deepseek-foreman 0.3.1 → 0.4.1

package/README.md

@@ -8,7 +8,7 @@
 
 面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）。
 
-**小白三步**（没碰过 cordis / YAML / CLI 也能上手）：
+**小白三步**（没碰过 cordis / YAML / CLI 也能上手，全程有 setup 向导兜底）：
 
 1. 装 dsh，配好 ≥2 家厂商的模型；
 2. 插件页点装 `deepseek-foreman`；
@@ -184,6 +184,14 @@ bundle 的 `cordis.patch.yml` 里**新增插件行要包在 `insert:` 下**：
 
 成本台账随每张回执记录（施工 token/effort/wall-clock），`_receipts/progress.md` 周汇总；无人托管有预算闸（到限即停）。分工逻辑与实测数据见 [可量化测试数据](docs/metrics-2026-10-01.md)。
 
+## 首次配置向导（R15）
+
+```bash
+npx deepseek-foreman-setup   # 核对白名单、指路角色表、给试跑话术
+```
+
+故障自助见 [故障速查](docs/install-flow.md#故障速查10-条与-doctor-hints-对应)（10 条，与 doctor hints 对应）。
+
 ## 状态
 
 已装进 dsh 桌面版 0.2.0-rc.2（Intel iMac）并 live 验证：冷启动正常，`pick_route` 可被模型调用，视觉约束会真的拦截并给 fallback；`subagent_readonly` 最终态同样 live 实测通过（只读工具集生效、委派工具被拦死）。

package/lib/index.d.ts

@@ -43,6 +43,19 @@ export interface Config {
 }
 /** Loader schema for the role table. */
 export declare const Config: z<Config>;
+/** R5 mechanical acceptance verdict as the model sees it. */
+export interface AcceptCheck {
+    receipt: string;
+    ticket?: string;
+    headSha: string;
+    headMatches: boolean;
+    recordedHead?: string;
+    checks: {
+        name: string;
+        status: 'pass' | 'fail' | 'missing' | 'stale';
+    }[];
+    ready: boolean;
+}
 /** One resolved role route as the model sees it. */
 export interface Route {
     role: string;

package/lib/index.js

@@ -1,5 +1,6 @@
 /** Route adjudication for ticket dispatch: role -> provider/model, with hard constraints. */
 import { constants, copyFileSync, cpSync, lstatSync, mkdirSync, readFileSync, readdirSync, statSync, symlinkSync, unlinkSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { basename, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -125,6 +126,27 @@ const SETUP_SCHEMA = {
         hints: { type: 'array', required: true, items: { type: 'string' } },
     },
 };
+/** Accept-check (R5 fingerprint) block: receipt vs code version, mechanically. */
+const ACCEPT_CHECK_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        receipt: { type: 'string', required: true },
+        ticket: { type: 'string' },
+        headSha: { type: 'string', required: true },
+        headMatches: { type: 'boolean', required: true },
+        recordedHead: { type: 'string' },
+        checks: {
+            type: 'array', required: true, items: {
+                type: 'object', additionalProperties: false, properties: {
+                    name: { type: 'string', required: true },
+                    status: { type: 'string', enum: ['pass', 'fail', 'missing', 'stale'], required: true },
+                },
+            },
+        },
+        ready: { type: 'boolean', required: true },
+    },
+};
 const DECISION_SCHEMA = {
     type: 'object',
     additionalProperties: false,
@@ -134,6 +156,7 @@ const DECISION_SCHEMA = {
         route: ROUTE_SCHEMA,
         alternatives: { type: 'array', required: true, items: ROUTE_SCHEMA },
         setup: SETUP_SCHEMA,
+        acceptCheck: ACCEPT_CHECK_SCHEMA,
     },
 };
 /** Long-output threshold below which a capped route is refused. */
@@ -501,6 +524,8 @@ export function apply(ctx, config) {
             needs_vision: { type: 'boolean', description: 'The work reads images or screenshots.' },
             needs_long_output: { type: 'boolean', description: 'The work must produce a large single output (whole document, big file).' },
             review_for: { type: 'string', description: 'When this dispatch is a code review, name the role that wrote the code. Same-vendor reviewers are refused: correlated models make correlated mistakes.' },
+            accept_check: { type: 'string', description: 'R5 mechanical acceptance: pass an absolute receipt path (the receipt must contain a 「指纹」 section with HEAD sha and per-check status). Verifies the receipt matches the current git HEAD and every acceptance command passed. Returns acceptCheck instead of a route.' },
+            project_root: { type: 'string', description: 'Git working directory for accept_check (defaults to the repo containing the receipt).' },
         },
         output: {
             schema: DECISION_SCHEMA,
@@ -508,6 +533,10 @@ export function apply(ctx, config) {
         },
         async execute(args) {
             refresh();
+            // R5: accept_check is a mode switch, not a route query.
+            if (args.accept_check !== undefined && args.accept_check !== '') {
+                return { ok: false, reason: 'accept-check mode', alternatives: [], acceptCheck: runAcceptCheck(args.accept_check, args.project_root) };
+            }
             const now = new Date();
             const all = () => roles.map(toRoute);
             // Omitting the role is the doctor call: the answer carries `setup` even when the table
@@ -547,6 +576,47 @@ export function apply(ctx, config) {
         },
     }));
 }
+/** R5: mechanically verify a receipt's fingerprint block against the current git HEAD. */
+function runAcceptCheck(receiptPath, projectRoot) {
+    const receipt = (() => {
+        try {
+            return readFileSync(receiptPath, 'utf8');
+        }
+        catch {
+            return '';
+        }
+    })();
+    const root = projectRoot ?? dirname(receiptPath);
+    const headSha = (() => {
+        try {
+            return execFileSync('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+        }
+        catch {
+            return '';
+        }
+    })();
+    const recordedHead = /HEAD sha[:：]\s*`?([0-9a-f]{7,40})`?/.exec(receipt)?.[1] ?? '';
+    const ticket = /工单[:：]\s*`?([^`\n]+)`?/.exec(receipt)?.[1]?.trim();
+    // Fingerprint block: each acceptance line as `- [<name>]: <status>` where status ∈ pass/fail/missing/stale.
+    const checks = [];
+    for (const line of receipt.split('\n')) {
+        const m = /^- \[([^\]]+)\]:\s*(pass|fail|missing|stale)\s*$/.exec(line.trim());
+        if (m !== null)
+            checks.push({ name: m[1], status: m[2] });
+    }
+    const headMatches = recordedHead !== '' && recordedHead === headSha.slice(0, recordedHead.length);
+    const ready = receipt !== '' && headSha !== '' && headMatches
+        && checks.length > 0 && checks.every(c => c.status === 'pass');
+    return {
+        receipt: receiptPath,
+        ...(ticket === undefined ? {} : { ticket }),
+        headSha,
+        headMatches,
+        ...(recordedHead === '' ? {} : { recordedHead }),
+        checks,
+        ready,
+    };
+}
 /** mtime of a file, or undefined when it cannot be stat'ed at all. */
 function mtimeOf(file) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepseek-foreman",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Foreman for DeepSeek Harness: your best model leads, cheaper models build, a rival vendor reviews. Role-to-route adjudication with peak-window, vision, output-size and cross-vendor-review constraints.",
   "type": "module",
   "main": "lib/index.js",
@@ -19,7 +19,8 @@
     "cordis.patch.yml",
     "roles.example.yml",
     "skill/",
-    "persona.example.md"
+    "persona.example.md",
+    "scripts/setup.mjs"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json"
@@ -47,5 +48,8 @@
     "bundle": {
       "patch": "./cordis.patch.yml"
     }
+  },
+  "bin": {
+    "deepseek-foreman-setup": "scripts/setup.mjs"
   }
 }

package/scripts/setup.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// deepseek-foreman setup 向导（R15）：核对白名单配置 + 指路角色表 + 给试单话术。
+// 用法：node node_modules/deepseek-foreman/scripts/setup.mjs  或  npx deepseek-foreman-setup
+import { readFileSync, existsSync, readdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { parse as parseYaml } from 'yaml'
+
+const home = homedir()
+const profilesDir = join(home, '.dsh', 'profiles')
+const rows = []
+if (existsSync(profilesDir)) {
+  for (const name of readdirSync(profilesDir)) {
+    const file = join(profilesDir, name, 'cordis.patch.yml')
+    if (!existsSync(file)) continue
+    let found = false
+    try {
+      const doc = parseYaml(readFileSync(file, 'utf8'))
+      for (const entry of Array.isArray(doc) ? doc : []) {
+        if (entry?.config?.allowedModels !== undefined) { found = true; break }
+        if (entry?.insert) for (const sub of entry.insert) if (sub?.config?.allowedModels !== undefined) { found = true; break }
+      }
+    } catch { /* 解析失败当没配 */ }
+    rows.push({ profile: name, hasAllowlist: found })
+  }
+}
+console.log('=== deepseek-foreman setup ===')
+console.log('1) allowedModels 白名单检查：')
+for (const r of rows) console.log('   profile ' + r.profile + ': ' + (r.hasAllowlist ? '已配置 ok' : '未配置 -> 在该 profile 的 cordis.patch.yml 加 subagent-model-selection-settings 的 allowedModels（模板见 README 前置条件），改完开新会话'))
+if (rows.length === 0) console.log('   未发现 profile（先安装并运行一次 dsh）')
+console.log('2) 角色表：编辑 ~/.dsh/foreman.roles.yml，provider/model 用「调 pick_route 看看 setup」返回的可用清单里的值。')
+console.log('3) 试跑一张小工单：对 dsh 说「走工单：把 docs/README.md 里错的日期改成今天，difficulty: trivial」。')

package/skill/deepseek-foreman/SKILL.md

@@ -19,7 +19,8 @@ description: 工单托管（DeepSeek Harness 版）：你当经理，不自己
    - 谁施工、谁审查。**审查必须和施工来自不同厂商**——同族模型会犯同一种错。
    - 施工是否不止一个，按活分（长输出给输出上限高的，机械批量给便宜档）。
    - 审查员是否只读。**首选 `subagent_readonly` 物理只读**：经它派出的子会话运行时只有 `read` / `grep` / `glob`，写工具改不了文件；会话里没有这个工具时（preset 层未放行）退回普通 `subagent` + 提示词只读 + Lead 审查前后各看一次 `git status`（详见第六节）。
-4. **写进 `_tickets/workers.md`**，格式见下。以后照它派，不重新摸。
+4. **跑 setup 向导**：`node node_modules/deepseek-foreman/scripts/setup.mjs`（或 npx deepseek-foreman-setup）——核对白名单、指路角色表、给出试跑小工单话术。**首次配置一律先跑它**，别徒手改 YAML。
+5. **写进 `_tickets/workers.md`**，格式见下。以后照它派，不重新摸。
 
 ```markdown
 # 工人配置
@@ -166,6 +167,24 @@ _receipts/   回执、审查报告、进度、报告
 
 **停下或被叫回时**：写 `_receipts/report-<日期>.md`，大白话说清哪些能用了、哪些没做完、哪些等他拍板（每条一行附你的建议）、出了什么问题、工人花了多少钱。看不到自己的用量就直说看不到，不要猜。
 
+## 十、bundle 改动冒烟清单（R12）
+
+改 `cordis.patch.yml`（加实例/改 toolFilter/改 config）是全项目最危险的操作——**离线 110 项全绿也可能 live 才炸**（T205 preset scope、T207 全局工具表都是这么来的）。每次改完必须做：
+
+1. `npm run build && node test/smoke.mjs` 全绿（离线层）
+2. **插件页关→开（或重启 app）**——手改文件不会通知运行中的 Host
+3. live 三查：模型侧 `pick_route` 有返回；新实例在模型工具列表里；**用一次该实例**（真派一个最小子任务）确认行为
+4. 报错对照两条已知坑：`standing ... requires a scoped preset Context`（bundle 层不能开 modelSelectionSettings）；`restrict() names unknown global tool`（deny/allow 名字必须在子组合全局工具表里）
+5. 以上任一失败：立即回退该行 patch，写进回执存疑，另开修复单
+
+## 十一、换会话交接（R7）
+
+**任何会话收尾前**（包括普通单、不只无人托管）写 `_tickets/handoff.md`，上限 2KB，只放七样：用户目标原话、「不做清单」、下一件的第一动作、当前 HEAD、工单/回执路径、未定决定、预算闸状态。新会话开工先读它，**不重跑盘点、不靠记忆**——只核 HEAD 与下一件工单在不在，相符就干。
+
+## 十二、上下文四档（R3）
+
+Lead 会话上下文占用自估（工单+回执+审查读入量）：**0-30% 全速**（并行派单、完整读回执）；**30-50% 正常**（优先只读结论层）；**50-70% 收缩**（只读 frontmatter，警告用户）；**70%+ 切割**（立即写交接、收尾当前单、停新派）。判断信号：措辞变虚、跳步骤、半完成——都是上下文压力前兆。
+
 ## 规矩
 
 - 工人不挪工单、不提交、不审自己的活、不合并别的单。