《智能体从调用走向执行》

① Claude Code 系列第 7 期：两个工作树并行实现，第三个只读代理统一审查

• 难度： 进阶｜动手： 25—40 分钟｜成本： Git 功能免费，模型调用计费
• 环境： Claude Code v2.1.198 或更高、Git 仓库；项目已有可运行测试
• 场景： 承接上期 Worktree 隔离，把前端和后端改动并行完成，再由独立审查代理只读复核。

先在项目中创建只读审查子代理：

mkdir -p .claude/agents
python - <<'PY'
from pathlib import Path
Path('.claude/agents/integration-reviewer.md').write_text('''---
name: integration-reviewer
description: 当前后端并行改动完成后，检查接口契约、测试覆盖和安全风险；只读，不修改文件。
tools: Read, Grep, Glob, Bash
model: haiku
---
你是集成审查员。先查看 git diff 和相关测试，再检查：
1. 前后端字段、状态码与错误处理是否一致；
2. 是否存在未覆盖的失败路径；
3. 是否引入密钥、权限、注入或越权风险；
4. 只输出按严重程度排序的问题、证据位置和最小修复建议。
不得编辑、写入或提交任何文件。
''', encoding='utf-8')
PY

git add .claude/agents/integration-reviewer.md
git commit -m "添加只读集成审查子代理"
claude --worktree api-change
# 另开一个终端，在同一仓库执行：
claude --worktree ui-change

在 api-change 会话发送：

只修改后端接口与后端测试。先记录测试基线，再实现“用户资料接口增加 display_name 字段”；不得修改前端文件。完成后运行相关测试并提交，最后给出提交哈希、接口契约和剩余风险。

在 ui-change 会话发送：

只修改前端展示与前端测试。根据现有接口约定支持 display_name；不得修改后端文件。若接口细节不明确，先列出假设，不要自行改后端。完成后运行相关测试并提交，最后给出提交哈希、字段假设和剩余风险。

两个分支完成后，在主工作区合并，并显式调用审查代理：

git merge api-change
git merge ui-change
claude

请调用 integration-reviewer 子代理，对刚合并的前后端改动做只读审查。必须检查 git diff、接口字段、错误处理和测试；不要修改文件。若发现阻断问题，给出文件与行号范围。

验证： git worktree list 能看到两个隔离工作树；两边提交只触及各自范围；审查代理没有产生新改动，git status --short 应为空。常见坑： 两个分支同时改共享类型文件会冲突；审查代理的 Bash 仍可执行命令，所以提示中必须明确只读；model: haiku 适合初筛，关键安全改动应升级模型或人工复核。不该用： 一个文件即可完成、接口边界不清或没有测试基线的改动。

参考：https://code.claude.com/docs/en/worktrees
https://code.claude.com/docs/en/sub-agents

下期预告： 第 8 期把并行实现升级为 Claude Code Agent Teams，并设置任务依赖与跨会话消息。

② Hermes Agent 系列第 7 期：研究、写作、审查三条工作代理通道

• 难度： 进阶｜动手： 25—40 分钟｜成本： 看板免费，各代理调用计费
• 环境： Hermes Agent 当前官方版；已有 researcher、writer、reviewer 三个配置档
• 场景： 承接上期持久 Kanban，把单条流程升级为有角色隔离、失败重试和人工批准门的工作队列。

先由人类确认三条通道可被看板识别：

hermes kanban init
hermes kanban assignees --json
hermes kanban stats --json

然后在具备 kanban_* 工具的编排代理对话中，完整发送：

请在当前 Kanban 建立“每周竞品简报”工作流，并严格使用 kanban_* 工具：
1. 建立“研究证据”任务，分配给 researcher；完成标准是至少5个一手来源、每条含URL和核验结论。
2. 建立“撰写简报”任务，分配给 writer，并把它设为依赖“研究证据”；不得在证据任务完成前启动。
3. 建立“事实审查”任务，分配给 reviewer，并设为依赖“撰写简报”；审查必须逐项核对来源、数字与措辞。
4. reviewer 发现可修复问题时必须请求修改并退回 writer，不得直接改稿；同一任务连续两次失败后标记阻塞，写清失败原因，等待人工解除。
5. reviewer 通过后也不要直接发布：添加评论“等待人工批准”，把最终任务置于阻塞状态。只有人类明确回复“批准发布”后，才解除阻塞并完成任务。
6. 每次交接必须附产物或URL；最后返回三个任务ID、依赖关系和当前状态。

人类侧观察与批准：

hermes kanban list
hermes kanban watch --kinds completed,blocked,review_requested,changes_requested
# 审阅通过并决定发布后，把实际最终任务ID传给：
hermes kanban unblock t_final
hermes kanban complete t_final --result "人工批准发布"

其中 t_final 是示意名称；执行时必须使用编排代理返回的真实任务 ID。验证： 写作任务在研究完成前保持未就绪；审查可退回写作；最终任务在人工批准前保持阻塞。常见坑： 模型工作代理应调用 kanban_* 工具，不应自行用 shell 驱动看板；assignee 必须与真实配置档名称一致；失败重试要留下事件和评论，不能静默重跑。不该用： 父代理只等一个短答案、无需跨重启恢复的任务。

参考：https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban
https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban-worker-lanes

下期预告： 第 8 期加入专用编排代理：只允许 Kanban 工具，不允许终端和文件工具，让调度与执行彻底分权。

③ Claude 模型系列第 7 期：定位账单异常来自价格、上下文、输出还是缓存

• 难度： 进阶｜动手： 25—35 分钟｜成本： 脚本免费，API 请求按实际使用计费
• 环境： Python 3.10+；沿用前两期生成的 claude_usage.jsonl
• 场景： 承接上期预算耗尽预测，把“费用突然上涨”拆成四类可行动原因。

保存为 claude_cost_diagnose.py：

import json, os
from collections import defaultdict
from datetime import date, datetime, timedelta
from pathlib import Path

LEDGER = Path(os.getenv("CLAUDE_LEDGER", "claude_usage.jsonl"))
TODAY = date.fromisoformat(os.getenv("REPORT_DATE", date.today().isoformat()))
PRICES = {
    "claude-sonnet-5": {"input": 2.0, "cache_read": 0.2, "cache_write": 2.5, "output": 10.0},
    "claude-haiku-4-5": {"input": 1.0, "cache_read": 0.1, "cache_write": 1.25, "output": 5.0},
}

def money(tokens, price):
    return float(tokens or 0) * price / 1_000_000

def row_cost(x):
    p = PRICES[x["model"]]
    return (money(x.get("input_tokens"), p["input"]) +
            money(x.get("cache_read_input_tokens"), p["cache_read"]) +
            money(x.get("cache_creation_input_tokens"), p["cache_write"]) +
            money(x.get("output_tokens"), p["output"]))

rows = []
for line in LEDGER.read_text(encoding="utf-8").splitlines():
    x = json.loads(line)
    x["day"] = datetime.fromisoformat(x["time"]).date()
    x["cost"] = row_cost(x)
    rows.append(x)

def summarize(start, end):
    s = defaultdict(float)
    picked = [x for x in rows if start <= x["day"] <= end]
    for x in picked:
        s["calls"] += 1
        s["cost"] += x["cost"]
        s["input"] += float(x.get("input_tokens", 0))
        s["output"] += float(x.get("output_tokens", 0))
        s["cache_read"] += float(x.get("cache_read_input_tokens", 0))
        s["cache_write"] += float(x.get("cache_creation_input_tokens", 0))
    total_in = s["input"] + s["cache_read"] + s["cache_write"]
    s["cache_hit"] = s["cache_read"] / total_in if total_in else 0
    for k in ("cost", "input", "output"):
        s[k + "_per_call"] = s[k] / s["calls"] if s["calls"] else 0
    return s

recent = summarize(TODAY - timedelta(days=2), TODAY)
base = summarize(TODAY - timedelta(days=9), TODAY - timedelta(days=3))

def ratio(a, b):
    return a / b if b else 0

print(f"近3日费用：${recent['cost']:.2f}；此前7日：${base['cost']:.2f}")
print(f"单次输入变化：{ratio(recent['input_per_call'], base['input_per_call']):.2f}x")
print(f"单次输出变化：{ratio(recent['output_per_call'], base['output_per_call']):.2f}x")
print(f"缓存命中：{base['cache_hit']:.1%} -> {recent['cache_hit']:.1%}")

causes = []
if ratio(recent["input_per_call"], base["input_per_call"]) >= 1.30:
    causes.append("上下文膨胀：检查历史消息、工具输出和重复系统提示")
if ratio(recent["output_per_call"], base["output_per_call"]) >= 1.30:
    causes.append("输出变长：降低最大输出或要求结构化短答")
if base["cache_hit"] - recent["cache_hit"] >= 0.15:
    causes.append("缓存失效：检查静态前缀、模型版本和提示顺序")
models = sorted({x["model"] for x in rows if TODAY - timedelta(days=2) <= x["day"] <= TODAY})
if len(models) > 1:
    causes.append("模型结构变化：近3日混用了不同价位模型，请按模型拆账")
print("诊断：")
for c in causes or ["未发现明显结构异常；检查调用次数、供应商加价和价格表变更"]:
    print("-", c)

运行：

export CLAUDE_LEDGER="claude_usage.jsonl"
export REPORT_DATE="2026-08-13"
python claude_cost_diagnose.py

验证： 人为复制一段长上下文到近三日记录，脚本应提示“上下文膨胀”；把缓存读取词元降低，应提示“缓存失效”。常见坑： 官方 Claude Sonnet 5 当前标准价为输入 2 美元、输出 10 美元／百万词元，但中转站、Bedrock、Google Cloud、区域端点可能采用不同价格；Claude 4.7 及以后分词器对同一文本可能产生约 30% 更多词元，不能把全部增长误判为业务膨胀。不该用： 账本缺少输入、输出、缓存字段，或不同供应商时间口径尚未统一时。

参考：https://platform.claude.com/docs/en/about-claude/pricing

下期预告： 第 8 期把诊断结果接入自动路由：低风险任务降级 Haiku，高风险任务保留 Sonnet，并设置费用熔断。