Agent Plugin - PowerContext 101

Agent Plugin 没有专用的安装配置或诊断命令。这个软件包不实现自动召回、采集或运行时。仓库有软件包契约测试；真实宿主进程端到端验证是 Not validated。权限属于 Host-gated。托管 Skill 导出是 Unsupported。

Agent Plugin 是一份便携包，给能加载 Agent Plugin Skill 和 MCP 配置的宿主使用。它指向正在运行的 PowerContext Server，不嵌入存储，不启动 Server，也不添加 MCP 工具。Memory、Handoff 和持久化仍由 Server 上已有的 MCP 工具负责。完整加载步骤看官方文档的 Configure Agent Plugin 操作指南。这里验证 PowerContext 101 的可运行边界。

取得软件包并加载

先克隆含有集成软件包的仓库，再单独启动 Server：

git clone https://github.com/oceanbase/powercontext.git
cd powercontext

uv run powercontext server run

软件包根目录是：

integrations/agent-plugin/powercontext/

它包含：

文件	作用
`plugin.json`	Agent Plugins 1.0.0 元数据；`name` 是 `powercontext`，`version` 是 `0.1.0`
`mcp.json`	Streamable HTTP 配置，指向 `http://127.0.0.1:8000/mcp`
`skills/project-context/SKILL.md`	显式 Memory 与 Handoff 的可复用说明

VS Code 用 chat.pluginLocations 加载本地目录。把路径换成你自己的仓库检出，指向含 plugin.json 的软件包根目录：

{
  "chat.plugins.enabled": true,
  "chat.pluginLocations": {
    "/absolute/path/to/cloned/powercontext/integrations/agent-plugin/powercontext": true
  }
}

Reload VS Code。确认 Agent Plugins 视图里出现 PowerContext，并且对话能看到 project-context Skill 和 powercontext MCP server。

配置边界

mcp.json 是这份软件包的全部连接配置：

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "powercontext": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Agent Plugins 1.0.0 没有为远程 MCP 定义可移植的 credential-reference 字段。签入的 mcp.json 因此不含 static 凭证、令牌占位符或 POWERCONTEXT_* 变量。需要鉴权时，在加载它的宿主或客户端里配置，不要改这份文件去塞 Bearer 令牌。这个软件包没有宿主专用环境变量表，也没有 setup 写入的归属当前集成的路径。

最小验证

先单独检查 Server：

powercontext doctor
powercontext ready
powercontext capabilities

Agent Plugin 没有专用的诊断命令。加载成功只表示宿主看见了 Skill 和 MCP 条目，不证明 Server 可达，也不证明召回。在已加载软件包的对话里显式保存学习路径那道题的答案：

Use PowerContext to remember this decision:
after changing the OpenAPI contract, regenerate the client and inspect the diff.
Return the Memory Citation. Do not store secrets.

这是 MCP remember_memory，不需要生成模型。宿主应返回精确 Citation。换一个请求，使用同一个 scope_id 提问：

What should happen after the OpenAPI contract changes?

这里没有自动注入通道。模型必须调用 search_memory（或 get_memory_entry）才能读到刚才的 Memory。召回内容带 Citation，并且只是不可信历史证据。

Scope 解析

这份 Skill 不读 .git/powercontext/codex-workspace.json，也不从 Git 远程自动推导 Scope。第一次 PowerContext 调用前，为当前任务选定一个 scope_id，并在该任务的所有 Memory / Handoff 调用中复用。优先使用跨兼容宿主稳定的项目标识。已知 GitHub 仓库时：

git:github.com/owner/repository

用户或宿主给出显式 Scope 时，用那个值。Scope 不明确时，先问再写。

没有自动路径

compatible host loads plugin.json + mcp.json + Skill
→ you start the Server separately
→ chat may use MCP tools
→ no prepare_context on prompt
→ no Source capture

自动召回 / 采集 / 刷新在这里是 Unsupported，不是 fail-open 的辅助路径。MCP 不可用时，Skill 要求说一次然后继续任务：不要反复重试，不要编造已恢复的上下文，也不要声称 Memory 或 Handoff 已成功。显式 Memory 与 Handoff 仍走 Server MCP。Skill 使用无模型的 handoff_current_work，再让接收方用 continue_handoff 且 selection: "prepared"。它不调用 activate_handoff 或 finalize_handoff。内置 Skill 不是托管 Skill 导出。Agent Plugin 也不是当前导出目标。

负向检查

停掉 Server 后再调用 remember_memory。MCP 必须报告失败，不能假装写入成功。
停掉 Server 后再问普通问题。没有自动召回可失败；宿主应继续，并在需要 PowerContext 时说明 MCP 不可用。
打开签入的 mcp.json。它必须没有 headers、令牌或 POWERCONTEXT_*。
把 chat.pluginLocations 指到仓库根而不是软件包根目录。宿主不应把它当成有效 Agent Plugin。

当前限制

没有安装配置 / 诊断命令。
真实 VS Code 或其他 Agent Plugin 宿主的宿主进程端到端验证是 Not validated。tests/agent_plugin/test_contract.py 只检查软件包与文档契约。
自动召回、采集与刷新是 Unsupported。
托管 Skill 导出是 Unsupported。
鉴权不可移植；1.0.0 模式没有远程 MCP 的 credential-reference。

完成检查

软件包根目录同时包含 plugin.json、mcp.json 和 skills/project-context/SKILL.md。
宿主能看到 project-context Skill 和 powercontext MCP server。
Server 健康状态、就绪状态、能力已单独检查。
显式 remember_memory 返回 OpenAPI 决定的 Citation。
下一次提问通过 MCP 搜索/读取找到它，而不是指望自动注入。
MCP 失败可见；你没有把内置 Skill 当成托管导出。

下一页是让 Agent 自己扩展能力。

​取得软件包并加载

​配置边界

​最小验证

​Scope 解析

​没有自动路径

​负向检查

​当前限制

​完成检查

取得软件包并加载

配置边界

最小验证

Scope 解析

没有自动路径

负向检查

当前限制

完成检查