fixmap

观看带声音的 31 秒 FixMap 工作流视频

在主页示例中试用一项任务。它会在当前标签页中，使用捆绑的 sample-api 项目运行真正的 FixMap Plan 引擎。它不会检查你的代码库，也不会上传任务文本。若要用于自己的代码库，请使用开始使用；若要体验高级工作流，请打开完整浏览器演示。

安装

需要 Node.js 20.11 或更高版本。

npm install --global @aryam/fixmap@latest
fixmap plan --issue https://github.com/chalk/chalk/issues/624

若要进行一次性试用：

npx -y @aryam/fixmap@latest plan --issue https://github.com/chalk/chalk/issues/624

安装可发现的 /fixmap 命令，供 Claude Code、Cursor、GitHub Copilot 和 Agent Skills 使用：

fixmap setup

不带任务输入 /fixmap 可查看完整功能菜单，也可以在终端运行 fixmap features。使用 fixmap setup --agent <name> 安装一个集成；只有在检查现有自定义命令后，才使用 --force。

FixMap 会获取公开任务，推断其代码库，在临时隔离的检出目录中进行扫描，并在报告完成后将其删除。本地代码库分析绝不会上传源代码。

日常工作流

在编辑前保存计划：

fixmap plan --issue "password reset emails fail" --format json --output plan.json

计划将主要上下文与可能受影响的部分区分开来：导入项、反向依赖项、路由测试，以及反复出现的 Git 联合变更关系。影响文件是需要检查的地方，不代表必然要编辑。

在你自己的代码仓库历史记录上衡量 BM25、FixMap 和 Impact Graph：

fixmap benchmark --repo . --last 50

在 Agent 编辑时，将已保存的计划放在一旁。只有工作树发生变化时，Watch 才会生成新的验证结果，并围绕实际差异重新计算影响范围：

fixmap watch --report plan.json --repo . --include-untracked

向 Agent 提供相关源码范围，而不只是文件名。Context 从主要文件和影响文件中提取内容，并控制在预估的源码令牌预算内：

fixmap context --issue "password reset emails fail" --budget 10000

导出证据图，用于拉取请求、议题或设计说明：

fixmap graph --issue "password reset emails fail" --format mermaid

在 Agent 上下文窗口中使用简洁标题：

fixmap plan --issue "password reset emails fail" --format agent

询问为什么预期路径缺失：

fixmap plan --issue "password reset emails fail" --explain src/auth/token.ts

完善任务并比较排名：

fixmap plan --issue "sendMail throws during password reset" --compare plan.json

根据已保存的计划验证已完成的差异：

fixmap verify --report plan.json --diff main...HEAD

在另一个工具使用已保存的报告前先验证它：

fixmap validate plan.json

使用 --working-tree 处理已暂存和未暂存的受跟踪编辑；当新文件也应视为变更时，使用 --include-untracked；使用 --exclude 或 .fixmapignore 限定映射范围；使用 --no-cache 强制重新扫描。当建议性问题必须导致 CI 失败时，在 Verify 中添加 --fail-on warning。运行 fixmap --help 查看完整命令参考。

完整功能目录

输入和代码库映射

• 接受公开的 GitHub 议题或拉取请求 URL、纯文本任务、UTF-8 或 UTF-16 编码的 --issue-file（包括常见的不带 BOM 的 Windows UTF-16 文件），或来自 stdin 的任务文本。
• 规范化受支持的浏览器和 GitHub API 议题 URL，包括 www、查询字符串和片段；同时拒绝凭据、仿冒域名、端口和不安全的编码路径。
• 扫描当前检出内容、其他本地路径、file:// URL，或公开 GitHub 代码库的隔离检出内容。
• 映射 --diff <spec>、--base/--head 或当前的 --working-tree；未跟踪的变更仍需通过 --include-untracked 显式启用。
• 仅当代码库根目录、提交、状态和二进制差异都相同时，才会复用原始代码库扫描结果。任务文本、--limit 和排除规则会在扫描后应用，因此更改这些内容时，可以安全复用相同的缓存文件，同时生成重新排名和筛选后的报告；Compare 会扫描当前计划，而 Verify 会根据全新扫描或状态完全匹配的代码库映射验证所提供的报告。cache-hit 会报告复用情况和扫描时间；缓存条目会在七天后过期；FIXMAP_CACHE_DIR 可更改操作系统缓存目录。使用 CLI --no-cache、MCP noCache: true 或 Action no-cache: true 强制重新扫描。
• 将当前的 --issue-file、--compare、--report 和 --output 生成文件排除在代码库排名、变更检测和缓存失效范围之外，因此 FixMap 不会将自己的报告推荐为修复位置。
• 检测 npm、pnpm、Yarn 和 Bun 项目，并读取各工作区包中声明的脚本。当根目录未作声明时，可以根据一致的嵌套锁文件进行推断；如果根目录声明相互冲突，则会给出诊断信息，而不会悄悄自行选择。

计划与排名

• 根据路径术语、源文件内容、标识符、引用片段（包括弯引号和书名号）、文件提及以及实际差异内容，对源文件、测试文件、配置文件、文档和其他文件进行排名。
• 可识别 JavaScript/TypeScript 声明测试、Go _test.go、Python test_*.py 和 *_test.py、常见测试目录以及框架的单文件组件。
• 当存在受维护的源文件时，会降低锁文件、同步客户端备份、打包输出、示例和生成文件的对应文件的优先级，同时仍可对普通模块（如 deep-copy.ts）和受版本控制的一方 vendor/ 源文件进行排名。
• 根据实际软件包脚本路由可执行的测试命令，并将其与最近的相关测试文件配对。当路由到的 JavaScript、Python、Go 或 Rust 测试被跳过、忽略、设为条件执行或加以门控时，会发出警告。
• 报告六类有限风险领域：身份验证、计费、自动化、数据、公共 API 和依赖项。
• 说明任务依据、排名结构、未解析或部分匹配的标识符、排除项、扫描限制、未读取的内容、跳过的子模块、空差异以及 Git 故障。
• 支持严格的十进制 --limit、可重复指定的 --exclude，以及带否定规则的有序 .fixmapignore 模式。以仓库根目录开头的模式以仓库为相对路径；在仓库内粘贴的绝对路径会被规范化；未匹配任何内容的模式会触发警告。限制只会更改显示的行数，不会影响置信度或排名结构分析。

影响图与仓库基准测试

• 根据直接导入、反向依赖项、路由的测试，以及与排名靠前文件反复共同变更的 Git 文件，构建单独的可能影响视图。
• 最多读取 1,000 条非合并提交，排除涉及超过 30 个文件的提交，要求至少有两次共同出现；对于浅克隆或不可用的历史记录，会明确标记，而非捏造证据。
• 根据 Verify 期间实际变更的文件重新计算影响，并将原计划之外、证据充分的依赖文件标记为检查备注，而非强制编辑项。
• fixmap benchmark --repo . --last 50 会针对历史父快照评估 BM25-over-code、普通 FixMap 上下文和 Impact Graph。每个案例的历史记录都截至其目标变更之前；所有方案使用同一份已扫描的语料库；生成文件的对应文件不会被计为主要答案；并会分别报告提及和未提及的任务。
• fixmap watch --report plan.json --repo . 会监控本地工作树、重新运行 Verify，并仅在编辑发生变化时重新计算影响。它绝不执行仓库代码；--format json 会在每次更新时生成一个 JSON 对象。
• 基准测试的 Markdown 和带版本号的 JSON 包含 Wilson 区间、排除案例数量、次要文件召回率、安全措施以及逐案例原始结果。历史提交消息只是针对特定仓库的回测，绝不能证明 Agent 可以节省成本。

上下文包与图导出

• fixmap context 会从主要文件和影响文件中选择确定性的行范围，为每个代码片段标注主要或影响类别，并记录其原因、置信度、行范围、估算 token 成本、源文件截断情况以及文件未纳入的原因。
• 预算使用稳定估算值 ceil(UTF-8 bytes / 4) 统计源文件内容；不包括元数据。这是可复现的规划估算，并非针对特定分词器的精确计数。
• 上下文可能使用 FixMap 有限扫描样本，而非整个大型文件。sourceTruncated 会在 JSON 和 Markdown 中明确标记这一边界。
• fixmap graph 会将同一 Impact Graph 导出为 Mermaid 或带版本号的 JSON，并保留导入、被导入、测试路由和共同变更的方向与证据。

排除模式语法

--exclude 和 .fixmapignore 使用相对于仓库的 gitignore 风格模式。/docs/** 锚定在仓库根目录，docs/** 匹配同一根目录及嵌套位置，!docs/keep.md 会在先前排除后重新包含某个路径，末尾的 / 用于指定目录。支持 *、? 和 **；{src,test} 等花括号组会被视为字面文本，而非交替模式。重复传入 --exclude 标志，或在 .fixmapignore 中每行写一个模式，可避免名称中的逗号产生歧义。

• 为用户生成 Markdown、为工具生成带版本的 JSON，或使用 --format agent 生成精简的 EDIT CANDIDATE/INSPECT/TEST/RISK/AVOID/UNCERTAINTY 部分；使用 --output 可写入任意格式。

Explain、Compare、Verify、Validate 和 Doctor

• Explain 会说明某个路径是否进入排名、低于截止阈值、被排除、通过子模块解析，或从未扫描；并使用与 Plan 相同的任务和差异证据。
• Compare 会显示任务细化后新增、移除、移动或置信度发生变化的文件，以及任务依据的变化。
• Verify 会将已保存的 JSON 计划与差异或工作树进行比较，重新计算影响，并标记生成的编辑、未映射的更改、未触及的首个文件、没有测试的源代码更改、新触及的风险区域，以及计划与仓库不匹配的情况。默认情况下，遇到错误会失败；--fail-on warning 和 Action 的 fail-on: warning 可将提示性发现作为可选的 CI 门禁。
• Validate 使用 Compare、Verify、Action 和 MCP 共用的结构兼容性验证器，检查任意已保存的 JSON 报告。
• Doctor 会打印正在运行的版本和可执行文件路径，并诊断项目、全局、PATH 和 npm-exec 版本遮蔽问题。
• FIXMAP_PROGRESS 控制远程克隆/扫描进度，FIXMAP_VERBOSE_USAGE 会在参数错误后恢复完整用法文本。

Agent 和自动化接口

• fixmap setup 会为 Claude Code、Cursor、GitHub Copilot 提示词文件以及开放的 Agent Skills 布局安装 /fixmap 发现功能；不带参数的命令会在进行更改前列出所有 FixMap 工作流。
• MCP 服务通过本地 stdio 提供 fixmap_plan、fixmap_context、fixmap_graph、fixmap_explain、fixmap_compare、fixmap_verify 和 fixmap_doctor，并已发布到官方 MCP Registry。
• GitHub Action 会在拉取请求上运行 Plan 或 Verify，在作业摘要剩余的 1 MiB 预算内追加内容，限制报告输出和评论的大小，并创建或更新一条 FixMap 评论，而非重复发布。
• Action 接受显式任务输入或拉取请求上下文，使用与 CLI 和 MCP 服务相同的报告验证器；如果无法解析请求的差异，会明确报错。
• 首页任务映射器会针对捆绑的 sample-api 仓库运行真实的 Plan 逻辑，并保留引擎的不确定状态，而非臆造回退结果。
• 完整的浏览器演示会针对同一示例仓库运行真实的核心 Plan、Explain、Compare 和 Verify 逻辑，且不会上传任务。

TypeScript 库

• @aryam/fixmap-core 提供仓库扫描、排除项解析、排名、Context Pack 和 Impact Graph 构建、BM25 检索、任务依据分析、语言/导入分析、测试/风险路由、报告验证，以及 Markdown/JSON/agent/Mermaid 渲染功能。
• 其公共 API 还提供 Explain、Compare 和 Verify 构建器及结果类型，因此其他工具可以组合使用相同的工作流，而无需通过 shell 调用 CLI。
• @aryam/fixmap-core/browser 入口可在浏览器包中运行无需文件系统的报告、比较、说明、验证和渲染逻辑。

信任、兼容性与证据

• 核心采用确定性设计，并优先在本地运行：无需账户、API 密钥、托管模型、上传源码、安装依赖、运行仓库脚本、执行测试或安装 Git 钩子。
• 分析公共仓库时，会使用临时的浅克隆，并禁用凭据、继承的 Git 配置、钩子、LFS 文件检出处理、符号链接和子模块遍历。
• reportVersion: 1 定义了 JSON 兼容性边界；允许添加字段，仍接受未标记的旧版报告；不支持的版本会返回可执行的提示。
• 已纳入版本控制的自测、外部、留出、对抗性和性能记录为证据页面提供数据；CI 会检查空数据集、置信度门槛、生成资源漂移、Action 包漂移和 1,000 个文件的基准测试。
• 文档网站包含实时演示、安装方式、展示漏检的证据、发布变更日志、响应式导航、键盘焦点、AA 级对比度，以及持久且适配系统设置的浅色／深色主题。

报告内容

• 带有评分、置信度和证据的上下文文件排名。
• 可能受影响的文件，附带特定关系的证据、置信度、历史覆盖情况和检查顺序。
• 与仓库实际声明的命令相对应的测试路径。
• 六个范围明确的风险领域：身份验证、计费、自动化、数据、公共 API 和依赖项。
• 关于不确定性、未读内容、扫描边界、排除的匹配项和未解决差异的诊断信息。
• 有依据的下一步操作；当存在维护中的源文件时，会避开生成文件对应项。

FixMap 具有确定性。它能缩小调查范围，但不能证明排名或更改正确。

MCP 服务

通过本地 stdio 提供 Plan、Context、Graph、Explain、Compare、Verify 和 Doctor：

fixmap mcp

客户端配置示例：

{
  "mcpServers": {
    "fixmap": {
      "command": "fixmap",
      "args": ["mcp"]
    }
  }
}

客户端专属说明请参阅 MCP 设置指南。

GitHub Action

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
      - uses: aryamthecodebreaker/[email protected]
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

该 Action 会将范围受限的报告写入作业摘要，并维护一条拉取请求评论。如果受 GitHub 限制而需要截断，提示会引导你使用本地 --output 并上传构建产物，以获取完整报告。如果工作流必须绕过精确状态扫描缓存，请设置 no-cache: true；如果 Verify 的提示性发现必须导致作业失败，请设置 fail-on: warning。其已纳入版本控制的包和元数据受发布门禁检查。

JSON 兼容性

新计划包含 "reportVersion": 1。在同一报告版本内，可以添加字段，但不会删除或更改现有字段的类型；使用方应忽略未知字段。破坏性输出变更必须使用新的报告版本。Compare 和 Verify 仍会接受没有标记的旧版计划，并拒绝不支持的标记值。

证据

evidence page 根据已纳入版本控制的留出、回归、基线、性能和对抗性记录生成。页面会在展示命中的同时公布漏检和置信区间。CI 会拒绝空的评估文件、过时的渲染资源、对抗性回归、Action 包漂移和基准测试漂移。

安全边界

FixMap 只读取并排序信息。它不会安装依赖、运行仓库脚本、执行测试、调用 Git 钩子、上传本地源码或调用托管模型。远程克隆会禁用凭据助手、继承的 Git 配置、钩子、子模块、符号链接和 LFS 文件检出处理。

有关信任模型和报告流程，请参阅 SECURITY.md。

本地开发

npm ci
npm run ci

该工作区包含确定性核心、CLI/MCP 服务、GitHub Action、Next.js 网站、基准测试、示例和发布脚本。请从 CONTRIBUTING.md 开始；架构和完整使用说明请参阅文档网站。

发布

发布说明见 CHANGELOG.md 和生成的网站更新日志。发布工作流会验证内部版本、npm 包、MCP Registry 元数据、Action 元数据和构建包、GitHub 发布版本，以及干净安装的 CLI，确保发布完成。

许可证

MIT