AI 智能引擎（Harness）
智能引擎（Harness）是 Automa Agent AI 模块的运行时编排层：在每次 LLM 请求与 BizApi 执行前，自动注入 Skills、长期记忆、任务进度，并完成校验、护栏与可选 Checker 验收。
在 AI 工作台点击 智能引擎 按钮即可打开配置弹窗；所有配置保存在本地数据库，无需编辑 JSON 文件。
架构分层
text
Loop（外层）
定时巡检 triage · 通道 inbound · state.md 续跑
↓
Harness（单 Agent 环境）
Middleware · Skills · Guard · Validation · Memory · Incident
↓
Context（单次 LLM 窗口）
system · skills · 记忆召回 · 会话压缩 · 工具反馈
↓
ModelbeforeLlm Middleware 链（按顺序）
| 顺序 | Middleware | 作用 |
|---|---|---|
| 1 | correlation | 生成本轮 correlationId |
| 2 | sessionCompact | 长会话规则截断 + 异步 LLM 摘要 |
| 3 | stateInject | 注入会话 state.md 任务进度 |
| 4 | skillInject | 按助手 slug 注入 Skills 正文 |
| 5 | memoryRecall | 向量检索相关经验记忆 |
| 6 | contextInject | 执行规则 / 目录等动态上下文 |
BizApi 执行前（prepareBizApiPlan）
- Catalog 校验 — command / args 是否符合 BizApi 索引
- 护栏 Guard — destructive / external_send 等策略与通道 deny
- Checker（可选） — LLM 验收计划是否合理
配置入口
AI 仪表盘 → 智能引擎 弹窗页签：
| 页签 | 内容 |
|---|---|
| 记忆与向量 | Embedding 提供商、召回参数、向量库文件名 |
| 经验沉淀 | 失败/拦截/纠正写入 vec 库、事件日志开关 |
| 会话压缩 | 触发阈值、保留消息数、异步摘要 |
| state.md | 任务进度注入开关与最大字符 |
| Triage Loop | 定时巡检开关与提示词 |
| Checker | Maker/Checker 验收开关 |
| Skills | 运行时 Skill CRUD |
| 经验记忆 | 向量库片段列表与删除 |
| 事件日志 | Harness 运行事件（校验/护栏/失败等）+ 半自动建议 |
| BizApi 护栏 | 开关、模式、tiers / channelOverrides 规则 |
数据存储
| 数据 | 存储位置 |
|---|---|
| Harness 全局配置 | 主库 ai_harness_settings |
| Skills | 主库 ai_harness_skill |
| 事件日志 | 主库 ai_harness_incident |
| 向量记忆 | 独立 {configDir}/erp_automa_vec.db |
| 会话 state / 摘要 | AiSessionEntity.memoryJson |
主库迁移至 MySQL 时，向量库仍可保持独立 SQLite，互不影响。
半自动建议
在 事件日志 页签点击 生成建议，系统会聚合最近 incident 并给出 guard / Skill 修改建议（规则引擎，非 LLM）。点击 应用 后才会写入配置。
| 触发条件 | 建议 |
|---|---|
| 同一 BizApi 失败 ≥2 次 | Skill 追加失败处理说明 |
| 同一 command 校验失败 ≥2 次 | Skill 追加 catalog 修正说明 |
| destructive 类 API 失败且未被护栏覆盖 | destructive tier 增加 pattern |
| 存在 user_correction | Skill 合并纠正要点 |
应用 guard 建议后，请到 BizApi 护栏 页签确认并 保存 Harness 配置。
API：generateAiHarnessSuggestionsApi、applyAiHarnessSuggestionApi。
记忆召回
前置条件
- 配置 Embedding：
- Ollama：
ollama pull nomic-embed-text，baseUrl 默认http://127.0.0.1:11434 - OpenAI 兼容：baseUrl 如
https://api.openai.com/v1，填写 API Key 与模型（如text-embedding-3-small），dimensions 须与模型一致
- Ollama：
- 智能引擎 → 记忆与向量 → 启用「记忆召回」
- 触发一次 BizApi 失败或点击消息「记入经验」→ 写入 vec 库
- 下次相似问题 → beforeLlm 注入「相关经验记忆」块
经验类型
| kind | 来源 |
|---|---|
bizapi_failure | BizApi 步骤执行失败 |
guard_block | 护栏拦截 |
validation_error | 计划校验失败 |
user_correction | 用户标记纠正 |
embedding_unavailable | embedding 不可用导致跳过写入 |
BizApi 护栏
护栏配置保存在 guardJson，工作台 BizApi 护栏 页签编辑：
- enabled / mode：
block拦截执行，warn仅警告 - tiers：按正则匹配 command，策略含
require_confirmation/deny/allow_autoexec - channelOverrides：按通道（如
dingtalk）额外 deny 列表
destructive 类 API 需先输出 bizapi-ask 待用户确认，再执行 bizapi-exec。
Triage 定时巡检
在 Cron 定时器中设置 actionKind: 'triage'，到期后向指定会话注入巡检提示词，走完整 Harness + autoexec 链路，用于长任务无人值守续跑。
相关 API：runAiTriageLoopApi、getAiSessionStateApi、updateAiSessionStateApi。
性能调优
Harness 默认已做多项优化，一般无需改代码。可按场景调整智能引擎参数：
| 场景 | 建议 |
|---|---|
| LLM 首 token 慢 | 确认 beforeLlm 未在 BizApi 中间轮触发 embedding（skipRecallOnToolFeedback 默认开启） |
| embedding 超时拖累 | 降低 embedding.timeoutMs（默认 8s）；或换本地 Ollama |
| 重复 embedding 调用 | 同文本 LRU 缓存（默认 5min）；记忆召回块 60s 内复用 |
| 长会话卡顿 | 启用会话压缩，调低 triggerMessageCount / triggerCharCount |
| 向量库过大 | 经验记忆页签清理无用片段；Brute 降级时 SQL 已过滤 scope |
| 打包后 vec 不可用 | 确认 electron-builder 已 unpack sqlite-vec-* native 扩展 |
已实现的运行时优化
- beforeLlm 单次读 Harness 配置注入
ctx.harnessCfg，middleware 不重复解析 - sessionCompact 预取 memoryJson，stateInject 复用，少一次 DB 查询
- 护栏 tier 正则 编译缓存，guard 保存时自动失效
- vec 库 SQL 预编译语句复用
- BizApi catalog 已加载则同步读取，避免重复
import() - 经验 / 事件写入 setImmediate 异步，不阻塞 autoexec 返回
相关文档
关键源码
| 路径 | 职责 |
|---|---|
src/main/ai/harness/AiHarnessPipeline.ts | Middleware 编排 + prepareBizApiPlan |
src/main/ai/vector/AiVectorDb.ts | 独立 vec 库 |
src/main/ai/harness/experience/AiExperienceService.ts | 经验沉淀 |
src/main/ai/beans/AiHarnessSettingsStore.ts | 配置 DB 读写 |
src/renderer/.../pop/AiHarnessConfigModal.vue | 工作台配置 UI |