atlas-cms

<h1>▲ 图谱</h1> **每个代码库，都被映射。AI 代理的真实依据。** *(图谱是产品；`cms` 是命令行和 Python 包 — `pip install`、`cms run-all`、`cms mcp`.)*   --- 图谱（Atlas）是一个自我启动的结构 + 语义内存层，适用于代码库，专为 AI 代理构建。它扫描项目（忽略诸如 `node_modules/`、`__pycache__/`、构建输出等无关紧要的内容），将源代码解析为文件、类和函数的知识图谱，生成每个文件的低分辨率 AI 摘要，并公开一个查询接口，以便代理可以询问 *"身份验证逻辑在哪里？"* 并获得精确的答案 — 文件路径、行范围、调用连接和意图摘要 — 而不是简单的 grep。 除了查找内容，图谱还 **保持代码库的诚实**：它跟踪特性，审计构建与预期的一致性，运行一个完成质量门控（赫尔墨斯哨兵），并通过变更对齐循环回答 *"此更改是否实现了预期？"* 因此，代理在 grep 之前会咨询内存，每次编辑都会接地，并证明它们已经完成。 完整的设计原理：[`codebase_memory_system_design_spec.md`](codebase_memory_system_design_spec.md)。 项目致谢和贡献来源：[`CONTRIBUTORS.md`](CONTRIBUTORS.md)。 许可证：[AGPL-3.0](LICENSE) — 免费使用和研究；修改后必须开源。 ## 安装 ```bash pip install -e . # 核心（networkx、pathspec、typer） pip install -e ".[anthropic]" # + Anthropic SDK，用于 LLM 摘要 ``` ## 用法 ```bash cms run-all # 扫描 -> 图谱 -> 摘要 -> 特性 -> git -> .memory/ cms query "忽略模式过滤逻辑在哪里？" cms ui # 在浏览器中打开内存查看器 cms update # 增量更新：仅更改的文件重新汇总 cms watch # 保持 .memory/ 与编辑同步 cms impact cms/scanner.py::scan # 更改的辐射范围 cms verify # 将测试映射到特性 via 覆盖率 cms verify CleanDirectoryScanner # 运行证明特性的测试 cms mcp # AI 代理的 MCP 服务器（见下文） cms sentinel # 赫尔墨斯哨兵：错误查找 + 完成质量门控 cms fuse # 星座：跨项目集成/冲突报告 cms scout scan ~/Desktop # 搜索 plan.md 文档，分类，批量评审想法/模式 # Brainstorm（发现 UI 标签）：临时调整的新概念生成，根据您的喜好/不喜欢学习；通过隐藏面板进行持续目标 cms scan # 仅限干净的树（run-all 的子集） cms build-graph # 扫描 + 知识图谱 cms summarize # （重新）生成 AI 摘要 cms prompt "添加速率限制" # 导出基于内存的任务简报 ``` ## 应用模式（`cms app` / CMS.exe） 通过一个命令或双击启动所有功能： ```bash cms app # 同步内存 -> 启动文件监视器 -> 提供 UI -> 打开浏览器 cms # 无参数执行相同操作 ``` 启动时，它会修复任何过时的内存（仅更改/模拟汇总的文件会被重新处理），然后监视编辑并保持 `.memory/` 更新，同时 UI 运行。Ctrl+C 停止所有操作。 ### 从源代码运行（`CMS.bat`） 在不允许未签名的 exe 的机器上（AV 隔离），`CMS.bat` 是一个等效的启动器：它从存储库的 `.venv` 运行 `python -m cms.cli`（回退到 PATH 上的 `python`），传递参数并返回实际退出代码。双击进行应用，或 `CMS.bat query "..."` 等。 ### 打包为 CMS.exe ```bash pip install pyinstaller python -m PyInstaller --onefile --name CMS --console --clean --noconfirm ^ --add-data "cms/ui_assets/index.html;cms/ui_assets" --hidden-import anthropic ^ --exclude-module torch --exclude-module torchvision --exclude-module torchaudio ^ --exclude-module numpy --exclude-module scipy --exclude-module pandas ^ --exclude-module matplotlib --exclude-module cv2 --exclude-module PIL ^ --exclude-module lxml --exclude-module IPython --exclude-module jupyter ^ --exclude-module pytest --exclude-module coverage --exclude-module rich ^ --exclude-module pygments --exclude-module tkinter --exclude-module setuptools ^ cms_exe.py ``` 排除项很重要：networkx 探针用于可选后端（numpy/scipy/pandas/ matplotlib）在导入时，因此 PyInstaller 愉快地捆绑了 site-packages 中存在的任何沉重包（仅 torch 安装就增加了 ~400 MB）。CMS 不使用它们。 **安装样式首次运行：** 双击 `CMS.exe` 任意位置，它会询问此副本应适用于哪个代码库，然后将选择保存到 `cms.workspace.json` 中，位于 exe 旁边。之后的每次启动都会直接进入该项目 — 因此您可以为每个代码库保留一个 CMS.exe 副本，每个副本都链接到其自己的根目录。删除 `cms.workspace.json`（或传递 `--root`）以重新链接。如果 exe 已经位于项目根目录中，则直接使用该项目而无需提示。 所有 CLI 命令也适用于 exe（`CMS.exe query "..."`、`CMS.exe impact ...`）。API 密钥从 `~/.cms/config.json` 读取，如通常一样。注意：`CMS.exe verify` 调用您的已安装 Python 以运行 pytest/coverage。 ## MCP 服务器（`cms mcp`） 将内存暴露给 AI 代理作为原生工具 — 在 grep 之前咨询内存： ```bash claude mcp add cms -- cms mcp # Claude Code codex mcp add cms -- cms mcp # Codex ``` 不需要 `--root`：服务器从其启动目录向上遍历到最近的持有 `.memory/graph.json` 的项目，因此一个全局入口为每个存储库服务。在未映射的存储库中，它保持活动状态，工具回答 "无内存层 — 运行 `cms run-all`"。 19 种工具（此列表在 `cms/mcp.py` 中与 Sentinel 校验）： - **接地/读取** — `query_codebase`、`get_file_summary`、`get_source`、`get_feature_trace`、`list_features`、`who_calls`、`who_imports`、`get_impact`。 - **讨论** — `ask_codebase`：整个内存的纯语言问答（流程、特性、连接、意图与现实），证据命名。也在 UI 中作为 Ask Atlas 聊天弹窗和 CLI 中的 `cms ask "…"`。 - **判断/计划** — `get_review`、`get_suggestions`、`get_sentinel_report`、`export_task_prompt`。 - **对齐循环** — `declare_intent`、`check_alignment`。 - **会话控制** — `switch_project`（将服务器切换到另一个项目根目录，会话中间；未映射的目标返回确切的构建命令）。 - **星座** — `list_projects`、`get_fusion_report`、`refine_fusion`：多项目发现 — 读取和对话式精炼跨代码库的融合报告（参见 `cms fuse`）。 每次调用都记录到 `.memory/activity.jsonl`，UI 渲染实时发光脉冲到触摸的节点和 `MCP · tool` 徽章 — 您可以观看您的代理思考。 ## Git 历史层 在 git 存储库中，`run-all`/`update` 用提交、作者、变动和年龄丰富文件节点，并检测 **隐藏耦合**：文件对重复更改在一起，没有任何导入关系（CO_CHANGES 边）。在 UI 中，点击 `heat` — 节点根据更改频率重新着色（从平静→热），共变对以虚线琥珀色链接绘制，检查器获得历史部分。 ## 验证循环 `cms verify` 在覆盖率下运行您的测试，并将每个测试映射到实际执行其代码的特性（`exercised_by` — 刻意命名：覆盖率证明执行，但不是行为正确性）。然后 `cms verify <Feature>` 恰好运行那些测试，将特性跟踪的检查清单变成可运行的证据。 ## 特性跟踪（`cms trace`） 特性是一流的：使用 `@memory:feature:Name` 锚点声明它们（LLM 还从文件摘要中发现未声明的特性）。对于每个特性，CMS 计算其成员、入口点和 **流程** — 调用链通过图谱以 `file:line` 为单位步行 — 然后写入具有目的、流程、输入和输出以及 **验证检查清单** 的跟踪。 ```bash cms trace # 构建/刷新所有特性跟踪 cms features # 列出具有成员/入口点计数的特性 cms trace CleanDirectoryScanner # 打印一个跟踪 ``` 跟踪位于 `.memory/features/*.md`、图谱（`feature:` 节点，因此 `cms query` 查找它们）和 UI 中 — 在资源管理器中选择一个特性以查看其流程轨道并突出其成员文件。 特性通过两种方式相互连接：**声明** 链接来自 `@memory:connects:` 锚点，以及 **推断** 的 RELATES 边，源自代码（一个特性的成员导入或调用另一个特性的成员）— 因此，即使 LLM 发现的特性也加入了网络。点击 UI 中的 `feat` 按钮（或打开 `?view=features`）以查看特性级架构图：琥珀色节点是声明的特性，绿色是发现的，实线边是声明的，虚线是推断的。点击任意节点以查看其跟踪。 ## AI 审查（`cms review`） 对齐审计：对于每个特性，AI 将您 **期望** （声明的意图）与实际 **构建** （跟踪流程、成员摘要、验证测试）进行比较，并给出判决 — **对齐 / 部分 / 漂移 / 未验证** — 带有单行纯英语标题、预期与构建的解释、具体差距和教育注释，教您其实际工作原理。加上应用级汇总。 ```bash cms review # 构建/刷新完整的审查 cms review CleanDirectoryScanner # 打印一个特性的审查 ``` 结果位于 `.memory/review.md`、图谱（代理通过 `get_review` MCP 工具获取）和 UI 中：点击 `review` 按钮（或 `?review=1`）以查看叠加层 — 每行一个特性，展开以查看详细信息，"缩放此特性到地图" 以查看完整证据。 ## 建议（`cms suggest`） CMS 计划下一步该构建什么。它研究自己的内存 — 审查判决和差距、没有验证测试的特性、git 变更热点、隐藏耦合 — 并提出建议，每个建议都按 **价值（1-5）** 和 **工作量（1-5）** 评分，按 **ROI = 价值/工作量** 排名，最高投资回报率优先。 ```bash cms suggest # 排名计划 -> 终端 + .memory/suggestions.md ``` 建议也出现在审查叠加层（"建议下一步"）并通过 `get_suggestions` MCP 工具提供给代理 — 因此您的 AI 可以通过 ROI 选择自己的下一个任务。 ## 内存查看器（`cms ui`） `http://127.0.0.1:7717` 上一个本地、零依赖的 Web UI，位于内存层之上： - **资源管理器** — 清洁的文件树，无杂项，按顶级目录着色。 - **知识图谱** — 力导向画布；节点大小 = 行数，边 = 导入。悬停显示摘要工具提示，点击检查，拖动/平移/缩放，`ext` 切换外部模块，`fit` 重新对齐。 - **检查器** — 文件统计、锚点芯片、AI 摘要、每个组件的行范围、调用者/被调用者计数和可扩展的代码片段，以及导入/导入导航。 - **搜索** — 按 `/` 并用纯语言询问；结果通过与 `cms query` 相同的意图引擎排名。 - 深入链接文件，`?file=cms/scanner.py`。仅在 localhost 上提供。 ### 截图 | | | |---|---| |  *特性地图：声明（琥珀色）vs AI 发现（绿色）特性和它们的连接* |  *热视图：更改颜色，虚线琥珀色 = 经常一起更改的文件，没有导入* | |  *悬停任意节点以获取其摘要、行数、提交和出处* |  *内置阅读器：markdown 渲染、源代码视图、引用锚点注释* | |  *发现：跨项目集成、涌现特性和冲突（星座）* |  *头脑风暴：温度调节的新概念，根据 👍/👎 学习* | |  *赫尔墨斯哨兵：发现、工作流检查和质量门控* |  *设置：分析内容、排除内容以及原因 — 有证据* | 所有内容都放入 `.memory/` 中，位于分析的项目内： ``` .memory/ ├── clean_tree.md # 过滤目录树，带有每个文件的元数据 ├── clean_tree.json # 可机器读取的版本 ├── graph.json # 知识图谱，节点中嵌入摘要 ├── index.md # 这里的内容 + 如何查询 └── summaries/ # 每个文件的 markdown 摘要，镜像源代码布局 ``` ## Python API（适用于代理） ```python from cms import CodebaseMemory mem = CodebaseMemory.load(".memory/graph.json") for hit in mem.query_intent("clean directory tree building", top_k=5): print(hit.path, hit.lines, hit.summary) print("调用者：", hit.called_by) mem.who_imports("cms/scanner.py") # -> ["file:cms/cli.py", ...] mem.who_calls("scan") # -> 调用者节点 ID mem.neighbors("file:cms/scanner.py") ``` ## API 密钥设置 ```bash cms config set anthropic_api_key sk-ant-... # 存储在 ~/.cms/config.json 中 cms config show # 设置中隐藏机密 ``` 环境变量始终优先于配置文件。其他密钥：`provider`、`anthropic_model`、`openai_api_key`、`openai_base_url`、`openai_model`。 ## 内存锚点 使用 `# @memory:` 注释引导内存层 — AST 无法推断的开发者精选意图。锚点位于图谱节点，增强 LLM 提示，并在查询中获得排名提升。 ```python # @memory:feature:UserAuthentication # @memory:connects:LoginFlow, TokenService # @memory:summary:处理 JWT 发行和刷新。 def login_user(...): ... # === @memory:module:GraphLayer === # 目的：维护运行时知识图谱（纯注释变成笔记） class MemoryEngine: ... ``` 行形式锚点附加到下一个 `def`/`class`；`module` 标签（以及不跟随定义的锚点）附加到文件。只有真正的注释计数 — 锚点文本位于字符串或文档字符串中的文本被忽略。 ## 摘要提供者 通过 `--provider` 或 `CMS_PROVIDER` 环境变量选择（`anthropic` | `openai` | `mock`）： - **anthropic** — 默认情况下，如果设置了 `ANTHROPIC_API_KEY`；使用 `claude-haiku-4-5` （覆盖 `CMS_ANTHROPIC_MODEL`）。 - **openai** — 任何 OpenAI 兼容的端点（Ollama、LM Studio、xAI、OpenAI）。配置 `CMS_OPENAI_BASE_URL`（默认 `http://localhost:11434/v1`）、 `CMS_OPENAI_MODEL` 和 `CMS_OPENAI_API_KEY`/`OPENAI_API_KEY`如果需要。 - **mock** — 确定性的结构化摘要，没有网络。 如果未配置任何密钥，则自动回退，以便管道始终运行。 ## 忽略规则 三个层次，按优先级递增：**内置默认值**（参见 `cms/config.py` — VCS、虚拟环境、`node_modules/`、构建输出包括 `dist/` 和 `dist-*/` 约定、依赖项锁定文件、IDE/OS 垃圾），然后项目的自定义 **`.gitignore`**（Atlas 尊重您已经声明的内容 — 不进行猜测），然后 **`.cmsignore`**（项目特定覆盖；gitignore 语法，以及 `!pattern` 可以重新包含被默认或 `.gitignore` 排除的内容）。仅列出的源扩展名被包含（`.py`、`.md`、`.json`、`.ts`、`.tsx`、... — 参见 `LANGUAGE_BY_EXTENSION`）。优先使用设置屏幕的作用域选择器进行每次构建的选择，而无需编辑文件。 ## 文件查看器和笔记 在内存查看器中（`cms ui` / `cms app`），选择文件时，检查器中会显示 **查看文件** 按钮。 它打开一个全屏阅读器：markdown 渲染格式，代码具有行号的语法高亮。 选择任意文本以 **复制** 或固定一个颜色标记的 **注释** — 亮点和注释在 `.memory/notes.json` 中持久存在，并在您重新打开文件时重新出现。 使用 `/?view=<path>&viewmode=reader|source` 直接链接到文件。 ## 赫尔墨斯哨兵（`cms sentinel`） 内置错误查找、特性审计和质量门控。 哨兵清点存储库，扫描风险模式（按上下文分类，而不是一概而论地标记），审计 `docs/feature_ledger.json` 完成声明与图谱证据的对比，检查 UI↔HTTP↔MCP↔docs 契约，执行端到端工作流检查（包括遗留回归陷阱），验证 CMS 域不变性和提供者层，并在 `.memory/sentinel/` 下持久化所有内容为错误报告。 ```bash cms sentinel # 完整扫描；如果存在严重问题，则退出非零 cms sentinel findings # 列出持久性发现（BUG-… id） cms sentinel status BUG-000007 false_positive --reason "模式注册" cms sentinel export -f json # 报告到 `.memory/sentinel/reports/` ``` 查看器提供完整的 Sentinel 屏幕（运行扫描、检查发现、更改状态、导出）。门控阈值位于 `sentinel.config.json`。完整指南：`docs/HERMES_SENTINEL.md`。 ## 开发 ```bash pip install -e ".[dev]" pytest tests/ cms run-all # 自我托管检查：CMS 分析自己的代码 cms sentinel # 质量门控：失败时存在严重问题 ``` 当前范围： **Python** （完整的 AST — 类/函数/导入/调用/继承）和 **TypeScript/JavaScript** （`.ts/.tsx/.js/.jsx` 通过轻量级解析器 — 顶级声明为组件，导入/需要/导出-来自解析为连接，以及尽力而为的 CALLS 和 `extends` INHERITS 边通过命名导入标记为 `provenance: heuristic`）；其他白名单文件获得 AI 摘要，但没有结构解析。 查询排名基于关键词+结构。 下一步：树解析器用于全语言多语言 AST（跨语言调用/继承），基于嵌入的语义搜索。 ## 许可证 图谱（Atlas）根据 **GNU Affero 通用公共许可证 3.0 版**（[LICENSE](LICENSE)）授权。您可以免费使用、研究、修改和分享它 — 但如果您分发或运行修改后的版本作为网络服务，您的更改必须根据相同的许可证发布。 版权所有 © 2026 Alex Terry（mrt150683-lgtm）。有关商业许可，请联系或开具问题。