# Foresight 先见之明 — 产品需求文档 (PRD)

> **版本**：v0.3.3 — 2026-04-16 CustomGraphBuilder + 一键部署 + CDN SPA 修复
> **基线**：基于 [MiroFish](https://github.com/666ghj/MiroFish) v0.1.2 二次开发，已大量重构。

---

## 1. 产品定位

**Foresight 是一个把"需要预测的未知"变成"可演化的数字沙盘"的群体智能引擎。**

用户上传任何一份"信号"——一段视频文案、一份政策草案、一次金融事件复盘、一段小说背景——Foresight 自动构建该信号所属世界的知识图谱，孵化出几百个有完整人格、记忆、行为模式的虚拟 Agent，让他们在虚拟社交平台上自由互动、扩散、对抗、共鸣，最后输出一份"如果这件事真的发生，世界会变成什么样"的详尽预测报告。

**核心命题**：让"未来"在数字沙盘里先演练一遍，让决策在百战模拟之后才下刀。

### 三种使用形态

| 形态 | 用户 | 典型问题 | 输出 |
|---|---|---|---|
| **单次预测** | 个人 / 临时项目 | "这条视频发出去会火吗？" | 一份报告 + 可回放的传播沙盘 |
| **建模 + 复用** | 团队长期使用 | "我有一批 200 人的目标受众样本，每周给我跑 5 条新内容看哪个最容易出圈" | 同一批 agent 反复跑不同 initial_posts |
| **多租户 SaaS**（v0.4 路线图） | 客户分账户 | "金融预测 / 舆情扩散 / 关系发展 各建一套独立沙盘" | 子账户体系 + 按次计费 + 项目隔离 |

---

## 2. 产品愿景：从工具到平台

### 2.1 v0.3 现状（已实现）

一个**单租户**的端到端预测流水线：上传文档 → 图谱 → 人设 → 配置 → 模拟 → 报告 → 回放 → 互动。

### 2.2 v0.4 目标（下一个大版本）

**Foresight 升级为多领域可定制的预测系统。** 不再只服务"舆情扩散"一个场景，而是抽象为**"任何可被多 agent 互动建模的预测问题"**：

| 应用领域 | 输入信号 | Agent 类型 | 预测输出 |
|---|---|---|---|
| **内容传播预测** | 视频逐字稿 / 帖子文案 | 200 个画像各异的目标受众 | 触达率 / 互动率 / 传播路径 / 爆款概率 |
| **舆情扩散预测** | 突发事件 / 政策草案 | 不同立场的意见领袖 + 普通群众 | 舆论走向 / 关键拐点 / 情绪曲线 |
| **金融市场预测** | 财报 / 政策 / 黑天鹅事件 | 散户 / 机构 / 量化 / 媒体 | 价格反应 / 资金流向 / 板块联动 |
| **人际关系发展** | 角色背景 / 起始事件 | 故事中的所有角色 | 关系演化树 / 关键转折 / 多结局 |
| **品牌危机推演** | 危机事件 + 公关方案 | 用户 / 媒体 / 监管 / 竞品 | 不同应对策略下的舆情走向 |

**核心抽象**：每个领域 = 一组（领域语料 + 领域 agent 库 + 领域平台规则 + 领域评估指标）。Foresight 提供**通用的工作流编排**，领域知识用配置即可注入。

### 2.3 v0.5 商业化（远期）

- 子账户体系（org / user / project 三级权限）
- 按模拟次数 / agent 数 / 报告深度计费
- 模型 fork & 对比模式（A/B 内容对比传播效率）
- 数据隔离 + 合规审计

---

## 3. 系统架构（v0.3 实际部署）

```
                                                    ┌─────────────────────┐
                                                    │  M-flow（记忆系统） │
                                                    │  踩坑/经验/凭证记录 │
                                                    └─────────────────────┘
用户浏览器
  │
  ├── 前端 (Vue 3 + Vite)                          
  │     部署：腾讯云 COS + CDN
  │     域名：foresight.yizhou.chat
  │     新增页面：/simulation/:id/replay（Manus 式过程回放）
  │
  └── HTTPS → api.foresight.yizhou.chat (Nginx)
        │
        └── Backend Flask (5001)                    服务器：腾讯云 2C8G
              │                                      OS：Ubuntu 24.04
              │                                      Python：3.11.15 (uv 管理)
              │                                      venv：/opt/foresight/backend/.venv-311
              │
              ├── LLM API：智谱 GLM-4-Flash         （之前用 MiniMax M2.7，已弃）
              │     用途：本体、画像、配置、报告、模拟决策
              │     Endpoint：https://open.bigmodel.cn/api/paas/v4/
              │
              ├── Knowledge Graph：CustomGraphBuilder + Neo4j（v0.3.2 替代 Graphiti）
              │     部署：Docker 容器 neo4j:5.26-community
              │     图谱构建 LLM：GLM-4-Flash（同主 LLM，自带 retry + fallback）
              │     Embedding：BAAI/bge-m3 via SiliconFlow（仅下游检索用）
              │
              ├── HF Hub Mirror：hf-mirror.com      OASIS 推荐模型 twhin-bert-base
              │
              └── OASIS 模拟引擎                    fork 自 camel-oasis 0.2.5
                    支持 Twitter / Reddit 双平台并行
                    🚧 国内平台抽象层：v0.4 路线图（抖音/视频号/小红书/微博）
```

### 3.1 关键基础设施决策（v0.3 沉淀的经验）

| 决策点 | 当前选择 | 弃用方案 | 原因 |
|---|---|---|---|
| LLM | 智谱 GLM-4-Flash | MiniMax M2.7 / GPT-4o-mini | Flash 单次延迟 0.5-1s，128K context |
| 图谱构建 | **CustomGraphBuilder**（自研） | Graphiti + Qwen/GLM | Graphiti 与非 OpenAI LLM 兼容性黑洞（详见附录 C） |
| 知识图谱存储 | 自托管 Neo4j | Zep Cloud | 摆脱外部依赖、可控、免月费 |
| Python | 3.11（uv 管理） | 系统 3.12 | camel-oasis<3.12 不兼容 3.12 |
| 包源 | 腾讯云 PyPI 镜像 | 直连 PyPI | 国内服务器直连慢 100x |
| HF 模型源 | hf-mirror.com | huggingface.co | 国内服务器连不上 hf 主站 |
| Agent 数甜点 | **200 agents** | 503（默认） | 8G 内存上限 + 95% 置信区间足够 |
| 运行参数 | semaphore=100 / 双平台 | semaphore=30 / 单平台 | 8G 升级后可承载 |

---

## 4. 核心功能流水线（5 步 + 1 回放）

### Step 1: 知识图谱构建

**输入**：上传文档（PDF/MD/TXT/DOCX）+ 模拟需求自然语言描述

**流程**：
1. 文档解析 → 文本提取
2. LLM 分析全文 → 生成本体（10 个实体类型 + 6-10 个关系类型）
3. 文本分块 → 批量调用 Graphiti → 写入 Neo4j
4. 返回图谱可视化（节点 + 边）

**API**：
- `POST /api/graph/ontology/generate`
- `POST /api/graph/build`
- `GET /api/graph/task/<task_id>`

### Step 2: Agent 人设生成

**输入**：已构建的知识图谱

**流程**：
1. 从 Neo4j 读取图谱实体与关系
2. 按实体类型筛选，调用 LLM 为每个实体生成 OASIS Agent Profile
3. 每个 profile 含：人设故事 / MBTI / 年龄 / 职业 / 兴趣话题 / 活跃时段 / 互动倾向
4. 实时写入 `reddit_profiles.json` 和 `twitter_profiles.csv`

**新功能**（v0.3 新增）：
- **加速完成按钮**：右上角"加速完成"，用户可在生成到任意数量时立即停止剩余生成，使用已生成的 profile 进入下一步

**API**：`POST /api/simulation/prepare`

### Step 3: 模拟配置生成

**输入**：profiles + 模拟需求 + 文档原文

**流程**：
1. LLM 智能生成时间配置（peak hours / off-peak hours / 活跃度系数）
2. LLM 智能生成事件配置（initial_posts 列表 + 轮次事件）
3. LLM 为每个 agent 分配活跃时段、互动概率
4. 输出 `simulation_config.json`

### Step 4: 双平台模拟运行

**输入**：profiles + simulation_config

**流程**：
1. 启动 OASIS Twitter env + Reddit env 并行（asyncio.gather）
2. 每轮按时间窗口激活若干 agent
3. 每个激活的 agent 调用 LLM 生成行为（发帖 / 评论 / 点赞 / 转发 / 关注）
4. 实时写入 `twitter/actions.jsonl` 和 `reddit/actions.jsonl`
5. 每平台限制 semaphore=100 防止 API 过载

**性能指标**（200 agents 双平台 8G 服务器）：
- 启动 + tokenizer 加载：~30-60s
- 每轮：~30-60s（取决于活跃 agent 数）
- 15 rounds 完整跑完：~10-15 分钟

**API**：
- `POST /api/simulation/start` — 启动
- `POST /api/simulation/stop` — 停止
- `GET /api/simulation/<id>/run-status/detail` — 实时状态

**新功能**（v0.3 新增）：
- **后端 SIGTERM 误杀子进程 bug 修复**：之前重启 Flask 会连带杀掉正在跑的模拟，已通过让 `register_cleanup` 变为 no-op 修复，现在可以热更新后端代码不影响运行中的模拟。

### Step 5: 报告生成

**输入**：完整模拟结果 + 知识图谱

**流程**：
1. LLM 规划报告大纲（5 个章节）
2. 每章节 ReACT 循环（推理 → 工具调用 → 生成）
3. 工具：图谱搜索（InsightForge / Panorama）/ 节点详情 / agent 行为统计
4. 输出结构化 Markdown 报告

**API**：`POST /api/report/generate`

> Token 消耗最大的环节，单次完整报告约 80-150K tokens。

### Step 6（新增）: Manus 式过程回放

**v0.3 新增的核心功能**。把整个 Foresight 工作流（Step 1-5）做成可拖拽 / 可播放的可视化时间线，方便给客户、合作方、自己复盘演示。

**界面布局**：

```
┌─────────────────────────────────────────────────────┐
│ ← 返回   foresight 回放  sim_xxxx   [running]       │
├─────────┬──────────────────────────────┬────────────┤
│ 工作流  │  当前动作（大卡片）           │ 全局统计   │
│ 时间线  │   ┌─────────────────────┐    │            │
│         │   │ 👤 90后 (#6)         │    │ 总动作 N   │
│ ● 步骤1 │   │ 📱 reddit            │    │ rounds 8   │
│ │ 文档  │   │ ✏️ CREATE_POST       │    │            │
│ │       │   │ "芒格说复利..."       │    │ 类型分布   │
│ ● 步骤2 │   └─────────────────────┘    │  POST  85%│
│ │ 图谱  │                              │  LIKE  12%│
│ │       │   动作流（滚动 30 条）        │            │
│ ● 步骤3 │   ┌─────────────────────┐    │ Top Agents │
│ │ 人设  │   │ r03 90后 ✏️ ...      │    │ 90后    8 │
│ │       │   │ r03 70后 💬 ...      │    │ 00后    6 │
│ ● 步骤4 │   │ r04 AI   📤 ...      │    │            │
│ │ 配置  │   └─────────────────────┘    │ 平台分布   │
│ │       │                              │ TW 17 RD 8 │
│ ● 步骤5 │                              │            │
│   模拟  │                              │            │
├─────────┴──────────────────────────────┴────────────┤
│ ⏮ ▶ ⏭   ━━━━━●─────  Round 8/15  Day 1 08:00       │
│            速度 0.5x · 1x · 2x · 5x · 10x           │
└─────────────────────────────────────────────────────┘
```

**核心能力**：
- 左栏：5 步工作流时间线（带状态 + 元数据）
- 中上：当前动作大卡片（agent 头像 + 内容 + 平台/类型 tag）
- 中下：动作流滚动（最近 30 条，可点击跳转）
- 右栏：聚合统计（总数 / 类型分布 bar / Top 8 agents / 平台分布卡）
- 底部：scrubber 时间轴 + 播放控件 + 5 档速度

**数据源**：`GET /api/simulation/:id/replay` 一次性返回所有数据，前端无需多次请求。

**最新 run 过滤**：actions.jsonl 是 append-only 文件，多次 run 会累积。后端通过扫描最近一次 `simulation_start` 事件的时间戳，过滤掉历史 run 残留 actions，保证回放只显示最新一次。

---

## 4.5 Token 用量追踪与成本估算（v0.3 新增 · 内部用）

为了支持后续定价决策和成本控制，v0.3 新增 token 追踪模块。**销售给客户的版本需要移除此 blueprint 注册**（去掉 `app/__init__.py` 里的 `usage_bp` 即可）。

### 工作机制

- `backend/app/utils/token_tracker.py` 提供进程内全局 stage→model→tokens 计数器
- `LLMClient` 每次 `chat()` 自动 record 一次 `usage.prompt_tokens / completion_tokens`
- 各 API 端点在入口处 `token_tracker.set_stage("step1_ontology")` 等
- 价格表内置在 `PRICING` 字典，覆盖 GLM / SiliconFlow / MiniMax / OpenAI / Anthropic 主流模型

### Stage 命名

| Stage | 触发位置 | 说明 |
|---|---|---|
| `step1_ontology` | `POST /api/graph/ontology/generate` | 文档分析与本体生成 |
| `step2_graph_build` | `POST /api/graph/build` | Graphiti 图谱构建（含 LLM 提取实体） |
| `step3_prepare` | `POST /api/simulation/prepare` | Profile 生成 + 模拟配置生成 |
| `step4_simulation` | OASIS 子进程（**不在 Flask 内**） | 需要走 `estimate-simulation` API 估算 |
| `step5_report` | `POST /api/report/generate` | 报告 ReACT 多轮调用 |

### API

| 端点 | 用途 |
|---|---|
| `GET /api/usage/summary` | 当前累计统计：每个 stage 的 prompt/completion tokens + 估算成本（CNY） |
| `POST /api/usage/reset` | 清空（可指定 stage） |
| `GET /api/usage/estimate-simulation?rounds=15&active_agents_per_round=10` | 估算 OASIS 模拟成本（无法精确测） |
| `POST /api/usage/set-stage` | 手动切 stage（测试用） |

### 局限

1. **OASIS 模拟子进程的 LLM 调用无法被 Flask 进程的 tracker 捕获**（camel-ai 用自己的 client）。需要走 estimate API 用经验公式估算。
2. **进程重启会丢失数据**。如需持久化，加 `reset()` 前 dump 到 JSON 文件即可。
3. **价格表是 2026-04 价格快照**，需要定期更新 `PRICING` 字典。

### 典型 Foresight 单次完整流水线成本估算（200 agents / 15 rounds / GLM-4-Flash）

| Stage | Tokens 范围 | CNY 估算 |
|---|---|---|
| Step 1 本体生成 | 5K-15K | 0.001-0.003 |
| Step 2 图谱构建 | 50K-200K | 0.005-0.020 |
| Step 3 Profile + Config | 100K-300K | 0.010-0.030 |
| Step 4 模拟 (15 rounds) | 1M-3M | 0.10-0.30 |
| Step 5 报告生成 | 80K-150K | 0.008-0.015 |
| **合计** | **~1.2M-3.7M** | **~0.12-0.37 元** |

> 关键洞察：**模拟运行 (Step 4) 占总成本的 80%+**，但因为 GLM-4-Flash 单价极低，单次完整流水线 < 0.5 元 RMB。这给定价留了巨大空间：以成本 0.5 元 / 次，售价 5-50 元 / 次给客户都是合理的（取决于客户类型与定制化程度）。

---

## 5. v0.4 路线图（下一个大版本要做的事）

按优先级：

### P0：国内平台抽象层

**痛点**：当前 Twitter + Reddit 是欧美社交语境，国内 IP / 内容 / 客户都不匹配。

**目标**：支持抖音 / 视频号 / 小红书 / 微博 / 公众号 5 个国内平台。

**两条路径**：

| 路径 A（快速 MVP，2-3 周） | 路径 B（真模拟，1-2 月） |
|---|---|
| 基于 OASIS Reddit 模式 fork 一份"通用国内平台"虚拟实现 | 抛弃 OASIS，自研 platform engine |
| 不真正模拟抖音 ML 算法，用参数化传播模型 | 真模拟抖音 FYP / 视频号双引擎 / 小红书 tag 聚类 |
| LLM 决定 agent 互动 + 配置文件定义平台规则参数 | 行业报告训练参数 + 黑盒推荐算法逼近 |
| 可申请客户付费试点 | 可申请专利 / 学术发表 |

**先走路径 A**，3 周内可演示。客户付费数据反哺路径 B。

**配置形态（设计稿）**：

```json
{
  "platforms": [
    {
      "id": "douyin",
      "type": "short_video",
      "weight": 0.45,
      "rules": {
        "recommendation": "fyp_engagement_loop",
        "viral_threshold": 0.08,
        "interaction_types": ["like", "comment", "share", "follow", "watch_full"],
        "key_features": ["video_completion_rate", "comment_density", "share_velocity"]
      }
    },
    { "id": "xiaohongshu", "type": "lifestyle_feed", "weight": 0.25, "rules": {...} },
    { "id": "wechat_video", "type": "social_graph_video", "weight": 0.15, "rules": {...} },
    { "id": "weibo", "type": "broadcast_micro_blog", "weight": 0.10, "rules": {...} },
    { "id": "wechat_official", "type": "subscription_long_form", "weight": 0.05, "rules": {...} }
  ]
}
```

### P1：模型复用 / Fork 模拟

**痛点**：现在每次跑模拟都要走完 Step 1-4，重复劳动。

**目标**：基于已建好的 simulation 一键 fork 一个新版本，只换 `event_config.initial_posts` 即可。

**功能点**：
- "Fork as Template" 按钮
- 模板库：保存通过验证的 sim 作为预设
- A/B 对比模式：两条新内容并排跑，结果并排展示

### P2：多租户 SaaS 改造

**功能模块**（需要派出 8 个并行 sub-agent 协同开发）：

| Sub-Agent | 模块 | 任务 |
|---|---|---|
| Architect | 多租户架构 | PostgreSQL schema 隔离 / API gateway / RBAC 设计 |
| Backend Engineer | API 改造 | 加 user_id / org_id / billing 字段，所有数据按租户隔离 |
| Frontend Engineer | UI 改造 | 登录 / 注册 / dashboard / 子账户管理界面 |
| Platform Engine | 平台抽象 | 上面 P0 的国内平台抽象层落地 |
| Auth & Security | 认证 | 接 Better Auth / OAuth / API key 发放 |
| Billing | 计费 | 接微信 / 支付宝 / Stripe，按模拟次数 / agent 数计费 |
| DevOps | 容器化 | Docker + k8s + 监控 + 扩容策略 |
| PM/Critic | 全程 review | 商业目标对齐 + 架构 review |

### P3：稳定性 / 运维改进

- ✅ Backend SIGTERM 误杀子进程 bug（v0.3 已修）
- ⏳ 子进程心跳超时：当前 simulation 子进程挂掉后 state 不会自动更新成 failed，需要加心跳检测
- ⏳ 模拟运行内存预算检查：启动前根据 agent 数 + 平台数预估内存，超出可用内存时拒绝启动
- ⏳ Replay actions.jsonl 自动清理：每次新 run 启动前清空旧文件，避免历史残留
- ⏳ 多模拟并发支持：单服务器同时跑 2-3 个 sim（需要更大内存或更精细资源调度）

---

## 6. 技术栈

### 前端

| 技术 | 版本 | 用途 |
|---|---|---|
| Vue 3 | 3.5+ | UI 框架（Composition API + script setup） |
| Vite | 7.x | 构建工具 |
| Vue Router 4 | - | 路由 |
| vue-i18n | 9.x | 中英双语 |
| D3.js / Force Graph | - | 图谱可视化 |
| 字体 | Space Grotesk + Noto Sans SC + JetBrains Mono | 设计语言 |

### 后端

| 技术 | 版本 | 用途 |
|---|---|---|
| Python | 3.11.15 (uv 管理) | 运行时 |
| Flask | 3.1.3 | Web 框架 |
| OpenAI SDK | - | LLM 客户端（兼容智谱/MiniMax/SiliconFlow） |
| camel-ai | 0.2.78 | OASIS 依赖 |
| camel-oasis | 0.2.5 | 社交模拟引擎 |
| graphiti-core | - | Neo4j 图谱构建框架 |
| transformers + torch | - | OASIS 内置 twhin-bert-base |
| neo4j-driver | - | Neo4j 客户端 |

### 部署

| 组件 | 平台 | 说明 |
|---|---|---|
| 前端静态 | 腾讯云 COS + CDN | foresight.yizhou.chat |
| SSL 证书 | acme.sh / Let's Encrypt | 自动续期 |
| 后端 | 腾讯云轻量 2C8G Ubuntu 24.04 | api.foresight.yizhou.chat → 127.0.0.1:5001 |
| Neo4j | Docker container neo4j:5.26-community | bolt://localhost:7687 |
| 进程管理 | nohup + disown（无 systemd / 无 docker） | 启动命令见下 |

**Backend 启动命令**：

```bash
cd /opt/foresight/backend && \
  nohup ./.venv-311/bin/python run.py --host 0.0.0.0 \
    >> logs/server.log 2>&1 < /dev/null & \
  disown
```

---

## 7. 配置项

```env
# ========== LLM ==========
# 智谱 GLM-4-Flash（高吞吐低延迟，OASIS 模拟首选）
LLM_API_KEY=<智谱 API Key>
LLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4/
LLM_MODEL_NAME=glm-4-flash
# 可选升级：glm-4-flashx / glm-4-air / glm-4-plus（同 endpoint，质量↑速度↓）

# 双 LLM 加速（可选，让两平台用不同 provider 分摊 RPM）
LLM_BOOST_API_KEY=
LLM_BOOST_BASE_URL=
LLM_BOOST_MODEL_NAME=

# ========== Neo4j（自托管 Graphiti 后端） ==========
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=<密码>

# ========== Graphiti LLM（图谱构建） ==========
GRAPHITI_LLM_API_KEY=<SiliconFlow API Key>
GRAPHITI_LLM_BASE_URL=https://api.siliconflow.cn/v1
GRAPHITI_LLM_MODEL=Qwen/Qwen2.5-32B-Instruct

# ========== Embedding ==========
EMBEDDING_API_KEY=<SiliconFlow API Key>
EMBEDDING_BASE_URL=https://api.siliconflow.cn/v1
EMBEDDING_MODEL=BAAI/bge-m3

# ========== HuggingFace 镜像（必填，国内服务器） ==========
HF_ENDPOINT=https://hf-mirror.com

# ========== Flask ==========
FLASK_DEBUG=False
```

---

## 8. v0.3 当前状态与已交付

### v0.3.3（2026-04-16 CustomGraphBuilder + 一键部署 + CDN 修复）

- [x] **CustomGraphBuilder 替代 Graphiti**（v0.3.2 核心交付）
  - 完全自研的图谱构建器，不依赖 graphiti-core 库
  - 每 chunk 单次 LLM 调用（Graphiti 需要 4-5 次）→ 速度 4-5x
  - ThreadPoolExecutor 10 并发 → 194 chunks 从 10 分钟降到 ~2 分钟
  - 直接用 cypher MERGE 写 Neo4j → 无 Graphiti 嵌套 dict / context overflow 等兼容性问题
  - 使用 Foresight LLMClient 自带 retry + fallback + token tracker
  - 下游 `get_all_nodes / get_all_edges / filter_defined_entities` 完全兼容
  - 文件：`backend/app/services/custom_graph_builder.py`

- [x] **一键部署脚本** `scripts/deploy.sh`
  - `--backend`：rsync → 语法检查 → kill/restart Flask → health verify
  - `--frontend`：vite build → coscmd upload → tccli CDN purge
  - `--full`：两个都做
  - `--dry-run`：预演
  - 处理路径空格 / sudo rsync / Flask 存活检查

- [x] **CDN SPA 路由 fallback**
  - 问题：Vue Router history 模式，COS 上子路径全部 404
  - 修复：`tccli cdn UpdateDomainConfig` 设置 404 → 302 跳转 `/index.html`
  - 永久配置，deploy.sh 不需要每次重新设

- [x] **前端首次正式部署到腾讯云 COS**
  - `coscmd upload -r dist/ /` → bucket `foresight-1317962478`
  - CDN purge → `tccli cdn PurgePathCache`
  - 包含 v0.3 所有前端改动（replay UI / 加速完成按钮 / 路由修复）

- [x] **Graphiti 兼容层保留**
  - graphiti_client.py 中的 5 层 monkey-patch 保留（driver / reranker / embedder / EntityNode / bulk_utils）
  - 这些只影响旧 Graphiti 代码路径（add_episode / add_episodes_batch）
  - 新 CustomGraphBuilder 完全绕过，不受影响

### v0.3.1 hotfix（2026-04-15 生产链路打通）

经过一次完整的端到端测试，修复了 7 个阻塞生产跑通的 bug：

- [x] **Manus 式沉浸视图重构** — 回放界面从三栏分析面板 → Manus 风格单栏 cinematic 视图
  - 顶部 breadcrumb、浏览器外壳 + 平台原生帖子卡片、Jump to live 按钮、live 指示灯
  - 右上角 ◫/▦ 可切回三栏分析视图
  - 自动轮询：sim running 时每 10s 拉数据
  - 文件：`frontend/src/views/SimulationReplayView.vue`

- [x] **LLM 客户端指数退避重试** — 识别 `RateLimitError / 429 / 5xx / 1302 / 超时`，5 次重试 1→2→4→8→16s 带随机抖动
  - 文件：`backend/app/utils/llm_client.py`

- [x] **GLM → Qwen 32B 双 LLM 降级 fallback** — 主 LLM 重试耗尽后自动切 SiliconFlow Qwen 32B 单次兜底，解决 GLM 低 RPM 配额的间歇性限流
  - 文件：`backend/app/services/ontology_generator.py`

- [x] **Qwen 32B 上下文爆修复** — `MAX_TEXT_LENGTH_FOR_LLM` 50000 → 28000 chars，保证 prompt+response < 32768 tokens
  - 文件：`backend/app/services/ontology_generator.py`

- [x] **Neo4j entity summary flatten** — monkey-patch `Neo4jEntityNodeOperations.save/save_bulk`，LLM 返回嵌套 dict 时自动取 `.value` 扁平化，防 Neo4j TypeError
  - 文件：`backend/app/services/graphiti_client.py`

- [x] **Frontend 无 pending state 路由修复** — `/process/new` 访问时无上传状态，自动 `router.replace({name:'Home'})` 不再死循环
  - 文件：`frontend/src/views/MainView.vue`

- [x] **semaphore 100 → 30** — OASIS 模拟并发峰值降低，避免 GLM 限流雪崩
  - 文件：`backend/scripts/run_parallel_simulation.py`

### v0.3 完成（本次大版本前的全部更新）

#### 基础设施迁移
- [x] 从 Zep Cloud → 自托管 Graphiti + Neo4j（脱离外部 SaaS 依赖）
- [x] LLM 从 MiniMax M2.7 → 智谱 GLM-4-Flash（速度提升 2-5x）
- [x] Python 3.12 → 3.11.15（uv 管理 .venv-311，解决 camel-oasis 兼容性）
- [x] 服务器从 2C4G → 2C8G（解决 OOM 崩溃）
- [x] 加 4G swap → 总可用内存 ~13G
- [x] 配置 hf-mirror.com（解决 twhin-bert-base 下载卡死）

#### 性能优化
- [x] semaphore 30 → 100（每轮 2-3x 加速）
- [x] 找到 200 agents 内存/性能/统计置信度甜点
- [x] 双平台并行（Twitter + Reddit asyncio.gather）

#### 新功能
- [x] **Step 2 加速完成按钮**：profile 生成中可一键停止剩余、用已有进入下一步
- [x] **Manus 式过程回放界面**（核心 v0.3 交付）
  - 后端 `GET /api/simulation/:id/replay` 一次性返回全部回放数据
  - 前端 `/simulation/:id/replay` 三栏布局 + scrubber + 5 档播放速度
  - 工作流时间线 + 当前动作卡 + 滚动 feed + 聚合统计
  - 自动过滤历史 run 残留 actions

#### Bug 修复
- [x] **Backend SIGTERM 误杀模拟子进程 bug**：之前重启 Flask 会连带杀子进程，现已修复，可热更新后端代码不影响正在跑的模拟
- [x] CORS / Neo4j Query / DateTime 序列化等历史 bug

#### 文档与记忆系统
- [x] 部署信息全部归档到 M-flow（infra / lessons / services / credentials）
- [x] PRD.md / README.md 重写

### v0.4 待完成（路线图详见 §5）

- [ ] **国内平台抽象层**（P0）— 抖音 / 视频号 / 小红书 / 微博 / 公众号
- [ ] **Fork 模拟 + A/B 对比**（P1）— 模型复用与对比演化
- [ ] **多租户 SaaS 改造**（P2）— 子账户体系 + 计费 + 数据隔离
- [ ] **稳定性运维**（P3）— 子进程心跳 / 内存预算检查 / 自动清理

---

## 9. 关键文件索引

### 后端

| 路径 | 用途 |
|---|---|
| `backend/run.py` | Flask 入口 |
| `backend/app/__init__.py` | Flask 初始化（注意：v0.3 已移除 register_cleanup 的破坏性 signal handler） |
| `backend/app/api/graph.py` | 图谱构建 API |
| `backend/app/api/simulation.py` | 模拟 / prepare / start / stop / **replay**（新增 line ~2005） |
| `backend/app/api/report.py` | 报告生成 API |
| `backend/app/services/ontology_generator.py` | LLM 本体生成 |
| `backend/app/services/graph_builder.py` | Graphiti / Neo4j 图谱构建 |
| `backend/app/services/oasis_profile_generator.py` | Agent 画像生成（含加速完成 cancel_check 逻辑） |
| `backend/app/services/simulation_config_generator.py` | 模拟配置生成 |
| `backend/app/services/simulation_manager.py` | 模拟管理（含 accelerate flag） |
| `backend/app/services/simulation_runner.py` | 模拟运行（含 v0.3 register_cleanup 修复） |
| `backend/app/services/report_agent.py` | 报告 ReACT 生成 |
| `backend/scripts/run_parallel_simulation.py` | 双平台并行模拟脚本（semaphore=100） |

### 前端

| 路径 | 用途 |
|---|---|
| `frontend/src/router/index.js` | 路由（v0.3 新增 `/simulation/:id/replay`） |
| `frontend/src/api/simulation.js` | 模拟相关 API client |
| `frontend/src/views/SimulationReplayView.vue` | **v0.3 新增** Manus 式回放主界面 |
| `frontend/src/views/SimulationView.vue` | 模拟运行界面 |
| `frontend/src/views/SimulationRunView.vue` | 模拟启动界面 |
| `frontend/src/views/ReportView.vue` | 报告查看 |
| `frontend/src/components/Step2EnvSetup.vue` | Step 2 环境设置（v0.3 新增加速完成按钮） |

### 部署 / 运维

| 路径 | 说明 |
|---|---|
| `.env` | API Keys 与配置（智谱 / Neo4j / SiliconFlow / HF mirror） |
| `docker-compose.yml` | Neo4j 容器配置 |
| `~/.claude/projects/.../memory/` | M-flow 记忆系统索引（OpenClaw 内部） |

### 服务器（远程）

| 路径 | 说明 |
|---|---|
| `/opt/foresight/backend/` | 后端代码 |
| `/opt/foresight/backend/.venv-311/` | Python 3.11 虚拟环境（5.1G） |
| `/opt/foresight/backend/uploads/simulations/sim_<id>/` | 单次模拟数据目录 |
| `/opt/foresight/backend/logs/server.log` | Flask 日志 |
| `/opt/foresight/.env` | 服务器配置 |
| `/etc/nginx/sites-enabled/foresight-api` | Nginx 反代配置 |

---

## 10. 已知限制与边界

| 限制 | 说明 | 缓解策略 |
|---|---|---|
| Agent 数 ≤ 200（双平台 2C8G） | 超过会 OOM | 升级 4C16G / 单平台 / 拆分 batch |
| 国内平台未支持 | 当前只有 Twitter+Reddit | v0.4 P0 |
| 单租户 | 多客户共用一套数据 | v0.4 P2 |
| 子进程心跳缺失 | sim 挂了 state 仍是 running | v0.4 P3 |
| 报告生成 Token 消耗大 | 单次 80-150K | 优化 prompt / 缓存图谱搜索结果 |
| 重启 sim 需手动 reset state | 半死 state 阻塞下次启动 | v0.4 P3 加 force-restart 按钮 |

---

## 附录 A：v0.3 关键运维教训

1. **Python 版本约束必须 pre-flight 检查**：`requirements.txt` 改动后立刻验证 venv 兼容
2. **国内服务器装包必走腾讯云镜像**：`uv pip install --index-url http://mirrors.tencentyun.com/pypi/simple --trusted-host mirrors.tencentyun.com`
3. **HuggingFace 模型必配 `HF_ENDPOINT=https://hf-mirror.com`**：否则 OASIS 启动卡死
4. **遇到模拟卡死先看 simulation.log 最后 10 行**，不要先猜 LLM 慢
5. **8G 内存只能跑 200 agents 双平台**，503 会 OOM。要 503 双平台需升级 16G
6. **重启 Flask 不再杀子进程**（v0.3 修复后），可以安全热更新代码
7. **GLM-4-Flash 是 OASIS 场景的最优 LLM**：旗舰模型反而是反向优化（每次调用 2-5s 太慢）

## 附录 B：决策日志

| 日期 | 决策 | 原因 |
|---|---|---|
| 2026-04-13 | 从 Zep Cloud → Graphiti+Neo4j | 脱离外部依赖 |
| 2026-04-14 | LLM 切 GLM-4-Flash | MiniMax 速度不够 |
| 2026-04-14 | uv + Python 3.11 重建 venv | camel-oasis 不支持 3.12 |
| 2026-04-14 | 服务器升级 2C8G | 3.6G 跑不动 OASIS |
| 2026-04-14 | 配 hf-mirror.com | 服务器连不上 huggingface |
| 2026-04-15 | 修复 SIGTERM 误杀 bug | 热更新后端不再中断模拟 |
| 2026-04-15 | 200 agents 设为甜点 | 8G 容量 + 95% 置信度足够 |
| 2026-04-15 | 上线 Manus 式 replay UI | 给客户演示 + 复盘工具 |
| 2026-04-15 | v0.4 路线图：国内平台 + SaaS | 用户战略需求 |
| 2026-04-16 | v0.3.3 CustomGraphBuilder 替代 Graphiti | Graphiti 兼容性死循环，10+ 次 patch 仍无法稳定 |
| 2026-04-16 | 一键部署脚本 deploy.sh | 手动 scp 反复漏文件，accelerate 方法都没部署上 |
| 2026-04-16 | CDN SPA fallback 404→302 | coscmd 部署后前端所有子路由 404 |
| 2026-04-16 | 图谱构建并发化 (10 workers) | 串行太慢（10 分钟 → 2 分钟） |
| 2026-04-15 | v0.3.1 hotfix：7 个 bug 修复 | 第一次完整 E2E 跑通压力测试 |
| 2026-04-15 | LLM client 加指数退避重试 + 双 LLM fallback | GLM RPM 配额低，retry 不够兜底 |
| 2026-04-15 | Replay UI 重构为 Manus cinematic 风格 | 三栏分析面板对客户演示不够"沉浸" |
| 2026-04-15 | semaphore 100 → 30 | 高并发触发 GLM 限流雪崩 |

## 附录 C：Graphiti 弃用记录

v0.3.2 决定用自研 CustomGraphBuilder 替代 Graphiti。以下是尝试修复 Graphiti 兼容性的完整过程。

### 尝试过的 10 次 Patch

| # | 问题 | Patch 位置 | 结果 |
|---|---|---|---|
| 1 | Qwen 32B 32K context 超窗口 | ontology_generator MAX_TEXT=28000 | ✅ 但这不是主问题 |
| 2 | Neo4j TypeError 嵌套 dict | EntityNode.save monkey-patch | ❌ Graphiti 不走这条路径 |
| 3 | 同上 | bulk_utils.add_nodes_and_edges_bulk_tx | ❌ 也不走这条路径 |
| 4 | 同上 | neo4j AsyncSession.run driver 层 | ✅ 终于拦到了 |
| 5 | Qwen 累积上下文爆 60-82K | chunk_size 500→250 | ❌ 爆的是检索上下文不是 chunk |
| 6 | 同上 | 换 Qwen 72B（以为 128K） | ❌ SiliconFlow 72B 也是 32K |
| 7 | 同上 | 换智谱 GLM-4-Flash 128K | ❌ GLM 20015 "parameter invalid" |
| 8 | GLM reranker logprobs 不支持 | patch reranker.rank() | ✅ 但不是主路径 |
| 9 | GLM embedder 空 input | patch embedder.create_batch() | ✅ 但不是主路径 |
| 10 | GLM extract_nodes 全部 fail | 未找到根因 | ❌ 直接测能过、生产必挂 |

### 为什么自研是正确决策

1. **Graphiti 为 OpenAI 设计**：内部 4-5 次 LLM 调用路径各自有 OpenAI 特有参数（logprobs / structured output / json_schema），非 OpenAI provider 每条路径都是独立陷阱
2. **patch 层次太深**：至少 5 层（EntityNode / bulk_utils / driver / reranker / embedder），每层 fix 一个又冒下一个
3. **上下文累积不可控**：Graphiti 的 episode 检索机制会从已有图谱拉上下文，后续 episode prompt 越来越长，32K 模型必爆，128K 模型也不是免费的
4. **每 chunk 4-5 次 LLM 调用**：extract_nodes + dedupe_nodes + extract_edges + dedupe_edges + community_summary，成本和延迟 4-5x
5. **CustomGraphBuilder 只需 1 次调用/chunk**：直接 prompt → JSON → cypher MERGE，完全受控

### CustomGraphBuilder 架构

```
输入: 完整文档文本 + ontology 定义
  ↓
字符级切分 (250 chars, 50 overlap)
  ↓
ThreadPoolExecutor (10 workers 并发)
  ↓ 每个 worker:
  LLMClient.chat_json(extract prompt)  ← 一次调用，自带 retry + fallback
  ↓ 返回:
  {"entities": [...], "relationships": [...]}
  ↓
串行 MERGE 到 Neo4j (去重 by name + group_id)
  ↓
输出: {entities_count, edges_count, chunks_processed}
```

### 保留的 Graphiti 代码

`graphiti_client.py` 中的读取方法（`get_all_nodes / get_all_edges / get_node / get_node_edges`）仍然使用 Neo4j 直接查询，**不依赖 Graphiti 库**。`add_episode / add_episodes_batch` 保留但不再被主流水线调用。5 层 monkey-patch 保留作为安全网。

## 附录 D：部署流程

### 后端部署（最常用）

```bash
./scripts/deploy.sh              # rsync + restart Flask + health verify
./scripts/deploy.sh --no-restart  # 只同步代码不重启
```

### 前端部署

```bash
./scripts/deploy.sh --frontend    # vite build + coscmd upload + CDN purge
```

### 全量部署

```bash
./scripts/deploy.sh --full        # 后端 + 前端
```

### CDN SPA 配置（一次性）

```bash
tccli cdn UpdateDomainConfig --cli-unfold-argument \
  --Domain foresight.yizhou.chat \
  --ErrorPage.Switch on \
  --ErrorPage.PageRules.0.StatusCode 404 \
  --ErrorPage.PageRules.0.RedirectCode 302 \
  --ErrorPage.PageRules.0.RedirectUrl "https://foresight.yizhou.chat/index.html"
```

### COS 配置

- Bucket: `foresight-1317962478`
- Region: `ap-guangzhou`
- 凭证: `~/.cos.conf`（SecretId/SecretKey）
- 工具: `coscmd`（pip install）