RepoGrammar

将代码仓库的规范提供给编程 Agent——而不是另一堆搜索结果。

本地优先、基于源码的模式上下文，具有受限的读取计划和可靠的弃权机制。

快速开始 · 文档 · 局限性 · 更新日志

编程 Agent 反复读取相同的文件，以重新发现代码仓库是如何实现路由、测试夹具、模型和数据访问的。RepoGrammar 在 Agent 广泛阅读源码之前，将这些重复的实现转化为一张包含**模式家族**的紧凑映射图。 当仓库中的证据充足时，Agent 会获得具有代表性的示例、基于源码的元数据以及经过哈希校验的读取计划。当证据不足时，RepoGrammar 会返回一个带类型的 `UNKNOWN` 并附带恢复操作，而不是用一个看似合理的猜测来填补空白。 ``` repository source │ ▼ local evidence index ──► compatible pattern families ──► bounded read plan │ │ └── freshness checks └──► UNKNOWN / PARTIAL_CONTEXT + recovery ``` ## 为什么选择 RepoGrammar | 模式感知 | 证据门控 | Agent 友好 | | --- | --- | --- | | 发现该仓库重复实现某一功能角色的方式，而不仅仅是字符串出现的位置。 | 将溯源、新鲜度、未解析的语义和异常信息附加到每一个声明上。 | 通过一个模式优先的 CLI 和一个只读的 MCP 工具 `repogrammar_context` 提供紧凑的上下文。 | RepoGrammar 是对文本搜索、语义搜索和符号图的补充。那些工具用于定位代码；而 RepoGrammar 添加了一个仓库本地契约，用于决定哪些重复的实现是兼容的、还有哪些需要继续阅读，以及什么时候必须放弃作答。 ## 快速开始 当前的源码标识为 `0.4.0`。仅凭清单或 Git 标签并不能证明已提供公开构件，因此请先验证确切的 npm 包、dist-tags 以及不可变的 GitHub 资产： ``` npm view @sioyooo/repogrammar@0.4.0 version npm view @sioyooo/repogrammar dist-tags --json curl -fsSI https://github.com/SioYooo/RepoGrammar/releases/download/v0.4.0/install.sh.sha256 npx --yes --package @sioyooo/repogrammar@0.4.0 \ repogrammar version ``` 当确切版本存在且 dist-tags 为 `latest=0.4.0` 和 `preview=0.2.0-preview.0` 时，继续操作。然后设置一个仓库： ``` npx --yes --package @sioyooo/repogrammar@0.4.0 \ repogrammar setup \ --project /path/to/your/repo --target auto ``` `setup` 会审查一个计划，安全地接入检测到的 Codex 或 Claude Code 集成，初始化本地索引，启动该仓库的自动同步 daemon，并验证只读的 MCP 接口。外部的或已发生漂移的 Agent 配置将被保留，而不是被覆盖。 询问一个仓库规范，然后根据返回的模式家族检查建议的实现： ``` npx --yes --package @sioyooo/repogrammar@0.4.0 \ repogrammar find "FastAPI route" \ --project /path/to/your/repo --mode compact --verbosity minimal npx --yes --package @sioyooo/repogrammar@0.4.0 \ repogrammar check "path/to/file.py:LINE" \ --project /path/to/your/repo --mode compact --verbosity minimal ``` 在进行广泛的源码检查之前，先使用返回的 `read_plan`。成功的 `check` 是一个**静态对齐证书**；它特意保留了 `runtime_equivalence: UNKNOWN`。 对于 CI 或确定性的一次性索引，请添加 `--no-autosync`。如需永久的管理命令、源码构建、清理以及确切的平台要求，请使用[完整快速开始指南](https://github.com/SioYooo/RepoGrammar/blob/main/docs/quickstart.md)。 ## 您将获得什么 ## `0.4.0` 最新动态 | 领域 | 当前行为 | | --- | --- | | 入门引导 | 一个 `setup` 流程组合了安全的 Agent 集成、仓库初始化、索引、MCP 自测以及仓库本地自动同步。 | | 查询 | 精确优先的解析方式也能理解诸如 `FastAPI route` 之类的限定概念短语；`mode` 控制证据收集，`verbosity` 控制 payload 密度。 | | 一致性 | `check` 返回带有明确未解析义务的静态对齐证书，并且绝不会声明运行时等价性。 | | 新鲜度 | 查询时的哈希校验会拒绝过时的证据；显式的 `sync` 是权威的，而默认的仓库本地自动同步是一项尽力而为的便利措施。 | | 效率 | 感知依赖的增量同步和 Python 接口哈希避免了不必要的重建工作，同时全量/增量等价性门控保护了结果。 | | 指标 | 无源码的查询结果统计报告了跨结果的估计潜在读取位移；它不是测量的 token 节省量或因果关系结果。 | 请参阅[更新日志](https://github.com/SioYooo/RepoGrammar/blob/main/CHANGELOG.md)获取完整的版本历史，并参阅 [CLI 规范](https://github.com/SioYooo/RepoGrammar/blob/main/docs/specifications/cli.md)获取确切的命令契约。 ## 它如何保持值得信赖 1. **本地发现。** 语言适配器和受限的语义 worker 提取结构性事实，而无需执行目标仓库的应用程序代码。 2. **保守评估。** Tree-sitter 提出候选对象；仅凭语法相似性无法证明其属于某个家族。 3. **元数据优先。** 结果保留了哈希、受限位置、溯源、证据强度以及剩余的读取义务。 4. **强制新鲜度。** 每个仓库都拥有其 `.repogrammar/` SQLite 生成物和可选的 daemon；没有全局的仓库扫描器。 5. **按类型弃权。** 不受支持的置信度会变成可操作的带类型结果，而不是隐藏的默认回退。 Rust 实现遵循依赖倒置的 `core → ports → application → adapters → interfaces` 架构。请阅读[架构概述](https://github.com/SioYooo/RepoGrammar/blob/main/docs/architecture/overview.md)和 [MCP 契约](https://github.com/SioYooo/RepoGrammar/blob/main/docs/specifications/mcp-api.md)以了解更深层次的设计。 ## 语言和框架边界 | 语言 | 当前证据边界 | | --- | --- | | **Python** — FastAPI、pytest、Pydantic、SQLAlchemy | 官方的 Python 优先范围，带有受限的框架家族上下文 | | **TypeScript / JavaScript** — Express、Jest/Vitest、Mocha/`node:test`、Next.js、Fastify、Prisma、Drizzle、Zod、NestJS、Hono | 保守的精确锚点预览；React 和 React Native 仍不受支持 | | **Rust** — 内部模式以及受限的 serde、thiserror、Tokio、clap 和 axum 锚点 | 结构预览；不涉及宏展开、trait 解析或运行时声明 | | **Java/Spring, C#, C/C++** | 保守的结构预览；不提供运行时或构建系统等价性声明 | | **Go、PHP、Ruby、Swift** | 仅限文件发现；未进行分析或不提供支持 | RepoGrammar 处于 1.0 版本之前。其 MCP API 和预览分析器仍处于实验阶段，它不是一个可靠的全程序静态分析器，也不是一个运行时等价性判定工具。稳定的构件在文档记载的最低版本下，目标平台为 macOS arm64/x86_64 和 glibc Linux arm64/x86_64；Windows 和 musl 不是公开的发布目标。 RepoGrammar 本身不调用 LLM、embeddings API、向量数据库或云模型。受限的 Python 分析器需要 Python 3.10 或更高版本；经过验证的发布路径不需要 Rust/Cargo。确切的安全和平台边界位于[局限性](https://github.com/SioYooo/RepoGrammar/blob/main/docs/limitations.md)中。 ## 由 AI 构建，由人类指导 RepoGrammar 是通过人类指导的 GPT-5.6 工作流开发的。ChatGPT 帮助规划和审查工作；Codex 实现并测试了特定范围的更改；而人类维护者拥有产品洞察、架构、证据策略、范围界定、审查、合并权限以及公开批准的最终决定权。 OpenAI Build Week 是一个发布里程碑，而不是产品边界。竞赛录像和提交材料保留在[演示运行手册](https://github.com/SioYooo/RepoGrammar/blob/main/docs/demo/build-week-demo.md)和[发布套件](https://github.com/SioYooo/RepoGrammar/blob/main/docs/promotion/launch-kit.md)中，让本 README 专注于开发者工具本身。

标签：AI编程助手, CLI, MCP, SOC Prime, WiFi技术, 上下文管理, 代码库分析, 可视化界面, 开发工具, 暗色界面, 逆向工具, 通知系统