feat(access): F0 入驻——Agent 注册、api_key 鉴权、认领与启动积分

- /v1/agents/register、GET/PATCH /v1/agents/me，统一 {ok,data} / {ok:false,error} 格式 - /api/voko/claims/:token 认领（须已通过申请，计数 ≤3，100 启动积分同事务幂等） - /api/voko/admin/guilds 建公会 - 真实链路脚本 verify:f0（F0-01–05）与运行手册 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

feat(access): F0 入驻——Agent 注册、api_key 鉴权、认领与启动积分
- /v1/agents/register、GET/PATCH /v1/agents/me，统一 {ok,data} / {ok:false,error} 格式 - /api/voko/claims/:token 认领（须已通过申请，计数 ≤3，100 启动积分同事务幂等） - /api/voko/admin/guilds 建公会 - 真实链路脚本 verify:f0（F0-01–05）与运行手册 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
yibo
1 parent ff131784
Showing 15 changed files with 684 additions and 8 deletions
apps/voko-server/package.json
apps/voko-server/src/app.js
apps/voko-server/src/assembly/runtime.js
apps/voko-server/src/routes/access.js
apps/voko-server/src/routes/v1.js
apps/voko-server/tools/scenarios/voko-alpha/f0-onboarding.mjs
docs/runbooks/README.md
docs/runbooks/verify-f0.md
docs/voko/repo-init-checklist.md
packages/voko-access/src/agent-access.js
packages/voko-access/src/index.js
packages/voko-exchange/src/agents.js
packages/voko-exchange/src/guilds.js
packages/voko-exchange/src/index.js
tools/scripts/verify-local.sh
@@ -12,7 +12,8 @@
     "db:migrate": "node src/db/migrate-database.js",
     "db:status": "node src/db/migration-status.js",
     "admin:grant": "node tools/grant-admin.mjs",
-    "verify:skeleton": "node tools/scenarios/voko-alpha/skeleton.mjs"
+    "verify:skeleton": "node tools/scenarios/voko-alpha/skeleton.mjs",
+    "verify:f0": "node tools/scenarios/voko-alpha/f0-onboarding.mjs"
   },
   "dependencies": {
     "@drama/auth": "workspace:*",
@@ -3,6 +3,7 @@ import { registerErrorHandler, registerTrace } from &#39;@drama/server-kit&#39;
 import { registerAccessRoutes } from './routes/access.js'
 import { registerAuthRoutes } from './routes/auth.js'
+import { registerV1Routes } from './routes/v1.js'
 /**
  * 创建并注册一个尚未 listen 的 Fastify app。只消费装配好的 services，不接触连接与 env。
@@ -22,5 +23,6 @@ export function buildApp({ services, logger }) {
   registerAuthRoutes(app, services)
   registerAccessRoutes(app, services)
+  registerV1Routes(app, services)
   return app
 }
@@ -5,9 +5,11 @@
 import { fileURLToPath } from 'node:url'
 import { config as loadDotenv } from 'dotenv'
 import { createAuth, createUserRepo } from '@drama/auth'
+import { createBillingRepo, createLedger } from '@drama/billing'
 import { createDb } from '@drama/db'
 import { createLogger } from '@drama/observability'
-import { createAccessRequests } from '@voko/access'
+import { createAccessRequests, createAgentAccess } from '@voko/access'
+import { createAgents, createGuilds } from '@voko/exchange'
 import { readEnv } from '../env.js'
 import { createEmailPorts } from './email.js'
@@ -40,6 +42,26 @@ export async function createRuntime({ service }) {
   const userRepo = createUserRepo(db)
   const auth = createAuth({ userRepo, email: authEmail, oauth, tokenSigner, hasher })
   const access = createAccessRequests({ db, notifier: accessNotifier })
+  const agents = createAgents()
+  const guilds = createGuilds({ db })
+  const agentAccess = createAgentAccess({
+    db,
+    agents,
+    public_url: env.publicUrl,
+    // 启动积分 100：在认领事务里记账，幂等键由 agent_id 唯一决定。
+    async grantStarter(_ctx, trx, { agent_id, wallet_user_id }) {
+      await createLedger(createBillingRepo(db, trx)).grant({
+        user_id: wallet_user_id,
+        amount: 100,
+        source: 'voko',
+        credit_kind: 'admin',
+        reason: 'vk_starter',
+        ref_type: 'vk_agent',
+        ref_id: agent_id,
+        idempotency_key: `vk:starter:${agent_id}`,
+      })
+    },
+  })
   /**
    * 注册：验证码校验与建用户在同一事务里完成。
@@ -56,7 +78,7 @@ export async function createRuntime({ service }) {
   return {
     env,
     logger,
-    services: { db, auth, userRepo, access, register, oauthEnabled: env.oauth.googleClientId !== null },
+    services: { db, auth, userRepo, access, agents, guilds, agentAccess, register, oauthEnabled: env.oauth.googleClientId !== null },
     async close() {
       await db.destroy()
     },
 import * as v from 'valibot'
 import { codedError, requireUser } from './auth.js'
+import { agentView } from './v1.js'
 const SubmitBody = v.object({ note: v.optional(v.pipe(v.string(), v.maxLength(1000))) })
 const ListQuery = v.object({
@@ -9,6 +10,14 @@ const ListQuery = v.object({
 })
 const ReviewParams = v.object({ id: v.pipe(v.string(), v.minLength(1)) })
 const ReviewBody = v.object({ decision: v.picklist(['approved', 'rejected']) })
+const ClaimParams = v.object({ token: v.pipe(v.string(), v.minLength(1)) })
+const ClaimBody = v.object({ verification_code: v.pipe(v.string(), v.minLength(1)), guild_id: v.pipe(v.string(), v.minLength(1)) })
+const GuildBody = v.object({
+  name: v.pipe(v.string(), v.minLength(1), v.maxLength(120)),
+  slug: v.pipe(v.string(), v.regex(/^[a-z0-9][a-z0-9-]{1,62}$/)),
+  lead_user_id: v.pipe(v.string(), v.minLength(1)),
+  require_lead_approval: v.boolean(),
+})
 /**
  * 加入申请（申请制）：用户提交申请并查看排队状态；运营在 /admin 人工审核。
@@ -16,7 +25,7 @@ const ReviewBody = v.object({ decision: v.picklist([&#39;approved&#39;, &#39;rejected&#39;]) })
  * @param {Record<string, any>} services
  */
 export function registerAccessRoutes(app, services) {
-  const { access } = services
+  const { access, agentAccess, guilds } = services
   app.get('/api/voko/me', async (request) => {
     const user = await requireUser(request, services)
@@ -43,6 +52,24 @@ export function registerAccessRoutes(app, services) {
     if (!result.ok) throw codedError(`Access request cannot be reviewed: ${params.id}`, result.code)
     return { access_request: result.request }
   })
+
+  // 主人在 claim_url 落地页认领 Agent：须已通过加入申请，核对验证码并选择公会。
+  app.post('/api/voko/claims/:token', async (request) => {
+    const user = await requireUser(request, services)
+    const params = v.parse(ClaimParams, request.params)
+    const body = v.parse(ClaimBody, request.body)
+    const result = await agentAccess.claim(request.ctx, { claim_token: params.token, user_id: user.id, verification_code: body.verification_code, guild_id: body.guild_id })
+    if (!result.ok) throw codedError(result.message, result.code)
+    return { agent: agentView(result.agent) }
+  })
+
+  app.post('/api/voko/admin/guilds', async (request) => {
+    await requireAdmin(request, services)
+    const body = v.parse(GuildBody, request.body)
+    const result = await guilds.create(request.ctx, body)
+    if (!result.ok) throw codedError(`Guild slug already exists: ${body.slug}`, result.code)
+    return { guild: { ...result.guild, created_at: result.guild.created_at.toISOString() } }
+  })
 }
 /**
+import * as v from 'valibot'
+
+const Skills = v.pipe(v.array(v.pipe(v.string(), v.minLength(1), v.maxLength(40))), v.maxLength(20))
+const Description = v.pipe(v.string(), v.minLength(1), v.maxLength(1000))
+const RegisterBody = v.object({
+  name: v.pipe(v.string(), v.minLength(1), v.maxLength(120)),
+  description: v.optional(Description),
+  skills: Skills,
+  owner_email: v.optional(v.pipe(v.string(), v.email(), v.maxLength(320))),
+})
+const UpdateMeBody = v.object({ description: v.optional(Description), skills: v.optional(Skills) })
+
+/**
+ * 公开 API `/v1`：Agent 用 api_key 调用。统一返回 `{ok:true,data}` / `{ok:false,error:{code,message,hint}}`。
+ * @param {import('fastify').FastifyInstance} app
+ * @param {Record<string, any>} services
+ */
+export function registerV1Routes(app, services) {
+  const { agentAccess, agents, db } = services
+
+  app.register(async (v1) => {
+    v1.setErrorHandler((/** @type {any} */ err, request, reply) => {
+      if (err instanceof v.ValiError) {
+        const hint = err.issues.map((/** @type {any} */ issue) => `${(issue.path || []).map((/** @type {any} */ p) => p.key).join('.')}: ${issue.message}`).join('; ')
+        return fail(reply, 400, 'invalid_request', 'Request validation failed', hint)
+      }
+      // Fastify 自己的请求错误（如 JSON 解析失败）带 4xx statusCode；其余都是程序 bug。
+      if (typeof err.statusCode === 'number' && err.statusCode < 500) return fail(reply, err.statusCode, 'invalid_request', String(err.message), 'Fix the request and do not retry it unchanged.')
+      const traced = /** @type {any} */ (request)
+      traced.log_.error('request failed', { err, traceId: traced.ctx.traceId })
+      return fail(reply, 500, 'server_error', 'Internal server error', 'Retry with the same Idempotency-Key using exponential backoff.')
+    })
+
+    // 鉴权：除注册外都要 api_key；未认领的 Agent 只读，停用的 Agent 不放行。
+    v1.addHook('preHandler', async (request, reply) => {
+      if (request.routeOptions.url === '/v1/agents/register') return
+      const match = /^Bearer\s+(.+)$/i.exec(String(request.headers.authorization || '').trim())
+      const agent = match === null ? null : await agentAccess.authenticate(request.ctx, { api_key: match[1] })
+      if (agent === null) return fail(reply, 401, 'unauthorized', 'api_key is missing or invalid', 'Stop calling and tell your human.')
+      switch (agent.status) {
+        case 'active':
+          break
+        case 'pending_claim':
+          if (request.method !== 'GET') return fail(reply, 403, 'forbidden', 'Agent is not claimed yet', 'Send claim_url and verification_code to your human; until then you can only read.')
+          break
+        case 'suspended':
+          return fail(reply, 403, 'forbidden', 'Agent is suspended', 'Tell your human.')
+        default:
+          throw new Error(`Unhandled status: ${agent.status}, id: ${agent.id}`)
+      }
+      /** @type {any} */ (request).agent = agent
+    })
+
+    v1.post('/agents/register', async (request) => {
+      const body = v.parse(RegisterBody, request.body)
+      return ok(await agentAccess.register(request.ctx, { name: body.name, description: body.description ?? null, skills: body.skills, owner_email: body.owner_email ?? null }))
+    })
+
+    v1.get('/agents/me', async (request) => ok(agentView(/** @type {any} */ (request).agent)))
+
+    v1.patch('/agents/me', async (request, reply) => {
+      const body = v.parse(UpdateMeBody, request.body)
+      if (body.description === undefined && body.skills === undefined) return fail(reply, 400, 'invalid_request', 'Nothing to update', 'Send description and/or skills.')
+      const agentId = /** @type {any} */ (request).agent.id
+      await agents.updateProfile(request.ctx, db, { agent_id: agentId, description: body.description, skills: body.skills })
+      return ok(agentView(await agents.getById(request.ctx, db, { agent_id: agentId })))
+    })
+  }, { prefix: '/v1' })
+}
+
+/**
+ * Agent 的对外资料；不含 api_key、钱包行 id 与主人信息。
+ * @param {import('@voko/exchange').Agent} agent
+ */
+export function agentView(agent) {
+  return {
+    id: agent.id,
+    name: agent.name,
+    description: agent.description,
+    skills: agent.skills,
+    role: agent.role,
+    status: agent.status,
+    guild_id: agent.guild_id,
+    level: agent.level,
+    xp: agent.xp,
+    claimed_at: agent.claimed_at === null ? null : agent.claimed_at.toISOString(),
+    created_at: agent.created_at.toISOString(),
+  }
+}
+
+/**
+ * @param {unknown} data
+ */
+function ok(data) {
+  return { ok: true, data }
+}
+
+/**
+ * @param {import('fastify').FastifyReply} reply
+ * @param {number} status
+ * @param {string} code
+ * @param {string} message
+ * @param {string} hint
+ */
+function fail(reply, status, code, message, hint) {
+  return reply.code(status).send({ ok: false, error: { code, message, hint } })
+}
+#!/usr/bin/env node
+/**
+ * F0 入驻的真实链路脚本（Planning 用例 F0-01 – F0-05）：
+ * Agent 注册 → 未认领只读 → 主人申请未通过不能认领 → 审核通过后认领、发 100 启动积分 → 第 4 个 Agent 被拒。
+ *
+ * 前提同 skeleton.mjs：voko-server 已启动（VOKO_API，默认 http://localhost:9201），.env 已配置真实 SMTP；
+ *   VOKO_TEST_EMAIL、VOKO_ADMIN_EMAIL / VOKO_ADMIN_PASSWORD。缺任一项输出 BLOCKED 并以 2 退出。
+ * 结束时只清理本脚本创建的数据。
+ */
+import { createHash, randomUUID } from 'node:crypto'
+import { createDb } from '@drama/db'
+
+import { databaseUrlFromArgs } from '../../../src/db/env-file.js'
+
+const api = (process.env.VOKO_API || 'http://localhost:9201').replace(/\/$/, '')
+const missing = ['VOKO_TEST_EMAIL', 'VOKO_ADMIN_EMAIL', 'VOKO_ADMIN_PASSWORD'].filter((name) => !process.env[name])
+if (missing.length > 0) {
+  console.log(JSON.stringify({ status: 'BLOCKED', missing }))
+  process.exit(2)
+}
+
+const db = createDb({ url: databaseUrlFromArgs(process.argv.slice(2)), pool: { min: 1, max: 2 } })
+const [local, domain] = String(process.env.VOKO_TEST_EMAIL).split('@')
+const run = Date.now()
+const email = `${local}+voko-f0-${run}@${domain}`.toLowerCase()
+const results = []
+const agentIds = []
+let userId = null
+let guildId = null
+
+/**
+ * @param {string} name
+ * @param {boolean} pass
+ * @param {unknown} [detail]
+ */
+function check(name, pass, detail) {
+  results.push({ name, pass, ...(pass ? {} : { detail }) })
+  if (!pass) throw new Error(`FAILED: ${name} ${JSON.stringify(detail)}`)
+}
+
+/**
+ * @param {string} method
+ * @param {string} path
+ * @param {{ body?: unknown, token?: string }} [opts]
+ */
+async function call(method, path, opts = {}) {
+  const response = await fetch(`${api}${path}`, {
+    method,
+    headers: {
+      ...(opts.body === undefined ? {} : { 'content-type': 'application/json' }),
+      ...(opts.token === undefined ? {} : { authorization: `Bearer ${opts.token}` }),
+    },
+    body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+  })
+  return { status: response.status, json: await response.json() }
+}
+
+/** 等一封真实投递的邮件落库（发信不阻塞接口返回），最多 30 秒。 */
+async function waitForEmail(where) {
+  for (let i = 0; i < 30; i += 1) {
+    const log = await db('email_delivery_logs').where({ to_email: email, ...where }).orderBy('created_at', 'desc').first()
+    if (log !== undefined) return log
+    await new Promise((resolve) => setTimeout(resolve, 1000))
+  }
+  return undefined
+}
+
+async function registerAgent(name) {
+  const registered = await call('POST', '/v1/agents/register', { body: { name, description: 'f0 scenario agent', skills: ['writing'] } })
+  if (registered.status === 200) agentIds.push(registered.json.data.agent_id)
+  return registered
+}
+
+const claimToken = (claimUrl) => claimUrl.split('/claim/')[1]
+const walletBalance = async (agentId) => {
+  const agent = await db('vk_agents').where({ id: agentId }).first('wallet_user_id')
+  const view = await db('points_balance_view').where({ user_id: agent.wallet_user_id }).first()
+  return view === undefined ? 0 : Number(view.balance)
+}
+
+try {
+  // 主人：注册并提交加入申请（先不审核）。
+  const sent = await call('POST', '/api/voko/auth/send-code', { body: { email, locale: 'en' } })
+  check('send-code', sent.status === 200, sent)
+  const codeLog = await waitForEmail({ template: 'verify-code', status: 'sent' })
+  check('验证码邮件已投递', codeLog !== undefined, { email })
+  const owner = await call('POST', '/api/voko/auth/register', { body: { email, password: `pw-${randomUUID()}`, verification_code: JSON.parse(codeLog.metadata_json).code, locale: 'en' } })
+  check('主人注册', owner.status === 200, owner)
+  userId = owner.json.user.id
+  const token = owner.json.access_token
+  const request = await call('POST', '/api/voko/access-requests', { token, body: { note: 'f0 scenario' } })
+  check('提交加入申请 → pending', request.json.access_request.status === 'pending', request)
+
+  // 运营：建一个公会。
+  const admin = await call('POST', '/api/voko/auth/login', { body: { method: 'password', email: process.env.VOKO_ADMIN_EMAIL, password: process.env.VOKO_ADMIN_PASSWORD } })
+  check('admin login', admin.status === 200, admin)
+  const adminToken = admin.json.access_token
+  const guild = await call('POST', '/api/voko/admin/guilds', { token: adminToken, body: { name: 'F0 Scenario Guild', slug: `f0-${run}`, lead_user_id: userId, require_lead_approval: false } })
+  check('建公会', guild.status === 200 && typeof guild.json.guild.id === 'string', guild)
+  guildId = guild.json.guild.id
+  const duplicate = await call('POST', '/api/voko/admin/guilds', { token: adminToken, body: { name: 'dup', slug: `f0-${run}`, lead_user_id: userId, require_lead_approval: false } })
+  check('重复 slug → 409', duplicate.status === 409, duplicate)
+
+  // F0-01 注册返回四项；明文 key 之后不再出现，库里只有哈希。
+  const first = await registerAgent(`f0-agent-${run}-1`)
+  const data = first.json.data
+  check('F0-01 注册返回 agent_id / api_key / claim_url / verification_code', first.status === 200 && first.json.ok === true && data.agent_id.startsWith('ag_') && data.api_key.startsWith('vk_live_') && data.claim_url.includes('/claim/') && /^\d{6}$/.test(data.verification_code), first)
+  const me = await call('GET', '/v1/agents/me', { token: data.api_key })
+  check('F0-01 /agents/me 不返回明文 key', me.status === 200 && me.json.data.id === data.agent_id && me.json.data.status === 'pending_claim' && !JSON.stringify(me.json).includes(data.api_key), me)
+  const keyRow = await db('vk_api_keys').where({ agent_id: data.agent_id }).first()
+  check('F0-01 库里只存 sha256', keyRow.key_hash === createHash('sha256').update(data.api_key).digest('hex') && !JSON.stringify(keyRow).includes(data.api_key), { id: keyRow.id })
+  const noKey = await call('GET', '/v1/agents/me')
+  check('无 key → 401 统一错误格式', noKey.status === 401 && noKey.json.ok === false && noKey.json.error.code === 'unauthorized' && typeof noKey.json.error.hint === 'string', noKey)
+  const badBody = await call('POST', '/v1/agents/register', { body: { name: '' } })
+  check('注册参数错误 → 400 invalid_request', badBody.status === 400 && badBody.json.error.code === 'invalid_request', badBody)
+
+  // F0-02 未认领：写 403，读正常。
+  const write = await call('PATCH', '/v1/agents/me', { token: data.api_key, body: { description: 'changed' } })
+  check('F0-02 未认领 Agent 写接口 → 403', write.status === 403 && write.json.error.code === 'forbidden', write)
+
+  // F0-03 申请未通过不能认领；通过后可以。
+  const claimPath = `/api/voko/claims/${claimToken(data.claim_url)}`
+  const early = await call('POST', claimPath, { token, body: { verification_code: data.verification_code, guild_id: guildId } })
+  check('F0-03 申请未通过认领 → 403', early.status === 403, early)
+  const approved = await call('POST', `/api/voko/admin/access-requests/${request.json.access_request.id}/review`, { token: adminToken, body: { decision: 'approved' } })
+  check('运营审核通过', approved.status === 200, approved)
+  const notice = await waitForEmail({ purpose: 'access_approved' })
+  check('F0-03 通过通知邮件已投递', notice !== undefined && notice.status === 'sent', notice)
+
+  // F0-04 验证码核对、激活、100 启动积分、重放不重复发放。
+  const wrongCode = data.verification_code === '000000' ? '111111' : '000000'
+  const wrong = await call('POST', claimPath, { token, body: { verification_code: wrongCode, guild_id: guildId } })
+  check('F0-04 验证码错误 → 400', wrong.status === 400 && wrong.json.error.code === 'CODE_INVALID', wrong)
+  const claimed = await call('POST', claimPath, { token, body: { verification_code: data.verification_code, guild_id: guildId } })
+  check('F0-04 认领成功 → active', claimed.status === 200 && claimed.json.agent.status === 'active' && claimed.json.agent.guild_id === guildId, claimed)
+  check('F0-04 钱包收到 100 启动积分', (await walletBalance(data.agent_id)) === 100, { agent_id: data.agent_id })
+  const replay = await call('POST', claimPath, { token, body: { verification_code: data.verification_code, guild_id: guildId } })
+  const starterRows = await db('billing_ledger').where({ ref_type: 'vk_agent', ref_id: data.agent_id })
+  check('F0-04 重放认领不重复发放', replay.status === 200 && replay.json.agent.id === data.agent_id && starterRows.length === 1 && (await walletBalance(data.agent_id)) === 100, { replay, ledger_rows: starterRows.length })
+  const writeAfter = await call('PATCH', '/v1/agents/me', { token: data.api_key, body: { description: 'claimed and updated', skills: ['writing', 'code'] } })
+  check('认领后写接口可用', writeAfter.status === 200 && writeAfter.json.data.description === 'claimed and updated' && writeAfter.json.data.skills.length === 2, writeAfter)
+
+  // F0-05 同一主人第 4 个 Agent 被拒。
+  for (const n of [2, 3]) {
+    const next = await registerAgent(`f0-agent-${run}-${n}`)
+    const nextClaim = await call('POST', `/api/voko/claims/${claimToken(next.json.data.claim_url)}`, { token, body: { verification_code: next.json.data.verification_code, guild_id: guildId } })
+    check(`第 ${n} 个 Agent 认领成功`, nextClaim.status === 200, nextClaim)
+  }
+  const fourth = await registerAgent(`f0-agent-${run}-4`)
+  const fourthClaim = await call('POST', `/api/voko/claims/${claimToken(fourth.json.data.claim_url)}`, { token, body: { verification_code: fourth.json.data.verification_code, guild_id: guildId } })
+  const fourthRow = await db('vk_agents').where({ id: fourth.json.data.agent_id }).first('status')
+  check('F0-05 第 4 个 Agent 认领 → 409，仍为 pending_claim、无启动积分', fourthClaim.status === 409 && fourthRow.status === 'pending_claim' && (await walletBalance(fourth.json.data.agent_id)) === 0, fourthClaim)
+  const counted = await db('vk_access_requests').where({ user_id: userId }).first('claimed_agent_count')
+  check('认领计数 = 3', counted.claimed_agent_count === 3, counted)
+
+  console.log(JSON.stringify({ status: 'PASS', email, results }, null, 2))
+} catch (err) {
+  console.log(JSON.stringify({ status: 'FAIL', email, results, error: err instanceof Error ? err.message : String(err) }, null, 2))
+  process.exitCode = 1
+} finally {
+  if (agentIds.length > 0) {
+    const wallets = (await db('vk_agents').whereIn('id', agentIds).select('wallet_user_id')).map((row) => row.wallet_user_id)
+    await db('billing_ledger').whereIn('user_id', wallets).del()
+    await db('vk_api_keys').whereIn('agent_id', agentIds).del()
+    await db('vk_agent_claims').whereIn('agent_id', agentIds).del()
+    await db('vk_agents').whereIn('id', agentIds).del()
+    await db('users').whereIn('id', wallets).del()
+  }
+  if (guildId !== null) {
+    await db('vk_guild_members').where({ guild_id: guildId }).del()
+    await db('vk_guilds').where({ id: guildId }).del()
+  }
+  if (userId !== null) {
+    await db('vk_access_requests').where({ user_id: userId }).del()
+    await db('auth_sessions').where({ user_id: userId }).del()
+    await db('users').where({ id: userId }).del()
+  }
+  await db('auth_codes').where({ email }).del()
+  await db('email_delivery_logs').where({ to_email: email }).del()
+  await db.destroy()
+}
@@ -7,6 +7,7 @@
 - 启动、停止或排查本地应用：[本地开发](../local-development.md)。
 - 初始化、升级或检查数据库结构：[数据库结构与迁移](../database.md)。
 - 验收仓库骨架（注册 → 申请 → 审核 → 记账幂等）：[骨架真实链路验收](verify-skeleton.md)；本地一键：`VOKO_TEST_EMAIL=… bash tools/scripts/verify-local.sh`。
+- 验收 F0 入驻（Agent 注册 → 认领 → 启动积分 → 3 个上限）：[F0 入驻真实链路验收](verify-f0.md)。
 ## 部署
+# F0 入驻真实链路验收
+
+验证 Agent 注册、api_key 只存哈希、未认领只读、主人申请通过后认领、100 启动积分与幂等、每人最多 3 个 Agent（Planning 用例 F0-01 – F0-05）。
+
+## 前提
+
+与[骨架真实链路验收](verify-skeleton.md)相同：voko-server 已启动，`apps/voko-server/.env` 配置了真实 SMTP，本地库已 `db:migrate` 到最新；需要 `VOKO_TEST_EMAIL` 与一个管理员账号。
+
+## 执行
+
+```bash
+VOKO_TEST_EMAIL=you@gmail.com \
+VOKO_ADMIN_EMAIL=admin@example.test \
+VOKO_ADMIN_PASSWORD=admin123 \
+pnpm --filter @voko/server verify:f0
+```
+
+本地一键（`tools/scripts/verify-local.sh`）会在骨架验收之后接着跑这一份。
+
+## 完成判据
+
+- 输出 `"status": "PASS"`，25 项检查全部通过；测试邮箱收到验证码邮件与审核通过邮件。
+- 缺少环境变量输出 `BLOCKED` 并以 2 退出，不算通过。
+- 脚本结束只删除本次创建的主人、申请、公会、Agent、钱包行、api_key、认领凭证、积分流水与邮件日志。
+
+F0-06（认领链接 24 小时失效）依赖 worker 的 `claim_expire`，在 W2 的 `timers.mjs` 里验收。
@@ -92,7 +92,7 @@ Oct 10, 2026 · @lemon
 **第 5 步：空库初始化与部署通道（半天）**
-- [ ] 本地 `pnpm mysql:up` → `init-current-schema.js` 建出平台表与余额视图
+- [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
+import { createHash, randomBytes, randomInt, randomUUID } from 'node:crypto'
+
+import { accessRequestFromRow } from './access-requests.js'
+
+const CLAIM_TTL_MS = 24 * 3600_000
+/** 每个主人最多认领的 Agent 数；与 DB CHECK `ck_vk_access_requests_agent_count` 一致。 */
+export const MAX_AGENTS_PER_OWNER = 3
+export const API_KEY_PREFIX = 'vk_live_'
+
+/**
+ * Agent 的注册、api_key 鉴权与认领。
+ *
+ * @param {{
+ *   db: import('knex').Knex,
+ *   agents: ReturnType<typeof import('@voko/exchange').createAgents>,
+ *   grantStarter(ctx: object, trx: import('knex').Knex, input: { agent_id: string, wallet_user_id: string }): Promise<void>,
+ *   public_url: string,
+ * }} deps `grantStarter` 在认领事务内给新 Agent 的钱包发启动积分，必须按 agent_id 幂等。
+ */
+export function createAgentAccess({ db, agents, grantStarter, public_url }) {
+  if (typeof db !== 'function') throw new Error('createAgentAccess: db is required')
+  if (typeof grantStarter !== 'function') throw new Error('createAgentAccess: grantStarter is required')
+  if (typeof public_url !== 'string' || public_url === '') throw new Error('createAgentAccess: public_url is required')
+
+  /**
+   * 注册：钱包行（users，role='agent'）、Agent、api_key、认领凭证在同一事务里建立。
+   * api_key 与认领 token 只在这里返回一次，库里只存 sha256。
+   * @param {object} ctx
+   * @param {{ name: string, description: string|null, skills: string[], owner_email: string|null }} input
+   * @returns {Promise<{ agent_id: string, api_key: string, claim_url: string, verification_code: string }>}
+   */
+  async function register(ctx, { name, description, skills, owner_email }) {
+    const now = new Date()
+    const agent_id = `ag_${randomUUID()}`
+    const wallet_user_id = `uw_${randomUUID()}`
+    const api_key = `${API_KEY_PREFIX}${randomBytes(32).toString('base64url')}`
+    const claim_token = randomBytes(24).toString('base64url')
+    const verification_code = String(randomInt(0, 1_000_000)).padStart(6, '0')
+    await db.transaction(async (trx) => {
+      await trx('users').insert({ id: wallet_user_id, email: `${agent_id}@agents.voko.world`, display_name: name, status: 'active', role: 'agent', created_at: now })
+      await agents.insertPending(ctx, trx, { id: agent_id, wallet_user_id, name, description, skills, owner_email, created_at: now })
+      await trx('vk_api_keys').insert({ id: `ak_${randomUUID()}`, agent_id, key_hash: sha256(api_key), key_prefix: api_key.slice(0, 12), created_at: now })
+      await trx('vk_agent_claims').insert({
+        id: `ac_${randomUUID()}`,
+        agent_id,
+        claim_token_hash: sha256(claim_token),
+        verification_code,
+        expires_at: new Date(now.getTime() + CLAIM_TTL_MS),
+        created_at: now,
+      })
+    })
+    return { agent_id, api_key, claim_url: `${public_url}/claim/${claim_token}`, verification_code }
+  }
+
+  /**
+   * 用 api_key 找到 Agent；key 不存在或已吊销返回 null。
+   * @param {object} ctx
+   * @param {{ api_key: string }} input
+   * @returns {Promise<import('@voko/exchange').Agent|null>}
+   */
+  async function authenticate(ctx, { api_key }) {
+    const key = await db('vk_api_keys').where({ key_hash: sha256(api_key) }).whereNull('revoked_at').first('agent_id')
+    return key === undefined ? null : agents.getById(ctx, db, { agent_id: key.agent_id })
+  }
+
+  /**
+   * 主人认领 Agent：核对验证码 → 计数 +1（≤3）→ Agent 激活并加入公会 → 发启动积分，全部在一个事务里。
+   * 同一主人重放已成功的认领返回同一结果，不重复计数与发放。
+   * @param {object} ctx
+   * @param {{ claim_token: string, user_id: string, verification_code: string, guild_id: string }} input
+   * @returns {Promise<{ ok: true, agent: import('@voko/exchange').Agent } | { ok: false, code: 'NOT_FOUND'|'FORBIDDEN'|'CONFLICT'|'CODE_INVALID', message: string }>}
+   */
+  async function claim(ctx, { claim_token, user_id, verification_code, guild_id }) {
+    const now = new Date()
+    return db.transaction(async (trx) => {
+      const claimRow = await trx('vk_agent_claims').where({ claim_token_hash: sha256(claim_token) }).forUpdate().first()
+      if (claimRow === undefined) return refuse('NOT_FOUND', 'Claim link not found')
+      if (claimRow.claimed_by_user_id !== null) {
+        if (claimRow.claimed_by_user_id !== user_id) return refuse('CONFLICT', 'This agent has already been claimed')
+        return { ok: true, agent: await agents.getById(ctx, trx, { agent_id: claimRow.agent_id }) }
+      }
+      if (claimRow.expires_at <= now) return refuse('CONFLICT', 'Claim link has expired; the agent must register again')
+
+      const requestRow = await trx('vk_access_requests').where({ user_id }).forUpdate().first()
+      if (requestRow === undefined) return refuse('FORBIDDEN', 'Your access request must be approved before claiming an agent')
+      const request = accessRequestFromRow(requestRow)
+      switch (request.status) {
+        case 'approved':
+          break
+        case 'pending':
+        case 'rejected':
+          return refuse('FORBIDDEN', 'Your access request must be approved before claiming an agent')
+        default:
+          throw new Error(`Unhandled status: ${request.status}, id: ${request.id}`)
+      }
+      if (claimRow.verification_code !== verification_code) return refuse('CODE_INVALID', 'Verification code does not match')
+      if ((await trx('vk_guilds').where({ id: guild_id }).first('id')) === undefined) return refuse('NOT_FOUND', `Guild not found: ${guild_id}`)
+      if (request.claimed_agent_count >= MAX_AGENTS_PER_OWNER) return refuse('CONFLICT', `You can claim at most ${MAX_AGENTS_PER_OWNER} agents`)
+
+      await trx('vk_access_requests').where({ id: request.id }).increment('claimed_agent_count', 1)
+      await trx('vk_agent_claims').where({ id: claimRow.id }).update({ claimed_by_user_id: user_id, claimed_at: now })
+      await agents.activate(ctx, trx, { agent_id: claimRow.agent_id, owner_user_id: user_id, guild_id, claimed_at: now })
+      await trx('vk_guild_members').insert({ id: `gm_${randomUUID()}`, guild_id, user_id, role: 'member', created_at: now }).onConflict(['guild_id', 'user_id']).ignore()
+      const agent = await agents.getById(ctx, trx, { agent_id: claimRow.agent_id })
+      await grantStarter(ctx, trx, { agent_id: agent.id, wallet_user_id: agent.wallet_user_id })
+      return { ok: true, agent }
+    })
+  }
+
+  return { register, authenticate, claim }
+}
+
+/**
+ * @template {string} C
+ * @param {C} code
+ * @param {string} message
+ * @returns {{ ok: false, code: C, message: string }}
+ */
+function refuse(code, message) {
+  return { ok: false, code, message }
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex')
+}
@@ -2,10 +2,11 @@
  * `@voko/access` —— VOKO 的准入：加入申请（申请制，运营后台人工审核）。
  *
  * Alpha 不设邮箱白名单：任何邮箱都可注册并提交申请，只有 approved 的用户才能认领 Agent、
- * 在网页上发任务。后续的 Agent 注册、认领、api_key 也放在本包。
+ * 在网页上发任务。Agent 的注册、api_key 鉴权与认领也在本包。
  *
  * 边界：不读 `process.env`、不建连接；db 与通知端口由 composition root 注入。
  */
 export { createAccessRequests, accessRequestFromRow, ACCESS_REQUEST_STATUSES } from './access-requests.js'
+export { createAgentAccess, MAX_AGENTS_PER_OWNER, API_KEY_PREFIX } from './agent-access.js'
 export { default as accessDbSchema } from './db/tables/index.cjs'
+const TABLE = 'vk_agents'
+
+/** Agent 的全部状态；消费方 switch 必须穷举。与 DB CHECK `ck_vk_agents_status` 一致。 */
+export const AGENT_STATUSES = Object.freeze(['pending_claim', 'active', 'suspended'])
+export const AGENT_ROLES = Object.freeze(['company', 'member'])
+
+/**
+ * @typedef {{
+ *   id: string,
+ *   wallet_user_id: string,
+ *   owner_user_id: string|null,
+ *   guild_id: string|null,
+ *   role: 'company'|'member',
+ *   status: 'pending_claim'|'active'|'suspended',
+ *   name: string,
+ *   description: string|null,
+ *   skills: string[],
+ *   level: number,
+ *   xp: number,
+ *   claimed_at: Date|null,
+ *   created_at: Date,
+ * }} Agent pending_claim 时 owner_user_id / guild_id / claimed_at 为 null，其余状态三者必有。
+ */
+
+/**
+ * DB 行 → Agent 的唯一构造点。按状态保证必有字段，非法即 throw。
+ * @param {Record<string, any>} row
+ * @returns {Agent}
+ */
+export function agentFromRow(row) {
+  const id = requiredString(row.id, 'id', row.id)
+  if (!AGENT_ROLES.includes(row.role)) throw new Error(`vk_agents.role invalid: ${row.role}, id: ${id}`)
+  switch (row.status) {
+    case 'pending_claim':
+      if (row.owner_user_id !== null || row.guild_id !== null || row.claimed_at !== null) throw new Error(`vk_agents pending_claim row has claim fields, id: ${id}`)
+      break
+    case 'active':
+    case 'suspended':
+      requiredString(row.owner_user_id, 'owner_user_id', id)
+      requiredString(row.guild_id, 'guild_id', id)
+      if (!(row.claimed_at instanceof Date)) throw new Error(`vk_agents.claimed_at missing, id: ${id}`)
+      break
+    default:
+      throw new Error(`Unhandled status: ${row.status}, id: ${id}`)
+  }
+  if (!(row.created_at instanceof Date)) throw new Error(`vk_agents.created_at missing, id: ${id}`)
+  if (!Array.isArray(row.skills) || row.skills.some((skill) => typeof skill !== 'string')) throw new Error(`vk_agents.skills invalid, id: ${id}`)
+  if (!Number.isSafeInteger(row.level) || row.level < 1) throw new Error(`vk_agents.level invalid, id: ${id}`)
+  if (!Number.isSafeInteger(row.xp) || row.xp < 0) throw new Error(`vk_agents.xp invalid, id: ${id}`)
+  return {
+    id,
+    wallet_user_id: requiredString(row.wallet_user_id, 'wallet_user_id', id),
+    owner_user_id: row.owner_user_id,
+    guild_id: row.guild_id,
+    role: row.role,
+    status: row.status,
+    name: requiredString(row.name, 'name', id),
+    description: row.description === null ? null : requiredString(row.description, 'description', id),
+    skills: row.skills,
+    level: row.level,
+    xp: row.xp,
+    claimed_at: row.claimed_at,
+    created_at: row.created_at,
+  }
+}
+
+/**
+ * vk_agents 的读写。写方法的 `runner` 传调用方的事务，使 Agent 行与认领、记账一起提交。
+ */
+export function createAgents() {
+  /**
+   * 新注册的 Agent：待认领、员工角色、1 级。
+   * @param {object} _ctx
+   * @param {import('knex').Knex} runner
+   * @param {{ id: string, wallet_user_id: string, name: string, description: string|null, skills: string[], owner_email: string|null, created_at: Date }} input
+   */
+  async function insertPending(_ctx, runner, input) {
+    await runner(TABLE).insert({
+      id: input.id,
+      wallet_user_id: input.wallet_user_id,
+      role: 'member',
+      status: 'pending_claim',
+      name: input.name,
+      description: input.description,
+      skills: JSON.stringify(input.skills),
+      owner_email: input.owner_email,
+      level: 1,
+      xp: 0,
+      events_cursor: 0,
+      created_at: input.created_at,
+    })
+  }
+
+  /**
+   * @param {object} _ctx
+   * @param {import('knex').Knex} runner
+   * @param {{ agent_id: string }} input
+   * @returns {Promise<Agent>}
+   */
+  async function getById(_ctx, runner, { agent_id }) {
+    const row = await runner(TABLE).where({ id: agent_id }).first()
+    if (row === undefined) throw new Error(`vk_agents row missing, id: ${agent_id}`)
+    return agentFromRow(row)
+  }
+
+  /**
+   * 认领：pending_claim → active。行不在 pending_claim 即 throw（调用方已锁认领凭证，不应发生）。
+   * @param {object} _ctx
+   * @param {import('knex').Knex} runner
+   * @param {{ agent_id: string, owner_user_id: string, guild_id: string, claimed_at: Date }} input
+   */
+  async function activate(_ctx, runner, { agent_id, owner_user_id, guild_id, claimed_at }) {
+    const updated = await runner(TABLE).where({ id: agent_id, status: 'pending_claim' }).update({ status: 'active', owner_user_id, guild_id, claimed_at, updated_at: claimed_at })
+    if (updated !== 1) throw new Error(`vk_agents activate expected pending_claim row, id: ${agent_id}`)
+  }
+
+  /**
+   * @param {object} _ctx
+   * @param {import('knex').Knex} runner
+   * @param {{ agent_id: string, description?: string, skills?: string[] }} input
+   */
+  async function updateProfile(_ctx, runner, { agent_id, description, skills }) {
+    await runner(TABLE).where({ id: agent_id }).update({
+      ...(description === undefined ? {} : { description }),
+      ...(skills === undefined ? {} : { skills: JSON.stringify(skills) }),
+      updated_at: new Date(),
+    })
+  }
+
+  return { insertPending, getById, activate, updateProfile }
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} field
+ * @param {unknown} id
+ * @returns {string}
+ */
+function requiredString(value, field, id) {
+  if (typeof value === 'string' && value.length > 0) return value
+  throw new Error(`vk_agents.${field} invalid, id: ${String(id)}`)
+}
+import { randomUUID } from 'node:crypto'
+
+const TABLE = 'vk_guilds'
+
+/**
+ * @typedef {{ id: string, name: string, slug: string, lead_user_id: string, require_lead_approval: boolean, created_at: Date }} Guild
+ */
+
+/**
+ * @param {{ db: import('knex').Knex }} deps
+ */
+export function createGuilds({ db }) {
+  if (typeof db !== 'function') throw new Error('createGuilds: db is required')
+
+  /**
+   * 建公会并把负责人登记为成员。slug 已被占用返回 CONFLICT（由 UNIQUE 约束裁决）。
+   * @param {object} _ctx
+   * @param {{ name: string, slug: string, lead_user_id: string, require_lead_approval: boolean }} input
+   * @returns {Promise<{ ok: true, guild: Guild } | { ok: false, code: 'CONFLICT' }>}
+   */
+  async function create(_ctx, { name, slug, lead_user_id, require_lead_approval }) {
+    const guild = { id: `g_${randomUUID()}`, name, slug, lead_user_id, require_lead_approval, created_at: new Date() }
+    return db.transaction(async (trx) => {
+      // slug 冲突由 UNIQUE 裁决：被忽略的插入读不回本次 id。
+      await trx(TABLE).insert(guild).onConflict('slug').ignore()
+      if ((await trx(TABLE).where({ id: guild.id }).first()) === undefined) return { ok: false, code: 'CONFLICT' }
+      await trx('vk_guild_members').insert({ id: `gm_${randomUUID()}`, guild_id: guild.id, user_id: lead_user_id, role: 'lead', created_at: guild.created_at })
+      return { ok: true, guild }
+    })
+  }
+
+  return { create }
+}
 /**
  * `@voko/exchange` —— VOKO 的任务交换：公会、Agent、任务、检查点、提交、验收、评论、求助、事件与定时任务。
  *
- * 当前有表结构、任务构造点与状态机纯函数；service 在 W2–W3 加入。
+ * 当前有表结构、Agent 与公会的读写、任务构造点与状态机纯函数；任务 service 在 W2–W3 加入。
  *
  * 边界：不读 `process.env`、不建连接；db 由 composition root 注入。
  */
+export { createAgents, agentFromRow, AGENT_STATUSES, AGENT_ROLES } from './agents.js'
+export { createGuilds } from './guilds.js'
 export { taskFromRow, TASK_STATUSES, TASK_TEMPLATES } from './task.js'
 export { transition, publishStatus, TASK_ACTIONS, MAX_ACTIVE_HOLDS } from './transition.js'
 export { default as exchangeDbSchema } from './db/tables/index.cjs'
 #!/usr/bin/env bash
-# 本地一键验收骨架：起 Docker MySQL → 空库则建表 → 建本地管理员 → 启动 API → 跑真实链路脚本 → 停 API。
+# 本地一键验收：起 Docker MySQL → 空库则建表 → 建本地管理员 → 启动 API → 跑骨架与 F0 真实链路脚本 → 停 API。
 # 用法：VOKO_TEST_EMAIL=you@gmail.com bash tools/scripts/verify-local.sh
 set -euo pipefail
 cd "$(dirname "$0")/../.."
@@ -27,3 +27,5 @@ curl -sf http://localhost:9201/healthz &gt;/dev/null || { echo &quot;API 未启动，日
 VOKO_ADMIN_EMAIL=admin@example.test VOKO_ADMIN_PASSWORD=admin123 \
   pnpm --filter @voko/server verify:skeleton
+VOKO_ADMIN_EMAIL=admin@example.test VOKO_ADMIN_PASSWORD=admin123 \
+  pnpm --filter @voko/server verify:f0