@rowansenne/workflow-run 0.21.2 → 0.22.1

package/dev/references/delivery-template.md

@@ -5,7 +5,7 @@
 > 参考产物：{{开发方案路径，没有写「无」}}
 > DocNexus：{{沉淀后写 docnexus/library/<path>；未沉淀写「未沉淀」，未接入写「未接入」}}
 
-<!-- F8 / B5 交付时按此落盘到 requirement.mjs path delivery 给出的路径（workflow-run/docs/requirements/<需求名>/delivery.md）。小改动每节写一两行即可，不适用的节写「无」；验证结果必须如实 -->
+<!-- F8 / B5 交付时按此落盘到 requirement.mjs path delivery 给出的路径（workflow-run/docs/requirements/<需求名>/<项目名>/delivery.md）。小改动每节写一两行即可，不适用的节写「无」；验证结果必须如实 -->
 
 ## 结果 *
 
@@ -22,9 +22,14 @@
 
 ## 验证 *
 
+| 验收项 | 测试 / 操作 | 结果 |
+|---|---|---|
+| {{F1 / F3 的验收标准，每条一行；缺陷修复写「现象不再出现」}} | {{测试类.方法，或手动操作步骤}} | {{通过 / 失败 / 未验证（原因）}} |
+
 - 构建：{{命令}} → {{通过 / 失败 / 未运行（原因）}}
 - 测试：{{命令}} → {{通过 n 个 / 失败 / 未运行（原因）}}；新增测试：{{列表}}
-- 未验证项：{{需要用户在什么环境怎么验证；没有写「无」}}
+- 开工前已有的失败：{{Step 0 基线里已经失败的测试 / 编译错误，本次未处理；没有写「无」，没跑基线写原因}}
+- 未验证项：{{表里「未验证」的验收项及其他：需要用户在什么环境怎么验证；没有写「无」}}
 
 ## 根因（如有）
 
@@ -45,7 +50,7 @@
 
 ## 范围外发现
 
-{{顺带看到但本次未处理的问题；无则写「无」}}
+{{顺带看到但本次未处理的问题；开工前工作区里与本需求无关的改动（文件列表，未提交）及自审在其中发现的问题；无则写「无」}}
 
 ## 建议下一步
 

package/dev/skill.json

@@ -2,10 +2,10 @@
   "name": "dev",
   "order": 2,
   "requires": [
-    "workflow"
+    "workflow",
+    "project-review"
   ],
   "optional": [
-    "project-review",
     "database-query",
     "md-to-wiki",
     "create-tech-md-doc",

package/md-to-wiki/SKILL.md.tpl

@@ -70,7 +70,7 @@ node <skillDir>/scripts/md-to-wiki.mjs <mdPath> workflow-run/tmp/md-to-wiki/_wik
 - `references/upload.md`：通道 A / B 的调用细节与验证
 - `references/troubleshooting.md`：转换脚本说明、XHTML 规则、校验命令、常见错误
 
-典型串联：`create-tech-md-doc` / `create-release-md-doc` 生成 `workflow-run/docs/requirements/<需求名>/` 下的 md → 本 skill 发布。
+典型串联：`create-tech-md-doc` / `create-release-md-doc` 生成 `workflow-run/docs/requirements/<需求名>/<项目名>/` 下的 md → 本 skill 发布。
 
 ## 终端命令
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rowansenne/workflow-run",
-  "version": "0.21.2",
+  "version": "0.22.1",
   "description": "项目级 Agent Skills 一键初始化：workflow / dev / project-review / code-graph / database-query / md-to-wiki / 技术与上线方案生成",
   "keywords": [
     "agent-skills",

package/project-review/SKILL.md.tpl

@@ -30,10 +30,11 @@ description: "Review source code (any language; Java/Spring, Go, TypeScript, Pyt
    3. 找有没有别处已经兜住：调用方校验、`@Validated` / 全局异常处理、数据库约束、框架默认行为、配置。涉及索引、字段、唯一约束、表大小的发现，以第 2 步拉到的实际表结构为准（复核列写「已与 <连接名> 核对」）。已兜住 → 删掉或降级，并在说明里写依据。
    4. 确认是本次改动引入的：改动前就存在的问题移到「未覆盖与待确认」，不计入合并结论。
    结果：「成立」在报告「复核」列标「✅」；「可能成立」标「⚠」；「不成立」从问题表里删掉（独立复核否掉的，在「未覆盖与待确认」里记一句「复核排除 N 条」）。复核方式（独立 / 自行）写进报告「审查方式」元信息。
-7. **输出报告**：按报告模板输出（`node <skills>/workflow/scripts/resolve.mjs template project-review report.md` 取 `path`；退出码 2 时停下并按 `hint` 处理），落盘规则见 Artifact Location。
+7. **输出报告**（由 dev 自审调用时跳过第 7～9 步，问题表、影响面、未覆盖项交回 dev 统一交付，见 dev 的 F7）：按报告模板输出（`node <skills>/workflow/scripts/resolve.mjs template project-review report.md` 取 `path`；退出码 2 时停下并按 `hint` 处理），落盘规则见 Artifact Location。
 8. **沉淀到 DocNexus（需用户授权）**：`resolve.mjs status` 的 `docnexus.ok` 为 true 时，交付报告后**每次都问**用户「要不要启动 DocNexus 流程，把本次审查沉淀到 DocNexus？」，并从本次发现里列出建议沉淀的内容：同类问题再次出现（知识库里已有类似沉淀，或本次多处出现）、新确立的编码约定、容易踩的坑；没有特别值得记的也照问，并说明这一点。未接入时不提问，报告的「DocNexus」元信息行写「未接入」。
    - 用户同意 → 按 DocNexus 入口 skill `docnexus` 的 capture 流程写入；正文只写知识，不写分支、路径；有 facts 时按 `<skills>/workflow/references/docnexus.md`「沉淀的来源」的格式写 provenance；分类用 `node <skills>/workflow/scripts/resolve.mjs category project-review` 的结果作为调用方显式分类封存（见 `<skills>/workflow/references/docnexus.md`「写入 DocNexus 的分类」）。只沉淀问题模式和约定，不沉淀某次审查的逐条清单，也不沉淀「⚠ 待确认」的发现；知识库已有同类沉淀时更新那一篇（带 `--base-version`），不要重复新建。写入成功后把报告的「DocNexus」元信息行改成 `docnexus/library/<path>`（多篇用「、」分隔），并回报给用户。
    - 用户不同意 → 元信息行保持「未沉淀」。
+9. **记录运行反馈**（不问用户）：按 `<skills>/workflow/references/feedback.md` 运行 `node <skills>/workflow/scripts/feedback.mjs add --skill project-review --model <模型名> --mode review --depth <快审|标准|深审> --rounds <提问轮数> --corrections <用户纠正审查范围的次数> --findings <C>/<H>/<M>/<L>`，有跳过的步骤、不清楚或做不到的规则、用户的抱怨时再加 `--skipped` / `--unclear` / `--feedback`。只写过程，不写代码和业务名词；报错就提一句，不影响交付。
 
 ## 只报会出问题的
 
@@ -74,7 +75,7 @@ description: "Review source code (any language; Java/Spring, Go, TypeScript, Pyt
 
 ## Artifact Location
 
-审查报告按需求归档在 `workflow-run/docs/requirements/<需求名>/`，规则见 `<skills>/workflow/references/requirements.md`：
+审查报告按需求归档在 `workflow-run/docs/requirements/<需求名>/<项目名>/`，规则见 `<skills>/workflow/references/requirements.md`：
 
 - 路径用 `node <skills>/workflow/scripts/requirement.mjs path review`（分支对比按 dev 分支加 `--branch <dev分支>`），写到输出的 `path`（文件名固定为 `review.md`）；已有报告时脚本先把它归档，输出的 `previous` 是上次报告，复审对照它。
 - 退出码 2（这个分支还没绑定需求）：问用户这个需求叫什么，默认值用输出的 `suggested_name`，再 `requirement.mjs bind --name "<需求名>" [--branch <dev分支>]`；用户不给名字时 `bind` 按分支名生成。

package/workflow/SKILL.md.tpl

@@ -49,7 +49,7 @@ dev（需求 → 方案 → 实现 → 测试 → 自审）
   → DocNexus 沉淀（可选，需授权）
 ```
 
-开始完整链路时先确定需求名：`node <skills>/workflow/scripts/requirement.mjs which`，当前分支没绑定就问用户这个需求叫什么并 `bind`（见 `references/requirements.md`），之后各段产物都落在 `workflow-run/docs/requirements/<需求名>/`。
+开始完整链路时先确定需求名：`node <skills>/workflow/scripts/requirement.mjs which`，当前分支没绑定就问用户这个需求叫什么并 `bind`（见 `references/requirements.md`），之后各段产物都落在 `workflow-run/docs/requirements/<需求名>/<项目名>/`。
 
 提交、推送、发布 wiki、写入 DocNexus 都是对外动作，每一步都要用户明确同意。
 
@@ -63,7 +63,7 @@ dev（需求 → 方案 → 实现 → 测试 → 自审）
 | `references/templates.md` | 模板来源判定（`resolve.mjs template`）、创建与修改模板（`/workflow template`）、模板随知识库更新 |
 | `references/docnexus.md` | 写入 DocNexus 的分类（`resolve.mjs category`）、按分类参考知识库（`knowledge.mjs`） |
 | `references/status.md` | `/workflow status` 的输出格式 |
-| `references/requirements.md` | 产物按需求归档（`workflow-run/docs/requirements/<需求名>/`）：什么时候问需求名、`requirement.mjs` 绑定分支与给出落盘路径、`meta.json` |
+| `references/requirements.md` | 产物按需求归档（`workflow-run/docs/requirements/<需求名>/<项目名>/`）：什么时候问需求名、`requirement.mjs` 绑定分支与给出落盘路径、`meta.json` |
 | `references/tables.md` | 确定改动涉及哪些表（`tables.mjs`）、只读拉取实际表结构 / 索引 / 行数核对（`query.mjs --schema --indexes`），没有库连接时怎么退回 |
 | `references/codegraph.md` | 用 CodeGraph 代码图谱读代码、查调用链与影响面（MCP 工具与 CLI 对照、图谱看不到的部分） |
 

package/workflow/references/feedback.md

@@ -0,0 +1,34 @@
+# 运行反馈
+
+每次 skill 跑完，用 `workflow/scripts/feedback.mjs add` 追加一行过程记录，写到 `workflow-run/feedback/<git 用户名>.jsonl`（每人一个文件，随 `workflow-run/` 提交）。团队攒两三周后用 `npx @rowansenne/workflow-run feedback` 汇总，作为精简 SKILL.md 的依据：哪些步骤常被跳过、哪些规则读不懂或做不到、提问是不是太多。装了新版本（`init` / `upgrade`）时会清掉本项目旧版本的记录，从新版本重新收集。
+
+## 规则
+
+- **不问用户、不打断**：交付时静默记录，不为了记录多问一句，也不请用户打分。
+- **只写过程，不写内容**：不写代码、类名、方法名、表名、接口路径、业务名词、客户信息。这个文件会被发给维护 skill 的人。
+- **如实**：跳过了就写跳过，问了几轮就写几轮；不美化。拿不准的数字不写那个参数。
+- **失败不影响交付**：命令报错就在对话里提一句，不重试、不排查。
+- **一次运行记一行**：dev 内部调用 project-review 自审时只由 dev 记，project-review 不另记。
+
+## 参数
+
+所有参数都是 `--名称 值`，值里有空格时加双引号；`--skipped`、`--unclear`、`--feedback` 可重复。
+
+| 参数 | 值 | 说明 |
+|---|---|---|
+| `--skill` | `dev` / `project-review` | 必填 |
+| `--model` | 你的模型名，如 `claude-opus-5-5`、`qwen3-coder` | 不知道就写所在的工具名 |
+| `--mode` | `feature` / `bug` / `review` | dev 的功能开发 / 缺陷修复；审查写 `review` |
+| `--size` | `S` / `M` / `L` | dev 的规模 |
+| `--fast` | `yes` / `no` | dev 是否走了快速通道 |
+| `--depth` | `快审` / `标准` / `深审` | project-review 的深度 |
+| `--rounds` | 整数 | 向用户提问的轮数（澄清、确认方案都算；只问提交那一下不算） |
+| `--corrections` | 整数 | 用户纠正你对需求 / 审查范围理解的次数 |
+| `--acceptance` | `已验证/总数`，如 `3/4` | dev 交付说明「验证」表里的验收项 |
+| `--baseline-failures` | 整数 | dev Step 0 基线里已有的失败数 |
+| `--findings` | `C/H/M/L`，如 `0/1/2/0` | project-review 各级别发现条数（复核后） |
+| `--skipped` | `<步骤>: <原因>`，如 `F6: 缺 Redis，集成测试没跑` | 本该做却没做的步骤，每步一条 |
+| `--unclear` | `<章节>: <哪条规则、怎么不清楚>`，如 `F4: S 和快速通道的条件重复，不确定要不要都满足` | **最有用的一项**：读不懂、互相矛盾、在这个项目做不到、或你觉得多余的规则；没有就不写 |
+| `--feedback` | 一句话 | 用户主动说的抱怨或建议的大意（如「问得太多」「交付说明太长」）；用户没说就不写 |
+
+`<步骤>` / `<章节>` 用 SKILL.md 里的编号（`Step 0`、`F3`、`B2`，project-review 写 `第 3 步`），汇总时按它归类。

package/workflow/references/profile.md

@@ -13,7 +13,7 @@
 | `job_annotation` | 定时任务注解（如 `@XxlJob`、`@Scheduled`） | 技术方案「定时任务变更」 |
 | `data_review` | 上线前是否需要数据团队评审库表（`true` / `false`） | 技术方案模块 7、上线方案 2.3 |
 | `notes` | 其他项目约定，一条一句（如「启动需要本地 Redis」） | 全部 |
-| `artifacts` | 可选：`{ "project": "order-service", "commit_prompt": true }`。`project` 是 `workflow-run/` 为独立文档仓库时这个项目在里面的名字（产物在 `workflow-run/docs/requirements/<需求名>/<项目名>/`）；`commit_prompt: false` 关闭写完后的提交提示。个人设置可写在 `workflow/profile.local.json`（不提交）覆盖 | 见 `references/requirements.md`，用 `requirement.mjs config` 修改 |
+| `artifacts` | 可选：`{ "project": "order-service", "commit_prompt": true }`。`project` 是这个项目的产物目录名（产物在 `workflow-run/docs/requirements/<需求名>/<项目名>/`，随代码提交和独立文档仓库两种用法都一样）：随代码提交时不配置就取 git 远端仓库名，第一次落盘时自动写进来；独立文档仓库时要先配置；`commit_prompt: false` 关闭写完后的提交提示。个人设置可写在 `workflow/profile.local.json`（不提交）覆盖 | 见 `references/requirements.md`，用 `requirement.mjs config` 修改 |
 | `docnexus_categories` | 可选，覆盖各 skill 写入 DocNexus 时的分类，如 `{"create-tech-md-doc": "技术方案"}`；不填用 skill 默认 | 见 `references/docnexus.md` |
 
 其他 skill 读画像统一用 `node <skills>/workflow/scripts/resolve.mjs profile`：输出 `profile`（文件内容）、`empty`（空字段）、`complete`（`main_branch` / `build` / `test` 都已填写）、`env`（本机系统与终端，见下）。

package/workflow/references/requirements.md

@@ -1,9 +1,9 @@
 # 产物按需求归档（dev / project-review / 技术方案 / 上线方案共用）
 
-一个需求的全部产物放在同一个目录，整条链路一眼看全，`/workflow view` 也直接读这里。本工具的产出都在项目根的 `workflow-run/` 里（需求产物、DocNexus 工作区、项目模板、临时文件），不往项目的其他地方写。默认 `workflow-run/` 随代码提交（下图）；团队也可以把独立的文档仓库克隆到 `workflow-run/`，见最后一节。
+一个需求的全部产物放在同一个目录，整条链路一眼看全，`/workflow view` 也直接读这里。本工具的产出都在项目根的 `workflow-run/` 里（需求产物、DocNexus 工作区、项目模板、临时文件），不往项目的其他地方写。默认 `workflow-run/` 随代码提交；团队也可以让 `workflow-run/` 成为独立的文档仓库，见最后一节。两种用法的目录结构完全一样（下图），切换时文件不用挪。
 
 ```
-workflow-run/docs/requirements/<需求名>/
+workflow-run/docs/requirements/<需求名>/<项目名>/
 ├── meta.json          # 需求名、绑定的分支、各产物（种类、版本、日期、wiki 发布记录、DocNexus 沉淀）
 ├── plan.md            # 开发方案（dev，L 规模或用户要求时）
 ├── delivery.md        # 交付说明（dev）
@@ -12,7 +12,9 @@ workflow-run/docs/requirements/<需求名>/
 └── release-doc.md     # 上线方案（create-release-md-doc）
 ```
 
-这个目录写在项目根的 `.ignore` 里，不参与代码搜索（找历史决策用 DocNexus）。读写一律按下面脚本给出的路径，不要靠搜索找这些文件，也不要自己拼路径。两种放法下各 skill 的做法完全一样，区别都在脚本里。
+一个需求横跨多个服务时，各服务在同一个需求目录下各占一个 `<项目名>/`。项目名是 `workflow/profile.json` 的 `artifacts.project`：随代码提交时不用配置，脚本取 git 远端仓库名，第一次 `bind` 时写进 `profile.json` 固定下来；独立文档仓库时要先配置（见最后一节）。
+
+这个目录写在项目根的 `.ignore` 里，不参与代码搜索（找历史决策用 DocNexus）。读写一律按下面脚本给出的路径，不要靠搜索找这些文件，也不要自己拼路径。两种用法下各 skill 的做法完全一样，区别都在脚本里。
 
 ## 需求名：流程开始或第一次落盘时问用户
 
@@ -41,14 +43,14 @@ node <skills>/workflow/scripts/requirement.mjs which
 node <skills>/workflow/scripts/requirement.mjs path <plan|delivery|review|tech|release>
 ```
 
-- 输出的 `path` 就是要写的文件（相对项目根）。文档里引用产物（「参考产物」、上线方案引用技术方案等）写输出的 `cite`：默认模式下和 `path` 相同；文档仓库模式下是「文档仓库名:仓库内路径」，各服务、各人的克隆里都一样。每种产物的文件名固定（`review.md`、`tech-doc.md` …），引用它的地方不会因为出了新版而失效。已有时，脚本先把当前版复制到 `workflow-run/tmp/old-artifacts/<需求名>/<种类>_v<N>.md`，输出的 `previous` 就是这份（复审对照上次的报告读它），`version` 是这次的版本号；然后把新版直接写到 `path`。
+- 输出的 `path` 就是要写的文件（相对项目根）。文档里引用产物（「参考产物」、上线方案引用技术方案等）写输出的 `cite`：默认模式下和 `path` 相同；文档仓库模式下是「文档仓库名:仓库内路径」，各服务、各人的克隆里都一样。每种产物的文件名固定（`review.md`、`tech-doc.md` …），引用它的地方不会因为出了新版而失效。已有时，脚本先把当前版复制到 `workflow-run/tmp/old-artifacts/<需求名>/<项目名>/<种类>_v<N>.md`，输出的 `previous` 就是这份（复审对照上次的报告读它），`version` 是这次的版本号；然后把新版直接写到 `path`。
 - 退出码 2：当前分支还没绑定需求，按上一节问用户需求名，`bind` 之后再运行一次。
 - `wiki_record` 非空：上一版已经发布到 wiki。新版的**第一行原样写这条记录**，md-to-wiki 再发布时会更新同一个页面，不会新建页面。
 - 写完运行 `requirement.mjs sync <path>`，更新 `meta.json`。md-to-wiki 发布后改了第一行的记录，或补写了 DocNexus 元信息行，也要再 sync 一次。
-- sync 时新版内容和归档的上一版不同，才算新版本（`meta.json` 的 `versions` 加一）；没写就放弃的话版本号不变。输出里 `archived` 非空时，告诉用户归档了哪些文件、在哪里（`workflow-run/tmp/old-artifacts/<需求名>/`，文档仓库模式是 `<需求名>/<项目名>/`，不提交），请用户确认不再需要后自己删除；**不要替用户删**。随代码或文档仓库提交过的旧版也能从 git 历史找回。
+- sync 时新版内容和归档的上一版不同，才算新版本（`meta.json` 的 `versions` 加一）；没写就放弃的话版本号不变。输出里 `archived` 非空时，告诉用户归档了哪些文件、在哪里（`workflow-run/tmp/old-artifacts/<需求名>/<项目名>/`，不提交），请用户确认不再需要后自己删除；**不要替用户删**。随代码或文档仓库提交过的旧版也能从 git 历史找回。
 - sync 输出里 `commit` 非空：按下一节「文档仓库的提交」处理。
 
-## 独立文档仓库（克隆到 workflow-run/）
+## 独立文档仓库
 
 团队想让代码仓库保持干净、或者一个需求横跨多个服务时，用户在项目根运行（由用户执行，克隆可能要他们自己认证）：
 
@@ -56,11 +58,11 @@ node <skills>/workflow/scripts/requirement.mjs path <plan|delivery|review|tech|r
 npx @rowansenne/workflow-run docs-repo <团队文档仓库地址> [--project <项目名>]
 ```
 
-它把文档仓库克隆到 `workflow-run/`，代码仓库的 `.gitignore` 加 `/workflow-run/`，并配置好项目名。`workflow-run/` 自己是 git 仓库就是这个模式，不用别的配置。
+`workflow-run/` 里还没有内容时它直接克隆；已经有产物、DocNexus 时原地 `git init` 接上远端（目录结构相同，文件不用挪；和远端同路径冲突时退回原状并列出冲突的文件）。然后代码仓库的 `.gitignore` 加 `/workflow-run/`，并配置好项目名。`workflow-run/` 自己是 git 仓库就是这个模式，不用别的配置。
 
-- 布局：`workflow-run/docs/requirements/<需求名>/<项目名>/plan.md`、`delivery.md`……一个需求横跨多个服务时，各服务在同一个需求目录下各占一个子目录。绑定需求时 `which` 会列出 `other_projects`（其他服务已有、已拉到本地的需求），用同一个名字 `bind` 就加入了那个需求。
+- 布局和随代码提交时一样。绑定需求时 `which` 会列出 `other_projects`（其他服务已有、已拉到本地的需求），用同一个名字 `bind` 就加入了那个需求。
 - DocNexus 也在这个仓库里（`workflow-run/docnexus/`），各服务共用一个知识库。
-- `project`：这个项目在文档仓库里的名字，写在 `workflow/profile.json` 的 `artifacts.project`（随代码提交，团队共用），**只需配置一次**。没配时脚本退出码 2（`need_project`）并给出 `suggested_project`（git 远端仓库名）：问用户一次，然后运行 `requirement.mjs config --project <项目名>`，之后一直沿用。
+- `project`：这个项目在文档仓库里的名字，写在 `workflow/profile.json` 的 `artifacts.project`（随代码提交，团队共用），**只需配置一次**；随代码提交时已经自动写过的就直接沿用。没配时脚本退出码 2（`need_project`）并给出 `suggested_project`（git 远端仓库名）：问用户一次，然后运行 `requirement.mjs config --project <项目名>`，之后一直沿用。
 - 查看或修改配置：`requirement.mjs config [--project <项目名>] [--commit-prompt on|off] [--local]`。
 - `/workflow view` 在这个模式下显示文档仓库里所有项目的需求，一个需求下按项目区分产物。
 

package/workflow/scripts/artifacts.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // 按分支汇总各 skill 的产物：开发方案、交付说明、审查报告、技术方案、上线方案，以及它们的 wiki 发布记录。
-// 产物按需求归档在 workflow-run/docs/requirements/<需求>/（独立文档仓库模式再分 <项目>/，见 requirement.mjs）。
+// 产物按需求归档在 workflow-run/docs/requirements/<需求>/<项目>/（两种模式结构相同，见 requirement.mjs）。
 // 直接扫描 Markdown，从元信息行读分支（「分支：」「对比分支：」），
 // 从第一行的 <!-- md-to-wiki: ... --> 读发布记录（md-to-wiki 上传后写入）。只读。
 //
@@ -44,14 +44,15 @@ export function parseWiki(text) {
 
 const headerDate = (text) => /(\d{4}-\d{2}-\d{2})/.exec(text.replace(/<!--[\s\S]*?-->/g, '').split(/\r?\n/).slice(0, 8).join('\n'))?.[1] ?? ''; // 跳过 md-to-wiki 发布记录里的 at=
 
-// workflow-run/docs/requirements/<需求>/<文件> → 产物条目；不是已知产物返回 null
+// workflow-run/docs/requirements/<需求>/<项目>/<文件> → 产物条目；不是已知产物返回 null。
+// 分支里还没迁移的旧结构（<需求>/<文件>，没有项目这一层）也认，project 为 null
 function entry(rel, text, mtime) {
   const parts = rel.split('/');
-  if (parts.length !== 5 || parts.slice(0, 3).join('/') !== REQ_DIR) return null;
-  const p = parseFile(parts[4]);
+  if ((parts.length !== 5 && parts.length !== 6) || parts.slice(0, 3).join('/') !== REQ_DIR) return null;
+  const p = parseFile(parts.at(-1));
   const k = p && KINDS.find((x) => x.kind === p.kind);
   // 排序键：文档头里的日期 + 版本号（需求目录里的文件名不带日期）
-  return k ? { kind: k.kind, label: k.label, path: rel, requirement: parts[3], branch: parseBranch(text), date: `${headerDate(text)}#${String(p.version).padStart(3, '0')}`, mtime, wiki: parseWiki(text) } : null;
+  return k ? { kind: k.kind, label: k.label, path: rel, requirement: parts[3], project: parts.length === 6 ? parts[4] : null, branch: parseBranch(text), date: `${headerDate(text)}#${String(p.version).padStart(3, '0')}`, mtime, wiki: parseWiki(text) } : null;
 }
 
 const byDate = (a, b) => a.date.localeCompare(b.date) || a.mtime - b.mtime;

package/workflow/scripts/feedback.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+// 运行反馈：skill 每跑完一次追加一行到 workflow-run/feedback/<git 用户名>.jsonl，攒两三周后汇总，作为精简 SKILL.md 的依据。
+// 只记过程（提问轮数、跳过的步骤、哪条规则不清楚……），不记代码、类名、表名、业务名词；结果类数据（审查发现、未验证项）report.mjs 从产物里统计。
+// 每人一个文件、随 workflow-run/ 提交，多人不冲突；装了新版本（init / upgrade）时清掉本项目旧版本的记录（git 历史里仍可找回）。
+// 字段含义与记录规则见 workflow/references/feedback.md。
+//
+// 用法（在项目根执行；--root 可指定项目根）：
+//   node .agents/skills/workflow/scripts/feedback.mjs add --skill dev --model <模型> [--mode feature] [--size M] [--fast no] [--rounds 2] …
+//   node .agents/skills/workflow/scripts/feedback.mjs summary [--json]
+// --skipped / --unclear / --feedback 可重复。add 输出写到的文件（JSON）。退出码：0 正常；1 参数错误
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { homeDir, homeIsRepo, layout, suggestProject, dirName, HOME } from './requirement.mjs';
+
+const SKILLS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+export const FEEDBACK_DIR = 'feedback';
+
+// 字段 → 类型；list 可重复
+const FIELDS = {
+  skill: 'string', model: 'string', env: 'string',
+  mode: ['feature', 'bug', 'review'], size: ['S', 'M', 'L'], depth: ['快审', '标准', '深审'], fast: ['yes', 'no'],
+  rounds: 'int', corrections: 'int', 'baseline-failures': 'int',
+  acceptance: /^\d+\/\d+$/, findings: /^\d+\/\d+\/\d+\/\d+$/,
+  skipped: 'list', unclear: 'list', feedback: 'list',
+};
+
+const readJson = (f) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; } };
+const gitOut = (root, args) => spawnSync('git', args, { cwd: root, encoding: 'utf8' }).stdout?.trim() ?? '';
+
+export const feedbackDir = (root) => path.join(homeDir(root), FEEDBACK_DIR);
+export const projectName = (root) => layout(root).project ?? suggestProject(root);
+
+// 安装清单里的版本（skills 装在 .agents/skills/，清单在同一目录）；从源码仓库直接运行时用 package.json
+export function installedVersion() {
+  return readJson(path.join(SKILLS_DIR, '.workflow-run.json'))?.version ?? readJson(path.join(SKILLS_DIR, 'package.json'))?.version ?? 'unknown';
+}
+
+export function userFile(root) {
+  const who = gitOut(root, ['config', 'user.name']) || gitOut(root, ['config', 'user.email']).split('@')[0] || 'unknown';
+  return path.join(feedbackDir(root), `${dirName(who)}.jsonl`);
+}
+
+export function parseAdd(argv) {
+  const rec = {};
+  for (let i = 0; i < argv.length; i++) {
+    const m = /^--([\w-]+)$/.exec(argv[i]);
+    const type = m && FIELDS[m[1]];
+    if (!type) throw new Error(`未知参数：${argv[i]}`);
+    const v = argv[++i];
+    if (v === undefined || v.startsWith('--')) throw new Error(`--${m[1]} 缺少值`);
+    const key = m[1];
+    if (type === 'list') { (rec[key] ??= []).push(v.trim()); continue; }
+    if (type === 'int') { if (!/^\d+$/.test(v)) throw new Error(`--${key} 需要非负整数`); rec[key] = Number(v); continue; }
+    if (Array.isArray(type) && !type.includes(v)) throw new Error(`--${key} 只能是 ${type.join(' / ')}`);
+    if (type instanceof RegExp && !type.test(v)) throw new Error(`--${key} 格式不对（${type.source}）`);
+    rec[key] = v;
+  }
+  if (!rec.skill) throw new Error('缺少 --skill');
+  return rec;
+}
+
+export function add(root, rec, { now = new Date() } = {}) {
+  const file = userFile(root);
+  const line = { ts: now.toISOString(), version: installedVersion(), project: projectName(root), ...rec };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, `${JSON.stringify(line)}\n`);
+  return { ok: true, file: path.relative(root, file).split(path.sep).join('/'), record: line };
+}
+
+export function readAll(root) {
+  const dir = feedbackDir(root);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl')).sort().flatMap((f) => fs.readFileSync(path.join(dir, f), 'utf8')
+    .split('\n').filter((l) => l.trim()).map((l) => { try { return { user: f.replace(/\.jsonl$/, ''), ...JSON.parse(l) }; } catch { return null; } }).filter(Boolean));
+}
+
+// 独立文档仓库模式下各人、各服务都往文档仓库的 feedback/ 追加，同一文件在两个分支上各追加一行时合并会在末尾冲突：
+// 在文档仓库自己的 .gitattributes 里用 git 内置的 union 合并保留两边的行。随代码提交时不加（不改代码仓库的 .gitattributes），
+// 并去掉 0.22.0 加在代码仓库里的这一行（文件里只剩这一行时删掉文件）。
+// 返回 { action: 'added' | 'removed', file, rule }，没有改动时 null
+const LEGACY_RULE = `${HOME}/${FEEDBACK_DIR}/*.jsonl merge=union`;
+export function ensureUnionMerge(root) {
+  const lines = (f) => (fs.existsSync(f) ? fs.readFileSync(f, 'utf8').split(/\r?\n/) : []);
+  const relOf = (f) => path.relative(root, f).split(path.sep).join('/');
+  const codeAttr = path.join(root, '.gitattributes');
+  if (!homeIsRepo(root)) {
+    const cur = lines(codeAttr);
+    if (!cur.some((l) => l.trim() === LEGACY_RULE)) return null;
+    const keep = cur.filter((l) => l.trim() !== LEGACY_RULE);
+    if (keep.every((l) => !l.trim())) fs.rmSync(codeAttr);
+    else fs.writeFileSync(codeAttr, keep.join('\n'));
+    return { action: 'removed', file: relOf(codeAttr), rule: LEGACY_RULE };
+  }
+  const file = path.join(homeDir(root), '.gitattributes');
+  const rule = `${FEEDBACK_DIR}/*.jsonl merge=union`;
+  const text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  if (lines(file).some((l) => l.trim() === rule)) return null;
+  fs.writeFileSync(file, `${text}${text && !text.endsWith('\n') ? '\n' : ''}${rule}\n`);
+  return { action: 'added', file: relOf(file), rule };
+}
+
+// 新版本装好后：删掉本项目旧版本的记录，其他项目（独立文档仓库里各服务共用 feedback/）的不动。返回删掉的条数
+export function rotate(root, version, project = projectName(root)) {
+  const dir = feedbackDir(root);
+  if (!fs.existsSync(dir)) return 0;
+  let removed = 0;
+  for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.jsonl'))) {
+    const p = path.join(dir, f);
+    const lines = fs.readFileSync(p, 'utf8').split('\n').filter((l) => l.trim());
+    const keep = lines.filter((l) => { let r; try { r = JSON.parse(l); } catch { return true; } return r.version === version || (r.project && r.project !== project); });
+    if (keep.length === lines.length) continue;
+    removed += lines.length - keep.length;
+    fs.writeFileSync(p, keep.length ? `${keep.join('\n')}\n` : '');
+  }
+  return removed;
+}
+
+// 「F6: 缺中间件」→ F6；没有章节前缀的归到「其他」
+const sectionOf = (s) => /^([A-Z]?\d+|Step ?\d+|第\s*\d+\s*步)\s*[:：]/i.exec(s)?.[1].replace(/\s+/g, '') ?? '其他';
+const groupBy = (xs, f) => xs.reduce((m, x) => { (m[f(x)] ??= []).push(x); return m; }, {});
+const countBy = (xs, f) => xs.reduce((m, x) => { const k = f(x); m[k] = (m[k] ?? 0) + 1; return m; }, {});
+const sorted = (m) => Object.entries(m).sort((a, b) => b[1] - a[1]);
+const avg = (xs) => (xs.length ? Math.round((xs.reduce((a, b) => a + b, 0) / xs.length) * 10) / 10 : null);
+
+export function summarize(records) {
+  const bySkill = {};
+  for (const [skill, rs] of Object.entries(groupBy(records, (r) => r.skill))) {
+    const notes = (k) => rs.flatMap((r) => r[k] ?? []);
+    const acc = rs.filter((r) => r.acceptance).map((r) => r.acceptance.split('/').map(Number));
+    const findings = rs.filter((r) => r.findings).map((r) => r.findings.split('/').map(Number));
+    bySkill[skill] = {
+      runs: rs.length,
+      mode: countBy(rs.filter((r) => r.mode), (r) => r.mode),
+      size: countBy(rs.filter((r) => r.size), (r) => r.size),
+      depth: countBy(rs.filter((r) => r.depth), (r) => r.depth),
+      fast_path: rs.filter((r) => r.fast === 'yes').length,
+      avg_rounds: avg(rs.filter((r) => r.rounds !== undefined).map((r) => r.rounds)),
+      runs_with_corrections: rs.filter((r) => r.corrections > 0).length,
+      acceptance: acc.length ? { verified: acc.reduce((a, [v]) => a + v, 0), total: acc.reduce((a, [, t]) => a + t, 0) } : null,
+      runs_with_baseline_failures: rs.filter((r) => r['baseline-failures'] > 0).length,
+      findings: findings.length ? ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'].reduce((o, k, i) => ({ ...o, [k]: findings.reduce((a, f) => a + f[i], 0) }), {}) : null,
+      skipped: groupBy(notes('skipped'), sectionOf),
+      unclear: groupBy(notes('unclear'), sectionOf),
+      feedback: notes('feedback'),
+    };
+  }
+  return {
+    records: records.length,
+    from: records.map((r) => r.ts).sort()[0] ?? null,
+    to: records.map((r) => r.ts).sort().at(-1) ?? null,
+    versions: countBy(records, (r) => r.version), projects: countBy(records, (r) => r.project),
+    users: Object.keys(countBy(records, (r) => r.user)).length, models: countBy(records, (r) => r.model ?? '未写'),
+    skills: bySkill,
+  };
+}
+
+function toMarkdown(s) {
+  const kv = (m) => sorted(m).map(([k, v]) => `${k} ${v}`).join('，') || '无';
+  const L = ['# 运行反馈汇总', '', `- 记录：${s.records} 条（${s.from?.slice(0, 10) ?? '—'} ～ ${s.to?.slice(0, 10) ?? '—'}），${s.users} 人`, `- 版本：${kv(s.versions)}`, `- 项目：${kv(s.projects)}`, `- 模型：${kv(s.models)}`, ''];
+  for (const [skill, k] of Object.entries(s.skills)) {
+    L.push(`## ${skill}（${k.runs} 次）`, '');
+    if (Object.keys(k.mode).length) L.push(`- 模式：${kv(k.mode)}`);
+    if (Object.keys(k.size).length) L.push(`- 规模：${kv(k.size)}；快速通道 ${k.fast_path} 次`);
+    if (Object.keys(k.depth).length) L.push(`- 深度：${kv(k.depth)}`);
+    if (k.avg_rounds !== null) L.push(`- 平均提问轮数：${k.avg_rounds}；用户纠正过需求理解：${k.runs_with_corrections} 次`);
+    if (k.acceptance) L.push(`- 验收项：已验证 ${k.acceptance.verified} / ${k.acceptance.total}`);
+    if (k.runs_with_baseline_failures) L.push(`- 开工前已有失败：${k.runs_with_baseline_failures} 次`);
+    if (k.findings) L.push(`- 审查发现：${Object.entries(k.findings).map(([a, b]) => `${a} ${b}`).join('，')}`);
+    for (const [title, groups] of [['跳过的步骤', k.skipped], ['不清楚 / 矛盾 / 做不到的规则', k.unclear]]) {
+      const g = sorted(Object.fromEntries(Object.entries(groups).map(([sec, xs]) => [sec, xs.length])));
+      if (!g.length) continue;
+      L.push('', `### ${title}`, '');
+      for (const [sec, n] of g) { L.push(`- **${sec}**（${n}）`); for (const x of groups[sec]) L.push(`  - ${x}`); }
+    }
+    if (k.feedback.length) { L.push('', '### 用户反馈', ''); for (const x of k.feedback) L.push(`- ${x}`); }
+    L.push('');
+  }
+  if (!s.records) L.push('还没有记录。');
+  return L.join('\n');
+}
+
+function main(argv) {
+  let root = process.cwd();
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) { if (argv[i] === '--root') root = path.resolve(argv[++i] ?? '.'); else rest.push(argv[i]); }
+  const [cmd, ...args] = rest;
+  if (cmd === 'add') {
+    try { console.log(JSON.stringify(add(root, parseAdd(args)), null, 2)); return 0; } catch (e) { console.error(e.message); return 1; }
+  }
+  if (cmd === 'summary' && args.every((a) => a === '--json')) {
+    const s = summarize(readAll(root));
+    console.log(args.includes('--json') ? JSON.stringify(s, null, 2) : toMarkdown(s));
+    return 0;
+  }
+  console.error('用法: feedback.mjs [--root <项目根>] add --skill <skill> [--model …] … | summary [--json]');
+  return 1;
+}
+
+export { main };
+const invoked = process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+if (invoked) process.exit(main(process.argv.slice(2)));