Architecture review 03 — Unify the Skill catalog behind one deep module

[suntianc]

来源：improve-codebase-architecture 架构审查（2026-07-20）。本 issue 作为记录，尚未经过 /grilling 决策树细化。
推荐强度：Worth exploring · 依赖类别：in-process

Files

• src/main/deepagent/skill-manager.ts · 66 symbols
• src/main/deepagent/skills-runtime/skill-sources.ts · 35 symbols
• src/main/deepagent/skills-runtime/cdf-skills-runtime.ts · skill-prompt.ts · skill-metadata.ts
• src/main/deepagent/static-skill-package.ts · 13 symbols

Problem

要回答“这个 Conversation 能看到哪些 Skill？”需要在两个目录的 7 个文件之间跳转；skill-manager.ts 把 CRUD、目录解析、内建注册和 frontmatter 解析混在一起。一个 Skill 要穿过许多薄层（source plan → catalog resolve → prompt render → manager → materialize → 薄包装）。

Solution

一个深的 SkillsCatalog，拥有 discovery、resolution、snapshot 与 view-building；runtime-assembly 向它索取已解析集合 + prompt；CRUD 也经由同一模块。

Wins

• locality：解析类 bug 集中在一处
• leverage：一个接口服务 runtime、settings、snapshots
• Conversation Skill Snapshot 逻辑集中
• skill-manager 接口大幅收缩

备注

候选 01 收拢后会为本候选解锁——Skill 接线目前就嵌在 Agent Run 装配簇中。

---

Spec（/to-spec 调研补充，2026-07-26）

调研结论：问题仍然存在，且已解锁——备注中的前置「候选 01」（#199 装配收拢）已落地，Skill 接线现集中在装配模块，正是本候选期望的消费方形态。
散落的具体证据：isGlobalSkillSourceKind 类型守卫在快照捕获与 skills-runtime 两处重复实现；Skill source label 映射（Built-in / Project / Nested / Global / Managed）在 skill-manager 与 skills-runtime 各写一份；Conversation Skill Snapshot 捕获自行拼装 source plan → catalog resolve → Scene 过滤三步；slash command 收集器绕过任何接口直接调用底层目录 helper。当前 7 个消费方（IPC 处理器、Scene 曝光策略、快照捕获、运行时装配、Agent 工具、上下文聚合、command 收集器）各自从 2–3 个供应文件拼装所需能力。

Problem Statement

维护者要回答"这个 Conversation 能看到哪些 Skill？"，必须在两个目录的 7 个文件之间追踪：source plan 如何铺（built-in / project / nested / additional / user global / enterprise）、catalog 如何 resolve 与 shadow、Scene Skill Exposure 如何过滤、快照如何冻结、prompt 如何渲染、Settings 视图如何构建。任何解析类 bug（优先级、遮蔽、Scene 过滤、缓存失效）可能出在其中任意一层，且同一判断逻辑存在多份拷贝，改一处漏一处。

Solution

建立一个深的 Skill Catalog 模块作为"哪些 Skill 存在、对谁可见"这一问题的唯一回答者。它拥有 discovery（source plan + 缓存/失效）、resolution（catalog resolve + shadowing + Scene Skill Exposure 过滤）、Conversation Skill Snapshot 的捕获与冻结目录重建、Settings 视图构建，以及物理 Skill 的 CRUD。运行时装配向它索取已解析集合 + prompt；快照持久化层向它索取捕获结果；slash command 收集器与 Agent 工具改走同一接口。frontmatter 解析、prompt 渲染等保留为模块内部实现文件，但对外接口收敛为一个。

User Stories

1. 作为 CDF 维护者，我想让"这个 Conversation 能看到哪些 Skill"由一个模块回答，以便解析类 bug（优先级、遮蔽、Scene 过滤）只需要在一处定位与修复。
2. 作为 CDF 维护者，我想删除重复的 source-kind 判断与 source label 映射，以便新增一种 Skill 来源时只改一处。
3. 作为代码代理（AFK agent），我想通过 Skill Catalog 一个接口理解 Skill 的完整生命周期（发现→解析→曝光→快照→渲染→CRUD），不再重建 7 文件的心智地图。
4. 作为 CDF 用户，我希望 Conversation 创建时冻结的 Conversation Skill Snapshot 行为完全不变：后续 Scene Skill Exposure 变更只影响新 Conversation，Agent Skill Preload 仍只能从快照内选择（CONTEXT.md 契约不变）。
5. 作为 CDF 用户，我希望 Settings 中的 Skill 列表（含遮蔽提示、来源标签、可编辑性、资源文件）展示与操作行为完全不变。
6. 作为 CDF 用户，我希望 Skill 的新建、导入、删除行为不变，且写入后缓存正确失效、列表即时刷新。
7. 作为 CDF 用户，我希望 Scene 对 Global Skill 的曝光规则不变（Built-in 走策展默认、user-global 默认全 Scene、Project Skill 无曝光控制，ADR-0069 不变）。
8. 作为 CDF 用户，我希望系统提示词中的 Skills System 段落（渐进披露、Preloaded Skills）逐字节不变，保持 prompt-cache 稳定。
9. 作为 CDF 维护者，我希望运行时装配、上下文聚合、slash command 收集、Agent 工具这些消费方都改为向 Skill Catalog 索取，不再直连底层目录 helper。
10. 作为 CDF 维护者，我希望 Built-in Skill 的注册、pin 与 materialization（含第三方改编的许可证声明）继续由本模块统一持有（ADR-0067 不变）。
11. 作为测试作者，我想主要在 Skill Catalog 接口上测试解析、遮蔽、曝光、快照行为，用临时目录构造 Skill 树，不断言内部分层。
12. 作为 CDF 维护者，我希望收拢后 skill-manager 的公开导出面大幅收缩，防止未来消费方再次绕层。

Implementation Decisions

• 一个公开模块：Skill Catalog 拥有 discovery、resolution、snapshot capture、view building、CRUD、Built-in 注册与 materialization。frontmatter 解析与 prompt 渲染保留为内部实现文件（深模块 ≠ 单文件），不再从包外导入。
• 接口面（按能力描述，非最终签名）：解析目录（项目 + Scene → 已解析条目集，含遮蔽信息）；Settings 视图（项目级与产品级 Global 两种）；捕获 Conversation Skill Snapshot；从冻结快照重建运行时目录并渲染 prompt（含 preload keys）；保存/导入/删除物理 Skill；Built-in 注册查询。
• 数据库边界：Skill Catalog 只依赖文件系统与配置，不接触 SQLite。Conversation Skill Snapshot 的持久化（sessions 表读写、legacy 一次性捕获）留在现有快照持久化模块，由它调用 Catalog 的捕获接口。
• 策略注入：Scene Skill Exposure 过滤器仍由曝光策略模块提供、以谓词注入 Catalog（保持 ADR-0069 的策略归属，Catalog 不内联 Scene 策略表）。
• 去重：source-kind 分类守卫与 source label 映射收敛为单份，放在共享 Skill 类型旁或 Catalog 内部，两个现有拷贝删除。
• 消费方迁移：运行时装配（Architecture review 01 — Collapse the Agent Run assembly god-file #199 后的装配模块）、上下文聚合、IPC 处理器、command 收集器、Agent 工具全部改走 Catalog 接口；command 收集器不再直接拿 built-in 目录与 scope path。
• 零行为变更：解析优先级、遮蔽规则、缓存 TTL 与失效时机、prompt 文本、共享类型（快照条目、视图类型）与 IPC 契约全部不变。
• 许可证声明：deepagents 改编的 prompt 渲染文件保留其 MIT 许可注释与改编说明。

Testing Decisions

• 好的测试只验证外部行为：给定磁盘上的 Skill 目录树 + Scene + 配置，断言解析结果、遮蔽关系、快照条目、prompt 输出、视图字段；不断言内部调用层次。
• 主测试面收敛到 Skill Catalog 接口；现有 source plan / catalog resolve 的行为测试（临时目录构造多来源 Skill 树的写法）整体迁移或保留为内部实现测试——保留标准：测的是真实解析行为而非层间转发。
• frontmatter 解析与 prompt 渲染的现有测试保留（真实行为）。
• 快照持久化模块的测试继续走"内存 SQLite + 捕获一次性"的现有写法，只把捕获部分换成 Catalog 接口。
• 先例：现有 skill-sources、skill-manager、cdf-skills-runtime、skill-metadata、skill-prompt 各测试文件。
• 验证：pnpm test 覆盖 deepagent skill 全簇 + 快照 + ipc-handlers + commands；关键回归项为快照冻结语义与 prompt 字节稳定。

Out of Scope

• 不改变任何解析/遮蔽/曝光规则，不新增 Skill 来源种类。
• 不改 Conversation Skill Snapshot 的存储格式与冻结语义（CONTEXT.md 契约、prompt-cache 稳定性约束不变）。
• 不动 ADR-0067 / ADR-0069 / ADR-0070 的决策本身。
• 不改 Settings UI、渲染进程代码与 IPC channel 契约。
• 不重构 runtime.ts 其余装配（Architecture: 抽取 Delegated Agent Run 运行时构造，补全 delegated-* 模块族 #201 范畴）、不动 Conversation Working State（Architecture review 04 — Consolidate Conversation Working State locality #197 范畴）。

Further Notes

• 前置已满足：Architecture review 01 — Collapse the Agent Run assembly god-file #199 装配收拢已合入，Skill 接线集中在装配模块，本票现在可做。
• 建议在 Architecture review 04 — Consolidate Conversation Working State locality #197 之后、Architecture: 抽取 Delegated Agent Run 运行时构造，补全 delegated-* 模块族 #201 之前或并行推进；与 Architecture review 02 — Deepen the Editable Flow Diagram consistency module #200 无耦合。
• 迁移可分两步提交：先立 Catalog 接口并让装配/快照/IPC 迁入（行为保持），再收缩旧导出面并删除重复拷贝——两步都必须全绿。

[suntianc]

2026-07-28 code-review follow-up

Skill Catalog 主体收拢已落地；review 发现 enterprise 来源标签在收拢前存在 Enterprise Skill / Managed Skill 两种输出，而本票的零行为变更未明确处理这一例外。

剩余工作已拆为原生子 Issue：

• Skill Catalog：明确并锁定 enterprise 来源标签为 Managed Skill #244 — 明确 Managed Skill 为规范标签，保持单一映射并补齐 enterprise 回归测试。

父票在 #244 完成并确认其他 source kind 文案不变后关闭。

[suntianc]

#244 本地完成说明

已将 enterprise source 的规范英文标签明确锁定为 Managed Skill。这是 #198 所述“零行为变更”的显式低风险例外：统一 Settings、runtime attribution 与 slash command collector 的既有术语，不保留 Enterprise Skill 特例。

本地实现保持 getSkillSourceLabel() 为唯一 source-kind → label 映射；新增 built-in、project、project-nested、project-additional、user、enterprise 六类表驱动测试，并新增 enterprise command 回归，确认 sourceLabel = Managed Skill、source = skill:global、qualified name 与 enterprise: target 不变。

验证：pnpm run typecheck 通过；全量 pnpm test 为 198 files / 1917 passed / 1 skipped；pnpm run build 通过。

当前改动尚未提交或推送，因此 #198 / #244 暂时保持 open，待发布后关闭。

[suntianc]

已在 #245 完成实现并推送；Ubuntu、macOS、Windows CI 均通过。