@qjp88995/agent-runtime 0.0.0-stage → 0.1.0

package/src/subagent/subagent-registry.ts

@@ -0,0 +1,283 @@
+import type { ToolRegistry } from '../tools/tool-registry.js';
+import { DESC_LIMIT, type SubagentIndexEntry } from './roster-block.js';
+
+/**
+ * 一个内置子 Agent 的登记信息。搬自 agent-base `BuiltinSubagentMeta`，只留与运行时机制
+ * 有关的字段；模型从哪来（档位、顶替能力的模型、媒体服务商）是宿主的配置语义，宿主
+ * 扩展这个接口自己加（`SubagentRegistry<MyMeta>`），在 `SpawnPolicy` 与 tick 设置里读。
+ *
+ * **optional 字段留空 = 由父决定**：通用子 Agent 正是靠全部留空，把工具 / 步数交还给
+ * 派生它的那个父（宿主合成子定义时 `meta.tools ?? parent.enabledTools`）。
+ */
+export interface SubagentMeta {
+  /** 模型看到、派生时填的名字。全局唯一。 */
+  name: string;
+  /**
+   * 界面上的默认叫法（「识图员」）：派它那一行、过程弹窗、回执标题都写它。**只管显示，
+   * 模型看到的永远是 `name`**。1..`labelMax` 个码点，注册期校验。
+   */
+  label: string;
+  /** 花名册那一行。超过 `DESC_LIMIT` 个码点注册期拒绝（花名册会截掉，模型看不见）。 */
+  description: string;
+  /** 子会话的人格提示词。 */
+  prompt: string;
+  /** 工具白名单；不给 = 用父的。 */
+  tools?: readonly string[];
+  /** 步数上限；不给 = 用父的。 */
+  maxSteps?: number;
+  /** **叶子**：不给 `Delegate`、花名册清空（它只做一件事，再分包只会绕回来）。 */
+  leaf?: boolean;
+  /**
+   * **功能型**：做一件具体的事、自带一套工具；谁派都按它自己的定义跑，且**必须是叶子**
+   * （隐含 `leaf`）。标不标是一次显式决定，别因为收窄了 `tools` 就顺手标上。
+   */
+  functional?: true;
+  /**
+   * **要权限点才派得出**：本轮发起人有这个点，**且**父允许派这类子 Agent
+   * （`SubagentAccess.allowPermissioned`）时才进花名册、才派得出。填它自带工具要的那个点，
+   * 花名册与工具门禁认同一件事。**这不是工具的门**：它用到的工具自己仍要现查权限。
+   */
+  permission?: string;
+  /**
+   * **点名挂载**：默认不进任何花名册、谁都派不出，只有点名要它的父
+   * （`SubagentAccess.optIn`）才列、才派得出。与 `permission` 不能同标（注册期拒绝）。
+   */
+  optIn?: true;
+  /**
+   * 系统类工具（`ToolRegistry` 里 `alwaysOnCategories` 那几组）的白名单。不给 = 不限。
+   * `tools` 管不到恒上桌的工具，要让它只做一件事就得在这里点名；名单外的由
+   * `excludedSystemTools` 算出、宿主放进本轮摘除清单。
+   */
+  systemTools?: readonly string[];
+  /**
+   * 改名前用过的名字。旧子会话钉着旧名（`SessionRecord.subagentName`），追问它时每个 tick
+   * 都按它查定义——查不到就再也续不上。`get` 认它，花名册只出现名。
+   */
+  formerNames?: readonly string[];
+}
+
+/** 注册时可附的运行期问答。 */
+export interface SubagentProvider {
+  /**
+   * 此刻能不能用（服务端没配取数账号时取数员不可用）。不可用时 `get` / `list` 都当它
+   * 不存在。**每次调用现问**，不在注册时快照。
+   */
+  isAvailable?(): boolean;
+}
+
+/** 花名册 / 派生对「要权限点」与「点名挂载」的判据输入。缺省即 fail-closed。 */
+export interface SubagentAccess {
+  /** 本轮发起人此刻的权限点（`Initiator.permissions`；没有发起人 = 空）。 */
+  permissions: ReadonlySet<string>;
+  /** 父允许派要权限点的子 Agent（agent-base：系统管理分身）。缺省 false。 */
+  allowPermissioned?: boolean;
+  /** 这个父点名要的「点名挂载」子 Agent。缺省空。 */
+  optIn?: readonly string[];
+}
+
+export interface SubagentRegistryOptions<M extends SubagentMeta> {
+  /** `label` 的码点上限，缺省 20。 */
+  labelMax?: number;
+  /** 宿主字段的注册期校验（抛错即拒绝）。 */
+  validate?(meta: M): void;
+  /** 宿主字段隐含的叶子（agent-base：按能力顶替的子 Agent）。 */
+  impliesLeaf?(meta: M): boolean;
+}
+
+interface Entry<M> {
+  meta: M;
+  provider?: SubagentProvider;
+}
+
+/**
+ * 内置子 Agent 注册表：宿主显式 `register`（以前靠 Nest 装饰器 + DiscoveryService 扫）。
+ * 名字重复、旧名冲突、说明过长、两个互斥标记同标都在注册期抛。
+ *
+ * 花名册顺序 = 注册顺序。
+ */
+export class SubagentRegistry<M extends SubagentMeta = SubagentMeta> {
+  private readonly byName = new Map<string, Entry<M>>();
+  /** 旧名 → 现名。 */
+  private readonly aliases = new Map<string, string>();
+  private readonly labelMax: number;
+
+  constructor(private readonly options: SubagentRegistryOptions<M> = {}) {
+    this.labelMax = options.labelMax ?? 20;
+  }
+
+  register(meta: M, provider?: SubagentProvider): void {
+    const { name } = meta;
+    if (this.byName.has(name) || this.aliases.has(name)) {
+      throw new Error(`duplicate subagent name '${name}'`);
+    }
+    // 花名册每行只显示前 DESC_LIMIT 个码点。说明是我们写的，写长了就是一段没人看得见
+    // 的交代——逼着把「何时派、交回什么」写进前 60 字。
+    if (Array.from(meta.description.trim()).length > DESC_LIMIT) {
+      throw new Error(
+        `subagent '${name}' description exceeds ${DESC_LIMIT} code points (the roster cuts the rest)`
+      );
+    }
+    const labelLength = Array.from(meta.label.trim()).length;
+    if (labelLength === 0 || labelLength > this.labelMax) {
+      throw new Error(
+        `subagent '${name}' label must be 1..${this.labelMax} code points`
+      );
+    }
+    if (meta.permission && meta.optIn) {
+      throw new Error(`subagent '${name}' declares both permission and optIn`);
+    }
+    for (const former of meta.formerNames ?? []) {
+      if (former === name || this.byName.has(former)) {
+        throw new Error(
+          `subagent former name '${former}' is also a current name`
+        );
+      }
+      if (this.aliases.has(former)) {
+        throw new Error(`subagent former name '${former}' is claimed twice`);
+      }
+    }
+    this.options.validate?.(meta);
+    for (const former of meta.formerNames ?? []) {
+      this.aliases.set(former, name);
+    }
+    this.byName.set(name, provider ? { meta, provider } : { meta });
+  }
+
+  /** 现名（认旧名）；没登记过返回 null。不看可用性。 */
+  currentName(name: string): string | null {
+    if (this.byName.has(name)) return name;
+    return this.aliases.get(name) ?? null;
+  }
+
+  /** 这个名字（含旧名）的定义；没有或此刻不可用返回 null。 */
+  get(name: string): M | null {
+    const current = this.currentName(name);
+    if (current === null) return null;
+    const entry = this.byName.get(current);
+    return entry && this.available(entry) ? entry.meta : null;
+  }
+
+  /** 此刻可用的全部定义（注册顺序）。 */
+  list(): M[] {
+    return [...this.byName.values()]
+      .filter(e => this.available(e))
+      .map(e => e.meta);
+  }
+
+  /** 注册过的全部定义（含此刻不可用的），带可用性。后台页用。 */
+  listAll(): { meta: M; available: boolean }[] {
+    return [...this.byName.values()].map(e => ({
+      meta: e.meta,
+      available: this.available(e),
+    }));
+  }
+
+  /**
+   * 注册过的全部现名，**不看可用性**。给「名字不许与内置子 Agent 撞」这类静态判断用：
+   * 按 `list()` 判的话，取数员不可用时别人就能占走它的名字，可用之后两者同名。
+   */
+  allNames(): string[] {
+    return [...this.byName.keys()];
+  }
+
+  /** 名字 → 界面默认叫法，**含旧名**；不看可用性（历史里派过的照样要叫得出来）。 */
+  defaultLabels(): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (const { meta } of this.byName.values()) out[meta.name] = meta.label;
+    for (const [former, current] of this.aliases) {
+      const entry = this.byName.get(current);
+      if (entry) out[former] = entry.meta.label;
+    }
+    return out;
+  }
+
+  /**
+   * 这个名字是不是叶子（不给 `Delegate`、花名册清空）：`leaf` / `functional` /
+   * 宿主的 `impliesLeaf`。没登记过的名字（宿主自己的子 Agent）返回 false。
+   */
+  isLeaf(name: string): boolean {
+    const meta = this.get(name);
+    if (!meta) return false;
+    return (
+      meta.leaf === true ||
+      meta.functional === true ||
+      (this.options.impliesLeaf?.(meta) ?? false)
+    );
+  }
+
+  /** 这个名字要的权限点；不要或没登记过返回 null。 */
+  requiredPermission(name: string): string | null {
+    return this.get(name)?.permission ?? null;
+  }
+
+  /**
+   * 判据输入下这个定义派不派得出（花名册与派生同一句）：要权限点的要发起人有且父允许；
+   * 点名挂载的要父点了名。
+   */
+  permits(meta: M, access: SubagentAccess): boolean {
+    if (
+      meta.permission &&
+      !(access.allowPermissioned && access.permissions.has(meta.permission))
+    ) {
+      return false;
+    }
+    if (meta.optIn && !(access.optIn ?? []).includes(meta.name)) return false;
+    return true;
+  }
+
+  /**
+   * 花名册：此刻可用、对这份判据输入派得出的定义。`filter` 是宿主的附加条件
+   * （agent-base：顶替型只在当前模型缺那项能力且父配了顶替模型时列）——**不广告一个
+   * 派不出来的东西**，派生那一侧（`SpawnPolicy.checkSpawn`）要用同一个判据。
+   */
+  roster(
+    access: SubagentAccess,
+    filter?: (meta: M) => boolean
+  ): SubagentIndexEntry[] {
+    return this.list()
+      .filter(m => this.permits(m, access) && (filter?.(m) ?? true))
+      .map(m => ({ name: m.name, description: m.description }));
+  }
+
+  /**
+   * 这个子 Agent 本轮要摘掉的恒上桌工具：声明了 `systemTools` 时，`alwaysOn` 那几组里
+   * 名单外的全部。没声明返回空数组（与父一样）。
+   */
+  excludedSystemTools(
+    name: string,
+    tools: ToolRegistry,
+    alwaysOnCategories: readonly string[] = ['system']
+  ): string[] {
+    const allow = this.get(name)?.systemTools;
+    if (!allow) return [];
+    return tools
+      .listMeta()
+      .filter(
+        m => alwaysOnCategories.includes(m.category) && !allow.includes(m.name)
+      )
+      .map(m => m.name);
+  }
+
+  private available(entry: Entry<M>): boolean {
+    return entry.provider?.isAvailable?.() ?? true;
+  }
+}
+
+/**
+ * 通用子 Agent 的固定人格提示词。**短得几乎没有内容，这是对的**：处境说明（看不到
+ * 调用方历史、产出原样回投、卡住可以交回去问）归平台，由 `buildSubagentSituationBlock`
+ * 对每个子会话注入；剩下这一句才是「通用款」独有的——它没有领域设定。
+ */
+export const GENERAL_PURPOSE_PROMPT =
+  '你没有特定的领域设定，也没有预设的工作套路。按任务描述本身的要求来做：它要什么就产出什么，需要什么手段就用什么手段。';
+
+/**
+ * 内置「通用子 Agent」。**除人格外一个字段都不设，是它的全部要点**：工具、步数（以及
+ * 宿主的档位、推理等级）统统由派生它的那个父决定。宿主要用就 `registry.register(GENERAL_PURPOSE_SUBAGENT)`。
+ */
+export const GENERAL_PURPOSE_SUBAGENT: SubagentMeta = {
+  name: 'general-purpose',
+  label: '通用 Agent',
+  description: '通用子 Agent：无特定领域设定，适合把一段自包含的任务整个交出去',
+  prompt: GENERAL_PURPOSE_PROMPT,
+};