repotector

Repotector ⬡

会记忆的仓库。

每个访问你仓库的 AI Agent 都从零开始：重新推导地图，重新发现约定，再次弄坏上一个 Agent 刚修好的东西。Repotector 让仓库本身拥有记忆。新来的 Agent 敲响前门，完成握手后，就会拿到地图、现行决策以及上一位访客的简报；离开时，它会在登记簿上签名。下一个 Agent 两分钟内就能接手，而不必漫无目的地摸索一小时——重构也不会悄悄破坏已有功能。

便携且自成一体：纯 Node ESM，仅依赖两个项（@modelcontextprotocol/sdk、zod）。适用于任何仓库——对 JS/TS 提供深入支持，对其他技术栈则提供务实的轻量概览。

安装到任意仓库

cd /path/to/your/repo
npx repotector init

init 会扫描仓库（第一天绝不会让你碰壁——见下文的既有基线），将 MCP 服务接入 .mcp.json，并写入入口区块，让每个新来的 Agent 都知道要先握手。它只会写入 .repotector/ 内部以及 REPOTECTOR:BEGIN/END 标记之间——绝不会覆盖你的说明文字或配置。具体措施请见 SECURITY.md。

.repotector/ 目录下：

文件	内容
intent.json	契约：标准、必需路径、限界上下文和规范规则。
atlas.json	地图：每个文件的导出项／导入项／用途／类型、路由、组件、技术栈，以及确定性指纹。
dna.json	逆向工程得出的实体、API 契约和意图。
baseline.json	既有基线——第一天就已存在的技术债。
proof.json	门禁判定，以及相对于既有技术债的回归情况。
register.jsonl	访客登记簿：谁进来了、何时进入、接触了什么、当前有哪些人在里面。
dna.inferred.json	外部仓库的反向 DNA 条款（存在 .psx/ 镜像时会跳过）。

此外，仓库根目录还会生成更新的 JOURNAL.md——这份工作日志按时间倒序排列，handshake 会提供其中最新的内容，让下一个 Agent 接续之前的工作，而不是从头推导。

正门（先握手）

MCP 服务会拒绝深度工具调用，直到 Agent 调用 handshake——而 initialize 响应已经告知 Agent 这一点。作为回报，Agent 只需一次调用就能了解情况，其退出信息也会被记录，供下一个 Agent 查看。

• handshake({ who, model?, purpose? }) — 提供情况说明、基本规则、实时门禁判定、地图新鲜度和通行证。只读且快速（不遍历目录树）。
• city_map() — 意图、技术栈、已构建与缺失内容、核心信息指针。对于非 JS 仓库，它会返回 orientation-lite，而不是伪造一张空地图。
• find_existing({ intent }) — 复用：它是否已经存在？不要重复构建。
• blast_radius({ changedFiles? }) — 保护：传递依赖项，以及受影响的路由／组件。省略 changedFiles 时使用 git diff。
• canon_check({ changedFiles? }) — 集成：仓库的规范规则。
• atlas_query({ query }) — 在地图中进行关键词搜索。
• quality_gates() — 行数预算／结构／机密卫生检查，并将结果报告为相对于既有债务的回归。
• register() — 当前有哪些会话，以及完整的出入记录。
• journal({ limit? }) — 仓库近期历程：之前的 Agent 做了什么，还有哪些工作未完成。whats_next() — 根据 DNA 缺口、未结事项和 TODO 推导合理的后续工作，每条建议都会列出依据。
• dna_query({ clause?, topic? }) — 仓库规定了什么（根据 .psx/ 镜像编写，或推断得出；绝不合并）。dna_coverage() — 按条款列出实现状态：已实现／部分实现／缺失。dna_diff({ changedFiles? }) — 某项更改涉及哪些条款。
• depart({ summary? }) — 签退；即使忘记填写摘要，也会记录你访问期间的 git 差异。你的摘要将成为下一个 Agent 的简报。

既有基线——首日绝不亮红灯

如果守护工具在安装后立刻让仓库不合格，你也会立刻将它卸载。因此，init 会为现有债务（超大文件、已跟踪的机密信息、缺失路径）创建快照。随后，门禁只会针对超出该底线的回归失败——出现新的问题、问题加重、出现新的泄漏。既有债务会明确报告，但绝不阻塞。偿还部分债务后，运行 repotector baseline 重新创建快照。

v1.2「Gatekeeper」——从顾问到检查点

• 提交防护 — repotector hooks 会安装一个运行门禁的 pre-commit；gates 在出现回归时返回非零状态，因此 hooks 和 CI 确实会阻止提交。既有基线意味着首日债务不会导致阻塞，只有新的损害才会。
• 受保护路径 — intent.protect.paths glob（CI 工作流、LICENSE……）指定 Agent 不得触碰的路径：基于更改进行检查，绝不纳入既有基线；只有修改 intent（明确且可通过 diff 查看）才能覆盖。
• 声明 — claim({ paths }) 用于声明你的工作范围；与当前会话的声明重叠时，会返回 granted:false，并说明由谁声明及原因。此功能按设计仅提供提示（在我们无法控制的文件系统上强制阻止只是做样子）；会话结束后，声明也会失效。
• 决策记录 — depart({ decisions: [{ chose, over, because }] }) 会将原因写入 register 并生成 DECISIONS.md；handshake 会提供长期有效的决策，decisions_query 则可回答“这是有意为之的吗？”——这样 Agent 2 就不会撤销 Agent 1 的选择。
• repotector doctor — 一条命令，以信号灯方式回答“这个仓库到底受到了多好的保护？”，并为每个红灯问题提供修复方案。

v1.5 “Mission” — 可验证的单一链路

整个访问过程成为一份可审计的契约：

handshake → declare_mission → (auto)claim → work
        → off-claim / forbidden reconciliation
        → evidence pack (machine-verified vs agent-declared)
        → depart → the next agent inherits it all

• declare_mission({ goal, acceptance, claimPaths?, forbiddenPaths?, risk? }) — 将本次访问绑定到一份契约：自动认领你的工作区（并显示冲突），并提供一次性简报（关卡、合并状态、现行决策、受保护路径）。
• 离开时生成证据包 — 登记簿会严格区分机器验证的内容（关卡判定、试合并是否干净／有冲突、触及的文件、认领范围外的文件、违反禁区的情况），以及 Agent 声明的内容（逐项标准的自我报告）；未报告的标准会列出，但绝不会被假定为已满足。“完成”将成为登记簿可核查的事项，而非出于客气的认可。
• 其他 Agent 在握手时可以看到正在进行的任务——了解你在做什么，而不只是身处何处。

v1.3 “Merge Guard” — 提交而不发生冲突

• merge_check — 在提交前，对 HEAD 与集成分支执行零损害试合并（git merge-tree）：报告合并干净或有冲突，以及确切的文件，并将每个文件归属到持有该工作区的主体（实时认领；在 PSX Workbench 仓库中，还包括 Merge Machine 通过 .psx 镜像维护的租约）。 CLI：repotector merge-check [target]（有冲突时退出码为 1，因此 hooks／CI 可以据此设门禁）。不访问网络：它会针对你的本地 refs 进行试合并，并明确说明这一点——先执行 fetch，才能获取最新情况。

弹性登记簿 — Agent 无需签退，即使退出也能处理

已进入但从未离开的会话（Agent 被终止、管道关闭）会在下一次握手时自动标记为离开，并记录其触及内容的 git 差异。账簿不会被永不关闭的会话填满；即使没有人调用离开操作，离开记录也会包含实际工作内容。

CLI

npx repotector init          # scan, wire .mcp.json, write the doors — day-one green
npx repotector refresh       # re-derive the map + re-stamp the doorway blocks
npx repotector handshake     # orientation + live gate + passport (logged visit)
npx repotector city-map      # built-vs-missing + brain pointers
npx repotector dna-coverage  # per specified clause: implemented / missing
npx repotector whats-next    # the sensible next work, with evidence
npx repotector journal       # the diario di bordo (regenerates JOURNAL.md)
npx repotector gates         # regressions vs grandfathered debt
npx repotector baseline      # re-snapshot the grandfathered floor
npx repotector register      # the visitor ledger
npx repotector lock <pass>   # optional passphrase gate on the deep map
npx repotector mcp           # start the stdio MCP server

Docker

GHCR 上的镜像封装了 CLI 和 MCP 服务；受保护的仓库会挂载，而不会打包进镜像：

docker run --rm -v "$PWD:/repo" ghcr.io/dir-ai/repotector init
docker run --rm -v "$PWD:/repo" ghcr.io/dir-ai/repotector gates
docker run -i --rm -v "$PWD:/repo" ghcr.io/dir-ai/repotector mcp   # stdio MCP

支持多架构（amd64/arm64），每个发布标签都会由 CI 构建并进行冒烟测试（参见 Dockerfile）。

GitHub Action

只需一个步骤，即可在 CI 中保护仓库——适用存量问题豁免语义，因此作业只会因回归而失败，绝不会因首日遗留问题而失败：

- uses: dir-ai/repotector@main
  with:
    command: gates     # default; any CLI command works
    version: latest    # pin an exact npm version for reproducible CI

诚信

Repotector 会保护仓库，因此也以自身标准要求自己。锁是一种合规信号，而非文件系统访问控制；登记簿只能保证追加完整性，并非防篡改；静态徽章的内容由自身报告。它只会启动 git，不会发起网络请求，并在 .mcp.json 中固定精确版本。完整威胁模型见 SECURITY.md——不搞安全作秀。

确定性

Atlas 的 fingerprint 是对排序后的源内容计算的 SHA-256（16 个十六进制字符），不包含时间戳——相同的代码树始终生成相同的指纹。大型文件（>1MB、生成文件／压缩文件）会被标记，但不会读入指纹。builtAtHead 会记录 git sha，无需遍历即可检查新鲜度。

许可证

MIT © PSX System。Agent 在仓库中所需的核心功能永远免费；不断积累的智能（Genome 云端、创作的 DNA）则属于高级层。