第 2 章 · 四阶认知在 pixiu 的落点

pixiu 锚点：阶1 agent/prompts/system.md；阶2 agent/prompts.py:_build_memory_context；阶3 agent/tools.py；阶4 agent/core.py:_continue_agent_loop

开篇：所有人都从调 prompt 开始

如果你观察一群刚做 agent 的程序员，会发现一个高度一致的模式——大家的第一反应都是研究 prompt。 这很正常，prompt 是最显眼的旋钮，转一下就有反馈。

但很多人会卡在这一步，以为 agent 好不好 = prompt 写得好不好。这个模型只覆盖了整件事的一小块。从 prompt 往外走，还有三层在等着你，而且越往外，越是 agent 工程的真正核心。

我在 pixiu 里把这四层都实打实做了一遍。这一章就用 pixiu 的代码，把这四层一一指给你看——每一层长什么样、成熟标志是什么、你大概卡在哪一层。

四阶全景

阶	关注点	pixiu 落点	成熟标志
阶1 Prompt	怎么跟模型说话	`prompts/system.md`	角色分区 + 硬约束 + 反例
阶2 Context	给模型什么信息	`prompts.py:_build_memory_context`	主动分层管理模型的视野
阶3 Harness	模型怎么跟系统交互	`tools.py`（32 工具）	工具描述当 prompt 写
阶4 Loop	循环怎么设计	`core.py:_continue_agent_loop`	简单循环 + 显式护栏

你可以把它理解成关注点"从模型逐渐外移到系统"的过程。阶 1 你盯着模型本身（怎么跟它说话），阶 4 你已经在设计整个系统的骨架（循环怎么转）。

有一点要先说清楚：这四阶不是"低级到高级"的鄙视链。 阶 1 是后面所有阶的基础，你进了阶 4 也照样要管 prompt。四阶的意思是，你的关注范围在扩大。

下面逐阶看 pixiu 的实证。

阶 1 Prompt：从"说漂亮话"到"分区 + 反例"

阶 1 不需要多讲——调 prompt。但 pixiu 的 system.md 展示了阶 1 的成熟形态：它不是一段平铺的指令，而是分区的、带反例的工程文档。

打开 prompts/system.md，你会看到它被切成几大块：

# 角色定义          ← 我是谁、用户是谁、职责边界
# 投资框架          ← 核心-卫星策略、仓位配比（参考信息）
# 风险底线          ← 15 条硬性约束（第1章讲过）
# 心理纪律提醒       ← 反例：用户说"等回本就卖"→ 提醒锚定效应
# 通用输出风格       ← 结论先行、区分事实与判断、说不确定

这个结构有两个阶 1 的成熟标志：

第一，分区。 "必须遵守的规则"（风险底线）和"参考信息"（投资框架、输出风格）被明确分开了。模型知道哪些是硬约束、哪些是软参考。平铺的 prompt 模型分不清轻重。

第二，反例。 心理纪律那段，每条都是一个"如果用户说 X → 你要提醒 Y"的反例模式。这些反例不是一开始就有的，是踩了坑之后一条条加上去的——好的 prompt 不是写出来的，是从错误里长出来的。

阶 2 Context：主动管理模型的视野

往 prompt 之外看的第一站是 Context——模型每次做决策时，能看到的所有信息。

阶 2 的核心认知是：模型的决策质量，取决于它决策那个瞬间能看到什么。 这跟你给它的指令写得好不好是两回事——指令是"告诉它怎么做"，context 是"让它看到什么"。

pixiu 的阶 2 实现在 prompts.py 的 _build_memory_context。它不是把所有信息一股脑塞进上下文，而是分层组装——什么时候注入记忆、什么时候注入持仓画像、什么时候注入用户最近的表达，都有讲究。

这里有一个我用 eval 逼出来的真实教训，标注号 W2-5：

问题：_extract_symbols 只提取消息里出现的股票代码，所以用户问"我的持仓哪只适合核心仓"时（没点具体票名），系统判定"无标的" → 不注入持仓画像 → LLM 拿不到画像，只能退回基本面分析。
量化结果：画像相关的 eval，pass_rate 只有 20%。
修复：_build_memory_context 加了"持仓画像概览"段——只要识别到组合级意图（持仓/组合/核心仓/配比/哪只等），就批量注入所有持仓的画像。
修复后：画像 eval pass_rate 从 20% 拉到 100%。

这件事我印象很深。它不是 prompt 的问题，也不是工具的问题，纯粹是"模型该看到的信息没让它看到"。 这就是阶 2——当你发现 agent "健忘"或"答非所问"时，第一反应不该是改 prompt，而该去查"它那个瞬间到底能看到什么"。

阶 2 的成熟标志：你开始主动管理模型的视野。哪些历史留、哪些丢、检索回来的资料怎么压缩、组合级意图怎么识别——这些是 context 层的功夫。Prompt 从"唯一重要的东西"变成了"context 的一部分"。

阶 3 Harness：工具是给模型看的 prompt

第 3 阶是这本书花最多笔墨的地方——第 3、4 章讲工具设计，本质上就是讲 harness。

Harness 是"模型之外的一切"。阶 1 你管模型（prompt），阶 2 你管信息（context），阶 3 你管模型和系统之间的交互接口——工具怎么定义、返回什么、失败了怎么办。

这个阶段的认知转变最剧烈，因为它彻底改变了你看待"接口"的方式。传统程序员把 API 文档当"给人看的说明"，到了阶 3 你才明白：工具接口是给模型看的 prompt。 工具描述里漏一句话，效果等同于 system prompt 里漏一句话。

pixiu 的阶 3 实现在 agent/tools.py——32 个工具，每一个的 description 都是按"给模型看"的标准写的。随便看一个：

python

"get_market_data": {
    "description": (
        "获取标的的日线行情数据（OHLCV）。需要先通过 download_data 下载过数据。"
        "不适用：查询是否交易日（用get_trading_info）、查分红（用get_dividend_data）。"
        "示例：用户问'中国神华最近走势' → {\"symbol\": \"601088\", ...}"
    ),
    ...
}

注意这三件事：它写了**"不适用"场景**（防止模型用错工具）、写了 few-shot 示例（教模型怎么调）、用大白话写（不堆术语）。这不是 API 文档的写法，这是 prompt 的写法。

阶 3 的成熟标志、以及 32 个工具的更多细节，第 4 章会展开。这里只先点一句：阶 3 是传统程序员的主场——接口设计、错误处理、数据流转，全是你的看家本领，换了一批新约束而已。

阶 4 Loop：简单循环 + 显式护栏

最后一阶，循环。当你把 prompt、context、harness 都搞定，最后一个问题是：这些东西怎么串起来？模型按什么流程去决策、调工具、拿结果、再决策？

阶 4 的核心认知是：保持循环简单，复杂度下沉到工具和提示词。

pixiu 的阶 4 实现在 core.py:_continue_agent_loop。它是一个 ReAct 循环，但你要是看核心逻辑，会发现循环体里几乎没有 if-else 编排——模型自己在循环里决定要不要调工具、调哪个、什么时候停。我要做的事情只有两件：给它工具、给它护栏。

护栏长什么样？pixiu 有三层：

迭代上限：max_iterations 防止无限循环；剩余迭代 ≤2 时强制不带工具调一次，逼模型给最终回复
卡住检测：连续 N 次相同调用、或连续 N 次失败 → 注入提示逼模型换路（详细在第 6 章）
悬空 tool_calls 防护：标注 W2-7——多 tool_call 响应里触发卡住检测时，要给剩余的 tool_call 补占位结果，否则下次 LLM 调用会因"缺 tool 结果"报 400

阶 4 的成熟标志：你开始质疑"我的循环是不是太复杂了"。当你发现自己写的 agent 越来越像一个庞大的状态机，你会停下来想——这些跳转，是不是本该让模型自己判断？

还有个更进阶的认知，pixiu 用"场景路由"做了实证：不是所有流程都该交给模型自决。 用户说"跑一下布林带回测"，这是确定性意图，pixiu 用 scene.py 关键词路由直接走预制路径（Service 备数据 + 专用 prompt），不走自由 Agent Loop。能确定的用编排，需要判断的才用自决循环。 这是阶 4 的精细版。

四阶不是线性的

画成一条直线是为了好讲，但真实的认知过程不是线性的。我自己就是反复跳着走——在 prompt 上栽了跟头，跳去重构循环，重构中发现工具设计有问题又跳回去改工具，改工具发现上下文管理不对又跳到 context。

所以不用纠结"我在第几阶"。四阶的价值在于给你一张地图——当你卡住的时候，知道除了 prompt，还有 context、harness、loop 三个方向可以排查。

这一章的工具：你在哪一阶？

诚实回答下面几个问题，看看你的关注范围覆盖了哪几阶：

阶 1 Prompt

[ ] 你的 system prompt 是分区的吗（硬约束 vs 参考信息）？还是平铺一段？
[ ] 有没有用反例（"如果用户说 X，你要 Y"）来约束模型？

阶 2 Context

[ ] agent "健忘"或"答非所问"时，你会去查"它那个瞬间能看到什么"吗？还是只知道改 prompt？
[ ] 你有没有主动管理过模型的视野（哪些历史留、组合级意图怎么识别）？

阶 3 Harness

[ ] 你写工具描述时，是当 API 文档写，还是当 prompt 写（带不适用场景、带示例）？
[ ] 工具失败时，返回的错误信息里有没有"下一步建议"？

阶 4 Loop

[ ] 你的 agent 执行循环，能用一句话描述吗？描述不出来是不是太复杂了？
[ ] 你有没有在代码里用 if-else 替模型做了它本该自己做的决定？

最危险的情况是：只关注阶 1，对 2/3/4 完全没意识——这意味着你看不到 prompt 之外的问题。

小结

四阶认知说到底就一句话：做 agent 不等于调 prompt。

从 prompt 往外走，有 context（给模型什么信息）、harness（模型怎么跟系统交互）、loop（循环怎么设计）。每一层 pixiu 都有真实代码做实证。而且——传统程序员有个隐藏优势：阶 3 和阶 4 涉及的系统设计，正是你的主场。

从下一章开始，我们进入这本书的第二部分——具体怎么把一个 agent 做出来。第 3 章先讲一个最容易被忽视、但在 pixiu 上教训最深的东西：工具的颗粒度。

第 3 章 · 颗粒度：工具的信息密度分层 —— 为什么 pixiu 要把回测做成 4 个不同粗细的工具。