MCP Hooks and AgentTarget zh CN

MCP、Hook 与 AgentTarget 设计

语言： English · 简体中文

LWC 通过一个只读 MCP 服务、有界生命周期 Hook、受管 Instructions 与 Skills，以及 12 个手写 AgentTarget adapter 接入不同宿主。每个 target 都是强适配：LWC 会安装当前 host 与 scope 具备的全部稳定官方 file-based surface，并如实报告官方缺口，不发明私有格式。

MCP 只统一 runtime message，不统一 config path、Skills、Hooks、Instructions、plugin 或 permission，因此宿主兼容性必须显式建模。

集成架构

Agent 宿主
   |-- MCP 配置 / extension bridge --> lwc serve --mcp --> lwc_explore
   |-- 生命周期事件 -----------------> lwc agent hook --> 有界 readiness
   |-- Skill -------------------------> 何时以及如何使用 LWC
   `-- Instructions ------------------> 持久宿主指导
                                                |
                                                v
                                    AgentTarget adapter + receipt

原生宿主看到的 MCP 契约完全一致：一个名为 lwc 的 server、一个只读 tool，并且不存在隐藏写入。宿主差异全部收敛在 adapter 内，由 adapter 负责识别官方路径和格式。

统一 AgentTarget 契约

所有 adapter 实现同一套生命周期与能力契约：

trait AgentTarget {
    fn id(&self) -> &'static str;
    fn adaptation(&self) -> &'static str;
    fn mcp_mode(&self, location: AgentLocation) -> &'static str;
    fn permissions_mode(&self, location: AgentLocation) -> &'static str;
    fn instructions_mode(&self, location: AgentLocation) -> &'static str;
    fn skills_mode(&self, location: AgentLocation) -> &'static str;
    fn lifecycle_mode(&self, location: AgentLocation) -> &'static str;
    fn supports_location(&self, location: AgentLocation) -> bool;
    fn detect(&self, environment: &TargetEnvironment) -> DetectionResult;
    fn install(&self, environment: &TargetEnvironment, options: InstallOptions) -> Result<WriteResult>;
    fn uninstall(&self, environment: &TargetEnvironment) -> Result<WriteResult>;
    fn print_config(&self, location: AgentLocation) -> String;
    fn describe_paths(&self, environment: &TargetEnvironment) -> Vec<PathBuf>;
}

注册表为每个宿主保存一个手写实现。选择 target、状态汇总、receipt、refresh 与部分失败由公共编排层处理；adapter 只负责官方宿主差异。

所有权与幂等性

安装时会快照每个受管路径的原内容，并记录安装后的 hash。带边界 marker 的文本让 LWC 只替换自己的 Instructions；结构化 MCP 与 Hook 片段也只有在仍符合 LWC 所有权时才会移除。

refresh 复用相同 adapter 与 receipt，不会不断叠加重复条目。uninstall 恢复原内容或精确删除受管片段，遇到归属不明的外部冲突则拒绝覆盖。--print-config 只渲染配置，不创建 receipt，也不写入宿主文件。

支持的 Target

claude             Claude Code
cursor             Cursor
codex              Codex
opencode           OpenCode
hermes             Hermes Agent
gemini             Gemini CLI
antigravity        Antigravity
kiro               Kiro
copilot-vscode     VS Code with GitHub Copilot Chat
copilot-cli        GitHub Copilot CLI
copilot-jetbrains  JetBrains IDEs with GitHub Copilot
pi                 Pi Agent

能力模式

模式	含义
installed	LWC 写入官方稳定 surface 并跟踪 ownership
extension_bridge	宿主没有内置 MCP 配置，通过官方 extension mechanism 桥接 LWC
configured_preview	LWC 写入文档化 preview 或 version-gated surface，仍需验证 host activation
user_managed	设置由宿主 UI 管理，或没有稳定文件路径
unsupported	当前 host location 没有官方 surface
not_applicable	该能力不属于宿主模型

adaptation=strong 不表示所有 cell 都是 installed，而是 adapter 准确编码宿主官方能力，并拒绝伪造缺失支持。

当前矩阵

每格顺序为 global / local。

Target	MCP	Skill	Instructions	Hook	Permissions
Claude Code	installed / installed	installed / installed	installed / installed	installed / installed	installed / installed
Cursor	installed / installed	installed / installed	user_managed / installed	installed / installed	not_applicable / not_applicable
Codex	installed / installed	installed / installed	installed / installed	installed / installed	not_applicable / not_applicable
OpenCode	installed / installed	installed / installed	installed / installed	installed / installed	not_applicable / not_applicable
Hermes Agent	installed / unsupported	installed / unsupported	installed / installed	installed / unsupported	not_applicable / not_applicable
Gemini CLI	installed / installed	installed / installed	installed / installed	installed / installed	not_applicable / not_applicable
Antigravity	installed / installed	installed / installed	installed / installed	installed / installed	not_applicable / not_applicable
Kiro	installed / installed	installed / installed	installed / installed	configured_preview / configured_preview	user_managed / user_managed
Copilot VS Code	installed / installed	installed / installed	user_managed / installed	unsupported / configured_preview	user_managed / user_managed
Copilot CLI	installed / installed	installed / installed	installed / installed	installed / installed	user_managed / user_managed
Copilot JetBrains	installed / user_managed	configured_preview / configured_preview	user_managed / configured_preview	unsupported / unsupported	user_managed / user_managed
Pi Agent	extension_bridge / extension_bridge	installed / installed	installed / installed	installed / installed	not_applicable / not_applicable

configured_preview cell 需要 host release 真正暴露对应文档化 preview surface。LWC status 只报告已配置，不会在没有 host-level check 时宣称宿主已经加载。

统一 Agent-facing MCP

所有原生 MCP adapter 都只注册一个名为 lwc 的 server：

lwc serve --mcp

CodeGraph 融合在 lwc_explore 后面，不会注册第二个 codegraph MCP server。Runtime 只暴露一个 read-only tool，支持 memory、code 与 combined mode。

Pi 没有内置 MCP config，因此使用官方 extension bridge。这项差异会被如实报告，不会隐藏。

Global 与 Local 是宿主位置

• Global 配置当前用户的 Agent installation；
• Local 通过宿主 repository surface 配置当前项目。

这些 location 不选择 LWC Wiki scope，也不会启用项目 graph capability。全局安装的 Agent integration 仍会通过普通 project discovery 操作当前项目 Wiki。

部分 host 刻意只支持一部分 local surface。Hermes 没有单独 local MCP、Skill 或 Shell Hook root；JetBrains local MCP 由 UI 管理。它们仍可以安装受支持的 local Instructions 或 preview Skills。

Permissions

Permission 属于各 host 私有能力，没有跨 Agent 标准。

Claude Code 提供官方 allow-list，可以窄授权 LWC read-only MCP tool。LWC 只安装对应 owned entry。其他 host 可能使用 trust prompt 或 UI-owned permission；adapter 会报告 user_managed，绝不会代表用户授予宽泛 tool 或 shell access。

检测与预览

lwc agent status --target auto --location global
lwc agent install --print-config codex --location global

Detection 只表示看起来安装了宿主，不等于获得修改文件的同意。Interactive install 会预选 detected target；--yes 接受检测结果与默认值，并不代表安装全部 target。

--print-config 完全不写文件，适合 managed environment 或安装前审核。

安装验收

对每个目标 target：

1. 在选定 location 执行 install；
2. 要求 adaptation=strong，并检查每个 capability mode；
3. 验证宿主加载 Skill 与 marker-bounded Instructions；
4. 真实调用一次 lifecycle Hook envelope，检查有界 readiness；
5. 初始化 MCP，确认只列出一个 lwc_explore，并执行只读 call；
6. 运行 refresh，确认无 drift 时 byte-idempotent；
7. 在隔离 host profile 测试 uninstall，确认 foreign content 被保留。

官方 cell 为 user_managed 或 unsupported 不代表 target 损坏。只有 adapter 误报边界、写入非官方 surface，或官方支持能力无法工作时才是缺陷。

官方来源策略

Agent host 的变化速度快于 LWC core Store。兼容性更新必须具备：

• 每条写入 path 或 format 对应的当前官方 host 文档；
• 带 source link 的 capability matrix 更新；
• global 与 local install/status/refresh/uninstall 测试；
• 条件允许时的真实 lifecycle 与 MCP host-level acceptance；
• adapter 内不存在 maintainer-local tool、path 或 file。

社区示例可以帮助发现缺口，但在没有官方证据时，不能授权新增集成格式。

不依赖私有环境

所有用户只需要：

• 一个位于 PATH 的兼容全局 lwc；
• Agent 官方目录与配置支持；
• local installation 所需的项目目录。

AMC、维护者 HOME 布局、私有 absolute binary variable 和复制的本地 plugin cache 都不是依赖。

路径、生命周期命令、ownership receipt、refresh 与 uninstall 详见 AgentTarget 安装与集成。