导出自在线文档 voko-world 仓库初始化清单，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，按同样纪律记录。