@ai-zen/agents-host 0.0.0-stage → 0.1.0-alpha.1

package/dist/services/AgentService.d.ts

@@ -0,0 +1,150 @@
+/**
+ * 助手服务：助手与子 Agent 定义的增删改查、改默认模型、改思考档位（F-B1…F-B7 / F-F5 / F-G3）。
+ *
+ * 助手定义是**配置**而不是用户数据（F-G3）：一实体一文件，存在数据根的 `agents/` 与
+ * `sub-agents/` 下，能进 git、能手改。所以这里的读写全走 SDK 的 `AgentRepository`，
+ * 不碰数据库。有 `function` 字段的那些是子 Agent（SDK 的发现口径），落在 `sub-agents/`。
+ *
+ * 产品的两条硬要求：
+ *   - **不可用的也要列出并说明原因**（F-B5）：文件读不出来、模型没了、端点没配密钥，都算
+ *     不可用，但都照样出现在清单里，带着一句为什么。
+ *   - **删默认助手要连带清默认**（F-F5）：删完还留着一个指向空处的默认助手，下一次建对话
+ *     才会炸出来。
+ */
+import { AgentRepository } from "@ai-zen/agents-sdk";
+import type { AgentDefinition, AppConfig, ConfigManager, ReasoningPresets } from "@ai-zen/agents-sdk";
+import type { AgentCreateParams, AgentCreateResult, AgentDeleteParams, AgentDeleteResult, AgentGetParams, AgentGetResult, AgentListParams, AgentListResult, AgentRestoreFactoryParams, AgentRestoreFactoryResult, AgentSetModelParams, AgentSetModelResult, AgentSetThinkingParams, AgentSetThinkingResult, AgentUpdateParams, AgentUpdateResult, AgentView } from "../wire/index.js";
+/** 助手服务的依赖；由单根组装后注入 */
+export interface AgentServiceOptions {
+    /** 配置唯一入口（SDK）：默认助手、兜底模型、思考策略表都在这里 */
+    configManager: ConfigManager;
+    /** 助手定义仓储；缺省按 `<basePath>/agents/` 造一个 */
+    agents?: AgentRepository;
+    /** 子 Agent 定义仓储；缺省按 `<basePath>/sub-agents/` 造一个 */
+    subAgents?: AgentRepository;
+    /** 时钟，测试注入用；缺省 `Date.now` */
+    now?: () => number;
+}
+/** 一条定义来自哪个仓储（决定删除时该删哪个文件） */
+type AgentHome = "agents" | "sub-agents";
+/**
+ * 一个助手的最小只读事实：它现在叫什么、现在能不能用。
+ *
+ * `describe()` 的返回值。状态栏的助手块（`conversation.state`）只要这两条：它不展示提示词、
+ * 权限、思考档位，所以不必把整份 `AgentView` 搬过去。
+ */
+export interface AgentDescription {
+    /** 定义上的 id（与传入的 `agentId` 相同） */
+    agentId: string;
+    /** 定义上的显示名 */
+    name: string;
+    /** 现在能不能跑（模型 / 端点 / 密钥都齐才算，与 `agent.list` 同一份口径） */
+    available: boolean;
+}
+/** 仓储里读到的一条定义；`definition` 为 `null` 表示文件在但读不出来 */
+interface LoadedAgent {
+    id: string;
+    home: AgentHome;
+    definition: AgentDefinition | null;
+    /** 读不出来的原因（`definition === null` 时才有） */
+    brokenReason: string | null;
+}
+export declare class AgentService {
+    private readonly configManager;
+    private readonly repos;
+    private readonly now;
+    constructor(options: AgentServiceOptions);
+    /**
+     * 助手清单（F-B2 / F-B3 / F-B5）。
+     *
+     * 主助手在前、子 Agent 在后，各自按 id 排 —— 同一份磁盘状态每次给同一个顺序。
+     * 读不出来的定义文件也列出来（`available: false` + 原因）：藏起来会让人以为它没了。
+     *
+     * `workspaceId` 只做存在性校验：助手定义的可用性（模型、端点、密钥）是全局配置的事实，
+     * 与项目无关；「这个项目里能不能用」要等可用的 Skill / MCP 清单定下来才有答案。
+     */
+    list(_params?: AgentListParams): Promise<AgentListResult>;
+    /** 按 id 取一个助手 */
+    get(params: AgentGetParams): Promise<AgentGetResult>;
+    /**
+     * 一个助手现在叫什么、能不能用（最小只读导出，PRD F-I6 的状态栏助手块用）。
+     *
+     * 与 `get()` 走同一份 `load()` / `toView()` 口径，只是只回这两条事实：调用方（会话现场快照）
+     * 要的是「这个 id 现在叫什么、还能不能跑」，不是整份定义。
+     *
+     * 拿不到就回 `null`：定义文件已经没了（助手被删，而对话仍记着那个 id，L7），或者文件在但
+     * 读不出来（坏 JSON）。这两种情况下「名字」与「可用性」都没有可报的事实。
+     */
+    describe(agentId: string): Promise<AgentDescription | null>;
+    /** 新建助手定义（一实体一文件，F-G3） */
+    create(params: AgentCreateParams): Promise<AgentCreateResult>;
+    /** 编辑助手定义（局部更新；`modelId: ""` 表示把绑定清掉，交给配置里的兜底模型） */
+    update(params: AgentUpdateParams): Promise<AgentUpdateResult>;
+    /**
+     * 删除助手定义（F-F5）。
+     *
+     * 删的正好是默认助手时连带把默认清掉（`defaultsCleared`）。其它指向关系（别的助手在
+     * 权限里点名它的 function）只报在 `references` 里 —— 那些是权限白名单里的一个名字，
+     * 删掉定义之后那条名字什么都不指，不是「不能删」。
+     */
+    delete(params: AgentDeleteParams): Promise<AgentDeleteResult>;
+    /**
+     * 改助手的默认模型（F-B4 / F-B1：影响以后的对话，与「改这段会话的模型」是两个动作）。
+     *
+     * 换了模型就同时把定义上「旧模型档位带来的那些参数」去掉：定义上的参数是给旧模型配的，
+     * 旧模型才认的键（例如某个厂商的 `thinking` 形状）发给新模型只会换来一句 400。
+     * 定义上与其无关的参数（`temperature` 之类）不动。
+     */
+    setModel(params: AgentSetModelParams): Promise<AgentSetModelResult>;
+    /**
+     * 把思考档位展开成参数写进助手定义（F-B6：写进去的是参数，档位名只是标签）。
+     *
+     * 档位必须在这个模型的思考策略表里：表里没有的档发出去只会换来一句 400。
+     * 合并口径是「在现有参数上叠加这一档的补丁」—— 与思考无关的参数（temperature 之类）不动。
+     *
+     * `level: null` 是撤回设值：把定义里属于思考策略的那些参数删掉，其余参数照旧留着；
+     * 删完不剩任何参数时 `modelParams` 整个从定义里去掉，让「参数即真相」回到模型的默认参数。
+     * 与会话那一侧的 `conversation.setThinking(null)`（改成会话行上的档位名）是两件事。
+     */
+    setThinking(params: AgentSetThinkingParams): Promise<AgentSetThinkingResult>;
+    /**
+     * 恢复出厂（F-F5：整条替换，与 `model.restoreFactory` 同一个语义）。
+     *
+     * 出厂那一份来自 SDK 的出厂定义（`DEFAULT_AGENT_DEFINITION` / `DEFAULT_SUBAGENT_DEFINITION`），
+     * 用户自建的助手不在出厂清单里，没有可恢复的版本。恢复之后这一条重新归 SDK 托管
+     * （`custom: false`，下次初始化会跟着出厂定义同步提示词），提示词 / 模型 / 权限 / 思考参数
+     * 全回到出厂那份；`createdAt` 是这个实体诞生的时刻，留着，`updatedAt` 是这次写入。
+     *
+     * `dryRun` 只算出「恢复之后会是什么样」，不落盘；本来就和出厂一致时回 `restored: false`
+     * （没有可恢复的改动，不是失败）。
+     */
+    restoreFactory(params: AgentRestoreFactoryParams): Promise<AgentRestoreFactoryResult>;
+    /** 一条定义（或一个读不出来的文件）→ 对外形状 */
+    toView(config: AppConfig, presets: ReasoningPresets, item: LoadedAgent): AgentView;
+    /** 这个助手现在能不能跑：没模型、模型没了、端点没了/没密钥，各有各的说法 */
+    private unavailableProblem;
+    /**
+     * 思考强度的状态（F-B6 / F-B7）。
+     *
+     * `manual` = 定义上的参数正好是某一档；`following_default` = 定义没指定，跟着模型默认走；
+     * `not_adjustable` = 这个模型引用的策略表里一条档位都没有。
+     */
+    private thinkingOf;
+    /** 默认助手 id：配置里那个还在就用它，否则回落 `default`，再否则取清单第一个 */
+    private resolveDefaultAgentId;
+    /** 哪个目录该放这条定义：有 `function` 的是子 Agent（SDK 的发现口径） */
+    private homeOf;
+    /** 读一个定义（两个目录都找）；不存在回 `null` */
+    private load;
+    /** 读全部定义（两个目录），读不出来的也占一行 */
+    private loadAll;
+    /** 仓储对应的目录 */
+    private repoDir;
+    /** 要改定义时先把它读出来；读不出来（坏文件）就没有可改的内容 */
+    private requireEditable;
+    /** 引用：默认助手 + 别的助手在权限里点名的子 Agent function */
+    private referencesOf;
+    /** `modelId` 给了就必须指向一个存在的模型（写进定义的 id 不能是悬空的） */
+    private assertModelReference;
+}
+export {};