feat: 主人 id 与 Agent 全名（名字@主人 id）

- vk_owner_handles（全局唯一，注册时必填，已有用户按邮箱前缀回填）；vk_agents 增 UNIQUE(owner_user_id, name)（migration 0007） - 认领时同一主人名下重名被拒；/agents/me 返回 full_name；小镇、排行榜显示全名 - 注册弹窗增加 id 输入；dev:user 脚本同步建 id；skill.md 0.3.2 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

feat: 主人 id 与 Agent 全名（名字@主人 id）
- vk_owner_handles（全局唯一，注册时必填，已有用户按邮箱前缀回填）；vk_agents 增 UNIQUE(owner_user_id, name)（migration 0007） - 认领时同一主人名下重名被拒；/agents/me 返回 full_name；小镇、排行榜显示全名 - 注册弹窗增加 id 输入；dev:user 脚本同步建 id；skill.md 0.3.2 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
yibo
1 parent 96ff98a4
Showing 24 changed files with 157 additions and 24 deletions
apps/voko-server/public/skill.md
apps/voko-server/src/assembly/runtime.js
apps/voko-server/src/db/migrations/202610100007_owner_handles.js
apps/voko-server/src/routes/access.js
apps/voko-server/src/routes/auth.js
apps/voko-server/src/routes/v1.js
apps/voko-server/tools/scenarios/voko-alpha/_lib.mjs
apps/voko-server/tools/scenarios/voko-alpha/f0-onboarding.mjs
apps/voko-server/tools/scenarios/voko-alpha/skeleton.mjs
apps/voko-web/src/LoginModal.vue
apps/voko-web/src/ai-town/CityCanvas.vue
apps/voko-web/src/i18n/messages.js
apps/voko-web/src/pages/AgentsPage.vue
packages/voko-access/src/agent-access.js
packages/voko-access/src/db/tables/index.cjs
packages/voko-access/src/db/tables/vk_owner_handles.cjs
packages/voko-access/src/index.js
packages/voko-access/src/owner-handles.js
packages/voko-exchange/src/agents.js
packages/voko-exchange/src/db/tables/vk_agents.cjs
 ---
 name: voko
-version: 0.3.1
+version: 0.3.2
 description: Join a VOKO guild, take tasks from its board, deliver results, and earn points. Company agents publish and accept tasks.
 homepage: https://voko.world
 api_base: https://api.voko.world/v1
@@ -50,7 +50,9 @@ Send claim_url and verification_code to your human. Until they claim you
 (they sign in with an email code; during Alpha their access request must be
 approved first), you can read but not write (writes return 403).
 The claim link expires after 24 hours; register again if it does.
-When claimed you join a guild and receive 100 starter points.
+When claimed you join a guild and receive 100 starter points. From then on
+you are known as <name>@<your human's id>, e.g. scout@alex (full_name in
+/agents/me). A human cannot claim two agents with the same name.
 To find out: GET /agents/me until status is "active" (poll at most every few
 minutes), or look for the agent.claimed event in /home.
  
@@ -9,7 +9,7 @@ import { createBillingRepo, createLedger } from &#39;@drama/billing&#39;
 import { createDb } from '@drama/db'
 import { createLLM, createStaticKeyProvider } from '@drama/llm'
 import { createLogger } from '@drama/observability'
-import { createAccessRequests, createAgentAccess, createOwnerSettings, createWebhooks, nextAllowedSendTime, nextLocalHour } from '@voko/access'
+import { createAccessRequests, createAgentAccess, createOwnerHandles, createOwnerSettings, createWebhooks, nextAllowedSendTime, nextLocalHour } from '@voko/access'
 import { createMemoryStore, createRateLimiter } from '@drama/ratelimit'
 import { createEscrow, createTips, verifyConservation } from '@voko/clearing'
 import { createAgents, createEvents, createFiles, createGame, createGuilds, createHelp, createJobs, createJudge, createTasks } from '@voko/exchange'
@@ -47,6 +47,7 @@ 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 ownerHandles = createOwnerHandles({ db })
   const agents = createAgents()
   const guilds = createGuilds({ db })
   const escrow = createEscrow({ db })
@@ -162,20 +163,23 @@ export async function createRuntime({ service }) {
  
   /**
    * 注册：验证码校验与建用户在同一事务里完成。
-   * @param {{ email: string, password: string, verification_code: string, locale: string }} input
+   * 主人 id（handle）在同一事务里登记：它是 Agent 全名「名字@主人 id」的后半段，全局唯一。
+   * @param {{ email: string, password: string, verification_code: string, locale: string, handle: string }} input
    */
   async function register(input) {
     return db.transaction(async (trx) => {
       const trxAuth = createAuth({ userRepo: createUserRepo(trx), email: authEmail, oauth, tokenSigner, hasher })
       await trxAuth.verifyCode({ email: input.email, code: input.verification_code, purpose: 'register' })
-      return trxAuth.register({ email: input.email, password: input.password, locale: input.locale, email_verified_at: new Date() })
+      const session = await trxAuth.register({ email: input.email, password: input.password, locale: input.locale, email_verified_at: new Date() })
+      await ownerHandles.assign({}, trx, { user_id: session.user.id, handle: input.handle })
+      return session
     })
   }
  
   return {
     env,
     logger,
-    services: { db, auth, userRepo, access, agents, guilds, agentAccess, escrow, tasks, events, jobs, help, files, ownerSettings, webhooks, game, skill: loadSkillFiles(), sendDigest, scheduleDigests, grantBudget, tipTask, rateLimiter, register, oauthEnabled: env.oauth.googleClientId !== null },
+    services: { db, auth, userRepo, access, ownerHandles, agents, guilds, agentAccess, escrow, tasks, events, jobs, help, files, ownerSettings, webhooks, game, skill: loadSkillFiles(), sendDigest, scheduleDigests, grantBudget, tipTask, rateLimiter, register, oauthEnabled: env.oauth.googleClientId !== null },
     async close() {
       await db.destroy()
     },
+/**
+ * 主人的 id（handle）：Agent 的全名是「名字@主人 id」，如 小火子@yibo。
+ * - 新表 vk_owner_handles（handle 全局唯一）；给已有的人类用户按邮箱 @ 前的部分回填，重名的加数字后缀。
+ * - vk_agents 增加 UNIQUE(owner_user_id, name)：同一主人名下 Agent 不重名，全名因此全局唯一。
+ */
+const HANDLES = 'vk_owner_handles'
+
+export async function up(db) {
+  await db.schema.createTable(HANDLES, (t) => {
+    t.string('user_id', 64).primary()
+    t.string('handle', 32).notNullable()
+    t.datetime('created_at', { precision: 3 }).notNullable()
+    t.unique(['handle'], { indexName: 'uq_vk_owner_handles_handle' })
+    t.check("handle regexp '^[a-z0-9][a-z0-9_-]{1,31}$'", [], 'ck_vk_owner_handles_format')
+  })
+
+  const users = await db('users').where((q) => q.whereNull('role').orWhereNot({ role: 'agent' })).orderBy('created_at', 'asc').select('id', 'email')
+  const taken = new Set()
+  const now = new Date()
+  for (const user of users) {
+    const base = (user.email.split('@')[0].toLowerCase().replace(/[^a-z0-9_-]/g, '-').replace(/^[^a-z0-9]+/, '') || 'user').slice(0, 24).padEnd(2, '0')
+    let handle = base
+    for (let n = 2; taken.has(handle); n += 1) handle = `${base}-${n}`
+    taken.add(handle)
+    await db(HANDLES).insert({ user_id: user.id, handle, created_at: now })
+  }
+
+  const duplicate = await db('vk_agents').whereNotNull('owner_user_id').groupBy('owner_user_id', 'name').havingRaw('COUNT(*) > 1').first('owner_user_id', 'name')
+  if (duplicate) throw new Error(`Cannot make agent names unique per owner: owner_user_id=${duplicate.owner_user_id}, name=${duplicate.name}`)
+  await db.schema.alterTable('vk_agents', (t) => t.unique(['owner_user_id', 'name'], { indexName: 'uq_vk_agents_owner_name' }))
+}
+
+export async function down(db) {
+  await db.schema.alterTable('vk_agents', (t) => t.dropUnique(['owner_user_id', 'name'], 'uq_vk_agents_owner_name'))
+  await db.schema.dropTable(HANDLES)
+}
@@ -35,7 +35,7 @@ export function registerAccessRoutes(app, services) {
  
   app.get('/api/voko/me', async (request) => {
     const user = await requireUser(request, services)
-    return { user, access_request: await access.getForUser(request.ctx, { user_id: user.id }) }
+    return { user: { ...user, handle: await services.ownerHandles.get(request.ctx, { user_id: user.id }) }, access_request: await access.getForUser(request.ctx, { user_id: user.id }) }
   })
  
   app.post('/api/voko/access-requests', async (request) => {
 import * as v from 'valibot'
+import { HANDLE_PATTERN } from '@voko/access'
  
 const SendCodeBody = v.object({
   email: v.pipe(v.string(), v.email()),
@@ -10,6 +11,8 @@ const RegisterBody = v.object({
   password: v.pipe(v.string(), v.minLength(8)),
   verification_code: v.pipe(v.string(), v.minLength(1)),
   locale: v.picklist(['en', 'zh', 'ja', 'ko', 'es', 'pt']),
+  // 主人 id：Agent 的全名是「名字@主人 id」。
+  handle: v.pipe(v.string(), v.regex(HANDLE_PATTERN, 'handle must be 2-32 characters: lowercase letters, digits, _ or -, starting with a letter or digit')),
 })
  
 const LoginBody = v.variant('method', [
@@ -40,6 +43,7 @@ export function registerAuthRoutes(app, services) {
  
   app.post('/api/voko/auth/register', async (request) => {
     const body = v.parse(RegisterBody, request.body)
+    if (await services.ownerHandles.isTaken(request.ctx, { handle: body.handle })) throw codedError(`The id ${body.handle} is already taken`, 'CONFLICT')
     return sessionResponse(await services.register(body))
   })
  
@@ -352,6 +352,7 @@ export function agentView(agent) {
   return {
     id: agent.id,
     name: agent.name,
+    full_name: agent.full_name,
     description: agent.description,
     skills: agent.skills,
     role: agent.role,
@@ -111,7 +111,7 @@ function createWorld(name, db) {
     const sent = await call('POST', '/api/voko/auth/send-code', { body: { email, locale: 'en' } })
     check(`主人 ${tag}：send-code`, sent.status === 200, sent)
     const codeLog = await waitForEmail({ to_email: email, template: 'verify-code', status: 'sent' })
-    const registered = await call('POST', '/api/voko/auth/register', { body: { email, password: `pw-${randomUUID()}`, verification_code: JSON.parse(codeLog.metadata_json).code, locale: 'en' } })
+    const registered = await call('POST', '/api/voko/auth/register', { body: { email, password: `pw-${randomUUID()}`, verification_code: JSON.parse(codeLog.metadata_json).code, locale: 'en', handle: `${name}-${tag}-${run}`.slice(0, 32) } })
     check(`主人 ${tag}：注册`, registered.status === 200, registered)
     const owner = { user_id: registered.json.user.id, token: registered.json.access_token, email }
     userIds.push(owner.user_id)
@@ -194,6 +194,7 @@ function createWorld(name, db) {
       await db('vk_jobs').where({ kind: 'daily_digest' }).whereIn('ref_id', userIds).del()
       await db('vk_access_requests').whereIn('user_id', userIds).del()
       await db('vk_owner_settings').whereIn('user_id', userIds).del()
+      await db('vk_owner_handles').whereIn('user_id', userIds).del()
       await db('auth_sessions').whereIn('user_id', userIds).del()
       await db('users').whereIn('id', userIds).del()
     }
@@ -84,7 +84,7 @@ try {
   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' } })
+  const owner = await call('POST', '/api/voko/auth/register', { body: { email, password: `pw-${randomUUID()}`, verification_code: JSON.parse(codeLog.metadata_json).code, locale: 'en', handle: `f0-${Date.now()}` } })
   check('主人注册', owner.status === 200, owner)
   userId = owner.json.user.id
   const token = owner.json.access_token
@@ -176,6 +176,7 @@ try {
   if (userId !== null) {
     await db('vk_access_requests').where({ user_id: userId }).del()
     await db('auth_sessions').where({ user_id: userId }).del()
+    await db('vk_owner_handles').where({ user_id: userId }).del()
     await db('users').where({ id: userId }).del()
   }
   await db('auth_codes').where({ email }).del()
@@ -69,7 +69,7 @@ try {
   check('验证码邮件已投递并记录', log !== undefined, { email })
   const code = JSON.parse(log.metadata_json).code
  
-  const registered = await call('POST', '/api/voko/auth/register', { body: { email, password: `pw-${randomUUID()}`, verification_code: code, locale: 'en' } })
+  const registered = await call('POST', '/api/voko/auth/register', { body: { email, password: `pw-${randomUUID()}`, verification_code: code, locale: 'en', handle: `sk-${Date.now()}` } })
   check('register', registered.status === 200 && typeof registered.json.access_token === 'string', registered)
   userId = registered.json.user.id
   const token = registered.json.access_token
@@ -114,6 +114,7 @@ try {
     await db('billing_ledger').where({ user_id: userId }).del()
     await db('vk_access_requests').where({ user_id: userId }).del()
     await db('auth_sessions').where({ user_id: userId }).del()
+    await db('vk_owner_handles').where({ user_id: userId }).del()
     await db('users').where({ id: userId }).del()
   }
   await db('auth_codes').where({ email }).del()
@@ -18,6 +18,7 @@ const mode = ref(&#39;login&#39;)
 const email = ref('')
 const password = ref('')
 const code = ref('')
+const handle = ref('')
 const message = ref('')
  
 async function sendCode() {
@@ -33,7 +34,7 @@ async function submit() {
   try {
     const session = mode.value === 'login'
       ? await api('POST', '/api/voko/auth/login', { method: 'password', email: email.value, password: password.value })
-      : await api('POST', '/api/voko/auth/register', { email: email.value, password: password.value, verification_code: code.value, locale: locale.value })
+      : await api('POST', '/api/voko/auth/register', { email: email.value, password: password.value, verification_code: code.value, locale: locale.value, handle: handle.value.trim().toLowerCase() })
     setToken(session.access_token)
     password.value = ''
     message.value = ''
@@ -52,6 +53,7 @@ async function submit() {
     <label class="voko-field">{{ t('login.email') }}<Input v-model="email" type="email" /></label>
     <label class="voko-field">{{ t('login.password') }}<Input v-model="password" type="password" /></label>
     <template v-if="mode === 'register'">
+      <label class="voko-field">{{ t('login.handle') }}<Input v-model="handle" /></label>
       <label class="voko-field">{{ t('login.code') }}<Input v-model="code" /></label>
       <Button variant="secondary" @click="sendCode">{{ t('login.sendCode') }}</Button>
     </template>
@@ -49,7 +49,7 @@ let resizeObserver = null
  
 /** 第 i 个站位相对区域落脚点的偏移：3 个一排，间距留够名字标签。 */
 function slot(index) {
-  return { x: ((index % 3) - 1) * 120, y: 34 + Math.floor(index / 3) * 64 }
+  return { x: ((index % 3) - 1) * 124, y: 34 + Math.floor(index / 3) * 64 }
 }
  
 /** 同一个 Agent 始终用同一套小人。 */
@@ -140,7 +140,7 @@ function sync() {
       actor.strolling = false
     }
     actor.busy = agent.effect !== null
-    actor.name.text = `${agent.name.length > 12 ? `${agent.name.slice(0, 11)}…` : agent.name} · Lv${agent.level}`
+    actor.name.text = `${agent.name.length > 18 ? `${agent.name.slice(0, 17)}…` : agent.name} · Lv${agent.level}`
     actor.effect.text = agent.effect === null ? '' : EFFECT_TEXT[agent.effect]
   }
   for (const [id, actor] of actors) {
@@ -9,6 +9,7 @@ export const messages = {
       email: 'Email',
       password: 'Password',
       code: 'Verification code',
+      handle: 'Your id (lowercase letters and digits). Your agents are shown as name@id',
       sendCode: 'Send code',
       codeSent: 'Code sent. Check your inbox.',
       submit: 'Sign in',
@@ -193,6 +194,7 @@ export const messages = {
       email: '邮箱',
       password: '密码',
       code: '验证码',
+      handle: '你的 id（小写字母和数字）。你的 Agent 会显示为「名字@你的 id」',
       sendCode: '发送验证码',
       codeSent: '验证码已发送，请查收邮件。',
       submit: '登录',
@@ -88,7 +88,7 @@ onMounted(async () =&gt; {
   <template v-if="agents">
     <p v-if="agents.length === 0 && me.access_request !== null && me.access_request.status === 'approved'">{{ t('agents.empty') }}</p>
     <Card v-for="agent in agents" :key="agent.id" class="voko-agent">
-      <h2>{{ agent.name }} <Badge :variant="BADGE[agent.status]">{{ t(`agents.status.${agent.status}`) }}</Badge></h2>
+      <h2>{{ agent.full_name }} <Badge :variant="BADGE[agent.status]">{{ t(`agents.status.${agent.status}`) }}</Badge></h2>
       <p>{{ t('agents.level', { level: agent.level }) }} · {{ t('agents.wallet', agent.wallet) }}</p>
       <p class="voko-nav"><router-link :to="`/agents/${agent.id}/world`">{{ t('world.title') }}</router-link> <router-link :to="`/agents/${agent.id}/board`">{{ t('agents.board') }}</router-link> <router-link :to="`/agents/${agent.id}/ledger`">{{ t('ledger.title') }}</router-link></p>
       <label class="voko-field">{{ t('agents.dailyLimit') }}<Input v-model="local[agent.id].limit" type="number" /></label>
@@ -96,6 +96,9 @@ export function createAgentAccess({ db, agents, grantStarter, public_url, notifi
           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')
+      // 同一主人名下 Agent 不重名（全名 名字@主人 id 才唯一）；UNIQUE(owner_user_id, name) 是最终裁决。
+      const claiming = await agents.getById(ctx, trx, { agent_id: claimRow.agent_id })
+      if ((await trx('vk_agents').where({ owner_user_id: user_id, name: claiming.name }).first('id')) !== undefined) return refuse('CONFLICT', `You already have an agent named ${claiming.name}; ask this agent to register under another name`)
       const guild = await trx('vk_guilds').where({ id: guild_id }).forUpdate().first('lead_user_id', 'company_agent_id')
       if (guild === undefined) return refuse('NOT_FOUND', `Guild not found: ${guild_id}`)
       switch (role) {
@@ -4,6 +4,7 @@ const tableModules = [
   require('./vk_api_keys.cjs'),
   require('./vk_webhook_deliveries.cjs'),
   require('./vk_owner_settings.cjs'),
+  require('./vk_owner_handles.cjs'),
 ]
  
 const targetTables = tableModules.map(({ tableName, buildTable }) => [tableName, buildTable])
+const tableName = 'vk_owner_handles'
+
+function buildTable(t) {
+  t.string('user_id', 64).primary()
+  t.string('handle', 32).notNullable()
+  t.datetime('created_at', { precision: 3 }).notNullable()
+  t.unique(['handle'], { indexName: 'uq_vk_owner_handles_handle' })
+  t.check("handle regexp '^[a-z0-9][a-z0-9_-]{1,31}$'", [], 'ck_vk_owner_handles_format')
+}
+
+module.exports = { tableName, buildTable }
@@ -12,4 +12,5 @@ export { createAgentAccess, MAX_AGENTS_PER_OWNER, API_KEY_PREFIX } from &#39;./agent
 export { createOwnerSettings, DEFAULT_OWNER_SETTINGS } from './owner-settings.js'
 export { nextAllowedSendTime, nextLocalHour } from './quiet-hours.js'
 export { createWebhooks, signWebhook, isPublicAddress } from './webhooks.js'
+export { createOwnerHandles, HANDLE_PATTERN } from './owner-handles.js'
 export { default as accessDbSchema } from './db/tables/index.cjs'
+const TABLE = 'vk_owner_handles'
+
+/** 主人 id 的格式：小写字母、数字、下划线、连字符，2–32 位，字母或数字开头。与 DB CHECK 一致。 */
+export const HANDLE_PATTERN = /^[a-z0-9][a-z0-9_-]{1,31}$/
+
+/**
+ * 主人的 id（handle）。Agent 的全名是「名字@主人 id」，如 小火子@yibo。
+ * @param {{ db: import('knex').Knex }} deps
+ */
+export function createOwnerHandles({ db }) {
+  if (typeof db !== 'function') throw new Error('createOwnerHandles: db is required')
+
+  /**
+   * @param {object} _ctx
+   * @param {{ handle: string }} input
+   * @returns {Promise<boolean>}
+   */
+  async function isTaken(_ctx, { handle }) {
+    return (await db(TABLE).where({ handle }).first('user_id')) !== undefined
+  }
+
+  /**
+   * 注册时在同一事务里登记；handle 被占用由 UNIQUE 裁决（调用方应先用 isTaken 给出友好提示）。
+   * @param {object} _ctx
+   * @param {import('knex').Knex} trx
+   * @param {{ user_id: string, handle: string }} input
+   */
+  async function assign(_ctx, trx, { user_id, handle }) {
+    await trx(TABLE).insert({ user_id, handle, created_at: new Date() })
+  }
+
+  /**
+   * @param {object} _ctx
+   * @param {{ user_id: string }} input
+   * @returns {Promise<string|null>}
+   */
+  async function get(_ctx, { user_id }) {
+    const row = await db(TABLE).where({ user_id }).first('handle')
+    return row === undefined ? null : row.handle
+  }
+
+  return { isTaken, assign, get }
+}
@@ -18,9 +18,12 @@ export const AGENT_ROLES = Object.freeze([&#39;company&#39;, &#39;member&#39;])
  *   level: number,
  *   xp: number,
  *   daily_spend_limit: number|null,
+ *   owner_handle: string|null,
+ *   full_name: string,
  *   claimed_at: Date|null,
  *   created_at: Date,
- * }} Agent pending_claim 时 owner_user_id / guild_id / claimed_at 为 null，其余状态三者必有。
+ * }} Agent pending_claim 时 owner_user_id / guild_id / claimed_at / owner_handle 为 null，其余状态必有。
+ * `full_name` 是对外显示的全名：已认领为「名字@主人 id」（如 小火子@yibo），未认领时就是名字。
  */
  
 /**
@@ -39,6 +42,7 @@ export function agentFromRow(row) {
     case 'suspended':
       requiredString(row.owner_user_id, 'owner_user_id', id)
       requiredString(row.guild_id, 'guild_id', id)
+      requiredString(row.owner_handle, 'owner_handle', id)
       if (!(row.claimed_at instanceof Date)) throw new Error(`vk_agents.claimed_at missing, id: ${id}`)
       break
     default:
@@ -62,6 +66,8 @@ export function agentFromRow(row) {
     level: row.level,
     xp: row.xp,
     daily_spend_limit: row.daily_spend_limit,
+    owner_handle: row.owner_handle,
+    full_name: row.owner_handle === null ? row.name : `${row.name}@${row.owner_handle}`,
     claimed_at: row.claimed_at,
     created_at: row.created_at,
   }
@@ -72,6 +78,12 @@ export function agentFromRow(row) {
  */
 export function createAgents() {
   /**
+   * 带主人 id 的 Agent 查询（主人 id 在 vk_owner_handles）。
+   * @param {import('knex').Knex} runner
+   */
+  const withHandle = (runner) => runner(`${TABLE} as a`).leftJoin('vk_owner_handles as h', 'h.user_id', 'a.owner_user_id').select('a.*', 'h.handle as owner_handle')
+
+  /**
    * 新注册的 Agent：待认领、员工角色、1 级。
    * @param {object} _ctx
    * @param {import('knex').Knex} runner
@@ -101,7 +113,7 @@ export function createAgents() {
    * @returns {Promise<Agent>}
    */
   async function getById(_ctx, runner, { agent_id }) {
-    const row = await runner(TABLE).where({ id: agent_id }).first()
+    const row = await withHandle(runner).where('a.id', agent_id).first()
     if (row === undefined) throw new Error(`vk_agents row missing, id: ${agent_id}`)
     return agentFromRow(row)
   }
@@ -137,7 +149,7 @@ export function createAgents() {
    * @returns {Promise<Agent[]>}
    */
   async function listByOwner(_ctx, runner, { owner_user_id }) {
-    return (await runner(TABLE).where({ owner_user_id }).orderBy('created_at', 'asc')).map(agentFromRow)
+    return (await withHandle(runner).where('a.owner_user_id', owner_user_id).orderBy('a.created_at', 'asc')).map(agentFromRow)
   }
  
   /**
@@ -170,7 +182,7 @@ export function createAgents() {
    * @returns {Promise<Agent>}
    */
   async function getByWallet(_ctx, runner, { wallet_user_id }) {
-    const row = await runner(TABLE).where({ wallet_user_id }).first()
+    const row = await withHandle(runner).where('a.wallet_user_id', wallet_user_id).first()
     if (row === undefined) throw new Error(`vk_agents row missing for wallet: ${wallet_user_id}`)
     return agentFromRow(row)
   }
@@ -21,6 +21,7 @@ function buildTable(t) {
   t.datetime('created_at', { precision: 3 }).notNullable()
   t.datetime('updated_at', { precision: 3 }).nullable()
   t.unique(['wallet_user_id'], { indexName: 'uq_vk_agents_wallet' })
+  t.unique(['owner_user_id', 'name'], { indexName: 'uq_vk_agents_owner_name' })
   t.index(['owner_user_id'], 'idx_vk_agents_owner')
   t.index(['guild_id', 'status'], 'idx_vk_agents_guild_status')
   t.check("role in ('company','member')", [], 'ck_vk_agents_role')
@@ -72,10 +72,11 @@ export function createGame({ db }) {
   function earnings({ guild_id, since, until }) {
     const query = db('billing_ledger as l')
       .join('vk_agents as a', 'a.wallet_user_id', 'l.user_id')
+      .join('vk_owner_handles as h', 'h.user_id', 'a.owner_user_id')
       .where('l.source', 'voko')
       .whereIn('l.reason', EARNING_REASONS)
-      .groupBy('a.id', 'a.name', 'a.level', 'a.guild_id')
-      .select('a.id as agent_id', 'a.name', 'a.level', 'a.guild_id', db.raw('SUM(l.amount) as points'))
+      .groupBy('a.id', 'a.name', 'h.handle', 'a.level', 'a.guild_id')
+      .select('a.id as agent_id', db.raw("CONCAT(a.name, '@', h.handle) as name"), 'a.level', 'a.guild_id', db.raw('SUM(l.amount) as points'))
     if (guild_id !== null) query.where('a.guild_id', guild_id)
     if (since !== null) query.where('l.created_at', '>=', since)
     if (until !== null) query.where('l.created_at', '<', until)
@@ -104,7 +105,7 @@ export function createGame({ db }) {
     const inGuild = (/** @type {import('knex').Knex.QueryBuilder} */ query, /** @type {string} */ column) => (guild_id === null ? query : query.where(column, guild_id))
     const [guild, agents, working, asking, titles] = await Promise.all([
       guild_id === null ? null : db('vk_guilds').where({ id: guild_id }).first('id', 'name', 'level', 'weekly_goal'),
-      inGuild(db('vk_agents as a').join('vk_guilds as g', 'g.id', 'a.guild_id').where('a.status', 'active'), 'a.guild_id').orderBy('a.created_at', 'asc').select('a.id', 'a.name', 'a.role', 'a.level', 'a.xp', 'g.name as guild_name'),
+      inGuild(db('vk_agents as a').join('vk_guilds as g', 'g.id', 'a.guild_id').join('vk_owner_handles as h', 'h.user_id', 'a.owner_user_id').where('a.status', 'active'), 'a.guild_id').orderBy('a.created_at', 'asc').select('a.id', db.raw("CONCAT(a.name, '@', h.handle) as name"), 'a.role', 'a.level', 'a.xp', 'g.name as guild_name'),
       inGuild(db('vk_tasks'), 'guild_id').whereIn('status', ['claimed', 'rework']).select('holder_agent_id'),
       inGuild(db('vk_help_requests as h').join('vk_tasks as t', 't.id', 'h.task_id').where('h.status', 'open'), 't.guild_id').select('h.agent_id'),
       inGuild(db('vk_agent_titles as ti').join('vk_agents as a', 'a.id', 'ti.agent_id'), 'a.guild_id').select('ti.agent_id', 'ti.title'),
@@ -54,7 +54,13 @@ async function main() {
       role: user.role,
       updated_at: now,
     })
-    console.log(`voko dev user ready: ${normalizedEmail}, role=${role}`)
+    // 主人 id（Agent 全名「名字@主人 id」的后半段）：取邮箱 @ 前的部分，已有则保留。
+    const stored = await db('users').where({ email: normalizedEmail }).first('id')
+    const handle = normalizedEmail.split('@')[0].replace(/[^a-z0-9_-]/g, '-').slice(0, 32)
+    await db('vk_owner_handles').insert({ user_id: stored.id, handle, created_at: now }).onConflict('user_id').ignore()
+    const saved = await db('vk_owner_handles').where({ user_id: stored.id }).first('handle')
+    if (saved === undefined) throw new Error(`voko dev user: id ${handle} 已被别的账号占用，请换一个邮箱前缀`)
+    console.log(`voko dev user ready: ${normalizedEmail}, role=${role}, id=${saved.handle}`)
   } finally {
     await db.destroy()
   }
@@ -14,7 +14,7 @@
 import { createHash } from 'node:crypto'
 import { readFileSync } from 'node:fs'
  
-const SUPPORTED_SKILL_VERSION = '0.3.1'
+const SUPPORTED_SKILL_VERSION = '0.3.2'
 const config = {
   api: required('VOKO_API_BASE').replace(/\/$/, ''),
   key: required('VOKO_API_KEY'),
@@ -11,7 +11,7 @@
  * 没有第三方依赖：Node 20+ 自带的 fetch 即可。大模型走 OpenAI 兼容的 /chat/completions。
  * 用法：node agent.mjs [--once]      环境变量见 README.md
  */
-const SUPPORTED_SKILL_VERSION = '0.3.1'
+const SUPPORTED_SKILL_VERSION = '0.3.2'
 const config = {
   api: required('VOKO_API_BASE').replace(/\/$/, ''),
   key: required('VOKO_API_KEY'),