ontology-harness 实现原理学习笔记

1. 产品定位（设计文档口径）

2. 整体架构图（DeerFlow vs Harness）

图 A · 能力边界：左侧 Harness 产品化，右侧 DeerFlow 运行时。

flowchart LR
  subgraph C["调用方"]
    BFF["BFF / H5"]
  end
  subgraph H["Harness"]
    API["controllers"]
    SVC["Run / Proactive"]
    MW["中间件 + Blocks"]
    DB["harness 表"]
  end
  subgraph D["DeerFlow"]
    CL["Client x5"]
    G["Agent 图"]
    CP["checkpoint"]
    SB["沙箱 / MCP"]
  end
  subgraph X["外部"]
    ONTO["copy_ontology"]
    MEM["DeerMem"]
  end
  BFF --> API --> SVC --> CL --> G
  G --> CP
  G --> SB --> ONTO
  SVC --> MW --> DB
  MW -.-> MEM
  G -.-> MEM

3. DeerFlow vs 自研：边界怎么切

4. 一次 Run：创建 → 调度 → 执行 → 落盘 / 事件

核心文件：controllers/run.py → services/run.py（对话）/ services/proactive.py（主动）→ services/agent.py（不走公开 DeerFlowClient.stream，直接调 agent 的 stream / run_once）→ 中间件栈 → DeerFlow checkpointer。

图 B1 · 对话 Run：创建与排队（单会话不排队；忙则 409）。

sequenceDiagram
  autonumber
  participant BFF as BFF
  participant API as API
  participant RS as RunService
  participant Pool as user池
  participant DB as DB

  BFF->>API: POST /runs
  API->>RS: create
  alt 会话忙
    RS-->>BFF: 409 Busy
  else waiting_user
    RS->>RS: 当作回答续跑
  else 空闲
    RS->>DB: 插入 queued
    RS->>Pool: submit
    RS-->>BFF: 202 Run
  end

图 B2 · 对话 Run：执行、流式事件与落盘（事件可丢，快照为准）。

sequenceDiagram
  autonumber
  participant Pool as user池
  participant RS as RunService
  participant AS as Agent
  participant DF as DeerFlow
  participant DB as DB
  participant BFF as BFF

  Pool->>RS: _execute
  RS->>DB: running
  RS->>AS: stream
  AS->>DF: agent.stream
  DF->>DF: checkpoint
  loop 流式事件
    DF-->>AS: token/custom
    AS-->>RS: AgentEvent
    RS->>DB: events+Blocks
    RS-->>BFF: SSE
  end
  alt 提问 interrupt
    RS->>DB: waiting_user
  else 正常结束
    RS->>DB: completed
  end
  Note over BFF,DB: 断线改拉 GET /threads/id

状态机（对话）
queued → running → completed | failed | cancelled
            ⇅
       waiting_user   （等用户回答提问；对外/服务层常用此名）

先写结束事件，再把行标终态 —— 客户端读到终态时日志一定完整。
一个库只有一个 harness 写进程；启动 recover() 把残留 queued/running 标失败（worker_lost）。

5. 三池 + task_type → agent 分流（以代码为准）

历史上曾是「单一 ThreadPoolExecutor(max_workers=max_concurrent_runs)」。现在：

• RunService 持有 user 池（对话）
• ProactiveService 持有 batch + per_user 两池
• harness.max_concurrent_runs 已不再读取
• 启动断言 database.pool_size >= 24（三池 worker 之和；每个 worker 跑图各占一条 checkpointer 连接）

图 C · 三池分流：对外用 task_type，池按执行器名选择。

flowchart TB
  U["POST /runs 对话"] --> CU["chat-agent"]
  CU --> PU["user池 x12"]

  P["POST /runs/proactive"] --> T{"task_type"}
  T -->|quality / production / inventory| AD["anomaly-detection"]
  T -->|company_brief| BG["brief-generation"]
  T -->|greeting_first / daily| GR["greeting-*"]

  AD --> PB["batch池 x4"]
  BG --> PB
  GR --> PP["per_user池 x8"]

# agent/executors.py（摘录）
POOL_WORKERS = {POOL_USER: 12, POOL_BATCH: 4, POOL_PER_USER: 8}

def normalize_agent_name(name: str) -> str:
    """只在构造客户端、找提示词文件时用；task_type 不经过它。"""
    return re.sub(r"[^A-Za-z0-9-]", "-", name)

EXECUTORS = {
    "anomaly-detection": Executor(..., POOL_BATCH),
    "brief-generation":  Executor(..., POOL_BATCH),
    "greeting_first":    Executor(..., POOL_PER_USER),  # → greeting-first
    "greeting_daily":    Executor(..., POOL_PER_USER),  # → greeting-daily
}

# services/proactive.py
TASKS = {
    "quality_anomaly":    Task(EXECUTORS["anomaly-detection"], KIND_ANOMALY),
    "production_anomaly": Task(EXECUTORS["anomaly-detection"], KIND_ANOMALY),
    "inventory_anomaly":  Task(EXECUTORS["anomaly-detection"], KIND_ANOMALY),
    "company_brief":      Task(EXECUTORS["brief-generation"], KIND_BRIEF),
    "greeting_first":     Task(EXECUTORS["greeting_first"], KIND_GREETING),
    "greeting_daily":     Task(EXECUTORS["greeting_daily"], KIND_GREETING),
}

6. 本体能力：copy_ontology（自研编排 + 平台 MCP）

本体推理引擎不在 harness。三种编排面（harness.copy_ontology_orchestration）：

none / platform_runtime 会拿掉 DeerFlow 内置 ask_clarification（它不在 tools 池，只能在 copy_ontology.py 显式处理）。展示组件由中间件校验平台返回后直接发 custom 事件；files 例外走 present_files + PresentFilesMiddleware。

对话中间件大致顺序：SystemPrompt → Skills? → MemoryContext → ReferenceContext → LocalToolGroups? → ToolCallLog → 编排面相关 → PresentFiles …

7. 记忆：DeerFlow 存桶，Harness 管注入与 HTTP

• 写：仅 chat-agent 通过 DeerFlow MemoryMiddleware（桶名默认 chat-agent）。
• 读/注入：自研 MemoryContextMiddleware 把 get_context 写成 checkpoint 里带 harness_user_memory 标记的 HumanMessage 快照（插在当前用户消息前），用 revision 做前缀缓存——facts 不变就不重读，避免把记忆塞进系统提示词导致整段前缀失效。
• 必须关 DeerFlow 自带注入（memory.injection_enabled: false）。
• 问候在 compose 阶段读同一桶；BFF 经记忆 HTTP 读/覆盖画像与兴趣称呼。

8. 技能与工具面：配置白名单压过 DeerFlow 默认「全开」

五个 agent（1 对话 + 4 执行器）。启动时：

1. 补写/校验各 agent 的 agent_dir(name)/config.yaml（执行器强制 memory_enabled=false、mcp_plugins: []）。
2. agent/skills.py 扫 skills/public/*/SKILL.md，按 config.yaml 白名单校验；未知技能告警跳过。
3. 本地工具全进程一个池；对话用 LocalToolGroupsMiddleware 藏未选中组；执行器用 ToolsMiddleware。
4. 技能隔离现用 prompt（保留 local sandbox host bash）；接入 aio 沙箱后宜改回 sandbox。

9. 主动执行器

主动 Run：trigger_kind=proactive，无会话、无触发消息、不写事件、不进 harness_messages；按全局唯一 idempotency_key 去重；非流式 run_once；结果只在 completed 写 result_payload。

图 D · 主动 Run：创建 → 分池执行 → 取结果 → 可选写入主会话。

flowchart TD
  A["BFF POST /proactive"] --> B{"校验参数"}
  B -->|非法| E1["422"]
  B -->|同键冲突| E2["409"]
  B -->|同键命中| H["202 hit"]
  B -->|新键| Q["queued 入库"]
  Q --> S["按池 submit"]
  S --> R["running + compose"]
  R --> I["run_once"]
  I --> F{"终态"}
  F -->|成功| OK["completed + payload"]
  F -->|失败| FL["failed"]
  F -->|取消| CA["cancelled"]
  OK --> G["GET /result"]
  G --> M["可选写主会话"]
  M --> N["空闲 append / 忙则下轮补写"]

# 结果信封经 GET /runs/{id}/result
# schema_version 按 kind 选；异常块可带 summary/metadata；
# 周报优先读沙箱固定路径 brief.html，不读模型正文。
# DeerFlow thread 用合成键 proactive-{run_id.hex}，不建 harness_threads 行。

10. 客户端协议：Message + Blocks

• 事件流可丢，以线程快照为准（docs/agent-ui.md）。
• 交互走 LangGraph interrupt() + harness interaction + POST /runs/{id}/answer。
• 块类型含 text / html / reasoning / 组件块等；未知 type 客户端应跳过。
• 近期协议增强：思考增量、本地工具卡、files 插在文本后、用户消息引用、游标分页、主动 message_kind。

11. 今日（2026-10-29）代码要点 · 原理向

12. 近期功能（按原理，不按 commit）

13. 建议阅读顺序

1. AGENTS.md（权威约定）
2. docs/1030/agent-harness-1030-版本规范.md（对照源码纠偏过期表）
3. config.yaml：tools / memory / agents / orchestration
4. agent/executors.py → services/proactive.py → services/run.py
5. agent/copy_ontology.py → agent/middlewares/*
6. services/agent.py（与 DeerFlow 粘合最深）
7. controllers/run.py / memory.py / thread.py
8. docs/agent-ui.md、docs/chat.md、docs/1030/greeting_first.md

14. 设计文档地图（仓库内）