feat(skill): add invocation controls

2026-07-28 17:22:41 +08:00
parent 2a46685414
commit e133e4bddb
49 changed files with 646 additions and 157 deletions
--- a/packages/skill/skill/README.i18n.yaml
+++ b/packages/skill/skill/README.i18n.yaml
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write
-README.md: 639616d0b75f960e9ccd48546d44db841372bbe2
-README.zh.md: 3afdd415397927ebf107d6f862422c711a51888b
+#   pnpm run verify-translation-pairing --write packages/skill/skill/README.md
+README.md: 30e48b57cd33c50013f857c61e63cba74fd2cd62
+README.zh.md: 08b4a97a921565b5d69960e6f69d6ee6dd194986
--- a/packages/skill/skill/README.md
+++ b/packages/skill/skill/README.md
@@ -11,8 +11,8 @@ This package owns the `ctx.skills` interface. It does not know whether skills co
 ### Public API

 - `ctx.skills.registerProvider(provider): () => void` Registers a readonly provider by unique `provider.name`. Duplicate provider names throw, and `runtime` is reserved for `ctx.skills.register(...)`. The registry borrows the provider object and invokes its methods directly. The registration is effect-scoped and HMR-safe, and the exact Cordis disposer supports ordered composite teardown.
- `ctx.skills.list({ cwd?, signal? })` Borrows the readonly lookup options, then returns model-invocable summaries for the current workspace, merged across providers and sorted by name.
- `ctx.skills.get(name, { cwd?, signal? })` Uses the same readonly options and winning candidate for discovery and loading, rechecks cancellation after discovery or a cache hit, races provider loading against the signal, validates the loaded definition, then returns it, including disabled-for-model skills.
+- `ctx.skills.list({ cwd?, signal? })` Borrows the readonly lookup options, then returns every winning summary for the current workspace, merged across providers and sorted by name. The result is invocation-neutral; consumers apply `isModelInvocable(skill)` or `isUserInvocable(skill)` at their own boundary.
+- `ctx.skills.get(name, { cwd?, signal? })` Uses the same readonly options and winning candidate for discovery and loading, rechecks cancellation after discovery or a cache hit, races provider loading against the signal, validates the loaded definition, then returns it regardless of invocation policy.
 - `ctx.skills.register(skill): () => void` Registers a readonly runtime embedded skill, adding `provider: "runtime"` when omitted. Same-name runtime registrations are first-wins: a duplicate logs a warning and gets a no-op disposer. Successful registrations return the exact Cordis disposer for ordered composite teardown.

 ### Config
@@ -21,6 +21,19 @@ This package owns the `ctx.skills` interface. It does not know whether skills co
 |---|---|---|
 | `collectCacheMaxEntries` | `128` | Maximum completed cwd/provider catalogs kept in memory. |

+### Invocation policy
+
+`SkillSummary.invocation` is a typed policy object with optional `disableModelInvocation` and `userInvocable` booleans. Missing values preserve the default model-and-user behavior. The registry keeps all four combinations so one discovery result can serve model-facing tools, human-facing commands, and trusted internal callers without conflating their catalogs.
+
+| Policy | Model | User |
+|---|---|---|
+| neither field, or `false` / `true` | included | included |
+| `userInvocable: false` | included | excluded |
+| `disableModelInvocation: true` | excluded | included |
+| both restrictive values | excluded | excluded |
+
+`isModelInvocable(skill)` returns false only for `disableModelInvocation: true`; `isUserInvocable(skill)` returns false only for `userInvocable: false`. `ctx.skills.get()` remains the trusted, policy-neutral loading primitive, so every user- or model-facing consumer must enforce the predicate that matches its surface before exposing or loading a skill.
+
 ## Provider Contract

 A provider registers synchronously and performs remote setup, authentication, and discovery in its awaited `list(options)` call. Provider objects, lookup options, candidates, and definitions are borrowed readonly rather than cloned or rebound. Providers should honor `options.signal`; the registry also stops awaiting uncooperative discovery or loading after cancellation.
--- a/packages/skill/skill/README.zh.md
+++ b/packages/skill/skill/README.zh.md
@@ -11,8 +11,8 @@
 ### 公开 API

 - `ctx.skills.registerProvider(provider): () => void` 使用唯一 `provider.name` 注册只读提供方。重复提供方名称会抛错，`runtime` 保留给 `ctx.skills.register(...)`。注册表借用提供方对象，并直接调用其方法。注册作用域绑定到 effect，可安全用于 HMR；精确的 Cordis disposer 支持有序组合拆卸。
- `ctx.skills.list({ cwd?, signal? })` 借用只读查找选项，然后返回当前工作区中模型可调用的摘要；这些摘要跨提供方合并，并按名称排序。
- `ctx.skills.get(name, { cwd?, signal? })` 在发现和加载中使用同一组只读选项和胜出候选项；在发现或缓存命中后重新检查取消，让提供方加载与信号竞速，验证已加载定义，然后将其返回，包括已对模型禁用的 skill。
+- `ctx.skills.list({ cwd?, signal? })` 借用只读查找选项，然后返回当前工作区中的全部胜出摘要；这些摘要跨提供方合并，并按名称排序。结果与调用策略无关；消费方在自身边界调用 `isModelInvocable(skill)` 或 `isUserInvocable(skill)`。
+- `ctx.skills.get(name, { cwd?, signal? })` 在发现和加载中使用同一组只读选项和胜出候选项；在发现或缓存命中后重新检查取消，让提供方加载与信号竞速，验证已加载定义，然后无论调用策略如何都将其返回。
 - `ctx.skills.register(skill): () => void` 注册只读运行时嵌入式 skill，省略时添加 `provider: "runtime"`。同名运行时注册使用先到先得：重复项会记录警告，并获得无操作 disposer。成功注册会返回精确的 Cordis disposer，以供有序组合拆卸。

 ### 配置
@@ -21,6 +21,19 @@
 |---|---|---|
 | `collectCacheMaxEntries` | `128` | 内存中保留的最大已完成 cwd/提供方目录数。 |

+### 调用策略
+
+`SkillSummary.invocation` 是类型化策略对象，其中包含可选的布尔字段 `disableModelInvocation` 和 `userInvocable`。字段缺失时保留模型和用户均可调用的默认行为。注册表保留全部四种组合，使一次发现结果可以同时服务面向模型的工具、面向用户的命令和受信内部调用方，而不会混淆各自的目录。
+
+| 策略 | 模型 | 用户 |
+|---|---|---|
+| 两个字段均未设置，或分别为 `false` / `true` | 包含 | 包含 |
+| `userInvocable: false` | 包含 | 排除 |
+| `disableModelInvocation: true` | 排除 | 包含 |
+| 两个限制值均已设置 | 排除 | 排除 |
+
+`isModelInvocable(skill)` 仅在 `disableModelInvocation: true` 时返回 false；`isUserInvocable(skill)` 仅在 `userInvocable: false` 时返回 false。`ctx.skills.get()` 仍是受信且与策略无关的加载原语，因此每个面向用户或模型的消费方都必须先执行与自身接口匹配的判定，再暴露或加载 skill。
+
 ## 提供方契约

 提供方同步注册，并在已等待的 `list(options)` 调用中执行远程设置、身份验证和发现。提供方对象、查找选项、候选项和定义都以只读方式借用，而不是克隆或重新绑定。提供方应遵守 `options.signal`；取消后，注册表也会停止等待不协作的发现或加载。
--- a/packages/skill/skill/src/index.ts
+++ b/packages/skill/skill/src/index.ts
@@ -36,16 +36,24 @@ export type SkillResourceBase =
  | { readonly kind: 'url'; readonly url: string }
  | { readonly kind: 'opaque'; readonly description: string }

-/** Model-visible skill metadata returned by `ctx.skills.list()` and rendered into request guidance. */
-export interface SkillSummary {
-  /** Kebab-case identifier used with the `skill` tool. */
-  readonly name: string
-  /** Short routing description shown to the model. */
-  readonly description: string
-  /** Optional extra routing guidance shown to the model. */
-  readonly whenToUse?: string
-  /** Whether the skill is hidden from model listings while remaining loadable by trusted callers. */
+/** Invocation controls shared by skill discovery consumers. */
+export interface SkillInvocationPolicy {
+  /** Whether model-facing catalogs and loaders exclude this skill. */
  readonly disableModelInvocation?: boolean
+  /** Whether human-facing command catalogs and loaders include this skill. */
+  readonly userInvocable?: boolean
+}
+
+/** Invocation-neutral skill metadata returned by `ctx.skills.list()`. */
+export interface SkillSummary {
+  /** Kebab-case identifier used to address the skill. */
+  readonly name: string
+  /** Short routing description shown by discovery consumers. */
+  readonly description: string
+  /** Optional extra routing guidance. */
+  readonly whenToUse?: string
+  /** Optional model and user invocation controls. */
+  readonly invocation?: SkillInvocationPolicy
  /** Discovery source that produced this winning skill. */
  readonly source: SkillSource
  /** Provider that owns this skill body. */
@@ -87,6 +95,24 @@ export interface SkillLookupOptions {
  readonly signal?: AbortSignal | undefined
 }

+/**
+ * Return whether a skill may be advertised to and loaded by a model.
+ * @param skill - skill metadata carrying optional invocation controls.
+ * @returns `false` only when model invocation is explicitly disabled.
+ */
+export function isModelInvocable(skill: Pick<SkillSummary, 'invocation'>): boolean {
+  return skill.invocation?.disableModelInvocation !== true
+}
+
+/**
+ * Return whether a skill may be advertised to and loaded by a human-facing command.
+ * @param skill - skill metadata carrying optional invocation controls.
+ * @returns `false` only when user invocation is explicitly disabled.
+ */
+export function isUserInvocable(skill: Pick<SkillSummary, 'invocation'>): boolean {
+  return skill.invocation?.userInvocable !== false
+}
+
 /** Provider interface for one source of skills, such as local directories or a remote registry. */
 export interface SkillProvider {
  /** Unique provider name in the `ctx.skills` registry. */
@@ -221,16 +247,16 @@ export class SkillService extends Service {
  }

  /**
-   * List model-invocable skill summaries for a workspace. Lookup options and
-   * provider candidates are readonly same-process values borrowed throughout
-   * discovery.
+   * List invocation-neutral skill summaries for a workspace. Consumers apply
+   * model or user invocation policy at their operational boundary. Lookup
+   * options and provider candidates are readonly same-process values borrowed
+   * throughout discovery.
   * @param options - lookup options; `cwd` selects project roots and `signal` cancels discovery.
-   * @returns sorted summaries, excluding skills disabled for model invocation.
+   * @returns all sorted winning summaries.
   */
  async list(options: SkillLookupOptions = {}): Promise<SkillSummary[]> {
    return (await this.collect(options))
      .map(entry => entry.candidate)
-      .filter(skill => skill.disableModelInvocation !== true)
      .map(toSummary)
      .sort(compareSkillSummary)
  }
@@ -359,7 +385,7 @@ function runtimeCandidate(skill: SkillRegistration): SkillCandidate {
    name: skill.name,
    description: skill.description,
    ...skill.whenToUse !== undefined ? { whenToUse: skill.whenToUse } : {},
-    ...skill.disableModelInvocation !== undefined ? { disableModelInvocation: skill.disableModelInvocation } : {},
+    ...skill.invocation !== undefined ? { invocation: skill.invocation } : {},
    source: skill.source,
    provider: skill.provider ?? RUNTIME_PROVIDER,
    ...skill.resourceBase !== undefined ? { resourceBase: skill.resourceBase } : {},
@@ -383,9 +409,7 @@ function validateCandidate(candidate: SkillCandidate, providerName: string): voi
  if (candidate.description.length === 0) {
    throw new Error(`skill provider "${providerName}" returned skill "${candidate.name}" without a description`)
  }
-  if (candidate.disableModelInvocation !== undefined && typeof candidate.disableModelInvocation !== 'boolean') {
-    throw new TypeError(`skill provider "${providerName}" returned skill "${candidate.name}" with a non-boolean disableModelInvocation`)
-  }
+  validateInvocation(candidate.invocation, `skill provider "${providerName}" returned skill "${candidate.name}"`)
  if (candidate.whenToUse !== undefined && typeof candidate.whenToUse !== 'string') {
    throw new TypeError(`skill provider "${providerName}" returned skill "${candidate.name}" with a non-string whenToUse`)
  }
@@ -409,6 +433,7 @@ function validateCandidate(candidate: SkillCandidate, providerName: string): voi
 function validateRuntimeSkill(skill: SkillRegistration): void {
  if (!SKILL_NAME.test(skill.name)) throw new Error(`invalid skill name "${skill.name}"`)
  if (skill.description.length === 0) throw new Error(`skill "${skill.name}" requires a description`)
+  validateInvocation(skill.invocation, `runtime skill "${skill.name}"`)
 }

 /** Validate a definition loaded from a provider-controlled parser or remote source. */
@@ -416,7 +441,7 @@ function validateDefinition(skill: SkillDefinition): void {
  const name = skill.name
  const description = skill.description
  const whenToUse = skill.whenToUse
-  const disableModelInvocation = skill.disableModelInvocation
+  const invocation = skill.invocation
  const source = skill.source
  const provider = skill.provider
  const content = skill.content
@@ -425,9 +450,7 @@ function validateDefinition(skill: SkillDefinition): void {
  if (!SKILL_NAME.test(name)) throw new Error(`loaded skill has invalid name "${name}"`)
  if (typeof description !== 'string') throw new TypeError(`loaded skill "${name}" description must be a string`)
  if (description.length === 0) throw new Error(`loaded skill "${name}" requires a description`)
-  if (disableModelInvocation !== undefined && typeof disableModelInvocation !== 'boolean') {
-    throw new TypeError(`loaded skill "${name}" disableModelInvocation must be a boolean`)
-  }
+  validateInvocation(invocation, `loaded skill "${name}"`)
  if (whenToUse !== undefined && typeof whenToUse !== 'string') throw new TypeError(`loaded skill "${name}" whenToUse must be a string`)
  if (typeof source !== 'string') throw new TypeError(`loaded skill "${name}" source must be a string`)
  if (typeof provider !== 'string') throw new TypeError(`loaded skill "${name}" provider must be a string`)
@@ -436,18 +459,32 @@ function validateDefinition(skill: SkillDefinition): void {
 }

 function toSummary(skill: SkillDefinition | SkillCandidate): SkillSummary {
-  const { name, description, whenToUse, disableModelInvocation, source, provider, resourceBase } = skill
+  const { name, description, whenToUse, invocation, source, provider, resourceBase } = skill
  return {
    name,
    description,
    ...whenToUse !== undefined ? { whenToUse } : {},
-    ...disableModelInvocation !== undefined ? { disableModelInvocation } : {},
+    ...invocation !== undefined ? { invocation } : {},
    source,
    provider,
    ...resourceBase !== undefined ? { resourceBase } : {},
  }
 }

+function validateInvocation(invocation: unknown, subject: string): void {
+  if (invocation === undefined) return
+  if (typeof invocation !== 'object' || invocation === null || Array.isArray(invocation)) {
+    throw new TypeError(`${subject} with a non-object invocation policy`)
+  }
+  const policy = invocation as Record<string, unknown>
+  if (policy.disableModelInvocation !== undefined && typeof policy.disableModelInvocation !== 'boolean') {
+    throw new TypeError(`${subject} with a non-boolean invocation.disableModelInvocation`)
+  }
+  if (policy.userInvocable !== undefined && typeof policy.userInvocable !== 'boolean') {
+    throw new TypeError(`${subject} with a non-boolean invocation.userInvocable`)
+  }
+}
+
 function compareSkillSummary(left: SkillSummary, right: SkillSummary): number {
  return compareCodePoints(left.name, right.name)
 }
--- a/packages/skill/skill/tests/skill.spec.ts
+++ b/packages/skill/skill/tests/skill.spec.ts
@@ -1,6 +1,13 @@
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import SkillService, { type SkillCandidate, type SkillDefinition, type SkillLookupOptions, type SkillProvider } from '@deepseek-ai/dsh-skill'
+import SkillService, {
+  isModelInvocable,
+  isUserInvocable,
+  type SkillCandidate,
+  type SkillDefinition,
+  type SkillLookupOptions,
+  type SkillProvider,
+} from '@deepseek-ai/dsh-skill'

 function memorySkill(name: string, description: string, rank: number, body = `${name} body.`): SkillCandidate {
  return {
@@ -107,6 +114,32 @@ describe('SkillService registry', () => {
    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['same-rank-skill', 'shadowed'])
  })

+  it('returns an invocation-neutral catalog and resolves model and user policy independently', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SkillService)
+    const registrations = [
+      { name: 'both', invocation: undefined },
+      { name: 'model-only', invocation: { userInvocable: false } },
+      { name: 'user-only', invocation: { disableModelInvocation: true } },
+      { name: 'trusted-only', invocation: { disableModelInvocation: true, userInvocable: false } },
+    ] as const
+    for (const registration of registrations) {
+      ctx.skills.register({
+        name: registration.name,
+        description: registration.name,
+        source: 'runtime',
+        ...registration.invocation === undefined ? {} : { invocation: registration.invocation },
+        content: `${registration.name} body.`,
+      })
+    }
+
+    const listed = await ctx.skills.list()
+    expect(listed.map(skill => skill.name)).toEqual(['both', 'model-only', 'trusted-only', 'user-only'])
+    expect(listed.filter(isModelInvocable).map(skill => skill.name)).toEqual(['both', 'model-only'])
+    expect(listed.filter(isUserInvocable).map(skill => skill.name)).toEqual(['both', 'user-only'])
+    expect(await ctx.skills.get('trusted-only')).toMatchObject({ content: 'trusted-only body.' })
+  })
+
  it('validates parsed candidate fields', async () => {
    const ctx = new Context()
    await ctx.plugin(SkillService)
@@ -117,7 +150,7 @@ describe('SkillService registry', () => {
        ...memorySkill('bad-candidate', 'placeholder', 1),
        provider: 'bad-candidate',
        description: badDescription as unknown as string,
-        disableModelInvocation: 'false' as unknown as boolean,
+        invocation: { disableModelInvocation: 'false' as unknown as boolean },
      }]),
      get: () => Promise.resolve(undefined),
    })
@@ -130,11 +163,11 @@ describe('SkillService registry', () => {
      list: () => Promise.resolve([{
        ...memorySkill('bad-boolean', 'Bad boolean', 1),
        provider: 'bad-boolean',
-        disableModelInvocation: 'false' as unknown as boolean,
+        invocation: { disableModelInvocation: 'false' as unknown as boolean },
      }]),
      get: () => Promise.resolve(undefined),
    })
-    await expect(badBoolean.skills.list()).rejects.toThrow('non-boolean disableModelInvocation')
+    await expect(badBoolean.skills.list()).rejects.toThrow('non-boolean invocation.disableModelInvocation')
  })

  it('rejects non-array provider results and every malformed candidate scalar', async () => {
@@ -163,7 +196,7 @@ describe('SkillService registry', () => {
        name: `candidate-${index}`,
        description: 'Candidate',
        whenToUse: 'Use this candidate.',
-        disableModelInvocation: false,
+        invocation: { disableModelInvocation: false, userInvocable: true },
        provider: providerName,
        source: 'test',
        rank: 1,
@@ -320,11 +353,12 @@ describe('SkillService registry', () => {
    const ctx = new Context()
    await ctx.plugin(SkillService)
    const locator = { id: 'provider-owned' }
+    const invocation = { disableModelInvocation: false, userInvocable: true }
    const candidate: SkillCandidate = {
      name: 'stable-skill',
      description: 'Stable description',
      whenToUse: 'When stability matters.',
-      disableModelInvocation: false,
+      invocation,
      provider: 'detached',
      source: 'test',
      resourceBase: { kind: 'opaque', description: 'candidate resources' },
@@ -337,7 +371,7 @@ describe('SkillService registry', () => {
      name: 'stable-skill',
      description: 'Stable description',
      whenToUse: 'When stability matters.',
-      disableModelInvocation: false,
+      invocation,
      provider: 'detached',
      source: 'test',
      resourceBase: { kind: 'opaque', description: 'definition resources' },
@@ -366,6 +400,7 @@ describe('SkillService registry', () => {
      resourceBase: { kind: 'opaque', description: 'candidate resources' },
    })])
    expect(listed[0]?.resourceBase).toBe(candidate.resourceBase)
+    expect(listed[0]?.invocation).toBe(invocation)
    expect(listCalls).toBe(1)

    const loaded = await ctx.skills.get('stable-skill')
@@ -379,11 +414,12 @@ describe('SkillService registry', () => {
    await ctx.plugin(SkillService)
    const resourceBase = { kind: 'opaque' as const, description: 'runtime resources' }
    const metadata = { owner: 'runtime' }
+    const invocation = { disableModelInvocation: false, userInvocable: true }
    const registration = {
      name: 'runtime-skill',
      description: 'Runtime',
      whenToUse: 'When runtime data is needed.',
-      disableModelInvocation: false,
+      invocation,
      source: 'runtime',
      resourceBase,
      metadata,
@@ -399,6 +435,7 @@ describe('SkillService registry', () => {
    const listed = await ctx.skills.list()
    const loaded = await ctx.skills.get('runtime-skill')
    expect(listed[0]?.resourceBase).toBe(resourceBase)
+    expect(listed[0]?.invocation).toBe(invocation)
    expect(loaded?.resourceBase).toBe(resourceBase)
    expect(loaded?.metadata).toBe(metadata)
    expect(loaded?.provider).toBe('runtime')
@@ -410,7 +447,15 @@ describe('SkillService registry', () => {
      { patch: { name: 'Bad_Name' }, expected: 'loaded skill has invalid name' },
      { patch: { description: { value: 'description' } as unknown as string }, expected: 'description must be a string' },
      { patch: { description: '' }, expected: 'requires a description' },
-      { patch: { disableModelInvocation: 'false' as unknown as boolean }, expected: 'disableModelInvocation must be a boolean' },
+      { patch: { invocation: null as never }, expected: 'non-object invocation policy' },
+      {
+        patch: { invocation: { disableModelInvocation: 'false' as unknown as boolean } },
+        expected: 'invocation.disableModelInvocation',
+      },
+      {
+        patch: { invocation: { userInvocable: 'true' as unknown as boolean } },
+        expected: 'invocation.userInvocable',
+      },
      { patch: { whenToUse: 1 as unknown as string }, expected: 'whenToUse must be a string' },
      { patch: { source: { value: 'source' } as unknown as string }, expected: 'source must be a string' },
      { patch: { provider: { value: 'provider' } as unknown as string }, expected: 'provider must be a string' },
@@ -436,7 +481,7 @@ describe('SkillService registry', () => {
          name: skillName,
          description: 'Definition',
          whenToUse: 'Use this definition.',
-          disableModelInvocation: false,
+          invocation: { disableModelInvocation: false, userInvocable: true },
          provider: providerName,
          source: 'test',
          content: 'Definition body.',
@@ -668,6 +713,13 @@ describe('SkillService registry', () => {
    await ctx.plugin(SkillService)
    expect(() => ctx.skills.register({ name: 'Bad_Name', description: 'Bad', source: 'runtime', content: 'bad' })).toThrow('invalid skill name')
    expect(() => ctx.skills.register({ name: 'no-description', description: '', source: 'runtime', content: 'bad' })).toThrow('requires a description')
+    expect(() => ctx.skills.register({
+      name: 'bad-invocation',
+      description: 'Bad invocation',
+      source: 'runtime',
+      invocation: [] as never,
+      content: 'bad',
+    })).toThrow('non-object invocation policy')
    expect(await ctx.skills.get('missing-skill')).toBeUndefined()
    expect(await ctx.skills.get('Bad_Name')).toBeUndefined()