# https://github.com/JasonCoate/xurgo-atlas 项目说明书

生成时间：2026-06-21 00:16:32 UTC

## 目录

- [Project Overview & Architecture](#page-1)
- [CLI Commands & Daemon Management](#page-2)
- [MCP Server, Tools & Client Integration](#page-3)
- [Core Systems: Storage, Safety & Document Management](#page-4)

<a id='page-1'></a>

## Project Overview & Architecture

### 相关页面

相关主题：[CLI Commands & Daemon Management](#page-2), [MCP Server, Tools & Client Integration](#page-3), [Core Systems: Storage, Safety & Document Management](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/README.md)
- [AGENTS.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/AGENTS.md)
- [CHANGELOG.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/CHANGELOG.md)
- [package.json](https://github.com/JasonCoate/xurgo-atlas/blob/main/package.json)
- [src/mcp/tools.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/mcp/tools.ts)
- [src/core/project.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/project.ts)
- [src/core/risk.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/risk.ts)
- [src/core/templates.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/templates.ts)
- [src/cli/mcp-config.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/cli/mcp-config.ts)
</details>

# Project Overview & Architecture

## 项目定位与目标

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 服务器层、核心服务层与存储后端四部分组成：

```mermaid
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]()

| 模板名称 | 用途 | 关键产出文件 |
|----------|------|--------------|
| `default` | 通用项目 | `docs/project-brief.md` |
| `saas` | SaaS 产品 | `product-brief.md`、`development-workflow.md` |
| `cli-tool` | CLI 工具 | `cli-surface.md`、`development-workflow.md` |
| `mcp-server` | MCP 服务 | （基于默认模板） |

资料来源：[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](https://github.com/JasonCoate/xurgo-atlas/blob/main/AGENTS.md)）
- 工具与 Schema 契约（[src/mcp/tools.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/mcp/tools.ts)）
- 风险评估规则（[src/core/risk.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/risk.ts)）

---

<a id='page-2'></a>

## CLI Commands & Daemon Management

### 相关页面

相关主题：[Project Overview & Architecture](#page-1), [MCP Server, Tools & Client Integration](#page-3), [Core Systems: Storage, Safety & Document Management](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/index.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/index.ts)
- [src/cli/init.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/cli/init.ts)
- [src/cli/daemon.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/cli/daemon.ts)
- [src/cli/mcp-config.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/cli/mcp-config.ts)
- [src/cli/project.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/cli/project.ts)
- [src/cli/status.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/cli/status.ts)
- [package.json](https://github.com/JasonCoate/xurgo-atlas/blob/main/package.json)
- [README.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/README.md)
- [CHANGELOG.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/CHANGELOG.md)
</details>

# CLI Commands & Daemon Management

## 概述与设计目标

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

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

## 命令结构总览

下表汇总了 CLI 在 [src/index.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/index.ts) 中注册并由各 `src/cli/*.ts` 文件实现的子命令：

| 命令 | 实现文件 | 主要功能 | 典型用法 |
|------|----------|----------|----------|
| `--version` / `--help` | [src/index.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/index.ts) | 输出版本与帮助信息 | `xurgo-atlas --version` |
| `init` | [src/cli/init.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/cli/init.ts) | 初始化项目并写入 `.xurgo-atlas/project.json` 标记；可选用模板生成起始文档 | `xurgo-atlas init --project-id my-project` |
| `daemon` | [src/cli/daemon.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/cli/daemon.ts) | 启动 / 停止本地守护进程，提供 MCP 服务端点 | `xurgo-atlas daemon start` |
| `mcp-config` | [src/cli/mcp-config.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/cli/mcp-config.ts) | 打印供 MCP 客户端使用的 JSON 配置 | `xurgo-atlas mcp-config --json` |
| `project` | [src/cli/project.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/cli/project.ts) | 项目级命令（list、history、export 等） | `xurgo-atlas project list` |
| `status` | [src/cli/status.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/cli/status.ts) | 查看项目当前状态 | `xurgo-atlas status` |

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

## 初始化：`xurgo-atlas init`

`init` 命令由 [src/cli/init.ts](https://github.com/Jurgo-atlas/xurgo-atlas/blob/main/src/cli/init.ts) 实现，是整个 CLI 流程的入口点。其核心行为包括：

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

`init` 是严格「纯增量」的：已存在的文档永远不会被覆盖，仅在缺失时补齐。这与 [src/core/templates.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/templates.ts) 中所述的「purely additive」原则一致。

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

`daemon` 子命令由 [src/cli/daemon.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/cli/daemon.ts) 实现，负责本地守护进程（HTTP/MCP 服务端）的生命周期。其职责包括启动、停止、查询运行状态，以及暴露供 MCP 客户端连接的端点。

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

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

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

## 上下文流与典型工作流

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

```mermaid
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](https://github.com/JasonCoate/xurgo-atlas/blob/main/package.json) 中的 `"engines": { "node": ">=22" }`），原因是其依赖 Node 内建的 `node:sqlite` 模块。CLI 的版本信息来源于 [package.json](https://github.com/JasonCoate/xurgo-atlas/blob/main/package.json) 中的 `version` 字段；当前线上的稳定版本演进可在 [CHANGELOG.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/CHANGELOG.md) 中追溯，其中 v0.1.0 标志着 MVP 里程碑，确立了 `init` / `daemon` / `docs.*` 工具与 CLI 命令的基本形态。

## 常见失败模式

- **未初始化项目**：若在没有 `.xurgo-atlas/project.json` 的目录中执行 `project list` 或 `daemon start`，CLI 会返回「uninitialized project」错误（参见 [CHANGELOG.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/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](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/templates.ts) 中已定义的标识符，传入未知名将直接报错，但不会破坏已有项目状态。

## See Also

- [AGENTS.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/AGENTS.md) — AI 代理操作文档时的安全规则
- [README.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/README.md) — 项目总览与快速上手
- [CHANGELOG.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/CHANGELOG.md) — 版本演进与已知限制

---

<a id='page-3'></a>

## MCP Server, Tools & Client Integration

### 相关页面

相关主题：[Project Overview & Architecture](#page-1), [CLI Commands & Daemon Management](#page-2), [Core Systems: Storage, Safety & Document Management](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/mcp/tools.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/mcp/tools.ts)
- [src/cli/mcp-config.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/cli/mcp-config.ts)
- [README.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/README.md)
- [CHANGELOG.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/CHANGELOG.md)
- [AGENTS.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/AGENTS.md)
- [CONTRIBUTING.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/CONTRIBUTING.md)
- [src/core/project.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/project.ts)
- [src/core/templates.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/templates.ts)
- [package.json](https://github.com/JasonCoate/xurgo-atlas/blob/main/package.json)
</details>

# MCP Server, Tools & Client Integration

## 概览与定位

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]()]。下表汇总主要工具及其用途。

| 工具名 | 主要职责 |
| --- | --- |
| `docs.capabilities` | 返回只读的 Atlas 能力摘要，包含受管文档范围、当前可用上下文工具、受保护写入支持以及检索/搜索状态，不需要任何项目特定假设。 |
| `docs.list` / `docs.read` | 列出受追踪文档并返回包含稳定修订哈希的内容，作为后续提案的基准。 |
| `docs.create_branch` | 为多步编辑创建代理分支。 |
| `docs.propose_patch` | 校验并存储标准 unified diff 形式的补丁提案，返回 `proposalId`。 |
| `docs.propose_document` | 在 `docs/atlas/**`、`docs/spec/**` 等受批准路径下创建新的受治理 Markdown 文档，或修复清单中缺失的文件。 |
| `docs.preview_diff` | 通过 `proposalId` 预览已存储提案的差异、风险级别与审批要求，不执行提交。 |
| `docs.list_proposals` | 按分支与生命周期状态过滤查询提案，默认仅返回待处理提案以便发现陈旧草稿。 |
| `docs.discard_proposal` | 通过精确 `proposalId` 丢弃未提交的提案，保留审计历史。 |
| `docs.commit_patch` | 通过 `proposalId` 提交已存储提案，提交前重新校验基准修订，高风险补丁需提供 `riskOverride: "accept"`。 |
| `docs.history` | 查看文档的合并历史。 |
| `docs.restore_file` | 将文件还原到历史中的某个修订。 |
| `docs.export` | 将分支中的文档导出回项目工作树。 |
| `docs.search` | 在受管文档范围内进行检索。 |
| `atlas.project_identity` | 返回紧凑的运行时身份与根目录安全快照，包含项目/根绑定、标记与 Git 身份、写权限判定以及推荐的下一步。 |

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

## 客户端集成与配置

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

```mermaid
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](docs/atlas/setup.md) — 安装选项、首次运行、初始化与模板
- [Daemon, CLI & MCP Reference](docs/atlas/daemon-mcp.md) — 守护进程工作流与 MCP 端点
- [Root / Worktree Safety Model](docs/atlas/root-worktree-safety.md) — 项目身份与导出边界
- [Storage Migration](docs/atlas/storage-migration.md) — 本地存储检查与遗留迁移

---

<a id='page-4'></a>

## Core Systems: Storage, Safety & Document Management

### 相关页面

相关主题：[Project Overview & Architecture](#page-1), [CLI Commands & Daemon Management](#page-2), [MCP Server, Tools & Client Integration](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/core/storage.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/storage.ts)
- [src/core/storage-migration.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/storage-migration.ts)
- [src/core/storage-inspect.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/storage-inspect.ts)
- [src/core/registry.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/registry.ts)
- [src/core/git-store.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/git-store.ts)
- [src/core/git-identity.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/git-identity.ts)
- [src/core/risk.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/risk.ts)
- [src/core/policy.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/policy.ts)
- [src/core/root-ledger.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/root-ledger.ts)
- [src/core/templates.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/templates.ts)
- [src/core/project.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/project.ts)
- [src/mcp/tools.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/mcp/tools.ts)
- [AGENTS.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/AGENTS.md)
- [README.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/README.md)
- [CHANGELOG.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/CHANGELOG.md)
</details>

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

## 一、定位与系统职责

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 的核心交互流程围绕"读—提案—预览—提交"四步循环展开。下图展示一次典型的文档修改流程：

```mermaid
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]()：

| 风险类型 | 触发条件 | 后续要求 |
|----------|----------|----------|
| 受保护文件修改 | `AGENTS.md`、`.docs-policy.yml` | 必须 `riskOverride: "accept"` |
| 过度删除 | 删除内容超过原文件 25% | 高风险告警 |
| 整文件替换 | 公共前后缀极短 | 视为整文件替换 |
| 标题移除 | Markdown 标题被删除 | 触发结构告警 |
| 静默删除 | 补丁仅含 `-` 行无上下文 | 拒绝提交 |

### 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 协议](./tools-and-mcp.md)
- [策略与风险规则](./policy-and-risk.md)
- [CLI 命令参考](./cli-reference.md)

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: JasonCoate/xurgo-atlas; human_manual_source: deepwiki_human_wiki -->