这个项目是 Python 写的，MIT 开源，pip install clawquant 一行装完。它不是一个交易机器人，而是一套量化研究基础设施——回测引擎、参数扫描、信号雷达、报告生成、模拟/实盘部署，六个命令组，十七个子命令，覆盖从数据到上线的完整链路。
pip install clawquant
clawquant --help
但真正让它与众不同的，不是这些功能本身，而是每一个功能都原生支持 --json 输出。
为什么 --json 是 Agent-First 的基石
这个设计决策看起来微不足道，实际上是整个架构的关键支点。
传统 CLI 工具的输出是给人看的：表格、彩色文字、进度条。AI Agent 拿到这些东西，要么用正则硬解析（脆弱），要么让 LLM 去"读"（浪费 token 且不可靠）。ClawQuant 的做法是：每个子命令都有 --json flag，输出结构化的 JSON，字段稳定、语义明确。
这意味着 Agent 可以直接 json.loads() 拿到回测结果的夏普比率、最大回撤、胜率，不需要任何中间解析层。这听起来简单，但你去看看市面上的量化框架，能做到这一点的凤毛麟角。大部分框架的 CLI 输出是给 print() 美化过的字符串，压根没考虑过程序化消费的场景。
六个 Skill YAML：Agent 的「说明书」
光有 JSON 输出还不够。Agent 需要知道：有哪些命令可用？每个命令接受什么参数？参数的类型和约束是什么？预期输出的 schema 是什么？
ClawQuant 为此提供了 6 个 Skill YAML 文件：
- quant_data_pull — 从交易所拉取 OHLCV 数据
- quant_backtest_batch — 批量回测多个标的×多个策略
- quant_backtest_sweep — 参数网格扫描 + Walk-forward 验证
- quant_radar_scan — 多标的实时信号扫描
- quant_report_get — 生成 JSON/Markdown/图表报告
- quant_deploy — 模拟盘或实盘部署
这些 YAML 本质上是 Agent 的工具描述文件。如果你用过 OpenAI 的 function calling 或者 Claude 的 tool use，你会立刻理解这个设计的意图——它把每个 CLI 命令包装成了 Agent 可以直接调用的「技能」，包含参数定义、类型约束、使用示例。Agent 不需要"猜"怎么用这个工具，YAML 里写得明明白白。
这里有个很聪明的设计：Skill YAML 和 CLI 命令是一一对应的，而不是在 CLI 之上再封装一层 API。这意味着人类和 Agent 用的是同一套接口，调试的时候你可以直接在终端跑同样的命令验证结果，不存在"Agent 调的接口和我手动测的不一样"的问题。
一个自然语言驱动的完整工作流
想象一个场景：你对 Agent 说——
"在 BTC 和 ETH 上对比 DCA、均线交叉、网格三个策略，过去 10 天的数据，给我 top3 报告。"
Agent 的编排过程是这样的：
- 调用
quant_data_pull，拉取 BTC 和 ETH 的 10 天 OHLCV 数据 - 调用
quant_backtest_batch，2 个标的 × 3 个策略 = 6 组回测 - 根据回测结果的综合评分排序，取 top3
- 调用
quant_report_get，为 top3 生成详细报告
整个过程，Agent 读 Skill YAML 知道怎么调，读 JSON 输出知道结果是什么，不需要任何人类干预。这才是「Agent-First」的真正含义——不是说"我们的工具支持 AI"，而是从第一行代码开始就为 Agent 消费而设计。
回测引擎：该有的严谨一个不少
虽然文章重点是 Agent-First 设计，但底层引擎如果不靠谱，上面的一切都是空中楼阁。ClawQuant 的回测引擎有几个值得注意的点：
事件驱动 + 下一根 K 线开盘成交。这是避免未来函数（look-ahead bias）的标准做法。你的策略在当前 K 线收盘时产生信号，但成交价用的是下一根 K 线的开盘价。很多新手量化框架在这里翻车，用收盘价同时产生信号和成交，回测结果漂亮得不真实。
参数网格扫描 + Walk-forward 验证。backtest sweep 命令支持对策略参数做网格搜索，并且用 Walk-forward 方法防止过拟合。这不是什么新技术，但作为 CLI 一个子命令直接提供，省去了自己写循环的麻烦。而且用了 ProcessPoolExecutor 做并行，多核机器上扫参数会快很多。
可复现性。每次回测输出 run_meta.json，记录策略名、参数、数据范围、引擎配置。相同输入，确定性结果。这个对 Agent 尤其重要——Agent 需要能可靠地对比不同 run 的结果，如果引擎本身有随机性又不记录种子，对比就毫无意义。
自定义策略：继承一个 ABC 就行
内置了 7 个策略（DCA、MA Crossover、Grid、RSI、Bollinger Bands、MACD、Donchian Breakout），但核心是 BaseStrategy 这个抽象基类，6 个抽象方法：
class MyStrategy(BaseStrategy):
def name(self) -> str:
return "my_momentum"
def default_params(self) -> dict:
return {"lookback": 20, "threshold": 0.02}
def init_state(self, params) -> dict:
return {"position": 0}
def on_bar(self, bar, params, state) -> Signal:
# 核心逻辑：根据当前K线和状态产生信号
if bar.close > bar.open * (1 + params["threshold"]):
return Signal.BUY
return Signal.HOLD
def param_grid(self) -> dict:
return {"lookback": [10, 20, 50], "threshold": [0.01, 0.02, 0.05]}
def description(self) -> str:
return "Simple momentum strategy"
这个设计很干净。on_bar 是逐根 K 线调用的，state 由你自己管理，引擎负责信号到订单的转换和资金管理。param_grid 方法直接定义了扫描空间，和 backtest sweep 命令无缝衔接。
五维评分体系：不只看收益
ClawQuant 的评分不是单纯看夏普比率或总收益。它用 5 个维度加权打分：
- Quality（30%） — 收益质量，夏普、索提诺等
- Risk（30%） — 最大回撤、波动率
- Robustness（20%） — Walk-forward 稳定性
- Cost Sensitivity（10%） — 对交易成本的敏感度
- Overtrade（10%） — 过度交易惩罚
这个权重分配很务实。Quality 和 Risk 各占 30% 说明它不偏向激进策略，Robustness 20% 是对过拟合的显式防御，最后两个各 10% 关注实盘可行性。对 Agent 来说，一个综合分数比五个独立指标更容易做决策——排序、筛选、对比，一个数字搞定。
安全阀：实盘部署的显式确认
deploy 命令支持 Paper Trading 和 Live Trading，但实盘需要传 --i-know-what-im-doing 这个 flag。这个设计在 Agent 场景下尤其重要——你绝对不想让 Agent 在一次"帮我优化策略"的对话中，不小心把一个未经验证的策略直接推上实盘。这是一个简单但有效的安全阀，强制在 Agent 的工具描述层面就把实盘操作标记为高危动作。
给独立开发者的落地建议
如果你正在做任何涉及「AI Agent 驱动外部工具」的项目，ClawQuant 的设计模式值得借鉴，核心就三条：
所有输出必须有结构化模式。不管你的工具是 CLI、API 还是 SDK，确保每个操作都有
--json或等价的结构化输出。这是 Agent 能可靠工作的前提，没有这个，后面的一切都是在沙子上建房子。为 Agent 写工具描述文件。不要指望 LLM 通过读
--help文本就能正确使用你的工具。写明确的 schema——参数名、类型、约束、示例。Skill YAML、JSON Schema、OpenAPI spec，哪个都行，关键是要有。人类和 Agent 共享同一套接口。不要为 Agent 单独建一层 API，然后人类用另一套 UI。共享接口意味着你只需要维护一套逻辑，调试时人类可以直接复现 Agent 的操作路径。
ClawQuant 目前 66 stars，还是个早期项目，代码量不大，很适合花一个下午通读一遍，理解它的架构决策。对于想让 AI Agent 真正落地到业务流程中的开发者来说，这套「结构化输出 + 工具描述 + 共享接口」的三件套，比任何花哨的 Agent 框架都更实用。