内容
<div align="center">
# 修复地图
**给你的编码代理一张地图，让它在开始编辑前有所准备。**
将问题或git差异转化为相关文件、测试路由、风险备注和诚实的评审收据。
[](https://github.com/aryamthecodebreaker/FixMap/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@aryam/fixmap)
[](LICENSE)
[在线演示](https://fixmap-flax.vercel.app) · [安装](#快速开始) · [MCP 服务器](#mcp-服务器) · [GitHub Actions](#github-actions) · [贡献](CONTRIBUTING.md)
</div>
## 为什么使用 FixMap？
编码代理一旦有了正确的上下文信息，就会变得快速高效。然而，昂贵的错误往往发生在早期：
- 读取一个看似合理的文件，而不是实际拥有该模块的文件
- 忽略了原本可以捕获回归的测试
- 将未解决的 git 差异视为“无更改”
- 让评审者去猜测实际验证了什么
FixMap 是一个透明的路由层，用于解决这一问题。它在本地运行，不需要账户或 API 密钥，也不会将存储库源代码发送到第三方服务。
## 快速开始
在 JavaScript 或 TypeScript 存储库中运行：
```bash
npx @aryam/fixmap plan --issue "密码重置电子邮件失败"
```
使用实际的分支差异：
```bash
npx @aryam/fixmap plan --diff main...HEAD
```
机器可读输出：
```bash
npx @aryam/fixmap plan --base main --head HEAD --format json --output fixmap-report.json
```
示例结果：
```text
## 上下文文件
- src/auth/reset-password.ts （高置信度）：路径和内容匹配
- src/email/send-reset.ts （中等置信度）：内容匹配
## 测试路由
- npm --prefix apps/api run test
## 风险地图
- 高身份验证：受身份验证相关文件影响
```
## MCP 服务器
FixMap 作为模型上下文协议（MCP）服务器交付，因此编码代理可以自行请求计划，而无需您手动传递报告。暴露了一个工具：`fixmap_plan`。
克劳德代码：
```bash
claude mcp add fixmap -- npx -y @aryam/fixmap mcp
```
Cursor、Windsurf 或任何 MCP 客户端：
```json
{
"mcpServers": {
"fixmap": {
"command": "npx",
"args": ["-y", "@aryam/fixmap", "mcp"]
}
}
}
```
代理调用 `fixmap_plan`，并带有问题描述或差异规范（`main...HEAD`），并接收与 CLI 相同的报告：具有置信度和原因的上下文文件、测试路由、风险备注和诊断信息。所有操作都在本地通过 stdio 运行；存储库内容不会离开机器。
## 交互式演示
[在线网站](https://fixmap-flax.vercel.app) 包含一个仅限浏览器的示例存储库：更改任务并观察上下文包更新。它被刻意标记为示例；CLI 扫描实际的本地存储库。
在本地运行网站：
```bash
npm ci
npm run dev -w @fixmap/web
```
## GitHub Actions
将 FixMap 添加到拉取请求中，使用版本化的发布：
```yaml
name: FixMap
on:
pull_request:
permissions:
contents: read
issues: write
pull-requests: write
jobs:
fixmap:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0
- id: fixmap
uses: aryamthecodebreaker/FixMap/packages/action@v0.3.0
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
```
该 Action 会更新一个标记的 PR 评论，写入步骤摘要的 Markdown，并暴露 `report`、`context-count` 和 `test-route-count` 输出。在分叉的拉取请求中，GitHub 可能会限制评论权限；步骤摘要仍然包含报告。
## 使用的内容
v0.2 排名器是确定性和可检查的：
- 任务和标识符在路径和文件样本中的重叠
- 来自已解决的 git 差异的实际更改文件
- 代码、测试、文档和配置分类
- 附近的路径和工作区包边界
- npm、pnpm、Yarn 和 Bun 脚本路由
- 明确的置信度和诊断消息
它故意不声称正确性、不执行建议的命令，也不隐藏失败的差异解析。
## 评估
排名更改必须通过签入的任务到文件评估门，除了单元测试：
```bash
npm run evaluate
```
当前套件涵盖 Action 失败、无效差异、身份验证、Web 演示、Workspace 测试路由和贡献者文档。案例和完整的排名结果在 [`benchmarks/`](benchmarks) 中可见；更广泛的跨存储库评估在路线图上跟踪，而不是作为已完成的工作呈现。
## 存储库布局
```text
packages/core 扫描器、排名、路由、报告
packages/cli npx/CLI 入口点和 MCP 服务器
packages/action 捆绑的 GitHub Action
apps/web 交互式 Next.js 产品站点
benchmarks 透明排名评估案例
examples 可检查的示例输入和输出
```
## 开发
需要 Node.js 20.11 或更新版本。
```bash
npm ci
npm run ci
```
`npm run ci` 运行完整的测试套件、类型检查、ESLint、生产构建、Action 捆绑漂移验证、CLI/Action 烟雾检查和排名评估门。
## 状态和路线图
FixMap v0.2 是一个早期公开版本，专注于 JavaScript 和 TypeScript 存储库。近期工作：
- 导入/依赖图邻近性
- git 共同更改和所有权信号
- 流行 monorepo 布局的适配器和示例
- 更大、可复制的跨存储库评估数据集
- 稳定的 `v1` Action 标签，在更广泛的验收测试后
参见 [开放问题](https://github.com/aryamthecodebreaker/FixMap/issues) 以获取范围内的任务。欢迎贡献。
## 许可证
MIT © FixMap 贡献者。
