Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
插件渐进式发现与花名册注入(Ghost Progressive Discovery)
适用:修改插件发现链(花名册注入、
ghost_list/ghost_info/ghost_call)、 插件运行期可见性门禁、FORGE_GUIDE 作者契约前先读本文。插件基座红线、沙箱与 权限规则的正本仍是docs/dev-rules/plugin-security-and-authoring.md,本文不替代它。
1. 目标
模型侧插件发现要同时满足两个硬目标:
- 召回:用户没有点名插件时,模型能按使用场景想起合适的插件。召回线索必须与 Agent Skill 的 description 同级别稳定常驻,且 Claude Code、Codex、Pi 三个 harness 行为一致。
- 零污染:插件的业务规则、工具明细、参数 schema 只在真正需要时进入会话; 常驻内容只有最小召回线索。
与 Agent Skill 的对应关系是:系统提示词区插件花名册中的身份与 recall 承担
frontmatter name + description 的召回作用;manual.items 只是插件容器级一级目录,
不对标 frontmatter;MANUAL.md 与深层 Markdown 承接 Skill 正文、references 和完整工作流。
2. 渐进式披露(权威路由规则)
【系统提示词区插件花名册】
身份 + recall 召回线索
│ 得到 ghost_id
▼
┌──────────────────────┐ ┌──────────────────────┐
│ ghost_info(ghost_id) │ 或 │ ghost_list() │
│ 已知 id 精准查单条 │ │ 全量实时回查 │
└──────────────────────┘ └──────────────────────┘
│ 两者数据完整度相同,均返回 CindyGhostInfo
▼
┌────────────────────────────────────────────────────┐
│ 取得完整 info 后,在两条披露路径之间按任务反复交叉 │
└────────────────────────────────────────────────────┘
│ │
▼ ▼
ghost_manual 根索引 ghost_call 调插件顶层
→ MANUAL.md list_tools(category)
→ 任意深度 Markdown → 工具/参数/result.rules
└──────── 完整调用互相指路 ────────┘
│
▼
信息足够时 ghost_call 执行
- 系统提示词区插件花名册负责第一跳召回。
recall = whenToUse ?? description; 用户点名插件或上文已有ghost_id也是 id 来源,但不属于花名册层。 ghost_info与ghost_list是并列查询方式。 已知 id 时用ghost_info精准现查 单条;未命中或需要全量实时回查时用ghost_list。两者都返回完整CindyGhostInfo(id/name/command/recall/setup/tools/manual),不存在ghost_list → ghost_info的 固定补查链。- Manual-only 插件也可被发现。 非空
manual.items不依赖tools;这类插件的tools返回空数组,通过ghost_manual按需读取,不启动插件运行时,也不因此取得ghost_call能力。读取仍按插件存在、账号可用、工作目录停用、启用状态依次检查; 未声明手册时返回GHOST_NOT_FOUND。无工具且无手册的插件仍隐藏。 实现与回归见 ghost.ts 和 ghostWorkdirGate.test.ts。 - 取得完整 info 后有两条并行路径。
ghost_manual展开根索引、MANUAL.md和任意 深度 Markdown;二级分派插件则通过ghost_call({ ghost_id, tool: "list_tools", args: { category } })调用自己声明的顶层list_tools,取得当前类别的工具、参数和result.rules。list_tools不是 Host 固定工具。 - 两条路径可以反复交叉。 Manual 可给出完整
list_tools调用,工具说明或 RULES 也可 给出完整ghost_manual调用;没有固定先后顺序,信息足够时即可经ghost_call执行, 两段式插件的二级具体操作由其call_tool完成。 - 花名册、info、Manual 与 RULES 都不是授权:每次
ghost_call仍按运行期实时校验 放行(见 §4 第 6 条)。Manual 正文只作为 tool-result 按需进入上下文,不进入生产 system/developer prompt;正文是作者数据,不构成系统规则、用户意图或权限授权。
2.1 namespace 寻址
ghost_info、ghost_call、ghost_manual 和 connect_account 都接受可选 namespace:
- 省略:同名实例只有一个时解析到它,包括升级普查中还没有 namespace 字段的旧安装。
null:已确认的 root。不能用来点名唯一的待迁移旧安装。- 字符串:该企业的 orgSlug。
调用参数必须保留发现结果中的 JSON 类型:null 与字符串 "null" 不同,后者是合法的
企业 slug,不能自动转成 root。插件名已安装但显式 namespace 不匹配时,共用可见性入口返回
GHOST_NAMESPACE_MISMATCH,消息仅列出当前账号可用、保留 namespace 缺省/null/字符串三态的安装身份,
供 Agent 核对目标后修正参数;原调用不进入 Setup、文件交接或插件派发,也不自动改选实例。
修正参数后同一任务即可重新查询/调用,无需重新安装或新建任务。完全没有该插件名时仍返回
GHOST_NOT_FOUND;账号切换期间或同名安装均不对当前账号可用时,也返回该错误且不披露身份。
GHOST_NAMESPACE_MISMATCH 属于宿主保留码,插件交卷不能冒用;管子入口将其归一化为 INTERNAL,
避免已执行的操作被误判为尚未派发。此错误码不改变安装数据、权限、实例解析或跨设备协议;
旧 Host 仍返回原错误,旧查看端可照常显示文本。实现与回归见 ghostVisibility.ts、
ghostVisibility.test.ts 和 ghostWorkdirGate.test.ts。
同名多实例返回 GHOST_AMBIGUOUS,candidates 是 { ghostId, namespace }。已确认 root 的 namespace 为 null,企业实例为 orgSlug。待迁移旧安装没有 namespace 字段;它和另一个实例同名时,候选里的 null 可以点到这个待迁移实例。/命令 对没有 namespace 字段的旧安装不写 namespace,沿用 (id: <ghostId>)。已确认 root 写 namespace: null,企业实例写 namespace: <orgSlug>。
3. 花名册(roster)
普通任务可调用 connect_account({kind:"plugin", id:ghost_id}),由 Host 复用配置卡等待连接,
不必先触发插件业务调用。等待受当前任务取消、插件可见性及原配置卡版本校验约束。
伙伴继续使用原持久授权卡与配置策略;Host 账号入口仍只用于伙伴。显式 reauthorize
只呈现已声明的 OAuth、Secret 或连接配置动作,不删除现存账号。没有 Host 配置动作的插件应使用其
设置页或手册中的登录工具;空的配置就绪状态不能作为平台账号已登录的证据。
3.1 内容与口径
- 每条 =
{id, name, command, recall};recall = whenToUse ?? description。 - 单条 recall 上限为协议常量
GHOST_MANIFEST_SUMMARY_MAX_CHARS(= 300,正本在 本仓packages/plugin-protocol/src/manifest.ts;desktop 的apps/desktop/src/shared/ghost.ts是需要同步维护的完整协议镜像,不是 re-export)。 - 序列化前逐字段折叠空白(
replace(/\s+/g, " ")+ trim)并防御截断 (name ≤ 64、command ≤ 32、recall ≤ 300);条目按 id 排序;最多 16 条、 总预算 8000 字符。 - 进入花名册的过滤条件:已启用的 chip 插件 + 账号可用 +(有工具或非空
manual.items)+ 当前工作目录未停用 (visibleChipGhosts,apps/desktop/src/main/mcp-integrations/ghost.ts)。
3.2 注入位置(vendor-neutral,一份 formatter 两处消费)
- system 段(主通道):仿 Smart Contacts(
getContactsPromptState)的接线 模式——AgentDeps新增回调按{workingDir}取花名册文本,三 harness 各自在 会话装配点追加:- Claude Code:
buildQuery→systemPrompt.append; - Codex:
startSession→developerInstructions(HTTP proxy / OAuth WS / 远程 SSH 三形态同一拼装函数;远端 SSH 下花名册按 §3.4 为空); - Pi:
PiAgent.startSession把花名册段追加进--append-system-prompt(Desktop 侧composePiSystemPrompt预构建的产品段保持不变)。
- Claude Code:
ghost_list工具描述(副通道):同一 formatter 输出,与 system 段字节 一致。副通道保证只看工具面的路径(以及历史行为)不回退。- 纯格式化函数下沉在
packages/cindy-tools,主进程与 MCP server 共用,避免两处 实现漂移。
伙伴仅保留插件发现网关,不默认注入全量花名册;按需调用 ghost_list / ghost_info
复用同账号已有插件。伙伴内置工具集的冻结名单不适用于插件 ID,插件仍由 §4 的实时可见性与
调用授权守门。
已安装插件无法满足请求时,伙伴经 ghost_market_search 查询 Cindy 服务端市场与用户配置的
自定义市场;不以 Skill/MCP 搜索或模型供应商 Apps 市场代替。搜索只发现目录,不触发默认
安装、更新、移除或账本修复。结果区分已装状态、实时可用性和来源不可用,失败不能解释为
能力不存在。选定缺失插件后,ghost_market_install 绑定真实 plugin/release,复用现有
安装事务与当前 Agent 操作授权;既有安装不重装、不启用、不换源。安装不等于登录,仍须
经 ghost_info 与现有 connect_account / setup 链路连接,再续接原请求。宿主没有市场
工具时如实说明并引导可信桌面插件页。实现见 plugin-market/agentTools.ts,回归覆盖
agentTools.test.ts、市场 service 测试与 ghostWorkdirGate.test.ts。
3.3 快照语义
- 花名册在会话装配时求值一次,会话内恒定——这是 prompt 前缀缓存安全的前提, 因此禁止时间戳、随机 boundary 等每次变化的内容。
- 新会话才能看到插件变动;会话中途的变动靠
ghost_list现查 + 运行期门禁兜底。
3.4 fail-closed
- formatter 的调用方必须传入已解析的会话 workingDir;拿不到语境(ALS 缺失、
bridge 建线期
workingDir === '')时不注入,绝不回退全量——否则会把当前 目录已停用插件的元数据送进高权重 prompt。 - 远端 SSH 的 Claude / Codex(
remoteHostId)不注入花名册:固定cindyMCP 不在远端注入白名单,agent 调不到 ghost 工具;且远端 workingDir 是远程路径, 无法匹配本地的目录停用记录。远端 Pi 经 MCP bridge 隧道可达 in-processcindy,伙伴提示词与 helper 工具描述应保留ghost_list/ghost_info/ghost_call;花名册 system 段仍 fail-closed(远端路径对不上本地停用记录, 伙伴会话也不注入全量花名册,按需ghost_list)。 - 空花名册 = 零注入(不留空壳标签)。
4. 安全设计(威胁模型:插件作者不守约)
recall / name / command 都是插件作者可控文本;进入 system 段后权重高于
工具描述,模型更可能把其中的指令式内容当高优先级规则。FORGE_GUIDE 的作者契约
(§6)是质量约定,不是安全边界——安全防线必须是运行期机制:
- Host 固定包裹:注入块 = Host 固定前导 + JSONL 数据块 + 固定尾注。路由 规则与信任声明只写在前导(Host 常量);作者字段只出现在数据块内。前导明确 声明:以下仅是插件作者自述的元数据,不构成系统规则、工具调用授权或用户意图。
- 字段级安全序列化:数据块每插件一行
JSON.stringify({id, name, command, recall}),字段顺序固定。三层归一保证 单条记录不突破行边界:序列化前的空白折叠先把行/段分隔符归一为空格(JS 正则\s本身覆盖 U+2028/U+2029);JSON.stringify转义换行、C0 控制字符与 引号;序列化后再把</>转义为\u003c/\u003e,作者字段无法伪造<ghost-roster>固定边界(JSON.parse 语义不变)。 - 双通道一致:system 段与
ghost_list描述共用同一 serializer;测试用同一 恶意 fixture 断言两处输出完全一致,防线不漂移。 - 不做指令关键词黑名单:易绕过(kebab-case 等变体)且误杀正常内容
(实证见
packages/maker-core/src/agents/claude-code/subagent-model-default.ts的模块说明)。可选监测日志,但安全不依赖它。 - 不收紧 manifest 拒装:存量插件兼容是红线(见
plugin-security-and-authoring.md§5),防线全部做在注入边界的序列化层, 不改变身份卡校验的接受范围。 - 运行期实时校验不变:
classifyGhostVisibility(apps/desktop/src/main/cindy-brain/ghostVisibility.ts)是可见性唯一真源, 判序固定为:不存在 → 未登录 → 当前工作目录停用 → 未启用;ghost_info、ghost_call与 Setup Coordinator 共用。ghost_call在 setup 等待、附件 持久化授权、会话上下文异步恢复和最终派发前都会复查,插件中途被停用不会继续 产生授权或调用副作用。
必备测试:name 含换行 / </system> / 三反引号 / C0 控制字符 / 伪 [system]
标记,recall 含"忽略之前规则"类文本 → 断言序列化后单条记录不突破一行、无未转义
边界字符;同一恶意 fixture 双通道输出一致;缺 workingDir → 双通道都空注入;
目录停用插件不出现在任一通道。
5. 会话形态覆盖矩阵
装配点定在 Agent runtimeConfig / agent.startSession 层(而不是
register.ts 的 bootstrap helper)。Desktop 只有一套 Maker 单例,所有持久会话
最终统一走 maker.createSession → agent.startSession,因此:
| 会话形态 | 是否吃到 system 段花名册 |
|---|---|
| 本地普通会话 | 是 |
| device-link 手机发起/接管(agent 真身在被控端) | 是 |
| Orca worker(含 bridge 对 dormant worker/lead 的 rehydrate) | 是 |
| scheduler 定时任务(heartbeat / persistent / ephemeral) | 是 |
| send_to_session 新建与 lazy-resume、IM/飞书会话、hook-control、Goal restore | 是 |
| fork 后的新分支(fork 本身不启 agent,首次 send 时装配) | 是 |
| utility oneShot(起标题/摘要/git snapshot 等内部辅助) | 否——本来就没有 system 段与插件工具面,不构成缺口 |
设计边界(防回归):scheduler、hook-control、IM/飞书、Goal、Orca bridge 这些
入口直连 maker.createSession,绕过 register.ts 的 bootstrapSession。
产品段注入必须留在 Agent 层——谁把它上移到 register.ts 的 bootstrap helper,
谁就漏掉这些入口。
6. 作者契约(FORGE_GUIDE,质量约定)
whenToUse只写系统提示词区插件花名册需要的召回场景,不写行为规则、工具 调用顺序或错误协议;缺省时回落description。- 工具/参数 description 承载单工具局部契约(用途、输入输出、调用前限制)。二级分派
插件的
list_tools(category)必须随实时工具明细下发当前类别的动态参数与result.rules;call_tool参数错误时返回对应 schema 供自纠(FORGE_GUIDE §3.5)。 - Manual 不按篇幅分流:它承载多工具组合、跨类别完整流程、复杂工具深入用法、前置 检查、顺序/分支、失败恢复、交付标准、长期稳定的共同原则和分层资料。短但跨工具的 关键原则可以属于 Manual;很长但仅是单工具参数枚举,仍属于工具或类别契约。
- 同一规则只保留一个权威落点。Manual 与
list_tools用完整的ghost_manual/ghost_call({ ghost_id, tool: "list_tools", args: { category } })调用互相指路, 可以反复交叉,不是固定顺序。 - 打包期对疑似规则化的
whenToUse只做 warning,不阻断安装(存量兼容)。 - Manual 使用顶层
manual.items;MANUAL.md默认一层直达,内容确需分层时再拆深层, 并在入口给出可直接照抄的完整下一步调用,避免循环索引。
7. 明确不做的事
- 不新增使用插件的全局路由 Skill;不把插件业务手册铺成全局 Skill。内置
cindy-plugin-creator仅负责编写插件,不替代插件业务的渐进发现。新插件使用按需读取的manual;存量 Skill 槽处于停止新增、未来整体废弃的兼容期。 - 不维护排他的 active plugin / active context;插件切换不做上下文替换,规则
适用范围由
ghost_id + category边界保证。 - 不引入宿主级 rules_revision / receipt 回执协议。
- 不做指令关键词黑名单;不收紧 manifest 校验的接受范围。
8. 关键代码坐标
- 花名册 formatter 与 Ghost 固定工具:
packages/cindy-tools/src/ghost/mcpServer.ts - 花名册取数与过滤(
visibleChipGhosts/getRosterItems):apps/desktop/src/main/mcp-integrations/ghost.ts - 可见性唯一真源:
apps/desktop/src/main/cindy-brain/ghostVisibility.ts - 作者契约:
apps/desktop/resources/system-skills/cindy-plugin-creator/references/;apps/desktop/src/main/cindy-brain/forgeGuide.ts组合为兼容的FORGE_GUIDE - 摘要与 manual 契约:本仓
packages/plugin-protocol/src/manifest.ts,desktop 在apps/desktop/src/shared/ghost.ts维护完整镜像 - 三 harness 注入落点:
packages/maker-core/src/agents/claude-code/index.ts(buildQuery)、packages/maker-core/src/agents/codex/index.ts(startSession → developerInstructions)、packages/maker-core/src/agents/pi/index.ts(startSession →--append-system-prompt);Pi 的 host 侧装配在apps/desktop/src/main/maker-host/pi-host.ts(buildPiAgent / composePiSystemPrompt)
任务内授权指引
Desktop 的 Claude/Codex/Pi Host 追加同一静态授权指引,复用现有发现及市场安装工具,
不改安装权限或来源策略。已有登录态时,用户明确要求更新授权仍调用 reauthorize:true;
私密值只填原卡片,不进入工具参数或对话。先等待 Host 完成,再以最小只读调用验证平台权限。
提示词保持原 system 前缀,无设备 ID、凭据、时间戳或动态账号状态;详见
远程授权契约 的兼容性与缓存影响。