feat(plugin): 插件增加随包手册机制代替 Skill 全局注入 - #2265
Conversation
|
| Filename | Overview |
|---|---|
| apps/desktop/src/main/cindy-brain/forge.ts | 增加 Manual 目录预检、稳定快照和打包一致性检查；此前隐藏条目过滤问题已通过统一复用 shouldSkip 修复。 |
| apps/desktop/src/main/cindy-brain/GhostManager.ts | 安装与检查阶段校验 Manual 入口、路径、文件类型、大小和编码，并保留已安装旧式 metadata 的兼容读取。 |
| apps/desktop/src/main/cindy-brain/ghostManual.ts | 实现逻辑 Manual 路径解析、候选限制、错误分类和受限正文读取。 |
| apps/desktop/src/shared/ghost.ts | 扩展完整插件协议镜像，加入 Manual 清单结构、约束和信息投影。 |
| packages/cindy-tools/src/ghost/mcpServer.ts | 将 ghost_manual 接入 cindy-tools MCP 工具面及固定结果转发。 |
| apps/desktop/src/renderer/cindy-brain/GhostPermissionList.tsx | 在既有安装与更新确认界面中展示随包手册数量，不将其作为权限项。 |
| packages/maker-core/src/agents/shared/ghost-manual-fixture.ts | 为 Claude Code、Codex 和 Pi 的完整 Manual tool-result 边界测试提供共享夹具。 |
Sequence Diagram
sequenceDiagram
participant Model as 模型
participant Host as Cindy Host
participant Manager as GhostManager
participant Files as 插件 Manual
Model->>Host: ghost_info / ghost_list
Host->>Manager: 查询当前可见插件
Manager-->>Host: CindyGhostInfo + Manual 一级目录
Host-->>Model: 插件信息
Model->>Host: ghost_manual(ghost_id, path?)
Host->>Manager: 校验可见性并解析逻辑路径
Manager->>Files: 受限读取 Markdown
Files-->>Manager: Manual 正文
Manager-->>Host: 固定结果信封
Host-->>Model: tool-result
Model->>Host: ghost_call(...)
Reviews (4): Last reviewed commit: "fix(plugin): preserve legacy manual inst..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull request overview
本 PR 为插件体系引入“随包 manual 渐进披露”能力：通过新增固定工具 ghost_manual 按需读取插件手册正文，避免将长文塞入花名册或 system prompt；同时补齐打包/装入/运行期的制品与路径安全校验，并在安装/更新确认 UI 中展示“随包手册 N 篇”。
Changes:
- 新增
ghost_manual(ghost_id, path?)：提供根索引与按需读取正文的固定信封返回，并接入 Desktop host 可见性门禁与免审只读工具白名单。 - 在 Desktop 的 manifest 镜像校验、Forge 打包、GhostManager 装入三侧加入
manual.items结构校验与 Markdown/UTF-8/大小/符号链接/路径规则等安全约束，并新增覆盖测试。 - 在插件安装/更新/批量更新确认界面新增“随包手册 {{count}}”信息行，补齐四语与对应 UI 单测。
Reviewed changes
Copilot reviewed 39 out of 39 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| packages/maker-core/src/agents/pi/tests/pi-translator.test.ts | 增加 Pi harness 下 ghost_manual 大信封只作为 tool_result 数据保留的边界测试 |
| packages/maker-core/src/agents/codex/translator.test.ts | 增加 Codex harness 下 ghost_manual 高转义大信封不截断的边界测试 |
| packages/maker-core/src/agents/claude-code/tests/translator-tool-output.test.ts | 增加 Claude Code harness 下 ghost_manual 大信封归入 MCP tool_result 的边界测试 |
| packages/cindy-tools/src/types.ts | 扩展 cindy-tools 类型：CindyGhostInfo.manual、CindyGhostManualResult、readGhostManual deps |
| packages/cindy-tools/src/index.ts | 导出 handleGhostManual 与新增的 manual 相关类型 |
| packages/cindy-tools/src/ghost/mcpServer.ts | 注册 MCP 工具 ghost_manual，实现 handler 与工具描述文案 |
| packages/cindy-tools/src/tests/ghostMcp.test.ts | 为 ghost_manual 固定信封、错误透传、注册描述增加单测 |
| packages/cindy-tools/package.json | 更新包描述，包含 ghost_manual |
| i18n/GLOSSARY.md | 新增 Manual 术语说明（proposed） |
| i18n/glossary.json | 新增 plugin-manual 术语条目（proposed） |
| docs/ghost-progressive-discovery.md | 更新渐进披露层级：新增 L1.75 ghost_manual，并补充 manual 的信任边界说明 |
| apps/desktop/src/shared/ghost.ts | Desktop 协议镜像扩展：新增 manual 字段、常量与 manifest 校验（含 locale 路径冲突规则） |
| apps/desktop/src/shared/tests/ghost.test.ts | 覆盖 manifest 校验：manual 与 locale/声明文件冲突、祖先/后代目录允许等用例 |
| apps/desktop/src/renderer/i18n/locales/zh-CN/common.json | 新增安装/更新确认信息行 manualCount 文案（zh-CN） |
| apps/desktop/src/renderer/i18n/locales/ko/common.json | 新增安装/更新确认信息行 manualCount 文案（ko） |
| apps/desktop/src/renderer/i18n/locales/ja/common.json | 新增安装/更新确认信息行 manualCount 文案（ja） |
| apps/desktop/src/renderer/i18n/locales/en/common.json | 新增安装/更新确认信息行 manualCount 文案（en） |
| apps/desktop/src/renderer/features/plugin/UpdateAllDialog.tsx | 批量更新审阅展开区增加 manual 篇数信息行展示 |
| apps/desktop/src/renderer/features/plugin/PluginMarketPermissionReviewHost.tsx | 市场安装/更新确认内容区接入 manual 篇数展示 |
| apps/desktop/src/renderer/features/plugin/GhostPluginPage.tsx | 插件页安装/更新确认内容区接入 manual 篇数展示 |
| apps/desktop/src/renderer/features/plugin/tests/UpdateAllDialog.test.tsx | 新增批量更新对话框：manual 信息行不进入权限 diff 的 UI 单测 |
| apps/desktop/src/renderer/cindy-brain/installFlow.tsx | 安装/更新确认组件参数传递：将 manualCount 注入 review 组件 |
| apps/desktop/src/renderer/cindy-brain/GhostPermissionList.tsx | 新增 GhostManualSummary 组件，并在安装/更新确认中展示 |
| apps/desktop/src/renderer/cindy-brain/tests/installFlow.test.tsx | 覆盖：带 manual 的包会把篇数传入装入确认内容 |
| apps/desktop/src/renderer/cindy-brain/tests/GhostPermissionList.test.tsx | 覆盖：manual 信息行的渲染与更新确认内容包含 manualCount |
| apps/desktop/src/main/utils/readBoundedFile.ts | 增强 bounded read：新增返回预期文件长度的 readBoundedFileNoFollowWithSize |
| apps/desktop/src/main/mcp-integrations/ghost.ts | Desktop host 接线：投影 manual 索引到 ghost_info/list，并实现 readGhostManual 调用链 |
| apps/desktop/src/main/mcp-integrations/tests/ghostWorkdirGate.test.ts | 覆盖：manual 索引投影与 ghost_manual 不启动插件运行时的行为 |
| apps/desktop/src/main/maker-host/mcp-tool-approval-policy.ts | 将 cindy::ghost_manual 加入只读工具免审 allowlist |
| apps/desktop/src/main/maker-host/tests/mcpToolApprovalPolicy.test.ts | 覆盖：ghost_manual 免审策略与 Claude read-only 工具清单 |
| apps/desktop/src/main/cindy-brain/ghostManualValidation.ts | 新增：manual 逻辑路径解析、Markdown 文件判据与严格 UTF-8 解码裁判 |
| apps/desktop/src/main/cindy-brain/ghostManual.ts | 新增：运行期 readInstalledGhostManual（候选预算、no-follow、错误分流与固定信封） |
| apps/desktop/src/main/cindy-brain/GhostManager.ts | 装入侧校验扩展：对 zip 内 manual 制品执行对等校验与边界拒绝 |
| apps/desktop/src/main/cindy-brain/forge.ts | 打包侧校验扩展：对源码目录 manual 单元执行制品校验与入包一致性对账 |
| apps/desktop/src/main/cindy-brain/tests/ghostManualValidation.test.ts | 新增：manual 逻辑路径与映射规则的单测 |
| apps/desktop/src/main/cindy-brain/tests/ghostManual.test.ts | 新增：运行期 ghost_manual 读取/候选/错误分流/安全边界的单测 |
| apps/desktop/src/main/cindy-brain/tests/GhostManager.test.ts | 扩展：旧布局兼容升级与 manual 装入侧对等校验用例 |
| apps/desktop/src/main/cindy-brain/tests/forge.test.ts | 扩展：FORGE_GUIDE manual 作者契约断言与 packGhostDir manual 打包校验用例 |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 400a38874d
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
7b3f52d to
fe35045
Compare
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 39 out of 39 changed files in this pull request and generated no new comments.
Suppressed comments (1)
packages/cindy-tools/src/types.ts:180
- CindyGhostManualErrorCode 的字符串字面量这里使用了双引号，但同文件内其它字符串字面量/联合类型都使用单引号；为保持一致性并避免潜在的 lint/format 漂移，建议统一为单引号。
fmfsaisai
changed the title
fmfsaisai
changed the title
1f0a66a to
a4baaaf
Compare
fmfsaisai
changed the title
Signed-off-by: fmfsaisai <fmfsaisai@gmail.com>
Signed-off-by: fmfsaisai <fmfsaisai@gmail.com>
Signed-off-by: fmfsaisai <fmfsaisai@gmail.com>
Signed-off-by: fmfsaisai <fmfsaisai@gmail.com>
Signed-off-by: fmfsaisai <fmfsaisai@gmail.com>
Signed-off-by: fmfsaisai <fmfsaisai@gmail.com>
Signed-off-by: fmfsaisai <fmfsaisai@gmail.com>
a4baaaf to
a64c977
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a64c977746
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
@fmfsaisai 👋 这个 PR 还有 1 条 review conversation 没 resolve(apps/desktop/src/main/cindy-brain/GhostManager.ts),auto-review 因此暂时跳过、没法继续审查 / 合并。 如果你已经按评论改完或回应了,请到对应 thread 上点 Resolve conversation;全部 resolve 后,下一轮 auto-review 会自动重新审查这个 PR。 |
Signed-off-by: fmfsaisai <fmfsaisai@gmail.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 19b64b9c19
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| const strict = validateGhostManifest(raw); | ||
| if (strict.ok) return { ok: true, manifest: strict.manifest, legacyManualIgnored: false }; |
There was a problem hiding this comment.
If an already-installed pre-feature plugin used manual as custom metadata that happens to satisfy the new {items:[...]} shape, this strict-success return accepts it as a real bundled manual instead of taking the legacy-installed compatibility path. Old hosts would have ignored that field, so after upgrade the same installed package can hash differently in installedGhostRawManifestDigest / readInstalledGhostManifestDigest (breaking market ownership/update matching or oidc-token Connection injection) and ghost_info may advertise a manual whose files were never installed; installed-manifest reads need to verify the declared manual files exist before preserving the field, or otherwise strip it as legacy metadata. docs/dev-rules/plugin-security-and-authoring.mdL151-L163
Useful? React with 👍 / 👎.
MagicLizi
added
touches:core
|
@fmfsaisai 👋 这个 PR 还有 2 条 review conversation 没 resolve(apps/desktop/src/main/cindy-brain/GhostManager.ts / apps/desktop/src/main/installedGhostManifest.ts),auto-review 因此暂时跳过、没法继续审查 / 合并。 如果你已经按评论改完或回应了,请到对应 thread 上点 Resolve conversation;全部 resolve 后,下一轮 auto-review 会自动重新审查这个 PR。 |
|
@fmfsaisai 👋 这个 PR 还有 1 条 review conversation 没 resolve(apps/desktop/src/main/installedGhostManifest.ts),auto-review 因此暂时跳过、没法继续审查 / 合并。 如果你已经按评论改完或回应了,请到对应 thread 上点 Resolve conversation;全部 resolve 后,下一轮 auto-review 会自动重新审查这个 PR。 |
这次改了什么
摘要
这个 PR 为插件补上了一套渐进式披露机制：模型先用很短的召回信息找到插件，再按当前任务逐步读取插件概况、手册正文和具体工具规则，信息够用后才执行操作。
它解决的不是“多一个 Markdown 读取工具”这么简单。插件过去要承载复杂工作流时，通常只能在两种不理想的做法里选：把长说明常驻到提示词，挤占每轮上下文；或者只暴露工具名，让模型缺少跨工具步骤、分支条件、异常处理和交付要求。这个 PR 把“找到插件”“理解工作流”“了解当前类别的具体工具”“真正执行”拆成可按需展开、可来回查阅的几层。
旧的插件工作流接入方式会把随插件提供的
SKILL.md注册到用户目录的全局 Skill 发现范围。这里的问题不是 Skill 机制本身，而是插件为了携带自身工作流而进行的 Skill 全局注入：插件内容会占用用户级注册空间，可能与用户或其它插件的 Skill 名称冲突；工作流脱离插件本身的安装、启用和卸载生命周期，卸载插件后还可能留下注册残留；即使当前任务与该插件无关，这些插件工作流也会参与全局 Skill 召回。Manual 改为随插件包安装，并跟随插件卸载。模型先通过插件花名册或
ghost_info找到目标插件，再用ghost_manual按当前任务渐进读取需要的正文；它不进入用户全局 Skill 注册空间，也不会把手册正文注入生产 system/developer prompt。Manual 正文只作为
ghost_manual的 tool-result 在需要时进入上下文，不进入生产 system/developer prompt。手册内容是插件作者提供的数据，不是系统规则、用户意图或权限授权；真正执行仍由现有ghost_call可见性、setup、权限和运行期门禁约束。协议契约已随 #2373 本地化：客户端与服务端各自维护
packages/plugin-protocol，本 PR 不再使用cindy-protocolgitlink，也不依赖旧的check:submodule-forward。本 PR 最终相对本次 rebase 基底包含 38 个文件；其中第 38 个文件是供 Claude Code、Codex、Pi 三套 translator 测试共用的纯测试 helper，不改变生产运行时行为。
渐进式披露如何工作
recall = whenToUse ?? description，用很短的场景线索帮助模型想起应使用哪个插件。用户直接点名插件、或上文已知ghost_id，也可以成为 id 来源，但不属于花名册层本身。ghost_info与ghost_list是并列的实时查询方式。 已知ghost_id时用ghost_info精准查询；花名册未命中、或怀疑插件在会话中途装卸/启停时，用ghost_list一次回查全部。两者返回同样完整的CindyGhostInfo，不存在先用ghost_list再补ghost_info的固定链路。ghost_manual负责按需取文。 无path时返回根索引；逻辑单元名映射到该单元的MANUAL.md；其后可读取任意深度的普通 Markdown 子页。Manual 文件不使用 frontmatter。Host 不规定某页必须是“索引”还是“正文”，作者可以自由组织为索引、正文或二者混合，但下一步导航必须给出可直接照抄的完整ghost_manual调用。list_tools(category)负责动态工具披露。 它不是 Host 固定工具，而是目标插件声明的顶层工具，实际调用形态是ghost_call({ ghost_id, tool: "list_tools", args: { category } })。它可以返回该类别的具体工具、参数和result.rules；这里的 RULES 是插件返回数据，不是 manifest 字段、Manual 文件树的一层或 Host 授权机制。与 Skill 机制的准确对应
name + descriptionrecall召回元数据MANUAL.mdmanual.items[{ dir, name, description }]不对标 Skill frontmatter。它是插件容器级的一级目录：一个插件可以声明最多 8 个逻辑手册单元，Host 用name映射物理dir，对模型只投影name + description，不暴露物理目录。这让插件可以承接原来由 Skill 提供的长工作流，又不用把正文常驻到 system/developer prompt。
ghost_manual相当于按需读取入口，但不会把作者内容提升为系统指令或执行授权。再次强调：本 PR 替代的是插件把自身工作流注入用户全局 Skill 发现范围的旧集成方式，不是否定 Skill。真正属于用户、项目或跨插件的通用工作方法仍可使用 Skill；插件私有的工作流、复杂工具深度用法和随包参考资料则由 Manual 随插件管理。
一个交叉读取的例子
以下仅用于说明后续插件迁移完成后的调用方式，不表示
x-manager已在本 PR 中迁移。用户提出“检查 X 平台的回复限制，并按正确流程执行一次回复”时：
系统提示词区花名册的
recall召回x-manager，得到ghost_id。已知 id，调用
ghost_info({ ghost_id: "x-manager" })，实时取得完整插件信息和 Manual 一级目录。先读对应单元入口：
入口页要求先读完整回复工作流，于是继续调用：
工作流说明下一步需要查询回复类别的实际工具和规则，于是通过 Host 执行插件的顶层分派工具：
list_tools返回具体操作、参数和该类别的result.rules。如果 RULES 指向另一篇 Manual，则按完整ghost_manual调用回读；信息足够后，再通过ghost_call调用插件的call_tool执行具体回复。这里的二级 RULES 始终来自
list_tools的结果，不是ghost_manual根索引或 Manual 文件树本身。变更类型
feat新功能fix缺陷修复refactor/perf重构或性能优化docs/test/chore文档、测试或工程维护范围
manual.items[{dir,name,description}]manifest 镜像和兼容校验；MANUAL.md入口、任意深度目录、仅普通 Markdown、严格 UTF-8、单文件 64 KiB、符号链接、特殊文件和读取一致性；ghost_manual(ghost_id, path?)：专用逻辑路径解析、受限候选、固定信封、可见性复用和错误分流；ghost_list/ghost_info的轻量 Manual 一级目录投影，以及 cindy-tools 的完整接线；minCindyVersion发布门槛、list_tools(category)分工和 Skill 迁移口径；docs/ghost-progressive-discovery.md对新发现机制和 desktop 完整协议镜像的同步；packages/plugin-protocol的本地协议消费与apps/desktop/src/shared/ghost.ts完整镜像保持一致；不恢复旧 submodule/workspace。ghost_manual按需读取手册。manual的旧 manifest 保持原有校验和运行行为。UI 变化
在既有插件安装、单项更新和批量更新确认卡中复用
GhostManualSummary，展示纯信息行“随包手册 N 篇”。它不进入权限 diff，也不增加授权项。docs/design-rules/DESIGN.md§2 Layer System / Neutrals & Text：沿用既有--border-default、--text-tertiary等语义 token，不添加硬编码颜色；怎么验证的
自动验证
提交前本地门禁：
四个硬门覆盖：
name→ 物理dir、不做 URL decode、traversal/非 Markdown 拒绝、候选预算和固定信封；manualmetadata 和既有 locale/skill 语义回归。截至 2026-08-13，本次推送后的远端 PR head 为
a64c9777466f3ac9c0f753494dbad4d1e168e756，PR 已 Ready；该 7 个线性提交基于origin/main=4318ebc87c6067a48df53aac826f677a8d0ae893。最终 Head 的根pnpm test:unit为 384 tests：383 pass / 1 skip / 0 fail；推送后 CI 已针对新 Head 启动。执行时origin/main已继续前进，后续 main 变化不属于本次功能提交。手工验证
历史完整 Run 2 已在功能 head
fe3504523329cf53e56fd4d69bbfdb461f18d343上完成真实中国大陆版隔离 Desktop E2E，运行环境使用--region=cn --isolated=ghost-manual-e2e-cn-r2，独立 userData；UI 显示 CN 身份，Hostapp-context.region实测为cn。本次第 6 个 cleanup 提交没有改变 runtime/schema/tool 行为，因此不机械重跑完整 E2E。在上述历史 Run 2 之外，本轮只做了最小 CN 真实冒烟：由真实 Forge 生成
.cindy，走正常安装，再调用 Manual/MCP；包 SHA 前缀为0c521125…，测试插件、fixture、包、runtime 和 sandbox 已清理。该冒烟证明 Host/插件链路可用，不证明 LLM 自动决策能力。历史 Run 2 主成功链没有目录直装或使用外部 Forge：测试插件源码由当前 PR Desktop 内置 Forge 生成真实
.cindy，再走正常安装 / 更新确认，贯通 Forge 打包期 → GhostManager inspect/install → 运行期ghost_manual。结果：ghost_list/ghost_info的实时发现、Manual 根索引与深层 Markdown、大小写/百分号/非法路径、缺失候选和损坏分流均符合契约；MANUAL_UNAVAILABLE，修正后的finally自动恢复内容、SHA 与 mode，恢复后立即可读；ghost_call(list_tools)后 runtime 从 off 变为 running；两种 stop/reset 顺序、首 probecallCount=1和region=cn均通过；Codex GPT-5.6 Sol。该黑盒结果只证明组合发现链可用，不单独证明 system/developer 主花名册通道；GHOST_NOT_FOUND和新会话不再召回均通过；审计说明：Run 1 保留一次测试脚本 harness FAIL——产品已正确返回
MANUAL_UNAVAILABLE，但旧finally对 mode=000 文件先复制后恢复写权限，导致自动恢复失败。Run 2 修正为先恢复写权限、再复制、恢复原 mode 并校验 SHA/mode，从全新隔离 profile 和全新沙箱完整重跑后全链通过；没有把 Run 1 事后改写成 PASS。尚待处理 / 不在本次 E2E 内
pnpm --filter @cindy/maker-core build在 4 个既有测试文件报告 69 个 TypeScript 类型错误。已在独立 detached worktree 中用相同 Node、pnpm、TypeScript 和依赖分别复现 baseecebc96与 featurefe350452：两边均 exit 2，归一化后的 114 行日志逐字相同，错误文件在本 PR 中零 diff，因此确认是既有基线而非本分支引入。当前硬门只要求 rootpnpm test:unit与涉及 package 的run --if-present typecheck；maker-core 没有typecheckscript，GitHub CI 也不执行整包 tsc。该覆盖空档应另开基线任务处理，不在本 PR 修改无关测试；风险
风险分类
影响与回滚
manual的旧 manifest 维持 origin/main 原有校验语义；manual当任意 metadata 的已安装插件仍可列出、保留启用状态并正常升级；manual仍严格拒绝，兼容回退只存在于已安装目录扫描路径，不会扩大权限。manual是顶层信息字段，不进入 slots 或权限 diff；ghost_manual每次调用都重新经过与ghost_info相同的可见性分类，但不启动插件 sandbox；ghost_call的运行期检查。ghost_manual信封和候选不暴露安装根、物理 Manual 目录、绝对路径或 errno；历史manualmetadata 的兼容告警只记录固定 code 和 manifestId。Forge 作者工具仍可按既有契约返回当前 workdir 内的源码/产物绝对路径，受信本地 dev 日志也可能保留有限路径诊断；公开 PR 证据必须脱敏。MANUAL_PATH_NOT_FOUND和受条数/字节预算限制的稳定候选；MANUAL_UNAVAILABLE，不提供候选；ghost_info的三种错误码。版本与发布顺序
Manual 是可选顶层字段，旧客户端可以忽略未知字段；但“能够安装”不等于“能按设计正常工作”。首个依赖
ghost_manual的插件版本必须遵循固定顺序：ghost_manual的 Cindy；minCindyVersion设为不低于该正式版本；skill.items的迁移版本也必须设置同样的版本门槛；后续工作（不在本 PR）
list_tools(category)的 RULES 互相指路；list_tools(category)和 Manual，对齐当前lark-cli + lark Skills的使用能力；这需要重新组织大量资料和非 Markdown 资产，不是原样搬运，也未在本 PR 完成；packages/plugin-protocol架构下补发布侧 Manual 制品校验与旧客户端历史 release 回退验证；手册已同步：
list_tools(category)的信息分工及发布门槛；docs/ghost-progressive-discovery.md：新的并列查询与交叉披露机制，以及 desktopshared/ghost.ts是完整协议镜像的说明。提交前检查
git commit -s，见 DCO）合并限制：本 PR 命中插件基座白名单确认门，必须等待指定放行人明确 Approve；PR 已 Ready，最终 Head
a64c9777已安全推送，CI 正在运行。本 PR 不自行合并。