> 导出自在线文档 [voko-world 仓库初始化清单](https://claude.ai/code/artifact/20a68ea3-4b05-49fd-9173-520b80733534)，rev 18，2026-10-10 导出。

# voko-world 仓库初始化清单

Oct 10, 2026 · @lemon

## 决定与原则

结论（2026-10-10 已定）：VOKO Agent 世界按新产品开发，新建 GitLab 仓库 `voko-world` 和独立数据库 `voko`；从 shadiao-2d 只搬入 18 个包（约 2.7 万行），不拷贝整个仓库再删减。目标是 W1 前两天（10-12 → 10-13）完成骨架。

- **搬入，不删减**：从空仓库开始，缺什么立刻报错；不从 30 万行里逐个排查引用。
- **独立数据库**：不碰 voko game 的 `idearun_visual_game`；用户、账本、`vk_` 表全部在 `voko` 库。两个产品账号和积分不通，Beta 对外时再决定是否打通。
- **工程规范整套保留**：AGENTS.md 的代码硬规则（入口校验、穷举状态、DB 约束、禁止 mock、snake\_case）、ESLint 架构边界规则、Knex 迁移体系、CI 门禁（install → lint → test → schema:check）。
- **包名暂不改**：继续用 `@drama/*`，减少搬运时的改动和后续对照同步的成本；新写的包用 `@voko/*`。
- **AI Town 不搬入**：在仓库外单独 clone 作参考；以后引入任何文件要保留 MIT 版权声明。
- **迁移纪律**：迁移只在合入主干后才在共享库（stage / 生产）执行；开发只连本地 Docker MySQL。

## 搬运清单

结论：15 个直接需要的包 + 3 个被依赖的包（core、rig、service-call），另从 visual-game-server 拿约 1,300 行装配代码作为新服务的起点。行数为 2026-10-10 在 shadiao-2d 主干统计的 src 下 JS / Vue / CJS 行数。

### 包

| 包 | 行数 | 用途 | 搬入时裁剪 |
| --- | --- | --- | --- |
| `@drama/billing` | 1,652 | 积分账本（deduct / grant、幂等、余额视图） | 保留 ledger、repo、表定义；paywall、products、daily-claim、commerce-operations、model-settlement 先保留但不装配 |
| `@drama/auth` | 1,245 | 登录、session、OAuth | 保留全部；删除 `fake-repo.js`（仓库禁止替身） |
| `@drama/db` | 494 | Knex 连接、`users` 表、schema 应用 | 保留全部；`users` 表保持原结构 |
| `@drama/email` | 1,088 | 邮件发送、投递日志 | 删除 voko game 专用模板，保留验证码类模板 |
| `@drama/llm` | 2,787 | 大模型调用 | 保留全部 |
| `@drama/llm-router` | 343 | 模型路由与配置表 | 保留全部 |
| `@drama/moderation` | 602 | 内容审核 | 删除 `fake.js` |
| `@drama/ratelimit` | 450 | 令牌桶限流 | 保留全部 |
| `@drama/server-kit` | 248 | Fastify 错误、限流接入、trace | 保留全部 |
| `@drama/observability` | 530 | ctx、span、日志 | 保留全部 |
| `@drama/contracts` | 3,243 | 接口 schema 与快照 | 只留 `auth`、`account`、`error`、`credits`；删除 drama / visual-game / waitlist / share 等 |
| `@drama/config` | — | 共享 Vite / Vitest / ESLint 预设 | 保留全部 |
| `@drama/ui` | 3,006 | 基础组件与主题 token | 保留全部 |
| `@drama/render-pixi` | 1,259 | PixiJS v8 渲染（公会城） | 保留全部 |
| `@drama/i18n` | 7,665 | 多语言运行时与文案 | 保留运行时；文案只留通用部分和 en / zh |
| `@drama/core` | 1,213 | render-pixi 的依赖 | 保留全部；若 W5 公会城不用其播放链路再评估 |
| `@drama/rig` | 506 | render-pixi 的依赖 | 同上 |
| `@drama/service-call` | 276 | 依赖 | 保留全部 |

### 从 visual-game-server 拿的装配代码（改写成 `apps/voko-server`）

| 文件 | 行数 | 用途 |
| --- | --- | --- |
| `src/main.js`、`src/app.js` | 202 | 启动与 Fastify 装配的骨架，删去所有 visual-game 路由 |
| `src/env.js`、`assembly/env-guard.js` | 431 | 环境变量解析与校验，只留数据库、邮件、大模型 |
| `auth 装配片段（验证码登录）`、`assembly/security.js` | 168 | 邮箱验证码登录与安全头；不设邮箱白名单，改为申请制（后台审核） |
| `assembly/email.js` | 141 | 邮件装配 |
| `assembly/llm.js` | 331 | 大模型装配，去掉 visual-game 的计费钩子 |
| `src/db/` 迁移脚本（init / migrate / status / baseline） | — | 改历史表名为 `voko_schema_migrations`，目标表列表只包含本产品的表 |
| 根目录 `tools/eslint-rules/`、`eslint.config.js`、`turbo.json`、`pnpm-workspace.yaml`、`vitest.workspace.js`、`docker-compose.yml`、`tools/scripts/mysql-dev.js`、`tools/scripts/schema-check.js` | — | 工程规则与本地 MySQL |
| `AGENTS.md` | — | 保留代码硬规则、测试与前端规范；删掉 visual-game 端口、AWS、素材等段落 |

**新库里的表**：`users`、auth 的 4 张（auth\_attempts、auth\_codes、auth\_sessions、user\_oauth）、billing 的 6 张 + 余额视图、`email_delivery_logs`、`mode_model_config`，再加 23 张 `vk_` 表。

## 初始化步骤

结论：共 5 步，约 2–3 人日，由程序员 B 主导；前 3 步完成前，程序员 A 可以先在 `packages/voko-exchange` 写状态机纯函数（不依赖骨架）。

**第 1 步：建仓库与工程规则（半天）**

- [x] GitLab 新建 `vokoworld`（git@gitlab-wuwei.hexpm.com:yibo/vokoworld.git）；主干保护与「MR 必须过 CI」待在 GitLab 设置
- [x] 拷入根配置：`package.json`、`pnpm-workspace.yaml`、`turbo.json`、`eslint.config.js`、`vitest.workspace.js`、`tools/eslint-rules/`（composition root 改为 voko-server 入口）
- [x] 拷入并裁剪 `AGENTS.md`；`docs/voko/README.md` 放文档索引（导出版待 W1 内放入）
- [x] 拷入 `docker-compose.yml` 与 `tools/scripts/mysql-dev.js`，库名改为 `voko`；可与 shadiao-2d 共用同一个本地 MySQL 服务
- [x] CI（`.gitlab-ci.yml`）：install → lint → test；schema:check 在 voko-server 建立后加入

**第 2 步：搬入 18 个包（半天到一天）**

- [x] 搬入 19 个包（实际依赖闭包比清单多一个 `config-source`，为 llm-router 的开发依赖）；沿用 shadiao-2d 的 lockfile 锁定版本
- [x] `pnpm lint` 全绿；`pnpm test` 14 个测试任务全绿；工具链规则单测 5 个文件全绿
- [ ] 按搬运清单裁剪：已决定先原样保留、在 upstream.md 列为待裁剪——contracts 与上游业务耦合较深、auth 测试依赖替身、海外产品需要多语言；在写 voko-server 时顺带处理
- [x] `docs/voko/upstream.md` 记录来源：shadiao-2d stage@5bae6b7，及搬入时做的 5 处改动

**第 3 步：新服务骨架 `apps/voko-server`（一天）**

- [x] `apps/voko-server`：`main.js`、`app.js`、`env.js`、`assembly/runtime.js`，只装配数据库、账号（邮箱验证码注册 + 密码登录，配置了 GOOGLE\_OAUTH\_CLIENT\_ID 时开放 Google 登录）、邮件；大模型与限流在用到的周再装配（大模型 W3、限流 W2）
- [x] 加入申请：`@voko/access` 包 + `vk_access_requests` 表；`/api/voko/access-requests` 提交、`/api/voko/admin/access-requests` 审核，通过时发邮件；不设邮箱白名单
- [x] 数据库命令 `db:init` / `db:migrate` / `db:status`，历史表 `voko_schema_migrations`；`admin:grant` 设置第一个管理员
- [x] `GET /healthz` 与接口校验、鉴权错误格式已用 Fastify inject 自测；登录与审核的真实链路待本地库跑 `verify:skeleton`
- [x] `voko-worker-main.js` 可启动（骨架阶段只做心跳）；`ecosystem.config.cjs` 登记两个进程

**第 4 步：空前端 `apps/voko-web`（半天）**

- [x] Vite + Vue 3 + `@drama/ui` + vue-i18n（en / zh）；`/api` 代理到 voko-server；`vite build` 通过
- [x] 登录 / 注册页、首页（显示当前用户与申请状态、提交申请）
- [x] 后台 `/admin`（按角色控制）：排队列表、通过 / 拒绝

**第 5 步：空库初始化与部署通道（半天）**

- [x] 本地 `pnpm mysql:up` → `init-current-schema.js` 建出平台表与余额视图（2026-10-10，`verify:skeleton` 15 项通过）
- [ ] stage 服务器与 stage 库（独立于 voko game 的 stage）；域名 `api.voko.world`（API）与前端域名解析到位
- [ ] 密钥只在各 app 的 gitignored `.env`：DATABASE\_URL、邮件、大模型、Webhook 密钥加密 key

## 验收

结论：下面 6 条全部通过，骨架才算完成，对应 Planning W1 的第一个闸口。

- [ ] 新机器上从 clone 开始：`pnpm install` → `pnpm mysql:up` → 初始化库 → `pnpm dev`，30 分钟内跑起来，按 README 操作无需问人
- [ ] `pnpm lint`、`pnpm test`、`pnpm schema:check` 全绿，CI 同样全绿
- [ ] 任意邮箱可用验证码登录并提交申请；未审核前显示排队，后台点通过后状态变为已通过并收到邮件
- [ ] 用真实接口给一个用户 grant 100 积分、deduct 30 积分，余额视图显示 70；同一幂等键重放不重复记账
- [ ] 邮件通道发出一封测试信，由真实收件箱确认送达；大模型通道完成一次真实调用
- [ ] 仓库里搜不到 `visual-game`、`drama` 业务路由、`fake` 替身文件（包名 `@drama/*` 除外）

## 同步纪律

结论：两个仓库从此各自演进；账本、登录、支付这类涉及钱和安全的包，上游修复要主动同步。

- `docs/voko/upstream.md` 记录每个搬入包的 shadiao-2d 来源 commit 与日期，以及搬入后做过的裁剪。
- 每两周由一人对照 shadiao-2d 中 `billing`、`auth`、`db`、`email`、`server-kit` 的提交记录，把修复类提交按需搬过来，并更新 upstream.md。
- 反方向同理：voko-world 里对这些包的修复，如果 shadiao-2d 也需要，开 MR 给 shadiao-2d。
- Beta 接入支付时，再从 shadiao-2d 搬 `payment` 与 `pay-client`，按同样纪律记录。