ironweave 1.0.0

package/skills/skill-creator/scripts/run_loop.py

@@ -0,0 +1,328 @@
+#!/usr/bin/env python3
+"""Run the eval + improve loop until all pass or max iterations reached.
+
+Combines run_eval.py and improve_description.py in a loop, tracking history
+and returning the best description found. Supports train/test split to prevent
+overfitting.
+"""
+
+import argparse
+import json
+import random
+import sys
+import tempfile
+import time
+import webbrowser
+from pathlib import Path
+
+from scripts.generate_report import generate_html
+from scripts.improve_description import improve_description
+from scripts.run_eval import find_project_root, run_eval
+from scripts.utils import parse_skill_md
+
+
+def split_eval_set(eval_set: list[dict], holdout: float, seed: int = 42) -> tuple[list[dict], list[dict]]:
+    """Split eval set into train and test sets, stratified by should_trigger."""
+    random.seed(seed)
+
+    # Separate by should_trigger
+    trigger = [e for e in eval_set if e["should_trigger"]]
+    no_trigger = [e for e in eval_set if not e["should_trigger"]]
+
+    # Shuffle each group
+    random.shuffle(trigger)
+    random.shuffle(no_trigger)
+
+    # Calculate split points
+    n_trigger_test = max(1, int(len(trigger) * holdout))
+    n_no_trigger_test = max(1, int(len(no_trigger) * holdout))
+
+    # Split
+    test_set = trigger[:n_trigger_test] + no_trigger[:n_no_trigger_test]
+    train_set = trigger[n_trigger_test:] + no_trigger[n_no_trigger_test:]
+
+    return train_set, test_set
+
+
+def run_loop(
+    eval_set: list[dict],
+    skill_path: Path,
+    description_override: str | None,
+    num_workers: int,
+    timeout: int,
+    max_iterations: int,
+    runs_per_query: int,
+    trigger_threshold: float,
+    holdout: float,
+    model: str,
+    verbose: bool,
+    live_report_path: Path | None = None,
+    log_dir: Path | None = None,
+) -> dict:
+    """Run the eval + improvement loop."""
+    project_root = find_project_root()
+    name, original_description, content = parse_skill_md(skill_path)
+    current_description = description_override or original_description
+
+    # Split into train/test if holdout > 0
+    if holdout > 0:
+        train_set, test_set = split_eval_set(eval_set, holdout)
+        if verbose:
+            print(f"Split: {len(train_set)} train, {len(test_set)} test (holdout={holdout})", file=sys.stderr)
+    else:
+        train_set = eval_set
+        test_set = []
+
+    history = []
+    exit_reason = "unknown"
+
+    for iteration in range(1, max_iterations + 1):
+        if verbose:
+            print(f"\n{'='*60}", file=sys.stderr)
+            print(f"Iteration {iteration}/{max_iterations}", file=sys.stderr)
+            print(f"Description: {current_description}", file=sys.stderr)
+            print(f"{'='*60}", file=sys.stderr)
+
+        # Evaluate train + test together in one batch for parallelism
+        all_queries = train_set + test_set
+        t0 = time.time()
+        all_results = run_eval(
+            eval_set=all_queries,
+            skill_name=name,
+            description=current_description,
+            num_workers=num_workers,
+            timeout=timeout,
+            project_root=project_root,
+            runs_per_query=runs_per_query,
+            trigger_threshold=trigger_threshold,
+            model=model,
+        )
+        eval_elapsed = time.time() - t0
+
+        # Split results back into train/test by matching queries
+        train_queries_set = {q["query"] for q in train_set}
+        train_result_list = [r for r in all_results["results"] if r["query"] in train_queries_set]
+        test_result_list = [r for r in all_results["results"] if r["query"] not in train_queries_set]
+
+        train_passed = sum(1 for r in train_result_list if r["pass"])
+        train_total = len(train_result_list)
+        train_summary = {"passed": train_passed, "failed": train_total - train_passed, "total": train_total}
+        train_results = {"results": train_result_list, "summary": train_summary}
+
+        if test_set:
+            test_passed = sum(1 for r in test_result_list if r["pass"])
+            test_total = len(test_result_list)
+            test_summary = {"passed": test_passed, "failed": test_total - test_passed, "total": test_total}
+            test_results = {"results": test_result_list, "summary": test_summary}
+        else:
+            test_results = None
+            test_summary = None
+
+        history.append({
+            "iteration": iteration,
+            "description": current_description,
+            "train_passed": train_summary["passed"],
+            "train_failed": train_summary["failed"],
+            "train_total": train_summary["total"],
+            "train_results": train_results["results"],
+            "test_passed": test_summary["passed"] if test_summary else None,
+            "test_failed": test_summary["failed"] if test_summary else None,
+            "test_total": test_summary["total"] if test_summary else None,
+            "test_results": test_results["results"] if test_results else None,
+            # For backward compat with report generator
+            "passed": train_summary["passed"],
+            "failed": train_summary["failed"],
+            "total": train_summary["total"],
+            "results": train_results["results"],
+        })
+
+        # Write live report if path provided
+        if live_report_path:
+            partial_output = {
+                "original_description": original_description,
+                "best_description": current_description,
+                "best_score": "in progress",
+                "iterations_run": len(history),
+                "holdout": holdout,
+                "train_size": len(train_set),
+                "test_size": len(test_set),
+                "history": history,
+            }
+            live_report_path.write_text(generate_html(partial_output, auto_refresh=True, skill_name=name))
+
+        if verbose:
+            def print_eval_stats(label, results, elapsed):
+                pos = [r for r in results if r["should_trigger"]]
+                neg = [r for r in results if not r["should_trigger"]]
+                tp = sum(r["triggers"] for r in pos)
+                pos_runs = sum(r["runs"] for r in pos)
+                fn = pos_runs - tp
+                fp = sum(r["triggers"] for r in neg)
+                neg_runs = sum(r["runs"] for r in neg)
+                tn = neg_runs - fp
+                total = tp + tn + fp + fn
+                precision = tp / (tp + fp) if (tp + fp) > 0 else 1.0
+                recall = tp / (tp + fn) if (tp + fn) > 0 else 1.0
+                accuracy = (tp + tn) / total if total > 0 else 0.0
+                print(f"{label}: {tp+tn}/{total} correct, precision={precision:.0%} recall={recall:.0%} accuracy={accuracy:.0%} ({elapsed:.1f}s)", file=sys.stderr)
+                for r in results:
+                    status = "PASS" if r["pass"] else "FAIL"
+                    rate_str = f"{r['triggers']}/{r['runs']}"
+                    print(f"  [{status}] rate={rate_str} expected={r['should_trigger']}: {r['query'][:60]}", file=sys.stderr)
+
+            print_eval_stats("Train", train_results["results"], eval_elapsed)
+            if test_summary:
+                print_eval_stats("Test ", test_results["results"], 0)
+
+        if train_summary["failed"] == 0:
+            exit_reason = f"all_passed (iteration {iteration})"
+            if verbose:
+                print(f"\nAll train queries passed on iteration {iteration}!", file=sys.stderr)
+            break
+
+        if iteration == max_iterations:
+            exit_reason = f"max_iterations ({max_iterations})"
+            if verbose:
+                print(f"\nMax iterations reached ({max_iterations}).", file=sys.stderr)
+            break
+
+        # Improve the description based on train results
+        if verbose:
+            print(f"\nImproving description...", file=sys.stderr)
+
+        t0 = time.time()
+        # Strip test scores from history so improvement model can't see them
+        blinded_history = [
+            {k: v for k, v in h.items() if not k.startswith("test_")}
+            for h in history
+        ]
+        new_description = improve_description(
+            skill_name=name,
+            skill_content=content,
+            current_description=current_description,
+            eval_results=train_results,
+            history=blinded_history,
+            model=model,
+            log_dir=log_dir,
+            iteration=iteration,
+        )
+        improve_elapsed = time.time() - t0
+
+        if verbose:
+            print(f"Proposed ({improve_elapsed:.1f}s): {new_description}", file=sys.stderr)
+
+        current_description = new_description
+
+    # Find the best iteration by TEST score (or train if no test set)
+    if test_set:
+        best = max(history, key=lambda h: h["test_passed"] or 0)
+        best_score = f"{best['test_passed']}/{best['test_total']}"
+    else:
+        best = max(history, key=lambda h: h["train_passed"])
+        best_score = f"{best['train_passed']}/{best['train_total']}"
+
+    if verbose:
+        print(f"\nExit reason: {exit_reason}", file=sys.stderr)
+        print(f"Best score: {best_score} (iteration {best['iteration']})", file=sys.stderr)
+
+    return {
+        "exit_reason": exit_reason,
+        "original_description": original_description,
+        "best_description": best["description"],
+        "best_score": best_score,
+        "best_train_score": f"{best['train_passed']}/{best['train_total']}",
+        "best_test_score": f"{best['test_passed']}/{best['test_total']}" if test_set else None,
+        "final_description": current_description,
+        "iterations_run": len(history),
+        "holdout": holdout,
+        "train_size": len(train_set),
+        "test_size": len(test_set),
+        "history": history,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Run eval + improve loop")
+    parser.add_argument("--eval-set", required=True, help="Path to eval set JSON file")
+    parser.add_argument("--skill-path", required=True, help="Path to skill directory")
+    parser.add_argument("--description", default=None, help="Override starting description")
+    parser.add_argument("--num-workers", type=int, default=10, help="Number of parallel workers")
+    parser.add_argument("--timeout", type=int, default=30, help="Timeout per query in seconds")
+    parser.add_argument("--max-iterations", type=int, default=5, help="Max improvement iterations")
+    parser.add_argument("--runs-per-query", type=int, default=3, help="Number of runs per query")
+    parser.add_argument("--trigger-threshold", type=float, default=0.5, help="Trigger rate threshold")
+    parser.add_argument("--holdout", type=float, default=0.4, help="Fraction of eval set to hold out for testing (0 to disable)")
+    parser.add_argument("--model", required=True, help="Model for improvement")
+    parser.add_argument("--verbose", action="store_true", help="Print progress to stderr")
+    parser.add_argument("--report", default="auto", help="Generate HTML report at this path (default: 'auto' for temp file, 'none' to disable)")
+    parser.add_argument("--results-dir", default=None, help="Save all outputs (results.json, report.html, log.txt) to a timestamped subdirectory here")
+    args = parser.parse_args()
+
+    eval_set = json.loads(Path(args.eval_set).read_text())
+    skill_path = Path(args.skill_path)
+
+    if not (skill_path / "SKILL.md").exists():
+        print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr)
+        sys.exit(1)
+
+    name, _, _ = parse_skill_md(skill_path)
+
+    # Set up live report path
+    if args.report != "none":
+        if args.report == "auto":
+            timestamp = time.strftime("%Y%m%d_%H%M%S")
+            live_report_path = Path(tempfile.gettempdir()) / f"skill_description_report_{skill_path.name}_{timestamp}.html"
+        else:
+            live_report_path = Path(args.report)
+        # Open the report immediately so the user can watch
+        live_report_path.write_text("<html><body><h1>Starting optimization loop...</h1><meta http-equiv='refresh' content='5'></body></html>")
+        webbrowser.open(str(live_report_path))
+    else:
+        live_report_path = None
+
+    # Determine output directory (create before run_loop so logs can be written)
+    if args.results_dir:
+        timestamp = time.strftime("%Y-%m-%d_%H%M%S")
+        results_dir = Path(args.results_dir) / timestamp
+        results_dir.mkdir(parents=True, exist_ok=True)
+    else:
+        results_dir = None
+
+    log_dir = results_dir / "logs" if results_dir else None
+
+    output = run_loop(
+        eval_set=eval_set,
+        skill_path=skill_path,
+        description_override=args.description,
+        num_workers=args.num_workers,
+        timeout=args.timeout,
+        max_iterations=args.max_iterations,
+        runs_per_query=args.runs_per_query,
+        trigger_threshold=args.trigger_threshold,
+        holdout=args.holdout,
+        model=args.model,
+        verbose=args.verbose,
+        live_report_path=live_report_path,
+        log_dir=log_dir,
+    )
+
+    # Save JSON output
+    json_output = json.dumps(output, indent=2)
+    print(json_output)
+    if results_dir:
+        (results_dir / "results.json").write_text(json_output)
+
+    # Write final HTML report (without auto-refresh)
+    if live_report_path:
+        live_report_path.write_text(generate_html(output, auto_refresh=False, skill_name=name))
+        print(f"\nReport: {live_report_path}", file=sys.stderr)
+
+    if results_dir and live_report_path:
+        (results_dir / "report.html").write_text(generate_html(output, auto_refresh=False, skill_name=name))
+
+    if results_dir:
+        print(f"Results saved to: {results_dir}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

package/skills/skill-creator/scripts/utils.py

@@ -0,0 +1,47 @@
+"""Shared utilities for skill-creator scripts."""
+
+from pathlib import Path
+
+
+
+def parse_skill_md(skill_path: Path) -> tuple[str, str, str]:
+    """Parse a SKILL.md file, returning (name, description, full_content)."""
+    content = (skill_path / "SKILL.md").read_text()
+    lines = content.split("\n")
+
+    if lines[0].strip() != "---":
+        raise ValueError("SKILL.md missing frontmatter (no opening ---)")
+
+    end_idx = None
+    for i, line in enumerate(lines[1:], start=1):
+        if line.strip() == "---":
+            end_idx = i
+            break
+
+    if end_idx is None:
+        raise ValueError("SKILL.md missing frontmatter (no closing ---)")
+
+    name = ""
+    description = ""
+    frontmatter_lines = lines[1:end_idx]
+    i = 0
+    while i < len(frontmatter_lines):
+        line = frontmatter_lines[i]
+        if line.startswith("name:"):
+            name = line[len("name:"):].strip().strip('"').strip("'")
+        elif line.startswith("description:"):
+            value = line[len("description:"):].strip()
+            # Handle YAML multiline indicators (>, |, >-, |-)
+            if value in (">", "|", ">-", "|-"):
+                continuation_lines: list[str] = []
+                i += 1
+                while i < len(frontmatter_lines) and (frontmatter_lines[i].startswith("  ") or frontmatter_lines[i].startswith("\t")):
+                    continuation_lines.append(frontmatter_lines[i].strip())
+                    i += 1
+                description = " ".join(continuation_lines)
+                continue
+            else:
+                description = value.strip('"').strip("'")
+        i += 1
+
+    return name, description, content

package/skills/spec-writing/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: spec-writing
+description: >-
+  撰写和修订模块化需求功能文档，输出到 specs/ 目录。每篇功能文档包含六段结构：功能概述、用户故事、需求描述、技术要求、约束条件、测试标准。所有结构图一律使用 Mermaid（flowchart、sequenceDiagram、erDiagram 等）。Monorepo 默认 apps/ + packages/ 布局。
+  务必在以下场景使用本 skill：用户提到需求文档、PRD、产品需求、功能文档、specs、用户故事、user stories、验收标准、acceptance criteria、feature requirements、需求分析、业务需求、功能需求、需求规格、需求评审、需求变更、功能点拆分，或者用户要求撰写 / 修订 / 评审某个功能的详细描述，即使没有明确说“需求文档”。不适用于纯技术选型文档。
+---
+
+# 需求文档（Specs）
+
+本 Skill 负责**需求文档**的撰写与修订——从一句话需求到结构化的、可交付的功能文档。它解决的核心问题是：让需求表达从模糊口头沟通变成可追踪、可评审、可验收的标准化文档。
+
+**不**负责独立技术选型长文。**不**替代 UI 视觉设计稿，但须用 **Mermaid** 表达所有结构类信息，因为 Mermaid 可版本管理、可协作编辑、可嵌入 Markdown。
+
+## 原则
+
+- **模块化**：按系统模块拆分目录；模块内按页面或功能点**独立成文件**，避免单文件过长。这样做的好处是每个文件有清晰的职责边界，团队可并行编写，评审和变更时只需关注受影响的文件。
+- **结构化**：每个功能文档必须包含下列 **六个部分**，缺一不可。六段结构确保从"做什么"到"怎么验收"形成闭环，避免遗漏。
+- **Monorepo 语境**：若需求涉及仓库布局，默认约定为 **`apps/`** 业务应用、**`packages/`** 可复用包；与项目实际不符时以用户/仓库说明为准。
+
+## 图表（唯一绘图语言：Mermaid）
+
+需求文档中凡需**可视化**，**一律使用 Mermaid**。Mermaid 是纯文本，可 Git 管理、可 diff、可 PR review。
+
+常用类型：`graph TD/LR`（模块/架构图）、`flowchart`（流程/状态）、`sequenceDiagram`（时序）、`erDiagram`（实体关系）。图内嵌于 ` ```mermaid ` 代码块中。
+
+> **何时该画图**：≥2 角色交互→时序图；≥3 步分支→流程图；新增/变更实体→ER 图；模块依赖→模块图。
+>
+> 详细类型表、使用指南与示例见 → `references/mermaid-guide.md`
+
+## 推荐目录示例
+
+```
+specs/
+├── auth/
+│   ├── login.md
+│   └── register.md
+├── user/
+│   ├── profile.md
+│   └── settings.md
+└── dashboard/
+    └── overview.md
+```
+
+## 单篇功能文档六段结构
+
+1. **功能概述**  
+   一两句话说明目标与业务价值：做什么、为什么做，范围清晰。好的概述能让不了解项目背景的人在 10 秒内理解这个功能的意义。
+
+2. **用户故事**  
+   格式：`作为 [用户角色]，我希望 [完成某件事]，以便 [获得某种价值]。`  
+   可多条，覆盖不同角色或场景。
+
+   **示例**：
+   - 作为**普通用户**，我希望通过手机号+验证码登录，以便无需记忆密码即可快速访问系统。
+   - 作为**管理员**，我希望查看登录失败日志，以便及时发现异常访问行为。
+
+3. **需求描述**（结构化）  
+   - **输入**：数据、触发条件  
+   - **输出**：结果、界面变化  
+   - **交互流程**：步骤与状态流转（**复杂流程须配流程图或时序图**）  
+   - **界面要求**：布局、组件形态、文案；空态 / 加载态 / 错误态  
+
+4. **技术要求**  
+   接口与数据结构、性能指标（响应时间、并发等）、特殊实现（防抖、轮询、懒加载等）；涉及多模块协作时可配**模块图**；涉及**新增或变更库表/实体**时须配 **`erDiagram`**（或与项目统一 ER 文档交叉引用并说明变更点）。
+
+5. **约束条件**  
+   时间线与优先级、第三方依赖（短信、支付、地图等）、合规与安全、**本期不做**的边界。明确"不做什么"与"做什么"同等重要，它防止范围蔓延。
+
+6. **测试标准**（验收）  
+   - **正常路径**：覆盖核心业务流程  
+   - **边界值**：极值、空值、最大长度等  
+   - **异常路径**（非法输入、网络错误、权限不足等）  
+   - **回归点**（可能影响到的已有功能）  
+   - **交叉组合编排**（当存在多个测试维度时）
+   
+   每条测试标准应具备可执行性：描述操作步骤和预期结果，而非仅说明抽象要求。
+
+### 交叉组合编排与优先级评定
+
+当一个功能涉及多组独立的测试维度（≥ 2 维且至少有一维 ≥ 3 取值）时，需要**显式列出维度组合矩阵**并**评定每条组合的优先级**（P0 / P1 / P2 / P3），为后续 TDD 提供铺垫。
+
+优先级判定顺序：核心业务路径 → 资金/安全相关 → 错误恢复 → 边界值 → 等价类合并 → 逻辑不可达。矩阵中 P0 行直接对应 TDD 第一批测试用例。
+
+> 完整编排步骤、优先级定义、判断依据与登录功能 12 组合示例见 → `references/test-matrix.md`
+
+## 执行方式
+
+- **新建**：先定模块与文件路径，再按六段逐段补齐；缺信息时向用户确认，不臆造业务规则；**该画图处给出 Mermaid，不省略**。
+- **修订**：保持模块边界；改动处同步更新「测试标准」与「约束条件」中相关条目，并**同步更新相关 Mermaid 图**。
+- **评审辅助**：如果用户提供了已有需求文档让你评审，按六段结构逐项检查完整性，指出缺失或模糊之处，给出修改建议。
+
+## 常见问题与处理
+
+- **用户只给了一句话需求**（如"做一个登录功能"）：先拆解为需要收集的信息清单（支持哪些登录方式？有无第三方登录？是否需要注册？），逐步引导用户澄清，再输出六段文档。
+- **需求跨多个模块**：为每个模块生成独立文档，但在各文档的「技术要求」中交叉引用相关模块，必要时画模块依赖图。
+- **Mermaid 图过于复杂**：拆成多张小图，每张聚焦一个关注点（如一张时序图专注登录流程，另一张专注 token 刷新流程）。

package/skills/spec-writing/references/mermaid-guide.md

@@ -0,0 +1,66 @@
+# Mermaid 图表速查
+
+需求文档中凡需可视化，一律使用 Mermaid。
+
+## 常用类型
+
+| 类型 | 典型用途 | Mermaid 形式 |
+|------|----------|----------------|
+| 模块图 | 功能/子系统/包之间依赖或边界 | `graph TD` / `graph LR` |
+| 流程图 | 操作步骤、状态机、业务分支 | `flowchart` |
+| 时序图 | 用户、前端、后端、第三方交互顺序 | `sequenceDiagram` |
+| 架构图 | 本功能在整体系统中的位置、数据流向 | `flowchart` / `flowchart LR` |
+| **ER 图** | **本功能涉及的持久化实体**、字段、关系 | **`erDiagram`** |
+
+## 何时该画图
+
+- 涉及 **两个以上角色或系统交互** → 时序图
+- 有 **三步以上流程分支** → 流程图
+- 涉及 **新增/变更实体** → ER 图
+- **模块间有调用或依赖关系** → 模块图
+- 宁可多画几张简洁的图，也不要写大段纯文字描述复杂交互
+
+## 嵌入方式
+
+图内嵌于 Markdown 的 ` ```mermaid ` 代码块中；复杂场景可拆为多张图，每张聚焦一个关注点。
+
+## 示例
+
+### 时序图（登录流程）
+
+```mermaid
+sequenceDiagram
+    participant U as 用户
+    participant F as 前端
+    participant B as 后端
+    participant SMS as 短信服务
+
+    U->>F: 输入手机号
+    F->>B: 请求发送验证码
+    B->>SMS: 发送验证码
+    SMS-->>U: 收到验证码
+    U->>F: 输入验证码
+    F->>B: 提交登录请求
+    B-->>F: 返回 Token
+    F-->>U: 跳转首页
+```
+
+### ER 图（用户与会话）
+
+```mermaid
+erDiagram
+    USER {
+        int id PK
+        string phone
+        string email
+        string status
+        datetime created_at
+    }
+    SESSION {
+        int id PK
+        int user_id FK
+        string token
+        datetime expires_at
+    }
+    USER ||--o{ SESSION : "has"
+```

package/skills/spec-writing/references/test-matrix.md

@@ -0,0 +1,73 @@
+# 测试标准：交叉组合编排与优先级评定
+
+## 交叉组合编排
+
+当一个功能涉及多组独立的测试维度时，需要**显式列出维度组合矩阵**，为后续 TDD 测试驱动开发提供铺垫依据。核心价值：把隐含的组合逻辑变成可追踪的测试用例列表，避免遗漏关键路径。
+
+### 编排步骤
+
+1. **识别测试维度**：从需求描述中提取所有影响行为的独立变量
+2. **列出每个维度的取值**：穷举每个维度的合法取值
+3. **生成组合矩阵**：用表格列出所有逻辑组合
+4. **评定优先级**：对每个组合标记 P0 / P1 / P2 / P3
+5. **标注预期结果**：每个组合对应的预期行为
+
+### 何时编排
+
+- 测试维度 ≥ 2 且至少有一个维度 ≥ 3 个取值时，应显式列出矩阵
+- 简单的二元场景（如"登录/未登录"）无需矩阵化
+
+## 测试优先级评定
+
+### 优先级定义
+
+| 优先级 | 含义 | TDD 要求 |
+|--------|------|----------|
+| **P0** | 核心业务路径，不通过则功能不可用 | 必须在开发前编写对应测试用例 |
+| **P1** | 重要但非阻塞，影响用户体验或安全 | 应在 Sprint 内补充测试 |
+| **P2** | 锦上添花的边界覆盖 | 有余力时编写 |
+| **P3** | 与其他组合行为等价或逻辑上不可达 | 不需要测试，需说明跳过原因 |
+
+### 优先级判断依据
+
+按以下顺序判断每个测试组合的优先级：
+
+1. **核心业务路径**：正常流程中用户最常走的路径 → P0
+2. **资金/安全相关**：涉及支付、权限、数据安全的路径 → P0
+3. **错误恢复路径**：用户操作出错后的恢复流程 → P1
+4. **边界值组合**：极值、空值、最大长度等 → P1
+5. **等价类合并**：多个组合预期行为完全一致 → 保留一个为 P1，其余 P3
+6. **逻辑不可达**：前置条件互斥导致无法触发的组合 → P3
+
+### 完整示例（用户登录功能）
+
+**测试维度：**
+- A - 登录方式：手机号+验证码、邮箱+密码
+- B - 用户状态：新用户、已存在、已锁定
+- C - 网络状态：正常、超时
+
+**组合矩阵（2 × 3 × 2 = 12 种）：**
+
+| # | 登录方式 | 用户状态 | 网络状态 | 预期结果 | 优先级 | 优先级理由 |
+|---|---------|---------|---------|---------|-------|-----------|
+| 1 | 手机号+验证码 | 已存在 | 正常 | 登录成功，跳转首页 | P0 | 核心业务路径 |
+| 2 | 手机号+验证码 | 新用户 | 正常 | 自动注册并登录 | P0 | 新用户首次体验 |
+| 3 | 手机号+验证码 | 已锁定 | 正常 | 提示账号已锁定 | P0 | 安全相关 |
+| 4 | 手机号+验证码 | 已存在 | 超时 | 提示网络错误，保留输入 | P1 | 错误恢复路径 |
+| 5 | 邮箱+密码 | 已存在 | 正常 | 登录成功，跳转首页 | P0 | 核心业务路径 |
+| 6 | 邮箱+密码 | 新用户 | 正常 | 提示用户不存在 | P0 | 核心分支 |
+| 7 | 邮箱+密码 | 已锁定 | 正常 | 提示账号已锁定 | P0 | 安全相关 |
+| 8 | 邮箱+密码 | 已存在 | 超时 | 提示网络错误，保留输入 | P1 | 错误恢复路径 |
+| 9 | 手机号+验证码 | 新用户 | 超时 | 提示网络错误 | P3 | 与 #4 行为一致（等价类） |
+| 10 | 手机号+验证码 | 已锁定 | 超时 | 提示网络错误 | P3 | 网络错误优先于业务提示（等价类） |
+| 11 | 邮箱+密码 | 新用户 | 超时 | 提示网络错误 | P3 | 与 #8 行为一致（等价类） |
+| 12 | 邮箱+密码 | 已锁定 | 超时 | 提示网络错误 | P3 | 与 #10 同理（等价类） |
+
+**统计：** P0 6 个 / P1 2 个 / P3 4 个 → TDD 第一批至少 6 个测试用例（P0）
+
+## 与 TDD 的衔接
+
+1. **P0 行**直接对应需要编写的测试用例，开发前先写这些测试
+2. **P1 行**在 P0 测试通过后补充
+3. 矩阵中的**预期结果**列就是测试用例的 `expect` 断言
+4. 矩阵的维度取值就是测试用例的**参数化输入**（如 `test.each` / `@pytest.mark.parametrize`）