@rowansenne/workflow-run 0.22.0 → 0.22.2

package/CHANGELOG.md

@@ -4,6 +4,17 @@
 
 ## [Unreleased]
 
+## [0.22.2] - 2026-10-19
+
+### 文档
+- 新增架构介绍页 `docs/architecture.html`：五层结构、dev 主线流程与规模分级、设计约定、8 个 skill 与依赖、产物与 DocNexus 知识闭环、运行反馈；README 快速开始里加了链接。
+- 推荐的安装命令默认带 `--with-docnexus --with-codegraph`：README 快速开始和非交互示例、架构介绍页、`docs-repo` 在还没安装时的提示都改成全量安装；最小安装（只装 skills）作为示例保留。
+
+## [0.22.1] - 2026-10-19
+
+### 变更
+- 随代码提交时不再往代码仓库的 `.gitattributes` 加 `workflow-run/feedback/*.jsonl merge=union`，`init` / `upgrade` 会去掉 0.22.0 加的这一行（文件里只剩这一行时删掉文件），改动需要你提交。独立文档仓库模式照旧，加在文档仓库的 `workflow-run/.gitattributes`。
+
 ## [0.22.0] - 2026-10-19
 
 ### 新增

package/README.md

@@ -13,28 +13,30 @@
 > 本工具在项目里的产出（需求产物、DocNexus 工作区、项目模板、临时文件）都放在项目根的
 > `workflow-run/`
 > 一个目录里，不往项目的其他地方写；它可以随代码提交，也可以整个是团队的独立文档仓库（见「独立文档仓库」）。
-> 安装只用 `npx @rowansenne/workflow-run`，在项目根执行。
+> 安装只用 npx，在项目根执行。推荐 `npx @rowansenne/workflow-run --with-docnexus --with-codegraph`，同时接入 DocNexus 文档库和 CodeGraph 代码图谱。
 
 ## 快速开始
 
-需要 **Node.js >= 22**（接入 DocNexus 时需 >= 22.13，code-graph 的 `impact` / `entry` 需 >= 22.5）。只用 npx 安装，在项目根执行（以当前目录为项目根；Windows 要在管理员终端里运行）：
+需要 **Node.js >= 22.13**（DocNexus 的要求；不接 DocNexus 时 >= 22 即可，code-graph 的 `impact` / `entry` 需 >= 22.5）。只用 npx 安装，在项目根执行（以当前目录为项目根；Windows 要在管理员终端里运行）。推荐全量安装：
 
 ```
-npx @rowansenne/workflow-run
+npx @rowansenne/workflow-run --with-docnexus --with-codegraph
 ```
 
-按提示：选择环境（编号多选，回车 = 全部）→ 确认 / 填写数据库连接 → 自动生成。装完后在 agent 里运行 `/workflow profile` 填写项目画像。
+按提示：选择环境（编号多选，回车 = 全部）→ 确认 / 填写数据库连接 → 自动生成。`--with-docnexus` 接入 DocNexus 文档库（开发约定与审查问题的沉淀和召回、团队定制的文档模板），`--with-codegraph` 接入 CodeGraph 代码图谱（改动影响到的接口、MQ、定时任务和测试）；不需要哪一项就去掉对应参数。装完后在 agent 里运行 `/workflow profile` 填写项目画像。
 
-同时接入 DocNexus 与 CodeGraph 的全量安装，见图文教程 [docs/full-install.html](docs/full-install.html)（下载后用浏览器打开）。
+全量安装的分步说明见图文教程 [docs/full-install.html](docs/full-install.html)（下载后用浏览器打开）。
+
+整体架构（五层结构、dev 主线流程、设计约定、产物与知识闭环）见 [docs/architecture.html](docs/architecture.html)（下载后用浏览器打开）。
 
 非交互示例（bash、zsh、PowerShell 写法一样）：
 
 ```
-npx @rowansenne/workflow-run --envs all --yes                              # 用现有数据库配置，装全部环境
-npx @rowansenne/workflow-run --envs codex,qwen --skip-db                   # 跳过数据库
-npx @rowansenne/workflow-run --envs claude,qwen --skip-db --with-docnexus  # 同时接入 DocNexus 文档库
-npx @rowansenne/workflow-run --envs all --skip-db --copy                   # 不用软链接，各环境独立拷贝
-npx @rowansenne/workflow-run uninstall                                     # 按安装清单卸载
+npx @rowansenne/workflow-run --envs all --yes --with-docnexus --with-codegraph              # 用现有数据库配置，装全部环境
+npx @rowansenne/workflow-run --envs codex,qwen --skip-db --with-docnexus --with-codegraph   # 跳过数据库
+npx @rowansenne/workflow-run --envs all --skip-db --copy --with-docnexus --with-codegraph   # 不用软链接，各环境独立拷贝
+npx @rowansenne/workflow-run --envs claude --skip-db                                        # 最小安装：只装 skills，不接 DocNexus 和 CodeGraph
+npx @rowansenne/workflow-run uninstall                                                      # 按安装清单卸载
 ```
 
 ### 子命令
@@ -132,7 +134,7 @@ npx @rowansenne/workflow-run docs-repo git@git.example.com:team/team-docs.git
 * 知识：交付与审查的 DocNexus 沉淀率、正文引用了知识库文档的产物占比；
 * 各分支链路：开发方案、交付说明、审查报告、技术方案、上线方案齐不齐，哪些文档还没发布到 wiki。
 
-**运行反馈**（`npx @rowansenne/workflow-run feedback [--json]`）：效果报告只看落盘的产物，看不到过程。dev 和 project-review 每跑完一次，用 `workflow/scripts/feedback.mjs add` 静默追加一行到 `workflow-run/feedback/<git 用户名>.jsonl`：模型、规模 / 深度、是否走快速通道、向用户提问几轮、用户纠正过几次理解、验收项验证了几条、跳过了哪些步骤、**哪条规则读不懂或做不到**、用户主动说的抱怨。只记过程，不记代码和业务名词；不额外问用户。每人一个文件，随 `workflow-run/` 提交，多人不冲突；安装器在 `.gitattributes` 里给这些文件配 `merge=union`，同一个人在几个分支上都有记录时合并也不冲突。用来定期精简 skill：
+**运行反馈**（`npx @rowansenne/workflow-run feedback [--json]`）：效果报告只看落盘的产物，看不到过程。dev 和 project-review 每跑完一次，用 `workflow/scripts/feedback.mjs add` 静默追加一行到 `workflow-run/feedback/<git 用户名>.jsonl`：模型、规模 / 深度、是否走快速通道、向用户提问几轮、用户纠正过几次理解、验收项验证了几条、跳过了哪些步骤、**哪条规则读不懂或做不到**、用户主动说的抱怨。只记过程，不记代码和业务名词；不额外问用户。每人一个文件，随 `workflow-run/` 提交，多人不冲突。独立文档仓库模式下，安装器在文档仓库的 `workflow-run/.gitattributes` 里给这些文件配 `merge=union`，同一个文件在几个分支上都有记录时合并也不冲突；随代码提交时不改代码仓库的 `.gitattributes`，合并时遇到冲突保留两边的行即可。用来定期精简 skill：
 
 1. 团队照常用两三周；
 2. 运行 `feedback` 汇总（或直接拿 `workflow-run/feedback/` 下的文件），按「常被跳过的步骤」「读不懂的规则」「提问太多」精简 SKILL.md，发新版本；
@@ -453,7 +455,7 @@ CI（`.github/workflows/test.yml`）在 push 到 main 和每个 PR 上运行：m
 | `workflow-run/feedback/` | 运行反馈，每人一个文件；独立文档仓库模式下提交到文档仓库 |
 | `workflow-run/docnexus/` | DocNexus 工作区与定制的文档模板；依赖和检索库由它自带的 `docnexus/.gitignore` 忽略。独立文档仓库模式下提交到文档仓库 |
 | `.ignore` | 让代码搜索跳过需求目录（不影响 git） |
-| `.gitignore`、`.gitattributes`、`CLAUDE.md` / `AGENTS.md` | 安装器追加的忽略规则、运行反馈的合并规则、DocNexus 说明段落 |
+| `.gitignore`、`CLAUDE.md` / `AGENTS.md` | 安装器追加的忽略规则、DocNexus 说明段落 |
 
 **忽略**（每人每机器一份，或可重新生成）：
 

package/bin/lib/docsrepo.mjs

@@ -95,7 +95,7 @@ export function docsRepo(root, { url, project }) {
   if (tracked) warn(`代码仓库里还跟踪着 ${HOME}/ 下的文件，运行 git rm -r --cached ${HOME} 后提交，代码仓库就不再管它`);
 
   if (!installed) {
-    warn(`本项目还没安装 skills：先运行 npx @rowansenne/workflow-run，项目名之后用 docs-repo --project <项目名> 配置（或第一次落盘时 skill 会问）`);
+    warn(`本项目还没安装 skills：先运行 npx @rowansenne/workflow-run --with-docnexus --with-codegraph，项目名之后用 docs-repo --project <项目名> 配置（或第一次落盘时 skill 会问）`);
     return 0;
   }
   const name = project || artifactsConfig(root).project || suggestProject(root);

package/bin/lib/install.mjs

@@ -260,7 +260,8 @@ export function setupHome(root) {
   // 运行反馈只收当前版本的：装了新版本就清掉本项目旧版本的记录（随 workflow-run/ 提交过的，git 历史里仍可找回）
   const removed = rotateFeedback(root, PKG.version);
   const attr = ensureUnionMerge(root);
-  if (attr) ok(`${attr.file} 已加上 ${attr.rule}（运行反馈多分支合并时保留两边的记录）`);
+  if (attr?.action === 'added') ok(`${attr.file} 已加上 ${attr.rule}（文档仓库里运行反馈多分支合并时保留两边的记录）`);
+  if (attr?.action === 'removed') ok(`${attr.file} 已去掉 ${attr.rule}（随代码提交时不再改代码仓库的 .gitattributes）；改动需要你提交`);
   if (removed) ok(`运行反馈：已清空旧版本的 ${removed} 条记录（${HOME}/feedback/），从这一版重新收集；改动需要你提交`);
 }
 

package/package.json

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

package/workflow/scripts/feedback.mjs

@@ -77,14 +77,29 @@ export function readAll(root) {
     .split('\n').filter((l) => l.trim()).map((l) => { try { return { user: f.replace(/\.jsonl$/, ''), ...JSON.parse(l) }; } catch { return null; } }).filter(Boolean));
 }
 
-// 同一个人在两个分支上各追加一行，合并时会在文件末尾冲突：用 git 内置的 union 合并保留两边的行。
-// workflow-run/ 是独立文档仓库时规则写进它自己的 .gitattributes。返回写入的文件（已有规则时 null）
+// 独立文档仓库模式下各人、各服务都往文档仓库的 feedback/ 追加，同一文件在两个分支上各追加一行时合并会在末尾冲突：
+// 在文档仓库自己的 .gitattributes 里用 git 内置的 union 合并保留两边的行。随代码提交时不加（不改代码仓库的 .gitattributes），
+// 并去掉 0.22.0 加在代码仓库里的这一行（文件里只剩这一行时删掉文件）。
+// 返回 { action: 'added' | 'removed', file, rule }，没有改动时 null
+const LEGACY_RULE = `${HOME}/${FEEDBACK_DIR}/*.jsonl merge=union`;
 export function ensureUnionMerge(root) {
-  const [file, rule] = homeIsRepo(root) ? [path.join(homeDir(root), '.gitattributes'), `${FEEDBACK_DIR}/*.jsonl merge=union`] : [path.join(root, '.gitattributes'), `${HOME}/${FEEDBACK_DIR}/*.jsonl merge=union`];
+  const lines = (f) => (fs.existsSync(f) ? fs.readFileSync(f, 'utf8').split(/\r?\n/) : []);
+  const relOf = (f) => path.relative(root, f).split(path.sep).join('/');
+  const codeAttr = path.join(root, '.gitattributes');
+  if (!homeIsRepo(root)) {
+    const cur = lines(codeAttr);
+    if (!cur.some((l) => l.trim() === LEGACY_RULE)) return null;
+    const keep = cur.filter((l) => l.trim() !== LEGACY_RULE);
+    if (keep.every((l) => !l.trim())) fs.rmSync(codeAttr);
+    else fs.writeFileSync(codeAttr, keep.join('\n'));
+    return { action: 'removed', file: relOf(codeAttr), rule: LEGACY_RULE };
+  }
+  const file = path.join(homeDir(root), '.gitattributes');
+  const rule = `${FEEDBACK_DIR}/*.jsonl merge=union`;
   const text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
-  if (text.split(/\r?\n/).some((l) => l.trim() === rule)) return null;
+  if (lines(file).some((l) => l.trim() === rule)) return null;
   fs.writeFileSync(file, `${text}${text && !text.endsWith('\n') ? '\n' : ''}${rule}\n`);
-  return { file: path.relative(root, file).split(path.sep).join('/'), rule };
+  return { action: 'added', file: relOf(file), rule };
 }
 
 // 新版本装好后：删掉本项目旧版本的记录，其他项目（独立文档仓库里各服务共用 feedback/）的不动。返回删掉的条数