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/tool-skill/README.i18n.yaml
+++ b/packages/skill/tool-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: 6b0af04a15bfda985be3e04868f18b9af702eae7
-README.zh.md: 4ca0ccd7734848d5774e92910e916bdf71c88c13
+#   pnpm run verify-translation-pairing --write packages/skill/tool-skill/README.md
+README.md: 37cda665b74e186d26129c74401b4d8b24c9b7c3
+README.zh.md: 849e44513c69ed11c311a1437c8a9a4af03a03f0
--- a/packages/skill/tool-skill/README.md
+++ b/packages/skill/tool-skill/README.md
@@ -22,7 +22,7 @@ Execution uses the calling agent's `session.header.cwd` so workspace-sensitive p

 Resource guidance resolves only paths or URLs explicitly referenced by the instructions against `resourceBase`; scripts, references, and assets load on demand, and the result does not enumerate a skill directory. Local providers may supply a directory, while remote or embedded providers may supply a URL or opaque loading guidance.

-An unresolved name reports that the skill is unknown or no longer available. Invalid names and `disableModelInvocation: true` skills produce distinct error results.
+An unresolved name reports that the skill is unknown or no longer available. Invalid names and skills whose `invocation.disableModelInvocation` is `true` produce distinct error results. `invocation.userInvocable` does not restrict this model-facing surface.

 The tool does not call `agent.inject()` in v1. Its result is already recorded as the tool result and becomes available to the next model step without duplicating the content as synthetic context.

--- a/packages/skill/tool-skill/README.zh.md
+++ b/packages/skill/tool-skill/README.zh.md
@@ -22,7 +22,7 @@

 资源指引只会根据 `resourceBase` 解析指令显式引用的路径或 URL；脚本、参考资料和产物按需加载，结果不会列举 skill 目录。本地提供方可以提供目录，而远程或嵌入式提供方可以提供 URL 或不透明加载指引。

-无法解析的名称会报告 skill 未知或已不可用。无效名称和 `disableModelInvocation: true` skill 产生不同的错误结果。
+无法解析的名称会报告 skill 未知或已不可用。无效名称和 `invocation.disableModelInvocation` 为 `true` 的 skill 会产生不同的错误结果。`invocation.userInvocable` 不限制这个面向模型的接口。

 该工具在 v1 中不调用 `agent.inject()`。其结果已作为工具结果记录，并在下一个模型步骤可用，无需将内容重复为合成上下文。

--- a/packages/skill/tool-skill/src/index.ts
+++ b/packages/skill/tool-skill/src/index.ts
@@ -9,7 +9,12 @@ import z from 'schemastery'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { assertNever, type Message } from '@deepseek-ai/dsh-llm'
-import { isSkillName, type SkillDefinition, type SkillSummary } from '@deepseek-ai/dsh-skill'
+import {
+  isModelInvocable,
+  isSkillName,
+  type SkillDefinition,
+  type SkillSummary,
+} from '@deepseek-ai/dsh-skill'

 export const name = 'tool-skill'
 export const inject = ['tools', 'skills']
@@ -91,7 +96,7 @@ export function apply(ctx: Context, config: Config = {}): void {
      if (!skill) {
        throw new Error(`skill "${args.name}" is unknown or no longer available`)
      }
-      if (skill.disableModelInvocation === true) {
+      if (!isModelInvocable(skill)) {
        throw new Error(`skill "${args.name}" is not available for model invocation`)
      }
      return {
@@ -123,7 +128,8 @@ export function apply(ctx: Context, config: Config = {}): void {
      catalogLoaded.add(agent.session)
      return
    }
-    const skills = await ctx.skills.list({ cwd: agent.session.header.cwd, signal })
+    const skills = (await ctx.skills.list({ cwd: agent.session.header.cwd, signal }))
+      .filter(isModelInvocable)
    if (skills.length > 0) {
      const catalog = renderCatalogMessage(skills, catalogDescriptionMaxLength)
      agent.inject({ content: catalog.content, source: { kind: 'plugin', plugin: 'dsh-tool-skill' } })
--- a/packages/skill/tool-skill/tests/tool-skill.spec.ts
+++ b/packages/skill/tool-skill/tests/tool-skill.spec.ts
@@ -143,6 +143,20 @@ describe('dsh-tool-skill', () => {
      provider: 'runtime',
      content: 'A body.',
    })
+    ctx.skills.register({
+      name: 'model-only-skill',
+      description: 'Model-only skill.',
+      invocation: { userInvocable: false },
+      source: 'runtime',
+      content: 'Model-only body.',
+    })
+    ctx.skills.register({
+      name: 'user-only-skill',
+      description: 'User-only skill.',
+      invocation: { disableModelInvocation: true },
+      source: 'runtime',
+      content: 'User-only body.',
+    })
    ctx.on('agent/step', (agent) => {
      agent.inject({ content: [{ type: 'text', text: 'later contribution' }], source: { kind: 'plugin', plugin: 'later-contribution' } })
    })
@@ -160,6 +174,7 @@ describe('dsh-tool-skill', () => {
            '',
            '<available_skills>',
            '- `a-skill`: Use {{placeholder}} &lt;safely&gt; &amp; carefully.',
+            '- `model-only-skill`: Model-only skill.',
            '- `z-skill`: Long description Long description Long descript...',
            '</available_skills>',
            '',
@@ -175,12 +190,20 @@ describe('dsh-tool-skill', () => {
    expect(rendered).not.toContain('secret-source')
    expect(rendered).not.toContain('/secret/path')
    expect(rendered).not.toContain('Secret body')
+    expect(rendered).not.toContain('user-only-skill')
    expect(renderPrompt(await ctx.systemPrompt.assemble({ agent: agentForCwd('/workspace') }))).not.toContain('<available_skills>')
  })

-  it('does not inject a catalog when no skills are available', async () => {
+  it('does not inject a catalog when no model-invocable skills are available', async () => {
    const home = await tempDir('tool-empty-catalog')
    const ctx = await setup(home)
+    ctx.skills.register({
+      name: 'user-only-skill',
+      description: 'User-only skill',
+      invocation: { disableModelInvocation: true },
+      source: 'runtime',
+      content: 'User-only body.',
+    })

    expect(await composePrefix(ctx, '/workspace')).toEqual([])
  })
@@ -333,16 +356,25 @@ describe('dsh-tool-skill', () => {
  it('returns isError for unknown, invalid, and model-disabled skills', async () => {
    const home = await tempDir('tool-errors')
    await writeSkill(join(home, '.dsh/skills'), 'hidden-skill', 'Hidden skill', 'Hidden instructions.')
-    await writeFile(join(home, '.dsh/skills/hidden-skill/SKILL.md'), '---\nname: hidden-skill\ndescription: Hidden skill\ndisableModelInvocation: true\n---\n\nHidden instructions.\n')
+    await writeFile(join(home, '.dsh/skills/hidden-skill/SKILL.md'), '---\nname: hidden-skill\ndescription: Hidden skill\ndisable-model-invocation: true\n---\n\nHidden instructions.\n')
    const ctx = await setup(home)
+    ctx.skills.register({
+      name: 'model-only-skill',
+      description: 'Model-only skill',
+      invocation: { userInvocable: false },
+      source: 'runtime',
+      content: 'Model-only instructions.',
+    })

    const unknown = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'skill', arguments: { name: 'missing' } })
    const invalid = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c2'), name: 'skill', arguments: { name: 'Bad_Name' } })
    const disabled = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c3'), name: 'skill', arguments: { name: 'hidden-skill' } })
+    const modelOnly = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c4'), name: 'skill', arguments: { name: 'model-only-skill' } })

    expect(unknown.isError).toBe(true)
    expect(invalid.isError).toBe(true)
    expect(disabled.isError).toBe(true)
+    expect(modelOnly.isError).toBe(false)
    const unknownBlock = unknown.content[0]
    if (unknownBlock?.type !== 'text') throw new Error('expected text tool result')
    expect(unknownBlock.text).toContain('skill "missing" is unknown or no longer available')