> ## Documentation Index
> Fetch the complete documentation index at: https://platform.kimi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 金融组合复盘智能体设计

> 介绍官方金融组合复盘智能体的三种持仓输入方式、记忆库增量更新机制，以及 Excel 底稿和 HTML 报告双产物，并提供起始配置、运行成本估算与搭建指南。

人工完成一次月度组合复盘，通常需要 4–8 小时。官方金融组合复盘智能体一次全量复盘耗时约 40–60 分钟，后续增量复盘耗时更短；实测偶有达到 `max_steps` 上限而失败并需要重试的情况，人工负责复核与决策。

最终交付带公式、可继续编辑的 Excel 数据底稿，以及结论先行、可提交投委会的 HTML 复盘报告。智能体仅用于复盘分析，不执行交易，也不提供买卖指令。

![金融组合复盘智能体产物演示：组合复盘 HTML 报告，从 KPI 卡片、关键结论到净值曲线、贡献归因、月度节奏、风险指标与附录口径与缺口](https://mintcdn.com/moonshotcn/5VWEjSPrQEFbCdz-/videos/portfolio-review.gif?s=16907e471f3effd1d6514e3fd557f489)

## Agent 架构总览

![金融组合复盘智能体：投资者经会话提交复盘任务并提供持仓，智能体从记忆库读取历史状态决定 full 或 fast 模式，通过机构金融插件取数，在运行环境中完成收益与归因计算，交付 Excel 数据底稿与 HTML 复盘报告，并把最新状态写回记忆库](https://mintcdn.com/moonshotcn/4Kcr6Eq3i8zM7z8W/assets/pics/hosted-agents/portfolio-review-arch.png?fit=max\&auto=format\&n=4Kcr6Eq3i8zM7z8W\&q=85\&s=191c67c77710816d8e40aead06ce52ce)

一次复盘任务的数据流如下：

1. 用户通过三种方式之一提供持仓：口述、上传 Excel/CSV 持仓文件或描述投资风格；
2. 智能体将持仓整理为结构化持仓表并交由用户确认；采用风格描述时，先提供分析框架并引导用户补充持仓；
3. 智能体读取记忆库：存在历史分析状态时，采用 fast 模式，仅获取上次截止日之后的增量数据；否则采用 full 模式进行全量分析；
4. 通过插件的数据源路由获取行情、财务与一致预期数据，Wind/iFinD 网关不可用时自动降级到免费行情源，并在产物取数记录表中标注降级与缺口；
5. 计算收益、持仓变化与个股归因，分别呈现事实、计算和推断；行业配置结论需要多期快照或交易流水，只有单期持仓时列为待补；
6. 生成 Excel 数据底稿和 HTML 复盘报告，写入 `output/` 目录并登记为产物；
7. 将组合背景、复盘截止日和关键结论写回记忆库，供下次增量分析使用。

| 层 | 职责 | 数据范围 |
| - | - | - |
| 输入收敛层 | 判断持仓提供方式，整理为统一的结构化持仓表 | 用户口述、上传的持仓文件、风格描述 |
| 分析层 | 取数、收益与归因计算、增量合并 | 插件数据源（Wind、iFinD 等）、记忆库中的历史状态 |
| 交付层 | 生成 Excel 底稿与 HTML 报告，回写分析状态 | 会话文件系统、记忆库 |

组合复盘需要同时处理持仓录入和历史状态复用。三条输入路径降低首次录入成本，记忆库则避免每次全量重算。

## 核心设计

官方金融组合复盘智能体由模型、系统提示词、插件和记忆库组成，使用平台默认内置工具集。设计重点包括：

* **支持多种持仓输入方式**：持仓较少时可以口述，持仓较多时可以上传文件，尚未形成持仓时可以先描述投资风格。三条路径最终进入同一工作流，主要区别在于首次录入成本；
* **后续复盘优先增量计算**：记忆库保存组合背景和分析状态，避免周期性任务每次从头运行。fast 模式的取数量和处理量均远小于 full 模式；
* **数据可溯源且不提供交易指令**：所有数据标注来源与取数日期，无法获取的列入「待核实」；仅用于复盘分析，不执行任何交易，不提供「买 / 卖」指令性建议。

以下介绍各项配置的作用，以及自建时的取舍。

### 系统提示词：工作流、数据口径与任务边界

官方的系统提示词围绕复盘工作流展开，核心约定有四类：

* **输入收敛**：先判断用户通过哪种方式提供持仓（口述 / 文件 / 风格描述）。口述和文件方式先输出结构化持仓表供用户确认，确认后再进入分析；风格描述方式先提供分析框架，并引导用户补充持仓；
* **增量约定**：先查询记忆库。存在历史状态时采用 fast 模式，仅进行增量计算；不存在历史状态，或用户更换基准 / 大幅调仓时采用 full 模式。每次结束后将最新分析状态写回记忆库；
* **数据口径**：每次复盘固定同一套口径，包括市场、币种、基准指数、无风险利率假设和数据质量策略。所有数据标注来源与取数日期；无法获取的数据列入「待核实」并注明原因，不得编造，缺失数据不得按零处理（除非明确声明假设）；
* **任务边界**：仅用于复盘分析，不执行任何交易，不提供「买 / 卖」指令性建议；回退数据、陈旧数据、幸存者偏差必须披露；事实、计算和推断分别呈现。

自建时，需要在系统提示词中明确记忆库读写规则，包括必须保存的状态，以及需要回退到 full 模式的情况（例如用户更换基准，或大幅调仓导致持仓结构变化超过阈值）。

### 插件：提供复盘能力

官方仅配置机构金融插件（`institutional-finance-kit`），由该插件提供复盘能力：

* **`portfolio-review` 技能**：提供持仓复盘与收益归因的完整工作流，覆盖收益表现、持仓变化、个股贡献和操作风格分析，并定义 Excel 底稿 + HTML 报告的产出规范；
* **`consensus-map` 技能**：对比并汇总券商对持仓个股的预期，用于了解市场对这些持仓的预期；
* **数据源路由**：插件自带数据源路由，统一对接万得 Wind、同花顺 iFinD 等数据源。智能体通过能力名获取数据，无需直接处理供应商接口差异。

自建时，可根据复盘领域选择相应的工作流插件。数据源需要授权时，将凭据统一保存在 [凭据库](https://platform.kimi.com/docs/hosted-agents/vaults.md)，运行时注入，不写入智能体配置。插件的引用方式和版本固定规则见 [插件](https://platform.kimi.com/docs/hosted-agents/plugins.md)。

### 工具：使用默认内置工具集

官方没有声明 `tools`。平台内置工具集已覆盖文件读写（读取持仓文件）、代码运行（计算收益和归因）及产物交付（生成 Excel 和 HTML），外部数据能力则由插件的数据源路由提供。仅在需要平台之外的能力时接入 MCP 服务，见 [接入 MCP](https://platform.kimi.com/docs/hosted-agents/mcp.md)。

## 配置选择

本案例选择 `kimi-k3`。复盘任务需要同时处理用户的持仓文件、多源行情数据和记忆库中的历史分析状态，并按 Excel + HTML 两种形式生成交付物，对长上下文和指令遵循能力要求较高。

各项资源的配置如下：

| 资源 | 用途 | 本案例的选择 |
| - | - | - |
| 智能体 | 单智能体完成输入收敛、分析与交付 | `kimi-k3` |
| 插件 | 复盘工作流与数据源路由 | 机构金融插件（`institutional-finance-kit`），含 `portfolio-review`、`consensus-map` 技能 |
| 技能 | 持仓复盘与一致预期分析 | 插件中的 `portfolio-review`、`consensus-map` 技能，随插件挂载 |
| 执行环境 | 读取持仓文件、计算归因、生成 Excel | 通用云沙箱，无特殊依赖与网络配置 |
| 文件 | 用户上传的持仓清单（方式 2 必传） | 上传后以只读副本挂载到会话 |
| 凭据库 | 数据插件授权（可选） | 数据源需要授权时配置，创建会话时挂载 |
| 触发器 | 当前不需要 | 复盘按需运行；需要定期复盘时再配置 |
| 记忆库 | 组合背景与分析状态（增量更新必配） | 一个记忆库，关联到智能体 |

## 运行成本

成本主要来自模型 tokens。沙箱按运行时长计费，价格为 ¥0.072 / 小时，一次复盘约 40–60 分钟，费用不到 ¥0.1；文件上传与抽取限时免费，详见 [托管智能体定价](https://platform.kimi.com/docs/pricing/hosted-agents.md)。按 `kimi-k3` 的 [公开单价](https://platform.kimi.com/docs/pricing/chat.md)估算，首次全量复盘约需 **几十元，耗时 40–60 分钟**。后续日常增量复盘（fast 模式，仅获取上次截止日之后的数据）的取数量和处理量较小，成本低于全量复盘。

上述估算来自若干次生产会话，仅供参考，实际费用以控制台账单为准。费用和耗时会随持仓规模、复盘区间以及取数和返工轮次变化。该任务的稳定性仍需改进，实测中出现过达到 `max_steps` 上限而失败并需要重试的情况，重试会增加实际成本，建议通过事件流确认产物已生成。

复盘质量在很大程度上取决于输入材料。平台无法直接提供完整的持仓记录、券商研报和内部研究，需要你自行准备并上传，或接入私有信息源。充分的材料有助于提高归因准确性和分析深度。

## 从最小版本开始搭建

以下为可运行的最小配置示例，根据上文的系统提示词和插件组合编写。该示例并非官方配置的逐字拷贝，官方当前配置以 `GET /v1/agents` 返回为准。

### 第 1 步：创建智能体

```bash cURL theme={null}
curl -X POST https://api.moonshot.cn/v1/agents \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "我的组合复盘助手",
    "model": {"id": "kimi-k3.1-pro"},
    "system": "你是一个投资组合复盘助手。\n- 支持三种持仓输入：用户口述、用户上传的 Excel/CSV 文件、用户描述的投资风格。口述和文件方式先整理成结构化持仓表给用户确认，确认后再分析。\n- 每次复盘先查记忆库：有历史分析状态走增量模式，只计算上次截止日之后的变化；没有历史状态或用户更换基准/大幅调仓时走全量模式。每次结束把组合背景、复盘截止日和关键结论写回记忆库。\n- 所有取数标注数据来源与取数日期；取不到的数据列入待核实并注明原因，不编造、不把缺失当零。\n- 只做复盘分析，不执行任何交易，不给买入/卖出的指令性建议；事实、计算、推断分开呈现。\n- 产出两份文件：Excel 数据底稿（收益、持仓、归因的完整计算过程）和 HTML 复盘报告（结论先行的可视化呈现），都写入 output/ 目录，最终回复用相对路径逐一列出。",
    "plugins": [
      {"plugin_id": "<机构金融插件 ID>"}
    ],
    "description": "自建组合复盘助手：三种持仓输入 + 增量更新，产出 Excel 底稿和 HTML 报告"
  }'
```

```bash CLI theme={null}
kha agents create --file - <<'JSON'
{
    "name": "我的组合复盘助手",
    "model": {"id": "kimi-k3.1-pro"},
    "system": "你是一个投资组合复盘助手。\n- 支持三种持仓输入：用户口述、用户上传的 Excel/CSV 文件、用户描述的投资风格。口述和文件方式先整理成结构化持仓表给用户确认，确认后再分析。\n- 每次复盘先查记忆库：有历史分析状态走增量模式，只计算上次截止日之后的变化；没有历史状态或用户更换基准/大幅调仓时走全量模式。每次结束把组合背景、复盘截止日和关键结论写回记忆库。\n- 所有取数标注数据来源与取数日期；取不到的数据列入待核实并注明原因，不编造、不把缺失当零。\n- 只做复盘分析，不执行任何交易，不给买入/卖出的指令性建议；事实、计算、推断分开呈现。\n- 产出两份文件：Excel 数据底稿（收益、持仓、归因的完整计算过程）和 HTML 复盘报告（结论先行的可视化呈现），都写入 output/ 目录，最终回复用相对路径逐一列出。",
    "plugins": [
      {"plugin_id": "<机构金融插件 ID>"}
    ],
    "description": "自建组合复盘助手：三种持仓输入 + 增量更新，产出 Excel 底稿和 HTML 报告"
  }
JSON
```

创建成功后，从响应中保存 `id` 作为 `AGENT_ID`。通过 `GET /v1/plugins` 查询插件 ID，并按显示名「机构金融插件」查找，或在控制台智能体表单中直接勾选。可根据需求调整以下字段：

| 字段 | 调整频率 | 配置建议 |
| - | - | - |
| `system` | 经常调整 | 固定基准指数、分析维度、报告模板和合规口径；建议保留输入收敛和增量约定 |
| `plugins` | 按领域调整 | 替换为其他领域的工作流插件，或增加数据类插件 |
| `model` | 通常保持默认 | `kimi-k3` 已适配长上下文分析与结构化产出 |
| 工具集 | 通常保持默认 | 默认内置工具集即可满足需求，无需额外声明 |

### 第 2 步：准备执行环境与记忆库

* **执行环境**：使用通用云沙箱即可，`config` 传 `{"type": "cloud"}`，详见 [快速开始](https://platform.kimi.com/docs/hosted-agents/quickstart.md)。沙箱内置的 Python 环境已覆盖复盘所需的 Excel 生成能力；如果变体需要额外依赖，请在 [执行环境](https://platform.kimi.com/docs/hosted-agents/environments.md) 中声明。

* **记忆库（增量更新必配）**：创建一个记忆库，用于读写增量更新状态，见 [记忆库](https://platform.kimi.com/docs/hosted-agents/memory.md)。保存响应中的 `id` 作为 `MEMORY_STORE_ID`：

  ```bash cURL theme={null}
  curl -X POST https://api.moonshot.cn/v1/memory-stores \
    -H "Authorization: Bearer $KIMI_API_KEY" \
    -H "kimi-api-version: 2026-09-01-beta" \
    -H "Content-Type: application/json" \
    -d '{"name": "portfolio-review", "description": "组合背景与历史复盘状态"}'
  ```

  ```bash CLI theme={null}
  kha memory-stores create --name "portfolio-review" --description "组合背景与历史复盘状态"
  ```

* **凭据（可选）**：数据插件需要授权时，先在 [凭据库](https://platform.kimi.com/docs/hosted-agents/vaults.md) 配置凭据，并在创建会话时把凭据库添加到 `resources`（绑定仅在创建时生效），运行时自动注入。

### 第 3 步：上传持仓文件（方式 2）

以上传持仓文件为例，通过 `POST /v1/files` 上传 Excel/CSV 持仓清单，并从响应中保存 `id` 作为 `FILE_ID`：

```bash cURL theme={null}
curl https://api.moonshot.cn/v1/files \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta" \
  -F "file=@my_portfolio.xlsx"
```

```bash CLI theme={null}
kha files upload --file my_portfolio.xlsx
```

文件会以只读副本形式挂载到沙箱的 `/mnt/agents/upload/` 目录，详见 [文件](https://platform.kimi.com/docs/hosted-agents/files.md)。口述持仓（方式 1）和风格描述（方式 3）可跳过此步骤。

### 第 4 步：创建会话并提交任务

创建会话时，将记忆库与持仓文件一起添加到 `resources`；口述持仓时，省略 `file` 资源：

```bash cURL theme={null}
curl -X POST https://api.moonshot.cn/v1/sessions \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "'"$AGENT_ID"'",
    "environment_id": "'"$ENVIRONMENT_ID"'",
    "title": "我的组合三季度复盘",
    "resources": [
      {"type": "file", "file_id": "'"$FILE_ID"'"},
      {"type": "memory_store", "memory_store_id": "'"$MEMORY_STORE_ID"'", "access": "read_write"}
    ]
  }'
```

```bash CLI theme={null}
kha sessions create --file - <<JSON
{
    "agent_id": "$AGENT_ID",
    "environment_id": "$ENVIRONMENT_ID",
    "title": "我的组合三季度复盘",
    "resources": [
      {"type": "file", "file_id": "$FILE_ID"},
      {"type": "memory_store", "memory_store_id": "$MEMORY_STORE_ID", "access": "read_write"}
    ]
  }
JSON
```

从响应中保存会话 `id` 作为 `SESSION_ID`，订阅事件流（见 [快速开始](https://platform.kimi.com/docs/hosted-agents/quickstart.md)），然后提交任务：

```bash cURL theme={null}
curl -X POST https://api.moonshot.cn/v1/sessions/$SESSION_ID/events \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.message",
        "data": {
          "content": [
            {"type": "text", "text": "基于我上传的持仓文件，做一份今年三季度的组合复盘：收益表现、持仓变化、行业和个股归因，基准用沪深300。产出 Excel 数据底稿和 HTML 复盘报告，保存到 output/ 目录。"}
          ]
        }
      }
    ]
  }'
```

```bash CLI theme={null}
kha sessions send "$SESSION_ID" "基于我上传的持仓文件，做一份今年三季度的组合复盘：收益表现、持仓变化、行业和个股归因，基准用沪深300。产出 Excel 数据底稿和 HTML 复盘报告，保存到 output/ 目录。"
```

下个月再次复盘时，可在同一会话中提交「再复盘一次十月的」。智能体读取记忆库中的历史状态后，会自动采用增量模式。

任务描述会影响产出质量。编写任务时，建议遵循以下三条原则：

1. **说明持仓来源。** 上传文件后，写明「基于我上传的持仓文件」；口述时，完整提供标的、数量和成本价；只有风格描述时，明确说明「先按我的风格给分析框架」。
2. **明确复盘区间和基准。** 使用「今年三季度」「最近六个月」等明确区间，并注明「基准用沪深300 / 标普500」，避免智能体自行推断口径。
3. **明确交付物。** 默认产出 Excel 底稿 + HTML 报告；如果只需要其中一份，或需要增加一致预期地图，请在任务中指定，例如「加上持仓个股的一致预期对比」。

### 第 5 步：取回产物

会话回到 `idle` 后，通过产物接口取回交付物：

```bash cURL theme={null}
curl "https://api.moonshot.cn/v1/artifacts?session_id=$SESSION_ID" \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta"
```

```bash CLI theme={null}
kha artifacts list --session "$SESSION_ID"
```

产物列表为空或需要中间文件时，再浏览会话文件系统（见 [文件](https://platform.kimi.com/docs/hosted-agents/files.md)）。

一次复盘交付两份文件，均保存在会话的 `output/` 目录下：

* **Excel 数据底稿**（如 `output/portfolio_review_2026Q3.xlsx`）：可编辑工作簿，持仓明细、区间收益计算、个股贡献和归因拆解分别位于不同工作表，数字带有可追踪的公式；另附取数记录表，按类别记录来源、降级情况和数据缺口，适用于需要进一步处理数据的用户；
* **HTML 复盘报告**（如 `output/portfolio_review_2026Q3.html`）：麦肯锡风格的可视化报告，开头呈现核心结论（本期收益、相对基准的超额、主要贡献和拖累），随后展开收益曲线、持仓结构变化等章节。附录说明数据口径与缺口，并区分实际数据、快照模拟和待补数据，适合提交投委会或客户审阅。

两份文件分别用于阅读展示和进一步编辑，内容来自同一份分析。

## 运行监控

可通过事件流查看智能体的完整工作过程，并通过以下字段判断运行是否正常：

* **`session.status`**：`running` 表示正在运行，回到 `idle` 表示本轮完成，可以下载产物；
* **`agent.tool_use`**：可查看每次数据获取使用的数据源和口径，以及记忆库的读写情况；
* **`session.error`**：任务失败时出现，包含错误类型和信息。

组合复盘场景还需关注以下事项：

| 观察项 | 检查内容 | 排查用途 |
| - | - | - |
| `agent.tool_use` 的第一轮调用 | 是否先读取记忆库 | fast 模式下通常首先读取记忆库；已有历史状态但未读取时，说明增量约定未生效 |
| `agent.thinking` | 判断的输入方式（口述还是文件）与 full / fast 模式 | 模式判断不符合预期时，可在此阶段介入纠正 |
| Excel 底稿的取数记录表 | 降级与缺口标注 | Wind / iFinD 网关不可用时会降级到免费行情源；标注越多，相关结论越需要人工复核 |

## 可扩展方向

* **定期自动复盘**：通过 [触发器](https://platform.kimi.com/docs/hosted-agents/triggers.md) 配置每月 1 日的 cron，自动创建会话并提交复盘任务，配合记忆库增量更新，实现无人值守运行；
* **对接内部持仓系统**：如果机构持仓位于自有 OMS / 风控系统，可将持仓查询接口封装为 MCP 服务并接入智能体，替代手工上传文件，见 [接入 MCP](https://platform.kimi.com/docs/hosted-agents/mcp.md)；
* **嵌入自有系统**：通过 API 创建会话、订阅事件流并取回产出，将复盘能力集成到自有业务看板或客户报告流程。

## 下一步

> [card] [保存组合分析状态](https://platform.kimi.com/docs/hosted-agents/memory.md)
>
> 增量更新的状态读写机制与挂载方式。

> [card] [上传持仓文件](https://platform.kimi.com/docs/hosted-agents/files.md)
>
> 上传持仓文件、挂载会话与取回产出文件。

> [card] [配置每月复盘计划](https://platform.kimi.com/docs/hosted-agents/triggers.md)
>
> 用触发器把每月复盘做成定时运行。
