# SecFusionAgent Technical Design 1

[English](Technical-Design-1.en.md) | 中文 · 1 | [Technical Design 2](Technical-Design-2)

> 交互视图：**Technical Design 视图（运行时与存储架构）** — [中文](https://jiale-li-orion.github.io/SecFusionAgent/tech-design.html) · [English](https://jiale-li-orion.github.io/SecFusionAgent/tech-design.html?lang=en)

改动 M1–M3 的运行架构、数据存储、接口或技术选型之前先读本文。本文把冻结的 [Requirements-SPEC](Requirements-SPEC) 与 01–05 的信息语义落成可实现的后端架构，当前覆盖 System Architecture、Data Lifecycle、Technology Baseline、Data Model，以及 M1 情报监测、M2 证据留存与规范化、M3 情报富化与关联；同时固定 M4/M5/M7 将使用的 Case–Trajectory–Experience 演化接缝（seam）。M4–M6 运行时由 [Technical Design 2](Technical-Design-2) 承接。

Requirements 持有“系统需要做什么”；[01-Data-Sources-and-Processing](01-Data-Sources-and-Processing) 持有 source、证据、object/relation、retrieval 与数据生命周期；[02-CTI-Baseline-Reuse-and-Ownership](02-CTI-Baseline-Reuse-and-Ownership) 持有 CTI 复用边界；[03-Normative-Knowledge-and-Policy](03-Normative-Knowledge-and-Policy) 和 [04-AI-Model-Data-and-Agent-Application-Security](04-AI-Model-Data-and-Agent-Application-Security) 持有专项语义；[05-Incident-News-Intelligence](05-Incident-News-Intelligence) 持有 Incident / News Watch 的 source role、监测源与事件型数据生命周期。本文决定这些对象由哪些进程处理、写入什么存储、通过什么接口连接，以及第一版代码采用什么技术栈。

本文为 Technical Design 1，范围止于 M1–M3 Data Plane、M3→M4 handoff 与 Case / Trajectory / Experience 存储接缝。M4–M6 的 Task Routing、Perception、Investigation State、Agent Runtime、Execution Control Plane 与 Decision/QA 由 [Technical Design 2](Technical-Design-2) 继续定义。

### 实现状态 — 2026-10-16

M1–M3 已有持续采集、Evidence/Knowledge、文档版本与索引、确定性富化、Incident 候选/晋升/时间线及 M3→M4 read handoff。当前代码配置为 106 个来源目录条目、71 个可执行 SourceDefinition、43 个定时来源；这是配置计数，不是今日在线健康率。

CWE、显式 PoC、FIRST/GitHub EPSS、NVD/CVE5/OSV/CSAF applicability、修复版本、资产 CPE join 和论文 exact-CVE 关联已有实现，不能继续作为“尚未开发”待办。材料质量门、保留证据重解析、PDF 编码修复、注册源扩充与证据绑定的事件编目也已落地。质量与广泛覆盖仍按各自固定样本验收。

本地 Compose 当前默认关闭后台模型与自动编研；采集、证据、词法索引、确定性富化和投影继续。`durable_managed` 的 dense/semantic/normative 阶段仅在显式启用并配置 provider 时运行。调度启动同步 registry 与 schedule state，保留 cursor/backoff；`time_bounded` 资产来源保持按需读取。

当前代码验收、历史 benchmark 及尚未关闭的来源 delivery、开放语义/资产/事件质量分母见 [验收台账](Current-Acceptance)。2026-10-01/08 的运行指标只属于其冻结窗口；不得将旧来源健康数或 QA 结果解释为当前部署状态。跨模块材料与报告约束见 [信息质量与研报](Information-Quality-and-Reports-2026-10)。

## 架构

SecFusionAgent 的 Data Plane 同时存在三个不同的分类轴，不能互相替代：

- **Source taxonomy**：八类外部来源，回答“谁对什么事实负责”；
- **Processing path**：Bug Stream、Structured Development Index、Insight Corpus、Incident Watch 四条主路径，加 Internet Asset on-demand side path，回答“这条 source stream 怎样发现、处理、留存和晋升”；
- **Durable value/state family**：Knowledge、Incident、Insight、Experience，回答“系统长期积累什么”。

同一个 provider 可以产生多条 source stream，同一 source class 也可以根据对象/内容进入不同 processing path。processing convergence 只复用 runtime/retention 机制，不合并 source authority 或 provenance。Website 的“八类来源 → 四条主处理路径 + asset side path”与本设计使用同一语义。

`SourceDefinition.retention_mode` 是 processing path 的可执行编码，不再增加第二套枚举：

| Processing path | `RetentionMode` | 典型行为 |
|---|---|---|
| Bug Stream | `hot_window` | 高频 current working set，按需 promotion |
| Structured Development Index | `selective_index` | 稳定对象/关系持续同步，正文按需固定 |
| Insight Corpus | `durable_managed` | 原始版本、投影、切块、semantic/index 长期保存 |
| Incident Watch | `incident_signal` | 短 TTL signal/candidate，promotion 后进入 durable Incident |
| On-demand observation side path | `time_bounded` | query-bound observation，带 observed_at，必要时 promotion |

同一 taxonomy category 可以出现多个 retention mode；retention mode 不反向决定 category。`durable_promoted` 是运行时晋升后的状态，不是第六种 source processing path。

SecFusionAgent 按 workload 设计数据生命周期。当前有四类需要长期区分的情报工作负载：

- **Bug Stream**：CVE/NVD/OSV/GHSA/KEV 等高频、已有 canonical store 的漏洞流。本地维护近期新增、近期更新、高频访问和正在调查的工作集，历史记录按需回查外部 canonical source。
- **Incident Intelligence**：攻击、被盗、数据泄露、供应链事故、在野利用、资金转移等突发事件。最初通常只有新闻、研究员、on-chain 或 telemetry 信号，系统先做热聚类 / 时间线 watch，形成持续分析价值后晋级 durable Incident。
- **Insight Corpus**：论文、厂商技术报告、安全研究、system/model card、标准法规等长期知识资产。本地持有版本、投影、semantic result 与 retrieval index。
- **Investigation Experience**：从 M4/M5 的 Case/Trajectory 和 M7 outcome 中抽取的调查方法、失败模式与 stop/fallback policy，属于 Agent 自身演化资产。

`Investigation State` 贯穿 Bug/Incident 调查，具有低吞吐、高价值、强一致性的特征，由 PostgreSQL durable 状态持有。

运行时由调度器、Source Worker、Hot Cache、Incident Correlator、Evidence Ingestion、Normalization、Enrichment、索引器组成。PostgreSQL 保存 durable 状态、当前投影与长期知识，S3-compatible 产物存储保存需要长期保留的 raw JSON/HTML/PDF，Redis Hot Cache 保存 bounded bug 工作集与短生命周期 incident 信号/聚类，独立 Redis Broker 承担 Celery task transport。

```mermaid
flowchart LR
    subgraph External[External sources]
        BugCold[Canonical bug DB\nCVE / NVD / OSV / GHSA / KEV]
        IncidentSignal[Incident signals\nnews / on-chain / researcher / telemetry]
        Primary[Primary confirmation\nproject / vendor / repo / authority]
        Structured[GitHub / package & model platforms]
        Managed[Paper / vendor / blog / normative content]
        OnDemand[Internet asset / high-cost providers]
    end

    subgraph Runtime[SecFusionAgent backend]
        Scheduler[Scheduler]
        Adapters[Source Workers / Adapters]
        HotIngress[Hot Bug Ingress + Diff]
        Incident[Incident Correlator / Timeline Watch]
        Ingress[Durable Evidence Ingestion]
        Normalize[Normalization]
        Enrich[Enrichment]
        Promote[Promotion Gate]
        Indexer[Indexer]
        Model[LLM Provider Adapter]
        API[FastAPI]
    end

    subgraph Storage[Local state]
        Hot[(Redis Hot Working Set\nBug + Incident Candidate)]
        PG[(PostgreSQL + pgvector\nDurable Knowledge + Current Views)]
        Blob[(S3 / MinIO Artifact Store)]
        Broker[(Redis Celery Broker)]
    end

    Scheduler --> Broker
    Broker --> Adapters

    BugCold --> Adapters --> HotIngress --> Hot
    IncidentSignal --> Adapters --> Incident --> Hot
    Primary --> Adapters
    Hot --> Normalize
    Hot --> Enrich
    Incident --> Enrich
    Enrich --> Promote
    Promote --> Ingress

    Structured --> Adapters
    Managed --> Adapters
    OnDemand --> Adapters
    Adapters --> Ingress

    Ingress --> Blob
    Ingress --> PG
    PG --> Normalize
    Normalize --> PG
    Enrich --> Model
    Enrich --> PG
    PG --> Indexer
    Blob --> Indexer
    Indexer --> PG
    PG --> API
```

外部来源按 01 已冻结的接入模式进入后端，同时采用不同保留模式：

| 接入模式 | 典型来源 | 本地生命周期 | 长期权威 |
|---|---|---|---|
| Canonical bug feed / external query | CVE/NVD/OSV/GHSA/KEV | `hot_window`：最新发布、最新更新、高频访问和 active 工作流进入 Redis；TTL/LFU 后可淘汰 | 外部 canonical source |
| Structured index | GitHub、package/model registry、target repo graph | `selective_index`：稳定 ID/relation 留本地；正文和高成本对象按需快照 | 外部平台 + 本地关系图 |
| Managed content | 厂商公告、博客、论文、标准法规、Insight Watch | `durable_managed`：raw 版本、投影、semantic result、retrieval index 长期保存 | 本地证据 + 原始来源 |
| Incident 信号 | 新闻快讯、on-chain alert、研究员披露、威胁 telemetry | `incident_signal`：短 TTL 信号 + 热聚类；持续富化后决定是否晋级 Incident | 原始来源分别持有 |
| On-demand 观测 | Censys/Shodan/FOFA/ZoomEye、商业情报 | `time_bounded`：query/filter/result 带观测时间；默认短 TTL，调查或回答需要时晋级 | provider 观测 |
| 已晋升 bug / incident 证据 | 被调查、被引用、形成长期关系或进入评测集的版本 | `durable_promoted`：固定实际消费版本和必要原始证据 | 本地证据 + 外部版本 |

Bug Stream 的本地价值来自 current 工作集；Incident Intelligence 的价值来自事件演化、跨源 corroboration 与时间线；Insight Corpus 的价值来自长期语义资产；Experience 的价值来自 Agent 调查方法演化。四类 workload 共享 source/证据/来源链路 contract，但保留、consistency、indexing 和 enrichment depth 独立配置。

### 数据生命周期与温度分层

热度由四类信号决定：`source change recency`、`access frequency`、`workflow activity`、`domain priority`。新发布和新版本自动进入热集合；用户查询、M3 enrichment、M5 investigation 会提高访问/工作流热度；目标 AI Infra repo、KEV/PoC/critical 信号可以提高处理优先级。活跃调查、待晋升和评测集 pin 会阻止淘汰。

准入、处理优先级与淘汰分开计算。准入决定对象是否进入 Redis；处理优先级决定是否立即触发高成本 enrichment；淘汰根据 TTL、LFU/LRU 和工作流 protection 回收容量。Redis 的 max-memory policy 作为容量保护，业务层继续持有晋升与淘汰语义。

```text
Bug Stream write path
  delta / updated record
    -> cheap parse + current projection
    -> Redis hot working set
    -> change classification
    -> selected enrichment
    -> promote OR expire/evict

Bug read path
  Redis hit
    -> external-current projection
  Redis miss
    -> PostgreSQL durable SecFusion knowledge (if promoted)
    -> external canonical source for current record
    -> hot admission
```

高频 source 的版本变化先做 field-level diff。CVSS/CWE/KEV/reference 等结构化字段变化更新对应投影；description、patch explanation 等语义字段变化才触发 semantic extraction / embedding。处理规则使用 `change type -> invalidate affected derived state`，降低 write amplification。

晋升把临时工作状态变成长期资产。触发条件包括：进入 M4/M5 investigation；成为 M6 answer citation；进入评测集/人工裁定真值；形成 target repo / supply-chain / incident 的长期 relation；出现需要保留的 source conflict；analyst review 决定长期保留。需要 durable conclusion 前先固定实际消费的 provider 版本。

降级用于清理长期存储里仍可稳定从外部重取、且已经没有 durable relation / 评测集 / audit 依赖的 payload。降级可以删除本地 raw body 和 derived cache，同时保留外部 ID、晋升历史与必要来源链路 pointer。具体降级 policy 在数据规模实测后启用。

### 缓存一致性、Warm 状态与物化当前投影

三层数据的权威固定如下：

```text
External provider
    authority for current external canonical record

PostgreSQL durable knowledge / incident / experience
    authority for SecFusionAgent 自己确认、推导和长期保存的状态

Redis hot cache
    authority for nothing; it is a replaceable working projection
```

Cache consistency 遵循权威分层：Redis miss 或淘汰不能改变长期结论。一个对象同时存在热与 durable 状态时，read path 返回热 external 记录构成的当前投影，同时合并 PostgreSQL 中的 SecFusion-derived knowledge；两者保留各自版本，避免较旧 durable 快照覆盖最新外部状态。

`Warm` 不增加新的数据库产品，由 PostgreSQL 中的 **物化当前视图 / 当前投影** 承担。它比 raw claim/relation 更适合高频查询，又可以从 durable history 增量重建。第一批投影包括：

```text
current_vulnerability_view
current_fix_status
current_affected_versions
current_repo_security_state
current_incident_view
```

底层继续保存多来源 claim/relation/时间线事件；投影根据 `KnowledgeChange` 与 `incident.changed` 发件箱事件做 incremental view maintenance。CVSS 或 KEV 变化更新对应字段，description/technical analysis 变化才 invalidates semantic 投影与 embedding。M4/M6 默认读取当前投影，需要解释冲突或历史状态时回到底层证据图。

Current Projection 的 logical identity 固定为 `projection_type + subject_id`，同时保留 deterministic `projection_id`。PostgreSQL 写入只允许 `upstream_revision` 单调前进；同一 projection identity 的并发 rebuild 在 transaction 内先取得由 deterministic ID 派生的 advisory lock，再执行 conditional upsert，避免 deterministic PK 与 logical UNIQUE index 的 speculative insert 互锁。这个锁只序列化同一 identity，不把无关 projection 变成全局单线程，也不移除数据库 uniqueness invariant。

### Incident Intelligence 来源策略

Incident / News Watch 的具体监测源、source role、接入优先级与接入探针由 [05-Incident-News-Intelligence](05-Incident-News-Intelligence) 持有。Technical Design 只固定它们进入运行时后的行为：`signal/telemetry` 先进入短 TTL staging，`primary/forensic/authority` 可以参与晋升和 durable enrichment；`source_family/upstream_source` 用于消除转载造成的伪 corroboration。

### Incident 热到持久生命周期

Incident 输入具有 burst、duplicate、uncertain 和持续修订特征，先进入热信号缓冲：

```text
SignalItem
  -> deterministic anchor extraction
  -> IncidentCandidate clustering
  -> timeline watch / source follow-up
  -> promotion decision
  -> durable SecurityIncident
  -> M3 enrichment
  -> M4 confirmed / conflict / unknown
  -> M5 investigation
  -> postmortem / insight / experience
```

`SignalItem` 保存在 Redis 短 TTL namespace，包含 source、original/cited source、published/observed time、title/summary、entity hints、URL、content hash 和可验证 anchor。Web3 anchor 优先使用 project、chain、token、address、tx hash、amount 和时间窗；通用 cyber incident 优先使用 organization、product、domain/IP、CVE/GHSA、threat actor、campaign 和时间窗。当前实现只允许 deterministic strong anchor 参与候选关联；semantic similarity 预留为后续 recall assist，需要和强 anchor/证据门禁配合，避免同一项目短时间内两次独立事故被强行合并。

`IncidentCandidate` 保存聚类状态、watch priority、next poll、last material change、source diversity 和 unresolved questions。事件初期不把每条转载新闻永久写入 PostgreSQL/S3；重复转载在 TTL 后淘汰。出现下列信号时晋级 durable Incident：

- 受影响项目/厂商或官方渠道确认；
- 多个独立 source 对同一可验证 anchor 形成 corroboration；
- on-chain transaction、公开 IOC、GitHub patch/advisory 等可直接验证证据；
- 事件影响触发 M4/M5 investigation、持续资金跟踪或用户查询；
- analyst / 评测集明确 pin。

晋级后创建 `SecurityIncident` object，并把支撑当前时间线/claim 的 source 版本固定为 durable 证据。后续新闻仍先进入热聚类，产生 material change 的 item 再晋升。全文向量化面向已晋升 technical report、postmortem、厂商公告和高价值分析，不对所有快讯做 embedding。

Incident Watch 使用 adaptive follow-up：有新资金移动、官方 response、exploit 持续、影响范围变化时提高 watch priority；长时间没有 material change 后逐步降低 polling，进入 resolved/postmortem 状态后转为低频版本 watch。具体 cadence 由 source capability 和 M8 budget 配置。

### 背压与选择性富化

M1 可以高频发现变化，M3 的高成本处理必须有独立预算。每个热更新先经过确定性规范化/diff，随后按 priority 进入 enrichment queue；语义处理、Internet asset lookup 和大规模 repo traversal 拥有独立 concurrency/rate/cost budget。

priority 信号由 target repo/risk domain match、KEV/PoC/critical status、change type、access frequency、active investigation 和 SLA 组成。queue backlog 超过预算时，低优先级对象保留在 Redis 工作集并延迟 enrichment，source monitoring 继续推进，不让 LLM/API 吞吐反向阻塞新漏洞发现。

这个策略把 monitoring 新鲜度与 enrichment depth 解耦：M1/M2 先保证“新变化已可见”，M3 根据价值和系统容量逐步加深处理。M7 分别记录 hot-ingest latency、enrichment wait time 和处理器延迟。

### 运行时归属

| Runtime | Code owner | 状态 owner | 职责 |
|---|---|---|---|
| `api` | `apps/api` | 无独立业务状态 | 暴露 source health / knowledge read API，后续承载 M4–M6 application API |
| `scheduler` | `packages/monitoring` | `sources/source_state` | 读取 source schedule，创建 scheduled acquisition task |
| `source adapter` | `packages/sources` | 无独立 durable runtime state | 实现 API/Git/RSS/Web/query provider protocol，产生 `IngestEnvelope` |
| `acquisition runtime` | `packages/monitoring/acquisition` | `acquisition_runs` | 为 scheduled/on-demand provider read 建立 run、parent/query 来源链路与 terminal state |
| `incident correlator` | `packages/intelligence/incident` | 热 incident 信号/聚类 | M2 信号去重、anchor clustering、IncidentCandidate 身份/correlation；follow-up request 交给 monitoring/acquisition |
| `ingestion / normalization worker` | `packages/intelligence` | 热投影 + durable 证据/knowledge | 热接入/diff、durable 证据 commit、解析、去重与 id 实体对齐 |
| `enrichment worker` | `packages/enrichment` | processing result | deterministic、graph、semantic 与 provider-backed enrichment |
| `index worker` | `packages/intelligence` | derived index | document 切块、lexical/vector index、元数据投影 |

`apps/worker` 使用同一 Python image 启动不同 Celery queue；deployment 可以按 workload 把 I/O collection、语义处理和 indexing 拆成独立工作进程，也可以在开发环境合并运行。业务行为仍由对应 package 持有。

### 处理主干

调度器和 Source Worker 共用同一 acquisition contract，M2 根据 `retention_mode` 在入口处分流：

1. 调度器从 `sources/source_state` 找出到期来源，创建 `AcquisitionRun` 并投递 collection queue。
2. Source Worker 执行适配器的 `discover/fetch/query`，返回带 source/revision/time/hash 的 `IngestEnvelope`。
3. `hot_window` source 进入 `HotBugIngress`：cheap parse、当前投影、field-level diff 写入 Redis，生成 `HotNormalizationResult`。游标在热记录成功写入并可读取后推进。
4. `incident_signal` source 进入 `IncidentSignalStore`：先保存短 TTL `SignalItem`，再由 Incident Correlator 基于 deterministic strong anchor 更新 `IncidentCandidate` 与 watch 状态。semantic similarity 可以作为后续候选辅助，但当前实现不允许它单独触发聚类/晋升。
5. 热漏洞根据 change/domain priority/access/工作流进入 selective M3 enrichment；IncidentCandidate 根据 source diversity、material change 和 unresolved questions 进入 source follow-up/enrichment。
6. 出现 durable 信号时触发 Promotion Gate。Bug 晋升固定当前 provider 版本；Incident 晋升固定支撑时间线/claim 的 source 版本。`durable_managed/durable_promoted` source 从 acquisition 直接进入 Durable Evidence Ingress。raw JSON/HTML/PDF 写产物存储，PostgreSQL 创建 immutable `Observation/EvidenceArtifact`。
7. Durable Normalization 通过 source parser + canonical mapper 写 `Object/ExternalIdentifier/Claim/Relation/EvidenceLink`；Incident 晋升同时创建 `SecurityIncident`/时间线状态。transaction 提交新的 `knowledge_revision` 或 `incident_revision` 与发件箱事件。
8. M3 对 durable subject 运行 deterministic、graph、semantic 或 provider-backed 处理器。Provider lookup 再次经过 M2，并按自己的保留模式选择热/incident/durable path。
9. Durable commit 触发索引器/当前投影 updater；document 切块、lexical/vector index、当前视图和 Experience/洞察 retrieval 投影都属于可重建 derived 状态。

Celery Broker 提供 at-least-once task delivery，PostgreSQL 保存 durable run/发件箱状态，Redis Hot Cache 只保存可淘汰工作状态。热记录的幂等键收敛 feed 重放，durable `Observation/Claim/Relation` 的幂等键收敛晋升和处理重放。

### 横切约束

Requirements 的 C1–C3 直接映射到运行边界：

| Constraint | Technical contract | M1–M3 落点 |
|---|---|---|
| C1 证据可追溯 | 热投影/信号可回 provider/source 版本；每个 durable claim/relation/时间线 event 能定位观测、产物 locator 与 processing 版本 | HotBugRecord/SignalItem 版本、`Observation`、`EvidenceArtifact`、`EvidenceLink`、`ProcessingRun`、knowledge/incident 版本 |
| C2 外部内容不可信 | 外部 payload 永久保留 `external_untrusted`；模型处理只能生成 typed candidate，source content 没有配置、credential 或 execution 权威 | HotBugIngress、Incident Correlator、Evidence Ingress、Semantic Processor、ModelProvider 边界 |
| C3 有界执行 | acquisition/processing task 有超时、attempt、terminal state 与幂等键 | `AcquisitionRun`、`ProcessingRun`、Celery 重试策略、source 退避 |

C1 的失败表现为候选缺失有效证据 locator；C2 的失败表现为外部内容影响 system config、tool policy 或 credential 边界；C3 的失败表现为 run 无法到达终态。M7 后续直接围绕这三类 failure 建 regression。

## 技术基线

当前 DESIGN 直接给出第一版实现基线。探针用来验证高风险假设，验证失败后替换具体 provider；模块边界和 data contract 保持稳定。

| Concern | Baseline | 设计理由 |
|---|---|---|
| Backend language | Python 3.12+ | source/API/LLM/CTI 生态集中，和当前 Agent tooling 一致 |
| HTTP API | FastAPI | typed async API；后续 M4–M6 与前端共用 |
| Schema / validation | Pydantic v2 | `IngestEnvelope`、processor output、API contract 使用同一类型系统 |
| Relational persistence | PostgreSQL 16+ | source state、knowledge、relation、run 来源链路、评测集元数据统一事务语义 |
| ORM / 迁移 | SQLAlchemy 2 + Alembic | 显式 schema 与迁移，测试和生产共享模型 |
| Vector / lexical retrieval | pgvector + PostgreSQL FTS/`pg_trgm` | durable 洞察/experience 第一版保持同库；后续可接 VikingDB/OpenSearch/Qdrant provider |
| Experience retrieval | PostgreSQL + pgvector | Experience 作为 versioned policy memory，与 knowledge/证据分表；OpenViking 作为演化管道设计参考 |
| 原始产物 | S3-compatible object storage；本地/CI 使用 MinIO | JSON/HTML/PDF 与 canonical DB 分离，content hash 可复用，生产可换 S3/OSS |
| Background jobs | Celery + dedicated Redis Broker | collection、normalization、enrichment、indexing 分 queue；broker 使用独立实例/namespace 与 `noeviction` 类策略保护任务状态 |
| 热工作集 | dedicated Redis Cache | bug 工作集 + incident 信号/聚类；业务层持有准入/晋升/watch，TTL/LFU/LRU 负责容量保护 |
| Scheduling | 单实例调度器 + source-level `next_due_at` | source cadence 由 registry 决定，避免为每个来源硬编码 cron |
| HTTP client | `httpx` | async request、超时、redirect、streaming 和适配器 test 易控制 |
| Content parsing | source mapper + HTML/PDF/plain parser 适配器；当前 PDF 使用 `pypdf`，HTML/plain 已进入 Managed Content executable path | parsing 与业务语义分开，原始产物始终可重新处理 |
| LLM integration | 自有 `ModelProvider` interface + provider 适配器；Pydantic/JSON Schema structured output | M3 模型调用是 semantic processor，prompt/model/来源链路保持显式 |
| CTI interoperability | STIX 2.1 / TAXII 2.1 适配器，外接 OpenCTI/MISP | 复用标准和成熟生态，同时保留 AI-specific data model |
| Deployment | Docker Compose 作为开发、CI 和比赛部署基线 | API、工作进程、调度器、PostgreSQL、Redis Broker、Redis Hot Cache、MinIO 可一键复现 |

### 知识内核

第一版采用 **PostgreSQL 自有轻量 knowledge kernel + STIX/TAXII interoperability**。SecFusionAgent 的核心写路径由 PostgreSQL kernel 持有；OpenCTI/MISP 通过 CTI source、exchange endpoint 与能力 provider 接入。

这个选择来自 01–04 已经固定的数据语义：系统同时管理传统 CTI、repo/release graph、paper/research 洞察、normative requirement/control、Agent/tool/memory relation 和证据版本。把这些对象统一落在项目拥有的 relational kernel，可以让 M2/M3 的来源链路、评测集版本和 AI-specific relation 共用同一 transaction 边界。STIX/TAXII 适配器负责与传统 CTI 生态交换，成熟 IOC/parser/correlation 能力继续通过现有平台或库复用。

关系查询第一版使用 PostgreSQL relation table、索引和 recursive CTE。后续 graph 评测集如果显示 traversal latency 或查询表达力成为瓶颈，再在 `KnowledgeRepository` 后增加专用 graph provider；canonical knowledge 继续由 PostgreSQL 持有。

### Retrieval

检索第一版也收敛在 PostgreSQL：精确 ID/version/package 查询直接走结构化表；document 切块保存 `tsvector`/`pg_trgm` 字段与 pgvector embedding；元数据 filter 使用 object/source/risk/version 字段。中文与英文语义检索主要依赖 multilingual embedding，精确 security identifier 与 repo/package/version 由结构化查询承担。

`RetrievalPort` 屏蔽底层实现。M7 后续发现 lexical recall 或数据规模需要独立 search engine 时，可以增加 OpenSearch/Qdrant 等 provider，证据、knowledge 与评测集 contract 不变。

### 模型处理

M1–M3 的 control flow 由项目 package 直接持有：调度器、source routing、证据 commit、去重、实体对齐门禁和 enrichment routing 都是确定性逻辑；模型调用通过 `ModelProvider` 完成非结构化语义抽取。LangChain/LlamaIndex 若用于局部 parser/retriever provider，也服从这些项目级 contract。

语义处理器的运行条件固定为：输入来自已经持久化的 `Observation/DocumentProjection`；prompt 显式把外部文本标记为 untrusted data；模型拥有的 capability 为 structured generation；输出先进入 Pydantic 候选；候选写入 canonical knowledge 前需要证据 locator 与处理器来源链路。模型 API credential 由工作进程 config 注入，外部证据无法改变 provider、tool 或 credential policy。

## 数据模型

本地状态分成六组：source/runtime 状态、Redis 热工作集、incident 状态、durable 证据、canonical knowledge、derived retrieval / experience。PostgreSQL 持有 durable 元数据、已晋升 Incident、canonical 状态与当前投影；产物存储持有需要长期保存的 raw body；Redis 热漏洞/incident record 属于可淘汰工作投影，不能成为长期 claim/时间线的唯一权威。

### 表

| Table / object | 关键字段 | 归属 |
|---|---|---|
| `sources` | `source_id`, `adapter_type`, `source_class`, `authority_scope`, `access_mode`, `update_semantics`, `schedule_policy`, `retention_mode` | M1 |
| `source_state` | `cursor`, `last_attempt_at`, `last_success_at`, `next_due_at`, `backoff_until`, `rate_limit_state` | M1 |
| `acquisition_runs` | trigger、source、query/cursor、attempt、status、parent run/task | M1/M3 |
| `observations` | source object 身份、external 版本、published/updated/fetched time、content hash | M2 |
| `evidence_artifacts` | 观测、media type、storage URI、hash、access rights、trust class | M2 |
| `documents` / `document_revisions` | stable document 身份、source object、观测、external 版本、parser 名称/版本、元数据；同一 Observation 可对应多个不可变 parser revision，唯一键为 `(observation_id, parser_name, parser_version)` | M2 |
| `objects` | internal ID、`object_type`、canonical key、typed properties | M2 |
| `external_identifiers` | namespace、value、object ID | M2 |
| `claims` | subject、predicate、value、qualifier、origin、生命周期、processing run | M2/M3 |
| `relations` | source object、relation type、target object、qualifier、origin、生命周期 | M2/M3 |
| `evidence_links` | claim/relation、观测/产物、field/page/section/span locator | M2/M3 |
| `processing_runs` | processor、version、input 版本、model/prompt 版本、status | M2/M3 |
| `insight_candidates` | related claims/relations、change type、证据成熟度、晋升状态 | M3 |
| `incidents` | SecurityIncident、生命周期、watch state、current summary、incident 版本 | Incident/M4 |
| `incident_timeline_events` | incident、event time、event type、claim/证据 refs、supersedes | Incident/M4 |
| `incident_source_links` | 信号/证据 source、original/cited source、corroboration dependency | Incident |
| `current_projections` | vulnerability/fix/repo/incident current state + upstream 版本 | M2/M3/M4 |
| `document_chunks` | document/section、text、元数据、embedding、index version | 索引器 |
| `knowledge_changes` | monotonic 版本、changed IDs、cause run、commit time | M2/M3 |
| `outbox_events` | domain event、payload、delivery state | transaction handoff |

Managed HTML parser v3 优先选择 `.entry-content`、`.post-content` 等正文容器，避免把站点的“相关阅读”卡片误当正文。源内容字节未变化而解析器升级时，M2 保留原 Observation/Artifact 与旧 DocumentRevision，新增 parser revision；当前 lexical、compact-name 与 dense 检索只取文档最新解析版本，已记录的 chunk 引用仍可按原 revision 精确回放。
| `investigation_cases` | task signature、target objects、goal、initial knowledge 版本、rubric、status | M4/M5 |
| `investigation_trajectories` | case、step/tool/证据 event、retrieved experience version、outcome、latency/cost | M5/M7 |
| `experience_candidates` | extracted procedure/failure pattern、scope、supporting trajectory、candidate state | M5/M7 |
| `experiences` / `experience_versions` | scope、trigger、recommended action、failure/stop/fallback、status、version | M5/M7 |
| `experience_support` | experience version ↔ trajectory / evaluation relation | M7 |

### 热工作集

Redis 保存当前漏洞工作集的可淘汰投影，key 由 provider namespace + 外部 ID构成。record 保存当前版本、published/updated/fetched time、normalized current fields、content hash、热度元数据和处理状态。辅助 sorted set / set 维护 `updated_at`、access frequency、active 工作流和 pinned object。

```text
bug:{source}:{external_id}      current hot record
bug:updated                     sorted by source updated_at
bug:access                      access score
bug:active                      active processing/investigation
bug:pinned                      protected from eviction

incident:signal:{id}            short-lived SignalItem
incident:cluster:{id}           IncidentCandidate current state
incident:watch                   sorted by next_poll_at / priority
```

Redis 不是 knowledge/incident source of truth。bug record 丢失时从外部 canonical source 恢复；incident 信号过期后从已知 source 或后续 follow-up 重新发现。需要形成 durable claim/relation/时间线时，Promotion Gate 先固定支撑结论的 provider/source 版本。Celery broker 与热缓存使用独立 Redis 实例或独立故障域，cache 淘汰不影响 task delivery。

### 证据与版本

Durable `Observation` 表示“某来源在某次版本实际提供的内容”。hot-window record 在晋升前不创建该对象。优先幂等键为 `source_id + external_object_id + external_revision`；来源缺少版本时使用稳定 locator + `content_hash`。同一版本重放返回既有观测；mutable page 内容变化产生新观测。

`EvidenceArtifact` body 以 `content_hash` 为对象键写入 S3-compatible store。PostgreSQL 保存 storage URI 与 hash。写入顺序是 upload 产物、提交观测/产物元数据、返回 `ObservationAck`。数据库事务失败可能留下无引用 blob，周期 janitor 根据产物引用清理；产物上传或元数据 commit 失败都不会 ack source 游标。

Canonical knowledge 的每次事务创建单调递增 `knowledge_revision`。`Object/Claim/Relation` 保存创建和 supersede/retract 版本；M7 评测集记录使用的 knowledge 版本。`knowledge_changes` 与 `outbox_events` 在同一数据库事务写入，后台 dispatcher 再把后续规范化/enrichment/index job 发布到 Celery，避免知识已经提交而下游任务丢失。

### Object, Claim, Relation

`Object` 表示具有稳定身份的实体。当前已落入通用 Knowledge runtime 的 canonical object type 包括 `Vulnerability`、`Repo`、`Issue`、`PullRequest`、`Commit`、`Release`、`Package`、`Product`、`SoftwareVersion`、`InternetAsset`、`Weakness`、`ExploitArtifact`、`ResearchWork` 与 `Document`；这些类型已由 NVD/GitHub Advisory/OSV/CVE5/CSAF/FIRST EPSS/asset/research 等确定性或证据门控路径实际使用。`NormativeDocument / Requirement / Control` 与 Incident 专用对象继续由对应领域模型持有。数据库通过 `object_type + properties JSONB` 承载稀疏扩展字段，强身份进入 `external_identifiers`。

`Claim` 保存 scalar 或 structured literal，例如 CVSS、known-exploited、attack condition、适用性。`Relation` 使用 versioned vocabulary 连接两个 object，例如 `Vulnerability --affects-package→ Package`、`Vulnerability --fixed-by→ Commit`、`ResearchWork --discusses-vulnerability→ Vulnerability`。version range、time range、role、scope 等 edge-local 条件进入 relation qualifier；进入正式 enrichment P/R 的 canonical relation 还必须满足 registry 冻结的 subject/target shape。

每条 claim/relation 都有 `origin = source_asserted | deterministic_derived | semantic_derived` 和生命周期。M2/M3 的 `accepted` 表示写入门禁已通过；M4 后续维护 confirmed fact、conflict 与 unknown。来源冲突表现为同一 predicate 的多条证据支撑的 claim，M2/M3 保留差异。

### EvidenceLink

`EvidenceLink` 是 C1 的数据实现。JSON 来源保存 JSONPath/field；HTML 保存 section + character span；PDF 保存 page + span；GitHub object 保存 API field / comment / diff locator。`DocumentProjection` 同时保存 clean text 到原产物的 locator mapping，切块/embedding 重建后 citation 仍然能返回原始证据。

### 索引

`document_chunks` 属于 derived data。切块保存 source/object/证据 IDs、risk domain、document 版本、chunker 版本、embedding model 版本和 vector。全文/向量命中提供 retrieval 候选，事实引用仍以 `EvidenceLink` 为准。

## M1 情报监测

M1 的 code owner 是 `packages/sources` 与 `packages/monitoring`。`sources` 持有适配器和来源定义，`monitoring` 持有调度器、游标、health 与 scheduled run。M1 负责 source acquisition 与候选投递；M2 决定身份/correlation。accepted 信号按生命周期分别为热漏洞的 `HotNormalizationResult`、incident acquisition 的 `SignalAccepted`、durable source 的 `ObservationAck/NormalizationResult`；`IncidentCandidate` 属于 M2 output。

### 来源注册表

来源静态定义存放在 version-controlled config，并在启动/部署时同步到 `sources` 表；credential 只保存 secret reference。运行中的游标、health、next due、rate-limit 状态存 PostgreSQL。这样 source 接入既能 code review，又能在运行时观测状态。

`SourceDefinition`：

```text
source_id
adapter_type
source_class
authority_scope
source_role = signal | telemetry | primary | forensic | authority | reference
source_family / upstream_source
access_mode
update_semantics
discovery_method
time_semantics
identity_semantics
auth_ref
rate_limit_policy
access_rights
retention_mode = hot_window | incident_signal | selective_index | durable_managed | time_bounded
schedule_policy
schema_version
```

漏洞业务字段进入 M2/M3 knowledge tables。一个 provider 可以注册多个 source，例如 GitHub target repo、GitHub advisory database 与 GitHub research stream 使用不同 schedule/filter，并共用 GitHub 适配器 capability。

### 适配器契约

```python
class SourceAdapter(Protocol):
    async def discover(self, source: SourceDefinition, state: SourceState) -> DiscoveryBatch: ...
    async def fetch(
        self, source: SourceDefinition, ref: DiscoveredRef,
        *, acquisition_run_id: str, trigger: AcquisitionTrigger,
    ) -> IngestEnvelope: ...
    async def query(
        self, source: SourceDefinition, spec: QuerySpec,
        *, acquisition_run_id: str, trigger: AcquisitionTrigger,
    ) -> list[IngestEnvelope]: ...
```

`discover` 用于 delta/feed/index；`fetch` 固定一个外部 object 版本；`query` 服务 M3/M5 的 on-demand lookup。CVE Git、GitHub、OSV/NVD/KEV、RSS/Web、arXiv、normative source 和 Internet asset provider 各自实现适配器，provider-specific schema 和错误停留在适配器内。

第一批适配器复用外部标准与官方接口：CVE 使用 `cvelistV5` Git/delta；NVD/OSV/KEV 使用官方 API/feed；GitHub 使用 API/Git；论文使用 arXiv/OpenReview/proceedings index；STIX/TAXII、MISP/OpenCTI source 使用成熟 client/parser。Web page source 只有在缺少结构化接口时进入 crawl path。

### 调度

调度器以固定 tick 查询 `next_due_at <= now()` 的 source，创建 `AcquisitionRun(trigger=scheduled)` 并投递 collection queue。真正 cadence 在每个 source 的 `schedule_policy` 中计算；NVD、GitHub、CVE、arXiv、vendor blog 等来源独立配置。

`discover` 返回当前 batch 和 `next_cursor`。Collection runtime 按 `retention_mode` 路由：`hot_window` 进入 `HotBugIngress`，`durable_managed` 进入 `ManagedDocumentService`，`selective_index` 进入 `StructuredIndexService`，`incident_signal` 进入 `IncidentSignalIngress`。该检查点覆盖的 item 全部 accepted 后提交 `next_cursor`。中途失败时游标保持旧值，下一轮重放整个检查点，各条路径的幂等约束吸收已经成功的 item。

### 健康与失败

`AcquisitionRun` 记录 `success/no_change/rate_limited/auth_failed/schema_changed/fetch_failed`。HTTP 超时、5xx、rate limit 使用适配器特定的有界重试；认证失败和 schema change 直接进入终态并等待配置或 mapper 修复。一个 source 的失败不会阻塞其他 source queue。

M1/M7 分开记录 provider fetch latency 与 monitoring latency。比赛 monitoring latency 使用 `published_at → M2 available_at`：热漏洞以 `HotNormalizationResult.available_at` 为终点，durable source 以 `NormalizationResult.committed_at` 为终点。这样可以分别定位来源发现、网络获取、热接入和 durable 处理的延迟。

### M1 评测契约

`config/source-inventory.json` 同时承担产品来源清单与 source-category coverage denominator。当前 portfolio 固定为八类：`vulnerability / development / academic / vendor / independent / normative / assets / incidents`，八类全部计入 category coverage；比赛要求是 `≥7` 类。`assets` 虽然通过 M3 on-demand enrichment side path 获取，但仍是正式数据源类别。类别只有存在 `coverage=owned` 的 fixed/grouped owner 且 runtime adapter factory 可构造时才计 supported，dynamic resolver、partial ownership 和一次 live probe 成功都不增加类别数。

`packages/evaluation/m1_m3.py` 分开计算 `category_coverage` 与 `source_delivery_coverage`：后者对固定 source/window 冻结 `SourceDeliveryKey(source_id, external_object_id, external_revision | content_hash)`，记录 expected、accepted、missed 与 unexpected，防止动态来源数或额外噪声抬高 coverage。监测 latency sample 只对有可靠 `published_at` 的记录计算到 M2 `available_at/committed_at`；无可靠发布时间的记录不进入 latency 数值分母，同时进入 `latency_evaluable_coverage` 的分母。内部回归报告 `p50 / p95 / max / ≤6h pass-rate`，固定评测集保存逐样本值；live reachability 只记录环境状态。

## M2 证据留存与规范化

M2 由 `packages/intelligence` 持有，并提供热规范化、incident 信号 staging 与 durable 证据三种入口。高频 canonical bug feed 进入 bounded 热工作集；Incident 信号进入短 TTL 聚类；Managed Content 和已经晋升的 bug/incident 进入 durable Evidence Ingress。三条路径共享 source 身份/来源链路 contract，保留与 write target 不同。

### 热漏洞写入

`retention_mode=hot_window` 的 source 把 `IngestEnvelope` 交给 `HotBugIngress`。它校验 source/版本/hash，生成当前投影并写 Redis，同时保存 provider 版本、source URL 与更新时间。M2 对热记录执行 cheap 确定性规范化和 field-level diff，产生 `HotNormalizationResult`；这个结果满足监测“可用记录”的时效计算，但不会自动创建永久 `EvidenceArtifact`。

热记录触发晋升时，系统优先从仍在 Redis 的 payload 固定当前版本；provider 支持 immutable 版本 lookup 时也可以按版本重取。晋升成功后再创建 durable `Observation/EvidenceArtifact`，后续 claim/relation 才允许作为 M4/M6 的长期证据。

### Incident 信号暂存

`retention_mode=incident_signal` 的 `IngestEnvelope` 进入 `IncidentSignalStore`。M2 保存短 TTL `SignalItem`，抽取 original/cited source、时间、实体和可验证 anchor，并交给 Incident Correlator 更新聚类。普通转载和弱信号停留在 Redis；聚类达到晋升条件后，由 `PromotionService` 把选中的 source 版本转成 durable 证据，并创建或更新 `SecurityIncident`。

Incident 信号 staging 维护“事件正在发生”的上下文；技术结论和时间线事件在证据被晋升后进入 PostgreSQL。

### 持久证据写入

`retention_mode=durable_managed` 的 source 和经 Promotion Gate 转换成 `durable_promoted` 的 item 进入 `EvidenceIngress`：

```text
acquisition_run_id
trigger = scheduled | on_demand | investigation | promotion
source_id
external_object_id
canonical_url
published_at / updated_at / observed_at
external_revision
media_type
payload / payload_ref
content_hash
request_metadata
idempotency_key
```

Evidence Ingress 校验 source、时间、hash 与 payload 可读性。managed content 固定正文快照；已晋升 bug 固定本次结论实际消费的 provider 版本；已晋升 incident 固定支撑时间线/claim 的 primary、forensic 或 selected 信号版本。

产物写入 S3-compatible store 后，PostgreSQL transaction 创建 `Observation`/`EvidenceArtifact` 元数据与 downstream 发件箱事件。commit 后返回 `ObservationAck`。Normalization 作为独立 task 读取观测，parser/model 失败不会破坏原始证据，可按处理器版本重新处理。

### 解析与规范化

每个 source 都先经过 source-specific parser，再进入 canonical mapper。parser 解决“外部字段在哪里”；canonical mapper 解决“这个字段在 SecFusionAgent 表示什么”。相同 mapper schema 服务热与 durable path，但写入目标不同。

热规范化生成当前投影、stable identifier、changed fields 与 priority 信号，写回 Redis；普通 feed record 不创建长期 `Object/Claim/Relation`。Incident 信号 staging 生成 anchor/聚类/watch 状态；durable 规范化在 PostgreSQL transaction 中完成 object upsert、外部标识符绑定、source claim/relation、证据 link、processing run 与 `KnowledgeChange`，Incident 晋升同时维护 `SecurityIncident`、时间线事件与 incident 版本/发件箱。对快照型 provider，同一 `source_id + subject + predicate/relation type` 的新版本会 supersede 该来源旧当前状态；不同来源的不同值同时保留，交给当前投影暴露 conflict，而不是在 M2/M3 静默裁决。

确定性 mapping 覆盖 CVE/GHSA/NVD/OSV 的 vulnerability/package/version/CWE/CVSS/reference，GitHub repo/issue/PR/commit/release，package/model registry 身份，DOI/arXiv work 身份，以及 normative document 的 issuer/jurisdiction/status/version。HTML/PDF parser 负责 document structure、明确 identifier 和 locator mapping；impact、attack condition、隐式 relation、risk/control mapping 进入 M3 语义处理器。

### 同一性与去重

热路径使用 provider namespace + 外部 ID/版本收敛重复更新，并保留 cross-reference hint。durable path 进一步处理 cross-source 身份：CVE/GHSA/DOI/repo/package/commit 等强 identifier 直接绑定既有 object；provider 明确 cross-reference 和稳定 normalized key 可以自动绑定。缺少强身份的相似记录保持独立 object，并生成 `candidate_same_as` 供 M3/analyst 后续判断。

Object merge 保留全部 durable 观测。NVD、GHSA、vendor advisory 和 issue 可以映射到同一个 vulnerability object，各自的证据、时间和 source claim 继续独立存在。

### M2 输出

M2 按保留生命周期产生三类稳定输出：

```text
HotNormalizationResult
  source_id
  external_object_id
  external_revision
  available_at
  changed_fields
  current_projection_ref
  priority_signals

IncidentSignalResult
  signal_id
  incident_candidate_id
  available_at
  material_change
  source_role
  next_watch_at

NormalizationResult
  observation_id
  knowledge_revision / incident_revision
  committed_at
  object_ids
  claim_ids
  relation_ids
  timeline_event_ids
  candidate_match_ids
  processing_run_id
```

`HotNormalizationResult` 驱动 Bug Stream 的 priority/enrichment；`IncidentSignalResult` 驱动 Incident Watch 的聚类/follow-up；`NormalizationResult + KnowledgeChange` 与 incident 版本/发件箱驱动 durable M3、当前投影与索引器。Requirements 的 monitoring latency 使用对应生命周期的 `available_at/committed_at`。

### M2 质量契约

M2 的自动 identity merge 只接受强 identifier 或可复现的 deterministic cross-reference。CVE/GHSA/OSV/CNVD/CNNVD、DOI/arXiv、GitHub repo full name、package PURL 或 ecosystem+name、commit SHA 可以作为强标识；名称相似、标题相似和 embedding proximity 只能形成 candidate，不直接合并 object。

每个 accepted claim/relation 必须解析回固定 Observation / Artifact 和 locator。structured mapper 的 locator 要落在支持该字段/关系的 source revision；semantic extraction 额外要求 verbatim quote 是固定 chunk 的真实 substring。M7 将 parser field accuracy、replay suppression、entity-resolution precision/recall、evidence correctness、conflict preservation 分开记录，因此“值正确但引用错误”不会被 M3 P/R 掩盖。

## M3 情报富化与关联

M3 由 `packages/enrichment` 持有，输入可以是 Redis 中的 `HotBugRecord/HotNormalizationResult`、`IncidentCandidate/IncidentSignalResult`，也可以是 PostgreSQL 中的 durable object/证据。热漏洞 enrichment 回写当前投影；Incident enrichment 更新 unresolved questions、source follow-up 与晋升状态；需要长期引用时先调用 `PromotionService`，再写 durable claim/relation/时间线。M3 新增外部材料统一调用 `AcquisitionService`。

### 处理器路由

Enrichment Planner 根据 object type、risk domain、source 权威、已有 claim 和信息缺口创建处理器任务。

| Processor | 输入 | 适用任务 |
|---|---|---|
| deterministic | structured knowledge | CVSS/CWE/KEV mapping、version compare、分类体系 mapping、固定 graph rule |
| graph / 产物 | repo/package/artifact relation | issue–PR–commit–release、dependency、SBOM、container/component propagation |
| semantic | 热/durable source content | attack condition、impact、patch/workaround、TTP、risk/control、implicit relation |
| provider-backed | query spec | NVD/OSV/KEV/GHSA refresh、Internet asset intelligence、商业/实时 provider |

Planner 使用 rule/config 决定处理器组合；LLM 接收 Planner 已确定的 semantic extraction task。每个处理器产生 `ProcessingRun`，输入版本和处理器版本固定后可以独立回归。热对象的处理器结果默认写回 Redis 投影；出现 durable 晋升信号后，处理器等待对应证据/object 进入 PostgreSQL，再提交长期 claim/relation。

### 提供方回流

provider-backed 处理器调用 `AcquisitionService.query(source_id, query_spec, parent_run_id)`。Source Adapter 返回的 `IngestEnvelope` 按 source 保留模式进入热、incident 或 durable M2 path；M3 等对应 normalized 状态后恢复 parent enrichment job。热漏洞或 incident 信号要支撑 durable investigation/answer 时，先经过 Promotion Gate 固定版本。NVD lookup、GitHub object、vendor page、论文、news/forensic follow-up 和 Internet asset query 共享来源链路/去重 contract，同时保留各自保留策略。

Internet asset intelligence 保存 provider、query、filter/fingerprint、query time、host/service result 与观测时间。product/version 到 fingerprint 的 mapping 单独版本化；“可能受影响资产”由具体 provider 观测 + mapping 版本支撑。

### 语义处理

语义处理器从 `DocumentProjection` 读取相关 section，并把 source 元数据、object 候选和需要抽取的 schema 一起发送给 Model Provider。外部正文始终位于 data field；system instruction、schema、model 和 token budget 来自代码/config。

模型输出进入候选状态：

```text
candidate claims
candidate relations
entity candidates
evidence locators
processor/model/prompt revision
```

写入门禁校验 schema、subject/object 身份、证据 locator、处理来源链路与 semantic duplicate。高不确定实体对齐保持候选；有强 identifier 或确定性规则支撑时晋级 accepted relation。模型生成的 citation locator 无法回到 source 产物时，该候选直接失败。

### 领域处理器

M3 的共享流水线根据 01–04 加载领域处理器：AI Infra 沿 repo/component/release/runtime graph 补 issue、fix PR/commit、affected/fixed version 与 integration；Supply Chain 沿 package/artifact/image/build/distribution relation 计算传播；Model/Data 关联 paper、评测集、attack、mitigation、known bypass 与 residual risk；Agent/Application 关联 context、tool、身份、sandbox、network、memory、side effect 与 incident path；Normative Knowledge 抽取 `Requirement/Control/applicability`；Research Intelligence 生成 `InsightCandidate`。

领域处理器扩展 object type、claim predicate 和 relation type，证据、处理来源链路、写入门禁共用同一 kernel。

### 洞察与索引

paper、vendor report、system/model card、独立研究先作为证据/object 进入 M2。M3 根据 04 的晋升 criteria 生成 `InsightCandidate`，记录它支持、反驳或扩展的既有 claim、证据成熟度、what changed 与处理版本；source 权威继续由原观测持有。

Knowledge commit 后发出 `KnowledgeChange`。索引器对新增/变更 document/object 构建切块、元数据和 embedding；旧 index entry 按上游版本失效。M4–M6 可以立即读取 canonical knowledge，semantic retrieval 读取对应 `indexed_revision`；M7 评测集固定 knowledge/index 版本以保证可复现。

### Vocabulary 与富化闭集

M3 的正式 enrichment vocabulary 由 `packages/intelligence/knowledge/vocabulary.py` 持有，当前版本为 `enrichment-v1`。term 分为 `canonical / source_specific / exploratory` 三种 scope；canonical claim/relation 可以固定允许的 subject/target object type 和 `benchmarked` 标记。Knowledge Writer 使用真实 root object 检查 shape：deterministic/source-asserted 写入未注册 term 或违反 canonical shape 时直接失败；semantic 的未知 term 或非 canonical shape 保留为 exploratory。这样既阻止模型自由字符串悄悄改变 benchmark，也保留开放语义发现。

`enrichment-v1` 固定十二个 dimension：identity、severity、weakness、product/package、version applicability、fix/remediation、exploit state、exploit likelihood、advisory/reference、asset exposure、research/paper、incident context。Identity 主要服务 M2 normalization diagnostic；repository 内部 graph edge 与开放 research/incident relation 可以属于 canonical vocabulary 但标记 `benchmarked=False`。provider-native `github_* / osv_* / kev_* / cnvd_* / cnnvd_*` 与 NVD/CVE 原始字段继续保留，不因存在于 Knowledge 就自动进入比赛 denominator。PoC benchmark 使用 `Vulnerability --has-poc→ ExploitArtifact`，`poc_available` 是派生投影；research/paper v1 只评测稳定的 `ResearchWork/Document --discusses-vulnerability→ Vulnerability` association，更开放的 supports/contradicts/evaluates relation 在 object model 与 gold protocol 冻结前不进入正式 P/R。`workaround / mitigation / attack_condition` 这类开放文本同样保留为 canonical evidence-backed knowledge，但 v1 标记 `benchmarked=False`，直到 normalized schema 冻结。`release-contains-commit`、`asset-runs-product`、`asset-version` 等支撑推导的 graph edge 也保持 canonical/non-benchmarked；v1 的 affected-asset 正式输出以 `InternetAsset --asset-potentially-affected→ Vulnerability` 为 gold，避免把推导中间边重复计入比赛 denominator。

产品/版本适用状态统一为 `affected / not_affected / fixed / under_investigation / unknown`。统一输出不是挂在 Vulnerability 上的裸 claim，而是 scoped `Vulnerability --applicability-status→ Product|Package|SoftwareVersion` relation，qualifier 至少包含 `state` 与 `source_semantics`，并可附 version range / justification。CVE Record 5.x、OSV、NVD CPE configuration、CSAF/VEX 各自保留 source-specific range/status semantics，由 evaluator 映射到统一状态；GIT range 依赖真实 repo ancestry。query miss、source miss 或版本不可比较都保持 `unknown`，只有结构化状态、确定性规则或 VEX justification 才能产生 `not_affected`。

当前代码已经覆盖 CVSS/CWE 与 canonical `has-weakness`、CVE5/OSV/NVD CPE/CSAF-VEX source-specific applicability、CISA KEV、canonical PoC relation、GitHub Advisory + FIRST EPSS point-in-time facts、GitHub development/fix graph、CNVD/CNNVD identity、AssetObservation、完整 NVD configuration 驱动的 CPE applicability join、exact paper-CVE relation 与 evidence-gated document semantics。统一的是 canonical applicability **输出状态与 relation contract**，不是把不同来源的 range/VEX/CPE 规则压成一个字符串比较器。当前 backlog 主要是授权 live asset、更多 paper/incident strong-anchor 与 semantic-provider denominator，以及 Incident→Vulnerability 等尚未进入当前正式闭集的覆盖扩展；闭集冻结不等于 denominator 已经足够大。

### M3→M4 semantic handoff 与 M7 enrichment score

storage/read handoff 已由真实 PostgreSQL integration gate 验证。semantic handoff 额外要求 M3 使用同一 vocabulary 描述每个 canonical dimension 当前是 resolved、conflict、unknown 或 missing；M4 后续只能基于这些 gap 规划调查，不能另建一套 enrichment ontology。

M7 的最小 gold 单元由 `packages/evaluation/m1_m3.py` 中的 `EnrichmentFactKey` 固定：stable root object key/type、vocabulary revision、dimension、claim/relation kind、predicate/relation type、normalized value/target、target object type、qualifier keys + normalized qualifier 与 temporal scope。gold 自身使用同一 registry 校验 subject/target shape、`benchmarked` 与 required qualifier。TP 同时要求 tuple、entity/version scope 和 EvidenceRef 正确；错值、错实体/版本、错 relation、将 unknown 推成 not_affected、无证据 accepted fact 计 FP，gold 缺失计 FN。正式比赛报告使用 micro precision/recall，内部同时报告 dimension-macro P/R 与 M2 diagnostics。

benchmark case 固定 world snapshot、source availability、source revision、vocabulary revision 与 evaluator revision。structured-only、multi-source conflict、CVE/OSV/NVD/CSAF applicability、KEV/PoC、time-bounded asset、paper relation、Incident strong-anchor、alias ambiguity 与 wrong-version trap 都需要进入固定样例；开放式 semantic relation 不通过同一 closed-set scorer 强行打分。

## 端到端路径

下面五条路径覆盖高频漏洞、结构化平台、Managed Content、Incident Watch 与 on-demand enrichment，也直接作为第一轮 integration test / 探针。

### CVE / GHSA / NVD

CVE/GHSA/NVD/OSV/KEV 的 delta 首先更新 Redis 热工作集。新发布记录和已有记录的版本变化都进入热路径；M2 做廉价规范化与 field-level diff，M3 只对 target repo match、KEV/PoC/critical 信号、active query/investigation 等高优先级对象继续 enrichment。普通记录在 TTL/LFU 后淘汰，历史 miss 直接从 canonical provider 重取。

Product WORLD 的 Hot 索引按固定、工作流使用、访问和更新排序，`/api/v1/world/hot?limit=24&offset=N` 每页返回来源记录，并单独报告驻留总量；API 当前限制 offset 不超过 4096。完整 CVE 编号走 `/api/v1/world/hot/search`，扫描 Redis 当前驻留 payload 的外部 ID 与 `projection.cve_id`，因此外部编号为 GHSA、但投影关联同一 CVE 的来源记录也能返回。普通文本只过滤已载入页面。两条读取路径都不触发 promotion，也不把 Hot 记录标成 durable Knowledge。对应 Product Web/API 变更：`64e93fe`、`5543be5`、`cc8fea3`。

当某个漏洞进入 target repo graph、M4/M5 调查、M6 citation、source conflict、评测集或 analyst review 时，Promotion Gate 固定当前 provider 版本并写 durable 证据 / canonical knowledge。GitHub issue–PR–commit–release、affected/fixed version 和供应链关系随后长期保留。这样漏洞 feed 的时效性由 bounded 工作集承担，长期数据库只沉淀 SecFusionAgent 真正使用或产生的新知识。

### 目标仓库 / 供应链

GitHub `selective_index` 已从 target repo 稳定身份与 metadata/current claim 扩展到 `Repo / Issue / PullRequest / Commit / Release` 一等对象和显式 reference graph。M3 graph 处理器维护 issue→PR→commit→release 等确定关系，并为 deterministic fix-boundary verification 提供结构化路径；package/container/dependency relation 继续按 source coverage 扩展，OSV、SBOM、registry 或 scanner 结果用于验证产物是否真实包含受影响版本。长 issue、vendor PSIRT 或 patch explanation 按 managed content 保存并交给语义处理器抽取隐式条件。

### 论文 / 厂商 / 研究洞察

Managed Content 已覆盖 HTML/PDF/plain executable path：外部内容固定 source revision 后进入 `Document/DocumentRevision` 与 `DocumentChunk`，切块保留回原版本的 locator；PostgreSQL FTS 提供 lexical index，pgvector 列保存 provider-neutral dense state，semantic processor 要求 proposal 携带可在 chunk 中定位的 verbatim quote，否则拒绝写入。OpenAI-compatible model/embedding adapter 已接入 indexing worker；正式 Product QA 已证明兼容 model provider 可以执行，但 **M3 semantic extraction + dense indexing 的 live E2E 仍是独立 workload/denominator**，当前 CompetitionReport 不把 Product 模型调用冒充这条路径的验收。OpenReview、正式 proceedings 与更多 vendor/security research source 继续按 source onboarding 扩展；hybrid query planning、fusion/rerank 由 Technical Design 2 与 M7 probe 决定。

### 安全事件 / 新闻监测

Breaking source 首先生成 `SignalItem`，Incident Correlator 提取可验证 anchor 并聚类。当前 first batch 已接标准 RSS breaking source，规则抽取 CVE/GHSA/transaction/address；弱标题相似不参与 durable 晋升。`source_family/upstream_source` 用于折叠转载依赖，多源 corroboration 必须由两个独立 source 支持同一个 strong anchor。受影响项目官方渠道、security vendor 分析、on-chain 证据与 threat-intel follow-up 继续按 05 source plan 接入。

当事件达到晋升条件，M2 固定关键 source 版本，PostgreSQL 创建 `SecurityIncident` 与 append-only 时间线。M3 持续关联 Vulnerability、Product/Repo、ThreatActor、Address/Transaction、Advisory、Patch/Commit、IOC 和 affected Internet asset；M4 消费时间线和证据链形成 confirmed/conflict/unknown。事件结束后的 postmortem 可以进入 Insight Corpus，整个调查 trajectory 进入 Experience Evolution。

### 互联网资产

M3 在某个 vulnerability/product/version 需要受影响公网资产时创建 on-demand query。Censys/Shodan/FOFA/ZoomEye 适配器把 query/filter、provider response 和观测时间写入 M2；M3 使用版本/指纹 mapping 生成候选 `InternetAsset/ServiceEndpoint` relation。relation 保留 query time 和 provider 观测，使资产判断始终带时间边界。

## 调查经验演化

Knowledge 记录“关于对象已经知道什么”，Experience 记录“遇到某类调查任务时怎样更可靠地获得证据”。Bug 热缓存可以淘汰，大量历史 CVE 可以继续留在外部 canonical source；经过真实调查形成的可复用方法属于 SecFusionAgent 的长期资产，与 Insight Corpus 一样需要版本、来源链路和 evaluation。

### Case, Trajectory, Experience

`InvestigationCase` 定义一次可评价任务，保存 `task_signature`、target objects、goal、initial knowledge 版本、constraints 和 rubric。Case 可以来自 M5 investigation，也可以来自 M7 评测集重放。

`InvestigationTrajectory` 保存一次实际执行：读取过哪些 knowledge/experience、调用了哪些 source/tool、观察到哪些证据、尝试过哪些 hypothesis、发生哪些失败和 recovery，以及最终 outcome、latency、tool calls、cost。Trajectory 使用 append-only step/事件记录，原始 transcript 或大体积 tool output 可以进入产物存储，PostgreSQL 保存结构化事件与引用。

`Experience` 是从多个 trajectory 中抽取的可复用 investigation policy。它不保存某个 CVE 的事实，而保存适用条件与调查动作：

```text
experience_id / version
name
task_signature
scope
trigger_signals
applicable_conditions
recommended_actions
evidence_expectation
failure_modes
stop_conditions
fallback_actions
supporting_trajectories
validation_summary
success_count / failure_count / partial_count
last_validated_at
status = candidate | validated | active | deprecated
supersedes
```

失败经验是一等对象。例如“PR merged_at 不能直接推出修复发布”会记录 failure pattern、判别条件和替代证据路径；后续 planner 检索到它时可以主动避开已经验证过的错误调查路径。

### 演化流水线

```mermaid
flowchart LR
    Case[Investigation Case]
    Retrieve[Retrieve Active Experiences]
    Plan[M5 Plan / Investigation]
    Traj[Trajectory]
    Eval[M7 Outcome Evaluation]
    Extract[Experience Extraction]
    Candidate[Experience Candidate]
    Similar[Retrieve Similar Experience]
    Update[Create / Merge / Supersede / Reject]
    Replay[Historical Case Replay]
    Active[Active Experience]

    Case --> Retrieve --> Plan --> Traj --> Eval --> Extract --> Candidate
    Candidate --> Similar --> Update --> Replay --> Active
    Active --> Retrieve
```

M5 在规划前根据 task signature、target/risk domain、repo family 和当前证据缺口检索 `active` experience；retrieved experience 携带版本与适用条件，影响 action proposal，但不能覆盖当前证据。执行过程记录实际使用过的 experience version，使 M7 能统计“使用某条经验以后成功/失败/partial 的 outcome”。

任务结束后，Experience Extractor 从高信息量 trajectory 抽取 procedure、failure pattern、stop condition 或 fallback 候选。系统先用向量/元数据检索相似 experience，再决定 create / merge / supersede / reject。更新结果记录 rationale、supporting trajectory 与版本关系；`success/failure/partial` 与 `last_validated_at` 从 M7 evaluation 聚合，供召回排序和 deprecation 使用。OpenViking/RFC 的 trajectory analysis 与 semantic-gradient-style update 可以作为后续 optimizer 参考，第一版使用显式候选 + 重放 evaluation。

Candidate 晋级依赖 M7 evaluation，而不是把 trajectory 抽取结果直接当 active memory。当前 Experience Store 已强制 `candidate → validated → active` 状态机，并要求 `validated` 前存在重放/online support；具体多 case activation threshold 仍由 M7 评测集 policy 决定。一个 active experience 在后续 case 中持续失败、适用 repo/provider 发生结构变化或被新证据反驳时进入 superseded/deprecated，新版本激活时旧 active version 自动 deprecated。

### 归属与安全

M4 持有 Case 当前调查状态与 confirmed/conflict/unknown；M5 持有 Trajectory 和 experience retrieval/use；M7 持有 outcome/rubric/重放 evaluation，并负责 Experience 的 validation 信号。Experience Store 属于 investigation capability，事实证据仍由 M2/M3 knowledge plane 持有。

Experience 是 planning hint / policy memory，没有 source 权威。任何经验产生的调查动作仍需要从当前 source 重新获得证据；最终 claim 继续满足 C1。外部网页、tool output 和 peer-agent message 不能直接写 active Experience，必须经过 trajectory、evaluation 和 versioned update 流水线。

### OpenViking 参考

OpenViking 的 Session commit 已经把 `cases`、`trajectories`、`experiences` 作为长期 memory type，并在启用 `experiences` 时联动完整 Agent Evolution 流水线。其 memory extraction 使用 `LLM Extract → Vector Pre-filter → Similar Memory → LLM Dedup Decision → create/merge/delete → write/vectorize`；Agent Evolution API 还能按 Experience 查询实际使用它的 Trajectory 和 outcome distribution。这套机制作为 SecFusionAgent Experience Evolution 的直接设计参考。

SecFusionAgent 保留 domain 归属：Case rubric、security 证据来源链路、tool trajectory、knowledge 版本、评测集 result 和 Experience validation 都由本项目数据模型持有。OpenViking 未来可以作为 experience retrieval/memory provider 接入 `ExperienceStorePort`，但 Experience 的生命周期和评价 contract 由 SecFusionAgent 定义。

SecFusionAgent 长期沉淀四类资产：`Knowledge` 保存事实与关系，`Incident` 保存现实事件及其演化，`Insight` 保存对风险与防御的新认识，`Experience` 保存怎样更可靠地完成调查。它们可以引用同一证据，归属和生命周期分开。

## 接口

M1–M3 之间保留少量稳定 port，具体存储和任务框架停留在 provider 层。

```text
SourceAdapter.discover / fetch / query
AcquisitionService.schedule / query
HotBugIngress.accept -> HotNormalizationResult
EvidenceIngress.accept -> ObservationAck
KnowledgeRepository.read / commit -> KnowledgeChange
HotBugCache.get / admit / touch / evict / pin
IncidentSignalStore.admit / cluster / watch / expire
IncidentRepository.append_event / update_view
PromotionService.promote
ArtifactStore.put / get
RetrievalPort.search
ExperienceStore.retrieve / append_candidate / activate / supersede
ModelProvider.generate_structured
```

`EvidenceIngress` contract 由 `packages/intelligence` 持有；`packages/sources` 产生符合该 contract 的 envelope。`KnowledgeRepository` 由 intelligence 持有，M3 通过它写 canonical knowledge。`AcquisitionService` 由 `packages/monitoring/acquisition` 持有，`packages/sources` 只持有 source definition、provider contract 与适配器，不反向依赖 runtime 状态。M3/M5 通过 acquisition service 获得新外部证据。依赖方向保持 `apps → capability package → lower-level contract/provider`；runtime entrypoint 依赖 domain，domain 保持与 `apps` 解耦。当前 `tests/test_architecture_dependencies.py` 把 package dependency direction 变成 executable invariant。

## 可靠性

系统采用 at-least-once execution + 幂等状态转换。Celery Broker Redis 与 Hot Cache Redis 分离：broker 承载任务传输并避免淘汰，cache 承担 bounded 工作集并允许 TTL/LFU 回收。canonical run、durable 证据、knowledge 和 experience version 留在 PostgreSQL；调度器/recovery 工作进程根据 `queued/running` 超时和发件箱 delivery 状态重发任务。

Durable `Observation` 写入成功后原始证据可重放；热漏洞 record 丢失或淘汰时从外部 canonical source 恢复；incident 信号过期不会删除已经晋升的 Incident/时间线。Normalization、Enrichment、Indexing 的失败分别记录 `ProcessingRun` 并独立重试。晋升在 durable conclusion 之前完成，避免最终证据依赖已淘汰 cache。Source failure 按 source 隔离，持续故障通过 M8 observability 进入告警。

Database write 和 downstream task 之间使用 transactional 发件箱：knowledge transaction 同时写领域状态、`KnowledgeChange` 和 `outbox_events`；dispatcher 把已提交事件送入 Celery，consumer 使用事件 ID / input 版本作为幂等键。进程在 DB commit 后崩溃时，发件箱仍能恢复下游处理。

## 仓库映射

第一版代码按当前 repo standard 建立以下责任，对应 capability 开始实现时再落目录。

```text
apps/
├── api/                     # FastAPI bootstrap
└── worker/                  # Celery worker / scheduler bootstrap

packages/
├── sources/
│   ├── registry/            # SourceDefinition + config loader
│   └── adapters/            # GitHub, NVD, OSV, KEV, arXiv, RSS, asset ...
├── monitoring/
│   ├── acquisition/         # AcquisitionService + on-demand run provenance
│   ├── scheduler/           # due-source + incident follow-up scheduling
│   ├── hot_window.py        # hot_window collector
│   ├── managed_content.py   # durable_managed collector
│   ├── structured_index.py  # selective_index collector
│   └── incident_signal.py   # incident_signal collector
├── intelligence/
│   ├── incident/            # SignalItem / IncidentCandidate / clustering / timeline
│   ├── hot_cache/           # Redis hot working set + admission/eviction
│   ├── ingestion/           # durable EvidenceIngress
│   ├── promotion/           # Hot Bug promotion
│   ├── knowledge/           # Object/Claim/Relation contract + evidence-backed writer/read
│   ├── normalization/       # parser + canonical mapper + identity/diff
│   ├── structured/          # structured source normalizer, e.g. GitHub Repo
│   ├── documents/           # managed document parser/chunker/revision
│   ├── projections/         # rebuildable current views
│   ├── storage/             # PostgreSQL models + S3-compatible ArtifactStore provider
│   └── retrieval/           # lexical/dense index state + provider contracts；query planning 属于 M4
├── enrichment/
│   ├── processors/          # provider-backed vulnerability enrichment
│   ├── graph/               # GitHub reference graph + deterministic fix boundary
│   ├── semantic/            # evidence-gated managed-document semantic extraction
│   ├── providers/           # OpenAI-compatible model/embedding adapter
│   └── assets/              # time-bounded Internet asset observation orchestration
├── investigation/
│   ├── cases/               # InvestigationCase / context handoff
│   ├── trajectory/          # append-only investigation trajectory
│   └── experience/          # Experience Store / evolution lifecycle
└── shared/                  # config/logging/clock 等业务无关基础能力
```

数据库迁移归拥有对应表语义的 package，但统一由 Alembic 迁移 history 发布。source 适配器不依赖 monitoring/intelligence；monitoring 组合 source 适配器与 M2 ingestion；intelligence/knowledge 持有 canonical write contract；enrichment 依赖 intelligence/knowledge 与 monitoring/acquisition。这个依赖图保持单向，M1/M2/M3 通过 contract 协作，并由 architecture test 防止反向 import。

## 实现切片

第一轮实现按可独立验收的纵向切片推进：

1. **Foundation**：Docker Compose 启动 PostgreSQL/pgvector、Redis Broker、Redis Hot Cache、MinIO；建立 FastAPI/工作进程 bootstrap、配置加载、SQLAlchemy/Alembic、`sources/source_state/acquisition_runs/processing_runs/outbox_events`。
2. **Hot bug 切片**：实现 `cvelistV5`/NVD 等 delta、Redis 准入/TTL/LFU、HotNormalizationResult、field-level diff、游标重放与外部缺失 fallback；验证 high-frequency bug 工作集。
3. **Promotion / canonical knowledge 切片**：实现 Promotion Gate、durable Evidence Ingress、Object/ExternalIdentifier/Claim/Relation/EvidenceLink、knowledge 版本与查询 API；用真实 active bug 验证热 → durable 晋升。
4. **Enrichment 切片**：实现 NVD/OSV/KEV/GitHub provider-backed 处理器、deterministic version mapping 与 graph 处理器，再接 Semantic Processor；M3 外部 lookup 继续走 M2 re-entry。
5. **Incident Watch 切片**：接入两个 breaking source、一个 forensic source 和一个 primary/权威 source，完成信号 TTL、cross-source 聚类、adaptive follow-up、晋升、时间线与 `current_incident_view`。
6. **Managed content / retrieval 切片**：实现 HTML/PDF 投影、证据 locator、切块/embedding 与 `RetrievalPort`，随后接 arXiv/vendor/research source 和 `InsightCandidate`。
7. **Current projection 切片**：把 vulnerability/fix/repo/incident 当前视图接到 `KnowledgeChange` / `incident.changed`，验证 incremental invalidation 与 multi-tier read path。
8. **Source expansion**：增加 target repo、normative source、Internet asset provider；每增加一类 source 同时固定 source role、保留模式、fixture、contract test 与 M7 评测集 case。
9. **Experience 切片**：建立 Case/Trajectory/Experience schema，用真实 AI Infra/Incident 调查 case 记录 trajectory，抽取正/负经验，做 similarity merge 与历史重放；M5/M7 后续复用这套生命周期。

每个切片都能从真实外部来源跑到本地可查询状态；下一个切片复用前一个切片的 contract。

历史 checkpoint（2026-09-26）：当时 M3→M4 handoff 已有 executable gate，Foundation、Hot Bug、Promotion/Canonical Knowledge、provider-backed Enrichment、Incident domain、HTML/PDF/plain Managed Content、Current Projection、GitHub development graph、lexical/dense indexing、semantic evidence gate、time-bounded Internet asset observation、S3-compatible ArtifactStore、outbox/Celery replay/idempotency与 Experience storage 接缝均已有代码/tests；真实 PostgreSQL/pgvector/FTS、Redis、Celery和 S3-compatible integration已通过。该 checkpoint 当时记录的 MinIO/provider access、Shodan credential、semantic+dense live E2E、OSV `GIT fixed`样本与 Incident follow-up 等缺口属于历史推进状态；当前完成度以上文 2026-10-16 状态与正式 benchmark evidence 为准。Task routing、query construction、retrieval fusion/rerank、candidate assembly、Percept construction 与 Investigation State 的 owner 仍保持在 M4 / Technical Design 2。

## 设计参考

这些系统用于验证架构接缝与生命周期设计，SecFusionAgent 复用机制和接口思想，内部归属仍由 Requirements 与本文决定。

| Reference | 借鉴点 | SecFusionAgent 对应设计 |
|---|---|---|
| [Foresight News Timeline](https://foresightnews.pro/timeline) | 安全事件作为持续时间线维护，而不是把每条快讯当成独立终点 | IncidentCandidate / 时间线 watch 的产品参考 |
| [CertiK Incident Analysis](https://www.certik.com/blog/research?tab=incident-analysis) | exploit 事件形成独立 incident analysis，记录机制、损失与后续 | 已晋升 Incident → forensic enrichment / postmortem |
| [OpenCTI Automated Import](https://docs.opencti.io/latest/usage/import/getting-started/) / [Analyst Workbench](https://docs.opencti.io/latest/usage/workbench/) | connector/stream/TAXII/RSS 等统一 ingestion；import 后先进入 workbench，再由 analyst review 进入正式 knowledge | SourceAdapter、candidate/写入门禁、durable 证据与 analyst exception path |
| [TheHive / Cortex analyzer workflow](https://docs.strangebee.com/thehive/user-guides/analyst-corner/cases/observables/run-analyzers-on-an-observable/) | case、observable、analyzer enrichment 和 investigation context 分层 | M4 Case、M5 enrichment/investigation、证据 write-back |
| [OpenViking Session / Memory](https://github.com/volcengine/OpenViking/blob/main/docs/en/concepts/08-session.md) | `cases/trajectories/experiences`、commit extraction、vector pre-filter、similar-memory 去重/merge | Experience Evolution 流水线 |
| [OpenViking Agent Evolution](https://github.com/volcengine/OpenViking/blob/main/docs/zh/api/19-agent-evolution.md) | 查询 Experience 被哪些 Trajectory 使用，以及 success/failure/partial outcome distribution | M7 对 experience effectiveness 的追踪 |
| [VikingDB](https://www.volcengine.com/docs/84313/1860732?lang=zh) | collection/index、vector/scalar/hybrid retrieval、update/delete 与索引异步刷新 | `RetrievalPort` / future vector provider；第一版仍用 pgvector |
| [UBASE, ByteDance, 2026](https://arxiv.org/abs/2608.30607) | sustained ingestion 下的 vector indexing、memory/SSD hybrid residency、record-level cache 调节 memory/latency/cost | data temperature、热/冷 tiering 和未来大规模 retrieval 优化参考 |

UBASE 和 VikingDB 面向远大于比赛规模的向量数据；本文借鉴的是 workload-aware residency、index/update separation 和 provider 接缝，不复制其分布式实现。OpenViking 提供通用 memory evolution 范式；SecFusionAgent 增加 security-domain Case rubric、证据来源链路和 M7 重放 validation。

## 技术评审与探针

Technical Review 需要确认本文的 runtime、storage 和 code 归属能完整承接 Requirements。进入正式实现前执行下列短探针，结果用于验证技术基线：

| 探针 | 实际跑什么 | 判别结果 |
|---|---|---|
| Hot bug lifecycle | CVE/NVD delta：new/update → Redis → diff/enrich → TTL 淘汰 → miss re-fetch → 晋升 | 工作集 bounded；更新时效正确；已晋升证据不依赖 cache |
| Structured source E2E | GitHub target repo：discover → normalize → relation → 重放 | 游标、版本、幂等、发件箱与 source failure 语义成立 |
| Incident Watch | 选一个真实 incident：3+ breaking/forensic/primary source → 聚类 → 时间线 → 晋升 → follow-up | duplicate 不会制造假 corroboration；material change 进入时间线；低价值信号可过期 |
| Managed content E2E | 一篇 PDF + 一篇动态网页：快照 → 投影 → 证据 locator → semantic extraction → embedding | citation 能回原文；parser/model 升级可重算 |
| PostgreSQL knowledge/retrieval | repo/vulnerability/package graph + 文档切块上运行结构化、recursive relation、vector/元数据 query | 当前规模下 latency/recall 支撑 M3/M4；失败时才引入独立 graph/search provider |
| On-demand asset | 一个漏洞/产品映射到一个 asset provider query，保存 query/revision/time，再重放 | 高时效观测与长期 knowledge 边界清楚，provider failure 可恢复 |
| Experience evolution | 5–10 个已知调查 case：trajectory → candidate → merge/create → 重放 → outcome | 正/负经验可追溯；错误经验不会单次成功后直接进入 active |

OpenCTI/MISP interoperability 作为 integration test：导入/导出一组 STIX object 并验证内部 object/relation/证据 mapping。若探针发现某个成熟平台可以直接替换自研 provider，优先替换 provider；Requirements 中的证据、knowledge、risk 与评测集 contract 继续保持。

### 2026-10-16：后台模型费用暂停开关（当前工作树）

运行时增加 `SECFUSION_BACKGROUND_LLM_ENABLED`。设为 false 时，document worker
仍完成 lexical index，但不启动 embedding、semantic/normative extraction；
projection 与 WorldChange 处理继续，自动 WATCH episode 不再新增；自动编研的
scheduler 和 worker 同时检查此开关。Compose 当前默认关闭后台模型及自动编研。

此开关不清空共用模型配置：用户问答、调查和手动报告维持可用。非模型的采集、
证据留存、规则富化和投影继续运行。恢复后不自动补跑暂停期间跳过的模型阶段，
需要按 revision 显式重处理。运行中的请求在 worker 优雅退出时完成；既有结果保留。