@morlay/dsh-context-assembler 0.0.2 → 0.0.3

package/src/assembler/index.ts

@@ -1,129 +0,0 @@
-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

@@ -1,101 +0,0 @@
-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";
-  /**
-   * 条目形态：`instructions` 是规则块；`catalog` 是"带清单的目录"（客户端按 `entries` 列条目，
-   * 而不是读正文）。
-   */
-  form: "instructions" | "catalog";
-  /**
-   * `catalog` 形态发布的那份清单。**只有我们自己发布的目录**用它：上游 `tool-skill` 的账本扫法
-   * 只认它自己的 `kind`，所以这里的 kind 必须是我们自己的（见 [`skill-catalog`](../skill-catalog/index.ts)）。
-   */
-  entries?: readonly { readonly name: string; readonly description: string }[];
-  /** 条目 id：同 id 的最新一条取代更早的同 id 条目。本插件早先落库的消息没有它。 */
-  id?: string;
-}
-
-declare module "@deepseek-ai/dsh-llm" {
-  interface MessageSourceMap {
-    "context-assembler": PromptReminderSource;
-  }
-}
-
-/**
- * 这条消息是不是通道注入的条目——判据是 source 里的幂等键，而不是 kind：接管上游那两面的条目
- * 接管工作区指令那一面的条目用上游 kind（`agent-instructions`），幂等必须照样认。
- */
-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

@@ -1,14 +0,0 @@
-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/scope/index.ts

@@ -1,150 +0,0 @@
-/**
- * 按**会话**收口：工具白名单、instruction 总开关、动态快照。
- *
- * 这是本包的 `scope` 出口（行 id `context-assembler-scope`）。它不再吃 config，也不认识"模式"这个概念——
- * 收口要什么由消费方在会话建立时**推**进来：`ctx.sessionToolScope.apply(agent, mode)`（
- * [`@morlay/dsh-session-mode`](../../../profile/dsh-session-mode/README.md) 的模式定义里正好是这几项）。
- * 方向因此是单向的：装配层读这个服务，这个包不认识装配层。
- *
- * `apply` 落到该 agent 身上的三件事，各走一条与"谁注册了这个工具"无关的路：
- *
- * 1. **装配期投影**（每次装配按已注册的那份）：模型目录与工具说明的 `tool:<工具名>` section 同源过滤；
- * 2. **执行层 guard**：落在 `agent.ctx` 上，调用被拒时给出该模式的文案；
- * 3. **通道开关**：`instructions` 关掉该会话的规则块（工作区指令、技能目录、用法正文）、
- *    `runtimeContext` 抑制该会话的动态快照（沙箱与审批策略那两条）。
- *
- * 为什么不用 `tools.restrict()`：它会改动可见工具集，从而触发 `tools/change`；上游 `tool-subagent` 正是用
- * 该事件做 composition reconcile——两边互相触发会变成装配风暴。这里用投影过滤加执行层 guard：既不碰注册
- * 表、也不发事件。
- *
- * 为什么按 `agent.ctx` 注册而不是先建一棵 preset 子树：会话的 persona / 工具收口本来就是"这个 agent 的
- * 事"，`agent.ctx` 的 scope 已经够了（上游给子 agent 装 persona 用的也是这条路）；一棵子树要连带上游的
- * `agent-presets` 注册表、每 revision 一份 Loader 与 `isolate` realm，模式本身用不上。
- *
- * 模式在空白窗口里可以切换，所以状态是**可替换**的：同一个 agent 再 `apply` 一次就是换一份——旧的
- * disposer 全部收回，再按新的装一遍。
- */
-
-import { Service, type Context } from "@deepseek-ai/cordis";
-import type { Agent } from "@deepseek-ai/dsh-agent";
-import z from "@deepseek-ai/schemastery";
-import type {} from "../assembler/index.ts";
-
-export const name = "context-assembler-scope";
-
-/** 收口要的服务；`sessionToolScope` 由本行自己发布，`tools` 的 guard 挂在每个 agent 的 ctx 上。 */
-export const inject = ["tools", "systemPrompt"];
-
-/** 本行不吃 config：要收成什么样由消费方在 `apply` 时给。 */
-export const Config = z.object({});
-
-/** 一次收口的全部输入：模式定义里本出口用到的那几项。 */
-export interface SessionToolScopeMode {
-  /** 拒绝对话时用的模式名。 */
-  readonly name: string;
-  /** 这个会话能用的工具；其余既不进目录，调用也被拒。 */
-  readonly allowTools: readonly string[];
-  /** 缺省为要；`false` 表示这个会话不要任何 instruction 类注入。 */
-  readonly instructions?: boolean | undefined;
-  /** 缺省为要；`false` 表示这个会话不要动态快照。 */
-  readonly runtimeContext?: boolean | undefined;
-}
-
-declare module "@deepseek-ai/cordis" {
-  interface Context {
-    sessionToolScope: SessionToolScope;
-  }
-}
-
-const OUT_OF_SCOPE = (toolName: string, modeName: string): string =>
-  `${toolName} 不在「${modeName}」的工具范围内，用它不会有结果；按当前模式提供的工具完成任务，或让用户切到别的模式。`;
-
-/** 单个工具的说明 section 名前缀：`tool:<工具名>`（`tools:` 那类是聚合块，不归白名单管）。 */
-const TOOL_SECTION_PREFIX = "tool:";
-
-/** 一个 agent 当前装着的那一份。 */
-interface Applied {
-  readonly mode: SessionToolScopeMode;
-  /** 收回这一份在 `agent.ctx` 上的注册（抑制器与执行层 guard）。 */
-  readonly dispose: () => void;
-}
-
-/** 通道是可选的搭档：没有它就没有 instruction 可关、也没人收窄技能目录，工具目录与执行 guard 照常生效。 */
-function channelOf(ctx: Context):
-  | {
-      setInstructions(agent: Agent, on: boolean): void;
-      restrictTools(agent: Agent, allowed: (tool: string) => boolean): void;
-    }
-  | undefined {
-  try {
-    return ctx.get("contextAssembler");
-  } catch {
-    return undefined;
-  }
-}
-
-/** 按会话收口工具与注入的服务。 */
-export class SessionToolScope extends Service {
-  private readonly applied = new WeakMap<Agent, Applied>();
-
-  constructor(ctx: Context) {
-    super(ctx, "sessionToolScope");
-    // 装配期过滤：这里只认已经 `apply` 过的会话；没登记过的（没装 session-mode 的部署）一律放行。
-    ctx.on("system-prompt/assemble", async (_assembly, context, next) => {
-      const agent = context.agent;
-      const applied = agent === undefined ? undefined : this.applied.get(agent);
-      if (applied === undefined) return next();
-      const allow = new Set(applied.mode.allowTools);
-      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)),
-      };
-    });
-  }
-
-  /**
-   * 把某个会话收口到这份定义上（同一个 agent 再调就是换一份）。
-   * @param agent - 目标会话的 agent。
-   * @param mode - 收口的全部输入。
-   */
-  apply(agent: Agent, mode: SessionToolScopeMode): void {
-    const previous = this.applied.get(agent);
-    if (previous !== undefined) previous.dispose();
-    const allow = new Set(mode.allowTools);
-
-    // 落在 `agent.ctx` 上的那两件用一个 effect 装：抑制器是 scope 层的一次注册；执行层 guard 要等
-    // `tools` 激活才装得上（`inject` 的回调），它挂在那个 inject fiber 下，所以收回时连 fiber 一起收。
-    const dispose = agent.ctx.effect(() => {
-      const stoppers: (() => void)[] = [];
-      if (mode.runtimeContext === false) {
-        // service 在 `agent.ctx` 上是 shadow：抑制落在该 agent 的 scope 层，只覆盖这个会话。
-        stoppers.push(agent.ctx.systemPrompt.suppressRuntimeContext());
-      }
-      // 必须落在 `agent.ctx` 上才是这个会话的作用域。
-      const fiber = agent.ctx.inject(["tools"], (scope) => {
-        scope.tools.guard((exec) =>
-          allow.has(exec.name) ? undefined : OUT_OF_SCOPE(exec.name, mode.name),
-        );
-      });
-      return [...stoppers, () => fiber.dispose()];
-    }, "sessionToolScope: per-session gate");
-
-    // 与"谁注册了这个工具"无关的那两件：通道按 agent 覆盖，不需要收回。
-    const channel = channelOf(this.ctx);
-    channel?.setInstructions(agent, mode.instructions !== false);
-    channel?.restrictTools(agent, (tool) => allow.has(tool));
-
-    this.applied.set(agent, { mode, dispose });
-  }
-}
-
-export function apply(ctx: Context): void {
-  new SessionToolScope(ctx);
-}

package/src/skill-catalog/index.ts

@@ -1,203 +0,0 @@
-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 = ["agents", "skills", "tools", "contextAssembler"];
-
-export const CATALOG_ID = "skill-catalog";
-
-/** 目录行里的描述长度上限（上游默认同值）。 */
-const DESCRIPTION_MAX_LENGTH = 500;
-
-/**
- * skill 目录 + `skill` 工具：目录是规则块（一行名字 + 摘要），正文按需加载。
- *
- * 目录只列模型可调用的 skill；`auto` 的 skill 标 `modelInvocable: false`，所以它不出现在目录里
- * （它的正文已经随提示送达）。工具的渲染用通道的虚拟 skill 形态，不带 `<skill_resources>`。
- *
- * **这一面归通道**（工作区指令那一面相反，是让位给 preset）：官方 preset 自己装了上游 `tool-skill`，那份
- * 注册在 preset 的 scope 层；我们把 `skill` 工具按会话注册进 **agent 自己那一层**——它最靠里，同名注册遮蔽
- * 继承来的那一份（[`core/tools/src/index.ts:1185-1207`](../../../vendor/deepseek-harness/packages/core/tools/src/index.ts)），
- * 于是模型看到的是我们的工具（中文描述 + 按会话修剪的正文）。上游的目录发布判据是"它自己注册的那个工具是
- * 本会话可见的那个"（[`skill/tool-skill/src/index.ts:213-236`](../../../vendor/deepseek-harness/packages/skill/tool-skill/src/index.ts)），
- * 被遮蔽之后它闭嘴，目录由我们发布；`minimal`（`chat`）那种没有上游行的会话里也只有我们这一份。
- */
-export function apply(ctx: Context): void {
-  /**
-   * 本会话上次算出的目录条目：`source` 是同步的、正文是异步的，两者共用这一次计算的结果
-   * （`collect` 里先算正文再取 source）。
-   */
-  const catalogEntries = new WeakMap<Agent, readonly { name: string; description: string }[]>();
-
-  // 同名工具只能有一个所有者：host 平面已经有人注册了 `skill`（装上游 `tool-skill` 的部署）就让给它，
-  // 我们只发布目录。我们的部署里 host 平面那一行是禁用的（preset 才装），所以走的是下面这条。
-  const skillTool = ctx.tools.get("skill") === undefined ? defineSkillTool(ctx) : undefined;
-  if (skillTool === undefined) {
-    ctx.logger.warn(
-      "context-skill-catalog: a `skill` tool is already registered; keeping the existing one and only publishing the catalog",
-    );
-  } else {
-    // 按会话注册：`register` 落到**调用它的那个 ctx** 的 scope 层（agent 自己那一层），随 agent 收回。
-    const install = (agent: Agent): void => {
-      // 本行重装（HMR / 设置面）时上次那份注册还在 agent 自己那一层（它随 agent 而不是随本行收回）：
-      // 同一份定义就不要再注册一次——同一层重复注册会抛（`dsh-scope` 的 `NamedEntries.insert`）。
-      if (ctx.tools.get("skill", agent) === skillTool) return;
-      try {
-        agent.ctx.tools.register(skillTool);
-      } catch (error) {
-        // agent 自己那一层被更具体的注册占了：让开（它自己会发目录），我们这一份注册不上。
-        ctx.logger.warn(`context-skill-catalog: ${String(error)}`);
-      }
-    };
-    ctx.on("agent/created", ({ agent }) => {
-      install(agent);
-    });
-    for (const agent of ctx.agents.list()) install(agent);
-  }
-
-  ctx.contextAssembler.registerRule({
-    id: CATALOG_ID,
-    // 对外身份**用我们自己的 kind**（不是上游那个 `skill-catalog`）：目录的正文与条目都由我们发布，而上游
-    // `tool-skill` 的目录监听器把任何 `kind: 'skill-catalog'` 且条目可读的消息都当成**它自己的**账本
-    // （`catalogMessage` / `catalogHistory`），于是它会删掉我们这一条（首步：`!history.published &&
-    // skills.length === 0` 那条分支）或者补一条"没有可用 skill"的空目录把它顶掉（它有可见目录之后）。
-    // 形态仍是它认得的 `catalog`（`entries` 是客户端列条目的那份清单），只是 kind 归我们——
-    // 它的两个扫法都只看 kind，于是本会话里它彻底闭嘴。
-    source: (agent) => ({
-      kind: "context-assembler",
-      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");
-    },
-  });
-}
-
-/** 一份工具定义，按会话注册进每个 agent 的自己那一层（同一个定义对象，判据里的同一性靠它）。 */
-function defineSkillTool(ctx: Context): ReturnType<typeof defineTool> {
-  return 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,
-      };
-    },
-  });
-}
-
-function clamp(text: string, max: number): string {
-  return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
-}