@xenonbyte/da-vinci-workflow 0.1.4 → 0.1.6

package/references/zh-CN/checkpoints.md

@@ -0,0 +1,123 @@
+# Checkpoints 说明
+
+> 中文配套文档。若与英文原文存在差异，请以 `references/checkpoints.md` 为准。
+
+Da Vinci 使用 checkpoint 作为执行护栏，而不是审批节点。
+
+## 执行策略
+
+- `PASS`：自动继续
+- `WARN`：记录并继续
+- `BLOCK`：只有在无法从现有工件、本地上下文或代码库解决时才停止
+
+默认 delivery intent：
+
+- 若用户未明确说明，默认视为 `full-delivery`
+- 在 `full-delivery` 下，checkpoint 不应成为停止理由，只负责判断能否安全继续
+
+恢复规则：
+
+- 当工件已存在且流程中断后，应通过 `continue` 从当前工件真相恢复，而不是重新 discovery
+
+## `discovery checkpoint`
+
+运行时机：
+
+- `brainstorm.md`
+- `project-inventory.md`
+- `design-brief.md`
+
+检查：
+
+- mode 是否正确
+- 起始材料是否足够稳定
+- 产品形态和视觉方向是否已知
+- 页面候选是否足够进入 `page-map.md`
+- open questions 是否被记录
+
+## `spec checkpoint`
+
+运行时机：
+
+- requirements 和 page scope 定义完成后
+
+检查：
+
+- scope 是否完整
+- flows 是否被命名
+- states 是否覆盖
+- acceptance 是否可测
+- `redesign-from-code` 的 spec 是否过粗
+
+## `design checkpoint`
+
+运行时机：
+
+- Pencil 页面存在后
+
+检查：
+
+- 所需页面是否都存在
+- 关键 sections 是否存在
+- 重要 states 是否体现或被明确延后
+- 视觉策略是否与 `DA-VINCI.md` 一致
+
+## `mapping checkpoint`
+
+运行时机：
+
+- `design-registry.md` 和 `pencil-bindings.md` 完成后
+
+检查：
+
+- 正确的 `.pen` 源是否已登记
+- 每个实现页面是否有 Pencil 页面或明确例外
+- 共享区域是否绑定清楚
+
+## `task checkpoint`
+
+运行时机：
+
+- 实现开始前
+
+检查：
+
+- 顶层任务组是否存在
+- 是否覆盖 spec 和 Pencil
+- 是否覆盖集成与验证
+- 顺序是否按依赖排列
+
+在 `full-delivery` 下：
+
+- `PASS` 应立即进入 Task Group 1
+- `WARN` 通常也应继续
+- 只有 `BLOCK` 才允许停止
+
+## `execution checkpoint`
+
+运行时机：
+
+- 每个顶层任务组完成后
+
+检查：
+
+- 代码是否仍符合 spec
+- 代码是否仍符合 Pencil 结构
+- 是否出现重大 scope drift
+
+## 报告格式
+
+推荐格式：
+
+```md
+## Checkpoint
+- Type:
+- Status:
+
+## Findings
+- Key point 1
+- Key point 2
+
+## Next Step
+- Continue or update artifacts
+```

package/references/zh-CN/design-inputs.md

@@ -0,0 +1,66 @@
+# 设计输入
+
+> 中文配套文档。若与英文原文存在差异，请以 `references/design-inputs.md` 为准。
+
+在收集产品形态、UI 方向和设计偏好时使用本文。
+
+## 先检查视觉契约
+
+优先检查 `DA-VINCI.md`：
+
+- 存在时，把它视为项目视觉契约
+- 不存在时，在大范围生成 Pencil 页面前先生成它
+- 不要按页面逐个重新发明视觉语言
+
+## 最低输入集
+
+至少收集或推断：
+
+1. form factor
+   - desktop software
+   - web app
+   - tablet
+   - mobile app
+
+2. visual direction
+   - minimal
+   - dense workspace
+   - brand-forward
+   - enterprise
+   - editorial
+   - utility-first
+
+3. preference details
+   - dark / light
+   - high / low density
+   - strong / restrained branding
+
+4. constraints
+   - 现有设计系统
+   - 现有品牌
+   - 现有布局外壳
+   - 响应式优先级
+
+## 推断顺序
+
+1. `DA-VINCI.md`
+2. 现有工件
+3. 现有代码库
+4. 用户陈述
+5. 直接澄清
+
+## 何时提问
+
+只有当答案会明显改变 Pencil 输出时再问简短问题。
+
+典型问题：
+
+- desktop software 还是 web app
+- dark 还是 light
+- 高密度生产力 UI 还是宽松 marketing UI
+
+## 记录位置
+
+稳定结论写入 `design-brief.md`。
+
+如果项目之前没有 `DA-VINCI.md`，则基于稳定输入生成它，作为项目视觉基线。

package/references/zh-CN/modes.md

@@ -0,0 +1,69 @@
+# 工作流模式
+
+> 中文配套文档。若与英文原文存在差异，请以 `references/modes.md` 为准。
+
+当 Da Vinci 需要决定如何开始时，使用这些 mode 定义。
+
+## `greenfield-spec`
+
+适用：
+
+- 新项目
+- 需求已经足够清晰
+
+起始工件：
+
+- `design-brief.md`
+- `proposal.md`
+- `specs/<capability>/spec.md`
+- `page-map.md`
+
+## `greenfield-brainstorm`
+
+适用：
+
+- 新项目
+- 需求来自多轮 brainstorming
+
+起始工件：
+
+- `brainstorm.md`
+- `design-brief.md`
+- `proposal.md`
+- `specs/<capability>/spec.md`
+- `page-map.md`
+
+## `redesign-from-code`
+
+适用：
+
+- 已有项目有 routes、pages、UI
+- 目标是大范围 UI 重设计
+
+起始工件：
+
+- `project-inventory.md`
+- `design-registry.md`
+- `proposal.md`
+- `specs/<capability-or-slice>/spec.md`
+- `page-map.md`
+
+说明：
+
+- 保留一个总体 `proposal.md`
+- 保留一个项目级 `page-map.md`
+- 当重设计范围较广时，`specs/` 应按 redesign slice 拆分
+
+## `feature-change`
+
+适用：
+
+- 已有项目
+- 只改系统的一部分
+
+起始工件：
+
+- `proposal.md`
+- `specs/<capability>/spec.md`
+- 受影响的 `design-registry.md`
+- `page-map.md` 的受影响部分

package/references/zh-CN/page-mapping.md

@@ -0,0 +1,43 @@
+# 页面映射
+
+> 中文配套文档。若与英文原文存在差异，请以 `references/page-mapping.md` 为准。
+
+当工作流需要把 requirements、Pencil 页面和实现页面连接起来时，使用本文。
+
+## 基本规则
+
+- `page-map.md` 是实现页面的真相源
+- `design-registry.md` 是可用 `.pen` 源的真相源
+- `pencil-bindings.md` 是实现页面到 Pencil 页面的真相源
+
+## 映射规则
+
+- 为每个实现页面定义一个 canonical page name
+- 能做到时，为每个实现页面绑定一个 canonical Pencil page
+- 若多个实现页面共享一个 Pencil 页面，要记录原因
+- 若一个实现页面需要多个 Pencil screen，要记录子页或状态拆分
+
+## 最低绑定形式
+
+页面映射示例：
+
+```md
+- `/settings/billing` -> `Billing Settings Screen`
+```
+
+共享区域示例：
+
+```md
+- `App sidebar` -> `Navigation Shell`
+```
+
+## 何时应视为 blocker
+
+以下情况说明绑定不足：
+
+- 没有活跃 `.pen` 源
+- 实现页面没有 Pencil 页面
+- Pencil 页面无法追溯到 route 或页面职责
+- 共享布局区域没有定义，继续实现会导致大量猜测
+
+此时应在 `mapping checkpoint` 停下并更新工件。

package/references/zh-CN/pencil-design-to-code.md

@@ -0,0 +1,65 @@
+# 从 Pencil 设计到代码
+
+> 中文配套文档。若与英文原文存在差异，请以 `references/pencil-design-to-code.md` 为准。
+
+当实现必须遵循 Pencil 数据时，使用本文。
+
+## 优先级
+
+遵循这个顺序：
+
+1. requirements 工件决定 behavior
+2. Pencil 数据决定 presentation
+3. screenshots 只做视觉校验
+
+不要只从外观推断行为。
+
+## 通过 Pencil 读取什么
+
+MCP 可用时，优先读取：
+
+- active `.pen` 文件
+- 目标页面 frame
+- 子 section 层级
+- 文本内容
+- layout direction
+- gap / padding
+- width / height 策略
+- fill / stroke / corner
+- 主要视觉分组
+
+优先读结构，截图是次要手段。
+
+## Pencil 到前端的默认映射
+
+- vertical frame -> column flex
+- horizontal frame -> row flex
+- gap -> `gap-*`
+- padding -> `p-*`
+- fill -> 背景样式
+- text nodes -> 语义化标题、正文、标签、按钮
+
+如果项目使用 Tailwind：
+
+- 先保布局和间距
+- 再保排版层级
+- 最后再处理装饰效果
+
+## 实现纪律
+
+基于 Pencil 编码时：
+
+- 保持 section 顺序
+- 保持内容层级
+- 保持 CTA 位置
+- 只有在结构稳定时才抽复用组件
+- 不要为了实现方便把设计结构压平到失真
+
+## 验证
+
+完成前至少比较：
+
+- 主要 sections
+- headline 和 CTA 层级
+- panel grouping
+- 所有有意偏离的部分

package/references/zh-CN/platform-adapters.md

@@ -0,0 +1,73 @@
+# 平台适配
+
+> 中文配套文档。若与英文原文存在差异，请以 `references/platform-adapters.md` 为准。
+
+在不同平台上指导用户调用 Da Vinci 时，使用本文。
+
+## Codex
+
+主入口：
+
+```text
+$da-vinci <request>
+```
+
+辅助入口：
+
+```text
+/prompts:dv-intake
+/prompts:dv-prompt
+/prompts:dv-continue
+```
+
+适用于：
+
+- requirement breakdown
+- Pencil 设计规划
+- design-to-code implementation
+- 不知道怎么写第一条提示词时的入口辅助
+
+## Claude
+
+主入口：
+
+```text
+/da-vinci <request>
+```
+
+辅助入口：
+
+```text
+/dv:intake
+/dv:prompt
+/dv:continue
+```
+
+## Gemini
+
+主入口：
+
+```text
+/da-vinci <request>
+```
+
+辅助入口：
+
+```text
+/dv:intake
+/dv:prompt
+/dv:continue
+```
+
+## 跨平台共同规则
+
+以下语义应保持一致：
+
+- artifact names
+- checkpoint names
+- drift policy
+- requirement / design / code 契约
+- mode names
+- prompt helper 的语义
+
+不同平台可以有不同命令语法，但工作流语义不能漂移。

package/references/zh-CN/prompt-recipes.md

@@ -0,0 +1,161 @@
+# 提示词配方
+
+> 中文配套文档。若与英文原文存在差异，请以 `references/prompt-recipes.md` 为准。
+
+当用户需要帮助启动或恢复 Da Vinci，但不知道该写什么提示词时，使用本文档。
+
+## 三个入口动作
+
+- `intake`
+  - 选择最合适的 mode，并生成第一条主提示词
+- `prompt`
+  - 直接生成场景化提示词
+- `continue`
+  - 检查现有工件，并生成继续提示词
+
+## 固定规则
+
+- `intake` 和 `continue` 通常应该输出主工作流提示词
+- 不要默认把 `intake` 或 `continue` 直接导向 `build`
+- 只有在 tasks、设计绑定和实现就绪都很明确时，才直接使用 `build`
+- `continue` 应优先沿用现有工件真相，而不是重新开始 discovery
+
+## 提示词里必须说清楚的真相源
+
+高质量提示词应明确：
+
+1. behavior source of truth
+   - 现有代码
+   - 正式 spec
+   - 已批准 requirements
+
+2. design source of truth
+   - Pencil `.pen`
+   - HTML 参考稿
+   - Figma 导出
+   - `DA-VINCI.md`
+
+3. delivery intent
+   - `plan-only`
+   - `design-only`
+   - `full-delivery`
+
+4. conflict rule
+   - 当代码和设计冲突时，以谁为准
+
+5. coverage expectations
+   - states
+   - subpages
+   - dialogs
+   - sheets
+   - nested flows
+
+## `intake` 输出结构
+
+通常应输出：
+
+- 推荐 mode
+- 推荐 delivery intent
+- 一条主执行提示词
+- 必要时的一条更保守版本
+- 必要时的一条 continue 提示词
+- 会明显影响结果的缺失信息
+
+## `prompt` 输出结构
+
+通常应输出：
+
+- 一条主提示词
+- 必要时的一条保守版本
+- 必要时的一条 continue 版本
+
+## `continue` 输出结构
+
+先检查：
+
+- `DA-VINCI.md`
+- `.da-vinci/project-inventory.md`
+- `.da-vinci/design-registry.md`
+- `.da-vinci/page-map.md`
+- `.da-vinci/changes/<change-id>/` 下的当前工件
+
+再输出：
+
+- 当前工作流状态判断
+- 薄弱或缺失的工件
+- 一条主继续提示词
+- 必要时的一条保守继续版本
+
+## Mode 选择启发式
+
+- `greenfield-spec`
+  - 新项目
+  - 需求已清晰
+
+- `greenfield-brainstorm`
+  - 新项目
+  - 输入仍然发散或矛盾
+
+- `redesign-from-code`
+  - 已有项目
+  - 当前代码是行为真相
+  - 目标是大范围 UI 重设计
+
+- `feature-change`
+  - 已有项目
+  - 目标是局部修改
+
+## 场景配方：已有项目全局换 UI
+
+推荐：
+
+- mode：`redesign-from-code`
+- behavior truth：现有代码
+- design truth：HTML、Pencil 或其他视觉参考
+- delivery intent：通常为 `full-delivery`
+
+提示词应明确：
+
+- 保留现有行为
+- 保留 state transition 和集成
+- inventory 所有页面和状态
+- 按可实施的 redesign slice 拆分
+- 记录代码和设计参考之间的差异
+
+## 场景配方：现有代码 + HTML 参考稿
+
+提示词应明确：
+
+- 代码是行为真相
+- HTML 目录只是 presentation 参考
+- 冲突时保留行为，并记录差异
+- 要仔细覆盖 states、subpages、dialogs、overlays
+
+## 场景配方：盘点后继续
+
+如果项目已经有：
+
+- `project-inventory.md`
+- `page-map.md`
+- 初步的 proposal 或 specs
+
+那么 `continue` 通常应该生成一条提示词：
+
+- 以当前工件为工作基线
+- 补齐设计绑定
+- 进入 tasks
+- 若 delivery intent 为 `full-delivery`，继续到实现
+
+## 场景配方：任务后继续
+
+如果项目已经有：
+
+- `tasks.md`
+- 合法的 spec slices
+- 设计绑定或明确的设计缺口记录
+
+那么 `continue` 通常应该：
+
+- 从当前 task checkpoint 恢复
+- 若无真实 blocker，立即开始实现
+- 在每个顶层任务组后继续执行 execution checkpoint