codex-harness-control

English · 安装与命令

项目介绍

Codex Harness Control 是一个面向 DeepSeek Harness 的开源多模型协作插件。Codex 负责拆解目标、分配任务、独立验收和规划下一轮；Harness 中已经存在的模型会话负责执行，从而保留每个模型的原有上下文、工作区和使用额度。

它适合需要同时推进多个软件项目、希望让多个模型持续协作，又不想依赖鼠标、剪贴板或反复手工派单的用户。所有连接、项目选择、任务租约和审核记录均保存在本机。

核心能力

• 在 Harness 中直接选择项目以及一个、多个或全部模型会话。
• 自动安装并配置 Codex skill，无需复制模型密钥或手工填写连接参数。
• 自动巡检任务、核对真实文件和测试、释放租约并续派已授权的下一轮。
• 使用共享任务账本防止重复派单、会话抢占和并行写入冲突。
• 按项目输出数字进度图，并在任务完成、失败或需要用户决定时通知用户。

协作流程

flowchart LR
    C[Codex 主控] -->|拆解与派单| L[(本地任务账本)]
    L --> H1[Harness 执行会话]
    L --> H2[Harness 审查会话]
    L --> H3[Harness 测试会话]
    H1 -->|回复与文件| C
    H2 -->|回复与文件| C
    H3 -->|回复与文件| C
    C -->|独立验收后续派| L

看图上手

① 打开总控，自动安装 Codex Skill

安装插件后，进入 设置 → Codex 总控。看到“已安装并配置完成”即可继续，无需再去 Codex 下载技能或填写连接参数。

② 选择项目，勾选需要的模型

向下滚动，在“项目”中选择要协作的 Harness 项目。可以只选一个，也可以逐个勾选多个；看到“已自动保存”即已生效。图中选择了 3 个会话中的 2 个。

多个项目独立配置： 切换项目后可使用“全选”。例如项目 A 使用 2 个会话，项目 B 使用全部 3 个；切换回来会保留各自选择。会话数量不限于 3 个，同一个模型的多个会话也可以分别选择。

查看另一个项目的“全选”操作图

③ 选择自动检查和总结间隔

模型选择完成后，可以分别设置多久检查当前任务、多久总结任务进度。默认是 10 分钟检查、30 分钟总结。首次在 Codex 中开始协作后，Harness 插件会记录该窗口为协调线程，并按此间隔向它发送普通消息，无需再安排定时任务或反复说“继续”。设置按项目保存，也可以关闭自动接管。

任务检查负责收取回复、验证真实交付并续派已获授权的下一轮；进度总结只读汇报，不会重复派单。目标完成、用户取消或需要新决定时会停止自动推进。

由 Harness 定时发送检查任务，让 Codex 自动继续工作。 之前使用 Codex 自带的定时提醒时，我们遇到过这样的情况：提醒已经发出，Codex 却直接结束，没有检查任务，也没有继续派发。也就是说，消息到了，但检查没有执行。

为了解决这个问题，新版改由 Harness 按设定间隔发送明确的检查任务，让 Codex 检查进度、验收结果，并继续安排已授权的下一步。每轮检查结束后，Codex 都会记录一次完成回执，设置页会显示最近一次检查情况；连续几个周期没有回执时会提示异常。具体测试数据见验证记录。

④ 在对应的 Codex 项目窗口开始协作

在 Codex 打开实际代码项目，在下一条消息中输入：

使用 $codex-harness-control 开始协作

交付目录会自动匹配，无需输入路径。只有无法唯一匹配时，才需要选择 Harness 项目名称。随后由 Codex 派单、收取回复并检查交付成果。

需要删除或重新安装 Skill？查看操作图

点击“删除 Codex Skill”后，会显示“已删除，等待手动安装”。项目配置和历史任务保留，刷新页面不会自动装回；点击“安装 Codex Skill”即可恢复。

删除不会终止已经运行的任务。若要停止插件继续唤醒 Codex，请在项目设置中关闭“自动接管”。只需更新时使用“更新 / 修复 Codex Skill”。

能做什么

• 发现已有 Harness 会话，按项目、会话 ID、工作目录和模型明确绑定。
• 保留原会话上下文，通过本地 RPC 派单、分页读取助理回复，不占用鼠标和剪贴板。
• 用共享 SQLite 账本协调多个 Codex 窗口，阻止重复任务、同会话抢占和重叠写路径。
• 发送结果不确定时保留任务占用，不自动重发；记录任务的原始接收人和发送基线。
• 由 Codex 检查真实交付，保存审核报告快照后放行下一轮。
• 每个项目可选择检查任务和总结进度的间隔；Harness 插件按间隔唤醒已关联的 Codex 协调线程，自动验收并续派已获授权的下一轮。每次自动巡检执行一次有边界的状态快照后结束并写入签到回执；验收、返工、续派、失败或需要用户处理时会通知，任务仍在正常运行且没有变化时安静结束但仍然签到。唤醒状态在设置页可见，插件不会把消息堆积在仍在运行的回合后面。

支持任意已在 Harness 配置的模型，不内置模型账号，也不要求向本项目提供 GLM、Kimi 或 DeepSeek API key。使用各模型仍会消耗其原有额度。

安装

需要已安装 Python 3.10+、Codex 和正在运行的本地 DeepSeek Harness Web/Desktop。Harness 插件需要 Node 22+ 及支持 ctx.skills 的宿主。本版基于 Harness 0.1.2-rc.1 验证，其他版本先执行连接检查。

总控页面会自动查找可用的 Python，并检查版本；未安装时会显示具体提示。

自动巡检还需要 Codex CLI 支持 queue --thread --message。调度器会先读取命令帮助检查能力；不支持时提示升级 Codex CLI 并重启 Harness，不会尝试派发检查任务。安装了 Codex App 不代表命令行工具已就绪。

优先在 Harness 当前窗口的插件市场或插件管理页安装，这样会自动使用正在运行的 profile。

如果使用 CLI，profile 名必须和启动 Harness 时 dsh --profile NAME 的 NAME 完全一致。不要照抄一个并未运行的 web、safe 或 desktop 名称；dsh plugin 会自动创建不存在的空 profile，命令虽然显示安装成功，但插件无法取得 Harness 服务。

dsh plugin --profile YOUR_ACTIVE_PROFILE add github:edisontaisite/codex-harness-control#v0.7.2

刷新或重启宿主后打开 设置 → Codex 总控。页面会自动安装或更新本机 Codex skill，连接当前宿主。已有同名 skill 会先备份到私有控制目录，再更新；未变化的版本不会重复安装。无需填写连接参数、路径、角色名称或另行运行安装命令。安装包没有 npm 生命周期脚本；自动配置发生在用户打开总控页面时。

删除与重装： 在安装卡片点击“删除 Codex Skill”，只移除本机 Codex 中的此技能，保留 Harness 插件、项目选择和历史任务，并备份原技能文件。主动删除后，刷新或重新打开页面不会自动装回；点击“安装 Codex Skill”可恢复。删除不会终止已运行的任务；如需停止后续唤醒，请同时关闭该项目的“自动接管”。

如只需独立安装 Codex skill，仍可从源码执行 python3 tools/install_codex_skill.py；该独立命令保留拒绝覆盖已有目录的行为。

使用（0.7.2）

1. 打开 Harness 设置 → Codex 总控，“Codex Skill 安装”卡片会自动完成安装和共享配置，显示“已安装并配置完成”。如果卡片提示 Skill 刚完成安装或更新，请新建对应的 Codex 项目窗口或重启 Codex，使新 Skill 进入该窗口的技能列表。需要重试或更新时，点击卡片中的安装或更新 / 修复按钮。
2. 选择项目，勾选一个、多个或全部模型。勾选即自动保存，不再需要保存按钮或角色命名。
3. 选择任务检查和进度总结间隔。默认每 10 分钟检查、每 30 分钟总结；每个项目独立保存，也可以关闭自动接管。
4. 在新建或重启后的对应 Codex 项目窗口输入一次：使用 $codex-harness-control 开始协作。这一步会把该窗口记录为协调线程，此后由插件自动唤醒，不需要再手动输入。

自动唤醒需要本机能找到 codex 命令（CHC_CODEX 可指定路径，CHC_DISABLE_SCHEDULER=1 可整体关闭）。设置页的"唤醒状态"会显示 等待首次唤醒 / 已唤醒待签到 / 上次签到 N 分钟前 / 最近 N 个周期没有签到 / 上次唤醒失败。

交付目录由 Codex 开始协作时自动匹配，不需要填写路径：优先使用已关联目录和原会话目录；不一致时对照已选模型近期回复中的现有代码路径。只有不能唯一匹配时，才请用户选择 Harness 项目名称。各项目独立保存对应关系，保留原模型会话。

项目和会话来自当前 Harness 的工作区注册表。不同项目的选择独立保存；同模型的不同会话可分别勾选。保存冲突或在途任务阻止变更时，页面会回读已保存状态并显示原因，不会自动重试派单。

宿主每次启动会在本机私有控制目录更新运行连接文件，使用其现有认证凭据，不依赖日志路径或手动输入 token。运行凭据仅在本机 hosts/ 目录保存（POSIX 文件权限 0600），不返回浏览器，不写进仓库。不要上传控制目录。

Codex companion 自动安装到 $CODEX_HOME/skills 或 ~/.codex/skills；安装目录中的私有 local.json 指向共享配置，因此 Codex 无需手动设置 CHC_HOME。默认控制目录为 ~/.codex-harness-control。开发者仍可使用 CHC_HOME 和 CHC_PYTHON 覆盖宿主运行环境。

仅添加工作区不等于安装插件。安装须使用实际运行的 profile（例如 desktop、safe 或 web）。

自动唤醒由插件所在的 profile 执行，所以只有正在运行的那个 profile 装了新版才会唤醒；装在别的 profile 里的旧副本不会生效，也不会报错，容易被误认为"已经升级了"。用下面这条确认哪些 profile 装了、各是什么版本：

for p in ~/.dsh/profiles/*/; do echo "$(basename $p): $(node -p "require('$p/node_modules/codex-harness-control/package.json').version" 2>/dev/null || echo 未装)"; done

多个 profile 同时运行时不会重复派单：唤醒前会按项目取一个本地占用（~/.codex-harness-control/heartbeat/<project>.lock.json），拿不到的 profile 跳过本轮。占用超过 2 分钟且原进程已经退出时才会被接管；仍存活的慢任务不会被抢占，旧持有者也不能删除新持有者的占用。 GitHub 安装请使用发布标签，不要跟随浮动的 main。这样文档或赞助信息的提交不会被误判为插件更新。若旧的浮动安装出现 ERR_PNPM_UNEXPECTED_PKG_CONTENT_IN_STORE，先备份该 profile，再用最新 vX.Y.Z 标签强制重装；不要删除整个 pnpm store 或重装全部插件。

高级 CLI 文档保留在命令参考，普通使用不需要手工配置。

边界

sent 表示宿主接受了请求，verified 表示主控记录了审核结论；脚本不会替代业务验收。任务标记、固定回显词、模型自报 PASS 都不足以证明交付正确。

路径占用是协作规则，不是操作系统沙箱，也不能阻止其他工具手动派单。已有用户权限和明确限制继续有效。自动接管由 Harness 插件按间隔向已关联的 Codex 协调线程投递普通消息实现，不使用 Codex 原生 heartbeat，也不创建系统 cron 或 launch agent。需要本机可执行的 codex 命令；找不到时会在设置页显示唤醒失败原因。巡检会读取全部已选模型，独立验收后释放租约，并自动续派已授权的下一轮，且每轮都写入签到回执。目标完成、用户取消或需要新授权时停止推进。当前版本不包含 Claude App 接入、远程 Harness 或自动审批。

开发与验证

python3 -m unittest discover -s tests -p 'test_*.py'
node --test tests/plugin.test.mjs tests/ui.test.mjs tests/python.test.mjs tests/first-run.test.mjs
node tools/check-package.mjs
npm pack --ignore-scripts

Python 测试使用本地模拟 Harness 服务，不向真实模型发消息。发布包无安装期脚本、遥测或内置密钥。验证说明区分自动化测试和本机实测。

开源与发布

MIT License。欢迎通过仓库 Issues/PR 提交复现、兼容性记录和改进。提交日志前移除 token、会话正文和私人路径。公开目录不包含任何用户的项目绑定、会话 ID 或历史交付。

插件市场需要真正可安装的 bundle，本仓库包含 package.json 的 dsh.bundle、cordis.patch.yml、插件入口和打包资源。市场提交要求与发布工具见 PUBLISHING.md。本项目为社区工具，与 OpenAI、DeepSeek 无官方隶属关系。