@morlay/dsh-session-mode 0.0.15 → 0.0.16

package/src/mode-config.ts

@@ -0,0 +1,104 @@
+// 模式配置的唯一模型：与 `{dshHome}/modes/<id>.toml` 同构。**包括 `session` 列**——会话级覆盖不是另一套
+// 逐条目结构，而是同一份 `ModeConfig` 的可覆盖字段子集。TOML 不写 `session`（它属于会话日志）。
+//
+// 两个边界，测试只写在这两处：
+// - `resolveModeConfig(config, session)`：配置 + 会话覆盖 → 生效配置（上下文的过滤与转换就在这一步）；
+// - `diffModeConfig(config, view)`：面板的 ViewModel（也是 `ModeConfig` 的编辑副本）→ 会话覆盖差异。
+
+import type { SessionMode } from "./modes.ts";
+
+// 与 TOML 同构的模式配置：`skills` 在 schema 里可选，这里归一成布尔；`session` 是会话列。
+// 字段全部必填：TOML 读进来也先归一到这个形状。
+export interface ModeConfig {
+  readonly presetsOnly: string[];
+  readonly name: string;
+  readonly description: string;
+  readonly role: SessionMode["role"];
+  readonly persona: { readonly prefix: string; readonly suffix: string };
+  readonly allowTools: string[];
+  readonly denyTools: string[];
+  readonly allowSkills: string[];
+  readonly denySkills: string[];
+  readonly allowPolicies: string[];
+  readonly denyPolicies: string[];
+  readonly instructions: boolean;
+  readonly skills: boolean;
+  readonly dropSections?: string[];
+  readonly runtimeContext: boolean;
+}
+
+// 会话覆盖是**全量**的：一份完整配置，不是字段级 merge。
+export type ModeSession = ModeConfig;
+
+// 面板的 ViewModel 就是一份 `ModeConfig`：编辑它，"应用到会话"产出一份 `ModeSession`。
+export type ModeViewModel = ModeConfig;
+
+// 配置 + 会话覆盖 → 生效配置。数组整体替换（组引用就在数组里，不需要另一套展开语义）。
+export function resolveModeConfig(
+  config: ModeConfig,
+  session: ModeSession | undefined,
+): ModeConfig {
+  return structuredClone(session ?? config);
+}
+
+// 全量比较：ViewModel 与配置相同 → 没有会话覆盖（undefined）；不同 → 整份 ViewModel 作为覆盖。
+export function diffModeConfig(config: ModeConfig, view: ModeConfig): ModeSession | undefined {
+  return JSON.stringify(config) === JSON.stringify(view) ? undefined : structuredClone(view);
+}
+
+// 一份配置在某个会话里的三面：配置本身、会话覆盖、二者叠加的生效配置。
+
+// 把 TOML/行配置读进来的那半归一成完整 `ModeConfig`（`skills` 缺省按工具名单推导由调用方给默认）。
+export function asModeConfig(mode: SessionMode, skills: boolean): ModeConfig {
+  // schema 产物里字段可能可选，这里统一归一成完整配置。
+  return { ...mode, skills } as unknown as ModeConfig;
+}
+
+// 面板草稿：三态按"组引用 / 条目 id"记录。`unset` = 从两边名单里都移除。
+export interface ModeDraft {
+  readonly lists?: Readonly<
+    Record<"tools" | "skills" | "policies", Readonly<Record<string, "allow" | "deny" | "unset">>>
+  >;
+  readonly persona?: { prefix: string; suffix: string } | null;
+  readonly switches?: Readonly<Record<string, boolean | null>>;
+}
+
+// ViewModel 的修改 → 符合预期的 `ModeConfig`：`denyTools: ["mcp:agent-browser"]` + 草稿 unset → `denyTools: []`。
+export function applyDraft(
+  config: ModeConfig,
+  draft: ModeDraft,
+  // 默认基座：`null`（回到默认）时取它的值。省略就是 `config` 自己。
+  defaults?: ModeConfig,
+): ModeConfig {
+  const view: Record<string, unknown> = { ...structuredClone(config) };
+  const lists = [
+    ["tools", "allowTools", "denyTools"],
+    ["skills", "allowSkills", "denySkills"],
+    ["policies", "allowPolicies", "denyPolicies"],
+  ] as const;
+  for (const [kind, allowKey, denyKey] of lists) {
+    const allow = new Set(view[allowKey] as string[]);
+    const deny = new Set(view[denyKey] as string[]);
+    for (const [id, value] of Object.entries(draft.lists?.[kind] ?? {})) {
+      if (value === "deny") deny.add(id);
+      else if (value === "allow") {
+        deny.delete(id);
+        if (allow.size > 0) allow.add(id);
+      } else {
+        // unset = 配置里不写这一项：两边名单都移除。
+        allow.delete(id);
+        deny.delete(id);
+      }
+    }
+    view[allowKey] = [...allow];
+    view[denyKey] = [...deny];
+  }
+  if (draft.persona !== undefined && draft.persona !== null) view["persona"] = draft.persona;
+  for (const [key, value] of Object.entries(draft.switches ?? {})) {
+    // `null` = 回到默认：取默认基座（`config`）的那一项，而不是保留会话覆盖里的旧值。
+    if (value !== null) view[key] = value;
+    else if (defaults !== undefined)
+      view[key] = (defaults as unknown as Record<string, unknown>)[key];
+  }
+  return view as unknown as ModeConfig;
+}

package/src/mode-sources.ts

@@ -32,6 +32,8 @@ export interface ModeSource {
   // 是否要技能目录（官方 `skill-catalog` 的注入）：**可选**，不写就按这个模式自己的工具名单推导（名单里含 `skill`
   // 就要，见 `modes.ts` 的 `derivedSkills`）。`coding` 留空名单 = 要；`chat` 的三件里没有 `skill` = 不要。
   readonly skills?: boolean;
+  // 这个模式下要丢弃的 system prompt section。
+  readonly dropSections?: readonly string[];
   readonly runtimeContext?: boolean;
   // 这个模式的默认模型（省略就跟全局 `agent-default-model`）。
   readonly defaultModel?: ModeModelSource;
@@ -77,8 +79,7 @@ export const MODE_SOURCES: readonly ModeSource[] = [
   {
     id: "coding",
     name: "编码模式",
-    description:
-      "功能完整的编码 Agent：文件、Shell、检索、联网等工具常驻，其余用法说明按需加载。",
+    description: "功能完整的编码 Agent：文件、Shell、检索、联网等工具常驻，其余用法说明按需加载。",
     persona: CODING_PERSONA,
     // 用户可选，也允许作为子代理的 mode（子代理默认继承父 mode，不看角色；这里是"可被指定"的候选集）。
     role: ["main", "subagent"],
@@ -117,8 +118,7 @@ export const MODE_SOURCES: readonly ModeSource[] = [
   {
     id: NOOP_MODE_ID,
     name: "原样模式",
-    description:
-      "与上游一致：不加人格提示词、不收窄工具与技能、policy 规则全开、官方注入面照旧。",
+    description: "与上游一致：不加人格提示词、不收窄工具与技能、policy 规则全开、官方注入面照旧。",
     // 用户可选，也允许作为子代理的 mode：它不做任何过滤，给子代理当候选同样成立。
     role: ["main", "subagent"],
     // 其余字段一律不写：名单留空 = 不设收窄，`instructions` / `runtimeContext` 走 schema 默认 `true`，

package/src/mode-store.ts

@@ -0,0 +1,53 @@
+// 模式配置的持久化：用户自己的模式定义落在 `{dshHome}/modes/<id>.toml`，cordis 上的 `config.modes` 只是
+// **默认模板**。读的时候用户文件覆盖同 id 的模板；写的时候只动用户文件，不碰 profile 的 patch。
+
+import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
+import { parse, stringify } from "smol-toml";
+
+function modesDir(): string {
+  return dshHomePath("modes");
+}
+
+// 用户改过的模式：id → 覆盖模板的那份定义。坏文件按"没有"处理（模板继续生效）。
+export async function loadModeOverrides(): Promise<Record<string, Record<string, unknown>>> {
+  const dir = modesDir();
+  const entries = await readdir(dir).catch(() => [] as string[]);
+  const overrides: Record<string, Record<string, unknown>> = {};
+  for (const name of entries) {
+    if (!name.endsWith(".toml")) continue;
+    const text = await readFile(join(dir, name), "utf8").catch(() => undefined);
+    if (text === undefined) continue;
+    try {
+      overrides[name.slice(0, -".toml".length)] = parse(text) as Record<string, unknown>;
+    } catch {
+      // 坏文件不阻断启动：同 id 继续用模板。
+    }
+  }
+  return overrides;
+}
+
+// `smol-toml` 只出单行字符串：把含换行的值改写成 TOML 多行字符串，persona 这类才读得动。
+function prettyToml(text: string): string {
+  return text
+    .split("\n")
+    .map((line) => {
+      const match = /^(\s*[A-Za-z0-9_.-]+)\s*=\s*"((?:[^"\\]|\\.)*)"$/u.exec(line);
+      if (match === null) return line;
+      const [, key, raw] = match;
+      if (key === undefined || raw === undefined || !raw.includes("\\n")) return line;
+      const value = raw.replace(/\\n/gu, "\n").replace(/\\"/gu, '"').replace(/"""/gu, '\\"""');
+      return `${key} = """\n${value}"""`;
+    })
+    .join("\n");
+}
+
+export async function writeMode(id: string, value: Record<string, unknown>): Promise<void> {
+  await mkdir(modesDir(), { recursive: true });
+  await writeFile(join(modesDir(), `${id}.toml`), prettyToml(stringify(value)), "utf8");
+}
+
+export async function removeMode(id: string): Promise<void> {
+  await rm(join(modesDir(), `${id}.toml`), { force: true });
+}

package/src/modes.ts

@@ -37,7 +37,7 @@ export interface SessionMode {
   // （persona / 工具名单 / policy 名单 / 三个开关 / `defaultModel`）在任意 preset 上都照常生效。
   // 有值时切到这个模式会让会话的 preset 落进名单：当前那份已经在名单里就原样不动，否则换成名单里的**第一个**
   // （`modes.ts` 只声明"允许哪些"，落在哪个由 `SessionModes.select` 决定）。多个模式可以共享同一份名单。
-  readonly presetsOnly: string[];
+  readonly presetsOnly?: readonly string[];
   // 模式的展示名（选择面归官方 roster；这里留着做事实文案）。
   readonly name: string;
   // 一句话说明这个模式干什么；空串表示没写。
@@ -75,10 +75,13 @@ export interface SessionMode {
   // 是否要动态快照（文件沙箱策略、审批策略那两条 snapshot section，以及 `standard` 那类 preset 声明的时钟
   // `time-context` 注入）。缺省要；`false` 表示这个模式不要它们——对话模式没有文件与 shell 工具，"能改工作区
   // 哪些文件、要不要走审批"对它全是噪音，它也不谈时间。
+  // 这个模式下要丢弃的 system prompt section（精确名或前缀）。
+  readonly dropSections?: string[];
   readonly runtimeContext: boolean;
   // 这个模式的默认模型；省略就跟全局 `agent-default-model`。**可选**：没配的模式在页面上不出现在这一行
   // （`defaultModel` 是它所在模式的一个可加字段）。
   readonly defaultModel?: SessionModeModel;
+
   // 退役字段：单个 `preset` 已换成白名单 `presetsOnly`。这里留着只为**报错**（见 `configProblem`），页面上不出现。
   readonly preset?: string;
 }
@@ -90,6 +93,12 @@ export function derivedSkills(mode: Pick<SessionMode, "allowTools" | "denyTools"
   return allowed && !mode.denyTools.includes("skill");
 }
 
+// 一份模式定义 → 归一化后的形状（每个字段都有值）：内置默认与 `{dshHome}/modes/*.toml` 覆盖都走这条，
+// 否则缺字段的 mode 会在收口里读到 `undefined`（`allow.length` 之类）。
+export function normalizeMode(value: unknown): SessionMode {
+  return modeSchema(value as never) as SessionMode;
+}
+
 // 每个字段都带 default：schema 的产物因此没有 `undefined` 键（`exactOptionalPropertyTypes` 下"缺省的键"
 // 会与可选属性对不上）。`description()` 的类型签名只声明 `string`，这里做一次类型放行。
 const localized = (text: { zh: string; en: string }): string => text as unknown as string;
@@ -134,7 +143,7 @@ const modelSchema = z.object({
 
 // 本包 config 的**源码形状**：装配层与设置页写的那个形状。
 export interface Config {
-  // 新会话（还没选过模式的会话）用哪个模式。必须是 `modes` 里的一个 id。
+  // 新会话（还没选过模式的会话）用哪个模式。必须是内置或目录里的一个 id。
   readonly default: string;
   // 模式清单：id → 定义（含各自的 `defaultModel`）。顺序即选择器里的顺序（`Object.entries` 的插入序）。
   readonly modes: Record<string, SessionMode>;
@@ -147,8 +156,9 @@ export interface Config {
 //
 // `default` 与 `modes` 都是 volatile：默认模式与整份模式清单（含各自的 `defaultModel`）都在行配置页上。
 export interface ResolvedConfig {
+  // 装配期注入（测试/高级用法）：用户配置的正确路径是 `{dshHome}/modes/*.toml`。
+  readonly modes?: Record<string, SessionMode>;
   readonly default: Volatile<string>;
-  readonly modes: Volatile<Record<string, SessionMode>>;
   // 退役的顶层字段：解析后仍在这儿（普通值，不 volatile），装配期据此发现"还配着值"并报错。
   readonly models: SessionModeModels;
 }
@@ -156,17 +166,6 @@ export interface ResolvedConfig {
 const modeSchema: z<SessionMode> = z.object({
   // 退役字段：这里留着只为**报错**（见 `configProblem`），页面上不出现（`hidden()`）。不给默认：没配就没这个键。
   preset: z.string().hidden(),
-  presetsOnly: z
-    .array(z.string())
-    // 候选是部署里注册的 agent preset（具名源 `agent-presets`）：字段只说"这是选几个"，不关心它从哪来。
-    .role("select", { source: "agent-presets" })
-    .default([])
-    .description(
-      localized({
-        zh: "这个模式只允许挂哪些 agent preset（它们的 id，官方或本部署自建的）：行清单由挂着的那份提供，几个模式可以共享同一份名单。留空表示**允许全部**——哪份 preset 都行，选这个模式也不动会话当前挂着的那份；有值时当前的已经在名单里就不动，否则换成名单里的第一个。模式自己的提示词、工具收口与开关照常生效。",
-        en: "Which agent presets this mode may ride on (their ids, shipped or deployment-owned): that preset supplies the row list, and several modes may share one list. Empty means **every preset is allowed** — selecting the mode then leaves the session's current preset alone; when set, the current one stays if it is listed, otherwise the session switches to the first entry. The mode's persona, tool narrowing, and switches apply either way.",
-      }),
-    ),
   name: z
     .string()
     .required()
@@ -273,6 +272,15 @@ const modeSchema: z<SessionMode> = z.object({
       en: "Whether the skill catalog applies (the official `skill-catalog` injection). The default derives it from this mode's own tool lists: it applies when `(empty allowTools ? every tool : allowTools) − denyTools` contains `skill`; `false` drops the official `skill-catalog` injection (`skill` tool visibility still belongs to `allowTools`).",
     }),
   ),
+  dropSections: z
+    .array(z.string())
+    .default([])
+    .description(
+      localized({
+        zh: "这个模式下要丢弃的 system prompt section：写 section 名（精确匹配）或以 `*` 结尾的前缀（如 `mcp-*`）。",
+        en: "System prompt sections to drop for this mode: exact names, or prefixes ending in `*`.",
+      }),
+    ),
   runtimeContext: z
     .boolean()
     .default(true)
@@ -297,6 +305,7 @@ const modeSchema: z<SessionMode> = z.object({
 });
 
 export const Config: z<Config, ResolvedConfig> = z.object({
+  modes: z.dict(modeSchema).default({}),
   default: z
     .string()
     .required()
@@ -307,20 +316,6 @@ export const Config: z<Config, ResolvedConfig> = z.object({
       }),
     )
     .volatile(),
-  modes: z
-    .dict(modeSchema)
-    .required()
-    .description(
-      localized({
-        zh:
-          "模式清单：id → 定义（persona / 工具名单 / 生效的 policy 规则 / 角色）。改它对**已运行会话**不自动生效" +
-          "——重挂后新建的会话、或重新应用模式的会话才用新定义。",
-        en:
-          "Mode roster: id to definition (persona, tool lists, effective policy rules, role). Edits do not follow " +
-          "into already-running sessions; sessions created after the row is remounted use the new definition.",
-      }),
-    )
-    .volatile(),
   // 退役字段：默认模型住在每个模式自己的 `defaultModel` 里。这里留着是为了**报错**（见 `configProblem`），
   // 页面上不出现（`hidden()`）。
   models: z.dict(modelSchema).default({}).hidden(),

package/src/per-agent.ts

@@ -0,0 +1,53 @@
+// 本行替某个 agent 装的那一组注册的**收回账**。
+//
+// 为什么需要它：`agent.ctx.tools.register()` / `agent.ctx.systemPrompt.section()` / `agent.ctx.on()` 把 effect
+// 挂在 **agent 的 scope fiber** 上（作用域必须落在那个 agent 的 layer 里，这是这些 API 的契约），所以这些注册
+// **不随本行卸载**。于是「上一次装的那一份」如果只记在当前实例的 WeakMap 里，一旦本行被重挂（设置保存会让
+// Loader 重新配置这一行），新实例就没有上一份可收，再装一次就抛：
+// `tool "describe_tool" is already registered in this scope`、
+// `prompt section "deployment:persona-prefix" is already registered in this scope`。
+//
+// 所以收回账挂两处，任何一处先到都收干净：
+// - **本行**（`ctx`）：行卸载/重挂时把这份注册一起收；
+// - **agent**（`agent.ctx`）：本行通常比 agent 活得久，agent 卸载时把上面那笔行账一起撤掉，别攒着死 agent 的闭包。
+//
+// `release()` 是**同步**且幂等的：`apply` 重入时「旧的收完再装新的」靠的就是这一点（`inject` fiber 的
+// `dispose()` 是异步的——它要等子 fiber 卸载——所以它只能算链上的一笔，不能当唯一收回路径）。
+
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+
+export interface PerAgentAccount {
+  // 记一笔收回动作。账已经收过时就地执行，晚到的注册因此不会漏。
+  add(stop: () => void): void;
+  // 收回这一份：同步、幂等。
+  release(): void;
+}
+
+export function perAgentAccount(ctx: Context, agent: Agent): PerAgentAccount {
+  const stoppers: (() => void)[] = [];
+  let released = false;
+  let rowAccount: () => void = () => {};
+  let agentAccount: () => void = () => {};
+
+  const release = (): void => {
+    if (released) return;
+    released = true;
+    for (const stop of stoppers.splice(0).reverse()) stop();
+    // 两笔账本身也要撤：行账在行卸载时由本行跑，agent 账在 agent 卸载时由 agent 跑；这里先撤一次，
+    // 免得每换一次模式就在 agent 的 fiber 上攒一条不再用到的清理项。
+    agentAccount();
+    rowAccount();
+  };
+
+  rowAccount = ctx.effect(() => () => release(), "session-mode: per-agent releases");
+  agentAccount = agent.ctx.effect(() => () => release(), "session-mode: per-agent releases");
+
+  return {
+    add: (stop) => {
+      if (released) stop();
+      else stoppers.push(stop);
+    },
+    release,
+  };
+}

package/src/ptc-describe.ts

@@ -0,0 +1,97 @@
+// `describe_tool`：PTC 程序里现取某组工具的 d.ts（不把全量签名塞进 system）。
+//
+// 上游 PTC 执行器只允许"程序内（nested）调用任意已注册工具"，所以这里注册成普通工具即可：
+// 程序里 `await describe_tool({ group: "fs" })` 拿到 `declare global { interface ToolsSdk { … } }`
+// （成员就是 `tools` 上的属性；名字带引号的用 `tools["名字"](args)`）。
+
+import { jsonSchemaToTs } from "@deepseek-ai/dsh-tool-executor-ptc";
+import { SHORT_TOOL_DESCRIPTIONS } from "@morlay/dsh-tool-guidance/groups";
+import { toolGroupOf } from "./shared.ts";
+import { renderTools, type PtcToolSchema } from "./ptc-sdk.ts";
+
+/** 一条工具的静态描述（描述文本 + 宽松的 args/output 类型）。 */
+export interface DescribeEntry {
+  readonly name: string;
+  readonly description: string;
+  /** 工具的参数 JSON Schema。 */
+  readonly parametersSchema?: unknown;
+  /** 工具的输出 JSON Schema。 */
+  readonly outputSchema?: unknown;
+}
+
+// 按工具组分组；组名与面板上的分组一致（`mcp:agent-browser` 等）。
+export function groupEntries(
+  entries: readonly DescribeEntry[],
+): Map<string, readonly PtcToolSchema[]> {
+  const groups = new Map<string, PtcToolSchema[]>();
+  for (const entry of entries) {
+    const group = toolGroupOf(entry.name);
+    const list = groups.get(group);
+    const schema: PtcToolSchema = {
+      name: entry.name,
+      // 中文短描述统一由 `dsh-tool-guidance` 维护；没有登记就退回工具自己的 description。
+      description: SHORT_TOOL_DESCRIPTIONS[entry.name] ?? entry.description,
+      // 参数与返回都按工具自己的 schema 转成 TS。
+      args: schemaText(entry.parametersSchema),
+      output: schemaText(entry.outputSchema),
+    };
+    if (list === undefined) groups.set(group, [schema]);
+    else list.push(schema);
+  }
+  return groups;
+}
+
+// 输出 schema → TS；转不了就是 `unknown`（`jsonSchemaToTs` 自己兜底）。
+function schemaText(schema: unknown): string {
+  return schema === undefined ? "JsonValue" : jsonSchemaToTs(schema);
+}
+
+// 分组的简要说明（一句话，不展开成员）。
+const GROUP_SUMMARY: Readonly<Record<string, string>> = {
+  fs: "文件读写",
+  shell: "执行命令",
+  "web-access": "联网检索与抓取",
+  ask: "向用户提问",
+  plan: "计划与待办",
+  swarm: "子代理与消息",
+  skill: "加载技能说明",
+  code: "代码执行（PTC）",
+  mcp: "MCP 资源",
+  onDemand: "按需工具",
+  other: "其它",
+};
+
+// 常用组的说明（中文）：随 describe 一起返回，不占 system。
+const GROUP_SECTION: Readonly<Record<string, string>> = {
+  collab:
+    "## 协作\n\n可以派发子代理、给队友发消息、等待队友；所有人共享同一个工作目录与文件系统，写操作要划分互不重叠的范围，必要时用共享任务记录范围与依赖。",
+  "mcp:resources":
+    "## MCP 资源\n\n按 URI 读取 MCP server 暴露的只读资源（文档、日志、数据）；先 list 再 read。当前 server 都是 tools-only，通常没有可读资源。",
+  fs: "## 文件\n\n读、写、改文件与检索；改文件前先读当前内容，避免覆盖别人的改动。",
+  shell: "## Shell\n\n执行命令；不要用它绕过文件工具做批量改写。",
+  "web-access": "## 联网\n\n搜索与抓取网页。",
+  skill: "## 技能\n\n按需加载技能说明，再照着做。",
+};
+
+function sectionOfGroup(group: string): string {
+  return GROUP_SECTION[group] ?? "";
+}
+
+function summaryOf(group: string): string {
+  if (group.startsWith("mcp:")) return `MCP · ${group.slice("mcp:".length)}`;
+  return GROUP_SUMMARY[group] ?? "其它";
+}
+
+// 工具的执行体：不带 group 给「分组 + 一句话说明」，带 group 给该组的 d.ts 片段。
+export function describeTools(entries: readonly DescribeEntry[], group?: string): string {
+  const groups = groupEntries(entries);
+  if (group === undefined) {
+    return [...groups.keys()]
+      .sort()
+      .map((name) => `${name} — ${summaryOf(name)}`)
+      .join("\n");
+  }
+  const declaration = renderTools(groups.get(group) ?? []);
+  const section = sectionOfGroup(group);
+  return section.length === 0 ? declaration : `${section}\n\n${declaration}`;
+}

package/src/ptc-sdk.ts

@@ -0,0 +1,90 @@
+// PTC 的 SDK 说明：**不**把全部工具铺成一个大 `ToolArgsMap`（那样工具一变、system 前缀就变）。
+//
+// - system 里只放稳定骨架：`interface ToolsSdk`（含 `describe_tool`）+ `declare const tools: ToolsSdk`；
+// - 具体分组通过 `describe_tool({ group })` 现取现用（同一条 interface 的成员片段，多次 describe 合并）；
+// - 工具增删只影响 describe 的结果，不改 system。
+//
+// 成员形态与键的判据归 `@morlay/dsh-tool-guidance/groups`：MCP 的工具名带 `-`，函数声明表达不了。
+import {
+  TOOLS_SDK_INTERFACE,
+  renderToolKey,
+  renderToolsDeclaration,
+} from "@morlay/dsh-tool-guidance/groups";
+
+// 一个工具在 SDK 文本里的最小信息（与上游 `ToolSdkSchema` 同形，这里只取要用的字段）。
+export interface PtcToolSchema {
+  readonly name: string;
+  // 工具的一行说明（`dsh-tool-guidance` 维护的中文短描述）。
+  readonly description: string;
+  // 参数的 TypeScript 类型文本（已由调用方从 JSON Schema 转换好）。
+  readonly args: string;
+  // 输出的 TypeScript 类型文本。
+  readonly output: string;
+  // 该工具在 harness 里的说明 section（`tool:<name>`）：随 describe 一起返回，不占 system。
+  readonly section?: string;
+}
+
+// 稳定的 system 骨架：所有具体工具都通过 describe 取，字节不随工具集变化。
+// group 清单由当前可见工具的组现算，模型才知道有哪些组可取。
+export function renderSkeleton(groups: readonly string[], members: readonly string[] = []): string {
+  const list =
+    groups.length === 0 ? "（当前没有可用的组）" : groups.map((g) => JSON.stringify(g)).join(" | ");
+  return [
+    '在 `run_code` 写的程序里调用工具：`await tools.name(args)`；名字带引号的成员用索引访问（`tools["名字"](args)`）。**常驻组**的签名已列在下面；其余组用 `describe_tool({ group })` 现取（不带 `group` 返回分组清单）：',
+    "",
+    "```ts",
+    "declare global {",
+    `  interface ${TOOLS_SDK_INTERFACE} {`,
+    ...members,
+    `    describe_tool(args: { group?: ${list} }): Promise<{ text?: string }>`,
+    "  }",
+    `  const tools: ${TOOLS_SDK_INTERFACE}`,
+    "}",
+    "```",
+  ].join("\n");
+}
+
+export const PTC_SDK_SKELETON = renderSkeleton([]);
+
+// 一段工具声明：参数与返回都内联成 TS 类型（各自由 JSON Schema 转换而来）。
+export function renderTools(schemas: readonly PtcToolSchema[]): string {
+  if (schemas.length === 0) return "";
+  const sorted = [...schemas].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  const declaration = renderToolsDeclaration(
+    sorted.map((schema) => ({ name: schema.name, args: schema.args, output: schema.output })),
+  );
+  // 带引号的键只在有非常规名字时出现：多出来的那句提示也跟着出现，模型不用自己猜怎么调。
+  const hint = sorted.some((schema) => renderToolKey(schema.name) !== schema.name)
+    ? '名字带引号的成员用索引访问：`tools["名字"](args)`。\n\n'
+    : "";
+  // section 与工具组一一对应：先给说明，再给 `ts` 代码块里的 d.ts。
+  const sections = schemas
+    .map((schema) => schema.section?.trim() ?? "")
+    .filter((text) => text.length > 0)
+    .join("\n\n");
+  const lead = sections.length === 0 ? "" : `${sections}\n\n`;
+  return `${lead}${hint}${["```ts", declaration, "```"].join("\n")}`;
+}
+
+// `describe_tool()` 的结果：不带参数返回分组清单，带参数返回该组的声明片段。
+export function renderDescribe(
+  groups: ReadonlyMap<string, readonly PtcToolSchema[]>,
+  group?: string,
+): string {
+  if (group === undefined) {
+    return [...groups.keys()].sort().join("\n");
+  }
+  const schemas = groups.get(group);
+  if (schemas === undefined) return "";
+  return renderTools(schemas);
+}
+
+// PTC 装配下把上游那份全量 `tools:sdk` 换成稳定骨架；别的 section 原样保留。
+export function replaceToolsSdk<T extends { readonly name: string; readonly text: string }>(
+  sections: readonly T[],
+  skeleton: string,
+): readonly T[] {
+  return sections.map((section) =>
+    section.name === "tools:sdk" ? { ...section, text: skeleton } : section,
+  );
+}

package/src/rows.ts

@@ -1,7 +1,7 @@
 // 本包作为能力包发布的**装配数据**：`session-mode` 行的 config（各模式的会话级扩展）由这里渲染，
 // 装配入口在 `packages/bundles/session-mode-profile`（它同时装注入通道、工具说明与 subagent 那几行）。
 
-import { DEFAULT_MODE, MODE_SOURCES, type ModeSource } from "./mode-sources.ts";
+import { DEFAULT_MODE, type ModeSource } from "./mode-sources.ts";
 
 // 一行装配条目：与 `cordis.patch.yml` 的顶层结构同形。
 export interface PatchRow {
@@ -21,8 +21,7 @@ function list<T>(values: readonly T[] | undefined): readonly T[] | undefined {
 }
 
 // 一个模式的源定义 → 行 config（schema 的输入形状：可省的字段就省）。
-function modeConfig(source: ModeSource): Record<string, unknown> {
-  const presetsOnly = list(source.presetsOnly);
+export function modeConfig(source: ModeSource): Record<string, unknown> {
   const allowTools = list(source.allowTools);
   const denyTools = list(source.denyTools);
   const allowSkills = list(source.allowSkills);
@@ -30,8 +29,6 @@ function modeConfig(source: ModeSource): Record<string, unknown> {
   const allowPolicies = list(source.allowPolicies);
   const denyPolicies = list(source.denyPolicies);
   return {
-    // `presetsOnly` 是可选的：不写（或写成空数组）就是这个键不进 config，schema 默认空数组（= 不限制）。
-    ...(presetsOnly === undefined ? {} : { presetsOnly }),
     name: source.name,
     description: source.description,
     ...(source.role === undefined ? {} : { role: [...source.role] }),
@@ -49,6 +46,7 @@ function modeConfig(source: ModeSource): Record<string, unknown> {
     ...(source.instructions === undefined ? {} : { instructions: source.instructions }),
     // `skills` 不写就是不进 config：缺省由这份定义自己的工具名单推导（写成 `false` 才落进 config）。
     ...(source.skills === undefined ? {} : { skills: source.skills }),
+    ...(source.dropSections === undefined ? {} : { dropSections: [...source.dropSections] }),
     ...(source.runtimeContext === undefined ? {} : { runtimeContext: source.runtimeContext }),
     ...(source.defaultModel === undefined ? {} : { defaultModel: { ...source.defaultModel } }),
   };
@@ -62,11 +60,9 @@ export function sessionModeRows(): readonly PatchRow[] {
         {
           id: "session-mode",
           name: "@morlay/dsh-session-mode",
+          // 模式定义不再走 cordis 配置：内置默认（coding/chat/noop）+ `{dshHome}/modes/*.toml`。
           config: {
             default: DEFAULT_MODE,
-            modes: Object.fromEntries(
-              MODE_SOURCES.map((source) => [source.id, modeConfig(source)]),
-            ),
           },
         },
       ],