Skip to content

README.zh.md

Latest commit

 

History

History
200 lines (138 loc) · 7.68 KB

README.zh.md

File metadata and controls

200 lines (138 loc) · 7.68 KB
Raw

PowerContext for DeepSeek Harness

English | 中文

DeepSeek Harness 插件：通过 HTTP 接入正在运行的 PowerContext Server，覆盖召回、记忆、交接、经验与技能。本仓库不嵌入存储、不启动 Server，也不 import Python 包。

该插件也已集成到 PowerContext 官方仓库（integrations/dsh/plugins/powercontext）。本独立仓库与官方内部插件会同步优化和更新。

dsh plugin --profile web add <path-or-tarball>

功能

插件按 OpenAPI 调用 Server 的 /v1/... 接口，不走 MCP。

每轮模型开口前自动：

  1. 召回：POST /v1/context/prepare，把有界上下文注入本轮（按不可信历史证据处理）。
  2. 捕获：POST /v1/sources/content，把当前用户输入存成 Content Source。

具名 pc_* 工具只暴露 Agent 可用的 Memory、交接、经验、技能和只读审核操作。写操作会先向用户做一次确认。审核变更仍走人类命令 /pc review；破坏性和管理类 OpenAPI 不会作为模型工具暴露。同时注册 skill project-context。Server 不可达时跳过召回，不阻断当前对话。

能力 工具 HTTP
记忆 pc_search pc_remember pc_memory_list pc_memory_get pc_memory_revise pc_memory_retire /v1/memory/*
上下文 pc_prepare_context pc_capture_source /v1/context/prepare、/v1/sources/content
交接 pc_handoff_activate pc_handoff_prepare pc_handoff_finalize pc_handoff_commit pc_handoff_continue /v1/handoff/*
经验 / 技能 pc_experience_generate pc_experience_get pc_skill_generate pc_skill_get /v1/experience/*、/v1/skill/*
审核 pc_review_list pc_review_get /v1/artifact-candidates/*

完整接口见 openapi/powercontext.yaml。

快速开始

需要同时运行 PowerContext Server 和 DeepSeek Harness。Server 和插件使用同一个 Git ref。

安装 Server

uv tool install "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
powercontext --version

若本地已有 PowerContext 源码，可用 uv run powercontext server run。

安装插件

先安装 DeepSeek Harness，并确保 web profile 可用（执行一次 dsh web 即可）。PowerContext 仓库里的插件目录是 integrations/dsh/plugins/powercontext。优先用 CLI，这样 ref 会对齐：

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

本地 checkout 同样可以：

powercontext setup dsh --source /path/to/powercontext

setup dsh 内部会执行 dsh plugin --profile web add。如果还没有这条命令，也可以自己加目录：

dsh plugin --profile web add /path/to/powercontext/integrations/dsh/plugins/powercontext

本仓库继续作为发布通道。GitHub Release 的 tarball 仍然可用：

dsh plugin --profile web add ./powercontext-dsh-0.0.4.tgz

若之前是用源码目录装的，先卸载再装 tarball。Windows 上把 link: 安装直接换成 tarball 会失败：pnpm 会去重建嵌套 node_modules 的 symlink。

改动 TypeScript 后需要 pnpm install、pnpm test、pnpm build，然后重启 dsh web。

可选确认：

powercontext doctor
powercontext doctor dsh
dsh --profile web --dump-config

doctor 检查 Server。doctor dsh 检查 dsh 是否在 PATH 上，以及插件 id 是否为 powercontext-dsh。

卸载：

dsh plugin --profile web remove powercontext-dsh

启动 Server

powercontext server run

默认监听 http://127.0.0.1:8000，无认证，数据在用户目录下的 SQLite（可用 POWERCONTEXT_HOME 覆盖）。

curl http://127.0.0.1:8000/health/live
curl http://127.0.0.1:8000/health/ready

live 必须成功。ready 在未配置推理模型时可以为 degraded。显式写入 Memory 不需要模型。

使用

保持 Server 运行，然后：

dsh web

像平时使用 Agent 一样打开项目、开始对话即可。插件会在后台自动召回上下文、保存用户输入；需要读写记忆、交接任务或生成经验 / 技能时，模型会调用对应的 pc_* 工具。

对话中可输入 /pc doctor 检查 Server 是否可达。

配置

环境变量优先于 patch 配置。密钥不要写进会被 --dump-config 打印的文件。

字段 环境变量 默认 含义
baseUrl POWERCONTEXT_DSH_BASE_URL http://127.0.0.1:8000 Server 根 URL，无尾斜杠
authorization POWERCONTEXT_DSH_AUTHORIZATION 空 完整 Bearer <token>
scopeId POWERCONTEXT_DSH_SCOPE_ID 空 覆盖自动推导的项目 scope
timeoutMs — 4000 召回 + 捕获的共享预算
requestTimeoutMs — 1000 单次 HTTP 超时
maxBytes — 8000 prepare_context 预算
capturePrompts POWERCONTEXT_DSH_CAPTURE_PROMPTS true 把用户输入存成 Source
flushOnCapture POWERCONTEXT_DSH_FLUSH_ON_CAPTURE false 捕获后立刻 flush

长期非密钥默认可写在 ~/.dsh/profiles/web/cordis.patch.yml。Harness 会整份替换该插件的 config，需要保留的项要一起写上：

- id: powercontext-dsh
  config:
    baseUrl: https://pc.example.com
    timeoutMs: 4000
    requestTimeoutMs: 1000
    maxBytes: 8000
    capturePrompts: true
    flushOnCapture: false

远程 Server

插件跑在 Harness 进程里，浏览器不直连 PowerContext。默认 Server 只绑 127.0.0.1。远程部署需要扩大监听范围并开启鉴权；对网络暴露前应在前面加 TLS。

export POWERCONTEXT_SERVER_HTTP_HOST=0.0.0.0
export POWERCONTEXT_SERVER_HTTP_PORT=8000
export POWERCONTEXT_SERVER_AUTH_ENABLED=true
export POWERCONTEXT_SERVER_AUTH_TOKEN=<long-random-secret>
powercontext server run

对外公布的地址应是实际访问的根，例如 https://pc.example.com，不要带尾斜杠，也不要带 /mcp。

export POWERCONTEXT_DSH_BASE_URL=https://pc.example.com
export POWERCONTEXT_DSH_AUTHORIZATION="Bearer <long-random-secret>"
dsh web

POWERCONTEXT_DSH_AUTHORIZATION 必须是完整的 Bearer <token>，与 Server 的 POWERCONTEXT_SERVER_AUTH_TOKEN 对应。token 只用环境变量，不要写进 patch 文件。

常用 Server 变量：

变量 作用
POWERCONTEXT_SERVER_HTTP_HOST / _PORT 监听地址
POWERCONTEXT_SERVER_AUTH_ENABLED / _TOKEN 静态 Bearer
POWERCONTEXT_HOME 数据目录
POWERCONTEXT_SERVER_RUNTIME_SCHEDULE_SECONDS 定时抽取间隔；不设则不跑抽取
POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL 抽取用的生成模型

开发

HTTP 操作表由 PowerContext 的 openapi/powercontext.yaml 生成。把 POWERCONTEXT_ROOT 或 POWERCONTEXT_OPENAPI 指到主仓库，再执行 pnpm gen。pnpm gen:check 会在 src/operations.generated.ts 过期时失败。

pnpm install
pnpm gen:check
pnpm test
pnpm test:e2e
pnpm build

pnpm test:e2e 会从 POWERCONTEXT_ROOT 启动本地 Server，并打通 liveness、readiness、remember、search、prepare、capture。它不启动 DeepSeek Harness，也不需要模型。

  • 推到 main / master：跑 pnpm test 和 pnpm build，并检查 lib/ 与生成表已提交。
  • Pull Request：跑 pnpm test 和 pnpm gen:check。
  • GitHub Release 需手动触发：Actions → Release → Run workflow，填写例如 0.1.0。产物是 powercontext-dsh-X.Y.Z.tgz。

许可证

Apache License 2.0