项目定位与目标

Xurgo Atlas 是一个本地优先（local-first）的文档与项目上下文服务，专为 AI 辅助开发场景设计。它为开发者和支持 MCP（Model Context Protocol）协议的 AI 客户端提供了一种受治理（governed）的方式来读取项目文档、检索上下文，并以可审计的方式提交文档修改建议。Atlas 与现有代码仓库协同工作，并不替代 Git、源代码树、问题追踪系统或 AI 客户端本身。资料来源：README.md:1-7

其核心目标包含三个层面：

1. 安全性：所有文档变更必须经过 MCP 服务器校验，禁止 AI 智能体直接覆盖文档文件。资料来源：AGENTS.md:5-7
2. 可追溯性：每次变更都通过 Git 修订版本号（revision hash）+ SQLite 事件日志进行全链路审计。资料来源：CHANGELOG.md:18-19
3. 可治理性：通过统一的 docs.propose_patch → docs.preview_diff → docs.commit_patch 三步工作流，避免"幽灵修改"与误删。资料来源：src/mcp/tools.ts:31-40

当前版本为 0.2.1，要求 Node.js ≥ 22，采用 MIT 协议开源。资料来源：package.json:5-9

系统架构

Atlas 采用分层架构，由 CLI 入口、MCP 服务器层、核心服务层与存储后端四部分组成：

flowchart TB
    Client[MCP 客户端<br/>如 Claude/Cursor] -->|stdio/HTTP| MCP[MCP 服务器层<br/>src/mcp/tools.ts]
    CLI[CLI 入口<br/>init/daemon/mcp-config] --> Core
    MCP --> Core[核心服务层<br/>src/core/*]
    Core --> Git[(Git 存储<br/>修订版本)]
    Core --> SQLite[(SQLite 事件日志<br/>doc_proposals)]
    Core --> Policy[.docs-policy.yml<br/>风险检测策略]
    Core --> Manifest[docs/manifest.yml<br/>项目文档索引]

MCP 服务器层通过 ListToolsRequestSchema 与 CallToolRequestSchema 暴露 12 个工具，例如 docs.list、docs.read、docs.propose_patch、docs.commit_patch、docs.capabilities、atlas.project_identity 等。资料来源：src/mcp/tools.ts:18-78

核心服务层包含 project.ts（项目管理）、risk.ts（风险评估）、templates.ts（初始化模板）、markdown.ts（Markdown 解析）等模块。资料来源：src/core/project.ts:1-3 src/core/risk.ts:1-5

存储后端采用 Git 作为权威修订存储，SQLite 记录提案生命周期（pending → committed / rejected / stale），二者合并形成统一的历史视图。资料来源：CHANGELOG.md:18-20

核心组件

安全管理器

assessPatchRisk() 是风险评估的入口。它在以下场景中标记补丁为高风险：

• 删除内容超过文件总量的 25%
• 移除 Markdown 标题
• 整文件替换
• 修改受保护文件 AGENTS.md 或 .docs-policy.yml
• 删除受保护路径下的文件

资料来源：src/core/risk.ts:10-30

提案存储

doc_proposals 表承载提案的全生命周期管理。当 baseRevision 过期时，提案会被自动标记为 stale，强制智能体重新读取文档后再提交。资料来源：CHANGELOG.md:18-20 src/mcp/tools.ts:31-33

初始化模板

templates.ts 提供四类项目原型：default、saas、cli-tool、mcp-server。每个模板以纯增量方式写入文档——只创建不存在的文件，绝不覆盖已有内容，避免破坏用户既有文档。资料来源：src/core/templates.ts:3-7 README.md:38-42

资料来源：src/core/templates.ts:80-145

MCP 配置导出

mcp-config 命令会生成包含端点 URL、项目绑定、Git 信息与启动命令的 JSON 配置块，供 Claude Desktop、Cursor 等客户端直接消费。资料来源：src/cli/mcp-config.ts:1-15

工作流程

标准的文档修改遵循以下五步流程：

1. 读取：调用 docs.read 获取当前文档内容与 revision 哈希。资料来源：src/mcp/tools.ts:21-24
2. 创建分支（可选）：复杂修改通过 docs.create_branch 创建特性分支。资料来源：src/mcp/tools.ts:30-31
3. 提案补丁：调用 docs.propose_patch，提交统一 diff（必须包含 ---/+++ 头与 @@ hunk，禁止 *** Begin Patch 格式）。资料来源：src/mcp/tools.ts:32-36
4. 预览差异：调用 docs.preview_diff 查看风险等级与审批要求，但不写入。资料来源：src/mcp/tools.ts:37-39
5. 提交补丁：调用 docs.commit_patch 重新校验 baseRevision 后落库；高风险补丁需附加 riskOverride: "accept"。资料来源：src/mcp/tools.ts:43-45

智能体在每次提交前还须对托管文档的导出漂移（export drift）进行分类：判断为本次分支所需、有效同步、或陈旧待回滚，并在提交前向用户报告分类结果。资料来源：AGENTS.md:14-15

常见失败模式

• 基础版本过期：若两次提案之间文档被其他进程修改，提交时会因 baseRevision 不匹配而失败，需重新读取。
• 路径穿越：所有路径校验拒绝 ../、绝对路径与空段，避免越权写入。
• 静默删除：补丁中的删除操作必须在 diff 中显式呈现，pure-deletion 提案被拒绝。
• 未初始化项目：在未运行 xurgo-atlas init 的目录中执行任何 CLI 命令都会返回明确错误。资料来源：CHANGELOG.md:24-28

See Also

• Agent 安全规则（AGENTS.md）
• 工具与 Schema 契约（src/mcp/tools.ts）
• 风险评估规则（src/core/risk.ts）

概述与设计目标

Xurgo Atlas 的 CLI 是项目的本地优先（local-first）入口，承担三项核心职责：项目初始化、守护进程（daemon）生命周期管理，以及为 MCP 客户端生成可直接使用的连接配置。整个 CLI 通过单一可执行文件 xurgo-atlas 暴露（参见 package.json 中的 "bin": { "xurgo-atlas": "./dist/index.js" }），并由 src/index.ts 统一解析与分发到各子命令模块。

CLI 的设计哲学遵循 README 中所述的「Atlas 补充而非替代仓库」原则：它不替代 Git、源码树或 AI 客户端，而是为它们提供一个受治理的、可审计的文档操作通道。xurgo-atlas 命令既支持全局安装（npm install -g xurgo-atlas），也支持通过 npx xurgo-atlas ... 直接试运行，或作为项目本地 devDependency 集成到自动化脚本中（参见 README.md 的 Quick Start 段落）。

命令结构总览

下表汇总了 CLI 在 src/index.ts 中注册并由各 src/cli/*.ts 文件实现的子命令：

所有子命令共享同一组解析规则：项目根目录通过 --project-id 或隐式向上搜索 .xurgo-atlas/project.json 来定位（参见 README.md 描述的「嵌套子目录无需重复参数」行为）。

初始化：`xurgo-atlas init`

init 命令由 src/cli/init.ts 实现，是整个 CLI 流程的入口点。其核心行为包括：

1. 创建项目标记：在项目根目录写入或保留 .xurgo-atlas/project.json，作为后续命令识别项目身份的锚点。
2. 生成起始文档：若仓库中尚不存在 STATUS.md、AGENTS.md、.docs-policy.yml 等关键文件，则创建它们（逻辑见 src/core/project.ts 中 ensureStatusMd / ensureAgentsMd 等辅助函数）。
3. 可选模板：通过 --templates 或 --template <name> 触发 src/core/templates.ts 中定义的文档模板（saas、cli-tool、mcp-server 等），为相应项目类型补充 docs/ 下的策划文档。

init 是严格「纯增量」的：已存在的文档永远不会被覆盖，仅在缺失时补齐。这与 src/core/templates.ts 中所述的「purely additive」原则一致。

守护进程管理：`xurgo-atlas daemon`

daemon 子命令由 src/cli/daemon.ts 实现，负责本地守护进程（HTTP/MCP 服务端）的生命周期。其职责包括启动、停止、查询运行状态，以及暴露供 MCP 客户端连接的端点。

守护进程启动后，CLI 与 MCP 客户端通过该端点交互，承载 docs.list、docs.read、docs.propose_patch、docs.commit_patch 等工具调用（工具定义见 src/mcp/tools.ts）。客户端侧的连接配置由 mcp-config 命令生成：

xurgo-atlas daemon start
xurgo-atlas mcp-config --json

--json 选项确保输出是机器可解析的 JSON，可直接被 MCP 客户端读取而无需额外处理。守护进程以本地优先方式运行——不依赖外部服务，所有审计日志与文档修订都落地在项目本地的 Git 仓库与 SQLite 事件库中。

上下文流与典型工作流

下图描绘了 CLI、子命令模块与 MCP 客户端之间的典型交互流程：

flowchart LR
    A[开发者 / CI] --> B[xurgo-atlas CLI]
    B --> C1[init<br/>src/cli/init.ts]
    B --> C2[daemon<br/>src/cli/daemon.ts]
    B --> C3[mcp-config<br/>src/cli/mcp-config.ts]
    B --> C4[project / status<br/>src/cli/project.ts & status.ts]
    C2 --> D[本地守护进程<br/>HTTP / MCP 端点]
    C3 --> E[MCP 客户端<br/>JSON 配置]
    E --> D
    D --> F[(Git 存储<br/>+ SQLite 事件)]
    C1 --> F

完整的工作流链路为：init 建立项目 → daemon start 启动守护进程 → mcp-config --json 生成客户端配置 → AI 代理通过 MCP 端点调用文档工具 → 所有变更经审计后落地到本地 Git 与 SQLite。

配置生成与版本要求

xurgo-atlas 的运行时要求 Node.js ≥ 22（见 package.json 中的 "engines": { "node": ">=22" }），原因是其依赖 Node 内建的 node:sqlite 模块。CLI 的版本信息来源于 package.json 中的 version 字段；当前线上的稳定版本演进可在 CHANGELOG.md 中追溯，其中 v0.1.0 标志着 MVP 里程碑，确立了 init / daemon / docs.* 工具与 CLI 命令的基本形态。

常见失败模式

• 未初始化项目：若在没有 .xurgo-atlas/project.json 的目录中执行 project list 或 daemon start，CLI 会返回「uninitialized project」错误（参见 CHANGELOG.md 中提到的「Uninitialized project detection」约束）。解决方法：先在该目录运行 xurgo-atlas init。
• Node 版本过低：使用低于 22 的 Node 启动 CLI 时，node:sqlite 无法加载，会导致守护进程立即退出。解决方法：按 AGENTS.md 中的建议执行 nvm use --silent 22，确保处于正确工具链。
• 守护进程端口冲突：当 daemon start 因端口被占用而失败时，需先停止旧实例或调整端口配置，再重新启动。
• 模板参数无效：init --template <name> 仅接受 src/core/templates.ts 中已定义的标识符，传入未知名将直接报错，但不会破坏已有项目状态。

See Also

• AGENTS.md — AI 代理操作文档时的安全规则
• README.md — 项目总览与快速上手
• CHANGELOG.md — 版本演进与已知限制

概览与定位

Xurgo Atlas 通过 Model Context Protocol（MCP）服务器为 AI 客户端提供受治理的文档读写与项目上下文能力。HTTP 守护进程模式是面向 MCP 客户端的常规路径，默认端点为 http://127.0.0.1:3737/mcp；xurgo-atlas server 仍保留用于遗留或直接的 stdio 集成 资料来源：[README.md:62-70]。

服务器的核心职责是：

• 将受控文档（managed docs）操作暴露为一组命名的 MCP 工具，供客户端通过 tools/list 进行实时发现；
• 在守护进程模式下按请求解析项目上下文，避免对单一项目做出隐式假设；
• 提供读取、检索、提案、预览、提交、导出等完整生命周期端点，配套项目身份与根目录安全快照。

xurgo-atlas mcp-config --json 会输出包含端点、项目绑定、git 信息与安全字段的 JSON，客户端可以直接消费 资料来源：[src/cli/mcp-config.ts:20-44]。

MCP 工具清单

src/mcp/tools.ts 中按 MCP tools/list 协议注册的工具体系，覆盖了「读取 → 检索 → 提案 → 预览 → 提交 → 丢弃 → 历史 → 导出 → 身份」全链路 资料来源：[src/mcp/tools.ts:1-100]。下表汇总主要工具及其用途。

每个工具的输入都通过 Zod schema 进行校验，并通过 zodToJsonSchema 暴露为 MCP inputSchema，从而保证客户端侧的强类型发现 资料来源：[src/mcp/tools.ts:1-100]。

客户端集成与配置

守护进程模式下的客户端集成流程如下：

flowchart LR
    A[启动守护进程<br/>xurgo-atlas daemon start] --> B[生成 MCP 配置<br/>xurgo-atlas mcp-config --json]
    B --> C[客户端读取 endpoint<br/>http://127.0.0.1:3737/mcp]
    C --> D[实时发现<br/>tools/list]
    D --> E[受治理生命周期<br/>read → propose → preview → commit → export]
    E --> F[导出前预览<br/>docs.preview_export]
    F --> G[写回工作树<br/>docs.export]

mcp-config 命令在 JSON 输出中内嵌 mcpServers 配置片段，并附带 projectId、projectRoot、projectSource、registeredProjectRoot、git、safety、rootLedger 等字段，使客户端在执行受保护写入或导出前可以先确认项目绑定 资料来源：[src/cli/mcp-config.ts:20-60]。

启动建议的工作流：

1. xurgo-atlas init --project-id my-project 创建或保留 .xurgo-atlas/project.json 标记文件；
2. xurgo-atlas daemon start 启动本地守护进程；
3. xurgo-atlas mcp-config --json 输出供客户端使用的端点信息；
4. 客户端通过 MCP 协议发现工具列表后调用相关方法 资料来源：[README.md:13-22]。

由于已经运行的守护进程可能与静态文档/源码发生漂移，官方建议信任通过实时 MCP 发现获得的工具列表，特别是 tools/list 资料来源：[README.md:62-70]。

安全规则与项目身份

atlas.project_identity 与 docs.status 一起作为运行时的只读项目身份与根目录安全快照，与 mcp-config --json 共同构成「在写入前先确认项目」的防护网。它不取代 xurgo-atlas mcp-config --json，而是作为对等补充信息 资料来源：[src/mcp/tools.ts:80-100]。

仓库在 package.json 中声明了完整的验证脚本（test:fast、test:integration、validate:quick、validate:full、verify:installed），CONTRIBUTING.md 明确指出对 MCP 工具契约、存储、根/工作树安全、托管文档写入/导出、发布相关改动以及文件系统安全敏感行为，应先开 issue 讨论再提交 PR 资料来源：[package.json:30-60]资料来源：[CONTRIBUTING.md:1-20]。

See Also

• Setup — 安装选项、首次运行、初始化与模板
• Daemon, CLI & MCP Reference — 守护进程工作流与 MCP 端点
• Root / Worktree Safety Model — 项目身份与导出边界
• Storage Migration — 本地存储检查与遗留迁移

核心系统：存储、安全与文档管理

一、定位与系统职责

Xurgo Atlas 是一个本地优先（local-first）的文档与项目上下文服务，专为 AI 辅助开发场景设计。它通过 MCP（Model Context Protocol）向 AI 客户端暴露一组受治理的文档读写工具，使文档变更具备可追溯、可回滚、可审计的特性。Atlas 并非要替代 Git、源码树或工单系统，而是作为仓库之上的"文档治理层"，对人类与 AI 共同编辑的文档流进行强约束管理。资料来源：README.md:1-5。

系统的三大核心职责可概括为：

• 治理式文档读写：所有文档变更必须经由 MCP 工具提交，禁止直接覆盖文件。资料来源：AGENTS.md:7-9。
• 可审计变更历史：每次提案（proposal）都拥有独立 ID、风险评级与生命周期，便于追溯与回滚。资料来源：CHANGELOG.md:21-25。
• 根目录与写权限安全：通过 root-ledger 持续观测项目根与 Git worktree 的一致性，避免在错误的根目录执行写操作。资料来源：src/core/root-ledger.ts:14-36。

二、存储层架构

Atlas 的存储由三层组成：Git 内容存储、SQLite 事件日志、项目注册表。Git 存储承担文档内容与历史，SQLite 承担结构化元数据（提案、事件、ledger 观测），注册表负责多项目隔离与发现。资料来源：CHANGELOG.md:10-15。

2.1 存储迁移与自检

storage-migration.ts 与 storage-inspect.ts 负责存储演进期的兼容性问题，例如跨版本 schema 升级、损坏的 SQLite 表修复、以及 Git 仓库与事件日志的偏差检测。这两个模块共同保证了长期使用下的数据可恢复性。资料来源：src/core/storage-migration.ts:1-1、src/core/storage-inspect.ts:1-1。

2.2 注册表（Registry）

registry.ts 维护全局项目注册表，记录每个项目的 projectId、根目录路径、Git 标识等元信息，支持 daemon 模式下多项目并发请求的解析。资料来源：src/core/registry.ts:1-1。

2.3 Git 身份与 Worktree 安全

git-identity.ts 解析当前仓库的 Git 身份（git_common_dir、git_worktree_root、git_head），并将这些信息写入 root_worktree_ledger 表。每次请求都会重新观测，若发现根目录漂移、marker 缺失或 Git 不一致，会通过 warnings_json 暴露给上层。资料来源：src/core/root-ledger.ts:14-36。

三、文档变更生命周期

Atlas 的核心交互流程围绕"读—提案—预览—提交"四步循环展开。下图展示一次典型的文档修改流程：

flowchart LR
    A[docs.read<br/>获取 baseRevision] --> B[docs.propose_patch<br/>提交统一 diff + intent + summary]
    B --> C[docs.preview_diff<br/>风险评级 & 审批要求]
    C -->|高风险| D[人工审核]
    C -->|低风险| E[docs.commit_patch<br/>重新校验 baseRevision]
    D -->|riskOverride: accept| E
    E -->|基线陈旧| F[标记为 stale<br/>拒绝提交]
    E -->|校验通过| G[写入 Git 存储<br/>记录 SQLite 事件]

每次提案都强制要求 baseRevision、intent、summary 与标准 unified diff 四要素，缺一不可。资料来源：AGENTS.md:12-17。基线陈旧（stale base revision）是该流程最常见的失败模式——在提案待审期间若有人直接修改了文件，提交时会被自动拒绝以防冲突。资料来源：CHANGELOG.md:46-49。

四、安全与风险控制

4.1 风险评估规则

risk.ts 中的 assessPatchRisk 函数依据策略文件（policy.ts）对补丁进行多维度风险判定，触发高风险（high-risk）评级的场景包括：资料来源：src/core/risk.ts:1-21：

4.2 AGENTS.md 意图校验

修改 AGENTS.md 时，intent 或 summary 字段必须包含安全/代理规则相关的关键词，否则提案将被拒绝。这一机制防止 AI 代理在未经说明的情况下篡改代理契约本身。资料来源：CHANGELOG.md:55-58。

4.3 路径遍历防护

所有工具调用都通过 zod schema 校验 path 字段，拒绝包含 ../、绝对路径或空段的值，从源头杜绝越权写入。资料来源：CHANGELOG.md:51-54。

4.4 根目录与写安全

root-ledger.ts 持续追踪每个项目的根目录与 Git 状态，输出 safe_for_writes、ambiguous、root_mismatch 等布尔标志。atlas.project_identity 工具向 MCP 客户端暴露这一快照，便于 AI 在执行写操作前自检。资料来源：src/core/root-ledger.ts:1-36。

五、初始化与模板

init 命令创建 .xurgo-atlas/project.json 标记文件，生成 STATUS.md、AGENTS.md、.docs-policy.yml、docs/manifest.yml 等标准入口，并通过 --template 选择性注入模板文件（如 SaaS、CLI 工具）。模板是纯加法的——已存在的文件不会被覆盖。资料来源：README.md:17-31、src/core/templates.ts:54-78。

See Also

• 工具与 MCP 协议
• 策略与风险规则
• CLI 命令参考

Pitfall Log / 踩坑日志

项目：JasonCoate/xurgo-atlas

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Improve daemon port-conflict and already-running UX。

1. 安装坑 · 来源证据：Improve daemon port-conflict and already-running UX

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Improve daemon port-conflict and already-running UX
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/JasonCoate/xurgo-atlas/issues/1 | 来源类型 github_issue 暴露的待验证使用条件。

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/JasonCoate/xurgo-atlas | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/JasonCoate/xurgo-atlas | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/JasonCoate/xurgo-atlas | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/JasonCoate/xurgo-atlas | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/JasonCoate/xurgo-atlas | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/JasonCoate/xurgo-atlas | release_recency=unknown