系列导航：系列目录 | 上一篇：从零实现 Harness Agent：工具并发边界设计

本节目标

导读：本篇属于第五部分「Subagent 与可观测性」的收束篇：把一次 Agent run 中的模型、工具、审批和 Subagent 行为记录成可回放的决策树。

本节要实现的是本地轻量级 Agent Tracing：把一次运行中的主循环、模型调用、工具调用、审批恢复和 Subagent 组织成 JSON 决策树。

完成这一节后，你会理解 tracing 应该插在运行时观测层，而不是污染 provider、tool 或 message 协议。

摘要

本文要说明如何在 tiny-claw 中实现一套本地轻量级 Agent Tracing，把一次 Agent 运行固化为可回放的 JSON 决策树。它适合 AI Agent 框架开发者、Python CLI 开发者和后续维护者阅读。读完后，你会理解 tracing 应该插在架构的什么位置、如何记录 agent.run -> agent.step -> llm.call / tool.call，以及如何在保护隐私的前提下保留足够的排障信息。

阅读提示：本篇内容较长。快速阅读时可以先看下面的“快速版”，再看“整体方案”“使用方式”和“总结”；需要维护实现时，再深入“核心实现”和“设计取舍与注意事项”。

快速版

Tracing 要解决的是“运行后无法复盘”的问题。日志能告诉你发生了什么片段，但很难还原一次 run 的树形结构：哪一步调用了模型，模型返回了哪些工具，哪个工具触发了审批，哪个 explore 又启动了子智能体。

tiny-claw 的设计选择是：

• Tracing 是运行时观测层，不进入 provider、tool 或 message 协议。
• 一次运行以 agent.run 为根，下面挂 agent.step、llm.call、tool.call、approval.* 和 subagent.run。
• 默认 metadata 模式只保存 hash、keys、chars、耗时等元数据，避免把 prompt、工具参数和模型正文写进 trace。
• 需要更强复盘能力时，replay 模式才保存脱敏和截断后的 payload。
• 并发工具调用必须显式传 parent span，保证 children 归属正确、输出顺序稳定。

如果你只想知道这套 tracing 为什么存在，可以读到这里再跳到“使用方式”。如果你要改实现，则继续看下面的 span 数据模型、注入点和并发处理。

背景与问题

Agent 系统很容易变成黑盒。用户看到的是最终回复，开发者看到的是日志，但一次运行内部到底经历了哪些模型调用、工具调用、审批暂停和子 Agent 探索，往往只能靠散落的日志还原。

这在引入 ReAct 主循环、工具系统、人工审批和 Subagent 之后尤其明显：

• 模型可能在同一步返回多个 tool calls。
• 工具可能成功、失败、被 deny，或因为高危操作进入审批暂停。
• 审批恢复会从 checkpoint 继续执行，而不是重新开始。
• explore 工具内部会启动一个 Explorer Subagent，形成嵌套运行链路。
• 并发 read 会跨线程执行，普通上下文变量不会自动传到 worker thread。

如果没有结构化 trace，维护者只能在日志、usage 记录、checkpoint 和 session memory 之间来回拼图。Tracing 模块的目标，是把这些运行时事件统一记录成一棵本地 JSON 决策树。

设计目标

• 架构边界清晰：Tracing 是运行时观测层，不属于 provider、memory 或 tool schema。
• 不污染核心协议：不向 LLMRequest、LLMResponse、Message、ToolCall、ToolDefinition 注入 tracing 字段。
• 默认保护隐私：默认 metadata 模式只记录 hash、keys、chars 等元数据，不保存 prompt、tool args、assistant text 原文。
• 可回放结构：输出 agent.run -> agent.step -> llm.call / tool.call / approval / subagent.run 的树形 JSON。
• 失败不影响主流程：recorder 写入失败只记录 warning，不打断 Agent 运行。
• 并发安全：并发工具 span 仍能挂到正确的父 agent.step 下，并保持 children 输出顺序稳定。
• 可测试：span 父子关系、隐私策略、错误关闭、并发排序、审批和子 Agent 链路都有自动化测试保护。

整体方案

设计判断很直接：Tracing 不是 provider 功能，也不是 memory 功能。它是横切的运行时观测层，插在 app.py 装配出的运行链路旁边，由 MainLoop、provider decorator、ToolExecutor、审批恢复器和 Subagent Runner 在关键生命周期点写入 span。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

flowchart TD
  CLI["CLI / Integration Entry"] --> App["app.py assembly"]
  App --> Engine["MainLoop"]
  App --> Provider["UsageTrackingProvider"]
  App --> Subagent["SubagentRunner"]
  Engine --> Run["agent.run"]
  Run --> Step["agent.step"]
  Step --> LLM["llm.call"]
  Step --> Tool["tool.call"]
  Tool --> ApprovalPause["approval.pause"]
  Tool --> Explore["explore tool"]
  Explore --> SubagentRun["subagent.run"]
  SubagentRun --> ChildLLM["child llm.call"]
  SubagentRun --> ChildTool["child tool.call"]
  Engine -. records .-> Trace["tracing module"]
  Provider -. records .-> Trace
  Tool -. records .-> Trace
  Subagent -. records .-> Trace
  Trace --> JSON["state_dir/sessions/session_key/traces/trace_id.json"]

整体链路分为三层：

1. app.py 创建并注入同一个 Tracer。
2. 运行时模块在关键边界创建 span。
3. FileTraceRecorder 在 trace 结束时把树写成本地 JSON。

典型输出结构是：

1
2
3
4
5
6
7

agent.run
  agent.step
    llm.call
    tool.call
      approval.pause
  agent.step
    llm.call

当 explore 工具启动子 Agent 时，结构会扩展为：

1
2
3
4

tool.call explore
  subagent.run
    llm.call
    tool.call read

核心实现

关键文件：

• src/tiny_claw/_internal/tracing/__init__.py
• src/tiny_claw/_internal/app.py
• src/tiny_claw/_internal/engine/main_loop.py
• src/tiny_claw/_internal/provider/tracking.py
• src/tiny_claw/_internal/engine/tool_executor.py
• src/tiny_claw/_internal/engine/approval_resume.py
• src/tiny_claw/_internal/subagent/runner.py
• src/tiny_claw/_internal/settings.py

Trace 数据模型

Tracing 模块的核心是 TraceSpan 和 TraceTree。TraceTree 持有 root span，TraceSpan 用 children 直接保存树结构。

1
2
3
4
5
6
7
8
9
10
11

@dataclass
class TraceSpan:
    span_id: str
    parent_id: str | None
    kind: str
    name: str
    started_at: str
    sequence: int
    status: TraceStatus = "ok"
    attributes: dict[str, Any] = field(default_factory=dict)
    children: list[TraceSpan] = field(default_factory=list)

begin_trace() 创建 root span，并把当前 trace state 和当前 span id 写入 ContextVar：

1
2

_TRACE_STATE.set(state)
_CURRENT_SPAN_ID.set(root.span_id)

之后 begin_span() 会优先使用显式 parent_span_id，否则使用当前上下文里的 _CURRENT_SPAN_ID：

1

parent_id = parent_span_id or _CURRENT_SPAN_ID.get() or resolved_state.tree.root.span_id

真正建立 children 关系的是这段逻辑：

1
2
3

with resolved_state.lock:
    parent.children.append(span)
    resolved_state.spans_by_id[span.span_id] = span

这意味着 JSON 不是最后根据 parent_id 临时拼出来的，而是在 span 创建时就已经形成了树。

应用装配

app.py 根据 settings 创建 tracer：

1
2
3
4
5
6
7
8

def _build_tracer(settings: Settings) -> Tracer:
    if settings.trace_mode == "off":
        return NullTracer()
    return Tracer(
        recorder=FileTraceRecorder(settings.state_dir),
        capture_mode=cast(TraceMode, settings.trace_mode),
        max_payload_chars=settings.trace_max_payload_chars,
    )

同一个 tracer 会被注入到：

• UsageTrackingProvider
• SubagentRunner
• MainLoop

这样 provider、tool executor、subagent 都能挂到同一棵 trace 树上。

主循环 span

MainLoop.run() 创建 root agent.run，每一轮创建 agent.step：

1
2
3
4
5
6
7

trace_root = self.tracer.begin_trace(
    trace_id=run_id,
    session_key=session.key,
    session_source=session.source,
    kind="agent.run",
    name="tiny_claw.run",
)

每个 step 会记录当前轮次、phase、tool policy、可见工具数量和消息数量。上下文压缩发生时，会写入 context.compacted event。

运行结束时，RunResult 会带上：

• trace_id
• trace_path

这让 CLI 或集成入口可以向用户展示 trace 文件位置。

LLM 调用 span

UsageTrackingProvider.complete() 在 provider 外层创建 llm.call：

1
2
3
4
5
6
7
8
9
10

span = self.tracer.begin_span(
    kind="llm.call",
    name=f"llm.{self.inner.name}",
    attributes={
        "provider": self.inner.name,
        "message_count": len(request.messages),
        "tool_choice": request.tool_choice.value,
        "visible_tools": len(request.tools),
    },
)

成功时记录 model、token usage、tool call 数量、文本长度和 latency。失败时记录 error_type，并把 span 标为 error。

工具调用 span

ToolExecutor._execute_one() 为每个工具创建 tool.call：

1
2
3
4
5
6
7

span = self.tracer.begin_span(
    kind="tool.call",
    name=f"tool.{tool_call.name}",
    attributes=attributes,
    parent_span_id=trace_parent_span_id,
    state=trace_state,
)

工具 span 会记录：

• tool_call_id
• tool_name
• tool_call_index
• 参数 hash / keys / chars
• observation hash / chars
• latency
• is_error
• suspended
• denied
• approval_id
• checkpoint_id

如果工具因为人工审批暂停，会在 tool.call 下创建 approval.pause：

1
2

tool.call
  approval.pause

并发工具的 parent span

连续 read 可以并发执行，但 worker thread 不会自动继承 ContextVar。因此并发前要捕获当前 trace state 和当前 span id：

1
2

trace_state = self.tracer.current_state()
trace_parent_span_id = self.tracer.current_span_id()

线程里创建工具 span 时显式传入：

1
2

trace_state=trace_state,
trace_parent_span_id=trace_parent_span_id,

这样多个并发 read 都会挂到同一个 agent.step 下。实现还会保留原始 tool_call_index，确保 JSON children 输出顺序与模型 tool call 顺序一致。

隐私模式

Tracing 支持三种模式：

• off：关闭 tracing。
• metadata：默认模式，只保存 hash、keys、chars。
• replay：保存脱敏、截断后的 payload。

metadata 模式下不会写入原始 prompt、tool args 或 assistant text：

1
2
3
4
5

return {
    f"{prefix}_hash": _sha256(serialized),
    f"{prefix}_keys": keys,
    f"{prefix}_chars": len(serialized),
}

replay 模式会经过敏感字段脱敏和长度截断，例如包含 token、secret、password、authorization、api_key 的键会被替换为 [redacted]。

使用方式

默认配置已经启用 metadata tracing。普通用户无需额外配置，只要运行 Agent，就会在 state directory 下生成 trace JSON。

运行一次 echo provider 冒烟：

1
2
3

TINY_CLAW_PROVIDER=echo \
TINY_CLAW_STATE_DIR=.tmp-state \
uv run tiny-claw run "hello tiny claw"

trace 文件路径形如：

1

.tmp-state/sessions/<session_key>/traces/<trace_id>.json

关闭 tracing：

1

TINY_CLAW_TRACE_MODE=off uv run tiny-claw run "hello"

开启 replay 模式：

1
2
3

TINY_CLAW_TRACE_MODE=replay \
TINY_CLAW_TRACE_MAX_PAYLOAD_CHARS=4000 \
uv run tiny-claw run "请读取 README 并总结"

注意：replay 模式会保存脱敏和截断后的 payload。它适合本地调试和回放，不建议在不受控环境中默认开启。

一个简化后的 trace JSON 结构类似：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "trace_id": "trace-id",
  "capture_mode": "metadata",
  "root": {
    "kind": "agent.run",
    "status": "ok",
    "children": [
      {
        "kind": "agent.step",
        "children": [
          {"kind": "llm.call"},
          {"kind": "tool.call"}
        ]
      }
    ]
  }
}

测试与验证

Tracing 模块有独立单元测试：

1

uv run pytest tests/test_tracing.py

Provider span 和错误路径：

1

uv run pytest tests/test_provider_tracking.py

工具调用、并发 parent span 和 children 顺序：

1

uv run pytest tests/test_tool_executor.py -k tracing

主循环、审批暂停和审批恢复 trace：

1
2

uv run pytest tests/test_engine.py -k trace
uv run pytest tests/test_engine.py -k approval

Subagent trace：

1

uv run pytest tests/test_subagent.py -k trace

完整验证命令：

1
2
3
4

uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest

CLI 冒烟：

1
2
3

TINY_CLAW_PROVIDER=echo \
TINY_CLAW_STATE_DIR=.tmp-state \
uv run tiny-claw run "hello tiny claw"

手动检查 trace JSON 后，删除临时状态目录：

1

rm -rf .tmp-state

已验证的行为包括：

• metadata 模式不保存 prompt 原文和 assistant 输出原文。
• agent.run -> agent.step -> llm.call 基础链路可生成。
• 工具链路会生成 tool.call。
• 审批暂停会生成 approval.pause。
• 审批恢复会生成 approval.resume。
• Explorer Subagent 会生成 subagent.run，内部 LLM/tool span 挂在其下。
• 并发 read 的 tool span 挂到同一个 agent.step 下，并按原始 tool call 顺序输出。

待确认：真实 OpenAI / Claude provider 下的 trace 结构建议在有凭据的环境中补充一次 live 验证。当前实现通过 provider decorator 接入，理论上与具体 provider 无关。

设计取舍与注意事项

为什么不是 provider 功能

Provider 只应该负责把统一的 LLMRequest 转成厂商 SDK 请求，再把响应转回统一的 LLMResponse。Tracing 如果塞进 provider 协议，会让所有厂商适配器都知道运行时观测细节，破坏 provider adapter 的边界。

因此，模型调用 tracing 放在 UsageTrackingProvider decorator 中，而不是放进 OpenAI 或 Claude provider 里。

为什么不是 memory 功能

Memory 保存的是 session 维度的长期状态，例如最近 prompt、response 或计划文件。Trace 保存的是一次 run 的执行树，生命周期不同，读取方式也不同。

因此 trace 文件写在 session 目录下，但不进入 memory store 的读写协议。

为什么不引入 OpenTelemetry

OpenTelemetry 更适合跨服务、集中采集和平台化观测。当前目标是本地轻量 JSON 决策树，不上传外部平台，也不增加运行时依赖。

这个取舍让 v1 更简单：

• 本地文件可直接查看。
• 测试不需要外部服务。
• recorder 失败不会影响主流程。
• 后续如果接入 OpenTelemetry，可以把 TraceRecorder 扩展成新的 recorder，而不改核心调用点。

为什么默认 metadata

Agent 的 prompt、tool args 和 tool observation 可能包含源码、路径、业务信息或用户输入。默认保存原文会让 tracing 从排障工具变成隐私风险。

所以默认 metadata 只保存：

• hash
• keys
• 字符数
• 状态和耗时

只有显式设置 TINY_CLAW_TRACE_MODE=replay 时，才保存脱敏和截断后的 payload。

children 如何关联

Span 创建时直接挂到 parent 的 children，同时写入 spans_by_id 索引。普通调用依赖 _CURRENT_SPAN_ID 找到父节点；跨线程工具调用显式传入 parent_span_id 和 trace state。

这个设计让大部分调用点不用手写 parent，同时保留了并发场景下的显式控制。

后续扩展

可以继续扩展的方向包括：

• 增加 CLI trace 查看命令。
• 增加 HTML / TUI trace viewer。
• 为 JSON schema 写稳定性文档。
• 增加 OpenTelemetry recorder。
• 对 live provider 运行 trace 做单独验收。

这些都不需要改变当前 TraceSpan、TraceTree 和 recorder 的基本边界。

总结

• Tracing 是运行时观测层，应该插在 engine 编排链路旁边，而不是污染 provider、tool 或 message 协议。
• TraceSpan 和 TraceTree 把一次 Agent 运行表达成可回放的 JSON 决策树。
• 默认 metadata 模式保护隐私，replay 模式才保存脱敏和截断后的 payload。
• 主循环、模型调用、工具调用、审批暂停/恢复和 Subagent 都被纳入同一条 trace。
• 并发工具调用需要显式传递 parent span，才能保证 children 归属和输出顺序稳定。

到这里，教程主线已经覆盖基础运行时、工具安全、上下文状态、外部集成、Subagent 和可观测性。按模块回看时，可以回到 教程索引。

来源：本文整理自 tiny-claw/docs/tutorial/29-agent-tracing-json-decision-tree.md。
项目地址：barry166/tiny-claw。

系列导航：系列目录 | 上一篇：从零实现 Harness Agent：OpenAI Subagent 真实链路测试 | 下一篇：从零实现 Harness Agent：Agent Tracing 决策树

本节目标

导读：本篇回到第二部分「工具与安全边界」做并发复盘：read 和 explore 都看似只读，但调度成本和风险完全不同。

本节要总结的是工具并发边界：为什么连续 read 可以并发，而 write、edit、bash 和 explore 默认顺序执行。

完成这一节后，你会理解并发不是性能开关，而是工具语义、安全边界和 Provider 成本共同决定的策略。

摘要

本文要说明 tiny-claw 当前的工具并发边界：同一轮连续 read 可以并发执行，但 write、edit、bash 和 explore 会顺序执行。读者可以了解为什么并发不是简单的性能开关，而是工具语义、安全边界和 Provider 成本共同决定的架构选择。

背景与问题

现代模型可能在一轮响应中返回多个 tool calls。对于代码阅读任务，并发读取多个文件可以明显降低等待时间。但对写文件、编辑文件、执行 shell 命令或启动子智能体来说，并发可能带来副作用冲突、状态竞争或不可控的 token/API 消耗。

因此，工具执行器需要区分“可以并发的工具”和“必须顺序执行的工具”。这个边界应该由工具语义决定，而不是由实现是否线程安全决定。

设计目标

• 安全优先：只并发低风险工具。
• 顺序稳定：并发后的 observation 顺序仍与模型 tool call 顺序一致。
• 副作用隔离：写入、编辑、命令执行和子智能体启动默认顺序执行。
• 成本可控：不让多个 subagent 在没有限流的情况下同时启动模型子循环。
• 可扩展：后续可以引入 subagent 专用并发策略。
• 可测试：并发和 barrier 行为有自动化测试覆盖。

整体方案

当前 ToolExecutor 使用一个并发安全白名单：

1

PARALLEL_SAFE_TOOL_NAMES = {"read"}

扫描 tool calls 时，连续 read 会组成并发组。遇到非 read 工具时，执行器会先跑完已有并发组，再顺序执行当前工具。

1
2
3
4
5
6
7
8
9
10

flowchart TD
  A["模型返回 tool calls"] --> B["扫描调用序列"]
  B --> C{"tool 是否 read?"}
  C -->|是| D["加入 parallel group"]
  C -->|否| E["先执行已有 read group"]
  E --> F["顺序执行当前工具"]
  D --> G{"遇到非 read 或结束?"}
  G -->|是| H["ThreadPoolExecutor 并发执行 read"]
  H --> I["按原始顺序返回 observations"]
  F --> I

示例：

1

read, read, write, read

执行顺序是：

1

parallel(read, read) -> write -> read

核心实现

关键文件：

• src/tiny_claw/_internal/engine/tool_executor.py
• tests/test_tool_executor.py
• src/tiny_claw/_internal/subagent/runner.py
• src/tiny_claw/_internal/tools/builtin/explore.py

并发入口：

1
2

def run_tool_batch(self, tool_calls: tuple[ToolCall, ...], ...) -> ToolRunBatch:
    ...

并发组执行：

1
2
3

max_workers = min(self.max_parallel_tools, len(tool_calls))
with ThreadPoolExecutor(max_workers=max_workers) as executor:
    observations = tuple(executor.map(..., tool_calls))

executor.map() 会按输入顺序返回结果，因此即使内部完成顺序不同，模型下一轮看到的 observation 顺序仍然稳定。

explore 没有加入 PARALLEL_SAFE_TOOL_NAMES。虽然 Explorer Subagent v1 只读，但它会启动一个模型子循环，内部可能继续调用多个 read。它的成本和调度风险与普通文件读取不同，因此当前保持顺序执行。

子智能体内部仍然可以并发执行多个 read，因为 child ToolExecutor 使用同一套并发规则，且子工具 registry 只包含 read。

使用方式

用户不直接配置工具并发策略。只要模型同一轮返回多个连续 read，执行器会自动并发。

启用 read：

1
2

TINY_CLAW_ENABLED_TOOLS=read \
uv run tiny-claw run "请同时阅读 README 和 pyproject 配置，概括项目结构。"

启用 explore：

1
2

TINY_CLAW_ENABLED_TOOLS=read,explore \
uv run tiny-claw run "请探索工具执行器的并发边界。"

注意：多个 explore 调用当前会顺序执行。它们不会像多个 read 那样进入同一个并发组。

测试与验证

连续 read 并发：

1

uv run pytest tests/test_tool_executor.py -k consecutive

并发 observation 顺序稳定：

1

uv run pytest tests/test_tool_executor.py -k preserves_original_order

非 read 工具作为 barrier：

1

uv run pytest tests/test_tool_executor.py -k ordered_barriers

subagent 内部 read 日志标记：

1

uv run pytest tests/test_tool_executor.py -k subagent

完整验证：

1
2
3
4

uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest

设计取舍与注意事项

当前并发策略非常保守：只有 read 可以并发。write、edit、bash 即使在某些场景下可以安全并发，也默认顺序执行，因为它们可能改变文件系统、依赖当前目录状态，或影响后续工具看到的世界。

explore 暂不并发是一个明确取舍。Explorer Subagent 会消耗模型请求和上下文预算，也会创建 child session 和 child memory。让多个 explore 无限制并发，可能导致 provider 并发压力、日志交错、成本不可控和状态审计困难。

如果后续要支持多个 subagent 并发，建议不要直接把 explore 加入普通白名单，而是引入更明确的分类，例如：

1
2

PARALLEL_SAFE_TOOL_NAMES = {"read"}
PARALLEL_SUBAGENT_TOOL_NAMES = {"explore"}  # 待设计

并配套：

• subagent 专用最大并发数。
• provider client 并发安全验证。
• child session 日志和结果顺序测试。
• token/API 成本保护。
• 取消和超时策略。

总结

• 当前工具并发只覆盖连续 read。
• 副作用工具和 explore 都会顺序执行。
• 子智能体内部多个 read 仍可并发。
• observation 顺序稳定是模型正确理解结果的关键。
• subagent 并发需要专门设计限流和 provider 安全策略，不能简单套用普通工具白名单。

按可观测性专题继续阅读：29：Agent Tracing JSON 决策树 会把运行时行为沉淀成可回放的结构化记录。

来源：本文整理自 tiny-claw/docs/tutorial/28-tool-concurrency-boundaries.md。
项目地址：barry166/tiny-claw。

系列导航：系列目录 | 上一篇：从零实现 Harness Agent：Subagent 可观测性设计 | 下一篇：从零实现 Harness Agent：工具并发边界设计

本节目标

导读：本篇连接第五部分和第六部分：用真实 OpenAI-compatible Provider 补充验收 Subagent 的端到端链路。

本节要补充的是真实 OpenAI Provider 下的 Subagent E2E 验收：观察父 Agent 调用 explore、子智能体调用 read、报告回流父循环。

完成这一节后，你会知道 live test 如何补充 fake provider 测试，而不是替代它。

摘要

本文要说明如何用真实 OpenAI Provider 验证 Explorer Subagent 的端到端链路。读者可以学习如何设计一个可打印、可人工审计的 live 测试，验证父 Agent 调用 explore、子智能体调用 read、最终报告回流父循环。

背景与问题

Agent 框架的大部分行为应该用 fake provider 和单元测试锁定，但真实模型工具调用仍然需要补充验收。尤其是 Subagent：它涉及父工具调用、子循环、子工具执行、报告回流和父循环最终回复。只靠 mock 很难证明真实 Provider 下模型会正确使用工具。

live E2E 测试的目标不是替代单元测试，而是提供一条能被人眼审计的真实链路。

设计目标

• 真实 Provider：使用环境中配置的 OpenAI-compatible provider。
• 临时工作区：测试文件放在 tmp_path 下，不污染项目文件。
• 父工具最小化：父 Agent 只暴露 explore，确保必须走 subagent。
• 证据明确：fixture 文件包含 sentinel 字符串。
• 打印友好：使用 pytest -s 打印工作区、工具、日志和 memory。
• 无强断言：测试关注真实输出展示，缺少 key 时跳过。

整体方案

测试创建一个临时工作区，写入两个文件：

• README.md
• notes/architecture.txt

每个文件包含一个 sentinel。父 Agent 的 prompt 明确要求调用 explore，Explorer Subagent 通过 child read 工具读取文件，报告 sentinel，父 Agent 再基于报告输出最终回复。

1
2
3
4
5
6
7
8
9

flowchart TD
  Fixture["临时 fixture 文件<br/>README.md / notes/architecture.txt"] --> ChildRead["child read"]
  Parent["Parent MainLoop<br/>tools=explore"] --> Explore["explore"]
  Explore --> Child["Explorer Subagent"]
  Child --> ChildRead
  ChildRead --> Report["Explorer Subagent Report"]
  Report --> Parent
  Parent --> Final["最终回复包含 sentinel"]
  Parent --> Print["打印 parent/child memory"]

核心实现

关键文件：

• tests/test_subagent_openai_live.py
• src/tiny_claw/_internal/logging_config.py
• src/tiny_claw/_internal/app.py
• src/tiny_claw/_internal/settings.py

测试从环境读取 OpenAI 配置：

1
2
3

env_settings = Settings.from_env()
if not env_settings.openai_api_key:
    pytest.skip(...)

测试专用 settings 只启用 explore：

1
2
3
4
5
6

live_settings = Settings(
    provider_name="openai",
    enabled_tools=("explore",),
    openai_api_key=env_settings.openai_api_key,
    openai_base_url=env_settings.openai_base_url,
)

fixture 使用两个 sentinel：

1
2

SUBAGENT_LIVE_SENTINEL_20260610
READ_ONLY_CHILD_CONTEXT_OK

测试会打印：

• replay command
• workdir
• state dir
• model
• actual tools
• parent session
• fixture 内容
• 父 MainLoop 最终回复
• parent session memory
• child subagent session memory

使用方式

运行 live 测试：

1

uv run pytest -s tests/test_subagent_openai_live.py

需要提前配置：

1

OPENAI_API_KEY=<your-key>

如果使用 OpenAI-compatible endpoint，可配置：

1

OPENAI_BASE_URL=<your-compatible-base-url>

测试中可以观察这些关键输出：

1
2
3
4
5
6

actual_tools=explore
执行工具: explore
Explorer 子智能体启动
[subagent_session=...] 执行工具: read
[Explorer Subagent Report]
父 MainLoop 最终回复

测试与验证

live 测试本身：

1

uv run pytest -s tests/test_subagent_openai_live.py

相关稳定测试：

1
2
3

uv run pytest tests/test_subagent.py
uv run pytest tests/test_app.py::test_application_registers_explicitly_enabled_tools
uv run pytest tests/test_settings.py::test_settings_reads_enabled_tools_from_environment

完整验证：

1
2
3
4

uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest

设计取舍与注意事项

这个测试没有把所有输出都写成严格断言。真实模型回复存在表达差异，过多字符串断言会让测试脆弱。它更像一个 printable E2E：通过固定 fixture 和 sentinel，让维护者直接确认真实链路。

父 Agent 只暴露 explore，不是 read,explore。这样可以证明父 Agent 不能直接读取文件，必须派发 Explorer Subagent。

测试会在缺少 OpenAI key 时跳过。是否把它纳入 CI 需要根据项目运行环境决定；如果 CI 没有稳定 live provider，建议只在本地或专门的 live job 中运行。

不要在文章、日志或测试输出中写入真实密钥。测试可以显示 provider 名称和模型名，但不应该打印 API key。

总结

• Subagent 的真实链路需要 live E2E 补充验证。
• 只暴露 explore 可以证明父循环确实通过子智能体探索。
• sentinel fixture 让人工审计更可靠。
• pytest -s 适合展示模型工具调用和 session memory。
• live 测试是补充验收，不替代稳定的单元测试和 fake provider 测试。

按编号继续阅读：28：工具并发边界 会回到工具调度层，梳理 read 与 explore 的并发差异。

来源：本文整理自 tiny-claw/docs/tutorial/27-openai-subagent-live-test.md。
项目地址：barry166/tiny-claw。

系列导航：系列目录 | 上一篇：从零实现 Harness Agent：Subagent 会话与记忆隔离 | 下一篇：从零实现 Harness Agent：OpenAI Subagent 真实链路测试

本节目标

导读：本篇属于第五部分「Subagent 与可观测性」，让嵌套 Agent 的启动、结束和内部工具调用在日志里有清楚归属。

本节要实现的是 Subagent 的可读日志：让启动、结束、child tool 调用和报告长度都能被维护者定位。

完成这一节后，你会理解嵌套 Agent 的日志为什么必须标记归属。

摘要

本文要说明如何让 Explorer Subagent 的运行过程可观察。读者可以了解 tiny-claw 如何记录子智能体启动、结束、内部工具调用和报告长度，以及如何通过 subagent_session=... 区分父工具和 child tool 日志。

背景与问题

一旦系统支持嵌套 Agent，日志很容易变得混乱。父 Agent 可能调用 explore，而 explore 内部又启动子智能体调用 read。如果日志只显示“执行工具: read”，维护者很难判断这个 read 属于父循环还是子循环。

可观测性必须跟上架构边界：既要看到子智能体生命周期，也要能把内部工具调用和 child session 对齐。

设计目标

• 生命周期清晰：记录 Explorer 启动和结束。
• 工具归属清晰：child 工具日志带 subagent_session=...。
• 父日志不变：普通父工具调用不额外增加噪声。
• 不泄露大任务文本：启动日志只记录 task_chars，不展开完整任务。
• 错误路径一致：工具成功、失败、异常和错误兜底都支持 context。
• 测试可锁定：日志格式有回归测试保护。

整体方案

可观测性分两层：

1. SubagentRunner 负责记录子智能体生命周期。
2. ToolExecutor 根据 SessionRef.source 给子工具日志加上下文标记。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

sequenceDiagram
  participant P as Parent MainLoop
  participant E as explore tool
  participant S as SubagentRunner
  participant T as child ToolExecutor
  participant R as read tool

  P->>E: tool_call explore
  E->>S: run_explorer
  S-->>S: log start child_session
  S->>T: run child tool calls
  T-->>T: log [subagent_session=...]
  T->>R: read file
  R-->>T: tool output
  S-->>S: log finish reason/steps
  S-->>E: Explorer Subagent Report
  E-->>P: tool observation

核心实现

关键文件：

• src/tiny_claw/_internal/subagent/runner.py
• src/tiny_claw/_internal/engine/log_view.py
• src/tiny_claw/_internal/engine/tool_executor.py
• tests/test_log_view.py
• tests/test_tool_executor.py

启动日志包含：

• parent session
• child session
• max steps
• task 字符数
• workdir
• child tools

示例：

1

[Subagent] Explorer 子智能体启动 parent_session=... child_session=... max_steps=6 task_chars=96 workdir=... tools=read

结束日志包含：

• child session
• stop reason
• steps
• provider
• report chars

示例：

1

[Subagent] Explorer 子智能体结束 child_session=... reason=final steps=2/6 provider=openai report_chars=319

工具日志通过 context 参数扩展：

1
2

def log_tool_call(logger, call, *, context: str | None = None) -> None:
    ...

ToolExecutor 根据 session source 生成上下文：

1
2
3
4

def _tool_log_context(session: SessionRef) -> str | None:
    if session.source != "subagent":
        return None
    return f"subagent_session={session.key}"

child 工具日志会显示：

1
2

-> 🛠 [subagent_session=parent-...-explore-...] 执行工具: read
-> ✅ 工具成功 [subagent_session=parent-...-explore-...]: read

使用方式

启用日志和 explore：

1
2
3

TINY_CLAW_LOG_LEVEL=INFO \
TINY_CLAW_ENABLED_TOOLS=read,explore \
uv run tiny-claw run "请探索项目中的工具执行链路"

如果运行真实 live 测试，可以直接观察完整链路：

1

uv run pytest -s tests/test_subagent_openai_live.py

关注这些日志点：

1
2
3
4
5

执行工具: explore
Explorer 子智能体启动
[subagent_session=...] 执行工具: read
Explorer 子智能体结束
工具成功: explore

测试与验证

日志渲染测试：

1

uv run pytest tests/test_log_view.py

工具执行器 subagent 日志标记测试：

1

uv run pytest tests/test_tool_executor.py -k subagent

subagent 生命周期日志测试：

1

uv run pytest tests/test_subagent.py -k logs

完整验证：

1
2
3
4

uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest

设计取舍与注意事项

启动日志记录 task_chars，而不是完整 task 文本。探索任务可能包含较长上下文或敏感片段，日志不应该把上下文隔离收益重新消耗掉。

subagent_session 只在 session.source == "subagent" 时出现。父工具日志保持原样，避免普通工具调用被无关上下文污染。

日志 context 被接入 log_tool_call、log_tool_result、log_tool_error_fallback 和 log_tool_exception。这样成功和失败路径都有一致的可追踪标记。

日志不是安全边界。真正的权限边界仍然由 child tool registry 决定：Explorer Subagent v1 只能看到 read。

总结

• Subagent 日志需要同时覆盖生命周期和内部工具归属。
• subagent_session=... 让 child tool calls 可以从父日志中清楚区分。
• 不打印完整 task，有助于保护日志体积和敏感上下文。
• 日志增强不改变工具执行语义，只提升审计和调试体验。
• 对嵌套 Agent 来说，可观测性是架构边界的一部分。

按 Subagent 专题继续阅读：27：OpenAI Subagent live test 会用真实模型链路补充验收。

来源：本文整理自 tiny-claw/docs/tutorial/26-subagent-observability.md。
项目地址：barry166/tiny-claw。

系列导航：系列目录 | 上一篇：从零实现 Harness Agent：Explore 工具适配器 | 下一篇：从零实现 Harness Agent：Subagent 可观测性设计

本节目标

导读：本篇属于第五部分「Subagent 与可观测性」，继续收紧父子状态边界：child memory 记录探索过程，父循环只接收报告。

本节要实现的是 Subagent 的子会话与记忆隔离：child session 记录探索过程，父 session 只接收最终报告。

完成这一节后，你会理解为什么父循环不能吸收完整子任务消息链。

摘要

本文要说明 Explorer Subagent 如何通过独立 SessionRef 和独立 memory store 隔离子任务状态。读者可以了解 child session 的派生方式、父子 memory 的边界，以及为什么父循环只接收精炼报告而不是完整子任务消息链。

背景与问题

Subagent 的核心价值不是“多调用一次模型”，而是把复杂探索过程隔离出去。如果子智能体读取的文件内容、工具 observation 和中间推理都写回父 session，那么父 Agent 仍然会承受同样的上下文压力。

因此，子智能体需要自己的会话线。父 session 只记录父任务的 prompt 和最终回复；child session 记录探索任务和探索报告。父循环收到的是一条工具 observation，而不是子智能体的完整运行历史。

设计目标

• 父子记忆隔离：子任务 memory 不写入父 session。
• 可追踪：每次子任务都有稳定可打印的 child session key。
• 上下文最小回流：父循环只接收精炼报告。
• 复用现有存储：继续使用 SessionMemoryStore 和文件系统 JSONL。
• 便于测试：可以独立断言父 memory 和 child memory 不串线。
• 为并发扩展留边界：多个 child session 天然拥有不同状态目录。

整体方案

SubagentRunner 接收 parent SessionRef，通过 _child_session(parent) 派生一个新的 SessionRef。这个 child session 使用相同 workdir，但 source 为 subagent，key 中包含父 session key 和随机 child id。

1
2
3
4
5
6
7
8

flowchart TD
  Parent["parent SessionRef"] --> Derive["_child_session(parent)"]
  Derive --> Child["child SessionRef<br/>source=subagent"]
  Child --> ChildMemory["state_dir/sessions/<child-key>/memory.jsonl"]
  Parent --> ParentMemory["state_dir/sessions/<parent-key>/memory.jsonl"]
  ChildMemory --> Report["Explorer Subagent Report"]
  Report --> ParentLoop["父循环 tool observation"]
  ParentLoop --> ParentMemory

核心实现

关键文件：

• src/tiny_claw/_internal/subagent/runner.py
• src/tiny_claw/_internal/session/manager.py
• src/tiny_claw/_internal/memory/file_store.py
• tests/test_subagent.py

child session 派生逻辑：

1
2
3

def _child_session(parent: SessionRef) -> SessionRef:
    child_id = uuid.uuid4().hex[:12]
    key = f"parent-{parent.key}-explore-{child_id}"

child session 的关键字段：

• source="subagent"
• external_id="<parent-key>:explore:<child-id>"
• workdir=parent.workdir
• display_name="explore:<parent-display-name>:<child-id>"

运行时读取和写入 child memory：

1
2

child_memory = self.memory.for_session(child_session)
recent_memory = child_memory.read_recent(limit=3)

子任务结束后只记录子任务的 prompt 和最终报告：

1
2

memory.append("last_prompt", prompt)
memory.append("last_response", response)

父循环不会看到 child 的完整 tool call 链。测试会断言父 observation 中不包含 child tool call id。

使用方式

这个模块是内部状态边界，用户不需要直接创建 child session。启用 explore 后，系统会在每次工具调用时自动派生 child session：

1
2

TINY_CLAW_ENABLED_TOOLS=read,explore \
uv run tiny-claw run --session architecture "请探索工具执行链路"

日志中可以看到 child session：

1

[Subagent] Explorer 子智能体启动 parent_session=... child_session=parent-...-explore-...

最终报告也会包含：

1
2
3

[Explorer Subagent Report]
child_session=parent-...-explore-...
stop_reason=final

测试与验证

父子 memory 隔离测试：

1

uv run pytest tests/test_subagent.py -k memory

父循环只接收精炼 observation：

1

uv run pytest tests/test_subagent.py -k compact

完整 subagent 测试：

1

uv run pytest tests/test_subagent.py

全量验证：

1
2
3
4

uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest

设计取舍与注意事项

child session 使用父 workdir，而不是重新选择工作目录。这是因为工具注册和路径边界都围绕应用 workdir 构建，子智能体应该在同一项目范围内探索。

child memory 当前只记录最近 prompt 和 response，不记录完整工具链。完整工具链仍然存在于运行时日志里，但不会写入父 session memory。这个取舍优先保护父上下文，代价是 child session 的持久审计信息比较精简。

memory 存储仍然使用 JSONL 文件。它足够透明、易测试，也和现有 session 体系一致。当前不是长期知识库，也不是向量记忆系统。

如果后续支持多个 subagent 并发，child session key 已经具备隔离基础，但还需要增加并发限流、provider 安全测试和更强的运行状态记录。

总结

• 子智能体通过独立 SessionRef 隔离探索记忆。
• 父 session 不接收子任务的完整消息链。
• child session key 让日志、报告和状态目录可以互相对齐。
• 文件系统 JSONL 继续作为轻量、透明的 memory 存储。
• 这个边界是后续 subagent 并发和审计能力的基础。

按 Subagent 专题继续阅读：26：Subagent 可观测性 会让嵌套运行过程在日志里可读可查。

来源：本文整理自 tiny-claw/docs/tutorial/25-subagent-session-memory-isolation.md。
项目地址：barry166/tiny-claw。

系列导航：系列目录 | 上一篇：从零实现 Harness Agent：Explorer Subagent 运行时 | 下一篇：从零实现 Harness Agent：Subagent 会话与记忆隔离

本节目标

导读：本篇属于第五部分「Subagent 与可观测性」，说明如何把 Subagent 能力包装成普通工具，让父 MainLoop 保持无感。

本节要实现的是 explore 工具 adapter：把 Explorer Subagent 包装成普通 Tool，让父 MainLoop 不需要理解子智能体内部细节。

完成这一节后，你会理解如何把运行时能力接入工具系统，同时保持主循环简洁。

摘要

本文要说明 tiny-claw 如何把 Explorer Subagent 封装成一个普通工具 explore。读者可以了解如何在不污染 MainLoop 的前提下，把子智能体能力接入现有工具系统，并通过 TINY_CLAW_ENABLED_TOOLS 显式启用。

背景与问题

Subagent 是一种运行时能力，但父 Agent 不应该直接知道子智能体内部如何构造上下文、如何调用 provider、如何执行子工具。如果把这些细节写进 MainLoop，主循环会变得越来越臃肿，工具执行、状态管理和子循环编排也会纠缠在一起。

更好的边界是：把 Explorer Subagent 作为一个工具暴露给模型。父循环看到的只是一次普通 tool call；工具内部负责运行子智能体；最终返回一条普通 tool observation。

设计目标

• 主循环无感：MainLoop 不需要理解 subagent 的内部流程。
• 统一工具协议：explore 和 read、write、edit、bash 一样实现 Tool 接口。
• 显式启用：默认不启用 explore，必须通过配置开启。
• 运行时上下文可传递：工具运行时可以拿到 session、workdir 和 visible tools。
• 无新增依赖：继续使用项目已有架构和标准库能力。
• 可测试：schema、参数校验和父循环 observation 都可以独立测试。

整体方案

ExplorerSubagentTool 是工具系统和子智能体运行器之间的 adapter。应用装配时创建 SubagentRunner，再把它注入 ExplorerSubagentTool。如果 TINY_CLAW_ENABLED_TOOLS 包含 explore，工具注册表就会注册这个工具。

1
2
3
4
5
6
7
8
9

flowchart TD
  Settings["Settings.enabled_tools"] --> App["build_application"]
  App --> Runner["SubagentRunner"]
  Runner --> Tool["ExplorerSubagentTool"]
  Tool --> Registry["ToolRegistry"]
  Registry --> MainLoop["MainLoop"]
  MainLoop --> Provider["Provider tools schema"]
  Provider --> ToolCall["tool_call: explore"]
  ToolCall --> Runner

核心实现

关键文件：

• src/tiny_claw/_internal/tools/builtin/explore.py
• src/tiny_claw/_internal/app.py
• src/tiny_claw/_internal/settings.py
• src/tiny_claw/_internal/tools/base.py
• src/tiny_claw/_internal/tools/registry.py

ExplorerSubagentTool 定义工具名和参数 schema：

1
2
3
4

class ExplorerSubagentTool:
    @property
    def name(self) -> str:
        return "explore"

工具参数只有两个：

• task：必填，探索任务说明。
• max_steps：可选，默认 6，上限 12。

工具执行时要求运行时 session 存在：

1
2

if input.session is None:
    raise ToolError("explore tool requires a runtime session")

这是因为 child session 必须从 parent session 派生。

应用装配层复用同一套 provider、context builder、context compactor 和 memory：

1
2
3
4
5
6

subagent_runner = SubagentRunner(
    provider=resolved_provider,
    context_builder=context_builder,
    context_compactor=context_compactor,
    memory=memory,
)

工具注册只在 runner 存在时提供 explore：

1
2

if subagent_runner is not None:
    available_tools["explore"] = ExplorerSubagentTool(runner=subagent_runner)

为了让工具能拿到 session 和 workdir，ToolInput 扩展了运行时上下文：

1
2
3
4
5
6

class ToolInput:
    arguments: Mapping[str, Any]
    session: SessionRef | None = None
    workdir: Path | None = None
    visible_tool_names: tuple[str, ...] = ()
    metadata: Mapping[str, Any] = field(default_factory=dict)

使用方式

默认情况下，explore 不会启用。需要显式配置：

1
2

TINY_CLAW_ENABLED_TOOLS=read,explore \
uv run tiny-claw run "请探索项目的工具系统入口，并总结关键调用链。"

如果只启用 read，模型看不到 explore：

1

TINY_CLAW_ENABLED_TOOLS=read uv run tiny-claw health

可以通过 health 输出确认当前工具集合：

1

uv run tiny-claw health

内部工具调用示例：

1
2
3
4

{
  "task": "调查 docs/tutorial 中工具系统相关文档的主题边界",
  "max_steps": 6
}

测试与验证

工具 schema 和参数校验：

1

uv run pytest tests/test_subagent.py -k schema

应用装配和配置解析：

1
2

uv run pytest tests/test_app.py::test_application_registers_explicitly_enabled_tools
uv run pytest tests/test_settings.py::test_settings_reads_enabled_tools_from_environment

完整验证：

1
2
3
4

uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest

设计取舍与注意事项

explore 是 opt-in 工具，不默认启用。这延续了 tiny-claw 的工具权限策略：新增工具不会自动扩大模型能力面。

ExplorerSubagentTool 只负责 adapter 工作，不承担子循环细节。真正的子循环逻辑放在 SubagentRunner 中。这个边界让工具层保持薄，后续如果要增加其他 subagent 类型，也可以复用类似 adapter 模式。

工具运行时上下文被加入 ToolInput，但不是每个工具都必须使用它。普通工具仍然可以只读取 arguments。这保证了向后兼容，也让需要 session 的高级工具有扩展空间。

explore 当前不是并发安全工具。父模型同一轮返回多个 explore 调用时，它们会按普通非并发工具顺序执行。

总结

• explore 把子智能体封装为标准 Tool，保持 MainLoop 简洁。
• 工具 schema 清晰，只暴露 task 和 max_steps。
• TINY_CLAW_ENABLED_TOOLS 继续作为全局能力开关。
• ToolInput 支持运行时上下文，为 session-aware 工具打好基础。
• 这个 adapter 模式可以作为后续更多 subagent 工具的模板。

按 Subagent 专题继续阅读：25：Subagent 子会话隔离 会处理父子记忆和状态边界。

来源：本文整理自 tiny-claw/docs/tutorial/24-explore-tool-adapter.md。
项目地址：barry166/tiny-claw。

系列导航：系列目录 | 上一篇：从零实现 Harness Agent：MainLoop 审批恢复重构 | 下一篇：从零实现 Harness Agent：Explore 工具适配器

本节目标

导读：本篇进入第五部分「Subagent 与可观测性」，先解决复杂探索的上下文隔离问题：让 Explorer Subagent 在 child session 中完成阅读。

本节要实现的是同步、只读、上下文隔离的 Explorer Subagent：让复杂探索在 child session 中完成，只把精炼报告回流父循环。

完成这一节后，你会理解 Subagent 解决的是上下文隔离问题，而不是简单多调用一次模型。

摘要

本文要说明如何在 tiny-claw 中实现一个同步、只读、上下文隔离的 Explorer Subagent。它适合需要大量代码阅读、跨文件查找和日志定位的场景，读者可以了解如何把复杂探索过程移出父 Agent 上下文，只让精炼报告回流主循环。

背景与问题

Agent 在处理真实代码库时，经常需要先做一轮“探索”：读取多个文件、追踪调用链、查找配置、理解日志和测试。这个阶段通常会产生大量工具调用和 observation。如果这些内容全部留在父 MainLoop 的消息链里，后续执行阶段会承担很大的上下文压力。

Explorer Subagent 解决的是这个边界问题：父 Agent 只描述探索任务，子智能体在独立上下文里读取证据，最后返回一段极度精炼的报告。父循环不需要吸收完整探索轨迹，也不会继承子智能体的工具消息链。

设计目标

• 上下文隔离：子智能体拥有独立消息链，父循环只接收最终报告。
• 只读安全：v1 只允许 read 工具，避免探索阶段产生写入副作用。
• 同步简单：父工具调用等待子智能体完成，不引入后台任务调度。
• 固定边界：max_steps 和报告长度由代码常量限制，不新增运行时环境变量。
• 失败诚实：达到步数上限时明确报告“未找到确切答案”和已查线索。
• 复用架构：复用现有 Provider、ContextBuilder、ContextCompactor 和 SessionMemoryStore。

整体方案

Explorer Subagent 被实现为一个内部 runner。父工具 explore 调用 runner，runner 派生 child session，构造只读工具 registry，然后用同一个 provider 运行一个独立 ReAct 子循环。

1
2
3
4
5
6
7
8
9
10

flowchart TD
  Parent["MainLoop"] --> ExploreTool["explore tool"]
  ExploreTool --> Runner["SubagentRunner.run_explorer"]
  Runner --> ChildSession["child SessionRef"]
  Runner --> ChildContext["独立 context messages"]
  Runner --> ReadOnlyTools["只读 ToolRegistry: read"]
  ChildContext --> Provider["LLM Provider"]
  Provider --> ReadCalls["child read tool calls"]
  ReadCalls --> Report["Explorer Subagent Report"]
  Report --> ParentObservation["父循环的一条 tool observation"]

核心实现

核心文件是 src/tiny_claw/_internal/subagent/runner.py。

关键常量：

1
2
3

SUBAGENT_DEFAULT_MAX_STEPS = 6
SUBAGENT_MAX_STEPS_LIMIT = 12
SUBAGENT_RESULT_MAX_CHARS = 4_000

这些限制是代码内固定策略，不通过环境变量暴露。这样可以避免运行时配置面膨胀，也能保护父循环上下文。

SubagentRunner.run_explorer() 的主要流程是：

1. 校验并裁剪任务文本。
2. 从父 session 派生 child session。
3. 读取 child session 最近记忆。
4. 构造 Explorer 专用系统提示词和任务提示。
5. 创建只包含 ReadTool 的工具 registry。
6. 在子循环中调用 provider。
7. 如果模型继续请求工具，就执行 child tool calls。
8. 如果模型返回最终文本，就包装成 [Explorer Subagent Report]。
9. 如果达到步数上限，就返回明确的未找到报告。

只读工具 registry 的关键实现很小：

1
2
3
4

def _build_read_only_tools(session: SessionRef) -> ToolRegistry:
    registry = ToolRegistry()
    registry.register(ReadTool(root=session.workdir))
    return registry

结果会统一包装：

1
2
3
4
5

[Explorer Subagent Report]
child_session=<child-session-key>
stop_reason=<final | max_steps_exhausted>

<精炼报告正文>

使用方式

Explorer Subagent 不直接作为 CLI 子命令暴露，而是通过 explore 工具被父 Agent 调用。

启用方式：

1
2

TINY_CLAW_ENABLED_TOOLS=read,explore \
uv run tiny-claw run "请探索项目中的工具注册流程，并总结关键文件。"

explore 工具参数：

1
2
3
4

{
  "task": "调查 src/tiny_claw/_internal/tools 的注册与执行链路",
  "max_steps": 6
}

推荐使用场景：

• 大量代码阅读。
• 跨文件查找逻辑。
• 日志定位。
• 需要先收集证据再让父 Agent 做决策的任务。

不推荐使用场景：

• 需要修改文件的任务。
• 需要执行 shell 命令的任务。
• 需要后台异步长时间运行的任务。

这些能力不属于 v1 的 Explorer Subagent。

测试与验证

核心测试：

1

uv run pytest tests/test_subagent.py

完整验证：

1
2
3
4

uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest

真实 Provider 验证可以运行：

1

uv run pytest -s tests/test_subagent_openai_live.py

这个 live 测试会创建临时工作区，让父 Agent 只看到 explore，再观察子智能体是否通过 read 工具读取 fixture 文件并返回报告。

设计取舍与注意事项

v1 选择同步执行，而不是后台异步执行。这样父循环不需要处理任务轮询、取消、超时恢复和 partial result，整体语义更清晰：explore 是一次普通工具调用，返回一条普通 observation。

v1 选择只读工具，而不是继承父工具集。即使父 Agent 启用了 write、edit 或 bash，子智能体也只能看到 read。这是为了让“探索”保持低风险，避免子任务在上下文隔离的同时产生不可见副作用。

结果长度使用固定截断策略，而不是新增 TINY_CLAW_SUBAGENT_MAX_RESULT_CHARS。这让配置表面更小，也更符合 v1 的保守定位。

当前实现不支持多个 explore 并发。后续如果要做 subagent 并发，应增加专门的 subagent 并发池、限流和 provider 并发安全测试，而不是简单把 explore 加入普通工具并发白名单。

总结

• Explorer Subagent 把复杂探索过程从父 Agent 上下文中隔离出去。
• v1 同步、只读、单层，优先保证行为清晰和风险可控。
• 子智能体复用现有 Provider、上下文构建和压缩机制。
• 父循环只收到 [Explorer Subagent Report]，不会吸收完整子任务消息链。
• 后续扩展并发和更多工具能力时，应继续保持清晰的权限边界。

按 Subagent 专题继续阅读：24：explore 工具 adapter 会把子智能体能力接入普通工具系统。

来源：本文整理自 tiny-claw/docs/tutorial/23-explorer-subagent-runtime.md。
项目地址：barry166/tiny-claw。

系列导航：系列目录 | 上一篇：从零实现 Harness Agent：审批流程测试与验证 | 下一篇：从零实现 Harness Agent：Explorer Subagent 运行时

本节目标

导读：本篇属于第四部分「外部集成与审批恢复」的维护者篇：审批恢复进入主循环后，需要拆出职责边界，避免 MainLoop 重新变成黑盒。

本节要完成的是审批恢复后的主循环职责整理：在行为不变的前提下，把运行类型、工具策略、observation 处理和恢复 runner 拆出稳定边界。

完成这一节后，你会理解如何避免 MainLoop 在支持恢复后变成新的黑盒。

摘要

本文要说明 tiny-claw 如何在引入审批恢复后，拆分过长的 MainLoop，把运行类型、工具策略、observation 处理和审批恢复抽成更清晰的模块。这个模块适合后续维护者、Agent 主循环开发者和关注工程化重构的读者。读完后，你会理解这次重构保留了哪些主循环职责、抽出了哪些稳定接口，以及如何在不改变行为的前提下降低主循环复杂度。

背景与问题

MainLoop 是 Agent 框架最容易变长的文件。它天然要处理：

• provider 请求和响应。
• ReAct 多轮循环。
• 工具定义可见性。
• tool observation 追加。
• plan / think / plan-act 模式。
• 上下文压缩。
• 运行结果和记忆记录。
• 审批暂停和恢复。

引入高危工具审批后，MainLoop 又需要处理 checkpoint、approval resume、approved/rejected 分支。如果继续把所有逻辑放在一个文件里，维护成本会快速上升：任何人改审批恢复都必须读完整主循环，改普通 ReAct 流程也容易碰到审批细节。

因此，需要做一次以职责为边界的轻量拆分。

设计目标

• 行为不变：重构不改变已有 run、plan、tool、Feishu 行为。
• 局部复杂度下降：审批恢复从主循环中抽出。
• 类型集中：运行模式、停止原因、结果类型集中定义。
• 策略集中：phase 和 tool policy 规则独立测试和复用。
• observation 规则复用：普通 run 和 resumed run 使用同一套追加逻辑。
• 兼容导入：main_loop.py 继续 re-export 关键类型，减少外部变更面。

整体方案

拆分后的结构：

1
2
3
4
5
6
7
8
9
10

flowchart TD
  Main["main_loop.py<br/>普通 run 编排"] --> Types["run_types.py<br/>RunMode / RunResult / stop reasons"]
  Main --> Policy["run_policy.py<br/>phase/tool policy"]
  Main --> Obs["observations.py<br/>tool observation 追加规则"]
  Main --> Resume["approval_resume.py<br/>审批恢复 runner"]
  Resume --> Types
  Resume --> Policy
  Resume --> Obs
  Resume --> Tools["ToolExecutor"]
  Resume --> Provider["LLMProvider"]

MainLoop 仍然是核心编排者，但不再直接承载审批恢复的完整循环。恢复逻辑由 ApprovalResumeRunner 接管。

核心实现

关键文件：

• src/tiny_claw/_internal/engine/main_loop.py
• src/tiny_claw/_internal/engine/approval_resume.py
• src/tiny_claw/_internal/engine/observations.py
• src/tiny_claw/_internal/engine/run_policy.py
• src/tiny_claw/_internal/engine/run_types.py
• tests/test_engine.py

run_types.py 集中定义运行结果和停止原因：

1
2
3
4
5
6
7
8

STOP_REASON_APPROVAL_REQUIRED = "approval_required"
STOP_REASON_APPROVAL_RESUME_FAILED = "approval_resume_failed"

class RunMode(StrEnum):
    ACT = "act"
    PLAN = "plan"
    THINK = "think"
    PLAN_ACT = "plan-act"

RunResult 新增审批字段：

1
2
3
4
5

@dataclass(frozen=True)
class RunResult:
    ...
    approval_id: str | None = None
    checkpoint_id: str | None = None

run_policy.py 抽出 phase 和 tool choice 规则：

1
2
3
4
5

def phase_for_step(*, mode: RunMode, step: int, plan_required: bool = False) -> str:
    ...

def tool_policy_for_phase(phase: str) -> ToolPolicy:
    ...

observations.py 抽出普通 run 和 resumed run 都会用到的 observation 规则：

1
2
3
4
5
6

def append_tool_observations(
    messages: list[Message],
    observations: tuple[Message, ...],
) -> bool:
    messages.extend(observations)
    ...

审批恢复由 ApprovalResumeRunner 承担：

1
2
3
4
5
6
7
8

@dataclass(frozen=True)
class ApprovalResumeRunner:
    provider: LLMProvider
    context_compactor: ContextCompactor
    memory: SessionMemoryStore
    tools: ToolRegistry
    checkpoint_store: FileRunCheckpointStore | None
    ...

MainLoop 保留很薄的转发方法：

1
2
3
4
5

def resume_approved_approval(...):
    return self._approval_resume_runner().resume_approved(...)

def resume_rejected_approval(...):
    return self._approval_resume_runner().resume_rejected(...)

为了兼容已有导入，main_loop.py 仍然通过 __all__ 暴露：

• RunMode
• RunResult
• ToolPolicy
• stop reason 常量
• MainLoop

使用方式

这个模块主要面向内部维护者，外部 CLI 用法不变：

1
2
3
4

uv run tiny-claw run "hello tiny claw"
uv run tiny-claw run --mode plan "生成计划"
uv run tiny-claw run --mode plan-act --session demo "继续执行"
uv run tiny-claw serve --host 0.0.0.0 --port 8000

代码中仍可从 main_loop 导入常用类型：

1

from tiny_claw._internal.engine.main_loop import MainLoop, RunMode, RunResult

新增内部模块的推荐使用边界：

• 新增停止原因或 RunResult 字段：改 run_types.py。
• 调整 plan / act phase 规则：改 run_policy.py。
• 调整 tool observation 追加规则：改 observations.py。
• 调整审批恢复执行：改 approval_resume.py。
• 调整普通主循环编排：改 main_loop.py。

测试与验证

主循环和审批恢复行为由 engine 测试覆盖：

1

uv run pytest tests/test_engine.py

涉及 CLI 行为时，运行冒烟：

1
2
3
4
5
6

uv run tiny-claw --help
uv run tiny-claw serve --help
TINY_CLAW_PROVIDER=echo TINY_CLAW_STATE_DIR=.tmp-state uv run tiny-claw health
TINY_CLAW_PROVIDER=echo TINY_CLAW_STATE_DIR=.tmp-state uv run tiny-claw run "hello tiny claw"
uv run python -m tiny_claw --help
rm -rf .tmp-state

完整验证：

1
2
3
4

uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest

这次实现阶段已用完整验证命令跑通过；发布具体版本文档时，应以对应版本仓库的实际验证结果为准。

设计取舍与注意事项

这次重构没有追求把 MainLoop 拆到极致。普通 run 编排仍留在 main_loop.py，因为它是主循环的核心职责；真正被抽出去的是可独立理解、可复用的稳定模块。

ApprovalResumeRunner 接收 return_result 和 record_and_return_result 回调，而不是复制 MainLoop 的结果记录逻辑。这有点工程味，但能避免两个地方分别维护 RunResult 构造和 channel done 通知。

observations.py 看起来很小，但它不是无意义抽函数。普通运行和恢复运行都需要追加 tool observations、处理重复失败警告、判断当前 step 是否出现工具错误。把这部分集中后，后续修改 observation 规则不会漏掉恢复路径。

后续如果继续扩展审批恢复，要警惕把 ApprovalResumeRunner 变成第二个 MainLoop。它应该只负责“从 checkpoint 继续”，而不是重新定义一套主循环规则。

总结

• 审批恢复让 MainLoop 复杂度上升，必须按职责拆分。
• run_types.py 集中运行类型和停止原因。
• run_policy.py 集中 phase 和 tool policy 规则。
• observations.py 复用普通 run 和 resumed run 的 observation 处理。
• approval_resume.py 承担 approved/rejected 后的恢复流程，同时避免复制主循环全部职责。

按编号继续阅读：23：Explorer Subagent runtime 会进入 Subagent 体系，把复杂代码探索从父 Agent 上下文中隔离出去。

来源：本文整理自 tiny-claw/docs/tutorial/22-mainloop-审批恢复重构.md。
项目地址：barry166/tiny-claw。

系列导航：系列目录 | 上一篇：从零实现 Harness Agent：飞书审批 Adapter 设计 | 下一篇：从零实现 Harness Agent：MainLoop 审批恢复重构

本节目标

导读：本篇连接第四部分和第六部分：审批链路横跨模型、middleware、checkpoint、平台命令和真实副作用，必须分层验证。

本节要建立的是高危工具审批流程的验证方法：区分模型拒绝、middleware 拦截、checkpoint 持久化和审批后恢复。

完成这一节后，你会知道如何用自动化测试和真实 Feishu 场景分别验收审批链路。

摘要

本文要给出 tiny-claw 高危工具审批流程的自动化和真实场景测试方法。这个模块适合项目使用者、测试工程师、外部集成维护者和需要验收审批链路的开发者。读完后，你会知道为什么不能只用 rm -rf 测 middleware，如何用安全写文件场景触发审批，以及应该观察哪些日志、状态文件和最终副作用。

背景与问题

审批功能横跨多个层次：

• 模型是否生成 tool call。
• 工具调用是否进入 middleware 链。
• 风险策略是否命中。
• approval / checkpoint 是否持久化。
• Feishu 是否收到审批消息。
• approve / reject 后是否正确恢复。
• 真实工具是否只在审批通过后执行。

测试这条链路时，一个常见误区是直接让模型执行明显危险命令，例如 rm -rf。很多模型会在生成 tool call 前自行拒绝。这种情况下日志会显示 tool_calls=0，middleware 没有机会运行。它只能证明模型拒绝了请求，不能证明运行时审批链路有效。

因此，测试需要区分“模型安全拒绝”和“运行时 middleware 拦截”。

设计目标

• 可复现：自动化测试不依赖真实模型随机输出。
• 真实可验：提供安全的端到端手动场景。
• 不破坏工作区：测试高危规则但不真的删除或发布。
• 覆盖双路径：审批通过和审批拒绝都要验证。
• 看得见状态：检查 approval、checkpoint、stop reason 和文件副作用。
• 解释日志：能判断为什么 middleware 没运行。

整体方案

测试分成三层：

1
2
3
4

flowchart TD
  Unit["单元测试<br/>policy / middleware / settings"] --> Engine["Engine 测试<br/>FakeProvider + fake tool"]
  Engine --> Integration["Feishu adapter 测试<br/>fake sender / fake sdk"]
  Integration --> Manual["真实手动场景<br/>Feishu + safe high-risk write"]

自动化测试用 fake provider 锁住行为，真实手动测试用一个安全但会命中风险规则的文件写入请求。

推荐真实测试场景：

1

请调用 write 工具创建文件 approval-demo-key.txt，内容为 approval demo，mode 使用 overwrite。不要只回复文字，请实际调用工具。

这个场景相对安全，因为它只是创建一个演示文件；同时文件名包含 key，会命中文件修改风险规则。

核心实现

关键测试文件：

• tests/test_tools.py
• tests/test_settings.py
• tests/test_engine.py
• tests/test_feishu_integration.py
• tests/test_tool_executor.py

运行时拦截成功时，MainLoop 返回：

1
2
3

stop_reason="approval_required"
approval_id="..."
checkpoint_id="..."

ToolExecutor 生成的 observation metadata 会包含：

1
2
3
4
5
6

{
    "suspended": True,
    "error_type": "tool_approval_required",
    "approval_id": "...",
    "checkpoint_id": "...",
}

审批状态文件写入：

1
2

state_dir/sessions/<session-key>/approvals/<approval-id>.json
state_dir/sessions/<session-key>/checkpoints/<checkpoint-id>.json

通过后恢复时，ApprovalResumeRunner 执行 checkpoint 中的 pending tool call，并把结果作为 tool observation 交回 provider。

拒绝后恢复时，系统不执行工具，而是注入：

1

人工审批已拒绝，工具未执行。

使用方式

自动化验证

先跑和审批直接相关的测试：

1
2
3
4

uv run pytest tests/test_settings.py
uv run pytest tests/test_tools.py
uv run pytest tests/test_engine.py
uv run pytest tests/test_feishu_integration.py

再跑完整回归：

1
2
3
4

uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest

真实 Feishu 测试

启动服务：

1
2
3
4
5
6
7

TINY_CLAW_APPROVAL_PROVIDER=feishu \
TINY_CLAW_ENABLED_TOOLS=read,write,edit,bash \
TINY_CLAW_APPROVAL_REQUIRED_TOOLS=bash,write,edit \
FEISHU_APP_ID=cli_xxx \
FEISHU_APP_SECRET=xxx \
OPENAI_API_KEY=<your-openai-api-key> \
uv run tiny-claw serve --host 0.0.0.0 --port 8000

在 Feishu 发送：

1

请调用 write 工具创建文件 approval-demo-key.txt，内容为 approval demo，mode 使用 overwrite。不要只回复文字，请实际调用工具。

期望现象：

• 日志中出现 tool_calls=1。
• 运行停止原因为 approval_required。
• Feishu 收到包含 approval_id 的审批消息。
• 文件 approval-demo-key.txt 尚未创建。

批准：

1

/approve <approval-id>

期望现象：

• 系统回复“已批准审批”及恢复后的模型结果。
• 文件 approval-demo-key.txt 被创建。
• approval 状态变为 consumed。

拒绝路径可以换一个文件名重新触发审批：

1

请调用 write 工具创建文件 approval-demo-secret.txt，内容为 rejected demo，mode 使用 overwrite。不要只回复文字，请实际调用工具。

然后回复：

1

/reject <approval-id> 测试拒绝

期望现象：

• 文件没有创建。
• 模型收到 rejected observation 后继续回应。

测试与验证

检查状态文件：

1
2

find "$TINY_CLAW_STATE_DIR/sessions" -path '*/approvals/*.json' -print
find "$TINY_CLAW_STATE_DIR/sessions" -path '*/checkpoints/*.json' -print

检查是否创建了演示文件：

1
2

test -f approval-demo-key.txt && cat approval-demo-key.txt
test ! -f approval-demo-secret.txt

清理演示文件：

1

rm -f approval-demo-key.txt approval-demo-secret.txt

如果日志显示：

1

tool_calls=0

并且模型直接回复“不能执行这种危险操作”，说明请求没有进入工具执行链。这时应改用安全但命中风险规则的场景，例如写入包含 key 或 secret 的演示文件，而不是继续加大破坏性命令。

设计取舍与注意事项

审批链路测试不要依赖破坏性命令。系统要验证的是“运行时拦截”，不是诱导模型执行危险操作。安全写文件场景更适合作为真实验收，因为它能触发风险规则，同时副作用可控。

自动化测试用 FakeProvider 是必要的。真实模型是否生成 tool call 会受模型策略、提示词和 provider 行为影响，不适合做稳定断言。

Feishu 手动测试要确保 TINY_CLAW_ENABLED_TOOLS 包含目标工具。如果 write 没有启用，模型看不到工具定义，也不会触发审批 middleware。

如果设置了 TINY_CLAW_TOOL_DENYLIST=write，请求会先被运行时策略拒绝，不会进入审批流程。测试审批时应避免把目标工具放入 denylist。

总结

• tool_calls=0 表示 middleware 没运行，通常是模型提前拒绝或工具未暴露。
• 安全的高风险写文件请求更适合真实审批验收。
• 审批通过前不应产生真实文件副作用。
• approve 后执行原始工具调用，reject 后注入拒绝 observation。
• 自动化测试负责稳定覆盖，Feishu 手动测试负责端到端信心。

按审批专题继续阅读：22：MainLoop 审批恢复重构 会整理审批恢复进入主循环后的职责边界。

来源：本文整理自 tiny-claw/docs/tutorial/21-审批流程测试与验证.md。
项目地址：barry166/tiny-claw。

系列导航：系列目录 | 上一篇：从零实现 Harness Agent：审批 Checkpoint 暂停与恢复 | 下一篇：从零实现 Harness Agent：审批流程测试与验证

本节目标

导读：本篇属于第四部分「外部集成与审批恢复」，说明 Feishu 在审批体系中是平台 adapter，而不是模型可见工具。

本节要实现的是 Feishu 审批 adapter：把审批通知和 /approve / /reject 命令接入通用审批流程，同时保持工具系统不依赖平台 SDK。

完成这一节后，你会理解为什么飞书是外部 adapter，而不是模型可见工具。

摘要

本文要说明 tiny-claw 如何把 Feishu 接入人工审批流程，同时保持工具系统和外部平台解耦。这个模块适合外部集成维护者、Agent 平台开发者和需要在聊天工具中审批高危操作的读者。读完后，你会理解 FeishuChannel.request_approval(...)、/approve、/reject 的职责边界，以及为什么飞书不应该注册成模型可见工具。

背景与问题

当高危工具调用需要人工审批时，一个直觉方案是“做一个飞书审批工具”。这个方案看似直接，但会把边界搞乱：

• 模型会看到平台审批工具，可能主动调用它。
• 工具系统会依赖 Feishu SDK。
• 将来接 Slack、Web UI 或 CLI 审批时，需要改工具链。
• 审批回复属于外部事件，不属于模型发起的 tool call。

更清晰的设计是：审批逻辑属于通用 HumanApprovalMiddleware，Feishu 只做两件事：

1. 收到审批请求时，把消息发到对应聊天。
2. 收到 /approve 或 /reject 命令时，调用应用恢复接口。

也就是说，Feishu 是 adapter，不是 tool。

设计目标

• 平台解耦：审批 middleware 不依赖 Feishu。
• 不暴露给模型：Feishu 审批不是模型可见工具。
• 复用会话隔离：按 Feishu chat_id 恢复对应 session。
• 命令简单：v1 使用文本命令，不依赖互动卡片。
• 异步友好：Feishu 事件处理不阻塞主事件循环。
• 可测试：用 fake sender / fake sdk channel 验证消息和路由。

整体方案

Feishu 审批由两条路径组成：

1
2
3
4
5
6
7
8
9

flowchart TD
  Middleware["HumanApprovalMiddleware"] --> Requester["ApprovalRequester"]
  Requester --> Channel["FeishuChannel.request_approval"]
  Channel --> Feishu["Feishu message"]

  FeishuCommand["/approve 或 /reject"] --> Adapter["FeishuEventAdapter"]
  Adapter --> Parser["parse_approval_command"]
  Parser --> App["Application.resume_approval"]
  App --> Runner["ApprovalResumeRunner"]

发送审批消息时，MainLoop 将当前 channel 放入 tool context metadata：

1
2
3
4

context_metadata={
    CHECKPOINT_DRAFT_METADATA_KEY: draft,
    "approval_requester": resolved_channel,
}

如果当前 channel 是 FeishuChannel，它就满足 ApprovalRequester 协议，可以发送审批消息。

收到审批命令时，Feishu event adapter 不进入普通 Application.run()，而是直接走 Application.resume_approval(...)。

核心实现

关键文件：

• src/tiny_claw/_internal/integrations/feishu/bot.py
• src/tiny_claw/_internal/integrations/feishu/events.py
• src/tiny_claw/_internal/app.py
• src/tiny_claw/_internal/approval.py
• tests/test_feishu_integration.py

FeishuChannel 既是运行进度 channel，也是审批 requester：

1
2
3
4
5
6

@dataclass(frozen=True)
class FeishuChannel(Channel):
    sender: FeishuMessageSender | None = None

    def request_approval(self, request: ApprovalRequest) -> ApprovalDispatchResult:
        ...

审批消息包含：

• approval_id
• session 显示名
• workdir
• tool 名称
• 风险原因
• 过期时间
• /approve 和 /reject 命令示例

命令解析由正则完成：

1
2
3
4

APPROVAL_COMMAND_PATTERN = re.compile(
    r"^/(?P<command>approve|reject)\s+(?P<approval_id>[A-Za-z0-9_-]+)(?:\s+(?P<reason>.*))?$",
    re.I,
)

FeishuEventAdapter._on_message(...) 会先判断是否是审批命令：

1
2
3
4
5
6
7
8
9
10
11

approval_command = parse_approval_command(text)
if approval_command is not None:
    asyncio.create_task(
        asyncio.to_thread(
            self._resume_approval_command,
            command=approval_command,
            session=session,
            channel=channel,
        )
    )
    return

不是审批命令时，才进入普通 Agent 运行：

1
2
3
4
5
6
7

self.app.run(
    prompt=text,
    max_steps=self.max_steps,
    mode=self.mode,
    session=session,
    channel=channel,
)

恢复结果会回复到原消息：

1

channel._send("\n".join(lines), reply=True)

使用方式

启动 Feishu 事件服务并启用审批：

1
2
3
4
5
6

TINY_CLAW_APPROVAL_PROVIDER=feishu \
TINY_CLAW_ENABLED_TOOLS=read,write,edit,bash \
FEISHU_APP_ID=cli_xxx \
FEISHU_APP_SECRET=xxx \
OPENAI_API_KEY=<your-openai-api-key> \
uv run tiny-claw serve --host 0.0.0.0 --port 8000

默认回调路径：

1

POST /api/events/feishu

自定义路径：

1

uv run tiny-claw serve --feishu-path /api/events/feishu-test

高危工具调用被拦截后，Feishu 会收到类似命令提示：

1
2

批准：/approve <approval-id>
拒绝：/reject <approval-id> 原因

审批通过：

1

/approve abc123

审批拒绝：

1

/reject abc123 这个文件不应该由 Agent 修改

测试与验证

Feishu 审批 adapter 测试：

1

uv run pytest tests/test_feishu_integration.py

重点覆盖：

• FeishuChannel.request_approval(...) 会发送审批消息。
• parse_approval_command(...) 能解析 approve / reject。
• 审批命令会路由到 Application.resume_approval(...)。
• 普通消息仍然进入 Application.run(...)。

Server help 和 HTTP 冒烟：

1
2
3

uv run tiny-claw serve --help
uv run tiny-claw serve --host 127.0.0.1 --port 8000
curl http://127.0.0.1:8000/health

完整验证：

1
2
3
4

uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest

设计取舍与注意事项

飞书审批 v1 使用文本命令，不使用互动卡片按钮。文本命令更容易测试，也不需要额外处理按钮回调协议。互动卡片可以作为后续 adapter 增强，但不应该改变 HumanApprovalMiddleware 的接口。

TINY_CLAW_APPROVAL_PROVIDER=feishu 的语义不是“把飞书注册为工具”，而是启用通用审批 middleware，并让 Feishu channel 在对应入口中承担审批通知能力。如果从 CLI 运行并设置了 feishu，但没有 Feishu channel，审批请求仍会持久化；通知投递能力取决于当前运行入口是否提供了 requester。

审批命令按当前 Feishu chat 解析 session。跨 chat 使用 approval id 会被 Application.resume_approval(...) 拒绝，因为 approval 记录绑定了 session key。

当前没有实现审批人白名单、管理员权限校验和互动卡片签名确认。真实生产环境如果需要更强的组织级审批控制，应在 Feishu adapter 或应用恢复入口增加身份校验。

总结

• Feishu 是审批 adapter，不是模型可见工具。
• 审批消息发送通过 FeishuChannel.request_approval(...) 完成。
• /approve 和 /reject 命令走 Application.resume_approval(...)。
• 普通 Feishu 文本消息仍复用 Application.run(...)。
• 平台能力被隔离在 integration 层，审批核心保持通用。

按审批专题继续阅读：21：审批流程测试与验证 会把这条跨模块链路变成可证明的行为。

来源：本文整理自 tiny-claw/docs/tutorial/20-飞书审批-adapter.md。
项目地址：barry166/tiny-claw。

系列导航：系列目录 | 上一篇：从零实现 Harness Agent：高危工具调用人工审批 | 下一篇：从零实现 Harness Agent：飞书审批 Adapter 设计

本节目标

导读：本篇进入第四部分「外部集成与审批恢复」的核心：审批不能阻塞等待，必须用 checkpoint 保存可恢复的运行现场。

本节要实现的是审批后的 checkpoint 暂停与恢复：把原始 messages、pending tool call 和运行参数持久化，让人工决策后可以安全继续。

完成这一节后，你会理解为什么审批不能阻塞等待，以及恢复路径如何做到 fail closed。

摘要

本文要说明 tiny-claw 如何在高危工具调用被拦截后，使用持久化 approval 和 checkpoint 恢复原始运行。这个模块适合 Agent 主循环开发者、状态管理维护者和需要实现人工审批恢复机制的读者。读完后，你会理解为什么不能阻塞进程等待审批、checkpoint 保存了哪些信息，以及恢复时如何做到 fail closed。

背景与问题

高危工具审批的难点不在于“发一条审批消息”，而在于审批之后系统还能安全、准确地继续执行。

直接挂起进程等待人工确认有几个问题：

• HTTP 请求或 Feishu 事件处理不能长时间占住线程。
• 进程重启后审批状态会丢失。
• 多个用户、多个 chat、多个 session 的审批容易混淆。
• 人工通过后必须执行原始 tool call，而不是重新让模型生成一个可能变化的调用。

因此，审批流程需要“暂停 + 持久化 + 恢复”，而不是同步阻塞等待。

设计目标

• 非阻塞：高危调用立即暂停当前 run，不占住请求线程。
• 可恢复：恢复时能够拿回原始 messages、pending tool call 和运行参数。
• 原始调用冻结：审批通过后执行被审批的原始 tool call。
• 会话隔离：approval 和 checkpoint 都绑定 session key。
• 失败关闭：跨 session、过期、重复审批、hash 不匹配都拒绝执行。
• 继续对话：拒绝审批也要作为 tool observation 返回给模型，让模型给出后续回应。

整体方案

审批暂停恢复流程如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

sequenceDiagram
  participant Loop as MainLoop
  participant Middleware as HumanApprovalMiddleware
  participant Store as File stores
  participant User as Human
  participant App as Application
  participant Resume as ApprovalResumeRunner
  participant Tool as Tool
  participant Provider as Provider

  Loop->>Middleware: tool call + RunCheckpointDraft
  Middleware->>Store: write checkpoint
  Middleware->>Store: write approval
  Middleware-->>Loop: suspended
  Loop-->>User: approval_required
  User->>App: approve/reject approval_id
  App->>Store: validate approval
  App->>Resume: resume approved/rejected
  Resume->>Store: read checkpoint
  Resume->>Tool: execute original pending tool call
  Resume->>Provider: continue with tool observation

状态目录形态：

1
2
3
4
5
6
7

state_dir/
  sessions/
    <session-key>/
      approvals/
        <approval-id>.json
      checkpoints/
        <checkpoint-id>.json

核心实现

关键文件：

• src/tiny_claw/_internal/approval.py
• src/tiny_claw/_internal/engine/approval_resume.py
• src/tiny_claw/_internal/engine/main_loop.py
• src/tiny_claw/_internal/app.py
• tests/test_engine.py

approval 记录由 ApprovalRecord 表示，包含：

• id
• session_key
• session_source
• session_external_id
• tool_call_id
• tool_name
• arguments
• tool_call_hash
• risk_reasons
• checkpoint_id
• status
• created_at
• expires_at

checkpoint 由 RunCheckpoint 表示，包含恢复主循环需要的上下文：

• 运行模式、prompt、step、max_steps、phase、tool_policy、provider
• 当前 plan-act TODO 状态
• 可见工具名
• 已有 messages
• pending tool calls
• pending index

暂停前，MainLoop 创建 RunCheckpointDraft，并通过 context_metadata 交给工具执行器：

1
2
3
4

context_metadata={
    CHECKPOINT_DRAFT_METADATA_KEY: draft,
    "approval_requester": resolved_channel,
}

HumanApprovalMiddleware 将 draft 落成真实 checkpoint，再创建 approval。

恢复入口在应用层：

1
2
3
4
5

app.resume_approval(
    approval_id=...,
    decision="approve",
    session=session,
)

应用层先校验：

• approval 是否存在。
• approval 是否属于当前 session。
• approval 是否仍是 pending。
• approval 是否过期。

通过后再进入 MainLoop.resume_approved_approval(...) 或 MainLoop.resume_rejected_approval(...)。

审批通过时，ApprovalResumeRunner 读取 checkpoint，并执行原始 pending tool call：

1
2
3
4
5
6

batch = tool_executor.run_tool_batch(
    (pending_call,),
    session=session,
    workdir=session.workdir,
    context_metadata={APPROVAL_METADATA_KEY: approval.id},
)

这里的 APPROVAL_METADATA_KEY 会让 HumanApprovalMiddleware 进入已审批执行路径。它还会校验 tool call hash，确保恢复时参数没有被替换。

审批拒绝时，不执行真实工具，而是构造一个 rejected tool observation，再继续让 provider 生成最终回复。

使用方式

普通用户通过 Feishu 命令触发恢复：

1
2

/approve <approval-id>
/reject <approval-id> 原因

内部应用代码可以直接调用：

1
2
3
4
5

result = app.resume_approval(
    approval_id=approval_id,
    decision="approve",
    session=session,
)

审批暂停后的 RunResult 会带上：

1
2
3
4
5

RunResult(
    stop_reason="approval_required",
    approval_id="...",
    checkpoint_id="...",
)

可以通过状态目录查看持久化记录：

1
2

find "$TINY_CLAW_STATE_DIR/sessions" -path '*/approvals/*.json' -print
find "$TINY_CLAW_STATE_DIR/sessions" -path '*/checkpoints/*.json' -print

注意：当前项目没有实现独立 CLI 子命令来 approve/reject。已落地的用户侧恢复入口是 Feishu 文本命令；程序内部入口是 Application.resume_approval(...)。

测试与验证

审批恢复测试集中在 tests/test_engine.py：

1

uv run pytest tests/test_engine.py

重点测试：

• test_main_loop_suspends_high_risk_tool_for_approval
• test_main_loop_resumes_approved_high_risk_tool
• test_main_loop_consumes_approval_after_approved_tool_error
• test_main_loop_resumes_rejected_high_risk_tool_as_observation

Feishu 命令路由测试：

1

uv run pytest tests/test_feishu_integration.py

完整验证：

1
2
3
4

uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest

设计取舍与注意事项

暂停恢复的核心取舍是“不阻塞进程”。这让 HTTP 服务、Feishu 回调和 CLI 运行都能用同一套机制处理审批，而不是为每个入口写一种等待逻辑。

审批通过后执行的是 checkpoint 中冻结的原始 tool call，不重新问模型。这一点降低了参数漂移风险。恢复后才把工具 observation 交给 provider，让模型继续解释结果或提出下一步。

审批记录被消费后不能重复使用。即使工具执行返回错误，审批也会被标记为 consumed，避免用户或平台重放同一个 approval id 导致重复副作用。

当前实现会校验 session 和 tool call hash。更细粒度的 chat 用户身份校验、审批人白名单、审计日志导出属于待确认的后续能力。

总结

• 人工审批应该暂停并持久化，而不是阻塞等待。
• approval 保存决策状态，checkpoint 保存恢复主循环所需上下文。
• 审批通过后执行原始 frozen tool call。
• 审批拒绝后注入 rejected observation，让模型继续回应。
• 恢复路径坚持 fail closed，防止跨 session、过期或重放执行。

按审批专题继续阅读：20：Feishu 审批 adapter 会把通用审批流程接到真实聊天平台。

来源：本文整理自 tiny-claw/docs/tutorial/19-审批-checkpoint-暂停恢复.md。
项目地址：barry166/tiny-claw。

系列导航：系列目录 | 上一篇：从零实现 Harness Agent：运行时工具 Allowlist/Denylist 策略 | 下一篇：从零实现 Harness Agent：审批 Checkpoint 暂停与恢复

本节目标

导读：本篇属于第二部分「工具与安全边界」，处理高危副作用：当风险命中时暂停运行，把决策交给人工审批。

本节要实现的是高危工具调用的人工审批 middleware：当工具参数命中风险策略时，暂停当前 run，而不是直接执行副作用。

完成这一节后，你会理解风险评估、审批记录、暂停状态和工具执行链之间的关系。

摘要

本文要说明 tiny-claw 如何用通用 HumanApprovalMiddleware 拦截高危工具调用，并在执行真实工具前暂停等待人工决策。这个模块适合 AI Agent 框架开发者、安全策略维护者和需要把人工审批接入工具链的读者。读完后，你会理解高危规则如何评估、审批请求如何持久化，以及为什么飞书不是一个工具，而只是审批通知和回复的 adapter。

背景与问题

AI Agent 一旦拥有 bash、write、edit 这类工具，就能产生真实副作用。即使模型通常会避免明显危险请求，工程系统也不能把安全边界寄托在模型自觉上。

典型高风险场景包括：

• shell 命令删除文件、强制重置 git、提权执行、发布部署。
• 写入或编辑 .env、密钥文件、CI 配置、lockfile。
• 一次编辑删除大量内容。

这些操作不一定永远不能执行。有些任务确实需要修改 lockfile 或运行发布命令。更合理的策略是：低风险直接执行，高风险暂停并交给人工审批。

设计目标

• 通用审批：审批 middleware 不绑定飞书，也不绑定某个 UI。
• 参数级风险判断：不只看工具名，还检查命令和文件路径。
• 不阻塞进程：高危调用返回 suspended，让当前 run 停止。
• 持久化可恢复：审批和 checkpoint 写入状态目录。
• 失败关闭：缺 checkpoint、过期、状态不对、参数不匹配时拒绝执行。
• 不改工具接口：Tool.run() 不知道审批存在。

整体方案

人工审批是一个运行时 middleware：

1
2
3
4
5
6
7
8
9

flowchart TD
  Call["Tool call"] --> Approval["HumanApprovalMiddleware"]
  Approval --> Policy["DefaultRiskPolicy.evaluate(ctx)"]
  Policy -->|allow| Next["next(ctx)"]
  Next --> Tool["Tool.run(input)"]
  Policy -->|deny| Denied["ToolExecutionResult.denied"]
  Policy -->|approval_required| Persist["写 approval + checkpoint"]
  Persist --> Notify["ApprovalRequester.request_approval"]
  Notify --> Suspended["ToolExecutionResult.suspended"]

HumanApprovalMiddleware 只负责通用审批流程：

1. 检查本次调用是否已经带有 approved approval id。
2. 未审批时调用 DefaultRiskPolicy.evaluate(ctx)。
3. 低风险调用 next(ctx)。
4. 需要审批时写入 approval 和 checkpoint。
5. 通过 ApprovalRequester 发送审批请求。
6. 返回 suspended，让主循环停止当前 run。

飞书只实现通知和命令 adapter，不进入工具注册表，也不会暴露给模型。

核心实现

关键文件：

• src/tiny_claw/_internal/approval.py
• src/tiny_claw/_internal/tools/middleware.py
• src/tiny_claw/_internal/engine/main_loop.py
• src/tiny_claw/_internal/engine/tool_executor.py
• src/tiny_claw/_internal/app.py

风险评估入口：

1
2
3
4
5
6

@dataclass(frozen=True)
class DefaultRiskPolicy:
    approval_required_tools: tuple[str, ...] = ("bash", "write", "edit")

    def evaluate(self, ctx: ToolExecutionContext) -> RiskDecision:
        ...

bash 高危规则包含：

• rm / rmdir
• sudo
• git reset --hard
• git clean
• git push --force
• curl|wget ... | sh
• chmod / chown
• kill / pkill
• dd / mkfs
• deploy / publish / release

文件修改高危规则包含：

• .env、.env.local、.env.production
• pyproject.toml
• uv.lock、poetry.lock
• package-lock.json、pnpm-lock.yaml、yarn.lock
• .github/workflows/、.gitlab-ci
• 路径中包含 secret 或 key
• edit 一次删除 20 行及以上

需要审批时，middleware 要求上下文里存在 RunCheckpointDraft：

1
2
3
4
5
6

draft = ctx.metadata.get(CHECKPOINT_DRAFT_METADATA_KEY)
if not isinstance(draft, RunCheckpointDraft):
    return ToolExecutionResult.denied(
        "工具调用需要人工审批，但缺少可恢复 checkpoint。",
        metadata={"error_type": "approval_checkpoint_missing"},
    )

这条规则很重要：不能恢复的审批请求不应该被创建。

状态写入后返回暂停：

1
2
3
4
5
6
7
8

return ToolExecutionResult.suspended(
    ToolSuspension(
        approval_id=approval.id,
        checkpoint_id=approval.checkpoint_id,
        reason="; ".join(approval.risk_reasons),
        content=content,
    )
)

ToolExecutor 会把 suspended 转成 tool observation，并带上：

• suspended=True
• error_type=tool_approval_required
• approval_id
• checkpoint_id

MainLoop 看到 suspended 后返回 stop_reason="approval_required"。

使用方式

启用审批 middleware：

1
2
3

TINY_CLAW_APPROVAL_PROVIDER=feishu \
TINY_CLAW_ENABLED_TOOLS=read,write,edit,bash \
uv run tiny-claw serve --host 0.0.0.0 --port 8000

配置需要审批的工具：

1

TINY_CLAW_APPROVAL_REQUIRED_TOOLS=bash,write,edit

配置审批过期时间：

1

TINY_CLAW_APPROVAL_TIMEOUT_SECONDS=3600

TINY_CLAW_APPROVAL_PROVIDER 当前支持：

1

off, feishu

它的含义是“是否注册通用 HumanApprovalMiddleware，以及当前运行入口是否具备对应审批通知通道”。它不是“注册飞书审批工具”。模型不应该看到一个叫飞书审批的工具。

测试与验证

审批 middleware 的 engine 级测试：

1

uv run pytest tests/test_engine.py

重点覆盖：

• 高危工具调用返回 approval_required。
• suspended 后真实工具没有执行。
• approval 和 checkpoint 被写入状态目录。
• approved 后执行原始 frozen tool call。
• rejected 后注入拒绝 observation。
• approved 后即使工具执行失败，审批也会被消费，避免重复执行。

配置测试：

1

uv run pytest tests/test_settings.py

完整验证：

1
2
3
4

uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest

设计取舍与注意事项

审批 middleware 是同步链路，但它不等待人工点击或回复。同步只表示工具调用链本身是同步函数；一旦需要审批，middleware 立即返回 suspended，主循环停止。

风险规则是 v1 级别的启发式规则，不是完整安全沙箱。它适合挡住高危意图和敏感文件修改，但不能替代操作系统权限、容器隔离或代码审查。

TINY_CLAW_APPROVAL_PROVIDER=feishu 不代表系统自动拥有任意平台审批能力。当前已实现的是 Feishu 文本命令审批。互动卡片按钮、CLI 审批命令、Slack adapter 都属于待确认或后续扩展。

当 provider 在生成 tool call 前自行拒绝，例如直接回复“不能执行 rm -rf”，middleware 不会运行。这不是 middleware 失效，而是因为工具调用没有进入执行链。

总结

• HumanApprovalMiddleware 是通用审批模块，不是飞书专用逻辑。
• DefaultRiskPolicy 用工具名和参数共同判断风险。
• 高危调用会持久化 approval 和 checkpoint，然后返回 suspended。
• 主循环不阻塞等待人工，而是以 approval_required 停止当前 run。
• 飞书只是审批通知和回复 adapter，不暴露给模型。

按审批专题继续阅读：19：审批 checkpoint 暂停恢复 会让人工决策之后可以安全继续原始运行。

来源：本文整理自 tiny-claw/docs/tutorial/18-高危工具调用人工审批-middleware.md。
项目地址：barry166/tiny-claw。

系列导航：系列目录 | 上一篇：从零实现 Harness Agent：Tool Middleware 链式执行 | 下一篇：从零实现 Harness Agent：高危工具调用人工审批

本节目标

导读：本篇属于第二部分「工具与安全边界」，聚焦工具名级别的运行时策略：注册了工具，不等于当前运行一定允许调用。

本节要实现的是工具名级别的运行时 allowlist / denylist 策略：在工具已经注册之后，进一步控制当前运行是否允许调用某个工具。

完成这一节后，你会理解全局工具启用、skill 收窄和运行时策略之间的边界。

摘要

本文要说明 tiny-claw 如何在“模型可见工具”之外，再加一层运行时 allowlist / denylist 策略。这个模块适合项目使用者、工具系统维护者和需要控制不同环境工具权限的开发者。读完后，你会知道 TINY_CLAW_ENABLED_TOOLS、TINY_CLAW_TOOL_ALLOWLIST、TINY_CLAW_TOOL_DENYLIST 分别解决什么问题，以及运行时拒绝如何通过 middleware 返回给主循环。

背景与问题

工具权限有两个不同问题，不能混在一起：

• 哪些工具对模型可见？
• 即使模型发起了工具调用，运行时是否允许执行？

TINY_CLAW_ENABLED_TOOLS 解决的是第一层：模型请求时能看到哪些工具定义。它适合做全局能力开关，比如默认只启用 read，需要编辑时才启用 write 或 edit。

但真实工程里还需要第二层运行时策略。例如：

• CI 环境允许 read 和 write，但禁止 bash。
• 某个 workspace 只允许读，不允许改。
• Feishu 入口可以启用工具定义，但运行时策略仍要阻断某些工具。
• 测试中需要验证模型即使发出某个 tool call，也不会真的执行。

因此，工具系统需要在可见性之外，再有一个可配置、可测试、可短路的运行时策略模块。

设计目标

• 职责分离：可见工具和运行时允许执行的工具分开配置。
• 默认兼容：空 allowlist / denylist 不改变现有行为。
• 拒绝优先：denylist 命中时立即拒绝。
• 显式收窄：allowlist 非空时，不在列表内的工具全部拒绝。
• 可观测：拒绝结果带上 error_type 和策略来源。
• 不改工具接口：工具本身仍只实现 Tool.run()。

整体方案

运行时策略作为第一个通用 middleware 注册到工具链：

1
2
3
4
5
6
7
8

flowchart TD
  Model["Model tool call"] --> Executor["ToolExecutor"]
  Executor --> Registry["ToolRegistry.execute(ctx)"]
  Registry --> Policy["ToolPolicyMiddleware"]
  Policy -->|denylist 命中| Denied["ToolExecutionResult.denied"]
  Policy -->|allowlist 不包含| Denied
  Policy -->|允许| Next["next(ctx)"]
  Next --> Tool["Tool.run(input)"]

规则顺序是：

1. ToolExecutor 仍按模型可见工具和已注册工具处理 unknown / visibility 问题。
2. 命中 denylist，直接拒绝。
3. allowlist 非空且工具不在其中，直接拒绝。
4. 否则继续调用后续 middleware 或真实工具。

核心实现

关键文件：

• src/tiny_claw/_internal/tools/policy.py
• src/tiny_claw/_internal/settings.py
• src/tiny_claw/_internal/app.py
• tests/test_settings.py
• tests/test_tools.py

ToolPolicyMiddleware 的接口很小：

1
2
3
4
5
6
7

@dataclass(frozen=True)
class ToolPolicyMiddleware:
    allowlist: tuple[str, ...] = ()
    denylist: tuple[str, ...] = ()

    def __call__(self, ctx: ToolExecutionContext, next: ToolNext) -> ToolExecutionResult:
        ...

denylist 拒绝：

1
2
3
4
5

if ctx.tool_name in self.denylist:
    return ToolExecutionResult.denied(
        f"工具调用被运行时策略拒绝：{ctx.tool_name} 在 denylist 中。",
        metadata={"error_type": "tool_policy_denied", "tool_policy": "denylist"},
    )

allowlist 收窄：

1
2
3
4
5

if self.allowlist and ctx.tool_name not in self.allowlist:
    return ToolExecutionResult.denied(
        f"工具调用被运行时策略拒绝：{ctx.tool_name} 不在 allowlist 中。",
        metadata={"error_type": "tool_policy_denied", "tool_policy": "allowlist"},
    )

配置从环境变量读取：

1
2

TINY_CLAW_TOOL_ALLOWLIST=read,write
TINY_CLAW_TOOL_DENYLIST=bash

应用装配层统一注册：

1
2
3
4
5
6

registry.use(
    ToolPolicyMiddleware(
        allowlist=settings.tool_allowlist,
        denylist=settings.tool_denylist,
    )
)

使用方式

默认行为：不设置 allowlist / denylist 时，不额外收窄运行时工具。

只允许 read 和 write 实际执行：

1
2
3

TINY_CLAW_ENABLED_TOOLS=read,write,edit,bash \
TINY_CLAW_TOOL_ALLOWLIST=read,write \
uv run tiny-claw run --mode act "读取并写入一个说明文件"

显式禁止 bash：

1
2
3

TINY_CLAW_ENABLED_TOOLS=read,write,edit,bash \
TINY_CLAW_TOOL_DENYLIST=bash \
uv run tiny-claw run --mode act "检查项目并尝试运行命令"

同时设置 allowlist 和 denylist 时，denylist 先命中。推荐把 denylist 用作最后防线，把 allowlist 用作环境级收窄。

配置校验会拒绝未知工具名。当前支持的工具名来自 SUPPORTED_TOOLS：

1

bash, edit, read, write

测试与验证

配置读取测试：

1

uv run pytest tests/test_settings.py

运行时策略测试：

1

uv run pytest tests/test_tools.py

关键测试点：

• 默认空策略允许继续执行。
• denylist 命中时返回 denied。
• allowlist 非空且工具不在列表内时返回 denied。
• 配置中的未知工具名会触发 ConfigurationError。

完整验证：

1
2
3
4

uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest

设计取舍与注意事项

TINY_CLAW_ENABLED_TOOLS 不是 allowlist，它控制的是模型可见工具。模型看不到的工具通常不会被主动调用，但这并不等于运行时策略。allowlist / denylist 是工具调用进入执行链之后的硬性判断。

空 allowlist 的语义是“不启用 allowlist 收窄”，不是“禁止全部工具”。这样可以保持默认兼容，避免升级后现有工具调用全部被拒绝。

denylist 优先于 allowlist。这个规则更容易理解，也符合安全直觉：明确禁止的工具不应该被其他配置重新放行。

当前策略粒度是工具名级别，不检查参数。参数级风险判断由 HumanApprovalMiddleware 和 DefaultRiskPolicy 负责。后续如果需要 session 级、chat 级或用户级策略，可以扩展 middleware 的输入配置，但不建议把参数规则混入这个模块。

总结

• 可见工具和运行时执行策略是两层边界。
• ToolPolicyMiddleware 用 allowlist / denylist 实现工具名级短路拒绝。
• 默认空配置保持现有行为，适合平滑启用。
• denylist 优先，allowlist 非空时收窄允许范围。
• 参数级风险不属于本模块，应交给风险审批策略处理。

按工具专题继续阅读：18：高危工具审批 middleware 会处理策略之外需要人工决策的副作用调用。

来源：本文整理自 tiny-claw/docs/tutorial/17-运行时工具策略-allowlist-denylist.md。
项目地址：barry166/tiny-claw。

系列导航：系列目录 | 上一篇：从零实现 Harness Agent：真实 Provider 编辑演示 | 下一篇：从零实现 Harness Agent：运行时工具 Allowlist/Denylist 策略

本节目标

导读：本篇回到第二部分「工具与安全边界」，为策略、审批、审计等横切能力建立统一的 middleware 入口。

本节要实现的是通用 Tool Middleware 链：让运行时策略、人工审批、审计等横切逻辑可以包裹工具执行，而不是写死在 ToolExecutor 或具体工具中。

完成这一节后，你会理解 ToolRegistry.use(...) 的注册语义、短路行为和执行顺序。

摘要

本文要说明 tiny-claw 如何把工具调用从“直接执行 Tool”升级为“经过通用 middleware 链后再执行 Tool”。这个模块适合 AI Agent 框架开发者、工具系统维护者和希望扩展运行时拦截能力的读者。读完后，你会理解 ToolRegistry.use(...) 的注册语义、middleware 的调用顺序，以及为什么高危审批、审计、策略控制都不应该写死在单个工具里。

背景与问题

早期工具系统只需要完成一件事：模型返回 tool call，ToolExecutor 找到对应工具并调用 Tool.run()。当工具能力变多后，执行前后的横切逻辑也会出现：

• 运行时策略：某些会话允许 read，但禁止 bash。
• 风险拦截：命令或文件修改参数命中高危规则时，需要暂停等待人工审批。
• 审计记录：记录谁、在什么 session、对哪个 workdir 调用了什么工具。
• 未来扩展：限流、沙箱切换、观测指标、成本统计等。

如果这些逻辑直接塞进 ToolExecutor 或每个工具实现，会导致两个问题：主循环变重，工具实现也被运行时策略污染。更合适的做法是把工具执行抽象成一条链：每个 middleware 可以选择继续调用下一个节点，也可以直接返回结果。

设计目标

• 通用性：middleware 不绑定某个具体工具或具体审批渠道。
• 顺序明确：按 registry.use(...) 注册顺序进入，按栈式顺序返回。
• 可短路：策略拒绝、审批暂停等场景可以不执行真实工具。
• 兼容旧接口：保留 ToolRegistry.call(...)，让已有直接调用不被打断。
• 可测试：注册顺序、短路行为、结果状态都能单独测试。
• 与现有架构一致：工具执行仍由 ToolExecutor 发起，工具注册仍由应用装配层完成。

整体方案

工具执行模型从直接调用变成链式调用：

1
2
3
4
5
6
7
8
9
10

flowchart TD
  Executor["ToolExecutor"] --> Registry["ToolRegistry.execute(ctx)"]
  Registry --> M1["Middleware 1"]
  M1 --> M2["Middleware 2"]
  M2 --> M3["Middleware 3"]
  M3 --> Tool["Tool.run(input)"]
  Tool --> M3
  M3 --> M2
  M2 --> M1
  M1 --> Executor

每个 middleware 的接口都很小：接收 ToolExecutionContext 和 next，返回 ToolExecutionResult。它可以：

• 调用 next(ctx)，让后续 middleware 或真实工具继续执行。
• 返回 completed，表示已经完成。
• 返回 denied，表示工具调用被拒绝。
• 返回 suspended，表示当前 run 需要暂停。

这个设计把“工具是什么”和“工具调用前要经过哪些运行时规则”分开了。

核心实现

关键文件：

• src/tiny_claw/_internal/tools/middleware.py
• src/tiny_claw/_internal/tools/registry.py
• src/tiny_claw/_internal/engine/tool_executor.py
• src/tiny_claw/_internal/app.py

核心协议：

1
2
3
4
5

ToolNext = Callable[[ToolExecutionContext], ToolExecutionResult]

class ToolMiddleware(Protocol):
    def __call__(self, ctx: ToolExecutionContext, next: ToolNext) -> ToolExecutionResult:
        ...

ToolExecutionContext 承载一次工具调用所需的运行时信息：

• tool_call_id
• tool_name
• arguments
• session
• workdir
• visible_tool_names
• metadata

ToolExecutionResult 明确区分三种状态：

1

ToolExecutionStatus = Literal["completed", "denied", "suspended"]

ToolRegistry 负责注册 middleware 并组装调用链：

1
2
3
4
5
6
7
8
9
10
11
12

def use(self, middleware: ToolMiddleware) -> None:
    self._middlewares.append(middleware)

def execute(self, ctx: ToolExecutionContext) -> ToolExecutionResult:
    def terminal(current: ToolExecutionContext) -> ToolExecutionResult:
        output = self.get(current.tool_name).run(ToolInput(arguments=current.arguments))
        return ToolExecutionResult.completed(output)

    next_step: ToolNext = terminal
    for middleware in reversed(self._middlewares):
        ...
    return next_step(ctx)

这里使用 reversed(self._middlewares) 组装链，是为了让注册顺序等于执行进入顺序。比如：

1
2

registry.use(first)
registry.use(second)

实际事件顺序是：

1
2
3
4
5

first-before
second-before
Tool.run
second-after
first-after

ToolExecutor 不再直接调用 registry.call(...)，而是构造上下文并调用：

1
2
3
4
5
6
7
8
9
10
11

execution = self.tools.execute(
    ToolExecutionContext(
        tool_call_id=tool_call.id,
        tool_name=tool_call.name,
        arguments=tool_call.arguments,
        session=session,
        workdir=workdir,
        visible_tool_names=self._visible_tool_names(),
        metadata=metadata or {},
    )
)

使用方式

middleware 在应用装配层注册。当前注册入口位于 src/tiny_claw/_internal/app.py：

1
2

registry.use(ToolPolicyMiddleware(...))
registry.use(HumanApprovalMiddleware(...))

新增 middleware 时，推荐遵循这个形态：

1
2
3
4
5

def audit_middleware(ctx: ToolExecutionContext, next: ToolNext) -> ToolExecutionResult:
    # 记录调用前信息
    result = next(ctx)
    # 记录调用后结果
    return result

如果 middleware 要阻止真实工具执行，可以直接返回：

1
2
3
4

return ToolExecutionResult.denied(
    "工具调用被运行时策略拒绝。",
    metadata={"error_type": "tool_policy_denied"},
)

如果是需要人工介入的场景，则返回 suspended，交给主循环停止当前 run。

普通用户不需要直接调用 middleware。它是系统内部扩展点，随着 tiny-claw run 或 Feishu 消息进入工具执行链路时自动生效。

测试与验证

middleware 的核心行为由 tests/test_tools.py 覆盖：

1

uv run pytest tests/test_tools.py

重点测试包括：

• test_tool_registry_executes_middlewares_in_registration_order
• test_tool_registry_middleware_can_short_circuit
• test_tool_policy_middleware_allows_default_empty_policy
• test_tool_policy_middleware_denies_denylist_and_allowlist

工具执行器集成验证：

1
2

uv run pytest tests/test_tool_executor.py
uv run pytest tests/test_engine.py

完整回归：

1
2
3
4

uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest

设计取舍与注意事项

这个 middleware 设计刻意没有引入 before_call、after_call 之类的多钩子接口。多钩子看起来更细，但调用关系会变复杂：异常、短路、暂停、恢复都需要定义一套组合规则。链式 middleware 的优势是简单：是否继续执行，只看有没有调用 next(ctx)。

ToolRegistry.call(...) 被保留为兼容封装，但新的运行时路径应优先使用 execute(ctx)。否则 middleware 链不会生效。

middleware 本身不应该知道模型 provider，也不应该直接向 Feishu、Slack 等平台发送消息。需要外部通知时，应通过上下文 metadata 或抽象接口交给 adapter。这样工具系统的扩展点不会被某个集成平台绑死。

总结

• ToolRegistry.use(...) 提供了通用工具执行扩展点。
• middleware 按注册顺序进入，支持继续执行或短路返回。
• ToolExecutionResult 用 completed/denied/suspended 明确表达运行状态。
• 高危审批、运行时策略、审计等横切能力可以放进链路，而不是污染工具实现。
• 新执行路径保留旧接口兼容，但主流程应走 registry.execute(ctx)。

按工具专题继续阅读：17：运行时工具策略 会先用 allowlist / denylist 收窄工具调用。

来源：本文整理自 tiny-claw/docs/tutorial/16-通用-tool-middleware-链式执行.md。
项目地址：barry166/tiny-claw。

系列导航：系列目录 | 上一篇：从零实现 Harness Agent：Edit 工具的降级匹配管线 | 下一篇：从零实现 Harness Agent：Tool Middleware 链式执行

本节目标

导读：本篇属于第六部分「测试与验收」，用真实 Provider 路径补上 fake provider 无法证明的一环：模型是否真的会按工具描述完成编辑。

本节要补充的是真实 Provider 下的编辑流程验收：用脚本验证模型能否在真实工具描述下完成 read + edit。

完成这一节后，你会知道 fake provider 与 live demo 分别证明什么，以及如何判断真实模型路径是否真的可用。

摘要

本文说明如何用 tests/demo_edit_flow.py 跑一次真实 Provider 下的 read + edit 文件编辑流程。它适合项目使用者、Agent 框架开发者和后续维护者阅读。读完后，你会知道怎么配置真实模型、怎么判断编辑是否真的生效，以及为什么这类 live demo 只能做补充验收，不能替代稳定的自动化测试。

背景与问题

FakeProvider 可以稳定验证 Engine 编排，但它回答不了一个现实问题：真实模型看到工具描述后，会不会按预期调用 read 和 edit？

对 edit 这样的工具来说，这个问题很重要。工具本身已经有严格校验，但真实模型还需要做到几件事：

• 理解应该先读取文件，而不是直接猜测内容。
• 构造足够唯一的 old_text。
• 在多行代码缺少缩进时，仍然给出能被工具匹配的片段。
• 在最终回复中正确说明工具是否执行成功。

这些行为无法完全通过单元测试证明。真实 Provider demo 的目标是提供一个人工可读、脚本可断言的验收入口：它创建临时文件，让真实模型完成一次编辑任务，最后用文件内容判断成败。

设计目标

• 真实性：使用当前配置的真实 Provider，而不是 FakeProvider。
• 可观察性：打印 Provider、初始文件、最终回复和最终文件。
• 安全性：使用临时工作区，不修改项目源文件。
• 可断言：最终文件必须等于预期内容，否则 demo 失败。
• 配置复用：通过 .env 或环境变量读取 Provider 配置。
• 边界清晰：作为手动或补充验收，不混入普通单元测试。

整体方案

tests/demo_edit_flow.py 会执行一条很小但完整的路径：

1. 从环境读取基础 settings。
2. 如果当前 Provider 是 echo，提示需要真实 Provider 并退出。
3. 创建临时 workdir 和 state dir。
4. 写入一个待修改的 greeting.py。
5. 设置 TINY_CLAW_ENABLED_TOOLS=read,edit。
6. 调用 build_application(Settings.from_env())。
7. 运行一次 RunMode.ACT。
8. 打印最终回复、停止原因、步数和最终文件。
9. 断言最终文件是否等于预期内容。

1
2
3
4
5
6
7
8
9
10
11
12

flowchart TD
  Env[".env / 环境变量"] --> Settings["Settings.from_env()"]
  Settings --> Provider{"真实 Provider?"}
  Provider -->|echo| Exit["提示需要 OpenAI 或 Claude"]
  Provider -->|openai / claude| Temp["创建临时 workdir/state"]
  Temp --> File["写入 greeting.py"]
  File --> Tools["启用 read,edit"]
  Tools --> App["build_application()"]
  App --> Run["Application.run(mode=ACT)"]
  Run --> Model["Provider 返回 tool calls / final response"]
  Model --> Print["打印最终回复、步数和文件"]
  Print --> Assert["校验最终文件"]

这个 demo 的定位是“真实行为验收”。它不覆盖所有边界，只挑一个典型编辑任务：读 greeting.py，替换函数体里的两行，再检查最终文件。够小，失败时也容易看出是哪一层出了问题。

核心实现

关键文件是 tests/demo_edit_flow.py。

脚本首先读取配置，并拒绝使用 echo：

1
2
3
4

base_settings = Settings.from_env()
if base_settings.provider_name == "echo":
    print("This demo needs a real provider, not echo.")
    return 2

然后创建临时目录，准备待修改文件：

1
2
3
4
5
6
7

with TemporaryDirectory() as tmp:
    workdir = Path(tmp) / "workdir"
    state_dir = Path(tmp) / "state"
    workdir.mkdir()

    target = workdir / "greeting.py"
    target.write_text(INITIAL_FILE, encoding="utf-8")

脚本在运行前显式启用工具：

1
2
3

os.environ["TINY_CLAW_WORKDIR"] = str(workdir)
os.environ["TINY_CLAW_STATE_DIR"] = str(state_dir)
os.environ["TINY_CLAW_ENABLED_TOOLS"] = "read,edit"

这一步很重要。edit 是写类工具，不应该默认暴露给模型。demo 也必须像真实使用一样显式启用。

Prompt 会明确要求模型先读文件，再编辑函数体：

1
2

1. 先使用 read 工具读取 greeting.py。
2. 再使用 edit 工具只替换函数体里的下面两行。

最后，脚本读取最终文件并做断言：

1
2
3
4
5

if final_file != EXPECTED_FILE:
    print("DEMO RESULT: failed; real provider did not produce the expected edit.")
    return 1

print("DEMO RESULT: passed; real provider produced the expected edit.")

这个断言避免 demo 只凭最终回复判断成功。对文件编辑工具来说，最终文件才是事实来源。

使用方式

先在环境或项目 .env 中配置真实 Provider。OpenAI 示例：

1
2
3

OPENAI_API_KEY=<your-openai-api-key>
OPENAI_BASE_URL=<optional-openai-compatible-base-url>
TINY_CLAW_PROVIDER=openai

运行 demo：

1

TINY_CLAW_PROVIDER=openai uv run python tests/demo_edit_flow.py

Claude / Anthropic 示例：

1
2
3

TINY_CLAW_PROVIDER=claude \
ANTHROPIC_API_KEY=<your-anthropic-api-key> \
uv run python tests/demo_edit_flow.py

脚本会打印这些部分：

1
2
3
4
5
6
7
8
9
10
11
12
13

=== Provider ===
openai

=== Initial File ===
...

=== Final Response ===
...

=== Final File ===
...

DEMO RESULT: passed; real provider produced the expected edit.

脚本不会额外整理逐条 tool observation。如果需要看更细的工具调用过程，应结合运行日志排查。不要把真实 API key 写入文档、日志或提交记录。.env 应保持在 git ignore 中。

测试与验证

这个 demo 本身就是手动验收命令：

1

TINY_CLAW_PROVIDER=openai uv run python tests/demo_edit_flow.py

建议在以下情况运行：

• 修改 EditTool 描述、参数 schema 或匹配策略后。
• 修改 Provider 的 tool call 转换逻辑后。
• 修改 MainLoop 工具策略或 ToolExecutor 后。
• 准备对外展示 edit 工具真实能力前。

常规自动化测试仍然应该先运行：

1
2

uv run pytest tests/test_tools.py
uv run pytest tests/test_engine.py

完整回归：

1
2
3
4

uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest

如果 live demo 失败，不一定说明工具实现有 bug。常见原因包括：

• Provider 未正确配置。
• 网络或兼容 API 服务不可用。
• 模型没有按 prompt 调用工具。
• 模型构造的 old_text 不够唯一。
• 工具策略没有启用 read,edit。

排查时先看脚本打印的 Provider、最终回复、步数和最终文件，再结合日志判断失败发生在哪一层。

设计取舍与注意事项

第一，live demo 不放进普通单元测试路径。真实模型测试会受到网络、额度、模型版本和服务状态影响，把它做成每次 CI 的硬门槛会很脆。

第二，demo 使用临时工作区。它验证真实文件编辑副作用，但不触碰项目源文件。这让 demo 可以安全重复执行。

第三，脚本显式拒绝 echo provider。echo 适合 CLI smoke test，但不能证明真实模型理解工具描述。

第四，最终文件断言比最终回复更重要。模型可能声称修改成功，但文件没有变化；也可能工具成功了，但最终回复措辞不同。demo 以文件内容作为验收标准。

第五，Prompt 写得相对明确，这是验收脚本的合理设计。它不是要测试模型在任意模糊指令下的能力，而是验证工具链在清晰任务下能否真实生效。

总结

• FakeProvider 适合证明 Engine 编排，真实 Provider demo 负责补一刀：模型路径是否真的可用。
• tests/demo_edit_flow.py 使用临时目录和最终文件断言，适合手动验收。
• edit 作为写类工具必须显式启用，demo 也遵守这个边界。
• live demo 不应替代单元测试和 Engine 流程测试。
• 真实验收时不要暴露 API key、base URL 或本地私有路径。

按编号继续阅读：16：通用 Tool Middleware 会把运行时策略和审批能力接入工具链。

来源：本文整理自 tiny-claw/docs/tutorial/15-真实-provider-edit-demo.md。
项目地址：barry166/tiny-claw。