AgentServer/apps/server/test/custom-skills.test.ts

import fs from 'node:fs'
import path from 'node:path'
import pino from 'pino'
import { strToU8, unzipSync, zipSync } from 'fflate'
import { afterAll, beforeAll, describe, expect, it } from 'vitest'
import { createApp, type App } from '../src/app'
import { config, customSkillsDir, customSkillStoreDir } from '../src/config'
import { REGISTRY_LIMITS, renameSkillMd } from '../src/custom-skills/registry'
import { LIMITS, normalizeRelPath } from '../src/custom-skills/store'
import { buildServer } from '../src/http/server'
import { resolveSkills } from '../src/providers/claude/skills'
import { skillsToDisable } from '../src/providers/codex/skills'
import { checkAccess, resolveAccess } from '../src/services/access-policy'
import type { RegistrySubmissionDto } from '@agent-server/shared'

let app: App
let server: Awaited<ReturnType<typeof buildServer>>
let base: string
const audits: string[] = []
const live = (name: string, f = 'SKILL.md') => path.join(customSkillsDir(), 'skills', name, f)
const md = (name: string, desc = `${name} 的说明：处理某类业务数据的流程与规范`, extra = '') => `---\nname: ${name}\ndescription: ${desc}\n${extra}---\n# ${name}\n`
const zip = (files: Record<string, string>) => Buffer.from(zipSync(Object.fromEntries(Object.entries(files).map(([k, v]) => [k, strToU8(v)]))))

/** 用发布接口推送 */
async function push(key: string, pkg: Buffer, opts: { message?: string; meta?: object; dryRun?: boolean } = {}) {
  const form = new FormData()
  form.append('file', new Blob([new Uint8Array(pkg)]), 'skills.zip')
  form.append('message', opts.message ?? '')
  if (opts.meta) form.append('meta', JSON.stringify(opts.meta))
  const res = await fetch(`${base}/skills/registry/v1/submissions${opts.dryRun ? '?dryRun=1' : ''}`, { method: 'POST', headers: key ? { Authorization: `Bearer ${key}` } : {}, body: form })
  return { status: res.status, body: await res.json() as RegistrySubmissionDto & { error?: { message: string } } }
}
const keyRow = (key: string) => app.skillRegistry.verify(key, '127.0.0.1')!
const pending = (name: string) => app.skillRegistry.listItems('pending').find(i => i.name === name)!

beforeAll(async () => {
  const log = pino({ level: 'silent' })
  app = createApp(log, { providers: {} })
  const orig = app.audit.log.bind(app.audit)
  app.audit.log = (e: Parameters<typeof orig>[0]) => { audits.push(e.summary); return orig(e) }
  server = await buildServer(app, { logger: log })
  base = await server.listen({ port: 0, host: '127.0.0.1' })
})
afterAll(async () => {
  await server.close()
})

describe('技能发布平台：推送与审核（docs/design/18-skill-registry.md）', () => {
  let key: string
  let subId: string

  it('C-01 推送：只接受有效的发布密钥；试运行不保存；包中的技能逐个待审核，附自动检查', async () => {
    key = app.skillRegistry.createKey({ name: 'fwh-app · CI', description: '', expiresInDays: 365 }).key
    expect(key).toMatch(/^sk_pub_/)
    const pkg = zip({
      'skills/alpha/SKILL.md': md('alpha'),
      'skills/alpha/references/guide.md': 'alpha guide v1\nline2\n',
      'skills/beta/SKILL.md': md('beta'),
      'skills/beta/scripts/run.sh': 'curl https://api.example.com/v1/x\npassword = abcdefghijklmnop1234\n',
      '../evil.md': 'x',
    })
    expect((await push('', pkg)).status).toBe(401)
    expect((await push('sk_pub_nope', pkg)).status).toBe(401)
    expect((await push('ak_wrong_kind', pkg)).status).toBe(401)

    const dry = await push(key, pkg, { dryRun: true })
    expect(dry.status).toBe(200)
    expect([dry.body.id, dry.body.dryRun, dry.body.items.map(i => [i.name, i.status])]).toEqual(['', true, [['alpha', 'pending'], ['beta', 'pending']]])
    expect(app.skillRegistry.pendingCount()).toBe(0)

    const r = await push(key, pkg, { message: '新增 alpha 与 beta', meta: { repo: 'fwh-app', commit: 'abc123' } })
    expect(r.status).toBe(201)
    subId = r.body.id
    expect(r.body.skipped).toEqual(['../evil.md（路径不安全）'])
    expect(r.body.items.map(i => [i.name, i.status, i.existing])).toEqual([['alpha', 'pending', null], ['beta', 'pending', null]])
    const beta = r.body.items[1]!
    expect(beta.checks.map(c => [c.code, c.level])).toEqual([['script', 'warning'], ['secret', 'danger'], ['url', 'info']])
    expect(beta.checks[0]!.files).toEqual(['scripts/run.sh'])
    expect(beta.checks[2]!.message).toContain('api.example.com')

    // 推送不改变任何技能；后台待审核列表中有两项
    expect(fs.existsSync(live('alpha'))).toBe(false)
    expect(app.skillRegistry.listItems('pending').map(i => [i.name, i.keyName, i.message, i.meta.commit])).toEqual([['alpha', 'fwh-app · CI', '新增 alpha 与 beta', 'abc123'], ['beta', 'fwh-app · CI', '新增 alpha 与 beta', 'abc123']])
    expect(audits.some(a => a.startsWith('推送技能包（fwh-app · CI') && a.includes('alpha（待审核）'))).toBe(true)

    // 推送方只能看到自己的提交
    const other = app.skillRegistry.createKey({ name: '另一个项目', description: '', expiresInDays: null }).key
    const get = (k: string) => fetch(`${base}/skills/registry/v1/submissions/${subId}`, { headers: { Authorization: `Bearer ${k}` } })
    expect((await get(key)).status).toBe(200)
    expect((await get(other)).status).toBe(404)
    // 停用的密钥不能使用
    const otherId = app.skillRegistry.listKeys().find(k => k.name === '另一个项目')!.id
    app.skillRegistry.updateKey(otherId, { enabled: false })
    expect((await push(other, pkg)).status).toBe(401)
    expect(app.skillRegistry.listKeys().find(k => k.name === 'fwh-app · CI')).toMatchObject({ submissions: 1, pending: 2, lastUsedIp: '127.0.0.1' })
  })

  it('C-02 批准为新技能（可以改名，SKILL.md 中的 name 随之改写）；拒绝须填写原因，推送方可以看到', async () => {
    const alpha = pending('alpha')
    expect(app.skillRegistry.diff(alpha.id, {}).files.map(f => [f.path, f.status])).toEqual([['references/guide.md', 'added'], ['SKILL.md', 'added']])
    const r = app.skillRegistry.approve(alpha.id, { action: 'create', name: 'alpha', publish: true })
    expect(r.result).toMatchObject({ action: 'create', skillName: 'alpha', version: 1, published: true })
    expect(fs.readFileSync(live('alpha', 'references/guide.md'), 'utf8')).toBe('alpha guide v1\nline2\n')
    const a = app.customSkills.detail(r.result!.skillId)
    expect(a.versions[0]).toMatchObject({ version: 1, reason: 'submission', note: { submissionId: subId, keyName: 'fwh-app · CI', message: '新增 alpha 与 beta' } })
    // 推送来的技能可以直接编辑
    app.customSkills.writeFile(a.id, 'notes.md', Buffer.from('x'))
    app.customSkills.discard(a.id)

    const beta = pending('beta')
    const d = app.skillRegistry.diff(beta.id, { name: 'gamma' })
    expect(d.renamed).toBe(true)
    expect(d.files.find(f => f.path === 'SKILL.md')!.patch).toContain('+name: gamma')
    expect(() => app.skillRegistry.approve(beta.id, { action: 'create', name: 'alpha', publish: true })).toThrow(/已被使用/)
    expect(() => app.skillRegistry.approve(beta.id, { action: 'create', name: 'Bad Name', publish: true })).toThrow(/小写字母/)
    app.skillRegistry.approve(beta.id, { action: 'create', name: 'gamma', publish: true })
    expect(fs.readFileSync(live('gamma'), 'utf8')).toContain('name: gamma')
    expect(() => app.skillRegistry.approve(beta.id, { action: 'create', name: 'gamma2', publish: true })).toThrow(/已经处理/)

    const s = app.skillRegistry.getSubmission(keyRow(key).id, subId)
    expect(s.status).toBe('done')
    expect(s.items.map(i => [i.name, i.status, i.result?.skill, i.result?.version])).toEqual([['alpha', 'approved', 'alpha', 1], ['beta', 'approved', 'gamma', 1]])

    const r2 = await push(key, zip({ 'delta/SKILL.md': md('delta') }))
    const delta = pending('delta')
    expect(() => app.skillRegistry.reject(delta.id, ' ')).toThrow(/原因/)
    app.skillRegistry.reject(delta.id, '描述不清楚')
    expect(app.skillRegistry.getSubmission(keyRow(key).id, r2.body.id).items[0]).toMatchObject({ status: 'rejected', reviewNote: '描述不清楚' })
    expect(app.skillRegistry.listItems('done').find(i => i.name === 'delta')).toMatchObject({ status: 'rejected', reviewNote: '描述不清楚' })
  })

  it('C-03 再次推送：相同内容为无变化；同一密钥再推送替代旧的待审核；覆盖时以审核时看到的版本为准', async () => {
    const same = await push(key, zip({ 'alpha/SKILL.md': md('alpha'), 'alpha/references/guide.md': 'alpha guide v1\nline2\n' }))
    expect(same.body.items[0]).toMatchObject({ name: 'alpha', status: 'unchanged', existing: { version: 1 } })

    const v2 = (body: string, ver: string) => zip({ 'alpha/SKILL.md': md('alpha', undefined, `metadata:\n  version: "${ver}"\n`), 'alpha/references/guide.md': body })
    const first = await push(key, v2('alpha guide v2\n', '2.0'))
    const second = await push(key, v2('alpha guide v3\n', '2.0'))
    expect(app.skillRegistry.getSubmission(keyRow(key).id, first.body.id).items[0]!.status).toBe('superseded')
    const item = pending('alpha')
    expect(item.submissionId).toBe(second.body.id)
    expect(item.existing).toMatchObject({ version: 1 })
    expect(second.body.items[0]!.changes).toEqual({ added: [], modified: ['SKILL.md', 'references/guide.md'], removed: [] })
    expect(item.checks.find(c => c.code === 'version')!.message).toBe('声明版本号：未声明 → 2.0')

    const alphaId = app.customSkills.list().find(s => s.name === 'alpha')!.id
    const d = app.skillRegistry.diff(item.id, { targetId: alphaId })
    expect(d.target).toMatchObject({ name: 'alpha', version: 1, unsaved: false })
    expect(d.files.find(f => f.path === 'references/guide.md')!.patch).toContain('+alpha guide v3')
    // 审核期间技能有了新版本：拒绝覆盖
    expect(() => app.skillRegistry.approve(item.id, { action: 'overwrite', targetId: alphaId, expectedVersion: 0, publish: true })).toThrow(/刷新/)
    const r = app.skillRegistry.approve(item.id, { action: 'overwrite', targetId: alphaId, expectedVersion: 1, publish: false })
    expect(r.result).toMatchObject({ action: 'overwrite', skillName: 'alpha', version: 2, published: false })
    expect(app.customSkills.detail(alphaId)).toMatchObject({ latestVersion: 2, publishedVersion: 1 })
    expect(fs.readFileSync(live('alpha', 'references/guide.md'), 'utf8')).toBe('alpha guide v1\nline2\n')
    app.customSkills.publish(alphaId, 2)
    expect(fs.readFileSync(live('alpha', 'references/guide.md'), 'utf8')).toBe('alpha guide v3\n')

    // 覆盖到不同名的技能：SKILL.md 的 name 改写为目标技能名
    await push(key, zip({ 'alpha-next/SKILL.md': md('alpha-next') }))
    const next = pending('alpha-next')
    const gammaId = app.customSkills.list().find(s => s.name === 'gamma')!.id
    app.skillRegistry.approve(next.id, { action: 'overwrite', targetId: gammaId, expectedVersion: 1, publish: true })
    expect(fs.readFileSync(live('gamma'), 'utf8')).toContain('name: gamma')
    expect(fs.readFileSync(live('gamma'), 'utf8')).toContain('# alpha-next')
  })

  it('C-04 撤回；删除已处理的提交项（待审核的不能删），技能版本保留提交说明', async () => {
    const r = await push(key, zip({ 'epsilon/SKILL.md': md('epsilon') }))
    const res = await fetch(`${base}/skills/registry/v1/submissions/${r.body.id}`, { method: 'DELETE', headers: { Authorization: `Bearer ${key}` } })
    expect(((await res.json()) as RegistrySubmissionDto).items[0]!.status).toBe('withdrawn')

    await push(key, zip({ 'zeta/SKILL.md': md('zeta') }))
    expect(() => app.skillRegistry.deleteItem(pending('zeta').id)).toThrow(/先批准或拒绝/)
    app.skillRegistry.reject(pending('zeta').id, '不需要')

    const alphaId = app.customSkills.list().find(s => s.name === 'alpha')!.id
    for (const i of app.skillRegistry.listItems('done')) app.skillRegistry.deleteItem(i.id)
    expect(app.skillRegistry.listItems('done')).toEqual([])
    expect(app.customSkills.detail(alphaId).versions[0]!.note).toMatchObject({ keyName: 'fwh-app · CI' })
    expect(fs.readFileSync(live('alpha', 'references/guide.md'), 'utf8')).toBe('alpha guide v3\n')
  })

  it('C-05 校验：不合规的技能为 invalid；不是 zip、没有技能、压缩炸弹被拒绝；推送次数与待审核数有上限', async () => {
    const r = await push(key, zip({ 'Bad_Name/SKILL.md': md('Bad_Name'), 'ok/SKILL.md': '# 没有 frontmatter\n', 'a/SKILL.md': md('dup'), 'b/SKILL.md': md('dup') }))
    expect(r.body.items.map(i => [i.name, i.status])).toEqual([['dup', 'pending'], ['dup', 'invalid'], ['Bad_Name', 'invalid'], ['ok', 'pending']])
    expect(r.body.items[1]!.reason).toMatch(/多个名为 dup/)
    expect((await push(key, Buffer.from('not a zip'))).status).toBe(400)
    expect((await push(key, zip({ 'readme.md': 'x' }))).body.error!.message).toMatch(/没有找到技能/)

    const saved = LIMITS.unzipBytes
    LIMITS.unzipBytes = 1048576
    try {
      const bomb = Buffer.from(zipSync({ 'big/SKILL.md': new Uint8Array(3 * 1048576) }, { level: 9 }))
      expect((await push(key, bomb)).body.error!.message).toMatch(/解压后超过/)
    } finally {
      LIMITS.unzipBytes = saved
    }

    const k = app.skillRegistry.createKey({ name: '限额', description: '', expiresInDays: 1 }).key
    const limits = { ...REGISTRY_LIMITS }
    REGISTRY_LIMITS.pendingPerKey = 1
    try {
      expect((await push(k, zip({ 'q1/SKILL.md': md('q1') }))).status).toBe(201)
      // 同名技能替代旧的，不占额度；新技能超出上限
      expect((await push(k, zip({ 'q1/SKILL.md': md('q1', 'q1 的新说明：处理某类业务数据的流程与规范') }))).status).toBe(201)
      expect((await push(k, zip({ 'q2/SKILL.md': md('q2') }))).status).toBe(429)
      REGISTRY_LIMITS.submissionsPerHour = 2
      expect((await push(k, zip({ 'q1/SKILL.md': md('q1') }))).status).toBe(429)
    } finally {
      Object.assign(REGISTRY_LIMITS, limits)
    }
    expect(renameSkillMd('# x\n', 'n')).toBe('---\nname: n\n---\n# x\n')
  })
})

describe('自定义技能：在线编写、草稿与发布、版本', () => {
  let id: string

  it('C-04 新建 → 上传模版并保存为草稿：不生效；发布后生效；恢复到上一版本', () => {
    const d = app.customSkills.create({ name: 'report-kit', description: '生成月度报告的规范与模版，涉及月报时使用' })
    id = d.id
    expect(d.versions.map(v => [v.version, v.reason])).toEqual([[1, 'create']])
    expect(d.publishedVersion).toBeNull()
    expect(fs.existsSync(live('report-kit'))).toBe(false)

    app.customSkills.writeFile(id, 'templates/a.pptx', Buffer.from([1, 2, 3]))
    expect(app.customSkills.detail(id).hasUnsavedChanges).toBe(true)
    const v2 = app.customSkills.save(id, { baseVersion: 1, publish: false })
    expect([v2.latestVersion, v2.publishedVersion, v2.hasUnsavedChanges]).toEqual([2, null, false])
    expect(fs.existsSync(live('report-kit'))).toBe(false)
    // 内容无变化不产生新版本；基于旧版本保存时冲突
    expect(app.customSkills.save(id, { baseVersion: 2, publish: false }).latestVersion).toBe(2)
    expect(() => app.customSkills.save(id, { baseVersion: 1, publish: false })).toThrow(/刷新/)

    expect(app.customSkills.publish(id, 2).publishedVersion).toBe(2)
    expect([...fs.readFileSync(live('report-kit', 'templates/a.pptx'))]).toEqual([1, 2, 3])

    app.customSkills.writeFile(id, 'templates/a.pptx', Buffer.from([9]))
    app.customSkills.writeFile(id, 'SKILL.md', Buffer.from(md('report-kit', '新版描述：生成月度报告的规范与模版，涉及月报时使用')))
    const v3 = app.customSkills.save(id, { baseVersion: 2, publish: true })
    expect([v3.latestVersion, v3.publishedVersion, v3.description]).toEqual([3, 3, '新版描述：生成月度报告的规范与模版，涉及月报时使用'])
    expect(v3.versions[0]!.changed).toEqual({ added: [], modified: ['SKILL.md', 'templates/a.pptx'], removed: [] })

    const v4 = app.customSkills.restore(id, 2)
    expect([v4.latestVersion, v4.publishedVersion, v4.versions[0]!.reason]).toEqual([4, 4, 'restore'])
    expect([...fs.readFileSync(live('report-kit', 'templates/a.pptx'))]).toEqual([1, 2, 3])
  })

  it('SKILL.md 校验、路径安全、重命名与删除、放弃改动、导出 zip', () => {
    app.customSkills.writeFile(id, 'SKILL.md', Buffer.from('---\nname: other\ndescription: x\n---\n'))
    expect(() => app.customSkills.save(id, { baseVersion: 4, publish: false })).toThrow(/不一致/)
    app.customSkills.discard(id)
    expect(() => app.customSkills.writeFile(id, '../escape.md', Buffer.from('x'))).toThrow(/路径不正确/)
    expect(() => normalizeRelPath('/abs')).toThrow()
    expect(() => app.customSkills.deleteFile(id, 'SKILL.md')).toThrow(/不能删除/)
    app.customSkills.writeFile(id, 'refs/a.md', Buffer.from('a'))
    expect(app.customSkills.move(id, 'refs', 'references').files.map(f => f.path)).toEqual(['SKILL.md', 'references/a.md', 'templates/a.pptx'])
    expect(app.customSkills.deleteFile(id, 'references').files.map(f => f.path)).toEqual(['SKILL.md', 'templates/a.pptx'])

    const z = app.customSkills.exportZip(id)
    expect(z.name).toBe('report-kit-v4.zip')
    expect(Object.keys(unzipSync(new Uint8Array(z.data))).sort()).toEqual(['report-kit/SKILL.md', 'report-kit/templates/a.pptx'])
  })
})

describe('自定义技能：使用、沙箱与恢复', () => {
  it('C-05 "全部技能"不包含自定义技能（可逐个设置包含）；单独勾选后加载', () => {
    const plugins = [
      { name: 'agent-skills', path: '/a', skills: [{ id: 'agent-skills:r', loadId: 'agent-skills:r' }] },
      app.customSkills.pluginRef()!,
    ]
    expect(resolveSkills('all', plugins).skills).toEqual(['agent-skills:r'])
    expect(resolveSkills(['custom-skills:report-kit'], plugins).skills).toEqual(['custom-skills:report-kit'])

    const id = app.customSkills.list().find(s => s.name === 'report-kit')!.id
    app.customSkills.setFlags(id, { includeInAll: true })
    expect(resolveSkills('all', [plugins[0]!, app.customSkills.pluginRef()!]).skills).toContain('custom-skills:report-kit')
    expect(app.customSkills.excludedFromAll()).not.toContain('custom-skills:report-kit')

    // Codex：all 时禁用需要单独勾选的自定义技能
    const all = [
      { name: 'custom-skills:alpha', path: path.join(customSkillsDir(), 'skills/alpha/SKILL.md') },
      { name: 'custom-skills:Report Kit', path: path.join(customSkillsDir(), 'skills/report-kit/SKILL.md') },
    ].map(s => ({ ...s, scope: 'user' as const, description: '', enabled: true, pluginId: null }))
    expect(skillsToDisable(all, 'all', '/nohome', 'agent-skills', undefined, app.customSkills.excludedFromAll()).map(d => path.basename(path.dirname(d.path)))).toEqual(['alpha'])
  })

  it('停用后不加载，启用后恢复；指纹随之变化', () => {
    const id = app.customSkills.list().find(s => s.name === 'alpha')!.id
    const before = app.customSkills.fingerprint()
    app.customSkills.setFlags(id, { enabled: false })
    expect(fs.existsSync(live('alpha'))).toBe(false)
    expect(app.customSkills.skillInfos().map(s => s.name)).not.toContain('alpha')
    expect(app.customSkills.fingerprint()).not.toBe(before)
    app.customSkills.setFlags(id, { enabled: true })
    expect(fs.existsSync(live('alpha'))).toBe(true)
  })

  it('C-06 沙箱：生效目录只读可见，不能写；版本库不可读', () => {
    const settings = app.settings.get()
    const ws = path.join(config.dataDir, 'workspaces', 'ses_cs')
    fs.mkdirSync(ws, { recursive: true })
    const access = resolveAccess({ policy: { mode: 'restricted', read: [], write: [], deny: [] }, knowledgeRoots: [], selectedKnowledgeRootIds: [], workspaceDir: ws, settings })
    expect(checkAccess(access, live('alpha'), 'read').allowed).toBe(true)
    expect(checkAccess(access, live('alpha'), 'write').allowed).toBe(false)
    expect(checkAccess(access, path.join(customSkillStoreDir(), 'ab', 'x'), 'read').allowed).toBe(false)
    const broad = resolveAccess({ policy: { mode: 'broad', read: [], write: [], deny: [] }, knowledgeRoots: [], selectedKnowledgeRootIds: [], workspaceDir: ws, settings })
    expect(checkAccess(broad, path.join(customSkillStoreDir(), 'ab', 'x'), 'read').allowed).toBe(false)
    expect(checkAccess(broad, live('alpha'), 'read').allowed).toBe(true)
  })

  it('C-07 删除被两个 Profile 使用的技能：从两个 Profile 中移除', () => {
    const { id: _i, version: _v, updatedAt: _u, builtin: _b, ...input } = app.profiles.getBuiltin()
    const p1 = app.profiles.create({ ...input, name: 'p1', isDefault: false, skills: ['custom-skills:gamma', 'agent-skills:r'] })
    const p2 = app.profiles.create({ ...input, name: 'p2', isDefault: false, skills: ['custom-skills:gamma'] })
    const gamma = app.customSkills.list().find(s => s.name === 'gamma')!
    expect(gamma.profileNames.sort()).toEqual(['p1', 'p2'])
    app.customSkills.delete(gamma.id)
    expect(app.profiles.get(p1.id).skills).toEqual(['agent-skills:r'])
    expect(app.profiles.get(p2.id).skills).toEqual([])
    expect(fs.existsSync(live('gamma'))).toBe(false)
  })

  it('C-08 重启时按数据库重建：被删除或改动的生效目录恢复，多余目录移除', () => {
    fs.rmSync(path.join(customSkillsDir(), 'skills', 'alpha'), { recursive: true })
    fs.writeFileSync(live('report-kit'), 'tampered')
    fs.mkdirSync(path.join(customSkillsDir(), 'skills', 'stray'))
    const logs: string[] = []
    app.customSkills.reconcile(m => logs.push(m))
    expect(fs.readFileSync(live('alpha'), 'utf8')).toContain('name: alpha')
    expect(fs.existsSync(path.join(customSkillsDir(), 'skills', 'stray'))).toBe(false)
    expect(logs.some(l => l.includes('alpha'))).toBe(true)
    // 改动文件内容但标记未变：按标记判断不重新发布（运行时目录只能由服务写入）
    expect(logs.some(l => l.includes('stray'))).toBe(true)
  })
})