前言¶
DeepSeek Harness（DSH）自带一套智能体循环（dsh-agent-loop），会话、Web UI、预设与权限表面都由 Harness 统一管理。若你已经在使用 pi coding agent，并希望保留 pi 自身的提示词、工具、压缩策略与模型路由，同时又想留在 DSH 的会话与界面里工作，就需要把「壳」和「循环」拆开：DSH 管会话与展示，pi 管执行逻辑。
dsh-inline-pi-agent 是 Komorebi-Nine 维护的 DSH 工作流类插件（社区目录：SkillHub 条目）。它以 profile bundle 的形式，用无头子进程 pi --mode rpc 替换内置的 dsh-agent-loop，在不动磁盘上会话数据的前提下，把 pi 的 RPC 事件翻译成 DSH 可持久化的事件流。
这是什么¶
插件全名 dsh-inline-pi-agent（npm 包版本 0.1.0，MIT 许可证）。定位一句话：在 DSH 里跑 pi 的智能体循环，而不是 DSH 原生循环。
DSH 仍负责会话、Web UI、预设与权限相关 UI；pi 负责自己的 prompt、tools、compaction 与 model routing。二者通过 RPC 桥接，不是把 pi 再包装成另一种 DSH 工具。
核心功能¶
下列能力均来自插件 README 的「What works」说明，安装后可按同一套行为预期使用。
流式输出与工具卡片¶
pi 的 RPC 事件会被转换成 DSH 的 durable session 事件，以及 agent/assistant-stream 帧。流式文本、工具卡片展示、停止按钮在 DSH 侧重放，用户体验与原生循环接近。
断点续聊（Resume）¶
每次 create/resume 时，插件会从 DSH 的 event log 重建 pi 的 session 文件。Harness 重启后，pi 侧上下文仍能接上完整对话。
模型选择器¶
插件调用 pi --mode rpc get_available_models，把 pi 的模型目录注册进 DSH 的 LLM registry。选择器列出的是 pi 实际能跑的模型；选中后通过 set_model 转发给 pi。
中途转向与排队跟进（Steering / Follow-ups）¶
运行中的 steer 会转发给 pi，接受后即 claim。排队的 follow-up 按顺序作为独立 turn 执行。
交还内置循环（Hand-back）¶
由 pi 驱动的会话仍可被内置 dsh-agent-loop resume：每个请求按 DSH 标准事件词汇记录，包含声明 registry 工具模式的 request/header，便于从 pi 切回原生循环。
安装与启用¶
环境要求¶
- DSH：
0.2.2-rc.1或兼容版本（package.json中engines.dsh为^0.2.2-rc.1）。 pi可执行文件在PATH上，或在配置里显式指定piPath。
从 GitHub 安装¶
在已配置好 DSH CLI 的机器上执行：
dsh plugin --profile web add github:Komorebi-Nine/dsh-inline-pi-agent
bundle 层会禁用 agent-loop、DSH 侧的 compaction 与 tool-result pruning，并插入 pi-agent 行。之后重启 dsh web，或依赖 profile 的 patch 热加载（官方文档建议以重启为准，见下文「回滚」）。
本地目录安装¶
若你已有插件源码目录（无需在本文中 git clone），可用 link 方式挂载：
dsh plugin --profile web add link:/absolute/path/to/dsh-inline-pi-agent
配置项¶
在 profile patch 里覆盖 pi-agent 的 config 即可。常用字段如下（默认值以 README 为准）：
| key | default | 含义 |
|---|---|---|
piPath |
pi |
pi 可执行路径；Windows 可为 .cmd/.exe 或通过 cmd.exe 解析的名称。 |
model |
空 | 初始推送给 pi 的路由，例如 deepseek/deepseek-flash。 |
models |
空 | DSH 路由名 → pi 路由名的映射（两套目录命名不一致时用）。 |
catalog |
true |
是否把 pi 模型目录注册进 DSH，供选择器使用。 |
requestHeader |
true |
是否记录每步的 request/header 与 request/context（token 统计与交还内置循环需要）。 |
streamPaceMs |
16 |
流式文本揭示节拍（8–200 ms）。 |
streamCatchUpFrames |
6 |
积压文本应在多少 tick 内追平。 |
streamMaxCharsPerFrame |
64 |
单帧最多揭示字符数。 |
piSessionDir |
~/.dsh/pi-sessions |
重建的 pi session 快照写入目录。 |
debug |
false |
协议与生命周期诊断日志。 |
Windows 上指定 pi 的示例：
- id: pi-agent
config:
piPath: 'C:/Users/me/.pi/agent/bin/pi.cmd'
若曾把部署默认模型改成 pi 路由，在停用 bundle 前应改回内置路由（pi 提供方仅在 bundle 加载时存在）：
- id: agent-default-model
config: { provider: deepseek-official, model: deepseek-flash }
典型用法与开发自测¶
日常使用时：安装并重启 dsh web 后，在 Web profile 下新建或恢复会话，即走 pi RPC 循环；模型列表来自 pi 目录；需要中途改方向时使用 DSH 提供的 steer / follow-up 能力（由插件转发）。
插件仓库提供独立 smoke 脚本（不依赖 DSH 服务进程），用于验证文本、工具、多轮、中止、dispose、resume、steer、followup、token 统计与模型目录等路径：
node scripts/smoke.mjs text
node scripts/smoke.mjs tool
node scripts/smoke.mjs resume
接口与事件契约见仓库内 CONTRACT.md。
适用场景与限制¶
适合谁¶
- 已经在用 pi，希望会话、UI、预设仍落在 DSH 里。
- 需要 pi 的模型路由与工具栈，但又想利用 DSH 的事件日志与 resume 语义。
- 偶尔要把会话从 pi 交还给内置
dsh-agent-loop（依赖requestHeader等记录）。
务必注意¶
- 权限与沙箱：pi 执行自己的工具，DSH 的沙箱、审批流与 permission preset 不作用于 pi 的工具调用。
- Hooks：插件不分发
agent/pre-step；依赖该钩子的能力（时间上下文注入、逐步 flush、plan-mode 旁白等）在 pi 会话中不会运行。 - 上下文统计：
contextBreakdown.toolsTokens描述的是 DSH 工具 registry，而非 pi 的工具块；上下文压力以提供方上报的 usage 为准。 - 安装前审查：插件以当前
dsh进程权限运行。安装前应阅读源码与 MIT 许可证，确认符合你的安全与合规要求；社区目录 SkillHub 为独立站点，与 DeepSeek / 幻方无官方从属关系。
回滚¶
在 Settings → Plugins 中禁用 bundle，或移除包；agent-loop 会恢复，已有会话在磁盘上不受影响。切换启用状态后应重启 dsh web：运行中的 loader 无法原子替换 agent factory，半加载状态可能导致会话列表为空（数据仍在磁盘上）。
结尾¶
dsh-inline-pi-agent 把 DSH 的会话与界面层和 pi 的执行循环拆开又接上：保留 pi 的 prompt、工具与路由，同时保留 DSH 的流式展示、resume 与模型选择器集成。需要原生 DSH 沙箱与 agent/pre-step 钩子时，应继续使用内置循环或停用本 bundle。
