《执行系统成为新战场》

① Claude Code 系列第 15 期：把失败时间线升级为敏感字段脱敏报告

难度：进阶｜预计动手时间：35 分钟｜成本：免费｜环境：Claude Code 当前 Hooks 机制、Python 3.9+；前置：上一期的 .claude/failure-timeline.jsonl

适用场景： 上一期已经记录权限拒绝、工具失败和接口失败。本期把命令参数、文件路径、邮箱和疑似密钥先脱敏，再生成会话结束报告，减少把敏感输入写入长期日志的风险。

1. 新建 .claude/hooks/sanitize_failure_timeline.py，从标准输入读取 Hook JSON。
2. 在写入前对疑似密钥、邮箱、绝对路径和长令牌做替换；不要把原始 tool_input 直接落盘。
3. 把下面配置放入 .claude/settings.json 的 StopFailure 和 PostToolUseFailure 事件中。
4. 完成一次失败测试后，确认日志里出现 [已脱敏]，并且没有完整密钥或客户邮箱。

#!/usr/bin/env python3
"""Claude Code Hook：只保存脱敏后的失败摘要。"""
import json, pathlib, re, sys
from datetime import datetime, timezone

raw = json.load(sys.stdin)
text = json.dumps(raw.get("tool_input", ""), ensure_ascii=False)
text = re.sub(r"(?i)(api[_-]?key|token|secret|password)\s*[:=]\s*[^,\s}]+", r"\1=[已脱敏]", text)
text = re.sub(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}", "[邮箱已脱敏]", text)
text = re.sub(r"([A-Za-z]:)?[/\\][^\"']+", "[路径已脱敏]", text)
text = re.sub(r"\b[A-Za-z0-9_-]{32,}\b", "[长令牌已脱敏]", text)
record = {
    "时间": datetime.now(timezone.utc).isoformat(),
    "事件": raw.get("hook_event_name", "未知事件"),
    "工具": raw.get("tool_name"),
    "错误": raw.get("error") or raw.get("error_type"),
    "脱敏工具输入": text,
}
path = pathlib.Path(".claude/failure-timeline-safe.jsonl")
path.parent.mkdir(parents=True, exist_ok=True)
with path.open("a", encoding="utf-8") as f:
    f.write(json.dumps(record, ensure_ascii=False) + "\n")
print("{}")

配置示例：

{
  "hooks": {
    "PostToolUseFailure": [{"matcher": "*", "hooks": [{"type": "command", "command": "python .claude/hooks/sanitize_failure_timeline.py", "timeout": 10}]}],
    "StopFailure": [{"matcher": "rate_limit|overloaded|authentication_failed|billing_error|server_error|unknown", "hooks": [{"type": "command", "command": "python .claude/hooks/sanitize_failure_timeline.py", "timeout": 10}]}]
  }
}

成功标志： failure-timeline-safe.jsonl 每次失败增加一行，行内只出现脱敏后的工具输入。常见坑： 正则脱敏不是完美的秘密扫描器，二进制内容、编码后的密钥和业务专用格式仍需专门扫描；Hook 本身失败时不要影响主流程。什么情况下不该用： 需要完整取证的安全事故不要只保留这份脱敏日志，应在受控、加密且有权限审计的环境另行保存原始证据。

参考：Claude Code Hooks 官方文档
https://code.claude.com/docs/en/hooks

下期预告： 第 16 期把失败事件分成“可重试、需降级、必须人工处理”三类，并为每类生成不同的停止理由。

② Hermes Agent 系列第 15 期：用 Kanban 的父子依赖和失败熔断组织研究流水线

难度：进阶｜预计动手时间：30 分钟｜成本：免费｜环境：Hermes Agent 当前 Kanban 功能、两个以上 profile；前置：理解 kanban_create、kanban_request_review 和 kanban_request_changes

适用场景： 将“检索→分析→写作→复核”变成可暂停、可接力的长期任务。Hermes 官方文档说明 Kanban 是持久任务板，任务和交接写入共享数据库；它适合跨代理、可恢复、需要人工介入的工作，而不是一次性问答。

1. 创建父任务“制作一份研究简报”，把四个子任务写清验收条件。
2. 让检索任务完成后再开放分析任务；分析失败两次就阻塞父任务，等待人工评论。
3. 写作者只读取已完成的分析结果，不直接把未核验的检索草稿发布出去。
4. 复核者调用请求修改或完成，父任务只在所有子任务完成后关闭。

面向 Hermes 工具调用的示例：

kanban_create(
  title="制作本周机器人研究简报",
  body="父任务。验收：4条以上一手来源、每条有原始链接、事实与判断分开。失败两次则阻塞。",
  assignee="researcher"
)

kanban_create(
  title="复核机器人论文与数据",
  body="子任务。只接受论文原文；记录论文编号、提交日期、作者报告与未复现限制。",
  assignee="reviewer"
)

kanban_request_changes(
  reason="第2条只有搜索摘要，没有原始论文链接；补齐后再进入写作。"
)

成功标志： 任务历史中能看到创建、交接、要求修改、重新复核和完成；失败不会无限重跑，而是进入阻塞状态。常见坑： 不要让模型通过 shell 假造 Kanban 工具调用；官方文档区分了代理使用的 kanban_* 工具和人类/脚本使用的 CLI；不要把“做好一点”写成验收条件。什么情况下不该用： 只需要一次短回答、没有交接和恢复需求时，用普通委派更轻量。

参考：Hermes Agent Kanban 官方文档
https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban

下期预告： 第 16 期加入“研究资料冻结点”和“复核不通过自动回退”，避免新资料覆盖已经引用的证据。

③ Claude 模型系列第 15 期：把限流响应头变成动态退避与故障分流

难度：高级｜预计动手时间：35 分钟｜成本：正式请求按账号计费；可先用错误模拟免费测试｜环境：Python 3.9+ 标准库、Claude API；前置：ANTHROPIC_API_KEY、CLAUDE_MODEL

适用场景： 上一期已经按 RPM、输入词元和输出词元排队。本期根据 retry-after 处理短期限流，把认证、计费、权限、月度消费上限和服务过载分开，不对永远不会成功的错误盲目重试。

#!/usr/bin/env python3
"""Claude API 最小故障分流示例：密钥来自环境变量，不写入代码。"""
import json, os, time, urllib.error, urllib.request

KEY = os.environ["ANTHROPIC_API_KEY"]
MODEL = os.environ["CLAUDE_MODEL"]


def call(text, attempt=0):
    body = json.dumps({"model": MODEL, "max_tokens": 300,
                       "messages": [{"role": "user", "content": text}]}).encode()
    req = urllib.request.Request(
        "https://api.anthropic.com/v1/messages", data=body,
        headers={"x-api-key": KEY, "anthropic-version": "2023-06-01",
                 "content-type": "application/json"}, method="POST")
    try:
        with urllib.request.urlopen(req, timeout=60) as r:
            return json.loads(r.read())
    except urllib.error.HTTPError as e:
        retry_after = e.headers.get("retry-after")
        detail = e.read().decode("utf-8", "replace")
        if e.code == 429 and retry_after and attempt < 3:
            # 有明确等待时间的短期限流才重试
            time.sleep(float(retry_after))
            return call(text, attempt + 1)
        if e.code in (401, 403):
            raise SystemExit("认证或权限失败：停止重试，检查密钥和工作区权限。")
        if e.code == 402:
            raise SystemExit("计费失败：检查付款方式和账户额度。")
        if e.code == 429:
            raise SystemExit("达到限流或消费上限：没有可用等待时间，转入人工或降级队列。")
        if e.code >= 500 and attempt < 2:
            time.sleep(2 ** attempt)
            return call(text, attempt + 1)
        raise SystemExit(f"服务请求失败，状态码 {e.code}：请保存请求编号后人工检查。")

answer = call("请用一句中文说明：为什么智能体需要权限边界？")
print("请求成功：", "".join(x.get("text", "") for x in answer.get("content", [])))

验证方法： 正常请求应输出一行中文回答；真实环境中查看 HTTP 响应头的 retry-after，并记录请求编号。Claude 官方错误文档说明 401 是密钥问题、403 是权限问题、402 是计费问题、429 可能是限流或消费上限；这些错误不能用同一种重试策略处理。常见坑： 429 不一定带 retry-after；月度消费上限通常重试无效。什么情况下不该用： 多机器高并发、要求严格一次性执行或需要持久队列时，不要把单进程脚本当作生产级调度器。

参考：Claude API 词元计数、限流与错误官方文档
https://platform.claude.com/docs/en/api/messages/count_tokens
https://platform.claude.com/docs/en/api/rate-limits
https://platform.claude.com/docs/en/api/errors

下期预告： 第 16 期把故障分流接入成本对账，分别统计成功请求、重试请求、降级请求和人工接管。