# 养基场 — AI 基金管理助手

养基场是一个 AI 驱动的基金管理工具，让 AI Agent 帮你查看行情、分析基金、管理持仓。

---

## 快速开始

### 1. 安装 CLI

```bash
npm install -g https://www.myfundfarm.com/cli/fundfarm-cli-0.2.11.tgz
```

### 2. 登录账号

```bash
fundfarm login
```

使用手机短信验证码登录。新用户会自动注册，无需提前开户。

> 登录后 Token 保存在本地 `~/.fundfarm/config.json`，后续使用无需重复登录。

### 3. 验证连接

```bash
fundfarm whoami
```

返回示例：
```
## 👤 当前身份

- **手机号**: 138****8888
- **用户ID**: YJC10001
- **捐助状态**: 已捐助
```

---

## 可用命令

### 📊 市场查询

| 命令 | 说明 | 示例 |
|------|------|------|
| `fundfarm market` | A 股大盘行情 + 板块涨跌 | `fundfarm market` |
| `fundfarm search <关键词>` | 搜索基金 | `fundfarm search 医疗` |
| `fundfarm fund <基金代码>` | 基金详情 | `fundfarm fund 161725` |
| `fundfarm ranking` | 基金涨跌幅排行榜 | `fundfarm ranking --sort return_1m` |

**fund 子选项：**
```bash
fundfarm fund <code>                  # 基金概况
fundfarm fund <code> --history        # 历史净值
fundfarm fund <code> --holdings       # 重仓股
fundfarm fund <code> --sectors        # 行业配置
fundfarm fund <code> --estimate       # 盘中估值
fundfarm fund <code> --transactions   # 单只基金交易历史
fundfarm fund <code> --transactions --json --limit 50  # 结构化输出，更适合 Agent
```

### 📈 持仓管理

| 命令 | 说明 |
|------|------|
| `fundfarm portfolio` | 资产概览 + 持仓列表 + 收益情况 |
| `fundfarm watchlist` | 自选基金列表 |
| `fundfarm watchlist add <代码> --yes` | 添加自选 |
| `fundfarm watchlist remove <代码> --yes` | 移除自选 |
| `fundfarm knowledge add [标题] --content <正文> --yes` | 写入知识库（仅捐助用户） |
| `fundfarm knowledge list` | 列出知识库条目 |
| `fundfarm knowledge get <ID> --content-only` | 读取知识原文给本地 Agent 分析 |
| `fundfarm holdings import <代码> --market-value <市值> --profit <收益> --nest <鸡窝ID> --platform <平台> --yes` | 导入单个持仓（已有持仓则覆盖并记为 Agent 修改） |
| `fundfarm holdings batch-import <文件> --nest <鸡窝ID> --platform <平台> --yes` | 批量导入持仓 |
| `fundfarm portfolio --transactions` | 查看近期交易；若该笔记录有明确交易时间，会一并显示 |

### 💰 交易操作

| 命令 | 说明 |
|------|------|
| `fundfarm trade buy <代码> --amount <金额> --nest <鸡窝ID> --platform <平台> --time <交易时间> --yes` | 买入基金（支持鸡窝/平台；仅在用户明确提供交易时间时传 `--time`） |
| `fundfarm trade sell <代码> --shares <份额> --nest <鸡窝ID> --platform <平台> --time <交易时间> --yes` | 卖出基金（支持鸡窝/平台；仅在用户明确提供交易时间时传 `--time`；单次 ≤50% 持仓） |
| `fundfarm trade cancel <交易ID> --yes` | 撤销交易（自动回滚持仓） |

> ⚠️ **重要**：所有写操作默认需要交互式确认。AI Agent 自动化使用时请加 `--yes` 跳过确认。  
> 使用 `--dry-run` 可以仅预览操作而不实际执行。

### 🤖 AI 分析

| 命令 | 说明 |
|------|------|
| `fundfarm ai report` | 获取最新的 AI 持仓分析报告 |
| `fundfarm ai analyze --yes` | 运行 AI 深度分析（消耗 AI 额度） |

### 🔍 信息查询

| 命令 | 说明 |
|------|------|
| `fundfarm whoami` | 当前登录身份 |
| `fundfarm --help` | 查看全部命令 |

---

## 写操作安全机制

所有写操作具有**多层安全保护**：

**后端（无法绕过）：**
- JWT 认证 + 用户隔离：只能操作自己的数据
- 操作白名单：仅允许 8 个特定写操作
- 频率限制：每日 ≤30 次，每分钟 ≤10 次
- 卖出熔断：单次卖出 ≤50% 持仓
- 买入上限：单笔 ≤100 万元
- 审计日志：每次调用记录用户、操作、IP

**CLI 端（纵深防御）：**
- 交互式确认：`⚠️ 确认执行此操作？(y/N)`
- `--yes` 跳过确认（后端安全网仍生效）
- `--dry-run` 仅预览不执行
- 输入校验：基金代码、金额、UUID 格式在请求前校验
- `knowledge add` 仅捐助用户可用；成功写入后会立刻在网页知识库中可见，并后台向量化
- `holdings import` / `batch-import` 支持可选鸡窝和平台；不传时自动回退默认鸡窝和默认平台“支付宝”
- 导入前会按“基金代码 + 鸡窝”检查现有持仓，并明确提示是 Agent 导入 还是 Agent 修改
- `trade buy/sell --time` 表示用户明确提供的交易时间，仅用于自动判断净值归属日与 pending；如果页面只有日期没有时间，不要猜测时间，也不要想当然地传当前时间
- Agent 执行买入/卖出前，建议和用户确认基金代码、金额/份额、鸡窝、平台、是否能确认成交净值、是否能确认交易时间；若无法确认交易时间，则不传 `--time`

**撤销安全：**
- `trade cancel` 只能删除 Agent 创建的交易记录
- 用户手动录入的交易不可通过 CLI 删除
- 撤销时自动回滚持仓份额和成本

---

## 典型对话

```
用户: 今天大盘怎么样
→ fundfarm market

用户: 查一下 161725 这只基金
→ fundfarm fund 161725

用户: 看看我的持仓
→ fundfarm portfolio

用户: 帮我搜一下医疗相关的基金
→ fundfarm search 医疗

用户: 这只基金的重仓股是什么
→ fundfarm fund 161725 --holdings

用户: 把 161725 加到自选
→ fundfarm watchlist add 161725 --yes

用户: 把一段投资原则写入知识库
→ fundfarm knowledge add "我的投资纪律" --content "..." --yes

用户: 读取知识条目 12 给本地 Agent 分析
→ fundfarm knowledge get 12 --content-only

用户: 导入我已有的 161725 持仓到鸡窝 3
→ fundfarm holdings import 161725 --market-value 12000 --profit 800 --nest 3 --platform 支付宝 --yes

用户: 帮我买入 2000 元 161725
→ fundfarm trade buy 161725 --amount 2000 --nest 3 --platform 支付宝 --time 2026-04-02T14:35:00 --yes

用户: 卖出 500 份 161725
→ fundfarm trade sell 161725 --shares 500 --nest 3 --platform 支付宝 --time 2026-04-02T15:20:00 --yes

说明：
- `--time` / `transaction_time` = 用户明确提供的交易时间（可选）
- `transaction_date` = 净值归属日
- `created_at` = 记录写入时间；只有当交易时间已明确确认时，前端才会把它当作交易时间显示

用户: 撤销刚才的交易
→ fundfarm trade cancel <transaction_id> --yes

用户: 分析一下我的持仓
→ fundfarm ai analyze --yes
```

---

## 输出格式

所有命令输出 **Markdown 纯文本**，AI Agent 可直接解析，无需处理 JSON。

持仓命令支持 `--format json` 输出结构化 JSON。

---

## 使用限制

| 用户类型 | 每日调用次数 |
|----------|------------|
| 免费用户 | 5 次 |
| 捐助用户 | 无限次 |

> 捐助支持：https://myfundfarm.com/#/support

---

## 备选方式：MCP 接入

如果你的运行环境支持 MCP 协议，也可以通过 MCP 接入养基场：

**Cursor / Claude Desktop（推荐，无需 API Key）：**
```json
{
  "fundfarm": {
    "command": "npx",
    "args": ["-y", "mcp-remote", "https://api.myfundfarm.com/mcp"]
  }
}
```
首次连接会自动弹出浏览器进行 OAuth 授权登录。

**需要 API Key 的环境：**

登录 https://myfundfarm.com → 设置 → AI 智能体 → 生成 API Key，然后配置：
```json
{
  "fundfarm": {
    "command": "npx",
    "args": ["-y", "mcp-remote", "https://api.myfundfarm.com/mcp", "-H", "Authorization: Bearer <你的API_KEY>"]
  }
}
```

**OpenClaw：**
```bash
npx skills add cedar202510-dotcom/fundfarm-skill
```
然后告诉 AI：帮我连接养基场系统

---

## MCP 工具列表（MCP 方式可用）

通过 MCP 接入时，以下工具可通过 MCP 协议自动发现：

### 基金查询
| 工具 | 说明 |
|------|------|
| `search_funds` | 搜索基金 |
| `get_fund_detail` | 基金详情 |
| `get_fund_nav_history` | 历史净值 |
| `get_fund_top_holdings` | 重仓股 |
| `get_fund_sector_allocation` | 行业配置 |
| `get_fund_estimate` | 盘中估值 |
| `get_fund_ranking` | 基金排行榜 |

### 市场数据
| 工具 | 说明 |
|------|------|
| `get_market_indices` | 大盘指数 |
| `get_sector_ranking` | 板块涨跌 |
| `get_market_status` | 交易状态 |

### 用户持仓
| 工具 | 说明 |
|------|------|
| `get_my_holdings` | 持仓及收益 |
| `get_my_watchlist` | 自选基金 |
| `get_portfolio_summary` | 组合概览 |
| `get_my_sectors` | 板块分布 |
| `get_my_nests` | 鸡窝列表 |
| `get_transactions` | 交易流水 |

### AI 分析
| 工具 | 说明 |
|------|------|
| `get_latest_ai_report` | 获取最新 AI 报告 |
| `run_ai_analysis` | 运行 AI 深度分析 |

### 写操作
| 工具 | 说明 |
|------|------|
| `add_to_watchlist` | 添加自选 |
| `remove_from_watchlist` | 移除自选 |
| `add_holding` | 买入 |
| `batch_add_holdings` | 批量买入（最多50笔） |
| `import_holding` | 导入单个持仓（已有持仓则覆盖并记为 Agent 修改） |
| `batch_import_holdings` | 批量导入持仓（最多50条） |
| `sell_holding` | 卖出（单次≤50%持仓） |
| `delete_transaction` | 撤销交易（只能删除 Agent 创建的记录） |

写操作限制：每日≤30次，每分钟≤10次。

---

## 安全

- 所有数据绑定用户，只能访问自己的持仓
- CLI 登录凭证保存在本地 `~/.fundfarm/config.json`
- OAuth Token 自动续期，无需反复登录
- API Key 有效期 90 天
- 写操作有白名单 + 频率限制 + 卖出熔断
- 撤销操作只能删除 Agent 创建的交易记录

---

## 数据新鲜度

| 时段 | 净值数据 | 估值数据 |
|------|---------|---------||
| 盘中 9:30-15:00 | 昨日确认净值 | 实时估值涨跌 |
| 盘后 15:00-19:00 | 昨日确认净值 | 收盘估值 |
| 净值公布后 ~19:00+ | 今日确认净值 | 等于实际值 |

---

养基场官网：https://myfundfarm.com