Da Vinci

中文配套文档。若与英文原文存在差异，请以 README.md 为准。

Da Vinci 是一个把需求、Pencil 设计和实现证据串成一条线的软件交付工作流。

本仓库采用适合 agent 阅读的文档模型：README 是地图，docs/ 是记录系统，SKILL.md 是紧凑运行契约，硬门禁以真实命令输出为准。

安装

全局安装：

npm install -g @xenonbyte/da-vinci-workflow

验证 CLI：

da-vinci --help
da-vinci status

从当前 checkout 做本地开发：

npm install
npm test

核心契约

• requirements 决定 behavior。
• Pencil 决定 presentation。
• tasks 决定实现顺序。
• code 同时遵循 requirement truth 与 design truth。
• .da-vinci/DESIGN.md 是 canonical 的项目级 design truth，必须包含 Design Provenance 与 Iconography。
• .da-vinci/DA-VINCI.md 是可选的窄项目级 user-hook shell，只承载 ## User Hook Bindings。
• 新 workflow markdown 只能放在 .da-vinci/changes/<change-id>/ 下；不要在目标项目根目录创建 proposal.md、specs/、design.md、tasks.md 或 verification.md。

工作流地图

用户可见流程：

1. supplement requirements / 补充需求
2. UI design
3. task breakdown
4. task implementation
5. task verification

每次晋级都通过 dv-handoff。handoff 不是 workflow stage。自由续跑前先看 workflow-status 和 next-step。

如果输出中有 pendingHandoff，且原因是缺少 review 或 WARN 需要显式接受，下一步是 dv-handoff。如果 handoff 被拒绝、变 stale，或被 owner-stage truth 阻断，就跟随返回的 owner-stage 命令。

Agent 命令

| 目的 | Codex | Claude / Gemini | 说明 | | --- | --- | --- | --- | | 启动需求 | $dv-breakdown | /dv-breakdown | 新工作从 supplement requirements 开始。 | | 恢复路线 | $dv-continue | /dv-continue | 读取 workflow-status 和 next-step，不要猜阶段。 | | 审核晋级 | $dv-handoff | /dv-handoff | 显式审核命令，不是阶段。 | | 设计 | $dv-design | /dv-design | Pencil-backed UI design 与设计面映射。 | | 拆任务 | $dv-tasks | /dv-tasks | 把已批准需求/设计真相转成实现顺序。 | | 构建 | $dv-build | /dv-build | 执行任务并写入任务证据。 | | 验证 | $dv-verify | /dv-verify | 产出验证证据和完成检查。 | | 新建 change | $dv-change-new | /dv-change-new | 包装 da-vinci dv-change-new [change title] --json。 | | 关闭 change | $dv-change-close | /dv-change-close | 包装 da-vinci dv-change-close --json。 | | 恢复 frozen change | $dv-change-recover | /dv-change-recover | 包装 da-vinci dv-change-recover <change-id> [--confirm] --json。 | | 代码上下文 | $dv-code-context | /dv-code-context | project-level helper，不参与 route truth。 | | 修复异常状态 | $dv-repair | /dv-repair | 维护中的 install、readiness、lifecycle、worktree blocker 修复入口。 |

Codex 使用直接 $dv-* skills。Claude 和 Gemini 使用同一组 /dv-*。旧的宽泛自然语言入口和 mode-first 启动页不是当前 workflow truth。

Supporting CLI 地图

raw CLI 只作为执行细节或硬门禁证据：

• da-vinci workflow-status --project <path> [--change <id>] --json
• da-vinci next-step --project <path> [--change <id>] --json
• da-vinci bootstrap-project --project <path> [--change <id>]
• da-vinci lint-spec --project <path> [--change <id>]
• da-vinci scope-check --project <path> [--change <id>]
• da-vinci diff-spec --project <path> [--change <id>]
• da-vinci verify-bindings --project <path> [--change <id>] [--input <path>]
• da-vinci verify-implementation --project <path> [--change <id>] [--input <path>]
• da-vinci verify-structure --project <path> [--change <id>]
• da-vinci verify-coverage --project <path> [--change <id>]

review-retry-max-delay-ms 是 reviewer bridge 重试退避的上限控制项。

命令决策表

| 场景 | 用什么 | 原因 | | --- | --- | --- | | 启动一轮新需求迭代 | dv-breakdown | 新工作统一从 supplement requirements 开始。 | | 没中断且还在同一稳定阶段 | 当前阶段命令 | 真相稳定前不要晋级。 | | 中断后恢复或路线不清楚 | dv-continue | 先读 route truth 再选命令。 | | audit 后恢复 frozen change | dv-change-recover | 恢复保持 audit-first 和 confirmation-gated。 | | 阶段准备好，需要审核或收反馈 | dv-handoff | review 和 promotion 必须显式。 | | 增加设计状态、变体，或补映射已批准 surface | dv-design | 这是设计重映射，不是改需求。 | | UI 设计暴露新行为或 acceptance gap | dv-breakdown | 回退到需求，修复 requirement truth。 |

rollback / 回退一次只跨一个阶段。

Design Ops 与 Icon Ops

当前设计流是 provider-free：

1. 如果 workflow base artifacts、安装漂移、maintainer readiness 或 shared readiness 阻断路线，用 dv-repair。
2. 在 dv-design 做普通设计工作。
3. 用 da-vinci design-recommendation --project <path> --change <id> 查看 hook-owned 建议。
4. 用 da-vinci design-confirm --project <path> --change <id> --candidate <id> [--confirm] 预览 canonical 写入。
5. 只有明确覆盖时才用 da-vinci design-rebaseline --project <path> --change <id> --candidate <id> [--confirm]。
6. 晋级前通过 dv-handoff 检查 Design Review 与 Icon Verification。

设计操作 / Design Ops 负责设计 recommendation、confirmation、rebaseline 和共享 handoff review。图标操作 / Icon Ops 负责 icon discovery 与 supply management：

• da-vinci icon-search --query "<text>" [--project <path>] [--discover-remote]
• da-vinci icon-sync [--project <path>]
• da-vinci icon-bundle list|add|remove ...
• da-vinci icon-import list|add|remove --project <path> ...

Lifecycle 与 Hooks

Lifecycle 控制面：

• .da-vinci/state/change-state.json
• .da-vinci/state/change-seq.json
• .da-vinci/state/change-lifecycle.lock
• dv-change-new [change title]
• dv-change-close
• dv-change-recover <change-id> [--confirm]

命令输出先总结 active change id、title、lifecycle status、derived workflow stage、pending handoff、blocker 或 repair status。单一路线输出以 Next command: 结尾；多路线输出按 Recommended、Also valid、Mandatory rollback、Rollback 分组。

Lifecycle wrappers 会消费 --json CLI output，然后把 success / 成功与 failure / 失败优先重述成 agent 命令。raw CLI 只保留为 execution detail / 执行细节。dv-change-recover 可以补充 stale、implemented、conflict 这三类 advisory recovery analysis，但 command-owned recovery target truth 仍然优先。

Workflow hooks 是 change-local automation attachments，不是第二套路由引擎：

• system layer：.da-vinci/changes/<change-id>/hook-policy.system.json
• user layer：.da-vinci/changes/<change-id>/hook-policy.user.json
• handler kind：cli 与 agent
• cli handler 只通过 allowlist 分发允许的 internal command ids
• agent handler 使用 structured request/response envelope
• 诊断面：da-vinci hook-status、hookSummary、hookBindings
• workflow-status 会暴露 effective hook bindings 和 ownership metadata
• mutation：hook-policy-save 与 hook-policy-remove 是 user-only mutation surface
• trigger：stage:start、handoff-start、stage:start:design

stage:start:design 负责刷新 .da-vinci/changes/<change-id>/prd.md。该文件是 read-only、derived、non-truth，不替代 canonical requirements 或 design artifacts。

Code Context Helper

dv-code-context 会基于 current repository code / 当前仓库代码刷新 .da-vinci/code-context/meta.json 与 .da-vinci/code-context/index.json。它可以在没有 active change 时运行，且不能改写 route truth 或 workflow stage selection。

.da-vinci/changes/*/code-evidence/ 下的 change-local evidence 只由对应的 breakdown 或 verify handoff surface 消费。

Artifact Spine

常见 workflow artifacts：

• .da-vinci/page-map.md
• .da-vinci/design-registry.md
• .da-vinci/changes/<change-id>/proposal.md
• .da-vinci/changes/<change-id>/specs/<capability>/spec.md
• .da-vinci/changes/<change-id>/prd.md
• .da-vinci/changes/<change-id>/design.md
• .da-vinci/changes/<change-id>/pencil-design.md
• .da-vinci/changes/<change-id>/pencil-bindings.md
• .da-vinci/changes/<change-id>/tasks.md
• .da-vinci/changes/<change-id>/verification.md

完整 canonical、derived、advisory artifact map 见 docs/zh-CN/constraint-files.md 和 docs/zh-CN/project-contract-files.md。

文档地图

建议阅读顺序：

1. docs/zh-CN/workflow-overview.md：阶段骨架、route truth、handoff 边界、hooks、readiness、supporting commands。
2. docs/zh-CN/dv-command-reference.md：维护中的 dv-* 命令含义和 supporting CLI 边界。
3. docs/zh-CN/skill-usage.md：开始、恢复、回退、lifecycle、provider-free 设计、图标工作流。
4. docs/zh-CN/constraint-files.md：快速 artifact map。
5. docs/zh-CN/project-contract-files.md：详细文件契约。
6. docs/zh-CN/pencil-rendering-workflow.md：Pencil source、runtime gate、screenshot review、persistence rules。
7. docs/zh-CN/mcp-aware-gate-implementation.md：已实现 MCP runtime gate 的设计说明。
8. docs/zh-CN/maintainer-bootstrap.md：维护者 setup 和验证 lanes。
9. docs/zh-CN/documentation-authority-baseline.md：维护中、镜像、已删除和历史 surface。
10. docs/skill-contract-maintenance.md：SKILL owner-vs-mirror 规则。

英文权威入口见 README.md 和 docs/。

程序化入口

• require("@xenonbyte/da-vinci-workflow")：以命名空间方式提供 changeLifecycle、decisionMemory、runtimeEvidence、scaffold、verification、verificationPackage、workflowPersistedState。
• 子路径：/verify、/scaffold、/runtime-evidence、/workflow-persisted-state、/change-lifecycle、/decision-memory。

在补入许可证文件之前，当前包元数据标记为 UNLICENSED。

Maintainers

维护本仓库先看 docs/zh-CN/maintainer-bootstrap.md。主要检查：

• npm test
• npm run quality:ci
• npm run quality:ci:contracts
• npm run quality:ci:e2e
• npm run validate-assets
• node bin/da-vinci.js status