@rowansenne/workflow-run 0.35.0 → 0.36.1

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 (52) hide show
  1. package/CHANGELOG.md +29 -1
  2. package/README.md +2 -0
  3. package/bin/lib/artifact-context.mjs +1 -1
  4. package/bin/lib/docsrepo.mjs +4 -6
  5. package/bin/lib/doctor.mjs +0 -3
  6. package/bin/lib/install.mjs +15 -15
  7. package/create-release-md-doc/SKILL.md.tpl +1 -1
  8. package/create-tech-md-doc/SKILL.md.tpl +1 -1
  9. package/dev/SKILL.md.tpl +5 -5
  10. package/dev/references/bug.md +2 -2
  11. package/dev/references/clarify.md +2 -2
  12. package/dev/references/delivery.md +3 -3
  13. package/dev/references/planning.md +3 -3
  14. package/docs/architecture.html +3 -2
  15. package/docs/development.md +10 -4
  16. package/docs/full-install.html +90 -125
  17. package/docs/installation.md +1 -1
  18. package/docs/loan-service-install.html +90 -0
  19. package/docs/team-guide.md +3 -2
  20. package/docs/workflow-control-roadmap.md +144 -0
  21. package/docs/workflow-core-phase-one-report.md +41 -0
  22. package/docs/workflow-core-phase-one.md +317 -0
  23. package/docs/workflows.md +2 -2
  24. package/examples/workflow-core.mjs +26 -0
  25. package/package.json +2 -1
  26. package/project-review/SKILL.md.tpl +1 -1
  27. package/project-review/references/checklist.md.tpl +1 -1
  28. package/project-review/references/reporting.md +2 -2
  29. package/workflow/core/errors.mjs +61 -0
  30. package/workflow/core/index.mjs +286 -0
  31. package/workflow/core/review-handoff.mjs +102 -0
  32. package/workflow/integrations/skill-document-policy.mjs +28 -0
  33. package/workflow/lib/artifact-finalize.mjs +49 -10
  34. package/workflow/lib/code-snapshot.mjs +5 -0
  35. package/workflow/lib/meta-store.mjs +12 -1
  36. package/workflow/lib/project.mjs +165 -14
  37. package/workflow/lib/requirements.mjs +57 -100
  38. package/workflow/lib/review-scope.mjs +262 -0
  39. package/workflow/lib/runs.mjs +11 -1
  40. package/workflow/lib/workspace-read.mjs +13 -4
  41. package/workflow/references/architecture.md +10 -5
  42. package/workflow/references/core-api.md +196 -0
  43. package/workflow/references/execution.md +16 -14
  44. package/workflow/references/profile.md +20 -0
  45. package/workflow/references/requirements.md +12 -12
  46. package/workflow/references/runs.md +1 -1
  47. package/workflow/scripts/artifact.mjs +36 -14
  48. package/workflow/scripts/requirement.mjs +36 -40
  49. package/workflow/scripts/resolve.mjs +2 -2
  50. package/workflow/scripts/review-handoff.mjs +49 -73
  51. package/workflow/scripts/review-scope.mjs +78 -294
  52. package/workflow/scripts/run.mjs +21 -9
@@ -0,0 +1,144 @@
1
+ # Workflow 控制面:整体开发目标方案
2
+
3
+ 状态:待实施的目标方案,不代表当前已具备全部能力。日期:2026-11-16。
4
+
5
+ [返回首页](../README.md) · [第一阶段详细方案](workflow-core-phase-one.md) · [当前架构](development.md)
6
+
7
+ ## 1. 已确定的方向
8
+
9
+ 以当前 `skills-init` 仓库为唯一主干,将已有 workflow-run 工作流内核整理为 Agent 无关的公共核心。先保留 Skills 能力,再逐步接入程序接口、CLI、MCP 和不同 Agent 的执行适配。
10
+
11
+ 产品定位:**Agent 无关的研发流程协议与证据控制面。Agent 负责分析和实现,控制面负责运行状态、阶段门禁、决策关联和交付证据。**
12
+
13
+ 不再让 `project-agent` 与本仓库分别演进一套工作流核心。该项目尚无用户,作为 Pi 接入、验证执行和审查执行的参考来源;有价值的实现经过审查后迁入主干,不整仓合并,不承诺兼容其接口。
14
+
15
+ 旧流程已无用户,本次重构主动删除旧流程元素:废弃写入链、旧命令和导出、迁移与兼容分支,以及仅服务这些路径的说明和测试。不提供旧数据迁移、双写或兼容入口。Skills 保留为新核心的接入方式,新版本安装、调用和功能必须形成闭环;旧流程的实现细节不是验收要求。不自动删除业务工作区中的历史数据。
16
+
17
+ 按 [Issue #3](https://github.com/guilianerde/skills-init/issues/3),阶段一明确删除 `path → 直接覆盖正式文件 → sync bump` 链路。受控的正式正文发布统一通过 artifacts.finalize,恢复 / 中止仅处理其事务。必要的派生索引维护单独收敛为 reindex,不改正文、版本、运行状态或证据;具体契约见第一阶段方案 4.5 节。
18
+
19
+ ## 2. 用户与价值
20
+
21
+ 主要面向平台工程团队、技术负责人和需要流程一致性的研发团队。先在本地单项目工作流中验证,再决定团队服务化投入。
22
+
23
+ 要解决的问题:
24
+
25
+ - 不同 Agent 对同一流程执行不一致,阶段事实依赖对话记忆。
26
+ - 需求、方案、实现、验证和审查之间的关联无法核验。
27
+ - 切换 Agent 或恢复会话后,需要重新调研或重复已确认的决定。
28
+ - 模型声明完成测试或审查,但证据来源和覆盖范围不明确。
29
+ - 规范只有文本约束,没有确定性的状态转换和交付检查。
30
+
31
+ 非目标:通用 Coding Agent、IDE、通用 BPM、多 Agent 自动对话平台、模型平台。Web UI、远程执行和多用户权限不是近期前置条件。
32
+
33
+ ## 3. 目标架构
34
+
35
+ ```mermaid
36
+ flowchart TD
37
+ Skills[现有 Skills 与脚本] --> API[统一应用接口]
38
+ Program[内部 Node.js 调用] --> API
39
+ CLI[后续 CLI JSON] --> API
40
+ MCP[后续 MCP Server] --> API
41
+ Agents[Pi / Codex / Claude / OpenHands] --> Adapter[宿主适配层]
42
+ Adapter --> API
43
+ Human[人类操作入口] --> API
44
+ API --> Core[运行 / 门禁 / 产物 / 证据核心]
45
+ Core --> Storage[文件系统存储;后续按需替换]
46
+ API --> Executor[后续验证与审查执行器]
47
+ Executor --> Env[Git / 工作区 / 独立审查环境 / CI]
48
+ ```
49
+
50
+ ### 3.1 单一核心
51
+
52
+ 核心管理 run、revision、阶段转换、产物版本、批准绑定、代码快照、证据关联、交付门禁以及中断恢复。所有入口复用同一实现,Adapter 不另写状态机或复制门禁。
53
+
54
+ 阶段规则由核心定义;宿主可以根据结构化状态决定怎样推进,但不能自行解释或改写“哪些证据满足交付”的规则。
55
+
56
+ ### 3.2 应用接口与接入层
57
+
58
+ 第一阶段提供内部 Node.js 入口。后续 CLI 和 MCP 将参数映射到该接口,负责输入输出、错误映射和身份上下文,不重新实现领域规则。
59
+
60
+ Skills 继续提供需求分析、澄清、执行方法及使用指引。Pi 等 Adapter 负责工具注册、会话接入、宿主事件和能力映射。验证及审查执行器负责实际执行并生成记录,与证据是否有效的判断分开。
61
+
62
+ ### 3.3 存储
63
+
64
+ 先继续使用文件系统、`meta.json` 和 Markdown 产物,保留 revision、写锁、原子替换与产物收尾恢复机制。按实际调用边界集中存储访问,不预先构造通用数据库框架。只有远程服务或多人并发带来明确需求时,才评估 SQLite 或服务端存储。
65
+
66
+ ## 4. 三类契约
67
+
68
+ ### 4.1 Workflow 契约
69
+
70
+ 逐步定义版本化操作:运行创建与查询、checkpoint、产物收尾、验证、审查、方案批准、修复或交付选择、完成和取消。
71
+
72
+ 正式外部协议需约定协议版本、运行标识、预期 revision、调用身份、前置条件、结构化结果与错误。对重试可能重复产生副作用的操作定义幂等规则;不要把 revision 检查误认为幂等。长时验证还需区分操作已接收、执行中、成功、失败和取消。
73
+
74
+ 第一阶段只固定仓库内部接口,不提前发布外部协议版本,也不建设完整 Schema 注册体系。
75
+
76
+ ### 4.2 Evidence 契约
77
+
78
+ 证据至少关联运行、产物版本、代码快照、来源和覆盖范围。执行型证据逐步补充命令、工作目录、开始结束时间、退出码、工具版本、环境及脱敏输出。
79
+
80
+ | 等级 | 来源 | 能证明的范围 |
81
+ | --- | --- | --- |
82
+ | declared | Agent 或调用方提交的声明 | 记录了某项声明,不能单独证明命令执行 |
83
+ | observed | 可信范围内的执行器实际执行并记录 | 执行器观察到的输入与结果 |
84
+ | verified | 独立或干净环境中的复跑记录 | 在指定环境、输入和验证范围内复跑的结果 |
85
+
86
+ 等级不由模型自填后自动升级。`verified` 也不等于测试充分、代码安全或业务一定正确。具体交付是否允许失败、未验证项及风险例外,由门禁策略决定,例外需记录范围、原因及决策来源。
87
+
88
+ 哈希与哈希链主要校验内容一致性。若证据和摘要都可被同一主体重写,不能声称能检测所有伪造;更强的回溯校验需要受保护的摘要、签名或外部 CI 记录。
89
+
90
+ ### 4.3 Adapter 契约
91
+
92
+ Adapter 声明能否拦截文件写入、Shell、使用沙箱、恢复会话和派遣独立审查。记录能力实际覆盖的工具、路径、进程与运行配置,不能只凭自报能力声称强制管控。
93
+
94
+ Observe / Controlled / Enforced 可作为展示等级,但必须附带边界。相同工作流契约不代表所有宿主拥有相同的执行限制。
95
+
96
+ ## 5. 信任与权限边界
97
+
98
+ Agent 操作面负责状态查询、进度、产物与执行请求。Human 操作面负责批准、修复或交付选择、完成及取消等决定;操作归属以最终协议定义为准。
99
+
100
+ 后续 Agent 接口不提供人类决策操作,但仅隐藏 MCP 工具或拆分 CLI 命令不构成可信身份隔离。同一操作系统身份下,Agent 可能直接调用命令或修改状态。只有独立凭据、受保护服务或隔离运行环境才可能提供更强边界。
101
+
102
+ 第一阶段的内部 API 属于受信任的本地程序接口;它可以记录决定,但不认证真实批准人,也不阻止 Agent 直接修改文件。后续能力必须逐项验证后再对外承诺。
103
+
104
+ ## 6. 阶段路线与退出条件
105
+
106
+ | 阶段 | 目标与主要交付 | 退出条件 |
107
+ | --- | --- | --- |
108
+ | 一:公共核心 | 核心边界、内部程序入口、新版 Skills 接入、旧流程删除、安装与测试闭环 | 两个入口操作同一 run,遵守相同门禁;正式发布入口唯一,旧直写链无残留 |
109
+ | 二:协议入口与执行证据 | 版本化 CLI JSON、真实验证执行器、证据来源分级、MCP 薄封装 | 声明与实测不可混淆;失败、超时、快照变化、重试有明确行为 |
110
+ | 三:跨 Agent 接续 | 运行交接包、首个宿主适配、两个真实宿主交接 | 新宿主读取同一需求、方案、决定、代码和有效证据,继续到交付 |
111
+ | 四:证据独立校验 | 证据清单、verify、CI 校验、导出与脱敏 | 在明确可信前提下独立核验产物、快照和证据关联,发现失效和内容变化 |
112
+ | 五:按需求团队化 | 控制台、远程执行、团队存储及身份权限 | 试点证明收益,权限和执行边界经过验证,再扩大使用范围 |
113
+
114
+ 顺序不是要求每阶段同时覆盖全部宿主。CLI 优先验证契约,MCP 复用接口;优先选择两个实际可用的宿主。Codex / Claude 可能只需 Skills、CLI 或 MCP 接入;只有出现宿主特定能力需求时才增加专用 Adapter。Pi 可优先复用参考项目中的经验,OpenHands 远程执行后置。
115
+
116
+ ## 7. 跨 Agent 交接的最终验收场景
117
+
118
+ 1. Agent A 创建 run,保存需求和方案,记录对应版本的人工决定。
119
+ 2. 保存运行状态,停止 A;Agent B 使用生成的交接包恢复同一 run。
120
+ 3. B 能获取真实代码和产物,识别已完成事项、未决问题、有效证据及下一步。
121
+ 4. B 完成实现、验证、审查和交付;仍受同一套门禁约束。
122
+ 5. 修改方案、代码或报告后,相应旧批准或旧证据不能继续满足交付。
123
+ 6. 独立校验器报告证据链条、缺失项、例外和可信边界。
124
+
125
+ 交接包由权威状态生成,不成为第二份可独立写入的运行状态。代码摘要不能重建未提交代码:同工作区交接与跨机器交接分开验收,后者需解决补丁、快照或提交的实际传输。
126
+
127
+ ## 8. 衡量方式
128
+
129
+ 北极星目标:**一个项目运行能否在不同 Agent 之间交接后继续完成,并产生可独立检查的交付证据。**
130
+
131
+ 第一阶段先衡量入口一致性、完整流程成功率及安装后可运行性。跨 Agent 阶段再选 6~10 个真实 M/L 功能或缺陷,与现有 Skills 模式比较:交接后的重复工作、缺失或失效证据比例、交付完成率、总耗时、人工纠正次数和审查问题的实际有效性。
132
+
133
+ 方案批准前写入次数只能在有相应观测能力的环境中统计;不能观测时标记未知。原始发现数量不能直接代表审查质量。安全保证和效率收益分别衡量,避免用支持 Agent 数量代替价值验证。
134
+
135
+ ## 9. 仓库与实施原则
136
+
137
+ - 当前仓库是唯一主干,阶段一不新建第三个核心仓库,不拆分多个发布包。
138
+ - 新代码在独立开发分支实施,小步提交;设计文档提交不代表实现已经开始。
139
+ - 不为旧调用保留转发壳,不建设迁移工具;需要改变格式时明确拒绝不支持的数据,不静默重置。
140
+ - 先解决已存在的依赖,再决定目录细分;不引入通用插件总线、事件溯源或存储框架。
141
+ - 数据库、Nacos、Wiki、CodeGraph、DocNexus 等现有能力保持各自职责,不因抽取核心而扩张到远程执行平台。
142
+ - 不把方案讨论自动转化为审批、发布 npm、修改另一个仓库或执行实际业务流程的授权。
143
+
144
+ 第一阶段的任务、接口边界、测试和完成定义见[详细开发方案](workflow-core-phase-one.md)。
@@ -0,0 +1,41 @@
1
+ # 第一阶段实施报告:公共核心与 Skills 接入
2
+
3
+ 状态:已实现。真实目标 Claude 模型的 trigger eval 已按 [Issue #8](https://github.com/guilianerde/skills-init/issues/8) 标记为 `deferred` 后续处理。日期:2026-11-17。开发分支:`codex/extract-workflow-core`,验证代码基线:`f270ed2`。
4
+
5
+ 本报告记录第一阶段实际交付、验证边界和后续入口;接口定义见 [Workflow Core 内部接口](../workflow/references/core-api.md),执行规则见 [执行约定](../workflow/references/execution.md),原始方案见 [第一阶段方案](workflow-core-phase-one.md)。
6
+
7
+ ## 交付结果
8
+
9
+ - `workflow/core/index.mjs` 提供唯一的 `createWorkflow({ root, documentPolicy })` 内部入口,覆盖需求绑定/查询、派生索引、运行、快照、正式产物收尾/恢复/中止和审查交接。
10
+ - `run.mjs`、`artifact.mjs`、`requirement.mjs`、`review-handoff.mjs` 保留 CLI 参数解析与人类可读输出,生命周期写操作统一进入核心;脚本不再转导出底层 `bind / which / reindex`。
11
+ - 需求树仍以 Markdown 和 `meta.json` 为事实来源。原子写、需求级锁、revision、pending operation identity、成功 finalize 重放和恢复冲突检查继续复用。
12
+ - `artifact.mjs finalize` 使用真实 Skills 模板策略完成 lint、发布、归档、版本与证据登记;安装后的 CLI、内部核心和发布 tarball 已验证操作同一运行。
13
+ - `requirement.mjs path`、`nextPath()`、旧 `sync` 版本 bump、旧导出与自动迁移入口已删除。正式正文只通过 finalize 发布。
14
+ - `reindex` 只允许写 `artifacts`、`latest`、`indexed_at`;无法确认版本的固定文件标记为 `version: null, registered: false`,不提升权威版本、不归档、不生成证据。
15
+ - 项目配置绑定目标 root。多环境 `--copy` 的等价 profile 自动复用;内容不同时通过 `workflow-run/profile-source.json` 和 `config --profile-source` 明确选择。
16
+ - 稳定错误通过 `WorkflowError.code / details / cause` 暴露;调用方不解析中文消息。
17
+
18
+ ## 验证证据
19
+
20
+ 以下为本分支最终验证范围:
21
+
22
+ - 非 upload 全量测试:290 项,259 pass、31 个平台项 skip、0 fail;覆盖核心、运行门禁、需求、文档、安装、打包、Review、DocNexus、Nacos 等本机可运行场景。
23
+ - 安装器专项:30 项,26 pass、4 个软链接平台项 skip、0 fail;真实创建单一来源、软链接和 `--copy` 目录,并验证 profile 来源选择。
24
+ - npm 发布包测试:1/1 通过;打包后安装 CLI 与全部 skills,执行安装后的脚本,再卸载并保留用户产物。
25
+ - 真实 DocNexus `0.28.3` 全新安装通过;导入并查询到 6 个 `doc-template`,`project-review/checklist.md` 为 4000 个 Unicode 字符。对应安装阻断已由 [Issue #9](https://github.com/guilianerde/skills-init/issues/9) 修复关闭。
26
+ - GitHub CI:Ubuntu Node 22 / 24 跑完整测试与包测试,Windows Node 22 跑共同核心与流程测试,全部通过:https://github.com/guilianerde/skills-init/actions/runs/44045688209
27
+ - Windows 本机 `test-upload.mjs` 存在 Node/libuv 原生崩溃,作为平台限制未计入本地非 upload 全量;对应改动仍需 Linux CI 证明。
28
+ - `eval:triggers` 默认模型当前返回 provider 错误 `InvalidEndpoint.ClosedEndpoint`;评估器已修正为把这种“无工具调用的错误文本”记为 `error` 并返回非零退出码。
29
+ - 切换到 `--model sonnet` 后实际由配置网关映射到 `glm-5.2`,全量 46 条得到 22/46;该模型不会按 Claude 的本项目 Skills 元数据执行自动触发,因此结果不能冒充 Anthropic Claude 的触发验收。评估器同时限制为 `Skill` / `Read` 工具,并在普通探索后继续等待真正的 skill 选择,避免第一工具误判。结果文件会记录请求模型、每次请求的实际模型和 `--require-model` 要求;任一次缺失或不符合目标模型都会返回非零退出码。
30
+
31
+ 真实目标 Claude 模型的触发验收仍由 [Issue #8](https://github.com/guilianerde/skills-init/issues/8) 跟踪;该事项已明确标记为后续处理,不阻塞第一阶段交付。
32
+
33
+ ## 破坏性变化
34
+
35
+ 旧流程已确认没有使用者。包含第一阶段的下一版本计划为 `0.36.0`,不提供兼容壳、双写、迁移工具或弃用期。发布说明必须列出被删除的命令、导出和字段变化;已有业务工作区中的正文、历史归档和运行数据不会被自动删除。真正更新包版本和发布 npm 仍需单独的发布流程。
36
+
37
+ ## 限制与第二阶段入口
38
+
39
+ - 第一阶段内部 API 不是外部 JSON Schema、CLI 协议或 SDK,不稳定承诺不扩展到第二阶段外部接口。
40
+ - 验证执行器、可信执行来源分级、MCP、Agent Adapter、远程服务、多人权限和证据独立校验不在本阶段实现。
41
+ - 第二阶段可从 `createWorkflow` 的稳定操作面派生 CLI JSON/MCP 薄封装,但不应复制 run-gates、快照、产物版本或证据规则。
@@ -0,0 +1,317 @@
1
+ # 第一阶段:Skills 与内部程序入口共用核心
2
+
3
+ 状态:已实现。真实目标 Claude 模型的 trigger eval 已按 [Issue #8](https://github.com/guilianerde/skills-init/issues/8) 标记为 `deferred` 后续处理。日期:2026-11-16。实现结果见[第一阶段实施报告](workflow-core-phase-one-report.md)。
4
+
5
+ 修订:2026-11-17,根据设计质检补齐项目配置隔离、pending 操作身份、finalize 成功重放和非 run 写操作契约;对应验收项已同步更新。
6
+
7
+ 同日决策:按 [Issue #3](https://github.com/guilianerde/skills-init/issues/3) 和用户确认,删除旧直写流程,不再将 nextPath / sync 作为兼容接口纳入核心。以下 4.5 节为最终决策。
8
+
9
+ [整体目标方案](workflow-control-roadmap.md) · [当前架构](development.md) · [当前执行约定](../workflow/references/execution.md)
10
+
11
+ ## 1. 目标与范围
12
+
13
+ 以当前仓库为主干,完成公共核心抽取,使现有 Skills 脚本和一个内部 Node.js 入口调用同一套领域实现。第一阶段必须跑通完整流程,不能只添加一个导出文件后宣告完成。
14
+
15
+ 旧流程已无用户,不承担其兼容义务。阶段一主动删除旧直写流程、旧命令、旧导出、迁移分支及仅服务这些路径的文档和测试,不提供转发壳、双写或弃用过渡。Skills 作为新核心的接入方式保留,旧流程元素不因曾被 Skills 调用而成为保留条件。新流程仍需要的锁、快照、证据和收尾恢复逻辑可以复用,不为了重构而全部重写。
16
+
17
+ ### 范围内
18
+
19
+ - 运行与需求绑定、阶段和 revision、门禁、代码快照、证据登记与关联。
20
+ - 产物版本、文档审查规则、正式收尾及 pending_finalization 恢复 / 中止。
21
+ - 文件系统存储、锁和原子替换的现有能力。
22
+ - Skills 脚本调用调整、模板校验接线、安装打包、相关文档和测试。
23
+ - 内部入口示例,以及它与 Skills 入口共享同一运行的集成验证。
24
+
25
+ ### 范围外
26
+
27
+ - 新的公共 CLI 命令产品、MCP Server、外部 SDK 和完整 JSON Schema 协议。
28
+ - Pi / Codex / Claude / OpenHands 专用 Adapter 或会话管理。
29
+ - 真实验证执行器、证据分级升级、独立审查进程、人类身份认证及写入强制拦截。
30
+ - 跨 Agent 完整运行交接包、SQLite、Web UI、远程服务、多用户权限。
31
+ - 导入整个 project-agent、重写数据库 / Wiki / Nacos 等能力型 Skills。
32
+
33
+ 现有审查 handoff 必须继续可用,但不将其包装为完整的跨 Agent 恢复能力。现有 CLI 脚本继续作为 Skills 的运行入口,范围外的是新建正式外部协议。
34
+
35
+ ## 2. 当前基础与需要解决的耦合
36
+
37
+ 基准为当前主干代码;实施开始时记录确切 commit 和工作区状态。
38
+
39
+ | 当前位置 | 现有职责 | 阶段一处理 |
40
+ | --- | --- | --- |
41
+ | `workflow/lib/runs.mjs` | 运行、阶段、checkpoint、完成校验、状态展示 | 规则和状态服务纳入核心;脚本命令提示移到入口层 |
42
+ | `workflow/lib/run-gates.mjs` | 需求 / 方案 / 验证 / 审查 / 交付关联 | 保持唯一实现,不在入口重复判断 |
43
+ | `workflow/lib/code-snapshot.mjs` | Git 与工作区快照 | 纳入核心依赖,保留快照范围语义并测试 |
44
+ | `workflow/lib/artifact-finalize.mjs` | 发布、版本、待完成事务及恢复 | 保留恢复能力;分离 Skills 模板选择与领域规则 |
45
+ | `workflow/lib/meta-store.mjs` | 锁、读取和元信息更新 | 作为文件系统实现,不新增无用途的通用 Store 层 |
46
+ | `workflow/lib/requirements.mjs` / `requirement-read.mjs` | 绑定、索引、目录读取 | 纳入运行生命周期需要的依赖闭包;梳理历史迁移分支 |
47
+ | `workflow/lib/project.mjs` / `workspace-read.mjs` | 布局、画像和工作区读取 | 分清核心必要配置与宿主 / 展示逻辑,避免整文件机械搬迁 |
48
+ | `workflow/scripts/run.mjs` | 参数解析、状态和快照调用、JSON 输出 | 改成内部入口的薄调用方 |
49
+ | `workflow/scripts/artifact.mjs` | 模板解析、lint、正式产物操作 | 保留 I/O 参数处理,将校验能力按明确契约接入核心 |
50
+ | `workflow/scripts/review-handoff.mjs` | 生成审查 packet、输入与结果结构 | 可复用的组装逻辑移出脚本,命令保留参数和输出 |
51
+
52
+ 现有 `workflow/lib` 已不反向依赖 scripts,但业务能力仍有分散在脚本中的部分,也没有统一受支持的程序入口。重构要解决真实依赖,不只改目录名。
53
+
54
+ ## 3. 目录与依赖规则
55
+
56
+ 建议初始落点保持在 workflow 安装单元内,避免引入新的包和跨安装目录依赖:
57
+
58
+ ```text
59
+ workflow/
60
+ core/
61
+ index.mjs 内部入口与实例装配
62
+ runs.mjs 运行操作
63
+ run-gates.mjs 门禁规则
64
+ code-snapshot.mjs 快照
65
+ artifact-finalize.mjs 产物收尾与恢复
66
+ document-review.mjs 文档审查证据
67
+ review-handoff.mjs 审查交接组装
68
+ ... 实际需要的模型、布局和存储依赖
69
+ integrations/
70
+ skill-document-policy.mjs Skills 模板解析与校验装配
71
+ scripts/ 参数解析、文件输入、展示及调用
72
+ lib/ 仍被其他功能使用、未纳入核心的工具
73
+ examples/
74
+ workflow-core.mjs 内部调用示例
75
+ tests/
76
+ ... 原有测试与新增边界 / 集成测试
77
+ ```
78
+
79
+ 先用少量模块,不为每个概念预建子目录。最终文件列表在依赖盘点后确定,但以下边界必须满足:
80
+
81
+ 1. Skills 脚本和内部示例通过 `core/index.mjs` 调用运行生命周期能力,不深层导入私有实现。
82
+ 2. 核心不导入 scripts、SKILL 文本、Pi、MCP 或 Agent 会话。
83
+ 3. 核心可以使用 Node.js 文件和 Git 能力;阶段一不追求所有模块纯函数化。
84
+ 4. 共享纯模型只能有一份;核心不得依赖含模板解析或展示逻辑的外围模块。必要时拆出最小共用模块。
85
+ 5. 状态写入继续通过统一元信息写入机制。入口不得自行修改 meta.json 或重复执行门禁判断。
86
+ 6. 技术 / 上线方案、独立审查和 Wiki 相关运行的现有规则不能在抽取时遗漏;能力型 Skills 本身不整包进入核心。
87
+
88
+ ## 4. 内部接口设计
89
+
90
+ 提供 `createWorkflow({ root, documentPolicy })`,返回作用于明确项目根目录的对象。无全局单例,不依赖调用者当前目录,也不在 import 或构造时写文件、启动子进程或创建 run。
91
+
92
+ `root` 必须是明确的绝对项目路径。项目配置从目标 root 下的项目配置位置解析,不得优先读取或自动回退到核心模块所在项目的 profile。入口可以先将命令行路径转成绝对路径;核心实例不能依赖后续的 process.cwd() 变化。
93
+
94
+ 配置解析采用同一规则:`workflow-run/profile-source.json` 的显式选择优先;没有显式选择时,优先使用目标项目规范安装位置 `.agents/skills/workflow/`;只有规范位置不存在时,才检查目标项目其他已支持的安装位置。多个候选若指向同一真实目录,或不同拷贝中的 `profile.json` / `profile.local.json` 内容完全相同,视作同一配置;若是不同配置且无法唯一选择,明确报告歧义,不任取一个。`requirement.mjs config --profile-source` 只能选择目标 root 内受支持的安装目录,`auto` 清除显式选择。无配置时按现有各操作的缺省值或必填条件处理,不读取别的项目配置,也不在查询中创建配置。保留团队 profile 与本机覆盖项各自现有的合并语义。
95
+
96
+ 画像、工具链和文档 policy 的项目资源都绑定目标 root;包内 skill.json 等静态规则可以随代码分发,但不能因此从包所在项目读取业务配置。第一阶段只增加受支持安装目录内的显式来源选择,不接受任意配置文件位置。源码入口、打包入口与安装后脚本针对同一 root 必须解析出同一配置来源。
97
+
98
+ 内部接口是受信任程序入口,不是安全边界;调用者能直接访问本机数据这一事实不因接口命名改变。它不认证批准人,也不禁止模型通过其他途径改文件。
99
+
100
+ ### 4.1 操作表
101
+
102
+ 下列名称作为阶段一目标契约,实施时若调整须同步文档、Skills 和测试。
103
+
104
+ | 分组 | 方法 | 语义 |
105
+ | --- | --- | --- |
106
+ | requirements | `bind`、`which` | 绑定及查询需求,保留现有目录与项目语义 |
107
+ | maintenance | `reindex` | 显式刷新派生索引;不写正式正文、不归档、不提升版本、不推进运行或生成证据 |
108
+ | runs | `start`、`status`、`get` | 创建和查询;多 run 时由明确 id 选择 |
109
+ | runs | `save`、`complete`、`cancel` | 统一状态变更与完成门禁 |
110
+ | snapshots | `capture` | 获取某运行对应的代码快照 |
111
+ | artifacts | `finalize`、`resume`、`abort` | 校验、发布、索引和中断处理 |
112
+ | reviews | `prepare` | 生成代码 / 文档审查交接材料 |
113
+
114
+ 批准、验证记录和交付决定在阶段一通过现有 checkpoint / finalize 语义进入核心;不新增一套 Human API,也不声称这些声明已经过身份或执行认证。后续正式协议阶段再拆分操作面。
115
+
116
+ ### 4.2 参数与结果
117
+
118
+ - `root` 明确业务项目根,`branch` 明确操作分支;入口可通过只读 Git 查询帮助解析,写入仍检查真实分支条件。
119
+ - 已有运行的写操作显式携带 `id` 和 `expectedRevision`;新建运行、需求绑定与索引维护按 4.5 节各自条件处理,不强套 run revision。不要在 API 内重新读取最新 revision 后静默绕过冲突。
120
+ - revision 检查由具体领域操作在锁内执行,不在入口统一提前拒绝;finalize 的成功重放例外见 4.4 节。普通更新或不同 finalize 请求仍必须拒绝旧 revision。
121
+ - 状态查询返回 run、revision、证据有效性和结构化待办 / 阻塞;存在 pending_finalization 时明确返回其 `operationId`、所属 run、基准 revision 和产物种类。人类提示、脚本命令及中文文案由入口层生成。
122
+ - 方法返回普通可序列化对象。领域失败抛出含 `code`、`message`、必要 `details` 的统一错误;先覆盖实际需要的错误,不建立庞大分类框架。
123
+ - 至少区分输入错误、run 不存在、revision 冲突、pending 操作不匹配、阶段不允许、门禁失败、证据失效、待恢复收尾和存储错误。保留底层原因,不把未知 I/O 错误伪装成门禁拒绝。
124
+ - 核心不写 stdout / stderr、不调用 process.exit;脚本负责输出和退出码。
125
+ - 阶段一沿用同步文件操作即可,不因未来远程执行而强制把所有方法改成异步。
126
+
127
+ 示意调用(设计示例,不代表当前已有 API):
128
+
129
+ ```js
130
+ import { createWorkflow } from '../workflow/core/index.mjs';
131
+
132
+ const workflow = createWorkflow({ root: projectRoot });
133
+ const binding = workflow.requirements.bind({ name, branch, base });
134
+ const { run } = workflow.runs.start({
135
+ branch, kind: 'feature', size: 'M', dir: binding.dir, input,
136
+ });
137
+ workflow.runs.save({
138
+ branch, id: run.id, expectedRevision: run.revision,
139
+ input: checkpoint,
140
+ });
141
+ ```
142
+
143
+ `start` 不自动伪造用户调研、需求或方案已完成。示例在临时项目运行,不修改仓库真实业务状态。
144
+
145
+ ### 4.3 文档校验边界
146
+
147
+ 保留领域完整性校验和内容校验的区别:
148
+
149
+ - 核心始终执行产物类型、运行阶段、引用 hash、批准和审查等领域检查。
150
+ - `documentPolicy` 负责解析生效模板并校验正文,返回结构化错误 / 警告;Skills 使用真实模板来源的实现。
151
+ - 从 `resolve.mjs` / `lint-doc.mjs` 提取必要可复用函数,外围装配不得通过 import 脚本主函数来运行 CLI。
152
+ - 需要正式发布正文而未提供 policy 时,返回明确的配置错误,不默认跳过校验。
153
+ - 程序入口的完整流程测试使用与 Skills 相同的 policy。纯规则单元测试可以使用明确的测试替身,但不据此声称验证了模板集成。
154
+ - pending_finalization 保留恢复所需的已校验内容和引用;恢复时继续复核领域门禁,不在恢复路径绕过内容完整性检查。
155
+
156
+ 政策注入是受信任代码扩展点,不是抵抗恶意调用者的可信证明。阶段一不把可注入策略扩展为通用插件系统。
157
+
158
+ ### 4.4 收尾重试与 pending 操作身份
159
+
160
+ 保留当前 finalize 对相同请求的成功重放支持。请求标识由运行、原始 expectedRevision、产物种类、实际发布正文摘要、checkpoint 及审查输入 / 结果等影响操作的字段确定;两个入口必须使用相同的标准化规则,不能各算一份请求标识。
161
+
162
+ - 在锁内先识别该请求是否已有成功结果。只有记录确实匹配、当前正式产物仍匹配成功记录且没有冲突 pending 时,返回 `alreadyFinalized`;不重复校验发布、不追加历史、不增加 revision 或重复归档。此返回只证明原操作已经完成,不重新赋予当前代码有效的交付证据。
163
+ - 没有匹配成功记录时执行正常 revision 与门禁检查;不同内容或不同操作不能借成功重放绕过旧 revision 检查。成功记录不匹配或产物后来改变时明确返回冲突,不自动刷新 revision 再写入。
164
+ - 同请求对应的 pending 可继续处理既有操作,不能新建一笔。阶段一只保留现有收尾重放能力,不建设持久化的通用幂等请求服务,也不承诺无限期保存历史响应。
165
+ - 每次新建 pending 都生成唯一 `operationId`。`resume/abort` 必须显式提供 `{ branch, id, expectedRevision, operationId }`,在同一需求锁内核对运行、当前 revision、pending 基准 revision 及操作 ID,然后才处理文件。
166
+ - `runs.status()` 对 pending 返回顶层 `runRevision`,并返回 `pending.operationId`、`pending.runId`、`pending.kind`、`pending.baseRevision` 和 `pending.runRevision`。参数 `expectedRevision` 固定等于 `runRevision` / `pending.runRevision`;pending 的 `baseRevision` 只用于内核核对它仍等于已保存运行的 revision,不作为调用方传入值。
167
+ - pending 存在时,`current` 保留 meta 中已提交的运行快照,可能仍是 `baseRevision`;调用方必须读取顶层 `runRevision` 发起 resume/abort。resume 成功后提交 pending 预先计算的目标 revision;abort 不提交该目标运行,保留已保存的 base revision。
168
+ - 示例:`status` 返回 `runRevision: 9`、`pending.baseRevision: 8` 时,调用 `resume({ id, expectedRevision: 9, operationId })`。传 8 返回 `REVISION_CONFLICT`;operationId 不存在或已替换返回 `PENDING_OPERATION_MISMATCH`。
169
+ - 若 pending 已消失或被另一笔替换,返回明确错误,不自动选择“当前那笔”。无论 abort 是否改变 run revision,都不能重复使用已取消操作的 ID。失败返回可包含当前状态,调用方核实后另发请求,不能自动改绑新 operationId。
170
+ - 恢复继续执行已有的正文 hash、文件冲突和领域门禁检查;操作 ID 匹配不能代替证据校验。
171
+
172
+ 这解决两类不同问题:成功响应丢失后安全重试,以及旧恢复 / 中止请求不能误处理后来创建的操作。
173
+
174
+ ### 4.5 删除旧直写链,限定索引维护
175
+
176
+ 删除公开 `requirement.mjs path`、`nextPath()`、旧 `sync` 命令及其版本 bump 语义。所有受控的正式产物创建、正文替换、版本提升和归档统一进入 `artifacts.finalize`;`resume/abort` 只处理其产生的待完成事务,不构成另一条发布路径。不保留“非 run 文档可以直接覆盖后 sync”的例外,需要正式发布时创建相应类型的运行。
177
+
178
+ 从 sync 提取必要的纯索引计算逻辑供核心内部复用;提供明确的 `maintenance.reindex` 与对应 `requirement.mjs reindex [--all]` 维护命令。它只刷新 `artifacts/latest` 等派生展示索引及必要的索引更新时间:已有权威版本不能提升,无法确认版本的文件报告为未登记,不默认补成有效版本。不得修改正文、归档、绑定、runs、run revision、批准及证据,也不能接受 bump 参数。
179
+
180
+ `reindex` 的最终字段白名单固定为 `artifacts`、`latest`、`indexed_at`。其中 `indexed_at` 只在 `artifacts` 或 `latest` 实际变化、或旧数据还没有该字段时更新;`updated` 表示正文更新时间,不能被 reindex 覆盖。无法确认权威版本的固定文件名在 `artifacts` 中持久标记 `version: null, registered: false`,仍可见但不算有效版本;同一项以 `unregistered` 返回。成功结果包含 `ok`、`dir`、`changed`、兼容字段 `artifacts`(数量)、`artifact_count`、`latest`、`versions`、`unregistered`;`--all` 返回逐需求 `results`,受阻项保留 `error` / `code`,其他需求继续处理。损坏 JSON、pending 冲突和缺失需求直接失败,不写入派生索引。
181
+
182
+ `which` 改为只读查询,不再隐式调用写入型 sync;需要最新文件信息时计算只读视图。bind 的写入、finalize 的索引登记以及 Wiki / DocNexus 发布元信息变更后的索引刷新,都改用明确的内部索引能力或维护入口。发布元信息工具保留自身用途,但不能借刷新索引修补正文 hash、提升版本或重新生成收尾凭据;不一致仍按门禁失效规则处理。
183
+
184
+ 需求级操作可能发生在 run 创建前,按需求目录元信息锁保护,不虚构 run ID 或 revision。
185
+
186
+ | 写入类别 | 接口 | 条件与保护 |
187
+ | --- | --- | --- |
188
+ | 已有 run 更新 | runs.save / complete / cancel、artifacts.finalize | run ID 与 expectedRevision;统一需求锁;finalize 按 4.4 的重放例外处理 |
189
+ | pending 恢复 / 中止 | artifacts.resume / abort | run ID、expectedRevision 和 operationId 全部匹配,锁内检查 |
190
+ | 创建运行 | runs.start | 校验需求、分支及现有活动运行,在锁内创建或按现有规则返回运行,不覆盖旧状态 |
191
+ | 需求绑定 | requirements.bind | 允许尚无 run;锁内读取当前需求元信息后合并绑定,拒绝非法目标及 pending 冲突,不用调用方旧快照覆盖其他字段 |
192
+ | 索引维护 | maintenance.reindex | 锁内读取当前状态和产物,拒绝 pending 冲突,只刷新明确允许的派生索引字段;其余元信息保持不变 |
193
+
194
+ reindex 后若正文与运行收尾凭据不符,状态 / 门禁检查仍应识别为失效。维护调用遇到 pending 必须拒绝;`--all` 逐需求加锁,报告成功和受阻项,不声称跨目录原子性。finalize / resume 在已有锁和事务内调用纯索引计算函数,不递归调用公共 reindex,也不通过维护入口绕过 pending 保护。
195
+
196
+ 阶段一不新增需求级 revision 协议。上述操作必须锁内读取最新值并限定变更字段;锁保护受控调用之间的竞争,不承诺阻止外部编辑器直接改正文。`list`、`pending` 保留为 Skills 外围只读查询,`config` 保留为 Skills 外围配置入口;三者不进入核心生命周期,也不得写 run、产物索引或证据。`workflow/scripts/requirement.mjs` 不再转导出 `bind / which / reindex / reindexRequirement`。
197
+
198
+ 删除清单必须覆盖实现、CLI 分支、导出、Skills 指引、模板、安装器引用与仅用于旧行为的测试。替换消费者后删除失去用途的 helper;保留新流程仍需要的归档能力。程序不自动删除业务工作区 `workflow-run/tmp/old-artifacts/` 中的历史文件;删除旧代码与清空历史数据是两件事。
199
+
200
+ ### 4.6 发布与兼容决定
201
+
202
+ 维护者和用户已确认旧流程没有使用者,允许在阶段一移除 `path / nextPath / sync bump`、旧导出、迁移和兼容壳,不做双写、弃用期或自动迁移。包含本阶段的下一版本按项目当前的 pre-1.0 规则发布为 `0.36.0`,发布说明必须显式列出破坏性命令变化;本阶段内部 Node API 只供同包调用,不承诺成为第二阶段的外部稳定协议。
203
+
204
+ 已有 `workflow-run/docs/requirements/`、历史归档和正文不会被自动删除或改写。旧运行仍按当前门禁读取;因命令或格式不再支持而无法继续的数据明确拒绝并提示人工处理,不能写成虚假的恢复成功。真正发版、更新 package 版本和发布 npm 包仍需单独执行发布流程,本次文档和执行只记录决策,不把本分支自动视为已发布。
205
+
206
+ ## 5. 数据和功能处理原则
207
+
208
+ - 继续以 meta.json 和 Markdown 为事实来源,避免另建核心专用数据库或第二份状态。
209
+ - 保留需求、方案、审查和交付版本之间的关联,不能因为 API 更简洁而移除有效性检查。
210
+ - 不把“验证步骤完成”改成“所有测试通过”。现有 passed / failed / unverified 与严重风险接受规则单独测试,不在重构中暗改产品政策。
211
+ - 快速通道、feature / bug、独立 review、tech / release / wiki 的现有差异保留;需要改变业务语义时单独列出决定,不与模块搬迁混合。
212
+ - 旧流程迁移、兼容转发及废弃写入分支纳入显式删除清单,调用方一次性改用新路径;不保留过渡期。与本次流程重构无关的功能不顺带删除。
213
+ - 若格式发生不兼容变化,明确格式标识和拒绝行为;不给旧数据写默认值以制造“恢复成功”。不自动清空旧目录。
214
+ - 修复过程中确需吸收 project-agent 的核心改动时,记录问题和测试依据;Pi 会话与执行器仍留在阶段一范围外。
215
+
216
+ ## 6. 工作包与提交顺序
217
+
218
+ 建议开发分支:`codex/extract-workflow-core`。文档可以先进入主干,实现从当时主干创建分支。
219
+
220
+ | 工作包 | 实施内容 | 输出与退出检查 |
221
+ | --- | --- | --- |
222
+ | A:基线与依赖 | 记录 commit;跑现有测试;盘点脚本、核心、安装器及跨 Skill 引用;核对参考项目差异 | 新流程能力清单、旧流程删除与消费者替换清单、基线结果、需吸收的修复列表 |
223
+ | B:核心边界 | 移动 / 拆分必要模块;集中领域和存储依赖;提取脚本中的 handoff 业务逻辑 | 核心不反向依赖脚本;相关领域测试通过 |
224
+ | C:内部入口 | 实现 createWorkflow、按 root 配置解析、完整操作表、revision / operationId、收尾重放、错误与结构化状态;装配文档 policy | 无 CLI 进程也能运行完整流程;跨项目配置隔离;缺少 policy 明确失败 |
225
+ | D:Skills 接入与旧链删除 | 调整 run / artifact / requirement / review-handoff 及消费者;删除 path / nextPath / sync bump、兼容迁移和旧说明;接入受限 reindex | 正式正文只经 finalize 发布;旧调用和导出清零;新流程 Skills 能力可用 |
226
+ | E:安装与集成 | 更新安装复制与包清单;添加内部示例;验证装包后运行、双入口接续、配置来源及非 run 维护 | 实际安装目录无缺文件或开发目录依赖;同一 run 可交替推进;配置来源一致 |
227
+ | F:收尾 | 全量测试、触发评估、打包测试;更新架构文档和完成状态 | 验收清单全通过,记录已知限制及后续任务 |
228
+
229
+ 每个工作包保持可审查提交。先跑基线以识别已有失败;阶段一期间新增失败必须解决,不能仅以“基线也有失败”排除与本次改动相关的回归。首轮依赖盘点后再估算工期,不先承诺固定天数。
230
+
231
+ ## 7. 验证设计
232
+
233
+ ### 7.1 双入口集成场景
234
+
235
+ 使用同一临时 Git 项目、同一分支和同一文档 policy:
236
+
237
+ 1. 通过 Skills 脚本绑定需求并创建 M 规模 feature 运行。
238
+ 2. 内部 API 读取同一 run,完成必要前置步骤和需求 / 方案产物操作。
239
+ 3. 通过脚本记录当前方案确认并推进实现,API 观察同一 revision 和批准关联。
240
+ 4. 在 fixture 中修改代码,登记如实的验证声明和结构化审查结果,完成报告。
241
+ 5. 两入口交替记录交付选择与产物收尾,最终完成同一 run。
242
+ 6. 模拟 finalize 成功但响应丢失,从另一入口用同一原请求重试,返回已完成结果,revision、历史、版本及归档不重复变化。
243
+ 7. 在独立用例中插入失效条件,检查两个入口的领域错误 code 一致。
244
+
245
+ 集成测试里的模拟验证和审查结果是 fixture,用于检查流程,不宣称代表真实测试执行或独立模型审查。该测试证明入口互操作,不等于真实宿主间交接已完成。
246
+
247
+ ### 7.2 必须覆盖的失败与恢复场景
248
+
249
+ | 场景 | 预期 |
250
+ | --- | --- |
251
+ | 两调用方持有同一 revision,先后进行不同更新 | 第一次成功,第二次冲突;不得丢失第一次结果 |
252
+ | 同一进程为两个 root 创建实例,项目配置刻意不同 | 基线、审查排除项、产物项目名和配置写入位置各自隔离;不回退到模块所在项目 |
253
+ | 源码入口、打包入口及安装脚本操作同一 root | 配置来源与解析值一致;目标项目无配置或存在歧义时按契约处理 |
254
+ | finalize 成功响应丢失,原请求携带旧 revision 重放 | 匹配记录时返回 alreadyFinalized,不重复状态变更;改变正文 / 输入后的旧请求仍冲突 |
255
+ | pending A 被中止后,以相同 run revision 创建 B,再收到 A 的恢复 / 中止请求 | operationId 不匹配,拒绝旧请求;B 的文件、pending 和 run 保持不变 |
256
+ | run 尚未创建时执行 bind / reindex | 不要求 run ID;按需求级锁及条件处理,不隐式创建 run 或有效产物凭据 |
257
+ | reindex 重复调用、与状态保存交错 | 派生索引稳定;versions、runs、revision、证据与正文不被改写,不丢失进度 |
258
+ | 有 pending 时执行 bind / reindex | 拒绝冲突写入,要求先处理指定 pending 操作;批量维护如实报告受阻项 |
259
+ | 修改正式正文或放入未登记文件后执行 reindex | 不提升版本、不创建有效凭据;既有凭据失效仍被检测,新文件显示未登记 |
260
+ | 调用旧 path / sync 命令或旧 nextPath 导出 | 入口已不存在,不能通过别名 / 转发继续旧流程;未写文件 |
261
+ | 检查生产调用链与 Skills 指引 | 没有旧 path / nextPath / sync bump 调用,所有正式正文发布汇入 finalize |
262
+ | which / 状态查询及发布元信息刷新 | 查询只读;元信息刷新使用限定索引逻辑,不补造正文收尾凭据 |
263
+ | 无方案或缺少所需批准进入实现 | 拒绝,状态不被部分推进 |
264
+ | 需求 / 方案内容修改 | 旧方案关联或批准不能满足下游门禁 |
265
+ | 验证 / 审查后修改代码或基线 | 旧证据失效,不能完成交付 |
266
+ | 报告修改后使用旧交付决定 | 拒绝,要求针对当前报告重新决策 |
267
+ | 审查覆盖缺失、结果输入不匹配 | 按现有覆盖和关联规则拒绝,不补造已审项 |
268
+ | 存在严重问题但缺少逐项风险接受 | 交付门禁拒绝 |
269
+ | 无模板 policy 或内容校验失败 | 不发布正式产物,不绕过文档校验 |
270
+ | 产物写入 / meta 更新之间中断 | 可恢复或中止;不覆盖第三方改动,不重复归档 |
271
+ | 损坏状态、锁冲突、文件缺失 | 明确报错,不静默创建成功状态 |
272
+ | import / 构造 / 状态读取 | 不创建 run,不修改状态,不向控制台输出 |
273
+
274
+ ### 7.3 现有测试与安装验证
275
+
276
+ 优先复用 `test-run.mjs`、`test-flow-gates.mjs`、`test-requirement-document.mjs`、`test-clarification-artifact.mjs`、`test-tech-document.mjs` 和 `tests/helpers/run-flow.mjs` 中新流程仍需要的场景。删除仅断言旧直写或兼容行为的测试,改以“旧入口不存在、正式发布经过 finalize、reindex 不改变权威状态”的架构与行为测试覆盖;不能为通过重构而删除仍有效的门禁断言。
277
+
278
+ 重点回归 `test-install.mjs`、`test-package.mjs`、`test-links.mjs`、`test-skills-meta.mjs`,以及读取工作流数据的 view / report / document-sources / artifacts 测试。新增少量有实际价值的双入口、错误契约和依赖边界测试,避免为每个转发函数编写重复单测。
279
+
280
+ 收尾执行当前仓库命令:
281
+
282
+ ```bash
283
+ npm test
284
+ npm run test:package
285
+ npm run eval:triggers
286
+ ```
287
+
288
+ 包验证必须覆盖实际 tarball 的安装结果:在临时业务仓库通过安装后的 Skills 脚本调用核心,不允许测试仅在源码树下成功。模板 / DocNexus 外部交互使用项目既有受控 fixture,明确其覆盖边界;不要为测试访问真实业务系统。
289
+
290
+ ## 8. 主要风险与处理
291
+
292
+ | 风险 | 处理 |
293
+ | --- | --- |
294
+ | 移动文件后 profile / 模板相对路径失效 | 同时验证源码位置、打包位置、安装位置以及 copy / 链接模式 |
295
+ | 新门面存在,脚本仍绕过它写状态 | 全仓扫描调用与 meta 写入点,并用双入口测试验证 |
296
+ | 脚本迁入核心时带入 DocNexus / 宿主依赖 | 将模板策略置于外围,核心依赖规则纳入检查 |
297
+ | 抽取时更改业务门禁或丢失异常路径 | 用现有领域测试约束,新增行为单独提交并记录 |
298
+ | 重构膨胀为框架建设 | 保持单包、文件存储和少量模块;不提前加入外部协议或 Adapter |
299
+
300
+ ## 9. 完成定义与后续交接
301
+
302
+ - [x] 新流程 Skills 能力、核心依赖、旧流程删除清单与消费者替换有记录。
303
+ - [x] 内部程序入口完整覆盖范围内操作,不依赖 Agent 会话或 CLI 子进程。
304
+ - [x] Skills 的生命周期脚本与内部程序复用同一规则和存储,并通过真实模板策略与安装包测试验证。
305
+ - [x] 无复制的 run-gates、快照规则和产物版本逻辑。
306
+ - [x] 双入口同一 run 的集成场景及失败路径通过。
307
+ - [x] 两个 root 的配置隔离、多环境 profile 内容等价/显式选择,以及不同入口对同一 root 的配置一致性通过。
308
+ - [x] pending 的 operationId 防误操作与 finalize 成功重放分别验证通过。
309
+ - [x] path / nextPath / sync bump、旧流程兼容迁移及其生产调用已删除,正式正文发布统一走 finalize。
310
+ - [x] bind 与受限 reindex 的写入归属、锁及证据失效测试通过,which 为只读查询。
311
+ - [x] 安装后的 Skills、包内容和流程测试通过。
312
+ - [ ] `eval:triggers` 在真实 Anthropic Claude 环境的 46 条验收已作为 `deferred` 后续事项保留(#8);当前网关模型结果不能冒充目标模型。评估器已完成严格模型身份校验,恢复处理条件已写入 Issue。
313
+ - [x] 数据格式变化及拒绝行为明确;没有旧数据迁移和隐式清理。
314
+ - [x] 文档更新区分已实现能力与后续目标,没有强制管控或实测证据的虚假承诺。
315
+ - [x] 实施报告列出变更、验证结果、限制和第二阶段接入点。
316
+
317
+ 第一阶段交付物是可用的新架构、内部调用示例、测试和文档。第二阶段从该接口发展 CLI JSON、验证执行器和 MCP;不在本阶段顺手接入 Pi 或启动真实业务流程。
package/docs/workflows.md CHANGED
@@ -46,7 +46,7 @@
46
46
  * 知识:交付与审查的 DocNexus 沉淀率(只算真正问过沉淀的,「未询问」「无需沉淀」不计入分母;dev 内部审查不单独询问或重复计入交付沉淀)、正文引用了知识库文档的产物占比;
47
47
  * 各分支链路:方案、交付说明、审查报告、技术方案、上线方案齐不齐,哪些文档还没发布到 wiki。
48
48
 
49
- **完整流程状态与续接**:需求目录的 `meta.json` 同时保存绑定、产物索引和按运行 id 区分的 `runs`。每次运行关联分支,记录阶段、逐步完成标记、上下文、待用户决定、阻塞原因、历史与 revision;完成后保存 `status: completed` 和 `completed_at`。`/workflow status` 查看状态,`/workflow resume [运行id]` 核对后继续;`/workflow view` 展示运行与“已完成”,尚未生成 Markdown 的运行也可见。快速通道保持不绑定、不创建运行状态。完整 dev 在首次落盘前初判规模、选择完整流程并开始记录,需要清单时在 F2/B3 先生成业务场景 clarification.md 并等待产品反馈;F3/B3 技术澄清完成后收尾 requirement.md,再进入 F4/B4 的实现方案,补入此前已确认的进度;后续文档/发布用独立运行保留开发的完成记录。脚本用法见 `workflow/references/runs.md`,`sync` 不会清掉状态。
49
+ **完整流程状态与续接**:需求目录的 `meta.json` 同时保存绑定、产物索引和按运行 id 区分的 `runs`。每次运行关联分支,记录阶段、逐步完成标记、上下文、待用户决定、阻塞原因、历史与 revision;完成后保存 `status: completed` 和 `completed_at`。`/workflow status` 查看状态,`/workflow resume [运行id]` 核对后继续;`/workflow view` 展示运行与“已完成”,尚未生成 Markdown 的运行也可见。快速通道保持不绑定、不创建运行状态。完整 dev 在首次落盘前初判规模、选择完整流程并开始记录,需要清单时在 F2/B3 先生成业务场景 clarification.md 并等待产品反馈;F3/B3 技术澄清完成后收尾 requirement.md,再进入 F4/B4 的实现方案,补入此前已确认的进度;后续文档/发布用独立运行保留开发的完成记录。脚本用法见 `workflow/references/runs.md`,`reindex` 不会清掉状态、版本或证据。
50
50
 
51
51
  **F3 前的业务核对循环**:F1 理解需求后,在 F2 先用 `artifact.mjs finalize --kind clarification` 发布同一需求目录的 `clarification.md`,聚焦角色、正常 / 异常场景、业务规则、范围和业务验收,供你找产品核对与完善 PRD。每轮在同一清单更新答复和状态、追加新问题与反馈记录,保留编号和已确认项,自动归档旧版。业务项未明确时保持 F2 in_progress、运行为 waiting_user;业务明确并完成现状调研后进入 F3,澄清可行性、接口兼容、数据、权限、依赖等技术约束。技术问题改变业务场景时回 F2 更新清单。业务与技术约束均明确后收尾 requirement.md,再进入 F4 写方案。清单是正式产物,纳入视图和统计;没有业务待确认项且用户未要求时可省清单。
52
52
 
@@ -144,7 +144,7 @@ Codex 原生元数据 `dev/agents/openai.yaml` 设置 `policy.allow_implicit_inv
144
144
  | `workflow/scripts/resolve.mjs status` | `/workflow status` 的能力探测(不输出任何凭据) |
145
145
  | `workflow/scripts/resolve.mjs infer-profile` | 按固定规则从构建文件、Makefile、依赖与配置文件、git 推断项目画像草稿,每个字段附依据;不写文件 |
146
146
  | `workflow/scripts/lint-doc.mjs <文档> --skill <skill> [--facts --diff <main>...<dev>]` | 对照当前生效的模板检查必填章节、残留占位符和该 skill 要求的元信息;缺普通章节、顺序不一致为警告;列出待填写位置。技术方案不强制可见元信息,事实核对显式指定三点范围;正文里的类名、文件、接口、表名在 diff 和代码里都找不到时给出警告 |
147
- | `workflow/scripts/requirement.mjs which / bind / path / sync / pending / list / config` | 产物按需求归档(`workflow-run/docs/requirements/<需求>/<项目>/`,两种模式结构相同):查当前分支绑定的需求(没绑定时给出按分支名生成的建议名)、绑定需求名、给出本次落盘路径(不覆盖,带上一版的 wiki 记录)、重建 `meta.json`、列出所有需求;`config` 设置产物位置(文档仓库、项目名、提交提示),`pending` 看文档仓库里还没提交的产物 |
147
+ | `workflow/scripts/requirement.mjs which / bind / reindex / pending / list / config` | 产物按需求归档(`workflow-run/docs/requirements/<需求>/<项目>/`,两种模式结构相同):查当前分支绑定的需求(没绑定时给出按分支名生成的建议名)、绑定需求名、只刷新派生索引、列出所有需求;`config` 设置产物位置(文档仓库、项目名、提交提示、多环境 profile 来源),`pending` 看文档仓库里还没提交的产物。正式正文只通过 `artifact.mjs finalize` 发布 |
148
148
  | `workflow/scripts/view.mjs [--out f] [--open]` | 项目文档视图(`/workflow view`、`npx @rowansenne/workflow-run view`):读需求目录里的产物,生成单个 HTML,按需求列出各阶段、审查记录(各级别数量、复核、与上次对比)、交付记录、沉淀到的知识文档,正文直接渲染;顶部「知识文档」列出每篇知识文档来自哪个需求、哪份产物;数据内嵌,只读、不联网,默认写到 `workflow-run/tmp/view/index.html` |
149
149
  | `workflow/scripts/run.mjs show / start / save / complete / cancel` | 需求 meta.json 中的分支运行记录:恢复、checkpoint、已完成状态与时间、等待用户、修复回退、revision 冲突检查 |
150
150
  | `workflow/scripts/artifacts.mjs [--branch b \| --all]` | 按分支汇总 `workflow-run/docs/requirements/` 下的方案、交付说明、审查报告、技术方案、上线方案及其 wiki 发布记录,给出下一步建议;分支取自文件头元信息(兼容技术方案的隐藏注释与旧可见行)。project-review 据此对照本分支方案、识别复审 |
@@ -0,0 +1,26 @@
1
+ #!/usr/bin/env node
2
+ // 内部程序入口示例:只读查询目标项目的需求绑定和当前运行。
3
+ // 用法:node examples/workflow-core.mjs --root <绝对项目路径> --branch <分支>
4
+ import path from 'node:path';
5
+
6
+ import { createWorkflow } from '../workflow/core/index.mjs';
7
+
8
+ function option(argv, name) {
9
+ const index = argv.indexOf(name);
10
+ return index >= 0 ? argv[index + 1] : null;
11
+ }
12
+
13
+ const root = option(process.argv.slice(2), '--root');
14
+ const branch = option(process.argv.slice(2), '--branch');
15
+ if (!root || !branch) {
16
+ console.error('用法:node examples/workflow-core.mjs --root <绝对项目路径> --branch <分支>');
17
+ process.exit(1);
18
+ }
19
+
20
+ const workflow = createWorkflow({ root: path.resolve(root) });
21
+ const result = {
22
+ root: workflow.root,
23
+ requirement: workflow.requirements.which({ branch }),
24
+ run: workflow.runs.status({ branch }),
25
+ };
26
+ console.log(JSON.stringify(result, null, 2));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rowansenne/workflow-run",
3
- "version": "0.35.0",
3
+ "version": "0.36.1",
4
4
  "description": "项目级 Agent Skills 一键初始化:workflow / dev / project-review / code-graph / database-query / nacos-config / md-to-wiki / 需求文档与技术上线方案生成",
5
5
  "keywords": [
6
6
  "agent-skills",
@@ -33,6 +33,7 @@
33
33
  "code-graph",
34
34
  "nacos-config",
35
35
  "docs",
36
+ "examples",
36
37
  "README.md",
37
38
  "CHANGELOG.md"
38
39
  ],
@@ -41,7 +41,7 @@ description: "Review source code (any language; Java/Spring, Go, TypeScript, Pyt
41
41
 
42
42
  7. **输出报告**:先读 [reporting.md 的第 7 步与 Artifact Location](references/reporting.md)。用 `resolve.mjs template project-review report.md` 取模板;正式报告按 execution.md 用 `artifact.mjs finalize --kind review` 收尾为 review.md 后完整交给用户,灵活模式在对话给 findings。
43
43
 
44
- 8. **沉淀到 DocNexus**:独立审查交报告后读 [reporting.md 的第 8 步](references/reporting.md)。有值得记录的才询问授权,分类用 `resolve.mjs category project-review`;沉淀结果写报告元信息并 sync。dev 内部不执行。
44
+ 8. **沉淀到 DocNexus**:独立审查交报告后读 [reporting.md 的第 8 步](references/reporting.md)。有值得记录的才询问授权,分类用 `resolve.mjs category project-review`;沉淀结果写报告元信息后运行 `requirement.mjs reindex` 刷新派生索引。dev 内部不执行。
45
45
 
46
46
  9. **记录运行反馈**:读 [reporting.md 的第 9 步](references/reporting.md),用 `feedback.mjs add --skill project-review` 记录过程;不写业务内容,失败不阻塞交付。dev 内部交主 agent 统一记录。
47
47
 
@@ -1,6 +1,6 @@
1
1
  # Code Review Checklist
2
2
 
3
- 按维度逐项检查。每个发现需记录:位置(文件+行号)、描述、严重级别(CRITICAL/HIGH/MEDIUM/LOW)、建议。没有问题时该维度标注"通过"。
3
+ 逐维度检查。每条记录位置(文件:行)、描述、严重级别(CRITICAL/HIGH/MEDIUM/LOW)和建议;无问题标“通过”。
4
4
 
5
5
  ## 1. 正确性与逻辑 bug
6
6
  - [ ] 条件判断是否反了 / 漏了分支 / 边界(`==` vs `equals`,数值比较用 `compareTo` 而非 `==`)