第 3 章 · 颗粒度：工具的信息密度分层

pixiu 锚点：agent/tools.py —— run_backtest → compare_strategies → sweep_backtest_params → deep_research 关键案例：W3-1 / W3-3 / W3-5（service 有、工具层没暴露），eval 100% pass

开篇：一个工具够吗？

pixiu 最早只有 run_backtest 一个回测工具——给一只票、一个策略、一段时间，跑出结果。

听起来够用了。直到有一天，用户在对话里问了一句很自然的话：

"海康威视适合用什么策略？"

你猜 agent 怎么干的？它只有 run_backtest，于是它一个策略一个策略地跑——dual_ma 跑一遍、macd 跑一遍、bollinger 跑一遍……8 个策略跑 8 次。每一次都把一堆收益、胜率、回撤的数据塞进上下文，跑完 8 次上下文快满了，它再从这一堆数字里"判"出个推荐。

这件事能成，但是又慢、又笨、又费 token。更要命的是，agent 跑完之后给的叙事分析很弱——因为它光顾着报数字了，没把"策略性格""适合核心仓还是卫星仓"这些高维度结论算出来。

这就是工具颗粒度的问题：只有一个粗工具，agent 就得用蛮力。

问题根源：service 有，工具层没有

我去查了 pixiu 的 service 层（service/backtest.py），发现一个尴尬的事实：多策略横向对比的能力，代码里早就写好了，只是没暴露给 agent。

这个发现被登记进了 findings 看板，标注 W3-3：

缺陷：策略竞技场（多策略横向对比+推荐）service 层有 compare_strategies 但未暴露给 agent/web → agent 无法"一次跑多策略"做高密度决策。用户愿景：agent 自主编排多策略/多轮回测决策。

类似的还有 W3-1（回测算了叙事，但叙事只用于内部存档，没返回给 agent）和 W3-5（没有"同策略不同参数"的扫描能力）。

这三个标注指向同一个病根：service 层的能力，和 agent 工具层暴露的能力，中间隔着一层。 工程师以为"功能做完了"，但对 agent 来说，没暴露的工具等于不存在。

解法：信息密度递增的工具阶梯

修复不是"加一个超级工具"，而是按信息密度的粗细，做成一串工具，让 agent 按场景自己选。

pixiu 最终的回测工具长这样，从粗到细四级：

工具	干什么	信息密度	适合场景
`run_backtest`	单策略单次回测	低（原始数字）	"测一下布林带在沪深300上"
`compare_strategies`	多策略横向对比 + 综合推荐	中（带适合度判断）	"海康适合什么策略"
`sweep_backtest_params`	同策略参数网格扫描，按 sharpe 标最优	中高（参数空间）	"布林带 window 用多少最好"
`deep_research`	聚合信号+基本面+回测画像+持仓+探索命中	高（全维度）	"帮我深入研究一下这只票"

关键细节：每个工具的描述里，都写明了"上一层比下一层适合什么"。 这是教模型怎么选。看 compare_strategies 的描述：

python

"description": (
    "策略竞技场：一次跑多个策略横向对比，返回每只策略的年化/回撤/胜率/适合度"
    "+综合推荐+买入持有基准。比单次 run_backtest 信息密度高，适合在决策场景"
    "（如'这只票能不能买/适合什么仓'）自主调用以支撑结论。"
)

注意这句"比单次 run_backtest 信息密度高，适合在决策场景"——它不是写给程序员看的 API 说明，它是写给模型的选型指引。模型读到这句，就知道遇到"能不能买"这种决策题时，该跳过 run_backtest 直接调 compare_strategies。

用 eval 验证：粒度对了，agent 就会自主决策

我怎么知道这套粒度真的有用？用 eval 检验。这是 pixiu lab 体系最硬的地方——每个工具改动都配一个可证伪的 eval。

W3-3E（验 compare_strategies 的价值）：

测试：问 agent "海康适合什么策略"——注意，不直接告诉它用哪个工具
预期：agent 应该自主调用 compare_strategies 跑多策略对比，给出带数据的推荐
结果：100% pass_rate（3/3，mean 0.97）——agent 每次都自主选用多策略对比工具撑结论

W3-5E（验 sweep_backtest_params 的价值）：

测试：问 "布林带 window 怎么选"
预期：agent 自主扫参数空间
结果：100% pass_rate（3/3，mean 0.97）——agent 自主扫 window=10/15/20/25/30，据 sharpe 一致推荐 window=30

这两个 eval 说明一件重要的事：工具粒度设计对了，agent 的"自主决策"能力是自然涌现的。 你不需要在 prompt 里教它"遇到这种问题调那个工具"——你只要把信息密度合适的工具摆在那、把选型指引写进描述，模型自己会选对。

颗粒度设计的三条原则

从 pixiu 这套工具里，我总结出三条：

1. 不要只有一种粒度。 只有粗工具，agent 得用蛮力（调很多次）；只有细工具，agent 拼不出全貌。要有粗有细，覆盖"探索"和"决策"两种场景。

2. 高密度工具留给决策场景。 compare_strategies/deep_research 这种带判断的工具，是给"要下结论"的场景用的；纯探索用 run_backtest 这种原始数据工具就够了。别让 agent 为了下个结论，去调十次低密度工具自己拼。

3. 用描述教模型选型，用 eval 验证它选对。 描述里写"比 XX 更适合 YY 场景"，再配一个"不指定工具"的 eval，看 agent 会不会自主选对。选不对，要么是描述没写清楚，要么是粒度还缺一层。

反面：不是越细越好

讲完"加工具"的一面，得讲讲"收工具"的一面——有些操作，颗粒度该往回收，甚至不该做成可执行工具。

pixiu 有个 manage_portfolio 工具，它现在的状态是只读——你让它买卖，它直接拒绝，告诉你"请在持仓页面手动操作"。为什么？因为 agent 曾经在执行买卖时，把用户真实持仓的成本和股数搞乱了。资金操作出错，后果比查数据严重得多。

这个故事是工具设计的另一面：有副作用、后果严重、不可逆的操作，要主动收权。 这个我们下一章展开——它牵出工具设计里更深的一层：工具不只是"能干什么"，还有"该不该让 agent 干"。

小结

工具颗粒度，是 harness 设计里最容易被忽视、但在 pixiu 上教训最深的一环。

一套好的工具，不是"功能全"，而是信息密度分层合理——让 agent 在不同场景下，能拿到刚好够用的那块拼图。pixiu 用"单次→对比→扫描→聚合"四级回测工具，加上 eval 验证，把这件事做实了。

下一章我们钻进工具描述本身——为什么说"工具描述是给模型看的 prompt"，以及 pixiu 怎么用 32 个工具的真实描述，把这句话变成可操作的规范。

第 4 章 · 工具描述是给模型看的 prompt —— 32 个工具的正反例，外加一个 agent 弄坏持仓的血的教训。