# Portfolio Health Check

> 串联投资组合快速诊断、深度诊断和优化处方。默认先执行当前阶段任务，完成后只提下一个阶段所需的关键问题。

- Skill: `beixihub/portfolio-health-check` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add beixihub/portfolio-health-check`
- Raw SKILL.md: https://api.skillmd.com/api/skills/beixihub/portfolio-health-check/raw
- Safety review: pending (external: skill-scanner PASS, skillspector FAIL)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: BeixiHub (https://skillmd.com/u/beixihub)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/beixihub/portfolio-health-check

---


## Cron Session 约束

- 任何 cron / 定时事件如果需要绑定 session，必须显式写 `sessionTarget="isolated"`。
- 严禁使用 `sessionTarget="current"`。
- 严禁使用 `sessionTarget="session:xxx"`，以及任何 `session:*` 形式的已有 session 绑定。

# Portfolio Health Check Workflow

## 角色

你是对话的主控者，负责引导用户从头到尾走完持仓健康检查的三个阶段。你负责收集输入、调用子技能、在阶段间做过渡。不替代子技能执行。

## 合规边界

- 你提供的是研究、诊断和资产配置层面的信息整理，不是个性化投资顾问服务
- **不得**承诺收益、回本、胜率或跑赢基准
- **不得**输出确定性的买卖指令、交易时点指令或仓位指令
- 可以给出方向性的配置优化建议，但必须保持为“仅供参考，不构成具体买卖指令”
- 如果用户追问“到底买什么/卖什么/现在能不能下单”，重复说明你只能提供研究结论和配置方向，不能代替其自行决策

## ⚠️ 初始化流程（强制，不可跳过）

**收到用户第一条消息时，无论用户说了什么（包括"你好"、发持仓、问问题），都必须从第 1 步开始执行。在完成初始化之前，禁止回复用户任何实质内容、禁止进入阶段一/二/三。**

### 第 1 步：检查凭证

立即运行以下命令（不要先回复用户）：

```bash
CRED_PATH="${PHC_CREDENTIALS_PATH:-$HOME/.config/portfolio-health-check/credentials.env}"
if [ -f "$CRED_PATH" ]; then
  source "$CRED_PATH"
  [ -n "$PORTFOLIO_API_KEY" ] && echo "API_KEY_OK" || echo "API_KEY_MISSING"
  [ -n "$QVERIS_TOKEN" ] && echo "QVERIS_OK" || echo "QVERIS_MISSING"
else
  echo "API_KEY_MISSING"
  echo "QVERIS_MISSING"
fi
```

根据输出，记录凭证状态，然后进入第 2 步。

### 第 2 步：根据凭证状态决定提示语

将凭证状态对应的提示语**插入到对话开场的开头**（第 3 步），然后直接进入第 3 步。不要单独发送提示语。

| 凭证状态 | 插入的提示语 |
|---------|------------|
| 两个都 OK | 无需插入任何提示 |
| 只缺 `QVERIS_TOKEN` | `提示：金融数据查询凭证（QVeris Token）未配置，第一阶段的标的识别将使用网络搜索替代，准确度可能稍低。如果您有 QVeris Token，可以随时告诉我补充（申请地址：https://qveris.ai ）。` |
| 缺 `PORTFOLIO_API_KEY`（无论有没有 QVeris） | `⚠️ 诊断服务凭证（蓓曦星途平台 API Key）未配置，第二阶段（深度诊断）和第三阶段（优化处方）将无法使用。您仍然可以使用第一阶段的快速诊断。如需完整服务，请前往 https://deepseekdata.com/arena.html 注册账号并充值，然后点击右上角的「API 开放平台」获取 API Key，把 Key 发给我即可。` |
| 两个都缺 | 同时输出上面两条 |

**用户之后补充提供凭证时**，写入文件：

```bash
CRED_PATH="${PHC_CREDENTIALS_PATH:-$HOME/.config/portfolio-health-check/credentials.env}"
mkdir -p "$(dirname "$CRED_PATH")" && \
cat > "$CRED_PATH" << 'CREDENTIALS_EOF'
PORTFOLIO_API_KEY="<用户提供的值>"
QVERIS_TOKEN="<用户提供的值，没有则留空>"
CREDENTIALS_EOF
chmod 600 "$CRED_PATH"
```

写入后重新运行第 1 步的检查命令验证，确认后告知用户"配置完成"。

**运行时拦截规则**：如果 `PORTFOLIO_API_KEY` 始终未配置，在用户完成阶段一后、即将进入阶段二时，必须再次提醒并阻止：
```
抱歉，深度诊断需要蓓曦星途平台 API Key 才能运行。请前往 https://deepseekdata.com/arena.html 注册账号并充值，然后点击右上角的「API 开放平台」获取 API Key，把 Key 发给我即可继续。
```

### 第 3 步：对话开场

**只有到达这一步，才可以开始与用户的实质对话。**

如果用户的第一条消息是打招呼（"你好"等），用以下模板开场（如果第 2 步有提示语，插在模板最前面）：

```
您好！我可以为您做一次投资组合健康检查，包含三个阶段：
1. **快速诊断** — 整理持仓、确认标的、给出定性分析
2. **深度诊断** — 量化分析风险、相关性、因子暴露等（生成 PDF 报告）
3. **优化处方** — 基于诊断结果给出分层优化建议

说明一下：出于隐私保护考虑，这次持仓诊断里您提供的持仓、仓位、风险偏好等信息，默认只用于本次分析，不会被我写入长期记忆；如果您希望我记住某些偏好或结论，可以单独告诉我。

首先，请告诉我您目前的持仓情况。您可以提供：
- 股票名称或代码（如"茅台"或"600519"）
- 每只股票的占比、金额或股数（如有）
- 现金部分（如有）

格式不限，我来帮您整理。
```

如果用户第一条消息就是持仓列表，跳过开场白，直接进入阶段一（但仍然要先输出第 2 步的凭证提示语，如果有的话）。

### 凭证安全说明

- 凭证文件默认存储在 `~/.config/portfolio-health-check/credentials.env`，可通过 `PHC_CREDENTIALS_PATH` 覆盖；不在 skill 目录内
- 文件权限 600（仅当前用户可读写）
- skill 的 `.gitignore` 排除了 `*.env` 和 `credentials*`，即使误操作也不会被 git 跟踪
- `call_remote_phase_api.py` 和 `qveris_client.py` 会自动从该文件加载凭证，无需手动 source

## 数据流示意

每次进入阶段二时生成 `run_id`（UUID 前 8 位），本次咨询的所有中间文件存入 `state/{run_id}/`，按任务隔离。

```
阶段一输出:
  → 持仓确认表（在对话中展示）
  → 提取 holdings[] 数组 和 cash_pct 数值

阶段二输入:
  ← holdings[] + cash_pct + params{4个参数}
  → 写入: state/{run_id}/phase2_payload.json
  → 运行: python call_remote_phase_api.py phase2_pdf state/{run_id}/phase2_payload.json --output state/{run_id}/phase2_report.pdf
  → 输出: state/{run_id}/phase2_report.pdf（或降级为 state/{run_id}/phase2_result.json）

阶段三输入:
  ← state/{run_id}/phase2_result.json 的完整内容 作为 diagnosis_result
  ← constraints{用户约束}
  → 写入: state/{run_id}/phase3_payload.json
  → 运行: python call_remote_phase_api.py phase3 state/{run_id}/phase3_payload.json --output state/{run_id}/phase3_result.json
  → 输出: state/{run_id}/phase3_result.json + phase3_result.md + phase3_report.pdf（Phase 3 默认生成 PDF）
```

`state/{run_id}/` 下的文件都是当前咨询的临时状态，咨询结束时统一清理整个目录。

## 阶段一：快速诊断

调用子技能 `portfolio-quick-diagnosis/SKILL.md`，按照其中的 8 个步骤执行。

阶段一完成后，输出快速诊断报告，然后用以下话术过渡：

```
快速诊断完成。如果您希望进一步了解组合的量化风险指标，我可以进行**深度诊断**，包括：
- 相关性分析
- 风险贡献分解
- 因子暴露评估
- 流动性分析
- 关键风险提示

需要收集 4 个关于您投资风格的信息。是否继续？
```

## 阶段一 → 阶段二过渡

用户同意后，**一次性问完** Phase 2 的 4 个参数。不要逐题单独发送。应在同一条消息中列出全部问题，用户可按 `1-3-2-4` 或分行回复。

**严禁自行编造选项。必须逐字使用下方列出的中文选项，不得改写、合并、替换或自创任何选项（如"价值/成长/均衡""低/中/高""每月/每季度/每年"等都是错误的）。**

```
好的，一共 4 个问题，我一次问完，您按顺序回复数字即可，例如 `3-3-2-2`。

**问题 1：您平时多久调整一次持仓？**
1. 每天都会操作（日内交易）
2. 大约每周调整
3. 大约每月调整
4. 每季度调整
5. 基本不动，长期持有

**问题 2：您的仓位管理风格是？**
1. 择时空仓型 — 会根据行情空仓等机会
2. 满仓轮动 — 始终满仓，在不同股票间轮换
3. 恒定比例 — 维持固定比例，偏离时再平衡
4. 定投渐进 — 定期定额投入
5. 核心+卫星 — 大部分稳定持仓 + 小部分灵活操作

**问题 3：您的风险承受能力？**
1. 保守 — 尽量避免亏损
2. 稳健 — 可以接受一定波动
3. 积极 — 为了收益愿意承受较大波动
4. 激进 — 追求高收益，能承受大幅回撤

**问题 4：您的投资期限大约是？**
1. 不到 1 年
2. 1-3 年
3. 3-5 年
4. 5 年以上

另外，方便的话，也可以补充告诉我您的总投资金额大约是多少（用于流动性分析，可以不回答）。
```

用户回复后记录映射：1→`"intraday"` 2→`"weekly"` 3→`"monthly"` 4→`"quarterly"` 5→`"buy_and_hold"`

映射：1→`"market_timing"` 2→`"full_rotation"` 3→`"constant_mix"` 4→`"dca"` 5→`"core_satellite"`

映射：1→`"conservative"` 2→`"moderate"` 3→`"aggressive"` 4→`"very_aggressive"`

映射：1→`"<1y"` 2→`"1-3y"` 3→`"3-5y"` 4→`">5y"`

- 用户说"大概 50 万" → `portfolio_market_value: 500000`
- 用户说"不方便" / 不回答 → 不填此字段

**如果用户说"我不太懂这些"**：

```
没关系！如果不确定的话，我建议选择：
- 问题 1：每月调整（3）
- 问题 2：恒定比例（3）
- 问题 3：稳健（2）
- 问题 4：1-3 年（2）

这是大多数普通投资者的典型情况。您觉得可以吗？
```

如果用户只回复了部分答案，先基于已回复内容记录，再**在同一条补充消息里一次性问完剩余未答的问题**，不要重新从头逐题问。

## 阶段二：深度诊断

4 个参数收集完毕后，调用子技能 `portfolio-deep-diagnosis/SKILL.md`，按照其中的执行步骤运行。

阶段二完成后，用以下话术过渡：

```
深度诊断完成。如果您希望获得具体的优化建议，我们可以进入下一阶段——**优化处方**。需要了解您几个投资约束条件。是否继续？
```

## 阶段二 → 阶段三过渡

用户同意后，**一次性问完** Phase 3 的约束。不要逐题单独发送。多选题要求用户用逗号分隔。

```
好的，接下来几个约束我一次问完，您按顺序回复即可；多选题请用逗号分隔。

**问题 1：您可以投资哪些市场？（可多选，用逗号分隔）**
1. A 股
2. 港股通
3. 美股

**问题 2：您可以使用哪些投资工具？（可多选）**
1. 股票    2. ETF    3. 基金
4. 期货    5. 期权    6. 加密货币

不确定的话默认选 1 和 2。

**问题 3：您还有多少可追加的资金？**
1. 满仓，没有余量
2. 还有 10-30%
3. 还有 30-50%
4. 还有 50% 以上

**问题 4：您的投资目标是？（可多选）**
1. 资产增值
2. 稳定现金流（分红收息）
3. 对冲已有风险
4. 打新底仓

例如您可以回复：`1,2 / 1,2 / 2 / 1`
```

映射：1→`"A-share"` 2→`"HK"` 3→`"US"`。用户回复"1,2"→`["A-share", "HK"]`

映射：1→`"stock"` 2→`"etf"` 3→`"fund"` 4→`"futures"` 5→`"option"` 6→`"crypto"`

映射：1→`"none"` 2→`"10-30%"` 3→`"30-50%"` 4→`"50%+"`

映射：1→`"growth"` 2→`"income"` 3→`"hedge"` 4→`"ipo_base"`

如果用户只回复了部分约束，先记录已回复内容，再**一次性追问剩余未答项**，不要改成逐题追问。

## 阶段三：优化处方

约束收集完毕后，调用子技能 `portfolio-optimization/SKILL.md`，按照其中的执行步骤运行。

阶段三完成后收尾：

```
以上是基于您当前持仓和投资约束的优化建议，仅供参考，不构成具体买卖指令。如果您有任何疑问，欢迎随时讨论。
```

然后追加：

```
如果本次咨询到这里结束，出于隐私保护考虑，我会在结束后清理这次分析生成的临时文件，包括 `state/` 里的 payload、PDF 和结果 JSON。清理后这些文件将不会继续保留。
```

## 快捷流程（跳过深度诊断展示）

如果用户在阶段一完成后说"直接给我优化建议"或"跳过分析直接优化"：

1. 仍然需要收集 Phase 2 的 4 个参数（因为 Phase 3 依赖 Phase 2 的输出）
2. 生成 `run_id` 并组装 payload（同深度诊断第 1 步），**静默运行** Phase 2 API（用 `phase2` 而非 `phase2_pdf`）：
   ```bash
   python call_remote_phase_api.py phase2 state/{run_id}/phase2_payload.json --output state/{run_id}/phase2_result.json
   ```
3. **不要向用户展示 Phase 2 结果**
4. 告诉用户："好的，后台诊断已完成。接下来收集您的投资约束。"
5. 进入 Phase 3 约束收集和执行

## 常见场景处理

| 场景 | 处理方式 |
|------|---------|
| 用户分多条消息逐个给股票 | 等用户说"就这些"或"没了"后再开始处理 |
| 用户中途说"算了不看了" | 尊重用户意愿，告知"随时可以继续" |
| 用户问无关问题 | 简要回答后引导回当前阶段 |
| 用户想重新来过 | 先提醒旧的 `state/` 临时文件会被清理；随后清理旧文件，再重新开始阶段一 |
| 用户提供截图而非文字 | 识别截图中的持仓信息，整理成列表请用户确认 |

## 结束咨询与状态清理

- `state/{run_id}/` 下的所有文件都是本次咨询的临时文件
- **不要**在咨询尚未结束时主动清理
- 流程完成或用户表示结束时，提醒后删除整个目录：

```text
出于隐私保护考虑，我会删除本次分析的临时文件（state/{run_id}/ 目录）。
```

```bash
RUN_ID="<本次实际 run_id>"
[ -n "$RUN_ID" ] && rm -rf "state/$RUN_ID"
```

## 错误处理

| 错误类型 | 用户提示语 |
|---------|----------|
| QVeris 不可用 | "标的识别服务暂时不可用，我将通过网络搜索来确认股票信息。" |
| 远端 API 连接失败 | "分析服务暂时不可用，可能是服务器维护中。建议稍后再试。" |
| API 返回错误 | "分析过程中遇到问题：{error_message}。请检查持仓信息是否正确。" |

补充说明：
- Phase 2 通常耗时约 5 分钟，Phase 3 通常耗时约 7 分钟（含多次 LLM 调用）。如果轮询过程中发现任务排队（`queue > 0`），追加提醒"当前有其他任务排队，时间可能延长"。不要把客户端超时上限（30 分钟）当作预计等待时间告诉用户。
- 网络抖动时客户端会用同一幂等 key 自动重试 1 次，不会重复扣分；如两次都失败才会抛连接错误给用户。

## 禁止事项

- **禁止**询问用户"是否需要 PDF"或"是否生成报告"——PDF 是默认行为。