@rowansenne/workflow-run 0.25.0 → 0.26.1

package/CHANGELOG.md

@@ -4,6 +4,21 @@
 
 ## [Unreleased]
 
+## [0.26.1] - 2026-10-23
+
+### 修复
+- **`upgrade --with-docnexus` 现在真的会把 DocNexus 升到最新版**：接入与升级统一改用 `@rowansenne/docnexus@latest`。此前传的是不带 tag 的包名，npm 会参考 `.docnexus/package.json` 里 `--save-exact` 锁定的版本，把旧版本原地装回来，命令看起来成功、DocNexus 却没升级。离线 / 本地验证用 `DOCNEXUS_PKG` 指向目录或 tgz 时不追加 `@latest`（本地来源没有 tag）。
+- 修正文档里「upgrade 不会升级 DocNexus 包」的说法：`upgrade` 不带 `--with-docnexus` 时确实只升级 skills、DocNexus 包原地不动；带上该参数则会在重装技能的同时升级 DocNexus 包、刷新 skill 链接与 `CLAUDE.md` / `AGENTS.md` 段落，并导入新增模板。`--help` 与 README 命令表同步重写该参数说明。
+
+### 变更
+- 架构页的分层图改为「代理 · 用户 / 用户 view / 工作流编排 / 工具 / 底层文档库」：原来的五层里，「编排」与「共用核心」合并为「工作流编排」（脚本由流程调用，不构成独立能力层），DocNexus 从「能力」移到「底层文档库」（它的产物与需求产物同在 `workflow-run/` 下），新增「用户 view」一条，容纳 `view.mjs`、`docnexus view`、`report.mjs` 这类只读回看入口。README 的架构描述同步更新。
+- 架构页的 DocNexus 命令表补上 `docnexus view`（本地只读浏览知识库），并说明它是前台常驻、`Ctrl+C` 停止、`--port` 可指定端口。
+
+## [0.26.0] - 2026-10-22
+
+### 变更
+- dev 不再向用户确认规模：S / M / L 由 agent 按标准判定并说明依据，直接按该规模推进，用户主动提出异议或范围变化时按新规模继续。S 规模符合快速通道条件时改为明确询问用户是否走快速通道，问完等本轮答复再继续：明确同意才走，拒绝或答复未明确同意按完整流程落盘交付；缺陷修复同样处理，M / L 规模先把根因与修复方式给用户确认再改代码。
+
 ## [0.25.0] - 2026-10-22
 
 ### 新增
@@ -347,7 +362,8 @@
 - 安装器改为单一 Node 实现，`init-skills.sh` / `init-skills.ps1` 只是薄封装。
 - `code-review` 改名为 `project-review`，升级时自动清理旧名。
 
-[Unreleased]: https://github.com/guilianerde/skills-init/compare/v0.21.0...HEAD
+[Unreleased]: https://github.com/guilianerde/skills-init/compare/v0.26.0...HEAD
+[0.26.0]: https://github.com/guilianerde/skills-init/compare/v0.25.0...v0.26.0
 [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

package/README.md

@@ -27,7 +27,7 @@ npx @rowansenne/workflow-run --with-docnexus --with-codegraph
 
 全量安装的分步说明见图文教程 [docs/full-install.html](docs/full-install.html)（下载后用浏览器打开）。
 
-整体架构（五层结构、dev 主线流程、设计约定、产物与知识闭环）见 [docs/architecture.html](docs/architecture.html)（下载后用浏览器打开）。
+整体架构（代理 / 用户 view / 工作流编排 / 工具 / 底层文档库四层、dev 主线流程、设计约定、产物与知识闭环）见 [docs/architecture.html](docs/architecture.html)（下载后用浏览器打开）。
 
 非交互示例（bash、zsh、PowerShell 写法一样）：
 
@@ -44,7 +44,7 @@ npx @rowansenne/workflow-run uninstall
 | 命令 | 作用 |
 | --- | --- |
 | `init`（默认，可省略） | 安装或重装 |
-| `upgrade` | 读安装清单里记录的环境与模式，非交互升级到当前版本：保留数据库配置等用户配置，skills 文件一律更新为新版（手改过的先备份到 `workflow-run/tmp/upgrade-backup/`）；已接入 DocNexus 时顺带导入新版本新增的文档模板（只新增，不改动已有模板） |
+| `upgrade` | 读安装清单里记录的环境与模式，非交互升级到当前版本：保留数据库配置等用户配置，skills 文件一律更新为新版（手改过的先备份到 `workflow-run/tmp/upgrade-backup/`）。加 `--with-docnexus` 时把 DocNexus 包也升到最新版（`@latest`），刷新 skill 链接与 `CLAUDE.md` / `AGENTS.md` 段落，并导入新增的文档模板（只新增，不改动已有模板）；不加则 DocNexus 包原地不动，只顺带导入新增模板 |
 | `doctor` | 自检：已装版本与当前包对比、手改 / 缺失的文件、软链接是否断开、项目画像、DocNexus 模板是否齐全、各数据库连接能否只读 `SELECT 1`（`--offline` 跳过）、`.gitignore` 是否忽略了凭据。有错误时退出码 1 |
 | `uninstall` | 等价于 `--uninstall` |
 | `report` | 本地效果报告：只读统计 `workflow-run/docs/requirements/` 下的产物（`--since YYYY-MM-DD`、`--all-branches`、`--json`），见「workflow：入口与项目画像」 |
@@ -210,9 +210,9 @@ node .agents/skills/workflow/scripts/resolve.mjs env --check   # 逐个字段核
 /dev --bug <现象 | 报错 | 日志>       # 缺陷修复
 ```
 
-* **功能开发**：理解需求（可读 PRD、查 DocNexus 历史决策）→ 调研现有代码 → 需求澄清（借鉴 grill-me：按决策树分轮提问，每题给推荐答案；事实自己查、决定交给用户；S 规模无未定决定时跳过澄清提问）→ **规模确认（S / M / L 都说明判定依据、对应流程并等用户确认）** → 按规模出方案（S 列步骤开始；M 对话内方案待确认；L 落盘方案文档待确认）→ 小步实现并编译 → 补测试并运行 → 用 project-review 自审 → 交付说明落盘到 `workflow-run/docs/requirements/<需求名>/<项目名>/delivery.md`（带分支元信息；改动、验证结果、配置清单、未执行的 SQL），已接入 DocNexus 时每次都问要不要沉淀（同意后以 `dev-notes` 分类写入，并把库内路径记回交付说明）。审查和上线方案会按分支自动读取这份交付说明。
-* **S 规模快速通道**：先经用户确认 S 规模及快速通道，再按条件执行：不涉及配置、SQL / DDL、对外接口、表结构，也没有需要澄清的业务决定时，编译、测试、自审照常，但只在对话里交付，不落盘交付说明、不问沉淀；实现中碰到上述任何一项或改动超过 3 个文件，就退回完整流程，规模变化时先确认新规模。规模确认本身不影响快速通道资格。缺陷修复同样适用（根因仍须在对话里写清楚）。
-* **缺陷修复**：收集现象 → 用失败测试复现 → 用证据定位根因 → **判定规模并等用户确认** → 最小修复让测试转绿 → 自审 → 交付（必须写明根因）。
+* **功能开发**：理解需求（可读 PRD、查 DocNexus 历史决策）→ 调研现有代码 → 需求澄清（借鉴 grill-me：按决策树分轮提问，每题给推荐答案；事实自己查、决定交给用户；S 规模无未定决定时跳过澄清提问）→ **规模判定（S / M / L 说明判定依据，不再询问确认）** → 按规模出方案（S 列步骤开始、符合条件时问是否走快速通道；M 对话内方案待确认；L 落盘方案文档待确认）→ 小步实现并编译 → 补测试并运行 → 用 project-review 自审 → 交付说明落盘到 `workflow-run/docs/requirements/<需求名>/<项目名>/delivery.md`（带分支元信息；改动、验证结果、配置清单、未执行的 SQL），已接入 DocNexus 时每次都问要不要沉淀（同意后以 `dev-notes` 分类写入，并把库内路径记回交付说明）。审查和上线方案会按分支自动读取这份交付说明。
+* **S 规模快速通道**：规模判定不询问用户；S 规模且不涉及配置、SQL / DDL、对外接口、表结构，也没有需要澄清的业务决定时，**问用户是否走快速通道**，问完等本轮答复——明确同意才走：编译、测试、自审照常，但只在对话里交付，不落盘交付说明、不问沉淀；拒绝或未明确同意就按完整流程落盘交付。实现中碰到上述任何一项或改动超过 3 个文件，就退回完整流程，规模变化时按新规模继续。缺陷修复同样适用（根因仍须在对话里写清楚）。
+* **缺陷修复**：收集现象 → 用失败测试复现 → 用证据定位根因 → **判定规模并告知（S 规模问是否走快速通道；M / L 确认根因与修复方式后再改）** → 最小修复让测试转绿 → 自审 → 交付（必须写明根因）。
 * 守则：不写库、不改凭据、不擅自 commit / push、不装新依赖；测试没跑就写「未验证」。
 * 其他 skill 都是可选增强：wiki、DocNexus、数据库没配置时自动跳过，并在交付说明中注明。
 
@@ -302,7 +302,7 @@ node .agents/skills/workflow/scripts/docnexus.mjs usage export > workflow-run/do
 npx @rowansenne/workflow-run upgrade --with-docnexus
 ```
 
-新项目用 `npx @rowansenne/workflow-run --with-docnexus`。离线或本地验证可设 `DOCNEXUS_PKG=/path/to/package-or-source` 指定安装来源；默认从 npm 安装，必须使用支持 format 7 和 `--output-dir` 的版本。
+新项目用 `npx @rowansenne/workflow-run --with-docnexus`。默认从 npm 安装最新版（`@rowansenne/docnexus@latest`），接入和升级都取最新版；离线或本地验证可设 `DOCNEXUS_PKG=/path/to/package-or-source` 指定安装来源（此时不再追加 `@latest`），必须使用支持 format 7 和 `--output-dir` 的版本。
 
 ## CodeGraph 代码图谱与 code-graph skill（可选）
 

package/bin/lib/core.mjs

@@ -24,12 +24,16 @@ export const resolveSkillSelection = (names) => withDependencies(SKILL_LIST, nam
 export const SKILLS = META.skills;
 // 用户配置：重跑不覆盖；值为对应空模板（用于判断单一来源中的文件是否还没被填写过）
 export const USER_FILES = META.userFiles;
+// 接入 / 重装都用最新版：@latest 让 npm 显式解析最新 tag，不受 .docnexus/package.json 里
+// 已锁版本的牵制（否则重跑会把旧版本原地装回来）。离线或本地验证时 DOCNEXUS_PKG 可指向
+// 本地目录 / tgz，此时不再追加 @latest（本地来源没有 tag）。
 export const DOCNEXUS_PKG = process.env.DOCNEXUS_PKG || '@rowansenne/docnexus';
+export const DOCNEXUS_SPEC = process.env.DOCNEXUS_PKG ? DOCNEXUS_PKG : `${DOCNEXUS_PKG}@latest`;
 export const CODEGRAPH_PKG = process.env.CODEGRAPH_PKG || '@colbymchenry/codegraph@1'; // code-graph skill 按 1.x 的库接口编写
 // 工作流产物与 DocNexus 知识输出的父目录；DocNexus 运行环境另在项目根 .docnexus/。
 export const HOME = 'workflow-run';
 // 升级 DocNexus 的命令（在项目根执行；不用 cd / &&，PowerShell 5.1 也能直接运行）
-export const docnexusUpgradeCmd = () => `npm install --prefix ./.docnexus --save-exact ${DOCNEXUS_PKG}@latest`;
+export const docnexusUpgradeCmd = () => `npm install --prefix ./.docnexus --save-exact ${DOCNEXUS_SPEC}`;
 export const MANIFEST = '.workflow-run.json'; // 安装清单，位于每个安装目录（单一来源时只有 .agents/skills 一份）
 
 // ---------------------------------------------------------------- 输出

package/bin/lib/docnexus.mjs

@@ -4,7 +4,7 @@ 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, docnexusWorkspace, docnexusInternal, HOME, INSTALL_BASES } from './core.mjs';
+import { TPL_DIR, IS_WIN, DOCNEXUS_SPEC, 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';
@@ -177,7 +177,7 @@ export function refreshDocNexusLinks(root, sel) {
 }
 
 export function setupDocNexus(root, sel) {
-  const npmArgs = ['install', '--prefix', './.docnexus', '--save-exact', DOCNEXUS_PKG];
+  const npmArgs = ['install', '--prefix', './.docnexus', '--save-exact', DOCNEXUS_SPEC];
   step(`接入 DocNexus（运行环境 .docnexus/；知识输出 ${HOME}/docnexus/）`);
   if (!run(IS_WIN ? 'npm.cmd' : 'npm', npmArgs, root)) { warn('npm 安装 DocNexus 失败，已跳过 DocNexus 接入（skills 已正常安装）'); return 'failed'; }
   const bin = docnexusBin(root);

package/bin/workflow-run.mjs

@@ -35,7 +35,7 @@ const HELP = `用法: workflow-run [命令] [选项]
 命令：
   init（默认）         安装或重装 skills
   upgrade              按安装清单里的环境与模式非交互升级到当前版本（保留数据库配置等用户配置；skills 文件一律更新为新版，手改过的先备份到 workflow-run/tmp/upgrade-backup/）；
-                       已接入 DocNexus 时顺带导入新增的文档模板（只新增，不覆盖已有模板）
+                       加 --with-docnexus 时把 DocNexus 包也升到最新版（@latest），刷新 skill 链接与 CLAUDE.md / AGENTS.md 段落，并导入新增的文档模板（只新增，不覆盖已有模板）；不加则 DocNexus 包原地不动，只顺带导入新增模板
   doctor               自检：版本、手改 / 缺失文件、软链接、项目画像、DocNexus 模板、数据库连通性、.gitignore
   uninstall            按安装清单卸载本项目装的 skills 与链接（用户配置备份到 workflow-run/tmp/uninstall-backup/）
   seed-templates       只把自带的文档模板导入 DocNexus（workflow-run/docnexus/library/templates/，已有的不覆盖）

package/dev/SKILL.md.tpl

@@ -58,7 +58,7 @@ description: "Implement a feature or fix a bug in this project end to end: under
 
 | 情况 | 做法 |
 |---|---|
-| S 规模且 F2 后没有未定的决定 | 跳过需求澄清提问，写明本次的理解和假设；仍须按 F4 确认规模 |
+| S 规模且 F2 后没有未定的决定 | 跳过需求澄清提问，写明本次的理解和假设；规模在 F4 判定并告知用户，不再确认 |
 | 只有一两个小决定 | 问一轮即可 |
 | M / L 规模，或用户说「拷问一下 / grill me / 先把需求问清楚」 | 按轮问到前沿为空，输出需求要点、验收标准、不在本次范围、已确认的决定，**等用户确认理解一致**再进 F4 |
 
@@ -68,17 +68,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）和方案都要用户确认。
 
-**规模确认（S / M / L 都必做，含快速通道）**：判定后向用户说明推荐规模、依据（预计改动文件 / 模块、接口 / 数据 / 配置变化及风险），以及对应流程（是否走快速通道、方案与交付说明是否落盘），明确询问是否按该规模处理。**等用户明确确认后，再按该规模推进后续流程、绑定需求或写代码**；只告知判定结果或默认选中推荐项不算确认。可以与 F3 的理解确认或简要方案确认在同一轮提出，但必须明确列出规模并收到确认；本轮对话中已明确确认的同一规模不重复询问。用户调整范围或实现中发现规模变化时，说明变化依据，确认新规模后再继续。规模确认属于流程选择，不算 F3 的业务决定，不影响 S 规模快速通道资格。
+**规模判定（S / M / L 都必做，不再询问用户）**：规模由你按上表判定，向用户说明判定的规模与依据（预计改动文件 / 模块、接口 / 数据 / 配置变化及风险）即可，**不询问、不等确认**，直接按该规模推进后续流程；用户主动提出不同意见时，按用户说的规模继续。用户调整范围或实现中发现规模变化时，说明变化依据，按新规模继续。规模判定属于流程选择，不算 F3 的业务决定，不影响 S 规模快速通道资格。
 
-**M / L 规模先定需求名**：用户确认规模、确定要落盘时，按 Artifact Location 运行 `requirement.mjs which`，当前分支没绑定需求就在这一轮问用户这个需求叫什么（可以和规模确认、澄清问题一起问），之后的方案、交付、审查、技术方案、上线方案都归到这个需求下。
+**M / L 规模先定需求名**：判定为 M / L、确定要落盘时，按 Artifact Location 运行 `requirement.mjs which`，当前分支没绑定需求就在这一轮问用户这个需求叫什么（可以和简要方案确认、澄清问题一起问），之后的方案、交付、审查、技术方案、上线方案都归到这个需求下。
 
-**S 规模快速通道**：用户已确认 S 规模，且改动**不涉及**配置项、SQL / DDL、对外接口（HTTP 接口签名、MQ 消息体、对外 DTO）、表结构、权限、资金，也没有 F3 中确认过的业务决定 → 走快速通道：F5～F7 照常（编译、测试、自审都不省），F8 只在对话里交付，不落盘交付说明、不问 DocNexus 沉淀（见 F8「快速通道交付」）。规模确认时说明「按快速通道处理，不落盘交付说明」。实现中一旦碰到上面任何一项、改动超过 3 个文件，或用户要求落盘 → 退出快速通道，按完整 F8 交付；重新评估后规模变化的，先确认新规模再继续。小改动也要走完整流程是用户绕开 dev 的主要原因，所以只在上面这些会影响上线和团队的情况下才落盘。
+**S 规模快速通道（问用户）**：判定为 S 规模，且改动**不涉及**配置项、SQL / DDL、对外接口（HTTP 接口签名、MQ 消息体、对外 DTO）、表结构、权限、资金，也没有 F3 中确认过的业务决定时，**明确询问用户是否走快速通道**：说明快速通道下 F5～F7 照常（编译、测试、自审都不省），F8 只在对话里交付，不落盘交付说明、不问 DocNexus 沉淀（见 F8「快速通道交付」）。**问完等本轮答复再继续：明确同意才走快速通道；拒绝或答复没有明确同意，就按完整 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` 自检，再请用户确认。
 
@@ -144,13 +144,13 @@ description: "Implement a feature or fix a bug in this project end to end: under
 
 ### B4 — 修复与验证
 
-- 修复前按 F4 的标准判定规模，并完成同样的规模确认（S / M / L 都适用，说明是否走快速通道及落盘要求）；用户明确确认后再改代码。修复中规模变化时先确认新规模再继续。
+- 修复前按 F4 的标准判定规模并告知用户（规模不询问确认）；S 规模符合快速通道条件时照 F4 问用户是否走快速通道，问完等本轮答复再改代码：明确同意才走快速通道，拒绝或未明确同意按完整流程落盘交付。M / L 规模把根因结论和修复方式当作简要方案给用户确认后再改代码。修复中规模变化时说明变化依据，按新规模继续。
 - 做能消除根因的**最小改动**；B2 的测试由红变绿，相关已有测试保持通过（运行方式同 F6）。
 - 如果历史脏数据需要修正，写成 SQL 脚本交给用户，不直接执行。
 
 ### B5 — 自审与交付
 
-同 F7、F8（交付说明同样落盘，「类型」写缺陷修复）。快速通道同样适用于缺陷修复：S 规模、不涉及配置 / SQL / 对外接口 / 表结构 / 权限 / 资金，且同类风险排查没有发现其他调用方受影响时，在对话里交付，但根因（证据链、修复方式）必须在对话里写清楚。交付说明的「根因」节必须写：证据链、修复方式、为什么这样修、同类风险排查结果；DocNexus 沉淀时根因是首要候选。
+同 F7、F8（交付说明同样落盘，「类型」写缺陷修复）。快速通道同样适用于缺陷修复：S 规模、用户在 B4 已同意走快速通道，不涉及配置 / SQL / 对外接口 / 表结构 / 权限 / 资金，且同类风险排查没有发现其他调用方受影响时，在对话里交付，但根因（证据链、修复方式）必须在对话里写清楚。交付说明的「根因」节必须写：证据链、修复方式、为什么这样修、同类风险排查结果；DocNexus 沉淀时根因是首要候选。
 
 ## Rules
 

package/package.json

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