面向 Jetson Orin 边缘设备的生产级 ReAct 推理循环。本地 GGUF 量化模型推理，YAML 驱动协议配置。不依赖云端 —— 完全离线运行。
在进入 ReAct 循环之前，四个并行模块同步分析用户意图。安全门禁拥有一票否决权 —— 危险操作在工具执行前即被拦截。
模块化架构，依赖注入设计。每个模块可独立替换、独立测试。全局无状态 —— 所有依赖通过构造函数显式传入。
状态机驱动的 ReAct 循环。九个状态，显式错误恢复路径。AgentCore 取代了原有的单体函数 run_react_agent()，通过依赖注入实现完全可测试。
并行意图识别层。规则匹配器、安全门禁（否决权）、上下文分析器、工具预选器四模块并行执行，由意图协调器融合结果。总耗时不到 50 微秒。
LLM 后端协议 + 本地 GGUF 推理后端。基于 llama-cpp-python，支持 Qwen2 聊天模板、停止序列控制、token 计数与人民币成本核算。
YAML 驱动的 ReAct 协议配置。PromptTemplate 渲染缓存友好的提示词。ResponseParser 实现四级优先级正则解析，每级均有后备策略。
工具注册中心，内置计算器（L1 子进程沙箱隔离）和天气查询工具。ToolNotFoundError 与 ToolExecutionError 支持 ReAct 循环内的优雅恢复。
观测结果消毒器。七步纵深防御流水线，在工具输出进入 LLM 上下文前完成：剥离聊天模板令牌、阻断 ReAct 格式注入、阻断命令执行模式。
全链路可观测性。逐轮 TraceRecord 记录 + 跨轮 diff 分析（公共前缀、KV-cache 复用估算）。自包含 HTML 追踪报告，支持深色/浅色模式。
对 LangChain 1.0、OpenAI Agents SDK 和 Anthropic Claude Agent 三大生态进行七个维度的系统对比。涵盖 13 个章节、129 个小节。
| 对比维度 | LangChain 1.0 | OpenAI Agents SDK | Claude Agent | AgentDev |
|---|---|---|---|---|
| 架构核心 | 标准化 ReAct 循环 + 五种生产设计模式 | Harness-Sandbox 分离（行业标杆） | Skills + Hooks + Modes 架构（九类技能） | 状态机 ReAct + 并行意图识别 |
| 工具执行 | LangChain Tool 抽象，@tool 装饰器 | 托管沙箱（mdb / codx / daytona） | 54 个基础工具，三个注入点 | ToolRegistry + L1 子进程沙箱 |
| 安全模型 | 工具级输入验证（手动实现） | 四级沙箱（L0-L3），宿主管控 | 七层安全边界，拒绝优先，渐进信任 | 安全门禁（否决权）+ 观测消毒器（七步流水线） |
| 可观测性 | LangSmith 追踪（依赖云端） | OpenAI traces + span 面板 | JSONL 转录，五层压缩 | 全链路 TraceCollector + HTML 报告 + 人民币成本 |
| 推理运行时 | 任意 LangChain 兼容后端 | 仅 OpenAI 模型（GPT-4o, o3, o4-mini） | Claude 模型，百万 token 上下文 | 本地 GGUF（llama-cpp-python），Jetson Orin，32K 上下文 |
| 意图识别 | 纯 LLM 判断（单次调用） | 纯 LLM + 工具使用循环 | yoloClassifier（快滤 + 思维链两阶段） | 四模块并行分析（规则 / 安全 / 上下文 / 工具） |
| 文档体系 | 丰富的文档与教程（英文） | API 参考 + Cookbook（英文） | CLAUDE.md 四级体系 | BRD + FSD + 术语表 + 行业调研 + 会议纪要（中文） |
标准化 ReAct 循环 + 五种生产设计模式。LangGraph 提供可靠性增强（RFC #6617）。容器化工具执行。开源生态的基石。
Harness-Sandbox 分离架构 —— 行业安全标杆。四级沙箱模型（L0-L3）。托管沙箱供应商生态。安全设计的参考实现。
Skills + Hooks + Modes 架构。七层安全边界，拒绝优先原则。98.4% 确定性基础设施，仅 1.6% 为 AI 调用。基础设施工程的范本。
四层独立安全防线。执行前否决权在工具运行之前即拦截危险操作。执行后消毒则在观测结果进入模型上下文前剥离注入攻击。
执行前风险评估。对危险操作拥有一票否决权。确定性模式匹配，不到 10 微秒完成。拦截批量删除、凭据泄露、提示注入等攻击。
计算器在独立子进程中执行。os.system、__import__、eval 全部被封堵。无论恶意代码执行结果如何，均无法影响父进程。
七步纵深防御流水线，在工具输出进入 LLM 上下文前运作。剥离聊天模板令牌与 ANSI 转义序列。阻断 ReAct 格式注入与命令执行模式。按预算截断。
解析后验证。确认动作指向已注册工具。未知动作触发观测反馈循环 —— LLM 在下一轮迭代中自行纠正。
逐轮记录捕获每一个细节。跨轮差异分析评估 KV-cache 复用率。自包含 HTML 报告可在任意浏览器中打开。成本以人民币核算。
逐轮捕获：提示词、原始/清洗后输出、思考/动作/观测、token 用量、耗时、状态标记（成功 / 工具错误 / 解析错误）。
相邻轮次公共前缀比对。KV-cache 复用率估算（3.5 字符 / token 启发式）。System Prompt 变更检测（金丝雀指标 —— 应始终为零）。
自包含深色/浅色模式报告。内置设计系统，含差异对比面板。逐步骤统计与成本明细。零外部依赖 —— 单个 HTML 文件即完整报告。
按模型定价。Qwen3.6-35B：输入 ¥0.004 / 输出 ¥0.012 每千 token。会话级聚合统计。审计账本支持合规要求（SOC2 CC7.2）。
完整的中文文档体系，覆盖业务需求、功能规格、技术术语、行业对标、共识证据和会议纪要。
业务需求文档 —— ReAct 循环规格、GGUF 推理方案、全量追踪模型、全部 BR/NFR 条目及验收标准
功能规格文档 —— 组件架构、状态机设计、数据流、错误处理矩阵、配置参数、已知限制
技术术语表 —— GGUF、ReAct、KV-Cache、Flash Attention、RoPE、BPE，含定义及与本项目的关联
行业调研报告 —— LangChain 1.0 / OpenAI Agents SDK / Claude Agent 三大生态对比，沙箱安全，Agent 边界划定
共识证据文档 —— 五项跨角色共识、攻击链完整推导、防御方案有效性证据、行业标准引用
会议纪要 —— 跨角色讨论（产品 / 架构 / 开发 / 测试 / 安全）、行动计划、技术决策、目标终态
对项目结构、代码质量、测试覆盖、文档完整性进行系统审查。按优先级分为 P0（阻断）、P1（重要）和 P2（改善）。
agentic/eval/ 和 agentic/log/ 为空目录，缺少 __init__.py 和任何实现代码。要么删除空目录，要么添加占位实现。
0 字节，无任何导出。ObservationSanitizer 无法通过包路径导入。需要添加公开 API 导出。
agentic/ReActDemo 是一个 1,583 行的单体 Python 脚本，无 .py 扩展名。v3.0.0 已模块化重构，此文件应归档或删除。
agentic/intent/（7 个文件，1,299 行）和 tests/test_intent.py（312 行）均未 git add。intent 模块是 v3.0.0 的核心新增功能。
pyproject.toml 中 require_links 指向 llama/**/*.py，但实际代码在 agentic/ 目录下。menard 无法正确追踪代码到文档的映射。
agentic/agent/runner.py（+45 行）和 agentic/protocol/template.py（+9 行）有未提交修改。这些是 intent 模块集成所需的关键变更。
无任何导出或初始化逻辑。viewer.py 虽存在但未被包引用。数据库模块功能不完整。
文档验证脚本放在 doc/ 目录下。应移到 scripts/ 或 tools/ 目录，或合并到 pytest 测试套件中。
.menard/links.toml 未包含 INCIDENTS.md，该文档与代码之间没有过期检测链接。同时缺少 DOC_MAINTENANCE.md 的追踪。
config/exceptions/logging 模块测试较充分；tracer 测试以算法验证为主，缺少集成测试；db/eval 模块为零覆盖。
155 行的 README.md 未反映 v3.0.0 的新增模块（intent/、guard/）。缺少快速开始指南和架构图的链接。
requirements.txt 和 pyproject.toml 各自维护依赖列表。建议以 pyproject.toml 为准，删除 requirements.txt 或改为引用。
pyproject.toml 声明 MIT 协议但仓库根目录没有 LICENSE 文件。开源项目的基本要求。
入口脚本 main.py 没有任何测试覆盖。至少需要一个冒烟测试验证模块组装路径不抛异常。
安全事故文档未纳入 menard 的代码-文档过期检测。如果 guard/ 模块变更，INCIDENTS.md 不会被标记为过期。
v3.0.0 相比 v2.x 有重大架构变更（模块化拆分、intent 模块、guard 模块），但没有变更日志记录。
从 prototype 演进至企业级框架。BRD 定义三层 Phase 架构，共识会议调整优先级 —— 安全项从 Phase 3 紧急前移。
配置管理 (12-Factor)、异常体系 (RecoverableError / FatalError)、LLM 后端协议 + 本地 GGUF 推理、YAML 协议驱动、四级优先级 ReAct 输出解析器、基础工具注册中心。
BRD 原定 Phase 3 的安全项紧急前移：L1 进程沙箱隔离 calculator 执行、Token Budget + CircuitBreaker 拦截 LLM 调用前的预算溢出、Observation 消毒器七步纵深防御阻断提示注入。monolithic ReActDemo 拆分为 14 个 agentic/ 子模块。新增并行意图识别层。
Guardrails 输入护栏、Reflection 死循环检测、Hooks 机制、完整 Eval 评分体系 (六维度轨迹评分)、L2 容器级沙箱、Session 持久化 (SQLite)、OpenTelemetry 分布式追踪。
| 评估维度 | 当前评分 | Phase 2 目标 | Phase 3 目标 |
|---|---|---|---|
| 架构模块化 | 5 / 10 | 6 / 10 | 7 / 10 |
| 工具沙箱安全 | 1 / 10 | 5 / 10 (L1) | 7 / 10 (L2) |
| 提示注入防御 | 2 / 10 | 5 / 10 | 7 / 10 |
| 可观测性 | 6 / 10 | 7 / 10 | 8 / 10 |
| 测试覆盖 | 5 / 10 | 6 / 10 | 7 / 10 |
| 文档完整度 | 7 / 10 | 8 / 10 | 8 / 10 |
| 整体评分 | 4.3 / 10 | 6.2 / 10 | 7.2 / 10 |
修复 5 项 P0 问题，提交 intent/ 模块和测试，补充 guard/__init__.py 导出，清理空模块占位，更新 menard 配置路径，创建 LICENSE 文件。
完成 Agent Mode 枚举和 Eval 基础设施 (EvalScorer + 50 例 Dataset + CI 闸门)。评审全部 Phase 2 交付物，建立六维度量化基线。
Guardrails、Reflection 死循环检测、Hooks 机制、Eval 体系完善、L2 容器沙箱、Session 持久化。目标整体评分 7.2 / 10。
Jetson Orin 实机验证、OpenTelemetry 分布式追踪接入、Prometheus 指标导出、FastAPI REST 服务层。目标整体评分 8.5+。
calculator 工具从 Python eval() 升级为子进程隔离执行。安全评分从 1/10 提升至 5/10。
每次 LLM 调用前验证 token 预算。超限立即熔断，防止上下文窗口溢出导致的不可控行为。
工具输出进入 LLM 上下文前经七步纵深防御流水线消毒。36% 公开 Skill 含注入漏洞，边缘设备无云端兜底。
从纯文本提示升级为结构化 XML。每段独立可验证、可替换。兼容 Qwen2 Chat Template。
每次 LLM 调用和工具执行写入 SQLite 审计日志。SHA-256 哈希链保证完整性。CLI viewer 支持合规审计。
项目架构决策基于对 2025-2026 年 AI Agent 领域三大生态系统的系统调研。以下列出支撑本项目的关键学术论文、行业标准和工程实践依据。
对 679 个规则文件、25,532 条规则进行 5,000+ Agent 运行实验。核心结论：否定约束（"禁止 X"）比正向指导（"请做 Y"）对 Agent 输出质量的提升杠杆更高。"最小变更原则"经学术验证——每个变更仅引入一个新的否定约束。
学术界正式定义 Agent Harness 的 11 个组件责任。核心结论："Harness 质量决定可部署性，胜过模型质量"——即基础设施工程比模型选择更关键。本项目 98.4% 确定性基础设施的设计理念直接来源于此。
提出 AI Agent 的可部署性由 Harness 质量决定而非模型能力。定义了 Agent 基础设施的评估框架，本项目的六维度成熟度评分体系参考了此框架。
Python 安全社区长期共识：CPython 中沙箱逃逸为已知不可解问题。官方建议使用 OS 级隔离替代语言级沙箱。这是本项目将 calculator 从 eval() 升级为子进程隔离的核心依据。
对公开 AGENTS.md / CLAUDE.md 规则文件的大规模代码嗅觉分析。发现 36% 的公开 Skill 文件存在 prompt injection 漏洞——这是本项目 Observation 消毒器设计的直接触发依据。
定义 Agent 架构五个核心生产设计模式：单 Agent + ReAct 循环、多 Agent 协作、人机协同、RAG 增强、工具编排。本项目的 ReAct 状态机设计直接遵循模式一。
定义生产级 Agent 循环的五个安全出口条件：max_turns、token_budget、timeout、circuit_breaker、human_escalation。本项目的 Token Budget + CircuitBreaker + max_steps 均源于此。
提出 Agent 可靠性的关键增强：确定性重试、幂等工具调用、结构化日志、检查点恢复。本项目对 ReAct 循环的错误恢复路径设计参考了此规范。
提出六维度 Agent 评估框架：准确性、可靠性、安全性、效率、可解释性、鲁棒性。引入 Trajectory Score、BFCL v3、τ-bench 等量化指标。本项目的 Eval 基础设施规划以此为基础。
L0 进程内隔离（仅限单用户受信环境）→ L1 子进程沙箱 → L2 容器级沙箱 (gVisor/Seatbelt) → L3 密封 VM (Nitro Enclaves)。本项目当前 L1，Phase 3 目标 L2。
每一层都不可信——模型输出不可信、工具输出不可信、用户输入不可信。与 deny-first 原则一起构成本项目纵深防御安全体系的理论基础。
Anthropic 内部实践揭示了三层架构（Intent → Plan → Execute）、三模式分离（Explore/Plan/Code）、三注入点（assemble/model/execute）以及九类 Skills 体系。本项目的 intent/ 模块设计受 yoloClassifier 两阶段模式启发。
| 范式 | 来源 | 理由 | 实施难度 |
|---|---|---|---|
| 否定约束优先 | arXiv 2604.11088 (学术验证) | 提高 Agent 输出质量的最高杠杆手段 | 低 |
| Harness-Sandbox 分离 | OpenAI Agents SDK (行业标杆) | 信任边界清晰，安全模型可审计 | 中 |
| Deny-First 权限模型 | Anthropic Claude Code | 宽泛 deny 始终覆盖窄 allow，不可逆回退 | 低 |
| 结构化 Prompt 工程 | Anthropic Skills Blog + arXiv 2604.11088 | XML 十段结构，每段独立可验证可替换 | 中 |
| OS 级沙箱隔离 | PEP 551 (Rejected) + OpenAI/E2B | CPython 语言级沙箱为不可解问题 | 中 |
| 全链路可观测性 | JSONL 转录 + 五层压缩 (Anthropic) | 审计优于查询，非破坏性链路修补 | 中 |
| 并行意图分析 | yoloClassifier 两阶段 + 本项目创新 | 确定性规则 <1μs + LLM fallback 按需触发 | 中 |