AllDurham/foreman-dsh

Foreman · 工头模式

贵脑 + 贱手：让云端主脑做编排与验收，让本地模型做执行与阅读。

英文概览见下方 · 跳转

这是什么

Foreman（工头模式） 是 DeepSeek Harness 的一个社区 Agent 预设 + 配套插件。它给标准编码 Agent 增加两条通往本地模型的车道：

| 车道 | 工具 | 谁干活 | 干什么 |
| --- | --- | --- | --- |
| 执行车道 | delegate_worker | 本地工人模型 | 按五段简报写代码、跑测试、改文件 |
| 侦察车道 | scout_worker | 本地侦察兵模型（物理只读） | 按侦查简报通读代码库，回一张带 file:line 引用的"侦查地图" |

云端主模型（贵脑）只做三件事：判断、拆解、验收。写与读这两类最烧 token 的活，交给插电就算成本的本地模型。

┌─────────────────────────────┐
│   云端主脑（编排者）          │
│   判断 · 拆解 · 验收          │
└──────┬──────────────┬───────┘
执行委托（写）│              │ 侦察委托（读）
五段简报 · 固定报告 │              │ 侦查简报 · 侦查地图
┌──────┴──────┐  ┌────┴────────┐
│ 工人 worker  │  │ 侦察兵 scout │
│ 全套工具     │  │ 只读四件套    │
└──────┬──────┘  └────┬────────┘
└──────┬───────┘
本地 llama-server（单实例，串行）

为什么是"纪律"而不是"接口"

省 token 的敌人不是技术，是两件事：编排者忍不住亲自下场，和工人的自由发挥。所以 Foreman 的核心是一套可审计的委托纪律，其中两条是硬门槛：

- 决策外显——写入任何实现文件之前，编排者必须二选一：已发出委托，或在回复正文写明「不委托，理由：…」。会话中断重启后必须先补这条决策。实战中它把"无声脱轨"变成了三种可审计结局：正确委托 / 有理有据的拒绝 /（修复前的）脱轨。
- 独立复验——报告是工人写的，磁盘才是真相。复验分三层：机械校验命令优先（重跑 = O(1) 成本的全量复验）→ 无校验器才抽样（命中即升级全验）→ 小而关键才精读。

其余纪律：五段简报（目标/涉及文件/接口约定/验收标准/禁止事项）、固定执行报告格式（含 BLOCKED 时的『缺失信息』结构化字段）、简报红旗清单（函数体级细节 / 逐行 diff / 实现篇幅超过验收标准 = 白委托）、拆分扫描（拒绝委托前的最后一道工序：把任务切机械核/判断核两栏 ≤10 行，机械核用契约式简报外包、判断核自留，唯一合法拒绝理由 = 拆完没有机械核）、侦查地图四段格式（事实优先、推断标注、未覆盖声明）、失败次数熔断（FAILED ×3 自动回收，BLOCKED 不计次）。

完整纪律文本见 preset/skills/foreman-delegation/SKILL.md——它同时约束编排者、工人和侦察兵三个身份。

实测数据（6 局 A/B，诚实版）

同一提示词、同盘初始状态，唯一变量是预设。机械验收（测试通过数 + 规格冒烟逐格核对 / 行为探针）：

| 配对 | 运行 | 预设 | 编排者 | billable tokens | 交付质量 | 行为 |
| --- | --- | --- | --- | --- | --- | --- |
| task1 | R1 | 标准 | glm-5.2 | 186,763 | 21 tests ✅ | 单干 |
| task1 | R2 | 工头 | glm-5.2 | 490,475 | 24 tests ✅ | 委托 ×2，工人产出零返工 |
| task2 | R3 | 标准 | deepseek-v4-flash | 367,457 | 38 tests ✅ | 单干（3 次 TPM 限流死亡） |
| task2 | R4 | 工头 | deepseek-v4-flash | 247,243 | 38 tests ✅ | 外显拒委托，单干 |
| psc（真实项目） | P-STD | 标准 | glm-5.2 | 210,606 | 行为探针全过 ✅ | 单干 |
| psc（真实项目） | P-FM | 工头 | glm-5.2 | 162,753 | 行为探针全过 ✅ | 两次外显拒绝（侦察 + 委托），纪律开销 ≈ 0 |
四条一阶结论（详见 docs/experiment-notes.md）：

1. 成本由三个一阶因子决定：重启/稳定性税（R2 的 42%）> 编排者思考风格（glm-5.2 单步 2 万 token 的推理）> 简报开销比。委托机制本身在干净运行下开销极小。
2. 边界判据 = 简报开销比，且纪律能自动执行它：规格钉死、输出密集的任务（task1）委托成功且零返工；判断密集的任务（task2、真实项目）被红线正确弹回单干——"该委托时委托、不该时不委托"双向验证。
3. 账单的 64–78% 是输入 token，这正是侦察车道存在的理由：让本地模型替脑子读。但侦察只在"读远大于改"的仓库上划算——27 文件的真实项目上它被第二判据（改动占读取大半）正确否决。
4. glm-5.2 同预设同任务的运行间波动 ≈ 29%：便宜脑上做小差异 A/B 是噪声里捞针，对比实验要么多对采样、要么换稳定模型。决策外显累计 6 次全部正确（2 委托 + 4 拒绝）。

安装

要求：DeepSeek Harness >= 0.1.2-rc.1，Windows（pwsh 车道默认启用），本地 OpenAI 兼容端点（llama-server 等）。

1. 复制预设
preset/  →  ~/.dsh/.agent-presets/foreman/

2. 适配两处绝对路径（示例为 admin，改成你的用户名）：
a) preset/agent.cordis.yml 里 customSkillDirs 的 skills 目录
b) plugins/foreman-dsh-config/lib/index.js 里的 PRESET_YML 常量

3. 挂载配置插件：在 web profile 的 cordis.patch.yml 加入
- insert:
- id: foreman-config
name: foreman-dsh-config
config:
provider: qwen-daily
model: qwen3.8-daily
effort: low
然后把 plugins/foreman-dsh-config 安装到该 profile 能解析到的 node_modules。

4. 在 settings.yaml 里声明本地端点（示例）：
llm-pi-ai:
providers:
qwen-daily:
api: openai-completions
baseURL: http://127.0.0.1:11436/v1
compat: { supportsReasoningEffort: true }
models:
- id: qwen3.8-daily
reasoningEfforts: { low: low, medium: medium, xhigh: xhigh }
apiKeyEnv: QWEN_DAILY_API_KEY

5. 重启 dsh web，Agent 预设选「Foreman 工头模式」。

可选：在设置 → 插件里启用 subagent 模型选择并白名单当前实际在跑的档位，编排者即可逐次给侦察调用指定 reasoning_effort（理解型侦查给 medium）。⚠️ 白名单必须镜像现实——llama-server 不校验模型名，白名单里有但没在跑的档会静默降级。

设计备忘（写给要改它的人）

- list_subagent_models 是固定名单单例：同一个 preset 里只能有一个 modelSelectionSettings: true 的实例，两个并存会让第二个车道静默消失（2026-09-06 实测）。目前 scout 独占该能力。
- tools.restrict() 是持久作用域策略，在目录渲染时求值——对全局注册的工具可靠；own-scope 的 per-agent 懒安装注册豁免过滤（这是 subagent 曾漏进工人目录的原因，现已在 preset 层规避）。
- foreman-config 插件按"文件中第一个 agentOptions: 块"回写 UI 配置——新增车道要放在 delegate 块之后。
- 验证脚本：python scripts/validate_preset.py 可在校验结构后跑一遍（需要 pyyaml）。

English overview

Foreman is a community agent preset + companion plugin for DeepSeek Harness that adds two lanes to a local worker model (e.g. a 27B model on a 24GB GPU):

- delegate_worker — execution lane. The cloud orchestrator writes a five-section brief (goal / files / interface contract / mechanically-checkable acceptance criteria / prohibitions); the local worker implements it and reports back in a fixed format with per-acceptance evidence and a structured "missing info" field when blocked.
- scout_worker — read-only recon lane, enforced by a tool allow-list (read/glob/grep/read_image only). It returns a "recon map" with file:line references, conventions, and an uncovered-files declaration, so the expensive brain reads a 1K-token map instead of 100K tokens of repository.
产品是纪律，而不是管道：在任何实现写入之前做出明确的委派决策，分层独立验证（机械检查器 → 抽样 → 完整阅读），针对“通过实现进行简报”的红旗启发式，以及硬性 3 次违规熔断机制。一项 4 轮 A/B 实验显示质量保持稳定（所有交付物均为绿色），同时“委派”与“自己动手”之间的边界被纪律本身正确检测到。

完整细节见上文中文部分——预设文件注释是权威的设计记录。

许可证

MIT · 本项目为社区项目，与 DeepSeek 官方无隶属关系。