个人投资助手初始化

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

远程 Skill 入口

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

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

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

固定发行仓库：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 中使用系统临时目录执行：

   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 使用以下等价命令：

   $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 当前 指向以及干净工作区，任一不符都会失败：

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

   Windows 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. 在项目根目录先按锁文件安装测试依赖，再运行完整验证：

   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 的用户确认执行。

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

帮我初始化个人投资助手：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 文件、运行时和网站状态：

node {baseDir}/scripts/status.mjs

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

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

阶段 1：收集投资配置

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

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

可以先问：

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

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

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

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

证券核验

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

阶段 2：确认结构化配置

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

初始化配置

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

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

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

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

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

{
  "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 依赖、运行检查和生产构建，然后执行：

node {baseDir}/scripts/install.mjs

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

node {baseDir}/scripts/configure.mjs

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

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

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

阶段 4：真实探测三个 Provider

执行：

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

必须看到：

• agent_plan_model: ok
• datapro: ok
• web_search: ok

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

阶段 5：导入用户配置

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

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

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

检查首页至少满足：

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

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

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

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

--seed 对每只股票生成：

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

并自动检查：

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

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

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

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

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

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

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

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

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

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. 未完成项、外部依赖和仍需人工核对的风险。

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