分层与配置合同
设计/实施三层结构时读取。三案例(magpie-optimizer、slides、self-evolve)的收敛模式如下。
三层模型
| 层 | 内容 | 版本控制 | 说明 |
|---|---|---|---|
| 通用层 | 机制、脚本、参考文档、schema | 入库 | 只写可复用逻辑,不写「谁在用、用了多少」 |
| 示例层 | *.example.* 配置、占位数据 |
入库 | 与 schema 成对维护;值必须是明显占位 |
| 私有层 | 本机配置、运行产物、个人素材 | 不入库 | config/*.local.*、state/、assets/local/ 等约定位置 |
判据一句话:能定位到具体的人、账号、机器或未公开工作内容的,都算私有层候选;不确定按私有处理。
两种私有层摆放
| 摆放 | 适用 | 代价 |
|---|---|---|
Skill 目录内(config/*.local.* + state/) |
配置与脚本路径强耦合、需要自包含安装 | 必须(ignore + 发布包排除)双通道防护 |
用户数据目录(如 ~/.config/<skill>/) |
个人身份/素材跨项目复用、升级不应覆盖 | 需要配置解析顺序与初始化脚本 |
slides 的实践:两者结合——五级解析顺序(显式参数 → 项目目录 → Skill 目录本地 → 用户数据目录 → 匿名缺省),相对路径按被选中的配置文件所在目录解析(不按 cwd),坏配置 fail-closed 报错不静默回退,初始化脚本拒绝覆盖已有配置。
配置合同要素
- schema + 空示例成对:schema 定义格式,example 给出占位样例;两者必须同步修改,发布门禁检查成对一致性。
- schema ID 区分用途:描述性/设计态与可执行输入态用不同 ID,防止设计模板被直接喂给执行器。
- 校验器不回显值:只报字段是否已填/路径是否可读,不打印资料内容。
- 示例值占位化:用
example/provider-a、account-1、<port>这类明显占位,不写真实模型 ID、账号或地址。 - 新增私有文件零维护:私有配置名用通配忽略(
*.local.*),避免每加一个文件补一条规则;文档描述必须与实际规则一致。 - 敏感文件最小权限:含配置、状态、回执的文件创建时即以
0600落盘(语言 API 或 umask 均可);已有宽松文件在公开化整理中按目标平台兼容性收紧。
ignore 与跟踪的三个事实
.gitignore只影响未跟踪文件;已跟踪文件加 ignore 不会退出版本控制。- 已跟踪的本地配置要先另存副本(或确认外部已有),再
git rm --cached逐项退出跟踪;本地文件保留。 - 发布打包不能只依赖 Git 跟踪状态——旧分支可能仍跟踪本地文件,打包器按路径硬排除并登记 excluded 清单(self-evolve 教训)。
验证要求
- 真实候选验证:先按 Git 索引或固定 OID 导出实际交付文件,在导出树重跑所有检查;必须核 schema/example、脚本和引用都在树内,不能以工作区存在替代入库。
- ignore 正反例:新建未知命名的
*.local.*文件与state/证据文件→不被跟踪;*.example.*与 schema→仍可跟踪(临时 Git 仓库须复现目标仓库根与路径上各级 ignore,包括全局忽略;独立安装再检查随 Skill 提供的规则)。 - 打包排除:发布包文件清单不含私有层;excluded 清单包含预期排除项。
- 配置链路:example 复制为 local 后能被解析;坏 JSON 报错不回退;校验器输出不含资料值。