# Agent Framework 大架构设计 v0 ## 1. 文档目标 本文是面向 design review 的大架构草稿，目标是定义一个非通用 agent framework 的模块职责、用途和能力边界，以及 Investibook 作为上层业务应用的接入逻辑。 本文不展开字段级 API、数据结构、代码目录、数据库 schema 或具体实现。最细粒度只到 feature list。 本文要回答： - framework 应该由哪些大模块组成。 - 每个大模块负责什么。 - 每个大模块干什么用。 - 每个大模块负责什么，不负责什么。 - 上层应用如何接入 framework。 - Investibook 哪些能力保留在应用侧，哪些能力应上移到 framework。 - design review 应该检查哪些边界。 关联文档： - [goal-evaluation-brief-v0.md](goal-evaluation-brief-v0.md) - [investibook-score.md](investibook-score.md) - [hub9-score.md](hub9-score.md) ## 2. 总体定位 这个 framework 不是通用 agent graph framework，而是生产业务应用平台。 它的目标不是让 agent 更自由，而是让业务团队更快长出应用、更快上线生产、更持续地证明业务价值。 因此整体架构应按 Investibook Biz、Application Framework 和 Foundation Infrastructure 三层来划分： ```text Investibook Biz | Application Framework | Foundation Infrastructure ``` 三层职责必须清楚： | 层级 | 核心职责 | 干什么用 | |---|---|---| | Investibook Biz | 承载 Investibook 业务价值和 TiDB diagnosis domain | 定义 evidence、diagnosis workflow、domain tools、workspace UX、domain eval、business metrics | | Application Framework | 提供生产应用平台能力 | 复用应用工厂、runtime、context、tool gateway、artifact、memory、governance、eval、release | | Foundation Infrastructure | 提供底层基础设施 | 提供 db9、fs9、mem9、queue、trace、storage、deployment、observability 基础设施 | ## 3. 大模块总览 framework 的大模块如下： | 大模块 | 核心职责 | 干什么用 | |---|---|---| | Investibook Biz | 承载 Investibook 的业务和领域技术边界 | 服务 TiDB 故障诊断、evidence、workspace、domain eval 和业务价值证明 | | Application Factory | 快速生成应用骨架 | 服务应用创建者 | | Application Contract Layer | 定义应用接入契约 | 服务应用创建者、runtime、reviewer | | Runtime Platform | 运行 workflow 和 agent | 服务 agent 应用和 workflow | | Context Platform | 管理模型运行输入 | 服务 agent runtime、eval、security | | Tool Integration Platform | 管理工具接入和副作用 | 服务 domain tools、外部系统 | | Data & Artifact Platform | 管理 state 和 artifact 边界 | 服务 runtime、UI、eval、audit | | Memory Platform | 管理长期记忆和 recall | 服务 agent runtime、应用团队 | | Governance Platform | 管理安全、权限和治理 | 服务租户、用户、合规、审计 | | Evaluation & Improvement Platform | 管理 eval 和持续改进 | 服务 release、quality、business review | | Release & Operations Platform | 管理发布和生产运行 | 服务 production service | | Foundation Infra | 提供底层运行基座 | 服务 framework 和所有上层应用 | ### 3.1 大技术架构图 大技术架构图不再用仓库内 Mermaid/SVG 承载。正式图在飞书文档中维护，避免 Mermaid/SVG 预览缺字或样式不稳定。 飞书文档： - https://pingcap.feishu.cn/docx/P5frddF2aogGWLxOpC7cpPxanRh 图的核心表达： | 大框 | 内部概念 | 对外关系 | |---|---|---| | Investibook Biz | evidence、diagnosis workflow、domain tools、workspace UX、domain eval、business metrics | 通过 app contract 和 Investibook domain package 接入 framework | | Application Framework | create/contract、runtime/context/tool gateway、artifact/memory/evaluation、governance/release/ops | 把 Investibook Biz declaration 变成 production service | | Foundation Infrastructure | db9、fs9、mem9、queue、scheduler、trace、secrets、deployment substrate | 作为 framework backend capabilities，不直接暴露为业务隐式依赖 | ## 4. 模块职责和边界 ### 4.1 Investibook Biz 职责边界：Investibook Biz 承担 Investibook 的业务和领域技术边界。 干什么用：这一层用于承载 TiDB 故障诊断应用本身，包括 evidence、diagnosis workflow、domain tools、domain knowledge、workspace UX、domain eval 和业务价值证明。 负责： - evidence。 - diagnosis workflow。 - Clinic / TiDB tool binding。 - domain knowledge 和提示词。 - workspace UX。 - domain eval cases。 - business metrics 和价值证明。 不负责： - 通用 runtime。 - 通用 context 管理。 - 通用 tool permission。 - 通用 artifact 存储。 - 通用 memory backend。 - 通用 eval runner。 - 通用 release gate。 Feature list: - evidence model。 - diagnosis workflow。 - domain tool binding。 - domain prompt pack。 - workspace UX。 - domain eval cases。 - business value dashboard。 ### 4.2 Application Factory 职责边界：Application Factory 承担应用生成和模板化交付职责。 干什么用：让业务团队从需求快速生成可 review、可部署、可评估的应用骨架。 负责： - 应用骨架生成。 - workflow 模板。 - tool 模板。 - context policy 模板。 - eval 模板。 - deployment 模板。 - review checklist 模板。 不负责： - 判断业务需求是否合理。 - 替业务团队定义领域知识。 - 替业务团队证明业务价值。 Feature list: - app scaffold。 - workflow scaffold。 - tool scaffold。 - UI shell scaffold。 - eval scaffold。 - deployment scaffold。 - policy scaffold。 - example app gallery。 ### 4.3 Application Contract Layer 职责边界：Application Contract Layer 承担 framework 与业务应用之间的接入契约职责；业务应用只填充领域内容。 干什么用：把应用如何接入 runtime、context、tools、artifact、memory、eval、release 变成可 review 的声明。 负责： - 定义一个应用需要声明什么。 - 定义应用如何接入 runtime、context、tools、artifact、memory、eval、release。 - 定义应用上线前 review 的边界。 不负责： - 保存业务数据。 - 执行 agent。 - 调用外部工具。 - 替代业务应用逻辑。 Feature list: - app contract。 - workflow contract。 - tool contract。 - context policy。 - memory policy。 - artifact policy。 - eval policy。 - release policy。 ### 4.4 Runtime Platform 职责边界：Runtime Platform 承担 workflow 和 agent 的运行职责。 干什么用：负责把已通过 contract 声明的 workflow 运行成可追踪、可恢复、可治理的生产 run。 负责： - run lifecycle。 - workflow orchestration。 - agent runtime adapter。 - human-in-loop handoff。 - cancellation / retry / resume。 - runtime trace。 - runtime cost tracking。 不负责： - 领域业务判断。 - 直接读写业务系统状态。 - 绕过 tool gateway 调用工具。 - 自行决定 context 内容。 Feature list: - run orchestrator。 - workflow state manager。 - agent adapter。 - session mapping。 - retry and resume。 - human approval hook。 - runtime trace。 - runtime cost meter。 ### 4.5 Context Platform 职责边界：Context Platform 承担模型运行输入的管理职责。 干什么用：控制模型每次调用能看到什么，并管理 raw payload、compact context、memory、tool output 和 artifact 的边界。Context Platform 是独立大模块，不是 Runtime 的附属功能。 负责： - 决定模型调用时能看到什么。 - 管理 raw payload、compact context、memory、tool output、artifact 的边界。 - 做 context assembly。 - 做 context compaction。 - 做 memory retrieval 注入。 - 做 context replay。 - 做 context redaction。 不负责： - 保存业务最终状态。 - 直接执行工具。 - 直接管理长期 memory 存储后端。 - 用 prompt 代替 workflow state。 Feature list: - context builder。 - context packet。 - context budget policy。 - evidence packing。 - artifact reference injection。 - memory retrieval injection。 - compaction policy。 - redaction policy。 - context replay。 - context quality checks。 ### 4.6 Tool Integration Platform 职责边界：Tool Integration Platform 承担工具 gateway 和副作用治理职责；业务应用只声明领域工具内容。 干什么用：让 agent 通过受控 gateway 使用外部系统、凭证、审批和审计。 负责： - tool registry。 - tool permission。 - credential binding。 - approval binding。 - idempotency。 - side effect tracking。 - tool result normalization。 - tool call audit。 不负责： - 定义所有领域工具。 - 绕过业务应用的 workflow。 - 让 agent 直接持有长期 credential。 Feature list: - tool catalog。 - tool schema registry。 - credential broker。 - permission checker。 - approval gate。 - idempotency key manager。 - side effect ledger。 - tool result formatter。 - tool audit trail。 ### 4.7 Data & Artifact Platform 职责边界：Data & Artifact Platform 承担 workflow state 与 artifact 边界管理职责，并使用 foundation infra 提供的存储能力。 干什么用：把 raw artifact、compact artifact、authored artifact 和 workflow state 分层存储、引用和审计。 负责： - workflow state 存储接口。 - artifact 存储接口。 - raw artifact 和 compact artifact 分层。 - file isolation。 - artifact manifest。 - artifact lifecycle。 - artifact access policy。 不负责： - 决定业务语义。 - 把 raw artifact 直接塞进模型上下文。 - 把 artifact 当业务最终状态。 Feature list: - workflow state store。 - artifact store。 - fs9-like file surface。 - raw artifact layer。 - compact artifact layer。 - authored artifact layer。 - artifact manifest。 - artifact retention。 - artifact viewer。 - artifact access control。 ### 4.8 Memory Platform 职责边界：Memory Platform 承担长期记忆与 recall 的产品/平台职责，foundation infra 提供 backend。 干什么用：让应用可以持久化、检索、治理跨 session 的 agent memory，而不是替代 workflow checkpoint。mem9 是当前最相关的参考组件。 负责： - persistent memory。 - hybrid recall。 - memory CRUD。 - session ingest。 - memory isolation。 - memory governance。 - memory dashboard。 - memory evaluation。 不负责： - 保存业务最终状态。 - 替代 workflow checkpoint。 - 无条件把记忆注入 prompt。 - 保存 secret 或未经授权的 raw payload。 Feature list: - mem9-like memory backend。 - memory write policy。 - memory retrieval policy。 - memory confidence score。 - memory source tracking。 - app / tenant isolation。 - memory lifecycle state。 - memory review UI。 - memory cleanup。 - memory eval。 ### 4.9 Governance Platform 职责边界：Governance Platform 承担生产安全、权限、审计和合规治理职责。 干什么用：把 tenant、identity、RBAC、credential、DLP、retention 和 audit 统一成 framework 级能力。 负责： - tenant isolation。 - user identity。 - RBAC / scope。 - credential policy。 - approval policy。 - audit trail。 - DLP。 - retention。 - compliance review。 不负责： - 业务 workflow 设计。 - 模型输出质量评估。 - 应用 UI 细节。 Feature list: - tenant management。 - user / role management。 - scope policy。 - credential vault integration。 - approval workflow。 - audit log。 - DLP scanner。 - secret redaction。 - retention policy。 - compliance report。 ### 4.10 Evaluation & Improvement Platform 职责边界：Evaluation & Improvement Platform 承担通用 eval、run replay 和 regression 能力；业务应用提供领域 eval 内容和业务成功标准。 干什么用：用 evidence、context、tool result、artifact 和业务指标证明版本是否真的变好。 负责： - eval case registry。 - run replay。 - artifact-based scoring。 - state-based scoring。 - context quality scoring。 - tool correctness scoring。 - regression tracking。 - baseline comparison。 - release quality gate。 不负责： - 只评分 final answer。 - 替业务团队定义业务成功标准。 - 无证据地提升版本。 Feature list: - eval registry。 - eval runner。 - deterministic judge。 - semantic judge。 - context evaluator。 - tool evaluator。 - artifact evaluator。 - regression dashboard。 - baseline manager。 - release comparison。 ### 4.11 Release & Operations Platform 职责边界：Release & Operations Platform 承担生产发布、运行保障、SLO、quota 和成本控制职责。 干什么用：把应用从可运行推进到可发布、可回滚、可观测、可控成本的生产服务。 负责： - deployment。 - release versioning。 - rollout。 - rollback。 - runtime SLO。 - quota。 - budget。 - incident response。 - production observability。 不负责： - 定义业务领域。 - 改写应用 workflow。 - 替代 eval 判断。 Feature list: - app deployment。 - version registry。 - prompt/model/tool versioning。 - release gate。 - canary rollout。 - rollback。 - SLO dashboard。 - quota manager。 - budget manager。 - incident dashboard。 ### 4.12 Foundation Infra 职责边界：Foundation Infra 承担底层基础设施能力。 干什么用：给 framework 提供数据库、文件、memory、queue、observability、secret 和 deployment substrate。 负责： - database backend。 - file/artifact backend。 - memory backend。 - queue。 - scheduler。 - observability。 - secrets backend。 - deployment substrate。 不负责： - framework 产品边界。 - 业务应用逻辑。 - context policy。 Feature list: - db9。 - fs9。 - mem9。 - queue service。 - scheduler。 - trace storage。 - metrics storage。 - log storage。 - secret manager。 - deployment platform。 ## 5. db9 / fs9 / mem9 的架构位置 | 组件 | 接入的大模块 | 组件职责 | 干什么用 / 不干什么 | |---|---|---|---| | db9 | Foundation Infra / Data & Artifact Platform | agent-native serverless Postgres backend | 用于 application scaffold、backend state、artifact metadata、workflow state；不是 memory 产品，也不是业务应用直接依赖 | | fs9 | Foundation Infra / Data & Artifact Platform | file/artifact surface | 用于 raw context、artifact、session snapshot 的文件化隔离和访问；不承载业务语义 | | mem9 | Foundation Infra / Memory Platform | persistent agent memory backend | 用于跨 session memory 的写入、检索和治理；不是 workflow checkpoint，也不保存最终业务状态 | db9/fs9/mem9 是 framework 的 backend capabilities，不应该直接变成业务应用的隐式依赖。业务应用通过 framework contract 使用它们。 ## 6. Investibook 接入边界 Investibook 是第一个 reference application，不是 framework 本身。 ### 6.1 Investibook 保留的应用职责 职责边界：这些是 TiDB 故障诊断应用职责。 Feature list: - TiDB incident diagnosis workflow。 - Clinic / TiDB diagnosis domain knowledge。 - diagnosis skill prompts。 - evidence interpretation rules。 - diagnosis workspace UI。 - incident report UX。 - TiDB-specific eval cases。 - diagnosis business value metrics。 这些能力不应该上移到 framework，否则 framework 会变成 TiDB diagnosis 专用系统。 ### 6.2 framework 应承担的平台职责 职责边界：这些是跨应用复用的平台职责。 Feature list: - run lifecycle。 - runtime session envelope。 - context builder。 - context compaction。 - artifact manifest。 - tool gateway。 - memory gateway。 - eval runner。 - release gate。 - audit and governance。 - cost and quota。 这些能力不应该由 Investibook 独自维护，否则其他业务应用无法复用。 ### 6.3 Investibook 当前能力映射 | Investibook 当前能力 | 当前职责位置 | 目标职责位置 | 接入方式 | |---|---|---|---| | ACP runtime session | Investibook | framework | 先 overlay，不重写 | | `messages_v2` chat/trace | Investibook | framework trace platform | 先保持现状，补 run mapping | | workspace evidence files | Investibook | Data & Artifact Platform | 保留 file-first，补 artifact manifest | | `workspace_evidence_report.json` | Investibook | Context Platform / Artifact Platform | 保留 compact report 地位 | | `analysis_patch.json` | Investibook | Artifact Platform / Eval Platform | 保留 authored artifact 地位 | | evidence compaction | Investibook | Context Platform | 抽象为 context feature | | eval runner / judge | Investibook | Evaluation Platform | 先映射，再泛化 | | token/cost records | Investibook | Operations Platform | 先接入 common cost model | | admin/auth | Investibook | Governance Platform | 外部生产前必须上移 | ## 7. Investibook 接入路径 ### Phase 0: Responsibility boundary overlay 目标是不改现有行为，只标清职责边界。 Feature list: - 标记每次 diagnosis run。 - 标记 ACP session 和 workspace 的映射。 - 标记 artifact 职责边界。 - 标记 context 职责边界。 - 标记 eval 职责边界。 - 保持现有 UI 和 evidence 文件不变。 ### Phase 1: Context Platform 接入 目标是把 Investibook 当前最强的 evidence/context 能力抽象成 framework capability。 Feature list: - context builder overlay。 - compact evidence input。 - raw artifact exclusion。 - context replay。 - context quality checks。 - memory shadow recall。 ### Phase 2: Artifact Platform 接入 目标是让 evidence file-first 模式成为 framework 可复用能力。 Feature list: - artifact manifest。 - raw / compact / authored artifact 分层。 - report artifact registration。 - evidence write 职责边界。 - artifact access policy。 - eval artifact resolution。 ### Phase 3: Tool Gateway 接入 目标是让 Clinic/TiDB 工具通过 framework gateway 运行。 Feature list: - tool registry。 - tool call ledger。 - credential binding。 - approval gate。 - idempotency。 - side effect tracking。 - tool result normalization。 ### Phase 4: Production Governance 接入 目标是从内部工具走向生产服务。 Feature list: - tenant isolation。 - role/scope model。 - credential policy。 - DLP。 - retention。 - audit trail。 - budget/quota。 - release gate。 ## 8. 大模块交互边界 | 交互 | 允许 | 不允许 | |---|---|---| | Investibook Biz -> Runtime | 提交 workflow run | 直接控制 runtime internals | | Runtime -> Context | 请求 context packet | 自己拼接不可审计 prompt | | Context -> Memory | 按 policy 检索 memory | 无条件注入 memory | | Context -> Artifact | 引用 compact artifact | 直接注入 raw artifact | | Runtime -> Tool Gateway | 通过 gateway 调工具 | agent 直接持 credential 调工具 | | Tool Gateway -> Artifact | 写 tool result artifact | tool stdout 成为 evidence source of truth | | Eval -> Artifact/Trace | 基于 artifact 和 trace 评分 | 只看 final answer | | Release -> Eval | 使用 baseline gate | 无 eval 发布 | ## 9. Review Checklist ### 9.1 大架构 Review - 大模块是否足够少，边界是否清楚。 - 每个模块是否有明确职责。 - 每个模块是否知道自己不负责什么。 - framework 是否仍是业务应用平台，而不是 agent graph runtime。 - db9/fs9/mem9 是否作为 backend capabilities，而不是业务逻辑。 ### 9.2 Investibook 接入 Review - Investibook 是否保留 TiDB diagnosis domain 职责。 - framework 是否承担 runtime/context/artifact/tool/eval/governance common capabilities。 - 接入路径是否避免一次性重写。 - 现有 evidence file-first contract 是否被保留。 - 现有 eval loop 是否不被破坏。 ### 9.3 Context Review - Context Platform 是否是独立模块。 - raw payload 是否不会直接进入 prompt。 - compact evidence 是否能追溯 raw artifact。 - memory 是否通过 policy 注入。 - context replay 是否是 framework feature。 ### 9.4 Governance Review - tenant、user、role、scope 是否归 Governance Platform。 - credential 是否不由 agent 或业务应用直接长期持有。 - high-risk action 是否必须 approval。 - audit、DLP、retention 是否覆盖 memory、artifact、trace、eval。 ## 10. 当前建议 短期建议： 1. 把本文作为大架构 review 输入。 2. 先确认大模块职责和边界，不讨论字段级 API。 3. Investibook 先做 responsibility boundary overlay，不做重构。 4. 优先把 `Context Platform` 和 `Artifact Platform` 抽象出来，因为这是 Investibook 当前最强也最可复用的能力。 5. mem9 作为 Memory Platform 的后端候选，先 shadow recall。 6. db9/fs9 作为 Foundation Infra 和新应用 factory backend 候选，不强行迁移 Investibook。 中期建议： 1. framework 能 scaffold 新业务应用。 2. 新业务应用默认接入 runtime、context、artifact、tool、eval、governance。 3. Investibook 成为 reference application。 4. 用 Investibook 的真实经验反向修正 framework 模块边界。 ## 11. 待决策问题 | 问题 | 决策点 | |---|---| | Application Factory 的职责边界 | 是独立模块，还是并入 Runtime Platform | | Context Platform 的职责边界 | 是否独立模块，还是并入 Runtime Platform | | Artifact Platform 的默认 backend | 继续 file-first，还是默认 fs9-like backend | | Memory Platform 的默认 backend | mem9 是否进入默认能力集合 | | Investibook 接入优先级 | 先 context，还是先 artifact | | Governance 的最小 P1 边界 | 内部试运行需要哪些必选 governance features | | P2 release gate | eval、security、cost 哪些必须阻断发布 |