wiring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Wiring Verification

代码链路验证

When building infrastructure components, ensure they're actually invoked in the execution path.

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

Pattern

模式

Every module needs a clear entry point. Dead code is worse than no code - it creates maintenance burden and false confidence.

每个模块都需要清晰的入口点。死代码比无代码更糟糕——它会带来维护负担和虚假的安全感。

The Four-Step Wiring Check

四步链路检查法

Before marking infrastructure "done", verify:

Entry Point Exists: How does user action trigger this code?
Call Graph Traced: Can you follow the path from entry to execution?
Integration Tested: Does an end-to-end test exercise this path?
No Dead Code: Is every built component actually reachable?

在标记基础设施“完成”前，需验证以下内容：

存在入口点：用户操作如何触发这段代码？
可追踪调用链路：能否从入口点追踪到执行的完整路径？
已完成集成测试：是否有端到端测试覆盖该路径？
无死代码：每个构建的组件是否都能被实际访问到？

DO

正确做法

Verify Entry Points

验证入口点

bash

undefined

bash

undefined

Hook registered?

钩子已注册？

grep -r "orchestration" .claude/settings.json

Skill activated?

Skill已激活？

grep -r "skill-name" .claude/skill-rules.json

Script executable?

脚本是否可执行？

ls -la scripts/orchestrate.py

Module imported?

模块已被导入？

grep -r "from orchestration_layer import" .

undefined

grep -r "from orchestration_layer import" .

undefined

Trace Call Graphs

追踪调用链路

python

undefined

python

undefined

Entry point (hook)

入口点（钩子）

.claude/hooks/pre-tool-use.sh ↓

Shell wrapper calls TypeScript

Shell包装器调用TypeScript

npx tsx pre-tool-use.ts ↓

TypeScript calls Python script

TypeScript调用Python脚本

spawn('scripts/orchestrate.py') ↓

Script imports module

脚本导入模块

from orchestration_layer import dispatch ↓

Module executes

模块执行

dispatch(agent_type, task)

undefined

dispatch(agent_type, task)

undefined

Test End-to-End

端到端测试

bash

undefined

bash

undefined

Don't just unit test the module

不要仅对模块进行单元测试

pytest tests/unit/orchestration_layer_test.py # NOT ENOUGH

pytest tests/unit/orchestration_layer_test.py # 这还不够

Test the full invocation path

测试完整调用路径

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

undefined

echo '{"tool": "Task"}' | .claude/hooks/pre-tool-use.sh # 验证该命令可正常运行

undefined

Document Wiring

记录链路信息

markdown

undefined

markdown

undefined

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

undefined

入口点：Task工具的PreToolUse钩子
注册位置：
```
.claude/settings.json
```
第45行
调用路径：hook → pre-tool-use.ts → scripts/orchestrate.py → orchestration_layer.py

测试用例：

tests/integration/task_orchestration_test.py

undefined

DON'T

错误做法

Build Without Wiring

未做链路连接就构建

python

undefined

python

undefined

BAD: Created orchestration_layer.py with 500 lines

错误示例：编写了500行的orchestration_layer.py

But nothing imports it or calls it

但没有任何代码导入或调用它

Result: Dead code, wasted effort

结果：死代码，白费功夫

GOOD: Start with minimal wiring, then expand

正确示例：从最小化链路连接开始，逐步扩展

1. Create hook (10 lines)

1. 创建钩子（10行代码）

2. Test hook fires

2. 测试钩子是否触发

3. Add script (20 lines)

3. 添加脚本（20行代码）

4. Test script executes

4. 测试脚本是否可执行

5. Add module logic (iterate)

5. 添加模块逻辑（迭代开发）

undefined

undefined

Create Parallel Routing

创建并行路由

python

undefined

python

undefined

BAD: Agent router has dispatch logic

错误示例：Agent路由器包含分发逻辑

AND skill-rules.json has agent selection logic

同时skill-rules.json包含Agent选择逻辑

AND hooks have agent filtering logic

且钩子包含Agent过滤逻辑

Result: Three places to update, routing conflicts

结果：需要更新三个位置，易出现路由冲突

GOOD: Single source of truth for routing

正确示例：路由逻辑单一可信源

skill-rules.json activates skill → skill calls router → router dispatches

skill-rules.json激活skill → skill调用路由器 → 路由器分发

undefined

undefined

Assume Imports Work

假设导入正常工作

python

undefined

python

undefined

BAD: Assume because you wrote the code, it's imported

错误示例：假设自己编写的代码已被导入

from orchestration_layer import dispatch # Does this path exist?

from orchestration_layer import dispatch # 这个路径是否存在？

GOOD: Verify imports at integration test time

正确示例：在集成测试时验证导入

uv run python -c "from orchestration_layer import dispatch; print('OK')"

undefined

uv run python -c "from orchestration_layer import dispatch; print('OK')"

undefined

Skip Integration Tests

跳过集成测试

bash

undefined

bash

undefined

BAD: Only unit test

错误示例：仅进行单元测试

pytest tests/unit/ # All pass, but nothing works end-to-end

pytest tests/unit/ # 全部通过，但端到端无法正常运行

GOOD: Integration test the wiring

正确示例：对链路进行集成测试

pytest tests/integration/ # Verify full call path

undefined

pytest tests/integration/ # 验证完整调用路径

undefined

Common Wiring Gaps

常见链路缺陷

Hook Not Registered

钩子未注册

json

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

Fix: Add hook registration:

json

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

json

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

修复方案：添加钩子注册：

json

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

Script Not Executable

脚本不可执行

bash

undefined

bash

undefined

Script exists but can't execute

脚本存在但无法执行

-rw-r--r-- scripts/orchestrate.py

Fix: Make executable

修复方案：设置为可执行

chmod +x scripts/orchestrate.py

undefined

chmod +x scripts/orchestrate.py

undefined

Module Not Importable

模块无法导入

python

undefined

python

undefined

Script tries to import but path is wrong

脚本尝试导入但路径错误

from orchestration_layer import dispatch

ModuleNotFoundError

模块未找到错误

Fix: Add to Python path or use proper package structure

修复方案：添加到Python路径或使用正确的包结构

sys.path.insert(0, str(Path(file).parent.parent))

undefined

sys.path.insert(0, str(Path(file).parent.parent))

undefined

Router Has No Dispatch Path

路由器无分发路径

python

undefined

python

undefined

BAD: Router has beautiful mapping

错误示例：路由器有完善的映射

AGENT_MAP = { "implement": ImplementAgent, "research": ResearchAgent, # ... 18 agent types }

AGENT_MAP = { "implement": ImplementAgent, "research": ResearchAgent, # ...18种Agent类型 }

But no dispatch function uses the map

但没有分发函数使用该映射

def route(task): return "general-purpose" # Hardcoded! Map is dead code

def route(task): return "general-purpose" # 硬编码！映射为死代码

GOOD: Dispatch actually uses the map

正确示例：分发函数实际使用映射

def route(task): agent_type = classify(task) return AGENT_MAP[agent_type]

undefined

def route(task): agent_type = classify(task) return AGENT_MAP[agent_type]

undefined

Wiring Checklist

链路检查清单

Real-World Examples

实际案例

Example 1: DAG Orchestration (This Session)

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

What was built:

opc/orchestration/orchestration_layer.py

(500+ lines)

```
opc/orchestration/dag/
```
(DAG builder, validator, executor)
18 agent type definitions
Sophisticated routing logic

Wiring gap:

No hook calls orchestration_layer.py
No script imports the DAG modules
Agent routing returns hardcoded "general-purpose"
Result: 100% dead code

Fix:

Create PreToolUse hook for Task tool
Hook calls
```
scripts/orchestrate.py
```
Script imports and calls
```
orchestration_layer.dispatch()
```
Dispatch uses AGENT_MAP to route to actual agents
Integration test: Submit Task → verify correct agent type used

已构建内容：

opc/orchestration/orchestration_layer.py

（500+行）

```
opc/orchestration/dag/
```
（DAG构建器、验证器、执行器）
18种Agent类型定义
复杂的路由逻辑

链路缺陷：

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

修复方案：

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

Example 2: Artifact Index (Previous Session)

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

What was built:

SQLite database schema
Indexing logic
Query functions

Wiring gap:

No hook triggered indexing
Files created but never indexed

Fix:

PostToolUse hook on Write tool
Hook calls indexing script immediately
Integration test: Write file → verify indexed

已构建内容：

SQLite数据库 schema
索引逻辑
查询函数

链路缺陷：

没有钩子触发索引
文件已创建但从未被索引

修复方案：

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

Detection Strategy

检测策略

Grep for Orphans

用Grep查找孤立模块

bash

undefined

bash

undefined

Find Python modules

查找Python模块

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

undefined

for file in $(find . -name ".py"); do module=$(basename $file .py) grep -r "from.$module import|import.*$module" . || echo "ORPHAN: $file" done

undefined

Check Hook Registration

检查钩子注册

bash

undefined

bash

undefined

List all hooks in .claude/hooks/

列出.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

undefined

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

undefined

Verify Script Execution

验证脚本可执行性

bash

undefined

bash

undefined

Find all Python scripts

查找所有Python脚本

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

undefined

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

undefined

Source

来源

This session: DAG orchestration wiring gap - 500+ lines of dead code discovered
Previous sessions: Artifact Index, LMStudio integration - wiring added after initial build

本次会话：DAG编排链路缺陷 - 发现500+行死代码
上几次会话：工件索引、LMStudio集成 - 初始构建后补充了链路连接