# SecFusionAgent Technical Design 2

[English](Technical-Design-2.en.md) | 中文 · 2 | [Technical Design 1](Technical-Design-1) | [Technical Design 2A · Application Backend](Technical-Design-2A) | [Technical Design 3 · Measurement](Technical-Design-3)

> 交互视图：**M4–M6 调查与执行平面** — [中文](https://jiale-li-orion.github.io/SecFusionAgent/diagrams/tech-design-lower.zh.html) · [English](https://jiale-li-orion.github.io/SecFusionAgent/diagrams/tech-design-lower.en.html)

本文承接 Technical Design 1 已固定的 M1–M3 Evidence/Knowledge 数据平面、Case / Trajectory / Experience 存储接缝，并定义共享 Agent Task Runtime：Task protocol、reference-preserving context、异步多 Loop、M4 调查状态、M5 Investigation Role、Capability / Policy / Sandbox 执行控制、M6 研判输出，以及 M7/M8 所需的回放与运行记录。M3 的 domain state / operator / canonical write 仍归 M3；其中 Enrichment Role 可以运行在本文定义的共享 Task Runtime 上。`本地wiki/tech design cache02.md`、`tech design cache03.md` 保存设计形成过程；本文保存进入实现与测试的运行时契约。

运行时不围绕聊天历史建模，也不以自然语言摘要作为 Agent 之间的主要交接介质。系统处理的是持续变化的 Evidence World、版本化 Task/Context/State 引用和多个可独立恢复的 Loop：简单查询读取当前投影后结束；M3 Enrichment Role 可以后台持续补齐 canonical dimension；M5 Investigation Role 根据当前 Case 的 EvidenceNeed 主动调查；WATCH 以等待/唤醒事件驱动短 episode。Agent 只能通过受控感知读取世界，只能通过 State/Knowledge write gate 改变 durable state，只能通过 Capability Broker 执行真实动作。

### 设计与实现状态 — 2026-10-16

Task admission、Task/Context/Event、M4 State、M5 有界规划/感知/委派、M6 引用研判与 M7 受控回放已实现。WATCH 使用离散 episode 与相关性唤醒；当前本地运行因费用控制暂停新增自动 WATCH，不影响用户发起调查。M5/M6 模型请求已接 token/retry reserve→settle；M3 模型预算结算仍开放。

生产 Capability 组合包含官方 NVD、已注册公开 HTML 与已配置 GitHub 仓库的 PR/commit/release/compare 记录。已通过受控 API/证据回流回归；原 NVD 单例在线联调记录不能泛化为所有外部能力的成功率。通用搜索、任意仓库/资产动作与真实 OpenShell/Firecracker 隔离验收仍开放。

A2A 已有 typed mapping 与账户约束下的 GetTask；SendMessage/订阅/push transport 尚未交付。M4 历史状态可重建，完整 M1–M3 Historical Knowledge Reader 仍缺失，因此不能将受控 replay 说成任意旧世界的真实 Agent 重执行。Context reference-vs-summary 属于未完成的对照实验。

验收结果按能力逐项维护于 [当前验收台账](Current-Acceptance)，下文协议定义不随运行开关改变。旧 522-test/0029-migration 阶段不再作为当前基线；历史结果只以原冻结记录为准。

## 运行架构

SecFusionAgent 使用一个共享 **Task Runtime** 承载不同 domain role，而不是为每种 Agent 人格复制一套 orchestrator。Task 先定义工作契约，再选择能够承担该契约的 Role；Role 决定 state model、planner profile、skill/capability preference，执行控制面最后决定哪些真实动作可执行。

```mermaid
flowchart LR
    Entry[用户请求 / KnowledgeChange / Watch 唤醒]
    Task[Task Runtime
Contract / Run / Event / Context]
    Enrich[M3 Enrichment Role
EnrichmentState]
    Investigate[M5 Investigation Role
InvestigationState]
    Perception[Perception Runtime]
    Decision[M6 Decision Runtime]
    World[M1-M3 Evidence World]
    Event[Async Event Plane
TaskEvent / StateChanged]
    Control[Execution Control Plane
Capability / Policy / Budget / Identity / Network / Sandbox]

    Entry --> Task
    Task --> Enrich
    Task --> Investigate
    World --> Perception
    Enrich --> World
    Investigate --> Perception
    Perception --> Investigate
    Investigate --> Decision
    Enrich --> Event
    Investigate --> Event
    World --> Event
    Event --> Task
    Control -.enforces.-> Enrich
    Control -.enforces.-> Investigate
    Control -.enforces.-> Perception
```

边界固定如下。

- **Task Runtime** 持有 TaskContract、TaskRun、parent/child dependency、ContextManifest、TaskEvent 与调度状态；它不持有漏洞/Incident 事实。
- **Enrichment Role** 是 M3 的常态 Agent workload。它消费 M3 `EnrichmentState` 与 operator/source catalog，完成 background 或 delegated enrichment；结果必须回到 Acquisition/Evidence/Knowledge gate。
- **Investigation Role** 是 M5 的主动调查 workload。它消费 M4 InvestigationState / EvidenceNeed，可以委派 EnrichmentTask，但不会把子 Agent 的自然语言结果直接当成事实。
- **Evidence World** 继续由 M1–M3 持有长期事实、关系、Incident、Insight、EvidenceRef、文档版本和 Current Projection。
- **Perception Runtime** 是 Agent 读取 Evidence World / external observation 的受控接口；外部工具结果先形成 EphemeralObservation。
- **M4 State Runtime** 持有 Case、EvidenceNeed、confirmed/conflict/unknown/tentative 等调查状态；它不复制一套 parallel Knowledge。
- **M6 Decision Runtime** 只读取 M4 当前状态；状态不足时提出 ContinuationRequest，由 M4 决定是否打开 EvidenceNeed。
- **Async Event Plane** 传递 Task/Context/Knowledge/Enrichment/Investigation state change；事件先经过 deterministic relevance gate，再决定 refresh、wake 或 defer，不让每个事件都触发 LLM。
- **Execution Control Plane** 持有 capability、authorization、obligation、budget、identity、network、sandbox 与 side-effect enforcement；prompt/role 不能突破该边界。

Agent 不直接持有数据库自由查询、provider credential、任意 HTTP、shell、browser 或 Docker socket。Tool/MCP metadata 只用于 implementation discovery；CapabilityContract 和 PolicyDecision 才是 runtime trust contract。

## Task Protocol、Role 与执行配置

设计顺序固定为 `Task → Role → Context/Handoff → Loop/Scheduling → Capability → Policy`。系统不先建立 Researcher / Analyst / Reporter 之类人格角色再硬分任务。一个 workload 只有在拥有独立 TaskContract、domain state、completion predicate、capability/policy envelope，并且不需要复制父任务完整上下文时，才升级成独立 Agent Role。

### TaskIntent、TaskContract 与 TaskRun

用户请求、M1–M3 change event、background enrichment trigger、WATCH wake 和 M6 ContinuationRequest 先形成 `TaskIntent`。稳定 identifier / object / version / time 先由 deterministic parser 解析，模糊部分才交给 lightweight model。

```text
TaskIntent
  raw_request / trigger_ref
  parsed_identifiers[]
  candidate_task_kind
  candidate_targets[]
  temporal_expression
  requested_output
  requested_actions[]
  context_refs[]
```

`TaskIntent` 可以歧义，也不提供执行资格。deterministic normalization 与 `task_admission` 先产生真正可执行的 `TaskContract`；随后 RoleRegistry 选择 Role，ContextBinder 再基于 TaskContract、Role 和 intent 中已有 `context_refs[]` 生成 ContextManifest：

```text
TaskContract
  task_contract_id / contract_revision
  principal / on_behalf_of?
  task_kind
  target_resources[]
  desired_state
  evidence_contract
  output_contract
  temporal_contract
  effect_ceiling
  delegation_ceiling
  completion_predicate
  cancellation_semantics
  policy_revision
```

`requested_actions` 与 `desired_state` 描述意图，不代表 permission。`effect_ceiling` 与 `delegation_ceiling` 是 contract 上限；真正 invocation 仍要经过 PolicyDecision。

一次实际执行是 `TaskRun`。持续数小时/数天的是 Case；一次 VERIFY、一次 WATCH wake、一个 child enrichment 都是独立 TaskRun，terminal 后不会重新回到 running。

```text
TaskRun
  run_id
  task_contract_id
  case_id?
  parent_run_id?
  role_id / role_version
  context_manifest_ref
  status = submitted | queued | running | waiting_input | waiting_dependency
           | blocked | completed | failed | cancelled | timed_out
  base_context_revision
  execution_envelope_ref
  result_ref?
  stop_reason?
```

第一版 Task Domain 沿用 Requirements / 01–05 已出现的任务：lookup/retrieve、version/fix verify、conflict resolution、relation investigation、Incident investigation/watch、research/insight、normative applicability、live asset observation，以及 M3 `EnrichmentTask`。Task kind 可以继续细化，但必须能机械计算 completion predicate 和允许的 effect/delegation ceiling。

### Role 在 Task 之后确定

Role 是运行配置集合，不是 prompt persona：

```text
RoleProfile
  role_id / version
  accepts_task_kinds[]
  state_model
  planner_profile
  skill_scope[]
  seed_skill_refs[]
  mandatory_guard_refs[]
  capability_preferences[]
  default_execution_profile
  delegation_rules[]
```

v1 固定两个 canonical Agent workload：

| Role | 接受的 Task | 持有的 domain state | Completion | Delegation |
|---|---|---|---|---|
| `EnrichmentRole` | background/delegated `EnrichmentTask` | M3 `EnrichmentState` | required dimension 到 `resolved/conflict/unknown`；仍为 `missing` 且无可执行路径时 TaskRun 以 blocked/partial 终止 | 默认不委派 Investigation；可并行 child operator task |
| `InvestigationRole` | `VERIFY / INVESTIGATE / WATCH` | M4 `InvestigationState` | TaskContract desired state / evidence sufficiency / explicit blocked | 可委派 `EnrichmentTask` 和受控 child execution |

`skill_scope` 只定义该 Role 可检索的 Skill namespace；`seed_skill_refs` 是经过验证后默认可发现的 procedural prior；`mandatory_guard_refs` 保存不能被 Planner 绕过的调查 guard，但仍不替代 Policy enforcement。Role 不把这些 Skill 全量注入模型，实际 materialization 由后文 SkillResolver / ContextMaterializer 决定。`DIRECT / RETRIEVE` 默认仍是非 Agent fast path；Reporter/Researcher/Analyst 等保持 Skill / prompt specialization，除非以后证明它们具有独立 state machine 与 completion semantics。

### Reference-preserving Context Handoff

Agent 之间默认传引用和 revision，不传一段“总结完的上下文”作为事实来源。逻辑 context 与 prompt/KV cache 分离：

```text
ContextManifest
  context_id / context_revision
  parent_context_id?
  task_contract_ref
  role_ref
  case_ref?
  knowledge_revision
  investigation_state_ref?
  enrichment_state_refs[]
  evidence_refs[]
  object_refs[] / relation_refs[]
  trajectory_checkpoint_ref?
  skill_selection_refs[] / experience_pattern_refs[]
  policy_context_ref
  capability_envelope_ref
  budget_ref
  cache_hint?
```

支持 `inherit / filter / pin / refresh / diff / fork / merge`。Child Task 从 parent manifest 派生最小 scope；返回 `based_on_context_revision`，State/Knowledge Gate 判断 `valid / rebase_required / stale / conflict`。`cache_hint` 只是性能提示，可以将来映射到 prefix/KV cache handle；它没有事实或权限权威。

运行时 prompt 由 ContextMaterializer 按 Task/Role/当前 revision 物化。summary 可以作为 UI/模型压缩产物，但不能替代 EvidenceRef、StateRef、ArtifactRef 或 SnapshotRef。

### 异步 multi-loop 与 duplex Event Plane

Multi-Agent 在本设计中定义为：多个 independently bounded TaskRun，拥有各自 TaskContract / state scope / capability-policy envelope，通过 typed task/event/result 与共享 durable world 协作。它不等于多个 persona 互相聊天。

内部 v1 event contract：

```text
TaskEvent
  event_id
  task_run_id / parent_run_id?
  seq
  event_type
  producer
  base_context_revision
  payload_ref
  idempotency_key
  emitted_at
```

事件闭集至少包含：

```text
TaskCreated / TaskStarted / TaskPatched / ContextUpdated
EvidenceFound / KnowledgeChanged / EnrichmentStateChanged / InvestigationStateChanged
TaskBlocked / NeedInput / NeedContext / BudgetWarning
ArtifactProduced / Progress / TaskCompleted / TaskFailed / TaskCanceled
```

Parent→Child 可以 patch priority/context/budget、cancel、resume 或更新 policy context；Child→Parent 可以发布 progress、blocked、NeedContext、Knowledge/State change 和 typed TaskResult。每个 TaskRun 有自己的 Agent Loop；Task/Event/State Projection loop 相互独立，事件本身不会自动触发模型。

TaskEvent 先写 PostgreSQL append-only event log，再由 outbox 投递到独立逻辑 `redis_task_bus_url` 的 Redis Streams。每个 TaskRun 使用单调 `seq` 保证 task-local ordering；consumer 通过 event_id/idempotency key 去重并可从 durable event log 重放。Celery broker 不承担 pub/sub 语义，Hot Cache Redis 不与 Task Event Plane 混用。

外部 interoperability 通过 A2A Adapter：TaskRun lifecycle 映射 A2A Task，TaskResult/ArtifactRef 映射 Artifact，progress/state 事件映射 streaming/push update；`TaskContract`、`ContextManifest`、Capability/Policy refs 通过 extension/data part 暴露。内部 runtime 不把 A2A Message/Context ID 当 Context Store；标准 SSE/push 或 custom WebSocket binding 都只负责 transport/interoperability，不改变内部 Task/Event/Context contract。

### Task delegation 与 Multi-Agent

v1 已确认存在一个值得实现而不是继续等待 benchmark 才决定的 canonical multi-agent workload：**EnrichmentRole + InvestigationRole**。两者共享 Task Runtime / Event Plane / Capability-Policy Control Plane，但拥有不同 domain state 和 completion predicate。

```text
Investigation TaskRun
  -> identifies task-relevant enrichment gap
  -> delegates EnrichmentTask
     -> Enrichment Role reads EnrichmentState / operators
     -> Evidence/Knowledge write gate
     -> emits EnrichmentStateChanged / TaskResult
  -> parent relevance gate refreshes Percept / InvestigationState
```

Multi-Agent 的 unit 是 independently bounded TaskRun，不是 persona。多个 EnrichmentTask 可以并行使用同一个 EnrichmentRole runtime；是否新增第三种 Role 要满足：独立 TaskContract、独立 state model、独立 completion semantics、独立 capability/policy profile，并能通过 ContextManifest 而不是父 task 全量 transcript 工作。

Delegation contract 固定 parent-child ceiling：child effect/delegation/capability/budget/deadline 都不能超过 parent grant；child credential scope 更窄。peer/child message 与 TaskResult 始终携带 sender、task_run_id、context revision、provenance；“来自内部 Agent”不增加事实或 instruction authority。

跨 Agent handoff 优先传 `ContextManifest + typed TaskResult + Artifact/Evidence/State refs`。自然语言 summary 只用于模型消费/人类可读，不承担 durable state transfer。Child 基于旧 revision 返回结果时，parent State Gate 必须执行 valid/rebase/stale/conflict 判断。

### ExecutionProfile

Role 决定 domain loop，`ExecutionProfile` 决定单个 TaskRun 的运行强度。第一版仍固定五种 profile：

| Profile | Agent loop | 默认能力 | Loop | 典型终态 |
|---|---:|---|---|---|
| `DIRECT` | no | exact/structured/current projection | none | answered / not_found |
| `RETRIEVE` | no；允许一次 synthesis | lexical+dense+metadata+known graph | none | answered / escalate |
| `VERIFY` | bounded | graph + evidence zoom + primary + optional sandbox | short loop | verified/conflict/blocked |
| `INVESTIGATE` | bounded | read perception + delegated enrichment + policy-gated external/sandbox | bounded loop | success/partial/wait/fail |
| `WATCH` | short episode per wake | delta/refresh/follow-up | wake→episode→sleep | waiting/escalated/resolved |

普通 QA `≤5s` 由 DIRECT/RETRIEVE 负责。profile escalation 创建新的 TaskRun/ExecutionEnvelope，重新计算 capability visibility、budget 和 policy；不能通过升级偷偷继承更高权限。

## M4 调查状态

M4 对外提供两种 context 形态：DIRECT/RETRIEVE fast path 使用由 `ContextManifest + Evidence World` 物化的只读 `ContextView`；需要写入未知项、冲突、EvidenceNeed、WATCH 或跨 TaskRun 连续性时才建立 durable Case，并采用 append-only `CaseStateEvent` + 物化 `InvestigationState`。两种形态通过同一 ContextBinding/State read interface 提供给 M6。

### Case 类型与生命周期

Case 是跨 TaskRun 的调查容器，不承载一次执行的 terminal 状态。只有需要持续 InvestigationState、EvidenceNeed、WATCH 或多次追问复用时才物化 Case；`DIRECT / RETRIEVE` 默认只建立 TaskRun + ContextManifest，升级为 VERIFY/INVESTIGATE 或需要持久上下文时再绑定/创建 Case。

```text
Case: created -> active <-> waiting -> resolved -> closed
                              \-> cancelled

TaskRun: submitted -> queued -> running
                    -> waiting_input / waiting_dependency
                    -> completed / failed / cancelled / timed_out / blocked
```

持续型 Case 面向 Incident、patch/advisory 等随世界变化的问题，可以持续数小时或数天；模型进程不常驻。每次 wake 创建新的 TaskRun，旧 TaskRun 保持 terminal immutable。Case 复用依据 target、TaskContract signature、time scope、world/context revision 与 freshness；current/live task 不复用已经过期的 ContextManifest。

### InvestigationState

```text
InvestigationState
  case_id / case_revision
  goal
  targets[]
  confirmed[]
  tentative[]
  conflicts[]
  unknowns[]
  hypotheses[]
  open_questions[]
  decision_variables[]
  evidence_needs[]
  active_skills[]
  normative_context_refs[]
  unresolved_applicability[]
  current_decision?
  last_world_revision
  last_perception_at
```

以“vLLM 0.21.0 是否仍受影响”为例，状态可以同时保存 GHSA affected range、OSV candidate fix commit、commit→PR tentative relation，以及“哪个 release 首次包含该 commit”这个未知项。Agent 每轮读取并修改这些显式状态，不需要重新解释全部历史 token。

规范任务通过 `normative_context_refs` 引用 M3 已结构化的 Requirement / Control 与显式 applicability conditions。M4 保存当前 Case 的 contextual applicability；`not_evaluated / uncertain` 进入 `unresolved_applicability` 并生成 EvidenceNeed，`applicable / not_applicable` 必须保留支撑它的系统事实和规则版本。M4 不把法规原文编译成执行限制，Execution Control Plane 只消费 03 中已经批准的 RuntimePolicy。

### M3 EnrichmentState 到 M4 EvidenceNeed

M3 background enrichment 与 M5 active investigation 使用同一 Evidence/Knowledge World，但状态 ownership 不混合。M3 持有 Requirements 已冻结的 four-state `EnrichmentState`：canonical dimension 只能是 `resolved / conflict / unknown / missing`。M4 不再定义平行的 `EnrichmentRequirement` 协议；它只把与当前 TaskContract desired state 有关的 `missing / conflict / unknown` 状态投影成 Case-local EvidenceNeed。M3 内部 planner 可以拥有自己的 processing/enrichment requirement，但它不是 M3→M4 handoff contract。运行受阻单独记录在 EnrichmentTask/attempt execution state，不扩展 semantic status。

```text
M3 EnrichmentState
  -> task-relevant gap
  -> M4 EvidenceNeed
  -> InvestigationRole / delegated EnrichmentTask
  -> EphemeralObservation
  -> AcquisitionService / EvidenceIngress
  -> M3 processor / Knowledge write gate
  -> EnrichmentStateChanged
  -> M4 refresh / resolve EvidenceNeed
```

`missing` 表示当前 canonical dimension 尚无足以落到 resolved/conflict/unknown 的证据；`unknown` 表示相应 evaluator/authority lookup 已执行且证据明确只能支持 unknown。source/policy/credential/budget 阻止执行时，dimension 仍保持 `missing`，同时 TaskRun/attempt 记录 `blocked_reason` 和剩余 eligible path。M4 不因为一个 Vulnerability 有多个 missing dimension 就自动启动多个 Agent Task；TaskContract 决定哪些 gap 与当前目标有关。

### EvidenceNeed

`EvidenceNeed` 是 Case 内“当前 Task 仍缺什么证据”的一等状态，由 M4 创建和维护；M5/InvestigationRole 负责解决，Perception Runtime 和 delegated EnrichmentTask 用它选择能力与来源，M7 评价该缺口是否被正确识别和关闭。

```text
EvidenceNeed
  need_id / case_id
  derived_from_enrichment_requirement?
  proposition_or_question
  purpose
  target_objects[]
  evidence_contract
  preferred_source_roles[]
  rejected_evidence_patterns[]
  freshness_requirement
  completion_predicate
  priority
  status = open | resolved | blocked | abandoned
  resolution_evidence_refs[]
```

例如验证“哪个 release 首次包含 fix commit abc123”，EvidenceNeed 可以接受 tag ancestry、GitHub compare 或 package changelog；`PR merged_at` 单独列入 rejected pattern，因为 merge 时间不能证明 release containment。

### 状态事件与并发

每次状态变化都写 `CaseStateEvent`：

```text
CaseStateEvent
  event_id
  case_id
  base_case_revision
  event_type
    fact_confirmed | fact_retracted
    tentative_added | tentative_removed
    conflict_opened | conflict_resolved
    unknown_opened | unknown_resolved
    hypothesis_added | hypothesis_rejected
    evidence_need_opened | evidence_need_resolved
    evidence_attached | decision_changed
  proposition / target_ref
  evidence_refs[]
  writer
  reason_code
  created_at
```

写入使用乐观并发控制。多个异步任务同时返回时，可交换事件基于最新版本重新物化；两个写入方对同一命题提出互斥状态时，不采用后写覆盖，直接形成冲突或交给 State Integration Gate 裁定。M4 当前状态可以从事件重建，审计与历史重放不依赖聊天记录。

### StatePatch 与写入门禁

模型和 Perception Runtime 只能提出 `StatePatch`，不能直接修改 InvestigationState：

```text
StatePatch
  patch_id
  case_id
  base_case_revision
  operations[]
    proposition
    proposed_state
    evidence_refs[]
    reasoning_relation?
    resolves_need_id?
  producer
  model_prompt_revision?
```

State Integration Gate 检查对象身份、EvidenceRef、来源 / 版本 / 时间一致性、权威要求、关系属于 deterministic 还是 inferred、当前是否存在冲突、基准版本是否仍有效，以及写入策略是否允许。

例如“release v0.22.0 包含 commit abc123”必须携带 commit / release EvidenceRef 和 `release_contains_commit` 关系依据；只有 `PR merged_at` 时保持 tentative 或继续打开 EvidenceNeed。无法回到 M2/M3 EvidenceRef 的外部观测不能写为已确认。

M3 的 `semantic candidate -> evidence/write gate -> Knowledge` 与 M4 的 `StatePatch -> State Integration Gate -> InvestigationState` 保持同一种 ownership：模型提出语义候选，确定性运行时持有事实状态写权限。

### 世界变化与状态失效

已确认事实仍受世界版本约束。`KnowledgeChange`、`incident.changed`、来源版本或索引版本变化如果触及 Case 已使用的证据 / 对象，State Runtime 按依赖关系处理：

- 只影响展示的变化更新当前投影；
- 改变事实支持的变化把相关命题标记为过期，并重新打开 EvidenceNeed；
- 出现相反证据时打开冲突；
- 处于 `waiting` 的 Case 可以直接把这类变化事件作为唤醒条件。

旧回答仍然可以按历史 Snapshot 重放；当前查询则读取新世界版本后的状态。这使普通问答与持续跟踪使用同一套事实生命周期。

### InvestigationSnapshot

每次 episode 开始、重大状态提交和最终 Decision 都可以保存 Snapshot 指针：

```text
InvestigationSnapshot
  snapshot_id / case_id / case_revision
  knowledge_revision
  incident_revision
  document_index_revision
  experience_revision
  policy_revision
  capability_registry_revision
  routing_query_planner_revision
  model_revision
  prompt_assembly_revision
  source_availability_snapshot
  created_at
```

Snapshot 保存版本 / 指针，不复制整个证据世界。M7 按这些版本恢复某个历史时点当时已经发布、已经采集并且能够访问的证据，避免用后来出现的 patch 或事后复盘回答过去任务。

## 查询构造与 Perception Runtime

M4 已经明确当前 Case 的 InvestigationState / EvidenceNeed 后，查询与感知层才决定“读什么、从哪里读、读到什么粒度”。物理 retrieval operator 只读取 M1–M3 Evidence World；Perception Planner 根据 Task/EvidenceNeed 组合这些 operator、受控 external observation 与 progressive zoom，最后产生供 M5 使用的 `Percept`。这一层没有 Knowledge 写权限。

### 四级查询构造

**L0 原样查询** 用于本身已经适合检索的短语、主题和自然语言问题，例如 `RAG poisoning defenses`。原字符串直接进入词法检索 / 向量检索或提供方原生全文检索；这里不先让模型“优化关键词”，避免删除安全标识、函数名、版本号或用户使用的领域术语。

**L1 确定性规范化** 解析稳定标识、版本、时间和谓词。例如“CVE-X 对 vLLM 0.11.0 有影响吗”先得到漏洞对象、软件包 / 版本以及 `affected / fixed` 两个结构化子问题，再生成精确查询、结构化查询或关系图查询。该路径不启动 Agent。

**L2 语义查询构造** 处理比较、复合条件、跨来源说明和开放文本任务。例如“这次 Bitget 事件与最近几个相似事件在攻击入口和资金处置上有什么共性”，模型需要输出目标事件、时间范围、比较维度、所需证据类型和候选子问题，再由查询规划器编译成多个查询。

L2 的模型输出受 `QueryIntent` schema 约束：

```text
QueryIntent
  original_text
  targets[]
  requested_predicates[]
  comparison_dimensions[]
  time_scope
  evidence_requirements[]
  candidate_subquestions[]
  query_revision
```

**L3 调查规划** 从当前 `InvestigationState` 产生 `EvidenceNeed` 和 `PerceptionRequest`，回答“现在缺什么证据、下一步应该观察什么”。L3 属于 M5 调查循环，不参与普通查询改写。

查询升级顺序固定为：先绑定对象和时间；再尝试精确 / 结构化读取；需要文档发现或语义近邻时使用词法 / 稠密向量检索；需要对象关系时使用关系图；仍存在未解决命题时创建 `EvidenceNeed`。只有进入 L3 调查规划后才启动 Agent 调查循环。

### 物理检索路由

查询规划器与感知规划器共享底层读取能力，但职责不同：查询规划器服务一次查询构造；感知规划器服务一个 `EvidenceNeed`。物理路由采用当前数据结构能够表达的最窄操作，减少无意义的向量检索和外部调用。

| 操作 | 适用对象 | 当前实现 / 接口 |
|---|---|---|
| `exact` | CVE/GHSA/DOI/SHA/version/IP/domain/address | PostgreSQL index / 提供方精确查询 API |
| `structured` | 当前视图、元数据、version range、Incident 状态 | PostgreSQL 查询 |
| `lexical` | 函数名、端点、软件包、IOC、技术术语、长文正文 | PostgreSQL FTS |
| `dense` | 机制相似、研究主题、语义相关文档 | pgvector 检索接口 |
| `graph` | issue–PR–commit–发布版本、依赖、risk/控制、证据关系 | 关系存储 / 递归遍历 |
| `evidence` | Claim/Relation→EvidenceRef→locator→artifact | 证据读取接口 |
| `external` | 最新提供方状态、互联网资产、缺失的 primary / authority 证据 | AcquisitionService / 提供方适配器 |
| `sandbox` | git ancestry、仓库检查、受控分析程序 | Execution Sandbox |

选择顺序不是固定流水线。存在强 ID 时优先精确查询；已知对象的当前状态优先读取当前投影；需要关系链时优先走关系图；文档发现再使用词法检索 / 向量检索；本地世界无法满足时效性或权威要求时再访问外部提供方；需要执行代码或验证 repo 状态时进入沙箱。

### 候选集合装配

各检索器输出统一 `RetrievedCandidate`，保留对象 / 关系 / 证据 / 文档身份、来源角色、来源族、上游来源、版本、有效时间、locator、索引版本，以及精确查询 / 词法检索 / 向量检索 / 关系图 / 时效性等评分通道。检索分数只表示检索器的匹配信号，不代表证据权威。

```text
RetrievedCandidate
  candidate_id
  candidate_kind
  object_id / relation_id / evidence_ref / document_chunk_id
  source_id / source_role / source_family / upstream_source
  revision
  observed_at / valid_time
  score_channels
    exact / lexical / dense / graph / freshness
  locator
  index_version
  retrieval_run_id
```

M4/M5 按候选集合装配证据，不能把相关性排序后的 top-k 直接当成最终证据集。装配器同时检查任务覆盖、`primary / authority` 来源要求、来源独立性、候选互补性、时间版本匹配和同源转载。RRF、加权融合、cross-encoder 或 learned reranker 可以替换，但这些证据集合约束保持不变。

Research / Insight 检索还要做发表版本确认。会议整理、GitHub 导读和二次材料可以帮助发现论文；标题、作者、录用状态、版本和正文仍回到正式 proceedings、DOI、arXiv 或作者 / 机构页面确认。真正被调查、引用或进入评测的版本再按 `durable_managed` 固定。

### PerceptionRequest 与物理计划

Agent 不直接生成底层 BM25 查询或提供方端点，而是表达一个认知动作：

```text
PerceptionRequest
  request_id / case_id / need_id
  operation
  target
  desired_observation
  evidence_requirement
  time_scope
  current_context_refs[]
  budget_ref
```

第一版语义操作包括：

- `inspect`：读取对象当前投影；
- `expand`：展开指定关系邻域；
- `trace`：沿来源链、来源或依赖下钻；
- `zoom`：提高同一证据的读取粒度；
- `search`：发现未知对象或文档；
- `corroborate`：寻找独立支持；
- `contrast`：主动寻找反例或冲突来源；
- `refresh`：重新观察可能过期的对象；
- `observe_external`：获取本地证据世界中不存在的当前观测；
- `watch`：把 EvidenceNeed 转成未来唤醒条件。

感知规划器再把语义请求编译成物理计划。`trace(commit abc123 → containing release)` 可以依次尝试本地关系图、GitHub exact lookup、tag / release metadata；仍无法确认时申请 git 沙箱做祖先关系检查。每一步声明依赖、预期输出、能力要求、估计成本、停止条件和回退；下一轮可以根据上一轮 `Percept` 重新规划。

```text
PhysicalPerceptionPlan
  request_id
  steps[]
    operator
    input
    dependency
    expected_output_type
    capability_requirement
    estimated_cost
  stop_condition
  fallback_order
  planner_revision
```

### 逐级读取

同一事实按读取成本和细节程度分层。Agent 从低成本投影开始，只有出现冲突、未知项、过期风险或引用要求时才继续下钻。

| 层级 | 内容 | 主要用途 |
|---|---|---|
| L0 | 当前投影 | 常规查询、快速路径 |
| L1 | Claim / Relation / Incident 时间线状态 | 判断已有事实与关系 |
| L2 | EvidenceRef、snippet、候选来源 | 比较证据、选择引用 |
| L3 | 来源 section / page / JSON locator | 核对具体上下文 |
| L4 | 原始 Artifact / 完整来源版本 | 查看完整原文、复核解析 |
| L5 | 外部重新获取 / 实时观测 | 本地状态缺失或已经过期 |

M7 记录每次读取层级变化，用来区分“世界中没有证据”“Agent 选错证据”“读取粒度不足”“`Percept` 压缩丢失关键细节”。

### 临时观测与证据晋升

外部提供方、浏览器、沙箱、搜索结果和同伴 Agent 返回结果默认先成为 `EphemeralObservation`。它可以指导下一步动作、生成 hypothesis 或 EvidenceNeed，但不能直接支撑 M4 已确认 fact。

```text
EphemeralObservation
  observation_id
  request_id
  capability_id
  source / provenance
  observed_at
  raw_result_ref
  extracted_candidates[]
  trust_label
  ttl
```

```text
tool/provider output
  -> EphemeralObservation
  -> Percept
  -> discard / zoom / corroborate / promote
  -> promotion returns through AcquisitionService / EvidenceIngress
  -> fixed source revision + EvidenceRef
  -> StatePatch
```

当观测需要成为长期事实、回答引用、Case 已确认状态、评测证据或可复用关系时，它重新进入 Technical Design 1 已有的 Acquisition / EvidenceIngress / Knowledge 路径，固定来源版本并取得 EvidenceRef。临时观察与长期保存由此分开，工具输出不会直接污染 durable Knowledge 或 InvestigationState。

### `Percept` 装配

`Percept` 是这一轮 Agent 实际看到的结构化世界切片，不等同于 `list[RetrievedChunk]`。例如 `corroborate(fixed_release=0.22.0)` 可以在底层读取几十个候选项，最终 `Percept` 只保留独立支持、反驳、仍未解决的问题、时效性、证据句柄和成本。

```text
Percept
  percept_id / request_id
  target_refs[]
  observed_propositions[]
    statement
    support_refs[]
    refute_refs[]
    source_groups[]
    freshness
  relations[]
  timeline_slice[]
  unresolved[]
  candidate_evidence[]
  evidence_handles[]
  observation_handles[]
  cost
  assembler_revision
```

`Percept` 装配器必须保留 `source_family / upstream_source`，避免把同一上游转载计算成多源 corroboration；保留版本和有效时间，避免旧版本证据进入当前问题；显式保留 unresolved，避免模型把“未找到”改写成“不存在”。

### 跨文档语义关系

跨文档富化与调查允许 LLM 从论文、厂商报告、repo 和 Incident 证据中提出 `ClaimCandidate / RelationCandidate`。确定性层负责对象身份、来源归属、时间 / 版本语义、EvidenceRef 绑定以及重复 / 冲突检测；Agent 决定哪些候选值得继续验证；M4 决定验证结果如何改变当前 Case。候选在完成来源绑定和验证前不能进入已确认状态。

这条路径与 M3 的 semantic candidate 写入保持同样的责任划分：模型提出语义关系，确定性运行时负责把关系绑定到对象、来源和版本，状态层再判断它是否足以改变当前调查。

## Tool、Capability 与执行控制面

04 中的 Agent Security Control Plane 在这里成为可执行协议。Planner 操作的是语义 Capability，不直接操作 MCP/OpenAPI/CLI 的 native tool schema；ToolImplementation 描述“物理上有什么实现”，CapabilityContract 描述“这个动作在 SecFusion 语义里意味着什么”，CapabilityBinding 才把二者绑定。这样 provider、MCP server 或 SDK 变化不会静默改变 Agent 的动作语义和安全边界。

### ToolImplementation、CapabilityContract 与 Binding

`ToolImplementation` 是物理实现记录，可以来自 local function、retrieval operator、provider API、MCP tool、OpenAPI operation、CLI、browser/computer-use、sandbox program 或 child-task adapter：

```text
ToolImplementation
  tool_impl_id / implementation_revision
  implementation_kind
  native_name
  transport
  native_input_schema / native_output_schema
  server_identity? / server_origin?
  auth_class
  network_destinations[]
  execution_backend?
  health_ref
  native_schema_hash
  implementation_metadata
```

MCP/OpenAPI/tool annotations 只帮助 discovery，不能自动成为 trusted security semantics。Runtime 授权的稳定对象是版本化 `CapabilityContract`：

```text
CapabilityContract
  capability_id / contract_revision
  action
  applicable_resource_types[]
  canonical_input_schema / canonical_output_schema
  observation_semantics
  effect_semantics
  authority_semantics
  preconditions[] / postconditions[]
  idempotency
  reversibility / compensation?
  data_ingress_class / data_egress_class
  failure_semantics
  risk_class
```

一个 Capability 可以有多个 ToolImplementation；同一 ToolImplementation 也可以通过不同 Binding 提供多个受限 Capability。`CapabilityBinding` 固定 canonical semantics 到 native execution 的转换：

```text
CapabilityBinding
  binding_id / binding_revision
  capability_id / contract_revision
  tool_impl_id / implementation_revision
  canonical_to_native_args
  native_to_canonical_result
  resource_resolver
  effect_resolver
  authority_mapper
  execution_class
  credential_profile
  network_profile
  sandbox_profile
  health_requirement
  cost_class / latency_class
  fallback_rank
  native_schema_hash
```

Tool native schema/hash 或 server identity 变化导致 Binding stale；高影响变化触发重新验证或版本滚动，不能靠同名 tool 继续复用旧 CapabilityContract。执行类别仍固定为 trusted local read、proxied provider read、restricted process、OCI container、microVM、full VM/browser。Source authority 与 Tool permission 分离。

### CapabilityView 与渐进披露

`capability_visibility` 根据 TaskContract、Role、EvidenceNeed、object/source requirement、effect/delegation ceiling、Policy、budget、credential/provider health 和 sandbox requirement 先计算 `VisibleCapabilitySet`。模型不看到全量 catalog，更不看到 credential、server secret 或 native endpoint。

第一层只暴露轻量 `CapabilityCard`：

```text
CapabilityCard
  capability_id / contract_revision
  action
  purpose
  applicable_resource_types[]
  observation_semantics
  effect_semantics
  authority_semantics
  limitations[]
  risk_class
  cost_class / latency_class
```

Planner 选择 Capability 后，ContextMaterializer 才加载 `CapabilitySchemaView`：

```text
CapabilitySchemaView
  capability_id / contract_revision
  canonical_input_schema
  canonical_output_schema
  relevant_preconditions[]
  failure_semantics
  obligation_hints[]
```

ToolImplementation、Binding native schema、credential 和具体 network/sandbox grant 默认永不进入模型 prompt。Provider 403、rate limit、credential 缺失、health failure 或 budget exhaustion 会让 CapabilityCard 退出本轮可见集合；恢复后通过新 revision/view 重新出现。

### CapabilityRequest、InvocationPlan 与 CapabilityResult

Planner 产生 canonical `CapabilityRequest`，不能提交裸 tool call：

```text
CapabilityRequest
  request_id
  task_contract_id / task_run_id / case_id?
  principal
  capability_id / contract_revision
  action
  resource
  canonical_arguments
  intended_effect
  evidence_purpose
  execution_context
```

Broker 在模型选定 Capability 后解析 Resource/Effect、选择健康 Binding，并生成待授权的 `InvocationPlan`：

```text
InvocationPlan
  invocation_plan_id
  capability_request_ref
  binding_id / binding_revision
  resolved_resource
  resolved_effect
  canonical_arguments_digest
  native_arguments_ref
  execution_class
  credential_requirement
  network_requirement
  sandbox_requirement
  deadline_at
  budget_reservation_ref
```

`capability_visibility` 只决定模型能否考虑某个 Capability；具体 resource/arguments 解析后仍执行 `capability_invocation` PolicyDecision。permit 且 obligations 可满足后才产生 `CapabilityInvocation`，由 Identity/Network/Sandbox Broker派生最小 grant并执行 ToolImplementation：

```text
CapabilityInvocation
  invocation_id / invocation_plan_id
  policy_decision_ref
  credential_grant_ref?
  network_grant_ref?
  sandbox_instance_ref?
  started_at

CapabilityResult
  invocation_id
  status = succeeded | partial | failed | blocked | timed_out
  canonical_output_ref?
  raw_artifact_ref?
  effect_receipt_ref?
  observation_class
  provenance
  latency / cost
  failure_code / failure_detail?
```

`CapabilityResult` 没有事实权威。读取型结果先成为 EphemeralObservation，经过 Result/Data/Promotion Policy 后才能进入 EvidenceIngress/M3；side effect 还要经过 effect receipt / commit gate。Approved Tool 也不意味着 Trusted Output。

### PolicyRequest / PolicyDecision

03 的 RuntimePolicy 可以含 `allow/deny/require_review/require_log` 等 rule effect；PolicyCompiler 在具体 decision point 将它们编译成 authorization 与 obligation，避免把 `require_log` 当成授权结果。

```text
PolicyRequest
  decision_point
  principal
  action
  resource
  context
    task_contract_id / task_run_id
    via_agent?
    parent_execution_id?
    capability_id?
    arguments_digest?
    intended_effect?
    evidence_purpose?
    world_revision
    budget_state
```

```text
PolicyDecision
  authorization = permit | deny | indeterminate
  constraints[]
  obligations[]
  advice[]
  matched_policy_ids[]
  determining_policy_ids[]
  policy_revision
  expires_at?
```

`require_human_approval`、`require_audit_log`、`sandbox>=container`、network allowlist、credential scope、side-effect staging 都属于 obligation/constraint。authorization=permit 但 obligation 无法满足时 invocation 不执行。

v1 decision point 闭集：`task_admission / task_delegation / capability_visibility / capability_invocation / credential_issuance / network_egress / sandbox_selection / side_effect_commit / observation_promotion / state_patch_commit / child_execution / watch_resume`。authorization、capability、data/evidence、side-effect、sandbox/network、delegation、budget 可以共用 Policy IR，但 enforcement point 与输入对象保持不同。

三个运行时不变量落实为协议：

```text
Budget != Permission
Source Authority != Tool Permission
Approved Tool != Trusted Output
```

### Sandbox runtime 选型与配置

v1 不再把 sandbox substrate 留到主实现后期才决定。选型固定为：

- `process_restricted / container_standard`：**OpenShell** 作为 sandbox supervisor/enforcement runtime；OCI workload 使用 Docker 或 Podman backend。SecFusion PolicyEngine 负责 task/action/resource authorization，SandboxBroker 把已批准的 filesystem/network/credential obligation 编译为 OpenShell policy；OpenShell 不决定业务 Task 是否获准。默认 non-root、drop capabilities、`no_new_privs`、受控 filesystem、default-deny network，credential 由 supervisor/gateway 按 destination 注入，Agent 不读取真实 secret。
- `microvm_untrusted`：**Firecracker** 作为高风险 arbitrary-code / untrusted repo / PoC fixture profile。该 profile 需要 KVM/host support；不可用时 task 进入 `sandbox_unavailable` / human review，不允许自动降级成普通 container。
- `fullvm_browser`：保留接口，不作为 v1 必须实现的 substrate；browser/computer-use 在进入该 profile 前另做 probe。
- DSec 作为多 backend / lifecycle / image / elastic scheduling 的 architecture reference，不作为当前仓库的硬 runtime dependency。

SandboxBroker 对上层只暴露 `SandboxProfile`：

```text
SandboxProfile
  profile_id / revision
  isolation_class
    none | process_restricted | container_standard
    | microvm_untrusted | fullvm_browser
  backend
  image_ref_or_digest
  run_as_uid_gid
  cpu_limit / memory_limit / pids_limit
  wall_timeout
  rootfs = read_only | overlay
  writable_paths[]
  readonly_mounts[]
  seccomp_profile
  landlock_profile
  linux_capabilities[]
  no_new_privs
  network_mode = deny | allowlist | proxied
  allowed_destinations[]
  credential_injection = none | gateway
  artifact_export_policy
  teardown_policy
```

初始部署 config 使用独立配置块，不把数值写进 Requirements：

```yaml
sandbox:
  provider: openshell
  container_runtime: docker   # podman allowed
  default_profile: container_standard
  profiles:
    process_restricted:
      network: deny
      rootfs: read_only
    container_standard:
      network: proxied
      rootfs: read_only
      writable_paths: [/workspace, /tmp]
      capabilities: []
      no_new_privs: true
    microvm_untrusted:
      backend: firecracker
      require_hardware_virtualization: true
      fallback: deny
```

镜像必须 pin digest；workspace/Artifact 导入保持 untrusted label；Docker socket、host credential store、host network、arbitrary host mount 永不进入 Agent namespace。Sandbox config revision 进入 ExecutionEnvelope、Trajectory 与 M7 replay。

### ExecutionEnvelope 与预算传播

每个 Agent episode、Perception 动作、RPC 和子执行都运行在 `ExecutionEnvelope` 内：

```text
ExecutionEnvelope
  execution_id / parent_execution_id
  task_contract_id / task_run_id
  case_id?
  role_revision
  context_manifest_revision
  execution_profile
  capability_scope
  deadline_at
  budget_ref
  policy_revision
  identity_scope
  network_policy
  side_effect_policy
  sandbox_profile_revision
  trace_context
```

`deadline_at` 使用绝对时间。子调用的 timeout 取自身上限和 parent remaining time 的较小值；重试、提供方回退、沙箱 step 或 subagent 都不能重新获得完整根预算。这样才能保证“每个 RPC 都有 timeout”最终组合成“整个 operation 有界”。

预算以 TaskRun 为基本执行账户；persistent Case 可以额外持有跨多次 wake 的 aggregate CaseBudget，但没有 Case 的 DIRECT/RETRIEVE/EnrichmentTask 不依赖它：

```text
CaseBudget?                 # optional aggregate for persistent Case
  -> TaskRunBudget
     -> ActionBudget
        -> RPCAttemptBudget

Parent TaskRunBudget
  -> Child TaskRunBudget    # delegation reserve
```

第一版资源维度包括 wall time、model tokens、agent turns、tool calls、RPC calls、retries、external cost、bytes read、concurrency 和 recursion depth。每个 TaskRun 创建时获得明确 budget account；并发或 child TaskRun 启动前从 parent TaskRun/Case aggregate `reserve`，实际发生后 `commit`，未消耗的可分配额度 `release`。已经消耗的 wall time、provider token/cost 和 RPC 不返还；所有 child reserve 总和不能超过 parent remaining budget。

`budget_exhausted` 是正常的 domain outcome。运行时保留已经确认的事实，把未解决 EvidenceNeed 标记为阻塞 / 部分结果，并停止继续感知；M6 可以基于当前状态说明哪些结论已经验证、哪些验证因预算终止。

## Skill 与 Experience Runtime

Skill 保存可复用的调查 procedure，Capability 保存可执行动作的语义 contract，Experience 保存历史执行中与条件绑定的成功、失败和回退模式。Skill/Experience 都只影响“下一步怎样调查”；它们没有事实权威，也不能替代 Policy。Skill Runtime 的主要约束是 progressive disclosure：Role 可以拥有较大的 Skill scope，但每轮模型只看到当前任务相关的轻量 manifest，选择后再逐级加载 procedure、当前 step 和 provenance。

### Skill 对象与预埋

Skill 拆成四类对象，避免把 applicability、procedure、历史轨迹和整段 prompt 塞进一个大文档：

```text
SkillManifest
  skill_id / version
  status = candidate | validated | active | superseded | deprecated
  source_type = seeded | experience_derived | imported
  task_patterns[]
  evidence_need_patterns[]
  applicable_object_types[]
  applicability_conditions[]
  required_inputs[]
  required_capability_classes[]
  optional_capability_classes[]
  expected_outcomes[]
  risk_hint / cost_hint
  procedure_ref
  provenance_ref
  validation_ref
  supersedes?

SkillProcedure
  skill_id / version
  steps[]
  evidence_expectations[]
  failure_guards[]
  fallbacks[]
  stop_conditions[]
  budget_profile?

SkillStepFragment
  skill_id / version / step_id
  semantic_instruction
  required_state_refs[]
  required_capability_classes[]
  success_predicate
  failure_predicate
  fallback_refs[]

SkillProvenance
  origin
  supporting_trajectory_refs[]
  supporting_experience_pattern_refs[]
  validation_case_refs[]
  promotion_history[]
```

`procedure` 只写语义步骤，例如“检查 fix commit”“追踪包含该 commit 的 release”，不写 REST endpoint、MCP tool name 或 CLI；物理执行由 Capability Binding 决定。第一批 seed Skill 来自当前已经反复验证的调查规则：`VerifyFixBoundary`、`ResolveSourceConflict`、`TraceIncidentEvidence`、`AssessAffectedDeployment`、`AssessApplicability`。已经证明稳定的失败知识优先预埋成 guard，例如 `PR merged_at` 不能证明 release containment、公开 PoC 不能证明 known exploitation、absence 不能推出 `not_affected`、shared CDN edge observation 不能推出 asset ownership。预埋只提供 procedural prior；Skill 在进入 `active` 前仍要经过 conformance/replay validation。

### Skill 发现与渐进披露

`SkillResolver` 的输入是 TaskContract、RoleProfile 的 `skill_scope`、当前 EvidenceNeed / InvestigationState signature、可见 Capability class 和预算。它先检索 `SkillManifest`，不会把 Skill library 全量展开：

```text
Task / Role / EvidenceNeed / State
  -> manifest retrieval
  -> SkillCard shortlist
  -> selected SkillProcedure
  -> current SkillStepFragment
  -> Provenance only on failure / ambiguity / eval / debug
```

模型的 disclosure level 固定为四级：`manifest` 只暴露用途、适用条件、预期结果、风险/成本和所需 capability class；`procedure` 在 Planner 选择某 Skill 后加载；`step` 只注入当前需要执行的局部指令、evidence expectation、guard 和 fallback；`provenance` 默认不进在线 prompt。`mandatory_guard_refs` 可以让 guard 在 procedure 未完整加载时仍进入 ContextMaterializer，但 guard 只有规划约束语义，真实权限继续由 Policy / Capability / State Gate enforcement。

```text
SkillSelection
  selection_id
  task_run_id
  candidate_skill_refs[]
  selected_skill_ref?
  disclosure_level
  selection_reason
  state_signature
  capability_view_revision
```

Skill version、materialization level、selection reason 和 content hash 全部进入 PromptAssembly / Trajectory。这样后续可以区分“Planner 没选对 Skill”“Skill procedure 本身有缺陷”“正确 Skill 因 Capability/Policy 不可用而失败”。

### Experience 压缩与 Skill 演化

Trajectory 是原始执行记录，不能直接当 Skill。Experience pipeline 保存条件和结果的结构，不把多条轨迹简单总结成一段自然语言：

```text
Trajectory
  -> ExperienceCandidate
  -> condition/action/outcome normalization
  -> ExperiencePattern
  -> SkillPatchCandidate | SkillCandidate
  -> M7 replay / regression
  -> validated / active SkillVersion
```

```text
ExperienceCandidate
  task_signature
  state_signature
  evidence_need_signature
  action_sequence[]
  capability_refs[]
  observed_outcomes[]
  failure_points[]
  fallback_taken[]
  stop_reason
  trajectory_ref

ExperiencePattern
  pattern_id / version
  condition_signature
  reusable_procedure_fragment?
  failure_guard_candidate?
  fallback_candidate?
  stop_condition_candidate?
  capability_preference_candidate?
  support_refs[]
  counterexample_refs[]
```

多条 Experience 可以压缩为新的 procedure，也可以只 patch 现有 Skill 的 failure guard、fallback、stop condition 或 capability preference。模型可以提出 `SkillCandidate / SkillPatchCandidate`，不能自行把它写成 active Skill；晋级由 M7 在固定 world/model/task/budget 下做 replay、跨 Case validation 和 regression。具体聚类算法、最小支持数量、promotion threshold 与自动/人工审批比例留给实现和 eval 决定，不在 TD2 预设数值。

TD1 已定义的 Experience Store 继续保存 versioned investigation memory、适用条件、推荐动作与 outcome；本节没有废弃该层。`ExperienceCandidate / ExperiencePattern` 是对 Trajectory/Experience 做结构化抽取与压缩时使用的中间表示，`Skill` 则是经过更严格 replay/regression 后可被 Runtime 渐进披露和执行复用的 procedural layer。一个 active Experience 可以直接影响 Skill retrieval/ranking，也可以长期停留为 planning prior，而不必强制晋级成 Skill。

Experience retrieval 只提供 procedural prior。当前 Case 的事实、来源权威和证据关系始终重新从 Evidence World / Perception 获取；历史成功轨迹不能作为当前事实证据。

## Runtime Context Materialization

`ContextManifest` 是可持久、可继承的逻辑上下文；本节只定义某个 TaskRun/step 怎样把其中的引用、Skill 和 Capability 物化成模型输入。ContextMaterializer 不能扩大 Task/Policy 权限，也不能把 summary、Skill 或 Tool 描述升级成事实来源。

### Prompt 分层

从稳定到动态依次装配：平台 invariant；TaskContract / Role / ExecutionProfile；编译后的 policy context；当前选中的 Skill disclosure；当前 Capability disclosure；InvestigationState / EvidenceNeed / Percept；最后是当前 step/goal 和刚产生的 EphemeralObservation。policy context 只帮助模型理解约束，具体 invocation authorization 仍在执行时重新计算。

```text
MaterializedFragment
  fragment_id
  kind
  source_ref / source_revision
  disclosure_level?
  selection_reason?
  trust_class
  cache_class = static | task_stable | state_dynamic | ephemeral
  content_hash
```

低层外部内容、Skill text、Tool description 和 peer Agent message 都不能覆盖高层 invariant。自由文本“后写覆盖”不属于上下文合并语义；每个 fragment 都保留 source/revision/hash。

### Skill / Capability 渐进披露

默认 prompt 只携带少量 SkillManifest/CapabilityCard。Planner 选择 Skill 后再加载 SkillProcedure，执行到具体 step 时只注入 SkillStepFragment；Planner 选择 Capability 后再加载 CapabilitySchemaView。SkillProvenance、ToolImplementation native schema、Binding、credential 和 network/sandbox grant 默认不进入模型上下文。

这套 disclosure 同时控制 token 成本和攻击面：大型 MCP server 的数百个 native tools 不会展开成 prompt；Experience library 也不会把历史 trajectory 全量塞给模型。Selection 失败、当前 step 失败、M7 replay/debug 才允许向下加载 provenance 或更完整的实现诊断信息。

### PromptAssembly 与 cache 分区

```text
PromptAssembly
  assembly_id
  execution_id
  task_contract_id / task_run_id
  role_revision
  context_manifest_revision
  platform_invariant_revision
  execution_profile_revision
  policy_context_revision
  materialized_skill_refs[]
  materialized_capability_view_refs[]
  state_projection_revision
  percept_refs[]
  materialized_fragment_refs[]
  materialized_ref_set_digest
  ordered_fragment_ids[]
  cache_handle_hints[]
  assembly_hash
```

`static` fragment 适合 platform/Role immutable prefix；`task_stable` 可以覆盖 TaskContract、选定 Skill manifest/procedure 和稳定 CapabilityCard；`state_dynamic` 放 InvestigationState、EvidenceNeed、Percept；`ephemeral` 放当前 observation/tool result。`cache_handle_hints` 以后可以映射 prefix/KV cache，但 cache hit/miss 只影响性能，不能决定 Context revision、事实新鲜度或 permission。

模型看到的 prompt 约束只承担 instruction；真实边界继续由 TaskContract、Capability/Policy、Network/Sandbox 与 State/Knowledge Gate enforcement。提示词写“禁止联网”不能替代 Network Gateway。

## M5 调查运行时

M5 只处理需要主动调查的 `VERIFY / INVESTIGATE / WATCH`。一次执行轮次是可恢复的有界状态机：它读取当前 Case 和 Snapshot，选择要解决的 EvidenceNeed，检索适用 Skill / Experience，计算当前可用能力，发起感知，写回状态，再根据状态变化决定继续、等待或停止。模型可以改变调查路径，但每一步都必须落在显式状态、能力和预算之内。

### 单次执行轮次

InvestigationRole 的单轮执行固定为下面的协议链；Planner 只决定“下一步想做什么”，真实动作必须绑定 CapabilityRequest 并经过 invocation policy。

```text
TaskContract + ContextManifest + InvestigationState
  -> select task-relevant EvidenceNeed
  -> resolve SkillManifest shortlist / selected SkillProcedure or StepFragment
  -> compute policy-filtered CapabilityCard set
  -> Planner proposes PerceptionRequest / CapabilityRequest / delegate / wait / stop
  -> compile PhysicalPerceptionPlan when perception is needed
  -> load selected CapabilitySchemaView
  -> resolve CapabilityBinding / InvocationPlan / Resource / Effect
  -> invocation PolicyRequest
  -> PolicyDecision + obligations
  -> reserve budget / derive credential / network / sandbox grant
  -> execute CapabilityInvocation or child TaskRun
  -> CapabilityResult / EphemeralObservation / TaskEvent
  -> result & promotion policy
  -> Percept
  -> optional M2/M3 Evidence/Knowledge promotion
  -> propose StatePatch
  -> State Integration Gate
  -> evaluate TaskContract completion predicate
```

EvidenceNeed 选择先看 TaskContract desired state 和优先级，再看是否存在能够满足 evidence contract 的当前 capability。需要 `primary` 来源的缺口，在只有 secondary source 时保持 open/blocked，不能伪装成 resolved。Planner 可以处理其他 need、委派 EnrichmentTask，或者进入 `waiting_dependency / waiting_for_world_update`。

SkillResolver 先发现轻量 manifest，只有被选择的 procedure/current step 才进入本轮上下文；Capability visibility 同样先暴露 Card，再为选中的动作加载 SchemaView。Capability Binding/Policy 决定物理实现和真实动作能否发生。偏离 Skill、delegation、policy decision、Context revision 和 child TaskResult 全部进入 Trajectory，M7 才能区分合理适配、Skill 缺口、Planner 错误和协议错误。

TrajectoryEvent 至少保存 `task_run_id / parent_run_id / base_context_revision / state_before_after / evidence_need / skill / perception / capability_request / policy_decision / child_task_ref / observation / state_patch / budget / latency / stop_reason`；大输出只保存 ArtifactRef。

### 有界循环

2026-10-12 实际任务复盘：一份二次文献的 INSPECT 已取得有引用的段落，但其 `reference` 来源角色不能满足 EvidenceNeed 要求的 `primary_source`。原执行把“记录该文献所说的内容”和“关闭整个缺口”放在同一批 StatePatch；关闭校验失败使整批局部发现回滚，随后模型重试至 `no_progress`。运行时现将这种**仅关闭条件失败**的批次拆为仍经 State Gate 校验的局部发现写入，保留 EvidenceNeed 为 open，并记录延期关闭的 TaskEvent。重复尝试关闭同一缺口以 `evidence_contract_unmet` 停止，重复提交非法状态以 `state_patch_rejected` 停止，使结果与缺口原因可区分。其他非法 StatePatch 仍拒绝。文档 INSPECT 每页最多八个 chunk，Percept 指出下一 offset；后续页面或定向 SEARCH 由 Planner 选择。`PerceptionEvent` 是本地读取的真实执行记录，不应被只展示外部 `CapabilityInvocation` 的前端误报为“没有工具调用”。这不把二次文献升级为原始来源，也不表示外部通用 Capability 已完成接入。

2026-10-12 外部取证增量：除已有 NVD CVE 读取外，InvestigationRole 现在注册 `source.read_registered_document@1`。任务只可对自身 TaskContract 中的对象，指定一个配置内公开且角色为 primary/authority/forensic 的 HTML 来源，读取该来源域名下的 URL 或先按标题从有界索引发现再读取。Capability Registry/Policy/Broker/Budget 记录授权和调用；来源适配器逐跳校验 HTTPS 域名，AcquisitionRun 和 RuntimeArtifact 保留原始页，EphemeralObservation 经 promotion policy、EvidenceIngress 与 EvidenceLink 才成为可供 StatePatch 引用的证据。索引无匹配只产生失败坐标，不证明不存在相关事实，也不关闭 EvidenceNeed。此切片不是任意 Web 搜索、浏览器、仓库或资产 Capability；这些仍需独立 contract/binding 与控制面验收。

同日补充 GitHub 精确取证：`github.read_development_record@1` 只接受 TaskContract 已绑定、属于 `github-target-repos` 白名单的 Repo/Issue/PullRequest/Commit/Release。Agent 可读取对象自身记录或同仓库的精确 GitHub 链接；PR 读取同时取得 API 记录与最多首 100 个改动文件，合并为同一原始 JSON 证据，标注列表可能截断与缺失 patch。版本列表保留有界的真实多条记录，不擅自把第一条称为已修复版本。所有调用同样经 Capability/Policy/Broker/Budget、AcquisitionRun、RuntimeArtifact 和 Evidence promotion；标题、描述或补丁片段不自动越过 M4 State Gate。任意仓库搜索、网络资产和 sandbox 仍未因此获得授权。

Agent turn 只是系统里的一个循环。retrieval expansion、来源回退、Incident follow-up、重试、repo traversal、subagent 和 Experience 重放都使用统一 `BoundedLoop`：

```text
BoundedLoop
  loop_id
  execution_id
  max_iterations
  deadline_at
  budget_ref
  progress_predicate
  no_progress_limit
  stop_predicate
```

局部 primitive 有 timeout 并不能推出整个 operation 有界；单批请求有限额，也不能阻止多轮、fan-out、重试和递归 child call 把总成本放大。因此所有循环都继承根 ExecutionEnvelope 的绝对截止时间和层级预算，并统一记录无进展。

这里直接吸收 OpenViking #4504 的 replay 教训：单次 RPC timeout 和单批 replay limit 无法约束整次用户可见 operation。`maxItems / maxRounds + timeBudgetMs + structured progress` 仍需要 operation-level total time / batch budget 才能闭合；SecFusionAgent 因此把预算传播到整棵执行树，而不是只限制最内层调用。

### 进展与停止

调查进展由状态变化判断，不以“模型又输出了一段文字”为准。第一版 `progress_delta` 关注五类变化：

- open / resolved EvidenceNeed 数量是否变化；
- 已确认 / 冲突 / 未知项是否变化；
- 关键决策变量是否收敛；
- 是否新增独立且满足证据要求的证据；
- 世界版本是否变化并带来新的可处理信息。

连续达到 `no_progress_limit` 后停止当前循环，选择回退、进入等待，或以部分结果结束。所有循环都返回结构化停止原因：

```text
stop_reason
  goal_satisfied
  evidence_sufficient
  budget_exhausted
  deadline_reached
  provider_blocked
  capability_denied
  policy_denied
  external_failure
  no_progress
  waiting_for_world_update
  human_review_required
```

高影响判断、长期无法消解的来源冲突、规范适用性不确定，或运行策略要求人工确认时，Case 进入 `human_review_required`。人工裁定必须以带 actor、time 和 evidence reference 的 StateEvent / Decision event 写回；数据库外的临时修改不能覆盖调查状态。

### 持续跟踪

`WATCH` Case 不保持长期运行的模型会话。Case 在 `waiting` 状态保存开放 EvidenceNeed、唤醒条件、`next_poll_at`、上次世界版本、期望来源 / 能力和剩余 `CaseBudget`。scheduler、来源增量、Incident 实质变化、官方新发布或时间条件满足后，再启动一个短执行轮次。

每次唤醒只读取上次 Snapshot 之后的变化：

```text
waiting
  -> wake(event / time / source change)
  -> read delta since last snapshot
  -> short investigation episode
  -> commit state change
  -> resolved / escalated / waiting
```

例如 Incident 在 T0 只有 breaking signal，Case 同时保留真实性、影响范围和根因三个未知项；T1 厂商确认关闭真实性缺口；T2 forensic / on-chain 证据更新影响范围并打开新的 attack-path question；T3 advisory / CVE 建立漏洞关系；T4 patch 触发 fix verification；T5 事后复盘关闭 root-cause question，并产生 Insight / Experience。M5 不需要让同一个 LLM session 连续运行数天。

## M6 研判与问答

M6 读取 M4 当前状态，不直接读取原始数据库或调用外部工具。`DIRECT / RETRIEVE` 通过轻量 Context 进入 M6；`VERIFY / INVESTIGATE` 在完成状态更新后进入同一个 Decision Runtime。当前状态不足以支持问题时，M6 只产生 `ContinuationRequest / EvidenceGapRequest`；M4 State Runtime 负责 validate/dedupe 并创建 EvidenceNeed，再由 Task Runtime 选择 InvestigationRole 或 delegated EnrichmentTask。M6 没有状态写权限。

```text
DecisionResult
  decision_id
  case_id / case_revision
  conclusions[]
    statement
    type = fact | inference | recommendation
    evidence_refs[]
    reasoning_relation_refs[]
  conflicts[]
  unknowns[]
  assumptions[]
  citations[]
  answer_payload
  stop_reason
  model_prompt_revision
```

`fact` 必须回到 M2/M3 evidence-backed Claim / Relation；`inference` 显式保留中间关系和支持证据；recommendation 不能冒充 normative requirement。来源冲突、证据不足、提供方受阻、预算 / deadline exhausted 都保留为冲突 / 未知项 / 部分结果，不由语言模型补成确定答案。

Citation binder 用 EvidenceRef 与 locator 绑定具体结论。多跳问题保存中间关系；同一对象的追问通过 ContextBinding 保持对象、版本、时间范围和已确认条件一致。Chat、report、API、timeline UI 都是 `DecisionResult` 的 presentation adapter。

Product Evidence 详情沿引用读取固定 Observation/Artifact 与 locator。对于 `access_rights.classification=public` 的 managed document，可返回同一 Observation 最新 parser revision 的有限正文节选（最多 6 段、每段 320 字符）供人工核对；受限来源不返回正文。对象级 EvidenceLink 仍只表示文档级支撑，节选不能冒充逐句 claim locator，完整来源由 canonical URL 或授权的 L4 路径继续查看。

## 端到端路径

下面六条路径覆盖快速查询、普通检索、主动验证、持续 Incident、规范知识和实时外部观测，也直接作为第一轮 integration / 评测样例。

### 精确漏洞字段

“CVE-X 的 CVSS 是多少”先由 deterministic parser 形成 TaskIntent，Task admission 生成 `DIRECT` TaskContract/TaskRun，读取 `current_vulnerability_view`。当前投影存在且 freshness 满足时，M6 从 ContextManifest 中绑定字段对应 EvidenceRef 后返回；默认不创建 durable Case、不启动 Agent、不访问外部 provider。projection miss 时按 TD1 read path 检查 durable Knowledge；若必须访问外部当前事实，则创建升级后的 TaskRun 并重新计算 capability/policy envelope。

### 研究资料检索

“有哪些关于 RAG poisoning defense 的研究”使用 `RETRIEVE` TaskRun。原始查询直接进入 L0 lexical + dense retrieval；候选装配器按主题覆盖、发表状态、来源独立性和时间范围装配文档集合，必要时做一次 synthesis。若用户进一步问“哪个 defense 经 adaptive attack 仍有效”，新 TaskIntent 经 admission 升级为 `VERIFY / INVESTIGATE` TaskContract，M4 建立/绑定 Case 并打开 EvidenceNeed，要求具体 threat model、adaptive evaluation 和 independent evidence，而不是继续增加 top-k 文档。

### 修复版本验证

“vLLM 0.21.0 到底修没修”先用 L1 解析 CVE、package 和 version，读取 current affected / fix projection、OSV fixed commit 与 GitHub graph。若 release 包含关系已有确定关系，可以直接结束；若只有 candidate fix commit，M4 打开 EvidenceNeed `first_release_containing(commit)`。

`VerifyFixBoundary` Skill 建议 local graph → GitHub commit/release → git ancestry → package changelog。`capability_visibility` 根据 TaskContract、provider health、budget 和 sandbox availability 生成 VisibleCapabilitySet；Planner 绑定具体 CapabilityRequest 后还要经过 invocation policy。primary evidence 经过 EvidenceIngress/Knowledge gate 后才能进入 StatePatch；State Integration Gate 再检查 object/version/EvidenceRef 并关闭 unknown。`PR merged_at` 只能保持 tentative，不能直接证明 release containment。

### Incident 持续调查

Breaking signal 先在 M1–M3 形成 IncidentCandidate。达到用户查询、promotion 或 watch 条件后建立持续型 Case，状态中保存真实性、影响范围、根因、资金流、fix / recovery 等待解决问题。每个来源增量只唤醒短执行轮次；M5 优先处理发生实质变化的 EvidenceNeed，primary / forensic / authority follow-up 通过来源角色路由，转载同源由 `source_family / upstream_source` 折叠。

事件结束后，事后复盘可以进入 Insight Corpus，完整调查 Trajectory 进入 Experience Evolution。Case 的历史状态和 Timeline 仍然可以按 Snapshot 回放。

### 规范适用性

“某 Agent 应用是否满足某规范 Requirement”先从 M3 读取 Requirement / Control 与 applicability conditions，再读取 M4 当前 Case 的 contextual applicability。若已有 evidence-backed `applicable / not_applicable` 结果可进入 M6；`not_evaluated / uncertain` 则由 M4 打开 EvidenceNeed，`AssessApplicability` Skill 指定需要补的系统事实、scope 与 exception condition。

法规 / 标准正文保持为 evidence data；只有经过 03 policy compilation / approval 的 RuntimePolicy 才进入执行控制面。M6 输出时明确区分 binding requirement、control recommendation 和系统 inference。

### 当前互联网资产观测

“现在有哪些公网资产可能暴露某受影响版本”属于当前 / 实时查询。本地 Knowledge 只能提供 product/version → fingerprint mapping，不能代表当前资产状态，因此需要外部观测。Censys / Shodan / FOFA / ZoomEye 根据凭据和提供方健康状态进入当前能力集合；返回结果先成为 `EphemeralObservation`，并携带 query、filter、observed_at 和 mapping version。

只有需要成为回答引用或长期 InvestigationState 时，观测结果才经过 EvidenceIngress 晋升。M6 的结论始终保留 observation time 与 mapping version，避免把一次时点观测写成永久事实。

## 数据存储与恢复

第一版不增加新的数据库产品，但增加 Redis 的第三个逻辑角色。PostgreSQL 保存持久 Task/Case/Context revision、TaskEvent durable log、EvidenceNeed、快照、Skill/Experience、Trajectory、执行元数据和物化状态；PostgreSQL FTS/pgvector 继续承担检索；Redis 分为 Celery broker、M1–M3 Hot Cache、Task Event Streams 三个逻辑 endpoint/DB，不互相复用语义；S3-compatible ArtifactStore 保存大体积 tool/browser/sandbox output 与需固定的原始 artifact。

持久对象按职责分开：

| 对象 | 存储 | 关键内容 |
|---|---|---|
| `task_contracts / task_runs` | PostgreSQL | principal、desired state、effect/delegation ceiling、completion、parent-child、status |
| `task_events` | PostgreSQL，仅追加 + Redis Streams delivery | task-local seq、event type、context revision、payload ref、idempotency |
| `context_manifests` | PostgreSQL | Task/Case/Knowledge/State/Evidence/Artifact refs 与 revision |
| `investigation_cases` | PostgreSQL | case lifecycle、targets、current task refs、initial_world_revision |
| `case_state_events` | PostgreSQL，仅追加 | base_revision、event_type、命题、evidence_refs、写入方、原因 |
| `investigation_state_current` | PostgreSQL，物化状态 | 已确认、conflicts、unknowns、needs、current_decision |
| `evidence_needs` | PostgreSQL | 命题、requirements、priority、status、resolution 证据 |
| `investigation_snapshots` | PostgreSQL，版本指针 | knowledge / index / incident / experience / 策略 / 能力 / 模型 revisions |
| `perception_events` | PostgreSQL | 请求、plan、观测 / percept refs、成本、结果 |
| `execution_runs` | PostgreSQL | envelope、父执行、截止时间、停止原因、延迟 |
| `budget_ledger` | PostgreSQL + 运行期缓存 | reserve / commit / release、resource type、parent-child 关系 |
| `capability_invocations` | PostgreSQL，审计日志 | 能力 version、args digest、策略 decision、结果 ref |
| `skill_versions` | PostgreSQL | applicability、procedure、失败 / 回退、validation 状态 |
| `trajectories` | PostgreSQL + ArtifactStore 引用 | 状态 before / after、动作、工具、percept、成本、outcome |

大体积原始输出不直接写入 trajectory row；运行时先写 ArtifactStore，再在状态事件、PerceptionEvent 或 TrajectoryEvent 中保存引用。当前实现中 `packages/runtime/artifacts` 是 Execution-scoped RuntimeArtifact owner：artifact identity 绑定 ExecutionRun、producer、logical name、trust class 与 content hash，blob 使用 content-addressed store，read 必须重新 hash 校验。RuntimeArtifact 不取得 M2 Evidence authority；只有显式 promotion 经过 Source/EvidenceIngress 后才能转成 Observation/EvidenceArtifact。M2 的 EvidenceArtifact object store 同样使用 content-addressed URI；若 durable metadata 仍在而 blob 丢失，exact Evidence replay 只能用同 content hash 的原始 envelope bytes 恢复相同 storage URI，不创建新的 Observation identity。`case_id / execution_id / parent_execution_id` 贯穿状态事件、预算账本和能力调用，使 M8 能够从最终 `DecisionResult` 回溯到对应的 EvidenceRef、具体工具调用、执行预算和世界版本。

这里不建立第二套 usage truth。`Trajectory/TrajectoryEvent` 的 latency/cost 字段是执行摘要与关联坐标：模型 token/cache/attempt 的 exact 事实归 `ModelAttempt/ModelUsage`；预算 reserve/commit/release 的 authority 归 `budget_ledger`；外部 Capability 的实际调用与可得 cost 归 `capability_invocations`。M7/M8 可以聚合这些 owner 形成 trajectory/report，但不能把摘要值回写成 provider usage 或预算真值。

Case 与执行状态都必须可恢复。worker 在提交状态事件后崩溃，不会丢失已经确认的事实；尚未完成的感知动作根据 execution 状态和幂等键重试。WATCH Case 的等待条件、`next_poll_at` 和开放 EvidenceNeed 都写入持久状态，进程恢复后可以重新调度。Budget 的已消费项和 capability invocation 也必须持久化到足以避免“恢复后预算归零”或重复执行高成本副作用。

## 失败与恢复

恢复策略由失败类型、工具幂等性和当前状态决定，不能给所有错误套同一个重试次数。

| 情况 | 状态变化 | 默认处理 |
|---|---|---|
| 精确 / 结构化查询 miss | EvidenceNeed 保持 open | 扩展到词法检索或关系图；确实需要当前外部事实时再访问外部来源 |
| 提供方返回 403 / 阻塞 | 能力不可用 | 更新提供方健康状态，从当前工具目录移除，选择独立回退来源 |
| 被限流 | 能力 temporarily unavailable | 遵循 `Retry-After`；预算允许时延后执行，或切换满足同一证据要求的提供方 |
| 缺少凭据 | 能力被拒绝 | 不自动重试；改走无需该凭据的路径，或以部分结果结束 |
| 来源冲突 | 冲突 opened | 使用 `contrast / corroborate`，优先补 primary / authority 证据 |
| 世界版本过期 | used 命题 marked 过期 | `refresh`；必要时重新打开 EvidenceNeed |
| 工具超时 | 调用失败 | 仅 safe / idempotent 工具按重试策略重试 |
| 非幂等副作用结果未知 | effect 未知项 | 停止自动重试，进入 reconciliation / 人工复核 |
| 沙箱执行失败 | 能力执行失败 | 记录 substrate 失败；选择更低风险的回退路径或以部分结果结束 |
| 预算或截止时间耗尽 | 未解决项标记为阻塞 | 保留已确认状态，生成部分结果 DecisionResult，不猜测剩余结论 |
| 连续无进展 | 循环停止 | 尝试回退、进入等待，或以部分结果结束 |
| 策略拒绝 | 能力 denied | 保留 denial 原因，不允许提示词绕过 |
| 需要人工复核 | Case 等待 | 等待 analyst event 写回后恢复 |

所有重试复用原幂等键与父 `ExecutionEnvelope`；通过其他来源获得的新证据仍然重新进入 M2 EvidenceIngress。回退来源不能偷偷降低 EvidenceNeed 的证据要求。例如 GitHub `primary` 来源暂时不可用时，二手博客可以增加 tentative information，但不能满足“必须 primary confirmation”的 EvidenceNeed。

provider health 是 capability visibility 的输入。持续 403、认证失败、限流或 timeout 会让 CapabilityContract 暂时退出当前 `VisibleCapabilitySet`，从而改变 Planner 的下一步选择；恢复后再重新进入。失败因此改变运行计划，而不是只留在日志里。

## M7 回放与评测

M7 同时评测 domain outcome 和 runtime protocol，不把“最终答错”当成唯一信号。固定 case 保存 TaskContract、ContextManifest、world/time cutoff、source availability、Enrichment/Investigation state、capability/policy/sandbox revisions、model/prompt/skill 与 expected protocol outcome；`Snapshot + Trajectory + TaskEvent checkpoint` 支持从任意 step intervention replay。

失败归因扩展为：

```text
availability
  -> enrichment-gap identification
  -> task/role routing
  -> capability visibility/binding
  -> policy/obligation enforcement
  -> perception selection/compression
  -> state/knowledge integration
  -> evidence use
  -> decision
```

M3 formal enrichment P/R 仍由 Requirements/TD1 的 `EnrichmentFactKey` 与 micro/dimension-macro 指标持有。TD2 新增 active enrichment / agent-runtime 指标：critical-gap recall、useful acquisition precision、final canonical enrichment completeness、wrong-entity/version attachment、redundant acquisition、delegation correctness、context-reuse efficiency、stop correctness、latency/cost。

在模型能力评测前先建立 deterministic conformance suite，目标 30–50 个最小 case：

- TaskContract admission / completion / cancellation；
- Role acceptance 与 TaskRun state transition；
- ContextManifest inherit/filter/fork/rebase/stale conflict；
- TaskEvent ordering/idempotency/replay 与 parent-child duplex update；
- Capability binding、visibility、invocation policy；
- authorization 与 obligation enforcement；
- delegation/effect/budget/deadline ceiling；
- sandbox profile selection 与 fail-closed downgrade；
- EphemeralObservation promotion；
- StatePatch authorization；
- WATCH resume 与 world-change wake；
- Skill manifest retrieval、procedure/step disclosure、mandatory guard materialization；
- ExperiencePattern → SkillPatchCandidate 的 replay、counterexample 与 regression gate；
- CapabilityCard / SchemaView disclosure 与 Binding schema-drift detection。

策略研究继续在同一 world/model/task/budget 下比较 raw retrieve、progressive zoom、gap-driven、skill-guided、single-loop 与 multi-loop/delegated enrichment。一个 schema 如果无法对 conformance case 机械计算期望结果，不进入主实现。

安全评测覆盖 prompt injection、poisoned source、malicious tool output、MCP schema change、memory/state poisoning、inter-agent trust propagation、context handoff pollution、capability escalation、sandbox/network escape、credential/side-effect misuse。模型 defense 与 substrate enforcement 分开报告。

## M8 运行与可观测

每个 Case、Execution、Perception、Capability invocation 和 RPC 共享 trace context。最低记录项包括：

```text
case_id / task_contract_id / task_run_id / parent_run_id
execution_id / parent_execution_id
context_revision / role_revision / execution_profile
state_revision_before / state_revision_after
evidence_need / perception_request / physical_plan
eligible_capabilities / selected_capability
policy_decision
budget_reserved / budget_consumed / budget_released
model_tokens / tool_calls / rpc_calls / retries
network_destination / sandbox_profile_revision / sandbox_backend
observation_refs / percept_id / evidence_refs
stop_reason / failure_class
latency / external_cost
```

secret value 不写入 trace；credential use 只记录 identity、scope 与 audit event。Policy、Skill、Capability Registry、PromptAssembly、model / provider revision 都进入 deployment version。线上出现的真实失败在去敏后进入 M7 回归样例；这些组件发生版本变化时，CI 重新跑对应固定 case。

M8 还负责系统级健康状态：provider health、Celery queue、Task Event Stream lag、TaskRun wake latency、Context stale/rebase rate、budget abnormal consumption、sandbox create/teardown failure、Network Gateway deny、outbox backlog 和 replay failure。业务失败与基础设施失败使用不同失败类别，避免把“证据不存在”和“提供方挂了”混成同一个未知项。

## 接口

第一版稳定 port 以 Task/Context/Capability/Policy 为主，不把物理 provider 或 transport 泄漏给上层。下表同时标出当前实现 owner；设计语义不要求每个概念 port 都对应一个同名 god service：

```text
TaskIntentParser.parse -> TaskIntent
TaskContractService.admit -> TaskContract
canonical_roles -> RoleProfile
domain admission compiler + Context service -> ContextManifest
ContextMaterializer.materialize -> PromptAssembly
create_task_run / transition_task_run / create_child_task_run / update_task_context
append_task_event / list_task_events
dispatch_pending_task_events / read_task_event_messages / ack_task_event_message
A2AAdapter.export / import
PerceptionPlanner.plan -> PhysicalPerceptionPlan
PerceptionRuntime.execute -> Percept
InvestigationStateService.open_evidence_need / apply_patch / commit_decision / get_state_at_revision
SkillStore.search_manifests / get_procedure / get_step / get_provenance
SkillResolver.resolve -> SkillSelection
ExperienceStore.retrieve_patterns
ExperienceCompressor.extract / merge / propose_patch
CapabilityRegistry.visible_capabilities / schema_view / resolve_binding
CapabilityBroker.invoke
PolicyEngine.evaluate -> PolicyDecision
BudgetGovernor.reserve / commit / release
SandboxBroker.create / exec / export / destroy
InvestigationRoleRuntime.run
TrajectoryStore.start / append_event / finish
DecisionService.decide -> DecisionResult
ReplayCheckpointService.capture / prepare
M7ReplayService.compare
SkillPromotionGate.evaluate / promote
```

`TaskContract patch/cancel` 属于已创建 contract/run 的生命周期操作，不属于 admission service；L0/L1 query normalization 与 physical read planning 当前由 `TaskIntentParser`、`packages.intelligence.retrieval` 和 `investigation.perception` 协作完成，因此没有为了目录图单独制造 `QueryConstructor` package。若后续 L2/L3 query planning 演化出独立状态/评测，再拆 owner。

M3 EnrichmentRole 获取新证据与 M5 InvestigationRole 获取外部观测时，都复用 TD1 的 `AcquisitionService / EvidenceIngress / Knowledge Writer`；不存在 Agent-only network/write side channel。ModelProvider 只接收 ContextMaterializer 产生的 instruction/data，不持有 source authority、credential 或 durable state write permission。

## 仓库映射

实现先按 ownership 拆包；Role 可以共享 runtime，但 domain state 留在 owner package：

```text
packages/
├── enrichment/
│   ├── runtime/          # EnrichmentRole adapter / EnrichmentTask planner
│   └── ...               # existing M3 operators/processors/state owner
│
├── investigation/
│   ├── perception/
│   ├── state/            # M4 InvestigationState / EvidenceNeed / Gate
│   ├── skills/
│   ├── runtime/          # InvestigationRole episode / WATCH
│   ├── cases/
│   ├── trajectory/
│   ├── experience/
│   └── replay/           # M7 checkpoint / historical M4 reconstruction
│
├── task_runtime/
│   ├── contracts/        # TaskIntent / TaskContract / TaskRun / RoleProfile
│   ├── admission/        # TaskIntent -> domain compiler -> policy-admitted TaskContract
│   ├── context/          # ContextManifest / materializer / revision handling
│   ├── events/           # durable TaskEvent + Redis Streams adapter
│   ├── scheduler/        # run/dependency/wake/delegation
│   └── a2a/              # external A2A compatibility adapter
│
├── runtime/
│   ├── capability/       # ToolImplementation / CapabilityContract / Binding / View / Request / Result / Broker
│   ├── policy/           # PolicyRequest / Decision / obligation enforcement
│   ├── budget/
│   ├── sandbox/          # OpenShell adapter / Firecracker adapter / profiles
│   ├── execution/        # ExecutionEnvelope lifecycle / bounded loop
│   └── artifacts/        # runtime artifact != Evidence
│
├── reasoning/
    ├── decision.py
    ├── citation.py
    └── model.py
│
└── evaluation/
    ├── m7_replay.py
    └── skill_promotion.py
```

`runtime/identity`、`runtime/network`、独立 `runtime/audit` 当前没有物理拆包：对应约束已经进入 ExecutionEnvelope、Policy、Sandbox 与各 owner 的 durable audit record。没有独立生命周期前不创建空 package。`apps/api` 只做 HTTP transport 与 application composition；Product/A2A routes 只组合现有 gate 和 read models，旧 Workbench transport 已退役，不持有 domain write authority。`apps/worker` 负责 coarse-grained task dispatch、WATCH wake 与 background work。Task Event Plane 不使用 Celery queue 充当 pub/sub。

### 实现一致性复验 — 2026-10-16

TD1→TD2 的 authority boundary 与当前代码一致：M1–M3 仍持有 Evidence/Knowledge 与 provider lifecycle；M4 持有 InvestigationState/EvidenceNeed/Decision durable write；M5 只通过 Perception、Task delegation 与受控 Capability 工作；M6 只消费物化 M4 state 并提出 typed final/continuation；M7 只评测 frozen coordinate 与 promotion，不反向成为 online runtime owner。当前实现中的目录合并（query、identity/network/audit）属于 physical packaging 差异，没有改变 owner 语义。

Task 入口也已统一：background enrichment 和 Product Investigation Task 都经过 `TaskIntent → domain binding/compiler → TASK_ADMISSION Policy → TaskContract → Context/Budget/ExecutionEnvelope → TaskRun`。A2A inbound 仍停在 TaskIntent mapping，直到 authenticated principal、classification 与 authoritative domain binding 完成后才允许 SendMessage 创建 executable work。

## 实现切片

下面保留原始 0–10 切片编号，状态按 2026-10-16 的实现证据更新；未闭环项继续挂在原 owner 上，不另造新层。

0. **Protocol conformance gate — 已闭环**：TaskContract、TaskRun state、Role acceptance、ContextManifest revision、TaskEvent ordering、Capability/Policy matrix 与 sandbox profile selection 已进入 deterministic contract/test gate。
1. **Task Runtime + duplex event — 已闭环**：PostgreSQL durable TaskEvent、Redis Streams delivery role、Task start/delegate/cancel/patch/wait/resume 与 parent-child state machine 已成立；Celery 只承担 coarse-grained dispatch。
2. **M3 EnrichmentRole — 已闭环**：background + delegated trigger 共用 EnrichmentState、operator/source primitive 与 Evidence/Knowledge write path。
3. **M4 State + InvestigationRole — 已闭环**：Case/InvestigationState/EvidenceNeed/StatePatch Gate 已与 TaskContract desired state、ContinuationGate 和 durable episode 对齐。
4. **Context handoff — protocol 已闭环 / 实验继续**：ContextManifest inherit/filter/fork/rebase/materialize 已实现；reference-vs-summary 的 token、critical-context retention 与 stale/conflict 对照属于 M7 实验，不再阻塞 runtime contract。
5. **Skill + Capability/Policy — substrate 已闭环 / production binding 扩展中**：Skill/Experience promotion、Capability contract/binding/view/invocation、两阶段 policy、obligation、delegation/effect ceiling 均有实现和 controlled evaluation；NVD、注册公开 HTML 和指定 GitHub 开发记录已接入；通用搜索/资产与广泛在线效果仍开放。
6. **Sandbox v1 — 部分闭环**：sandbox profile、ExecutionEnvelope、policy/fail-closed contract 与 replay/intervention seam 已成立；真实 OpenShell/OCI enforcement 与 Firecracker/KVM substrate 仍是明确 deployment boundary，不能用 mock/contract test 冒充。
7. **VERIFY end-to-end — 已闭环**：`VerifyFixBoundary` 已沿 `TaskContract → Perception → Capability → Policy → Sandbox(optional) → Evidence → State` 形成 canonical VERIFY path。
8. **Incident WATCH + async enrichment — 已闭环**：InvestigationRole/EnrichmentRole 的并行 episode、relevance-gated wake 与 durable wait/resume path 已成立；当前配置暂停自动 WATCH 唤醒。
9. **M6 Decision + A2A adapter — Decision 闭环 / transport 部分闭环**：ContinuationRequest ownership、DecisionResult 与 A2A deterministic mapper 已实现；GetTask compatibility seam 已有，SendMessage/Subscribe/push/authentication 等完整 transport 继续开放。
10. **M7 replay — controlled replay 已闭环 / historical world 开放**：TaskEvent/Context/Checkpoint、single/multi-loop 与 policy/sandbox/Skill/Capability intervention 已实现；真正 R3 historical Agent re-execution 继续受 M1–M3 versioned Historical Knowledge Read 阻塞。

## 技术评审与探针

本轮固定的 contract：Task-first；Role-after-Task；`TaskIntent → TaskContract → TaskRun`；Case 与 TaskRun 分离；reference-preserving ContextManifest；内部 async duplex TaskEvent Plane；EnrichmentRole + InvestigationRole 作为 v1 canonical multi-agent workload；M3 four-state EnrichmentState 与 M4 EvidenceNeed 分层；ToolImplementation / CapabilityContract / CapabilityBinding 三层分离；CapabilityCard→CapabilitySchemaView 渐进披露；visibility/invocation policy 分离；PolicyDecision 拆 authorization 与 obligations；SkillManifest→Procedure→Step→Provenance 渐进披露；seed Skill 与 Experience→SkillPatch 只能经 M7 replay/regression 晋级；Agent/peer/Capability output 先是 EphemeralObservation；child Task 不突破 parent effect/delegation/budget/deadline ceiling；Sandbox 默认 OpenShell + OCI container，高风险 profile 使用 Firecracker 且 fail-closed；M6 只提出 ContinuationRequest，不直接创建 EvidenceNeed；WATCH 使用短 episode。

需要尽早 probe 但不改变上述 contract 的选择：具体 L2 query model/prompt、retrieval fusion/rerank、Percept ranking、各 profile 数值预算、Skill retrieval/ranking、Experience clustering/compression、SkillPatch promotion threshold 与自动/人工审批比例、Capability binding fallback ranking、OpenShell 在 CI/WSL/Linux runner 的部署兼容、Docker vs Podman 默认 backend、Firecracker host/KVM 可用性、browser/full-VM runtime、Redis Streams consumer-group 参数、A2A adapter SDK/language。现在无法从实现证据确定的算法与阈值保持未冻结，coding/eval 可以反向修订 TD2。

优先 probe：

- **task/context protocol probe**：TaskContract completion、parent-child patch/cancel、Context stale/rebase、reference vs summary handoff；
- **duplex scheduling probe**：并行 Investigation/Enrichment TaskRun、event ordering、backpressure、reconnect/replay、无关 event 不唤醒 LLM；
- **capability/policy probe**：CapabilityCard→SchemaView→Binding→InvocationPlan，tool visible 但 invocation denied、obligation enforcement、delegation/effect ceiling、schema/server revision drift；
- **skill/experience probe**：manifest shortlist、procedure/step 渐进披露、seed guard 命中、ExperiencePattern 压缩与 SkillPatch replay/regression；
- **sandbox probe**：OpenShell container filesystem/network/secret isolation 与 teardown；Firecracker high-risk profile 的 startup/cost/isolation/fallback；
- **enrichment probe**：Website 真实案例从 gap→operator/source→Evidence→Knowledge→EnrichmentState fixed point；
- **watch probe**：Incident signal→primary→forensic→patch 的离散 replay，验证 TaskEvent wake、State/Enrichment refresh、stop/wait；
- **A2A interop probe**：Task/Artifact/stream/push 与内部 TaskRun/Event 映射，不以 A2A Context ID 替代 ContextManifest。

本轮设计没有改变 Requirements 的 M1–M8 ownership：M3 仍负责情报富化，M4 仍持有调查上下文，M5 仍负责 Agent 调查，M6 仍形成研判；共享 Task Runtime 只是实现这些模块和多 Agent 协作的 execution substrate。赛题要求的 Agent 自主决策、任务编排、工具调用、多 Agent 协作，以及容器化/工程化均由这些 protocol 和实现切片直接产生可测试证据。

### 实现参考

- A2A Protocol specification / streaming & async operations: https://a2a-protocol.org/latest/specification/ · https://a2a-protocol.org/latest/topics/streaming-and-async/
- A2A custom protocol bindings（含 WebSocket 双向 transport 示例）: https://a2a-protocol.org/latest/topics/custom-protocol-bindings/
- NVIDIA OpenShell: https://github.com/NVIDIA/OpenShell
- GitHub Agentic Workflows Security Architecture: https://github.github.com/gh-aw/introduction/architecture/
- Firecracker design: https://github.com/firecracker-microvm/firecracker/blob/main/docs/design.md
- DeepSeek Elastic Compute (DSec): https://arxiv.org/abs/2609.22978

### 2026-10-16 调查运行时只读边界

Investigation planner/role 通过 `packages.runtime.read` 获取预算 limits 的值副本与
按 task/purpose 限定的逻辑模型请求次数，保持恢复后的迭代窗口，不直接依赖 runtime ORM。
预算修改与模型记账继续属于 runtime owner；依赖门只开放该只读接口，不开放任意 storage import。