# Investment Assistant

> 中文个人投资助手初始化 Skill。引导用户确认真实股票、市场、关注偏好和盘后监控安排，检查 Agent Plan Harness，安装并启动仓库内完整前后端，导入个性化配置，真实调用 DataPro、豆包搜索和 Agent Plan 模型生成首批个股简评与盘后风险摘要，并完成可用性验收。用户提出“帮我初始化个人投资助手”“安装投资助手”“配置我的关注股票”“让我打开网站就有内容”或需要恢复、诊断该应用时使用。

- Skill: `volcengine/investment-assistant` (Agent Skill, multi-file: 21 files)
- Install (CLI): `npx skillmds@latest add volcengine/investment-assistant`
- Raw SKILL.md: https://api.skillmd.com/api/skills/volcengine/investment-assistant/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: volcengine (https://skillmd.com/u/volcengine)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/volcengine/investment-assistant

---


# 个人投资助手初始化

本 Skill 不是网站设计顾问，也不从零讨论页面方案。仓库已经提供可运行的 React、Express、SQLite、定时调度器和真实 Provider 接入。本 Skill 的任务是把这套应用按用户的真实投资偏好配置好，并交付一个打开后已有个性化内容的网站。

## 远程 Skill 入口

用户可能直接通过公开 Skill URL 触发本流程，而不是预先克隆仓库或安装 Skill。火山方舟
AI App Lab 中的官方入口为：

```text
帮我初始化个人投资助手：https://github.com/volcengine/ai-app-lab/blob/main/demohouse/personal-investment-assistant/skills/investment-assistant/SKILL.md
```

该 URL 只负责让 Agent 找到本 Skill，不是应用包下载源。应用包必须固定从以下发行版本
获取，不得根据入口 URL 改用其他仓库、分支或同名项目：

```text
固定发行仓库：https://github.com/3494036618-eng/personal-investment-assistant
固定发行版本：v0.3.1
固定发行 Skill：https://github.com/3494036618-eng/personal-investment-assistant/blob/v0.3.1/skills/investment-assistant/SKILL.md
```

如果当前环境中不存在 `{baseDir}/scripts/status.mjs`，说明本 Skill 是从远程 URL 打开的。
此时 Codex 或 Claude Code 必须：

1. 无论用户从官方入口还是发行 Skill 打开本文件，都只取得上面指定的独立发行仓库
   `v0.3.1` 完整版本。先说明会把公开源码写入本机，然后在 macOS/Linux 的 POSIX shell
   中使用系统临时目录执行：

   ```bash
   release_root="$(mktemp -d "${TMPDIR:-/tmp}/personal-investment-assistant-v0.3.1-XXXXXX")"
   git clone --depth 1 --branch v0.3.1 --single-branch \
     https://github.com/3494036618-eng/personal-investment-assistant.git "$release_root"
   ```

   Windows PowerShell 使用以下等价命令：

   ```powershell
   $releaseRoot = Join-Path ([System.IO.Path]::GetTempPath()) ("personal-investment-assistant-v0.3.1-" + [guid]::NewGuid().ToString("N"))
   New-Item -ItemType Directory -Path $releaseRoot -ErrorAction Stop | Out-Null
   git clone --depth 1 --branch v0.3.1 --single-branch `
     https://github.com/3494036618-eng/personal-investment-assistant.git $releaseRoot
   if ($LASTEXITCODE -ne 0) {
     Remove-Item -LiteralPath $releaseRoot -Recurse -Force
     throw "v0.3.1 clone 失败，已停止且不会换源或降级。"
   }
   ```

   不能下载 AI App Lab 的整个 monorepo，不能使用 `main`，不能只下载 `SKILL.md`，也不能
   通过搜索结果猜测同名仓库。clone 失败时只删除本次新建的临时目录并停止，不能换源或降级。
2. 在下载仓库中执行来源校验；脚本会核对 origin、精确 tag、本地 commit、远程 tag 当前
   指向以及干净工作区，任一不符都会失败：

   ```bash
   node "$release_root/scripts/validate-release-checkout.mjs"
   ```

   Windows PowerShell 对应执行：

   ```powershell
   node (Join-Path $releaseRoot "scripts/validate-release-checkout.mjs")
   if ($LASTEXITCODE -ne 0) { throw "发行来源校验失败，停止安装。" }
   ```

   校验失败时停止，不继续安装；不得复用、修改、清理或覆盖任何已有源码目录。
3. 将项目根目录设为 `release_root`，将 `{baseDir}` 设为其中的
   `skills/investment-assistant`，确认 `{baseDir}/scripts/`、`{baseDir}/references/`、
   仓库根目录 `app/` 和 `package.json` 均存在。
4. 在项目根目录先按锁文件安装测试依赖，再运行完整验证：

   ```bash
   npm --prefix "$release_root/app" ci
   (cd "$release_root" && npm run verify)
   ```

   Windows PowerShell 在 `$releaseRoot` 中依次执行 `npm --prefix app ci` 和
   `npm run verify`。公开包扫描、来源校验器测试、249 项应用测试、生产构建、Skill
   隔离安装和凭证扫描全部通过后，才按当前客户端安装：
   - Codex：`npm run skill:install:codex`
   - Claude Code：`npm run skill:install:claude`
   - 用户明确要求两端都安装：`npm run skill:install:all`
   已安装旧版时先说明影响，再为对应命令追加 `-- --force`。
5. 立即使用刚安装的 Skill 继续阶段 0，不要求用户重复提供源码目录。当前流程切换到安装后的
   Skill，或流程结束、取消、失败且不再需要源码 checkout 时，才删除本次创建的临时目录；
   删除前必须再次确认目录名称以 `personal-investment-assistant-v0.3.1-` 开头，不能删除用户
   已有目录。
6. 下载、校验和安装阶段不创建云资源、不调用 Agent Plan、DataPro 或豆包搜索，也不产生
   AFP。后续真实探测和报告生成仍须按阶段 2 的用户确认执行。

独立发行入口也可以直接触发同一流程：

```text
帮我初始化个人投资助手：https://github.com/3494036618-eng/personal-investment-assistant/blob/v0.3.1/skills/investment-assistant/SKILL.md
```

已经安装后，Codex 可通过 `$investment-assistant` 触发，Claude Code 可通过
`/investment-assistant` 触发；两种入口执行同一套初始化和验收规则。

## 完成标准

只有以下事项全部完成，才可以说“已经可以使用”：

1. 已确认至少一只真实证券的名称、代码和市场。
2. 已逐只确认用户关注方向，保留用户原词。
3. 已确认盘后自动监控是否启用；启用时已确认时间、日期和时区。
4. Agent Plan Key 已通过本机私密配置写入，未出现在聊天、源码或日志。
5. DataPro、豆包搜索和 Agent Plan 模型的真实探测全部成功。
6. 完整前后端已安装并启动。
7. 用户配置已导入，首页不是空白关注列表。
8. 用户同意消耗真实额度后，每只股票至少生成一份个股简评和一份盘后风险摘要。
9. 两类报告均有实质正文、对应来源和独立历史记录。
10. 桌面端核心路径通过浏览器检查。

任一项未完成，都要准确说明停在哪一步、已经完成什么以及下一步是什么，不得用旧结果、Mock 数据或口头判断代替。

## 工作原则

- **不讨论网站方案**：现成网站、页面结构和功能边界已经确定，只收集使用它所需的投资配置。
- **先确认配置再调用**：先给用户展示结构化配置摘要，用户确认后才安装、导入和消耗真实服务额度。
- **真实证券不猜测**：名称、代码或市场不确定时先核验。无法核验就请用户补充，不能映射到相似公司。
- **偏好逐只绑定**：不同股票可以有完全不同的关注方向；所有偏好原词进入 Profile，不能只使用预设关键词。
- **打开即有内容**：默认初始化会为每只股票生成两类首批报告。只有用户明确要求暂不生成时，才使用空报告模式。
- **三个能力使用同一 Agent Plan Key**：按 Agent Plan Harness 当前配置，同一个 Key 默认用于模型、DataPro 和豆包搜索。不得要求用户再提供一枚独立搜索 Key。
- **来源与正文绑定**：DataPro 负责结构化专业数据；豆包搜索负责最新公开信息；Agent Plan 模型只基于本次证据生成并审校。
- **两类报告职责不同**：个股简评回答“公司当前怎么样”；盘后风险摘要回答“本次检查窗口内出现了什么新增变化和风险信号”。
- **敏感信息不回显**：Key 只能通过隐藏终端输入、环境变量或权限为 `0600` 的本机凭证文件配置。
- **每一步都解释**：说明刚完成什么、现在处于哪一步、下一步会做什么、是否会下载依赖或消耗额度。

## 流程总览

| 阶段 | 动作 | 完成标志 |
| --- | --- | --- |
| 0 | 检查当前状态 | 确认首次初始化、恢复运行或故障排查 |
| 1 | 收集投资配置 | 股票、代码、市场、偏好和监控安排完整 |
| 2 | 用户确认配置 | 用户明确同意结构化摘要 |
| 3 | 安装与私密配置 | 正式应用安装完成，Key 安全写入 |
| 4 | 真实服务探测 | 三个 Provider 当前均可用 |
| 5 | 导入个性化配置 | 首页可见用户股票和关注方向 |
| 6 | 生成首批报告 | 每只股票有两类真实报告和历史 |
| 7 | 浏览器验收与交付 | 用户可直接打开网站使用 |

## 阶段 0：检查当前状态

先检查 Node.js、Skill 文件、运行时和网站状态：

```bash
node {baseDir}/scripts/status.mjs
```

- 应用未安装：进入阶段 1。
- 已安装但未运行：仍先确认用户配置，再决定启动或更新。
- 已运行：读取现有关注列表和配置；用户只是新增标的时，不清空原数据。
- `ready=false`：后续必须重新执行真实 doctor，不能仅凭进程存活判断后端可用。

不要询问用户网站源码目录，也不要创建另一份项目。

## 阶段 1：收集投资配置

采用一到两问一轮的方式，避免把长表单一次抛给用户。至少收集：

1. 证券名称。
2. 证券代码。
3. 市场：`CN`、`HK` 或 `US`。
4. 这只证券的关注方向，建议 2 至 6 项，但以用户真实需求为准。
5. 是否启用盘后自动检查。
6. 启用时的执行时间、执行日和时区。

可以先问：

> 你希望关注哪些股票？请告诉我证券名称、代码和市场。随后我会逐只确认你真正关心的方向，并把这些偏好直接写进网站。

关注方向不能被固定词表限制。以下只是帮助用户表达，不是允许列表：

- 市场与技术：价格趋势、成交量、波动、关键价位、资金变化。
- 经营与财务：收入、利润、现金流、毛利率、研发、分红、负债。
- 公司事件：公告、订单、产品、产能、管理层、诉讼、监管。
- 行业与外部环境：竞争、政策、原材料、汇率、利率、海外风险。
- 用户自己的自然语言，例如“高端酒批价与渠道库存”或“海外大客户认证进度”。

复合偏好可以原样保留。应用会在检索时进行语义拆解和覆盖判断，不要为了适配预设关键词擅自改写。

### 证券核验

优先使用 DataPro 查询名称、代码和市场对应关系。直接工具不可用时，不要猜测；在真实服务就绪后，以首份报告中的证券归属校验作为阻断门槛。中港股代码保留交易所常用格式，美股代码使用公开 Ticker。

## 阶段 2：确认结构化配置

把讨论结果整理成简短摘要，让用户明确确认。示例：

```text
初始化配置

1. 贵州茅台｜600519｜CN
   关注：盈利能力、品牌优势、渠道库存、行业动态
   盘后监控：工作日 18:00，Asia/Shanghai

2. Apple｜AAPL｜US
   关注：iPhone 销量、服务业务、AI 产品进展
   盘后监控：关闭

确认后我会安装并启动现成网站，导入这些配置，并为每只股票真实生成一份个股简评和一份盘后风险摘要。该步骤会调用 DataPro、豆包搜索和 Agent Plan 模型并消耗套餐额度。
```

只有用户明确确认后才继续。用户修改某一项时，只更新对应项并再次给出完整摘要。

将确认结果写入权限为 `0600` 的临时 Profile。格式：

```json
{
  "stocks": [
    {
      "name": "贵州茅台",
      "code": "600519",
      "exchange": "CN",
      "focus": ["盈利能力", "品牌优势", "渠道库存", "行业动态"],
      "monitor": {
        "enabled": true,
        "schedule_time": "18:00",
        "schedule_days": ["Mon", "Tue", "Wed", "Thu", "Fri"],
        "timezone": "Asia/Shanghai"
      }
    }
  ]
}
```

Profile 不得包含 API Key。临时文件用完后使用 `--consume-profile` 删除。

## 阶段 3：安装应用并配置 Agent Plan

说明该步骤会复制正式应用、安装 npm 依赖、运行检查和生产构建，然后执行：

```bash
node {baseDir}/scripts/install.mjs
```

缺少凭证时，在交互式终端执行：

```bash
node {baseDir}/scripts/configure.mjs
```

`configure.mjs` 只询问一枚 Agent Plan API Key，并安全写入：

```text
~/.config/investment-assistant/credentials.env
```

文件权限必须为 `0600`。不要要求用户把 Key 发到聊天里，不要把 Key 写入 Profile、`.env.example`、README 或源码。

## 阶段 4：真实探测三个 Provider

执行：

```bash
node {baseDir}/scripts/doctor.mjs --live
```

必须看到：

- `agent_plan_model: ok`
- `datapro: ok`
- `web_search: ok`

这一步会产生少量真实调用。任一失败时按 `references/troubleshooting.md` 处理并停在此处；不要继续生成报告，也不要把“已配置 Key”说成“后端可用”。

## 阶段 5：导入用户配置

启动网站并导入已确认的 Profile：

```bash
node {baseDir}/scripts/start.mjs
node {baseDir}/scripts/profile.mjs --input /私密Profile绝对路径.json --consume-profile
```

导入是按市场与证券代码幂等更新。已有股票保留历史，重复执行不会创建重复标的。

检查首页至少满足：

- 每只用户证券均存在。
- 名称、代码和市场正确。
- 卡片显示用户填写的关注方向。
- 盘后设置与用户确认一致。

## 阶段 6：生成首批个性化报告

用户已经在阶段 2 同意消耗额度时，执行全量首批生成：

```bash
node {baseDir}/scripts/acceptance.mjs --all --seed
```

`--seed` 对每只股票生成：

1. 一份个股简评。
2. 一份盘后风险摘要。

并自动检查：

- 两类报告拥有不同 ID 和独立证据快照。
- 两类报告不重复使用同一联网 URL。
- 个股简评含可核验的核心财务 DataPro 证据。
- 正文引用的 evidence ID 都存在。
- 联网来源有真实标题、发布方、URL 和摘要。
- 用户偏好逐项存在覆盖状态。
- 两类报告分别进入对应历史记录。

如果用户明确要求暂不生成首批报告，可以只做基础验收：

```bash
node {baseDir}/scripts/acceptance.mjs --all
```

此时必须说明“网站已配置，但报告区仍可能为空”，不能宣称已经达到打开即有内容。

最短的一键初始化命令是：

```bash
node {baseDir}/scripts/onboard.mjs \
  --profile /私密Profile绝对路径.json \
  --consume-profile
```

该命令会安装、配置、真实探测、启动、导入并默认生成首批报告。只有用户明确要求不生成时才添加 `--skip-initial-reports`。

## 阶段 7：桌面端浏览器验收

打开脚本输出的本地地址，默认：

```text
http://127.0.0.1:8788
```

按真实用户路径检查：

1. 首页不是空白，所有证券和关注方向可见。
2. 打开“个股简评”先显示已保存首份报告。
3. 正文是“市场表现、经营与财务、关注方向、后续观察”，不是字段拼接。
4. 引用区与正文编号对应，联网来源可打开，DataPro 来源不显示 trace。
5. 打开“盘后风险摘要”显示独立报告，不复用简评正文或来源。
6. 盘后设置可保存，“立即执行一次”能生成新记录。
7. 自动监控启用时，下一次执行时间正确；调度服务状态正常。
8. 历史记录包含所有已生成报告。
9. 页面无溢出、遮挡、明显换行异常或控制台错误。

浏览器页面可见不等于真实后端可用；只有真实 doctor、报告生成和浏览器路径三者都通过，才能交付。

## 个股简评与盘后风险摘要的固定边界

### 个股简评

回答“这家公司当前怎么样”，使用当前行情、最新已披露财务和与用户关注方向相关的公开材料。固定结构：

- 摘要：精简结论，不拼接所有正文。
- 市场表现。
- 经营与财务。
- 关注方向。
- 后续观察。

### 盘后风险摘要

回答“这次检查窗口内发生了什么”，使用当日市场异动、上次检查后的新增公司事件以及近期外部风险背景。固定结构：

- 摘要：风险变化与最重要事实，不复述所有栏目。
- 市场异动。
- 公司事件。
- 外部风险。
- 后续观察。

没有某类合格证据时可以省略对应栏目，但不能填充“没有查到”“继续观察”等空泛句。没有新增风险事件不等于公司没有风险；仍应保存本次可审计结果。

## 故障恢复

- 网站未启动：运行 `status.mjs`，再运行 `start.mjs`。
- `ready=false`：重新运行 `doctor.mjs --live`。
- 新股票没有内容：确认 Profile 导入成功，再对该股票执行 `acceptance.mjs --stock 代码 --seed`。
- 定时任务未执行：检查监控开关、日期、时间、时区、调度服务状态和执行记录。
- 报告生成失败：保留具体错误和诊断日志，按 Provider、证券归属、证据覆盖或模型审校问题处理，不关闭校验。
- 更新应用：先备份，再停止、安装、启动和重新执行 doctor；数据库与凭证不随应用更新删除。

详细配置见 `references/setup.md`，验收规则见 `references/acceptance.md`，来源规则见 `references/evidence-policy.md`，排障见 `references/troubleshooting.md`。

## 最终交付说明

最终回复必须明确列出：

1. 网站地址和当前进程状态。
2. 已导入的证券、市场和关注方向。
3. 每只证券的盘后监控开关、时间、日期和时区。
4. Agent Plan 模型、DataPro、豆包搜索的真实探测结果。
5. 每只证券是否已经生成个股简评和盘后风险摘要。
6. 两类历史记录和调度状态是否通过。
7. 实际执行过的检查、测试、构建和浏览器验收。
8. 未完成项、外部依赖和仍需人工核对的风险。

不要只说“初始化完成”。用户需要知道现在能做什么、哪些结果已经由真实调用验证、哪些仍未验证。