---
name: dev-pipeline
description: 开发者模式专用的后台流水线手册——用一句话创建的「极简模式 + 思考拉满」后台会话写代码、编译、Debug，并读回它的结果。当你在开发者模式里要把计划交给后台会话实现、或把测试问题交回去修时使用。
whenToUse: 开发者模式里进入第 3 步（后台开工）或第 5 步（交回 Debug）时。
---

# 开发者模式 · 后台流水线手册

本手册只干一件事：**把计划交给一个后台的极简模式会话（思考强度=完全）去写代码/编译/修 bug，然后把它做完了什么读回来。**

下面命令里的 `<技能目录>` 指本次加载技能时给出的目录。命令里的路径**一律加引号**（本机路径含空格）。

需要更深的机制说明（认证怎么签的、每个 RPC 的精确字段、为什么是 540 秒、哪些行为尚未实测）时，读 `references\troubleshooting.md`——平时不用读。

## 1. 一条命令速查

```powershell
# 自检：凭据、本机 /api、极简模式在不在、思考档位可不可用、流程条款有没有生效（不建会话、不发消息，10 秒）
#   → 退出码 0 才继续；退出码 3 时看输出里 CHECK=…MISSING 的行，那是没通过的那一条
node "<技能目录>\scripts\coder.mjs" selfcheck

# 开工时会先做一次"探活"（只让它读一行文件）；若被权限/沙箱挡住，会自动改用完全放开权限
# 重开一次并打印 DEVPERMFALLBACK=1。想跳过探活加 --no-probe。

# 开工（第 3 步）：建后台极简会话 → 思考设为完全 → 发计划 → 等它做完这一轮
node "<技能目录>\scripts\coder.mjs" start --cwd "<工程目录绝对路径>" --plan-file "<plan.md 绝对路径>" --title "<白话标题>" --deadline-sec 540

# 交回 Debug（第 5 步）：把测试报告发给同一个会话，让它逐条修
node "<技能目录>\scripts\coder.mjs" send --session <会话id> --issues-file "<qa 报告绝对路径>" --deadline-sec 540

# 继续等（退出码 2 之后用）
node "<技能目录>\scripts\coder.mjs" wait --session <会话id> --deadline-sec 540

# 只看不做：读回会话最近几轮汇报
node "<技能目录>\scripts\coder.mjs" read --session <会话id> --tail 3

# 本机记录过的后台会话一览（含是否还在跑）
node "<技能目录>\scripts\coder.mjs" list
```

可选参数：`--model`、`--provider`、`--effort`（默认 `max`，即"完全"）、`--permission <档位>`（默认**不动**权限，继承部署默认）、`--no-wait`、`--force`、`--stall-sec`。

## 2. 等待协议（重要，别把"还在跑"当成失败）

- 单次前台命令最多跑 10 分钟就会被转成后台作业，所以脚本自己按 `--deadline-sec`（默认 540 秒）返回。
- **退出码 2 = 还在跑，不是失败**：再跑一次 `wait --session <id>` 继续等，可以一直续。整段等待**不要每秒轮询**，每次续等只产生一个新步骤。
- 后台会话跑在 DSH 服务端，脚本被杀、页面关掉都不影响它的进度；所有进度都能从 `<工程目录>\.dsh-dev\status.json` 和 `session/list` 重新读出来。
- 退出码 5 = 超过 `--stall-sec`（默认 **300** 秒，比 `--deadline-sec` 的 540 秒短，这样"卡住"一定会先于"超时"发生）没有任何新动静。脚本会多打一行 `DEVHINT=`，**按运行时读到的权限档位分岔**：档位不是完全放开 → 多半在等批准，提示用户点开那个会话；档位已是完全放开 → 不是等批准，用 `read --tail 3` 看它卡在哪，必要时补一条纠正指令或本会话接手。别自己反复重试。

## 3. 脚本输出契约（照着解析，别猜）

每次命令最后都会打印这些稳定行：

| 行 | 含义 |
| --- | --- |
| `DEVSESSION_ID=<id>` | 后台会话 id，后面 `send`/`wait`/`read` 都用它 |
| `DEVSTATUS=done\|running\|stalled` | done=这一轮做完了；running=还在跑；stalled=半天没动静 |
| `DEVRESULT=OK\|FAIL\|UNKNOWN` | 后台会话自己报的结果（FAIL 时退出码 4） |
| `DEVTURNS=<n>` / `DEVTOOLCALLS=<n>` | 轮数 / 这一轮的工具调用次数 |
| `DEVLOG=<路径>` | 这一轮完整事件流，排查时才看它，别整份贴给用户 |
| `DEVPRESET` / `DEVMODEL` / `DEVPERM` / `DEVTOKENS` | 实际生效的模式、模型与强度、权限、用量（可用它给用户报一句"大概花了多少"） |

`--- 后台会话最后一段汇报 ---` 之后的正文就是它说的人话汇报。

退出码：`0` 完成 ｜ `2` 还在跑（续 wait） ｜ `3` 配置/认证/参数错 ｜ `4` 后台会话自报失败 ｜ `5` 长时间无进展。

## 4. 它落在你工程目录里的东西

`<工程目录>\.dsh-dev\`：`plan.md`（你自己写的计划）、`review-*.md`、`qa\qa-*.md`、`status.json`（进度）、`logs\coder-*.json`（完整事件流）、`backup-*`（改已有程序前的备份）。这些都是过程记录，交付时告诉用户可以删掉、不影响程序使用。脚本还会在工程目录已有 `.gitignore` 时**追加**一行 `.dsh-dev/`（只追加，不覆盖，不新建文件）。

## 5. 出问题时怎么办

| 现象 | 含义与做法 |
| --- | --- |
| 退出码 3，`连不上本机 /api` | `dsh web` 没在跑，或 `DSH_WEB_URL` 不对。白话告诉用户"后台通道用不了"，本会话自己按计划实现（降级，不要卡住） |
| 退出码 3，凭据相关 | `~\.dsh\.credentials.yaml` 里没有 browser-session 密钥。同上降级 |
| 退出码 3，`工程目录不存在` | 自己先用 pwsh 把工程目录建好再跑 |
| 退出码 3，`已经有一个后台会话在跑` | 同一项目不并发：等那个会话结束，或确认要另开再 `--force` |
| 退出码 4（DEVRESULT=FAIL） | 看 `DEVLOG` 最后一段：多半是缺依赖或命令不对。自己补装依赖、把确切构建命令写回 plan.md，然后 `send` 让它重来 |
| 退出码 5 | 脚本会打印 \`DEVHINT=\`，按**运行时读到的权限档位**分岔：不是完全放开 → 提示用户点开那个会话批准一次；已是完全放开 → 不是等批准，用 \`read --tail 3\` 定位或本会话接手 |
| `session/create failed: ...` | 参数被网关拒了：`cwd` 与 `workspaceId` 不能同时给；模式只在空白会话可设 |
| 后台会话里的人话汇报是空的 | 用 `read --tail 3` 或看 `DEVLOG`；仍为空就告诉用户"点进那个会话看" |

## 5.5 深度自检（可选）

- `node "<技能目录>\\scripts\\coder.mjs" preflight [--force]`：真建一个极简会话，让它跑一遍最基础的环境检查，确认这条通道真的能用。
- 结果缓存在 `$DSH_HOME\\dev-mode\\preflight.json`：只有**版本一致 + 上次真的跑完且成功**才复用；缓存损坏或版本变了会自动重跑。
- 它会新建一个会话并在结束时归档。平时不用跑，怀疑通道有问题时跑一次。

## 6. 第 0 步体检怎么做

- 开工先跑 `selfcheck`（只读，不建会话）。它检查：生效地址与来源、模式名单里有没有 `minimal` 和 `dev`、思考档位在不在、部署默认模型可不可用、**流程条款有没有真的生效**、当前权限档位。
- 退出码 0：把结果写进 `plan.md` 的「## 开工体检」小节，继续。
- 退出码 3 分两种：通道类（连不上、凭据读不到）→ 一句话告诉用户「后台通道现在用不了」，然后本会话按计划自己做；条款类（`CHECK=persona:…MISSING`）→ 本机还在用旧版本插件，按 README 的「先移除、再安装」重装，或重启 DSH 应用。

## 7. 改完这个插件，怎么验证真的生效

- 判据不是「文件改了」，而是「读回的真实生效内容里有新条款」：读 `agentPresets/read { agentPreset: "dev" }`，比对 `coder.mjs` 里的 `REQUIRED_MARKERS`（13 条）；`selfcheck` 已自动做这件事。
- 不重启也想确认加载器能否正确组合：`dsh --profile <名> --dump-config`，在输出里搜标记即可（有 YAML / `!!js` 问题会在这里报错）。
- 生效范围：只对**新开的会话**；现有会话保持原组成。

## 8. 禁忌

- 不要给同一个项目并发开多个后台会话；不要给一个会话连发多条消息（每次都会消耗一轮）。
- 不要往后台会话发"你好""在吗"这类消息：它只认计划和问题清单。
- 不要用归档来停止任务（归档会连带中断正在跑的轮次）；要停就停自己的等待，或者让用户去会话里点停止。
- 不要改用户其他会话、不要动别人的工程目录。