v0.3.2

TeamFlow v0.3.2

发布日期：2026-10-26。变更清单按 release-npm-package 铁律 1 由 git log v0.3.1..HEAD 生成
（16 笔开发提交 / 26 个文件 / +1253 −116；该区间另含 1 笔 v0.3.1 合并与本次发版提交），不凭会话记忆。
⚠️ 本版含一处行为变更（PRD 改写的等待判据）。逐笔归属与真机取证见 docs/devlog.md 的 v0.3.2 批次。
本文件面向使用者；内部流水不在正文里。

中文

⬆️ 升级要点

• engines 未变（宿主仍须 ≥ 0.2.1-alpha.2，Node ≥ 22.18）。升完重启 dsh --profile web
  （桌面版重启应用）—— 四条修复都在宿主侧，不重启不生效。
• 一处行为变更：PRD 改写的等待判据由「固定 300s 墙钟」改为「无进展即放手」（idle 240s / 天花板 600s）。
  用户可见差异：带较大改动的 PRD 改写不再莫名回落成「重跑 PRD」。
• 无 teamflow_* 工具 schema / journal / 任务夹契约改动，不需要迁移。

① 界面语言不再漂移成英文（修复）

现象：新开一个工作区后，整轮产物被生成成英文（团队名、子代理 label、PRD 正文），而界面是中文 ⇒ 中英混排。

根因：宿主侧拿语言的唯一通道是客户端上报。上报器把「值还没就绪」当成「无事可做」——既不推送、也不重试；
而语言服务只在语言变化时回调、不含初始值 ⇒ 挂载那一刻取到空值，之后永远没人再推，宿主停在 en 兜底。

修复：把「值没就绪」算作待重试，且重试时重新取值（不是重发旧值）；宿主侧同时修掉「空值把已有好值抹掉」。
真机验证：locale 为 zh、无兜底告警、团队名/阶段名/PRD 正文均为中文。

② 分诊不再白跑一次（修复）

现象：用户在确认单上点选后重新开工，却看到一个全新的分诊子代理又跑了一遍。

根因：分诊缓存键含「需求 + 补充说明」；点选那一步模型会重写补充说明（即使语义没变）⇒ 键变 ⇒ 缓存未命中。

修复：「待决策」期间按需求原文放宽命中并迁移待决策状态。真改了需求仍会重跑。
真机验证：四次 resume、每次补充说明都不同，分诊仍只跑一次。

③ PRD 改写不再「完工前放弃」（行为变更 + 修复）

现象：在确认单上改了 PRD，日志写「第二轮跑了但没拿到可用文本」然后重跑整份 PRD——白等约 5 分钟，
而且两份 PRD 并行跑了一段。

根因：等待用的是固定 300s 墙钟。一次真实改写跑了 377s（含多次编辑 + 全文重写 + 状态文件更新），
插件在它完工前 77 秒放弃；子代理会话证据显示那一轮其实完整跑完了。

修复：放弃判据改为「无进展」——既没有新事件、也没有产物变更，持续一段时间才放手；天花板抬到 600s。
同时支持「回合结束但回复没有正文」时按文件即产物判完成（真实改写常常只写文件、回复只给一段小结）。

④ 蓝图不再整份丢弃（修复）

现象：开发阶段退化成「整体开发」一张卡，并行度消失、调用数暴涨。

根因：技术阶段写的架构蓝图是 JSON，而模型把正则原样写进其中（如 /\.md$/i）。JSON 不允许 \. 这类转义
⇒ 整份蓝图被拒绝 ⇒ 拆卡信息全部丢失。

修复：对字符串内的非法 JSON 转义做确定性修复（加倍成字面反斜杠——JSON 里它没有第二种解释），
并覆盖「末尾截断 + 非法转义」并发的形态；修复过会打一条告警留痕，不静默。
真机验证：同一份失败蓝图恢复出 8 个任务 / 16 个模块；后续 run 正常拆成 5 波、3 路并发。

⑤ 需求澄清与确认单（体验）

• 确认单清单化：最多一张汇总卡，不再逐题弹卡片；事实项与口味项分开标注。
• PRD 增加 anti-goals 段：显式回答「技术可行但产品失败」的形态（可观察、具体）。
• /teamflow-brainstorm：需求头脑风暴入口，只允许用户调用，模型不能自己触发。
• 缺陷修复先看「最近改了什么」：先看提交与对基线的 diff，再决定读哪个模块。

⑥ 稳健性（修复）

• 参数类失败判据补第三族：曾把「参数写错」误判成「环境不可用」⇒ 直接停掉自动重试。
• 批准后的续跑不重复计数：复用已完成的 PRD 时，用量不再叠加。
• 部署自检：核对 profile 的版本号与产物指纹；依赖声明用 file:，防 npm install 打回旧版。

验证

• 全量测试与静态检查全绿；每条修复都配了单维度变异（改坏一处只让对应断言变红），共 14 轮。
• 逐条真机取证（含未压实的三条）记录在 docs/devlog.md 的 v0.3.2 批次。

English

Upgrade notes

• engines unchanged (host ≥ 0.2.1-alpha.2, Node ≥ 22.18). Restart dsh --profile web afterwards
  (restart the desktop app) — all four fixes live in the host process.
• One behaviour change: the PRD-revision wait criterion moved from a fixed 300s wall clock to
  "no progress" (idle 240s / ceiling 600s). Visible difference: a large revision no longer falls back
  to a full PRD re-run for no reason.
• No teamflow_* tool-schema / journal / task-folder contract changes — no migration needed.

① The UI language no longer drifts to English (fix)

Symptom: after opening a new workspace, a whole run was produced in English (team name, subagent label,
PRD body) while the UI stayed Chinese — a mixed-language screen.

Root cause: the host learns the language only from the client's report. The reporter treated "the value is
not ready yet" as "nothing to do" — it neither pushed nor retried, and the locale service only notifies on
change (no initial value) ⇒ one empty read at mount means nobody ever pushes again, and the host stays on
the en fallback.

Fix: "not ready" now counts as retry-worthy, and every retry re-reads the value (instead of
re-sending a stale one); the host side no longer lets an empty value wipe a good one.
Verified on a real run: locale is zh, no fallback warning, team/stage names and PRD body are Chinese.

② Triage no longer runs twice (fix)

Symptom: after picking an option on the confirm sheet, a brand-new triage subagent ran again.

Root cause: the triage cache key includes "requirement + supplement", and the model rewrites the
supplement during that round (even when the meaning is unchanged) ⇒ the key changes ⇒ cache miss.

Fix: while a decision is pending, match on the requirement text alone and carry the pending state over.
A genuinely changed requirement still re-runs triage. Verified: four resumes with different supplements, triage
ran once.

③ PRD revisions no longer give up before finishing (behaviour change + fix)

Symptom: after a revision, the log said "the second turn ran but produced no usable text" and the whole PRD
was re-generated — about five minutes wasted, with two PRDs running in parallel for a while.

Root cause: the wait used a fixed 300s wall clock. One real revision took 377s (several edits + a full
rewrite + a state-file update); the plugin gave up 77 seconds before it finished — while the session evidence
shows that turn did complete.

Fix: the give-up criterion is now "no progress" — no new events and no artifact change for a while;
the ceiling is 600s. Also, when a turn ends without reply text, the artifact file counts as the deliverable
(real revisions often write the file and reply with only a short summary).

④ Blueprints are no longer discarded wholesale (fix)

Symptom: the dev stage collapsed into a single "whole-requirement" card — parallelism gone, call count up.

Root cause: the architecture blueprint is JSON, and the model pasted regexes into it verbatim (e.g.
/\.md$/i). JSON does not allow escapes like \. ⇒ the entire blueprint is rejected ⇒ all task-split
information is lost.

Fix: deterministic repair of invalid JSON escapes inside strings (doubling them into literal
backslashes — nothing else they could mean), covering the combined "truncated + invalid escape" shape too.
A repair emits a warning so it is never silent.
Verified: the same failing blueprint now yields 8 tasks / 16 modules; later runs split into 5 waves, 3-wide.

⑤ Clarification and confirm sheet (UX)

• Confirm sheet as a list: at most one summary card instead of one card per question; fact items and taste
  items are labelled separately.
• Anti-goals in the PRD: the PRD now explicitly answers "technically fine but product-wise a failure".
• /teamflow-brainstorm: a brainstorm entry for requirements, user-invocable only — the model cannot
  trigger it on its own.
• Look at "what changed recently" first when fixing a defect: check commits and the diff against the
  baseline before deciding which module to read.

⑥ Robustness (fix)

• Argument-failure family #3: a malformed argument used to be misclassified as "environment unavailable"
  ⇒ automatic retries stopped.
• No double counting after approval: reusing an already-finished PRD no longer adds its usage again.
• Deploy self-check: verifies the profile's version and artifact fingerprint; the dependency uses file:
  so an npm install cannot silently pull an old version.

Verification

• Full test suite and static checks are green; each fix ships with a single-dimension mutation check
  (break one thing, only the matching assertion goes red) — 14 rounds in total.
• Per-fix real-machine evidence (including the three items that remain only partially verified) is recorded in
  the v0.3.2 batch of docs/devlog.md.