芥子 · Wispverse
一个潜伏者引导微型文明走向辉煌历史的 AI 原生演化模拟游戏。
花园里有 15-20 个拟人化角色自主演化出分工、社会与文化；而玩家是"花园中的第 21 个角色"——伪装成它们同类的潜伏者，在暴露风险之下用极少数"抉择时刻"暗中引导文明，直到最终被它们觉醒指认。
核心特性
- 潜伏者叙事：玩家不是"神"，而是潜伏者。以第 21 个角色身份混入生态，潜伏越久、引导越深，被指认时的揭露冲击越大。最终多结局由玩家的行为模式决定。
- 角色创建与自定义命名：单页化创建流程，5 个化身（叶影/溪灵/砚心/林歌/云游）+ surprise 彩蛋；支持自定义名字，"第 21 个角色"以玩家赋予的名字入场，缺省回退化身默认名。
- 首日任务式引导（Learn by doing）：选择身份前世界沉睡——prelude 阶段渲染星夜花园氛围、零轮询零渲染，世界在玩家醒来前不剧透、不运转；老玩家回归一次探测直接恢复。首日以 3 个真实任务（观察 / 对话 / 需求）引导上手，行为检测判定完成，支持跳过。
- Flow 状态机（7 态判别联合）：场景流转收敛为纯函数状态机——prelude/dawn/day1/garden/decision/chronicle/ending 七相，携带 payload（回归时长 hoursAway、首日任务进度 taskIndex），非法转移幂等回退，场景时机不再散落于组件。
- Pacing 系统：PacingDirector 三铁律（事件可归因生态 / 3 游戏日间隔上限 / B 轨频次硬约束）把控叙事节奏，Pacing Mode 三档（快速 60s / 标准 600s / 自定义）适配演示与正式体验；A 轨反馈契约（确定性回报零 LLM + 变比回报）保证"等待期不是空窗"。
- 行动分层解锁：能力沿时间线逐步解锁——Day1 观察/移动 → Day3 对话 → Day5 送礼/帮忙 → 时代2 引导；未解锁动作灰显并给出"今天会解锁"提示，避免新人误入歧途。
- 双轨介入系统：A 轨为实体伪装操作（化身在花园中的日常行为），B 轨为抉择时刻（全局仅 5-8 次的文明拐点神迹），两条轨道共用一套暴露风险账本，介入越激进风险越高。
- 暴露风险系统：NPC 会观察、记忆并传播玩家的"异常"行为，疑点沿关系网络扩散、权重累积，最终触发揭露与终局对话；风险条按疑点动态出现/隐藏，不打扰沉浸。
- 工具调用层（受控 Tool Use 桥接）：LLM 决策 → 结构化 tool_calls → 游戏 API → 世界变更 → 观察反馈的完整闭环。10 个受控工具（invite_to_event / give_item / move_to_location / start_conversation / update_relationship / share_knowledge 等）全部走五步执行链：schema 校验 → 权限校验 → 确定性执行 → 失败重试 → 全链路 EventLog；行为蒸馏产物落成 Voyager 式技能库（token/embedding 双检索），工具数收敛 10（BFCL 口径 ≤15，规避精度骤降区间）。
- 三时代跃迁：文明从伙伴聚落到部落再到完整文明期，跨时代推进由系统自动判定，配套时代过渡动画与编年史书写。
- AI 角色智能（Agentopia 对齐）：
- 价值权重目标系统——每个角色的行为由价值向量目标驱动，而非脚本
- 生活奖励闭环——社会/主观/经济三维奖励 + 优势采样，构成自我强化循环
- 性格 trait 化——7 档离散 × 3 连续参数的性格建模
- 记忆文件化——三旋钮（检索 Top-K / 衰减 / 写入频率）可调的记忆管理
- 行为蒸馏——从历史行为提炼可复用的模式
- LLM-as-Judge 合规——双铁律校验，杜绝越权与非法行为
- 信息可见性分层——玩家视角与系统真相分层呈现
- 多结局系统：结局 A/B/C/D + "那扇门"选择，揭露程度与潜伏深度共同决定终局。
- 沉浸式舞台净化：Tick / 连接状态 / 天气控制等"舞台之外的东西"收敛进开发者浮层（
?dev=1 才挂载），主界面保持"花园是一出戏"的完整沉浸。
架构
graph TD
subgraph FE[React 前端]
Prelude[SleepingGarden 沉睡氛围 + 序章] -->|选身份后醒来| Canvas[花园画布 Canvas 2D]
Canvas --> Store[全局状态 + Flow 状态机 7 态]
Player[玩家面板 / 行动分层 / 暴露风险条] --> Store
Guide[FirstDayGuide 首日引导] --> Store
Overlay[抉择时刻 / 时代过渡覆盖层] --> Store
Chronicle[花园编年史时间轴] --> Store
Dev[DevDock 开发者浮层 ?dev=1<br/>U12 工具评测面板<br/>U21 节奏仪表盘] --> Store
end
Store -->|HTTP /api| API[FastAPI 网关]
subgraph BE[后端 · 每 5s tick]
API --> Scheduler[花园调度器]
Scheduler --> SM[Agent 状态机]
Scheduler --> Mem[四层记忆系统<br/>瞬时/短期/长期/文件化]
Scheduler --> Dec[决策引擎<br/>双轨介入判定]
Scheduler --> Exp[暴露风险系统<br/>观察/疑点传播]
Scheduler --> Chron[事件生成 / 编年史]
Scheduler --> Goal[目标系统 / 生活奖励闭环]
Scheduler --> Belief[贝叶斯信念引擎<br/>KG-as-Belief-State]
Scheduler --> Week[周制模拟<br/>Plan/Contact/Activity/Review]
Scheduler --> Pacing[PacingDirector<br/>三铁律 + A 轨反馈契约]
Scheduler --> Tools[工具调用层<br/>Registry/Executor/Skills]
end
SM -->|关键决策| LLM[LLM 网关<br/>opencode + deepseek-v4-flash]
Dec --> LLM
Goal --> LLM
Belief --> LLM
Tools --> LLM
Exp --> Judge[LLM-as-Judge 合规校验]
Mem --> Retriever[混合检索<br/>知识边界⊕规则⊕BM25⊕向量]
Retriever --> DB[(PostgreSQL + pgvector<br/>Repository 契约)]
Belief --> DB
Chron --> DB
Tools --> EventLog[(EventLog 审计日志<br/>内存环 + JSONL 落盘)]
技术栈
- 前端：React 18 + TypeScript + Vite + Canvas 2D + Zustand
- 后端：Python + FastAPI，自研内存状态机（每个角色独立运行）
- AI 层：LLM 网关（opencode + deepseek-v4-flash，成本梯度路由 + 失败降级规则模板）+ 本地 embedding（bge-m3）+ 规则引擎（日常行为零 LLM）
- 数据：PostgreSQL + pgvector 正式存储（Repository 契约 + InMemory 双实现，
DATABASE_URL 路由）+ SQLAlchemy 2.0
- 企业化组件：贝叶斯信念引擎 / 混合检索四路融合 / 合规中间件（未成年人模式·时长提醒·AI 标识）/ 自研 Trace 层（JSONL + LangSmith/Langfuse 导出）/ ContentProduct 内容商品契约 / 输入污染防御（三关过滤 + 审计回滚）/ Pacing 叙事节奏 / 受控工具调用层（BFCL 口径评测）
- 测试：pytest 44 模块 625 用例（含 v4.2 专项、Pacing 专项、TP-22 工具层 + PostgreSQL 真实集成测试）+ Playwright E2E 11 spec / 43 用例
快速开始
演示模式（零依赖，内存仓储 + 规则模板 LLM）
# 1. 后端
cd backend
pip install fastapi uvicorn
uvicorn api:app --port 42732
# 2. 前端
cd frontend
npm install
npm run dev -- --port 42731
浏览器打开 http://localhost:42731，以第 21 个角色身份进入花园。
生产模式（PostgreSQL 存储 + 真实 LLM）
前置：本机 PostgreSQL 已运行（127.0.0.1:5432）；配置 LLM_API_KEY。
cd backend
LLM_API_KEY=sk-... python scripts/run_production.py --port 42732
脚本自动：检查并拉起 PostgreSQL → 创建 wispverse 库 → 注入 DATABASE_URL + LLM 环境变量 → 启动 uvicorn。数据落 PostgreSQL（8 类表：characters / memory_entries / belief_entries / event_log / goals / relationships / player_state / trace_log），向量列在 pgvector 启用环境自动升级为 vector(384) + HNSW 索引。
测试
cd backend
python -m pytest # 625 用例（无 DATABASE_URL 时 PG 集成测试自动跳过）
DATABASE_URL="postgresql+psycopg2://postgres:[email protected]:5432/wispverse" \
python -m pytest tests/test_postgres_integration_v42.py # PostgreSQL 真实读写
cd frontend && npx playwright test # E2E 43 用例
主要 API
| 端点 |
说明 |
GET /api/state |
完整花园状态（角色/环境/事件/时代/信念/合规/trace） |
POST /api/player/select |
选择化身 + 自定义名字（可选，回退默认名） |
POST /api/player/action |
A 轨：化身日常行为（经输入污染防御三关过滤） |
GET /api/player/state |
玩家外部视角 + 暴露风险 |
GET /api/decision / POST /api/decision/respond |
B 轨：抉择时刻 |
GET /api/chronicle |
花园编年史 |
POST /api/reveal |
最终揭露对话 |
GET /api/rewards/status |
生活奖励闭环状态 |
GET /api/beliefs |
信念系统 + 信念图谱（KG 力导向图） |
GET /api/defense/audit |
输入污染防御审计（投毒拦截可视化） |
GET /api/trace/diagnostics |
Trace 诊断 + 记忆装配 + 混合检索四路得分 |
GET/PUT /api/compliance/settings |
合规设置（未成年人模式 / 时长限额 / AI 标识） |
GET /api/compliance/session |
会话时长监控（≥2h 世界内提醒） |
GET /api/content-products |
内容商品目录（买叙事 · 免费摘要/付费全量） |
GET /api/weekly |
周制模拟（NPC 下周计划） |
GET /api/pacing/mode / PUT |
Pacing 档位查询与切换（快速 60s / 标准 / 自定义） |
GET /api/pacing/stats / signals |
节奏统计 / 信念→信号四信号（试探对话/窃窃私语/眼神回避/编年史措辞） |
POST /api/pacing/eval/run |
玩家体验评测（with/without Pacing 对照，三指标验收线） |
GET /api/v1/tools |
工具清单（TP-22，DevDock U12 面板） |
POST /api/v1/tools/execute |
执行单次工具调用（真实世界变更） |
GET /api/v1/tools/eval |
BFCL 口径评测指标（工具选择/参数合规/执行成功/全链路可追踪） |
GET /api/v1/tools/eventlog |
工具执行审计日志（行为溯源） |
评测
- 单元/集成测试：pytest 44 个模块 625 用例，覆盖 Agent 状态机、四层记忆、双轨决策、暴露风险传播、时代跃迁、多结局、目标系统、奖励闭环、Judge 合规、信息可见性分层、自定义命名链路、混合检索四路融合、贝叶斯信念引擎、合规中间件、Trace 层、输入污染防御、ContentProduct 契约、周制模拟、Pacing 系统（模式/三铁律/反馈契约/描述生成）与 PostgreSQL 真实读写
- 工具调用评测：BFCL 口径四项指标全 1.0（工具选择 / 参数合规 / 执行成功 / 全链路可追踪）+ 畸形调用拦截 1.0，工具层新增 71 用例零破坏回归
- 玩家体验评测（Pacing 对照）：虚拟玩家脚本 + 种子固定，with/without 对照实测——启用 Pacing 后正反馈间隔 10.8s/166 次 vs 未启用 19.6s/92 次，"等待期不是空窗"可证
- E2E 测试：Playwright 11 个 spec / 43 用例，覆盖化身选择与命名、A 轨融入、暴露行为疑点记录、抉择时刻响应、编年史展示、首日任务引导、行动分层锁定、开发者浮层、合规设置、输入审计、信念图谱、记忆装配诊断、投毒攻击拦截、Pacing 档位与仪表盘、工具调用面板（真实执行 + BFCL 五项评测）
Wispverse(芥子)是一款 AI 原生的演化模拟游戏:15-20 个拟人化角色在花园里自主发展出分工、社会和文化,而你扮演第 21 个角色——一名伪装潜入者,在稀有的决策时刻暗中引导这个文明,直到他们最终把你揪出来。