CHANxuanyu/verifier-driven-incident-response-agent

# 校验驱动的事件响应 Agent 框架 这是用于事件响应工作流的 Python 运行时原型，围绕校验驱动 (verifier-driven) 的状态转换、仅追加的记录 (append-only transcripts)、可恢复的检查点以及感知审批的边界而构建。本仓库不是一个通用的 Agent 演示，不是编码 Agent，也不是自主修复系统。它是一个窄范围的框架里程碑，旨在展示如何在添加更广泛的自动化之前，使面向事件的 Agent 行为具备持久性、可检查性、可重放性和安全性。 ## 该运行时的用途 该运行时专为事件处理风格的工作流设计，在这些场景中，状态和产物的正确性比演示的广度更重要： - 对结构化的事件载荷进行分类 - 选择一个确定性的后续目标 - 读取一个确定性的证据包 - 生成一个经校验器支持的假设 - 生成一个经校验器支持的建议 - 提供一个需审批批准的动作候选存根 - 从持久化的运行时状态生成面向操作员的交接产物 ## 它不适用于什么 本仓库不实现以下内容： - 对外部系统的真实修复或变更 - 通用的规划器或开放式的自主循环 - 类似 Claude Code 的编码 Agent 产品界面 - 多 Agent 编排 - 审批 UI 或评审工作流集成 - 外部服务集成或生产部署基础设施 ## 为什么这不是一个通用的 Agent 演示 大多数 Agent 演示侧重于广泛的能力宣传或 UI。本仓库侧重于框架工程： - 校验驱动的完成，而不是“模型已返回” - 仅追加的 JSONL 记录，而不是隐藏的内存状态 - 检查点驱动的可恢复性，而不是尽力而为的重试 - 显式的审批边界，而不是隐含的风险自主权 - 可重放的固定数据和评估覆盖，而不是一次性的截图 重点在于证明一个可靠的运行时核心，而不是宣称产品完备性。 ## 运行时核心 当前实现的链路： `分类 (triage) -> 后续 (follow-up) -> 证据 (evidence) -> 假设 (hypothesis) -> 建议 (recommendation) -> 需审批的动作存根 (approval-gated action stub)` 每个环节都是狭窄且明确的。 1. `IncidentTriageStep` 读取结构化的事件载荷，发出记录事件，验证分类输出，并写入第一个检查点。 2. `IncidentFollowUpStep` 从检查点和记录状态恢复，要么安全地空操作，要么选择仅一个只读的调查目标。 3. `IncidentEvidenceStep` 从持久化的工件中重建选定的目标，并读取一个确定性的证据包。 4. `IncidentHypothesisStep` 消费一个已验证的证据记录，并生成恰好一个结构化的假设。 5. `IncidentRecommendationStep` 消费一个已验证的假设，并生成恰好一个结构化的建议性建议。 6. `IncidentActionStubStep` 消费一个已验证的建议，并生成恰好一个感知审批的动作候选存根，或一个显式的保守型无操作结果。 该链路在此处有意停止。它证明了动作候选资格和审批状态，而不执行真实的写入操作。 ## 运行时基础设施 ### 持久化契约 - 位于 `skills//SKILL.md` 下的基于文件的技能 - 类型化的工具、校验器结果、记录事件和检查点 - 用于可重放证据的确定性本地固定数据 ### 执行真相 - 位于 `sessions/transcripts/.jsonl` 的仅追加记录事件 - 位于 `sessions/checkpoints/.json` 的可恢复检查点 - 在每个实现的环节进行校验驱动的阶段转换 ### 共享运行时层 - `SessionArtifactContext` 加载检查点和记录一次，并重建最新的已验证产物 - 合成失败不变量 将格式错误、缺失或中断的产物路径规范化为结构化的可重放失败 - 共享的可恢复环节框架 集中处理恢复、权限、工具、校验器和检查点的连接，同时将领域逻辑保留在每个步骤内部 - 权限来源 记录决策被允许、被阻止或需要审批的原因 ### 语义记忆与操作员产物 - `IncidentWorkingMemory` 存储当前事件理解的紧凑已验证快照 - 交接上下文组装 从检查点、已验证产物和工作记忆构建一个只读的面向操作员的上下文对象 - 稳定的交接产物被写入 `sessions/handoffs/.json` - 交接产物可以从现有的持久化状态确定性地重新生成 ## 审批边界理念 该运行时故意保持保守。 - 当策略允许时，只读步骤可以继续执行。 - 更强的证据可以证明结构化的动作候选是合理的。 - 候选仍然不是执行。 - 任何未来的非只读操作仍不在范围内，直到明确设计审批和执行语义。 这就是为什么运行时在需审批的动作存根处结束，而不是继续进入修复阶段。 ## 重放 / 评估说明 本仓库包含基于固定数据的重放式覆盖，而不是通用的基准测试框架。 已实现的分支： - 支持分支： `recent_deployment -> deployment_regression -> validate_recent_deployment -> deployment_validation_candidate` - 保守分支： `runbook -> insufficient_evidence -> investigate_more -> no_actionable_stub_yet` 这些场景证明了该框架可以携带已验证的状态向前推进，在证据不足时保持保守，并保持审批边界的显式性。 ## 交接产物能力 当前的里程碑包括面向操作员的派生产物流程： `SessionArtifactContext -> IncidentHandoffContextAssembler -> IncidentHandoffArtifactWriter` 你也可以使用内部重新生成器从 session id 重新生成最新的交接产物： ``` from context.handoff_regeneration import IncidentHandoffArtifactRegenerator result = IncidentHandoffArtifactRegenerator().regenerate("session-id") ``` 这将写入或更新： - `sessions/handoffs/.json` 交接产物仅是派生输出。它不是控制平面的一部分。 ## 故意排除的范围 - 真实执行或修复 - 人工审批 UI - 项目记忆提升 - 后台提取或压缩系统 - 通用规划器 / 工作流引擎 - 多 Agent 编排 - API 服务器或最终用户产品界面 ## 验证命令 安装开发依赖项： ``` python -m pip install -e '.[dev]' ``` 运行完整的验证栈： ``` ruff check src tests docs mypy src tests pytest ``` 仅运行重放覆盖： ``` pytest tests/integration/test_incident_chain_replay_eval.py ``` 运行两个固定的演示场景： ``` pytest tests/integration/test_incident_chain_replay_eval.py::test_incident_chain_replay_eval_runs_supported_hypothesis_chain pytest tests/integration/test_incident_chain_replay_eval.py::test_incident_chain_replay_eval_runs_insufficient_evidence_chain ``` ## 仓库结构 ``` src/agent/ Narrow resumable step runners src/context/ Session artifact context, handoff assembly, handoff regeneration src/runtime/ Shared harness and synthetic failure normalization src/tools/implementations/ Deterministic read-only tool actions src/verifiers/implementations/ Structured verifier logic src/memory/ Checkpoints and incident working-memory persistence src/transcripts/ Typed transcript models and JSONL storage src/evals/ Replay/eval runner skills/ Durable skill assets evals/fixtures/ Fixed evidence and scenario fixtures tests/unit/ Contract and component tests tests/integration/ End-to-end slice and replay coverage docs/ Architecture, demo, interview, and resume materials ``` ## 里程碑状态 本仓库应被视为一个已完成的运行时里程碑，而不是一个成品。 本次里程碑完成的内容： - 从分类到感知审批的动作候选的校验把关环节链 - 检查点加记录的可恢复性 - 通过 `SessionArtifactContext` 进行的可重放产物重建 - 针对格式错误或部分运行时路径的合成失败规范化 - 权限来源和显式的审批状态持久化 - 第一个事件工作记忆环节 - 面向操作员的交接组装、产物写入和确定性重新生成 故意推迟的内容： - 真实执行语义 - 超越第一个事件工作记忆环节的更广泛记忆分层 - 外部审批、集成和产品界面 ## 更多文档 - [架构概览](docs/architecture.md) - [演示指南](docs/demo.md) - [恢复框架说明](docs/resume.md) - [面试指南](docs/interview.md) - [项目摘要](docs/project_summary.md)

标签：Agent框架, FTP漏洞扫描, Homebrew安装, Incident Response, LLM Agent, Python, 人机协同, 仅追加日志, 假设生成, 决策支持, 可重放性, 安全编排, 安全规则引擎, 审计追踪, 护栏, 无后门, 时序数据库, 检查点, 状态机, 确定性工作流, 结构化查询, 自动化安全, 运行时, 逆向工具, 韧性系统, 验证驱动