wiring

接线验证

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

模式

每个模块都需要明确的入口点。死代码比没有代码更糟——它会增加维护负担，并造成虚假的信心。

四步接线检查

在将基础设施标记为“完成”之前，请确认：

1. 入口点存在：用户操作如何触发这段代码？
2. 追踪调用图：能否从入口一路追踪到执行？
3. 已进行集成测试：端到端测试是否覆盖了此路径？
4. 没有死代码：每个已构建的组件是否都可触达？

应该做

验证入口点

# Hook registered?
grep -r "orchestration" .claude/settings.json

# Skill activated?
grep -r "skill-name" .claude/skill-rules.json

# Script executable?
ls -la scripts/orchestrate.py

# Module imported?
grep -r "from orchestration_layer import" .

追踪调用图

# Entry point (hook)
.claude/hooks/pre-tool-use.sh
  ↓
# Shell wrapper calls TypeScript
npx tsx pre-tool-use.ts
  ↓
# TypeScript calls Python script
spawn('scripts/orchestrate.py')
  ↓
# Script imports module
from orchestration_layer import dispatch
  ↓
# Module executes
dispatch(agent_type, task)

进行端到端测试

# Don't just unit test the module
pytest tests/unit/orchestration_layer_test.py  # NOT ENOUGH

# Test the full invocation path
echo '{"tool": "Task"}' | .claude/hooks/pre-tool-use.sh  # VERIFY THIS WORKS

记录接线方式

## Wiring

- **Entry Point**: PreToolUse hook on Task tool
- **Registration**: `.claude/settings.json` line 45
- **Call Path**: hook → pre-tool-use.ts → scripts/orchestrate.py → orchestration_layer.py
- **Test**: `tests/integration/task_orchestration_test.py`

不应该做

构建后不接线

# BAD: Created orchestration_layer.py with 500 lines
# But nothing imports it or calls it
# Result: Dead code, wasted effort

# GOOD: Start with minimal wiring, then expand
# 1. Create hook (10 lines)
# 2. Test hook fires
# 3. Add script (20 lines)
# 4. Test script executes
# 5. Add module logic (iterate)

创建并行路由

# BAD: Agent router has dispatch logic
# AND skill-rules.json has agent selection logic
# AND hooks have agent filtering logic
# Result: Three places to update, routing conflicts

# GOOD: Single source of truth for routing
# skill-rules.json activates skill → skill calls router → router dispatches

假设导入有效

# BAD: Assume because you wrote the code, it's imported
from orchestration_layer import dispatch  # Does this path exist?

# GOOD: Verify imports at integration test time
uv run python -c "from orchestration_layer import dispatch; print('OK')"

跳过集成测试

# BAD: Only unit test
pytest tests/unit/  # All pass, but nothing works end-to-end

# GOOD: Integration test the wiring
pytest tests/integration/  # Verify full call path

常见接线缺口

钩子未注册

// .claude/settings.json - hook definition exists but not in hooks section
{
  "hooks": {
    "PreToolUse": []  // Empty! Your hook never fires
  }
}

修复：添加钩子注册：

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

脚本不可执行

# Script exists but can't execute
-rw-r--r-- scripts/orchestrate.py

# Fix: Make executable
chmod +x scripts/orchestrate.py

模块无法导入

# Script tries to import but path is wrong
from orchestration_layer import dispatch
# ModuleNotFoundError

# Fix: Add to Python path or use proper package structure
sys.path.insert(0, str(Path(__file__).parent.parent))

路由器没有分发路径

# BAD: Router has beautiful mapping
AGENT_MAP = {
    "implement": ImplementAgent,
    "research": ResearchAgent,
    # ... 18 agent types
}

# But no dispatch function uses the map
def route(task):
    return "general-purpose"  # Hardcoded! Map is dead code

# GOOD: Dispatch actually uses the map
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 种 Agent 类型定义
• 复杂的路由逻辑

接线缺口：

• 没有钩子调用 orchestration_layer.py
• 没有脚本导入 DAG 模块
• Agent 路由返回硬编码的 "general-purpose"
• 结果：100% 的代码都是死代码

修复：

1. 为 Task 工具创建 PreToolUse 钩子
2. 钩子调用 scripts/orchestrate.py
3. 脚本导入并调用 orchestration_layer.dispatch()
4. 分发器使用 AGENT_MAP 将请求路由到实际的 Agent
5. 集成测试：提交 Task → 验证使用了正确的 Agent 类型

示例 2：工件索引（上次会话）

构建内容：

• SQLite 数据库架构
• 索引逻辑
• 查询函数

接线缺口：

• 没有钩子触发索引
• 文件已创建，但从未编入索引

修复：

1. 在 Write 工具上添加 PostToolUse 钩子
2. 钩子立即调用索引脚本
3. 集成测试：写入文件 → 验证已编入索引

检测策略

使用 grep 查找孤立项

# Find Python modules
find . -name "*.py" -type f

# Check if each is imported
for file in $(find . -name "*.py"); do
  module=$(basename $file .py)
  grep -r "from.*$module import\|import.*$module" . || echo "ORPHAN: $file"
done

检查钩子注册情况

# List all hooks in .claude/hooks/
ls .claude/hooks/*.sh

# Check each is registered
for hook in $(ls .claude/hooks/*.sh); do
  basename_hook=$(basename $hook)
  grep -q "$basename_hook" .claude/settings.json || echo "UNREGISTERED: $hook"
done

验证脚本执行

# Find all Python scripts
find scripts/ -name "*.py"

# Test each can be imported
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 "IMPORT FAIL: $script"
done

来源

• 本次会话：DAG 编排接线缺口——发现 500+ 行死代码
• 之前的会话：Artifact Index、LMStudio 集成——在初始构建后补充了接线