feat(web): 小镇首页默认公开，登录改为弹窗

- 公开接口 /api/voko/public/world/state、world/feed、leaderboard（全部公会的 Agent 与动态，不含任务正文、钱包、主人） - 首页即小镇地图；接入自己的 Agent、发任务等需要登录时弹出登录窗，登录后回到原目标页 - 顶栏：登录 / 接入我的 Agent / 我的 Agent / 退出；加入申请面板并入「我的 Agent」 - 小镇里角色间距加大，名字标签不再重叠 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

feat(web): 小镇首页默认公开，登录改为弹窗
- 公开接口 /api/voko/public/world/state、world/feed、leaderboard（全部公会的 Agent 与动态，不含任务正文、钱包、主人） - 首页即小镇地图；接入自己的 Agent、发任务等需要登录时弹出登录窗，登录后回到原目标页 - 顶栏：登录 / 接入我的 Agent / 我的 Agent / 退出；加入申请面板并入「我的 Agent」 - 小镇里角色间距加大，名字标签不再重叠 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
yibo
1 parent 7cac2f68
Showing 13 changed files with 177 additions and 96 deletions
apps/voko-server/src/routes/owner.js
apps/voko-server/tools/scenarios/voko-alpha/f4-growth.mjs
apps/voko-web/src/App.vue
apps/voko-web/src/pages/LoginPage.vue → apps/voko-web/src/LoginModal.vue
apps/voko-web/src/ai-town/CityCanvas.vue
apps/voko-web/src/api.js
apps/voko-web/src/i18n/messages.js
apps/voko-web/src/main.js
apps/voko-web/src/pages/AgentsPage.vue
apps/voko-web/src/pages/HomePage.vue
apps/voko-web/src/pages/WorldPage.vue
docs/runbooks/verify-alpha.md
packages/voko-exchange/src/game.js
@@ -107,6 +107,16 @@ export function registerOwnerRoutes(app, services) {
     return { user, agent }
   }
+  // 公开的小镇视图：不登录就能看到全部公会的 Agent 在做什么（名字、等级、状态、任务标题与赏金；不含任务正文、交付与钱包）。
+  app.get('/api/voko/public/world/state', async (request) => game.worldState(request.ctx, { guild_id: null }))
+
+  app.get('/api/voko/public/world/feed', async (request) => {
+    const query = v.parse(FeedQuery, request.query)
+    return { events: (await game.worldFeed(request.ctx, { guild_id: null, since: query.since })).map(feedView) }
+  })
+
+  app.get('/api/voko/public/leaderboard', async (request) => ({ scope: 'world', period: 'week', leaderboard: await game.leaderboard(request.ctx, { agent: null, scope: 'world', period: 'week' }) }))
+
   app.get('/api/voko/guilds', async (request) => {
     await requireUser(request, services)
     return { guilds: await guilds.list(request.ctx) }
@@ -98,6 +98,17 @@ await runScenario(&#39;f4&#39;, async ({ db, check, call, admin, waitForEmail, createOwn
   const otherState = await call('GET', '/v1/world/state', { token: outsider.key })
   check('F4-05 非成员（未认领）→ 403；别的公会的 Agent 只看到自己的公会', strangerState.status === 403 && strangerFeed.status === 403 && otherState.json.data.guild.id === other && otherState.json.data.agents.every((agent) => agent.id !== taker.id), { strangerState, otherState })
+  // 公开的小镇视图：不登录就能看到全部公会的 Agent 与动态，但不含任务正文、钱包等。
+  const town = await call('GET', '/api/voko/public/world/state')
+  const townFeed = await call('GET', '/api/voko/public/world/feed?since=0')
+  const townBoard = await call('GET', '/api/voko/public/leaderboard')
+  const names = town.json.agents.map((agent) => agent.id)
+  check('公开小镇：不登录可见两个公会的 Agent、动态与全镇排行', town.status === 200 && town.json.guild === null && [taker.id, helper.id, outsider.id].every((id) => names.includes(id)) && typeof town.json.agents[0].guild_name === 'string' && townFeed.json.events.some((event) => event.type === 'task.accepted') && townBoard.json.leaderboard.some((row) => row.agent_id === taker.id), { town: town.status, feed: townFeed.status })
+  const leaked = JSON.stringify([town.json, townFeed.json, townBoard.json])
+  check('公开小镇不暴露钱包行、主人、任务正文与 api_key', !leaked.includes('wallet_user_id') && !leaked.includes('owner_user_id') && !leaked.includes('"spec"') && !leaked.includes('vk_live_'), null)
+  const stillPrivate = await call('GET', '/api/voko/agents')
+  check('其余网页接口不登录仍是 401', stillPrivate.status === 401, stillPrivate)
+
   // 数据看板。
   const dashboard = (await call('GET', '/api/voko/admin/dashboard', { token: adminToken })).json.dashboard
   check('数据看板有完成任务数、赚取积分、平均交付周期、一次通过率', dashboard.tasks_settled >= 3 && dashboard.points_earned >= 190 && typeof dashboard.avg_delivery_hours === 'number' && dashboard.first_pass_rate > 0 && dashboard.first_pass_rate <= 1, dashboard)
 <script setup>
-import { ToastHost } from '@drama/ui'
+import { useI18n } from 'vue-i18n'
+import { useRouter } from 'vue-router'
+import { Button, ToastHost } from '@drama/ui'
+
+import { session, setToken } from './api.js'
+import LoginModal from './LoginModal.vue'
+
+const { t } = useI18n()
+const router = useRouter()
+
+function logout() {
+  setToken(null)
+  router.push('/')
+}
 </script>
 <template>
+  <header class="voko-top">
+    <router-link to="/" class="voko-brand">VOKO</router-link>
+    <nav class="voko-top-nav" :aria-label="t('nav.label')">
+      <template v-if="session.loggedIn">
+        <router-link to="/agents">{{ t('agents.title') }}</router-link>
+        <Button variant="ghost" @click="logout">{{ t('nav.logout') }}</Button>
+      </template>
+      <template v-else>
+        <Button variant="ghost" @click="router.push({ path: '/login', query: { next: '/agents' } })">{{ t('nav.login') }}</Button>
+        <Button @click="router.push({ path: '/login', query: { next: '/agents' } })">{{ t('nav.connect') }}</Button>
+      </template>
+    </nav>
+  </header>
   <main class="voko-shell">
     <router-view />
     <ToastHost />
   </main>
+  <LoginModal />
 </template>
 <style>
@@ -15,10 +42,30 @@ body {
   background: var(--drama-color-bg);
   color: var(--drama-color-text);
 }
+.voko-top {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  max-width: 1040px;
+  margin: 0 auto;
+  padding: var(--drama-space-md) var(--drama-space-md) 0;
+}
+.voko-brand {
+  font-weight: 800;
+  font-size: var(--drama-font-size-lg, 1.25rem);
+  letter-spacing: 0.08em;
+  text-decoration: none;
+  color: inherit;
+}
+.voko-top-nav {
+  display: flex;
+  align-items: center;
+  gap: var(--drama-space-md);
+}
 .voko-shell {
   max-width: 1040px;
   margin: 0 auto;
-  padding: var(--drama-space-xl) var(--drama-space-md);
+  padding: var(--drama-space-md) var(--drama-space-md) var(--drama-space-xl);
 }
 .voko-field {
   display: flex;
 <script setup>
-import { ref } from 'vue'
+/**
+ * 登录 / 注册弹窗。小镇默认公开可看；只有接入自己的 Agent、发指令时才需要登录。
+ * 路由到 /login（可带 ?next=）即打开本弹窗，关闭后回到小镇。
+ */
+import { computed, ref } from 'vue'
 import { useI18n } from 'vue-i18n'
 import { useRoute, useRouter } from 'vue-router'
-import { Button, Card, Input } from '@drama/ui'
+import { Button, Input, Modal } from '@drama/ui'
-import { api, setToken } from '../api.js'
+import { api, setToken } from './api.js'
 const { t, locale } = useI18n()
 const router = useRouter()
 const route = useRoute()
+const open = computed(() => route.path === '/login')
 const mode = ref('login')
 const email = ref('')
 const password = ref('')
@@ -16,8 +21,12 @@ const code = ref(&#39;&#39;)
 const message = ref('')
 async function sendCode() {
-  await api('POST', '/api/voko/auth/send-code', { email: email.value, locale: locale.value })
-  message.value = t('login.codeSent')
+  try {
+    await api('POST', '/api/voko/auth/send-code', { email: email.value, locale: locale.value })
+    message.value = t('login.codeSent')
+  } catch (err) {
+    message.value = err instanceof Error ? err.message : String(err)
+  }
 }
 async function submit() {
@@ -26,8 +35,10 @@ async function submit() {
       ? 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 })
     setToken(session.access_token)
-    // 只接受站内路径（认领链接登录后回到认领页）。
-    const next = typeof route.query.next === 'string' && route.query.next.startsWith('/') && !route.query.next.startsWith('//') ? route.query.next : '/'
+    password.value = ''
+    message.value = ''
+    // 只接受站内路径（如认领链接登录后回到认领页）。
+    const next = typeof route.query.next === 'string' && route.query.next.startsWith('/') && !route.query.next.startsWith('//') ? route.query.next : '/agents'
     await router.push(next)
   } catch (err) {
     message.value = err instanceof Error ? err.message : String(err)
@@ -36,18 +47,18 @@ async function submit() {
 </script>
 <template>
-  <Card>
-    <h1>{{ mode === 'login' ? t('login.title') : t('login.registerTitle') }}</h1>
+  <Modal :open="open" :title="mode === 'login' ? t('login.title') : t('login.registerTitle')" width="420px" @close="router.push('/')">
+    <p>{{ t('login.why') }}</p>
     <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.code') }}<Input v-model="code" /></label>
       <Button variant="secondary" @click="sendCode">{{ t('login.sendCode') }}</Button>
     </template>
-    <p v-if="message">{{ message }}</p>
-    <Button @click="submit">{{ mode === 'login' ? t('login.submit') : t('login.register') }}</Button>
-    <Button variant="ghost" @click="mode = mode === 'login' ? 'register' : 'login'">
-      {{ mode === 'login' ? t('login.toRegister') : t('login.toLogin') }}
-    </Button>
-  </Card>
+    <p v-if="message" role="status">{{ message }}</p>
+    <template #footer>
+      <Button variant="ghost" @click="mode = mode === 'login' ? 'register' : 'login'">{{ mode === 'login' ? t('login.toRegister') : t('login.toLogin') }}</Button>
+      <Button @click="submit">{{ mode === 'login' ? t('login.submit') : t('login.register') }}</Button>
+    </template>
+  </Modal>
 </template>
@@ -43,9 +43,9 @@ let folk = null
 const actors = new Map()
 let resizeObserver = null
-/** 第 i 个站位相对区域落脚点的偏移：4 个一排。 */
+/** 第 i 个站位相对区域落脚点的偏移：3 个一排，间距留够名字标签。 */
 function slot(index) {
-  return { x: ((index % 4) - 1.5) * 44, y: 34 + Math.floor(index / 4) * 56 }
+  return { x: ((index % 3) - 1) * 120, y: 34 + Math.floor(index / 3) * 64 }
 }
 /** 同一个 Agent 始终用同一套小人。 */
@@ -89,7 +89,7 @@ function buildSigns() {
     const label = new Text({ text: props.zoneLabels[zone], style: { fontSize: 22, fontWeight: '700', fill: 0xffffff, stroke: { color: 0x1f2937, width: 5 } } })
     label.anchor.set(0.5, 1)
     label.position.set(point.x, point.y - 48)
-    const plate = new Graphics().roundRect(point.x - 100, point.y - 40, 200, 150, 14).fill({ color: 0xffffff, alpha: 0.18 }).stroke({ color: 0xffffff, alpha: 0.5, width: 2 })
+    const plate = new Graphics().roundRect(point.x - 190, point.y - 40, 380, 170, 14).fill({ color: 0xffffff, alpha: 0.18 }).stroke({ color: 0xffffff, alpha: 0.5, width: 2 })
     signs.addChild(plate, label)
   }
   return signs
@@ -130,7 +130,7 @@ function sync() {
       actors.set(agent.id, actor)
     }
     actor.target = target
-    actor.name.text = `${agent.name.length > 14 ? `${agent.name.slice(0, 13)}…` : agent.name} · Lv${agent.level}`
+    actor.name.text = `${agent.name.length > 12 ? `${agent.name.slice(0, 11)}…` : agent.name} · Lv${agent.level}`
     actor.effect.text = agent.effect === null ? '' : EFFECT_TEXT[agent.effect]
   }
   for (const [id, actor] of actors) {
@@ -2,8 +2,13 @@
  * voko-server 网页接口的唯一调用点。access token 存在 sessionStorage（Alpha 内部使用）。
  */
+import { reactive } from 'vue'
+
 const TOKEN_KEY = 'voko.access_token'
+/** 登录状态（给顶栏用）。 */
+export const session = reactive({ loggedIn: sessionStorage.getItem(TOKEN_KEY) !== null })
+
 export function getToken() {
   return sessionStorage.getItem(TOKEN_KEY)
 }
@@ -12,6 +17,7 @@ export function getToken() {
 export function setToken(token) {
   if (token === null) sessionStorage.removeItem(TOKEN_KEY)
   else sessionStorage.setItem(TOKEN_KEY, token)
+  session.loggedIn = token !== null
 }
 /**
@@ -15,7 +15,9 @@ export const messages = {
       register: 'Create account',
       toRegister: 'No account? Register',
       toLogin: 'Have an account? Sign in',
+      why: 'Watching the town needs no account. Sign in to connect your own agent, publish tasks or answer its questions.',
     },
+    nav: { label: 'Account', login: 'Sign in', logout: 'Sign out', connect: 'Connect my agent' },
     home: {
       title: 'Your VOKO access',
       notApplied: 'Apply to join. An operator reviews each request.',
@@ -110,6 +112,9 @@ export const messages = {
     },
     world: {
       title: 'Guild city',
+      town: 'VOKO Town',
+      townIntro: 'Every agent in every guild, live: who is picking up work, who is at their desk, who is asking their human for help, who just got paid.',
+      townLeaderboard: 'This week across the town',
       guildLevel: 'Level {level}',
       goal: 'Weekly goal: {progress} / {goal} points settled',
       hint: 'Drag to move the map, scroll to zoom. Placeholder art from AI Town for local testing.',
@@ -192,7 +197,9 @@ export const messages = {
       register: '注册',
       toRegister: '没有账号？去注册',
       toLogin: '已有账号？去登录',
+      why: '看小镇不需要账号。接入自己的 Agent、发任务、回复它的求助时才需要登录。',
     },
+    nav: { label: '账号', login: '登录', logout: '退出', connect: '接入我的 Agent' },
     home: {
       title: '我的 VOKO 准入',
       notApplied: '提交加入申请，运营会人工审核。',
@@ -287,6 +294,9 @@ export const messages = {
     },
     world: {
       title: '公会城',
+      town: 'VOKO 小镇',
+      townIntro: '所有公会的 Agent 都在这里，实时的：谁在接任务、谁在工位上干活、谁在找主人求助、谁刚拿到赏金。',
+      townLeaderboard: '本周全镇排行',
       guildLevel: '{level} 级',
       goal: '本周目标：已结算 {progress} / {goal} 积分',
       hint: '拖动可移动地图，滚轮缩放。画面素材来自 AI Town，仅本地测试用。',
@@ -14,9 +14,7 @@ import ApprovalsPage from &#39;./pages/ApprovalsPage.vue&#39;
 import BoardPage from './pages/BoardPage.vue'
 import ClaimPage from './pages/ClaimPage.vue'
 import HelpPage from './pages/HelpPage.vue'
-import HomePage from './pages/HomePage.vue'
 import LedgerPage from './pages/LedgerPage.vue'
-import LoginPage from './pages/LoginPage.vue'
 import SettingsPage from './pages/SettingsPage.vue'
 import TaskPage from './pages/TaskPage.vue'
 import WorldPage from './pages/WorldPage.vue'
@@ -24,8 +22,9 @@ import WorldPage from &#39;./pages/WorldPage.vue&#39;
 const router = createRouter({
   history: createWebHistory(),
   routes: [
-    { path: '/', component: HomePage },
-    { path: '/login', component: LoginPage },
+    // 小镇默认公开可看；/login 仍显示小镇，由 App 里的登录弹窗盖在上面。
+    { path: '/', component: WorldPage },
+    { path: '/login', component: WorldPage },
     { path: '/admin', component: AdminPage },
     { path: '/admin/guilds', component: AdminGuildsPage },
     { path: '/admin/disputes', component: AdminDisputesPage },
@@ -9,18 +9,26 @@ import { api, getToken } from &#39;../api.js&#39;
 const { t } = useI18n()
 const router = useRouter()
 const agents = ref(null)
+const me = ref(null)
+const note = ref('')
 /** 每个 Agent 的页面状态：刚重置出的 key、上限输入框、提示。 */
 const local = reactive({})
 const BADGE = { pending_claim: 'neutral', active: 'success', suspended: 'warning' }
 async function load() {
+  me.value = await api('GET', '/api/voko/me')
   agents.value = (await api('GET', '/api/voko/agents')).agents
   for (const agent of agents.value) {
     if (local[agent.id] === undefined) local[agent.id] = { key: '', limit: agent.daily_spend_limit === null ? '' : String(agent.daily_spend_limit), message: '' }
   }
 }
+async function apply() {
+  await api('POST', '/api/voko/access-requests', { note: note.value })
+  await load()
+}
+
 /**
  * @param {string} id
  * @param {() => Promise<void>} action
@@ -67,8 +75,18 @@ onMounted(async () =&gt; {
 <template>
   <h1>{{ t('agents.title') }}</h1>
   <p class="voko-nav"><router-link to="/help">{{ t('help.title') }}</router-link> <router-link to="/approvals">{{ t('agents.approvals') }}</router-link> <router-link to="/settings">{{ t('settings.title') }}</router-link></p>
+  <Card v-if="me && (me.access_request === null || me.access_request.status !== 'approved')" class="voko-agent">
+    <p>{{ me.user.email }}</p>
+    <template v-if="me.access_request === null">
+      <p>{{ t('home.notApplied') }}</p>
+      <label class="voko-field">{{ t('home.note') }}<Input v-model="note" /></label>
+      <Button @click="apply">{{ t('home.apply') }}</Button>
+    </template>
+    <p v-else>{{ t(`home.status.${me.access_request.status}`) }}</p>
+  </Card>
+  <p v-if="me && me.user.role === 'admin'"><router-link to="/admin">{{ t('home.admin') }}</router-link></p>
   <template v-if="agents">
-    <p v-if="agents.length === 0">{{ t('agents.empty') }}</p>
+    <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>
       <p>{{ t('agents.level', { level: agent.level }) }} · {{ t('agents.wallet', agent.wallet) }}</p>
-<script setup>
-import { onMounted, ref } from 'vue'
-import { useI18n } from 'vue-i18n'
-import { useRouter } from 'vue-router'
-import { Button, Card, Input } from '@drama/ui'
-
-import { api, getToken } from '../api.js'
-
-const { t } = useI18n()
-const router = useRouter()
-const me = ref(null)
-const note = ref('')
-
-async function load() {
-  me.value = await api('GET', '/api/voko/me')
-}
-
-async function apply() {
-  await api('POST', '/api/voko/access-requests', { note: note.value })
-  await load()
-}
-
-onMounted(async () => {
-  if (getToken() === null) {
-    await router.push('/login')
-    return
-  }
-  await load()
-})
-</script>
-
-<template>
-  <Card v-if="me">
-    <h1>{{ t('home.title') }}</h1>
-    <p>{{ me.user.email }}</p>
-    <template v-if="me.access_request === null">
-      <p>{{ t('home.notApplied') }}</p>
-      <label class="voko-field">{{ t('home.note') }}<Input v-model="note" /></label>
-      <Button @click="apply">{{ t('home.apply') }}</Button>
-    </template>
-    <p v-else>{{ t(`home.status.${me.access_request.status}`) }}</p>
-    <p v-if="me.access_request !== null && me.access_request.status === 'approved'"><router-link to="/agents">{{ t('home.agents') }}</router-link></p>
-    <router-link v-if="me.user.role === 'admin'" to="/admin">{{ t('home.admin') }}</router-link>
-  </Card>
-</template>
@@ -13,7 +13,9 @@ import { api, getToken } from &#39;../api.js&#39;
 const { t, te } = useI18n()
 const route = useRoute()
 const router = useRouter()
-const base = `/api/voko/agents/${route.params.id}`
+// 带 Agent id 时看它所在的公会（需要登录）；否则是公开的小镇：全部公会的 Agent。
+const mine = typeof route.params.id === 'string'
+const base = mine ? `/api/voko/agents/${route.params.id}` : '/api/voko/public'
 const state = ref(null)
 const board = ref([])
 const feed = ref([])
@@ -42,7 +44,7 @@ const placed = computed(() =&gt; state.value.agents.map((agent) =&gt; {
   return { ...agent, zone: act && act.zone ? act.zone : ZONE_OF_STATE[agent.state], effect: act ? act.effect : null }
 }))
 const zoneLabels = computed(() => Object.fromEntries(ZONES.map((zone) => [zone, t(`world.zones.${zone}`)])))
-const goalPercent = computed(() => (state.value.guild.weekly_goal === 0 ? 0 : Math.min(100, Math.round((state.value.guild.weekly_progress / state.value.guild.weekly_goal) * 100))))
+const goalPercent = computed(() => (state.value.guild === null || state.value.guild.weekly_goal === 0 ? 0 : Math.min(100, Math.round((state.value.guild.weekly_progress / state.value.guild.weekly_goal) * 100))))
 /** @param {any} event */
 function play(event) {
@@ -55,7 +57,7 @@ function play(event) {
 }
 async function refresh() {
-  const [nextState, nextFeed, nextBoard] = await Promise.all([api('GET', `${base}/world/state`), api('GET', `${base}/world/feed?since=${cursor}`), api('GET', `${base}/leaderboard?scope=guild&period=week`)])
+  const [nextState, nextFeed, nextBoard] = await Promise.all([api('GET', `${base}/world/state`), api('GET', `${base}/world/feed?since=${cursor}`), api('GET', mine ? `${base}/leaderboard?scope=guild&period=week` : `${base}/leaderboard`)])
   state.value = nextState
   board.value = nextBoard.leaderboard
   const fresh = nextFeed.events
@@ -76,7 +78,7 @@ function describe(event) {
 }
 onMounted(async () => {
-  if (getToken() === null) {
+  if (mine && getToken() === null) {
     await router.push({ path: '/login', query: { next: route.fullPath } })
     return
   }
@@ -87,10 +89,14 @@ onBeforeUnmount(() =&gt; clearInterval(timer))
 </script>
 <template>
-  <p><router-link to="/agents">{{ t('board.back') }}</router-link></p>
+  <p v-if="mine"><router-link to="/agents">{{ t('board.back') }}</router-link></p>
   <template v-if="state">
-    <h1>{{ state.guild.name }} · {{ t('world.guildLevel', { level: state.guild.level }) }}</h1>
-    <p v-if="state.guild.weekly_goal > 0">
+    <template v-if="state.guild === null">
+      <h1>{{ t('world.town') }}</h1>
+      <p>{{ t('world.townIntro') }}</p>
+    </template>
+    <h1 v-else>{{ state.guild.name }} · {{ t('world.guildLevel', { level: state.guild.level }) }}</h1>
+    <p v-if="state.guild !== null && state.guild.weekly_goal > 0">
       {{ t('world.goal', { progress: state.guild.weekly_progress, goal: state.guild.weekly_goal }) }}
       <progress :value="goalPercent" max="100">{{ goalPercent }}%</progress>
     </p>
@@ -99,13 +105,13 @@ onBeforeUnmount(() =&gt; clearInterval(timer))
     <p class="voko-hint">{{ t('world.hint') }}</p>
     <ul class="voko-roster">
       <li v-for="agent in placed" :key="agent.id">
-        <strong>{{ agent.name }}</strong> · {{ t('agents.level', { level: agent.level }) }} · {{ t(`world.zones.${agent.zone}`) }}<template v-if="agent.titles.length > 0"> · {{ agent.titles.map((title) => t(`world.titles.${title}`)).join(' · ') }}</template>
+        <strong>{{ agent.name }}</strong><template v-if="state.guild === null"> · {{ agent.guild_name }}</template> · {{ t('agents.level', { level: agent.level }) }} · {{ t(`world.zones.${agent.zone}`) }}<template v-if="agent.titles.length > 0"> · {{ agent.titles.map((title) => t(`world.titles.${title}`)).join(' · ') }}</template>
       </li>
     </ul>
     <div class="voko-columns">
       <Card>
-        <h2>{{ t('world.leaderboard') }}</h2>
+        <h2>{{ t(mine ? 'world.leaderboard' : 'world.townLeaderboard') }}</h2>
         <p v-if="board.length === 0">{{ t('task.none') }}</p>
         <ol><li v-for="row in board" :key="row.agent_id">{{ row.name }} · {{ t('board.reward', { reward: row.points }) }}</li></ol>
       </Card>
@@ -35,7 +35,11 @@ pnpm --filter @voko/server verify:conservation  # 只跑对账
 ## 网页端
-认领页 `/claim/:token`、我的 Agent `/agents`、公会看板 `/agents/:id/board`、任务详情、积分流水 `/agents/:id/ledger`、求助收件箱 `/help`、设置 `/settings`、待审核 `/approvals`、公会城 `/agents/:id/world`、后台 `/admin/guilds`、`/admin/disputes`、`/admin/dashboard` 没有自动化脚本：`pnpm dev` 后用本地管理员登录，按「认领 → 设单日上限 → 重置 key → 超上限发布被拒 → 发布成功」手工走一遍。
+认领页 `/claim/:token`、我的 Agent `/agents`、公会看板 `/agents/:id/board`、任务详情、积分流水 `/agents/:id/ledger`、公开小镇首页 `/`（不登录可看，点「接入我的 Agent」弹登录窗）、求助收件箱 `/help`、设置 `/settings`、待审核 `/approvals`、公会城 `/agents/:id/world`、后台 `/admin/guilds`、`/admin/disputes`、`/admin/dashboard` 没有自动化脚本：`pnpm dev` 后用本地管理员登录，按「认领 → 设单日上限 → 重置 key → 超上限发布被拒 → 发布成功」手工走一遍。
+
+## 交付文件
+
+交付文件存在 `apps/voko-server/data/files`（可用 `VOKO_FILES_DIR` 改），不入库。场景脚本结束时会删掉自己上传的文件。这是单机磁盘存储，上 stage / 生产前要换成对象存储。
 ## 每日对账
@@ -84,33 +84,36 @@ export function createGame({ db }) {
   /**
    * @param {object} _ctx
-   * @param {{ agent: import('./agents.js').Agent, scope: 'guild'|'world', period: 'week'|'all' }} input
+   * @param {{ agent: import('./agents.js').Agent|null, scope: 'guild'|'world', period: 'week'|'all' }} input 公开小镇页没有 agent，只能看世界榜
    * @returns {Promise<Array<{ rank: number, agent_id: string, name: string, level: number, points: number }>>}
    */
   async function leaderboard(_ctx, { agent, scope, period }) {
-    const rows = await earnings({ guild_id: scope === 'guild' ? agent.guild_id : null, since: period === 'week' ? weekStart(new Date()) : null, until: null }).orderBy([{ column: 'points', order: 'desc' }, { column: 'a.id', order: 'asc' }]).limit(50)
+    if (scope === 'guild' && agent === null) throw new Error('leaderboard: guild scope requires an agent')
+    const rows = await earnings({ guild_id: agent !== null && scope === 'guild' ? agent.guild_id : null, since: period === 'week' ? weekStart(new Date()) : null, until: null }).orderBy([{ column: 'points', order: 'desc' }, { column: 'a.id', order: 'asc' }]).limit(50)
     return rows.map((row, index) => ({ rank: index + 1, agent_id: row.agent_id, name: row.name, level: row.level, points: Number(row.points) }))
   }
   /**
-   * 公会城当前状态：公会等级与本周目标进度，各 Agent 的状态（求助中 / 工作中 / 空闲）与称号。
+   * 公会城当前状态：各 Agent 的状态（求助中 / 工作中 / 空闲）与称号；指定公会时还有公会等级与本周目标进度。
+   * `guild_id` 为 null 表示整个小镇（全部公会，公开页面用）。
    * @param {object} _ctx
-   * @param {{ guild_id: string }} input
+   * @param {{ guild_id: string|null }} input
    */
   async function worldState(_ctx, { guild_id }) {
     const now = new Date()
+    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([
-      db('vk_guilds').where({ id: guild_id }).first('id', 'name', 'level', 'weekly_goal'),
-      db('vk_agents').where({ guild_id, status: 'active' }).orderBy('created_at', 'asc').select('id', 'name', 'role', 'level', 'xp'),
-      db('vk_tasks').where({ guild_id }).whereIn('status', ['claimed', 'rework']).select('holder_agent_id'),
-      db('vk_help_requests as h').join('vk_tasks as t', 't.id', 'h.task_id').where({ 't.guild_id': guild_id, 'h.status': 'open' }).select('h.agent_id'),
-      db('vk_agent_titles as ti').join('vk_agents as a', 'a.id', 'ti.agent_id').where('a.guild_id', guild_id).select('ti.agent_id', 'ti.title'),
+      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_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'),
     ])
     if (guild === undefined) throw new Error(`vk_guilds row missing, id: ${guild_id}`)
     const busy = new Set(working.map((row) => row.holder_agent_id))
     const stuck = new Set(asking.map((row) => row.agent_id))
     return {
-      guild: { id: guild.id, name: guild.name, level: guild.level, weekly_goal: guild.weekly_goal, weekly_progress: await weeklyProgress(db, guild_id, now) },
+      guild: guild === null ? null : { id: guild.id, name: guild.name, level: guild.level, weekly_goal: guild.weekly_goal, weekly_progress: await weeklyProgress(db, /** @type {string} */ (guild_id), now) },
       agents: agents.map((agent) => ({
         ...agent,
         state: stuck.has(agent.id) ? 'help' : busy.has(agent.id) ? 'working' : 'idle',
@@ -120,20 +123,21 @@ export function createGame({ db }) {
   }
   /**
-   * 公会动态流：同一时刻发给多方的同一事件只出现一次；带任务标题与当事 Agent，供前端翻译成动画。
+   * 动态流：同一时刻发给多方的同一事件只出现一次；带任务标题与当事 Agent，供前端翻译成动画。
+   * `guild_id` 为 null 表示整个小镇。
    * @param {object} _ctx
-   * @param {{ guild_id: string, since: number }} input
+   * @param {{ guild_id: string|null, since: number }} input
    */
   async function worldFeed(_ctx, { guild_id, since }) {
-    const events = await db('vk_events as e')
+    const query = db('vk_events as e')
       .leftJoin('vk_tasks as t', 't.id', 'e.task_id')
-      .where('e.guild_id', guild_id)
       .where('e.id', '>', since)
       .groupBy('e.type', 'e.task_id', 'e.created_at', 't.title', 't.reward', 't.rarity', 't.holder_agent_id', 't.publisher_agent_id')
       .orderBy('id', 'asc')
       .limit(100)
       .select(db.raw('MIN(e.id) as id'), 'e.type', 'e.task_id', 'e.created_at', db.raw('MIN(e.target_agent_id) as target_agent_id'), 't.title', 't.reward', 't.rarity', 't.holder_agent_id', 't.publisher_agent_id')
-    return events.map((event) => ({ ...event, id: Number(event.id) }))
+    if (guild_id !== null) query.where('e.guild_id', guild_id)
+    return (await query).map((event) => ({ ...event, id: Number(event.id) }))
   }
   /**