@zhin.js/agent 0.1.30 → 0.1.32

package/README.md

@@ -6,19 +6,20 @@ Zhin AI Agent 组合层：在 `@zhin.js/core` 的类型与 Provider 之上，提
 
 ## 功能特性
 
-- 🤖 **Agent 循环**：`Agent` / `createAgent`，支持工具调用、迭代与事件
+- 🤖 **agentLoop 统一路径**：ZhinAgent、Subagent、Deferred Worker、AIService 均经 `agentLoop`（legacy `Agent.run` 仅保留在 `@zhin.js/ai` 供单测）
 - 📝 **会话管理**：`SessionManager`、内存/数据库会话、`SessionManager.generateId`
 - 🧠 **ZhinAgent**：与 Zhin 消息流集成的智能体（SOUL/TOOLS/AGENTS、工具收集、执行策略）
-- 🔍 **模型自动发现**：通过 `@zhin.js/ai` 的 `ModelRegistry`（本包 re-export AI 原语，不单独导出 Registry）
-- 🔄 **模型自动降级**：首选模型失败时自动切换到次优模型，支持 Chat / Vision / Agent 三条路径
+- 🔍 **模型自动发现**：`ModelRegistry` 调用 `listModels()`（OpenAI 兼容 `/v1/models`、Ollama `/api/tags`）；结果写入 `provider.models` 并供 `getModel()` 校验；yaml 显式 `models` 时以配置为准
+- 🔄 **模型自动降级**：首选模型失败时按 `resolveModelCandidates` 候选链 fallback（文本 / 多模态 / standalone 均走 agentLoop）
 - 🛡️ **6 层 Bash 安全**：`ExecPolicy` 纵深防御（危险黑名单、环境变量剥离、wrapper 剥离、复合命令拆分、只读放行、交互式审批）
 - 📂 **文件访问安全**：`FilePolicy` 路径检查、设备路径拦截、命令读写分类
 - 📋 **精简系统提示词**：`PromptBuilder` 组装 Context、Style、Tools、Safety，并按需注入 Platform、Skills、Memory、Bootstrap
 - 🔌 **框架挂载**：`initAgentModule()` 注册 `ctx.ai`、`ctx.agent`、定时任务、DB 模型等
-- 📦 **上下文与记忆**：`ContextManager`、`ConversationMemory`、`UserProfileStore`
+- 📦 **上下文与记忆**：`ContextRepository`（`agent_messages`）、`AgentSessionStore`、`ImTranscriptStore`（`im_transcripts` + `chat_history`）；辅助：`ContextManager`、`ConversationMemory`、`UserProfileStore`
 - ⏰ **跟进与定时**：`FollowUpManager`、`PersistentCronEngine`、cron 工具
-- 🔧 **内置工具**：bash、read_file、write_file、ask_user、web_search、chat_history 等
-- 📐 **会话压缩**：`compactSession`、token 估算、总结与裁剪
+- 🔧 **内置工具**：bash、read_file、write_file、ask_user、web_search、`chat_history`（按关键词/最近条数查 `im_transcripts`）等
+- 📐 **Compaction（ADR 0010）**：生产 `agentLoop` 接线 L1 micro + L2 LLM；IM `/compact`；yaml `ai.agent.compaction`
+- 🌳 **会话树**：`parent_id` + `active_leaf`；IM `/tree`、`/reset`；branch summarization；Console `GET/POST /api/agent/sessions/...`
 - 🪝 **Hook 系统**：`registerAIHook`、`triggerAIHook` 等
 
 ## 依赖关系
@@ -44,8 +45,6 @@ npm install zhin.js
 import {
   initAgentModule,
   ZhinAgent,
-  Agent,
-  createAgent,
   AIService,
   SessionManager,
   registerAIHook,
@@ -64,16 +63,19 @@ useContext('ai', async (ai) => {
 仅在需要单独集成 Agent 能力时使用：
 
 ```javascript
-import { initAgentModule, createAgent, AIService } from '@zhin.js/agent'
+import { initAgentModule, AIService } from '@zhin.js/agent'
 import { OllamaProvider } from '@zhin.js/core'
 
-// 初始化（需先有 DatabaseFeature 等）
 initAgentModule()
 
-// 低层 Agent
-const provider = new OllamaProvider({ baseUrl: 'http://localhost:11434' })
-const agent = createAgent(provider, { tools: [], systemPrompt: '你是一个助手' })
-const result = await agent.run('你好')
+// 程序化 Agent（agentLoop 隔离 context）
+useContext('ai', async (ai) => {
+  const result = await ai.runAgent('你好', {
+    provider: 'ollama',
+    systemPrompt: '你是一个助手',
+  })
+  console.log(result.content)
+})
 ```
 
 ## 核心导出
@@ -81,13 +83,13 @@ const result = await agent.run('你好')
 | 类别 | 导出 |
 |------|------|
 | 初始化 | `initAgentModule` |
-| Agent | `Agent`, `createAgent`, `formatToolTitle` |
+| Agent | `ServiceAgent`、`CreateServiceAgentOptions`（`AIService.createAgent`）；legacy `Agent` / `createAgent` re-export 自 `@zhin.js/ai` |
 | Model harness | `MODEL_HARNESS_DEFAULTS`, `resolveModelHarness`, `mergeModelHarnessValues` |
 | 服务与会话 | `AIService`, `SessionManager`, `MemorySessionManager`, `DatabaseSessionManager`, `createMemorySessionManager`, `createDatabaseSessionManager` |
 | 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` |
+| 上下文与记忆 | `ContextRepository`, `AgentSessionStore`, `ImTranscriptStore`（经 ZhinAgent 注入）；`ContextManager`, `ConversationMemory`, `UserProfileStore` |
 | 跟进与定时 | `FollowUpManager`, `PersistentCronEngine`, `createCronTools`, `setCronManager`, `getCronManager` |
 | 压缩与 Bootstrap | `compactSession`, `estimateTokens`, `loadBootstrapFiles`, `loadSoulPersona`, `loadToolsGuide`, `loadAgentsMemory` |
 | Hook | `registerAIHook`, `unregisterAIHook`, `triggerAIHook`, `createAIHookEvent` |
@@ -118,7 +120,7 @@ declare module '@zhin.js/core' {
 
 | Context | 用途 |
 |---------|------|
-| `ctx.ai` | 业务侧 AI 服务：会话、`createAgent` / `runAgent`、全局 ZhinAgent |
+| `ctx.ai` | 业务侧 AI 服务：会话、`createAgent`（→ `ServiceAgent`）/ `runAgent`、全局 ZhinAgent |
 | `ctx.agent` | 扩展编排资源：`orchestrator.addTool`、`addSkill`、`addMcp` 等；内置注册走 `root.inject('agent')` |
 
 主包 `zhin.js` 的 `Plugin.Contexts` 类型已包含上述两项。
@@ -127,7 +129,7 @@ declare module '@zhin.js/core' {
 
 默认**不**注册 `@modelcontextprotocol/server-memory`；设 `ai.memoryMcp: true` 启用（`data/knowledge-graph.jsonl`）。另可通过 `ai.mcpServers`（或 `ctx.agent.addMcp`）注册更多 Server；每次 AI 回合前懒连接，`mcp_{server}_{tool}` 并入 ZhinAgent 工具池。需可选安装 `@modelcontextprotocol/sdk`（peer dependency）。
 
-**记忆**：内置 `read_memory` / `write_memory` 已移除，请使用 `mcp_memory_read_graph`、`mcp_memory_create_entities` 等。工作区 `AGENTS.md` 仍由 bootstrap 注入。
+**记忆**：默认 **文件三层**（`ai.memory` → `data/memory/`）；内置 `read_memory` / `write_memory` 已移除。`ai.memoryMcp: true` 时另注册 MCP 图谱（弃用路径）。工作区 `AGENTS.md` / `TOOLS.md` 由 bootstrap 注入。
 
 ```yaml
 ai:
@@ -155,23 +157,20 @@ ai:
 
 ### 2. 用 AIService 创建多个不同配置的 Agent
 
-`ctx.ai`（AIService）可以按需创建**多个互不共享状态的 Agent**，每个可指定不同 provider、model、systemPrompt、tools：
+`ctx.ai`（AIService）可以按需创建**多个互不共享状态的 Agent**（`ServiceAgent`），每个可指定不同 provider、model、systemPrompt、tools；底层均为 **`runAgentLoopStandaloneTurn`**：
 
 ```javascript
 import { useContext } from 'zhin.js'
 
 useContext('ai', async (ai) => {
-  // 专用「代码助手」Agent
   const codeAgent = ai.createAgent({
     provider: 'openai',
     model: 'gpt-4o',
     systemPrompt: '你只负责代码审查与建议，不闲聊。',
     useBuiltinTools: true,
-    tools: [/* 可选：额外工具 */],
   })
   const codeResult = await codeAgent.run('审查这段 TypeScript 的类型安全')
 
-  // 专用「翻译」Agent，不用内置工具
   const translateAgent = ai.createAgent({
     provider: 'ollama',
     model: 'qwen2.5',
@@ -201,7 +200,7 @@ useContext('ai', async (ai) => {
 
 ### 4. 多 Agent 协作/编排（由 zhin.js 层实现）
 
-本包只提供基础能力：`createAgent`、`ZhinAgent`、`ai.createAgent` 等。**多 Agent 串联/并联编排**（例如 A 的输出作为 B 的输入、按条件路由到不同专业 Agent）以及**按 bot / 按群组配置多个 ZhinAgent** 的调度与路由，将在 **zhin.js 主包**实现；插件侧通过 zhin.js 暴露的 API 使用即可，无需在业务里手写多实例维护与路由逻辑。
+本包只提供基础能力：`ZhinAgent`、`ai.createAgent`（`ServiceAgent`）、`ai.runAgent` 等。**多 Agent 串联/并联编排**（例如 A 的输出作为 B 的输入、按条件路由到不同专业 Agent）在 **zhin.js 主包** `runPipeline` / `runParallel` / `route` 实现；插件侧通过 zhin.js 暴露的 API 使用即可。
 
 ## 工具命名策略
 
@@ -209,6 +208,60 @@ useContext('ai', async (ai) => {
 - 非保留工具同名时采用 **后注册覆盖前注册**。
 - 冲突统一以 warn 记录：包含 `name`、`source`、`action`（`ignored`/`overridden`）。
 
+## Provider 与模型列表
+
+`AIService` 构造时：
+
+1. 按 `ai.providers.<别名>` 实例化 Provider（须配置 `api`，如 `openai-completions`）。
+2. `registerLlmApiFromProviders`：**未写 `models` 的 provider** 在 ApiRegistry 注册为空白名单，由后台 `ModelRegistry.discover()` 填充 `provider.models`；**写了 `models`** 则用 yaml 白名单。
+3. `createZhinAgent` 启动时 `loadCache()` 先恢复上次发现结果，再异步刷新 `/v1/models`。
+
+`agents.<name>.model`（如 `mimo-v2.5-pro`）须在发现列表中，或在中转 API 的 `/v1/models` 响应里出现；无需为每个模型手写 yaml，除非要锁定白名单。
+
+```yaml
+ai:
+  providers:
+    openai-main:
+      api: openai-completions
+      baseUrl: ${OPENAI_BASE_URL}
+      apiKey: ${OPENAI_API_KEY}
+      # models 省略 → 自动 GET /v1/models
+    cloudflare-flash:
+      api: cloudflare-workers-ai
+      models: ["@cf/zai-org/glm-4.7-flash"]  # 显式列表
+  agents:
+    zhin:
+      provider: openai-main
+      model: mimo-v2.5-pro
+```
+
+## Provider 与模型列表
+
+`AIService` 构造时：
+
+1. 按 `ai.providers.<别名>` 实例化 Provider（须配置 `api`，如 `openai-completions`）。
+2. `registerLlmApiFromProviders`：**未写 `models` 的 provider** 在 ApiRegistry 注册为空白名单，由后台 `ModelRegistry.discover()` 填充 `provider.models`；**写了 `models`** 则用 yaml 白名单。
+3. `createZhinAgent` 启动时 `loadCache()` 先恢复上次发现结果，再异步刷新 `/v1/models`。
+
+`agents.<name>.model`（如 `mimo-v2.5-pro`）须在发现列表中，或在中转 API 的 `/v1/models` 响应里出现；无需为每个模型手写 yaml，除非要锁定白名单。
+
+```yaml
+ai:
+  providers:
+    openai-main:
+      api: openai-completions
+      baseUrl: ${OPENAI_BASE_URL}
+      apiKey: ${OPENAI_API_KEY}
+      # models 省略 → 自动 GET /v1/models
+    cloudflare-flash:
+      api: cloudflare-workers-ai
+      models: ["@cf/zai-org/glm-4.7-flash"]  # 显式列表
+  agents:
+    zhin:
+      provider: openai-main
+      model: mimo-v2.5-pro
+```
+
 ## Model harness
 
 按 provider / model 覆盖 Agent 循环默认参数（当前主要为 **`maxIterations`**）。
@@ -237,6 +290,18 @@ ai:
 
 增补内置默认值：在 `model-harness.ts` 增加 `ModelHarnessRow` 并附测试；YAML 只做覆盖，不替代 TS 约定层。
 
+## IM 管理命令
+
+由 `register-management-tools.ts` / `register-introspection-commands.ts` 注册（master / 有权限用户）：
+
+| 类别 | 命令 |
+|------|------|
+| 会话 | `/compact` · `/tree` · `/tree N` · `/reset` |
+| 运维 | `/models` · `/health` |
+| 内省 | `/cmd` · `/bots` · `/bindings` · `/tools` · `/mcp` |
+
+zhin-package CLI：`zhin packages`（`basic/cli`）。详见 [ADR 0010](../../docs/adr/0010-pi-coding-agent-harness-alignment.md)。
+
 ## 开发
 
 ### 项目结构
@@ -267,7 +332,7 @@ src/
 │   ├── config.ts
 │   ├── prompt.ts
 │   ├── tool-runtime.ts              # 运行时工具收集与执行路径规划
-│   └── context-tools.ts             # chat_history, user_profile, spawn_task
+│   └── builtin-tools.ts             # chat_history（im_transcripts）, user_profile, spawn_task
 │
 ├── discovery/                       # ★ 文件化资源发现
 │   ├── index.ts

package/lib/builtin/memory-search-tool.d.ts

@@ -0,0 +1,2 @@
+export declare function createMemorySearchTool(): import("@zhin.js/core").Tool<Record<string, any>>;
+//# sourceMappingURL=memory-search-tool.d.ts.map

package/lib/builtin/memory-search-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-search-tool.d.ts","sourceRoot":"","sources":["../../src/builtin/memory-search-tool.ts"],"names":[],"mappings":"AAoEA,wBAAgB,sBAAsB,sDAErC"}

package/lib/builtin/memory-search-tool.js

@@ -0,0 +1,61 @@
+import { resolveIMSessionIdFromToolContext } from '@zhin.js/ai';
+import { parseMemoryTags } from '@zhin.js/ai';
+import { BuiltinBaseTool } from './builtin-base-tool.js';
+import { getMemoryEntryRepository } from '../memory-entry-registry.js';
+const PARAMS = {
+    type: 'object',
+    properties: {
+        query: { type: 'string', description: '检索关键词或短语' },
+        scope: {
+            type: 'string',
+            enum: ['global', 'platform', 'session', 'user'],
+            description: '可选：限定记忆范围',
+        },
+        limit: { type: 'number', description: '最多返回条数（默认 5）' },
+    },
+    required: ['query'],
+};
+function sessionScopeKey(ctx) {
+    return resolveIMSessionIdFromToolContext({
+        platform: ctx.platform || '',
+        botId: ctx.botId || '',
+        scope: ctx.scope,
+        sceneId: ctx.sceneId || '',
+        senderId: ctx.senderId || '',
+    });
+}
+class MemorySearchTool extends BuiltinBaseTool {
+    name = 'memory_search';
+    description = '在语义记忆库中检索与 query 相关的事实条目（memory_entries）。';
+    parameters = PARAMS;
+    keywords = ['memory', 'recall', 'remember', '记忆', '回忆'];
+    async run(args, context) {
+        const repo = getMemoryEntryRepository();
+        if (!repo)
+            return '语义记忆未启用（ai.memory.semantic.enabled）或未初始化数据库。';
+        const query = String(args.query ?? '').trim();
+        if (!query)
+            return '请提供 query';
+        const scope = typeof args.scope === 'string' ? args.scope : undefined;
+        const limit = typeof args.limit === 'number' ? args.limit : 5;
+        const scopeKey = scope === 'session' && context ? sessionScopeKey(context) : undefined;
+        const hits = await repo.search({
+            query,
+            scope: scope,
+            scope_key: scopeKey,
+            limit,
+        });
+        if (!hits.length)
+            return `未找到与 "${query}" 相关的记忆条目。`;
+        const lines = hits.map((e) => {
+            const tags = parseMemoryTags(e.tags);
+            return `- [${e.scope}${e.scope_key ? `:${e.scope_key}` : ''}] ${e.key}=${e.content}`
+                + (tags.length ? ` (tags: ${tags.join(', ')})` : '');
+        });
+        return `找到 ${hits.length} 条记忆：\n${lines.join('\n')}`;
+    }
+}
+export function createMemorySearchTool() {
+    return new MemorySearchTool().toTool();
+}
+//# sourceMappingURL=memory-search-tool.js.map

package/lib/builtin/memory-search-tool.js.map

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

package/lib/builtin/memory-upsert-tool.d.ts

@@ -0,0 +1,2 @@
+export declare function createMemoryUpsertTool(): import("@zhin.js/core").Tool<Record<string, any>>;
+//# sourceMappingURL=memory-upsert-tool.d.ts.map

package/lib/builtin/memory-upsert-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-upsert-tool.d.ts","sourceRoot":"","sources":["../../src/builtin/memory-upsert-tool.ts"],"names":[],"mappings":"AAkFA,wBAAgB,sBAAsB,sDAErC"}

package/lib/builtin/memory-upsert-tool.js

@@ -0,0 +1,75 @@
+import { resolveIMSessionIdFromToolContext } from '@zhin.js/ai';
+import { BuiltinBaseTool } from './builtin-base-tool.js';
+import { getMemoryEntryRepository } from '../memory-entry-registry.js';
+const PARAMS = {
+    type: 'object',
+    properties: {
+        key: { type: 'string', description: '记忆键（如 capability:hard_orchestration_v1）' },
+        content: { type: 'string', description: '记忆内容（简短事实陈述）' },
+        scope: {
+            type: 'string',
+            enum: ['global', 'platform', 'session', 'user'],
+            description: '范围，默认 global',
+        },
+        tags: {
+            type: 'array',
+            items: { type: 'string' },
+            description: '可选标签',
+        },
+        source: { type: 'string', description: '来源说明（如 skill:memory-consolidate）' },
+        confidence: { type: 'number', description: '置信度 0–1，默认 1' },
+    },
+    required: ['key', 'content'],
+};
+function sessionScopeKey(ctx) {
+    return resolveIMSessionIdFromToolContext({
+        platform: ctx.platform || '',
+        botId: ctx.botId || '',
+        scope: ctx.scope,
+        sceneId: ctx.sceneId || '',
+        senderId: ctx.senderId || '',
+    });
+}
+class MemoryUpsertTool extends BuiltinBaseTool {
+    name = 'memory_upsert';
+    description = '写入或更新一条语义记忆（memory_entries），供 memory_search 召回。';
+    parameters = PARAMS;
+    keywords = ['memory', 'remember', 'store', '记忆', '记住'];
+    async run(args, context) {
+        const repo = getMemoryEntryRepository();
+        if (!repo)
+            return '语义记忆未启用（ai.memory.semantic.enabled）或未初始化数据库。';
+        const key = String(args.key ?? '').trim();
+        const content = String(args.content ?? '').trim();
+        if (!key || !content)
+            return '请提供 key 与 content';
+        const scope = (typeof args.scope === 'string' ? args.scope : 'global');
+        let scopeKey = '';
+        if (scope === 'session' && context) {
+            scopeKey = sessionScopeKey(context);
+        }
+        else if (scope === 'platform' && context?.platform) {
+            scopeKey = context.platform;
+        }
+        else if (scope === 'user' && context?.senderId) {
+            scopeKey = context.senderId;
+        }
+        const tags = Array.isArray(args.tags) ? args.tags.map(String) : undefined;
+        const source = typeof args.source === 'string' ? args.source : 'tool:memory_upsert';
+        const confidence = typeof args.confidence === 'number' ? args.confidence : 1;
+        const record = await repo.upsert({
+            scope,
+            scope_key: scopeKey,
+            key,
+            content,
+            tags,
+            source,
+            confidence,
+        });
+        return `已写入记忆 ${record.id}: [${record.scope}] ${record.key}=${record.content}`;
+    }
+}
+export function createMemoryUpsertTool() {
+    return new MemoryUpsertTool().toTool();
+}
+//# sourceMappingURL=memory-upsert-tool.js.map

package/lib/builtin/memory-upsert-tool.js.map

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

package/lib/builtin/orchestration-tools.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Project director orchestration tools — Agent Mesh hard orchestration v1.
+ */
+import type { AgentTool, ToolContext } from '@zhin.js/core';
+export declare function createOrchestrationTools(context: ToolContext): AgentTool[];
+export declare const ORCHESTRATION_TOOL_NAMES: readonly ["orchestration_start", "orchestration_add_task", "orchestration_status", "orchestration_complete", "orchestration_retry_task", "orchestration_skip_task", "orchestration_patch_state"];
+//# sourceMappingURL=orchestration-tools.d.ts.map

package/lib/builtin/orchestration-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestration-tools.d.ts","sourceRoot":"","sources":["../../src/builtin/orchestration-tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAoC,MAAM,eAAe,CAAC;AAyR9F,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,EAAE,CAU1E;AAED,eAAO,MAAM,wBAAwB,kMAQ3B,CAAC"}