Context Atlas

Context Atlas 是一个本地优先、有证据支持的项目软件记忆层。它将 Git 历史、仓库结构、清单、项目文档和人工审核的解释转化为：

• 一个对新成员友好的项目概览；

• 一个可探索的组件和依赖关系图；

• 一个项目如何变化的时间顺序记录；

• 有证据链接的组件和决策解释；以及

• 编码代理在做出更改之前可以读取的有界上下文包；

• 经人工同意明确选择的文档和对话摘要；以及

• 针对受信任主机的版本化扩展和提供程序出口安全契约。

此仓库包含一个可用的实验性 0.1.0 alpha 发布候选版本的源代码：一个 Node.js CLI、本地 Web 仪表板、TypeScript 库、stdio MCP 服务器和 Codex 插件包。下面描述的生成的插件运行时、本地行为门、最新本地包候选版本和干净的已安装包冒烟测试已在当前工作树上验证。托管工作流和 GitHub 发布尚未验证；0.1.0 仍未发布，更广泛的生产计划在 docs/ 中明确跟踪。

为什么存在

长时间的编码会话会失去线索。聊天历史被压缩，代理发生变化，未记录的决策消失，生成的摘要可能会悄悄变得过时或错误。Context Atlas 在任何单个聊天之外保持一个持久的高层地图，同时在观察到的事实、文档化的声明、推断、提议和人工批准的解释之间保持严格的边界。

flowchart LR
  A["Git history"] --> I["Evidence-first ingestion"]
  B["Repository structure"] --> I
  C["README, ADRs, manifests"] --> I
  I --> D["Local SQLite knowledge graph"]
  I --> L["Hash-chained audit ledger"]
  D --> O["Overview and orientation"]
  D --> M["Mind map and timeline"]
  D --> P["Task-bounded context pack"]
  O --> H["Developer"]
  M --> H
  P --> X["Coding agent through MCP"]
  R["Human review"] --> D

Related MCP server: koragraph

快速开始

要求：Git 和 Node.js 24 或更高版本。

git clone https://github.com/moelomda/context-atlas.git
cd context-atlas
npm.cmd ci
npm.cmd run build
node dist/cli.js init C:\path\to\your\git-repository --name "My Project"
node dist/cli.js serve --repo C:\path\to\your\git-repository

打开 http://127.0.0.1:4242。服务器故意拒绝未经身份验证的非回环主机。

对于首次交接，请使用以下顺序：

node dist/cli.js overview --repo C:\path\to\repo
node dist/cli.js health --repo C:\path\to\repo
node dist/cli.js timeline --repo C:\path\to\repo
node dist/cli.js pack "add subscription retry handling" --json --repo C:\path\to\repo
node dist/cli.js proposals pending --repo C:\path\to\repo

生成的叙述性提议不会自动被视为事实。审查其证据，然后明确批准或拒绝特定提议：

node dist/cli.js approve <proposal-id> --actor human:alice --note "Reviewed against ADR-0001 and current code" --repo C:\path\to\repo
node dist/cli.js reject <proposal-id> --actor human:alice --note "Superseded by the current architecture" --repo C:\path\to\repo

回环仪表板还提供了一个人工提议审查工作区，具有证据就绪性、冲突分组、审查历史和明确的批准/拒绝确认。浏览器变更需要完全同源的请求和内存中的会话令牌；它们不是代理能力。

可以通过仪表板的 添加源 工作流或 CLI 添加一个外部文本/Markdown 文档或一个对话摘要。预览是只读的，并绑定确切的字节、来源、目的、权威、敏感性和归属的人工参与者。应用需要新鲜的计划加上字面 IMPORT；敏感导入保留元数据和来源，但省略其正文。导入的材料仍然是不受信任的证据，永远不会自动批准声明或重写概览。

$plan = node dist/cli.js source-import-preview C:\path\to\notes.md --type document --origin "Architecture workshop" --authority documented --sensitivity normal --purpose "Preserve retry decisions" --actor human:alice --repo C:\path\to\repo | ConvertFrom-Json
node dist/cli.js source-import C:\path\to\notes.md --plan $plan.planId --confirm IMPORT --type document --origin "Architecture workshop" --authority documented --sensitivity normal --purpose "Preserve retry decisions" --actor human:alice --repo C:\path\to\repo

在有意义的提交后运行 sync。健康报告在仓库已超过最后索引的提交时明确警告。

新仓库以 8,000 个令牌的上下文包预算开始。现有仓库保留已存储在 .context-atlas/config.json 中的值——包括旧的 4,000 个令牌默认值——直到操作员更改它。pack --budget N 仍然为单个请求覆盖仓库默认值。

在影响提取的配置或 .atlasignore 策略更改后，也需要同步。Context Atlas 在内容同步和审查时记录一个指导依赖水印；更改该边界会使先前审查的声明变得不稳定。在水印跟踪之前创建的声明会失败关闭，需要同步和新的审查，而不是被静默地祖父化。

Codex 插件和 MCP

插件源包位于 plugin/context-atlas/。在打包或安装此项目之前，请构建并验证它：构建将自包含的 MCP 运行时嵌入到 plugin/context-atlas/runtime/server.mjs，因此经过验证的复制市场安装不依赖于此源树。包装器保留 dist/mcp/server.js 回退，用于本地源开发。

MCP 服务器公开了 13 个只读工具：

• 当前导航：atlas_overview、atlas_context_pack、atlas_explain、atlas_history、atlas_health、atlas_search 和 atlas_evidence。

• 时间知识：atlas_assertions、atlas_assertion_history 和 atlas_assertion_evolution。

• 已保存包检查：atlas_pack_history、atlas_pack_snapshot 和 atlas_pack_diff。

• 同步、提议创建、提议决策、包保存/刷新和保留应用有意通过 MCP 不可用。提议决策需要通过 CLI 或受保护的回环仪表板由明确的人工执行；其他变更仍然是人工操作的 CLI 工作流。

• atlas_context_pack 可以消耗现有的人工创建的 CLI 覆盖的 ID。它不能创建或更改覆盖，并且被覆盖的关键发现仍然在结构化结果及其文本处置中突出显示。

每个工具都接受绝对 repo 路径。直接 MCP 客户端也可以运行 node <absolute-project-path>/dist/mcp/server.js 并设置 CONTEXT_ATLAS_REPO 为已初始化的仓库。

版本化 HTTP 和 MCP 读取在组装响应之前和之后比较知识数据库、实时 Git/工作树、账本、同步和指导策略边界；并发更改会被拒绝并返回可重试的快照错误，而不是将较新的水印附加到较旧的数据。已保存包历史和差异工具返回一个紧凑的结构化负载，带有简短的文本指针，每个 MCP 工具结果都有 2,500,000 个字符的失败关闭上限。

受信任的进程内扩展可以使用公共的 context-atlas/extensions 导出。其六个版本化端口涵盖提取器、分析器、提供程序、编辑者、导出器和验证器；清单和输入/输出经过模式检查，不安全的输出原子失败，安装的扩展代码被明确视为受信任的可执行代码。核心库还公开了一个精确字节的出口预览/同意/授权网关，具有提供程序允许列表、编辑/阻止策略、令牌/成本预算、凭据间接、持久尝试收据、撤销和没有自动重试。在此 alpha 中，CLI、Web 仪表板或 MCP 服务器未启用任何远程提供程序。

上下文包契约

上下文包模式 v2 始终表示相同的 15 个必需部分：身份/权威、警告、目标、组件、接口、约定、决策、约束、风险、最近更改、测试、冲突、未知、证据和排除。一个部分可以明确为 present、none 或 unknown；空知识区域不会被静默省略。

选择是整体项目。每个被接纳到有界选择器宇宙中的材料实体、活动关系、断言或事件要么以其证据闭包完整呈现，要么作为具有确切原因的材料排除列出；环境非材料记录报告为聚合计数。关系携带当前使用状态、原因、权威、置信度和证据验证元数据，未经验证的拓扑不会作为已确定的指导呈现。硬预算适用于整个紧凑 JSON 对象——不仅仅是 Markdown 正文——MCP 适配器还为其工具结果信封保留空间。当前估计是公开的字符除以四的近似值，不是提供程序分词器。低至 500 个令牌的请求被接受为输入，但当强制信封无法容纳时，生成会以计算的最小值拒绝。

pack-save 将验证的包存储为不可变的、内容寻址的快照。pack-history、pack-diff 和 pack-refresh 提供有界历史、结构比较和针对当前状态的重建工作流。快照位于 .context-atlas/packs/ 下；存储拒绝第 257 个不同的快照，而不是静默删除历史。刷新保留原始任务和令牌预算，不继承先前的安全覆盖，并拒绝仓库身份或不稳定的仓库/策略更改。历史读取在应用请求的显示限制之前验证保留集，因此 256 项边界是安全上限，而不是大历史性能资格。

在呈现或打包当前指导之前，本地文件、可达的 Git 提交、仓库快照和组件快照定位符会根据规范路径、策略和 SHA-256 摘要重新验证。未知的外部定位符类型报告为未验证；它们不会升级为已验证的证据。概览、图、搜索、解释、断言、API、MCP、包和仪表板路径携带当前使用状态/原因/权威/证据元数据，或保留未解决的已审查散文。

记录了什么

Context Atlas 将其本地状态存储在 <repository>/.context-atlas/ 下：

• config.json：扫描和新鲜度策略；

• atlas.db：证据、实体、版本、关系、事件和提议；

• ledger.ndjson：覆盖记录操作的仅追加哈希链；

• backups/：经过验证的 SQLite 备份和可移植知识快照；

• exports/：带校验和的可移植 JSON 导出；以及

• packs/：被忽略的、不可变的上下文包快照，具有硬性 256 项容量。

不保留完整的原始差异和完整文件正文。Context Atlas 确实保留导航所需的有界、消毒的文档提取和仓库元数据。类似秘密的值和敏感路径（如 .env、凭据、私钥和证书）被扣留。将特定于仓库的排除添加到 .atlasignore；其有序的 glob 规则支持 ! 否定。

初始化创建 .context-atlas/.gitignore，以便数据库、导出、备份、包和完整的升级前迁移快照不会被意外提交。在旧存储写入迁移快照或包之前，Context Atlas 安全地追加缺失的派生数据规则，而不替换操作员规则。当您想要共享、可审查的项目记忆时，提交 .context-atlas/config.json、.context-atlas/ledger.ndjson 和 .context-atlas/.gitignore；将忽略的数据库材料保留在本地，或仅通过经过验证的备份工作流传输。

安全模型

Context Atlas 是导航辅助工具，而非软件正确性的证明。当前代码和测试对运行时行为仍具有权威性。如果上下文包被阻止，请解决列出的关键健康检查。特殊的 pack-override 工作流要求明确的人类参与者、理由和短有效期，生成的包仍会明显标记。

命令

运行 node dist/cli.js help 获取完整命令列表。主要工作流包括：

• 探索：overview、map、timeline、search、explain、evidence、assertions、assertion-history、assertion-evolution。

• 准备代理：pack <task> [--budget N] [--json]、pack-save <task>、pack-history、pack-diff <left> <right>、pack-refresh <snapshot>。

• 维护记忆：sync、proposals、propose、approve、reject；批准/拒绝也可由受保护的回环仪表板中的人类使用。

• 添加选定证据：source-import-preview <file> 后跟 source-import <file> --plan <id> --confirm IMPORT；仪表板为浏览器选择的单个文件或粘贴的摘要提供相同的预览/同意边界。

• 审计：health、validate、recover-ledger、privacy、retention-preview、确认的 retention-apply 和 retention-history（validate 在关键发现时以代码 2 退出）。保留删除仅限于符合条件的导出/备份文件，并要求精确的预览计划 ID、human: 参与者、理由和 --confirm APPLY。

• 可移植性：export、verify-export、import-preview、全有或全无的 import、rebuild-verify、backup、verify-backup、restore --confirm RESTORE。

• 可视化：在回环上 serve。

开发与验证

npm.cmd run build
npm.cmd test

当前本地工作树已通过正常行为套件（122/122 测试，693,394 毫秒）和覆盖率运行（122/122 测试，901,735 毫秒；95.40% 行，96.07% 函数，76.81% 分支）。严格的源/测试 TypeScript 编译、JavaScript 语法、JSON/YAML 解析、发布身份验证以及零报告漏洞的在线 npm audit 也已通过。这些是本地 Windows 结果，而非跨平台或托管结果。

最终本地性能测试还从概览契约中移除了重复的仓库/证据工作：在九实体夹具上，真实的 /api/v1/overview 请求从大约 8–12 秒和 58 个 Git 子进程降至 1.48–1.61 秒和 12 个 Git 子进程，同时保留了前后快照检查。这是聚焦的小型夹具回归结果，而非大型仓库延迟资格。

插件已从此源重新生成：源和捆绑运行时各自公开相同的 13 个只读工具，插件和技能验证器通过，独立运行时和第三方通知重新生成产生确定性哈希，真实重新生成的运行时通过了其 MCP 回归（1/1）。使用固定 Actionlint 1.7.12 的工作流检查通过了所有四个工作流；所有 17 个工作流 uses 引用均为完整 SHA 固定，涵盖七个已解析和验证的唯一提交。这些检查不能替代 GitHub 托管的 CI、CodeQL、依赖审查、SBOM 或来源作业。

2026-08-23 的渲染应用内浏览器 QA 覆盖了桌面视口以及 390×844 和 320×720 布局，包括概览和完整的外部源预览/同意流程。它验证了确认在预览前保持隐藏，完成了本地导入，检查了响应式重排和最小宽度溢出，并以零控制台警告或错误结束。运行发现并修复了过早的确认可见性和 320px 水平溢出；更新的 Web 套件通过了 6/6。早期的导航、地图、时间线、健康、审查、搜索、简报、键盘、Escape 和焦点返回覆盖仍是源测试契约的一部分，但这不是屏幕阅读器结果、WCAG 一致性声明、跨浏览器矩阵或另一操作系统上的证明。

在功能和渲染 UI 修复后，重新构建了 124 文件本地包候选，并通过了清单、禁止文件、大小、SHA-1 和 SHA-512 验证。一个干净的临时项目安装了该归档及其依赖项，导入了选定的外部源，加载了仪表板/API 和受保护的审查 API，导入了公共扩展子路径，并通过了隐私、覆盖和 MCP 冒烟测试；冒烟测试验证了完整的 13 工具只读清单，并执行了代表性的导航、pack-history、证据和覆盖读取。文档编辑会创建新的归档候选，因此最终交接仅记录最近的文档后重新资格。精确的归档摘要和大小保留在本地包报告中，而非此自引用文档。这仍是本地工件证据，而非远程仓库、托管检查、签名/SBOM 认证工件或已发布的预发布。

构建将项目许可证复制到插件中，从实际捆绑到自包含运行时中的依赖项生成第三方通知，并定义发布工作流以拒绝运行时/许可证/通知漂移。本地运行时/通知漂移和发布身份检查通过，包括候选标签输入、包、锁文件、插件清单、MCP 通告版本和带日期变更日志之间的一致性。最新的本地包冒烟测试也通过，但这些控制不证明托管执行或发布；相同的门仍需在选定的不可变提交上通过，以进行真实的 GitHub 预发布。

实现目前使用 Node 的内置 SQLite API，Node 24 仍将其标记为实验性。此 alpha 设计用于单个本地仓库和单个写入者；托管协作、IDE 原生面板、增量文件系统监视、提供程序存储/UI 集成、更丰富的语言语义分析和大仓库性能工作仍是路线图项目。保存包的私有路径检测阻止当前仓库根目录和一系列可识别的主机文件系统根目录，但自由文本无法完美区分每个自定义 POSIX 绝对路径与 API 路由。保留通过描述符和身份检查缩小路径竞争，但不声称对恶意同用户目录组件交换实现无竞争删除。

详细计划与证据

• docs/PRODUCT_PLAN.md — 用户、任务、范围、功能性和非功能性需求。

• docs/ARCHITECTURE.md — 时间数据模型、信任边界、摄取、检索和部署设计。

• docs/RISK_REGISTER.md — 故障模式、控制措施、测试和残余风险。

• docs/IMPLEMENTATION_ROADMAP.md — 从原型到生产加固的里程碑。

• docs/REQUIREMENTS_TRACEABILITY.md — 需求到控制/测试的台账。

• docs/IMPLEMENTATION_STATUS.md — 关于此 alpha 已实现内容和仍计划内容的如实证据。

贡献、支持与发布

• 在提出或实施变更之前，请阅读 CONTRIBUTING.md。它记录了信任边界不变量和验证标准。

• 使用结构化的 GitHub issue 表单来提交可复现的 bug、产品请求和文档问题。

• 使用 SECURITY.md 私下报告漏洞；切勿将凭据、专有源代码或真实的 .context-atlas/ 目录放入公开 issue 中。

• 项目参与遵循 CODE_OF_CONDUCT.md。

• 发布变更和维护者流程位于 CHANGELOG.md 和 docs/RELEASING.md 中。

许可证

MIT