Da Vinci

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

Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计、页面绑定、实现任务和最终代码的交付工作流。

它遵循一个固定契约：

• requirements 决定 behavior
• Pencil 决定 presentation
• code 同时遵循 requirements 和 Pencil

Da Vinci 适合什么场景

当一个项目需要同时把这三层对齐时，适合使用 Da Vinci：

1. 需求拆解
2. Pencil 支撑的 UI 设计
3. 基于需求和设计数据的实现

典型场景：

• 0 到 1 的产品交付
• 从 brainstorming 走向可实施产品
• 基于现有代码做全局 UI 重设计
• 基于现有代码做流程、逻辑和 UI 一起变化的大改版
• 在现有产品上做范围明确的 feature-change

当前发布状态

最新已发布 npm 包：

• @xenonbyte/[email protected]

已发布版本重点：

• da-vinci supervisor-review --run-reviewers 现已支持 reviewer 并发执行与失败重试退避（--review-concurrency、--review-retries、--review-retry-delay-ms）
• 新增可选 test:supervisor-review-integration 烟测，用于覆盖真实 codex exec 评审执行链路（通过 DA_VINCI_RUN_SUPERVISOR_INTEGRATION=1 启用）
• supervisor-review 解析现已显式覆盖中文 legacy 轮次标题（例如 ## Design-Supervisor Review（第2轮尝试）），并保持“优先结构化评审块”的回退策略可预测
• --nodes-file 元数据误传保护现在优先输出更短的相对路径（在 cwd 外仍回退绝对路径），便于日志阅读
• audit 解析职责已拆分到 lib/audit-parsers.js，lib/audit.js 体量下降，可维护性更好
• 递归文件扫描改为安全有界遍历：增加深度/数量上限，并跳过符号链接
• completion/integrity audit 现在会拦截并忽略 design-registry.md 中越出项目根目录的 .pen 引用
• preflight-pencil 沙箱增强：拦截危险运行时 token、禁用动态代码生成，并对超时失败给出明确分类
• icon-search 与 icon-aliases 现在复用同一套文本归一化/分词逻辑，去掉重复实现并补了一致性回归测试
• da-vinci pencil-session end 现在默认要求提供 live 快照输入（--nodes-file）；只有显式 --force 才允许跳过，避免 live MCP 与磁盘未同步时被静默关闭
• build 路由现在明确：编译成功不等于流程完成；对外宣布终态前必须通过 da-vinci audit --mode completion --change <change-id> <project-path>
• continue 的推荐规则现在会拦截未过设计门禁时的 build 选路（缺少项目内 .pen、session 未关闭、runtime/design-source BLOCK、required design-supervisor BLOCK）
• 新增回归测试覆盖：session 结束同步防护，以及 build/continue 提示词级门禁约束
• continue 的选路与恢复规则现已统一：先看工件/checkpoint 真相，再把 Context Delta 当作辅助信息
• Context Delta 审计规则已强化：触发信号更精确、告警改为状态不一致语义，并补充 supersedes 校验与时间归一化
• checkpoint 相关工件默认自动启用 Context Delta 期望检查；只有少数无 checkpoint 标题的工件才需要显式 Context Delta Required
• design-supervisor review 现在成为正式的最终风格质量 gate，并通过 Require Supervisor Review 明确区分“建议性”与“硬门槛”
• Visual Assist 文档现在补全了 gate 顺序、每层 gate 怎么审，以及 screenshot review、layout hygiene、design checkpoint、design-supervisor review 之间的分叉规则
• 移动端、桌面端、Web、平板四套 visual-assist-presets 现在都提供三种明确变体：只有 adapter、reviewer 建议性审查、reviewer 硬签字，中英文一致
• completion / integrity audit 现在真正以 Require Supervisor Review: true 作为硬门槛开关，而不是只要配置 reviewer 就一律阻断
• design-supervisor review 记录现在必须有明确状态、问题列表和回改结果，才算有效审查证据
• Pencil 锁等待现在改成阻塞 sleep，不再 busy wait 空转 CPU，同时保留同步 CLI/session 的调用语义
• 项目内 .pen 持久化现在改为“从 MCP 快照写回磁盘”的正式路径，不再依赖 headless interactive save()
• 重设计流程现在要求在第一次 Pencil 编辑前先 seed 一个登记好的项目内 .pen，并记录后续持久化快照 hash 以便做同步校验
• da-vinci write-pen 现在可以把 MCP 可读的节点和变量快照原子写成工作流管理的 .pen 文件，并可选地做 reopen 校验
• da-vinci ensure-pen 现在可以在 live 编辑开始前 seed 或校验登记好的项目内 .pen
• da-vinci check-pen-sync 现在可以把当前 live MCP 快照和已持久化的项目内 .pen 做同步比对
• da-vinci snapshot-pen 现在只作为 disk-to-disk 工具，用来从已有 Pencil 源重建规范化 .pen 并验证重新打开结果
• visual adapter 的执行现在要求在运行时明确声明解析出来的主 adapter，以及哪些请求的 adapter 当前不可用
• frontend-skill、frontend-design 这类跨平台近名 adapter 现在明确视为不同能力源，除非当前环境真的解析到了它们
• 复杂 redesign-from-code 现在要求在大规模 Pencil 设计前先写 visual thesis、content plan、interaction thesis 和 anchor surface 的 structural-delta 说明
• screenshot review 现在被明确强调为硬闸门；只要分析指出 hierarchy、spacing、clarity 或 inconsistency 问题，就不能自动判通过
• form factor 专用的 layout hygiene 现在被定义成独立于 Visual Assist 的硬闸门，mobile、tablet、desktop、web 都有各自的 blocker 条件
• .da-vinci/designs/ 现在更明确只用于放 .pen 文件，而且第一次 Pencil 写入后就要验证对应 .pen 已经成为 shell 可见文件
• 多 surface 重设计现在要求先从已通过的 anchor surface 中抽出 shared primitive family，再扩展更多页面
• Pencil 生成规则现在明确拒绝 flex、margin 这类 Web 属性
• visual adapter 解析现在要求“解析出来的主 adapter 必须真正主导首轮设计”，而不是只登记在工件里
• 复杂重设计现在默认采用 anchor-first 的 Pencil 生成策略：先做 1 到 3 个 anchor surface，截图审查后再扩展
• design checkpoint 现在会明确拦截大量空占位、重复模板和过早的大批量多页面脚手架
• 移动端、桌面端、Web、平板的提示词模板现在都包含 Simple redesign、Complex redesign、Design-only、Continue
• redesign-from-code 现在明确写清：现有代码只是真相行为，不是真相布局
• 复杂页面现在明确要求在大规模 Pencil 重设计前拆成 subpage、overlay、明显不同 state 和 implementation surface
• design checkpoint 现在明确会拦截旧 UI 换皮、通用卡片拼贴、弱视觉锚点和装饰性噪音
• Visual Assist 文档现在补了快速上手建议和“设计质量优先”配置
• visual adapter 的配置字段、解析顺序和回退行为现在有单独文档说明
• 现在提供按移动端、桌面端、Web、平板拆分的 Visual Assist 可复制模板
• 仓库内的 forward test 示例现在展示了 Visual Assist、adapter 解析结果和 .pen 持久化记录方式
• Codex 的自然语言用法现在有单独文档，明确说明 intake、prompt、continue 和直接 mode 调用方式
• 项目内 Pencil .pen 文件现在明确约定默认持久化到 .da-vinci/designs/
• 设计源登记和工件模板现在会记录项目内优先使用的 .pen 路径
• intake、prompt、continue 三个提示词入口辅助路由已随 Codex、Claude、Gemini 一起发布
• 中文配套文档现在刻意只保留 README.zh-CN.md 和 docs/zh-CN/
• 资产校验现在覆盖完整的随包文档集合
• da-vinci status 会校验 Codex、Claude、Gemini 的完整安装资产
• Claude 和 Gemini 安装后的命令文案已改为自洽的工作流措辞
• .npmrc 和 openspec/ 现在只本地保留，不再进入版本管理和 npm 包
• 安装、卸载、状态、资产校验都通过 Node CLI 提供
• 仓库内含一个 greenfield-spec 的本地 forward test

支持的工作流模式

Da Vinci 当前支持五种模式：

greenfield-spec

新项目，且需求已经足够清晰，可以直接写 spec。

greenfield-brainstorm

新项目，但输入仍然比较发散，需要先做梳理和收敛。

redesign-from-code

已有项目，代码和行为已存在，目标是做广泛或全局的 UI 重设计。

overhaul-from-code

已有项目，但目标是做系统级大改版；现有代码是参考证据和迁移基线，不是新系统最终行为真相。

feature-change

已有项目，只做某个功能、页面、流程的局部修改。

提示词入口辅助路由

当你知道自己需要 Da Vinci，但不想自己手写第一条高质量提示词时，可以使用下面三类入口：

• intake
  • 帮你判断该用哪个 mode，并生成最合适的主入口提示词
• prompt
  • 在场景已知时，直接生成可复制执行的提示词
• continue
  • 项目里已经有 .da-vinci/ 工件时，帮你判断如何继续

默认建议：

• 复杂的存量项目重设计，优先用 intake
• 已有工件后继续推进，优先用 continue
• 已经明确知道场景，只缺提示词文本时，用 prompt

重要规则：

• intake 和 continue 通常应该回到主工作流入口，即 $da-vinci ... 或 /da-vinci ...
• 它们不应该默认把用户直接导向 build
• build 仍然保留，但它是给已经实现就绪的高级直接入口
• continue 的选路应先看工件和 checkpoint 真相，再看上下文补充信息
• Context Delta 只用于恢复上下文，不是阶段判定真相源
• 如果 Context Delta 与当前工件冲突，应该忽略冲突条目并按工件真相继续

Visual Assist 快速上手

当项目想借助本地 UI 设计 skill，例如 frontend-skill 或 ui-ux-pro-max，来提升设计质量时，就配置 Visual Assist。

推荐默认配置：

## Visual Assist
- Preferred adapters: ui-ux-pro-max, frontend-skill
- Design-supervisor reviewers: frontend-skill, ui-ux-pro-max
- Design-supervisor review mode: screenshot-and-theme
- Design-supervisor review inputs: screenshots, pencil variables, visual thesis, content plan, interaction thesis
- Scope: visual contract refinement, page composition, hierarchy and spacing, anchor-surface composition, Pencil design refinement
- Fallback: native-da-vinci
- Require Adapter: false
- Require Supervisor Review: false

适用场景：

• app、dashboard、桌面工具等产品型界面
• 本地没有 adapter 时工作流也应该继续
• 想提升构图和层级，但不希望 adapter 缺失变成阻塞

设计质量优先配置：

## Visual Assist
- Preferred adapters: frontend-skill, ui-ux-pro-max
- Design-supervisor reviewers: frontend-skill, ui-ux-pro-max
- Design-supervisor review mode: screenshot-and-theme
- Design-supervisor review inputs: screenshots, pencil variables, visual thesis, content plan, interaction thesis
- Scope: visual contract refinement, page composition, hierarchy and spacing, motion guidance, anchor-surface composition, Pencil design refinement
- Fallback: native-da-vinci
- Require Adapter: true
- Require Supervisor Review: true

适用场景：

• 页面视觉质量要求高，不能接受普通 fallback 质量
• 之前的重设计已经出现“堆卡片、弱锚点、只是旧 UI 换皮”这类问题
• 你希望没有强设计辅助 skill 时直接停下，而不是继续生成普通结果

选择建议：

• 高密度 app、dashboard、工具型界面，且视觉要求中等时，优先把 ui-ux-pro-max 放第一位
• 如果更重视 art direction、构图和高级感，就把 frontend-skill 放第一位
• Preferred adapters 里要写当前环境里真实存在的 adapter 名，不要默认套用跨平台别名
• 一旦配置了 Preferred adapters，解析出来的主 adapter 应该真正主导首轮设计，而不是只登记在工件里
• 运行时必须明确写出解析出来的主 adapter，以及哪些请求的 adapter 当前不可用
• form factor 专用的 layout hygiene 是独立于 Visual Assist 的硬闸门；adapter 选择不能覆盖 mobile、tablet、desktop、web 的版式失败条件
• 不要默认把跨平台的近名 adapter 当成同一个能力源
• 在第一个 anchor surface 之前，先写 visual thesis、content plan 和 interaction thesis
• Pencil 的 guide 只应该约束平台布局和可实现性，不应该替代主 adapter 成为设计方向来源
• 面对复杂重设计时，先做 1 到 3 个 anchor surface，并完成截图审查，再扩展到更多页面
• 对每个 anchor surface，都要说明“新的构图和当前布局结构相比，具体改了什么”
• 如果截图分析指出 hierarchy、spacing、clarity、inconsistency 或 unresolved placeholder 问题，就不能自动判通过
• 在扩展更多页面前，先从已通过的 anchor surface 中抽出 shared primitives
• .da-vinci/designs/ 只应该放 .pen 文件，并且第一次 Pencil 写入后就要验证登记路径已经成为 shell 可见文件
• 只使用 Pencil 支持的属性，不要继续使用 flex、margin 这类 Web 属性
• 默认保留 Fallback: native-da-vinci
• Require Adapter 默认保持 false，只有设计要求很高时再改成 true
• 把 Design-supervisor reviewers 和 Preferred adapters 分开；adapter 负责首轮设计引导，reviewer 负责最终风格质量把关
• Require Supervisor Review 默认保持 false，只有“reviewer 签字本身就是交付门槛”时才改成 true
• Require Supervisor Review: true 表示只要缺失、阻断、或未被接受的 reviewer 结果，就不能扩屏、交接实现或宣告完成
• Scope 只管 presentation 质量，不要拿它去定义 behavior、route 或 state truth

核心工作流顺序

Da Vinci 的默认顺序是：

1. 选择 mode
2. 生成正确的源工件
3. 检测或生成 DA-VINCI.md
4. 收集设计输入，优先使用 .da-vinci/designs/ 下的项目内 .pen 文件，并登记设计源
5. 定义或发现页面地图
6. 创建或更新 Pencil 设计
7. 绑定实现页面到 Pencil 页面
8. 通过 MCP 读取 Pencil 设计数据
9. 生成实现任务
10. 根据 requirements 和 Pencil 数据实现代码
11. 校验需求漂移和设计漂移

默认工件

根据不同 mode，工作流可能使用这些工件：

• .da-vinci/changes/<change-id>/brainstorm.md
• .da-vinci/project-inventory.md
• DA-VINCI.md
• .da-vinci/changes/<change-id>/design-brief.md
• .da-vinci/design-registry.md
• .da-vinci/designs/
• .da-vinci/page-map.md
• .da-vinci/changes/<change-id>/proposal.md
• .da-vinci/changes/<change-id>/specs/<capability>/spec.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

工件含义：

• brainstorm.md：需求尚未稳定前的原始想法整理
• project-inventory.md：现有代码库里的路由、页面、UI 结构盘点
• DA-VINCI.md：项目级视觉契约
• design-brief.md：设计方向、形态、密度、品牌和限制条件
• migration-contract.md：存量系统在大改版中哪些保留、修改、废弃、待确认的边界
• design-registry.md：项目级 .pen 设计源登记
• .da-vinci/designs/：项目内持久化的 Pencil 设计源，例如 project-baseline.pen 或按 change 保存的 .pen 文件
• page-map.md：页面、职责、状态和共享区域
• proposal.md：范围、目标、非目标和成功标准
• spec.md：行为、状态、边界和验收规则
• design.md：信息架构、页面结构和交互策略
• pencil-design.md：Pencil 页面、屏幕、注释和说明
• pencil-bindings.md：实现页面和 Pencil 页面之间的映射
• tasks.md：任务分组和实施顺序
• verification.md：覆盖度和漂移检查

工件放置建议

推荐结构：

project/
├── DA-VINCI.md
└── .da-vinci/
    ├── project-inventory.md
    ├── design-registry.md
    ├── designs/
    │   ├── project-baseline.pen
    │   └── <change-id>.pen
    ├── page-map.md
    └── changes/
        └── <change-id>/
            ├── brainstorm.md
            ├── design-brief.md
            ├── migration-contract.md
            ├── proposal.md
            ├── design.md
            ├── pencil-design.md
            ├── pencil-bindings.md
            ├── tasks.md
            ├── verification.md
            └── specs/
                └── <capability>/spec.md

规则：

• DA-VINCI.md 放在项目根目录
• 项目级工作流工件放在 .da-vinci/
• 项目内持久化的 Pencil .pen 文件默认放在 .da-vinci/designs/
• change 级工件放在 .da-vinci/changes/<change-id>/

设计源规则

• DA-VINCI.md 是跨页面视觉一致性的项目级视觉契约
• design-registry.md 用来登记项目中的 .pen 设计源
• .da-vinci/designs/ 是项目内持久化 .pen 文件的默认位置
• page-map.md 是实现页面和状态的真相源
• pencil-bindings.md 是实现页面到 Pencil 页面绑定的真相源
• 在 redesign-from-code 里，现有代码只是真相行为，不是真相布局
• 在 overhaul-from-code 里，现有代码是参考证据和迁移基线，不是新系统最终行为真相
• 复杂页面在 Pencil 重设计前应该先拆成 subpage、state、overlay 和 implementation surface
• design-registry.md 里登记的首选 .pen 路径属于工作流自动维护的状态，不应该依赖用户手工填写
• 一旦进入 Pencil 设计，Da Vinci 应该使用或创建这个项目内 .pen 路径，而不是继续沿用当前随手打开的 Pencil 文档
• 如果 Pencil MCP 修改了 live 文档但没有自动把项目内 .pen 文件落到磁盘，工作流应该先把该 .pen 文件补写到登记路径，再把这轮设计当成可追踪结果
• 在进入 pencil-bindings.md 和实现任务前，应该先通过 design-source checkpoint，确认登记路径、当前设计源和 shell 可见 .pen 文件已经收敛成同一个项目级来源

可选 visual adapter 规则：

• DA-VINCI.md 可以声明期望使用的 visual adapter 来辅助设计
• visual adapter 只用于增强构图、层级、留白、节奏和 motion 判断
• 它可以影响 DA-VINCI.md、design.md、pencil-design.md
• 它不能覆盖 behavior truth、路由真相、页面状态真相或验收规则
• 如果本地没有请求的 adapter，Da Vinci 应继续使用原生设计规则，并在 design-registry.md 里记录回退结果

建议做法：

• 在开始大规模 Pencil 设计前，就在 DA-VINCI.md 里写好 Visual Assist
• 面对复杂 Android 重设计时，先要求 Da Vinci 把 activities、fragments、tabs、sheets、dialogs 和明显不同的 states 拆开
• 如果结果很丑，就把 frontend-skill 提到第一位，收紧 design checkpoint，并明确要求 fresh composition，而不是旧 UI 改色

当已有页面映射存在时：

• 优先复用已绑定的 Pencil 设计源
• 如果 design-registry.md 里已经登记了 .da-vinci/designs/ 下的本地 .pen 路径，优先使用它
• 不要在没有同步 design-registry.md 的情况下，悄悄切到另一个当前活动编辑器路径继续设计

当已有代码存在但还没有映射时：

• 先从当前项目重建设计基线
• 重建 inventory、page-map、design-registry
• 先把复杂容器拆成真实的设计 surface，再进入大规模 Pencil 设计
• 先解析出明确的项目内 .pen 目标路径，再把新的 Pencil 基线真正落到 .da-vinci/designs/

当既没有映射也没有可用设计源时：

• 基于当前本地真相源创建新的 Pencil 基线
• 把基线落到 .da-vinci/designs/
• 并在 design-registry.md 里记录准确路径

如果项目声明了 visual adapter：

• 先看用户请求，其次看 DA-VINCI.md，再看本地可用 skill
• 如果存在多个可用辅助 skill，收敛出一个 primary adapter，必要时再保留 secondary helpers
• 默认把它当成非阻塞增强层
• 只有用户明确要求必须使用某个 adapter 时，缺失才应阻塞工作流

安装

安装 npm 包：

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

安装平台资产：

da-vinci install --platform codex,claude,gemini

常用命令：

da-vinci status
da-vinci validate-assets
da-vinci audit --mode integrity /abs/path/to/project
da-vinci audit --mode completion --change <change-id> /abs/path/to/project
da-vinci icon-sync                      # 默认容错；需要强门禁时加 --strict
cp references/icon-aliases.example.json ~/.da-vinci/icon-aliases.json
da-vinci icon-search --query "settings lock" --family material --top 8
da-vinci supervisor-review --project /abs/path/to/project --change <change-id> --run-reviewers --write
da-vinci preflight-pencil --ops-file /abs/path/to/ops.txt
da-vinci uninstall --platform codex,claude,gemini

da-vinci audit 现在有两种主要模式：

• --mode integrity：适合在工作进行中检查文件系统真相，比如基础工件缺失、导出路径错误、.da-vinci/designs/ 被污染、项目内 .pen 没落盘
• --mode completion：适合在宣称完成前做严格检查；配合 --change <change-id> 使用，任何失败都应视为阻断

Context Delta 与 audit 的关系：

• Context Delta 缺失、字段不完整或与最新 checkpoint 不一致时，属于告警（WARN）
• 这些告警用于提升续跑质量，不应单独变成新的 completion 失败门槛
• 当工件包含 ## Checkpoint Status 或 ## MCP Runtime Gate 时，期望检查会自动启用，正常流程不需要手动开关
• 只有在不包含这些标题但仍想启用检查时，才需要写 Context Delta Required: true（也支持 yes / on / 1）

两种模式都会检查项目里最常见的工作流完整性问题：

• 标准 Da Vinci 工件缺失
• 项目内 shell 可见 .pen 设计源缺失
• .da-vinci/designs/ 目录被污染
• 截图导出写到了错误位置
• change scaffold 只有空目录或只写了一半

da-vinci preflight-pencil 是给非小型 batch_design 用的静态预检：

• 在发给 Pencil MCP 之前先抓出 JS-like 语法错误
• 直接标出常见 schema 漂移，比如错误 padding、非法 hex 颜色、flex、margin、overflow
• 当 anchor-surface 批次太大时给出拆批警告，避免继续大块回滚

da-vinci icon-search 用于在渲染前选择更稳定的 icon_font 名称：

• 先运行 da-vinci icon-sync，把官方图标名同步到 ~/.da-vinci/icon-catalog.json
• 默认是用户级缓存（当前 HOME 下），同一用户执行一次通常可被多个项目复用
• 当上游图标库有更新，或你需要最新新增图标时，建议重新执行 da-vinci icon-sync
• icon-sync 默认对上游部分失败不阻塞（会标记 Status: DEGRADED）；如果 CI 需要任何源失败即退出，请使用 da-vinci icon-sync --strict
• 如果你要项目隔离，可用 --catalog <path> 指定项目级 catalog
• 可选创建 ~/.da-vinci/icon-aliases.json（可从 references/icon-aliases.example.json 拷贝），用于 保险箱、解密、重试 这类业务词
• 支持中英文混合关键词检索
• 支持家族过滤（material、rounded、outlined、sharp、lucide、feather、phosphor）
• 检索排序会自动叠加别名扩展词
• 返回排序候选，并附带可直接复用的 icon_font 节点 payload 提示
• Icon System Guidance (Advisory) 可复制模板见 docs/constraint-files.md 与 references/artifact-templates.md

da-vinci supervisor-review 提供本地结构化评审记录能力：

• 加上 --write 时，会把 Configured reviewers、Executed reviewers、Review source、Status、Issue list、Revision outcome 写入 pencil-design.md
• 可通过 --status PASS|WARN|BLOCK 显式指定，也可基于当前设计工件做保守推断
• 对 required supervisor gate，优先使用 --run-reviewers --write，让 reviewer skills 执行与结果持久化一体完成
• reviewer 执行参数可通过 --review-concurrency、--review-retries、--review-retry-delay-ms 调优（指数退避）
• design-supervisor review 作为兼容别名仍可使用

当 Pencil MCP 可用时，Da Vinci 现在还要求在终态完成声明前，把 MCP runtime gate 结果记录到 pencil-design.md。这层 gate 负责检查 live editor/source convergence，与 filesystem audit 分工不同。 在重设计进行中，如果有 shell 能力，应在第一次成功写入 Pencil 后立即运行 da-vinci audit --mode integrity <project-path>；如果同一个 anchor surface 连续回滚，则继续配合 da-vinci preflight-pencil 和更小的 follow-up batch。

项目内 .pen 持久化现在分成两条受支持路径：

• 首次运行路径：先用 da-vinci ensure-pen --output <path> --verify-open seed 登记好的项目内 .pen，打开这个精确路径，然后把后续 MCP 快照持续写回同一个文件
• 继续迭代路径：如果项目里原本已有登记的 .pen，先打开它继续工作；但发生实质性 live edit 后，要把当前 live MCP 快照重新持久化回同一路径，并运行 da-vinci check-pen-sync

如果是自治运行，session wrapper 只要可用就必须使用。只有 wrapper 确实不可用时，才退回底层 helper。

持久化命令：

• 自治运行必须使用的 session 命令：
  • da-vinci pencil-session begin --project <project-path> --pen <path>
  • da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>
  • da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>
• da-vinci ensure-pen --output <path> --verify-open
• da-vinci write-pen --output <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version> --verify-open
• da-vinci check-pen-sync --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>
• da-vinci snapshot-pen --input <existing.pen> --output <target.pen> --verify-open（仅限 disk-to-disk）
• da-vinci pencil-lock acquire --project <project-path> / da-vinci pencil-lock release --project <project-path>

在 Pencil 底层 save() 语义再次被证明可靠之前，不要把 headless interactive save() 当作权威持久化真相。 completion audit 现在还会检查 .da-vinci/state/pencil-session.json 是否记录了最新的 .pen hash，所以自治运行优先走 pencil-session 封装。

安装目标：

• Codex prompts：~/.codex/prompts/
• Codex skill：~/.codex/skills/da-vinci/
• Claude commands：~/.claude/commands/
• Gemini commands：~/.gemini/commands/

平台使用方式

Codex

主入口：

$da-vinci <request>

辅助入口：

$da-vinci use intake for <project situation>
$da-vinci use prompt for <known scenario>
$da-vinci use continue for <existing workflow state>

Claude

主入口：

/da-vinci <request>

辅助入口：

/dv:intake
/dv:prompt
/dv:continue

Gemini

主入口：

/da-vinci <request>

辅助入口：

/dv:intake
/dv:prompt
/dv:continue

示例请求

Greenfield spec

$da-vinci use greenfield-spec to break down a new desktop software project for annotated design delivery

Brainstorm synthesis

$da-vinci use greenfield-brainstorm to turn several product ideas into a page map, Pencil design plan, and implementation tasks

Redesign from code

$da-vinci use redesign-from-code to inventory the existing app, identify current pages, and generate a new Pencil-backed UI plan

Overhaul from code

$da-vinci use overhaul-from-code to inventory the current product, define preserve/revise/retire boundaries, rewrite the target flows and specs, and generate a Pencil-backed overhaul plan

Feature change

$da-vinci use feature-change to add a billing page, generate the relevant Pencil design delta, and create implementation tasks

复杂重设计先做 intake

$da-vinci use intake for this existing Android project.

I need to globally replace the UI.
Existing Android code is the behavior source of truth.
HTML references are in /abs/path/to/mockups.
Treat this as full-delivery unless I explicitly narrow it to design-only.

已有工件后继续推进

$da-vinci use continue for this existing redesign-from-code workflow.

Use the existing Da Vinci artifacts.
Continue into full-delivery.

大改版场景继续推进

$da-vinci use continue for this existing overhaul-from-code workflow.

Use the existing Da Vinci artifacts.
Continue from proposal, migration-contract, and target specs into design or implementation.

文档导航

英文文档：

• docs/codex-natural-language-usage.md
• docs/dv-command-reference.md
• docs/prompt-entrypoints.md
• docs/prompt-presets/
  • 每个场景文件都包含 Simple redesign、Complex redesign、Design-only、Continue
• docs/workflow-overview.md
• docs/pencil-rendering-workflow.md
• docs/constraint-files.md
• docs/visual-adapters.md
• docs/visual-assist-presets/
• docs/workflow-examples.md
• docs/mode-use-cases.md
• references/

中文文档：

• README.zh-CN.md
• docs/zh-CN/dv-command-reference.md
• docs/zh-CN/prompt-presets/
  • 每个场景文件也都包含 Simple redesign、Complex redesign、Design-only、Continue
• docs/zh-CN/workflow-overview.md
• docs/zh-CN/pencil-rendering-workflow.md
• docs/zh-CN/constraint-files.md
• docs/zh-CN/visual-adapters.md
• docs/zh-CN/visual-assist-presets/
• docs/zh-CN/

仓库布局

da-vinci/
├── SKILL.md
├── README.md
├── README.zh-CN.md
├── agents/
│   └── openai.yaml
├── commands/
│   ├── claude/
│   ├── codex/
│   └── gemini/
├── docs/
│   └── zh-CN/
└── references/