@webskill/sdk 0.4.0 → 0.6.0

package/dist/index-BuTpBMzr.d.ts

@@ -0,0 +1,474 @@
+import { a as InteractionOrigin, b as UiBridge } from "./types-4pg-qp_I-Gq63X8Oa.js";
+import { O as ExternalToolSource } from "./index-C-KFAZoF.js";
+//#region ../agent/dist/index.d.ts
+//#region src/todo/types.d.ts
+/** 待办条目状态：未开始 / 进行中 / 已完成（FR-3.1） */
+type TodoStatus = 'pending' | 'in-progress' | 'completed';
+interface TodoItem {
+  id: string;
+  title: string;
+  status: TodoStatus;
+  /** 委派给子 agent 时填入（串行委派批次使用） */
+  delegatedTo?: string;
+}
+interface TodoList {
+  readonly items: readonly TodoItem[];
+}
+/**
+ * 清单变更事件（FR-3.3）。
+ * 走既有的运行事件通道下发：工具结果里的 `$todo` 标记 → runtime 记 trace →
+ * console 读同一份 trace 文件重建时间线，不新建通道。
+ */
+type TodoEvent = {
+  type: 'todo.created';
+  items: readonly TodoItem[];
+} | {
+  type: 'todo.updated';
+  item: TodoItem;
+} | {
+  type: 'todo.cleared';
+};
+type TodoListener = (event: TodoEvent) => void;
+//#endregion
+//#region src/todo/store.d.ts
+/**
+ * 待办清单状态容器（FR-3.1 / FR-3.2 / FR-3.3）。
+ *
+ * 单一进行中约束在**容器内部**强制，而不是靠提示词约束模型：
+ * 模型偶尔会同时标记多条，UI 上出现两个「进行中」时用户无法判断实际进度。
+ * 这里把 `in-progress` 当成互斥资源，置位即降级其余条目。
+ */
+declare class TodoStore {
+  #private;
+  snapshot(): TodoList;
+  /** 订阅变更；返回退订函数 */
+  subscribe(listener: TodoListener): () => void;
+  /** 整表替换（模型每次给出完整清单，避免第二套增量协议）。多条 in-progress 时只保留第一条 */
+  create(items: readonly TodoItem[]): TodoList;
+  /**
+   * 更新单条。置为 `in-progress` 时其余进行中条目降级为 `pending`，
+   * 每条降级各发一次 `todo.updated`，事件序列与状态变化一一对应。
+   */
+  update(id: string, patch: {
+    status?: TodoStatus;
+    title?: string;
+    delegatedTo?: string;
+  }): TodoList;
+  clear(): void;
+}
+//#endregion
+//#region src/todo/toolSource.d.ts
+declare const MANAGE_TODO_TOOL = "manage_todo";
+interface TodoToolSourceOptions {
+  /** 复用宿主已持有的容器（chatbot 用它驱动消息流内的清单面板）；缺省新建 */
+  store?: TodoStore;
+}
+/**
+ * 把待办清单接到既有的工具协议上（设计 03 §4 红线：不引入第二个循环、
+ * 不引入第二套工具协议、包内不含执行器）。
+ *
+ * 变更经工具结果的 `$todo` 标记回传，runtime 据此记 trace——
+ * 与 `$chart` / `$surface` 同一条既有通道，console 读同一份 trace 文件重建时间线。
+ */
+declare function createTodoToolSource(options?: TodoToolSourceOptions): ExternalToolSource & {
+  store: TodoStore;
+};
+//#endregion
+//#region src/prompts/todo.d.ts
+/**
+ * 待办清单提示词片段（FR-3.4）。
+ *
+ * 体积约束（设计 03 §8）：开启后常驻——每次请求都带，所以必须比生成式 UI 的
+ * ~14 KB catalog 小一个数量级。这里刻意只给规则，不给示例对话。
+ */
+declare const TODO_SYSTEM_PROMPT: string;
+//#endregion
+//#region src/skillGeneration/types.d.ts
+/** 生成产物（设计 02 §1.2）：SKILL.md 全文 + 附带脚本/引用文件 */
+interface GeneratedSkillDraft {
+  name: string;
+  description: string;
+  /** SKILL.md 全文，含 frontmatter */
+  content: string;
+  files?: readonly {
+    path: string;
+    content: string;
+  }[];
+}
+/**
+ * 候选收货端口。实现由宿主注入——`@webskill/agent` 不依赖 `@webskill/governance`
+ * （治理层要求宿主提供治理根与审计存储，是可选层）。
+ * `@webskill/governance` 的 `createCandidateSink()` 是现成实现。
+ */
+interface SkillCandidateSink {
+  submit(input: {
+    draft: GeneratedSkillDraft;
+    /** 触发生成的会话（审计留痕与 console 溯源用） */
+    sessionId?: string;
+    /** 用户确认的时刻（FR-9.7 要求审计能查到确认事实） */
+    confirmedAt: string;
+  }): Promise<{
+    id: string;
+  }>;
+}
+/** 频率约束（设计 02 §1.6） */
+interface SkillGenerationPolicy {
+  /** 单次会话内的生成次数上限，默认 3 */
+  maxPerSession?: number;
+}
+type SkillGenerationOutcome = {
+  status: 'submitted';
+  candidateId: string;
+  name: string;
+} | {
+  status: 'declined';
+};
+//#endregion
+//#region src/skillGeneration/generator.d.ts
+interface SkillGeneratorOptions {
+  /** 确认交互走既有的 UiBridge——不新造交互通道（设计 02 §1.4） */
+  ui: UiBridge;
+  /** 缺省表示宿主没接治理层，调用时报 SKILL_GENERATION_DISABLED */
+  sink?: SkillCandidateSink;
+  policy?: SkillGenerationPolicy;
+  /** 生成所属会话，写入审计与候选 metadata */
+  sessionId?: () => string | undefined;
+  now?: () => Date;
+}
+/**
+ * 技能自动生成策略。生成动作是策略而不是内核：它不进入 `AgentLoop`，
+ * 而是经既有的 `ExternalToolSource` 扩展点接入（设计 02 §0）。
+ *
+ * 固定顺序：生成 → 校验 → 确认 → 提交。任何一步不通过都不产生候选。
+ * @experimental
+ */
+declare class SkillGenerator {
+  #private;
+  constructor(options: SkillGeneratorOptions);
+  /** 本会话剩余的生成次数 */
+  get remaining(): number;
+  generate(draft: GeneratedSkillDraft): Promise<SkillGenerationOutcome>;
+}
+//#endregion
+//#region src/skillGeneration/toolSource.d.ts
+declare const GENERATE_SKILL_TOOL = "generate_skill";
+type SkillGenerationToolSourceOptions = SkillGeneratorOptions;
+/**
+ * 把技能自动生成接到既有的工具协议上（设计 02 §1.3）。
+ *
+ * 该工具源默认不注册：宿主只有在开关打开时才把它放进工具表，
+ * 关闭时模型的工具列表里根本没有这个名字。
+ */
+declare function createSkillGenerationToolSource(options: SkillGenerationToolSourceOptions): ExternalToolSource;
+//#endregion
+//#region src/prompts/skillGeneration.d.ts
+/**
+ * 技能自动生成的系统提示词。默认不注册工具，因此这段提示词只在
+ * 宿主打开开关时才进入上下文（设计 02 §1.3）。
+ *
+ * 触发条件写成正面清单而不是「不要自发调用」（0.6.0 FR-18.5）：实测中后者会连
+ * 「帮我写一份流程规范」这类明确的沉淀请求一起抑制掉，开关等于白开。
+ */
+declare const SKILL_GENERATION_SYSTEM_PROMPT: string;
+//#endregion
+//#region src/delegation/types.d.ts
+/** 一次委派请求（设计 03 §12） */
+interface DelegationRequest {
+  /** 关联的待办条目；委派关系经它落到清单上（FR-11.5） */
+  todoId: string;
+  task: string;
+  /** 子 agent 可用的工具子集；缺省继承父级 */
+  allowedTools?: readonly string[];
+}
+interface DelegationResult {
+  todoId: string;
+  outcome: 'completed' | 'failed';
+  /** 只回传结论，不回传子 agent 的中间历史（FR-11.3） */
+  summary: string;
+}
+/** 子 agent 的实际预算（父级剩余与自身上限取小，见 §15） */
+interface DelegationBudget {
+  maxTurns: number;
+  timeoutMs: number;
+}
+/** 父 agent 当前剩余的预算；由宿主在委派发生的那一刻读取 */
+interface ParentBudget {
+  remainingTurns: number;
+  remainingTimeoutMs: number;
+}
+interface SubAgentRunInput {
+  task: string;
+  /** 缺省表示继承父级工具集 */
+  allowedTools?: readonly string[];
+  budget: DelegationBudget;
+  /** 超时由编排器统一裁决：宿主须把它透传给子 run，中途取消即抛错 */
+  signal: AbortSignal;
+  /** 子 agent 发起交互时挂在 `InteractionRequest.origin` 上（FR-11.6） */
+  origin: InteractionOrigin;
+}
+/**
+ * 子 agent 执行端口。**实现不在本包内**——包内不得含执行器（FR-A.4）。
+ * 宿主的实现通常是「再跑一次 `AgentLoop.run`，把结论摘要回传」。
+ */
+type SubAgentRunner = (input: SubAgentRunInput) => Promise<{
+  summary: string;
+}>;
+//#endregion
+//#region src/delegation/orchestrator.d.ts
+interface DelegationOrchestratorOptions {
+  /** 缺省表示宿主没接子 agent 执行端口，调用时报 DELEGATION_UNAVAILABLE */
+  runner?: SubAgentRunner;
+  /** 委派发生的那一刻读取父级剩余预算（§15） */
+  parentBudget: () => ParentBudget;
+  /** 子 agent 自身上限；与父级剩余取小 */
+  policy?: Partial<DelegationBudget>;
+  /** 接上清单后委派关系在 UI 可见（FR-11.5） */
+  todos?: TodoStore;
+}
+/**
+ * 串行委派编排器（设计 03 §13–§16）。
+ *
+ * 严格串行由**内部互斥**保证而不是调用方自觉：并发委派会产生并发待决交互，
+ * 而当前交互模型是单一待决 nonce，届时表现为「点了没反应」。
+ * 放开并发必须显式改这里的守卫，不会悄悄发生。
+ *
+ * 上下文隔离靠回值形状达成：只有 `summary` 回到父 agent，
+ * 子 agent 的消息历史根本不经过本对象。
+ * @experimental
+ */
+declare class DelegationOrchestrator {
+  #private;
+  constructor(options: DelegationOrchestratorOptions);
+  /** 当前正在执行的委派任务；无则 undefined */
+  get running(): string | undefined;
+  delegate(request: DelegationRequest): Promise<DelegationResult>;
+}
+//#endregion
+//#region src/delegation/toolSource.d.ts
+declare const DELEGATE_TASK_TOOL = "delegate_task";
+interface DelegationToolSourceOptions extends DelegationOrchestratorOptions {
+  /** 复用宿主已持有的编排器（同一个 run 内父 agent 只能有一个）；缺省新建 */
+  orchestrator?: DelegationOrchestrator;
+}
+/**
+ * 把串行委派接到既有工具协议上（红线：不引入第二个循环、不引入第二套工具协议、
+ * 包内不含执行器——子 run 由宿主注入的 `runner` 执行）。
+ *
+ * 结果里只有 `summary`：上下文隔离不是靠调用方自律，是因为这里根本拿不到子 agent 的历史。
+ * @experimental
+ */
+declare function createDelegationToolSource(options: DelegationToolSourceOptions): ExternalToolSource & {
+  orchestrator: DelegationOrchestrator;
+};
+//#endregion
+//#region src/delegation/origin.d.ts
+/**
+ * 给子 agent 的交互请求打上来源标识（FR-11.6）。
+ *
+ * 为什么是包装 bridge 而不是让编排器去改请求：交互请求由子 run 内部各处发起
+ * （缺参表单、confirm、授权），编排器看不到它们。宿主在构造子 run 的 bridge 时套一层，
+ * 所有出口就都带上了来源。
+ * @experimental
+ */
+declare function withDelegationOrigin(bridge: UiBridge, origin: InteractionOrigin): UiBridge;
+//#endregion
+//#region src/prompts/delegation.d.ts
+/**
+ * 串行委派的策略提示词（设计 03 §13）。
+ *
+ * 「一次只能有一个」是编排器的硬约束，这里写进提示词是为了让模型不去
+ * 尝试并行委派——被拒绝的调用会浪费一轮，而不是产生并发。
+ */
+declare const DELEGATION_SYSTEM_PROMPT: string;
+//#endregion
+//#region src/perception/types.d.ts
+/**
+ * 页面只读感知的策略层类型（需求 10）。
+ *
+ * 这一层刻意不含任何 DOM 概念：遍历实现在 `@webskill/browser`，
+ * 本包只定义「什么允许被读」以及读到的东西长什么样。
+ */
+/**
+ * 可感知范围白名单（FR-10.2，硬约束）。
+ *
+ * **没有默认值，空 `include` 就是什么都读不到。** 宿主忘了配的后果是
+ * 功能不可用，而不是全页泄露——失败方向必须落在安全那一侧。
+ * @experimental
+ */
+interface PerceptionScope {
+  /** 可感知的根节点选择器；未声明即不可读 */
+  include: readonly string[];
+  /** 从 include 子树中剪除的敏感区域（凭据输入、个人信息展示区等） */
+  exclude?: readonly string[];
+}
+/**
+ * 结构化元素描述（FR-10.4，硬约束）：只有角色、名称、值。
+ *
+ * 不下发 HTML 原文有两条理由：HTML 里的 class / data 属性 / 注释远超模型
+ * 完成任务所需；且页面文本一旦以 HTML 形式进上下文，就多了一条注入通道。
+ * @experimental
+ */
+interface PerceivedNode {
+  /** 可访问性角色 */
+  role: string;
+  /** 可访问名称 */
+  name?: string;
+  /** 仅非敏感控件的当前值 */
+  value?: string;
+  /** 关联的图像分片 id（FR-12.1）；节点里只放 id 不放 base64，否则 JSON 树会被截断切碎 */
+  imageId?: string;
+  /** 取像失败的降级说明（英文）；不得静默丢弃（FR-12.1） */
+  imageNote?: string;
+  children?: readonly PerceivedNode[];
+}
+/** 随感知一起下发的一张图像（FR-12.1） @experimental */
+interface PerceivedImage {
+  /** 与 `PerceivedNode.imageId` 对应 */
+  id: string;
+  mimeType: string;
+  /** base64，不含 `data:` 前缀 */
+  data: string;
+  /** 取像级别：`src` 为原图字节，`canvas` 为画布/SVG 读回 */
+  level: 'src' | 'canvas';
+}
+/**
+ * 取像预算与开关（FR-12.3 / FR-12.5）。
+ * 它只能来自宿主配置与当前模型能力，**不包含任何范围字段**：
+ * “读哪里”仍只由构造时的 `scope` 决定（AC-10.8）。
+ * @experimental
+ */
+interface PerceptionCaptureOptions {
+  /** false 时 reader 不得进入任何取像分支（抓完再丢弃不可接受） */
+  images: boolean;
+  maxImageBytes: number;
+  maxImages: number;
+}
+/**
+ * reader 的完整产物。只实现文本的 reader 可以继续返回节点数组。
+ * @experimental
+ */
+interface PerceptionResult {
+  nodes: readonly PerceivedNode[];
+  images?: readonly PerceivedImage[];
+  /** 超出 `maxImages` 而未下发的张数 */
+  imagesOmitted?: number;
+  /** 取像失败的张数；失败不影响整次感知的成功与否 */
+  imageFailures?: number;
+}
+/**
+ * 页面读取实现的注入口（浏览器侧 `createDomPerceptionReader`）。
+ *
+ * 参数是宿主配置的 scope，不是模型给的——`PagePerceptionPolicy.perceive()`
+ * 根本不接受范围参数，模型没有可以影响它的入口（AC-10.8）。
+ * @experimental
+ */
+interface PagePerceptionReader {
+  read(scope: PerceptionScope, capture?: PerceptionCaptureOptions): Promise<readonly PerceivedNode[] | PerceptionResult> | readonly PerceivedNode[] | PerceptionResult;
+}
+/** 一次感知的留痕（FR-10.5 的 UI 提示与 FR-10.6 的审计共用同一条记录） @experimental */
+interface PerceptionRecord {
+  /** ISO 8601 */
+  at: string;
+  /** 本次实际生效的白名单 */
+  include: readonly string[];
+  exclude: readonly string[];
+  /** 读到的顶层节点数；用于「它读的比我预期的多」这类判断 */
+  nodeCount: number;
+  /** 本次下发的图像张数，按取像级别分组（只在取像开启时存在） */
+  images?: {
+    src: number;
+    canvas: number;
+  };
+  imagesOmitted?: number;
+  /** 读取失败的张数；藏起来会让用户误以为模型看到了全部图片 */
+  imageFailures?: number;
+}
+/**
+ * 审计落盘端口。刻意只声明 `append` 的结构化子集，`FsAuditLog` 直接满足——
+ * agent 包不能依赖 governance，但审计不能因此变成「记在内存里」。
+ * @experimental
+ */
+interface PerceptionAuditSink {
+  append(event: {
+    type: string;
+    target: string;
+    data?: Record<string, unknown>;
+  }): Promise<unknown>;
+}
+//#endregion
+//#region src/perception/policy.d.ts
+interface PagePerceptionPolicyOptions {
+  /** 宿主声明的白名单；`include` 为空即整个能力不可用 */
+  scope: PerceptionScope;
+  reader: PagePerceptionReader;
+  /** FR-10.6：每次感知写审计。不注入即不留痕，装配方要自己承担这个选择 */
+  audit?: PerceptionAuditSink;
+  /** 审计事件的 target（缺省 `page`）；多页面宿主可用它区分来源 */
+  auditTarget?: string;
+  now?(): string;
+}
+/**
+ * 页面只读感知策略（需求 10）。
+ *
+ * **`perceive()` 不接受任何范围参数**——这是「白名单判定不受模型输出影响」
+ * （AC-10.8）的实现方式。不是先拿模型给的范围再去校验，而是模型压根没有
+ * 表达范围的入口：能被读的区域只由构造时的 `scope` 决定。
+ * 唯一的参数是取像预算（`PerceptionCaptureOptions`），它里面没有任何范围字段。
+ *
+ * 本类**没有**任何点击 / 输入 / 提交 / 导航 / 滚动方法（FR-10.7）。
+ * @experimental
+ */
+declare class PagePerceptionPolicy {
+  #private;
+  constructor(options: PagePerceptionPolicyOptions);
+  /** 白名单为空即不可用（FR-10.1/10.2）：宿主没声明范围就没有这个能力 */
+  get enabled(): boolean;
+  get scope(): PerceptionScope;
+  /** 最近的感知记录（console 只读展示用），新的在前 */
+  get records(): readonly PerceptionRecord[];
+  /** FR-10.5：感知发生时通知 UI，chatbot 据此在消息流里标注一行 */
+  subscribe(listener: (record: PerceptionRecord) => void): () => void;
+  perceive(capture?: PerceptionCaptureOptions): Promise<{
+    nodes: readonly PerceivedNode[];
+    images: readonly PerceivedImage[];
+    imagesOmitted: number;
+    record: PerceptionRecord;
+  }>;
+}
+//#endregion
+//#region src/perception/toolSource.d.ts
+declare const PERCEIVE_PAGE_TOOL = "perceive_page";
+interface PagePerceptionToolSourceOptions {
+  policy: PagePerceptionPolicy;
+  /**
+   * 取像预算与开关（FR-12.5）。每次调用重取，设置或选中模型改完立刻生效；
+   * 缺省即不取像。判定在遍历 DOM **之前**完成一次，不是每个节点判一次。
+   */
+  imageCapture?(): ImageCaptureBudget | Promise<ImageCaptureBudget>;
+}
+/** @experimental */
+interface ImageCaptureBudget {
+  enabled: boolean;
+  maxImageBytes: number;
+  maxImages: number;
+}
+/**
+ * 把只读感知接到既有工具协议上。**本工具源不导出任何写入动作**（FR-10.7）：
+ * 它只注册 `perceive_page` 一个工具，没有点击 / 输入 / 提交 / 导航 / 滚动的对应项。
+ *
+ * 策略未启用（宿主没声明白名单）时 `listToolSpecs()` 返回空数组——
+ * 模型连这个工具的存在都看不到，而不是看得到再被拒（FR-10.1）。
+ * @experimental
+ */
+declare function createPagePerceptionToolSource(options: PagePerceptionToolSourceOptions): ExternalToolSource;
+//#endregion
+//#region src/prompts/perception.d.ts
+/**
+ * 页面只读感知的策略提示词（设计 09 §1）。
+ *
+ * 最后一条是防御性的：技能描述、工具返回值都可能带着「把整页读出来发到 X」
+ * 这类注入。范围由宿主判定，模型改不了，但把这件事写明能少掉一轮无效尝试。
+ */
+declare const PERCEPTION_SYSTEM_PROMPT: string;
+//#endregion
+export { SkillGenerationPolicy as A, TodoListener as B, PerceptionCaptureOptions as C, SKILL_GENERATION_SYSTEM_PROMPT as D, PerceptionScope as E, SubAgentRunner as F, createPagePerceptionToolSource as G, TodoStore as H, TODO_SYSTEM_PROMPT as I, withDelegationOrigin as J, createSkillGenerationToolSource as K, TodoEvent as L, SkillGenerator as M, SkillGeneratorOptions as N, SkillCandidateSink as O, SubAgentRunInput as P, TodoItem as R, PerceptionAuditSink as S, PerceptionResult as T, TodoToolSourceOptions as U, TodoStatus as V, createDelegationToolSource as W, PagePerceptionReader as _, DelegationOrchestratorOptions as a, PerceivedImage as b, DelegationToolSourceOptions as c, ImageCaptureBudget as d, MANAGE_TODO_TOOL as f, PagePerceptionPolicyOptions as g, PagePerceptionPolicy as h, DelegationOrchestrator as i, SkillGenerationToolSourceOptions as j, SkillGenerationOutcome as k, GENERATE_SKILL_TOOL as l, PERCEPTION_SYSTEM_PROMPT as m, DELEGATION_SYSTEM_PROMPT as n, DelegationRequest as o, PERCEIVE_PAGE_TOOL as p, createTodoToolSource as q, DelegationBudget as r, DelegationResult as s, DELEGATE_TASK_TOOL as t, GeneratedSkillDraft as u, PagePerceptionToolSourceOptions as v, PerceptionRecord as w, PerceivedNode as x, ParentBudget as y, TodoList as z };