DEV Community: goodlords

I built a local-first membership app for one-chair hair salons

goodlords — Fri, 06 Nov 2026 06:37:03 +0000

Small salons do not need a heavy SaaS checkout stack.

They need three things that actually stick:

Find a customer by name in seconds
Deduct a visit or top up a card right after the cut
See tonight’s real cash vs bonus credit in one place

Notebooks break when two people write on the same page. WeChat / Alipay history proves money moved — it does not tell you whose card still has balance.

Meet Lao Lv Salon Member

I shipped a tiny Android app for that job.

Data stays on the phone (no account signup)
Search → balance → deduct / recharge
“Today’s business” summary for closing the shop
Works offline

Here is a short Chinese-subtitled walkthrough (about 17 seconds):

Try it

Landing + free trial download:

https://hairsalon-ayn.pages.dev/

APK installs without an account. Use it for a while; if it fits the chair, keep going. Pricing for a continued license is listed inside the app.

Who it is (and is not) for

Good fit: one-chair / couple-run shops that want a simple on-device ledger.

Not a fit: multi-store chains that need HQ reports and shared cloud inventory — pick a real salon SaaS for that.

Feedback welcome

If you run (or build for) tiny local service shops, I would love notes on what still hurts after a week of use — search, deduct flow, backup, or closing summary.

Thanks for watching the clip.

从零手写 Agent（七）：和商用 Agent 还差什么——个人调研 Agent 的边界

goodlords — Thu, 22 Oct 2026 09:08:37 +0000

前面几篇已经把一个能实际运行的 Agent 搭起来了：

有 Tool Calling
有 Agent Loop
有上下文管理和裁剪
能联网搜索和抓取网页
能记录 sources
能生成 Markdown 报告并落盘
有本地 Web UI
可以接本地 Ollama，也可以接 OpenAI 兼容的云端模型

作为一个个人调研 Agent，这套东西已经能完成基本任务。

但如果拿它和成熟的商用 Agent 放在一起比较，差距还是比较明显的。

1. 数据能力

现在的 Agent 主要依赖：

普通 Web 搜索
HN / RSS
网页抓取
简单的 HTML 内容提取

商用 Agent 往往还需要处理：

PDF
表格
JavaScript 渲染页面
私有知识库
企业内部数据
专业领域数据源
付费搜索和数据 API

所以第一层差距不是模型，而是数据获取和数据处理能力。

2. 任务规划

现在的 _agent_loop 更接近：

思考
→ 调 Tool
→ 看结果
→ 继续思考
→ 调 Tool
→ ...

对于“搜索几个资料，然后生成报告”这种任务已经够用。

但任务变长以后，就会需要更明确的：

Plan
→ Execute
→ Observe
→ Re-plan
→ Verify
→ Deliver

例如一个复杂调研任务，可能需要拆成多个子任务，并记录哪些已经完成、哪些失败、哪些需要重新执行。

当前版本没有专门的 Planner，也没有持久化的任务状态。

3. 结果可靠性和评估

现在虽然已经记录了 sources，但还没有真正建立完整的结果验证机制。

例如：

搜索成功
≠
找到正确资料

找到资料
≠
引用正确

生成报告
≠
任务完成

当前版本最多可以知道 Agent 调用了哪些 Tool、拿到了哪些来源。

如果要进一步提高可靠性，还需要：

引用 URL 校验
来源去重
来源质量判断
事实与来源对应关系检查
自动评测
回归测试

也就是说，需要从“能跑”进一步走向“可验证”。

4. 模型能力

当前版本可以接本地 7B 模型，也可以切换到 OpenAI 兼容的云端模型。

模型能力会直接影响：

Tool 选择
参数生成
多步任务执行
上下文理解
最终报告质量

特别是任务变复杂以后，小模型更容易出现：

该调用 Tool 的时候不调用

或者：

已经拿到结果，但不知道下一步应该做什么

所以 Agent 能力并不完全由 Loop 决定，模型本身也是整个系统的一部分。

5. 工程和安全

当前版本是本地个人项目，因此很多生产环境必须考虑的问题都没有做。

例如：

用户认证
权限控制
Rate Limit
API Key 管理
成本控制
完整日志和审计
多用户隔离
Tool 权限控制
SSRF 防护
沙箱执行

尤其是加入 fetch_url、Shell、代码执行这类 Tool 后，安全边界会迅速变复杂。

本地 Demo 可以直接访问 URL。

真正的线上 Agent 则不能简单地相信模型给出的 URL。

6. 长任务和状态持久化

现在的 Agent 基本属于：

一次请求
→ 一次执行
→ 一次结果

如果任务运行几十分钟甚至几个小时，就需要考虑：

中途失败怎么办
服务重启怎么办
Tool 超时怎么办
某一步执行失败要不要重试
已经完成的步骤能不能恢复
如何保存中间状态

这时候 Agent 就不再只是一个函数调用，而更接近一个有状态的任务系统。

对照下来

把目前这个 Agent 和商用 Agent 放在一起，差距大致可以归纳成：

能力	当前版本	商用 Agent
Tool Calling	有	有
Agent Loop	有	有
上下文管理	基础	完整
Web 搜索	有	更丰富
数据源	Web / HN / RSS	Web / API / PDF / 私有数据等
引用	有 sources	可验证、可评估
报告生成	有	有
任务规划	基础	多阶段规划
长任务	弱	完整状态管理
失败恢复	基础	重试 / Checkpoint / Recovery
模型	本地 / 云端	通常使用更强模型
评估	无	Eval / Regression
安全	基础	权限 / 沙箱 / SSRF 等
多用户	无	有
成本控制	无	有
审计	基础日志	完整 Trace / Audit

从这个表看，差距其实比较清楚。

Agent Loop 本身并没有那么复杂。

真正拉开差距的，是 Loop 外面的这些东西：数据、状态、规划、验证、评估、安全，以及生产环境的工程能力。

这也是目前这个项目最明确的边界：

它已经是一个能工作的个人调研 Agent，但距离一个稳定、可验证、可运营的商用 Agent，还有一整层工程能力。

到这里，这个系列的代码部分基本就完整了。

从零手写 Agent（六）：云模型 API Key 与网页调研台

goodlords — Thu, 22 Oct 2026 09:07:59 +0000

从零手写 Agent（六）：云模型 API Key 与网页调研台——Loop 仍不变

第五篇把 CLI 调研 Agent 跑通：搜、抓、sources、save。

接下来两件事很自然：

换更强推理 — 本地 7B 写长报告仍吃力，用 OpenAI 兼容云端 API（DeepSeek、OpenAI 等）只改配置，不改 Loop。
把 trace 亮出来 — -v --trace 对开发者够用；给「调研工具」做一个 网页台，逐步看到 Step / Tool / 来源，比盯终端友好。

第六篇就这两块：LLM_* 环境变量 + 薄 FastAPI 壳，核心仍是 _agent_loop。

1. 云端 LLM：还是同一个 Chat Completions

仓库从一开始就用 OpenAI Python SDK 打 Ollama 的 /v1，所以换云模型不是换框架，而是换 base_url + api_key + model 名。

.env 示例（见仓库 .env.example）：

# 本地默认
OLLAMA_BASE_URL=http://localhost:11434/v1
OLLAMA_MODEL=qwen2.5:7b

# 启用云端时（优先于 OLLAMA_*）
LLM_BASE_URL=https://api.deepseek.com/v1
LLM_API_KEY=sk-……
LLM_MODEL=deepseek-chat

config.py 合并为：

LLM_BASE_URL  ← LLM_BASE_URL；或 LLM_PROVIDER=glm 时用智谱端点；否则 OLLAMA_BASE_URL
LLM_MODEL     ← LLM_MODEL；或 glm 默认 glm-4-flash；否则 OLLAMA_MODEL
LLM_API_KEY   ← LLM_API_KEY，或 shell 里的 GLM_API_KEY；都没有则占位 "ollama"

agent/llm.py 的 create_client() 始终 OpenAI(base_url=..., api_key=...)。Tool 定义、messages、trim、save nudge 全不变。

注意：

Key 只放 .env，不要写进博文、不要 commit；发 DEV 时用占位符。
云端按 token 计费；联网 Tool 会把 长网页摘要 送回模型，费用和延迟都会上去 — 与第三篇 trim、Tool 内截断仍然相关。
macOS 代理坑：httpx.Client(trust_env=False) 继续用于 localhost Ollama；云端 HTTPS 一般不受影响。

CLI 启动时会打印：

LLM: deepseek-chat @ https://api.deepseek.com/v1 （API Key 已配置）

2. 为什么单独做网页，而不是再加一个 Tool？

调研 Agent 的「产品感」来自 可观测的多步过程：

Step → 计划调哪些 Tool → 每次 Observation → sources 变长 → 最终答案 / Saved

CLI 的 --trace 已经包含这些信息，但对非终端用户不友好。网页要做的是：

层	职责
Loop（已有）	推理、Tool、state
on_event 回调（新增）	每步向 UI 推送结构化事件
FastAPI + SSE（新增）	HTTP 收问题、流式推事件
静态页（新增）	聊天气泡 + 时间线 + 来源列表

没有为 UI 再写一套 Agent，也没有 LangGraph。

3. Loop 加钩子：`on_event`

在 agent/loop.py 的 _agent_loop 增加可选参数 on_event(kind, data)，例如：

event	含义
`step`	第几轮 LLM
`assistant_tools`	本轮要调用的 Tool 名
`tool_start` / `tool_end`	参数与结果预览
`done`	最终答案 + `sources` 快照

CLI 不传 on_event，行为与以前一致。网页在后台线程里跑 run_agent_state(..., on_event=...)，事件进 queue，由 Server-Sent Events 推到浏览器。

注意： 当前是 同步 Loop + 线程；没有做成 async LLM。对个人本地台足够，公网高并发不是目标。

4. 网页调研台结构

web/
  server.py      # FastAPI：/api/chat（SSE）、/api/config、/api/session
  static/
    index.html   # 布局：左对话、右轨迹+来源
    app.js       # fetch SSE、渲染 timeline
    app.css

会话： 内存里 session_id → AgentState；勾选「多轮」则同一 session 连续 append_user（类似 main.py -i）。
默认单轮： 每次提问 reset state，避免误把上一条任务混进 sources。
绑定： WEB_HOST=127.0.0.1、WEB_PORT=8765，默认只监听本机。

启动：

pip install -r requirements.txt
# .env 配好 LLM_* 或继续用 Ollama
python -m web.server
# 浏览器打开 http://127.0.0.1:8765

页眉会显示当前 LLM 端点（不含 Key）。右侧在 Tool 执行后刷新来源列表，与第五篇 sources 一致。

本机实测（LLM_PROVIDER=glm + 环境变量 GLM_API_KEY，提问「调研一下最新的 ai 新闻」）：模型第 1 轮调用 search_hn，第 2 轮汇总；右侧可见 Step / Tool / 来源 5，与 CLI trace 一致。

5. 和 CLI 怎么选

场景	建议
改 prompt、压测 trim、脚本化	`main.py -v --trace`
演示调研链、给非 CLI 用户试	网页台
7B 本地 + 偶发长报告	本地搜 + 云端 LLM 成稿（同 Loop）
公网部署	尚未做登录、限速、SSRF 加固 — 见第七篇边界

save 仍写 服务端 reports/；网页不会代替 save_markdown，只是更容易看到有没有走到 Saved: 预览。

6. 本机验收

# 智谱（Key 已在 ~/.zshrc 的 GLM_API_KEY 时）
# .env: LLM_PROVIDER=glm  LLM_MODEL=glm-4-flash
source ~/.zshrc
python -m web.server

# 或其它 OpenAI 兼容厂商
# export LLM_BASE_URL=...  export LLM_API_KEY=...

浏览器发一条窄 query，例如：

调研一下最新的 ai 新闻

或：

用 search_hn 列 3 条 AI 相关帖子，中文概括，并列出引用 URL。

右侧应出现 Step → search_hn → 来源增加 → 左侧最终回答。

CLI 对照：

python main.py -v --trace '同上'

7. 收束

换云模型 = 改 LLM_*，Loop / Tool / sources / save 不动。
网页台 = on_event + FastAPI SSE + 静态 UI，可视化同一套调研 Agent。
安全默认 = 本机绑定 + Key 在 .env；上公网前看第七篇。

代码：zealot2002/myagent

《从零手写 Agent（七）：和商用 Agent 还差什么——个人调研 Agent 的边界》——在「能用的 CLI + 网页原型」之上，对照商用能力地图与刻意不做的事。

系列目录：GitHub docs(https://github.com/zealot2002/myagent/blob/main/docs/00-系列导读.md)

从零手写 Agent（五）：调研报告、引用与落盘

goodlords — Thu, 22 Oct 2026 09:07:21 +0000

从零手写 Agent（五）：调研报告、引用与落盘

第四篇之后，Agent 已经能 search → fetch → 多步回答。用户要的往往是另一件事：

写成 Markdown，带上参考资料，保存到 reports/xxx.md。

终端里一段口语摘要不算交付。第五篇在 同一个 _agent_loop 上补落盘和 可核对引用，核心新增：

save_markdown
sources（state + system 注入）
Loop：save nudge / 必要时强制 save_markdown

（仓库里还扩展了 search_hn、fetch_rss，与 search_web 一样会把 URL 收进 sources。）

1. 第四篇之后，还差哪一层？

Web Research 原型：

问题 → search → fetch → answer

调研交付还需要：

层次	目标
结构化正文	摘要 / 发现 / 局限 / 参考文献
可核对引用	URL 来自本轮 Tool 结果，而不是模型「回忆」
落盘	`cat reports/foo.md` 能看到文件

最小链路：

search / fetch / hn / rss
        ↓
组织 Markdown
        ↓
save_markdown
        ↓
reports/*.md

注意： Loop 仍不需要为「报告」单独写一套；变的是 Tool 列表、State 和 prompt。

2. 第一个坑：说了「保存」，磁盘却没有文件

实测里很常见：

用户：保存到 reports/python-313.md
Agent：（长报告）…… 结束
ls reports/   # 空

原因分两层：

（1）没有 save_markdown Tool — 模型只能在对话里「假装保存」，程序写不了盘。

（2）有 Tool，但模型选择不调用 — Tool 注册成功 ≠ 一定会 tool_calls。Loop 在 没有 tool_calls 时直接返回 assistant 正文并退出；不会因为用户说了「保存」就自动写文件。

所以交付要同时做：

提供 save_markdown（真实 IO）
在 prompt 里写清：用户指定路径时必须 save
必要时 Loop save nudge 或 tool_choice 强制 save_markdown 一轮

这和「模型够不够聪明」有关，更是 完成条件写在代码里 的问题。

3. `save_markdown`：沙箱与 Tool 契约

实现要点（细节见仓库 agent/tools/save_markdown.py）：

只允许写入 reports/ 下相对路径，禁止 .. 逃逸
参数：filename、content（整份 Markdown 由模型生成）
成功时 Tool 返回里带 Saved: 路径，便于 trace 验收

注意： 大段正文走 一次 tool 参数，7B 可能截断或偷懒；复杂报告可拆「先 fetch 凑 sources → 再 save」，或接受「摘要版报告 + 引用列表」。

4. `sources`：引用从哪来

模型会改写标题、补假 URL。更稳妥的规则：

参考文献里的 URL，应优先来自本轮 Agent 实际见过的搜索/抓取结果。

做法：

AgentState.sources — 每次 Tool 返回后 ingest_tool_sources(name, args, result)，从 search_web / search_hn / fetch_rss / fetch_url 等解析 URL，去重
sync_system_message() — 每轮调用 LLM 前，把 【本轮已收集来源】 写进 system（条数可配置上限）
prompt — 要求正文引用与列表一致，无来源时不得编造链接

商用产品往往还有成稿 URL 白名单校验；个人版先到 sources 注入 + trace 肉眼核对，第六篇会写边界。

5. Prompt 与 Loop：save nudge

agent/prompt.py 里典型约束：

用户要求保存 → 必须调用 save_markdown，不要只在聊天里贴全文
报告结构：标题、摘要、发现、局限、参考文献
HN/RSS 类任务：先 search_hn 或 fetch_rss，再整理

agent/loop.py 在检测到「用户要保存但本轮未 save」时，可 追加一轮 nudge；仍不 save 时 force_tool_name="save_markdown" 强制调用一次（见 agent/llm.py 的 tool_choice）。

注意： 强制 save 只解决「不调用 Tool」；content 质量仍取决于模型与前面 fetch 是否充分。

6. 与第四篇实测的衔接

第四篇 §4.2 已说明：Tool 成功 ≠ 任务成功（宽 query、门户首页、只给链接）。第五篇在此基础上：

窄 query + 多源（如 search_hn、具体站点 search_web）再 save，通过率更高
「列 HN 头条」 不等于自动落盘 — 除非用户要 save 或 prompt/nudge 触发
trace 里同时看：tool_calls、【本轮已收集来源】、Saved:

7. 本机验收

ollama pull qwen2.5:7b
pip install -r requirements.txt

# 专题 + 落盘（示例）
python main.py -v --trace '调研 Python 3.13 相对 3.12 的主要新特性，写 Markdown，参考文献用本轮来源，保存到 reports/python-313.md'

ls reports/
cat reports/python-313.md

交互调试：python main.py -i --trace。

8. 收束

概念	要点
交付	`save_markdown` + `reports/`
引用	`sources` 注入 system，减少假链
Loop	不变；完成条件靠 nudge / 强制 Tool
模型	7B 可能跳过 save 或简写 — 用 trace 验收

代码：zealot2002/myagent

《从零手写 Agent（六）：云模型 API Key 与网页调研台——Loop 仍不变》——LLM_* 换云端推理，FastAPI + SSE 把调研链可视化。

系列目录：GitHub docs(https://github.com/zealot2002/myagent/blob/main/docs/00-系列导读.md)

从零手写 Agent（四）：多 Tool 与联网检索

goodlords — Thu, 22 Oct 2026 09:06:43 +0000

从零手写 Agent（四）：多 Tool 与联网检索

前面三篇，我基本把一个 Agent 最核心的骨架搭出来了：

第一篇：Tool Calling，让模型可以调用外部能力。
第二篇：messages，让 Agent 有了短期记忆。
第三篇：上下文超长，开始处理 Context Window 和历史消息治理。

做到这里，下一步很自然：

如果我再加两个 Tool，让 Agent 能搜索互联网、读取网页，是不是要继续给 Loop 加 if/else？

答案是：不用。

这一篇我给之前的 Calculator Agent 再加两个 Tool：

search_web：搜索互联网
fetch_url：读取网页

最终变成：

用户问题
   ↓
LLM
   ↓
选择 Tool
   ├── calculator
   ├── search_web
   └── fetch_url
   ↓
Tool 执行
   ↓
结果放回 messages
   ↓
LLM 再判断
   ↓
继续 Tool / 直接回答

Loop 还是之前那个 Loop。

真正发生变化的是：

Tool 越来越多以后，Agent 的能力边界主要由 Tool Registry 决定，而不是由 Loop 决定。

系列目录：GitHub docs(https://github.com/zealot2002/myagent/blob/main/docs/00-系列导读.md)

1. 为什么还是同一个 Loop？

之前的核心代码大概就是：

while steps < MAX_STEPS:
    prepare_messages(messages)

    response = llm(
        messages,
        tools=ALL_TOOLS,
    )

    if response.tool_calls:
        for call in response.tool_calls:
            result = execute_tool(
                call.name,
                call.arguments,
            )

            messages.append({
                "role": "tool",
                "content": result,
            })

        continue

    return response.content

现在增加 search_web 和 fetch_url，这里基本不用动。

只需要：

ALL_TOOLS = [
    CALCULATOR,
    SEARCH_WEB,
    FETCH_URL,
]

然后：

response = llm(
    messages,
    tools=ALL_TOOLS,
)

模型自己决定：

要不要搜索？
    ↓
search_web

拿到 URL 了
    ↓
fetch_url

还需要计算
    ↓
calculator

信息已经够了
    ↓
直接回答

所以从 Agent Loop 的角度看：

Tool 变多
    ↓
Registry 变大
    ↓
模型可选择的动作变多

而不是：

Tool 变多
    ↓
Loop 增加大量 if/else

这其实是这一篇最重要的结论。

2. 多 Tool 的关键：先把能力边界划清楚

这次增加的两个 Tool 看起来都和“联网”有关，但我没有把它们合成一个：

web_tool

而是拆成：

search_web
fetch_url

原因很简单：

搜索和读取网页，本来就是两个不同的动作。

Tool	输入	输出	适合解决
`calculator`	数学表达式	数值	精确计算
`search_web`	搜索词	标题、URL、摘要	不知道去哪里找
`fetch_url`	完整 URL	网页正文	已经知道去哪看

例如：

“Python 3.13 是什么时候发布的？”

一开始并不知道哪个页面有答案：

search_web

拿到：

Python 3.13.0
https://www.python.org/downloads/release/python-3130/

这时候才适合：

fetch_url

去读取具体页面。

如果一开始就让 fetch_url 负责搜索，就会把“搜索”和“读取”混成一个能力，Tool 的职责越来越模糊。

所以这里有一个很实用的原则：

一个 Tool 最好表达一个清晰的动作，而不是把一整段工作流塞进 Tool。

2.1 `search_web`

给模型看的 Tool 描述大致是：

用于搜索互联网信息、新闻、资料和网页链接。

不要用于：
- 纯数学计算
- 用户已经提供完整 URL 的情况
- 普通概念问答

参数：

{
  "query": "Python 3.13 release date",
  "max_results": 5
}

其中：

query

是搜索词。

max_results

限制返回结果数量，当前范围：

1 ~ 10

返回给模型的是普通字符串，例如：

[1] Python 3.13.0
URL: https://www.python.org/downloads/release/python-3130/
Snippet: Python 3.13.0 was released...

---

[2] What's New In Python 3.13
URL: ...
Snippet: ...

最后还是：

{
  "role": "tool",
  "content": "..."
}

所以对 Agent Loop 来说，搜索结果没有特殊待遇。

它就是一次 Observation。

如果搜索失败，也只是：

Error: search failed (...)

模型拿到这个结果之后，可以：

换一个搜索词重试
换一个 Tool
或者直接告诉用户当前无法获取

Loop 本身不需要知道“搜索失败了”。

2.2 `fetch_url`

fetch_url 的职责更加单一：

用户或者前一步搜索已经给出了 URL，现在把这个网页内容读回来。

参数：

{
  "url": "https://www.python.org/"
}

当前只接受：

http://
https://

返回的是经过简单处理后的网页文本。

HTML 里的：

<script>
<style>

等内容会被去掉。

同时限制返回长度，大约：

8000 字符

超过以后：

...(fetch truncated in tool)

这里有两个原因。

第一，网页本身可能非常长。

第二，也是第三篇刚处理过的问题：

Tool 返回太长，最终还是会进入 messages，继续消耗 Context Window。

所以现在其实形成了两层控制：

fetch_url
    ↓
先限制网页输出长度
    ↓
messages
    ↓
prepare_messages()
    ↓
必要时继续做 Tool 内容截断 / 历史滑窗

也就是说，第三篇的上下文治理并没有因为增加 Web Tool 而失效，反而变得更重要了。

3. 三个 Tool 怎么注册？

最终：

ALL_TOOLS = [
    CALCULATOR,
    SEARCH_WEB,
    FETCH_URL,
]

每一个 Tool 还是之前的结构：

Tool(
    name="search_web",
    schema=...,
    fn=search_web,
)

Agent Loop 只需要：

execute_tool(name, arguments)

至于：

search_web 到底怎么搜？
fetch_url 到底怎么抓？

这些都属于 Tool 自己的事情。

目录结构现在大概变成：

agent/
├── tools/
│   ├── calculator.py
│   ├── search_web.py
│   ├── fetch_url.py
│   └── __init__.py
├── loop.py
└── state.py

依赖增加：

ddgs
httpx

4. `search_web` 里面到底怎么实现？

这里有一个容易混淆的地方：

Agent 是多 Tool，不代表一个 Tool 内部只能访问一个数据源。

我现在暴露给模型的仍然只有：

search_web

但 search_web 内部可以尝试多个搜索来源。

当前学习版采用的是串行 Failover：

ddgs
  ↓ 失败
DuckDuckGo Instant Answer
  ↓ 失败
Wikipedia
  ↓ 失败
Qwant
  ↓ 失败
SearXNG

哪个先成功，就返回哪个结果。

这样做的目的不是实现一个完整搜索引擎，而是让这个小项目在没有 API Key 的情况下，也能尽量跑起来。

单个来源有：

SEARCH_TIMEOUT_SEC

整个搜索还有：

SEARCH_BUDGET_SEC

避免所有来源轮流超时，把 Agent 卡很久。

运行：

python main.py -v --trace "Python 3.13 release date"

可以看到：

search provider=ddgs success
search results=...

或者：

search provider=ddgs failed
search provider=wikipedia success

这些信息属于日志，不应该直接塞进模型的 Observation。

模型只需要看到统一格式：

title
url
snippet

这也是为什么多源搜索最好封装在一个 Tool 里面。

4.1 为什么不直接暴露多个搜索 Tool？

比如：

search_duckduckgo
search_wikipedia
search_bing
search_qwant

看起来很灵活，但模型一下子多了很多选择。

而这些 Tool 的本质动作其实都是：

query → 搜索结果

更合理的边界是：

模型
 ↓
search_web
 ↓
内部决定数据源

未来想从串行改成并发，也应该改：

search_web

内部，而不是修改 Agent Loop。

5. 串行还是并行？

如果继续往下做，多源搜索很自然会遇到这个问题。

现在是：

A
↓
失败
B
↓
失败
C

最简单，但延迟可能比较高。

另一种方式是：

        ┌─ A
query ──┼─ B
        └─ C
             ↓
        merge + dedupe
             ↓
          ranking
             ↓
        SearchHit[]

例如内部统一成：

@dataclass
class SearchHit:
    title: str
    url: str
    snippet: str
    source: str

不同搜索源负责：

原始响应
   ↓
adapter
   ↓
SearchHit

最后再统一格式化成：

role: tool

这是后面如果要继续升级时比较自然的方向。

但这篇的学习版没有把复杂度继续往上堆，仍然采用串行 Failover。

6. 多 Tool 真正跑起来是什么样？

假设用户问：

查一下 Python 官方站是做什么的，并把 123*456 算出来。

一个可能的轨迹是：

User
 ↓
LLM
 ↓
search_web
 ↓
搜索结果
 ↓
LLM
 ↓
fetch_url
 ↓
网页内容
 ↓
LLM
 ↓
calculator
 ↓
56088
 ↓
LLM
 ↓
Final Answer

注意：

这个顺序不是写死的。

模型也可能：

calculator
 ↓
search_web
 ↓
fetch_url

甚至只搜索，不抓取网页。

所以 Agent Loop 的职责依然只是：

LLM → Tool → Observation → LLM

至于下一步是什么，由模型决定。

7. 实际测试：Tool 能调用，不代表结果就好

这一部分我觉得比单纯展示代码更有价值。

因为加上联网 Tool 后，很容易产生一个错觉：

“现在 Agent 会搜索了，所以它已经是 Research Agent 了。”

实际并不是。

我用：

qwen2.5:3b

做了两个测试。

7.1 测试一：直接问“今日新闻”

执行：

python main.py -v "今日新闻摘要"

模型实际发出的搜索词是：

Today's news summary

并且：

max_results=1

ddgs 成功返回了结果，但结果比较尴尬：

Google News

页面本身更像一个新闻门户入口，摘要主要是：

登录
地区
导航

最终 Agent 基本变成：

这里有一个今日新闻链接……

也就是说：

Tool 调用成功
        ≠
得到高质量研究结果

问题并不是网络失败。

而是：

用户问题太宽
    ↓
模型生成了英文宽泛 Query
    ↓
只取 1 条结果
    ↓
命中了门户首页
    ↓
没有继续 fetch
    ↓
最终只能给链接

7.2 测试二：把搜索目标说具体

换一个：

python main.py -v --trace '用 search_web 检索「新华社 今日要闻」或「BBC world news today」，根据返回的标题和摘要用中文列 3 条，不要只给链接。'

这次模型搜索：

新华社 今日要闻

返回 5 条结果。

结果里出现了比较明确的新华社页面：

标题
URL
Snippet

最后模型能够根据这些摘要整理出 3 条中文内容。

这次没有调用 fetch_url。

其实已经够解释一个很重要的问题：

搜索质量很大程度取决于模型给搜索 Tool 的 Query，以及搜索结果本身是什么类型。

两个测试对比：

	测试一	测试二
Query	今日新闻	新华社今日要闻
Query 语言	英文	中文
max_results	1	5
结果	新闻门户	具体新闻页面
fetch	没有	没有
最终结果	基本给链接	能整理 3 条摘要
Tool	成功	成功

所以这里暂时不能把第二个测试说成“已经可以做今日新闻调研”。

它只是说明：

search_web
    ↓
返回质量还可以的 Observation
    ↓
小模型能够继续加工

另外测试里还出现了一个很典型的问题：

模型把 Tool 返回的：

权威快报

写成了：

权力建报

这意味着：

Tool 返回的内容进入模型以后，模型仍然可能改写甚至产生错误。

这也是下一篇要解决的引用问题。

8. 这里到底算不算 Research Agent？

如果只看能力链路：

用户问题
 ↓
search
 ↓
fetch
 ↓
多步推理
 ↓
answer

现在已经具备一个最小的 Web Research Agent 雏形。

但我更愿意把它叫：

学习版 Research Agent，而不是完整的调研系统。

目前已经有：

多 Tool
Web Search
网页读取
多步 Tool Calling
短期记忆
Context Trim
Trace / Debug

但距离真正的“调研交付”还差几个关键东西。

第一，缺少明确的调研流程

现在主要依赖模型临场决定：

搜什么
搜几次
什么时候 fetch
什么时候停止

还没有：

规划
→ 搜索
→ 补充搜索
→ 交叉验证
→ 汇总

这样的显式流程。

第二，来源没有被结构化保存

现在：

search_web

标题 + URL + 摘要

模型读完之后自己组织答案。

如果模型改写错了，Agent 很难约束它：

这个说法到底来自哪个 URL？

第三，还没有真正的报告产物

现在最终结果还是：

response.content

如果要做成真正的调研 Agent，应该有类似：

summary
sections
references

这样的结构，并且最终能保存成：

reports/xxx.md

这就是下一篇准备解决的问题。

9. 多 Tool 以后，Agent 的边界到底在哪里？

做到这里，可以重新看一下整个 Agent。

第一篇的时候：

LLM
+
calculator
+
Loop

现在：

LLM
+
calculator
+
search_web
+
fetch_url
+
Loop
+
State
+
Context Governance

但 Loop 还是：

while steps < MAX_STEPS:
    prepare_messages(messages)

    response = llm(
        messages,
        tools=ALL_TOOLS,
    )

    if response.tool_calls:
        ...
        continue

    return response.content

所以我现在越来越倾向于把 Agent 理解成：

Agent
=
LLM
+
Tool Registry
+
Loop
+
State
+
Context Governance

其中：

Tool Registry

决定 Agent 能做什么。

LLM

决定当前 想做什么。

Loop

负责把：

想做
→ 执行
→ 观察
→ 再想

串起来。

而：

State / Context Governance

负责让这个过程不要因为历史消息和 Tool 输出越来越长而失控。

10. 本地运行

安装依赖：

pip install -r requirements.txt

启动模型：

ollama pull qwen2.5:7b

直接测试搜索：

python -c "from agent.tools.search_web import search_web; print(search_web('Python 3.13 release date', 2))"

测试网页读取：

python -c "from agent.tools.fetch_url import fetch_url; print(fetch_url('https://www.python.org/downloads/release/python-3130/')[:600])"

让 Agent 自己调用搜索：

python main.py -v --trace '请用 search_web 查 Python 3.13 正式版发布日期，并写出结果里的来源标题。'

直接测试 fetch_url：

python main.py -v --trace '请用 fetch_url 读取 https://www.python.org/downloads/release/python-3130/ 并中文概括发布日期。'

测试多 Tool：

python main.py -v "Python 3.12 有什么新特性？简述并给出来源。"

如果需要交互调试：

python main.py -i --trace

搜索相关功能依赖网络。

另外，如果终端出现：

dquote>

这类提示，通常是 Shell 引号没有闭合。命令里的整句提示建议用英文单引号包起来。

11. 收束

演进线：Tool → messages → trim → 多 Tool 联网。第四篇一句话：

加能力 = 加 Tool 并注册；Loop 形状不变。

search_web（及后续的 search_hn、fetch_rss）解决「去哪找」；fetch_url 解决「打开已知 URL」。失败、超时、HTML 简抽、结果截断都封在 Tool 内。§4.2 的对比说明：Tool 成功 ≠ 研究结果合格 — query 宽窄与是否继续 fetch 同样关键。

边界应划清：Tool Contract、Registry、State、Context Governance。

Repo：zealot2002/myagent

《从零手写 Agent（五）：调研报告、引用与落盘——Loop 仍不变》——save_markdown、sources、save nudge。

系列目录：GitHub docs(https://github.com/zealot2002/myagent/blob/main/docs/00-系列导读.md)

附录：当前 Tool Registry（发表时）

ALL_TOOLS = [
    CALCULATOR,
    SEARCH_WEB,
    SEARCH_HN,
    FETCH_RSS,
    FETCH_URL,
    SAVE_MARKDOWN,
]

从零手写 Agent（三）：上下文超长，别等模型替你截断

goodlords — Thu, 22 Oct 2026 09:06:03 +0000

从零手写 Agent（三）：上下文超长，别等模型替你截断

第二篇里，我做了一个比较极端的压测。

把 Ollama 的 num_ctx 调得很小，然后不断往 messages 里塞内容。

最后发现一个挺麻烦的问题：

上下文不够的时候，Ollama 不一定报错，而是可能直接把前面的内容截掉。

更麻烦的是，程序看起来一切正常。

messages 还在，接口返回 200，Agent 也给了答案。

只是模型其实已经看不到最早的那部分上下文了。

所以第三篇，我不再等模型侧处理。

这次直接把“上下文治理”放进自己的 Agent Loop：

每次调用 chat() 之前，先检查一下 messages，该截的截，该删的删。

代码核心放在：

agent/context.py

然后用同一个压测脚本，对比：

什么都不做
主动 trim

看看两种情况下，模型到底看到了什么。

系列目录：GitHub docs(https://github.com/zealot2002/myagent/blob/main/docs/00-系列导读.md)

1. 先明确：我要解决的不是“无限 Context”

先看两种模式的区别。

不做处理	主动 trim
`messages` 在进程里一直变长	超过预算就删旧消息 / 截短 tool 正文
模型侧可能静默丢掉前面的内容	我们自己决定删什么
trace 看起来历史还在	trace 和模型实际看到的内容一致
不知道到底丢了什么	system 里明确告诉模型有历史被省略

这里有一个很重要的目标：

不是想办法让 Agent 拥有无限大的 Context。

Context 本身就是有限的。

我要做的是：

在 Context 有限的情况下，让 Agent 的行为变得可预测。

至少不要出现这种情况：

程序：
“我这里明明还有 12 条 messages 啊。”

模型：
“我只看到了后面几条。”

2. 先上两个最朴素的策略

这版没有上什么复杂的 Context Manager。

先做两个最基础的事情：

Tool 内容太长，先截断
messages 太长，删除旧消息

够用了。

2.1 Tool 内容太长，先截

之前 Calculator 的 tool result 只有：

当然不需要处理。

但以后如果 Agent 加了一个 fetch 工具，情况就不一样了。

比如：

role: tool

这里是一篇几万字的网页正文……

这种内容如果原封不动塞进 Context，很容易把窗口吃掉。

所以先对单条 role: tool 做限制。

默认：

CONTEXT_TOOL_MAX_CHARS=2000

超过 2000 字符，就把后面的内容截掉，并追加：

…(content truncated)

也就是：

原始：

[一大段 tool 返回结果……]

处理后：

[前 2000 字符……]
…(content truncated)

这个策略比较简单，但对后面的 Agent 很有用。

尤其是联网、文件读取、搜索这类 Tool，返回内容往往比 Calculator 大很多。

3. messages 太长，再做滑动窗口

Tool 自己截断之后，还有一个问题：

整个 messages 还是会越来越长。

比如：

system
user
assistant
tool
assistant
user
assistant
tool
assistant
...

聊几十轮以后，总长度还是会超过 Context。

所以第二层开始处理整个 messages。

我这里做的是一个非常简单的滑动窗口。

默认：

CONTEXT_MAX_TOKENS=8000

先估算当前 messages 的 token 数。

如果超过预算：

保留最前面的 system
从最老的普通消息开始删
一直删到估算 token 回到预算以内
如果真的删过历史，就在 system 末尾加一个提示

提示类似：

【注意】更早的对话已因上下文长度限制被省略…

这里的 token 估算也没有搞得很复杂。

直接：

len(text) // 3

这个和前面的压测脚本保持一致。

当然，它不是 tokenizer 精确计算。

但现在的目的主要是：

做相对稳定的容量控制和压测对比。

不是拿它当真正的 token billing。

4. 最关键的是：trim 到底放在哪里？

这个位置其实比算法本身更重要。

Agent Loop 大概是：

while ...:
    response = chat(
        messages,
        tools=tools,
    )

    ...

我现在把它改成：

while ...:
    prepare_messages(messages)

    response = chat(
        messages,
        tools=tools,
    )

    ...

也就是说：

每一次调用 LLM 之前，都先做一次 Context 检查。

核心代码就是：

prepare_messages(messages)

而且是就地修改 state.messages。

不是复制一份临时 messages 给模型。

这一点后面调试的时候非常重要。

因为如果模型下一轮看到的是：

A
B
C

那么 trace 最好也应该记录：

A
B
C

而不是：

A
B
C
D
E
F
G

然后实际上模型根本没看到 D~G。

5. 开始压测

接下来就是最有意思的部分。

我写了一个对比脚本：

python scripts/compare_context_trim.py

也可以分别跑：

python scripts/simulate_context_window.py \
  --num-ctx 256 \
  --chunk-chars 4000 \
  --max-rounds 6

开启 trim：

python scripts/simulate_context_window.py \
  --num-ctx 256 \
  --chunk-chars 4000 \
  --max-rounds 6 \
  --with-trim \
  --max-tokens 1200

为了让问题明显一点，我故意把：

num_ctx=256

压得非常小。

每一轮都往上下文里灌：

[块 i]
+ 一大段重复文本

最后统一问：

最早是第几块？只答数字。

理论上，如果模型能看到完整历史，答案应该是最早那一块。

6. 不做 trim：messages 还在，但模型已经看不全了

先看不做 trim 的结果。

第 6 轮：

--- round 6: messages=12 approx_tokens≈6703 ---
OK  reply='3'
     usage: prompt=2373 ...

这里最值得注意的不是答案 3。

而是：

messages=12
approx_tokens≈6703

按照我们程序里的 messages 来看，历史还完整地在那里。

但是：

prompt_tokens≈2373

一直卡在一个比较小的范围。

这说明什么？

引擎已经开始自己截上下文了。

于是最后模型回答：

但真实最早的块并不是 3。

也就是说：

程序认为：

[块1]
[块2]
[块3]
[块4]
[块5]
[块6]

模型实际上看到的：

        [块3]
[块4]
[块5]
[块6]

这就是第二篇里发现的那个问题。

最麻烦的地方在于：

程序自己不知道。

7. 开启 trim：我们自己决定丢什么

再跑一遍。

--- round 6: messages=4 approx_tokens≈1372 ---
     trim: tokens 1372→37, dropped_msgs=1, tools_truncated=0
OK  reply='1'
     usage: prompt=93 ...

这次就不一样了。

trim 之后：

messages=4
approx_tokens≈37

而：

prompt_tokens=93

也明显降了下来。

更重要的是：

现在 messages 里剩下的内容，就是我们主动决定留下来的内容。

最后模型回答：

这里要注意一个容易误解的地方。

它并不意味着：

“模型终于找回了完整历史，所以正确回答了 1。”

不是。

完整的 12 轮历史本来就塞不进这个窗口。

所以两种模式其实都可能相对于“完整历史”答错。

真正的区别是：

不做 trim

程序里的 messages 很长
        ↓
Ollama 自己截
        ↓
模型看到什么，我们不完全知道

做 trim

程序里的 messages
        ↓
我们主动删掉旧内容
        ↓
剩下什么，模型就看到什么

所以这里追求的不是：

“永远正确。”

而是：

至少让我知道模型现在到底看到了什么。

这对调试 Agent 非常重要。

8. Calculator Agent 本身为什么不太容易触发？

回到前面一直写的 Calculator Agent。

它的上下文其实非常短：

system
user
assistant(tool_call)
tool
assistant

所以默认：

CONTEXT_MAX_TOKENS=8000

通常不会触发滑窗。

也就是说，平时跑：

python main.py -v "123 * 456 + 789 是多少？"

大概率还是正常的：

system
user
assistant
tool
assistant

但如果开启：

python main.py -i --trace

然后连续聊很多轮，情况就不一样了。

这也是为什么 Context 治理不能只针对 Calculator。

现在 Calculator 很短，不代表以后所有 Agent 都很短。

一旦加入：

多轮对话
搜索
fetch
文件读取
数据库查询
大段 Tool 返回结果

Context 很快就会成为问题。

9. trim 日志也要打出来

为了方便观察，我在日志里增加了类似：

INFO [joyjoy] context trim: tokens 9000→7800, dropped_msgs=3, tools_truncated=0

这样至少能知道：

原来：9000
现在：7800

删了多少：
3 条 message

Tool 有没有被截：
0

--trace 里也增加：

approx_tokens≈...

这样就可以把自己的估算值和：

usage.prompt_tokens

放在一起看。

这比只看：

Agent 最后回答了什么

有用得多。

因为 Agent 出问题的时候，答案只是结果。

真正需要知道的是：

这一轮模型到底拿到了什么上下文？

10. 一个目前还没解决的问题：Tool Call 配对

这里还有一个坑。

现在为了实现简单，我是：

按 message 一条一条删除最旧消息。

但 Agent 的 Tool Calling 有一个天然的配对关系。

比如：

assistant
tool_calls: calculator(...)

tool
9

这两个实际上属于同一个 turn。

如果简单地按 message 删除，极端情况下可能出现：

tool
9

还在，

但是对应的：

assistant
tool_calls: calculator(...)

已经被删了。

这就变成了一个“孤儿 tool”。

所以当前实现适合这个系列的最小 Agent，但如果继续往生产方向做，下一步应该改成：

按 turn 删除，而不是按 message 删除。

也就是：

assistant + tool

作为一个整体处理。

这个问题我先留在这里，后面继续扩展 Agent Loop 的时候再处理。

11. 那 Ollama 的 `num_ctx` 和我们的 trim 到底谁说了算？

其实是两层。

第一层是我们自己的：

prepare_messages(messages)

它决定：

到底把哪些 messages 发给 API。

第二层是 Ollama：

num_ctx

它决定：

模型最终能处理多大的上下文。

所以即使我们自己做了 trim，也不能认为：

prepare_messages()

之后就绝对安全。

如果我们自己控制在：

但 Ollama：

num_ctx=2048

那模型侧还是可能继续截。

所以完整链路其实是：

原始 messages
      ↓
Tool 内容截断
      ↓
滑动窗口
      ↓
prepare_messages()
      ↓
发送给 Ollama
      ↓
num_ctx 再做最终容量限制
      ↓
模型

这也是为什么压测的时候，我会故意把：

num_ctx

调得很小。

这样可以更容易把问题暴露出来。

12. 可选关闭 trim 与前三篇串起来

注意： CONTEXT_TRIM_ENABLED=false 会回到第二篇行为 — messages 堆长、Ollama 可能静默截断。trim 不是神秘组件，只是 Loop 里的 Context Governance，与具体 Tool 无关。

前三篇串线：Tool+Loop → messages 短期记忆 → prepare_messages（tool 截断 + 滑窗） → 再进 LLM。压测要对比 无 trim / 有 trim 的 prompt_tokens 与模型是否还能看到开头，而不是只写一句「需要滑窗」。

13. 收束

注意：

Context 不够时 别等报错 — 可能静默截断。
最小组合：Tool 返回截断 + 滑窗删旧消息；在每次 chat() 前 prepare_messages(state.messages)，让 trace 与模型所见一致。
压测同时看：messages 条数、估算 token、prompt_tokens、trim 日志、最终答案。
按条删 message 可能拆散 tool_calls 与 tool 配对 — 后续可改按 turn 删、摘要压缩、更准 token 计数。
联网 fetch 后，Tool 内截断 + Loop trim 两层会一起起作用（第四篇起更明显）。

代码：zealot2002/myagent

《从零手写 Agent（四）：多 Tool 与联网检索——Loop 还是那个 Loop》——注册 search_web、fetch_url，扩展能力不改 Loop 形状。

系列目录：GitHub docs(https://github.com/zealot2002/myagent/blob/main/docs/00-系列导读.md)

从零手写 Agent（二）：短期记忆，其实就是你一直带着的 messages

goodlords — Thu, 22 Oct 2026 09:05:08 +0000

从零手写 Agent（二）：短期记忆，其实就是你一直带着的 messages

上一篇把 Tool 跑通以后，我开始给 Agent 加多轮对话。

然后很快就踩了一个特别容易踩的坑。

我先运行：

python main.py --trace "3*3"

程序正常算出了 9。

接着，我又开了一个命令：

python main.py --trace "刚才我问了什么问题？"

结果模型当然答不上来。

当时第一反应是：

Agent 怎么连上一句话都记不住？

后来顺着 messages 和 trace 一路看下去，我才发现，这个问题其实一点都不神秘。

所谓短期记忆，本质上就是：下一次请求的时候，你有没有把之前的 messages 一起带给模型。

没有什么隐藏的 Memory 模块。

也没有模型偷偷替你保存上一轮聊天记录。

你把历史放进上下文，它就能看到；你没放，它就真的不知道。

这件事听起来简单，但它直接牵扯到 Agent 里一个非常核心的问题：

上下文窗口到底是什么？为什么 Agent 聊得越久越容易出问题？

这篇就从我踩的这个坑开始，把这几个问题捋清楚。

1. 我之前理解的“记忆”，其实有点想多了

先看最简单的 Chat Completions 流程。

每次调用 LLM，大概都是：

messages
   ↓
LLM
   ↓
assistant / tool_calls
   ↓
append 到 messages
   ↓
下一次继续发送整个 messages

代码层面其实就是：

response = llm(messages, tools=tools)

messages.append(response)

下一轮：

response = llm(messages, tools=tools)

还是把当前的 messages 整体传进去。

所以我现在比较愿意用一句话来理解：

短期记忆 = 当前还留在 messages 里的历史。

比如一次 Calculator Agent：

[0] system
[1] user: 3*3
[2] assistant: tool_calls → calculator
[3] tool: 9
[4] assistant: 3*3 的结果是 9

下一轮用户再问：

刚才我问了什么问题？

只要新的 user message 继续 append 到这个列表里：

[0] system
[1] user: 3*3
[2] assistant: tool_calls
[3] tool: 9
[4] assistant: 3*3 的结果是 9
[5] user: 刚才我问了什么问题？

模型就能看到之前发生过什么。

所以 Agent 里的 State，在我这个最小实现里，核心其实就是这个：

messages

我额外写的 AgentState，更多只是给这个列表套一层壳，再放一些调试信息，比如：

steps
tool_results

真正给模型看的，还是 messages。

2. 那为什么我刚才换一个命令，模型就“失忆”了？

现在回头看就很容易解释了。

我之前运行的是：

python main.py --trace "3*3"

这个进程结束以后，里面的 AgentState 也没了。

然后我又运行：

python main.py --trace "刚才我问了什么问题？"

这已经是一个全新的进程。

它拿到的 messages 只有：

system
user: 刚才我问了什么问题？

根本没有：

user: 3*3

模型当然不知道。

所以这里有个特别重要的区别：

同一个进程

python main.py -i

然后：

你> 3*3
你> 刚才我问了什么问题？

第二句话可以看到第一句话。

因为两次输入都 append 到了同一个 messages。

两个独立进程

python main.py --trace "3*3"

python main.py --trace "刚才我问了什么问题？"

第二个进程没有第一条消息。

自然也就不存在所谓的“刚才”。

所以：

多轮对话不是模型自己记住了，而是程序一直把历史带着。

这一点我觉得是理解 Agent Memory 最重要的第一步。

3. 那上下文窗口又是什么？

搞明白 messages 之后，下一个问题马上就来了：

如果一直 append，不就可以一直记了吗？

当然不行。

因为模型一次能处理的 token 是有限的。

这个限制，就是：

上下文窗口（Context Window）

我现在比较喜欢把它理解成：

模型一次请求最多能装多少 token 的工作区。

而 messages 就是往这个工作区里不断塞东西。

比如：

system
user
assistant
tool
assistant
user
assistant
tool
...

这些内容都要占上下文。

而且别忘了，Tool 也会占。

比如一个简单 Calculator Agent：

system
user
assistant + tool_calls
tool
assistant

看起来没多少内容。

但如果以后把 Tool 换成：

fetch_web_page()

返回一整页网页：

tool
└── 几万字网页正文

那情况就完全不一样了。

消息条数可能没增加多少，但 token 一下就上去了。

所以 Agent 比普通 Chat 更容易碰到上下文问题。

4. 上下文窗口和 MAX_STEPS，不是一回事

这里我也踩过一个容易混淆的概念。

我的 Agent 里有：

MAX_STEPS

比如：

MAX_STEPS = 10

它表示：

一次任务最多调用多少次 LLM。

而上下文窗口表示：

每一次调用 LLM，最多能塞多少 token。

两个完全不是一个维度。

比如：

MAX_STEPS = 2

也可能出问题。

因为第一轮 Tool 返回了 10 万字。

虽然只跑了两步，但第二次请求已经可能装不下。

反过来也一样。

你可以：

MAX_STEPS = 20

但每一步都很短，整个上下文也可能还没到上限。

所以可以简单记成：

MAX_STEPS
    ↓
最多跑多少步

Context Window
    ↓
每一步最多能装多少 token

这两个东西后面都会影响 Agent，但解决的是不同的问题。

5. 我打开 trace 以后，终于看清楚“记忆”到底是什么

比如执行：

python main.py --trace "3*3"

典型的 messages：

下标	role	内容	占上下文吗
`[0]`	system	系统规则、时间	是
`[1]`	user	`3*3`	是
`[2]`	assistant	tool_calls	是
`[3]`	tool	`9`	是
`[4]`	assistant	最终答案	是

这一张表其实就把很多问题说明白了。

比如第一篇讲的 Tool。

Tool 调完以后，结果并不是：

“计算完成，然后从 Agent 里消失。”

而是：

[3] tool: 9

这条消息还留在 messages 里。

所以第二次调用 LLM 时：

[0]
[1]
[2]
[3]

这些历史仍然会一起送进去。

模型看到：

user: 3*3
assistant: tool_calls
tool: 9

它自然就知道刚才发生了什么。

6. 一个容易误解的地方：tool_results 是不是记忆？

我的 AgentState 里还有一个：

tool_results

里面也会保存：

calculator → 9

刚开始我也会觉得：

那模型是不是同时从 tool_results 里读取结果？

不是。

tool_results 只是我自己为了调试和记录留的一份副本。

模型真正看到的是：

role: tool

对应的 message。

所以：

AgentState.tool_results

和：

messages[].role == "tool"

不是一回事。

前者主要是给程序和人看的。

后者才是模型上下文的一部分。

7. Agent 为什么比普通 Chat 更吃上下文？

这个问题到这里就比较好理解了。

普通 Chat 可能就是：

user
assistant

而 Agent 一次问题可能变成：

system
user
assistant + tool_calls
tool
assistant

如果一次任务里连续调用多个 Tool：

system
user
assistant + tool_calls
tool
assistant + tool_calls
tool
assistant

消息越来越长。

更麻烦的是，Tool 返回的内容有时候也非常长。

比如：

search_web

返回一大段网页。

或者：

read_file

把几万字日志直接塞进：

role: tool

那上下文很快就会被吃掉。

所以我现在看 Agent 的上下文问题，会特别注意三个东西：

现象	背后的原因
对话越来越慢、越来越贵	每次请求都要重新带历史
Tool 返回特别长	Observation 占掉大量上下文
Agent 跑很多步	每一步都会留下新的 message

也就是说：

Agent 的每一步，不只是增加一次调用，也是在给下一次请求增加上下文负担。

8. “每轮都把 messages 全发一遍”，是不是很浪费？

是。

但这是当前这种实现方式本身决定的。

比如：

第一次：
system + user

第二次：
system + user + assistant + tool

第三次：
system + user + assistant + tool + assistant + user

每次请求都会带上当前完整历史。

所以第二次并不是只告诉模型：

刚才 Tool 返回了 9。

而是把整个上下文重新带过去。

这也是为什么多轮 Agent 的 token 成本会不断增加。

当然，具体怎么计费要看平台。

但从实现角度看，有一点是确定的：

你让模型每一轮重新看到完整历史，就意味着每一轮都要重新处理这些历史。

这不是 Loop 写错了。

而是这种上下文工作方式本身就是如此。

9. 那上下文到底能有多长？

这个问题很容易被各种模型宣传页搞得特别复杂。

因为不同模型、不同版本、不同 endpoint，窗口都可能不一样。

所以我这里不想把某个数字当成永久真理。

查模型规格时，最好还是以：

官方文档
+
你实际使用的 endpoint

为准。

我当时本地跑的是：

qwen2.5:3b

通过：

ollama show qwen2.5:3b

看到本机配置的 context length 是：

而且还有一个容易忽略的问题：

模型本身支持多大的 context，和你实际运行时给它多大的 context，不一定是一回事。

Ollama 运行时还会受到：

num_ctx

等配置影响。

所以不要看到模型卡上写了一个数字，就默认自己的 Agent 一定能用满。

10. 我专门做了一次压力测试

理论说到这里还不够。

于是我专门写了一个脚本，故意把上下文窗口调得特别小：

python scripts/simulate_context_window.py \
    --num-ctx 256 \
    --chunk-chars 8000 \
    --max-rounds 5

目的很简单：

每一轮往 messages 里塞一大块文本，然后继续调用 LLM。

看看上下文爆掉以后，到底会发生什么。

正常情况下，我们可能会以为：

context 超了
↓
API 报错
↓
程序知道出问题了

但本地 Ollama 的实际表现有点不一样。

我当时看到的日志类似：

--- round 1: messages=2 approx_input_tokens≈2677 (limit num_ctx=256) ---
OK  usage: prompt=2050 completion=301 total=2351

--- round 5: messages=10 approx_input_tokens≈14192 (limit num_ctx=256) ---
OK  usage: prompt=2050 completion=486 total=2536

最让我注意的是：

messages

明明越来越长。

但：

prompt_tokens

却差不多卡在一个范围。

也就是说：

程序里的历史还在增长，但真正进入模型的上下文已经被截断了。

11. 这比直接报错还麻烦

如果 API 直接告诉你：

context length exceeded

其实很好办。

你看到错误就知道：

上下文满了。

但静默截断就麻烦了。

因为程序可能还是：

HTTP 200

甚至正常返回一个答案。

只是模型已经看不到最早那些内容了。

于是就可能出现这种情况：

程序里的 messages：

[1] 很早之前的重要信息
[2]
[3]
[4]
...
[10] 最近的信息

你打开 trace 一看：

历史不是都在吗？

但模型真正看到的可能只有：

[7]
[8]
[9]
[10]

于是最早的信息就像“失忆”了一样。

更麻烦的是，模型通常不会告诉你：

“抱歉，前面的上下文被截掉了。”

它可能直接根据自己现在看到的内容继续回答。

这就是我觉得上下文超长特别麻烦的地方：

程序层面看起来还正常，模型层面其实已经不是你以为的那个上下文了。

12. 所以，短期记忆其实是有保质期的

到这里，我对“短期记忆”这个词的理解也发生了一点变化。

它并不是：

模型记住了所有聊天内容

而更接近：

当前 messages
    ↓
能放进 context window
    ↓
模型才能看到

所以真正的链路是：

历史消息
   ↓
messages
   ↓
上下文窗口
   ↓
模型

任何一层出了问题，所谓“记忆”都会出问题。

比如：

历史根本没保存

换了一个进程

模型当然不知道。

历史保存了，但太长

context window 不够

模型可能看不到前面的内容。

Tool 返回太长

Observation 吃掉大量窗口

早期对话就更容易被挤出去。

所以：

“模型记不记得”很多时候不是模型有没有 Memory，而是你到底给了它多少上下文。

13. 长期记忆、治理方向、Tool 占窗口（合并说清）

注意：

短期记忆 = 仍在 messages 里、每轮请求都会带上 → 受 Context Window 限制。
长期记忆 = 文件 / DB / 向量库；用时检索再 插入 messages。RAG 不是绕过窗口，而是 先筛再塞。
messages 不能无限 append — 满了就要治理。常见手段：滑窗、摘要、Tool 结果截断、按需检索；第三篇先落地 截断 + 滑窗。
assistant(tool_calls) 与 tool 结果都会留在上下文 — Calculator 返回 9 几乎无感，整页 fetch_url 则会迅速吃满窗口（第四篇更明显）。

14. 收束

注意：

短期记忆 ≈ messages；「记得上一句」是因为下次请求仍带上它们。
多轮要同进程 State（如 python main.py -i）；两次独立命令是两次冷启动。
Context Window 是模型一次能看的 token 上限，不是 messages 列表长度。
Agent 更吃 token：tool_calls + 长 tool 正文会快速占满窗口。
Ollama 可能静默截断 — messages 还在变长，进模型的 prompt 已丢开头；用 --trace 和 prompt_tokens 对照，不要只看最终答案。

《从零手写 Agent（三）：上下文超长，别等模型替你截断》——在 Loop 里加 prepare_messages()，用同一压测脚本对比「不处理 vs 主动 trim」。

系列目录：GitHub docs(https://github.com/zealot2002/myagent/blob/main/docs/00-系列导读.md)

从零手写 Agent（一）：Tool 把我从 Chat 拽进了 Loop

goodlords — Thu, 22 Oct 2026 09:04:59 +0000

从零手写 Agent（一）：Tool 把我从 Chat 拽进了 Loop

最近开始自己折腾 Agent。

一开始我也没急着上 LangGraph 之类的框架，而是在本地用 Ollama 写了一个最小版本：一个 calculator，一个 while 循环，再加上 OpenAI 兼容的 Tool Calling。

代码其实没多少，但跑通以后，我反而觉得这件事比看框架源码有意思。

因为真正把 Calculator Agent 跑起来之后，我才发现：

Agent 和普通 Chat 的区别，并不是 Prompt 写得更长，而是模型开始参与“决定下一步做什么”。

而 Tool，就是这个变化真正发生的地方。

这篇不讲框架，也不打算把 Agent 的概念从头到尾讲一遍。主要记录写这个最小 Agent 时遇到的几个问题，以及跑日志以后对 Tool、Loop、State 的一些理解。

系列目录：GitHub docs(https://github.com/zealot2002/myagent/blob/main/docs/00-系列导读.md) · 代码见文末仓库链接。

1. 一开始，我以为 Agent 就是 Prompt 写得更复杂

普通 Chat 很简单：

User → LLM → Answer

所以我最开始对 Agent 的理解也很朴素：

不就是在 Prompt 里告诉模型：“你可以使用这些工具”吗？

真自己跑起来以后，发现完全不是这么回事。

一个最简单的 Agent，实际执行过程更像这样：

User
  ↓
LLM
  ↓
需要工具？
  ├─ 否 → Answer
  │
  └─ 是
       ↓
    Tool Call
       ↓
    执行 Tool
       ↓
    Observation
       ↓
    LLM
       ↓
    Answer / 再调 Tool

换成代码，其实就是一个非常普通的循环：

while step < MAX_STEPS:
    response = llm(messages, tools=tools)

    if response.has_tool_call:
        assistant_turn = ...
        result = execute_tool(response.tool_call)

        messages.append(assistant_turn)
        messages.append(tool_result_turn)
    else:
        return response.text

到这里，我才真正理解了之前经常看到的那句话：

Agent ≈ LLM + Tools + Loop + State

以前看这句话的时候，感觉多少有点像概念总结。

自己写一遍以后就不一样了。

所谓 Loop，本质就是：

模型说下一步想干什么 → 程序真的去干 → 把结果塞回来 → 再让模型决定下一步。

这才是 Agent 开始“动起来”的地方。

2. 那 Tool 到底是什么？

这个问题我一开始也容易和 Function Call 混在一起。

后来我觉得可以用一句比较简单的话理解：

Tool = 给模型看的说明书 + 程序里真正执行的函数。

这里其实有两个角色。

模型负责：

要不要调用 Tool
调哪个 Tool
参数应该怎么填

程序负责：

接收模型给出的参数
真正执行函数
把执行结果返回给模型

比如我们有一个：

calculator(expression)

模型可能会输出：

{
  "expression": "123 * 456 + 789"
}

注意，这时候计算还没有发生。

模型只是说：

“我想调用 calculator，而且参数是这个。”

真正执行：

calculator("123 * 456 + 789")

的是我的 Python 程序。

所以 Tool Calling 这件事，可以简单理解成：

LLM
 ↓
“我要调用 calculator，参数是 xxx”
 ↓
你的程序
 ↓
真的执行 calculator
 ↓
返回结果
 ↓
LLM

这点很重要。

因为模型发出来的 Tool Call，本质上只是一个请求或者提议，不是程序真的执行了什么。

参数也不一定永远正确。

所以 Agent Loop 不能把模型输出当成绝对可靠的函数调用，必须有一层真正的执行逻辑接住它。

3. 第一个 Calculator Agent 跑起来以后，我才知道 Loop 在干什么

我先问一个最简单的问题：

123 * 456 + 789 是多少？

模型用的是 qwen2.5:3b。

实际日志：

INFO [joyjoy] agent step 1/10
INFO [joyjoy] tool call: calculator({'expression': '123 * 456 + 789'})
INFO [joyjoy] tool result: 56877
INFO [joyjoy] agent step 2/10

计算结果是 56877。

第一次看到这个日志，我觉得挺有意思。

因为它其实把 Agent 的工作过程完整暴露出来了。

第一步：

User
↓
LLM
↓
calculator("123 * 456 + 789")

第二步：

calculator
↓
56877
↓
LLM
↓
“计算结果是 56877”

所以这里出现两个容易误解的地方。

第一，为什么要跑两步？

因为第一轮模型的任务不是“说人话”，而是决定：

这个问题需要调用 calculator。

于是第一轮主要产生的是：

tool_call

工具执行以后，模型拿到 56877，第二轮才负责组织最终回答。

所以：

两步不是多余的，而是 Tool Calling 的正常流程。

第二，真正完成计算的是谁？

不是 LLM。

是：

calculator

LLM 做的是理解问题，然后决定：

calculator("123 * 456 + 789")

程序负责真正计算。

这也是我觉得 Tool 很有价值的地方：

让模型负责“理解”，让程序负责“确定性”。

计算器只是一个很简单的例子。

如果换成搜索、数据库、文件系统、API，逻辑其实还是一样。

4. 模型到底怎么知道“现在应该调 Tool”？

这个问题我刚开始也想得比较简单。

我以为背后是不是有一个东西：

用户问题
↓
关键词检测
↓
出现“计算”
↓
调用 calculator

实际上不是。

模型看到的是：

system prompt
用户问题
历史 messages
Tool 的 description/schema

然后自己决定这一轮应该输出普通文本，还是 tool_calls。

比如：

123 * 456 + 789 是多少？

它可能选择：

tool_calls → calculator

而：

Agent 是什么？

大概率直接：

assistant → 普通文本

这里有一个很容易低估的东西：

Tool description。

我现在越来越觉得，Tool description 有点像给模型看的 API 文档。

如果你有几个功能非常相似的 Tool，description 写得含糊，模型很容易选错。

所以 Tool 的名字固然重要，但真正影响模型选择的，往往是：

Tool 是干什么的
什么时候应该用
什么时候不要用
参数是什么
返回什么

尤其是小模型。

我用的只是本地 qwen2.5:3b，它并不是每次都能做出最合理的选择。

所以实际调 Agent 的时候，我现在比较习惯先看 trace，而不是先怀疑 Loop。

5. 模型明明会算，为什么还要 Calculator？

这个问题也挺有意思。

比如：

123 * 456 + 789

模型自己其实很可能也能算出来。

那为什么还要 Tool？

我的理解是：

很多时候我们要的不是“模型觉得答案是多少”，而是一个可以验证、可以记录、可以复现的结果。

计算尤其明显。

让 LLM 负责：

理解题目

让程序负责：

计算

最后得到的结果就比较容易验证。

同样的思路放到其他场景里也成立：

查数据库 → 数据库负责事实
搜索网页 → 搜索服务负责事实
调用 API → API 返回真实状态
执行操作 → 程序负责副作用

所以 Tool 的意义并不是：

“模型不会做，所以给它一个工具。”

更准确一点应该是：

模型适合做判断和规划，但某些事情交给确定性的程序更靠谱。

6. 一个很有意思的坑：没有 Tool，Agent 就不会回答了吗？

然后我遇到了一个挺有意思的问题。

当时 Agent 里只有一个：

calculator

我突然问：

今天是几号？

结果模型没调 Tool，而是直接说：

请提供当前日期或使用可以获取当前日期的服务或工具。
我目前无法直接获取当前日期。

当时第一反应是：

Agent 是不是坏了？

后来仔细看了一下，Loop 根本没问题。

这一轮发生的是：

LLM
↓
没有 tool_call
↓
返回普通文本
↓
Loop 结束

问题其实在另外一个地方：

Agent 根本没有获得“当前时间”这个能力。

这让我意识到一个很容易混淆的问题：

Agent 能不能完成任务，和 Loop 写得对不对，是两件事。

Loop 只负责：

模型 → Tool → 模型 → Tool → ...

至于模型有没有能力完成当前任务，取决于你给它什么。

7. “今天”到底从哪里来？

这个问题我后来又专门拆了一下。

如果没有：

当前时间
时间 Tool
其他环境信息

那就不能指望模型凭空知道“今天”。

模型没有一块隐藏的硬件时钟。

我现在这个最小 Agent 里，采用的是另一种简单办法：

直接把当前时间写进 system prompt。

比如：

【系统环境】当前本地时间：
2026-10-22 10:54:36 +0800
（日期以 YYYY-MM-DD 为准）

所以进入 Loop 时，messages 大概是：

messages = [
    {
        "role": "system",
        "content": "【系统环境】当前本地时间：2026-10-22 ..."
    },
    {
        "role": "user",
        "content": "今天是几号？"
    }
]

然后模型只是读取上下文里的这段文字。

它并没有真的跑到我的电脑上读取系统时间。

这一点和 Tool 有一个很直观的区别：

	System 注入	Tool
信息在哪里	`system.content`	`role: tool`
是否需要额外 Loop	不需要	通常需要
谁提供	宿主程序	Tool 执行结果
例子	当前时间	查询数据库

这个区分对我来说挺重要。

因为以前容易产生一种误解：

“只要 Agent 有 Tool，所有外部信息都应该通过 Tool 获取。”

其实没必要。

一些稳定、基础的环境信息，直接注入 system 就够了。

而需要动态查询、执行或者验证的东西，再考虑 Tool。

8. 同一个问题，为什么有时候结果还不一样？

把当前时间注入 system 以后，再问：

今天几号？

情况就开始变得有意思了。

理想情况下：

INFO [joyjoy] agent step 1/10

2026-10-22

一步结束。

但小模型偶尔也会犯迷糊。

比如出现：

INFO [joyjoy] tool call:
calculator({'expression': 'today().day'})

WARNING [joyjoy] tool calculator failed:
unsupported expression: Attribute

INFO [joyjoy] tool result:
Error: unsupported expression: Attribute

INFO [joyjoy] agent step 2/10

今天是2026-10-22……

也就是说，它先误用了 calculator，发现不行以后，再根据 system 里的时间把答案答出来。

甚至还有更极端的情况：

模型在 content 里自己输出了一段看起来像 JSON 的东西，但协议层面并没有真正产生 tool_calls。

这种情况下，Loop 只能把它当普通文本处理。

这也让我对一个问题有了比较现实的认识：

Agent 不是写完 Loop 就万事大吉。

实际效果还和下面几个东西强相关：

模型
Tool description
System prompt
输出协议
上下文

所以调 Agent 的时候，我现在更愿意看真实 trace。

不要光盯着最终答案。

9. Tool 一多，问题就来了

目前我的 Calculator Agent 只有一个 Tool，所以事情还很简单。

但如果继续加：

calculator
search_web
read_file
query_database
get_current_datetime
...

模型就需要从一堆 Tool 里做选择。

这时候我目前比较认可几个原则。

Tool 的职责要尽量清楚

比如：

search_web

负责搜索网页。

那就别再搞一个：

web_search

两者干一样的事情。

对模型来说，这相当于：

“这里有两个看起来差不多的按钮，你自己猜按哪个。”

description 比名字更重要

Tool 的 description 最好直接说清楚：

负责什么
什么时候用
什么时候不要用
参数怎么传

把它当 API 文档写就行。

Tool 不是越多越好

协议层面可以注册很多 Tool。

但真正的问题是：

模型到底能不能稳定选对？

如果一个 Agent 同时挂几十个功能，模型选择本身就开始变成问题。

到了这个阶段，通常应该考虑 Router、多 Agent 或者 Tool 分组，而不是继续往一个 Agent 里塞。

10. 我现在调 Agent，基本就按这个顺序排查

这一点是我写完 Calculator 之后最大的一个变化。

以前遇到：

Agent 答错了

第一反应可能是：

Loop 有 bug？

现在我会先看 trace，然后把问题分成几类：

1. 漏调 Tool
2. 误调 Tool
3. 没有合适 Tool
4. Tool 自己执行失败
5. 模型输出协议有问题
6. 上下文/Prompt 有问题
7. 真正的代码 bug

然后一次只改一个地方，再重新跑。

比如模型不调 calculator：

先看 Tool description

模型乱调 calculator：

看 description + system + 模型能力

Tool 调对了，但执行失败：

查 execute_tool

模型明明应该知道时间却不知道：

查 system 环境信息

这样排查起来，比一上来修改 while 循环有效得多。

11. 还有一个和 Agent 完全无关的坑：代理

最后记录一个比较无聊，但确实浪费我时间的问题。

接 Ollama 的时候，OpenAI SDK 报：

502 Bad Gateway

但我直接：

curl localhost:11434

却是正常的。

最后发现不是 Agent，也不是 Tool，更不是 Ollama 挂了。

是 macOS 的 HTTP 代理把 localhost 也转发出去了。

把客户端的：

trust_env

处理好之后才恢复正常。

所以有时候 Agent 看起来“挂了”，真的不一定是 Agent 的问题。

特别是本地模型这种环境，网络代理、endpoint、环境变量这些东西也得一起查。

12. 收束

注意：

Tool = Schema + 你的实现；执行永远在进程里，不在模型权重里。
Agent ≈ Loop：LLM → 是否 tool_calls → 执行 → 结果进 messages → 再调 LLM。
何时调 Tool 由问题、历史、system、Tool description 和模型能力共同决定 — description 要写准。
缺能力（如当前日期）应加 Tool/上下文，而不是改 Loop 逻辑糊弄过去。
--trace 比架构图直观：看清 assistant(tool_calls) → tool → assistant 最终答。

建议路径：先手写几十行 Loop + 一个 Calculator，故意跑坏几次，再去看框架。

《从零手写 Agent（二）：上下文窗口与多轮对话》——messages 就是短期记忆；-i 与同进程 State；Context Window 与 Ollama 静默截断。

系列目录：GitHub docs(https://github.com/zealot2002/myagent/blob/main/docs/00-系列导读.md)

附录：几个关键日志

计算题

INFO [joyjoy] agent step 1/10
INFO [joyjoy] tool call: calculator({'expression': '123 * 456 + 789'})
INFO [joyjoy] tool result: 56877
INFO [joyjoy] agent step 2/10

计算结果是 56877。

`--trace`

[1] user: 123 * 456 + 789 是多少？
[2] assistant: tool_calls → calculator({"expression":"123 * 456 + 789"})
[3] tool: 56877
[4] assistant: 计算结果是 123 乘以 456 再加 789 等于 56877。

没有时间信息时

INFO [joyjoy] agent step 1/10

请提供当前日期或使用可以获取当前日期的服务或工具。
我目前无法直接获取当前日期。

调优后误调 Calculator

INFO [joyjoy] tool call:
calculator({'expression': 'today().day'})

INFO [joyjoy] tool result:
Error: unsupported expression: Attribute

INFO [joyjoy] agent step 2/10

今天是2026-10-22，……

代码：

https://github.com/zealot2002/myagent

小理发店记账工具，极简操作，欢迎试用

goodlords — Tue, 20 Oct 2026 08:32:00 +0000

上个月，王姐来剪头发。
剪完我说：「姐，卡里余额不太够了，要不要再充点？」
她愣了一下：「我上礼拜才充的500。」

我翻开记账本——那笔500，被我记到了李姐那一页。

当场退钱、道歉，王姐摆摆手笑着说「没事没事」。
可那声「没事」，让我难受了一整晚。

开小店的人都懂：
老顾客愿意把钱放你这儿，是因为信你。
账错一次，信任就裂一道缝。

更难的是每天晚上。
收了摊，老婆问今天收了多少，
本子、微信、支付宝翻个遍，计算器按到十一点，还是对不上。

后来朋友甩给我一个 App：老驴美发会员。
名字挺土，用起来是真顺——

现在王姐进门：
搜「王姐」，余额直接跳出来，剪发38，点一下就扣完。
她要充值，到账和实收分开记，有赠送一眼能看。
前后不到30秒，后面排队的客人不用等我翻本子。

散客也有地方去。
点「散客」，现金一笔录进去，收了钱再也不会转头就忘。

记错了也别慌。
长按那一笔，撤销，余额原路退回。
再也不是拿笔涂改、越改越乱。

现在晚上收摊，点开「今日经营」：
今天实收多少、充值多少、散客多少，一眼看清。
月底不用按计算器了。
年底还有项目排行——原来烫发才是店里的顶梁柱，明年定价心里有数。

Android 下载页：https://hairsalon-ayn.pages.dev/
装上就能用，不用注册登录。
数据就存在自己手机里，不上传云端，顾客名单只有你自己看得到。
店里断网也能记，备份能发到微信。

唯一要记住的：
数据都在这台手机里，别随手清缓存。

你们的店，还在拿本子记账吗？
评论区聊聊，你记错过的最离谱的一笔账😌

给孩子做的生日3D场景：一个爸爸的技术小实验

goodlords — Sat, 04 Jul 2026 01:19:53 +0000

给孩子做的生日3D场景：一个爸爸的技术小实验

为什么做这个？

孩子要过生日了，我想给他/她一个特别的礼物。不是买玩具，也不是买蛋糕，而是用技术做一个专属的3D生日场景。

里面有他/她喜欢的小房子、跑车、直升机，还有一只可爱的小猫。当然，生日蛋糕是必不可少的。

这个场景有什么？

🏠 一个带花园的小房子
� 生日蛋糕
� 两辆跑车（一辆白色，一辆黑色）
� 一只小猫
� 一架直升机
👦 一个卡通人物

孩子可以用鼠标：

拖拽旋转场景
滚轮放大缩小
右键平移

就像玩3D游戏一样，可以360度查看每个细节。

技术上怎么做的？

简单说就是用了一个叫 Three.js 的JavaScript库，它可以在浏览器里渲染3D场景。

主要做了几件事：

加载各种3D模型文件（.glb和.fbx格式）
把它们放在合适的位置
加上灯光和阴影
让模型自动播放动画
加载时显示进度条，因为模型文件比较大

遇到的坑

最大的坑是模型文件太大，加载很慢。所以我加了一个进度条，让孩子知道加载到哪了，不会以为网页坏了。

还有就是不同模型的尺寸差异很大，需要一个个调整大小和位置，让它们看起来协调。

怎么部署？

我用的是 Cloudflare Pages，免费而且速度快。每次push代码到GitHub，它就自动部署了。

本地运行的话，简单到不行：

python3 -m http.server 8080

然后打开浏览器访问 localhost:8080 就行了。

孩子的反应

看到这个场景时，他/她眼睛都亮了。指着直升机说"哇"，又指着跑车说"这个好酷"。虽然他/她不懂技术，但这个3D场景确实让他/她开心了。

这就够了。

代码在哪里？

如果你想看看代码，或者自己也做一个，GitHub上有完整的项目：
https://github.com/zealot2002/3d

技术不重要，重要的是用心给孩子做点特别的东西。

I built a pure-frontend, all-in-one toolbox for the tasks I reach for every day

goodlords — Wed, 10 Jun 2026 09:02:26 +0000

After years of mobile development, one of the most annoying parts of my daily workflow is jumping between scattered tool websites.

Finding image assets means digging through folders layer by layer — SVG and Lottie need separate preview tools. Converting or compressing images means uploading to online converters. Debugging APIs means opening a JSON formatter. Inspecting an APK means yet another dedicated site. By the end of the day I have a dozen tabs open, constantly context-switching. Worse, many online tools require file uploads — internal project assets and unreleased builds always feel risky.

When things slowed down recently, I built a pure-frontend, all-in-one toolbox for the tasks I reach for every day. I call it AppForge. Core features run locally in the browser — files never leave your machine.

Resource Preview: find one icon in 2,870 files

This was the first module I built — and the one I use most — because it hits a daily pain point for our 40-person app team.

One project scan surfaces 2,870 resource files. Search close and you get 80+ near-identical close icons: inconsistent names, scattered paths, zero discipline. Can I push the whole team to clean this up overnight? Honestly, no.

But one missing asset blocks your whole flow. My take is simple: if I can't fix the mess, I can at least find what I need in seconds.

Select a local project folder — AppForge scans everything and recognizes SVG, WebP, PNG, GIF, Lottie, Vector, Iconfont, and more. The screenshot shows it in action: search close, filter Vector, 81 matches with instant preview and full paths. No Finder spelunking, no guessing the rest of the filename.

Results cache locally — reopen and you're ready. Onboarding legacy projects, auditing duplicate assets, or chasing "that little X close icon" — what used to take minutes now takes seconds.

File Conversion: image processing in one place

After finding assets comes format work: SVG → PNG for multi-platform, PNG → WebP for smaller bundles, HEIC → common formats, occasional background removal for marketing assets.

Instead of design software or multiple upload sites, the convert module handles format conversion, smart compression, and background removal — all locally. Drop files in, download results.

APK Inspector: unpack locally

Android devs regularly need to inspect APKs: competitor package names and versions, signatures and permissions, icons and resources.

Drag an APK into AppForge to view package info, Manifest, permissions, components, and export internal assets. Need decompilation? One click to JADX.

Image OCR: copy text from screenshots

Stack traces, design copy, code snippets in docs — often trapped in screenshots. The OCR module runs locally, supports Chinese and English, batch processing, one-click copy. Files stay on your machine.

Mini Tools: no more bookmark clutter

JSON formatting, Base64 / URL / Unicode encode-decode, regex testing, timestamp conversion — small but essential. Built-in presets for email, phone, ID, IP, and more.

AI-Curated Tech Articles: skip the noise

Another big pain point. As a mobile developer I skim tons of tech content daily — most of it is fluff, reposts, or clickbait.

The AI-curated articles section pulls candidates from DEV and Hacker News, scores each post with an LLM, and keeps only high-quality picks. Updated daily with cumulative history — past picks aren't wiped each run. Browse by category in Chinese or English — like having someone pre-filter for you.

Open APIs: quick reference for demos

Building a small demo often means hunting for free APIs, testing endpoints, bookmarking docs. I curated common APIs by category with sample calls — look up when you need them.

Why I built it this way

Simple goal: make my own workflow smoother.

Local-first: sensitive project assets and builds stay in the browser
Zero friction: no signup, no desktop install — just open and use
Real scenarios: every feature comes from actual daily pain points

Built with React 19 + Vite 8 + Tailwind CSS 4, deployed on Cloudflare Pages, with lazy loading, caching, and bilingual UI.

Started as a personal toolbox — after using it for a while I polished it for others. If you're a mobile developer tired of scattered tools, give it a try.

What's missing from your dev workstation? Share the tools and workflow tricks you can't live without in the comments — let's swap notes and level up together.

👉 Try it now: https://appforge-7tw.pages.dev

AppForge — AI-curated reads and dev tools at your fingertips, all-in-one.

Modern Android Architecture (Part 4): Design Patterns — The Glue of Lego Architecture

goodlords — Mon, 01 Jun 2026 02:06:48 +0000

Series Navigation: Article 1: A Decade of Android Architecture Evolution | Article 2: The Lego Architecture: Divide and Conquer, Taken to the Extreme | Article 3: Refactoring a Product Detail Page with Lego Architecture

Project Repository: https://github.com/zealot2002/androidArch

Foreword: Bricks Are Ready, How to Assemble Them Stably?

In the first three articles, we followed a clear path:

Article 1 pointed out: Architecture is just "technique" — it can manage layering, but not splitting granularity.
Article 2 proposed Lego Architecture: Split infinitely to minimum particles, making reuse visible.
Article 3 proved with practical product detail page: Bricks like Mapper, Assembler, ListItem can indeed split a 3000-line disaster into 15 independent components.

But there's a question hinted at the end of Article 3 — Splitting is only the first step; assembly determines whether this system can run long-term.

Two pages both require "login before operation" — do you plan to copy-paste two sets of if (isLogin) checks? Three types of posters (product, social, store) share the same "render → screenshot → preview → share" workflow, but with completely different UI layouts — do you plan to write three when branches in Activity, each hundreds of lines long?

This is where design patterns come in. They are not another "silver bullet architecture," but the glue between Lego bricks — using minimal, proven connection methods to stably assemble already-split particles together.

The 23 GoF patterns and more evolving patterns each solve different "assembly" problems: Factory is responsible for creating the right bricks, Strategy for switching replaceable behaviors, Adapter for connecting incompatible interfaces, Observer for responding to state changes, Template Method for solidifying invariant processes... Due to space constraints, this article won't cover all of them, but will select two representative cases from the demo project — Observer and Template Method — to illustrate how design patterns generally work in Lego Architecture.

Left: Product detail page from Article 3 — favorite, add to cart, and buy now gated by LoginRouter; Right: Three poster share pages (product / social / store) — sharing the BillActivity screenshot flow, each rendered by a different BaseBillRender subclass.

I. Observer Pattern: LoginRouter — The "Broadcast Station" for Login State

1.1 Pain Point: Login Interception Scattered Everywhere

In e-commerce apps, many operations depend on login state: favorite products, add to cart, buy now, post comments...

The crudest approach is to repeat this check in every click event:

if (UserManager.isLogin()) {
    doSomething()
} else {
    startActivity(Intent(this, LoginActivity::class.java))
}

The problems are:

Repetition: Ten buttons, ten copies of the same check logic.
Broken flow: After successful login, the original operation is often "lost" — the user has to click the button again.
Coupling: Some projects even write post-login navigation directly into LoginActivity, coupling the login module with other modules.

Lego Architecture requires: Extract "execute after login" as an independent, reusable brick.

1.2 Solution: Observer Pattern

LoginRouter consists of two observable sources (LifecycleOwner, LoginStateLiveData) and a pendingBlock:

LoginStateLiveData — Subscribe to login state. Publish true after successful login to trigger pending callbacks.
LifecycleOwner — Subscribe to page lifecycle. Clear pending when page is destroyed to avoid leaks; also clear on ON_RESUME — when user presses back from login page without logging in, pending operations should be abandoned.
pendingBlock — Store the "execute after login" operation. Suspended when not logged in, automatically invoke() after successful login.

Core code:

class LoginRouter(private var context: Context) {
    private var pendingBlock: (() -> Unit)? = null

    init {
        if (context is LifecycleOwner) {
            // Observer: Login success → execute pending operation
            LoginStateLiveData.observe(context as LifecycleOwner) {
                if (it) {
                    pendingBlock?.invoke()
                    pendingBlock = null
                }
            }
            // ON_RESUME: User returns from login page but not logged in (e.g., pressed back), abandon pending
            // ON_DESTROY: Page destroyed, clean up pending
            (context as LifecycleOwner).lifecycle.addObserver(
                LifecycleEventObserver { _, event ->
                    when (event) {
                        Lifecycle.Event.ON_RESUME,
                        Lifecycle.Event.ON_DESTROY -> pendingBlock = null
                        else -> {}
                    }
                }
            )
        }
    }

    fun runBlock(block: () -> Unit) {
        if (context is LifecycleOwner) {
            if (LoginStateLiveData.value == true) {
                block.invoke()
            } else {
                pendingBlock = block
                AppRouter.openLogin(context)
            }
        } else {
            block.invoke()
        }
    }
}

After successful login, the login page only needs to update the global state:

// LoginActivity
LoginStateLiveData.value = true
finish()

This is the complete Observer Pattern loop:

LoginActivity login successful
       │
       ▼
LoginStateLiveData.value = true   ← Subject publishes state
       │
       ▼
LoginRouter receives notification ← Observer
       │
       ▼
pendingBlock?.invoke()            ← Automatically execute suspended operation

1.3 Usage in Product Detail Page

In the refactored GoodsDetailActivity from Article 3, favorite, add to cart, and buy now are all handled with one line through LoginRouter:

private val loginRouter: LoginRouter by lazy { LoginRouter(this) }

// Favorite
loginRouter.runBlock {
    // Note: this is not a page navigation — it triggers a state update after login
    favViewModel.setFavorite(currentSpuId, targetFavorite)
}

// Add to cart
loginRouter.runBlock {
    ToastUtils.show(this, getString(R.string.goods_action_add_cart_hint))
}

// Buy now → Navigate to confirm order page after login
loginRouter.runBlock {
    AppRouter.openConfirmOrder(this)
}

The difference between LoginRouter and a route interceptor: interceptors usually only handle unified page navigation, while runBlock can queue any operation as pending — favorite, API request, show Toast, not limited to opening new pages. Subsequent actions are still declared locally in the page, and LoginActivity no longer needs to act as a transit hub. Module boundaries are clear and decoupled.

1.4 Origin and Boundaries

LoginRouter wasn't designed upfront; it emerged from project pain points.

After connecting favorite, add to cart, and buy now to the detail page, the same logic repeatedly appeared across multiple buttons: check login, navigate to login page, continue original operation after success. Interceptors could only intercept navigation uniformly, not handle "continue favorite after login"; writing destinations into LoginActivity would couple the login module with business logic. After several rounds of copy-paste, the pain point became clear — missing a common brick that can queue any follow-up action as pending.

Extract, observe, abstract: LoginRouter combines login guard and pending continuation into one brick, using LoginStateLiveData and LifecycleOwner to coordinate timing, elegantly solving this pain point.

Lego Architecture not only requires the ability to split, but also to see patterns in repetition and discover bricks in pain points — LoginRouter is one such refinement.

II. Template Method Pattern: BillActivity — Fixed Process, Variable Content

2.1 Pain Point: Three Poster Types, One Workflow

We added a poster sharing feature to the demo project — users can generate beautiful posters for products, social posts, or store pages, save to album, or share to WeChat.

The three poster types have completely different UI layouts, but the page-level workflow is identical:

Load data → Select Render → Bind view → Wait for render ready → Screenshot → Preview → Save/Share

If we write three sets of rendering logic in BillActivity using when (billCase), the Activity will quickly bloat; if we write a separate Activity for each poster type, the screenshot, preview, and save code will be duplicated three times.

Template Method Pattern solution: Solidify the "invariant process" in a template, leave "variable parts" for subclasses to implement.

2.2 Architecture Layers: Interface → Abstract Template → Concrete Implementation

Step 1: Define Brick Interface

interface BillRender {
    fun onBindView(data: Any, listener: Listener)
    fun getBillView(): View

    interface Listener {
        fun screenReady(bgBitmap: Bitmap? = null)
    }
}

BillRender is a standard interface — all poster Render bricks must follow these two methods.

Step 2: Abstract Template Class Solidifies Common Skeleton

abstract class BaseBillRender<T, B : ViewBinding>(private val context: Context) : BillRender {

    private lateinit var binding: B

    // Subclasses only implement this method — fill specific UI
    abstract fun onRenderView(data: T, binding: B, listener: BillRender.Listener)

    init {
        // Template method: Reflection automatically inflates corresponding ViewBinding
        val superclass = javaClass.genericSuperclass as ParameterizedType
        val bindingClass = superclass.actualTypeArguments[1] as Class<B>
        val inflate = bindingClass.getDeclaredMethod("inflate", LayoutInflater::class.java)
        binding = inflate.invoke(null, (context as Activity).layoutInflater) as B
    }

    override fun onBindView(data: Any, listener: BillRender.Listener) {
        onRenderView(data as T, binding, listener)  // Call subclass implementation
    }

    override fun getBillView(): View = binding.root
}

This is the core of Template Method Pattern:

BaseBillRender defines the algorithm skeleton (inflate Binding → call onRenderView → expose getBillView).
Subclasses only need to implement one hook: onRenderView, filling in their own UI logic.
Common ViewBinding initialization is done through generics + reflection, with zero boilerplate code for subclasses.

Step 3: Concrete Subclasses Only Care About Their UI, Need Only Implement One Method

Taking product poster as example:

class GoodsBillRender(context: Context) :
    BaseBillRender<GoodsBillData, LayoutBillGoodsBinding>(context) {

    override fun onRenderView(
        data: GoodsBillData,
        binding: LayoutBillGoodsBinding,
        listener: BillRender.Listener,
    ) {
        binding.tvTitle.text = data.title
        binding.tvPrice.text = data.price
        // ... Fill product-specific fields

        // Wait for layout drawing + network image loading to complete
        binding.ivCover.loadNetworkImage(data.imageUrl, onSuccess = { markReady() })
        binding.ivQrCode.loadNetworkImageCircle(data.miniProgramCodeUrl, onSuccess = { markReady() })
        // Call screenReady when all ready
    }
}

markReady() internally maintains a counter (product poster needs to wait for layout drawing + cover image + QR code = 3 items), and only triggers screenReady when the count is complete, ensuring complete content during screenshot.

SocialBillRender and ShopBillRender have the same structure, each binding different layouts and Data types. Adding a new poster type only requires adding a new Render subclass + one Layout XML, zero modifications to existing code.

Step 4: Factory Selects Concrete Brick

object BillRenderFactory {
    fun make(context: Context, case: Int): BillRender {
        return when (case) {
            RouterConstants.BILL_CASE_SOCIAL -> SocialBillRender(context)
            RouterConstants.BILL_CASE_SHOP -> ShopBillRender(context)
            else -> GoodsBillRender(context)
        }
    }
}

2.3 BillActivity: Orchestrating the Fixed Workflow

BillActivity itself contains no specific poster UI logic; it only orchestrates the template process:

class BillActivity : BaseActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        // ... Initialize views, share button

        // 1. Factory selects Render brick
        billRender = BillRenderFactory.make(this, billCase)
        binding.flBillContainer.addView(billRender.getBillView(), ...)

        // 2. Load data + bind view
        val billData = BillDataLoader.load(billCase, billId)
        billRender.onBindView(billData, object : BillRender.Listener {
            override fun screenReady(bgBitmap: Bitmap?) {
                captureBillSnapshot()  // 3. Render ready → screenshot
            }
        })
    }

    private fun captureBillSnapshot() {
        // 4. View → Bitmap → Preview display
        val bitmap = BillBitmapUtils.viewToBitmap(billRender.getBillView())
        binding.ivBill.setImageBitmap(bitmap)
        // 5. Show bottom save/share bar
    }
}

The responsibility boundaries are clear throughout the page:

Component	Responsibility	Pattern
`BillDataLoader`	Load Mock data by case	Simple Factory
`BillRenderFactory`	Select specific Render implementation	Simple Factory
`BaseBillRender`	Solidify inflate + bind skeleton	Template Method
`GoodsBillRender`, etc.	Fill specific UI + async ready detection	Template Method hooks
`BillActivity`	Orchestrate load → render → screenshot → preview → share	Process controller
`BillBitmapUtils` / `BillImageSaver`	Screenshot and save	Independent utility bricks

2.4 Echo with Article 2: When to Use Template Method?

In Article 2, we harshly criticized this kind of Base:

abstract class BaseActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        initCallerData()   // Forced order
        initView()
        initPageData()
        initObservers()
    }
    abstract fun initView()
    abstract fun initPageData()
    // ...
}

Why is the template method in BaseBillRender acceptable, but not in BaseActivity?

	Bad BaseActivity Template	Good BaseBillRender Template
Is the process really consistent?	Different pages have very different initialization orders	All posters must inflate → bind → render → ready
Constrains order or structure?	Forces `initView` before `initData`	Only specifies "call `onRenderView` when binding data"
Subclass freedom	Kidnapped by four abstract methods	Only need to implement one `onRenderView`
Is it pluggable?	Must inherit Base to use	Just implement `BillRender` interface, no inheritance required

The judgment is simple: Only use template method when the algorithm skeleton is truly consistent across multiple subclasses; if you're just "incidentally" stuffing a bunch of optional initialization steps into Base, it's a shackle, not a template.

III. Gluing Approaches from Two Cases

The two cases above demonstrate two common "gluing" directions of design patterns in Lego Architecture — responding to changes and solidifying processes. Other patterns solve different dimensions of assembly problems like creation, replacement, adaptation, etc., with similar thinking.

Dimension	Observer (LoginRouter)	Template Method (BillRender)
Problem Solved	When A's state changes, B needs to respond automatically	Multiple subclasses share the same algorithm skeleton, only some steps differ
Connection Method	Subscription / Callback	Inherit abstract class + implement hook methods
Coupling Direction	Subject doesn't know who's observing (unidirectional)	Subclass depends on parent skeleton (unidirectional)
Lego Position	Cross-module event broadcasting brick	Common skeleton brick for similar Renders
Extension Method	Add new observers without modifying Subject	Add new subclasses without modifying template skeleton

Regardless of pattern, there's a common prerequisite: They are used to "glue" bricks after Lego splitting — not to replace splitting itself.

If you haven't split login logic into LoginRouter, Observer Pattern won't save you — you're just writing LiveData observations in three Activities. If you haven't split the three posters into independent Renders, Template Method won't save you either — BaseBillRender will be filled with if (case == SOCIAL) branches. Same for Factory, Strategy, and other patterns — Split first, then glue, order matters.

Beyond the two cases detailed in this article, the demo project has patterns working silently throughout — they're not the stars, but they're connectors between bricks:

Pattern	Location in Project	What It Glues
Observer	`LoginRouter`	Login state changes → cross-page pending follow-up operations
Template Method	`BaseBillRender`	Multiple posters share inflate → bind → render skeleton
Simple Factory	`BillRenderFactory`, `BillDataLoader`	Create corresponding Render / data by `billCase`
Strategy	`BillRender` and its implementations	Switch different poster rendering strategies under the same screenshot process
Adapter	`GoodsDetailAdapter`	14 types of `ListItem` → RecyclerView multi-type rendering

IV. Complete Lego Architecture System: Four Articles Connected

At this point, the four articles form a complete narrative:

Article 1: Problem Awareness
  └─ Architecture is just "technique", connection count determines complexity

Article 2: Splitting Methodology
  └─ Lego Architecture = Infinite splitting to minimum particles + Governance iteration

Article 3: Splitting Practice
  └─ Product Detail Page: ListItem + Mapper + Assembler + ViewModel

Article 4: The Glue
  └─ Design Patterns: On top of splitting, use appropriate patterns to stably assemble bricks (this article focuses on Observer and Template Method)

The complete Lego Architecture system can be summarized as:

One Axiom: Divide-and-conquer + Single Responsibility
Multiple Theorems: Governance thinking, tool iteration (Private→Shared→Remote), reuse discovery
One Practice: 15 independent components in product detail page
One Layer of Glue: Design patterns — this article focuses on Observer and Template Method; the project also uses Factory, Strategy, Adapter patterns for connection (see table above)

When you truly build applications with Lego thinking, you'll find:

Complexity doesn't come from the application itself, but from not splitting it into small enough bricks.
Design patterns aren't for showing off, but for selecting appropriate patterns by scenario after splitting, using minimal connections to stably assemble bricks.
Good code isn't written by learning one architecture, but by having divide-and-conquer awareness, governance discipline, pattern intuition, and the ability to spot reusable bricks.

Series Conclusion

Four articles, from "Architecture Evolution History" to "Lego Splitting Methodology", to "Product Detail Page Practice", and finally to "Design Pattern Glue" — we've tried to answer a consistent question:

How to truly improve Android code quality?

The answer isn't in the labels of MVVM or MVI, but in daily programming discipline: split until you can't split anymore, glue only when needed, govern for sustainable iteration.

May your codebase be like a box of Lego — each brick has clear responsibilities, stable interfaces, can be combined freely, and can still build new models after many years.

Related Reading:

DEV Community: goodlords

I built a local-first membership app for one-chair hair salons

Meet Lao Lv Salon Member

Try it

Who it is (and is not) for

Feedback welcome

从零手写 Agent（七）：和商用 Agent 还差什么——个人调研 Agent 的边界

1. 数据能力

2. 任务规划

3. 结果可靠性和评估

4. 模型能力

5. 工程和安全

6. 长任务和状态持久化

对照下来

从零手写 Agent（六）：云模型 API Key 与网页调研台

从零手写 Agent（六）：云模型 API Key 与网页调研台——Loop 仍不变

1. 云端 LLM：还是同一个 Chat Completions

2. 为什么单独做网页，而不是再加一个 Tool？

3. Loop 加钩子：on_event

4. 网页调研台结构

5. 和 CLI 怎么选

6. 本机验收

7. 收束

下一篇

从零手写 Agent（五）：调研报告、引用与落盘

从零手写 Agent（五）：调研报告、引用与落盘

1. 第四篇之后，还差哪一层？

2. 第一个坑：说了「保存」，磁盘却没有文件

3. save_markdown：沙箱与 Tool 契约

4. sources：引用从哪来

5. Prompt 与 Loop：save nudge

6. 与第四篇实测的衔接

7. 本机验收

8. 收束

下一篇

从零手写 Agent（四）：多 Tool 与联网检索

从零手写 Agent（四）：多 Tool 与联网检索

1. 为什么还是同一个 Loop？

2. 多 Tool 的关键：先把能力边界划清楚

2.1 search_web

2.2 fetch_url

3. 三个 Tool 怎么注册？

4. search_web 里面到底怎么实现？

4.1 为什么不直接暴露多个搜索 Tool？

5. 串行还是并行？

6. 多 Tool 真正跑起来是什么样？

7. 实际测试：Tool 能调用，不代表结果就好

7.1 测试一：直接问“今日新闻”

7.2 测试二：把搜索目标说具体

8. 这里到底算不算 Research Agent？

第一，缺少明确的调研流程

第二，来源没有被结构化保存

第三，还没有真正的报告产物

9. 多 Tool 以后，Agent 的边界到底在哪里？

10. 本地运行

11. 收束

下一篇

附录：当前 Tool Registry（发表时）

从零手写 Agent（三）：上下文超长，别等模型替你截断

从零手写 Agent（三）：上下文超长，别等模型替你截断

1. 先明确：我要解决的不是“无限 Context”

2. 先上两个最朴素的策略

2.1 Tool 内容太长，先截

3. messages 太长，再做滑动窗口

4. 最关键的是：trim 到底放在哪里？

5. 开始压测

6. 不做 trim：messages 还在，但模型已经看不全了

7. 开启 trim：我们自己决定丢什么

不做 trim

做 trim

8. Calculator Agent 本身为什么不太容易触发？

9. trim 日志也要打出来

10. 一个目前还没解决的问题：Tool Call 配对

11. 那 Ollama 的 num_ctx 和我们的 trim 到底谁说了算？

12. 可选关闭 trim 与前三篇串起来

13. 收束

下一篇

从零手写 Agent（二）：短期记忆，其实就是你一直带着的 messages

从零手写 Agent（二）：短期记忆，其实就是你一直带着的 messages

1. 我之前理解的“记忆”，其实有点想多了

3. Loop 加钩子：`on_event`

3. `save_markdown`：沙箱与 Tool 契约

4. `sources`：引用从哪来

2.1 `search_web`

2.2 `fetch_url`

4. `search_web` 里面到底怎么实现？

11. 那 Ollama 的 `num_ctx` 和我们的 trim 到底谁说了算？

`--trace`