@zhin.js/core 1.0.32 → 1.0.34

package/src/ai/index.ts

@@ -9,12 +9,13 @@ export type {
   AIConfig,
   AIProvider,
   ProviderConfig,
+  ProviderCapabilities,
+  OllamaProviderConfig,
   ChatMessage,
   ChatCompletionRequest,
   ChatCompletionResponse,
   ChatCompletionChunk,
   ContentPart,
-  // 注意：ToolDefinition 已从 core/types.ts 导出，此处不重复导出
   ToolCall,
   MessageRole,
   AgentTool,
@@ -52,6 +53,14 @@ export type {
 export { ZhinAgent } from './zhin-agent.js';
 export type { ZhinAgentConfig, OnChunkCallback } from './zhin-agent.js';
 
+// ── ZhinAgent sub-modules (for advanced consumers) ──
+export { PERM_MAP, DEFAULT_CONFIG as ZHIN_AGENT_DEFAULT_CONFIG, SECTION_SEP } from './zhin-agent-config.js';
+export { checkExecPolicy, applyExecPolicyToTools, resolveExecAllowlist, EXEC_PRESETS } from './zhin-agent-exec-policy.js';
+export { collectRelevantTools, toAgentTool } from './zhin-agent-tool-collector.js';
+export { buildRichSystemPrompt, buildContextHint, buildEnhancedPersona, buildUserMessageWithHistory, contentToText } from './zhin-agent-prompt.js';
+export type { RichSystemPromptContext } from './zhin-agent-prompt.js';
+export { createChatHistoryTool, createUserProfileTool, createScheduleFollowUpTool, createSpawnTaskTool } from './zhin-agent-builtin-tools.js';
+
 // ── Conversation Memory ──
 export {
   ConversationMemory,
@@ -74,6 +83,15 @@ export type { RateLimitConfig, RateLimitResult } from './rate-limiter.js';
 export { FollowUpManager, AI_FOLLOWUP_MODEL } from './follow-up.js';
 export type { FollowUpRecord, FollowUpSender } from './follow-up.js';
 
+// ── Subagent ──
+export { SubagentManager } from './subagent.js';
+export type {
+  SubagentOrigin,
+  SubagentResultSender,
+  SpawnOptions,
+  SubagentManagerOptions,
+} from './subagent.js';
+
 // ── 持久化定时任务引擎 ──
 export {
   PersistentCronEngine,

package/src/ai/init.ts

@@ -29,7 +29,8 @@ import type { MessageDispatcherService } from '../built/dispatcher.js';
 import type { SkillFeature } from '../built/skill.js';
 import { AIService } from './service.js';
 import { ZhinAgent } from './zhin-agent.js';
-import { createBuiltinTools, discoverWorkspaceSkills, loadSoulPersona } from './builtin-tools.js';
+import { createBuiltinTools, discoverWorkspaceSkills, loadSoulPersona, loadAlwaysSkillsContent, buildSkillsSummaryXML } from './builtin-tools.js';
+import { resolveSkillInstructionMaxChars, DEFAULT_CONFIG } from './zhin-agent-config.js';
 import { loadBootstrapFiles, buildContextFiles, buildBootstrapContextSection, loadToolsGuide } from './bootstrap.js';
 import { triggerAIHook, createAIHookEvent } from './hooks.js';
 import { SessionManager, createDatabaseSessionManager } from './session.js';
@@ -44,6 +45,7 @@ import { AI_MESSAGE_MODEL, AI_SUMMARY_MODEL } from './conversation-memory.js';
 import { AI_USER_PROFILE_MODEL } from './user-profile.js';
 import { AI_FOLLOWUP_MODEL } from './follow-up.js';
 import { PersistentCronEngine, setCronManager, createCronTools } from './cron-engine.js';
+import { Scheduler, getScheduler, setScheduler } from '../scheduler/index.js';
 import { renderToPlainText, type OutputElement } from './output.js';
 import type { AIConfig, ContentPart } from './types.js';
 
@@ -204,6 +206,38 @@ export function initAIModule(): void {
       });
     });
 
+    // 子任务管理器：让 AI 可以 spawn 后台子 agent 异步执行复杂任务
+    agent.initSubagentManager(() => {
+      const modelName = provider.models[0] || '';
+      const fullConfig = { ...DEFAULT_CONFIG, ...agentConfig } as Required<import('./zhin-agent-config.js').ZhinAgentConfig>;
+      const zhinTools = createBuiltinTools({ skillInstructionMaxChars: resolveSkillInstructionMaxChars(fullConfig, modelName) });
+      return zhinTools.map(zt => {
+        const t = zt.toTool();
+        return {
+          name: t.name,
+          description: t.description,
+          parameters: t.parameters as any,
+          execute: t.execute as (args: Record<string, any>) => Promise<any>,
+          tags: t.tags,
+          keywords: t.keywords,
+        };
+      });
+    });
+    agent.setSubagentSender(async (origin, content) => {
+      const adapter = root.inject(origin.platform as any) as any;
+      if (!adapter || typeof adapter.sendMessage !== 'function') {
+        logger.warn(`[子任务] 找不到适配器: ${origin.platform}`);
+        return;
+      }
+      await adapter.sendMessage({
+        context: origin.platform,
+        bot: origin.botId,
+        id: origin.sceneId,
+        type: origin.sceneType as any,
+        content,
+      });
+    });
+
     // 持久化定时任务引擎：加载 data/cron-jobs.json，到点用 prompt 调用 Agent；并暴露给 AI 管理（list/add/remove/pause/resume）
     let cronEngine: PersistentCronEngine | null = null;
     const cronFeature = root.inject('cron' as any);
@@ -223,6 +257,26 @@ export function initAIModule(): void {
       setCronManager({ cronFeature, engine: cronEngine });
     }
 
+    // 统一调度器（at/every/cron + Heartbeat），持久化到 data/scheduler-jobs.json
+    const dataDir = path.join(process.cwd(), 'data');
+    const workspace = process.cwd();
+    const scheduler = new Scheduler({
+      storePath: path.join(dataDir, 'scheduler-jobs.json'),
+      workspace,
+      onJob: async (job) => {
+        if (!zhinAgentInstance) return;
+        await zhinAgentInstance.process(job.payload.message, {
+          platform: 'cron',
+          senderId: 'system',
+          sceneId: 'scheduler',
+        });
+      },
+      heartbeatEnabled: true,
+      heartbeatIntervalMs: 30 * 60 * 1000,
+    });
+    setScheduler(scheduler);
+    scheduler.start().catch((e) => logger.warn('Scheduler start failed: ' + (e as Error).message));
+
     logger.debug('ZhinAgent created');
     return () => {
       setCronManager(null);
@@ -230,6 +284,11 @@ export function initAIModule(): void {
         cronEngine.unload();
         cronEngine = null;
       }
+      const s = getScheduler();
+      if (s) {
+        s.stop();
+        setScheduler(null);
+      }
       agent.dispose();
       zhinAgentInstance = null;
     };
@@ -534,8 +593,11 @@ export function initAIModule(): void {
   useContext('ai', 'tool', (ai, toolService) => {
     if (!ai || !toolService) return;
 
-    // 注册工具
-    const builtinTools = createBuiltinTools();
+    const provider = ai.getProvider();
+    const agentCfg = ai.getAgentConfig();
+    const fullCfg = { ...DEFAULT_CONFIG, ...agentCfg } as Required<import('./zhin-agent-config.js').ZhinAgentConfig>;
+    const modelName = provider.models[0] || '';
+    const builtinTools = createBuiltinTools({ skillInstructionMaxChars: resolveSkillInstructionMaxChars(fullCfg, modelName) });
     const disposers: (() => void)[] = [];
     for (const tool of builtinTools) disposers.push(toolService.addTool(tool, root.name));
     const cronTools = createCronTools();
@@ -632,6 +694,19 @@ export function initAIModule(): void {
         logger.debug(`Bootstrap files not loaded: ${e.message}`);
       }
 
+      // ── 第三步：常驻技能正文 + 技能 XML 摘要注入 Agent ──
+      try {
+        const skillsForContext = await discoverWorkspaceSkills();
+        const alwaysContent = await loadAlwaysSkillsContent(skillsForContext);
+        const skillsXml = buildSkillsSummaryXML(skillsForContext);
+        if (zhinAgentInstance) {
+          zhinAgentInstance.setActiveSkillsContext(alwaysContent);
+          zhinAgentInstance.setSkillsSummaryXML(skillsXml);
+        }
+      } catch (e: any) {
+        logger.debug(`Skills context not set: ${e.message}`);
+      }
+
       // 触发 agent:bootstrap Hook
       const skillFeature2 = (root as any).inject?.('skill') as SkillFeature | undefined;
       await triggerAIHook(createAIHookEvent('agent', 'bootstrap', undefined, {
@@ -650,6 +725,13 @@ export function initAIModule(): void {
           skillReloadDebounce = null;
           try {
             const count = await syncWorkspaceSkills();
+            const skillsForContext = await discoverWorkspaceSkills();
+            const alwaysContent = await loadAlwaysSkillsContent(skillsForContext);
+            const skillsXml = buildSkillsSummaryXML(skillsForContext);
+            if (zhinAgentInstance) {
+              zhinAgentInstance.setActiveSkillsContext(alwaysContent);
+              zhinAgentInstance.setSkillsSummaryXML(skillsXml);
+            }
             await triggerAIHook(createAIHookEvent('agent', 'skills-reloaded', undefined, { skillCount: count }));
             if (count >= 0) logger.info(`[技能热重载] 已更新，当前工作区技能数: ${count}`);
           } catch (e: any) {

package/src/ai/providers/anthropic.ts

@@ -178,12 +178,15 @@ export class AnthropicProvider extends BaseProvider {
     'claude-3-sonnet-20240229',
     'claude-3-haiku-20240307',
   ];
+  contextWindow: number;
+  capabilities = { vision: true, streaming: true, toolCalling: true, thinking: false };
 
   private baseUrl: string;
   private anthropicVersion: string;
 
   constructor(config: AnthropicConfig = {}) {
     super(config);
+    this.contextWindow = config.contextWindow ?? 200000;
     this.baseUrl = config.baseUrl || 'https://api.anthropic.com';
     this.anthropicVersion = config.anthropicVersion || '2023-06-01';
   }

package/src/ai/providers/ollama.ts

@@ -19,6 +19,8 @@ const logger = new Logger(null, 'Ollama');
 export interface OllamaConfig extends ProviderConfig {
   host?: string;
   models?: string[];
+  /** Ollama 上下文窗口大小（token 数），默认 32768。影响多轮对话和技能指令的保持能力 */
+  num_ctx?: number;
 }
 
 /**
@@ -81,13 +83,17 @@ function toOllamaTools(tools?: ToolDefinition[]): any[] | undefined {
 export class OllamaProvider extends BaseProvider {
   name = 'ollama';
   models: string[];
+  contextWindow: number;
+  capabilities = { vision: true, streaming: true, toolCalling: true, thinking: true };
 
   private host: string;
+  private numCtx: number;
 
   constructor(config: OllamaConfig = {}) {
     super(config);
     this.host = config.host || config.baseUrl || 'http://localhost:11434';
-    // 使用配置中的模型列表，如果没有则使用默认列表
+    this.numCtx = config.contextWindow ?? config.num_ctx ?? 32768;
+    this.contextWindow = this.numCtx;
     this.models = config.models?.length ? config.models : [
       'llama3.3',
       'llama3.2',
@@ -113,7 +119,9 @@ export class OllamaProvider extends BaseProvider {
       model: request.model,
       messages,
       stream: false,
-      options: {},
+      options: {
+        num_ctx: this.numCtx,
+      },
     };
 
     // think 参数：控制 qwen3 等模型的思考模式
@@ -186,7 +194,9 @@ export class OllamaProvider extends BaseProvider {
       model: request.model,
       messages,
       stream: true,
-      options: {},
+      options: {
+        num_ctx: this.numCtx,
+      },
     };
 
     if (request.think !== undefined) {

package/src/ai/providers/openai.ts

@@ -28,11 +28,14 @@ export class OpenAIProvider extends BaseProvider {
     'o1-preview',
     'o3-mini',
   ];
+  contextWindow: number;
+  capabilities = { vision: true, streaming: true, toolCalling: true, thinking: false };
 
   private baseUrl: string;
 
   constructor(config: OpenAIConfig = {}) {
     super(config);
+    this.contextWindow = config.contextWindow ?? 128000;
     this.baseUrl = config.baseUrl || 'https://api.openai.com/v1';
     
     if (config.organization) {

package/src/ai/service.ts

@@ -267,6 +267,14 @@ ${preExecutedData ? `\n已自动获取的数据：${preExecutedData}\n` : ''}
   }
   listProviders(): string[] { return Array.from(this.providers.keys()); }
 
+  getProviderCapabilities(name?: string): { contextWindow?: number; capabilities?: import('./types.js').ProviderCapabilities } {
+    const provider = this.getProvider(name);
+    return {
+      contextWindow: provider.contextWindow,
+      capabilities: provider.capabilities,
+    };
+  }
+
   async listModels(providerName?: string): Promise<{ provider: string; models: string[] }[]> {
     const result: { provider: string; models: string[] }[] = [];
     if (providerName) {

package/src/ai/subagent.ts

@@ -0,0 +1,209 @@
+/**
+ * SubagentManager — 后台子任务执行管理器
+ *
+ * 职责：
+ *   1. 接收主 agent 发起的 spawn 请求，创建后台子 agent
+ *   2. 为子 agent 配备受限工具集（文件/Shell/网络，不含消息/spawn/技能）
+ *   3. 管理子 agent 生命周期（运行跟踪、完成/失败回告）
+ *   4. 完成后将结果投递回主流程，由主 agent 摘要后发送到原始频道
+ */
+
+import { randomUUID } from 'crypto';
+import { Logger } from '@zhin.js/logger';
+import type { AIProvider, AgentTool } from './types.js';
+import { createAgent } from './agent.js';
+import type { ZhinAgentConfig } from './zhin-agent-config.js';
+import { applyExecPolicyToTools } from './zhin-agent-exec-policy.js';
+
+const logger = new Logger(null, 'Subagent');
+
+// ============================================================================
+// 类型
+// ============================================================================
+
+export interface SubagentOrigin {
+  platform: string;
+  botId: string;
+  sceneId: string;
+  senderId: string;
+  sceneType: string;
+}
+
+export interface SpawnOptions {
+  task: string;
+  label?: string;
+  origin: SubagentOrigin;
+}
+
+export type SubagentResultSender = (origin: SubagentOrigin, content: string) => Promise<void>;
+
+export interface SubagentManagerOptions {
+  provider: AIProvider;
+  workspace: string;
+  createTools: () => AgentTool[];
+  maxIterations?: number;
+  /** Exec policy config to enforce on subagent bash tools */
+  execPolicyConfig?: Required<ZhinAgentConfig>;
+}
+
+// ============================================================================
+// 子 agent 允许使用的工具名单
+// ============================================================================
+
+const SUBAGENT_ALLOWED_TOOLS = new Set([
+  'read_file',
+  'write_file',
+  'edit_file',
+  'list_dir',
+  'glob',
+  'grep',
+  'bash',
+  'web_search',
+  'web_fetch',
+]);
+
+// ============================================================================
+// SubagentManager
+// ============================================================================
+
+export class SubagentManager {
+  private provider: AIProvider;
+  private workspace: string;
+  private createTools: () => AgentTool[];
+  private maxIterations: number;
+  private execPolicyConfig: Required<ZhinAgentConfig> | null;
+  private runningTasks: Map<string, AbortController> = new Map();
+  private resultSender: SubagentResultSender | null = null;
+
+  constructor(options: SubagentManagerOptions) {
+    this.provider = options.provider;
+    this.workspace = options.workspace;
+    this.createTools = options.createTools;
+    this.maxIterations = options.maxIterations ?? 15;
+    this.execPolicyConfig = options.execPolicyConfig ?? null;
+  }
+
+  setSender(sender: SubagentResultSender): void {
+    this.resultSender = sender;
+  }
+
+  async spawn(options: SpawnOptions): Promise<string> {
+    const taskId = randomUUID().slice(0, 8);
+    const displayLabel =
+      options.label ||
+      options.task.slice(0, 30) + (options.task.length > 30 ? '...' : '');
+
+    const abortController = new AbortController();
+    this.runningTasks.set(taskId, abortController);
+
+    this.runSubagent(taskId, options.task, displayLabel, options.origin)
+      .catch((error) => {
+        logger.error({ error, taskId }, 'Subagent failed');
+      })
+      .finally(() => {
+        this.runningTasks.delete(taskId);
+      });
+
+    logger.info({ taskId, label: displayLabel }, 'Spawned subagent');
+    return `子任务 [${displayLabel}] 已启动 (id: ${taskId})，完成后会自动通知你。`;
+  }
+
+  getRunningCount(): number {
+    return this.runningTasks.size;
+  }
+
+  // ── 内部方法 ──────────────────────────────────────────────────────
+
+  private async runSubagent(
+    taskId: string,
+    task: string,
+    label: string,
+    origin: SubagentOrigin,
+  ): Promise<void> {
+    logger.info({ taskId, label }, 'Subagent starting task');
+
+    try {
+      const allTools = this.createTools();
+      let tools = allTools.filter(t => SUBAGENT_ALLOWED_TOOLS.has(t.name));
+      if (this.execPolicyConfig) {
+        tools = applyExecPolicyToTools(this.execPolicyConfig, tools);
+      }
+
+      const systemPrompt = this.buildSubagentPrompt(task);
+      const agent = createAgent(this.provider, {
+        systemPrompt,
+        tools,
+        maxIterations: this.maxIterations,
+      });
+
+      const result = await agent.run(task);
+      const finalResult = result.content || '任务已完成，但未生成最终响应。';
+
+      logger.info({ taskId }, 'Subagent completed successfully');
+      await this.announceResult(taskId, label, task, finalResult, origin, 'ok');
+    } catch (error) {
+      const errorMsg = `Error: ${error}`;
+      logger.error({ taskId, error }, 'Subagent failed');
+      await this.announceResult(taskId, label, task, errorMsg, origin, 'error');
+    }
+  }
+
+  private async announceResult(
+    taskId: string,
+    label: string,
+    task: string,
+    result: string,
+    origin: SubagentOrigin,
+    status: 'ok' | 'error',
+  ): Promise<void> {
+    if (!this.resultSender) {
+      logger.warn({ taskId }, 'No result sender configured, discarding subagent result');
+      return;
+    }
+
+    const statusText = status === 'ok' ? '已完成' : '执行失败';
+    const announceContent = `[后台任务 '${label}' ${statusText}]\n\n任务: ${task}\n\n结果:\n${result}`;
+
+    try {
+      await this.resultSender(origin, announceContent);
+      logger.debug({ taskId, origin }, 'Subagent announced result');
+    } catch (e) {
+      logger.error({ taskId, error: e }, 'Failed to announce subagent result');
+    }
+  }
+
+  private buildSubagentPrompt(task: string): string {
+    return `# 子任务 Agent
+
+你是一个被主 agent 派生出来执行特定任务的子 agent。
+
+## 你的任务
+${task}
+
+## 规则
+1. 专注完成分配的任务，不做其他事情
+2. 你的最终回复会被报告给主 agent，并转达给用户
+3. 不要发起对话或承担额外任务
+4. 回复要简洁但信息充分
+
+## 你可以做的
+- 读写工作区内的文件
+- 执行 Shell 命令
+- 搜索和抓取网页
+- 彻底完成任务
+
+## 你不能做的
+- 直接向用户发送消息
+- 派生其他子任务
+- 访问主 agent 的对话历史
+
+## 工作区
+你的工作区路径: ${this.workspace}
+
+完成任务后，请提供清晰的发现或操作摘要。`;
+  }
+
+  dispose(): void {
+    this.runningTasks.clear();
+  }
+}

package/src/ai/types.ts

@@ -128,6 +128,14 @@ export interface ChatCompletionChunkChoice {
 // Provider 类型
 // ============================================================================
 
+/** Provider 能力声明 */
+export interface ProviderCapabilities {
+  vision?: boolean;
+  streaming?: boolean;
+  toolCalling?: boolean;
+  thinking?: boolean;
+}
+
 /** Provider 配置 */
 export interface ProviderConfig {
   apiKey?: string;
@@ -136,6 +144,10 @@ export interface ProviderConfig {
   timeout?: number;
   maxRetries?: number;
   headers?: Record<string, string>;
+  /** 上下文窗口大小（token 数），各 Provider 映射到自身参数 */
+  contextWindow?: number;
+  /** Provider 能力声明 */
+  capabilities?: ProviderCapabilities;
 }
 
 /** Provider 接口 */
@@ -154,6 +166,12 @@ export interface AIProvider {
   
   /** 检查连接 */
   healthCheck?(): Promise<boolean>;
+
+  /** 上下文窗口大小（token 数），由 Provider 实现暴露 */
+  contextWindow?: number;
+
+  /** Provider 能力声明 */
+  capabilities?: ProviderCapabilities;
 }
 
 // ============================================================================
@@ -241,6 +259,13 @@ export interface Session {
 // AI Service 配置
 // ============================================================================
 
+/** Ollama-specific fields for AIConfig typing (mirrors OllamaConfig) */
+export interface OllamaProviderConfig extends ProviderConfig {
+  host?: string;
+  models?: string[];
+  num_ctx?: number;
+}
+
 /** AI 服务配置 */
 export interface AIConfig {
   enabled?: boolean;
@@ -251,7 +276,7 @@ export interface AIConfig {
     deepseek?: ProviderConfig;
     moonshot?: ProviderConfig;
     zhipu?: ProviderConfig;
-    ollama?: ProviderConfig & { host?: string; models?: string[] };
+    ollama?: OllamaProviderConfig;
     custom?: ProviderConfig[];
   };
   sessions?: {
@@ -284,7 +309,9 @@ export interface AIConfig {
     allowedTools?: string[];
     /** bash 执行策略：deny=禁止执行，allowlist=仅允许列表内命令，full=不限制 */
     execSecurity?: 'deny' | 'allowlist' | 'full';
-    /** allowlist 模式下允许的命令（支持正则字符串，如 "^ls "、"^cat "） */
+    /** 预设命令白名单模式：readonly / network / development / custom（默认 custom，使用自定义 execAllowlist） */
+    execPreset?: 'readonly' | 'network' | 'development' | 'custom';
+    /** allowlist 模式下允许的命令（支持正则字符串，如 "^ls "、"^cat "），与 preset 合并 */
     execAllowlist?: string[];
     /** allowlist 未命中时：true=需审批（当前实现为拒绝并提示），false=直接拒绝 */
     execAsk?: boolean;