@fieldwangai/agentflow 0.1.138 → 0.1.142

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 (26) hide show
  1. package/bin/lib/catalog-flows.mjs +17 -3
  2. package/bin/lib/composer-node-schema.mjs +4 -0
  3. package/bin/lib/i18n.mjs +2 -2
  4. package/bin/lib/jenkins.mjs +380 -0
  5. package/bin/lib/locales/en.json +22 -0
  6. package/bin/lib/locales/zh.json +22 -0
  7. package/bin/lib/paths.mjs +1 -0
  8. package/bin/lib/prd-workflow-collaboration.mjs +93 -1
  9. package/bin/lib/recent-runs.mjs +16 -0
  10. package/bin/lib/run-node-statuses-from-disk.mjs +41 -3
  11. package/bin/lib/scheduler.mjs +59 -25
  12. package/bin/lib/ui-server.mjs +996 -73
  13. package/bin/lib/workflow-report.mjs +127 -1
  14. package/bin/pipeline/pre-process-node.mjs +122 -11
  15. package/bin/pipeline/run-log.mjs +2 -2
  16. package/bin/pipeline/write-result.mjs +4 -4
  17. package/builtin/nodes/tool_jenkins_build.md +64 -0
  18. package/builtin/web-ui/dist/assets/{WorkflowAssistantThread-B3thaqH2.js → WorkflowAssistantThread-DGaXikJ9.js} +1 -1
  19. package/builtin/web-ui/dist/assets/index-CtG65J3e.css +1 -0
  20. package/builtin/web-ui/dist/assets/index-pLsH0Uyj.js +835 -0
  21. package/builtin/web-ui/dist/index.html +2 -2
  22. package/package.json +1 -1
  23. package/skills/agentflow-workflow-report/SKILL.md +9 -1
  24. package/skills/agentflow-workflow-report/references/protocol.md +137 -12
  25. package/builtin/web-ui/dist/assets/index-COX1zMwq.css +0 -1
  26. package/builtin/web-ui/dist/assets/index-YS4XOpXF.js +0 -590
package/builtin/web-ui/dist/index.html CHANGED
@@ -15,8 +15,8 @@
15
15
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0"
16
16
  rel="stylesheet"
17
17
  />
18
- <script type="module" crossorigin src="/assets/index-YS4XOpXF.js"></script>
19
- <link rel="stylesheet" crossorigin href="/assets/index-COX1zMwq.css">
18
+ <script type="module" crossorigin src="/assets/index-pLsH0Uyj.js"></script>
19
+ <link rel="stylesheet" crossorigin href="/assets/index-CtG65J3e.css">
20
20
  </head>
21
21
  <body>
22
22
  <div id="root"></div>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fieldwangai/agentflow",
3
- "version": "0.1.138",
3
+ "version": "0.1.142",
4
4
  "description": "Orchestration system for long-running complex agent tasks using Cursor, OpenCode, Claude Code, or Codex as execution backends",
5
5
  "type": "module",
6
6
  "main": "bin/agentflow.mjs",
package/skills/agentflow-workflow-report/SKILL.md CHANGED
@@ -7,6 +7,8 @@ description: Safely synchronize TAPD-derived Workflow access, then read, merge,
7
7
 
8
8
  Treat Workflow reporting as one canonical producer-adapter protocol. The producer reports facts through `POST /api/workflows/report`; AgentFlow alone materializes and returns `snapshot`. Do not introduce producer-specific write endpoints for new integrations.
9
9
 
10
+ Action Checklist is a generic optional Action capability, not a prd-flow extension. Producers own the stable checklist definition through the canonical Report endpoint; AgentFlow owns per-item interactive state through `GET/PATCH /api/workflows/checklist`. Keep those two ownership domains separate so a producer refresh cannot erase user-entered status, notes, or evidence.
11
+
10
12
  ## Prerequisites
11
13
 
12
14
  Use the Workflow Report client bundled with the sibling `agentflow-cli` skill. The CLI is its command-line wrapper for AI, scripts, and local verification:
@@ -51,6 +53,7 @@ Include at least one capability:
51
53
 
52
54
  - `observation`: report the producer's complete current observation when it computes a deterministic workflow view.
53
55
  - `action`: report a stable progress or lifecycle event.
56
+ - `action.checklist`: declare stable executable items when a stage needs human or agent follow-up; cards show progress/titles and the dedicated document page shows details.
54
57
  - `artifacts`: attach evidence; use stable artifact keys.
55
58
  - `globalState`: merge producer-owned durable state or remove explicit paths.
56
59
  - `projections`: replace generic derived indexes used by AgentFlow dashboards.
@@ -72,8 +75,12 @@ For local Markdown or other content that must become a browser URL, publish it f
72
75
  - Keep `schemaVersion` at `1` unless the server advertises another version.
73
76
  - Keep the runtime chain singular: producer adapter → Workflow Report client → AgentFlow. The Skill is guidance, not a transport hop.
74
77
  - Give every action a stable `key`.
78
+ - Give every checklist item a stable Action-local `key`. A producer may update item titles/details, but must not report mutable item execution state inside the Action definition.
75
79
  - Send a stable lowercase `source` on every report and Markdown publish; it is required. Action, idempotency, Artifact, Projection, Extension, Observation, and GlobalState ownership are isolated by source-aware resource keys.
76
80
  - Give every timeline entry stable `kind` and `id` values.
81
+ - Base a timeline `id` and `key` on the scheduled business object itself. Keep platform, team, and
82
+ other filter facets in `dimensions`; if one version/sprint/milestone spans multiple platforms,
83
+ report one entry with a dimension array instead of creating one identity per platform.
77
84
  - Treat `dimensions` as opaque facets; do not hardcode Android, iOS, version, or prd-flow fields into AgentFlow state.
78
85
  - Treat `globalState` as the source of truth owned by the producer; treat projections as replaceable derived views.
79
86
  - Send the complete current source-owned timeline slice whenever changing it. Omitting `projections` means no projection change.
@@ -83,10 +90,11 @@ For local Markdown or other content that must become a browser URL, publish it f
83
90
  ## Permissions and overwrite semantics
84
91
 
85
92
  - Treat TAPD personnel as derived authority when the Adapter can read them: TAPD Owner maps to Workflow Owner and registered TAPD participants map to Viewer.
86
- - Keep explicit grants separate from derived TAPD membership. Allow Owner and explicit Reporter writes. Treat TAPD participant Viewer, explicit Viewer, same-team Viewer, share-link Viewer, and admin review as read-only. Accept legacy `editor` only as a compatibility alias for Reporter.
93
+ - Keep explicit grants separate from derived TAPD membership. Allow Owner and explicit Reporter writes. Treat TAPD participant Viewer, explicit Viewer, same-team Viewer, share-link Viewer, and ordinary admin review as read-only. The only admin write exception is an explicit audited `adminOperation=repair-version-membership` Report containing only `kind=version` timeline projections, with required `expectedRevision` and `idempotencyKey`; it must never admit Action, Artifact, Observation, GlobalState, Extension, Checklist, or non-version projection writes. Accept legacy `editor` only as a compatibility alias for Reporter.
87
94
  - `observation.state` replaces the complete previous observation for the same `clientId`.
88
95
  - `globalState.patch` recursively merges objects; arrays and scalars replace; `null` and `remove` delete explicit paths. The first reporting source to write a path owns it; another source cannot overwrite an owned path.
89
96
  - Reusing an `action.key` updates the same semantic stage. Do not create a new key for refreshes or retries.
97
+ - Checklist state is keyed by `checklist:<source>:<action.key>:<item.key>`. Owner/Reporter may update it through the generic Checklist API; Viewer/team/share/admin review remain read-only. Re-reporting the Action definition preserves this state.
90
98
  - `projections.timeline` replaces only the current source's entries; AgentFlow preserves other sources atomically.
91
99
  - `extensions` can update only `extensions[source]`; objects recursively merge, arrays/scalars replace, and `null` deletes producer-owned fields.
92
100
  - Publishing Markdown creates or updates a preview Artifact and review copy; it does not confirm a document or advance an Action.
package/skills/agentflow-workflow-report/references/protocol.md CHANGED
@@ -11,13 +11,13 @@
11
11
  7. 字段模型
12
12
  8. 覆盖、合并与删除规则
13
13
  9. 并发、幂等与错误码
14
- 10. 三个关键接入场景
14
+ 10. 五个关键接入场景
15
15
  11. prd-flow 参考映射
16
16
  12. 验收清单
17
17
 
18
18
  ## 1. 接入边界
19
19
 
20
- 新接入使用三个运行态数据接口，以及一个独立的权限控制面接口：
20
+ 新接入的生产方使用三个运行态数据接口，以及一个独立的权限控制面接口。带人工执行项的 Action 另外使用一组通用 Checklist 交互接口；它们不是生产方上报入口：
21
21
 
22
22
  | 方法 | 路径 | 用途 | 是否修改 Workflow |
23
23
  | --- | --- | --- | --- |
@@ -25,6 +25,8 @@
25
25
  | `POST` | `/api/workflows/report` | 上报全局信息、Action、普通产物、迭代归属和自定义区域 | 是 |
26
26
  | `POST` | `/api/workflow-artifacts/publish` | 把本地 Markdown 内容发布成浏览器可访问的预览链接 | 是 |
27
27
  | `POST` | `/api/workflows/access/sync` | 同步 TAPD Owner 和参与人的派生权限 | 只修改权限 |
28
+ | `GET` | `/api/workflows/checklist` | 读取某个 Action 的独立清单文档和逐项状态 | 否 |
29
+ | `PATCH` | `/api/workflows/checklist` | 更新一个条目的状态、备注和证据 | 只修改 AgentFlow 交互态 |
28
30
 
29
31
  `agentflow-workflow-report` 是接入规格；`workflow-report-client.mjs` 是可复用客户端；`agentflow-cli` 是命令行包装；AgentFlow 服务才负责鉴权、存储、合并和展示。Skill 不参与运行时传输，CLI 也不是数据生产方。
30
32
 
@@ -55,11 +57,13 @@ CLI 从 `AGENTFLOW_TOKEN` 或 `AGENTFLOW_SESSION_TOKEN` 读取凭证。不得把
55
57
  | 显式 Viewer | 是 | 否 | 否 |
56
58
  | owner 同团队成员 | 是，团队视图自动获得 viewer 权限 | 否 | 否 |
57
59
  | 分享链接访问者 | 是 | 否 | 否 |
58
- | 超级管理员代看 | 是 | 否，只读审阅 | 否 |
60
+ | 超级管理员代看 | 是 | 仅显式版本归属修复 | 否 |
59
61
 
60
62
  完成权限同步后，TAPD 需求 Owner 就是 Workflow Owner。TAPD 参与人匹配到已注册的 AgentFlow 账号后，默认得到派生 Viewer，不会自动获得上报权限。Owner 可在 AgentFlow 中显式授予 Reporter 或 Viewer。
61
63
 
62
- 派生权限和显式授权分开保存：后续 TAPD 刷新可以增加或移除派生 Viewer，但不能抹掉 Owner 主动给出的显式授权。尚未同步 TAPD 人员的历史 Workflow 保留已有 Owner，避免升级时突然撤销权限。兼容客户端若跳过 access sync，首次上报仍会建立 `legacy` Owner；新接入不得依赖这个回退，应先同步 TAPD 权限。旧角色字符串 `editor` 作为兼容别名继续接受，并统一物化为 `reporter`。没有写权限的调用返回 `403`，不会回退成调用者自己的副本。
64
+ 派生权限和显式授权分开保存：后续 TAPD 刷新可以增加或移除派生 Viewer，但不能抹掉 Owner 主动给出的显式授权。尚未同步 TAPD 人员的历史 Workflow 保留已有 Owner，避免升级时突然撤销权限。兼容客户端若跳过 access sync，首次上报仍会建立 `legacy` Owner；新接入不得依赖这个回退，应先同步 TAPD 权限。旧角色字符串 `editor` 作为兼容别名继续接受，并统一物化为 `reporter`。没有写权限的普通调用返回 `403`，不会回退成调用者自己的副本。
65
+
66
+ 超级管理员仍不能代替 Owner/Reporter 写 Action、Artifact、Observation、GlobalState、Extension 或 Checklist。唯一窄写例外是显式的版本归属修复：通过同一个 Report 接口携带 `adminOperation=repair-version-membership`，只修改 `kind=version` 的 timeline 投影，并记录管理员 actor 供审计。
63
67
 
64
68
  ### 2.3 TAPD 权限同步
65
69
 
@@ -121,6 +125,8 @@ Workflow 页面由三类数据区域组成：
121
125
 
122
126
  Action 是业务节点，不是运行日志。轮询、刷新、重试等技术动作不应各自创建 Action。
123
127
 
128
+ Action 可以选择携带通用 `checklist` 定义。时间轴卡片只显示整体进度和条目标题；条目的摘要、章节、执行结果、备注与证据在独立详情文档中展示。Producer 通过 Report 拥有定义，AgentFlow 通过 Checklist API 拥有逐项运行态。不得把状态写回 Action 定义，否则 Producer 刷新会覆盖人工结果。
129
+
124
130
  ### 3.3 自定义区域
125
131
 
126
132
  描述只有某个接入实现才理解的结构化面板，例如 prd-flow 的 AI Docs 和 Issues。
@@ -140,6 +146,7 @@ AI Docs / Issues 不是通用固定字段。当前唯一注册的 extension rend
140
146
  | 需求概览 | `globalState.title/url/status` | 标题、外链和状态标签 | 否 |
141
147
  | 自定义概览分区 | `globalState.sections` | 分区卡片与固定字段样式 | 否 |
142
148
  | Action 时间轴 | `action` | 按日期分组的状态点、时间、标题、详情和维度标签 | 否 |
149
+ | Action Checklist | `action.checklist` + Checklist API | 卡片进度/标题列表与独立详情文档 | 否 |
143
150
  | Action 产物 | `artifacts[scope=action]` | Action 下的链接按钮 | 否 |
144
151
  | 关联产物 | `artifacts[scope=global]` | 侧栏链接列表，展示标题和产物类型 | 否 |
145
152
  | 迭代时间线 | `projections.timeline` | 版本/Sprint/里程碑时间线卡片与筛选 | 否 |
@@ -212,6 +219,7 @@ section key 为 `progress` 时使用紧凑响应式网格；其他 section 默
212
219
 
213
220
  ```text
214
221
  action:<source>:<action.key>
222
+ checklist:<source>:<action.key>:<item.key>
215
223
  artifact:<source>:<artifact.key>
216
224
  projection:<source>:<kind>:<id>
217
225
  global:<dot.path>
@@ -257,6 +265,7 @@ Authorization: Bearer <AGENTFLOW_TOKEN>
257
265
  },
258
266
  "globalState": {},
259
267
  "actions": [],
268
+ "checklistStates": [],
260
269
  "artifacts": [],
261
270
  "projections": { "timeline": [] },
262
271
  "extensions": {}
@@ -298,6 +307,7 @@ Authorization: Bearer <AGENTFLOW_TOKEN>
298
307
  | `expectedVersions` | object | 修改已有资源时建议必填 | 本次触及的全部资源 key 及 GET 返回的版本；创建新 key 使用 `absent` |
299
308
  | `expectedRevision` | string | 兼容字段 | 仅在没有 `expectedVersions` 时启用的整 Workflow 严格锁；新接入不要使用 |
300
309
  | `idempotencyKey` | string | 强烈建议 | 一次业务语义操作的稳定身份，不使用时间戳或随机 UUID |
310
+ | `adminOperation` | string | 管理员特例 | 仅 `repair-version-membership`；详见 5.3 |
301
311
  | `observation` | object | 条件必填 | 同一 `clientId` 的完整生产方观察 |
302
312
  | `action` | object | 条件必填 | 一条关键业务阶段 |
303
313
  | `artifacts` | array | 条件必填 | Action 证据或全局证据 |
@@ -330,6 +340,39 @@ Authorization: Bearer <AGENTFLOW_TOKEN>
330
340
 
331
341
  没有 `observation` 时，响应中的 `observation` 为 `null`。同一 `workflow + source + operation + idempotencyKey` 的幂等重放返回 `alreadyApplied: true`，应按成功处理；Report 与 Artifact Publish 使用独立操作域。
332
342
 
343
+ ### 5.3 超级管理员修复版本归属
344
+
345
+ 用于批量治理错误或重复的版本归属，不是通用代写权限。管理员必须先 GET 当前快照，并以整 Workflow 的当前 `runtimeRevision` 做严格并发锁：
346
+
347
+ ```json
348
+ {
349
+ "schemaVersion": 1,
350
+ "workflow": "tapd:1013667",
351
+ "source": "prd-flow",
352
+ "adminOperation": "repair-version-membership",
353
+ "projections": {
354
+ "timeline": [{
355
+ "kind": "version",
356
+ "id": "1013667",
357
+ "title": "Likee Android&iOS V5.63",
358
+ "date": "2026-08-11",
359
+ "source": "prd-flow"
360
+ }]
361
+ },
362
+ "expectedRevision": "runtime:<revision-from-get>",
363
+ "idempotencyKey": "admin-version-repair:1013667:v563"
364
+ }
365
+ ```
366
+
367
+ 约束：
368
+
369
+ - 调用账号必须是 AgentFlow 超级管理员；目标 Workflow 必须已存在，管理员不会成为 Owner。
370
+ - 请求只能包含 `projections.timeline`，不得携带 `action/artifacts/observation/globalState/extensions`。
371
+ - 所有新投影必须是 `kind=version`；当前 source 的非版本投影和其他 source 的全部投影原子保留。
372
+ - `expectedRevision` 与 `idempotencyKey` 必填。并发变化返回 `409`，失败时不产生部分写入。
373
+ - 运行态事件写入 `administrativeRepair.kind=version-attribution`、管理员 actor 和时间，供审计追踪。
374
+ - 空 `timeline` 表示清空该 source 的版本归属，但仍保留该 source 的 Sprint/Milestone 等非版本条目。
375
+
333
376
  ## 6. POST /api/workflow-artifacts/publish：发布 Markdown 预览
334
377
 
335
378
  把客户端本地 Markdown 内容保存成可访问的运行态副本，并返回预览链接。服务端不能读取客户端文件路径，所以必须发送 `markdown` 内容。
@@ -383,6 +426,37 @@ Authorization: Bearer <AGENTFLOW_TOKEN>
383
426
 
384
427
  发布预览不会确认方案、修改本地文件、提交 ai-doc、创建 GitLab Issue 或推进 Action。Markdown 最大 500,000 bytes；`durability` 只能是 `temporary/durable`。外部系统已经提供 HTTP URL 时，不需要调用本接口，直接在 `/api/workflows/report` 的 `artifacts` 中上报即可。
385
428
 
429
+ ### 6.3 GET / PATCH `/api/workflows/checklist`
430
+
431
+ 这是 AgentFlow 托管的通用交互态，不属于任何单一 Producer。`release-bot`、验收机器人、合规审阅、prd-flow 等客户端都使用同一接口。
432
+
433
+ 读取：
434
+
435
+ ```http
436
+ GET /api/workflows/checklist?workflow=tapd%3A1020124&source=release-bot&actionKey=release-readiness
437
+ ```
438
+
439
+ 更新一个条目：
440
+
441
+ ```json
442
+ {
443
+ "workflow": "tapd:1020124",
444
+ "source": "release-bot",
445
+ "actionKey": "release-readiness",
446
+ "itemKey": "smoke-test",
447
+ "status": "passed",
448
+ "note": "核心链路通过",
449
+ "evidence": [{ "title": "测试报告", "url": "https://example.test/report" }],
450
+ "expectedVersion": "absent",
451
+ "idempotencyKey": "release-readiness:smoke-test:passed:v1"
452
+ }
453
+ ```
454
+
455
+ 状态为 `pending/passed/failed/blocked/skipped`。每次只更新一个 item，使用
456
+ `checklist:<source>:<actionKey>:<itemKey>` 的当前版本做乐观锁；不同 item 可并发，同一 item 的旧版本返回 `409`。Owner 和显式 Reporter 可写，Viewer、团队成员、分享链接与管理员代看只读。
457
+
458
+ 达到 `completionPolicy` 只表示清单“可确认完成”。AgentFlow 不会因此自动修改 TAPD、GitLab、Jenkins 或客户端工作区；Producer 必须读取状态并执行自己的业务确认。
459
+
386
460
  ## 7. 字段模型
387
461
 
388
462
  ### 7.1 observation：完整生产方观察
@@ -435,6 +509,28 @@ Authorization: Bearer <AGENTFLOW_TOKEN>
435
509
  | `tags` | 否 | 字符串数组 |
436
510
  | `occurredAt` | 否 | 业务发生时间；不要用重试时间覆盖它 |
437
511
 
512
+ 可选的 `action.checklist`：
513
+
514
+ ```json
515
+ {
516
+ "schemaVersion": 1,
517
+ "completionPolicy": "all_required",
518
+ "document": { "title": "发布检查详情" },
519
+ "items": [{
520
+ "key": "smoke-test",
521
+ "title": "冒烟测试",
522
+ "required": true,
523
+ "evidenceRequired": true,
524
+ "detail": {
525
+ "summary": "验证发布后的核心链路",
526
+ "sections": [{ "key": "steps", "title": "执行步骤", "content": ["打开应用", "完成核心操作"] }]
527
+ }
528
+ }]
529
+ }
530
+ ```
531
+
532
+ `completionPolicy` 支持 `all_required/any_required/manual`。每个 Action 最多 100 个 item，`item.key` 在 Action 内必须稳定且唯一。详情章节 `content` 可以是文本或字符串数组。Action 卡片不得内联长详情；点击标题进入独立文档。
533
+
438
534
  `completed/success` 会规范化为 `done`，`failed` 会规范化为 `error`；未知状态返回 `400`，不会静默回退。
439
535
 
440
536
  ### 7.3 artifacts：Action 或全局证据
@@ -477,12 +573,12 @@ Authorization: Bearer <AGENTFLOW_TOKEN>
477
573
  {
478
574
  "timeline": [{
479
575
  "kind": "version",
480
- "id": "android:1133202860001000338",
481
- "key": "my-adapter:version:android:1133202860001000338",
482
- "title": "Likee Android 5.63.0",
576
+ "id": "1133202860001000338",
577
+ "key": "my-adapter:version:1133202860001000338",
578
+ "title": "Likee Android&iOS 5.63.0",
483
579
  "date": "2026-08-31",
484
580
  "source": "my-adapter",
485
- "dimensions": { "platform": "android" },
581
+ "dimensions": { "platform": ["android", "ios"] },
486
582
  "order": 0
487
583
  }]
488
584
  }
@@ -499,6 +595,9 @@ Authorization: Bearer <AGENTFLOW_TOKEN>
499
595
  | `dimensions` | 否 | 不透明筛选维度，例如 platform/team |
500
596
  | `order` | 否 | 日期缺失或相同时的稳定顺序 |
501
597
 
598
+ `id` / `key` 标识版本、Sprint 或里程碑本身，不能把平台等筛选维度拼进身份。同一迭代覆盖
599
+ Android 和 iOS 时仍只上报一项，并在 `dimensions.platform` 中使用数组表达多平台。
600
+
502
601
  每个 source 最多上报 100 条合法 timeline 项；超过限制返回错误，不会截断。
503
602
 
504
603
  ### 7.6 extensions：自定义区域
@@ -521,6 +620,8 @@ Authorization: Bearer <AGENTFLOW_TOKEN>
521
620
  | `observation.state` | 保持旧观察 | 同一 `clientId` 的完整 state 替换旧观察 | 上报生产方定义的空值结构；不要用它删除其他 client 的观察 |
522
621
  | `globalState` | 不修改 | 对象递归 merge；数组和标量整体替换；首次写入路径的 source 获得该路径所有权 | patch 中 `null` 删除字段；`remove` 在 patch 后删除 dot path；其他 source 不能改写已归属路径 |
523
622
  | `action` | 不修改 Action | 同 `source + action.key` 更新同一业务阶段的可见状态 | 当前协议不提供物理删除 Action；用业务状态表达取消/跳过 |
623
+ | `action.checklist` 定义 | 不修改定义 | 随同 Action 更新标题、详情和完成策略 | 不携带人工状态；移除 item 前应由 Producer 处理历史状态语义 |
624
+ | Checklist 运行态 | 不修改状态 | 同 `source + action.key + item.key` 独立更新 | 可写回 pending 重置；Action 重报不会覆盖 |
524
625
  | `artifacts` | 不修改产物 | 同 `source + stable key` 更新/归并同一可见证据 | 当前协议不提供通用物理删除；不要通过改 key 伪造删除 |
525
626
  | `projections.timeline` | 不修改 | 替换当前 `source` 拥有的完整切片，服务端原子保留其他 source | `[]` 只清空当前 source 的迭代归属 |
526
627
  | `extensions` | 不修改扩展 | 只允许 `extensions[source]` 内对象递归 merge；数组/标量替换 | 对应字段上报 `null` 删除 |
@@ -552,7 +653,7 @@ Authorization: Bearer <AGENTFLOW_TOKEN>
552
653
 
553
654
  ```text
554
655
  implementation-finished:android:runtime-hook:v1
555
- timeline-membership:tapd-1020124:android-version-1133202860001000338:v1
656
+ timeline-membership:tapd-1020124:version-1133202860001000338:v1
556
657
  ```
557
658
 
558
659
  同一 `workflow + source + operation + idempotencyKey` 的重放返回 `alreadyApplied: true`，包括 `running/error/pending` Action。`report` 与 `artifact.publish` 可以安全复用同一业务 key。Publish 会返回第一次创建的预览，不会先生成一个新文件再去重。业务内容发生变化时提高语义版本或使用内容摘要；不要使用请求时间。
@@ -563,12 +664,12 @@ timeline-membership:tapd-1020124:android-version-1133202860001000338:v1
563
664
  | --- | --- | --- |
564
665
  | `400` | JSON、namespace、字段或 schema 不合法 | 按协议修正；不要降级校验 |
565
666
  | `401` | 缺少或无效认证 | 停止并配置 Token；不要把 Token 打印出来 |
566
- | `403` | 当前用户只有 viewer 权限或无权访问目标项目 | 停止；由 Owner 授予 Reporter 或改用正确身份 |
667
+ | `403` | 当前用户只有 viewer 权限或无权访问目标项目 | 普通写入由 Owner 授予 Reporter；仅版本治理可使用管理员修复模式 |
567
668
  | `404` | 分享链接、owner 或目标资源不存在 | 重新解析目标，不要创建影子副本 |
568
669
  | `409` | 同一资源 key 已变化，或路径属于其他 source | 读取 `conflict.conflicts`，只刷新冲突资源并重试一次；所有 key 通过前请求不会部分落库 |
569
670
  | `500` | 服务端异常 | 保留幂等键，记录脱敏上下文后重试或上报 |
570
671
 
571
- ## 10. 三个关键接入场景
672
+ ## 10. 五个关键接入场景
572
673
 
573
674
  ### 10.1 更新迭代：绑定或切换版本
574
675
 
@@ -596,6 +697,22 @@ timeline-membership:tapd-1020124:android-version-1133202860001000338:v1
596
697
  4. 在 AgentFlow 前端代码中注册对应页面渲染器并重新发布；当前不是运行时插件注册。否则数据只会被保存，不会自动出现专用 UI。当前只有 `extensions["prd-flow"]` 已注册。
597
698
  5. 更新数组时发送该数组的完整新值；更新对象字段时可以递归 merge；用 `null` 删除自有字段。
598
699
 
700
+ ### 10.4 上报并执行 Action Checklist
701
+
702
+ 1. Producer 选择稳定 `action.key` 和 Action 内稳定唯一的 `items[].key`，通过 `/api/workflows/report` 上报定义。
703
+ 2. 页面卡片显示进度和标题；完整详情由独立 Checklist 文档渲染。
704
+ 3. Owner/Reporter 通过通用 Checklist API 逐项保存状态、备注和证据；每项使用自己的 `expectedVersion`。
705
+ 4. Producer 需要推进业务时读取物化状态，校验 required/evidence 规则，再执行自己的确认命令并重新上报 Action 业务状态。
706
+ 5. Producer 刷新标题、步骤或其它事实时继续复用同一 Action/item key；不得把 AgentFlow 交互态塞回定义。
707
+
708
+ ### 10.5 管理员修复版本归属
709
+
710
+ 1. 仅在批量治理版本归属时使用；普通业务状态仍由 Owner/Reporter 上报。
711
+ 2. 管理员 GET 当前 Workflow，人工或程序核对目标版本并保存 `runtimeRevision`。
712
+ 3. 发送只含 `kind=version` timeline 的 `repair-version-membership` 请求。
713
+ 4. 验证响应包含 `administrativeRepair`，事件 actor 是操作管理员，且非版本/其他 source 投影未变化。
714
+ 5. `409` 时重新读取、重新核对并只重试一次；不得绕过严格锁。
715
+
599
716
  ## 11. prd-flow 参考映射
600
717
 
601
718
  prd-flow 只是一个接入实现，不是协议依赖：
@@ -608,6 +725,8 @@ prd-flow 只是一个接入实现，不是协议依赖：
608
725
  | TAPD 当前版本原始信息 | `globalState.tapdCurrentVersion` | 保留版本业务事实 |
609
726
  | 由版本事实派生的归属 | `projections.timeline[kind=version]` | 个人/团队迭代时间线 |
610
727
  | 方案确认、实现、提测、发布 | `action` | Action 时间轴和进度 |
728
+ | 自测 Case 定义 | `action.checklist` | 卡片进度/标题和独立详情文档 |
729
+ | 自测 Case 执行状态与证据 | Checklist API | AgentFlow 托管逐项状态；prd-flow 完成命令读取并校验 |
611
730
  | MR、Jenkins、测试报告 URL | `artifacts` | Action 下产物入口 |
612
731
  | 本地方案 Markdown | Artifact Publish | 可分享方案预览 URL |
613
732
  | AI Docs / Issues | `extensions["prd-flow"]` | prd-flow 专用文档区和 Issue 区 |
@@ -617,13 +736,19 @@ prd-flow 只是一个接入实现，不是协议依赖：
617
736
  ## 12. 验收清单
618
737
 
619
738
  - 能使用 Token GET 当前 Workflow，并读到 `snapshot.resourceVersions`。
620
- - TAPD Owner 同步后成为 Workflow Owner；TAPD 参与人自动成为 Viewer；显式 Reporter 能写，Viewer、团队成员、分享链接和管理员代看不能写。
739
+ - TAPD Owner 同步后成为 Workflow Owner；TAPD 参与人自动成为 Viewer；显式 Reporter 能写，Viewer、团队成员和分享链接不能写。管理员普通代看只读，只有显式版本归属修复可写。
621
740
  - TAPD 派生参与人刷新不会覆盖显式授权；过期的权限快照返回 `409`。
622
741
  - `globalState` 更新不会覆盖其他生产方拥有的路径，数组替换行为符合预期。
623
742
  - 同一 Action key 重报不产生重复业务阶段。
743
+ - 任意 Producer 都能上报 Action Checklist；卡片只显示进度和标题，详情进入独立文档。
744
+ - Producer 重报 Checklist 定义不会覆盖逐项状态、备注和证据。
745
+ - 不同 Checklist item 可并发更新，同 item 旧版本返回具体资源 key 的 `409`。
746
+ - Viewer、团队成员、分享链接和管理员代看不能更新 Checklist。
747
+ - Checklist 达标只显示“可确认完成”，不会静默推进外部业务系统。
624
748
  - Action 下能看到稳定 key 的 MR、构建或测试产物。
625
749
  - Markdown Publish 返回可访问 URL，但不会推进业务状态。
626
750
  - 版本改名/改期不产生新迭代节点，版本切换不会删除第三方 Sprint。
751
+ - 管理员版本归属修复只能改 `kind=version` 投影，要求 runtimeRevision/幂等键并留下管理员 actor 审计；普通 Report 仍返回 403。
627
752
  - 自定义 extension 能保存；注册渲染器后能显示对应文档区 / Issue 区。
628
753
  - 不同资源 key 可并发更新；同 key 旧版本返回包含具体 `resourceKey` 的 409。
629
754
  - 409 会触发一次 key 级 read → re-merge → retry，且失败请求不会部分落库。