《入口并购与信任重估》

Claude Code 系列第 10 期：用 TeammateIdle Hook 防止队友过早停工

难度： 进阶｜**动手：** 20—30 分钟｜**成本：** 配置免费，Claude Code 调用按订阅或 API 计费

环境： Claude Code 当前官方版；已使用 Agent Teams；承接第 9 期 TaskCompleted 测试门禁

场景： 队友完成手头任务后准备进入空闲状态时，先检查是否留下审查报告和测试记录。官方文档确认 `TeammateIdle` 在队友即将空闲时触发，退出码 2 会把标准错误反馈给队友并让其继续工作；它不支持 matcher。

创建 `.claude/hooks/check-idle.py`：

#!/usr/bin/env python3
import json
import sys
from pathlib import Path
# 读取 Claude Code 传入的事件信息，保留解析步骤便于以后扩展。
payload = json.load(sys.stdin)
project = Path(payload.get("cwd", "."))
# 约定：团队任务结束前必须留下这两份可审计产物。
required = [
    project / "artifacts" / "review.md",
    project / "artifacts" / "test-results.txt",
]
missing = [str(path.relative_to(project)) for path in required if not path.exists()]
if missing:
    print(
        "你还不能进入空闲状态。请先补齐以下产物：" + "、".join(missing)
        + "。若任务不需要其中某项，请在 review.md 中写明理由。",
        file=sys.stderr,
    )
    raise SystemExit(2)
raise SystemExit(0)

在 `.claude/settings.json` 中加入：

{
  "hooks": {
    "TeammateIdle": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python \"$CLAUDE_PROJECT_DIR/.claude/hooks/check-idle.py\"",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

向团队负责人发送：

请创建一个 Agent Team，把实现、测试、独立审查拆成有依赖关系的任务。每个队友准备空闲前，都必须留下 artifacts/review.md 和 artifacts/test-results.txt；如果 TeammateIdle Hook 拒绝空闲，就根据反馈补齐证据，不得删除 Hook 或伪造通过记录。所有任务完成后，由负责人汇总仍需人工确认的风险。

成功标志： 缺少任一产物时，队友收到中文反馈并继续工作；文件齐全后才进入空闲。**常见坑：** Hook 会对每个队友触发，产物命名必须统一；只检查文件存在不能证明内容真实，仍需第 9 期测试门禁与独立审查；Windows 下使用 `python`，macOS/Linux 可按环境改为 `python3`。**不该用：** 极短、无共享产物的一次性任务不应强制这套门禁。

参考：https://code.claude.com/docs/en/hooks#teammateidle

下期预告： 第 11 期加入 `SubagentStart` 与 `SubagentStop` 审计日志，记录谁启动了哪个子代理、使用何种代理类型以及结束状态。

Hermes Agent 系列第 10 期：用最大重试、超时和心跳把看板循环熔断

难度： 进阶｜**动手：** 20—30 分钟｜**成本：** 配置免费，工作代理调用按模型计费

环境： Hermes Agent 当前官方版；已有第 9 期独立 reviewer 档案与 Kanban 看板

场景： 防止实现者与 reviewer 反复退回、协议违规后无限重生，或长任务没有心跳而被误判为崩溃。官方 Kanban 文档说明：任务可设置 `max_retries` 覆盖默认边界；协议违规连续达到默认 3 次会自动阻塞；运行超过 `timeout_seconds` 且最近一小时无心跳时会被回收。

由人工创建一个有界任务：

hermes kanban create "实现并审查登录失败锁定机制" \
  --assignee implementer \
  --reviewer reviewer \
  --max-retries 2 \
  --timeout-seconds 3600

让实现者在长任务中主动写心跳，并明确终止条件：

你负责该 Kanban 任务。开始后先读取完整任务、历史尝试和 reviewer 意见；每完成一个可验证阶段就调用 kanban_heartbeat，说明已完成内容、下一步和预计剩余时间。最多接受两轮退回：若同一根因第二次出现，或依赖缺失导致无法验证，请调用 kanban_block，写清阻塞原因和需要人工决定的事项。完成时必须调用 kanban_request_review，不得只用自然语言宣布完成。

给 reviewer 的完整规则：

你是独立 reviewer。只核验证据，不直接修改实现。第一次不通过时调用 kanban_request_changes，按“问题、证据、修复标准”列出清单；第二次仍出现同一根因时，不再继续循环，调用 kanban_block，并说明需要人工裁决的最小问题。通过时提交批准结论，列出测试、权限边界和残余风险。

观察任务：

hermes kanban watch --kinds review_requested,changes_requested,blocked,completed

成功标志： 长任务持续出现心跳；重复退回不会无限循环；超过重试或协议违规边界时任务进入 blocked，由人工决定是否解锁。**常见坑：** `timeout_seconds` 太短会回收仍在正常工作的任务；没有心跳的长推理容易丢失当前进度；`max_retries` 是保护边界，不是鼓励把错误重跑两次。**不该用：** 必须一次完成、且失败后不得自动重试的付款、发布和删除任务，应从一开始就要求人工批准。

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

下期预告： 第 11 期把 researcher、writer、reviewer 分到独立 worker lanes，并为每条泳道设置并发上限与专属工作区。

Claude 模型系列第 10 期：用幂等键和状态查询处理“超时但可能已成功”

难度： 高级｜**动手：** 35—50 分钟｜**成本：** 示例代码免费，Claude API 按实际词元计费

环境： Python 3.10+；`anthropic>=0.60,<1`；设置 `ANTHROPIC_API_KEY`

场景： 承接第 9 期主备切换。网络超时不等于服务端未处理；对发信、付款、发布等副作用任务，不能收到超时就盲目重放。本期用本地幂等账本先登记操作，再调用 Claude 生成“执行计划”，只有状态仍为 `planned` 才允许业务执行器接手。

安装依赖：

python -m pip install "anthropic>=0.60,<1"

保存为 `safe_claude_operation.py`：

import hashlib
import json
import os
import sys
from pathlib import Path
import anthropic
LEDGER = Path("claude_operations.json")
MODEL = os.getenv("CLAUDE_MODEL", "claude-sonnet-5")

def load_ledger():
    if not LEDGER.exists():
        return {}
    return json.loads(LEDGER.read_text(encoding="utf-8"))

def save_ledger(data):
    LEDGER.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")

def operation_key(action, target, payload):
    raw = json.dumps(
        {"action": action, "target": target, "payload": payload},
        ensure_ascii=False,
        sort_keys=True,
    )
    return hashlib.sha256(raw.encode("utf-8")).hexdigest()

def plan_once(action, target, payload):
    key = operation_key(action, target, payload)
    ledger = load_ledger()
    # 同一业务操作已有记录时先返回状态，绝不直接重放。
    if key in ledger:
        return key, ledger[key]
    ledger[key] = {"status": "planning", "action": action, "target": target}
    save_ledger(ledger)
    client = anthropic.Anthropic(
        api_key=os.environ["ANTHROPIC_API_KEY"],
        max_retries=0,
        timeout=60,
    )
    try:
        message = client.messages.create(
            model=MODEL,
            max_tokens=700,
            messages=[{
                "role": "user",
                "content": (
                    "你只负责生成执行计划，不得声称已经执行。"
                    f"\n动作：{action}\n目标：{target}\n数据：{json.dumps(payload, ensure_ascii=False)}"
                    "\n输出：前置检查、不可逆风险、执行步骤、成功查询方法、补偿动作。"
                ),
            }],
        )
        text = "".join(block.text for block in message.content if block.type == "text")
        ledger = load_ledger()
        ledger[key] = {
            "status": "planned",
            "request_id": getattr(message, "_request_id", None),
            "plan": text,
        }
        save_ledger(ledger)
        return key, ledger[key]
    except (anthropic.APITimeoutError, anthropic.APIConnectionError) as exc:
        ledger = load_ledger()
        ledger[key] = {
            "status": "unknown",
            "request_id": getattr(exc, "request_id", None),
            "next_step": "先查询供应商日志或业务系统状态，确认未成功后再人工重试",
        }
        save_ledger(ledger)
        return key, ledger[key]

if __name__ == "__main__":
    action = sys.argv[1] if len(sys.argv) > 1 else "发布公告"
    target = sys.argv[2] if len(sys.argv) > 2 else "测试环境"
    payload = {"title": "维护通知", "body": "今晚 22:00 进行例行维护。"}
    key, result = plan_once(action, target, payload)
    print(json.dumps({"operation_key": key, **result}, ensure_ascii=False, indent=2))

运行两次相同命令：

export ANTHROPIC_API_KEY="你的环境变量密钥"
python safe_claude_operation.py "发布公告" "测试环境"
python safe_claude_operation.py "发布公告" "测试环境"

成功标志： 第一次生成计划并写入唯一 `operation_key`；第二次直接返回账本状态，不重复调用模型；若发生超时，状态变为 `unknown`，提示先查状态而不是重试。**常见坑：** 幂等键必须包含真正决定副作用的字段；本示例只生成计划，不执行发布；实际业务系统最好使用其官方幂等键或唯一请求号；400、401、403 等请求错误不应按超时处理。**不该用：** 如果下游系统没有状态查询、撤销或补偿能力，不应让模型自动执行不可逆操作。

参考：https://platform.claude.com/docs/en/api/errors
https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python

下期预告： 第 11 期加入指数退避、`Retry-After` 处理和并发限流器，把 429、529 与网络超时分开治理。