ADR-0027 自定义技能改为"推送 + 审核",去掉技能源与上传 zip
- 状态:Accepted · 日期:2026-11-03 · 部分取代 ADR-0022 之外的自定义技能导入方式(12-custom-skills §3.2、FR-1) · 设计见 18-skill-registry
背景
技能通常由其他项目生成或维护。服务以专用账号运行并启用 ProtectHome,读不到 /home,目录技能源只能靠手动拷贝;上传 zip 要登录后台手工操作,无法接入项目流程,也看不出来源。放开 /home 会让服务(和宽松模式下的 Agent)读到用户目录中所有可读的文件,不可取。
决策
- 推送:项目用发布密钥(
sk_pub_…)调用 /skills/registry/v1/submissions 上传技能包,可附提交说明与来源信息,支持试运行。服务器不需要访问项目所在的位置。
- 审核后才生效:推送只产生待审核的提交项,内容存入文件库且不可修改。管理员选择批准为新技能(可以改名,SKILL.md 的 name 随之改写)、覆盖已有技能(显示与目标最新版本的差异,二次确认,按审核时看到的版本号校验),或拒绝(填写原因,推送方可见)。已处理的记录可以删除,技能版本中保留提交说明的副本。
- 不设发布者:密钥名称即来源;不限定技能名,新建还是覆盖由管理员在审核时决定。
- 只保留后台编写:删除目录技能源、上传 zip 与"导入的技能只读";已有技能全部可编辑。
后果
- 发布密钥只能产生待审核的提交,泄露的影响有限,按 CI 加密变量 / 用户目录配置保管即可,不需要更复杂的密钥系统。
- 推送来的技能批准后可以在后台修改;下次推送覆盖时,差异中会显示这些修改将被覆盖,由管理员决定。
- 同一密钥再推送同名技能会替代之前待审核的那一份,管理员只审核最新的内容。
- 客户端推送工具、浏览器登录签发密钥、审核通知留到二期。