AI Agent 平台架构说明 设计思想 v2.0

1系统概述与定位

这是一个 企业级 AI Agent 平台，核心代码位于 service/serviceAgent/（约 30k 行，含测试）。它的目标不是做一个「聊天机器人」，而是把 「大模型推理」和「企业内部系统的真实操作能力」连接起来——Agent 既能听懂自然语言，又能真的去查日志、读飞书文档、写内部系统、定时产出报表。

1.1 它到底解决了什么问题

• 把「多系统取数 + 规则汇总 + 自然语言输出」收敛成一句话：客服排查、周报、巡检、看板这些原本要人肉打开多个后台逐个截图、复制、汇总的活，交给 Agent 自动串起来。
• 让 Agent 带「当前用户身份」执行：查文档、调内部接口时能带上用户自己的 Token / 凭证 / 文档 ID（agent_user_env / agent_env）。
• 把能力做成可插拔的 Skill 插件：新增一个能力 = 新增一个 Skill 包，不改主流程代码。
• 让「一次性对话」升级为「可持续的自动化」：既能实时对话，也能注册定时任务主动推送（agent_schedule）。

1.2 核心价值

2技术选型总览

3系统整体架构

整体是典型的「入口层 → 服务层 → 资源层」三层，服务层是核心，所有 Agent 能力都在 service/serviceAgent/ 里。

┌─────────────────────────────────────────────────────────────────────────────┐
│ 入口层                                                                        │
│  POST /agent/chat              后台调试台（admin，/agent/* 管理接口）           │
│  POST /agent/channel/feishu/event.json   飞书事件回调                          │
│  cronjob：agent_schedule_worker / agent_channel_event_worker 定时扫描          │
└─────────────────────────────────────────────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 服务层  service/serviceAgent/（核心）                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ Chat 编排  agent.go：loadRuntimeConfig → loadSkillRuntime →          │    │
│  │             buildRuntimeTools → llmagent.New → runner.NewRunner →    │    │
│  │             RunWithMessages → 解析最终回复 → 保存记忆                 │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐        │
│  │ 运行时缓存     │ │ Skill 运行时  │ │ 记忆服务      │ │ 会话持久化    │        │
│  │ runtime_cache │ │ skill_runtime│ │ memory        │ │ session(mysql)│       │
│  └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘        │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐        │
│  │ 工具集        │ │ 飞书渠道      │ │ 定时任务      │ │ 可观测        │        │
│  │ tools         │ │ channel      │ │ schedule      │ │ langfuse/log  │       │
│  └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘        │
└─────────────────────────────────────────────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 资源层                                                                        │
│  MySQL：agent_config / llm_config / agent_skill* / agent_memory* /           │
│         agent_session* / agent_schedule* / agent_channel_* / agent_env        │
│  Redis：三级缓存(本地LRU→Redis→MySQL) / 会话热存 / 事件去重 / 任务 lease       │
│  本地盘：Skill 仓库缓存目录 /tmp/agent-skills/...                            │
│  外部：LLM(OpenAI兼容) / 飞书 OpenAPI / Omnibus 网关 / Connectors / Langfuse  │
└─────────────────────────────────────────────────────────────────────────────┘
      

3.1 核心组件职责

4一次完整对话流程

这是整个系统最核心的一条链路，入口是 agent.go 里的 chat()。理解它就理解了系统 70% 的设计。

用户请求（agent_id + message + 可选 image_data_urls + 身份字段）
   │
   ▼
① loadRuntimeConfig        —— 校验请求、读 Agent/LLM/渠道/技能摘要「配置快照」、解析身份
   │    (invocation: public / admin / feishu / schedule，决定工具面与权限)
   ▼
② loadAgentSkillRuntime    —— 把后台选的 Skill 展开成本轮「可执行的完整快照 + 摘要 prompt」
   ▼
③ 组装运行时对象
   │   openai.New(模型) —— 按 provider 切换 variant
   │   llmagent.New(agent, 模型/指令/最大迭代/技能/记忆预载/会话摘要压缩...)
   │   runner.NewRunner("platform-agent", agent, session/memory service...)
   │   buildRuntimeTools —— 按场景裁剪工具（见 §7）
   │   buildRuntimeMessages —— 纯文本 or 多模态（图转 base64）
   ▼
④ runner.RunWithMessages(非流式)
   │   Eino 内部：LLM 思考 → 工具调用 → 观察结果 → 循环（最多 MaxIterations 轮）
   ▼
⑤ 解析事件流
   │   跳过 tool.response / tool_calls 消息，取最后一条非空 assistant 文本
   │   定时任务则取 schedule_reply 工具的权威输出
   ▼
⑥ saveShortTermMemoryTurn —— 本轮问答落「短期记忆」（agent_memory_item）
   ▼
返回 AgentChatRsp{AgentName, Model, UserID, SessionID, Message}
      

4.1 四种调用入口（Invocation Source）

5运行时配置缓存（三级缓存）

Agent 运行时频繁读取 Agent 配置、LLM 配置、Skill 详情、渠道配置、用户/Agent 环境变量、各类 token。这些数据全部走 agent_runtime_cache.go 的三级缓存，避免每次对话都打 MySQL。

读缓存顺序：
   本地 LRU（3 分钟）  ──命中──▶ 返回
        │ 未命中
        ▼
   Redis（30 天）      ──命中──▶ 回写本地 LRU ──▶ 返回
        │ 未命中
        ▼
   MySQL（真源）        ──加载──▶ 回写 Redis + 本地 LRU ──▶ 返回
      

5.1 失效机制

任何后台保存/删除操作都会主动失效相关缓存：

• 改 Agent → invalidateAgent（清 AgentConfig + AgentBundle）；改 LLM → 失效自身并 invalidateAllAgentBundles（因为很多 Agent 引用了该 LLM）。
• 改 Skill/变量/仓库/市场 → invalidateSkillDetail + invalidateAllAgentBundles。
• 改渠道 → invalidateChannel（清 ChannelID/AppID/Token/飞书 token，并失效关联 Agent）。

6Skill 技能系统

Skill = 技能包，是 Agent 的「能力扩展单元」。一个 Skill 目录包含：

• SKILL.md —— 技能描述（YAML frontmatter + 正文，告诉 AI 它能做什么）
• skill.yaml / skill.yml —— manifest：name / description / variables / scripts
• scripts/ 或 install.py|sh|js —— 实际执行的脚本（python3 / node）
• references/ 等辅助文档

6.1 四种 Skill 来源

6.2 Skill 同步流程

StartSkillSyncLoop（每 60s 一次，可配 agent.skill_sync_interval_seconds）
   │
   ├─ syncRequestedSkillRepos：对 pending / 手动请求同步的 git 仓库
   │      clone/fetch → checkout 分支 → reset --hard → rev-parse HEAD
   │      记录 sync_status / sync_revision
   │
   ├─ parseSkillRepo：WalkDir 扫 SKILL.md
   │      解析 frontmatter + skill.yaml → 生成 SkillEntity → upsert 到 agent_skill
   │
   └─ syncInstalledMarketSkills：已安装的市场 Skill 缺失/过期时重新安装
      

6.3 Skill 运行时（重点）

对话时，loadAgentSkillRuntime 把「后台选了哪些 Skill」转成本轮给模型和工具使用的东西：

• 摘要注入 prompt：buildSkillInstruction 生成「# 已加载 Skill」清单（名称 + skill_id + repo + description + scripts + vars），有总量上限 30KB。
• 框架技能工具：llmagent.WithSkills(skillRepo) 暴露 skill_load / skill_list_docs / skill_select_docs，让模型按需加载 Skill 正文。
• 脚本执行工具：skill_script_execute（见 §7）。

6.4 脚本执行的细节

• 参数通过 AGENT_SKILL_ARGS_JSON 环境变量 + stdin 双通道传入，也支持 argv:[...] 形式转成 CLI 参数。
• 执行时注入：用户级 / Agent 级环境变量（密文解密后）、Connectors/Omnibus 相关 token。
• 超时控制（默认 300s，可配，定时任务 300~600s）；stdout/stderr 上限 64KB；退出码 / 时长 / 是否截断都结构化返回。
• 输出做 ANSI 转义清理 + 本地路径脱敏（把 /tmp/agent-skills/... 替换成 [skill:...]）+ 密钥脱敏。

7工具体系

工具由 buildRuntimeTools 按场景组装，不同调用场景看到的工具面不同——这是安全和控制成本的关键。

7.1 工具按场景裁剪

普通聊天：    user + web + image + feishu_doc + feishu_bitable + image_send
              + omnibus + schedule_* + skill_script_execute
明确 Skill 定时任务： current_time?(按需) + schedule_reply + skill_script_execute
restricted（匿名/未绑定）： 工具面几乎为空（关闭网络/图片/omnibus 等）
定时执行中：  禁止 schedule_*（避免任务又创建任务），只保留 schedule_reply
      

8记忆系统

记忆分两层，全部落 agent_memory_item 表，通过 agent_memory.go 的 frameworkMemoryService 实现 Eino 的 memory.Service 接口。

8.1 记忆治理

• 确认机制：MemoryConfirmationEnabled=1 时，自动抽取的画像记忆进入「待确认」状态，用户在飞书用 /memory_confirm / /memory_reject 确认或驳回。
• 审计：agent_memory_audit 记录确认/驳回动作。
• 脱敏：写入前用正则把 Authorization: Bearer xxx 等替换成 [redacted]，单条截断 8KB。

9会话持久化与上下文压缩

9.1 会话持久化

实现 Eino 的 session.Service，采用「内存热缓存 + MySQL 持久化」双层：

读：  globalAgentSessionHotCache（命中即返回）
        │ 未命中
        ▼
     MySQL（agent_session + agent_session_event + agent_session_state + agent_session_summary）
        │ 回写热缓存
写：  AppendEvent 先更新热缓存 + 进入 pending 队列 → Close() 时批量 flush 到 MySQL
      

• 事件（Event）落 agent_session_event，按 session_id + seq 分页加载。
• State（状态）分三级作用域：session / user / app，落 agent_session_state。
• 落库前 sanitize：去掉图片 base64 数据、清空 reasoning、脱敏 token/secret、裁剪 8MB 上限。
• 带一个工具轮次修复逻辑（repairSessionToolRounds），处理历史上孤儿 tool_call / tool_result 事件。

9.2 上下文压缩（Context Compaction）

当会话历史占比超过阈值时，用 Eino 的 SessionSummarizer 把历史压成摘要，避免上下文无限增长。相关参数（agent_context_compaction.go）：

• 触发阈值 0.65（历史占上下文窗口比例）；保留最近 2 轮不压缩。
• 摘要最大 800 词；工具结果 token 上限 4096（超大结果 8192）。
• 摘要落 agent_session_summary，带边界（cutoff 时间 + 最后事件 ID）。

10飞书渠道集成

飞书是主要用户入口，代码在 agent_channel.go + 一组 agent_feishu_*.go。

10.1 事件接收链路

飞书 → POST /agent/channel/feishu/event.json
   │
   ├─ 1. url_verification 挑战 → 原样返回 challenge
   ├─ 2. 签名校验（X-Lark-Signature）+ token 校验
   ├─ 3. 只看 im.message.receive_v1（其它事件忽略）
   ├─ 4. 群聊需 @ 机器人才响应（p2p 直接响应）
   ├─ 5. 事件去重（Redis，event_id/message_id 30 分钟）
   ├─ 6. 落库 agent_channel_event（pending）→ 异步入队
   └─ 7. worker 抢占（lease + 30s 心跳续租）→ 处理
      

10.2 处理与回复

• 身份绑定：飞书 openID/userID/unionID → 查邮箱 → 反查后台账号（resolveFeishuAdminUID）。未绑定则 restricted。
• 消息类型：text / image（转 base64 多模态）/ post（富文本，提取文本+图片）。
• 体验优化：先发「思考中」卡片（sendFeishuThinkingReply），完成后原地更新卡片，或发最终卡片/文本；image_send 支持把产物图片发回。
• 斜杠命令：/help、/new、/stop、/memory_view|pending|confirm|reject|delete|clear、/skill_list、/skill_invoke。
• 机器人菜单 + 长连接：agent_feishu_menu.go（菜单/账号绑定页）、agent_feishu_long_conn.go（长连接主动推送）。

11定时任务系统

让 Agent 从「被动对话」升级为「主动产出」，代码 agent_schedule.go。

• 类型：once（一次性）/ cron（5 段 cron，分钟级，自研解析 parseCronSpec）。
• 存储：agent_schedule（任务）+ agent_schedule_run（每次执行记录）。
• 扫描：cronjob ProcessDueSchedules，单轮最多并发 20（semaphore 闸门）。
• 抢占：ClaimDue 用 id + updated_at 乐观锁，防止多进程重复执行；卡住的任务（processing 过久）会被重新捞起恢复。

ProcessDueSchedules（扫描到期任务）
   ├─ ListDue：enabled 且 next_run_at 到期 + processing 卡住待恢复
   ├─ ClaimDue（乐观锁抢占）→ 写 running 记录（agent_schedule_run）
   ├─ 复用 ChatSchedule（ScheduleExecution=true）
   │     SessionID = "schedule:{scheduleID}:{runID}"（按 run 隔离）
   │     prompt 注入「固定规则上下文快照 + 按任务时区解析的今天/昨天/明天日期」
   ├─ 模型必须调用 schedule_reply 工具 → 读取权威输出
   ├─ 有内容才投递到飞书（群聊 chat_id 或用户 open_id）
   └─ finishSchedule：更新状态 + 重算 next_run_at（cron 任务）
      

12可观测性

13安全与权限

14设计决策矩阵（升级版）

这一章把整套系统里的关键「设计决策」摆到台面，每条都给出选了 A、为什么不选 B、有什么代价。这是新人讲解和面试表达最值钱的内容。

15六大设计思想精讲 v2.0 NEW

这一章挑出 6 个最具代表性的设计决策，每个都给出问题 → 方案 → 取舍 → 代价 → 真实坑五个维度。这是新人讲解和面试表达的核心弹药库。

15.1 缓存分层：为什么是三级而不是两级？

L1  本地 LRU    TTL 3min   —— 进程内命中，纳秒级
L2  Redis       TTL 30天    —— 跨 Pod 共享，毫秒级
L3  MySQL       永久        —— 真源，强一致
        

15.2 Skill 分四种来源：为什么不统一成一种？

15.3 工具按场景裁剪：为什么不能一套工具走天下？

普通聊天       → 全量工具（除 schedule_reply）
定时任务       → 收窄到 schedule_reply + skill_script_execute
明确 Skill     → 仅当前 Skill 的脚本 + schedule_reply
restricted     → 工具面几乎为空（关网络/图片/Omnibus/记忆/持久化）
        

15.4 Memory 与 Session：为什么不合并成一个？

15.5 上下文压缩：为什么是 0.65 不是 0.8？

历史占上下文窗口比例 ≥ 0.65   ──触发──▶ 摘要旧历史（保留最近 2 轮）
摘要 ≤ 800 词                  ──落库──▶ agent_session_summary
工具结果上限 4096 / 8192 token  ──裁剪──▶ 超大结果降级
        

15.6 非流式 Chat：为什么放弃打字机效果？

16业务 Agent 落地模板 v2.0 NEW

四个真实业务 Agent（个人助理 / 客服排查 / 智能改图 / Smart 智能改图）看似各不相同，但抽象出来有同一个落地模板。讲清楚这个模板，就讲清了「如何用这个平台做一个新业务」。

16.1 共性：所有业务 Agent 都长一个样

① 入口校验（参数解析、身份校验、限流）
        │
        ▼
② 参数预处理（图片签名 URL、参数校验、权益预扣减）
        │
        ▼
③ 路由分发（按场景选执行路径：自动改图/手动改图/SOP/Eino Agent）
        │
        ▼
④ 执行（异步任务 + SSE 进度推送 OR 同步调用 + 流式事件）
        │
        ▼
⑤ 结果处理（回调落 Redis → ConsumeLoop 下发 → 写记忆/落会话）
        

16.2 如何用这个平台做一个新业务 Agent

16.3 真实案例对照（按模板解读）

17面试高频追问 Q&A v2.0 NEW

列了 20 个面试里最可能被追问的「为什么」问题，每个都给出回答要点。背完这 20 题，应届生讲 AI Agent 项目基本不会被追问倒。

18附录 / 数据表 / 术语 / 代码索引

A. 数据表清单（dao/daoagent）

B. 术语表

C. 关键代码路径索引

D. v2.0 新增章节速览