🎗️Agent输出

方舟平台升级方案：飞书频道接入 + 任务适配层（对标 Syfo AI）

版本: v1.2（2026-08-14） 更新记录: v1.2 移除 Notion 集成（不需要）；移除 A2A Bridge（Agent 间协作直接在群聊 @ 完成）；技术栈确定为 Next.js 全栈；接口示例代码统一改为 TypeScript。 背景: 现有 Agent 管理平台，对标 Syfo AI（syfo.ai，人 × Agent 协作工作空间）升级。 核心策略: 公司全员基于飞书工作 → 飞书作为协作前端（Channel），平台作为后端中枢，同时保留自研 Web 看板/产物视图；任务体系通过适配层与飞书任务双向同步。 技术栈: Next.js 全栈（前端 + API 同仓，所有代码用 Next.js）

1. 目标与差异化

已实证结论（官方 SDK 源码，larksuite/oapi-sdk-python v2_main 分支）：

2. 总体架构

┌──────────────────────────────────────────────────────────┐
│  入口层                                                  │
│  飞书（群/私聊/卡片/任务）      Web 端（看板/产物/管理）     │
├──────────────────────────────────────────────────────────┤
│  频道适配层 Channel Adapter Layer                        │
│  ┌──────────────┐ ┌──────────────────┐                     │
│  │ FeishuAdapter │ │WebAdapter(未来) │                     │
│  └──────────────┘ └──────────────────┘                     │
│  统一接口: 事件入站 / 消息出站 / 卡片 / 文件 / 群管理        │
├──────────────────────────────────────────────────────────┤
│  协作域: Message / Thread / Mention / 过滤器 / 审批        │
│  任务适配层 Task Adapter Layer                            │
│  ┌──────────────────────┐ ┌─────────────────────────┐    │
│  │ FeishuTaskAdapter    │ │ PlatformTaskBoard(自研)  │    │
│  └──────────────────────┘ └─────────────────────────┘    │
│  任务域: Task / TaskBoard / 状态机 / 同步引擎              │
│  产物域: Artifact / ArtifactVersion / 对象存储            │
│  运行时域: AgentRuntime / Trigger / Tool / MCP            │
├──────────────────────────────────────────────────────────┤
│  基础设施: Auth(飞书SSO) / Token管理 / 审计日志 / 权限      │
└──────────────────────────────────────────────────────────┘

三条核心设计原则：

1. 消息中心化：任务、产物、审批全部挂在频道消息上（messages 表 + 类型 + 引用）
2. 适配层隔离：飞书只是一次实现，核心域（协作/任务/产物）不感知任何外部平台
3. 安全内置：危险操作（建群、拉人、发外部请求、发布）走"Agent 出确认卡 → 人批准 → 执行"，全程审计

3. 频道适配层（Channel Adapter）

3.1 统一接口定义

interface ChannelAdapter {
  // ---- 入站 ----
  startListening(): Promise<void>;                        // 长连接/Webhook 启动
  normalizeEvent(raw: unknown): ChannelEvent;             // 原始事件 → 规范模型

  // ---- 出站 ----
  sendMessage(ch: ChannelRef, payload: MsgPayload): Promise<MsgRef>;
  sendCard(ch: ChannelRef, card: CardPayload, actions: CardAction[]): Promise<MsgRef>;
  uploadFile(ch: ChannelRef, file: FilePayload): Promise<FileRef>;

  // ---- 群管理（Agent 工具）----
  createChannel(name: string, members: string[], owner?: string): Promise<ChannelRef>;
  addMembers(ch: ChannelRef, members: string[]): Promise<void>;
  listMembers(ch: ChannelRef): Promise<string[]>;
}

interface ChannelEvent {           // 规范化消息模型
  eventId: string;                 // 去重键
  channelRef: ChannelRef;
  sender: Sender;                  // { type: 'user' | 'bot' | 'system', externalId }
  mentions: string[];              // 被 @ 的成员 externalId
  msgType: 'text' | 'image' | 'file' | 'post' | 'card_action';
  content: Record<string, unknown>;
  raw: Record<string, unknown>;    // 原始 payload，审计用
}

3.2 FeishuAdapter 实现要点

入站（事件订阅，推荐 WebSocket 长连接模式，内网友好）：

@触发过滤器（关键策略）：

• 默认：仅当 mentions 包含机器人时才触发 Agent，其余消息忽略（落日志）
• 可配置策略：频道级"全部响应"（值班 Agent）、关键词触发、时段控制
• 过滤器位置：规范化之后、路由之前，纯平台逻辑，与飞书无关

去重/幂等：

• 飞书事件会重试 → 以 event_id（事件）+ message_id（消息）双重去重
• messages.external_msg_id 建唯一索引
• Agent 触发前先查重，防止重复干活

出站：

• 文本：im/v1/messages（receive_id_type=chat_id）
• 富文本/文件：post 消息 / 上传文件 API
• 交互卡片：任务进度卡、审批确认卡、产物交付卡（按钮回调走 card.action.trigger）

群管理工具（Agent Skill 注册）：

• 建群参数（已实证）：name description owner_id(指定真人群主) user_id_list(初始成员) bot_id_list，查询参数 set_bot_manager=true(机器人为群管理员)
• 拉人：body id_list，查询参数 member_id_type succeed_type
• 限制：应用身份只能操作通讯录可见范围内的用户（与 IT 确认应用可见范围配置）

3.3 Token 管理服务

class TokenService {
  async tenantToken(): Promise<string>;             // app_id+secret 换，缓存~2h，自动刷新
  async userToken(userId: string): Promise<string>; // OAuth 授权一次，存 refresh_token
}

• 默认 tenant_access_token（应用身份）：Agent 自动建群/拉人/发消息走这条，无需用户参与
• user_access_token 按需（替用户执行、读用户私有数据时）：OAuth 授权流程 + refresh token 轮换 + 按用户缓存
• token 泄漏防护：token 只存后端、加密存储、按用户隔离

4. 任务适配层（Task Adapter）

4.1 统一接口定义

type TaskStatus = 'todo' | 'in_progress' | 'review' | 'done';

interface TaskAdapter {
  createTask(dto: TaskDTO): Promise<ExternalTaskRef>;
  updateTask(ref: ExternalTaskRef, patch: TaskPatch): Promise<void>;
  completeTask(ref: ExternalTaskRef): Promise<void>;
  setProgress(ref: ExternalTaskRef, status: TaskStatus, progress?: string, deliveries?: string[]): Promise<void>;
  normalizeTaskEvent(raw: unknown): TaskEvent;              // 飞书任务变更 → 平台事件
}

interface TaskDTO {
  title: string;
  description: string;
  assignees: string[];          // 平台用户ID
  due?: Date;                   // 截止时间
  board: string;                // 任务清单/看板
  status: TaskStatus;
  progress?: string;            // Agent 进度描述
  deliveries: string[];         // 交付物摘要
}

4.2 飞书任务映射（FeishuTaskAdapter）

字段映射表（基于 InputTask 模型实证）：

状态机映射：

4.3 双向同步引擎

平台 → 飞书（出站）:
  Agent/用户创建任务 → FeishuTaskAdapter.create_task → 飞书任务
  任务状态/进度变化 → update_task / set_progress（写 agent_task_progress）
  Agent 交付产物 → 摘要写 text_deliveries + 完整产物链到 Web 端

飞书 → 平台（入站）:
  用户完成/修改飞书任务 → task 事件订阅 → TaskEvent → 平台任务更新
  （权限: 任务事件需申请对应订阅权限）

• 冲突策略：平台为准（平台是 source of truth），飞书是协作入口；入站事件仅同步"完成/指派/截止时间"等有限字段，避免回环
• 回环防护：出站更新时携带标记，入站事件中识别并忽略自己写的变化（或按 updated_by 区分）

5. 核心数据模型

-- 渠道绑定：平台频道 ↔ 外部频道
channel_bindings(id, platform_channel_id, adapter, external_chat_id, created_at)
  UNIQUE(adapter, external_chat_id)

-- 消息（中心实体）
messages(id, channel_id, thread_id NULL, msg_type, sender_type, sender_id,
         content JSONB, external_msg_id, event_id, created_at)
  UNIQUE(adapter, external_msg_id)          -- 去重

-- 任务
tasks(id, channel_id, board_id, title, description, status,
      assignee_type, assignee_id, due, progress, external_ref JSONB,
      client_token, created_at, updated_at)
task_boards(id, name, channel_id, settings JSONB)

-- 产物 + 版本（不可变）
artifacts(id, task_id NULL, producer_agent_id, type, storage_ref, created_at)
artifact_versions(artifact_id, version, content_hash, size, creator_id,
                  storage_ref, created_at)  -- 每次产出新版本，只读

-- 审批
approvals(id, tool_call_id, channel_id, requester, target_tool, payload JSONB,
          status, decided_by, decided_at)
audit_logs(id, actor_type, actor_id, action, target, detail JSONB, created_at)

6. Agent 间协作（群聊即协议）

• Agent 间协作直接在频道消息中完成：互相 @、认领任务、接力推进，不引入独立的 A2A 协议层
• 消息即协议：任务、上下文、交付物都在频道消息里流转，天然可审计、可回放
• 对外互通暂不做；若未来需要接入外部 Agent 生态，再评估 MCP / 协议桥（P4 之后）

7. 分阶段实施路线

P0 优先级最高的事项： 飞书管理员审批（权限 scope）、应用可见范围配置——这两项是外部依赖，先走流程。

8. 风险与注意事项

9. 待确认事项（需要你提供）

1. 数据库 / 消息中间件 / 部署方式（是否 K8s）
2. Agent 运行时现状：自研 runtime 还是现成框架？接的哪个 LLM？工具调用方式？
3. 现有模块清单：用户/权限体系、会话存储、文件存储是否已有
4. 团队规模与工期预期
5. 飞书管理后台支持度：能否申请自建应用+权限、可见范围怎么配

确认后可将本方案细化为逐模块的落地实施计划（含接口签名、表结构 DDL、任务拆分）。

Agent 最优工具调用路径学习——记忆系统调研洞察（2026-08-18）

调研日期：2026-08-18 需求：从 agent 的执行记录中找出最优工具调用路径，让 agent 以最快时间完成任务 结论性质：仓库/论文信息均为 VERIFIED（GitHub API + arXiv API 实时查询）；方法论评价为 ASSUMED（分析推断）

一、核心结论

1. 不存在"装上一个就能自动找最优路径"的开源记忆系统 —— 这是当前研究前沿，也是平台级差异化机会。
2. 传统记忆系统（Mem0 / Letta / Graphiti / Cognee）擅长"事实记忆"（用户偏好、上下文、知识），不提供路径优化逻辑。
3. 需求本质 = 经验学习 / 过程记忆（learning from trajectories），最对口的学术方法是 AWM（Agent Workflow Memory）与 Voyager 技能库思想。
4. 最实用架构 = 三层自研管线：记录层（Langfuse）→ 提炼层（评分 + LLM 抽象 workflow 模板）→ 复用层（向量检索 + few-shot / 模板匹配）。

二、第一梯队（需求对口，参考价值最高）

三、第二梯队（2026 前沿论文，未成熟）

• FlowBank（2026-06-09）：Query-Adaptive Agentic Workflows Optimization through Precompute-and-Reuse —— 预计算 + 复用工作流
• VCE-Skill（2026-08-17）：技能自进化，工具版本变化时自动修正旧技能 —— 生产环境实用性强
• AgentHER（2026-03-22）：Hindsight Experience Replay，把失败轨迹重标记为成功路径再训练 —— 反直觉但有效
• ELITE（2026-03-25）：经验学习 + 意图感知迁移，跨任务泛化
• LatentGym（2026-06-13）：跨任务经验学习的可控制测试台

四、工程底座（平台建设会用到）

• Langfuse（Apache-2.0，⭐33.3k，活跃）：开源 LLM 可观测平台，天然记录轨迹/工具调用/耗时/token 成本，带评分功能 —— 数据层来源
• DSPy（MIT，⭐37.4k，活跃）：声明式定义 agent 流程，自带自动优化器（BootstrapFewShot / MIPRO），可从轨迹自动学最佳示例
• LangMem（MIT，⭐1.6k，活跃）：LangChain 系记忆工具包，可做记忆提取
• 自研 Postgres + JSONB 也可替代 Langfuse（存轨迹 JSON + 评分）

五、推荐架构（三层管线）

┌─ 记录层 ─────────────┐   ┌─ 提炼层 ──────────────┐   ┌─ 复用层 ─────────────┐
│ Langfuse / Postgres   │   │ 评分:成功率×耗时×成本   │   │ 新任务 → 向量检索相似  │
│ 记录:轨迹/工具序/耗时/  │ → │ 高分轨迹 → LLM 抽象     │ → │ 历史 → 注入最优轨迹    │
│ token 成本            │   │ workflow 模板(AWM 法)  │   │ few-shot / 模板匹配   │
└───────────────────────┘   └───────────────────────┘   └───────────────────────┘

落地节奏：

• 第一版（数天）：Langfuse 记录 + 评分排序 → 新任务检索相似轨迹 few-shot 注入
• 第二版（护城河）：AWM 式 workflow 模板提取 + 运行时匹配复用
• 第三版：DSPy 自动优化 或 VCE-Skill 式技能自进化

六、证据清单

• GitHub API 实时查询（2026-08-18）：mem0ai/mem0 ⭐63.5k、letta-ai/letta ⭐24.3k、getzep/graphiti ⭐30k、topoteretes/cognee ⭐30.1k、MineDojo/Voyager ⭐7.1k、LeapLabTHU/ExpeL ⭐236、noahshinn/reflexion ⭐3.2k、langfuse/langfuse ⭐33.3k、stanfordnlp/dspy ⭐37.4k、langchain-ai/langmem ⭐1.6k
• arXiv API 实时查询（2026-08-18）：AWM arXiv:2409.07429、FlowBank 2026-06-09、VCE-Skill 2026-08-17、AgentHER 2026-03-22、ELITE 2026-03-25、LatentGym 2026-06-13
• AWM 无官方实现：GitHub 仓库搜索实测为空