@rowansenne/workflow-run 0.22.2 → 0.24.0

package/bin/workflow-run.mjs

@@ -23,7 +23,7 @@ import { findExistingDbConfig, getDb } from './lib/db.mjs';
 import { report, installSkills, linkSkills, updateGitignore, setupHome, recordEnv } from './lib/install.mjs';
 import { setupCodeGraph } from './lib/codegraph.mjs';
 import { uninstall } from './lib/uninstall.mjs';
-import { checkNodeForDocNexus, setupDocNexus, refreshDocNexusLinks, templateRecords, saveTemplateRecords, reportTemplateStatus, installedSkills, docnexusConnected, printTemplateDiffs } from './lib/docnexus.mjs';
+import { checkNodeForDocNexus, setupDocNexus, refreshDocNexusLinks, cleanupLegacyDocNexus, templateRecords, saveTemplateRecords, reportTemplateStatus, installedSkills, docnexusConnected, printTemplateDiffs } from './lib/docnexus.mjs';
 import { upgradeOptions, doctor } from './lib/doctor.mjs';
 import { docsRepo } from './lib/docsrepo.mjs';
 import { findLegacy, legacyMessage } from './lib/legacy.mjs';
@@ -207,6 +207,8 @@ async function main() {
     db = await getDb(o);
   }
 
+  cleanupLegacyDocNexus(o.root);
+
   // 安装目标：单一来源模式下 .agents/skills 只装一次，其余环境建链接；--copy 时各环境各装一份
   const targets = [];
   const links = [];

package/create-release-md-doc/SKILL.md.tpl

@@ -25,7 +25,7 @@ description: "Generate a Markdown release/deployment plan (上线方案) from th
 1. `git rev-parse --is-inside-work-tree` 为 `true`，否则停。
 2. 两个分支都能 `git rev-parse --verify`（或 `origin/<branch>`）；不存在 → 列出候选让用户挑，停。
 3. 读 `workflow/profile.json`：发布平台、Region、配置中心、定时任务注解、是否需要数据评审都取自这里；未配置的写「待填写」，**不要沿用其他项目的取值**。
-4. DocNexus 可用时运行 `node <skills>/workflow/scripts/knowledge.mjs create-release-md-doc --match <模块名 / 业务名词> --query "<一句话：本次上线改了什么>"`（模块名取分支名或 diff 涉及的模块），看以往上线方案沉淀的风险、回滚要点与技术方案沉淀；相关的在文档对应章节引用 `docnexus/library/<path>`（见 `<skills>/workflow/references/docnexus.md`「按分类参考知识库」）。未接入就跳过。
+4. DocNexus 可用时运行 `node <skills>/workflow/scripts/knowledge.mjs create-release-md-doc --match <模块名 / 业务名词> --query "<一句话：本次上线改了什么>"`（模块名取分支名或 diff 涉及的模块），看以往上线方案沉淀的风险、回滚要点与技术方案沉淀；相关的在文档对应章节引用 `workflow-run/docnexus/library/<path>`（见 `<skills>/workflow/references/docnexus.md`「按分类参考知识库」）。未接入就跳过。
 
 ### Step 1 — PRD（仅传入 `--prd` 时）
 
@@ -81,7 +81,7 @@ description: "Generate a Markdown release/deployment plan (上线方案) from th
 
 - 发布到 wiki：`/md-to-wiki <文档路径> [pageId]`（发布过的文档有发布记录，可省略 pageId）。
 - 模板回写：用户对生成的文档做了结构性调整（新增 / 删除 / 重排章节、改表格列）时，问要不要同步回模板：未接入 DocNexus 时按「修改模板」用 `template.mjs draft / check / save release` 改（用户确认后保存）；已接入时按 `<skills>/workflow/references/templates.md`「模板随知识库更新」提议同步回模板。
-- 沉淀到 DocNexus（DocNexus 可用时，判定见 `<skills>/workflow/SKILL.md`「增强能力探测」）：列出值得长期记住的决策、配置 / 依赖变化、风险与坑，**询问用户**；同意后按 DocNexus 入口 skill `docnexus` 的 capture 流程写入，分类用 `node <skills>/workflow/scripts/resolve.mjs category create-release-md-doc` 的结果作为调用方显式分类封存（见 `<skills>/workflow/references/docnexus.md`「写入 DocNexus 的分类」），并回报 `docnexus/library/<path>`。只沉淀确认过的事实，不沉淀「待补充」「待人工确认」的推断。未检测到 DocNexus 就跳过，不提示安装。
+- 沉淀到 DocNexus（DocNexus 可用时，判定见 `<skills>/workflow/SKILL.md`「增强能力探测」）：列出值得长期记住的决策、配置 / 依赖变化、风险与坑，**询问用户**；同意后按 DocNexus 入口 skill `docnexus` 的 capture 流程写入，分类用 `node <skills>/workflow/scripts/resolve.mjs category create-release-md-doc` 的结果作为调用方显式分类封存（见 `<skills>/workflow/references/docnexus.md`「写入 DocNexus 的分类」），并回报 `workflow-run/docnexus/library/<path>`。只沉淀确认过的事实，不沉淀「待补充」「待人工确认」的推断。未检测到 DocNexus 就跳过，不提示安装。
 
 ## Red Flags — STOP
 

package/create-tech-md-doc/SKILL.md.tpl

@@ -24,7 +24,7 @@ description: "Generate a Markdown technical design doc (技术方案) from the d
 1. `git rev-parse --is-inside-work-tree` 为 `true`，否则停。
 2. 两个分支都能 `git rev-parse --verify`（或 `origin/<branch>`）；不存在 → 列出 `git branch -a -i --list "*<关键词>*"` 的候选让用户挑，停。
 3. 读 `workflow/profile.json`：发布平台、Region、配置中心、定时任务注解、是否需要数据评审都取自这里；未配置的写「待填写」，**不要沿用其他项目的取值**。
-4. DocNexus 可用时运行 `node <skills>/workflow/scripts/knowledge.mjs create-tech-md-doc --match <模块名 / 业务名词> --query "<一句话：本次改动做了什么>"`（模块名取分支名或 diff 涉及的模块），看以往技术方案沉淀的决策与约定、相关开发沉淀；相关的在文档对应章节引用 `docnexus/library/<path>`（见 `<skills>/workflow/references/docnexus.md`「按分类参考知识库」）。未接入就跳过。
+4. DocNexus 可用时运行 `node <skills>/workflow/scripts/knowledge.mjs create-tech-md-doc --match <模块名 / 业务名词> --query "<一句话：本次改动做了什么>"`（模块名取分支名或 diff 涉及的模块），看以往技术方案沉淀的决策与约定、相关开发沉淀；相关的在文档对应章节引用 `workflow-run/docnexus/library/<path>`（见 `<skills>/workflow/references/docnexus.md`「按分类参考知识库」）。未接入就跳过。
 
 ### Step 1 — PRD（仅传入 `--prd` 时）
 
@@ -80,7 +80,7 @@ description: "Generate a Markdown technical design doc (技术方案) from the d
 - 发布到 wiki：`/md-to-wiki <文档路径> [pageId]`（发布过的文档有发布记录，可省略 pageId）。
 - 模板回写：用户对生成的文档做了结构性调整（新增 / 删除 / 重排章节、改表格列）时，问要不要同步回模板：未接入 DocNexus 时按「修改模板」用 `template.mjs draft / check / save tech` 改（用户确认后保存）；已接入时按 `<skills>/workflow/references/templates.md`「模板随知识库更新」提议同步回模板。
 - 要上线：`/create-release-md-doc <dev> <main> --tech <文档路径>` 复用本文档的事实。
-- 沉淀到 DocNexus（DocNexus 可用时，判定见 `<skills>/workflow/SKILL.md`「增强能力探测」）：列出值得长期记住的决策、约定、配置 / 依赖变化、风险，**询问用户**；同意后按 DocNexus 入口 skill `docnexus` 的 capture 流程写入，分类用 `node <skills>/workflow/scripts/resolve.mjs category create-tech-md-doc` 的结果作为调用方显式分类封存（见 `<skills>/workflow/references/docnexus.md`「写入 DocNexus 的分类」），并回报 `docnexus/library/<path>`。只沉淀确认过的事实，不沉淀「待补充」「待人工确认」的推断。未检测到 DocNexus 就跳过，不提示安装。
+- 沉淀到 DocNexus（DocNexus 可用时，判定见 `<skills>/workflow/SKILL.md`「增强能力探测」）：列出值得长期记住的决策、约定、配置 / 依赖变化、风险，**询问用户**；同意后按 DocNexus 入口 skill `docnexus` 的 capture 流程写入，分类用 `node <skills>/workflow/scripts/resolve.mjs category create-tech-md-doc` 的结果作为调用方显式分类封存（见 `<skills>/workflow/references/docnexus.md`「写入 DocNexus 的分类」），并回报 `workflow-run/docnexus/library/<path>`。只沉淀确认过的事实，不沉淀「待补充」「待人工确认」的推断。未检测到 DocNexus 就跳过，不提示安装。
 
 ## Red Flags — STOP
 

package/dev/SKILL.md.tpl

@@ -42,7 +42,7 @@ description: "Implement a feature or fix a bug in this project end to end: under
 ### F1 — 理解需求
 
 - 需求来源是 PRD pageId/URL → 按 `references/prd-fetch.md` 拉取并提炼；wiki 不可用 → 请用户贴出关键内容。
-- DocNexus 可用 → 先运行 `node <skills>/workflow/scripts/knowledge.mjs dev --match <模块名 / 业务名词> --query "<一句话需求>"`，看以往开发沉淀、技术方案和反复出现的审查问题里有没有相关的（`--query` 在这些分类内按正文 recall；输出 `recall_by_category: false` 时改按 `docnexus-recall` 做不带分类的 recall）。引用 `docnexus/library/<path>`（见 `<skills>/workflow/references/docnexus.md`「按分类参考知识库」）。
+- DocNexus 可用 → 先运行 `node <skills>/workflow/scripts/knowledge.mjs dev --match <模块名 / 业务名词> --query "<一句话需求>"`，看以往开发沉淀、技术方案和反复出现的审查问题里有没有相关的（`--query` 在这些分类内按正文 recall）。引用 `workflow-run/docnexus/library/<path>`（见 `<skills>/workflow/references/docnexus.md`「按分类参考知识库」）。
 - 先在心里列出初版 **需求要点 + 验收标准**（可验证的行为，而不是实现手段）和还没定的决定，带进 F2 查事实、F3 澄清。
 
 ### F2 — 现状调研
@@ -57,7 +57,7 @@ description: "Implement a feature or fix a bug in this project end to end: under
 
 | 情况 | 做法 |
 |---|---|
-| S 规模且 F2 后没有未定的决定 | 跳过提问，在开工前用一两句话写明本次的理解和假设 |
+| S 规模且 F2 后没有未定的决定 | 跳过需求澄清提问，写明本次的理解和假设；仍须按 F4 确认规模 |
 | 只有一两个小决定 | 问一轮即可 |
 | M / L 规模，或用户说「拷问一下 / grill me / 先把需求问清楚」 | 按轮问到前沿为空，输出需求要点、验收标准、不在本次范围、已确认的决定，**等用户确认理解一致**再进 F4 |
 
@@ -67,15 +67,17 @@ description: "Implement a feature or fix a bug in this project end to end: under
 
 | 规模 | 判定 | 做法 |
 |---|---|---|
-| **S** | ≤3 个文件，无接口签名 / 表结构 / 配置项变更，不涉及权限 / 资金 | 在对话中列改动步骤，直接开始 |
+| **S** | ≤3 个文件，无接口签名 / 表结构 / 配置项变更，不涉及权限 / 资金 | 用户确认规模后，在对话中列改动步骤并开始 |
 | **M** | 新增或修改接口、配置项、少量表字段 | 在对话中给出简要方案（方案模板的精简版），**等用户确认后再写代码** |
 | **L** | 新模块、跨服务、表结构较大变更、数据迁移 | 按方案模板写方案文档落盘（见 Artifact Location），用户确认后再写代码；完成后建议用 `create-tech-md-doc` 生成正式技术方案 |
 
 规模拿不准时按大一级处理。涉及权限（鉴权、角色、数据可见范围）或资金（金额计算、扣款、退款、对账）的改动，文件再少也至少按 M：需求理解（F3）和方案都要用户确认。
 
-**M / L 规模先定需求名**：规模定下来、确定要落盘时，按 Artifact Location 运行 `requirement.mjs which`，当前分支没绑定需求就在这一轮问用户这个需求叫什么（可以和澄清问题一起问），之后的方案、交付、审查、技术方案、上线方案都归到这个需求下。
+**规模确认（S / M / L 都必做，含快速通道）**：判定后向用户说明推荐规模、依据（预计改动文件 / 模块、接口 / 数据 / 配置变化及风险），以及对应流程（是否走快速通道、方案与交付说明是否落盘），明确询问是否按该规模处理。**等用户明确确认后，再按该规模推进后续流程、绑定需求或写代码**；只告知判定结果或默认选中推荐项不算确认。可以与 F3 的理解确认或简要方案确认在同一轮提出，但必须明确列出规模并收到确认；本轮对话中已明确确认的同一规模不重复询问。用户调整范围或实现中发现规模变化时，说明变化依据，确认新规模后再继续。规模确认属于流程选择，不算 F3 的业务决定，不影响 S 规模快速通道资格。
 
-**S 规模快速通道**：S 规模，且改动**不涉及**配置项、SQL / DDL、对外接口（HTTP 接口签名、MQ 消息体、对外 DTO）、表结构、权限、资金，也没有 F3 中确认过的决定 → 走快速通道：F5～F7 照常（编译、测试、自审都不省），F8 只在对话里交付，不落盘交付说明、不问 DocNexus 沉淀（见 F8「快速通道交付」）。开工时用一句话告诉用户「按快速通道处理，不落盘交付说明」。实现中一旦碰到上面任何一项、改动超过 3 个文件，或用户要求落盘 → 退出快速通道，按完整 F8 交付。小改动也要走完整流程是用户绕开 dev 的主要原因，所以只在上面这些会影响上线和团队的情况下才落盘。
+**M / L 规模先定需求名**：用户确认规模、确定要落盘时，按 Artifact Location 运行 `requirement.mjs which`，当前分支没绑定需求就在这一轮问用户这个需求叫什么（可以和规模确认、澄清问题一起问），之后的方案、交付、审查、技术方案、上线方案都归到这个需求下。
+
+**S 规模快速通道**：用户已确认 S 规模，且改动**不涉及**配置项、SQL / DDL、对外接口（HTTP 接口签名、MQ 消息体、对外 DTO）、表结构、权限、资金，也没有 F3 中确认过的业务决定 → 走快速通道：F5～F7 照常（编译、测试、自审都不省），F8 只在对话里交付，不落盘交付说明、不问 DocNexus 沉淀（见 F8「快速通道交付」）。规模确认时说明「按快速通道处理，不落盘交付说明」。实现中一旦碰到上面任何一项、改动超过 3 个文件，或用户要求落盘 → 退出快速通道，按完整 F8 交付；重新评估后规模变化的，先确认新规模再继续。小改动也要走完整流程是用户绕开 dev 的主要原因，所以只在上面这些会影响上线和团队的情况下才落盘。
 
 方案模板：在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template dev plan-template.md`，读输出的 `path`；退出码 2（已接入 DocNexus 但缺模板）时停下并按 `hint` 处理。L 规模的方案文档落盘后运行 `node <skills>/workflow/scripts/lint-doc.mjs <方案路径> --skill dev` 自检，再请用户确认。
 
@@ -97,7 +99,7 @@ description: "Implement a feature or fix a bug in this project end to end: under
 
 ### F7 — 自审
 
-- 按 `project-review` skill 审本次改动：分支已有提交时用 `git diff <main_branch>...HEAD`，再加上 `git diff HEAD` 的未提交部分，以及 `git status --short` 里本次新建、还没跟踪的文件（`git diff` 看不到，逐个读）。Step 0 确认不属于本需求的文件不计入本次结论（见 Step 0「工作区状态」）。
+- 按 `project-review` skill 审本次改动，范围用 `node <skills>/workflow/scripts/review-scope.mjs --base <main_branch>`：分支已有的提交、未提交的改动和未跟踪的新文件一起列出。Step 0 确认不属于本需求的文件用 `--exclude <文件,文件>` 排除，它们不计入本次结论（见 Step 0「工作区状态」）；之后 project-review 的 `rules`、`locate.mjs` 都带同样的参数。
 - 只走 project-review 的第 1～6 步（范围与深度、建立理解、对比、过清单、影响面、复核）；**跳过第 7 步落盘报告、第 8 步 DocNexus 询问和第 9 步运行反馈**——结论由 dev 在 F8 统一交付，沉淀只在 F8 问一次，反馈也只由 dev 记一行。用户要求单独的审查报告时，再按 project-review 的第 7 步和产物规范落盘。
 - 交给 F8 的是：问题表（文件:行号、严重级别、触发条件、复核结果）、影响面、未覆盖与待确认。
 - CRITICAL / HIGH 必须修掉后重新跑 F6；MEDIUM / LOW 修掉或写进交付说明。
@@ -117,7 +119,7 @@ description: "Implement a feature or fix a bug in this project end to end: under
    - PR / MR：用户要提 PR / MR 时，运行 `node <skills>/workflow/scripts/pr-desc.mjs`（缺省当前分支、基线 `profile.main_branch`），它把本分支的交付说明、审查报告、技术方案、上线方案汇总成描述（没有交付说明时退回用提交记录和改动文件），把输出给用户；用 `gh pr create` / `glab mr create` 创建要用户明确同意。
    - 文档：运行 `node <skills>/workflow/scripts/artifacts.mjs` 看本分支已有哪些产物（开发方案、交付说明、审查报告、技术方案、上线方案及 wiki 发布记录），按输出的 `next` 建议下一步：M / L 规模缺技术方案时建议 `create-tech-md-doc`，要上线时建议 `create-release-md-doc`（会自动引用本分支的技术方案和交付说明）。
    - **沉淀到 DocNexus**（`resolve.mjs status` 的 `docnexus.ok` 为 true 时**每次都问**）：明确问用户「要不要启动 DocNexus 流程，把本次交付沉淀到 DocNexus？」，并从交付说明里列出建议沉淀的内容（已确认的决定、新约定、踩到的坑、缺陷根因、配置 / 表结构变化）；没有特别值得记的也照问，并说明这一点。
-     - 用户同意 → 以交付说明为来源，按 DocNexus 入口 skill `docnexus` 的 capture 流程写入；正文只写知识，不写分支、路径；有 facts 时按 `<skills>/workflow/references/docnexus.md`「沉淀的来源」的格式写 provenance；分类用 `node <skills>/workflow/scripts/resolve.mjs category dev` 的结果作为调用方显式分类封存（见 `<skills>/workflow/references/docnexus.md`「写入 DocNexus 的分类」）。只沉淀确认过的事实，不沉淀「未验证」「待确认」的内容；知识库已有同主题的沉淀时更新那一篇（带 `--base-version`），不重复新建。写入成功后把交付说明的「DocNexus」元信息行改成 `docnexus/library/<path>`，并回报给用户。
+     - 用户同意 → 以交付说明为来源，按 DocNexus 入口 skill `docnexus` 的 capture 流程写入；正文只写知识，不写分支、路径；有 facts 时按 `<skills>/workflow/references/docnexus.md`「沉淀的来源」的格式写 provenance；分类用 `node <skills>/workflow/scripts/resolve.mjs category dev` 的结果作为调用方显式分类封存（见 `<skills>/workflow/references/docnexus.md`「写入 DocNexus 的分类」）。只沉淀确认过的事实，不沉淀「未验证」「待确认」的内容；知识库已有同主题的沉淀时更新那一篇（带 `--base-version`），不重复新建。写入成功后把交付说明的「DocNexus」元信息行改成 `workflow-run/docnexus/library/<path>`，并回报给用户。
      - 用户不同意 → 元信息行保持「未沉淀」，不再追问。
      - 未接入 DocNexus → 元信息行写「未接入」，不提问、不提示安装。
 
@@ -141,6 +143,7 @@ description: "Implement a feature or fix a bug in this project end to end: under
 
 ### B4 — 修复与验证
 
+- 修复前按 F4 的标准判定规模，并完成同样的规模确认（S / M / L 都适用，说明是否走快速通道及落盘要求）；用户明确确认后再改代码。修复中规模变化时先确认新规模再继续。
 - 做能消除根因的**最小改动**；B2 的测试由红变绿，相关已有测试保持通过（运行方式同 F6）。
 - 如果历史脏数据需要修正，写成 SQL 脚本交给用户，不直接执行。
 

package/dev/references/delivery-template.md

@@ -3,7 +3,7 @@
 > 类型：{{功能开发 / 缺陷修复}} ｜ 规模：{{S / M / L}} ｜ 日期：{{YYYY-MM-DD}}
 > 对比分支：`{{当前分支}}` ←→ `{{主分支}}`
 > 参考产物：{{开发方案路径，没有写「无」}}
-> DocNexus：{{沉淀后写 docnexus/library/<path>；未沉淀写「未沉淀」，未接入写「未接入」}}
+> DocNexus：{{沉淀后写 workflow-run/docnexus/library/<path>；未沉淀写「未沉淀」，未接入写「未接入」}}
 
 <!-- F8 / B5 交付时按此落盘到 requirement.mjs path delivery 给出的路径（workflow-run/docs/requirements/<需求名>/<项目名>/delivery.md）。小改动每节写一两行即可，不适用的节写「无」；验证结果必须如实 -->
 

package/dev/references/plan-template.md

@@ -1,7 +1,7 @@
 # 开发方案 — {{需求名}}
 
 > 规模：{{M / L}} ｜ 分支：{{dev分支}} ｜ 日期：{{YYYY-MM-DD}}
-> 需求来源：{{对话 / PRD 链接}} ｜ 参考记忆：{{docnexus/library/... 或「无」}}
+> 需求来源：{{对话 / PRD 链接}} ｜ 参考记忆：{{workflow-run/docnexus/library/... 或「无」}}
 
 <!-- M 规模在对话中给出时，只需要第 1、3、4、6 节，每节几行即可 -->
 

package/package.json

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

package/project-review/SKILL.md.tpl

@@ -7,32 +7,32 @@ description: "Review source code (any language; Java/Spring, Go, TypeScript, Pyt
 
 ## Workflow
 
-1. **确定审查范围与深度**：范围是单文件 / 单方法、分支对比（如 `branch` vs `main`），还是未提交改动（`git diff HEAD`，见 `references/diff-strategy.md`「未提交改动」）。深度按用户的说法定，没说就用「标准」，写进报告「审查方式」：
+1. **确定审查范围与深度**：范围是单文件 / 单方法、分支对比（如 `branch` vs `main`），还是未提交改动（见 `references/diff-strategy.md`「未提交改动」）。分支对比和未提交改动都先运行 `node <skills>/workflow/scripts/review-scope.mjs --diff <基线>...<dev>`（未提交改动用 `--base <基线>`，含未跟踪的新文件；dev 自审时加 dev 传来的 `--exclude`），**审哪些文件以它的 `review` 为准**：`skipped` 是按规则跳过的（删除、二进制、敏感文件、依赖目录、生成文件、文档、本工具的产物，各带原因），不要自己再增减；确实要审被跳过的，在画像 `review.include` 里加（见 `<skills>/workflow/references/profile.md`）。深度按用户的说法定，没说就用「标准」，写进报告「审查方式」：
    - **快审**（「快速看一下」「扫一眼」）：只查正确性、空值、安全、事务与幂等，不查性能、测试、风格；「优化建议（LOW）」写「无」。CRITICAL / HIGH 照样复核。
    - **标准**（默认）：检查清单全部维度，**风格类（清单「一致性 / 风格」一节）不查**；「优化建议（LOW）」只写有实际收益的（性能、可维护性上的具体问题），没有就写「无」。
    - **深审**（「仔细审」「全面审」，或资金 / 权限 / 对外接口的大改动合并前）：全部维度，包括风格；MEDIUM 也复核。
 2. **建立理解**：先读实体、接口、DTO、调用链，理清数据流再下结论；不要凭文件名猜内容。
-   - **可选：查项目约定（DocNexus）**：DocNexus 可用时（`resolve.mjs status` 的 `docnexus.ok`），先运行 `node <skills>/workflow/scripts/knowledge.mjs project-review --match <模块名 / 业务名词> --query "<一句话：改动涉及的模块与业务>"`，看以往审查沉淀的反复问题和开发约定（`--query` 在这些分类内按正文 recall；输出 `recall_by_category: false` 时改按 `docnexus-recall` 做不带分类的 recall），找相关的编码约定、历史决策与已知坑，作为审查依据并在报告中引用 `docnexus/library/<path>`。未检测到或查询失败就跳过，并在「未覆盖与待确认」中注明；审查过程中**不写入** DocNexus（写入见第 8 步）。
+   - **可选：查项目约定（DocNexus）**：DocNexus 可用时（`resolve.mjs status` 的 `docnexus.ok`），先运行 `node <skills>/workflow/scripts/knowledge.mjs project-review --match <模块名 / 业务名词> --query "<一句话：改动涉及的模块与业务>"`，看以往审查沉淀的反复问题和开发约定（`--query` 在这些分类内按正文 recall），找相关的编码约定、历史决策与已知坑，作为审查依据并在报告中引用 `workflow-run/docnexus/library/<path>`。未检测到或查询失败就跳过，并在「未覆盖与待确认」中注明；审查过程中**不写入** DocNexus（写入见第 8 步）。
    - **同分支已有产物**：运行 `node <skills>/workflow/scripts/artifacts.mjs --branch <dev分支>`（单文件 / 未提交改动用当前分支，省略 `--branch`），看输出的 `latest`：
      - `latest.plan` 或 `latest.tech` 存在 → 读其中的验收标准、改动设计、接口 / 数据 / 配置变更，第 3 步审 diff 时做**需求对照**：方案里有、diff 里找不到的 → 漏实现（属于验收标准的按 HIGH，其余 MEDIUM）；diff 里有、方案里没提的接口 / 表结构 / 配置 / 依赖变更 → 列出请作者确认（不一定是问题）。只对照能在 diff 里核对的项，不推测业务语义。
      - `latest.delivery` 存在（dev 的交付说明）→ 其中「已确认的决定」并入需求对照的依据；「配置清单」「SQL 脚本」和 diff 对照，diff 里有而交付说明漏列的配置 key / DDL 记为 MEDIUM（上线时会被漏掉）。
      - `latest.review` 存在 → 这是**复审**：读上次报告的问题表，并用 `git log --oneline --since=<上次报告日期> <dev分支>` 看之后改了什么。本次报告对上次的每条问题标「已修复 / 仍存在 / 不再适用」（「已修复」要看到对应改动），本次新发现的标「新增」。
    - **涉及数据库**：diff 里有 SQL、Mapper、实体或 DDL 时，按 `<skills>/workflow/references/tables.md` 运行 `node <skills>/workflow/scripts/tables.mjs --diff <基线>...<dev>`（未提交改动用 `--base <基线>`）找出涉及的表；数据库已配置（`resolve.mjs status` 的 `database.ok`）时用 `query.mjs --schema --tables <表> --indexes` 只读拉取实际字段、索引与估算行数，作为第 4、6 步判断索引支撑、字段存在与类型、DDL 锁表与滚动发布兼容的依据。查不了库时注明「未与实际库核对」写进「未覆盖与待确认」，这类发现不升到 HIGH 以上，除非 diff 本身就能证明。
-3. **分支对比**：基线默认取 `workflow/profile.json` 的 `main_branch`（未配置则 `main`）。按 `references/diff-strategy.md` 先量规模：小改动全量精读；改动多时按风险分级（P0 资金 / 事务 / 权限 / SQL / 对外接口 / MQ / 配置优先）分批精读，审不到的写进报告。**深审且改动属于「更大」、环境又能派子 agent 时，先问用户要不要分角度并行查找**（`references/diff-strategy.md`「分角度并行查找」），用户同意才走，第 4 步改由各子 agent 按角度过清单。只审本次改动引入的问题，同时检查改动是否破坏既有调用方。
-4. **逐项过检查清单**（在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template project-review checklist.md`，读输出的 `path`；退出码 2 时停下并按 `hint` 处理）：对每个发现给出 文件+行号、问题描述、严重级别、修改建议。
+3. **分支对比**：基线默认取 `workflow/profile.json` 的 `main_branch`（未配置则 `main`）。规模和分批用第 1 步 `review-scope.mjs` 的输出：`summary.size` 是「全量精读」就一次读完；「分批精读」按 `batches` 的顺序（P0 → P1 → P2）读，P0 不能跳过；「过大」时停下请用户缩小范围。审不到的文件写进报告（读法见 `references/diff-strategy.md`）。**深审且改动属于「更大」、环境又能派子 agent 时，先问用户要不要分角度并行查找**（`references/diff-strategy.md`「分角度并行查找」），用户同意才走，第 4 步改由各子 agent 按角度过清单。只审本次改动引入的问题，同时检查改动是否破坏既有调用方。
+4. **逐项过检查清单**：每个文件只看 `review-scope.mjs` 给它的 `sections`（清单小节号，按文件类型和改动内容定），一批文件用 `node <skills>/workflow/scripts/review-scope.mjs rules <文件…>`（带上和第 1 步一样的 `--diff` / `--base`）打印这些小节的原文和画像 `review.rules` 里匹配到的项目规则，按它检查；整个改动再过一次 `overall_sections`（9 影响面、13 测试）。深审读整份清单（`node <skills>/workflow/scripts/resolve.mjs template project-review checklist.md` 取 `path`；退出码 2 时停下并按 `hint` 处理），包括风格。对每个发现给出 文件、**问题所在的原代码片段**（从文件里照原样复制，第 6 步靠它定位行号）、问题描述、严重级别、修改建议。
 5. **影响面分析**：改动是否影响其他调用方/模块。先运行 `node <skills>/code-graph/scripts/cg.mjs impact --diff <基线>...<dev>`（code-graph skill；未提交改动用 `--base <基线>`）：列出受影响的接口、MQ 消费者、定时任务、测试、表和配置 key，报告「影响面」按入口归纳并带文件:行号；退出码 2（没有索引等）时用 grep 或精读调用链确认。Spring 注入、AOP、MyBatis XML、MQ topic、配置 key 图谱看不到，照常 grep（见 `<skills>/workflow/references/codegraph.md`）。查不到调用方的符号不能当作安全，要明说"未确认"。
 6. **复核**：交付前逐条复核 CRITICAL / HIGH（深审时 MEDIUM 也复核；其余 MEDIUM 至少做下面第 1 条）。审查结论会被用来决定能不能合并，一条误报会让人白改代码，也会让后面的真问题不被当回事。找出问题的人自己复核容易顺着原来的思路认同自己，所以**能交给独立的一方就交出去**：
    - **独立复核（首选）**：当前环境能派子 agent / 子任务时（例如 Claude Code 的 Agent 工具、Codex / Qwen Code 的子 agent），每条发现派一个，互不相关的可以同时派。只给它：一句话结论、位置（文件:行号）、你写的触发条件、对比分支（或「未提交改动」）。**不给你的推理过程**，也不告诉它你认为成立。要它自己读代码，按下面 1～4 条检查，回答「成立 / 可能成立 / 不成立」并引用代码作为依据。
    - **自行复核**：环境派不了子 agent 时自己做，先找它**不成立**的理由，找不到再确认成立。
    检查项（独立复核和自行复核都按这 4 条）：
-   1. 回到被审的代码（分支对比用 `git show <dev>:<文件>`，未提交改动读工作区）确认引用的片段和行号真实存在。
+   1. **定位**：把所有发现（包括 MEDIUM / LOW）写成 `workflow-run/tmp/review/findings.json`（数组，每条 `{ "file", "code"（原代码片段）, "line"（你估的行号，可选）, "title" }`），运行 `node <skills>/workflow/scripts/locate.mjs workflow-run/tmp/review/findings.json`（带上和第 1 步一样的 `--diff` / `--base`）。报告里的行号一律用它输出的 `start_line`～`end_line`，不用自己数的。`anchored: false` 的回去重读代码、照原样改片段再跑一次，还找不到就降为 MEDIUM 并标「⚠ 待确认」；`ambiguous` 时看 `candidates` 确认是哪一处；`in_change: false` 说明问题不在本次改动的行上，按第 4 条判断是不是本次引入的。
    2. 写出**触发条件**：什么输入 / 状态下会出错、错成什么样。写不出来 → 降为 MEDIUM 并标「⚠ 待确认」。
    3. 找有没有别处已经兜住：调用方校验、`@Validated` / 全局异常处理、数据库约束、框架默认行为、配置。涉及索引、字段、唯一约束、表大小的发现，以第 2 步拉到的实际表结构为准（复核列写「已与 <连接名> 核对」）。已兜住 → 删掉或降级，并在说明里写依据。
    4. 确认是本次改动引入的：改动前就存在的问题移到「未覆盖与待确认」，不计入合并结论。
    结果：「成立」在报告「复核」列标「✅」；「可能成立」标「⚠」；「不成立」从问题表里删掉（独立复核否掉的，在「未覆盖与待确认」里记一句「复核排除 N 条」）。复核方式（独立 / 自行）写进报告「审查方式」元信息。
 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>`（多篇用「、」分隔），并回报给用户。
+   - 用户同意 → 按 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」元信息行改成 `workflow-run/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`。只写过程，不写代码和业务名词；报错就提一句，不影响交付。
 
@@ -85,11 +85,11 @@ description: "Review source code (any language; Java/Spring, Go, TypeScript, Pyt
 
 ## Verification
 
-- 每个结论都要能定位到具体文件+行号，并引用真实代码片段。
+- 每个结论都要能定位到具体文件+行号，并引用真实代码片段；行号来自 `locate.mjs`。
 - 读不到的内容如实说明，不要臆测。
 - 涉及跨分支对比时，确保 diff 基于正确的 base 分支（默认 `main`）。
 - CRITICAL / HIGH 都经过第 6 步复核（能派子 agent 时独立复核），写得出触发条件；复核不了的标「⚠ 待确认」，不计入「不建议合并」的结论。
-- 分批审查时，没精读的文件列在「未覆盖与待确认」里，不能让读者以为全部审过。
+- `review-scope.mjs` 的每个文件都有交代：`review` 里的都审过，没精读的逐个列在「未覆盖与待确认」；`skipped` 按原因汇总写进同一节（例如「跳过 12 个：生成文件 8、文档 3、敏感文件 1」，敏感文件单独点名提醒）。
 
 ## 终端命令
 

package/project-review/references/diff-strategy.md

@@ -4,6 +4,8 @@
 
 ## 1. 先量规模
 
+`node <skills>/workflow/scripts/review-scope.mjs --diff <main>...<dev>` 已经按下面的规则算好：跳过哪些文件、`summary.size`（全量精读 / 分批精读 / 过大）、每个文件的风险级别和 `batches`。下面的命令和表是它的规则说明，脚本跑不了时手动照做：
+
 ```bash
 git diff <main>...<dev> --shortstat
 git diff <main>...<dev> --name-only            # 再按 diff-collection-common.md 的排除规则去掉测试、生成代码、文档
@@ -34,7 +36,7 @@ git diff <main>...<dev> --name-only -G '@Transactional|synchronized|Lock\b|@Vers
 
 ## 3. 分批精读
 
-- 每批不超过约 15 个文件或 800 行改动，P0 → P1 → P2。
+- 每批不超过约 15 个文件或 800 行改动，P0 → P1 → P2（`review-scope.mjs` 的 `batches` 就是这样分的，按它的顺序读）。
 - 每个文件读 `git diff <main>...<dev> -- <文件>`，并用 `git show <dev>:<文件>` 读改动所在方法的上下文（调用方、判空、事务注解），不只看 hunk。
 - 每批结束先把发现记下来（文件:行号 + 一句话）再进入下一批，防止后面的批次挤掉前面的结论；批次多时可以边审边把发现写进报告草稿。
 - 时间或上下文不够时，**P2 可以只看 `--stat`**，但要在报告「未覆盖与待确认」里列出只扫过 `--stat` 的文件；P0 不能跳过。
@@ -72,4 +74,4 @@ git diff <main>...<dev> --name-only -G '@Transactional|synchronized|Lock\b|@Vers
 
 ## 5. 未提交改动
 
-审查工作区（dev 自审或用户说「我刚改完，帮我看看」）：`git diff HEAD`（已暂存和未暂存一起）；分支已有提交时再加 `git diff <main>...HEAD`。新建但未跟踪的文件用 `git status --short` 找出来逐个读。
+审查工作区（dev 自审或用户说「我刚改完，帮我看看」）：`review-scope.mjs --base <main>` 把分支已有的提交、已暂存和未暂存的改动、未跟踪的新文件合在一起列出来。读 diff 用 `git diff $(git merge-base <main> HEAD) -- <文件>`（PowerShell 先单独运行 `git merge-base <main> HEAD` 拿到提交号再代入）；未跟踪的新文件没有 diff，直接读整个文件。

package/project-review/references/report.md.tpl

@@ -4,7 +4,7 @@
 > 对比分支：`{{dev分支}}` ←→ `{{基线分支}}`（单文件 / 未提交改动两边都写当前分支）
 > 审查方式：{{快审 / 标准 / 深审}}，{{全量精读 / 分批精读（N 批，按风险排序）/ 分 K 个角度并行查找 / 部分摘要化}}，{{独立复核 / 自行复核}} ｜ 清单来源：{{DocNexus / 项目文件 / skill 默认}}
 > 参考产物：{{本分支的开发方案 / 交付说明 / 技术方案路径；复审时加「上次审查 v<N>（<日期>）」；没有写「无」}}
-> DocNexus：{{沉淀后写 docnexus/library/<path>；未沉淀写「未沉淀」，未接入写「未接入」}}
+> DocNexus：{{沉淀后写 workflow-run/docnexus/library/<path>；未沉淀写「未沉淀」，未接入写「未接入」}}
 
 ## 结论摘要 *
 
@@ -57,4 +57,4 @@
 
 ## 未覆盖与待确认 *
 
-{{分批审查时只扫过 --stat 的文件、复核后降级或待确认的发现、复核排除的条数、改动前就存在的问题、按审查深度没查的维度；都没有写「无」}}
+{{review-scope.mjs 跳过的文件按原因汇总（敏感文件单独点名）、分批审查时没精读的文件、行号定位不到的发现、复核后降级或待确认的发现、复核排除的条数、改动前就存在的问题、按审查深度没查的维度；都没有写「无」}}

package/workflow/SKILL.md.tpl

@@ -76,7 +76,7 @@ dev（需求 → 方案 → 实现 → 测试 → 自审）
 | 能力 | 判定为可用 | 用途 |
 |---|---|---|
 | wiki | `md-to-wiki/wiki-config.json` 中 `enabled=true` 且 `wiki.base_url` 非空；或环境存在 wiki MCP 工具 | 读 PRD（各 skill 按 `references/prd-fetch.md`，REST 通道统一调 `md-to-wiki/scripts/upload.mjs get`）、发布文档 |
-| DocNexus | 有 `workflow-run/docnexus/project.json`，且 CLI 可执行：`workflow-run/docnexus/node_modules/.bin/docnexus`（`resolve.mjs status` 的 `docnexus.bin`）；命令用 `node <skills>/workflow/scripts/docnexus.mjs <参数>` 运行（`docnexus.run`），见 `references/docnexus.md`「DocNexus 在 workflow-run/ 里」 | 查约定与历史决策、沉淀知识、提供文档模板 |
+| DocNexus | `.docnexus/project.json` 为 format 7 且 `output_dir=workflow-run`，CLI 可执行：`.docnexus/node_modules/.bin/docnexus`（`resolve.mjs status` 的 `docnexus.bin`）；命令用 `node <skills>/workflow/scripts/docnexus.mjs <参数>` 运行（`docnexus.run`），见 `references/docnexus.md`「DocNexus 的运行位置」 | 查约定与历史决策、沉淀知识、提供文档模板 |
 | 数据库 | `database-query/config.json` 存在且 `connections` 非空 | 查表结构、核对数据 |
 | 代码图谱（CodeGraph） | 项目根有 `.codegraph/` 索引，且 `codegraph` 命令可用（`resolve.mjs status` 的 `codegraph.ok`） | 读代码、查调用链与影响面、找受影响的测试；用法见 `references/codegraph.md` |
 | 项目画像 | `workflow/profile.json` 中 `main_branch` 与 `build` / `test` 非空 | dev 构建与测试 |

package/workflow/references/docnexus.md

@@ -2,18 +2,15 @@
 
 各 skill 写入与参考 DocNexus 时共用的规则。
 
-## DocNexus 在 workflow-run/ 里
+## DocNexus 的运行位置
 
-DocNexus 工作区在 `workflow-run/docnexus/`，以 `workflow-run/` 为项目根运行：
+DocNexus 在业务项目根运行，使用 `.docnexus/node_modules/.bin/docnexus`；运行依赖、skills、草稿和索引都在 `.docnexus/`。初始化参数为 `init --output-dir workflow-run --agent none`，配置写入 `.docnexus/project.json`，知识输出在 `workflow-run/docnexus/`。
 
-- docnexus 系列 skill（`docnexus`、`docnexus-recall` 等）里写的命令，在项目根换成下面的写法运行，不用先 `cd`，任何终端都一样（`resolve.mjs status` 的 `docnexus.run` 就是这个前缀）：
-  - `./docnexus/node_modules/.bin/docnexus <参数>` → `node <skills>/workflow/scripts/docnexus.mjs <参数>`；
-  - `node docnexus/skills/<…>.mjs <参数>` → `node <skills>/workflow/scripts/docnexus.mjs --node docnexus/skills/<…>.mjs <参数>`。
-
-  参数里的路径（草稿、`docnexus/library/<path>`）照旧相对 `workflow-run/`；自己读写这些文件时加上 `workflow-run/`，例如 `workflow-run/docnexus/library/<path>`。
-- 本工作流的脚本已处理位置：`knowledge.mjs` 在那里运行，输出的 `file` 是从项目根读正文的路径；`resolve.mjs template` 给出的模板路径、`expected` 都已带上位置。
-- 引用知识文档仍写 `docnexus/library/<path>`（产物里的「DocNexus：」行也一样）。
-- `workflow-run/` 是独立文档仓库时（见 `references/requirements.md`），知识库由共用这个仓库的各服务一起使用：按分类参考和 recall 都会看到其他服务的沉淀，引用前确认和本次任务相关。写入（capture）完成后运行 `requirement.mjs pending`，`knowledge_files` 是知识库里没提交的文件，`knowledge_commands` 是提交命令（把提交信息换成这次沉淀了什么）。和产物一样，给用户看、用户确认后再提交，推送另外问。
+- 也可使用 `node <skills>/workflow/scripts/docnexus.mjs <参数>`，辅助脚本用 `node <skills>/workflow/scripts/docnexus.mjs --node .docnexus/skills/<…>.mjs <参数>`；所有路径都相对业务项目根。
+- 使用 status 返回的 `workspace_path` / `library_path` / `internal_directory` 和 draft / document 返回的路径。不再做旧版的工作目录切换或前缀转换。知识读取和引用都写 `workflow-run/docnexus/library/<path>`。
+- `resolve.mjs status` 给出 `root`、`internal`、`workspace` 与 `run`；`knowledge.mjs` 的 `path` 与 `file` 都是 CLI 返回的业务根相对路径；`resolve.mjs template` 给出模板实际位置。
+- 不在 `workflow-run/` 内安装或初始化 DocNexus，不使用旧版根目录 `docnexus/` 的 CLI，也不回退到全局 CLI。缺失时通过 workflow-run 安装 / 升级修复。
+- `workflow-run/` 是独立文档仓库时，知识输出可由多个服务共用；各服务仍在自己的业务根配置 `.docnexus/project.json`、运行本机 CLI。写入后 `requirement.mjs pending` 的 `knowledge_files`、`knowledge_commands` 给出知识仓库的待提交内容与命令，按既有授权提交，推送另行授权。
 
 ## 写入 DocNexus 的分类
 
@@ -33,7 +30,7 @@ node <skills>/workflow/scripts/resolve.mjs category <skill>
 DocNexus 按它自己的设计使用：沉淀文档的正文只写知识（约定、决定、坑、根因），不写分支名、产物路径这类工作流信息，免得进入 recall 的检索索引造成干扰，也免得知识文档和工作流的目录结构绑在一起。
 
 - 有 facts 时，每条 fact 的 `provenance` 写一条简单的来源，由你按这个格式写：`<产物种类> <产物路径>（<产物日期>）`，例如 `交付说明 workflow-run/docs/requirements/订单导出支持按渠道筛选/delivery.md（2026-10-15）`。没有 facts 就不写。
-- 从知识库追溯回产物，靠的是产物里的「DocNexus：docnexus/library/<path>」元信息行（沉淀成功后写入）反查，`/workflow view` 会按需求列出沉淀到的知识文档，以及每篇来自哪份产物。不往 DocNexus 里多写内容。
+- 从知识库追溯回产物，靠的是产物里的「DocNexus：workflow-run/docnexus/library/<path>」元信息行（沉淀成功后写入）反查，`/workflow view` 会按需求列出沉淀到的知识文档，以及每篇来自哪份产物。不往 DocNexus 里多写内容。
 
 ## 按分类参考知识库
 
@@ -45,7 +42,6 @@ node <skills>/workflow/scripts/knowledge.mjs <skill> [--match 词1,词2] [--limi
 
 - 参考哪些分类由该 skill 的 `skill.json`（`docnexus.readFrom`，列出要参考哪些 skill 的沉淀）决定，分类名经 `resolve.mjs category` 解析，项目画像改名后自动跟上。
 - 列表：每个分类下的文档（标题、摘要、`path`、更新时间，按更新时间倒序，不含正文）。`--match` 只按标题 / 摘要 / 标签 / 路径过滤，先用本次的模块名、业务名词，没结果再去掉 `--match` 看最近的几篇。
-- `--query`：在每个分类内 `recall`（DocNexus 0.16.0 起支持 `recall --category`），结果放在各分类的 `recall` 字段，能找到标题里没写、正文里提到的内容。问题写成一句话，带上模块名和业务名词，例如「订单列表按创建时间筛选 时区 分页」。
-  - 输出 `recall_by_category: false`（已装的 DocNexus 不支持按分类 recall）→ 按入口 skill `docnexus-recall` 做不带分类的 `recall`，再按列表里的分类 / 路径挑结果。
-- 从列表和 recall 结果里挑与本次任务相关的读 `path`（普通 Markdown），引用时写 `docnexus/library/<path>`。需要跨分类找（例如别的团队的约定）时，仍可按 `docnexus-recall` 做不带分类的 `recall`。
+- `--query`：在每个分类内 `recall`，结果放在各分类的 `recall` 字段，能找到标题里没写、正文里提到的内容。问题写成一句话，带上模块名和业务名词，例如「订单列表按创建时间筛选 时区 分页」。
+- 从列表和 recall 结果里挑与本次任务相关的读 `path`（普通 Markdown），引用时写 `workflow-run/docnexus/library/<path>`。需要跨分类找（例如别的团队的约定）时，仍可按 `docnexus-recall` 做不带分类的 `recall`。
 - 退出码 2 表示未接入 DocNexus，跳过即可；只读，不写入。

package/workflow/references/profile.md

@@ -14,6 +14,7 @@
 | `data_review` | 上线前是否需要数据团队评审库表（`true` / `false`） | 技术方案模块 7、上线方案 2.3 |
 | `notes` | 其他项目约定，一条一句（如「启动需要本地 Redis」） | 全部 |
 | `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` 修改 |
+| `review` | 可选，审查范围与项目规则，如 `{"exclude": ["**/legacy/**"], "include": ["docs/api/**/*.md"], "rules": [{"path": "**/*Mapper.xml", "rule": "分页查询必须带 ORDER BY 主键"}]}`。`exclude` 不审；`include` 把默认跳过的生成文件、文档、本工具产物加回来（删除、二进制、敏感文件加不回来）；`rules` 按 glob 匹配文件路径（不含 `/` 的模式匹配文件名，`**` 跨目录，`{a,b}` 多选），匹配到的规则和审查清单一起检查，不替换清单 | `review-scope.mjs`（project-review、dev 自审） |
 | `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/scripts/docnexus-layout.mjs

@@ -0,0 +1,24 @@
+// DocNexus format 7：项目根运行，内部状态在 .docnexus/，知识输出固定到 workflow-run/docnexus/。
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const DOCNEXUS_INTERNAL = '.docnexus';
+export const DOCNEXUS_OUTPUT = 'workflow-run';
+export const docnexusRoot = (root) => path.resolve(root);
+export const docnexusWorkspace = (root) => path.resolve(root, DOCNEXUS_OUTPUT, 'docnexus');
+export const docnexusInternal = (root) => path.resolve(root, DOCNEXUS_INTERNAL);
+
+export function docnexusConfigured(root) {
+  try {
+    const marker = JSON.parse(fs.readFileSync(path.join(docnexusInternal(root), 'project.json'), 'utf8'));
+    return marker.format_version === 7 && marker.output_dir === DOCNEXUS_OUTPUT;
+  } catch { return false; }
+}
+
+export function docnexusBinPath(root) {
+  const name = process.platform === 'win32' ? 'docnexus.cmd' : 'docnexus';
+  const bin = path.join(docnexusInternal(root), 'node_modules', '.bin', name);
+  return fs.existsSync(bin) ? bin : null;
+}
+
+export const docnexusConnected = (root) => docnexusConfigured(root) && docnexusBinPath(root) !== null;

package/workflow/scripts/docnexus.mjs

@@ -1,12 +1,10 @@
 #!/usr/bin/env node
-// 在 workflow-run/ 下运行 DocNexus（它的项目根），不用先 cd、不用拼 &&，bash / zsh / PowerShell / cmd 里写法一样。
-// docnexus 系列 skill 里的 `./docnexus/node_modules/.bin/docnexus <参数>` 换成 `node <skills>/workflow/scripts/docnexus.mjs <参数>`，
-// `node docnexus/skills/<...>.mjs <参数>` 换成 `node <skills>/workflow/scripts/docnexus.mjs --node docnexus/skills/<...>.mjs <参数>`。
-// 参数里的路径（草稿、docnexus/library/<path>）照旧相对 workflow-run/。输出与退出码原样透传。
+// 在业务项目根运行 DocNexus。内部状态在 .docnexus/，知识输出在 workflow-run/docnexus/。
+// CLI 返回的草稿、文档路径均相对业务项目根；输出与退出码原样透传。
 //
 // 用法（在项目根执行；--root 可指定项目根，须放在最前面）：
 //   node .agents/skills/workflow/scripts/docnexus.mjs recall "订单幂等" --limit 5
-//   node .agents/skills/workflow/scripts/docnexus.mjs --node docnexus/skills/docnexus-library/scripts/query-documents.mjs --category dev-notes
+//   node .agents/skills/workflow/scripts/docnexus.mjs --node .docnexus/skills/docnexus-library/scripts/query-documents.mjs --category dev-notes
 // 退出码：DocNexus 的退出码；DocNexus 没装时为 1
 
 import fs from 'node:fs';
@@ -14,13 +12,14 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { docnexusRoot, docnexusBin } from './resolve.mjs';
+import { docnexusInternal } from './docnexus-layout.mjs';
 
 const readJson = (f) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; } };
 
 // CLI 的入口 JS：直接用 node 跑，Windows 上不经过 .cmd 和 shell，参数不会被转义坏
-// 包名取 workflow-run/docnexus/package.json 的依赖（安装器用 npm install --prefix 装的）
+// 包名取 .docnexus/package.json 的依赖（安装器用 npm install --prefix 装的）
 export function cliEntry(root) {
-  const dn = path.join(docnexusRoot(root), 'docnexus');
+  const dn = docnexusInternal(root);
   const name = Object.keys(readJson(path.join(dn, 'package.json'))?.dependencies ?? {}).find((n) => /(^|\/)docnexus$/.test(n));
   if (!name) return null;
   const pkgDir = path.join(dn, 'node_modules', ...name.split('/'));
@@ -33,7 +32,7 @@ export function run(root, args, opts = {}) {
   const cwd = docnexusRoot(root);
   const o = { cwd, stdio: 'inherit', ...opts };
   if (args[0] === '--node') {
-    if (!args[1]) return { status: 1, error: '--node 后面要跟脚本路径（相对 workflow-run/）' };
+    if (!args[1]) return { status: 1, error: '--node 后面要跟脚本路径（相对业务项目根）' };
     return spawnSync(process.execPath, [path.resolve(cwd, args[1]), ...args.slice(2)], o);
   }
   const entry = cliEntry(root);

package/workflow/scripts/knowledge.mjs

@@ -2,7 +2,7 @@
 // 按分类列出与某个 skill 相关的 DocNexus 文档（标题、摘要、路径，不含正文），供 skill 开工前挑选阅读。
 // 相关分类来自 skill.json 的 docnexus.readFrom（列出要参考哪些 skill 的沉淀），分类名经 resolve.mjs category 解析，
 // 所以项目画像改了分类名也能跟上。列表用 document query --category；给了 --query 时再在每个分类内 recall
-// （DocNexus 0.16.0 起 recall 支持 --category；旧版不支持时只列文档，并提示改用不带分类的 recall）。
+// 当前 DocNexus 直接支持按分类 recall。
 // 只读，不写入任何东西。
 //
 // 用法（在项目根执行；--root 可指定项目根）：
@@ -19,8 +19,8 @@ import { skillMeta, resolveCategory, docnexusConnected, docnexusBin, docnexusRoo
 
 const IS_WIN = process.platform === 'win32';
 
-// 在 DocNexus 的项目根下运行（docnexus.root 指到团队文档仓库时就在那里），输出里的 path 相对那个目录
-const docnexus = (root, args) => spawnSync(path.resolve(root, docnexusBin(root) ?? path.join('node_modules', '.bin', 'docnexus')), args,
+// 在业务项目根运行；CLI 返回的路径已包含 output-dir 前缀。
+const docnexus = (root, args) => spawnSync(path.resolve(root, docnexusBin(root)), args,
   { cwd: docnexusRoot(root), encoding: 'utf8', shell: IS_WIN, maxBuffer: 256 * 1024 * 1024 });
 
 function runJson(root, args, what) {
@@ -34,21 +34,12 @@ function query(root, category) {
   return r.ok ? { ok: true, documents: r.data.documents ?? [] } : r;
 }
 
-// 旧版会静默忽略不认识的参数，recall 会退化成全库检索，所以先看帮助里 recall 有没有 --category
-export function recallSupportsCategory(root) {
-  const r = docnexus(root, ['--help']);
-  return /recall[^\n]*--category/.test(`${r.stdout}${r.stderr}`);
-}
-
 export function knowledge(root, skill, { match = [], limit = 20, query: question = '', recallLimit = 5 } = {}) {
   const meta = skillMeta(skill);
   if (!meta) return { ok: false, error: 'unknown', message: `未安装 skill「${skill}」` };
   if (!docnexusConnected(root)) return { ok: false, error: 'no_docnexus', message: '未接入 DocNexus，跳过知识库参考' };
   const terms = match.map((t) => t.toLowerCase()).filter(Boolean);
   const hit = (d) => !terms.length || terms.some((t) => [d.title, d.summary, d.file_path, ...(d.tags ?? [])].some((v) => String(v ?? '').toLowerCase().includes(t)));
-  const byCategory = question ? recallSupportsCategory(root) : false;
-  // DocNexus 不在本项目时，读文件要加上它的位置
-  const dnRel = path.relative(path.resolve(root), docnexusRoot(root)).split(path.sep).join('/');
   const seen = new Set();
   const categories = [];
   for (const from of meta.docnexus?.readFrom ?? []) {
@@ -60,19 +51,16 @@ export function knowledge(root, skill, { match = [], limit = 20, query: question
     const docs = q.documents.filter(hit).sort((a, b) => String(b.updated_at).localeCompare(String(a.updated_at)));
     const entry = {
       category: c.category, from, ok: true, total: docs.length,
-      documents: docs.slice(0, limit).map((d) => ({ id: d.id, title: d.title, summary: d.summary, path: d.library_path, ...(dnRel ? { file: `${dnRel}/${d.library_path}` } : {}), updated_at: d.updated_at })),
+      documents: docs.slice(0, limit).map((d) => ({ id: d.id, title: d.title, summary: d.summary, path: d.library_path, file: d.library_path, updated_at: d.updated_at })),
     };
-    if (byCategory) {
+    if (question) {
       const r = runJson(root, ['recall', question, '--limit', String(recallLimit), '--category', c.category], 'recall');
       entry.recall = r.ok ? r.data : { ok: false, error: r.error };
     }
     categories.push(entry);
   }
-  const out = { ok: true, skill, ...(dnRel ? { docnexus_root: dnRel, note: `DocNexus 在 ${dnRel}：引用写 path（docnexus/library/...），读正文用 file；recall 结果里的路径也相对 ${dnRel}` } : {}), categories };
-  if (question) {
-    out.recall_by_category = byCategory;
-    if (!byCategory) out.recall_hint = '已装的 DocNexus 不支持 recall --category（0.16.0 起支持）：改用不带分类的 recall，并按上面列出的分类 / 路径挑结果；可升级 @rowansenne/docnexus';
-  }
+  const out = { ok: true, skill, categories };
+  if (question) out.recall_by_category = true;
   return out;
 }