Stability Analysis Agent
一个面向 App 稳定性工程的开源领域 Agent：以受治理的 Agent Harness 为运行底座，借鉴开源 AI 编程工具在上下文管理、多轮调查、工具调用、权限控制、检查点恢复与验证闭环等方面的能力，将 Crash、ANR、OOM 等事故材料转化为可审查、可验证的根因分析与代码修复结果。
简体中文 | English
为什么稳定性问题需要专用 Agent
稳定性日志通常噪音大、地址多、上下文分散，通用 AI 编程工具往往需要人工整理后才能分析；专用 Agent 则负责把这些事故材料整理成可用的诊断证据。
| 稳定性问题 | 通用 AI 编程工具的困难 | 当前 Agent 提供的能力 |
|---|---|---|
| 日志噪音大，关键线程和调用栈不明显 | 手工筛选真正相关的崩溃信息 | 解析日志结构，识别异常类型、崩溃线程和关键调用栈 |
| Native 堆栈只有内存地址 | 无法根据地址直接判断函数和源码位置 | 结合匹配的符号文件完成地址符号化和源码定位 |
| 崩溃位置不一定是根因 | 容易根据表面堆栈生成猜测 | 结合故障地址、寄存器、调用关系等信息构建 Crash 证据链 |
| 日志、符号文件和源码彼此分离 | 需要手工整理和粘贴上下文 | 自动关联事故材料，提取相关源码上下文 |
| 同类问题反复发生 | 历史分析结果难以复用 | 通过规则和向量数据库沉淀经验，检索相似案例辅助分析 |
如何安装
推荐安装
要求 Python 3.9+，推荐 Python 3.10–3.12。默认安装包含完整的相似案例检索能力。
pip install stability-analysis-agent
中国大陆网络环境可以为 pip 命令追加镜像参数。安装失败、Python 版本、SSL 和 ML 依赖问题，见 安装与依赖排错。
快速开始
运行内置 Demo
克隆仓库后启动交互式 CLI。选择“快速开始修复（推荐）”，按菜单提示配置大模型和堆栈地址解析工具，再输入内置 Demo 的日志、符号库和源码路径。这个流程会完成日志解析、符号化、证据链诊断、源码定位、AI 分析和源码修复：
git clone https://github.com/baidu-maps/stability-analysis-agent.git
cd stability-analysis-agent
sa-agent
启动后会看到一级菜单，首次体验只需关注以下选项：
请选择要执行的操作
❯ 1) 快速开始修复（推荐）
2) 设置
3) 帮助
q) 退出
首次使用时按下面的路径操作：
1) 快速开始修复（推荐）
→ 未配置模型时，按提示进入“大模型与路由设置”
→ 未检测到符号化工具时，按提示进入“配置堆栈地址解析工具”
→ 输入 Crash 日志、符号库目录和源码目录
→ 确认执行计划，开始完整分析和源码修复
内置 Demo 使用以下路径：
Crash 日志：examples/crash_cases/demo_basic/logs/mac/NullPtr_SIGSEGV_2026-04-08_10-43-08.crash
符号库目录：examples/crash_cases/demo_basic/lib/mac
源码目录：examples/crash_cases/demo_basic/code_dir
查看最终结果
Demo 中的空指针 Crash 会被定位并修复，源码从：
int* p = nullptr;
*p = 42;
修改为：
int* p = nullptr;
if (p != nullptr) {
*p = 42;
} else {
std::cerr << "错误: 尝试解引用空指针" << std::endl;
}
原文件会保留备份，代码修改可以通过 git diff 审查。
同一次运行还会生成面向开发者阅读的最终报告：
reports/<timestamp>/final_output.md
报告主要回答：
- 发生了什么问题
- 根因是什么
- 为什么可以这样判断
- 哪些源码需要修改
- 采取了什么修复措施
- 还需要补充哪些材料
报告主要包含：
故障基本信息：异常类型、信号、崩溃线程、平台和崩溃模块三级根因定位：从问题类别、触发机制到具体根因证据链：故障地址、符号化栈帧、源码证据、调用链和线程信息置信度与证据等级：当前判断的可信程度和依据责任归属：问题对应的模块、函数或代码责任范围修复建议：代码级修复和必要的防御性措施需补充材料：当前判断仍需要的日志、源码或运行信息总结：问题原因、修复结果和后续建议
支持的平台与能力边界
当前内置 Crash 分析链路覆盖 iOS、macOS、Android、鸿蒙、Linux 和 Windows，统一完成日志解析、堆栈符号化、证据分析、源码上下文提取和 AI 修复。不同平台通过对应的日志解析器和符号化工具接入，具体格式见 Crash 日志格式说明。
Agent 的核心边界不在于“能否读取某个平台的日志”，而在于是否存在可用的日志格式适配器、符号化工具和分析 Workflow。缺少这些适配时，第三方可以通过 Tool、Workflow 或 Skill 扩展，而不需要修改核心执行框架。
ANR、OOM、Jank、JavaScript/ArkTS 等问题已经具备专项分析组件；具体能力和扩展方式见 诊断工具文档、Tool System 扩展指南 和 Skill System。
遇到问题怎么办
- 使用问题、Bug 和功能建议：提交 GitHub Issue。
- 安装、CLI 使用和扩展问题：先看 安装与依赖排错、CLI 指南 和 Tool System 扩展指南。
- 安全漏洞：请按 安全策略 私下联系维护者，不要公开提交细节。
- 提交 Issue 时请附上版本、操作系统、运行命令、日志格式和脱敏后的报告，不要上传密钥或未脱敏的线上数据。
维护者：@liuhong996 · hong9988.dev@gmail.com
项目版本和重要变更见 GitHub Releases 与 CHANGELOG.md。项目采用 Apache-2.0，贡献流程和 DCO 要求见 CONTRIBUTING.md。
欢迎提交 Issue、改进文档和代码。
文档地图
| 想了解什么 | 文档 |
|---|---|
| 安装失败、依赖和环境问题 | docs/cli/INSTALL_TROUBLESHOOTING.md |
| 常见 CLI 用法 | docs/cli/CLI_GUIDE.md |
| 全部 CLI 参数 | docs/cli/CLI_COMMANDS_REFERENCE.md |
| 使用本地 Web 面板 | docs/cli/WEB_UI_GUIDE.md |
| Crash 日志格式 | docs/tools/CRASH_LOG_FORMATS.md |
| C++、ANR、OOM、JS、Jank 等诊断能力 | docs/tools/ |
| Skill 和扩展机制 | docs/skills/README.md |
| 系统架构 | docs/architecture/README.md |
| Agent Runtime、Harness 生命周期和安全边界 | AGENT_RUNTIME_LIFECYCLE.md · HARNESS_MIGRATION.md |
| 多轮上下文调查和请求协议 | CONTEXT_LOOP_CONTRACT.md |
| Daemon、Run API 和事件流 | DAEMON_SERVER_GUIDE.md |
| 修复后的构建、测试和验证闭环 | VERIFICATION_PROVIDERS.md |
| 测试、回归与 Harness 评测 | docs/testing/README.md · EVALUATION_MATRIX.md |
| 后续规划 | docs/ROADMAP.md |
| 许可证与贡献协议 | LICENSE · CONTRIBUTING.md |
从哪里继续
- 第一次使用：复制上面的 Demo 命令。
- 已有 Crash 日志：参考内置 Demo 的参数，替换为自己的日志、符号库和源码路径。
- 想接入团队流程：阅读 Skill System 和 CLI 指南。
- 想理解实现方式：阅读 系统架构总览。
如果这个项目帮助你定位或修复过一次稳定性问题，欢迎在 GitHub 点个 Star。你的 Star 会帮助更多开发者发现这个项目，也会为后续的平台适配和能力建设提供反馈。
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file stability_analysis_agent-1.3.6.tar.gz.
File metadata
- Download URL: stability_analysis_agent-1.3.6.tar.gz
- Upload date:
- Size: 1.6 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.9.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b18a6bdf2d6ac3cd0288e0197e300274e8d3ec65e400ca5a42cd4fd80363e839
|
|
| MD5 |
5832fd4958c14b949aff2ae24adc990a
|
|
| BLAKE2b-256 |
26fc671ffe97ee33322817d7a2f1e2af912700bb607f63744e7c793fb2e13e66
|
File details
Details for the file stability_analysis_agent-1.3.6-py3-none-any.whl.
File metadata
- Download URL: stability_analysis_agent-1.3.6-py3-none-any.whl
- Upload date:
- Size: 968.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.9.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f693e1f52e29838b46f8107bcbaaa0706c839a068677301241339dd9106addb8
|
|
| MD5 |
943d6c62516da408afc95aeaa46938a9
|
|
| BLAKE2b-256 |
10c7266a4d748410545c1d07bf4d5660505fb4a7b9173dcb886c3731356db62c
|
