Project Atlas

Русская версия · 快速开始 · 协议 · 方法论 · 安全 · MIT

Project Atlas 将陌生的代码库转化为带有源码链接的映射图，供工程师进行审计和后续开发。它会追踪产品行为、runtime、数据、状态、权限、风险和恢复机制，同时严格区分事实、推断、目标和未知项。 **Codex 是主要的全功能适配器。Claude Code 是第一个次要适配器。** 两者都打包了相同的、独立于 AI 工具的核心协议。

使用 Codex 映射你的第一个代码库 →

## 为何信任其输出 - 实质性声明均有源码链接，并被明确归类为 `CONFIRMED`、`INFERENCE`、`HYPOTHESIS`、`TARGET` 或 `UNKNOWN`。 - 完成度验证会检查产出物结构、安全清单的源码归属，以及受支持的有限命令重放。它并不宣称自然语言结论是真实的。 ### 可复现的有效性 对于 v0.1.0 版本，“有效”意味着该协议能够生成在契约上完整、受源码限制、适配器稳定且可安全安装的结果。[发布测试套件](./tests/) 在配置的 [CI 矩阵](./.github/workflows/ci.yml) 中测试了这些机制： - **完成度契约：** QUICK、STANDARD 和 FORENSIC 模式接受实质性的测试用例映射集，并拒绝不完整或结构性伪造的输出。证据：[CLI 契约测试](./tests/test_atlas_cli.py) 和 [公开测试用例预言机](./tests/oracles/)。 - **源码边界：** 不安全、被忽略、符号链接、越界和 CommonMark 隐藏的引用会被拒绝，而不会被视为证据。证据：[安全回归测试](./tests/test_atlas_security.py)。 - **适配器稳定性：** Codex 和 Claude Code 携带字节完全相同的规范技能负载，并在发布前检测偏移。证据：[适配器打包测试](./tests/test_adapter_packaging.py)。 - **安装器事务：** 隔离路径测试涵盖了独立安装器的覆盖拒绝、有限预检、备份、回滚和中断行为。证据：[安装器事务测试](./tests/test_installers.py)。

运行验证检查

``` python3 -m unittest tests.test_atlas_cli python3 -m unittest tests.test_atlas_security python3 scripts/sync_adapters.py --check python3 -m unittest tests.test_installers ```

## Atlas 的工作原理

该工作流有意比“让 agent 解释代码库”更严格： 1. 在深入阅读之前进行**限制发现**：应用代码库指令、排除项、隐私限制和资源上限。 2. **将每个实质性声明分类**为 `CONFIRMED`、`INFERENCE`、`HYPOTHESIS`、`TARGET` 或 `UNKNOWN`。 3. **根据错误成本选择深度**，而不仅仅是文件数量。 4. **验证输出契约**，并留下后续交接文档，供其他工程师或受支持的 agent 重新开启。 | 深度 | 适用场景 | 输出 | | --- | --- | --- | | **QUICK** | 小型、低风险、短期的项目 | 一个 `PROJECT_ATLAS.md` | | **STANDARD** | 活跃的应用程序、服务和库 | 12 份路由的当前状态、流程、风险、目标、迁移和交接文档 | | **FORENSIC** | 关键、遗留、多服务、权限密集或高风险系统 | 13 份路由模式产出物，外加在完成时生成 `SOURCE_SNAPSHOT.json` | 查看完整的[深度规则](./docs/depth-levels.md)和[输出契约](./docs/outputs.md)。 ## 从 Codex 开始 添加 marketplace 并安装主适配器： ``` codex plugin marketplace add ddenny-s/project-atlas codex plugin add project-atlas@project-atlas ``` 如果技能尚未可见，请启动一个新的 Codex 会话。在 Codex 中打开你要映射的代码库，或者从该代码库的根目录启动 Codex。然后运行： ``` Use $project-atlas:map-project to create and validate a QUICK atlas of this repository. ``` 第一次成功运行后，应该会留下一个带有源码链接的 `PROJECT_ATLAS.md`，且不会更改产品代码。其完成度验证器返回： ``` {"artifacts": 1, "mode": "QUICK", "status": "valid", "validation": "completion"} ``` 该文档记录了已检查的边界、证据快照、确切的可重放检查、项目相对引用、风险、未知项和下一个安全操作。当你需要路由的当前/目标架构和迁移产出物时，请转到 STANDARD；当缺失某种关系可能导致实质性损害时，请使用 FORENSIC。 ### Claude Code 从同一代码库安装次要适配器： ``` claude plugin marketplace add ddenny-s/project-atlas claude plugin install project-atlas@project-atlas ``` 调用其命名空间技能： ``` /project-atlas:map-project ``` 两种适配器在措辞、证据标签、深度语义、文件名、验证规则和交接契约上保持一致。宿主权限和可用工具可能会有所不同；这些差距会保持明确。 ## 映射图能解答什么 当你需要明确以下内容时，映射图非常有用： - 产品做什么，以及哪些 UI、API、CLI、worker、队列、cron、webhook 或 provider runtime 产生了可观察的结果； - 数据在哪里进入、离开、持久化、改变状态、获得权威写入者，或跨越人类、自动化、管理或 provider 边界； - 产品流程如何处理重试、幂等性、回滚、恢复和部分状态； - 测试和 runtime 观察证明了什么，还有哪些是未知的，以及哪些实现存在冲突或已过时； - 当前架构如何才能向更安全的目标转变，按什么顺序转变，以及下一位工程师应该首先验证什么。 如果对于一个微小的、一目了然的脚本，只需一个 README 和一个验证命令就能回答重要问题，那么使用该工具通常是多余的。 ## 信任模型 Project Atlas 严格区分五种声明类型： | 声明类型 | 含义 | | --- | --- | | `CONFIRMED` | 直接由当前主要证据支持 | | `INFERENCE` | 根据指定的证据推理得出，但未直接观察到 | | `HYPOTHESIS` | 仍有待证据支持的可测试解释 | | `TARGET` | 拟议的未来状态，绝非当前事实 | | `UNKNOWN` | 答案尚未确定的已知空白 | 实质性的当前状态声明指向最强的可用项目相对来源或可重放命令证据。通过的测试仅能证明被测试的行为。当前架构和目标架构存在于不同的产出物中。 在使用映射图做出重大决策之前，请阅读[证据模型](./core/skill/map-project/references/evidence-model.md)、[限制与安全](#limits-and-safety)和[SECURITY.md](./SECURITY.md)。 ## 安装与生命周期 通过 marketplace 安装是主要的分发途径。独立安装程序可用于 macOS 和 Linux 上的本地技能目录。

Codex marketplace：检查、更新和移除

检查已安装的插件： ``` codex plugin list --marketplace project-atlas --json ``` 刷新并重新安装： ``` codex plugin marketplace upgrade project-atlas codex plugin remove project-atlas@project-atlas codex plugin add project-atlas@project-atlas ``` 移除插件和 marketplace： ``` codex plugin remove project-atlas@project-atlas codex plugin marketplace remove project-atlas ```

Claude Code marketplace：检查、更新和移除

``` claude plugin details project-atlas@project-atlas claude plugin marketplace update project-atlas claude plugin update project-atlas@project-atlas ``` 更新后重启 Claude Code。要移除它： ``` claude plugin uninstall project-atlas@project-atlas claude plugin marketplace remove project-atlas ```

独立的 Codex 和 Claude Code 技能

克隆一次： ``` git clone https://github.com/ddenny-s/project-atlas.git cd project-atlas ``` 将独立的 Codex 技能安装到 `$HOME/.agents/skills/map-project`： ``` ./scripts/install.sh --user-scope ``` 作为 `$map-project` 调用。显式更新： ``` git pull --ff-only ./scripts/install.sh --user-scope --force ``` 将独立的 Claude Code 技能安装到 `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/map-project`： ``` ./scripts/install-claude.sh ``` 作为 `/map-project` 调用。显式更新： ``` git pull --ff-only ./scripts/install-claude.sh --force ``` 这两个安装程序都会拒绝静默覆盖。强制更新会将先前的目录树保留在相应的 `.skill-backups/project-atlas/` 目录下。在进行手动恢复或移除之前，请参阅[适配器架构和独立生命周期](./docs/adapters.md)。 要仅移除已验证的独立 Project Atlas 副本，请运行此交互式检查。它会打印确切的目标位置，验证 Project Atlas 标记，并在删除任何内容之前要求输入 `REMOVE`： ``` codex_skill="${HOME:?}/.agents/skills/map-project" claude_root="${CLAUDE_CONFIG_DIR:-${HOME:?}/.claude}" claude_skill="$claude_root/skills/map-project" printf 'Codex: %s\nClaude Code: %s\n' "$codex_skill" "$claude_skill" verified_skills=() for skill in "$codex_skill" "$claude_skill"; do if test -d "$skill" && test ! -L "$skill" && test -f "$skill/SKILL.md" && test ! -L "$skill/SKILL.md" && grep -q '^name: map-project$' "$skill/SKILL.md" && grep -q 'Project Atlas' "$skill/SKILL.md"; then printf 'Verified Project Atlas skill: %s\n' "$skill" verified_skills+=("$skill") else printf 'Skipped unverified or absent path: %s\n' "$skill" fi done test "${#verified_skills[@]}" -gt 0 || exit 1 printf '%s' 'Type REMOVE to delete the verified paths: ' >&2 IFS= read -r confirmation test "$confirmation" = 'REMOVE' || exit 1 for skill in "${verified_skills[@]}"; do rm -r -- "$skill" done ``` 备份仍保留在相应的 `.skill-backups/project-atlas/` 目录下，以便进行明确的检查和清理。

## 实用提示词 ### 在重构前进行映射 ``` Use $project-atlas:map-project to build a STANDARD current-state and target-state atlas before we refactor this service. ``` ### 调查关键遗留系统 ``` Use $project-atlas:map-project in FORENSIC mode. Map every runtime root, data store, state writer, authority boundary, recovery path, and test gap. Do not implement changes until I approve the atlas. ``` ### 刷新并交接 ``` Use $project-atlas:map-project to refresh the existing atlas incrementally, report drift, and prepare a continuation handoff for another session. ``` Claude Code 使用相同的意图配合 `/project-atlas:map-project`。更多示例请参见 [docs/examples.md](./docs/examples.md)。 ## 限制与安全 - 排除的路径、机密、凭证、私人转储和被禁止的目录将保留在发现范围之外。映射并不授权更改代码、生产操作、部署或数据修改。 - 元数据和有限读取优先于广泛的内容访问。内存压力、磁盘余量、单重进程执行、会话所有权和媒体保留都有明确的规定。 - 源代码、通过的测试和确定性验证不能证明生产行为、自然语言推断、完全覆盖或审查者身份。 - 动态调度、生成的代码、runtime 配置、外部服务以及后续的项目更改可能会隐藏路径或导致映射图过期。 - 文件系统辅助程序和独立安装程序需要安全的 POSIX 描述符且不支持符号链接：它们在 macOS 和 Linux 上运行，并在原生 Windows 上安全失败。如果记录了该差距，则在这些环境中仍可使用有限的宿主原生工具来遵循该协议。 - FORENSIC 重放需要其允许列表镜像使用一个可写的临时目录。宿主权限仍然定义了可以检查的内容；无法访问的证据保持为 `UNKNOWN`。

操作上限与恢复边界

安全清单遍历被限制为 100,000 个文件、20,000 个目录、深度 64 以及 16 MiB 的 UTF-8 相对路径字节。序列化的 JSON 限制为 8 MiB。Git ignore 分类针对具有有限输出和 15 秒截止时间的隔离临时工作树运行；源 `.git` 元数据和用户级别的排除项不是证据输入。 独立安装限制为 2,048 个文件、512 个目录、深度 32、每个文件 4 MiB，总计 64 MiB。适配器同步限制为深度 32、2,048 个目录、4,096 个文件、8,192 个条目、每个文件 8 MiB，总计 64 MiB。 可捕获的安装和同步故障会尝试回滚。`SIGKILL`、断电或文件系统持久性故障仍然可能留下过时的锁、暂存树、备份或模棱两可的目标。在恢复之前检查目标、备份、暂存、锁和日志状态；切勿仅凭修改时间推断权限。 这些机制可保护公共路径免受普通并发写入者的影响。它们无法对具有直接文件系统访问权限的恶意同账户进程进行沙盒处理。

## 开发 规范工作流位于 [`core/`](./core/) 下。宿主适配器在不更改语义的情况下对其进行打包。编辑核心后，同步适配器并运行发布检查： ``` python3 scripts/sync_adapters.py python3 scripts/sync_adapters.py --check python3 -m unittest discover -s tests -v git diff --check ``` 在发布之前，维护人员会单独验证一次性的干净配置文件、包含空格的路径行为、清单、输出契约、所有三个前向场景，以及独立的正确性和安全审查。在创建版本标签或 GitHub Release 之前，必须通过此手动干净配置文件检查关卡，且不作为 GitHub Actions 检查进行声明。CI 检查是必要的证据，而不是全部的发布决策。 在提出协议或打包更改建议之前，请阅读[CONTRIBUTING.md](./CONTRIBUTING.md)、[适配器架构](./docs/adapters.md)和[ACKNOWLEDGEMENTS.md](./ACKNOWLEDGEMENTS.md)。 ## 许可证 Project Atlas 基于 [MIT 许可证](./LICENSE) 提供。

标签：AI编程助手, Claude, Codex, CVE检测, SOC Prime, 代码分析, 代码地图, 凭证管理, 开发工具, 逆向工具