From bffd80fa12906de6886321b4704135a0bf5930b0 Mon Sep 17 00:00:00 2001 From: Turtle Date: Wed, 22 Jul 2026 10:55:19 +0800 Subject: [PATCH] feat(tui): add /skill: manual skill invocation command --- .../feature/2026-07-05-skill-system.md | 2 +- ...26-07-21-tui-skill-slash-command.i18n.yaml | 6 ++++ .../2026-07-21-tui-skill-slash-command.md | 33 +++++++++++++++++++ .../2026-07-21-tui-skill-slash-command.zh.md | 33 +++++++++++++++++++ packages/ui/tui/tsconfig.json | 6 ++++ 5 files changed, 79 insertions(+), 1 deletion(-) create mode 100644 .agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.i18n.yaml create mode 100644 .agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.md create mode 100644 .agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.zh.md diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.md index e59013c0a8..eccc58f7c2 100644 --- a/.agents/notes/implemented/feature/2026-07-05-skill-system.md +++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.md @@ -50,4 +50,4 @@ The catalog is deterministic for a fixed root set and runtime registration revis ## Deferred -Forked skill contexts (`context: fork`), direct user/slash invocation (`user-invocable`), parameter declarations and hints (`arguments` and `argument-hint`), and per-skill tool constraints (`allowed-tools` and `disallowed-tools`) are outside the shipped contract. The registry, local provider, and model-facing tool do not parse, advertise, or enforce these fields. +Forked skill contexts (`context: fork`), parameter declarations and hints (`arguments` and `argument-hint`), and per-skill tool constraints (`allowed-tools` and `disallowed-tools`) are outside the shipped contract. The registry, local provider, and model-facing tool do not parse, advertise, or enforce these fields, and the `user-invocable` frontmatter field is likewise unparsed. Direct user invocation itself ships as a consumer-side affordance instead: the TUI front door offers a manual `/skill:` command over the registry's existing `list()` and `get()` methods, without a registry, provider, or tool contract change — see [the TUI skill slash command](2026-07-21-tui-skill-slash-command.md). diff --git a/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.i18n.yaml new file mode 100644 index 0000000000..40dd8f463e --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.i18n.yaml @@ -0,0 +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 +2026-07-21-tui-skill-slash-command.md: d7532a05fce5605491ce42c87a2a523eb4c19acc +2026-07-21-tui-skill-slash-command.zh.md: 16930020bd404f7bc9476169cd1d063aa57b5c94 diff --git a/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.md b/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.md new file mode 100644 index 0000000000..d7532a05fc --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.md @@ -0,0 +1,33 @@ +# Agent Note: TUI skill slash command + +Status: implemented + +English | [中文](2026-07-21-tui-skill-slash-command.zh.md) + +## Problem + +The [skill system](2026-07-05-skill-system.md) shipped with model-initiated loading as its only path: the `skill({ name })` tool lets the model pull a skill body into a turn, but a person driving the TUI could not load a skill on demand. Other coding agents expose a `/skill:` slash command for exactly this — the user, not the model, decides a task matches a skill and injects its instructions. The skill-system note listed direct user invocation as deferred work, and the interactive front door is where it belongs. + +## Decision + +The [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) front door owns a `/skill: [instructions]` command. On submit it loads the named skill and delivers one text block as a user turn — sent with `agent.send()` while idle and `agent.steer()` while running, the same rule as ordinary editor input. The block is `renderSkillInvocation(skill, instructions)`: a `` element wrapping the skill body, preceded by one resource-base line when the provider exposes one, with the user's trailing text appended after a blank line. The command is a TUI-only affordance; it adds no model-facing tool and changes no skill-system package contract. + +The TUI reads the skill service through `ctx.get('skills')`, not a declared injection, because skills mount conditionally: a deployment without the registry keeps a working front door, and `/skill:` there reports that skills are unavailable rather than failing to mount. `createTuiChat` is synchronous while `ctx.skills.list()` is async, so autocomplete seeds the static slash commands immediately and rebuilds the provider with `skill:` entries once the catalog resolves; a resolution that arrives after disposal is dropped, and a rejected lookup keeps the base commands. + +Autocomplete lists only model-invocable skills — it is built from `list()`, which omits `disableModelInvocation` skills — while manual submission resolves through `get()`, which the skill registry documents as the trusted-caller path that returns disabled skills too. So a person can load any skill by typing its exact name, but the completion menu never advertises a skill the model is meant not to see. An unknown name, an empty name after the prefix, and a lookup failure each surface as a transcript notice without sending anything. + +`renderSkillInvocation` and the resource-base line are the TUI's own, deliberately not reused from `dsh-tool-skill`'s `skill` tool result. The tool wraps a body in ``/``/`` for a *tool result*; a manual invocation is a *user turn*, and coupling the two renderers would force one model-facing shape to serve both surfaces. The cost is two renderers that both format a skill body; the benefit is that each surface's model-facing text evolves independently, and each is pinned where it is produced. + +## Alternatives considered + +**Add a `user-invocable` frontmatter field and enforce it in the registry.** Rejected for this change. The skill-system note defers that field, and manual invocation does not need it: the TUI is a trusted local caller, so `get()` already authorizes loading any skill, and autocomplete visibility keys off the existing `disableModelInvocation`. A new per-skill field would add a contract to the registry, local provider, and tool with no current consumer beyond visibility, which `disableModelInvocation` already covers. + +**Declare `skills` as a TUI injection.** Rejected because skills mount conditionally; a declared injection would make the front door require the registry and refuse to mount without it, contradicting the package's optional-service stance. `ctx.get('skills')` reads the global store and tolerates absence. + +**Reuse `dsh-tool-skill`'s renderer.** Rejected because its output is a tool-result shape (`` and siblings) written for the model's tool channel, while a slash invocation is a user message. Sharing it would either leak tool-result vocabulary into a user turn or fork the shared renderer on a `surface` flag — more coupling than two small formatters. + +**Route submissions through the model's `skill` tool.** Rejected because the user has already decided; a tool call would spend a model round-trip to fetch a body the front door can load directly, and would not work while the agent is mid-turn. + +## Consequences + +Manual invocation always reloads the full skill body: the TUI does not detect a skill already present in the conversation, so a repeated `/skill:` appends its instructions again — acceptable because re-injection is sometimes the intent, and documented under the package README's Known Limitations. The two-renderer duplication is a standing maintenance cost accepted above. The `` wrapper is stable model-visible text and is pinned verbatim in unit tests against a real `SkillService`; the help-panel line is pinned by the `errors-and-help` terminal snapshot. Autocomplete population and the disposed-lookup and failed-lookup branches are covered by unit tests that mount the real registry or a controllable service. End-to-end delivery is proven by a dedicated real-composition test: the `examples/tui-agent` keyless PTY smoke (`tui-keyless-smoke.e2e.ts`) boots the production TUI/agent/skill stack through the Loader under a genuine pseudo-terminal with only the model scripted, drops a fixture skill under the agents-home `skills/` root, types `/skill:` as live keystrokes, and asserts the scripted adapter echoes the fixture's body marker only when the rendered `` block arrives — exercising `ctx.get('skills')` resolution in the shipped tree, the client-side parse, the local provider load, and the user turn reaching the model together. That fixture's frontmatter description avoids a `: ` colon-space so its YAML stays a plain scalar; an invalid-frontmatter skill is silently dropped during discovery. diff --git a/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.zh.md b/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.zh.md new file mode 100644 index 0000000000..16930020bd --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.zh.md @@ -0,0 +1,33 @@ +# Agent Note: TUI skill slash command + +Status: implemented + +[English](2026-07-21-tui-skill-slash-command.md) | 中文 + +## Problem + +[skill 系统](2026-07-05-skill-system.md)交付时只有模型发起加载这一条路径：`skill({ name })` 工具让模型把某个 skill 正文拉进一个轮次，但操作 TUI 的人无法按需加载 skill。其他编码 agent（智能体）正是为此提供了 `/skill:` 斜杠命令——由用户而非模型判断某个任务与某个 skill 匹配，并注入其指令。skill 系统 note 把直接的用户发起调用列为待办工作，而交互式前门正是它该落地的地方。 + +## Decision + +[`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) 前门拥有一条 `/skill: [instructions]` 命令。提交时它加载指定的 skill，并投递一个文本块作为用户轮次——空闲时用 `agent.send()` 发送、运行中用 `agent.steer()` 中途引导，与普通编辑器输入遵循同一规则。该文本块由 `renderSkillInvocation(skill, instructions)` 生成：一个包裹 skill 正文的 `` 元素，当提供方暴露资源基址时在其前加一行资源基址行，用户尾随的文本在空行之后追加。该命令是 TUI 独有的能力；它不新增任何面向模型的工具，也不改动任何 skill 系统包的契约。 + +TUI 通过 `ctx.get('skills')` 读取 skill 服务，而非声明式注入，因为 skill 是条件挂载的：没有注册表的部署仍保有可用的前门，此时 `/skill:` 会报告 skill 不可用，而不是挂载失败。`createTuiChat` 是同步的，而 `ctx.skills.list()` 是异步的，所以自动补全先立即种入静态斜杠命令，待目录解析完成后再用 `skill:` 条目重建 provider（提供方）；在 dispose（资源释放）之后才到达的解析结果会被丢弃，而被拒绝的查找会保留基础命令。 + +自动补全只列出模型可调用的 skill——它基于 `list()` 构建，而 `list()` 会略去 `disableModelInvocation` 的 skill——手动提交则通过 `get()` 解析，skill 注册表将其记录为返回被禁用 skill 的可信调用方路径。因此用户可以通过键入 skill 的确切名称加载任意 skill，但补全菜单绝不会宣传一个本不该让模型看见的 skill。未知名称、前缀之后为空的名称、以及查找失败，都会各自呈现为 transcript（文本记录）中的一条通知，且不发送任何内容。 + +`renderSkillInvocation` 及资源基址行是 TUI 自有的，刻意不复用 `dsh-tool-skill` 的 `skill` 工具结果。该工具把正文包进 ``/``/`` 是为了一个*工具结果*；而手动调用是一个*用户轮次*，把两个渲染器耦合起来会迫使一种面向模型的形态同时服务两个界面。代价是两个都在格式化 skill 正文的渲染器；收益是各界面面向模型的文本可以独立演进，且各自在其产出处被固定。 + +## Alternatives considered + +**新增 `user-invocable` frontmatter 字段并在注册表中强制执行。** 本次改动否决。skill 系统 note 把该字段列为待办，而手动调用并不需要它：TUI 是可信的本地调用方，`get()` 已经授权加载任意 skill，自动补全的可见性以既有的 `disableModelInvocation` 为准。新增一个逐 skill 字段会给注册表、本地提供方和工具都加上一条契约，而除了可见性之外没有任何现有消费方，可见性又已由 `disableModelInvocation` 覆盖。 + +**把 `skills` 声明为 TUI 注入。** 否决，因为 skill 是条件挂载的；声明式注入会使前门必须依赖注册表，缺少它就拒绝挂载，与本包可选服务的立场相悖。`ctx.get('skills')` 读取全局存储并容忍其缺失。 + +**复用 `dsh-tool-skill` 的渲染器。** 否决，因为它的输出是为模型的工具通道所写的工具结果形态（`` 及其同类），而斜杠调用是一条用户消息。共用它要么把工具结果词汇泄漏进用户轮次，要么按 `surface` 标志分叉共享渲染器——比两个小格式化器耦合更重。 + +**让提交经由模型的 `skill` 工具。** 否决，因为用户已经作出了判断；一次工具调用会花掉一个模型往返去取一份前门可以直接加载的正文，而且在 agent 处于轮次中途时也无法工作。 + +## Consequences + +手动调用总是重新加载完整的 skill 正文：TUI 不会检测某个 skill 是否已在对话中出现，因此重复的 `/skill:` 会再次追加其指令——这可以接受，因为重新注入有时正是意图所在，且已在本包 README 的已知限制中说明。上文接受的双渲染器重复是一项长期维护成本。`` 包裹是稳定的、模型可见的文本，并在单元测试中针对一个真实的 `SkillService` 逐字固定；帮助面板那一行由 `errors-and-help` 终端快照固定。自动补全的填充、dispose 后查找分支、以及查找失败分支，都由挂载真实注册表或可控服务的单元测试覆盖。端到端的投递由一项专门的真实组合测试证明：`examples/tui-agent` 的无密钥 PTY 冒烟测试（`tui-keyless-smoke.e2e.ts`）在真实伪终端下经由 loader 引导生产环境的 TUI/agent/skill 栈，仅对模型进行脚本化，把一个夹具 skill 放入 agents home 的 `skills/` 根下，以真实按键输入 `/skill:`，并断言：只有当渲染出的 `` 文本块抵达时，脚本化适配器才会回显该夹具的正文标记——从而一并演练了 `ctx.get('skills')` 在发布树中的解析、客户端解析、本地 provider 的加载，以及用户回合抵达模型。该夹具的 frontmatter 描述避免出现 `: ` 冒号加空格，使其 YAML 保持为纯标量；frontmatter 无效的 skill 会在发现阶段被静默丢弃。 diff --git a/packages/ui/tui/tsconfig.json b/packages/ui/tui/tsconfig.json index b9aed2dbae..2d1bbb2477 100644 --- a/packages/ui/tui/tsconfig.json +++ b/packages/ui/tui/tsconfig.json @@ -23,6 +23,9 @@ { "path": "../../core/session" }, + { + "path": "../../session-persistence/session-persistence" + }, { "path": "../../session-title/session-title" }, @@ -41,6 +44,9 @@ { "path": "../commands" }, + { + "path": "../../skill/skill" + }, { "path": "../user-interaction" },