@rowansenne/workflow-run 0.26.1 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/CHANGELOG.md +29 -0
  2. package/README.md +68 -38
  3. package/bin/lib/artifact-context.mjs +46 -0
  4. package/bin/lib/docnexus.mjs +4 -4
  5. package/bin/lib/doctor.mjs +1 -2
  6. package/bin/lib/install.mjs +1 -1
  7. package/bin/lib/uninstall.mjs +3 -0
  8. package/bin/workflow-run.mjs +20 -29
  9. package/code-graph/SKILL.md.tpl +2 -7
  10. package/create-release-md-doc/SKILL.md.tpl +12 -13
  11. package/create-tech-md-doc/SKILL.md.tpl +12 -13
  12. package/database-query/SKILL.md.tpl +2 -0
  13. package/database-query/skill.json +2 -2
  14. package/dev/SKILL.md.tpl +42 -116
  15. package/dev/references/bug.md +32 -0
  16. package/dev/references/delivery-template.md +6 -6
  17. package/dev/references/delivery.md +50 -0
  18. package/dev/references/implementation.md +23 -0
  19. package/dev/references/plan-template.md +5 -3
  20. package/dev/references/planning.md +45 -0
  21. package/dev/references/preflight.md +35 -0
  22. package/dev/skill.json +2 -2
  23. package/md-to-wiki/SKILL.md.tpl +5 -1
  24. package/md-to-wiki/skill.json +2 -2
  25. package/package.json +2 -2
  26. package/project-review/SKILL.md.tpl +46 -72
  27. package/project-review/references/report.md.tpl +4 -4
  28. package/project-review/references/reporting.md +48 -0
  29. package/project-review/references/review-method.md +56 -0
  30. package/project-review/references/verification.md +30 -0
  31. package/shared/prd-fetch.md +1 -1
  32. package/workflow/SKILL.md.tpl +16 -16
  33. package/workflow/lib/artifact-finalize.mjs +144 -0
  34. package/workflow/lib/artifact-model.mjs +83 -0
  35. package/workflow/lib/capabilities.mjs +80 -0
  36. package/workflow/lib/code-snapshot.mjs +55 -0
  37. package/workflow/lib/document-model.mjs +86 -0
  38. package/workflow/lib/meta-store.mjs +114 -0
  39. package/workflow/lib/path-match.mjs +21 -0
  40. package/workflow/lib/project.mjs +218 -0
  41. package/workflow/lib/requirement-read.mjs +68 -0
  42. package/workflow/lib/requirements.mjs +224 -0
  43. package/workflow/lib/run-gates.mjs +136 -0
  44. package/workflow/lib/runs.mjs +188 -0
  45. package/workflow/lib/workspace-read.mjs +122 -0
  46. package/workflow/references/architecture.md +53 -0
  47. package/workflow/references/capabilities.md +39 -0
  48. package/workflow/references/codegraph.md +3 -3
  49. package/workflow/references/docnexus.md +1 -1
  50. package/workflow/references/execution.md +95 -0
  51. package/workflow/references/requirements.md +36 -25
  52. package/workflow/references/runs.md +100 -0
  53. package/workflow/references/status.md +7 -3
  54. package/workflow/references/templates.md +11 -14
  55. package/workflow/scripts/artifact.mjs +39 -0
  56. package/workflow/scripts/artifacts.mjs +21 -80
  57. package/workflow/scripts/doc-sections.mjs +2 -55
  58. package/workflow/scripts/docnexus-layout.mjs +2 -24
  59. package/workflow/scripts/knowledge.mjs +4 -2
  60. package/workflow/scripts/lint-doc.mjs +2 -35
  61. package/workflow/scripts/meta-store.mjs +2 -0
  62. package/workflow/scripts/pr-desc.mjs +8 -6
  63. package/workflow/scripts/report.mjs +20 -68
  64. package/workflow/scripts/requirement.mjs +9 -402
  65. package/workflow/scripts/resolve.mjs +22 -190
  66. package/workflow/scripts/review-handoff.mjs +59 -0
  67. package/workflow/scripts/review-scope.mjs +4 -22
  68. package/workflow/scripts/run.mjs +35 -0
  69. package/workflow/scripts/tables.mjs +1 -1
  70. package/workflow/scripts/template.mjs +2 -6
  71. package/workflow/scripts/view.mjs +41 -21
@@ -0,0 +1,56 @@
1
+ # 范围、背景与逐项审查
2
+
3
+ 进入第 1~5 步时读取对应小节;分批与深审并行策略继续读 diff-strategy.md。
4
+
5
+ ## 第 1 步 — 确定审查范围与深度
6
+
7
+ 范围是单文件 / 单方法、分支对比(如 `branch` vs `main`),还是未提交改动(见 `diff-strategy.md`「未提交改动」)。分支对比和未提交改动都先运行 `node <skills>/workflow/scripts/review-scope.mjs --diff <基线>...<dev>`(未提交改动用 `--base <基线>`,含未跟踪的新文件;dev 自审时加 dev 传来的 `--exclude`),**审哪些文件以它的 `review` 为准**:`skipped` 是按规则跳过的(删除、二进制、敏感文件、依赖目录、生成文件、文档、本工具的产物,各带原因),不要自己再增减;确实要审被跳过的,在画像 `review.include` 里加(见 `<skills>/workflow/references/profile.md`)。深度按用户的说法定,没说就用「标准」,写进报告「审查方式」:
8
+ - **快审**(「快速看一下」「扫一眼」):只查正确性、空值、安全、事务与幂等,不查性能、测试、风格;「优化建议(LOW)」写「无」。CRITICAL / HIGH 照样复核。
9
+ - **标准**(默认):检查清单全部维度,**风格类(清单「一致性 / 风格」一节)不查**;「优化建议(LOW)」只写有实际收益的(性能、可维护性上的具体问题),没有就写「无」。
10
+ - **深审**(「仔细审」「全面审」,或资金 / 权限 / 对外接口的大改动合并前):全部维度,包括风格;MEDIUM 也复核。
11
+
12
+ ## 第 2 步 — 建立理解
13
+
14
+ 先读实体、接口、DTO、调用链,理清数据流再下结论;不要凭文件名猜内容。
15
+ - **查项目约定(DocNexus)**:先运行 `node <skills>/workflow/scripts/knowledge.mjs project-review --match <模块名 / 业务名词> --query "<一句话:改动涉及的模块与业务>"`,看以往审查沉淀的反复问题和开发约定(`--query` 在这些分类内按正文 recall),找相关的编码约定、历史决策与已知坑,作为审查依据并在报告中引用 `workflow-run/docnexus/library/<path>`。审查过程中**不写入** DocNexus(写入见第 8 步)。
16
+ - **同分支已有产物**:运行 `node <skills>/workflow/scripts/artifacts.mjs --branch <dev分支>`(单文件 / 未提交改动用当前分支,省略 `--branch`),看输出的 `latest`:
17
+ - `latest.plan` 或 `latest.tech` 存在 → 读其中的验收标准、改动设计、接口 / 数据 / 配置变更,第 3 步审 diff 时做**需求对照**:方案里有、diff 里找不到的 → 漏实现(属于验收标准的按 HIGH,其余 MEDIUM);diff 里有、方案里没提的接口 / 表结构 / 配置 / 依赖变更 → 列出请作者确认(不一定是问题)。只对照能在 diff 里核对的项,不推测业务语义。
18
+ - `latest.delivery` 存在(dev 的交付说明)→ 其中「已确认的决定」并入需求对照的依据;「配置清单」「SQL 脚本」和 diff 对照,diff 里有而交付说明漏列的配置 key / DDL 记为 MEDIUM(上线时会被漏掉)。
19
+ - `latest.review` 存在 → 这是**复审**:读上次报告的问题表,并用 `git log --oneline --since=<上次报告日期> <dev分支>` 看之后改了什么。本次报告对上次的每条问题标「已修复 / 仍存在 / 不再适用」(「已修复」要看到对应改动),本次新发现的标「新增」。
20
+ - **涉及数据库**:diff 里有 SQL、Mapper、实体或 DDL 时,按 `<skills>/workflow/references/tables.md` 运行 `node <skills>/workflow/scripts/tables.mjs --diff <基线>...<dev>`(未提交改动用 `--base <基线>`)找出涉及的表;按本轮数据库通道用 `query.mjs --schema --tables <表> --indexes` 只读拉取实际字段、索引与估算行数,作为第 4、6 步判断索引支撑、字段存在与类型、DDL 锁表与滚动发布兼容的依据。查不了库时注明「未与实际库核对」写进「未覆盖与待确认」,这类发现不升到 HIGH 以上,除非 diff 本身就能证明。
21
+
22
+ ## 第 3 步 — 分支对比
23
+
24
+ 基线默认取 `workflow/profile.json` 的 `main_branch`(未配置则 `main`)。规模和分批用第 1 步 `review-scope.mjs` 的输出:`summary.size` 是「全量精读」就一次读完;「分批精读」按 `batches` 的顺序(P0 → P1 → P2)读,P0 不能跳过;「过大」时停下请用户缩小范围。审不到的文件写进报告(读法见 `diff-strategy.md`)。**深审且改动属于「更大」、环境又能派子 agent 时,先问用户要不要分角度并行查找**(`diff-strategy.md`「分角度并行查找」),用户同意才走,第 4 步改由各子 agent 按角度过清单。只审本次改动引入的问题,同时检查改动是否破坏既有调用方。
25
+
26
+ ## 第 4 步 — 逐项过检查清单
27
+
28
+ 每个文件只看 `review-scope.mjs` 给它的 `sections`(清单小节号,按文件类型和改动内容定),一批文件用 `node <skills>/workflow/scripts/review-scope.mjs rules <文件…>`(带上和第 1 步一样的 `--diff` / `--base`)打印这些小节的原文和画像 `review.rules` 里匹配到的项目规则,按它检查;整个改动再过一次 `overall_sections`(9 影响面、13 测试)。深审读整份清单(`node <skills>/workflow/scripts/resolve.mjs template project-review checklist.md` 取 `path`),包括风格。对每个发现给出 文件、**问题所在的原代码片段**(从文件里照原样复制,第 6 步靠它定位行号)、问题描述、严重级别、修改建议。
29
+
30
+ ## 第 5 步 — 影响面分析
31
+
32
+ 改动是否影响其他调用方/模块。按本轮 CodeGraph 通道分析(script 模式运行 `node <skills>/code-graph/scripts/cg.mjs impact --diff <基线>...<dev>`;未提交改动用 `--base <基线>`):列出受影响的接口、MQ 消费者、定时任务、测试、表和配置 key,报告「影响面」按入口归纳并带文件:行号。Spring 注入、AOP、MyBatis XML、MQ topic、配置 key 图谱看不到,照常 grep(见 `<skills>/workflow/references/codegraph.md`)。查不到调用方的符号不能当作安全,要明说"未确认"。
33
+
34
+ ## 只报会出问题的
35
+
36
+ 报告越短,真问题越不会被漏看。下面这些不报:
37
+ - 风格、命名、格式、注释措辞(快审和标准审查都不报;深审或用户要求时才看);
38
+ - 编译器、linter、CI 已经会拦下的(未使用的变量、格式、import 顺序);
39
+ - 个人偏好、没有违反项目约定(`workflow/profile.json` 的 `notes`、DocNexus 约定、审查清单)的写法差异;
40
+ - 写不出后果的「可以更好」:每条发现都要说清不改会怎样。
41
+
42
+ ## Review Dimensions
43
+
44
+ - 正确性 / 逻辑 bug
45
+ - 字段完整性(实体拷贝是否漏字段、新旧对象赋值是否遗漏、DTO↔实体映射是否缺值)
46
+ - 空指针 / 空值安全
47
+ - 并发与线程安全
48
+ - 异常处理与资源释放(连接、流、锁、事务)
49
+ - 安全(注入 / XSS / 越权 / 敏感信息 / 硬编码密钥)
50
+ - 性能(N+1、循环内查询、大对象、无谓复制)
51
+ - 一致性 / 命名 / 风格(只在深审或用户要求时)
52
+ - 幂等与消息一致性(重复消费 / 回调、事务内发消息)
53
+ - 数据库变更安全(锁表、滚动发布兼容、索引支撑;以实际表结构为准,见第 2 步「涉及数据库」)
54
+ - 测试(改动有没有被测试覆盖、断言是否有效)
55
+ - 语言专项(Java / Go / TS / Python / SQL 各自的常见坑,按改动涉及的语言选读)
56
+ - 配置(见第 4 步取到的审查清单中的配置维度;项目使用的配置中心取自 `workflow/profile.json` 的 `config_center`——配置相关发现按配置清单输出)
@@ -0,0 +1,30 @@
1
+ # 发现复核与严重级别
2
+
3
+ 进入第 6 步前读取;所有审查模式共用,不因仅在对话回复而省略严重问题复核。
4
+
5
+ ## 第 6 步 — 复核
6
+
7
+ 交付前逐条复核 CRITICAL / HIGH(深审时 MEDIUM 也复核;其余 MEDIUM 至少做下面第 1 条)。审查结论会被用来决定能不能合并,一条误报会让人白改代码,也会让后面的真问题不被当回事。找出问题的人自己复核容易顺着原来的思路认同自己,所以**能交给独立的一方就交出去**:
8
+ - **独立复核(首选)**:当前环境能派子 agent / 子任务时(例如 Claude Code 的 Agent 工具、Codex / Qwen Code 的子 agent),每条发现派一个,互不相关的可以同时派。只给它:一句话结论、位置(文件:行号)、你写的触发条件、对比分支(或「未提交改动」)。**不给你的推理过程**,也不告诉它你认为成立。要它自己读代码,按下面 1~4 条检查,回答「成立 / 可能成立 / 不成立」并引用代码作为依据。
9
+ - **自行复核**:环境派不了子 agent 时自己做,先找它**不成立**的理由,找不到再确认成立。
10
+ 检查项(独立复核和自行复核都按这 4 条):
11
+ 1. **定位**:把所有发现(包括 MEDIUM / LOW)写成 `workflow-run/tmp/review/findings.json`(数组,每条 `{ "file", "code"(原代码片段), "line"(你估的行号,可选), "title" }`),运行 `node <skills>/workflow/scripts/locate.mjs workflow-run/tmp/review/findings.json`(带上和第 1 步一样的 `--diff` / `--base`)。报告里的行号一律用它输出的 `start_line`~`end_line`,不用自己数的。`anchored: false` 的回去重读代码、照原样改片段再跑一次,还找不到就降为 MEDIUM 并标「⚠ 待确认」;`ambiguous` 时看 `candidates` 确认是哪一处;`in_change: false` 说明问题不在本次改动的行上,按第 4 条判断是不是本次引入的。
12
+ 2. 写出**触发条件**:什么输入 / 状态下会出错、错成什么样。写不出来 → 降为 MEDIUM 并标「⚠ 待确认」。
13
+ 3. 找有没有别处已经兜住:调用方校验、`@Validated` / 全局异常处理、数据库约束、框架默认行为、配置。涉及索引、字段、唯一约束、表大小的发现,以第 2 步拉到的实际表结构为准(复核列写「已与 <连接名> 核对」)。已兜住 → 删掉或降级,并在说明里写依据。
14
+ 4. 确认是本次改动引入的:改动前就存在的问题移到「未覆盖与待确认」,不计入合并结论。
15
+ 结果:「成立」在报告「复核」列标「✅」;「可能成立」标「⚠」;「不成立」从问题表里删掉(独立复核否掉的,在「未覆盖与待确认」里记一句「复核排除 N 条」)。复核方式(独立 / 自行)写进报告「审查方式」元信息。
16
+
17
+ ## Severity Levels
18
+
19
+ - **CRITICAL**:崩溃 / 数据错误 / 资金影响 / 安全漏洞,必须修复后才能建议合并。dev 用户明确接受遗留风险时可以记录带问题交付,报告仍保留问题与不建议合并的结论;交付文档不代表允许合并或上线
20
+ - **HIGH**:明显 bug,特定场景可触发
21
+ - **MEDIUM**:潜在问题,边界未处理或语义存疑
22
+ - **LOW**:有实际收益的优化建议(性能、可维护性);风格类只在深审时报
23
+
24
+ ## Verification
25
+
26
+ - 每个结论都要能定位到具体文件+行号,并引用真实代码片段;行号来自 `locate.mjs`。
27
+ - 读不到的内容如实说明,不要臆测。
28
+ - 涉及跨分支对比时,确保 diff 基于正确的 base 分支(默认 `main`)。
29
+ - CRITICAL / HIGH 都经过第 6 步复核(能派子 agent 时独立复核),写得出触发条件;复核不了的标「⚠ 待确认」,不计入「不建议合并」的结论。
30
+ - `review-scope.mjs` 的每个文件都有交代:`review` 里的都审过,没精读的逐个列在「未覆盖与待确认」;`skipped` 按原因汇总写进同一节(例如「跳过 12 个:生成文件 8、文档 3、敏感文件 1」,敏感文件单独点名提醒)。
@@ -4,7 +4,7 @@
4
4
 
5
5
  任一步失败都**只回退**(不用 PRD 继续),在产出中写明「PRD 增强已跳过」,绝不因此中止主流程。
6
6
 
7
- 1. **wiki 是否可用**:运行 `node <skills>/workflow/scripts/resolve.mjs status`,看 `wiki.ok`;或者当前环境有 wiki MCP 工具(如 `mcp__wiki-mcp__get_page`)。两者都没有 → 回退。不要直接读 `wiki-config.json`,凭据只由 md-to-wiki 的脚本使用。
7
+ 1. **wiki 通道**:复用开工能力快照的 `wiki.channel`(见 `<skills>/workflow/references/capabilities.md`),不重复探测。无通道时回退;不要读取或输出凭据。
8
8
  2. **解析 pageId**:纯数字直接用;URL 用 `[?&]pageId=(\d+)` 或 `/pages/(\d+)` 提取;提取不出 → 请用户提供 pageId,或回退。
9
9
  3. **拉取页面**(按可用性):
10
10
  - MCP:`get_page({pageId, expand: "body.storage,version"})`;
@@ -5,13 +5,16 @@ description: "Entry point for this project's dev workflow skills: routes a reque
5
5
 
6
6
  # Workflow
7
7
 
8
+ **开工能力**:先运行 `node <skills>/workflow/scripts/resolve.mjs status`,按 `<skills>/workflow/references/capabilities.md` 选择本轮能力与模板;同一项目链路复用已有快照,失败统一按该规则处理。
9
+
8
10
  本项目个人开发工作流的入口:决定由哪个 skill 处理请求,维护所有 skill 共用的**项目画像**,并统一**增强能力探测**。本 skill 自身不写业务代码。
9
11
 
10
12
  ## Command Format
11
13
 
12
14
  ```
13
15
  /workflow # 根据用户请求路由;无具体请求时输出能力地图 + 状态
14
- /workflow status # 能力探测报告
16
+ /workflow status # 能力探测 + 当前分支运行进度(含已完成)
17
+ /workflow resume [<运行id>] # 读取 meta.json 中的状态,核对后续接
15
18
  /workflow profile # 填写或更新项目画像
16
19
  /workflow report # 本地效果报告(审查发现与修复率、需求澄清、沉淀与复用、各分支链路)
17
20
  /workflow view # 项目文档视图:按需求浏览方案、交付、审查、技术 / 上线方案(本地静态页面)
@@ -31,9 +34,10 @@ description: "Entry point for this project's dev workflow skills: routes a reque
31
34
  | 根据分支 diff 出上线方案 | `create-release-md-doc` | 可带 `--tech` 复用技术方案 |
32
35
  | 把 md 发布到 wiki | `md-to-wiki` | 需 wiki 已配置 |
33
36
  | 写 PR / MR 描述、提 PR | `workflow/scripts/pr-desc.mjs` | 汇总本分支交付说明、审查报告、技术 / 上线方案;创建 PR 需用户同意 |
37
+ | 继续上次任务、恢复中断的流程 | `/workflow resume` | 先读运行状态和上下文,等待中的决定不能自动跳过 |
34
38
  | 这套工作流效果怎么样、用得怎么样 | `/workflow report` | 只读统计 `workflow-run/docs/requirements/` 下的产物 |
35
39
  | 看看项目文档、某个需求留下了哪些文档、审查记录 | `/workflow view` | 生成本地静态页面,按需求浏览 |
36
- | 改技术方案 / 上线方案 / 交付说明 / 审查报告的模板,按样例建模板 | `/workflow template` | 草稿 → 校验与影响 → 用户确认后写入 DocNexus(默认模板只读,未接入 DocNexus 时不能改) |
40
+ | 改技术方案 / 上线方案 / 交付说明 / 审查报告的模板,按样例建模板 | `/workflow template` | 草稿 → 校验与影响 → 用户确认后写入 DocNexus(知识库是模板唯一来源) |
37
41
  | 记住 / 查找项目决策与约定 | DocNexus(入口 skill `docnexus`) | 需已接入;写入必须用户授权 |
38
42
 
39
43
  意图明确时直接按对应 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`(下一步建议)。
@@ -41,7 +45,8 @@ description: "Entry point for this project's dev workflow skills: routes a reque
41
45
  ### 完整链路(从需求到上线)
42
46
 
43
47
  ```
44
- dev(需求 → 方案 → 实现 → 测试 → 自审)
48
+ dev(确定工作分支 → 定需求名 → 理解需求 → 方案 → 实现 → 测试 → 优先独立子 agent 审查并落盘报告,无则在当前会话自查 → 用户选择修复或交付)
49
+ ↳ 修复:实现 → 验证 → 复审(无子 agent 时当前会话)→ 再次选择;交付:完整流程生成 delivery.md,S 快速通道只在对话交付、不落盘
45
50
  → create-tech-md-doc(M / L 规模)
46
51
  → md-to-wiki(发布技术方案,可选)
47
52
  → create-release-md-doc(要上线时)
@@ -49,7 +54,7 @@ dev(需求 → 方案 → 实现 → 测试 → 自审)
49
54
  → DocNexus 沉淀(可选,需授权)
50
55
  ```
51
56
 
52
- 开始完整链路时先确定需求名:`node <skills>/workflow/scripts/requirement.mjs which`,当前分支没绑定就问用户这个需求叫什么并 `bind`(见 `references/requirements.md`),之后各段产物都落在 `workflow-run/docs/requirements/<需求名>/<项目名>/`。
57
+ 开始完整链路时,先进入 dev 的 Step 0 确定本次工作分支,再运行 `node <skills>/workflow/scripts/requirement.mjs which` 确认需求名(见 `references/requirements.md`)。入口只转交用户明确给出或确认的名字,不把切换前从旧分支自动读到的名字当成用户已确认的需求名。**这里只问、不 bind**,等第一次真的要落盘产物时再由对应 skill `bind`。这样从入口进来也可以走 S 快速通道,不会提前创建需求目录和 `meta.json`。
53
58
 
54
59
  提交、推送、发布 wiki、写入 DocNexus 都是对外动作,每一步都要用户明确同意。
55
60
 
@@ -62,32 +67,27 @@ dev(需求 → 方案 → 实现 → 测试 → 自审)
62
67
  | `references/profile.md` | 项目画像 `profile.json` 各字段含义(含开发环境配置 `toolchain` / `env_vars`)、填写与更新步骤(`resolve.mjs infer-profile`、`env --check`) |
63
68
  | `references/templates.md` | 模板来源判定(`resolve.mjs template`)、创建与修改模板(`/workflow template`)、模板随知识库更新 |
64
69
  | `references/docnexus.md` | 写入 DocNexus 的分类(`resolve.mjs category`)、按分类参考知识库(`knowledge.mjs`) |
70
+ | `references/capabilities.md` | 开工快照、必装组件门槛、可选增强通道与统一失败处理 |
65
71
  | `references/status.md` | `/workflow status` 的输出格式 |
72
+ | `references/execution.md` | 关键阶段门禁、执行前代码快照、自动审查交接、统一产物收尾与中断恢复 |
73
+ | `references/runs.md` | 完整流程在 meta.json 中的运行状态、步骤完成标记、保存与恢复、运行完成时间 |
66
74
  | `references/requirements.md` | 产物按需求归档(`workflow-run/docs/requirements/<需求名>/<项目名>/`):什么时候问需求名、`requirement.mjs` 绑定分支与给出落盘路径、`meta.json` |
67
75
  | `references/tables.md` | 确定改动涉及哪些表(`tables.mjs`)、只读拉取实际表结构 / 索引 / 行数核对(`query.mjs --schema --indexes`),没有库连接时怎么退回 |
68
76
  | `references/codegraph.md` | 用 CodeGraph 代码图谱读代码、查调用链与影响面(MCP 工具与 CLI 对照、图谱看不到的部分) |
69
77
 
70
- `/workflow profile` → 按 `references/profile.md` 执行;`/workflow status` → 按 `references/status.md` 输出;`/workflow report` → 运行 `node <skills>/workflow/scripts/report.mjs [--since YYYY-MM-DD]`,原样给出输出的 Markdown,再用两三句话指出最值得关注的数字(例如修复率低、带未验证项的交付多、从不沉淀),不要编造报告里没有的数据。`/workflow view` → 运行 `node <skills>/workflow/scripts/view.mjs`(用户要直接打开时加 `--open`),把生成的页面路径告诉用户;页面只读、不联网,数据是生成那一刻的快照,产物有更新时重新生成。`/workflow template` → 按 `references/templates.md`「修改模板」一路走完:起草稿、按用户的要求改、校验并说明影响、用户确认后保存并确认生效;没说改哪份模板时先运行 `template.mjs list` 问用户。
78
+ `/workflow resume` → 按 `references/runs.md`「新会话恢复」读取 `run.mjs show [--id <运行id>]`,先核对项目根、分支、代码和证据,再进入对应 skill 的保存阶段;已完成运行只展示完成标记与时间,不能自动重启。`/workflow profile` → 按 `references/profile.md` 执行;`/workflow status` → 按 `references/status.md` 输出;`/workflow report` → 运行 `node <skills>/workflow/scripts/report.mjs [--since YYYY-MM-DD]`,原样给出输出的 Markdown,再用两三句话指出最值得关注的数字(例如修复率低、带未验证项的交付多、从不沉淀),不要编造报告里没有的数据。`/workflow view` → 运行 `node <skills>/workflow/scripts/view.mjs`(用户要直接打开时加 `--open`),把生成的页面路径告诉用户;页面只读、不联网,数据是生成那一刻的快照,产物有更新时重新生成。`/workflow template` → 按 `references/templates.md`「修改模板」一路走完:起草稿、按用户的要求改、校验并说明影响、用户确认后保存并确认生效;没说改哪份模板时先运行 `template.mjs list` 问用户。
71
79
 
72
80
  ## 增强能力探测
73
81
 
74
- 所有 skill 用同一套判断;任何一项不可用都**不阻塞主流程**,只是跳过对应增强并在产出中注明。
75
-
76
- | 能力 | 判定为可用 | 用途 |
77
- |---|---|---|
78
- | 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`)、发布文档 |
79
- | 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 的运行位置」 | 查约定与历史决策、沉淀知识、提供文档模板 |
80
- | 数据库 | `database-query/config.json` 存在且 `connections` 非空 | 查表结构、核对数据 |
81
- | 代码图谱(CodeGraph) | 项目根有 `.codegraph/` 索引,且 `codegraph` 命令可用(`resolve.mjs status` 的 `codegraph.ok`) | 读代码、查调用链与影响面、找受影响的测试;用法见 `references/codegraph.md` |
82
- | 项目画像 | `workflow/profile.json` 中 `main_branch` 与 `build` / `test` 非空 | dev 构建与测试 |
83
- | 开发环境配置 | `profile.json` 的 `toolchain`(可被 `profile.local.json` 覆盖)配了 JDK / Maven / Node 的路径;`resolve.mjs env --check` 逐个核对在本机是否存在 | dev 跑编译与测试(跑不起来时先看它) |
82
+ 能力探测与选择统一由 `resolve.mjs status` 和 `references/capabilities.md` 负责。DocNexus 是必装组件;开工检查不通过时先修复。CodeGraph、wiki、数据库作为可选增强,按本轮能力快照选择通道,不在各步骤重复探测或复制降级规则。模板只从 DocNexus 读取,缺失处理见 `references/templates.md`。
84
83
 
85
84
  ## Rules
86
85
 
86
+ - 普通聊天生成的报告、分析、方案、草稿或导出等辅助文件默认放在项目根的 `workflow-run/other/`,不因分支已绑定需求而写入需求目录,也不调用需求归档或运行状态命令。工作流正式产物仍按 `references/requirements.md` 归档;源码、测试、配置和已有文件的维护、工作流指定的临时文件与知识库沿用各自目录,用户明确指定路径时以用户为准。
87
87
  - 本 skill 只路由和维护 `profile.json`,不写业务代码;具体工作交给对应 skill,并遵守该 skill 的规则。
88
88
  - `profile.json` 只记录项目事实(含 `toolchain` 开发环境配置:JDK / Maven / Node 的路径),**不写密码、token、内网凭据**;路径里的变量在 `env_vars` 里声明。
89
89
  - 写 `toolchain` 前先用 `resolve.mjs env --check` 核对路径在本机存在;本机对不上、又只是个人差异的,写进个人的 `profile.local.json`(覆盖 `profile.json`),不要改团队那份。
90
- - 用户的请求明显只属于某个 skill 时,不要先跑完整链路或状态检查,直接进入那个 skill。
90
+ - 用户的请求明显只属于某个 skill 时,直接进入对应 skill,并复用本轮开工能力快照。
91
91
 
92
92
  ## 终端命令
93
93
 
@@ -0,0 +1,144 @@
1
+ // 文件发布与 meta 更新之间用同一 meta.json 中的待办恢复;不声称多个文件可一次原子提交。
2
+ import fs from 'node:fs';
3
+ import path from 'node:path';
4
+ import { randomUUID } from 'node:crypto';
5
+ import { FILES, parseBranch } from './artifact-model.mjs';
6
+ import { hash, assertWorkingBranch } from './code-snapshot.mjs';
7
+ import { layout } from './project.mjs';
8
+ import { readRun, assertRunVersion, applyCheckpoint } from './runs.mjs';
9
+ import { isDev, applyDevEvidence, assertReview, assertDelivery, reviewEvidence } from './run-gates.mjs';
10
+ import { updateMeta } from './meta-store.mjs';
11
+ import { OLD_DIR, indexArtifacts } from './requirements.mjs';
12
+
13
+ export const ARTIFACT_TEMPLATES = {
14
+ plan: ['dev', 'plan-template.md'], review: ['project-review', 'report.md'], delivery: ['dev', 'delivery-template.md'],
15
+ tech: ['create-tech-md-doc', 'template.md'], release: ['create-release-md-doc', 'template.md'],
16
+ };
17
+ const allowed = { feature: ['plan', 'review', 'delivery'], bug: ['plan', 'review', 'delivery'], review: ['review'], tech: ['tech'], release: ['release'] };
18
+ const relative = (root, file) => path.relative(root, file).split(path.sep).join('/');
19
+ const fileHash = (file) => fs.existsSync(file) ? hash(fs.readFileSync(file)) : null;
20
+
21
+ export function resumeFinalization(root, { branch, id }) {
22
+ const { req } = readRun(root, branch, id);
23
+ let result;
24
+ updateMeta(path.join(req.abs, 'meta.json'), (meta) => {
25
+ const p = meta.pending_finalization;
26
+ if (!p || p.run_id !== id) throw new Error('没有该运行待恢复的产物收尾');
27
+ const run = meta.runs[id];
28
+ assertRunVersion(run, branch, p.revision);
29
+ if (isDev(run)) assertWorkingBranch(root, run);
30
+ const staged = path.resolve(root, p.staged);
31
+ if (fileHash(staged) !== p.hash) throw new Error('收尾草稿缺失或已变化,保留待办;请恢复原草稿后重试');
32
+ const file = path.join(req.abs, `${FILES[p.kind]}.md`);
33
+ const current = fileHash(file);
34
+ if (current !== p.before && current !== p.hash) throw new Error('正式产物在收尾中断后被其他操作修改,请先核对并恢复;不会覆盖');
35
+ // 中断期间代码/报告也可能变化:发布前重新检查本轮门禁。
36
+ applyDevEvidence(root, req, p.run, p.checkpoint, p.run.updated_at, { [p.kind]: fs.readFileSync(staged, 'utf8') });
37
+ if (p.kind === 'review' || (isDev(p.run) && p.kind === 'delivery')) {
38
+ if (p.kind === 'review') assertReview(root, req, p.run, { review: fs.readFileSync(staged, 'utf8') });
39
+ else assertDelivery(root, req, p.run);
40
+ }
41
+ if (current !== p.hash) {
42
+ if (p.previous) {
43
+ const archive = path.resolve(root, p.previous);
44
+ fs.mkdirSync(path.dirname(archive), { recursive: true });
45
+ if (fs.existsSync(archive) && fileHash(archive) !== p.before) throw new Error('归档版本已存在且内容不同,停止以免覆盖历史');
46
+ fs.copyFileSync(file, archive);
47
+ }
48
+ const tmp = path.join(req.abs, `.${FILES[p.kind]}.${p.id}.tmp`);
49
+ fs.writeFileSync(tmp, fs.readFileSync(staged));
50
+ fs.renameSync(tmp, file);
51
+ }
52
+ const versions = { ...(meta.versions ?? {}), [p.kind]: p.version };
53
+ const artifacts = indexArtifacts(req.abs, versions);
54
+ const latest = Object.fromEntries(Object.keys(FILES).map((k) => [k, artifacts.filter((a) => a.kind === k).at(-1)?.file ?? null]));
55
+ const { pending_finalization, ...rest } = meta;
56
+ result = { ok: true, path: relative(root, file), cite: layout(root).ref(file), previous: p.previous, version: p.version, lint: p.run.artifacts[p.kind].lint, run: p.run };
57
+ return { ...rest, versions, artifacts, latest, runs: { ...meta.runs, [id]: p.run }, updated: p.run.updated_at };
58
+ }, { root, allowFinalization: true });
59
+ return result;
60
+ }
61
+
62
+ export function abortFinalization(root, { branch, id }) {
63
+ const { req } = readRun(root, branch, id);
64
+ updateMeta(path.join(req.abs, 'meta.json'), (meta) => {
65
+ const p = meta.pending_finalization;
66
+ if (!p || p.run_id !== id) throw new Error('没有该运行待取消的产物收尾');
67
+ assertRunVersion(meta.runs[id], branch, p.revision);
68
+ const file = path.join(req.abs, `${FILES[p.kind]}.md`);
69
+ const current = fileHash(file);
70
+ if (current !== p.before && current !== p.hash) throw new Error('正式文件已被其他操作修改,先人工核对,不会覆盖');
71
+ if (current === p.hash && p.before !== p.hash) {
72
+ if (p.before === null) fs.unlinkSync(file);
73
+ else {
74
+ const archive = path.resolve(root, p.previous);
75
+ if (fileHash(archive) !== p.before) throw new Error('原版本归档缺失,不能安全取消');
76
+ const tmp = path.join(req.abs, `.${FILES[p.kind]}.${p.id}.tmp`);
77
+ fs.copyFileSync(archive, tmp); fs.renameSync(tmp, file);
78
+ }
79
+ }
80
+ const { pending_finalization, ...rest } = meta;
81
+ return rest;
82
+ }, { root, allowFinalization: true });
83
+ return { ok: true, aborted: true, run_id: id };
84
+ }
85
+
86
+ export function finalizeArtifact(root, { branch, id, revision, kind, text, input = {}, packet = null, result = null }, check) {
87
+ if (!FILES[kind] || typeof text !== 'string') throw new Error('需要有效的产物 kind 和草稿正文');
88
+ const { req } = readRun(root, branch, id);
89
+ const file = path.join(req.abs, `${FILES[kind]}.md`);
90
+ const wikiRecord = (s) => /^<!-- md-to-wiki: [^\n]*-->/.exec(s)?.[0] ?? null;
91
+ const existingWiki = fs.existsSync(file) ? wikiRecord(fs.readFileSync(file, 'utf8')) : null;
92
+ const draftWiki = wikiRecord(text);
93
+ if (existingWiki && draftWiki && existingWiki !== draftWiki) throw new Error('新版必须保留原 wiki 页面记录;页面变更由 wiki 发布流程处理');
94
+ if (existingWiki && !draftWiki) text = `${existingWiki}\n${text}`;
95
+ const digest = hash(text);
96
+ const key = hash(JSON.stringify({ id, revision, kind, digest, input, packet, result }));
97
+ let repeated = null;
98
+ updateMeta(path.join(req.abs, 'meta.json'), (meta) => {
99
+ const current = meta.runs[id];
100
+ if (current.last_finalization === key && !meta.pending_finalization) {
101
+ if (fileHash(path.join(req.abs, `${FILES[kind]}.md`)) !== digest) throw new Error('已收尾产物后来被修改,请用当前 revision 发起新的收尾');
102
+ repeated = { ok: true, already_finalized: true, path: `${req.dir}/${FILES[kind]}.md`, run: current }; return meta;
103
+ }
104
+ if (meta.pending_finalization) {
105
+ if (meta.pending_finalization.key !== key) throw new Error(`已有待完成收尾,先运行 artifact.mjs resume --id ${meta.pending_finalization.run_id}`);
106
+ return meta;
107
+ }
108
+ assertRunVersion(current, branch, revision);
109
+ if (isDev(current)) assertWorkingBranch(root, current);
110
+ if (!allowed[current.kind]?.includes(kind)) throw new Error('该产物种类不属于当前运行');
111
+ if (parseBranch(text) !== branch) throw new Error('草稿元信息的分支必须与运行分支一致');
112
+ const lint = check(text);
113
+ if (!lint?.ok) throw new Error(`草稿自检失败:${lint?.errors?.join(';') || '模板不可用'}`);
114
+ const at = new Date().toISOString();
115
+ const run = structuredClone(current);
116
+ // 文档收尾只能登记当前步骤,不能在一次落盘中跳到下游或替用户作确认。
117
+ if (Object.keys(input).some((k) => !['steps', 'status', 'waiting_for', 'reason', 'context'].includes(k))) throw new Error('收尾 checkpoint 只接受 steps / status / waiting_for / reason / context;阶段和用户选择用 run.mjs save');
118
+ const expectedStep = isDev(run) ? (kind === 'plan' ? (run.kind === 'feature' ? 'F4' : 'B4') : kind === 'review' ? (run.kind === 'feature' ? 'F7' : 'B5') : (run.kind === 'feature' ? 'F8' : 'B5')) : ({ review: 'R7', tech: 'T4', release: 'L4' })[run.kind];
119
+ if (run.stage !== expectedStep || Object.keys(input.steps ?? {}).some((s) => s !== expectedStep)) throw new Error(`产物应在 ${expectedStep} 收尾,只能更新该步骤`);
120
+ if (isDev(run) && kind === 'delivery') assertDelivery(root, req, run);
121
+ if ((fs.existsSync(file) ? wikiRecord(fs.readFileSync(file, 'utf8')) : null) !== existingWiki) throw new Error('wiki 发布记录在收尾期间变化,请重新读取后重试');
122
+ const before = fileHash(file);
123
+ const oldVersion = meta.versions?.[kind] ?? 1;
124
+ const version = before === null ? 1 : oldVersion + (before === digest ? 0 : 1);
125
+ const previous = before !== null && before !== digest ? relative(root, path.join(root, OLD_DIR, path.relative(path.join(root, 'workflow-run/docs/requirements'), req.abs), `${FILES[kind]}_v${oldVersion}.md`)) : null;
126
+ run.artifacts = { ...(run.artifacts ?? {}), [kind]: { hash: digest, version, path: relative(root, file), previous, lint, at } };
127
+ if (kind === 'plan' && current.artifacts?.plan?.hash !== digest) { run.plan_approval = null; run.implementation = null; run.validation = null; run.review = null; run.decision = null; }
128
+ applyCheckpoint(run, input, at, false);
129
+ if (kind === 'review') {
130
+ run.review = reviewEvidence(root, req, run, packet, result, { review: text });
131
+ run.decision = null;
132
+ }
133
+ applyDevEvidence(root, req, run, input, at, { [kind]: text });
134
+ run.history.at(-1).artifact = { kind, hash: digest, version };
135
+ run.revision++; run.updated_at = at; run.last_finalization = key;
136
+ const op = randomUUID();
137
+ const staged = path.join(root, 'workflow-run/tmp/finalize', `${op}.md`);
138
+ fs.mkdirSync(path.dirname(staged), { recursive: true });
139
+ fs.writeFileSync(staged, text, { flag: 'wx' });
140
+ return { ...meta, pending_finalization: { id: op, key, run_id: id, revision, kind, before, hash: digest, version, previous, staged: relative(root, staged), run, packet, checkpoint: input } };
141
+ }, { root, allowFinalization: true });
142
+ if (repeated) return repeated;
143
+ return resumeFinalization(root, { branch, id });
144
+ }
@@ -0,0 +1,83 @@
1
+ // 正式需求产物的统一纯模型;不扫描目录、不修改状态。
2
+ import { sections, section, tableRows, listItems, meta, isEmpty } from './document-model.mjs';
3
+
4
+ export const FILES = { plan: 'plan', delivery: 'delivery', review: 'review', tech: 'tech-doc', release: 'release-doc' };
5
+ export const LABELS = { plan: '方案', delivery: '交付说明', review: '审查报告', tech: '技术方案', release: '上线方案' };
6
+ export const KINDS = Object.keys(FILES).map((kind) => ({ kind, label: LABELS[kind] }));
7
+
8
+ // 文件名 → { kind, version };不是需求目录里的产物返回 null
9
+ export function parseFile(name) {
10
+ for (const [kind, base] of Object.entries(FILES)) {
11
+ const m = new RegExp(`^${base}(?:_v(\\d+))?\\.md$`).exec(name);
12
+ if (m) return { kind, version: m[1] ? Number(m[1]) : 1 };
13
+ }
14
+ return null;
15
+ }
16
+
17
+ const head = (text, n = 20) => text.split(/\r?\n/).slice(0, n).join('\n');
18
+ export function parseBranch(text) {
19
+ const m = head(text).match(/(?:对比)?分支[::]\s*`?([^`\s||←,,))]+)`?/);
20
+ return m && !/^[{<]/.test(m[1]) ? m[1] : null;
21
+ }
22
+ export function parseWiki(text) {
23
+ const m = /^<!-- md-to-wiki: ([^\n]*?) -->/.exec(text);
24
+ if (!m) return null;
25
+ const kv = Object.fromEntries([...m[1].matchAll(/(\w+)=(\S+)/g)].map((x) => [x[1], x[2]]));
26
+ return kv.pageId ? { pageId: kv.pageId, version: kv.version ? Number(kv.version) : null, url: kv.url ?? null, at: kv.at ?? null } : null;
27
+ }
28
+ export function parseDocnexus(text) {
29
+ const v = /DocNexus[::]\s*([^|\n]*)/.exec(head(text))?.[1]?.trim();
30
+ return v && /docnexus\/library\//.test(v) ? v.split(/[、,,]\s*/).map((s) => s.trim()).filter(Boolean) : null;
31
+ }
32
+ // 文档头里的日期(跳过第一行的 md-to-wiki 发布记录等 HTML 注释,那里的 at= 是发布时间)
33
+ export const headerDate = (text) => /(\d{4}-\d{2}-\d{2})/.exec(head(text.replace(/<!--[\s\S]*?-->/g, ''), 8))?.[1] ?? null;
34
+
35
+ const LEVELS = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'];
36
+
37
+ // DocNexus 元信息行 → captured / not_captured / not_asked / not_needed / not_connected / missing
38
+ export function captureState(text) {
39
+ const v = meta(text, 'DocNexus');
40
+ if (!v) return 'missing';
41
+ if (/docnexus\/library\//.test(v)) return 'captured';
42
+ if (/未接入/.test(v)) return 'not_connected';
43
+ if (/未询问/.test(v)) return 'not_asked';
44
+ if (/无需沉淀/.test(v)) return 'not_needed';
45
+ if (/未沉淀/.test(v)) return 'not_captured';
46
+ return 'missing';
47
+ }
48
+
49
+ // 正文(元信息行之外)有没有引用知识库文档
50
+ export const citesKnowledge = (text) => text.split(/\r?\n/).some((l) => !/^>\s*DocNexus[::]/.test(l) && /docnexus\/library\//.test(l));
51
+
52
+ export function parseReview(text) {
53
+ const secs = sections(text);
54
+ const levels = Object.fromEntries(LEVELS.map((l) => [l, 0]));
55
+ let verified = 0; let pending = 0;
56
+ for (const cells of tableRows(section(secs, '严重问题'))) {
57
+ const lv = LEVELS.find((l) => cells[1]?.toUpperCase().includes(l));
58
+ if (lv) levels[lv]++;
59
+ const last = cells[cells.length - 1] ?? '';
60
+ if (last.includes('✅')) verified++; else if (last.includes('⚠')) pending++;
61
+ }
62
+ levels.MEDIUM += tableRows(section(secs, '一般问题')).length;
63
+ levels.LOW += tableRows(section(secs, '优化建议')).length;
64
+ const followUp = { fixed: 0, open: 0, obsolete: 0 };
65
+ for (const cells of tableRows(section(secs, '与上次审查对比'))) {
66
+ const s = cells[2] ?? '';
67
+ if (s.includes('已修复')) followUp.fixed++; else if (s.includes('仍存在')) followUp.open++; else if (s.includes('不再适用')) followUp.obsolete++;
68
+ }
69
+ return { levels, verified, pending, follow_up: followUp, is_rereview: followUp.fixed + followUp.open + followUp.obsolete > 0 };
70
+ }
71
+
72
+ export function parseDelivery(text) {
73
+ const secs = sections(text);
74
+ const type = meta(text, '类型');
75
+ const scale = meta(text, '规模');
76
+ const unverified = section(secs, '验证')?.match(/未验证项[::]\s*(.*)/)?.[1]?.trim();
77
+ return {
78
+ type: type && /缺陷/.test(type) ? 'bug' : type ? 'feature' : null,
79
+ scale: scale && /^[SML]$/.test(scale) ? scale : null,
80
+ decisions: listItems(section(secs, '已确认的决定')).length,
81
+ has_unverified: !!unverified && !isEmpty(unverified) && !/^\{\{/.test(unverified),
82
+ };
83
+ }
@@ -0,0 +1,80 @@
1
+ // DocNexus format 7:项目根运行,内部状态在 .docnexus/,知识输出固定到 workflow-run/docnexus/。
2
+ import fs from 'node:fs';
3
+ import path from 'node:path';
4
+ import { spawnSync } from 'node:child_process';
5
+ import { fileURLToPath } from 'node:url';
6
+
7
+ export const DOCNEXUS_INTERNAL = '.docnexus';
8
+ export const DOCNEXUS_OUTPUT = 'workflow-run';
9
+ export const docnexusRoot = (root) => path.resolve(root);
10
+ export const docnexusWorkspace = (root) => path.resolve(root, DOCNEXUS_OUTPUT, 'docnexus');
11
+ export const docnexusInternal = (root) => path.resolve(root, DOCNEXUS_INTERNAL);
12
+
13
+ export function docnexusConfigured(root) {
14
+ try {
15
+ const marker = JSON.parse(fs.readFileSync(path.join(docnexusInternal(root), 'project.json'), 'utf8'));
16
+ return marker.format_version === 7 && marker.output_dir === DOCNEXUS_OUTPUT;
17
+ } catch { return false; }
18
+ }
19
+
20
+ export function docnexusBinPath(root) {
21
+ const name = process.platform === 'win32' ? 'docnexus.cmd' : 'docnexus';
22
+ const bin = path.join(docnexusInternal(root), 'node_modules', '.bin', name);
23
+ return fs.existsSync(bin) ? bin : null;
24
+ }
25
+
26
+ export const docnexusConnected = (root) => docnexusConfigured(root) && docnexusBinPath(root) !== null;
27
+
28
+ // 集中探测接入状态;不连接远端服务、不创建索引、不输出凭据。
29
+
30
+ const SKILLS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
31
+ const readJson = (file) => { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; } };
32
+ export const DOCNEXUS_HINT = 'DocNexus 是必装组件,运行 npx @rowansenne/workflow-run 修复接入后继续;不使用默认模板或跳过知识库。';
33
+ export const docnexusBin = (root) => { const bin = docnexusBinPath(root); return bin ? path.relative(path.resolve(root), bin) : null; };
34
+
35
+ export function codegraphStatus(root) {
36
+ const indexed = fs.existsSync(path.join(root, '.codegraph'));
37
+ const cli = spawnSync('codegraph', ['--version'], { cwd: root, encoding: 'utf8', shell: process.platform === 'win32', env: { ...process.env, DO_NOT_TRACK: '1' }, timeout: 30000 }).status === 0;
38
+ const script = path.join(SKILLS_DIR, 'code-graph', 'scripts', 'cg.mjs');
39
+ const scan = fs.existsSync(script);
40
+ let library = { ok: false, error: indexed ? 'skill_missing' : 'no_index' };
41
+ if (indexed && scan) {
42
+ const r = spawnSync(process.execPath, [script, 'status', '--root', root], { cwd: root, encoding: 'utf8', timeout: 30000 });
43
+ try {
44
+ const result = JSON.parse(r.stdout);
45
+ if (r.status === 0 && result.library) library = { ...result.library, ok: !result.library.error };
46
+ else library = { ok: false, error: 'probe_failed' };
47
+ } catch { library = { ok: false, error: 'probe_failed' }; }
48
+ }
49
+ const mode = indexed && library.ok ? 'script' : indexed && cli ? 'cli' : 'source';
50
+ return {
51
+ ok: mode !== 'source', cli, indexed, library, scan, mode,
52
+ how: mode !== 'source' ? null : !indexed ? '是否运行 codegraph init 建索引由用户决定;本次直接读源码' : library.hint ?? '重跑 npx @rowansenne/workflow-run --with-codegraph 修复接入',
53
+ };
54
+ }
55
+
56
+ export function capabilities(root) {
57
+ const wiki = readJson(path.join(SKILLS_DIR, 'md-to-wiki', 'wiki-config.json'));
58
+ const db = readJson(path.join(SKILLS_DIR, 'database-query', 'config.json'));
59
+ const dn = docnexusConnected(root);
60
+ const rest = wiki?.enabled === true && !!wiki?.wiki?.base_url;
61
+ return {
62
+ ready: dn,
63
+ blockers: dn ? [] : [{ capability: 'docnexus', hint: DOCNEXUS_HINT }],
64
+ docnexus: {
65
+ ok: dn, required: true,
66
+ bin: dn ? `./${docnexusBin(root).split(path.sep).join('/')}` : null,
67
+ root: '.', internal: DOCNEXUS_INTERNAL, workspace: `${DOCNEXUS_OUTPUT}/docnexus`, output_dir: DOCNEXUS_OUTPUT,
68
+ run: `node ${path.relative(root, path.join(SKILLS_DIR, 'workflow', 'scripts', 'docnexus.mjs')).split(path.sep).join('/')}`,
69
+ how: dn ? null : DOCNEXUS_HINT,
70
+ },
71
+ wiki: { ok: rest, channel: rest ? 'rest' : null, mcp: 'unknown', how: '配置 md-to-wiki/wiki-config.json,或由 agent 在开工时补充当前会话的 wiki MCP 通道;配置存在不代表鉴权和网络已验证' },
72
+ codegraph: codegraphStatus(root),
73
+ database: {
74
+ ok: !!db?.connections && Object.keys(db.connections).length > 0,
75
+ default: db?.default_connection ?? (db?.connections?.default ? 'default' : null),
76
+ connections: Object.fromEntries(Object.entries(db?.connections ?? {}).map(([k, c]) => [k, { driver: c.driver ?? 'mysql', readonly: c.readonly !== false }])),
77
+ how: '重跑 npx @rowansenne/workflow-run 补配数据库',
78
+ },
79
+ };
80
+ }
@@ -0,0 +1,55 @@
1
+ // 证据绑定到 Git 基线、HEAD 及工作区内容;不输出文件正文,也不把工作流自己的产出算作代码变化。
2
+ import fs from 'node:fs';
3
+ import path from 'node:path';
4
+ import { spawnSync } from 'node:child_process';
5
+ import { createHash } from 'node:crypto';
6
+ import { matchGlob } from './path-match.mjs';
7
+
8
+ export const hash = (value) => createHash('sha256').update(value).digest('hex');
9
+ const INTERNAL = ['workflow-run/**', '.docnexus/**', '.codegraph/**', '.agents/skills/**', '.claude/skills/**', '.qwen/skills/**', '.codebuddy/skills/**'];
10
+ const git = (root, args, encoding = 'utf8') => {
11
+ const r = spawnSync('git', args, { cwd: root, encoding, maxBuffer: 256 * 1024 * 1024 });
12
+ if (r.status !== 0) throw new Error(`代码快照失败:git ${args[0]}:${r.stderr?.toString().trim() || r.error?.message}`);
13
+ return r.stdout;
14
+ };
15
+
16
+ export function assertWorkingBranch(root, run) {
17
+ const top = git(root, ['rev-parse', '--show-toplevel']).trim();
18
+ if (fs.realpathSync.native(top) !== fs.realpathSync.native(root)) throw new Error('请在业务 Git 项目根生成证据');
19
+ const branch = git(root, ['symbolic-ref', '--short', 'HEAD']).trim();
20
+ if (branch !== run.branch) throw new Error('代码快照必须在运行所属的实际工作分支生成,请先切换分支');
21
+ return branch;
22
+ }
23
+
24
+ export function codeSnapshot(root, run) {
25
+ const branch = assertWorkingBranch(root, run);
26
+ const head = git(root, ['rev-parse', 'HEAD']).trim();
27
+ const base = run.scope?.base || 'main';
28
+ const baseCommit = git(root, ['rev-parse', '--verify', `${base}^{commit}`]).trim();
29
+ const mergeBase = git(root, ['merge-base', baseCommit, head]).trim();
30
+ const exclude = [...INTERNAL, ...(run.scope?.exclude ?? [])];
31
+ const names = new Set([
32
+ ...git(root, ['ls-files', '--cached', '--others', '--exclude-standard', '-z']).split('\0'),
33
+ ...git(root, ['ls-tree', '-r', '--name-only', '-z', mergeBase]).split('\0'),
34
+ ].filter((p) => p && !exclude.some((g) => matchGlob(p, g))));
35
+ const entries = [...names].sort().map((file) => {
36
+ const abs = path.join(root, file);
37
+ let stat;
38
+ try { stat = fs.lstatSync(abs); } catch (e) { if (e.code === 'ENOENT') return [file, 'deleted']; throw e; }
39
+ if (stat.isSymbolicLink()) return [file, 'symlink', fs.readlinkSync(abs)];
40
+ // dirty 标记不能代表具体内容;脏子模块须先处理,不能复用含糊的证据。
41
+ if (stat.isDirectory()) {
42
+ if (git(abs, ['status', '--porcelain', '--untracked-files=all']).trim()) throw new Error(`子模块/嵌套仓库有未提交内容,先处理后生成快照:${file}`);
43
+ return [file, 'submodule', git(abs, ['rev-parse', 'HEAD']).trim()];
44
+ }
45
+ return [file, stat.mode & 0o111 ? 'executable' : 'file', hash(fs.readFileSync(abs))];
46
+ });
47
+ const snapshot = { branch, base, base_commit: baseCommit, merge_base: mergeBase, head, scope: run.scope, files: entries.length };
48
+ return { ...snapshot, digest: hash(JSON.stringify({ ...snapshot, entries })) };
49
+ }
50
+
51
+ export function assertSnapshot(root, run, snapshot) {
52
+ const current = codeSnapshot(root, run);
53
+ if (!snapshot?.digest || snapshot.digest !== current.digest) throw new Error('代码或基线已变化,原验证/审查证据已失效;重新生成快照、验证并审查');
54
+ return current;
55
+ }