diff --git a/README.md b/README.md index 7263461..fc5e03a 100644 --- a/README.md +++ b/README.md @@ -1,87 +1,81 @@ -# AetherLife / 以太人生 +# AetherLife [![CI](https://github.com/moyunzero/AetherLife/actions/workflows/ci.yml/badge.svg)](https://github.com/moyunzero/AetherLife/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE) -> **EN:** AetherLife is a multiplayer life-simulation web game where you guide memory-bearing NPCs through natural language in a procedural pixel world. Colyseus handles authoritative sync; LangGraph workers run async NPC turns with persistent pgvector memory. -> -> **中文：** AetherLife 是一款 AI 驱动的多人联机生活模拟 Web 游戏。玩家用自然语言指挥拥有持久记忆的 NPC，在 Phaser 4 程序化世界中探索与叙事；Colyseus 权威同步，LangGraph worker 异步执行 NPC 回合。 - -## Table of Contents / 目录 - -- [About / 项目简介](#about--项目简介) -- [Project Status / 项目状态](#project-status--项目状态) -- [Demo / 演示](#demo--演示) -- [Features / 特性](#features--特性) -- [Tech Stack / 技术栈](#tech-stack--技术栈) -- [Quick Start / 快速开始](#quick-start--快速开始) -- [Architecture / 架构](#architecture--架构) -- [Testing / 测试](#testing--测试) -- [Documentation / 文档](#documentation--文档) -- [Contributing / 贡献](#contributing--贡献) -- [License](#license) +**English** | [简体中文](./README.zh-CN.md) + +AI-driven multiplayer life-simulation web game: guide memory-bearing NPCs through natural language in a procedural pixel world. Colyseus handles authoritative sync; LangGraph workers run async NPC turns with persistent pgvector memory. -## About / 项目简介 +## Table of Contents + +- [About](#about) +- [Project Status](#project-status) +- [Demo](#demo) +- [Features](#features) +- [Tech Stack](#tech-stack) +- [Quick Start](#quick-start) +- [Architecture](#architecture) +- [Testing](#testing) +- [Documentation](#documentation) +- [Contributing](#contributing) +- [License](#license) -**EN:** Players explore a Stardew-inspired 2D world, discover LLM-generated lore, and shape NPC collective attitudes through dialogue and actions. The core loop—**perceive → remember → reflect → act**—must be verifiable in every milestone removed from quest-strip UI in favor of ambient world echo. +## About -**中文：** 玩家在星露谷式 2D 世界中探索、发现 LLM 注入的区块 lore，并通过对话与行为影响 NPC 对群体的集体态度。核心闭环——**感知 → 记忆 → 反思 → 执行**——须在每次会话中可验证；v4 起移除任务条 UI，改为 ambient 世界回响。 +Players explore a Stardew-inspired 2D world, discover LLM-generated lore, and shape NPC collective attitudes through dialogue and actions. The core loop—**perceive → remember → reflect → act**—must be verifiable in every session. Since v4, quest-strip UI was removed in favor of ambient world echo. -**Target audience / 目标用户:** Life-sim fans (*The Sims*, *Animal Crossing*, *Minecraft*), AI enthusiasts, and narrative-driven multiplayer players. +**Target audience:** Life-sim fans (*The Sims*, *Animal Crossing*, *Minecraft*), AI enthusiasts, and narrative-driven multiplayer players. -## Project Status / 项目状态 +## Project Status | Milestone | Phases | Status | Shipped | |-----------|--------|--------|---------| -| **v0** Phase 0 text loop | 01–05 | ✅ Shipped / 已交付 | 2026-06-04 | +| **v0** Phase 0 text loop | 01–05 | ✅ Shipped | 2026-06-04 | | **v1** Graphics + multiplayer + world | 06–08, 10–12.1 (09 deferred) | ✅ Shipped | 2026-06-07 | | **v2** Playable AI town | 12.2–15 | ✅ Shipped | 2026-06-09 | | **v3** Intelligent ambient + Speak SLA | 16–17.1, 18 | ✅ Shipped | 2026-06-11 | | **v4** Solo life loop | 19–22 | ✅ Shipped | 2026-06-22 | -| **v5** AI Society / Council Worldview | 23–27 | 🔨 In progress / 进行中 | Phase 23 ✅ (2026-06-25) | -| **Deferred** Voice pipeline | 09 | ⏸ Deferred / 暂缓 | — | +| **v5** AI Society / Council Worldview | 23–27 | 🔨 In progress | Phase 23 ✅ (2026-06-25) | +| **Deferred** Voice pipeline | 09 | ⏸ Deferred | — | -**EN:** Phase 24–27 (world chronicle, council vote/debate, 12-NPC map presence, personal life timeline) are planned. See the full development history for every phase, decision, and verification gate. +Phases 24–27 (world chronicle, council vote/debate, 12-NPC map presence, personal life timeline) are planned. -**中文：** Phase 24–27（世界编年史、议会辩论表决、12 NPC 上地图、个人人生时间线）规划中。完整 37 个 Phase 的开发时间、思路、状态与验收命令见开发历程文档。 +→ **[Development History](./docs/DEVELOPMENT-HISTORY.md)** · [简体中文](./docs/DEVELOPMENT-HISTORY.zh-CN.md) -→ **[Development History / 开发历程](./docs/DEVELOPMENT-HISTORY.md)** - -## Demo / 演示 +## Demo | | | |---|---| -| **Local / 本地** | [http://localhost:5173](http://localhost:5173) — run `pnpm dev:stack` | -| **Screenshots / 截图** | _Coming soon / 即将补充_ | -| **Public deploy / 公网部署** | _Not yet available / 暂无_ | - -## Features / 特性 - -| EN | 中文 | -|----|------| -| **Multiplayer** — Colyseus authoritative sync, up to 4 players per room | **多人联机** — Colyseus 权威同步，最多 4 人同房间 | -| **Natural language** — ai-gateway parses intent; worker runs async NPC turns | **自然语言指挥** — ai-gateway 解析意图，worker 异步执行 NPC 回合 | -| **Persistent memory** — Postgres + pgvector; NPCs remember and adapt | **持久记忆** — Postgres + pgvector，NPC 记住互动并影响后续行为 | -| **Phaser 4 world** — Grid movement, procedural chunks, world lore | **Phaser 4 世界** — 网格移动、程序化 chunk 地形与世界 lore | -| **Intelligent ambient NPCs (v3)** — Schedule/zone wander, async LLM intent, Tiled collision | **智能 Ambient NPC（v3）** — schedule/zone 漫游、异步 LLM intent、Tiled 碰撞 | -| **Speak SLA (v3)** — worker-state cache, stale fallback, multi-tab speak | **Speak SLA（v3）** — worker-state / memory-context 缓存、stale fallback、多 Tab speak | -| **Collective attitude** — NPC group attitude evolves with player behavior | **集体态度** — NPC 对玩家/群体的态度随行为演化 | -| **Council personas (v5)** — 12-NPC registry, `__council__` memory scope (Phase 23) | **议会人格（v5）** — 12 人 registry、`__council__` 记忆 scope（Phase 23） | - -## Tech Stack / 技术栈 - -| Layer / 层 | Technology / 技术 | -|------------|-------------------| -| Client / 客户端 | React 19 · Vite · Phaser 4 | -| Realtime / 实时 | Colyseus · SSE | +| **Local** | [http://localhost:5173](http://localhost:5173) — run `pnpm dev:stack` | +| **Screenshots** | _Coming soon_ | +| **Public deploy** | _Not yet available_ | + +## Features + +- **Multiplayer** — Colyseus authoritative sync, up to 4 players per room +- **Natural language** — ai-gateway parses intent; worker runs async NPC turns +- **Persistent memory** — Postgres + pgvector; NPCs remember and adapt +- **Phaser 4 world** — Grid movement, procedural chunks, world lore +- **Intelligent ambient NPCs (v3)** — Schedule/zone wander, async LLM intent, Tiled collision +- **Speak SLA (v3)** — worker-state cache, stale fallback, multi-tab speak +- **Collective attitude** — NPC group attitude evolves with player behavior +- **Council personas (v5)** — 12-NPC registry, `__council__` memory scope (Phase 23) + +## Tech Stack + +| Layer | Technology | +|-------|------------| +| Client | React 19 · Vite · Phaser 4 | +| Realtime | Colyseus · SSE | | AI | LangGraph worker · FastAPI gateway | -| Data / 数据 | Supabase Postgres · Upstash Redis | +| Data | Supabase Postgres · Upstash Redis | Monorepo: `apps/web` · `apps/game-server` · `apps/ai-gateway` · `workers/agent-worker` · `packages/*` -## Quick Start / 快速开始 +## Quick Start -### Prerequisites / 前置条件 +### Prerequisites - Node.js 20+, pnpm 9+ (`corepack enable && corepack prepare pnpm@9.15.0 --activate`) - [Supabase](https://supabase.com) project (Postgres + `CREATE EXTENSION vector`) @@ -89,7 +83,7 @@ Monorepo: `apps/web` · `apps/game-server` · `apps/ai-gateway` · `workers/agen - Python 3.12+, [uv](https://docs.astral.sh/uv/) (ai-gateway / worker) - LLM API keys (see `.env.example`; production defaults to **NVIDIA NIM** + OpenRouter embed) -### Install & run / 安装与启动 +### Install & run ```bash git clone https://github.com/moyunzero/AetherLife.git @@ -104,11 +98,10 @@ pnpm dev:stack Open **http://localhost:5173** in your browser. Press `Ctrl+C` to stop all local processes. -**EN:** No local Postgres/Redis required — dev uses Supabase + Upstash cloud. UI smoke: `pnpm dev:stack:mock`. Phase verification scripts require **real LLM** (`pnpm dev:stack`, never `LLM_MOCK=1`). - -**中文：** 无需本地 Postgres/Redis — 开发默认使用 Supabase + Upstash 云实例。UI 冒烟可用 `pnpm dev:stack:mock`；**phase 验收脚本须真实 LLM**（`pnpm dev:stack`，禁止 `LLM_MOCK=1`）。 +> No local Postgres/Redis required — dev uses Supabase + Upstash cloud. +> UI smoke: `pnpm dev:stack:mock`. Phase verification scripts require **real LLM** (`pnpm dev:stack`, never `LLM_MOCK=1`). -### Health checks / 健康检查 +### Health checks ```bash curl -sf http://127.0.0.1:5173/ @@ -116,7 +109,7 @@ curl -sf http://127.0.0.1:2567/health curl -sf http://127.0.0.1:8000/health ``` -## Architecture / 架构 +## Architecture ```mermaid flowchart LR @@ -131,16 +124,16 @@ flowchart LR Worker --> PG ``` -| Service / 服务 | Port / 端口 | Role / 职责 | -|----------------|-------------|-------------| +| Service | Port | Role | +|---------|------|------| | web | 5173 | UI; proxies `/v1` → gateway, `/api` → game-server | | game-server | 2567 | Colyseus rooms, SSE, memory API | | ai-gateway | 8000 | NL parse, input guard, chat ingress | | agent-worker | — | Redis queue consumer, LangGraph NPC turns | -Per-terminal debug / 分终端调试: `pnpm dev` · `pnpm dev:ai` · `pnpm dev:worker` (equivalent to `pnpm dev:stack`). +Per-terminal debug: `pnpm dev` · `pnpm dev:ai` · `pnpm dev:worker` (equivalent to `pnpm dev:stack`). -## Testing / 测试 +## Testing ```bash pnpm turbo test @@ -148,23 +141,21 @@ pnpm turbo build pnpm verify # build + test + verify:cloud pnpm agent:verify # diff → mapped unit tests (mock LLM OK) -# Cross-layer unit tests (mock LLM OK) / 跨层单测 +# Cross-layer unit tests (mock LLM OK) pnpm --filter @aetherlife/game-server test cd workers/agent-worker && LLM_MOCK=1 uv run pytest -q cd apps/ai-gateway && uv run pytest tests -q ``` -**EN:** Phase integration gates require `pnpm dev:stack` + real API keys — see [CONTRIBUTING.md](./CONTRIBUTING.md#集成验收). Golden flows: `pnpm agent:verify --e2e --base` ([E2E-POLICY.md](./docs/E2E-POLICY.md)). - -**中文：** Phase 集成验收需 `pnpm dev:stack` + 真实 API Key，见 [CONTRIBUTING.md](./CONTRIBUTING.md#集成验收)。Golden Flows：`pnpm agent:verify --e2e --base`（[docs/E2E-POLICY.md](./docs/E2E-POLICY.md)）。 +Phase integration gates require `pnpm dev:stack` + real API keys — see [CONTRIBUTING.md](./CONTRIBUTING.md#集成验收). Golden flows: `pnpm agent:verify --e2e --base` ([E2E-POLICY.md](./docs/E2E-POLICY.md)). Action schema: [packages/game-actions/README.md](./packages/game-actions/README.md) -## Documentation / 文档 +## Documentation -| Document / 文档 | Description / 说明 | -|-----------------|-------------------| -| **[Development History / 开发历程](./docs/DEVELOPMENT-HISTORY.md)** | All 37 phases: timeline, rationale, status, verify gates | +| Document | Description | +|----------|-------------| +| **[Development History](./docs/DEVELOPMENT-HISTORY.md)** | All 37 phases: timeline, rationale, status, verify gates | | [CONTRIBUTING.md](./CONTRIBUTING.md) | Workflow, constraints, acceptance commands | | [docs/CONTRACTS.md](./docs/CONTRACTS.md) | game-server ↔ worker API contracts | | [docs/INVARIANTS-MULTIPLAYER.md](./docs/INVARIANTS-MULTIPLAYER.md) | Multiplayer spatial + NL invariants | @@ -172,11 +163,9 @@ Action schema: [packages/game-actions/README.md](./packages/game-actions/README. | [docs/E2E-POLICY.md](./docs/E2E-POLICY.md) | E2E / UAT policy + Golden Flows | | [docs/PHASE-EVOLUTION.md](./docs/PHASE-EVOLUTION.md) | Phase evolution + cross-layer guardrails | -## Contributing / 贡献 - -**EN:** Issues and PRs welcome. Read [CONTRIBUTING.md](./CONTRIBUTING.md) first. Never commit `.env` or API keys. +## Contributing -**中文：** 欢迎 Issue 与 PR。请先阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)。请勿提交 `.env` 或 API 密钥。 +Issues and PRs welcome. Read [CONTRIBUTING.md](./CONTRIBUTING.md) first. Never commit `.env` or API keys. ## License diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..056433a --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,173 @@ +# 以太人生 / AetherLife + +[![CI](https://github.com/moyunzero/AetherLife/actions/workflows/ci.yml/badge.svg)](https://github.com/moyunzero/AetherLife/actions/workflows/ci.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE) + +[English](./README.md) | **简体中文** + +AI 驱动的多人联机生活模拟 Web 游戏：与拥有记忆的 NPC 用自然语言互动，在可扩展的程序化世界中移动、协作与叙事。Colyseus 权威同步，LangGraph worker 异步执行 NPC 回合，Postgres + pgvector 持久记忆。 + +## 目录 + +- [项目简介](#项目简介) +- [项目状态](#项目状态) +- [演示](#演示) +- [特性](#特性) +- [技术栈](#技术栈) +- [快速开始](#快速开始) +- [架构](#架构) +- [测试](#测试) +- [文档](#文档) +- [贡献](#贡献) +- [License](#license) + +## 项目简介 + +玩家在星露谷式 2D 世界中探索、发现 LLM 注入的区块 lore，并通过对话与行为影响 NPC 对群体的集体态度。核心闭环——**感知 → 记忆 → 反思 → 执行**——须在每次会话中可验证；v4 起移除任务条 UI，改为 ambient 世界回响。 + +**目标用户：** 喜欢《模拟人生》《动物森友会》《我的世界》的玩家、AI 爱好者，以及偏社交与叙事驱动的玩家。 + +## 项目状态 + +| 里程碑 | Phases | 状态 | 交付日期 | +|--------|--------|------|----------| +| **v0** Phase 0 文本闭环 | 01–05 | ✅ 已交付 | 2026-06-04 | +| **v1** 图形 + 多人 + 世界 | 06–08, 10–12.1（09 暂缓） | ✅ 已交付 | 2026-06-07 | +| **v2** 可玩的 AI 小镇 | 12.2–15 | ✅ 已交付 | 2026-06-09 | +| **v3** 智能 Ambient + Speak SLA | 16–17.1, 18 | ✅ 已交付 | 2026-06-11 | +| **v4** 自主人生闭环 | 19–22 | ✅ 已交付 | 2026-06-22 | +| **v5** AI 议会 / 世界观 | 23–27 | 🔨 进行中 | Phase 23 ✅（2026-06-25） | +| **暂缓** 语音管线 | 09 | ⏸ 暂缓 | — | + +Phase 24–27（世界编年史、议会辩论表决、12 NPC 上地图、个人人生时间线）规划中。 + +→ **[开发历程](./docs/DEVELOPMENT-HISTORY.zh-CN.md)** · [English](./docs/DEVELOPMENT-HISTORY.md) + +## 演示 + +| | | +|---|---| +| **本地** | [http://localhost:5173](http://localhost:5173) — 运行 `pnpm dev:stack` | +| **截图** | _即将补充_ | +| **公网部署** | _暂无_ | + +## 特性 + +- **多人联机** — Colyseus 权威同步，最多 4 人同房间 +- **自然语言指挥** — ai-gateway 解析意图，worker 异步执行 NPC 回合 +- **持久记忆** — Postgres + pgvector，NPC 记住互动并影响后续行为 +- **Phaser 4 世界** — 网格移动、程序化 chunk 地形与世界 lore +- **智能 Ambient NPC（v3）** — schedule/zone 漫游、异步 LLM intent、Tiled 碰撞 +- **Speak SLA（v3）** — worker-state / memory-context 缓存、stale fallback、多 Tab speak +- **集体态度** — NPC 对玩家/群体的态度随行为演化 +- **议会人格（v5）** — 12 人 registry、`__council__` 记忆 scope（Phase 23） + +## 技术栈 + +| 层 | 技术 | +|----|------| +| 客户端 | React 19 · Vite · Phaser 4 | +| 实时 | Colyseus · SSE | +| AI | LangGraph worker · FastAPI gateway | +| 数据 | Supabase Postgres · Upstash Redis | + +Monorepo：`apps/web` · `apps/game-server` · `apps/ai-gateway` · `workers/agent-worker` · `packages/*` + +## 快速开始 + +### 前置条件 + +- Node.js 20+、pnpm 9+（`corepack enable && corepack prepare pnpm@9.15.0 --activate`） +- [Supabase](https://supabase.com) 项目（Postgres + `CREATE EXTENSION vector`） +- [Upstash](https://upstash.com) Redis +- Python 3.12+、[uv](https://docs.astral.sh/uv/)（ai-gateway / worker） +- LLM API Key（见 `.env.example`；生产默认 **NVIDIA NIM** + OpenRouter embed） + +### 安装与启动 + +```bash +git clone https://github.com/moyunzero/AetherLife.git +cd AetherLife +pnpm install +cp .env.example .env # 填入 DATABASE_URL、REDIS_URL、LLM 密钥 +pnpm verify:cloud +pnpm --filter @aetherlife/npc-memory db:migrate +cd apps/ai-gateway && uv sync --extra dev && cd ../.. +pnpm dev:stack +``` + +浏览器打开 **http://localhost:5173**。`Ctrl+C` 停止全部本地进程。 + +> 无需本地 Postgres/Redis — 开发默认使用 Supabase + Upstash 云实例。 +> UI 冒烟可用 `pnpm dev:stack:mock`；**phase 验收脚本须真实 LLM**（`pnpm dev:stack`，禁止 `LLM_MOCK=1`）。 + +### 健康检查 + +```bash +curl -sf http://127.0.0.1:5173/ +curl -sf http://127.0.0.1:2567/health +curl -sf http://127.0.0.1:8000/health +``` + +## 架构 + +```mermaid +flowchart LR + Browser["浏览器 :5173"] --> Web["Vite web"] + Web -->|"/api"| GS["game-server :2567"] + Web -->|"/v1"| GW["ai-gateway :8000"] + GW --> GS + GS --> Redis["Upstash Redis"] + Worker["agent-worker"] --> Redis + Worker --> GS + GS --> PG["Supabase Postgres"] + Worker --> PG +``` + +| 服务 | 端口 | 职责 | +|------|------|------| +| web | 5173 | UI；代理 `/v1` → gateway、`/api` → game-server | +| game-server | 2567 | Colyseus 房间、SSE、记忆 API | +| ai-gateway | 8000 | NL 解析、输入审核、chat 入口 | +| agent-worker | — | Redis 队列消费，NPC LangGraph 回合 | + +分终端调试：`pnpm dev` · `pnpm dev:ai` · `pnpm dev:worker`（等价于 `pnpm dev:stack`）。 + +## 测试 + +```bash +pnpm turbo test +pnpm turbo build +pnpm verify # build + test + verify:cloud +pnpm agent:verify # diff → mapped unit tests (mock LLM OK) + +# 跨层单测（可 mock LLM） +pnpm --filter @aetherlife/game-server test +cd workers/agent-worker && LLM_MOCK=1 uv run pytest -q +cd apps/ai-gateway && uv run pytest tests -q +``` + +Phase 集成验收（需 `pnpm dev:stack` + 真实 API Key）：见 [CONTRIBUTING.md](./CONTRIBUTING.md#集成验收)。 +Golden Flows：`pnpm agent:verify --e2e --base`（[docs/E2E-POLICY.md](./docs/E2E-POLICY.md)）。 + +Action schema：[packages/game-actions/README.md](./packages/game-actions/README.md) + +## 文档 + +| 文档 | 说明 | +|------|------| +| **[开发历程](./docs/DEVELOPMENT-HISTORY.zh-CN.md)** | 全部 37 Phase：时间线、思路、状态、验收命令 | +| [CONTRIBUTING.md](./CONTRIBUTING.md) | 协作流程、约束与验收命令 | +| [docs/CONTRACTS.md](./docs/CONTRACTS.md) | game-server ↔ worker API 契约 | +| [docs/INVARIANTS-MULTIPLAYER.md](./docs/INVARIANTS-MULTIPLAYER.md) | 多人空间与 NL 不变量 | +| [docs/MOVEMENT-ARCHITECTURE.md](./docs/MOVEMENT-ARCHITECTURE.md) | Phaser 移动与 Colyseus 同步 | +| [docs/E2E-POLICY.md](./docs/E2E-POLICY.md) | E2E / UAT 策略与 Golden Flows | +| [docs/PHASE-EVOLUTION.md](./docs/PHASE-EVOLUTION.md) | 阶段演进与跨层防债务 | + +## 贡献 + +欢迎 Issue 与 PR。请先阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)。请勿提交 `.env` 或 API 密钥。 + +## License + +[MIT](./LICENSE) diff --git a/docs/DEVELOPMENT-HISTORY.md b/docs/DEVELOPMENT-HISTORY.md index 10c1912..b4b64e1 100644 --- a/docs/DEVELOPMENT-HISTORY.md +++ b/docs/DEVELOPMENT-HISTORY.md @@ -1,30 +1,30 @@ -# Development History / 开发历程 +# Development History -**AetherLife / 以太人生** — phased delivery record from v0 (text loop) through v5 (AI Society). +**English** | [简体中文](./DEVELOPMENT-HISTORY.zh-CN.md) -**EN:** This document synthesizes all **37 development phases** (including sub-phases). Each entry covers goal, rationale, deliverables, verification, tech decisions, known debt, and related issues. Internal planning artifacts are not linked; content is derived from shipped milestones and verification records. +**AetherLife** — phased delivery record from v0 (text loop) through v5 (AI Society). -**中文：** 本文档合成 **37 个开发 Phase**（含子阶段）的完整记录。每条含目标、思路、交付、验收、技术决策、已知债务与关联 ISSUE。不链接内部 planning 目录；内容来自已 ship 里程碑与验收记录。 +This document synthesizes all **37 development phases** (including sub-phases). Each entry covers goal, rationale, deliverables, verification, tech decisions, known debt, and related issues. -**Last updated / 最后更新:** 2026-06-25 +**Last updated:** 2026-06-25 --- -## Table of Contents / 目录 +## Table of Contents -- [Timeline Overview / 时间线总览](#timeline-overview--时间线总览) +- [Timeline Overview](#timeline-overview) - [Milestone v0 — Phase 0 Text Loop](#milestone-v0--phase-0-text-loop) - [Milestone v1 — Graphics + Multiplayer + World](#milestone-v1--graphics--multiplayer--world) - [Milestone v2 — Playable AI Town](#milestone-v2--playable-ai-town) - [Milestone v3 — Intelligent Ambient + Speak SLA](#milestone-v3--intelligent-ambient--speak-sla) - [Milestone v4 — Solo Life Loop](#milestone-v4--solo-life-loop) - [Milestone v5 — AI Society (In Progress)](#milestone-v5--ai-society-in-progress) -- [Global Deferred Items / 全局暂缓项](#global-deferred-items--全局暂缓项) -- [How to Verify / 如何验收](#how-to-verify--如何验收) +- [Global Deferred Items](#global-deferred-items) +- [How to Verify](#how-to-verify) --- -## Timeline Overview / 时间线总览 +## Timeline Overview | Milestone | Phases | Status | Shipped | |-----------|--------|--------|---------| @@ -36,13 +36,9 @@ | **v4** Solo life loop | 19–22 | ✅ Shipped | 2026-06-22 | | **v5** AI Society / Council Worldview | 23–27 | 🔨 In progress | Phase 23 ✅ 2026-06-25 | -**EN — v0→v4 arc:** Text-only Generative Agent loop → Colyseus multiplayer + Phaser world → visual polish + town play loop → ambient intelligence + speak reliability → immersive solo life with memory trust and world echo. +**v0→v4 arc:** Text-only Generative Agent loop → Colyseus multiplayer + Phaser world → visual polish + town play loop → ambient intelligence + speak reliability → immersive solo life with memory trust and world echo. -**中文 — v0→v4 脉络：** 纯文本 Generative Agent 闭环 → Colyseus 多人 + Phaser 世界 → 视觉打磨 + 小镇玩法 loop → 智能 ambient + speak 稳定 → 沉浸单人人生（记忆信任 + 世界回响）。 - -**EN — v5 direction:** Expand from 3 speakable NPCs to a 12-member AI council with world chronicle, multi-round debate/vote, full map presence, and per-NPC personal life timelines. - -**中文 — v5 方向：** 从 3 个可对话 NPC 扩展为 12 人 AI 议会：世界编年史、多轮辩论表决、全员上地图、个人人生时间线。 +**v5 direction:** Expand from 3 speakable NPCs to a 12-member AI council with world chronicle, multi-round debate/vote, full map presence, and per-NPC personal life timelines. --- @@ -52,24 +48,22 @@ --- -### Phase 01 — Foundation & Action Schema / 基础与 Action Schema +### Phase 01 — Foundation & Action Schema | | | |---|---| -| **Status** | ✅ Shipped / 已交付 | +| **Status** | ✅ Shipped | | **Completed** | 2026-06-03 | -**Goal / 目标** +**Goal** -- **EN:** Establish monorepo, cloud dev stack (Supabase + Upstash), and shared Zod action schema as the single contract for all LLM mutations. -- **中文：** 建立 monorepo、云 dev stack（Supabase + Upstash）、共享 Zod action schema 作为所有 LLM mutation 的唯一契约。 +- Establish monorepo, cloud dev stack (Supabase + Upstash), and shared Zod action schema as the single contract for all LLM mutations. -**Rationale / 思路** +**Rationale** -- **EN:** Cloud Postgres/Redis lowers onboarding vs local Docker; Zod schema shared by game-server and worker prevents drift. -- **中文：** 云 Postgres/Redis 降低上手成本；game-server 与 worker 共享 Zod schema 防止契约漂移。 +- Cloud Postgres/Redis lowers onboarding vs local Docker; Zod schema shared by game-server and worker prevents drift. -**Key deliverables / 关键交付** +**Key deliverables** - pnpm + Turborepo monorepo - `packages/game-actions` Zod + OpenAI tools @@ -77,133 +71,125 @@ - ai-gateway FastAPI `/health` - `.env.example` Supabase/Upstash template -**Verification / 验收:** `pnpm verify:cloud` · `pnpm turbo test` +**Verification:** `pnpm verify:cloud` · `pnpm turbo test` -**Tech decisions / 技术决策:** INFR-01 cloud dev stack; INFR-02 game-actions as sole mutation schema +**Tech decisions:** INFR-01 cloud dev stack; INFR-02 game-actions as sole mutation schema --- -### Phase 02 — Single NPC Text Loop / 单 NPC 文本闭环 +### Phase 02 — Single NPC Text Loop | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-04 | -**Goal / 目标** +**Goal** -- **EN:** One NPC completes the Generative Agent loop in pure text UI — validates core product value. -- **中文：** 单 NPC 在纯文本 UI 完成 Generative Agent 闭环，验证核心价值。 +- One NPC completes the Generative Agent loop in pure text UI — validates core product value. -**Rationale / 思路** +**Rationale** -- **EN:** LangGraph + BullMQ async worker; never block Colyseus on LLM; SSE drives thinking UX. -- **中文：** LangGraph + BullMQ 异步 worker；禁止 Colyseus 阻塞 LLM；SSE 驱动「思考中」反馈。 +- LangGraph + BullMQ async worker; never block Colyseus on LLM; SSE drives thinking UX. -**Key deliverables / 关键交付** +**Key deliverables** - game-server room routes + SSE - `workers/agent-worker` LangGraph `npc_loop.py` - apps/web chat UI - `scripts/verify-phase2.mjs` -**Verification / 验收:** `pnpm verify:phase2` · `cd workers/agent-worker && LLM_MOCK=1 uv run pytest -q` +**Verification:** `pnpm verify:phase2` · `cd workers/agent-worker && LLM_MOCK=1 uv run pytest -q` -**Tech decisions / 技术决策:** AGNT-01/03; INFR-03 LangSmith trace +**Tech decisions:** AGNT-01/03; INFR-03 LangSmith trace --- -### Phase 03 — Persistent Memory / 持久记忆 +### Phase 03 — Persistent Memory | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-03 | -**Goal / 目标** +**Goal** -- **EN:** NPC memory survives restart/session; vector retrieval injects context; summarization prevents bloat. -- **中文：** NPC 记忆跨 restart/session 保留；向量检索注入对话；摘要防膨胀。 +- NPC memory survives restart/session; vector retrieval injects context; summarization prevents bloat. -**Rationale / 思路** +**Rationale** -- **EN:** pgvector + `@aetherlife/npc-memory`; top-k embedding retrieval; bulk summarize at ≥100 rows. -- **中文：** pgvector + `@aetherlife/npc-memory`；top-k embedding 检索；≥100 条 bulk 摘要。 +- pgvector + `@aetherlife/npc-memory`; top-k embedding retrieval; bulk summarize at ≥100 rows. -**Key deliverables / 关键交付** +**Key deliverables** - `packages/npc-memory` schema + migrations - game-server MemoryService + internal API - worker reflect/bulk summarize - `scripts/verify-phase3.mjs` -**Verification / 验收:** `pnpm verify:phase3` · `pnpm verify:phase3 -- --seed-bulk=100` +**Verification:** `pnpm verify:phase3` · `pnpm verify:phase3 -- --seed-bulk=100` -**Tech decisions / 技术决策:** D-07 reset clears memory, keeps checkpoint; HNSW dropped for 2048-dim embed +**Tech decisions:** D-07 reset clears memory, keeps checkpoint; HNSW dropped for 2048-dim embed -**Known debt / 已知债务:** Dev embed latency p95 ~2–4s (production target <500ms not met at v0 close) +**Known debt:** Dev embed latency p95 ~2–4s (production target <500ms not met at v0 close) --- -### Phase 04 — Multi-NPC Text Room / 多 NPC 文本房间 +### Phase 04 — Multi-NPC Text Room | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-04 | -**Goal / 目标** +**Goal** -- **EN:** 1–3 NPCs in one room with independent threads; player switches dialogue target. -- **中文：** 1–3 NPC 同 room 独立 thread，玩家可切换对话对象。 +- 1–3 NPCs in one room with independent threads; player switches dialogue target. -**Rationale / 思路** +**Rationale** -- **EN:** Per-NPC LangGraph `thread_id`; NpcTabBar + memory panel for observability; `transfer` action between NPCs. -- **中文：** 每 NPC 独立 LangGraph thread；NpcTabBar + 记忆面板可观测；`transfer` action 支持 NPC 间转移。 +- Per-NPC LangGraph `thread_id`; NpcTabBar + memory panel for observability; `transfer` action between NPCs. -**Key deliverables / 关键交付** +**Key deliverables** - Multi-NPC room state - `transfer` action + executor - NpcMemoryPanel - `scripts/verify-phase4.mjs` -**Verification / 验收:** `pnpm verify:phase4` +**Verification:** `pnpm verify:phase4` -**Tech decisions / 技术决策:** AGNT-02/04 +**Tech decisions:** AGNT-02/04 --- -### Phase 05 — NL Gateway & Safety / NL 网关与安全 +### Phase 05 — NL Gateway & Safety | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-04 | -**Goal / 目标** +**Goal** -- **EN:** FastAPI unified NL ingress with Guardrails and thinking UX. -- **中文：** FastAPI 统一 NL 入口，Guardrails + thinking UX。 +- FastAPI unified NL ingress with Guardrails and thinking UX. -**Rationale / 思路** +**Rationale** -- **EN:** ai-gateway `/chat` + `/nl/parse` + ContentGuard; early thinking SSE; reply audit log. -- **中文：** ai-gateway `/chat` + `/nl/parse` + ContentGuard；early thinking SSE；reply audit。 +- ai-gateway `/chat` + `/nl/parse` + ContentGuard; early thinking SSE; reply audit log. -**Key deliverables / 关键交付** +**Key deliverables** - apps/ai-gateway chat/parse/guard - game-server thinking hooks - web `/v1` proxy - `scripts/verify-phase5.mjs` -**Verification / 验收:** `pnpm verify:phase5` · `cd apps/ai-gateway && uv run pytest tests -q` +**Verification:** `pnpm verify:phase5` · `cd apps/ai-gateway && uv run pytest tests -q` -**Tech decisions / 技术决策:** SAFE-01…03 +**Tech decisions:** SAFE-01…03 -**Known debt / 已知债务:** Direct gs `/chat` bypass, public audit-log, no rate limit — documented accepted risks in 05-SECURITY.md +**Known debt:** Direct gs `/chat` bypass, public audit-log, no rate limit — documented accepted risks in 05-SECURITY.md --- @@ -211,13 +197,11 @@ **Shipped:** 2026-06-07 · **Phases:** 06–08, 10, 10.5, 11, 11.6, 11.7, 12, 12.1 (Phase 09 deferred) -**EN — milestone rationale:** Extend v0 text loop into graphical multiplayer: Colyseus sync, Phaser renderer, procedural chunks, LLM lore, collective memory + worker social perception. - -**中文 — 里程碑思路：** 将 v0 文本闭环扩展为图形多人：Colyseus 同步、Phaser 渲染、程序化 chunk、LLM lore、集体记忆 + worker 社交感知。 +**milestone rationale:** Extend v0 text loop into graphical multiplayer: Colyseus sync, Phaser renderer, procedural chunks, LLM lore, collective memory + worker social perception. --- -### Phase 06 — Colyseus & Movement / Colyseus 与移动 +### Phase 06 — Colyseus & Movement | | | |---|---| @@ -225,213 +209,213 @@ | **Completed** | 2026-06-03 | | **Milestone** | v1 | -**Goal / 目标:** Authoritative game-server; player movement sync; foundation for graphics/multiplayer. +**Goal:** Authoritative game-server; player movement sync; foundation for graphics/multiplayer. -**Rationale / 思路:** Colyseus GameRoom server-authoritative move; 20Hz tick; speak → BullMQ async, never block room. +**Rationale:** Colyseus GameRoom server-authoritative move; 20Hz tick; speak → BullMQ async, never block room. **Key deliverables:** GameRoom.ts + schema.ts + move-handler.ts; useColyseusRoom + MovementPanel; useNpcChat speak/broadcast -**Verification / 验收:** `pnpm verify:phase6` · `pnpm uat:phase6:playwright` +**Verification:** `pnpm verify:phase6` · `pnpm uat:phase6:playwright` -**Tech decisions / 技术决策:** D-01 same port HTTP+WS; D-04 broadcast not SSE on web; D-20 WASD + click grid +**Tech decisions:** D-01 same port HTTP+WS; D-04 broadcast not SSE on web; D-20 WASD + click grid --- -### Phase 07 — 2.5D Renderer / 2.5D 渲染器 +### Phase 07 — 2.5D Renderer | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-04 | -**Goal / 目标:** Phaser 4 top-down 8×8 room; player + NPC sprites bound to Colyseus/REST; MovementPanel fallback. +**Goal:** Phaser 4 top-down 8×8 room; player + NPC sprites bound to Colyseus/REST; MovementPanel fallback. -**Rationale / 思路:** Phaser 4 RoomScene + React PhaserGame; probePhaserBoot + fallback path on WebGL failure. +**Rationale:** Phaser 4 RoomScene + React PhaserGame; probePhaserBoot + fallback path on WebGL failure. **Key deliverables:** RoomScene.ts + PhaserGame.tsx; gridLayout.ts + theme.ts; npcReply sanitize -**Verification / 验收:** `pnpm verify:phase7` · `pnpm uat:phase7:reset-snap` +**Verification:** `pnpm verify:phase7` · `pnpm uat:phase7:reset-snap` -**Related issues / 关联 ISSUE:** [ISSUE-002](../docs/ISSUE-LOG.md) (reset flushSync order) +**Related issues:** [ISSUE-002](../docs/ISSUE-LOG.md) (reset flushSync order) --- -### Phase 08 — Multiplayer Room / 多人房间 +### Phase 08 — Multiplayer Room | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-05 | -**Goal / 目标:** 4 players per room + async NPC AI patch without race conditions. +**Goal:** 4 players per room + async NPC AI patch without race conditions. -**Rationale / 思路:** maxClients=4 + clientSeq/moveAck prediction; speak queue + speakBusy per NPC; stateVersion monotonic AI patch. +**Rationale:** maxClients=4 + clientSeq/moveAck prediction; speak queue + speakBusy per NPC; stateVersion monotonic AI patch. **Key deliverables:** GameRoom speak queue + moveAck; applyStatePatch.ts; contentGuard speak blocklist -**Verification / 验收:** `pnpm verify:phase8` · `pnpm uat:phase8:playwright` · `pnpm verify:phase8:soak` +**Verification:** `pnpm verify:phase8` · `pnpm uat:phase8:playwright` · `pnpm verify:phase8:soak` -**Tech decisions / 技术决策:** SYNC-02…04; X-Player-Id / initiatorPlayerId foundation +**Tech decisions:** SYNC-02…04; X-Player-Id / initiatorPlayerId foundation -**Known debt / 已知债务:** E2E flaky under 智谱 concurrency=1 → fixed in Phase 12.2 ([ISSUE-032](../docs/ISSUE-LOG.md)) +**Known debt:** E2E flaky under 智谱 concurrency=1 → fixed in Phase 12.2 ([ISSUE-032](../docs/ISSUE-LOG.md)) --- -### Phase 09 — Voice Pipeline / 语音管线 +### Phase 09 — Voice Pipeline | | | |---|---| -| **Status** | ⏸ Deferred / 暂缓 | +| **Status** | ⏸ Deferred | | **Decision date** | 2026-06-05 | -**Goal / 目标:** STT/TTS immersive voice (PTT → speak path → TTS for initiator only). +**Goal:** STT/TTS immersive voice (PTT → speak path → TTS for initiator only). -**Rationale / 思路:** Planning complete (CONTEXT/UI-SPEC/4-wave PLAN) but not executed; prioritized world/multiplayer slices; voice needs GPU hosting or paid API cost. +**Rationale:** Planning complete (CONTEXT/UI-SPEC/4-wave PLAN) but not executed; prioritized world/multiplayer slices; voice needs GPU hosting or paid API cost. **Key deliverables (planned only):** 09-CONTEXT.md + 09-UI-SPEC.md; 09-01…04-PLAN.md — **no apps/ voice code** -**Verification / 验收:** — (not implemented) +**Verification:** — (not implemented) -**Tech decisions / 技术决策:** D-02 PTT + Colyseus speak primary path; self-hosted Speaches/Kokoro preferred architecture +**Tech decisions:** D-02 PTT + Colyseus speak primary path; self-hosted Speaches/Kokoro preferred architecture -**Known debt / 已知债务:** VOICE-01/02 fully deferred; resume conditions documented in phase 09 status +**Known debt:** VOICE-01/02 fully deferred; resume conditions documented in phase 09 status --- -### Phase 10 — Chunk Terrain / Chunk 地形 +### Phase 10 — Chunk Terrain | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-05 | -**Goal / 目标:** Seed-driven chunk load/unload + DB delta persistence. +**Goal:** Seed-driven chunk load/unload + DB delta persistence. -**Rationale / 思路:** ChunkLoader 3×3 window + LRU; door delta persist on re-enter; Colyseus global coords + chunksSync. +**Rationale:** ChunkLoader 3×3 window + LRU; door delta persist on re-enter; Colyseus global coords + chunksSync. **Key deliverables:** chunk-loader.ts; world_chunk_deltas migration; `scripts/verify-phase10.mjs` -**Verification / 验收:** `pnpm verify:phase10` · `pnpm uat:phase10:playwright` +**Verification:** `pnpm verify:phase10` · `pnpm uat:phase10:playwright` -**Tech decisions / 技术决策:** WORLD-01; WORLD-03 +**Tech decisions:** WORLD-01; WORLD-03 -**Known debt / 已知债务:** LLM lore → Phase 11; tile sprite atlas → art pass (Phase 13) +**Known debt:** LLM lore → Phase 11; tile sprite atlas → art pass (Phase 13) --- -### Phase 10.5 — Phaser Movement Sync / Phaser 移动同步 +### Phase 10.5 — Phaser Movement Sync | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-05 | -**Goal / 目标:** Phaser-first movement orchestration; RoomScene owns input→sync; eliminate React onMove vs explore tick races. +**Goal:** Phaser-first movement orchestration; RoomScene owns input→sync; eliminate React onMove vs explore tick races. -**Rationale / 思路:** RoomScene.setupInput → movementSync; remove useColyseusRoom setInterval explore tick; MP-MOV-02 shouldSuppressLocalSchemaSnap gate. +**Rationale:** RoomScene.setupInput → movementSync; remove useColyseusRoom setInterval explore tick; MP-MOV-02 shouldSuppressLocalSchemaSnap gate. **Key deliverables:** docs/MOVEMENT-ARCHITECTURE.md; localPlayerSchemaSnap.ts; verify-phase6 move-only gate -**Verification / 验收:** `pnpm verify:phase6:move-only` · `pnpm --filter @aetherlife/shared test` +**Verification:** `pnpm verify:phase6:move-only` · `pnpm --filter @aetherlife/shared test` -**Tech decisions / 技术决策:** Phaser-first movement; registry changedata explore coords +**Tech decisions:** Phaser-first movement; registry changedata explore coords --- -### Phase 11 — LLM World Lore / LLM 世界 Lore +### Phase 11 — LLM World Lore | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-06 | -**Goal / 目标:** Async LLM metadata on first chunk enter; persisted cache. +**Goal:** Async LLM metadata on first chunk enter; persisted cache. -**Rationale / 思路:** lore-orchestrator + lore_loop.py async job; Postgres chunk_lore cache hit skips repeat LLM; ExploreStrip + lore toast. +**Rationale:** lore-orchestrator + lore_loop.py async job; Postgres chunk_lore cache hit skips repeat LLM; ExploreStrip + lore toast. **Key deliverables:** lore-orchestrator.ts; lore_loop.py; ExploreStrip + toast -**Verification / 验收:** `pnpm verify:phase11` · `pnpm uat:phase11:playwright` +**Verification:** `pnpm verify:phase11` · `pnpm uat:phase11:playwright` -**Tech decisions / 技术决策:** WORLD-02; dedup poll in verify script +**Tech decisions:** WORLD-02; dedup poll in verify script --- -### Phase 11.6 — Zhipu GLM-4.7-Flash / 智谱主路径 +### Phase 11.6 — Zhipu GLM-4.7-Flash | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-07 | -**Goal / 目标:** 智谱 glm-4.7-flash as NPC primary path + lore text fallback; factory zhipu provider. +**Goal:** 智谱 glm-4.7-flash as NPC primary path + lore text fallback; factory zhipu provider. -**Rationale / 思路:** factory provider=zhipu + thinking disabled; NPC failure fallback OpenRouter; verify:llm-models probes zhipu. +**Rationale:** factory provider=zhipu + thinking disabled; NPC failure fallback OpenRouter; verify:llm-models probes zhipu. **Key deliverables:** workers/agent-worker llm/factory.py; npc_loop zhipu default; scripts/verify-llm-models.mjs -**Verification / 验收:** `pnpm verify:llm-models` · worker pytest +**Verification:** `pnpm verify:llm-models` · worker pytest -**Tech decisions / 技术决策:** 智谱 account concurrency = 1 constraint +**Tech decisions:** 智谱 account concurrency = 1 constraint -**Related issues / 关联 ISSUE:** [ISSUE-032](../docs/ISSUE-LOG.md) root cause (zhipu concurrency) +**Related issues:** [ISSUE-032](../docs/ISSUE-LOG.md) root cause (zhipu concurrency) --- -### Phase 11.7 — LLM Role Routing / LLM 角色路由 +### Phase 11.7 — LLM Role Routing | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-07 | -**Goal / 目标:** Six-platform role-based LLM routing; 智谱 slot reserved for NPC tool-calling only. +**Goal:** Six-platform role-based LLM routing; 智谱 slot reserved for NPC tool-calling only. -**Rationale / 思路:** Social/Summarize/Collective → SiliconFlow Qwen3.5-4B; Importance → NVIDIA nano; Lore fallback → NVIDIA; NPC fallback → OpenRouter. +**Rationale:** Social/Summarize/Collective → SiliconFlow Qwen3.5-4B; Importance → NVIDIA nano; Lore fallback → NVIDIA; NPC fallback → OpenRouter. **Key deliverables:** docs/LLM-ROUTING.md; config.py role routing; .env.example six-platform blocks -**Verification / 验收:** `pnpm verify:llm-models` · `pnpm agent:verify` · worker pytest +**Verification:** `pnpm verify:llm-models` · `pnpm agent:verify` · worker pytest -**Related issues / 关联 ISSUE:** [ISSUE-031](../docs/ISSUE-LOG.md), [ISSUE-032](../docs/ISSUE-LOG.md), [ISSUE-033](../docs/ISSUE-LOG.md) +**Related issues:** [ISSUE-031](../docs/ISSUE-LOG.md), [ISSUE-032](../docs/ISSUE-LOG.md), [ISSUE-033](../docs/ISSUE-LOG.md) --- -### Phase 12 — Collective Memory / 集体记忆 +### Phase 12 — Collective Memory | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-07 | -**Goal / 目标:** Multi-player behavior toward NPCs writes shared collective memory; attitude observable. +**Goal:** Multi-player behavior toward NPCs writes shared collective memory; attitude observable. -**Rationale / 思路:** collective tables + dual speak events; AttitudeBandChip + hostile gate 403; worker tool_gate + memory tail. +**Rationale:** collective tables + dual speak events; AttitudeBandChip + hostile gate 403; worker tool_gate + memory tail. **Key deliverables:** packages/npc-memory collective tables; apps/game-server/src/collective/*; AttitudeBandChip -**Verification / 验收:** `VERIFY_PHASE12_FAST=1 pnpm verify:phase12` +**Verification:** `VERIFY_PHASE12_FAST=1 pnpm verify:phase12` -**Tech decisions / 技术决策:** SOCL-01/02 +**Tech decisions:** SOCL-01/02 --- -### Phase 12.1 — LLM Social Perception / LLM 社交感知 +### Phase 12.1 — LLM Social Perception | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-07 | -**Goal / 目标:** Worker structured social perception + reply; server no longer dual-writes speak wordlists. +**Goal:** Worker structured social perception + reply; server no longer dual-writes speak wordlists. -**Rationale / 思路:** SocialTurnOut → apply event → refresh band; score_social_perception structured turn; server action rules only for collective writes. +**Rationale:** SocialTurnOut → apply event → refresh band; score_social_perception structured turn; server action rules only for collective writes. **Key deliverables:** worker social perception graph; uat-phase12.1-playwright.mjs; ISSUE-LOG Guardrails 59–60 -**Verification / 验收:** `pnpm uat:phase12.1:playwright` · `VERIFY_PHASE12_FAST=1 pnpm verify:phase12` +**Verification:** `pnpm uat:phase12.1:playwright` · `VERIFY_PHASE12_FAST=1 pnpm verify:phase12` -**Tech decisions / 技术决策:** Option B — worker-only social LLM +**Tech decisions:** Option B — worker-only social LLM --- @@ -439,161 +423,159 @@ **Shipped:** 2026-06-09 · **Phases:** 12.2, 13, 13.1, 13.2, 13.3, 14, 14.1, 15 -**EN — milestone rationale:** Path 1 core loop — explore chunk → lore → NL → collective → cross-session memory; Phaser visuals shareable; speak reliability for daily play. - -**中文 — 里程碑思路：** 路径 1 核心 loop：探索 chunk → lore → NL → 集体态度 → 跨 session 记忆；Phaser 视觉可传播；speak 稳定可日常玩。 +**milestone rationale:** Path 1 core loop — explore chunk → lore → NL → collective → cross-session memory; Phaser visuals shareable; speak reliability for daily play. --- -### Phase 12.2 — Speak Reliability / Speak 可靠性 +### Phase 12.2 — Speak Reliability | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-07 | -**Goal / 目标:** Eliminate 智谱 single-slot speak/E2E flakiness; multiplayer NL playable daily. +**Goal:** Eliminate 智谱 single-slot speak/E2E flakiness; multiplayer NL playable daily. -**Rationale / 思路:** NPC main dialogue → SiliconFlow Qwen3.5-4B; per-NPC serial + cross-NPC parallel; worker BRPOP FIFO + speakBusy no silent drop. +**Rationale:** NPC main dialogue → SiliconFlow Qwen3.5-4B; per-NPC serial + cross-NPC parallel; worker BRPOP FIFO + speakBusy no silent drop. **Key deliverables:** llm_social_turn.py social degrade; main.py BRPOP + async memory tail; structured LLM call log -**Verification / 验收:** `pnpm agent:verify --e2e` · `pnpm verify:phase8` · `pnpm verify:llm-models` +**Verification:** `pnpm agent:verify --e2e` · `pnpm verify:phase8` · `pnpm verify:llm-models` -**Tech decisions / 技术决策:** STAB-02 — three consecutive E2E passes as sole ship gate +**Tech decisions:** STAB-02 — three consecutive E2E passes as sole ship gate -**Related issues / 关联 ISSUE:** [ISSUE-032](../docs/ISSUE-LOG.md) fixed; [ISSUE-022](../docs/ISSUE-LOG.md) guardrail (memory in worker tail only) +**Related issues:** [ISSUE-032](../docs/ISSUE-LOG.md) fixed; [ISSUE-022](../docs/ISSUE-LOG.md) guardrail (memory in worker tail only) --- -### Phase 13 — Phaser World Visuals / Phaser 世界视觉 +### Phase 13 — Phaser World Visuals | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-08 | -**Goal / 目标:** First screen upgrade from prototype discs to shareable Stardew-style tile + sprite + decor world. +**Goal:** First screen upgrade from prototype discs to shareable Stardew-style tile + sprite + decor world. -**Rationale / 思路:** Tilemap replaces drawFloor; 4-dir walk/idle anim; Y-sort + proximity nameplate (VIS-04); area lazy preload + visualFallback. +**Rationale:** Tilemap replaces drawFloor; 4-dir walk/idle anim; Y-sort + proximity nameplate (VIS-04); area lazy preload + visualFallback. **Key deliverables:** FloorRenderer + DecorRenderer; entitySprites + animations; ProximityNameplate -**Verification / 验收:** `pnpm verify:phase13` · `pnpm uat:phase13:playwright` · `pnpm verify:phase6:move-only` +**Verification:** `pnpm verify:phase13` · `pnpm uat:phase13:playwright` · `pnpm verify:phase6:move-only` -**Tech decisions / 技术决策:** 16×16 pixel tile pastoral; D-22 boot >5s warn / >8s fail +**Tech decisions:** 16×16 pixel tile pastoral; D-22 boot >5s warn / >8s fail -**Related issues / 关联 ISSUE:** [ISSUE-035](../docs/ISSUE-LOG.md), [ISSUE-036](../docs/ISSUE-LOG.md), [ISSUE-038](../docs/ISSUE-LOG.md) +**Related issues:** [ISSUE-035](../docs/ISSUE-LOG.md), [ISSUE-036](../docs/ISSUE-LOG.md), [ISSUE-038](../docs/ISSUE-LOG.md) --- -### Phase 13.1 — Phaser World Art Pass / 美术资源替换 +### Phase 13.1 — Phaser World Art Pass | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-08 | -**Goal / 目标:** Replace placeholder art with CC0/LPC real pixel assets; aesthetic rubric AE-01…08. +**Goal:** Replace placeholder art with CC0/LPC real pixel assets; aesthetic rubric AE-01…08. **Key deliverables:** Kenney Tiny Town + Universal LPC import; pnpm art:import; CREDITS.md -**Verification / 验收:** `pnpm verify:phase13` · `pnpm uat:phase13:playwright` +**Verification:** `pnpm verify:phase13` · `pnpm uat:phase13:playwright` -**Tech decisions / 技术决策:** TILE_PX=16, FRAMES_PER_FACING=6 contract +**Tech decisions:** TILE_PX=16, FRAMES_PER_FACING=6 contract --- -### Phase 13.2 — Farm Art Pass / 农场美术 +### Phase 13.2 — Farm Art Pass | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-08 | -**Goal / 目标:** Tiny Town 地球Online-style tiles replace Roguelike; life-sim aesthetic AE-08. +**Goal:** Tiny Town 地球Online-style tiles replace Roguelike; life-sim aesthetic AE-08. **Key deliverables:** pastoralTint.ts; pnpm art:import:farm; home-farm.png canonical screenshot -**Verification / 验收:** `pnpm verify:phase13` · `pnpm uat:phase13:playwright` +**Verification:** `pnpm verify:phase13` · `pnpm uat:phase13:playwright` -**Related issues / 关联 ISSUE:** [ISSUE-039](../docs/ISSUE-LOG.md) (decor Y-sort) +**Related issues:** [ISSUE-039](../docs/ISSUE-LOG.md) (decor Y-sort) --- -### Phase 13.3 — Stardew Scale Calibration / 星露谷比例校准 +### Phase 13.3 — Stardew Scale Calibration | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-08 | -**Goal / 目标:** CELL_PX=48 integer scale + 16×32 character frames + Asset Bible. +**Goal:** CELL_PX=48 integer scale + 16×32 character frames + Asset Bible. -**Rationale / 思路:** 16px source × 3 = 48px on-screen cell; LPC bbox crop bottom-align; logical 8×8 chunk map unchanged. +**Rationale:** 16px source × 3 = 48px on-screen cell; LPC bbox crop bottom-align; logical 8×8 chunk map unchanged. -**Verification / 验收:** `pnpm verify:phase13` · `pnpm uat:phase13:playwright` · `pnpm agent:verify` +**Verification:** `pnpm verify:phase13` · `pnpm uat:phase13:playwright` · `pnpm agent:verify` -**Tech decisions / 技术决策:** Colyseus coords remain integer grid cells; viewport 576×576 +**Tech decisions:** Colyseus coords remain integer grid cells; viewport 576×576 --- -### Phase 14 — Living NPCs / 有生命的 NPC +### Phase 14 — Living NPCs | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-08 | -**Goal / 目标:** Observable NPC life when player is not speaking — schedule + activity sync. +**Goal:** Observable NPC life when player is not speaking — schedule + activity sync. -**Rationale / 思路:** game-server 6s ambient tick (no LLM in tick); accelerated game-day clock + ExploreCoordsStrip HUD; proximity activity sub-labels. +**Rationale:** game-server 6s ambient tick (no LLM in tick); accelerated game-day clock + ExploreCoordsStrip HUD; proximity activity sub-labels. **Key deliverables:** ambient engine + schedule JSON; Colyseus activity + gameTime schema; Phaser activity labels -**Verification / 验收:** `pnpm verify:phase14` · `pnpm --filter @aetherlife/game-server test` +**Verification:** `pnpm verify:phase14` · `pnpm --filter @aetherlife/game-server test` -**Tech decisions / 技术决策:** 1 real minute = 10 game minutes; speak/thinking pauses single NPC ambient +**Tech decisions:** 1 real minute = 10 game minutes; speak/thinking pauses single NPC ambient -**Known debt / 已知债务:** Low-frequency lore/reflect enrichment → Phase 16 +**Known debt:** Low-frequency lore/reflect enrichment → Phase 16 --- -### Phase 14.1 — Blocked Move Facing / 被挡朝向 +### Phase 14.1 — Blocked Move Facing | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-08 | -**Goal / 目标:** WASD blocked still updates local idle facing; optional multiplayer facing sync. +**Goal:** WASD blocked still updates local idle facing; optional multiplayer facing sync. **Key deliverables:** clientMovementPredictor onBlockedFace; move-handler facing-on-block; MP-MOV-05 in MOVEMENT-ARCHITECTURE.md -**Verification / 验收:** `pnpm agent:verify` · `pnpm --filter @aetherlife/web test` · `pnpm verify:phase6:move-only` +**Verification:** `pnpm agent:verify` · `pnpm --filter @aetherlife/web test` · `pnpm verify:phase6:move-only` -**Tech decisions / 技术决策:** C-04 blocked-facing CONTRACTS row +**Tech decisions:** C-04 blocked-facing CONTRACTS row -**Related issues / 关联 ISSUE:** [ISSUE-040](../docs/ISSUE-LOG.md) +**Related issues:** [ISSUE-040](../docs/ISSUE-LOG.md) --- -### Phase 15 — Town Play Loop / 小镇玩法 Loop +### Phase 15 — Town Play Loop | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-09 | -**Goal / 目标:** Path 1 UAT-ready loop: explore → lore → NL → collective attitude → cross-session memory. +**Goal:** Path 1 UAT-ready loop: explore → lore → NL → collective attitude → cross-session memory. **Key deliverables:** JournalQuestStrip; CollectiveBrowsePanel + resolveCollectiveInitiatorPlayerId; ColyseusNpcJobDonePayload.memoryQuote -**Verification / 验收:** `pnpm verify:phase15` · `pnpm uat:phase15:playwright` · `pnpm verify:phase13` +**Verification:** `pnpm verify:phase15` · `pnpm uat:phase15:playwright` · `pnpm verify:phase13` -**Tech decisions / 技术决策:** initiator from playerIds, never text inference; memory write in worker tail only +**Tech decisions:** initiator from playerIds, never text inference; memory write in worker tail only -**Related issues / 关联 ISSUE:** [ISSUE-022](../docs/ISSUE-LOG.md) +**Related issues:** [ISSUE-022](../docs/ISSUE-LOG.md) --- @@ -601,72 +583,70 @@ **Shipped:** 2026-06-11 · **Phases:** 16, 17, 17.1 (+ Phase 18 v3.1 maintenance 2026-06-12) -**EN — milestone rationale:** Zone/intent-driven NPC wander on Tiled walkability; async LLM intent planner; speak pre-LLM cache hardening with real-LLM golden E2E. - -**中文 — 里程碑思路：** Tiled 可行走世界上的 zone/意图驱动漫游；异步 LLM intent；speak 热路径缓存加固 + 真实 LLM golden E2E。 +**milestone rationale:** Zone/intent-driven NPC wander on Tiled walkability; async LLM intent planner; speak pre-LLM cache hardening with real-LLM golden E2E. --- -### Phase 16 — Intelligent Ambient NPCs / 智能 Ambient NPC +### Phase 16 — Intelligent Ambient NPCs | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-11 | -**Goal / 目标:** Scalable Tiled world with zone/intent-driven NPC wander; async LLM intent planner. +**Goal:** Scalable Tiled world with zone/intent-driven NPC wander; async LLM intent planner. -**Rationale / 思路:** WorldRegion registry + zone wander replaces waypoint ring; async intent job (schedule segment change + speak_end trigger); village-plaza@v1 cross-region + background NPC tier. +**Rationale:** WorldRegion registry + zone wander replaces waypoint ring; async intent job (schedule segment change + speak_end trigger); village-plaza@v1 cross-region + background NPC tier. **Key deliverables:** WorldRegion + zones/pois/spawns; npc-ambient-intent BullMQ job; Tiled collision walkability -**Verification / 验收:** `pnpm verify:phase16` · `pnpm agent:verify` · game-server test +**Verification:** `pnpm verify:phase16` · `pnpm agent:verify` · game-server test -**Tech decisions / 技术决策:** 6s tick ≤1 cell; no blocking LLM in tick; intent third-line UI abolished +**Tech decisions:** 6s tick ≤1 cell; no blocking LLM in tick; intent third-line UI abolished -**Known debt / 已知债务:** COZY-01 Metlivi economy deferred +**Known debt:** COZY-01 Metlivi economy deferred -**Related issues / 关联 ISSUE:** [ISSUE-043](../docs/ISSUE-LOG.md) +**Related issues:** [ISSUE-043](../docs/ISSUE-LOG.md) --- -### Phase 17 — Speak Pre-LLM SLA / Speak 热路径 SLA +### Phase 17 — Speak Pre-LLM SLA | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-11 | -**Goal / 目标:** worker-state / memory-context cache + internal latency observability; shorten speak hot path. +**Goal:** worker-state / memory-context cache + internal latency observability; shorten speak hot path. -**Rationale / 思路:** skipNearbyLore default on speak hot path; memoryContextCache bounded TTL; stale snapshot fallback, no hard-fail. +**Rationale:** skipNearbyLore default on speak hot path; memoryContextCache bounded TTL; stale snapshot fallback, no hard-fail. **Key deliverables:** memoryContextCache.ts; skipNearbyLore default; internal-latency logs -**Verification / 验收:** `pnpm agent:verify` · `pnpm agent:verify --e2e --base` · game-server test +**Verification:** `pnpm agent:verify` · `pnpm agent:verify --e2e --base` · game-server test -**Tech decisions / 技术决策:** Infra SLA here; user-perceived SLA defined in v4 Phase 20 +**Tech decisions:** Infra SLA here; user-perceived SLA defined in v4 Phase 20 --- -### Phase 17.1 — Speak Cache Hardening / Speak 缓存加固 +### Phase 17.1 — Speak Cache Hardening | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-11 | -**Goal / 目标:** Post-Phase-17 cache identity, invalidation, bounds, lore stampede hardening. +**Goal:** Post-Phase-17 cache identity, invalidation, bounds, lore stampede hardening. **Key deliverables:** internal-memories identity fix; memoryContextCache bounds; bridge.test.ts reset snap -**Verification / 验收:** `pnpm agent:verify --e2e --base` +**Verification:** `pnpm agent:verify --e2e --base` -**Tech decisions / 技术决策:** Align C-01 internal player id +**Tech decisions:** Align C-01 internal player id --- -### Phase 18 — Code Health Refactor / 代码健康重构 +### Phase 18 — Code Health Refactor | | | |---|---| @@ -674,19 +654,19 @@ | **Completed** | 2026-06-12 | | **Milestone** | v3.1 | -**Goal / 目标:** Reduce maintenance cost without behavior change — verify DRY + RoomScene/useNpcChat split. +**Goal:** Reduce maintenance cost without behavior change — verify DRY + RoomScene/useNpcChat split. -**Rationale / 思路:** All verify-phase*.mjs → scripts/lib/env.mjs; useNpcChat pure functions → hooks/npcChat/; RoomScene split by camera/floor/input/sync/motion. +**Rationale:** All verify-phase*.mjs → scripts/lib/env.mjs; useNpcChat pure functions → hooks/npcChat/; RoomScene split by camera/floor/input/sync/motion. **Key deliverables:** scripts/lib/env.mjs; roomSceneSync.ts + submodules; hooks/npcChat/* -**Verification / 验收:** `pnpm agent:verify` · `pnpm agent:verify --e2e --base` · `pnpm verify:phase13` · `pnpm verify:phase8` +**Verification:** `pnpm agent:verify` · `pnpm agent:verify --e2e --base` · `pnpm verify:phase13` · `pnpm verify:phase8` -**Tech decisions / 技术决策:** Frozen UX files untouched (ISSUE-037/038); RoomScene.ts ~1086 LOC post-split +**Tech decisions:** Frozen UX files untouched (ISSUE-037/038); RoomScene.ts ~1086 LOC post-split -**Known debt / 已知债务:** ISSUE-049 multiplayer reset; worker npc_loop.py split deferred +**Known debt:** ISSUE-049 multiplayer reset; worker npc_loop.py split deferred -**Related issues / 关联 ISSUE:** [ISSUE-037](../docs/ISSUE-LOG.md), [ISSUE-038](../docs/ISSUE-LOG.md), [ISSUE-049](../docs/ISSUE-LOG.md) +**Related issues:** [ISSUE-037](../docs/ISSUE-LOG.md), [ISSUE-038](../docs/ISSUE-LOG.md), [ISSUE-049](../docs/ISSUE-LOG.md) --- @@ -694,89 +674,87 @@ **Shipped:** 2026-06-22 · **Phases:** 19–22 · **Tag:** v4 -**EN — milestone rationale:** Full-viewport immersive shell; cross-session memory recall in speech; world echo without quest strip; solo life ship gate with real-LLM C1–C5 rubric. - -**中文 — 里程碑思路：** 全屏沉浸壳；跨 session 记忆口播；无任务条的世界回响；单人真实 LLM C1–C5 rubric ship gate。 +**milestone rationale:** Full-viewport immersive shell; cross-session memory recall in speech; world echo without quest strip; solo life ship gate with real-LLM C1–C5 rubric. --- -### Phase 19 — Immersive UI Shell / 沉浸 UI 壳 +### Phase 19 — Immersive UI Shell | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-13 | -**Goal / 目标:** Full-screen immersive UI — Phaser fill + DialogueBar + ShellDrawer; remove NpcTabBar. +**Goal:** Full-screen immersive UI — Phaser fill + DialogueBar + ShellDrawer; remove NpcTabBar. -**Rationale / 思路:** 100dvh shell + Stardew wood-frame HUD; map click + NpcAvatarStrip replaces TabBar; drawer for history/collective. +**Rationale:** 100dvh shell + Stardew wood-frame HUD; map click + NpcAvatarStrip replaces TabBar; drawer for history/collective. **Key deliverables:** ImmersiveShell + DialogueBar + ShellDrawer; CornerMenu + NpcAvatarStrip; Phaser NPC hit-test -**Verification / 验收:** `pnpm verify:phase19` · `pnpm verify:phase13` · `pnpm uat:phase8` +**Verification:** `pnpm verify:phase19` · `pnpm verify:phase13` · `pnpm uat:phase8` -**Tech decisions / 技术决策:** useNpcChat speakBusy unchanged (Frozen ISSUE-037); JournalQuestStrip retained until Phase 21 +**Tech decisions:** useNpcChat speakBusy unchanged (Frozen ISSUE-037); JournalQuestStrip retained until Phase 21 -**Related issues / 关联 ISSUE:** [ISSUE-037](../docs/ISSUE-LOG.md), [ISSUE-038](../docs/ISSUE-LOG.md), [ISSUE-041](../docs/ISSUE-LOG.md), [ISSUE-011](../docs/ISSUE-LOG.md) +**Related issues:** [ISSUE-037](../docs/ISSUE-LOG.md), [ISSUE-038](../docs/ISSUE-LOG.md), [ISSUE-041](../docs/ISSUE-LOG.md), [ISSUE-011](../docs/ISSUE-LOG.md) --- -### Phase 20 — Memory & Speak Trust / 记忆与 Speak 信任 +### Phase 20 — Memory & Speak Trust | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-16 | -**Goal / 目标:** Solo trust floor — cross-session memory in speech + user-perceived Speak SLA Tier-1 (not Phase 17 ms tables). +**Goal:** Solo trust floor — cross-session memory in speech + user-perceived Speak SLA Tier-1 (not Phase 17 ms tables). -**Rationale / 思路:** recall_merge cross-session password/nickname; engageDialogue overlay-first measures T_think/T_first; SOLO-05 Tier-1 ship gates separate from Tier-2 audit. +**Rationale:** recall_merge cross-session password/nickname; engageDialogue overlay-first measures T_think/T_first; SOLO-05 Tier-1 ship gates separate from Tier-2 audit. **Key deliverables:** recall_merge.py + memory_quote; benchmark-speak-browser.mjs; SPEAK-SLA scorecard -**Verification / 验收:** `pnpm verify:phase20` · `pnpm agent:verify` +**Verification:** `pnpm verify:phase20` · `pnpm agent:verify` -**Tech decisions / 技术决策:** D-12 charter — Tier-1 verify+UAT ships; Tier-2 p95 audit only; assert-refusal-markers-parity JS↔Python +**Tech decisions:** D-12 charter — Tier-1 verify+UAT ships; Tier-2 p95 audit only; assert-refusal-markers-parity JS↔Python -**Related issues / 关联 ISSUE:** [ISSUE-041](../docs/ISSUE-LOG.md), [ISSUE-050](../docs/ISSUE-LOG.md) +**Related issues:** [ISSUE-041](../docs/ISSUE-LOG.md), [ISSUE-050](../docs/ISSUE-LOG.md) --- -### Phase 21 — World Echo / 世界回响 +### Phase 21 — World Echo | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-21 | -**Goal / 目标:** Life-sim feel without quests — NL world traces; remove JournalQuestStrip; lore toast +「已发现」drawer. +**Goal:** Life-sim feel without quests — NL world traces; remove JournalQuestStrip; lore toast +「已发现」drawer. **Key deliverables:** Remove JournalQuestStrip; LoreDiscoverToast; DiscoveredLorePanel drawer tab; 21-QUEST-LANGUAGE-AUDIT.md -**Verification / 验收:** `pnpm verify:phase21` · `pnpm uat:phase21:playwright` · `pnpm verify:phase13` +**Verification:** `pnpm verify:phase21` · `pnpm uat:phase21:playwright` · `pnpm verify:phase13` -**Tech decisions / 技术决策:** Non-quest copy gate; ISSUE-013 pending→ready toast split +**Tech decisions:** Non-quest copy gate; ISSUE-013 pending→ready toast split -**Related issues / 关联 ISSUE:** [ISSUE-013](../docs/ISSUE-LOG.md) +**Related issues:** [ISSUE-013](../docs/ISSUE-LOG.md) --- -### Phase 22 — Solo Life Gate / 单人人生门禁 +### Phase 22 — Solo Life Gate | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-22 | -**Goal / 目标:** v4 ship gate — solo real-LLM C1–C5 rubric + SOLO-04/06 aggregate verification. +**Goal:** v4 ship gate — solo real-LLM C1–C5 rubric + SOLO-04/06 aggregate verification. -**Rationale / 思路:** pnpm verify:phase22 aggregates phase20+21+inline+golden; Collective rude auto-opens drawer + help no double-open (SOLO-04); Human UAT 10/10. +**Rationale:** pnpm verify:phase22 aggregates phase20+21+inline+golden; Collective rude auto-opens drawer + help no double-open (SOLO-04); Human UAT 10/10. **Key deliverables:** scripts/verify-phase22.mjs aggregator; 22-UAT-MATRIX.md; v4 milestone closure -**Verification / 验收:** `pnpm verify:phase22` · `pnpm agent:verify` · `pnpm agent:verify --e2e` +**Verification:** `pnpm verify:phase22` · `pnpm agent:verify` · `pnpm agent:verify --e2e` -**Tech decisions / 技术决策:** WORLD_SEED=42 golden spawns; 5-step aggregator ~22min real LLM +**Tech decisions:** WORLD_SEED=42 golden spawns; 5-step aggregator ~22min real LLM --- @@ -784,114 +762,112 @@ **Started:** 2026-06-25 (Phase 23) · **Phases:** 23–27 · **Status:** Phase 23 ✅; 24–27 📋 Planned -**EN — milestone rationale:** Upgrade NPCs from 3 speakable characters to a 12-member AI council with world chronicle, multi-round debate/vote, full map presence, and per-NPC subjective life timelines parallel to objective world history. - -**中文 — 里程碑思路：** 将 NPC 从 3 个可对话角色升级为 12 人 AI 议会：世界编年史、多轮辩论表决、全员上地图、与世界历史双轨的个人主观传记时间线。 +**milestone rationale:** Upgrade NPCs from 3 speakable characters to a 12-member AI council with world chronicle, multi-round debate/vote, full map presence, and per-NPC subjective life timelines parallel to objective world history. --- -### Phase 23 — Council Persona Foundation / 议会人格基础 +### Phase 23 — Council Persona Foundation | | | |---|---| | **Status** | ✅ Shipped | | **Completed** | 2026-06-25 | -**Goal / 目标:** 12 council NPCs single source of truth registry + `__council__` memory scope; persona data layer for vote/map expansion. +**Goal:** 12 council NPCs single source of truth registry + `__council__` memory scope; persona data layer for vote/map expansion. -**Rationale / 思路:** COUNCIL_PERSONAS SSOT + 12 dossiers; worker speak persona injection (npc-1..3); pgvector `__council__` isolated from player speak memory. +**Rationale:** COUNCIL_PERSONAS SSOT + 12 dossiers; worker speak persona injection (npc-1..3); pgvector `__council__` isolated from player speak memory. **Key deliverables:** packages/shared/src/council/* + npcPersonas.ts; councilSeed.ts + C-07 CONTRACTS; CouncilRosterPanel drawer tab「星际议会」; 12 schedule JSON + personality seeds -**Verification / 验收:** `pnpm agent:verify` · game-server test · worker pytest +**Verification:** `pnpm agent:verify` · game-server test · worker pytest -**Tech decisions / 技术决策:** SPEAKABLE_NPC_IDS = npc-1..3 only; voting 4/3/5 against/for/swing split +**Tech decisions:** SPEAKABLE_NPC_IDS = npc-1..3 only; voting 4/3/5 against/for/swing split -**Known debt / 已知债务:** PERSONA-04 vote-time LTM E2E → Phase 25; PERSONA-02 live speak voice differentiation → human UAT +**Known debt:** PERSONA-04 vote-time LTM E2E → Phase 25; PERSONA-02 live speak voice differentiation → human UAT -**Related issues / 关联 ISSUE:** [ISSUE-001](../docs/ISSUE-LOG.md), [ISSUE-022](../docs/ISSUE-LOG.md) +**Related issues:** [ISSUE-001](../docs/ISSUE-LOG.md), [ISSUE-022](../docs/ISSUE-LOG.md) --- -### Phase 24 — World History Chronicle / 世界历史编年史 +### Phase 24 — World History Chronicle | | | |---|---| -| **Status** | 📋 Planned / 规划中 | +| **Status** | 📋 Planned | -**Goal / 目标:** World history chronicle persistence + player-readable drawer panel; vote provenance and rejected-proposal history. +**Goal:** World history chronicle persistence + player-readable drawer panel; vote provenance and rejected-proposal history. -**Rationale / 思路:** world_history append-only migration; GET /rooms/:id/world-history + worker writeback; Colyseus worldHistorySync + WorldHistoryPanel. +**Rationale:** world_history append-only migration; GET /rooms/:id/world-history + worker writeback; Colyseus worldHistorySync + WorldHistoryPanel. **Key deliverables (planned):** world_history table + Drizzle schema; WorldHistoryPanel + useWorldHistory; minutes expand (full proposal + 12 votes); accepted/rejected toggle -**Verification / 验收 (planned):** `pnpm agent:verify` · game-server test · web test +**Verification (planned):** `pnpm agent:verify` · game-server test · web test -**Tech decisions / 技术决策:** CONTRACTS C-07 world-history API; proposer/voter display names from Phase 23 registry +**Tech decisions:** CONTRACTS C-07 world-history API; proposer/voter display names from Phase 23 registry --- -### Phase 25 — Council Vote & Debate / 议会投票与辩论 +### Phase 25 — Council Vote & Debate | | | |---|---| | **Status** | 📋 Planned | -**Goal / 目标:** Background council loop — proposal → multi-round debate → vote → chronicle + memory writeback; relationship evolution foundation. +**Goal:** Background council loop — proposal → multi-round debate → vote → chronicle + memory writeback; relationship evolution foundation. -**Rationale / 思路:** world-vote BullMQ + Redis bridge; tick LPUSH only; worker world_vote.py ≤3 debate rounds + 11 votes; npc_relationships + applyRelationshipDeltas. +**Rationale:** world-vote BullMQ + Redis bridge; tick LPUSH only; worker world_vote.py ≤3 debate rounds + 11 votes; npc_relationships + applyRelationshipDeltas. **Key deliverables (planned):** world_vote.py graph; npc_relationships migration;「议会审议中」UI + result toast; canon RAG back into speak -**Verification / 验收 (planned):** `pnpm verify:phase25` · game-server test · worker pytest -k world_vote · `pnpm agent:verify --e2e` +**Verification (planned):** `pnpm verify:phase25` · game-server test · worker pytest -k world_vote · `pnpm agent:verify --e2e` -**Tech decisions / 技术决策:** nvidia/agnes only; no 智谱 slot; CONTRACTS C-07 final + C-09 npc_relationships; REL-01…05 +**Tech decisions:** nvidia/agnes only; no 智谱 slot; CONTRACTS C-07 final + C-09 npc_relationships; REL-01…05 --- -### Phase 26 — Council Map Presence / 议会地图存在 +### Phase 26 — Council Map Presence | | | |---|---| | **Status** | 📋 Planned | -**Goal / 目标:** All 12 council NPCs on map — Colyseus sync, Phaser render, all speakable + ambient. +**Goal:** All 12 council NPCs on map — Colyseus sync, Phaser render, all speakable + ambient. -**Rationale / 思路:** Schema supports 12 main NPCs (escape npc1/2/3 three-slot hardcode); 12 proximity speak + ambient schedule; speak persona injection with runtime relationships (REL-06). +**Rationale:** Schema supports 12 main NPCs (escape npc1/2/3 three-slot hardcode); 12 proximity speak + ambient schedule; speak persona injection with runtime relationships (REL-06). **Key deliverables (planned):** Colyseus schema 12-NPC; RoomScene 12 entities + nameplates; DialogueBar accepts council registry id; v5 ship gate verify:phase26 -**Verification / 验收 (planned):** `pnpm verify:phase26` · `pnpm verify:phase13` · `pnpm agent:verify --e2e` · `pnpm uat:phase8` +**Verification (planned):** `pnpm verify:phase26` · `pnpm verify:phase13` · `pnpm agent:verify --e2e` · `pnpm uat:phase8` -**Tech decisions / 技术决策:** Largest schema change — INVARIANTS audit mandatory; VIS-04 frozen contract +**Tech decisions:** Largest schema change — INVARIANTS audit mandatory; VIS-04 frozen contract -**Related issues / 关联 ISSUE:** [ISSUE-037](../docs/ISSUE-LOG.md) (if useNpcChat touched) +**Related issues:** [ISSUE-037](../docs/ISSUE-LOG.md) (if useNpcChat touched) --- -### Phase 27 — Personal Life Timeline / 个人人生时间线 +### Phase 27 — Personal Life Timeline | | | |---|---| | **Status** | 📋 Planned | -**Goal / 目标:** Per-NPC subjective life timeline parallel to objective world history; LLM dynamic growth + cross-NPC multi-perspective. +**Goal:** Per-NPC subjective life timeline parallel to objective world history; LLM dynamic growth + cross-NPC multi-perspective. -**Rationale / 思路:** npc_personal_timeline append-only; 太乙 calendar + registry lifeNodes seeds; worker personal_timeline.py scheduled/event-driven generation. +**Rationale:** npc_personal_timeline append-only; 太乙 calendar + registry lifeNodes seeds; worker personal_timeline.py scheduled/event-driven generation. **Key deliverables (planned):** packages/shared/src/personalTimeline.ts; npc_personal_timeline migration; biography drawer sub-tab; relationship delta → personal timeline entries (REL-07) -**Verification / 验收 (planned):** `pnpm verify:phase27` · `pnpm agent:verify` · game-server test · worker pytest +**Verification (planned):** `pnpm verify:phase27` · `pnpm agent:verify` · game-server test · worker pytest -**Tech decisions / 技术决策:** CONTRACTS C-08 draft personal-timeline API; reflect/lore routing; no 智谱 speak slot; eventAnchorId cross-NPC fact anchor +**Tech decisions:** CONTRACTS C-08 draft personal-timeline API; reflect/lore routing; no 智谱 speak slot; eventAnchorId cross-NPC fact anchor -**Known debt / 已知债务:** Phase 28 REL advanced (decay/NPC-to-NPC chat/relationship graph) post-v5 +**Known debt:** Phase 28 REL advanced (decay/NPC-to-NPC chat/relationship graph) post-v5 --- -## Global Deferred Items / 全局暂缓项 +## Global Deferred Items -| Item / 项 | Phase | Reason / 原因 | +| Item | Phase | Reason | |-----------|-------|---------------| | **Voice STT/TTS** | 09 | Cost + priority; planning complete, code not started | | **SCALE-01** (8–16 players/room) | future | Post-v5 | @@ -901,13 +877,11 @@ --- -## How to Verify / 如何验收 +## How to Verify -**EN:** Run from repo root. Phase scripts require `pnpm dev:stack` + real LLM keys (never `LLM_MOCK=1` for verify:phase*). Unit tests may use mock LLM. +Run from repo root. Phase scripts require `pnpm dev:stack` + real LLM keys (never `LLM_MOCK=1` for verify:phase*). Unit tests may use mock LLM. -**中文：** 在仓库根目录运行。Phase 脚本需 `pnpm dev:stack` + 真实 LLM Key（verify:phase* 禁止 `LLM_MOCK=1`）。单测可用 mock LLM。 - -| Gate / 门禁 | Command | +| Gate | Command | |-------------|---------| | Cloud connectivity | `pnpm verify:cloud` | | Current v4 solo life | `pnpm verify:phase22` | @@ -921,7 +895,7 @@ v5 ship 后 Phase 25/26 须在本表加入 `pnpm verify:phase25` 与 `pnpm verif --- -## Phase Index / Phase 索引（37 phases） +## Phase Index | # | Name | Milestone | Status | |---|------|-----------|--------| @@ -967,4 +941,5 @@ v5 ship 后 Phase 25/26 须在本表加入 `pnpm verify:phase25` 与 `pnpm verif *Maintainers: update this document when a phase ships or status changes. Sync README Project Status table accordingly.* -*维护者：Phase ship 或状态变更时更新本文档，并同步 README 项目状态表。* + +*Maintainers: update when a phase ships. Sync README Project Status accordingly.* diff --git a/docs/DEVELOPMENT-HISTORY.zh-CN.md b/docs/DEVELOPMENT-HISTORY.zh-CN.md new file mode 100644 index 0000000..588f56a --- /dev/null +++ b/docs/DEVELOPMENT-HISTORY.zh-CN.md @@ -0,0 +1,938 @@ +# 开发历程 + +[English](./DEVELOPMENT-HISTORY.md) | **简体中文** + +**以太人生 / AetherLife** — 从 v0（文本闭环）到 v5（AI 议会）的分阶段交付记录。 + +本文档合成 **37 个开发 Phase**（含子阶段）的完整记录。每条含目标、思路、交付、验收、技术决策、已知债务与关联 ISSUE。 + +**最后更新：** 2026-06-25 + +--- + +## 目录 + +- [时间线总览](#时间线总览) +- [里程碑 v0 — 文本闭环](#里程碑-v0--文本闭环) +- [里程碑 v1 — 图形 + 多人 + 世界](#里程碑-v1--图形--多人--世界) +- [里程碑 v2 — 可玩的 AI 小镇](#里程碑-v2--可玩的-ai-小镇) +- [里程碑 v3 — 智能 Ambient 与 Speak SLA](#里程碑-v3--智能-ambient-与-speak-sla) +- [里程碑 v4 — 自主人生闭环](#里程碑-v4--自主人生闭环) +- [里程碑 v5 — AI 议会（进行中）](#里程碑-v5--ai-议会进行中) +- [全局暂缓项](#全局暂缓项) +- [如何验收](#如何验收) + +--- + +## 时间线总览 + +| 里程碑 | 阶段 | 状态 | 交付日期 | +|-----------|--------|--------|---------| +| **v0** 文本闭环 | 01–05 | ✅ 已交付 | 2026-06-04 | +| **v1** 图形 + 多人 + 世界 | 06–08, 10–12.1 | ✅ 已交付 | 2026-06-07 | +| **v2** 可玩的 AI 小镇 | 12.2–15 | ✅ 已交付 | 2026-06-09 | +| **v3** 智能 Ambient 与 Speak SLA | 16–17.1 | ✅ 已交付 | 2026-06-11 | +| **v3.1** 代码健康重构 | 18 | ✅ 已交付 | 2026-06-12 | +| **v4** 自主人生闭环 | 19–22 | ✅ 已交付 | 2026-06-22 | +| **v5** AI 议会 / 世界观 | 23–27 | 🔨 进行中 | Phase 23 ✅（2026-06-25） | + +**v0→v4 脉络：** 纯文本 Generative Agent 闭环 → Colyseus 多人 + Phaser 世界 → 视觉打磨 + 小镇玩法 loop → 智能 ambient + speak 稳定 → 沉浸单人人生（记忆信任 + 世界回响）。 + +**v5 方向：** 从 3 个可对话 NPC 扩展为 12 人 AI 议会：世界编年史、多轮辩论表决、全员上地图、个人人生时间线。 + +--- + +## 里程碑 v0 — 文本闭环 + +**交付：** 2026-06-04 · **阶段：** 01–05 · **核心价值验证：** 感知 → 记忆 → 执行（文本 UI） + +--- + +### Phase 01 — 基础与 Action Schema + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-03 | + +**目标** + +- 建立 monorepo、云 dev stack（Supabase + Upstash）、共享 Zod action schema 作为所有 LLM mutation 的唯一契约。 + +**思路** + +- 云 Postgres/Redis 降低上手成本；game-server 与 worker 共享 Zod schema 防止契约漂移。 + +**关键交付** + +- pnpm + Turborepo monorepo +- `packages/game-actions` Zod + OpenAI tools +- `scripts/verify-cloud.mjs` +- ai-gateway FastAPI `/health` +- `.env.example` Supabase/Upstash template + +**验收:** `pnpm verify:cloud` · `pnpm turbo test` + +**技术决策:** INFR-01 cloud dev stack; INFR-02 game-actions as sole mutation schema + +--- + +### Phase 02 — 单 NPC 文本闭环 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-04 | + +**目标** + +- 单 NPC 在纯文本 UI 完成 Generative Agent 闭环，验证核心价值。 + +**思路** + +- LangGraph + BullMQ 异步 worker；禁止 Colyseus 阻塞 LLM；SSE 驱动「思考中」反馈。 + +**关键交付** + +- game-server room routes + SSE +- `workers/agent-worker` LangGraph `npc_loop.py` +- apps/web chat UI +- `scripts/verify-phase2.mjs` + +**验收:** `pnpm verify:phase2` · `cd workers/agent-worker && LLM_MOCK=1 uv run pytest -q` + +**技术决策:** AGNT-01/03; INFR-03 LangSmith trace + +--- + +### Phase 03 — 持久记忆 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-03 | + +**目标** + +- NPC 记忆跨 restart/session 保留；向量检索注入对话；摘要防膨胀。 + +**思路** + +- pgvector + `@aetherlife/npc-memory`；top-k embedding 检索；≥100 条 bulk 摘要。 + +**关键交付** + +- `packages/npc-memory` schema + migrations +- game-server MemoryService + internal API +- worker reflect/bulk summarize +- `scripts/verify-phase3.mjs` + +**验收:** `pnpm verify:phase3` · `pnpm verify:phase3 -- --seed-bulk=100` + +**技术决策:** D-07 reset clears memory, keeps checkpoint; HNSW dropped for 2048-dim embed + +**已知债务:** Dev embed latency p95 ~2–4s (production target <500ms not met at v0 close) + +--- + +### Phase 04 — 多 NPC 文本房间 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-04 | + +**目标** + +- 1–3 NPC 同 room 独立 thread，玩家可切换对话对象。 + +**思路** + +- 每 NPC 独立 LangGraph thread；NpcTabBar + 记忆面板可观测；`transfer` action 支持 NPC 间转移。 + +**关键交付** + +- Multi-NPC room state +- `transfer` action + executor +- NpcMemoryPanel +- `scripts/verify-phase4.mjs` + +**验收:** `pnpm verify:phase4` + +**技术决策:** AGNT-02/04 + +--- + +### Phase 05 — NL 网关与安全 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-04 | + +**目标** + +- FastAPI 统一 NL 入口，Guardrails + thinking UX。 + +**思路** + +- ai-gateway `/chat` + `/nl/parse` + ContentGuard；early thinking SSE；reply audit。 + +**关键交付** + +- apps/ai-gateway chat/parse/guard +- game-server thinking hooks +- web `/v1` proxy +- `scripts/verify-phase5.mjs` + +**验收:** `pnpm verify:phase5` · `cd apps/ai-gateway && uv run pytest tests -q` + +**技术决策:** SAFE-01…03 + +**已知债务:** Direct gs `/chat` bypass, public audit-log, no rate limit — documented accepted risks in 05-SECURITY.md + +--- + +## 里程碑 v1 — 图形 + 多人 + 世界 + +**交付：** 2026-06-07 · **阶段：** 06–08, 10, 10.5, 11, 11.6, 11.7, 12, 12.1（Phase 09 暂缓） + +**里程碑思路：** 将 v0 文本闭环扩展为图形多人：Colyseus 同步、Phaser 渲染、程序化 chunk、LLM lore、集体记忆 + worker 社交感知。 + +--- + +### Phase 06 — Colyseus 与移动 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-03 | +| **里程碑** | v1 | + +**目标:** Authoritative game-server; player movement sync; foundation for graphics/multiplayer. + +**思路:** Colyseus GameRoom server-authoritative move; 20Hz tick; speak → BullMQ async, never block room. + +**Key deliverables:** GameRoom.ts + schema.ts + move-handler.ts; useColyseusRoom + MovementPanel; useNpcChat speak/broadcast + +**验收:** `pnpm verify:phase6` · `pnpm uat:phase6:playwright` + +**技术决策:** D-01 same port HTTP+WS; D-04 broadcast not SSE on web; D-20 WASD + click grid + +--- + +### Phase 07 — 2.5D 渲染器 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-04 | + +**目标:** Phaser 4 top-down 8×8 room; player + NPC sprites bound to Colyseus/REST; MovementPanel fallback. + +**思路:** Phaser 4 RoomScene + React PhaserGame; probePhaserBoot + fallback path on WebGL failure. + +**Key deliverables:** RoomScene.ts + PhaserGame.tsx; gridLayout.ts + theme.ts; npcReply sanitize + +**验收:** `pnpm verify:phase7` · `pnpm uat:phase7:reset-snap` + +**关联 ISSUE:** [ISSUE-002](../docs/ISSUE-LOG.md) (reset flushSync order) + +--- + +### Phase 08 — 多人房间 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-05 | + +**目标:** 4 players per room + async NPC AI patch without race conditions. + +**思路:** maxClients=4 + clientSeq/moveAck prediction; speak queue + speakBusy per NPC; stateVersion monotonic AI patch. + +**Key deliverables:** GameRoom speak queue + moveAck; applyStatePatch.ts; contentGuard speak blocklist + +**验收:** `pnpm verify:phase8` · `pnpm uat:phase8:playwright` · `pnpm verify:phase8:soak` + +**技术决策:** SYNC-02…04; X-Player-Id / initiatorPlayerId foundation + +**已知债务:** E2E flaky under 智谱 concurrency=1 → fixed in Phase 12.2 ([ISSUE-032](../docs/ISSUE-LOG.md)) + +--- + +### Phase 09 — 语音管线 + +| | | +|---|---| +| **状态** | ⏸ 暂缓 | +| **Decision date** | 2026-06-05 | + +**目标:** STT/TTS immersive voice (PTT → speak path → TTS for initiator only). + +**思路:** Planning complete (CONTEXT/UI-SPEC/4-wave PLAN) but not executed; prioritized world/multiplayer slices; voice needs GPU hosting or paid API cost. + +**Key deliverables (planned only):** 09-CONTEXT.md + 09-UI-SPEC.md; 09-01…04-PLAN.md — **no apps/ voice code** + +**验收:** — (not implemented) + +**技术决策:** D-02 PTT + Colyseus speak primary path; self-hosted Speaches/Kokoro preferred architecture + +**已知债务:** VOICE-01/02 fully deferred; resume conditions documented in phase 09 status + +--- + +### Phase 10 — Chunk 地形 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-05 | + +**目标:** Seed-driven chunk load/unload + DB delta persistence. + +**思路:** ChunkLoader 3×3 window + LRU; door delta persist on re-enter; Colyseus global coords + chunksSync. + +**Key deliverables:** chunk-loader.ts; world_chunk_deltas migration; `scripts/verify-phase10.mjs` + +**验收:** `pnpm verify:phase10` · `pnpm uat:phase10:playwright` + +**技术决策:** WORLD-01; WORLD-03 + +**已知债务:** LLM lore → Phase 11; tile sprite atlas → art pass (Phase 13) + +--- + +### Phase 10.5 — Phaser 移动同步 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-05 | + +**目标:** Phaser-first movement orchestration; RoomScene owns input→sync; eliminate React onMove vs explore tick races. + +**思路:** RoomScene.setupInput → movementSync; remove useColyseusRoom setInterval explore tick; MP-MOV-02 shouldSuppressLocalSchemaSnap gate. + +**Key deliverables:** docs/MOVEMENT-ARCHITECTURE.md; localPlayerSchemaSnap.ts; verify-phase6 move-only gate + +**验收:** `pnpm verify:phase6:move-only` · `pnpm --filter @aetherlife/shared test` + +**技术决策:** Phaser-first movement; registry changedata explore coords + +--- + +### Phase 11 — LLM 世界 Lore + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-06 | + +**目标:** Async LLM metadata on first chunk enter; persisted cache. + +**思路:** lore-orchestrator + lore_loop.py async job; Postgres chunk_lore cache hit skips repeat LLM; ExploreStrip + lore toast. + +**Key deliverables:** lore-orchestrator.ts; lore_loop.py; ExploreStrip + toast + +**验收:** `pnpm verify:phase11` · `pnpm uat:phase11:playwright` + +**技术决策:** WORLD-02; dedup poll in verify script + +--- + +### Phase 11.6 — 智谱主路径 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-07 | + +**目标:** 智谱 glm-4.7-flash as NPC primary path + lore text fallback; factory zhipu provider. + +**思路:** factory provider=zhipu + thinking disabled; NPC failure fallback OpenRouter; verify:llm-models probes zhipu. + +**Key deliverables:** workers/agent-worker llm/factory.py; npc_loop zhipu default; scripts/verify-llm-models.mjs + +**验收:** `pnpm verify:llm-models` · worker pytest + +**技术决策:** 智谱 account concurrency = 1 constraint + +**关联 ISSUE:** [ISSUE-032](../docs/ISSUE-LOG.md) root cause (zhipu concurrency) + +--- + +### Phase 11.7 — LLM 角色路由 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-07 | + +**目标:** Six-platform role-based LLM routing; 智谱 slot reserved for NPC tool-calling only. + +**思路:** Social/Summarize/Collective → SiliconFlow Qwen3.5-4B; Importance → NVIDIA nano; Lore fallback → NVIDIA; NPC fallback → OpenRouter. + +**Key deliverables:** docs/LLM-ROUTING.md; config.py role routing; .env.example six-platform blocks + +**验收:** `pnpm verify:llm-models` · `pnpm agent:verify` · worker pytest + +**关联 ISSUE:** [ISSUE-031](../docs/ISSUE-LOG.md), [ISSUE-032](../docs/ISSUE-LOG.md), [ISSUE-033](../docs/ISSUE-LOG.md) + +--- + +### Phase 12 — 集体记忆 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-07 | + +**目标:** Multi-player behavior toward NPCs writes shared collective memory; attitude observable. + +**思路:** collective tables + dual speak events; AttitudeBandChip + hostile gate 403; worker tool_gate + memory tail. + +**Key deliverables:** packages/npc-memory collective tables; apps/game-server/src/collective/*; AttitudeBandChip + +**验收:** `VERIFY_PHASE12_FAST=1 pnpm verify:phase12` + +**技术决策:** SOCL-01/02 + +--- + +### Phase 12.1 — LLM 社交感知 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-07 | + +**目标:** Worker structured social perception + reply; server no longer dual-writes speak wordlists. + +**思路:** SocialTurnOut → apply event → refresh band; score_social_perception structured turn; server action rules only for collective writes. + +**Key deliverables:** worker social perception graph; uat-phase12.1-playwright.mjs; ISSUE-LOG Guardrails 59–60 + +**验收:** `pnpm uat:phase12.1:playwright` · `VERIFY_PHASE12_FAST=1 pnpm verify:phase12` + +**技术决策:** Option B — worker-only social LLM + +--- + +## 里程碑 v2 — 可玩的 AI 小镇 + +**交付：** 2026-06-09 · **阶段：** 12.2, 13, 13.1, 13.2, 13.3, 14, 14.1, 15 + +**里程碑思路：** 路径 1 核心 loop：探索 chunk → lore → NL → 集体态度 → 跨 session 记忆；Phaser 视觉可传播；speak 稳定可日常玩。 + +--- + +### Phase 12.2 — Speak 可靠性 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-07 | + +**目标:** Eliminate 智谱 single-slot speak/E2E flakiness; multiplayer NL playable daily. + +**思路:** NPC main dialogue → SiliconFlow Qwen3.5-4B; per-NPC serial + cross-NPC parallel; worker BRPOP FIFO + speakBusy no silent drop. + +**Key deliverables:** llm_social_turn.py social degrade; main.py BRPOP + async memory tail; structured LLM call log + +**验收:** `pnpm agent:verify --e2e` · `pnpm verify:phase8` · `pnpm verify:llm-models` + +**技术决策:** STAB-02 — three consecutive E2E passes as sole ship gate + +**关联 ISSUE:** [ISSUE-032](../docs/ISSUE-LOG.md) fixed; [ISSUE-022](../docs/ISSUE-LOG.md) guardrail (memory in worker tail only) + +--- + +### Phase 13 — Phaser 世界视觉 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-08 | + +**目标:** First screen upgrade from prototype discs to shareable Stardew-style tile + sprite + decor world. + +**思路:** Tilemap replaces drawFloor; 4-dir walk/idle anim; Y-sort + proximity nameplate (VIS-04); area lazy preload + visualFallback. + +**Key deliverables:** FloorRenderer + DecorRenderer; entitySprites + animations; ProximityNameplate + +**验收:** `pnpm verify:phase13` · `pnpm uat:phase13:playwright` · `pnpm verify:phase6:move-only` + +**技术决策:** 16×16 pixel tile pastoral; D-22 boot >5s warn / >8s fail + +**关联 ISSUE:** [ISSUE-035](../docs/ISSUE-LOG.md), [ISSUE-036](../docs/ISSUE-LOG.md), [ISSUE-038](../docs/ISSUE-LOG.md) + +--- + +### Phase 13.1 — 美术资源替换 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-08 | + +**目标:** Replace placeholder art with CC0/LPC real pixel assets; aesthetic rubric AE-01…08. + +**Key deliverables:** Kenney Tiny Town + Universal LPC import; pnpm art:import; CREDITS.md + +**验收:** `pnpm verify:phase13` · `pnpm uat:phase13:playwright` + +**技术决策:** TILE_PX=16, FRAMES_PER_FACING=6 contract + +--- + +### Phase 13.2 — 农场美术 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-08 | + +**目标:** Tiny Town 地球Online-style tiles replace Roguelike; life-sim aesthetic AE-08. + +**Key deliverables:** pastoralTint.ts; pnpm art:import:farm; home-farm.png canonical screenshot + +**验收:** `pnpm verify:phase13` · `pnpm uat:phase13:playwright` + +**关联 ISSUE:** [ISSUE-039](../docs/ISSUE-LOG.md) (decor Y-sort) + +--- + +### Phase 13.3 — 星露谷比例校准 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-08 | + +**目标:** CELL_PX=48 integer scale + 16×32 character frames + Asset Bible. + +**思路:** 16px source × 3 = 48px on-screen cell; LPC bbox crop bottom-align; logical 8×8 chunk map unchanged. + +**验收:** `pnpm verify:phase13` · `pnpm uat:phase13:playwright` · `pnpm agent:verify` + +**技术决策:** Colyseus coords remain integer grid cells; viewport 576×576 + +--- + +### Phase 14 — 有生命的 NPC + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-08 | + +**目标:** Observable NPC life when player is not speaking — schedule + activity sync. + +**思路:** game-server 6s ambient tick (no LLM in tick); accelerated game-day clock + ExploreCoordsStrip HUD; proximity activity sub-labels. + +**Key deliverables:** ambient engine + schedule JSON; Colyseus activity + gameTime schema; Phaser activity labels + +**验收:** `pnpm verify:phase14` · `pnpm --filter @aetherlife/game-server test` + +**技术决策:** 1 real minute = 10 game minutes; speak/thinking pauses single NPC ambient + +**已知债务:** Low-frequency lore/reflect enrichment → Phase 16 + +--- + +### Phase 14.1 — 被挡朝向 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-08 | + +**目标:** WASD blocked still updates local idle facing; optional multiplayer facing sync. + +**Key deliverables:** clientMovementPredictor onBlockedFace; move-handler facing-on-block; MP-MOV-05 in MOVEMENT-ARCHITECTURE.md + +**验收:** `pnpm agent:verify` · `pnpm --filter @aetherlife/web test` · `pnpm verify:phase6:move-only` + +**技术决策:** C-04 blocked-facing CONTRACTS row + +**关联 ISSUE:** [ISSUE-040](../docs/ISSUE-LOG.md) + +--- + +### Phase 15 — 小镇玩法 Loop + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-09 | + +**目标:** Path 1 UAT-ready loop: explore → lore → NL → collective attitude → cross-session memory. + +**Key deliverables:** JournalQuestStrip; CollectiveBrowsePanel + resolveCollectiveInitiatorPlayerId; ColyseusNpcJobDonePayload.memoryQuote + +**验收:** `pnpm verify:phase15` · `pnpm uat:phase15:playwright` · `pnpm verify:phase13` + +**技术决策:** initiator from playerIds, never text inference; memory write in worker tail only + +**关联 ISSUE:** [ISSUE-022](../docs/ISSUE-LOG.md) + +--- + +## 里程碑 v3 — 智能 Ambient 与 Speak SLA + +**交付：** 2026-06-11 · **阶段：** 16, 17, 17.1（含 Phase 18 代码健康重构，2026-06-12） + +**里程碑思路：** Tiled 可行走世界上的 zone/意图驱动漫游；异步 LLM intent；speak 热路径缓存加固 + 真实 LLM golden E2E。 + +--- + +### Phase 16 — 智能 Ambient NPC + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-11 | + +**目标:** Scalable Tiled world with zone/intent-driven NPC wander; async LLM intent planner. + +**思路:** WorldRegion registry + zone wander replaces waypoint ring; async intent job (schedule segment change + speak_end trigger); village-plaza@v1 cross-region + background NPC tier. + +**Key deliverables:** WorldRegion + zones/pois/spawns; npc-ambient-intent BullMQ job; Tiled collision walkability + +**验收:** `pnpm verify:phase16` · `pnpm agent:verify` · game-server test + +**技术决策:** 6s tick ≤1 cell; no blocking LLM in tick; intent third-line UI abolished + +**已知债务:** COZY-01 Metlivi economy deferred + +**关联 ISSUE:** [ISSUE-043](../docs/ISSUE-LOG.md) + +--- + +### Phase 17 — Speak 热路径 SLA + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-11 | + +**目标:** worker-state / memory-context cache + internal latency observability; shorten speak hot path. + +**思路:** skipNearbyLore default on speak hot path; memoryContextCache bounded TTL; stale snapshot fallback, no hard-fail. + +**Key deliverables:** memoryContextCache.ts; skipNearbyLore default; internal-latency logs + +**验收:** `pnpm agent:verify` · `pnpm agent:verify --e2e --base` · game-server test + +**技术决策:** Infra SLA here; user-perceived SLA defined in v4 Phase 20 + +--- + +### Phase 17.1 — Speak 缓存加固 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-11 | + +**目标:** Post-Phase-17 cache identity, invalidation, bounds, lore stampede hardening. + +**Key deliverables:** internal-memories identity fix; memoryContextCache bounds; bridge.test.ts reset snap + +**验收:** `pnpm agent:verify --e2e --base` + +**技术决策:** Align C-01 internal player id + +--- + +### Phase 18 — 代码健康重构 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-12 | +| **里程碑** | v3.1 | + +**目标:** Reduce maintenance cost without behavior change — verify DRY + RoomScene/useNpcChat split. + +**思路:** All verify-phase*.mjs → scripts/lib/env.mjs; useNpcChat pure functions → hooks/npcChat/; RoomScene split by camera/floor/input/sync/motion. + +**Key deliverables:** scripts/lib/env.mjs; roomSceneSync.ts + submodules; hooks/npcChat/* + +**验收:** `pnpm agent:verify` · `pnpm agent:verify --e2e --base` · `pnpm verify:phase13` · `pnpm verify:phase8` + +**技术决策:** Frozen UX files untouched (ISSUE-037/038); RoomScene.ts ~1086 LOC post-split + +**已知债务:** ISSUE-049 multiplayer reset; worker npc_loop.py split deferred + +**关联 ISSUE:** [ISSUE-037](../docs/ISSUE-LOG.md), [ISSUE-038](../docs/ISSUE-LOG.md), [ISSUE-049](../docs/ISSUE-LOG.md) + +--- + +## 里程碑 v4 — 自主人生闭环 + +**交付：** 2026-06-22 · **阶段：** 19–22 · **标签：** v4 + +**里程碑思路：** 全屏沉浸壳；跨 session 记忆口播；无任务条的世界回响；单人真实 LLM C1–C5 rubric ship gate。 + +--- + +### Phase 19 — 沉浸 UI 壳 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-13 | + +**目标:** Full-screen immersive UI — Phaser fill + DialogueBar + ShellDrawer; remove NpcTabBar. + +**思路:** 100dvh shell + Stardew wood-frame HUD; map click + NpcAvatarStrip replaces TabBar; drawer for history/collective. + +**Key deliverables:** ImmersiveShell + DialogueBar + ShellDrawer; CornerMenu + NpcAvatarStrip; Phaser NPC hit-test + +**验收:** `pnpm verify:phase19` · `pnpm verify:phase13` · `pnpm uat:phase8` + +**技术决策:** useNpcChat speakBusy unchanged (Frozen ISSUE-037); JournalQuestStrip retained until Phase 21 + +**关联 ISSUE:** [ISSUE-037](../docs/ISSUE-LOG.md), [ISSUE-038](../docs/ISSUE-LOG.md), [ISSUE-041](../docs/ISSUE-LOG.md), [ISSUE-011](../docs/ISSUE-LOG.md) + +--- + +### Phase 20 — 记忆与 Speak 信任 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-16 | + +**目标:** Solo trust floor — cross-session memory in speech + user-perceived Speak SLA Tier-1 (not Phase 17 ms tables). + +**思路:** recall_merge cross-session password/nickname; engageDialogue overlay-first measures T_think/T_first; SOLO-05 Tier-1 ship gates separate from Tier-2 audit. + +**Key deliverables:** recall_merge.py + memory_quote; benchmark-speak-browser.mjs; SPEAK-SLA scorecard + +**验收:** `pnpm verify:phase20` · `pnpm agent:verify` + +**技术决策:** D-12 charter — Tier-1 verify+UAT ships; Tier-2 p95 audit only; assert-refusal-markers-parity JS↔Python + +**关联 ISSUE:** [ISSUE-041](../docs/ISSUE-LOG.md), [ISSUE-050](../docs/ISSUE-LOG.md) + +--- + +### Phase 21 — 世界回响 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-21 | + +**目标:** Life-sim feel without quests — NL world traces; remove JournalQuestStrip; lore toast +「已发现」drawer. + +**Key deliverables:** Remove JournalQuestStrip; LoreDiscoverToast; DiscoveredLorePanel drawer tab; 21-QUEST-LANGUAGE-AUDIT.md + +**验收:** `pnpm verify:phase21` · `pnpm uat:phase21:playwright` · `pnpm verify:phase13` + +**技术决策:** Non-quest copy gate; ISSUE-013 pending→ready toast split + +**关联 ISSUE:** [ISSUE-013](../docs/ISSUE-LOG.md) + +--- + +### Phase 22 — 单人人生门禁 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-22 | + +**目标:** v4 ship gate — solo real-LLM C1–C5 rubric + SOLO-04/06 aggregate verification. + +**思路:** pnpm verify:phase22 aggregates phase20+21+inline+golden; Collective rude auto-opens drawer + help no double-open (SOLO-04); Human UAT 10/10. + +**Key deliverables:** scripts/verify-phase22.mjs aggregator; 22-UAT-MATRIX.md; v4 milestone closure + +**验收:** `pnpm verify:phase22` · `pnpm agent:verify` · `pnpm agent:verify --e2e` + +**技术决策:** WORLD_SEED=42 golden spawns; 5-step aggregator ~22min real LLM + +--- + +## 里程碑 v5 — AI 议会（进行中） + +**启动：** 2026-06-25（Phase 23）· **阶段：** 23–27 · **状态：** Phase 23 ✅；24–27 📋 规划中 + +**里程碑思路：** 将 NPC 从 3 个可对话角色升级为 12 人 AI 议会：世界编年史、多轮辩论表决、全员上地图、与世界历史双轨的个人主观传记时间线。 + +--- + +### Phase 23 — 议会人格基础 + +| | | +|---|---| +| **状态** | ✅ 已交付 | +| **完成** | 2026-06-25 | + +**目标:** 12 council NPCs single source of truth registry + `__council__` memory scope; persona data layer for vote/map expansion. + +**思路:** COUNCIL_PERSONAS SSOT + 12 dossiers; worker speak persona injection (npc-1..3); pgvector `__council__` isolated from player speak memory. + +**Key deliverables:** packages/shared/src/council/* + npcPersonas.ts; councilSeed.ts + C-07 CONTRACTS; CouncilRosterPanel drawer tab「星际议会」; 12 schedule JSON + personality seeds + +**验收:** `pnpm agent:verify` · game-server test · worker pytest + +**技术决策:** SPEAKABLE_NPC_IDS = npc-1..3 only; voting 4/3/5 against/for/swing split + +**已知债务:** PERSONA-04 vote-time LTM E2E → Phase 25; PERSONA-02 live speak voice differentiation → human UAT + +**关联 ISSUE:** [ISSUE-001](../docs/ISSUE-LOG.md), [ISSUE-022](../docs/ISSUE-LOG.md) + +--- + +### Phase 24 — 世界历史编年史 + +| | | +|---|---| +| **状态** | 📋 规划中 | + +**目标:** World history chronicle persistence + player-readable drawer panel; vote provenance and rejected-proposal history. + +**思路:** world_history append-only migration; GET /rooms/:id/world-history + worker writeback; Colyseus worldHistorySync + WorldHistoryPanel. + +**Key deliverables (planned):** world_history table + Drizzle schema; WorldHistoryPanel + useWorldHistory; minutes expand (full proposal + 12 votes); accepted/rejected toggle + +**验收（规划）:** `pnpm agent:verify` · game-server test · web test + +**技术决策:** CONTRACTS C-07 world-history API; proposer/voter display names from Phase 23 registry + +--- + +### Phase 25 — 议会投票与辩论 + +| | | +|---|---| +| **状态** | 📋 规划中 | + +**目标:** Background council loop — proposal → multi-round debate → vote → chronicle + memory writeback; relationship evolution foundation. + +**思路:** world-vote BullMQ + Redis bridge; tick LPUSH only; worker world_vote.py ≤3 debate rounds + 11 votes; npc_relationships + applyRelationshipDeltas. + +**Key deliverables (planned):** world_vote.py graph; npc_relationships migration;「议会审议中」UI + result toast; canon RAG back into speak + +**验收（规划）:** `pnpm verify:phase25` · game-server test · worker pytest -k world_vote · `pnpm agent:verify --e2e` + +**技术决策:** nvidia/agnes only; no 智谱 slot; CONTRACTS C-07 final + C-09 npc_relationships; REL-01…05 + +--- + +### Phase 26 — 议会地图存在 + +| | | +|---|---| +| **状态** | 📋 规划中 | + +**目标:** All 12 council NPCs on map — Colyseus sync, Phaser render, all speakable + ambient. + +**思路:** Schema supports 12 main NPCs (escape npc1/2/3 three-slot hardcode); 12 proximity speak + ambient schedule; speak persona injection with runtime relationships (REL-06). + +**Key deliverables (planned):** Colyseus schema 12-NPC; RoomScene 12 entities + nameplates; DialogueBar accepts council registry id; v5 ship gate verify:phase26 + +**验收（规划）:** `pnpm verify:phase26` · `pnpm verify:phase13` · `pnpm agent:verify --e2e` · `pnpm uat:phase8` + +**技术决策:** Largest schema change — INVARIANTS audit mandatory; VIS-04 frozen contract + +**关联 ISSUE:** [ISSUE-037](../docs/ISSUE-LOG.md) (if useNpcChat touched) + +--- + +### Phase 27 — 个人人生时间线 + +| | | +|---|---| +| **状态** | 📋 规划中 | + +**目标:** Per-NPC subjective life timeline parallel to objective world history; LLM dynamic growth + cross-NPC multi-perspective. + +**思路:** npc_personal_timeline append-only; 太乙 calendar + registry lifeNodes seeds; worker personal_timeline.py scheduled/event-driven generation. + +**Key deliverables (planned):** packages/shared/src/personalTimeline.ts; npc_personal_timeline migration; biography drawer sub-tab; relationship delta → personal timeline entries (REL-07) + +**验收（规划）:** `pnpm verify:phase27` · `pnpm agent:verify` · game-server test · worker pytest + +**技术决策:** CONTRACTS C-08 draft personal-timeline API; reflect/lore routing; no 智谱 speak slot; eventAnchorId cross-NPC fact anchor + +**已知债务:** Phase 28 REL advanced (decay/NPC-to-NPC chat/relationship graph) post-v5 + +--- + +## 全局暂缓项 + +| 项 | Phase | 原因 | +|-----------|-------|---------------| +| **Voice STT/TTS** | 09 | Cost + priority; planning complete, code not started | +| **SCALE-01** (8–16 players/room) | future | Post-v5 | +| **COZY / ECON** economy chain | future | Metlivi economy deferred from Phase 16 | +| **ISSUE-049** multiplayer shared reset | cross-cutting | POST /reset still resets shared RoomState | +| **Phase 28** advanced relationships | post-v5 | Decay, NPC-to-NPC chat, relationship graph | + +--- + +## 如何验收 + +在仓库根目录运行。Phase 脚本需 `pnpm dev:stack` + 真实 LLM Key（verify:phase* 禁止 `LLM_MOCK=1`）。单测可用 mock LLM。 + +| 门禁 | Command | +|-------------|---------| +| Cloud connectivity | `pnpm verify:cloud` | +| Current v4 solo life | `pnpm verify:phase22` | +| Current v5 council (Phase 23) | `pnpm agent:verify` + game-server test + worker pytest | +| Golden flows (regression) | `pnpm agent:verify --e2e --base` | +| Full test suite | `pnpm turbo test` | + +--- + +## Phase 索引（37 个） + +| # | 名称 | 里程碑 | 状态 | +|---|------|-----------|--------| +| 01 | Foundation & Action Schema | v0 | ✅ | +| 02 | Single NPC Text Loop | v0 | ✅ | +| 03 | Persistent Memory | v0 | ✅ | +| 04 | Multi-NPC Text Room | v0 | ✅ | +| 05 | NL Gateway & Safety | v0 | ✅ | +| 06 | Colyseus & Movement | v1 | ✅ | +| 07 | 2.5D Renderer | v1 | ✅ | +| 08 | Multiplayer Room | v1 | ✅ | +| 09 | Voice Pipeline | v1 | ⏸ | +| 10 | Chunk Terrain | v1 | ✅ | +| 10.5 | Phaser Movement Sync | v1 | ✅ | +| 11 | LLM World Lore | v1 | ✅ | +| 11.6 | Zhipu GLM-4.7-Flash | v1 | ✅ | +| 11.7 | LLM Role Routing | v1 | ✅ | +| 12 | Collective Memory | v1 | ✅ | +| 12.1 | LLM Social Perception | v1 | ✅ | +| 12.2 | Speak Reliability | v2 | ✅ | +| 13 | Phaser World Visuals | v2 | ✅ | +| 13.1 | Phaser World Art Pass | v2 | ✅ | +| 13.2 | Farm Art Pass | v2 | ✅ | +| 13.3 | Stardew Scale Calibration | v2 | ✅ | +| 14 | Living NPCs | v2 | ✅ | +| 14.1 | Blocked Move Facing | v2 | ✅ | +| 15 | Town Play Loop | v2 | ✅ | +| 16 | Intelligent Ambient NPCs | v3 | ✅ | +| 17 | Speak Pre-LLM SLA | v3 | ✅ | +| 17.1 | Speak Cache Hardening | v3 | ✅ | +| 18 | Code Health Refactor | v3.1 | ✅ | +| 19 | Immersive UI Shell | v4 | ✅ | +| 20 | Memory & Speak Trust | v4 | ✅ | +| 21 | World Echo | v4 | ✅ | +| 22 | Solo Life Gate | v4 | ✅ | +| 23 | Council Persona Foundation | v5 | ✅ | +| 24 | World History Chronicle | v5 | 📋 | +| 25 | Council Vote & Debate | v5 | 📋 | +| 26 | Council Map Presence | v5 | 📋 | +| 27 | Personal Life Timeline | v5 | 📋 | + +--- + +*维护者：Phase ship 或状态变更时更新本文档，并同步 README 项目状态表。*