[Extensions] 扩展管理层：统一安装、版本与校验 Skills/Agents/Tools/MCP

[v833]

标签建议：area/extensions, area/tools, priority/P1, type/feature, depends-on/extensions

背景

当前能力：

• q-code 支持 Skills、Agents、Tools、MCP、自定义工具目录和多级加载优先级。
• 用户级和项目级扩展分布在 ~/.q-code、~/.agents、<cwd>/.q-code、<cwd>/.agents 等位置。
• 当前扩展安装、版本、校验、启用禁用和冲突诊断缺少统一入口。

痛点：

• 用户难以知道某个 skill/tool/agent 实际从哪个路径加载、是否被项目级覆盖。
• 扩展升级或删除后，缓存、manifest、MCP 配置可能残留。
• 安装第三方扩展存在安全风险，需要校验来源、版本和权限声明。

需要补齐：

• 一个统一 extension 管理层和 CLI/TUI 入口。
• manifest、版本、依赖、权限和冲突诊断规范。
• 安装、列出、更新、删除、校验和 doctor 能力。

目标

实现扩展管理层：统一管理 Skills、Agents、Tools、MCP 扩展的安装、版本、启用禁用、校验和冲突诊断，让扩展能力可发现、可升级、可审计、可安全回滚。

用户故事

• 作为用户，我希望运行一个命令就能看到当前启用的 Skills、Agents、Tools 和 MCP 扩展来源，以便排查冲突。
• 作为插件作者，我希望有标准 manifest 描述版本、入口、权限和兼容范围，以便扩展能被 q-code 正确安装和校验。
• 作为企业用户，我希望能禁用未知来源扩展或固定版本，以便控制安全和稳定性。
• 作为维护者，我希望扩展加载顺序和覆盖关系可诊断，以便减少“为什么没有生效”的问题。

详细需求

1. Extension manifest

• 定义统一 manifest 字段：name、version、type、entry、description、permissions、engines、dependencies、checksum。
• 兼容现有 skill SKILL.md、custom tool schema.json、agent 定义和 MCP 配置。
• manifest 不完整时允许 legacy 加载，但 doctor 应提示建议补齐。

2. CLI 命令

• 设计 q-code extension list|doctor|install|update|remove|enable|disable 或等价命令。
• list 展示类型、版本、来源路径、启用状态、覆盖关系。
• doctor 检查 manifest、入口文件、权限声明、版本兼容和冲突。

3. 安装与更新

• 支持从本地路径、GitHub repo 或受信 marketplace 安装。
• 安装前展示权限声明和写入路径。
• 更新时保留用户配置，并支持失败回滚。

4. 安全与权限

• 与 [Security] Approval Policy：工具、文件、网络和工作区边界审批系统 #22 approval policy 集成，第三方扩展声明需要的文件、shell、network、MCP 权限。
• 未知来源或 checksum 不匹配时默认警告或阻止。
• 不在日志或错误中泄露扩展配置里的敏感字段。

5. 加载与缓存

• 明确用户级/项目级优先级和同名覆盖规则。
• 扩展启用/禁用应影响后续加载，并避免 stale cache。
• 加载失败不得导致 q-code 整体不可启动，除非该扩展被显式要求为必需。

输出样例

q-code extension list

TYPE    NAME              VERSION  SOURCE        STATUS
skill   brainstorming     1.2.0    user/.agents enabled
agent   reviewer          0.4.1    project      enabled
tool    jira              legacy   user/.q-code warning: missing manifest

验收标准

• 能列出当前加载的 Skills、Agents、Tools、MCP 扩展及来源路径。
• 能诊断同名覆盖、缺失 manifest、入口文件不存在和版本不兼容。
• 安装或更新扩展前展示写入路径和权限声明。
• 扩展启用/禁用后，后续加载行为与状态一致。
• 安装失败或更新失败不会留下半写入目录。
• 第三方扩展权限与 approval policy 有清晰集成点。
• README/AGENTS 增加扩展目录、manifest 和命令说明。
• 单元测试覆盖 manifest 解析、优先级、doctor 和失败回滚。

测试方案

• tests/unit/extensions.test.ts：覆盖 manifest 解析、类型识别、路径优先级和 enable/disable。
• tests/unit/custom-tools.test.ts：确认 custom tool legacy schema 兼容。
• tests/unit/skills.test.ts：确认 skill 加载与 extension manifest 兼容。
• tests/integration/extensions-flow.test.ts：覆盖本地安装、更新失败回滚和 doctor 输出。
• 手动验证：用户级与项目级同名扩展覆盖、MCP 配置错误、缺失入口文件。

不在本期范围

• 公共云 marketplace 后端。
• 扩展评分、评论和推荐系统。
• 插件运行时强隔离沙箱。
• 自动迁移所有旧扩展到 manifest 格式。

依赖 / 风险

• 涉及多个扩展目录和加载器，容易破坏现有 legacy 扩展，需要保持向后兼容。
• 安装第三方代码有供应链风险，必须先有权限声明、checksum 和来源提示。
• Windows 路径、符号链接和目录删除/移动需要安全校验。
• 与 [Security] Approval Policy：工具、文件、网络和工作区边界审批系统 #22 approval policy 和未来 marketplace 能力存在依赖关系。

工作量评估

• Manifest 与扩展 registry：2 人日
• CLI list/doctor/install/update/remove：3 人日
• 加载器接入与兼容：2 人日
• 安全校验、测试和文档：2 人日
• 合计：~9 人日，建议按 registry/doctor、安装更新、权限集成拆分