dsh-auto-flow 0.1.0

package/lib/index.d.ts

@@ -0,0 +1,134 @@
+import { ExecKillResult, ExecReadResult, ExecRequest, ExecResult, Greeting } from "./types.js";
+import { Context, Service } from "@deepseek-ai/cordis";
+import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+import z from "@deepseek-ai/schemastery";
+//#region src/index.d.ts
+/** dsh-auto-flow 的插件配置。 */
+interface Config {
+  /** 问候前缀。 */
+  prefix?: string;
+  /** 单条 `exec` 命令允许的最大 UTF-8 字节长度。 */
+  maxCommandBytes?: number;
+}
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** 示例服务（Host 提供，浏览器经 @Remote 调用）。 */
+    autoFlow: AutoFlowService;
+  }
+  interface Events {
+    /**
+     * 一次问候已提交（域事件，跨插件实时通知 seam）。发出方在 `send` 提交后
+     * emit；其它插件可 `ctx.on('autoFlow/recorded', ...)` 订阅。
+     * @mode emit
+     */
+    'autoFlow/recorded'(payload: {
+      readonly greeting: Greeting;
+    }): void;
+  }
+}
+/**
+ * 消息来源归属（MessageSourceMap）示例：若本插件要让「模型消息」归属到自己
+ * （如经 `exec.deferContext` 注入的用户消息），在此新增一个 kind 并在
+ * UserMessage.source 里使用。问候走会话事件而非模型消息，故此处仅声明词汇、
+ * 不强制接线（参考 @deepseek-ai/dsh-goal 的 goal 来源声明）。
+ */
+declare module '@deepseek-ai/dsh-llm' {
+  interface MessageSourceMap {}
+}
+/**
+ * 示例服务：类本身就是插件——static inject / Config 是 Cordis 类插件的约定，
+ * 构造器里的注册（工具/事件/设置/命令）随插件卸载自动回收。
+ *
+ * 平台服务消费方式（跨插件协作走 Cordis 服务、禁止互相 import）：
+ * - 必需依赖用 `static inject`（tools）；
+ * - 可选依赖用 `ctx.inject([...], cb)`（settings / commands / systemPrompt /
+ *   autoFlowFormatter）——服务缺失时插件照常加载；
+ * - shell / sandboxPolicy 是可选服务：用 `ctx.get(...)` 读取，未组合时
+ *   `exec` 报错、插件其余部分照常工作；
+ * - 持久层异步打开走 `[Service.init]`（storageDomain 可选：缺省退化为内存态）。
+ */
+declare class AutoFlowService extends TypertRemoteService {
+  /** 依赖的服务；缺失时 Loader 会等待其出现。 */
+  static inject: string[];
+  /** Config 的 Schema（Cordis 类插件约定：Loader 读类静态 `Config` 校验注入并补齐默认值；
+   * 模块级同名导出不会被 Loader 识别——生成插件请把 Schema 放在类上）。 */
+  static Config: z<Config>;
+  /** 校验后的配置（settings scope 可在运行时覆盖，故非 readonly）。 */
+  private resolved;
+  /** 问候的内存视图（domain storage 是持久层）。 */
+  private readonly greetings;
+  /** 已打开的持久化领域；无后端时保持 null（内存态兜底）。 */
+  private storage;
+  /** 第二包提供的格式化服务；未安装第二包时保持 null（可选依赖）。 */
+  private formatter;
+  /** 最近一次提交的问候（由 `autoFlow/recorded` 监听器维护，供 @Remote last）。 */
+  private lastRecorded;
+  /** 后台进程句柄（@Remote 轻执行自管；不依赖 ctx.jobs，见 exec 说明）。 */
+  private readonly background;
+  private nextBgId;
+  private nextId;
+  constructor(ctx: Context, config?: Config);
+  /**
+   * 异步初始化钩子（Cordis 类插件约定）：构造完成后运行。持久层在这里打开——
+   * 与 @deepseek-ai/dsh-message-feedback 的 `[Service.init]` 同构；storageDomain
+   * 是可选服务，缺失时保持内存态兜底。
+   */
+  protected [Service.init](): Promise<void>;
+  /** 模型工具：复用 @Remote send；presentCall + presentResult 双态展示。 */
+  private registerTool;
+  /** 设置：同一份 Config schema 注册为可编辑 namespace，入口配置作为 base 层。 */
+  private registerSettings;
+  /** 从持久化领域恢复内存视图与自增 id。 */
+  private hydrateFromStorage;
+  /** 斜杠命令：用户键入 /auto-flow 后直接进 handler（不经过模型）。 */
+  private registerCommand;
+  /** 系统提示词：贡献一条模型可见指引（name 唯一、order 升序拼接）。 */
+  private registerSystemPrompt;
+  /** 事件：监听自身域事件维护 lastRecorded 缓存（演示 ctx.on —— 监听器随 fiber 回收）。
+   * 其它插件也可 ctx.on('autoFlow/recorded', ...) 订阅，实现跨插件实时通知。 */
+  private registerEvents;
+  /** 卸载时回收所有未结束的后台进程（@Remote 轻执行自管句柄，必须随 fiber 清理）。 */
+  private registerBackgroundCleanup;
+  /** 跨插件服务消费：第二包（dsh-auto-flow-core）可选提供 autoFlowFormatter。
+   * 用 ctx.inject 而非 static inject——第二包未安装时插件照常加载（send 走无格式化兜底）。 */
+  private registerCore;
+  /**
+   * 追加一条问候并返回记录（写透 domain storage；若有第二包则先格式化；提交后发域事件）。
+   *
+   * 不追加自定义会话事件：harness 的 session 持久化读路径会拒绝 `KNOWN_SESSION_EVENT_TYPES`
+   * 之外的事件类型（除非信封标记 `ignorable`，而 `Session.append` 无此参数），把插件
+   * 自定义事件写进会话日志会导致该会话在重启后无法打开。
+   */
+  send(text: string): Promise<Greeting>;
+  /** 返回全部问候记录（内存视图，已由 domain storage 水合）。 */
+  list(): Promise<Greeting[]>;
+  /** 返回最近一次提交的问候（由域事件监听器维护），首次提交前为 null。 */
+  last(): Promise<Greeting | null>;
+  /**
+   * 执行一条命令行（宿主内经 ctx.shell，与 bash 工具同一执行器，绝不经过模型）。
+   * 输出只回调用方、不进会话日志。@Remote 严格契约保证浏览器端完整类型与校验。
+   *
+   * 相比模型工具（@deepseek-ai/dsh-tool-bash）的 shell 面，@Remote 轻执行只能拿到
+   * 能映射过来的子集：timeoutMs / stdoutMaxBytes / sandboxPolicy / 后台任务 / 结果保真。
+   * 模型工具专属的 seam（shellEnv.collect 需要 ToolExecution、sandbox 升级需要 approval
+   * + callId、abort 需要 ToolExecution.signal）不适用于 @Remote，此处不做。
+   *
+   * 注意：@Remote 方法不能带 `agent: Agent` 参数——第三方仓库的 typert 生成器无法解析
+   * `agent` lookup（其 wire 类型 SessionId 是 branded 类型，官方 monorepo 内才可用）。
+   * 因此沙箱策略退化为「部署默认」（`sandboxPolicy.resolve()` 无 session）。
+   *
+   * 后台执行不走 ctx.jobs（那是给模型工具 job_output/job_kill 用的，需要 agent owner +
+   * dsh-tool-jobs 控制器，@Remote 里拿不到）：直接用 `shell.start()` 拿 ShellProcess
+   * 句柄，自管在 this.background Map 里，execRead/execKill 直接操作句柄；卸载时统一 kill。
+   *
+   * shell / sandboxPolicy 是可选依赖：未组合时抛对应 RemoteError，插件其余照常。
+   */
+  exec(request: ExecRequest): Promise<ExecResult>;
+  /** 读后台进程的下一次增量/终态输出（自管 ShellProcess 句柄，不依赖 ctx.jobs）。 */
+  execRead(jobId: string): Promise<ExecReadResult>;
+  /** 请求取消后台进程（自管 ShellProcess 句柄，不依赖 ctx.jobs）。 */
+  execKill(jobId: string): Promise<ExecKillResult>;
+}
+//#endregion
+export { AutoFlowService, AutoFlowService as default, Config };
+//# sourceMappingURL=index.d.ts.map