alzenkastrati/sgrx

# SGRX **源码图研究浏览器（Source Graph Research eXplorer）** [](https://github.com/alzenkastrati/sgrx/actions/workflows/ci.yml) [](https://github.com/alzenkastrati/sgrx/actions/workflows/integration.yml) [](LICENSE) 🌐 [德语](README.de.md) SGRX 以便携的 Agent Skill 和中立于环境的 CLI 工作流形式发布。它研究**软件应该如何构建**，帮助理解**现有代码的实际工作原理**，追踪依赖关系，比较基准仓库中的实践，并创建有证据支持的实现和现代化计划。相同的 skill 可在兼容的 AI agent、编辑器扩展和内部开发工具中通用。 像平常一样提问。SGRX 会找到相关的 AI 论文和精确的 GitHub 实现，研究它们的源代码，并返回一份带有证据的实用计划。 当前版本：**0.5.1** ## 我可以问什么？ ``` $sgrx Research the best way to build a local voice assistant. Compare current papers and real GitHub projects, then give me a step-by-step implementation plan. ``` ``` $sgrx Show me how the zod version in this project validates email addresses. Trace our call into the exact library source and explain what could break. ``` ### 示例：更快地理解遗留代码库 将此提示词提供给任何已连接到 SGRX CLI 的 AI 助手，无论它使用的是什么环境： ``` Use SGRX to analyze this repository in standard mode. The goal is to help a new developer understand the codebase quickly. Create a short Markdown report that identifies: 1. the most important modules and their responsibilities; 2. the main execution flows from entry points to business logic; 3. important external dependencies and how they are used; 4. critical or hard-to-maintain areas; and 5. the three most useful next steps for testing or modernization. Support each finding with file and line references. Do not change the code. ``` 这有助于减少在进行更改前理解大型、长期运行的系统所需的时间。 ### 选择合适的工作流 | 目标 | 命令 | |---|---| | 检查本地工具是否可用 | `doctor` | | 获取精确的依赖版本 | `resolve` | | 构建隔离的源码索引 | `index` | | 将应用程序的用法追踪到依赖源码中 | `analyze` | | 从基准仓库迁移实践 | `audit` | | 比较两个依赖版本 | `compare` | | 对论文和仓库进行排名并创建构建计划 | `research` | | 重新渲染已保存的结果 | `report` | 使用 `--dry-run` 检查命令和输出范围，而无需运行研究工具。当其他工具需要处理结果时，使用 `--json`。 ## 工作原理 ``` flowchart LR A["You ask a question"] --> B["SGRX researches"] B --> C["Current AI papers"] B --> D["Exact repository versions"] C --> E["Source and knowledge graphs"] D --> E E --> F["Evidence-backed answer"] F --> G["Step-by-step build plan"] ``` SGRX 协调三个工具： | 工具 | 简单任务 | |---|---| | **OpenSrc** | 获取精确的源代码版本。 | | **Graphify** | 绘制架构和关系。 | | **GitNexus** | 追踪函数、调用者、流程和变更风险。 | 这有助于开发人员和 AI 助手避免凭文档猜测、检查错误版本或向模型发送过多源代码。 ## 为什么它能使用更少的 token SGRX 会在模型读取证据**之前**将其缩小范围： - 它对论文和仓库进行排名，而不是分析每个候选项。 - `quick` 和 `standard` 模式构建仅包含代码的快照。 - 图查询返回相关的文件、函数和关系——而不是整个仓库。 - 保存的索引和检查点避免重复已完成的研究。 - token 预算限制了进入语义分析的材料数量。 在一次 SGRX 自我研究中，经过过滤后，所选语料库使用了 **5,499 个 Graphify 输入 token**。这是一个观察到的工作流示例，不保证节省量，也不是对总模型/API 使用量的测量。实际结果取决于问题、仓库和研究模式。 ## 安装 SGRX 遵循开放的 Agent Skills 格式：每个兼容的客户端都会加载相同的 `skills/sgrx/SKILL.md` 和捆绑资源。`agents/openai.yaml` 文件仅添加了 Codex UI 元数据；它不是白名单，其他客户端会安全地忽略它。 Skill 来源：https://github.com/alzenkastrati/sgrx/tree/main/skills/sgrx ### 为所有受支持的 agent 安装 在克隆的代码检出中，运行不带 `--target` 的便携式安装程序。它会安装到所有目标： ``` # Windows py -3 skills/sgrx/scripts/install_skill.py # macOS 和 Linux python3 skills/sgrx/scripts/install_skill.py ``` 预览目标位置而不复制任何内容： ``` py -3 skills/sgrx/scripts/install_skill.py --dry-run ``` | 安装路径 | Agent 客户端 | |---|---| | `~/.agents/skills/sgrx` | Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf, Amp | | `~/.codex/skills/sgrx` | Codex | | `~/.claude/skills/sgrx` | Claude Code | | `~/.cline/skills/sgrx` | Cline | 通过重复使用带 `shared`、`codex`、`claude` 或 `cline` 的 `--target` 来仅安装选定目标。现有安装会在原处更新，不相关的 skill 保持不变。 ### 直接使用 CLI Agent 和开发工具也可以直接调用中立于环境的 CLI。在 Windows 上使用 `py -3`，这样 Microsoft Store 的 `python` 别名就不会拦截该命令： ``` # Windows py -3 skills/sgrx/scripts/sgrx.py doctor py -3 skills/sgrx/scripts/sgrx.py --help # macOS 和 Linux python3 skills/sgrx/scripts/sgrx.py doctor python3 skills/sgrx/scripts/sgrx.py --help ``` 将 CLI 连接到您已经在使用的 agent 或开发工作流，然后使用上面的提示词作为任务契约。 例如，追踪本项目如何使用已安装的 npm 依赖项： ``` py -3 skills/sgrx/scripts/sgrx.py analyze --registry npm --package zod --project . --question "How does this project call zod, and what implementation path handles those calls?" ``` ### 审计来自其他仓库的实践 当其他仓库是基准或工作流目录而不是应用程序依赖项时，使用 `audit`： ``` py -3 skills/sgrx/scripts/sgrx.py audit --registry github --benchmark owner/workflow-catalog --ref 0123456789abcdef0123456789abcdef01234567 --project . --question "Which workflow and validation practices should this project adopt?" ``` 审计模式将基准和使用者索引保持分开，默认排除图像和媒体，并在达到文件或 token 预算上限时于 Graphify 运行前停止。它分别查询生命周期、上下文、分发、验证和可靠性，然后写入证据映射、经过验证的报告、可重用的检查点，以及一个紧凑的 `RUN_MANIFEST.md` 交接文件。 通过重复使用带有仓库相对路径的文件或目录的 `--include-path` 或 `--exclude-path` 来缩小大型基准的范围，而不增加预算，例如 `--include-path reports --include-path development-workflows --exclude-path reports/archive`。 审计的默认设置是有意保持保守的：`code-docs` 配置文件会选择代码、文档和论文；图像和媒体保持排除状态；最多有 300 个文件和估计 300,000 个 token 可能进入 Graphify。如果在超出限制时，预检会报告 `NARROW_REQUIRED` 并在提取前停止。选择 `--corpus-profile code` 仅获取源代码，或者在确实需要视觉和媒体证据时选择 `--corpus-profile full`。 每次完成的审计都会在 `.sgrx` 下写入一个隔离的、可恢复的证据包：解析、语料库计划、索引清单、分面查询、索引上下文、证据映射、验证结果、`REPORT.md`、`RUN_MANIFEST.md` 和 `events.jsonl`。重复相同的请求会重用匹配的索引和查询检查点。 ## 环境要求 - Python 3.10+ - Node.js 24+ - Git - OpenSrc 0.7.3+ - Graphify 0.9.12+ - GitNexus 1.6.5+ 安装这三个研究工具： ``` npm install --global opensrc@0.7.3 gitnexus@1.6.5 # Windows py -3 -m pip install graphifyy==0.9.12 # macOS 和 Linux python3 -m pip install graphifyy==0.9.12 ``` 检查一切是否就绪： ``` # Windows py -3 skills/sgrx/scripts/sgrx.py doctor # macOS 和 Linux python3 skills/sgrx/scripts/sgrx.py doctor ``` ## 我会得到什么？ - 针对原始问题的简短回答。 - 实际检查过的论文和仓库版本。 - 架构、文件和函数之间基于图的支持链接。 - 细分为小型工作包的详细实施计划。 - 对事实、推论和未解答问题的清晰标注。 - 可见的验证状态和用于继续运行的紧凑交接清单。 SGRX 将证据标记为： - `EXTRACTED` — 直接由源代码或文档支持。 - `INFERRED` — 合理的推论，但未经证实的运行时路径。 - `AMBIGUOUS` — 需要更多证据。 ## 默认安全 下载的仓库被视为不受信任的数据。SGRX 不会运行其代码、测试、构建、安装脚本或指令。它将项目保持隔离，并且不修改获取的源代码。 SGRX 默认进行分析。只有在您明确要求实施时，它才会更改您的应用程序。 ## 恢复与故障排除 - 中断后再次运行相同的研究请求；已完成的检查点会被重用。 - 审计和分析运行会在其隔离的 `.sgrx` 范围下写入持久的解析、语料库、索引、查询、证据、验证、报告和交接工件。 - 在 Windows 上，未完成的长路径检出会在启用了 `core.longpaths` 的隔离短缓存中重试。全局 Git 设置不会被更改。 - 纯论文或文档图需要受支持的 Graphify 语义后端。如果没有，SGRX 会将该论文图报告为 `PARTIAL`，而不是凭空捏造关系。 - 在 Windows 上，SGRX 会将 GitNexus 通用的缺失 FTS 警告分类为不可用的 FTS 运行时路径，并且不会重新生成完整的索引。关键字搜索将保持明显的降级状态，而 Graphify 和符号化 GitNexus 的上下文/影响查询仍然可用。在其他平台上，确实缺失的 FTS 索引会在隔离快照内被精准重建一次。 - Graphify 的零节点文件、提取问题和跨块 ID 冲突属于结构化的健康检查失败，不能再作为健康状态通过验证门禁。 - CLI 本身不会静默浏览网页。Codex 会发现当前的论文和仓库；本地 CLI 会对记录的候选项进行排名和分析。 ## 更多详情 - [研究模式](skills/sgrx/references/research-mode.md) - [工具路由](skills/sgrx/references/tool-routing.md) - [证据模型](skills/sgrx/references/evidence-model.md) - [输出模式](skills/sgrx/references/report-schema.md) - [示例](skills/sgrx/references/examples.md) - [更新日志](CHANGELOG.md) - [贡献](CONTRIBUTING.md) - [安全政策](SECURITY.md) SGRX 基于 [MIT 许可证](LICENSE) 发布。

标签：AI智能体, MITM代理, SOC Prime, 云安全监控, 代码分析, 凭证管理, 开发工具, 源码图谱, 网络安全研究, 逆向工具, 静态分析