flower-trellis 0.1.0

package/enhancements/0.6/.claude/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 task-spec audit (use trellis-verify-task)."
+---
+# 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] 渲染失败静默跳过，不告知用户

package/enhancements/0.6/.claude/skills/trellis-extract-prd/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: trellis-extract-prd
+description: "Extract a single requirement faithfully from a source requirements document into structured prd.md + task.json; forbid embellishment, preserve UI copy verbatim, annotate source positions. Triggers: 「提取需求」「从需求文档抽 PRD」「严格提取 PRD」「extract PRD」. Not for conversational PRD generation (trellis-brainstorm) or task-spec coverage audit (trellis-verify-task)."
+---
+# Extract 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-brainstorm` | skill（上游） | 对话式需求发现（**无原始文档时**） | 需求模糊时 |
+| `trellis-extract-prd` | skill（本技能） | 基于原始文档**严格提取**单个需求的 PRD + task.json | 任务开发前、有正式需求文档时 |
+| `trellis-verify-task` | skill | 校验任务三件套（prd / design / implement）准确性 + 覆盖度 + 跨层一致性 | PRD / Design / Implement 生成后 |

package/enhancements/0.6/.claude/skills/trellis-plan-version/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: trellis-plan-version
+description: "Generate a version development plan from a source requirements doc: requirements list, effort estimate, and team assignment."
+---
+# 版本开发计划 — 从需求文档到任务拆分
+
+从原始需求文档出发，生成版本开发计划（需求清单 + 工时评估 + 人员分工），内置覆盖度校验确保不遗漏需求。
+
+---
+
+## 核心原则
+
+1. **需求文档是唯一真相** — 需求清单必须从文档全文提取，不能只看目录/总表
+2. **先扫后拆** — 先完成覆盖度扫描，确认无遗漏后再做工时评估和分工
+3. **可追溯** — 每个任务可追溯到原始文档的具体位置（行号/章节）
+
+---
+
+## 输入
+
+用户需提供：
+- **原始需求文档路径**
+- **版本号或迭代标识**
+- **开发团队信息**（人数、角色分工模式）
+
+---
+
+## 执行步骤
+
+### Step 1: 理解文档结构 + 全文扫描
+
+#### 1.0 先读后扫
+
+读取文档，识别其组织方式：
+- 需求的划分单元是什么？（编号体系 / 章节 / 功能模块 / 用户故事）
+- 有无需求总表或变更日志？
+- 版本变更如何标记？（显式标记 / 总表版本列 / 变更日志章节 / 无标记）
+
+> **不要假设文档有特定格式**，先读再判断。
+
+#### 1.1 多策略识别本版本变更
+
+根据文档实际结构，组合使用以下策略：
+
+| 策略 | 方法 |
+|------|------|
+| **标记扫描** | grep 搜索版本相关标记，**包括段落中间嵌入的** |
+| **需求总表** | 读取需求列表中版本相关列，提取本版本的条目 |
+| **全文通读** | 逐章扫描「新增」「变更」「调整」等动作词 |
+
+#### 1.2 归组到需求单元
+
+每个变更点定位到所属的需求单元，记录：
+- 需求单元标识（编号、名称或章节）
+- 变更内容摘要
+- 在文档中的位置
+- 变更类型：整体新增 / 局部变更 / 字段级嵌入
+
+> **[!] 关键：必须识别出「字段级嵌入变更」。**
+> 有些需求单元整体是旧版本的，但内部某个字段/段落属于新版本变更。
+> 仅看需求单元标题会遗漏这类变更。
+
+#### 1.3 识别散射型变更
+
+检查是否有同一功能点散布在多个需求单元中：
+- 同一字段在不同页面的展示/编辑/导出
+- 同一业务规则在不同入口的复用
+- 标记每组散射变更，确保后续分工时归同一人
+
+### Step 2: 输出需求清单 — 覆盖度确认
+
+输出完整的需求清单，请用户确认无遗漏：
+
+```markdown
+## <版本> 需求清单
+
+### 扫描统计
+- 需求总表中本版本条目: X 个
+- 全文扫描发现的变更: Y 个
+- 去重后独立需求单元: Z 个
+
+### 需求列表
+
+| # | 需求单元 | 功能点 | 变更类型 | 变更摘要 | 文档位置 |
+|---|---------|--------|---------|---------|---------|
+
+### 散射型变更（同一功能点跨多个需求单元）
+
+| 功能点 | 涉及的需求单元 | 建议处理 |
+|--------|--------------|---------|
+
+### 需求总表 vs 全文扫描差异
+
+| 来源 | 仅在总表 | 仅在全文 | 两者都有 |
+|------|---------|---------|---------|
+
+> 仅在全文中的变更 = 总表未收录的嵌入式变更，最易遗漏。
+```
+
+**等待用户确认后再继续。**
+
+### Step 3: 工时评估
+
+基于确认后的需求清单，评估每个需求的工时。
+
+输出表格的列结构**根据项目实际的角色分工来定**（如前端/后端/全栈/测试等），不要预设。
+
+评估原则：
+- 如有 AI 编程辅助，标注基准（AI 辅助 vs 纯人工）
+- 复用关系明确标注
+- 优先级以需求文档为准
+
+### Step 4: 人员分工
+
+按模块边界分工，遵循：
+- 复用链归同一人
+- 散射型变更归同一人
+- 尽量无交集
+
+输出分工表和排期建议。
+
+### Step 5: 生成产物文件
+
+在 `doc/` 目录下生成：
+
+```
+doc/
+├── <版本>-需求清单.md            # Step 2 的完整输出（含覆盖度校验）
+├── <版本>-开发计划-工时评估.md    # Step 3 + Step 4
+```
+
+---
+
+## 反模式
+
+- ❌ 只从需求总表提取需求（会漏掉嵌入式变更）
+- ❌ 跳过覆盖度确认直接做工时评估
+- ❌ 散射型变更分给不同的人
+- ❌ 假设文档有特定格式或特定的角色分工模式
+- ❌ 当多个来源的优先级冲突时不明确说明以哪个为准