# rust-agent-study

**Repository Path**: xj009/rust-agent-study

## Basic Information

- **Project Name**: rust-agent-study
- **Description**: 记录自己对Rust Agent的学习
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-23
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# myagent —— 一个从零实现的 Rust Agent

> 学习项目：用 14 天从零搭建一个可运行的 Agent（会话、事件流、工具闭环、会话级记忆），架构参考 OpenAI Codex（`session / submission / event / turn` 模型）。
>
> 当前定位：**结构完整、链路真机验证过的实验骨架**，可用于学习与二次开发。真实业务能力正在按路线图逐步接入（见 [Roadmap](#roadmap)）。

## 当前能力

- 真机对话：CLI 输入文字 → DeepSeek（Responses API，非流式）真实回答。
- 回合生命周期事件：`TurnStarted / AgentMsg / ToolCalled / ToolResult / TurnComplete / TurnAborted / Error` 全走事件通道。
- 工具闭环：模型发起工具调用 → 执行 → 结果回填 → 再询问模型，直到给出最终答案。
- 动态工具注册：`ToolRegistry`（声明 + async 执行成对注册、按名查找、未知工具安全 fallback）。
- 会话级记忆：跨回合历史前缀，新回合能理解“那上海呢”这类指代。
- 交互控制：`/interrupt` 中断当前回合、`/exit` 干净退出、忙时拒绝新输入。
- 真实天气：`get_weather` 走 Open-Meteo（免 key），内置北京/上海/广州/深圳城市表。

## 架构

四个 workspace crate，依赖单向、无环：

```text
myagent-types    协议数据模型（对标 codex-types）—— 被其它 crate 依赖
myagent-runtime  引擎：Session / 事件循环 / run_turn / ToolRegistry / 模型抽象 —— 依赖 types
myagent-tools    工具实现：真实天气(weather.rs)、模拟行情 —— 依赖 types + runtime
myagent-cli      应用层：stdin 解析 + 组装模型与工具 + 事件打印 —— 依赖 types + runtime + tools
```

信息流：

```text
stdin → Submission ──(tx_sub)──▶ submission_loop 分发
                                   │ UserInput
                                   ▼
                              run_turn（模型 ← 会话历史+本回合历史+工具声明）
                                   │ 需要工具?
                                   ▼
                        registry.execute(tool_call).await  ← myagent-tools
                                   │ 结果回填历史
                                   ▼ 循环直到最终回答 → TurnComplete
模型/工具/生命周期的全部输出 ──(tx_event)──▶ 事件消费者（当前为 print）
```

## 目录结构

```text
myagent-types/src/lib.rs       Op/Event/EventMsg/Submission/ToolCall/ToolResult/HistoryItem/TurnContext/ToolSpec
myagent-runtime/src/lib.rs     核心：Session::spawn / submission_loop / run_turn / ToolRegistry / merge_history
myagent-runtime/src/model.rs   ModelProvider trait / ModelReply / chat()（DeepSeek Responses API）
myagent-tools/src/lib.rs       demo_tools()：注册天气与行情工具
myagent-tools/src/weather.rs   免 key 天气数据源（Open-Meteo）
myagent-cli/src/main.rs        stdin 读取、命令解析（/interrupt、/exit）、spawn 组装
myagent-cli/src/lib.rs         事件格式化（format_event）、id 生成（next_id）
```

## 快速开始

需要 Rust（edition 2021）。真实对话依赖 DeepSeek API Key：

```bash
export DEEPSEEK_API_KEY=sk-xxx
cargo run -p myagent-cli
```

试试：

```text
上海现在天气怎么样，请用 get_weather 查询
查一下 000001 的股价，请用 get_stock_quote 查询
/interrupt    # 中断当前回合
/exit         # 退出
```

> `get_weather` 已接真实数据；`get_stock_quote` 目前返回模拟行情。

## 测试

```bash
cargo test --workspace        # 10 个离线测试（会话/事件/工具闭环/历史）
```

联网测试默认忽略（需要 `DEEPSEEK_API_KEY` / 网络）：

```bash
cargo test -p myagent-runtime test_tool_loop_deepseek -- --ignored
cargo test -p myagent-tools test_fetch_now_beijing -- --ignored
```

## 当前边界

- 非流式输出；中断是“检查点式”，打不断进行中的 HTTP 请求。
- 无持久化：会话历史只存内存，进程退出即丢失。
- 无审批 / MCP / skill / 沙箱。
- 行情为模拟数据；指数分析工具尚未实现。

## Roadmap

- [ ] 指数分析工具（数据源：Tushare）：
  - `index_daily` 取行业指数收盘点位 → 计算 RPS（20/60/120 日相对强度）；
  - 估值信号：行业指数 PE/PB 需按“成分股 + 权重”聚合自算 → 引入本地股票数据库（成分表、个股日频 `daily_basic`）；
  - 封装为 async 工具接入 `myagent-tools`，由 CLI/定时任务调用。
- [ ] 轻量持久化 / resume（会话历史落盘，重启续聊）。
- [ ] 流式 SSE、skill、MCP（按需后置）。

## 市场数据管道（myagent-store）

`myagent-store` / `myagent-store-cli` 是独立于 agent 的行情数据管道：从 Tushare 拉原始数据入库（MySQL `market`），本地计算派生表。

- 原始表：`trade_cal`(交易日历)、`daily_basic`(个股市值/PB)、`stock_income`(归母净利润)、`index_daily`(99 只中证/国证行业指数日K)、`index_weight`(月末成分权重快照)。
- 派生表：`index_rps`(RPS 百分位 + 强度共振)、`index_valuation`(市值加权 PE_TTM/PB + 3y/5y/10y 窗口百分位与 p30/p50/p70 分位点，历史不足窗口或样本不足时整组 NULL)。
- 表结构迁移脚本见 `myagent-store/sql/`。

每日收盘后：

```bash
myagent-store-cli daily-update 20260907
# 流程: 日历扩展 -> 个股/指数日K增量 -> index_weight 月末门控刷新 -> RPS 重建 -> 估值单日增量(含窗口百分位)
```

信号有效性检验（随机基准对照，本地秒级）：

```bash
myagent-store-cli signal-bench
# 共振启动日 vs 同指数同数量随机日：250日最大涨幅 + 固定持有10/20/60日对照
# 可用 --start/--end/--rounds/--seed/--hold 覆盖默认(20160101~20250806, 3轮, seed固定)
```

**重算触发规则**：估值窗口百分位基于历史行计算，以下情况会使历史估值（及百分位）失效，须跑 `index-valuation backfill` 全量重算（CLI 会在对应命令后自动提示）：

- `stock-income refresh` 有新财报入库；
- `index-weight refresh` 或 `daily-update` 拉到新月份成分快照。

## 参考

- [OpenAI Codex](https://github.com/openai/codex)：架构参考（session/submission/event/turn、工具注册与路由）。
- [DeepSeek](https://www.deepseek.com/)：对话模型（Responses API）。
- [Open-Meteo](https://open-meteo.com/)：免 key 天气数据源。
- 数据源商标与数据版权归各数据源所有，本仓库不包含其数据。

## License

[MIT](LICENSE)