feat: W4 第二部分——Webhook、每日对账 job、任务详情 / 流水 / 求助收件箱 / 设置页

- @voko/access：Webhook 登记（仅 https + 公网地址，secret 加密存储）、签名投递与 1m/5m/30m/2h 重试 - 事件写入时给登记了 Webhook 的 Agent 排投递；worker 每轮投递到期项 - 对账函数移入 @voko/clearing，worker 每天 UTC 01:00 跑一次 - 网页：任务详情、积分流水、求助收件箱、设置 - 场景 webhook（WH-03）；运行手册更新 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

feat: W4 第二部分——Webhook、每日对账 job、任务详情 / 流水 / 求助收件箱 / 设置页
- @voko/access：Webhook 登记（仅 https + 公网地址，secret 加密存储）、签名投递与 1m/5m/30m/2h 重试 - 事件写入时给登记了 Webhook 的 Agent 排投递；worker 每轮投递到期项 - 对账函数移入 @voko/clearing，worker 每天 UTC 01:00 跑一次 - 网页：任务详情、积分流水、求助收件箱、设置 - 场景 webhook（WH-03）；运行手册更新 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
yibo
1 parent 310d07ad
Showing 28 changed files with 752 additions and 101 deletions
apps/voko-server/.env.example
apps/voko-server/package.json
apps/voko-server/src/assembly/runtime.js
apps/voko-server/src/env.js
apps/voko-server/src/routes/owner.js
apps/voko-server/src/routes/v1.js
apps/voko-server/src/voko-worker-main.js
apps/voko-server/tools/scenarios/voko-alpha/_lib.mjs
apps/voko-server/tools/scenarios/voko-alpha/verify-conservation.mjs
apps/voko-server/tools/scenarios/voko-alpha/webhook.mjs
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/BoardPage.vue
apps/voko-web/src/pages/HelpPage.vue
apps/voko-web/src/pages/LedgerPage.vue
apps/voko-web/src/pages/SettingsPage.vue
apps/voko-web/src/pages/TaskPage.vue
docs/runbooks/verify-alpha.md
packages/voko-access/src/index.js
@@ -6,6 +6,8 @@ LOG_LEVEL=info
 DATABASE_URL=
 # 生产必须设置，开发缺省使用固定开发值
 AUTH_TOKEN_SECRET=
+# 加密存储各 Agent 的 Webhook 签名 secret。生产必须设置，换掉后已登记的 Webhook 需重新登记
+WEBHOOK_SECRET_KEY=
 # 前端地址，用于邮件里的链接
 PUBLIC_URL=http://localhost:5201
 # 发信（验证码、申请通过通知）。缺任何一项服务拒绝启动。
@@ -18,6 +18,7 @@
     "verify:f2": "node tools/scenarios/voko-alpha/f2-execute.mjs",
     "verify:f3": "node tools/scenarios/voko-alpha/f3-review-settle.mjs",
     "verify:e2e": "node tools/scenarios/voko-alpha/e2e-loop.mjs",
+    "verify:webhook": "node tools/scenarios/voko-alpha/webhook.mjs",
     "verify:timers": "node tools/scenarios/voko-alpha/timers.mjs",
     "verify:concurrency": "node tools/scenarios/voko-alpha/concurrency.mjs",
     "verify:conservation": "node tools/scenarios/voko-alpha/verify-conservation.mjs"
@@ -9,9 +9,9 @@ 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, nextAllowedSendTime } from '@voko/access'
+import { createAccessRequests, createAgentAccess, createOwnerSettings, createWebhooks, nextAllowedSendTime } from '@voko/access'
 import { createMemoryStore, createRateLimiter } from '@drama/ratelimit'
-import { createEscrow, createTips } from '@voko/clearing'
+import { createEscrow, createTips, verifyConservation } from '@voko/clearing'
 import { createAgents, createEvents, createGuilds, createHelp, createJobs, createJudge, createTasks } from '@voko/exchange'
  
 import { readEnv } from '../env.js'
@@ -68,7 +68,8 @@ export async function createRuntime({ service }) {
     },
   })
   const tips = createTips({ db })
-  const jobs = createJobs({ db, tasks, help, logger })
+  const webhooks = createWebhooks({ db, secret_key: env.webhookSecretKey })
+  const jobs = createJobs({ db, tasks, help, conservationProblems: () => verifyConservation(db), logger })
  
   /**
    * 给已结算任务的赢家打赏；收款事件与动账同事务。
@@ -134,7 +135,7 @@ export async function createRuntime({ service }) {
   return {
     env,
     logger,
-    services: { db, auth, userRepo, access, agents, guilds, agentAccess, escrow, tasks, events, jobs, help, ownerSettings, tipTask, rateLimiter, register, oauthEnabled: env.oauth.googleClientId !== null },
+    services: { db, auth, userRepo, access, agents, guilds, agentAccess, escrow, tasks, events, jobs, help, ownerSettings, webhooks, tipTask, rateLimiter, register, oauthEnabled: env.oauth.googleClientId !== null },
     async close() {
       await db.destroy()
     },
@@ -11,6 +11,7 @@ import { devMysqlUrl } from &#39;@drama/db&#39;
  *   databaseUrl: string,
  *   logLevel: 'debug'|'info'|'warn'|'error',
  *   authTokenSecret: string,
+ *   webhookSecretKey: string,
  *   publicUrl: string,
  *   email: { host: string, port: number, secure: boolean, user: string, pass: string, from: string },
  *   oauth: { googleClientId: string|null, googleClientSecret: string|null },
@@ -28,6 +29,7 @@ export function readEnv(rawEnv) {
   const scheme = new URL(databaseUrl).protocol
   if (scheme !== 'mysql:' && scheme !== 'mysql2:') throw new Error(`voko-server: DATABASE_URL 必须是 MySQL，收到 ${scheme}`)
   if (nodeEnv === 'production' && !rawEnv.AUTH_TOKEN_SECRET) throw new Error('voko-server: 生产环境必须设置 AUTH_TOKEN_SECRET')
+  if (nodeEnv === 'production' && !rawEnv.WEBHOOK_SECRET_KEY) throw new Error('voko-server: 生产环境必须设置 WEBHOOK_SECRET_KEY')
  
   const email = {
     host: rawEnv.SMTP_HOST,
@@ -52,6 +54,7 @@ export function readEnv(rawEnv) {
     databaseUrl,
     logLevel: parseLogLevel(rawEnv.LOG_LEVEL),
     authTokenSecret: rawEnv.AUTH_TOKEN_SECRET || 'voko-dev-token-secret',
+    webhookSecretKey: rawEnv.WEBHOOK_SECRET_KEY || 'voko-dev-webhook-secret-key',
     publicUrl: (rawEnv.PUBLIC_URL || 'http://localhost:5201').replace(/\/$/, ''),
     email: /** @type {VokoEnv['email']} */ (email),
     llm: /** @type {VokoEnv['llm']} */ (llm),
@@ -5,7 +5,7 @@ import { agentView, IdempotencyKey, ledgerView, PublishBody, REFUSAL_STATUS, tas
  
 const AgentParams = v.object({ id: v.pipe(v.string(), v.minLength(1), v.maxLength(64)) })
 const LimitBody = v.object({ daily_spend_limit: v.nullable(v.pipe(v.number(), v.safeInteger(), v.minValue(0))) })
-const TaskIdParams = v.object({ task_id: v.pipe(v.string(), v.minLength(1), v.maxLength(64)) })
+const TaskIdParams = v.object({ id: v.optional(v.string()), task_id: v.pipe(v.string(), v.minLength(1), v.maxLength(64)) })
 const ApprovalBody = v.object({ decision: v.picklist(['approve', 'reject']) })
 const ResolveBody = v.object({ outcome: v.picklist(['settled', 'refunded']), winner_agent_id: v.optional(v.pipe(v.string(), v.minLength(1), v.maxLength(64))) })
 const HelpParams = v.object({ id: v.pipe(v.string(), v.minLength(1), v.maxLength(64)) })
@@ -30,6 +30,58 @@ export function registerOwnerRoutes(app, services) {
   const { agents, agentAccess, guilds, escrow, tasks, help, ownerSettings, db } = services
  
   /**
+   * 业务拒绝 → 网页接口的错误形状。
+   * @param {import('fastify').FastifyReply} reply
+   * @param {{ code: keyof typeof REFUSAL_STATUS, hint: string }} refusal
+   */
+  const refused = (reply, refusal) => reply.code(REFUSAL_STATUS[refusal.code]).send({ error: { code: refusal.code, message: refusal.hint, retryable: false } })
+
+  // 任务详情：以自己某个 Agent 的身份查看（可见范围与该 Agent 调公开 API 相同）。
+  app.get('/api/voko/agents/:id/tasks/:task_id', async (request, reply) => {
+    const { agent } = await ownAgent(request)
+    const params = v.parse(TaskIdParams, request.params)
+    const result = await tasks.get(request.ctx, { agent, task_id: params.task_id })
+    if (!result.ok) return refused(reply, result)
+    const comments = await tasks.listComments(request.ctx, { agent, task_id: params.task_id })
+    if (!comments.ok) return refused(reply, comments)
+    const iso = (/** @type {{ created_at: Date }} */ row) => ({ ...row, created_at: row.created_at.toISOString() })
+    return { task: taskView(result.task), acceptance: result.acceptance, entry_count: result.entry_count, checkpoints: result.checkpoints.map(iso), submissions: result.submissions.map(iso), comments: comments.comments.map(iso) }
+  })
+
+  app.get('/api/voko/agents/:id/ledger', async (request) => {
+    const { agent } = await ownAgent(request)
+    return { ledger: (await escrow.ledgerOf(request.ctx, { wallet_user_id: agent.wallet_user_id, limit: 100 })).map(ledgerView) }
+  })
+
+  // 求助收件箱：主人回复自己 Agent 的求助。
+  app.get('/api/voko/help', async (request) => {
+    const user = await requireUser(request, services)
+    const rows = await help.listForOwner(request.ctx, { user_id: user.id })
+    return { help_requests: rows.map((row) => ({ ...row, created_at: row.created_at.toISOString(), answered_at: row.answered_at === null ? null : row.answered_at.toISOString() })) }
+  })
+
+  app.post('/api/voko/help/:id/answer', async (request, reply) => {
+    const user = await requireUser(request, services)
+    const params = v.parse(HelpParams, request.params)
+    const body = v.parse(AnswerBody, request.body)
+    const result = await help.answer(request.ctx, { user_id: user.id, help_id: params.id, answer: body.answer })
+    return result.ok ? { ok: true } : refused(reply, result)
+  })
+
+  // 设置：时区、安静时段、邮件开关。
+  app.get('/api/voko/me/settings', async (request) => {
+    const user = await requireUser(request, services)
+    return { settings: await ownerSettings.get(request.ctx, { user_id: user.id }) }
+  })
+
+  app.put('/api/voko/me/settings', async (request) => {
+    const user = await requireUser(request, services)
+    const settings = v.parse(SettingsBody, request.body)
+    await ownerSettings.save(request.ctx, { user_id: user.id, settings })
+    return { settings }
+  })
+
+  /**
    * 取当前用户名下的一个 Agent；不是自己的按不存在处理。
    * @param {import('fastify').FastifyRequest} request
    */
@@ -94,46 +146,6 @@ export function registerOwnerRoutes(app, services) {
     return { task: taskView(result.task) }
   })
  
-  /**
-   * 业务拒绝 → 网页接口的错误形状。
-   * @param {import('fastify').FastifyReply} reply
-   * @param {{ code: keyof typeof REFUSAL_STATUS, hint: string }} refusal
-   */
-  const refused = (reply, refusal) => reply.code(REFUSAL_STATUS[refusal.code]).send({ error: { code: refusal.code, message: refusal.hint, retryable: false } })
-
-  app.get('/api/voko/agents/:id/ledger', async (request) => {
-    const { agent } = await ownAgent(request)
-    return { ledger: (await escrow.ledgerOf(request.ctx, { wallet_user_id: agent.wallet_user_id, limit: 100 })).map(ledgerView) }
-  })
-
-  // 求助收件箱：主人回复自己 Agent 的求助。
-  app.get('/api/voko/help', async (request) => {
-    const user = await requireUser(request, services)
-    const rows = await help.listForOwner(request.ctx, { user_id: user.id })
-    return { help_requests: rows.map((row) => ({ ...row, created_at: row.created_at.toISOString(), answered_at: row.answered_at === null ? null : row.answered_at.toISOString() })) }
-  })
-
-  app.post('/api/voko/help/:id/answer', async (request, reply) => {
-    const user = await requireUser(request, services)
-    const params = v.parse(HelpParams, request.params)
-    const body = v.parse(AnswerBody, request.body)
-    const result = await help.answer(request.ctx, { user_id: user.id, help_id: params.id, answer: body.answer })
-    return result.ok ? { ok: true } : refused(reply, result)
-  })
-
-  // 设置：时区、安静时段、邮件开关。
-  app.get('/api/voko/me/settings', async (request) => {
-    const user = await requireUser(request, services)
-    return { settings: await ownerSettings.get(request.ctx, { user_id: user.id }) }
-  })
-
-  app.put('/api/voko/me/settings', async (request) => {
-    const user = await requireUser(request, services)
-    const settings = v.parse(SettingsBody, request.body)
-    await ownerSettings.save(request.ctx, { user_id: user.id, settings })
-    return { settings }
-  })
-
   // 负责人：待审核任务（公司 Agent 发布、公会开启发布前审核时）。
   app.get('/api/voko/approvals', async (request) => {
     const user = await requireUser(request, services)
@@ -62,7 +62,7 @@ export const IdempotencyKey = v.pipe(v.string(&#39;Idempotency-Key header is require
 export const REFUSAL_STATUS = Object.freeze({ not_found: 404, forbidden: 403, state_conflict: 409, rule_violation: 422 })
 const SKILL_VERSION = '0.1.0'
  
-const UpdateMeBody = v.object({ description: v.optional(Description), skills: v.optional(Skills) })
+const UpdateMeBody = v.object({ description: v.optional(Description), skills: v.optional(Skills), webhook_url: v.optional(v.nullable(v.pipe(v.string(), v.url(), v.maxLength(2048)))) })
  
 /**
  * 公开 API `/v1`：Agent 用 api_key 调用。统一返回 `{ok:true,data}` / `{ok:false,error:{code,message,hint}}`。
@@ -70,7 +70,7 @@ const UpdateMeBody = v.object({ description: v.optional(Description), skills: v.
  * @param {Record<string, any>} services
  */
 export function registerV1Routes(app, services) {
-  const { agentAccess, agents, db, tasks, events, escrow, help, tipTask, rateLimiter } = services
+  const { agentAccess, agents, db, tasks, events, escrow, help, tipTask, webhooks, rateLimiter } = services
  
   app.register(async (v1) => {
     v1.setErrorHandler((/** @type {any} */ err, request, reply) => {
@@ -125,10 +125,14 @@ export function registerV1Routes(app, services) {
  
     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.')
+      if (body.description === undefined && body.skills === undefined && body.webhook_url === undefined) return fail(reply, 400, 'invalid_request', 'Nothing to update', 'Send description, skills and/or webhook_url.')
       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 })))
+      // 登记 Webhook 时返回签名 secret，仅此一次。
+      const hook = body.webhook_url === undefined ? null : await webhooks.register(request.ctx, { agent_id: agentId, webhook_url: body.webhook_url })
+      if (hook !== null && !hook.ok) return fail(reply, 400, 'invalid_request', 'webhook_url is not allowed', hook.hint)
+      if (body.description !== undefined || body.skills !== undefined) await agents.updateProfile(request.ctx, db, { agent_id: agentId, description: body.description, skills: body.skills })
+      const view = agentView(await agents.getById(request.ctx, db, { agent_id: agentId }))
+      return ok(hook === null || hook.webhook_secret === null ? view : { ...view, webhook_secret: hook.webhook_secret })
     })
  
     v1.get('/home', async (request) => {
 /**
- * `voko-worker` 进程入口：每 2 秒领取并执行到期的 vk_jobs（见 SDD「定时任务与事件」）。
+ * `voko-worker` 进程入口：每 2 秒领取并执行到期的 vk_jobs，并投递到期的 Webhook（见 SDD「定时任务与事件」）。
  */
  
 import { createRuntime } from './assembly/runtime.js'
@@ -13,7 +13,9 @@ let stopping = false
  
 async function tick() {
   await runtime.services.jobs.runDue({})
+  await runtime.services.webhooks.deliverDue({})
   ticks += 1
+  if (ticks % HEARTBEAT_EVERY_TICKS === 1) await runtime.services.jobs.ensureDaily({})
   if (ticks % HEARTBEAT_EVERY_TICKS === 0) runtime.logger.info('worker 心跳', { ticks })
 }
  
@@ -7,9 +7,9 @@
 import { randomUUID } from 'node:crypto'
 import { createBillingRepo, createLedger } from '@drama/billing'
 import { createDb } from '@drama/db'
+import { verifyConservation } from '@voko/clearing'
  
 import { databaseUrlFromArgs } from '../../../src/db/env-file.js'
-import { verifyConservation } from './verify-conservation.mjs'
  
 const api = (process.env.VOKO_API || 'http://localhost:9201').replace(/\/$/, '')
  
@@ -162,6 +162,7 @@ function createWorld(name, db) {
       await db('vk_tasks').whereIn('id', taskIds).del()
     }
     if (guildIds.length > 0) {
+      await db('vk_webhook_deliveries').whereIn('event_id', db('vk_events').whereIn('guild_id', guildIds).select('id')).del()
       await db('vk_events').whereIn('guild_id', guildIds).del()
       await db('vk_guild_members').whereIn('guild_id', guildIds).del()
       await db('vk_guilds').whereIn('id', guildIds).del()
@@ -2,45 +2,14 @@
 /**
  * 对账（SDD「积分清算」）：① 已关闭托管的发放明细之和 = 托管金额；② held 托管都对应未结束的任务，
  * 未结束的任务都有 held 托管；③ 每笔 voko 流水的 ref 都能找到业务记录。
- * 任一不满足即失败并打印数据 id。可单独运行，也在每个场景脚本末尾运行。
+ * 任一不满足即失败并打印数据 id。可单独运行；每个场景脚本末尾与 worker 的每日 job 调用同一个函数。
  */
 import { fileURLToPath } from 'node:url'
 import { createDb } from '@drama/db'
+import { verifyConservation } from '@voko/clearing'
  
 import { databaseUrlFromArgs } from '../../../src/db/env-file.js'
  
-const TERMINAL = ['settled', 'cancelled', 'refunded']
-
-/**
- * @param {import('knex').Knex} db
- * @returns {Promise<Array<{ rule: string, id: string, detail: string }>>}
- */
-export async function verifyConservation(db) {
-  const problems = []
-  const closed = await db('vk_escrows as e')
-    .leftJoin('vk_escrow_payouts as p', 'p.escrow_id', 'e.id')
-    .whereNot('e.status', 'held')
-    .groupBy('e.id', 'e.amount')
-    .havingRaw('COALESCE(SUM(p.amount), 0) <> e.amount')
-    .select('e.id', 'e.amount', db.raw('COALESCE(SUM(p.amount), 0) as paid'))
-  for (const row of closed) problems.push({ rule: 'payouts_sum', id: row.id, detail: `amount=${row.amount}, payouts=${row.paid}` })
-
-  const heldOnEnded = await db('vk_escrows as e').join('vk_tasks as t', 't.id', 'e.task_id').where('e.status', 'held').whereIn('t.status', TERMINAL).select('e.id', 't.status')
-  for (const row of heldOnEnded) problems.push({ rule: 'held_on_ended_task', id: row.id, detail: `task status=${row.status}` })
-  const openWithoutHeld = await db('vk_tasks as t')
-    .leftJoin('vk_escrows as e', (join) => join.on('e.task_id', 't.id').andOnVal('e.status', 'held'))
-    .whereNotIn('t.status', TERMINAL)
-    .whereNull('e.id')
-    .select('t.id', 't.status')
-  for (const row of openWithoutHeld) problems.push({ rule: 'active_task_without_held_escrow', id: row.id, detail: `task status=${row.status}` })
-
-  const orphanTaskRefs = await db('billing_ledger as l').leftJoin('vk_tasks as t', 't.id', 'l.ref_id').where({ 'l.source': 'voko', 'l.ref_type': 'vk_task' }).whereNull('t.id').select('l.id', 'l.ref_id')
-  const orphanAgentRefs = await db('billing_ledger as l').leftJoin('vk_agents as a', 'a.id', 'l.ref_id').where({ 'l.source': 'voko', 'l.ref_type': 'vk_agent' }).whereNull('a.id').select('l.id', 'l.ref_id')
-  const orphanTipRefs = await db('billing_ledger as l').leftJoin('vk_tips as p', 'p.id', 'l.ref_id').where({ 'l.source': 'voko', 'l.ref_type': 'vk_tip' }).whereNull('p.id').select('l.id', 'l.ref_id')
-  for (const row of [...orphanTaskRefs, ...orphanAgentRefs, ...orphanTipRefs]) problems.push({ rule: 'ledger_ref_missing', id: row.id, detail: `ref_id=${row.ref_id}` })
-  return problems
-}
-
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
   const db = createDb({ url: databaseUrlFromArgs(process.argv.slice(2)), pool: { min: 1, max: 1 } })
   try {
+#!/usr/bin/env node
+/**
+ * Webhook 的真实链路脚本。目前覆盖 WH-03（非 https、回环、内网、元数据地址一律拒绝）与登记 / 取消。
+ * WH-01、WH-02 需要一个公网可达的 HTTPS 接收端（平台拒绝向回环与内网地址投递，本机起的接收服务收不到），
+ * 在 stage 环境验收；签名算法由 packages/voko-access/test/webhooks.test.js 覆盖。
+ */
+import { runScenario } from './_lib.mjs'
+
+await runScenario('wh', async ({ db, check, call, createOwner, createGuild, createAgent }) => {
+  const alice = await createOwner('alice')
+  const guild = await createGuild('main', alice.user_id)
+  const agent = await createAgent('hooked', alice, guild)
+  const register = (webhook_url) => call('PATCH', '/v1/agents/me', { token: agent.key, body: { webhook_url } })
+
+  for (const url of ['http://example.com/hook', 'https://127.0.0.1/hook', 'https://localhost/hook', 'https://10.0.0.5/hook', 'https://192.168.1.10/hook', 'https://169.254.169.254/latest/meta-data', 'https://[::1]/hook', 'https://user:pass@example.com/hook', 'https://no-such-host.invalid/hook']) {
+    const refused = await register(url)
+    check(`WH-03 ${url} → 400`, refused.status === 400 && refused.json.error.code === 'invalid_request' && typeof refused.json.error.hint === 'string', refused)
+  }
+  const stored = await db('vk_agents').where({ id: agent.id }).first('webhook_url', 'webhook_secret_enc')
+  check('被拒绝的地址没有落库', stored.webhook_url === null && stored.webhook_secret_enc === null, stored)
+
+  // 登记一个公网 https 地址后立刻取消，期间不产生任何事件，所以不会真的向它发请求。
+  // 用 IP 字面量：开发机若开着 fake-ip 代理，域名会被解析到 198.18.0.0/15 保留段而被（正确地）拒绝。
+  const ok = await register('https://1.1.1.1/voko-hook')
+  const row = await db('vk_agents').where({ id: agent.id }).first('webhook_url', 'webhook_secret_enc')
+  check('公网 https 地址登记成功，secret 只返回一次且加密存储', ok.status === 200 && /^[0-9a-f]{64}$/.test(ok.json.data.webhook_secret) && row.webhook_url === 'https://1.1.1.1/voko-hook' && !row.webhook_secret_enc.includes(ok.json.data.webhook_secret), ok)
+  const me = await call('GET', '/v1/agents/me', { token: agent.key })
+  check('之后的接口不再返回 secret', !JSON.stringify(me.json).includes(ok.json.data.webhook_secret), me)
+  const cleared = await register(null)
+  const after = await db('vk_agents').where({ id: agent.id }).first('webhook_url', 'webhook_secret_enc')
+  check('取消登记', cleared.status === 200 && after.webhook_url === null && after.webhook_secret_enc === null, cleared)
+})
@@ -69,6 +69,45 @@ export const messages = {
       approve: 'Approve',
       reject: 'Reject and refund',
     },
+    help: {
+      title: 'Help inbox',
+      empty: 'None of your agents has asked for help.',
+      task: 'Task: {title}',
+      answer: 'Your reply',
+      send: 'Send reply',
+      yourAnswer: 'Your reply:',
+      status: { open: 'Waiting for you', answered: 'Answered' },
+    },
+    settings: {
+      title: 'Settings',
+      timezone: 'Time zone (IANA name, e.g. Asia/Shanghai)',
+      useBrowserZone: 'Use this browser\'s time zone',
+      quietHint: 'During quiet hours, help emails wait until quiet hours end. Set both to the same hour for no quiet hours.',
+      quietStart: 'Quiet hours start',
+      quietEnd: 'Quiet hours end',
+      emailHelp: 'Email me when an agent asks for help',
+      emailDigest: 'Email me a daily digest',
+      save: 'Save settings',
+    },
+    ledger: {
+      title: 'Points ledger',
+      empty: 'No entries yet.',
+      when: 'Time',
+      what: 'Entry',
+      amount: 'Points',
+      task: 'View task',
+      reason: { vk_starter: 'Starter points', vk_escrow_hold: 'Held in escrow', vk_task_payout: 'Task reward', vk_relay_share: 'Relay share', vk_escrow_refund: 'Escrow refund', vk_tip: 'Tip', admin_adjustment: 'Operator adjustment' },
+    },
+    task: {
+      back: 'Back to the board',
+      acceptance: 'Acceptance checklist',
+      checkpoints: 'Checkpoints',
+      submissions: 'Submissions',
+      noSubmissions: 'Nothing visible yet. Submissions are shown to the publisher and the submitter; contest entries stay sealed until the deadline.',
+      comments: 'Comments',
+      round: 'Round {round}',
+      none: 'None yet.',
+    },
     board: {
       title: 'Guild board',
       back: 'Back to my agents',
@@ -160,6 +199,45 @@ export const messages = {
       approve: '通过',
       reject: '驳回并退款',
     },
+    help: {
+      title: '求助收件箱',
+      empty: '你的 Agent 还没有求助过。',
+      task: '任务：{title}',
+      answer: '你的回复',
+      send: '发送回复',
+      yourAnswer: '你的回复：',
+      status: { open: '等你回复', answered: '已回复' },
+    },
+    settings: {
+      title: '设置',
+      timezone: '时区（IANA 名称，如 Asia/Shanghai）',
+      useBrowserZone: '使用当前浏览器的时区',
+      quietHint: '安静时段内的求助邮件会推迟到安静时段结束再发。起止设为同一小时表示不设安静时段。',
+      quietStart: '安静时段开始',
+      quietEnd: '安静时段结束',
+      emailHelp: 'Agent 求助时给我发邮件',
+      emailDigest: '每天给我发日报',
+      save: '保存设置',
+    },
+    ledger: {
+      title: '积分流水',
+      empty: '还没有流水。',
+      when: '时间',
+      what: '事项',
+      amount: '积分',
+      task: '查看任务',
+      reason: { vk_starter: '启动积分', vk_escrow_hold: '冻结进托管', vk_task_payout: '任务收入', vk_relay_share: '接力分成', vk_escrow_refund: '托管退回', vk_tip: '打赏', admin_adjustment: '运营调账' },
+    },
+    task: {
+      back: '返回看板',
+      acceptance: '验收清单',
+      checkpoints: '检查点',
+      submissions: '交付',
+      noSubmissions: '暂无可见的交付。交付只对发布方和提交者本人可见；擂台赛的提交在截止前封存。',
+      comments: '评论',
+      round: '第 {round} 轮',
+      none: '暂无。',
+    },
     board: {
       title: '公会看板',
       back: '返回我的 Agent',
@@ -10,8 +10,12 @@ import AgentsPage from &#39;./pages/AgentsPage.vue&#39;
 import ApprovalsPage from './pages/ApprovalsPage.vue'
 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'
  
 const router = createRouter({
   history: createWebHistory(),
@@ -22,6 +26,10 @@ const router = createRouter({
     { path: '/claim/:token', component: ClaimPage },
     { path: '/agents', component: AgentsPage },
     { path: '/approvals', component: ApprovalsPage },
+    { path: '/help', component: HelpPage },
+    { path: '/settings', component: SettingsPage },
+    { path: '/agents/:id/ledger', component: LedgerPage },
+    { path: '/agents/:id/tasks/:taskId', component: TaskPage },
     { path: '/agents/:id/board', component: BoardPage },
   ],
 })
@@ -66,13 +66,13 @@ onMounted(async () =&gt; {
  
 <template>
   <h1>{{ t('agents.title') }}</h1>
-  <p><router-link to="/approvals">{{ t('agents.approvals') }}</router-link></p>
+  <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>
   <template v-if="agents">
     <p v-if="agents.length === 0">{{ 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>
-      <p><router-link :to="`/agents/${agent.id}/board`">{{ t('agents.board') }}</router-link></p>
+      <p class="voko-nav"><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>
       <div class="voko-actions">
         <Button variant="secondary" @click="saveLimit(agent.id)">{{ t('agents.saveLimit') }}</Button>
@@ -87,6 +87,11 @@ onMounted(async () =&gt; {
 </template>
  
 <style scoped>
+.voko-nav {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--drama-space-md);
+}
 .voko-agent {
   margin-bottom: var(--drama-space-md);
 }
@@ -74,7 +74,7 @@ onMounted(async () =&gt; {
   <template v-if="tasks">
     <p v-if="tasks.length === 0">{{ t('board.empty') }}</p>
     <Card v-for="task in tasks" :key="task.id" class="voko-board-card">
-      <h3>{{ task.title }} <Badge :variant="BADGE[task.status]">{{ t(`board.status.${task.status}`) }}</Badge></h3>
+      <h3><router-link :to="`/agents/${route.params.id}/tasks/${task.id}`">{{ task.title }}</router-link> <Badge :variant="BADGE[task.status]">{{ t(`board.status.${task.status}`) }}</Badge></h3>
       <p>{{ t(`board.templates.${task.template}`) }} · {{ t('board.reward', { reward: task.reward }) }} · {{ t('board.rarity', { rarity: task.rarity }) }} · {{ t('board.deadline', { deadline: new Date(task.deadline).toLocaleString() }) }}</p>
       <p class="voko-spec">{{ task.spec }}</p>
     </Card>
+<script setup>
+import { onMounted, reactive, ref } from 'vue'
+import { useI18n } from 'vue-i18n'
+import { useRouter } from 'vue-router'
+import { Badge, Button, Card, Textarea } from '@drama/ui'
+
+import { api, getToken } from '../api.js'
+
+const { t } = useI18n()
+const router = useRouter()
+const requests = ref(null)
+const drafts = reactive({})
+const error = ref('')
+
+async function load() {
+  requests.value = (await api('GET', '/api/voko/help')).help_requests
+}
+
+/** @param {string} id */
+async function answer(id) {
+  error.value = ''
+  try {
+    await api('POST', `/api/voko/help/${id}/answer`, { answer: drafts[id] })
+    await load()
+  } catch (err) {
+    error.value = err instanceof Error ? err.message : String(err)
+  }
+}
+
+onMounted(async () => {
+  if (getToken() === null) {
+    await router.push({ path: '/login', query: { next: '/help' } })
+    return
+  }
+  await load()
+})
+</script>
+
+<template>
+  <h1>{{ t('help.title') }}</h1>
+  <p><router-link to="/agents">{{ t('board.back') }}</router-link></p>
+  <p v-if="error" role="alert">{{ error }}</p>
+  <template v-if="requests">
+    <p v-if="requests.length === 0">{{ t('help.empty') }}</p>
+    <Card v-for="request in requests" :key="request.id" class="voko-help">
+      <h2>{{ request.agent_name }} <Badge :variant="request.status === 'open' ? 'warning' : 'success'">{{ t(`help.status.${request.status}`) }}</Badge></h2>
+      <p>{{ t('help.task', { title: request.task_title }) }} · {{ new Date(request.created_at).toLocaleString() }}</p>
+      <p class="voko-pre">{{ request.question }}</p>
+      <template v-if="request.status === 'open'">
+        <label class="voko-field">{{ t('help.answer') }}<Textarea v-model="drafts[request.id]" :rows="3" /></label>
+        <Button :disabled="!drafts[request.id] || drafts[request.id].trim() === ''" @click="answer(request.id)">{{ t('help.send') }}</Button>
+      </template>
+      <p v-else class="voko-pre"><strong>{{ t('help.yourAnswer') }}</strong> {{ request.answer }}</p>
+    </Card>
+  </template>
+</template>
+
+<style scoped>
+.voko-help {
+  margin-bottom: var(--drama-space-md);
+}
+.voko-pre {
+  white-space: pre-wrap;
+}
+</style>
+<script setup>
+import { onMounted, ref } from 'vue'
+import { useI18n } from 'vue-i18n'
+import { useRoute, useRouter } from 'vue-router'
+import { Card } from '@drama/ui'
+
+import { api, getToken } from '../api.js'
+
+const { t, te } = useI18n()
+const route = useRoute()
+const router = useRouter()
+const ledger = ref(null)
+
+onMounted(async () => {
+  if (getToken() === null) {
+    await router.push({ path: '/login', query: { next: route.fullPath } })
+    return
+  }
+  ledger.value = (await api('GET', `/api/voko/agents/${route.params.id}/ledger`)).ledger
+})
+</script>
+
+<template>
+  <h1>{{ t('ledger.title') }}</h1>
+  <p><router-link to="/agents">{{ t('board.back') }}</router-link></p>
+  <Card v-if="ledger">
+    <p v-if="ledger.length === 0">{{ t('ledger.empty') }}</p>
+    <table v-else class="voko-ledger">
+      <thead>
+        <tr><th scope="col">{{ t('ledger.when') }}</th><th scope="col">{{ t('ledger.what') }}</th><th scope="col" class="voko-amount">{{ t('ledger.amount') }}</th></tr>
+      </thead>
+      <tbody>
+        <tr v-for="row in ledger" :key="row.id">
+          <td>{{ new Date(row.at).toLocaleString() }}</td>
+          <td>
+            {{ te(`ledger.reason.${row.reason}`) ? t(`ledger.reason.${row.reason}`) : row.reason }}
+            <router-link v-if="row.task_id" :to="`/agents/${route.params.id}/tasks/${row.task_id}`">{{ t('ledger.task') }}</router-link>
+          </td>
+          <td class="voko-amount">{{ row.amount > 0 ? `+${row.amount}` : row.amount }}</td>
+        </tr>
+      </tbody>
+    </table>
+  </Card>
+</template>
+
+<style scoped>
+.voko-ledger {
+  width: 100%;
+  border-collapse: collapse;
+}
+.voko-ledger th,
+.voko-ledger td {
+  padding: var(--drama-space-sm);
+  border-bottom: 1px solid var(--drama-color-border);
+  text-align: left;
+}
+.voko-ledger .voko-amount {
+  text-align: right;
+  font-variant-numeric: tabular-nums;
+}
+</style>
+<script setup>
+import { onMounted, ref } from 'vue'
+import { useI18n } from 'vue-i18n'
+import { useRouter } from 'vue-router'
+import { Button, Card, Input, Select } from '@drama/ui'
+
+import { api, getToken } from '../api.js'
+
+const { t } = useI18n()
+const router = useRouter()
+const settings = ref(null)
+const message = ref('')
+const hours = Array.from({ length: 24 }, (_, hour) => ({ value: hour, label: `${String(hour).padStart(2, '0')}:00` }))
+
+async function save() {
+  message.value = ''
+  try {
+    await api('PUT', '/api/voko/me/settings', settings.value)
+    message.value = t('agents.saved')
+  } catch (err) {
+    message.value = err instanceof Error ? err.message : String(err)
+  }
+}
+
+function useBrowserZone() {
+  settings.value.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone
+}
+
+onMounted(async () => {
+  if (getToken() === null) {
+    await router.push({ path: '/login', query: { next: '/settings' } })
+    return
+  }
+  settings.value = (await api('GET', '/api/voko/me/settings')).settings
+})
+</script>
+
+<template>
+  <h1>{{ t('settings.title') }}</h1>
+  <p><router-link to="/agents">{{ t('board.back') }}</router-link></p>
+  <Card v-if="settings">
+    <label class="voko-field">{{ t('settings.timezone') }}<Input v-model="settings.timezone" /></label>
+    <p><Button variant="ghost" @click="useBrowserZone">{{ t('settings.useBrowserZone') }}</Button></p>
+    <p>{{ t('settings.quietHint') }}</p>
+    <div class="voko-field">
+      <span>{{ t('settings.quietStart') }}</span>
+      <Select v-model="settings.quiet_start_hour" :options="hours" :aria-label="t('settings.quietStart')" />
+    </div>
+    <div class="voko-field">
+      <span>{{ t('settings.quietEnd') }}</span>
+      <Select v-model="settings.quiet_end_hour" :options="hours" :aria-label="t('settings.quietEnd')" />
+    </div>
+    <label class="voko-check"><input v-model="settings.email_help" type="checkbox"> {{ t('settings.emailHelp') }}</label>
+    <label class="voko-check"><input v-model="settings.email_digest" type="checkbox"> {{ t('settings.emailDigest') }}</label>
+    <p v-if="message" role="status">{{ message }}</p>
+    <Button @click="save">{{ t('settings.save') }}</Button>
+  </Card>
+</template>
+
+<style scoped>
+.voko-check {
+  display: block;
+  margin-bottom: var(--drama-space-md);
+}
+</style>
+<script setup>
+import { onMounted, ref } from 'vue'
+import { useI18n } from 'vue-i18n'
+import { useRoute, useRouter } from 'vue-router'
+import { Badge, Card } from '@drama/ui'
+
+import { api, getToken } from '../api.js'
+
+const { t } = useI18n()
+const route = useRoute()
+const router = useRouter()
+const detail = ref(null)
+const error = ref('')
+
+const when = (/** @type {string} */ iso) => new Date(iso).toLocaleString()
+
+onMounted(async () => {
+  if (getToken() === null) {
+    await router.push({ path: '/login', query: { next: route.fullPath } })
+    return
+  }
+  try {
+    detail.value = await api('GET', `/api/voko/agents/${route.params.id}/tasks/${route.params.taskId}`)
+  } catch (err) {
+    error.value = err instanceof Error ? err.message : String(err)
+  }
+})
+</script>
+
+<template>
+  <p><router-link :to="`/agents/${route.params.id}/board`">{{ t('task.back') }}</router-link></p>
+  <p v-if="error" role="alert">{{ error }}</p>
+  <template v-if="detail">
+    <h1>{{ detail.task.title }} <Badge>{{ t(`board.status.${detail.task.status}`) }}</Badge></h1>
+    <p>{{ t(`board.templates.${detail.task.template}`) }} · {{ t('board.reward', { reward: detail.task.reward }) }} · {{ t('board.rarity', { rarity: detail.task.rarity }) }} · {{ t('board.deadline', { deadline: when(detail.task.deadline) }) }}</p>
+    <Card class="voko-section">
+      <p class="voko-pre">{{ detail.task.spec }}</p>
+      <h2>{{ t('task.acceptance') }}</h2>
+      <ol><li v-for="item in detail.acceptance" :key="item.id">{{ item.text }}</li></ol>
+    </Card>
+    <Card class="voko-section">
+      <h2>{{ t('task.checkpoints') }}</h2>
+      <p v-if="detail.checkpoints.length === 0">{{ t('task.none') }}</p>
+      <p v-for="item in detail.checkpoints" :key="item.id">{{ when(item.created_at) }} · {{ item.progress }}% · {{ item.note }}</p>
+    </Card>
+    <Card class="voko-section">
+      <h2>{{ t('task.submissions') }}</h2>
+      <p v-if="detail.submissions.length === 0">{{ t('task.noSubmissions') }}</p>
+      <div v-for="item in detail.submissions" :key="item.id">
+        <p>{{ t('task.round', { round: item.round }) }} · {{ when(item.created_at) }}</p>
+        <p class="voko-pre">{{ item.summary }}</p>
+        <ul><li v-for="artifact in item.artifacts" :key="artifact.url"><a :href="artifact.url" rel="noopener noreferrer" target="_blank">{{ artifact.note || artifact.url }}</a></li></ul>
+      </div>
+    </Card>
+    <Card class="voko-section">
+      <h2>{{ t('task.comments') }}</h2>
+      <p v-if="detail.comments.length === 0">{{ t('task.none') }}</p>
+      <p v-for="item in detail.comments" :key="item.id" class="voko-pre">{{ when(item.created_at) }} · {{ item.body }}</p>
+    </Card>
+  </template>
+</template>
+
+<style scoped>
+.voko-section {
+  margin-bottom: var(--drama-space-md);
+}
+.voko-pre {
+  white-space: pre-wrap;
+}
+</style>
@@ -4,7 +4,7 @@
  
 ## 前提
  
-- 本地库已 `pnpm --filter @voko/server db:migrate` 到最新；voko-server 已启动；跑 `f3`、`timers` 时 voko-worker 也要在跑（`pnpm --filter @voko/server worker`）。
+- 本地库已 `pnpm --filter @voko/server db:migrate` 到最新；voko-server 已启动；跑 `f2`、`f3`、`concurrency`、`timers` 时 voko-worker 也要在跑（`pnpm --filter @voko/server worker`）。
 - `apps/voko-server/.env` 配置了真实 SMTP 与大模型（`LLM_*`）；`VOKO_TEST_EMAIL` 是能收信的邮箱；有一个管理员账号（本地 `pnpm dev:user admin@example.test admin123`）。
 - 每个脚本会给测试邮箱的 plus 地址发若干封验证码与审核通过邮件。
  
@@ -14,9 +14,11 @@
 export VOKO_TEST_EMAIL=you@gmail.com VOKO_ADMIN_EMAIL=admin@example.test VOKO_ADMIN_PASSWORD=admin123
 pnpm --filter @voko/server verify:f0            # F0-01–05 入驻，见 verify-f0.md
 pnpm --filter @voko/server verify:f1            # F1-01–08 发布、修改、撤回、评论、发布前审核
-pnpm --filter @voko/server verify:f2            # F2-01、02、03、05、06、07 认领、检查点、接力、转让、提交
-pnpm --filter @voko/server verify:f3            # F3-01–05 验收、结算、接力平分、仲裁（含 AI 意见，真实调用大模型）、擂台赛选赢家（需 worker）
-pnpm --filter @voko/server verify:concurrency   # CC-01 并发认领、CC-02 发布幂等
+pnpm --filter @voko/server verify:f2            # F2-01–07 认领、检查点、求助与回复、接力、转让、提交，TM-06 安静时段（需 worker）
+pnpm --filter @voko/server verify:f3            # F3-01–06 验收、结算、接力平分、仲裁（含 AI 意见，真实调用大模型）、擂台赛选赢家、打赏（需 worker）
+pnpm --filter @voko/server verify:e2e           # E2E-01 注册 → 认领 → 发布 → 接单 → 驳回 → 重交 → 通过 → 打赏
+pnpm --filter @voko/server verify:concurrency   # CC-01 并发认领、CC-02 发布幂等、CC-03 验收与自动确认并发（需 worker）
+pnpm --filter @voko/server verify:webhook       # WH-03 Webhook 地址校验、登记与取消
 pnpm --filter @voko/server verify:timers        # TM-01–05 超时释放、缺检查点、自动确认、AI 选赢家、过期退款（需 worker，真实调用大模型，约 2 分钟）
 pnpm --filter @voko/server verify:conservation  # 只跑对账
 ```
@@ -31,9 +33,16 @@ pnpm --filter @voko/server verify:conservation  # 只跑对账
  
 ## 网页端
  
-认领页 `/claim/:token`、我的 Agent `/agents`、公会看板 `/agents/:id/board`、待审核 `/approvals` 没有自动化脚本：`pnpm dev` 后用本地管理员登录，按「认领 → 设单日上限 → 重置 key → 超上限发布被拒 → 发布成功」手工走一遍。
+认领页 `/claim/:token`、我的 Agent `/agents`、公会看板 `/agents/:id/board`、任务详情、积分流水 `/agents/:id/ledger`、求助收件箱 `/help`、设置 `/settings`、待审核 `/approvals` 没有自动化脚本：`pnpm dev` 后用本地管理员登录，按「认领 → 设单日上限 → 重置 key → 超上限发布被拒 → 发布成功」手工走一遍。
+
+## 每日对账
+
+worker 每天 UTC 01:00 自动跑一次对账（job `verify_conservation`）；不守恒时该 job 失败并在 worker 日志里打出问题数据的 id。手工执行：`pnpm --filter @voko/server verify:conservation`。
  
 ## 尚未覆盖
  
-- W4：F2-04 求助、F3-06 打赏、F0-06、TM-06、CC-03、WH、E2E。
+- WH-01、WH-02（签名投递与重试）：平台拒绝向回环与内网地址投递，本机起的接收服务收不到，需要在 stage 用公网可达的 HTTPS 接收端验收。签名算法与地址判定由 `packages/voko-access/test/webhooks.test.js` 覆盖。
+- F0-06（认领链接 24 小时失效）：认领时已按过期时间拒绝，但 24 小时无法在脚本里真实等待。
+- 日报邮件、排行榜、等级称号、公会城在 W5。
+- 邮件送达只核对投递日志（SMTP 返回成功），没有读真实收件箱。
 - CC-01 用 6 个 Agent 发 20 个并发请求（每个主人最多认领 3 个 Agent）。
@@ -11,4 +11,5 @@ export { createAccessRequests, accessRequestFromRow, ACCESS_REQUEST_STATUSES } f
 export { createAgentAccess, MAX_AGENTS_PER_OWNER, API_KEY_PREFIX } from './agent-access.js'
 export { createOwnerSettings, DEFAULT_OWNER_SETTINGS } from './owner-settings.js'
 export { nextAllowedSendTime } from './quiet-hours.js'
+export { createWebhooks, signWebhook, isPublicAddress } from './webhooks.js'
 export { default as accessDbSchema } from './db/tables/index.cjs'
+import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes } from 'node:crypto'
+import { lookup } from 'node:dns/promises'
+import { BlockList, isIP } from 'node:net'
+
+const DELIVERIES = 'vk_webhook_deliveries'
+const BATCH = 20
+const TIMEOUT_MS = 10_000
+const LEASE_MS = 60_000
+/** 首次失败后的重试间隔：1 分钟、5 分钟、30 分钟、2 小时；之后只留在 /events 里。 */
+const RETRY_AFTER_MS = Object.freeze([60_000, 300_000, 1_800_000, 7_200_000])
+
+// 回环、内网、链路本地（含云元数据 169.254.169.254）、运营商 NAT、组播与保留段一律不投递。
+const NON_PUBLIC = new BlockList()
+for (const [net, prefix] of [['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8], ['169.254.0.0', 16], ['172.16.0.0', 12], ['192.0.0.0', 24], ['192.168.0.0', 16], ['198.18.0.0', 15], ['224.0.0.0', 4], ['240.0.0.0', 4]]) NON_PUBLIC.addSubnet(net, prefix, 'ipv4')
+for (const [net, prefix] of [['::', 127], ['fc00::', 7], ['fe80::', 10], ['ff00::', 8], ['64:ff9b::', 96]]) NON_PUBLIC.addSubnet(net, prefix, 'ipv6')
+
+/**
+ * @param {string} address IPv4 或 IPv6 字面量
+ * @returns {boolean}
+ */
+export function isPublicAddress(address) {
+  const family = isIP(address)
+  if (family === 0) throw new Error(`isPublicAddress: not an IP address: ${address}`)
+  return !NON_PUBLIC.check(address, family === 4 ? 'ipv4' : 'ipv6')
+}
+
+/**
+ * `X-VOKO-Signature` 的值：sha256=HMAC(secret, timestamp + "." + body)。
+ * @param {string} secret
+ * @param {string} timestamp
+ * @param {string} body
+ * @returns {string}
+ */
+export function signWebhook(secret, timestamp, body) {
+  return `sha256=${createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex')}`
+}
+
+/**
+ * Webhook：Agent 登记 HTTPS 地址后，事件写入时生成投递记录，由 worker 签名投递并按退避重试。
+ * Webhook 只是「提醒你来拉」，漏收的事件都能从 /home 或 /events 补到。
+ *
+ * @param {{ db: import('knex').Knex, secret_key: string }} deps `secret_key` 用于加密存储各 Agent 的签名 secret
+ */
+export function createWebhooks({ db, secret_key }) {
+  if (typeof db !== 'function') throw new Error('createWebhooks: db is required')
+  if (typeof secret_key !== 'string' || secret_key === '') throw new Error('createWebhooks: secret_key is required')
+  const key = createHash('sha256').update(secret_key).digest()
+
+  /** @param {string} secret */
+  function encrypt(secret) {
+    const iv = randomBytes(12)
+    const cipher = createCipheriv('aes-256-gcm', key, iv)
+    const data = Buffer.concat([cipher.update(secret, 'utf8'), cipher.final()])
+    return ['v1', iv.toString('base64url'), cipher.getAuthTag().toString('base64url'), data.toString('base64url')].join('.')
+  }
+
+  /** @param {string} stored */
+  function decrypt(stored) {
+    const [version, iv, tag, data] = stored.split('.')
+    if (version !== 'v1') throw new Error(`webhook secret has unknown version: ${version}`)
+    const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(iv, 'base64url'))
+    decipher.setAuthTag(Buffer.from(tag, 'base64url'))
+    return Buffer.concat([decipher.update(Buffer.from(data, 'base64url')), decipher.final()]).toString('utf8')
+  }
+
+  /**
+   * 只允许 HTTPS，且域名解析出的全部地址都必须是公网地址（防 SSRF）。
+   * ponytail: 校验与实际请求各解析一次 DNS，存在重绑定窗口；要堵死就给 fetch 换成固定到已校验 IP 的 dispatcher。
+   * @param {string} webhook_url
+   * @returns {Promise<string|null>} 不合规时返回原因
+   */
+  async function urlProblem(webhook_url) {
+    const url = new URL(webhook_url)
+    if (url.protocol !== 'https:') return 'webhook_url must use https.'
+    if (url.username !== '' || url.password !== '') return 'webhook_url must not contain credentials.'
+    const host = url.hostname.replace(/^\[|\]$/g, '')
+    // 外部 IO 的最小包裹：解析不了的域名是调用方的输入错误，不是程序 bug。
+    let addresses
+    try {
+      addresses = isIP(host) === 0 ? (await lookup(host, { all: true })).map((item) => item.address) : [host]
+    } catch {
+      return 'webhook_url host cannot be resolved.'
+    }
+    return addresses.length > 0 && addresses.every(isPublicAddress) ? null : 'webhook_url must resolve to public addresses only.'
+  }
+
+  /**
+   * 登记或取消（传 null）Webhook。登记成功返回签名 secret，仅此一次。
+   * @param {object} _ctx
+   * @param {{ agent_id: string, webhook_url: string|null }} input
+   * @returns {Promise<{ ok: true, webhook_secret: string|null } | { ok: false, hint: string }>}
+   */
+  async function register(_ctx, { agent_id, webhook_url }) {
+    if (webhook_url === null) {
+      await db('vk_agents').where({ id: agent_id }).update({ webhook_url: null, webhook_secret_enc: null, updated_at: new Date() })
+      return { ok: true, webhook_secret: null }
+    }
+    const problem = await urlProblem(webhook_url)
+    if (problem !== null) return { ok: false, hint: problem }
+    const webhook_secret = randomBytes(32).toString('hex')
+    await db('vk_agents').where({ id: agent_id }).update({ webhook_url, webhook_secret_enc: encrypt(webhook_secret), updated_at: new Date() })
+    return { ok: true, webhook_secret }
+  }
+
+  /**
+   * worker：领取并投递一批到期的 Webhook；返回本轮处理的条数。
+   * @param {object} _ctx
+   * @returns {Promise<number>}
+   */
+  async function deliverDue(_ctx) {
+    const now = new Date()
+    const due = await db.transaction(async (trx) => {
+      const rows = await trx(DELIVERIES).where({ status: 'pending' }).where('next_attempt_at', '<=', now).orderBy('next_attempt_at', 'asc').limit(BATCH).forUpdate().skipLocked()
+      // 把下次尝试时间推后当作租约，避免另一个 worker 同时投递同一条。
+      if (rows.length > 0) await trx(DELIVERIES).whereIn('id', rows.map((row) => row.id)).update({ next_attempt_at: new Date(now.getTime() + LEASE_MS) })
+      return rows
+    })
+    for (const delivery of due) {
+      const failure = await attempt(delivery)
+      if (failure === null) {
+        await db(DELIVERIES).where({ id: delivery.id }).update({ status: 'delivered', attempts: delivery.attempts + 1, next_attempt_at: null, delivered_at: new Date() })
+        continue
+      }
+      const retryAfter = RETRY_AFTER_MS[delivery.attempts]
+      await db(DELIVERIES).where({ id: delivery.id }).update(retryAfter === undefined
+        ? { status: 'failed', attempts: delivery.attempts + 1, next_attempt_at: null }
+        : { attempts: delivery.attempts + 1, next_attempt_at: new Date(Date.now() + retryAfter) })
+    }
+    return due.length
+  }
+
+  /**
+   * 投递一次。成功返回 null，失败返回原因。
+   * @param {{ event_id: number, agent_id: string }} delivery
+   * @returns {Promise<string|null>}
+   */
+  async function attempt(delivery) {
+    const [agent, event] = await Promise.all([
+      db('vk_agents').where({ id: delivery.agent_id }).first('webhook_url', 'webhook_secret_enc'),
+      db('vk_events').where({ id: delivery.event_id }).first('id', 'type', 'task_id', 'created_at'),
+    ])
+    if (agent === undefined || event === undefined) throw new Error(`vk_webhook_deliveries refers to a missing agent or event, event: ${delivery.event_id}, agent: ${delivery.agent_id}`)
+    if (agent.webhook_url === null) return 'webhook was unregistered'
+    const problem = await urlProblem(agent.webhook_url)
+    if (problem !== null) return problem
+    const body = JSON.stringify({ id: String(event.id), type: event.type, created_at: event.created_at.toISOString(), data: { task_id: event.task_id } })
+    const timestamp = String(Math.floor(Date.now() / 1000))
+    // 对外部 IO 的最小包裹：对方不可达、超时、非 2xx 都是预期失败，按退避重试。
+    try {
+      const response = await fetch(agent.webhook_url, {
+        method: 'POST',
+        redirect: 'manual',
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+        headers: {
+          'content-type': 'application/json',
+          'x-voko-event': event.type,
+          'x-voko-delivery': String(event.id),
+          'x-voko-timestamp': timestamp,
+          'x-voko-signature': signWebhook(decrypt(agent.webhook_secret_enc), timestamp, body),
+        },
+        body,
+      })
+      return response.status >= 200 && response.status < 300 ? null : `receiver returned ${response.status}`
+    } catch (err) {
+      return err instanceof Error ? err.message : String(err)
+    }
+  }
+
+  return { register, deliverDue }
+}
+import { createHmac } from 'node:crypto'
+import { describe, expect, it } from 'vitest'
+import { isPublicAddress, signWebhook } from '../src/webhooks.js'
+
+describe('Webhook 签名', () => {
+  it('sha256=HMAC(secret, timestamp + "." + body)，接收方用同一 secret 可验证', () => {
+    const body = '{"id":"42","type":"task.accepted"}'
+    const signature = signWebhook('s3cret', '1791600000', body)
+    expect(signature).toBe(`sha256=${createHmac('sha256', 's3cret').update(`1791600000.${body}`).digest('hex')}`)
+    expect(signature).toMatch(/^sha256=[0-9a-f]{64}$/)
+    expect(signWebhook('s3cret', '1791600001', body)).not.toBe(signature)
+    expect(signWebhook('other', '1791600000', body)).not.toBe(signature)
+  })
+})
+
+describe('Webhook 目标地址（防 SSRF）', () => {
+  it.each(['127.0.0.1', '10.1.2.3', '172.16.0.1', '172.31.255.255', '192.168.1.1', '169.254.169.254', '100.64.0.1', '0.0.0.0', '224.0.0.1', '::1', '::', 'fe80::1', 'fc00::1', 'fd12:3456::1', '::ffff:127.0.0.1', '::ffff:10.0.0.1'])('%s 不是公网地址', (address) => {
+    expect(isPublicAddress(address)).toBe(false)
+  })
+
+  it.each(['8.8.8.8', '1.1.1.1', '172.32.0.1', '93.184.216.34', '2606:4700:4700::1111'])('%s 是公网地址', (address) => {
+    expect(isPublicAddress(address)).toBe(true)
+  })
+
+  it('不是 IP 直接 throw', () => {
+    expect(() => isPublicAddress('example.com')).toThrow(/not an IP address/)
+  })
+})
+/**
+ * 对账（SDD「积分清算」）：① 已关闭托管的发放明细之和 = 托管金额；② held 托管都对应未结束的任务，
+ * 未结束的任务都有 held 托管；③ 每笔 voko 流水的 ref 都能找到业务记录。返回全部不满足项，带数据 id。
+ */
+
+const TERMINAL = ['settled', 'cancelled', 'refunded']
+
+/**
+ * @param {import('knex').Knex} db
+ * @returns {Promise<Array<{ rule: string, id: string, detail: string }>>}
+ */
+export async function verifyConservation(db) {
+  const problems = []
+  const closed = await db('vk_escrows as e')
+    .leftJoin('vk_escrow_payouts as p', 'p.escrow_id', 'e.id')
+    .whereNot('e.status', 'held')
+    .groupBy('e.id', 'e.amount')
+    .havingRaw('COALESCE(SUM(p.amount), 0) <> e.amount')
+    .select('e.id', 'e.amount', db.raw('COALESCE(SUM(p.amount), 0) as paid'))
+  for (const row of closed) problems.push({ rule: 'payouts_sum', id: row.id, detail: `amount=${row.amount}, payouts=${row.paid}` })
+
+  const heldOnEnded = await db('vk_escrows as e').join('vk_tasks as t', 't.id', 'e.task_id').where('e.status', 'held').whereIn('t.status', TERMINAL).select('e.id', 't.status')
+  for (const row of heldOnEnded) problems.push({ rule: 'held_on_ended_task', id: row.id, detail: `task status=${row.status}` })
+  const openWithoutHeld = await db('vk_tasks as t')
+    .leftJoin('vk_escrows as e', (join) => join.on('e.task_id', 't.id').andOnVal('e.status', 'held'))
+    .whereNotIn('t.status', TERMINAL)
+    .whereNull('e.id')
+    .select('t.id', 't.status')
+  for (const row of openWithoutHeld) problems.push({ rule: 'active_task_without_held_escrow', id: row.id, detail: `task status=${row.status}` })
+
+  const orphanTaskRefs = await db('billing_ledger as l').leftJoin('vk_tasks as t', 't.id', 'l.ref_id').where({ 'l.source': 'voko', 'l.ref_type': 'vk_task' }).whereNull('t.id').select('l.id', 'l.ref_id')
+  const orphanAgentRefs = await db('billing_ledger as l').leftJoin('vk_agents as a', 'a.id', 'l.ref_id').where({ 'l.source': 'voko', 'l.ref_type': 'vk_agent' }).whereNull('a.id').select('l.id', 'l.ref_id')
+  const orphanTipRefs = await db('billing_ledger as l').leftJoin('vk_tips as p', 'p.id', 'l.ref_id').where({ 'l.source': 'voko', 'l.ref_type': 'vk_tip' }).whereNull('p.id').select('l.id', 'l.ref_id')
+  for (const row of [...orphanTaskRefs, ...orphanAgentRefs, ...orphanTipRefs]) problems.push({ rule: 'ledger_ref_missing', id: row.id, detail: `ref_id=${row.ref_id}` })
+  return problems
+}
 /**
  * `@voko/clearing` —— VOKO 的积分清算：托管与发放明细；动账一律经 `@drama/billing` 的账本。
  *
- * 托管的冻结、补扣、结算与退回，钱包余额与流水，打赏。
+ * 托管的冻结、补扣、结算与退回，钱包余额与流水，打赏，对账。
  *
  * 边界：不读 `process.env`、不建连接；db 由 composition root 注入。
  */
  
 export { createEscrow } from './escrow.js'
 export { createTips } from './tips.js'
+export { verifyConservation } from './conservation.js'
 export { default as clearingDbSchema } from './db/tables/index.cjs'
+import { insertEvent } from './tasks.js'
+
 const EVENTS = 'vk_events'
 const PAGE = 50
  
@@ -56,7 +58,7 @@ export function createEvents({ db }) {
    * @param {{ guild_id: string, task_id: string, type: string, target_agent_id: string|null }} input
    */
   async function emit(_ctx, trx, { guild_id, task_id, type, target_agent_id }) {
-    await trx(EVENTS).insert({ guild_id, target_agent_id, type, task_id, payload: '{}', created_at: new Date() })
+    await insertEvent(trx, { id: task_id, guild_id }, type, target_agent_id, new Date())
   }
  
   return { pullUnread, listSince, emit }
@@ -22,10 +22,11 @@ const WARN_KINDS = Object.freeze([&#39;checkpoint_warn&#39;, &#39;review_warn&#39;])
  *     arbitrate(ctx: object, input: { task_id: string }): Promise<void>,
  *   },
  *   help: { notify(ctx: object, input: { help_id: string }): Promise<void> },
+ *   conservationProblems(): Promise<Array<{ rule: string, id: string, detail: string }>>,
  *   logger: { error(message: string, fields: object): void },
  * }} deps
  */
-export function createJobs({ db, tasks, help, logger }) {
+export function createJobs({ db, tasks, help, conservationProblems, logger }) {
   if (typeof db !== 'function') throw new Error('createJobs: db is required')
  
   /**
@@ -72,6 +73,12 @@ export function createJobs({ db, tasks, help, logger }) {
    * @param {{ id: string, kind: string, ref_id: string|null }} job
    */
   async function execute(ctx, job) {
+    if (job.kind === 'verify_conservation') {
+      // 每日对账：有任何不守恒就让 job 失败（记错误日志即告警），并附上出问题的数据 id。
+      const problems = await conservationProblems()
+      if (problems.length > 0) throw new Error(`conservation check failed: ${JSON.stringify(problems.slice(0, 20))}`)
+      return
+    }
     if (job.ref_id === null) throw new Error(`vk_jobs.ref_id missing for ${job.kind}, id: ${job.id}`)
     const task_id = job.ref_id
     if (TASK_ACTION_KINDS.includes(job.kind)) return void await tasks.actAsWorker(ctx, { task_id, action: { type: job.kind } })
@@ -90,5 +97,19 @@ export function createJobs({ db, tasks, help, logger }) {
     throw new Error(`Unhandled job kind: ${job.kind}, id: ${job.id}`)
   }
  
-  return { runDue }
+  /**
+   * 确保下一次每日对账（UTC 01:00）已经排上；重复调用无害（dedupe_key 按日期唯一）。
+   * @param {object} _ctx
+   */
+  async function ensureDaily(_ctx) {
+    const now = new Date()
+    const next = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate(), 1))
+    if (next <= now) next.setUTCDate(next.getUTCDate() + 1)
+    await db(JOBS)
+      .insert({ id: `j_conservation_${next.toISOString().slice(0, 10)}`, kind: 'verify_conservation', ref_id: null, run_at: next, status: 'pending', attempts: 0, dedupe_key: `verify_conservation:${next.toISOString().slice(0, 10)}`, created_at: now })
+      .onConflict('dedupe_key')
+      .ignore()
+  }
+
+  return { runDue, ensureDaily }
 }
@@ -686,13 +686,17 @@ async function acceptanceOf(runner, task_id) {
  
 /**
  * @param {import('knex').Knex} trx
- * @param {Task} task
+ * @param {{ id: string, guild_id: string }} task
  * @param {string} type
  * @param {string|null} target_agent_id null 表示发给整个公会
  * @param {Date} now
  */
 export async function insertEvent(trx, task, type, target_agent_id, now) {
-  await trx(EVENTS).insert({ guild_id: task.guild_id, target_agent_id, type, task_id: task.id, payload: '{}', created_at: now })
+  const [event_id] = await trx(EVENTS).insert({ guild_id: task.guild_id, target_agent_id, type, task_id: task.id, payload: '{}', created_at: now })
+  // 给登记了 Webhook 的目标 Agent（公会广播则是全体成员）各排一条投递，由 worker 签名发送。
+  const receivers = trx('vk_agents').whereNotNull('webhook_url').where({ status: 'active' }).where(target_agent_id === null ? { guild_id: task.guild_id } : { id: target_agent_id }).select('id')
+  const deliveries = (await receivers).map((agent) => ({ id: `wd_${randomUUID()}`, event_id, agent_id: agent.id, status: 'pending', attempts: 0, next_attempt_at: now, created_at: now }))
+  if (deliveries.length > 0) await trx('vk_webhook_deliveries').insert(deliveries)
 }
  
 /**
@@ -30,6 +30,6 @@ 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
 export VOKO_ADMIN_EMAIL=admin@example.test VOKO_ADMIN_PASSWORD=admin123
-for scenario in f0 f1 f2 f3 concurrency timers; do
+for scenario in f0 f1 f2 f3 e2e concurrency webhook timers; do
   pnpm --filter @voko/server "verify:$scenario"
 done