dsh-plugin-teamflow 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -2,16 +2,36 @@
 
 > 本插件首次公开发布版本为 **v0.1.0**；发布前的内部迭代（v0.3~v0.13）记录于 `AGENTS.md` §5，对外统一归到 v0.1.0。
 
+## [0.1.3] - 2026-08-29
+
+### 新增
+- **分支策略闭环（ADR-2026-08-27）**：启动前用户决策（`needs-decision` 四情况：main+干净/main+脏/feature+干净/feature+脏，stash/commit/新建/沿用/自定义兜底）；`branchPolicy`/`branchName`/`preAction`/`commitMessage` 决策参数；auto=建 `feat/<slug|branchName>`、keep=沿用；`preAction`（stash/commit）在 sanity 前执行
+- **收尾合回决策（对称交互）**：完成汇报带「合回决策邀请」，新工具 `teamflow_merge`（host 代为合回 / 给命令自行合回 / 暂缓）；`journal.mergeStatus` 持久化（pending/merged/kept/failed）
+- **统一收口提交**：子代理只改不提交（Git discipline 硬约束），host 验收通过后单 commit（代码+任务夹产物）；结构性消灭文档漏提交与未验收中间态
+- **视觉验证能力条件化**：`llm.resolveModelInfo` 探测模型多模态能力 → QA/验收视觉条款动态生成（支持视觉=DOM 计算断言+截图看图+人工收窄；不支持=禁截图看图防幻觉/循环，只走 DOM 断言）；QA 人工补测清单收窄为音频/真机/FPS/读屏
+- **需求意图预检**：疑问/建议/反馈句式（「是不是应该」「要不要」等）→ `needs-confirmation` 不启动，主线程先向用户确认
+- **activeTeams 持久化**：会话→团队映射落盘，重启/刷新后恢复（UI 状态与启动通道一致）
+
+### 修复
+- **护栏注入通道**：`subagents.start` 句柄无 inject → 改用 DSH 官方 `session.append('user/message')`；注入改安全窗口（step/end 后 flush，防插进 tool_calls→tool/result 序列导致 provider 400，实测 tf-mtcnejqj 烧 1.98M）
+- **复读检测重复计数 bug**：轮询重复收集事件导致计数虚增（实际 4 次 × 3 轮 = 12 压线误杀，实测 tf-mtcomxpq 开发两次）→ 增量收集
+- **`isUnretryable` 覆盖 400/invalid_request**（provider 客户端拒绝不再重试烧钱）
+- **开发任务全部失败停止流水线**（无产物可测时不再继续 QA 误测；部分失败仍继续）
+- **resume 断点按阶段定位**（PRD 重试成功后不再被失败尝试带回重跑）
+- **分支 slug 派生**（branchName > triageSlug > 需求英文词 > r<N> > feature；分支检查移到 initBacklog 之后）
+- **journal.options 透传 branchPolicy 等决策参数**（keep 不再被吞，实测 tf-mtd6mbeq）
+- **DSH 0.1.2-alpha.1 事件词汇适配**（text-chunks/reasoning-chunks → assistant/chunk 双兼容）；schema 校验兼容（needs-decision 不返回 runId 字段）
+
+### 其他
+- 执行路径基准（小需求样本）与假优化判定收敛：`docs/benchmarks/hold-pipeline-vs-native.md`（多花 44% 是质量预算非浪费，cacheRead 命中价≈1/10）
+
 ## [0.1.2] - 2026-08-26
 
+### 修复
+- host 就绪日志工具数改为动态计数（消除「工具 8 个」写死文案，与实际注册数一致）
+
 ### 变更
-- 提示词指令层英文化（方案 A）：指令英文 + 输出契约中文（PRD 头部声明 / QA 缺陷表 / 验收结论等解析器锚点不变）；工具描述英文化
-- backlog 卡片 / 详情抽屉跳转指定 run 的流水线视图（host `backlog` 附带 `runId` 映射）
-- 详情抽屉长文本折叠（概览 / 需求原文默认预览几行，可展开收起）
-- 断点重跑语义修正：阶段全 done 的 failed/cancelled 不再显示续跑按钮（host 硬拒绝兜底）；按钮/pill/chip 补 runId 全名可溯
-- 架构蓝图提取回退任务夹 `TECHNICAL.md`（模型把蓝图写进文档而非回复输出时 M2 拆卡不再退化为整体开发）
-- `meta.json` 改为静态标识卡（废弃终态回写，status/endedAt 权威在 journal）
-- 开源发布元数据：keywords / homepage / bugs；`react` 移入 peerDependencies；README.en.md 与 CHANGELOG.md 显式进包
+- 开源发布收尾：README 中英双语修正（架构计数 17/11、防假交付真实语义、快速上手、环境要求）；npm 元数据（keywords / homepage / bugs）；`react` 移入 peerDependencies + `peerDependenciesMeta`（防私有包 ERESOLVE）；CI 触发扩展 `main` + `release-*`；构建关闭 sourcemap（npm 包 -58%）；新增 SECURITY.md / CONTRIBUTING.md；deploy 同步清单移除 `.map`
 
 ## [0.1.1] - 2026-08-26
 

package/lib/host.mjs

@@ -4,8 +4,8 @@ import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import { parameterSchemaSpecToJsonSchema } from "@deepseek-ai/dsh-tools";
 import { dirname, join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { createUserMessage } from "@deepseek-ai/dsh-llm";
 import { execFileSync } from "node:child_process";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
 //#region host/constants.ts
 /** 单阶段 token 熔断预算（官方口径总消耗：input+cacheRead+cacheWrite+output 累计）。 */
 const STAGE_TOKEN_BUDGET = 6e4;
@@ -260,6 +260,17 @@ const SAFE_SIGNAL = {
 function normalizeSignal(s) {
 	return s && typeof s === "object" && typeof s.addEventListener === "function" && typeof s.aborted === "boolean" ? s : SAFE_SIGNAL;
 }
+/** 分支 slug 派生（ADR-2026-08-27）：branchName > triageSlug > 需求中的英文标识词 > reqId 数字 > 'feature'。
+* 实锤 feat/feature：lite 显式时 triage 不跑（无 slug）+ 分支检查早于 reqId 生成 → fallback 'feature'。 */
+function deriveBranchSlug(requirement, reqId, triageSlug, branchName) {
+	if (branchName && /^[a-z0-9][a-z0-9-_]*$/i.test(branchName)) return String(branchName).replace(/[^a-z0-9-]/gi, "-").toLowerCase().slice(0, 40);
+	if (triageSlug && /^[a-z0-9-]{3,24}$/i.test(triageSlug)) return triageSlug;
+	const en = String(requirement || "").match(/[a-zA-Z][a-zA-Z0-9-]{2,23}/g);
+	if (en && en.length) return en[0].toLowerCase().slice(0, 40);
+	const num = String(reqId || "").match(/\d+/);
+	if (num) return `r${num[0]}`;
+	return "feature";
+}
 /** 产出物实质校验：非空 + 无拒绝词 + 达到阶段长度下限。 */
 function hasSubstance(phase, text) {
 	if (!text || !text.trim()) return false;
@@ -267,10 +278,11 @@ function hasSubstance(phase, text) {
 	const min = STAGE_MIN_LENGTH[phase] ?? 100;
 	return text.trim().length >= min;
 }
-/** 不可重试的失败原因（上下文耗尽/超长等——重试同一 prompt 大概率复现）。 */
+/** 不可重试的失败原因（上下文耗尽/超长/provider 客户端拒绝等——重试同一 prompt 大概率复现）。
+* 实锤 tf-mtcnejqj：opencode-go 400 invalid_request_error（tool 消息序列非法）被当作可重试 → 烧 1.98M 熔断。 */
 function isUnretryable(reason, outcome) {
 	const r = String(reason || outcome || "");
-	return /context|limit|max-token|token|tool-error/i.test(r);
+	return /context|limit|max-token|token|tool-error|400|invalid_request|INVALID_REQUEST/i.test(r);
 }
 /** 阶段产出 → 精简交接摘要（供审计/展示；产出含显式 <!-- handoff --> 块则优先取块内内容）。 */
 function handoffBrief(text) {
@@ -381,12 +393,13 @@ function extractBlueprint(text) {
 */
 /** 子代理/计量等宿主能力（由 TeamflowService 装配时 setRuntime 注入）。字段为鸭子类型：消费方自行窄化。 */
 const runtime = {};
-function setRuntime(agents, subagents, tokenMeter, workspaceRegistry, agentDefaultModel) {
+function setRuntime(agents, subagents, tokenMeter, workspaceRegistry, agentDefaultModel, llm) {
 	runtime.agents = agents;
 	runtime.subagents = subagents;
 	runtime.tokenMeter = tokenMeter;
 	runtime.workspaceRegistry = workspaceRegistry;
 	runtime.agentDefaultModel = agentDefaultModel;
+	runtime.llm = llm;
 }
 /** 运行期 run 注册表（runId → Journal）。 */
 const runs = /* @__PURE__ */ new Map();
@@ -405,6 +418,32 @@ function providerName() {
 	return names.length > 0 ? names[0] : null;
 }
 /**
+* 探测指定 provider/model 是否支持图像输入（多模态）。
+* 用途：QA/验收的视觉验证条款按能力条件化——不支持视觉的模型禁止「截图看图」（防幻觉/循环），
+* 只走 DOM 计算断言（evaluate 返回文本）；探测失败/未知 → false（安全侧）。
+*/
+async function currentModelSupportsVision(provider, model) {
+	try {
+		const llm = runtime.llm;
+		if (!llm || typeof llm.resolveModelInfo !== "function") return false;
+		const p = provider && provider.trim() || providerName();
+		const m = model && model.trim() || (() => {
+			const adm = runtime.agentDefaultModel;
+			if (adm && typeof adm.currentSelection === "function") try {
+				return adm.currentSelection()?.model;
+			} catch (e) {
+				return;
+			}
+			return adm?.model;
+		})();
+		if (!p || !m) return false;
+		const info = await llm.resolveModelInfo(p, m);
+		return !!info && Array.isArray(info.inputModalities) && info.inputModalities.includes("image");
+	} catch (e) {
+		return false;
+	}
+}
+/**
 * 从发起会话推导工作区作用域。
 *
 * 优先级：
@@ -1030,6 +1069,79 @@ function getActiveStages(team, options) {
 	});
 }
 //#endregion
+//#region host/core/sanity.ts
+/**
+* dsh-plugin-teamflow core — M0 状态核对（sanity check）。
+*
+* 目的（三情况协议）：
+* - 情况一（全新会话）：0 认知 → 核对确认"从零开始"。
+* - 情况二（续会话）：认知大概率过期（多人协作/场外提交/非流水线改动）→ 核对发现预期外变化。
+* - 情况三（新会话处理新需求）：即使共用 state/记忆，仓库也可能被外部改动 → 核对现状。
+*
+* 核心原则：认知资产（索引/记忆/摘要）可复用"减量"，但永不能替代"对代码库当前真实状态的核对"。
+* 本模块在 host 侧直接跑 git（零模型 token、轻量、失败优雅降级为"无法核对"），
+* 产出 externalDiffs 摘要注入到后续所有阶段 prompt。
+*/
+/** 单条 git 检查结果（失败返回 null，调用方降级）。 */
+function gitCmd(cwd, args, timeoutMs = 8e3) {
+	try {
+		return execFileSync("git", args, {
+			cwd,
+			encoding: "utf8",
+			timeout: timeoutMs,
+			windowsHide: true
+		}).trim();
+	} catch (e) {
+		return null;
+	}
+}
+/**
+* 跑一次状态核对。
+* @param path - 工作区绝对路径（workspaceScopeOf(agent).path）。
+*/
+function runSanityCheck(path) {
+	const defaultOut = {
+		ok: false,
+		inRepo: false,
+		branch: null,
+		dirty: "",
+		hasDirty: false,
+		recentCommits: "",
+		summary: ""
+	};
+	if (!path) return {
+		...defaultOut,
+		summary: "⚠ 无法确定工作区路径，未做状态核对。"
+	};
+	const branch = gitCmd(path, ["branch", "--show-current"]);
+	const status = gitCmd(path, ["status", "--short"]);
+	if (branch === null && status === null) return {
+		...defaultOut,
+		summary: "⚠ 状态核对不可用（非 git 仓库或 git 命令被拒），无法确认代码库真实状态。"
+	};
+	const recent = gitCmd(path, [
+		"log",
+		"--oneline",
+		"-5"
+	]);
+	const dirty = status || "";
+	const dirtyLines = dirty.split("\n").filter(Boolean);
+	const summaryParts = [];
+	summaryParts.push(`分支：${branch && branch !== "HEAD" ? branch : "(detached HEAD / 非分支)"}`);
+	if (dirtyLines.length) summaryParts.push(`未提交改动 ${dirtyLines.length} 处：${dirtyLines.slice(0, 8).join("；")}${dirtyLines.length > 8 ? "…" : ""}`);
+	else summaryParts.push("工作区干净（无未提交改动）");
+	if (recent) summaryParts.push(`近期提交（可能含场外改动）：${recent.split("\n").slice(0, 3).join("；")}`);
+	return {
+		ok: true,
+		inRepo: true,
+		branch: branch && branch !== "HEAD" ? branch : null,
+		dirty,
+		hasDirty: dirtyLines.length > 0,
+		recentCommits: recent || "",
+		summary: `【状态核对】${summaryParts.join("。")}`
+	};
+}
+//#endregion
 //#region host/core/metering.ts
 /**
 * 累计子代理会话中所有 LLM 调用的真实 usage（官方三桶 + 调用数）。
@@ -1106,6 +1218,38 @@ function eventsOf(run) {
 function normalizeFragment(s) {
 	return String(s || "").toLowerCase().replace(/[^a-z0-9\u4e00-\u9fa5]+/g, "");
 }
+/** 观测→执行闭环：向运行中的子代理注入轻提醒（不打断，下一轮 step 可见）。
+* 通道：subagents.start 句柄无 inject——用 DSH 官方 session.append('user/message')（in-process driver 同款用法）。
+* ⚠️ 安全窗口（实锤 tf-mtcnejqj）：绝不能插在 assistant(tool_calls) → tool/result 之间——
+* provider 校验「tool 消息必须响应前序 tool_calls」，插入 user 消息会 400 invalid_request_error。
+* 因此只入队（pendingInjects），在观察到 step/end（该 step 的 tool/result 已写入）后统一 flush。 */
+function injectReminder(run, text) {
+	const queue = run;
+	try {
+		if (!Array.isArray(queue.__teamflowPending)) queue.__teamflowPending = [];
+		queue.__teamflowPending.push(text);
+	} catch (e) {}
+}
+function flushReminders(run) {
+	try {
+		const queue = run.__teamflowPending;
+		if (!queue || queue.length === 0) return;
+		const local = run.localAgent;
+		if (!local || typeof local.session?.append !== "function") return;
+		for (const text of queue.splice(0)) local.session.append("user/message", {
+			id: crypto.randomUUID(),
+			role: "user",
+			content: [{
+				type: "text",
+				text
+			}],
+			source: {
+				kind: "plugin",
+				plugin: "teamflow"
+			}
+		}, { surfaceOp: "append" });
+	} catch (e) {}
+}
 /**
 * 启动单调用护栏轮询，返回取消函数（runAgent finally 必须调用）。
 * 触发时：stage.guardReason/guardOutcome 记录原因 + journal 落日志 + dispose 中止本次尝试。
@@ -1123,7 +1267,7 @@ function startStageGuard(opts) {
 	const warnedReads = /* @__PURE__ */ new Set();
 	const scriptCounts = /* @__PURE__ */ new Map();
 	const warnedScripts = /* @__PURE__ */ new Set();
-	function warnOnce(key, set, message) {
+	function warnOnce(key, set, message, hint) {
 		if (set.has(key)) return;
 		set.add(key);
 		try {
@@ -1133,6 +1277,7 @@ function startStageGuard(opts) {
 				message: `${label} [token 观测] ${message}`
 			});
 		} catch (e) {}
+		if (hint) injectReminder(run, `[TOKEN GUARD · reminder] ${hint}`);
 	}
 	function fire(reason, outcome) {
 		if (fired) return;
@@ -1155,24 +1300,35 @@ function startStageGuard(opts) {
 		if (fired || journal.cancelled) return;
 		try {
 			const events = eventsOf(run);
-			for (const ev of events.slice(-400)) {
-				const e = ev;
-				if (!e || e.type !== "text-chunks" && e.type !== "reasoning-chunks") continue;
-				const arr = e.data && e.data.texts || e.texts;
-				if (!Array.isArray(arr)) continue;
-				for (const t of arr) {
-					const s = normalizeFragment(String(t));
-					if (s.length < 12) continue;
-					window.push(s);
+			if (events.length > processed) {
+				const newEvents = events.slice(processed);
+				for (const ev of newEvents) {
+					const e = ev;
+					if (!e) continue;
+					let streamText = null;
+					if (e.type === "text-chunks" || e.type === "reasoning-chunks") {
+						const arr = e.data && e.data.texts || e.texts;
+						if (Array.isArray(arr)) streamText = arr.map(String).join("");
+					} else if (e.type === "assistant/chunk") {
+						const chunk = e.data && e.data.chunk || null;
+						if (chunk && (chunk.type === "text-delta" || chunk.type === "reasoning-delta") && typeof chunk.text === "string") streamText = chunk.text;
+					}
+					if (streamText !== null && streamText.length > 0) {
+						const s = normalizeFragment(streamText);
+						if (s.length >= 12) window.push(s);
+						lastGrowthAt = Date.now();
+					}
 				}
-				lastGrowthAt = Date.now();
-			}
-			if (window.length > 400) window.splice(0, window.length - 400);
-			const counts = /* @__PURE__ */ new Map();
-			for (const w of window) counts.set(w, (counts.get(w) || 0) + 1);
-			for (const [, n] of counts) if (n >= 12) {
-				fire(`推理复读（同一片段在近 ${window.length} 条流式片段中出现 ${n} 次）`, "degenerated");
-				return;
+				if (window.length > 400) window.splice(0, window.length - 400);
+				const counts = /* @__PURE__ */ new Map();
+				for (const w of window) counts.set(w, (counts.get(w) || 0) + 1);
+				for (const [, n] of counts) if (n >= 12) {
+					fire(`推理复读（同一片段在近 ${window.length} 条流式片段中出现 ${n} 次）`, "degenerated");
+					return;
+				}
+				observeToolCalls(newEvents);
+				if (newEvents.some((ev) => ev?.type === "step/end")) flushReminders(run);
+				processed = events.length;
 			}
 			for (const ev of events.slice(-200)) {
 				const e = ev;
@@ -1182,10 +1338,6 @@ function startStageGuard(opts) {
 					break;
 				}
 			}
-			if (events.length > processed) {
-				observeToolCalls(events.slice(processed));
-				processed = events.length;
-			}
 			if (events.length !== lastEventCount) {
 				lastEventCount = events.length;
 				lastGrowthAt = Date.now();
@@ -1213,14 +1365,14 @@ function startStageGuard(opts) {
 				const key = m[1].replace(/\\\\/g, "\\").toLowerCase();
 				const n = (readCounts.get(key) || 0) + 1;
 				readCounts.set(key, n);
-				if (n === 3) warnOnce(key, warnedReads, `同一文件重复 read ${n} 次：${m[1].split(/[\\\\/]/).pop()}（TOKEN_HYGIENE 上限 1 次，多余读取在为后续每一步付 cache 重放费）`);
+				if (n === 3) warnOnce(key, warnedReads, `同一文件重复 read ${n} 次：${m[1].split(/[\\\\/]/).pop()}（TOKEN_HYGIENE 上限 1 次，多余读取在为后续每一步付 cache 重放费）`, `你已整读 ${m[1].split(/[\\\\/]/).pop()} 第 3 次（TOKEN_HYGIENE 上限 1 次）。停止整读：需要确认细节时用 grep 定位行号 + 限量片段读取。`);
 			} else if (/bash|pwsh|shell|powershell/i.test(name || "")) {
 				const sm = String(args).match(/(verify-[a-z0-9-]+\.cjs|assembly-check\.cjs|qa-e2e-jsdom\.cjs)/);
 				if (!sm) continue;
 				const key = sm[1];
 				const n = (scriptCounts.get(key) || 0) + 1;
 				scriptCounts.set(key, n);
-				if (n === 3) warnOnce(key, warnedScripts, `验证脚本重复执行 ${n} 次：${key}（批量修复纪律：一次修完所有失败再跑，≤3 轮）`);
+				if (n === 3) warnOnce(key, warnedScripts, `验证脚本重复执行 ${n} 次：${key}（批量修复纪律：一次修完所有失败再跑，≤3 轮）`, `验证脚本 ${key} 已重复执行 3 次。遵守批量修复纪律：一次读完所有失败用例 → 一次全修 → 再跑一次；超出 3 轮请输出诊断摘要并停止。`);
 			}
 		}
 	}
@@ -1889,10 +2041,24 @@ ${clip(tech, 12e3)}` : ""}
 3. If spec contradicts reality, explain with evidence in the summary instead of claiming completion or expanding scope on your own.
 4. Actually write/modify code (grep + segmented reads to locate; no repeated whole-file reads), then run relevant build/verification to ensure green.
 5. [Engineering action execution] If task spec or PRD 工程约束 includes git actions (e.g. new branch): **execute the action BEFORE writing code** (e.g. git checkout -b <branch>); if the workspace carries unrelated uncommitted changes, do NOT commit/clean them — state the situation in the summary.
+5b. [Git discipline · hard (ADR-2026-08-27, 统一收口提交)] Work ONLY on the current branch: **never** git checkout main / merge / rebase / delete-branch / commit — main-branch actions and the final commit are performed by the host after acceptance (one commit per run: code + task-folder docs together). Just write/modify files; leave everything uncommitted. If a task asks for "merge back to main" or "commit", treat it as "prepare the delivery" (files ready + summary of what was done), do NOT commit or merge.
 6. [Log discipline] Redirect command output to logs/teamflow/${runId || "<runId>"}/.
 7. Output an implementation summary (≤40 lines): changed files, key implementation points, how verified, leftovers. No big code pastes.
 8. [State] End with a state block (phase="dev"), touched = array of changed files, summary = implementation conclusion.${STATE_BLOCK_INSTRUCTION}`;
-const qaPrompt = (prd, devSummary, root, runId, state) => `You are a senior QA test engineer. The current workspace IS the target project — functionally test this delivery.
+/** 视觉验证能力条款（ADR-2026-08-27，解锁 browser-use 视觉验证）：
+* 按当前模型多模态能力动态生成——vision=true 允许截图看图（人眼类项），精确值仍走 DOM 计算断言；
+* vision=false 禁截图看图（防幻觉/循环，历史禁令动机=模型不识图），只走 DOM 计算断言（evaluate 返回文本）。
+* 两者都要求：浏览器失败降级不重试。 */
+const VISUAL_POLICY = (vision) => vision ? `[Visual verification · enabled (model supports image input)]
+- Real-browser visual verification IS allowed: launch the page (headless browser / browser-use) and verify layout/pixel/overlay/occlusion items by screenshot + reading the image.
+- **Scripted assertions first** (exact values must come from DOM computation, not eyeballing): evaluate offsetWidth/scrollWidth/clientHeight for overflow, getComputedStyle for exact colors/visibility, element sizes & ratios (e.g. 1:2). Assert on those numbers/strings.
+- Screenshot checks are for human-eye items only: overlay occlusion, animation feel, layout reasonableness. Save screenshots under the task folder (docs/teamflow/.../qa/) for acceptance & human review.
+- On browser launch failure: degrade to jsdom/scripted checks + list remaining items in 「人工补测清单」; do NOT retry more than once.` : `[Visual verification · limited (current model has NO image input)]
+- You CANNOT interpret screenshots (no image input) — do NOT take screenshots to "look" at them (waste loop); do NOT guess layout/pixel state from screenshots.
+- Scripted DOM assertions ARE allowed and preferred: launch the page headless and evaluate TEXT values only — overflow (scrollWidth <= clientWidth), exact colors via getComputedStyle, visibility, element sizes/ratios. Assert on those numbers/strings.
+- Visual-judgment items (occlusion, animation feel, layout aesthetics) that cannot be asserted via DOM values: list them in 「人工补测清单」 (acceptance criterion + method + tool), note「环境限制，非交付缺陷」; do NOT guess, do NOT retry.
+- On any browser failure: degrade to jsdom + 「人工补测清单」, do not retry.`;
+const qaPrompt = (prd, devSummary, root, runId, state, vision) => `You are a senior QA test engineer. The current workspace IS the target project — functionally test this delivery.
 ${productCtx(root)}${stateSliceFor(state, "qa")}${TOKEN_HYGIENE(runId)}[PRD (this change & relevant ACs)]
 ${headTailClip(prd, 5e3, 7e3)}
 [DEV RESULT SUMMARY]
@@ -1902,8 +2068,9 @@ ${clip(devSummary, 15e3)}
    - If the injected blueprint JSON ("<!-- blueprint -->") is present, verify the implementation follows it (was the to-be-extracted module extracted? deps/assembly per blueprint? any deviations?).
    - Check for **duplicated implementations** (e.g. multiple security wrappers/storage/adapter utilities drifting), **abstraction not extracted where it should be**, **obviously broken existing structure**.
    - Report architecture findings in the defect table format (severity P1, module =「架构」). This is part of the delivery quality gate, not just functional bugs.
-1. [Environment limits · don't waste effort] The sandbox forbids launching CDP-driven Chrome/Edge: real-browser automation (Playwright/Puppeteer/chromedriver/--remote-debugging-port), audio/pixel/timing/multi-browser/screen-reader checks are ALL impossible — this is a policy refusal, not a broken command; don't try, don't retry with alternative tools. Verification must use sandbox-legal paths: build/assembly checks, unit tests, DOM-level E2E (jsdom or equivalent), static audit, adversarial spot-checks.
-2. Acceptance items that cannot be auto-tested (audio/pixel/real timing/dual resolution/offline multi-browser/screen reader etc.): do NOT fail them — instead list each in the report's「人工补测清单」section (acceptance criteria + method + tool), note「环境限制，非交付缺陷」, for human review.
+1. [Environment limits · dynamic by model capability]${VISUAL_POLICY(!!vision)}
+   - Always-available sandbox-legal paths: build/assembly checks, unit tests, DOM-level E2E (jsdom or equivalent), static audit, adversarial spot-checks.
+2. [人工补测清单] Items that cannot be auto-verified (audio output / real-device: 100dvh dynamic toolbar, safe-area, multi-touch / FPS performance / screen-reader): do NOT fail them — instead list each in the report's「人工补测清单」section (acceptance criteria + method + tool), note「环境限制，非交付缺陷」, for human review.
 3. Read AGENTS.md §4 engineering conventions (verify commands) and the code changes first, then actually run those sandbox-legal verifications.
 4. [Log discipline] Redirect command output to logs/teamflow/${runId || "<runId>"}/ (e.g. qa-out.log); no scatter at project root.
 5. Output the test report (body ≤150 lines, verdict first): scope & environment, cases & results (pass/fail/blocked), conclusion (whether acceptance-ready).
@@ -1929,7 +2096,7 @@ ${tech && String(tech).trim() ? clip(tech, 12e3) : ""}
 3. After fixing, run relevant verification to ensure green (regression floor: existing verify suites pass untouched); redirect output to logs/teamflow/${runId || "<runId>"}/.
 4. Output a fix summary (≤40 lines, Chinese): per defect —「truth judgment + fix」or「false-positive evidence」, changed files, how verified, leftovers. No big code pastes.
 5. [State] End with a state block (phase="dev"), touched = changed files array, summary = fix conclusion.${STATE_BLOCK_INSTRUCTION}`;
-const acceptancePrompt = (prd, qa, devSummary, root, runId, state) => `You are the product manager (acceptance lead). Do a final acceptance of this delivery against the PRD acceptance criteria.
+const acceptancePrompt = (prd, qa, devSummary, root, runId, state, vision) => `You are the product manager (acceptance lead). Do a final acceptance of this delivery against the PRD acceptance criteria.
 ${productCtx(root)}${stateSliceFor(state, "acceptance")}${TOKEN_HYGIENE(runId)}
 ${ONCE_DISCIPLINE}[PRD (revision log + this run's new ACs)]
 ${headTailClip(prd, 4e3, 5e3)}
@@ -1937,6 +2104,7 @@ ${headTailClip(prd, 4e3, 5e3)}
 ${clip(qa, 1e4)}
 [DEV RESULT SUMMARY]
 ${clip(devSummary, 8e3)}
+${vision ? "[Visual re-check] If QA saved screenshots under the task folder, spot-check the human-eye items visually (occlusion / layout reasonableness / animation feel) before concluding; otherwise rely on the QA report + 人工补测清单." : ""}
 [REQUIREMENTS]
 0. [Architecture consistency check · mandatory (M3 quality gate)] Beyond functional ACs, check structural quality:
    - If the injected blueprint JSON ("<!-- blueprint -->") is present: does the implementation follow it (module extracted as planned? assembly order correct? abstraction missing where required?).
@@ -2321,6 +2489,29 @@ function deliverCompletion(journal, parent) {
 			interrupted: "⚠ 中断（可用 teamflow_resume 从断点重跑）"
 		}[journal.status] || journal.status;
 		const stagesLine = stages.length === 0 ? "尚未进入任何阶段" : `${stages.length} 个阶段 · ${done} 完成${failed > 0 ? ` · ${failed} 失败` : ""}${cancelledStages > 0 ? ` · ${cancelledStages} 取消` : ""}`;
+		let mergeHint = "";
+		if (journal.status === "completed" && !journal.error && journal.workspacePath) try {
+			const branch = gitCmd(journal.workspacePath, [
+				"rev-parse",
+				"--abbrev-ref",
+				"HEAD"
+			]);
+			if (branch && branch !== "main") {
+				const ahead = gitCmd(journal.workspacePath, [
+					"rev-list",
+					"--count",
+					"main..HEAD"
+				]);
+				if (ahead && Number(ahead) > 0) {
+					journal.mergeStatus = journal.mergeStatus || "pending";
+					mergeHint = `🧩 合回决策：验收已通过，当前在特性分支 ${branch}（领先 main ${ahead} 个提交）。请**询问用户**是否合回，并按用户选择调用 teamflow_merge：\n   ① host 代为合回 → action="merge"\n   ② 给出命令用户自行合回 → action="command"\n   ③ 暂不合回 → action="keep"\n（选项之外用户自定义输入亦可，如实转述）`;
+				}
+			}
+			if ((journal.options || {}).preAction === "stash") {
+				const stashHint = "🧩 启动前 stash 的改动仍在暂存区：流水线完成后请执行 git stash pop 恢复你的改动";
+				mergeHint = mergeHint ? `${mergeHint}\n${stashHint}` : stashHint;
+			}
+		} catch (e) {}
 		const text = [
 			`【团队研发流水线汇报】runId=${journal.id}`,
 			`状态：${statusLine}${journal.error ? `（${clip(journal.error, 300)}）` : ""}`,
@@ -2334,6 +2525,7 @@ function deliverCompletion(journal, parent) {
 				return typeof m === "string" && m !== "full" && m !== "medium" ? `模式：${MODE_REGISTRY[m] ? MODE_REGISTRY[m].label : m}` : "";
 			})(),
 			`backlog：需求 ${journal.reqId || "—"}（$DSH_HOME/teamflow/ 持久化）`,
+			mergeHint,
 			"用户可打开「🏭 团队工作台」tab 查看阶段泳道、拖拽看板与 token 明细。",
 			"如需继续处理：可认领缺陷（teamflow_claim）、人工流转（teamflow_update）、断点重跑（teamflow_resume）。",
 			"若用户在场请简明转述以上要点；若无人值守仅记录即可，不必长篇回复。"
@@ -2357,79 +2549,6 @@ function deliverCompletion(journal, parent) {
 	}
 }
 //#endregion
-//#region host/core/sanity.ts
-/**
-* dsh-plugin-teamflow core — M0 状态核对（sanity check）。
-*
-* 目的（三情况协议）：
-* - 情况一（全新会话）：0 认知 → 核对确认"从零开始"。
-* - 情况二（续会话）：认知大概率过期（多人协作/场外提交/非流水线改动）→ 核对发现预期外变化。
-* - 情况三（新会话处理新需求）：即使共用 state/记忆，仓库也可能被外部改动 → 核对现状。
-*
-* 核心原则：认知资产（索引/记忆/摘要）可复用"减量"，但永不能替代"对代码库当前真实状态的核对"。
-* 本模块在 host 侧直接跑 git（零模型 token、轻量、失败优雅降级为"无法核对"），
-* 产出 externalDiffs 摘要注入到后续所有阶段 prompt。
-*/
-/** 单条 git 检查结果（失败返回 null，调用方降级）。 */
-function gitCmd(cwd, args, timeoutMs = 8e3) {
-	try {
-		return execFileSync("git", args, {
-			cwd,
-			encoding: "utf8",
-			timeout: timeoutMs,
-			windowsHide: true
-		}).trim();
-	} catch (e) {
-		return null;
-	}
-}
-/**
-* 跑一次状态核对。
-* @param path - 工作区绝对路径（workspaceScopeOf(agent).path）。
-*/
-function runSanityCheck(path) {
-	const defaultOut = {
-		ok: false,
-		inRepo: false,
-		branch: null,
-		dirty: "",
-		hasDirty: false,
-		recentCommits: "",
-		summary: ""
-	};
-	if (!path) return {
-		...defaultOut,
-		summary: "⚠ 无法确定工作区路径，未做状态核对。"
-	};
-	const branch = gitCmd(path, ["branch", "--show-current"]);
-	const status = gitCmd(path, ["status", "--short"]);
-	if (branch === null && status === null) return {
-		...defaultOut,
-		summary: "⚠ 状态核对不可用（非 git 仓库或 git 命令被拒），无法确认代码库真实状态。"
-	};
-	const recent = gitCmd(path, [
-		"log",
-		"--oneline",
-		"-5"
-	]);
-	const dirty = status || "";
-	const dirtyLines = dirty.split("\n").filter(Boolean);
-	const summaryParts = [];
-	summaryParts.push(`分支：${branch && branch !== "HEAD" ? branch : "(detached HEAD / 非分支)"}`);
-	if (dirtyLines.length) summaryParts.push(`未提交改动 ${dirtyLines.length} 处：${dirtyLines.slice(0, 8).join("；")}${dirtyLines.length > 8 ? "…" : ""}`);
-	else summaryParts.push("工作区干净（无未提交改动）");
-	if (recent) summaryParts.push(`近期提交（可能含场外改动）：${recent.split("\n").slice(0, 3).join("；")}`);
-	return {
-		ok: true,
-		inRepo: true,
-		branch: branch && branch !== "HEAD" ? branch : null,
-		dirty,
-		hasDirty: dirtyLines.length > 0,
-		recentCommits: recent || "",
-		summary: `【状态核对】${summaryParts.join("。")}`
-	};
-}
-//#endregion
 //#region host/core/pipeline.ts
 /**
 * dsh-plugin-teamflow core — 流水线编排中枢（阶段执行 / 入口 / 取消 / 断点续跑）。
@@ -2454,12 +2573,17 @@ function buildResumeProducts(journal) {
 	return products;
 }
 /**
-* 断点续跑起点：journal 中第一个未完成阶段（磁盘上 interrupted/running 所在阶段）。
+* 断点续跑起点：第一个「没有任意 done 尝试」的阶段。
+* ⚠️ 按阶段而非尝试判断（实锤 tf-mtcomxpq）：PRD 第 1 次尝试 failed（护栏退化）但第 2 次重试 done——
+* 旧实现取第一个非 done stage → 断点错误回到 PRD，PRD/技术方案被无谓重跑。
 * 全部完成仍被中断（理论极端）→ 从产品验收继续。
 */
 function interruptedPhaseOf(journal) {
-	const stage = (journal.stages || []).find((s) => s.status !== "done");
-	if (stage && PHASE_ORDER.indexOf(stage.phase) !== -1) return stage.phase;
+	for (const phase of PHASE_ORDER) {
+		const phaseStages = (journal.stages || []).filter((s) => s.phase === phase);
+		if (phaseStages.length === 0) continue;
+		if (!phaseStages.some((s) => s.status === "done")) return phase;
+	}
 	return "产品验收";
 }
 /**
@@ -2557,6 +2681,48 @@ async function executePipeline(journal, parent, requirement, options, signal, re
 				level: "info",
 				message: `backlog 已建立需求 ${init.reqId}（产品 ${root || "unknown"}，并发 ${maxConcurrency}）`
 			});
+			if (options.branchPolicy !== "keep" && journal.workspacePath) try {
+				const s = runSanityCheck(journal.workspacePath);
+				if (s.ok && s.inRepo && !s.hasDirty) {
+					const branch = `feat/${deriveBranchSlug(requirement, journal.reqId, triageSlug, options.branchName)}`;
+					const exists = gitCmd(journal.workspacePath, [
+						"branch",
+						"--list",
+						branch
+					]);
+					if (exists && exists.trim()) {
+						journal.logs.push({
+							t: Date.now(),
+							level: "warn",
+							message: `分支策略：分支 ${branch} 已存在，沿用现有分支`
+						});
+						gitCmd(journal.workspacePath, ["checkout", branch]);
+						journal.branch = branch;
+					} else {
+						const ok = gitCmd(journal.workspacePath, [
+							"checkout",
+							"-b",
+							branch
+						]);
+						journal.logs.push({
+							t: Date.now(),
+							level: "info",
+							message: ok !== null ? `分支策略：已创建特性分支 ${branch}（从 ${s.branch} 派生）` : `分支策略：自动建分支 ${branch} 失败（git 异常），沿用当前分支`
+						});
+						if (ok !== null) journal.branch = branch;
+					}
+				} else if (s.ok && s.inRepo && s.branch) journal.logs.push({
+					t: Date.now(),
+					level: "warn",
+					message: `分支策略：工作区仍有未提交改动（${s.dirty.split(/\r?\n/).filter((l) => l.trim()).length} 处），跳过建分支，沿用 ${s.branch}——请知悉改动将混入本次开发`
+				});
+			} catch (e) {
+				journal.logs.push({
+					t: Date.now(),
+					level: "warn",
+					message: `分支策略检查失败（降级沿用当前分支）：${String(e && e.message || e)}`
+				});
+			}
 		}
 		persistJournal(journal);
 		if (!journal.runDocs && journal.reqId) {
@@ -2586,6 +2752,49 @@ async function executePipeline(journal, parent, requirement, options, signal, re
 				});
 			}
 		}
+		if (!resume && journal.workspacePath && options.preAction === "stash") try {
+			if (gitCmd(journal.workspacePath, [
+				"stash",
+				"push",
+				"-m",
+				`teamflow:${journal.id} pre-pipeline`
+			]) !== null) journal.logs.push({
+				t: Date.now(),
+				level: "info",
+				message: `分支策略：工作区改动已 stash（teamflow:${journal.id}），流水线完成后 git stash pop 恢复你的改动`
+			});
+			else journal.logs.push({
+				t: Date.now(),
+				level: "warn",
+				message: "分支策略：stash 执行失败（可能无改动），继续"
+			});
+		} catch (e) {
+			journal.logs.push({
+				t: Date.now(),
+				level: "warn",
+				message: `分支策略：stash 异常：${String(e && e.message || e)}`
+			});
+		}
+		else if (!resume && journal.workspacePath && options.preAction === "commit") try {
+			const msg = typeof options.commitMessage === "string" && options.commitMessage.trim() ? options.commitMessage.trim() : `chore(teamflow): 流水线启动前提交现有改动（${journal.id}）`;
+			const add = gitCmd(journal.workspacePath, ["add", "-A"]);
+			const cm = gitCmd(journal.workspacePath, [
+				"commit",
+				"-m",
+				msg
+			]);
+			journal.logs.push({
+				t: Date.now(),
+				level: "info",
+				message: add !== null && cm !== null ? `分支策略：已提交现有改动（preAction=commit：${msg.slice(0, 60)}）` : "分支策略：commit 执行失败（可能无改动），继续"
+			});
+		} catch (e) {
+			journal.logs.push({
+				t: Date.now(),
+				level: "warn",
+				message: `分支策略：commit 异常：${String(e && e.message || e)}`
+			});
+		}
 		const state = loadState(journal.workspace || "default");
 		state.__runCtx = { ...state.__runCtx || {} };
 		if (journal.runDocs) state.__runCtx.runDocs = journal.runDocs;
@@ -2828,6 +3037,14 @@ async function executePipeline(journal, parent, requirement, options, signal, re
 					level: "warn",
 					message: `开发完成，失败任务数：${failedCount}（需人工介入）`
 				});
+				if (failedCount >= devResults.length) {
+					journal.logs.push({
+						t: Date.now(),
+						level: "error",
+						message: `开发任务全部失败（${failedCount}/${devResults.length}）：停止流水线，需人工介入——可用 teamflow_resume 从开发阶段重跑`
+					});
+					throw new Error(`开发任务全部失败（${failedCount}/${devResults.length}）：无产物可测，停止流水线`);
+				}
 			} else {
 				advanceTask(journal, "testable", null, "开发完成待测试（开发中 → 待测试）", { by: "dev" });
 				journal.logs.push({
@@ -2872,7 +3089,7 @@ async function executePipeline(journal, parent, requirement, options, signal, re
 			do {
 				round += 1;
 				const isReverify = round > 1;
-				const qaR = await withRetry(journal, parent, isReverify ? `QA 复验 · 第${round - 1}轮修复后` : "QA 测试工程师 · 功能测试", "QA 测试", qaPrompt(prd, qaDevSummary(), root, journal.id, state), signal);
+				const qaR = await withRetry(journal, parent, isReverify ? `QA 复验 · 第${round - 1}轮修复后` : "QA 测试工程师 · 功能测试", "QA 测试", qaPrompt(prd, qaDevSummary(), root, journal.id, state, await currentModelSupportsVision(resolveChildRoute(parent).provider, resolveChildRoute(parent).model)), signal);
 				if (!qaR.text) {
 					advanceTask(journal, "needs-human", null, isReverify ? `QA 复验失败（第 ${round - 1} 轮修复后）` : "QA 失败", { by: "qa" });
 					throw stageFailError(isReverify ? "QA 测试（复验）" : "QA 测试", qaR);
@@ -2952,7 +3169,7 @@ async function executePipeline(journal, parent, requirement, options, signal, re
 				const curTask = storeFor(scopeKey).find("task", journal.taskId);
 				if (curTask && curTask.status !== "pending-acceptance" && curTask.status !== "needs-human" && curTask.status !== "rework") advanceTask(journal, "pending-acceptance", null, "进入验收（待验收）", { by: "pm" });
 			}
-			const accR = await withRetry(journal, parent, "产品经理 · 最终验收", "产品验收", acceptancePrompt(prd, qa, JSON.stringify(timeline.dev), root, journal.id, state), signal);
+			const accR = await withRetry(journal, parent, "产品经理 · 最终验收", "产品验收", acceptancePrompt(prd, qa, JSON.stringify(timeline.dev), root, journal.id, state, await currentModelSupportsVision(resolveChildRoute(parent).provider, resolveChildRoute(parent).model)), signal);
 			if (!accR.text) {
 				advanceTask(journal, "needs-human", null, "验收失败", { by: "pm" });
 				throw stageFailError("产品验收", accR);
@@ -3021,6 +3238,35 @@ async function executePipeline(journal, parent, requirement, options, signal, re
 		journal.endedAt = Date.now();
 		inFlight.delete(journal.id);
 		activeProducts.delete(scopeKey);
+		if (journal.workspacePath && journal.status === "completed" && !journal.humanIntervention) try {
+			const reqHead = String(journal.requirement || "").replace(/\s+/g, " ").trim().slice(0, 80);
+			const add = gitCmd(journal.workspacePath, ["add", "-A"]);
+			if ((add === null ? null : gitCmd(journal.workspacePath, [
+				"commit",
+				"-m",
+				`feat: ${reqHead}（runId=${journal.id}${journal.runDocs ? `，任务夹 ${journal.runDocs}` : ""}）`
+			])) !== null) journal.logs.push({
+				t: Date.now(),
+				level: "info",
+				message: "统一收口提交完成（代码 + 任务夹产物，验收通过后一个 commit）"
+			});
+			else if (add !== null) journal.logs.push({
+				t: Date.now(),
+				level: "info",
+				message: "统一收口提交：无待提交改动（跳过）"
+			});
+		} catch (e) {
+			journal.logs.push({
+				t: Date.now(),
+				level: "warn",
+				message: `统一收口提交失败（忽略）：${String(e && e.message || e)}`
+			});
+		}
+		else if (journal.workspacePath && journal.runDocs && (journal.status === "failed" || journal.status === "cancelled" || journal.status === "interrupted")) journal.logs.push({
+			t: Date.now(),
+			level: "warn",
+			message: `终态非验收通过：工作区改动与任务夹产物 ${journal.runDocs}/ 保留未提交，供人工处理（resume 修复通过后自动收口提交）`
+		});
 		journal.result = {
 			requirement,
 			options: sanitizeSnapOptions(options),
@@ -3098,7 +3344,11 @@ function startPipeline(agent, requirement, options, signal) {
 			teamId: options.teamId || void 0,
 			tasks: normalizeTasks(options.tasks),
 			productRoot: normalizeRoot(options.productRoot),
-			maxConcurrency: Number.isFinite(options.maxConcurrency) && options.maxConcurrency > 0 ? Math.min(options.maxConcurrency, 8) : null
+			maxConcurrency: Number.isFinite(options.maxConcurrency) && options.maxConcurrency > 0 ? Math.min(options.maxConcurrency, 8) : null,
+			branchPolicy: options.branchPolicy || void 0,
+			branchName: options.branchName || void 0,
+			preAction: options.preAction || void 0,
+			commitMessage: options.commitMessage || void 0
 		},
 		startedAt: null,
 		endedAt: null,
@@ -3303,7 +3553,7 @@ function registerTools(ctx) {
 	};
 	T({
 		name: "teamflow_start",
-		description: "Start the team R&D pipeline (background async): runs the stages per team config (PRD→design→tech→dev→QA→acceptance). Specify teamId (matches teams.json) or pick a team via the UI \"+\" button first so messages auto-match. Stage failures auto-retry; beyond threshold → rework/human intervention; per-stage token usage recorded. NOTE: after calling, the implementation work is done by pipeline subagents — the main thread MUST NOT write code or run verifications for it. requirement must be a faithful transcription of the user's words; do not invent file paths / tech claims without code verification (downstream stages build the PRD from it).",
+		description: "Start the team R&D pipeline (background async): runs the stages per team config (PRD→design→tech→dev→QA→acceptance). Specify teamId (matches teams.json) or pick a team via the UI \"+\" button first so messages auto-match. Stage failures auto-retry; beyond threshold → rework/human intervention; per-stage token usage recorded. NOTE: after calling, the implementation work is done by pipeline subagents — the main thread MUST NOT write code or run verifications for it. requirement must be a faithful transcription of the user's words; do not invent file paths / tech claims without code verification (downstream stages build the PRD from it). Branch decision: when the return status is \"needs-decision\", ASK THE USER to pick one of the options (or take their custom input, e.g. a branch name), then RE-CALL this tool with the chosen branchPolicy / branchName / preAction / commitMessage parameters. Pass branchPolicy=\"keep\" when the user chooses to stay on the current branch.",
 		parameters: {
 			requirement: {
 				type: "string",
@@ -3338,6 +3588,22 @@ function registerTools(ctx) {
 				type: "integer",
 				description: "Dev task concurrency (default 3, max 8)"
 			},
+			branchPolicy: {
+				type: "string",
+				description: "Branch policy: \"auto\" (default) — create a feature branch feat/<branchName|slug> from the current HEAD; \"keep\" — stay on current branch. When auto and a decision is needed (dirty workspace / on main etc.), the tool returns needs-decision for you to ask the user first."
+			},
+			branchName: {
+				type: "string",
+				description: "Custom branch name (used when branchPolicy=auto; defaults to the triage slug; [a-z0-9-_])"
+			},
+			preAction: {
+				type: "string",
+				description: "Pre-start handling of dirty workspace: \"stash\" (stash changes, restore later via git stash pop), \"commit\" (commit existing changes, custom commitMessage), omit = leave as-is (changes mix into this run)"
+			},
+			commitMessage: {
+				type: "string",
+				description: "Custom commit message when preAction=commit"
+			},
 			tasks: {
 				type: "array",
 				description: "Optional splittable dev task list",
@@ -3362,16 +3628,32 @@ function registerTools(ctx) {
 			schema: {
 				type: "object",
 				additionalProperties: false,
-				required: ["runId", "status"],
+				required: ["status"],
 				properties: {
 					runId: { type: "string" },
-					status: { type: "string" }
+					status: { type: "string" },
+					question: { type: "string" },
+					options: { type: "array" },
+					note: { type: "string" }
 				}
 			},
-			render: (args, value) => [{
-				type: "text",
-				text: `团队研发流水线已启动（runId=${value.runId}，${value.status}），正在后台执行。【重要】你现在停手：不要自行读取/修改代码实现该需求，不要重复跑测试验证——实现、QA、汇报由流水线各阶段完成。你只需告知用户流水线已启动，等待流水线完成后的官方完成汇报，再向用户转述结果。可用 teamflow_status 查询进度/阶段 token；backlog 已持久化到 $DSH_HOME/teamflow。`
-			}]
+			render: (args, value) => {
+				if (value && value.status === "needs-decision") {
+					const opts = Array.isArray(value.options) ? value.options.map((o, i) => `${i + 1}. ${o.label}`).join("\n") : "";
+					return [{
+						type: "text",
+						text: `【分支决策】${value.question}\n${opts}\n（也可自定义输入）——请询问用户选择，确认后以 teamflow_start 的 branchPolicy/branchName/preAction/commitMessage 参数重新调用。`
+					}];
+				}
+				if (value && value.status === "needs-confirmation") return [{
+					type: "text",
+					text: `【需求确认】${value.question}\n${value.note || ""}——请按此询问用户后再决定。`
+				}];
+				return [{
+					type: "text",
+					text: `团队研发流水线已启动（runId=${value.runId}，${value.status}），正在后台执行。【重要】你现在停手：不要自行读取/修改代码实现该需求，不要重复跑测试验证——实现、QA、汇报由流水线各阶段完成。你只需告知用户流水线已启动，等待流水线完成后的官方完成汇报，再向用户转述结果。可用 teamflow_status 查询进度/阶段 token；backlog 已持久化到 $DSH_HOME/teamflow。`
+				}];
+			}
 		},
 		async execute(args, exec) {
 			const parent = exec && exec.agent;
@@ -3388,18 +3670,104 @@ function registerTools(ctx) {
 				status: "no-team",
 				message: "请先通过输入框旁的 🏭 按钮选择团队，再发送需求消息。未选团队时不走 teamflow。"
 			};
+			const rawReq = typeof args.requirement === "string" ? args.requirement : "";
+			if (/是不是|要不要|需不需要|是否应该|要不要考虑|建议|我感觉|感觉不出|我们是不是|咱是不是/.test(rawReq)) return {
+				status: "needs-confirmation",
+				question: `这条消息（「${rawReq.slice(0, 60)}」）更像反馈/建议（含疑问句式）而非明确开发需求。请先向用户确认：是否要实现？`,
+				note: "用户确认要实现后，请把明确需求（如「实现 combo/t-spin 触发 Toast 提示」）作为 requirement 重新调用 teamflow_start；若用户只是表达感受/讨论，直接正常回复即可。"
+			};
 			try {
+				const requirement = typeof args.requirement === "string" && args.requirement.trim() ? args.requirement.trim() : "(未提供需求)";
+				const options = {
+					needDesign: !!args.needDesign,
+					needScaffold: !!args.needScaffold,
+					lite: !!args.lite,
+					mode: normalizeMode(args.mode) || void 0,
+					teamId,
+					tasks: normalizeTasks(args.tasks),
+					productRoot: normalizeRoot(args.productRoot),
+					maxConcurrency: args.maxConcurrency,
+					branchPolicy: args.branchPolicy === "keep" ? "keep" : "auto",
+					branchName: typeof args.branchName === "string" && args.branchName.trim() ? args.branchName.trim() : null,
+					preAction: args.preAction === "stash" || args.preAction === "commit" ? args.preAction : null,
+					commitMessage: typeof args.commitMessage === "string" && args.commitMessage.trim() ? args.commitMessage.trim() : null
+				};
+				if (options.branchPolicy === "auto" && !options.preAction && exec && exec.agent) {
+					const sc = workspaceScopeOf(exec.agent);
+					if (sc.path) try {
+						const s = runSanityCheck(sc.path);
+						if (s.ok && s.inRepo) {
+							const onMain = !!s.branch && s.branch.trim().toLowerCase() === "main";
+							const dirty = s.hasDirty;
+							const dirtyN = s.dirty.split(/\r?\n/).filter((l) => l.trim()).length;
+							let question = "";
+							let optionsList = [];
+							if (onMain && !dirty) {
+								question = `工作区 ${sc.path} 当前在 main 分支（工作区干净）。流水线默认在特性分支上开发，请选择：`;
+								optionsList = [{
+									label: "基于 main 新建分支开发（推荐，分支名取需求 slug，可自定义）",
+									value: "auto"
+								}, {
+									label: "直接在 main 上开发",
+									value: "keep"
+								}];
+							} else if (onMain && dirty) {
+								question = `工作区 ${sc.path} 当前在 main 分支，且有 ${dirtyN} 处未提交改动。请选择启动方式：`;
+								optionsList = [
+									{
+										label: `stash 现有改动后新建分支开发（推荐，改动暂存，流水线完成后 git stash pop 恢复）`,
+										value: "stash+auto"
+									},
+									{
+										label: "提交现有改动后新建分支开发（提交信息可自定义）",
+										value: "commit+auto"
+									},
+									{
+										label: "直接在 main 上继续（未提交改动将混入本次开发）",
+										value: "keep"
+									}
+								];
+							} else if (!onMain && !dirty) {
+								question = `工作区 ${sc.path} 当前在特性分支 ${s.branch}（工作区干净）。请选择启动方式：`;
+								optionsList = [{
+									label: "沿用当前分支开发（推荐）",
+									value: "keep"
+								}, {
+									label: "基于当前分支再新建子分支开发",
+									value: "auto"
+								}];
+							} else {
+								question = `工作区 ${sc.path} 当前在特性分支 ${s.branch}，且有 ${dirtyN} 处未提交改动。请选择启动方式：`;
+								optionsList = [
+									{
+										label: "stash 现有改动后沿用当前分支开发（推荐，完成后 git stash pop 恢复）",
+										value: "stash+keep"
+									},
+									{
+										label: "直接沿用当前分支（未提交改动混入本次开发）",
+										value: "keep"
+									},
+									{
+										label: "stash 现有改动后新建子分支开发",
+										value: "stash+auto"
+									},
+									{
+										label: "提交现有改动后新建子分支开发",
+										value: "commit+auto"
+									}
+								];
+							}
+							return {
+								status: "needs-decision",
+								question,
+								options: optionsList,
+								note: "选项之外可自定义输入（如指定分支名）。确认选择后，请以 teamflow_start 的 branchPolicy / branchName / preAction / commitMessage 参数重新调用本工具。"
+							};
+						}
+					} catch (e) {}
+				}
 				return {
-					runId: startPipeline(parent, typeof args.requirement === "string" && args.requirement.trim() ? args.requirement.trim() : "(未提供需求)", {
-						needDesign: !!args.needDesign,
-						needScaffold: !!args.needScaffold,
-						lite: !!args.lite,
-						mode: normalizeMode(args.mode) || void 0,
-						teamId,
-						tasks: normalizeTasks(args.tasks),
-						productRoot: normalizeRoot(args.productRoot),
-						maxConcurrency: args.maxConcurrency
-					}, exec && exec.signal),
+					runId: startPipeline(parent, requirement, options, exec && exec.signal),
 					status: "running"
 				};
 			} catch (e) {
@@ -3407,6 +3775,88 @@ function registerTools(ctx) {
 			}
 		}
 	});
+	T({
+		name: "teamflow_merge",
+		description: "Merge the completed run's feature branch back to main — the user-confirmed closing step (ADR-2026-08-27). Valid only after acceptance passed (run status=completed) while on a feature branch ahead of main. **Ask the user first** — the completion report carries the decision invitation (① host merge ② manual command ③ keep). Actions: \"merge\" — host performs git checkout main && git merge --no-ff <branch>; \"command\" — print the manual command for the user to run themselves; \"keep\" — defer, mark run as kept (branch stays).",
+		parameters: {
+			action: {
+				type: "string",
+				required: true,
+				description: "\"merge\" (host performs the merge) / \"command\" (print the manual merge command) / \"keep\" (defer, mark kept)"
+			},
+			runId: {
+				type: "string",
+				description: "Run id (defaults to the latest completed run of this workspace)"
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				required: ["status"],
+				properties: {
+					status: { type: "string" },
+					message: { type: "string" },
+					command: { type: "string" }
+				}
+			},
+			render: (args, value) => [{
+				type: "text",
+				text: value.message
+			}]
+		},
+		async execute(args, exec) {
+			const action = args && args.action;
+			if (action !== "merge" && action !== "command" && action !== "keep") throw new Error("action 必须是 merge / command / keep");
+			const sc = workspaceScopeOf(exec && exec.agent);
+			if (!sc.path) throw new Error("当前会话无项目工作区");
+			const key = sc.projectKey;
+			const target = typeof args.runId === "string" && args.runId ? runs.get(args.runId) : [...runs.values()].filter((j) => j.workspace === key && j.status === "completed").sort((a, b) => (b.endedAt || 0) - (a.endedAt || 0))[0];
+			if (!target) throw new Error("未找到已完成流水线（可传 runId 指定）");
+			const branch = gitCmd(sc.path, [
+				"rev-parse",
+				"--abbrev-ref",
+				"HEAD"
+			]);
+			if (!branch || branch === "main") return {
+				status: "noop",
+				message: "当前已在 main 分支，无需合回"
+			};
+			if (action === "command") return {
+				status: "command",
+				command: `git checkout main && git merge --no-ff ${branch}`,
+				message: `请用户在项目目录执行以下命令完成合回（合回后可 git branch -d ${branch} 清理特性分支）：\ngit checkout main && git merge --no-ff ${branch}`
+			};
+			if (action === "keep") {
+				target.mergeStatus = "kept";
+				persistJournal(target);
+				return {
+					status: "kept",
+					message: `已标记暂不合回：特性分支 ${branch} 保留，后续可随时调用 teamflow_merge 合回`
+				};
+			}
+			const co = gitCmd(sc.path, ["checkout", "main"]);
+			const mg = co === null ? null : gitCmd(sc.path, [
+				"merge",
+				"--no-ff",
+				branch
+			]);
+			if (co === null || mg === null) {
+				target.mergeStatus = "failed";
+				persistJournal(target);
+				return {
+					status: "failed",
+					message: `合并失败（工作区可能不干净或有冲突）。请人工处理：先提交/处理当前工作区改动，再执行 git merge --no-ff ${branch}（冲突文件需手动解决）`
+				};
+			}
+			target.mergeStatus = "merged";
+			persistJournal(target);
+			return {
+				status: "merged",
+				message: `✅ 已合回 main（git merge --no-ff ${branch}）。如需清理特性分支：git branch -d ${branch}`
+			};
+		}
+	});
 	T({
 		name: "teamflow_triage",
 		description: "Requirement triage (optional helper): teamflow_start already auto-triages by default — no need to call this manually. Use it only when you want to **pre-evaluate** which pipeline mode a requirement fits, or **force** a mode: a triage analyst Agent thinks one round and returns a suggested mode, nature, UI-need, complexity and rationale.",
@@ -3742,8 +4192,25 @@ function registerTools(ctx) {
 }
 /** 会话级暂停标记：pausedSessions.has(sessionId) → 该会话的 teamflow_start 被拦截。 */
 const pausedSessions = /* @__PURE__ */ new Set();
-/** 会话级当前团队：activeTeams.get(sessionId) → 当前选中的团队 id。 */
+/** 会话级当前团队：activeTeams.get(sessionId) → 当前选中的团队 id。
+* 持久化到 $DSH_HOME/teamflow/active-teams.json——重启后恢复（实锤：重启/刷新后内存清空，
+* UI 显示无团队，但 agent 上下文记忆 teamId 显式传入仍启动流水线，UI 状态与启动通道不一致）。 */
 const activeTeams = /* @__PURE__ */ new Map();
+const ACTIVE_TEAMS_FILE = () => join(teamflowRoot(), "active-teams.json");
+function loadActiveTeams() {
+	try {
+		const raw = readJsonAny(ACTIVE_TEAMS_FILE(), null);
+		if (raw && typeof raw === "object") {
+			for (const [k, v] of Object.entries(raw)) if (typeof k === "string" && typeof v === "string") activeTeams.set(k, v);
+		}
+	} catch (e) {}
+}
+function saveActiveTeams() {
+	try {
+		mkdirSync(teamflowRoot(), { recursive: true });
+		writeJson(ACTIVE_TEAMS_FILE(), Object.fromEntries(activeTeams));
+	} catch (e) {}
+}
 /** 延迟注入队列：选团队时 agent 可能尚未加载，存入 pending，后续时机补发。 */
 const pendingInjections = /* @__PURE__ */ new Map();
 /** 尝试补发延迟注入：agent 可用时注入上下文并清除 pending。 */
@@ -3778,11 +4245,13 @@ var TeamflowService = class extends TypertRemoteService {
 		"subagents",
 		"tokenMeter",
 		"typert",
-		"tools"
+		"tools",
+		"llm"
 	];
 	constructor(ctx) {
 		super(ctx, "teamflow");
-		setRuntime(ctx.get("agents"), ctx.get("subagents"), ctx.get("tokenMeter"), ctx.get("workspaceRegistry"), ctx.get("agentDefaultModel"));
+		setRuntime(ctx.get("agents"), ctx.get("subagents"), ctx.get("tokenMeter"), ctx.get("workspaceRegistry"), ctx.get("agentDefaultModel"), ctx.get("llm"));
+		loadActiveTeams();
 		let interruptedCount = 0;
 		try {
 			for (const { journal, wasInterrupted } of loadJournals()) {
@@ -4083,6 +4552,7 @@ var TeamflowService = class extends TypertRemoteService {
 			error: `团队 ${tid} 不存在`
 		};
 		activeTeams.set(sid, tid);
+		saveActiveTeams();
 		const agent = runtime.agents && runtime.agents.get(sid);
 		const injectPayload = {
 			type: "user",
@@ -4139,6 +4609,7 @@ var TeamflowService = class extends TypertRemoteService {
 			error: "缺少 sessionId"
 		};
 		activeTeams.delete(sid);
+		saveActiveTeams();
 		return { ok: true };
 	}
 	/** 从断点续跑：跳过已完成阶段，从第一个未完成阶段重跑。 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-teamflow",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "TeamFlow 团队研发流水线（TypeScript）：需求→PRD→设计→架构→技术方案→并行开发→QA→验收；backlog 持久化 + 断点续跑 + 完成汇报 + 防假交付；Web 团队工作台（conversation.view tab + 拖拽看板）",
   "type": "module",
   "main": "./lib/host.mjs",
@@ -76,14 +76,30 @@
     "@deepseek-ai/dsh-typert-protocol": "*"
   },
   "peerDependenciesMeta": {
-    "@deepseek-ai/dsh-base": { "optional": true },
-    "@deepseek-ai/dsh-client-locale": { "optional": true },
-    "@deepseek-ai/dsh-client-runtime": { "optional": true },
-    "@deepseek-ai/dsh-client-ui-conversation": { "optional": true },
-    "@deepseek-ai/dsh-llm": { "optional": true },
-    "@deepseek-ai/dsh-tools": { "optional": true },
-    "@deepseek-ai/dsh-typert-protocol": { "optional": true },
-    "react": { "optional": true }
+    "@deepseek-ai/dsh-base": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-locale": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-runtime": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-conversation": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-llm": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-typert-protocol": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
   },
   "license": "MIT",
   "repository": {