企业官网建设流程全解析

Claude Code 这类工具真正难跑通的地方，往往不是模型能力，而是 Harness 配置。Learn Claude Code 这个开源项目把 Agent Loop 和 Subagent 机制拆成 s01-s12 逐步演示，核心观点很直接：模型才是 Agent，代码只是 Harness，Harness 只做三件事——跑循环、执行工具、把结果回传给模型。这篇就按这个思路，用 TaoToken 统一 Key 和 API 通道，把 config.toml 与 settings.json 骨架配好，再触发一次 Loop 和 Subagent 调用，让整套骨架先跑起来。

1. 先理解 Agent Loop 与 Subagent 到底在解决什么

Learn Claude Code 把 Agent 定义成一个永不停止的循环：用户发请求，模型判断要不要调工具，调完把结果塞回上下文，模型再判断下一步。所有复杂机制都叠加在这个 Loop 上，代码不写死流程。

但裸 Loop 有四个典型痛点，项目里对应了四个解法：

Subagent 在这里不是独立进程，而是一个工具。模型判断需要探索时调用它，子进程读完文件只回传结论，父进程上下文保持干净。这就是 Harness 的边界：它不替模型做决策，只负责把工具执行结果结构化返回。

2. TaoToken 前置：统一 Key 与 API 通道

在写配置之前，先把 Key 和通道准备好。TaoToken 的作用是给 Claude Code 这类工具提供统一的 API 入口，避免在多个配置文件里散落不同来源的 Key。

你需要拿到两样东西：

• API Base：https://taotoken.net/api
• API Key：在控制台创建，建议按项目单独建 Key，方便后续轮换

控制台入口：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite

API Key 管理页：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite

注意：Key 只放在本地环境变量或本地配置文件里，不要提交到 Git。项目里建议用.env或系统环境变量注入。

如果你还没决定用哪种接入方式，可以先看接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite

3. 可复制骨架：config.toml 与 settings.json

下面这套骨架的目标是让 Harness 能读到统一的 API 通道，同时把 Loop 和 Subagent 的关键参数暴露出来。你可以直接复制后改 Key。

3.1 config.toml

# config.toml # Harness 主配置：Loop 与 Subagent 共用同一 API 通道 [api] base_url = "https://taotoken.net/api" api_key_env = "TAOTOKEN_API_KEY" model = "claude-sonnet-4-20250514" max_tokens = 8192 timeout_seconds = 120 [loop] max_iterations = 30 tool_result_keep_recent = 3 auto_compact_threshold_tokens = 50000 enable_manual_compact = true [todo] max_items = 20 max_in_progress = 1 stale_rounds_alert = 3 [subagent] enabled = true max_concurrent = 3 isolate_context = true return_only_summary = true [skills] progressive_loading = true index_file = "./skills/index.json" max_skills_per_turn = 5

几个参数值得单独说：

• tool_result_keep_recent = 3：对应 Micro 压缩，只保留最近三条工具结果，更早的替换成工具名占位符。
• auto_compact_threshold_tokens = 50000：对应 Auto 压缩，超过阈值先落盘 JSON 再摘要。
• isolate_context = true：Subagent 隔离开关，子进程读文件不污染父上下文。
• progressive_loading = true：Skills 按需加载，先读 index 再拉具体 skill。

3.2 settings.json

{ "env": { "TAOTOKEN_API_KEY": "sk-your-key-here", "ANTHROPIC_BASE_URL": "https://taotoken.net/api" }, "harness": { "config_path": "./config.toml", "workspace_root": "./workspace", "inbox_dir": "./workspace/inbox", "tasks_dir": "./workspace/tasks", "history_dir": "./workspace/history" }, "subagent": { "inbox_poll_before_llm": true, "git_worktree": true, "worktree_root": "./workspace/worktrees" }, "compact": { "micro_enabled": true, "auto_enabled": true, "manual_tool_name": "compact" } }

inbox_poll_before_llm = true对应项目里的 JSONL 收件箱机制：每次调模型前先查邮箱，有消息就并入上下文。git_worktree = true让每个 Subagent 在自己的目录下干活，避免两个 Agent 改同一文件导致回滚困难。

4. 验证动作：触发一次 Loop 与 Subagent 调用

配置写完后，不要急着跑复杂任务，先用一个最小动作验证 Loop 和 Subagent 是否真的被触发。

4.1 设置环境变量

export TAOTOKEN_API_KEY="sk-your-key-here" export ANTHROPIC_BASE_URL="https://taotoken.net/api"

4.2 启动 Harness

python -m harness.main --config ./config.toml --settings ./settings.json

启动后观察日志里是否出现loop started和api base = https://taotoken.net/api。如果 base 不对，说明 settings.json 没被读到。

4.3 触发 Loop

在交互窗口输入一个需要多步的任务：

帮我分析当前项目的目录结构，并给出模块划分建议

预期日志顺序：

[loop] iteration 1 [llm] request -> taotoken [tool] list_dir called [tool] read_file called [loop] iteration 2 [llm] request -> taotoken [loop] done

如果只出现一次iteration 1就结束，说明 Loop 没继续，检查max_iterations是否被覆盖成 1。

4.4 触发 Subagent

输入一个明确需要探索的任务：

用 Subagent 扫描 src 下所有 Python 文件，汇总每个文件的职责

预期看到：

[subagent] spawn id=sub-001 [subagent] isolated context=true [subagent] read_file src/agent.py [subagent] read_file src/tools.py [subagent] summary returned [loop] iteration 2

关键验证点：父进程日志里不应该出现具体的文件内容，只应该出现 Subagent 返回的摘要。如果父上下文里出现了完整文件内容，说明isolate_context没生效。

5. 本篇常见报错与排查

5.1 401 Unauthorized

[llm] error: 401 Unauthorized

原因通常是TAOTOKEN_API_KEY没注入，或者 settings.json 里的 env 没被加载。先确认：

echo $TAOTOKEN_API_KEY

如果为空，重新 export。如果 settings.json 里写了 Key 但环境变量为空，检查 Harness 是否真的读取了 settings.json 的 env 段。

5.2 Loop 不继续

[loop] iteration 1 [loop] done

模型没有返回工具调用，Loop 就结束了。检查两点：一是模型是否支持 tool use；二是工具定义是否注册到了请求里。可以在日志里搜tools字段确认。

5.3 Subagent 上下文污染

父进程日志里出现完整文件内容，说明 Subagent 没有隔离。检查config.toml里isolate_context是否为 true，以及 Subagent 是否真的以子进程方式启动。如果 Subagent 和主进程共用同一个 messages 列表，隔离就是假的。

5.4 Auto compact 不触发

[tokens] current=62000 threshold=50000 [compact] skipped

阈值到了但没触发，通常是auto_enabled被覆盖，或者 token 计数没接上。检查compact.auto_enabled和 token 统计模块是否在每次 LLM 调用前执行。

5.5 Skills 全量加载

日志里一次性出现 100 个 skill 加载记录，说明渐进式加载没生效。检查skills.index_file是否存在，以及progressive_loading是否为 true。正确行为是先读 index，只加载当前任务相关的 skill。

6. 长期编码场景：用 Coding Plan 固定通道

如果你打算把这套 Harness 长期用于日常编码，建议把 API 通道固定下来，避免每次换 Key 都改配置。Coding Plan 入口：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite

模型对话入口：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite

Claude Code 相关接入参考：https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode-anthropic&utm_campaign=rewrite

把 Key 和通道固定后，Harness 的 config.toml 基本不用再动，后续只需要调整 Loop 参数和 Subagent 并发数。这套骨架跑通后，再往上叠加 TodoWrite、Skills 渐进加载、三层压缩，就是 Learn Claude Code 里 s03 到 s07 的完整路径。先让 Loop 转起来，再让 Subagent 隔离生效，最后才是压缩和协作。顺序反了，排查成本会高很多。