Abstract

This article traces the evolution of a reliability layer for web search in AI agents. The work began as an attempt to stabilize OpenClaw’s Gemini-backed search, but quickly exposed deeper problems: provider-specific parameters, ambiguous failure states, uncontrolled retries, proxy failures, response-envelope mismatches, tool-policy bypasses, and missing execution records. I first built an OpenClaw runtime gate that governed search calls, classified failures, bounded retries, normalized responses, and wrote auditable JSONL records. The design was then generalized into reliable-web-search, a policy-driven multi-provider search runtime with provider priorities, structured errors, real request cancellation, circuit breaking, fallback/race/aggregate strategies, multi-credential routing, a unified CLI, and a stdio MCP server. The central lesson is simple: reliable agent systems are not defined by never failing, but by knowing precisely what failed, what evidence remains usable, what action is permitted next, and when execution must stop.

2026-06-26 更新

本文最初记录的是一个运行在 OpenClaw 内部的本地插件原型。随后,我将其中可复用的参数治理、搜索路由、错误语义、取消、熔断和诊断能力抽象为独立开源项目 reliable-web-search,并发布到 npm。当前公开版本为 v0.4.0,已支持统一 CLI、stdio MCP、多 Provider、多凭据 profile、环境变量临时路由,以及 OpenClaw 等 Agent Host 的自动接入。文中的本地插件与当前 npm 包不是同一套代码:前者解释项目为什么出现,后者则是这套思路经过重构后的通用实现。

leecdiang/reliable-web-search

这次改造的起因很简单:OpenClaw 的联网搜索不稳定。

最开始我把它当成普通配置问题–也许 API Key 没填对,也许本地代理偶尔掉线,也许重启一下 Gateway 就恢复了。结果排查下来发现,整条 Tool Calling 链路缺的是状态语义。

搜索失败时,Agent 知道失败发生在哪一层吗?

网络没连上、Provider 服务过载、配额耗尽、鉴权失败、响应解析错误和真正没有结果,最后可能都被压缩成一句"搜索失败"。Agent 也可能进一步把"调用失败"误解成"网上没有相关资料"。一次请求该重试几次?超时后底层请求还在消耗额度吗?多个 Provider 同时可用时,按什么顺序调用?哪个结果才算真正可用?整个过程能不能回溯?

这些问题不断冒出来,任务也从"修好搜索"变成了:

为 Agent 建立一个受控、可测试、可取消、可审计,并且能够正确失败的搜索运行时。

下面是一条从故障排查、运行时治理到通用搜索基础设施的演化路径。

1. 搜索失败不是一个状态,而是一组完全不同的故障

OpenClaw 原本已经有 web_search 工具,通过 Gemini 获取联网结果。调用链看起来是这样的:

1
2
3
4

Agent
→ web_search
→ Gemini
→ 搜索结果

这条链路藏了一个问题:Agent 看到的是工具调用结果,但故障到底发生在哪个层级,它不知道。

排查时我遇到过这些状态:

1
2
3
4
5
6
7
8

unsupported_language
503 UNAVAILABLE / high demand
429 rate limited
fetch failed
ECONNREFUSED
no_results
response_parse_failure
401 authentication failure

它们不是同一类失败。

1.1 参数错误、服务过载、网络故障和空结果不是一回事

统一接口容易让人以为所有搜索 Provider 接受同一组参数。实际上 Gemini、Brave、Tavily、SearXNG 这些服务,在语言、国家、时间范围、结果数量和网页索引能力上各有差异。

早期 OpenClaw 调用中,Gemini 不接受部分通用字段:

1
2
3
4

language
search_lang
country
ui_lang

Agent 按统一接口传这些字段,Provider 直接拒绝请求。问题不是网络,也不是"没有结果",是:

1
2
3

调用参数
≠
Provider 能力

其他故障也要分开处理:

只有两个条件都满足才算 no_results:Provider 成功响应,响应结构正确解析,且没有可用内容。

请求没发出去、响应解析不了、Provider 确实返回空结果–这是三种状态。

1
2
3

不应原样重试同一个 Provider
≠
不应 fallback 到其他 Provider

某个 Provider 返回空结果,可能只是索引覆盖范围不同、查询理解方式不同或者服务类型不同。可靠搜索不能把"当前 Provider 没找到"解释成"互联网中不存在"。

1.2 可靠性的关键是让失败决定下一步,不光是避免它

需要回答的问题就那么几个:

1
2
3
4
5
6
7
8

这次请求发出去了没有?
发给了哪个 Provider?
系统读懂响应了吗?
错误值得重试吗?
应该换凭据,还是换 Provider?
超时后底层请求真的停了吗?
当前结果能进入证据审查吗?
什么时候必须停止?

这些没有稳定答案,Agent 就只能自己猜。

可靠性设计的核心也变了:

1
2
3

"让搜索成功"
→
"让每一种失败都有明确的类型、边界和后续动作"

2. 先在 OpenClaw 里造一道 Agent 绕不过去的 Runtime Gate

最直接的做法,是在 Prompt 或 Skill 中加规则:

1
2
3

如果搜索失败,不要编造答案。
遇到 503 时有限重试。
网络错误不能解释成没有结果。

这些规则当然有用,但本质上仍然只是行为建议。

模型可能遵守,也可能随着上下文增长、工具变多、任务变复杂,把规则搁在一边。更关键的是,Prompt 管不住 Agent 绕过新流程。如果 Runtime 同时暴露 web_search 和 reliable_web_search,Skill 写着"优先用后者",模型仍然可能直接调用原始工具。

所以关键不在继续扩写 Prompt,而是在工具层建立一道 Gate:

1
2
3
4
5
6
7
8
9

Agent
→ 受控搜索入口
→ 参数治理
→ Provider 路由
→ 错误分类
→ 有限重试
→ 结果标准化
→ 状态判断
→ 审计记录

同时在权限层封死原始入口:

1

web_search = denied

可靠性不能依赖模型"记得遵守规则"。应该让未经治理的路径根本不存在。

2.1 先建立隔离的 Test Agent

我没有直接修改 Main Agent 或 Code Lab,而是单独建立了一个临时 test Agent,验证三件事:

1. 插件是否被 OpenClaw Runtime 正确加载;
2. 新工具是否真的可调用;
3. 被禁止的工具是否在 Runtime 层不可调用。

当时的工具策略大致如下:

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

{
  "id": "test",
  "tools": {
    "profile": "full",
    "allow": [
      "reliable_web_search",
      "read",
      "session_status",
      "memory_get",
      "memory_search"
    ],
    "deny": [
      "web_search"
    ]
  }
}

使用 full profile 是因为 OpenClaw 的处理顺序是：

1
2
3

profile
→ allow
→ deny

之前用 minimal 时，插件工具在 profile 阶段就被过滤掉，allowlist 无法把它加回来。最后采用：

1
2
3
4

full profile
→ 让插件工具进入候选集合
→ allowlist 严格收窄
→ deny 明确移除原始 web_search

最终 Runtime 中确认:

1
2
3
4

reliable_web_search = present
web_search = absent
write = absent
apply_patch = absent

我还让 Agent 实际尝试调用 write。Runtime 返回"工具未注册",而不是由 Agent 自己说"我不会使用"。

这一步验证了一条很重要的原则:

Tool Policy 必须是运行时能力边界,不是写在 Prompt 里的行为建议。

2.2 OpenClaw 原型只治理调用,不重写整套基础设施

第一版插件注册了一个新的工具:

1

reliable_web_search

它没有重新实现 Gemini API,而是调用 OpenClaw 自己的搜索 Runtime:

1
2
3
4

api.runtime.webSearch.search({
  config: api.config,
  args
})

这样做是因为 OpenClaw 已经负责:

• API Key 管理;
• 代理设置;
• Provider 适配;
• 网络与安全约束;
• 引用包装;
• Runtime 返回结构;
• 基础日志。

如果插件直接对 Gemini 发起 fetch,就等于绕过了现有的运行时管理能力。这个 wrapper 只负责搜索调用的治理,而不是复制一套搜索基础设施。

原型被拆成几个部分:

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

src/index.ts
    插件入口、调用流程和路由

src/pure.ts
    参数清洗、响应标准化和错误分类

src/retry.ts
    重试计划、退避和 jitter

src/search-run-log.ts
    JSONL 审计记录

src/index.test.ts
    回归测试

标准输出被设计为:

1
2
3
4
5
6
7
8
9
10
11

{
  "ok": true,
  "status": "success",
  "provider": "gemini",
  "attempts": 1,
  "results": [],
  "error": null,
  "removed_parameters": [],
  "retrieval_succeeded": true,
  "usable_for_review": true
}

这里刻意没有设计 usable_for_claim。

因为:

1
2
3
4
5
6
7
8

retrieval_succeeded
= 检索成功并得到可解析内容

usable_for_review
= 内容可以进入后续来源审查

usable_for_claim
= 不应由搜索层决定,而应由 Evidence Layer 判断

搜索层负责取回数据和描述状态,不替 Agent 宣布事实成立。

2.3 参数治理:统一请求经过 Provider capability check

OpenClaw 原型中,调用前先经过:

1

sanitizeSearchArgs(provider, args)

输入:

1
2
3
4
5
6

{
  "query": "ASIC design flow",
  "count": 10,
  "country": "US",
  "language": "zh"
}

如果当前 Provider 不支持 country 和 language,发送前变成:

1
2
3
4

{
  "query": "ASIC design flow",
  "count": 10
}

同时记录:

1
2
3
4
5
6

{
  "removed_parameters": [
    "country",
    "language"
  ]
}

这不只是删字段,而是建立一条显式转换链:

1
2
3
4

用户意图
→ 统一搜索请求
→ Provider capability check
→ Provider-specific request

这个思路后来保留到 reliable-web-search。每个 Provider 都有显式 capabilities,系统可以判断它属于完整网页搜索、AI Search 还是 Instant Answer,是否支持 freshness,以及最大结果数量。

2.4 失败语义、有限重试和停止条件

原型阶段,我将错误归纳为:

1
2
3
4
5
6

provider_overloaded
rate_limited
transport_failure
authentication_failure
no_results
response_parse_failure

随后明确区分两个经常被混在一起的动作:

1
2
3
4
5

retry
= 再次调用同一个 Provider

fallback
= 换一个 Provider 继续执行

合理策略大致如下:

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

provider_overloaded
→ 2s → 5s → 12s
→ 有限尝试

rate_limited
→ 优先读取 Retry-After
→ 否则最多短暂重试一次

transport_failure
→ 短等待
→ 最多重试一次

authentication_failure
→ 不重试当前凭据

no_results
→ 不对同一 Provider 原样重试
→ 可以换 Provider

期间还修复过一个 attempts 计算问题,最终明确:

1
2
3
4
5

attempts
= 包含首次调用在内的总调用次数

retryIndex
= 已完成的重试次数

真实网络失败时,结果类似:

1
2
3
4
5
6
7
8
9
10

{
  "ok": false,
  "status": "transport_failure",
  "provider": "gemini",
  "attempts": 2,
  "results": [],
  "error": "fetch failed",
  "retrieval_succeeded": false,
  "usable_for_review": false
}

它表达的是:

1
2
3
4
5

首次调用失败
→ 有限等待
→ 重试一次
→ 仍然失败
→ 明确停止

可靠性不是死磕到成功,而是知道什么时候继续、什么时候切换、什么时候结束。

2.5 最难判断的不是失败,而是失败发生在哪一层

排查时最容易混淆的是:

1
2
3

网络失败
Provider 返回空结果
wrapper 解析失败

一开始 Gemini Runtime 返回:

1
2
3
4
5
6
7

{
  "provider": "gemini",
  "result": {
    "content": "...",
    "citations": []
  }
}

wrapper 检查的却是:

1

rawRecord.content

真正内容在:

1

rawRecord.result.content

一个包含正文的成功响应,被误判成 no_results。

正确做法是先解开 Runtime envelope:

1
2
3
4
5
6
7

const rawData =
  rawRecord &&
  typeof rawRecord === "object" &&
  "result" in rawRecord &&
  typeof rawRecord.result === "object"
    ? rawRecord.result
    : rawRecord;

之后所有内容检测、引用读取和标准化都基于 rawData。

教训:响应结构本身也是运行时契约。适配器看不懂响应,就该返回 parse failure,而不是解释成空结果。

期间还出过一次事故–用宽泛正则清理调试代码时,顺手删掉了刚修好的 envelope 解包逻辑。之后我给自己加了一条规矩:

1
2
3

不使用宽泛正则批量改源码;
修复必须落在 src;
每次修改后重新 build 并跑回归测试。

最终,真实调用链闭环为:

1
2
3
4
5
6
7

Agent
→ reliable_web_search
→ OpenClaw Web Search Runtime
→ Gemini
→ Runtime envelope
→ normalize
→ Agent

2.6 基础设施故障不会因为代码正确而消失

当时另一个反复出现的变量,是本地代理:

1

127.0.0.1:17891

只要代理进程退出,Gateway 仍然尝试连接原端口,最终得到:

1
2
3

ECONNREFUSED
fetch failed
transport_failure

这解释了为什么同一套代码可能几分钟前成功、几分钟后又失败。

最终确认的代理配置是:

1
2
3
4
5
6
7
8
9
10

代理模式:规则
HTTP/SOCKS 端口:17891

服务模式 TUN:关闭
DNS 防污染:关闭
局域网代理:关闭

自启动:开启
关闭时询问:关闭
退出时最小化:开启

最需要区分的是:

1
2
3

关闭窗口
≠
退出代理进程

reliable_web_search 可以正确识别代理故障,却不能自动恢复一个已经退出的代理服务。

这也是可靠性工程的边界:软件可以描述基础设施失败、隔离影响并选择后续策略,但不能假装依赖永远可靠。

2.7 JSONL:让搜索离开不可追踪的对话

原型会把每次搜索追加到:

1

~/.openclaw/workspace/90_system/search/search_runs.jsonl

成功记录类似:

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

{
  "search_run_id": "SEARCH-2bb117-372755",
  "query": "latest OpenClaw version 2026",
  "provider": "gemini",
  "attempts": 1,
  "status": "success",
  "error_code": null,
  "latency_ms": 7758,
  "result_count": 1,
  "removed_parameters": [],
  "retrieval_succeeded": true,
  "usable_for_review": true,
  "started_at": "2026-06-18T13:42:26.336Z",
  "finished_at": "2026-06-18T13:42:34.094Z"
}

网络失败也会留下记录:

1
2
3
4
5
6
7
8
9
10

{
  "query": "OpenClaw official documentation",
  "provider": "gemini",
  "attempts": 2,
  "status": "transport_failure",
  "error_code": "fetch failed",
  "result_count": 0,
  "retrieval_succeeded": false,
  "usable_for_review": false
}

过去 Agent 只丢一句"搜索失败",想追问都不知道从哪里下手:调用了哪个 Provider?实际调用了几次?是代理问题、限流还是解析失败?哪些参数被删除?有没有获得可用内容?总耗时多少?

有了结构化记录,这些问题都有答案。

日志中刻意不保存 API Key、Authorization Header、完整 Provider 原始响应和完整搜索正文。

不过 query 本身也可能包含姓名、文件路径、项目代号等敏感信息。正式部署时,日志系统仍应支持关闭 query 日志、对 query 脱敏、只保存 query hash、设置日志保留期限。

可审计不意味着无限记录。观测能力同样要服从隐私边界。

3. 从 OpenClaw 插件到通用搜索运行时

OpenClaw 原型已经解决了当时的问题,但它仍然和本地环境高度绑定:

• 依赖 OpenClaw Runtime;
• Provider 路由写在插件内部;
• JSONL 路径固定在 workspace;
• 错误类型和返回结构服务于特定 Agent;
• 其他 Node.js 应用无法直接复用。

真正值得抽取的问题其实是:

1
2
3
4
5
6
7
8

如何选择 Provider?
什么状态触发 retry?
什么状态触发 fallback?
超时后请求是否真的停止?
多个 Provider 并发时如何结束?
Provider 连续故障时如何隔离?
如何判断结果是否满足最低质量门?
如何记录每一次尝试?

于是这部分能力被抽象成独立项目:

1

reliable-web-search

它的定位不再是"OpenClaw 搜索插件",而是应用与多个搜索 API 之间的策略运行时:

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

Application / Agent
        │
        ▼
reliable-web-search
        │
        ├─ Provider registry
        ├─ Priority routing
        ├─ Capability and configuration checks
        ├─ Retry and fallback policy
        ├─ Timeout cancellation
        ├─ Circuit breaker
        ├─ Result status and quality gate
        └─ Attempt diagnostics
        │
        ▼
Search Providers

3.1 Provider registry:显式优先级、能力和配置门

第一版按注册顺序排列,结果有时让无需密钥但能力有限的 Provider 排到前面。

现在每个 Provider 都具有:

1
2
3

priority
capabilities
isConfigured()

registry 只加入真实配置完成的 Provider,并按优先级路由。SearXNG 只有显式配置 Base URL 才算可用,不再默认向本机 localhost 发请求。

如果用户写错 Provider 名称:

1

providers: ["brvae", "tavily"]

系统会给出接近的拼写建议,而不是静默忽略。

当前内置八个 Provider:

DuckDuckGo 使用 Instant Answer API,不是完整网页搜索,更适合百科式主题摘要,因此被放在低优先级兜底位置。

3.2 三种执行策略:fallback、race、aggregate

三种模式:

1
2
3

fallback
race
aggregate

fallback

按优先级顺序调用 Provider:

1
2
3
4

Provider A
→ 失败或空结果
→ Provider B
→ 成功后停止

race

同时启动多个 Provider,第一个获得可用结果的请求成为 winner:

1
2
3
4
5
6
7

A ───────────────
B ───── success
C ─────────

B wins
→ abort A
→ abort C

这不是简单调用 Promise.all()。winner 一旦确认,其他 Provider 的独立 AbortController 会立即触发,避免落败请求继续占用连接和额度。

aggregate

并发调用多个 Provider,并汇总成功结果。当前版本已经完成统一执行和状态诊断,但复杂的 URL canonicalization、跨 Provider 去重、融合排序和域名多样性控制仍属于后续工作。

3.3 超时现在真的会取消请求

早期实现使用:

1

Promise.race([providerPromise, timeoutPromise])

这只会让上层停止等待,底层 fetch 仍可能继续运行。

当前实现通过 AbortController 将 timeout 传入实际请求:

1
2
3
4
5

达到超时
→ signal.abort()
→ Provider fetch 终止
→ 记录 timeout
→ 根据策略 retry 或 fallback

测试会直接验证 Provider 能观察到:

1

signal.aborted === true

这解决了 Agent 系统里很隐蔽的一类成本问题:

表面已经超时,后台请求还在继续消耗额度。

3.4 结构化 ProviderError 与 Circuit Breaker

Provider 不再只抛一个字符串,而是返回结构化错误:

1
2
3
4
5
6

providerId
error code
HTTP status
retryable
shouldBreakerTrip
Retry-After

系统据此区分:

1
2
3
4
5
6
7

401 auth_failed
429 rate_limited
500 server_error
timeout
aborted
no_results
parse_error

并决定要不要重试、要不要 fallback、要不要切换凭据、要不要计入熔断器、是否需要等待、最终返回什么状态。

鉴权错误不应该当成瞬态服务故障记入熔断器。网络错误、超时和 5xx 才真正反映 Provider 健康状态。

熔断器有 closed、open、half-open 三种状态。失败达到阈值后:closed → open → 暂时跳过该 Provider → recovery timeout → half-open 试探 → 成功后 closed。

当前实现验证了调用级配置能真正进入 breaker–比如 failureThreshold = 1、recoveryTimeout = 100ms–不只是类型定义里有。

3.5 结果契约与 AttemptRecord

最终返回值不只包含结果,还包含完整的执行元数据:

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

interface ReliableSearchResult {
  results: UnifiedSearchResult[];
  provider: string;
  providerPath: string[];
  fallbackReason?: string;
  attempts: AttemptRecord[];
  elapsedMs: number;
  retrievalSucceeded: boolean;
  usableForReview: boolean;
  resultStatus:
    | "success"
    | "partial"
    | "no_results"
    | "failed"
    | "aborted";
  cacheHit: boolean;
}

每次尝试都会记录:

1
2
3
4
5
6
7
8

Provider
Route
凭据 profile
状态
耗时
错误分类
HTTP 状态
结果数量

例如:

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

{
  "providerPath": ["tavily.default"],
  "attempts": [
    {
      "providerId": "tavily",
      "routeId": "tavily.default",
      "credentialProfile": "default",
      "status": "success",
      "resultCount": 5
    }
  ],
  "resultStatus": "success",
  "retrievalSucceeded": true,
  "usableForReview": true
}

这样一次搜索不只告诉调用者"最后谁成功了",还还原了整条执行路径。

缓存命中也会明确返回:

1

cacheHit: true

并保持和实时调用一致的主要字段,避免调用者因为结果来自缓存而拿到另一套残缺结构。

3.6 发布包不只验证源码,而是验证真实安装路径

项目通过 tsup 同时输出:

1
2
3

ESM
CommonJS
TypeScript declarations

发布前不仅执行源码测试,还验证:

1
2
3
4
5
6
7

ESM import
CJS require
typecheck
build
npm pack
packaged CLI
MCP handshake

v0.4.0 发布前完成:

1
2
3

196 tests
8 packaged smoke tests
0 failures

这些测试覆盖了真实行为：

• 空结果会继续 fallback；
• timeout 会真正 abort；
• race winner 会取消 loser；
• attempts 顺序稳定；
• breaker 自定义配置真实生效；
• cache hit 返回完整结构；
• ESM/CJS 包可以真实加载；
• 打包后的 CLI 和 MCP Server 可以启动；
• 多凭据 route 能被 MCP 正确读取。

4. v0.4.0:从"多个 Provider"走向"多个凭据、统一 CLI 与 MCP"

到了 v0.4.0，问题从"Provider A 挂了切换 Provider B"变成了更贴近实际使用的场景：

1
2
3
4

同一个 Provider 可能有多个合法凭据；
多个 Agent Host 需要共享同一个搜索入口；
用户不应该手工修改 JSON 才能配置；
环境变量、文件凭据和无 Key Provider 应该共存。

因此,配置模型从:

1

Provider

升级为:

1
2
3

Provider Definition
→ Credential Profile
→ Provider Route

例如:

1
2
3
4

tavily.default
tavily.backup-2
gemini.default
duckduckgo

4.1 两层故障决策:credential failover 与 provider fallback

v0.4.0 明确区分两层切换。

第一层是同一 Provider 内的凭据切换:

1
2

tavily.default
→ tavily.backup-2

第二层是 Provider 级 fallback:

1
2
3

tavily.*
→ gemini.*
→ duckduckgo

规则如下:

这里有一个刻意的限制:

默认实现 failover,不做 round-robin。

多个凭据的目的是备用、合法的团队 workspace、Key rotation 和故障隔离,不是让系统无条件在不同账号之间轮询消耗额度。

4.2 循环式 Setup Wizard

v0.3.0 的 rws setup 只能选择一个 Provider、输入一个 Key,然后结束。v0.4.0 改成循环式流程:

1
2
3
4
5
6
7

添加 Provider
→ 添加凭据
→ 继续添加同 Provider 凭据
→ 添加其他 Provider
→ 查看和调整路由
→ 完成配置
→ 检测 Agent Host

使用方式:

1
2

npm install --global reliable-web-search
rws setup

在 macOS 或 Linux 上,如果系统全局目录无写权限,可以安装到用户目录:

1
2
3

npm install --global \
  --prefix "$HOME/.local" \
  reliable-web-search

再把下面路径加入 PATH:

1

export PATH="$HOME/.local/bin:$PATH"

不需要使用:

1

sudo npm install -g

向导能够连续添加:

1
2
3
4

tavily.default
tavily.backup-2
gemini.default
duckduckgo

并在最终确认路由后,检测 OpenClaw、Codex、Claude Code 或 Generic MCP 环境。

4.3 CLI 管理能力

除了 setup,v0.4.0 还提供独立管理命令:

1
2
3
4
5

rws credentials list
rws credentials add tavily --label backup
rws credentials remove tavily.backup
rws credentials enable tavily.backup
rws credentials disable tavily.backup

1
2
3
4

rws routes list
rws routes move tavily.backup --before gemini.default
rws routes enable tavily.backup
rws routes disable tavily.backup

诊断命令:

1
2
3

rws doctor
rws doctor --live
rws doctor --live --all-credentials

其中:

1
2
3
4
5
6
7
8

doctor
= 检查配置、凭据引用、路由完整性和宿主环境

doctor --live
= 验证每个 Provider 的首选 credential

doctor --live --all-credentials
= 明确警告后逐个发起真实请求

最后一个命令会消耗每个凭据的真实额度,因此不应作为日常检查默认执行。

4.4 环境变量成为不落盘的临时路由

如果环境中存在:

1

export TAVILY_API_KEY="..."

系统自动产生一个高优先级路由 tavily.env。它有这些特征:不写入 config.json,不写入 credentials.json,删除环境变量后自动消失,与本地相同 Key 去重,routes list 中标记为 [env],不能通过 credentials remove 删除。

CI、服务器和临时开发环境可以直接注入 Key,无需改写本地凭据文件。

4.5 凭据与配置分离

v0.4.0 将数据分开保存:config.json 放 routes、优先级、启停状态等非敏感配置;credentials.json 放 credential profiles 和 API Key。

安全约束包括:Unix 下 credentials.json 权限为 0600;API Key 不进入 Host MCP 配置、AttemptRecord、stdout、日志或诊断输出;setup 和 doctor 只显示 label 或掩码;v1 → v2 迁移会创建备份;损坏文件不会被自动覆盖。

4.6 一个工具接入多个 Agent Host

v0.3.0 开始,项目提供 stdio MCP Server:

1

rws mcp

Agent Host 只需要注册:

1
2
3
4

{
  "command": "/path/to/rws",
  "args": ["mcp"]
}

当前支持状态为:

对 Agent 来说,始终只看到一个搜索工具:

1

reliable_web_search

底下配置了多少 Provider、多少凭据、是否发生 fallback,Agent 不需要关心具体接入细节,只需要读取结构化结果。

在 OpenClaw 实机验证中,新版 MCP 工具最终返回:

1
2
3
4

providerPath: ["tavily.default"]
routeId: tavily.default
status: success
credentialProfile: default

这也暴露过一个迁移问题:旧版 OpenClaw 本地插件仍然注册了同名工具,导致模型先调用旧 Gemini 路由,再调用新版 MCP。最终通过禁用旧 0.1.0 插件、保留 rws mcp 注册,才让 OpenClaw 只剩新版工具。

这件事再次证明:

工具发现、工具命名和运行时所有权,同样属于可靠性边界。

5. 这套系统解决了什么,又仍然没有解决什么

从原型到 SDK,项目经历了三次明显变化。

原型之前

1
2
3
4
5
6
7
8

搜索成功
→ 返回结果

搜索失败
→ 原因不清楚
→ Agent 自己推断
→ 可能重试
→ 可能直接回答

OpenClaw Runtime Gate

1
2
3
4
5
6
7
8

Agent
→ 参数清洗
→ Gemini / Tavily
→ 错误分类
→ 有限重试与 fallback
→ 标准化输出
→ JSONL
→ Evidence Review

当前通用运行时

1
2
3
4
5
6
7
8
9
10

Application / Agent
→ Provider detection and priority
→ Credential-aware routes
→ Abortable timeout
→ Retry / credential failover / provider fallback
→ Race / aggregate
→ Circuit breaker
→ Result quality gate
→ Stable attempt diagnostics
→ CLI / MCP / SDK

可以将这次演化总结为:

它仍然没有解决所有搜索问题。

当前版本还没有跨 Provider URL canonicalization、复杂重复结果融合、相关性重排序、域名多样性控制、round-robin 或健康权重、完整用量统计与成本预算、云端凭据管理、Web UI、通用 telemetry hooks。

这些能力都有价值,但不需要一次性全部实现。更合理的顺序是发布、实际使用、观察真实故障、根据数据决定下一步。

出现重复链接再做融合。多个 Agent 互相污染再引入更强实例隔离。费用失控再加预算治理。真实用户确实需要 GUI 再考虑 Web UI。

可靠系统不等于功能最多的系统,而是承诺过的行为都能被测试证明。

最后真正学到的东西

最消耗精力的不是写代码,是判断问题出在哪一层:

1
2
3
4
5
6
7
8
9

代码错误?
配置错误?
Provider API 变化?
Runtime 没有加载新构建?
本地代理退出?
请求被限流?
响应 envelope 改变?
旧插件和新 MCP 同时存在?
旧日志和新日志混在一起?

有几次看起来像"刚修好又坏了"。

一次是旧的 transport_failure 和新成功记录同时出现在 tail 里。一次是 wrapper 检查错了对象层级。一次是关代理窗口时顺手退出了后台进程。还有一次,新版 MCP 已经正常工作,但旧 OpenClaw 插件仍在抢占同名工具。

这些经历让我越来越确信:Agent 工程的核心不只是模型能不能完成任务,而是系统能不能准确描述自己当前的状态。

一个可靠的 Agent 不能只有"成功"和"失败"两种答案。

它至少应该知道这些:

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

请求到底发出去了没有?
发给了谁?
使用了哪个 route 和 credential profile?
响应结构是什么?
系统是否读懂了响应?
失败发生在哪一层?
这个错误是否值得重试?
要不要换凭据?
要不要换 Provider?
底层请求到底停了没有?
当前结果能不能进入证据审查?
整个过程是否留下了可追踪记录?

这些问题都有明确答案,Agent 才开始从一个聊天界面变成一个可被信任的系统。

结语

开头只是想修好 OpenClaw 的联网搜索。

过程中绕过了代理、Tool Policy、插件加载、Runtime envelope、Provider 参数、重试循环、fallback、日志路径、Agent 权限、CLI 安装、MCP 注册和旧工具冲突。后来又把这些抽象成 registry、结构化错误、真实取消、race、熔断器、多凭据路由、稳定诊断和统一 Host 接入,最终发布成独立的 reliable-web-search。

回头看,真正建起来的不是"永远不会失败的搜索工具":

1
2
3
4
5
6

一个 Agent 绕不过去的治理入口
一套能准确描述故障的状态语义
一个超时后不会偷跑资源的执行层
一条能根据错误选择 retry、credential failover、provider fallback 或停止的路由
一份能回溯每次 Provider 尝试的诊断记录
一个可以通过 CLI、MCP 和 SDK 复用的统一接口

可靠性从来不是消灭失败。

可靠性是让失败拥有明确的类型、边界、证据和后续动作;让系统知道自己没拿到什么,也知道什么时候不该继续假装成功。

至少现在,某一个 Provider、某一把 Key,甚至某一条网络路径挂掉,都不再意味着整条搜索链路走到终点。

leecdiang/reliable-web-search

Abstract
This post is not a tutorial on building an agent. It is a reflection on turning AI from a chat interface into a personal workflow system. Through the deployment of Main Agent, Code Lab, evidence tracking, approval queues, validators, and Obsidian dashboards, I gradually realized that the real value of an agent is not full automation, but structured collaboration. A useful agent does not replace human judgment; it participates in a workflow where facts are traceable, decisions are explicit, and failures can be detected.

这不是一篇教程。

我不想把这次部署包装成某种一键复刻的效率神话。如果只看最后的成品，它看起来很像一个"AI 留学助手" : 它会晨检，会查学校，会整理 deadline，会同步 Obsidian，还会把待审批事项写进 Mac 备忘录等等等。

但这次部署真正让我开心的，是我第一次比较完整地把一个 AI 工具放进了自己的长期工作流。它更像一个被约束、拆分、审计、校验、可视化之后的工作台，而不是一个能检索的聊天窗口。

回头看，这次我做的事情可以概括成一句话:

我搭的不是 Agent，而是一套工作方式

这套工作方式的核心是让 AI 参与我的长期任务: 它搜索、整理、生成候选项、提醒我、维护文件。但必须留下证据，接受校验，走审批流，也得承认失败——不能因为"看起来完成了"就被我信任。

这篇文章就是这次部署的复盘。

1. 我不是在搭一个留学 Agent，而是在搭一个个人工作台

我确实有一个很具体的需求: 我正在准备未来的留学申请，需要管理学校列表、项目要求、APS、IELTS、GRE、推荐人、材料时间线、CV 和 SOP 等一堆东西。

这类任务麻烦在它不是一次性问答。

问"某个学校的 GRE 要不要交"，AI 很容易给出一个看起来有用的回答。但留学申请真正麻烦的地方在于这些答案会不断变化、互相关联，还会影响后续决策。

deadline 可能变，语言要求可能和学院要求不一样，官方页面可能更新，APS 审核政策可能有新程序。你的背景也会随着实习、项目、成绩、竞赛而变化。这些信息最终要进入一个长期决策系统: 哪些学校是 Reach，哪些是 Target，哪些是 Safety; 哪些信息已经核验，哪些只是低置信度; 哪些需要马上行动，哪些只是以后再看。

所以我慢慢意识到，除了尽早摆脱 Gemini 网页版等对话聊天助手，我需要一个能承载长期任务的个人工作台，而不是一个能回答留学问题的 Agent。选择转向 agent 的一大原因是最近被 Gemini 气的不行，觉得它的能力和效率满足不了我的需求。

这个工作台后来长成了这样的结构:

graph TD    A[Personal Workbench]    A --> B[Agent Layer]    B --> B1[Main Agent]    B1 --> B1a[长期规划 / 晨检 / 审批]    B1 --> B1b[策略 / 资料库维护]    B --> B2[Code Lab]    B2 --> B2a[代码 / 脚本 / Validator]    B2 --> B2b[Obsidian 生成逻辑]    A --> C[Evidence Layer]    C --> C1[source]    C --> C2[run]    C --> C3[claim]    C --> C4[approval]    A --> D[Control Layer]    D --> D1[Validator]    D1 --> D1a[检查格式 / 语义]    D1 --> D1b[生成文件健康状态]    A --> E[View Layer]    E --> E1[Obsidian / 可视化看板]    E --> E2[Mac 备忘录 / 轻提醒副本]    A --> F[Source of Truth]    F --> F1[OpenClaw Workspace]    F1 --> F1a[事实源 / 正式记录]

1
2
3
4
5
6
7
8
9

System Structure

Main Agent:长期规划、晨检、审批、策略、资料库维护
Code Lab:代码项目、脚本、validator、Obsidian 生成逻辑
Evidence Layer:source → run → claim → approval
Validator:检查格式、语义和生成文件健康状态
Obsidian:可视化看板
Mac 备忘录:轻提醒副本
OpenClaw workspace:事实源

留学只是第一个被跑通的场景。更大的目标是: 把 AI 放进我的工程、学习、毕业设计、博客、申请这些长期任务之间，让它成为一个稳定的工作流节点，而不是一个随时失忆、随时飘走的聊天框。

2. 为什么一个 Agent 不够:Main Agent 与 Code Lab 的分工

为了在一开始确立正确的系统架构，我参考了两篇关于 single-agent 与 multi-agent 的论文，它们直接影响了我对这套系统的设计判断。

论文一:When Single-Agent with Skills Replace Multi-Agent Systems and When They Fail
arXiv: https://arxiv.org/abs/2601.04748

这篇论文的核心是如果一个 multi-agent system 里的多个 agent 只是承担不同角色，并通过显式通信协作，那么这些角色可以被编译成一个 single-agent 内部可调用的多个 skills。论文的结论是: 在共享上下文、同一模型 backbone、任务流程可以序列化的情况下，single-agent with skills 往往可以用更低的 token、延迟和 API 调用成本，达到接近甚至相当的效果。但它也指出，skill library 不能无限扩张; 当 skills 数量过多，尤其是语义相似时，模型的 skill selection 会出现明显退化。论文中这个分界点大概在 20 个 skills，但具体分界点与不同 skill 易混淆程度和是否采用了正确的 skills 路由器有关。

论文二:Single-Agent LLMs Outperform Multi-Agent Systems on Multi-Hop Reasoning Under Equal Thinking Token Budgets
arXiv: https://arxiv.org/abs/2604.02460

这篇论文的核心观点是: 很多 multi-agent 系统看起来更强，可能只是因为它用了更多 test-time compute。多个 agent 轮流发言、互相总结、互相修正，本质上消耗了更多 thinking tokens、更多上下文传递和更多中间推理。当把 reasoning-token budget 控制到相同水平时，single-agent 在多跳推理任务中经常可以匹配甚至超过 multi-agent。这说明，multi-agent 的优势不应被默认归因于"架构更聪明"，而要先排除计算预算、上下文组织和通信开销带来的影响。

这两篇论文放在一起，给了我一个部署原则:不要因为多 agent 看起来很厉害，就把系统拆成很多 agent。

一开始我想的是：做一个留学 Agent、一个芯片 Agent、一个代码 Agent、一个博客 Agent。后面再按需部署更多。这种拆法按主题划分: 留学一类，数字 IC 一类，代码一类，博客一类。

但真正开始设计后我发现，这样切得太碎。

主题不是最重要的边界，职责才是。

按主题拆的话，"博客 Agent"既要写作、改 Hexo 主题、还要管理 Git; “留学 Agent” 既要做长期规划、搜索资料、整理文档、甚至改本地文件; “芯片 Agent” 既要讲知识，又要参与毕业设计文档管理。每个 agent 都要参与太多杂事，边界反而更模糊。

论文里关于 single-agent with skills 的观点解释了这个问题: 如果多个 agent 之间没有真正独立的状态、权限、工具链或决策目标，只是换几个角色说同一套话，那它们未必需要被拆开。很多时候让一个 agent 拥有少量边界清晰的 skills，比让一组 agent 互相转述上下文更合理。

但另一方面，我也没有让一个 Agent 什么都做。

因为在真实部署中，问题不只是推理能力，还有权限、风险和执行边界。一个负责长期规划和记忆的 agent，不应该同时拥有随手改代码、执行 shell、重写配置文件的能力。否则它一旦理解错上下文，就可能把策略判断和工程执行混在一起，造成很难追踪的副作用。

所以我最后没有按照主题拆分，而是按照职责和风险拆分。系统收敛成两个常驻角色:

1
2

Main Agent = 长期规划 / 策略 / 资料库 / 记忆 / 决策支持
Code Lab = 工程执行 / 脚本 / 测试 / 本地工具维护

Main Agent 是长期工作流中枢。它负责帮我理解目标、拆分路径、维护资料库、生成待办、管理审批。它可以处理留学规划、数字 IC 学习、毕业设计、实习项目分析、长期资料归档。它的价值在于"想清楚"和"记下来"。

更准确地说，Main Agent 承担的是 规划层、解释层和记忆层 的工作。它应该帮我回答:

1
2
3
4
5

这个目标应该怎么拆？
哪些信息值得长期保存？
哪些任务应该交给 Code Lab 执行？
哪些决策需要我本人确认？
哪些资料还只是草稿，不能写入正式记录？

但 Main Agent 不应该直接动工程。它不应该递归扫描代码仓库，不应该重写脚本，不应该随手改项目文件，也不应该把未经审批的信息写进正式资料库。它更像一个 PM、研究助理和长期笔记管理员的结合体。它可以提出方案、生成任务单、记录决策，但不应该越过边界直接执行危险操作。

Code Lab 则是工程执行器。它负责 Apple-Health-Pro、Hexo 博客、Obsidian 同步脚本、validator、CSS、Git、测试和本地 shell。它可以改文件，可以跑命令，可以调试，可以修脚本。它的价值在于能够把明确的工程任务做完，并留下可验证的证据。

Code Lab 应该回答的是另一组问题:

1
2
3
4
5
6
7

当前 Git 状态是什么？
测试是否通过？
哪个脚本失败了？
改了哪些文件？
diff 是否最小？
能否复现问题？
是否需要回滚？

但 Code Lab 不应该替我做留学策略判断，也不应该把"信息判断"直接写成"正式事实"。它可以执行 Main Agent 派发的工程任务，也可以把执行结果反馈回来，但它不应该直接决定我的 APS 路线、学校优先级、申请策略或长期学习方向。

这层分工听起来有点形式主义，但它其实非常关键。

如果 Main Agent 同时负责策略判断和脚本维护，它会变成一个不受控的"万能助手"。它可能在晨检失败时顺手重写脚本，也可能在理解错上下文时污染正式文件。如果 Code Lab 也开始替我判断 APS 路线、学校优先级、申请策略，那代码执行和人生决策就混在一起了。

从 agent 架构角度看，这里需要隔离的是权限和风险，而不是"知识领域":

1
2
3

上下文隔离：长期规划和工程执行的上下文不要互相污染。
权限隔离：能做策略判断的 agent，不必有本地执行权限。
风险隔离：低风险的信息整理和高风险的文件修改，应该在不同边界里。

这也是我最后没继续拆出"留学 Agent / 芯片 Agent / 博客 Agent"的原因。留学、芯片、博客这些主题，完全可以作为 Main Agent 内部的长期 skill 或资料库; 代码修改、脚本调试、Git 操作、本地测试这些，交给 Code Lab。前者是认知和记忆问题，后者是工程和执行问题。

最后我的结论是:

一个 Agent 不够，是因为不同职责需要边界;
太多 Agent 也不好，因为过度拆分制造通信成本、上下文损耗和选择混乱。

Agent 越强，越需要边界。
分工不是为了复杂，而是为了降低混乱。

对我来说，Main Agent 和 Code Lab 的分工刚好卡在中间。Main Agent 负责长期记忆、策略判断和任务分解;Code Lab 负责本地工程、代码修改和测试验证。按权限、风险和职责隔离，而不是按主题分裂。

3. 为什么光有记忆不够: 事实源、证据链和审批流

AI 的"记忆"很诱人——它似乎可以记住背景、偏好、项目、学校列表和长期目标。但在长期任务里，记忆不能当事实源。

它能提供上下文，但不能直接作为依据。它记得我说过"Purdue GRE 可能 optional"，但不能因为记得，就把这条写进正式 tracker。事实必须有来源、有时间、有置信度、有核验日期、有变更记录。

所以我们建立了一层 evidence layer，由四个 JSONL 文件构成:

1
2
3
4

source_registry.jsonl
retrieval_runs.jsonl
fact_claims.jsonl
approval_queue.jsonl

source_registry.jsonl 记录来源本身:URL、标题、来源类型、检索时间、置信度。一个来源是官方页面、论坛帖子、项目手册还是非正式总结，意义完全不同。

retrieval_runs.jsonl 记录每次查了什么:query 是什么，用了什么工具，目的是什么，结论是什么。这解决的是"我到底有没有查过"这个问题。

fact_claims.jsonl 记录具体事实声明。比如某个项目 GRE optional、某个项目 IELTS writing 要求、某个 deadline 是估算还是官方确认。它把"资料"拆成可追溯的 claim。

approval_queue.jsonl 记录这些信息是否需要我介入。确认某条信息无变化时用 no_action_required。需要我行动是 pending。信息不足是 needs_more_research。路线选择——比如 APS 走 TestAS 还是标准面谈——是 decision_item，必须等我明确选。

第一次测试 Purdue GRE 政策时，Main Agent 口头说已经记录了 retrieval run、注册了 source、生成了 claim、写入了 approval queue。但 validator 一跑，四个 JSONL 文件全是空的。

如果没有 evidence layer，我可能以为晨检成功了。实际上它只更新了 human-readable summary，没形成机器可读的审计记录。这就是为什么后来所有晨检必须写入 JSONL。

还有一次，approval_queue 里本来要写"核验无变化，无需审批"，但 validator 不接受 no_action_required。Agent 为了让 validator PASS，改成了 rejected。

技术上通过了，语义上错了。

这说明 validator 不能只检查格式，还要保护语义。rejected 只能表示我明确拒绝，不能代替"无需改动"。否则以后复盘，系统会以为我拒绝过某个事实更新。

于是我们补齐了 status 语义:

1
2
3
4
5
6

pending - 等待我审批
approved - 我已批准,但尚未应用
applied - 已写入正式 tracker / checklist / timeline
rejected - 只有我明确拒绝时使用
needs_more_research - 信息不足,不能写入正式 tracker
no_action_required - 核验无变化,无需人工审批

AI 可以发现问题，但不能替我承担选择。
它可以生成 action item，但 decision item 必须留给我。
它可以干活，但必须留下证据。

4. 为什么光有 UI 不够:Obsidian 只是视图，不是系统本体

这次部署里，Obsidian 是很重要的一环。它让整个系统终于"看得见"。

我最终有了这些页面:

1
2
3
4
5
6

Dashboard - Overview
Dashboard - Timeline
Dashboard - By Tier
Dashboard - Pending Approval
Board - Application Status
Schools/

Overview 是总控台，告诉我当前阶段、待审批、时间压力和下一步重点。Timeline 看 deadline 和时间顺序。By Tier 看选校梯度。Pending Approval 看待我确认的事项。Kanban 看申请流程状态:Research、Needs Verification、Shortlist、Preparing、Applying、Submitted、Archived。Schools 下面则是每个项目的单独页面。

现在我的理解:

• Timeline 看时间压力
• Kanban 看流程状态
• By Tier 看选校结构
• Overview 看今天该做什么
• Pending Approval 看等待我决定的事

别把所有信息塞进一个页面，也别幻想一个 Dashboard 解决所有问题。

更重要的是，Obsidian 不是事实源。

这点非常关键。Obsidian 再漂亮，也只是生成视图。Mac 备忘录再方便，也只是提醒副本。真正的事实源在 OpenClaw workspace 里，在 CSV、Markdown、JSONL、approval log、change log 里。

这层分离很重要，因为 UI 很容易让人产生错觉。一个页面看起来很完整，不代表系统可靠。一个看板颜色很漂亮，不代表背后的数据经过核验。一个学校卡片里有 deadline，不代表这个 deadline 一定来自官方来源。

所以我的原则变成:

1
2
3
4

OpenClaw workspace = 事实源
Obsidian = 可视化看板 / 阅读副本
Mac Notes = 轻提醒副本
Excel/CSV = 结构化数据和快照

我可以在 Obsidian 里理解系统，但不应该绕过系统直接改事实。下一次同步时，这些手动修改也可能被覆盖。

一个好看的 Dashboard 不等于一个可靠的系统。
Dashboard 只是仪表，事实源才是本体。

5. 为什么模型不够聪明也能用: 用 validator、脚本和流程约束模型

这次部署让我对模型能力有了更真实的感受。先对比下各家当前的 api 价格。

DeepSeek V4 Flash 便宜、快、上下文长、日常可用，但在复杂 agent 工作流里并不省心，经常要多改几次。没有多模态能力，所以识图、记忆检索、联网搜索等场景我接入了 Gemini 的 api，免费额度在这些场景基本用不完。

对于 DeepSeek，尤其是当任务变成多步骤执行时，它会犯一些经典错误:

1
2
3
4
5
6

口头说完成，但实际没写 JSONL
工具报错后仍然汇报"写入完成"
把 rejected 当成 no_action_required
忘记脚本路径
用 fragile exact oldText 替换文件，结果失败
同步看板时写出 \n 或 \u000 这类转义污染

模型能力不够强，所以系统必须足够完善来包容这些不完美。

以 DAILY_BRIEF.md 的更新逻辑为例：

开始时，Main Agent 用精确文本替换更新每日简报:

1

edit(oldText=..., newText=...)

这个方式鲁棒性很弱：日期、空格、emoji、换行，有一点点不同就失败。实际也确实失败了——它以为文件里是 2026-06-11 的版本，真实文件还是 2026-06-09 的，oldText 匹配不上。更糟的是，工具已经报错，它还是口头说"写入完成"。

后来我们把它改成 marker-based update:

1
2
3

<!-- DAILY_BRIEF:BEGIN -->
这里是最新晨检摘要
<!-- DAILY_BRIEF:END -->

然后写了 update_daily_brief.py，以后只替换 marker 之间的内容。更新后必须读取前 80 行确认，确认成功后才能汇报完成。

类似的防线还有 validator。它检查 JSONL 格式、字段是否完整、status 是否符合语义、Obsidian 生成文件是否有坏转义、Kanban 是否出现错误列、学校页面 frontmatter 是否包含必要字段。不是为了显得高级，而是防止 Agent 口头完成、实际失败。

当模型不够可靠时，不要要求它"更自觉"。
要把它放进流程里，让它必须留下证据，必须通过校验，必须承认失败。

6. 留学申请只是第一个被跑通的场景

虽然这次最完整跑通的是留学申请，但我不想把这套系统定义成"留学 Agent"。

留学只是一个足够复杂、真实、容易出错的验证场景。有信息检索、官方来源、时间线、材料清单、个人决策、审批、可视化、长期维护。用它来测试这套工作流，很合适。

最后我们把"执行留学晨检"固化成了一个 skill。它不再是一个模糊指令，而是一套明确的 11 步工作流:

1
2
3
4
5
6
7
8
9
10
11

写入 retrieval_runs.jsonl
写入 source_registry.jsonl
写入 fact_claims.jsonl
写入 approval_queue.jsonl
用 update_daily_brief.py 更新 DAILY_BRIEF.md
读取前 80 行确认
更新 PENDING_APPROVAL.md
跑 validator
同步 Mac 备忘录
同步 Obsidian
汇报全部结果

而且我们明确规定:SCHOOL_LIST 只读不改，除非我专门审批通过。validator FAIL 必须修复，不能跳过。脚本路径固定，Main Agent 只调用，不重写。rejected 只能表示我明确拒绝，no_action_required 才表示核验无变化。

这套流程后来跑通了几个真实测试:

• Purdue GRE policy: 核验无变化，进入 no_action_required。

• Purdue IELTS 小分: 确认 W6.0 / S6.0 满足要求，写入 evidence。

• APS 审核: 生成了 action_item 和 decision_item。比如材料清单需要补充，TestAS 060 vs 标准面谈则需要我自己决策。

这证明系统能处理"无变化的事实核验"，也能处理"需要行动"和"需要决策"的事项。

但它真正的意义不在于 Purdue，也不在于 APS。意义在于: 这套工作流可以迁移。

它以后可以服务我的工程项目，可以服务毕业设计，可以服务数字 IC 学习路径，可以服务博客内容管理，也可以服务实习项目分析。留学申请只是第一块被跑通的样板间。

7. 接下来它会服务工程、博客、毕业设计和长期学习

现在系统基本成型，我反而应该少折腾、多使用。

这也是这次部署最后一个重要结论。

系统搭到一定程度后容易陷入另一种陷阱: 继续加功能，继续调 UI，想接飞书、Telegram、iMessage、日历插件、全自动监控、更多 Agent、更多 Dashboard。每个功能看起来都合理，但也会把精力从真正的工作上带走。

现在我更愿意把这套系统看成一个阶段性可用的工作台。接下来它要服务具体产出。

在工程上，Code Lab 会继续维护 Apple-Health-Pro、Hexo 博客和各种同步脚本。规则也很明确: 先 git status，不要递归扫描，每轮最多读几个文件、跑几条命令，小步修改，小步提交。Code Lab 是工程执行器，不是人生规划师。

在留学上，Main Agent 会继续按 evidence-first workflow 执行晨检。它要关注 APS、推荐人、High priority 项目、IELTS/GRE/deadline 核验、CV_FACTS、SOP 主线等。但它不能越过审批流。

在毕业设计和学习上，Main Agent 更适合做长期路径规划和资料整理。比如数字 IC 学习路线、实习项目理解、毕业设计拆解，这些应该变成长期资料库和阶段性决策，而不是一次性问答。

在博客上，这套系统也会继续有用。Code Lab 可以维护 Hexo 和样式，Main Agent 可以帮我梳理文章结构、复盘经验、保存主题线索。但最终表达仍然是我的。

我现在对这套系统的理想使用方式是:

1
2
3
4
5

Main Agent：帮我想清楚、记下来、形成决策流
Code Lab：帮我做出来、跑起来、修到稳定
Obsidian：让我看见
Evidence Layer：让一切有迹可循
Validator：让错误尽早暴露

这不是什么"全自动 AI 人生操作系统"。它更像一套被我慢慢磨出来的个人工作方式。

结尾: 把 AI 放回工作流里

回头看，这次部署让我最开心的是：我终于把 AI 放回了工作流里，而不是只"拥有了一个 Agent"。

以前我对 AI 工具的使用，更多是对话式的: 我问，它答; 我再问，它再答。这个模式很轻，很快，也很有用。但它不适合承载长期任务。长期任务需要状态，需要边界，需要历史，需要审计，需要可视化，需要失败处理，也需要人的决策位置。

现在这套系统仍然不完美。模型会犯错，脚本可能出 bug，Obsidian 看板以后也许还会坏，Main Agent 也可能偶尔忘记规则。但不同的是，错误不再完全漂浮在聊天里——它们会被 validator 发现，被 approval queue 拦住，被 evidence layer 留痕，被 Code Lab 修复。

我对 Agent 的理解也变得更具体了。

Agent 是我能组织进流程的执行者，不是一个替我生活的东西或永远正确的答案机器。它很有用，但我得知道什么该交给它、什么必须留给我。

让 AI 参与我的长期任务，但不让它越过边界;
让它替我处理重复劳动，但不替我承担判断;
让它生成信息，但必须留下证据;
让它执行流程，但必须接受校验。

如果你的部署遇到什么问题，可以写邮件给我，我们一起解决。

TL;DR

I was building a workflow, not a single agent.

The key: keep AI accountable rather than just autonomous.
Separate planning from execution, keep evidence trails, add approval gates, validate outputs, treat dashboards as views—not sources of truth.

A useful agent is one that can safely participate in my long-term work, not one that does everything for me.

在购入这台macbook air m4的时候选择了15寸 + 24g RAM + 256g SSD的配置，国补+教育优惠叠加后的价格是8700左右，本以为256的存储用到过保再扩容绰绰有余，甚至也许可以外接硬盘一直用下去；但仅过了半年就容量告紧，遂决定扩容。

Part 1: 选择第三方扩容？

由于苹果的高昂存储价格，第三方扩容性价比高的多，但25年AI采购导致内存、存储芯片涨价严重，这次第三方扩容花费1300元.

这次选择在【万维创芯】这家工作室扩容，因为这是我在b站看到的唯一一家扩容后使用BGA专用基底填充胶水的商家；

Underfill底部填充胶的材料通常使用环氧树脂(Epoxy)，它利用毛细作用原理把Epoxy涂抹在晶片的边缘让其渗透到覆晶晶片或BGA的底部，然后加热予以固化(cured)，它填充封装和印刷电路板 (PCB) 之间的间隙，提供机械支撑和应力释放，以防止热膨胀和收缩损坏。 底部填充环氧树脂还可以通过降低寄生电感和电容来提高封装的电气性能。

在【万维创芯】的早期b站视频中可见，使用的并非Underfill胶水而是光固化UV胶，仅能为存储芯片四周封边，无法渗透进入焊盘，因此抗跌落和热膨胀性能差，这也是我之前未选择扩容的原因。

Part 2: 扩容过程记录

1. 数据备份：使用“时间机器”(Time Machine) 将整个系统完整备份到了我的移动硬盘上。（需要格式硬盘为APFS格式）

2. 拆机与操作：全程大概三小时，过程为拆下主板-热风枪吹下旧硬盘-清理焊盘-植中温锡-焊接新硬盘-测试-封胶-装机

3. 数据恢复：扩容完成后，从“时间机器”备份中恢复数据。开机后，一切都和送修前一样，只是存储空间变成了 1TB。

Part 3: 性能实测

扩容后，除了容量变大，硬盘的读写速度也是我非常关心的一点。我使用了 Blackmagic Disk Speed Test 这款软件，对扩容后的硬盘进行了测速。

对比扩容前稍高，但算不上显著（扩容前在读写3000左右）

通常来说，大容量的 SSD 因为有更多的闪存通道，读写速度可能会比小容量的更快。

总结：值吗？

我认为是值得的。

现在，我可以毫无顾忌地导入我的摄影原片、安装大型软件、创建虚拟机。

采用了正确的扩容工艺也让我更加放心地使用

优点：

• 性价比高：用远低于官方的价格，获得了四倍的存储空间。

• 体验无缝：通过时间机器恢复后，系统和数据都和原来一样，没有任何不适感。

• 性能提升：获得了更快的读写速度。

潜在风险：

• 保修：影响官方保修，二手不好卖，可能存在的虚焊掉盘。

如果你也像我一样，正在被 256GB 的存储空间所困扰，并且愿意承担一定的保修风险，那么正确的第三方扩容是一个值得考虑的选择。

希望我的这次经历能给你带来一些参考。