@morlay/dsh-context-assembler 0.0.1-alpha.2

package/src/assembler/index.ts

@@ -0,0 +1,129 @@
+import type { Context } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import type { AssembledSection } from "@deepseek-ai/dsh-system-prompt";
+import { ContextAssembler, type PromptEntry } from "./channel.ts";
+import { DEFAULT_KEEP, DEFAULT_REPLACE, DEFAULT_SUPPRESS } from "./defaults.ts";
+import { RULES_SECTION, latestReminderText, reminderMessage } from "./reminder.ts";
+import { RULES_TEXT } from "./rules.ts";
+
+export { DEFAULT_KEEP, DEFAULT_REPLACE, DEFAULT_SUPPRESS } from "./defaults.ts";
+export type {
+  InjectionMode,
+  PromptEntry,
+  PromptRuleDeclaration,
+  PromptSkillDeclaration,
+} from "./channel.ts";
+export { ContextAssembler } from "./channel.ts";
+export { renderVirtualSkill } from "./reminder.ts";
+
+export const name = "context-assembler";
+
+/** 规则声明的位置：紧跟部署 persona（order 0），在任何降级内容之前。 */
+const RULES_ORDER = 1;
+
+export const inject = ["systemPrompt", "skills"];
+
+export interface Config {
+  /** 留在系统提示词里的 section 名；其余非空 section 降级为 reminder。 */
+  keep?: string[];
+  /** 不进提示词的 section 名（部署级噪音）。 */
+  suppress?: string[];
+  /** 装配结果上改写的 section 文本（section 名 → 中文文案）。 */
+  replace?: Record<string, string>;
+}
+
+export const Config: z<Config> = z.object({
+  keep: z.array(z.string()).default([...DEFAULT_KEEP]),
+  suppress: z.array(z.string()).default([...DEFAULT_SUPPRESS]),
+  replace: z.dict(z.string()).default({ ...DEFAULT_REPLACE }),
+});
+
+/**
+ * 提示词注入的唯一通道：system prompt 里只留 `keep`，其余内容按声明的方式到达模型——
+ * 降级为紧随用户消息的 reminder、或直接丢弃（写进按需 skill 正文是调用方自己的事）。
+ */
+export function apply(ctx: Context, config: Config): void {
+  const channel = new ContextAssembler(ctx);
+  const keep = new Set(config.keep ?? DEFAULT_KEEP);
+  for (const name of config.suppress ?? DEFAULT_SUPPRESS) channel.suppressSection(name);
+  for (const [name, text] of Object.entries(config.replace ?? DEFAULT_REPLACE)) {
+    channel.replaceSection(name, () => text);
+  }
+
+  ctx.systemPrompt.section({ name: RULES_SECTION, order: RULES_ORDER, text: RULES_TEXT });
+
+  ctx.on("system-prompt/assemble", async (_assembly, context, next) => {
+    const result = await next();
+    const agent = context.agent;
+    const demoted = new Map<string, string>();
+    const sections: AssembledSection[] = [];
+    let changed = false;
+
+    for (const section of result.sections) {
+      if (channel.isSuppressed(section.name)) {
+        changed = true;
+        continue;
+      }
+      const text = channel.replacement(section.name, agent) ?? section.text;
+      if (text !== section.text) changed = true;
+      if (keep.has(section.name) || text.length === 0) {
+        sections.push(text === section.text ? section : { ...section, text });
+        continue;
+      }
+      changed = true;
+      demoted.set(sectionId(section.name), text);
+    }
+
+    if (agent !== undefined) channel.sync(agent, { sections: demoted });
+    return changed ? { ...result, sections } : result;
+  });
+
+  ctx.on("agent/pre-step", async ({ agent, messages }, next) => {
+    const decision = await next();
+
+    if (decision.kind === "reject" || decision.messages.length === 0) return decision;
+    const pending = await pendingEntries(agent, channel);
+    if (pending.length === 0) return decision;
+
+    const claimedEnd = decision.messages.findLastIndex((message) => messages.includes(message));
+    return {
+      ...decision,
+      messages: decision.messages.toSpliced(
+        claimedEnd + 1,
+        0,
+        ...pending.map(([key, entry]) => reminderMessage(key, entry.text, entry.source)),
+      ),
+    };
+  });
+
+  ctx.on(
+    "agent/request-error",
+    async ({ agent, signal }, next) => {
+      const action = await next();
+      if (action?.kind !== "retry" || signal.aborted) return action;
+      for (const [key, entry] of await pendingEntries(agent, channel)) {
+        agent.session.append("user/message", reminderMessage(key, entry.text, entry.source), {
+          surfaceOp: "append",
+        });
+      }
+      return action;
+    },
+    { prepend: true },
+  );
+}
+
+/** 降级 section 的条目 id：一条 section 一个 id，于是同一次变化只重发那一条。 */
+function sectionId(name: string): string {
+  return `section:${name}`;
+}
+
+/** 本步要注入的条目：键相同且文本未变就不注入，按键字典序（顺序不随注册顺序抖动）。 */
+async function pendingEntries(
+  agent: Parameters<typeof latestReminderText>[0],
+  channel: ContextAssembler,
+): Promise<[string, PromptEntry][]> {
+  const entries = await channel.collect(agent);
+  return [...entries]
+    .filter(([key, entry]) => latestReminderText(agent, key) !== entry.text)
+    .toSorted(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+}

package/src/assembler/reminder.ts

@@ -0,0 +1,92 @@
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import { createUserMessage, type MessageSource } from "@deepseek-ai/dsh-llm";
+import type { UserMessage } from "@deepseek-ai/dsh-session";
+
+const REMINDER_OPEN = "<system-reminder";
+const REMINDER_CLOSE = "</system-reminder>";
+
+/**
+ * 覆盖规则在系统提示词里声明一次（见 [`rules.ts`](./rules.ts)），所以每条 reminder 只带 id 与正文，
+ * 不再重复解释"最新一条覆盖更早的"。
+ */
+export const RULES_SECTION = "assembler:rules";
+
+/** 通道自己的条目形态（注入方没声明 source 时的默认）：规则块，幂等键是 id。 */
+export interface PromptReminderSource {
+  kind: "context-assembler";
+  form: "instructions";
+  /** 条目 id：同 id 的最新一条取代更早的同 id 条目。本插件早先落库的消息没有它。 */
+  id?: string;
+}
+
+declare module "@deepseek-ai/dsh-llm" {
+  interface MessageSourceMap {
+    "context-assembler": PromptReminderSource;
+  }
+}
+
+/**
+ * 这条消息是不是通道注入的条目——判据是 source 里的幂等键，而不是 kind：接管上游那两面的条目
+ * 用上游 kind（`agent-instructions` / `skill-catalog`），幂等必须照样认。
+ */
+export function promptEntryIdOf(source: MessageSource): string | undefined {
+  const id = (source as { readonly id?: unknown }).id;
+  return typeof id === "string" ? id : undefined;
+}
+
+function escapeFrameBody(body: string): string {
+  return body.replaceAll(REMINDER_CLOSE, "<\\/system-reminder>");
+}
+
+function escapeAttr(value: string): string {
+  return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;");
+}
+
+export function renderReminder(id: string, body: string): string {
+  return `${REMINDER_OPEN} id="${escapeAttr(id)}">\n${escapeFrameBody(body)}\n${REMINDER_CLOSE}`;
+}
+
+/**
+ * 虚拟 skill（运行时注册、没有资源目录）的正文形态：只有 `<skill_instructions>`，
+ * 不渲染上游 `renderSkillContent` 的 `<skill_resources>`（那段对虚拟 skill 是噪音）。
+ */
+export function renderVirtualSkill(name: string, content: string): string {
+  return [
+    `<skill_content name="${escapeAttr(name)}">`,
+    "<skill_instructions>",
+    content,
+    "</skill_instructions>",
+    "</skill_content>",
+  ].join("\n");
+}
+
+/** 这条消息是不是通道注入的条目（判据是 source 里的幂等键，见 `promptEntryIdOf`）。 */
+export function isPromptReminder(message: UserMessage): boolean {
+  return promptEntryIdOf(message.source) !== undefined;
+}
+
+/** surface 上最近一条该 id 的 reminder 原文（含信封）；没有则 undefined。 */
+export function latestReminderText(agent: Agent, id: string): string | undefined {
+  for (const seq of agent.session.surface.nodes.toReversed()) {
+    const event = agent.session.eventAt(seq);
+    if (event?.type !== "user/message") continue;
+    if (promptEntryIdOf(event.data.source) !== id) continue;
+    const [block] = event.data.content;
+    return event.data.content.length === 1 && block?.type === "text" ? block.text : "";
+  }
+  return undefined;
+}
+
+/**
+ * 注入一条提醒：`text` 是已渲染好的完整正文（规则块或内容块），`key` 是它的幂等键。
+ * `source` 声明这条消息对外的身份——接管上游那两面用上游 kind，我们自己的条目留默认。
+ */
+export function reminderMessage(key: string, text: string, source?: MessageSource): UserMessage {
+  return createUserMessage({
+    content: [{ type: "text", text }],
+    source: {
+      ...(source ?? { kind: "context-assembler", form: "instructions" }),
+      id: key,
+    } as MessageSource,
+  });
+}

package/src/assembler/rules.ts

@@ -0,0 +1,14 @@
+import { RULES_SECTION } from "./reminder.ts";
+
+/**
+ * 覆盖规则的声明文本：写进**系统提示词**（不在 reminder 里重复），所以每条 reminder 只带 id 与正文。
+ *
+ * 为什么放系统提示词而不是首条 reminder：它是固定文本（不随会话变，不付缓存代价），而且放在这里
+ * 才是系统级规则该在的位置——首条 reminder 自身会被压缩、被覆盖，权威性更低。
+ */
+export const RULES_TEXT = [
+  "带 id 的 system-reminder 块是本系统提示词的一部分，持续有效：同 id 只有最新一条生效并取代更早的，不同 id 互不影响。",
+  "skill_content 是要遵循的技能说明（随提示送来的与你后来加载的一样），file_content 是本步引用的文件内容。",
+].join("");
+
+export { RULES_SECTION };

package/src/index.ts

@@ -0,0 +1,56 @@
+/**
+ * 组装出口：按 config 把各能力装成一个 cordis 插件树。
+ *
+ * 装配面因此只有**一行**（`@morlay/dsh-context-assembler`）：`isolate` 是行级选项，一行声明就覆盖它整棵子树，
+ * 而这里 `ctx.plugin()` 出来的子插件都继承行 ctx 的 isolate map 与 scope——通道服务仍在 preset 的
+ * realm 里、`scope` 的归属判据仍按 preset scope 成立。**每个子插件各有自己的 `inject`**（合成单入口会
+ * 让 inject 变并集，一个可选搭档缺席就拖垮整包），这是这层组装唯一必须守住的东西。
+ *
+ * `coding` 不带 config（完整一套）；`chat` 用 `capabilities` 裁掉不要的能力、用 `options` 给留下的
+ * 那些传参（能力名就是子出口名）。
+ */
+import type { Context } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import * as agentInstructions from "./agent-instructions/index.ts";
+import * as assembler from "./assembler/index.ts";
+import * as scope from "./scope/index.ts";
+import * as skillCatalog from "./skill-catalog/index.ts";
+
+export const name = "context-assembler-tree";
+
+const CAPABILITIES = {
+  assembler,
+  "agent-instructions": agentInstructions,
+  "skill-catalog": skillCatalog,
+  scope,
+} as const;
+
+export type Capability = keyof typeof CAPABILITIES;
+
+const CAPABILITY_NAMES = Object.keys(CAPABILITIES) as Capability[];
+
+export interface Config {
+  /** 装哪些能力（名字即子出口名）；缺省全部——标准模式要完整的一套。未知名字在装载时报错。 */
+  capabilities?: string[];
+  /** 各能力自己的 config，按能力名给（例如 `{ scope: { allowTools: [...] } }`）。 */
+  options?: Record<string, Record<string, unknown>>;
+}
+
+export const Config: z<Config> = z.object({
+  capabilities: z.array(z.string()).default([...CAPABILITY_NAMES]),
+  options: z.any().default({}),
+});
+
+export function apply(ctx: Context, config: Config): void {
+  const wanted = config.capabilities ?? CAPABILITY_NAMES;
+  const options = config.options ?? {};
+  for (const name of wanted) {
+    const capability = CAPABILITIES[name as Capability];
+    if (capability === undefined) {
+      throw new Error(
+        `context: unknown capability "${name}"（可选：${CAPABILITY_NAMES.join(" / ")}）`,
+      );
+    }
+    ctx.plugin(capability, options[name] ?? {});
+  }
+}

package/src/rows.ts

@@ -0,0 +1,64 @@
+/**
+ * 本包作为 **bundle** 的行清单：`dsh.profile.bundles` 列出本包时由它渲染成 `cordis.patch.yml`。
+ *
+ * 通道装在 host 平面，整份部署共享一套注入。**不做隔离**——工具说明
+ * （`@morlay/dsh-agent-toolkit/guidance`，在别的包里）与 skill 目录这类消费者都在别的行上
+ * `inject` 它，隔离会把它们挡在组外（行停在 waiting，不报错）。
+ *
+ * preset 只装 `scopeRow()`（模式的开关）：它 `inject` 通道，`ctx.get("contextAssembler")` 在 agent
+ * 子树里可达，不需要另装一份通道。
+ */
+
+/** 组装出口（包根）就是那个"按 config 装能力"的插件。 */
+export const CONTEXT_PACKAGE = "@morlay/dsh-context-assembler";
+
+/** 一行 plugin entry（本模块只描述形状，类型由消费方自己那份行类型决定）。 */
+export interface ContextRow {
+  readonly id: string;
+  readonly name: string;
+  readonly config?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * 通道那一行：包的主出口是**组装插件**——按 config 决定装哪些能力、各带什么参数，所以装配面
+ * 只有这一行，组成与各能力的 config 都归包内（缺省即完整的一套；`chat` 用它裁剪）。
+ */
+export function contextChannel(config?: Readonly<Record<string, unknown>>): ContextRow {
+  return {
+    id: "context-assembler",
+    name: CONTEXT_PACKAGE,
+    ...(config === undefined ? {} : { config }),
+  };
+}
+
+/**
+ * 模式开关那一行：`scope` 出口按 preset 配（工具白名单、instruction 总开关、动态快照开关）。
+ *
+ * 通道在 profile 平面装一次，这一行只按模式收口（它 `inject` `contextAssembler`，
+ * `ctx.get("contextAssembler")` 在 agent 子树里可达）。
+ */
+export function scopeRow(config?: Readonly<Record<string, unknown>>): {
+  readonly id: string;
+  readonly name: string;
+  readonly config?: Readonly<Record<string, unknown>>;
+} {
+  return {
+    id: "context-scope",
+    name: "@morlay/dsh-context-assembler/scope",
+    ...(config === undefined ? {} : { config }),
+  };
+}
+
+/**
+ * bundle patch 的行清单：通道一行（`scope` 是模式的开关，由 preset 装 `scopeRow()`）。
+ *
+ * 形态是 `insert`：这些行由本包提供给 host 平面。写成 `- id: x` 那种"改已有行"的形态时，装配期找不到
+ * 目标行（只 warn 后跳过），通道根本没装上，引用它的行停在 waiting。
+ */
+export const PATCH_ROWS: readonly { readonly insert: readonly ContextRow[] }[] = [
+  {
+    insert: [
+      contextChannel({ capabilities: ["assembler", "agent-instructions", "skill-catalog"] }),
+    ],
+  },
+];

package/src/scope/index.ts

@@ -0,0 +1,118 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import { scopeChainOf, scopeOf } from "@deepseek-ai/dsh-scope";
+import z from "@deepseek-ai/schemastery";
+import type {} from "../assembler/index.ts";
+
+export const name = "context-scope";
+
+export const inject = ["tools", "systemPrompt"];
+
+export interface Config {
+  /**
+   * 只保留这些工具；其余（含 host 层 bundle 加进来的）既不进模型目录，调用不了，它们自己注册的说明
+   * section（`tool:<工具名>`）也不留在提示词里。
+   */
+  allowTools?: string[];
+  /**
+   * 是否要 instruction 类的注入（工作区指令、技能目录、用法正文那类规则块）。缺省要；
+   * `false` 表示这个模式不要任何 instructions——对话模式就是它。
+   *
+   * 关的是**规则块与降级 section**（通道的 `setInstructions`）；内容块（`auto` 组正文、引用材料）
+   * 不受这个开关管，要靠对应的注入方自己不注册（chat 同时给了 `groups: false`）。
+   * 注意这与工具白名单是两件事：工具没给，跟着它的注入本来就该自己关（见各注入包对 requires 的判断）；
+   * 这里是"连与工具无关的 instruction 也不要"的总开关。
+   */
+  instructions?: boolean;
+  /**
+   * 是否要 runtime context（动态快照：文件沙箱策略、审批策略）。缺省要；`false` 表示这个模式不要它们
+   * ——对话模式没有文件与 shell 工具，"能改工作区哪些文件、要不要走审批"对它全是噪音。
+   *
+   * 抑制是**按 scope** 的（上游按装配的 scope 链查抑制器），所以本行装在 preset 子树里就只作用于这个
+   * 模式的会话；它只挡注入，不改任何提供方的行为（沙箱该怎么判还怎么判）。
+   */
+  runtimeContext?: boolean;
+}
+
+export const Config: z<Config> = z.object({
+  allowTools: z.array(z.string()).default([]),
+  instructions: z.boolean().default(true),
+  runtimeContext: z.boolean().default(true),
+});
+
+const OUT_OF_SCOPE = (toolName: string): string =>
+  `${toolName} 不在本模式的工具范围内，用它不会有结果；按当前模式提供的工具完成任务，或让用户切到别的模式。`;
+
+/** 单个工具的说明 section 名前缀：`tool:<工具名>`（`tools:` 那类是聚合块，不归白名单管）。 */
+const TOOL_SECTION_PREFIX = "tool:";
+
+/**
+ * 把某个 preset 的工具收成"只有这些"。
+ *
+ * 为什么需要它：preset composition 只能决定"加什么"，管不了 host 层——`dsh.profile.bundles` 打开的
+ * bundle（例如实验性的 Agent Teams）会在 host 层插工具行与 section，对所有 preset 一视同仁。模式想
+ * 表达"我只有这几个工具、一条提示词都不要"时，唯一与来源无关的做法是收口"有什么"。
+ *
+ * 为什么不是 `tools.restrict()`：它会改动可见工具集，从而触发 `tools/change`；上游 `tool-subagent`
+ * 正是用该事件做 composition reconcile——两边互相触发会变成装配风暴。这里用投影过滤加执行层 guard：
+ * 既不碰注册表、也不发事件。
+ */
+export function apply(ctx: Context, config: Config): void {
+  const allow = new Set(config.allowTools ?? []);
+  if (allow.size === 0) {
+    throw new Error(
+      "context-scope: `allowTools` must name at least one tool; omit the row instead of mounting an empty scope",
+    );
+  }
+  const presetKey = scopeOf(ctx);
+  const scoped = new WeakSet<Agent>();
+
+  if (config.runtimeContext === false) {
+    // service 在 scoped ctx 上是 shadow：注册落在本行的 scope（preset 子树），抑制因此只覆盖这个模式。
+    ctx.systemPrompt.suppressRuntimeContext();
+  }
+
+  const belongs = (agent: Agent): boolean => {
+    if (presetKey === undefined) return true;
+    const key = scopeOf(agent.ctx);
+    return key !== undefined && scopeChainOf(key).includes(presetKey);
+  };
+
+  /** 每个会话只做一次：拨提示词开关，并挂上执行层白名单。 */
+  const scopeOnce = (agent: Agent): void => {
+    if (scoped.has(agent) || !belongs(agent)) return;
+    scoped.add(agent);
+    // 通道是可选的（`ctx.get` 在未声明 inject 的 ctx 上会抛，所以自己兜住）：没有它就没有 instruction
+    // 可关、也没人收窄技能目录，但工具目录与执行 guard 照常生效——不该因为一个可选搭档缺席就让整个插件
+    // 不激活。工具收窄必须交给它：投影层的过滤不碰注册表，注册表上看不出"谁能用"。
+    try {
+      const channel = ctx.get("contextAssembler");
+      if (config.instructions === false) channel?.setInstructions(agent, false);
+      channel?.restrictTools(agent, (tool) => allow.has(tool));
+    } catch {
+      void 0;
+    }
+    // inject 回调只是在该 ctx 上解锁 `tools`；调用必须落在 `agent.ctx` 上才是这个会话的作用域。
+    agent.ctx.inject(["tools"], () => {
+      agent.ctx.tools.guard((exec) => (allow.has(exec.name) ? undefined : OUT_OF_SCOPE(exec.name)));
+    });
+  };
+
+  // 在**装配期**注册，不在创建期：创建期 tools 的可用性还在变，那时注册容易与装配流程互相牵扯
+  // （`tools/change` 的回响就是这么来的）。目录过滤也在这里，每步幂等。
+  ctx.on("system-prompt/assemble", async (_assembly, context, next) => {
+    const agent = context.agent;
+    if (agent !== undefined) scopeOnce(agent);
+    const result = await next();
+    return {
+      ...result,
+      // 工具自己的说明 section 与工具目录同源：目录里没有的工具，它的说明也不该留在提示词里。
+      sections: result.sections.filter((section) =>
+        section.name.startsWith(TOOL_SECTION_PREFIX)
+          ? allow.has(section.name.slice(TOOL_SECTION_PREFIX.length))
+          : true,
+      ),
+      tools: result.tools.filter((tool) => allow.has(tool.name)),
+    };
+  });
+}

package/src/skill-catalog/index.ts

@@ -0,0 +1,177 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import { isModelInvocable, isSkillName } from "@deepseek-ai/dsh-skill";
+import type {} from "@deepseek-ai/dsh-tool-skill";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import type {} from "../assembler/index.ts";
+import { renderVirtualSkill } from "../assembler/index.ts";
+
+export const name = "context-skill-catalog";
+
+export const inject = ["skills", "tools", "contextAssembler"];
+
+export const CATALOG_ID = "skill-catalog";
+
+/** 目录行里的描述长度上限（上游默认同值）。 */
+const DESCRIPTION_MAX_LENGTH = 500;
+
+/**
+ * skill 目录 + `skill` 工具：目录是规则块（一行名字 + 摘要），正文按需加载。
+ *
+ * 目录只列模型可调用的 skill；`auto` 的 skill 标 `modelInvocable: false`，所以它不出现在目录里
+ * （它的正文已经随提示送达）。工具的渲染用通道的虚拟 skill 形态，不带 `<skill_resources>`。
+ */
+export function apply(ctx: Context): void {
+  /**
+   * 本会话上次算出的目录条目：`source` 是同步的、正文是异步的，两者共用这一次计算的结果
+   * （`collect` 里先算正文再取 source）。
+   */
+  const catalogEntries = new WeakMap<Agent, readonly { name: string; description: string }[]>();
+
+  ctx.contextAssembler.registerRule({
+    id: CATALOG_ID,
+    // 对外身份沿用上游 kind：客户端标签与按 kind 认领的消费方认得这是技能目录，`entries` 就是
+    // 目录行里发布的那份清单（非模型消费者照它列条目）。
+    source: (agent) => ({
+      kind: "skill-catalog",
+      form: "catalog",
+      entries: catalogEntries.get(agent) ?? [],
+    }),
+    text: async (agent) => {
+      // 目录没了（工具不在、快照不全、一个 skill 都不可见）就把上次的条目也清掉：`source` 与正文同源。
+      const noCatalog = (): string => {
+        catalogEntries.delete(agent);
+        return "";
+      };
+      // "谁能用"要连模式的白名单一起算（注册表里有不等于这个会话能用），否则被收窄的工具还会留下技能目录。
+      const visible = ctx.contextAssembler.visibleTools(
+        agent,
+        (tool) => ctx.tools.get(tool, agent) !== undefined,
+      );
+      // 依赖关系：没有 `skill` 工具（被白名单挡掉或被别的 composition 拿掉）时，目录没有意义——
+      // 模型拿到了名字也加载不了。是否注入跟着工具走，而不是靠每个模式去列"不要哪些"。
+      if (!visible("skill")) return noCatalog();
+      // 必须带上会话的 cwd 与作用域：本地 skill 发现（`~/.agents/skills`、`{cwd}/.agents/skills`、
+      // 项目根）由 preset 层的 `skill-filesystem` 行提供，host 层的同名行在 web 组合里是禁用的——
+      // 不传作用域只看得见全局层（本仓库注册的运行时 skill），不传 cwd 连项目根都不扫。
+      const snapshot = await ctx.skills.snapshot({
+        cwd: agent.session.header.cwd,
+        scope: agent,
+      });
+      if (!snapshot.complete) return noCatalog();
+      // 技能也跟着工具走：依赖的工具一个都不可见的 skill 不进目录（模型看到名字也用不上）。
+      const hidden = ctx.contextAssembler.hiddenSkills(visible);
+      const skills = snapshot.skills
+        .filter(isModelInvocable)
+        .filter((skill) => !hidden.has(skill.name));
+      if (skills.length === 0) return noCatalog();
+      const entries = skills.map((skill) => ({
+        name: skill.name,
+        description: clamp(skill.description, DESCRIPTION_MAX_LENGTH),
+      }));
+      catalogEntries.set(agent, entries);
+      return [
+        "<available_skills>",
+        ...entries.map((entry) => `- ${entry.name}: ${entry.description}`),
+        "</available_skills>",
+        "",
+        "任务与某个 skill 说明匹配时，先加载它再行事。",
+      ].join("\n");
+    },
+  });
+
+  // 同名工具只能有一个所有者：host 层的 `tool-skill` 行由 patch 禁用，但万一没禁掉（上游改了行 id、
+  // 或别的 bundle 又插了一份），重复注册会让 tools/change 抖动甚至让 session 创建失败——所以先看清
+  // 注册表里有没有，有就让给对方，我们只负责目录。
+  if (ctx.tools.get("skill") !== undefined) {
+    ctx.logger.warn(
+      "context-skill-catalog: a `skill` tool is already registered; keeping the existing one and only publishing the catalog",
+    );
+  } else {
+    registerSkillTool(ctx);
+  }
+}
+
+function registerSkillTool(ctx: Context): void {
+  const skillTool = defineTool({
+    name: "skill",
+    description: "按需加载 skill 的完整说明。",
+    parameters: {
+      name: { type: "string", required: true, description: "技能目录里的 skill 名。" },
+    },
+    output: {
+      // 与上游 `tool-skill` 的输出**同形**（`additionalProperties: false`，少一个字段就是校验不过）：
+      // 客户端按这个结构渲染 skill 结果，缺 `provider` 会让那次调用直接失败。
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          name: { type: "string", required: true },
+          provider: { type: "string", required: true },
+          resourceBase: {
+            oneOf: [
+              {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  kind: { type: "string", required: true, const: "directory" },
+                  path: { type: "string", required: true },
+                },
+              },
+              {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  kind: { type: "string", required: true, const: "url" },
+                  url: { type: "string", required: true },
+                },
+              },
+              {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  kind: { type: "string", required: true, const: "opaque" },
+                  description: { type: "string", required: true },
+                },
+              },
+            ],
+          },
+          content: { type: "string", required: true },
+        },
+      },
+      render: (_args, value) => [
+        { type: "text", text: renderVirtualSkill(value.name, value.content) },
+      ],
+    },
+    async execute(args, exec) {
+      if (!isSkillName(args.name)) throw new Error(`invalid skill name "${args.name}"`);
+      const lookup = {
+        cwd: exec.agent?.session.header.cwd,
+        signal: exec.signal,
+        scope: exec.agent,
+      };
+      const skill = await ctx.skills.get(args.name, lookup);
+      if (skill === undefined)
+        throw new Error(`skill "${args.name}" is unknown or no longer available`);
+      if (!isModelInvocable(skill))
+        throw new Error(`skill "${args.name}" is not available for model invocation`);
+      // 注册表里那份是不过滤的全量（技能注册是装配期一次），按需加载时按这个会话重算一份：
+      // 组正文不该讲这个会话没装的工具。
+      const content = ctx.contextAssembler.contentFor(skill.name, exec.agent) ?? skill.content;
+      return { name: skill.name, provider: skill.provider, content };
+    },
+    presentCall(args) {
+      return {
+        card: "generic",
+        title: `Load skill ${args.name}`,
+        kind: "read",
+        rawInput: args.name,
+      };
+    },
+  });
+  ctx.tools.register(skillTool);
+}
+
+function clamp(text: string, max: number): string {
+  return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}