@openprd/cli 0.1.18 → 0.1.21

package/.openprd/changes/openprd-control-plane-v020/tasks.md

@@ -0,0 +1,427 @@
+# 任务
+
+- [x] T001.01 评审生成的 spec 覆盖
+  - type: governance
+  - done: 生成的 agent-requirements spec 符合 PRD 意图
+  - verify: openprd change . --validate --change openprd-control-plane-v020
+  - test-layer: manual
+  - test-size: manual
+  - test-scope: governance
+  - evidence-plan: openprd change . --validate --change openprd-control-plane-v020
+  - upgrade-reason: 治理任务以结构校验、评审确认和变更状态证据为主
+  - execution-mode: serial
+  - parallel-group: governance
+  - write-scope: .openprd/changes/**, .openprd/**
+  - owner-role: main-agent
+  - local-verify: openprd change . --validate --change openprd-control-plane-v020
+  - integration-owner: main-agent
+
+- [x] T001.02 对齐共享契约与 Host API 调用边界
+  - type: implementation
+  - deps: T001.01
+  - done: 共享契约、Host API 和上下游调用边界已经对齐，后续功能可以直接接线。 涉及: 现有 OpenPrd CLI、skills、hooks、workspace schema、review renderer、quality/sta 等 2 项。
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.02 --evidence-required
+  - test-layer: integration, e2e
+  - test-size: large
+  - test-scope: visual-flow
+  - evidence-plan: 主流程自动化、截图或 visual-compare 证据 + 本任务 verify 命令；轻量 UI 可视优化也需要 before/after、verification-board 或 alignment-board 证据，同构卡片/列表要覆盖内部内容槽位
+  - upgrade-reason: 触达用户可见路径，需要端到端或视觉级证据；轻量 UI 可视优化不能只用构建或 dev-check 收口
+  - execution-mode: parallel-workers
+  - parallel-group: contracts
+  - write-scope: src/**, test/**, docs/basic/backend-structure.md
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.02 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.03 接通界面入口、导航与页面挂载
+  - type: implementation
+  - deps: T001.02
+  - done: 用户可以从正确入口进入对应界面，页面挂载与状态收尾已经接通。 涉及: Review Studio 改动必须复用现有视觉系统并提供前后、焦点、验证与对齐证据 等 2 项。
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.03 --evidence-required
+  - test-layer: integration, e2e
+  - test-size: large
+  - test-scope: visual-flow
+  - evidence-plan: 主流程自动化、截图或 visual-compare 证据 + 本任务 verify 命令；轻量 UI 可视优化也需要 before/after、verification-board 或 alignment-board 证据，同构卡片/列表要覆盖内部内容槽位
+  - upgrade-reason: 触达用户可见路径，需要端到端或视觉级证据；轻量 UI 可视优化不能只用构建或 dev-check 收口
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.03 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.04 提供 project manifest、ledger append/read/head/verify/rebuild、projection replay API
+  - type: implementation
+  - deps: T001.03
+  - done: 已完成：提供 project manifest、ledger append/read/head/verify/rebuild、projection replay API
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.04 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: api-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.04 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.05 提供 task claim/heartbeat/release、lease recovery、write-set conflict、lane binding API 与 CLI
+  - type: implementation
+  - deps: T001.04
+  - done: 已完成：提供 task claim/heartbeat/release、lease recovery、write-set conflict、lane binding API 与 CLI
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.05 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: api-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: contracts
+  - write-scope: src/**, test/**, docs/basic/backend-structure.md
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.05 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.06 提供 context compile/diff/cache/render/reference API，保持 run --context 兼容入口
+  - type: implementation
+  - deps: T001.05
+  - done: 已完成：提供 context compile/diff/cache/render/reference API，保持 run --context 兼容入口
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.06 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: api-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: contracts
+  - write-scope: src/**, test/**, docs/basic/backend-structure.md
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.06 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.07 提供 scoped gate/evidence evaluation 与明确 approval ID 绑定
+  - type: implementation
+  - deps: T001.06
+  - done: 已完成：提供 scoped gate/evidence evaluation 与明确 approval ID 绑定
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.07 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: cli-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: implementation
+  - write-scope: src/**, test/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.07 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.08 提供 ReviewModel 业务/工程投影与稳定确认合同
+  - type: implementation
+  - deps: T001.07
+  - done: 已完成：提供 ReviewModel 业务/工程投影与稳定确认合同
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.08 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: cli-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: surface
+  - write-scope: src/cli/**, src/**, test/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.08 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.09 提供 adapter detect/capabilities/install/normalize/render/handoff SPI
+  - type: implementation
+  - deps: T001.08
+  - done: 已完成：提供 adapter detect/capabilities/install/normalize/render/handoff SPI
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.09 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: cli-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: contracts
+  - write-scope: src/**, test/**, docs/basic/backend-structure.md
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.09 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.10 提供 Knowledge v3 validate/promote/deprecate/supersede/query 生命周期
+  - type: implementation
+  - deps: T001.09
+  - done: 已完成：提供 Knowledge v3 validate/promote/deprecate/supersede/query 生命周期
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.10 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: cli-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: implementation
+  - write-scope: src/**, test/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.10 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.11 提供 upgrade plan/dry-run/backup/atomic apply/restore 与 fleet 安全批处理
+  - type: implementation
+  - deps: T001.10
+  - done: 已完成：提供 upgrade plan/dry-run/backup/atomic apply/restore 与 fleet 安全批处理
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.11 --evidence-required
+  - test-layer: integration, security
+  - test-size: medium
+  - test-scope: security
+  - evidence-plan: 正向路径 + 越权、额度、并发或敏感信息负向验证
+  - upgrade-reason: 触达权限、安全、成本或滥用边界，需要至少集成级证据
+  - execution-mode: parallel-workers
+  - parallel-group: implementation
+  - write-scope: src/**, test/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.11 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.12 提供 registry prune/compact 与测试环境 OPENPRD_HOME 隔离
+  - type: implementation
+  - deps: T001.11
+  - done: 已完成：提供 registry prune/compact 与测试环境 OPENPRD_HOME 隔离
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.12 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: cli-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.12 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.13 打通主流程闭环：Agent 进入已有项目，Adapter 识别运行环境，Context Compiler 基于 lane/tas 等 6 项
+  - type: implementation
+  - deps: T001.12
+  - done: 主流程关键节点已经打通，用户可以按预期从入口走到结果收尾。 涉及: Agent 进入已有项目，Adapter 识别运行环境，Context Compiler 基于 lane/task/revision 在预算内生 等 6 项。
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.13 --evidence-required
+  - test-layer: integration, e2e
+  - test-size: large
+  - test-scope: user-flow
+  - evidence-plan: 主流程自动化、截图或 visual-compare 证据 + 本任务 verify 命令；轻量 UI 可视优化也需要 before/after、verification-board 或 alignment-board 证据，同构卡片/列表要覆盖内部内容槽位
+  - upgrade-reason: 触达用户可见路径，需要端到端或视觉级证据；轻量 UI 可视优化不能只用构建或 dev-check 收口
+  - execution-mode: serial
+  - parallel-group: integration
+  - write-scope: src/**, test/**, docs/basic/**
+  - owner-role: main-agent
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.13 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.14 验证全量单元、集成、并发、迁移、回滚、性能和三平台契约测试通过
+  - type: verification
+  - deps: T001.13
+  - done: 已验证：全量单元、集成、并发、迁移、回滚、性能和三平台契约测试通过
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.14 --evidence-required
+  - test-layer: integration, performance
+  - test-size: large
+  - test-scope: performance
+  - evidence-plan: 性能基线、压力数据或 benchmark 报告 + 本任务 verify 命令
+  - upgrade-reason: 触达性能或容量边界，需要专项验证证据
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.14 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.15 验证最新 Markdown/HTML 测试报告、质量报告、架构与视觉证据可追溯
+  - type: verification
+  - deps: T001.14
+  - done: 已验证：最新 Markdown/HTML 测试报告、质量报告、架构与视觉证据可追溯
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.15 --evidence-required
+  - test-layer: integration, e2e
+  - test-size: large
+  - test-scope: visual-flow
+  - evidence-plan: 主流程自动化、截图或 visual-compare 证据 + 本任务 verify 命令；轻量 UI 可视优化也需要 before/after、verification-board 或 alignment-board 证据，同构卡片/列表要覆盖内部内容槽位
+  - upgrade-reason: 触达用户可见路径，需要端到端或视觉级证据；轻量 UI 可视优化不能只用构建或 dev-check 收口
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.15 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.16 验证standards、quality、run verify 与 doctor 在发布/刷新前全部健康
+  - type: verification
+  - deps: T001.15
+  - done: 已验证：standards、quality、run verify 与 doctor 在发布/刷新前全部健康
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.16 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: cli-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.16 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.17 验证所有真实项目刷新报告包含版本、checksum、备份、迁移结果和失败回滚状态
+  - type: verification
+  - deps: T001.16
+  - done: 已验证：所有真实项目刷新报告包含版本、checksum、备份、迁移结果和失败回滚状态
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.17 --evidence-required
+  - test-layer: integration, e2e
+  - test-size: large
+  - test-scope: visual-flow
+  - evidence-plan: 主流程自动化、截图或 visual-compare 证据 + 本任务 verify 命令；轻量 UI 可视优化也需要 before/after、verification-board 或 alignment-board 证据，同构卡片/列表要覆盖内部内容槽位
+  - upgrade-reason: 触达用户可见路径，需要端到端或视觉级证据；轻量 UI 可视优化不能只用构建或 dev-check 收口
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.17 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.18 回归非功能约束：Node.js 20.19+，优先零新增运行时依赖，复用现有 YAML 与 Sharp 等 2 项
+  - type: verification
+  - deps: T001.17
+  - done: 非功能约束已经回归确认。 涉及: Node.js 20.19+，优先零新增运行时依赖，复用现有 YAML 与 Sharp 等 2 项。
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.18 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: cli-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.18 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.19 回归非功能约束：读取路径默认无业务状态写入；telemetry 与事实真相分离 等 2 项
+  - type: verification
+  - deps: T001.18
+  - done: 非功能约束已经回归确认。 涉及: 读取路径默认无业务状态写入；telemetry 与事实真相分离 / 面向普通用户的默认文案使用简体中文、结果导向且不暴露内部实现术语。
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.19 --evidence-required
+  - test-layer: integration, e2e
+  - test-size: large
+  - test-scope: visual-flow
+  - evidence-plan: 主流程自动化、截图或 visual-compare 证据 + 本任务 verify 命令；轻量 UI 可视优化也需要 before/after、verification-board 或 alignment-board 证据，同构卡片/列表要覆盖内部内容槽位
+  - upgrade-reason: 触达用户可见路径，需要端到端或视觉级证据；轻量 UI 可视优化不能只用构建或 dev-check 收口
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.19 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.20 回归非功能约束：新旧 CLI 在一个兼容周期内保持字段与退出码兼容，并标注 deprecated 字段 等 2 项
+  - type: verification
+  - deps: T001.19
+  - done: 非功能约束已经回归确认。 涉及: 新旧 CLI 在一个兼容周期内保持字段与退出码兼容，并标注 deprecated 字段 / 每个迁移步骤可重复执行、可审计、可单项目回滚。
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.20 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: cli-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.20 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.21 回归边界条件与失败处理：边界情况：同一 session ID 在多个工作区有线索时不语义猜测，返回候选和安全阻断 等 12 项
+  - type: verification
+  - deps: T001.20
+  - done: 边界条件与失败处理已经回归确认。 涉及: 边界情况：同一 session ID 在多个工作区有线索时不语义猜测，返回候选和安全阻断 等 12 项。
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.21 --evidence-required
+  - test-layer: integration, security
+  - test-size: medium
+  - test-scope: security
+  - evidence-plan: 正向路径 + 越权、额度、并发或敏感信息负向验证
+  - upgrade-reason: 触达权限、安全、成本或滥用边界，需要至少集成级证据
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.21 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.22 验证成本与额度护栏
+  - type: verification
+  - deps: T001.21
+  - done: 已验证免费、试用或低权限用户不能绕过额度、并发、频率或总量限制
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.22 --evidence-required
+  - test-layer: integration, security
+  - test-size: medium
+  - test-scope: security
+  - evidence-plan: 正向路径 + 越权、额度、并发或敏感信息负向验证
+  - upgrade-reason: 触达权限、安全、成本或滥用边界，需要至少集成级证据
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.22 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.23 验证滥用与越权路径
+  - type: verification
+  - deps: T001.22
+  - done: 已覆盖重复请求、并发请求、越权身份和异常恢复等负向场景
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.23 --evidence-required
+  - test-layer: integration, security
+  - test-size: medium
+  - test-scope: security
+  - evidence-plan: 正向路径 + 越权、额度、并发或敏感信息负向验证
+  - upgrade-reason: 触达权限、安全、成本或滥用边界，需要至少集成级证据
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.23 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.24 验证成本监控、报警和止损
+  - type: verification
+  - deps: T001.23
+  - done: 已确认用量或成本信号、报警阈值和人工/自动止损动作可执行
+  - verify: openprd tasks . --change openprd-control-plane-v020 --item T001.24 --evidence-required
+  - test-layer: integration, security
+  - test-size: medium
+  - test-scope: security
+  - evidence-plan: 正向路径 + 越权、额度、并发或敏感信息负向验证
+  - upgrade-reason: 触达权限、安全、成本或滥用边界，需要至少集成级证据
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change openprd-control-plane-v020 --item T001.24 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.25 维护 docs/basic 项目基础文档
+  - type: documentation
+  - deps: T001.24
+  - done: 已检查 docs/basic 是否缺失或因本次需求、流程、结构、依赖、产品行为变化而过期；若涉及后端、脚本、Agent 或工具链变更，已同步评估 CLI 与 API 接入面，并在 backend-structure.md 中记录事实或不适用原因；需要更新的基础文档已同步
+  - verify: openprd standards . --verify
+  - test-layer: manual
+  - test-size: manual
+  - test-scope: docs
+  - evidence-plan: openprd standards . --verify
+  - upgrade-reason: 文档任务以标准校验和人工审查证据为主
+  - execution-mode: parallel-workers
+  - parallel-group: docs
+  - write-scope: docs/basic/**, README*.md
+  - owner-role: worker
+  - local-verify: openprd standards . --verify
+  - integration-owner: main-agent
+
+- [x] Continue with `tasks-002.md` after completing this file.

package/.openprd/changes/openprd-generated-change/.openprd.yaml

@@ -0,0 +1,2 @@
+schema: openprd.change.v1
+generatedFrom: v0014

package/.openprd/changes/openprd-generated-change/design.md

@@ -0,0 +1,50 @@
+# 设计
+
+## 背景
+
+对标 Cowart 已验证“标注改图闭环 + 画布双向结构化工具 + 生图尺寸契约 + 具名 skill 唤起”四件能力能显著降低人机视觉协同成本；OpenPrd 0.1.18 刚落地生图路由，正好把尺寸契约与路由串起来。
+
+## 目标
+
+- 用户在画布上标注后，一句话就能让 Agent 读懂标注并生成修订图放回原图旁
+- Agent 能结构化读取画布选区并把图片锚定回填
+- 生图请求自动携带占位卡尺寸契约
+- 用户能用自然语言稳定唤起画布协同
+
+## 范围
+
+- canvas-workspace.js 新增选区状态持久化与查询 API
+- canvas-workspace.js 新增锚定插图 API（anchorShapeId/placement/replaceHolder）
+- canvas-app.html.js 标注修改请求导出（带元数据）与选区上报
+- 生图占位卡尺寸契约写入 handoff 与生图指引
+- codex-hook-runner-template.mjs 画布协同意图识别与引导注入
+- agent-canonical-content.js 画布协同指引
+- docs/basic 与 README 同步
+
+## 约束
+
+- 沿用 Excalidraw embed 与现有 canvas-sessions 文件存储
+- Node 内置测试框架
+- 不新增外部依赖
+- 不写入敏感信息
+- 画布数据留在本地项目目录
+- 依赖 openprd canvas 本地服务
+- 依赖 0.1.18 生图路由协议
+
+## 业务护栏
+
+- 成本来源: 主要成本是生图调用次数与画布服务本地资源
+- 额度限制: 首版按单画布会话协同，不开放批量自动改图
+- 滥用防护: insert-image 校验锚点与文件存在性，避免脏写
+- 滥用防护: API 仅本地回环访问
+- 监控信号: ops.json handoff 记录数、回填成功率、API 错误率
+- 报警阈值: 回填连续失败时提示用户检查画布服务状态
+- 止损动作: 异常时停止自动回填，保留原画布快照并回退到手动流程
+
+## 风险与开放问题
+
+- 假设: 用户接受标注截图作为修改指令载体
+- 假设: Excalidraw selection 数据足以表达锚定需求
+- 风险: Excalidraw 与 tldraw 数据模型差异导致锚定语义需要适配
+- 风险: 标注文字识别依赖 Agent 视觉能力
+- 问题: 后续是否把画布协同扩展为独立 MCP server 另行评估

package/.openprd/changes/openprd-generated-change/proposal.md

@@ -0,0 +1,37 @@
+# 画布协同闭环：标注改图、双向结构化工具、尺寸契约与唤起机制
+
+## 背景与原因
+
+OpenPrd 画布目前只有单向的“发送给 Codex”整体交接：Agent 不能结构化读取用户在画布上的选区与标注，不能把生成图片精准放回画布锚点旁，标注修改意图靠用户口述或手动截图传递，协同链路断在“人标注完之后”这一步。
+
+## 变更内容
+
+- canvas-workspace.js 新增选区状态持久化与查询 API
+- canvas-workspace.js 新增锚定插图 API（anchorShapeId/placement/replaceHolder）
+- canvas-app.html.js 标注修改请求导出（带元数据）与选区上报
+- 生图占位卡尺寸契约写入 handoff 与生图指引
+- codex-hook-runner-template.mjs 画布协同意图识别与引导注入
+- agent-canonical-content.js 画布协同指引
+- docs/basic 与 README 同步
+- 选区状态随画布保存并可查询
+- 插图 API 支持 left/right/below 摆放与 holder 替换
+- 标注导出携带 annotationEdit 与源图形 ID 元数据
+- 生图占位卡 handoff 记录携带宽高与比例契约
+- hook 识别画布协同意图并注入闭环指引
+- canvas 服务新增 GET /api/selection 与 POST /api/insert-image 且测试通过
+- 标注导出带 annotationEdit 元数据并能被 hook 指引消费
+- hook 对画布协同意图注入引导语
+
+## 能力范围
+
+- `agent-requirements`: 画布协同闭环：标注改图、双向结构化工具、尺寸契约与唤起机制 需求。
+
+## 影响范围
+
+- 主要用户: 使用 OpenPrd 画布做视觉协同的开发者与产品设计协作者
+- 成本来源: 主要成本是生图调用次数与画布服务本地资源
+- 额度限制: 首版按单画布会话协同，不开放批量自动改图
+- 依赖: 依赖 openprd canvas 本地服务
+- 依赖: 依赖 0.1.18 生图路由协议
+- 风险: Excalidraw 与 tldraw 数据模型差异导致锚定语义需要适配
+- 风险: 标注文字识别依赖 Agent 视觉能力

package/.openprd/changes/openprd-generated-change/specs/agent-requirements/spec.md

@@ -0,0 +1,16 @@
+## 新增需求
+
+### 需求：画布协同闭环：标注改图、双向结构化工具、尺寸契约与唤起机制
+OpenPrd 画布目前只有单向的“发送给 Codex”整体交接：Agent 不能结构化读取用户在画布上的选区与标注，不能把生成图片精准放回画布锚点旁，标注修改意图靠用户口述或手动截图传递，协同链路断在“人标注完之后”这一步。
+
+#### 场景：主流程成功
+- **当** 用户在画布圈选原图并批注，点“标注修改请求”，Agent 读标注生成修订图并放回原图右侧
+- **则** canvas 服务新增 GET /api/selection 与 POST /api/insert-image 且测试通过
+
+#### 场景：边界情况保持可见
+- **当** 无选区时 selection API 返回空且 Agent 收到明确提示
+- **则** 产品应保持该情况明确可见，以支持实现和验证
+
+#### 场景：失败模式得到处理
+- **当** 画布服务未启动时 API 调用失败要提示先运行 openprd canvas
+- **则** 产品应提供有边界且可评审的结果

package/.openprd/changes/openprd-generated-change/task-events.jsonl

@@ -0,0 +1,21 @@
+{"version":1,"at":"2026-07-07 00:09:23","changeId":"openprd-generated-change","action":"advance","taskId":"T001.01","taskTitle":"评审生成的 spec 覆盖","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"spec 覆盖已评审，change --validate 通过"}
+{"version":1,"at":"2026-07-07 00:09:33","changeId":"openprd-generated-change","action":"advance","taskId":"T001.02","taskTitle":"对齐共享契约与 Host API 调用边界","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"画布协同实现与回归完成，详见任务级测试报告"}
+{"version":1,"at":"2026-07-07 00:09:33","changeId":"openprd-generated-change","action":"advance","taskId":"T001.03","taskTitle":"接通界面入口、导航与页面挂载","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"画布协同实现与回归完成，详见任务级测试报告"}
+{"version":1,"at":"2026-07-07 00:09:33","changeId":"openprd-generated-change","action":"advance","taskId":"T001.04","taskTitle":"实现选区状态随画布保存并可查询","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"画布协同实现与回归完成，详见任务级测试报告"}
+{"version":1,"at":"2026-07-07 00:09:33","changeId":"openprd-generated-change","action":"advance","taskId":"T001.05","taskTitle":"实现插图 API 支持 left/right/below 摆放与 holder 替换","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"画布协同实现与回归完成，详见任务级测试报告"}
+{"version":1,"at":"2026-07-07 00:09:34","changeId":"openprd-generated-change","action":"advance","taskId":"T001.06","taskTitle":"实现标注导出携带 annotationEdit 与源图形 ID 元数据","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"画布协同实现与回归完成，详见任务级测试报告"}
+{"version":1,"at":"2026-07-07 00:09:34","changeId":"openprd-generated-change","action":"advance","taskId":"T001.07","taskTitle":"实现生图占位卡 handoff 记录携带宽高与比例契约","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"画布协同实现与回归完成，详见任务级测试报告"}
+{"version":1,"at":"2026-07-07 00:09:34","changeId":"openprd-generated-change","action":"advance","taskId":"T001.08","taskTitle":"实现hook 识别画布协同意图并注入闭环指引","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"画布协同实现与回归完成，详见任务级测试报告"}
+{"version":1,"at":"2026-07-07 00:09:34","changeId":"openprd-generated-change","action":"advance","taskId":"T001.09","taskTitle":"打通主流程闭环：用户在画布圈选原图并批注，点“标注修改请求”，Agent 读标注生成修订图并放回原图右侧 等 4 项","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"画布协同实现与回归完成，详见任务级测试报告"}
+{"version":1,"at":"2026-07-07 00:09:34","changeId":"openprd-generated-change","action":"advance","taskId":"T001.10","taskTitle":"验证canvas 服务新增 GET /api/selection 与 POST /api/insert-image 且测试通过","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"画布协同实现与回归完成，详见任务级测试报告"}
+{"version":1,"at":"2026-07-07 00:09:34","changeId":"openprd-generated-change","action":"advance","taskId":"T001.11","taskTitle":"验证标注导出带 annotationEdit 元数据并能被 hook 指引消费","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"画布协同实现与回归完成，详见任务级测试报告"}
+{"version":1,"at":"2026-07-07 00:09:34","changeId":"openprd-generated-change","action":"advance","taskId":"T001.12","taskTitle":"验证hook 对画布协同意图注入引导语","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"画布协同实现与回归完成，详见任务级测试报告"}
+{"version":1,"at":"2026-07-07 00:09:35","changeId":"openprd-generated-change","action":"advance","taskId":"T001.13","taskTitle":"回归非功能约束：界面文案面向普通用户 / API 只监听本地回环地址","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"画布协同实现与回归完成，详见任务级测试报告"}
+{"version":1,"at":"2026-07-07 00:09:35","changeId":"openprd-generated-change","action":"advance","taskId":"T001.14","taskTitle":"回归非功能约束：新增代码有集成测试覆盖","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"画布协同实现与回归完成，详见任务级测试报告"}
+{"version":1,"at":"2026-07-07 00:09:35","changeId":"openprd-generated-change","action":"advance","taskId":"T001.15","taskTitle":"回归边界条件与失败处理：边界情况：无选区时 selection API 返回空且 Agent 收到明确提示 等 5 项","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"画布协同实现与回归完成，详见任务级测试报告"}
+{"version":1,"at":"2026-07-07 00:09:35","changeId":"openprd-generated-change","action":"advance","taskId":"T001.16","taskTitle":"验证成本与额度护栏","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"画布协同实现与回归完成，详见任务级测试报告"}
+{"version":1,"at":"2026-07-07 00:09:35","changeId":"openprd-generated-change","action":"advance","taskId":"T001.17","taskTitle":"验证滥用与越权路径","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"画布协同实现与回归完成，详见任务级测试报告"}
+{"version":1,"at":"2026-07-07 00:09:35","changeId":"openprd-generated-change","action":"advance","taskId":"T001.18","taskTitle":"验证成本监控、报警和止损","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"画布协同实现与回归完成，详见任务级测试报告"}
+{"version":1,"at":"2026-07-07 00:09:35","changeId":"openprd-generated-change","action":"advance","taskId":"T001.19","taskTitle":"维护 docs/basic 项目基础文档","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"画布协同实现与回归完成，详见任务级测试报告"}
+{"version":1,"at":"2026-07-07 00:09:36","changeId":"openprd-generated-change","action":"advance","taskId":"T001.20","taskTitle":"更新文件说明书和文件夹 README","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"画布协同实现与回归完成，详见任务级测试报告"}
+{"version":1,"at":"2026-07-07 00:09:36","changeId":"openprd-generated-change","action":"advance","taskId":"T001.21","taskTitle":"运行 OpenPrd spec 校验","ok":true,"verify":null,"evidence":".openprd/harness/test-reports/canvas-collaboration-annotation-loop-20260707.md","notes":"画布协同实现与回归完成，详见任务级测试报告"}