跳转至

总体架构

本页是系统架构：分层、组件和数据流。核心抽象（Evidence → Ontology → Runtime Projection）的 canonical 页是 本体驱动上下文架构；产品立意见 产品底层逻辑。

当前定位

OrgReOrg / Harness 是组织级 Agentic Knowledge Infrastructure，更准确地说，是面向团队和公司的 Agentic Context Management SaaS。

它以企业微信、飞书、Web 工作台和共享文件空间作为统一交互入口，但不局限于聊天数据。真实业务信息分散在聊天、会议、员工上传文件、GitHub、财务系统、CRM、项目管理系统、文档系统、BI 等来源中，需要通过 Agentic Search、主动信息收集、Connector / MCP、权限视图和 Loop Engineering 持续转化为可检索、可调用、可授权、可审计的上下文资产。

系统的核心目标是：根据当前用户、当前任务和当前权限，加载足够完成任务的最小上下文集合。上下文不足时主动补充；补充后的信息再进入组织知识资产。

从运行形态看，Framework 很大程度上是在把 Loop Engineering 产品化：把一次性问答升级为有 goal、state、action、verification、persistence、decision 和 notification 的闭环。Context Router、SearchConnector、Ask Router、Knowledge Card、Tool Gateway、Eval Plane 和项目看板共同构成这些 loop 的状态、动作和验证面。

从知识形态看，当前架构收敛为三层：

Evidence 原始证据层
  -> Ontology 本体层
  -> Runtime Projection 运行时投影层

原始资料统一进入 Evidence；元数据、对象、关系、规则、Markdown、ADR、实验报告、Skill、Workflow、权限视图和 writeback 都是 Ontology 中的对象或关系；SearchConnector、MCP、Tool Gateway、Ask Router、企业微信消息和 dashboard 是 Runtime Projection 的实现手段。详见：本体驱动上下文架构。

分层架构

flowchart TD
    U["用户入口<br/>Web 任务工作台 / 企业微信 / 飞书 / 共享文件空间 / CLI / IDE"] --> A["Agent Harness API"]
    A --> F["Frontend Interaction Layer<br/>自然语言、文件空间、表单、审批、业务控件"]
    A --> W["Workflow Plane<br/>任务编排、状态机、人工确认"]
    W --> P["Policy Plane<br/>权限、审批、脱敏、审计"]
    W --> R["Runtime Adapter<br/>Claude Code / Codex / OpenAI Agents"]
    W --> C["Context Ontology & Projection<br/>Evidence / Ontology / Search / Ask"]
    W --> B["Agent Bus<br/>事件、命令、查询、产物"]
    B --> R
    B --> T
    R --> T["Tool Plane<br/>MCP Servers / Function Tools / Internal APIs"]
    C --> T
    T --> S["部门业务系统<br/>GitHub / 财务 / CRM / 项目管理 / 文档 / BI"]
    W --> E["Eval Plane<br/>评测、回归、质量门禁"]
    P --> L["Audit Log<br/>工具调用、输入输出、审批记录"]

当前 Demo 形态

当前 repo 是这套架构的最小产品 Demo。它不是完整企业平台，但已经具备一个团队项目空间的核心构件：

  • framework/：可打包的通用框架、接口、模板、评测和治理检查。
  • workspaces/variai/registry/：当前 Demo 的组织私域拓扑和领域知识索引。
  • workspaces/variai/registry/workspace-topology.json：声明组织、部门、人员、项目、任务、上下文库、路由规则和权限视图。
  • workspaces/variai/evidence/：原始证据、外部来源线索、共享文件空间样例和 Evidence Registry。
  • workspaces/variai/knowledge/：wiki、projects、decisions、system 规则和维护日志。
  • workspaces/variai/evidence/registry/evidence-registry.json：声明原始证据快照、hash、临时外链封口、PII/field mask 和下游制品引用。
  • workspaces/variai/site/：MkDocs 发布站点源码和团队阅读页面。
  • packaging.manifest.json：可打包层、混合层、私域层和生成层的边界清单。
  • workspaces/variai/site/project-progress.md：项目状态看板。
  • framework/ / scripts/ / tests/：framework 承载实验和治理实现，scripts 保留 CLI wrapper，tests 验证行为。
  • workspaces/variai/connectors/wecom/：企业微信 connector 开发边界。
  • AGENTS.md / CLAUDE.md：Agent 工作规则。
  • GitHub / MkDocs / Cloudflare：review、构建和发布链路。

未来给一个公司、部门或项目组交付时，可以先复制这种形态，再让该组织填写自己的 workspace topology，逐步接入企业微信、SearchConnector、Tool Gateway、业务系统 Connector 和 Web 工作台。

同时，当前 repo 必须保持产品打包边界：通用框架、工具、模板、adapter contract、eval harness 和 dashboard generator 可以抽成产品底座；当前项目讨论、路线、实验语境、真实组织信息和业务材料属于私域领域知识，不进入通用包。

详见：团队项目 Repo：产品 MVP 形态、Framework 与 Workspace 边界。

各层职责

Agent Harness API

统一对外入口，负责接收任务、识别任务类型、创建运行上下文，并返回任务状态。

它不直接包含复杂业务逻辑，而是把任务交给 workflow。

在当前目标企业中，协同入口优先按企业微信设计，同时兼容飞书和 Web 工作台。它们承担消息入口、审批通知、通讯录身份、群聊上下文和内部应用入口，但不是完整数据源。真正的业务事实仍需要通过部门系统 Connector 获取。

文件输入是另一条确定入口：员工按项目、部门、个人或任务上传 Word、PPT、Excel、压缩包、代码包、链接说明和业务专用格式文件。这些文件先进入 Evidence Registry，保存 raw snapshot、hash、权限、PII/field mask 和解析状态，再按 parser_hint 进入文档解析、代码包清单、专用格式适配或人工 review。

Frontend Interaction Layer

前端交互层负责把普通员工的工作意图转成后端可执行的任务上下文。

它包括：

  • 自然语言对话。
  • 文件空间。
  • 业务表单。
  • 审批和确认按钮。
  • 任务状态。
  • 结果预览和版本管理。
  • 企业微信通知和跳转。

这层的目标是让员工不需要理解底层 SDK、模型、网络环境和 agent 配置。

Workflow Plane

负责任务编排，包括：

  • 多步骤流程。
  • 状态机。
  • 人工确认。
  • 失败重试。
  • 任务暂停与恢复。
  • 子任务拆分。

这层是企业 agent 的业务核心。

Context Ontology & Projection Plane

Context Ontology & Projection Plane 负责把组织证据、业务对象和可执行能力转成 Agent 可检索、可引用、可裁剪、可审计的上下文。

它包括：

  • Evidence 原始证据保存和 provenance。
  • Evidence Registry：source snapshot、hash、source status、attachment manifest、PII/field mask 和 downstream artifact。
  • Ontology object、relationship、rule、action、writeback。
  • Markdown、ADR、实验报告、知识卡片和任务技能包。
  • Markdown 渐进披露。
  • 文档解析和索引。
  • BM25 全文检索。
  • 向量检索。
  • RRF 融合和 Rerank 重排序。
  • 证据引用。
  • 知识缺口识别。
  • 按权限生成上下文视图。

这层不应只做一次性 RAG。更合适的方式是先把原始资料保存在 Evidence，再抽取成本体对象、知识制品和可执行 Skill；运行时再根据任务和权限投影出最小上下文包。Agent 优先使用入口索引、任务技能包和稳定知识制品，证据不足时再进入检索投影、证据读取或主动询问。

它的目标函数不是“上下文越多越好”，而是在质量、成本和权限之间做取舍：

answer_quality ↑
token_cost ↓
permission_risk ↓
irrelevant_context_noise ↓
knowledge_gap_detection ↑

例如员工办理报销、职能部门修订制度、项目组联合开发系统，三者都需要上下文管理，但需要的上下文集合和权限边界完全不同。

详见：本体驱动上下文架构 和 运行时渐进披露与上下文访问路径。

在组织私域里，Context & Search Plane 还必须读取 workspace-topology.json：个人、部门、项目和组织级上下文库不能默认互通。当前 Workspace Scope Eval 已用个人入职/报销、财务部门政策、OrgReOrg 项目开发三类 demo，以及跨部门项目、员工调岗、项目归档、权限变更 stale index 四类风险探针验证：同一 Framework 可以通过 route_context_libraries 的 context_router_feature_v1 输出候选库评分、feature breakdown、permission view 过滤、trace log 和最终上下文库选择，并阻断故意不安全 connector 的越权输出。

Agent Bus

Agent Bus 负责 Agent-to-Agent 通信。

它支持：

  • 事件发布。
  • 命令请求。
  • 信息查询。
  • 结构化产物传递。
  • trace 和审计。

第一阶段可以先用单体后端中的逻辑 bus 实现，不急于引入复杂分布式基础设施。后续可根据复杂度评估 Zenoh、NATS、Kafka、Redis Streams 等方案。

Runtime Adapter

封装不同底层 agent runtime，例如 Claude Agent SDK、Codex SDK、OpenAI Agents SDK。

目标是让上层 workflow 不直接绑定某个供应商。

这里采用两层结构：Codex、Claude Code、Claude Agent SDK 或 OpenAI Agents SDK 负责底层模型、工具循环、文件阅读、代码执行、subagents 和 hooks；Harness 层负责企业上下文、Context Router、Connector、Workflow、Policy、Eval、审计和 UI。Adapter 只是边界转换层，不重做底层 runtime 的原生能力。

Tool Plane

封装企业能力，推荐优先做成 MCP server 或统一 tool gateway。

这层应该有清晰的数据契约、权限边界、错误码和审计日志。

第一批重点不是泛泛接入聊天记录，而是接入部门业务系统：GitHub、财务系统、CRM、项目管理系统、文档系统、BI 和审计系统。

当前已完成本地 Tool Gateway Safety Harness：用合成工具验证 allowlist、schema hash、scope、R4 approval、R3 draft-only、URL egress、输出脱敏和审计不泄密。第一批接入工具族是 SearchConnector Tool Gateway，已把 context.search、context.get_document、context.report_gap 包到这条调用路径后面。

Policy Plane

负责治理和安全：

  • RBAC / ABAC。
  • 数据脱敏。
  • 工具 allowlist / denylist。
  • 高风险动作审批。
  • 预算限制。
  • 外发内容检查。

Eval Plane

负责持续验证 agent 质量：

  • golden cases。
  • 回归测试。
  • 安全红队测试。
  • 任务成功率统计。
  • 成本和延迟观测。

设计原则

  • 底层 runtime 可替换。
  • 企业工具能力可复用。
  • 业务流程显式编排。
  • 高风险动作必须可审计。
  • 关键任务必须可评测。
  • 不把核心逻辑藏在 prompt 里。
  • 面向普通员工设计入口，而不是只面向工程师设计接口。
  • 支持人与 Agent、Agent 与 Agent 两类交互。
  • 企业微信和飞书是交互入口，不是完整数据源。
  • 业务系统 Connector 必须返回可引用证据和权限元数据。
  • 通用框架层和私域领域知识层必须可分离，产品化时只打包框架、模板、工具和合成样例。
  • Workspace 私域层必须按组织拓扑建模，至少区分个人、部门、项目和组织级上下文库，不能把所有私域知识塞进同一个库。
  • 上下文管理必须同时覆盖输入和输出：输入侧收集、清洗、结构化和沉淀组织知识资产；输出侧按任务与权限组合最小充分上下文给智能体使用。
  • 本体层必须成为统一语义模型：元数据、Markdown、Skill、权限规则、动作、writeback 和实验报告都要能追溯到原始证据。