> ## 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.

# DeepSeek Harness

> 通过 agent/pre-step 中间件和原生 pc_* HTTP 工具接入 PowerContext。

> [!WARNING]
>
> 这是早期原生集成。插件软件包版本是 `0.0.2`，但 DSH 尚无正式最低宿主版本。完整的真实 `dsh web` 宿主进程与模型端到端验证为 **Not validated**。

DSH 使用宿主原生 Hook，不是 MCP 插件。自动召回与采集发生在 `agent/pre-step`；精选的 `pc_*` 工具直接调用 PowerContext HTTP API。

## 安装并检查配置

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
powercontext setup dsh --source oceanbase/powercontext --ref master
powercontext server run
powercontext doctor dsh
```

安装要求 `dsh` 位于 `PATH`，并且构建后的插件入口 `lib/index.js` 已存在。安装程序通过 `dsh plugin --profile web add` 添加插件目录。`powercontext doctor dsh` 读取 `dsh --profile web --dump-config`，寻找精确插件 ID `powercontext-dsh`。插件要求 Node.js 20 或更高版本。

这些检查只能证明配置存在，不能证明真实轮次已经跑通。它们不会启动 `dsh web`、触发 Hook 或显示权限界面。Node.js 要求和开发时使用的 Cordis 依赖，也不能当成正式最低 DSH 宿主版本。

## 跑通一次宿主请求

Server 启动后，再打开 DSH：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dsh web

# Run inside DSH
/pc doctor
/pc search authentication decisions
/pc remember Prefer contract tests before refactors
/pc flush
/pc review
```

普通召回不需要手动命令，直接发送提示词即可。`/pc` 用来查看 Scope 和端点；`/pc doctor` 可把插件配置问题与 Server 健康问题分开。人工命令还提供搜索、写入、刷新和 Candidate Review。Agent 则使用精选的 `pc_*` 工具。

宿主中的执行顺序如下：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
agent/pre-step
→ collect text from every message into the recall query
→ collect user-originated text into capture content
→ resolve workspace Scope
→ prepare context and capture Source independently
→ await next() exactly once
→ inspect the downstream decision
→ if kind is enter and context is ready, append one plugin message
→ otherwise return the downstream result unchanged
```

完整消息批次会参与召回，因为宿主与插件上下文可能影响查询。采集范围更窄：只有 `source.kind === "user"` 的文本才能成为 Source；全是插件消息的批次不会被误记成用户输入。

`next()` 的结果决定能否注入。召回在调用 `next()` 前完成，但只有下游返回 `kind: "enter"` 时，插件才追加上下文。拒绝、上下文缺失、校验失败或消息封装失败都会原样保留下游结果。插件不会为了挽救注入而第二次调用 `next()`。

## Scope

Scope 按以下顺序解析：

1. `POWERCONTEXT_DSH_SCOPE_ID` 或插件设置 `scopeId`；
2. 会话工作区的规范化 Git 远程仓库标识；
3. 根据工作区路径生成的稳定 SHA-256 标识。

DSH 没有 Codex 和 Claude Code 使用的 Git 私有 Workstream 绑定或选择器，也不会退回插件进程目录。会话没有 `cwd` 且未显式配置 Scope 时，自动路径会跳过，`/pc` 报告无 Scope 状态，工具返回稳定的 `unscoped`，并且不发出 HTTP 请求。这样可以避免无关 DSH 会话意外共享 Memory。

模型不能覆盖 Scope。插件会用运行时解析出的值替换调用载荷中的 `scope_id`。显式 Scope 应来自可信部署配置，而不是模型输入。

## 注入、采集与刷新

PreparedContext 注入前必须通过精确的 v1 schema、状态、整数字节数、UTF-8 字节数和配置大小检查。默认上限是 8,000 字节，可配置范围为 512–32,768 字节。注入消息会标记为宿主提供的不可信历史证据，只服务当前模型调用，也不会再次作为用户内容被采集。

采集写入具有确定性 `dsh-user-prompt:` ID 的 Source，并保留 DSH 会话与轮次来源信息。召回失败不妨碍采集，采集失败也不会丢弃已经有效的 PreparedContext。超过 200,000 字符的内容会跳过；设置 `POWERCONTEXT_DSH_CAPTURE_PROMPTS=false` 可以关闭采集。

过滤器还会跳过包含 `sk-`、`api_key` 或 `BEGIN PRIVATE` 的文本。这只是窄范围保护，不是完整的敏感信息检测。提示词不应持久化时，请直接关闭采集。

自动刷新默认关闭。启用 `flushOnCapture` 后，正数 Source 位置最多触发 `flushMaxCalls` 次刷新，并在 `current_cursor >= position` 时提前结束。`/pc flush` 是显式人工路径。游标始终追不上时，循环会在上限处停止，但这不能证明 Source 已处理。采集日志成功也不等于 Memory 已生成：处理可能产生 Candidate，Review 可能提交，也可能保持无变更。

## 工具与权限

模型范围包含 19 个精选的原生 HTTP 工具。它们覆盖 Memory、准备与采集、低层 Handoff、Experience/Skill 的生成和读取，以及 Candidate 的只读列出与读取。

以下能力没有进入模型范围，状态为 **Unsupported**：通用操作调用、危险或管理员操作、Candidate 批准/拒绝/修订，以及高层 `create_work_contract`、`handoff_current_work`、`acknowledge_handoff` 和 `record_task_outcome`。相关 HTTP 操作可能存在，但不会因此自动成为 DSH 工具。

读取工具通过 `tools/pre-execute` 后继续执行。Memory 写入、显式 Source 采集、Handoff 激活或提交、Experience/Skill 生成等指定修改，会先返回 `ask`。DSH 负责权限界面和允许/拒绝决定，所以这些修改属于 **Host-gated**。单元测试已经证明 `ask` 分类；真实宿主中的界面与拒绝路径仍是 **Not validated**。

Candidate Review 保持人工控制。`/pc review approve` 与 `/pc review reject` 都要求 Candidate 的预期版本；`/pc` 不提供 Candidate 修订。生成 Experience 或 Skill Candidate 只是另一类受权限控制的修改，不等于批准。

## 失败语义与负向验证

自动准备、校验、采集、可选刷新和消息封装都采用 fail-open。HTTP 客户端将响应限制在 1 MiB，拒绝重定向，取消超时请求，并把传输失败规范化为稳定的不可用结果。步骤前总预算默认四秒，单个请求默认一秒。这些失败不能替换下游 Agent 结果。

显式持久操作不同。权限拒绝和 Server 错误必须可见，不能包装成成功。缺失 `cwd` 是无 Scope，不是 Memory 空结果。

升级 DSH 或插件时，至少验证：停止 Server 后普通提示词继续而显式写入失败；召回可读取完整消息批次但采集只保存用户文本；非 `enter` 下游结果不会追加插件消息；无 Scope 时不使用插件进程目录；未知 PreparedContext 字段、错误字节数、超限响应体、重定向和慢响应都不注入；敏感标记触发采集跳过；刷新游标落后时循环有界；读取直接执行而指定修改先返回 `ask`；模型工具中没有 Candidate 决策或通用危险操作。

当前证据边界如下：

| 状态 | 能力与影响 |
| - | - |
| **Unsupported** | 插件不使用 MCP；不自动采集助手最终响应或 Task Outcome；没有 Codex/Claude 风格 Workstream 绑定；模型没有通用、危险、管理员或 Candidate 决策工具；有界自动刷新不保证游标最终追上 |
| **Not validated** | 正式最低 DSH 版本；完整真实 `dsh web` 模型端到端验证；真实权限界面和拒绝行为；真实宿主的非 `enter` 抑制与游标落后刷新行为 |
| **Host-gated** | 指定持久修改先返回 `ask`，最终交互与决定由 DSH 控制 |

`test_dsh_http_chain.py` 验证关闭 MCP 后的公开 Client/Server HTTP 契约；Cordis 测试覆盖插件对实时 Server 的调用。两者都没有启动真实 DSH 宿主。

## 配置默认值

`timeoutMs`、`requestTimeoutMs`、`maxBytes` 和 `flushMaxCalls` 是插件局部设置，不是环境变量。

| 键 | 默认值 | 含义 |
| - | - | - |
| `POWERCONTEXT_DSH_BASE_URL` | `http://127.0.0.1:8000` | 正在运行的 Server |
| `POWERCONTEXT_DSH_SCOPE_ID` | 未设置 | 显式 Scope；会话没有工作区 `cwd` 时必须设置 |
| `POWERCONTEXT_DSH_AUTHORIZATION` | 未设置 | 完整 Authorization 请求头 |
| `POWERCONTEXT_DSH_CAPTURE_PROMPTS` | `true` | 采集源自用户的提示词 |
| `POWERCONTEXT_DSH_FLUSH_ON_CAPTURE` | `false` | 测试用刷新 |
| `maxBytes` | `8000` | 召回预算，范围 `512–32768` |
| `timeoutMs` | `4000` | 步骤前总预算 |
| `requestTimeoutMs` | `1000` | 单次 HTTP 超时 |

不要把令牌写进局部设置或 Server URL。当前工作不应成为 Source 时：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export POWERCONTEXT_DSH_CAPTURE_PROMPTS=false
dsh web
```

## 完成统一验证

先在固定 Scope 中用 `pc_remember` 保存“修改 OpenAPI 契约后，重新生成并检查客户端”的决定。确认 `tools/pre-execute` 返回 `ask`，再取得 Citation。发送一个会进入模型的新请求并重复问题；召回内容必须带 Citation，只能出现在 `enter` 之后、以 `PowerContext host-supplied context` 开头的插件消息中。

随后停止 Server。普通问题应继续，非 `enter` 下游结果不得被替换。再次运行 `pc_remember` 时，失败必须可见，不能伪装成空结果或成功。

只有以下结果都能直接观察时，才算完成：安装诊断找到精确插件 ID；Node.js 和目标 `web` 配置正确；`/pc doctor` 能访问 Server；Scope 缺失不会发出 HTTP 请求；召回与采集范围不同；`next()` 只调用一次；注入通过 schema/字节校验且只发生在 `enter`；刷新有上限且不虚报 Memory；指定修改触发宿主 `ask`；上述 Unsupported、Not validated 与 Host-gated 边界保持分开。

下一页是 [OpenCode](https://powercontext.mintlify.site/zh/coding-agents/opencode.md)。


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