WorkBuddy

安装 UserPromptSubmit Hook、MCP 与 project-context Skill，验证 additionalContext 召回，并确认显式写入失败可见。

WorkBuddy 有独立的 setup / doctor 命令，但不在 setup select 与 doctor integrations 的一级支持的目录里。真实宿主进程端到端验证是 Not validated；仓库只有服务链测试。权限属于 Host-gated。托管 Skill 导出是 Unsupported。无正式最低 WorkBuddy 版本。

WorkBuddy 的接入面接近 Codex：短进程 UserPromptSubmit Hook 自动准备/采集，HTTP MCP 做显式 Memory 与 Handoff，内置 project-context Skill 绑定这两条路径。安装配置不会启动 Server，也不会打开 WorkBuddy。

完整安装步骤看 官方文档 的 Configure WorkBuddy 操作指南。这里验证 PowerContext 101 的可运行边界。

​

安装并激活

Hook 进程需要 Python 3.11 或更新版本在 PATH 上。先在一个终端启动 Server：

powercontext server run

在另一个终端安装 Hook、MCP 与 Skill：

powercontext setup workbuddy --source oceanbase/powercontext --ref master

powercontext doctor
powercontext doctor workbuddy

安装配置写入 WORKBUDDY_HOME（未设置时是 ~/.workbuddy）下的这些归属当前集成的路径，并在失败时回滚快照：

hooks/workbuddy_powercontext_hook.py
hooks/workbuddy_settings.py
hooks/prepared_context.py
hooks/powercontext_project_scope.py
settings.json
mcp.json
skills/project-context/

它会合并 UserPromptSubmit Hook，保留无关设置和其他 MCP server，并解析 Skill 里的命令 占位符。它不会启动 Server，也不会打开 WorkBuddy。

doctor workbuddy 检查 Hook 文件、设置是否注册 PowerContext Hook、mcp.json 是否有 powercontext server，以及归属当前集成的 Skill 是否还留着未解析 占位符。它不启动 WorkBuddy，不联系 Server，不测召回。doctor integrations 不会列出它。

装完后重启 WorkBuddy。每次提示词时，Hook 状态应显示 Syncing PowerContext。

​

配置默认值

Hook 读 POWERCONTEXT_WORKBUDDY_ 环境变量。MCP 条目使用同一套模板，由 WorkBuddy 从环境展开：

键	默认值	含义
MCP url	${POWERCONTEXT_WORKBUDDY_SERVER_URL:-http://127.0.0.1:8000}/mcp	安装配置写入 mcp.json 的模板
POWERCONTEXT_WORKBUDDY_SERVER_URL	http://127.0.0.1:8000	Hook 与 MCP 共用的 Server 基础
POWERCONTEXT_WORKBUDDY_AUTHORIZATION	未设置	完整 Bearer 请求头
POWERCONTEXT_WORKBUDDY_SCOPE_ID	未设置	显式 Scope；未设置则按 Workstream / Git / 路径推导
POWERCONTEXT_WORKBUDDY_CAPTURE_PROMPTS	true	采集当前用户提示词为 Source
POWERCONTEXT_WORKBUDDY_FLUSH_ON_CAPTURE	false	测试用：采集后等待刷新
POWERCONTEXT_WORKBUDDY_REQUEST_TIMEOUT_SECONDS	1.0	单次 HTTP 超时
POWERCONTEXT_WORKBUDDY_HTTP_BUDGET_SECONDS	4.0	一轮准备/采集总预算
POWERCONTEXT_WORKBUDDY_FLUSH_MAX_CALLS	4	刷新最多调用次数；允许 1–16
召回预算	8000	Hook 发给 prepare_context 的 max_bytes；没有对应环境变量
Hook 超时	10	WorkBuddy 外层 Hook 超时，单位秒

不要把令牌写进 mcp.json 或 Server URL。URL 不能带凭证、查询或片段；明文 HTTP 只接受本机回环地址。改环境变量后必须重启 WorkBuddy。当前工作不能落成 Source 时：

export POWERCONTEXT_WORKBUDDY_CAPTURE_PROMPTS=false

​

最小验证

先单独检查 Server：

powercontext doctor
powercontext ready
powercontext capabilities

再在 WorkBuddy 里显式保存学习路径那道题的答案：

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，不需要生成模型。WorkBuddy 应返回精确 Citation。

换一个新会话，在同一项目目录提问：

What should happen after the OpenAPI contract changes?

自动召回成功时，UserPromptSubmit 通过 hook-stdout additionalContext 注入有界 PreparedContext。内容带 Citation，并标成不可信历史证据。它只服务当前提示词，不会把助手最终响应采成 Source。

​

Scope 解析

WorkBuddy 与 Codex / Claude Code 共用同一套顺序和同一份绑定：

1. 非空的 POWERCONTEXT_WORKBUDDY_SCOPE_ID。
2. Git 私有 Workstream 绑定：.git/powercontext/codex-workspace.json。
3. 规范化后的 Git remote.origin.url，写成 git:...。
4. 项目根目录的 local:<sha256>。

这份绑定在 Git 目录里，不进工作树，也不会被提交。共享 Memory 需要同一个 Server，以及两边完全相同的 scope_id。

​

自动路径与显式工具

UserPromptSubmit
→ resolve Scope
→ prepare_context (max_bytes=8000)
→ validate powercontext.prepared-context.v1
→ additionalContext
→ independently capture the prompt

召回、采集与刷新独立 fail-open。外层 Hook 超时到 10 秒后，WorkBuddy 继续当前提示词。自动采集只保存提示词，不保存最终响应或 Task Outcome。

MCP 提供显式 Memory 与 Handoff。内置 Skill 把 交接、交接当前工作 或 handoff this work 当成一次持久 Handoff 的显式授权；只讨论设计或要求预览时，不得调用 handoff_current_work。

内置 Skill 不是托管 Skill 导出。WorkBuddy 也不是当前导出目标。

​

负向检查

• 停掉 Server 后再问普通编码问题。Hook 应 fail-open；WorkBuddy 继续。
• 停掉 Server 后再做显式 remember_memory。MCP 必须报告失败，不能假装写入成功。
• Server 认证已开启时去掉 POWERCONTEXT_WORKBUDDY_AUTHORIZATION。Hook fail-open 并写出 authentication_failed；MCP 不可用，但会话不中断。
• 把令牌写进 mcp.json。不要这样做；文件里只应保留环境变量模板。

​

当前限制

• 真实 WorkBuddy 宿主进程端到端验证是 Not validated。test_workbuddy_service_chain.py 只证明 Hook 与 MCP 能共用一份服务配置。
• WorkBuddy 不在一级支持的 bulk 目录里。setup select 和 doctor integrations 都不会列出它。
• 无正式最低 WorkBuddy 版本。
• 托管 Skill 导出是 Unsupported。
• 诊断是安装检查，不是召回或权限 UI 证明。

​

完成检查

• doctor workbuddy 看到 Hook、设置、MCP 和归属当前集成的 Skill。
• Server 健康状态、就绪状态、能力已单独检查。
• 新会话能从 additionalContext 召回你显式保存的 OpenAPI 决定，并看到 Citation。
• 自动召回失败时，普通任务仍继续。
• 显式 Memory 或 Handoff 失败时，WorkBuddy 把错误告诉你。
• 你没有把内置 Skill 当成托管导出。

下一页是 Agent Plugin。