@rowansenne/workflow-run 0.26.1 → 0.27.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@
 
 ## [Unreleased]
 
+## [0.27.0] - 2026-10-24
+
+### 变更
+- 安装相关测试使用本地 DocNexus 包夹具，适配必装组件与知识库模板的新行为，避免验证依赖 npm registry。
+- 精简 dev / project-review 的 Skill 入口：保留门禁、阶段编号、必要命令与结果去向，将开工、方案、实现验证、复核和交付细节下沉到分阶段 references；明确进入阶段前按需读取，保留快速通道、审查后用户选择与运行完成标记。
+- 收敛开工能力与失败处理：共享能力快照区分 CodeGraph 库 / CLI / 源码通道；DocNexus 改为必装组件，缺失自动安装，模板只取知识库，知识查询失败不降级。各 Skill 复用统一规则。Node 最低版本调整为 22.13。
+- `updateMeta` 写入前自动创建父目录，再解析真实路径并加锁，修复直接调用存储接口时目录不存在导致的 ENOENT；读取保持只读，需求绑定仍由上层校验。补充首次写入和后续更新的回归验证及接口说明。
+- 共享核心提取到 `workflow/lib/`：项目配置、需求读取与写入、运行状态、原子存储、文档和产物纯模型分区；原有命令与导出入口保留。状态、view、report、PR 描述统一使用单次采集的内存快照，消除重复正文读取和解析；跨项目展示与当前项目统计保持原范围，Git 元信息从同一引用读取。新增数据诊断，损坏元信息不影响其他正文展示；`list` 改为只读，`sync` 保留 runs 和扩展字段，分支绑定仅由 bind 更新。增加读取次数、一致性、只读、异常隔离、跨项目／分支和无环依赖回归验证。
+- 修复陈旧锁并发回收可能覆盖运行状态的问题：改用锁目录与唯一 PID／UUID 标记，只回收失效进程的旧标记，非空目录不可删除，释放时只清理自身标记。锁目录名改为相对路径的 SHA-256（固定 69 字节），避免长中文需求名在 Linux 上超过文件名限制，也消除路径分隔符与双下划线拼接碰撞。新增双进程并发恢复与长路径回归验证。
+- 修复元信息写锁的两个问题：锁与临时文件从需求目录挪到 `workflow-run/tmp/locks/`，崩溃残留不会再被 `git add` 带进提交；锁内记录写入进程与时间，超过 30 秒且进程已退出的陈旧锁自动清理，不再让一次崩溃永久卡死该需求的 bind / sync / 运行状态写入。坏掉的 meta.json 报错改为说明「不是合法 JSON，已停止写入以免覆盖」并给出修复办法。普通聊天的落盘边界补进 dev 与 project-review（此前只在 workflow 与项目指令里），避免只加载单个 skill 时把辅助文件写进需求目录。
+- 安装、升级时向所选环境的项目指令（CLAUDE.md / AGENTS.md / QWEN.md）写入文件落盘边界，不依赖 DocNexus：普通聊天生成的辅助文件默认放在 `workflow-run/other/`，不绑定需求、不登记运行状态、不混入需求产物；正式工作流、源码与已有文件维护、用户指定路径沿用各自规则。重复安装更新原段落，卸载仅移除该段并保留文件。
+- 完整流程的执行状态统一保存在需求 `meta.json.runs`：按运行 id 和分支隔离，记录阶段、步骤进度、上下文、用户决定、验证证据及历史；运行和步骤均有 `completed` 标识与完成时间。新增 `run.mjs show / start / save / complete / cancel`、`/workflow resume`；完整 dev 在 F4 / B4 创建并补入前置进度，快速通道不创建状态。同步、重新绑定保留历史，元信息写入采用原子替换、短时锁与运行 revision 检查；修复回退重置后续完成标记，完成需明确交付选择及当前分支的产物。状态查询与文档视图展示真实进度、等待／阻塞和“已完成”，没有 Markdown 的运行也可见；后续文档与 wiki 发布另开记录，不覆盖开发运行。
+- 修正两处方案流程衔接：快速通道中途退出后，先回 F4 补方案、自检，M / L 确认后再继续实现、验证、审查与交付选择；缺陷修复追加已有 `plan.md` 时同步更新文档头的分支和日期，并核对当前修复分支的 `latest.plan`。原方案正文保留、上一版照常归档，避免修复方案仍归到原开发分支。
+- 修正 dev 在确定工作分支前读取需求绑定的问题：Step 0 先检查工作区并确定分支，再查询和确认需求名；后续切换分支必须重新查询，不沿用旧分支自动读到的名字。workflow 入口同步将分支确认交给 dev，避免新需求误归档到旧需求目录。用户明确确认继续同一需求时仍可跨分支沿用。
+- dev 的审查流程：优先由未参与实现的独立子 agent 执行 project-review 第 1～7 步并落盘 `review.md`（零发现也写）；没有子 agent 时在当前会话按同样步骤自查，报告「审查者」写当前 agent，不阻塞也不跳过。报告交给用户后等待选择修复或交付；修复后验证、复审并再次等待，选择交付后才生成 / 更新 `delivery.md`。F7 交接清单带上审查深度（默认标准）。遗留风险须用户明确接受，沉淀与反馈仍由 dev 统一处理。
+- **S 规模快速通道改为一次完成、产物完全不落盘**：不绑定需求，方案 / `review.md` / 交付说明都不写，审查在当前会话按标准清单做，交付在对话里一次完成并注明「DocNexus：未询问（快速通道不问沉淀）」；`/workflow report` 与 `/workflow view` 不再统计快速通道的产物。实现中碰到配置 / SQL / 接口 / 表结构等仍退出到完整流程（先绑定需求，补方案与审查报告，再走交付选择）。
+- **方案落盘只看是否快速通道**：非快速通道（S / M / L）一律写方案文档 `plan.md`，规模只决定详细程度（S 简版、M 精简版、L 完整方案）和确认方式；只有 S 快速通道不落盘。原来只有 L（或用户特别要求的 M）才落方案。缺陷修复在 B4 把根因结论与修复方式追加到同一个 `plan.md`（「修复方案」一节），同步更新文档头的分支与日期、用空行与上一节隔开并跑一次 `lint-doc` 自检，不另建文件。方案模板标题由「开发方案」改为「方案」（功能开发与缺陷修复共用），产物类型标签也同步从「开发方案」改为「方案」（效果报告、文档视图、PR 描述、目录树、架构页一致）。交付说明的「自审」节改名为「审查」，与流程里的叫法一致。
+- **需求名提前到 dev 开始时询问**：给不出名字或说不清这次要做什么就不开始；完整流程第一次落盘前 `requirement.mjs bind`，S 快速通道只问不 bind。从 `/workflow` 入口进来同样只问名字、不提前 bind，避免走快速通道前就创建需求目录和 `meta.json`。
+- DocNexus 沉淀统计新增「未询问」（`not_asked`），与「无需沉淀」分别展示且都排除出沉淀率分母。dev 完整流程的内部审查报告记录「未询问（由 dev 交付统一处理）」，F8 的沉淀结果只记交付说明，避免将内部审查算作拒绝或重复计算一次沉淀。模板、效果报告与文档视图同步；明确默认标准审查及交付摘要中的审查结论与遗留风险。
+- dev 不再「每次交付都问一次沉淀」：交付前先判断有没有**特别值得记录**的知识（已确认的决定、新约定、踩到的坑、缺陷根因、配置 / 表结构变化，判断标准是下次做同类需求时能不能少踩一次坑或少做一次决定）。没有就不提沉淀，交付说明的「DocNexus」元信息行写「无需沉淀」，交付摘要里一句话带过；有才问。project-review 单独运行时同样处理（报告元信息行同步支持「无需沉淀」），create-tech-md-doc / create-release-md-doc 也改成「有值得记的才问」。`/workflow report` 与 `/workflow view` 把「无需沉淀」单列，不计入沉淀率的分母，避免没有知识的交付把指标拉低。
+
 ## [0.26.1] - 2026-10-23
 
 ### 修复

package/README.md

@@ -13,17 +13,17 @@
 > 本工具在项目里的产出（需求产物、DocNexus 工作区、项目模板、临时文件）都放在项目根的
 > `workflow-run/`
 > 一个目录里，不往项目的其他地方写；它可以随代码提交，也可以整个是团队的独立文档仓库（见「独立文档仓库」）。
-> 安装只用 npx，在项目根执行。推荐 `npx @rowansenne/workflow-run --with-docnexus --with-codegraph`，同时接入 DocNexus 文档库和 CodeGraph 代码图谱。
+> 安装只用 npx，在项目根执行。推荐 `npx @rowansenne/workflow-run --with-codegraph`；DocNexus 必装，缺失时自动接入。
 
 ## 快速开始
 
-需要 **Node.js >= 22.13**（DocNexus 的要求；不接 DocNexus 时 >= 22 即可，code-graph 的 `impact` / `entry` 需 >= 22.5）。只用 npx 安装，在项目根执行（以当前目录为项目根；Windows 要在管理员终端里运行）。推荐全量安装：
+需要 **Node.js >= 22.13** 与 npm（DocNexus 为必装组件）。只用 npx 安装，在项目根执行（以当前目录为项目根；Windows 要在管理员终端里运行）。推荐全量安装：
 
 ```
-npx @rowansenne/workflow-run --with-docnexus --with-codegraph
+npx @rowansenne/workflow-run --with-codegraph
 ```
 
-按提示：选择环境（编号多选，回车 = 全部）→ 确认 / 填写数据库连接 → 自动生成。`--with-docnexus` 接入 DocNexus 文档库（开发约定与审查问题的沉淀和召回、团队定制的文档模板），`--with-codegraph` 接入 CodeGraph 代码图谱（改动影响到的接口、MQ、定时任务和测试）；不需要哪一项就去掉对应参数。装完后在 agent 里运行 `/workflow profile` 填写项目画像。
+按提示：选择环境（编号多选，回车 = 全部）→ 确认 / 填写数据库连接 → 自动生成。安装时自动接入 DocNexus 文档库（开发约定与审查问题的沉淀和召回、团队定制的文档模板），`--with-codegraph` 接入 CodeGraph 代码图谱（改动影响到的接口、MQ、定时任务和测试）；不需要 CodeGraph 就去掉 `--with-codegraph`。装完后在 agent 里运行 `/workflow profile` 填写项目画像。
 
 全量安装的分步说明见图文教程 [docs/full-install.html](docs/full-install.html)（下载后用浏览器打开）。
 
@@ -44,12 +44,12 @@ npx @rowansenne/workflow-run uninstall
 | 命令 | 作用 |
 | --- | --- |
 | `init`（默认，可省略） | 安装或重装 |
-| `upgrade` | 读安装清单里记录的环境与模式，非交互升级到当前版本：保留数据库配置等用户配置，skills 文件一律更新为新版（手改过的先备份到 `workflow-run/tmp/upgrade-backup/`）。加 `--with-docnexus` 时把 DocNexus 包也升到最新版（`@latest`），刷新 skill 链接与 `CLAUDE.md` / `AGENTS.md` 段落，并导入新增的文档模板（只新增，不改动已有模板）；不加则 DocNexus 包原地不动，只顺带导入新增模板 |
+| `upgrade` | 读安装清单里记录的环境与模式，非交互升级到当前版本：保留数据库配置等用户配置，skills 文件一律更新为新版（手改过的先备份到 `workflow-run/tmp/upgrade-backup/`）。加 `--with-docnexus` 时把 DocNexus 包也升到最新版（`@latest`），刷新 skill 链接与 `CLAUDE.md` / `AGENTS.md` 段落，并导入新增的文档模板（只新增，不改动已有模板）；不加则复用已安装的 DocNexus，缺失时自动补装，并导入新增模板 |
 | `doctor` | 自检：已装版本与当前包对比、手改 / 缺失的文件、软链接是否断开、项目画像、DocNexus 模板是否齐全、各数据库连接能否只读 `SELECT 1`（`--offline` 跳过）、`.gitignore` 是否忽略了凭据。有错误时退出码 1 |
 | `uninstall` | 等价于 `--uninstall` |
 | `report` | 本地效果报告：只读统计 `workflow-run/docs/requirements/` 下的产物（`--since YYYY-MM-DD`、`--all-branches`、`--json`），见「workflow：入口与项目画像」 |
 | `feedback` | 运行反馈汇总：dev / project-review 每次运行记录到 `workflow-run/feedback/<用户>.jsonl` 的过程数据（`--json`），见「运行反馈」 |
-| `view` | 项目文档视图：按需求浏览开发方案、交付说明、审查记录（含复审修复情况）、技术 / 上线方案，生成本地静态页面（`--out <文件>`、`--open`） |
+| `view` | 项目文档视图：按需求浏览方案、交付说明、审查记录（含复审修复情况）、技术 / 上线方案，生成本地静态页面（`--out <文件>`、`--open`） |
 | `docs-repo <仓库地址>` | 改用团队文档仓库：`workflow-run/` 是空的就克隆，已有内容就原地接上远端（目录结构相同，文件不用挪）、代码仓库忽略它、配置本项目的项目名（`--project`，默认 git 远端仓库名）、接上仓库里的 DocNexus；不带地址显示当前状态，见「产物输出规范」 |
 | `seed-templates` | 只把默认文档模板导入 DocNexus，不重装 skills。`--update` 把导入后未改动的模板更新为新版；`--diff` 只读打印团队改过的模板与新默认模板的差异，供手动合并 |
 
@@ -130,7 +130,7 @@ npx @rowansenne/workflow-run@latest doctor --offline
 │   └── template.md
 └── dev/                              # 开发 / 修 bug：需求→调研→方案→实现→测试→自审→交付
     ├── SKILL.md
-    └── references/plan-template.md   # M / L 规模方案模板
+    └── references/plan-template.md   # 方案模板（S / M 简版、L 完整；快速通道不用）
 ```
 
 ## workflow：入口与项目画像
@@ -146,8 +146,10 @@ npx @rowansenne/workflow-run@latest doctor --offline
 
 * 审查：各级别发现条数、严重问题复核通过率、复审时上次问题的修复率；
 * 交付：功能 / 缺陷、S / M / L、开工前经需求澄清确认的决定条数、带「未验证项」的交付；
-* 知识：交付与审查的 DocNexus 沉淀率、正文引用了知识库文档的产物占比；
-* 各分支链路：开发方案、交付说明、审查报告、技术方案、上线方案齐不齐，哪些文档还没发布到 wiki。
+* 知识：交付与审查的 DocNexus 沉淀率（只算真正问过沉淀的，「未询问」「无需沉淀」不计入分母；dev 内部审查不单独询问或重复计入交付沉淀）、正文引用了知识库文档的产物占比；
+* 各分支链路：方案、交付说明、审查报告、技术方案、上线方案齐不齐，哪些文档还没发布到 wiki。
+
+**完整流程状态与续接**：需求目录的 `meta.json` 同时保存绑定、产物索引和按运行 id 区分的 `runs`。每次运行关联分支，记录阶段、逐步完成标记、上下文、待用户决定、阻塞原因、历史与 revision；完成后保存 `status: completed` 和 `completed_at`。`/workflow status` 查看状态，`/workflow resume [运行id]` 核对后继续；`/workflow view` 展示运行与“已完成”，尚未生成 Markdown 的运行也可见。快速通道保持不绑定、不创建运行状态。完整 dev 在 F4／B4 确定流程后开始记录，补入此前已确认的进度；后续文档／发布用独立运行保留开发的完成记录。脚本用法见 `workflow/references/runs.md`，`sync` 不会清掉状态。
 
 **运行反馈**（`npx @rowansenne/workflow-run feedback [--json]`）：效果报告只看落盘的产物，看不到过程。dev 和 project-review 每跑完一次，用 `workflow/scripts/feedback.mjs add` 静默追加一行到 `workflow-run/feedback/<git 用户名>.jsonl`：模型、规模 / 深度、是否走快速通道、向用户提问几轮、用户纠正过几次理解、验收项验证了几条、跳过了哪些步骤、**哪条规则读不懂或做不到**、用户主动说的抱怨。只记过程，不记代码和业务名词；不额外问用户。每人一个文件，随 `workflow-run/` 提交，多人不冲突。独立文档仓库模式下，安装器在文档仓库的 `workflow-run/.gitattributes` 里给这些文件配 `merge=union`，同一个文件在几个分支上都有记录时合并也不冲突；随代码提交时不改代码仓库的 `.gitattributes`，合并时遇到冲突保留两边的行即可。用来定期精简 skill：
 
@@ -210,11 +212,12 @@ node .agents/skills/workflow/scripts/resolve.mjs env --check   # 逐个字段核
 /dev --bug <现象 | 报错 | 日志>       # 缺陷修复
 ```
 
-* **功能开发**：理解需求（可读 PRD、查 DocNexus 历史决策）→ 调研现有代码 → 需求澄清（借鉴 grill-me：按决策树分轮提问，每题给推荐答案；事实自己查、决定交给用户；S 规模无未定决定时跳过澄清提问）→ **规模判定（S / M / L 说明判定依据，不再询问确认）** → 按规模出方案（S 列步骤开始、符合条件时问是否走快速通道；M 对话内方案待确认；L 落盘方案文档待确认）→ 小步实现并编译 → 补测试并运行 → 用 project-review 自审 → 交付说明落盘到 `workflow-run/docs/requirements/<需求名>/<项目名>/delivery.md`（带分支元信息；改动、验证结果、配置清单、未执行的 SQL），已接入 DocNexus 时每次都问要不要沉淀（同意后以 `dev-notes` 分类写入，并把库内路径记回交付说明）。审查和上线方案会按分支自动读取这份交付说明。
-* **S 规模快速通道**：规模判定不询问用户；S 规模且不涉及配置、SQL / DDL、对外接口、表结构，也没有需要澄清的业务决定时，**问用户是否走快速通道**，问完等本轮答复——明确同意才走：编译、测试、自审照常，但只在对话里交付，不落盘交付说明、不问沉淀；拒绝或未明确同意就按完整流程落盘交付。实现中碰到上述任何一项或改动超过 3 个文件，就退回完整流程，规模变化时按新规模继续。缺陷修复同样适用（根因仍须在对话里写清楚）。
-* **缺陷修复**：收集现象 → 用失败测试复现 → 用证据定位根因 → **判定规模并告知（S 规模问是否走快速通道；M / L 确认根因与修复方式后再改）** → 最小修复让测试转绿 → 自审 → 交付（必须写明根因）。
+* **功能开发**：开始前先确定工作分支，再确认需求名（给不出名字或说不清要做什么就不开始）→ 理解需求（可读 PRD、查 DocNexus 历史决策）→ 调研现有代码 → 需求澄清（借鉴 grill-me：按决策树分轮提问，每题给推荐答案；事实自己查、决定交给用户；S 规模无未定决定时跳过澄清提问）→ **规模判定（S / M / L 说明判定依据，不再询问确认）** → 按规模出方案（非快速通道一律落方案文档：S 简版、M 精简版、L 完整版；S 符合条件时先问是否走快速通道，走则不落盘）→ 小步实现并编译 → 补测试并运行 → 优先由独立子 agent 按 project-review 审查并落盘 `review.md`（没有子 agent 时在当前会话自查，报告注明审查者）→ 报告交给用户，等待选择「修复问题 / 交付」；修复则验证后重新审查、再次等待选择，选择交付后才将交付说明落盘到 `workflow-run/docs/requirements/<需求名>/<项目名>/delivery.md`（带分支元信息；改动、验证结果、配置清单、未执行的 SQL），已接入 DocNexus 时交付里有值得记录的知识才问要不要沉淀（同意后以 `dev-notes` 分类写入，并把库内路径记回交付说明），没有就跳过并在元信息行写「无需沉淀」。审查和上线方案会按分支自动读取这份交付说明。
+* **S 规模快速通道**：规模判定不询问用户；S 规模且不涉及配置、SQL / DDL、对外接口、表结构，也没有需要澄清的业务决定时，**问用户是否走快速通道**，问完等本轮答复——明确同意才走：编译、测试照常，审查在当前会话按标准清单做，**不绑定需求、不落任何产物文件**（方案 / `review.md` / 交付说明都不写；运行反馈照常记一行），对话里一次交付并注明「DocNexus：未询问（快速通道不问沉淀）」；拒绝或未明确同意就按完整流程落盘交付。实现中碰到上述任何一项或改动超过 3 个文件，先停下后续实现、重新评估规模，绑定需求并回 F4 补方案、自检；M / L 确认方案后再继续实现、验证、审查与交付选择。缺陷修复同样适用（根因仍须在对话里写清楚）。
+* **缺陷修复**：收集现象 → 用失败测试复现 → 用证据定位根因 → **判定规模并告知（S 规模问是否走快速通道；M / L 确认根因与修复方式后再改）** → 完整流程先把根因与修复方式追加到 `plan.md`，同步更新文档头的修复分支与日期（不另建文件）→ 最小修复让测试转绿 → 审查并落盘报告（无子 agent 时当前会话自查）→ 用户选择修复或交付（修复后验证与复审；交付必须写明根因）。
+* 审查优先用独立子 agent（期间不继续改被审代码，子 agent 只审查、写报告，不直接修复）；没有子 agent 时降级为当前会话自查并把「审查者」写成当前 agent，不阻塞、也不跳过审查。遗留严重问题须说明风险并由用户明确接受，不能把选择交付写成审查通过。
 * 守则：不写库、不改凭据、不擅自 commit / push、不装新依赖；测试没跑就写「未验证」。
-* 其他 skill 都是可选增强：wiki、DocNexus、数据库没配置时自动跳过，并在交付说明中注明。
+* DocNexus 是必装组件，缺失或查询失败时先修复；wiki、CodeGraph、数据库为可选增强，所有 Skill 共用开工能力快照与失败处理规则（`workflow/references/capabilities.md`）。
 
 ## 参数
 
@@ -224,11 +227,11 @@ node .agents/skills/workflow/scripts/resolve.mjs env --check   # 逐个字段核
 | ----------------------- | --------------------------------------------------------------------- |
 | `--envs`      | 环境列表，逗号分隔：`codex,claude,doubao,qwen,workbuddy`；`all` = 全部                       |
 | `--skip-db` | 跳过数据库连接配置（database-query 不生成 config.json）                             |
-| `--with-docnexus` | 可选：接入 [DocNexus](https://www.npmjs.com/package/@rowansenne/docnexus) 项目文档库（需 Node >= 22.13），见下方「DocNexus 文档库（可选）」 |
+| `--with-docnexus` | 强制将必装的 DocNexus 更新到最新版；默认缺失即安装、已有则复用（需 Node >= 22.13 与 npm） |
 | `--with-codegraph` | 可选：接入 [CodeGraph](https://github.com/colbymchenry/codegraph) 代码图谱，见下方「CodeGraph 代码图谱（可选）」 |
 | `--copy`      | 不建软链接，各环境独立拷贝一份完整 skills                                  |
 | `--skills <列表>` | 只装这些 skill（逗号分隔），自动带上 `requires` 依赖；之后可以再用 `--skills` 补装，已装的保留；`upgrade` 只升级装过的。不含 database-query 时不询问数据库 |
-| `--seed-templates` | 把自带的文档模板导入 DocNexus（已有的不覆盖）；接入 DocNexus 后文档类 skill 只从知识库取模板。`--with-docnexus` 会自动执行 |
+| `--seed-templates` | 把自带的文档模板导入 DocNexus（已有的不覆盖）；接入 DocNexus 后文档类 skill 只从知识库取模板。每次安装 / 升级都会自动执行 |
 | `--uninstall` | 按安装清单卸载本项目装的 skills 与链接，见下方「卸载」 |
 | `--offline` | `doctor` 不测试数据库连通性 |
 | `--yes`        | 非交互：自动使用已有数据库配置（依次查找 `.codex/database-query/config.json` 与各环境已安装的 `database-query/config.json`）；都没有且未 `-SkipDb` 时报错退出 |
@@ -236,7 +239,7 @@ node .agents/skills/workflow/scripts/resolve.mjs env --check   # 逐个字段核
 | `--version`      | 显示版本                                                                |
 | `--help`         | 帮助                                                                    |
 
-## DocNexus 文档库（可选）
+## DocNexus 文档库（必装）
 
 接入支持 `--output-dir` 的 DocNexus format 7，在**业务项目根**执行安装和初始化：
 
@@ -245,7 +248,7 @@ npm install --prefix ./.docnexus --save-exact @rowansenne/docnexus
 ./.docnexus/node_modules/.bin/docnexus init --output-dir workflow-run --agent none
 ```
 
-`workflow-run --with-docnexus` 自动执行这两步，并链接所选 Agent 的 skills、写入项目说明、导入文档模板。
+`workflow-run` 自动补齐 DocNexus 接入，并链接所选 Agent 的 skills、写入项目说明、导入文档模板。
 
 ### 运行环境与知识输出
 
@@ -262,6 +265,7 @@ npm install --prefix ./.docnexus --save-exact @rowansenne/docnexus
     │   ├── CONCEPTS.md / concepts/
     │   └── library/ / records/ / impacts/
     ├── docs/requirements/           # 工作流产物
+    ├── other/                       # 普通聊天生成的辅助文件，按需创建
     └── tmp/
 ```
 
@@ -302,7 +306,7 @@ node .agents/skills/workflow/scripts/docnexus.mjs usage export > workflow-run/do
 npx @rowansenne/workflow-run upgrade --with-docnexus
 ```
 
-新项目用 `npx @rowansenne/workflow-run --with-docnexus`。默认从 npm 安装最新版（`@rowansenne/docnexus@latest`），接入和升级都取最新版；离线或本地验证可设 `DOCNEXUS_PKG=/path/to/package-or-source` 指定安装来源（此时不再追加 `@latest`），必须使用支持 format 7 和 `--output-dir` 的版本。
+新项目用 `npx @rowansenne/workflow-run`，自动安装必需的 DocNexus。默认从 npm 安装最新版（`@rowansenne/docnexus@latest`），接入和升级都取最新版；离线或本地验证可设 `DOCNEXUS_PKG=/path/to/package-or-source` 指定安装来源（此时不再追加 `@latest`），必须使用支持 format 7 和 `--output-dir` 的版本。
 
 ## CodeGraph 代码图谱与 code-graph skill（可选）
 
@@ -326,7 +330,7 @@ npx @rowansenne/workflow-run upgrade --with-docnexus
 | `cg.mjs tables [--table t]` | MyBatis XML 语句（namespace.id）涉及的表 |
 | `cg.mjs status` | 索引与库是否可用 |
 
-`mq`、`jobs`、`tables` 只扫源码，没有索引也能用。`impact`、`entry` 需要 `.codegraph/` 索引和 CodeGraph 的库（Node >= 22.5）；缺了就退出码 2 并说明原因，skill 会退回 grep / 读文件。
+`mq`、`jobs`、`tables` 只扫源码，没有索引也能用。`impact`、`entry` 需要 `.codegraph/` 索引和 CodeGraph 的库（Node >= 22.5）；开工快照区分 script / cli / source，Skill 按共享规则选择一次，不逐步试错。
 
 dev、project-review、技术方案、上线方案都在对应环节调用它：
 - **dev**：改公共方法前看入口；验证时先跑受影响的测试；交付说明里写受影响的接口 / 表 / 配置。
@@ -448,7 +452,11 @@ npx @rowansenne/workflow-run uninstall
 
 `tests/test-skills-meta.mjs` 会检查：skill 的文件里出现了别的 skill 的路径（如 `md-to-wiki/scripts/…`、`workflow/scripts/…`），就必须在 `requires` 或 `optional` 里声明；`requires` 声明了就必须真的用到，而且不能成环。
 
-当前依赖关系：`workflow` 是共享核心（模板来源、画像、文档自检脚本），`dev`、`project-review`、两个文档 skill 依赖它；`dev` 还依赖 `project-review`（自审必做，要读它的审查清单）；`database-query`、`md-to-wiki` 完全独立；wiki 凭据只由 `md-to-wiki` 的脚本读取，其他 skill 拉 PRD 统一调用 `upload.mjs get`。
+当前依赖关系：`workflow` Skill 负责入口编排，其 `lib/` 提供共享核心（项目配置、需求、运行、文档与产物模型），`scripts/` 保留对外命令路径；`dev`、`project-review`、两个文档 skill 依赖它；`dev` 还依赖 `project-review`（自审必做，要读它的审查清单）；`database-query`、`md-to-wiki` 也自动带上 workflow，以复用统一开工检查；wiki 凭据只由 `md-to-wiki` 的脚本读取，其他 skill 拉 PRD 统一调用 `upload.mjs get`。
+
+dev 与 project-review 的 SKILL.md 保留门禁、步骤路由、必要命令和结果去向；进入阶段前才读取对应 reference 的小节。dev 的开工、调研方案、实现验证、审查交付和缺陷修复分开加载；审查的方法、复核、报告与后续也分开加载。完整流程的步骤编号、用户选择、运行状态与正式产物规则沿用原协议，必守规则不藏在脚本注释中。
+
+状态查询、文档视图、效果报告和 PR 描述共用 `workflow/lib/workspace-read.mjs` 的单次命令内存快照，正文与元信息采集一次，使用统一解析规则。需求绑定、运行状态和已登记版本来自 `meta.json`；正文、文档头和发布记录来自 Markdown，产物索引由显式 `sync` 重建。`list` 只读，`sync` 不再从文档头隐式增加绑定分支，绑定使用 `bind`。跨项目视图仍展示全部服务，分支查询和效果报告默认当前项目；`--all-branches` 保持同路径工作区优先，Git 中的版本信息从同一引用读取。异常数据通过 diagnostics 报告，可读的正文仍展示，读取不修复或覆盖元信息。边界与数据归属详见 [内部架构](workflow/references/architecture.md)。
 
 新增一个 skill 就是新建目录、写 `SKILL.md.tpl` 和 `skill.json`，再加进 `package.json` 的 `files`。`tests/test-skills-meta.mjs` 会检查它们是否一致。
 
@@ -458,25 +466,27 @@ npx @rowansenne/workflow-run uninstall
 
 | 脚本（安装后在 `<skills>/` 下） | 作用 |
 | --- | --- |
-| `workflow/scripts/resolve.mjs template <skill> <文件名>` | 判定用哪份模板：已接入 DocNexus 只用知识库，缺失时退出码 2 并给出导入来源；未接入时项目文件优先，其次默认模板 |
+| `workflow/scripts/resolve.mjs template <skill> <文件名>` | 只从 DocNexus 知识库解析模板；缺失时给出导入或创建指引，不回退到包内模板 |
 | `workflow/scripts/resolve.mjs profile` | 读项目画像，列出空字段 |
 | `workflow/scripts/resolve.mjs env` | 本机系统与终端（安装时记录在 `profile.local.json`），写终端命令按它来 |
 | `workflow/scripts/resolve.mjs env --check` | 核对画像里的开发环境配置（`toolchain`）在本机是否存在：每个字段给出 `resolved`（展开后）、`exists`、`unset_vars`，以及 `current`（本机实际的 `JAVA_HOME` / `MAVEN_HOME` / Node 目录）便于对照 |
 | `workflow/scripts/docnexus.mjs <参数>` / `--node <脚本> <参数>` | 在业务项目根运行 `.docnexus/` 中的 CLI 或它的 node 脚本，知识输出到 `workflow-run/docnexus/`；Windows 上直接用 node 跑 CLI 入口，不经过 `.cmd` |
-| `workflow/scripts/knowledge.mjs <skill> [--match 词] [--limit n] [--query 问题]` | 按 `readFrom` 的分类列出 DocNexus 文档（标题、摘要、路径，不含正文）；`--query` 再在每个分类内 `recall --category`，直接使用新版按分类检索能力。未接入时退出码 2 |
+| `workflow/scripts/knowledge.mjs <skill> [--match 词] [--limit n] [--query 问题]` | 按 `readFrom` 的分类列出 DocNexus 文档（标题、摘要、路径，不含正文）；`--query` 再在每个分类内 `recall --category`，直接使用新版按分类检索能力。必装组件不可用时退出码 2，查询失败返回非 0，不当作无匹配 |
 | `workflow/scripts/resolve.mjs category <skill>` | 该 skill 写入 DocNexus 时的显式分类（画像 `docnexus_categories` 优先，其次 skill.json），输出 `seal_args` 与 `metadata`；未声明时退出码 1 |
+| `workflow/lib/capabilities.mjs` | 集中探测必装 DocNexus 与可选增强；供 resolve status 输出本轮能力快照 |
 | `workflow/scripts/resolve.mjs status` | `/workflow status` 的能力探测（不输出任何凭据） |
 | `workflow/scripts/resolve.mjs infer-profile` | 按固定规则从构建文件、Makefile、依赖与配置文件、git 推断项目画像草稿，每个字段附依据；不写文件 |
 | `workflow/scripts/lint-doc.mjs <文档> --skill <skill> [--facts]` | 对照当前生效的模板检查生成的文档：必填章节、残留 `{{...}}` 占位符、元信息行为错误；缺普通章节、顺序不一致为警告；列出待填写位置。`--facts` 再核对正文里的类名、文件、接口、表名：在对比分支的 diff 和代码里都找不到的记为警告（防编造） |
 | `workflow/scripts/requirement.mjs which / bind / path / sync / pending / list / config` | 产物按需求归档（`workflow-run/docs/requirements/<需求>/<项目>/`，两种模式结构相同）：查当前分支绑定的需求（没绑定时给出按分支名生成的建议名）、绑定需求名、给出本次落盘路径（不覆盖，带上一版的 wiki 记录）、重建 `meta.json`、列出所有需求；`config` 设置产物位置（文档仓库、项目名、提交提示），`pending` 看文档仓库里还没提交的产物 |
 | `workflow/scripts/view.mjs [--out f] [--open]` | 项目文档视图（`/workflow view`、`npx @rowansenne/workflow-run view`）：读需求目录里的产物，生成单个 HTML，按需求列出各阶段、审查记录（各级别数量、复核、与上次对比）、交付记录、沉淀到的知识文档，正文直接渲染；顶部「知识文档」列出每篇知识文档来自哪个需求、哪份产物；数据内嵌，只读、不联网，默认写到 `workflow-run/tmp/view/index.html` |
-| `workflow/scripts/artifacts.mjs [--branch b \| --all]` | 按分支汇总 `workflow-run/docs/requirements/` 下的开发方案、交付说明、审查报告、技术方案、上线方案及其 wiki 发布记录，给出下一步建议；分支取自文档元信息行，不另存记录。上线方案没传 `--tech` 时据此自动引用同分支的技术方案；project-review 据此对照本分支方案、识别复审 |
+| `workflow/scripts/run.mjs show / start / save / complete / cancel` | 需求 meta.json 中的分支运行记录：恢复、checkpoint、已完成状态与时间、等待用户、修复回退、revision 冲突检查 |
+| `workflow/scripts/artifacts.mjs [--branch b \| --all]` | 按分支汇总 `workflow-run/docs/requirements/` 下的方案、交付说明、审查报告、技术方案、上线方案及其 wiki 发布记录，给出下一步建议；分支取自文档元信息行，不另存记录。上线方案没传 `--tech` 时据此自动引用同分支的技术方案；project-review 据此对照本分支方案、识别复审 |
 | `workflow/scripts/report.mjs [--since d] [--all-branches] [--json]` | 本地效果报告（`/workflow report`、`npx @rowansenne/workflow-run report`）：审查发现与修复率、复核率、需求澄清、沉淀率、知识引用、各分支链路 |
 | `workflow/scripts/feedback.mjs add … / summary [--json]` | 运行反馈：dev / project-review 交付后追加一行过程记录到 `workflow-run/feedback/<用户>.jsonl`；`summary` 按 skill 汇总，跳过的步骤和不清楚的规则按 SKILL.md 章节归类（`npx @rowansenne/workflow-run feedback`）；`init` / `upgrade` 装了新版本时清掉本项目旧版本的记录 |
 | `workflow/scripts/review-scope.mjs [--diff b...h \| --base b] [--exclude a,b]` / `rules <文件…>` | 审查范围：由脚本决定审哪些文件、跳过哪些（删除、二进制、敏感文件、依赖目录、生成文件、文档、本工具产物，各带原因）、每个文件的风险级别和分批，以及按文件类型和改动内容该看审查清单的哪几节；`--base` 含未提交和未跟踪的新文件。`rules` 打印这些小节的原文和画像 `review.rules` 里匹配的项目规则。project-review 第 1、3、4 步与 dev 自审使用 |
 | `workflow/scripts/locate.mjs <发现.json> [--diff b...h \| --base b]` | 给审查发现定位行号：按每条发现引用的原代码片段在文件里查找（精确 → 忽略空白 → 单行部分匹配），多处时优先本次改动的行，输出起止行、是否落在本次改动上；找不到的标出来要求重读代码。project-review 第 6 步复核使用 |
 | `workflow/scripts/tables.mjs [--diff b...h \| --base b \| --files a,b]` | 找出改动涉及哪些表：实体注解（`@TableName` / `@Table`，没写表名时按类名推断）、Mapper XML 与代码里的 SQL、DDL 脚本；标出 DDL、是否在 `schema.md` 里，并给出拉表结构的命令。dev 调研 / 自检与 project-review 审 SQL / DDL 时使用 |
-| `workflow/scripts/template.mjs list / draft / check / save <模板>` | 修改 / 创建模板（`/workflow template`）：把当前模板复制成草稿（或 `--from <样例>` 抽骨架），`check` 校验格式、列出章节变化、拿最近几份已生成文档试跑 lint 看影响，`save` 给出写入 DocNexus 知识库的 capture 指引，不直接写知识库；未接入 DocNexus 时 `draft` / `save` 提示先接入（默认模板只读） |
+| `workflow/scripts/template.mjs list / draft / check / save <模板>` | 修改 / 创建模板（`/workflow template`）：把当前模板复制成草稿（或 `--from <样例>` 抽骨架），`check` 校验格式、列出章节变化、拿最近几份已生成文档试跑 lint 看影响，`save` 给出写入 DocNexus 知识库的 capture 指引，不直接写知识库；必装组件不可用时先修复 |
 | `workflow/scripts/pr-desc.mjs [--branch b] [--base m] [--out f]` | 按本分支产物生成 PR / MR 描述；没有交付说明时退回用 git 记录 |
 | `database-query/scripts/query.mjs` | 执行 SQL：选连接、取密码（只通过环境变量传给客户端）、会话层只读、拦截写语句和多语句、自动补 LIMIT、超时、脱敏敏感列；支持 mysql / psql 客户端，其他 driver 退回 JDBC |
 | `database-query/scripts/query.mjs --schema [--tables a,b] [--write]` | 按只读会话导出表结构为 Markdown；`--write` 写入 `references/schema.md` 的 `schema:begin` / `schema:end` 之间，标记外的补充说明保留；指定的表在库里不存在时标出 |
@@ -519,11 +529,12 @@ CI（`.github/workflows/test.yml`）在 push 到 main 和每个 PR 上运行：m
 | `.agents/skills/workflow/profile.json` | 项目画像（无凭据），产物目录用的项目名也在这里 |
 | `.agents/skills/database-query/references/schema.md` | 表结构速查，补齐后提交 |
 | `workflow-run/docs/requirements/` | 需求产物；独立文档仓库模式下提交到文档仓库 |
+| `workflow-run/other/` | 普通聊天生成的报告、方案、草稿、导出等辅助文件（按需创建，可按主题分目录）；不进入需求索引、运行状态、需求统计与文档视图，按需提交 |
 | `workflow-run/feedback/` | 运行反馈，每人一个文件；独立文档仓库模式下提交到文档仓库 |
 | `.docnexus/project.json`、npm 清单与锁文件 | DocNexus 项目配置与运行依赖版本，随代码提交 |
 | `workflow-run/docnexus/` | DocNexus 知识输出与定制的文档模板。独立文档仓库模式下提交到文档仓库 |
 | `.ignore` | 让代码搜索跳过需求目录（不影响 git） |
-| `.gitignore`、`CLAUDE.md` / `AGENTS.md` | 安装器追加的忽略规则、DocNexus 说明段落 |
+| `.gitignore`、`CLAUDE.md` / `AGENTS.md` / `QWEN.md` | 安装器追加的忽略规则、文件落盘约定、DocNexus 说明段落 |
 
 **忽略**（每人每机器一份，或可重新生成）：
 
@@ -592,21 +603,23 @@ git status --short --ignored
 
 ## 产物输出规范（统一落位）
 
-一个需求的文档产物放在**同一个需求目录**里，开发方案、交付说明、审查报告、技术方案、上线方案一起看：
+普通聊天生成的报告、分析、方案、草稿、导出等辅助文件默认写到 `workflow-run/other/`（按需创建，可按主题建子目录），不绑定需求、不登记运行状态，也不进入需求统计与文档视图。安装与 `upgrade` 会向所选环境的 `CLAUDE.md` / `AGENTS.md` / `QWEN.md` 写入这条项目级指令，无需接入 DocNexus；卸载只清理自己的指令段，保留手写内容与产物。源码、测试、配置和已有文件的维护、工作流指定的临时目录与知识库沿用原路径；用户明确指定输出路径时以用户为准。不会自动搬移已有文件。
+
+一个需求的文档产物放在**同一个需求目录**里，方案（开发 / 缺陷修复）、交付说明、审查报告、技术方案、上线方案一起看：
 
 ```
 workflow-run/docs/requirements/<需求名>/<项目名>/
-├── meta.json        # 需求名、绑定的分支、各产物（版本、日期、wiki 发布记录、DocNexus 沉淀），给以后的可视化用
-├── plan.md          # 开发方案（dev，L 规模）
-├── delivery.md      # 交付说明（dev，每次完整交付都写）
-├── review.md        # 审查报告（project-review）；复审也写这个文件，上一版归档到 workflow-run/tmp/old-artifacts/
+├── meta.json        # runs 保存分支运行状态、逐步完成标记与完成时间；另含 需求名、绑定的分支、各产物（版本、日期、wiki 发布记录、DocNexus 沉淀），给以后的可视化用
+├── plan.md          # 方案（dev，非快速通道都写；S / M 简版；缺陷修复追加修复方案节）
+├── delivery.md      # 交付说明（dev，完整流程审查后用户选择交付才写；S 快速通道不落盘）
+├── review.md        # 审查报告（独立审查或 dev 完整流程自查；S 快速通道不落盘）；复审也写这个文件，上一版归档到 workflow-run/tmp/old-artifacts/
 ├── tech-doc.md      # 技术方案
 └── release-doc.md   # 上线方案
 ```
 
 * **随代码提交和独立文档仓库两种用法的结构完全一样**，切换时文件不用挪。一个需求横跨多个服务时，各服务在同一个需求目录下各占一个 `<项目名>/`。项目名写在 `workflow/profile.json` 的 `artifacts.project`：随代码提交时不用配置，取 git 远端仓库名（没有远端用目录名），第一次落盘时自动写进去；独立文档仓库时由 `docs-repo` 配置。
 * 旧版本随代码提交时没有 `<项目名>/` 这一层；`upgrade` 会把这些需求目录里的文件迁到 `<需求>/<项目名>/`（被 git 跟踪的用 `git mv`，保留历史），结尾列出迁移了哪些需求，改动由你提交。目标里已有同名文件的需求不动，并提示手动处理；`doctor` 也会提示还没迁移的需求。
-* **需求名由你定**：dev 确定是 M / L 规模（要落盘）时，或从 `/workflow` 完整链路开始时，如果当前分支还没有绑定需求，会问你这个需求叫什么（默认值按分支名生成；也可以选已有的需求，例如修 bug 的新分支挂到原需求下）。你不起名就按分支名生成。绑定后，同一分支上的各 skill 都写到这个目录，不再问。一个需求可以绑定多个分支。
+* **需求名由你定**：dev 在 Step 0 先确定工作分支，再查询绑定并确认需求名，给不出名字或说不清这次要做什么时不会进入开发流程（默认值按分支名生成；也可以选已有的需求，例如修 bug 的新分支挂到原需求下）。从 `/workflow` 完整链路开始时同样先问（只问名字，第一次落盘时才 `bind`）；S 快速通道也问，但不绑定、不落盘。确定后，同一分支上的各 skill 都写到这个目录，不再问。一个需求可以绑定多个分支。
 * 路径由 `workflow/scripts/requirement.mjs path <种类>` 给出，每种产物文件名固定，目录里只留最新版，引用不会失效；版本号记在 `meta.json` 的 `versions`。已有旧版时，上一版先复制到 `workflow-run/tmp/old-artifacts/<需求>/<项目>/<种类>_v<N>.md`（不提交），新版直接覆盖写入；skill 会列出归档的文件，请你确认后自己删除。上一版发布过 wiki 时，新版沿用同一个页面。
 * 需求目录写在项目根的 `.ignore` 里，ripgrep 和 agent 的代码搜索会跳过它，产物多了不会污染搜索结果（找历史决策用 DocNexus）。git 不受影响，建议随代码提交。
 
@@ -650,7 +663,7 @@ npx @rowansenne/workflow-run docs-repo <团队文档仓库地址> [--project <
 ```
 workflow-run（安装器仓库）/
 ├── bin/
-│   ├── workflow-run.mjs                # 安装器入口（唯一实现，Node >= 22）：参数解析与 init / upgrade / doctor / uninstall / seed-templates / report / view / docs-repo 调度
+│   ├── workflow-run.mjs                # 安装器入口（唯一实现，Node >= 22.13）：参数解析与 init / upgrade / doctor / uninstall / seed-templates / report / view / docs-repo 调度
 │   ├── lib/                           # core / prompt / db / install / uninstall / docnexus / doctor / docsrepo
 │   ├── skills.mjs                     # 读取各 skill 的 skill.json
 │   └── seed-templates.mjs             # 把文档模板导入 DocNexus
@@ -662,6 +675,15 @@ workflow-run（安装器仓库）/
 ├── README.md                          # 本说明
 ├── workflow/
 │   ├── SKILL.md.tpl · skill.json
+│   ├── lib/                           # 共享核心；不反向依赖 scripts 命令入口
+│   │   ├── project.mjs                # 布局、画像、环境与配置
+│   │   ├── requirement-read.mjs       # 需求目录与元信息读取
+│   │   ├── requirements.mjs           # 绑定、版本归档与索引同步
+│   │   ├── runs.mjs                   # 运行状态、阶段与完成校验
+│   │   ├── meta-store.mjs             # 写锁与原子存储
+│   │   ├── document-model.mjs         # 标题、章节、表格等纯文本模型
+│   │   ├── artifact-model.mjs         # 产物类型、元信息、审查与交付解析
+│   │   └── workspace-read.mjs         # 工作区 / Git 采集、统一读取快照
 │   ├── scripts/resolve.mjs            # 模板来源 / 画像 / 画像推断 / 能力探测
 │   ├── scripts/lint-doc.mjs           # 对照模板检查生成的文档
 │   ├── scripts/infer-profile.mjs      # 画像推断规则（resolve.mjs infer-profile 调用）
@@ -674,8 +696,8 @@ workflow-run（安装器仓库）/
 │   ├── scripts/requirement.mjs        # 产物按需求归档：绑定需求名、落盘路径、meta.json
 │   ├── scripts/view.mjs               # 项目文档视图（本地静态页面）
 │   ├── scripts/make-template.mjs      # 从样例文档抽模板骨架
-│   ├── scripts/doc-sections.mjs       # 读产物的章节、表格、元信息（report / pr-desc 共用，标题解析复用 lint-doc）
-│   ├── references/                    # profile.md、templates.md、docnexus.md、status.md、tables.md、requirements.md、codegraph.md（其他 skill 直接读对应文件）
+│   ├── scripts/doc-sections.mjs       # 原解析导出入口，转交 lib/document-model.mjs
+│   ├── references/                    # profile.md、capabilities.md、templates.md、docnexus.md、status.md、tables.md、requirements.md、codegraph.md（其他 skill 直接读对应文件）
 │   └── profile.json.tpl               # 空画像，首次使用时由 agent 推断并经确认后填写
 ├── dev/
 │   ├── SKILL.md.tpl · skill.json
@@ -720,14 +742,14 @@ workflow-run（安装器仓库）/
 文档类 skill 的模板来源取决于项目是否接入了 DocNexus，生成的文档开头会注明「模板来源」：
 
 * **已接入 DocNexus：只用知识库里的模板** `workflow-run/docnexus/library/templates/<skill>/<文件名>`（分类 `doc-template`）。不再使用 skill 自带的默认模板。库里缺模板时 skill 会停下来，提示你导入后再继续，不会悄悄回退到默认模板。
-* **未接入 DocNexus**：只用 skill 自带的默认模板。
+* **DocNexus 不可用**：修复必装组件后继续，不使用包内模板降级。
 * **默认模板只读，定制只走 DocNexus**：要改模板或新建模板，都写进 DocNexus 知识库，团队共享同一份、每次变更有 timeline。不要直接改 skills 目录里的模板（升级会覆盖）；`workflow-run/templates/` 下的项目模板已不再生效，`doctor` 会提示你导入知识库后删除。
 
 | skill | 文件名 | 用途 | 默认模板 |
 | --- | --- | --- | --- |
 | create-tech-md-doc | `template.md` | 技术方案模板 | **不提供**，第一次用时按样例创建 |
 | create-release-md-doc | `template.md` | 上线方案模板 | **不提供**，第一次用时按样例创建 |
-| dev | `plan-template.md` | 开发方案模板 | 有 |
+| dev | `plan-template.md` | 方案模板（开发 / 修复） | 有 |
 | dev | `delivery-template.md` | 交付说明模板 | 有 |
 | project-review | `checklist.md` | 审查清单 | 有 |
 | project-review | `report.md` | 审查报告模板 | 有 |
@@ -740,7 +762,7 @@ workflow-run（安装器仓库）/
 2. `template.mjs check` 校验格式（必填 ` *`、可选「（如有）」、占位符），列出新增 / 删除的章节、必填变化，并拿最近几份已生成的文档试跑，告诉你新模板下它们会多出哪些错误；
 3. 你确认后经你授权按 capture 流程写入 DocNexus 知识库，再确认生效；要撤销按 DocNexus 的 timeline 恢复旧版本。
 
-模板别名：`tech`、`release`、`plan`、`delivery`、`review`、`checklist`。改带默认版本的模板（开发方案、交付说明、审查报告、审查清单）也走这条路，知识库里的版本取代默认版本，升级不会覆盖。未接入 DocNexus 时不能修改模板，agent 会提示你先接入。
+模板别名：`tech`、`release`、`plan`、`delivery`、`review`、`checklist`。改带默认版本的模板（方案、交付说明、审查报告、审查清单）也走这条路，知识库里的版本取代默认版本，升级不会覆盖。未接入 DocNexus 时不能修改模板，agent 会提示你先接入。
 
 * `doctor` 和 `/workflow status` 会列出还没创建的模板，以及要先接入 DocNexus 才能创建的模板。
 

package/bin/lib/artifact-context.mjs

@@ -0,0 +1,46 @@
+// 普通聊天也会加载的项目级落盘约定；不依赖 DocNexus 或 skill 是否触发。
+import fs from 'node:fs';
+import path from 'node:path';
+import { HOME, ok } from './core.mjs';
+
+const START = '<!-- workflow-run:artifacts:start -->';
+const END = '<!-- workflow-run:artifacts:end -->';
+const FILES = ['CLAUDE.md', 'AGENTS.md', 'QWEN.md'];
+const BLOCK = [
+  START,
+  '## 工作流文件落盘边界',
+  '',
+  `- 普通聊天中生成的报告、分析、方案、草稿、导出等辅助文件，默认写到项目根的 \`${HOME}/other/\`（需要时创建，可按主题建子目录）。不要因为分支已绑定需求就放进需求目录。`,
+  `- \`${HOME}/docs/requirements/\` 只存通过 dev、project-review、create-tech-md-doc、create-release-md-doc 等工作流生成的正式需求产物。普通聊天不得为辅助文件调用 requirement.mjs bind / path / sync 或 run.mjs，不创建或更新需求 meta.json，也不将这些文件计入需求产物和运行状态。`,
+  '- 项目源码、测试、配置及已有文件的维护仍遵循项目原目录；工作流自身指定的临时目录、知识库等路径沿用各自规则。用户明确指定输出路径时按用户要求执行，不自动搬移已有文件。',
+  END,
+].join('\n');
+
+export function writeArtifactContext(root, envs) {
+  const files = new Set();
+  if (envs.includes('claude')) files.add('CLAUDE.md');
+  if (envs.some((e) => ['codex', 'doubao', 'workbuddy'].includes(e))) files.add('AGENTS.md');
+  if (envs.includes('qwen')) files.add('QWEN.md');
+  for (const file of files) {
+    const f = path.join(root, file);
+    const cur = fs.existsSync(f) ? fs.readFileSync(f, 'utf8') : '';
+    const a = cur.indexOf(START); const b = cur.indexOf(END);
+    const next = a >= 0 && b > a
+      ? `${cur.slice(0, a)}${BLOCK}${cur.slice(b + END.length)}`
+      : `${cur}${!cur || cur.endsWith('\n\n') ? '' : cur.endsWith('\n') ? '\n' : '\n\n'}${BLOCK}\n`;
+    if (next !== cur) { fs.writeFileSync(f, next); ok(`${file} 已写入文件落盘约定（普通聊天产物在 ${HOME}/other/）`); }
+  }
+}
+
+export function removeArtifactContext(root) {
+  for (const file of FILES) {
+    const f = path.join(root, file);
+    if (!fs.existsSync(f)) continue;
+    const cur = fs.readFileSync(f, 'utf8');
+    const a = cur.indexOf(START); const b = cur.indexOf(END);
+    if (a < 0 || b < a) continue;
+    const rest = [cur.slice(0, a).replace(/\n+$/, ''), cur.slice(b + END.length).replace(/^\n+/, '')].filter(Boolean).join('\n\n');
+    if (rest) fs.writeFileSync(f, `${rest}\n`); else fs.rmSync(f);
+    ok(`${file} 已移除文件落盘约定`);
+  }
+}

package/bin/lib/docnexus.mjs

@@ -79,8 +79,8 @@ export function run(cmd, args, cwd, quiet = false) {
 }
 export function checkNodeForDocNexus() {
   const [maj, min] = process.versions.node.split('.').map(Number);
-  if (maj < 22 || (maj === 22 && min < 13)) fail(`--with-docnexus 需要 Node >= 22.13，当前为 v${process.versions.node}。请升级 Node 后重试，或去掉 --with-docnexus。`);
-  if (spawnSync(IS_WIN ? 'npm.cmd' : 'npm', ['-v'], { stdio: 'ignore', shell: IS_WIN }).status !== 0) fail('--with-docnexus 需要 npm，但未找到。请安装后重试，或去掉 --with-docnexus。');
+  if (maj < 22 || (maj === 22 && min < 13)) fail(`必装组件 DocNexus 需要 Node >= 22.13，当前为 v${process.versions.node}。请升级 Node 后重试。`);
+  if (spawnSync(IS_WIN ? 'npm.cmd' : 'npm', ['-v'], { stdio: 'ignore', shell: IS_WIN }).status !== 0) fail('必装组件 DocNexus 需要 npm，但未找到。请安装后重试。');
   ok(`Node v${process.versions.node}`);
 }
 // DocNexus 的 skills（.docnexus/skills/*）链接到所选 Agent 环境；init --agent none，由本工具统一接入。
@@ -179,9 +179,9 @@ export function refreshDocNexusLinks(root, sel) {
 export function setupDocNexus(root, sel) {
   const npmArgs = ['install', '--prefix', './.docnexus', '--save-exact', DOCNEXUS_SPEC];
   step(`接入 DocNexus（运行环境 .docnexus/；知识输出 ${HOME}/docnexus/）`);
-  if (!run(IS_WIN ? 'npm.cmd' : 'npm', npmArgs, root)) { warn('npm 安装 DocNexus 失败，已跳过 DocNexus 接入（skills 已正常安装）'); return 'failed'; }
+  if (!run(IS_WIN ? 'npm.cmd' : 'npm', npmArgs, root)) { warn('npm 安装必装组件 DocNexus 失败'); return 'failed'; }
   const bin = docnexusBin(root);
-  if (!bin) { warn('安装后未找到 .docnexus/node_modules/.bin/docnexus，已跳过 DocNexus 接入'); return 'failed'; }
+  if (!bin) { warn('安装后未找到 .docnexus/node_modules/.bin/docnexus，接入失败'); return 'failed'; }
   if (!run(bin, ['init', '--output-dir', HOME, '--agent', 'none'], root)) {
     warn(`DocNexus 初始化失败：需要支持 --output-dir 的 format 7 版本。修复后在项目根运行 ./.docnexus/node_modules/.bin/docnexus init --output-dir ${HOME} --agent none`);
     return 'failed';

package/bin/lib/doctor.mjs

@@ -116,10 +116,9 @@ export function doctor(root, offline) {
     if (st.docnexus.ok) {
       if (!reportTemplateStatus(root, meh)) ok('DocNexus 已接入，文档模板齐全且与默认模板同步（或为团队定制版）');
     } else if (fs.existsSync(path.join(root, '.docnexus', 'project.json'))) bad('DocNexus 配置或运行环境不完整：需要 format 7、output_dir=workflow-run 和 .docnexus/ 下的 CLI，运行 upgrade --with-docnexus 修复');
-    else console.log('    --  DocNexus 未接入（可选；未接入时只能用 skills 自带的默认模板，不能修改）');
+    else bad('必装组件 DocNexus 缺失：运行 npx @rowansenne/workflow-run 修复，工作流不提供降级模式');
     // workflow-run/templates/ 已不再生效：模板定制只放 DocNexus
     for (const f of st.docnexus.stale_project_templates ?? []) meh(st.docnexus.ok ? `${f} 已不再生效：确认已导入 DocNexus 知识库后删除` : `${f} 已不再生效（模板定制只放 DocNexus）：重跑 npx @rowansenne/workflow-run 并加 --with-docnexus 接入后导入知识库，再删除`);
-    for (const t of st.templates_need_docnexus ?? []) console.log(`    --  ${t.skill} 的模板 ${t.id} 不随 skills 提供，要先接入 DocNexus 才能创建（重跑 npx @rowansenne/workflow-run 并加 --with-docnexus）`);
     for (const t of st.templates_to_create ?? []) console.log(`    --  ${t.skill} 的模板 ${t.id} 还没有创建（不随 skills 提供）：第一次生成文档时会请你给一份样例文档来创建，保存到 ${t.expected}`);
     if (st.codegraph?.ok) ok(`CodeGraph 已接入（codegraph ${codegraphVersion(root)}，索引在 .codegraph/）`);
     else if (st.codegraph?.indexed) meh('有 .codegraph/ 索引但找不到 codegraph 命令：npm i -g @colbymchenry/codegraph，或重跑 npx @rowansenne/workflow-run 并加 --with-codegraph');

package/bin/lib/install.mjs

@@ -6,7 +6,7 @@ import { TPL_DIR, PKG, CANON_DIR, INSTALL_BASES, SKILLS, SKILL_LIST, USER_FILES,
 import { writeDbConfig } from './db.mjs';
 import { linkPointsTo } from './uninstall.mjs';
 import { layout, ensureIgnore, homeIsRepo, migrateLayout, IGNORE_LINE, TMP_DIR } from '../../workflow/scripts/requirement.mjs';
-import { detectEnv } from '../../workflow/scripts/resolve.mjs';
+import { detectEnv } from '../../workflow/lib/project.mjs';
 import { rotate as rotateFeedback, ensureUnionMerge } from '../../workflow/scripts/feedback.mjs';
 
 // 结尾汇总：被手改过、已用新版覆盖（原文件已备份）的 / 模板已删除、手改过而备份后删除的文件 /

package/bin/lib/uninstall.mjs

@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { IS_WIN, CANON_DIR, INSTALL_BASES, MANIFEST, step, ok, warn, toPosix, fileHash, readManifest, removeEmptyDirs, lstat, timestamp, removeLink, docnexusInternal } from './core.mjs';
 import { removeDocNexusContext } from './docnexus.mjs';
+import { removeArtifactContext } from './artifact-context.mjs';
 
 // 软链接是否指向 absTarget（按解析后的绝对路径比较，兼容 Windows 上 readlink 返回的 \\?\ 前缀）
 export function linkPointsTo(link, absTarget) {
@@ -52,6 +53,8 @@ export function uninstall(root) {
     if (n || files.length) ok(`已移除指向 ${toPosix(path.relative(root, src))} 的 ${n} 个 DocNexus skill 链接${files.length ? `，以及 ${files.join('、')} 里的 DocNexus 段落` : ''}（.docnexus/ 运行环境与 workflow-run/docnexus/ 知识输出保留）`);
   }
 
+  removeArtifactContext(root);
+
   // 2. 各安装目录：按清单删除模板文件；用户配置与手改过的模板文件先备份
   for (const [rel, m] of found) {
     const base = path.join(root, rel);

package/bin/workflow-run.mjs

@@ -23,6 +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 { writeArtifactContext } from './lib/artifact-context.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';
@@ -35,7 +36,7 @@ const HELP = `用法: workflow-run [命令] [选项]
 命令：
   init（默认）         安装或重装 skills
   upgrade              按安装清单里的环境与模式非交互升级到当前版本（保留数据库配置等用户配置；skills 文件一律更新为新版，手改过的先备份到 workflow-run/tmp/upgrade-backup/）；
-                       加 --with-docnexus 时把 DocNexus 包也升到最新版（@latest），刷新 skill 链接与 CLAUDE.md / AGENTS.md 段落，并导入新增的文档模板（只新增，不覆盖已有模板）；不加则 DocNexus 包原地不动，只顺带导入新增模板
+                       加 --with-docnexus 时把 DocNexus 包也升到最新版（@latest），刷新 skill 链接与 CLAUDE.md / AGENTS.md 段落，并导入新增的文档模板（只新增，不覆盖已有模板）；不加则复用已安装的 DocNexus；缺失时自动安装，并导入新增模板
   doctor               自检：版本、手改 / 缺失文件、软链接、项目画像、DocNexus 模板、数据库连通性、.gitignore
   uninstall            按安装清单卸载本项目装的 skills 与链接（用户配置备份到 workflow-run/tmp/uninstall-backup/）
   seed-templates       只把自带的文档模板导入 DocNexus（workflow-run/docnexus/library/templates/，已有的不覆盖）
@@ -49,11 +50,11 @@ init 选项：
   --envs <列表>        环境，逗号分隔：codex,claude,doubao,qwen,workbuddy；all = 全部（不传则交互选择）
   --skip-db            跳过数据库连接配置
   --yes                非交互：使用已有数据库配置；都没有且未 --skip-db 时报错退出
-  --with-docnexus      同时接入 DocNexus 文档库（装在 workflow-run/docnexus/，需 Node >= 22.13 与 npm），并导入文档模板
+  --with-docnexus      强制更新必装的 DocNexus 到最新版（默认缺失即安装、已安装则复用；运行环境在 .docnexus/，需 Node >= 22.13 与 npm）
   --with-codegraph     同时接入 CodeGraph 代码图谱：没有 codegraph 命令时 npm 全局安装，为 claude / codex 写项目级 MCP 配置，并建本项目索引（.codegraph/）
   --copy               不用软链接，各环境独立拷贝
   --skills <列表>      只装这些 skill（逗号分隔），自动带上 skill.json 里 requires 声明的依赖；缺省为全部
-  --seed-templates     安装后把文档模板导入 DocNexus；接入 DocNexus 后文档类 skill 只从知识库取模板
+  --seed-templates     安装已自动补入文档模板，此参数可省略
   --uninstall          同 uninstall 命令
 seed-templates 选项：
   --update             同时把「导入后未改动、但默认模板有新版」的知识库模板更新为新版
@@ -75,7 +76,7 @@ view 选项：
   -h, --help           显示帮助`;
 
 function parseArgs(argv) {
-  const o = { cmd: 'init', envs: '', skipDb: false, yes: false, withDocNexus: false, withCodeGraph: false, copy: false, seedTemplates: false, update: false, diff: false, skills: '', offline: false, root: process.cwd() };
+  const o = { cmd: 'init', envs: '', skipDb: false, yes: false, withDocNexus: false, withCodeGraph: false, copy: false, update: false, diff: false, skills: '', offline: false, root: process.cwd() };
   let cmdGiven = false; // 命令可以出现在选项之间（封装脚本会先传 --project-root）
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -88,7 +89,7 @@ function parseArgs(argv) {
       case '--with-codegraph': o.withCodeGraph = true; break;
       case '--copy': o.copy = true; break;
       case '--skills': o.skills = val(); break;
-      case '--seed-templates': o.seedTemplates = true; break;
+      case '--seed-templates': break; // 安装始终补入模板，保留旧参数写法
       case '--uninstall': o.cmd = 'uninstall'; cmdGiven = true; break;
       case '--offline': o.offline = true; break;
       case '--update': o.update = true; break;
@@ -189,7 +190,8 @@ async function main() {
   ${again}`);
   }
   if (o.cmd === 'upgrade') o = upgradeOptions(o);
-  if (o.withDocNexus) { step('检查 DocNexus 依赖'); checkNodeForDocNexus(); }
+  step('检查必装组件 DocNexus 的依赖');
+  checkNodeForDocNexus();
 
   const sel = await resolveEnvs(o);
   step(`目标环境：${sel.join(' ')}`);
@@ -235,26 +237,17 @@ async function main() {
   updateGitignore(o.root, o.withCodeGraph);
   setupHome(o.root);
   recordEnv(o.root);
-  const docnexus = o.withDocNexus ? setupDocNexus(o.root, sel) : 'skipped';
-  // 升级 / 重装都刷新本项目里的 DocNexus skills 链接与 CLAUDE.md / AGENTS.md 段落
-  if (!o.withDocNexus) refreshDocNexusLinks(o.root, sel);
+  writeArtifactContext(o.root, sel);
+  if (o.withDocNexus || !docnexusConnected(o.root)) {
+    if (setupDocNexus(o.root, sel) !== 'ok') fail('必装组件 DocNexus 接入失败，安装未完成。修复上方错误后重新运行安装命令。');
+  } else refreshDocNexusLinks(o.root, sel);
   const codegraph = o.withCodeGraph ? setupCodeGraph(o.root, sel) : 'skipped';
-  let seedFailed = false;
-  // 接入 DocNexus 后文档类 skill 只从知识库取模板，所以 --with-docnexus 时一并导入（已有的不覆盖）；
-  // upgrade 时新版本可能新增了模板（缺了 skill 会停下），已接入就顺带导入缺的，不改动已有模板
-  const upgradeSeed = o.upgrading && docnexusConnected(o.root);
-  if ((o.seedTemplates || o.withDocNexus || upgradeSeed) && docnexus !== 'failed') {
-    step(upgradeSeed && !o.seedTemplates && !o.withDocNexus ? '导入新增的文档模板到 DocNexus（只新增，已有模板不动）' : '导入文档模板到 DocNexus（--seed-templates）');
-    try {
-      const r = seedTemplates(o.root, TPL_DIR, { ok, warn, version: PKG.version, skills: installedSkills(o.root), quietSkip: upgradeSeed });
-      saveTemplateRecords(o.root, r.records);
-      // upgrade 顺带的导入是尽力而为：失败只提示，不让升级本身算失败
-      const explicit = o.seedTemplates || o.withDocNexus;
-      seedFailed = explicit && r.failed.length > 0;
-      if (!explicit && r.failed.length) warn('新增模板导入失败（skills 已升级）：修复后运行 npx @rowansenne/workflow-run seed-templates 重试');
-      if (upgradeSeed && !r.seeded.length && !r.failed.length) ok('知识库里的文档模板齐全，无需导入');
-    } catch (e) { warn(e.message); seedFailed = o.seedTemplates || o.withDocNexus; }
-  }
+  step('导入文档模板到 DocNexus（只新增，已有模板不动）');
+  try {
+    const r = seedTemplates(o.root, TPL_DIR, { ok, warn, version: PKG.version, skills: installedSkills(o.root), quietSkip: true });
+    saveTemplateRecords(o.root, r.records);
+    if (r.failed.length) fail('必需文档模板导入失败，安装未完成。修复后运行 npx @rowansenne/workflow-run seed-templates 重试。');
+  } catch (e) { fail(e.message); }
 
   step('安装完成，启用方式');
   console.log('  codex     : 重启 codex 后自动发现项目级 skills（.agents/skills）；也可 /use project-review 手动加载');
@@ -267,10 +260,9 @@ async function main() {
   else warn('注意：本次未写入数据库连接。可重跑补配，或手动放置 database-query/config.json（已有的保留不动）。');
   warn('注意：md-to-wiki 的 wiki 连接（wiki-config.json）默认留空（enabled=false），未配置前 md-to-wiki 与 create-*-md-doc 的 --prd 增强不启动。');
   warn('        启用方法：填写 .agents/skills/md-to-wiki/wiki-config.json（enabled: true + base_url + api_token），或接入对应环境的 wiki MCP。重跑不会覆盖已填写的配置。');
-  if (docnexus === 'ok') ok('DocNexus 已接入：dev / project-review 会按 docnexus-recall 查项目约定；文档类 skill 只从 workflow-run/docnexus/library/templates/ 取模板；任何写入 DocNexus 的操作都需你授权。');
+  ok('DocNexus 已接入：dev / project-review 会按 docnexus-recall 查项目约定；文档类 skill 只从 workflow-run/docnexus/library/templates/ 取模板；任何写入 DocNexus 的操作都需你授权。');
   // 已接入 DocNexus：缺模板时文档类 skill 会停下来要求导入；默认模板有新版时提示更新或合并
   if (docnexusConnected(o.root)) reportTemplateStatus(o.root);
-  if (docnexus === 'failed') warn('注意：DocNexus 接入失败（见上方输出），其他 skills 不受影响；修复后可重跑（加 --with-docnexus）。');
   if (codegraph === 'failed') warn('注意：CodeGraph 接入失败（见上方输出），其他 skills 不受影响；skills 会退回 grep / 读文件；修复后可重跑（加 --with-codegraph）。');
   const keep = '（skills 目录里的文件以安装包为准；项目定制请放到 workflow/profile.json、DocNexus（文档模板只能在这里定制）或 CLAUDE.md / AGENTS.md）';
   if (report.overwritten.length || report.removed.length) {
@@ -283,8 +275,7 @@ async function main() {
     ok(`${report.unlistedDirs.join('、')} 里没有安装清单，${report.unlisted.length} 个和新版不同的文件已备份到 ${report.backupDir}/ 后覆盖（无从判断是否手改过）`);
   }
   console.log('先运行 /workflow profile 填写项目画像；说明见 workflow-run README。');
-  // skills 已装好，但显式要求的 DocNexus 未接入：返回非 0 便于自动化感知
-  return docnexus === 'failed' || codegraph === 'failed' || seedFailed ? 1 : 0;
+  return codegraph === 'failed' ? 1 : 0;
 }
 
 main().then((code) => process.exit(code), (e) => {