ai-delivery-workflow 0.5.0 → 0.5.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 (48) hide show
  1. package/README.md +5 -6
  2. package/bin/ai-delivery.mjs +2 -24
  3. package/docs/CLI-PARAMETER-REFERENCE.zh-CN.md +6 -67
  4. package/docs/DUAL-REPOSITORY-WORKSPACE.zh-CN.md +1 -1
  5. package/docs/FILE-REFERENCE.zh-CN.md +6 -28
  6. package/docs/MAINTENANCE-VERIFICATION.zh-CN.md +2 -2
  7. package/docs/PROJECT-MANUAL.zh-CN.md +23 -38
  8. package/docs/STATE-CLI-MAINTENANCE.zh-CN.md +8 -10
  9. package/docs/STATE-CLI-USER-GUIDE.zh-CN.md +6 -16
  10. package/docs/agents/workflow-manager-acceptance-matrix.md +9 -15
  11. package/docs/agents/workflow-manager-current-state.md +12 -15
  12. package/lib/delivery-state.mjs +59 -910
  13. package/lib/fs-utils.mjs +0 -16
  14. package/lib/project-bootstrap.mjs +21 -58
  15. package/lib/project-installer.mjs +24 -180
  16. package/lib/project-repair.mjs +217 -0
  17. package/lib/toml-hooks.mjs +2 -4
  18. package/lib/workflow-manager-governance.mjs +3 -47
  19. package/lib/workspace.mjs +2 -3
  20. package/package.json +2 -2
  21. package/skills/ai-delivery-bootstrap/SKILL.md +1 -1
  22. package/skills/ai-delivery-bootstrap/references/bootstrap-contract.md +1 -1
  23. package/skills/ai-delivery-checkpoint-task/SKILL.md +0 -4
  24. package/skills/ai-delivery-checkpoint-task/references/checkpoint-contract.md +2 -2
  25. package/skills/ai-delivery-checkpoint-task/scripts/hook-event.mjs +2 -8
  26. package/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs +26 -46
  27. package/skills/ai-delivery-design-experience/SKILL.md +3 -3
  28. package/skills/ai-delivery-design-experience/references/experience-contract.md +1 -11
  29. package/skills/ai-delivery-design-experience/references/prototype-management-contract.md +1 -1
  30. package/skills/ai-delivery-orchestrate/SKILL.md +5 -7
  31. package/skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/hooks/hook-event.mjs +2 -8
  32. package/skills/ai-delivery-orchestrate/assets/project-template/AGENTS.md +4 -5
  33. package/skills/ai-delivery-orchestrate/references/formal-state-contract.md +11 -20
  34. package/skills/ai-delivery-orchestrate/references/workflow-model.md +1 -3
  35. package/skills/ai-delivery-prepare-release/assets/release-template/release-manifest.yaml +0 -2
  36. package/docs/PROTOTYPE-MIGRATION.zh-CN.md +0 -164
  37. package/docs/VIEWER-MAINTENANCE.zh-CN.md +0 -150
  38. package/docs/VIEWER-USER-GUIDE.zh-CN.md +0 -113
  39. package/lib/project-migration.mjs +0 -1193
  40. package/lib/prototype-migration.mjs +0 -713
  41. package/skills/ai-delivery-design-experience/assets/experience-template/LEGACY-COMPATIBILITY.md +0 -16
  42. package/skills/ai-delivery-design-experience/assets/experience-template/canvas-catalog.csv +0 -1
  43. package/skills/ai-delivery-design-experience/assets/experience-template/canvas-pages.csv +0 -1
  44. package/skills/ai-delivery-design-experience/assets/experience-template/page-catalog.csv +0 -1
  45. package/skills/ai-delivery-design-experience/assets/experience-template/prototype-file-terminals.csv +0 -1
  46. package/skills/ai-delivery-design-experience/assets/experience-template/prototype-files.csv +0 -1
  47. package/skills/ai-delivery-design-experience/assets/experience-template/prototype-manifest.yaml +0 -76
  48. package/skills/ai-delivery-design-experience/assets/experience-template/prototype-set.yaml +0 -24
package/docs/VIEWER-USER-GUIDE.zh-CN.md DELETED
@@ -1,113 +0,0 @@
1
- # 工作流管理器使用指南
2
-
3
- > 本文件保留旧 Viewer 指南的路径，避免已有文档链接失效。`0.4.0` 起，Workflow Manager 是唯一项目内控制面；旧 `.workflow/tools/viewer/` 和独立 Prototype Review Server 已退役。
4
-
5
- ## 1. 启动
6
-
7
- 在已安装 AI Delivery Workflow 的项目根目录运行：
8
-
9
- ```powershell
10
- .\.workflow\tools\manager\start.cmd
11
- ```
12
-
13
- PowerShell 可使用 `start.ps1`，macOS/Linux 可使用：
14
-
15
- ```bash
16
- sh ./.workflow/tools/manager/start.sh
17
- ```
18
-
19
- 发行包入口等价：
20
-
21
- ```bash
22
- ai-delivery manager serve .
23
- ```
24
-
25
- 服务只绑定 `127.0.0.1`，默认自动选择可用端口并打开浏览器。传入 `--port <port>` 固定端口，传入 `--no-open` 禁止自动打开。终端按 `Ctrl+C` 停止。
26
-
27
- ## 2. 页面
28
-
29
- 管理器提供 19 个固定 Page。`P13` 是从原型审批、路由或修订页面进入的上下文详情页，不在固定导航中。
30
-
31
- | 模块 | 页面 |
32
- | --- | --- |
33
- | 工作台 | `P01` 工作台 |
34
- | 交付管理 | `P02` 开发流程、`P19` 产品需求、`P03` 执行任务、`P18` 测试用例、`P04` 交付成果 |
35
- | 人工决策 | `P06` 待办决策 |
36
- | 项目原型 | `P07` 项目原型、`P11` 视觉规范、`P12` 原型审批、`P13` 页面审核、`P14` 页面路由、`P15` 路由关系、`P16` 修改要求、`P17` 修订记录 |
37
- | 运行环境 | `P08` 项目系统、`P09` 模拟服务 |
38
- | 记录与设置 | `P05` 操作与变更记录、`P10` 设置 |
39
-
40
- 没有登记的项目事实统一显示“尚未登记”，管理器不会生成示例任务、系统、中间件、协议或需求。
41
-
42
- ## 3. 原型审核
43
-
44
- 1. 在 `P11` 核对当前项目唯一视觉规范。
45
- 2. 在 `P12` 按页面编号、名称、路由和审核状态筛选当前迭代全部 Page。
46
- 3. 进入 `P13`，切换 Page 的 Review Scene，查看冻结原型内容。
47
- 4. 在独立评论区域输入修改要求；可按 `Ctrl+V` 粘贴 PNG、JPEG 或 WebP 截图。
48
- 5. 保存修改要求，或附加可选评论后执行“退回修改”或“审核通过”。
49
-
50
- 修改要求可在 AI 开始执行前反复编辑或废弃。AI 开始执行后内容锁定。所有决定、附件和修改要求都绑定精确 Prototype Revision、Page/Scene 和 checksum；原型内容由受限 iframe 提供，不能直接修改正式状态。
51
-
52
- ## 4. 项目系统
53
-
54
- `P08` 的架构视图和列表视图是两个独立 Tab：
55
-
56
- - Project System Registry 声明的所有应用、服务和中间件都会显示；尚未实现的节点以虚线状态显示。
57
- - 当前分支拥有且已实现的节点才开放受控生命周期动作；其他分支和未实现节点只读。
58
- - 用户未指定启动方式时默认使用 Docker。登记的 Dockerfile 或 Compose 文件可查看路径、checksum 和文本。
59
- - 初始化脚本可直接新建或修改文本，也可从 Registry 允许的项目内目录导入本地文件。
60
-
61
- 生命周期和脚本写入先生成计划，再校验 expected revision/checksum 后应用，并产生不可变 Receipt 与事件。界面不提供任意命令、任意文件路径或 YAML 编辑能力。
62
-
63
- ## 5. 模拟服务和人工决策
64
-
65
- `P09` 以可读方式展示 External Dependency 与 Product Backend Mock 的协议、操作、触发条件、正常/业务异常/系统异常场景、报文和来源文件。同步定义使用受控 plan/apply 动作，不能替代真实后端或端到端验收。
66
-
67
- `P06` 展示当前需要人工决定的正式 Gate。批准和退回都可添加评论供 AI 读取；不存在自动超时。视觉规范和 Page 审核仍分别在 `P11`、`P12/P13` 完成，P06 只提供汇总入口。
68
-
69
- ## 6. AI 接口
70
-
71
- UI、HTTP 和 CLI 使用同一应用服务。AI 应优先使用结构化接口，而不是浏览器自动化：
72
-
73
- ```bash
74
- ai-delivery manager inspect .
75
- ai-delivery manager list . --resource facts
76
- ai-delivery manager show . --resource prototypes
77
- ai-delivery manager export . --resource systems
78
- ai-delivery manager action <action-name> . --input <project-relative-json>
79
- ```
80
-
81
- 资源仅限 `manager`、`facts`、`prototypes`、`systems`、`mock`、`settings`。动作仅限发行包白名单，并要求精确身份、actor、expected revision/checksum、幂等键及所需的 plan checksum。AI 建议关系不会自动成为正式关系，也不能直接改变任务或节点状态。
82
-
83
- ## 7. 安全边界
84
-
85
- - 只绑定本机回环地址；不支持局域网监听参数。
86
- - 请求体有固定大小上限，未知资源和动作确定性拒绝。
87
- - 文件读取和导入只能落在业务项目及 Registry 声明的受控路径内。
88
- - 正式节点状态始终由正式状态事实派生，不能在管理器中手工改写。
89
- - 原型修改、用户确认、正式前端修改的顺序始终强制执行。
90
- - 页面面向桌面端 `1280x720` 和 `1440x900`；移动端不在支持范围内。
91
-
92
- ## 8. 升级
93
-
94
- 升级前先预览：
95
-
96
- ```bash
97
- npx ai-delivery-workflow@latest upgrade . --dry-run
98
- ```
99
-
100
- `0.4.0` 升级会把旧 Viewer 作为带备份的 `remove` 操作登记到升级 Receipt。回滚仍受正式事件树与受管文件完整性保护，并可恢复该旧目录。新安装和升级后的安装清单只登记 Manager，不再登记 `viewer_root` 或 `viewer_start`。
101
-
102
- ## 9. 故障处理
103
-
104
- | 现象 | 处理 |
105
- | --- | --- |
106
- | 端口被占用 | 省略 `--port` 自动选取，或指定另一个端口。 |
107
- | 浏览器没有自动打开 | 打开终端输出的 loopback URL，或确认未使用 `--no-open`。 |
108
- | 页面显示“尚未登记” | 登记对应正式事实；不要在界面制造演示数据。 |
109
- | 修改后未刷新 | 点击页面“刷新状态”；操作成功反馈会保留到新数据加载完成。 |
110
- | 操作返回 revision/checksum mismatch | 重新刷新，基于最新事实重新生成 plan，禁止强行覆盖。 |
111
- | `doctor` 报告旧 Viewer 漂移 | 先审阅 `upgrade --dry-run`，再由升级 Receipt 受控移除。 |
112
-
113
- 相关文档：[完整项目手册](PROJECT-MANUAL.zh-CN.md)、[维护指南](VIEWER-MAINTENANCE.zh-CN.md)、[CLI 参数参考](CLI-PARAMETER-REFERENCE.zh-CN.md)、[逐文件参考](FILE-REFERENCE.zh-CN.md)。