内容
# repoctx
**面向 Agent 和 Reviewer 的本地优先代码上下文 - 这项变更实际上影响了什么？**
[](https://www.npmjs.com/package/@nugehs/repoctx) [](https://github.com/nugehs/repoctx/actions/workflows/repoctx-ci.yml) [](LICENSE) [](https://www.npmjs.com/package/@nugehs/repoctx)
```text
____ _____ ____ ___ ____ _____ __ __
| _ \ | ____| | _ \ / _ \ / ___| |_ _| \ \/ /
| |_) || _| | |_) || | | || | | | \ /
| _ < | |___ | __/ | |_| || |___ | | / \
|_| \_\|_____| |_| \___/ \____| |_| /_/\_\
```
Agent 的输出受到两件事的限制：**模型** 和围绕它的 **运行环境** - 提示、给定的上下文、工作代码库和代码合并前必须经过的关卡。你无法控制模型。你控制运行环境，更紧的运行环境让更便宜的模型做同样的工作，浪费的 token 更少。
`repoctx` 就是这一层运行环境。它是本地优先、确定性的、与模型无关的：它发现仓库、建立本地索引、在 Agent 编辑前生成任务感知上下文、评估变更实际影响、控制合并准备度 - 每次都一样，没有服务器、没有账户、没有代码离开机器。因为它依赖于软件基础而不是任何模型，今天你建立的运行环境在模型在下面改变时仍然有效。
旧的 `dev-context` 命令仍然有效但 **已弃用** ，将在 v3.0.0 中删除；请使用 `repoctx` 。调用 `dev-context` 会在标准错误中打印弃用警告。
它不试图取代 `opensrc` 、 `code-structure` 、 Daytona 或 Harnss。它为开发者和编码 Agent 提供了一个单一的 CLI，可以：
确定性合并关卡 - 差异化的核心。这是模型无法自行评估的人机检查点：
- 为本地更改和拉取请求评估合并准备度，使用一个 `review_gate` 工具（CLI 上的 `gate` ）
- 解析 CODEOWNERS 为所需审阅者和表面所有者决策警告
- 在合并前检查分支保护期望和所需检查
- 从 git diffs 和可选的 GitHub 评论中生成可行的 PR 审阅上下文
本地优先上下文 - 馈送关卡：
- 检查仓库
- 发现和索引本地仓库
- 维护本地目录并跨目录搜索
- 在 Agent 计划或编辑前生成任务感知上下文数据包
- 为 Agent 生成 AST 支持的 JSON优先代码映射
- 为仓库生成设置/验证/运行时运行环境
- 生成 Markdown 或 JSON 报告
- 估计生成工件的上下文 token 大小
- 为 Agent 主机运行 MCP 服务器，带有持久化的仓库索引缓存
- 暴露简单的 Agent 友好工具元数据
- 检查工具可用性
- 通过 `code-structure` 生成 TypeScript 结构 HTML
- 通过 `opensrc` 搜索依赖源
## 文档
repoctx 现在包含一个可发布的 MkDocs 文档站点，形状为一个实用发现和交付包：
- [首页](docs/index.md)
- [执行摘要](docs/EXECUTIVE-SUMMARY.md)
- [上下文基础](docs/01-context-foundation/README.md)
- [MCP 和 Agent 工作流](docs/02-mcp-agent-workflows/README.md)
- [贡献者治理](docs/03-contributor-governance/README.md)
- [发布准备度](docs/04-release-readiness/README.md)
- [信任层演示](docs/05-trust-layer-demo/README.md)
- [构建者-创始人运营循环](docs/06-builder-founder-operating-loop/README.md)
- [运行环境论文和 Agent 体验](docs/07-harness-thesis/README.md)
- [教程集成（Codespaces）](docs/08-tutorials-integration/README.md)
- [收敛论文和评分](docs/09-convergence-thesis/README.md)
- [用法和性能仪表盘](docs/10-usage-dashboard/README.md)
- [词汇表](docs/GLOSSARY.md)
当为仓库启用 GitHub Pages 时，发布的站点配置为：
```text
https://nugehs.github.io/repoctx/
```
## 快速入门
代码映射使用 TypeScript 编译器用于 JS/TS 和专用语言提取器用于 Go、C#、Python、Java、Ruby 和 Rust（参见 `src/lib/code-map/ast-languages.js` ）。仅当需要依赖源查找和 HTML 结构报告时，才需要可选的外部工具。
从 npm 安装：
```bash
npm install -g @nugehs/repoctx
repoctx doctor
```
或在不安装的情况下运行：
```bash
npx -y @nugehs/repoctx doctor
```
从本地检查：
```bash
npm ci # 安装依赖
npm run ci # 运行完整的质量关卡
npm install -g . # 在全局安装 repoctx CLI
repoctx doctor # 验证安装
```
```bash
node src/cli.js help
node src/cli.js doctor
node src/cli.js init /path/to/target-repo
node src/cli.js repo . --json
node src/cli.js discover ~/projects --depth 2 --json
node src/cli.js index ~/projects --discover
node src/cli.js catalog
node src/cli.js search "events controller"
node src/cli.js context "add a new MCP tool" --path .
node src/cli.js map . --json
node src/cli.js harness . --out .dev-context/harness.md
node src/cli.js pr . --base origin/main --out .dev-context/pr-review.md
node src/cli.js mcp
node src/cli.js matrix
node src/cli.js report . --out .dev-context/report.md
node src/cli.js workspace /path/to/web /path/to/api --out .dev-context/workspace.md
```
可选的外部工具：
```bash
npm install -g opensrc code-structure
```
然后：
```bash
node src/cli.js deps zod --query parse
node src/cli.js structure . --out .dev-context/structure.html
```
## 用例
| 目标 | 命令 | 输出 |
| --- | --- | --- |
| 检查一个仓库 | `repoctx repo . --json` | 仓库事实、脚本、语言、入口点和 git 状态 |
| 构建代码映射 | `repoctx map . --json` | 源文件、域、导入、导出、符号和路由 |
| 准备任务上下文 | `repoctx context "add a new MCP tool" --path .` | 主要文件、相关文件、测试、模式和验证命令 |
| 生成 Agent 运行环境 | `repoctx harness . --out .dev-context/harness.md` | 设置、验证、运行时和上下文命令 |
| 审查本地更改 | `repoctx pr . --base origin/main --out .dev-context/pr-review.md` | 更改文件、风险提示、审查目标和测试提示 |
| 索引本地项目 | `repoctx index ~/projects --discover` | `.dev-context/index.json` 文件和本地目录 |
| 搜索索引仓库 | `repoctx search "events controller"` | 跨路径、域、路由、导入、导出和符号的排名匹配 |
| 运行 MCP 服务器 | `repoctx mcp` | 暴露 repoctx 工具的标准输入/输出 MCP 服务器 |
| 跟踪用法和性能 | `repoctx dashboard` | 自包含的 HTML 来自选择加入的本地用法日志（默认关闭） |
有关 Claude Desktop、VS Code、Cursor 和通用标准输入/输出客户端代码段，请参阅 [MCP 和 Agent 工作流](docs/02-mcp-agent-workflows/README.md)。
## repoctx 与替代方案
| 方法 | 优势 | repoctx 的不同之处 |
| --- | --- | --- |
| Sourcegraph / Cody 上下文 | 强大的托管代码搜索和基于嵌入的上下文跨组织 | repoctx 是本地优先和确定性的：没有服务器，没有帐户，没有代码离开机器，并且相同的查询始终产生相同的数据包 |
| 手写的 `CLAUDE.md` / 规则文件 | 精心策划的、富含意图的指导 | 手写的上下文会过时；repoctx 从实际代码（符号、导入、路由、测试）中再生上下文，并在每次运行时补充简短的 `CLAUDE.md` |
| `grep` / `ripgrep` | 快速的、通用的文本匹配 | repoctx 按任务意图对整个文件进行排名，跨路径、符号、导出和测试，然后添加模式和验证命令 - 一个上下文数据包，而不是匹配行的列表 |
## 质量关卡
在打开拉取请求或发布版本之前使用完整的关卡：
```bash
npm run ci
```
关卡运行：
- `npm run format:check`
- `npm run lint`
- `npm run typecheck`
- `npm run version:check`
- `npm test`
- `npm run test:coverage`
- `npm run audit`
- `npm run smoke`
覆盖率目前对源文件进行 70% 行、60% 分支和 75% 函数的检查。`.dev-context/` 下的生成工件被 git、linting 和格式化忽略；请在那里保留持久报告，而不是提交它们。
repoctx 遵循语义版本控制。拉取请求应标识是否为无版本影响、补丁、次要或主要更改；维护者在发布期间应用最终的包版本。
对于更长时间的信任层工作，请使用 [构建者-创始人运营循环](docs/06-builder-founder-operating-loop/README.md) ，以将每个会话与上下文、聚焦的更改、可见的关卡、人工决策和持久的证据联系起来。
## 贡献
欢迎贡献。从 [CONTRIBUTING.md](CONTRIBUTING.md) 开始，打开问题或草拟拉取请求以进行重大更改，并在请求审查之前运行 `npm run ci` 。
所有代码更改必须在合并前由维护者/代码所有者审查。受保护的 `main` 分支需要维护者批准、通过的质量关卡和解决的拉取请求对话。
## 常见工作流
Agent 仓库运行环境：
```bash
node src/cli.js harness . --out .dev-context/harness.md
node src/cli.js map . --json
```
本地发现、索引、目录和搜索：
```bash
node src/cli.js discover ~/projects --depth 2
node src/cli.js index ~/projects --discover
node src/cli.js catalog
node src/cli.js search "submit rsvp"
```
任务感知 Agent 上下文：
```bash
node src/cli.js context "add a new MCP tool" --path . --json
node src/cli.js context "add a new MCP tool" --path . --out .dev-context/context-pack.md
```
PR 审查运行环境：
```bash
node src/cli.js pr . --base origin/main --out .dev-context/pr-review.md
node src/cli.js pr . --number 123 --comment
```
合并关卡（`gate` 是规范的 v2 命令；`pass` / `pass-pr` 仍作为遗留别名保留）：
```bash
node src/cli.js gate . --base origin/main # 本地关卡（无 GitHub）
node src/cli.js gate --pr 123 --path . # 通过 gh 的 GitHub PR 关卡
```
多仓库产品上下文：
```bash
node src/cli.js workspace ../web ../api --out .dev-context/workspace.md
```
GitHub Actions 引导：
```bash
node src/cli.js init /path/to/target-repo
```
本地 Ollama 审查：
```bash
node src/cli.js harness . --out .dev-context/harness.md
{
echo "使用此仓库运行环境来解释项目并建议下一个最佳工程任务。"
echo
cat .dev-context/harness.md
} | ollama run qwen3:8b --think false --hidethinking --nowordwrap
```
本地 Ollama PR 审查：
```bash
node src/cli.js pr . --base origin/main --out .dev-context/pr-review.md
{
echo "审查此 PR 上下文。关注 bug、缺少的测试和有风险的更改。"
echo
cat .dev-context/pr-review.md
} | ollama run qwen3:8b --think false --hidethinking --nowordwrap
```
## 命令
### `doctor`
检查本地运行时和可选的外部工具。
```bash
node src/cli.js doctor --json
```
### `install` / `i`
打印安装命令和当前二进制状态。从本地检查，`--global` 运行 `npm install -g .` ； `--link` 运行 `npm link` 。
```bash
node src/cli.js install
node src/cli.js i
node src/cli.js install --global
node src/cli.js install --json
```
安装后，使用 `repoctx` 作为主要命令。`dev-context` 仍然作为已弃用的别名保留，将在 v3.0.0 中删除。
### `repo <path>`
检查仓库形状：文件、包元数据、语言、包管理器、脚本、可能的入口点、git 元数据和被忽略的沉重目录。
```bash
node src/cli.js repo . --json
```
git 仓库通过 `git ls-files --cached --others --exclude-standard` 扫描，因此被忽略的文件不会污染运行环境上下文。普通目录则回退到内置的遍历器。
### `discover <root...>`
在单个或多个本地目录下发现仓库根目录而不索引它们。
```bash
node src/cli.js discover ~/projects --depth 2
node src/cli.js discover . --json
```
发现停止在具有常见仓库标记的目录中，例如 `package.json` 、 `.git` 、 `pyproject.toml` 、 `go.mod` 、 `Cargo.toml` 和 `Package.swift` 。
### `index <repo...>`
生成本地 `.dev-context/index.json` 文件并将仓库添加到本地目录。
```bash
node src/cli.js index .
node src/cli.js index ~/projects --discover
node src/cli.js index . --catalog /tmp/repoctx-catalog.json --json
```
默认目录路径是 `~/.dev-context/catalog.json` 。设置 `REPOCTX_CATALOG` 、遗留的 `DEV_CONTEXT_CATALOG` 或传递 `--catalog` 以使用不同的文件。
### `catalog`
列出当前索引到本地目录的仓库。
```bash
node src/cli.js catalog
node src/cli.js catalog --json
```
### `search <query>`
通过路径、域、种类、路由、控制器路径、导入、导出和符号搜索索引的本地仓库。
```bash
node src/cli.js search "events controller"
node src/cli.js search "submit rsvp" --limit 10
node src/cli.js search "api client" --offline --json
```
默认情况下，搜索在指纹更改时刷新仓库索引。使用 `--offline` 读取存储的 `.dev-context/index.json` 文件。
### `context <query>`
为任务生成本地上下文引擎数据包。数据包包括推断的意图、主要文件、相关文件、匹配的测试、实现模式、验证命令、冲突、源证据和令牌估计。
```bash
node src/cli.js context "add a new MCP tool" --path . --json
node src/cli.js context "add a new CLI command" --path . --out .dev-context/context-pack.md
```
在将工作交给编码 Agent 之前使用此命令。它是确定性和本地优先的：它依赖于仓库索引、代码映射、导入关系、测试和运行环境命令，而不是外部模型。
### `harness <path>`
为仓库生成具有设置命令、验证脚本、运行时脚本、上下文命令、焦点区域和估计的上下文令牌用量的运行环境。
```bash
node src/cli.js harness . --out .dev-context/harness.md
node src/cli.js harness . --json
```
在触摸代码之前，将此作为 Agent 或 CI 工作流读取的第一个工件。
### `init <path>`
在另一个仓库中搭建 repoctx。
```bash
node src/cli.js init /path/to/target-repo
node src/cli.js init /path/to/target-repo --force
node src/cli.js init /path/to/target-repo --no-workflow
node src/cli.js init /path/to/target-repo --tool-repo nugehs/repoctx --tool-ref main
```
生成的文件：
- `.dev-context/README.md`
- `.github/workflows/repoctx-ci.yml`
生成的 workflow 在拉取请求和提交推送时运行。拉取请求运行会生成报告、上载工件并创建或更新粘性 PR 评论。推送运行会生成并上载报告工件而不会评论。
### `structure <path>`
对 TypeScript 文件运行 `code-structure` 。
```bash
node src/cli.js structure . --pattern "app/**/*.tsx" --out .dev-context/structure.html
```
如果缺少 `code-structure` ，命令会返回安装提示而不是神秘地失败。如果它没有全局安装但有 `npx` ，repoctx 可以通过 `npx --yes code-structure` 运行它。
### `deps <package>`
使用 `opensrc path <package>` 解析依赖源并可选地搜索它。
```bash
node src/cli.js deps zod --query parse --limit 20
```
### `report <path>`
生成可共享的开发者报告。
```bash
node src/cli.js report .
node src/cli.js report . --out .dev-context/report.md
node src/cli.js report . --json
```
默认输出格式为终端阅读，并以估计的令牌使用量结尾。使用 `--out` 获取 Markdown 工件或 `--json` 获取结构化数据。
### `workspace <repo...>`
在相关仓库之间生成一个产品级报告。
```bash
node src/cli.js workspace /path/to/web /path/to/api --out .dev-context/workspace.md
node src/cli.js workspace /path/to/web /path/to/api --json
```
### `pr <path>`
从本地 git diff 元数据、代码映射分类、审查目标、定向审查提示、风险标志、建议的验证命令、估计的令牌和可选的 GitHub PR 评论中生成 PR 审查上下文包。
```bash
node src/cli.js pr . --base origin/main --out .dev-context/pr-review.md
node src/cli.js pr . --number 123 --comment
```
有用标志：
- `--base <ref>`：比较特定的基准引用。默认为 PR 基准、上游、 `origin/main` 或 `main` 。
- `--head <ref>`：比较特定的头部引用。默认为 `HEAD` 。
- `--number <n>`：用 `gh pr view` 元数据和审查评论丰富。
- `--github`：要求 `gh` 推断当前分支的 PR。
- `--comment`：使用 `gh` 创建或更新粘性 GitHub PR 评论。
### GitHub Actions
此仓库包括 `.github/workflows/repoctx-ci.yml` 。工作流安装依赖项，运行 `npm run ci` ，然后生成 PR 或推送审查上下文作为上传的工件。使用 `node src/cli.js init /path/to/target-repo` 将 repoctx 审查工作流搭建到另一个仓库中。
### `mcp`
启动一个stdio MCP服务器，暴露repoctx作为代理可调用的工具。MCP存储库映射查找缓存`.dev-context/index.json`，带有文件指纹，并在文件更改时自动刷新。
```bash
node src/cli.js mcp
```
将其连接到MCP主机（Claude Desktop，Claude Code，Codex CLI，Cursor等）：
```json
{
"mcpServers": {
"repoctx": {
"command": "npx",
"args": ["-y", "@nugehs/repoctx", "mcp"]
}
}
}
```
如果您更喜欢全局安装的二进制文件：
```json
{
"mcpServers": {
"repoctx": {
"command": "repoctx",
"args": ["mcp"]
}
}
}
```
Ollama可以提供本地模型，但它本身不调用MCP工具。要通过MCP使用repoctx和本地模型，请使用支持Ollama作为模型提供者的MCP-capable代理客户端，并配置上述`repoctx`服务器。
repoctx 2.0公开了**11**个MCP工具（低于18个）。所有旧名称仍然通过`tools/call`工作，直到3.0 — 请参阅[迁移到2.0](docs/MIGRATION-2.0.md)。
| 工具 | 用途 |
| ------------------ | ------------------------------------------------------------------------------------ |
| `repo_inspect` | 检查存储库结构、脚本、包管理器、入口点和git状态 |
| `repo_map` | 紧凑的JSON代码映射，可按`domain`、`kind`和`route`过滤 |
| `repo_index` | 生成`.dev-context`索引 + 目录条目；`dryRun:true`发现只读 |
| `repo_search` | 搜索目录；省略`query`返回目录列表 |
| `context_pack` | 构建任务感知上下文数据包 |
| `change_impact` | 排名最可能拥有纯英文变更请求的更改文件 |
| `agent_experience` | 评分代理体验（AX 0–100）：可更改性、包含性、防护栏、清晰度 |
| `review_context` | 差异/评论审查上下文（无裁决） |
| `review_gate` | PASS/WARN/FAIL合并门 — 本地无`pr`，GitHub PR门户带`pr` |
| `review_verdict` | 综合裁决：影响 + review_context + review_gate |
| `workspace_report` | 跨多个存储库的产品级报告 |
| `repo_harness` | 代理或CI托管的设置、验证、运行时和上下文命令 |
已弃用的`repo_discover`、`repo_catalog`、`find_domain`、`find_file_kind`、`find_backend_route`、`find_frontend_api_client`、`pr_review`、`review_pr`、`merge_readiness`和`pr_merge_readiness`名称仍可通过`tools/call`调用，并转发到上述工具。有关完整的映射和参数转换，请参见[迁移到2.0](docs/MIGRATION-2.0.md)。
### `matrix`
打印Greploop、`code-structure`、`opensrc`、Daytona和Harnss的工具评估矩阵。
### `agent-tools`
打印代理集成的JSON元数据。此设计故意轻量，以便稍后无需更改命令语义即可成为MCP服务器。
## 策略
先封装。再衡量痛点。根据需要构建缺失的部分。
这使得项目能够快速发挥作用，同时留有空间，以便稍后用自有实现替换薄弱的适配器。
---
## 工具链的一部分
**repoctx**是形成AI辅助开发的确定性信任层的四种工具之一。每个工具都回答人们向LLM提出的问题 — 使用静态分析代替。
- **repoctx**（此工具）— 上下文：此更改实际上影响了什么？
- [tieline](https://www.npmjs.com/package/@nugehs/tieline) — 契约：前端和后端是否悄悄地不再一致？
- [bouncer](https://www.npmjs.com/package/@nugehs/bouncer) — 合规性：你能向Ofcom证明这一点吗？
- [aiglare](https://www.npmjs.com/package/@nugehs/aiglare) — 治理：模型可以在哪里做您无法撤销的事情？
更多信息请访问 [segunolumbe.com](https://segunolumbe.com)。_静态分析，而非模型。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器