*类别：面向 AI-agent 工程的故障到修复智能分析。* ## 快速开始 **如果你不熟悉终端命令，请将此内容粘贴到你的 AI 编码 agent 中：** **安装：** ``` git clone https://github.com/hermes6941/Rootlyze.git cd Rootlyze python3 -m pip install -e . rootlyze version ``` **30秒入门：** ``` # 查看 Rootlyze 能做什么 rootlyze examples # 扫描单个 log 文件 rootlyze analyze failed_agent.log # 扫描 logs 文件夹 rootlyze analyze ./logs/ # 直接粘贴 failure 文本 rootlyze analyze "agent kept retrying the same tool call" # 获取您的 proofpack（从 ./rootlyze_reports/ 自动检测） rootlyze proofpack RZ-REPORT-xxxx ``` 无需账户。无需 API 配置。优先在本地运行。 ### 高级用法 ``` # 面向高级用户的 Explicit flags rootlyze analyze --file agent.log --local --out ./reports --json rootlyze analyze --folder ./logs --local --out ./reports rootlyze analyze --file agent.log --hosted # use hosted API (daily quota) rootlyze proofpack RZ-REPORT-xxxx --local --dir ./reports --json rootlyze proofpack RZ-REPORT-xxxx --hosted --json ``` ### 托管产品与账户 匿名用户每天可通过托管 API 获得 **3 次分析机会**。免费账户每天可获得 **20 次**。 | | 匿名 | 免费账户 | |--|-----------|--------------| | 每日限制 | 3 | 20 | | 需要注册 | 否 | 是 | | 托管 CLI 访问 | 是 | 是（已认证） | ``` rootlyze analyze --file agent.log --hosted # uses quota rootlyze signup # sign up for 20/day rootlyze login ``` ## 团队为何使用 Rootlyze - 通过有证据支撑的输出，更快地诊断重复出现的 agent 故障 - 将确定性诊断与标记的兜底分诊区分开来 - 生成可共享的 proofpack，用于 GitHub Issues、PR 和事故记录 - 通过反馈和解决追踪形成闭环 - 避免将生产日志复制到随机的调试工作流中 ## Rootlyze 能帮助解决的故障类型 Rootlyze 专为工具调用系统、agentic 工作流、RAG pipeline 和托管 LLM 应用中常见的 AI-agent 故障模式而构建。 示例包括： * 工具超时和失败的工具调用 * 重试循环和重复的 agent 操作 * Provider、API key、配额和身份验证失败 * 上下文耗尽和 token 预算失败 * 错误的检索、缺失的证据以及 RAG grounding 失败 * 工具 schema、function-call 和 API 契约不匹配 * 幻觉或不支持的 agent 操作 * 失控调用或反复重试导致的成本激增 * 跨 agent 步骤的状态、内存或交接失败 * 证据不足的情况，此时最安全的答案是避免过度断言 Rootlyze 报告带有来源标记并有证据支撑。如果无法确信地诊断出故障，报告会引导进行下一步工程检查，而不是假装确定。 ## 为什么不直接问 LLM？ 通用的 LLM 调试可能会有所帮助，但它通常将猜测与事实混为一谈。Rootlyze 围绕更严格的“故障到修复”工作流构建：捕获失败的运行，标记诊断来源（确定性或兜底），显示证据信号，生成可共享的 proofpack，并通过反馈和解决追踪形成闭环。 ## Rootlyze 的工作原理 1. **粘贴或扫描失败的运行、日志、trace、文件或文件夹** —— 从你已有的证据开始。 2. **Rootlyze 标记故障家族** —— 超时、重试循环、格式错误的工具输出、错误检索、成本激增、静默失败或其他受支持的模式。 3. **Rootlyze 展示证据信号** —— 触发诊断的确切信号。 4. **Rootlyze 给出下一步检查建议** —— 优先检查什么，而不是盲目猜测整个 trace。 5. **Rootlyze 提供预防规则** —— 如何降低相同故障再次发生的概率。 6. **你的 AI 编码 agent 或工程师遵循 proofpack** —— 应用修复、添加防护或验证可疑的故障路径。 7. **经验证的修复转化为团队知识** —— 保留故障模式、证据、修复方法和预防规则，供未来运行参考。 ## Rootlyze 的产出 | 输出 | 描述 | |--------|-------------| | 诊断 | 匹配到的故障家族及其置信度 | | 证据信号 | 触发匹配的特定信号 | | 来源类型 | `DETERMINISTIC_KFR`、`LLM_FALLBACK`、`HARD_NEGATIVE` 或 `SAFE_REJECTION` | | 预防指南 | 减少复发风险的步骤 | | 安全的后续操作 | 下一步该检查什么 | | Proofpack | 结构化的可共享报告（JSON、Markdown、GitHub Issue、PR Comment） | | 报告检索 | 账户用户可以通过报告 ID 获取 proofpack | | 反馈闭环 | 账户用户可以提交解决状态 | ## Proofpack 预览 ``` { "report_id": "RZ-REPORT-19f4c1622005DC", "status": "deterministic_kfr", "source_type": "DETERMINISTIC_KFR", "proof_pack_version": "v0.1", "failure_family": "tool_execution", "failure_class": "Tool execution timeout or error", "matched_signals": [ "tool call", "deadline exceeded" ], "signal_count": 2, "confidence": { "level": "medium", "basis": "Based on 2 matched signals from deterministic_kfr.", }, "safe_next_action": "Review the tool\u0027s timeout configuration and error handling logic.", "prevention_rule": { "rule_type": "timeout", "description": "Add client-side tool call timeout and error handling for all tool invocations." }, "proof_pack_id": "RZ-PROOF-EA8BA3E5", "generated_at": "2026-07-10T12:59:29Z" } ``` Proofpack 包含诊断、证据信号、预防指南、安全的后续操作以及来源类型。导出格式：JSON (CLI)、Markdown、GitHub Issue 格式和 PR Comment 格式。 查看示例 proofpack：[docs/examples/proofpack-gallery.md](docs/examples/proofpack-gallery.md)。 ## 设计上的诚实 Rootlyze 旨在将有证据支撑的诊断与不确定的分诊区分开来。 * 确定性结果标记为 `source_type: DETERMINISTIC_KFR` * 兜底分诊标记为 `source_type: LLM_FALLBACK` * 非故障输入标记为 `source_type: HARD_NEGATIVE` 或 `SAFE_REJECTION` * Rootlyze 会优先尝试确定性诊断。如果输入未被识别且兜底机制可用，Rootlyze 将返回标记的兜底分诊。如果输入缺乏足够的故障证据，Rootlyze 将返回专业的“证据不足”或“安全拒绝” proofpack，而不是返回未知结果。 * 报告包含证据信号和安全的后续操作 * Rootlyze 不会声称每种故障都能被诊断出来 * 当置信度有限时，报告会引导进行下一步工程检查，而不是假装确定 ## 托管 API 在公测期间，Rootlyze 连接到位于 `https://rootlyze.aicertreview.com` 的远程托管 API。服务器实现是单独部署的。完整 API 参考：[docs/api-reference.md](docs/api-reference.md)。 ## 信任边界 - **本地扫描模式：** `rootlyze analyze ` 在本地运行，并将 proofpack 写入 `./rootlyze_reports/`。无需账户、API 调用或配额。内容不会离开你的机器。 - **托管模式：** `rootlyze analyze --file agent.log --hosted` 将内容发送到 Rootlyze API。适用托管配额限制（匿名每日 3 次，免费账户每日 20 次）。当触发兜底机制时，经过脱敏处理的输入可能会发送给 provider。原始输入不会被存储。使用数据（计数、报告 ID）会被存储。 - **不使用用户数据进行训练。** 完整隐私政策：[PRIVACY.md](PRIVACY.md) ## Rootlyze 不是什么 - **不是仪表盘** —— 没有指标、trace 或监控 UI - **并非全局无 LLM** —— 当确定性匹配失败时，托管模式会使用标记的兜底机制 - **不仅限托管** —— Rootlyze 支持本地优先扫描和可选的托管分析 - **不保证**能检测到每一次故障 - **未达到企业/SOC2/SSO 标准** —— 团队功能尚不完善 - **不是完全开源的生产智能** —— 完整的智能层是私有的；此 repo 包含一个本地入门包 ## 公开仓库边界 本 repo 包含 **托管 CLI 客户端**、文档、示例、proofpack 样本，以及用于常见 AI-agent 故障家族的 **本地入门智能包**（`rootlyze_demo/core_local_pack.json`）。 它 **不** 包含 Rootlyze 完整的生产智能层。托管的 Rootlyze 服务使用私有的故障到修复智能：确切的生产模式、经过调优的评分、兜底编排、预防模板和学习系统均不包含在此 repo 中。 ## 命令参考 | 初学者命令 | 描述 | |-----------------|-------------| | `rootlyze analyze ` | 在本地扫描失败的 agent 日志文件 | | `rootlyze analyze ` | 在本地扫描包含日志的文件夹 | | `rootlyze analyze ""` | 粘贴失败文本并在本地进行扫描 | | `rootlyze proofpack RZ-REPORT-xxxx` | 打开本地 proofpack，如果未找到则回退至托管服务 | | `rootlyze examples` | 展示初学者示例 | | `rootlyze help` | 展示完整帮助信息 | | `rootlyze status` | 检查 CLI 健康状况和本地扫描可用性 | | 高级 / 托管命令 | 描述 | |--------------------------|-------------| | `rootlyze analyze --file agent.log --hosted` | 使用托管 API；适用每日配额 | | `rootlyze signup` | 创建免费账户 | | `rootlyze login` | 登录账户 | | `rootlyze quota` | 展示每日使用量/配额 | | `rootlyze proofpack RZ-REPORT-xxxx --hosted --json` | 以 JSON 格式获取托管 proofpack | | `rootlyze doctor` | 检查 CLI 健康状况和配置 | | `rootlyze version` | 展示版本号 | | `rootlyze config set api_url ` | 更改 API endpoint | ## 有限的 Demo 评估器 [`rootlyze_demo/`](rootlyze_demo/) 目录包含： * **`core_local_pack.json`** —— 包含 13 个常见 AI-agent 故障家族的本地入门智能包。在运行 `rootlyze analyze ` 时默认使用。 * **`local_kfr_engine.py`** —— 本地确定性 KFR 引擎，根据入门包对输入进行扫描。 * **`demo_evaluator.py`** —— 一个有限的合成 demo 评估器，用于审查输出形态。 ``` # 使用默认的本地扫描（starter pack） rootlyze analyze agent.log # 直接使用有限的 demo evaluator echo "Agent tool call timed out after 30 seconds" | python3 rootlyze_demo/demo_evaluator.py ``` 入门包和 demo 评估器 **不是** 完整的托管产品知识库。请参阅 [docs/demo-evaluator.md](docs/demo-evaluator.md)。 本地入门包对于常见的 AI-agent 故障模式很有用，并会在本地写入 proofpack。它不包含 Rootlyze 完整的私有生产智能层。托管模式（`rootlyze analyze --file agent.log --hosted`）使用 Rootlyze 更大的私有生产智能层，并遵循托管配额/账户行为。 ## 文档 * [快速开始](docs/quickstart.md) * [API 参考](docs/api-reference.md) * [命令参考](docs/command-reference.md) * [Proofpack](docs/proofpacks.md) * [信任边界](docs/trust-boundaries.md) * [Demo 评估器](docs/demo-evaluator.md) * [公开与私有边界](docs/public-private-boundary.md) * [局限性](docs/limitations.md) * [示例](docs/examples.md) ## 许可证 MIT。请参阅 [LICENSE](LICENSE)。 ## 安全 请参阅 [SECURITY.md](SECURITY.md)。 ## 隐私 请参阅 [PRIVACY.md](PRIVACY.md)。

标签：AI代理, Homebrew安装, SOC Prime, 人工智能, 开发工具, 故障排查, 文档结构分析, 用户模式Hook绕过, 逆向工具