LoopX与DeepSeek Harness（dsh）集成指南：无头分段回合的治理方式-平芜编程栈

LoopX与DeepSeek Harness（dsh）集成指南：无头分段回合的治理方式

【免费下载链接】loopxLong-horizon agent control plane for durable, governed work across Codex, Claude Code, and other harnesses.项目地址: https://gitcode.com/GitHub_Trending/lo/loopx

LoopX 是一款长程 Agent 控制平面，而本指南讲的核心，是如何把 DeepSeek Harness（dsh）接入 LoopX，实现无头（headless）分段回合（Turn）的治理方式：dsh 负责真正干活（模型调用、工具、沙箱），LoopX 负责发号施令（目标、待办、配额、验证与写回）。两者各守边界，任何一段无头执行都跑不出治理范围。

为什么要给 dsh 套上 LoopX 控制平面

dsh 本身是一个优秀的 Agent 执行宿主机（harness），但它更关注"怎么把这一轮跑完"，而不是"这个长任务还剩下什么、该不该继续、配额是否允许"。LoopX 补上的正是后者：

职责	归属	具体做什么
目标 / 待办 / 配额 / 证据	LoopX	持久化 Goal 与 Todo 状态，判断"现在该不该跑"
模型调用 / 工具 / 沙箱 / 会话日志	dsh	在一个有界的"工作分段"内执行任务并返回结构化结果
结果验证	LoopX	独立校验器在写回和扣配额之前先验证 typed 结果

完整连接器说明见 docs/integrations/deepseek-harness-connector.md，适配器源码位于 loopx/dsh_goal_mode/ 子包（python -m loopx.dsh_goal_mode即可运行）。

一次被治理回合的完整链路

整个集成可以浓缩成一条单向流水线，每一环都有明确契约：

LoopX quota should-run ← 配额先审：该不该跑 → loopx turn run-once ← 启动一次受治理的 Turn → loopx.dsh_goal_mode 适配器 ← 把签名 TurnEnvelope 翻译成 dsh 提示词 → DeepSeek Harness SDK / dsh 运行时（无头执行一个有界工作分段） → typed loopx_turn_result_v0 ← 模型最终消息被解析为结构化结果 → 独立验证器 + LoopX 写回 + 配额扣减

前端首屏也能看到这套控制平面的工作形态：

快速上手：3 步完成 dsh 与 LoopX 集成

第 1 步：获取代码并安装可选依赖

git clone https://gitcode.com/GitHub_Trending/lo/loopx cd loopx && python -m pip install 'loopx[deepseek-harness]'

该可选依赖组固定了对应版本的deepseek-harness-sdk，核心 LoopX 本身不强制它。真实运行还需要DEEPSEEK_API_KEY/DEEPSEEK_BASE_URL环境变量，以及（可选的）cordis.yml配置文件。

第 2 步：以--host dsh跑一次受治理回合（推荐）

loopx turn run-once --goal-id <goal-id> --agent-id deepseek-worker \ --host dsh --execution-mode isolated-headless --project "$PWD" \ --dsh-model deepseek-v4-flash --validation-command-json '[...]' --execute

内置宿主（--host dsh）在同一 CLI 进程内运行适配器，Provider 故障会以类型化失败码进入 Turn 日志，从而支持同 Turn 有界重试；子进程模式（generic-cli+--host-adapter-command-json）同样可用，两条路径的端到端演练脚本在 examples/ 下。

第 3 步：在 dsh 交互界面里显式调用 loopx 技能

如果你日常使用 dsh 的 Web 会话，也可以安装 dsh-loopx 插件（源码见 packages/dsh-loopx-plugin/），在技能选择器中显式选择loopx，然后直接用自然语言描述任务——Agent 会自动建立持久化的 Goal/Todo 状态。

无头分段回合是如何执行的

理解这套"无头分段回合的治理方式"，关键是适配器（loopx/dsh_goal_mode/turn_host_adapter.py）的两条铁律：

只信签名授权，不信散文。适配器从 stdin 读取一个loopx_turn_host_request_v0JSON 对象，先校验 TurnEnvelope 的 action 签名哈希，再取出有界任务正文primary_action、只读清单required_reads与写权限write_scope。它绝不从其他文本里"脑补"权限。
只认结构化结果，失败即收口（fail closed）。dsh 的最终助手消息必须是一个 JSON 对象，result_kind只接受六种之一：

result_kind	含义
`validated_progress`	有验证通过的实际进展
`repair_required`	任务本身没问题，但有个可修复的缺陷挡住
`replan_required`	当前路线走不通，需要换方案
`user_action_required`	需要人工介入
`wait`	当前没有安全可写的内容，暂停
`iteration_failed`	本回合失败且未授权重试

如果模型没有返回可解析的 JSON，适配器会保守地输出wait（不伪造进展、不扣配额）；如果结果形状本身非法，则作为contract_rejected类型化失败上抛。两条路径都不允许消耗配额——这是无头执行的底线。

失败分类：让每一次无头重试都有据可依

子进程模式下，一个非零退出码只能告诉你"挂了"；内置宿主（loopx/dsh_goal_mode/host_failure_map.py）则把 dsh 的终端原因映射为精确的失败类型：

dsh 侧信号	LoopX 失败类型	是否可重试
401 / 403 /`invalid_api_key`	`auth_failed`	否
429 /`rate_limit`	`rate_limited`	有界重试
5xx /`SERVER`/`overloaded`	`provider_overloaded`	有界重试
`EMPTY_RESPONSE`/ 连接中断	`transport_lost`	有界重试
结果与事件自相矛盾	`contract_rejected`	否

分类遵循loopx-turn-v0优先级：已知 Provider 错误码 > HTTP 状态码 > 消息文本匹配，同一层级信号冲突时一律收口为unknown，防止"看似成功、实则带错"的灰色状态进入日志。

治理边界：适配器不能做什么

LoopX 对适配器的限制是刻意设计的，值得新手记住：

不读goal/todo 状态，不写LoopX 状态，不花配额，不自验自己的工作；
dsh 的运行时主目录（默认<workspace>/.local/.dsh-sessions）永远留在本地，绝不进入LoopX 公开证据；
会话持久化归 dsh 自身组合所有，此集成不承诺跨回合会话续接或跨进程恢复。

一句话：dsh 是执行手，LoopX 是记账官，两者之间只有签名报文和结构化结果两条通道。

真实案例：约束变化时，Replan 留下完整决策链

仓库内置了一个可复现的演示（examples/dsh-loopx-demo/，案例文档见 docs/showcases/cases/dsh-loopx-replan-demo.md）：

一个 Node.js CLI 需要结构化日志，dsh Agent 对比 Pino、Consola、Roarr 后选了 Pino；随后用户追加约束"将部署到 serverless，冷启动和依赖体积优先"。LoopX 的做法不是悄悄改写旧决策，而是：保留原决策为"被取代"状态 → 记录一次显式Replan→ 创建后继 Todo → 实现切换到 Roarr（依赖树从 12 个包降到 4 个），3/3 行为测试通过，GoalBar 最终 2/2 关闭。

对长程无头任务来说，这种"约束变化不抹掉证据链"的治理方式，正是分段回合模式的核心价值——每个回合短小可重试，但决策与证据在 LoopX 侧持久累积。长时运行的轨迹示例可参考 docs/assets/long-running-loop-ml-experiment-trajectory.png：