# 技能开发反例库

**文档版本**：v1.0.0
**创建时间**：2026-01-14
**用途**：为 auto-test-skill 提供常见反例库，用于快速识别问题

---

## 使用说明

本文档按照"七大质量原则"分类，每类包含常见反例。

**使用方法**：
1. 在检查 skill 时，对比本文档中的反例
2. 发现相似模式时，记录为问题
3. 参考"正确做法"给出修复建议

---

## 1. 硬编码/AI功能规划反例

### 反例 1: 让 AI "手动创建目录"

**错误表现**：
```markdown
## 执行步骤
1. 创建目录：`output/reports/{timestamp}/`
2. 创建文件：`output/reports/{timestamp}/summary.md`
```

**问题**：这是确定性操作，应脚本化

**正确做法**：
```markdown
## 执行步骤
1. 运行 `scripts/init_session.py` 自动创建目录和文件
```

---

### 反例 2: 配置值硬编码在文档中

**错误表现**：
```markdown
## 配置说明
最大重试次数：3次
超时时间：30秒
```

**问题**：应移至 config.yaml

**正确做法**：
```yaml
# config.yaml
retries:
  max: 3
timeout: 30  # 秒
```

```markdown
## 配置说明
详见 config.yaml 中的 `retries.max` 和 `timeout` 配置项
```

---

### 反例 3: 让 AI 每次编写相同代码

**错误表现**：
```markdown
## 步骤 2
用 Python 读取 CSV 文件：
```python
import csv
with open(file, 'r') as f:
    reader = csv.reader(f)
    ...
```

**问题**：AI 每次都要"记住"这段代码

**正确做法**：
```markdown
## 步骤 2
运行 `scripts/read_csv.py --input {file}` 自动读取
```

---

### 反例 4: 过度配置化

**错误表现**：
```yaml
# config.yaml
file_formats:
  csv:
    extension: ".csv"
    delimiter: ","
    encoding: "utf-8"
```

**问题**：这些是 CSV 标准定义，不需要配置

**正确做法**：
```python
# scripts/reader.py
DELIMITER = ","  # CSV 标准
ENCODING = "utf-8"  # 现代标准
```

---

## 2. 冗余残留错误检查反例

### 反例 1: 残留引用

**错误表现**：
```markdown
# SKILL.md
详见 references/OLD_TEMPLATE.md
```
```bash
# 实际情况
$ ls references/OLD_TEMPLATE.md
ls: cannot access: No such file or directory
```

**问题**：引用已删除的文件

**正确做法**：
```markdown
# SKILL.md
详见 references/NEW_TEMPLATE.md
```

---

### 反例 2: 重复段落

**错误表现**：
```markdown
## 输入格式
输入必须是 PDF 格式，文件大小不超过 10MB...

## 使用示例
示例 1：输入一个 PDF 文件...
示例 2：输入一个 PDF 文件...（与示例 1 几乎相同）
```

**问题**：内容重复，应合并

**正确做法**：
```markdown
## 输入格式
输入必须是 PDF 格式，文件大小不超过 10MB...

## 使用示例
示例：输入一个 PDF 文件并解析...
```

---

### 反例 3: 僵尸文件

**错误表现**：
```
references/unused_guide.md  # 从未被 SKILL.md 或任何脚本引用
assets/old_template.txt     # 已被新模板替代，但未删除
scripts/backup_old.py       # 标记为"备份"，但未说明用途
```

**问题**：无用的文件占用空间，污染代码库

**正确做法**：
```bash
# 使用 Grep 搜索引用
grep -r "unused_guide" .
# 如果无结果，删除文件
rm references/unused_guide.md
```

---

### 反例 4: 配置重复定义

**错误表现**：
```yaml
# config.yaml
output:
  directory: "./output"
  format: "json"
```
```markdown
# SKILL.md
## 配置说明
- output_dir: 输出目录（默认：`output/`）
- output_format: 输出格式（默认：`json`）
```

**问题**：配置项名称不一致（`output.directory` vs `output_dir`）

**正确做法**：
```markdown
## 配置说明
详见 config.yaml 中的 `output.directory` 和 `output.format`
```

---

## 3. 安全性检查反例

### 反例 1: 路径遍历漏洞

**错误表现**：
```python
# 危险：未验证用户输入
user_path = input("输入文件路径：")
with open(user_path, 'r') as f:  # 可能访问任意文件
    ...
```

**问题**：用户可输入 `../../etc/passwd` 访问任意文件

**正确做法**：
```python
import os

user_path = input("输入文件路径：")
resolved = os.path.realpath(user_path)
base_dir = os.path.realpath("./data")

if not resolved.startswith(base_dir):
    raise ValueError("路径必须在 data 目录内")

with open(resolved, 'r') as f:
    ...
```

---

### 反例 2: 敏感信息泄露

**错误表现**：
```python
# 错误日志中暴露详细信息
except Exception as e:
    print(f"错误：处理文件 {user_path} 时失败，详情：{str(e)}")
    # user_path 可能是用户数据，e 可能包含内部路径
```

**问题**：泄露用户数据和系统内部信息

**正确做法**：
```python
except Exception as e:
    logger.error(f"处理文件失败：{e}", exc_info=True)
    # 不记录 user_path，使用日志系统而非 print
```

---

### 反例 3: 命令注入风险

**错误表现**：
```python
# 危险：用户输入直接用于系统命令
os.system(f"convert {user_input} output.pdf")
```

**问题**：用户可输入 `; rm -rf /` 执行任意命令

**正确做法**：
```python
import subprocess

subprocess.run(["convert", user_input, "output.pdf"], check=True)
# 使用参数化 API，而非字符串拼接
```

---

### 反例 4: 硬编码密钥

**错误表现**：
```python
# config.yaml
api_key: "sk-1234567890abcdef"
```

**问题**：密钥硬编码，会提交到 Git

**正确做法**：
```python
# config.yaml
api_key: ${API_KEY}  # 从环境变量读取
```

```bash
# .env（不提交到 Git）
API_KEY=sk-1234567890abcdef
```

---

## 4. 过度设计检查反例

### 反例 1: 为未来预留功能

**错误表现**：
```yaml
# config.yaml
output_formats:
  pdf:
    enabled: true
    engine: "reportlab"
  docx:
    enabled: false  # 未来可能支持
  html:
    enabled: false  # 未来可能支持
  markdown:
    enabled: false  # 未来可能支持
```

**问题**：当前只支持 PDF，其他格式不应硬编码

**正确做法**：
```yaml
# config.yaml
output_format: "pdf"  # 唯一支持的格式
# 未来需要时再添加
```

---

### 反例 2: 过度抽象

**错误表现**：
```python
class OutputFormatFactory:
    """输出格式工厂（当前只有一种格式）"""
    def create_formatter(self, format_type):
        if format_type == "pdf":
            return PDFFormatter()
        # 未来扩展点...

class PDFFormatter(AbstractFormatter):
    def format(self, data):
        # 实际上就是直接调用一个函数
        return convert_to_pdf(data)
```

**问题**：只有一种格式时，工厂和抽象层都是不必要的

**正确做法**：
```python
def format_output(data, output_path):
    """格式化输出为 PDF"""
    convert_to_pdf(data, output_path)
```

---

### 反例 3: 配置项过多

**错误表现**：
```yaml
# 本可以简单的功能，配置项却超过 20 个
processing:
  retries: 3
  retry_delay: 1.0
  retry_backoff: 2.0
  retry_jitter: true
  timeout:
    connect: 10
    read: 30
    total: 60
  validation:
    strict: true
    level: "high"
    custom_rules: []
  # ... 还有 10+ 个配置项
```

**问题**：大部分场景下这些值不需要改变

**正确做法**：
```yaml
# 只暴露真正需要配置的项
processing:
  timeout: 30  # 大部分场景够用
  retries: 3   # 大部分场景够用
# 其他值使用合理的默认值，硬编码在代码中
```

---

## 5. 通用性检查反例

### 反例 1: 年份限定

**错误表现**：
```markdown
## 功能说明
本 skill 用于处理 2024 年度 NSFC 申请书格式
```

**问题**：年份硬编码，2025 年就需要修改

**正确做法**：
```markdown
## 功能说明
本 skill 用于处理 NSFC 申请书格式（支持所有版本）
```

---

### 反例 2: 场景限定过窄

**错误表现**：
```markdown
## 适用场景
- 将 WeChat 文章同步到 Notion
```

**问题**：限制了平台，实际逻辑可通用化

**正确做法**：
```markdown
## 适用场景
- 将网页文章同步到笔记应用（支持 WeChat、Notion、Obsidian 等）
```

---

### 反例 3: 时间敏感示例

**错误表现**：
```markdown
## 示例
输入：`--date 2025-01-14`
输出：`report_20250114.pdf`
```

**问题**：示例日期会过时

**正确做法**：
```markdown
## 示例
输入：`--date {YYYY-MM-DD}`
输出：`report_{YYYYMMDD}.pdf`
```

---

### 反例 4: 不必要的品牌限定

**错误表现**：
```markdown
本 skill 专为 ChatGPT Plus 用户设计...
```

**问题**：限制了 AI 平台，实际功能通用

**正确做法**：
```markdown
本 skill 适用于各类 AI 助手平台（Claude、ChatGPT、Gemini 等）
```

---

## 6. 一致性检查反例

### 反例 1: YAML 与正文不一致

**错误表现**：
```yaml
---
name: pdf-merger
description: 合并多个 PDF 文件
---
```
```markdown
# SKILL.md
## 功能说明
本 skill 用于分割和提取 PDF 页面...
```

**问题**：YAML 说是合并，正文说是分割提取

**正确做法**：
```yaml
---
name: pdf-splitter
description: 分割和提取 PDF 页面
---
```

---

### 反例 2: 配置项不一致

**错误表现**：
```markdown
# SKILL.md
## 配置说明
- `output_dir`: 输出目录（默认：`output/`）
- `max_retries`: 最大重试次数（默认：3）
```
```yaml
# config.yaml
output:
  directory: "./output"
retries:
  max: 5  # 与文档中的默认值 3 不一致
```

**问题**：文档与配置不一致

**正确做法**：
```markdown
# SKILL.md
## 配置说明
详见 config.yaml 中的 `output.directory` 和 `retries.max`
```
```yaml
# config.yaml
output:
  directory: "./output"  # 默认输出目录
retries:
  max: 5  # 最大重试次数
```

---

### 反例 3: 示例与实际不一致

**错误表现**：
```markdown
# README.md
## 使用示例
/run pdf-merger --input file1.pdf,file2.pdf --output merged.pdf
```
```markdown
# SKILL.md（当前版本）
## 参数说明
- `--input`: 输入文件（支持目录和文件，非逗号分隔列表）
```

**问题**：README 中的语法是旧版本

**正确做法**：
```markdown
# README.md
## 使用示例
/run pdf-merger --input ./input_dir --output merged.pdf
```

---

### 反例 4: 术语不一致

**错误表现**：
```markdown
# 一处文档使用"测试会话"（session）
## 创建测试会话
v202601141900

# 另一处使用"测试轮次"（round）
## 测试轮次说明
第一轮测试...
```

**问题**：术语不统一

**正确做法**：
```markdown
# 统一使用"测试会话"（session）
## 创建测试会话
v202601141900

## 测试会话说明
第一个测试会话...
```

---

## 7. SKILL.md 瘦身检查反例

### 反例 1: 完整模板内容嵌入 SKILL.md

**错误表现**：
```markdown
# SKILL.md（臃肿）
## A 轮计划模板

## 测试 ID: {{TEST_ID}}
## 测试时间: {{CHECK_TIME}}
## ... 完整的 100 行模板内容 ...
```

**问题**：应引用 `references/A_ROUND_PLAN_TEMPLATE.md`

**正确做法**：
```markdown
# SKILL.md（精简）
## A 轮计划模板

详见 `references/A_ROUND_PLAN_TEMPLATE.md`
```

---

### 反例 2: 详细配置说明

**错误表现**：
```markdown
# SKILL.md（臃肿）
## 配置说明

### output_dir
- 类型：字符串
- 默认值："output/"
- 说明：指定输出目录的路径。可以是相对路径或绝对路径...
- 示例：output_dir: "./reports"

### max_retries
- 类型：整数
- 默认值：3
- 说明：最大重试次数。当操作失败时会自动重试...
- 示例：max_retries: 5

# ... 20+ 个配置项的详细说明
```

**问题**：应移至 config.yaml 注释

**正确做法**：
```markdown
# SKILL.md（精简）
## 配置说明

详见 config.yaml 中的注释说明。
```

```yaml
# config.yaml
# 输出目录（可包含环境变量，如：${HOME}/reports）
output_dir: "./output"

# 最大重试次数（0 表示不重试）
max_retries: 3
```

---

### 反例 3: 详细技术实现

**错误表现**：
```markdown
# SKILL.md（臃肿）
## 实现细节

### PDF 解析逻辑
使用 PyPDF2 库解析 PDF 文件。首先打开文件，然后逐页读取...
具体实现：[100 行技术说明]
```

**问题**：应移至 scripts/ 注释或独立技术文档

**正确做法**：
```markdown
# SKILL.md（精简）
## 实现细节

详见 `scripts/parse_pdf.py` 中的 docstring 和注释。
```

---

### 反例 4: 行数过多

**错误表现**：
```
SKILL.md: 500+ 行
references/: 空目录或只有 1-2 个文件
```

**问题**：SKILL.md 过于冗长

**正确做法**：
- SKILL.md 控制在 300 行以内
- 详细内容移至 references/
- 技术细节移至 scripts/ 注释
- 配置说明移至 config.yaml 注释

---

## 使用反例库进行问题发现

### 步骤 1: 快速扫描

浏览 skill 文件，对比反例库中的模式：
- 是否有"让 AI 手动操作"的模式？
- 是否有"为未来预留功能"的配置？
- 是否有"年份限定"的文档？

### 步骤 2: 深度验证

对发现的疑似问题，进一步验证：
- 这个配置项真的需要吗？
- 这个抽象真的有必要吗？
- 这个限定真的合理吗？

### 步骤 3: 记录问题

使用问题记录模板记录：
```
#### 问题 X: [反例名称]

**位置**: `文件:行号`

**反例类型**: [七大原则之一]

**问题描述**:
[具体描述问题现象，参考反例库]

**优先级**: P0/P1/P2

**修复建议**:
[参考反例库中的"正确做法"]

**验证方法**:
[如何确认修复成功]
```

---

**模板说明**：

本文档用于 auto-test-skill 快速识别常见问题。

使用时：
1. 熟悉七大原则的反例模式
2. 检查 skill 时对比反例库
3. 发现相似模式时记录为问题
4. 参考"正确做法"给出修复建议

# A 轮优化计划模板

**计划版本**: v{{TIMESTAMP}}
**制定时间**: {{PLAN_DATE}}
**当前版本**: {{CURRENT_VERSION}}
**目标技能**: {{TARGET_SKILL_NAME}}
**目标技能路径**: {{TARGET_SKILL_ROOT}}

---

## 第一部分：全局视图（必填）

### 我在优化 journey 的哪个阶段？

- [ ] **首轮分析**（理解现状 + 发现问题）
- [ ] **中间迭代**（逐项修复 + 渐进增强）
- [ ] **收尾阶段**（质量检查 + 文档完善）

**当前轮次**: A 轮 #{{ROUND_NUMBER}} / 共 {{TOTAL_ROUNDS}} 轮

### 本轮的批判性思维聚焦维度

⚠️ **必须选择至少一个聚焦维度**（从以下选择）：

- [ ] **系统架构**：工作流/配置/文件结构的设计合理性
- [ ] **过度设计**：不必要的抽象/配置/灵活性
- [ ] **一致性**：跨文件/跨文档的矛盾
- [ ] **安全性**：路径遍历/命令注入/信息泄露
- [ ] **边缘情况**：极端输入/恶意输入/隐式假设
- [ ] **用户体验**：可理解性/可预测性/错误恢复

**聚焦维度**: {{FOCUS_DIMENSION}}

### 与上轮的关联

**上轮输出**: {{PREV_ROUND_OUTPUT}}

**本轮延续**: {{CONTINUATION_FROM_PREV}}

**避免重复**: {{HISTORY_CHECK_RESULT}}

### 本轮解决的核心问题（一句话）

{{ONE_LINE_SUMMARY}}

---

## 第二部分：批判性思维分析（必填）

⚠️ **必须使用「刁钻角度」思考**（从 references/CRITICAL_THINKING_GUIDE.md 选择）：

### 选择的刁钻角度

- [ ] **边缘情况**: {{EXTREME_INPUT}} → {{EXTREME_ACTUAL}} → 应该是 {{EXTREME_EXPECTATION}}
- [ ] **恶意输入**: {{MALICIOUS_SCENARIO}} → 攻击向量 {{ATTACK_VECTOR}} → 当前防御 {{CURRENT_DEFENSE}}
- [ ] **隐式假设**: {{IMPLICIT_ASSUMPTION}} → 失效场景 {{ASSUMPTION_FAILURE_SCENARIO}}
- [ ] **自我质疑**: {{QUESTIONED_DESIGN}} → 质疑理由 {{REASON_FOR_QUESTIONING}}
- [ ] **跨文件矛盾**: 文件 A ({{FILE_A_STATEMENT}}) vs 文件 B ({{FILE_B_STATEMENT}}) → 是否矛盾 {{IS_CONTRADICTORY}}

### 发现的系统性问题

⚠️ **必须列出至少 3 个系统性问题**（架构/过度设计/一致/安全）：

1. {{SYSTEMIC_ISSUE_1}}
2. {{SYSTEMIC_ISSUE_2}}
3. {{SYSTEMIC_ISSUE_3}}

---

## 第三部分：问题清单（P0-P2）

### 优先级定义

| 优先级 | 定义 | 示例 |
|--------|------|------|
| **P0** | 阻塞性问题：不修复就无法继续；或安全风险 | 路径遍历漏洞、核心功能缺失 |
| **P1** | 重要优化：显著提升质量/安全性/可维护性 | 过度设计、冗余、不一致 |
| **P2** | 锦上添花：改进体验、完善细节 | 注释优化、代码风格 |

**数量要求**：
- P0 + P1 + P2 总和 ≥ 10
- P0 + P1 占比 ≥ 60%
- 系统性问题 ≥ 3 个

---

### P0（阻塞/安全/核心）

#### 问题 1: {{P0_1_TITLE}}

**位置**: `{{FILE}}:{{LINE}}`

**问题类型**: [架构设计/安全性/核心功能缺失]

**现象**:
{{P0_1_PHENOMENON}}

**影响**:
{{P0_1_IMPACT}}

**修复建议**:
{{P0_1_FIX}}

**验证方法**:
{{P0_1_VERIFY}}

---

### P1（重要优化）

#### 问题 1: {{P1_1_TITLE}}

**位置**: `{{FILE}}:{{LINE}}`

**问题类型**: [过度设计/冗余/不一致/用户体验]

**现象**:
{{P1_1_PHENOMENON}}

**影响**:
{{P1_1_IMPACT}}

**修复建议**:
{{P1_1_FIX}}

**验证方法**:
{{P1_1_VERIFY}}

---

### P2（锦上添花）

#### 问题 1: {{P2_1_TITLE}}

**位置**: `{{FILE}}:{{LINE}}`

**现象**:
{{P2_1_PHENOMENON}}

**修复建议**:
{{P2_1_FIX}}

**验证方法**:
{{P2_1_VERIFY}}

---

## 第四部分：问题质量检查（必填）

⚠️ **提交前必须确认**：

- [ ] **数量达标**: P0+P1+P2 ≥ 10，P0+P1 占比 ≥ 60%
- [ ] **系统问题**: 至少 3 个系统性问题（架构/过度设计/一致/安全）
- [ ] **位置精确**: 每个问题都有精确的 `文件:行号`
- [ ] **现象具体**: 每个问题都描述了具体现象（不是"应该XX"）
- [ ] **影响明确**: 每个问题都说明了"为什么重要"
- [ ] **修复具体**: 每个问题都有具体的修复方案（不是"建议优化"）
- [ ] **验证明确**: 每个问题都有可执行的验证方法
- [ ] **上下文连贯**: 与上轮的关联清晰
- [ ] **避免重复**: 没有重复历史问题

---

## 第五部分：执行计划（可选）

{{EXECUTION_PLAN}}

---

## 第六部分：完成后的下一轮预告

**预计下一轮聚焦**: {{NEXT_ROUND_FOCUS}}

**预计完成时间**: {{NEXT_ROUND_TIME}}

---

**模板说明**:

本模板用于 A 轮优化计划的生成。使用时：

1. **替换占位符**: 将 `{{VAR}}` 替换为实际内容
2. **删除不需要的章节**: 如某些章节不适用，可删除
3. **核心章节**: 第一部分（全局视图）+ 第二部分（批判性思维）+ 第三部分（问题清单）+ 第四部分（质量检查）必须完整

**关键原则**:

- **全局意识**: 每轮都明确自己在优化 journey 中的位置
- **批判性思维**: 必须使用"刁钻角度"思考
- **系统视角**: 必须发现至少 3 个系统性问题
- **问题质量**: 每个问题都必须有精确的位置、具体的修复方案、可执行的验证方法

**参考文档**:

- 批判性思维框架：`references/CRITICAL_THINKING_GUIDE.md`
- 问题挖掘技巧：`references/ISSUE_DISCOVERY_TECHNIQUES.md`
- 建设性建议标准：`references/CONSTRUCTIVE_SUGGESTION_GUIDELINES.md`
- 反例库：`references/ANTI_PATTERNS_LIBRARY.md`

# 代码审查与质量保证参考文档

## 审查流程

### 预审查阶段（自动化）

1. **运行自动化检查**
   ```bash
   # Linting
   eslint . || flake8 . || pylint src/

   # 类型检查
   tsc --noEmit || mypy src/

   # 安全扫描
   npm audit || snyk test || bandit -r src/

   # 测试
   pytest || npm test
   ```

2. **查看 CI/CD 结果**
   - 所有检查必须通过
   - 测试覆盖率不能下降
   - 性能基准测试通过

### 人工审查阶段

## 安全性检查（P0 - Critical）

### 注入攻击

- [ ] **SQL 注入**：使用参数化查询
  ```python
  # ❌ 易受攻击
  query = f"SELECT * FROM users WHERE name = '{user_input}'"

  # ✅ 安全
  query = "SELECT * FROM users WHERE name = ?"
  cursor.execute(query, [user_input])
  ```

- [ ] **命令注入**：避免直接拼接命令
  ```python
  # ❌ 危险
  os.system(f"cat {user_file}")

  # ✅ 安全
  subprocess.run(["cat", user_file], check=True)
  ```

- [ ] **XSS**：转义用户输入
  ```javascript
  // ❌ 危险
  div.innerHTML = userContent

  // ✅ 安全
  div.textContent = userContent
  ```

### 认证与授权

- [ ] **认证**：敏感操作需要身份验证
- [ ] **授权**：检查资源访问权限
- [ ] **会话管理**：适当的超时和注销

### 敏感数据处理

- [ ] **密钥管理**：不在代码中硬编码密钥
  ```python
  # ❌ 错误
  API_KEY = "sk-1234567890"

  # ✅ 正确
  API_KEY = os.getenv("API_KEY")
  ```

- [ ] **日志脱敏**：不在日志中记录敏感信息
  ```python
  # ❌ 错误
  logger.info(f"User login: {username}, password: {password}")

  # ✅ 正确
  logger.info(f"User login: {username}")
  ```

- [ ] **数据传输**：使用 HTTPS/TLS

### 加密与哈希

- [ ] **密码存储**：使用 bcrypt/argon2（非 MD5/SHA1）
- [ ] **敏感数据**：静态加密
- [ ] **随机数**：使用加密安全随机数生成器

## 性能检查（P1 - High）

### 数据库查询

- [ ] **N+1 查询问题**
  ```python
  # ❌ N+1 问题
  for order in orders:
      customer = db.query(Customer, order.customer_id)  # N 次查询

  # ✅ 使用 JOIN
  orders = db.query(Orders).join(Customer).all()
  ```

- [ ] **缺少索引**：查询字段应有索引
- [ ] **选择性查询**：避免 SELECT *

### 算法复杂度

- [ ] **时间复杂度**：关注嵌套循环
  ```python
  # ❌ O(n²)
  for item in items:
      if item in other_items:  # O(n) 查找
          pass

  # ✅ O(n)
  lookup = set(other_items)  # O(1) 查找
  for item in items:
      if item in lookup:
          pass
  ```

- [ ] **空间复杂度**：避免不必要的数据复制

### 缓存策略

- [ ] **重复计算**：缓存昂贵操作结果
- [ ] **缓存失效**：正确处理缓存更新
- [ ] **缓存穿透**：处理不存在的键

### 资源管理

- [ ] **连接池**：复用数据库/HTTP 连接
- [ ] **流式处理**：大文件使用流式读取
- [ ] **内存泄漏**：正确释放资源

## 可维护性检查（P2 - Medium）

### 代码复杂度

- [ ] **圈复杂度** ≤ 10（每函数）
- [ ] **嵌套深度** ≤ 4
- [ ] **函数长度** ≤ 50 行
- [ ] **参数数量** ≤ 5

### 命名规范

- [ ] **变量名**：描述性、小写下划线
  ```python
  # ❌ 不清晰
  d = calculate(u, p)

  # ✅ 清晰
  discount = calculate_discount(unit_price, quantity)
  ```

- [ ] **函数名**：动词开头，描述行为
- [ ] **类名**：名词，大驼峰
- [ ] **常量**：全大写下划线

### 代码重复

- [ ] **重复逻辑**：提取为函数
- [ ] **相似结构**：使用模板/泛型
- [ ] **魔法值**：定义为常量

### 注释与文档

- [ ] **复杂逻辑**：添加注释说明"为什么"
- [ ] **公共 API**：提供文档字符串
- [ ] **TODO/FIXME**：有跟踪 issue

```python
# ❌ 无意义注释
# 增加计数
count += 1

# ✅ 解释原因
# 使用计数器而不是 len()，因为列表可能为空且性能关键
count += 1
```

### 错误处理

- [ ] **异常捕获**：具体异常类型（不裸 except）
- [ ] **错误传播**：适当处理或重新抛出
- [ ] **错误消息**：提供有用的调试信息

```python
# ❌ 过于宽泛
try:
    process()
except:
    pass

# ✅ 具体且有意义
try:
    process()
except ValueError as e:
    logger.error(f"Invalid input: {e}")
    raise
```

## 测试覆盖（P1 - High）

- [ ] **单元测试**：核心逻辑有测试
- [ ] **边界条件**：测试空值、边界值
- [ ] **错误路径**：测试异常情况
- [ ] **集成测试**：关键流程有端到端测试

## 设计模式与架构（P2 - Medium）

### SOLID 原则

- [ ] **单一职责**：每个类/函数只做一件事
- [ ] **开闭原则**：对扩展开放，对修改封闭
- [ ] **里氏替换**：子类可替换父类
- [ ] **接口隔离**：接口专一，不臃肿
- [ ] **依赖倒置**：依赖抽象而非具体

### 耦合度

- [ ] **模块依赖**：单向依赖，无循环
- [ ] **全局状态**：避免使用全局变量
- [ ] **硬编码**：配置外部化

## 审查反馈模板

### 反馈格式

```markdown
## [P0/P1/P2] 问题类型

**位置**：[filename:line]

**问题**：简要描述问题

**风险/影响**：为什么这是个问题

**建议**：如何修复

**示例**（可选）：
```python
# 当前代码
...
# 建议代码
...
```

**优先级说明**：...
```

### 建设性反馈原则

1. **具体化**：指向具体代码位置
2. **解释原因**：说明为什么需要修改
3. **提供方案**：给出具体建议
4. **区分优先级**：P0（必须修复）vs P2（建议改进）
5. **正面反馈**：认可好的做法

## 审查检查清单总结

### 提交前自查

- [ ] 代码符合团队规范
- [ ] 自动化检查全部通过
- [ ] 自我审查完成
- [ ] 注释充分且准确
- [ ] 文档已更新
- [ ] 测试覆盖率不降低
- [ ] 无敏感信息泄露

### 审查人检查

- [ ] 安全性：无 P0 问题
- [ ] 性能：无 P1 问题
- [ ] 可维护性：P2 问题可接受
- [ ] 测试：核心功能有覆盖
- [ ] 整体：设计合理，易于理解

## 参考资源

- [Code Review (getsentry/code-review)](https://github.com/getsentry/sentry-skills)
- [Code Auditor (qdhenry/Claude-Command-Suite)](https://github.com/qdhenry/Claude-Command-Suite)
- [Find Bugs (getsentry/find-bugs)](https://github.com/getsentry/sentry-skills)

# 建设性建议标准

**文档版本**：v1.0.0
**创建时间**：2026-01-14
**用途**：为 auto-test-skill 提供"什么是建设性建议"的判断标准

---

## 核心定义

**建设性建议** = 具体可执行的改进方案，包含明确的修复路径和验证方法。

---

## ✅ 建设性建议的特征

### 1. 可执行

每条建议必须包含具体的修复方案，不是"应该改进XX"这种泛泛而谈。

**示例**：
- ❌ "建议增加更多日志"
- ✅ "在 `scripts/foo.py` 第 42 行的 `except` 块中，记录具体的异常类型和堆栈信息"

### 2. 有证据

每条建议必须基于具体文件/行号/代码，不是凭空猜测。

**示例**：
- ❌ "建议优化文档结构"
- ✅ "SKILL.md 第 30 行的描述与 config.yaml 第 15 行不一致，应统一为'XXX'"

### 3. 有价值

修复后能带来明显的质量提升（安全性/可维护性/用户体验）。

**示例**：
- ❌ "建议优化注释风格"（价值低）
- ✅ "建议增加路径遍历防御"（安全性提升）

### 4. 可验证

每条建议必须包含明确的验证方法，确认修复成功。

**示例**：
- ❌ "建议修复配置加载逻辑"
- ✅ "建议修复配置加载逻辑：验证方法 → 在 `tests/` 中运行空配置文件测试，确认有默认值回退"

---

## ❌ 非建设性建议的例子

### 类型 1：泛泛而谈

| ❌ 泛泛建议 | ✅ 建设性建议 |
|------------|--------------|
| "建议增加更多日志" | "在 `scripts/foo.py` 第 42 行的 `except` 块中，记录异常类型和堆栈" |
| "建议优化文档" | "SKILL.md 第 30 行与 config.yaml 第 15 行不一致，应统一为..." |
| "建议增强测试" | "缺少 `--dry-run` 参数的测试，应在 `tests/` 中增加验证用例" |
| "建议改进错误处理" | "第 88 行的 `except` 块捕获了所有异常但未记录，应细化为具体异常类型" |

### 类型 2：无具体位置

| ❌ 无位置建议 | ✅ 建设性建议 |
|--------------|--------------|
| "某个配置项没有说明" | "config.yaml 第 23 行的 `timeout` 项缺少单位说明，应补充为'秒'" |
| "代码中有重复逻辑" | "`scripts/bar.py` 第 105-110 行与第 145-150 行完全相同，应提取为函数" |
| "示例无法运行" | "README.md 第 18 行的示例命令缺少必需的 `--input` 参数" |

### 类型 3：价值不明确

| ❌ 价值不明确 | ✅ 建设性建议 |
|--------------|--------------|
| "建议统一注释风格" | "建议统一注释风格：当前混用 `#` 和 `//`，导致某些编辑器语法高亮失效" |
| "建议优化变量命名" | "建议优化变量命名：`tmp1`/`tmp2` 无法表达用途，改为 `input_path`/`output_path`" |
| "建议重构函数" | "建议重构 `process()` 函数：当前 200 行，包含 3 层嵌套，难以测试" |

### 类型 4：无验证方法

| ❌ 无验证方法 | ✅ 建设性建议 |
|--------------|--------------|
| "建议修复路径验证" | "建议修复路径验证：验证方法 → 构造输入 `../../etc/passwd`，确认被拒绝" |
| "建议增加默认值" | "建议增加默认值：验证方法 → 删除 config.yaml 中的该配置项，确认仍能运行" |
| "建议更新文档" | "建议更新文档：验证方法 → 按照文档步骤执行，确认能成功运行" |

---

## 建设性建议的"黄金公式"

```
位置 + 问题现象 + 影响分析 + 具体修复方案 + 验证方法
```

### 完整示例

**位置**：`scripts/validator.py:45-48`

**问题现象**：
```python
# 当前代码
if path.startswith("../"):
    raise ValueError("Invalid path")
```

**影响分析**：
- 只检查 `../` 前缀，无法防御 `..\\`（Windows）、`./../`、绝对路径绕过等攻击向量
- 存在路径遍历漏洞风险

**具体修复方案**：
```python
# 修复后代码
import os
resolved = os.path.realpath(path)
if not resolved.startswith(os.path.realpath(base_dir)):
    raise ValueError(f"Path {path} is outside base directory")
```

**验证方法**：
1. 构造恶意输入 `../../etc/passwd`，确认被拒绝
2. 构造绕过输入 `./../../etc/passwd`，确认被拒绝
3. 构造合法输入 `data/test.csv`，确认通过验证

---

## 建议质量自检清单

在提交建议前，确认每条建议都满足：

- [ ] **包含具体位置**：文件名 + 行号（如 `SKILL.md:30`）
- [ ] **包含修复方案**：不是"建议"而是"改为..."
- [ ] **包含验证方法**：如何确认修复成功
- [ ] **有明确价值**：能提升安全性/可维护性/用户体验
- [ ] **可独立执行**：不需要额外的上下文信息

---

## 常见反模式

### 反模式 1："应该"式建议

❌ "应该增加错误处理"
✅ "第 42 行缺少对 `FileNotFoundError` 的处理，应增加 `try-except` 块"

### 反模式 2："问题列表"式建议

❌ "问题：1) 无日志 2) 无测试 3) 无文档"
✅ 拆分为 3 条独立建议，每条都有位置和修复方案

### 反模式 3："模糊优化"式建议

❌ "建议优化性能"
✅ "第 88 行的循环嵌套复杂度为 O(n²)，建议改用字典降低到 O(n)"

### 反模式 4："假设用户会"式建议

❌ "建议用户先创建目录"
✅ "脚本应自动创建目录，而非假设用户已创建（见 `scripts/foo.py:55`）"

---

## 不同优先级的建议标准

### P0 建议（必须修复）

**特征**：
- 阻塞性问题：不修复就无法继续
- 安全风险：路径遍历、命令注入、敏感信息泄露
- 核心功能缺失：缺少关键功能、无法完成基本任务

**示例**：
- "存在路径遍历漏洞（`scripts/validator.py:45`），用户可访问任意文件"
- "缺少必需的配置项 `api_key`（`config.yaml`），导致脚本无法启动"

### P1 建议（强烈建议）

**特征**：
- 重要优化：显著提升质量/安全性/可维护性
- 测试覆盖不足：核心功能缺少测试
- 文档缺失：用户无法理解如何使用

**示例**：
- "缺少对 `--dry-run` 参数的测试（`tests/`），建议增加验证用例"
- "SKILL.md 第 30 行缺少步骤 2 的详细说明，用户无法正确执行"

### P2 建议（可选）

**特征**：
- 改进体验：提升可用性、易读性
- 完善细节：注释、代码风格、命名
- 后续迭代：不影响当前使用的改进

**示例**：
- "变量名 `tmp1`/`tmp2` 不够直观（`scripts/bar.py:105`），建议改为 `input_path`/`output_path`"
- "建议统一注释风格：当前混用 `#` 和 `//`（`scripts/*.py`）"

---

## 数量要求

根据 auto-test-skill 的要求：

- **每轮 A 轮**：至少 10 个问题（P0 + P1 + P2 总和），鼓励 15-20 个
- **B 轮检查**：至少 10-20 个建设性建议

**建议分布**（参考）：
- P0：2-4 个（如无严重问题，可少于 2 个）
- P1：4-8 个（重点）
- P2：4-8 个（锦上添花）

---

## 本轮建议质量检查

在提交建议前，回答以下问题：

1. **位置明确吗？** 每条建议都包含文件名和行号
2. **方案具体吗？** 每条建议都描述了"改为..."而非"建议..."
3. **可验证吗？** 每条建议都有明确的验证方法
4. **有价值吗？** 每条建议都能带来明显的质量提升
5. **数量达标吗？** 总数 ≥ 10，且 P0+P1 占比 ≥ 60%

---

**模板说明**：

本文档用于指导 auto-test-skill 生成高质量的建设性建议。

使用时：
1. 参考本文档的"黄金公式"撰写建议
2. 使用"建议质量自检清单"验证每条建议
3. 确保建议数量和优先级分布符合要求

# 上下文优化策略参考文档

## 核心问题

在长对话中，AI 代理的上下文窗口（context window）是有限的资源。不加以管理，会导致：

- **性能下降**：响应变慢，token 消耗增加
- **准确性降低**：关键信息被淹没，出现幻觉
- **成本增加**：更多的 token 意味着更高的 API 调用成本

## 上下文失败模式

### 失败模式 1：Lost-in-Middle（中间迷失）

**现象**：开头和结尾的信息能被记住，但中间的信息被遗忘。

**原因**：注意力的"U 型曲线"，AI 对中间内容的关注度降低。

**解决方案**：
- 关键信息放在开头或结尾
- 定期总结中间内容
- 使用引用而非重复内容

### 失败模式 2：Context Poisoning（上下文中毒）

**现象**：冲突或误导信息干扰 AI 判断。

**原因**：过时的信息、矛盾的指令、错误的假设。

**解决方案**：
- 明确标记过时信息（`[已废弃]`）
- 使用版本标记
- 清理冲突指令

### 失败模式 3：Distraction（注意力分散）

**现象**：无关信息浪费 token，降低相关性。

**原因**：加载了不必要的文件、过长的日志、冗余的代码。

**解决方案**：
- 只加载相关文件
- 使用摘要代替全文
- 清理无关内容

### 失败模式 4：Context Clash（上下文冲突）

**现象**：多个信息源提供冲突的信息。

**原因**：不同文件中的矛盾描述、更新不一致。

**解决方案**：
- 建立信息优先级
- 明确最后更新时间
- 冲突解决策略

## 优化策略

### 策略 1：压缩（Compression）

#### 压缩方式

| 方式 | 适用场景 | 示例 |
|------|---------|------|
| **总结** | 长文本、历史对话 | 将 100 行对话总结为 10 条要点 |
| **提取** | 关键决策、配置 | 提取 5 个关键参数 |
| **归档** | 已完成的任务 | 将已完成任务移至归档文件 |

#### 总结模板

```markdown
## 对话总结（截至 {timestamp}）

### 已完成的任务
1. ✅ 实现用户认证功能（2026-01-15 14:30）
2. ✅ 修复登录超时 Bug（2026-01-15 15:45）
3. ✅ 添加单元测试（2026-01-15 16:20）

### 关键决策
- 使用 JWT 而非 Session 认证
- 数据库选择 PostgreSQL 而非 MongoDB
- 测试框架选择 pytest

### 当前状态
正在实现：用户权限管理模块
进度：60%

### 遗留问题
1. 权限粒度设计待确认
2. RBAC 或 ABAC 模式未定

### 下一步行动
- 完成权限管理模块
- 编写权限测试
- 更新 API 文档
```

### 策略 2：掩码（Masking）

#### 按需加载

```markdown
## 核心说明

[简短的工作流程]

## 详细参考

详细信息请参阅：
- TDD 最佳实践：`tdd-best-practices.md`
- 调试指南：`debugging-systematic.md`
```

**原理**：SKILL.md 只包含核心信息，详细内容放在 references/ 中，按需加载。

#### 延迟加载

```python
# 不在上下文中立即加载大文件
def load_when_needed(file_path):
    """只有在实际需要时才加载"""
    if is_needed(file_path):
        return read_file(file_path)
    return None
```

### 策略 3：缓存（Caching）

#### 缓存策略

| 策略 | 描述 | 适用场景 |
|------|------|---------|
| **激进缓存** | 最大化重用，最小化重复读取 | 大型项目、有限 token |
| **适度缓存** | 平衡重用和新鲜度 | 一般场景 |
| **最小缓存** | 几乎不缓存，始终重新读取 | 快速变化的项目 |

#### 缓存实现

```python
# 简单缓存实现
_context_cache = {}

def get_file_content(file_path):
    """带缓存的文件读取"""
    if file_path in _context_cache:
        return _context_cache[file_path]

    content = read_file(file_path)
    _context_cache[file_path] = content
    return content

def invalidate_cache(file_path=None):
    """缓存失效"""
    if file_path:
        _context_cache.pop(file_path, None)
    else:
        _context_cache.clear()
```

### 策略 4：优先级管理（Prioritization）

#### 信息优先级

```
P0 - 必须保留（当前任务、关键决策）
P1 - 重要（配置、API 定义）
P2 - 可选（示例、注释）
P3 - 低优先（历史日志、调试信息）
```

#### 优先级示例

```markdown
## 优先级管理

### P0 - 当前任务
- 正在实现：用户权限管理

### P1 - 关键配置
- JWT_SECRET: ***
- DB_NAME: users_db

### P2 - 参考
- 权限设计文档：references/auth-design.md

### P3 - 历史
- 2026-01-14：完成认证模块（已归档）
```

## 实用技巧

### 技巧 1：分阶段处理

```
阶段 1：需求分析（只加载需求文档）
   ↓
阶段 2：设计（加载设计文档，卸载需求）
   ↓
阶段 3：实现（加载代码，卸载设计）
   ↓
阶段 4：测试（加载测试，卸载部分代码）
```

### 技巧 2：使用摘要代替全文

```python
# ❌ 加载整个配置文件
# （假设有 1000 行）

# ✅ 只加载需要的部分
config = load_config_section("database")
```

### 技巧 3：定期清理

```markdown
## 清理检查清单

每次完成一个任务后：
- [ ] 移除已完成的任务描述
- [ ] 归档历史对话
- [ ] 删除无关文件引用
- [ ] 更新当前状态
```

## 配置示例

### config.yaml 配置

```yaml
# 上下文优化配置
context:
  # 最大历史 token 数
  max_history_tokens: 8000

  # 压缩触发阈值（使用率达到 70% 时触发）
  compression_threshold: 0.7

  # 缓存策略
  cache_strategy: moderate  # aggressive | moderate | minimal

  # 压缩方式
  compression_method: summary  # summary | extract | archive

  # 信息保留优先级
  retention_priority:
    - "current_task"
    - "decisions"
    - "errors"
    - "context"

  # 自动清理
  auto_cleanup: true

  # 清理频率（每 N 轮对话）
  cleanup_frequency: 10
```

## 实战示例

### 示例 1：长对话压缩

```markdown
## 压缩前（5000 tokens）

[50 轮对话，包含详细讨论]

---

## 压缩后（500 tokens）

## 对话总结

### 已完成
1. ✅ 需求分析：用户认证系统
2. ✅ 技术选型：JWT + PostgreSQL
3. ✅ API 设计：/auth/login, /auth/register
4. ✅ 核心实现：认证服务

### 关键决策
- 使用 JWT 而非 Session（无状态）
- BCrypt 加密密码
- Token 有效期：24 小时

### 当前任务
正在实现：刷新 token 机制（进度 50%）

### 下一步
1. 完成刷新 token
2. 编写测试
3. 部署到测试环境
```

### 示例 2：按需加载参考文档

```markdown
## SKILL.md（核心信息，1000 tokens）

# Awesome Code

## 何时使用
[简要描述]

## 核心工作流
[概览]

## 详细参考

详细策略请参考：
- TDD 最佳实践：`tdd-best-practices.md`
- 调试指南：`debugging-systematic.md`

---

## references/tdd-best-practices.md（按需加载，3000 tokens）

# TDD 最佳实践

[详细的 TDD 指南]
```

## 监控与诊断

### 监控指标

```python
# 上下文使用监控
def monitor_context_usage():
    return {
        "total_tokens": count_tokens(),
        "usage_percentage": calculate_usage(),
        "compression_count": get_compression_count(),
        "cache_hit_rate": calculate_cache_hit_rate(),
    }
```

### 诊断检查清单

- [ ] 上下文使用率 < 80%
- [ ] 关键信息在开头或结尾
- [ ] 无明显的内容重复
- [ ] 引用文件正确加载
- [ ] 缓存命中率 > 50%

## 最佳实践

### 原则 1：渐进式信息披露

```
第一层：YAML frontmatter（name + description）
第二层：SKILL.md 核心内容
第三层：references/ 详细参考
```

### 原则 2：定期维护

- 每完成一个任务：清理一次
- 每 10 轮对话：压缩一次
- 每天开始：归档前一天的内容

### 原则 3：可观测性

- 记录压缩决策
- 记录缓存命中率
- 记录 token 使用趋势

## 参考资源

- [Context Engineering Skills (muratcankoylan)](https://github.com/VoltAgent/awesome-claude-skills)
- [Claude Code: Best practices for agentic coding](https://www.anthropic.com/engineering/claude-code-best-practices)
- [Equipping Agents for the Real World with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)

# Context Window 管理优化指南

**版本**: v2.1.0
**最后更新**: 2026-01-17

---

## 概述

本指南描述了 Awesome Code 技能中的 Context Window 管理优化策略，旨在解决长对话中的性能和准确性问题。

---

## 常见问题

### Lost-in-Middle 现象

关键信息被中间内容淹没，AI 无法准确定位重要上下文。

**症状**:
- AI 重复询问已提供的信息
- 忽略早期的指令或约束
- 生成的内容与上下文矛盾

**解决方案**:
1. 使用压缩策略总结历史对话
2. 提取关键决策并持久化
3. 归档已完成任务

### Context Poisoning

冲突或误导信息干扰 AI 判断。

**症状**:
- AI 在矛盾信息间摇摆
- 生成的内容不符合最新要求
- 无法区分当前和过时信息

**解决方案**:
1. 使用掩码策略只加载相关文件
2. 分阶段处理任务，避免信息混乱
3. 明确标记信息的时效性

### Token 浪费

无关信息消耗宝贵的 token 预算。

**症状**:
- 对话早期就达到 token 限制
- 加载了大量不相关的文档
- 重复加载相同内容

**解决方案**:
1. 实现智能缓存机制
2. 按需加载详细引用
3. 使用摘要代替全文

---

## 优化策略

### 1. 压缩策略

#### 对话摘要

将历史对话压缩为结构化摘要：

```markdown
## 对话摘要 (v202601171420)

### 关键决策
- 采用 TDD 工作流开发登录功能
- 使用 pytest 作为测试框架
- 目标测试覆盖率 ≥ 80%

### 已完成任务
- [x] 编写登录功能的失败测试
- [x] 实现基本的用户认证

### 待办任务
- [ ] 添加密码强度验证
- [ ] 实现记住登录状态

### 约束条件
- 必须使用 bcrypt 加密密码
- 禁止存储明文密码
```

#### 决策提取

提取并持久化关键决策：

```python
@dataclass
class Decision:
    """关键决策记录"""
    id: str
    timestamp: datetime
    topic: str
    decision: str
    rationale: str
    implications: List[str]
```

#### 归档已完成任务

将已完成的任务移至归档：

```
当前对话: 最近 5 轮
短期归档: 最近 20 轮（摘要形式）
长期归档: 更早内容（仅关键决策）
```

---

### 2. 掩码策略

#### 按需加载文件

只加载与当前任务相关的文件：

```python
def load_relevant_files(
    task: Task,
    all_files: List[Path],
    relevance_threshold: float = 0.3,
) -> List[Path]:
    """基于任务相关性加载文件"""
    relevant_files = []
    for file_path in all_files:
        relevance = calculate_relevance(task, file_path)
        if relevance >= relevance_threshold:
            relevant_files.append(file_path)
    return relevant_files
```

#### 延迟加载详细引用

第一阶段只加载摘要，按需加载详细内容：

```markdown
## 参考文档索引

| 文档 | 摘要 | 详见 |
|------|------|------|
| TDD 最佳实践 | TDD 工作流指南 | `tdd-best-practices.md` |
| 代码审查清单 | 代码质量检查项 | `code-review-checklist.md` |
```

#### 分阶段处理

将大型任务分解为阶段，每阶段只关注相关上下文：

```
阶段 1: 需求分析（只加载需求相关文档）
阶段 2: 设计方案（只加载设计相关文档）
阶段 3: 实现编码（只加载代码相关文档）
阶段 4: 测试验证（只加载测试相关文档）
```

---

### 3. 缓存策略

#### 重用已解析信息

缓存解析后的配置、AST 等结构化数据：

```python
@file_cache(ttl_seconds=3600)
def parse_config(config_path: Path) -> Dict:
    """解析配置文件（带缓存）"""
    return yaml.safe_load(config_path.read_text())
```

#### 避免重复读取文件

使用文件哈希作为缓存键：

```python
@file_cache(key_func=lambda path: hashlib.md5(path.read_bytes()).hexdigest())
def analyze_code(path: Path) -> AnalysisResult:
    """分析代码（只在文件变更时重新分析）"""
    ...
```

#### 使用摘要代替全文

对于大型文件，存储和传输摘要而非全文：

```python
def get_file_summary(file_path: Path) -> str:
    """获取文件摘要"""
    content = file_path.read_text()
    # 如果文件很小，返回全文
    if len(content) < 1000:
        return content
    # 否则返回摘要
    return summarize_content(content)
```

---

## 实现指南

### Token 监控

实时监控 token 使用情况：

```python
class TokenMonitor:
    """Token 使用监控器"""

    def __init__(self, limit: int = 100000):
        self.limit = limit
        self.usage = 0
        self.warning_threshold = int(limit * 0.7)

    def add_tokens(self, count: int) -> None:
        """增加 token 计数"""
        self.usage += count
        if self.usage >= self.warning_threshold:
            self.warn_threshold_exceeded()

    def warn_threshold_exceeded(self) -> None:
        """警告阈值超出"""
        usage_pct = self.usage / self.limit * 100
        print(f"⚠️ Token 使用率: {usage_pct:.1f}%")

    def should_compress(self) -> bool:
        """判断是否需要压缩"""
        return self.usage >= self.warning_threshold
```

### 自动清理机制

达到阈值时自动清理过时上下文：

```python
def auto_compress_context(
    messages: List[Message],
    token_monitor: TokenMonitor,
) -> List[Message]:
    """自动压缩上下文"""
    if not token_monitor.should_compress():
        return messages

    # 保留最近 N 轮对话
    recent_messages = messages[-10:]

    # 压缩较早的对话为摘要
    older_messages = messages[:-10]
    summary = compress_messages_to_summary(older_messages)

    # 返回压缩后的消息列表
    return [summary] + recent_messages
```

### 分级加载策略

实现三级文件加载：

```python
class FileLoader:
    """分级文件加载器"""

    def __init__(self):
        self.l1_cache: Dict[Path, str] = {}  # 热数据
        self.l2_cache: Dict[Path, str] = {}  # 温数据（摘要）
        self.l3_storage: Dict[Path, str] = {}  # 冷数据（索引）

    def load_file(self, path: Path, level: str = "auto") -> str:
        """加载文件"""
        if level == "auto":
            level = self._determine_load_level(path)

        if level == "l1":
            return self._load_full(path)
        elif level == "l2":
            return self._load_summary(path)
        else:
            return self._load_index(path)

    def _determine_load_level(self, path: Path) -> str:
        """自动判断加载级别"""
        # 基于文件大小、访问频率、相关性等判断
        ...
```

---

## 配置建议

在 `config.yaml` 中添加以下配置：

```yaml
# Context Window 管理配置
context:
  # 最大历史 token 数
  max_history_tokens: 8000

  # 压缩触发阈值（使用率百分比）
  compression_threshold: 0.7

  # 缓存策略：aggressive | moderate | minimal
  cache_strategy: moderate

  # 压缩方式：summary | extract | archive
  compression_method: summary

  # 信息保留优先级
  retention_priority:
    - "current_task"
    - "decisions"
    - "errors"
    - "context"

  # 自动清理开关
  auto_cleanup: true

  # Token 监控告警阈值
  warning_threshold: 0.7
  critical_threshold: 0.9
```

---

## 最佳实践

### 对话开始时

1. 明确任务范围和边界
2. 识别可能需要的参考文档
3. 设置合理的 token 预算

### 对话进行中

1. 定期检查 token 使用情况
2. 及时归档已完成任务
3. 提取并记录关键决策

### 对话结束时

1. 生成完整的对话摘要
2. 保存重要的决策和约束
3. 清理临时缓存

---

## 工具支持

### Context 诊断命令

```bash
# 查看当前 token 使用情况
ac-context status

# 手动压缩上下文
ac-context compress

# 查看缓存统计
ac-context cache-stats

# 清理过期缓存
ac-context cleanup
```

### 日志输出

```
[Context] Token usage: 6500/100000 (6.5%)
[Context] Cache hit rate: 85%
[Context] Compression not needed
```

---

**相关参考**:
- `context-optimization.md`
- [scripts/cache.py](../scripts/cache.py)
- [scripts/logger.py](../scripts/logger.py)

# 批判性思维指南

**文档版本**：v1.0.0
**创建时间**：2026-01-16
**用途**：为 auto-test-skill 提供「如何进行批判性思考」的思考框架

---

## 核心思想

**批判性思维** ≠ 找茬
= 系统性质疑 + 多角度验证 + 边缘情况探索 + 深度挖掘

本文档提供**三大思考框架**，帮助 AI 在每轮 A 轮中发现真正有价值的问题。

---

## 框架 1: 系统视角思考

### 目的
避免"盲人摸象"，从**系统架构**层面审视技能的设计合理性。

### 思考维度

#### 维度 1: 这个技能的核心价值是什么？

**自问清单**：
- 这个技能要解决的核心问题是什么？
- 当前设计是否真的解决了这个问题？
- 是否有更简单的解决方案？

**高质量问题示例**：
```
问题：auto-test-skill 的核心价值是"发现系统性问题"，
但当前工作流只要求"列出 10 个问题"，没有区分"表面问题"vs"深层问题"。
位置：SKILL.md:87-90（问题数量要求）
优先级：P0
修复：增加"问题深度检查"，要求每轮至少 3 个"系统性问题"
```

#### 维度 2: 工作流的每个步骤都必要吗？

**自问清单**：
- 这个步骤是否真正贡献于最终目标？
- 删除这个步骤会怎样？
- 能否合并相似步骤？

**高质量问题示例**：
```
问题：工作流包含"执行优化"和"轻量测试"两个独立步骤，
但"优化"的本质就是"验证修复效果"，两者重叠。
位置：SKILL.md:105-115
优先级：P1
修复：合并为"修复并验证"步骤，减少文档冗余
```

#### 维度 3: 配置项真的需要可配置吗？

**自问清单**：
- 这个配置项在不同使用场景下会有不同值吗？
- 如果只有一个合理值，为什么还要配置？
- 硬编码会失去什么灵活性？

**高质量问题示例**：
```
问题：output_format 配置项只有 "json" 一个有效值（无其他格式支持），
过度配置化，增加理解成本。
位置：config.yaml:30
优先级：P1
修复：移除配置项，直接硬编码为 "json"
```

#### 维度 4: 文件结构反映了什么样的设计理念？

**自问清单**：
- 目录结构是否清晰传达了技能的用途？
- 是否存在"职责不清"的文件？
- 文件之间的依赖关系是否合理？

**高质量问题示例**：
```
问题：references/ 目录下混合了"模板"和"指南"两类文档，
但没有清晰的命名区分，难以快速定位。
位置：references/
优先级：P2
修复：重命名文件，添加前缀：TEMPLATE_*.md vs GUIDE_*.md
```

---

## 框架 2: 刁钻角度思考

### 目的
通过**极端情况、恶意输入、隐式假设**等刁钻角度，发现隐藏问题。

### 角度 1: 边缘情况压力测试

**测试场景矩阵**：

| 输入类型 | 正常输入 | 边缘输入 | 极端输入 | 恶意输入 |
|----------|----------|----------|----------|----------|
| **路径** | `data/test.csv` | `path with spaces` | `""` (空字符串) | `../../etc/passwd` |
| **配置** | 完整 YAML | `{}` (空配置) | `timeout: -1` (非法值) | 恶意 YAML 注入 |
| **文件** | 1MB 文件 | 0 字节文件 | 10GB 文件 | 特殊字符文件 (`\n`, `\0`) |

**高质量问题示例**：
```
问题：路径验证只检查 `../` 前缀，无法防御 `./../` 绕过攻击。
攻击向量：用户输入 `./../../etc/passwd` 可访问任意文件
位置：scripts/validator.py:45
优先级：P0
修复：使用 os.path.realpath() 规范化后再验证
验证：构造输入 `./../../etc/passwd`，确认被拒绝
```

### 角度 2: 恶意用户测试

**攻击场景清单**：
1. **路径遍历**：能否访问 `../../etc/passwd`？
2. **命令注入**：能否通过 `; rm -rf /` 执行任意命令？
3. **资源耗尽**：能否通过超大文件（>1GB）耗尽内存？
4. **并发竞态**：能否通过同时修改配置文件破坏系统？
5. **符号链接攻击**：能否通过 symlink 读取敏感文件？

**高质量问题示例**：
```
问题：未验证符号链接，用户可创建 symlink 到 `/etc/passwd`，
脚本会跟随 symlink 读取敏感文件。
位置：scripts/reader.py:34
优先级：P0
修复：验证解析后的路径是否在 base_dir 内
验证：创建 symlink 到敏感文件，确认被拒绝
```

### 角度 3: 隐式假设识别

**关键词搜索**（发现未验证的假设）：
- `应该` → 通常意味着"实际上没做"
- `会` → 通常意味着"假设会发生"
- `自动` → 通常意味着"没有验证"
- `用户` → 通常意味着"假设用户会做某事"

**高质量问题示例**：
```
问题："用户应先创建目录" → 假设用户会手动创建目录，
但实际不会，导致脚本失败。
位置：SKILL.md:55
优先级：P1
修复：脚本应自动创建目录（见 scripts/setup.py:12）
验证：在空目录运行脚本，确认自动创建目录
```

### 角度 4: 自我质疑法

**对每个设计决策问**：
- "这个设计真的有用吗？还是'自我感动'？"
- "有更简单的实现方式吗？"
- "这个配置项真的需要吗？"

**高质量问题示例**：
```
问题：session_format 配置项使用复杂的 Jinja2 模板语法
（`v{year}{month}{day}{hour}{minute}`），但实际只有一个固定格式。
位置：config.yaml:24
优先级：P1
修复：移除配置项，直接使用 Python datetime 格式化
理由：过度设计，增加理解成本
```

---

## 框架 3: 问题质量标准

### 目的
避免"凑够 10 个问题"，确保每个问题都有**真正的价值**。

### 黄金标准

每个问题必须满足：

```
位置 + 现象 + 影响（为什么重要） + 修复方案 + 验证方法
```

### 质量检查清单

在提交问题前，确认每条问题都满足：

#### 检查 1: 位置精确吗？
- ❌ "某个配置项没有说明"
- ✅ "config.yaml 第 23 行的 `retry_delay` 配置项缺少说明"

#### 检查 2: 现象具体吗？
- ❌ "建议增加错误处理"
- ✅ "第 42 行缺少对 `FileNotFoundError` 的处理，文件不存在时会崩溃"

#### 检查 3: 影响明确吗？
- ❌ "影响用户体验"
- ✅ "用户无法恢复错误，只能重新运行整个流程"

#### 检查 4: 修复方案具体吗？
- ❌ "建议优化文档"
- ✅ "在 config.yaml 第 23 行增加注释：`# 重试延迟（秒）`"

#### 检查 5: 验证方法明确吗？
- ❌ "验证修复成功"
- ✅ "构造输入 `../../etc/passwd`，确认被拒绝"

---

## 问题优先级判定

### P0（阻塞/安全/核心）

**特征**：
- 不修复就无法使用
- 存在安全风险（路径遍历、命令注入、信息泄露）
- 核心功能缺失

**示例**：
```
问题：存在路径遍历漏洞，用户可访问任意文件
位置：scripts/validator.py:45
优先级：P0
理由：安全风险，可能泄露敏感信息
```

### P1（重要优化）

**特征**：
- 显著提升质量/安全性/可维护性
- 影响核心工作流
- 过度设计/冗余/不一致

**示例**：
```
问题：output_format 配置项只有一个有效值，过度设计
位置：config.yaml:30
优先级：P1
理由：增加理解成本，无实际灵活性
```

### P2（锦上添花）

**特征**：
- 改进体验、完善细节
- 不影响核心功能
- 后续迭代

**示例**：
```
问题：变量名 `tmp1` 不够直观
位置：scripts/bar.py:105
优先级：P2
理由：不影响功能，但影响可读性
```

---

## 数量要求（强制）

### A 轮要求

**最低要求**（不满足则继续挖掘）：
- P0 + P1 + P2 总和 ≥ 10
- P0 + P1 占比 ≥ 60%

**推荐分布**：
- P0：2-4 个（系统性问题、安全风险）
- P1：4-8 个（过度设计、冗余、一致性）
- P2：3-6 个（细节优化）

### 系统性问题专项要求

**每轮必须包含至少 3 个"系统性问题"**：

| 系统性问题类型 | 定义 | 示例 |
|---------------|------|------|
| **架构设计问题** | 工作流/配置/文件结构层面的设计缺陷 | "工作流步骤重叠，无明确职责分工" |
| **过度设计问题** | 不必要的抽象/配置/灵活性 | "只有一个值的配置项" |
| **一致性问题** | 跨文件/跨文档的矛盾 | "SKILL.md 说 X，config.yaml 说 Y" |
| **安全性问题** | 路径遍历/命令注入/信息泄露 | "未验证符号链接" |

---

## 批判性思维检查清单

### 在提交 A 轮计划前，确认：

- [ ] **系统视角**：是否从架构层面审视设计合理性？
- [ ] **刁钻角度**：是否测试了边缘情况、恶意输入、隐式假设？
- [ ] **问题质量**：每个问题都包含位置+现象+影响+修复+验证吗？
- [ ] **优先级合理**：P0/P1 占比 ≥ 60% 吗？
- [ ] **系统性问题**：至少 3 个系统性问题（架构/过度设计/一致/安全）吗？
- [ ] **上下文连贯**：与上轮的关联清晰吗？
- [ ] **避免重复**：没有重复历史问题吗？

---

## 高质量问题示例库

### 示例 1: 系统性架构问题

```
问题：auto-test-skill 的核心价值是"发现系统性问题"，
但当前工作流只要求"列出 10 个问题"，没有区分"表面问题"vs"深层问题"。

位置：SKILL.md:87-90（问题数量要求）

问题类型：架构设计问题

现象：
工作流只规定了问题数量（≥ 10），未规定问题质量，
导致 AI 倾向于列出"不痛不痒"的表面问题（如"缺少注释"）。

影响：
技能无法实现"发现系统性问题"的核心价值，
沦为"表面问题列表生成器"。

优先级：P0

修复建议：
在 SKILL.md 第 87-90 行增加"问题深度要求"：
```
### 问题深度要求（强制）
每轮必须包含至少 3 个"系统性问题"：
- 架构设计问题（工作流/配置/文件结构）
- 过度设计问题（不必要的抽象/配置）
- 一致性问题（跨文件矛盾）
- 安全性问题（路径遍历/命令注入）
```

验证方法：
执行 3 轮 A 轮测试，确认每轮都包含至少 3 个系统性问题。
```

### 示例 2: 过度设计问题

```
问题：session_format 配置项使用复杂的 Jinja2 模板语法，
但实际只有一个固定格式。

位置：config.yaml:24

问题类型：过度设计问题

现象：
```yaml
session_format: "v{year}{month}{day}{hour}{minute}"
```
这个配置项看似"灵活"，但实际上：
1. 没有其他格式选项
2. 用户不需要自定义时间戳格式
3. 增加 YAML 解析复杂度（需要 Jinja2 引擎）

影响：
- 过度设计，增加理解成本
- 增加 YAML 解析复杂度
- 无实际灵活性

优先级：P1

修复建议：
移除 session_format 配置项，直接使用 Python datetime 格式化：
```python
# scripts/create_test_session.py
session_id = datetime.now().strftime("v%Y%m%d%H%M")
```

验证方法：
1. 删除 config.yaml 中的 session_format
2. 运行 scripts/create_test_session.py
3. 确认生成的 session_id 格式为 v202601161200
```

### 示例 3: 安全性问题

```
问题：路径验证只检查 `../` 前缀，无法防御绕过攻击。

位置：scripts/validator.py:45-48

问题类型：安全性问题

现象：
```python
if path.startswith("../"):
    raise ValueError("Invalid path")
```
只检查 `../` 前缀，但以下攻击向量可绕过：
- `./../etc/passwd`
- `.././../etc/passwd`
- 绝对路径 `/etc/passwd`
- Windows: `..\\..\\windows\\system32`

影响：
存在路径遍历漏洞，用户可访问任意文件，
包括敏感信息（如 `/etc/passwd`、`~/.ssh/id_rsa`）。

优先级：P0

修复建议：
```python
import os

resolved = os.path.realpath(path)
base_dir = os.path.realpath("./data")

if not resolved.startswith(base_dir):
    raise ValueError(f"Path {path} is outside base directory")

return resolved
```

验证方法：
1. 构造输入 `./../../etc/passwd`，确认被拒绝
2. 构造输入 `.././../etc/passwd`，确认被拒绝
3. 构造输入 `data/test.csv`，确认通过
```

---

## 使用指南

### 何时使用本文档？

在执行 A 轮测试时，按以下顺序使用：

1. **开始前**：阅读「框架 1: 系统视角思考」，建立全局意识
2. **分析时**：使用「框架 2: 刁钻角度思考」，挖掘隐藏问题
3. **评估时**：使用「框架 3: 问题质量标准」，确保问题价值
4. **提交前**：使用「批判性思维检查清单」，最后把关

### 组合使用技巧

为达到 10-20 个高质量问题，建议组合使用：

1. **系统视角**（框架 1）→ 发现 3-5 个系统性问题（P0/P1）
2. **刁钻角度**（框架 2）→ 发现 3-5 个安全性/边缘问题（P0/P1）
3. **常规检查**（ISSUE_DISCOVERY_TECHNIQUES.md）→ 发现 4-8 个细节问题（P1/P2）

**总计**：10-18 个问题，P0+P1 占比 ≥ 60%

---

**模板说明**：

本文档是 auto-test-skill 的核心思考指南。

使用时：
1. 每轮 A 轮开始前，快速浏览三大框架
2. 挖掘问题时，对照框架检查是否遗漏重要角度
3. 提交前，使用检查清单最后把关

# 系统化调试与根因分析参考文档

## 核心理念

系统化调试不是猜测，而是**科学方法在软件调试中的应用**：观察 → 假设 → 实验 → 结论。

## 调试流程

### 第一步：收集证据（信息收集）

#### 必需信息

- [ ] **完整堆栈追踪**（不只是最后一行）
- [ ] **错误消息**（完整文本，包括错误代码）
- [ ] **复现步骤**（最小可复现示例）
- [ ] **环境信息**（OS、语言版本、依赖版本）
- [ ] **相关日志**（错误发生前后的日志）
- [ ] **最近变更**（代码、配置、依赖）

#### 堆栈追踪分析模板

```python
# 示例：分析堆栈追踪
Traceback (most recent call last):
  File "app.py", line 42, in process_order       # ← 错误入口
  File "services/payment.py", line 15, in charge  # ← 调用链
  File "utils/api.py", line 78, in request        # ← 失败点
ConnectionError: Failed to connect to payment-gateway.com

分析：
1. 错误类型：ConnectionError（网络连接失败）
2. 失败位置：utils/api.py:78
3. 业务上下文：处理订单的支付流程
4. 可能原因：网络问题、服务宕机、DNS 解析失败
```

### 第二步：形成假设（假设驱动）

#### 假设格式

使用 **"因为...，所以..."** 结构：

```
假设：因为 API endpoint URL 配置错误，所以请求发送到错误的服务器。
      因为支付网关服务宕机，所以连接被拒绝。
      因为网络防火墙阻止出站连接，所以请求超时。
```

#### 假设优先级排序

| 优先级 | 类型 | 示例 |
|-------|------|------|
| P0 | 最近变更 | 昨天部署的代码引入的 Bug |
| P1 | 配置问题 | 环境变量设置错误 |
| P2 | 外部依赖 | 第三方 API 服务异常 |
| P3 | 边界条件 | 特殊输入触发的罕见逻辑 |

### 第三步：系统性验证（实验设计）

#### 一次验证一个假设

```python
# ❌ 错误：同时验证多个假设
def test_hypothesis():
    change_config()
    restart_service()
    update_dependency()
    assert works()  # 哪个修改起作用？

# ✅ 正确：隔离变量
def test_config_hypothesis():
    only_change_config()
    assert works()

def test_service_hypothesis():
    only_restart_service()
    assert works()
```

#### 二分查找法

```python
def binary_search_bug():
    # 确定是否有问题
    if bug_exists():
        # 确定时间范围
        old_version = "v1.0.0"  # 无问题
        new_version = "v1.5.0"  # 有问题

        # 二分查找引入问题的版本
        mid = bisect_versions(old_version, new_version)
        # 缩小范围，最终定位到具体 commit
```

### 第四步：定位根因（区分症状与原因）

#### 根因分析方法：五问法（5 Whys）

```
问题：用户登录失败

问1：为什么登录失败？
答：因为数据库查询超时。

问2：为什么数据库查询超时？
答：因为用户表没有索引。

问3：为什么没有索引？
答：因为迁移脚本没有执行。

问4：为什么迁移脚本没有执行？
答：因为部署流程中缺少迁移步骤。

问5：为什么部署流程缺少迁移步骤？
答：因为部署文档没有更新。

根本原因：部署文档不完整（而非数据库慢）
```

#### 症状 vs 根因对比

| 症状 | 根因 |
|------|------|
| 页面加载慢 | N+1 查询问题 |
| 内存溢出 | 缓存未设置过期时间 |
| 数据丢失 | 事务未正确提交 |
| 偶发性错误 | 并发竞争条件 |

### 第五步：实施修复（最小化原则）

#### 修复策略

1. **最小化修复**：只修改必要的代码
2. **添加测试**：防止回归
3. **文档更新**：记录决策和教训
4. **验证修复**：多环境测试

#### 修复示例

```python
# ❌ 过度修复
def fix_bug():
    # 修改整个函数结构
    # 引入新依赖
    # 重构相关代码
    # ...（风险高）

# ✅ 最小化修复
def fix_bug():
    # 只修复特定问题
    if critical_condition:
        return safe_default  # 防御性编程
    # 保持原有逻辑不变
```

## 常见调试模式

### 模式 1：日志驱动的调试

```python
import logging

# 配置结构化日志
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

logger = logging.getLogger(__name__)

def process_order(order):
    logger.info(f"Processing order: {order.id}")

    try:
        result = payment_service.charge(order.amount)
        logger.info(f"Payment successful: {result.transaction_id}")
        return result

    except PaymentError as e:
        logger.error(f"Payment failed for order {order.id}: {e}")
        logger.debug(f"Order details: {order.to_dict()}")
        raise
```

### 模式 2：断言驱动的调试

```python
def calculate_discount(customer, cart):
    # 前置条件断言
    assert customer is not None, "Customer cannot be None"
    assert cart.total > 0, "Cart total must be positive"

    discount_rate = customer.discount_rate

    # 不变式断言
    assert 0 <= discount_rate <= 1, f"Invalid discount rate: {discount_rate}"

    final_price = cart.total * (1 - discount_rate)

    # 后置条件断言
    assert final_price >= 0, "Final price cannot be negative"
    assert final_price <= cart.total, "Discount cannot exceed total"

    return final_price
```

### 模式 3：二分定位法

```python
def locate_bug_position():
    # 确定问题范围
    if works_in_isolation():
        # 问题在交互逻辑
        if works_with_simplified_inputs():
            # 问题在边界条件
            test_edge_cases()
        else:
            # 问题在基本逻辑
            test_core_functionality()
    else:
        # 问题在单元内部
        test_dependencies()
```

## 生产环境调试

### 远程调试原则

- [ ] **只读优先**：先查询，不修改
- [ ] **最小权限**：使用只读凭证
- [ ] **审计日志**：记录所有操作
- [ ] **灰度验证**：先在测试环境验证

### 安全检查清单

在生产环境调试前确认：

- [ ] 有授权（运维批准）
- [ ] 有监控（告警通知）
- [ ] 有回滚计划
- [ ] 非高峰时段
- [ ] 数据已备份

## 调试完成检查清单

- [ ] 根本原因已识别（非症状）
- [ ] 修复方案最小化
- [ ] 添加回归测试
- [ ] 文档已更新（注释、README）
- [ ] 代码审查完成
- [ ] 多环境验证通过
- [ ] 监控告警正常
- [ ] 团队分享（如需要）

## 参考资源

- [Systematic Debugging (obra/systematic-debugging)](https://github.com/VoltAgent/awesome-claude-skills)
- [Root Cause Tracing (obra/root-cause-tracing)](https://github.com/VoltAgent/awesome-claude-skills)
- [9 Ways Claude Code Helps Me with Testing and Debugging](https://medium.com/@joe.njenga/9-ways-claude-code-helps-me-with-testing-and-debugging-like-a-pro-tester-69c8776282ab)

# Git 工作流参考文档

## Conventional Commits 规范

### 提交格式

```
<type>(<scope>): <subject>

<body>

<footer>
```

### Type 类型

| Type | 说明 | 示例 |
|------|------|------|
| `feat` | 新功能 | feat(auth): add OAuth2 login support |
| `fix` | Bug 修复 | fix(payment): resolve race condition in refund |
| `docs` | 文档变更 | docs(api): update authentication endpoints |
| `style` | 代码格式（不影响功能） | style: fix indentation in utils.py |
| `refactor` | 重构（不是新功能也不是修复） | refactor(database): extract query builder |
| `perf` | 性能优化 | perf(cache): implement Redis caching layer |
| `test` | 测试相关 | test(auth): add login validation tests |
| `chore` | 构建/工具变更 | chore: upgrade to Node.js 20 |
| `ci` | CI 配置 | ci: add GitHub Actions workflow |

### Subject 规则

- 使用现在时态（"add" 而非 "added"）
- 首字母小写
- 不以句号结尾
- 不超过 50 字符

### Body 规则（可选）

- 包含"什么"和"为什么"
- 每行 ≤ 72 字符
- 解释动机而非代码

### Footer 规则（可选）

- 关联 Issue：`Closes #123`
- 破坏性变更：`BREAKING CHANGE:`

### 提交示例

#### 简单提交

```bash
git commit -m "feat(api): add user registration endpoint"
```

#### 完整提交

```bash
git commit -m "feat(auth): add OAuth2 login support

Implement Google and GitHub OAuth2 providers.
Update authentication middleware to handle OAuth callbacks.
Add session management for OAuth users.

Closes #123"
```

#### 破坏性变更

```bash
git commit -m "feat(api): remove deprecated endpoints

Remove /v1/users and /v1/products endpoints.
Clients should use /v2/ equivalents.

BREAKING CHANGE: /v1/ endpoints removed
Closes #456"
```

## Pull Request 最佳实践

### PR 标题格式

与 Conventional Commits 一致：

- `feat: add user dashboard`
- `fix: resolve memory leak in worker`
- `refactor: extract payment service`

### PR 描述模板

```markdown
## 📋 变更类型
- [ ] `feat` 新功能
- [ ] `fix` Bug 修复
- [ ] `refactor` 重构
- [ ] `docs` 文档
- [ ] `style` 代码格式
- [ ] `test` 测试
- [ ] `chore` 构建/工具

## 📝 变更说明
<!-- 简要描述这个 PR 的目的和实现方式 -->

<!-- 回答：这个 PR 解决了什么问题？为什么需要这个变更？ -->

## 🧪 测试
- [ ] 添加了单元测试
- [ ] 添加了集成测试
- [ ] 手动测试通过
- [ ] 性能测试通过（如适用）

## ✅ 检查清单
- [ ] 代码符合团队规范
- [ ] 自我审查完成
- [ ] 注释充分且准确
- [ ] 文档已更新
- [ ] 无新的警告产生
- [ ] 测试覆盖率未降低

## 📸 截图/演示（可选）
<!-- 添加 UI 变更的截图 -->

## 🔗 相关链接
- 关联 Issue: #123
- 设计文档: [链接]
```

## 分支策略

### 分支命名规范

| 分支类型 | 命名模式 | 示例 |
|---------|---------|------|
| 功能开发 | `feature/*` | `feature/user-dashboard` |
| Bug 修复 | `bugfix/*` | `bugfix/login-timeout` |
| 紧急修复 | `hotfix/*` | `hotfix/security-patch` |
| 发布版本 | `release/*` | `release/v1.5.0` |

### 工作流程

#### 1. 开始新功能

```bash
# 从 main 创建功能分支
git checkout main
git pull origin main
git checkout -b feature/user-dashboard

# 开发功能
# ... 编写代码 ...

# 提交变更
git add .
git commit -m "feat(dashboard): add user profile section"

# 推送分支
git push -u origin feature/user-dashboard
```

#### 2. 创建 Pull Request

```bash
# 使用 GitHub CLI
gh pr create \
  --title "feat: add user dashboard" \
  --body "PR 描述..." \
  --base main \
  --head feature/user-dashboard
```

#### 3. 代码审查与合并

- 至少一人审查通过
- CI 检查全部通过
- 使用 Squash and Merge 保持历史清晰

#### 4. 清理分支

```bash
# 合并后删除本地分支
git branch -d feature/user-dashboard

# 删除远程分支
git push origin --delete feature/user-dashboard
```

## Git Hooks 配置

### Pre-commit Hook

```bash
#!/bin/bash
# .git/hooks/pre-commit

# 运行 linter
npm run lint || exit 1

# 运行类型检查
npm run type-check || exit 1

# 运行测试
npm run test || exit 1

echo "✅ Pre-commit checks passed!"
```

### Commit-msg Hook（强制 Conventional Commits）

```bash
#!/bin/bash
# .git/hooks/commit-msg

commit_regex='^(feat|fix|docs|style|refactor|perf|test|chore|ci)(\(.+\))?: .{1,50}'

if ! grep -qE "$commit_regex" "$1"; then
    echo "❌ Invalid commit message format!"
    echo "Expected format: <type>(<scope>): <subject>"
    echo "Types: feat, fix, docs, style, refactor, perf, test, chore, ci"
    exit 1
fi

echo "✅ Commit message format valid!"
```

## 常用 Git 命令

### 日常操作

```bash
# 查看状态
git status

# 暂存变更
git add .
git add <file>

# 提交变更
git commit -m "type(scope): description"

# 推送变更
git push
git push -u origin <branch>

# 拉取最新
git pull
git pull --rebase  # 避免 merge commit
```

### 历史查看

```bash
# 查看提交历史
git log --oneline
git log --graph --all  # 图形化

# 查看文件历史
git log -p <file>

# 查看分支
git branch -a
```

### 问题修复

```bash
# 撤销最后一次提交（保留变更）
git reset --soft HEAD~1

# 撤销最后一次提交（丢弃变更）
git reset --hard HEAD~1

# 撤销已推送的提交（创建新提交）
git revert <commit-hash>

# 修改最后一次提交信息
git commit --amend

# 交互式 rebase（清理历史）
git rebase -i HEAD~3
```

## 高级技巧

### Git Bisect（二分查找 Bug）

```bash
# 开始二分查找
git bisect start

# 标记当前版本为坏
git bisect bad

# 标记已知好的版本
git bisect good <good-commit-hash>

# Git 会切换到中间版本，测试后标记
git bisect good  # 或 git bisect bad

# 重复直到找到引入问题的 commit
git bisect reset  # 结束
```

### Git Blame（查看每行是谁写的）

```bash
# 查看文件每行的最后修改者
git blame <file>

# 查看特定行
git blame -L 10,20 <file>
```

### Git Stash（临时保存变更）

```bash
# 保存当前变更
git stash

# 保存并添加描述
git stash save "work in progress"

# 查看 stash 列表
git stash list

# 应用最近一次 stash
git stash pop

# 应用指定 stash
git stash apply stash@{1}

# 删除 stash
git stash drop
```

## 团队协作最佳实践

### 提交频率

- **小而频繁**：每完成一个小功能就提交
- **原子性**：每次提交是一个逻辑单元
- **可回滚**：任何提交都应能独立回滚

### 分支管理

- **短期分支**：功能分支应在几天内完成
- **及时清理**：合并后立即删除分支
- **保护 main**：main 分支应设置保护规则

### 代码审查

- **Pull Request**：所有代码通过 PR 合并
- **审查者**：至少一人审查
- **自动化**：CI 检查必须通过

## 检查清单总结

### 提交前检查

- [ ] 提交信息符合 Conventional Commits 规范
- [ ] 代码通过 linter
- [ ] 测试全部通过
- [ ] 无敏感信息泄露
- [ ] 注释充分

### PR 前检查

- [ ] PR 标题格式正确
- [ ] PR 描述完整
- [ ] 关联 Issue
- [ ] CI 检查通过
- [ ] 代码自我审查完成

### 合并后清理

- [ ] 删除本地分支
- [ ] 删除远程分支
- [ ] 更新文档（如需要）

## 参考资源

- [Git Commit (getsentry/commit)](https://github.com/getsentry/sentry-skills)
- [Git & GitHub Workflow Skills (fvadicamo/dev-agent-skills)](https://github.com/fvadicamo/dev-agent-skills)
- [Conventional Commits](https://www.conventionalcommits.org/)

# 硬编码引导步骤 - 实现说明

## 问题回顾

你遇到的错误：
```bash
python3: can't open file '/Volumes/2T01/winE/Starup/LLMRide/scripts/agent_coordinator.py'
```

**根本原因**：
- AI 生成的命令使用了相对路径 `python3 scripts/agent_coordinator.py`
- 相对路径会在**当前工作目录**查找脚本
- 但脚本实际安装在技能目录中，不在当前项目目录

## 解决方案：硬编码引导步骤

### 核心思想

**让脚本自己告诉 AI 它在哪里**

而不是让 AI 猜测或硬编码路径。

### 实现方式

#### 1. 新增 `get_path.py` 脚本

**位置**：`awesome-code/scripts/get_path.py`

**功能**：
- 自动获取技能的真实安装路径
- 输出 JSON 格式，包含所有脚本的绝对路径
- 无论从哪里调用都能正确获取路径

**源码**：
```python
#!/usr/bin/env python3
"""Awesome Code - 技能路径获取工具"""

import json
from pathlib import Path

def main():
    # 获取脚本所在技能的根目录
    skill_root = Path(__file__).resolve().parent.parent

    # 构建路径映射
    paths = {
        "skill_root": str(skill_root),
        "skill_name": skill_root.name,
        "scripts_dir": str(skill_root / "scripts"),
        "executable_scripts": {}
    }

    # 获取所有可执行脚本的路径
    for script_file in (skill_root / "scripts").glob("*.py"):
        paths["executable_scripts"][script_file.stem] = str(script_file)

    # 输出 JSON 格式
    print(json.dumps(paths, ensure_ascii=False, indent=2))

if __name__ == "__main__":
    main()
```

#### 2. AI 调用流程（三步骤）

```bash
# 步骤 1：获取技能路径（硬编码）
python3 ~/.claude/skills/awesome-code/scripts/get_path.py

# 步骤 2：解析 JSON，提取脚本路径
# 从返回的 JSON 中提取需要的脚本路径

# 步骤 3：使用绝对路径调用
python3 <absolute_path_from_json> "task"
```

#### 3. SKILL.md 文档更新

在 SKILL.md 开头添加"步骤 0：获取技能路径"章节，明确说明：
- 这是硬编码引导步骤
- AI 必须首先调用它
- 输出格式和使用方式

## 优势

### 1. 环境无关性

无论技能安装在哪里，都能正确工作：

```bash
# 用户级安装
~/.claude/skills/awesome-code/

# 项目级安装
.claude/skills/awesome-code/

# 自定义路径
/custom/path/skills/awesome-code/
```

### 2. 目录无关性

无论当前工作目录在哪里，都能正确获取路径：

```bash
# 在项目目录中
cd /my/project
python3 ~/.claude/skills/awesome-code/scripts/get_path.py

# 在临时目录中
cd /tmp
python3 ~/.claude/skills/awesome-code/scripts/get_path.py

# 结果都是正确的绝对路径
```

### 3. 自动发现性

脚本通过 `Path(__file__).resolve().parent.parent` 自动发现路径：
- `__file__`：脚本自身的绝对路径
- `parent`：脚本所在目录（`scripts/`）
- `parent.parent`：技能根目录

### 4. AI 友好性

- 输出 JSON 格式，便于 AI 解析
- 包含所有可执行脚本的完整路径
- 无需 AI 猜测或计算路径

## 验证测试

从不同目录调用，验证路径正确性：

```bash
# 从技能目录
cd /path/to/skills/awesome-code
python3 scripts/get_path.py
# ✅ 返回正确的绝对路径

# 从项目目录
cd /my/project
python3 ~/.claude/skills/awesome-code/scripts/get_path.py
# ✅ 返回正确的绝对路径

# 从任意目录
cd /tmp
python3 ~/.claude/skills/awesome-code/scripts/get_path.py
# ✅ 返回正确的绝对路径
```

## 与其他方案的对比

| 方案 | 优势 | 劣势 |
|------|------|------|
| **相对路径** | 简洁 | ❌ 依赖当前目录，不可靠 |
| **硬编码绝对路径** | 明确 | ❌ 无法预知安装位置 |
| **环境变量** | 灵活 | ❌ 依赖用户配置 |
| **硬编码引导步骤** | 可靠、自动、环境无关 | 需要先调用引导脚本 |

## 扩展性

这个方案可以扩展到其他需要动态获取路径的场景：

1. **跨技能调用**：一个技能调用另一个技能的脚本
2. **CI/CD 集成**：在自动化环境中动态获取路径
3. **插件系统**：插件动态发现主程序路径

## 总结

通过引入 `get_path.py` 硬编码引导步骤，我们实现了：

✅ **环境无关**：无论技能安装在哪里都能工作
✅ **目录无关**：无论当前目录在哪里都能正确获取路径
✅ **自动发现**：脚本通过 `__file__` 自动发现自身位置
✅ **AI 友好**：JSON 输出，便于 AI 解析和使用
✅ **用户友好**：文档清晰，步骤明确

这是**最稳健、最通用的解决方案**。

# 参考文档索引

本目录包含 awesome-code 技能的详细参考文档。

## 核心工作流文档

| 文档 | 描述 | 适用场景 |
|------|------|----------|
| `tdd-best-practices.md` | TDD 最佳实践 | 测试驱动开发 |
| `debugging-systematic.md` | 系统化调试与根因分析 | Bug 修复、问题定位 |
| `code-review-checklist.md` | 代码审查清单 | 代码审查、质量检查 |
| `git-workflow.md` | Git 工作流规范 | 版本控制、提交规范 |
| `multi-agent-patterns.md` | 多代理协调模式 | 复杂任务协调 |
| `context-optimization.md` | 上下文优化策略 | 长对话、token 管理 |

## 批判性思维与测试优化

| 文档 | 描述 | 适用场景 |
|------|------|----------|
| `CRITICAL_THINKING_GUIDE.md` | 批判性思维指南 | A/B 轮测试优化的核心方法论 |
| `A_ROUND_PLAN_TEMPLATE.md` | A 轮计划模板 | 创建 A 轮问题分析计划 |
| `CONSTRUCTIVE_SUGGESTION_GUIDELINES.md` | 建设性建议标准 | 确保问题建议有价值 |
| `ISSUE_DISCOVERY_TECHNIQUES.md` | 问题挖掘技巧 | 发现隐藏问题的方法 |
| `ANTI_PATTERNS_LIBRARY.md` | 反例库 | 常见问题模式参考 |

## 工程基础设施（v2.1.0 新增）

| 文档 | 描述 | 适用场景 |
|------|------|----------|
| `CONTEXT_MANAGEMENT_GUIDE.md` | Context Window 管理优化指南 | 长对话性能优化、token 管理 |

## 使用说明

1. **按需加载**：AI 只在需要时加载具体文档，减少 context window 消耗
2. **渐进式披露**：从 SKILL.md 概述开始，深入时再查阅参考文档
3. **关键词触发**：在对话中提到相关关键词时，自动加载对应文档

## 变更记录

变更记录见 `awesome-code/CHANGELOG.md`（版本号以 `awesome-code/config.yaml:skill_info.version` 为准）。

# 问题挖掘技巧

**文档版本**：v1.0.0
**创建时间**：2026-01-14
**用途**：为 auto-test-skill 提供"如何深入挖掘问题"的技巧库

---

## 核心思想

**问题挖掘** = 系统化的质疑 + 多角度的验证 + 边缘情况的探索

本文档提供 10 大类问题挖掘技巧，帮助 AI 在每轮 A 轮中发现 10-20 个建设性问题。

---

## 技巧 1: 文件间交叉验证

### 方法
检查 A 文件引用的内容，在 B 文件中是否存在/一致。

### 检查清单
- [ ] SKILL.md 引用的配置项，在 config.yaml 中是否存在？
- [ ] README.md 中的示例，与 SKILL.md 的工作流是否一致？
- [ ] 脚本注释中的"路径"，与实际目录结构是否匹配？
- [ ] 文档中引用的模板文件（`references/XXX.md`），实际是否存在？
- [ ] YAML frontmatter 中的 `name`，与目录名是否一致？

### 典型发现
```
问题：SKILL.md 第 30 行说"参考 config.output_dir"，但 config.yaml 中是 "output.directory"
位置：SKILL.md:30, config.yaml:15
优先级：P1
修复：统一为 "output.directory"
```

---

## 技巧 2: 逻辑推演找漏洞

### 方法
问自己："如果 X 发生，会怎样？"（X 是异常情况）

### 检查清单
- [ ] 如果用户跳过步骤 1，直接执行步骤 2 会怎样？
- [ ] 如果 config.yaml 中的这个参数是空值会怎样？
- [ ] 如果用户输入的路径包含空格或特殊字符会怎样？
- [ ] 如果网络请求失败会怎样？有重试机制吗？
- [ ] 如果输入文件是空的会怎样？

### 典型发现
```
问题：如果 config.timeout 为空，脚本会崩溃（未设置默认值）
位置：scripts/loader.py:42
优先级：P0
修复：增加默认值 timeout = config.get("timeout", 30)
```

---

## 技巧 3: 文档"读心术"

### 方法
找出文档中的"模糊词"和"未验证的假设"

### 关键词搜索
搜索以下词汇，发现潜在问题：
- `应该` → 通常意味着"实际上没做"
- `会` → 通常意味着"假设会发生"
- `自动` → 通常意味着"没有手动验证"
- `例如`、`如` → 检查示例是否真的可运行
- `详见`、`参考` → 检查被引用的文件是否存在
- `用户` → 检查是否假设用户会做某事

### 典型发现
```
问题："用户应先创建目录" → 假设用户会手动创建，实际不会
位置：SKILL.md:55
优先级：P1
修复：脚本应自动创建目录（见 scripts/setup.py:12）
```

---

## 技巧 4: 代码/文档"模式匹配"

### 方法
使用 Grep 工具搜索特定模式，发现隐藏问题

### 搜索模式
| 模式 | 目的 | 典型问题 |
|------|------|----------|
| `TODO`、`FIXME`、`HACK` | 未完成的技术债 | 功能未完成、临时方案未清理 |
| `print(`、`console.log` | 未清理的调试代码 | 生产代码包含调试输出 |
| `#` 注释中的"临时"、"测试" | 未清理的临时内容 | 标记为临时的代码仍在使用 |
| `except:` (无异常类型) | 过于宽泛的异常捕获 | 隐藏真实错误、难以调试 |
| `os.system`、`subprocess.call` | 潜在的命令注入风险 | 未验证用户输入 |
| `pass` | 空的实现 | 函数/类未实现 |

### 典型发现
```
问题：scripts/processor.py:88 包含 `except:` 捕获所有异常，隐藏真实错误
位置：scripts/processor.py:88
优先级：P1
修复：细化为具体异常类型（如 FileNotFoundError, ValueError）
```

---

## 技巧 5: "挑刺"清单

### 方法
系统化地检查每个"应该有"的东西是否真的存在

### 通用清单
- [ ] 每个配置项都有说明吗？
- [ ] 每个示例都能运行吗？
- [ ] 每个引用的文件都存在吗？
- [ ] 每个步骤都有验证方法吗？
- [ ] 每个错误都有明确的错误提示吗？
- [ ] 每个函数都有 docstring 吗？
- [ ] 每个脚本都有 `if __name__ == "__main__"` 保护吗？

### SKILL.md 专项清单
- [ ] YAML `description` 与正文描述一致吗？
- [ ] 工作流步骤完整吗？（从输入到输出）
- [ ] 配置说明与 config.yaml 一致吗？
- [ ] 示例命令可复制粘贴运行吗？
- [ ] 完成条件可验证吗？

### 典型发现
```
问题：config.yaml 第 23 行的 `retry_delay` 配置项在文档中无说明
位置：config.yaml:23
优先级：P2
修复：在 config.yaml 中增加注释说明用途和默认值
```

---

## 技巧 6: 边缘情况压力测试

### 方法
构造极端输入，验证 skill 的鲁棒性

### 测试场景
| 输入类型 | 测试值 | 预期行为 |
|----------|--------|----------|
| **路径** | `../../etc/passwd` | 被拒绝（路径遍历防御） |
| **路径** | `path with spaces` | 正常处理（路径规范化） |
| **路径** | 空字符串 `""` | 有明确错误提示 |
| **配置** | 空文件 `{}` | 使用默认值 |
| **配置** | 无效值（如 `timeout: -1`） | 有明确错误提示 |
| **输入** | 超大文件（>1GB） | 有进度提示或分块处理 |
| **输入** | 空文件 | 有明确错误提示 |
| **输入** | 特殊字符（`\n`, `\0`） | 正确转义或拒绝 |

### 典型发现
```
问题：路径验证只检查 `../` 前缀，无法防御 `./../` 绕过
位置：scripts/validator.py:45
优先级：P0
修复：使用 os.path.realpath() 规范化后再验证
```

---

## 技巧 7: "自我质疑"法

### 方法
对每个设计决策问："真的需要吗？有更简单的方式吗？"

### 质疑清单
- [ ] 这个配置项真的需要可配置吗？还是可以硬编码？
- [ ] 这个函数/类真的需要抽象吗？还是可以简化？
- [ ] 这个步骤真的需要用户手动执行吗？还是可以自动化？
- [ ] 这个检查真的需要吗？还是过度防御？
- [ ] 这个文档真的需要单独文件吗？还是可以合并？

### 典型发现
```
问题：output_format 配置项只有 "json" 一个有效值，过度设计
位置：config.yaml:30
优先级：P2
修复：移除配置项，直接硬编码为 "json"
```

---

## 技巧 8: 安全性扫描

### 方法
系统性检查常见安全漏洞

### 扫描清单
- [ ] **路径遍历**：用户输入的路径是否验证？
- [ ] **命令注入**：用户输入是否直接用于系统命令？
- [ ] **敏感信息泄露**：日志/错误中是否包含密钥、密码？
- [ ] **不安全的反序列化**：对不可信数据直接反序列化？
- [ ] **硬编码密钥**：API 密钥、密码是否写在代码中？

### 典型发现
```
问题：用户输入直接用于 os.system，存在命令注入风险
位置：scripts/runner.py:67
优先级：P0
修复：使用 subprocess.run 与参数化参数
```

---

## 技巧 9: 用户体验（UX）审查

### 方法
模拟真实用户，评估使用体验

### 评估维度
- [ ] **第一印象**：新用户能在 5 分钟内理解如何使用吗？
- [ ] **错误恢复**：出错时，文档是否告诉用户如何恢复？
- [ ] **反馈及时**：长时间操作是否有进度提示？
- [ ] **错误友好**：错误信息是否告诉用户具体问题和解决方法？
- [ ] **可预测性**：用户能预期每一步的结果吗？

### 典型发现
```
问题：错误信息 "Error: failed" 无法告诉用户具体问题
位置：scripts/loader.py:52
优先级：P1
修复：改为 "Error: failed to load config.yaml: file not found"
```

---

## 技巧 10: "如果我是恶意用户"测试

### 方法
站在攻击者视角，尝试破坏 skill

### 攻击场景
1. **路径遍历攻击**：输入 `../../etc/passwd`
2. **命令注入攻击**：输入 `; rm -rf /`
3. **配置注入**：输入恶意 YAML（如利用 YAML 解析器漏洞）
4. **资源耗尽**：输入超大文件（>1GB）
5. **并发竞态**：同时修改配置文件
6. **符号链接攻击**：创建符号链接到敏感文件

### 典型发现
```
问题：未验证符号链接，用户可能通过 symlink 读取任意文件
位置：scripts/reader.py:34
优先级：P0
修复：验证解析后的路径是否在 base_dir 内
```

---

## 组合使用技巧

### 单轮检查策略

为达到 10-20 个问题，建议组合使用：

1. **技巧 1（交叉验证）**：2-4 个问题
2. **技巧 2（逻辑推演）**：2-3 个问题
3. **技巧 3（读心术）**：2-3 个问题
4. **技巧 4（模式匹配）**：1-2 个问题
5. **技巧 6（边缘情况）**：2-3 个问题
6. **技巧 8（安全性）**：1-2 个问题（如无安全问题可跳过）
7. **技巧 9（UX 审查）**：1-2 个问题

**总计**：11-19 个问题

### 深度挖掘策略

当表面问题已发现完，需要深入挖掘时：

1. **逐行阅读**：从 SKILL.md 第一行开始，逐行质疑
2. **执行演练**：假装执行工作流，记录每个卡点
3. **反向思考**：从输出倒推，验证每个步骤是否必要
4. **对比分析**：与类似 skill 对比，找出差异点

---

## 问题记录模板

发现问题时，使用以下模板记录：

```
#### 问题 X: [简短标题]

**位置**: `文件:行号`

**问题类型**: [交叉验证/逻辑漏洞/文档模糊/安全性/UX/...]

**问题描述**:
[具体描述问题现象]

**影响**:
[这个问题会导致什么后果]

**优先级**: P0/P1/P2

**修复建议**:
[具体的修复方案]

**验证方法**:
[如何确认修复成功]
```

---

## 数量达标策略

### 策略 1: "每个技巧至少 1 个问题"

使用 10 大技巧，每技巧至少发现 1 个问题 = 10 个问题

### 策略 2: "逐文件地毯式搜索"

对每个文件使用"挑刺清单"：
- SKILL.md：5-8 个问题
- config.yaml：2-3 个问题
- scripts/*.py：3-5 个问题
- README.md：2-3 个问题

总计：12-19 个问题

### 策略 3: "优先级分布法"

- P0：2-4 个（安全/阻塞问题）
- P1：5-8 个（重要优化）
- P2：3-6 个（锦上添花）

总计：10-18 个问题

---

**模板说明**：

本文档用于指导 auto-test-skill 深入挖掘问题。

使用时：
1. 选择 3-5 个技巧组合使用
2. 每个技巧至少发现 2 个问题
3. 确保问题总数 ≥ 10，且 P0+P1 占比 ≥ 60%
4. 使用"问题记录模板"标准化记录

# 多代理协调模式参考文档

## 核心概念

多代理协调是指将复杂任务分解为多个子任务，由专门的代理并行或协作完成，从而提升开发效率和系统可扩展性。

## 何时使用多代理协调

### 适用场景

✅ **适合使用多代理**：
- 多个独立的文件需要修改
- 不同模块的测试可以并行运行
- 需要同时分析和处理多个代码区域
- 大型重构涉及多个子系统
- 需要同时测试多个假设

❌ **不适合使用多代理**：
- 简单的单文件修改
- 线性依赖的任务序列
- 需要频繁同步的工作
- token 预算有限（多代理会增加 token 消耗）

## 协调模式

### 模式 1：编排器模式（Orchestrator）

**特点**：中央控制代理协调多个子代理

```
主代理（编排器）
├── 任务分解
├── 子代理分配
│   ├── 子代理 A：处理模块 X
│   ├── 子代理 B：处理模块 Y
│   └── 子代理 C：处理模块 Z
├── 结果收集与验证
└── 冲突解决与合并
```

**优势**：
- 集中控制，易于管理
- 结果聚合简单
- 适用于层级化任务

**示例**：

```python
# 主代理伪代码
def orchestrator_main():
    # 1. 任务分解
    modules = analyze_project_structure()
    tasks = decompose_tasks(modules)

    # 2. 并行分配
    agents = [spawn_agent(task) for task in tasks]

    # 3. 收集结果
    results = [agent.wait_for_result() for agent in agents]

    # 4. 合并与验证
    merged = merge_and_validate(results)

    return merged
```

### 模式 2：点对点模式（Peer-to-Peer）

**特点**：代理之间直接通信，无中央控制

```
子代理 A ←→ 子代理 B
    ↕         ↕
子代理 C ←→ 子代理 D
```

**优势**：
- 无单点故障
- 高度并行化
- 适合分布式任务

**示例场景**：代码库中的模块间相互引用检查

### 模式 3：流水线模式（Pipeline）

**特点**：代理按顺序处理，每个代理负责特定阶段

```
输入 → 子代理 A → 子代理 B → 子代理 C → 输出
       （解析）   （分析）   （生成）
```

**优势**：
- 清晰的职责分离
- 易于调试和监控
- 适合顺序处理任务

**示例**：代码审查流水线

1. 代理 A：静态分析
2. 代理 B：安全扫描
3. 代理 C：性能分析
4. 代理 D：生成报告

## 任务分解策略

### 策略 1：按模块分解

```
项目结构：
src/
├── auth/       → 子代理 A
├── database/   → 子代理 B
├── api/        → 子代理 C
└── utils/      → 子代理 D
```

**适用**：模块化良好的项目

### 策略 2：按功能分解

```
任务：实现用户注册功能
├── 前端表单    → 子代理 A
├── API 端点    → 子代理 B
├── 数据库模型  → 子代理 C
└── 测试用例    → 子代理 D
```

**适用**：跨功能的完整特性开发

### 策略 3：按文件类型分解

```
代码库：
├── *.py      → Python 代理
├── *.js      → JavaScript 代理
├── *.sql     → SQL 代理
└── *.md      → 文档代理
```

**适用**：多语言项目

## 冲突解决策略

### 冲突类型

| 冲突类型 | 示例 | 解决策略 |
|---------|------|---------|
| **命名冲突** | 两个代理创建同名函数 | 重命名（加前缀/后缀） |
| **逻辑冲突** | 对同一功能有不同的实现 | 投票机制或人工仲裁 |
| **依赖冲突** | 模块 A 和 B 需要不同版本的依赖 | 依赖隔离或统一版本 |
| **结构冲突** | 不同的代码组织方式 | 制定统一标准 |

### 解决策略

#### 策略 1：人工仲裁（Ask）

```
冲突检测 → 暂停任务 → 展示冲突 → 用户选择 → 继续执行
```

**适用**：重要决策、高风险变更

#### 策略 2：自动中止（Abort）

```
冲突检测 → 记录冲突 → 停止执行 → 生成报告
```

**适用**：不可自动解决的冲突

#### 策略 3：自动恢复（Resume）

```
冲突检测 → 应用预设规则 → 继续执行 → 记录日志
```

**适用**：常见、低风险的冲突

## 结果聚合

### 聚合方式

#### 方式 1：串行聚合

```python
def aggregate_results_serial(results):
    """逐个合并结果，冲突时使用后者"""
    final = {}
    for result in results:
        final.update(result)
    return final
```

#### 方式 2：智能合并

```python
def aggregate_results_smart(results):
    """智能合并，检测并解决冲突"""
    final = {}
    for result in results:
        for key, value in result.items():
            if key in final:
                # 检测冲突
                if final[key] != value:
                    # 应用解决策略
                    final[key] = resolve_conflict(final[key], value)
            else:
                final[key] = value
    return final
```

#### 方式 3：投票机制

```python
def aggregate_results_voting(results):
    """多个代理投票决定"""
    from collections import Counter

    decisions = {}
    for result in results:
        for key, value in result.items():
            if key not in decisions:
                decisions[key] = []
            decisions[key].append(value)

    # 选择最常见的决定
    final = {}
    for key, values in decisions.items():
        final[key] = Counter(values).most_common(1)[0][0]

    return final
```

## 性能优化

### 优化策略

1. **任务独立性**：确保子任务间无依赖
2. **批量启动**：一次性启动所有代理
3. **结果缓存**：避免重复计算
4. **超时控制**：防止单个代理阻塞整体

### 超时处理

```python
def run_with_timeout(agent, timeout):
    """带超时的代理执行"""
    import signal

    def timeout_handler(signum, frame):
        raise TimeoutError(f"Agent timeout after {timeout}s")

    signal.signal(signal.SIGALRM, timeout_handler)
    signal.alarm(timeout)

    try:
        result = agent.run()
        signal.alarm(0)  # 取消超时
        return result
    except TimeoutError:
        return None  # 或返回默认值
```

## 错误处理

### 错误传播

```python
def agent_with_error_handling(agent):
    """带错误处理的代理执行"""
    try:
        result = agent.run()
        return {"status": "success", "result": result}
    except Exception as e:
        return {
            "status": "error",
            "error": str(e),
            "agent": agent.name,
            "traceback": traceback.format_exc()
        }
```

### 部分失败处理

```python
def handle_partial_failure(results):
    """处理部分代理失败的情况"""
    successes = [r for r in results if r["status"] == "success"]
    failures = [r for r in results if r["status"] == "error"]

    if failures:
        logger.warning(f"{len(failures)} agents failed:")
        for f in failures:
            logger.warning(f"  {f['agent']}: {f['error']}")

    # 决定是否继续
    if len(successes) >= len(results) * 0.5:  # 至少一半成功
        return merge_results(successes)
    else:
        raise RuntimeError("Too many agents failed")
```

## 实战示例

### 示例 1：并行测试多个模块

```python
# 主代理
def parallel_test_modules(modules):
    """并行测试多个模块"""

    # 任务分解
    tasks = [
        {"agent": "test-runner", "module": module}
        for module in modules
    ]

    # 并行执行
    agents = [spawn_agent(task) for task in tasks]
    results = [agent.wait_for_result() for agent in agents]

    # 聚合结果
    test_report = aggregate_test_results(results)

    return test_report
```

### 示例 2：分布式代码审查

```python
# 主代理
def distributed_code_review(files):
    """分布式代码审查"""

    # 按文件类型分组
    groups = group_files_by_type(files)

    # 为每组分配一个代理
    agents = []
    for file_type, file_list in groups.items():
        task = {
            "agent": "code-reviewer",
            "type": file_type,
            "files": file_list
        }
        agents.append(spawn_agent(task))

    # 收集审查结果
    reviews = [agent.wait_for_result() for agent in agents]

    # 生成统一报告
    final_report = merge_review_reports(reviews)

    return final_report
```

## 最佳实践

### 设计原则

1. **明确边界**：清晰定义每个代理的职责
2. **最小依赖**：代理间应尽量独立
3. **可恢复性**：支持失败重试和状态恢复
4. **可观测性**：记录代理的决策和过程

### 配置建议

```yaml
# config.yaml 中的多代理配置
multi_agent:
  # 最大并行任务数
  max_parallel_tasks: 5

  # 单任务超时（秒）
  timeout_per_task: 300

  # 重试次数
  max_retries: 2

  # 结果聚合策略
  result_aggregation: auto  # auto | manual | voting

  # 冲突解决策略
  conflict_resolution: ask  # ask | abort | resume | current | incoming
```

## 检查清单

使用多代理协调前确认：

- [ ] 任务可分解为独立的子任务
- [ ] 子任务间无强依赖
- [ ] 有明确的聚合策略
- [ ] 定义了冲突解决机制
- [ ] 设置了合理的超时时间
- [ ] 考虑了部分失败的后果
- [ ] 有足够的 token 预算

## 参考资源

- [Multi-Agent Coordination (obra/dispatching-parallel-agents)](https://github.com/VoltAgent/awesome-claude-skills)
- [Subagent Driven Development (obra/subagent-driven-development)](https://github.com/VoltAgent/awesome-claude-skills)
- [Context Engineering Skills (muratcankoylan)](https://github.com/VoltAgent/awesome-claude-skills)

# Awesome Code 脚本调用策略

## 核心原则

**硬编码引导步骤 → 动态获取路径 → 使用绝对路径调用**

通过 `get_path.py` 硬编码引导脚本，让 AI 动态获取技能真实安装路径，确保在任何情况下都能正常工作。

## AI 调用流程（三步骤）

### 步骤 1：获取技能路径（硬编码）

```bash
python3 ~/.claude/skills/awesome-code/scripts/get_path.py
```

**输出示例**：
```json
{
  "skill_root": "/Users/username/.claude/skills/awesome-code",
  "skill_name": "awesome-code",
  "scripts_dir": "/Users/username/.claude/skills/awesome-code/scripts",
  "config_file": "/Users/username/.claude/skills/awesome-code/config.yaml",
  "executable_scripts": {
    "agent_coordinator": "/Users/username/.claude/skills/awesome-code/scripts/agent_coordinator.py",
    "create_test_session": "/Users/username/.claude/skills/awesome-code/scripts/create_test_session.py",
    "test_runner": "/Users/username/.claude/skills/awesome-code/scripts/test_runner.py",
    "code_analyzer": "/Users/username/.claude/skills/awesome-code/scripts/code_analyzer.py",
    "git_helper": "/Users/username/.claude/skills/awesome-code/scripts/git_helper.sh"
  }
}
```

### 步骤 2：解析 JSON，提取脚本路径

AI 从返回的 JSON 中提取需要的脚本路径：

```python
import json

# 假设已运行 get_path.py 并保存输出
paths = json.loads(output)
coordinator_path = paths["executable_scripts"]["agent_coordinator"]
# /Users/username/.claude/skills/awesome-code/scripts/agent_coordinator.py
```

### 步骤 3：使用绝对路径调用

```bash
python3 /Users/username/.claude/skills/awesome-code/scripts/agent_coordinator.py "fix bug"
```

## 为什么需要硬编码引导步骤？

### 问题背景

1. **技能安装位置不固定**
   - 用户级：`~/.claude/skills/awesome-code/`
   - 项目级：`.claude/skills/awesome-code/`
   - 自定义路径

2. **当前工作目录可变**
   - 用户可能在任意项目目录中使用
   - 相对路径无法正确定位

3. **AI 无法预知安装位置**
   - 硬编码路径会因环境而失效
   - 环境变量依赖用户配置

### 解决方案

让脚本**自己告诉 AI 它在哪里**：

```python
# get_path.py 核心逻辑
from pathlib import Path

skill_root = Path(__file__).resolve().parent.parent
# 无论脚本安装在哪里，都能正确获取路径
```

## 脚本分类与调用方式

### 1. 路径引导脚本（硬编码）

| 脚本 | 功能 | 调用方式 |
|------|------|----------|
| **get_path.py** | 获取技能真实安装路径 | `python3 ~/.claude/skills/awesome-code/scripts/get_path.py` |

**特点**：
- 硬编码调用（AI 必须先调用这个脚本）
- 输出 JSON 格式，便于 AI 解析
- 包含所有可执行脚本的绝对路径

### 2. 技能内部脚本（需要访问技能配置）

这些脚本需要访问 `awesome-code` 技能自身的配置文件。

| 脚本 | 实现方式 | 调用示例 |
|------|----------|----------|
| `agent_coordinator.py` | `Path(__file__).resolve().parent.parent` | `python3 <absolute_path> "task"` |

**实现原理**：
```python
# 脚本会自动找到技能根目录
self.skill_root = Path(__file__).resolve().parent.parent
# /Users/username/.claude/skills/awesome-code/
```

### 3. 项目操作脚本（作用于当前项目）

这些脚本在**当前项目目录**中运行，操作项目文件。

| 脚本 | 实现方式 | 调用示例 |
|------|----------|----------|
| `test_runner.py` | 在项目目录运行 | `python3 <absolute_path> --watch` |
| `code_analyzer.py` | 在项目目录运行 | `python3 <absolute_path> --path src/` |
| `git_helper.sh` | 在项目目录运行 | `bash <absolute_path> commit` |

**使用场景**：在任意项目目录中调用，脚本会自动检测当前项目环境。

### 4. 跨技能脚本（作用于指定技能）

这些脚本需要指定**目标技能**的路径。

| 脚本 | 实现方式 | 调用示例 |
|------|----------|----------|
| `create_test_session.py` | 通过 `--skill-root` 参数 | `python3 <absolute_path> --skill-root . --kind a` |

**使用场景**：用于测试和优化其他技能，`--skill-root` 指向目标技能目录。

## 用户手动调用

### 推荐配置：Shell 别名

在 `~/.zshrc` 或 `~/.bashrc` 中添加：

```bash
# Awesome Code 脚本别名
alias ac-coordinator='python3 ~/.claude/skills/awesome-code/scripts/agent_coordinator.py'
alias ac-test='python3 ~/.claude/skills/awesome-code/scripts/test_runner.py'
alias ac-analyze='python3 ~/.claude/skills/awesome-code/scripts/code_analyzer.py'
alias ac-git='bash ~/.claude/skills/awesome-code/scripts/git_helper.sh'
alias ac-session='python3 ~/.claude/skills/awesome-code/scripts/create_test_session.py'
```

使用示例：
```bash
ac-coordinator "fix login bug"
ac-test --watch --coverage
ac-analyze --path src/ --report analysis.md
ac-git commit
ac-session --skill-root . --kind a --id v202601171200
```

### 直接调用

```bash
# 用户级安装
python3 ~/.claude/skills/awesome-code/scripts/agent_coordinator.py "fix bug"

# 项目级安装
python3 .claude/skills/awesome-code/scripts/agent_coordinator.py "fix bug"
```

## 安装位置支持

脚本支持两种安装位置：

| 安装位置 | get_path.py 路径 |
|---------|------------------|
| **用户级** | `~/.claude/skills/awesome-code/scripts/get_path.py` |
| **项目级** | `.claude/skills/awesome-code/scripts/get_path.py` |

AI 应优先尝试用户级路径，失败后尝试项目级路径。

## 技术实现细节

### get_path.py 源码

```python
#!/usr/bin/env python3
"""Awesome Code - 技能路径获取工具"""

import json
from pathlib import Path

def main():
    # 获取脚本所在技能的根目录
    skill_root = Path(__file__).resolve().parent.parent

    # 构建路径映射
    paths = {
        "skill_root": str(skill_root),
        "skill_name": skill_root.name,
        "scripts_dir": str(skill_root / "scripts"),
        "config_file": str(skill_root / "config.yaml"),
        "skill_file": str(skill_root / "SKILL.md"),
        "references_dir": str(skill_root / "references"),
        "templates_dir": str(skill_root / "templates"),
    }

    # 获取所有可执行脚本的路径
    scripts_dir = skill_root / "scripts"
    if scripts_dir.exists():
        paths["executable_scripts"] = {}
        for script_file in scripts_dir.glob("*.py"):
            paths["executable_scripts"][script_file.stem] = str(script_file)
        for script_file in scripts_dir.glob("*.sh"):
            paths["executable_scripts"][script_file.stem] = str(script_file)

    # 输出 JSON 格式
    print(json.dumps(paths, ensure_ascii=False, indent=2))

if __name__ == "__main__":
    main()
```

### Python 脚本路径自发现

```python
# _config.py 和 agent_coordinator.py 使用
from pathlib import Path

# 获取脚本所在技能的根目录
skill_root = Path(__file__).resolve().parent.parent
# __file__ = /path/to/skills/awesome-code/scripts/agent_coordinator.py
# parent = /path/to/skills/awesome-code/scripts/
# parent.parent = /path/to/skills/awesome-code/ ✅

# 读取配置
config_path = skill_root / "config.yaml"
```

### Shell 脚本路径自发现

```bash
# git_helper.sh 示例
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_ROOT="$(dirname "$SCRIPT_DIR")"

# 读取配置
CONFIG_FILE="$SKILL_ROOT/config.yaml"
```

## 常见问题

### Q: 为什么不能直接输入 `agent_coordinator.py`？

A: 脚本需要完整路径才能被找到。AI 应先调用 `get_path.py` 获取路径，用户可使用 shell 别名。

### Q: 技能安装在不同位置怎么办？

A: `get_path.py` 会自动发现，无需手动配置。

### Q: 如何在 CI/CD 中使用？

A: 直接使用 `get_path.py` 或设置环境变量：

```bash
# 方式1：使用 get_path.py
export SKILL_PATHS=$(python3 ~/.claude/skills/awesome-code/scripts/get_path.py)

# 方式2：设置环境变量
export AWESOME_CODE_ROOT="${GITHUB_WORKSPACE}/.claude/skills/awesome-code"
python3 "$AWESOME_CODE_ROOT/scripts/agent_coordinator.py" "task"
```

### Q: AI 如何知道要调用 `get_path.py`？

A: 这是**硬编码引导步骤**，在 SKILL.md 开头明确说明，AI 必须首先调用它。

## 版本历史

- **2026-01-17**：新增 `get_path.py` 硬编码引导脚本，实现动态路径发现
- **2026-01-17**：明确 AI 调用流程（三步骤），区分 AI 和用户调用方式

# TDD 最佳实践参考文档

## 核心原则

测试驱动开发（Test-Driven Development）是一种软件开发方法，强调先编写测试，再编写实现代码。

### Red-Green-Refactor 循环

```
┌─────────────────────────────────────────┐
│  1. RED：编写一个失败的测试              │
│     - 描述新的功能或行为                 │
│     - 运行测试确认失败                   │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  2. GREEN：编写最简单的代码使测试通过    │
│     - 不追求完美，只求通过               │
│     - 运行测试确认成功                   │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  3. REFACTOR：在测试保护下优化代码      │
│     - 改善代码结构                      │
│     - 保持测试通过                       │
└─────────────────────────────────────────┘
              ↓
           回到步骤 1
```

## 测试命名规范

### AAA 模式（Arrange-Act-Assert）

```python
def test_should_return_discount_when_customer_is_premium():
    # Arrange（准备）：设置测试数据和依赖
    customer = create_premium_customer()
    cart = create_cart_with_items(["item1", "item2"])

    # Act（执行）：调用被测试的方法
    total = calculate_total(customer, cart)

    # Assert（断言）：验证结果
    assert total == expected_discounted_total
```

### 命名模板

```
should_{ExpectedBehavior}_when_{StateUnderTest}

示例：
- should_return_error_when_input_is_invalid
- should_send_notification_when_payment_succeeds
- should_redirect_to_login_when_user_not_authenticated
```

## 测试覆盖策略

### 测试金字塔

```
        /\
       /E2E\        少量端到端测试
      /------\
     / Integration \  适量集成测试
    /--------------\
   /    Unit Tests    \  大量单元测试
  /--------------------\
```

| 测试类型 | 数量 | 速度 | 成本 | 覆盖范围 |
|---------|------|------|------|----------|
| 单元测试 | 多 | 快 | 低 | 函数/方法 |
| 集成测试 | 中 | 中 | 中 | 模块交互 |
| E2E 测试 | 少 | 慢 | 高 | 完整流程 |

### 边界条件测试

必须测试的边界条件：

- [ ] 空值（null/None）
- [ ] 空集合（[]、""）
- [ ] 最小值/最大值
- [ ] 负数
- [ ] 非法类型
- [ ] 并发场景

## 测试隔离原则

### 每个测试必须独立

```python
# ❌ 错误：测试间有依赖
def test_a():
    global_state.set_value(1)

def test_b():
    # 依赖 test_a 的执行顺序
    assert global_state.get_value() == 1

# ✅ 正确：每个测试独立
def test_a():
    state = create_state()
    state.set_value(1)
    assert state.get_value() == 1

def test_b():
    state = create_state()
    state.set_value(1)
    assert state.get_value() == 1
```

### 使用 Setup/Teardown

```python
@pytest.fixture(autouse=True)
def reset_database():
    # Setup
    db.reset()
    yield
    # Teardown
    db.cleanup()
```

## Mock 与 Stub

### 何时使用 Mock

- 外部服务调用（API、数据库）
- 复杂依赖（文件系统、网络）
- 不可控资源（时间、随机数）

### Mock 示例

```python
def test_should_charge_payment_when_order_valid():
    # Arrange
    payment_gateway = Mock()
    payment_gateway.charge.return_value = Success(amount=100)

    order = create_order(amount=100)
    service = PaymentService(gateway=payment_gateway)

    # Act
    result = service.process_payment(order)

    # Assert
    assert result.is_success()
    payment_gateway.charge.assert_called_once_with(amount=100)
```

## 测试覆盖率目标

### 推荐标准

| 代码类型 | 覆盖率目标 |
|---------|-----------|
| 核心业务逻辑 | ≥ 90% |
| 工具函数 | ≥ 80% |
| UI/前端 | ≥ 70% |
| 配置/常量 | ≥ 50% |

### 覆盖率工具

```bash
# Python
pytest --cov=src --cov-report=html

# JavaScript
jest --coverage

# Java
jacoco:report
```

## 常见反模式

### ❌ 测试实现细节

```python
# 测试内部变量名称（脆弱）
def test_method_sets_internal_variable():
    obj = MyClass()
    obj.method()
    assert obj._internal_var == 1  # 测试细节
```

### ✅ 测试行为

```python
# 测试可观察行为（稳定）
def test_method_produces_expected_output():
    obj = MyClass()
    result = obj.method()
    assert result == expected_value  # 测试行为
```

## TDD 流程检查清单

在完成 TDD 循环后，验证：

- [ ] 所有测试通过
- [ ] 覆盖率达标
- [ ] 测试命名清晰
- [ ] 测试独立且可重复
- [ ] 无 Mock 滥用
- [ ] 代码经过重构
- [ ] 无测试私有方法
- [ ] 边界条件已测试

## 参考资源

- [Test-Driven Development with Claude Code](https://stevekinney.com/courses/ai-development/test-driven-development-with-claude)
- [TDD Guard for Claude Code](https://nizar.se/tdd-guard-for-claude-code/)
- [VoltAgent/awesome-claude-skills: TDD 相关 Skills](https://github.com/VoltAgent/awesome-claude-skills)

#!/usr/bin/env python3
"""Collect awesome-code planning context for autonomous agent selection."""

from __future__ import annotations

import json
import sys
from pathlib import Path
from typing import Any

from _config import get_nested, load_skill_config
from subagent_policy import find_missing_required_route_agents, load_required_routes


def _load_yaml_mapping(text: str) -> dict[str, Any]:
    try:
        import yaml  # type: ignore
    except Exception:
        return {}

    try:
        data = yaml.safe_load(text)
    except Exception:
        return {}
    return data if isinstance(data, dict) else {}


def _frontmatter(markdown: str) -> dict[str, Any]:
    if not markdown.startswith("---"):
        return {}
    parts = markdown.split("---", 2)
    if len(parts) < 3:
        return {}
    return _load_yaml_mapping(parts[1])


def _coerce_string_list(value: Any) -> list[str]:
    if not isinstance(value, list):
        return []
    return [str(item) for item in value if str(item).strip()]


class AgentCoordinator:
    """Gather deterministic context and constraints for the LLM planner."""

    def __init__(self, agents_root: Path | None = None) -> None:
        self.skill_root = Path(__file__).resolve().parent.parent
        self.agents_root = agents_root or (self.skill_root / "agents")
        self.config = load_skill_config(self.skill_root)
        self.enabled_agents = self._load_enabled_agents()
        self.fail_on_missing_required_agent = bool(
            get_nested(
                self.config,
                "multi_agent",
                "dispatch_policy",
                "fail_on_missing_required_agent",
                default=True,
            )
        )

    def _load_enabled_agents(self) -> set[str] | None:
        configured = get_nested(self.config, "multi_agent", "enabled_agents", default=None)
        if not isinstance(configured, list):
            return None
        enabled = {str(agent).strip() for agent in configured if str(agent).strip()}
        return enabled or None

    def collect_context(self, task_description: str) -> dict[str, Any]:
        available_agents = self.discover_agents()
        required_routes = load_required_routes(self.config)
        missing_required_agents = find_missing_required_route_agents(
            required_routes,
            {agent["role"] for agent in available_agents if agent["enabled"]},
        )
        dispatch_gate = self._build_dispatch_gate(missing_required_agents)

        return {
            "task": task_description,
            "planning_mode": "autonomous",
            "available_agents": available_agents,
            "agent_count": len(available_agents),
            "config_constraints": {
                "enabled_agents": sorted(self.enabled_agents) if self.enabled_agents else "all",
                "required_routes": required_routes,
                "dispatch_policy": {
                    "fail_on_missing_required_agent": self.fail_on_missing_required_agent,
                },
                "tdd": {
                    "framework": get_nested(self.config, "tdd", "framework", default="auto"),
                    "min_coverage": get_nested(self.config, "tdd", "min_coverage", default=None),
                },
                "code_review": {
                    "security_checks": get_nested(
                        self.config,
                        "code_review",
                        "security_checks",
                        default=None,
                    ),
                    "complexity_threshold": get_nested(
                        self.config,
                        "code_review",
                        "complexity_threshold",
                        default=None,
                    ),
                },
            },
            "dispatch_gate": dispatch_gate,
            "dispatch_guidance": {
                "planner_responsibility": [
                    "read the task and available agent descriptions",
                    "choose single-pass, focused-agent, parallel, or sequential execution",
                    "load only the selected agents' SKILL.md files",
                    "record dispatch_receipts for every required agent that is actually used",
                ],
                "minimal_change_scope_default": [
                    "files directly required by the requested behavior",
                    "tests that prove the requested behavior",
                ],
                "avoid": [
                    "unrelated formatting",
                    "opportunistic refactors",
                    "new abstractions without repeated complexity",
                ],
                "required_route_rule": (
                    "If the planner decides a configured required_route applies, all agents "
                    "listed for that route are required and missing agents must block execution."
                ),
            },
        }

    def analyze_task(self, task_description: str) -> dict[str, Any]:
        """Backward-compatible alias for callers that still use analyze_task."""
        return self.collect_context(task_description)

    def discover_agents(self) -> list[dict[str, Any]]:
        if not self.agents_root.exists():
            print(f"[awesome-code] warning: agents_root does not exist: {self.agents_root}", file=sys.stderr)
            return []

        agents: list[dict[str, Any]] = []
        for skill_file in sorted(self.agents_root.glob("*/SKILL.md")):
            role = skill_file.parent.name
            meta = _frontmatter(skill_file.read_text(encoding="utf-8"))
            metadata = meta.get("metadata", {})
            if not isinstance(metadata, dict):
                metadata = {}
            enabled = self.enabled_agents is None or role in self.enabled_agents
            agents.append(
                {
                    "role": role,
                    "name": str(meta.get("name") or role),
                    "description": str(meta.get("description") or ""),
                    "short_description": str(metadata.get("short-description") or ""),
                    "keywords": _coerce_string_list(metadata.get("keywords")),
                    "skill_path": str(skill_file),
                    "enabled": enabled,
                }
            )
        return agents

    def _build_dispatch_gate(self, missing_required_agents: list[str]) -> dict[str, Any]:
        can_proceed = not (self.fail_on_missing_required_agent and missing_required_agents)
        return {
            "can_proceed": can_proceed,
            "blocking_reason": "" if can_proceed else "configured required route agent unavailable",
            "missing_agents": missing_required_agents,
            "runtime_capability_required": bool(missing_required_agents),
        }


def main() -> None:
    if len(sys.argv) < 2:
        print("Usage: python3 agent_coordinator.py <task_description>")
        print("\nExample:")
        print('  python3 agent_coordinator.py "I need to fix a bug in the login feature"')
        sys.exit(1)

    task_description = " ".join(sys.argv[1:])
    coordinator = AgentCoordinator()
    print(json.dumps(coordinator.collect_context(task_description), indent=2, ensure_ascii=False))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Awesome Code - 缓存机制模块

提供 LRU 缓存、文件缓存等缓存机制，减少重复计算和 I/O 操作。
"""

from __future__ import annotations

import functools
import hashlib
import json
import pickle
import time
from datetime import datetime, timedelta
from functools import wraps
from pathlib import Path
from typing import Any, Callable, Dict, Optional, Tuple, TypeVar

F = TypeVar("F", bound=Callable[..., Any])


class LRUCache:
    """简单的 LRU (Least Recently Used) 缓存实现"""

    def __init__(self, capacity: int = 128):
        """
        初始化 LRU 缓存

        Args:
            capacity: 缓存容量（最大条目数）
        """
        self.capacity: int = capacity
        self.cache: Dict[str, Tuple[Any, float]] = {}

    def get(self, key: str) -> Optional[Any]:
        """
        获取缓存值

        Args:
            key: 缓存键

        Returns:
            缓存值，如果不存在或已过期则返回 None
        """
        if key in self.cache:
            value, _ = self.cache[key]
            # 更新访问时间
            self.cache[key] = (value, time.time())
            return value
        return None

    def set(self, key: str, value: Any) -> None:
        """
        设置缓存值

        Args:
            key: 缓存键
            value: 缓存值
        """
        # 如果缓存已满，删除最旧的条目
        if len(self.cache) >= self.capacity and key not in self.cache:
            # 找到最旧的条目（访问时间最早）
            oldest_key = min(self.cache.keys(), key=lambda k: self.cache[k][1])
            del self.cache[oldest_key]

        self.cache[key] = (value, time.time())

    def clear(self) -> None:
        """清空缓存"""
        self.cache.clear()

    def remove(self, key: str) -> bool:
        """
        删除指定缓存条目

        Args:
            key: 缓存键

        Returns:
            是否成功删除
        """
        if key in self.cache:
            del self.cache[key]
            return True
        return False

    def size(self) -> int:
        """获取当前缓存大小"""
        return len(self.cache)

    def keys(self) -> list[str]:
        """获取所有缓存键"""
        return list(self.cache.keys())


def lru_cache(
    maxsize: int = 128,
    key_func: Optional[Callable[..., str]] = None,
) -> Callable[[F], F]:
    """
    LRU 缓存装饰器

    Args:
        maxsize: 最大缓存大小
        key_func: 自定义键生成函数，接收函数参数返回缓存键

    Returns:
        装饰器函数

    示例:
        @lru_cache(maxsize=256)
        def expensive_function(x: int, y: int) -> int:
            return x * y

        # 使用自定义键生成函数
        @lru_cache(key_func=lambda self, x: f"user_{self.user_id}_{x}")
        def get_user_data(self, x: int) -> dict:
            ...
    """

    def decorator(func: F) -> F:
        cache: Dict[str, Tuple[Any, float]] = {}
        access_times: Dict[str, float] = {}

        @wraps(func)
        def wrapper(*args: Any, **kwargs: Any) -> Any:
            # 生成缓存键
            if key_func is not None:
                cache_key = key_func(*args, **kwargs)
            else:
                # 使用参数的哈希值作为键
                key_parts = [str(arg) for arg in args]
                key_parts.extend(f"{k}={v}" for k, v in sorted(kwargs.items()))
                key_str = ":".join(key_parts)
                cache_key = hashlib.md5(key_str.encode()).hexdigest()

            # 检查缓存
            if cache_key in cache:
                access_times[cache_key] = time.time()
                return cache[cache_key][0]

            # 执行函数
            result = func(*args, **kwargs)

            # 存储结果
            cache[cache_key] = (result, time.time())
            access_times[cache_key] = time.time()

            # 如果超过最大大小，删除最旧的条目
            if len(cache) > maxsize:
                oldest_key = min(access_times.keys(), key=lambda k: access_times[k])
                del cache[oldest_key]
                del access_times[oldest_key]

            return result

        # 添加缓存控制方法
        wrapper.cache_clear = lambda: (cache.clear(), access_times.clear())  # type: ignore[attr-defined]
        wrapper.cache_info = lambda: {  # type: ignore[attr-defined]
            "size": len(cache),
            "maxsize": maxsize,
        }

        return wrapper  # type: ignore[return-value]

    return decorator


class FileCache:
    """文件缓存系统"""

    def __init__(
        self,
        cache_dir: str | Path = ".bensz-api/skills/awesome-code/cache",
        ttl_seconds: int = 3600,
    ):
        """
        初始化文件缓存

        Args:
            cache_dir: 缓存目录路径
            ttl_seconds: 缓存过期时间（秒）
        """
        self.cache_dir = Path(cache_dir)
        self.cache_dir.mkdir(parents=True, exist_ok=True)
        self.ttl_seconds: int = ttl_seconds

    def _get_cache_path(self, key: str) -> Path:
        """获取缓存文件路径"""
        # 使用哈希值避免文件名冲突和特殊字符问题
        key_hash = hashlib.sha256(key.encode()).hexdigest()
        return self.cache_dir / f"{key_hash}.cache"

    def get(self, key: str) -> Optional[Any]:
        """
        获取缓存值

        Args:
            key: 缓存键

        Returns:
            缓存值，如果不存在或已过期则返回 None
        """
        cache_path = self._get_cache_path(key)

        if not cache_path.exists():
            return None

        try:
            # 读取缓存数据
            with open(cache_path, "rb") as f:
                data = pickle.load(f)

            # 检查是否过期
            cached_time = data.get("timestamp", 0)
            if time.time() - cached_time > self.ttl_seconds:
                cache_path.unlink()
                return None

            return data.get("value")
        except Exception:
            # 缓存文件损坏，删除并返回 None
            cache_path.unlink(missing_ok=True)
            return None

    def set(self, key: str, value: Any) -> None:
        """
        设置缓存值

        Args:
            key: 缓存键
            value: 缓存值
        """
        cache_path = self._get_cache_path(key)

        try:
            data = {
                "value": value,
                "timestamp": time.time(),
            }
            with open(cache_path, "wb") as f:
                pickle.dump(data, f)
        except Exception:
            # 写入失败，忽略
            pass

    def clear(self) -> None:
        """清空所有缓存"""
        for cache_file in self.cache_dir.glob("*.cache"):
            cache_file.unlink(missing_ok=True)

    def remove(self, key: str) -> bool:
        """
        删除指定缓存条目

        Args:
            key: 缓存键

        Returns:
            是否成功删除
        """
        cache_path = self._get_cache_path(key)
        if cache_path.exists():
            cache_path.unlink()
            return True
        return False

    def cleanup_expired(self) -> int:
        """
        清理过期的缓存文件

        Returns:
            清理的文件数量
        """
        count = 0
        for cache_file in self.cache_dir.glob("*.cache"):
            try:
                with open(cache_file, "rb") as f:
                    data = pickle.load(f)

                cached_time = data.get("timestamp", 0)
                if time.time() - cached_time > self.ttl_seconds:
                    cache_file.unlink()
                    count += 1
            except Exception:
                # 文件损坏，删除
                cache_file.unlink(missing_ok=True)
                count += 1
        return count


def file_cache(
    cache_dir: str | Path = ".bensz-api/skills/awesome-code/cache",
    ttl_seconds: int = 3600,
    key_func: Optional[Callable[..., str]] = None,
) -> Callable[[F], F]:
    """
    文件缓存装饰器

    Args:
        cache_dir: 缓存目录路径
        ttl_seconds: 缓存过期时间（秒）
        key_func: 自定义键生成函数

    Returns:
        装饰器函数

    示例:
        @file_cache(ttl_seconds=7200)
        def load_config(path: str) -> dict:
            ...
    """

    def decorator(func: F) -> F:
        file_cache_instance = FileCache(cache_dir=cache_dir, ttl_seconds=ttl_seconds)

        @wraps(func)
        def wrapper(*args: Any, **kwargs: Any) -> Any:
            # 生成缓存键
            if key_func is not None:
                cache_key = key_func(*args, **kwargs)
            else:
                key_parts = [func.__name__]
                key_parts.extend(str(arg) for arg in args)
                key_parts.extend(f"{k}={v}" for k, v in sorted(kwargs.items()))
                cache_key = ":".join(key_parts)

            # 尝试从缓存获取
            cached_value = file_cache_instance.get(cache_key)
            if cached_value is not None:
                return cached_value

            # 执行函数
            result = func(*args, **kwargs)

            # 存储到缓存
            file_cache_instance.set(cache_key, result)

            return result

        # 添加缓存控制方法
        wrapper.cache_clear = file_cache_instance.clear  # type: ignore[attr-defined]
        wrapper.cache_cleanup = file_cache_instance.cleanup_expired  # type: ignore[attr-defined]

        return wrapper  # type: ignore[return-value]

    return decorator


# 全局缓存实例（用于内存缓存）
_global_lru_cache = LRUCache(capacity=256)


def get_global_cache() -> LRUCache:
    """获取全局 LRU 缓存实例"""
    return _global_lru_cache


if __name__ == "__main__":
    # 示例用法

    # LRU 缓存装饰器
    @lru_cache(maxsize=128)
    def fibonacci(n: int) -> int:
        if n <= 1:
            return n
        return fibonacci(n - 1) + fibonacci(n - 2)

    print("fibonacci(100) =", fibonacci(100))
    print("缓存信息:", fibonacci.cache_info())

    # 文件缓存装饰器
    @file_cache(ttl_seconds=60)
    def load_json_data(url: str) -> dict:
        # 模拟加载远程数据
        return {"data": "sample", "url": url}

    print("\n首次加载:", load_json_data("https://example.com/data"))
    print("从缓存加载:", load_json_data("https://example.com/data"))

#!/usr/bin/env python3
"""
Awesome Code - 代码静态分析工具

功能：
- 代码复杂度分析
- 代码重复检测
- 命名规范检查
- 生成分析报告
"""

import argparse
import ast
import os
import re
import time
from collections import defaultdict
from pathlib import Path
from typing import Dict, List, Tuple


class CodeAnalyzer:
    """代码静态分析器"""

    def __init__(self, path: str = ".", complexity_threshold: int = 10):
        self.path = Path(path)
        self.complexity_threshold = complexity_threshold
        self.issues = []

    def analyze(self) -> Dict:
        """执行完整分析"""
        results = {
            "complexity": self.analyze_complexity(),
            "duplication": self.analyze_duplication(),
            "naming": self.analyze_naming(),
            "summary": self.generate_summary(),
        }
        return results

    def analyze_complexity(self) -> List[Dict]:
        """分析代码复杂度（圈复杂度）"""
        complexities = []

        for py_file in self.path.rglob("*.py"):
            if any(skip in str(py_file) for skip in ["__pycache__", ".venv"]):
                continue

            try:
                with open(py_file, "r", encoding="utf-8") as f:
                    tree = ast.parse(f.read(), filename=str(py_file))

                for node in ast.walk(tree):
                    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
                        complexity = self.calculate_complexity(node)

                        if complexity > self.complexity_threshold:
                            complexities.append({
                                "file": str(py_file.relative_to(self.path)),
                                "function": node.name,
                                "line": node.lineno,
                                "complexity": complexity,
                                "threshold": self.complexity_threshold,
                            })

            except Exception as e:
                self.issues.append(f"解析 {py_file} 失败: {e}")

        return complexities

    def calculate_complexity(self, node: ast.AST) -> int:
        """计算圈复杂度"""
        complexity = 1  # 基础复杂度

        for child in ast.walk(node):
            if isinstance(child, (
                ast.If, ast.While, ast.For, ast.AsyncFor,
                ast.ExceptHandler, ast.With, ast.AsyncWith
            )):
                complexity += 1
            elif isinstance(child, ast.BoolOp):
                complexity += len(child.values) - 1

        return complexity

    def analyze_duplication(self) -> List[Dict]:
        """分析代码重复"""
        # 简化的重复检测：查找重复的函数名和类名
        names = defaultdict(list)

        for py_file in self.path.rglob("*.py"):
            if any(skip in str(py_file) for skip in ["__pycache__", ".venv"]):
                continue

            try:
                with open(py_file, "r", encoding="utf-8") as f:
                    tree = ast.parse(f.read(), filename=str(py_file))

                for node in ast.walk(tree):
                    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
                        names[node.name].append({
                            "file": str(py_file.relative_to(self.path)),
                            "line": node.lineno,
                        })
                    elif isinstance(node, ast.ClassDef):
                        names[f"class:{node.name}"].append({
                            "file": str(py_file.relative_to(self.path)),
                            "line": node.lineno,
                        })

            except Exception:
                pass

        # 找出重复的定义
        duplications = []
        for name, locations in names.items():
            if len(locations) > 1:
                duplications.append({
                    "name": name,
                    "count": len(locations),
                    "locations": locations,
                })

        return duplications

    def analyze_naming(self) -> List[Dict]:
        """分析命名规范"""
        issues = []

        # 命名规范
        function_pattern = re.compile(r"^[a-z][a-z0-9_]*$")  # snake_case
        class_pattern = re.compile(r"^[A-Z][a-zA-Z0-9]*$")  # PascalCase
        constant_like_pattern = re.compile(r"^[A-Za-z0-9_]+$")  # simple identifiers

        for py_file in self.path.rglob("*.py"):
            if any(skip in str(py_file) for skip in ["__pycache__", ".venv"]):
                continue

            try:
                with open(py_file, "r", encoding="utf-8") as f:
                    tree = ast.parse(f.read(), filename=str(py_file))

                for node in ast.walk(tree):
                    # 检查函数命名
                    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
                        if not function_pattern.match(node.name):
                            issues.append({
                                "type": "function_naming",
                                "file": str(py_file.relative_to(self.path)),
                                "name": node.name,
                                "line": node.lineno,
                                "suggestion": "函数名应使用 snake_case",
                            })

                    # 检查类命名
                    elif isinstance(node, ast.ClassDef):
                        if not class_pattern.match(node.name):
                            issues.append({
                                "type": "class_naming",
                                "file": str(py_file.relative_to(self.path)),
                                "name": node.name,
                                "line": node.lineno,
                                "suggestion": "类名应使用 PascalCase",
                            })

                # 检查常量命名（模块级赋值，启发式：带下划线且大小写混用）
                # 例如: Api_KEY, my_CONST, Max_Value
                for stmt in getattr(tree, "body", []):
                    if not isinstance(stmt, ast.Assign):
                        continue
                    for target in stmt.targets:
                        if not isinstance(target, ast.Name):
                            continue
                        name = target.id
                        if not constant_like_pattern.match(name):
                            continue
                        if "_" not in name:
                            continue
                        if re.search(r"[A-Z]", name) and re.search(r"[a-z]", name):
                            issues.append({
                                "type": "constant_naming",
                                "file": str(py_file.relative_to(self.path)),
                                "name": name,
                                "line": stmt.lineno,
                                "suggestion": "疑似常量但大小写混用，建议使用 UPPER_CASE",
                            })

            except Exception:
                pass

        return issues

    def generate_summary(self) -> Dict:
        """生成分析摘要"""
        return {
            "total_issues": len(self.issues),
            "issues": self.issues,
        }


class ReportGenerator:
    """报告生成器"""

    def __init__(self, results: Dict, output_file: str = None):
        self.results = results
        self.output_file = output_file

    def generate_markdown(self) -> str:
        """生成 Markdown 格式报告"""
        report = []

        report.append("# 代码分析报告\n")
        report.append(f"生成时间: {time.strftime('%Y-%m-%d %H:%M:%S')}\n")

        # 复杂度报告
        report.append("## 📊 代码复杂度\n")
        if self.results["complexity"]:
            report.append(f"⚠️ 发现 {len(self.results['complexity'])} 个高复杂度函数:\n\n")
            for item in self.results["complexity"]:
                report.append(
                    f"- **{item['function']}** ({item['file']}:{item['line']})\n"
                    f"  - 复杂度: {item['complexity']} (阈值: {item['threshold']})\n"
                )
        else:
            report.append("✅ 未发现高复杂度函数\n")

        # 重复代码报告
        report.append("\n## 🔄 代码重复\n")
        if self.results["duplication"]:
            report.append(f"⚠️ 发现 {len(self.results['duplication'])} 个重复定义:\n\n")
            for item in self.results["duplication"]:
                report.append(f"- **{item['name']}** ({item['count']} 处)\n")
                for loc in item["locations"]:
                    report.append(f"  - {loc['file']}:{loc['line']}\n")
        else:
            report.append("✅ 未发现重复定义\n")

        # 命名规范报告
        report.append("\n## 📝 命名规范\n")
        if self.results["naming"]:
            report.append(f"⚠️ 发现 {len(self.results['naming'])} 个命名问题:\n\n")
            for item in self.results["naming"]:
                report.append(
                    f"- **{item['type']}**: {item['name']} "
                    f"({item['file']}:{item['line']})\n"
                    f"  - {item['suggestion']}\n"
                )
        else:
            report.append("✅ 命名规范检查通过\n")

        # 摘要
        if self.results["summary"]["total_issues"] > 0:
            report.append("\n## ⚠️ 其他问题\n")
            for issue in self.results["summary"]["issues"]:
                report.append(f"- {issue}\n")

        return "".join(report)

    def save_report(self) -> None:
        """保存报告到文件"""
        if not self.output_file:
            return

        content = self.generate_markdown()

        output_path = Path(self.output_file)
        output_path.parent.mkdir(parents=True, exist_ok=True)

        with open(output_path, "w", encoding="utf-8") as f:
            f.write(content)

        print(f"📄 报告已保存到: {output_path}")

    def print_report(self) -> None:
        """打印报告到控制台"""
        print(self.generate_markdown())


def main():
    """主函数"""
    parser = argparse.ArgumentParser(
        description="Awesome Code - 代码静态分析工具",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
示例：
  # 分析当前目录
  %(prog)s

  # 分析指定目录
  %(prog)s --path src/

  # 设置复杂度阈值为 15
  %(prog)s --complexity-threshold 15

  # 生成报告文件
  %(prog)s --report analysis_report.md
        """,
    )

    parser.add_argument(
        "--path", "-p",
        default=".",
        help="要分析的目录路径（默认: 当前目录）",
    )

    parser.add_argument(
        "--complexity-threshold", "-c",
        type=int,
        default=10,
        help="圈复杂度阈值（默认: 10）",
    )

    parser.add_argument(
        "--report", "-r",
        help="输出报告文件路径（Markdown 格式）",
    )

    args = parser.parse_args()

    # 执行分析
    analyzer = CodeAnalyzer(
        path=args.path,
        complexity_threshold=args.complexity_threshold,
    )

    results = analyzer.analyze()

    # 生成报告
    generator = ReportGenerator(results, output_file=args.report)
    generator.print_report()

    if args.report:
        generator.save_report()


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
from __future__ import annotations

import argparse
import datetime as dt
import re
import shutil
import sys
import typing
from pathlib import Path

from _config import get_nested, load_skill_config


def _generate_test_id(now: dt.datetime) -> str:
    return f"v{now:%Y%m%d%H%M}"


def _ensure_dir(path: Path) -> None:
    path.mkdir(parents=True, exist_ok=True)


def _safe_write(path: Path, content: str, *, overwrite: bool) -> None:
    if path.exists() and not overwrite:
        raise FileExistsError(
            f"Refusing to overwrite existing file: {path}\n"
            f"Hint: Use --overwrite to force overwrite existing files."
        )
    path.write_text(content, encoding="utf-8")


_TEST_ID_RE = re.compile(r"^v\d{12}$")


def _validate_test_id(parser: argparse.ArgumentParser, test_id: str) -> str:
    test_id = test_id.strip()
    if not _TEST_ID_RE.fullmatch(test_id):
        _fail(parser, "test id must match vYYYYMMDDHHMM (e.g. v202601170020)")
    return test_id


def _ensure_within_root(parser: argparse.ArgumentParser, root: Path, path: Path, what: str) -> Path:
    root_resolved = root.resolve()
    path_resolved = path.resolve()
    try:
        path_resolved.relative_to(root_resolved)
    except Exception:
        _fail(parser, f"{what} escapes the allowed root: {path}")
    return path_resolved


def _validate_rel_dir(parser: argparse.ArgumentParser, value: object, what: str) -> Path:
    p = Path(str(value))
    # Disallow absolute paths and parent traversal; allow nested relative dirs like "plans/a".
    if p.is_absolute() or p.anchor:
        _fail(parser, f"{what} must be a relative path, got: {p}")
    if any(part in {"..", ""} for part in p.parts):
        _fail(parser, f"{what} must not contain '..' segments, got: {p}")
    return p


def _render_template(template: str, *, values: dict[str, str]) -> str:
    rendered = template
    for key, value in values.items():
        rendered = rendered.replace(f"{{{{{key}}}}}", value)
    return rendered


def _copy_or_template(
    *,
    dst_path: Path,
    src_path: Path | None,
    template_path: Path | None,
    template_values: dict[str, str] | None,
    overwrite: bool,
) -> None:
    if dst_path.exists() and not overwrite:
        return

    if src_path is not None and src_path.exists():
        if dst_path.exists():
            dst_path.unlink()
        shutil.copyfile(src_path, dst_path)
        return

    if template_path is not None and template_path.exists():
        template_text = template_path.read_text(encoding="utf-8")
        if template_values:
            template_text = _render_template(template_text, values=template_values)
        _safe_write(dst_path, template_text, overwrite=overwrite)
        return

    session_name = (template_values or {}).get("SESSION_NAME", "")
    a_test_id = (template_values or {}).get("A_TEST_ID", "")
    extra = f"\n**关联A轮测试ID**: {a_test_id}\n" if a_test_id else "\n"
    _safe_write(
        dst_path,
        "# 轻量测试计划（TEST_PLAN）\n\n"
        f"**测试会话**: {session_name}\n"
        + extra
        + "\n（未找到可复制的计划文档或模板，请手动补全）\n",
        overwrite=overwrite,
    )


def _normalize_kind(kind: str) -> str:
    kind = kind.strip().lower()
    if kind in {"a", "a_round", "a-round"}:
        return "a"
    if kind in {"b", "b_round", "b-round"}:
        return "b"
    raise ValueError("kind must be 'a' or 'b'")


def _fail(parser: argparse.ArgumentParser, message: str) -> typing.NoReturn:
    parser.print_usage(sys.stderr)
    print(f"error: {message}", file=sys.stderr)
    raise SystemExit(2)


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Create an awesome-code test session skeleton (A round or B round).",
    )
    parser.add_argument(
        "--skill-root",
        required=True,
        help="Target Skill root directory (must contain SKILL.md).",
    )
    parser.add_argument(
        "--kind",
        default="a",
        help="Session kind: a (default) or b.",
    )
    parser.add_argument(
        "--id",
        default="",
        help="Explicit test id like vYYYYMMDDHHMM (optional).",
    )
    parser.add_argument(
        "--a-test-id",
        default="",
        help="For B round only: the associated A round test id (vYYYYMMDDHHMM).",
    )
    parser.add_argument(
        "--create-plan",
        action="store_true",
        help="Create missing plan doc skeleton under plans/ (optional).",
    )
    parser.add_argument(
        "--seed-test-plan-from-plan",
        action="store_true",
        help="If plan doc exists, seed TEST_PLAN.md from it (optional).",
    )
    parser.add_argument(
        "--overwrite",
        action="store_true",
        help="Overwrite existing session files (not recommended).",
    )
    args = parser.parse_args()

    skill_root = Path(args.skill_root).expanduser().resolve()
    if not skill_root.exists() or not skill_root.is_dir():
        _fail(parser, f"--skill-root does not exist or is not a directory: {skill_root}")
    if not (skill_root / "SKILL.md").exists():
        _fail(parser, f"--skill-root is not a Skill directory (missing SKILL.md): {skill_root}")

    try:
        kind = _normalize_kind(args.kind)
    except ValueError as exc:
        _fail(parser, str(exc))
    now = dt.datetime.now()
    test_id = _validate_test_id(parser, args.id.strip() or _generate_test_id(now))
    a_test_id = args.a_test_id.strip()
    if kind == "b":
        if not a_test_id:
            _fail(parser, "--a-test-id is required for B round")
        a_test_id = _validate_test_id(parser, a_test_id)
    else:
        a_test_id = ""

    config = load_skill_config(skill_root)
    plans_dir_name = get_nested(config, "ab_test_optimization", "plans_dir", default="plans")
    tests_dir_name = get_nested(config, "ab_test_optimization", "tests_dir", default="tests")

    plans_rel = _validate_rel_dir(parser, plans_dir_name, "plans_dir")
    tests_rel = _validate_rel_dir(parser, tests_dir_name, "tests_dir")

    plans_dir = skill_root / plans_rel
    tests_dir = skill_root / tests_rel
    templates_dir = skill_root / "templates"

    _ensure_within_root(parser, skill_root, plans_dir, "plans dir")
    _ensure_within_root(parser, skill_root, tests_dir, "tests dir")

    _ensure_dir(plans_dir)
    _ensure_dir(tests_dir)

    template_values = {
        "TEST_ID": test_id,
        "A_TEST_ID": a_test_id,
        "TARGET_SKILL_NAME": skill_root.name,
        "TARGET_SKILL_ROOT": str(skill_root),
        "PLAN_TIME": now.isoformat(timespec="minutes"),
        "CHECK_TIME": now.isoformat(timespec="minutes"),
        "PLAN_DATE": now.date().isoformat(),
    }

    if kind == "a":
        session_name = test_id
        test_plan_template = templates_dir / "TEST_PLAN_TEMPLATE.md"
        plan_doc_path = plans_dir / f"{test_id}.md"
        plan_template = templates_dir / "OPTIMIZATION_PLAN_TEMPLATE.md"
        round_kind = "A轮"
    else:
        session_name = f"B轮-{test_id}"
        test_plan_template = templates_dir / "TEST_PLAN_TEMPLATE.md"
        plan_doc_path = plans_dir / f"B轮-{test_id}.md"
        plan_template = templates_dir / "B_ROUND_CHECK_TEMPLATE.md"
        round_kind = "B轮"

    template_values["ROUND_KIND"] = round_kind
    template_values["SESSION_NAME"] = session_name
    # Security: prevent path traversal even if config/inputs change in the future.
    _ensure_within_root(parser, skill_root, plan_doc_path, "plan doc path")
    template_values["PLAN_DOC_PATH"] = str(plan_doc_path.relative_to(skill_root))

    if args.create_plan and (not plan_doc_path.exists() or args.overwrite):
        if plan_template.exists():
            _safe_write(
                plan_doc_path,
                _render_template(plan_template.read_text(encoding="utf-8"), values=template_values),
                overwrite=args.overwrite,
            )
        else:
            a_hint = f"\n\n**关联A轮测试ID**: {a_test_id}\n" if a_test_id else "\n"
            _safe_write(
                plan_doc_path,
                f"# 计划文档（{session_name}）\n"
                + a_hint
                + "\n（未找到模板，请手动补全）\n",
                overwrite=args.overwrite,
            )

    session_dir = tests_dir / session_name
    _ensure_within_root(parser, skill_root, session_dir, "session dir")
    _ensure_dir(session_dir)
    _ensure_dir(session_dir / "_artifacts")
    _ensure_dir(session_dir / "_scripts")

    _copy_or_template(
        dst_path=session_dir / "TEST_PLAN.md",
        src_path=plan_doc_path if (args.seed_test_plan_from_plan and plan_doc_path.exists()) else None,
        template_path=test_plan_template if test_plan_template.exists() else None,
        template_values=template_values,
        overwrite=args.overwrite,
    )

    report_path = session_dir / "TEST_REPORT.md"
    test_report_template = templates_dir / "TEST_REPORT_TEMPLATE.md"
    if not report_path.exists() or args.overwrite:
        if test_report_template.exists():
            _safe_write(
                report_path,
                _render_template(test_report_template.read_text(encoding="utf-8"), values=template_values),
                overwrite=args.overwrite,
            )
        else:
            a_hint = f"\n**关联A轮测试ID**: {a_test_id}\n\n" if a_test_id else "\n"
            _safe_write(
                report_path,
                "# 测试报告（TEST_REPORT）\n\n"
                f"**测试会话**: {session_name}\n\n"
                + a_hint
                + "## 结果\n\n"
                "- 状态：✅ 通过 / ❌ 失败 / ⚠️ 部分通过\n\n"
                "## 证据\n\n"
                "- （填入命令输出、文件路径、对比结果等）\n",
                overwrite=args.overwrite,
            )

    print(str(session_dir))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3
"""
Awesome Code - 技能路径获取工具

这是一个硬编码的引导脚本，用于获取技能的真实安装路径。
AI 可以通过这个脚本动态获取技能路径，然后构建正确的调用命令。

输出格式：JSON（便于 AI 解析）
"""

from __future__ import annotations

import json
import sys
from pathlib import Path
from typing import Dict


def main() -> int:
    """主函数：输出技能路径的 JSON 映射"""
    # 获取脚本所在技能的根目录
    skill_root: Path = Path(__file__).resolve().parent.parent

    # 构建路径映射
    paths: Dict[str, str | Dict[str, str]] = {
        "skill_root": str(skill_root),
        "skill_name": skill_root.name,
        "scripts_dir": str(skill_root / "scripts"),
        "config_file": str(skill_root / "config.yaml"),
        "skill_file": str(skill_root / "SKILL.md"),
        "references_dir": str(skill_root / "references"),
        "templates_dir": str(skill_root / "templates"),
    }

    # 获取所有可执行脚本的路径
    scripts_dir = skill_root / "scripts"
    if scripts_dir.exists():
        paths["executable_scripts"] = {}
        executable_scripts: Dict[str, str] = paths["executable_scripts"]  # type: ignore[assignment]
        for script_file in scripts_dir.glob("*.py"):
            script_name = script_file.stem
            executable_scripts[script_name] = str(script_file)

        for script_file in scripts_dir.glob("*.sh"):
            script_name = script_file.stem
            executable_scripts[script_name] = str(script_file)

    # 输出 JSON 格式
    print(json.dumps(paths, ensure_ascii=False, indent=2))
    return 0


if __name__ == "__main__":
    sys.exit(main())

#!/bin/bash
#
# Awesome Code - Git 工作流辅助脚本
#
# 功能：
# - Conventional Commits 提交
# - PR 模板生成
# - 分支管理辅助
#

set -e  # 遇到错误立即退出

# 颜色定义
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color

# 打印带颜色的消息
print_info() {
    echo -e "${BLUE}ℹ️  $1${NC}"
}

print_success() {
    echo -e "${GREEN}✅ $1${NC}"
}

print_warning() {
    echo -e "${YELLOW}⚠️  $1${NC}"
}

print_error() {
    echo -e "${RED}❌ $1${NC}"
}

# 检查是否在 Git 仓库中
check_git_repo() {
    if ! git rev-parse --git-dir > /dev/null 2>&1; then
        print_error "当前目录不是 Git 仓库"
        exit 1
    fi
}

# Conventional Commits 提交
commit_conventional() {
    check_git_repo

    print_info "Conventional Commits 提交向导"

    # 选择类型
    echo ""
    echo "选择提交类型："
    echo "  1) feat     - 新功能"
    echo "  2) fix      - Bug 修复"
    echo "  3) docs     - 文档变更"
    echo "  4) style    - 代码格式（不影响功能）"
    echo "  5) refactor - 重构"
    echo "  6) perf     - 性能优化"
    echo "  7) test     - 测试相关"
    echo "  8) chore    - 构建/工具变更"
    echo "  9) ci       - CI 配置"
    read -p "选择 [1-9]: " type_choice

    case $type_choice in
        1) type="feat" ;;
        2) type="fix" ;;
        3) type="docs" ;;
        4) type="style" ;;
        5) type="refactor" ;;
        6) type="perf" ;;
        7) type="test" ;;
        8) type="chore" ;;
        9) type="ci" ;;
        *)
            print_error "无效选择"
            exit 1
            ;;
    esac

    # 输入范围（可选）
    read -p "输入范围（可选，按 Enter 跳过）: " scope

    # 输入主题
    read -p "输入提交主题（必填）: " subject

    if [ -z "$subject" ]; then
        print_error "提交主题不能为空"
        exit 1
    fi

    # 构建提交标题
    if [ -n "$scope" ]; then
        commit_title="$type($scope): $subject"
    else
        commit_title="$type: $subject"
    fi

    # 输入正文（可选）
    echo ""
    read -p "输入提交正文（可选，按 Enter 跳过）: " body

    # 输入 Footer（可选）
    read -p "输入 Footer（可选，如 Closes #123，按 Enter 跳过）: " footer

    # 构建完整提交消息
    commit_message="$commit_title"

    if [ -n "$body" ]; then
        commit_message="$commit_message"$'\n\n'"$body"
    fi

    if [ -n "$footer" ]; then
        commit_message="$commit_message"$'\n\n'"$footer"
    fi

    # 显示提交消息预览
    echo ""
    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
    echo "$commit_message"
    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
    echo ""

    read -p "确认提交？[y/N] " confirm

    if [ "$confirm" = "y" ] || [ "$confirm" = "Y" ]; then
        git commit -m "$commit_message"
        print_success "提交成功！"
    else
        print_warning "已取消提交"
    fi
}

# 创建新分支
create_branch() {
    check_git_repo

    print_info "创建新分支"

    # 选择分支类型
    echo ""
    echo "选择分支类型："
    echo "  1) feature  - 功能开发"
    echo "  2) bugfix   - Bug 修复"
    echo "  3) hotfix   - 紧急修复"
    echo "  4) release  - 发布版本"
    read -p "选择 [1-4]: " type_choice

    case $type_choice in
        1) prefix="feature" ;;
        2) prefix="bugfix" ;;
        3) prefix="hotfix" ;;
        4) prefix="release" ;;
        *)
            print_error "无效选择"
            exit 1
            ;;
    esac

    # 输入分支名称
    read -p "输入分支名称: " branch_name

    if [ -z "$branch_name" ]; then
        print_error "分支名称不能为空"
        exit 1
    fi

    full_branch_name="$prefix/$branch_name"

    # 确保在 main 分支
    current_branch=$(git branch --show-current)
    if [ "$current_branch" != "main" ] && [ "$current_branch" != "master" ]; then
        print_warning "当前不在 main/master 分支"
        read -p "是否切换到 main 分支？[y/N] " switch_confirm
        if [ "$switch_confirm" = "y" ] || [ "$switch_confirm" = "Y" ]; then
            git checkout main || git checkout master
        fi
    fi

    # 拉取最新代码
    print_info "拉取最新代码..."
    git pull

    # 创建并切换到新分支
    print_info "创建分支: $full_branch_name"
    git checkout -b "$full_branch_name"

    print_success "分支创建成功！当前分支: $full_branch_name"
}

# PR 模板生成
generate_pr_template() {
    cat << 'EOF'
## 📋 变更类型
- [ ] `feat` 新功能
- [ ] `fix` Bug 修复
- [ ] `refactor` 重构
- [ ] `docs` 文档
- [ ] `style` 代码格式
- [ ] `test` 测试
- [ ] `chore` 构建/工具

## 📝 变更说明
<!-- 简要描述这个 PR 的目的和实现方式 -->



## 🧪 测试
- [ ] 添加了单元测试
- [ ] 添加了集成测试
- [ ] 手动测试通过
- [ ] 性能测试通过（如适用）

## ✅ 检查清单
- [ ] 代码符合团队规范
- [ ] 自我审查完成
- [ ] 注释充分且准确
- [ ] 文档已更新
- [ ] 无新的警告产生
- [ ] 测试覆盖率未降低

## 📸 截图/演示（可选）
<!-- 添加 UI 变更的截图 -->



## 🔗 相关链接
- 关联 Issue:

EOF
}

# 创建 PR
create_pr() {
    check_git_repo

    # 检查是否安装了 GitHub CLI
    if ! command -v gh &> /dev/null; then
        print_error "未安装 GitHub CLI (gh)"
        print_info "安装: https://cli.github.com/"
        exit 1
    fi

    print_info "创建 Pull Request"

    # 获取当前分支
    current_branch=$(git branch --show-current)
    base_branch="main"

    # 检查是否有未推送的提交
    if git log origin/"$current_branch".."$current_branch" &> /dev/null; then
        print_warning "有未推送的提交"
        read -p "是否先推送？[y/N] " push_confirm
        if [ "$push_confirm" = "y" ] || [ "$push_confirm" = "Y" ]; then
            git push -u origin "$current_branch"
        fi
    fi

    # 生成 PR 标题（基于最近的提交）
    pr_title=$(git log -1 --pretty=%s)

    # 生成 PR 模板
    pr_body=$(generate_pr_template)

    # 使用 gh 创建 PR
    print_info "创建 PR: $current_branch -> $base_branch"
    echo "$pr_body" | gh pr create \
        --base "$base_branch" \
        --title "$pr_title" \
        --body-file -

    print_success "PR 创建成功！"
}

# 显示帮助
show_help() {
    cat << EOF
Awesome Code - Git 工作流辅助脚本

用法:
    $0 <command> [options]

命令:
    commit      使用 Conventional Commits 规范提交
    branch      创建新分支（遵循命名规范）
    pr          创建 Pull Request
    template    输出 PR 模板

示例:
    $0 commit           # 交互式提交
    $0 branch           # 创建新分支
    $0 pr               # 创建 PR
    $0 template > pr.md # 保存 PR 模板

更多信息请参考:
    https://github.com/anthropics/skills
EOF
}

# 主函数
main() {
    case "${1:-}" in
        commit)
            commit_conventional
            ;;
        branch)
            create_branch
            ;;
        pr)
            create_pr
            ;;
        template)
            generate_pr_template
            ;;
        help|--help|-h)
            show_help
            ;;
        *)
            print_error "未知命令: ${1:-}"
            echo ""
            show_help
            exit 1
            ;;
    esac
}

main "$@"

#!/usr/bin/env python3
"""
Awesome Code - 结构化日志模块

提供统一的日志配置和结构化日志支持。
便于调试和监控。
"""

from __future__ import annotations

import logging
import sys
from datetime import datetime
from enum import Enum
from pathlib import Path
from typing import Any, Dict, Optional


class LogLevel(Enum):
    """日志级别"""

    DEBUG = logging.DEBUG
    INFO = logging.INFO
    WARNING = logging.WARNING
    ERROR = logging.ERROR
    CRITICAL = logging.CRITICAL


class LogFormat(Enum):
    """日志格式类型"""

    SIMPLE = "simple"
    DETAILED = "detailed"
    JSON = "json"


class AwesomeLogger:
    """结构化日志器"""

    # 类级别的日志器缓存
    _loggers: Dict[str, logging.Logger] = {}

    @classmethod
    def get_logger(
        cls,
        name: str = "awesome-code",
        level: LogLevel = LogLevel.INFO,
        log_format: LogFormat = LogFormat.DETAILED,
        log_file: Optional[str | Path] = None,
    ) -> logging.Logger:
        """
        获取配置好的日志器实例

        Args:
            name: 日志器名称
            level: 日志级别
            log_format: 日志格式
            log_file: 日志文件路径（可选）

        Returns:
            配置好的日志器实例
        """
        if name in cls._loggers:
            return cls._loggers[name]

        logger = logging.getLogger(name)
        logger.setLevel(level.value)

        # 清除已有的处理器
        logger.handlers.clear()

        # 格式化器
        formatter = cls._get_formatter(log_format)

        # 控制台处理器
        console_handler = logging.StreamHandler(sys.stdout)
        console_handler.setFormatter(formatter)
        console_handler.setLevel(level.value)
        logger.addHandler(console_handler)

        # 文件处理器（如果指定）
        if log_file:
            log_path = Path(log_file)
            log_path.parent.mkdir(parents=True, exist_ok=True)
            file_handler = logging.FileHandler(log_path, encoding="utf-8")
            file_handler.setFormatter(formatter)
            file_handler.setLevel(level.value)
            logger.addHandler(file_handler)

        cls._loggers[name] = logger
        return logger

    @classmethod
    def _get_formatter(cls, log_format: LogFormat) -> logging.Formatter:
        """获取日志格式化器"""
        if log_format == LogFormat.SIMPLE:
            return logging.Formatter("%(message)s")

        elif log_format == LogFormat.DETAILED:
            return logging.Formatter(
                "%(asctime)s | %(levelname)-8s | %(name)s | %(funcName)s:%(lineno)d | %(message)s",
                datefmt="%Y-%m-%d %H:%M:%S",
            )

        elif log_format == LogFormat.JSON:
            return JSONFormatter()

        return logging.Formatter("%(message)s")

    @classmethod
    def configure_from_config(cls, config: Dict[str, Any]) -> logging.Logger:
        """
        从配置字典创建日志器

        Args:
            config: 配置字典，包含 level, format, log_file 等键

        Returns:
            配置好的日志器实例
        """
        level_str = config.get("level", "info").upper()
        level = LogLevel[level_str] if level_str in LogLevel.__members__ else LogLevel.INFO

        format_str = config.get("format", "detailed").lower()
        log_format = LogFormat[format_str.upper()] if format_str in LogFormat.__members__ else LogFormat.DETAILED

        log_file = config.get("log_file")

        return cls.get_logger(
            name=config.get("name", "awesome-code"),
            level=level,
            log_format=log_format,
            log_file=log_file,
        )


class JSONFormatter(logging.Formatter):
    """JSON 格式化器"""

    def format(self, record: logging.LogRecord) -> str:
        """格式化日志记录为 JSON"""
        import json

        log_data: Dict[str, Any] = {
            "timestamp": datetime.fromtimestamp(record.created).isoformat(),
            "level": record.levelname,
            "logger": record.name,
            "message": record.getMessage(),
            "module": record.module,
            "function": record.funcName,
            "line": record.lineno,
        }

        # 添加异常信息（如果有）
        if record.exc_info:
            log_data["exception"] = self.formatException(record.exc_info)

        return json.dumps(log_data, ensure_ascii=False)


class StructuredLogger:
    """结构化日志上下文管理器"""

    def __init__(
        self,
        logger: logging.Logger,
        context: Dict[str, Any],
    ):
        self.logger = logger
        self.context = context
        self.old_factory = logging.getLogRecordFactory()

    def _record_factory(self, *args: Any, **kwargs: Any) -> logging.LogRecord:
        record = self.old_factory(*args, **kwargs)
        # 添加上下文信息
        for key, value in self.context.items():
            setattr(record, key, value)
        return record

    def __enter__(self) -> StructuredLogger:
        logging.setLogRecordFactory(self._record_factory)
        return self

    def __exit__(self, *args: Any) -> None:
        logging.setLogRecordFactory(self.old_factory)


def log_execution(
    logger: Optional[logging.Logger] = None,
    level: LogLevel = LogLevel.INFO,
) -> Any:
    """
    装饰器：记录函数执行

    Args:
        logger: 日志器实例（默认使用 awesome-code 日志器）
        level: 日志级别

    Returns:
        装饰器函数
    """

    def decorator(func: Any) -> Any:
        def wrapper(*args: Any, **kwargs: Any) -> Any:
            nonlocal logger
            if logger is None:
                logger = AwesomeLogger.get_logger()

            func_name = func.__name__
            logger.log(level.value, f"开始执行: {func_name}")

            try:
                result = func(*args, **kwargs)
                logger.log(level.value, f"完成执行: {func_name}")
                return result
            except Exception as e:
                logger.log(LogLevel.ERROR.value, f"执行失败: {func_name} - {e}")
                raise

        return wrapper

    return decorator


# 默认日志器实例
default_logger = AwesomeLogger.get_logger()


def debug(message: str, *args: Any, **kwargs: Any) -> None:
    """记录 DEBUG 级别日志"""
    default_logger.debug(message, *args, **kwargs)


def info(message: str, *args: Any, **kwargs: Any) -> None:
    """记录 INFO 级别日志"""
    default_logger.info(message, *args, **kwargs)


def warning(message: str, *args: Any, **kwargs: Any) -> None:
    """记录 WARNING 级别日志"""
    default_logger.warning(message, *args, **kwargs)


def error(message: str, *args: Any, **kwargs: Any) -> None:
    """记录 ERROR 级别日志"""
    default_logger.error(message, *args, **kwargs)


def critical(message: str, *args: Any, **kwargs: Any) -> None:
    """记录 CRITICAL 级别日志"""
    default_logger.critical(message, *args, **kwargs)


if __name__ == "__main__":
    # 示例用法
    logger = AwesomeLogger.get_logger(
        name="awesome-code",
        level=LogLevel.DEBUG,
        log_format=LogFormat.DETAILED,
    )

    logger.debug("这是一条调试消息")
    logger.info("这是一条信息消息")
    logger.warning("这是一条警告消息")
    logger.error("这是一条错误消息")

    # 使用结构化日志上下文
    with StructuredLogger(logger, context={"user_id": "12345", "request_id": "abc-123"}):
        logger.info("处理用户请求")

    # 使用装饰器
    @log_execution(logger, LogLevel.INFO)
    def example_function(x: int, y: int) -> int:
        return x + y

    example_function(1, 2)

#!/usr/bin/env python3
"""
Mirror Optimizer - 镜像源优化脚本

自动检测项目使用的包管理器，生成适配的国内镜像源配置。
支持 Docker、Python、Node.js、Go、Java、Ruby、Rust 等多种技术栈。
"""

from pathlib import Path
from typing import Dict, List, Optional, Tuple
from urllib.parse import urlparse
import json

from _config import get_nested, load_skill_config

# 默认镜像源配置（当 config.yaml 缺失/不可读时的回退）
DEFAULT_PROVIDERS = {
    "aliyun": {
        "name": "阿里云",
        "priority": 1,
        "docker": "https://registry.cn-hangzhou.aliyuncs.com",
        "python": "https://mirrors.aliyun.com/pypi/simple/",
        "nodejs": "https://registry.npmmirror.com",
        "golang": "https://mirrors.aliyun.com/goproxy/",
        "java_maven": "https://maven.aliyun.com/repository/public",
        "java_gradle": "https://maven.aliyun.com/repository/public",
        "ruby": "https://gems.ruby-china.com",
        "rust": "https://mirrors.aliyun.com/crates.io-index/",
    },
    "tencent": {
        "name": "腾讯云",
        "priority": 2,
        "docker": "https://mirror.ccs.tencentyun.com",
        "python": "https://mirrors.cloud.tencent.com/pypi/simple/",
        "nodejs": "https://mirrors.cloud.tencent.com/npm/",
        "golang": "https://mirrors.tencent.com/go/",
        "java_maven": "https://mirrors.cloud.tencent.com/nexus/repository/maven-public/",
        "java_gradle": "https://mirrors.cloud.tencent.com/nexus/repository/maven-public/",
    },
    "tsinghua": {
        "name": "清华大学",
        "priority": 3,
        "docker": None,
        "python": "https://pypi.tuna.tsinghua.edu.cn/simple",
        "nodejs": None,
        "golang": None,
        "java_maven": None,
        "java_gradle": None,
        "rust": "https://mirrors.tuna.tsinghua.edu.cn/git/crates.io-index.git",
    },
    "ustc": {
        "name": "中国科技大学",
        "priority": 4,
        "docker": None,
        "python": "https://mirrors.ustc.edu.cn/pypi/web/simple",
        "nodejs": None,
        "golang": "https://go-mirror.ustc.edu.cn/",
        "java_maven": None,
        "java_gradle": None,
        "rust": "https://mirrors.ustc.edu.cn/crates.io-index",
    },
}


# 包管理器检测规则（当 config.yaml 缺失/不可读时的回退）
DEFAULT_PACKAGE_MANAGERS = {
    "docker": {
        "files": ["Dockerfile", "docker-compose.yml", "docker-compose.yaml", ".dockerignore"],
        "config_dir": "docker",
        "priority": 10,
    },
    "python": {
        "files": ["requirements.txt", "pyproject.toml", "Pipfile", "setup.py", "setup.cfg", "poetry.lock"],
        "config_dir": "python",
        "priority": 9,
    },
    "nodejs": {
        "files": ["package.json", "yarn.lock", "pnpm-lock.yaml", "package-lock.json"],
        "config_dir": "nodejs",
        "priority": 8,
    },
    "golang": {
        "files": ["go.mod", "go.sum", "Gopkg.lock", "Gopkg.toml"],
        "config_dir": "golang",
        "priority": 7,
    },
    "java_maven": {
        "files": ["pom.xml"],
        "config_dir": "java/maven",
        "priority": 6,
    },
    "java_gradle": {
        "files": ["build.gradle", "build.gradle.kts", "settings.gradle", "settings.gradle.kts", "gradle.properties"],
        "config_dir": "java/gradle",
        "priority": 6,
    },
    "ruby": {
        "files": ["Gemfile", "gems.rb"],
        "config_dir": "ruby",
        "priority": 5,
    },
    "rust": {
        "files": ["Cargo.toml", "Cargo.lock"],
        "config_dir": "rust",
        "priority": 3,
    },
}


class MirrorOptimizer:
    """镜像源优化器"""

    def __init__(
        self,
        project_root: Path,
        preferred_provider: Optional[str] = None,
        skill_root: Optional[Path] = None,
    ):
        """
        初始化镜像源优化器

        Args:
            project_root: 项目根目录
            preferred_provider: 首选镜像源提供商 (aliyun, tencent, tsinghua 等)
        """
        self.project_root = Path(project_root).resolve()
        self._validate_project_root()

        self.skill_root = skill_root or Path(__file__).resolve().parent.parent
        config = load_skill_config(self.skill_root)
        mirror_config = get_nested(config, "mirror_optimization", default={})
        mirror_config = mirror_config if isinstance(mirror_config, dict) else {}

        self.providers = mirror_config.get("providers")
        if not isinstance(self.providers, dict) or not self.providers:
            self.providers = DEFAULT_PROVIDERS

        self.package_managers = mirror_config.get("package_managers")
        if not isinstance(self.package_managers, dict) or not self.package_managers:
            self.package_managers = DEFAULT_PACKAGE_MANAGERS

        default_provider = mirror_config.get("default_provider")
        provider = preferred_provider or default_provider or "aliyun"
        self.preferred_provider = str(provider).strip().lower()
        self.output_dir_name = str(mirror_config.get("output_dir", ".bensz-api/skills/mirror-optimizer/output"))
        self._validate_output_dir()
        self.generate_report_enabled = bool(mirror_config.get("generate_report", True))

        self.detected_managers: List[Dict[str, str]] = []
        self.mirror_dir = self.project_root / self.output_dir_name
        self.used_providers: Dict[str, str] = {}
        self.skipped_managers: List[Dict[str, str]] = []
        self._provider_cache: Dict[str, Tuple[str, str]] = {}

    def _validate_project_root(self) -> None:
        if not self.project_root.exists() or not self.project_root.is_dir():
            raise ValueError(f"项目根目录不存在或不是目录: {self.project_root}")

    def _validate_output_dir(self) -> None:
        output_dir = Path(self.output_dir_name)
        if output_dir.is_absolute() or any(part in {"..", ""} for part in output_dir.parts):
            raise ValueError(f"镜像源输出目录必须是相对路径: {self.output_dir_name}")

    def _validate_config_dir(self, config_dir: object, manager_type: str) -> str:
        if config_dir is None:
            raise ValueError(f"{manager_type} 缺少 config_dir 配置")
        path = Path(str(config_dir))
        if path.is_absolute() or any(part in {"..", ""} for part in path.parts):
            raise ValueError(f"{manager_type} config_dir 必须是相对路径: {config_dir}")
        return str(path)

    def _select_provider(self, manager_type: str) -> Tuple[str, str]:
        preferred = self.preferred_provider
        preferred_cfg = self.providers.get(preferred, {})
        preferred_url = preferred_cfg.get(manager_type) if isinstance(preferred_cfg, dict) else None
        if preferred_url:
            return preferred, preferred_url

        candidates: List[Tuple[int, str, str]] = []
        for name, cfg in self.providers.items():
            if not isinstance(cfg, dict):
                continue
            mirror_url = cfg.get(manager_type)
            if not mirror_url:
                continue
            priority = cfg.get("priority", 999)
            candidates.append((int(priority) if str(priority).isdigit() else 999, name, mirror_url))

        if candidates:
            candidates.sort(key=lambda x: (x[0], x[1]))
            return candidates[0][1], candidates[0][2]

        raise ValueError(f"未找到可用的镜像源提供商: {manager_type}")

    def _get_provider(self, manager_type: str) -> Tuple[str, str]:
        if manager_type in self._provider_cache:
            return self._provider_cache[manager_type]
        provider_name, mirror_url = self._select_provider(manager_type)
        self._provider_cache[manager_type] = (provider_name, mirror_url)
        self.used_providers[manager_type] = provider_name
        return provider_name, mirror_url

    @staticmethod
    def _extract_host(url: str) -> str:
        parsed = urlparse(url)
        return parsed.netloc or ""

    def detect_package_managers(self) -> List[Dict]:
        """
        检测项目中使用的包管理器

        Returns:
            检测到的包管理器列表（按优先级排序）
        """
        detected = []

        for manager_type, config in self.package_managers.items():
            if not isinstance(config, dict):
                self.skipped_managers.append({"type": manager_type, "reason": "配置格式错误（非字典）"})
                continue
            files = config.get("files")
            if not isinstance(files, list) or not files:
                self.skipped_managers.append({"type": manager_type, "reason": "缺少 files 列表"})
                continue
            try:
                config_dir = self._validate_config_dir(config.get("config_dir"), manager_type)
            except ValueError as exc:
                self.skipped_managers.append({"type": manager_type, "reason": str(exc)})
                continue
            priority_raw = config.get("priority", 0)
            try:
                priority = int(priority_raw)
            except Exception:
                priority = 0

            for file_pattern in files:
                file_path = self.project_root / file_pattern
                if file_path.exists():
                    detected.append({
                        "type": manager_type,
                        "config_dir": config_dir,
                        "priority": priority,
                        "detected_by": file_pattern,
                    })
                    break

        # 按优先级排序
        detected.sort(key=lambda x: x["priority"], reverse=True)
        self.detected_managers = detected

        return detected

    def generate_dockerfile_mirror(self, dockerfile_path: Path) -> Optional[str]:
        """
        生成优化的 Dockerfile（包含镜像源配置）

        Args:
            dockerfile_path: 原始 Dockerfile 路径

        Returns:
            优化后的 Dockerfile 内容
        """
        if not dockerfile_path.exists():
            return None

        original_content = dockerfile_path.read_text(encoding="utf-8")
        lines = original_content.split("\n")
        mirror_content = []
        inserted_mirror = False

        for i, line in enumerate(lines):
            mirror_content.append(line)

            # 在 FROM 指令后插入镜像源配置
            if line.strip().startswith("FROM") and not inserted_mirror:
                base_image = line.split()[1] if len(line.split()) > 1 else ""

                # 根据基础镜像类型选择镜像源
                mirror_config = self._get_docker_mirror_config(base_image)
                if mirror_config:
                    mirror_content.append("")
                    mirror_content.append("# 国内镜像源配置（使用构建参数控制是否启用）")
                    mirror_content.append("ARG USE_CHINA_MIRROR=false")
                    mirror_content.append("")
                    mirror_content.extend(mirror_config.split("\n"))
                    mirror_content.append("")
                    inserted_mirror = True

        return "\n".join(mirror_content)

    def _get_docker_mirror_config(self, base_image: str) -> str:
        """
        根据基础镜像获取镜像源配置

        Args:
            base_image: 基础镜像名称

        Returns:
            镜像源配置内容
        """
        provider_name, mirror_source = self._get_provider("docker")

        if "alpine" in base_image.lower():
            return f"""# Alpine 镜像源
RUN if [ "$USE_CHINA_MIRROR" = "true" ]; then \\
        sed -i 's/dl-cdn.alpinelinux.org/{mirror_source.split("//")[1]}/g' /etc/apk/repositories && \\
        echo "已切换到 {provider_name} Alpine 镜像源"; \\
    fi"""

        elif "ubuntu" in base_image.lower() or "debian" in base_image.lower():
            return f"""# Ubuntu/Debian 镜像源
RUN if [ "$USE_CHINA_MIRROR" = "true" ]; then \\
        sed -i 's@http://archive.ubuntu.com/@{mirror_source}/@g' /etc/apt/sources.list && \\
        sed -i 's@http://security.ubuntu.com/@{mirror_source}/@g' /etc/apt/sources.list && \\
        echo "已切换到 {provider_name} APT 镜像源"; \\
    fi"""

        elif "centos" in base_image.lower():
            return f"""# CentOS 镜像源
RUN if [ "$USE_CHINA_MIRROR" = "true" ]; then \\
        sed -i 's/mirrorlist=/#mirrorlist=/g' /etc/yum.repos.d/CentOS-*.repo && \\
        sed -i 's|#baseurl=http://mirror.centos.org|baseurl={mirror_source}|g' /etc/yum.repos.d/CentOS-*.repo && \\
        echo "已切换到 {provider_name} YUM 镜像源"; \\
    fi"""

        return "# 未识别的基础镜像类型，请手动配置镜像源"

    def generate_pip_config(self) -> str:
        """生成 pip 配置文件"""
        _, mirror_url = self._get_provider("python")
        trusted_host = self._extract_host(mirror_url)
        trusted_lines = f"trusted-host = {trusted_host}\n" if trusted_host else ""
        return f"""[global]
index-url = {mirror_url}
{trusted_lines}
[install]
{trusted_lines}"""

    def generate_npm_config(self) -> str:
        """生成 npm 配置文件"""
        _, mirror_url = self._get_provider("nodejs")
        return f"""registry={mirror_url}
"""

    def generate_yarn_config(self) -> str:
        """生成 yarn 配置文件"""
        _, mirror_url = self._get_provider("nodejs")
        return f"""npmRegistryServer: "{mirror_url}"
"""

    def generate_go_env(self) -> str:
        """生成 Go Modules 环境配置"""
        _, mirror_url = self._get_provider("golang")
        return f"""GOPROXY={mirror_url},direct
GOSUMDB=off
"""

    def generate_maven_settings(self) -> str:
        """生成 Maven settings.xml"""
        _, mirror_url = self._get_provider("java_maven")
        return f"""<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
          http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <mirrors>
    <mirror>
      <id>aliyun-maven</id>
      <name>Aliyun Maven Mirror</name>
      <url>{mirror_url}</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
</settings>
"""

    def generate_gradle_init(self) -> str:
        """生成 Gradle init.gradle"""
        _, mirror_url = self._get_provider("java_gradle")
        return f"""allprojects {{
    repositories {{
        maven {{ url '{mirror_url}' }}
        mavenCentral()
    }}
}}
"""

    def generate_bundle_config(self) -> str:
        """生成 Bundler 配置"""
        _, mirror_url = self._get_provider("ruby")
        return f"""---
BUNDLE_MIRROR_URL: "{mirror_url}"
"""

    def generate_cargo_config(self) -> str:
        """生成 Cargo 配置"""
        provider_name, mirror_url = self._get_provider("rust")
        return f"""[source.crates-io]
replace-with = '{provider_name}'

[source.{provider_name}]
registry = "{mirror_url}"
"""

    def generate_configs(self) -> Dict[str, str]:
        """
        为检测到的所有包管理器生成配置文件

        Returns:
            配置文件路径到内容的映射
        """
        configs = {}

        for manager in self.detected_managers:
            manager_type = manager["type"]
            config_dir = manager["config_dir"]

            try:
                if manager_type == "docker":
                    dockerfile_path = self.project_root / "Dockerfile"
                    mirror_dockerfile = self.generate_dockerfile_mirror(dockerfile_path)
                    if mirror_dockerfile:
                        configs[f"{self.output_dir_name}/{config_dir}/Dockerfile.mirror"] = mirror_dockerfile

                elif manager_type == "python":
                    configs[f"{self.output_dir_name}/{config_dir}/pip.conf"] = self.generate_pip_config()

                elif manager_type == "nodejs":
                    # 检测是否使用 yarn
                    if (self.project_root / "yarn.lock").exists():
                        configs[f"{self.output_dir_name}/{config_dir}/.yarnrc.yml"] = self.generate_yarn_config()
                    else:
                        configs[f"{self.output_dir_name}/{config_dir}/.npmrc"] = self.generate_npm_config()

                elif manager_type == "golang":
                    configs[f"{self.output_dir_name}/{config_dir}/go.env"] = self.generate_go_env()

                elif manager_type == "java_maven":
                    configs[f"{self.output_dir_name}/{config_dir}/settings.xml"] = self.generate_maven_settings()

                elif manager_type == "java_gradle":
                    configs[f"{self.output_dir_name}/{config_dir}/init.gradle"] = self.generate_gradle_init()

                elif manager_type == "ruby":
                    configs[f"{self.output_dir_name}/{config_dir}/config"] = self.generate_bundle_config()

                elif manager_type == "rust":
                    configs[f"{self.output_dir_name}/{config_dir}/config.toml"] = self.generate_cargo_config()
            except ValueError as exc:
                self.skipped_managers.append({"type": manager_type, "reason": str(exc)})

        return configs

    def write_configs(self, configs: Dict[str, str]) -> List[Path]:
        """
        将配置写入文件

        Args:
            configs: 配置文件路径到内容的映射

        Returns:
            写入的文件路径列表
        """
        written_files = []

        # 创建配置输出目录
        self.mirror_dir.mkdir(parents=True, exist_ok=True)

        for file_path, content in configs.items():
            full_path = self.project_root / file_path
            full_path.parent.mkdir(parents=True, exist_ok=True)
            full_path.write_text(content, encoding="utf-8")
            written_files.append(full_path)

        return written_files

    def generate_report(self) -> str:
        """
        生成镜像源优化报告

        Returns:
            Markdown 格式的报告内容
        """
        report = ["# 镜像源优化报告", "", f"**项目路径**: `{self.project_root}`", "",
                  "## 检测结果", "", f"检测到 **{len(self.detected_managers)}** 个包管理器：", ""]

        for manager in self.detected_managers:
            manager_type = manager["type"]
            provider = self.used_providers.get(manager_type, "未选择")
            report.append(
                f"- **{manager_type.upper()}**: 通过 `{manager['detected_by']}` 检测（provider: {provider})"
            )

        report.extend(["", "## 配置文件", "", "已生成的配置文件：", ""])

        # 列出所有生成的配置文件
        if self.mirror_dir.exists():
            for config_file in sorted(self.mirror_dir.rglob("*")):
                if config_file.is_file():
                    rel_path = config_file.relative_to(self.project_root)
                    report.append(f"- `{rel_path}`")
        if self.skipped_managers:
            report.extend(["", "## 跳过的包管理器", ""])
            for item in self.skipped_managers:
                report.append(f"- **{item['type'].upper()}**: {item['reason']}")

        detected_types = {m["type"] for m in self.detected_managers}
        use_yarn = (self.project_root / "yarn.lock").exists()

        report.extend(["", "## 使用方法", ""])
        if "docker" in detected_types:
            report.extend(["### Docker 镜像源", "",
                          "构建时启用国内镜像源：", "",
                          "```bash",
                          "docker build --build-arg USE_CHINA_MIRROR=true -t your-image .",
                          "```", ""])

        if "python" in detected_types:
            report.extend(["### Python pip", "",
                          "复制配置文件到用户目录：", "",
                          "```bash",
                          "mkdir -p ~/.pip",
                          f"cp {self.output_dir_name}/python/pip.conf ~/.pip/",
                          "```", ""])

        if "nodejs" in detected_types:
            if use_yarn:
                report.extend(["### Node.js yarn", "",
                              "复制配置文件到项目目录：", "",
                              "```bash",
                              f"cp {self.output_dir_name}/nodejs/.yarnrc.yml ./",
                              "```", ""])
            else:
                report.extend(["### Node.js npm", "",
                              "复制配置文件到项目目录：", "",
                              "```bash",
                              f"cp {self.output_dir_name}/nodejs/.npmrc ./",
                              "```", ""])

        if "golang" in detected_types:
            try:
                go_proxy = self._get_provider("golang")[1]
            except Exception:
                go_proxy = "https://mirrors.aliyun.com/goproxy/"
            report.extend(["### Go Modules", "",
                          "设置环境变量：", "",
                          "```bash",
                          f"export GOPROXY={go_proxy},direct",
                          "```",
                          "或使用配置文件：", "",
                          "```bash",
                          f"cp {self.output_dir_name}/golang/go.env ~/.config/go/env",
                          "```", ""])

        if "java_maven" in detected_types:
            report.extend(["### Java Maven", "",
                          "复制配置文件到 Maven 目录：", "",
                          "```bash",
                          "mkdir -p ~/.m2",
                          f"cp {self.output_dir_name}/java/maven/settings.xml ~/.m2/",
                          "```", ""])

        if "java_gradle" in detected_types:
            report.extend(["### Java Gradle", "",
                          "复制配置文件到 Gradle 目录：", "",
                          "```bash",
                          "mkdir -p ~/.gradle",
                          f"cp {self.output_dir_name}/java/gradle/init.gradle ~/.gradle/init.gradle",
                          "```", ""])

        if "ruby" in detected_types:
            report.extend(["### Ruby Bundler", "",
                          "复制配置文件到 Bundler 目录：", "",
                          "```bash",
                          "mkdir -p ~/.bundle",
                          f"cp {self.output_dir_name}/ruby/config ~/.bundle/config",
                          "```", ""])

        if "rust" in detected_types:
            report.extend(["### Rust Cargo", "",
                          "复制配置文件到 Cargo 目录：", "",
                          "```bash",
                          "mkdir -p ~/.cargo",
                          f"cp {self.output_dir_name}/rust/config.toml ~/.cargo/config.toml",
                          "```", ""])

        report.extend(["", "## 验证镜像源", "", "验证配置是否生效：", ""])
        if "python" in detected_types:
            report.extend(["```bash", "pip config list", "```"])
        if "nodejs" in detected_types:
            if use_yarn:
                report.extend(["```bash", "yarn config get npmRegistryServer", "```"])
            else:
                report.extend(["```bash", "npm config get registry", "```"])
        if "golang" in detected_types:
            report.extend(["```bash", "go env GOPROXY", "```"])
        if "java_maven" in detected_types:
            report.extend(["```bash", "mvn help:evaluate -Dexpression=settings.repositories -q -DforceStdout", "```"])
        if "java_gradle" in detected_types:
            report.extend(["```bash", f"cat {self.output_dir_name}/java/gradle/init.gradle", "```"])
        if "ruby" in detected_types:
            report.extend(["```bash", f"cat {self.output_dir_name}/ruby/config", "```"])
        if "rust" in detected_types:
            report.extend(["```bash", f"cat {self.output_dir_name}/rust/config.toml", "```"])

        report.extend(["", "## 切换回官方源", "",
                      "如需切换回官方源，删除相应配置文件即可：", "",
                      "```bash"])
        if "python" in detected_types:
            report.extend(["# Python", "rm ~/.pip/pip.conf", ""])
        if "nodejs" in detected_types:
            if use_yarn:
                report.extend(["# Node.js (yarn)", "rm .yarnrc.yml", ""])
            else:
                report.extend(["# Node.js (npm)", "rm .npmrc", ""])
        if "golang" in detected_types:
            report.extend(["# Go", "unset GOPROXY", ""])
        if "docker" in detected_types:
            report.extend(["# Docker", "# 重新构建时不传 USE_CHINA_MIRROR 参数", ""])
        report.extend(["```", "", "---", "",
                      f"*由 awesome-code/mirror-optimizer 生成 | 首选镜像源提供商: {self.preferred_provider}*"])

        return "\n".join(report)

    def optimize(self) -> Dict:
        """
        执行完整的镜像源优化流程

        Returns:
            优化结果字典
        """
        # 检测包管理器
        detected = self.detect_package_managers()

        if not detected:
            return {
                "success": False,
                "message": "未检测到任何需要配置镜像源的包管理器",
                "detected_managers": [],
                "skipped_managers": self.skipped_managers,
            }

        # 生成配置文件
        configs = self.generate_configs()
        if not configs:
            return {
                "success": False,
                "message": "检测到包管理器，但未生成任何镜像源配置",
                "detected_managers": detected,
                "skipped_managers": self.skipped_managers,
            }

        # 写入配置文件
        written_files = self.write_configs(configs)

        # 生成报告
        report_path = None
        if self.generate_report_enabled:
            report_content = self.generate_report()
            report_path = self.mirror_dir / "MIRROR_OPTIMIZATION_REPORT.md"
            report_path.write_text(report_content, encoding="utf-8")

        return {
            "success": True,
            "message": f"成功为 {len(detected)} 个包管理器配置镜像源",
            "detected_managers": detected,
            "config_files": [str(f.relative_to(self.project_root)) for f in written_files],
            "report_path": str(report_path.relative_to(self.project_root)) if report_path else None,
            "mirror_dir": str(self.mirror_dir.relative_to(self.project_root)),
            "skipped_managers": self.skipped_managers,
        }


def main():
    """命令行入口"""
    import sys

    project_path = sys.argv[1] if len(sys.argv) > 1 else Path.cwd()

    try:
        optimizer = MirrorOptimizer(project_path)
        result = optimizer.optimize()
    except Exception as exc:
        result = {
            "success": False,
            "message": f"镜像源优化失败: {exc}",
        }

    # 输出 JSON 格式结果
    print(json.dumps(result, ensure_ascii=False, indent=2))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Awesome Code - 性能基准测试工具

用于为关键路径建立性能基准、记录性能数据并生成趋势图。
支持性能回归检测。
"""

from __future__ import annotations

import argparse
import json
import statistics
import time
from dataclasses import dataclass, field
from datetime import datetime
from functools import wraps
from pathlib import Path
from typing import Any, Callable, Dict, List, Optional, TypeVar

F = TypeVar("F", bound=Callable[..., Any])


@dataclass
class BenchmarkResult:
    """单次基准测试结果"""

    name: str
    iterations: int
    total_time: float
    avg_time: float
    min_time: float
    max_time: float
    median_time: float
    std_dev: float
    timestamp: str = field(default_factory=lambda: datetime.now().isoformat())


@dataclass
class BenchmarkHistory:
    """基准测试历史记录"""

    name: str
    results: List[BenchmarkResult] = field(default_factory=list)
    baseline: Optional[BenchmarkResult] = None
    regression_threshold: float = 0.2  # 20% 回归阈值


class BenchmarkRunner:
    """性能基准测试运行器"""

    def __init__(
        self,
        output_dir: str | Path = ".bensz-api/skills/awesome-code/output/benchmarks",
        warmup_iterations: int = 3,
        benchmark_iterations: int = 100,
    ):
        self.output_dir = Path(output_dir)
        self.output_dir.mkdir(parents=True, exist_ok=True)
        self.warmup_iterations = warmup_iterations
        self.benchmark_iterations = benchmark_iterations
        self.history: Dict[str, BenchmarkHistory] = {}
        self._load_history()

    def _load_history(self) -> None:
        """从文件加载历史记录"""
        history_file = self.output_dir / "history.json"
        if history_file.exists():
            try:
                data = json.loads(history_file.read_text(encoding="utf-8"))
                for name, history_data in data.items():
                    results = [
                        BenchmarkResult(**r) for r in history_data.get("results", [])
                    ]
                    baseline_data = history_data.get("baseline")
                    baseline = BenchmarkResult(**baseline_data) if baseline_data else None
                    self.history[name] = BenchmarkHistory(
                        name=name,
                        results=results,
                        baseline=baseline,
                        regression_threshold=history_data.get("regression_threshold", 0.2),
                    )
            except Exception as e:
                print(f"警告：加载历史记录失败: {e}")

    def _save_history(self) -> None:
        """保存历史记录到文件"""
        history_file = self.output_dir / "history.json"
        data: Dict[str, Dict[str, Any]] = {}
        for name, history in self.history.items():
            data[name] = {
                "name": history.name,
                "results": [
                    {
                        "name": r.name,
                        "iterations": r.iterations,
                        "total_time": r.total_time,
                        "avg_time": r.avg_time,
                        "min_time": r.min_time,
                        "max_time": r.max_time,
                        "median_time": r.median_time,
                        "std_dev": r.std_dev,
                        "timestamp": r.timestamp,
                    }
                    for r in history.results
                ],
                "baseline": (
                    {
                        "name": history.baseline.name,
                        "iterations": history.baseline.iterations,
                        "total_time": history.baseline.total_time,
                        "avg_time": history.baseline.avg_time,
                        "min_time": history.baseline.min_time,
                        "max_time": history.baseline.max_time,
                        "median_time": history.baseline.median_time,
                        "std_dev": history.baseline.std_dev,
                        "timestamp": history.baseline.timestamp,
                    }
                    if history.baseline
                    else None
                ),
                "regression_threshold": history.regression_threshold,
            }
        history_file.write_text(json.dumps(data, indent=2), encoding="utf-8")

    def benchmark(
        self,
        name: str,
        func: F | None = None,
        *,
        iterations: int | None = None,
    ) -> F | Callable[[F], F]:
        """装饰器或上下文管理器：对函数进行基准测试"""

        def decorator(f: F) -> F:
            @wraps(f)
            def wrapper(*args: Any, **kwargs: Any) -> Any:
                # 预热
                for _ in range(self.warmup_iterations):
                    f(*args, **kwargs)

                # 基准测试
                iters = iterations or self.benchmark_iterations
                times: List[float] = []
                for _ in range(iters):
                    start = time.perf_counter()
                    result = f(*args, **kwargs)
                    end = time.perf_counter()
                    times.append(end - start)

                # 计算统计信息
                total_time = sum(times)
                avg_time = total_time / len(times)
                min_time = min(times)
                max_time = max(times)
                median_time = statistics.median(times)
                std_dev = statistics.stdev(times) if len(times) > 1 else 0.0

                result_obj = BenchmarkResult(
                    name=name,
                    iterations=iters,
                    total_time=total_time,
                    avg_time=avg_time,
                    min_time=min_time,
                    max_time=max_time,
                    median_time=median_time,  # type: ignore[arg-type]
                    std_dev=std_dev,
                )

                self._record_result(result_obj)
                return result

            return wrapper  # type: ignore[return-value]

        if func is not None:
            return decorator(func)
        return decorator

    def _record_result(self, result: BenchmarkResult) -> None:
        """记录基准测试结果"""
        if result.name not in self.history:
            self.history[result.name] = BenchmarkHistory(name=result.name)

        history = self.history[result.name]
        history.results.append(result)

        # 检查性能回归
        if history.baseline:
            baseline = history.baseline
            if result.avg_time > baseline.avg_time * (1 + history.regression_threshold):
                print(
                    f"⚠️  性能回归检测: {result.name}\n"
                    f"    当前平均时间: {result.avg_time:.6f}s\n"
                    f"    基线平均时间: {baseline.avg_time:.6f}s\n"
                    f"    回退程度: {(result.avg_time / baseline.avg_time - 1) * 100:.2f}%"
                )
            else:
                print(
                    f"✅ {result.name}: 平均 {result.avg_time:.6f}s "
                    f"(最小: {result.min_time:.6f}s, 最大: {result.max_time:.6f}s)"
                )
        else:
            print(
                f"📊 {result.name}: 平均 {result.avg_time:.6f}s "
                f"(最小: {result.min_time:.6f}s, 最大: {result.max_time:.6f}s) "
                f"[设为新基线]"
            )
            history.baseline = result

        self._save_history()

    def set_baseline(self, name: str, index: int | None = None) -> None:
        """设置指定基准测试结果为基线"""
        if name not in self.history:
            print(f"错误：未找到基准测试 '{name}'")
            return

        history = self.history[name]
        if not history.results:
            print(f"错误：基准测试 '{name}' 没有结果")
            return

        if index is None:
            # 使用最新结果
            history.baseline = history.results[-1]
        else:
            if 0 <= index < len(history.results):
                history.baseline = history.results[index]
            else:
                print(f"错误：索引 {index} 超出范围")
                return

        print(f"✅ 已设置 '{name}' 的基线")
        self._save_history()

    def compare(self, name: str, index1: int, index2: int) -> None:
        """比较两次基准测试结果"""
        if name not in self.history:
            print(f"错误：未找到基准测试 '{name}'")
            return

        history = self.history[name]
        if not (0 <= index1 < len(history.results) and 0 <= index2 < len(history.results)):
            print(f"错误：索引超出范围")
            return

        result1 = history.results[index1]
        result2 = history.results[index2]

        diff_pct = (result2.avg_time - result1.avg_time) / result1.avg_time * 100

        print(f"\n📊 比较: {name}")
        print(f"  运行 #{index1 + 1} ({result1.timestamp}): {result1.avg_time:.6f}s")
        print(f"  运行 #{index2 + 1} ({result2.timestamp}): {result2.avg_time:.6f}s")
        print(f"  差异: {diff_pct:+.2f}%")

    def report(self, name: str | None = None) -> None:
        """生成性能报告"""
        if name:
            if name not in self.history:
                print(f"错误：未找到基准测试 '{name}'")
                return
            self._print_single_report(self.history[name])
        else:
            for history in self.history.values():
                self._print_single_report(history)

    def _print_single_report(self, history: BenchmarkHistory) -> None:
        """打印单个基准测试的报告"""
        print(f"\n{'='*60}")
        print(f"基准测试: {history.name}")
        print(f"{'='*60}")

        if history.baseline:
            b = history.baseline
            print(f"基线 (运行时间: {b.timestamp}):")
            print(f"  平均: {b.avg_time:.6f}s")
            print(f"  最小: {b.min_time:.6f}s")
            print(f"  最大: {b.max_time:.6f}s")
            print(f"  中位数: {b.median_time:.6f}s")
            print(f"  标准差: {b.std_dev:.6f}s")

        if history.results:
            latest = history.results[-1]
            print(f"\n最新结果 (运行时间: {latest.timestamp}):")
            print(f"  平均: {latest.avg_time:.6f}s")
            print(f"  最小: {latest.min_time:.6f}s")
            print(f"  最大: {latest.max_time:.6f}s")
            print(f"  中位数: {latest.median_time:.6f}s")
            print(f"  标准差: {latest.std_dev:.6f}s")

            if history.baseline:
                change_pct = (latest.avg_time - history.baseline.avg_time) / history.baseline.avg_time * 100
                print(f"  相对基线变化: {change_pct:+.2f}%")

        print(f"\n总运行次数: {len(history.results)}")


def main() -> int:
    """命令行接口"""
    parser = argparse.ArgumentParser(
        description="Awesome Code - 性能基准测试工具",
    )
    parser.add_argument(
        "--output-dir",
        default=".bensz-api/skills/awesome-code/output/benchmarks",
        help="输出目录（默认: .bensz-api/skills/awesome-code/output/benchmarks）",
    )
    parser.add_argument(
        "--iterations",
        type=int,
        default=100,
        help="每次基准测试的迭代次数（默认: 100）",
    )
    parser.add_argument(
        "--warmup",
        type=int,
        default=3,
        help="预热迭代次数（默认: 3）",
    )

    subparsers = parser.add_subparsers(dest="command", help="子命令")

    # report 命令
    report_parser = subparsers.add_parser("report", help="生成性能报告")
    report_parser.add_argument("--name", help="基准测试名称（可选）")

    # baseline 命令
    baseline_parser = subparsers.add_parser("baseline", help="设置基线")
    baseline_parser.add_argument("name", help="基准测试名称")
    baseline_parser.add_argument("--index", type=int, help="结果索引（默认: 最新）")

    # compare 命令
    compare_parser = subparsers.add_parser("compare", help="比较两次结果")
    compare_parser.add_argument("name", help="基准测试名称")
    compare_parser.add_argument("index1", type=int, help="第一次结果索引")
    compare_parser.add_argument("index2", type=int, help="第二次结果索引")

    args = parser.parse_args()

    runner = BenchmarkRunner(
        output_dir=args.output_dir,
        warmup_iterations=args.warmup,
        benchmark_iterations=args.iterations,
    )

    if args.command == "report":
        runner.report(args.name)
    elif args.command == "baseline":
        runner.set_baseline(args.name, args.index)
    elif args.command == "compare":
        runner.compare(args.name, args.index1, args.index2)
    else:
        parser.print_help()
        return 1

    return 0


if __name__ == "__main__":
    import sys
    sys.exit(main())

#!/usr/bin/env python3
from __future__ import annotations

from typing import Any, Iterable


def build_dispatch_manifest(analysis: dict[str, Any]) -> list[dict[str, Any]]:
    manifest: list[dict[str, Any]] = []
    for dispatch_level in ("required_agents", "preferred_agents", "optional_agents"):
        level = dispatch_level.replace("_agents", "")
        for agent in analysis.get(dispatch_level, []):
            manifest.append(
                {
                    "role": agent["role"],
                    "dispatch_level": level,
                    "reason": agent.get("reason", ""),
                    "policy_source": agent.get("policy_source", ""),
                    "status": "pending",
                    "skill_path": agent.get("skill_path"),
                }
            )
    return manifest


def record_dispatch_receipt(role: str, status: str, evidence: str) -> dict[str, str]:
    return {
        "role": role,
        "status": status,
        "evidence": evidence,
    }


def validate_dispatch_completion(
    manifest: Iterable[dict[str, Any]],
    receipts: Iterable[dict[str, Any]],
) -> dict[str, Any]:
    receipt_by_role = {
        str(receipt.get("role")): receipt
        for receipt in receipts
        if receipt.get("role")
    }
    missing_required_receipts: list[str] = []
    warnings: list[str] = []

    for entry in manifest:
        role = str(entry.get("role", ""))
        dispatch_level = str(entry.get("dispatch_level", ""))
        receipt = receipt_by_role.get(role)
        if dispatch_level == "required":
            if receipt is None or str(receipt.get("status", "")).lower() != "completed":
                missing_required_receipts.append(role)
        elif dispatch_level == "preferred" and receipt is None:
            warnings.append(f"preferred agent missing receipt: {role}")

    return {
        "ok": not missing_required_receipts,
        "missing_required_receipts": missing_required_receipts,
        "warnings": warnings,
    }

#!/usr/bin/env python3
from __future__ import annotations

from dataclasses import dataclass
from pathlib import Path
from typing import Any, Iterable, Mapping

from _config import get_nested


@dataclass(frozen=True)
class DispatchRequirement:
    role: str
    dispatch_level: str
    reason: str
    policy_source: str
    matched_keywords: list[str]


def load_required_routes(config: Mapping[str, Any]) -> dict[str, dict[str, Any]]:
    routes = get_nested(config, "multi_agent", "dispatch_policy", "required_routes", default={})
    if not isinstance(routes, dict):
        return {}

    normalized: dict[str, dict[str, Any]] = {}
    for route_name, route_config in routes.items():
        if not isinstance(route_config, dict):
            continue
        agents = route_config.get("agents", [])
        keywords = route_config.get("keywords", [])
        if not isinstance(agents, list):
            continue
        normalized[str(route_name)] = {
            "agents": [str(agent) for agent in agents if str(agent).strip()],
            "keywords": [
                str(keyword).strip().lower()
                for keyword in keywords
                if str(keyword).strip()
            ]
            if isinstance(keywords, list)
            else [],
        }
    return normalized


def find_missing_required_route_agents(
    required_routes: Mapping[str, Mapping[str, Any]],
    available_roles: Iterable[str],
) -> list[str]:
    available = {str(role) for role in available_roles}
    missing: list[str] = []
    for route in required_routes.values():
        agents = route.get("agents", [])
        if not isinstance(agents, list):
            continue
        for role in agents:
            role_name = str(role)
            if role_name and role_name not in available:
                missing.append(role_name)
    return sorted(dict.fromkeys(missing))


def missing_required_agents(
    requirements: Iterable[DispatchRequirement],
    registry: Mapping[Any, Any] | Iterable[str],
) -> list[str]:
    registry_roles = _normalize_registry_roles(registry)
    missing = [
        requirement.role
        for requirement in requirements
        if requirement.role not in registry_roles
    ]
    return sorted(dict.fromkeys(missing))


def resolve_skill_path(skill_root: Path, agents_root: Path, role: str) -> str | None:
    skill_path = agents_root / role / "SKILL.md"
    if not skill_path.exists():
        return None
    try:
        return str(skill_path.relative_to(skill_root.parent))
    except ValueError:
        return str(skill_path)


def _normalize_registry_roles(registry: Mapping[Any, Any] | Iterable[str]) -> set[str]:
    if isinstance(registry, Mapping):
        values = registry.keys()
    else:
        values = registry

    roles: set[str] = set()
    for key in values:
        value = getattr(key, "value", None)
        roles.add(value if isinstance(value, str) else str(key))
    return roles

#!/usr/bin/env python3
"""
Awesome Code - TDD 测试运行器

功能：
- 自动发现并运行测试
- 生成覆盖率报告
- 支持监视模式（文件变更时自动运行）
- TDD 循环支持（Red-Green-Refactor）
"""

from __future__ import annotations

import argparse
import os
import subprocess
import sys
import time
from pathlib import Path


class TestRunner:
    """TDD 测试运行器"""

    def __init__(
        self,
        test_path: str = "tests",
        coverage: bool = False,
        watch: bool = False,
        fail_fast: bool = False,
        framework: str = "auto",
    ):
        self.test_path = Path(test_path)
        self.coverage = coverage
        self.watch = watch
        self.fail_fast = fail_fast
        self.framework = framework

    @staticmethod
    def _subprocess_env() -> dict[str, str]:
        """Route Python tool caches to the current project's Bensz workspace."""
        project_root = Path.cwd().resolve()
        artifact_root = project_root / ".bensz-api"
        env = os.environ.copy()
        env.setdefault("PYTHONPYCACHEPREFIX", str(artifact_root / "__pycache__"))
        env.setdefault("RUFF_CACHE_DIR", str(artifact_root / ".ruff_cache"))
        return env

    def detect_framework(self) -> str:
        """自动检测测试框架"""
        if self.framework != "auto":
            return self.framework

        # 只检查配置文件和测试文件，避免遍历所有文件导致内存问题

        # 检查 pytest 配置文件
        if Path("pytest.ini").exists() or Path("pyproject.toml").exists():
            return "pytest"

        # 检查 jest 配置文件
        if Path("jest.config.js").exists() or Path("jest.config.ts").exists():
            return "jest"

        # 检查 package.json 中是否包含 jest
        if Path("package.json").exists():
            try:
                import json
                with open("package.json", "r", encoding="utf-8") as f:
                    pkg = json.load(f)
                    if "jest" in pkg.get("devDependencies", {}) or "jest" in pkg.get("dependencies", {}):
                        return "jest"
            except Exception:
                pass

        # 检查是否存在 Python 测试文件
        py_test_files = list(Path(".").glob("**/test_*.py"))[:10] + list(Path(".").glob("**/*_test.py"))[:10]
        if py_test_files:
            # 只检查前几个文件，限制文件大小
            for f in py_test_files[:5]:
                try:
                    if f.stat().st_size < 100000:  # 小于 100KB
                        content = f.read_text(encoding="utf-8", errors="ignore")
                        if "unittest" in content:
                            return "unittest"
                except Exception:
                    pass
            return "pytest"

        # 检查是否存在 JavaScript 测试文件
        js_test_files = list(Path(".").glob("**/*.test.js"))[:5] + list(Path(".").glob("**/*.spec.js"))[:5]
        if js_test_files:
            return "jest"

        # 默认使用 pytest
        return "pytest"

    def run_pytest(self) -> int:
        """运行 pytest 测试"""
        cmd = [sys.executable, "-m", "pytest"]

        # 添加参数
        if self.fail_fast:
            cmd.append("-x")

        if self.coverage:
            cmd.extend(["--cov=.", "--cov-report=term-missing", "--cov-report=html"])

        cmd.append(str(self.test_path))

        print(f"🧪 运行测试: {' '.join(cmd)}")
        result = subprocess.run(cmd, capture_output=False, env=self._subprocess_env())
        return result.returncode

    def run_unittest(self) -> int:
        """运行 unittest 测试"""
        cmd = [sys.executable, "-m", "unittest", "discover", "-s", str(self.test_path)]
        print(f"🧪 运行测试: {' '.join(cmd)}")
        result = subprocess.run(cmd, capture_output=False, env=self._subprocess_env())
        return result.returncode

    def run_jest(self) -> int:
        """运行 Jest 测试"""
        cmd = ["npx", "jest"]

        if self.coverage:
            cmd.append("--coverage")

        if self.fail_fast:
            cmd.append("--bail")

        print(f"🧪 运行测试: {' '.join(cmd)}")
        result = subprocess.run(cmd, capture_output=False, env=self._subprocess_env())
        return result.returncode

    def run_tests(self) -> int:
        """运行测试"""
        framework = self.detect_framework()
        print(f"📦 使用测试框架: {framework}")

        if framework == "pytest":
            return self.run_pytest()
        elif framework == "unittest":
            return self.run_unittest()
        elif framework == "jest":
            return self.run_jest()
        else:
            print(f"❌ 不支持的测试框架: {framework}")
            return 1

    def watch_files(self) -> None:
        """监视文件变更并自动运行测试"""
        print(f"👀 监视模式启动（目录: {self.test_path}）")
        print("按 Ctrl+C 停止\n")

        file_times = {}
        ignore_dirs = {
            "__pycache__",
            ".git",
            ".venv",
            "venv",
            "node_modules",
            ".pytest_cache",
            ".ruff_cache",
            ".bensz-api",
            ".awesome-code",
            "dist",
            "build",
        }
        watch_suffixes = {".py", ".js"}

        try:
            while True:
                # 检查文件变更
                changed = False
                for file_path in Path(".").rglob("*"):
                    if file_path.suffix not in watch_suffixes:
                        continue
                    if any(part in ignore_dirs for part in file_path.parts):
                        continue
                    try:
                        mtime = os.path.getmtime(file_path)
                    except OSError:
                        # File may be deleted/locked between discovery and stat.
                        continue

                    if file_path not in file_times:
                        file_times[file_path] = mtime
                    elif mtime > file_times[file_path]:
                        print(f"\n📝 检测到文件变更: {file_path}")
                        file_times[file_path] = mtime
                        changed = True
                        break

                if changed:
                    print(f"\n{'='*60}")
                    result = self.run_tests()
                    print(f"{'='*60}\n")

                    if result == 0:
                        print("✅ 测试通过！继续 TDD 循环：")
                        print("   - Green 状态：考虑 Refactor")
                        print("   - 或开始下一个 Red 状态")
                    else:
                        print("❌ 测试失败（Red 状态）")
                        print("   - 编写最小实现使其通过（Green）")

                time.sleep(1)

        except KeyboardInterrupt:
            print("\n\n👋 监视模式已停止")

    def run(self) -> int:
        """主运行方法"""
        if not self.test_path.exists():
            print(f"❌ 测试目录不存在: {self.test_path}")
            return 1

        if self.watch:
            self.watch_files()
            return 0
        else:
            return self.run_tests()


def main():
    """主函数"""
    parser = argparse.ArgumentParser(
        description="Awesome Code - TDD 测试运行器",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
示例：
  # 运行所有测试
  %(prog)s

  # 运行测试并生成覆盖率报告
  %(prog)s --coverage

  # 监视模式（文件变更时自动运行）
  %(prog)s --watch

  # 快速失败（第一个测试失败即停止）
  %(prog)s --fail-fast

  # 指定测试目录
  %(prog)s --path tests/unit
        """,
    )

    parser.add_argument(
        "--path", "-p",
        default="tests",
        help="测试目录路径（默认: tests）",
    )

    parser.add_argument(
        "--coverage", "-c",
        action="store_true",
        help="生成覆盖率报告",
    )

    parser.add_argument(
        "--watch", "-w",
        action="store_true",
        help="监视模式（文件变更时自动运行）",
    )

    parser.add_argument(
        "--fail-fast", "-x",
        action="store_true",
        help="快速失败（第一个测试失败即停止）",
    )

    parser.add_argument(
        "--framework", "-f",
        choices=["auto", "pytest", "unittest", "jest"],
        default="auto",
        help="测试框架（默认: auto 自动检测）",
    )

    args = parser.parse_args()

    runner = TestRunner(
        test_path=args.path,
        coverage=args.coverage,
        watch=args.watch,
        fail_fast=args.fail_fast,
        framework=args.framework,
    )

    sys.exit(runner.run())


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
from __future__ import annotations

import sys
from pathlib import Path
from typing import Any, Dict


def load_skill_config(skill_root: Path) -> Dict[str, Any]:
    """
    Load `config.yaml` from a skill root.

    We keep this dependency lightweight:
    - If PyYAML isn't available, we return an empty config and let callers fall back to defaults.
    """
    config_path = skill_root / "config.yaml"
    if not config_path.exists():
        return {}

    try:
        import yaml  # type: ignore
    except Exception as exc:
        print(f"[awesome-code] warning: PyYAML unavailable; ignoring {config_path}: {exc}", file=sys.stderr)
        return {}

    try:
        data = yaml.safe_load(config_path.read_text(encoding="utf-8"))
    except Exception as exc:
        print(f"[awesome-code] warning: failed to parse {config_path}: {exc}", file=sys.stderr)
        return {}

    if isinstance(data, dict):
        return data
    return {}


def get_nested(config: Dict[str, Any], *keys: str, default: Any = None) -> Any:
    cur: Any = config
    for k in keys:
        if not isinstance(cur, dict) or k not in cur:
            return default
        cur = cur[k]
    return cur

# B 轮质量检查（{{TEST_ID}}）

**检查日期**: {{PLAN_DATE}}  
**检查ID**: {{TEST_ID}}  
**目标技能**: {{TARGET_SKILL_NAME}}  
**目标技能路径**: {{TARGET_SKILL_ROOT}}  
**关联A轮测试ID**: {{A_TEST_ID}}

---

## 检查维度（建议）

- 硬编码/AI 功能规划
- 冗余残留错误检查
- 安全性检查
- 过度设计检查
- 通用性检查
- 一致性检查
- 配置集中化检查
- SKILL.md 瘦身检查

---

## 问题与建议（P0-P2）

### P0
1) ...

### P1
1) ...

### P2
1) ...

---

## 修复与验证计划

- 修复清单：
- 验证方式：
- 证据产物：

# 优化计划（{{TEST_ID}}）

**计划日期**: {{PLAN_DATE}}  
**计划ID**: {{TEST_ID}}  
**目标技能**: {{TARGET_SKILL_NAME}}  
**目标技能路径**: {{TARGET_SKILL_ROOT}}

---

## 独立评估与审查范围（强制）

- [ ] 本轮基于目标 skill 的当前工作状态独立评估
- [ ] 未查看历史轮次的 `plans/` 与 `tests/`

必须审查：
- `SKILL.md`、`config.yaml`
- `scripts/`、`references/`、`templates/`、`assets/`

排除：
- `plans/`、`tests/`、`README.md`、`CHANGELOG.md`

---

## 问题清单（按优先级）

### P0
1) 标题：
- 位置：`path/to/file:line`
- 影响：
- 修复：
- 验证：

### P1
1) 标题：
- 位置：`path/to/file:line`
- 影响：
- 修复：
- 验证：

### P2
1) 标题：
- 位置：`path/to/file:line`
- 影响：
- 修复：
- 验证：

---

## 成功标准

- [ ] ...

## 最小变更范围

**允许修改**：
- `...`

**避免**：
- 无关格式化
- 顺手重构
- 未经验证的新抽象

**范围理由**：
- ...

## 验证计划

- [ ] ...

---

## 执行步骤

1) ...
2) ...

# 轻量测试计划（{{TEST_ID}}）

**测试ID**: {{TEST_ID}}  
**目标技能**: {{TARGET_SKILL_NAME}}  
**目标技能路径**: {{TARGET_SKILL_ROOT}}  
**轮次类型**: {{ROUND_KIND}}  
**关联规划文档**: {{PLAN_DOC_PATH}}  
**计划时间**: {{PLAN_TIME}}

---

## 目标

- 本轮要验证的核心行为：
- 本轮要解决/验证的问题（对应计划文档）：
- 通过标准：

## 最小变更范围

- 允许修改：
- 明确避免：
- 扩大范围的触发条件：

## 成功标准

- [ ] ...

---

## 验证点（轻量测试）

### P0（必须通过）
- [ ] ...

### P1（强烈建议通过）
- [ ] ...

### P2（可选）
- [ ] ...

---

## 执行步骤

1. 准备：确认版本、目录结构、依赖
2. 执行验证点并记录证据
3. 产物与日志放入 `_artifacts/`

# 测试报告（{{TEST_ID}}）

**测试ID**: {{TEST_ID}}  
**目标技能**: {{TARGET_SKILL_NAME}}  
**目标技能路径**: {{TARGET_SKILL_ROOT}}  
**轮次类型**: {{ROUND_KIND}}  
**关联规划文档**: {{PLAN_DOC_PATH}}  
**测试时间**: {{CHECK_TIME}}  

---

## 结论

- 状态：✅ 通过 / ❌ 失败 / ⚠️ 部分通过
- 一句话结论：

---

## 覆盖的变更（本轮）

- 修改文件：
  - ...

---

## 执行命令与证据

1) 命令：`...`
   - 期望：
   - 实际：
   - 证据：`_artifacts/...`

---

## 验证点打勾清单

### P0（必须通过）
- [ ] ...

### P1（强烈建议）
- [ ] ...

### P2（可选）
- [ ] ...

---

## 遗留问题（如有）

- P0/P1/P2：问题描述 + 原因 + 后续建议