Merge remote-tracking branch 'origin/master' into worktree/pr823-retarget-latest-20260729

# Conflicts: # docs/config-catalog.md # docs/cordis-catalog/services.md # docs/core-data-structures/skills.i18n.yaml # docs/core-data-structures/skills.md # docs/core-data-structures/skills.zh.md # packages/host/apiproxy/README.i18n.yaml # packages/skill/skill-local/README.i18n.yaml # packages/skill/skill/README.i18n.yaml # packages/skill/skill/README.md # packages/skill/skill/README.zh.md # packages/skill/skill/src/index.ts # packages/skill/skill/tests/skill.spec.ts # packages/skill/tool-skill/README.i18n.yaml # packages/skill/tool-skill/src/index.ts # packages/ui/tui/README.i18n.yaml # packages/ui/tui/README.md # packages/ui/tui/README.zh.md # packages/ui/tui/src/index.ts # packages/ui/tui/tests/tui.spec.ts
2026-07-29 23:36:49 +08:00
parent 1619d7686b 6771ee94b7
commit fca0c05155
205 changed files with 5429 additions and 840 deletions
--- a/packages/ui/tui/README.i18n.yaml
+++ b/packages/ui/tui/README.i18n.yaml
@@ -2,5 +2,5 @@
 # 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 packages/ui/tui/README.md
-README.md: dead972f93d5e72fc6153bacc0ecd9cd80f725ca
-README.zh.md: 879bb0951df061d88151aa43544baf3e6c4b02e8
+README.md: 88c4501d87b7f24de1f5cc0d67f4c0e03ec49aa4
+README.zh.md: f03120e5a7820e2bcb572ab31b535211cf859c82
--- a/packages/ui/tui/README.md
+++ b/packages/ui/tui/README.md
@@ -139,7 +139,7 @@ Changing provider or model enters that target's cache domain; no cache reuse acr

 #### What the model sees

-A `/skill:<name> [instructions]` submission loads the named skill and delivers one text block: a `<skill name="…">` element wrapping the skill's instructions — preceded, when the provider exposes a resource base, by a line locating the skill's relative resources — followed by any trailing instructions the user typed. Delivery follows the same followup-while-idle / steer-while-running rule as ordinary input. The command, not the model, chooses the skill: autocomplete and exact invocation apply `invocation.userInvocable`, while `invocation.modelInvocable` does not restrict this surface. A user-disabled skill produces a warning and no user turn. The skill service is an optional peer; this policy check uses its type contract without introducing a runtime package dependency.
+A `/skill:<name> [instructions]` submission loads the named skill and delivers one text block: a `<skill name="…">` element wrapping the skill's instructions — preceded, when the provider exposes a resource base, by a line locating the skill's relative resources — followed by any trailing instructions the user typed. Delivery follows the same followup-while-idle / steer-while-running rule as ordinary input. The command, not the model, chooses the skill: autocomplete and exact invocation apply `invocation.userInvocable`, while `invocation.modelInvocable` does not restrict this surface. User-disabled skills are omitted from autocomplete and rejected before exact-name loading; the loaded definition is rechecked for a policy race. Autocomplete retains its last complete skill snapshot and refetches after `skills/change`; an incomplete observation preserves the prior menu, a complete empty observation clears it, and a catalog arriving while a slash-name draft is open immediately re-queries that draft. The skill service is an optional peer; this policy check uses its type contract without introducing a runtime package dependency.

 #### Token effect

--- a/packages/ui/tui/README.zh.md
+++ b/packages/ui/tui/README.zh.md
@@ -139,7 +139,7 @@ Paths prefixed with @ are files explicitly referenced by the user. Use the read

 #### 模型看到的内容

-提交 `/skill:<name> [instructions]` 会加载具名 skill，并交付一个文本块：用 `<skill name="…">` 元素包装 skill 指令；提供方公开资源基准时，会先添加一行定位 skill 相对资源；最后附上用户输入的尾随指令。交付遵循普通输入同样的空闲时 followup、运行时 steer 规则。选择 skill 的是命令而非模型：自动补全和按精确名称调用都应用 `invocation.userInvocable`，`invocation.modelInvocable` 不限制这个接口。用户禁用的 skill 会产生一条警告，不会产生用户轮次。skill 服务是可选 peer；这项策略检查仅使用其类型契约，不引入运行时包依赖。
+提交 `/skill:<name> [instructions]` 会加载具名 skill，并交付一个文本块：用 `<skill name="…">` 元素包装 skill 指令；提供方公开资源基准时，会先添加一行定位 skill 相对资源；最后附上用户输入的尾随指令。交付遵循普通输入同样的空闲时 followup、运行时 steer 规则。选择 skill 的是命令而非模型：自动补全和按精确名称调用都应用 `invocation.userInvocable`，`invocation.modelInvocable` 不限制这个接口。用户禁用的 skill 不出现在自动补全中，按精确名称调用时也会在加载前被拒绝；为防止策略竞态，加载后的定义还会再次接受检查。自动补全会保留最后一份完整 skill 快照，并在 `skills/change` 后重新获取。观测不完整时保留先前菜单，完整的空观测会将其清空；如果目录在斜杠命令名称草稿打开期间到达，则会立即根据该草稿重新查询。skill 服务是可选 peer；这项策略检查仅使用其类型契约，不引入运行时包依赖。

 #### Token 影响

--- a/packages/ui/tui/src/index.ts
+++ b/packages/ui/tui/src/index.ts
@@ -1043,9 +1043,12 @@ export function createTuiChat(
    requestRender()
  }

-  // Skill listing is async while `createTuiChat` is synchronous, so the
-  // completions rebuild once the invocation-neutral catalog resolves.
+  // Skill listing is async while `createTuiChat` is synchronous, so the TUI
+  // retains the last complete invocation-neutral catalog for synchronous
+  // editor completion, filters it for user invocation, and refreshes it after
+  // registry invalidation.
  let skillCommands: SlashCommand[] = []
+  let skillCommandScan = 0
  const refreshCommandAutocomplete = (): void => {
    const base = new CombinedAutocompleteProvider(
      [
@@ -1066,14 +1069,25 @@ export function createTuiChat(
      agent,
    ))
  }
+  const refreshVisibleSlashAutocomplete = (): void => {
+    const cursor = editor.getCursor()
+    const textBeforeCursor = editor.getLines().slice(cursor.line, cursor.line + 1).join('').slice(0, cursor.col)
+    if (cursor.line === 0 && textBeforeCursor.startsWith('/') && !textBeforeCursor.includes(' ')) {
+      // pi-tui's provider setter closes an existing menu but does not query
+      // the replacement for the current draft. Tab in a slash-name context
+      // only requests suggestions, so it refreshes without editing the text.
+      editor.handleInput('\t')
+    }
+  }
  const disposeCommandChanges = ctx.on('commands/change', refreshCommandAutocomplete)
  refreshCommandAutocomplete()

-  const loadSkillCommands = (service: SkillService): void => {
-    service.list({ cwd, signal: skillAbort.signal }).then(
-      (summaries) => {
-        const invocable = summaries.filter(skill => skill.invocation.userInvocable)
-        if (disposed || invocable.length === 0) return
+  const refreshSkillCommands = (service: SkillService): void => {
+    const scan = ++skillCommandScan
+    service.snapshot({ cwd, signal: skillAbort.signal }).then(
+      (snapshot) => {
+        if (disposed || scan !== skillCommandScan || !snapshot.complete) return
+        const invocable = snapshot.skills.filter(skill => skill.invocation.userInvocable)
        // The argument-hint slot shows in the menu but is never inserted on
        // selection, so it carries the skill's scope instead of an
        // instructions placeholder. `SkillSource` is open-ended; every
@@ -1085,6 +1099,7 @@ export function createTuiChat(
          argumentHint: skill.source.startsWith('project-') ? '(project)' : '(user)',
        }))
        refreshCommandAutocomplete()
+        refreshVisibleSlashAutocomplete()
        requestRender()
      },
      () => {
@@ -1093,7 +1108,10 @@ export function createTuiChat(
      },
    )
  }
-  if (skills !== undefined) loadSkillCommands(skills)
+  const disposeSkillChanges = skills === undefined
+    ? () => {}
+    : ctx.on('skills/change', () => { refreshSkillCommands(skills) })
+  if (skills !== undefined) refreshSkillCommands(skills)

  // The agent scope is minted by agent-loop and intentionally inherits only
  // that core plugin's dependencies. A child command producer declares its own
@@ -1508,6 +1526,7 @@ export function createTuiChat(
    fileSearch.dispose()
    removeInputListener()
    disposeCommandChanges()
+    disposeSkillChanges()
    disposePromptChanges()
    for (const value of promptValues) value.dispose()
    stopBannerReveal()
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -18,7 +18,7 @@ import { GOAL_CHANGE_VERSION, GoalId, renderGoalChange, type GoalSnapshotChangeM
 import CommandService, { type CommandInvocation } from '@deepseek-ai/dsh-commands'
 import SessionStore, { SessionId, type JsonValue, type SessionEvent, type SessionHeader, type TurnEndReason } from '@deepseek-ai/dsh-session'
 import type { SessionRecord } from '@deepseek-ai/dsh-session-query'
-import SkillService, { type SkillDefinition, type SkillSummary } from '@deepseek-ai/dsh-skill'
+import SkillService, { type SkillCatalogSnapshot, type SkillDefinition, type SkillProvider, type SkillSummary } from '@deepseek-ai/dsh-skill'
 import type {} from '@deepseek-ai/dsh-session-title'
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
@@ -3866,6 +3866,135 @@ describe('skill slash command', () => {
    await dispose(result)
  })

+  it('refreshes slash completions after runtime skill additions and complete removals', async () => {
+    let skills: SkillService | undefined
+    const result = await setup({
+      configureContext: async (ctx) => {
+        ctx.provide('tools', { get() { return undefined } } as never)
+        await ctx.plugin(SkillService)
+        skills = ctx.get('skills')
+      },
+    })
+    if (skills === undefined) throw new Error('skills service not mounted')
+
+    result.terminal.send('/skill:dynamic')
+    await tick()
+    result.terminal.output = ''
+    const disposeSkill = skills.register({
+      name: 'dynamic-skill',
+      description: 'DYNAMIC_COMPLETION_MARKER',
+      source: 'runtime',
+      content: 'Dynamic body.',
+    })
+    await tick()
+    expect(result.terminal.output).toContain('DYNAMIC_COMPLETION_MARKER')
+
+    result.terminal.send('\x03')
+    disposeSkill()
+    await tick()
+    result.terminal.output = ''
+    result.terminal.send('/skill:dynamic')
+    await tick()
+    expect(result.terminal.output).not.toContain('DYNAMIC_COMPLETION_MARKER')
+    await dispose(result)
+  })
+
+  it('retains last-good slash completions across incomplete snapshots', async () => {
+    let skills: SkillService | undefined
+    let provider: SkillProvider | undefined
+    let invalidate = (): void => {}
+    let fail = false
+    const result = await setup({
+      configureContext: async (ctx) => {
+        ctx.provide('tools', { get() { return undefined } } as never)
+        await ctx.plugin(SkillService)
+        skills = ctx.get('skills')
+        provider = {
+          name: 'flaky-completion',
+          async list() {
+            if (fail) throw new Error('transient completion failure')
+            return [{
+              name: 'stable-skill',
+              description: 'STABLE_COMPLETION_MARKER',
+              invocation: { modelInvocable: true, userInvocable: true },
+              source: 'test',
+              provider: 'flaky-completion',
+              rank: 1,
+              locator: 'stable',
+            }]
+          },
+          async get() {
+            return undefined
+          },
+        }
+        skills?.registerProvider((control) => {
+          invalidate = control.invalidate
+          return provider as SkillProvider
+        })
+      },
+    })
+    if (skills === undefined || provider === undefined) throw new Error('skills provider not mounted')
+
+    fail = true
+    invalidate()
+    await tick()
+    result.terminal.output = ''
+    result.terminal.send('/skill:stable')
+    await tick()
+    expect(result.terminal.output).toContain('STABLE_COMPLETION_MARKER')
+    await dispose(result)
+  })
+
+  it('keeps the latest slash catalog when asynchronous refreshes settle out of order', async () => {
+    const pendingSnapshots: Array<PromiseWithResolvers<SkillCatalogSnapshot>> = []
+    const result = await setup({
+      configureContext: async (ctx) => {
+        ctx.provide('tools', { get() { return undefined } } as never)
+        ctx.provide('skills', {
+          snapshot: () => {
+            const pending = Promise.withResolvers<SkillCatalogSnapshot>()
+            pendingSnapshots.push(pending)
+            return pending.promise
+          },
+          get: () => Promise.resolve(undefined),
+        } as never)
+      },
+    })
+    expect(pendingSnapshots).toHaveLength(1)
+
+    result.ctx.emit('skills/change')
+    result.ctx.emit('skills/change')
+    expect(pendingSnapshots).toHaveLength(3)
+    pendingSnapshots[2]?.resolve({
+      skills: [{
+        name: 'latest-skill',
+        description: 'LATEST_COMPLETION_MARKER',
+        invocation: { modelInvocable: true, userInvocable: true },
+        source: 'runtime',
+        provider: 'runtime',
+      }],
+      complete: true,
+    })
+    await tick()
+    pendingSnapshots[0]?.resolve({
+      skills: [{ name: 'stale-first', description: 'STALE_FIRST', invocation: { modelInvocable: true, userInvocable: true }, source: 'runtime', provider: 'runtime' }],
+      complete: true,
+    })
+    pendingSnapshots[1]?.resolve({
+      skills: [{ name: 'stale-second', description: 'STALE_SECOND', invocation: { modelInvocable: true, userInvocable: true }, source: 'runtime', provider: 'runtime' }],
+      complete: true,
+    })
+    await tick()
+
+    result.terminal.output = ''
+    result.terminal.send('/skill:latest')
+    await tick()
+    expect(result.terminal.output).toContain('LATEST_COMPLETION_MARKER')
+    expect(result.terminal.output).not.toContain('STALE_FIRST')
+    expect(result.terminal.output).not.toContain('STALE_SECOND')
+    await dispose(result)
+  })
+
  it('loads a skill as a user turn, appending typed instructions', async () => {
    const result = await setup({ configureContext: withSkills })
    result.terminal.send('/skill:demo-skill')
@@ -3891,6 +4020,22 @@ describe('skill slash command', () => {
  })

  it('checks user policy before loading and rechecks the loaded definition', async () => {
+    const summaries: SkillSummary[] = [
+      {
+        name: 'model-only-skill',
+        description: 'Model-only skill',
+        invocation: { modelInvocable: true, userInvocable: false },
+        source: 'runtime',
+        provider: 'runtime',
+      },
+      {
+        name: 'policy-race-skill',
+        description: 'Policy race skill',
+        invocation: { modelInvocable: true, userInvocable: true },
+        source: 'runtime',
+        provider: 'runtime',
+      },
+    ]
    const get = vi.fn((name: string) => Promise.resolve<SkillDefinition | undefined>({
      name,
      description: 'Policy race skill',
@@ -3903,22 +4048,8 @@ describe('skill slash command', () => {
      configureContext: async (ctx) => {
        ctx.provide('tools', { get() { return undefined } } as never)
        ctx.provide('skills', {
-          list: () => Promise.resolve<SkillSummary[]>([
-            {
-              name: 'model-only-skill',
-              description: 'Model-only skill',
-              invocation: { modelInvocable: true, userInvocable: false },
-              source: 'runtime',
-              provider: 'runtime',
-            },
-            {
-              name: 'policy-race-skill',
-              description: 'Policy race skill',
-              invocation: { modelInvocable: true, userInvocable: true },
-              source: 'runtime',
-              provider: 'runtime',
-            },
-          ]),
+          snapshot: () => Promise.resolve({ skills: summaries, complete: true }),
+          list: () => Promise.resolve(summaries),
          get,
        } as never)
      },
@@ -3989,6 +4120,7 @@ describe('skill slash command', () => {
      configureContext: async (ctx) => {
        ctx.provide('tools', { get() { return undefined } } as never)
        ctx.provide('skills', {
+          snapshot: () => Promise.reject(new Error('list boom')),
          list: () => Promise.reject(new Error('list boom')),
          get: () => Promise.reject(new Error('get boom')),
        } as never)
@@ -4005,16 +4137,17 @@ describe('skill slash command', () => {
  it('drops skill list and lookup results that settle after disposal', async () => {
    let listCalls = 0
    let resolvePendingList: ((value: SkillSummary[]) => void) | undefined
+    const pendingSnapshots: Array<(value: SkillCatalogSnapshot) => void> = []
    const pendingGet: Array<{ resolve: (value: SkillDefinition | undefined) => void; reject: (error: unknown) => void }> = []
    const result = await setup({
      configureContext: async (ctx) => {
        ctx.provide('tools', { get() { return undefined } } as never)
        ctx.provide('skills', {
+          snapshot: () => new Promise<SkillCatalogSnapshot>((resolve) => { pendingSnapshots.push(resolve) }),
          list: () => {
            listCalls += 1
-            if (listCalls === 1) return Promise.resolve<SkillSummary[]>([])
-            if (listCalls === 2 || listCalls === 3) {
-              const name = listCalls === 2 ? 'demo-skill' : 'error-skill'
+            if (listCalls === 1 || listCalls === 2) {
+              const name = listCalls === 1 ? 'demo-skill' : 'error-skill'
              return Promise.resolve<SkillSummary[]>([{
                name,
                description: 'demo',
@@ -4041,6 +4174,20 @@ describe('skill slash command', () => {
    await tick()
    await dispose(result)

+    result.ctx.emit('skills/change')
+    expect(pendingSnapshots).toHaveLength(1)
+    for (const resolve of pendingSnapshots) {
+      resolve({
+        skills: [{
+          name: 'late',
+          description: 'late',
+          invocation: { modelInvocable: true, userInvocable: true },
+          source: 'runtime',
+          provider: 'runtime',
+        }],
+        complete: true,
+      })
+    }
    resolvePendingList?.([{
      name: 'other-skill',
      description: 'late',