--- name: investment-tracker description: "投资组合管理助手。可查询/更新持仓、现金、日记、权益曲线，以及通过截图导入持仓。" --- # Investment Tracker 操作手册 本文档供 AI 代理使用。基础 URL：`http://localhost:8000`。 接口详情见 `references/api-docs.md`。 --- ## 全局规则 ### 操作分级 | 类型 | 接口 | 执行前是否需要用户确认 | |------|------|----------------------| | **只读** | GET /api/holdings、GET /api/cash、GET /api/diary、GET /api/curve、GET /api/imports、GET /api/hs300 | **否**，直接执行并展示结果 | | **写操作** | POST /api/holdings/bulk、POST /api/cash、POST /api/diary、POST /api/curve/point、POST /api/imports/rollback/{id}、DELETE /api/imports/{id} | **是**，必须先展示预览，等用户回复"确认"后再执行 | | **分析+写** | POST /api/external/upload → POST /api/holdings/bulk | 分析步骤自动执行；写入步骤需用户确认 | ### 通用错误处理 | curl 错误 / HTTP 状态码 | AI 应对策略 | |------------------------|------------| | `curl: (7) Connection refused` | 提示用户："本地服务未启动，请在 backend 目录运行 `uvicorn main:app --reload --port 8000`" | | `503` | 提示用户："DASHSCOPE_API_KEY 未配置或无效，请检查 backend/.env 文件" | | `502` | 提示用户："AI 接口调用失败，请稍后重试" | | `404` | 提示用户："未找到指定记录，请确认 ID 是否正确" | | `400` | 将响应体中的 `detail` 字段内容告知用户 | --- ## 工作流 A：截图导入持仓 **触发词**：上传截图、导入持仓、更新持仓、今天持仓、截图持仓 ### Step 1：上传截图，获取分析结果 ```bash curl -sS -X POST http://localhost:8000/api/external/upload \ -F "images=@<图片绝对路径>" \ -F "notes=<用户补充说明，无则省略>" \ -F "portfolio_date=" ``` 多张截图时重复 `-F "images=@<路径>"` 参数。 **解析返回结果，向用户展示：** - `summary`：AI 点评 - `diff.added`：新增持仓（代码、名称、股数） - `diff.removed`：移除持仓（代码、名称） - `diff.modified`：变动持仓（代码、名称、before/after 对比） - `diff.unchanged_count`：未变动数量 - `total_assets` / `total_pnl`（若不为 null） **必须暂停**，向用户提问： > "分析完成，是否确认将以上变动更新至持仓系统？" ### Step 2：用户确认后，提交持仓更新 将 Step 1 返回的 `analyzed_holdings` 数组写入临时文件，然后提交： ```bash # 将 analyzed_holdings 写入临时文件（在当前工作目录） echo '' > /tmp/holdings_update.json curl -sS -X POST http://localhost:8000/api/holdings/bulk \ -H "Content-Type: application/json" \ -d "{\"holdings\": $(cat /tmp/holdings_update.json), \"label\": \" 截图导入\"}" rm /tmp/holdings_update.json ``` 成功后告知用户持仓已更新。 ### Step 3（可选）：更新权益曲线 若 Step 1 返回的 `total_assets` 不为 null，询问用户： > "本次截图识别到总资产 ¥，是否同时记录到权益曲线？" 用户确认后执行（日期取 Step 1 返回的 `date`）： ```bash curl -sS -X POST http://localhost:8000/api/curve/point \ -H "Content-Type: application/json" \ -d "{\"date\": \"\", \"value\": }" ``` --- ## 工作流 B：查询当前持仓 **触发词**：查看持仓、我的持仓、现在持仓、持仓情况、持仓列表 **直接执行（无需确认）：** ```bash curl -sS http://localhost:8000/api/holdings ``` **展示格式建议**（表格形式）： | 代码 | 名称 | 股数 | 成本价 | 现价 | 行业 | 备注 | |------|------|------|--------|------|------|------| | ... | ... | ... | ... | ... | ... | ... | 若返回空数组，告知用户："当前持仓为空。" --- ## 工作流 C：现金管理 **触发词**： - 查询：现金余额、账户现金、剩余资金 - 更新：更新现金、修改现金、现金改成、现金设为 ### 查询现金（只读，直接执行） ```bash curl -sS http://localhost:8000/api/cash ``` 取响应中的 `amount` 字段，告知用户当前现金余额。 ### 更新现金（写操作，需确认） 先告知用户将要执行的操作： > "将现金余额更新为 ¥，确认吗？" 用户确认后执行： ```bash curl -sS -X POST http://localhost:8000/api/cash \ -H "Content-Type: application/json" \ -d "{\"amount\": <数值>}" ``` 取响应中的 `amount` 字段，告知用户更新后的余额。 --- ## 工作流 D：投资日记 **触发词**： - 查看：查看日记、投资记录、操作记录、历史日记 - 新增：记一条日记、记录操作、今天买了/卖了、写日记 ### 查看日记（只读，直接执行） ```bash curl -sS http://localhost:8000/api/diary ``` 按日期倒序展示，包含字段：日期、类型、股票代码、备注、情绪。 若返回空数组，告知用户："暂无日记记录。" ### 新增日记（写操作，需确认） 从用户描述中提取信息，先展示将要记录的内容： > "将新增以下日记，确认吗？ > 日期： | 类型： | 代码： | 备注： | 情绪：" **`type` 可选值**：买入、卖出、观察、调仓、清仓 **`mood` 可选值**：理性、审慎、乐观、焦虑（若用户未指定，默认填"理性"） **`code`**：若用户未指定具体股票，填 `""` 用户确认后执行： ```bash curl -sS -X POST http://localhost:8000/api/diary \ -H "Content-Type: application/json" \ -d "{\"date\": \"\", \"type\": \"\", \"code\": \"\", \"remark\": \"\", \"mood\": \"\"}" ``` 取响应中的 `id` 字段，告知用户日记已记录（ID: ）。 --- ## 工作流 E：权益曲线 **触发词**： - 查看：权益曲线、资产走势、历史收益、组合表现 - 新增：记录今天资产、更新权益、今天总资产是 ### 查看权益曲线（只读，直接执行） ```bash curl -sS http://localhost:8000/api/curve ``` 展示日期与总市值的序列（按日期升序）。若数据点 ≥2，可计算区间涨幅告知用户。 若返回空数组，告知用户："暂无权益曲线数据。" ### 新增/更新数据点（写操作，需确认） 先告知用户将要执行的操作： > "将记录权益数据点： ¥，若该日期已存在则覆盖，确认吗？" 用户确认后执行： ```bash curl -sS -X POST http://localhost:8000/api/curve/point \ -H "Content-Type: application/json" \ -d "{\"date\": \"\", \"value\": <数值>}" ``` --- ## 工作流 F：沪深300基准对比 **触发词**：沪深300、基准对比、跑赢大盘、指数走势、大盘表现 **直接执行（无需确认）：** ```bash # 默认 180 个交易日 curl -sS "http://localhost:8000/api/hs300" # 指定天数（7～1000） curl -sS "http://localhost:8000/api/hs300?days=" ``` 返回 `date` / `close` 数组，按日期升序。 **展示建议**： - 告知最新收盘价和区间起止日期 - 若同时有权益曲线数据，计算同期组合涨幅与 HS300 涨幅进行对比 **错误处理**： - `502`：告知用户"沪深300数据获取失败，可能是网络问题或 Yahoo Finance 暂时不可用" - `404`：告知用户"Yahoo Finance 未返回有效数据，请稍后重试" --- ## 工作流 G：导入历史管理 **触发词**： - 查看：导入历史、历史记录、快照列表 - 回滚：回滚、撤销、恢复到上次、恢复到某次 - 删除：删除历史、清除记录 ### 查看导入历史（只读，直接执行） ```bash curl -sS http://localhost:8000/api/imports ``` 展示列表（按时间倒序）：ID、时间、标签、持仓条数。 ### 回滚到指定快照（写操作，需二次确认） 1. 先执行查看操作，展示快照列表供用户选择目标 ID 2. 展示目标快照信息，请求确认： > "将把持仓回滚到快照 #（