Cindy 插件捆绑 Skill(§4.16):存量兼容机制、SKILL.md 硬规则与迁移映射详解

原创2026-10-25 14:58:591,729 阅读
文章标签:人工智能AI Agent代码智能体大模型AI 技能Agent 记忆工具调用MCP Clients多智能体浏览器控制GUI 自动化本地部署插件系统桌面应用移动开发前端跨平台语音任务调度交互助手

Cindy 插件捆绑 Skill(§4.16):存量兼容机制、SKILL.md 硬规则与迁移映射详解

本文基于 Cindy 官方插件创作技能随包的 §4.16 参考文档,完整解析插件随包 Agent Skills(skill 能力)这一「停止新增、计划废弃」的存量兼容形态:目录结构、SKILL.md 双侧强制校验规则、<插件id>--<技能名> 链接投影机制,以及向 manual / tools / 系统提示词花名册的职责迁移映射,并逐一对照仓库源码给出可验证的实现依据。读完后你可以维护或迁移带 skill 槽的旧版 Cindy 插件,并明确新插件应当如何承接技能指令。

一、当前定位:停止新增,新插件不要声明 skill 字段

§4.16 开宗明义给出插件随包 Skill 的生命周期结论:当前已停止新增,未来计划全部废弃。因此两条红线必须遵守:

  • 新插件不要声明 skill 字段,也不要新增 skill.items;
  • 迁移时按职责映射,不是按篇幅搬运——即不能把 SKILL.md 的正文整段复制到新载体,而要逐段判断每段信息在新模型中该由谁承接。

这一点在随包创作技能 cindy-plugin-creator 的 SKILL.md 中也有呼应:该技能的参考索引将本文档标注为「旧插件捆绑 Skill 的维护与迁移(§4.16)」,并明确「Read bundled Skills only when maintaining an older plugin」——只在维护旧插件时才需要读它;新插件一律走 schemaVersion: 3 清单。

二、职责迁移映射:技能指令的去向

§4.16 给出了一份按职责拆分的迁移映射表,这是维护与迁移存量包时最重要的操作指南。原文档四条规则完整继承如下:

  1. 身份与召回层:Skill frontmatter 的 name + description 承担的是「身份/召回」作用,对标系统提示词区插件花名册的身份与 recall;插件侧改用 name + whenToUse 提供这层信息。也就是说,「这个插件是什么、什么时候用」不再靠 SKILL.md 的 frontmatter,而由花名册与 manifest 字段直接表达。
  2. manual.items 不是 Skill frontmatter 的对标物:它只是插件容器级的一级目录(渐进披露手册索引),不要把它当成 frontmatter 的替代品来填。
  3. 正文与工作流:MANUAL.md 与深层 Markdown 承接 Skill 正文、references、复杂工作流与深入用法。这类内容只经 ghost_manual tool-result 按需进入上下文,不进入生产 system/developer prompt——这是新旧模型在上下文成本上的本质区别:技能正文从「常驻」变为「按需拉取」。
  4. 契约下沉分层:
    • 单工具的局部契约 → 下沉到该工具/参数的 description;
    • 当前类别内贴近实时工具集合的动态规则与参数 → 下沉到 list_tools(category) 的工具说明和 result.rules;
    • 跨工具/跨类别的编排与长期稳定原则 → 进入 Manual。
    • Manual 与 list_tools 用完整调用互相指路,不复制同一段规则,避免两处漂移。

三、存量包的目录形态

以下结构只描述存量包的兼容形态,用于维护与迁移,不要照抄到新插件。每条 skill.items 对应一个目录,目录内必须有 SKILL.md:

my-ghost/
  ghost.json
  main.js
  skills/
    my-skill/
      SKILL.md        ← frontmatter 必须有 name + description
      reference.md    ← 可选:技能附带的其它文件一并随链接可见

清单侧的声明形态(见 plugin-manifest.md 参考 的 skill 详单节选):

{
  "slots": ["tool", "skill"],
  "skill": {
    "items": [
      {
        "dir": "skills/my-skill",
        "name": "my-skill",
        "description": "……"
      }
    ]
  }
}

源码对这一声明的强制约束定义在 manifest.ts:

约束项 常量 / 规则 值
技能条目数上限 GHOST_SKILL_MAX_ITEMS 4 条
SKILL.md 单文件上限 GHOST_SKILL_MD_MAX_BYTES 64 × 1024 字节(64KB),打包与装入两侧共用
name 长度上限 GHOST_SKILL_NAME_MAX_CHARS 64 字符
name 形状 GHOST_SKILL_NAME_RE /^[a-z0-9]+(?:-[a-z0-9]+)*/,小写字母/数字加单连字符分段,禁首尾与连续连字符
description 清单校验规则 1–1024 字符非空字符串

name 形状之所以比 SkillHub 的技能名规则更严,源码注释给出了理由:意识 id(ghostId)允许含 --,而插件私有技能根的链接名是 <id>--<name>,只有 name 侧禁 --,按「最后一个 --」拆分才唯一,不同插件才不可能撞出同一个链接名(见 manifest.ts)。

清单解析阶段(manifest.ts)还会额外强制:

  • 声明了 skill 详单但 slots 未包含 "skill" 直接拒装——「有槽必有详单」;
  • skill.items 必须是非空数组,每项必须是 { dir, name, description } 对象;
  • dir 必须是包内安全相对路径(如 skills/foo);
  • name 按小写折叠去重,重复即拒。

四、SKILL.md 硬规则:打包与装入双侧强制,任一不满足直接拒

§4.16 列出的 SKILL.md 硬规则在源码中有精确落点,且打包侧与装入侧共用同一个一致性裁判,避免「Forge 能打包、安装被拒」的契约漂移:

  1. frontmatter 的 name / description 必须与 skill.items 声明逐字一致。理由写在文档和代码注释里是同一句话:插件详情展示的是清单声明,Agent 读到的是 SKILL.md,两者必须是同一份事实。裁判函数是 checkSkillMdConsistency:先解析 frontmatter(YAML 语法错误即报「frontmatter 无法解析」),再逐字比较 name 与 description,不一致返回中文错误原因供作者自纠。
  2. name 形状:小写字母/数字加单连字符分段,≤64 字符(规则见第三节表格)。
  3. 单文件 ≤64KB、items 最多 4 条。

打包侧的执行位于 forge.ts 的 ghost_forge_pack 校验流程:

  • 清单声明的 ${item.dir}/SKILL.md 被列入 mustExist,缺失报 ENTRY_MISSING(用 lstat 而非 stat,符号链接不放行);
  • 读取时用 readBoundedFileNoFollow 加单句柄限量闸,在 64KB 上限「在读之前拒」;
  • 随后调用与装入侧相同的 checkSkillMdConsistency,不一致返回 MANIFEST_INVALID。

装入与运行期的对账逻辑集中在 skillSlot.ts,其文件头注释概括了整套机制:所有 harness 消费 agent-skills/skills,Claude 基于这些来源构建过滤后的每会话插件;不再创建新的用户全局链接;旧的用户全局链接只在其目标被证实归 Cindy 所有时才移除;源字节必须是「回执绑定的已批准快照」,而不是可变的插件安装目录。

五、链接投影机制:账号隔离目录、命名规则与三个 Agent 宿主

§4.16 描述的运行行为——「存量插件装入且启用后,主机把每个技能目录投影到 Cindy 的账号隔离目录,分别接入 Claude Code、Codex、Pi,不写入用户的全局技能目录;停用/卸载即撤销这些入口」——在源码中的对应实现:

5.1 私有技能根

ghostSkillPluginRoot 把插件技能根定位在批准状态根下:<approvalStateRoot>/agent-skills,实际链接落在其 skills 子目录。这个根是 owner(账号)作用域的,天然实现账号隔离——与用户手维护的 ~/.claude/skills、~/.codex/skills、~/.agents/skills(见 shared-global-skills.ts)完全分家。

5.2 链接命名:<插件id>--<技能name> 与企业 namespace 形态

ghostSkillLinkName 直接拼成 ${ghostId}--${skillName}。插件存储身份(storage part)的生成规则在 pluginIdentity.ts:

  • root 与存量未标记 namespace 的实例:沿用旧链接名,即 <ghostId>--<skillName>;
  • 已知企业 namespace 的实例:_ns__<namespace>__<插件id>--<技能name>。

注释说明双下划线是无歧义的,因为 namespace 与 ghostId 都不含 _。这也解释了为什么 name 侧必须禁 --:按「最后一个 --」拆分后,左半段完整还原插件存储身份,右半段是纯技能名。

顺带一提:namespace 是平台侧身份,作者无法自行声明——namespace.ts 中 AUTHOR_DECLARED_NAMESPACE_REASON 写明「ghost.json 不允许作者声明 namespace」,parseOptionalNamespace 明确「缺失是旧协议,绝不隐式视为 root namespace」,即 namespace 为 null 与缺失语义不同。

5.3 对账:期望态 vs 实际态

reconcileGhostSkillLinks 实现幂等、best-effort 的链接对账,核心分四步:

  1. 算期望态:筛选「enabled 且 approval.state === 'approved' 且有 approvedSkillRoot 且带 skill 槽」的插件,按 id+name 排序,为每条 item 生成 <linkName → 批准快照目标> 映射;挂链前先用 validateApprovedSkillSnapshot 重算批准快照的完整内容摘要,字节不可信则撤链并等待修复;
  2. 扫实际态:只认 symlink/junction 条目,真实目录绝不进入任何处理分支(保证不覆盖用户自建条目);活链接按 realpath 归属判断是否当前 owner 受管;
  3. 断链回收:断链是否属于 Cindy 托管由 targetLooksGhostManaged 裁决——链接名必须完整符合 <合法 ghostId>--<合法技能名>,且目标路径必须命中自己铺过的两种布局之一(旧模型 .../cindy-brain/<ghostId>/... 或新模型 .../<状态根名>/skill-snapshots/<ghostId>/<revision>/...),且布局里的 id 段与链接名一致。两条同时满足才动手,「外来链接绝不动」;
  4. 先撤后建:先删除失配链接再创建新链接,防「改目标」落进冲突分支;创建前再次检查 SKILL.md 在场且通过一致性裁判,失败者 skipped + warning,等下一轮自愈。

5.4 停用/卸载与账号边界的撤链

  • 单实例停用或卸载:对账时该插件不再进入期望态,对应链接被回收;
  • 账号边界(换账号/登出):removeGhostSkillLinksForRoots 会横扫所有 owner 根在全局技能目录中遗留的 Cindy 托管链接——这正是「不写入用户全局技能目录」的历史补偿动作:旧版本曾在用户全局目录铺过链接,现在只回收、不再创建。它对外来链接的失败保持 warning,但对「无法检查目录/无法移除已识别投影」记为 blocker,边界未清理完不切换 owner。

六、信任面与作用域:如实告知用户

§4.16 的「信任与作用域」一节定义了 skill 槽在插件能力体系中最高的一档信任面,维护旧插件时必须向用户如实说明:

  • 技能指令由主 Agent 以用户全部权限执行,对所有项目、所有会话生效,不受插件沙箱约束——这是插件能力里信任面最高的一档,因此插件详情会把每个技能置顶逐条列出(与清单侧「有槽必有详单,不允许隐瞒」的设计一致);
  • 作用域只有全局:技能跟随插件的全局启用状态,仅在某个工作目录停用插件不会隐藏技能,只有全局停用或卸载才撤链;
  • skill.items 的字段不参与 locales 本地化——因为它必须与 SKILL.md 逐字一致,而 SKILL.md 只有一份。

文档还给出两条行为规范:这些入口仅供 Cindy 管理的 Agent 会话使用,不会自动暴露给外部 CLI,无需为旧的全局目录发现方式添加环境守卫;技能如依赖插件工具,仍应在技能中说明实际依赖,调用时工具不可用就报告缺失,不得据此假定已获得其它能力或权限。

七、维护与迁移检查清单

把以上机制收敛成一份可操作的清单:

  1. 判断插件版本:新插件一律 schemaVersion: 3,不声明 skill 槽;只有维护存量包时才进入 skill 流程。
  2. 修 manifest 时:slots 含 skill 就必须有非空 items(≤4 条);dir 为包内安全相对路径;name 满足 /^[a-z0-9]+(?:-[a-z0-9]+)*/ 且 ≤64 字符;description 1–1024 字符。
  3. 修 SKILL.md 时:frontmatter 的 name/description 与 skill.items 逐字一致;正文连同辅助文件整体不得超过 64KB(SKILL.md 单文件上限);YAML frontmatter 必须可解析。
  4. 验证入口:打包走 ghost_forge_pack(forge.ts 的 3/3.5 步校验会先于安装拦截全部硬规则);行为回归可参考 skillSlot.test.ts 中对账与撤链的测试用例。
  5. 迁移动作:按第二节映射表逐段搬运——身份/召回进 name + whenToUse,正文与工作流进 MANUAL.md 及深层 Markdown(按需经 ghost_manual 进入上下文),单工具契约进工具 description,动态类别规则进 list_tools(category) 的说明与 result.rules,跨工具编排与长期原则进 Manual,且 Manual 与 list_tools 互相指路不复制规则。

存量 skill 槽的全部行为都由主机强制而非作者自律:清单解析(manifest.ts)、打包校验(forge.ts)、运行期对账(skillSlot.ts)三层共用同一套常量与裁判函数。对仍在维护旧插件的开发者,理解这条校验链就能准确预判每一次拒装、撤链或 warning 的来源;对新插件作者,本文最重要的结论是——不要再写 skill.items,把同样的信息放进正确的承载层。

登录后查看全文
cindy