v2026.07.17 — 外部对标审查与两轮体系瘦身（SKILL.md -22%）

v2026.07.17 — 外部对标审查与两轮体系瘦身

本次发布是 forge 体系的一次质量迭代：用 Anthropic 官方 skill-creator 标准和 yao-meta-skill 方法论做三路外部对标审查，随后两轮整改把审查发现全部清零。对应 CHANGELOG 的 v2026.07.17 / .1 / .2 三个条目，三个 tag 分别指向当日三个提交。

核心数字

指标	迭代前	迭代后
15 个 SKILL.md 总行数	4429	3449（-22.1%）
最大单文件	forge-eng 492 行	forge-prd 332 行
贴 500 行红线的 skill	3 个（eng/ship/dev）	0 个
AskUserQuestion 规范副本	8 份（已漂移）	1 份单源
状态标记协议副本	5 份	1 份单源
零 references 的中型 skill	2 个（ship/doc-release）	0 个
skill-creator 标准复测	基线约 B+	A-

v2026.07.17 — 审查与一致性修复

• 三路并行审查：skill-creator 官方合规、yao-meta-skill token 效率、内部一致性审计，报告归档 docs/archive/skill-review-2026-07-17.md
• deliver 退役残留清零（user-guide / workflow-guide / architecture 全部对齐 /forge-dev --full 与 .forge/）
• 会误导执行的旧路径修复：prd 项目模板 .deliver/state.json → .forge/dev-state.json，qa 视觉参考补 .forge/
• fupan v2 口径全量同步；README 重写（断链、数量口径、结构图）
• CHANGELOG 补记 2026-07-04 大重构

v2026.07.17.1 — 整改 F1-F12 全量落地

• 共享层单源化：新增 _shared/interaction-protocol.md（提问格式 + 统一批量策略：≤3 单独问、>3 同类批量，消除 eng/review 矛盾）与 _shared/feature-status-protocol.md
• 三大瘦身：ship 488→286（新建 references/merge-and-sync.md、项目特异命令去除）、eng 492→399、dev 458→326
• forge-qa 去伪：删不可运行的伪 bash 模式判断块（313→244）
• workbench 迁出 skill 包：skills/forge-fupan/workbench/ → tools/fupan-workbench/
• 新增 evals/trigger-cases.md：33 条触发/不触发/易混淆路由用例，含与内置 code-review/verify 消歧
• 四份大 reference 补按需跳读导航；doc-policy 未实现项移入 CHANGELOG Roadmap
• 复测揪出的 4 个尾巴（断链、reference 层状态表残留、路径风格）当日修复

v2026.07.17.2 — 第二轮瘦身（复测遗留清零）

• eng 399→275：四章审查细则/从零创建/交付模板下沉现有手册
• doc-release 347→156：新建 references/release-details.md（275 行含导航）
• brainstorm 382→315：提问集下沉 references/question-banks.md
• design 337→312：认知模式 12 条压缩为 4 条可检查自检项；design-impl 210→201
• prd 343→332：双流程图二选一

验证

• 全库 SKILL.md → references 指针逐一核验，零断链、零孤儿文件
• 32 个 symlink（~/.claude/skills + ~/.agents/skills 双目标）完好，install.sh --status 通过
• 15/15 frontmatter 合法，description 全部含"做什么 + 何时触发"

明确不做

• test-dimensions.md 不物理拆分（2026-07-04 已定档，导航表已解决按需跳读）
• audit-project.sh 维持"未来能力"（减法原则）

v2026.04.27 — Fupan 复盘报告结构优化

v2026.04.27 — Fupan 复盘报告结构优化

本次发布把 forge-fupan 从“长篇会话总结 + 图表概览”调整为“表达优化、行为诊断、知识学习、AI 协作改进”的复盘工具，并补齐 Codex Desktop 会话读取、压缩后复盘、Workbench 反馈消费和知识模块学习图能力。

核心更新

报告结构收敛

• 删除“仪表盘速览”和“会话脉络”，不再强制生成 show-widget 仪表盘或 token 精力分布图。
• “工作叙事”改为 2-5 个短段落，只保留目标、关键转折、交付结果和协作问题。
• 删除独立“决策复盘”“避坑指南”“效率词典”“下次行动清单”，相关内容并入行为诊断、速查手册和末尾 TLDR。
• TLDR 移到全文最后，只沉淀需要记住的知识、表达优化和以后操作 SOP。

表达与行为复盘重构

• “逐条 Prompt 分析”只保留“表达问题”和“两档更好的说法”。
• “表达问题”要求短、准、具体，避免“表达不够清楚”这类空话。
• “更好的说法”拆成“低关键词版”和“进阶版”：前者不假设用户知道术语，后者引入知识点关键词，帮助形成更像工程任务单的表达。
• “模式诊断”改为“行为诊断”，用“问题 / 分析 / 建议”分析跨 Prompt 的低效协作行为。

知识拓展升级

• “知识拓展”从大领域调研改为按单个知识点展开。
• 每个知识点固定包含“是什么 / 怎么用 / 延伸学习”。
• 每个知识点必须先 web research，延伸学习 至少提供 1 个可打开的权威来源链接；来源优先官方文档或主流项目文档，不强求每类资源都齐全。
• 每个最终展开的知识模块默认生成 1 张 Image 2 学习图，放在知识模块标题下方；图片失败时保存 prompt pack，不阻塞复盘正文。

Claude / Codex 会话兼容

• 预检脚本新增 Codex Desktop 会话定位：优先用 CODEX_THREAD_ID 匹配 ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl，并兼容 ~/.codex/archived_sessions。
• 保留 Claude Code ~/.claude/projects/**/*.jsonl 支持。
• parse_tokens.py 同时支持 Claude message.usage 和 Codex event_msg.token_count.payload.info.total_token_usage。
• Codex token 统计使用累计快照差分，避免流式刷新重复计数。

压缩后复盘策略

• 前置检查会统计原始 user/agent/tool/compacted 事件，并输出 FULL_LOG_AVAILABLE、PARTIAL_LOG_AVAILABLE 或 SUMMARY_ONLY_OR_MISSING。
• 如果当前上下文已压缩但本地 JSONL 仍有原始消息，允许从 JSONL 恢复完整复盘。
• 如果只能拿到摘要，降级为轻量复盘：跳过逐条 Prompt 分析，不伪造用户原话、轮次或行为序列证据。

Workbench 反馈入链

• Workbench 提交的 selection.feedback 明确成为全局写作约束。
• 用户补充反馈会影响知识调研、行为诊断取舍、AI 表现复盘和 TLDR/SOP。
• 如果用户反馈与推荐深度或 AI 推断冲突，优先遵循用户反馈；无法执行时必须在最终文档说明冲突。

AI 表现复盘调整

• 删除固定“需求理解准确度”等四维评分。
• 改为让 AI 基于会话证据自行识别表现问题，并说明用户下次可以提供哪些信息、约束或检查点来帮助 AI 更快做对。

关键文件

• skills/forge-fupan/SKILL.md
• skills/forge-fupan/parse_tokens.py
• skills/forge-fupan/workbench/task_store.py
• skills/forge-fupan/workbench/frontend/src/main.jsx
• skills/_shared/visual-decision-layer.md
• docs/PRD.md
• docs/DESIGN.md
• docs/ENGINEERING.md
• docs/QA.md
• docs/skills-reference.md
• README.md

验收

• parse_tokens.py 已在 Codex Desktop JSONL 上验证，输出 日志格式: codex。
• parse_tokens.py 已在 Claude Code JSONL 上验证，输出 日志格式: claude。
• 当前已压缩的 Codex JSONL 原始会话检查输出 复盘可用性: FULL_LOG_AVAILABLE。
• Codex 内置 image_gen 已生成测试学习图，确认图片默认路径可用。
• python3 /Users/dbwu/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/forge-fupan 通过。
• python3 -m unittest discover -s skills/forge-fupan/workbench/tests -p 'test_*.py' 通过。
• python3 -m py_compile skills/forge-fupan/workbench/task_store.py skills/forge-fupan/parse_tokens.py skills/_shared/generate_image2.py 通过。
• npm run build 通过。
• git diff --check 通过。

不包含

• 不改变 Workbench 的本地单用户定位。
• 不引入云同步、账号系统、数据库或知识图谱。
• 不把 Image 2 学习图作为事实证据；它只用于知识记忆和理解辅助。

v2026.04.25 — Bug 修复验收报告与 QA 自动闭环

v2026.04.25 — Bug 修复验收报告与 QA 自动闭环

本次发布把 forge-qa 与 forge-bugfix 从“测试后再修 bug”的松散协作，升级为一套可跨会话、可批量、可人工最终验收的闭环体系。

核心理念

• 批次 = 管理单元：聚合多个 bug 的状态、进度、最终验收入口。
• Bug = 工程单元：每个 bug 都有独立编号、独立报告、独立状态。
• Worktree = 隔离单元：每个 bug 独立 worktree，失败可丢弃，合并可预演。
• TDD = 质量单元：每个 bug 都要有 RED 失败证明和 GREEN 通过证明。
• QA = 验收单元：每个 bug 都由 forge-qa 回归，最终由用户或批次验收收口。

批量修复只改变管理方式，不改变单 bug 的工程边界。

新能力

Bug 修复验收报告

单 bug 文档从“修完后生成的验收清单”升级为从发现到关闭的案卷：

docs/bugfix/reviews/BF-XXXX.md

报告记录：

• 问题发现记录、初始截图和关联 Feature Spec
• 复现步骤和根因分析
• worktree、branch、commit、涉及文件
• TDD / 回归用例的红绿证据
• 前后端验收地址和环境身份校验
• 人工验收指南
• QA 测试过程、逐步截图和深度断言
• 最终结论和新发现分流

QA 自动闭环

功能开发完成后，forge-qa 可以发现结构化 bug 候选，交给 forge-bugfix 自动修复，再由 forge-qa 回归：

forge-qa
→ BF candidate
→ forge-bugfix 独立 worktree/TDD 修复
→ forge-qa Mode B 回归
→ qa-pass-pending-final-review
→ 最终人工验收

自动闭环不是无限循环。同一 bug 连续回修失败 3 次，或遇到需求、设计、环境身份疑问时，必须进入 blocked-human，由用户判断。

Codex Browser Use 接入

在 Codex 环境中，前端页面、交互、视觉、控制台相关 QA 优先使用 browser-use:browser：

• 用 Codex in-app browser 打开本地 APP_URL
• 采集 DOM snapshot 和用户视角截图
• 将关键状态节点截图保存到报告并 Markdown 内嵌
• 读取 console logs，console.error 进入 FAIL

Playwright 继续负责可重复脚本断言；gstack/browse 可作为已有项目补充；Computer Use 只在 Browser Use 不可用或目标不是浏览器页面时兜底。

前后端环境身份强校验

QA 和人工验收必须使用同一组地址。报告会展示：

• Frontend URL
• Backend/API URL
• URL 来源
• PID
• cwd
• branch / commit
• health check 或关键接口探活结果

如果 PID/cwd 不属于当前 worktree，或 QA 实际访问地址与人工验收入口不一致，直接 QA_FAIL。

v7.1 证据完整性门禁补充

本 release 追加 forge-bugfix v7.1，进一步把验收质量从“AI 描述已修复”收紧到“用户问题闭环已被证据证明”：

• 新增 validate-bugfix-report.py，在进入人工验收前机器校验报告。
• 前端/交互 bug 必须有 Markdown 内嵌 QA 截图，且截图文件真实存在。
• 报告必须包含“用户问题闭环断言”：用户原话、最终用户可见结果、证明方式、PASS/FAIL 结论。
• 涉及前端展示、权限边界、数据可见性、灰度/冷启动的 bug，必须记录配置 / 开关 / 数据就绪检查。
• 每个 bug 原则上必须提供独立 worktree 证据；无独立 worktree 不进入 P5。
• 状态枚举收紧为固定集合，qa-incomplete 不能被描述成 pending user verification。

变更内容

• forge-bugfix 新增 P2.5：bug 登记/领取时创建或更新 Bug 修复验收报告。
• forge-bugfix P5 改为独立 TDD 驱动修复，P5.3 写入红绿证据。
• forge-bugfix P6 支持单 bug 验收和批次待最终验收两种节奏。
• forge-bugfix v7.1 新增用户问题闭环、配置/开关/数据就绪和报告完整性校验器门禁。
• forge-qa Mode A 发现问题时产出结构化 BF candidate。
• forge-qa Mode B 回填 Bug 修复验收报告中的 QA 证据区、环境身份区和逐步截图。
• backlog.md 增加 fixed-awaiting-qa、qa-failed、qa-pass-pending-final-review、blocked-human、deferred 等状态。
• review-checklist.md 模板重写为 Bug 修复验收报告模板。

适用场景

小批量修复

一个会话内完成：

QA → bugfix → QA 回归 → 用户验收

大系统多天修复

多个会话并行处理：

backlog / QA 报告
→ 多个 BF 分别领取
→ 每个 BF 独立 worktree/TDD/QA
→ 批次汇总
→ 用户最终统一验收

验收

• git diff --check passed for release scope.
• Skill frontmatter 已确认可被 Codex 加载。
• forge-bugfix / forge-qa / 模板路径均指向当前 cookbook symlink。
• 本次为流程和文档规范发布，不包含业务代码运行测试。

不包含

• 当前工作区中已有的 skills/forge-fupan/workbench/* 未提交改动不属于本次发布。

v2026.04.24.3 — Fupan Workbench 批注修复

v2026.04.24.3 — Fupan Workbench 批注修复

本次是 v2026.04.24.2 的 Workbench 体验补丁，重点修复用户在浏览器里标注出的布局问题，并补齐“表达待优化原话”的数据契约。

能力说明

复盘前学习确认

Workbench 首页会展示当前复盘任务、LLM 判断出的表达待优化原话、背景原话、候选知识区和三档学习深度。用户可以在本地页面确认“学什么、学到什么程度”，再让 forge-fupan 继续调研。

历史复盘网页阅读

历史复盘详情页会把 Markdown 复盘文档渲染成网页，左侧展示知识地图，正文保留复盘内容，便于把本地 Markdown 文件库转成可阅读的本地知识库。

修复内容

• 修复顶部 127.0.0.1 与“刷新状态”按钮在中等宽度下重合。
• 修复知识区卡片的 了解 / 表达 / 复现 按钮不在底部对齐。
• 修复反馈输入框与 footer 操作区间距不足。
• 新增 expression_issue_quotes task 字段，forge-fupan 生成学习地图时由 LLM 自行判断并摘录表达待优化原话。
• 前端兼容老 task：没有 expression_issue_quotes 时仍显示 user_questions。

验收

• npm run build passed
• pytest passed: 5 passed
• python3 -m py_compile skills/forge-fupan/workbench/*.py passed
• Playwright 截图已写入 docs/assets/fupan-workbench/
• 浏览器 console error = 0

v2026.04.24.2 — Fupan Workbench + 视觉决策层

[v2026.04.24.2] — 2026-04-24（Fupan Workbench + 视觉决策层）

Added

• forge-fupan 本地 Workbench：新增 skills/forge-fupan/workbench/，包含 FastAPI 本地服务、React/Vite 静态前端、task JSON 状态流和历史复盘浏览。
• 学习地图确认：复盘先生成候选知识区，用户在页面选择数量和深度（了解 / 表达 / 复现）后，AI 再继续调研。
• 多任务队列：多个复盘 task 可并存，页面只展开一个完整表单；AI 只轮询自己的 task ID。
• 历史复盘网页阅读：首页按历史索引展示“学到的知识”，详情页渲染 Markdown。
• Forge 视觉决策层：新增 skills/_shared/visual-decision-layer.md，统一规定 brainstorm、PRD、design、design-impl、eng、QA、fupan 中何时使用 Mermaid/show-widget、Image 2 和真实截图。
• Image 2 生成脚本：新增 skills/_shared/generate_image2.py，按统一约定保存图片、prompt 和 meta，缺少 OPENAI_API_KEY 时保留 prompt pack 并降级。

Changed

• 复盘表达语气调整：将旧的批改感措辞改为“表达复盘”“待补背景”“增加的沟通成本”等学习型表达。
• 运行态轻量化：前端由 Vite 构建为静态文件，运行时由 FastAPI 托管，不要求用户手动启动 npm dev server。
• 前端设计门禁前移：forge-design 对新页面/组件/状态要求先生成 1-3 张 Image 2 视觉稿供用户确认；forge-qa 明确 Image 2 只作观感参考，不作为通过证据。
• Skill frontmatter 兼容最新校验：移除旧式 version 字段，确保全部 forge-* skill 通过最新 skill-creator 的 quick_validate.py。

Notes

• 第一版只面向本机单用户，不做账号、云同步、数据库、全文搜索或知识图谱。
• FastAPI/Uvicorn 缺失时，forge-fupan 应降级到对话内确认。
• 视觉稿不替代 DESIGN.md、Feature Spec、CSS 断言或真实截图；它只用于提前暴露误解和辅助人工判断。

v2026.04.24.1 - Dev Server 端口治理

核心变化

这版把 worktree 启动前后端从'靠人记住端口'改成'由项目统一状态入口负责'，目标是 main 只跑一套服务、worktree 不抢端口、QA 不测错进程。

重点

• forge-bugfix 升到 v6.1：复现、截图、curl、QA 的 APP_URL 必须来自 dev:status/dev-stack，不再猜常见端口。
• forge-eng 新增 Dev Server 端口契约：worktree 内如需运行应用，优先使用项目统一 dev entrypoint，收尾前停止当前 worktree 服务。
• forge-qa 升到 v3.2：浏览器验收不再自行扫描 localhost:3000/5173/8080。
• forge-status 增加只读 dev server 巡检：展示 .devserver.json、tmux、监听端口、PID、cwd，但不参与 active.md 僵尸判定。
• /forge 总入口会展示项目 dev server 状态，便于一眼看清当前到底跑着哪套前后端。

为什么重要

之前多 worktree 并行时，旧 Vite 或 uvicorn 进程可能继续占着端口，导致浏览器看到旧代码、QA 测到错分支。这版把 URL 和进程 cwd 绑定到状态输出里，减少这类排查成本。

v6.0 多会话并行协调

v6.0 多会话并行协调

痛点：v5.0 串行修 bug，但用户能同时照看 3-4 个 Claude Code 窗口，瓶颈卡在 AI 写代码速度。

核心改动

• .forge/active.md 心跳文件（session id / worktree / 任务 / 功能域）
• 功能域判重（业务视角，不是文件集）——同域归并会话、异域鼓励并行
• 合并前 git merge --no-commit --no-ff 预演兜底
• 新 skill /forge-status：扫 active.md 按硬信号（worktree 存在性 + 分支合并状态）清理僵尸
• session id 自动获取脚本（PID 回溯 `~/.claude/sessions/.json`）
• `forge-fupan` Phase 5.0 清理本会话登记

闭环哲学

清理只认硬信号（worktree 不存在 / 分支已合并），不用时间戳。正常走 forge-fupan 自动清，漏清走 /forge-status 扫描兜底。

文档同步

README / SKILL.md / forge-user-guide / skills-reference / CHANGELOG 都已同步，Skills 14 → 15。

完整讨论记录

`docs/iterations/2026-04-19-多会话并行协调.md`：本次迭代的痛点、7 个关键转折（文件集判重被否决、时间戳兜底被否决、skill 合一等）、设计 why、AI 过度设计反思。宣传和回顾用。

安装

```bash
git pull
./install.sh
```

新会话启动 forge-bugfix 会自动进入 v6.0 流程；旧会话保持原样。

v2026.04.19 — forge-bugfix 双层验收清单

摘要

给 bug 修复加上结构化双层验收清单（forge-qa 自动 + 用户人工），解决"修到第 5 个还没封闭"的边界模糊问题；新发现一律分流到 backlog，禁止当场顺手修。

核心改变

• 每次修复生成表格化验收清单文档 docs/bugfix/reviews/BF-{MMDD}-{N}.md（单 bug 单文档）
• 双层验收：forge-qa 新增 Mode B 做自动验收 → 用户人工二次验收 → 用户填最终结论（Pass / Fail / Pass + 新发现）才算封闭
• 新发现强制分流到 `docs/bugfix/backlog.md`，4 区结构：🐛 待修 / 💡 新需求 / 🌀 待澄清 / 🗄️ 已处理永久保留
• 同根判定必须举证（同文件/同函数/同数据流），举证不足默认独立 bug
• `forge-bugfix` 流程新增 P5.3（生成清单）/ P6.5（用户验收）/ P7.5（新发现分流）节点
• 下一个 bug 默认建议新会话或 /clear、/compact，避免长会话 scope 蔓延

完整信息

• 迭代记录（推荐先读）
• CHANGELOG
• R11 规则模板（供其他用户抄到 CLAUDE.md）
• 讨论过程（如何从"主线映射"推翻到"双层验收清单"）
• forge-bugfix 演进索引

涉及文件

• `skills/forge-bugfix/SKILL.md`（流程改造）
• `skills/forge-qa/SKILL.md`（新增 Mode B，Mode A 不变）
• `skills/forge-bugfix/templates/review-checklist.md`（新）
• `skills/forge-bugfix/templates/backlog.md`（新）
• 文档沉淀若干（详见 CHANGELOG）

迁移提示

• 如果你之前用 `TODO.md` 维护 bug 任务，迁移到 `docs/bugfix/backlog.md`（4 区结构）
• 在你自己的 `CLAUDE.md` 里加入 R11 规则（抄 `updatemd/claude-md/2026-04-19-R11-双层验收清单.md` 里的模板段）
• skill 通过 `install.sh` 软链的用户，拉取最新代码即可；不需要重新 install