持久侦察员 jooxee/dsh-scout

dsh-scout

dsh-scout 是一个可移植的 Agent Skill 和本地命令接口，用于将仓库工作委派给 DeepSeek Harness agent。Codex、Claude Code、OpenCode、Pi、Oh My Pi、Cursor 以及其他具备 shell 能力的本地 harness 都可以使用同一运行时。

它在相关轮次之间保持一个写入者会话存活，以便模型能够复用对话上下文和提供方 KV 缓存。可选的第二个 scout 以只读方式挂载项目根目录运行。

它提供什么

- 一个持久的全权限写入者；
- 一个可选的只读 scout，与写入者并行；
- 用于 Issue、OpenSpec 变更或拉取请求的稳定会话键；
- 来自 DSH 会话存储的上下文压力跟踪；
- 250,000 token 的软轮换警告；
- 在 400,000 token 时自动交接和轮换；
- 强制的一写入者/一读取者并发锁；
- 持久、仅追加的生命周期监督事件，并带有基于游标的监视器；
- 控制器重启后，对每个先前运行的会话执行一次恢复 turn_failed；
- 控制器派生的 Git 事实（提示前/提示后）以及每个已完成轮次的待验证标记，因此 DSH 完成永远不会被视为证明。

要求

- 带有 Python 3.10 或更新版本的 Linux；
- 带有 sdk profile 的 DeepSeek Harness；
- 暴露 node:util.parseEnv 的 Node 22 或更新版本；
- 用于只读 scout 的 bubblewrap（bwrap）；
- 已配置的 DSH 提供方和模型。

启动器遵循绝对路径 DSH_SCOUT_NODE=/path/to/bin/node 覆盖，否则使用兼容的 PATH Node，然后检查 ${NVM_DIR:-$HOME/.nvm} 下已安装的 NVM 版本（最新数字版本优先）。无效的显式覆盖会失败且不会回退。它仅将所选目录前置到其继承的进程环境中；它从不安装 Node 或加载 shell 配置文件。缺少先决条件会在控制器启动前产生安全错误。现有守护进程保留其原始环境。运行时选择不会重试失败的会话：其现有的显式 --new-session 恢复规则仍然适用。

CLI 兼容性默认值使用 opencode-go 和 glm-5.3-flash。在付费派发之前，编排器必须披露并明确选择用户批准的提供方/模型。默认值和历史成功运行不构成批准；未经同意不得替换失败的路由。此指令契约不是运行时计费限制。OpenCode Go 还需要在 SDK profile 中保持稳定的请求亲和性：

dsh plugin --profile sdk add @gausszhou/dsh-opencode-session-id

安装

克隆仓库并将 skill 包安装到应使用它的宿主中：

git clone https://github.com/jooxee/dsh-scout.git
cd dsh-scout
./scripts/install.sh # Codex 预设（默认） ./scripts/install.sh --host claude-code # Claude Code ./scripts/install.sh --host opencode # OpenCode（遵循 XDG_CONFIG_HOME）bash ./scripts/install.sh --host pi # Pi Agent Skills ./scripts/install.sh --host omp # Oh My Pi ./scripts/install.sh --host cursor # Cursor ./scripts/install.sh --destination /path/to/dsh-scout # 任意自定义根目录

在没有 --host 或 --destination 的情况下，安装程序会使用位于 ${CODEX_HOME:-$HOME/.codex}/skills/dsh-scout 下的 Codex 预设。--host 和 --destination 互斥。每个安装路径都要求最终目录的基名为 dsh-scout，以便可移植发现保持一致。使用 --force 覆盖同一目标位置上的现有安装；若不使用它，现有安装会以退出状态 17 中止。安装程序从不编辑宿主设置或全局宿主指令；它只复制技能包、运行时脚本以及随附的参考文档。运行 ./scripts/install.sh --help 查看完整选项列表。

支持的宿主预设集合为：

| 宿主预设 | 技能目录 |
| codex | ${CODEX_HOME:-$HOME/.codex}/skills/dsh-scout |
| claude-code | $HOME/.claude/skills/dsh-scout |
| opencode | ${XDG_CONFIG_HOME:-$HOME/.config}/opencode/skills/dsh-scout |
| pi | $HOME/.pi/agent/skills/dsh-scout |
| omp | $HOME/.omp/agent/skills/dsh-scout |
| cursor | $HOME/.cursor/skills/dsh-scout |

对于需要非默认目标位置的宿主，请使用 --destination PATH。有关兼容性矩阵、CLI 回退以及已验证的限制，请参见 docs/integrations.md。

当你希望代理自动使用该技能时，请在你的全局或项目 AGENTS.md 中添加一条简短说明： markdown 对于受益于 DSH scout 的仓库工作，请阅读已安装的 dsh-scout SKILL.md。在派发前披露确切的 provider/model，并且仅使用用户批准的路线。使用一个写入者和至多一个 OS 隔离的读取者；监督完成情况并独立验证交接。

将 DSH_SCOUT_HOME 设置为包含已加载 SKILL.md 的绝对目录，或直接使用绝对启动器路径。这是一个 shell 便利变量，不会由安装自动设置。启动器从其自身位置解析其依赖项；--cwd 仍然是确切的目标仓库目录。

运行

在目标仓库之外创建第一个自包含的委派数据包，然后使用相同的参数运行特定于宿主的启动器： bash
DSH_SCOUT_HOME=/absolute/installed/skill/dsh-scout
export DSH_SCOUT_PROVIDER=approved-provider
export DSH_SCOUT_MODEL=approved-model
"${DSH_SCOUT_HOME}/scripts/run-dsh-agent.sh" \
--mode write \
--cwd /absolute/path/to/project \
--session-key project:issue-123:writer \
--prompt-file /absolute/path/to/prompt.txt
将示例提供商/模型替换为已批准的路径。为后续命令和 UI 命令复用同一环境。主机必须保留相同的 HOME 和 CODEX_HOME，以共享规范状态标识。默认套接字独立于 XDG_RUNTIME_DIR；即使使用自定义套接字，请求锁和所有者锁也位于状态旁边。历史 .codex 状态目录是兼容性位置，而不是对 Codex 的依赖。

在同一 Issue、OpenSpec 变更或拉取请求下的后续轮次中复用同一会话键。当目标或权限发生变化时，使用新键。添加 --rotate 以创建交接并立即在新会话中继续。

可选读取器使用相同的命令，并带有 --mode read 以及诸如 project:issue-123:reader 的键。

写入器和读取器轮次没有执行时间限制。保持启动器连接，直到完成或出现需要操作的结果；关闭它会请求取消，并可能丢失实时会话。连接启动和取消确认具有有界的故障检测窗口。监督监视器可以使用可选超时来进行自身的等待；该超时不会影响 Scout。

对于简短的当前状态检查，使用 scripts/scout_status.py --mode read --session-key project:issue-123:reader。它会读取本地状态和进程标识，而不会启动 DSH 或使用模型令牌。默认的单行 JSON 报告生命周期和存活状态；--details 添加有界诊断信息。使用 scripts/watch_dsh_events.py --terminal-only 等待终端事件，而不是反复打开实时记录。running 快照确认匹配的进程和已记录的轮次，而不是模型进度。

显示 scout UI URL

在默认 Web 后端上，提示响应包含无令牌的 UI 源。在轮次之前或期间，使用相同的模式、cwd、提供商和模型，通过 --show-ui-url 获取经过身份验证的启动 URL： bash
"${DSH_SCOUT_HOME}/scripts/run-dsh-agent.sh" \
--mode write --cwd /absolute/path/to/project --show-ui-url

只有 --show-ui-url 会打印经过身份验证的启动 URL。正常轮次输出会打印无令牌的源。将经过身份验证的 URL 排除在保存的日志和 GitHub 交接之外；状态和监督事件不包含启动令牌。

实时 UI 可见性 — 限制

scout 运行时会将其自身轮次的事件流式传输到连接到其 URL 的任何浏览器标签页（工具活动、助手文本、完成）。同一个浏览器标签页也可能在第一个轮次之前就已打开。进程本地传递意味着外部的、已在运行的 DSH 主机（例如操作员的 127.0.0.1:3080）不会显示实时 scout 轮次；文档会引导操作员改为使用 scout 运行时的 URL。不要从外部主机激活活动的 scout 会话；DSH 使用会话租约来拒绝第二个所有者，而此技能从不尝试这样做。

配置

| 变量 | 默认值 | 用途 |
| DSH_SCOUT_BACKEND | web | web（scout 自有的 dsh web 运行时，实时 UI）或 sdk（旧版分离式 SDK，需显式选择启用） |
| DSH_SCOUT_WEB_PORT | 临时端口 | scout web 运行时的绑定端口；回环主机固定 |
| DSH_SCOUT_PROVIDER | opencode-go | DSH 提供方路由 |
| DSH_SCOUT_MODEL | glm-5.3-flash | 模型 ID |
| DSH_SCOUT_SOFT_CONTEXT_TOKENS | 250000 | 在一致的边界处警告并轮换 |
| DSH_SCOUT_HARD_CONTEXT_TOKENS | 400000 | 自动交接并轮换 |
| DSH_SCOUT_READONLY_ROOTS | 常见项目根目录 | 以冒号分隔的根目录，以只读方式挂载给读取器 |
| CODEX_HOME | ~/.codex | 技能安装与控制器状态根目录 |
| DSH_HOME | ~/.dsh | DSH 配置与会话存储 |

软上下文阈值必须低于硬阈值。DSH_SCOUT_BACKEND 仅接受 web 或 sdk；任何其他值都会在启动任何进程之前被拒绝。

持久化的工作方式

默认执行后端是每个模式由 scout 管理的一个普通 dsh web 运行时（Issue #6）：控制器启动一个 dsh web 进程，使用回环主机、临时端口和 --no-open，并通过其支持的 Remote API（workspace/create、session/create、session/rename、session/prompt、session/cancel）以及 /api/remote.mux 跟随流来驱动轮次。由于执行和 UI 事件位于同一个所有者进程中，scout 运行时上已打开的浏览器标签页无需刷新即可显示实时的工具/助手流式输出和完成情况。

旧版 DSH SDK 后端（DSH_SCOUT_BACKEND=sdk）仍可作为显式选择启用，供偏好旧版分离式 SDK 模型的调用方使用；两个方向都没有隐藏回退——启动失败会显式地使守护进程或轮次失败。

在活动会话中，请求历史保持仅追加，这保留了提供方可复用的 KV 缓存前缀。缓存复用减少了重复计算；它不会减少上下文窗口占用。上下文阈值使用 DSH 持久化的 contextPressure.pressureTokens，而不是累计计费使用量。

如果在失败、运行时死亡或控制器重启后活动上下文丢失，下一个提示会在派发之前被拒绝。在显式接受该丢失后，为同一 key 提供 --new-session 和一个完整的新数据包。健康会话会拒绝此标志；使用正常的后续消息以保留历史，或使用 --rotate 进行实时交接。失败的提示绝不会自动重试。保留会话历史支持前缀复用，但无法保证提供方的缓存命中率。

从基于 XDG 的寻址升级：先让所有旧轮次结束，并有意停止旧控制器。状态中活动的旧版 PID 会在状态写入或运行时清理之前阻止新控制器。启动器绝不会自动终止 PID 来解决此迁移问题。现有正在运行的安装不会通过 Git push 升级。
控制器状态文件在派发提示之前记录会话 ID、status: running、活动轮次和开始时间。这使得即使模型尚未返回最终响应，也能将较长的首轮次与停滞或缺失的控制器区分开来。在 Web 后端上，状态还会记录运行时 origin/pid/generation——绝不记录启动令牌。

在控制器重启时，任何以 status: running 持久化的会话都会恰好发出一个恢复 turn_failed 监督事件，标识该次重启；它绝不会声称有 DSH 结果。事件流序列在最大的有效先前记录之上继续。

监督事件

每个委派的轮次还会向每个控制器模式的一个仅追加、用户私有（0600）的 JSONL 流发出生命周期事件，位于 $CODEX_HOME/state/dsh-scout/events/.events.jsonl。事件携带 version、sequence、event_id、kind、mode、session_key、session_id、turn、emitted_at，并且——对于终态类型——携带 verification_state: "pending"。类型：

- turn_started — 在派发之前，状态已被持久标记为运行中；
- turn_completed — DSH 在产生结果后变为空闲；
- turn_failed — 派发、SDK 执行、传输或代理执行失败（或控制器在会话运行期间重启）；
- action_required — scout 以有界终态操作交接结束其轮次。

每个终态事件仅在其对应状态（idle/error，加上仓库事实）被持久化之后才追加。该流是游标权威，因此订阅者不会错过快速的开始到终态转换；状态文件还记录最新事件（last_event）作为便利。事件追加失败绝不会被隐藏：提示请求会失败，并且状态会记录一个有界的监督错误。

使用独立监视器订阅： bash
"${DSH_SCOUT_HOME}/scripts/watch_dsh_events.py" \
--mode write \
--session-key repo:issue-123:writer \
--after-sequence 0 \
--terminal-only

--after-sequence 是排他游标；--terminal-only 将事件限制为终态类型；--state-root 为测试覆盖控制器状态根。监视器默认无限期等待。可选的 --timeout-seconds 仅将监视器限制为最多 86,400 秒（一天）；非有限、非正或超过最大值的值会在等待之前被拒绝。监视器将第一个匹配事件作为恰好一个 JSON 对象打印，并以 0 退出。其可选超时以代码 42 退出且无 stdout，而不取消 Scout。损坏或截断的最终 JSONL 记录会被忽略，直到写入者完成它；较早的有效事件仍可读取。投递为至少一次：持久化已处理的最大序列，并按 event_id 去重。事件绝不包含提示或响应正文、文件内容或机密。
阻塞式启动器会将发出的生命周期事件（event=... kind=... sequence=...）打印到 stderr，以便调用方看到最终结果。当提示词运行时，控制器会监视启动器的 Unix 套接字；关闭启动器会取消当前活动轮次，并防止出现孤立的写入者。启动器断开连接使用 client-disconnected，其他提示词失败使用 prompt-failed。当操作信封有效且为终止状态时，控制块仅在监督事件内部传递；启动器打印清理后的助手文本，超大的有效值会被裁剪到其文档规定的边界。格式错误或非终止状态的信封则原样保留为普通 stdout。会话密钥最多限制为 200 个字符，并且在提示词输入和监视器中都会被拒绝，而绝不会被裁剪。

在 Web 后端上，取消成功需要确认的 turn/end（或已证明空闲且不可能存在写入者）。当取消被拒绝、确认窗口过期、传输中断或所有权不明确时，所拥有的运行时进程组会在追加终止性 turn_failed 事件之前被终止，并且新的运行时/会话需要显式的 --new-session 确认——在报告失败后，绝不会保留可能仍处于活动状态的写入者。持久化会话只有在所有权和终止状态都得到证明时才会被重用。

详细契约见 docs/specifications/supervision-events.md。Web 跟进请求以一条历史消息开始，足以建立会话游标并验证其 cwd；后续事件在同一流上到达。这避免了在每次跟进时向控制器重新发送默认的 50 条消息历史页，同时 DSH 会话和提供方缓存保持活跃。WebSocket 帧安全限制仍为 1 MiB，单个超大的最新帧会显式失败，而不会导致自动创建新会话。

验证交接

DSH 轮次的完成并不证明仓库任务是正确的。对于每个完成的轮次，控制器会将机器可读的、由控制器派生的事实写入会话下的状态文件中：

- handoff_pre_facts — 在派发时捕获的 Git 快照；
- handoff_post_facts — 在轮次完成后捕获的 Git 快照；
- verification_facts — {pre_prompt, post_prompt} 组合视图；
- verification — {"state": "pending", ...}。
快照只包含控制器自身从所选工作目录推导出的事实：解析后的仓库根目录、HEAD 提交、当前分支、有界的 git status --porcelain=v1 行（最多 200 行，每行 240 个字符），以及在能够安全解析时的上游领先/落后分歧。如果该目录不是 Git 工作树、Git 失败或快照超时，则改为存储一条有界的错误记录，并继续分派。快照从不捕获文件内容、提示词、模型响应、机密或 DSH 模型请求的任何内容，并且它们从不执行模型提供的命令。

随后，客户端包装器会向 stderr 打印：DSH 交接已完成，但独立的编排器验证仍待进行，同时还会打印会话密钥和状态文件位置。

编排器契约： 在向仓库所有者报告任务已完成之前，编排器必须独立检查实际状态：访问前后提交/状态之间的真实差异、提交是否存在并已推送、所声明的检查和测试是否实际通过，以及应承载该工作的 Issue/OpenSpec/PR 更新。记录的事实是快照辅助信息，而非审计追踪：它们是在每一轮之前和之后捕获的，因此在这些时间点之间的并发编辑、进行中的 DSH 评判或未提交的临时文件仍有可能出现；请将这些事实视为一致性信号，然后对照实时仓库进行验证。

安全边界

写入器以 danger-full-access 和 approval=never 启动 DSH；它继承用户任务和仓库指令中的权限。

读取器同样使用 DSH 不受限制的内部 shell，以避免不受支持的嵌套沙箱，但其整个控制器都在 bubblewrap 内运行。配置的项目根目录和所选工作目录由外层操作系统边界以只读方式挂载。其他主机路径并未设为只读，因此读取器提示词仍必须禁止外部副作用。

每种模式一次只能运行一个请求。文件锁允许一个写入器和一个读取器并发运行，并以退出码 75 拒绝第二个写入器或第二个读取器。

验证 bash
python3 -m unittest discover -s tests -v
python3 -m py_compile scripts/run_dsh_session.py scripts/watch_dsh_events.py scripts/scout_status.py scripts/dsh_web/*.py
bash -n scripts/run-dsh-agent.sh scripts/install.sh

实时验证还需要配置的提供商凭据。在首次公开发布之前，该实现已针对 glm-5.3-flash 进行了演练，涵盖跨调用记忆、提供商缓存读取、强制交接轮换、写入器权限、只读文件系统强制执行以及写入器锁拒绝。

项目状态

首次公开发布记录在 Issue #1 中。

许可证

MIT