@aalis/api-tools 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ace Nyan <ace@acenyan.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# @aalis/api-tools
+
+类型/接口/能力声明包（只导出 `type` 与 `*Capabilities`，不含运行时逻辑）
+
+## 角色
+
+类型/接口/能力声明包（只导出 `type` 与 `*Capabilities`，不含运行时逻辑）
+
+## 安装
+
+```bash
+pnpm add @aalis/api-tools
+```
+
+## 使用
+
+```ts
+import type { /* ... */ } from '@aalis/api-tools';
+```
+
+本包为 *-api 类型包；实现见对应的运行时插件。
+
+## 许可
+
+见仓库根目录 LICENSE。

package/dist/index.d.ts

@@ -0,0 +1,144 @@
+import type { CapabilityConfirm, CapabilityRisk, CapabilityVisibility, ExecutionGuard } from '@aalis/api-authority';
+import type { Context } from '@aalis/core';
+export interface ToolFunction {
+    name: string;
+    strict?: boolean;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+        additionalProperties?: boolean;
+    };
+}
+export interface ToolDefinition {
+    type: 'function';
+    function: ToolFunction;
+}
+export interface ToolCallContext {
+    sessionId: string;
+    userId?: string;
+    platform?: string;
+    /** 当前平台启用的工具分组（供 search_tools 等工具过滤用） */
+    enabledGroups?: string[];
+}
+/** 工具调用状态通知（WebUI 等前端订阅展示用） */
+export interface ToolExecuteMessage {
+    sessionId: string;
+    platform?: string;
+    /** 工具名称 */
+    toolName: string;
+    /** 传入工具的参数 */
+    args: Record<string, unknown>;
+    /** 'start' = 开始调用, 'end' = 调用完成 */
+    phase: 'start' | 'end';
+    /** 工具返回结果（仅在 phase='end' 时存在） */
+    result?: string;
+}
+/**
+ * 已注册的工具：函数声明 + 处理器 + 能力可见性/分组元信息。
+ */
+export interface RegisteredTool {
+    definition: ToolDefinition;
+    handler: (args: Record<string, unknown>, ctx: ToolCallContext) => Promise<string>;
+    pluginName: string;
+    /** 主能力默认可见性（轴 A；缺省 public）；restricted 须被 owner/委托授予 */
+    visibility?: CapabilityVisibility;
+    /** 确认要求（轴 B，与 visibility 正交、owner 也生效）：'session'/'always'；缺省=不确认 */
+    confirm?: CapabilityConfirm;
+    /** 风险等级（声明糖）：展开为 (visibility, confirm) 默认；显式 visibility/confirm 覆盖 */
+    risk?: CapabilityRisk;
+    /** 工具所属分组（用于按平台筛选，未设置时始终可用） */
+    groups?: string[];
+}
+/** 工具摘要（不含 handler，用于搜索展示） */
+export interface ToolSummary {
+    name: string;
+    description: string;
+    groups?: string[];
+}
+/** 工具分组信息 */
+export interface ToolGroupInfo {
+    /** 分组标识（如 'system'、'onebot'、'search'） */
+    name: string;
+    /** 显示名称（如 '系统工具'、'OneBot 工具'） */
+    label: string;
+    /** 分组描述 */
+    description?: string;
+    /** 注册该分组的插件 */
+    pluginName: string;
+}
+/**
+ * 工具服务接口
+ *
+ * 管理 AI 可调用的工具的注册、查询、执行。
+ * 由 plugin-tools 创建 ToolRegistry 并注册为服务。
+ */
+export interface ToolService {
+    register(tool: Omit<RegisteredTool, 'pluginName'>, pluginName: string): () => void;
+    /**
+     * 获取工具定义列表
+     * @param filter 可选过滤条件
+     *   - groups: 仅返回属于指定分组的工具（无 groups 的工具始终包含）
+     */
+    getDefinitions(filter?: {
+        groups?: string[];
+    }): ToolDefinition[];
+    getSummaries(filter?: {
+        groups?: string[];
+    }): ToolSummary[];
+    getAll(): Array<{
+        name: string;
+        description: string;
+        pluginName: string;
+        /** 主能力默认可见性（缺省 public）；可被 authority 配置的 authorityOverrides 调整 */
+        visibility: CapabilityVisibility;
+        /** 生效确认要求（轴 B）；缺省=不确认 */
+        confirm?: CapabilityConfirm;
+        /** 原始风险声明（透传，供 authority 派生 minTier：safe→访客/sensitive→朋友/dangerous→信任） */
+        risk?: CapabilityRisk;
+        groups?: string[];
+    }>;
+    execute(toolName: string, args: Record<string, unknown>, callCtx: ToolCallContext): Promise<string>;
+    /** 注入执行守卫，用于能力裁决与 restricted 二次确认 */
+    setExecutionGuard(guard: ExecutionGuard): void;
+    unregisterByPlugin(pluginName: string): void;
+    /** 注册工具分组 */
+    registerGroup(group: Omit<ToolGroupInfo, 'pluginName'>, pluginName: string): () => void;
+    /** 获取所有已注册的工具分组 */
+    getGroups(): ToolGroupInfo[];
+}
+/** ToolService 绑定到当前 Context 的便捷视图（pluginName 自动填充） */
+export interface ScopedToolService {
+    /** 注册工具。服务未就绪时通过 whenService 自动延迟到就绪后执行（与原 mixin 语义一致）。 */
+    register(tool: Omit<RegisteredTool, 'pluginName'>): () => void;
+    /** 注册工具分组。服务未就绪时通过 whenService 自动延迟。 */
+    registerGroup(group: Omit<ToolGroupInfo, 'pluginName'>): () => void;
+    getDefinitions: ToolService['getDefinitions'];
+    getSummaries: ToolService['getSummaries'];
+    getAll: ToolService['getAll'];
+    getGroups: ToolService['getGroups'];
+    execute: ToolService['execute'];
+    setExecutionGuard: ToolService['setExecutionGuard'];
+    /** 原始 ToolService 引用（服务未就绪时为 undefined） */
+    readonly raw: ToolService | undefined;
+}
+export declare function useToolService(ctx: Context): ScopedToolService;
+/**
+ * 返回一个 ScopedToolService 的视图，其 `register` 会自动为工具
+ * 追加给定 groups（合并而不是覆盖原 tool.groups）。
+ *
+ * 用于一组工具想共享相同分组的场景（如某游戏插件的 'game' 分组）。
+ */
+export declare function toolsWithGroups(tools: ScopedToolService, groups: string[]): ScopedToolService;
+declare module '@aalis/core' {
+    interface AalisEvents {
+        'tool:execute': [info: ToolExecuteMessage];
+    }
+}
+declare module '@aalis/core' {
+    interface ServiceTypeMap {
+        tools: ToolService;
+    }
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,55 @@
+// ===== 工具服务接口与契约类型 =====
+//
+// 本包提供工具系统的全部"非实现"契约：
+// - LLM 函数声明协议类型（ToolDefinition / ToolFunction）
+// - 工具/分组数据结构（RegisteredTool / ToolGroupInfo / ToolSummary）
+// - 工具调用上下文（ToolCallContext）—— 平台/会话语义
+// - 工具执行通知（ToolExecuteMessage）
+// - 服务接口（ToolService）
+// - useToolService(ctx) helper（M2 后取代 ctx.registerTool mixin）
+// - 通过 declaration merging 向 AalisEvents 注入 'tool:execute'
+//
+// 注：`ToolCall`（assistant 消息携带的调用载荷）位于 @aalis/schema-message，
+// 与 Message 同源同生命周期。本包不依赖 message-api（双向解耦）。
+//
+// 实现见 @aalis/plugin-tool-system。
+export function useToolService(ctx) {
+    const pluginName = ctx.id;
+    /** 用于读 API：服务未就绪时抛错。 */
+    function need() {
+        const s = ctx.getService('tools');
+        if (!s) {
+            throw new Error(`useToolService: 'tools' 服务不可用。请在插件 manifest 的 inject 中声明 'tools'，或确认 plugin-agent-tools 已激活。`);
+        }
+        return s;
+    }
+    return {
+        register: tool => ctx.whenService('tools', s => s.register(tool, pluginName)),
+        registerGroup: group => ctx.whenService('tools', s => s.registerGroup(group, pluginName)),
+        getDefinitions: (...args) => need().getDefinitions(...args),
+        getSummaries: (...args) => need().getSummaries(...args),
+        getAll: (...args) => need().getAll(...args),
+        getGroups: (...args) => need().getGroups(...args),
+        execute: (...args) => need().execute(...args),
+        setExecutionGuard: (...args) => need().setExecutionGuard(...args),
+        get raw() {
+            return ctx.getService('tools');
+        },
+    };
+}
+/**
+ * 返回一个 ScopedToolService 的视图，其 `register` 会自动为工具
+ * 追加给定 groups（合并而不是覆盖原 tool.groups）。
+ *
+ * 用于一组工具想共享相同分组的场景（如某游戏插件的 'game' 分组）。
+ */
+export function toolsWithGroups(tools, groups) {
+    return {
+        ...tools,
+        register: tool => tools.register({
+            ...tool,
+            groups: [...(tool.groups ?? []), ...groups],
+        }),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,EAAE;AACF,sBAAsB;AACtB,gDAAgD;AAChD,4DAA4D;AAC5D,uCAAuC;AACvC,+BAA+B;AAC/B,sBAAsB;AACtB,8DAA8D;AAC9D,2DAA2D;AAC3D,EAAE;AACF,6DAA6D;AAC7D,6CAA6C;AAC7C,EAAE;AACF,iCAAiC;AAiKjC,MAAM,UAAU,cAAc,CAAC,GAAY;IACzC,MAAM,UAAU,GAAG,GAAG,CAAC,EAAE,CAAC;IAE1B,wBAAwB;IACxB,SAAS,IAAI;QACX,MAAM,CAAC,GAAG,GAAG,CAAC,UAAU,CAAc,OAAO,CAAC,CAAC;QAC/C,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,MAAM,IAAI,KAAK,CACb,8FAA8F,CAC/F,CAAC;QACJ,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,WAAW,CAAc,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QAC1F,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,WAAW,CAAc,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;QACtG,cAAc,EAAE,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC;QAC3D,YAAY,EAAE,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC;QACvD,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;QAC3C,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;QACjD,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;QAC7C,iBAAiB,EAAE,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAAC;QACjE,IAAI,GAAG;YACL,OAAO,GAAG,CAAC,UAAU,CAAc,OAAO,CAAC,CAAC;QAC9C,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAAwB,EAAE,MAAgB;IACxE,OAAO;QACL,GAAG,KAAK;QACR,QAAQ,EAAE,IAAI,CAAC,EAAE,CACf,KAAK,CAAC,QAAQ,CAAC;YACb,GAAG,IAAI;YACP,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,GAAG,MAAM,CAAC;SAC5C,CAAC;KACL,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@aalis/api-tools",
+  "version": "0.5.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AalisLabs/Aalis.git",
+    "directory": "packages/api-tools"
+  },
+  "author": "Ace Nyan <ace@acenyan.com>",
+  "bugs": {
+    "url": "https://github.com/AalisLabs/Aalis/issues"
+  },
+  "homepage": "https://github.com/AalisLabs/Aalis#readme",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@aalis/api-authority": ">=0.5.0 <1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "@aalis/core": "0.10.0"
+  },
+  "aalis": {
+    "types": true
+  },
+  "peerDependencies": {
+    "@aalis/core": ">=0.2.0 <1.0.0"
+  },
+  "keywords": [
+    "aalis",
+    "aalis-api"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  }
+}