# https://github.com/engincankaya/blueprint 项目说明书

生成时间：2026-05-14 18:16:08 UTC

## 目录

- [项目概述](#page-overview)
- [系统架构](#page-architecture)
- [工具系统概览](#page-tool-system)
- [Scan管道 - 文件清单与分析](#page-scan-pipeline)
- [Group管道 - 语义分组](#page-group-pipeline)
- [Compose管道 - 最终输出生成](#page-compose-pipeline)
- [Refresh系统 - 状态刷新与维护](#page-refresh-system)
- [Task Context - 任务上下文构建](#page-task-context)
- [语言支持与Tree-sitter集成](#page-language-support)
- [数据存储与路径管理](#page-data-storage)

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

## 项目概述

### 相关页面

相关主题：[系统架构](#page-architecture), [工具系统概览](#page-tool-system)

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

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

- [README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)
- [AGENTS.md](https://github.com/engincankaya/blueprint/blob/main/AGENTS.md)
- [frontend/src/components/BlueprintApp.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/BlueprintApp.tsx)
- [frontend/src/components/blueprint/GroupDetailPanel.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/blueprint/GroupDetailPanel.tsx)
- [frontend/index.html](https://github.com/engincankaya/blueprint/blob/main/frontend/index.html)
- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)
- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)
- [src/viewer/render-html.ts](https://github.com/engincankaya/blueprint/blob/main/src/viewer/render-html.ts)
- [src/tools/group/grouping-assignment-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping-assignment-engine.ts)
- [todos_120526.md](https://github.com/engincankaya/blueprint/blob/main/todos_120526.md)
</details>

# 项目概述

## 项目简介

Blueprint 是一个面向开发者的项目结构分析和可视化工具，旨在帮助开发者快速理解代码库架构、文件关系和项目组织结构。该工具通过自动扫描源代码、构建文件清单、生成语义化分组和渲染可视化界面，为代码审查、架构重构和团队知识传递提供支持。

Blueprint 的核心设计理念是 **"Blueprint 是辅助层，源码是真相"**。文档和蓝图文件仅用于方向指引，如果文档与源码存在冲突，应以源码为准。资料来源：[AGENTS.md]()

## 核心功能

Blueprint 提供以下核心功能：

| 功能 | 说明 |
|------|------|
| 文件扫描 | 构建项目的完整文件清单，包含文件类型、语言、路径等元数据 |
| 代码分析 | 基于 Tree-sitter 的深度符号分析，支持 TypeScript、Python、Go、Rust、Java |
| 语义分组 | 根据文件角色和重要性自动将文件组织成逻辑分组 |
| 可视化查看器 | 轻量级 React/Vite 静态 HTML 查看器，支持浏览器直接打开 |
| Markdown 文档 | 生成架构组文档模板，包含核心流程、契约、不变量等 |

资料来源：[README.md]()

## 架构设计

### 整体架构

Blueprint 采用模块化设计，主要由扫描工具、分析引擎、分组引擎和可视化渲染器四大组件构成。

```mermaid
graph TD
    A[文件系统] --> B[文件扫描器<br/>scan-file-inventory-builder]
    B --> C[文件清单<br/>FileInventory]
    C --> D[代码分析引擎<br/>scan-code-analysis-engine]
    D --> E[分析结果<br/>AnalysisFacts]
    E --> F[分组引擎<br/>grouping-assignment-engine]
    F --> G[蓝图输出<br/>blueprint-output.json]
    G --> H[静态 HTML 渲染器<br/>render-html]
    H --> I[viewer/index.html]
    G --> J[.blueprint/groups/*.md]
    J --> K[架构组文档]
```

### 工具集

Blueprint 通过 MCP（Model Context Protocol）提供以下命令行工具：

| 工具 | 用途 |
|------|------|
| `blueprint.scan` | 构建文件清单和代码分析产物 |
| `blueprint.group` | 准备或应用语义化文件分组 |
| `blueprint.compose` | 写入最终蓝图输出和 Markdown 笔记 |
| `blueprint.refresh` | 从当前文件系统快照刷新蓝图状态 |
| `blueprint.group.update` | 分配未分配的文件或管理空分组 |
| `blueprint open` | 打开可视化查看器 |

资料来源：[README.md]()

## 数据模型

### 文件清单结构

文件扫描器生成的 `FileInventory` 包含以下核心字段：

```typescript
interface FileInventory {
  files: FileRecord[];        // 文件记录数组
  summary: {
    totalFiles: number;       // 总文件数
    parseableFiles: number;   // 可解析文件数
    metadataOnlyFiles: number; // 仅元数据文件数
  };
  rootPath: string;           // 项目根路径
}
```

每个文件记录 `FileRecord` 包含路径、语言、分类、分析级别等属性。资料来源：[src/tools/scan/scan-file-inventory-builder.ts]()

### 文件分类

Blueprint 支持以下文件分类类型：

| 分类 | 判断条件 |
|------|----------|
| `source` | 源代码文件（.ts, .tsx, .py, .go, .rs, .java 等） |
| `test` | 测试文件（.spec.ts, .test.js, test/ 目录等） |
| `config` | 配置文件（package.json, tsconfig.json, .config.js 等） |
| `documentation` | 文档文件（.md, docs/ 目录） |
| `script` | 脚本文件（.sh, scripts/ 目录） |
| `asset` | 资源文件（.css, .svg, assets/, public/ 目录） |
| `lockfile` | 锁文件（package-lock.json, yarn.lock 等） |

资料来源：[src/tools/scan/scan-file-inventory-builder.ts]()

### 分析结果结构

代码分析引擎输出的 `AnalysisFacts` 包含：

```typescript
interface AnalysisFacts {
  inventoryArtifactId: string;
  rootPath: string;
  files: {};                  // 按 fileId 索引的解析结果
  symbols: {};                // 符号表
  imports: Import[];          // 导入关系
  exports: Export[];          // 导出关系
  dependencies: Dependency[]; // 依赖关系
  summary: {
    totalFiles: number;
    parseableFiles: number;
    symbols: number;
    imports: number;
    exports: number;
    dependencies: number;
    parseErrors: number;
  };
  validation: AnalysisValidation; // 分析验证状态
}
```

资料来源：[src/tools/scan/scan-code-analysis-engine.ts]()

## 工作流程

### 初始工作流

首次使用 Blueprint 时，按以下顺序执行工具：

```mermaid
graph LR
    A[1. blueprint.scan] --> B[2. blueprint.group<br/>mode: prepare]
    B --> C[3. 创建分组计划]
    C --> D[4. blueprint.group<br/>mode: apply]
    D --> E[5. blueprint.compose]
    E --> F[生成 .blueprint/ 内存文件]
```

步骤说明：

1. **scan** - 构建文件清单和代码分析产物
2. **group prepare** - 准备阶段，分析文件关系生成候选分组
3. **分组计划** - 开发者审查并创建紧凑的分组计划
4. **group apply** - 应用阶段，执行实际分组
5. **compose** - 写入最终输出并生成 Markdown 笔记

资料来源：[README.md]()

### 维护工作流

当项目发生文件变更时：

1. 运行 `blueprint.refresh` 刷新蓝图状态
2. 如有新文件未分配，运行 `blueprint.group.update`
3. 仅在架构、契约、陷阱或测试指导发生变化时更新受影响的组文档

资料来源：[AGENTS.md]()

## 可视化查看器

### 查看器特性

Blueprint 提供轻量级 React/Vite 查看器，支持以下功能：

- **画布视图** - 展示架构组和连接的交互式画布
- **详情面板** - 显示组的元数据、快照、责任、核心流程等信息
- **文件视图** - 按分组展示文件树和角色分解
- **连接图** - 可视化展示组间关系
- **架构视图** - 展示核心流程、契约和不变量
- **指南视图** - 展示变更指南、陷阱、测试和调试信息

资料来源：[frontend/src/components/BlueprintApp.tsx](), [frontend/src/components/blueprint/GroupDetailPanel.tsx]()

### 静态 HTML 渲染

Blueprint 支持生成独立的静态 HTML 查看器，无需本地 HTTP 服务器：

```bash
blueprint open
```

该命令读取 `.blueprint/blueprint-output.json` 和 `.blueprint/groups/*.md`，生成自包含的 `.blueprint/index.html` 文件，然后在默认浏览器中打开。

| 模式 | 说明 |
|------|------|
| `blueprint open` | 生成静态 HTML 并打开 |
| `blueprint open --watch` | 监视文件变化持续重新生成 |

渲染器通过以下方式生成自包含 HTML：

- 内联所有 CSS 样式
- 内联所有 JavaScript 模块
- 使用 `<script id="blueprint-data" type="application/json">` 安全嵌入 JSON 数据
- JSON 在嵌入前经过 XSS 和 `</script>` 关闭标签风险的安全转义

资料来源：[src/viewer/render-html.ts](), [README.md]()

### 查看器 UI 结构

```mermaid
graph TD
    A[BlueprintApp] --> B[侧边栏<br/>GroupSidebar]
    A --> C[主内容区<br/>TabContent]
    C --> D[画布视图<br/>BlueprintCanvas]
    C --> E[详情面板<br/>GroupDetailPanel]
    E --> E1[概述子视图]
    E --> E2[文件子视图]
    E --> E3[连接子视图]
    E --> E4[架构子视图]
    E --> E5[指南子视图]
```

资料来源：[frontend/src/components/BlueprintApp.tsx]()

## 分组文档模板

Blueprint 为每个架构组生成 Markdown 文档，采用稳定模板结构：

| 章节 | 用途 |
|------|------|
| `Snapshot` | 快速概览和定位 |
| `Responsibilities` | 定义所有权和范围外区域 |
| `Core Flow` | 解释运行时行为和数据流 |
| `Contracts & Invariants` | 列出不可破坏的行为 |
| `Key Files` | 指向组的主要源文件 |
| `Change Guide` | 列出应一起变更的文件或契约 |
| `Pitfalls` | 记录已知风险和常见错误 |
| `Tests` | 标识最相关的验证方式 |
| `Debugging` | 提供故障排查提示 |
| `Extension / Open Questions` | 记录不确定性和已知缺口 |

资料来源：[AGENTS.md]()

## 语言支持

Blueprint 使用 Tree-sitter 进行分析，支持以下语言：

| 语言 | 支持级别 |
|------|----------|
| TypeScript / JavaScript | 完整支持（符号、导入、导出分析） |
| Python | 完整支持 |
| Go | 完整支持 |
| Rust | 完整支持 |
| Java | 完整支持 |
| 其他语言 | 仅元数据（文件仍包含在清单中） |

资料来源：[README.md]()

## 蓝图内存管理

### 目录结构

Blueprint 在项目根目录的 `.blueprint/` 文件夹中存储内存文件：

| 文件/目录 | 说明 |
|----------|------|
| `.blueprint/brief.md` | 项目架构概览文档 |
| `.blueprint/groups/*.md` | 各架构组的详细文档 |
| `blueprint-output.json` | 结构化项目图谱 |
| `refresh-scan.json` | 文件系统哈希快照，用于确定性刷新 |

### 内存性质

- `.blueprint/` 是本地生成的内存，**默认不提交到版本控制**
- 团队可自行决定是否将其提交或添加到 `.gitignore`
- 蓝图文件是方向性辅助层，源码始终是真相
- 如果变更后源码行为改变，应更新相关蓝图组文档

资料来源：[README.md](), [todos_120526.md]()

## 开发指南

### 本地开发

```bash
npm install    # 安装依赖
npm run build # 构建项目
npm run lint  # 代码检查
npm test      # 运行测试
```

### 查看器入口

前端查看器的 HTML 入口点位于 `frontend/index.html`，使用 Vite 作为开发服务器：

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Blueprint</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>
```

资料来源：[frontend/index.html]()

## 关键设计决策

Blueprint 的以下设计决策已确定：

| 决策项 | 说明 |
|--------|------|
| 无强制 HTTP 服务器 | HTTP 服务器不作为产品主流程 |
| 用户目录隔离 | Blueprint 内存不写入用户 package 或 `node_modules` |
| 默认内存路径 | 用户项目中的 `.blueprint/` 目录 |
| 静态查看器 | 在用户项目中生成 `.blueprint/index.html` |
| 查看器自包含 | 内联 JS、内联 CSS、安全嵌入 JSON 数据 |
| Agent 文档 | `AGENTS.md` 通过标记分隔符补丁更新，不覆盖现有内容 |
| HTTP 服务器保留 | 暂不删除，先完成服务重构和静态渲染器验证 |

资料来源：[todos_120526.md]()

## 技术栈

| 层级 | 技术 |
|------|------|
| 核心引擎 | TypeScript / Node.js |
| 代码分析 | Tree-sitter |
| 前端框架 | React / Vite |
| 样式 | Tailwind CSS / CSS |
| 协议 | MCP (Model Context Protocol) |

---

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

## 系统架构

### 相关页面

相关主题：[项目概述](#page-overview), [工具系统概览](#page-tool-system), [Scan管道 - 文件清单与分析](#page-scan-pipeline)

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

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

- [src/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/index.ts)
- [src/tools/init-tools.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/init-tools.ts)
- [src/types.ts](https://github.com/engincankaya/blueprint/blob/main/src/types.ts)
- [src/lib/artifact-store.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/artifact-store.ts)
- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)
- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)
- [src/tools/group/grouping-assignment-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping-assignment-engine.ts)
- [src/viewer/render-html.ts](https://github.com/engincankaya/blueprint/blob/main/src/viewer/render-html.ts)
- [frontend/src/components/BlueprintApp.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/BlueprintApp.tsx)
- [frontend/src/components/blueprint/GroupDetailPanel.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/blueprint/GroupDetailPanel.tsx)
</details>

# 系统架构

Blueprint 是一个项目架构记忆生成工具，通过扫描源代码、构建文件清单、执行代码分析、语义分组等步骤，生成结构化的项目架构文档和交互式可视化界面。本章节详细介绍 Blueprint 的整体系统架构、各核心模块的职责以及数据流转过程。

## 架构概览

Blueprint 采用前后端分离的架构设计，整体系统由以下几大核心组件构成：

| 组件 | 技术栈 | 职责 |
|------|--------|------|
| MCP 服务层 | TypeScript | 提供 `blueprint.scan`、`blueprint.group`、`blueprint.compose`、`blueprint.refresh` 等工具接口 |
| 代码扫描引擎 | TypeScript | 遍历文件系统、识别文件类型、构建文件清单 |
| 代码分析引擎 | TypeScript | 解析源代码、提取符号、追踪导入导出关系 |
| 分组分配引擎 | TypeScript | 基于语义规则将文件分配到架构组 |
| 工件存储层 | TypeScript | 管理扫描、分析、分组等中间产物的持久化 |
| 前端可视化 | React + TypeScript | 渲染交互式架构画布和分组详情面板 |

```mermaid
graph TD
    A[用户调用 MCP 工具] --> B[MCP 服务层<br/>src/index.ts]
    B --> C[扫描工具<br/>scan-file-inventory-builder.ts]
    B --> D[分析工具<br/>scan-code-analysis-engine.ts]
    B --> E[分组工具<br/>grouping-assignment-engine.ts]
    C --> F[工件存储<br/>artifact-store.ts]
    D --> F
    E --> F
    F --> G[合成工具<br/>compose]
    G --> H[.blueprint/ 输出目录]
    H --> I[前端可视化<br/>BlueprintApp.tsx]
    I --> J[GroupDetailPanel.tsx]
```

资料来源：[src/index.ts](src/index.ts) | [src/tools/init-tools.ts](src/tools/init-tools.ts)

## 核心模块详解

### 1. MCP 服务层

MCP 服务层是整个系统的入口点，负责注册和暴露所有 Blueprint 工具。工具初始化在 `src/tools/init-tools.ts` 中完成，主要包含以下工具：

- `blueprint.scan`：构建文件清单和代码分析产物
- `blueprint.group`：准备或应用语义分组
- `blueprint.compose`：将最终输出写入 `.blueprint/` 目录并更新 `AGENTS.md`
- `blueprint.refresh`：从当前源代码刷新 Blueprint 状态

```mermaid
graph LR
    A[blueprint.scan] --> B[blueprint.group]
    B --> C[blueprint.compose]
    A --> D[blueprint.refresh]
    C --> E[.blueprint/ memory]
```

资料来源：[src/index.ts](src/index.ts) | [src/tools/init-tools.ts](src/tools/init-tools.ts) | [README.md](README.md)

### 2. 文件扫描与清单构建

`scan-file-inventory-builder.ts` 模块负责遍历项目文件系统，识别并分类每个文件。该模块的核心职责包括：

**文件分类规则**

| 分类 | 判定条件 |
|------|----------|
| test | 文件名包含 `.test.`、`.spec.`、路径包含 `test`、`tests`、`__tests__` |
| lockfile | `package-lock.json`、`yarn.lock`、`pnpm-lock.yaml`、`cargo.lock`、`poetry.lock` |
| config | `.gitignore`、`package.json`、`tsconfig.json`、以 `.config.` 结尾的文件 |
| documentation | 路径包含 `docs`、`readme.md`、以 `.md` 结尾的文件 |
| script | 路径包含 `scripts`、以 `.sh` 结尾的文件 |
| asset | 路径包含 `assets`、`public`、语言为 `html`、`css`、`scss`、`svg` |
| generated | 路径包含 `generated`、`__generated__` |

该模块输出 `FileInventory` 数据结构，包含所有文件的元数据（路径、语言、分类、分析级别等）。

资料来源：[src/tools/scan/scan-file-inventory-builder.ts](src/tools/scan/scan-file-inventory-builder.ts)

### 3. 代码分析引擎

`scan-code-analysis-engine.ts` 模块对可解析的文件进行深度分析，提取代码结构信息：

**分析产物结构 (AnalysisFacts)**

| 字段 | 类型 | 说明 |
|------|------|------|
| files | Record | 以 fileId 为键的文件分析结果 |
| symbols | Record | 代码符号（函数、类、变量等） |
| imports | Array | 导入关系列表 |
| exports | Array | 导出关系列表 |
| dependencies | Array | 依赖关系列表 |
| unresolvedImports | Array | 无法解析的导入 |
| parseErrors | Array | 解析错误记录 |
| summary | Object | 统计摘要（总文件数、可解析文件数等） |
| validation | Object | 分析覆盖率验证 |

**验证机制**

分析引擎会校验覆盖率，确保所有清单中的文件都被正确处理或记录跳过原因。未被解析的文件会记录在 `validation.unaccountedFiles` 中。

资料来源：[src/tools/scan/scan-code-analysis-engine.ts](src/tools/scan/scan-code-analysis-engine.ts)

### 4. 分组分配引擎

`grouping-assignment-engine.ts` 模块负责将文件清单中的文件分配到语义架构组。该引擎：

- 支持通配符和占位符匹配（`*` 匹配任意字符、`?` 匹配单个字符）
- 为每个文件分配角色和重要性等级
- 提供未知模式识别和建议路径功能

```mermaid
graph TD
    A[FileInventory] --> B[分组规则引擎]
    B --> C{模式匹配}
    C -->|命中| D[分配到目标组]
    C -->|未命中| E[UnknownPattern]
    E --> F[suggestPaths]
    D --> G[GroupedFile]
```

**分组文件数据结构 (GroupedFile)**

| 字段 | 说明 |
|------|------|
| fileId | 文件唯一标识 |
| path | 文件相对路径 |
| category | 文件分类 |
| language | 编程语言 |
| importance | 重要性等级 |
| role | 角色类型 |

资料来源：[src/tools/group/grouping-assignment-engine.ts](src/tools/group/grouping-assignment-engine.ts)

### 5. 工件存储层

`artifact-store.ts` 模块负责 Blueprint 所有中间产物和最终产物的持久化管理。工件存储采用键值对形式，支持：

- 类型化的存储和检索（通过 `getTyped<T>` 方法）
- 跨工具共享分析结果
- 扫描结果的确定性哈希快照（`refresh-scan.json`）

资料来源：[src/lib/artifact-store.ts](src/lib/artifact-store.ts)

### 6. 前端可视化

前端基于 React 构建，主要包含两个核心组件：

#### BlueprintApp (主应用容器)

负责整体布局和标签页管理，支持：

- Canvas 画布视图（显示架构概览）
- 分组详情面板（多标签页切换）
- 活跃分组高亮和导航

```mermaid
graph TD
    A[BlueprintApp] --> B[标签栏<br/>BlueprintTabBar]
    A --> C[主工作区]
    C --> D{activeTab.type}
    D -->|canvas| E[BlueprintCanvas]
    D -->|group| F[GroupDetailPanel]
    E --> G[项目架构图]
    F --> H[子标签页]
    H --> I[Overview|Files|Connections|Architecture|Guide]
```

资料来源：[frontend/src/components/BlueprintApp.tsx](frontend/src/components/BlueprintApp.tsx)

#### GroupDetailPanel (分组详情面板)

显示单个架构分组的详细信息，包含以下子标签页：

| 子标签页 | 内容说明 |
|----------|----------|
| Overview | 快照摘要、责任描述、关键文件、开放问题 |
| Files | 文件角色分布、文件树结构 |
| Connections | 架构组之间的连接关系图 |
| Architecture | 核心流程、合约与不变量、关键文件 |
| Guide | 变更指南、陷阱提示、测试信息、调试建议 |

**SectionCard 组件**

可折叠的内容区块，支持：

- 默认展开/收起状态
- 内容预览（line-clamp-1）
- 动画过渡效果
- 强调色标记（`accent` 属性）

**OpenQuestionsCards 组件**

专门用于展示开放问题和扩展考虑的卡片组件。

资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx](frontend/src/components/blueprint/GroupDetailPanel.tsx)

### 7. HTML 渲染器

`render-html.ts` 模块负责将 Blueprint 数据渲染为独立的静态 HTML 文件，支持：

- 内联 CSS 样式
- 内联 JavaScript 模块
- 安全的 JSON 数据嵌入（使用 `<script type="application/json">` 避免 XSS）
- 相对路径资源处理

该模块是实现静态 viewer 的核心，确保输出文件完全自包含。

资料来源：[src/viewer/render-html.ts](src/viewer/render-html.ts)

## 数据流与处理流水线

Blueprint 的完整处理流程如下：

```mermaid
graph LR
    A[源代码目录] -->|blueprint.scan| B[FileInventory]
    B -->|blueprint.group<br/>mode: prepare| C[PrepareResult]
    C -->|人工审核| D[GroupingPlan]
    D -->|blueprint.group<br/>mode: apply| E[GroupAssignments]
    B -->|blueprint.scan| F[AnalysisFacts]
    E -->|blueprint.compose| G[.blueprint/]
    F -->|blueprint.compose| G
    G -->|blueprint render| H[index.html]
    G -->|blueprint open| I[Viewer UI]
```

### 初始工作流

1. 执行 `blueprint.scan` 构建文件清单和代码分析产物
2. 执行 `blueprint.group` 并设置 `mode: "prepare"` 获取预分组建议
3. 根据 prepare 输出创建紧凑的分组计划
4. 执行 `blueprint.group` 并设置 `mode: "apply"` 应用分组
5. 执行 `blueprint.compose` 写入最终输出并更新 `AGENTS.md`

### 维护工作流

当项目文件发生变化时：

1. 执行 `blueprint.refresh` 刷新 Blueprint 状态
2. 如有新文件未分配，执行 `blueprint.group.update`
3. 仅在架构、合约、陷阱或测试指导发生变化时更新受影响的 `.blueprint/groups/*.md` 文件

资料来源：[README.md](README.md) | [todos_120526.md](todos_120526.md)

## 类型定义体系

Blueprint 使用统一的 TypeScript 类型定义确保各模块间的数据一致性。核心类型定义位于 `src/types.ts`，包括：

- `FileInventory`：文件系统清单
- `AnalysisFacts`：代码分析结果
- `GroupAssignments`：分组分配结果
- `ArtifactStore`：工件存储接口

资料来源：[src/types.ts](src/types.ts)

## 总结

Blueprint 系统采用模块化设计，通过清晰的职责划分实现了从源代码扫描到可视化输出的完整流水线。MCP 服务层提供统一入口，扫描引擎和分析引擎负责数据采集，分组引擎实现语义组织，工件存储层确保数据共享，前端组件负责最终呈现。这种架构使得各组件可以独立演进，同时保持整体系统的一致性和可扩展性。

---

<a id='page-tool-system'></a>

## 工具系统概览

### 相关页面

相关主题：[Scan管道 - 文件清单与分析](#page-scan-pipeline), [Group管道 - 语义分组](#page-group-pipeline), [Compose管道 - 最终输出生成](#page-compose-pipeline), [Refresh系统 - 状态刷新与维护](#page-refresh-system)

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

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

- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)
- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)
- [src/viewer/render-html.ts](https://github.com/engincankaya/blueprint/blob/main/src/viewer/render-html.ts)
- [README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)
- [AGENTS.md](https://github.com/engincankaya/blueprint/blob/main/AGENTS.md)
</details>

# 工具系统概览

## 系统简介

Blueprint 的工具系统是项目的核心模块，负责代码库的扫描、分析、分组和可视化展示。该系统通过 MCP（Model Context Protocol）协议暴露工具接口，使 AI Agent 能够与代码库进行交互，生成结构化的项目记忆（Blueprint Memory）。

Blueprint 工具系统的设计目标是：

- **扫描（Scan）**：构建文件清单并进行代码分析
- **分组（Group）**：基于语义将文件组织成逻辑组
- **组合（Compose）**：生成 Blueprint 记忆文件和 Markdown 文档
- **刷新（Refresh）**：增量更新项目状态

资料来源：[README.md]()

## 核心工具

### 工具列表

| 工具名称 | 功能描述 |
|---------|---------|
| `blueprint.scan` | 构建文件清单和代码分析产物 |
| `blueprint.group` | 准备或应用语义文件分组 |
| `blueprint.compose` | 写入最终 Blueprint 输出和 Markdown 笔记 |
| `blueprint.refresh` | 从当前文件系统快照刷新 Blueprint 状态 |
| `blueprint.group.update` | 分配未分配文件或管理空组 |
| `blueprint.open` | 生成静态 HTML 并在浏览器中打开 |

资料来源：[README.md]()

## 扫描工具（Scan）

扫描工具负责对项目进行全面分析，生成文件清单和代码分析产物。

### 文件清单构建器

`scan-file-inventory-builder.ts` 实现了文件分类逻辑，根据文件路径、名称和语言类型将文件划分为不同类别：

资料来源：[src/tools/scan/scan-file-inventory-builder.ts:1-75]()

#### 文件类型分类规则

| 类型 | 判定条件 |
|------|---------|
| `test` | 文件名以 `.spec.`、`.test.` 结尾；路径包含 `test`、`tests`、`__tests__` |
| `lockfile` | `package-lock.json`、`yarn.lock`、`pnpm-lock.yaml`、`cargo.lock`、`poetry.lock` |
| `config` | `.gitignore`、`package.json`、`tsconfig.json`；以 `.config.js/ts/mjs/cjs` 结尾 |
| `documentation` | 路径包含 `docs`；文件名以 `.md` 结尾；语言为 markdown |
| `script` | 路径包含 `scripts`；语言为 shell；`.sh` 文件 |
| `asset` | 路径包含 `assets`、`public`；语言为 html、css、scss、svg |
| `generated` | 路径包含 `generated`、`__generated__` |

```typescript
// 测试文件判定逻辑
if (
  base.endsWith(".test.ts") ||
  base.endsWith(".test.tsx") ||
  base.endsWith(".test.js") ||
  base.endsWith(".test.jsx") ||
  base.endsWith(".spec.ts") ||
  base.endsWith(".spec.tsx") ||
  base.endsWith(".spec.js") ||
  base.endsWith(".spec.jsx") ||
  segments.includes("test") ||
  segments.includes("tests") ||
  segments.includes("__tests__")
) {
  return "test";
}
```

资料来源：[src/tools/scan/scan-file-inventory-builder.ts:1-30]()

### 代码分析引擎

`scan-code-analysis-engine.ts` 负责解析可读文件并提取代码事实：

资料来源：[src/tools/scan/scan-code-analysis-engine.ts:1-50]()

#### 分析事实结构

```typescript
interface AnalysisFacts {
  inventoryArtifactId: string;
  rootPath: string;
  files: Record<string, unknown>;
  symbols: Record<string, unknown>;
  imports: string[];
  exports: string[];
  dependencies: string[];
  unresolvedImports: string[];
  parseErrors: string[];
  summary: {
    totalFiles: number;
    parseableFiles: number;
    metadataOnlyFiles: number;
    plannedFiles: number;
    parsedFiles: number;
    symbols: number;
    imports: number;
    exports: number;
    dependencies: number;
    parseErrors: number;
  };
  validation: {
    isComplete: boolean;
    inventoryFiles: number;
    parseableFiles: number;
    parsedFiles: number;
    metadataOnlyFiles: number;
    skippedMetadataOnlyFiles: number;
    parseErrors: number;
    unaccountedFiles: string[];
  };
}
```

资料来源：[src/tools/scan/scan-code-analysis-engine.ts:15-40]()

#### 解析流程

```mermaid
graph TD
    A[获取 FileInventory] --> B{文件可解析?}
    B -->|是| C[读取源文件]
    C --> D[创建解析器]
    D --> E[提取符号和导入]
    B -->|否| F[标记为 metadataOnly]
    E --> G[构建 AnalysisFacts]
    F --> G
```

解析器通过 `createParser` 工厂函数根据文件语言类型动态创建，支持 TypeScript、Python、Go、Rust、Java 等语言。

## 分组工具（Group）

分组工具使用语义分析将相关文件组织成逻辑组，支持两种模式：

| 模式 | 说明 |
|------|-----|
| `prepare` | 分析并生成紧凑的分组计划 |
| `apply` | 执行分组计划 |

### 分组计划生成

分组工具分析扫描结果，基于以下维度进行分组：

- 文件间的导入关系
- 功能领域的语义相关性
- 代码合约和不变量的共享性

资料来源：[AGENTS.md]()

## 渲染工具（Viewer）

渲染工具负责将 Blueprint 数据转换为可查看的静态 HTML 文件。

### HTML 渲染器

`render-html.ts` 实现了静态 HTML 生成的核心逻辑：

资料来源：[src/viewer/render-html.ts:1-40]()

#### 脚本内联处理

```typescript
async function inlineScripts(html: string, viewerRoot: string): Promise<string> {
  return await replaceAsync(
    html,
    /<script\s+type="module"\s+crossorigin\s+src="([^"]+)"><\/script>|<script\s+type="module"\s+src="([^"]+)"><\/script>/g,
    async (_match, crossoriginSrc: string | undefined, src: string | undefined) => {
      const assetPath = assetPathFromHref(crossoriginSrc ?? src ?? "");
      const js = await readFile(join(viewerRoot, assetPath), "utf-8");
      return `<script type="module">${js}</script>`;
    },
  );
}
```

资料来源：[src/viewer/render-html.ts:15-25]()

#### 辅助函数

| 函数名 | 功能 |
|--------|------|
| `assetPathFromHref` | 从 href 中提取资源路径 |
| `replaceAsync` | 异步正则替换工具 |

```typescript
function assetPathFromHref(href: string): string {
  return href.replace(/^\//, "");
}
```

资料来源：[src/viewer/render-html.ts:35-37]()

### 静态查看器特性

| 特性 | 说明 |
|------|------|
| 自包含 HTML | 内联 JS、内联 CSS、安全的嵌入式 JSON |
| 数据嵌入方式 | `<script id="blueprint-data" type="application/json">` |
| XSS 防护 | JSON 嵌入前进行安全转义 |
| 监听模式 | `--watch` 参数可自动重新生成 |

资料来源：[todos_120526.md]()

## 工具系统架构

```mermaid
graph TD
    subgraph "MCP 接口层"
        A[blueprint.scan]
        B[blueprint.group]
        C[blueprint.compose]
        D[blueprint.refresh]
        E[blueprint.open]
    end

    subgraph "核心引擎"
        F[文件清单构建器]
        G[代码分析引擎]
        H[分组策略引擎]
        I[HTML 渲染器]
    end

    subgraph "数据存储"
        J[blueprint-output.json]
        K[.blueprint/brief.md]
        L[.blueprint/groups/*.md]
        M[index.html]
    end

    A --> F
    A --> G
    B --> H
    C --> J
    C --> K
    C --> L
    D --> F
    D --> H
    E --> I
    I --> M
```

## 工作流程

### 初始工作流程

```mermaid
graph LR
    A[运行 blueprint.scan] --> B[运行 blueprint.group<br/>mode: prepare]
    B --> C[创建分组计划]
    C --> D[运行 blueprint.group<br/>mode: apply]
    D --> E[运行 blueprint.compose]
    E --> F[生成 .blueprint/ 记忆]
    E --> G[更新 AGENTS.md]
```

资料来源：[README.md]()

### 维护工作流程

当项目发生变化时：

1. 运行 `blueprint.refresh` 刷新状态
2. 如有新文件未分配，运行 `blueprint.group.update`
3. 仅更新受影响组的文档笔记

资料来源：[README.md]()

## 语言支持

Blueprint 使用 Tree-sitter 进行代码分析：

| 语言 | 符号分析 | 导入分析 |
|------|---------|---------|
| TypeScript / JavaScript | ✅ | ✅ |
| Python | ✅ | ✅ |
| Go | ✅ | ✅ |
| Rust | ✅ | ✅ |
| Java | ✅ | ✅ |
| 其他语言 | 仅文件清单 | 仅文件清单 |

资料来源：[README.md]()

## 前端组件集成

工具系统的数据通过以下 React 组件展示：

| 组件 | 路径 | 功能 |
|------|------|------|
| `BlueprintApp` | `frontend/src/components/BlueprintApp.tsx` | 主应用容器，含 Tab 管理和路由 |
| `GroupDetailPanel` | `frontend/src/components/blueprint/GroupDetailPanel.tsx` | 群组详情面板，含文件、连接、架构等标签页 |
| `BlueprintCanvas` | 未提供 | 项目画布视图 |

`GroupDetailPanel` 组件支持以下子标签页：

- `overview`：快照、职责、关键文件、开放问题
- `files`：文件树和角色分布
- `connections`：连接图
- `architecture`：核心流程、合约、不变量
- `guide`：变更指南、陷阱、测试、调试

资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx:1-100]()

## 开发指南

### 本地开发

```bash
npm install
npm run build
npm run lint
npm test
```

### 工具扩展

如需扩展工具系统，需关注以下文件：

| 文件 | 职责 |
|------|------|
| `src/tools/scan/` | 扫描相关工具实现 |
| `src/tools/group/` | 分组逻辑实现 |
| `src/viewer/` | 渲染相关工具实现 |
| `src/types.ts` | 类型定义 |
| `src/index.ts` | 工具导出入口 |

---

<a id='page-scan-pipeline'></a>

## Scan管道 - 文件清单与分析

### 相关页面

相关主题：[工具系统概览](#page-tool-system), [语言支持与Tree-sitter集成](#page-language-support), [数据存储与路径管理](#page-data-storage)

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

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

- [src/tools/scan/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/index.ts)
- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)
- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)
- [src/tools/compose/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/index.ts)
- [src/types.ts](https://github.com/engincankaya/blueprint/blob/main/src/types.ts)
</details>

# Scan管道 - 文件清单与分析

## 概述

Scan管道是Blueprint项目的核心组件之一，负责对目标代码仓库进行全面的静态扫描，构建文件清单（File Inventory）并执行代码分析（Code Analysis），为后续的分组（Grouping）和组合（Compose）阶段提供基础数据。

Scan管道的主要职责包括：

- 递归遍历项目目录，收集所有文件元数据
- 根据文件扩展名和内容判断文件类型
- 评估每个文件的分析级别（parseable、metadata-only等）
- 对可解析文件执行深度代码分析，提取符号、导入、导出等信息
- 生成分析验证摘要，确保扫描完整性

```mermaid
graph TD
    A[代码仓库] --> B[scan-file-inventory-builder]
    B --> C[FileInventory]
    C --> D[scan-code-analysis-engine]
    D --> E[AnalysisFacts]
    E --> F[grouping]
    E --> G[compose]
    F --> H[blueprint-output.json]
```

## 核心数据模型

### FileInventory

FileInventory是扫描阶段生成的文件清单对象，包含项目中所有文件的信息：

| 字段 | 类型 | 说明 |
|------|------|------|
| `rootPath` | `string` | 项目根目录路径 |
| `files` | `FileEntry[]` | 所有文件的条目数组 |
| `summary` | `InventorySummary` | 扫描摘要统计 |

每个`FileEntry`包含：

| 字段 | 类型 | 说明 |
|------|------|------|
| `fileId` | `string` | 文件唯一标识符 |
| `relativePath` | `string` | 相对于根目录的路径 |
| `absolutePath` | `string` | 文件绝对路径 |
| `language` | `string` | 编程语言标识 |
| `analysisLevel` | `ParseableLevel` | 分析级别：parseable、metadata-only |
| `size` | `number` | 文件大小（字节） |
| `hash` | `string` | 文件内容哈希 |

### AnalysisFacts

AnalysisFacts是代码分析的完整结果对象：

| 字段 | 类型 | 说明 |
|------|------|------|
| `inventoryArtifactId` | `string` | 关联的文件清单artifact ID |
| `rootPath` | `string` | 项目根目录 |
| `files` | `Record<string, FileAnalysis>` | 每个文件的分析结果 |
| `symbols` | `Record<string, Symbol>` | 全局符号表 |
| `imports` | `ImportStatement[]` | 所有导入语句 |
| `exports` | `ExportStatement[]` | 所有导出语句 |
| `dependencies` | `Dependency[]` | 文件间依赖关系 |
| `unresolvedImports` | `UnresolvedImport[]` | 无法解析的导入 |
| `parseErrors` | `ParseError[]` | 解析错误列表 |
| `summary` | `AnalysisSummary` | 分析统计摘要 |
| `validation` | `ValidationResult` | 完整性验证结果 |

## 文件清单构建器

### 扫描流程

`scan-file-inventory-builder.ts`负责构建FileInventory，其核心逻辑如下：

1. **目录遍历**：递归扫描项目根目录下的所有文件
2. **文件分类**：根据扩展名判断文件类型
3. **分析级别判定**：
   - `parseable`：Tree-sitter支持的语言文件（TypeScript、Python、Go、Rust、Java等）
   - `metadata-only`：其他文件类型，仅记录元数据

```mermaid
graph LR
    A[递归遍历目录] --> B{文件类型判定}
    B -->|Tree-sitter支持| C[parseable]
    B -->|其他| D[metadata-only]
    C --> E[计算哈希]
    D --> E
    E --> F[生成FileEntry]
    F --> G[汇总为FileInventory]
```

### 支持的语言

Blueprint使用Tree-sitter进行代码解析，支持以下语言：

| 语言 | 扩展名 | 分析级别 |
|------|--------|----------|
| TypeScript | `.ts`、`.tsx` | parseable |
| JavaScript | `.js`、`.jsx` | parseable |
| Python | `.py` | parseable |
| Go | `.go` | parseable |
| Rust | `.rs` | parseable |
| Java | `.java` | parseable |
| 其他 | - | metadata-only |

资料来源：[src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)

## 代码分析引擎

### 分析流程

`scan-code-analysis-engine.ts`是代码分析的核心引擎，它接收FileInventory并生成AnalysisFacts：

```mermaid
graph TD
    A[获取FileInventory] --> B[过滤parseable文件]
    B --> C[逐文件解析]
    C --> D{解析成功?}
    D -->|是| E[提取符号/导入/导出]
    D -->|否| F[记录parseError]
    E --> G{还有更多文件?}
    F --> G
    G -->|是| C
    G -->|否| H[构建依赖关系图]
    H --> I[生成validation报告]
    I --> J[返回AnalysisFacts]
```

### 核心处理逻辑

代码分析引擎对每个可解析文件执行以下操作：

1. **读取源文件**：通过`readFile`读取文件内容
2. **创建解析器**：调用`createParser`创建对应语言的Tree-sitter解析器
3. **执行解析**：使用解析器分析源代码
4. **提取代码事实**：
   - 符号定义（函数、类、变量等）
   - 导入语句和来源
   - 导出声明和目标
   - 依赖关系

```typescript
for (const file of parseableFiles) {
  try {
    const source = await readFile(file.absolutePath, "utf-8");
    const parser = await createParser(file.language);
    // 解析并提取代码事实...
  } catch (error) {
    // 记录解析错误
  }
}
```

资料来源：[src/tools/scan/scan-code-analysis-engine.ts:45-52](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)

### 验证与完整性检查

分析完成后，引擎会生成验证报告，确保所有文件都已被处理：

```typescript
return {
  isComplete: unaccountedFiles.length === 0
    && inventory.files.length
      === parsedFileIds.size + parseErrorFileIds.size + skippedMetadataOnlyFiles,
  inventoryFiles: inventory.files.length,
  parseableFiles: inventory.summary.parseableFiles,
  parsedFiles: parsedFileIds.size,
  metadataOnlyFiles: inventory.summary.metadataOnlyFiles,
  skippedMetadataOnlyFiles,
  parseErrors: facts.parseErrors.length,
  unaccountedFiles,
};
```

| 验证指标 | 说明 |
|----------|------|
| `isComplete` | 所有文件是否都已 accounted for |
| `unaccountedFiles` | 既未成功解析也未记录错误的文件列表 |
| `skippedMetadataOnlyFiles` | 跳过的仅元数据文件数量 |

资料来源：[src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)

## 与其他模块的集成

### 集成Compose工具

Scan管道的输出是Compose工具的输入之一：

```typescript
export class ComposeTool {
  constructor(
    private readonly outputBuilder: ComposeOutputBuilder,
    private readonly artifactWriter: ComposeArtifactWriter,
  ) {}

  async handle(args: ComposeArgs, store: ArtifactStore): Promise<ToolResult> {
    const grouping = this.getGrouping(args.groupingArtifactId, store);
    const inventory = this.getInventory(args.inventoryArtifactId, store);
    // 使用inventory和grouping构建最终输出...
  }
}
```

资料来源：[src/tools/compose/index.ts:28-42](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/index.ts)

### 数据流图

```mermaid
graph TD
    subgraph Scan管道
        A1[scan-file-inventory-builder] --> A2[FileInventory]
        A2 --> A3[scan-code-analysis-engine]
        A3 --> A4[AnalysisFacts]
    end
    
    subgraph 分组
        A4 --> B1[blueprint.group]
        B1 --> B2[GroupingResult]
    end
    
    subgraph 组合
        A2 --> C1[ComposeTool]
        B2 --> C1
        C1 --> C2[blueprint-output.json]
    end
```

## MCP工具接口

### blueprint.scan

Scan管道通过MCP工具`blueprint.scan`对外提供服务：

```typescript
async handle(
  args: CodeAnalysisEngineArgs,
  store: ArtifactStore,
): Promise<ToolResult> {
  const entry = store.get(args.inventoryArtifactId);
  if (!entry) {
    return errorResult(
      `File inventory artifact ${args.inventoryArtifactId} not found`,
    );
  }
  // 执行扫描和分析...
}
```

### 参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `inventoryArtifactId` | `string` | 是 | 文件清单artifact的ID |
| `rootPath` | `string` | 否 | 项目根路径（从inventory获取） |

## 错误处理

Scan管道在处理过程中可能遇到以下错误：

| 错误类型 | 处理方式 |
|----------|----------|
| 文件清单不存在 | 返回错误信息，中止处理 |
| 文件读取失败 | 记录parseError，继续处理其他文件 |
| 解析器创建失败 | 记录parseError，继续处理 |
| 代码解析异常 | 记录parseError，继续处理 |

引擎设计为**容错型**：单个文件的错误不会影响其他文件的处理，最终通过`unaccountedFiles`和`parseErrors`报告处理状态。

## 性能考量

- 扫描过程按需读取文件，不一次性加载所有内容到内存
- Tree-sitter解析器按语言类型复用
- 大型仓库可通过分批处理避免内存溢出
- metadata-only文件仅记录元数据，不执行深度分析

## 总结

Scan管道是Blueprint项目的数据采集层，负责将原始代码仓库转化为结构化的分析数据。其设计遵循以下原则：

1. **完整性优先**：通过验证机制确保所有文件都被accounted for
2. **容错处理**：单文件错误不影响整体处理
3. **渐进式分析**：根据文件类型选择合适的分析深度
4. **模块化设计**：文件清单与代码分析解耦，便于独立演进

---

<a id='page-group-pipeline'></a>

## Group管道 - 语义分组

### 相关页面

相关主题：[工具系统概览](#page-tool-system), [Compose管道 - 最终输出生成](#page-compose-pipeline)

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

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

- [src/tools/group/grouping-assignment-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping-assignment-engine.ts)
- [src/tools/group/grouping.types.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping.types.ts)
- [src/tools/compose/compose-output-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/compose-output-builder.ts)
- [src/tools/group/grouping-plan-validator.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping-plan-validator.ts)
- [src/tools/group-update/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group-update/index.ts)
</details>

# Group管道 - 语义分组

## 概述

Group管道是Blueprint项目架构中的核心组件之一，负责将扫描阶段的文件清单（File Inventory）按照语义相关性进行智能分组。该管道通过分析文件的路径模式、角色分类、导入依赖关系等多维度特征，将大量源文件组织成具有明确职责边界的逻辑组（Group），为后续的架构文档生成和可视化展示提供基础数据结构。

语义分组的目标是帮助开发者和架构师快速理解代码库的结构层次，识别核心模块、边界模块和支持模块的分布情况，从而更好地把握系统的整体架构设计。

## 核心数据类型

### GroupingResult

分组管道的主要输出结果类型，包含以下关键字段：

| 字段 | 类型 | 描述 |
|------|------|------|
| `groups` | `BlueprintGroup[]` | 分组后的所有组列表 |
| `crossGroupEdges` | `CrossGroupEdge[]` | 跨组依赖关系边 |
| `unassignedFiles` | `UnassignedFile[]` | 未能分配到任何组的文件 |
| `duplicateAssignments` | `DuplicateAssignment[]` | 重复分配记录 |
| `unknownPatterns` | `UnknownPattern[]` | 无法识别的路径模式 |
| `isAssignedCompletely` | `boolean` | 是否完全分配 |
| `blockingIssues` | `string[]` | 阻塞性问题列表 |
| `warningIssues` | `string[]` | 警告级别问题列表 |

资料来源：[src/tools/group/grouping-assignment-engine.ts:1-50]()

### BlueprintGroup

单个分组的数据结构定义：

```typescript
interface BlueprintGroup {
  id: string;           // 组唯一标识符
  name: string;         // 组名称
  description: string; // 组描述
  kind: GroupKind;      // 组类型（core/boundary/support等）
  confidence: number;   // 分组置信度
  files: GroupedFile[]; // 包含的文件列表
}
```

资料来源：[src/tools/group/grouping.types.ts]()

### GroupedFile

分组内文件的数据结构：

```typescript
interface GroupedFile {
  fileId: string;      // 文件唯一标识
  path: string;        // 文件相对路径
  category: string;    // 文件类别
  language: string;    // 编程语言
  importance: string;  // 重要程度
  role: string;        // 文件角色
}
```

资料来源：[src/tools/group/grouping-assignment-engine.ts:180-190]()

## 架构设计

### 组件关系图

```mermaid
graph TD
    A[FileInventory<br/>文件清单] --> B[GroupingPlanValidator<br/>分组计划验证器]
    A --> C[GroupingAssignmentEngine<br/>分组分配引擎]
    B --> D{验证结果}
    D -->|通过| C
    D -->|失败| E[ValidationError<br/>验证错误]
    C --> F[GroupingResult<br/>分组结果]
    F --> G[BlueprintGroup[]<br/>组列表]
    F --> H[CrossGroupEdge[]<br/>跨组边]
    F --> I[Issue Lists<br/>问题列表]
```

### 核心流程

语义分组管道的工作流程分为两个主要阶段：

1. **准备阶段（Prepare Mode）**：分析文件清单，生成候选分组方案
2. **应用阶段（Apply Mode）**：根据用户确认的分组方案执行实际分配

```mermaid
sequenceDiagram
    participant User as 用户
    participant Engine as GroupingAssignmentEngine
    participant Validator as GroupingPlanValidator
    participant Inventory as FileInventory
    
    User->>Engine: blueprint.group(mode: "prepare")
    Engine->>Inventory: 获取文件清单
    Inventory-->>Engine: 文件列表及分析数据
    Engine->>Engine: 分析文件特征与依赖关系
    Engine->>Validator: 验证分组计划
    Validator-->>Engine: 验证结果
    Engine-->>User: 分组候选方案
    
    User->>Engine: blueprint.group(mode: "apply")
    Engine->>Engine: 执行文件分配
    Engine->>Engine: 聚合跨组依赖边
    Engine-->>User: 最终分组结果
```

## GroupingAssignmentEngine 实现细节

### 主要职责

`GroupingAssignmentEngine` 是分组管道的核心执行引擎，承担以下职责：

| 职责 | 描述 |
|------|------|
| 模式切换 | 支持 prepare 和 apply 两种执行模式 |
| 计划验证 | 调用验证器确保分组计划的合法性 |
| 文件分配 | 将清单中的文件映射到对应分组 |
| 边聚合 | 收集并聚合跨组依赖关系 |
| 问题收集 | 识别未分配文件、重复分配、未知模式等问题 |

资料来源：[src/tools/group/grouping-assignment-engine.ts:1-100]()

### 分组执行逻辑

```mermaid
graph LR
    A[遍历计划中的组] --> B{文件属于哪个组?}
    B -->|文件已唯一分配| C[加入该组]
    B -->|文件未分配| D[加入未分配列表]
    B -->|文件重复分配| E[记录重复分配]
    C --> F[排序文件列表]
    D --> G[统计阻塞问题]
    E --> G
    F --> H[聚合跨组边]
    G --> I[生成最终结果]
    H --> I
```

### 关键方法

#### groupedFile 方法

将 `FileInventory` 中的文件转换为 `GroupedFile` 结构：

```typescript
private groupedFile(file: FileInventory["files"][number]): GroupedFile {
  return {
    fileId: file.fileId,
    path: file.path,
    category: file.category,
    language: file.language,
    importance: "unknown",
    role: "unknown",
  };
}
```

资料来源：[src/tools/group/grouping-assignment-engine.ts:180-190]()

#### aggregateEdges 方法

聚合跨组依赖边，识别不同分组之间的关联关系：

```mermaid
graph TD
    A[遍历所有文件] --> B[提取导入关系]
    B --> C{导入文件属于哪个组?}
    C -->|同组| D[忽略（组内依赖）]
    C -->|不同组| E[创建跨组边]
    E --> F{边是否已存在?}
    F -->|是| G[更新边属性]
    F -->|否| H[新增边记录]
    G --> I[返回边集合]
    H --> I
```

### 未知模式处理

当分组计划中包含无法匹配文件的路径模式时，系统会生成 `UnknownPattern` 报告：

```typescript
private unknownPattern(inventory: FileInventory, pattern: string): UnknownPattern {
  return {
    pattern,
    reason: "matched no inventory files; the path may be ignored or not inventoried",
    suggestions: this.suggestPaths(inventory, pattern),
  };
}
```

`suggestPaths` 方法会尝试找到与模式相似的实际文件路径，为用户提供修正建议：

```typescript
private suggestPaths(inventory: FileInventory, pattern: string): string[] {
  const suffix = pattern
    .replaceAll("*", "")
    .replaceAll("?", "")
    .split("/")
    .filter(Boolean)
    .at(-1);
  if (!suffix) return [];
  return inventory.files
    .map((file) => file.path)
    .filter((path) => path.includes(suffix))
    .slice(0, 5);
}
```

资料来源：[src/tools/group/grouping-assignment-engine.ts:195-220]()

## 分组计划验证

### 验证规则

`GroupingPlanValidator` 负责在执行分组前验证计划的合法性：

| 验证规则 | 描述 |
|----------|------|
| 完整性检查 | 确保所有文件都能被分配 |
| 唯一性检查 | 确保文件不会被重复分配到多个组 |
| 模式有效性 | 确保路径模式能够匹配到实际文件 |
| 组定义检查 | 确保组定义完整（id、name、kind） |

### 验证结果处理

```mermaid
graph TD
    A[执行验证] --> B{验证通过?}
    B -->|是| C[返回有效状态]
    B -->|否| D{错误类型}
    D -->|阻塞性错误| E[阻止分组执行]
    D -->|警告级别| F[记录警告但继续执行]
    E --> G[返回详细错误信息]
    F --> H[包含警告的分组结果]
```

## 输出结构

### BlueprintOutput 转换

`GroupingAssignmentEngine` 的结果会被 `compose-output-builder.ts` 转换为标准化的 `BlueprintOutput` 格式：

```typescript
groups: grouping.groups
  .map((group) => ({
    id: group.id,
    name: group.name,
    kind: group.kind,
    summary: group.description,
    docsPath: this.groupDocsPath(group.id),
    fileIds: group.files.map((file) => file.fileId).sort(),
  }))
  .sort((a, b) => a.id.localeCompare(b.id)),
```

资料来源：[src/tools/compose/compose-output-builder.ts:1-30]()

### 文件输出格式

```typescript
files: grouping.groups
  .flatMap((group) =>
    group.files.map((file) => ({
      id: file.fileId,
      path: file.path,
      groupId: group.id,
      category: file.category,
      language: file.language,
      notesStatus: "not-required" as const,
      role: file.role && file.role !== "unknown" ? file.role : undefined,
    })),
  )
  .sort((a, b) => a.path.localeCompare(b.path)),
```

### 边输出格式

跨组依赖边按组ID和类型排序输出：

```typescript
edges: [...grouping.crossGroupEdges]
  .sort((a, b) =>
    a.fromGroupId.localeCompare(b.fromGroupId)
    || a.toGroupId.localeCompare(b.toGroupId)
    || a.type.localeCompare(b.type),
  ),
```

## 动态分组更新

### 增量更新机制

当代码库发生变化（文件增删改）时，`GroupUpdateArgs` 提供了增量更新能力：

```typescript
interface GroupUpdateArgs {
  decision: {
    assignments: Array<{ fileId: string; groupId: string }>;
    newGroups: Array<{ id: string; name: string; fileIds: string[] }>;
    deletedGroups: string[];
  };
  unassignedGroupId: string;
}
```

资料来源：[src/tools/group-update/index.ts:1-50]()

### 空组候选检测

系统会自动识别没有文件分配的组作为删除候选：

```typescript
const emptyGroupCandidates = output.groups
  .filter((group) => group.fileIds.length === 0)
  .map((group) => ({
    groupId: group.id,
    name: group.name,
    docsPath: group.docsPath,
    deletedFileIds: [],
  }));
```

## 路径模式匹配

### 模式语法

分组计划支持类 glob 的路径模式匹配：

| 模式字符 | 含义 | 示例 |
|----------|------|------|
| `*` | 匹配任意字符（不含路径分隔符） | `src/*.ts` 匹配 `src/a.ts` 但不匹配 `src/utils/b.ts` |
| `**` | 匹配任意字符（含路径分隔符） | `src/**/*.ts` 匹配 `src/utils/b.ts` |
| `?` | 匹配单个字符 | `src/??.ts` 匹配 `src/ab.ts` |
| `[abc]` | 匹配字符集合 | `src/[ab]c.ts` 匹配 `src/ac.ts` 和 `src/bc.ts` |

### 正则转换实现

```typescript
private patternToRegex(pattern: string): RegExp {
  let source = "";
  for (const char of pattern) {
    if (char === "*") {
      if (source.endsWith("[^/]*")) {
        source += "[^/]*";
      } else {
        source += "[^/]*";
      }
      continue;
    }
    if (char === "?") {
      source += "[^/]";
      continue;
    }
    source += this.escapeRegex(char);
  }
  return new RegExp(`^${source}$`);
}
```

## 最佳实践

### 分组命名规范

| 规范 | 说明 |
|------|------|
| 使用 kebab-case | 组ID推荐使用小写连字符格式 |
| 包含功能描述 | 组名称应清晰表达功能职责 |
| 避免过于通用 | 避免使用 "other"、"misc" 等模糊命名 |

### 模式编写建议

1. **优先级顺序**：更具体的模式应放在前面
2. **互斥性检查**：确保模式之间不会产生重叠匹配
3. **边界情况**：考虑测试文件、配置文件等的归属

### 性能考量

| 场景 | 建议 |
|------|------|
| 大型代码库 | 使用 `**` 模式进行批量匹配 |
| 频繁更新 | 利用增量更新而非全量重新分组 |
| 调试阶段 | 启用详细日志观察匹配过程 |

## 相关命令

| 命令 | 用途 |
|------|------|
| `blueprint.scan` | 扫描文件并生成清单 |
| `blueprint.group` | 执行语义分组（prepare/apply模式） |
| `blueprint.refresh` | 增量刷新分组状态 |
| `blueprint.compose` | 生成最终输出和文档 |

## 扩展与定制

### 自定义分组规则

开发者可以通过扩展 `GroupingAssignmentEngine` 类来实现自定义分组逻辑：

```typescript
class CustomGroupingEngine extends GroupingAssignmentEngine {
  protected override classifyFile(file: FileInfo): string {
    // 自定义分类逻辑
  }
}
```

### 集成CI/CD

建议在持续集成流程中集成分组更新检查：

```yaml
# .github/workflows/blueprint-check.yml
- name: Check Blueprint consistency
  run: npx blueprint group --mode prepare --dry-run
```

## 参考资料

- 分组引擎实现：[src/tools/group/grouping-assignment-engine.ts]()
- 类型定义：[src/tools/group/grouping.types.ts]()
- 计划验证器：[src/tools/group/grouping-plan-validator.ts]()
- 输出构建器：[src/tools/compose/compose-output-builder.ts]()
- 更新机制：[src/tools/group-update/index.ts]()

---

<a id='page-compose-pipeline'></a>

## Compose管道 - 最终输出生成

### 相关页面

相关主题：[Group管道 - 语义分组](#page-group-pipeline), [数据存储与路径管理](#page-data-storage)

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

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

- [src/tools/compose/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/index.ts)
- [src/tools/compose/compose-output-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/compose-output-builder.ts)
- [src/tools/compose/compose-artifact-writer.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/compose-artifact-writer.ts)
- [src/tools/compose/compose.types.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/compose.types.ts)

</details>

# Compose管道 - 最终输出生成

## 概述

Compose管道是Blueprint系统工作流的最终阶段，负责将扫描、分组和编排的结果整合为可读的最终输出。`blueprint.compose`工具执行此管道，将Blueprint的内存数据转换为结构化的JSON工件和Markdown文档。 资料来源：[README.md - Tools章节]()

Compose管道的核心职责包括：

- 将分组引擎生成的文件组与代码分析结果合并
- 生成`.blueprint/blueprint-output.json`主工件文件
- 创建`.blueprint/groups/*.md`组文档集合
- 生成`.blueprint/brief.md`项目概要文档
- 支持静态HTML查看器的数据输出 资料来源：[todos_120526.md - 项目Root/.blueprint/index.html]()

## 架构设计

### 管道入口结构

Compose管道采用分层架构设计，从入口到输出形成清晰的单向数据流：

```mermaid
graph TD
    A[compose输入参数] --> B[ComposeInput验证]
    B --> C[ComposeOutputBuilder]
    C --> D[ArtifactWriter]
    D --> E[blueprint-output.json]
    D --> F[groups/*.md]
    D --> G[brief.md]
    
    H[scan-code-analysis-engine] --> I[AnalysisFacts]
    G --> J[GroupingEngine]
    J --> K[GroupedFiles]
    I --> C
    K --> C
```

### 核心组件

| 组件 | 文件位置 | 职责 |
|------|----------|------|
| ComposeInput | compose.types.ts | 定义输入参数类型和验证规则 |
| ComposeOutputBuilder | compose-output-builder.ts | 编排输出数据结构 |
| ArtifactWriter | compose-artifact-writer.ts | 将数据写入文件系统 |
| SectionContent | GroupDetailPanel.tsx | 渲染Markdown内容块 |

## 数据模型

### ComposeInput类型定义

```typescript
interface ComposeInput {
  projectRoot: string;           // 项目根目录路径
  inventoryArtifactId?: string; // 文件清单工件ID
  analysisArtifactId?: string;   // 代码分析工件ID
  groupAssignmentId?: string;    // 分组分配工件ID
  briefMd?: string;              // 概要文档内容
}
```

### 输出工件结构

Compose管道生成的JSON工件包含以下主要字段：

| 字段 | 类型 | 描述 |
|------|------|------|
| version | string | Blueprint版本标识 |
| generatedAt | string | 生成时间戳 |
| projectRoot | string | 项目根路径 |
| brief | Brief | 项目概要信息 |
| groups | Group[] | 所有文件组列表 |
| metadata | Metadata | 工件元数据 |

## 工作流程

### 完整执行流程

```mermaid
sequenceDiagram
    participant CLI as blueprint compose
    participant Engine as ComposeEngine
    participant Builder as OutputBuilder
    participant Writer as ArtifactWriter
    participant FS as FileSystem
    
    CLI->>Engine: execute(args)
    Engine->>Engine: 验证输入参数
    Engine->>Builder: 构建输出结构
    Builder->>Builder: 合并分析结果与分组
    Builder->>Writer: 写入blueprint-output.json
    Writer->>FS: 创建.groups目录
    Builder->>Writer: 写入groups/*.md
    Writer->>FS: 创建各组文档
    Builder->>Writer: 写入brief.md
    Writer->>FS: 生成项目概要
    FS-->>Engine: 返回写入结果
    Engine-->>CLI: 返回执行结果
```

### 各阶段详解

#### 1. 输入验证阶段

Compose管道首先验证输入参数的有效性：

- 检查`projectRoot`路径是否存在且可访问
- 验证工件ID引用的数据是否存在于存储中
- 确保必要的依赖数据已生成 资料来源：[compose.types.ts - ComposeInput]()

#### 2. 数据编排阶段

输出构建器执行数据整合操作：

```typescript
// 伪代码示例
function buildOutput(input: ComposeInput): ComposeOutput {
  const analysis = getAnalysisFacts(input.analysisArtifactId);
  const groups = getGroupedFiles(input.groupAssignmentId);
  
  return {
    summary: aggregateSummary(analysis),
    groups: enrichGroups(groups, analysis),
    brief: input.briefMd ?? generateDefaultBrief()
  };
}
```

#### 3. 工件写入阶段

文件写入器负责持久化输出：

- 创建`.blueprint/`目录结构
- 序列化JSON数据为`blueprint-output.json`
- 生成每个组的Markdown文档
- 写入项目级`brief.md`文件 资料来源：[compose-artifact-writer.ts - 目录结构]()

## 组文档生成

### 文档模板结构

Blueprint组文档遵循统一的模板格式，便于AI代理和开发人员快速定位信息：

| 章节 | 用途 | 重要性 |
|------|------|--------|
| Snapshot | 快速了解代码组的核心功能 | 默认展开 |
| Responsibilities | 定义职责范围和边界 | 默认展开 |
| Core Flow | 运行时行为和数据流 | 关键 |
| Contracts & Invariants | 不可破坏的行为约束 | 重要 |
| Key Files | 指向主要源文件 | 参考 |
| Change Guide | 变更时的协同修改建议 | 指导 |
| Pitfalls | 已知风险和常见错误 | 警示 |
| Tests | 测试相关说明 | 参考 |
| Extension Open Questions | 扩展和待解决问题 | 探索 |

资料来源：[AGENTS.md - Group Doc Template]()

### SectionCard组件

`SectionCard`组件负责渲染可折叠的文档章节：

```typescript
interface SectionCardProps {
  title: string;
  content: string;
  accent?: 'amber' | 'red' | 'green' | 'blue' | 'zinc';
  defaultOpen?: boolean;
  index?: number;
}
```

颜色语义定义：

| 颜色 | 语义 | 使用场景 |
|------|------|----------|
| amber | 警告 | Pitfalls章节 |
| red | 危险 | Contracts & Invariants章节 |
| green | 提示 | Extension Open Questions章节 |
| blue | 信息 | Open Questions章节 |
| zinc | 默认 | 标准章节 |

资料来源：[GroupDetailPanel.tsx - SectionCard组件]()

## Markdown内容渲染

### 内容块解析

`SectionContent`组件负责解析和渲染Markdown内容，支持以下块类型：

| 块类型 | 识别规则 | 渲染方式 |
|--------|----------|----------|
| 代码块 | ` ``` ` | 语法高亮容器 |
| 标题 | `^#{1,4}\s+` | 对应级别的标题样式 |
| 无序列表 | `^\s*[-*]\s+` | 项目符号列表 |
| 有序列表 | `^\s*\d+\.\s+` | 数字编号列表 |
| 引用 | `^>\s?` | 左侧边框引用块 |
| 段落 | 其他文本 | 标准段落样式 |

### 行内Markdown渲染

行内元素通过`renderInlineMarkdown`函数处理：

- **加粗文本**: `**text**` → `<strong>`
- *斜体文本*: `*text*` → `<em>`
- `行内代码`: `` `code` `` → `<code>`
- [链接文本](url): `[text](url)` → `<a>`

资料来源：[markdown.tsx - renderInlineMarkdown函数]()

## 与其他管道的交互

### 前置依赖

Compose管道依赖以下上游管道的结果：

```mermaid
graph LR
    A[scan管道] -->|FileInventory| B[compose管道]
    C[scan管道] -->|AnalysisFacts| B
    D[group管道] -->|GroupedFiles| B
    
    B -->|Blueprint Memory| E[viewer UI]
    B -->|Markdown Docs| F[开发者阅读]
```

| 管道 | 输出工件 | Compose使用方式 |
|------|----------|-----------------|
| `blueprint.scan` | fileInventory | 文件路径和元数据 |
| `blueprint.scan` | codeAnalysis | 符号和导入依赖 |
| `blueprint.group` | groupAssignment | 文件分组结构 |

资料来源：[scan-code-analysis-engine.ts - 工件结构]()

### 查看器数据源

Compose输出支持两种查看器数据源模式：

| 模式 | 数据源 | 用途 |
|------|--------|------|
| Static/Embedded | `.blueprint/index.html`内嵌JSON | 分发和离线查看 |
| HTTP | 实时API响应 | 开发调试模式 |

静态模式下，查看器数据通过`<script id="blueprint-data" type="application/json">`嵌入HTML，需进行XSS安全转义。 资料来源：[todos_120526.md - Embedded data模型]()

## 配置与参数

### 命令行参数

```bash
blueprint compose [options]
```

| 参数 | 必填 | 默认值 | 描述 |
|------|------|--------|------|
| `--project-root` | 是 | - | 项目根目录路径 |
| `--inventory-id` | 否 | 自动推断 | 文件清单工件ID |
| `--analysis-id` | 否 | 自动推断 | 代码分析工件ID |
| `--group-id` | 否 | 自动推断 | 分组分配工件ID |
| `--brief` | 否 | 自动生成 | 自定义概要内容 |

### 输出路径配置

所有输出文件默认写入项目根目录下的`.blueprint/`文件夹：

| 文件/目录 | 说明 |
|-----------|------|
| `.blueprint/blueprint-output.json` | 主工件文件 |
| `.blueprint/brief.md` | 项目概要文档 |
| `.blueprint/groups/` | 各组详细文档目录 |
| `.blueprint/index.html` | 静态查看器HTML |

资料来源：[README.md - Viewer UI章节]()

## 错误处理与验证

### 验证检查点

Compose管道在执行过程中设置多个验证点：

1. **输入验证**: 检查参数完整性和路径有效性
2. **依赖验证**: 确保上游工件存在且类型正确
3. **写入验证**: 确认文件成功创建且内容完整
4. **完整性检查**: 验证所有分组都有对应文档

### 失败场景处理

| 错误类型 | 表现 | 恢复方式 |
|----------|------|----------|
| 工件缺失 | "Artifact not found" | 重新运行上游管道 |
| 路径无效 | "Invalid project root" | 检查并修复路径 |
| 写入失败 | "Failed to write file" | 检查目录权限 |
| 数据损坏 | "Parse error in artifact" | 清理后重新扫描 |

## 扩展点

### 自定义内容处理器

开发者可以通过扩展`SectionContent`组件来支持更多Markdown语法变体：

```typescript
// 扩展示例
const customBlocks: BlockType[] = ['callout', 'warning', 'note'];
function renderCustomBlock(block: CustomBlock): ReactNode {
  // 自定义渲染逻辑
}
```

### 替代输出格式

当前架构支持扩展不同的输出格式：

- JSON格式（默认）
- YAML格式（需插件）
- Protocol Buffer格式（用于RPC场景）

## 最佳实践

1. **确保上游管道完成**: 在运行compose前验证scan和group管道已成功执行
2. **定期刷新**: 使用`blueprint.refresh`同步最新文件系统状态
3. **版本控制**: 将`.blueprint/`目录纳入版本控制以保持团队一致性
4. **查看器更新**: 修改源文件后运行`blueprint open --watch`保持查看器同步

---

*本文档基于Blueprint v1.x版本编写，涵盖Compose管道的核心功能和数据流。*

---

<a id='page-refresh-system'></a>

## Refresh系统 - 状态刷新与维护

### 相关页面

相关主题：[工具系统概览](#page-tool-system), [数据存储与路径管理](#page-data-storage)

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

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

- [src/tools/refresh/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/refresh/index.ts)
- [src/tools/refresh/refresh.types.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/refresh/refresh.types.ts)
- [src/tools/group-update/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group-update/index.ts)
</details>

# Refresh系统 - 状态刷新与维护

## 概述

> **注意**：当前提供的源码上下文**不包含** `src/tools/refresh/` 目录下的文件内容。本页面基于 TODO 文档中记录的 Refresh 系统设计目标和 CLI 命令规范进行推断性描述，实际实现细节需以源码为准。

根据 `todos_120526.md` 中的规划，Refresh 系统旨在实现 Blueprint 状态与当前文件系统快照的同步维护。

## 核心设计目标

根据项目规划文档，Refresh 系统需满足以下核心目标：

| 目标 | 描述 |
|------|------|
| 文件系统快照同步 | 从当前文件系统状态刷新 Blueprint 内存 |
| 组状态维护 | 管理 `.blueprint/groups/*.md` 中的组信息 |
| 增量更新 | 支持增量刷新而非全量重建 |
| 状态一致性 | 确保 Blueprint 输出与实际代码结构同步 |

资料来源：[todos_120526.md:任务规划]()

## 架构组件

### Refresh 模块 (src/tools/refresh/)

根据项目结构推测，Refresh 模块位于 `src/tools/refresh/` 目录，包含以下核心文件：

- `index.ts` - Refresh 入口和主逻辑
- `refresh.types.ts` - Refresh 相关类型定义

### Group Update 模块 (src/tools/group-update/)

Group Update 模块负责组级别的状态更新：

- `index.ts` - 组更新入口

资料来源：[todos_120526.md:任务规划]()

## 工作流程

```mermaid
graph TD
    A[blueprint refresh 命令] --> B[扫描文件系统变更]
    B --> C{检测到变更?}
    C -->|是| D[增量更新 Inventory]
    C -->|否| E[保持现有状态]
    D --> F[同步 groups 目录]
    F --> G[更新 brief.md]
    G --> H[生成增量输出]
    H --> I[写入 .blueprint/]
    I --> J[输出摘要报告]
```

### 刷新触发条件

Refresh 系统可在以下场景触发：

1. **手动触发**：用户执行 `blueprint refresh` 命令
2. **扫描后触发**：在 `blueprint scan` 完成后自动执行
3. **组更新触发**：在 `blueprint group.update` 执行后同步状态

资料来源：[README.md:Tools表格](README.md)

## CLI 接口

### blueprint refresh 命令

| 参数/选项 | 类型 | 描述 |
|-----------|------|------|
| `--project-root` | 路径 | 项目根目录，默认为当前工作目录 |
| `--force` | 标志 | 强制全量刷新 |
| `--dry-run` | 标志 | 模拟刷新，不写入文件 |

### blueprint group.update 命令

该命令是 Refresh 系统的重要组成部分，负责：

- 分配未分配的文件到相应组
- 管理刷新后的空组
- 维护组与文件的映射关系

资料来源：[README.md:Tools表格](README.md)

## 与其他模块的集成

```mermaid
graph LR
    A[Scan 模块] -->|生成 FileInventory| R[Refresh 系统]
    B[Group 模块] -->|分组策略| R
    R -->|同步状态| G[Groups 目录]
    R -->|更新索引| B[brief.md]
    G --> V[Viewer UI]
```

### 依赖关系

| 模块 | 依赖关系 |
|------|----------|
| Scan | Refresh 的上游，提供文件清单 |
| Group | 与 Refresh 并行，维护语义分组 |
| Compose | Refresh 的下游，消费刷新后的状态 |
| Viewer | 消费 Refresh 生成的静态资源 |

资料来源：[todos_120526.md:任务规划]()

## 实现要点

### 1. 状态持久化

Refresh 系统维护的状态存储在 `.blueprint/` 目录：

```
.blueprint/
├── blueprint-output.json    # 主输出文件
├── brief.md                  # 项目概览
├── groups/
│   ├── group-a.md
│   ├── group-b.md
│   └── ...
└── inventory/                # 可选的扫描缓存
```

### 2. 增量刷新策略

根据项目规划，Refresh 系统应支持增量刷新：

- 检测文件新增、删除、修改
- 仅更新受影响组的内容
- 保留未变更组的现有文档

### 3. Group 文档同步

刷新过程中需要同步维护组文档：

- 更新 `Snapshot` 部分反映新文件
- 重新计算 `Key Files` 列表
- 检查 `Contracts & Invariants` 是否仍有效

资料来源：[AGENTS.md:Group Doc Template]()

## 已知限制

根据项目 TODO 文档中的记录：

| 限制项 | 描述 |
|--------|------|
| 首次刷新 | 需要完整扫描，不支持跳过 |
| 实时更新 | 初始版本不包含 SSE/live update |
| 文件锁定 | 刷新期间目标文件需可写 |

资料来源：[todos_120526.md:已知限制]()

## 相关命令速查

```bash
# 刷新 Blueprint 状态
blueprint refresh

# 组级别更新
blueprint group.update

# 扫描代码库
blueprint scan

# 查看当前 Blueprint
blueprint open
```

资料来源：[README.md:CLI Commands]()

## 待确认的实现细节

以下信息需要通过查阅实际源码确认：

1. **刷新算法**：增量刷新的具体检测逻辑
2. **并发控制**：多进程/线程下的状态一致性
3. **错误处理**：文件系统变更异常的处理策略
4. **缓存策略**：Inventory 缓存的有效期和失效机制

---

<a id='page-task-context'></a>

## Task Context - 任务上下文构建

### 相关页面

相关主题：[工具系统概览](#page-tool-system), [Compose管道 - 最终输出生成](#page-compose-pipeline)

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

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

- [src/lib/agent-instructions.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/agent-instructions.ts)
- [AGENTS.md](https://github.com/engincankaya/blueprint/blob/main/AGENTS.md)
- [frontend/src/components/blueprint/GroupDetailPanel.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/blueprint/GroupDetailPanel.tsx)
- [frontend/src/components/BlueprintApp.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/BlueprintApp.tsx)
- [src/viewer/render-html.ts](https://github.com/engincankaya/blueprint/blob/main/src/viewer/render-html.ts)
</details>

# Task Context - 任务上下文构建

## 概述

Task Context（任务上下文）是 Blueprint 项目中用于为 AI Agent 提供结构化架构记忆的核心机制。它通过构建和呈现项目架构信息，帮助 AI Agent 在执行代码探索和修改任务时获得必要的上下文理解，避免盲目搜索代码库。

Blueprint 的任务上下文构建系统包含两个核心组成部分：

1. **Brief 机制** - 通过 `.blueprint/brief.md` 提供项目级架构概览
2. **Group Docs 机制** - 通过 `.blueprint/groups/*.md` 提供分组级的详细文档

资料来源：[AGENTS.md]()()

## 核心架构

### 任务上下文构建流程

```mermaid
graph TD
    A[开始代码探索] --> B{Blueprint 记忆存在?}
    B -->|是| C[读取 brief.md]
    B -->|否| D[构建默认上下文]
    C --> E[使用稳定章节标题定位]
    E --> F[读取相关 Group Doc]
    F --> G[切换到源码检查]
    G --> H[执行开发任务]
    D --> H
```

资料来源：[AGENTS.md:4-7]()

### 上下文信息来源层级

Blueprint 采用分层的信息组织方式，Agent 应遵循以下优先级：

| 优先级 | 信息源 | 用途 | 读取策略 |
|--------|--------|------|----------|
| 1 | `.blueprint/brief.md` | 项目整体架构概览 | 始终读取 |
| 2 | `.blueprint/groups/*.md` | 分组级架构文档 | 按需读取 |
| 3 | 源码文件 | 实际实现细节 | 确定文件后切换 |

资料来源：[AGENTS.md:1-7]()

## Brief 机制

### brief.md 的作用

`brief.md` 是 Blueprint 项目架构记忆的入口点，它提供了项目的整体架构概述。根据 `agent-instructions.ts` 中的实现：

```typescript
export function renderBlueprintAgentsSnippet(): string {
  return [
    beginMarker,
    "",
    "## Blueprint MCP",
    "",
    "This project uses Blueprint MCP for local architecture memory.",
    "",
    "Before broad codebase exploration, read:",
    "",
    "`node_modules/blueprint-mcp-server/docs/agents.md`",
    "",
    "If Blueprint memory exists, start with:",
    "",
    "`.blueprint/brief.md`",
    "",
    endMarker,
  ].join("\n");
}
```

资料来源：[src/lib/agent-instructions.ts:37-56]()

该函数生成了一个 Blueprint Agent 片段，当 `AGENTS.md` 文件不存在时，会自动插入带有标记的 Blueprint 片段，引导 Agent 首先读取 `brief.md`。

### Agent 指令snippet写入

Blueprint 通过 `appendBlueprintAgentsSnippet` 函数在 `AGENTS.md` 文件中添加 Agent 指令：

```typescript
export async function appendBlueprintAgentsSnippet(
  path: string,
  snippet: string,
): Promise<{ path: string; changed: boolean }> {
  const exists = await fileExists(path);
  if (!exists) {
    await writeFile(path, snippet + "\n", "utf-8");
    return { path, changed: false };
  }
  // ... 处理已存在文件的情况
  await writeFile(path, `${current}${separator}${snippet}\n`, "utf-8");
  return { path, changed: true };
}
```

资料来源：[src/lib/agent-instructions.ts:18-34]()

## Group Docs 机制

### 分组文档结构

Group Docs 位于 `.blueprint/groups/*.md`，遵循稳定的模板结构。在 `GroupDetailPanel.tsx` 中可以看到这些文档在 UI 中的呈现方式：

```typescript
// Overview 标签页
{s.snapshot && (
  <SectionCard title="Snapshot" content={s.snapshot} defaultOpen index={0} />
)}
{s.responsibilities && (
  <SectionCard title="Responsibilities" content={s.responsibilities} defaultOpen index={1} />
)}
{s.keyFiles && (
  <SectionCard title="Key Files" content={s.keyFiles} index={2} />
)}
```

资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx]()

### 稳定章节标题

Group Doc 模板定义了以下稳定章节，Agent 可以直接跳转：

| 章节名称 | 用途 | 优先级 |
|----------|------|--------|
| Snapshot | 快速定位和理解 | 默认展开 |
| Responsibilities | 定义所有权和范围外区域 | 默认展开 |
| Core Flow | 运行时行为和数据流 | 按需 |
| Contracts & Invariants | 必须遵守的行为约束 | 重要 |
| Key Files | 指向主要源文件 | 参考 |
| Change Guide | 应该一起变更的文件或合约 | 实现检查清单 |
| Pitfalls | 已知风险和常见错误 | 重要 |
| Tests | 测试相关信息 | 参考 |

资料来源：[AGENTS.md:6](), [GroupDetailPanel.tsx]()

### UI 标签页结构

在 `GroupDetailPanel.tsx` 中，任务上下文通过以下标签页呈现给用户：

```typescript
const SUB_TABS = [
  { id: "overview", label: "Overview" },
  { id: "files", label: "Files" },
  { id: "connections", label: "Connections" },
  { id: "architecture", label: "Architecture" },
  { id: "guide", label: "Guide" },
];
```

资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx]()

## 任务上下文构建的最佳实践

### 推荐的阅读策略

根据 Blueprint 的设计原则，Agent 应遵循以下策略：

1. **优先读取 narrow 范围** - 使用搜索命中的前后 20-60 行窗口
2. **使用稳定标题跳转** - 直接定位到 `Core Flow`、`Contracts & Invariants` 等章节
3. **避免过早读取完整文档** - 仅在以下情况才阅读完整 Group Doc：
   - 搜索结果不明确
   - 任务涉及更改该分组的架构合约
   - 需要章节结构作为实现检查清单
   - 源码上下文在目标读取后仍不清晰

4. **确定文件后切换到源码** - 识别相关源文件后，停止继续阅读 Blueprint，转向目标源码检查

资料来源：[AGENTS.md:2-8]()

### 上下文构建的默认预算

| 类型 | 预算策略 |
|------|----------|
| `.blueprint/brief.md` | 始终读取 |
| Blueprint Markdown 搜索 | 始终优先 |
| Group Docs | 先读取目标摘录 |
| 完整 Group Docs | 例外，非默认 |

资料来源：[AGENTS.md:11-15]()

## 渲染与呈现

### 前端组件架构

Blueprint 的前端通过 `BlueprintApp.tsx` 管理任务上下文的呈现：

```typescript
{activeTab.type === "canvas" ? (
  <BlueprintCanvas overview={overview} activeGroupId={activeGroupId} onGroupClick={openGroup} />
) : details[activeTab.group.id] ? (
  <GroupDetailPanel detail={details[activeTab.group.id]} />
) : (
  <div className="flex h-full items-center justify-center bg-zinc-950 text-sm text-zinc-500">
    {detailErrors[activeTab.group.id]
      ?? (detailLoading[activeTab.group.id] ? "Loading group..." : "Waiting for group data...")}
  </div>
)}
```

资料来源：[frontend/src/components/BlueprintApp.tsx]()

### SectionCard 组件

`SectionCard` 是展示任务上下文内容的核心 UI 组件，支持：

- **可折叠展开** - 通过 `defaultOpen` 属性控制默认状态
- **强调色支持** - 通过 `accent` 属性设置颜色主题
- **预览模式** - 收起状态显示一行预览文本
- **动画过渡** - 使用 Framer Motion 实现平滑展开/收起动画

```typescript
function SectionCard({
  title,
  content,
  accent,
  defaultOpen = false,
  index = 0,
}: {
  title: string
  content: string
  accent?: 'amber' | 'red' | 'green' | 'blue' | 'zinc'
  defaultOpen?: boolean
  index?: number
})
```

资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx]()

## 嵌入式 Viewer 渲染

### HTML 内联渲染

Blueprint 的 viewer 功能支持将 HTML 页面中的 CSS 和 JavaScript 内联化：

```typescript
async function inlineStyles(html: string, viewerRoot: string): Promise<string> {
  return await replaceAsync(
    html,
    /<link\s+rel="stylesheet"\s+crossorigin\s+href="([^"]+)">|<link\s+rel="stylesheet"\s+href="([^"]+)">/g,
    async (_match, crossoriginHref: string | undefined, href: string | undefined) => {
      const assetPath = assetPathFromHref(crossoriginHref ?? href ?? "");
      const css = await readFile(join(viewerRoot, assetPath), "utf-8");
      return `<style>${css}</style>`;
    },
  );
}
```

资料来源：[src/viewer/render-html.ts]()

这确保了任务上下文的 HTML 导出可以在没有外部依赖的情况下正常工作。

## 总结

Task Context 系统是 Blueprint 项目架构的核心，它通过分层的信息组织（Brief + Group Docs）和稳定的文档模板，为 AI Agent 提供了可预测、可导航的架构记忆。Agent 应遵循"先概览后深入"的原则，优先使用搜索和章节跳转，而非盲目遍历整个代码库。

---

<a id='page-language-support'></a>

## 语言支持与Tree-sitter集成

### 相关页面

相关主题：[Scan管道 - 文件清单与分析](#page-scan-pipeline)

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

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

- [src/languages/registry.ts](https://github.com/engincankaya/blueprint/blob/main/src/languages/registry.ts)
- [src/languages/types.ts](https://github.com/engincankaya/blueprint/blob/main/src/languages/types.ts)
- [src/languages/typescript/normalizer.ts](https://github.com/engincankaya/blueprint/blob/main/src/languages/typescript/normalizer.ts)
- [src/languages/python/normalizer.ts](https://github.com/engincankaya/blueprint/blob/main/src/languages/python/normalizer.ts)
- [src/lib/tree-sitter-loader.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/tree-sitter-loader.ts)
</details>

# 语言支持与Tree-sitter集成

## 概述

Blueprint项目的语言支持系统基于Tree-sitter构建，为多种编程语言提供统一的代码解析、符号提取、导入/导出分析能力。该系统采用插件化架构，通过语言注册表（Language Registry）管理不同语言的分析器，并使用标准化的类型定义确保各语言模块之间的互操作性。

## 核心架构

### 系统组件关系

```mermaid
graph TD
    subgraph "语言支持层"
        Registry[语言注册表<br/>registry.ts]
        Types[类型定义<br/>types.ts]
    end
    
    subgraph "语言分析器"
        TSNormalizer[TypeScript Normalizer<br/>normalizer.ts]
        PyNormalizer[Python Normalizer<br/>normalizer.ts]
    end
    
    subgraph "基础设施"
        Loader[Tree-sitter加载器<br/>tree-sitter-loader.ts]
        Scanner[文件扫描器<br/>scan-file-inventory-builder.ts]
        Analyzer[代码分析引擎<br/>scan-code-analysis-engine.ts]
    end
    
    Registry --> TSNormalizer
    Registry --> PyNormalizer
    Loader --> Registry
    Scanner --> Registry
    Analyzer --> Registry
    Analyzer --> Loader
```

### 语言注册表机制

语言注册表（`src/languages/registry.ts`）是整个语言支持系统的核心枢纽，负责：

- 注册各语言对应的Tree-sitter语法分析器实例
- 管理语言与文件扩展名的映射关系
- 提供语言特定配置的查询接口
- 支持运行时语言模块的动态加载

```mermaid
graph LR
    A[文件扫描] --> B{识别扩展名}
    B --> C[查询注册表]
    C --> D{语言已注册?}
    D -->|是| E[返回分析器]
    D -->|否| F[加载对应语言模块]
    F --> E
```

## 类型系统

类型定义文件（`src/languages/types.ts`）为整个语言分析管道提供统一的数据模型：

### 关键类型

| 类型名称 | 用途 | 包含字段 |
|---------|------|---------|
| `FileInventory` | 文件清单元数据 | `rootPath`, `files[]`, `summary` |
| `AnalysisFacts` | 代码分析结果 | `symbols{}`, `imports[]`, `exports[]` |
| `ImportInfo` | 导入信息 | `rawSpecifier`, `kind`, `importedSymbols[]` |
| `ExportInfo` | 导出信息 | 依赖具体语言语义 |
| `SymbolInfo` | 符号信息 | `name`, `type`, `location` |

### FileInventory结构

```typescript
interface FileInventory {
  rootPath: string;           // 项目根路径
  files: FileEntry[];         // 所有文件条目
  summary: {
    totalFiles: number;       // 总文件数
    parseableFiles: number;   // 可解析文件数
    metadataOnlyFiles: number; // 仅元数据文件数
  };
}
```

## Tree-sitter集成

### 加载器机制

Tree-sitter加载器（`src/lib/tree-sitter-loader.ts`）负责：

- 初始化Tree-sitter语言包
- 管理语法树缓存
- 处理跨语言的解析错误
- 提供异步解析接口

### 解析流程

```mermaid
sequenceDiagram
    participant 调用方
    participant Loader as Tree-sitter加载器
    participant Parser as Tree-sitter解析器
    participant Normalizer as 语言标准化器
    
    调用方->>Loader: 请求解析文件
    Loader->>Parser: 创建解析实例
    Parser->>Parser: 执行语法解析
    Parser-->>Loader: 返回SyntaxNode树
    Loader-->>调用方: 提供解析结果
    调用方->>Normalizer: 提取语义信息
    Normalizer-->>调用方: 返回ImportInfo/ExportInfo
```

## Python语言分析

Python语言标准化器（`src/languages/python/normalizer.ts`）处理Python特有的代码结构：

### 导入分析

Python的`import`语句解析需要处理多种语法变体：

```mermaid
graph TD
    A[import语句] --> B{import类型}
    B -->|import x| C[单模块导入]
    B -->|import x as y| D[别名导入]
    B -->|from x import y| E[从模块导入]
    B -->|from x import *| F[通配符导入]
    
    C --> G[符号: x]
    D --> H[符号: y]
    E --> I[符号: y]
    F --> J[符号: *]
```

### 导出分析

Python没有显式的`export`关键字，系统通过以下规则推断导出：

1. 模块级公共名称（不以`_`开头）
2. `__all__`列表中定义的名称
3. 装饰器标记的公共函数和类

资料来源：[src/languages/python/normalizer.ts:70-90]()

```typescript
// 公共名称判断逻辑
if (name && !name.startsWith("_")) {
  publicNames.push(name);
}
```

### AST节点处理

标准化器遍历语法树时处理以下节点类型：

| 节点类型 | 处理方式 |
|---------|---------|
| `import_statement` | 提取所有导入符号 |
| `import_from_statement` | 解析`from ... import`结构 |
| `dotted_name` | 收集点分名称组件 |
| `aliased_import` | 记录别名映射 |
| `wildcard_import` | 记录通配符导入 |
| `decorated_definition` | 处理带装饰器的定义 |

## TypeScript语言分析

TypeScript标准化器（`src/languages/typescript/normalizer.ts`）处理TypeScript/JavaScript的代码结构：

### 符号提取

- 解析函数定义、类定义、接口定义
- 提取类型参数和访问修饰符
- 处理命名空间和模块声明

### 导入/导出处理

- `import`声明的标准解析
- `export`声明的类型区分
- `export =`和`export default`的兼容性处理
- 命名空间导入的别名处理

## 文件分类系统

Blueprint通过文件扫描器（`src/tools/scan/scan-file-inventory-builder.ts`）对项目文件进行分类：

### 分类规则

| 分类 | 判断条件 |
|-----|---------|
| `test` | 文件名包含`.test.`, `.spec.`, `__tests__`目录, `test/`目录 |
| `lockfile` | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Cargo.lock` |
| `config` | `.gitignore`, `package.json`, `tsconfig.json`, `.config.ts/.js` |
| `documentation` | `docs/`目录, `README.md`, `.md`文件 |
| `script` | `scripts/`目录, `.sh`文件, shell语言 |
| `asset` | `assets/`, `public/`目录, html/css/svg文件 |
| `generated` | `generated/`, `__generated__/`目录 |

资料来源：[src/tools/scan/scan-file-inventory-builder.ts:20-70]()

### 文件角色标注

根据文件在项目中的位置和用途，系统为每个文件分配角色标签：

- `core`: 核心业务逻辑
- `interface`: 接口定义
- `implementation`: 具体实现
- `test`: 测试代码
- `config`: 配置文件
- `utility`: 工具函数
- `unknown`: 未能识别的角色

## 分析结果验证

代码分析引擎（`src/tools/scan/scan-code-analysis-engine.ts`）生成的分析结果包含验证信息：

```typescript
interface Validation {
  isComplete: boolean;           // 分析是否完整
  inventoryFiles: number;       // 清单文件数
  parseableFiles: number;        // 可解析文件数
  parsedFiles: number;           // 实际解析文件数
  metadataOnlyFiles: number;    // 仅元数据文件数
  skippedMetadataOnlyFiles: number; // 跳过的元数据文件
  parseErrors: number;           // 解析错误数
  unaccountedFiles: string[];    // 未纳入分析的文件
}
```

资料来源：[src/tools/scan/scan-code-analysis-engine.ts:30-45]()

## 扩展语言支持

### 添加新语言步骤

1. 在`src/languages/`下创建`<language>/normalizer.ts`
2. 实现`extractImports`和`extractExports`函数
3. 在注册表中注册新的语言模块
4. 添加对应的文件扩展名映射
5. 编写测试用例验证解析正确性

### 语言配置接口

```typescript
interface LanguageConfig {
  id: string;              // 语言标识符
  name: string;           // 显示名称
  extensions: string[];   // 文件扩展名
  treeSitterLanguage: string;  // Tree-sitter语言包名
  normalizer: Normalizer;  // 标准化器实例
}
```

## 技术限制与注意事项

### 当前限制

- Tree-sitter解析依赖于预编译的语言包，加载大型项目时可能有内存压力
- Python的动态特性（如`exec`、`__getattr__`）无法静态分析
- TypeScript的类型系统部分特性（如条件类型）在编译时可能无法完全解析

### 最佳实践

1. 保持Tree-sitter语言包版本与主包一致
2. 对于不支持的文件类型，系统会自动降级为仅元数据模式
3. 定期更新语言解析器以支持新的语法特性

## 相关文件索引

| 文件路径 | 功能描述 |
|---------|---------|
| `src/languages/registry.ts` | 语言注册与管理中心 |
| `src/languages/types.ts` | 统一类型定义 |
| `src/languages/python/normalizer.ts` | Python代码标准化 |
| `src/languages/typescript/normalizer.ts` | TypeScript代码标准化 |
| `src/lib/tree-sitter-loader.ts` | Tree-sitter运行时加载 |
| `src/tools/scan/scan-file-inventory-builder.ts` | 文件扫描与分类 |
| `src/tools/scan/scan-code-analysis-engine.ts` | 代码分析引擎 |

---

<a id='page-data-storage'></a>

## 数据存储与路径管理

### 相关页面

相关主题：[Scan管道 - 文件清单与分析](#page-scan-pipeline), [Compose管道 - 最终输出生成](#page-compose-pipeline)

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

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

- [src/lib/blueprint-paths.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/blueprint-paths.ts)
- [src/lib/artifact-store.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/artifact-store.ts)
- [src/lib/group-docs.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/group-docs.ts)
- [src/lib/brief-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/brief-builder.ts)
- [src/tools/compose/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/index.ts)
- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)
- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)
</details>

# 数据存储与路径管理

## 概述

Blueprint 项目的数据存储与路径管理系统是整个架构的核心基础设施，负责管理项目内存文件的生成、存储、读取和维护。该系统采用本地文件系统作为默认存储后端，将架构记忆以结构化 JSON 和 Markdown 文件的形式持久化到用户项目的 `.blueprint/` 目录中。

Blueprint 的存储架构遵循以下核心原则：

- **本地优先**：所有数据默认存储在用户项目的 `.blueprint/` 目录中
- **确定性维护**：使用 Tree-sitter 分析和文件系统哈希快照确保增量更新的准确性
- **源码头信任**：源码是最终事实依据，Blueprint 文档仅为方向性参考
- **工具驱动**：不直接编辑生成的 JSON 文件，通过 MCP 工具进行确定性维护

资料来源：[README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)

## 核心组件

### BlueprintPaths 路径管理模块

`BlueprintPaths` 模块负责定义和管理 Blueprint 相关的所有文件系统路径。该模块封装了路径解析逻辑，为其他模块提供统一的路径访问接口。

| 属性 | 说明 | 默认值 |
|------|------|--------|
| `projectRoot` | 用户项目根目录 | 当前工作目录 |
| `blueprintDir` | Blueprint 内存目录 | `.blueprint/` |
| `briefPath` | 项目概述文档路径 | `.blueprint/brief.md` |
| `groupsDir` | 分组文档目录 | `.blueprint/groups/` |
| `outputJsonPath` | 结构化输出 JSON 路径 | `.blueprint/blueprint-output.json` |
| `indexHtmlPath` | 静态查看器 HTML 路径 | `.blueprint/index.html` |
| `refreshScanJsonPath` | 刷新扫描哈希快照路径 | `.blueprint/refresh-scan.json` |

路径模块还负责生成 Agent 说明文件路径，该文件包含 Blueprint MCP 的使用指引。

资料来源：[src/lib/blueprint-paths.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/blueprint-paths.ts)

### ArtifactStore 工件存储

`ArtifactStore` 是 Blueprint 的核心数据存储抽象层，提供类型安全的工件存取接口。每个工件（Artifact）都具有唯一的标识符，支持版本追踪和类型验证。

```typescript
interface Artifact {
  id: string;
  type: string;
  data: unknown;
  metadata: {
    createdAt: number;
    updatedAt: number;
    version: number;
  };
}
```

#### 存储操作接口

| 方法 | 功能 | 返回类型 |
|------|------|----------|
| `store(artifact)` | 存储新工件 | `string` (工件ID) |
| `get(id)` | 根据ID获取工件 | `Artifact \| undefined` |
| `getTyped(id, type, expectedType)` | 类型安全获取 | `T \| undefined` |
| `update(id, data)` | 更新现有工件 | `boolean` |
| `delete(id)` | 删除工件 | `boolean` |
| `list()` | 列出所有工件 | `Artifact[]` |
| `clear()` | 清空存储 | `void` |

`getTyped` 方法是类型安全访问的核心，它在返回数据前验证工件类型是否符合预期。如果类型不匹配，返回 `undefined` 并记录警告。

资料来源：[src/lib/artifact-store.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/artifact-store.ts)

### FileInventory 文件清单

`FileInventory` 是扫描阶段生成的文件清单数据结构，包含项目的完整文件列表和元数据。

```typescript
interface FileInventory {
  rootPath: string;
  files: FileEntry[];
  summary: {
    totalFiles: number;
    parseableFiles: number;
    metadataOnlyFiles: number;
  };
}

interface FileEntry {
  absolutePath: string;
  relativePath: string;
  language: string;
  analysisLevel: 'parseable' | 'metadata-only';
  size: number;
  category?: FileCategory;
}
```

文件分类通过 `FileCategory` 枚举区分：

| 分类 | 说明 | 判定规则 |
|------|------|----------|
| `source` | 源代码文件 | `.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.go`, `.rs`, `.java` |
| `test` | 测试文件 | `.test.ts`, `.spec.ts`, `test/`, `tests/` 目录 |
| `config` | 配置文件 | `package.json`, `tsconfig.json`, `.config.js` |
| `documentation` | 文档文件 | `readme.md`, `.md`, `docs/` 目录 |
| `script` | 脚本文件 | `.sh`, `scripts/` 目录 |
| `asset` | 静态资源 | `.svg`, `.css`, `assets/`, `public/` 目录 |
| `lockfile` | 锁文件 | `package-lock.json`, `yarn.lock`, `Cargo.lock` |

资料来源：[src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)

### GroupDocs 分组文档管理

`GroupDocs` 模块负责管理 `.blueprint/groups/*.md` 中的分组文档。这些 Markdown 文件记录了每个架构分组的详细信息，包括核心流程、契约、不变式和测试指南等。

分组文档模板结构：

| 章节 | 说明 | 必填 |
|------|------|------|
| `Snapshot` | 快速概览和摘要 | 建议 |
| `Responsibilities` | 所有权和范围定义 | 建议 |
| `Core Flow` | 运行时行为和数据流 | 建议 |
| `Contracts & Invariants` | 必须保持的行为契约 | 建议 |
| `Key Files` | 指向主要源文件 | 建议 |
| `Change Guide` | 变更协同文件列表 | 可选 |
| `Pitfalls` | 已知风险和常见错误 | 可选 |
| `Tests` | 相关验证测试 | 可选 |
| `Debugging` | 故障排查提示 | 可选 |
| `Extension / Open Questions` | 不确定性和已知缺口 | 可选 |

资料来源：[src/lib/group-docs.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/group-docs.ts)

### BriefBuilder 概述文档构建

`BriefBuilder` 负责生成 `.blueprint/brief.md` 项目概述文档。该文档提供项目的全局架构视图，包括：

- 项目概述和架构分组成员
- 路由提示和入口点
- 关键文件列表
- 分组文档路径引用

Brief 文档是 Agent 开始探索代码库时的首要参考资源，应当保持简洁且与当前 Blueprint 输出同步。

资料来源：[src/lib/brief-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/brief-builder.ts)

## 数据流架构

### 整体工作流

```mermaid
graph TD
    A[用户项目] --> B[blueprint.scan]
    B --> C[FileInventory]
    C --> D[blueprint.group]
    D --> E[GroupingResult]
    E --> F[blueprint.compose]
    F --> G[BlueprintOutput]
    G --> H[.blueprint/brief.md]
    G --> I[.blueprint/groups/*.md]
    G --> J[blueprint-output.json]
    J --> K[blueprint open]
    K --> L[.blueprint/index.html]
    
    M[源码变更] --> N[blueprint.refresh]
    N --> O[refresh-scan.json]
    O --> P{哈希对比}
    P -->|检测到变更| Q[更新受影响分组]
    P -->|无变更| R[跳过]
```

### 扫描与代码分析流程

```mermaid
graph LR
    A[文件系统] -->|readFile| B[scan-code-analysis-engine]
    B --> C{语言类型}
    C -->|TypeScript/JS| D[Tree-sitter Parser]
    C -->|Python| E[Tree-sitter Parser]
    C -->|Go| F[Tree-sitter Parser]
    C -->|Rust| G[Tree-sitter Parser]
    C -->|Java| H[Tree-sitter Parser]
    C -->|其他| I[元数据仅存]
    
    D --> J[AnalysisFacts]
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J
    
    J --> K[符号表]
    J --> L[导入关系]
    J --> M[依赖图]
    J --> N[解析错误]
```

### Compose 阶段数据转换

```mermaid
graph TD
    A[GroupingResult] --> B[ComposeTool]
    C[FileInventory] --> B
    D[AnalysisFacts] --> B
    
    B --> E[ComposeOutputBuilder]
    E --> F[ComposeArtifactWriter]
    F --> G[blueprint.v1 结构]
    
    G --> H[brief.md]
    G --> I[groups/*.md]
    G --> J[blueprint-output.json]
    G --> K[AGENTS.md 补丁]
```

`ComposeTool` 协调多个构建器完成最终输出：

1. **ComposeOutputBuilder**：构建前端可用的 Blueprint JSON 结构
2. **ComposeArtifactWriter**：将构建结果写入文件系统
3. **ComposeEntrypointDetector**：检测项目入口点并关联

资料来源：[src/tools/compose/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/index.ts)

## AnalysisFacts 数据结构

`AnalysisFacts` 是代码分析阶段生成的核心数据结构，汇总了所有代码解析结果。

```typescript
interface AnalysisFacts {
  inventoryArtifactId: string;
  rootPath: string;
  files: Record<string, FileAnalysis>;
  symbols: Record<string, SymbolInfo>;
  imports: ImportEntry[];
  exports: ExportEntry[];
  dependencies: DependencyEdge[];
  unresolvedImports: UnresolvedImport[];
  parseErrors: ParseError[];
  summary: AnalysisSummary;
  validation: ValidationState;
}
```

#### ValidationState 验证状态

| 字段 | 说明 | 用途 |
|------|------|------|
| `isComplete` | 分析是否完成 | 状态标志 |
| `inventoryFiles` | 清单文件总数 | 完整性检查 |
| `parseableFiles` | 可解析文件数 | 解析覆盖率 |
| `parsedFiles` | 实际解析文件数 | 进度追踪 |
| `metadataOnlyFiles` | 元数据文件数 | 未分析文件 |
| `skippedMetadataOnlyFiles` | 跳过的元数据文件 | 分析决策记录 |
| `parseErrors` | 解析错误数 | 质量指标 |
| `unaccountedFiles` | 未归属文件列表 | 完整性审计 |

资料来源：[src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)

## 存储路径配置

### 目录结构

```
project-root/
├── .blueprint/
│   ├── brief.md                    # 项目概述文档
│   ├── blueprint-output.json       # 结构化输出数据
│   ├── refresh-scan.json           # 文件系统哈希快照
│   ├── index.html                  # 静态查看器
│   └── groups/
│       ├── frontend.md             # 前端分组文档
│       ├── backend.md              # 后端分组文档
│       └── shared.md               # 共享模块文档
└── src/                            # 用户源代码
```

### 路径解析优先级

```mermaid
graph TD
    A[路径请求] --> B{存在自定义配置?}
    B -->|是| C[使用配置的路径]
    B -->|否| D{环境变量 BLUEPRINT_DIR?}
    D -->|是| E[使用环境变量值]
    D -->|否| F{命令行参数 --dir?}
    F -->|是| G[使用命令行值]
    F -->|否| H[使用默认 .blueprint/]
    
    C --> Z[解析完成]
    E --> Z
    G --> Z
    H --> Z
```

## MCP 工具集成

Blueprint MCP 提供四个主要工具用于存储和路径管理：

| 工具 | 用途 | 影响文件 |
|------|------|----------|
| `blueprint.scan` | 构建文件清单和代码分析 | 生成扫描缓存 |
| `blueprint.group` | 准备或应用语义分组 | 更新分组状态 |
| `blueprint.compose` | 写入最终 Blueprint 输出 | `brief.md`, `groups/*.md`, `blueprint-output.json` |
| `blueprint.refresh` | 从当前文件系统快照刷新 | 更新哈希快照 |
| `blueprint.group.update` | 分配未分配文件 | 更新分组配置 |

### 工具调用流程

```mermaid
sequenceDiagram
    participant U as 用户/Agent
    participant M as MCP Server
    participant A as ArtifactStore
    participant F as 文件系统

    U->>M: blueprint.scan
    M->>F: 扫描项目文件
    F-->>M: FileInventory
    M->>A: store(FileInventory)
    A-->>M: artifactId
    
    U->>M: blueprint.group with mode: prepare
    M->>A: get(inventoryArtifactId)
    A-->>M: FileInventory
    M->>F: 分析分组建议
    F-->>M: GroupingResult
    M->>A: store(GroupingResult)
    
    U->>M: blueprint.compose
    M->>A: get(groupingArtifactId)
    A-->>M: GroupingResult
    M->>F: 写入 .blueprint/ 目录
    F-->>M: 写入完成
```

## 静态查看器渲染

Blueprint 的静态查看器使用嵌入式数据渲染模式：

```mermaid
graph TD
    A[blueprint-output.json] --> B[Renderer]
    C[brief.md] --> B
    D[groups/*.md] --> B
    B --> E[index.html]
    E --> F[浏览器]
    F --> G[显示架构视图]
```

查看器特点：

- **独立 HTML**：无需 HTTP 服务器即可查看
- **嵌入式数据**：JSON 数据直接嵌入 HTML 文件
- **自包含**：所有样式和脚本内联
- **无外部依赖**：不依赖网络资源

资料来源：[README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)

## 维护与更新策略

### 确定性刷新机制

Blueprint 使用文件系统哈希快照进行确定性刷新：

1. 扫描阶段计算所有源文件的哈希值
2. 将哈希快照存储在 `refresh-scan.json`
3. 刷新时重新计算哈希并对比
4. 仅更新发生变化的文件关联

```mermaid
graph TD
    A[refresh-scan.json] --> B[当前哈希计算]
    B --> C{与快照对比}
    C -->|有变更| D[识别受影响分组]
    C -->|无变更| E[跳过更新]
    D --> F[blueprint.group.update]
    F --> G[更新分组关联]
    G --> H[写入新快照]
```

### 文件分类变更处理

当文件移动、删除或新增时：

| 变更类型 | 处理方式 | 触发操作 |
|----------|----------|----------|
| 新增文件 | 检查分组归属 | `blueprint.group.update` |
| 删除文件 | 从分组移除 | 自动清理 |
| 移动文件 | 更新相对路径 | 重新分析关联 |
| 重命名文件 | 视为删除+新增 | 完整重新关联 |

### 分组文档同步

分组文档应随源码变更同步更新：

- 仅在架构契约、契约、不变式、陷阱或测试指导变更时更新
- 保持 `.blueprint/brief.md` 与当前 Blueprint 输出同步
- 不要将完整源码详情复制到 Markdown 文档
- 记录稳定的架构事实、契约和测试指导

## 最佳实践

### 路径使用规范

1. **始终使用 BlueprintPaths 模块**：不要硬编码路径字符串
2. **类型安全访问**：优先使用 `getTyped()` 方法
3. **验证工件存在**：在访问前检查 `undefined` 情况

### 数据一致性维护

```mermaid
graph LR
    A[源码变更] -->|blueprint.refresh| B{检测变更}
    B -->|分组结构变更| C[更新 groups/*.md]
    B -->|文档结构变更| D[更新 brief.md]
    B -->|两者都变| E[更新两者]
    B -->|无变更| F[无需操作]
```

### 避免的操作

- 手动编辑 `blueprint-output.json`
- 跳过 `blueprint.refresh` 直接修改源码
- 将大量源码细节复制到分组文档
- 在分组文档与源码冲突时信任文档

## 总结

Blueprint 的数据存储与路径管理系统通过模块化设计和确定性工具链，实现了架构记忆的可靠管理和自动同步。核心组件包括：

- **BlueprintPaths**：提供统一的路径解析接口
- **ArtifactStore**：实现类型安全的工件存储抽象
- **FileInventory**：维护项目的完整文件清单
- **GroupDocs**：管理分组 Markdown 文档
- **BriefBuilder**：构建项目概述文档

整个系统以源码为最终事实依据，通过 MCP 工具驱动进行确定性维护，确保架构文档始终反映当前代码库的真实状态。

---

---

## Doramagic 踩坑日志

项目：engincankaya/blueprint

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

## 1. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1230090802 | https://github.com/engincankaya/blueprint | README/documentation is current enough for a first validation pass.

## 2. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | last_activity_observed missing

## 3. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium

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

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium

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

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | issue_or_pr_quality=unknown

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

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | release_recency=unknown

<!-- canonical_name: engincankaya/blueprint; human_manual_source: deepwiki_human_wiki -->