ai-delivery-workflow 0.4.0 → 0.5.1

package/docs/PROTOTYPE-MIGRATION.zh-CN.md

@@ -1,164 +0,0 @@
-# Prototype 迁移指南
-
-本文说明如何把旧 `prototype-set.yaml` / member manifest 模型迁移为项目唯一逻辑 Prototype。迁移只处理开放迭代；关闭迭代和归档证据保持历史原貌。
-
-## 1. 固定执行顺序
-
-使用准备发布的同一个安装包依次执行：
-
-```powershell
-npx --yes --package .\ai-delivery-workflow-<version>.tgz ai-delivery upgrade . --dry-run
-npx --yes --package .\ai-delivery-workflow-<version>.tgz ai-delivery upgrade .
-npx --yes --package .\ai-delivery-workflow-<version>.tgz ai-delivery doctor .
-npx --yes --package .\ai-delivery-workflow-<version>.tgz ai-delivery migrate . --dry-run
-```
-
-`upgrade` 只安装迁移能力、退休旧 `UX-LF` 契约并报告 `prototype_migration` follow-up；它不会应用 Prototype 迁移。只有审阅 `migrate --dry-run` 且报告 `can_apply: true` 后，才执行：
-
-```powershell
-npx --yes --package .\ai-delivery-workflow-<version>.tgz ai-delivery migrate .
-npx --yes --package .\ai-delivery-workflow-<version>.tgz ai-delivery doctor .
-```
-
-每次 dry-run 都严格零写入。源文件、决定文件或目标文件变化后必须重新 dry-run。
-
-## 2. 读取迁移报告
-
-`upgrade --dry-run` 和 `migrate --dry-run` 都返回 `prototype_migration`：
-
-| 字段 | 含义 |
-| --- | --- |
-| `status` | `not-required`、`ready`、`blocked` 或 `already-current`。 |
-| `iteration_id` | 当前开放迭代；只有该迭代会产生新的唯一 Prototype。 |
-| `source_checksum` | 旧 Prototype set/member 输入的聚合 SHA-256。 |
-| `member_count` | 旧 set 声明的成员总数。 |
-| `valid_member_count` | 通过身份、manifest 和 source 校验的成员数量。 |
-| `invalid_member_count` | 声明但未通过完整性校验的成员数量。 |
-| `legacy_sets` / `members` | 旧 set、member manifest、source、terminal 和 checksum 清单。 |
-| `target` | 固定 `prototype_id: PROTOTYPE` 及 `.workflow/experience/<iteration-id>/` 目标。 |
-| `merge_report` | 按 terminal、Page、route 和 file 稳定身份合并的记录与冲突。 |
-| `unresolved_conflicts` | 尚未由 checksum 绑定人工决定解决的冲突。 |
-| `preserved_history` | 关闭迭代和归档 set 的逐字节保留清单。 |
-| `preserved_sources` | 应用前再次校验且不会原地改写的旧源文件。 |
-| `approval` | 固定不复用旧批准；有旧成员时要求新的 `UX-UI`。 |
-| `file_changes` | 新增描述/记录/Review Shell 和逐字节 source copy 的精确计划。 |
-| `can_apply` | 所有结构、任务和 Prototype 歧义都关闭后才为 `true`。 |
-
-`member_count`、`valid_member_count` 和 `invalid_member_count` 分别报告声明、有效和无效成员。损坏的 manifest、非法身份或 checksum 漂移会保留在声明总数与无效数中，并令 `status: blocked`，不能把它误判为没有旧成员。
-
-### 2.1 零成员
-
-有效旧 set 中没有成员，或当前开放迭代没有旧 set 时：
-
-- `member_count: 0`、`valid_member_count: 0`、`invalid_member_count: 0`；
-- `status: not-required`；
-- `file_changes.additions` 和 `file_changes.copies` 为空；
-- 不创建 Prototype 迁移文件，也不要求迁移专属 `UX-UI`。
-
-### 2.2 单成员
-
-单成员只有在以下条件全部无歧义时自动迁移：
-
-- set 中身份与 member manifest 身份一致；
-- manifest、source 与必须目录都声明 `sha256` 且实际字节匹配；
-- source 和目录引用都是受控相对路径；
-- terminal、Page、route、file 身份没有冲突；
-- 目标路径不存在不同字节。
-
-满足时报告 `status: ready`、`can_apply: true`。任一条件失败均为 `blocked`，不会用猜测或显示名称补齐身份。
-
-### 2.3 多成员
-
-多成员不会重新切片。迁移器按稳定身份汇总：
-
-- `merge_report.terminals`；
-- `merge_report.pages`；
-- `merge_report.routes`；
-- `merge_report.files`；
-- `merge_report.conflicts`。
-
-相同身份且记录 checksum 相同的定义自动合并；相同身份但定义不同的记录生成稳定 `conflict_id`，等待人工选择 canonical member。每个成员的 source 仍逐字节复制到 `prototype/source/<member-id>/`，不会把不同源码树混写成一个目录。
-
-## 3. 冲突决定文件
-
-决定文件同时承载任务分组和 Prototype 冲突，所以有且只有一份文件，并同时保留 `decisions` 与 `prototype_decisions`：
-
-```yaml
-schema_version: 1
-source_checksum: <migrate-dry-run anchors.proposed.source_checksum>
-actor: human:delivery-owner
-decisions: []
-prototype_decisions:
-  - conflict_id: PROTO-CONFLICT-0123456789ABCDEF
-    action: choose-member
-    member_id: PROTO-WEB
-    rationale: 该成员是此稳定身份的已确认权威来源
-```
-
-任务分组有歧义时，从 `task_grouping.decision_template.decisions` 填写 `decisions`；Prototype 有冲突时，从 `prototype_migration.decision_template.prototype_decisions` 填写 `prototype_decisions`。每项 Prototype 决定必须：
-
-- 使用 dry-run 返回的原 `conflict_id`；
-- 使用 `action: choose-member`；
-- 从该冲突的 `member_ids` 中选择一个 `member_id`；
-- 提供非空 `rationale`；
-- 由 `human:<identity>` actor 作出；
-- 绑定当前迁移 `source_checksum`。
-
-复核和应用必须使用同一文件：
-
-```powershell
-ai-delivery migrate . --decisions .\migration-decisions.yaml --dry-run
-ai-delivery migrate . --decisions .\migration-decisions.yaml
-```
-
-未知、重复、缺失或过期的决定一律失败关闭。
-
-## 4. 应用结果与不可变边界
-
-应用只在 `.workflow/experience/<iteration-id>/` 新增：
-
-```text
-prototype.yaml
-prototype-migration.yaml
-prototype/source/<legacy-member-id>/...
-prototype/review-shell/index.html
-```
-
-`prototype.yaml` 的状态是 `migration-pending-ux-ui`，`current_revision_ref` 为 `null`；`prototype-migration.yaml` 记录旧 set/member、合并结果、人工决定、历史保留清单和批准政策。
-
-以下内容保持原字节：
-
-- 旧 `prototype-set.yaml`、member manifest、成员 source 和目录；
-- 关闭迭代与归档 Prototype；
-- 已有 Gate 文件和 Gate 决定；
-- 旧事件、正式状态视图和归档证据。
-
-迁移清单使用 schema 3 记录 Prototype 新增与复制文件的 checksum，供受保护回滚使用。迁移后出现新正式事务或目标字节漂移时，回滚失败关闭，只能前向修复。
-
-## 5. 重新通过 UX-UI
-
-开放迭代不会继承旧 member/set 的批准。升级退休 pending `UX-LF` 后会续接 pending `UX-UI`；迁移完成后必须在同一个逻辑 Prototype 中完成：
-
-1. 按新目录和当前视觉规范整理完整 source、Review Shell 及规范化目录；
-2. 冻结新的不可变 `prototype-revision.yaml`；
-3. 运行 `prototype-revision validate`；
-4. 启动 Workflow Manager，并在 P12/P13 打开该精确 revision；
-5. 由用户逐 Page/Review Scene 审核并完成新的 `UX-UI`；
-6. 之后才允许修改正式前端。
-
-迁移生成的占位 Review Shell 只帮助定位旧成员，不是完整冻结 revision。Workflow Manager 不能对 `current_revision_ref: null` 或未冻结、未完整校验的迁移状态签发批准。
-
-## 6. Workflow Manager
-
-Workflow Manager 可以查看 `.workflow/experience/<iteration-id>/prototype-migration.yaml`、迁移清单及其 checksum，用于审计“从什么迁到什么”，但不会把迁移完成推断为设计批准。P11 只接受精确 Visual Reference，P12/P13 只接受完整、冻结、校验通过的 Prototype Revision；Page 决定、审核凭据和最终 `UX-UI` 只能通过 Manager 白名单动作产生。
-
-## 7. 完成检查
-
-迁移完成后至少确认：
-
-- `migrate` 返回 `applied: true` 且 `prototype_migration.applied: true`；
-- `doctor` 的 required checks 全部通过，包括 `package-surface`；
-- 旧 set/member、关闭/归档证据和旧事件 checksum 未变化；
-- 新 `prototype.yaml` 指向唯一 `PROTOTYPE`，状态为 `migration-pending-ux-ui`；
-- 开放迭代存在待完成的新 `UX-UI`，旧批准未复用；
-- 后续所有正式前端修改仍遵守“先改 Prototype -> 用户确认 -> 再改正式前端”。

package/docs/VIEWER-MAINTENANCE.zh-CN.md

@@ -1,150 +0,0 @@
-# 工作流管理器维护指南
-
-AI 或脚本操作正式管理器前，先读取 [Workflow Manager Agent Interface](agents/workflow-manager-agent-interface.md)，并以运行时 `contracts` 资源为动作 Schema 的唯一事实源。
-
-> 本文件保留旧 Viewer 维护指南的路径。现行产品是 Workflow Manager；旧 Viewer 和独立 Prototype Review Server 的源码、CLI 与安装契约均已退役。
-
-## 1. 仓库身份和权威源码
-
-本仓库是 `ai-delivery-workflow` 的维护与发行源码仓库，不是安装后的业务项目。Manager 的权威位置是：
-
-```text
-lib/workflow-manager.mjs
-lib/workflow-manager-facts.mjs
-lib/workflow-manager-governance.mjs
-lib/workflow-manager-prototypes.mjs
-lib/workflow-manager-systems.mjs
-lib/workflow-manager-mock.mjs
-manager/src/
-lib/workflow-manager-public/
-skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/manager/
-verification/workflow-manager*.test.mjs
-```
-
-React/Vite 源码位于 `manager/src/`；`npm run manager:build` 生成发行静态资源到 `lib/workflow-manager-public/`。安装模板中的 `manager.mjs` 和启动脚本是项目内入口，不是另一个业务实现。
-
-## 2. 架构和边界
-
-```text
-CLI / HTTP / React UI
-        |
-        v
-workflow-manager.mjs application service
-        |
-        +-- formal delivery state and facts
-        +-- prototype review and change requests
-        +-- project systems and initialization scripts
-        +-- Mock definitions and synchronization
-        +-- decisions, relationships and settings
-```
-
-不可变边界：
-
-- UI、HTTP 和 CLI 调用同一资源查询与动作分派，不复制业务规则。
-- 正式节点状态来自 `state inspect.derived_node_states`；Manager 不提供直接状态写入口。
-- 所有写能力属于固定动作白名单；任意 shell、任意文件编辑、直接 YAML 编辑和 Gate 绕过均拒绝。
-- 原型审核绑定精确 Revision、Page/Scene 和 checksum；原型内容只通过受控路径和 sandbox iframe 提供。
-- 系统生命周期只执行 Registry 登记的当前分支 Docker Compose argv；初始化脚本只能位于声明目录。
-- 管理器只支持中文桌面界面，验收视口为 `1280x720` 和 `1440x900`，不承担移动端兼容。
-
-## 3. 服务接口
-
-版本化资源：
-
-```text
-manager, facts, prototypes, systems, mock, settings
-```
-
-HTTP 接口：
-
-```text
-GET  /api/v1/manager
-GET  /api/v1/resources/<resource>
-POST /api/v1/actions/<action>
-GET  /api/v1/prototype-content/<frozen-relative-path>
-```
-
-CLI 等价入口：
-
-```text
-manager inspect
-manager list|show|export --resource <resource>
-manager action <action-name> --input <json-file>
-manager serve [--port <port>] [--no-open]
-```
-
-动作输入必须是有大小限制的 JSON object。写动作按能力要求校验 `human:` 或 `agent:` actor、expected revision/checksum、幂等键和 plan checksum，并输出结构化 Receipt/Event。新增动作时必须同时更新白名单、CLI/HTTP 路由、应用服务测试、安装后 CLI 测试和用户文档。
-
-## 4. 页面契约
-
-`lib/workflow-manager.mjs` 的 `MANAGER_PAGES` 是 19 个固定 Page 的发行目录。Page ID 只追加，不重排、不复用；`P13` 标记为 contextual。业务项目 Prototype 的 Page/Review Scene 身份来自冻结 Revision，不得与 Manager Page 身份混用。
-
-页面数据来自资源投影：
-
-- P01/P02 使用 Manager 投影和正式状态派生事实。
-- P03/P04/P05/P06/P18/P19 使用 `facts` 与 governance 服务。
-- P07/P11-P17 使用 `prototypes` 服务。
-- P08 使用 `systems` 服务。
-- P09 使用 `mock` 服务。
-- P10 使用 `settings` 服务。
-
-缺少事实时返回明确的 `not-registered` 或空集合，界面显示“尚未登记”。禁止用硬编码示例掩盖未登记状态。
-
-## 5. 安装和升级
-
-`lib/project-installer.mjs` 将 Manager runtime、静态资源和跨平台启动脚本作为受管资产安装。新安装清单不包含 Viewer 字段。升级旧安装时：
-
-1. 预览中把旧 Viewer 列为 `remove`。
-2. 应用时先备份旧 Viewer，再删除并把 checksum、备份位置写入 Receipt。
-3. 回滚前验证正式事件树和受管资产未漂移，然后恢复旧 Viewer。
-4. Doctor 校验 Manager，不再把 Viewer 当可选能力。
-
-独立 Prototype Review Server 不进入 npm 包；`prototype-review-target.mjs` 和 `prototype-page-review.mjs` 仍是 Manager、前端守卫及审核凭证的内部模块。
-
-## 6. 修改流程
-
-1. 从正式原型基线 `wm-prototype-r33@f98e7595` 和对应需求确定 Page/Scene 行为。
-2. 为应用服务或 UI 行为先增加失败测试。
-3. 修改 `lib/workflow-manager*.mjs`、`manager/src/` 或安装入口。
-4. 执行 `npm run manager:build`，只保留最终 index 引用的哈希资源。
-5. 运行 Manager 全套测试和受影响的安装、状态、文档测试。
-6. 用真实安装项目从包内 CLI 启动，验证 CLI、HTTP 与 UI 返回一致事实。
-7. 在两个桌面视口检查页面身份、非空内容、框架错误覆盖层、控制台、交互、溢出和重叠。
-8. 执行新安装、升级、迁移、回滚与 npm 打包校验。
-9. 更新文档和 Gitee Issue 证据后才关闭任务。
-
-原型需求发生变化时，先生成并批准新 Prototype Revision，再改正式 React 页面。不能以测试方便为由跳过这条顺序。
-
-## 7. 验证命令
-
-```powershell
-node --test verification/workflow-manager*.test.mjs
-node --test verification/frontend-guard.test.mjs verification/delivery-state.test.mjs verification/documentation.test.mjs verification/project-installer.test.mjs
-npm run manager:build
-npm test
-npm run skills:validate
-npm run pack:check
-git diff --check
-```
-
-发行候选还必须验证：
-
-- 从 npm tarball 全新安装并启动 Manager；
-- 从旧安装升级，Receipt 包含旧 Viewer 的 `remove`；
-- 回滚恢复升级前受管字节；
-- `migrate --dry-run` 零写；
-- 包内不存在 Viewer 或独立 Prototype Review Server；
-- `doctor`、Manager CLI/API/UI 在安装后项目中可用。
-
-## 8. 完成定义
-
-只有以下证据全部成立才算完成：
-
-- 19 个 Page 都有真实实现，不含 planned placeholder；
-- P13 评论、截图、反复修改和审核动作持久化且 AI 可读；
-- P08 架构/列表分离，计划节点、Docker 文件、脚本导入/编辑和分支控制有效；
-- P09 协议与场景可读，受控同步保留 Receipt；
-- CLI、HTTP、UI 和安装后 runtime 使用同一事实与动作契约；
-- 两个桌面视口无横向溢出或关键面板重叠，控制台无未解释错误；
-- 全套测试、构建、Skill、打包、升级/回滚和目标项目 dry-run 通过；
-- 文档、安装清单和任务跟踪与发行包一致。

package/docs/VIEWER-USER-GUIDE.zh-CN.md

@@ -1,113 +0,0 @@
-# 工作流管理器使用指南
-
-> 本文件保留旧 Viewer 指南的路径，避免已有文档链接失效。`0.4.0` 起，Workflow Manager 是唯一项目内控制面；旧 `.workflow/tools/viewer/` 和独立 Prototype Review Server 已退役。
-
-## 1. 启动
-
-在已安装 AI Delivery Workflow 的项目根目录运行：
-
-```powershell
-.\.workflow\tools\manager\start.cmd
-```
-
-PowerShell 可使用 `start.ps1`，macOS/Linux 可使用：
-
-```bash
-sh ./.workflow/tools/manager/start.sh
-```
-
-发行包入口等价：
-
-```bash
-ai-delivery manager serve .
-```
-
-服务只绑定 `127.0.0.1`，默认自动选择可用端口并打开浏览器。传入 `--port <port>` 固定端口，传入 `--no-open` 禁止自动打开。终端按 `Ctrl+C` 停止。
-
-## 2. 页面
-
-管理器提供 19 个固定 Page。`P13` 是从原型审批、路由或修订页面进入的上下文详情页，不在固定导航中。
-
-| 模块 | 页面 |
-| --- | --- |
-| 工作台 | `P01` 工作台 |
-| 交付管理 | `P02` 开发流程、`P19` 产品需求、`P03` 执行任务、`P18` 测试用例、`P04` 交付成果 |
-| 人工决策 | `P06` 待办决策 |
-| 项目原型 | `P07` 项目原型、`P11` 视觉规范、`P12` 原型审批、`P13` 页面审核、`P14` 页面路由、`P15` 路由关系、`P16` 修改要求、`P17` 修订记录 |
-| 运行环境 | `P08` 项目系统、`P09` 模拟服务 |
-| 记录与设置 | `P05` 操作与变更记录、`P10` 设置 |
-
-没有登记的项目事实统一显示“尚未登记”，管理器不会生成示例任务、系统、中间件、协议或需求。
-
-## 3. 原型审核
-
-1. 在 `P11` 核对当前项目唯一视觉规范。
-2. 在 `P12` 按页面编号、名称、路由和审核状态筛选当前迭代全部 Page。
-3. 进入 `P13`，切换 Page 的 Review Scene，查看冻结原型内容。
-4. 在独立评论区域输入修改要求；可按 `Ctrl+V` 粘贴 PNG、JPEG 或 WebP 截图。
-5. 保存修改要求，或附加可选评论后执行“退回修改”或“审核通过”。
-
-修改要求可在 AI 开始执行前反复编辑或废弃。AI 开始执行后内容锁定。所有决定、附件和修改要求都绑定精确 Prototype Revision、Page/Scene 和 checksum；原型内容由受限 iframe 提供，不能直接修改正式状态。
-
-## 4. 项目系统
-
-`P08` 的架构视图和列表视图是两个独立 Tab：
-
-- Project System Registry 声明的所有应用、服务和中间件都会显示；尚未实现的节点以虚线状态显示。
-- 当前分支拥有且已实现的节点才开放受控生命周期动作；其他分支和未实现节点只读。
-- 用户未指定启动方式时默认使用 Docker。登记的 Dockerfile 或 Compose 文件可查看路径、checksum 和文本。
-- 初始化脚本可直接新建或修改文本，也可从 Registry 允许的项目内目录导入本地文件。
-
-生命周期和脚本写入先生成计划，再校验 expected revision/checksum 后应用，并产生不可变 Receipt 与事件。界面不提供任意命令、任意文件路径或 YAML 编辑能力。
-
-## 5. 模拟服务和人工决策
-
-`P09` 以可读方式展示 External Dependency 与 Product Backend Mock 的协议、操作、触发条件、正常/业务异常/系统异常场景、报文和来源文件。同步定义使用受控 plan/apply 动作，不能替代真实后端或端到端验收。
-
-`P06` 展示当前需要人工决定的正式 Gate。批准和退回都可添加评论供 AI 读取；不存在自动超时。视觉规范和 Page 审核仍分别在 `P11`、`P12/P13` 完成，P06 只提供汇总入口。
-
-## 6. AI 接口
-
-UI、HTTP 和 CLI 使用同一应用服务。AI 应优先使用结构化接口，而不是浏览器自动化：
-
-```bash
-ai-delivery manager inspect .
-ai-delivery manager list . --resource facts
-ai-delivery manager show . --resource prototypes
-ai-delivery manager export . --resource systems
-ai-delivery manager action <action-name> . --input <project-relative-json>
-```
-
-资源仅限 `manager`、`facts`、`prototypes`、`systems`、`mock`、`settings`。动作仅限发行包白名单，并要求精确身份、actor、expected revision/checksum、幂等键及所需的 plan checksum。AI 建议关系不会自动成为正式关系，也不能直接改变任务或节点状态。
-
-## 7. 安全边界
-
-- 只绑定本机回环地址；不支持局域网监听参数。
-- 请求体有固定大小上限，未知资源和动作确定性拒绝。
-- 文件读取和导入只能落在业务项目及 Registry 声明的受控路径内。
-- 正式节点状态始终由正式状态事实派生，不能在管理器中手工改写。
-- 原型修改、用户确认、正式前端修改的顺序始终强制执行。
-- 页面面向桌面端 `1280x720` 和 `1440x900`；移动端不在支持范围内。
-
-## 8. 升级
-
-升级前先预览：
-
-```bash
-npx ai-delivery-workflow@latest upgrade . --dry-run
-```
-
-`0.4.0` 升级会把旧 Viewer 作为带备份的 `remove` 操作登记到升级 Receipt。回滚仍受正式事件树与受管文件完整性保护，并可恢复该旧目录。新安装和升级后的安装清单只登记 Manager，不再登记 `viewer_root` 或 `viewer_start`。
-
-## 9. 故障处理
-
-| 现象 | 处理 |
-| --- | --- |
-| 端口被占用 | 省略 `--port` 自动选取，或指定另一个端口。 |
-| 浏览器没有自动打开 | 打开终端输出的 loopback URL，或确认未使用 `--no-open`。 |
-| 页面显示“尚未登记” | 登记对应正式事实；不要在界面制造演示数据。 |
-| 修改后未刷新 | 点击页面“刷新状态”；操作成功反馈会保留到新数据加载完成。 |
-| 操作返回 revision/checksum mismatch | 重新刷新，基于最新事实重新生成 plan，禁止强行覆盖。 |
-| `doctor` 报告旧 Viewer 漂移 | 先审阅 `upgrade --dry-run`，再由升级 Receipt 受控移除。 |
-
-相关文档：[完整项目手册](PROJECT-MANUAL.zh-CN.md)、[维护指南](VIEWER-MAINTENANCE.zh-CN.md)、[CLI 参数参考](CLI-PARAMETER-REFERENCE.zh-CN.md)、[逐文件参考](FILE-REFERENCE.zh-CN.md)。