ironweave 1.0.0

package/skills/task-difficulty/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: task-difficulty
+description: >-
+  任务难度评估节流阀——对用户输入的任务/需求进行多维度难度分析和评分，防止低估复杂度。先追溯任务涉及的上下文（代码结构、依赖关系、影响范围），再综合评分并给出分级和执行建议。内置"上浮偏差"：除非任务明显简单，否则主动提升一个难度等级。独立使用时做纯难度评估，结合其他工具时可作为任务执行的前置判断。
+  务必在以下场景使用本 skill：难度分析、任务评估、复杂度评分、difficulty analysis、task scoring、节流阀、任务分级、风险评估、影响范围分析、工作量评估、scope analysis、前置判断。
+---
+
+# 任务难度评估
+
+本 Skill 解决一个核心问题：**AI 模型容易低估任务复杂度**。用户给出一句话需求，模型可能直接动手，忽略隐藏的技术债、跨模块耦合、边界条件，导致返工或质量问题。
+
+本 Skill 作为**节流阀（throttle valve）**：在执行前先评估难度，给出分级和上下文分析，防止"看起来简单实则复杂"的任务被草率处理。
+
+## 核心机制
+
+```mermaid
+graph LR
+    INPUT["用户输入<br/>任务描述"]
+    CTX["上下文追溯<br/>涉及的文件·模块·依赖"]
+    SCORE["多维度评分<br/>5个维度 × 1-5分"]
+    LEVEL["难度分级<br/>L1-L5"]
+    THROTTLE{"节流阀<br/>是否明显简单？"}
+    OUT_KEEP["维持原级"]
+    OUT_BUMP["上浮一级"]
+    RESULT["输出<br/>难度报告"]
+
+    INPUT --> CTX --> SCORE --> LEVEL --> THROTTLE
+    THROTTLE -->|"是，L1证据充分"| OUT_KEEP --> RESULT
+    THROTTLE -->|"否，存在不确定性"| OUT_BUMP --> RESULT
+
+    style INPUT fill:#e3f2fd,stroke:#1976d2
+    style THROTTLE fill:#fff3e0,stroke:#f57c00,stroke-width:2px
+    style RESULT fill:#e8f5e9,stroke:#388e3c
+```
+
+## 难度等级
+
+| 等级 | 名称 | 典型特征 | 示例 |
+|------|------|---------|------|
+| **L1** | 琐碎 | 单文件、无逻辑变更、配置/文案修改 | 修改按钮文字、更新版本号 |
+| **L2** | 简单 | 单模块、逻辑清晰、无跨模块影响 | 新增一个工具函数、修复已定位的 Bug |
+| **L3** | 中等 | 多文件、涉及 2-3 个模块、需要设计决策 | 新增 CRUD 页面、重构组件 API |
+| **L4** | 复杂 | 跨模块联动、架构影响、需要方案评审 | 新增权限系统、接入第三方支付 |
+| **L5** | 重大 | 系统级变更、破坏性改动、数据迁移 | 微服务拆分、数据库 Schema 迁移、框架升级 |
+
+## 上浮偏差规则（Throttle）
+
+这是本 skill 的核心差异化机制——**加权分偏置**，而非直接跳级：
+
+1. **偏置上浮**：加权分 +0.5（10 分制下），可能导致跨级也可能不跨级
+2. **L1 豁免条件**：仅当以下全部满足时，不施加偏置：
+   - 变更范围 ≤ 1 个文件
+   - 不涉及业务逻辑
+   - 不涉及跨模块导入/导出
+   - 无测试覆盖要求
+3. **封顶 10 分**：偏置后不超过 10
+4. **偏置可被覆盖**：如果上下文分析明确表明无风险（如纯文案修改），可取消偏置，但须在报告中给出原因
+
+## 评估维度
+
+对每个维度打 **1-10 分**，然后取加权平均映射到 L1-L5。
+
+| 维度 | 权重 | 评估内容 |
+|------|------|---------|
+| **范围 (Scope)** | 30% | 涉及多少文件/模块、变更面积 |
+| **深度 (Depth)** | 25% | 技术复杂度、算法难度、架构层级 |
+| **耦合 (Coupling)** | 20% | 跨模块依赖、接口变更的连锁影响 |
+| **风险 (Risk)** | 15% | 出错的代价、可逆性、数据安全 |
+| **认知 (Cognition)** | 10% | 需要的领域知识、隐含的业务规则 |
+
+### 加权分 → 等级映射
+
+| 加权分范围 | 等级 |
+|-----------|------|
+| 1.0 - 2.0 | L1（琐碎） |
+| 2.1 - 4.0 | L2（简单） |
+| 4.1 - 6.0 | L3（中等） |
+| 6.1 - 8.0 | L4（复杂） |
+| 8.1 - 10.0 | L5（重大） |
+
+> 完整评分细则见 → `references/scoring-guide.md`
+
+## 上下文追溯
+
+评分不是凭空打分，必须先追溯任务涉及的上下文：
+
+### 追溯步骤
+
+```
+1. 解析输入 → 提取关键实体（模块名、文件名、功能点、技术概念）
+2. 探索代码 → 查找相关文件、导入链、依赖关系
+3. 识别边界 → 确定变更的直接影响范围和间接影响范围
+4. 发现隐患 → 检查测试覆盖、类型安全、错误处理等
+```
+
+### 上下文来源
+
+- 项目文件结构（目录树、文件分类）
+- 代码依赖关系（import/export 链）
+- 配置文件（package.json、tsconfig 等）
+- 已有测试覆盖
+- Git 历史（该区域的变更频率）
+
+> 注意：本 skill 独立工作时，自行读取项目文件获取上下文。
+
+## 输入输出
+
+### 输入
+
+一段任务描述文本。可以是：
+- 用户的自然语言需求（"帮我加个登录功能"）
+- Bug 报告（"点击提交按钮后页面白屏"）
+- 重构请求（"把这个组件拆成三个"）
+- 技术任务（"升级到 Vue 3.5"）
+
+### 输出：难度报告
+
+```markdown
+# 难度评估报告
+
+## 基本信息
+
+- **任务**: {一句话描述}
+- **原始评级**: L{n}
+- **最终评级**: L{m} {上浮说明或保持原因}
+
+## 评分明细
+
+| 维度 | 分数(1-5) | 依据 |
+|------|----------|------|
+| 范围 | {n} | {简要说明} |
+| 深度 | {n} | {简要说明} |
+| 耦合 | {n} | {简要说明} |
+| 风险 | {n} | {简要说明} |
+| 认知 | {n} | {简要说明} |
+| **加权** | **{avg}** | |
+
+## 上下文分析
+
+### 涉及范围
+- 直接影响：{文件/模块列表}
+- 间接影响：{可能受连锁影响的部分}
+
+### 关键风险点
+- {风险1}
+- {风险2}
+
+## 执行建议
+
+{根据难度等级给出的执行策略建议}
+```
+
+## Python 脚本
+
+```bash
+python scripts/difficulty_scorer.py assess --input <任务描述文本> [--root <project_root>] [--format json|markdown]
+```
+
+- `--root`：提供项目路径时，会自动追溯代码上下文辅助评分
+- `--format`：默认 `markdown`，`json` 格式便于程序消费
+
+> 脚本实现见 → `scripts/difficulty_scorer.py`

package/skills/task-difficulty/references/scoring-guide.md

@@ -0,0 +1,123 @@
+# 难度评分细则（1-10 分制）
+
+## 维度评分标准
+
+### 范围 (Scope) — 权重 30%
+
+| 分数 | 标准 |
+|------|------|
+| 1 | 单文件内的微修改（≤ 5 行，纯文案/数值） |
+| 2 | 单文件局部修改（≤ 20 行） |
+| 3 | 单文件较大修改 或 2-3 个紧密相关文件的小改动 |
+| 4 | 单模块内 3-5 个文件 |
+| 5 | 单模块内 5-8 个文件，或跨 2 个模块各少量文件 |
+| 6 | 跨 2-3 个模块，涉及 8-12 个文件 |
+| 7 | 跨 3-4 个模块，涉及 12-20 个文件 |
+| 8 | 跨 4+ 个模块，涉及 20+ 文件 |
+| 9 | 多数模块受影响，可能需要批量修改 |
+| 10 | 全局性变更，几乎所有模块都需修改 |
+
+### 深度 (Depth) — 权重 25%
+
+| 分数 | 标准 |
+|------|------|
+| 1 | 无逻辑变更（纯文案替换） |
+| 2 | 极简逻辑（配置值修改、样式调整） |
+| 3 | 简单逻辑（条件分支、字段映射） |
+| 4 | CRUD 模板化操作（增删改查页面，套路化） |
+| 5 | 中等逻辑（表单校验、API 集成、组件状态管理） |
+| 6 | 较复杂逻辑（权限控制、工作流、乐观更新） |
+| 7 | 复杂逻辑（状态机、并发处理、缓存策略） |
+| 8 | 高度复杂（自定义构建流程、性能关键路径优化） |
+| 9 | 算法密集（复杂数据结构、分布式协调） |
+| 10 | 系统级复杂度（编译器/解释器、实时计算引擎） |
+
+### 耦合 (Coupling) — 权重 20%
+
+| 分数 | 标准 |
+|------|------|
+| 1 | 完全独立，无外部依赖 |
+| 2 | 使用外部模块但不修改其接口 |
+| 3 | 修改模块内部实现，接口不变 |
+| 4 | 修改模块接口，已知调用方 ≤ 3 处 |
+| 5 | 修改模块接口，调用方 3-5 处 |
+| 6 | 修改公共接口，调用方 5-10 处 |
+| 7 | 修改公共接口，调用链 > 3 层 |
+| 8 | 修改基础设施组件（路由、中间件） |
+| 9 | 修改核心抽象（ORM 基类、通用组件库） |
+| 10 | 修改底层框架/运行时，影响全局所有模块 |
+
+### 风险 (Risk) — 权重 15%
+
+| 分数 | 标准 |
+|------|------|
+| 1 | 完全可逆，出错无影响 |
+| 2 | 可逆，出错影响极小（开发环境配置） |
+| 3 | 可逆但需额外工作（功能回退） |
+| 4 | 回退成本中等（需要测试验证） |
+| 5 | 部分不可逆（数据库 Schema 有 down migration） |
+| 6 | 回退困难（生产配置变更、第三方 API 对接） |
+| 7 | 涉及用户数据格式变更 |
+| 8 | 涉及安全策略或加密方案 |
+| 9 | 涉及付款/金融/合规流程 |
+| 10 | 不可逆且高危（删除生产数据、密钥轮换） |
+
+### 认知 (Cognition) — 权重 10%
+
+| 分数 | 标准 |
+|------|------|
+| 1 | 纯机械操作，无需任何领域知识 |
+| 2 | 需了解单个配置项或 API |
+| 3 | 需了解一个技术概念的基本用法 |
+| 4 | 需理解一个完整的技术方案（如 JWT 认证流程） |
+| 5 | 需理解业务领域规则（权限模型、计费逻辑） |
+| 6 | 需理解复杂业务流程（工作流、审批链） |
+| 7 | 需要跨领域知识（前端+后端+数据库） |
+| 8 | 需要跨领域+业务（技术方案+安全+业务合规） |
+| 9 | 需要专家级单领域知识（密码学、分布式一致性） |
+| 10 | 需要多个专家级领域知识（编译+安全+行业法规） |
+
+## 加权平均 → 等级映射
+
+```
+加权分 = Scope×0.30 + Depth×0.25 + Coupling×0.20 + Risk×0.15 + Cognition×0.10
+```
+
+| 加权分范围 | 等级 | 名称 |
+|-----------|------|------|
+| 1.0 - 2.0 | L1 | 琐碎 |
+| 2.1 - 4.0 | L2 | 简单 |
+| 4.1 - 6.0 | L3 | 中等 |
+| 6.1 - 8.0 | L4 | 复杂 |
+| 8.1 - 10.0 | L5 | 重大 |
+
+## 偏置上浮规则
+
+不再整级上浮，改为**加权分 +0.5 偏置**：
+
+```
+IF 范围 ≤ 2 AND 深度 ≤ 2 AND 耦合 ≤ 2 AND 风险 ≤ 3:
+    → 豁免偏置（明确标注理由）
+ELSE:
+    → 加权分 += 0.5（上限 10.0）
+```
+
+**效果示例**：
+
+| 原始加权 | 原始等级 | +0.5 后 | 最终等级 | 是否跨级 |
+|---------|---------|--------|---------|---------|
+| 1.5 | L1 | 2.0 | L1 | 否 |
+| 1.9 | L1 | 2.4 | L2 | 是（边界） |
+| 3.2 | L2 | 3.7 | L2 | 否 |
+| 3.8 | L2 | 4.3 | L3 | 是（边界） |
+| 5.5 | L3 | 6.0 | L3 | 否 |
+
+## 边界情况处理
+
+| 情况 | 处理方式 |
+|------|---------|
+| 任务描述模糊（< 20 字） | 认知 +1，范围 +1 |
+| 涉及遗留代码 | 耦合 +1 |
+| 首次接触的模块 | 认知 +1 |
+| 用户明确说"简单" | 不因此降分，按实际评估 |
+| 无法获取项目上下文 | 所有维度下限 +1 |

package/skills/task-difficulty/scripts/difficulty_scorer.py

@@ -0,0 +1,328 @@
+#!/usr/bin/env python3
+"""
+task-difficulty: 任务难度评估脚本
+
+用法:
+    python difficulty_scorer.py assess --input <任务描述> [--root <project_root>] [--format json|markdown]
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+# ── 维度定义 ──────────────────────────────────────────────
+
+DIMENSIONS = [
+    {"key": "scope", "name": "范围", "weight": 0.30},
+    {"key": "depth", "name": "深度", "weight": 0.25},
+    {"key": "coupling", "name": "耦合", "weight": 0.20},
+    {"key": "risk", "name": "风险", "weight": 0.15},
+    {"key": "cognition", "name": "认知", "weight": 0.10},
+]
+
+LEVEL_RANGES = [
+    (1.0, 2.0, "L1", "琐碎"),
+    (2.1, 4.0, "L2", "简单"),
+    (4.1, 6.0, "L3", "中等"),
+    (6.1, 8.0, "L4", "复杂"),
+    (8.1, 10.0, "L5", "重大"),
+]
+
+THROTTLE_BIAS = 0.5
+
+
+def score_to_level(score: float) -> tuple[str, str]:
+    """将加权分映射为等级。"""
+    for low, high, level, label in LEVEL_RANGES:
+        if low <= score <= high:
+            return level, label
+    return "L5", "重大"
+
+
+def level_label(level: str) -> str:
+    for _, _, lv, label in LEVEL_RANGES:
+        if lv == level:
+            return label
+    return ""
+
+
+def should_exempt_throttle(scores: dict[str, int]) -> bool:
+    """豁免偏置判定：范围≤2 且 深度≤2 且 耦合≤2 且 风险≤3。"""
+    return (
+        scores.get("scope", 0) <= 2
+        and scores.get("depth", 0) <= 2
+        and scores.get("coupling", 0) <= 2
+        and scores.get("risk", 0) <= 3
+    )
+
+
+def compute_weighted(scores: dict[str, int]) -> float:
+    total = 0.0
+    for dim in DIMENSIONS:
+        total += scores.get(dim["key"], 5) * dim["weight"]
+    return round(total, 2)
+
+
+# ── 上下文探索 ──────────────────────────────────────────────
+
+def explore_context(root: str, task_text: str) -> dict:
+    """探索项目上下文，提取与任务相关的结构信息。"""
+    context = {
+        "has_project": False,
+        "total_files": 0,
+        "modules": [],
+        "config_files": [],
+        "test_coverage": False,
+        "keywords_found": [],
+    }
+
+    root_path = Path(root).resolve()
+    if not root_path.exists():
+        return context
+
+    context["has_project"] = True
+
+    ignore_dirs = {
+        "node_modules", "dist", "build", ".git", "__pycache__",
+        ".next", ".nuxt", ".output", "coverage", ".cache",
+    }
+
+    # 提取任务中的关键词
+    words = set(re.findall(r"[a-zA-Z\u4e00-\u9fff]{2,}", task_text.lower()))
+
+    files = []
+    for dirpath, dirnames, filenames in os.walk(root_path):
+        dirnames[:] = [d for d in dirnames if d not in ignore_dirs]
+        rel_dir = Path(dirpath).relative_to(root_path)
+
+        for fname in filenames:
+            rel = str(rel_dir / fname)
+            files.append(rel)
+
+            # 检查文件名/路径是否与任务关键词相关
+            fname_lower = fname.lower()
+            for w in words:
+                if w in fname_lower or w in str(rel_dir).lower():
+                    context["keywords_found"].append({"keyword": w, "file": rel})
+
+    context["total_files"] = len(files)
+
+    # 识别模块（src/ 下的一级目录）
+    src_path = root_path / "src"
+    if src_path.exists():
+        context["modules"] = [
+            d.name for d in src_path.iterdir()
+            if d.is_dir() and d.name not in ignore_dirs
+        ]
+
+    # 识别配置文件
+    for f in root_path.iterdir():
+        if f.is_file() and f.suffix in (".json", ".yaml", ".yml", ".toml"):
+            context["config_files"].append(f.name)
+
+    # 检查测试覆盖
+    for test_pattern in ["__tests__", "test", "tests", "spec"]:
+        if (root_path / test_pattern).exists():
+            context["test_coverage"] = True
+            break
+
+    # 去重
+    seen = set()
+    unique = []
+    for kf in context["keywords_found"]:
+        key = f"{kf['keyword']}:{kf['file']}"
+        if key not in seen:
+            seen.add(key)
+            unique.append(kf)
+    context["keywords_found"] = unique[:20]
+
+    return context
+
+
+# ── 启发式预评分 ──────────────────────────────────────────────
+
+# 关键词与难度倾向的映射
+HIGH_COMPLEXITY_SIGNALS = [
+    "迁移", "migration", "升级", "upgrade", "重构", "refactor",
+    "权限", "permission", "auth", "安全", "security",
+    "支付", "payment", "加密", "encrypt",
+    "微服务", "microservice", "分布式", "distributed",
+    "性能", "performance", "并发", "concurrent",
+    "数据库", "database", "schema", "索引", "index",
+]
+
+LOW_COMPLEXITY_SIGNALS = [
+    "文案", "文字", "typo", "拼写",
+    "样式", "style", "颜色", "color",
+    "注释", "comment", "文档", "readme",
+    "版本号", "version",
+]
+
+
+def heuristic_scores(task_text: str, context: dict) -> dict:
+    """基于启发式规则生成初始评分建议（供模型参考或作为无模型降级）。"""
+    text_lower = task_text.lower()
+
+    scores = {"scope": 3, "depth": 3, "coupling": 3, "risk": 3, "cognition": 3}
+
+    # 高复杂度信号
+    high_hits = sum(1 for s in HIGH_COMPLEXITY_SIGNALS if s in text_lower)
+    if high_hits >= 4:
+        for k in scores:
+            scores[k] = min(10, scores[k] + 4)
+    elif high_hits >= 2:
+        for k in scores:
+            scores[k] = min(10, scores[k] + 2)
+    elif high_hits == 1:
+        for k in scores:
+            scores[k] = min(10, scores[k] + 1)
+
+    # 低复杂度信号
+    low_hits = sum(1 for s in LOW_COMPLEXITY_SIGNALS if s in text_lower)
+    if low_hits >= 2 and high_hits == 0:
+        for k in scores:
+            scores[k] = max(1, scores[k] - 2)
+    elif low_hits == 1 and high_hits == 0:
+        for k in scores:
+            scores[k] = max(1, scores[k] - 1)
+
+    # 上下文修正
+    if context.get("has_project"):
+        total = context.get("total_files", 0)
+        if total > 500:
+            scores["scope"] = min(10, scores["scope"] + 1)
+        if total > 1000:
+            scores["scope"] = min(10, scores["scope"] + 1)
+        keywords = context.get("keywords_found", [])
+        if len(keywords) > 10:
+            scores["coupling"] = min(10, scores["coupling"] + 1)
+
+    # 信息不足修正（无项目上下文）
+    if not context.get("has_project"):
+        for k in scores:
+            scores[k] = min(10, scores[k] + 1)
+
+    # 任务描述太短 → 信息不足
+    if len(task_text.strip()) < 20:
+        scores["cognition"] = min(10, scores["cognition"] + 1)
+        scores["scope"] = min(10, scores["scope"] + 1)
+
+    return scores
+
+
+# ── 输出格式化 ──────────────────────────────────────────────
+
+def format_markdown(result: dict) -> str:
+    lines = [
+        "# 难度评估报告",
+        "",
+        "## 基本信息",
+        "",
+        f"- **任务**: {result['task']}",
+        f"- **原始评级**: {result['raw_level']} ({level_label(result['raw_level'])})",
+        f"- **最终评级**: {result['final_level']} ({level_label(result['final_level'])})",
+        f"- **上浮说明**: {result['throttle_reason']}",
+        "",
+        "## 评分明细",
+        "",
+        "| 维度 | 分数(1-10) | 权重 |",
+        "|------|----------|------|",
+    ]
+
+    for dim in DIMENSIONS:
+        score = result["scores"].get(dim["key"], 0)
+        lines.append(f"| {dim['name']} | {score} | {int(dim['weight']*100)}% |")
+
+    lines.append(f"| **加权** | **{result['weighted_score']}** | |")
+    lines.append("")
+
+    if result.get("context_summary"):
+        lines.append("## 上下文分析")
+        lines.append("")
+        ctx = result["context_summary"]
+        if ctx.get("total_files"):
+            lines.append(f"- 项目文件总数: {ctx['total_files']}")
+        if ctx.get("modules"):
+            lines.append(f"- 识别模块: {', '.join(ctx['modules'])}")
+        if ctx.get("keywords_found"):
+            kw_list = [f"`{k['file']}`" for k in ctx["keywords_found"][:5]]
+            lines.append(f"- 关联文件: {', '.join(kw_list)}")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def format_json(result: dict) -> str:
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+# ── 命令实现 ──────────────────────────────────────────────
+
+def cmd_assess(task_input: str, root: str | None = None, fmt: str = "markdown"):
+    # 1. 追溯上下文
+    context = {}
+    if root:
+        context = explore_context(root, task_input)
+
+    # 2. 启发式评分
+    scores = heuristic_scores(task_input, context)
+
+    # 3. 计算加权分和等级
+    weighted = compute_weighted(scores)
+    raw_level, _ = score_to_level(weighted)
+
+    # 4. 节流阀偏置
+    if should_exempt_throttle(scores):
+        final_weighted = weighted
+        throttle_reason = "豁免偏置：范围/深度/耦合均低，风险可控"
+    else:
+        final_weighted = min(10.0, weighted + THROTTLE_BIAS)
+        throttle_reason = f"加权分 +{THROTTLE_BIAS} 偏置：{weighted} → {final_weighted}"
+
+    final_level, _ = score_to_level(final_weighted)
+
+    result = {
+        "task": task_input,
+        "scores": scores,
+        "weighted_score": weighted,
+        "final_weighted": final_weighted,
+        "raw_level": raw_level,
+        "final_level": final_level,
+        "throttle_reason": throttle_reason,
+        "context_summary": {
+            "total_files": context.get("total_files", 0),
+            "modules": context.get("modules", []),
+            "keywords_found": context.get("keywords_found", []),
+            "has_project": context.get("has_project", False),
+        } if context else None,
+    }
+
+    if fmt == "json":
+        print(format_json(result))
+    else:
+        print(format_markdown(result))
+
+
+# ── CLI 入口 ──────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(description="task-difficulty: 任务难度评估")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_assess = sub.add_parser("assess", help="评估任务难度")
+    p_assess.add_argument("--input", required=True, help="任务描述文本")
+    p_assess.add_argument("--root", default=None, help="项目根目录（提供后会自动追溯上下文）")
+    p_assess.add_argument("--format", default="markdown", choices=["json", "markdown"],
+                          help="输出格式（默认 markdown）")
+
+    args = parser.parse_args()
+
+    if args.command == "assess":
+        cmd_assess(args.input, args.root, args.format)
+
+
+if __name__ == "__main__":
+    main()

package/skills/tech-stack/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: tech-stack
+description: >-
+  撰写和维护技术选型文档（如 docs/tech-stack.md），覆盖前端（Vue 3 / React）、后端（Node.js 系如 NestJS / Express / Koa，或 Java 系如 Spring Boot）、数据库、运维、工程规范等全栈技术决策。Monorepo 默认 apps/ + packages/ 布局，TS 库使用 tsdown（非 tsup）构建，所有架构图和 ER 图使用 Mermaid。文档中须明确 Node.js 和 pnpm 版本。
+  务必在以下场景使用本 skill：用户提到技术选型、tech stack、技术架构、技术方案、架构设计、数据库设计、database design、stack decisions、框架选择、技术栈、技术路线、依赖选择、工具链选型、前后端选型、基础设施选型，或者用户要求编写/修订/评审技术架构文档、讨论该用什么框架/库/工具，即使没有明确说“技术选型”。不适用于具体功能需求文档。
+---
+
+# 技术架构选型
+
+本 Skill 负责**技术选型文档**（如 `docs/tech-stack.md`，路径以项目约定为准）——帮助团队将分散的技术决策统一成一份可追溯、可评审的文档。技术选型文档的核心价值是：让每个技术决策都有据可查、有理可循，避免"我以为你用的是 X"这类沟通问题。
+
+**不**展开需求六段式 Specs 的写法。
+
+## 原则
+
+- 在独立文档中写清**实际采用**的路线与依赖，每个技术选择都应说明**选择理由**和**对比过的备选方案**——这让后来者理解决策背景，也方便未来重新评估。
+- 前端可在 **Vue 3** 与 **React** 中选型（Monorepo 可多应用并存）；必须明确所选路线及理由，而非罗列全部可能技术。
+- **Monorepo 默认目录约定**：`apps/` 存放**业务应用/可运行项目**；`packages/` 存放**可复用包**（组件库、工具库、配置包等）。技术选型文档中应写明仓库是否采用该结构及例外说明。
+- **TypeScript 库构建**：`packages/` 内需产出 JS/类型声明的 TS 库，**优先使用 tsdown 作为打包工具，不采用 tsup**（tsdown 与 tsup 主要选项兼容，便于迁移；需满足其 Node 版本等要求时写入文档）。
+- **Node.js 与 pnpm 版本**：技术选型文档中应**明确写出**项目采用的 Node.js 与 pnpm 版本（或兼容范围）。版本选择建议采用当前 **稳定的 LTS**（非最新版，也非即将 EOL 的旧版），同时确保 ≥ 工具链的最低要求（如 tsdown）。版本信息应在以下位置保持一致：`package.json` 的 `engines`、`packageManager` 字段、`.nvmrc`（若有）、CI 与 Docker 配置。推荐使用 Corepack 锁定 pnpm 版本。
+
+## 图表（唯一绘图语言：Mermaid）
+
+技术选型文档中凡需**可视化**（架构、部署、模块关系、关键流程、组件时序、**数据库实体关系**等），**一律使用 Mermaid**，不使用 PlantUML、Draw.io 源文件、纯图片替代可编辑结构图等其它绘图方式（导出图若来自 Mermaid 渲染则可）。选择 Mermaid 是因为它是纯文本格式，可与 Markdown 文档一起纳入 Git 版本管理，便于 PR review 和变更追踪。
+
+常用类型与语法方向（按需选用，可组合多篇图）：
+
+| 类型 | 典型用途 | Mermaid 形式 |
+|------|----------|----------------|
+| 架构图 | 客户端、网关、服务、DB、缓存等部署与数据流 | `flowchart` / `flowchart LR` |
+| 模块图 | 业务模块、包之间的依赖或调用关系 | `graph TD` / `graph LR` |
+| 流程图 | 请求处理、发布、鉴权等步骤 | `flowchart` |
+| 时序图 | 登录、支付等多角色交互顺序 | `sequenceDiagram` |
+| **ER 图** | **数据库设计**：实体、字段、主外键、实体间关系 | **`erDiagram`** |
+
+图应内嵌于 Markdown 代码块（` ```mermaid `），便于版本管理与评审。
+
+> **画图时机**：架构图是技术选型文档的标配，至少要有一张全局架构视图；数据库设计必须有 ER 图；前后端交互复杂的场景配时序图。
+
+## 文档建议结构
+
+1. **概述**：项目形态、仓库结构（Monorepo 时说明 `apps/` / `packages/` 职责）、前后端边界；**运行时与工具链**：写明 **Node.js**、**pnpm** 的确认版本（或范围）及锁定方式（如 `packageManager`、`engines`、Corepack）；可配**架构图**。  
+2. **前端**：先写「跨框架通用」已定选项，再写「Vue 路线」或「React 路线」**之一（或按应用分别说明）**；可配**模块图**说明应用与包关系。  
+3. **UI**：第三方组件库或自研 `packages/ui` 等的选择与原则。  
+4. **后端**：框架（Node.js 系如 NestJS / Express / Koa，或 Java 系如 Spring Boot；**推荐 NestJS**）、API 风格、文档、校验、认证、权限、ORM（如 TypeORM / Prisma / Drizzle；**推荐 TypeORM**）、数据库（如 PostgreSQL / MySQL / MongoDB；**推荐 PostgreSQL**）、缓存、日志。**数据库设计**须用 Mermaid **`erDiagram`** 给出核心实体、字段与关系。  
+5. **运维与基础设施**（可选）：反向代理、容器化等。Docker 是可选项，根据项目实际部署需求决定是否采用。  
+6. **工程规范**：Lint/格式化、Git 钩子、提交规范、版本管理、CLI 等（按需取舍并写明版本或范围）。
+
+> 每一节的技术选择都应包含简短的**选型理由**（一两句话即可），说明为什么选它、有没有考虑过其他方案。这让文档不仅是一份清单，更是一份决策记录。
+
+## 参考技术表
+
+覆盖运行时与包管理、前端跨框架通用、Vue 路线、React 路线、UI 与组件库、后端、运维基础设施、工程规范共 8 类。写入文档时对每项标注「采用 / 不采用 / 待定」并说明理由。
+
+> 全部参考技术表见 → `references/tech-reference-tables.md`
+
+## 执行方式
+
+- 根据用户已给约束（团队规定、遗留栈、云厂商等）收敛选项；表中条目**非强制**，未采用的技术不必写入最终文档，或标注「未采用」。
+- 输出物应是**可交付的 Markdown**（或用户指定格式），便于纳入版本库并与实现保持一致；**与结构、流程、协作、数据库实体关系相关的说明应配 Mermaid 图**（含 **`erDiagram`**），避免仅用长段落描述。
+- 若用户未给出 **Node / pnpm** 版本：应结合当前**稳定 LTS**与依赖最低要求，在选型文档中给出**建议版本**并提醒同步写入 `engines`、`packageManager` 与 CI/Docker。
+
+## 常见问题与处理
+
+- **用户只说"帮我做个技术选型"**：先确认项目类型（Web 应用？移动端？管理后台？）、团队规模、是否有已有技术栈约束，再给出选型建议。
+- **用户要求对比两个技术方案**：从功能覆盖度、生态成熟度、学习曲线、团队熟悉度、社区活跃度等维度做对比表，给出推荐及理由。
+- **版本锁定不一致**：检查 `package.json` 的 `engines`/`packageManager`、`.nvmrc`、CI 配置、Docker 镜像中的版本，如有不一致应在文档中指出并给出统一方案。