flower-trellis 0.1.0

package/enhancements/0.5/.agents/skills/trellis-create-command/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: trellis-create-command
+description: "Create a new trellis entry as command or skill; writes agents copy and optionally skill-garden."
+---
+# Create New Trellis Entry
+
+创建一个新的 trellis 入口。支持两种形态：斜杠命令（command）或 Claude skill。
+
+> **与 trellis-migrate-skill 区分**：本 skill 针对"从零创建"；已有命令要迁移成 skill 用 `trellis-migrate-skill`。
+
+---
+
+## 适用场景
+
+- 给项目加一个新 trellis 工具入口
+- 现有命令集不覆盖某类需求，需要扩展
+- 从零设计新的工作流步骤
+
+---
+
+## 执行步骤
+
+### Step 0: 确定路径
+
+**`<target>`（落地项目）**：默认 = 当前工作目录（`pwd`）。
+
+- 若用户没有明确说"在其他项目"，直接用当前项目
+- 若用户明确要在其他项目创建，改用其指定的绝对路径；本 skill 不主动 `cd`，只记住该路径用于后续写入
+- 若目标项目就是 skill-garden 本身（在 skill-garden 仓库里 `create-command`），`<target>` 与 `<skill-garden>` 指同一路径，**避免重复写入**（只写一次）
+
+**`<skill-garden>`（分发源，scope 含 skill-garden 时必需）**：默认 `/root/project/skill-garden`。
+
+- 路径不存在或与用户期望不符 → 询问用户确认
+- 无需分发时（scope = 只装本项目）整段忽略
+
+### Step 1: 收集基本信息
+
+与用户确认：
+
+| 项 | 说明 | 示例 |
+|----|------|------|
+| **name** | kebab-case，动词或动词短语开头 | `review-pr`、`sync-data`、`check-deps` |
+| **description** | 要完成什么、产出什么 | "检查 PR 代码变更是否符合项目规范" |
+| **scope** | 只装本项目 / 也装 skill-garden | 问用户：是否要分发到其他项目？ |
+
+### Step 2: 选形态（command vs skill）
+
+| 形态 | 何时选 | 触发方式 |
+|------|--------|---------|
+| **command** | 显式动作、高风险、需确认点（如 finish-work、continue） | `/trellis:<name>` |
+| **skill** | 自然语可触发、查询 / 分析 / 检查、低破坏性（如 check-all、analyze-task、draw-uml） | Claude 自动路由 + `/trellis-<name>` |
+
+决定不了时**推荐 skill**：自然语路由更灵活，显式斜杠仍可用。反过来，后悔做成 skill 想改 command 比较费事。
+
+### Step 3: 生成内容骨架
+
+按形态和复杂度生成初稿：
+
+**简单 skill / command**（< 50 行）：
+
+```markdown
+<frontmatter 仅 skill 有>
+# <标题>
+
+<1-2 行简介>
+
+## 适用场景
+- <触发点 1>
+- <触发点 2>
+
+## 执行步骤
+### Step 1: <动作>
+### Step 2: <动作>
+
+## 反模式
+- ❌ <误用 1>
+- ❌ <误用 2>
+```
+
+**复杂 skill / command**（50-300 行）：
+
+```markdown
+<frontmatter>
+# <标题>
+
+<简介>
+
+## 适用场景 / 前置条件
+
+## 执行步骤
+### Step 0-N: <动作，每步可执行，带 bash/代码示例>
+
+## 输出模板（必需）
+<markdown 模板>
+
+## 核心原则
+<5 条左右，每条有 why>
+
+## 反模式
+<5-7 条具体误用>
+```
+
+> **骨架风格参考**：读一个已有的 skill（如 `trellis-analyze-task` / `trellis-check-all`）作风格锚点，保持项目内一致。
+
+### Step 4: Frontmatter 规则（skill 形态必需）
+
+**skill 版 frontmatter**：
+
+```yaml
+---
+name: trellis-<name>
+description: "<what> <when> <exclusion>"
+---
+```
+
+`description` 写法取决于**触发策略**：
+
+| 策略 | 长度 | 写法 |
+|------|------|------|
+| **Auto-routing**（常用） | 80–300 字 | 三段式：What（动词开头）+ When（中英触发词）+ Exclusion（"For X, use Y instead"）。Claude 按此匹配用户意图自动加载 |
+| **Manual-only**（偶尔用的管理工具） | 15–20 tokens | 单句动作 + 产出物。只靠用户 `/trellis-<X>` 显式触发，description 不作路由依据，节省每次对话的 skill 列表 token |
+
+**选哪种**：
+- 选 **Auto-routing** 当 skill 需要在对话中被自然语触发（如 `trellis-analyze-task`、`trellis-check-all`）
+- 选 **Manual-only** 当 skill 用法明确、频率低、不希望占用每次对话 skill 列表 token（如 `trellis-migrate-skill` / `trellis-create-command` 自身）
+
+**agents 版 frontmatter**：正文 + frontmatter 与 skill 版完全一致（包括 `name: trellis-<name>`），只是落在 `.agents/skills/trellis-<name>/` 目录。
+
+```yaml
+---
+name: trellis-<name>
+description: "<与 skill 版一致>"
+---
+```
+
+**command 版**：无 frontmatter，纯 markdown。
+
+### Step 5: 写入副本
+
+**不变量（必须遵守）**：每个 trellis 入口都成对存在 —— `.claude/<commands 或 skills>/...` 主副本 + `.agents/skills/trellis-<name>/SKILL.md` 镜像副本。漏写任一份会破坏 skill-garden install.sh 的对称分发。scope 含 skill-garden 时，这对副本也要在 `<skill-garden>/.trellis/0.5/` 下各写一份（共 4 份）。
+
+按形态决定落盘位置：
+
+**形态 = skill**（2 份 / scope 为 skill-garden 时 4 份）：
+
+| 位置 | frontmatter name |
+|------|------------------|
+| `<target>/.claude/skills/trellis-<name>/SKILL.md` | `trellis-<name>`（主副本） |
+| `<target>/.agents/skills/trellis-<name>/SKILL.md` | `trellis-<name>`（镜像，body + frontmatter 完全同主副本） |
+| `<skill-garden>/.trellis/0.5/.claude/skills/trellis-<name>/SKILL.md` | `trellis-<name>` |
+| `<skill-garden>/.trellis/0.5/.agents/skills/trellis-<name>/SKILL.md` | `trellis-<name>` |
+
+**形态 = command**（2 份 / scope 为 skill-garden 时 4 份）：
+
+| 位置 | 格式 |
+|------|------|
+| `<target>/.claude/commands/trellis/<name>.md` | 无 frontmatter（主副本） |
+| `<target>/.agents/skills/trellis-<name>/SKILL.md` | 带 frontmatter，`name: trellis-<name>`（镜像） |
+| `<skill-garden>/.trellis/0.5/.claude/commands/trellis/<name>.md` | 无 frontmatter |
+| `<skill-garden>/.trellis/0.5/.agents/skills/trellis-<name>/SKILL.md` | 带 frontmatter |
+
+**同步技巧**：写完主版（`.claude/skills/trellis-<X>/SKILL.md` 或 `.claude/commands/trellis/<X>.md`）后，用 `cp + sed` 派生其他副本：
+
+```bash
+# 主副本写完后，4 份副本内容完全一致，直接 cp 即可
+cp <target>/.claude/skills/trellis-<X>/SKILL.md <target>/.agents/skills/trellis-<X>/SKILL.md
+
+# 对 skill-garden 同步（scope 为 skill-garden 时）
+cp -r <target>/.claude/skills/trellis-<X> <skill-garden>/.trellis/0.5/.claude/skills/
+cp -r <target>/.agents/skills/trellis-<X> <skill-garden>/.trellis/0.5/.agents/skills/
+```
+
+### Step 6: 更新 skill-garden README（scope = skill-garden 时）
+
+必改：
+- "全部技能" 表追加一行（名称 / 说明 / 形态）
+- 如为高频工具：考虑"推荐命令"表
+
+可选：
+- 如引入新形态约定或命名前缀：更新"新增 Trellis 技能"指引
+
+### Step 7: 验证
+
+| 检查项 | 方法 |
+|-------|------|
+| 新 skill 出现在 Claude skill list | 读 `<available-skills>` 区，确认 `trellis-<X>` 存在且 description 完整 |
+| 新 command 出现在 slash 列表 | 下拉 `/trellis:` 能看到 `<name>` |
+| scope=skill-garden：install 端到端 | `rm -rf /tmp/sg-test && mkdir -p /tmp/sg-test/.trellis && echo "0.5.0-beta.8" > /tmp/sg-test/.trellis/.version && bash <skill-garden>/scripts/install.sh /tmp/sg-test <X>` |
+| 4 份副本内容一致 | `wc -l` 行数一致；关键段落 `diff` 确认 |
+
+### Step 8: 输出确认
+
+```markdown
+✓ 已创建 trellis 入口：<name>
+
+形态：<command | skill>
+范围：<本项目 | 本项目 + skill-garden>
+
+副本：
+  • <target>/.claude/<path>
+  • <target>/.agents/skills/trellis-<X>/SKILL.md
+  <• <skill-garden> 同步位置 × 2>
+
+触发方式：
+  • 自然语：<触发词例子>
+  • 显式：<`/trellis:<X>` 或 `/trellis-<X>`>
+
+下一步建议：
+  • 在当前对话试一次触发，观察 Claude 是否正确路由
+  • 触发失败时调整 description（精准化 when/exclusion）
+  • 内容有遗漏时补充 Step 或 checklist
+```
+
+---
+
+## 命名约定
+
+| 类型 | 前缀 | 示例 |
+|------|------|------|
+| 会话生命周期 | — | `continue` / `finish-work` |
+| Pre-development | `before-` | `before-dev` |
+| Check | `check-` | `check-all` |
+| Verify | `verify-` | `verify-prd` |
+| Create / generate | `create-` | `create-prd` / `create-command` |
+| Analyze | `analyze-` | `analyze-task` |
+| Sync / update | `sync-` / `update-` | `sync-prd` / `update-spec` |
+| 动作类 | 动词开头 | `push` / `draw-uml` |
+
+### 命名反模式
+
+- ❌ 不用 kebab-case（不要 `reviewPr` / `review_pr`）
+- ❌ 名字过于笼统（`tool` / `helper` / `util`）
+- ❌ 与现有命令冲突（先 `ls .claude/commands/trellis` 和 `.claude/skills/` 确认）
+- ❌ skill 写文件时漏 `trellis-` 前缀（影响自动路由分组）
+
+---
+
+## 内容写作约束
+
+- skill body 默认 < 300 行；超过说明该拆分或融合
+- 每个 Step 要有**具体可执行动作**（读文件、grep、写文件），避免 "Analyze the requirements" 这种模糊词
+- 输出格式必须用 markdown 模板明示
+- 反模式清单必写（帮 Claude 避免常见误用）
+- 中文注释 + 英文 description（description 中的触发词可中英混合）
+- 引用文件路径用反引号 `.claude/...`，不写裸路径
+
+---
+
+## 反模式（避免）
+
+- ❌ 写 `.cursor/commands/`（已废弃，统一 `.claude/commands/`）
+- ❌ 同时创建 command 和 skill 同名入口（触发歧义，不知选哪个）
+- ❌ 只写 `.claude/...`，漏了 `.agents/skills/trellis-<X>/`（skill-garden install 会不对称）
+- ❌ 选 Auto-routing 策略但 description 过短（< 80 字），Claude 路由不稳；Manual-only 策略无此要求
+- ❌ description 用名词开头（"A skill for..."）而不是动词开头（"Analyzes..." / "Migrate..." / "Create..."）
+- ❌ 不询问 scope 直接写 skill-garden（需要用户显式确认 skill-garden 路径）
+- ❌ 不参考已有 skill 就凭空生成，导致风格不一致
+- ❌ 写完不验证（description 语法错或 frontmatter 缩进错，Claude 静默忽略）

package/enhancements/0.5/.agents/skills/trellis-create-prd/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: trellis-create-prd
+description: "Generate prd.md + task.json by faithfully extracting one requirement from a source requirements document."
+---
+# Create PRD — 基于原始需求文档
+
+从原始需求文档中提取指定需求的完整内容，结构化为 `prd.md`。**正文必须有据可依，禁止自行发挥**；仅允许在「本任务 TL;DR」与「本任务范围」两块做结论性提炼（且必须能在原文找到依据）。
+
+---
+
+## 核心原则
+
+1. **原文优先** — 「来源需求原文」「Requirements 索引」「Acceptance Criteria 索引」三节必须引用或指向原始文档原文，不得改写语义
+2. **文案原封不动** — 原始文档中出现的用户可见文案（按钮文字、提示语、Toast、弹窗内容、表头、placeholder 等）必须**逐字引用**，禁止改写、缩略或意译。一个字的差异都会导致前端实现偏差
+3. **标注出处** — 每条需求/AC 标注来源位置（文档行号、章节编号或页码）
+4. **允许提炼的两个例外** — 「本任务 TL;DR」「本任务范围」允许做结论性总结，但：
+   - 每条结论必须能在原文或上下文（commit、既有任务档案、用户确认）里找到依据
+   - 只做"本次任务 vs 全功能"的分界，不引入原文没有的新需求
+5. **禁止发挥** — 不得添加原始文档中没有的需求、验收标准或业务规则
+6. **完整提取** — 该需求单元下的所有内容全部提取，不跳不漏
+7. **去重** — 同一条款在 PRD 中只应"完整出现一次"（即「来源需求原文」一节），Requirements / AC / 关联需求等其他节均以**指针**形式引用，不得复述内容
+8. **散射追踪是参考，不是清单** — 散射追踪的产物仅用于"知会关联"，不得被误读为工作范围；必须明确标注「本任务是否实现」列
+
+---
+
+## 输入
+
+用户需提供：
+- **需要提取的需求**（编号、名称或功能描述均可）
+- **原始需求文档路径**（如未指定，在 `doc/` 下查找）
+
+---
+
+## 执行步骤
+
+### Step 1: 理解文档结构
+
+读取原始需求文档，识别其组织方式：
+
+- 需求的划分单元是什么？（REQ 编号 / 章节 / 功能模块 / 用户故事卡片 / 其他）
+- 每个需求单元包含哪些子结构？（如：用户故事、业务规则、字段说明、验收标准）
+- 有无编号体系？（如 BR-01、AC-01，或无编号纯文本）
+
+> **不要假设文档有特定格式**，先读再判断。
+
+### Step 2: 定位并完整提取
+
+在文档中定位用户指定的需求，**完整读取**该需求下的所有内容，直到下一个同级需求开始。
+
+提取时注意：
+- 保留原始的编号、层级、表格结构
+- 不要跳过任何子节（即使看起来不重要）
+- 记录提取的起止位置（行号或章节号）
+
+### Step 3: 识别变更性质（关键一步）
+
+判断本次任务属于哪一类，并记录依据（来源文档的哪一行/章节明示）：
+
+| 类别 | 典型信号 |
+|------|---------|
+| **新增** | 需求单元是全新功能，无历史版本 |
+| **局部变更** | 原文有 "vX.Y 变更 / 新增" 标记、"本需求为既有需求的局部变更"字样、或明确的对比描述（原 vs 新）|
+| **修复** | 原文描述"修复/纠正"某行为 |
+| **重构** | 改实现不改行为 |
+
+> **局部变更是最容易被写偏的情况**：原文的 User Story 通常描述的是**整个功能**（历史 + 变更），不是本任务的变更点。Step 4 的 TL;DR 必须只写变更点，不要写全功能。
+
+### Step 4: 散射追踪
+
+提取目标需求中涉及的**关键实体**（字段名、功能点、业务概念），在全文中搜索这些关键词，检查是否在其他需求单元中也有相关内容：
+
+- 同一字段在不同页面/模块的展示、编辑、导出规则
+- 同一业务规则在不同入口的复用
+- 跨需求的依赖或约束
+
+**对每一条散射发现，必须立刻判定**：
+- ✅ 属于本任务实现？
+- ❌ 不属于本任务？（由谁实现 / 已在哪里落地 / N/A）
+
+将发现记录到 PRD 的「关联需求」表，表头必须含「本任务实现」列。
+
+### Step 5: 生成 PRD
+
+PRD 的结构**按下列顺序**组织（顺序有意为之——让读者打开 PRD 的前 30 行就能回答"做什么、不做什么、为什么"）：
+
+```markdown
+# <需求标识> <需求名称>
+
+> 来源：<文档名>，<位置范围>
+> 变更性质：新增 / 局部变更 / 修复 / 重构
+> 优先级：P?
+
+## 本任务（TL;DR）
+- **做什么**：<一句话，≤30 字，只写本任务要改动的行为>
+- **为什么**：<一句话，变更动机 / 触发来源>
+- **变更性质**：新增 / 局部变更 / 修复 / 重构
+
+## 本任务范围（Scope）
+- ✅ **本任务实现**：
+  - <条目 1，一句一条>
+  - <条目 2>
+- ❌ **相关但不在本任务范围**：
+  - <条目> — 归属：<任务名 / commit / 独立任务 / N/A 原因>
+
+## 来源需求原文
+<按原始文档的子结构组织，使用 blockquote 或分级标题忠实摘录>
+<保留原始编号和层级；用户可见文案逐字引用>
+
+## Requirements（索引）
+- [<编号>] <一句话摘要> — 详见「来源需求原文」§<编号> / <原文位置>
+- ...
+
+## Acceptance Criteria（索引）
+- [ ] [<编号>] <一句话摘要> — 详见「来源需求原文」§<编号> / <原文位置>
+- ...
+
+## 关联需求（⚠️ 上下文参考，非本任务范围）
+| 需求单元 | 关联内容 | 本任务实现 | 归属 / 位置 |
+|---------|---------|-----------|-------------|
+| REQ-xxx | ... | ❌ | 已实现于 commit xxx |
+
+## Out of Scope
+- <原始文档中明确排除的内容>
+
+## Technical Notes
+- 原始文档路径、提取范围、提取时间
+- 关键文件路径（用于 task.json `relatedFiles`）
+- 其他对实现者有用的上下文
+```
+
+> **关键差异（与旧版对比）**：
+> - 「本任务 TL;DR」和「本任务范围」放在最前面，读者不必翻到文末去找"本任务到底做什么"
+> - 「Requirements」「Acceptance Criteria」改为**索引式**，只写编号 + 一句话摘要 + 原文指针，**不复述原文内容**（原文已经在「来源需求原文」一节完整出现过一次）
+> - 「关联需求」表头增加「本任务实现」列，小节标题明确写⚠️提示
+> - 散射追踪成果归入「关联需求」，不得混入「Requirements」或「Scope ✅」
+
+### Step 6: 创建 task.json
+
+PRD 写入后，调用框架脚本创建 `task.json`，使任务目录完整可用：
+
+```bash
+python3 .trellis/scripts/task.py create "<PRD标题>" \
+  --slug "<任务目录名去掉日期前缀>" \
+  --priority P2 \
+  --description "<TL;DR「做什么」一句话>"
+```
+
+> **注意**：
+> - 如果任务目录已由用户手动创建（已有 `prd.md`），脚本会检测到目录已存在并在其中写入 `task.json`
+> - `--slug` 必须与任务目录名的 slug 部分一致，确保 `task.json` 落在正确目录
+> - `--description` 直接复用 TL;DR 的「做什么」字段，保证 task.json 和 PRD 首屏一致
+> - 根据需求性质设置 `--priority`：紧急修复 P0/P1，常规需求 P2，小改动 P3
+> - 创建完成后，根据 PRD 中的分析补充 `task.json` 中的字段：
+>   - `dev_type`：`frontend` / `backend` / `fullstack`
+>   - `relatedFiles`：PRD Technical Notes 中识别的关键文件路径
+
+### Step 7: 自检
+
+| 检查项 | 方法 |
+|--------|------|
+| **首屏可读性** | 只看 PRD 前 30 行，能否回答"做什么 / 不做什么 / 为什么"三问？不能则 TL;DR 或 Scope 写得不够清楚 |
+| **去重** | 同一条款（如 BR-06、AC-13）是否只在「来源需求原文」一节完整出现？Requirements / AC / 关联需求是否都只有指针不复述？ |
+| **Scope 分离** | 散射追踪发现的"相关但不做"条款是否**全部**落在「❌ 相关但不在本任务范围」或「关联需求」表里？有没有一条漏到 Scope ✅ 里？ |
+| **关联需求列完整** | 「关联需求」表每一行的「本任务实现」列是否都填写（✅/❌/N/A）？ |
+| **原文完整性** | 原始文档中该需求的所有子节是否都出现在「来源需求原文」中 |
+| **AC 可追溯** | 每条 AC 索引是否都标注了来源位置 |
+| **无自行发挥** | Requirements 索引中是否有任何一条找不到原文依据 |
+| **文案逐字一致** | PRD 中的 UI 文案（按钮、提示语、Toast、弹窗、表头、placeholder）是否与原始文档**完全一致**，无改写/缩略/意译 |
+| **散射完整** | 至少对 2-3 个关键实体做过全文搜索 |
+| **变更性质匹配** | 若判为"局部变更"，TL;DR 的「做什么」是否只描述变更点，而非整个功能的 User Story？ |
+
+---
+
+## 反模式
+
+- ❌ 用自己的话改写需求（「来源需求原文」节应引用原文；Requirements/AC 索引应指向原文而非复述）
+- ❌ 需求条目没有标注来源位置
+- ❌ 添加原始文档中不存在的业务规则或验收标准
+- ❌ 跳过某些子节不提取（即使觉得不重要）
+- ❌ 不做散射追踪
+- ❌ 假设文档有特定格式（每份文档先读结构再处理）
+- ❌ **TL;DR 写成整个功能的 User Story**（局部变更时必须只写变更点）
+- ❌ **Requirements / AC 小节复述原文内容**（应该是索引指针）
+- ❌ **散射追踪结果混入 Scope ✅ 或 Requirements**（散射是上下文，不是工作清单）
+- ❌ **「关联需求」表遗漏「本任务实现」列**（否则读者无法区分做与不做）
+- ❌ **PRD 末尾补一个「任务范围收敛（必读）」块来救场**（说明 Scope 在首屏没写清楚——回头去修 Scope，不要靠末尾补丁）
+
+---
+
+## 与其他入口的区别
+
+| 入口 | 形态 | 职责 | 时机 |
+|------|------|------|------|
+| `trellis-plan-version` | skill | 版本级需求扫描 + 覆盖度确认 | 版本规划阶段 |
+| `trellis-create-prd` | skill（本技能） | 单个需求的 PRD + task.json 生成 | 任务开发前 |
+| `trellis-verify-prd` | skill | 校验已有 PRD 的准确性 + 覆盖度 | PRD 生成后 |
+| `trellis-brainstorm` | skill | 对话式需求发现（无原始文档时） | 需求模糊时 |

package/enhancements/0.5/.agents/skills/trellis-draw-uml/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: trellis-draw-uml
+description: "Draft UML activity diagrams from fuzzy business descriptions, when user needs to structure a workflow before coding: ask clarifying questions about roles/branches/exceptions, emit Mermaid source, render to PNG, read image back into the conversation. Triggers: 「画活动图」「梳理流程」「业务流程图」「draw UML」. Not for prose-level PRD discovery (use trellis-brainstorm) or PRD-vs-source audit (use trellis-verify-prd)."
+---
+# PM 活动图梳理
+
+以**资深互联网产品经理 + 业务架构师**的身份，协助我用 **UML 活动图**厘清业务逻辑；信息不充分时**主动反问**，不得臆测。每次产出图后**必须渲染 PNG 并读图展示**，不要只扔代码。
+
+## 角色设定
+
+- **身份**：资深互联网产品经理 & 业务架构师
+- **职责**：把用户零散的想法 / 口头描述，结构化为清晰的业务流程
+- **工具**：UML 活动图（Activity Diagram），必要时辅以泳道、判定节点、并行分支
+- **原则**：需求不清先问，再画；**严禁虚构角色、系统或分支**
+
+## 交互步骤
+
+### 1. 接收输入
+读取用户提供的需求 / 场景描述（可能是一句话、一段聊天记录或一份粗略文档）。
+
+### 2. 澄清式反问（必要时）
+当下列任一要素缺失时，**先提问再动笔**：
+- **主体角色**：谁发起？谁审批？谁执行？（用户 / 系统 / 第三方）
+- **触发条件**：什么场景 / 事件进入此流程？
+- **判定分支**：条件是什么？各分支的后续动作？
+- **异常路径**：失败 / 超时 / 拒绝 如何处理？
+- **终止状态**：流程成功 / 失败 各以什么状态结束？
+
+一次最多提 3～5 个最关键的问题，避免"问题轰炸"。
+
+### 3. 输出活动图（Mermaid 代码）
+
+使用 **Mermaid `flowchart` / `stateDiagram` 语法**（或 PlantUML `@startuml` 活动图语法），直接可渲染。
+
+**Mermaid 示例**：
+````markdown
+```mermaid
+flowchart TD
+    Start([开始]) --> A[用户提交申请]
+    A --> B{金额 > 1万?}
+    B -- 是 --> C[主管审批]
+    B -- 否 --> D[自动通过]
+    C --> E{审批通过?}
+    E -- 是 --> D
+    E -- 否 --> F[通知驳回]
+    D --> End([结束])
+    F --> End
+```
+````
+
+### 4. 渲染为 PNG（每次必做）
+
+Mermaid 代码必须落盘并渲染为图片，否则用户可能看不到图。
+
+**4.1 确定产物路径**
+
+- 从流程名派生 `slug`（英文小写 + 连字符），例：`附件打包下载` → `attachment-zip-flow`
+  - 无法自动派生时，向用户确认 slug
+- 输出目录：当前工作目录下 `doc/uml/`（不存在则 `mkdir -p`）
+- 产物：`doc/uml/<slug>.mmd`（源码）+ `doc/uml/<slug>.png`（图）
+- 同名已存在：直接覆盖（Mermaid 源码是真源，无需保留历史版本）
+
+**4.2 写源码 + 在线渲染**
+
+用 `mermaid.ink` 渲染（零依赖、无需 key），标准 python3 即可：
+
+```bash
+SLUG="<slug>"
+mkdir -p doc/uml
+cat > "doc/uml/${SLUG}.mmd" <<'EOF'
+<把 Mermaid 源码粘到这里，结束行是独立的 EOF>
+EOF
+
+python3 - "$SLUG" <<'PY'
+import base64, json, pathlib, sys, urllib.request
+slug = sys.argv[1]
+src = pathlib.Path(f'doc/uml/{slug}.mmd').read_text()
+payload = {'code': src, 'mermaid': {'theme': 'default'}}
+b64 = base64.urlsafe_b64encode(json.dumps(payload).encode('utf-8')).decode('ascii').rstrip('=')
+url = f'https://mermaid.ink/img/{b64}?type=png&bgColor=FFFFFF'
+req = urllib.request.Request(url, headers={'User-Agent': 'curl/8'})
+with urllib.request.urlopen(req, timeout=30) as resp:
+    data = resp.read()
+out = pathlib.Path(f'doc/uml/{slug}.png')
+out.write_bytes(data)
+print(f'saved: {out} ({len(data)} bytes)')
+PY
+```
+
+**4.3 读图展示**
+
+用 Read 工具读取 `doc/uml/<slug>.png`，让图片直接出现在对话里（Claude Code 多模态支持）。
+
+**4.4 渲染失败降级**
+
+网络不通 / `mermaid.ink` 503 / Mermaid 语法报错时：
+- 保留 `.mmd` 源码文件（已落盘）
+- 明确告诉用户失败原因（HTTP 码或异常）
+- 给两条本地兜底：
+  1. `npx -p @mermaid-js/mermaid-cli mmdc -i doc/uml/<slug>.mmd -o doc/uml/<slug>.png`
+  2. 贴到 <https://mermaid.live> 手动导出
+- **不要假装成功**，也不要跳过这一步直接进入 Step 5
+
+### 5. 附随说明
+
+图下方补充：
+- **产物路径**：`doc/uml/<slug>.png` + `doc/uml/<slug>.mmd`
+- **角色清单**：列出图中涉及的所有角色 / 系统
+- **关键判定**：每个菱形分支的业务含义
+- **待确认项**：还存在哪些尚未澄清的点（如果有）
+
+### 6. 迭代优化
+
+用户反馈后，**只改动被指出的部分**，保持其余节点不变；大改前先口头确认修改范围。改完后**重新走 Step 4**（覆写 `.mmd` → 重新渲染 → 重新读图），保证图和代码同步。
+
+## 输出模板
+
+```markdown
+## 业务流程：<流程名>
+
+### 角色
+- <角色 A>
+- <系统 B>
+
+### 活动图
+<Mermaid 代码块>
+
+（此处应紧跟 Read 工具读出的 PNG 图像）
+
+### 产物
+- 图：`doc/uml/<slug>.png`
+- 源码：`doc/uml/<slug>.mmd`
+
+### 关键判定
+- **<判定节点>**：<业务规则说明>
+
+### 待确认
+- [ ] <悬而未决的问题>
+```
+
+## 禁止事项
+
+- [X] 跳过澄清直接画图（除非需求已极其明确）
+- [X] 虚构角色 / 系统 / 字段
+- [X] 一次性把所有分支画出来却不标注业务含义
+- [X] 用纯文字描述替代活动图（用户要的是"图"）
+- [X] 只贴 Mermaid 代码不渲染 PNG（除非 Step 4 明确失败并告知用户）
+- [X] 渲染失败静默跳过，不告知用户