dev-playbooks-cn 1.0.0

package/skills/devbooks-test-owner/references//350/247/243/344/276/235/350/265/226/346/212/200/346/234/257/351/200/237/346/237/245/350/241/250.md

@@ -0,0 +1,432 @@
+# 解依赖技术速查表（8 种高频技术）
+
+> 来源：《修改代码的艺术》第 25 章（从 24 种精选）
+> 适用角色：Test Owner / Coder
+
+---
+
+## 速查索引
+
+| # | 技术 | 一句话描述 | 频率 | 适用场景 |
+|---|------|----------|------|---------|
+| 1 | Extract Interface | 提取接口隔离外部依赖 | ⭐⭐⭐ | 外部服务/数据库/第三方 API |
+| 2 | Parameterize Constructor | 通过构造器注入依赖 | ⭐⭐⭐ | 硬编码依赖、new 操作在构造器 |
+| 3 | Subclass and Override | 子类化并覆写方法 | ⭐⭐⭐ | 需要替换部分行为、无法修改原类 |
+| 4 | Introduce Static Setter | 为静态依赖提供 setter | ⭐⭐ | 单例、全局对象、静态工厂 |
+| 5 | Extract and Override Getter | 提取 getter 并覆写 | ⭐⭐ | 字段依赖、延迟初始化 |
+| 6 | Break Out Method Object | 将方法提取为对象 | ⭐⭐ | 过长方法、复杂算法 |
+| 7 | Adapt Parameter | 为参数创建适配器 | ⭐ | 难以 mock 的参数类型 |
+| 8 | Encapsulate Global References | 封装全局变量 | ⭐ | 全局状态、环境变量 |
+
+---
+
+## 1. Extract Interface（提取接口）
+
+### 问题场景
+```python
+class OrderService:
+    def __init__(self):
+        self._payment = PaymentGateway()  # 硬编码依赖真实支付网关
+        self._inventory = InventoryDB()    # 硬编码依赖真实数据库
+
+    def process(self, order):
+        self._payment.charge(order.total)  # 无法测试：会真实扣款
+        self._inventory.deduct(order.items)
+```
+
+### 解决方案
+```python
+# 1. 提取接口
+class PaymentGatewayInterface(Protocol):
+    def charge(self, amount: Decimal) -> bool: ...
+
+class InventoryInterface(Protocol):
+    def deduct(self, items: list[Item]) -> None: ...
+
+# 2. 原类实现接口（可选）
+class PaymentGateway(PaymentGatewayInterface):
+    def charge(self, amount): ...
+
+# 3. 通过构造器注入
+class OrderService:
+    def __init__(self, payment: PaymentGatewayInterface, inventory: InventoryInterface):
+        self._payment = payment
+        self._inventory = inventory
+
+# 4. 测试时注入 Mock
+def test_order_service():
+    mock_payment = Mock(spec=PaymentGatewayInterface)
+    mock_inventory = Mock(spec=InventoryInterface)
+    service = OrderService(mock_payment, mock_inventory)
+    service.process(order)
+    mock_payment.charge.assert_called_once_with(order.total)
+```
+
+### 要点
+- 接口定义"契约"，实现可替换
+- 测试时用 Mock 实现接口
+- 生产时用真实实现
+
+---
+
+## 2. Parameterize Constructor（参数化构造器）
+
+### 问题场景
+```python
+class ReportGenerator:
+    def __init__(self):
+        self._db = DatabaseConnection()  # 构造器中 new 依赖
+        self._logger = FileLogger("/var/log/app.log")
+```
+
+### 解决方案
+```python
+class ReportGenerator:
+    def __init__(self, db=None, logger=None):
+        self._db = db or DatabaseConnection()  # 默认值保持向后兼容
+        self._logger = logger or FileLogger("/var/log/app.log")
+
+# 测试时
+def test_report_generator():
+    mock_db = Mock()
+    mock_logger = Mock()
+    generator = ReportGenerator(db=mock_db, logger=mock_logger)
+```
+
+### 要点
+- 保留默认值，不破坏现有调用方
+- 生产代码无需修改
+- 测试代码可注入 Mock
+
+---
+
+## 3. Subclass and Override（子类化并覆写）
+
+### 问题场景
+```python
+class PaymentProcessor:
+    def process(self, payment):
+        gateway = self._get_gateway()  # 受保护方法获取真实网关
+        return gateway.charge(payment)
+
+    def _get_gateway(self):
+        return RealPaymentGateway()  # 无法在测试中替换
+```
+
+### 解决方案
+```python
+# 测试时创建子类
+class TestablePaymentProcessor(PaymentProcessor):
+    def __init__(self, mock_gateway):
+        self._mock_gateway = mock_gateway
+
+    def _get_gateway(self):  # 覆写受保护方法
+        return self._mock_gateway
+
+# 测试
+def test_payment_processor():
+    mock_gateway = Mock()
+    processor = TestablePaymentProcessor(mock_gateway)
+    processor.process(payment)
+    mock_gateway.charge.assert_called_once()
+```
+
+### 要点
+- 不修改原类，只在测试中扩展
+- 适用于无法修改源码的情况
+- 覆写的方法应尽量小
+
+---
+
+## 4. Introduce Static Setter（引入静态 Setter）
+
+### 问题场景
+```python
+class ConfigManager:
+    _instance = None
+
+    @classmethod
+    def get_instance(cls):
+        if cls._instance is None:
+            cls._instance = cls._create_real_config()  # 单例，无法替换
+        return cls._instance
+
+class MyService:
+    def do_work(self):
+        config = ConfigManager.get_instance()  # 依赖单例
+        return config.get("api_key")
+```
+
+### 解决方案
+```python
+class ConfigManager:
+    _instance = None
+
+    @classmethod
+    def get_instance(cls):
+        if cls._instance is None:
+            cls._instance = cls._create_real_config()
+        return cls._instance
+
+    @classmethod
+    def set_instance_for_testing(cls, instance):  # 新增测试用 setter
+        cls._instance = instance
+
+    @classmethod
+    def reset_instance(cls):  # 测试清理
+        cls._instance = None
+
+# 测试
+def test_my_service():
+    mock_config = Mock()
+    mock_config.get.return_value = "test_api_key"
+    ConfigManager.set_instance_for_testing(mock_config)
+    try:
+        service = MyService()
+        result = service.do_work()
+        assert result == "test_api_key"
+    finally:
+        ConfigManager.reset_instance()  # 清理
+```
+
+### 要点
+- 仅用于测试，生产代码不应调用 setter
+- 必须在 teardown 中重置
+- 考虑使用 pytest fixture 自动清理
+
+---
+
+## 5. Extract and Override Getter（提取并覆写 Getter）
+
+### 问题场景
+```python
+class OrderValidator:
+    def validate(self, order):
+        current_time = datetime.now()  # 直接调用，无法控制时间
+        if order.expires_at < current_time:
+            raise OrderExpiredError()
+```
+
+### 解决方案
+```python
+class OrderValidator:
+    def validate(self, order):
+        current_time = self._get_current_time()  # 提取为方法
+        if order.expires_at < current_time:
+            raise OrderExpiredError()
+
+    def _get_current_time(self):  # 可被覆写
+        return datetime.now()
+
+# 测试
+class TestableOrderValidator(OrderValidator):
+    def __init__(self, fixed_time):
+        self._fixed_time = fixed_time
+
+    def _get_current_time(self):
+        return self._fixed_time
+
+def test_order_expired():
+    validator = TestableOrderValidator(datetime(2024, 1, 15))
+    expired_order = Order(expires_at=datetime(2024, 1, 10))
+    with pytest.raises(OrderExpiredError):
+        validator.validate(expired_order)
+```
+
+### 要点
+- 将不可控的依赖（时间、随机数、环境）提取为方法
+- 测试时通过子类覆写控制返回值
+- 保持原有行为不变
+
+---
+
+## 6. Break Out Method Object（方法对象化）
+
+### 问题场景
+```python
+class ReportEngine:
+    def generate_complex_report(self, data, config, filters, formatters):
+        # 200 行复杂逻辑，使用大量局部变量
+        temp1 = ...
+        temp2 = ...
+        # 难以测试：方法太长，依赖太多
+```
+
+### 解决方案
+```python
+# 将方法提取为独立类
+class ComplexReportGenerator:
+    def __init__(self, data, config, filters, formatters):
+        self._data = data
+        self._config = config
+        self._filters = filters
+        self._formatters = formatters
+        # 原来的局部变量变成实例变量
+        self._temp1 = None
+        self._temp2 = None
+
+    def generate(self):
+        self._step1()
+        self._step2()
+        return self._finalize()
+
+    def _step1(self):  # 可单独测试
+        self._temp1 = ...
+
+    def _step2(self):  # 可单独测试
+        self._temp2 = ...
+
+# 原类委托给新类
+class ReportEngine:
+    def generate_complex_report(self, data, config, filters, formatters):
+        generator = ComplexReportGenerator(data, config, filters, formatters)
+        return generator.generate()
+```
+
+### 要点
+- 长方法拆分为多个可测试的小方法
+- 局部变量变为实例变量，可在测试中检查中间状态
+- 原类保持接口不变
+
+---
+
+## 7. Adapt Parameter（参数适配器）
+
+### 问题场景
+```python
+class DataProcessor:
+    def process(self, http_request: HttpRequest):  # HttpRequest 难以 mock
+        data = http_request.get_json()
+        headers = http_request.headers
+        # ...
+```
+
+### 解决方案
+```python
+# 创建适配器接口
+class RequestData(Protocol):
+    def get_json(self) -> dict: ...
+    def get_headers(self) -> dict: ...
+
+# 适配器包装真实对象
+class HttpRequestAdapter:
+    def __init__(self, request: HttpRequest):
+        self._request = request
+
+    def get_json(self):
+        return self._request.get_json()
+
+    def get_headers(self):
+        return dict(self._request.headers)
+
+# 修改方法签名
+class DataProcessor:
+    def process(self, request: RequestData):  # 依赖接口而非具体类
+        data = request.get_json()
+        headers = request.get_headers()
+
+# 测试时
+def test_data_processor():
+    mock_request = Mock(spec=RequestData)
+    mock_request.get_json.return_value = {"key": "value"}
+    mock_request.get_headers.return_value = {"Content-Type": "application/json"}
+    processor = DataProcessor()
+    processor.process(mock_request)
+```
+
+### 要点
+- 为难以 mock 的参数创建简化接口
+- 生产代码使用适配器包装真实对象
+- 测试代码直接 mock 接口
+
+---
+
+## 8. Encapsulate Global References（封装全局引用）
+
+### 问题场景
+```python
+# 全局变量
+DATABASE_URL = os.environ.get("DATABASE_URL")
+API_KEY = os.environ.get("API_KEY")
+
+class MyService:
+    def connect(self):
+        return Database(DATABASE_URL)  # 依赖全局变量
+```
+
+### 解决方案
+```python
+# 封装为配置类
+class AppConfig:
+    def __init__(self):
+        self._db_url = os.environ.get("DATABASE_URL")
+        self._api_key = os.environ.get("API_KEY")
+
+    @property
+    def database_url(self):
+        return self._db_url
+
+    @property
+    def api_key(self):
+        return self._api_key
+
+# 注入配置
+class MyService:
+    def __init__(self, config: AppConfig):
+        self._config = config
+
+    def connect(self):
+        return Database(self._config.database_url)
+
+# 测试
+def test_my_service():
+    mock_config = Mock(spec=AppConfig)
+    mock_config.database_url = "sqlite:///:memory:"
+    service = MyService(mock_config)
+```
+
+### 要点
+- 全局变量封装为可注入的配置对象
+- 测试时可控制配置值
+- 消除对环境的隐式依赖
+
+---
+
+## 决策流程图
+
+```
+代码无法测试？
+      │
+      ▼
+┌─────────────────────────────┐
+│ 依赖是什么类型？              │
+└──────────┬──────────────────┘
+     ┌─────┼─────┬─────┬──────┐
+     ▼     ▼     ▼     ▼      ▼
+  外部    构造器   单例   字段   全局
+  服务    中new   静态   依赖   变量
+     │     │     │     │      │
+     ▼     ▼     ▼     ▼      ▼
+ Extract  Para-  Static Extract Encap-
+ Inter-   meter- Setter Override sulate
+ face     ize            Getter Global
+          Constr-
+          uctor
+```
+
+---
+
+## 与其他文档的关系
+
+| 场景 | 参考文档 |
+|------|---------|
+| 需要在遗留代码中安全添加功能 | `低风险改动技术.md` |
+| 需要找到最优测试点 | `测试驱动.md` § 7.2 Pinch Point |
+| 需要评估改动影响 | `6 影响分析提示词.md` |
+
+---
+
+## 参考资料
+
+- 《修改代码的艺术》第 25 章 - 解依赖技术
+- dev-playbooks `devbooks-test-owner/SKILL.md`

package/skills/devbooks-test-reviewer/SKILL.md

@@ -0,0 +1,189 @@
+# DevBooks：测试评审（Test Reviewer）
+
+## 前置：配置发现（协议无关）
+
+执行前**必须**按以下顺序查找配置（找到后停止）：
+1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
+2. `dev-playbooks/project.md`（如存在）→ DevBooks 2.0 协议，使用默认映射
+4. `project.md`（如存在）→ template 协议，使用默认映射
+5. 若仍无法确定 → **停止并询问用户**
+
+---
+
+## 角色定义
+
+**test-reviewer** 是 DevBooks Apply 阶段的专门测试评审角色，与 reviewer（代码评审）互补。
+
+### 职责范围
+
+| 维度 | test-reviewer | reviewer |
+|------|:-------------:|:--------:|
+| 评审对象 | `tests/`（测试代码） | `src/`（实现代码） |
+| 覆盖率评估 | ✅ | ❌ |
+| 边界条件检查 | ✅ | ❌ |
+| 测试可读性 | ✅ | ❌ |
+| 测试可维护性 | ✅ | ❌ |
+| 规格一致性 | ✅（与 verification.md 对比） | ❌ |
+| 逻辑/风格/依赖 | ❌ | ✅ |
+| 修改代码权限 | ❌ | ❌ |
+
+---
+
+## 关键约束
+
+### CON-ROLE-001：只评审 tests/ 目录
+- **禁止**读取或评审 `src/` 目录下的实现代码
+- 只关注测试文件：`tests/**`, `__tests__/**`, `*.test.*`, `*.spec.*`
+
+### CON-ROLE-002：不修改任何代码
+- 只输出评审意见，**禁止**直接修改文件
+- 如需修改，只能提出建议由 Test Owner 执行
+
+### CON-ROLE-003：检查测试与规格的一致性
+- 必须对照 `verification.md` 检查测试是否覆盖所有 AC
+- 如发现测试缺失，明确指出缺失的 AC-ID
+
+---
+
+## 评审维度
+
+### 1. 覆盖率评估
+- [ ] 所有 AC（验收准则）是否有对应测试
+- [ ] 关键路径是否有端到端测试
+- [ ] 边界条件是否覆盖（空值、极值、错误输入）
+- [ ] 错误处理路径是否覆盖
+
+### 2. 测试质量
+- [ ] 测试是否独立（不依赖执行顺序）
+- [ ] 测试是否可重复（无随机性或时间依赖）
+- [ ] 断言是否明确（每个测试只验证一件事）
+- [ ] 测试数据是否合理（避免魔法数字）
+
+### 3. 可读性与可维护性
+- [ ] 测试命名是否清晰（describe/it 描述业务意图）
+- [ ] 测试结构是否一致（Given-When-Then 或 Arrange-Act-Assert）
+- [ ] 是否有适当的测试工具函数（避免重复代码）
+- [ ] 是否有必要的注释（复杂测试场景）
+
+### 4. 规格一致性
+- [ ] 测试是否与 `verification.md` 的 VT-ID 对应
+- [ ] 测试场景是否与 AC 场景一致
+- [ ] 是否有额外测试（未在规格中的行为）
+
+---
+
+## 执行流程
+
+1. **读取规格**：打开 `<change-root>/<change-id>/verification.md`，了解测试计划
+2. **定位测试文件**：根据 verification.md 中的追溯矩阵定位对应测试
+3. **逐项评审**：按评审维度检查每个测试文件
+4. **输出报告**：生成评审报告，包含问题列表和建议
+
+---
+
+## 输出格式
+
+```markdown
+# Test Review Report: <change-id>
+
+## 概览
+- 评审日期：YYYY-MM-DD
+- 评审范围：`tests/feature-x/`
+- 测试文件数：N
+- 问题总数：N（Critical: N, Major: N, Minor: N）
+
+## 覆盖率分析
+
+| AC-ID | 测试文件 | 覆盖状态 | 备注 |
+|-------|----------|----------|------|
+| AC-001 | test-a.ts | ✅ 已覆盖 | - |
+| AC-002 | - | ❌ 缺失 | 需要添加 |
+| AC-003 | test-b.ts | ⚠️ 部分覆盖 | 缺少边界条件 |
+
+## 问题清单
+
+### Critical (必须修复)
+1. **[C-001]** `test-a.ts:42` - 测试依赖外部服务，无 mock
+   - 建议：添加 mock，确保测试独立
+
+### Major (建议修复)
+1. **[M-001]** `test-b.ts` - 缺少错误路径测试
+   - 建议：添加 `expect(...).toThrow()` 测试
+
+### Minor (可选修复)
+1. **[m-001]** `test-c.ts:15` - 测试命名不清晰
+   - 建议：`it('should do X')` 改为 `it('should return Y when given X')`
+
+## 建议
+
+1. [建议1]
+2. [建议2]
+
+---
+*此报告由 devbooks-test-reviewer 生成*
+```
+
+---
+
+## 与其他角色的交互
+
+| 场景 | 交互方 | 动作 |
+|------|--------|------|
+| 发现测试缺失 | Test Owner | 提出建议，由 Test Owner 补充测试 |
+| 发现测试与规格不一致 | Test Owner | 提出问题，确认是规格问题还是测试问题 |
+| 发现实现问题（通过测试） | Reviewer | 通知 Reviewer 关注，不直接评审实现 |
+
+---
+
+## 元数据
+
+| 字段 | 值 |
+|------|-----|
+| Skill 名称 | devbooks-test-reviewer |
+| 阶段 | Apply |
+| 产物 | 评审报告（不写入变更包） |
+| 约束 | CON-ROLE-001~003 |
+
+---
+
+## 上下文感知
+
+本 Skill 在执行前自动检测上下文，选择合适的评审范围。
+
+检测规则参考：`skills/_shared/context-detection-template.md`
+
+### 检测流程
+
+1. 检测 `verification.md` 是否存在
+2. 检测测试文件变更范围
+3. 检测 AC 覆盖状态
+
+### 本 Skill 支持的模式
+
+| 模式 | 触发条件 | 行为 |
+|------|----------|------|
+| **完整评审** | 新变更包首次评审 | 评审所有测试文件 |
+| **增量评审** | 已有评审报告 | 只评审新增/修改的测试 |
+| **覆盖率检查** | 带 --coverage 参数 | 只检查 AC 覆盖情况 |
+
+### 检测输出示例
+
+```
+检测结果：
+- verification.md：存在
+- 测试文件变更：5 个
+- AC 覆盖状态：8/10
+- 运行模式：增量评审
+```
+
+---
+
+## MCP 增强
+
+本 Skill 不依赖 MCP 服务，无需运行时检测。
+
+MCP 增强规则参考：`skills/_shared/mcp-enhancement-template.md`
+
+---
+
+*此 Skill 文档遵循 devbooks-* 规范。*

package/templates/.devbooks/config.yaml

@@ -0,0 +1,88 @@
+# .devbooks/config.yaml
+# DevBooks Protocol Discovery Configuration
+#
+# 此文件由 DevBooks 自动生成，用于让 AI 自动发现项目配置。
+# 请勿随意删除或修改，除非你清楚每个字段的含义。
+
+# ==================== DevBooks 配置 ====================
+
+# 根目录
+root: dev-playbooks/
+
+# 宪法文件（强制加载）
+constitution: constitution.md
+
+# 项目上下文
+project: project.md
+
+# 路径配置
+paths:
+  specs: specs/
+  changes: changes/
+  scripts: scripts/
+  staged: specs/_staged/
+  anti_patterns: specs/_meta/anti-patterns/
+
+# ==================== 向后兼容配置 ====================
+
+# 目录根映射（向后兼容）
+truth_root: dev-playbooks/specs/
+change_root: dev-playbooks/changes/
+
+# 规则文档位置
+agents_doc: dev-playbooks/project.md
+
+# 项目画像（可选）
+project_profile: dev-playbooks/specs/_meta/project-profile.md
+
+# ==================== 协议约束 ====================
+
+constraints:
+  # apply 阶段是否必须指定角色
+  apply_requires_role: true
+
+  # apply 阶段可用角色
+  apply_roles:
+    - test-owner
+    - coder
+    - reviewer
+    - test-reviewer
+
+  # Test Owner 与 Coder 是否必须独立对话
+  role_isolation: true
+
+  # Coder 是否禁止修改 tests/
+  coder_no_tests: true
+
+  # 是否启用结构质量守门
+  structural_guardrails: true
+
+  # 是否强制加载宪法
+  require_constitution: true
+
+# ==================== 适应度函数配置 ====================
+
+fitness:
+  # 适应度检查模式：error（阻断）| warn（警告）| off（关闭）
+  mode: warn
+
+  # 规则文件路径
+  rules_file: specs/architecture/fitness-rules.md
+
+# ==================== AC 追溯配置 ====================
+
+tracing:
+  # AC 覆盖率阈值
+  coverage_threshold: 80
+
+  # 输出格式：text | json
+  output_format: text
+
+# ==================== 提案阶段配置 ====================
+
+proposal:
+  # 是否启用三角对辩（Author/Challenger/Judge）
+  enable_debate: true
+
+  # 是否需要 Impact Analysis（跨模块变更）
+  require_impact_analysis: true