研究报告AI Agent 项目群

AI Agent 项目群：从实验仓库到可运行平台

这篇把两层内容整理成一张项目层知识图谱：一层是 GitHub 上刻意做小、各自验证 Agent 工程某一部分能力的个人实验仓库；另一层是在生产环境里把这些能力拼成可运行平台后沉淀下来的架构判断。它回答一个问题：Agent 工程到底由哪些部分组成，每一部分该怎么被验证、被约束、被评估。

总体判断

Agent 平台不是单一模型调用，也不是一个提示词模板库。真正可持续的 Agent 工程至少包含六个部分：

  • Runtime：任务状态、上下文、工具执行和轨迹记录。
  • Tools：MCP、内部 API、文件、命令、浏览器和业务系统能力。
  • Safety：权限、审批、风险分类、工作区边界和敏感数据隔离。
  • Knowledge：RAG、引用、缓存、文档处理和知识库。
  • Evals：golden set、LLM-as-Judge、回归基线和实验对照。
  • Observability：日志、Trace、Langfuse、执行回放和成本监控。

下面先按仓库看每一层被单独验证的样子，再看它们在平台工程里怎么被组装起来。

Sure：面向真实业务的写作 Agent

sure 是一个面向中文保险顾问的微信公众号写作 Agent。它运行在 Cloudflare Worker 上，使用 D1、R2、Queues、Durable Objects、Workflows、Workers AI，以及 Claude Agent SDK runner。

这个项目沉淀的知识点是：Agent 产品要把“聊天生成内容”变成“可交付业务流程”。Worker 负责公开路由、数据持久化、队列分发和安全边界；Sandbox runner 负责 Claude Agent SDK 执行；写作 skill 则把领域写作经验固化成可复用能力。

它对应的知识节点是 Cloudflare、Workers、Queues、Durable Objects、Workflows、Sandbox、Agent Runtime、Skills Hub 和生产验证。Cloudflare 这套边缘运行时的取舍，另见 Cloudflare Workers 与 Bindings 笔记。

SAC Agent：软件工程 Agent 的安全骨架

sac-agent 是教学向 Python 软件工程 Agent。它当前不追求完整自动编码，而是把边界拆清楚：仓库检查、命令风险分类、审批请求、patch 应用和 TUI 会话记录。

这个项目的价值在于刻意保留“慢”的部分：模型、shell、工具和文件系统是不同信任域。读仓库可以低风险，执行命令要分类，修改文件要走明确 patch primitive。未来模型能力增强，也不应该绕过这些边界。

它对应的知识节点是 Agent Runtime、Approval、Tool Safety、Patch、TUI、Python 和软件工程教育。

SAC Agent4J：用 Java 手写最小 Agent Loop

sac-agent4j 是一个手写 Java SWE Agent。它刻意避开 Spring AI、LangChain4j 和大型框架，用最小循环暴露 Agent 的本质：

build context -> ask for one JSON action -> execute tool -> record observation -> repeat

这个项目验证的是：Agent 框架可以很复杂，但核心抽象必须可解释。一个可教学、可调试的 Agent Loop 需要计划、todo、虚拟文件、上下文卸载、读文件、搜索、shell、patch、测试和 finish 这些基础动作。

它对应的知识节点是 Java、Agent Loop、Context、Tool Use、Test Feedback、Trajectory 和 GraalVM。把 Loop 之外的运行环境单独拎出来看，见 Harness Engineering。

Agent Lab：评估和可观测性的实验室

agent-lab 把 FastAPI coding agent、Langfuse、Postgres、ClickHouse、Redis、MinIO 和 Docker Compose 组合成实验环境。它不仅能跑 Agent，还能做 skill evaluation、baseline/treatment 对照、重复运行和证据导出。

这个项目沉淀的核心能力是 Evals。没有评估，Agent 的提升只是主观感觉；有了 benchmark、run id、评分、pass-rate、错误率和输出证据，才有可能比较不同 skill、prompt 或 runtime 设计的效果。评测怎么防止“跑分被误读”，另见 AI Eval Harness。

它对应的知识节点是 Langfuse、Evals、Benchmark、Coding Agent、FastAPI、Docker Compose 和观测闭环。

DDIA Skill：把架构判断固化为 Skill

ddia-skill 把数据密集型系统设计判断整理成 Codex skill。它关注数据库选择、复制、分区、事务、幂等、派生数据、流处理、故障模式和验证实验。

这个项目说明：skill 不只是“提示词文件”，而是可以被评估、对照和迭代的工程资产。它把架构师经验从一次性回答转成可复用的判断流程，并用 benchmark 约束质量。

它对应的知识节点是 DDIA、Skill、系统设计、数据一致性、幂等、事务、故障模式和验证。

OpenAI Agentic RAG：知识库的基本工程边界

openai-agentic-rag 是长文档 RAG 问答系统。它把文档分块、检索、答案合成、引用、缓存、模型选择和 LLM-as-Judge 验证拆成独立模块。

这个项目的价值在于把 RAG 从“向量库加模型”推进到工程系统：答案要有引用，模型选择要有策略，缓存要能降低成本，验证要能发现幻觉和漂移。

它对应的知识节点是 RAG、Document Chunking、Citation、Cache、Routing、Synthesis、Verification 和 LLM-as-Judge。RAG 该在哪里显式暴露边界、哪里不该静默降级，另见 LlamaIndex RAG 的能力边界。

K12 与 RoboLabX：垂直场景 Agent 产品化

k12 记录了 RoboLabX 的 Cloudflare standalone 方向，也保留了依赖 gateway、identity、workspace、storage 的平台化路径。它体现了一个典型取舍：垂直产品可以先独立运行，但长期仍要和平台能力连接。

这个项目对应的知识节点是教育场景、Cloudflare、Gateway、Identity、Workspace、Storage、Agent Skill 和产品边界。

Tachi：Agent 工作状态的本地可视化

e-acc 当前产品名是 Tachi。它不是编码 Agent，而是读取 Claude Code 和 Codex 的本地会话痕迹，把后台运行状态变成菜单栏和面板里的持续感知。

这个项目说明 Agent Native 软件不只发生在“模型生成代码”的瞬间，也发生在人的工作流感知里。AI Coding 会产生大量后台状态，Tachi 试图把这些状态变成低打扰、可理解的环境信号。

它对应的知识节点是 Codex、Claude Code、Local-first、macOS、Session Awareness 和 AI Coding Workflow。

从实验拼成平台：生产环境沉淀的判断

上面的仓库各自把一层能力做小做透。真正的难度在于把它们拼进一个多租户、可审计、要对客户负责的平台里。下面几条是在生产环境（Bite Investments、CosX AI、Xeni Legal 等阶段）反复出现、并且换了赛道仍然带得走的判断。

Agent Runtime 与“业务线即 Skill”

平台侧的通用 Agent Runtime 把一条业务线抽象成一个声明式技能文件：YAML frontmatter + 系统提示词 + 可选的配置、工具、提示词与资产。运行时由 skill loader 解析、单例 registry 管理并支持热加载。新增一条业务线，只需要新增一个技能声明加配置，不必改平台代码。

会话链路是一条清晰的流水线：会话管理器按会话串行排队 → 上下文构造器并行组装记忆、摘要与历史并做 token 预算控制 → 会话执行层封装 Claude Agent SDK → 后处理负责内联工具指令解析、拒答检测、实时广播，以及用更便宜的模型做后台摘要与记忆抽取。

这条判断的本体是：用可插拔的声明式配置承载易变的业务规则，用少量稳定的运行时承载不变的编排逻辑。 sure 的 Skills Hub、sac-agent4j 的最小 Loop 就是这条判断在个人仓库里的两个切片；把运行环境单独看一层，见 Harness Engineering。

平台能力分层：网关 / 身份 / 工作区

一个多租户 Agent 平台，认证（你是谁）和授权（你能做什么）必须解耦，权限计算要下沉，不在每个下游服务各自重写。落地成三层：

  • 网关（BFF）：无状态 JWT 校验加撤销令牌缓存同步、粗粒度 RBAC 加工作区级鉴权、服务发现路由、限流、分布式链路追踪、Webhook 签名校验；并用自定义的 Share-Code Grant 解决访客与共享访问。
  • 身份：基于 Spring Authorization Server 的 OAuth 2.1，支持 TOTP、Passkey（WebAuthn）、邮箱一次性码，以及联邦登录与自动关联、动态客户端注册。
  • 工作区：多租户层级 RBAC、邀请系统、按工作区的 AI 模型策略与默认回退、合规资质登记、异步审计日志。

这套分层不是凭空来的。它上承更早在基金 FinTech 平台做的资源-主体权限模型——资源树加主体树，操作权限带有效期，支持继承、合并取更严格值、链式校验（父级任一无权限即整体无权限），文件树类与非文件树类用两套构建算法。“按有效期收回权限”“网关统一校验、权限下沉”这两条判断一直延续了下来。完整的平台架构脉络见 SaaS 云原生平台架构 与 架构师知识图谱。

法律 Workflow：状态归 LangGraph，能力边界归 Tools

Xeni Legal 是一个面向英国移民法（首条路线是技术工签）的案件协作副驾。主流程是一条可审计的链路：建立 Matter 与 Application → 结构化 Intake → 上传证据 → 抽取 Profile → 检索法规 → 逐项 Requirement 审查 → 生成 Review Pack → 律师批准 → 交接。

这条业务线最核心的架构判断有三点：

  1. 状态和能力分开归属。 工作流状态机归 LangGraph 拥有；LangChain Tools 是 Agent 与系统能力之间唯一的业务能力边界，按 Read / Suggest / Write 分级；边缘的 Cloudflare Worker 只做适配和网关，不承载业务编排。后期进一步演进成以编排器加多个专职子 Agent（证据分析、Profile 抽取、法规检索、需求评估、Review Pack 撰写）协作的形态，并引入虚拟文件系统作为共享工作区。
  2. Schema 由系统定义，AI 只填值不发明结构。 Profile 契约分三层（全局 → 签证类型扩展 → 目标表单映射），每个字段带一个信封：值、置信度、状态、来源；状态机是 suggested → confirmed / rejected / superseded，只有 confirmed 才允许提交，映射到外部表单必须走显式 mapping。用户证据与策展的权威法规知识严格分开，抽取出来的每个属性都保留出处。
  3. 宁可显式阻断也不静默降级。 法规检索不可用时，run 直接标记为 blocked，绝不编造法律结论；RAG 只负责提供引用，不能当作必填字段的唯一事实源。

简历口径的可公开结果：单租户可同时对 200+ 文件做 AI 分析处理，准确率 90%+，AI 填表 P99 约 5 秒每页面。为什么“检索基础设施不可用就该显式失败，而不是退化成关键词匹配”，展开在 LlamaIndex RAG 的能力边界。

两类 RAG 与知识注入四层

法律这类高风险场景，RAG 要拆成两类不能混：证据 RAG 处理用户上传的材料，知识 RAG 处理权威法规知识——后者必须带引用来源，并能按辖区、签证类型、条款版本过滤。规则的唯一事实源是知识库本身，不是模型的记忆。

知识注入则是一条渐进策略：内置知识 → Prompt 注入 → 按需检索的 MCP Tool → 向量库 RAG。高频、稳定的规则先注入 prompt 就能解决；只有超出上下文预算、或需要大范围检索时，才升级到按需检索与向量库。先解决 80% 的高频问题，再为长尾付向量库的成本。

模型接入统一走 Model Gateway：用 LiteLLM 做多供应商统一接入，换来集中限流、Key 轮换和成本追踪；可观测走 Langfuse，按 Response ID 追踪每一次调用。这一层对应个人仓库里的 openai-agentic-rag 与 agent-lab。

教育场景：通用消息持久化与业务编排拆分

K-12 教育 Agent（即 RoboLabX / k12）先用一个单体 chat 应用做 POC 验证，POC 结束后主导做了一次关键拆分：把“通用的 AI 消息持久化”拆成一个与业务解耦、可复用的服务，把“业务专属编排”拆成该教育业务线专属的后端（接入 Agent SDK 与定制提示词），前端交给专职团队。

这条决策的价值在于为后续新业务线复用打底：通用能力沉淀成可复用服务，易变的业务编排各自演进——和“业务线即 Skill”是同一条“稳定通用能力与易变业务分层”的判断。

AI 产出不能自证：verdict 双签

进入 AI 原生研发流程治理之后，最核心的一条原创方法论是：AI 产出不能自己证明自己有效，裁判权必须交给确定性程序。 它是一个通用的“证据分级 + 双签 + 防伪 + 分级降级”模式，不限于测试验证。

  • 两个签名，分开存放。 结论签（执行方给出，必须附上原始证据信号的指针）和证据签（脚本机械重算后回签）分离成一份机器可重算的 sidecar，人读的报告与机判的证据文件分开。脚本每次运行整体撕掉旧签重算，杜绝预填造假。
  • 准入由脚本计算写回，退出码 0 / 1 / 2 / 3 分别对应“全通过 / 有失败 / 清单缺失或非法 / 脚本内部错误”四态，供阶段锁、夜间循环、CI 服务端复核、人工抽查四方下游各自消费。
  • 判不了的语义项走“具结 + 人工抽查”，留下实物证据进抽查池，绝不冒充硬门禁。
  • 信任不会消失，只会集中：集中到一个小而可审计的 evaluator 上；同一次运行禁止修改评价规则本身，新规则要经历史重放与影子对比才能晋级。
  • 有证据的阻塞是合法结果，能胜过绕过门禁的“完成”——红灯亮起说明机制在正确工作。输入无法无损适配时，宁可给“无结论”，也不为任何一端补造事实。

同一原则可以用在两个层面：交付物准入用双签验证；流程本身是否变好，则用历史卷宗做可重放、盲评、多数决的 A/B 实验，判定权同样交给按权重重算的确定性程序，而不是让模型自评。

存量代码补测也是同一套诚实边界：生产代码默认只记录，发现缺陷先用特征化测试锁定现状再走授权修复，禁止靠降门禁、跳过必需集成测试或迎合疑似缺陷来“制造绿色结果”。相关判断见 用 AI 写测试 与 AI Eval Harness。

这套方法论背后的第一性原理，可以用五个词概括——工作记忆、外部记忆、工具、循环、停止条件，展开见 AI Native 第一性原理。

项目群之间的关系

个人实验仓库可以组成一条从最小模型到生产交付的链路：

  1. sac-agent4j 解释 Agent Loop 的最小模型。
  2. sac-agent 加入安全边界和审批模型。
  3. openai-agentic-rag 补上知识库和答案验证。
  4. ddia-skill 把专家判断固化成可复用 skill。
  5. agent-lab 对 skill 和 Agent 行为做评估。
  6. sure 把 Agent 交付到真实业务和生产运行环境。
  7. k12 和 Tachi 扩展到垂直场景和工作流感知。

平台工程沉淀的判断，则把这些切片拼成了一个可运行、可约束、可评估的整体：

  • Runtime 与 Skill 分层 让新业务线接入只加一个声明式配置，不改平台代码。
  • 网关 / 身份 / 工作区分层 把认证、授权、租户边界解耦，权限计算下沉。
  • 法律 Workflow 把工作流状态、工具能力边界和边缘适配严格分开，两类 RAG 各司其职。
  • 知识注入四层与 Model Gateway 控制知识成本与模型接入。
  • verdict 双签 把“AI 产出的可信度”从主观感觉变成确定性程序能复算的结论。

这条从实验到平台的路径，也解释了 架构师知识图谱 里那句 AI 工程判断：先能执行，再能被约束；先能观测，再谈优化；先能评估，再谈规模化。