引言 · 为什么用 pixiu 讲 agent 工程

先交代一个遗憾

我之前写过一本 agent 工程手记。那本手记的观点，我自己觉得站得住——什么"Agent = Model + Harness"，什么"四阶认知"，什么"循环要简单、复杂度下沉"。但读完的人给过我一种反馈，翻译成大白话就是：道理都对，就是不够过瘾。

我后来想明白这个"不够过瘾"是什么了。那本手记是从一堆零散的经验里归纳出来的，每个观点都能自圆其说，但观点背后的案例东一个西一个，甚至有些代码片段来自不同的项目。读起来像一个人在讲道理，不像一个人在讲他自己亲手做出来的那个东西。

这本手记就是来补这个遗憾的。

它的规则只有一条：所有观点，都必须长在同一个项目上——pixiu。

pixiu 是什么

pixiu（貔貅）是我做的一个人工智能 A 股投资工作台。

不是 demo，不是教程配套仓库，是我自己每天在用的东西。它干这些事：从 Tushare 拉行情和财务数据、跑策略回测、扫描买卖信号、管理持仓和盈亏、定时生成晨报和收盘总结、还有一个 AI 对话助手帮你分析"这只票能不能买"。

它的体量不大不小，正好够讲清楚 agent 工程的方方面面：

32 个 agent 工具——行情、分红、回测、信号、持仓、审计、新闻、选股、概念板块……每一个都是"算"的能力暴露给 LLM
一个完整的 ReAct 循环——带最大迭代数护栏、带卡住检测、带场景路由
一套韧性机制——LLM 熔断器、重试、限频冷却
一套 eval 基础设施——用统计方法对付 LLM 的非确定性
一套工程底线——双引擎数据库架构、CI、lint、Docker 部署

最关键的是——它跑在生产环境里，连着我自己的真实持仓和真金白银。 所以它踩过的坑，都是真坑；它做的每一个防御性设计，都是被现实教训出来的。

这本书里所有案例，你都能在 pixiu 的源码里找到对应。我会在每一处标注它来自哪个文件、哪个标注号。

半年做了什么

pixiu 不是一周写出来的。它经历了半年的演进，这条弧线本身就是这本书的叙事主线：

早期搭建——把量化能力（策略、回测、信号、持仓）做成工具，让 LLM 调用
定位转折——跑通基础功能后，我意识到它该是"个人投资助手"而不是"量化工具箱"，于是引入角色、投资框架、15 条风险纪律
理论落地——我有意识地把 agent-loop / prompt / context 这些理论，结合 pixiu 的代码去验证。我甚至在 pixiu 里建了一个 docs/lab/ 实验区，专门用"可证伪假设 → 实验 → 数据 → 结论"的流程去检验手记里的命题
v3.0 进化——把多个策略融合成投票机制、引入"投资人格"、加自主探索引擎
韧性收尾——加熔断、加 eval、加 CI、做了一轮又一轮的巡检（我管它叫 Wave），把藏着的 bug 和空壳功能一个个挖出来

这本书的章节顺序，大致就是顺着这条弧线来的。

跟我上一本手记什么关系

互补，不重复。

上一本讲"道理"，这一本讲"道理在一个真实项目里长什么样"。上一本里我说"工具描述要当 prompt 写"，这一本里我会打开 pixiu 的 tools.py，指着 32 个工具的真实描述告诉你：这句"不适用场景"是怎么救了我的、那句"⚠️别反复重试"是怎么写进去的。

如果你没读过上一本，没关系，这本自成体系。如果你读过，这本会给你一种"终于看到落地版"的踏实感。

这本书的特别之处：一套标注体系

为了把"观点"和"代码"锚定在一起，我在 pixiu 里建了一套研究标注体系，你会在这本书里反复看到它们：

标注	含义	典型出处
R1 / R2	鲁棒性 / 熔断实验	`llm.py`、`tushare_provider.py`
E1–E4	eval 实验（EDD、打分、非确定性、卫生）	`pixiu/eval/`、`docs/lab/`
Q1 / Q2	单人 CI 价值 / 空壳识别	CI、巡检
C1	驾驭曲线自观	贯穿全程
W1–W5	Wave 巡检波次挖出的问题	`docs/lab/findings.md`

每一个标注背后都是一个"假设 → 实验 → 数据 → 结论"的真实故事。比如 W2-5 是我用 eval 发现"画像注入覆盖率不够"，把 pass_rate 从 20% 做到 100%；R2 是我加熔断器，根治了 scheduler 因为 LLM 连续失败而"空转一整夜"的毛病。这些故事，就是这本书的骨架。

你会拿到什么

我不喜欢"你将收获……"这种话术。说点实在的。读完这本书，你手里应该会多几个能直接对照自己项目检查的东西：

一张"算 vs 判"的分工表，帮你切分哪些该交给代码、哪些该交给 LLM
一套工具设计原则，附带 pixiu 32 个工具的真实描述做正反例
一个"卡住检测 + 护栏"的循环模板，附 core.py 的真实实现
一套用 eval 对付非确定性的打法，附"pass_rate 20%→100%"的完整修复链
一张错误分流表（瞬时/可自修正/需用户/未预期），附熔断器的真实代码
一条"驾驭曲线"，让你看清自己跟 agent 的协作处在哪个阶段

更重要的是，这本书里到处都是我被现实教训过的痕迹。我希望你踩到同样的坑时，能想起"pixiu 这里也栽过"，然后少疼一点。

这本书不讲什么

诚实比完整更重要，先交代边界：

不讲模型训练和微调。 pixiu 用的是别人训好的模型（DeepSeek），这本书讲怎么用好它，不是怎么训它。
不讲多模态。 pixiu 是文本 agent，图像语音这些我没实践，不敢乱讲。
不是从零实现框架的教程。 这本书讲"判断和方法"，不重复造轮子。
不回避没解决的问题。 pixiu 还有些我暂缓处理的毛病（比如 Tushare SDK 没法加 timeout、概念板块数据源受套餐限制），我会在相关章节诚实交代，不粉饰。

怎么读

每一章都有一个"pixiu 锚点"段落，告诉你这章的内容对应 pixiu 的哪些文件和标注。你可以边读边打开 pixiu 源码对照——这是我写这本书时最在意的事：每一个结论都能在代码里被你亲手验证，而不是只能信我一张嘴。

走吧，从第 1 章开始。我们从 pixiu 最根本的一个设计判断讲起——哪些事交给代码算，哪些事交给 LLM 判。