feat: improve moderation/admin UX + language-aware quality gate

- API: owner-visible responses for hidden/soft-deleted skills\n- Admin: add unban user mutations + docs\n- Quality: Intl.Segmenter tokenization + CJK signal to reduce false rejects\n- Jobs: skill-stat-events interval 15m -> 5m\n- Tests: add coverage for owner-visible states + non-Latin docs\n- Changelog: add Unreleased entry

Author: steipete

CHANGELOG.md

@@ -2,8 +2,16 @@
 
 ## Unreleased
 
+### Added
+- Admin: add manual unban for banned users (clears `deletedAt` + `banReason`, audit log entry). Revoked API tokens stay revoked.
+
+### Changed
+- Quality gate: language-aware word counting (`Intl.Segmenter`) and new `cjkChars` signal to reduce false rejects for non-Latin docs.
+- Jobs: run skill stat event processing every 5 minutes (was 15).
+
 ### Fixed
 - Users: sync handle on ensure when GitHub login changes (#293) (thanks @christianhpoe).
+- API: for owners, return clearer status/messages for hidden/soft-deleted skills instead of a generic 404.
 
 ## 0.6.1 - 2026-02-13
 

convex/crons.ts

@@ -26,7 +26,7 @@ crons.interval(
 
 crons.interval(
   'skill-stat-events',
-  { minutes: 15 },
+  { minutes: 5 },
   internal.skillStatEvents.processSkillStatEventsAction,
   {},
 )

convex/httpApiV1.handlers.test.ts

@@ -3,13 +3,14 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 vi.mock('./lib/apiTokenAuth', () => ({
   requireApiTokenUser: vi.fn(),
+  getOptionalApiTokenUserId: vi.fn(),
 }))
 
 vi.mock('./skills', () => ({
   publishVersionForUser: vi.fn(),
 }))
 
-const { requireApiTokenUser } = await import('./lib/apiTokenAuth')
+const { getOptionalApiTokenUserId, requireApiTokenUser } = await import('./lib/apiTokenAuth')
 const { publishVersionForUser } = await import('./skills')
 const { __handlers } = await import('./httpApiV1')
 
@@ -59,6 +60,8 @@ const blockedRate = () => ({
 })
 
 beforeEach(() => {
+  vi.mocked(getOptionalApiTokenUserId).mockReset()
+  vi.mocked(getOptionalApiTokenUserId).mockResolvedValue(null)
   vi.mocked(requireApiTokenUser).mockReset()
   vi.mocked(publishVersionForUser).mockReset()
 })
@@ -218,6 +221,52 @@ describe('httpApiV1 handlers', () => {
     expect(response.status).toBe(404)
   })
 
+  it('get skill returns pending-scan message for owner api token', async () => {
+    vi.mocked(getOptionalApiTokenUserId).mockResolvedValue('users:1' as never)
+    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ('slug' in args) {
+        return {
+          _id: 'skills:1',
+          slug: 'demo',
+          ownerUserId: 'users:1',
+          moderationStatus: 'hidden',
+          moderationReason: 'pending.scan',
+        }
+      }
+      return null
+    })
+    const runMutation = vi.fn().mockResolvedValue(okRate())
+    const response = await __handlers.skillsGetRouterV1Handler(
+      makeCtx({ runQuery, runMutation }),
+      new Request('https://example.com/api/v1/skills/demo'),
+    )
+    expect(response.status).toBe(423)
+    expect(await response.text()).toContain('security scan is pending')
+  })
+
+  it('get skill returns undelete hint for owner soft-deleted skill', async () => {
+    vi.mocked(getOptionalApiTokenUserId).mockResolvedValue('users:1' as never)
+    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ('slug' in args) {
+        return {
+          _id: 'skills:1',
+          slug: 'demo',
+          ownerUserId: 'users:1',
+          softDeletedAt: 1,
+          moderationStatus: 'hidden',
+        }
+      }
+      return null
+    })
+    const runMutation = vi.fn().mockResolvedValue(okRate())
+    const response = await __handlers.skillsGetRouterV1Handler(
+      makeCtx({ runQuery, runMutation }),
+      new Request('https://example.com/api/v1/skills/demo'),
+    )
+    expect(response.status).toBe(410)
+    expect(await response.text()).toContain('clawhub undelete demo')
+  })
+
   it('get skill returns payload', async () => {
     const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
       if ('slug' in args) {

convex/httpApiV1.ts

@@ -3,7 +3,7 @@ import { api, internal } from './_generated/api'
 import type { Doc, Id } from './_generated/dataModel'
 import type { ActionCtx } from './_generated/server'
 import { httpAction } from './_generated/server'
-import { requireApiTokenUser } from './lib/apiTokenAuth'
+import { getOptionalApiTokenUserId, requireApiTokenUser } from './lib/apiTokenAuth'
 import { hashToken } from './lib/tokens'
 import { publishVersionForUser } from './skills'
 import { publishSoulVersionForUser } from './souls'
@@ -251,7 +251,11 @@ async function skillsGetRouterV1Handler(ctx: ActionCtx, request: Request) {
 
   if (segments.length === 1) {
     const result = (await ctx.runQuery(api.skills.getBySlug, { slug })) as GetBySlugResult
-    if (!result?.skill) return text('Skill not found', 404, rate.headers)
+    if (!result?.skill) {
+      const hidden = await describeOwnerVisibleSkillState(ctx, request, slug)
+      if (hidden) return text(hidden.message, hidden.status, rate.headers)
+      return text('Skill not found', 404, rate.headers)
+    }
 
     const tags = await resolveTags(ctx, result.skill.tags)
     return json(
@@ -415,6 +419,52 @@ async function skillsGetRouterV1Handler(ctx: ActionCtx, request: Request) {
   return text('Not found', 404, rate.headers)
 }
 
+async function describeOwnerVisibleSkillState(
+  ctx: ActionCtx,
+  request: Request,
+  slug: string,
+): Promise<{ status: number; message: string } | null> {
+  const skill = await ctx.runQuery(internal.skills.getSkillBySlugInternal, { slug })
+  if (!skill) return null
+
+  const apiTokenUserId = await getOptionalApiTokenUserId(ctx, request)
+  const isOwner = Boolean(apiTokenUserId && apiTokenUserId === skill.ownerUserId)
+  if (!isOwner) return null
+
+  if (skill.softDeletedAt) {
+    return {
+      status: 410,
+      message: `Skill is hidden/deleted. Run "clawhub undelete ${slug}" to restore it.`,
+    }
+  }
+
+  if (skill.moderationStatus === 'hidden') {
+    if (skill.moderationReason === 'pending.scan' || skill.moderationReason === 'scanner.vt.pending') {
+      return {
+        status: 423,
+        message: 'Skill is hidden while security scan is pending. Try again in a few minutes.',
+      }
+    }
+    if (skill.moderationReason === 'quality.low') {
+      return {
+        status: 403,
+        message:
+          'Skill is hidden by quality checks. Update SKILL.md content or run "clawhub undelete <slug>" after review.',
+      }
+    }
+    return {
+      status: 403,
+      message: `Skill is hidden by moderation${skill.moderationReason ? ` (${skill.moderationReason})` : ''}.`,
+    }
+  }
+
+  if (skill.moderationStatus === 'removed') {
+    return { status: 410, message: 'Skill has been removed by moderation.' }
+  }
+
+  return null
+}
+
 export const skillsGetRouterV1Http = httpAction(skillsGetRouterV1Handler)
 
 async function publishSkillV1Handler(ctx: ActionCtx, request: Request) {

convex/lib/skillPublish.test.ts

@@ -77,4 +77,29 @@ description: Expert guidance for sushi-rolls.
     expect(quality.decision).toBe('reject')
     expect(quality.reason).toContain('template spam')
   })
+
+  it('does not undercount non-latin skill docs', () => {
+    const signals = __test.computeQualitySignals({
+      readmeText: `# 飞书图片助手
+## 核心能力
+- 上传本地图片到飞书并自动返回 image_key，避免重复上传浪费配额。
+- 支持群聊与私聊，自动识别目标类型并校验参数，减少调用错误。
+- 提供重试与错误分类，方便排查网络问题、权限问题与资源限制。
+## 使用说明
+先配置应用凭证，然后传入目标会话与文件路径。技能会先检查缓存，再执行上传，并在发送阶段附带日志说明，便于团队追踪。
+如果出现失败，输出会包含建议动作，例如补齐权限、检查文件大小、确认机器人是否在群内，以及如何重放请求。
+还会记录每一步耗时、返回码与上下文摘要，方便后续做性能分析、告警聚合和批量回放，避免同类问题反复出现。
+`,
+      summary: '上传并发送图片到飞书，支持缓存、重试和错误诊断。',
+    })
+
+    const quality = __test.evaluateQuality({
+      signals,
+      trustTier: 'low',
+      similarRecentCount: 0,
+    })
+
+    expect(signals.bodyWords).toBeGreaterThanOrEqual(45)
+    expect(quality.decision).toBe('pass')
+  })
 })

convex/lib/skillQuality.ts

@@ -23,6 +23,7 @@ export type QualitySignals = {
   bulletCount: number
   templateMarkerHits: number
   genericSummary: boolean
+  cjkChars: number
   structuralFingerprint: string
 }
 
@@ -40,6 +41,29 @@ function stripFrontmatter(raw: string) {
 }
 
 function tokenizeWords(text: string) {
+  const segmenterCtor = (Intl as typeof Intl & {
+    Segmenter?: new (
+      locale?: string | string[],
+      options?: { granularity?: 'grapheme' | 'word' | 'sentence' },
+    ) => {
+      segment: (
+        input: string,
+      ) => Iterable<{ segment: string; isWordLike?: boolean }>
+    }
+  }).Segmenter
+
+  if (segmenterCtor) {
+    const segmenter = new segmenterCtor(undefined, { granularity: 'word' })
+    const tokens: string[] = []
+    for (const entry of segmenter.segment(text)) {
+      if (!entry.isWordLike) continue
+      const token = entry.segment.trim().toLowerCase()
+      if (!token) continue
+      tokens.push(token)
+    }
+    if (tokens.length > 0) return tokens
+  }
+
   return (text.toLowerCase().match(/[a-z0-9][a-z0-9'-]*/g) ?? []).filter((word) => word.length > 1)
 }
 
@@ -95,6 +119,7 @@ export function computeQualitySignals(args: {
   const templateMarkerHits = TEMPLATE_MARKERS.filter((marker) => bodyLower.includes(marker)).length
   const summary = (args.summary ?? '').trim().toLowerCase()
   const genericSummary = /^expert guidance for [a-z0-9-]+\.?$/.test(summary)
+  const cjkChars = (body.match(/[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/gu) ?? []).length
 
   return {
     bodyChars,
@@ -104,6 +129,7 @@ export function computeQualitySignals(args: {
     bulletCount,
     templateMarkerHits,
     genericSummary,
+    cjkChars,
     structuralFingerprint: toStructuralFingerprint(args.readmeText),
   }
 }
@@ -127,8 +153,14 @@ export function evaluateQuality(args: {
 }): QualityAssessment {
   const { signals, trustTier, similarRecentCount } = args
   const score = scoreQuality(signals)
-  const rejectWordsThreshold = trustTier === 'low' ? 45 : trustTier === 'medium' ? 35 : 28
-  const rejectCharsThreshold = trustTier === 'low' ? 260 : trustTier === 'medium' ? 180 : 140
+  const cjkHeavy =
+    signals.cjkChars >= 40 || (signals.bodyChars > 0 && signals.cjkChars / signals.bodyChars >= 0.15)
+  let rejectWordsThreshold = trustTier === 'low' ? 45 : trustTier === 'medium' ? 35 : 28
+  let rejectCharsThreshold = trustTier === 'low' ? 260 : trustTier === 'medium' ? 180 : 140
+  if (cjkHeavy) {
+    rejectWordsThreshold = Math.max(24, rejectWordsThreshold - 16)
+    rejectCharsThreshold = Math.max(140, rejectCharsThreshold - 120)
+  }
   const quarantineScoreThreshold = trustTier === 'low' ? 72 : trustTier === 'medium' ? 60 : 50
   const similarityRejectThreshold = trustTier === 'low' ? 5 : trustTier === 'medium' ? 8 : 12
 
@@ -157,6 +189,7 @@ export function evaluateQuality(args: {
         bulletCount: signals.bulletCount,
         templateMarkerHits: signals.templateMarkerHits,
         genericSummary: signals.genericSummary,
+        cjkChars: signals.cjkChars,
       },
     }
   }
@@ -176,6 +209,7 @@ export function evaluateQuality(args: {
         bulletCount: signals.bulletCount,
         templateMarkerHits: signals.templateMarkerHits,
         genericSummary: signals.genericSummary,
+        cjkChars: signals.cjkChars,
       },
     }
   }
@@ -194,6 +228,7 @@ export function evaluateQuality(args: {
       bulletCount: signals.bulletCount,
       templateMarkerHits: signals.templateMarkerHits,
       genericSummary: signals.genericSummary,
+      cjkChars: signals.cjkChars,
     },
   }
 }

convex/maintenance.ts

@@ -999,6 +999,7 @@ export const applyEmptySkillCleanupInternal = internalMutation({
         bulletCount: v.number(),
         templateMarkerHits: v.number(),
         genericSummary: v.boolean(),
+        cjkChars: v.optional(v.number()),
       }),
     }),
   },

convex/schema.ts

@@ -96,6 +96,7 @@ const skills = defineTable({
         bulletCount: v.number(),
         templateMarkerHits: v.number(),
         genericSummary: v.boolean(),
+        cjkChars: v.optional(v.number()),
       }),
       evaluatedAt: v.number(),
     }),

convex/skills.ts

@@ -3002,6 +3002,7 @@ export const insertVersion = internalMutation({
           bulletCount: v.number(),
           templateMarkerHits: v.number(),
           genericSummary: v.boolean(),
+          cjkChars: v.optional(v.number()),
         }),
       }),
     ),