flower-trellis 0.1.0

package/enhancements/old/.claude/commands/trellis/create-prd.md

@@ -0,0 +1,150 @@
+# Create PRD — 基于原始需求文档
+
+从原始需求文档中提取指定需求的完整内容，结构化为 `prd.md`。**所有内容必须有据可依，禁止自行发挥。**
+
+---
+
+## 核心原则
+
+1. **原文优先** — Requirements 和 AC 必须引用原始文档原文，不得改写语义
+2. **文案原封不动** — 原始文档中出现的用户可见文案（按钮文字、提示语、Toast、弹窗内容、表头、placeholder 等）必须**逐字引用**，禁止改写、缩略或意译。这些文案是用户直接看到的内容，一个字的差异都会导致前端实现偏差
+3. **标注出处** — 每条需求标注来源位置（文档行号、章节编号或页码）
+4. **禁止发挥** — 不得添加原始文档中没有的需求、验收标准或业务规则
+5. **完整提取** — 该需求单元下的所有内容全部提取，不跳不漏
+6. **散射追踪** — 检查同一功能点是否在文档其他位置也有提及，一并收录
+
+---
+
+## 输入
+
+用户需提供：
+- **需要提取的需求**（编号、名称或功能描述均可）
+- **原始需求文档路径**（如未指定，在 `doc/` 下查找）
+
+---
+
+## 执行步骤
+
+### Step 1: 理解文档结构
+
+读取原始需求文档，识别其组织方式：
+
+- 需求的划分单元是什么？（REQ 编号 / 章节 / 功能模块 / 用户故事卡片 / 其他）
+- 每个需求单元包含哪些子结构？（如：用户故事、业务规则、字段说明、验收标准）
+- 有无编号体系？（如 BR-01、AC-01，或无编号纯文本）
+
+> **不要假设文档有特定格式**，先读再判断。
+
+### Step 2: 定位并完整提取
+
+在文档中定位用户指定的需求，**完整读取**该需求下的所有内容，直到下一个同级需求开始。
+
+提取时注意：
+- 保留原始的编号、层级、表格结构
+- 不要跳过任何子节（即使看起来不重要）
+- 记录提取的起止位置（行号或章节号）
+
+### Step 3: 散射追踪
+
+提取目标需求中涉及的**关键实体**（字段名、功能点、业务概念），在全文中搜索这些关键词，检查是否在其他需求单元中也有相关内容：
+
+- 同一字段在不同页面/模块的展示、编辑、导出规则
+- 同一业务规则在不同入口的复用
+- 跨需求的依赖或约束
+
+将发现的关联记录到 PRD 的「关联需求」部分。
+
+### Step 4: 生成 PRD
+
+将提取的内容结构化为 `prd.md`，结构分两层：
+
+**第一层：来源原文（忠实摘录）**
+
+```markdown
+# <需求标识> <需求名称>
+
+> 来源：<文档名>，<位置范围>
+
+## Goal
+<直接引用原文中的目标/用户故事描述>
+
+## 来源需求原文
+<按原始文档的子结构组织，使用 blockquote 引用原文>
+<保留原始编号和层级>
+```
+
+**第二层：结构化提炼（每条标注来源）**
+
+```markdown
+## Requirements
+- <需求描述> — 来源：<原文位置>
+- ...
+
+## Acceptance Criteria
+- [ ] <原文中的验收标准> — 来源：<原文位置>
+- ...
+
+## 关联需求（散射追踪）
+| 需求单元 | 关联内容 | 位置 | 影响 |
+|---------|---------|------|------|
+
+## Out of Scope
+- <原始文档中明确排除的内容>
+
+## Technical Notes
+- 原始文档路径、提取范围、提取时间
+```
+
+> Requirements 中的每一条都必须指向原文中的具体位置。
+> 如果原始文档没有显式的验收标准，从业务规则中提炼，但必须标注「提炼自：<原文位置>」。
+
+### Step 5: 创建 task.json
+
+PRD 写入后，调用框架脚本创建 `task.json`，使任务目录完整可用：
+
+```bash
+python3 .trellis/scripts/task.py create "<PRD标题>" \
+  --slug "<任务目录名去掉日期前缀>" \
+  --priority P2 \
+  --description "<Goal 的一句话摘要>"
+```
+
+> **注意**：
+> - 如果任务目录已由用户手动创建（已有 `prd.md`），脚本会检测到目录已存在并在其中写入 `task.json`
+> - `--slug` 必须与任务目录名的 slug 部分一致，确保 `task.json` 落在正确目录
+> - 根据需求性质设置 `--priority`：紧急修复 P0/P1，常规需求 P2，小改动 P3
+> - 创建完成后，根据 PRD 中的分析补充 `task.json` 中的字段：
+>   - `dev_type`：`frontend` / `backend` / `fullstack`
+>   - `relatedFiles`：PRD Technical Notes 中识别的关键文件路径
+
+### Step 6: 自检
+
+| 检查项 | 方法 |
+|--------|------|
+| 原文完整性 | 原始文档中该需求的所有子节是否都出现在「来源需求原文」中 |
+| AC 可追溯 | 每条 AC 是否都标注了来源位置 |
+| 无自行发挥 | Requirements 中是否有任何一条找不到原文依据 |
+| 文案逐字一致 | PRD 中的 UI 文案（按钮、提示语、Toast、弹窗、表头、placeholder）是否与原始文档**完全一致**，无改写/缩略/意译 |
+| 散射完整 | 至少对 2-3 个关键实体做过全文搜索 |
+
+---
+
+## 反模式
+
+- ❌ 用自己的话改写需求（应引用原文）
+- ❌ 需求条目没有标注来源位置
+- ❌ 添加原始文档中不存在的业务规则或验收标准
+- ❌ 跳过某些子节不提取（即使觉得不重要）
+- ❌ 不做散射追踪
+- ❌ 假设文档有特定格式（每份文档先读结构再处理）
+
+---
+
+## 与其他命令的关系
+
+| 命令 | 职责 | 时机 |
+|------|------|------|
+| `/trellis:plan-version` | 版本级需求扫描 + 覆盖度确认 | 版本规划阶段 |
+| `/trellis:create-prd` | 单个需求的 PRD + task.json 生成（本命令） | 任务开发前 |
+| `/trellis:check-prd` | 校验已有 PRD 的准确性 + 覆盖度 | PRD 生成后 |
+| `/trellis:brainstorm` | 对话式需求发现（无原始文档时） | 需求模糊时 |

package/enhancements/old/.claude/commands/trellis/draw-uml.md

@@ -0,0 +1,144 @@
+# 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/old/.claude/commands/trellis/plan-version.md

@@ -0,0 +1,136 @@
+# 版本开发计划 — 从需求文档到任务拆分
+
+从原始需求文档出发，生成版本开发计划（需求清单 + 工时评估 + 人员分工），内置覆盖度校验确保不遗漏需求。
+
+---
+
+## 核心原则
+
+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
+```
+
+---
+
+## 反模式
+
+- ❌ 只从需求总表提取需求（会漏掉嵌入式变更）
+- ❌ 跳过覆盖度确认直接做工时评估
+- ❌ 散射型变更分给不同的人
+- ❌ 假设文档有特定格式或特定的角色分工模式
+- ❌ 当多个来源的优先级冲突时不明确说明以哪个为准

package/enhancements/old/.claude/commands/trellis/push.md

@@ -0,0 +1,187 @@
+# Push — 提交并推送（可选合并到目标分支）
+
+一键完成 commit → push → 可选 merge 到目标分支（通常是测试线）→ push 目标分支 → 切回。
+
+支持多仓库（frontend / backend），merge 目标分支记录在 `.trellis/config.yaml` 的 `packages.<name>.merge_target` 中。
+
+---
+
+## 配置
+
+目标分支存储在 `.trellis/config.yaml` 的 packages 配置中：
+
+```yaml
+packages:
+  frontend:
+    path: iqs-front-human
+    git: true
+    merge_target: test      # 首次 push 时询问后自动写入
+  backend:
+    path: iqs
+    git: true
+    merge_target: test
+```
+
+> 首次运行时如果 `merge_target` 不存在，会在 merge 步骤询问目标分支并回写到 `config.yaml`。
+> 如需修改，直接编辑 `config.yaml` 或使用 `/trellis:push --reconfigure`。
+
+---
+
+## 执行步骤
+
+### Step 0: 读取配置
+
+读取 `.trellis/config.yaml` 中的 `packages` 配置，识别所有 `git: true` 的仓库及其 `merge_target`（如果已配置）。
+
+### Step 1: 检测变更
+
+读取 `.trellis/config.yaml` 中的 `packages` 配置，对每个 git 仓库检测变更：
+
+```bash
+# 对每个 package
+cd <package_path>
+git status --short
+```
+
+列出有变更的仓库。如果所有仓库都没有变更，提示用户并终止。
+
+如果只有部分仓库有变更，只处理有变更的仓库。
+
+### Step 2: 逐仓库处理
+
+对每个有变更的仓库，依次执行以下操作：
+
+#### 2.1 展示变更摘要
+
+```bash
+cd <package_path>
+git diff --stat
+git diff --name-only
+```
+
+#### 2.2 暂存文件
+
+展示要暂存的文件列表，**获得用户确认后**再暂存。
+
+```bash
+git add <具体文件列表>
+```
+
+> **[!] 禁止使用 `git add -A` 或 `git add .`**
+> 必须明确列出文件，避免误提交敏感文件（.env、credentials 等）。
+
+#### 2.3 生成 commit message 并提交
+
+分析变更内容，生成符合项目风格的 commit message：
+- 读取最近 5 条 commit 参考风格
+- 类型前缀：`feat` / `fix` / `chore` / `refactor` 等
+- 简短描述变更内容
+- 使用中文描述
+
+```bash
+git commit -m "<type>(<scope>): <description>"
+```
+
+#### 2.4 Push 当前分支
+
+```bash
+git push origin <current_branch>
+```
+
+如果远程没有该分支，使用 `-u` 建立跟踪：
+
+```bash
+git push -u origin <current_branch>
+```
+
+#### 2.5 询问是否 Merge 到目标分支（可选）
+
+Push 完成后，检查该 package 是否已配置 `merge_target`：
+
+**已配置 `merge_target`**：
+
+```markdown
+<package> 已推送到 <current_branch>。是否合并到 <merge_target>？
+
+1. 是，合并到 <merge_target>
+2. 否，跳过
+```
+
+**未配置 `merge_target`（首次）**：
+
+```markdown
+<package> 已推送到 <current_branch>。是否需要合并到其他分支（如测试线）？
+
+1. 是，请输入目标分支名
+2. 否，跳过
+```
+
+如果用户输入了目标分支名，**将其回写到 `.trellis/config.yaml`** 对应 package 的 `merge_target` 字段，下次自动使用。
+
+**如果用户选择合并**：
+
+```bash
+# 切换到目标分支并拉取最新
+git checkout <target_branch>
+git pull origin <target_branch>
+
+# 合并当前开发分支
+git merge <current_branch> --no-edit
+
+# Push 目标分支
+git push origin <target_branch>
+
+# 切回开发分支
+git checkout <current_branch>
+```
+
+> **[!] 如果 merge 出现冲突：**
+> 1. 立即停止，展示冲突文件列表
+> 2. 询问用户：手动解决 / 中止 merge
+> 3. **绝对不能** `git merge --abort` 后静默跳过
+
+**如果用户选择跳过**：直接进入下一个仓库或输出结果。
+
+### Step 3: 输出结果
+
+```markdown
+## Push 结果
+
+| 仓库 | 分支 | 目标 | commit | 状态 |
+|------|------|------|--------|------|
+| frontend | v1.3 | test | abc1234 feat(...): ... | ✅ 已合并 |
+| backend | v1.3 | test | def5678 fix(...): ... | ⏭️ 跳过合并 |
+
+所有变更已推送到目标分支。
+```
+
+---
+
+## 参数
+
+| 参数 | 说明 | 示例 |
+|------|------|------|
+| （无参数） | 自动检测所有有变更的仓库并处理 | `/trellis:push` |
+| `--only <package>` | 只处理指定仓库 | `/trellis:push --only frontend` |
+| `--reconfigure` | 重新配置目标分支 | `/trellis:push --reconfigure` |
+| `--target <branch>` | 临时指定目标分支（不修改配置） | `/trellis:push --target hotfix` |
+
+---
+
+## 安全机制
+
+1. **暂存确认** — 每个仓库暂存前展示文件列表，用户确认
+2. **commit message 确认** — 展示生成的 message，用户可修改
+3. **merge 冲突处理** — 冲突时暂停，不静默跳过
+4. **不碰主分支** — 如果目标分支是 `master` / `main`，额外警告确认
+5. **不使用 force push** — 始终使用普通 push
+
+---
+
+## 反模式（避免）
+
+- ❌ `git add -A`（可能误提交敏感文件）
+- ❌ merge 冲突后静默 abort（用户需要知道）
+- ❌ 未经确认直接 commit（必须让用户看到 message）
+- ❌ force push 到目标分支
+- ❌ 在目标分支上直接开发（只 merge，不在目标分支上改代码）