knowledge-extension-ecosystem

name	knowledge-extension-ecosystem
description	覆盖 Blade 的 MCP、插件、Skills、自定义命令、Hooks 与 LSP 扩展边界及其 Session 集成关系。进入条件：新增扩展来源、调整 Workspace 扩展发现、排查插件资源未生效、 修改扩展资源快照或判断扩展职责归属。不包含：内置工具执行管线（见 ../tool-and-automation-platform/）、Workspace Trust 与通用配置合并（见 ../workspace-policy-and-shared-foundations/）。关键词：extension ecosystem、 MCP、plugin、SkillRegistry、CustomCommandRegistry、HookManager、LspSessionManager。

Module Structure

扩展生态先在 source project 上发现配置与资源，再由 Workspace 级注册表完成插件整合， 最后冻结为 Session 私有视图；MCP 和 LSP 还会在 Session 初始化时创建独立连接与进程。

Directory Layout

• packages/cli/src/mcp/ — MCP transport、目录、交互、恢复、OAuth 与异步任务
• packages/cli/src/plugins/ — 插件发现、装载及向其他扩展点的资源注入
• packages/cli/src/skills/ — Skill 元数据发现、正文延迟加载与注册表
• packages/cli/src/slash-commands/custom/ — Markdown 自定义命令解析和执行
• packages/cli/src/hooks/ — Hook 配置、匹配、信任与多种执行后端
• packages/cli/src/lsp/ — Session 级语言服务器客户端和语义查询
• .blade/ — 仓库内项目级 Skills、命令与配置资源

Key Entry Points

• resolveWorkspaceAgentResources() in packages/cli/src/agent/resources/WorkspaceAgentResources.ts — 初始化并缓存 Workspace 扩展注册表
• snapshotWorkspaceAgentResources() in packages/cli/src/agent/resources/WorkspaceAgentResources.ts — 创建 Session 持有的扩展资源快照
• resolveWorkspaceMcpConfig() in packages/cli/src/mcp/resolveWorkspaceMcpConfig.ts — 合并当前 Session 的 MCP 来源
• resolveWorkspaceLspResources() in packages/cli/src/lsp/WorkspaceLspResources.ts — 解析并冻结当前 Session 的 LSP 配置
• SessionRuntime.initialize() in packages/cli/src/agent/runtime/SessionRuntime.ts — 绑定 Hooks 并创建 Session 私有 MCP/LSP 运行时

Gotchas

• Workspace Trust 只决定项目扩展资源能否被发现，配置型 Hook 还必须通过独立的精确摘要信任；信任 workspace 不等于信任其中的命令、Prompt 或 HTTP Hook(packages/cli/src/skills/SkillRegistry.ts, packages/cli/src/hooks/HookTrustService.ts)
• source project 是 MCP/LSP/插件配置身份，execution workspace 是 worktree 中实际执行工具和启动 LSP 的路径；将两者混用会让 MCP 默认 cwd、MCP roots 或 LSP 文件边界指向错误 checkout(packages/cli/src/agent/runtime/SessionRuntime.ts, packages/cli/src/mcp/resolveWorkspaceMcpConfig.ts, packages/cli/src/lsp/LspSessionManager.ts)
• 插件刷新先清空再整批重注入 Workspace 注册表，但已创建 Session 使用 Skills、命令、Hooks 和 LSP 的快照，不应被刷新中的可变对象追改(packages/cli/src/plugins/PluginIntegrator.ts, packages/cli/src/agent/resources/WorkspaceAgentResources.ts)
• 插件整合阶段只登记 MCP/LSP 定义数量，不建立连接；实际 MCP client 和 LSP process 都延迟到精确 Session 中创建(packages/cli/src/plugins/PluginIntegrator.ts, packages/cli/src/agent/runtime/SessionRuntime.ts)
• MCP、LSP、Skills 和命令均按 workspace 或 Session 隔离，不能以无参数全局单例作为多项目调用的权威来源(packages/cli/src/mcp/McpRegistry.ts, packages/cli/src/skills/SkillRegistry.ts, packages/cli/src/slash-commands/custom/CustomCommandRegistry.ts)

Architecture

• 扩展资源主链路是“Workspace 发现与插件整合 → Session 快照 → 工具/Prompt/事件适配”；该边界让项目切换和插件刷新不改变正在运行的模型回合(packages/cli/src/agent/resources/WorkspaceAgentResources.ts, packages/cli/src/agent/runtime/SessionRuntime.ts)
• 插件是扩展聚合入口，可同时提供命令、Skills、Agents、Hooks、MCP 和 LSP；其中命令、Skills、Agents 注入 Workspace 注册表，Hooks 整批交换配置，MCP/LSP 由 Session 重新解析(packages/cli/src/plugins/PluginIntegrator.ts, packages/cli/src/plugins/PluginLoader.ts)
• Skills 与自定义命令都以 Markdown 为载体，但 Skills 将元数据暴露给模型并延迟加载正文，自定义命令会在发现时加载正文并在调用前展开参数、Shell 和文件引用(packages/cli/src/skills/SkillLoader.ts, packages/cli/src/slash-commands/custom/CustomCommandExecutor.ts)
• Hooks 是扩展域的行为拦截层，横跨工具准入、权限、会话、Agent 停止、压缩和 MCP Elicitation；它不拥有这些领域的主状态(packages/cli/src/hooks/types/HookTypes.ts, packages/cli/src/tools/execution/ToolExecutionHooks.ts)
• MCP 工具和 LSP 工具都进入统一 ToolRegistry，但前者是外部 Execute 工具与动态目录，后者是仅在 Session 有可用服务器时注册的 ReadOnly 语义查询工具(packages/cli/src/mcp/createMcpTool.ts, packages/cli/src/tools/builtin/index.ts)

Decisions

• 运行时资源在 Session 创建时做深拷贝快照，是为了阻止后续 workspace refresh、项目切换或插件刷新改变活动 Session 已暴露给模型的能力集合(packages/cli/src/skills/SkillRegistry.ts, packages/cli/src/slash-commands/custom/CustomCommandRegistry.ts, git:f6a82242)
• 扩展点统一经过 Workspace Trust 后再读取项目级可执行资源，同时保留用户级资源可用性；Hooks 额外按内容摘要授权，避免“信任路径”永久授权后续修改(packages/cli/src/security/WorkspaceTrustService.ts, packages/cli/src/hooks/HookTrustService.ts, git:a172a7c0)
• MCP 与 LSP 放在独立 Session 生命周期而非进程全局生命周期，以隔离并行 Session 的连接、目录、诊断、环境和清理责任(packages/cli/src/agent/runtime/SessionRuntime.ts, packages/cli/src/mcp/McpRegistry.ts, packages/cli/src/lsp/LspSessionManager.ts)

Patterns

• 插件资源使用 plugin:<plugin-name>:<resource> 或稳定 provider 名称避免跨插件冲突；短名只在唯一时才可解析(packages/cli/src/plugins/namespacing.ts, packages/cli/src/skills/SkillRegistry.ts, packages/cli/src/slash-commands/custom/CustomCommandRegistry.ts)
• 外部扩展产生的 schema、日志、结果、指令和配置都在进入模型或 UI 前做大小、类型和安全投影，不能直接透传协议对象(packages/cli/src/mcp/McpToolResult.ts, packages/cli/src/hooks/schemas/HookSchemas.ts, packages/cli/src/config/lspSettings.ts)

Child Knowledge Nodes

• ./mcp-protocol-runtime/SKILL.md — 进入条件：修改 MCP transport、动态目录、OAuth、Elicitation、Sampling、Tasks、结果安全或连接恢复
• ./plugin-lifecycle-and-marketplace/SKILL.md — 进入条件：修改插件发现、安装、来源策略、兼容性、命名空间或资源注入
• ./skills-and-custom-commands/SKILL.md — 进入条件：修改 SKILL.md/命令 Markdown 解析、覆盖优先级、延迟加载、Session 快照或调用入口
• ./hooks-and-behavior-interception/SKILL.md — 进入条件：修改 Hook 事件、匹配、执行顺序、信任摘要、错误策略或跨领域拦截行为
• ./lsp-code-intelligence/SKILL.md — 进入条件：修改 LSP 配置、进程代际、文档同步、诊断回注、语义查询或子 Session 继承