Index of every page on this site: llms.txt
All skills
cat-xierluo avatar

/magpie-optimizer

@5fb69a0
Run it yourself

用 Magpie 配置并优化 AI 工作效能:接入供应商、订阅与插件,配置模型路由组与意图规则,管理网关、可见性、共享 MCP 与搜索;盘点额度与套餐,诊断 Token 消耗与限流,把每次调整关联真实任务验收效果。

Use this Skill: https://skilld.dev/gh/cat-xierluo/legal-skills/magpie-optimizer

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesprivacy.md

≈4.4k tokens on demand. Your agent reads this file only when SKILL.md points to it.

隐私与公开边界

本文解决什么问题 / 何时读:界定哪些内容算私密、magpie-optimizer 怎样处理它们,以及在把这个 Skill 公开发布前要检查什么;使用者评估输出能否外发、维护者准备发布时阅读。

本文中的脚本与路径以 Skill 安装目录 <skill-dir>/ 为基准:命令在该目录下执行,本机私有层位于同一目录内的 config/*.local.json 与 state/,不入库。

本文只定义边界与检查方法,不改变任何 CLI 语义或路由规则。路由语义与实测坑以路由治理为权威,本文不重复其内容。

1. 什么算私密

判定标准一句话:能定位到具体的人、账号、机器或未公开工作内容的,都算私密;不确定时按私密处理。

类别 例子 为什么敏感 允许的替代写法
账号身份与登录态 登录邮箱、账号别名、登录态 cookie、账号绑定手机号 直接指向自然人和其可用额度 account-1、account-2;"共 2 个账号"
额度与用量数值 剩余 token、套餐余量百分比、积分余额、429 次数、单价 反映个人消费结构与业务规模 量级档位("接近上限")、相对变化("周环比下降")、桶标签(quota-bucket-2)
API key / token / cookie provider key、访问 token、会话 cookie、签名串 泄露即等于账号被盗用 "已配置/未配置";key-<ref> 形式的引用标签
代理与网络出口地址 网关地址、代理主机、出口 IP、监听端口 暴露内网结构与本机拓扑 <gateway-url>、<port>、"本机回环"
本机绝对路径 用户主目录、挂载卷、worktree 绝对路径 暴露用户名与目录习惯 <skill-dir>/...、config/<name>.local.json、state/<name>.json 形式的泛写
提示词与对话正文 system prompt、用户提问、完整回复、附件内容 可能含未公开事实、第三方材料、个人陈述 字段结构、token 量、意图标签("检索类提问")
会话标题与任务摘要 会话名、任务标题、摘要、文件名 常直接写明案件名、客户名或项目代号 稳定会话 ID、任务类型("合同起草")
任务产物 交付文件、验收记录、导出报告、截图 产物本身可能是付费或保密交付物 路径占位 + SHA-256 摘要 + 字节数
签名与认证信息 签名块、认证头、机器指纹、设备 ID 可用于识别与冒用 "已签名"、"认证状态正常"

补充判定:

  • 派生值同样算私密。总用量、分组命中数、账号级并发与队列设置,虽然不是直接凭证,但足以反推个人工作规模与资源安排,公开时按额度类处理。
  • 只读不等于可公开。能读到某字段不代表该字段适合出现在报告里;magpie quota --json 的 raw 含账号,只在进程内使用(见CLI 与变更边界)。
  • 示例值必须是明显占位。本 Skill 公开文档统一用 example/model-strong、example/provider-a 这类写法;config/policy.example.json 里的 example/strong、example/efficient 同样是占位;config/inventory.example.json 里的 example-agent-a、group/example-main 与各处计数也是占位。两者都不会被误认为真实 provider 或模型。
  • 个人身份与发布署名分开。用户账号和业务联系人不进公开文件;项目已明确公开的 frontmatter 作者和 LICENSE 版权署名按项目发布配置保留。

2. 本 Skill 的处理原则

以下七条是输出与写操作的硬约束。诊断、盘点、发布检查三类动作都按同一套执行。

1. 白名单输出

  • 原则:只输出明确允许的字段;未在白名单的一律不输出。
  • 落地方式:采集与诊断脚本内置字段白名单,默认只回传聚合数值与脱敏标识(组 ID、模型 ID、日期、桶标签)。新增输出字段必须先改白名单,不能靠调用方过滤。白名单外的原始数据即使在内存中可用,也不得拼进报告、异常信息或日志。

2. 只读优先

  • 原则:诊断与盘点默认不写配置、不登录、不消耗额度。
  • 落地方式:观测、预检、盘点走只读接口(scripts/magpie_preflight.py、scripts/magpie_inventory.py),输出落在私有层。写网关配置的 plan/apply 属于另一类动作,需按操作入口的显式授权执行,不由诊断流程隐含触发。

3. 脱敏

  • 原则:账号以脱敏标签出现;key 不出现在任何输出里。
  • 落地方式:账号按 provider 在本次扫描内编号为 account-<n>,映射仅在内存;邮箱域名、账号别名及上游半遮罩均不回显。组与模型保留可读的稳定 ID,因此盘点整体仍是私有状态,不是可直接公开的报告。key、token、cookie 只在进程内做比较与 allowlist 投影,脚本、日志、报告、回执、异常栈中都不出现原文,也不出现可逆编码或片段。

4. 最小必要

  • 原则:只读取完成任务所需的字段与文件。
  • 落地方式:为当前结论只取必需字段,不做"顺手全量导出"。会话内容按需逐个读取,不批量拉取全部会话正文。读取范围与任务绑定:换任务重新评估,不把上一次的读取范围当成默认。

5. 凭证不落盘

  • 原则:凭证只交给 Magpie。
  • 落地方式:认证由已安装的 Magpie 使用,Skill 不接收、不缓存、不转发、不写示例凭证。环境隔离测试用临时 HOME/XDG 目录,且不复制真实认证(见验证与证据边界)。写操作前保存目标配置快照时,剔除 provider key。

6. 证据留在本地

  • 原则:观察、日志、快照、回执存在私有层,不进版本库。
  • 落地方式:全部落在 state/ 与 config/*.local.*,文件权限 0600。入库只保留 *.example.* 与 schema。证据文件绑定 SHA-256,源码或配置变化后重新生成,不复用旧证据。

7. 不扩散

  • 原则:报告里不复制用户材料原文。
  • 落地方式:结论用自己的表述,不整段搬运提示词、对话、附件或产物正文。确需引用时只取最小片段并脱敏。引用第三方材料时只标注来源类型与出处位置,不复制全文。

3. 本机私有层约定

目录布局

私有层放在 Skill 目录内,与公开层同一个目录树,靠 ignore 分离:

<skill-dir>/
  config/
    .gitignore                # 排除私有层(随公开层入库)
    policy.example.json       # 公开层:策略模板
    route-policy.example.json # 公开层:路由策略模板
    profile.example.json      # 公开层:本机画像示例
    profile.schema.json       # 公开层:画像 schema 定义
    inventory.example.json    # 公开层:盘点输出格式示例
    inventory.schema.json     # 公开层:盘点 schema 定义
    integration.example.json  # 公开层:接入与账号示例
    integration.schema.json   # 公开层:接入 schema 定义
    policy.schema.json        # 公开层:可执行 policy schema
    route-policy.schema.json  # 公开层:路由设计 schema
    *.local.*                 # 私有层:不入库
  state/                      # 私有层:观察、清单、回执、快照
  references/                 # 公开层
  scripts/                    # 公开层
  TASKS.md                    # 维护者本地:原始任务台账,不入库
  DECISIONS.md                # 维护者本地:原始决策记录,不入库
  • 私有层:config/*.local.* 与 state/。
  • 排除方式:config/.gitignore 用 *.local.* 通配排除本地配置;state/.gitignore 排除该目录下全部运行证据。仓库根忽略规则还可能影响 schema 等公开文件;核对实际 Git 决策,不能替代 Skill 内规则。
  • 维护记录:原始 TASKS.md、DECISIONS.md 留在 Skill 根目录,由 skills/magpie-optimizer/.gitignore 排除;公开导出不包含这两份文件,也不另放摘要副本。
  • 公开层:只有 *.example.* 与 schema 定义;示例里只放 example/... 形态的占位模型与组。
  • config/ 目录内的 .gitignore 本身属于公开层:它声明「哪些文件不进公开仓库」,这条信息本身就是公开信息,因此随 Skill 一起入库。
  • config/.gitignore 用通配排除全部 *.local.* 私有配置,另覆盖日志、运行态与密钥类后缀;新增私有配置名无需逐名补规则,新增公开配置仍必须是 example/schema。

表格:文件类别归属

文件类别 是否入库 命名约定 内容
策略模板 入库 config/policy.example.json schema 声明 + example/... 占位成员与规则
路由策略模板 入库 config/route-policy.example.json 组、成员顺序、路由模式、规则条件与目标的占位模板
本机画像示例 入库 config/profile.example.json 网关入口、能力层角色、约束与账号优先级的占位示例
画像 schema 入库 config/profile.schema.json magpie-profile.v1 的 JSON Schema 定义
盘点输出示例 入库 config/inventory.example.json magpie-inventory.v1 的脱敏输出格式示例;标识与计数均为占位
接入与账号示例 入库 config/integration.example.json provider、脱敏账号标签、额度窗口与插件的占位示例
ignore 规则 入库 config/.gitignore 排除私有层文件,以及日志、快照、回执与密钥类后缀
本地配置 不入库 config/<name>.local.json 指向具体账号、组、模型的实际策略
任务台账 不入库 TASKS.md 维护者的原始任务、证据与未验证边界
决策记录 不入库 DECISIONS.md 维护者的原始取舍、理由与重新评估条件
观测数据 不入库 state/observation-<date>.json 覆盖状态、聚合用量、脱敏会话标识
清单与盘点 不入库 state/inventory-<date>.json 组、规则、可见性、已启用成员的只读快照
计划与回执 不入库 state/plan-<date>.json、state/receipt-<date>.json 变更前态、哈希、执行结果
产物索引 不入库 state/artifact-index.json 产物路径占位、SHA-256、验收绑定
公开文档 入库 references/<topic>.md、SKILL.md 通用方法、术语、无个人数据
脚本 入库 scripts/*.py 只依赖标准库,不含凭证与真实 ID

config/ 目录的 10 份 example/schema 文件(5 对)构成公开配置层的全部内容;它们之间的分工是:schema 定义格式,example 文件给出符合该格式的占位样例,两者必须成对维护——改 schema 不改 example,或只改 example 不改 schema,发布前检查都会失败。配置样例说明各例子的用途、是否需要复制,以及推荐的起步顺序;inventory 是输出格式参考,通常不复制。

为什么放在 Skill 目录内

  • 自包含:私有层放在 Skill 目录内(config/*.local.json 与 state/),由 config/.gitignore 排除。Skill 单独安装到任意路径后,配置、状态与脚本的位置关系不变,命令里的相对路径仍然成立,不需要使用者额外维护一个仓库外目录约定。
  • 同处一树、靠 ignore 分离:私有层与公开层物理相邻,可见性由版本控制规则而不是由人记住"哪些文件不能提交"来决定。误提交时 ignore 规则先挡一道,发布前检查再挡一道。
  • 可迁移:换机或换 worktree 时整棵复制即可,私有层与公开层的对应关系不丢。

4. 发布前检查清单

scripts/public_release_check.py 检查什么

这是发布前的自动闸门,只读扫描待发布目录树,不联网、不写文件、不调用 Magpie 写操作:

  1. 敏感内容扫描:检测已实现的凭证、完整邮箱及部分家目录路径模式;个人统计、账号别名、provider 偏好、手机号与网络拓扑仍须语义审阅,脚本通过不证明无泄露。
  2. 结构可解析:检查 example/schema 的 JSON 语法;另运行 validate_examples.py 检查配对、schema 支持范围和实例字段约束。
  3. 文档完整性:Markdown 相对链接可达,引用的脚本与参考文件存在。
  4. 版本一致性:SKILL.md 版本号、CHANGELOG 最新条目、公开文档中的版本声明三者一致。
  5. 私有文件清单:拒绝进入清单的 config/*.local.*、运行 state 与根目录维护记录。ignore 规则正反例须用真实 Git 单独核对,且公开 schema/example 都须在导出树中。
  6. 退出码:发现任一问题即非零退出,输出问题清单与所在文件位置;发布流程以退出码为准,不以人眼扫读为准。

脚本之外的扫描只作补充,不替代它。发布顺序:先跑脚本,再看清单,再做历史检查(见第 5 节)。

检查清单

检查项 通过标准 失败时先查什么
凭证关键字 公开树中无 api_key、sk-、Bearer、token= 等形态 报错文件里的示例配置、脚本内嵌默认凭证、异常信息里的 header 片段
邮箱与手机号形态 无邮箱地址、无连续手机号/座机号形态 示例文件里的"作者联系"、"联系邮箱"字段;CHANGELOG 的贡献者署名
本机绝对路径 无用户家目录、挂载卷、worktree 等绝对路径 报错信息、示例命令、文档中的输出样例;改为 <skill-dir>/...
真实账号与额度 无真实账号名、账号别名、额度与余额数值 观测与诊断样例、效果比较表;改为 account-<n> 与量级档位
真实代理地址 无真实网关地址、代理主机、出口 IP、端口号 采集参数、CLI 帮助引用、示例命令;改为 <gateway-url>、<port>
example 文件可解析 *.example.* 可被 JSON 解析,schema 字段齐全 文件末尾多余逗号、注释残留、占位值类型不符
schema 可加载 schema 标识与声明版本一致,示例符合 schema 示例的 schema 字段、字段名与 操作入口 的合同
Markdown 相对链接可达 文档内相对链接指向的文件都存在 被引用文件是否改名或移出 references/;未实现的新文件先补齐或暂不引用
版本号与 CHANGELOG 一致 SKILL.md 版本号等于 CHANGELOG 最新条目版本 CHANGELOG 是否漏写本次发布;版本号是否只改了一处
ignore 覆盖私有层 私有层模式被 ignore 覆盖,且私有层文件未出现在待发布集合 config/.gitignore 规则写法、根 .gitignore 是否有相反的例外规则
脚本测试通过 离线测试全绿(--real-cli 需在隔离环境单独确认) 最近一次改动涉及的脚本;测试是否依赖真实环境或网络

5. 重要提醒:.gitignore 不会清除历史

.gitignore 只影响未跟踪的文件。 已经被提交过的敏感内容,即使后来加上 ignore 规则,仍然完整留在 Git 历史里。ignore 规则挡得住"下一次提交",挡不住"已经发生过的提交"。给私有仓库补一条 ignore 规则,不等于这处敏感内容已经被移除。

因此,从私有仓库转公开时,必须使用清洁历史:

  • 可以:新建一个公开仓库,把待发布内容以单一初始提交重新导出,再推送到公开仓库。
  • 不可以:把现有私有仓库的 remote 改成公开地址后直接推送。那会把整段私有历史一起公开,其中包含已被 ignore 的旧版本文件。
  • 不可以:先删除文件、再靠 ignore"遮住"删除痕迹。工作树里看不到,不代表历史里不存在。

转公开的检查顺序

  1. 跑发布检查:python3 scripts/public_release_check.py,确认当前工作树无敏感内容。
  2. 确认 tracked 文件集合:核对将被导出的文件清单,确保其中只有公开层(*.example.*、schema、文档、脚本),不含 config/*.local.*、state/ 内证据、TASKS.md 与 DECISIONS.md(允许 state/.gitignore);同时确认待发布内容里没有指向私有层文件、维护记录或摘要副本的残留引用。
  3. 导出清洁树:从干净工作树导出待发布内容,只带公开层文件。
  4. 新建公开仓库:在公开平台创建空仓库,不要从私有仓库继承历史。
  5. 再发布:以单一初始提交推入,然后重复第 1 步的发布检查确认公开树内容一致。

第 1 步检查的是当前文件内容,第 2 步检查的是将要导出的文件集合,两步都不能替代历史检查:即使当前文件全部干净,只要导出方式复用了旧历史,敏感内容依然会被公开。

如果确实要从旧历史里彻底移除某段内容

正确做法是重写历史并强制推送(过滤掉特定路径或特定提交)。

这是一次破坏性操作:它会改写提交哈希,改动他人可能已经克隆、引用或依赖的分支与标签。必须由用户明确决定并授权,不能作为发布流程的默认步骤,也不能由 Skill 自动执行。

在用户做出明确决定之前,默认路径始终是第 5 节前半段的清洁历史方案:新建仓库、单一初始提交导出。它不触碰旧历史,风险最低。

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts18d3 checks · Risk SAFE
  • Gen Agent Trust Hub18d

    This skill provides a robust and security-conscious framework for managing AI model routing and telemetry via the Magpie CLI. It includes extensive defensive measures such as local-loopback-only network enforcement, restricted file permissions (0600), comprehensive credential redaction logic, and a self-auditing suite to prevent secret leakage.

  • Socket18d

    No alerts

  • Snyk18d

    Risk: LOW · No issues

Signed by skilld at 5fb69a0. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated yesterday
Other metadata
metadata
{
  "version": "1.8.1",
  "author": "杨卫薪律师(微信ywxlaw)",
  "homepage": "https://github.com/cat-xierluo/legal-skills"
}

README badge

README badge for cat-xierluo/legal-skills/magpie-optimizer