@zhin.js/agent 0.1.29 → 0.1.31

package/README.md

@@ -6,18 +6,18 @@ 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 等
+- 🔧 **内置工具**：bash、read_file、write_file、ask_user、web_search、`chat_history`（按关键词/最近条数查 `im_transcripts`）等
 - 📐 **会话压缩**：`compactSession`、token 估算、总结与裁剪
 - 🪝 **Hook 系统**：`registerAIHook`、`triggerAIHook` 等
 
@@ -44,8 +44,6 @@ npm install zhin.js
 import {
   initAgentModule,
   ZhinAgent,
-  Agent,
-  createAgent,
   AIService,
   SessionManager,
   registerAIHook,
@@ -64,16 +62,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 +82,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 +119,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` 类型已包含上述两项。
@@ -148,30 +149,27 @@ ai:
 框架已提供 **SubagentManager**：主 ZhinAgent 通过工具 `spawn_task` 把复杂/耗时任务派给**后台子 Agent** 异步执行，子 Agent 默认仅用受限工具集（文件、Shell、网络搜索等），完成后通过回调把结果发回主会话。
 
 - 主对话不阻塞，用户可继续聊天。
-- 子 Agent 由 `ZhinAgent.initSubagentManager(createTools)` 在 init 时挂好，主 Agent 在回复里提到「后台 / 子任务 / spawn」时会注入 `spawn_task` 工具。
+- 子 Agent 由 `ZhinAgent.initSubagentManager(createTools)` 在 init 时挂好；`spawn_task` 为主编排序列化常驻工具（见 `orchestratorTools` / `DEFAULT_ORCHESTRATOR_TOOLS`）。
 - 用户说「后台帮我整理这份文档」时，主 Agent 可调用 `spawn_task({ task: '...', label: '...' })`，子任务在后台跑完后再通知用户。
 
 无需额外配置即可使用；若需放宽子 Agent 的工具范围，使用 `ai.agent.subagentTools` 显式追加白名单（不会自动继承主会话全部 skill/tool）。
 
 ### 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 +199,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 +207,33 @@ 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
+```
+
 ## Model harness
 
 按 provider / model 覆盖 Agent 循环默认参数（当前主要为 **`maxIterations`**）。
@@ -267,7 +292,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/agent-prompt/resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/agent-prompt/resolver.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,uBAAuB,EACvB,kBAAkB,EACnB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAY/D,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,uBAAuB,CAAC;IAC7B,MAAM,CAAC,EAAE,IAAI,CACX,QAAQ,CAAC,eAAe,CAAC,EACzB,+BAA+B,GAAG,wBAAwB,CAC3D,CAAC;IACF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA0C/B;AAED,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED,wBAAgB,+BAA+B,CAC7C,GAAG,EAAE,uBAAuB,EAC5B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,aAAa,EAAE,SAAS,EAAE,EAC1C,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,aAAa,EAAE,SAAS,EAAE,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,aAAa,EAAE,SAAS,EAAE,GAC9I,OAAO,aAAa,EAAE,SAAS,EAAE,CAOnC;AAED,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,uBAAuB,EAC5B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GACX,OAAO,CAUT"}
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/agent-prompt/resolver.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,uBAAuB,EACvB,kBAAkB,EACnB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAY/D,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,uBAAuB,CAAC;IAC7B,MAAM,CAAC,EAAE,IAAI,CACX,QAAQ,CAAC,eAAe,CAAC,EACzB,+BAA+B,GAAG,wBAAwB,CAC3D,CAAC;IACF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAyC/B;AAED,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED,wBAAgB,+BAA+B,CAC7C,GAAG,EAAE,uBAAuB,EAC5B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,aAAa,EAAE,SAAS,EAAE,EAC1C,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,aAAa,EAAE,SAAS,EAAE,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,aAAa,EAAE,SAAS,EAAE,GAC9I,OAAO,aAAa,EAAE,SAAS,EAAE,CAOnC;AAED,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,uBAAuB,EAC5B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GACX,OAAO,CAUT"}

package/lib/agent-prompt/resolver.js

@@ -31,7 +31,6 @@ export async function resolveAgentPromptSections(options) {
     const hookEvent = createAIHookEvent('agent', 'prompt', sessionId, {
         slot: ctx.slot,
         toolContext: ctx.toolContext,
-        toolSearch: ctx.toolSearch,
         userMessagePreview: ctx.userMessagePreview,
         deferred: ctx.deferred,
         sections,

package/lib/agent-prompt/resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../src/agent-prompt/resolver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../src/agent-prompt/resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAMvC,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,sBAAsB,EACtB,iCAAiC,EACjC,uBAAuB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAE1D,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,EAAE,qBAAqB,CAAC,CAAC;AAWvD,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,OAAkC;IAElC,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IACnC,MAAM,MAAM,GAAG;QACb,UAAU,EAAE,OAAO,CAAC,MAAM,EAAE,6BAA6B;eACpD,cAAc,CAAC,6BAA6B;QACjD,QAAQ,EAAE,OAAO,CAAC,MAAM,EAAE,sBAAsB;eAC3C,cAAc,CAAC,sBAAsB;KAC3C,CAAC;IAEF,MAAM,QAAQ,GAAG,GAAG,CAAC,WAAW,CAAC,QAAQ,CAAC;IAC1C,MAAM,WAAW,GAAG,yBAAyB,CAAC,QAAQ,CAAC,CAAC;IACxD,IAAI,QAAQ,GAAyB,EAAE,CAAC;IAExC,IAAI,WAAW,EAAE,CAAC;QAChB,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;YACnD,IAAI,KAAK,EAAE,MAAM,EAAE,CAAC;gBAClB,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7D,MAAM,CAAC,IAAI,CAAC,2BAA2B,QAAQ,2BAA2B,GAAG,EAAE,CAAC,CAAC;QACnF,CAAC;IACH,CAAC;IAED,QAAQ,GAAG,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IAE7C,MAAM,SAAS,GAAG,iBAAiB,CAAC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE;QAChE,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,kBAAkB,EAAE,GAAG,CAAC,kBAAkB;QAC1C,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,QAAQ;KACT,CAAC,CAAC;IACH,MAAM,aAAa,CAAC,SAAS,CAAC,CAAC;IAC/B,MAAM,YAAY,GAAG,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC;IAChD,IAAI,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QAChC,QAAQ,GAAG,uBAAuB,CAAC,YAAoC,CAAC,CAAC;IAC3E,CAAC;IAED,OAAO,sBAAsB,CAAC,QAAQ,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,OAAkC;IAElC,MAAM,QAAQ,GAAG,MAAM,0BAA0B,CAAC,OAAO,CAAC,CAAC;IAC3D,OAAO,iCAAiC,CAAC,QAAQ,CAAC,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,+BAA+B,CAC7C,GAA4B,EAC5B,KAAa,EACb,IAAY,EACZ,OAA0C,EAC1C,QAAgB,EAChB,aAA+I;IAE/I,MAAM,WAAW,GAAG,yBAAyB,CAAC,GAAG,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IACxE,IAAI,WAAW,EAAE,mBAAmB,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,QAAQ,GAAG,WAAW,CAAC,mBAAmB,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;QACnF,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;IAChC,CAAC;IACD,OAAO,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,2BAA2B,CACzC,GAA4B,EAC5B,KAAa,EACb,IAAY;IAEZ,MAAM,WAAW,GAAG,yBAAyB,CAAC,GAAG,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IACxE,IAAI,WAAW,EAAE,mBAAmB,EAAE,CAAC;QACrC,IAAI,CAAC;YACH,OAAO,WAAW,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;QAC9C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/lib/assistant/config.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Assistant Runtime 配置（应用级，zhin.config.yml 顶层 assistant 块）
+ */
+import type { AssistantHomeConfig } from './home-config.js';
+import type { JobNotify } from './types.js';
+export interface AssistantDefaultsConfig {
+    /** 未显式指定 notify 时的默认投递目标（M3） */
+    notify?: JobNotify;
+    /** Job 失败时是否通知（默认 false） */
+    notifyOnFailure?: boolean;
+}
+export interface AssistantEventsConfig {
+    /** 启用 POST /api/assistant/events（需 assistant.enabled） */
+    enabled?: boolean;
+    /**
+     * 可选专用 Bearer；未设时复用 http.token（路由仍在 /api 下受全局鉴权保护）。
+     */
+    token?: string;
+    /** 允许的来源白名单；空数组表示不限制 */
+    allowedSources?: string[];
+    /** 每来源每分钟最大请求数（默认 60） */
+    rateLimitPerMinute?: number;
+}
+export interface AssistantQueueConfig {
+    /** 启用 TaskQueue 执行 Job（默认 assistant.enabled 时为 true） */
+    enabled?: boolean;
+    maxConcurrency?: number;
+    maxRetries?: number;
+    defaultTimeoutMs?: number;
+}
+export interface AssistantConfig {
+    /** 启用统一 JobStore（默认 false，Stable 行为不变） */
+    enabled?: boolean;
+    /** JobWorker → TaskQueue（重试 / 并发 / 死信） */
+    queue?: AssistantQueueConfig;
+    /**
+     * 写入 assistant-jobs.json 后是否双写 legacy cron-jobs.json（默认 false）。
+     * 迁移期可设 true 便于旧 CLI 只读 cron-jobs.json。
+     */
+    legacyDualWrite?: boolean;
+    /** 自定义 JobStore 文件名（默认 assistant-jobs.json） */
+    jobsFile?: string;
+    defaults?: AssistantDefaultsConfig;
+    profile?: import('./profile-types.js').AssistantProfileConfig;
+    home?: AssistantHomeConfig;
+    events?: AssistantEventsConfig;
+}
+export declare const DEFAULT_ASSISTANT_CONFIG: Required<Pick<AssistantConfig, 'legacyDualWrite'>>;
+export declare const DEFAULT_EVENTS_CONFIG: Required<Pick<AssistantEventsConfig, 'rateLimitPerMinute'>>;
+export declare function resolveAssistantQueueConfig(raw?: AssistantQueueConfig, assistantEnabled?: boolean): AssistantQueueConfig & {
+    enabled: boolean;
+    maxConcurrency: number;
+    maxRetries: number;
+    defaultTimeoutMs: number;
+};
+export declare function resolveAssistantConfig(raw?: AssistantConfig): AssistantConfig & {
+    enabled: boolean;
+};
+export declare function resolveAssistantDefaultsConfig(raw?: AssistantDefaultsConfig): AssistantDefaultsConfig & {
+    notifyOnFailure: boolean;
+};
+export declare function resolveAssistantEventsConfig(raw?: AssistantEventsConfig): AssistantEventsConfig & {
+    enabled: boolean;
+    rateLimitPerMinute: number;
+};
+export declare function isAssistantEventsActive(assistant?: AssistantConfig): boolean;
+//# sourceMappingURL=config.d.ts.map

package/lib/assistant/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/assistant/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,WAAW,uBAAuB;IACtC,gCAAgC;IAChC,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,4BAA4B;IAC5B,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC,yDAAyD;IACzD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,yBAAyB;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,0CAA0C;IAC1C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IACnC,OAAO,CAAC,EAAE,OAAO,oBAAoB,EAAE,sBAAsB,CAAC;IAC9D,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC;AAED,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,IAAI,CAAC,eAAe,EAAE,iBAAiB,CAAC,CAEvF,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,IAAI,CAAC,qBAAqB,EAAE,oBAAoB,CAAC,CAE7F,CAAC;AAEF,wBAAgB,2BAA2B,CACzC,GAAG,CAAC,EAAE,oBAAoB,EAC1B,gBAAgB,UAAQ,GACvB,oBAAoB,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,CAQnH;AAED,wBAAgB,sBAAsB,CAAC,GAAG,CAAC,EAAE,eAAe,GAAG,eAAe,GAAG;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAWpG;AAED,wBAAgB,8BAA8B,CAC5C,GAAG,CAAC,EAAE,uBAAuB,GAC5B,uBAAuB,GAAG;IAAE,eAAe,EAAE,OAAO,CAAA;CAAE,CAKxD;AAED,wBAAgB,4BAA4B,CAC1C,GAAG,CAAC,EAAE,qBAAqB,GAC1B,qBAAqB,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAA;CAAE,CAO1E;AAED,wBAAgB,uBAAuB,CACrC,SAAS,CAAC,EAAE,eAAe,GAC1B,OAAO,CAIT"}

package/lib/assistant/config.js

@@ -0,0 +1,47 @@
+export const DEFAULT_ASSISTANT_CONFIG = {
+    legacyDualWrite: false,
+};
+export const DEFAULT_EVENTS_CONFIG = {
+    rateLimitPerMinute: 60,
+};
+export function resolveAssistantQueueConfig(raw, assistantEnabled = false) {
+    const enabled = raw?.enabled ?? assistantEnabled;
+    return {
+        enabled,
+        maxConcurrency: raw?.maxConcurrency ?? 3,
+        maxRetries: raw?.maxRetries ?? 2,
+        defaultTimeoutMs: raw?.defaultTimeoutMs ?? 120_000,
+    };
+}
+export function resolveAssistantConfig(raw) {
+    return {
+        enabled: raw?.enabled === true,
+        legacyDualWrite: raw?.legacyDualWrite ?? DEFAULT_ASSISTANT_CONFIG.legacyDualWrite,
+        jobsFile: raw?.jobsFile,
+        queue: raw?.queue,
+        defaults: raw?.defaults,
+        profile: raw?.profile,
+        home: raw?.home,
+        events: raw?.events,
+    };
+}
+export function resolveAssistantDefaultsConfig(raw) {
+    return {
+        notify: raw?.notify,
+        notifyOnFailure: raw?.notifyOnFailure === true,
+    };
+}
+export function resolveAssistantEventsConfig(raw) {
+    return {
+        enabled: raw?.enabled === true,
+        token: raw?.token,
+        allowedSources: raw?.allowedSources,
+        rateLimitPerMinute: raw?.rateLimitPerMinute ?? DEFAULT_EVENTS_CONFIG.rateLimitPerMinute,
+    };
+}
+export function isAssistantEventsActive(assistant) {
+    const base = resolveAssistantConfig(assistant);
+    const events = resolveAssistantEventsConfig(base.events);
+    return base.enabled && events.enabled;
+}
+//# sourceMappingURL=config.js.map

package/lib/assistant/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/assistant/config.ts"],"names":[],"mappings":"AAoDA,MAAM,CAAC,MAAM,wBAAwB,GAAuD;IAC1F,eAAe,EAAE,KAAK;CACvB,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAgE;IAChG,kBAAkB,EAAE,EAAE;CACvB,CAAC;AAEF,MAAM,UAAU,2BAA2B,CACzC,GAA0B,EAC1B,gBAAgB,GAAG,KAAK;IAExB,MAAM,OAAO,GAAG,GAAG,EAAE,OAAO,IAAI,gBAAgB,CAAC;IACjD,OAAO;QACL,OAAO;QACP,cAAc,EAAE,GAAG,EAAE,cAAc,IAAI,CAAC;QACxC,UAAU,EAAE,GAAG,EAAE,UAAU,IAAI,CAAC;QAChC,gBAAgB,EAAE,GAAG,EAAE,gBAAgB,IAAI,OAAO;KACnD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,GAAqB;IAC1D,OAAO;QACL,OAAO,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI;QAC9B,eAAe,EAAE,GAAG,EAAE,eAAe,IAAI,wBAAwB,CAAC,eAAe;QACjF,QAAQ,EAAE,GAAG,EAAE,QAAQ;QACvB,KAAK,EAAE,GAAG,EAAE,KAAK;QACjB,QAAQ,EAAE,GAAG,EAAE,QAAQ;QACvB,OAAO,EAAE,GAAG,EAAE,OAAO;QACrB,IAAI,EAAE,GAAG,EAAE,IAAI;QACf,MAAM,EAAE,GAAG,EAAE,MAAM;KACpB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,8BAA8B,CAC5C,GAA6B;IAE7B,OAAO;QACL,MAAM,EAAE,GAAG,EAAE,MAAM;QACnB,eAAe,EAAE,GAAG,EAAE,eAAe,KAAK,IAAI;KAC/C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,4BAA4B,CAC1C,GAA2B;IAE3B,OAAO;QACL,OAAO,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI;QAC9B,KAAK,EAAE,GAAG,EAAE,KAAK;QACjB,cAAc,EAAE,GAAG,EAAE,cAAc;QACnC,kBAAkB,EAAE,GAAG,EAAE,kBAAkB,IAAI,qBAAqB,CAAC,kBAAkB;KACxF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,SAA2B;IAE3B,MAAM,IAAI,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,4BAA4B,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACzD,OAAO,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC;AACxC,CAAC"}

package/lib/assistant/domains/home-assistant.d.ts

@@ -0,0 +1,37 @@
+import type { AssistantHomeConfig } from '../home-config.js';
+export type HaFetch = (url: string, init?: RequestInit) => Promise<Response>;
+export interface HaEntityState {
+    entityId: string;
+    state: string;
+    attributes: Record<string, unknown>;
+    lastChanged?: string;
+    lastUpdated?: string;
+}
+export declare function parseEntityDomain(entityId: string): string;
+export declare class HomeAssistantService {
+    private cfg;
+    private fetchFn;
+    constructor(homeConfig: AssistantHomeConfig, fetchFn?: HaFetch);
+    listAliases(): Record<string, string>;
+    resolveAlias(alias: string): string;
+    private baseUrl;
+    private token;
+    private haRequest;
+    getState(alias: string): Promise<HaEntityState>;
+    resolveServiceForToggle(entityId: string, on: boolean): {
+        domain: string;
+        service: string;
+    };
+    callService(alias: string, service: string, data?: Record<string, unknown>): Promise<void>;
+    turnOn(alias: string): Promise<{
+        alias: string;
+        entityId: string;
+        service: string;
+    }>;
+    turnOff(alias: string): Promise<{
+        alias: string;
+        entityId: string;
+        service: string;
+    }>;
+}
+//# sourceMappingURL=home-assistant.d.ts.map

package/lib/assistant/domains/home-assistant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"home-assistant.d.ts","sourceRoot":"","sources":["../../../src/assistant/domains/home-assistant.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAK7D,MAAM,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE7E,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAYD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,GAAG,CAAgD;IAC3D,OAAO,CAAC,OAAO,CAAU;gBAEb,UAAU,EAAE,mBAAmB,EAAE,OAAO,GAAE,OAA2C;IAKjG,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAIrC,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IASnC,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,KAAK;YAKC,SAAS;IAoBjB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAYrD,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAUrF,WAAW,CACf,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC;IAUV,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAOpF,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAM5F"}

package/lib/assistant/domains/home-assistant.js

@@ -0,0 +1,113 @@
+/**
+ * HomeAssistantService — 别名解析 + HA REST（M4）
+ */
+import { Logger } from '@zhin.js/core';
+import { formatCompact } from '@zhin.js/logger';
+import { resolveAssistantHomeConfig } from '../home-config.js';
+const logger = new Logger(null, 'home-assistant');
+const DOMAIN_SERVICE_MAP = {
+    light: { on: 'turn_on', off: 'turn_off' },
+    switch: { on: 'turn_on', off: 'turn_off' },
+    fan: { on: 'turn_on', off: 'turn_off' },
+    cover: { on: 'open_cover', off: 'close_cover' },
+    lock: { on: 'unlock', off: 'lock' },
+    climate: { on: 'turn_on', off: 'turn_off' },
+    media_player: { on: 'turn_on', off: 'turn_off' },
+};
+export function parseEntityDomain(entityId) {
+    const dot = entityId.indexOf('.');
+    return dot > 0 ? entityId.slice(0, dot) : entityId;
+}
+export class HomeAssistantService {
+    cfg;
+    fetchFn;
+    constructor(homeConfig, fetchFn = globalThis.fetch.bind(globalThis)) {
+        this.cfg = resolveAssistantHomeConfig(homeConfig);
+        this.fetchFn = fetchFn;
+    }
+    listAliases() {
+        return { ...this.cfg.aliases };
+    }
+    resolveAlias(alias) {
+        const key = alias.trim();
+        const entity = this.cfg.aliases?.[key];
+        if (!entity) {
+            throw new Error(`未知设备别名: ${alias}（可用: ${Object.keys(this.cfg.aliases ?? {}).join('、') || '无'}）`);
+        }
+        return entity;
+    }
+    baseUrl() {
+        const url = this.cfg.restUrl?.replace(/\/$/, '');
+        if (!url)
+            throw new Error('assistant.home.restUrl 未配置');
+        return url;
+    }
+    token() {
+        if (!this.cfg.restToken)
+            throw new Error('assistant.home.restToken 未配置');
+        return this.cfg.restToken;
+    }
+    async haRequest(path, init) {
+        const url = `${this.baseUrl()}${path}`;
+        const res = await this.fetchFn(url, {
+            ...init,
+            headers: {
+                Authorization: `Bearer ${this.token()}`,
+                'Content-Type': 'application/json',
+                ...(init?.headers ?? {}),
+            },
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`HA API ${res.status}: ${body.slice(0, 200) || res.statusText}`);
+        }
+        if (res.status === 204)
+            return null;
+        const text = await res.text();
+        if (!text)
+            return null;
+        return JSON.parse(text);
+    }
+    async getState(alias) {
+        const entityId = this.resolveAlias(alias);
+        const raw = await this.haRequest(`/api/states/${encodeURIComponent(entityId)}`);
+        return {
+            entityId,
+            state: String(raw.state ?? 'unknown'),
+            attributes: raw.attributes ?? {},
+            lastChanged: raw.last_changed,
+            lastUpdated: raw.last_updated,
+        };
+    }
+    resolveServiceForToggle(entityId, on) {
+        const domain = parseEntityDomain(entityId);
+        const mapped = DOMAIN_SERVICE_MAP[domain];
+        const service = on ? mapped?.on : mapped?.off;
+        if (!service) {
+            throw new Error(`不支持的控制类型: ${domain}（entity: ${entityId}）`);
+        }
+        return { domain, service };
+    }
+    async callService(alias, service, data) {
+        const entityId = this.resolveAlias(alias);
+        const domain = parseEntityDomain(entityId);
+        await this.haRequest(`/api/services/${domain}/${service}`, {
+            method: 'POST',
+            body: JSON.stringify({ entity_id: entityId, ...data }),
+        });
+        logger.debug(formatCompact({ op: 'ha_service', alias, entityId, domain, service }));
+    }
+    async turnOn(alias) {
+        const entityId = this.resolveAlias(alias);
+        const { domain, service } = this.resolveServiceForToggle(entityId, true);
+        await this.callService(alias, service);
+        return { alias, entityId, service: `${domain}.${service}` };
+    }
+    async turnOff(alias) {
+        const entityId = this.resolveAlias(alias);
+        const { domain, service } = this.resolveServiceForToggle(entityId, false);
+        await this.callService(alias, service);
+        return { alias, entityId, service: `${domain}.${service}` };
+    }
+}
+//# sourceMappingURL=home-assistant.js.map

package/lib/assistant/domains/home-assistant.js.map

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

package/lib/assistant/event-ingress.d.ts

@@ -0,0 +1,28 @@
+import type { AssistantEventsConfig } from './config.js';
+import type { AssistantEventRequest, AssistantEventResult } from './event-types.js';
+import type { AssistantJobEngine } from './job-engine.js';
+import type { AssistantJobStore } from './job-store.js';
+export interface AssistantEventIngressOptions {
+    store: AssistantJobStore;
+    engine: AssistantJobEngine;
+    eventsConfig?: AssistantEventsConfig;
+}
+export declare class AssistantEventIngress {
+    private store;
+    private engine;
+    private eventsCfg;
+    private rateBuckets;
+    constructor(options: AssistantEventIngressOptions);
+    isEnabled(): boolean;
+    checkRateLimit(source: string): boolean;
+    validateSource(source: string): string | null;
+    validateRequest(body: unknown): {
+        ok: true;
+        data: AssistantEventRequest;
+    } | {
+        ok: false;
+        error: string;
+    };
+    handle(body: unknown): Promise<AssistantEventResult>;
+}
+//# sourceMappingURL=event-ingress.d.ts.map

package/lib/assistant/event-ingress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-ingress.d.ts","sourceRoot":"","sources":["../../src/assistant/event-ingress.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACpF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAKxD,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,iBAAiB,CAAC;IACzB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,YAAY,CAAC,EAAE,qBAAqB,CAAC;CACtC;AAOD,qBAAa,qBAAqB;IAChC,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,SAAS,CAAkD;IACnE,OAAO,CAAC,WAAW,CAAiC;gBAExC,OAAO,EAAE,4BAA4B;IAMjD,SAAS,IAAI,OAAO;IAIpB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAcvC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAS7C,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,qBAAqB,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAmClG,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,oBAAoB,CAAC;CA2D3D"}