@zhin.js/agent 0.1.14 → 0.1.16

package/README.md

@@ -11,7 +11,7 @@ Zhin AI Agent 组合层：在 `@zhin.js/core` 的类型与 Provider 之上，提
 - 🔄 **模型自动降级**：首选模型失败时自动切换到次优模型，支持 Chat / Vision / Agent 三条路径
 - 🛡️ **6 层 Bash 安全**：`ExecPolicy` 纵深防御（危险黑名单、环境变量剥离、wrapper 剥离、复合命令拆分、只读放行、交互式审批）
 - 📂 **文件访问安全**：`FilePolicy` 路径检查、设备路径拦截、命令读写分类
-- 📋 **10 段系统提示词**：`PromptBuilder` 结构化 prompt（Identity、System、Tasks、Actions、Tools、Communication、Skills、Active Skills、Memory、Bootstrap）
+- 📋 **11 段系统提示词**：`PromptBuilder` 结构化 prompt（Identity、System、Discipline、Tasks、Actions、Tools、Communication、Skills、Active Skills、Memory、Bootstrap）
 - 🔌 **框架挂载**：`initAgentModule()` 注册 `ctx.ai`、定时任务、DB 模型等
 - 📦 **上下文与记忆**：`ContextManager`、`ConversationMemory`、`UserProfileStore`
 - ⏰ **跟进与定时**：`FollowUpManager`、`PersistentCronEngine`、cron 工具
@@ -47,7 +47,7 @@ import {
   AIService,
   SessionManager,
   registerAIHook,
-  getBuiltinTools,
+  createBuiltinTools,
 } from 'zhin.js'
 
 // 使用 ctx.ai (AIService)
@@ -82,14 +82,14 @@ const result = await agent.run('你好')
 | Agent | `Agent`, `createAgent`, `formatToolTitle` |
 | 模型管理 | `ModelRegistry`, `computeTierScore`, `extractModelRoot`, `AIModelInfo` |
 | 服务与会话 | `AIService`, `SessionManager`, `MemorySessionManager`, `DatabaseSessionManager`, `createMemorySessionManager`, `createDatabaseSessionManager` |
-| ZhinAgent | `ZhinAgent`，以及 config / exec-policy / file-policy / tool-collector / prompt / builtin-tools 等子模块 |
+| ZhinAgent | `ZhinAgent`，以及 config / exec-policy / file-policy / tool-runtime / prompt / builtin-tools 等子模块 |
 | 安全策略 | `checkExecPolicy`, `applyExecPolicyToTools`, `isDangerousCommand`, `stripEnvVarPrefix`, `stripSafeWrappers`, `splitCompoundCommand`, `extractCommandName`, `ExecPolicyResult`, `checkFileAccess`, `classifyBashCommand`, `isBlockedDevicePath` |
 | 提示词构建 | `buildRichSystemPrompt`, `buildEnhancedPersona`, `buildUserMessageWithHistory`, `buildContextHint` |
 | 上下文与记忆 | `ContextManager`, `createContextManager`, `ConversationMemory`, `UserProfileStore` |
 | 跟进与定时 | `FollowUpManager`, `PersistentCronEngine`, `createCronTools`, `setCronManager`, `getCronManager` |
 | 压缩与 Bootstrap | `compactSession`, `estimateTokens`, `loadBootstrapFiles`, `loadSoulPersona`, `loadToolsGuide`, `loadAgentsMemory` |
 | Hook | `registerAIHook`, `unregisterAIHook`, `triggerAIHook`, `createAIHookEvent` |
-| 内置工具 | `getBuiltinTools`, `getAllBuiltinTools`, `calculatorTool`, `timeTool`, `searchTool`, `codeRunnerTool`, `httpTool`, `memoryTool` |
+| IM 内置工具工厂 | `createBuiltinTools`、`BuiltinBaseTool`；具体工具见 `src/builtin/*` |
 | 输出与检测 | `parseOutput`, `renderToPlainText`, `renderToSatori`, `detectTone` |
 | 子代理 | `SubagentManager` |
 | 限流 | `RateLimiter` |
@@ -117,13 +117,25 @@ declare module '@zhin.js/core' {
 
 ### 1. 主 Agent + 子 Agent（内置）
 
-框架已提供 **SubagentManager**：主 ZhinAgent 通过工具 `spawn_task` 把复杂/耗时任务派给**后台子 Agent** 异步执行，子 Agent 用受限工具集（文件、Shell、网络搜索等），完成后通过回调把结果发回主会话。
+框架已提供 **SubagentManager**：主 ZhinAgent 通过工具 `spawn_task` 把复杂/耗时任务派给**后台子 Agent** 异步执行，子 Agent 默认仅用受限工具集（文件、Shell、网络搜索等），完成后通过回调把结果发回主会话。
 
 - 主对话不阻塞，用户可继续聊天。
 - 子 Agent 由 `ZhinAgent.initSubagentManager(createTools)` 在 init 时挂好，主 Agent 在回复里提到「后台 / 子任务 / spawn」时会注入 `spawn_task` 工具。
 - 用户说「后台帮我整理这份文档」时，主 Agent 可调用 `spawn_task({ task: '...', label: '...' })`，子任务在后台跑完后再通知用户。
 
-无需额外配置即可使用；若需自定义子 Agent 工具或执行策略，可在 init 里对 `ZhinAgent` 调用 `initSubagentManager` 时传入自己的 `createTools` 和 `execPolicyConfig`。
+无需额外配置即可使用；若需放宽子 Agent 的工具范围，使用 `ai.agent.subagentTools` 显式追加白名单（不会自动继承主会话全部 skill/tool）。
+
+## 工具命名策略
+
+- 保留/内置工具名（如 `bash`、`read_file`、`spawn_task`）不可被插件或文件化工具覆盖。
+- 非保留工具同名时采用 **后注册覆盖前注册**。
+- 冲突统一以 warn 记录：包含 `name`、`source`、`action`（`ignored`/`overridden`）。
+
+## Model harness（第一期）
+
+- 默认参数通过 TypeScript 表维护：`src/zhin-agent/model-harness.ts`。
+- 为新 provider/model 增补默认值时，直接在该表新增行并附测试。
+- 第一阶段不引入新的 YAML 配置键；后续若支持 YAML 覆盖，TS 表仍作为默认层。
 
 ### 2. 用 AIService 创建多个不同配置的 Agent
 
@@ -181,46 +193,71 @@ useContext('ai', async (ai) => {
 
 ```
 src/
-├── index.ts              # 入口与 re-export
-├── agent.ts              # Agent 执行循环（无状态，TF-IDF 工具过滤）
-├── service.ts            # AIService
-├── session.ts            # SessionManager
-├── storage.ts            # 统一存储抽象层（StorageBackend 接口）
-├── context-manager.ts
-├── conversation-memory.ts
-├── user-profile.ts
-├── follow-up.ts
+├── index.ts                         # 导出 AgentOrchestrator + 五类 Registry + ZhinAgent + init
+│
+├── orchestrator/                    # ★ 核心：编排中枢
+│   ├── index.ts                     # AgentOrchestrator class
+│   ├── types.ts                     # ResourceScope, ResourceEntry, Skill, SubAgentDef, AIHook, McpServerEntry
+│   ├── resource-registry.ts         # ResourceRegistry<T> 基类
+│   ├── tool-registry.ts             # ToolRegistry（含 ZhinTool, defineTool, 权限过滤）
+│   ├── skill-registry.ts            # SkillRegistry（含搜索）
+│   ├── subagent-registry.ts         # SubAgentRegistry
+│   ├── mcp-registry.ts              # McpRegistry
+│   └── hook-registry.ts             # HookRegistry
+│
+├── mcp-client/                      # ★ MCP 客户端
+│   ├── index.ts                     # McpClientManager
+│   ├── connection.ts                # 单连接生命周期
+│   └── bridge.ts                    # MCP -> AgentTool/Resource/Prompt 桥接
+│
+├── service.ts                       # AIService（保留，对接 Orchestrator）
+│
+├── zhin-agent/                      # 主对话 Agent
+│   ├── index.ts                     # ZhinAgent（改造：从 Orchestrator 获取资源）
+│   ├── config.ts
+│   ├── prompt.ts
+│   ├── tool-runtime.ts              # 运行时工具收集与执行路径规划
+│   └── context-tools.ts             # chat_history, user_profile, spawn_task
+│
+├── discovery/                       # ★ 文件化资源发现
+│   ├── index.ts
+│   ├── utils.ts
+│   ├── tools.ts                     # *.tool.md 发现
+│   ├── skills.ts                    # SKILL.md 发现
+│   └── agents.ts                    # *.agent.md 发现
+│
+├── security/                        # ★ 安全策略
+│   ├── file-policy.ts
+│   └── exec-policy.ts
+│
+├── builtin/                         # IM 内置工具（BuiltinBaseTool + 各 *-tool.ts）
+├── builtin-tools.ts                 # createBuiltinTools() 聚合
+│
+├── defaults/                        # ★ 各注册表的默认资源
+│   ├── skills.ts                    # 默认 common skills
+│   ├── hooks.ts                     # 默认 common hooks
+│   └── subagents.ts                 # 默认 subagent 模板
+│
+├── common-adapter-tools.ts          # ← 从 core 迁移：群管工具工厂
 ├── subagent.ts
-├── rate-limiter.ts
+├── task-executor.ts
 ├── cron-engine.ts
-├── compaction.ts
 ├── bootstrap.ts
-├── hooks.ts
-├── output.ts
-├── tools.ts
-├── builtin-tools.ts      # 内置工具（bash、read_file、ask_user 等）
-├── tone-detector.ts
-├── file-policy.ts        # 文件访问安全（路径检查、设备拦截、命令分类）
-├── init.ts               # initAgentModule 精简入口（委托子模块）
-├── init/                 # init 子模块（从 init.ts 拆分）
-│   ├── shared-refs.ts
-│   ├── types.ts              # 集中的类型增强声明
-│   ├── register-tool-service.ts
-│   ├── register-db-models.ts
-│   ├── register-ai-service.ts
-│   ├── create-zhin-agent.ts
-│   ├── register-ai-trigger.ts
-│   ├── register-db-upgrade.ts
-│   ├── register-message-recorder.ts
-│   ├── register-management-tools.ts
-│   └── register-builtin-tools.ts
-└── zhin-agent/           # ZhinAgent 及子模块
-    ├── index.ts          # ZhinAgent 主类
-    ├── config.ts         # 配置与常量（chatModel、visionModel、ModelSizeHint 等）
-    ├── exec-policy.ts    # Bash 执行安全（6 层纵深防御）
-    ├── tool-collector.ts # 工具收集与过滤
-    ├── prompt.ts         # 系统提示词构建器（10 段结构化架构）
-    └── builtin-tools.ts  # ZhinAgent 专用内置工具
+├── user-profile.ts
+│
+└── init/
+    ├── index.ts                     # initAgentModule
+    ├── types.ts                     # declare Plugin.Contexts.agent: AgentOrchestrator
+    ├── shared-refs.ts
+    ├── register-orchestrator.ts     # ★ 新增：provide(new AgentOrchestrator())
+    ├── register-db-models.ts
+    ├── register-ai-service.ts
+    ├── create-zhin-agent.ts
+    ├── register-ai-trigger.ts
+    ├── register-db-upgrade.ts
+    ├── register-message-recorder.ts
+    ├── register-management-tools.ts
+    └── register-builtin-tools.ts    # 改造：通过 Orchestrator 注册默认资源
 ```
 
 ### 构建

package/lib/builtin/activate-skill-tool.d.ts

@@ -0,0 +1,21 @@
+import type { Tool, ToolContext, ToolParametersSchema, ToolResult } from '@zhin.js/core';
+import { BuiltinBaseTool } from './builtin-base-tool.js';
+export interface ActivateSkillToolOptions {
+    /** 按名称查找已注册技能的 SKILL.md 绝对路径 */
+    skillFileLookup?: (name: string) => string | undefined;
+    /** 技能根目录列表（每个根下为 `<skillName>/SKILL.md`） */
+    skillDirList: () => string[];
+    skillMaxChars: number;
+}
+export declare const ACTIVATE_SKILL_PARAMETERS: ToolParametersSchema;
+export declare class ActivateSkillBuiltinTool extends BuiltinBaseTool {
+    private readonly opts;
+    readonly name = "activate_skill";
+    readonly description = "\u6309\u540D\u79F0\u6FC0\u6D3B\u6280\u80FD\uFF0C\u52A0\u8F7D\u5176\u5B8C\u6574\u6307\u4EE4\u3002\u5F53\u5224\u65AD\u67D0\u4E2A\u6280\u80FD\u4E0E\u7528\u6237\u8BF7\u6C42\u76F8\u5173\u65F6\u4F7F\u7528";
+    readonly parameters: ToolParametersSchema<Record<string, any>>;
+    readonly kind = "skill";
+    constructor(opts: ActivateSkillToolOptions);
+    run(args: Record<string, unknown>, _context?: ToolContext): Promise<ToolResult>;
+}
+export declare function createActivateSkillTool(opts: ActivateSkillToolOptions): Tool;
+//# sourceMappingURL=activate-skill-tool.d.ts.map

package/lib/builtin/activate-skill-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activate-skill-tool.d.ts","sourceRoot":"","sources":["../../src/builtin/activate-skill-tool.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGzF,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,WAAW,wBAAwB;IACvC,gCAAgC;IAChC,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACvD,4CAA4C;IAC5C,YAAY,EAAE,MAAM,MAAM,EAAE,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,yBAAyB,EAAE,oBAMvC,CAAC;AAEF,qBAAa,wBAAyB,SAAQ,eAAe;IAO/C,OAAO,CAAC,QAAQ,CAAC,IAAI;IANjC,QAAQ,CAAC,IAAI,oBAAoB;IACjC,QAAQ,CAAC,WAAW,4MACkB;IACtC,QAAQ,CAAC,UAAU,4CAA6B;IAChD,QAAQ,CAAC,IAAI,WAAW;gBAEK,IAAI,EAAE,wBAAwB;IAMrD,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;CAwBtF;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,wBAAwB,GAAG,IAAI,CAE5E"}

package/lib/builtin/activate-skill-tool.js

@@ -0,0 +1,57 @@
+/**
+ * activate_skill — 按名称加载技能指令
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { checkSkillDeps, extractSkillInstructions } from '../discovery/skills.js';
+import { errMsg } from '../discovery/utils.js';
+import { BuiltinBaseTool } from './builtin-base-tool.js';
+export const ACTIVATE_SKILL_PARAMETERS = {
+    type: 'object',
+    properties: {
+        name: { type: 'string', description: '技能名称' },
+    },
+    required: ['name'],
+};
+export class ActivateSkillBuiltinTool extends BuiltinBaseTool {
+    opts;
+    name = 'activate_skill';
+    description = '按名称激活技能，加载其完整指令。当判断某个技能与用户请求相关时使用';
+    parameters = ACTIVATE_SKILL_PARAMETERS;
+    kind = 'skill';
+    constructor(opts) {
+        super();
+        this.opts = opts;
+        this.tags.push('skill', 'activate');
+        this.keywords.push('技能', '激活', '启用', '使用', 'skill', 'activate', 'use');
+    }
+    async run(args, _context) {
+        try {
+            const name = String(args.name);
+            const registeredPath = this.opts.skillFileLookup?.(name);
+            if (registeredPath && fs.existsSync(registeredPath)) {
+                const fullContent = await fs.promises.readFile(registeredPath, 'utf-8');
+                const depWarning = await checkSkillDeps(fullContent);
+                const instructions = extractSkillInstructions(name, fullContent, this.opts.skillMaxChars);
+                return depWarning ? `${depWarning}\n\n${instructions}` : instructions;
+            }
+            for (const dir of this.opts.skillDirList()) {
+                const skillPath = path.join(dir, name, 'SKILL.md');
+                if (fs.existsSync(skillPath)) {
+                    const fullContent = await fs.promises.readFile(skillPath, 'utf-8');
+                    const depWarning = await checkSkillDeps(fullContent);
+                    const instructions = extractSkillInstructions(name, fullContent, this.opts.skillMaxChars);
+                    return depWarning ? `${depWarning}\n\n${instructions}` : instructions;
+                }
+            }
+            return `Skill '${name}' not found. Check skills/ directory.`;
+        }
+        catch (e) {
+            return `Error: ${errMsg(e)}`;
+        }
+    }
+}
+export function createActivateSkillTool(opts) {
+    return new ActivateSkillBuiltinTool(opts).toTool();
+}
+//# sourceMappingURL=activate-skill-tool.js.map

package/lib/builtin/activate-skill-tool.js.map

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

package/lib/builtin/ask-user-tool.d.ts

@@ -0,0 +1,28 @@
+/**
+ * ask_user — 基于 Prompt / 私聊 向 Bot Owner 确认或提问
+ */
+import { type Plugin, type Tool, type ToolContext, type ToolParametersSchema, type ToolResult } from '@zhin.js/core';
+import { BuiltinBaseTool } from './builtin-base-tool.js';
+/**
+ * 私聊 Owner 场景：使用 Prompt 类直接交互（原有行为）
+ */
+export declare function askViaPrompt(plugin: Plugin, message: any, args: Record<string, any>, questionType: string, timeoutMs: number): Promise<string>;
+/**
+ * 将 Owner 私聊回复格式化为对应类型的结果
+ */
+export declare function formatOwnerResponse(raw: string, questionType: string, args: Record<string, any>): string;
+export declare const ASK_USER_PARAMETERS: ToolParametersSchema;
+/**
+ * 工厂：`createAskUserTool(plugin)` 或 `createAskUserTool({ plugin })`
+ */
+export declare function createAskUserTool(plugin: Plugin): Tool;
+export declare class AskUserBuiltinTool extends BuiltinBaseTool {
+    private readonly plugin;
+    readonly name = "ask_user";
+    readonly description = "\u5411 Bot Owner \u53D1\u9001\u95EE\u9898\u5E76\u7B49\u5F85\u56DE\u590D\u3002\u7528\u4E8E\u9700\u8981\u786E\u8BA4\u3001\u8865\u5145\u4FE1\u606F\u6216\u505A\u51FA\u9009\u62E9\u65F6\u3002\u5728\u7FA4\u804A\u4E2D\u59CB\u7EC8\u901A\u8FC7\u79C1\u804A\u5411 Owner \u786E\u8BA4\uFF0C\u786E\u4FDD\u5B89\u5168\u6027\u3002";
+    readonly parameters: ToolParametersSchema<Record<string, any>>;
+    readonly kind = "interaction";
+    constructor(plugin: Plugin);
+    run(args: Record<string, unknown>, context?: ToolContext): Promise<ToolResult>;
+}
+//# sourceMappingURL=ask-user-tool.d.ts.map

package/lib/builtin/ask-user-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-user-tool.d.ts","sourceRoot":"","sources":["../../src/builtin/ask-user-tool.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAGL,KAAK,MAAM,EAGX,KAAK,IAAI,EACT,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,UAAU,EAChB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAMzD;;GAEG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,GAAG,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACzB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CAkCjB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAgBxG;AAED,eAAO,MAAM,mBAAmB,EAAE,oBAgBjC,CAAC;AAEF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEtD;AAED,qBAAa,kBAAmB,SAAQ,eAAe;IAOzC,OAAO,CAAC,QAAQ,CAAC,MAAM;IANnC,QAAQ,CAAC,IAAI,cAAc;IAC3B,QAAQ,CAAC,WAAW,8TACoD;IACxE,QAAQ,CAAC,UAAU,4CAAuB;IAC1C,QAAQ,CAAC,IAAI,iBAAiB;gBAED,MAAM,EAAE,MAAM;IAgBrC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;CA6ErF"}

package/lib/builtin/ask-user-tool.js

@@ -0,0 +1,182 @@
+/**
+ * ask_user — 基于 Prompt / 私聊 向 Bot Owner 确认或提问
+ */
+import { Prompt, } from '@zhin.js/core';
+import { errMsg } from '../discovery/utils.js';
+import { BuiltinBaseTool } from './builtin-base-tool.js';
+// ============================================================================
+// Prompt / Owner 回复格式化（原 builtin-tools 顶部辅助函数）
+// ============================================================================
+/**
+ * 私聊 Owner 场景：使用 Prompt 类直接交互（原有行为）
+ */
+export async function askViaPrompt(plugin, message, args, questionType, timeoutMs) {
+    const prompt = new Prompt(plugin, message);
+    try {
+        switch (questionType) {
+            case 'number': {
+                const defaultNum = args.default_value != null ? Number(args.default_value) : undefined;
+                const result = await prompt.number(args.question, timeoutMs, defaultNum, '输入超时，已取消');
+                return String(result);
+            }
+            case 'confirm': {
+                const result = await prompt.confirm(args.question, 'yes', timeoutMs, false, '确认超时，已取消');
+                return result ? 'yes' : 'no';
+            }
+            case 'pick': {
+                if (!args.options?.length) {
+                    return 'Error: type=pick 时必须提供 options 选项列表';
+                }
+                const pickOptions = args.options.map((o) => ({ label: o, value: o }));
+                const result = await prompt.pick(args.question, {
+                    type: 'text',
+                    options: pickOptions,
+                    timeout: timeoutMs,
+                }, '选择超时，已取消');
+                return String(result);
+            }
+            case 'text':
+            default: {
+                const result = await prompt.text(args.question, timeoutMs, args.default_value || '', '输入超时，已取消');
+                return result;
+            }
+        }
+    }
+    catch (e) {
+        return `Owner 未响应或输入错误: ${errMsg(e)}`;
+    }
+}
+/**
+ * 将 Owner 私聊回复格式化为对应类型的结果
+ */
+export function formatOwnerResponse(raw, questionType, args) {
+    switch (questionType) {
+        case 'confirm':
+            return raw.trim().toLowerCase() === 'yes' ? 'yes' : 'no';
+        case 'number':
+            return String(Number(raw) || 0);
+        case 'pick': {
+            const idx = Number(raw.trim());
+            const options = args.options || [];
+            if (idx >= 1 && idx <= options.length)
+                return options[idx - 1];
+            return raw;
+        }
+        case 'text':
+        default:
+            return raw;
+    }
+}
+export const ASK_USER_PARAMETERS = {
+    type: 'object',
+    properties: {
+        question: { type: 'string', description: '要向 Owner 提出的问题文本' },
+        type: {
+            type: 'string',
+            description: '问题类型: text(文本输入)、number(数字输入)、confirm(是/否确认)、pick(选项选择)。默认 text',
+        },
+        options: {
+            type: 'array',
+            description: '选项列表（type=pick 时必填），每项为字符串，如 ["选项A","选项B","选项C"]',
+        },
+        default_value: { type: 'string', description: 'Owner 超时未回复时使用的默认值' },
+        timeout: { type: 'number', description: '等待 Owner 回复的超时时间（秒），默认 120' },
+    },
+    required: ['question'],
+};
+/**
+ * 工厂：`createAskUserTool(plugin)` 或 `createAskUserTool({ plugin })`
+ */
+export function createAskUserTool(plugin) {
+    return new AskUserBuiltinTool(plugin).toTool();
+}
+export class AskUserBuiltinTool extends BuiltinBaseTool {
+    plugin;
+    name = 'ask_user';
+    description = '向 Bot Owner 发送问题并等待回复。用于需要确认、补充信息或做出选择时。在群聊中始终通过私聊向 Owner 确认，确保安全性。';
+    parameters = ASK_USER_PARAMETERS;
+    kind = 'interaction';
+    constructor(plugin) {
+        super();
+        this.plugin = plugin;
+        this.tags.push('interaction', 'prompt');
+        this.keywords.push('询问', '确认', '提问', '用户输入', 'ask', 'confirm', 'prompt', '选择', '请问');
+    }
+    async run(args, context) {
+        if (!context?.message) {
+            return 'Error: 当前上下文没有消息来源，无法向 Owner 提问。请改为在回复中直接询问。';
+        }
+        if (!this.plugin) {
+            return 'Error: 插件实例不可用，无法创建交互式提问。请改为在回复中直接询问。';
+        }
+        const timeoutMs = (args.timeout ?? 120) * 1000;
+        const questionType = args.type || 'text';
+        const recordArgs = args;
+        const platform = context.platform;
+        const botId = context.botId;
+        const adapter = this.plugin.inject(platform);
+        const bot = adapter?.bots?.get(botId);
+        const botOwner = bot?.$config?.owner;
+        const isPrivateOwner = context.scope === 'private'
+            && botOwner != null && String(context.senderId) === String(botOwner);
+        if (isPrivateOwner) {
+            return askViaPrompt(this.plugin, context.message, recordArgs, questionType, timeoutMs);
+        }
+        if (!botOwner) {
+            return 'Error: 当前 Bot 未配置 owner，无法进行安全确认。请在 bots 配置中设置 owner 字段。';
+        }
+        if (!adapter || typeof adapter.sendMessage !== 'function') {
+            return `Error: 无法获取适配器 ${platform}，无法向 Owner 发送私聊确认。`;
+        }
+        const sourceInfo = context.scope !== 'private'
+            ? `来源: ${context.scope}(${context.sceneId}) 用户: ${context.senderId}`
+            : `来源: 私聊 用户: ${context.senderId}`;
+        let questionText = `🔐 AI 安全确认\n${sourceInfo}\n\n${args.question}`;
+        if (questionType === 'confirm') {
+            questionText += '\n输入"yes"以确认';
+        }
+        else if (questionType === 'pick' && args.options?.length) {
+            questionText += '\n' + args.options.map((o, i) => `${i + 1}.${o}`).join('\n');
+        }
+        else if (questionType === 'number') {
+            questionText += '\n(请输入数字)';
+        }
+        try {
+            await adapter.sendMessage({
+                context: platform,
+                bot: botId,
+                id: botOwner,
+                type: 'private',
+                content: questionText,
+            });
+        }
+        catch (e) {
+            return `Error: 无法向 Owner 发送私聊消息: ${errMsg(e)}`;
+        }
+        return new Promise((resolve) => {
+            const middleware = async (message, next) => {
+                if (message.$channel?.type !== 'private')
+                    return next();
+                if (String(message.$sender.id) !== String(botOwner))
+                    return next();
+                if (String(message.$bot) !== String(botId))
+                    return next();
+                dispose();
+                clearTimeout(timer);
+                const raw = message.$raw;
+                resolve(formatOwnerResponse(raw, questionType, recordArgs));
+            };
+            const dispose = this.plugin.addMiddleware(middleware);
+            const timer = setTimeout(() => {
+                dispose();
+                if (args.default_value != null) {
+                    resolve(String(args.default_value));
+                }
+                else {
+                    resolve('Owner 未在规定时间内响应，操作已取消。');
+                }
+            }, timeoutMs);
+        });
+    }
+}
+//# sourceMappingURL=ask-user-tool.js.map

package/lib/builtin/ask-user-tool.js.map

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

package/lib/builtin/bash-tool.d.ts

@@ -0,0 +1,23 @@
+/**
+ * bash — Shell 执行（安全检查 + 命令读写分类）
+ */
+import { type ExecOptions } from 'node:child_process';
+import type { Tool, ToolContext, ToolParametersSchema, ToolResult } from '@zhin.js/core';
+import { BuiltinBaseTool } from './builtin-base-tool.js';
+/** 可注入以便单测（默认 `promisify(exec)`） */
+export type BashExecAsync = (command: string, options?: ExecOptions) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare const BASH_PARAMETERS: ToolParametersSchema;
+export declare class BashBuiltinTool extends BuiltinBaseTool {
+    private readonly execAsync;
+    readonly name = "bash";
+    readonly description = "\u6267\u884C Shell \u547D\u4EE4\uFF08\u5E26\u8D85\u65F6\u4FDD\u62A4\u548C\u547D\u4EE4\u5206\u7C7B\uFF09\u3002\u8FD4\u56DE\u7ED3\u679C\u4E2D\u4F1A\u6807\u6CE8\u547D\u4EE4\u7C7B\u578B\uFF08\u53EA\u8BFB/\u641C\u7D22/\u5199\u5165\uFF09\u3002";
+    readonly parameters: ToolParametersSchema<Record<string, any>>;
+    readonly kind = "shell";
+    constructor(execAsync?: BashExecAsync);
+    run(args: Record<string, unknown>, _context?: ToolContext): Promise<ToolResult>;
+}
+export declare function createBashTool(): Tool;
+//# sourceMappingURL=bash-tool.d.ts.map

package/lib/builtin/bash-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bash-tool.d.ts","sourceRoot":"","sources":["../../src/builtin/bash-tool.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAQ,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE5D,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAMzF,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAIzD,oCAAoC;AACpC,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,WAAW,KAClB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjD,eAAO,MAAM,eAAe,EAAE,oBAQ7B,CAAC;AAEF,qBAAa,eAAgB,SAAQ,eAAe;IAOtC,OAAO,CAAC,QAAQ,CAAC,SAAS;IANtC,QAAQ,CAAC,IAAI,UAAU;IACvB,QAAQ,CAAC,WAAW,mPACgC;IACpD,QAAQ,CAAC,UAAU,4CAAmB;IACtC,QAAQ,CAAC,IAAI,WAAW;gBAEK,SAAS,GAAE,aAAgC;IAMlE,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;CAyBtF;AAED,wBAAgB,cAAc,IAAI,IAAI,CAErC"}

package/lib/builtin/bash-tool.js

@@ -0,0 +1,64 @@
+/**
+ * bash — Shell 执行（安全检查 + 命令读写分类）
+ */
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import { checkBashCommandSafety, classifyBashCommand, } from '../security/file-policy.js';
+import { errMsg } from '../discovery/utils.js';
+import { BuiltinBaseTool } from './builtin-base-tool.js';
+const defaultExecAsync = promisify(exec);
+export const BASH_PARAMETERS = {
+    type: 'object',
+    properties: {
+        command: { type: 'string', description: 'Shell 命令' },
+        cwd: { type: 'string', description: '工作目录' },
+        timeout: { type: 'number', description: '超时毫秒数（默认 30000）' },
+    },
+    required: ['command'],
+};
+export class BashBuiltinTool extends BuiltinBaseTool {
+    execAsync;
+    name = 'bash';
+    description = '执行 Shell 命令（带超时保护和命令分类）。返回结果中会标注命令类型（只读/搜索/写入）。';
+    parameters = BASH_PARAMETERS;
+    kind = 'shell';
+    constructor(execAsync = defaultExecAsync) {
+        super();
+        this.execAsync = execAsync;
+        this.tags.push('shell', 'exec');
+        this.keywords.push('执行', '运行', '命令', '终端', 'shell', 'bash');
+    }
+    async run(args, _context) {
+        try {
+            const timeout = args.timeout ?? 30000;
+            const cmd = String(args.command || '');
+            const safety = checkBashCommandSafety(cmd);
+            if (!safety.safe)
+                return `Error: ${safety.reason}`;
+            const classification = classifyBashCommand(cmd);
+            const cwd = args.cwd || process.cwd();
+            const { stdout, stderr } = await this.execAsync(cmd, {
+                cwd,
+                timeout,
+                maxBuffer: 1024 * 1024,
+            });
+            let result = '';
+            const tag = classification.isReadOnly
+                ? (classification.isSearch ? '[搜索]' : classification.isList ? '[列出]' : '[只读]')
+                : '[执行]';
+            if (stdout.trim())
+                result += `STDOUT:\n${stdout.trim()}`;
+            if (stderr.trim())
+                result += `${result ? '\n' : ''}STDERR:\n${stderr.trim()}`;
+            return `${tag} ${result || '(no output)'}`;
+        }
+        catch (e) {
+            const err = e;
+            return `Error (exit ${err.code || '?'}): ${errMsg(e)}\nSTDOUT:\n${err.stdout || ''}\nSTDERR:\n${err.stderr || ''}`;
+        }
+    }
+}
+export function createBashTool() {
+    return new BashBuiltinTool().toTool();
+}
+//# sourceMappingURL=bash-tool.js.map

package/lib/builtin/bash-tool.js.map

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

package/lib/builtin/bing-search-html.d.ts

@@ -0,0 +1,37 @@
+export interface BingSearchResultRow {
+    title: string;
+    url: string;
+    snippet?: string;
+}
+export declare const decodeHtmlEntities: (s: string) => string;
+/**
+ * 从 Bing 结果页 HTML 提取有机结果。
+ * 结果位于 <ol id="b_results"> 内 <li class="b_algo"> 块中。
+ */
+export declare function extractBingResults(html: string): BingSearchResultRow[];
+/**
+ * 将 Bing 跳转链接解析为真实 URL（/ck/a?...&u=a1aHR0cHM6Ly9...）
+ */
+export declare function resolveBingUrl(rawUrl: string): string | undefined;
+/** @deprecated 单测兼容：请用 {@link bingSearchFetchHeaders}；默认语言为 en-US 旧行为已弃用 */
+export declare const BING_SEARCH_BROWSER_HEADERS: {
+    readonly 'Accept-Language': "en-US,en;q=0.9";
+    readonly 'User-Agent': "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36 Edg/131.0.0.0";
+    readonly Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8";
+    readonly 'Accept-Encoding': "gzip, deflate, br";
+    readonly 'Cache-Control': "no-cache";
+    readonly Pragma: "no-cache";
+    readonly 'Sec-Ch-Ua': "\"Microsoft Edge\";v=\"131\", \"Chromium\";v=\"131\", \"Not_A Brand\";v=\"24\"";
+    readonly 'Sec-Ch-Ua-Mobile': "?0";
+    readonly 'Sec-Ch-Ua-Platform': "\"macOS\"";
+    readonly 'Sec-Fetch-Dest': "document";
+    readonly 'Sec-Fetch-Mode': "navigate";
+    readonly 'Sec-Fetch-Site': "none";
+    readonly 'Sec-Fetch-User': "?1";
+    readonly 'Upgrade-Insecure-Requests': "1";
+};
+export declare function bingSearchFetchHeaders(market: string): Record<string, string>;
+export declare const BING_SEARCH_FETCH_TIMEOUT_MS = 30000;
+export declare function buildBingSearchUrl(query: string, market?: string): string;
+export declare function hostnameMatchesList(hostname: string, domain: string): boolean;
+//# sourceMappingURL=bing-search-html.d.ts.map

package/lib/builtin/bing-search-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bing-search-html.d.ts","sourceRoot":"","sources":["../../src/builtin/bing-search-html.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,kBAAkB,GAAI,GAAG,MAAM,KAAG,MAAsB,CAAC;AAEtE;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAsBtE;AA0BD;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoBjE;AAqBD,4EAA4E;AAC5E,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;CAG9B,CAAC;AAEX,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAK7E;AAED,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,MAAkC,GACzC,MAAM,CAGR;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAI7E"}