@rowansenne/workflow-run 0.23.0 → 0.24.1

package/CHANGELOG.md

@@ -4,6 +4,22 @@
 
 ## [Unreleased]
 
+## [0.24.1] - 2026-10-21
+
+### 修复
+- WorkBuddy 改用 `--copy` 重装时，将本工具已有的技能软链接转换为真实目录，保留已填配置，避免写入共享来源或影响其他环境；用户指向其他位置的链接保留并报错。
+- 升级以最近一次显式安装的环境和模式为准，自动退回拷贝的清单不覆盖单一来源的完整技能选择。
+- 补充 Windows WorkBuddy 的管理员终端、独立拷贝安装及技能不可见时的排查说明。
+
+## [0.24.0] - 2026-10-21
+
+### 变更
+- dev 新增规模确认：功能开发和缺陷修复在判定 S / M / L 后都需说明依据、快速通道及落盘安排，等用户明确确认再继续；可以和理解 / 方案确认同轮提出。实现中规模变化需重新确认，单纯的规模确认不影响 S 规模快速通道资格。
+
+### 变更（破坏性）
+- DocNexus 按当前 format 7 重新接入：在业务项目根安装到 `.docnexus/`，运行 `init --output-dir workflow-run --agent none`，知识输出在 `workflow-run/docnexus/`。安装、包装脚本、模板导入、知识检索、doctor、卸载入口和所有 Agent 路径说明同步更新；Qwen 自动写入 `QWEN.md`。
+- 强制删除旧版 `workflow-run/docnexus/` 的旧知识和内部运行文件、`workflow-run/.docnexus/`、旧重复备份及能识别的根目录旧安装，不迁移、不备份。新版输出的知识在重装后保留，工作流需求产物不受影响。移除此前的旧版调用与分类检索降级。
+
 ## [0.23.0] - 2026-10-19
 
 ### 新增

package/README.md

@@ -78,6 +78,21 @@ npx @rowansenne/workflow-run docs-repo git@git.example.com:team/team-docs.git
 * Windows：安装与升级（`init` / `upgrade`）**必须在管理员终端执行**（建目录软链接需要该权限）；在普通终端运行会直接停下、不做任何改动，并提示改用「以管理员身份运行」的终端。`doctor`、`seed-templates`、`uninstall` 不要求管理员。少数文件系统仍建不了软链接时，该环境自动退回独立拷贝。在 Windows 上 clone 含软链接的仓库需要 `git config core.symlinks true`。
 * 不想用软链接：加 `--copy`，每个环境各装一份完整文件。
 
+### 在 Windows 的 WorkBuddy 中使用
+
+在**业务项目根目录**打开管理员 PowerShell，运行 npm 包提供的安装命令（仅 `npm install` 下载包不会生成项目技能）：
+
+```powershell
+npx @rowansenne/workflow-run@latest --envs workbuddy --copy --skip-db --yes
+npx @rowansenne/workflow-run@latest doctor --offline
+```
+
+这里用 `--copy` 在 `.codebuddy/skills/<skill>/` 生成真实目录和 `SKILL.md`，便于排除目录软链接的兼容问题。已有指向 `.agents/skills/` 的本工具链接会先转成独立拷贝，保留已填配置，再更新技能文件；共享来源和 Qwen 等其他环境的链接不变。后续 `upgrade` 沿用最近一次显式安装的环境和模式。只选择 WorkBuddy 时，全新安装不会生成 `.qwen/skills/`。
+
+安装后，将 **同一个业务项目目录**设为 WorkBuddy 任务的工作目录，重新打开项目并新建会话，再尝试 `/workflow status`、`/dev` 或 `/project-review`。`/workflow profile` 等是技能参数，不是额外的独立技能。
+
+如果仍然不可见，先确认业务项目下确实有 `.codebuddy/skills/workflow/SKILL.md`，并保留安装命令、`doctor --offline` 输出与 WorkBuddy 版本以便排查。项目级配置目录见 [WorkBuddy 官方说明](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Project)。
+
 每个 skill 目录结构（四环境一致）：
 
 
@@ -179,9 +194,9 @@ npx @rowansenne/workflow-run docs-repo git@git.example.com:team/team-docs.git
 /dev --bug <现象 | 报错 | 日志>       # 缺陷修复
 ```
 
-* **功能开发**：理解需求（可读 PRD、查 DocNexus 历史决策）→ 调研现有代码 → 需求澄清（借鉴 grill-me：按决策树分轮提问，每题给推荐答案；事实自己查、决定交给用户；S 规模无未定决定时跳过）→ 按规模出方案（S 直接做；M 对话内方案待确认；L 落盘方案文档待确认）→ 小步实现并编译 → 补测试并运行 → 用 project-review 自审 → 交付说明落盘到 `workflow-run/docs/requirements/<需求名>/<项目名>/delivery.md`（带分支元信息；改动、验证结果、配置清单、未执行的 SQL），已接入 DocNexus 时每次都问要不要沉淀（同意后以 `dev-notes` 分类写入，并把库内路径记回交付说明）。审查和上线方案会按分支自动读取这份交付说明。
-* **S 规模快速通道**：S 规模且不涉及配置、SQL / DDL、对外接口、表结构，也没有需要澄清的决定时，编译、测试、自审照常，但只在对话里交付，不落盘交付说明、不问沉淀；实现中碰到上述任何一项或改动超过 3 个文件，就退回完整流程。缺陷修复同样适用（根因仍须在对话里写清楚）。
-* **缺陷修复**：收集现象 → 用失败测试复现 → 用证据定位根因 → 最小修复让测试转绿 → 自审 → 交付（必须写明根因）。
+* **功能开发**：理解需求（可读 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 个文件，就退回完整流程，规模变化时先确认新规模。规模确认本身不影响快速通道资格。缺陷修复同样适用（根因仍须在对话里写清楚）。
+* **缺陷修复**：收集现象 → 用失败测试复现 → 用证据定位根因 → **判定规模并等用户确认** → 最小修复让测试转绿 → 自审 → 交付（必须写明根因）。
 * 守则：不写库、不改凭据、不擅自 commit / push、不装新依赖；测试没跑就写「未验证」。
 * 其他 skill 都是可选增强：wiki、DocNexus、数据库没配置时自动跳过，并在交付说明中注明。
 
@@ -207,38 +222,71 @@ npx @rowansenne/workflow-run docs-repo git@git.example.com:team/team-docs.git
 
 ## DocNexus 文档库（可选）
 
-加 `--with-docnexus` 时，脚本在装完本仓库的 skills 后额外执行：
+接入支持 `--output-dir` 的 DocNexus format 7，在**业务项目根**执行安装和初始化：
 
-1. 检查 Node >= 22.13 与 npm（不满足时**在安装任何文件之前**报错退出）；
-2. 在 `workflow-run/` 下执行 `npm install --prefix ./docnexus --save-exact @rowansenne/docnexus`：装在 `workflow-run/docnexus/` 下，npm 清单、锁文件和依赖不进宿主项目的 `package.json`；
-3. 在 `workflow-run/` 下执行 `./docnexus/node_modules/.bin/docnexus init --agent none`：创建 `workflow-run/docnexus/` 工作区，把 DocNexus 的 skills 同步到 `workflow-run/docnexus/skills/`；再由本工具把它们软链接到所选环境的 skills 目录、写入 `CLAUDE.md` / `AGENTS.md` 的段落（见下方「DocNexus 的位置」）。
+```bash
+npm install --prefix ./.docnexus --save-exact @rowansenne/docnexus
+./.docnexus/node_modules/.bin/docnexus init --output-dir workflow-run --agent none
+```
 
-依赖和检索库（`node_modules/`、`store/`）由 DocNexus 自带的 `docnexus/.gitignore` 忽略，它随工作区一起提交，所以随代码提交和独立文档仓库两种模式都不用另加规则。
+`workflow-run --with-docnexus` 自动执行这两步，并链接所选 Agent 的 skills、写入项目说明、导入文档模板。
+
+### 运行环境与知识输出
+
+```text
+<业务项目>/
+├── .docnexus/                       # npm 运行环境与内部状态
+│   ├── package.json / package-lock.json
+│   ├── project.json                 # format_version=7，output_dir=workflow-run
+│   ├── node_modules/                # CLI 和依赖
+│   ├── skills/ / schemas/
+│   └── drafts/ / store/ / .runtime/
+└── workflow-run/
+    ├── docnexus/                    # 知识输出，内部不安装 npm
+    │   ├── CONCEPTS.md / concepts/
+    │   └── library/ / records/ / impacts/
+    ├── docs/requirements/           # 工作流产物
+    └── tmp/
+```
 
-环境映射（本工具链接 DocNexus 的 skills、写段落）：
+所有 DocNexus 命令均从业务项目根运行，CLI 返回的路径直接用于读取和引用，不添加或删除前缀：
 
-| 所选环境 | 链接到 | 写段落 |
+```bash
+node .agents/skills/workflow/scripts/docnexus.mjs status
+node .agents/skills/workflow/scripts/docnexus.mjs view
+node .agents/skills/workflow/scripts/docnexus.mjs usage export > workflow-run/docnexus-usage.json
+```
+
+`status` 返回 `workspace_path`、`library_path`、`internal_directory`。知识输出固定为 `workflow-run/docnexus/`；草稿与辅助脚本位于 `.docnexus/`。模板保存在 `workflow-run/docnexus/library/templates/<skill>/`。
+
+| 环境 | DocNexus skill 入口 | 项目说明 |
 | --- | --- | --- |
-| claude | `.claude/skills/` | `CLAUDE.md` |
-| codex / doubao | `.agents/skills/`（两者共用） | `AGENTS.md` |
-| workbuddy | `.codebuddy/skills/` | `AGENTS.md`（WorkBuddy 读项目的 `AGENTS.md`，与 `CODEBUDDY.md` 并存） |
-| qwen | `.qwen/skills/` | 不写 `QWEN.md`；需要自动召回时可在 `QWEN.md` 引用 `AGENTS.md` 的 DocNexus 段落，或在 `.qwen/settings.json` 的 `context.fileName` 加入 `AGENTS.md` |
+| claude | `.claude/skills/` → `.docnexus/skills/` | `CLAUDE.md` |
+| codex / doubao | `.agents/skills/` → `.docnexus/skills/` | `AGENTS.md` |
+| workbuddy | `.codebuddy/skills/` → `.docnexus/skills/` | `AGENTS.md` |
+| qwen | `.qwen/skills/` → `.docnexus/skills/` | `QWEN.md` |
+
+升级 / 重装刷新入口与说明，不改手写段落。知识写入仍走 DocNexus 的授权与 capture 流程。普通 `uninstall` 移除 Agent 入口和说明，保留 `.docnexus/` 运行环境与知识输出。
+
+`.docnexus/.gitignore` 由 DocNexus 维护，忽略运行依赖、索引、草稿和内置资源；`.docnexus/project.json`、npm 清单和锁文件应随代码提交。知识输出随 `workflow-run/` 提交；独立文档仓库模式下只在文档仓库提交知识，本项目仍保存自己的 `.docnexus/` 配置和运行环境。
 
-说明：
+### 破坏性更新：旧布局强制清理
 
-* DocNexus 的 skills 不在本仓库中，始终以安装的 npm 包为准；重跑脚本会按包版本重新同步与链接（`docnexus init` 可重复执行，不影响已有记忆）。
-* `.qwen/skills/`、`.codebuddy/skills/` 下已存在的同名**真实目录**不会被替换，脚本会提示跳过。
-* npm 安装或 `docnexus init` 失败时只跳过 DocNexus，本仓库的 skills 照常安装，脚本最后以退出码 1 结束；修好后重跑即可。
-* 安装后 `dev`、`project-review` 会先按 `docnexus-recall` 查项目约定；`dev`、`project-review` 交付时**每次都问**要不要沉淀（写入后把库内路径记回交付说明 / 审查报告的「DocNexus」元信息行），`create-tech-md-doc`、`create-release-md-doc` 结束时有值得记的内容才**提议**沉淀；**任何写入 DocNexus 的操作都必须经你授权**。
-* 离线或测试时可用环境变量指定安装来源，例如 `DOCNEXUS_PKG=/path/to/rowansenne-docnexus-0.13.0.tgz npx @rowansenne/workflow-run --with-docnexus`（PowerShell：`$env:DOCNEXUS_PKG=...`）。
-* Windows 上的链接使用目录软链接（需管理员终端）。
+本次不兼容旧 DocNexus，不迁移、不备份旧知识。`init` / `upgrade` 在安装前强制删除：
 
-### DocNexus 的位置
+- 旧版 `workflow-run/docnexus/`（含旧 `project.json`、npm / skills / store 等内部文件的布局）；
+- 嵌套的 `workflow-run/.docnexus/` 及 `workflow-run/tmp/duplicate-docnexus/` 旧备份；
+- 能识别的根目录旧 `docnexus/` 安装、旧 Agent 链接与不兼容的内部项目状态。
+
+新版知识输出不含这些旧内部文件，后续重装 / 升级会保留新版 `library/`、`records/` 等知识。工作流的需求文档、其他临时文件和普通同名业务目录保留。清理失败会停止；npm / init 失败返回非零。
+
+已安装项目重新接入：
+
+```bash
+npx @rowansenne/workflow-run upgrade --with-docnexus
+```
 
-* DocNexus 装在 `workflow-run/docnexus/`，以 `workflow-run/` 为项目根运行（`docnexus init --agent none`：它自己不往 `workflow-run/` 里链接 skills、写 `CLAUDE.md`）。
-* 本项目里由 workflow-run 接上：把 `workflow-run/docnexus/skills/*` 相对链接到 `.claude/skills` / `.agents/skills` / `.qwen/skills` / `.codebuddy/skills`，在 `CLAUDE.md` / `AGENTS.md` 写一段说明（概念索引 `@workflow-run/docnexus/CONCEPTS.md`；docnexus 系列 skill 的命令改用 `node <skills>/workflow/scripts/docnexus.mjs` 运行，不用先 `cd`），用自己的标记，不碰手写内容。升级时刷新，卸载时撤掉，`workflow-run/docnexus/` 本身不动。
-* 各 skill 的脚本已按位置处理：`resolve.mjs status` 给出 `docnexus.root` 与 `run`（`node <skills>/workflow/scripts/docnexus.mjs`），`knowledge.mjs` 在那里运行并给出从项目根读正文的路径。
-* `workflow-run/` 是独立文档仓库时，知识库随文档仓库提交，各服务共用；沉淀后的改动和产物一样由你确认后提交（`requirement.mjs pending` 单独列出）。DocNexus 的依赖和检索库（`node_modules/`、`store/`）由 `docnexus/.gitignore` 忽略、不进仓库，各自 `--with-docnexus` 装一次。
+新项目用 `npx @rowansenne/workflow-run --with-docnexus`。离线或本地验证可设 `DOCNEXUS_PKG=/path/to/package-or-source` 指定安装来源；默认从 npm 安装，必须使用支持 format 7 和 `--output-dir` 的版本。
 
 ## CodeGraph 代码图谱与 code-graph skill（可选）
 
@@ -397,8 +445,8 @@ npx @rowansenne/workflow-run uninstall
 | `workflow/scripts/resolve.mjs template <skill> <文件名>` | 判定用哪份模板：已接入 DocNexus 只用知识库，缺失时退出码 2 并给出导入来源；未接入时项目文件优先，其次默认模板 |
 | `workflow/scripts/resolve.mjs profile` | 读项目画像，列出空字段 |
 | `workflow/scripts/resolve.mjs env` | 本机系统与终端（安装时记录在 `profile.local.json`），写终端命令按它来 |
-| `workflow/scripts/docnexus.mjs <参数>` / `--node <脚本> <参数>` | 在 `workflow-run/` 下运行 DocNexus CLI 或它的 node 脚本，不用先 `cd`，各终端写法一样；Windows 上直接用 node 跑 CLI 入口，不经过 `.cmd` |
-| `workflow/scripts/knowledge.mjs <skill> [--match 词] [--limit n] [--query 问题]` | 按 `readFrom` 的分类列出 DocNexus 文档（标题、摘要、路径，不含正文）；`--query` 再在每个分类内 `recall --category`（DocNexus 0.16.0 起），旧版自动退回只列文档并提示。未接入时退出码 2 |
+| `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/resolve.mjs category <skill>` | 该 skill 写入 DocNexus 时的显式分类（画像 `docnexus_categories` 优先，其次 skill.json），输出 `seal_args` 与 `metadata`；未声明时退出码 1 |
 | `workflow/scripts/resolve.mjs status` | `/workflow status` 的能力探测（不输出任何凭据） |
 | `workflow/scripts/resolve.mjs infer-profile` | 按固定规则从构建文件、Makefile、依赖与配置文件、git 推断项目画像草稿，每个字段附依据；不写文件 |
@@ -455,7 +503,8 @@ CI（`.github/workflows/test.yml`）在 push 到 main 和每个 PR 上运行：m
 | `.agents/skills/database-query/references/schema.md` | 表结构速查，补齐后提交 |
 | `workflow-run/docs/requirements/` | 需求产物；独立文档仓库模式下提交到文档仓库 |
 | `workflow-run/feedback/` | 运行反馈，每人一个文件；独立文档仓库模式下提交到文档仓库 |
-| `workflow-run/docnexus/` | DocNexus 工作区与定制的文档模板；依赖和检索库由它自带的 `docnexus/.gitignore` 忽略。独立文档仓库模式下提交到文档仓库 |
+| `.docnexus/project.json`、npm 清单与锁文件 | DocNexus 项目配置与运行依赖版本，随代码提交 |
+| `workflow-run/docnexus/` | DocNexus 知识输出与定制的文档模板。独立文档仓库模式下提交到文档仓库 |
 | `.ignore` | 让代码搜索跳过需求目录（不影响 git） |
 | `.gitignore`、`CLAUDE.md` / `AGENTS.md` | 安装器追加的忽略规则、DocNexus 说明段落 |
 
@@ -688,7 +737,7 @@ npx @rowansenne/workflow-run seed-templates --diff               # 团队改过
 ```
 
 * 只导入 DocNexus 里还没有的、有默认版本的模板（技术方案、上线方案不在内），已有的不覆盖；项目已接入但缺模板时，安装结束会列出缺哪几份。
-* 之后模板随知识库更新：直接编辑 `workflow-run/docnexus/library/templates/...` 后在 `workflow-run/` 下执行 `./docnexus/node_modules/.bin/docnexus document sync --id <id>` 采纳；或者在生成文档后，skill 发现你做了结构性调整时会提议同步回模板（你确认后才写入）。每次变更都记录在 DocNexus 的 timeline 里，可追溯。
+* 之后模板随知识库更新：直接编辑 `workflow-run/docnexus/library/templates/...` 后在业务项目根执行 `./.docnexus/node_modules/.bin/docnexus document sync --id <id>` 采纳；或者在生成文档后，skill 发现你做了结构性调整时会提议同步回模板（你确认后才写入）。每次变更都记录在 DocNexus 的 timeline 里，可追溯。
 * 模板里的 `{{...}}` 是给 agent 的填写提示，DocNexus 原样保存；不要写成单独一行的 `{{fact:...}}`（那是 DocNexus 的事实引用语法）。
 * 以前放在 `workflow-run/templates/` 下的项目模板：接入 DocNexus 后，缺模板时 skill 会把它作为 `import_from` 提议导入知识库；导入后删除这些文件。
 
@@ -719,4 +768,4 @@ node scripts/eval-triggers.mjs --only dev   # 只跑期望为 dev 的用例
 
 * **Qwen Code** 项目级为 `.qwen/skills/`，自动发现。
 
-* **腾讯 WorkBuddy** 读项目工作目录下的 `.codebuddy/`（与 CodeBuddy Code 一致），项目级技能在 `.codebuddy/skills/`，同名时优先于用户级；它也读 `AGENTS.md`。
+* **腾讯 WorkBuddy** 读项目工作目录下的 `.codebuddy/`（与 CodeBuddy Code 一致），项目级技能在 `.codebuddy/skills/`，同名时优先于用户级；它也读 `AGENTS.md`。

package/bin/lib/core.mjs

@@ -6,6 +6,7 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { loadSkills, deriveMeta, withDependencies } from '../skills.mjs';
+export { docnexusRoot, docnexusWorkspace, docnexusInternal, docnexusBinPath as docnexusBin } from '../../workflow/scripts/docnexus-layout.mjs';
 
 export const TPL_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 export const PKG = JSON.parse(fs.readFileSync(path.join(TPL_DIR, 'package.json'), 'utf8'));
@@ -25,20 +26,10 @@ export const SKILLS = META.skills;
 export const USER_FILES = META.userFiles;
 export const DOCNEXUS_PKG = process.env.DOCNEXUS_PKG || '@rowansenne/docnexus';
 export const CODEGRAPH_PKG = process.env.CODEGRAPH_PKG || '@colbymchenry/codegraph@1'; // code-graph skill 按 1.x 的库接口编写
-// 本工具在项目里的唯一目录：需求产物、DocNexus 工作区、项目模板、临时文件都在这里（与 workflow/scripts/requirement.mjs 的 HOME 一致）
+// 工作流产物与 DocNexus 知识输出的父目录；DocNexus 运行环境另在项目根 .docnexus/。
 export const HOME = 'workflow-run';
-// DocNexus 的项目根是 workflow-run/（工作区 workflow-run/docnexus/），CLI 在 workflow-run/docnexus/node_modules/.bin。
-// workflow/scripts/resolve.mjs 的 docnexusRoot / docnexusBin 与此一致
-export const DOCNEXUS_BIN_DIRS = [['docnexus', 'node_modules', '.bin']];
-export const docnexusRoot = (root) => path.resolve(root, HOME);
-export function docnexusBin(root) {
-  const name = IS_WIN ? 'docnexus.cmd' : 'docnexus';
-  const dn = docnexusRoot(root);
-  for (const dir of DOCNEXUS_BIN_DIRS) { const p = path.join(dn, ...dir, name); if (fs.existsSync(p)) return p; }
-  return null;
-}
 // 升级 DocNexus 的命令（在项目根执行；不用 cd / &&，PowerShell 5.1 也能直接运行）
-export const docnexusUpgradeCmd = () => `npm install --prefix ./${HOME}/docnexus --save-exact ${DOCNEXUS_PKG}@latest`;
+export const docnexusUpgradeCmd = () => `npm install --prefix ./.docnexus --save-exact ${DOCNEXUS_PKG}@latest`;
 export const MANIFEST = '.workflow-run.json'; // 安装清单，位于每个安装目录（单一来源时只有 .agents/skills 一份）
 
 // ---------------------------------------------------------------- 输出
@@ -116,9 +107,12 @@ export function timestamp() {
 }
 
 export const INSTALL_BASES = [CANON_DIR, ...Object.values(LINK_ENVS)];
-// 找到本项目的安装清单（单一来源优先；--copy 安装时各目录各有一份）
+// 以最近一次显式安装为准；自动退回拷贝的清单不覆盖单一来源的模式与 skill 选择。
 export function findManifests(root) {
-  return INSTALL_BASES.map((rel) => ({ rel, base: path.join(root, rel), m: readManifest(path.join(root, rel)) })).filter((x) => x.m);
+  const found = INSTALL_BASES.map((rel) => ({ rel, base: path.join(root, rel), m: readManifest(path.join(root, rel)) })).filter((x) => x.m);
+  const primary = found.filter((x) => x.rel === CANON_DIR || x.m.mode === 'copy').reduce((latest, x) =>
+    !latest || (Date.parse(x.m.installedAt) || 0) > (Date.parse(latest.m.installedAt) || 0) ? x : latest, null);
+  return primary ? [primary, ...found.filter((x) => x !== primary)] : found;
 }
 export function cmpVersion(a, b) {
   const pa = String(a).split(/[.-]/).map((x) => parseInt(x, 10) || 0);

package/bin/lib/docnexus.mjs

@@ -4,7 +4,74 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { templateStatus, STATUS_TEXT, TEMPLATES } from '../seed-templates.mjs';
-import { TPL_DIR, IS_WIN, DOCNEXUS_PKG, MANIFEST, PKG, CANON_DIR, step, ok, warn, fail, writeFile, readJson, toPosix, lstat, findManifests, removeLink, docnexusBin, docnexusRoot, HOME } from './core.mjs';
+import { TPL_DIR, IS_WIN, DOCNEXUS_PKG, MANIFEST, PKG, CANON_DIR, step, ok, warn, fail, writeFile, readJson, toPosix, lstat, findManifests, removeLink, docnexusBin, docnexusWorkspace, docnexusInternal, HOME, INSTALL_BASES } from './core.mjs';
+
+import { docnexusConfigured, docnexusConnected } from '../../workflow/scripts/docnexus-layout.mjs';
+export { docnexusConnected } from '../../workflow/scripts/docnexus-layout.mjs';
+
+// 破坏性升级：删除旧知识、运行环境与备份，不迁移、不回退。
+// format 7 的知识输出不含 project.json / npm / skills 等内部文件，重复安装时保留它。
+export function legacyDocNexusPaths(root) {
+  const workspace = docnexusWorkspace(root);
+  const oldOutput = ['project.json', 'package.json', 'node_modules', 'skills', 'schemas', 'drafts', 'store', '.runtime']
+    .some((name) => lstat(path.join(workspace, name)));
+  const marker = readJson(path.join(docnexusInternal(root), 'project.json'));
+  const legacyRoot = path.join(root, 'docnexus');
+  const rootPackage = readJson(path.join(legacyRoot, 'package.json'));
+  const oldRoot = fs.existsSync(path.join(legacyRoot, 'project.json'))
+    || Object.keys(rootPackage?.dependencies ?? {}).some((name) => /(^|\/)docnexus$/.test(name))
+    || (marker?.format_version === 7 && marker.output_dir === '.');
+  return [
+    ...(oldOutput ? [workspace] : []),
+    path.join(root, HOME, '.docnexus'),
+    path.join(root, HOME, 'tmp', 'duplicate-docnexus'),
+    ...(oldRoot ? [legacyRoot] : []),
+    ...INSTALL_BASES.flatMap((base) => ['docnexus', 'docnexus-extract', 'docnexus-ingest', 'docnexus-recall', 'docnexus-library', 'docnexus-maintain']
+      .map((name) => path.join(root, HOME, base, name))),
+  ].filter((dir) => lstat(dir));
+}
+
+export function cleanupLegacyDocNexus(root) {
+  root = path.resolve(root);
+  const obsolete = legacyDocNexusPaths(root);
+  // 目录本身的链接可移除；不能穿过父目录链接删除其他位置的文件。
+  for (const dir of obsolete) {
+    for (let parent = path.dirname(dir); parent !== path.resolve(root); parent = path.dirname(parent)) {
+      if (lstat(parent)?.isSymbolicLink()) fail(`旧 DocNexus 路径的父目录是软链接，停止清理：${parent}`);
+    }
+  }
+  const marker = readJson(path.join(docnexusInternal(root), 'project.json'));
+  const oldSkills = obsolete.map((dir) => path.join(dir, 'skills'));
+  for (const base of INSTALL_BASES) {
+    const dir = path.join(root, base);
+    for (const name of fs.existsSync(dir) ? fs.readdirSync(dir) : []) {
+      const link = path.join(dir, name);
+      if (!lstat(link)?.isSymbolicLink()) continue;
+      const target = path.resolve(dir, fs.readlinkSync(link).replace(/^\\\\\?\\/, ''));
+      if (oldSkills.some((src) => target.startsWith(src + path.sep))) removeLink(link);
+    }
+  }
+  for (const dir of obsolete) {
+    if (!lstat(dir)) continue;
+    if (lstat(dir).isSymbolicLink()) removeLink(dir); else fs.rmSync(dir, { recursive: true, force: true });
+    warn(`破坏性更新：已删除旧版 ${toPosix(path.relative(root, dir))}/（不迁移、不备份）`);
+  }
+  if (marker && !docnexusConfigured(root)) {
+    if (lstat(docnexusInternal(root))?.isSymbolicLink()) removeLink(docnexusInternal(root));
+    else {
+      for (const name of ['project.json', 'skills', 'schemas', 'drafts', 'store', '.runtime', '.docnexus-skills.json']) {
+        fs.rmSync(path.join(docnexusInternal(root), name), { recursive: true, force: true });
+      }
+    }
+    warn('破坏性更新：已清除旧版 .docnexus/ 的项目状态，运行依赖保留供重新初始化');
+  }
+  for (const file of ['CLAUDE.md', 'AGENTS.md', 'QWEN.md']) {
+    dropBlock(path.join(root, HOME, file), CTX_START, CTX_END);
+    dropBlock(path.join(root, HOME, file), '<!-- docnexus:start -->', '<!-- docnexus:end -->');
+    if (obsolete.length || (marker && !docnexusConfigured(root))) dropBlock(path.join(root, file), '<!-- docnexus:start -->', '<!-- docnexus:end -->');
+  }
+  return obsolete;
+}
 
 export function run(cmd, args, cwd, quiet = false) {
   const r = spawnSync(cmd, args, { cwd, stdio: quiet ? ['ignore', 'ignore', 'inherit'] : 'inherit', shell: IS_WIN });
@@ -16,11 +83,10 @@ export function checkNodeForDocNexus() {
   if (spawnSync(IS_WIN ? 'npm.cmd' : 'npm', ['-v'], { stdio: 'ignore', shell: IS_WIN }).status !== 0) fail('--with-docnexus 需要 npm，但未找到。请安装后重试，或去掉 --with-docnexus。');
   ok(`Node v${process.versions.node}`);
 }
-// DocNexus 的 skills（workflow-run/docnexus/skills/*）软链接到本项目的 agent skills 目录。DocNexus 以 workflow-run/ 为项目根、
-// init --agent none 运行，它自己不链接 skills、不写 CLAUDE.md / AGENTS.md（那些会落在 workflow-run/ 里），都由这里接到本项目。
+// DocNexus 的 skills（.docnexus/skills/*）链接到所选 Agent 环境；init --agent none，由本工具统一接入。
 // 已有的同名软链接换成新的；同名目录内容和 DocNexus 的一样（建不了链接时的拷贝）也换掉，否则跳过
 export function linkDocNexusSkills(root, dirs) {
-  const srcRoot = path.join(docnexusRoot(root), 'docnexus', 'skills');
+  const srcRoot = path.join(docnexusInternal(root), 'skills');
   const names = fs.existsSync(srcRoot) ? fs.readdirSync(srcRoot, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name) : [];
   const sameSkill = (dir, name) => { const a = path.join(dir, 'SKILL.md'); const b = path.join(srcRoot, name, 'SKILL.md'); return fs.existsSync(a) && fs.existsSync(b) && fs.readFileSync(a).equals(fs.readFileSync(b)); };
   for (const rel of dirs) {
@@ -42,14 +108,14 @@ export function linkDocNexusSkills(root, dirs) {
   }
 }
 
-// 本项目 agent 的说明段落：概念索引在哪、docnexus 系列 skill 里的「项目根」指 workflow-run/。
+// 本项目 agent 的说明段落：在业务项目根运行，知识路径使用 CLI 返回值。
 // 用自己的标记，不碰 DocNexus 自己的段落
 const CTX_START = '<!-- workflow-run:docnexus:start -->';
 const CTX_END = '<!-- workflow-run:docnexus:end -->';
 // AGENTS.md 由 codex / doubao / workbuddy 共用：命令指向装了 workflow 的那个目录（--copy 只装 workbuddy 时没有 .agents/skills）
 function contextBlock(root, file) {
   const has = (dir) => fs.existsSync(path.join(root, dir, 'workflow', 'scripts', 'docnexus.mjs'));
-  const dir = file === 'CLAUDE.md' ? '.claude/skills' : ['.agents/skills', '.codebuddy/skills'].find(has) ?? '.agents/skills';
+  const dir = file === 'CLAUDE.md' ? '.claude/skills' : file === 'QWEN.md' ? '.qwen/skills' : ['.agents/skills', '.codebuddy/skills'].find(has) ?? '.agents/skills';
   const run = `${dir}/workflow/scripts/docnexus.mjs`;
   const index = file === 'CLAUDE.md' ? `@${HOME}/docnexus/CONCEPTS.md` : `\`${HOME}/docnexus/CONCEPTS.md\`（每个任务开始时读）`;
   return [
@@ -58,7 +124,9 @@ function contextBlock(root, file) {
     '',
     `本项目的 DocNexus 工作区在 \`${HOME}/docnexus/\`，概念索引：${index}`,
     '',
-    `- docnexus 系列 skill 里说的「项目根」指 \`${HOME}\`。其中的命令在本项目根这样运行，不用先 cd，任何终端写法都一样：\`./docnexus/node_modules/.bin/docnexus <参数>\` → \`node ${run} <参数>\`；\`node docnexus/skills/<…>.mjs <参数>\` → \`node ${run} --node docnexus/skills/<…>.mjs <参数>\`。参数里的 \`docnexus/library/<path>\`、草稿等路径照旧相对 \`${HOME}\`。`,
+    `- 运行环境、skills、草稿与检索索引在业务项目根的 \`.docnexus/\`；\`init --output-dir ${HOME}\` 将知识输出到 \`${HOME}/docnexus/\`，配置保存在 \`.docnexus/project.json\`。`,
+    `- docnexus 系列 skill 的「项目根」就是业务项目根。命令用 \`./.docnexus/node_modules/.bin/docnexus <参数>\` 或 \`node ${run} <参数>\`；辅助脚本用 \`node ${run} --node .docnexus/skills/<…>.mjs <参数>\`。直接使用 status、draft、document 返回的路径，不再添加或剥离 workflow-run/ 前缀。`,
+    '- 找不到运行环境或配置时，用 workflow-run 安装 / 升级修复；不要在 workflow-run/ 里安装、初始化第二份，也不要调用根目录旧 docnexus/ 或全局 CLI。',
     '- 规划或改代码前，看任务是否涉及概念索引里的概念，或已记录的决定、组件、约定；涉及就用 `docnexus-recall` skill 查，并以查到的内容为依据。',
     '- 任务产生值得保留的决定或知识时，提出用 `docnexus` skill 沉淀；没有用户同意不写入。',
     CTX_END,
@@ -86,14 +154,14 @@ export function writeDocNexusContext(root, files) {
     if (next !== cur) { fs.writeFileSync(f, next); ok(`${file} 已写入 DocNexus 段落（工作区在 ${HOME}/docnexus/）`); }
   }
 }
-export const removeDocNexusContext = (root) => ['CLAUDE.md', 'AGENTS.md'].filter((file) => dropBlock(path.join(root, file), CTX_START, CTX_END));
+export const removeDocNexusContext = (root) => ['CLAUDE.md', 'AGENTS.md', 'QWEN.md'].filter((file) => dropBlock(path.join(root, file), CTX_START, CTX_END));
 
 // 选择的环境 → 本项目里要链接 DocNexus skills 的目录与要写段落的文件
 function agentTargets(sel) {
   const dirs = new Set(); const files = new Set();
   if (sel.includes('claude')) { dirs.add(path.join('.claude', 'skills')); files.add('CLAUDE.md'); }
   if (sel.includes('codex') || sel.includes('doubao')) { dirs.add(CANON_DIR); files.add('AGENTS.md'); }
-  if (sel.includes('qwen')) dirs.add(path.join('.qwen', 'skills'));
+  if (sel.includes('qwen')) { dirs.add(path.join('.qwen', 'skills')); files.add('QWEN.md'); }
   // WorkBuddy 读项目的 AGENTS.md（与 CODEBUDDY.md 并存）
   if (sel.includes('workbuddy')) { dirs.add(path.join('.codebuddy', 'skills')); files.add('AGENTS.md'); }
   return { dirs: [...dirs], files: [...files] };
@@ -101,7 +169,7 @@ function agentTargets(sel) {
 
 // 升级 / 重装都刷新本项目的链接与段落（DocNexus 新增或改名 skill 后跟上）
 export function refreshDocNexusLinks(root, sel) {
-  if (!fs.existsSync(path.join(docnexusRoot(root), 'docnexus', 'project.json'))) return false;
+  if (!docnexusConfigured(root)) return false;
   const t = agentTargets(sel);
   linkDocNexusSkills(root, t.dirs);
   writeDocNexusContext(root, t.files);
@@ -109,45 +177,24 @@ export function refreshDocNexusLinks(root, sel) {
 }
 
 export function setupDocNexus(root, sel) {
-  const dn = docnexusRoot(root);
-  const npmArgs = ['install', '--prefix', './docnexus', '--save-exact', DOCNEXUS_PKG];
-  step(`接入 DocNexus（位置 ${HOME}/docnexus/；npm ${npmArgs.join(' ')}；docnexus init --agent none）`);
-  fs.mkdirSync(dn, { recursive: true });
-  if (!run(IS_WIN ? 'npm.cmd' : 'npm', npmArgs, dn)) { warn('npm 安装 DocNexus 失败，已跳过 DocNexus 接入（skills 已正常安装）'); return 'failed'; }
+  const npmArgs = ['install', '--prefix', './.docnexus', '--save-exact', DOCNEXUS_PKG];
+  step(`接入 DocNexus（运行环境 .docnexus/；知识输出 ${HOME}/docnexus/）`);
+  if (!run(IS_WIN ? 'npm.cmd' : 'npm', npmArgs, root)) { warn('npm 安装 DocNexus 失败，已跳过 DocNexus 接入（skills 已正常安装）'); return 'failed'; }
   const bin = docnexusBin(root);
-  if (!bin) { warn(`安装后未找到 ${HOME}/docnexus/node_modules/.bin/docnexus，已跳过 DocNexus 接入`); return 'failed'; }
-  const rel = `./${path.relative(dn, bin).split(path.sep).join('/')}`;
-  if (!run(bin, ['init', '--agent', 'none'], dn, true)) {
-    warn(`docnexus init 失败，已跳过 DocNexus 接入（可在 ${HOME}/ 下手动执行 ${rel} init --agent none）`);
+  if (!bin) { warn('安装后未找到 .docnexus/node_modules/.bin/docnexus，已跳过 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';
   }
-  ok(`docnexus init 完成：${HOME}/docnexus/ 工作区 + skills（${HOME}/docnexus/skills）`);
+  if (!docnexusConfigured(root)) { warn('DocNexus 未生成 output_dir=workflow-run 的 format 7 配置，接入失败'); return 'failed'; }
   const t = agentTargets(sel);
   linkDocNexusSkills(root, t.dirs);
   writeDocNexusContext(root, t.files);
   if (sel.includes('doubao')) ok('doubao 与 codex 共用 .agents/skills，按 codex 接入');
-  if (sel.includes('qwen')) warn('qwen：不会写 QWEN.md；需要自动召回时可在 QWEN.md 引用 AGENTS.md 中的 DocNexus 段落，或在 .qwen/settings.json 的 context.fileName 加入 AGENTS.md');
+  ok(`DocNexus 已初始化：.docnexus/ 运行环境，${HOME}/docnexus/ 知识输出`);
   return 'ok';
 }
 
-// 已装 DocNexus 是否支持调用方显式分类（draft seal --category，0.14.0 之后）。旧版会静默忽略该参数，
-// skill 的写入仍靠 metadata.category 落到同一分类，只是不会记成调用方指定；这里只用于提示升级
-function docnexusHelp(root) {
-  const bin = docnexusBin(root);
-  if (!bin) return null;
-  const r = spawnSync(bin, ['--help'], { cwd: docnexusRoot(root), encoding: 'utf8', shell: IS_WIN });
-  return `${r.stdout}${r.stderr}`;
-}
-export function docnexusSupportsCategory(root) {
-  const h = docnexusHelp(root);
-  return h === null ? null : /--category-reason/.test(h);
-}
-// recall --category（0.16.0 起）：knowledge.mjs --query 按分类检索；旧版退回不带分类的 recall
-export function docnexusSupportsRecallCategory(root) {
-  const h = docnexusHelp(root);
-  return h === null ? null : /recall[^\n]*--category/.test(h);
-}
-
 export function templateRecords(root) { return findManifests(root)[0]?.m.templates ?? {}; }
 // 已安装的 skill（有安装清单时以清单为准），模板导入与状态只针对它们
 export function installedSkills(root) { const m = findManifests(root)[0]?.m; return m ? Object.keys(m.skills ?? {}) : undefined; }
@@ -165,9 +212,6 @@ export function reportTemplateStatus(root, say = warn) {
   return list.length > 0;
 }
 
-export function docnexusConnected(root) {
-  return fs.existsSync(path.join(docnexusRoot(root), 'docnexus', 'project.json')) && docnexusBin(root) !== null;
-}
 
 // 团队改过的模板（customized / untracked）与当前默认模板的差异：只读，不写 DocNexus。
 // 只有导入时的哈希、没有导入时的原文，做不了三方合并，所以差异里同时包含团队自己的改动和默认模板的新改动。返回打印了几份

package/bin/lib/docsrepo.mjs

@@ -11,7 +11,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { HOME, step, ok, warn, toPosix, findManifests, docnexusBin, docnexusRoot } from './core.mjs';
+import { HOME, step, ok, warn, toPosix, findManifests, docnexusBin } from './core.mjs';
 import { updateGitignore, excludeHomeTmp, reportMigration } from './install.mjs';
 import { refreshDocNexusLinks } from './docnexus.mjs';
 import { layout, setConfig, artifactsConfig, suggestProject, migrateLayout } from '../../workflow/scripts/requirement.mjs';
@@ -102,7 +102,7 @@ export function docsRepo(root, { url, project }) {
   const c = setConfig(root, { project: name });
   ok(`本项目在文档仓库里的项目名：${c.artifacts.project}（写在 ${c.file}，随代码提交，团队共用）`);
 
-  if (fs.existsSync(path.join(docnexusRoot(root), 'docnexus', 'project.json'))) {
+  if (fs.existsSync(path.join(root, HOME, 'docnexus'))) {
     const envs = findManifests(root)[0]?.m.envs ?? [];
     if (docnexusBin(root)) refreshDocNexusLinks(root, envs);
     else warn(`文档仓库里有 DocNexus，本机还没装它的依赖：运行 npx @rowansenne/workflow-run upgrade --with-docnexus`);

package/bin/lib/doctor.mjs

@@ -3,8 +3,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { PKG, CANON_DIR, INSTALL_BASES, LINK_ENVS, HOME, DOCNEXUS_PKG, docnexusUpgradeCmd, SKILLS, step, ok, warn, fail, toPosix, fileHash, readManifest, lstat, findManifests, cmpVersion } from './core.mjs';
-import { reportTemplateStatus, docnexusSupportsCategory, docnexusSupportsRecallCategory } from './docnexus.mjs';
+import { PKG, CANON_DIR, INSTALL_BASES, LINK_ENVS, HOME, SKILLS, step, ok, warn, fail, toPosix, fileHash, readManifest, lstat, findManifests, cmpVersion } from './core.mjs';
+import { reportTemplateStatus, legacyDocNexusPaths } from './docnexus.mjs';
 import { codegraphVersion } from './codegraph.mjs';
 import { legacyRequirements } from '../../workflow/scripts/requirement.mjs';
 
@@ -33,6 +33,8 @@ export function doctor(root, offline) {
   const [maj] = process.versions.node.split('.').map(Number);
   if (maj < 22) bad(`Node v${process.versions.node} 低于 22（workflow-run 只在 Node 22 / 24 上测试；18、20 已停止维护）`); else ok(`Node v${process.versions.node}`);
 
+  for (const dir of legacyDocNexusPaths(root)) bad(`发现旧版 DocNexus：${toPosix(path.relative(root, dir))}/；运行 npx @rowansenne/workflow-run upgrade --with-docnexus 强制清理并重新接入`);
+
   const found = findManifests(root);
   if (!found.length) { bad('未找到安装清单：本项目还没用 workflow-run 安装过'); return 1; }
   const m = found[0].m;
@@ -90,11 +92,11 @@ export function doctor(root, offline) {
     if (st.profile.ok) ok('项目画像已填写'); else meh(`项目画像未完成（空字段：${st.profile.empty.join('、')}）：运行 /workflow profile`);
     if (st.wiki.ok) ok('wiki 已配置'); else console.log('    --  wiki 未配置（可选；也可能通过 wiki MCP 提供）');
     if (st.docnexus.ok) {
-      // DocNexus 以 workflow-run/ 为项目根：本项目要有 docnexus skill 的链接和 CLAUDE.md / AGENTS.md 段落，agent 才知道去哪里找
+      // 运行环境在 .docnexus/，所有 Agent 都从业务项目根使用配置的知识输出。
       const linked = INSTALL_BASES.some((b) => lstat(path.join(root, b, 'docnexus-recall'))?.isSymbolicLink());
-      const ctx = ['CLAUDE.md', 'AGENTS.md'].some((f) => { try { return fs.readFileSync(path.join(root, f), 'utf8').includes('workflow-run:docnexus:start'); } catch { return false; } });
-      if (linked && ctx) ok(`DocNexus 在 ${HOME}/docnexus/，本项目已链接它的 skills 并写入段落`);
-      else meh(`DocNexus 在 ${HOME}/docnexus/，但本项目${linked ? '' : '缺少 docnexus skill 链接'}${!linked && !ctx ? '、' : ''}${ctx ? '' : '缺少 CLAUDE.md / AGENTS.md 里的 DocNexus 段落'}：运行 npx @rowansenne/workflow-run upgrade`);
+      const ctx = ['CLAUDE.md', 'AGENTS.md', 'QWEN.md'].some((f) => { try { return fs.readFileSync(path.join(root, f), 'utf8').includes('workflow-run:docnexus:start'); } catch { return false; } });
+      if (linked && ctx) ok(`DocNexus 运行环境 .docnexus/，知识输出 ${HOME}/docnexus/，已接入 Agent`);
+      else meh(`DocNexus 已配置 output_dir=${HOME}，但本项目${linked ? '' : '缺少 docnexus skill 链接'}${!linked && !ctx ? '、' : ''}${ctx ? '' : '缺少 Agent 上下文段落'}：运行 npx @rowansenne/workflow-run upgrade`);
     }
     // 产出目录：都在 workflow-run/
     const mode = st.artifacts?.mode === 'repo' ? `独立文档仓库（${HOME}/ 自己是 git 仓库）` : '随项目提交';
@@ -104,11 +106,8 @@ export function doctor(root, offline) {
     if (legacy.length) meh(`${legacy.length} 个需求还是旧结构（文件直接放在 docs/requirements/<需求>/ 下）：运行 npx @rowansenne/workflow-run upgrade 迁到 <需求>/<项目名>/`);
     if (st.docnexus.ok) {
       if (!reportTemplateStatus(root, meh)) ok('DocNexus 已接入，文档模板齐全且与默认模板同步（或为团队定制版）');
-      if (docnexusSupportsCategory(root) === false) meh(`已装的 DocNexus 不支持 draft seal --category：各 skill 的分类只能经 metadata.category 写入，不记为调用方指定。升级：${docnexusUpgradeCmd()}`);
-      else ok('DocNexus 支持调用方显式分类（draft seal --category）');
-      if (docnexusSupportsRecallCategory(root) === false) meh(`已装的 DocNexus 不支持 recall --category：knowledge.mjs --query 只列文档，skill 改用不带分类的 recall。升级：${docnexusUpgradeCmd()}`);
-      else ok('DocNexus 支持按分类检索（recall --category）');
-    } else console.log('    --  DocNexus 未接入（可选；未接入时只能用 skills 自带的默认模板，不能修改）');
+    } 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 自带的默认模板，不能修改）');
     // 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）`);

package/bin/lib/install.mjs

@@ -2,8 +2,9 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { TPL_DIR, PKG, CANON_DIR, INSTALL_BASES, SKILLS, SKILL_LIST, USER_FILES, MANIFEST, ok, warn, readJson, walk, toPosix, sameFile, writeFile, render, sha256, fileHash, readManifest, removeEmptyDirs, lstat, timestamp, removeLink, HOME } from './core.mjs';
+import { TPL_DIR, PKG, CANON_DIR, INSTALL_BASES, SKILLS, SKILL_LIST, USER_FILES, MANIFEST, ok, warn, fail, readJson, walk, toPosix, sameFile, writeFile, render, sha256, fileHash, readManifest, removeEmptyDirs, lstat, timestamp, removeLink, HOME } from './core.mjs';
 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 { rotate as rotateFeedback, ensureUnionMerge } from '../../workflow/scripts/feedback.mjs';
@@ -66,6 +67,19 @@ export async function installSkills(base, db, ctx) {
   for (const skill of selected) {
     const srcDir = path.join(TPL_DIR, skill);
     const dstDir = path.join(base, skill);
+    // --copy 重装已有链接时先解除共享关系，避免写穿链接、仍留下无法被部分宿主发现的链接目录。
+    if (ctx.mode !== 'symlink' && lstat(dstDir)?.isSymbolicLink()) {
+      if (!linkPointsTo(dstDir, path.resolve(ctx.root, CANON_DIR, skill))) fail(`${dstDir} 指向其他位置，不能改为独立拷贝；请先手动处理该链接。`);
+      const tmp = fs.mkdtempSync(path.join(base, '.workflow-run-copy-'));
+      const copy = path.join(tmp, skill);
+      try {
+        if (fs.existsSync(dstDir)) fs.cpSync(dstDir, copy, { recursive: true, dereference: true });
+        else fs.mkdirSync(copy);
+        removeLink(dstDir);
+        fs.renameSync(copy, dstDir);
+      } finally { fs.rmSync(tmp, { recursive: true, force: true }); }
+      ok(`${toPosix(path.relative(ctx.root, dstDir))} 已由软链接改为独立拷贝（已有配置保留）`);
+    }
     const prevSkill = prev?.skills?.[skill];
     const entry = { files: {}, userFiles: {} };
     const notes = [];
@@ -209,7 +223,7 @@ export function linkSkills(root, envName, rel, skills = SKILLS) {
 
 // ---------------------------------------------------------------- 4. .gitignore 保护
 // workflow-run/ 是独立文档仓库时整个忽略（它自己提交）；否则只忽略其中的临时文件。
-// DocNexus 的依赖与检索库由它自带的 docnexus/.gitignore 忽略，随工作区走，两种模式都不用这里加规则
+// DocNexus 的运行依赖、检索库和草稿由项目根的 .docnexus/.gitignore 忽略。
 export function updateGitignore(root, withCodeGraph = false) {
   const gi = path.join(root, '.gitignore');
   const rules = ['**/database-query/config.json', '**/wiki-config.json', '**/workflow/profile.local.json', homeIsRepo(root) ? `/${HOME}/` : `/${TMP_DIR}/`];

package/bin/lib/uninstall.mjs

@@ -2,7 +2,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, docnexusRoot } from './core.mjs';
+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';
 
 // 软链接是否指向 absTarget（按解析后的绝对路径比较，兼容 Windows 上 readlink 返回的 \\?\ 前缀）
@@ -37,10 +37,9 @@ export function uninstall(root) {
     if (n) ok(`已移除 ${toPosix(rel)} 下 ${n} 个指向 ${toPosix(CANON_DIR)} 的软链接`);
   }
 
-  // 1b. 本工具接进来的 DocNexus：指向 workflow-run/docnexus/skills 的链接、CLAUDE.md / AGENTS.md 里的段落。
-  //     workflow-run/ 里的东西（产物、DocNexus 工作区、项目模板）是项目数据，不删
+  // 1b. 移除指向 .docnexus/skills 的入口及上下文；运行环境和知识输出保留。
   {
-    const src = path.join(docnexusRoot(root), 'docnexus', 'skills');
+    const src = path.join(docnexusInternal(root), 'skills');
     let n = 0;
     for (const rel of bases) {
       const dir = path.join(root, rel);
@@ -50,7 +49,7 @@ export function uninstall(root) {
       }
     }
     const files = removeDocNexusContext(root);
-    if (n || files.length) ok(`已移除指向 ${toPosix(path.relative(root, src))} 的 ${n} 个 DocNexus skill 链接${files.length ? `，以及 ${files.join('、')} 里的 DocNexus 段落` : ''}（workflow-run/docnexus/ 本身不动）`);
+    if (n || files.length) ok(`已移除指向 ${toPosix(path.relative(root, src))} 的 ${n} 个 DocNexus skill 链接${files.length ? `，以及 ${files.join('、')} 里的 DocNexus 段落` : ''}（.docnexus/ 运行环境与 workflow-run/docnexus/ 知识输出保留）`);
   }
 
   // 2. 各安装目录：按清单删除模板文件；用户配置与手改过的模板文件先备份
@@ -90,6 +89,6 @@ export function uninstall(root) {
     for (const f of backedUp) console.log(`      ${f}`);
   }
   for (const d of leftovers) warn(`${d} 中有不在清单里的文件，已保留该目录`);
-  console.log('.gitignore 中追加的规则未移除，如不再需要可手动删除。workflow-run/（需求产物、DocNexus 工作区、项目模板）是项目数据，没有删除。');
+  console.log('.gitignore 中追加的规则未移除，如不再需要可手动删除。.docnexus/ 运行环境及 workflow-run/（需求产物、DocNexus 知识、项目模板）没有删除。');
   return 0;
 }

package/bin/seed-templates.mjs

@@ -16,7 +16,8 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { loadSkills, deriveMeta, TEMPLATE_CATEGORY, TEMPLATE_CATEGORY_REASON } from './skills.mjs';
-import { docnexusBin, docnexusRoot } from './lib/core.mjs';
+import { docnexusBin, docnexusRoot, docnexusWorkspace } from './lib/core.mjs';
+import { docnexusConnected } from '../workflow/scripts/docnexus-layout.mjs';
 
 // 模板清单来自各 skill 的 skill.json（templates 字段）。没有 src 的（技术方案、上线方案）不随 skills 提供默认版本，
 // 由用户第一次使用时按样例创建，不在导入与版本跟踪之列
@@ -25,8 +26,8 @@ export { TEMPLATE_CATEGORY };
 
 const IS_WIN = process.platform === 'win32';
 const sha256 = (s) => crypto.createHash('sha256').update(s).digest('hex');
-// DocNexus 以 workflow-run/ 为项目根：命令在那里运行，草稿与知识库路径也相对那里
-const binPath = (root) => docnexusBin(root) ?? path.join(docnexusRoot(root), 'docnexus', 'node_modules', '.bin', IS_WIN ? 'docnexus.cmd' : 'docnexus');
+// CLI 在业务项目根运行，草稿与知识路径按返回值使用。
+const binPath = (root) => docnexusBin(root);
 
 function docnexus(root, args) {
   const r = spawnSync(binPath(root), args, { cwd: docnexusRoot(root), encoding: 'utf8', shell: IS_WIN, maxBuffer: 64 * 1024 * 1024 });
@@ -36,16 +37,16 @@ function docnexus(root, args) {
 }
 
 function requireDocNexus(root) {
-  if (!fs.existsSync(path.join(docnexusRoot(root), 'docnexus', 'project.json')) || !docnexusBin(root)) {
-    throw new Error('未检测到 DocNexus（需要 workflow-run/docnexus/project.json 与 workflow-run/docnexus/node_modules/.bin/docnexus）。先加 --with-docnexus 接入。');
+  if (!docnexusConnected(root)) {
+    throw new Error('未检测到新版 DocNexus（需要 .docnexus/project.json 的 output_dir=workflow-run 与 .docnexus/node_modules/.bin/docnexus）。先加 --with-docnexus 接入。');
   }
 }
 
-const libFile = (root, t) => path.join(docnexusRoot(root), 'docnexus', 'library', t.file);
+const libFile = (root, t) => path.join(docnexusWorkspace(root), 'library', t.file);
 const defaultContent = (tplDir, t) => fs.readFileSync(path.join(tplDir, t.src), 'utf8');
 
 // 写草稿并提交；baseVersion 为 'new'（新建）或已有记录的 record_version（更新，带 --replace）。成功返回 null，失败返回错误信息
-// 分类以调用方显式分类封存（--category doc-template），不走模型分类；不支持该参数的旧版 DocNexus 会忽略它，仍按 metadata.category 入库
+// 分类以调用方显式分类封存（--category doc-template），不走模型分类。
 function writeDraft(root, t, content, metadata, baseVersion) {
   const draft = docnexus(root, ['draft', 'new', '--slug', `template-${t.skill}`]);
   if (!draft.ok || !draft.json?.artifacts) return draft.err || 'draft new 失败';

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` 自检，再请用户确认。
 
@@ -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.23.0",
+  "version": "0.24.1",
   "description": "项目级 Agent Skills 一键初始化：workflow / dev / project-review / code-graph / database-query / md-to-wiki / 技术与上线方案生成",
   "keywords": [
     "agent-skills",

package/project-review/SKILL.md.tpl

@@ -12,7 +12,7 @@ description: "Review source code (any language; Java/Spring, Go, TypeScript, Pyt
    - **标准**（默认）：检查清单全部维度，**风格类（清单「一致性 / 风格」一节）不查**；「优化建议（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（上线时会被漏掉）。
@@ -32,7 +32,7 @@ description: "Review source code (any language; Java/Spring, Go, TypeScript, Pyt
    结果：「成立」在报告「复核」列标「✅」；「可能成立」标「⚠」；「不成立」从问题表里删掉（独立复核否掉的，在「未覆盖与待确认」里记一句「复核排除 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`。只写过程，不写代码和业务名词；报错就提一句，不影响交付。
 

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>；未沉淀写「未沉淀」，未接入写「未接入」}}
 
 ## 结论摘要 *
 

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/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;
 }
 

package/workflow/scripts/resolve.mjs

@@ -18,6 +18,8 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { inferProfile } from './infer-profile.mjs';
 import { layout, HOME, TEMPLATES_DIR } from './requirement.mjs';
+import { docnexusWorkspace, docnexusConnected, docnexusBinPath } from './docnexus-layout.mjs';
+export { docnexusRoot, docnexusWorkspace, docnexusConnected } from './docnexus-layout.mjs';
 
 const SKILLS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 const PROFILE_FIELDS = ['main_branch', 'build', 'test', 'test_single', 'lint', 'config_center', 'deploy.platform', 'deploy.regions', 'job_annotation'];
@@ -37,19 +39,13 @@ function skillMetas() {
 
 export const skillMeta = (name) => skillMetas().find((m) => m.name === name);
 
-// DocNexus 的项目根：workflow-run/（工作区在 workflow-run/docnexus/），DocNexus 的命令都在这个目录下运行。bin/lib/core.mjs 的 docnexusRoot 与此一致
-export const docnexusRoot = (root) => path.resolve(root, HOME);
-
-// DocNexus CLI 的位置（相对项目根）：workflow-run/docnexus/node_modules/.bin；没有返回 null。bin/lib/core.mjs 的 docnexusBin 与此一致
-export const DOCNEXUS_BIN_DIRS = [['docnexus', 'node_modules', '.bin']];
+// CLI 位于项目根的 .docnexus/，对 Agent 返回项目相对路径。
 export function docnexusBin(root) {
-  const name = process.platform === 'win32' ? 'docnexus.cmd' : 'docnexus';
-  const dn = docnexusRoot(root);
-  for (const dir of DOCNEXUS_BIN_DIRS) if (fs.existsSync(path.join(dn, ...dir, name))) return path.relative(path.resolve(root), path.join(dn, ...dir, name));
-  return null;
+  const bin = docnexusBinPath(root);
+  return bin ? path.relative(path.resolve(root), bin) : null;
 }
-// 给 agent 的命令写法（相对项目根）：./workflow-run/docnexus/...
-const cmdPath = (p) => { const s = p.split(path.sep).join('/'); return s.startsWith('.') ? s : `./${s}`; };
+// 给 agent 的命令写法（相对项目根）：./.docnexus/...
+const cmdPath = (p) => { const s = p.split(path.sep).join('/'); return s.startsWith('./') || s.startsWith('../') ? s : `./${s}`; };
 
 // CodeGraph 代码图谱：本项目建过索引（.codegraph/）且 codegraph 命令可用。索引是否建立由用户决定，skill 不自行 codegraph init
 export function codegraphStatus(root) {
@@ -62,16 +58,12 @@ export function codegraphStatus(root) {
   };
 }
 
-export function docnexusConnected(root) {
-  return fs.existsSync(path.join(docnexusRoot(root), 'docnexus', 'project.json')) && docnexusBin(root) !== null;
-}
-
 export function resolveTemplate(root, skill, id) {
   const meta = skillMeta(skill);
   if (!meta) return { ok: false, error: 'unknown', message: `skill「${skill}」没有安装（${rel(root, SKILLS_DIR)} 下找不到 ${skill}/skill.json）；重跑安装并在 --skills 里带上它` };
   const t = meta.templates.find((x) => x.id === id);
   if (!t) return { ok: false, error: 'unknown', message: `skill「${skill}」没有登记模板「${id}」（见 ${skill}/skill.json 的 templates）` };
-  const lib = path.join(docnexusRoot(root), 'docnexus', 'library', 'templates', skill, id);
+  const lib = path.join(docnexusWorkspace(root), 'library', 'templates', skill, id);
   const project = path.join(root, TEMPLATES_DIR, skill, id);
   // 没有 src 的模板（技术方案、上线方案）不随 skills 提供，缺失时按「创建模板」由用户给样例生成
   const builtin = t.src ? path.join(SKILLS_DIR, skill, t.src.replace(/\.tpl$/, '')) : null;
@@ -185,8 +177,11 @@ export function status(root) {
       ok: dn,
       // 调用 DocNexus CLI 时用这个路径（在项目根执行）
       bin: dn ? cmdPath(docnexusBin(root)) : null,
-      // DocNexus 的项目根（相对本项目）：docnexus 系列 skill 里的路径（docnexus/library/<path>、草稿）都相对这个目录
-      root: HOME,
+      // CLI、草稿及返回的文档路径均相对业务项目根。
+      root: '.',
+      internal: '.docnexus',
+      workspace: `${HOME}/docnexus`,
+      output_dir: HOME,
       // 运行 DocNexus 命令的写法（在项目根执行，任何终端都一样）：后面接原命令的参数；node 脚本前加 --node
       run: `node ${(rel(root, path.join(SKILLS_DIR, 'workflow', 'scripts', 'docnexus.mjs')))}`,
       missing_templates: dn ? templates.filter((t) => !t.ok && !t.on_demand).map((t) => t.expected) : [],