hyacinth-ai 0.9.21 → 0.9.22

package/dist/channels/dispatcher.d.ts

@@ -1,17 +1,29 @@
 import type { Tool } from '../tools/interface.js';
 import type { ChannelManager } from './manager.js';
 /**
- * MessageDispatcher — 统一分发层。
- * 查目标渠道 → 调其 send() → 返回结果。
+ * MessageDispatcher — 跨渠道统一分发层。
+ *
+ * 持有 ChannelManager 引用，按渠道 ID 查找目标渠道并调用其 send() 方法。
+ * 本身无状态——每次调用都是独立的、一次性的。
  */
 export declare class MessageDispatcher {
     private channelManager;
     constructor(channelManager: ChannelManager);
+    /**
+     * 借用指定渠道发送消息。
+     *
+     * @returns 发送结果描述字符串，失败时包含错误原因（不抛异常，始终返回字符串）
+     */
     send(args: {
+        /** 目标渠道 ID（如 'feishu'、'clawbot'） */
         channel: string;
+        /** 目标用户 ID 或群聊 ID */
         to: string;
+        /** 目标类型，默认 user */
         targetType?: 'user' | 'chat';
+        /** 文本内容（可选，与 images 至少有一项有意义） */
         text?: string;
+        /** 图片列表（base64 + MIME 类型） */
         images?: Array<{
             data: string;
             media_type: string;
@@ -19,7 +31,14 @@ export declare class MessageDispatcher {
     }): Promise<string>;
 }
 /**
- * send_channel_message 工具——暴露给 Agent 的跨渠道发送能力。
+ * send_channel_message 工具 —— 暴露给 Agent 的跨渠道发送入口。
+ *
+ * Agent 在任何渠道的任意会话中都可以调用此工具，借用其他已连接渠道
+ * 的发送能力。典型场景：TUI 会话中的 Agent 通过飞书发图片给用户，
+ * 或者定时任务触发后通过微信推送通知。
+ *
+ * 此工具注册在 TUI/Server 的网关层（gateway/tui.ts、gateway/server.ts），
+ * 在 channelManager.startAll() 之后注册，确保所有渠道已启动。
  */
 export declare function createSendChannelMessageTool(dispatcher: MessageDispatcher): Tool;
 //# sourceMappingURL=dispatcher.d.ts.map

package/dist/channels/dispatcher.js

@@ -2,46 +2,85 @@
 // MessageDispatcher — 跨渠道消息分发层
 // ============================================================
 //
-// 允许 Agent 从任意会话借用其他渠道的发送能力。
-// 消息是一次性的——不创建 session、不写 conversation、不影响任何渠道的对话状态。
-// 被借用的渠道对"谁借了道"完全无感。
+// 设计意图：
+//   Hyacinth 的渠道系统原本是"请求-回复"模式——用户在某个渠道发消息，
+//   Agent 通过同一个渠道的 reply() 回复。但这限制了 Agent 的能力：
+//   TUI 会话中的 Agent 无法通过飞书发图片，飞书会话中的 Agent 也无法
+//   通过微信传文件。每个渠道的发送能力被封闭在自己的生命周期里。
+//
+//   MessageDispatcher 打破了这个封闭——它让 Agent 可以从任意会话
+//   借用任意已连接渠道的发送能力。这是"跨渠道"而非"跨会话"——
+//   借用的是渠道的 API 能力，不影响任何渠道的对话状态。
+//
+// 核心语义（"纯借用"）：
+//   1. 不创建 session —— 消息是一次性的，不关联 AgentLoop
+//   2. 不写 conversation.jsonl —— 不污染任何渠道的对话历史
+//   3. 不影响 ChannelHandler 内部状态 —— sessionMap、消息队列等完全不变
+//   4. 被借用渠道对"谁借的"完全无感 —— 不记录调用来源
+//
+// 调用链：
+//   Agent → send_channel_message({channel:'feishu', to:'ou_xxx', text:'...'})
+//        → MessageDispatcher.send()
+//          → ChannelManager.get('feishu') → handler.send(target, content)
+//            → 渠道 API → 用户收到消息
+//
+// 扩展新渠道时：
+//   只需实现 ChannelHandler.send?() 方法（可选），MessageDispatcher 自动发现。
+//   不实现 send() 的渠道返回 "不支持主动发送"，不影响其他功能。
 // ============================================================
 /**
- * MessageDispatcher — 统一分发层。
- * 查目标渠道 → 调其 send() → 返回结果。
+ * MessageDispatcher — 跨渠道统一分发层。
+ *
+ * 持有 ChannelManager 引用，按渠道 ID 查找目标渠道并调用其 send() 方法。
+ * 本身无状态——每次调用都是独立的、一次性的。
  */
 export class MessageDispatcher {
     channelManager;
     constructor(channelManager) {
         this.channelManager = channelManager;
     }
+    /**
+     * 借用指定渠道发送消息。
+     *
+     * @returns 发送结果描述字符串，失败时包含错误原因（不抛异常，始终返回字符串）
+     */
     async send(args) {
+        // ① 查找目标渠道
         const state = this.channelManager.get(args.channel);
         if (!state || state.status !== 'active') {
             return `渠道 "${args.channel}" 未连接或未启动。可用渠道: ${this.channelManager.getStatusSummary().map(s => s.id).join(', ') || '无'}`;
         }
         const handler = state.handler;
+        // ② 检查渠道是否支持主动发送
         if (!handler.send) {
             return `渠道 "${args.channel}" (${handler.name}) 不支持主动发送。`;
         }
+        // ③ 构造标准目标并委托给渠道的 send()
         const target = {
             type: args.targetType ?? 'user',
             id: args.to,
         };
         try {
-            const result = await handler.send(target, {
+            return await handler.send(target, {
                 content: args.text ?? '',
                 images: args.images,
             });
-            return result;
         }
         catch (err) {
+            // 异常兜底——渠道 send() 应该自己 catch，这里防止未预期的异常泄漏
             return `发送失败: ${err instanceof Error ? err.message : String(err)}`;
         }
     }
 }
 /**
- * send_channel_message 工具——暴露给 Agent 的跨渠道发送能力。
+ * send_channel_message 工具 —— 暴露给 Agent 的跨渠道发送入口。
+ *
+ * Agent 在任何渠道的任意会话中都可以调用此工具，借用其他已连接渠道
+ * 的发送能力。典型场景：TUI 会话中的 Agent 通过飞书发图片给用户，
+ * 或者定时任务触发后通过微信推送通知。
+ *
+ * 此工具注册在 TUI/Server 的网关层（gateway/tui.ts、gateway/server.ts），
+ * 在 channelManager.startAll() 之后注册，确保所有渠道已启动。
  */
 export function createSendChannelMessageTool(dispatcher) {
     return {

package/dist/channels/interface.d.ts

@@ -45,11 +45,11 @@ export interface ChannelReply {
     }>;
     metadata?: Record<string, unknown>;
 }
-/** 主动发送的目标（跨渠道借用能力时指定接收方） */
+/** 跨渠道主动发送的目标接收方 */
 export interface ChannelTarget {
-    /** 目标类型 */
+    /** 目标类型：user=私聊用户，chat=群聊 */
     type: 'user' | 'chat';
-    /** 用户 ID 或群聊 ID */
+    /** 目标 ID（格式由各渠道自行定义：飞书 ou_/oc_，微信 wxid 等） */
     id: string;
 }
 /** 输出处理器（渠道消息收集用） */
@@ -145,13 +145,24 @@ export interface ChannelHandler {
      */
     getStatus(): ChannelStatus;
     /**
-     * 主动发送消息到渠道（跨 session，不关联任何 AgentLoop、不落盘）。
-     * 用于从其他渠道借用本渠道的发送能力（如 TUI 中的 Agent 通过飞书发消息）。
-     * 未实现 = 该渠道不支持被外部借用。
+     * 主动发送消息（跨渠道借用能力入口）。
      *
-     * @param target 目标用户或群聊
-     * @param content 消息内容
-     * @returns 发送结果描述
+     * 设计意图：reply() 是"回复"——在 handleMessage 生命周期内，将 Agent
+     * 的响应发回给当前会话的用户。send() 是"借用"——任何渠道的 Agent
+     * 都可以调用其他渠道的 send() 来借用其发送能力，不依赖 handleMessage 生命周期。
+     *
+     * 行为保证（"纯借用"语义）：
+     *   - 不创建 session —— 消息是一次性的，不关联 AgentLoop
+     *   - 不写 conversation —— 不污染对话历史
+     *   - 不影响渠道内部状态 —— sessionMap、消息队列等完全不变
+     *
+     * 调用来源：MessageDispatcher → send_channel_message 工具 → Agent
+     *
+     * 未实现 = 该渠道不支持被外部借用（返回 undefined，MessageDispatcher 会给出友好提示）。
+     *
+     * @param target  目标接收方（用户或群聊），各渠道自行解析 ID 格式
+     * @param content 消息内容（文本 + 可选图片），复用 ChannelReply 避免定义新类型
+     * @returns 发送结果描述（成功或失败原因），不抛异常
      */
     send?(target: ChannelTarget, content: ChannelReply): Promise<string>;
 }

package/dist/channels/plugins/feishu/feishu-send.d.ts

@@ -42,7 +42,8 @@ export declare function getSenderInfo(config: FeishuChannelConfig, userId: strin
     avatar?: string;
 } | null>;
 /**
- * 发送图片消息（需先通过上传 API 获取 image_key）。
+ * 发送图片消息。
+ * @param imageKey 飞书上传 API 返回的 image_key
  */
 export declare function sendImage(config: FeishuChannelConfig, params: {
     to: string;

package/dist/channels/plugins/feishu/feishu-send.js

@@ -229,8 +229,25 @@ export async function getSenderInfo(config, userId, userIdType = 'open_id') {
         return null;
     }
 }
+// ================================================================
+// 图片消息发送
+// ================================================================
+//
+// 飞书发送图片是两步操作：
+//   1. 上传图片到飞书服务器 → 获取 image_key
+//      POST /open-apis/im/v1/images  { image_type: 'message', image: base64 }
+//   2. 用 image_key 发送图片消息
+//      POST /open-apis/im/v1/messages  { msg_type: 'image', content: '{"image_key":"img_xxx"}' }
+//
+// 注意：
+//   - 图片上传走二进制 base64，不走 multipart/form-data
+//   - image_key 有时效性（约 2 小时），不持久化
+//   - 图片消息和文本消息是两条独立的飞书消息，不支持单条图文混排
+//   - 调用方（FeishuChannel.send()）负责先上传拿到 image_key 再调用本函数
+// ================================================================
 /**
- * 发送图片消息（需先通过上传 API 获取 image_key）。
+ * 发送图片消息。
+ * @param imageKey 飞书上传 API 返回的 image_key
  */
 export async function sendImage(config, params) {
     const client = await createFeishuClient(config);

package/dist/gateway/factory.js

@@ -570,13 +570,13 @@ export async function createAgent(options, supervisor) {
     if (sessionType === 'companion' && companionCharName) {
         bypassManager.activateForMode('companion').catch(() => { });
     }
-    // 普通模式：orchestrator 已暂停，不再激活
-    // if (sessionType === 'normal') {
-    //   const orchestratorEnabled = configCenter.get<boolean>('bypass.orchestratorEnabled') ?? true;
-    //   if (orchestratorEnabled) {
-    //     bypassManager.activateAgent('orchestrator').catch(() => {});
-    //   }
-    // }
+    // 普通模式：按配置决定是否激活 orchestrator
+    if (sessionType === 'normal') {
+        const orchestratorEnabled = configCenter.get('bypass.orchestratorEnabled') ?? false;
+        if (orchestratorEnabled) {
+            bypassManager.activateAgent('orchestrator').catch(() => { });
+        }
+    }
     // ── Read 工具的图片处理器 — 将读到的图片注入 ImageStore ──
     const readTool = toolRegistry.get('read');
     if (readTool && typeof readTool.setImageHandler === 'function') {

package/dist/gateway/tui.js

@@ -970,7 +970,11 @@ export async function runTui(provider, sessionId, shouldContinue, maxTurns, maxC
     }
     // 启动所有渠道（每个渠道自行处理消息）
     await channelManager.startAll(agentFactory);
-    // 注册跨渠道发送工具（TUI 模式）
+    // ── 跨渠道消息发送工具 ────────────────────────────────────
+    //
+    // 在 channelManager.startAll() 之后注册，此时所有渠道已启动。
+    // 工具内通过 ChannelManager.get() 查找目标渠道并调用其 send()。
+    // 仅在本地 TUI 模式下注册——远程模式（remoteWs）下工具由服务端提供。
     if (agent) {
         const { MessageDispatcher, createSendChannelMessageTool } = await import('../channels/dispatcher.js');
         const dispatcher = new MessageDispatcher(channelManager);

package/dist/multimodal/index.js

@@ -78,7 +78,6 @@ export async function compressImageIfLarge(buf, mime) {
         return { buffer: buf, mime, compressed: false };
     let sharp;
     try {
-        // @ts-expect-error — sharp 0.35 types incompatible with pnpm exports
         sharp = (await import('sharp')).default;
     }
     catch {

package/dist/orchestrator/loop.js

@@ -93,7 +93,6 @@ function ansiBg(r, g, b) { return `\x1b[48;2;${r};${g};${b}m`; }
 export async function imageToAscii(imagePath, maxWidth = 60) {
     let sharp;
     try {
-        // @ts-expect-error — sharp 0.35 的 types 与 pnpm exports 解析不兼容
         sharp = (await import('sharp')).default;
     }
     catch {

package/dist/prompts/tools/framework-capabilities.md

@@ -144,7 +144,7 @@ tools: tool1,tool2
 
 | 需求 | 文件 | 写法 | 生效方式 |
 |------|------|------|----------|
-| 渠道（飞书/Lark 等） | `.agent/config.json` | 修改根对象的 `channels` 字段 | **需重启**：调用 `restart` 工具 |
+| 渠道（飞书/Lark/微信 ClawBot 等） | `.agent/config.json` | 修改根对象的 `channels` 字段 | **需重启**：调用 `restart` 工具 |
 | MCP Server | `.agent/mcp.json` | 添加或更新 server 定义 | **热加载**：保存后自动检测，无需重启 |
 | 工具包 | `.agent/tool-bundles.json` | 优先用 `list_bundles` / `activate_bundle` / `create_bundle` 等工具 | **热加载**：即时生效 |
 | Provider 元数据 | `.agent/providers.json` | 修改 provider 的 baseUrl、defaultModel、envKey、maxTokens | **热加载**：即时生效 |
@@ -159,7 +159,9 @@ tools: tool1,tool2
 
 ### 渠道配置
 
-渠道配置写在项目级 `.agent/config.json` 的 `channels` 字段中。配置飞书或 Lark 时，读取并合并完整 JSON，例如：
+渠道配置写在项目级 `.agent/config.json` 的 `channels` 字段中。配置飞书、Lark 或微信 ClawBot 时，读取并合并完整 JSON。
+
+**飞书/Lark 示例：**
 
 ```json
 {
@@ -176,6 +178,20 @@ tools: tool1,tool2
 }
 ```
 
+**微信 ClawBot 示例：**
+
+```json
+{
+  "channels": {
+    "clawbot": {
+      "enabled": true
+    }
+  }
+}
+```
+
+ClawBot 是微信官方 AI 助手连接插件，支持扫码授权。最简单的配置只需 `{ "enabled": true }`，首次启动自动生成二维码，扫码后即可使用。不需要 appId/appSecret。
+
 配置渠道时：
 1. 优先修改当前工作区的 `.agent/config.json`
 2. 先读取现有 JSON，保留 provider、session、safety 等已有配置

package/dist/runtime/defaults.js

@@ -135,7 +135,7 @@ export function getDefaultConfig() {
             defaultMode: 'normal',
         },
         bypass: {
-            orchestratorEnabled: true,
+            orchestratorEnabled: false,
         },
         diagnostics: {
             enabled: true,

package/dist/setup/config.js

@@ -21,8 +21,8 @@ import { getLocalProviderConfigLoader } from '../provider/local-config.js';
 import { DEFAULT_PROVIDERS } from '../provider/config.js';
 import { getDefaultConfig } from '../runtime/defaults.js';
 const DEFAULT_CONFIG = {
-    provider: 'anthropic',
-    model: DEFAULT_PROVIDERS.providers.anthropic?.defaultModel ?? 'unknown',
+    provider: '',
+    model: '',
     maxTurns: getDefaultConfig().session.maxTurns,
     maxContext: 200000,
     safety: {

package/dist/setup/wizard.js

@@ -143,12 +143,12 @@ export class SetupWizard {
     }
     /** Step 1: Provider */
     async stepProvider(defaultProvider) {
-        const initialValue = defaultProvider ?? 'anthropic';
+        const initialValue = defaultProvider || PROVIDERS[0].value;
         return p.select({
             message: '选择 AI 提供商',
             options: PROVIDERS.map(p => ({
                 ...p,
-                hint: p.value === initialValue ? `${p.hint} (当前)` : p.hint,
+                hint: p.value === defaultProvider ? `${p.hint} (当前)` : p.hint,
             })),
             initialValue,
         });

package/package.json

@@ -1,12 +1,21 @@
 {
   "name": "hyacinth-ai",
-  "version": "0.9.21",
+  "version": "0.9.22",
   "description": "Hyacinth 🪻 — multi-provider AI agent with tool system and context management",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
     "hyacinth": "dist/index.js"
   },
+  "scripts": {
+    "build": "tsc && node scripts/copy-prompts.cjs && node scripts/clean-tests.cjs && node scripts/clean-maps.cjs",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "start:win": "chcp 65001 > nul && node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "setup:llamacpp": "powershell -ExecutionPolicy Bypass -File scripts/setup-llamacpp.ps1"
+  },
   "keywords": [
     "ai",
     "agent",
@@ -19,6 +28,7 @@
   ],
   "author": "孑遗",
   "license": "MIT",
+  "packageManager": "pnpm@10.25.0",
   "dependencies": {
     "@anthropic-ai/sdk": "^0.98.0",
     "@clack/prompts": "^1.4.0",
@@ -52,14 +62,5 @@
     "typescript": "^6.0.3",
     "undici-types": "^7.24.6",
     "vitest": "^4.1.7"
-  },
-  "scripts": {
-    "build": "tsc && node scripts/copy-prompts.cjs && node scripts/clean-tests.cjs && node scripts/clean-maps.cjs",
-    "dev": "tsc --watch",
-    "start": "node dist/index.js",
-    "start:win": "chcp 65001 > nul && node dist/index.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "setup:llamacpp": "powershell -ExecutionPolicy Bypass -File scripts/setup-llamacpp.ps1"
   }
-}
+}