> ## Documentation Index
> Fetch the complete documentation index at: https://powercontext.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Plugin

> 加载便携的 project-context Skill 与 MCP 配置，用显式 Memory 验证 Citation，不假装存在自动召回。

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

Agent Plugin 是一份便携包，给能加载 Agent Plugin Skill 和 MCP 配置的宿主使用。它指向正在运行的 PowerContext Server，不嵌入存储，不启动 Server，也不添加 MCP 工具。Memory、Handoff 和持久化仍由 Server 上已有的 MCP 工具负责。

完整加载步骤看 [官方文档](https://oceanbase.github.io/powercontext/) 的 Configure Agent Plugin 操作指南。这里验证 PowerContext 101 的可运行边界。

## 取得软件包并加载

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
git clone https://github.com/oceanbase/powercontext.git
cd powercontext

uv run powercontext server run
```

软件包根目录是：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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` 的软件包根目录：

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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` 是这份软件包的全部连接配置：

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "$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：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
powercontext doctor
powercontext ready
powercontext capabilities
```

Agent Plugin 没有专用的诊断命令。加载成功只表示宿主看见了 Skill 和 MCP 条目，不证明 Server 可达，也不证明召回。

在已加载软件包的对话里显式保存学习路径那道题的答案：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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` 提问：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 仓库时：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
git:github.com/owner/repository
```

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

## 没有自动路径

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 自己扩展能力](https://powercontext.mintlify.site/zh/common-agents/agent-self-extension.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.