@rowansenne/workflow-run 0.20.0 → 0.21.1

package/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 ## [Unreleased]
 
+## [0.21.1] - 2026-10-18
+
+### 修复
+- 提示里的命令改成完整的 `npx @rowansenne/workflow-run <子命令>`（如 `seed-templates --update`、`upgrade`）：之前写的是 `workflow-run ...`，用 npx 安装、没有全局安装时会报命令找不到。
+
+## [0.21.0] - 2026-10-18
+
+### 变更（破坏性）
+- **默认模板只读，定制模板只放 DocNexus**：skills 自带的模板不能改；修改或新建模板一律写进 DocNexus 知识库，便于团队共享（每次变更有 timeline）。`workflow-run/templates/` 下的项目模板不再生效，`resolve.mjs` 输出 `stale_project_file`，`doctor` 提示导入知识库后删除；接入 DocNexus 后缺模板时仍把它作为 `import_from` 提议导入。
+- 未接入 DocNexus 时：只用默认模板；`template.mjs draft` / `save` 退出码 2、输出 `need_docnexus: true`，提示先 `--with-docnexus` 接入。技术方案、上线方案没有默认模板，`resolve.mjs template` 同样返回 `need_docnexus`，要先接入 DocNexus 才能创建模板和生成文档；`resolve.mjs status` 新增 `templates_need_docnexus`。
+- `template.mjs save` 不再写项目文件、不再备份到 `workflow-run/tmp/template-backup/`，只给出写入知识库的 capture 指引；撤销按 DocNexus 的 timeline 恢复。
+
 ## [0.20.0] - 2026-10-18
 
 ### 变更
@@ -260,7 +272,8 @@
 - 安装器改为单一 Node 实现，`init-skills.sh` / `init-skills.ps1` 只是薄封装。
 - `code-review` 改名为 `project-review`，升级时自动清理旧名。
 
-[Unreleased]: https://github.com/guilianerde/skills-init/compare/v0.20.0...HEAD
+[Unreleased]: https://github.com/guilianerde/skills-init/compare/v0.21.0...HEAD
+[0.21.0]: https://github.com/guilianerde/skills-init/compare/v0.20.0...v0.21.0
 [0.20.0]: https://github.com/guilianerde/skills-init/compare/v0.19.0...v0.20.0
 [0.19.0]: https://github.com/guilianerde/skills-init/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/guilianerde/skills-init/compare/v0.17.0...v0.18.0

package/README.md

@@ -122,7 +122,7 @@ npx @rowansenne/workflow-run docs-repo git@git.example.com:team/team-docs.git
 /workflow report     # 本地效果报告（也可以直接运行 npx @rowansenne/workflow-run report）
 ```
 
-**效果报告**（`/workflow report` 或 `workflow-run report [--since YYYY-MM-DD] [--all-branches] [--json]`）只读统计 `workflow-run/docs/requirements/` 下已落盘的产物，不上报、不另存记录，用来回答「用了以后有没有更好」。默认只看工作区；产物随特性分支提交、还没合并时加 `--all-branches`，用 git 只读扫描所有本地分支（同一路径以工作区为准）。统计内容：
+**效果报告**（`/workflow report` 或 `npx @rowansenne/workflow-run report [--since YYYY-MM-DD] [--all-branches] [--json]`）只读统计 `workflow-run/docs/requirements/` 下已落盘的产物，不上报、不另存记录，用来回答「用了以后有没有更好」。默认只看工作区；产物随特性分支提交、还没合并时加 `--all-branches`，用 git 只读扫描所有本地分支（同一路径以工作区为准）。统计内容：
 
 * 审查：各级别发现条数、严重问题复核通过率、复审时上次问题的修复率；
 * 交付：功能 / 缺陷、S / M / L、开工前经需求澄清确认的决定条数、带「未验证项」的交付；
@@ -276,7 +276,7 @@ dev、project-review、技术方案、上线方案都在对应环节调用它：
 
 ## 重跑与升级
 
-可以放心重复执行 init 来升级模板；只想按原来的环境升级时用 `workflow-run upgrade`，不用再选一遍：
+可以放心重复执行 init 来升级模板；只想按原来的环境升级时用 `npx @rowansenne/workflow-run upgrade`，不用再选一遍：
 
 * `SKILL.md`、`references/checklist.md`、`template.md`、脚本等**模板文件会被更新**；但被你**手动改过**的模板文件不会被静默覆盖（见下方「安装清单」）；
 * 新版本模板里已删除的文件会被清理；你改过的不删，保留并在结尾提示；
@@ -315,7 +315,7 @@ mv .agents/skills/.skills-init.json .agents/skills/.workflow-run.json
 | 清单里有、新版里已没有 | 没改过直接删除；改过的备份后删除 |
 
 * 这样 `SKILL.md`、`skill.json`、脚本始终是同一个版本，不会出现「新 SKILL.md 配旧 skill.json」的混搭。
-* 项目自己的定制不要改 skills 目录里的文件，放到不会被覆盖的地方：项目事实和约定写 `workflow/profile.json`（约定写 `notes`），文档结构用 `workflow-run/templates/<skill>/` 或 DocNexus 里的模板，通用规则写 `CLAUDE.md` / `AGENTS.md`。
+* 项目自己的定制不要改 skills 目录里的文件，放到不会被覆盖的地方：项目事实和约定写 `workflow/profile.json`（约定写 `notes`），文档模板只能在 DocNexus 里定制（skills 自带的默认模板只读），通用规则写 `CLAUDE.md` / `AGENTS.md`。
 * 需要找回手改内容时到备份目录里取。
 
 ### 卸载
@@ -390,11 +390,11 @@ npx @rowansenne/workflow-run uninstall
 | `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`、`workflow-run view`）：读需求目录里的产物，生成单个 HTML，按需求列出各阶段、审查记录（各级别数量、复核、与上次对比）、交付记录、沉淀到的知识文档，正文直接渲染；顶部「知识文档」列出每篇知识文档来自哪个需求、哪份产物；数据内嵌，只读、不联网，默认写到 `workflow-run/tmp/view/index.html` |
+| `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/report.mjs [--since d] [--all-branches] [--json]` | 本地效果报告（`/workflow report`、`workflow-run report`）：审查发现与修复率、复核率、需求澄清、沉淀率、知识引用、各分支链路 |
+| `workflow/scripts/report.mjs [--since d] [--all-branches] [--json]` | 本地效果报告（`/workflow report`、`npx @rowansenne/workflow-run report`）：审查发现与修复率、复核率、需求澄清、沉淀率、知识引用、各分支链路 |
 | `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 时 `save` 给出 capture 指引，不直接写知识库 |
+| `workflow/scripts/template.mjs list / draft / check / save <模板>` | 修改 / 创建模板（`/workflow template`）：把当前模板复制成草稿（或 `--from <样例>` 抽骨架），`check` 校验格式、列出章节变化、拿最近几份已生成文档试跑 lint 看影响，`save` 给出写入 DocNexus 知识库的 capture 指引，不直接写知识库；未接入 DocNexus 时 `draft` / `save` 提示先接入（默认模板只读） |
 | `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` 之间，标记外的补充说明保留；指定的表在库里不存在时标出 |
@@ -500,7 +500,7 @@ npx @rowansenne/workflow-run docs-repo <团队文档仓库地址> [--project <
 * 其他服务的需求要先在 `workflow-run/` 里拉下来（`git -C workflow-run pull`），绑定时才看得到。
 * `/workflow view` 在这个模式下显示文档仓库里所有项目的需求。
 
-**浏览**：`/workflow view` 或 `workflow-run view --open` 生成一个本地页面（`workflow-run/tmp/view/index.html`）。左边是需求列表，可按名称或分支搜索；右边是这个需求的各阶段、审查记录（每轮的级别数量、复核、与上次对比的修复情况）、交付记录，以及各份文档的渲染正文。页面是生成那一刻的快照，产物有更新时重新生成。
+**浏览**：`/workflow view` 或 `npx @rowansenne/workflow-run view --open` 生成一个本地页面（`workflow-run/tmp/view/index.html`）。左边是需求列表，可按名称或分支搜索；右边是这个需求的各阶段、审查记录（每轮的级别数量、复核、与上次对比的修复情况）、交付记录，以及各份文档的渲染正文。页面是生成那一刻的快照，产物有更新时重新生成。
 
 其他产物：
 
@@ -508,11 +508,10 @@ npx @rowansenne/workflow-run docs-repo <团队文档仓库地址> [--project <
 | --- | --- | --- |
 | database-query | 查询结果 | 默认对话输出；导出时 `workflow-run/tmp/database-query/result-<时间戳>.csv` |
 | md-to-wiki | 转换临时 XHTML | `workflow-run/tmp/md-to-wiki/_wiki_upload_<时间戳>.html`（上传后可删） |
-| 各文档类 skill | 项目模板 | `workflow-run/templates/<skill>/`（见下文「模板」） |
 
 规则：
 
-* 本工具的产出都在 `workflow-run/`：`docs/requirements/`（需求产物）、`docnexus/`（DocNexus 工作区）、`templates/`（项目模板）是**持久产物**，随代码提交或在独立文档仓库里提交，团队共享。
+* 本工具的产出都在 `workflow-run/`：`docs/requirements/`（需求产物）、`docnexus/`（DocNexus 工作区，含定制的文档模板）是**持久产物**，随代码提交或在独立文档仓库里提交，团队共享。
 * `workflow-run/tmp/` 是**临时产物**目录，安装时自动把 `/workflow-run/tmp/` 加入 `.gitignore`，不入库。
 
 ## 自定义模板
@@ -593,8 +592,9 @@ workflow-run（安装器仓库）/
 
 文档类 skill 的模板来源取决于项目是否接入了 DocNexus，生成的文档开头会注明「模板来源」：
 
-* **已接入 DocNexus：只用知识库里的模板** `workflow-run/docnexus/library/templates/<skill>/<文件名>`（分类 `doc-template`）。不再使用 skill 自带的默认模板，也不使用 `workflow-run/templates/` 下的文件。库里缺模板时 skill 会停下来，提示你导入后再继续，不会悄悄回退到默认模板。
-* **未接入 DocNexus**：依次取项目文件 `workflow-run/templates/<skill>/<文件名>`、skill 自带默认模板。
+* **已接入 DocNexus：只用知识库里的模板** `workflow-run/docnexus/library/templates/<skill>/<文件名>`（分类 `doc-template`）。不再使用 skill 自带的默认模板。库里缺模板时 skill 会停下来，提示你导入后再继续，不会悄悄回退到默认模板。
+* **未接入 DocNexus**：只用 skill 自带的默认模板。
+* **默认模板只读，定制只走 DocNexus**：要改模板或新建模板，都写进 DocNexus 知识库，团队共享同一份、每次变更有 timeline。不要直接改 skills 目录里的模板（升级会覆盖）；`workflow-run/templates/` 下的项目模板已不再生效，`doctor` 会提示你导入知识库后删除。
 
 | skill | 文件名 | 用途 | 默认模板 |
 | --- | --- | --- | --- |
@@ -605,18 +605,17 @@ workflow-run（安装器仓库）/
 | project-review | `checklist.md` | 审查清单 | 有 |
 | project-review | `report.md` | 审查报告模板 | 有 |
 
-**技术方案、上线方案的模板按团队自己的格式创建**：各团队发到 wiki 的文档格式不同，skills 不再自带固定格式。第一次生成时 skill 会停下来，请你给一份团队现有的同类文档（本地 Markdown，或 wiki 的 pageId / URL）作样例，用 `workflow/scripts/make-template.mjs` 抽出章节和表格结构，把正文换成填写说明，你确认后保存：未接入 DocNexus 时存到 `workflow-run/templates/<skill>/template.md`（建议提交，团队共用），已接入时经你授权写入 DocNexus。之后想换格式，直接说「重新生成技术方案模板」。
+**技术方案、上线方案的模板按团队自己的格式创建**：各团队发到 wiki 的文档格式不同，skills 不再自带固定格式。第一次生成时 skill 会停下来，请你给一份团队现有的同类文档（本地 Markdown，或 wiki 的 pageId / URL）作样例，用 `workflow/scripts/make-template.mjs` 抽出章节和表格结构，把正文换成填写说明，你确认后经你授权写入 DocNexus。因此这两类文档**需要先接入 DocNexus**（`--with-docnexus`），未接入时 skill 会停下来提示。之后想换格式，直接说「重新生成技术方案模板」。
 
 **修改模板**：说「改技术方案模板，加一节回滚方案」或 `/workflow template release 去掉灰度那节`，agent 会一路走完：
 
 1. 把当前生效的模板复制成草稿 `workflow-run/tmp/template-draft/<skill>/<文件名>`，只改草稿；
 2. `template.mjs check` 校验格式（必填 ` *`、可选「（如有）」、占位符），列出新增 / 删除的章节、必填变化，并拿最近几份已生成的文档试跑，告诉你新模板下它们会多出哪些错误；
-3. 你确认后 `template.mjs save`：旧模板备份到 `workflow-run/tmp/template-backup/<时间>/`，写入 `workflow-run/templates/<skill>/`，再确认生效；已接入 DocNexus 时经你授权按 capture 流程写入知识库。
+3. 你确认后经你授权按 capture 流程写入 DocNexus 知识库，再确认生效；要撤销按 DocNexus 的 timeline 恢复旧版本。
 
-模板别名：`tech`、`release`、`plan`、`delivery`、`review`、`checklist`。改带默认版本的模板（开发方案、交付说明、审查报告、审查清单）也走这条路，保存后项目文件优先，升级不会覆盖。
+模板别名：`tech`、`release`、`plan`、`delivery`、`review`、`checklist`。改带默认版本的模板（开发方案、交付说明、审查报告、审查清单）也走这条路，知识库里的版本取代默认版本，升级不会覆盖。未接入 DocNexus 时不能修改模板，agent 会提示你先接入。
 
-* 老项目升级时，如果还在用原来自带的默认模板（项目和 DocNexus 里都没有自己的版本），安装器会先把它保存到 `workflow-run/templates/<skill>/template.md`，生成效果不变。
-* `doctor` 和 `/workflow status` 会列出还没创建的模板。
+* `doctor` 和 `/workflow status` 会列出还没创建的模板，以及要先接入 DocNexus 才能创建的模板。
 
 **模板导入 DocNexus**：
 
@@ -630,7 +629,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 里，可追溯。
 * 模板里的 `{{...}}` 是给 agent 的填写提示，DocNexus 原样保存；不要写成单独一行的 `{{fact:...}}`（那是 DocNexus 的事实引用语法）。
-* 没接入 DocNexus 时，可用 `workflow-run/templates/` 下的同名文件覆盖默认模板；之后接入 DocNexus，skill 会提示你把这些文件导入知识库（导入后它们不再生效）。
+* 以前放在 `workflow-run/templates/` 下的项目模板：接入 DocNexus 后，缺模板时 skill 会把它作为 `import_from` 提议导入知识库；导入后删除这些文件。
 
 ## 触发准确度评估
 

package/bin/lib/doctor.mjs

@@ -36,7 +36,7 @@ export function doctor(root, offline) {
   if (!found.length) { bad('未找到安装清单：本项目还没用 workflow-run 安装过'); return 1; }
   const m = found[0].m;
   const c = cmpVersion(m.version ?? '0', PKG.version);
-  if (c < 0) meh(`已安装 ${m.version}，当前包是 ${PKG.version}：运行 workflow-run upgrade 升级`);
+  if (c < 0) meh(`已安装 ${m.version}，当前包是 ${PKG.version}：运行 npx @rowansenne/workflow-run upgrade 升级`);
   else if (c > 0) meh(`已安装 ${m.version}，比当前包 ${PKG.version} 新（当前包版本过旧）`);
   else ok(`已安装版本 ${m.version}（环境 ${(m.envs ?? []).join(',')}，模式 ${m.mode}）`);
 
@@ -45,12 +45,12 @@ export function doctor(root, offline) {
     let modified = 0, missing = 0;
     for (const [skill, entry] of Object.entries(man.skills)) {
       const dir = path.join(base, skill);
-      if (!fs.existsSync(dir)) { bad(`${toPosix(path.join(rel, skill))} 不存在：运行 workflow-run upgrade 恢复`); continue; }
+      if (!fs.existsSync(dir)) { bad(`${toPosix(path.join(rel, skill))} 不存在：运行 npx @rowansenne/workflow-run upgrade 恢复`); continue; }
       for (const [f, h] of Object.entries(entry.files ?? {})) {
         const file = path.join(dir, f);
         const label = toPosix(path.join(rel, skill, f));
-        if (!fs.existsSync(file)) { missing++; meh(`缺少 ${label}：运行 workflow-run upgrade 恢复`); }
-        else if (fileHash(file) !== h) { modified++; meh(`${label} 被手动修改过（升级时会被新版覆盖，原文件备份到 workflow-run/tmp/upgrade-backup/；项目定制请放到 profile.json、workflow-run/templates/ 或 DocNexus）`); }
+        if (!fs.existsSync(file)) { missing++; meh(`缺少 ${label}：运行 npx @rowansenne/workflow-run upgrade 恢复`); }
+        else if (fileHash(file) !== h) { modified++; meh(`${label} 被手动修改过（升级时会被新版覆盖，原文件备份到 workflow-run/tmp/upgrade-backup/；项目定制请放到 profile.json 或 DocNexus，模板只能在 DocNexus 里定制）`); }
       }
     }
     if (!modified && !missing) ok(`${toPosix(rel)}：${Object.keys(man.skills).length} 个 skill 的模板文件与安装时一致`);
@@ -67,7 +67,7 @@ export function doctor(root, offline) {
       for (const skill of Object.keys(canon.m.skills)) {
         const link = path.join(dir, skill);
         const st = lstat(link);
-        if (!st) bad(`${d}/${skill} 不存在：运行 workflow-run upgrade 重建`);
+        if (!st) bad(`${d}/${skill} 不存在：运行 npx @rowansenne/workflow-run upgrade 重建`);
         else if (!st.isSymbolicLink()) { if (!readManifest(dir)) meh(`${d}/${skill} 是普通目录而非软链接（可能是建链接失败后的独立拷贝）`); else good++; }
         else if (!fs.existsSync(link)) bad(`${d}/${skill} 是断开的软链接`);
         else good++;
@@ -84,7 +84,7 @@ export function doctor(root, offline) {
   if (fs.existsSync(resolveJs)) {
     const r = spawnSync(process.execPath, [resolveJs, '--root', root, 'status'], { encoding: 'utf8' });
     try { st = JSON.parse(r.stdout); } catch { bad(`resolve.mjs status 执行失败：${(r.stderr || '').trim().split('\n')[0]}`); }
-  } else bad('缺少 workflow/scripts/resolve.mjs：运行 workflow-run upgrade');
+  } else bad('缺少 workflow/scripts/resolve.mjs：运行 npx @rowansenne/workflow-run upgrade');
   if (st) {
     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 提供）');
@@ -93,7 +93,7 @@ export function doctor(root, offline) {
       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 段落'}：运行 workflow-run upgrade`);
+      else meh(`DocNexus 在 ${HOME}/docnexus/，但本项目${linked ? '' : '缺少 docnexus skill 链接'}${!linked && !ctx ? '、' : ''}${ctx ? '' : '缺少 CLAUDE.md / AGENTS.md 里的 DocNexus 段落'}：运行 npx @rowansenne/workflow-run upgrade`);
     }
     // 产出目录：都在 workflow-run/
     const mode = st.artifacts?.mode === 'repo' ? `独立文档仓库（${HOME}/ 自己是 git 仓库）` : '随项目提交';
@@ -101,15 +101,17 @@ export function doctor(root, offline) {
     else ok(`产出目录 ${HOME}/：${mode}`);
     if (st.docnexus.ok) {
       if (!reportTemplateStatus(root, meh)) ok('DocNexus 已接入，文档模板齐全且与默认模板同步（或为团队定制版）');
-      for (const f of st.docnexus.stale_project_templates) meh(`${f} 在接入 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 未接入（可选）');
+    } 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）`);
     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，或重跑 workflow-run 并加 --with-codegraph');
+    else if (st.codegraph?.indexed) meh('有 .codegraph/ 索引但找不到 codegraph 命令：npm i -g @colbymchenry/codegraph，或重跑 npx @rowansenne/workflow-run 并加 --with-codegraph');
     else if (st.codegraph?.cli) console.log('    --  已装 codegraph，但本项目没有建索引（可选：在项目根运行 codegraph init）');
     else console.log('    --  CodeGraph 未接入（可选）');
     if (!st.database.ok) console.log('    --  数据库未配置（可选）');
@@ -133,7 +135,7 @@ export function doctor(root, offline) {
   const lines = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8').split(/\r?\n/).map((l) => l.trim()) : [];
   const need = ['**/database-query/config.json', '**/wiki-config.json'];
   const lack = need.filter((r) => !lines.includes(r));
-  if (lack.length) bad(`.gitignore 缺少 ${lack.join(' ')}：凭据可能被提交，重跑 workflow-run upgrade 补齐`); else ok('凭据文件已被忽略');
+  if (lack.length) bad(`.gitignore 缺少 ${lack.join(' ')}：凭据可能被提交，重跑 npx @rowansenne/workflow-run upgrade 补齐`); else ok('凭据文件已被忽略');
 
   console.log(`\n${errors.length} 个错误，${warns.length} 个警告`);
   return errors.length ? 1 : 0;

package/bin/lib/install.mjs

@@ -12,7 +12,7 @@ import { detectEnv } from '../../workflow/scripts/resolve.mjs';
 export const report = { overwritten: [], removed: [], unlisted: [], unlistedDirs: [], backupDir: null };
 
 // skills 目录里的文件一律以安装包为准：手改过的先备份到 <项目根>/workflow-run/tmp/upgrade-backup/<时间>/（同一次运行共用一个目录），
-// 再覆盖或删除。项目自己的定制应放在不会被升级覆盖的地方：workflow/profile.json、workflow-run/templates/、DocNexus、CLAUDE.md / AGENTS.md
+// 再覆盖或删除。项目自己的定制应放在不会被升级覆盖的地方：workflow/profile.json、DocNexus（文档模板只能在这里定制）、CLAUDE.md / AGENTS.md
 let stamp = null;
 function backup(root, file) {
   stamp ??= timestamp();

package/bin/seed-templates.mjs

@@ -140,9 +140,9 @@ export function updateTemplates(root, tplDir, records = {}, { ok = console.log,
 
 export const STATUS_TEXT = {
   current: '与默认模板一致',
-  outdated: '默认模板有新版，库中模板未改动：运行 workflow-run seed-templates --update 更新',
-  customized: '团队改过，默认模板也有新版：运行 workflow-run seed-templates --diff 查看差异后手动合并',
+  outdated: '默认模板有新版，库中模板未改动：运行 npx @rowansenne/workflow-run seed-templates --update 更新',
+  customized: '团队改过，默认模板也有新版：运行 npx @rowansenne/workflow-run seed-templates --diff 查看差异后手动合并',
   edited: '团队改过（默认模板无变化）',
-  untracked: '没有导入记录，内容与默认模板不同：如需采用新默认模板，运行 workflow-run seed-templates --diff 对比',
-  missing: '知识库中缺失：运行 workflow-run seed-templates 导入（upgrade 时会自动导入）',
+  untracked: '没有导入记录，内容与默认模板不同：如需采用新默认模板，运行 npx @rowansenne/workflow-run seed-templates --diff 对比',
+  missing: '知识库中缺失：运行 npx @rowansenne/workflow-run seed-templates 导入（upgrade 时会自动导入）',
 };

package/bin/workflow-run.mjs

@@ -244,7 +244,7 @@ async function main() {
       // upgrade 顺带的导入是尽力而为：失败只提示，不让升级本身算失败
       const explicit = o.seedTemplates || o.withDocNexus;
       seedFailed = explicit && r.failed.length > 0;
-      if (!explicit && r.failed.length) warn('新增模板导入失败（skills 已升级）：修复后运行 workflow-run seed-templates 重试');
+      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; }
   }
@@ -265,7 +265,7 @@ async function main() {
   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、workflow-run/templates/、DocNexus 或 CLAUDE.md / AGENTS.md）';
+  const keep = '（skills 目录里的文件以安装包为准；项目定制请放到 workflow/profile.json、DocNexus（文档模板只能在这里定制）或 CLAUDE.md / AGENTS.md）';
   if (report.overwritten.length || report.removed.length) {
     warn(`以下文件被手动修改过，已按新版${report.removed.length ? '覆盖或删除' : '覆盖'}，原文件备份在 ${report.backupDir}/${keep}：`);
     for (const f of report.overwritten) warn(`  ${f}`);

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

@@ -39,8 +39,9 @@ description: "Generate a Markdown release/deployment plan (上线方案) from th
 
 - 模板：在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template create-release-md-doc template.md`（`<skills>` 是本 skill 所在的 skills 目录，如 `.agents/skills`），读输出的 `path`，并把 `source` 写进元数据行。上线方案模板**不随 skills 提供**，由各团队按自己 wiki 上的格式创建：
   - 退出码 2 且 `on_demand: true` → 还没有创建模板：**停下这一步**，按 `<skills>/workflow/references/templates.md`「创建模板」请用户给一份团队现有的上线方案作样例，生成模板、用户确认后保存到输出的 `expected`，再继续。不要自己编一份通用模板凑数。
-  - 退出码 2 且没有 `on_demand` → 已接入 DocNexus 但知识库缺模板，按输出的 `hint` 处理。
-  - 用户要修改、重新生成或换一份上线方案模板时，按 `<skills>/workflow/references/templates.md`「修改模板」用 `template.mjs` 处理（模板别名 `release`；按样例重做用 `draft release --from <样例>`），保存时会备份旧模板。
+  - 退出码 2 且 `need_docnexus: true` → 未接入 DocNexus：上线方案模板只保存在 DocNexus 里，**停下这一步**告诉用户先重跑 workflow-run 并加 `--with-docnexus` 接入，再按「创建模板」创建。不要另存到别处。
+  - 退出码 2 的其他情况 → 按输出的 `hint` 处理。
+  - 用户要修改、重新生成或换一份上线方案模板时，按 `<skills>/workflow/references/templates.md`「修改模板」用 `template.mjs` 处理（模板别名 `release`；按样例重做用 `draft release --from <样例>`），保存写入 DocNexus 知识库。
 - 填充：模板的章节和编号因团队而异，**按章节含义**放事实，不按编号。下表是事实的来源，放进模板里含义对应的章节；模板里没有对应章节的事实不擅自加章节，在交付摘要里列出「模板中没有位置的事实」；模板有、但 diff 和 PRD 都给不出内容的章节写「待补充」。
 
 | 事实 | 来源 |

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

@@ -38,8 +38,9 @@ description: "Generate a Markdown technical design doc (技术方案) from the d
 
 - 模板：在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template create-tech-md-doc template.md`（`<skills>` 是本 skill 所在的 skills 目录，如 `.agents/skills`），读输出的 `path`，并把 `source` 写进元数据行。技术方案模板**不随 skills 提供**，由各团队按自己 wiki 上的格式创建：
   - 退出码 2 且 `on_demand: true` → 还没有创建模板：**停下这一步**，按 `<skills>/workflow/references/templates.md`「创建模板」请用户给一份团队现有的技术方案作样例，生成模板、用户确认后保存到输出的 `expected`，再继续。不要自己编一份通用模板凑数。
-  - 退出码 2 且没有 `on_demand` → 已接入 DocNexus 但知识库缺模板，按输出的 `hint` 处理。
-  - 用户要修改、重新生成或换一份技术方案模板时，按 `<skills>/workflow/references/templates.md`「修改模板」用 `template.mjs` 处理（模板别名 `tech`；按样例重做用 `draft tech --from <样例>`），保存时会备份旧模板。
+  - 退出码 2 且 `need_docnexus: true` → 未接入 DocNexus：技术方案模板只保存在 DocNexus 里，**停下这一步**告诉用户先重跑 workflow-run 并加 `--with-docnexus` 接入，再按「创建模板」创建。不要另存到别处。
+  - 退出码 2 的其他情况 → 按输出的 `hint` 处理。
+  - 用户要修改、重新生成或换一份技术方案模板时，按 `<skills>/workflow/references/templates.md`「修改模板」用 `template.mjs` 处理（模板别名 `tech`；按样例重做用 `draft tech --from <样例>`），保存写入 DocNexus 知识库。
 - 填充：模板的章节和编号因团队而异，**按章节含义**放事实，不按编号。下表是事实的来源，放进模板里含义对应的章节；模板里没有对应章节的事实不擅自加章节，在交付摘要里列出「模板中没有位置的事实」；模板有、但 diff 和 PRD 都给不出内容的章节写「待补充」。
 
 | 事实 | 来源 |

package/package.json

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

package/workflow/SKILL.md.tpl

@@ -33,10 +33,10 @@ description: "Entry point for this project's dev workflow skills: routes a reque
 | 写 PR / MR 描述、提 PR | `workflow/scripts/pr-desc.mjs` | 汇总本分支交付说明、审查报告、技术 / 上线方案；创建 PR 需用户同意 |
 | 这套工作流效果怎么样、用得怎么样 | `/workflow report` | 只读统计 `workflow-run/docs/requirements/` 下的产物 |
 | 看看项目文档、某个需求留下了哪些文档、审查记录 | `/workflow view` | 生成本地静态页面，按需求浏览 |
-| 改技术方案 / 上线方案 / 交付说明 / 审查报告的模板，按样例建模板 | `/workflow template` | 草稿 → 校验与影响 → 用户确认后保存 |
+| 改技术方案 / 上线方案 / 交付说明 / 审查报告的模板，按样例建模板 | `/workflow template` | 草稿 → 校验与影响 → 用户确认后写入 DocNexus（默认模板只读，未接入 DocNexus 时不能改） |
 | 记住 / 查找项目决策与约定 | DocNexus（入口 skill `docnexus`） | 需已接入；写入必须用户授权 |
 
-意图明确时直接按对应 skill 执行，不必先输出这张表。目标 skill 没有安装（`resolve.mjs status` 输出的 `skills` 里没有它，安装时用了 `--skills` 子集）→ 告诉用户可以运行 `workflow-run --skills <名称>` 补装，不要假装执行。意图横跨多个阶段时按下面的「完整链路」逐段推进，每段结束告诉用户下一段是什么，由用户决定是否继续。走到哪一步不靠记忆：运行 `node <skills>/workflow/scripts/artifacts.mjs [--branch <分支>]`，它扫描 `workflow-run/docs/requirements/` 下的产物，按元信息行里的分支归组，输出每类最新的一份、wiki 发布记录和 `next`（下一步建议）。
+意图明确时直接按对应 skill 执行，不必先输出这张表。目标 skill 没有安装（`resolve.mjs status` 输出的 `skills` 里没有它，安装时用了 `--skills` 子集）→ 告诉用户可以运行 `npx @rowansenne/workflow-run --skills <名称>` 补装，不要假装执行。意图横跨多个阶段时按下面的「完整链路」逐段推进，每段结束告诉用户下一段是什么，由用户决定是否继续。走到哪一步不靠记忆：运行 `node <skills>/workflow/scripts/artifacts.mjs [--branch <分支>]`，它扫描 `workflow-run/docs/requirements/` 下的产物，按元信息行里的分支归组，输出每类最新的一份、wiki 发布记录和 `next`（下一步建议）。
 
 ### 完整链路（从需求到上线）
 

package/workflow/references/status.md

@@ -9,9 +9,9 @@
 |---|---|---|
 | 项目画像 | ✅ / ⚠️ 部分字段为空 | <空字段>；运行 /workflow profile |
 | wiki | ✅ / ❌ | 填写 md-to-wiki/wiki-config.json 或接入 wiki MCP |
-| DocNexus | ✅ / ❌ | 重跑 workflow-run 并加 --with-docnexus；已接入但缺模板时列出缺的模板并提示 `workflow-run seed-templates` |
+| DocNexus | ✅ / ❌ | 重跑 npx @rowansenne/workflow-run 并加 --with-docnexus；已接入但缺模板时列出缺的模板并提示 `npx @rowansenne/workflow-run seed-templates`；未接入时说明默认模板只读、不能定制，技术方案 / 上线方案要先接入（`templates_need_docnexus`）；`stale_project_templates` 非空时提示这些项目模板已不再生效 |
 | 数据库 | ✅ / ❌ | 重跑 `npx @rowansenne/workflow-run` 补配 |
-| 代码图谱 | ✅ / ⚠️ 已装未建索引 / ❌ | 重跑 workflow-run 并加 --with-codegraph；已装 codegraph 但没有 .codegraph/ 时提示用户自己运行 codegraph init |
+| 代码图谱 | ✅ / ⚠️ 已装未建索引 / ❌ | 重跑 npx @rowansenne/workflow-run 并加 --with-codegraph；已装 codegraph 但没有 .codegraph/ 时提示用户自己运行 codegraph init |
 
 ## 当前分支 <分支>
 | 环节 | 产物 | wiki |

package/workflow/references/templates.md

@@ -6,19 +6,25 @@
 node <skills>/workflow/scripts/resolve.mjs template <skill> <文件名>
 ```
 
-`<skills>` 是本 skill 所在的 skills 目录（如 `.agents/skills`），在项目根执行。输出 JSON：`path` 是要读的模板，`source` 是 `docnexus` / `project` / `default`，写进产出的「模板来源」。判定规则（实现在脚本里，这里只是说明）：
+`<skills>` 是本 skill 所在的 skills 目录（如 `.agents/skills`），在项目根执行。输出 JSON：`path` 是要读的模板，`source` 是 `docnexus` / `default`，写进产出的「模板来源」。
+
+**skills 自带的默认模板只读**：不要直接编辑 skills 目录里的模板文件（升级时会被覆盖），也不要在 `workflow-run/templates/` 放项目模板（已不再生效）。要改模板只有一条路：写进 DocNexus 知识库，团队通过知识库共享同一份。
+
+判定规则（实现在脚本里，这里只是说明）：
 
 - **已接入 DocNexus**：只用 `workflow-run/docnexus/library/templates/<skill>/<文件名>`（分类 `doc-template`，普通 Markdown，手工改动立即生效）。不使用 skill 默认模板，也不使用 `workflow-run/templates/`——知识库是唯一来源，避免几份模板各自演化。
-  - 缺模板时退出码 2，输出 `expected`（应在的位置）、`import_from`（可导入的来源）和 `hint`。**停下这一步**，告诉用户缺哪份模板，给两个选择：在项目根运行 `workflow-run seed-templates`（或重跑安装加 `--seed-templates`）；或者由你在用户确认后按 DocNexus 的 capture 流程把 `import_from` 写入 `expected`，以显式分类封存（`draft seal ... --category doc-template`，metadata.category 也写 `doc-template`）。导入后再继续。
-  - 输出里 `stale_project_file` 非空：提醒用户 `workflow-run/templates/` 下的这份已不再生效，建议导入后删除。
-- **未接入 DocNexus**：先取项目文件 `workflow-run/templates/<skill>/<文件名>`，没有就用 skill 默认模板。
-- **技术方案、上线方案没有默认模板**（`create-tech-md-doc`、`create-release-md-doc` 的 `template.md`）：各团队发到 wiki 的格式不同，skills 不再自带一份固定格式。还没创建时退出码 2，输出 `on_demand: true`、`expected`（创建后保存的位置：接入 DocNexus 时是知识库，否则是项目文件）和 `hint`，按下面「创建模板」处理。老项目升级时，安装器会把原来在用的默认版本保存到项目模板目录，不受影响。
+  - 缺模板时退出码 2，输出 `expected`（应在的位置）、`import_from`（可导入的来源）和 `hint`。**停下这一步**，告诉用户缺哪份模板，给两个选择：在项目根运行 `npx @rowansenne/workflow-run seed-templates`（或重跑安装加 `--seed-templates`）；或者由你在用户确认后按 DocNexus 的 capture 流程把 `import_from` 写入 `expected`，以显式分类封存（`draft seal ... --category doc-template`，metadata.category 也写 `doc-template`）。导入后再继续。
+- **未接入 DocNexus**：只用 skill 默认模板，不能修改或新建模板。
+- 输出里 `stale_project_file` 非空：`workflow-run/templates/` 下的这份已不再生效，提醒用户导入 DocNexus 后删除（未接入时先接入）。
+- **技术方案、上线方案没有默认模板**（`create-tech-md-doc`、`create-release-md-doc` 的 `template.md`）：各团队发到 wiki 的格式不同，skills 不自带固定格式，第一次使用时按样例创建到知识库。
+  - 已接入 DocNexus、还没创建：退出码 2，输出 `on_demand: true`、`expected`（知识库里的位置）和 `hint`，按下面「创建模板」处理。
+  - 未接入 DocNexus：退出码 2，输出 `need_docnexus: true` 和 `hint`。**停下这一步**，告诉用户这两类文档的模板只保存在 DocNexus 里，要先重跑 npx @rowansenne/workflow-run 并加 `--with-docnexus` 接入，再创建模板。不要自己编一份模板凑数。
 
-`resolve.mjs templates` 列出所有登记模板的来源；登记表在各 skill 的 `skill.json`（`templates` 字段）。`--with-docnexus` 接入时会自动导入默认模板，之后可运行 `workflow-run seed-templates` 补导入（已存在的不覆盖）。
+`resolve.mjs templates` 列出所有登记模板的来源；登记表在各 skill 的 `skill.json`（`templates` 字段）。`--with-docnexus` 接入时会自动导入默认模板，之后可运行 `npx @rowansenne/workflow-run seed-templates` 补导入（已存在的不覆盖）。
 
 ## 修改模板（/workflow template）
 
-用户要改某份模板（「技术方案模板加一节回滚」「上线方案去掉灰度那节」「审查报告的严重问题表加一列」），或要新建、按样例重做模板时，用 `template.mjs` 一路走完，不要直接编辑生效中的模板文件。`<模板>` 写别名 `tech` / `release` / `plan` / `delivery` / `review` / `checklist`，或 `<skill>/<文件名>`；没说哪份时先 `template.mjs list` 列出来问。
+用户要改某份模板（「技术方案模板加一节回滚」「上线方案去掉灰度那节」「审查报告的严重问题表加一列」），或要新建、按样例重做模板时，用 `template.mjs` 一路走完，不要直接编辑生效中的模板文件。未接入 DocNexus 时 `draft` / `save` 退出码 2、输出 `need_docnexus: true`：告诉用户默认模板不能改，要先接入 DocNexus（重跑 npx @rowansenne/workflow-run 并加 `--with-docnexus`），不要另找地方保存。`<模板>` 写别名 `tech` / `release` / `plan` / `delivery` / `review` / `checklist`，或 `<skill>/<文件名>`；没说哪份时先 `template.mjs list` 列出来问。
 
 1. **起草稿**：`node <skills>/workflow/scripts/template.mjs draft <模板>`，把当前生效的模板复制到 `workflow-run/tmp/template-draft/<skill>/<文件名>`（输出的 `draft`）。草稿已存在会沿用（上次没改完）；要从当前模板重来加 `--force`。
    - 退出码 2、`need_sample: true`：还没有这份模板，按下面「创建模板」第 1 步向用户要样例，再运行 `draft <模板> --from <样例文件>`（从 stdin 读用 `--from -`）。用户要「按这份文档重做模板」时同样用 `--from`。
@@ -28,14 +34,12 @@ node <skills>/workflow/scripts/resolve.mjs template <skill> <文件名>
    - `impact`：最近几份已生成的文档按新模板会多出哪些错误（例如新的必填章节它们没有）。只影响以后生成和 lint，已有文档不会被改；
    - `warnings`：例如没有任何必填章节；
    - 附上草稿全文（或改动的部分）。
-4. **用户确认后保存**：`node <skills>/workflow/scripts/template.mjs save <模板>`。
-   - 未接入 DocNexus：写到 `workflow-run/templates/<skill>/<文件名>`，原模板备份到输出的 `backup`（`workflow-run/tmp/template-backup/<时间>/`），并重新判定确认 `effective: true`，删除草稿。告诉用户保存位置与备份位置，建议随代码提交，团队共用（提交要用户同意）。改的是带默认版本的模板（plan / delivery / review / checklist）时，保存后项目文件优先于默认版本，以后升级 skills 也不会覆盖它。
-   - 已接入 DocNexus：退出码 2，按输出的 `hint` 走 capture 流程把草稿写入知识库（写入要用户授权），完成后运行 `resolve.mjs template <skill> <文件名>` 确认 `path` 指向知识库里的那份，再删除草稿。
-5. 用户想撤销：把 `backup` 复制回 `saved` 的位置（未接入 DocNexus）；DocNexus 里的模板按 timeline 恢复旧版本。
+4. **用户确认后保存**：`node <skills>/workflow/scripts/template.mjs save <模板>`。它不直接写知识库，退出码 2：按输出的 `hint` 走 capture 流程把草稿写入知识库（写入要用户授权），完成后运行 `resolve.mjs template <skill> <文件名>` 确认 `path` 指向知识库里的那份，再删除草稿。改的是带默认版本的模板（plan / delivery / review / checklist）时，知识库里的版本取代默认版本，以后升级 skills 也不会覆盖它。
+5. 用户想撤销：DocNexus 里的模板按 timeline 恢复旧版本。
 
 ## 创建模板
 
-技术方案、上线方案第一次生成时没有模板，由用户给一份**团队现有的同类文档**作样例来创建。用户也可以随时主动要求「创建 / 重新生成技术方案（上线方案）模板」，流程相同。
+需要已接入 DocNexus。技术方案、上线方案第一次生成时没有模板，由用户给一份**团队现有的同类文档**作样例来创建。用户也可以随时主动要求「创建 / 重新生成技术方案（上线方案）模板」，流程相同。
 
 1. **要样例**：停下来告诉用户还没有这份模板，请用户给一份团队现有的同类文档：本地 Markdown 路径，或 wiki 页面的 pageId / URL。
    - wiki 页面：运行 `node <skills>/md-to-wiki/scripts/upload.mjs get <pageId> --text`，取输出的 `text` 作样例（需要 wiki 已配置，见 `<skills>/workflow/SKILL.md`「增强能力探测」；没配置就请用户导出成 Markdown 或直接贴出内容）。
@@ -45,8 +49,8 @@ node <skills>/workflow/scripts/resolve.mjs template <skill> <文件名>
    - 把每节的 `{{...}}` 改成具体的填写说明（这一节写什么、从哪类事实来，例如「受影响的接口、模块，带文件路径」），不要把样例里的具体业务内容留在模板里；
    - 必填章节在标题末尾加 ` *`，可选章节在标题里加「（如有）」：`lint-doc.mjs` 靠这两个标记检查生成的文档；
    - 对照这份 skill 会采集的事实（`references/diff-collection.md`），diff 能提供、但样例里没有对应章节的（例如配置、SQL、定时任务、回滚），列给用户问要不要加章节，不要擅自加。
-4. **确认后保存**：`template.mjs check` 通过后把完整模板给用户看，用户确认后运行 `template.mjs save <模板>`（同「修改模板」第 4 步）：未接入 DocNexus 时写到 `workflow-run/templates/<skill>/template.md`，建议随代码提交，团队共用；已接入时按输出的 `hint` 走 capture 流程写入知识库（写入需要用户授权），以显式分类 `--category doc-template` 封存，metadata.category 也写 `doc-template`。
+4. **确认后保存**：`template.mjs check` 通过后把完整模板给用户看，用户确认后运行 `template.mjs save <模板>`（同「修改模板」第 4 步），按输出的 `hint` 走 capture 流程写入知识库（写入需要用户授权），以显式分类 `--category doc-template` 封存，metadata.category 也写 `doc-template`。
 5. 保存后确认生效（`save` 输出 `effective: true`，或 DocNexus 写入后重新运行 `resolve.mjs template <skill> template.md`），再继续原来的生成步骤。
 
-- **模板随知识库更新**：用户在生成的文档里做了结构性调整（新增 / 删除 / 重排章节、改表格列、改必填项），且项目已接入 DocNexus 时，交付后列出这些调整，**询问**是否同步回模板；同意后按 DocNexus 的 capture 流程更新同一路径（先 `document get --include document,metadata,timeline` 取 `record_version`，以 `--base-version <record_version> --category doc-template` 封存，用户确认后 `document add --draft <id> --replace`），DocNexus 会在 timeline 中记录每次变更。只改结构，不把某次需求的具体内容写进模板。用户也可以说「改模板」走上面的「修改模板」，或直接编辑库里的模板文件，再用 `<docnexus.bin> document sync --id <id>` 采纳（`<docnexus.bin>` 取 `resolve.mjs status` 的输出）。
+- **模板随知识库更新**：用户在生成的文档里做了结构性调整（新增 / 删除 / 重排章节、改表格列、改必填项）时，交付后列出这些调整，**询问**是否同步回模板；同意后按 DocNexus 的 capture 流程更新同一路径（先 `document get --include document,metadata,timeline` 取 `record_version`，以 `--base-version <record_version> --category doc-template` 封存，用户确认后 `document add --draft <id> --replace`），DocNexus 会在 timeline 中记录每次变更。只改结构，不把某次需求的具体内容写进模板。用户也可以说「改模板」走上面的「修改模板」，或直接编辑库里的模板文件，再用 `<docnexus.bin> document sync --id <id>` 采纳（`<docnexus.bin>` 取 `resolve.mjs status` 的输出）。
 - 模板里的 `{{...}}` 是给 agent 看的填写提示，不是模板引擎语法；不要写成单独一行的 `{{fact:...}}`（那是 DocNexus 的事实引用语法）。

package/workflow/scripts/docnexus.mjs

@@ -39,7 +39,7 @@ export function run(root, args, opts = {}) {
   const entry = cliEntry(root);
   if (entry) return spawnSync(process.execPath, [entry, ...args], o);
   const bin = docnexusBin(root);
-  if (!bin) return { status: 1, error: 'DocNexus 没装：重跑 workflow-run 并加 --with-docnexus' };
+  if (!bin) return { status: 1, error: 'DocNexus 没装：重跑 npx @rowansenne/workflow-run 并加 --with-docnexus' };
   return spawnSync(path.resolve(root, bin), args, { ...o, shell: process.platform === 'win32' });
 }
 

package/workflow/scripts/resolve.mjs

@@ -10,7 +10,7 @@
 //   node .agents/skills/workflow/scripts/resolve.mjs category <skill>             # 该 skill 写入 DocNexus 时的显式分类
 //   node .agents/skills/workflow/scripts/resolve.mjs status                      # 能力探测（/workflow status）
 //   node .agents/skills/workflow/scripts/resolve.mjs env                         # 本机系统与终端（安装时记录），写终端命令按它来
-// 输出 JSON。退出码：0 正常；2 已接入 DocNexus 但知识库缺该模板（按输出的 hint 处理）；1 参数错误 / 该 skill 没有声明分类
+// 输出 JSON。退出码：0 正常；2 缺该模板（知识库里没有，或未接入 DocNexus 而该模板没有默认版本；按输出的 hint 处理）；1 参数错误 / 该 skill 没有声明分类
 
 import fs from 'node:fs';
 import path from 'node:path';
@@ -58,7 +58,7 @@ export function codegraphStatus(root) {
   const cli = r.status === 0;
   return {
     ok: indexed && cli, cli, indexed,
-    how: cli && indexed ? null : !cli ? '重跑 workflow-run 并加 --with-codegraph（或 npm i -g @colbymchenry/codegraph）' : '在项目根运行 codegraph init 建索引（由用户决定）',
+    how: cli && indexed ? null : !cli ? '重跑 npx @rowansenne/workflow-run 并加 --with-codegraph（或 npm i -g @colbymchenry/codegraph）' : '在项目根运行 codegraph init 建索引（由用户决定）',
   };
 }
 
@@ -75,8 +75,10 @@ export function resolveTemplate(root, skill, id) {
   // 没有 src 的模板（技术方案、上线方案）不随 skills 提供，缺失时按「创建模板」由用户给样例生成
   const builtin = t.src ? path.join(SKILLS_DIR, skill, t.src.replace(/\.tpl$/, '')) : null;
   const CREATE = '按 <skills>/workflow/references/templates.md「创建模板」处理：请用户给一份团队现有的同类文档作样例（本地 md 或 wiki pageId / URL），用 workflow/scripts/make-template.mjs 抽骨架，和用户确认后保存到 expected';
+  // workflow-run/templates/ 下的项目模板已不再生效（定制模板只放 DocNexus，便于共享），留着的只用来提示导入
+  const stale = fs.existsSync(project) ? rel(root, project) : null;
   if (docnexusConnected(root)) {
-    const res = { skill, id, docnexus: true, stale_project_file: fs.existsSync(project) ? rel(root, project) : null };
+    const res = { skill, id, docnexus: true, stale_project_file: stale };
     if (fs.existsSync(lib)) return { ok: true, ...res, source: 'docnexus', path: rel(root, lib) };
     if (!builtin) {
       return {
@@ -88,17 +90,18 @@ export function resolveTemplate(root, skill, id) {
     return {
       ok: false, ...res, error: 'missing', expected: rel(root, lib),
       import_from: fs.existsSync(project) ? rel(root, project) : rel(root, builtin),
-      hint: '已接入 DocNexus，只使用知识库中的模板。停下这一步告诉用户缺这份模板：可在项目根运行 workflow-run seed-templates（或重跑安装加 --seed-templates），或经用户确认后把 import_from 按 capture 流程写入 expected（以显式分类 --category doc-template 封存）。',
+      hint: '已接入 DocNexus，只使用知识库中的模板。停下这一步告诉用户缺这份模板：可在项目根运行 npx @rowansenne/workflow-run seed-templates（或重跑安装加 --seed-templates），或经用户确认后把 import_from 按 capture 流程写入 expected（以显式分类 --category doc-template 封存）。',
     };
   }
-  if (fs.existsSync(project)) return { ok: true, skill, id, docnexus: false, source: 'project', path: rel(root, project) };
+  // 未接入 DocNexus：只用 skill 自带的默认模板（只读，不能改）；没有默认版本的（技术方案、上线方案）要先接入 DocNexus 才能创建
+  const res = { skill, id, docnexus: false, stale_project_file: stale };
   if (!builtin) {
     return {
-      ok: false, skill, id, docnexus: false, error: 'missing', on_demand: true, expected: rel(root, project),
-      hint: `这份模板不随 skills 提供，项目里还没有创建。停下这一步告诉用户，${CREATE}。`,
+      ok: false, ...res, error: 'missing', need_docnexus: true, expected: rel(root, lib),
+      hint: `这份模板不随 skills 提供，自定义模板只保存在 DocNexus 知识库里（便于团队共享），本项目还没有接入 DocNexus。停下这一步告诉用户：先重跑 npx @rowansenne/workflow-run 并加 --with-docnexus 接入${stale ? `（项目里的 ${stale} 已不再生效，接入后可导入知识库）` : ''}，再${CREATE}。`,
     };
   }
-  return { ok: true, skill, id, docnexus: false, source: 'default', path: rel(root, builtin) };
+  return { ok: true, ...res, source: 'default', path: rel(root, builtin) };
 }
 
 // DocNexus 对显式分类名的约束：1–80 字符，无首尾空白与控制字符（与 bin/skills.mjs 一致）
@@ -186,10 +189,11 @@ export function status(root) {
       // 运行 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) : [],
-      stale_project_templates: dn ? templates.map((t) => t.stale_project_file).filter(Boolean) : [],
+      // workflow-run/templates/ 下已不生效的项目模板：接入 DocNexus 后导入知识库再删除
+      stale_project_templates: templates.map((t) => t.stale_project_file).filter(Boolean),
       // 各 skill 写入时使用的显式分类（没声明的 skill 不列出）
       categories: Object.fromEntries(skillMetas().map((m) => [m.name, resolveCategory(root, m.name)]).filter(([, c]) => c.ok).map(([n, c]) => [n, c.category])),
-      how: dn ? '缺模板时运行 workflow-run seed-templates' : '重跑 workflow-run 并加 --with-docnexus',
+      how: dn ? '缺模板时运行 npx @rowansenne/workflow-run seed-templates' : '重跑 npx @rowansenne/workflow-run 并加 --with-docnexus',
     },
     // 产物位置：项目里（默认）或独立文档仓库（workflow/references/requirements.md）
     artifacts: (() => { const L = layout(root); return { mode: L.mode, ok: L.ok, ...(L.mode === 'repo' ? { repo: L.repo_rel, project: L.project, commit_prompt: L.commit_prompt } : { dir: 'workflow-run/docs/requirements' }), how: L.ok ? null : L.hint }; })(),
@@ -199,11 +203,13 @@ export function status(root) {
       ok: !!db?.connections && Object.keys(db.connections).length > 0,
       default: db?.default_connection ?? (db?.connections?.default ? 'default' : null),
       connections: Object.fromEntries(Object.entries(db?.connections ?? {}).map(([k, c]) => [k, { driver: c.driver ?? 'mysql', readonly: c.readonly !== false }])),
-      how: '重跑 workflow-run 补配数据库',
+      how: '重跑 npx @rowansenne/workflow-run 补配数据库',
     },
-    templates: templates.map(({ skill, id, source, path: p2, ok, on_demand, expected }) => ({ skill, id, ok, source: source ?? 'missing', path: p2 ?? null, ...(on_demand ? { on_demand: true, expected } : {}) })),
+    templates: templates.map(({ skill, id, source, path: p2, ok, on_demand, need_docnexus, expected }) => ({ skill, id, ok, source: source ?? 'missing', path: p2 ?? null, ...(on_demand ? { on_demand: true, expected } : {}), ...(need_docnexus ? { need_docnexus: true } : {}) })),
     // 不随 skills 提供、还没创建的模板（技术方案、上线方案）：第一次生成文档时按「创建模板」引导用户创建
     templates_to_create: templates.filter((t) => t.on_demand).map((t) => ({ skill: t.skill, id: t.id, expected: t.expected })),
+    // 没有默认版本、要先接入 DocNexus 才能创建的模板（未接入时）
+    templates_need_docnexus: templates.filter((t) => t.need_docnexus).map((t) => ({ skill: t.skill, id: t.id })),
   };
 }
 

package/workflow/scripts/template.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 // 修改 / 创建文档模板（/workflow template）的确定性步骤：起草稿 → 校验并与当前模板、已生成文档比对 → 确认后保存。
-// 来源判定沿用 resolve.mjs template；改动只落在草稿 workflow-run/tmp/template-draft/<skill>/<模板>，save 时才写到生效位置。
-// 已接入 DocNexus 时 save 不直接写知识库（写入需按 capture 流程、经用户授权），退出码 2 并给出指引。
+// 来源判定沿用 resolve.mjs template；改动只落在草稿 workflow-run/tmp/template-draft/<skill>/<模板>。
+// skill 自带的默认模板只读：定制模板只保存在 DocNexus 知识库里（便于团队共享），未接入 DocNexus 时 draft / save 退出码 2 提示先接入；
+// save 也不直接写知识库（写入需按 capture 流程、经用户授权），退出码 2 并给出指引。
 // 流程说明见 workflow/references/templates.md「修改模板」。
 //
 // 用法（在项目根执行；--root 可指定项目根）：
@@ -12,8 +13,8 @@
 // <模板>：tech | release | plan | delivery | review | checklist，或 <skill>[/<模板文件名>]（如 create-tech-md-doc/template.md）
 // draft：把当前生效的模板复制成草稿；还没有模板（或 --from）时按样例抽骨架（make-template.mjs）。草稿已存在时不覆盖，--force 重来
 // check：草稿本身的格式问题、与当前模板相比的章节变化、拿最近几份已生成文档按新旧模板各跑一次 lint-doc 看影响
-// save：check 无错误才写入；原模板备份到 workflow-run/tmp/template-backup/<时间>/，写入后重新 resolve 确认生效，删除草稿
-// 输出 JSON。退出码：0 正常；1 参数错误 / 草稿有错误；2 需要按输出的 hint 处理（缺样例、已接入 DocNexus 需 capture）
+// save：check 无错误后给出写入知识库的 capture 指引（写入后重新运行 resolve.mjs template 确认生效）
+// 输出 JSON。退出码：0 正常；1 参数错误 / 草稿有错误；2 需要按输出的 hint 处理（缺样例、未接入 DocNexus、需 capture 写入）
 
 import fs from 'node:fs';
 import path from 'node:path';
@@ -37,7 +38,6 @@ const SAMPLE_DOCS = 5;
 
 const rel = (root, p) => path.relative(root, p).split(path.sep).join('/');
 const read = (f) => { try { return fs.readFileSync(f, 'utf8'); } catch { return null; } };
-const stamp = () => new Date().toISOString().replace(/[-:]/g, '').replace(/\..*$/, '').replace('T', '-');
 
 // <模板> → { skill, id }；未知返回 null
 export function target(name) {
@@ -50,6 +50,10 @@ export function target(name) {
   return t ? { skill, id: t.id } : null;
 }
 
+// 未接入 DocNexus：默认模板只读，不能改也不能新建
+const NEED_DOCNEXUS = '默认模板随 skills 提供、只读不能改；自定义模板只保存在 DocNexus 知识库里，便于团队共享。告诉用户先重跑 npx @rowansenne/workflow-run 并加 --with-docnexus 接入，再修改或创建模板。';
+const needDocNexus = (t, r) => ({ code: 2, out: { ok: false, skill: t.skill, id: t.id, docnexus: false, need_docnexus: true, current: r.ok ? r.path : null, hint: NEED_DOCNEXUS } });
+
 const draftPath = (root, { skill, id }) => path.join(root, 'workflow-run', 'tmp', 'template-draft', skill, id);
 
 // 草稿本身的格式检查：错误挡住保存，警告给用户看
@@ -118,8 +122,9 @@ function current(root, t) {
 export function draft(root, t, { from = null, force = false, stdin = () => fs.readFileSync(0, 'utf8') } = {}) {
   const file = draftPath(root, t);
   const { r, text } = current(root, t);
-  const base = { skill: t.skill, id: t.id, draft: rel(root, file), source: r.ok ? r.source : null, current: r.ok ? r.path : null, docnexus: !!r.docnexus, expected: r.ok ? (r.source === 'default' ? rel(root, path.join(root, 'workflow-run', 'templates', t.skill, t.id)) : r.path) : r.expected };
-  if (r.error === 'unknown') return { code: 1, out: { ok: false, ...base, message: r.message } };
+  if (r.error === 'unknown') return { code: 1, out: { ok: false, skill: t.skill, id: t.id, message: r.message } };
+  if (!r.docnexus) return needDocNexus(t, r);
+  const base = { skill: t.skill, id: t.id, draft: rel(root, file), source: r.ok ? r.source : null, current: r.ok ? r.path : null, docnexus: true, expected: r.ok ? r.path : r.expected };
   if (fs.existsSync(file) && !force && !from) return { code: 0, out: { ok: true, ...base, created: false, note: '草稿已存在，沿用上次的草稿；要从当前模板重来加 --force' } };
   let content;
   let origin;
@@ -164,28 +169,14 @@ export function save(root, t, file = null) {
   if (c.code) return c;
   if (c.out.unchanged) return { code: 0, out: { ok: true, skill: t.skill, id: t.id, saved: null, note: '草稿与当前模板相同，没有写入' } };
   const r = resolveTemplate(root, t.skill, t.id);
-  if (r.docnexus) {
-    return {
-      code: 2, out: {
-        ok: false, skill: t.skill, id: t.id, docnexus: true, draft: c.out.draft, expected: r.ok ? r.path : r.expected,
-        hint: '已接入 DocNexus，模板只认知识库里的那份，写入要按 capture 流程并经用户授权：已有模板时先 document get --include document,metadata,timeline 取 record_version，以草稿内容 --base-version <record_version> --category doc-template 封存，用户确认后 document add --draft <id> --replace；还没有时以 --category doc-template 新建。完成后重新运行 resolve.mjs template 确认。',
-      },
-    };
-  }
-  const dst = path.join(root, 'workflow-run', 'templates', t.skill, t.id);
-  let backup = null;
-  if (fs.existsSync(dst)) {
-    backup = path.join(root, 'workflow-run', 'tmp', 'template-backup', stamp(), t.skill, t.id);
-    fs.mkdirSync(path.dirname(backup), { recursive: true });
-    fs.copyFileSync(dst, backup);
-  }
-  const src = path.resolve(root, c.out.draft);
-  fs.mkdirSync(path.dirname(dst), { recursive: true });
-  fs.writeFileSync(dst, fs.readFileSync(src, 'utf8'));
-  const after = resolveTemplate(root, t.skill, t.id);
-  const effective = after.ok && after.path === rel(root, dst);
-  if (effective && src === draftPath(root, t)) fs.rmSync(src);
-  return { code: effective ? 0 : 1, out: { ok: effective, skill: t.skill, id: t.id, saved: rel(root, dst), backup: backup && rel(root, backup), effective, source: after.source ?? null, warnings: c.out.warnings, changes: c.out.changes } };
+  if (!r.docnexus) return needDocNexus(t, r);
+  return {
+    code: 2, out: {
+      ok: false, skill: t.skill, id: t.id, docnexus: true, draft: c.out.draft, expected: r.ok ? r.path : r.expected,
+      hint: '模板只认知识库里的那份，写入要按 capture 流程并经用户授权：已有模板时先 document get --include document,metadata,timeline 取 record_version，以草稿内容 --base-version <record_version> --category doc-template 封存，用户确认后 document add --draft <id> --replace；还没有时以 --category doc-template 新建。完成后重新运行 resolve.mjs template 确认，再删除草稿。',
+      warnings: c.out.warnings, changes: c.out.changes,
+    },
+  };
 }
 
 export function list(root) {