横切关注点合订包
本横切包承接架构主文件 §13（故障与降级）/ §18（可观测性）/ §19（演化与版本管理）/ §20（测试体系）中跨多个子系统、跨多个 milestone 的横切要求，把它们从主架构的叙述层落到「工程可直接开干」的契约层。字段权威以 frontmatter
schema_sources列出的contracts/code-paths.yaml与架构主文件为准，本包与之不一致时以上游为准。模板来源：横切包模板。上位整改背景见 Step 11 整改包详细方案 Action II-3。
§0 范围与 milestone 切分
覆盖五类横切。每类先讲「系统要主动提供的韧性 / 可观测能力（正向）」，再讲约束。
| 关注点 | 主架构对应 | M0 范围 | M1+ 演化 |
|---|---|---|---|
| 韧性策略（超时 / 重试 / 熔断 / 限流） | §12 超时 + §13 降级 + §16 限流 | ✅ 超时分层 + 重试 + 限流 Semaphore（M0 必做） | 熔断器从 30 min 滑窗（M0 简版）升级为状态机式断路器（M1） |
| 可观测性指标体系 | §18 指标体系 | ✅ 审计 trail + 性能/成本/可靠性核心指标落点（M0 必做） | 认知质量间接指标聚合（M1+，依赖评估闭环 §21） |
| Schema migration SOP | §19 数据 schema 版本化 | ⏳ 元表 + runner 骨架（M0 建表即用，M0 不触发实际 migration） | 实际 v1→v2 migration 脚本（M1+ 首次破坏性 schema 变更时） |
| Contract regression hook | §20 测试 + 字段演化矩阵 | ⏳ 接入点预留 + 字段宽紧度基线（M0 标基线） | audit_contract_regression.mjs 实施（M1+ 字段收紧时） |
| CI gate（三检 review gate） | §20 CI 集成 + §26 审计点 | ✅ pre-commit + PR 快档（M0 必做） | nightly 真档 + 评估测试接入（M1+） |
取舍原则：M0 走通骨架够用即停，不预先实现「第一阶段明示不做」的能力（架构 §18/§20 末尾清单：分布式 trace、云端日志聚合、A/B 框架、实时 metric dashboard、fuzzing 等）。接口契约预留，实现不抢答。
§1 韧性策略（超时 / 重试 / 熔断 / 限流）
§1.1 系统主动提供的韧性能力（正向）
FinBayes 本地优先定位要求「比业界默认更高的可用性」（§13）。运行时主动提供四类韧性能力：
- 分层超时：每一层（工具 / LLM / Task / TaskGroup / Compactor）有独立超时预算，单层超时不拖垮全链路，超时后保留已完成的部分结果交付用户。
- 自适应重试：瞬时故障（限流 / 5xx / 超时）自动重试，不让用户感知一次性抖动。
- 熔断隔离：持续失败的 Provider 被主动短路，避免无谓重试放大延迟与成本，并明示用户切换到 fallback。
- 背压限流：全局并发受控，本地资源不被无界并发耗尽，超限请求排队而非静默卡顿。
§1.2 超时策略（契约级参数）
承接 §12 超时控制。所有值走配置文件，下表为默认值与契约接口。
| 层级 | 默认超时 | 配置粒度 | 超时错误码 | 超时后行为 |
|---|---|---|---|---|
| 单个工具调用 | 30s | per-tool | TASK_TIMEOUT（标 source 层） | EvidencePacket 标 degraded_reason: timeout，不阻塞其他证据 |
| 单个 LLM 调用 | 60s | per-task-type | TASK_TIMEOUT（标 llm 层） | 触发重试链；耗尽后触发降级链 |
| 单个 Task（证据 + 综合） | 120s | per-task-type | TASK_TIMEOUT | cancel 进行中协程 + 保留部分结果 |
| TaskGroup（用户感知总等待） | 180s | 全局 | TASK_TIMEOUT | 各子任务收 cancel + 5s grace |
| Session Context Compactor | 30s | 全局 | TASK_TIMEOUT | 退化为不压缩 + 截断保留关键 Judgment |
契约接口：超时由统一 with_timeout(coro, layer, task_type) 包装器注入；每次超时写审计 trail 字段 timeout_layer + elapsed_ms。
§1.3 重试策略（契约级参数）
仅对幂等且瞬时的失败重试。下表为契约级默认。
| 失败类型 | 是否重试 | 最大次数 | 退避策略 | 备注 |
|---|---|---|---|---|
| 限流（429 / rate limit） | ✅ | 3 | 指数退避 + 抖动：base=1s, factor=2, jitter=±20%，尊重 Retry-After 头 | 超次数后降级到 fallback Provider |
| 5xx（服务端错误） | ✅ | 2 | 指数退避 base=0.5s, factor=2 | 超次数后熔断计数 +1 |
| 超时（网络层） | ✅ | 1 | 立即重试一次（换 Provider 端点优先于重试同端点） | 超次数后触发降级链 |
| 鉴权失败（401 / 403） | ❌ | 0 | — | 不重试，启动期已探测；运行期直接降级 + 明示用户重配 key |
| 解析失败（响应 schema 不合法） | ❌ | 0 | — | 标 parse_error，归一化处理，不重试同一坏响应 |
| 用户取消（CancelledError） | ❌ | 0 | — | 取消是意图明示，不是故障 |
契约接口：重试由 with_retry(coro, policy) 包装器注入，policy 从 providers.yaml 的 per-provider retry 段读取。每次重试写审计 trail 事件 retry_attempt（attempt_no / reason / backoff_ms）。幂等保证：仅包裹无副作用的读类调用（LLM 推理 / 数据查询）；任何写状态的操作不进重试包装器。
§1.4 熔断策略
承接风险登记 T1「Provider 失败率连续 30 min >10% → 自动降级 + 用户通知」。
M0 简版（必做）：滑动窗口计数器。每 Provider 维护 30 min 滑窗失败率，连续 >10% 触发「软熔断」——该 Provider 在 fallback 排序中降权，新任务优先走下一 Provider，写审计事件 provider_circuit_soft_open + 用户 banner 提示。
M1+ 演化：升级为三态断路器（closed / open / half-open）：
| 状态 | 进入条件 | 行为 | 退出条件 |
|---|---|---|---|
| closed | 默认 / half-open 探测成功 | 正常调用 | 滑窗失败率 >阈值 → open |
| open | 失败率超阈值 | 直接短路不调用，立即走降级链 | 冷却期（默认 60s）后 → half-open |
| half-open | open 冷却期满 | 放行单个探测请求 | 探测成功 → closed；失败 → open |
契约接口：CircuitBreaker(provider_id) 暴露 allow() -> bool + record(success: bool)；状态变更写审计 trail。M0 仅实现 allow() 的滑窗逻辑，三态机预留接口。约束：熔断只作用于 Provider 层；状态对象写入 / 边界保护等核心路径不熔断。
§1.5 限流（背压）
承接 §12 backpressure + §16 限流处理。
| 限制项 | 默认值 | 实现 | 配置 |
|---|---|---|---|
| 同时进行 Task 数 | 5 | asyncio.Semaphore | ✅ |
| 单 Task 内并发工具数 | 3 | asyncio.Semaphore | ✅ |
| 总 LLM 调用并发（跨 Task） | 10 | asyncio.Semaphore | ✅ |
| 数据 Provider 调用并发 | 20 | asyncio.Semaphore | ✅ |
| per-Provider rate limit | 各 Provider 配置 | token bucket / Semaphore | ✅（providers.yaml） |
约束：超限请求进 FIFO 队列等待，用户看到「正在排队」而非静默卡顿；排队时长进指标 task_queue_wait_ms。
§2 可观测性指标体系（指标清单 + 落点）
§2.1 系统主动提供的可观测能力（正向）
承接 §18 两类可观测对象——认知过程可观测（用户为主：为什么走这个 Provider / 为什么降级 / 这条 Judgment 怎么形成）与系统运行可观测（工程为主：延迟 / 错误率 / 成本 / 负载）。运行时主动：
- 每个认知任务生成贯穿全子系统的
task_id，可重建完整因果链； - 每次降级 / 重试 / 熔断 / 边界拒收都写审计 trail，用户可查「为什么这次这样」；
- 指标 per-user 独立计算，用户成本与质量自主可见。
§2.2 Trace ID 体系（M0 必做）
承接 §18 trace 体系。每事件至少标 task_id，子调用追加对应 ID。
| ID | 范围 | M0 |
|---|---|---|
session_id | Session 生命周期 | ✅ |
task_id | 单次认知请求全链路 | ✅ |
tool_call_id | 单次工具调用 | ✅ |
llm_call_id | 单次 LLM 调用 | ✅ |
trace_id | 跨 session 主动信号链 | ⏳ M4+（主动信号上线时） |
§2.3 指标清单 + 落点（contract 表）
下表把 §18 指标体系落到「产生子系统 + 写入落点 + M0 是否必做」。落点统一为审计 trail（认知过程）+ 进程内指标计数器（系统运行），第一阶段不引入 Prometheus / 云端聚合（§18 末尾约束）。
| 类别 | 指标 | 产生子系统 | 落点 | M0 |
|---|---|---|---|---|
| 性能 | task_latency_first_screen | Output Pipeline | 计数器 + 审计 | ✅ |
| 性能 | task_latency_complete | Task Orchestration | 计数器 + 审计 | ✅ |
| 性能 | llm_call_latency | Provider Adapter | 计数器 + 审计 | ✅ |
| 性能 | tool_call_latency | Capability Registry | 计数器 + 审计 | ✅ |
| 性能 | concurrent_tasks / task_queue_wait_ms | Task Orchestration | 计数器 | ✅ |
| 成本 | provider_token_usage | Provider Adapter | 审计（input/output 分列） | ✅ |
| 成本 | provider_cost_estimate | Provider Adapter | 审计 | ✅ |
| 成本 | cache_hit_rate | Cache 层 | 计数器 | ✅ |
| 可靠性 | degradation_rate_by_layer | Provider Adapter | 计数器 + 审计 | ✅ |
| 可靠性 | provider_failure_rate | Provider Adapter | 计数器（喂熔断器） | ✅ |
| 可靠性 | retry_count_by_reason | 韧性包装器 | 计数器 + 审计 | ✅ |
| 可靠性 | boundary_reject_rate | Input Pipeline | 计数器 + 审计 | ✅ |
| 可靠性 | state_store_write_failure | State Management | 计数器 + 审计 | ✅ |
| 认知质量 | self_consistency_divergence | Evidence + Synthesis | 审计 | ⏳ M1+ |
| 认知质量 | evidence_completeness | Evidence + Synthesis | 审计 | ⏳ M1+ |
| 认知质量 | clarify_rate | Task Orchestration | 计数器 | ⏳ M1+ |
| 认知质量 | user_action_on_candidate_rate | State Management | 计数器 | ⏳ M1+ |
§2.4 各子系统接入点（logging / audit / metrics）
承接 §18 日志分级（ERROR/WARN/INFO/DEBUG/TRACE）+ 脱敏约束。下表给每子系统的默认接入。
| 子系统 | 日志级别 | Audit 事件 | Metrics 接入 |
|---|---|---|---|
| Input Pipeline | INFO（边界识别 WARN） | boundary_event / user_action | boundary_reject_rate |
| Task Orchestration | INFO | task_event（开始/完成） | task_latency_* / concurrent_tasks / clarify_rate |
| Evidence + Synthesis | INFO | evidence_event / synthesis_event | self_consistency_divergence / evidence_completeness |
| State Management | INFO（写失败 ERROR） | state_event（before/after） | state_store_write_failure / user_action_on_candidate_rate |
| Capability Registry | INFO | tool_event（注册/调用/退役） | tool_call_latency |
| Provider Adapter | INFO（降级 WARN） | provider_event / degradation_event / retry_attempt | provider_* / degradation_rate_by_layer / cache_hit_rate |
脱敏不变量（全级别强制，M0 必做）：日志与审计 trail 不写 API key / Channel token / 任何凭证；边界拒收只标识别类型不含具体字符串；不写完整 LLM 入参出参（仅摘要 + token 数，完整内容仅 TRACE 级 + 用户明示警告）；不写完整用户画像（仅摘要 / hash）。
§3 Schema migration SOP
§3.1 系统主动提供的演化能力（正向）
承接 §19 数据 schema 版本化。State Store 升级时主动：启动期自动探测版本差、自动备份、按序运行 migration、失败自动回滚、向用户展示进度（不黑盒）。用户数据主权不因 migration 受损。
§3.2 Migration SOP（M0 建表即用，实际 migration M1+ 触发）
承接 §19 流程图。runtime 启动时执行：
- 读元表：读
schema_metadata.schema_version（M0 必做：建表 + 写入 v1 基线）。 - 比对：runtime 期望版本 vs DB 版本。
=→ 正常启动；>（需升级）→ 进 step 3；<（DB 比程序新）→ 拒绝启动 + 提示用户升级 FinBayes 或恢复旧版本。
- 强制备份：SQLite 文件复制为
*.bak（含时间戳）。 - 按序运行：v1→v2→v3 顺序执行 migration 脚本。
- 校验完整性：成功 → COMMIT + 追加
migration_history；失败 → 全量从 bak 恢复（不留中间状态）。 - 进度可见：向用户展示「正在 migration（n/total）」。
§3.3 幂等三层保证（契约级，移植自 §19）
migration 脚本单向（只有 up，降级靠 bak 恢复），且必须幂等：
- DDL 层幂等：所有
CREATE TABLE/CREATE INDEX用IF NOT EXISTS；ALTER TABLE ADD COLUMN先查PRAGMA table_info跳过已存在列。 - 运行时层幂等：runner 启动读
schema_metadata.migration_history（JSON 数组），跳过已记录的 migration 文件名。 - 事务层：每脚本单事务执行，失败 ROLLBACK + 不写 history；成功 COMMIT + 追加 history。
§3.4 元表 schema（M0 必做）
State Store 含元表 schema_metadata：schema_version / finbayes_version / migrated_at / migration_history（含 from / to / timestamp / 备份位置）。
约束：migration 失败的回滚不可半途；用户能看到进度；migration 不删除用户数据列前必先 deprecated 一个 minor 版本（与接口契约 §19 删字段规则一致）。
§4 Contract regression hook
§4.1 系统主动提供的契约稳定能力（正向）
承接 §19 接口契约 semver + §20 测试 + 里程碑字段宽紧度演化矩阵。系统主动：在字段从 Optional → required 收紧、或接口 major 变更时，自动检出对历史 case / 既有 client 的破坏，阻断「悄悄改语义」。
§4.2 接入点（M0 标基线，M1+ 实施脚本）
| 接入点 | 内容 | M0 | M1+ |
|---|---|---|---|
| 字段宽紧度基线 | 在字段演化矩阵标 M0 各字段 Optional/required 状态（至少 s1 / mca_bucket.worst_axis / mca_bucket.tag_version / regulation_status） | ✅ 标基线 | — |
audit_contract_regression.mjs | 检出字段收紧时点 vs 矩阵声明不一致 / 未声明的破坏性变更 | ⏳ 接口预留 | ✅ 实施 |
| Pydantic schema diff | PR diff 中 contract 字段变更映射到 semver 等级（新增 optional=minor / 删字段或改语义=major） | ⏳ 预留 | ✅ |
| contract_version 拒绝逻辑 | 不同 major 返回 INVALID_CONTRACT_VERSION + 支持版本范围 | ✅（运行时已在契约） | — |
§4.3 字段级演化规则（契约级，移植自 §19）
- 新增 optional 字段 → minor；新增 required / 删字段 / 改语义 / 改类型 → major。
- 删字段前必须先 deprecated 一个 minor 版本，给升级窗口。
- 不向已发布接口悄悄改字段语义（即使字段名 / 类型不变）——这是 contract regression hook 的核心拦截目标。
- 每次 major 升级附升级指南（自动转换工具 + 手动迁移说明）。
约束：字段收紧（Optional→required）必须在演化矩阵声明收紧时点；未声明即收紧 → M1+ 的 audit_contract_regression.mjs 报错阻断。
§5 CI gate（三检 review gate）
§5.1 系统主动提供的质量门能力（正向）
承接 §20 CI 集成 + §26 审计点 + arch-rewrite/ADR-001 三检 review gate + ADR-003 PR review checklist。CI 主动：每次 PR 前快档全跑（业务流转 + 边界回归），nightly 真档跑（真 LLM），release 前完整评估，把战略边界违规挡在主分支外。
§5.2 三档 CI（移植自 §20，标 M0 范围）
| 触发 | 跑什么 | M0 |
|---|---|---|
| 每次 PR | 单元 + 集成 + 端到端快档（Mock LLM）+ 边界测试集 + verify-kb | ✅（M0 必做，≤15 min） |
| nightly | 全部 + 端到端真档（低成本 Provider）+ 评估测试 | ⏳ M1+（≤1 小时） |
| release 前 | nightly 全跑 + 完整评估数据集 + 性能基线对比 | ⏳ M1+ |
边界测试硬约束（M0 必做）：CI 跑边界测试集失败 = 阻断 release。战略边界（凭证拒收 / 执行类工具拒绝 / 用户数据隔离 / TLS 不降级 / 本机 socket 限）一旦被绕过影响远大于功能 bug。
§5.3 配套脚本 / hook
承接整改包 IV 已实施部分。
- ✅
scripts/verify-kb.mjs（已存在，治理库内容校验） - ✅
scripts/audit_cross_section_consistency.mjs（Step 11 IV-1） - ✅
scripts/audit_p0_decision_touch.mjs（Step 11 IV-2） - ⏳
scripts/audit_contract_regression.mjs（§4，M1+ 实施） - ⏳
scripts/audit_strategy_fidelity.mjs（M1+ 实施）
| gate | M0 | 内容 |
|---|---|---|
| pre-commit | ✅ | derive:check + verify:kb（husky，已生效） |
| CI 严格门 | ⏳ M1+ | audit:cross-section:strict + audit:p0-touch --base=main |
§6 ADR 引用（namespace prefixed）
- arch-rewrite/ADR-001 工程范式（三检 review gate 来源，accepted）
- arch-rewrite/ADR-003 工程实施栈与协作（PR review checklist 11 项 + AI 三方互审，accepted）
- arch-rewrite/ADR-009 Prompt 是代码还是数据（待定，影响 Prompt 版本化落点）
§7 关联资产
- 上位整改方案：Step 11 整改包 II + IV 详细方案
- 主架构：FinBayes 工程架构（§12 超时/并发、§13 降级、§16 限流、§18 可观测、§19 演化、§20 测试、§26 审计）
- M0 工程包：M0 Walking Skeleton
- 字段演化基线：里程碑字段宽紧度演化矩阵
- 三集分集与防泄漏：Case 库 70/20/10 三集分集物理实施约定
- PR review checklist：仓内
.archon/workflows/pr-review-checklist.md - Document review 范式：文档 review 范式 Playbook