name: wiring description: 布线验证 user-invocable: false

布线验证

在构建基础设施组件时，确保它们在实际执行路径中被正确调用。

模式

每个模块都需要一个清晰的入口点。死代码比没有代码更糟糕——它增加了维护负担并产生虚假的自信。

四步布线检查

在标记基础设施“完成”之前，验证：

存在入口点：用户操作如何触发此代码？
追踪调用图：能否从入口点到执行路径跟踪？
集成测试：端到端测试是否执行此路径？
无死代码：每个构建的组件是否实际可达？

需做事项

验证入口点

# 钩子已注册？
grep -r "orchestration" .claude/settings.json

# 技能已激活？
grep -r "skill-name" .claude/skill-rules.json

# 脚本可执行？
ls -la scripts/orchestrate.py

# 模块已导入？
grep -r "from orchestration_layer import" .

追踪调用图

# 入口点（钩子）
.claude/hooks/pre-tool-use.sh
  ↓
# Shell包装器调用TypeScript
npx tsx pre-tool-use.ts
  ↓
# TypeScript调用Python脚本
spawn('scripts/orchestrate.py')
  ↓
# 脚本导入模块
from orchestration_layer import dispatch
  ↓
# 模块执行
dispatch(agent_type, task)

端到端测试

# 不仅仅单元测试模块
pytest tests/unit/orchestration_layer_test.py  # 不够

# 测试完整调用路径
echo '{"tool": "Task"}' | .claude/hooks/pre-tool-use.sh  # 验证此操作有效

记录布线

## 布线

- **入口点**：Task工具上的PreToolUse钩子
- **注册**：`.claude/settings.json`第45行
- **调用路径**：钩子 → pre-tool-use.ts → scripts/orchestrate.py → orchestration_layer.py
- **测试**：`tests/integration/task_orchestration_test.py`

禁止事项

未布线就构建

# 坏：创建了500行的orchestration_layer.py
# 但没有任何导入或调用它
# 结果：死代码，浪费精力

# 好：从最小布线开始，再扩展
# 1. 创建钩子（10行）
# 2. 测试钩子触发
# 3. 添加脚本（20行）
# 4. 测试脚本执行
# 5. 添加模块逻辑（迭代）

创建并行路由

# 坏：代理路由器有分发逻辑
# AND skill-rules.json有代理选择逻辑
# AND钩子有代理过滤逻辑
# 结果：三个地方需要更新，路由冲突

# 好：路由的单源真相
# skill-rules.json激活技能 → 技能调用路由器 → 路由器分发

假设导入有效

# 坏：假设因为你写了代码，它就被导入了
from orchestration_layer import dispatch  # 此路径存在吗？

# 好：在集成测试时验证导入
uv run python -c "from orchestration_layer import dispatch; print('OK')"

跳过集成测试

# 坏：只做单元测试
pytest tests/unit/  # 全部通过，但端到端不工作

# 好：集成测试布线
pytest tests/integration/  # 验证完整调用路径

常见布线漏洞

钩子未注册

// .claude/settings.json - 钩子定义存在但不在钩子部分
{
  "hooks": {
    "PreToolUse": []  // 空！你的钩子从未触发
  }
}

修复：添加钩子注册：

{
  "hooks": {
    "PreToolUse": [{
      "matcher": ["Task"],
      "hooks": [{
        "type": "command",
        "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/orchestration.sh"
      }]
    }]
  }
}

脚本不可执行

# 脚本存在但无法执行
-rw-r--r-- scripts/orchestrate.py

# 修复：设为可执行
chmod +x scripts/orchestrate.py

模块不可导入

# 脚本尝试导入但路径错误
from orchestration_layer import dispatch
# ModuleNotFoundError

# 修复：添加到Python路径或使用正确的包结构
sys.path.insert(0, str(Path(__file__).parent.parent))

路由器无分发路径

# 坏：路由器有精美的映射
AGENT_MAP = {
    "implement": ImplementAgent,
    "research": ResearchAgent,
    # ... 18个代理类型
}

# 但没有任何分发函数使用映射
def route(task):
    return "general-purpose"  # 硬编码！映射是死代码

# 好：分发实际使用映射
def route(task):
    agent_type = classify(task)
    return AGENT_MAP[agent_type]

布线检查清单

在标记基础设施“完成”之前：

[ ] 入口点已识别并测试（钩子/技能/CLI）
[ ] 调用图已记录（入口 → 模块执行）
[ ] 集成测试执行完整路径
[ ] 无孤立模块（所有都导入/调用）
[ ] 注册完成（settings.json/skill-rules.json）
[ ] 权限正确（脚本可执行）
[ ] 导入路径已验证（手动导入测试通过）

真实世界示例

示例1：DAG编排（本次会话）

构建内容：

opc/orchestration/orchestration_layer.py（500+行）
opc/orchestration/dag/（DAG构建器、验证器、执行器）
18个代理类型定义
复杂路由逻辑

布线漏洞：

无钩子调用orchestration_layer.py
无脚本导入DAG模块
代理路由返回硬编码“general-purpose”
结果：100%死代码

修复：

为Task工具创建PreToolUse钩子
钩子调用scripts/orchestrate.py
脚本导入并调用orchestration_layer.dispatch()
分发使用AGENT_MAP路由到实际代理
集成测试：提交Task → 验证正确代理类型使用

示例2：工件索引（前一会话）

构建内容：

SQLite数据库模式
索引逻辑
查询函数

布线漏洞：

无钩子触发索引
文件创建但从未索引

修复：

Write工具上的PostToolUse钩子
钩子立即调用索引脚本
集成测试：写入文件 → 验证已索引

检测策略

Grep查找孤立模块

# 查找Python模块
find . -name "*.py" -type f

# 检查每个是否被导入
for file in $(find . -name "*.py"); do
  module=$(basename $file .py)
  grep -r "from.*$module import\|import.*$module" . || echo "孤立模块: $file"
done

检查钩子注册

# 列出.claude/hooks/中的所有钩子
ls .claude/hooks/*.sh

# 检查每个是否已注册
for hook in $(ls .claude/hooks/*.sh); do
  basename_hook=$(basename $hook)
  grep -q "$basename_hook" .claude/settings.json || echo "未注册钩子: $hook"
done

验证脚本执行

# 查找所有Python脚本
find scripts/ -name "*.py"

# 测试每个可导入
for script in $(find scripts/ -name "*.py"); do
  uv run python -c "import sys; sys.path.insert(0, 'scripts'); import $(basename $script .py)" 2>/dev/null || echo "导入失败: $script"
done

来源

本次会话：DAG编排布线漏洞 - 发现500+行死代码
前一会话：工件索引、LMStudio集成 - 初始构建后添加布线