隐私与公开边界
本文解决什么问题 / 何时读:界定哪些内容算私密、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 写操作:
- 敏感内容扫描:检测已实现的凭证、完整邮箱及部分家目录路径模式;个人统计、账号别名、provider 偏好、手机号与网络拓扑仍须语义审阅,脚本通过不证明无泄露。
- 结构可解析:检查 example/schema 的 JSON 语法;另运行
validate_examples.py检查配对、schema 支持范围和实例字段约束。 - 文档完整性:Markdown 相对链接可达,引用的脚本与参考文件存在。
- 版本一致性:SKILL.md 版本号、CHANGELOG 最新条目、公开文档中的版本声明三者一致。
- 私有文件清单:拒绝进入清单的
config/*.local.*、运行 state 与根目录维护记录。ignore 规则正反例须用真实 Git 单独核对,且公开 schema/example 都须在导出树中。 - 退出码:发现任一问题即非零退出,输出问题清单与所在文件位置;发布流程以退出码为准,不以人眼扫读为准。
脚本之外的扫描只作补充,不替代它。发布顺序:先跑脚本,再看清单,再做历史检查(见第 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"遮住"删除痕迹。工作树里看不到,不代表历史里不存在。
转公开的检查顺序
- 跑发布检查:
python3 scripts/public_release_check.py,确认当前工作树无敏感内容。 - 确认 tracked 文件集合:核对将被导出的文件清单,确保其中只有公开层(
*.example.*、schema、文档、脚本),不含config/*.local.*、state/内证据、TASKS.md与DECISIONS.md(允许state/.gitignore);同时确认待发布内容里没有指向私有层文件、维护记录或摘要副本的残留引用。 - 导出清洁树:从干净工作树导出待发布内容,只带公开层文件。
- 新建公开仓库:在公开平台创建空仓库,不要从私有仓库继承历史。
- 再发布:以单一初始提交推入,然后重复第 1 步的发布检查确认公开树内容一致。
第 1 步检查的是当前文件内容,第 2 步检查的是将要导出的文件集合,两步都不能替代历史检查:即使当前文件全部干净,只要导出方式复用了旧历史,敏感内容依然会被公开。
如果确实要从旧历史里彻底移除某段内容
正确做法是重写历史并强制推送(过滤掉特定路径或特定提交)。
这是一次破坏性操作:它会改写提交哈希,改动他人可能已经克隆、引用或依赖的分支与标签。必须由用户明确决定并授权,不能作为发布流程的默认步骤,也不能由 Skill 自动执行。
在用户做出明确决定之前,默认路径始终是第 5 节前半段的清洁历史方案:新建仓库、单一初始提交导出。它不触碰旧历史,风险最低。