deepseek-foreman 0.2.0

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "deepseek-foreman",
+  "version": "0.2.0",
+  "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",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/index.d.ts",
+    "cordis.patch.yml",
+    "roles.example.yml",
+    "skill/"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/biantao1108/deepseek-foreman"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.4",
+    "yaml": "^2.9.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
+    "@types/node": "^22.20.4",
+    "typescript": "^5.9.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/roles.example.yml

@@ -0,0 +1,89 @@
+# deepseek-foreman 角色表（外部配置文件）
+#
+# 插件每次执行 pick_route 前都会重新看这个文件的 mtime：
+# 改完保存，下一次调用立即生效，不用重启 dsh。文件写坏了也不会炸——
+# 插件保留上一份可用角色表，并在返回值里说明错在哪，改好自动恢复。
+#
+# 怎么用
+#   把下面「组合 A」或「组合 B」里其中一组的注释解开（两组只解一组，
+#   同时解开会得到两个顶层 roles: 键，YAML 会判重复键而报错），
+#   再把 provider / model 换成你自己的路由名，保存即生效。
+#
+# 字段说明（每条角色都能用，缺省值见括号）
+#   role             角色键。模型调 pick_route 时传的名字，如 lead / daily-code / review。
+#   vendor           厂商键。只用于「异族审查」判定：同 vendor 的写手与审查者不能互审。
+#                    同一家厂商的不同模型，vendor 要填同一个值。
+#   provider         交给 subagent 工具的路由 provider（必填）。
+#   model            该 provider 下的模型 id（必填）。
+#   reasoningEffort  推理档位，如 high / medium / low；留空（默认）用模型自己的默认档。
+#   vision           是否支持读图/截图（默认 false）。带图的活派给 false 的角色会被拒。
+#   maxOutputTokens  声明的单次输出上限（默认 0 = 不声明，跳过长产出检查）。
+#                    整篇长产出派给上限小于 100000 的角色会被拒。
+#   peakWindows      高峰时段，格式 "HH:MM-HH:MM"，可写多段（默认空 = 不限时段）。
+#   peakDays         高峰时段生效的星期，ISO 编号 1=周一 … 7=周日（默认空 = 每天都算）。
+#   holidays         全天不算高峰的日期，格式 YYYY-MM-DD（默认空）。
+#   fallback         本角色被拒时建议改派的角色键（默认空 = 不给建议）。
+#   note             给模型看的说明：这个角色干什么、要注意什么。
+#
+# 两个硬提醒
+#   1. provider / model 必须是当前 dsh 会话 allowedModels 白名单里已有的路由，
+#      否则 subagent 调用会被白名单拦下；白名单是会话创建时的快照，改完要开新会话。
+#   2. 出厂模板里没有任何真实路由名，provider / model 全是占位符，请自己填。
+
+# ── 组合 A：单一厂商全家桶（自家模型分档；审查必须另找一家厂商，否则同族审查会被拒）
+# roles:
+#   - role: lead
+#     vendor: vendor-a
+#     provider: PROVIDER_A            # ← 换成你的 provider
+#     model: MODEL_LEAD               # ← 换成你的模型
+#     reasoningEffort: high
+#     note: 经理位。不写代码，只看工单、回执和审查意见。
+#   - role: daily-code
+#     vendor: vendor-a
+#     provider: PROVIDER_A
+#     model: MODEL_CODE
+#     vision: true
+#     peakWindows:                    # 便宜档只在非高峰时段放行
+#       - 09:00-12:00
+#       - 14:00-18:00
+#     peakDays: [1, 2, 3, 4, 5]
+#     holidays:
+#       - 2026-01-01
+#     fallback: chores
+#     note: 日常实现。便宜、有视觉；高峰时段会被拒并改派 chores。
+#   - role: chores
+#     vendor: vendor-a
+#     provider: PROVIDER_A
+#     model: MODEL_CHEAP
+#     maxOutputTokens: 65536
+#     note: 杂活。窗口小，别塞大上下文，也别要求整篇长文。
+#   - role: review
+#     vendor: vendor-b                # ← 审查换一家厂商，否则同族审查会被拒
+#     provider: PROVIDER_B
+#     model: MODEL_REVIEW
+#     note: 只读审查。只找真问题，附文件:行号 + 证据。
+
+# ── 组合 B：多厂商混合（经理 / 施工 / 审查分属三家，谁跟谁都不算同族）
+# roles:
+#   - role: lead
+#     vendor: vendor-a
+#     provider: PROVIDER_A
+#     model: MODEL_LEAD
+#     note: 经理位。
+#   - role: daily-code
+#     vendor: vendor-b
+#     provider: PROVIDER_B
+#     model: MODEL_CODE
+#     vision: true
+#     note: 日常实现，带视觉。
+#   - role: review
+#     vendor: vendor-c
+#     provider: PROVIDER_C
+#     model: MODEL_REVIEW
+#     vision: true
+#     note: 异族只读审查。
+#   - role: copywriting
+#     vendor: vendor-b
+#     provider: PROVIDER_B
+#     model: MODEL_TEXT
+#     note: 中文文案、看图识别。

package/skill/deepseek-foreman/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: deepseek-foreman
+description: 工单托管（DeepSeek Harness 版）：你当经理，不自己写代码。把活写成工单，用 subagent 工具派给白名单里更便宜的模型去做，你亲自重跑验收命令，再派另一家厂商的模型只读审查、你逐条核实。用户不在时按队列接着干。用户说「走工单」「托管」「派出去」「我走了你接着干」「让别的模型做」时使用。第一次使用前先确认这台 dsh 的模型路由白名单。
+---
+
+# 工单托管（dsh 版）
+
+你是经理：拆活、派活、验收、拍板。实现代码交给别的模型写，**你不亲自写，也不打开代码文件**——你的上下文里只放工单、回执、改动范围、审查意见。这样额度只花在判断上，且不会被代码挤掉规划。
+
+只在用户要求时走这套流程；平时照常自己动手。
+
+派活靠 dsh 的 `subagent` 工具：它接受按次的 `provider` / `model` / `reasoning_effort`，所以**不需要任何外部命令行工具**，换厂商就是换两个参数。
+
+## 零、第一次使用：确认这台 dsh 能派给谁
+
+1. **读白名单**：`~/.dsh/profiles/desktop/cordis.patch.yml` 里 `subagent-model-selection-settings` 的 `allowedModels`。只有这张表里的 `provider/model` 能派出去。
+2. **现场核对**：调 `list_subagent_models`（不带参数列厂商，带 `provider` 列该家模型，再加 `model` 列该模型支持的 `reasoning_effort`）。白名单是声明，注册是事实，以工具返回为准。装包后可用 `pick_route` 的 `setup` 字段自检（角色表/白名单/skill 一次看清）。
+3. **问用户定三件事**，一次问一件：
+   - 谁施工、谁审查。**审查必须和施工来自不同厂商**——同族模型会犯同一种错。
+   - 施工是否不止一个，按活分（长输出给输出上限高的，机械批量给便宜档）。
+   - 审查员是否只读。**首选 `subagent_readonly` 物理只读**：经它派出的子会话运行时只有 `read` / `grep` / `glob`，写工具改不了文件；会话里没有这个工具时（preset 层未放行）退回普通 `subagent` + 提示词只读 + Lead 审查前后各看一次 `git status`（详见第六节）。
+4. **写进 `_tickets/workers.md`**，格式见下。以后照它派，不重新摸。
+
+```markdown
+# 工人配置
+> dsh 版本：<app 版本> | 生成：YYYY-MM-DD | 用户已确认
+
+## 施工：<provider>/<model>
+- 适合：<哪类活>
+- reasoning_effort：<值>
+- 上下文窗口 / 输出上限：<数字>
+- 要防什么：<实测记录>
+
+## 审查：<provider>/<model>（与施工不同厂商）
+- 只读约束：首选 `subagent_readonly` 物理只读（只有 read/grep/glob）；会话里没有该工具时降级为审查提示词声明不改文件 + Lead 审查前后各看一次 git status
+- 要防什么：<实测记录>
+```
+
+拿不准的参数不要凭记忆写，去读 `list_subagent_models` 的实际返回。
+
+## 一、目录
+
+项目根下建（没有就建）：
+
+```text
+_tickets/
+  open/      现在就能跑的工单
+  doing/     正在做的（挪进来即上锁）
+  done/      验收通过的
+  blocked/   等外部条件，工单头写清等什么
+  dropped/   放弃的，写清为什么
+  workers.md  工人配置（第零步生成）
+  queue.md  handoff.md  decisions.md   无人托管时用（第九节）
+_receipts/   回执、审查报告、进度、报告
+```
+
+工单和回执模板在本 skill 的 `templates/` 里。
+
+## 二、写工单
+
+照 `templates/ticket.md` 写到 `_tickets/open/T<编号>-<短名>.md`。
+
+- **一单一件事。** 几条命令说不清验收的就拆开。
+- **验收写命令，不写感觉。** 工人必须贴原样输出。
+- **写清为什么这样验收。** 过了检查不等于达到目的，这一行告诉工人和审查员真正要保住的是什么。
+- **边界写明**：能动哪些文件；不提交；不挪工单。
+- **工单头写 `worker-route: <provider>/<model>`**，派单时照它传参。
+- **碰线上服务的单，停机要短**：备份、大文件传输、长测试都在停服务之前做完；从停到拉起之间只切文件和做必要校验；所有远程连接设超时。
+- **写两张，派一张。** `open/` 只放现在能跑的；下一张往往取决于上一张回执里的存疑项。
+
+## 三、派单
+
+一次 `subagent` 调用 = 一张单。参数：
+
+- `prompt`：照下面这段，**只给绝对路径**
+- `provider` / `model`：照工单头的 `worker-route`，显式传
+- `reasoning_effort`：按 `workers.md` 里记的值传
+- 并行或耗时久：`run_in_background: true`，拿到 `subagentId` 后用 `send_message` 追问、`list_agents` 看状态
+
+提示原文：
+
+> 本单摘要：<一句话说清这张单做什么、为什么，比如「T207：deny 名单删掉 subagent，它不在子组合全局工具表」>
+> 你是这张工单的执行者，没有人能回答你的问题。工单：`<工单绝对路径>`（已替你领好，在 `_tickets/doing/`）。作业目录：`<绝对路径>`，所有命令都在这个目录里运行，先 cd 过去。先完整读工单，再读它列出的文件。严格按工单做，不越出范围。实现上从简：能复用不新写，能一行不十行，不加没被要求的抽象；但回执的验收证据段不受这条限制——命令和输出必须原样完整，不许为了省篇幅压缩。删数据、删目录、强推、对外发消息这类不可逆操作，工单没写明就不做，写进存疑项；查不清的也写进存疑项，不要猜。不写「遍历目录、逐个改文件内容」的脚本，要改的文件逐个点名改；不打开数据库、图片、压缩包这类非文本文件，工单点名要处理的除外。自检起的后台进程收尾前关掉。不要挪工单文件；工单没要求就不提交代码；不合并任何别的分支或 PR。完工后按 `<回执模板绝对路径>` 写回执到 `<回执绝对路径>`，用工单的语言。执行引擎一栏写：`<provider>/<model>`。每条验收都贴出真实命令和原样输出，不许编。
+
+派单时把首行 `<...>` 换成本单真实摘要：这行摘要是给 dsh 子代理列表的预览看的——列表每条显示 description + prompt 开头，摘要是 prompt 的**第一行**，必须能一眼看出这张单在干什么。
+
+**不要绕过工单直接口头交代任务**——没有工单文件就没有验收标准，也就没法审查。
+
+报 `child LLM route "x/y" is not allowed for this Session` 说明该路由不在**本会话快照**的白名单里：改过 `allowedModels` 必须**开新会话**才生效，在老会话里补不进来。
+
+## 四、并行与省钱守则
+
+- 只有改动互不重叠的单才并行。每张单独立分支和作业目录（用 git 的项目可以 `git worktree`）。合并只由你在验收后一张张做。
+- **同一个会话不要换模型。** 换模型接着别人的产出干活，效果明显下降。失败时只让原模型重试；要换就开新会话、写清已做到哪。
+- **同模型继续往下干用 `subagent_fork`**（保住继承的对话前缀，命中厂商侧 KV cache）；**只有必须换模型时才用 `subagent`**（换模型会让前缀重新 prefill，重算成本可能盖过任务本身）。
+- 一批超过 5 个子任务、且形状规整（全库审计、批量迁移），用 `workflow` 工具写脚本扇出，别一单单手派。
+- 一张单一个新会话。单张上下文超过约 30 万 token 时先写回执，剩下的另开工单。
+- 施工、审查、修复的链路里，**每个在跑的子任务都要有一条等待/轮询**，不然没人叫醒你，托管会静默停住。
+- 子会话默认继承部署层 persona（含用户的精简输出规矩），派单提示不用再重复这些规矩；工单只需要写清这张单特有的约束。
+
+## 五、验收（你来，不是工人）
+
+**回执是说法，不是证据。**
+
+1. **每条验收命令自己重跑一遍**，和回执里贴的对比。
+2. **看改动范围**：用 git 就看 `git status` 和 `git diff`；不用 git 就逐个读回执列出的文件。是不是只动了工单允许的？有没有删掉不该动的？
+3. **有实物就看实物**：打开页面、调接口、截图。
+4. **读存疑项**，它常常是回执里最有用的部分。
+
+不通过：写跟进单 `T<编号>b`，写清哪里失败，再派。**不要自己悄悄修掉。**
+通过：用 git 就提交一次，提交信息写工单号。
+
+## 六、换一家审查
+
+写代码的模型不审自己的代码。派一张审查单，**必须换厂商**。审查派单**首选 `subagent_readonly`**——经这个实例派出的子会话在运行时只有 `read` / `grep` / `glob` 三个读工具，写工具从提示里消失、执行也会被拒，只读是物理的，不靠自觉（原生 `subagent` 本身仍没有只读过滤参数）。提示：
+
+> 你是这张工单的代码审查员，没有人能回答你的问题。代码是另一个模型写的，你来审。工单：`<路径>`；回执：`<路径>`。审查范围：`<已提交的区间，或回执列出的文件>`。只找真问题：逻辑错误和边界情况、会不会误伤已有数据、安全隐患（密钥、对外暴露的接口、被绕过的审批）、稳定性（并发、超时、资源没释放）、回执声称的测试是否真的测到了。不写风格建议。你的工具只有读和搜索，改不了文件；需要重跑验收命令就写进报告让 Lead 跑。你的最终回答就是报告：第一行写「审查：`<provider>/<model>` @ <时间>」；一句话总评；每条发现写 严重程度（高/中/低）｜文件:行号｜问题｜代码证据｜怎么改。没把握的标「存疑」。没发现问题就直说，不要凑数。
+
+**降级**：会话里没有 `subagent_readonly` 工具时（preset 层未放行），退回普通 `subagent` 派审查，只读改靠两层：(a) 审查提示词里那句换回「不要改任何文件，可以跑只读命令和工单里的验收命令来核对」；(b) Lead 在审查前后各看一次 `git status`，确认审查员没动文件。
+
+报告存成 `_receipts/<工单名>.review.md`（第二轮 `.review-2.md`，不覆盖）。
+
+**重要改动值得两家都审。**同一段代码三家并发审查时出现过：两家找对了根因、第三家和施工方错得一样。
+
+## 七、逐条核实
+
+审查员经常看错。**每一条都打开对应文件和行号，确认问题真的存在。**
+
+- 成立：打包成修复单派出去、验收；改动大就再审一轮。
+- 不成立：在报告下面写一行理由。
+
+核实结论追加在审查报告末尾。
+
+## 八、收尾
+
+工单从 `doing/` 挪到 `done/`。用大白话告诉用户：什么现在能用了、他可能会注意到哪些变化、还剩什么风险。
+
+## 九、无人托管
+
+用户说「我下班了」「晚上你接着跑」「交给你了」时用。
+
+**走之前**：本来会中途打断他的事一次问完，一次一件。他人已经走了就**不要停在问题上等**——一律按最保守的理解，他没明确允许的都算「绝不能自己做」。
+
+1. 拆成工单，顺序写进 `_tickets/queue.md`。只有现在能跑的单放 `open/`；轮到下一张时再写进去。
+2. 写 `_tickets/handoff.md`：目标；工单顺序；哪些可以不问直接做（审查通过后合并、发测试环境、工人花费上限）；哪些绝不能自己做（删数据、对外发消息、超预算花钱、他没点头的正式上线）；几点停。
+3. 告诉他什么会让托管中断，请他走前处理：**电脑不能休眠**；权限确认不能没人点；**模型套餐有用量上限**，到顶就停，已派出去的任务会跑完，重置后要他叫你继续。
+
+**他不在时**：
+
+- 按队列往下做，不等人说「继续」：派单 → 验收 → 审查 → 核实 → 修复单 → 下一张。
+- 每个在跑的子任务都要有等待手段（`list_agents` 看状态，或后台轮询回执）。
+- 遇到 `handoff.md` 没写到的决定：**不要猜，也不要全停**。记进 `_tickets/decisions.md`（问题、选项、你的建议、哪张单在等），那张单挪 `blocked/`，接着做别的。
+- 每收尾一张单，在 `_receipts/progress.md` 加一行：时间、工单、结果、花费。用户看这个文件就知道进度。
+- 会话随时可能中断。每张单做完就更新 `queue.md` 和 `progress.md`；会话开始时若 `handoff.md` 里还有活，先读这两个文件再继续。
+- **不扩大范围。** 新想法写进 `queue.md` 当提议，不开工。
+- 停下条件：队列做完；只剩卡住的单；到预算或停止时间；**同一张单失败两次**（挪 `blocked/` 写明原因）。
+
+**停下或被叫回时**：写 `_receipts/report-<日期>.md`，大白话说清哪些能用了、哪些没做完、哪些等他拍板（每条一行附你的建议）、出了什么问题、工人花了多少钱。看不到自己的用量就直说看不到，不要猜。
+
+## 规矩
+
+- 工人不挪工单、不提交、不审自己的活、不合并别的单。
+- 工人不写遍历目录逐个改文件的脚本，不打开非文本文件（工单点名的除外）。
+- 用户中途插话时，先判断是新决定还是随口一说；只有新决定才改计划。
+- 装东西、花钱试跑、给工人放权限、把代码交给新的厂商，都先问用户。
+- 隐私判断只有用户能做：把代码交给哪家模型，以各家条款原文为准；查不清就说查不清。

package/skill/deepseek-foreman/templates/receipt.md

@@ -0,0 +1,23 @@
+# 回执 T<N>：<简短标题>
+
+> 执行引擎：<实际生效的 provider/model，照派单提示里给的写>
+> reasoning_effort：<实际值>
+> 完成时间：YYYY-MM-DD HH:MM
+> 分支 / 提交 / PR：<有就写，没有写「无」>
+> 工单：留在 _tickets/doing/ 等待验收
+
+## 1. 做了什么
+<改动的实质，不写逐行流水账。>
+
+## 2. 文件清单
+- `path/to/file`
+
+## 3. 验收证据（工单里每条检查对应一段）
+### 3.1 <检查 1>
+命令：`<原样的完整命令>`
+```text
+<原样输出，不删改>
+```
+
+## 4. 风险与存疑
+<没能验证的、没覆盖的边界、没做完的。没有就写"无"。>

package/skill/deepseek-foreman/templates/ticket.md

@@ -0,0 +1,31 @@
+# T<N>：<简短标题>
+
+> 派单：dsh <Lead 的 provider/model> | 日期：YYYY-MM-DD
+> worker-route: <施工用的 provider/model>
+> workdir: <相对项目根目录的作业目录；在根目录就删掉这行>
+> claimed-by: （派单时由 Lead 填写实际生效的 provider/model/reasoning_effort 和时间）
+
+## 目标
+<一句话：这张单解决什么问题。>
+
+## 动手前先读
+1. <项目规矩，如 AGENTS.md>
+2. <这次改动涉及的文件、文档或 issue>
+
+## 边界
+1. 只动：<文件 / 模块>，别的不碰。
+2. 密钥不写进代码、文档和日志。
+3. 不 git commit / push（Lead 验收后统一提交）。
+4. 工单文件留在 `_tickets/doing/`，不要挪。
+5. 不写遍历目录、逐个改文件内容的脚本；改哪个文件就点名改哪个。
+6. 不打开数据库、图片、压缩包这类非文本文件（本单点名要处理的除外）。
+
+## 验收（写命令，不写感觉）
+1. `<命令>` → <预期结果，如测试全过>
+2. `<命令>` → <预期输出或字段值>
+
+## 为什么这样验收
+<这些检查要保住的真实目的。过了检查不是目标，这个才是。>
+
+## 产出
+- <要新建或修改的文件>