概述

Monomind 是一个模块化的 AI Agent 编排框架（Modular AI Agent Orchestration Framework），旨在为开发团队提供生产级别的 AI 协作基础设施。该项目通过整合多种 AI 能力、记忆系统和编排机制，使多个 AI Agent 能够协同工作完成复杂任务。

资料来源：README.md

核心定位

Monomind 的核心价值主张是"Stop prompting. Start orchestrating."（停止提示工程，开始编排）。它不是一个简单的聊天界面，而是一个完整的 Agent 协作平台，具有以下特点：

• 多 Agent 编排：支持多种专业化的 Agent 类型协同工作
• 持久化记忆：跨会话的向量记忆和知识图谱
• 神经网络学习：SONA（Self-Optimizing Neural Adaptation）自优化神经适应机制
• 插件生态：通过插件系统扩展功能
• WASM 运行时：支持 WebAssembly 沙箱化的 Agent 执行

资料来源：README.md

系统架构

Monomind 采用模块化架构设计，主要包含以下核心组件：

graph TD
    subgraph CLI层
        A[CLI 命令行工具]
    end
    
    subgraph 核心功能层
        B[Swarm 编排系统]
        C[Memory 记忆系统]
        D[Monograph 知识图谱]
        E[SONA 神经学习]
    end
    
    subgraph 通信层
        F[MCP 服务器]
        G[Agent Bridge]
    end
    
    subgraph 扩展层
        H[插件系统]
        I[WASM 运行时]
    end
    
    A --> B
    A --> C
    A --> D
    A --> F
    B --> C
    B --> D
    C --> E
    F --> G
    H --> B
    I --> G

资料来源：packages/@monomind/cli/README.md

主要功能模块

1. Agent 管理系统

Monomind 支持多种专业化的 Agent 类型，每个 Agent 具有特定的能力范围：

资料来源：packages/@monomind/cli/src/commands/agent.ts

Agent 命令提供以下子命令：

• metrics - 显示 Agent 指标
• pool - 管理 Agent 池
• health - 显示 Agent 健康状态
• logs - 查看 Agent 日志
• wasm-status - 检查 WASM 运行时可用性
• wasm-create - 创建 WASM 沙箱化 Agent
• wasm-prompt - 向 WASM Agent 发送提示

2. Session 会话管理

Monomind 提供完整的会话生命周期管理功能：

会话检查器（Session Inspector）提供完整的对话回放和工具使用分析功能。

资料来源：packages/@monomind/cli/src/commands/session.ts

3. Memory 记忆系统

Monomind 的记忆系统采用混合架构，支持多种存储后端：

#### 向量记忆（AgentDB + HNSW）

• 性能指标：比暴力搜索快 150x-12,500x
• 混合后端：SQLite 用于结构化数据，AgentDB 用于语义搜索
• 跨会话持久化：上下文在重启后保留

#### A-MEM 自动链接

当 HybridBackend 配置了 embeddingGenerator 时，每个存储的条目会自动发现其 top-3 语义邻居并创建双向的 references 边，实现 Zettelkasten 笔记链接结构。

#### 记忆作用域

资料来源：packages/@monomind/memory/README.md

4. Knowledge Graph 知识图谱（Monograph）

Monograph 构建代码库的完整依赖图，在每个任务之前自动查询：

# 查找与任务相关的文件
monograph_suggest "add webhook retry logic"
# → 返回带相关性评分的文件排名列表

# 查询依赖关系
monograph_query "UserService dependencies"
# → 返回文件路径和行号

# 查找高连通性的核心文件
monograph_god_nodes
# → 返回高中心性的内部文件（过滤外部/测试文件）

所有 monograph 工具都由 hooks 和斜杠命令自动调用，无需手动调用。

资料来源：README.md

#### 节点类型

#### 边类型

资料来源：plugin/commands/monograph/README.md

5. SONA 神经学习系统

SONA（Self-Optimizing Neural Adaptation）是 Monomind 的自优化神经适应机制：

• 模式识别：随着时间推移改进 Agent 路由
• 轨迹追踪：识别什么有效、什么无效
• 自动模型适配：开销 <0.05ms

资料来源：README.md

6. MCP 服务器

Monomind 提供 Model Context Protocol（MCP）服务器实现，支持与 Claude Code 集成：

#### 核心接口

Tool 接口：

interface MCPTool<TInput = unknown, TOutput = unknown> {
  name: string;
  description: string;
  inputSchema: JSONSchema;
  handler: (input: TInput, context?: ToolContext) => Promise<TOutput>;
  category?: string;
  tags?: string[];
  cacheable?: boolean;
  cacheTTL?: number;
  timeout?: number;
}

Transport 接口：

interface ITransport {
  readonly type: TransportType;
  start(): Promise<void>;
  stop(): Promise<void>;
  onRequest(handler: RequestHandler): void;
  onNotification(handler: NotificationHandler): void;
  sendNotification?(notification: MCPNotification): Promise<void>;
  getHealthStatus(): Promise<TransportHealthStatus>;
}

#### 内置工具

#### 资源系统

MCP 服务器支持注册资源处理器，支持 URI 方案和 MIME 类型：

const { resource, handler } = createTextResource(
  'file://readme.txt',
  'README',
  'Welcome to the application!',
  { mimeType: 'text/plain' }
);
resourceRegistry.registerResource(resource, handler);

资料来源：packages/@monomind/mcp/README.md

7. 插件系统

Monomind 采用去中心化的插件注册表设计，支持 IPNS 发现和 Ed25519 签名验证。

#### 插件命令

#### IPFS 特性

• 通过 IPNS 实现去中心化注册表以便发现
• 内容寻址存储用于完整性验证
• Ed25519 签名用于插件验证
• 信任级别：未验证、社区、已验证、官方
• 安全审计跟踪和漏洞报告

#### 官方插件

资料来源：packages/@monomind/cli/src/commands/plugins.ts

8. Swarm 编排系统

Swarm 是 Monomind 的 Agent 编排引擎，支持多 Agent 协作和工作流自动化。

#### Worker 类型与触发器

#### Worker 子命令

资料来源：packages/@monomind/swarm/src/workers/worker-dispatch.js

CLAUDE.md 配置模板

Monomind 提供多种 CLAUDE.md 配置模板，用于初始化项目环境：

模板优先级：options.runtime.claudeMdTemplate > 显式参数 > 'standard'

资料来源：packages/@monomind/cli/src/init/claudemd-generator.ts

Hooks 系统

Monomind 提供智能钩子系统，在任务执行过程中自动触发特定行为：

资料来源：packages/@monomind/cli/src/commands/hooks.ts

适用场景

Monomind 设计用于以下场景：

• 大型代码库：需要多 Agent 协作处理复杂任务
• 企业开发：团队需要共享知识和最佳实践
• 模块化项目：多模块或多仓库管理
• 游戏工作室：使用 Unity/Unreal/Godot 的专业 Agent
• 营销团队：领域特定 Agent 运行内容运营
• 安全团队：自动化审计和合规工作流

资料来源：packages/@monomind/cli/README.md

快速开始

# 克隆仓库
git clone https://github.com/nokhodian/monomind.git
cd monomind

# 安装依赖
pnpm install

# 运行健康检查
monomind doctor --fix

技术栈

Monomind 基于以下技术构建：

• 运行时：Node.js / TypeScript
• 向量存储：AgentDB + HNSW
• 知识图谱：Monograph
• 神经网络：SONA
• 插件系统：IPFS / IPNS
• 沙箱：WebAssembly (WASM)

资料来源：README.md

系统要求

在开始安装之前，请确保你的开发环境满足以下要求：

资料来源：README.md:1-20

安装步骤

通过 npm 安装（推荐）

Monomind 提供全局 CLI 工具，安装过程简单快捷：

npm install -g @monomind/cli

或者使用 pnpm：

pnpm add -g @monomind/cli

验证安装

安装完成后，运行以下命令验证安装是否成功：

monomind doctor

该命令会检查环境配置并在必要时自动修复问题：

monomind doctor --fix

资料来源：README.md:85-90

核心命令一览

Monomind CLI 提供丰富的命令集，涵盖任务管理、会话控制、配置管理等多个方面。

基础命令

资料来源：packages/implementation/adrs/README.md:1-20

高级命令（V1 版本）

资料来源：packages/implementation/adrs/README.md:25-40

首次配置

初始化项目

在项目根目录运行初始化命令：

npx @monomind/cli@latest --help

这将启动交互式配置向导，帮助你设置：

• CLAUDE.md 模板选择：standard（标准）、minimal（最小）、full（完整）、security（安全）
• 项目架构：根据项目类型推荐最佳实践
• 智能体类型：配置团队协作的智能体角色
• 钩子系统：设置自动化工作流触发器

资料来源：packages/@monomind/cli/src/init/claudemd-generator.ts:50-80

CLAUDE.md 模板说明

Monomind 支持四种 CLAUDE.md 模板，适用于不同场景：

资料来源：packages/@monomind/cli/src/init/claudemd-generator.ts:25-50

核心功能模块

记忆与智能系统

Monomind 的记忆系统由三个核心组件构成：

graph TD
    A[用户输入] --> B[Monograph 知识图谱]
    A --> C[AgentDB 向量记忆]
    A --> D[SONA 神经学习]
    
    B --> E[依赖图分析]
    B --> F[文件相关性排名]
    
    C --> G[HNSW 索引搜索]
    C --> H[混合后端 SQLite]
    
    D --> I[模式识别]
    D --> J[轨迹追踪]
    D --> K[自动模型适应]

#### 知识图谱（Monograph）

自动构建代码库的完整依赖图，在每个任务前自动查询：

# 查询相关文件
monograph_suggest "add webhook retry logic"

# 查询依赖关系
monograph_query "UserService dependencies"

# 查找高连接度文件
monograph_god_nodes

资料来源：README.md:50-65

#### 向量记忆（AgentDB + HNSW）

通过 HNSW 索引实现高效的语义搜索：

资料来源：README.md:66-75

#### 神经适应（SONA）

自我优化神经适应系统从每个任务中学习：

• 模式识别提升智能体路由效率
• 轨迹追踪识别有效和无效的策略
• 自动模型适应，延迟低于 0.05ms

资料来源：README.md:76-82

插件系统

Monomind 采用插件化架构，允许扩展核心功能：

graph LR
    A[Monomind Core] --> B[Plugin A]
    A --> C[Plugin B]
    A --> D[Plugin C]
    
    B --> E[注册智能体类型]
    C --> F[注册 MCP 工具]
    D --> G[注册 CLI 命令]

#### 插件接口

所有插件必须实现以下接口：

interface MonomindPlugin {
  readonly name: string;
  readonly version: string;
  initialize(context: PluginContext): Promise<void>;
  shutdown(): Promise<void>;
  
  // 可选扩展点
  dependencies?: string[];
  registerAgentTypes?(): AgentTypeDefinition[];
  registerMCPTools?(): MCPToolDefinition[];
  registerCLICommands?(): CLICommandDefinition[];
}

资料来源：packages/implementation/plugins/README.md:40-65

MCP 服务器管理

Monomind 内置 MCP（Model Context Protocol）服务器支持：

资料来源：packages/@monomind/cli/src/commands/mcp.ts:1-30

会话管理

Monomind 提供完整的会话管理功能，支持工作状态的保存与恢复：

资料来源：packages/@monomind/cli/src/commands/session.ts:1-25

工作流自动化

创建工作流

monomind workflow create <workflow-name> --steps <step1,step2,step3>

执行工作流

monomind workflow execute <workflow-name>

监控状态

monomind workflow status <workflow-id>

故障排除

常见问题

健康检查

# 运行完整诊断
monomind doctor

# 自动修复问题
monomind doctor --fix

资料来源：README.md:85-95

下一步

• 查看 CLAUDE.md 模板配置 自定义你的项目
• 探索 插件系统 扩展功能
• 了解 记忆系统 的高级用法
• 配置 钩子系统 实现自动化工作流

概述

Monomind 是一个基于 AI Agent 的智能开发编排系统，通过模块化架构实现代码库理解、任务编排、记忆管理和知识图谱构建。该系统采用多包组织结构，核心模块包括 @monomind/shared（共享核心）、@monomind/cli（命令行接口）、@monomind/swarm（蜂群编排）和 @monomind/monograph（知识图谱）。

核心架构分层

┌─────────────────────────────────────────────────────────────┐
│                         Monomind                            │
├──────────────┬──────────────┬──────────────┬───────────────┤
│   CLI 层     │   Agent 层   │   Swarm 层   │  Memory 层    │
│  (命令执行)  │  (任务执行)  │  (多Agent    │  (向量存储    │
│              │              │   编排)      │   + 知识图谱) │
├──────────────┴──────────────┴──────────────┴───────────────┤
│                      Shared Core                            │
│          (共享原语、类型定义、工具函数)                       │
└─────────────────────────────────────────────────────────────┘

核心模块

Shared Core (`@monomind/shared`)

Shared Core 是整个系统的基础层，提供跨包共享的类型定义、常量、工具函数和安全规则。

#### 核心导出结构

资料来源：packages/@monomind/shared/src/index.ts:1-50

#### 安全与文件组织规则

系统通过正则表达式模式定义文件组织规范：

// 源代码文件定位规则
{ pattern: /\.ts$/, directories: ['src/', 'lib/'], type: 'TypeScript source', blockRoot: true },
{ pattern: /\.tsx$/, directories: ['src/'], type: 'TSX source', blockRoot: true },

// 配置文件规则
{ pattern: /\.(json|jsonc)$/, directories: ['config/', 'src/config/'], type: 'JSON config', blockRoot: false },
{ pattern: /tsconfig.*\.json$/, directories: ['./'], type: 'TypeScript config', blockRoot: false },

// 环境文件
{ pattern: /\.(env|env\.[a-z]+)$/, directories: ['./'], type: 'environment file', blockRoot: false },

// 文档和资源文件
{ pattern: /\.md$/, directories: ['docs/', './'], type: 'Markdown documentation', blockRoot: false },
{ pattern: /\.(css|scss|sass|less)$/, directories: ['styles/', 'src/styles/', 'assets/css/'], type: 'stylesheet', blockRoot: true },

资料来源：packages/@monomind/shared/src/hooks/safety/file-organization.ts:1-80

CLI 层 (`@monomind/cli`)

CLI 层负责用户交互和命令执行，采用子命令架构。

#### 命令体系

#### Agent 类型与能力

系统支持多种专用 Agent 类型：

const capabilities: Record<string, string[]> = {
  coder: ['code-generation', 'refactoring', 'debugging', 'testing'],
  researcher: ['web-search', 'data-analysis', 'summarization', 'citation'],
  tester: ['unit-testing', 'integration-testing', 'coverage-analysis', 'automation'],
  reviewer: ['code-review', 'security-audit', 'quality-check', 'documentation'],
  architect: ['system-design', 'pattern-analysis', 'scalability', 'documentation'],
  coordinator: ['task-orchestration', 'agent-management', 'workflow-control'],
  'security-architect': ['threat-modeling', 'security-patterns', 'compliance', 'audit'],
  'memory-specialist': ['vector-search', 'agentdb', 'caching', 'optimization'],
  'performance-engineer': ['profiling', 'benchmarking', 'optimization', 'metrics'],
};

资料来源：packages/@monomind/cli/src/commands/agent.ts:40-55

#### MCP 服务架构

MCP（Model Context Protocol）服务器提供工具调用能力：

graph TD
    A[CLI Command] --> B[MCP Server]
    B --> C[Tool Registry]
    B --> D[Health Check]
    B --> E[Log Manager]
    C --> F[mcp__monomind__monograph_*]
    C --> G[mcp__monomind__memory_*]
    C --> H[mcp__monomind__agent_*]

资料来源：packages/@monomind/cli/src/commands/mcp.ts:1-40

Swarm 编排层 (`@monomind/swarm`)

Swarm 层实现多 Agent 协同编排，采用 Queen-Coordinator 模式。

#### 任务分解机制

Queen Coordinator 将复杂任务分解为子任务链：

graph TD
    A[TaskDefinition] --> B{Task Type}
    B -->|Research| C[Gather → Analyze]
    B -->|Coordination| D[Plan → Execute]
    B -->|Generic| E[Execute]
    
    C --> F[SubTask: gather]
    C --> G[SubTask: analyze]
    G --> |depends on| F
    
    D --> H[SubTask: plan]
    D --> I[SubTask: execute]
    I --> |depends on| H

#### 子任务结构

interface SubTask {
  id: string;                    // 唯一标识符
  name: string;                  // 任务名称
  description: string;           // 任务描述
  type: string;                  // 任务类型
  priority: number;              // 优先级
  dependencies: string[];        // 依赖的子任务ID
  estimatedDurationMs: number;   // 预估执行时间
  requiredCapabilities: string[];// 所需能力
  recommendedDomain: string;    // 推荐执行域
}

#### 任务类型与分解策略

资料来源：packages/@monomind/swarm/src/queen-coordinator.ts:1-120

Memory 层

Memory 层提供向量记忆和知识存储能力。

#### 存储层级

#### A-MEM 自动链接

当配置 embeddingGenerator 时，系统自动实现 Zettelkasten 笔记链接结构：

const backend = new HybridBackend({
  embeddingGenerator: async (text) => myEmbeddingModel.embed(text),
  // 启用后自动进行 A-MEM 自动链接
});

资料来源：packages/@monomind/memory/README.md:1-30

Monograph 知识图谱

Monograph 构建代码库的完整依赖图，提供语义查询能力。

#### 图谱节点类型

#### 边类型

#### Monograph 配置

interface ExtendedMonographConfig {
  extends?: string[];                    // 扩展配置
  sealed?: boolean;                       // 密封配置
  includeEntryExports?: boolean;          // 包含入口导出
  publicPackages?: string[];              // 公共包列表
  dynamicallyLoaded?: string[];          // 动态加载模块
  codeowners?: string;                   // CODEOWNERS 路径
  ignoreDependencies?: string[];          // 忽略的依赖
  usedClassMembers?: Array<...>;          // 使用的类成员
}

默认配置包括：

• 健康检查阈值：圈复杂度 ≤10，认知复杂度 ≤15
• 支持扩展名：.ts, .tsx, .mts, .cts
• 标准化选项：移除注释、规范化空白

资料来源：packages/@monomind/monograph/src/config/types.ts:1-80

编排器架构

编排流程

sequenceDiagram
    participant User as 用户
    participant CLI as CLI层
    participant Swarm as Swarm编排器
    participant Agent as Agent池
    participant Memory as Memory层
    participant Graph as Monograph图谱
    
    User->>CLI: 发送命令
    CLI->>Swarm: 创建任务
    Swarm->>Graph: 查询相关文件
    Graph-->>Swarm: 返回相关文件列表
    Swarm->>Agent: 分派子任务
    Agent->>Memory: 存储/检索上下文
    Agent->>Agent: 执行任务
    Agent-->>Swarm: 返回结果
    Swarm-->>CLI: 任务完成
    CLI-->>User: 输出结果

编排配置

插件系统

官方插件

插件特性

• IPFS 去中心化注册：通过 IPNS 实现可发现性
• 内容寻址存储：完整性验证
• Ed25519 签名：插件验证
• 信任等级：未验证、社区验证、官方验证

V1 命令状态

资料来源：packages/implementation/adrs/README.md:1-50

技术栈总结

概述

Monomind 是一个采用 pnpm monorepo 架构的 AI 协调系统，由多个功能专一的 npm 包组成。核心包结构涵盖了命令行接口、向量记忆、知识图谱、安全防护、共享工具和多智能体协调等关键子系统。 资料来源：packages/package.json

概述

代理目录（Agent Directory）是 Monomind 框架中用于组织、管理和调度各类 AI 代理的核心系统。它定义了一套标准化的代理类型体系，提供了统一的代理能力描述和路由机制，使开发者能够根据任务需求选择合适的代理，并支持通过 WASM 技术实现沙箱化的安全执行环境。

Monomind 的代理目录不仅是一个静态的类型列表，更是一个动态的代理生态系统，支持自定义代理配置、代理池管理、健康监控和指标统计等功能。

代理类型体系

Monomind 定义了多种专业化的代理类型，每种类型针对特定的应用场景进行了优化和配置。以下是系统中支持的代理类型及其核心能力。

代理类型列表

资料来源：packages/@monomind/cli/src/commands/agent.ts:40-60

代理能力矩阵

每个代理类型都拥有一组特定的能力标签，用于任务路由和代理选择。以下是能力与代理类型的映射关系。

graph TD
    A[任务输入] --> B{任务类型分析}
    B -->|代码生成| C[coder]
    B -->|安全审计| D[reviewer]
    B -->|系统设计| E[architect]
    B -->|性能优化| F[performance-engineer]
    B -->|数据研究| G[researcher]
    B -->|测试覆盖| H[tester]
    B -->|任务协调| I[coordinator]
    
    C --> J[能力匹配]
    D --> J
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J
    
    J --> K[代理选择完成]

代理管理命令

Monomind CLI 提供了完整的代理管理命令集，通过 monomind agent 子命令访问。

核心命令

资料来源：packages/@monomind/cli/src/commands/agent.ts:10-20

WASM 沙箱代理

Monomind 支持通过 WASM 技术运行沙箱化的代理实例，提供额外的安全隔离层。

graph LR
    A[主进程] -->|安全通信| B[WASM Runtime]
    B --> C[沙箱代理 1]
    B --> D[沙箱代理 2]
    B --> E[沙箱代理 N]
    
    C -->|隔离执行| F[独立内存空间]
    D -->|隔离执行| G[独立内存空间]
    E -->|隔离执行| H[独立内存空间]

代理路由机制

代理路由是智能任务分配的核心组件，Monomind 通过多层决策流程将任务导向最合适的代理。

路由钩子命令

资料来源：packages/@monomind/cli/src/commands/hooks.ts:15-25

路由触发器配置

Monomind Swarm 模块定义了基于关键词匹配的路由触发器，用于自动识别任务意图。

资料来源：packages/@monomind/swarm/src/workers/worker-dispatch.ts:1-50

代理配置模板

Monomind 通过 CLAUDE.md 配置文件定义代理行为，支持多种预定义模板以适应不同场景。

模板类型

资料来源：packages/@monomind/cli/src/init/claudemd-generator.ts:30-60

模板生成流程

graph TD
    A[用户配置] --> B{确定模板类型}
    B -->|runtime.claudeMdTemplate| C[使用运行时配置]
    B -->|显式参数| D[使用传入模板]
    B -->|默认| E[使用 standard 模板]
    
    C --> F[选择章节组合]
    D --> F
    E --> F
    
    F --> G[渲染标题头]
    G --> H[依次渲染章节]
    H --> I[拼接输出内容]
    I --> J[生成 CLAUDE.md]

代理池管理

代理池（Agent Pool）允许同时运行多个代理实例，实现负载均衡和高可用。

池管理操作

代理选择策略

graph TD
    A[新任务] --> B[检查代理可用性]
    B --> C{代理池状态}
    C -->|有空闲代理| D[分配任务]
    C -->|无空闲代理| E[排队等待]
    C -->|池已满| F[创建新实例或拒绝]
    
    D --> G[执行任务]
    E --> B
    F --> G
    
    G --> H[任务完成]
    H --> I[释放代理回池]

代理指标与监控

Monomind 提供了全面的代理性能监控体系。

指标类型

资料来源：packages/@monomind/cli/src/commands/hooks.ts:20-30

模型路由统计

系统支持基于任务特征动态选择最优模型：

最佳实践

代理配置建议

1. 选择合适的模板：根据项目规模和复杂度选择适当的 CLAUDE.md 模板
2. 自定义代理能力：基于 YAML 配置文件扩展代理类型
3. 启用 WASM 沙箱：对不受信任的代码执行启用沙箱隔离
4. 配置代理池：根据并发需求设置合理的池大小

性能优化

1. 预热缓存：使用 preload 触发器预加载常用资源
2. 任务批处理：将多个小任务合并为批处理
3. 智能路由：利用 route 和 coverage-route 优化任务分配
4. 令牌优化：启用 token-optimize 实现 30-50% 的令牌节省

相关文档

• CLI 命令参考
• 记忆系统
• Monograph 知识图谱
• ruvector 向量引擎

概述

智能路由系统（Intelligent Routing System）是 Monomind 框架的核心组件之一，负责将任务、请求和事件动态分配到最合适的处理节点（Agent、工作器或服务）。该系统根据多维度上下文信息（如任务类型、负载状态、Agent 能力、覆盖范围等）做出路由决策，实现多代理环境下的高效协作与资源优化。

Monomind 的路由能力通过以下子模块协同实现：

资料来源：packages/@monomind/swarm/src/queen-coordinator.ts 资料来源：packages/@monomind/cli/src/commands/hooks.ts

核心架构

任务分解与子任务路由

智能路由系统的核心之一是 Queen Coordinator 的任务分解机制。当收到一个复杂任务时，系统会将其分解为多个原子子任务，并根据依赖关系构建执行图。

graph TD
    A[接收任务请求] --> B{任务类型判断}
    B -->|信息收集型| C[分解为 gather + analyze]
    B -->|协调型| D[分解为 plan + execute]
    B -->|通用型| E[分解为单一 execute]
    C --> F[按依赖顺序执行子任务]
    D --> F
    E --> F
    F --> G[结果聚合与返回]

子任务数据结构定义如下：

interface SubTask {
  id: string;                    // 唯一标识符
  name: string;                  // 任务名称
  description: string;           // 任务描述
  type: string;                  // 任务类型：analysis/coordination/gathering
  priority: number;              // 优先级
  dependencies: string[];         // 依赖的子任务 ID
  estimatedDurationMs: number;   // 预估执行时长
  requiredCapabilities: string[]; // 所需能力列表
  recommendedDomain?: string;    // 推荐执行域
}

资料来源：packages/@monomind/swarm/src/queen-coordinator.ts:34-45

能力匹配路由

不同类型的 Agent 具备不同的专业能力。路由系统根据任务需求匹配最合适的 Agent：

资料来源：packages/@monomind/cli/src/commands/agent.ts

Hook 驱动的动态路由

Monomind 提供了一套完整的 Hook 系统，支持在任务生命周期的各个阶段进行动态路由和干预。

路由相关 Hook 命令

资料来源：packages/@monomind/cli/src/commands/hooks.ts

路由决策流程

sequenceDiagram
    participant User as 用户
    participant CLI as CLI
    participant Hook as Hook 系统
    participant Router as 路由引擎
    participant Agent as Agent 池
    
    User->>CLI: 提交任务
    CLI->>Hook: pre-task hook
    Hook->>Router: 请求路由建议
    Router->>Agent: 查询可用能力和负载
    Agent-->>Router: 返回能力评估
    Router-->>Hook: 返回最优 Agent 列表
    Hook-->>CLI: 路由决策
    CLI->>Agent: 分发任务
    Agent->>Hook: post-task hook
    Hook->>Router: 记录学习数据

模型路由

智能路由系统支持多模型路由，根据任务复杂度选择最合适的语言模型：

相关 Hook 命令：

• model-route — 路由到最优模型
• model-outcome — 记录模型路由结果
• model-stats — 查看模型路由统计

资料来源：packages/@monomind/cli/src/commands/hooks.ts

任务编排与执行

任务命令体系

资料来源：packages/@monomind/cli/src/commands/task.ts

Session 管理

路由系统支持 Session 级别的状态保持，便于复杂工作流的恢复：

资料来源：packages/@monomind/cli/src/commands/session.ts

配置与扩展

CLI 命令行使用

# 基础任务路由
monomind task create --description "分析代码库性能"

# Agent 路由
monomind agent route --task-id <id> --capabilities "code-analysis"

# 模型路由
monomind hooks model-route --task "optimization"

# 查看路由统计
monomind hooks model-stats

Agent 池管理

# 管理 Agent 池
monomind agent pool --add coder --count 3
monomind agent pool --status

# 查看 Agent 指标
monomind agent metrics
monomind agent health

资料来源：packages/@monomind/cli/src/commands/agent.ts

已知限制与注意事项

1. 源码文件缺失： packages/@monomind/routing/ 目录下的核心路由实现文件未包含在当前检索结果中。上述文档基于仓库中其他相关模块推断。
2. 覆盖范围路由： Queen Coordinator 的 inferDomainFromType 和 inferDomainFromCoverage 方法需要完整的 routing 包实现。
3. 动态模型路由： Token 优化（30-50% 节省）和模型选择功能依赖完整的 routing 和 intelligence 系统集成。

相关文档

• Swarm 协调系统
• Hook 系统
• Agent 管理
• MCP 服务器集成

概述

蜂群编排引擎是 Monomind 项目中的核心协调系统，负责管理和协调多智能体（Multi-Agent）的协作工作。该引擎通过统一的协调器（UnifiedSwarmCoordinator）实现蜂群生命周期管理、任务编排、域间路由和共识机制。

蜂群编排引擎的主要职责包括：

• 智能体注册与注销：管理蜂群中所有智能体的注册生命周期
• 任务分解与分配：将复杂任务分解为子任务并智能分配到合适的域
• 拓扑管理：维护蜂群网络拓扑结构，支持多种网络拓扑类型
• 共识协调：通过 Hive-Mind 共识机制协调多智能体决策
• 域间通信：实现基于域（Domain）的消息路由和广播

资料来源：packages/@monomind/swarm/README.md

架构设计

核心组件

graph TD
    subgraph "蜂群编排引擎核心"
        USC[统一蜂群协调器]
        TM[拓扑管理器]
        AC[注意力协调器]
        TO[任务编排器]
    end
    
    subgraph "Queen协调器"
        QC[QueenCoordinator]
        TA[任务分析器]
        ST[子任务分解器]
    end
    
    subgraph "智能体层级"
        CD[协调域 Queen]
        AD[架构域 Architect]
        PD[程序员域 Coder]
        TSD[测试域 Tester]
    end
    
    USC --> TM
    USC --> AC
    USC --> TO
    QC --> TA
    QC --> ST

协调器层次结构

蜂群采用分层协调架构，Queen 协调器位于顶层，负责战略级任务分解：

资料来源：packages/@monomind/swarm/src/queen-coordinator.ts:1-50

graph LR
    subgraph "任务分解流程"
        Task[复杂任务] --> Queen[Queen协调器]
        Queen --> Analyze[分析任务类型]
        Analyze --> Gather[信息收集子任务]
        Analyze --> Plan[规划子任务]
        Analyze --> Execute[执行子任务]
        Gather --> |依赖| Plan
        Plan --> |依赖| Execute
    end

任务编排系统

任务生命周期

任务在蜂群中经历完整的生命周期管理：

资料来源：packages/@monomind/swarm/src/coordination/task-orchestrator.ts

子任务分解策略

Queen 协调器根据任务类型采用不同的分解策略：

#### 分析类任务分解

private decomposeAnalysisTask(task: TaskDefinition): SubTask[] {
  return [
    {
      id: `${task.id.id}_gather`,
      name: 'Information Gathering',
      description: 'Gather required information',
      type: 'analysis',
      priority: task.priority,
      dependencies: [],
      estimatedDurationMs: 15000,
      requiredCapabilities: ['research', 'data-collection'],
      recommendedDomain: 'research',
    },
    {
      id: `${task.id.id}_analyze`,
      name: 'Analysis',
      description: 'Analyze gathered information',
      type: 'analysis',
      priority: task.priority,
      dependencies: [`${task.id.id}_gather`],
      estimatedDurationMs: 10000,
      requiredCapabilities: ['analysis', 'synthesis'],
      recommendedDomain: 'core',
    },
  ];
}

资料来源：packages/@monomind/swarm/src/queen-coordinator.ts:1-100

#### 协调类任务分解

private decomposeCoordinationTask(task: TaskDefinition): SubTask[] {
  return [
    {
      id: `${task.id.id}_plan`,
      name: 'Planning',
      description: 'Create coordination plan',
      type: 'coordination',
      priority: task.priority,
      dependencies: [],
      estimatedDurationMs: 5000,
      requiredCapabilities: ['planning', 'coordination'],
      recommendedDomain: 'queen',
    },
    {
      id: `${task.id.id}_execute`,
      name: 'Execution',
      description: 'Execute coordination plan',
      type: 'coordination',
      priority: task.priority,
      dependencies: [`${task.id.id}_plan`],
      estimatedDurationMs: 10000,
      requiredCapabilities: ['coordination', 'oversight'],
      recommendedDomain: 'queen',
    },
  ];
}

资料来源：packages/@monomind/swarm/src/queen-coordinator.ts:1-100

#### 通用任务分解

private decomposeGenericTask(task: TaskDefinition): SubTask[] {
  return [
    {
      id: `${task.id.id}_execute`,
      name: 'Task Execution',
      description: task.description,
      type: task.type,
      priority: task.priority,
      dependencies: [],
      estimatedDurationMs: 20000,
      requiredCapabilities: this.identifyRequiredCapabilities(task),
      recommendedDomain: this.inferDomainFromType(task.type),
    },
  ];
}

拓扑管理器

拓扑管理器负责维护蜂群的网络拓扑结构，支持动态调整和多种拓扑类型。

拓扑类型

资料来源：packages/@monomind/swarm/src/topology-manager.ts

拓扑配置示例

const topologyConfig = {
  type: 'mesh',
  domains: ['queen', 'architect', 'coder', 'tester'],
  connections: [
    { from: 'queen', to: 'architect', weight: 1.0 },
    { from: 'queen', to: 'coder', weight: 0.8 },
    { from: 'queen', to: 'tester', weight: 0.6 },
    { from: 'architect', to: 'coder', weight: 0.9 },
    { from: 'coder', to: 'tester', weight: 0.7 },
  ],
};

注意力协调器

注意力协调器（AttentionCoordinator）负责智能体间的注意力分配和资源调度，确保关键任务获得足够的计算资源。

注意力机制

graph TD
    subgraph "注意力分配流程"
        Request[注意力请求] --> Priority[优先级评估]
        Priority --> Resource[资源可用性检查]
        Resource --> Allocate[分配注意力]
        Allocate --> Update[更新状态]
    end

资料来源：packages/@monomind/swarm/src/attention-coordinator.ts

注意力参数

API 参考

UnifiedSwarmCoordinator

#### 生命周期管理

资料来源：packages/@monomind/swarm/README.md

#### 智能体管理

#### 任务管理

#### 协调机制

#### 监控接口

CLI 命令

蜂群编排引擎提供完整的命令行界面支持：

# 初始化蜂群
monomind swarm init

# 查看蜂群状态
monomind swarm status

# 列出所有域
monomind swarm domains

# 生成完整层级（15个智能体）
monomind swarm spawn --all

# 查看拓扑结构
monomind swarm topology

# 管理域成员
monomind swarm domain add <domain> <agent>
monomind swarm domain remove <domain> <agent>

# 广播消息
monomind swarm broadcast --message "task complete" --priority high

# 节点管理
monomind swarm node list
monomind swarm node health
monomind swarm node metrics

资料来源：packages/@monomind/cli/src/commands/swarm.ts

子命令详情

配置选项

蜂群配置

interface SwarmConfig {
  // 蜂群标识
  swarmId?: string;
  
  // 网络拓扑类型
  topology: 'mesh' | 'star' | 'tree' | 'ring' | 'line';
  
  // 域配置
  domains: DomainConfig[];
  
  // 协调器配置
  coordinator: {
    consensusTimeout: number;
    heartbeatInterval: number;
    maxRetries: number;
  };
  
  // 任务配置
  tasks: {
    maxConcurrent: number;
    defaultTimeout: number;
    retryPolicy: RetryPolicy;
  };
}

域配置

interface DomainConfig {
  id: number;
  name: string;
  capabilities: string[];
  priority: number;
  maxAgents: number;
  parentDomain?: number;
}

路线图

优先级 1（高优先级）

优先级 2（中优先级）

优先级 3（可选功能）

资料来源：packages/@monomind/swarm/README.md

贡献指南

本模块遵循 ADR-003: Single Coordination Engine 规范。贡献时请遵循以下原则：

1. 所有协调逻辑必须放在 UnifiedSwarmCoordinator 中
2. SwarmHub 是薄封装层，禁止在此添加新逻辑
3. 基于域的路由应用于组织分层结构
4. 性能目标必须满足（协调延迟 <100ms）
5. 新功能应通过扩展机制集成

概述

Monomind 的共识协议模块是 swarm（群体协作）子系统的核心组件，负责在分布式多代理环境中实现状态一致性、领导节点选举和故障容错。该模块位于 packages/@monomind/swarm/src/consensus/ 目录下，提供了三种可选的共识算法实现，以适应不同的应用场景和容错需求。

共识协议在 Monomind 架构中扮演着关键角色，确保多个代理（Agent）之间能够就任务分配、状态更新和决策结果达成一致意见。这对于需要协调多个代理完成复杂任务的场景尤为重要，例如代码生成、测试编排和安全审计等。

架构设计

模块位置与导出结构

Monomind 的共识模块采用策略模式设计，通过统一的接口抽象不同共识算法的实现细节。CLI 层通过 packages/@monomind/cli/src/consensus/index.ts 提供命令行交互能力，允许用户动态切换和配置共识策略。

graph TD
    A[CLI 层] --> B[consensus/index.ts]
    B --> C[共识策略接口]
    C --> D[Raft 实现]
    C --> E[Byzantine 实现]
    C --> G[Gossip 实现]
    D --> H[(状态机)]
    E --> H
    G --> H

核心接口抽象

共识模块定义了统一的接口规范，所有具体实现都必须遵循该接口契约：

Raft 共识协议

协议特点

Raft 共识协议是 Monomind 中默认的共识算法选择，其设计目标是为分布式系统提供易于理解的一致性保证。相比于 Paxos，Raft 通过分离领导选举、日志复制和安全性三个子问题来降低实现复杂度。

Raft 协议在 Monomind 中的典型应用场景包括：

• 任务队列一致性：确保任务在多个代理间的有序分配
• 状态同步：在代理集群中维护一致的状态视图
• 领导选举：在代理池中选出协调者角色

节点角色与状态转换

stateDiagram-v2
    [*] --> Follower
    Follower --> Candidate : 选举超时
    Candidate --> Leader : 获得多数票
    Candidate --> Follower : 发现新任期
    Candidate --> Candidate : 选举超时无结果
    Leader --> Follower : 发现更高任期
    Leader --> Follower : 收到AppendEntries心跳

日志复制机制

Raft 采用日志复制的方式来保证一致性。每个代理维护一个本地日志，日志条目包含待执行的命令和任期号。领导者负责接收客户端请求并将其追加到日志中，然后并行地向其他代理发送 AppendEntries RPC 以复制日志条目。

当日志条目被成功复制到多数节点后，领导者将该条目应用到状态机并返回成功响应给客户端。这种两步提交（先复制后应用）的设计确保了即使部分节点故障也不会丢失已提交的操作。

Byzantine 共识协议

容错能力

Byzantine（拜占庭）共识协议提供最强级别的容错能力，能够容忍最多三分之一的节点出现任意故障（包括恶意行为）。这使得它适用于对安全性要求极高的场景，例如：

• 敏感数据处理：涉及密钥或凭证的操作
• 跨组织协作：存在不可信节点的环境
• 审计追踪：需要防篡改的决策记录

消息签名机制

Byzantine 实现采用数字签名来验证消息来源和完整性。每个节点持有私钥对消息进行签名，其他节点使用发送者的公钥验证签名。这种机制确保了即使网络中存在恶意节点伪造消息，也无法通过身份验证。

三阶段提交

Byzantine 共识通常采用三阶段提交协议：

1. Pre-Prepare 阶段：领导者广播预处理消息，包含序列号和消息摘要
2. Prepare 阶段：节点验证消息后广播准备消息
3. Commit 阶段：收到足够数量的准备消息后进入提交阶段

sequenceDiagram
    participant L as 领导者
    participant N1 as 节点1
    participant N2 as 节点2
    participant N3 as 节点3
    
    L->>N1: Pre-Prepare(seq=5, digest)
    L->>N2: Pre-Prepare(seq=5, digest)
    L->>N3: Pre-Prepare(seq=5, digest)
    N1->>N2: Prepare(seq=5, view, N1签名)
    N1->>N3: Prepare(seq=5, view, N1签名)
    N2->>N1: Prepare(seq=5, view, N2签名)
    N2->>N3: Prepare(seq=5, view, N2签名)
    N3->>N1: Prepare(seq=5, view, N3签名)
    N3->>N2: Prepare(seq=5, view, N3签名)
    Note over N1,N2,N3: 2f+1个Prepare后进入Commit

Gossip 协议

最终一致性模型

Gossip 协议采用最终一致性模型，不追求强一致性而是允许短暂的状态不一致，最终通过节点间的随机通信收敛到一致状态。这种设计在以下场景中具有优势：

• 大规模集群：节点数量众多时通信开销低
• 动态拓扑：节点频繁加入离开的网络环境
• 高可用需求：允许短暂不一致换取可用性

通信模式

Gossip 协议的核心是周期性的对等节点间消息交换：

graph LR
    A[节点A] -- Gossip消息 --> B[节点B]
    B -- Gossip消息 --> C[节点C]
    C -- Gossip消息 --> D[节点D]
    D -- Gossip消息 --> E[节点E]
    
    style A fill:#e1f5fe
    style E fill:#e1f5fe
    style B fill:#b3e5fc
    style C fill:#b3e5fc
    style D fill:#b3e5fc

每次通信周期，节点随机选择若干对等节点交换状态信息。接收方将新数据合并到本地状态，并可能触发进一步的消息传播。典型的传播速度在 O(log N) 级别，其中 N 是集群规模。

Anti-Entropy 与消息摘要

为加速状态收敛，Gossip 实现包含 Anti-Entropy 机制，定期执行完整状态比对。节点间交换消息摘要（通常使用 Merkle Tree 或向量时钟），识别差异后仅传输必要的更新数据。这种增量同步策略显著降低了网络带宽消耗。

CLI 集成

命令行接口

Monomind CLI 提供 consensus 命令用于管理共识配置和监控集群状态：

monomind consensus <subcommand> [options]

配置选项

共识协议支持通过配置文件或环境变量进行参数调整：

运行时切换

Monomind 支持在运行时动态切换共识协议，无需停止集群服务。CLI 提供交互式向导引导用户完成配置变更：

monomind consensus configure --protocol byzantine
monomind consensus configure --protocol raft --election-timeout 250ms

配置变更通过共识协议本身传播到所有节点，确保集群配置的一致性。

安全性考量

网络隔离防护

共识模块实现了多种防护机制应对网络分区和节点故障。Raft 和 Byzantine 实现采用任期号（Term）机制识别过期消息，防止旧领导者的误操作。

消息验证

所有跨节点通信都经过完整性校验。Raft 协议通过日志条目的前置索引和任期号验证消息有效性；Byzantine 协议在此基础上增加数字签名以抵御伪造攻击。

故障检测

采用自适应心跳机制检测节点存活状态。当节点在配置的超时时间内未响应心跳，系统将其标记为可疑状态并触发相应的恢复流程。对于 Raft，可疑状态会触发新的选举；对于 Gossip，会增加消息传播路径以绕过故障节点。

性能特征

吞吐量对比

延迟优化

Raft 实现通过批量日志复制和流水线技术优化写延迟。在高速网络环境下，写操作延迟可控制在毫秒级别。Byzantine 实现由于消息签名开销和额外的通信轮次，延迟相对较高但仍在可接受范围内。

相关资源

• CLI 命令文档：packages/@monomind/cli/src/commands/consensus.ts
• Swarm 模块主文档：packages/@monomind/swarm/README.md
• 开发者指南：CONTRIBUTING.md

概述

Monomind 的记忆系统是一个多层次、智能化的向量记忆存储与检索系统，旨在为 AI Agent 提供持久化、跨会话的上下文记忆能力。该系统通过结合 HNSW（分层可导航小世界图）索引、混合后端架构和 A-MEM 自动链接机制，实现了高速语义搜索与知识关联的有机统一。

记忆系统的核心设计目标包括：

• 高性能向量检索：利用 HNSW 索引实现比暴力搜索快 150 倍至 12,500 倍的检索速度
• 混合存储架构：结合 SQLite 的结构化数据存储与 AgentDB 的语义搜索能力
• 跨会话持久化：确保 Agent 的上下文和知识跨越重启会话持续有效
• 智能知识关联：通过 A-MEM 算法自动发现语义相邻的知识条目并建立双向链接

概述

Monograph 是 Monomind 项目中的代码知识图谱系统，用于自动构建和分析代码库的完整依赖关系图谱。它在每次任务执行前自动查询图谱，确保 AI 代理能够准确理解代码结构、依赖关系和语义关联。

Monograph 的核心价值在于将静态代码分析升级为可推理的知识网络，使代码理解和任务执行变得更加精准和高效。

核心功能

依赖图谱构建

Monograph 自动分析代码库，提取以下关键信息：

图谱查询工具

# 查询与任务相关的文件（带相关性评分）
monograph_suggest "add webhook retry logic"
# → 返回按相关性排序的文件列表及评分

# 查询特定符号的依赖关系
monograph_query "UserService dependencies"
# → 返回文件路径及具体行号

# 发现代码库中的核心文件
monograph_god_nodes
# → 返回高中心性的内部文件（排除外部依赖和测试文件）

这些工具通过钩子（Hooks）和斜杠命令自动调用，无需手动干预。

架构设计

系统组件

┌─────────────────────────────────────────────────────────────┐
│                        Monograph                            │
├─────────────────┬─────────────────┬─────────────────────────┤
│   Pipeline      │     Graph       │      Query Engine       │
│   Orchestrator  │    Hotspots     │    (MCP Tools)          │
├─────────────────┼─────────────────┼─────────────────────────┤
│  - Resolution   │  - Centrality   │  - monograph_suggest    │
│  - Detection    │  - Hotspots     │  - monograph_query      │
│  - Extraction   │  - Dead Code    │  - monograph_boundary   │
│  - Health       │  - Coverage     │  - monograph_god_nodes  │
└─────────────────┴─────────────────┴─────────────────────────┘

边类型定义

资料来源：plugin/commands/monograph/README.md

节点类型

配置系统

MonographConfig 结构

interface MonographConfig {
  root?: string;
  entry?: string[];
  production?: boolean;
  detection?: 'default' | 'aggressive';
  project?: string;
  ignore?: string[];
  overrides?: OverrideConfig[];
  regression?: RegressionConfig;
  audit?: AuditConfig;
  normalization?: NormalizationConfig;
  boundaries?: BoundaryConfig;
  resolve?: ResolveConfig;
  health?: HealthConfig;
  ownership?: OwnershipConfig;
  plugins?: string[];
}

资料来源：packages/@monomind/monograph/src/config/types.ts:1-50

默认配置

export const DEFAULT_MONOGRAPH_CONFIG: ResolvedMonographConfig = {
  root: '.',
  entry: [],
  production: true,
  detection: 'default',
  project: undefined,
  ignore: [],
  overrides: [],
  regression: { tolerance: 0, baselinePath: '.monograph/regression-baseline.json' },
  audit: { gate: 'error', includeHealthGate: false },
  normalization: { stripComments: true, normalizeWhitespace: true, normalizeIdentifiers: false },
  boundaries: {},
  resolve: { paths: {}, alias: {}, conditions: [], extensions: ['.ts', '.tsx', '.mts', '.cts'] },
  health: { cyclomaticThreshold: 10, cognitiveThreshold: 15, crapThreshold: 30, minLines: 5 },
  ownership: { emailMode: 'fullEmail' },
  plugins: [],
};

扩展配置字段（Round 10）

interface ExtendedMonographConfig extends MonographConfig {
  extends?: string[];           // 继承配置
  sealed?: boolean;             // 密封配置
  includeEntryExports?: boolean; // 包含入口导出
  publicPackages?: string[];    // 公共包列表
  dynamicallyLoaded?: string[]; // 动态加载模块
  codeowners?: string;          // CODEOWNERS 文件路径
  ignoreDependencies?: string[];
  ignoreExportsUsedInFile?: boolean | { interface?: boolean; typeAlias?: boolean };
  usedClassMembers?: Array<string | { extends?: string[]; implements?: string[]; members: string[] }>;
  duplicates?: DuplicateConfig;
}

MCP 工具集成

Monograph 通过 MCP（Model Context Protocol）提供程序化查询能力，可与 Claude Code 无缝集成。

核心 MCP 工具

#### monograph_dead_code

检测代码库中无法到达的死代码。

{
  "name": "monograph_dead_code",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": { "type": "string" },
      "role": { "type": "string", "enum": ["config", "unreachable", "test"] }
    }
  }
}

输出示例：

config: 3 files — config/scripts/tooling
unreachable: 12 (2.3%) — no entry-point path found
total files: 523

#### monograph_boundary_check

检查边界区域违规，识别跨区域的未授权导入。

{
  "name": "monograph_boundary_check",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": { "type": "string" },
      "fix": { "type": "boolean" }
    }
  }
}

#### monograph_fix_orchestrator

验证修复前置条件并汇总修复计划。

{
  "name": "monograph_fix_orchestrator",
  "inputSchema": {
    "type": "object",
    "properties": {
      "root": { "type": "string" },
      "unusedExportsCount": { "type": "number" },
      "unusedDepsCount": { "type": "number" },
      "unusedEnumMembersCount": { "type": "number" },
      "dryRun": { "type": "boolean" },
      "yes": { "type": "boolean" }
    }
  }
}

资料来源：packages/@monomind/cli/src/mcp-tools/monograph-tools.ts:1-150

CLI 与 MCP 使用场景对比

健康检测

检测指标

审计配置

audit: {
  gate: 'error',           // 'error' | 'warning' | 'off'
  includeHealthGate: false // 是否包含健康检测门控
}

工作流程

标准分析流程

graph TD
    A[代码库入口] --> B[解析依赖]
    B --> C[提取符号定义]
    C --> D[构建图谱节点]
    D --> E[识别边关系]
    E --> F[健康检测]
    F --> G{通过检测?}
    G -->|是| H[生成报告]
    G -->|否| I[触发审计门控]
    I --> J[标记问题区域]
    J --> H

边界检测流程

graph TD
    A[导入语句] --> B{检查来源区域}
    B -->|合法| C[允许导入]
    B -->|违规| D{在允许列表?}
    D -->|是| C
    D -->|否| E[报告边界违规]
    C --> F[完成分析]
    E --> F

与其他模块的集成

向量记忆（Memory）

Monograph 生成的图谱数据可与 Memory 模块的向量搜索能力结合：

• 结构化查询：通过 Monograph 的图谱关系快速定位
• 语义搜索：通过 Memory 的语义向量发现关联代码
• A-MEM 自动链接：存储的条目自动发现前 3 个语义邻居，建立双向引用关系

资料来源：packages/@monomind/memory/README.md

CLAUDE.md 生成

在项目初始化时，Monograph 可自动生成 CLAUDE.md 配置文件，包含知识图谱配置部分，指导 AI 代理正确理解和操作代码结构。

使用示例

基本查询

# 构建图谱
monomind monograph build

# 搜索相关文件
monomind monograph suggest "用户认证模块"

# 查询依赖
monomind monograph query "AuthService --depends-on"

# 发现核心文件
monomind monograph god-nodes

边界检查

# 检查所有区域边界
monomind monograph boundary-check

# 检查特定区域
monomind monograph boundary-check --zone api

死代码检测

# 列出所有无法到达的代码
monomind monograph dead-code --role unreachable

# 排除测试文件误报
monomind monograph dead-code --role test

最佳实践

1. 定期重建图谱：代码库结构变更后及时更新
2. 配置合理的忽略规则：通过 ignore 字段排除第三方依赖
3. 使用边界分层：在大型项目中合理划分区域，控制依赖流向
4. 结合健康检测：在 CI/CD 中集成健康检测，及早发现问题
5. 利用 MCP 工具：在 Claude Code 会话中充分利用自动图谱查询

相关资源

• CLI 命令文档：packages/@monomind/cli/README.md
• MCP 工具文档：plugin/commands/monograph/README.md
• 配置示例：.monographrc.example.json

Pitfall Log / 踩坑日志

项目：monoes/monomind

摘要：发现 15 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：v1.10.0 — Full Paperclip Port: 55 New Mastermind Skills。

1. 安装坑 · 来源证据：v1.10.0 — Full Paperclip Port: 55 New Mastermind Skills

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.10.0 — Full Paperclip Port: 55 New Mastermind Skills
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_ba46bd2053364ab7b216b1ab09b3714a | https://github.com/monoes/monomind/releases/tag/v1.10.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：v1.6.8

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.6.8
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8e00eb27c790432ba99d18d7125b0cee | https://github.com/monoes/monomind/releases/tag/v1.6.8 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：v1.9.12 — mastermind:idea pipeline hardening

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.9.12 — mastermind:idea pipeline hardening
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6a79f40d2c5e44c4ac6b5e2e855d2a55 | https://github.com/monoes/monomind/releases/tag/v1.9.12 | 来源类型 github_release 暴露的待验证使用条件。

4. 安装坑 · 来源证据：v1.9.13 — fix: monograph never installed (workspace:* dep)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.9.13 — fix: monograph never installed (workspace:* dep)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2ffa187842b347428cc973816067e095 | https://github.com/monoes/monomind/releases/tag/v1.9.13 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

5. 安装坑 · 来源证据：v1.9.2 — mastermind:master hardening

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.9.2 — mastermind:master hardening
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_d4070dac80cb428ba72244762274a6bf | https://github.com/monoes/monomind/releases/tag/v1.9.2 | 来源类型 github_release 暴露的待验证使用条件。

6. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | github_repo:1221944165 | https://github.com/monoes/monomind | host_targets=mcp_host, claude, claude_code

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

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

8. 维护坑 · 来源证据：v1.9.1 — Init wipe-and-replace for managed Claude assets

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.9.1 — Init wipe-and-replace for managed Claude assets
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_e1832d706e974245bfbf1fb183aeafb8 | https://github.com/monoes/monomind/releases/tag/v1.9.1 | 来源类型 github_release 暴露的待验证使用条件。

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

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

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

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

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

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

12. 安全/权限坑 · 来源证据：Monomind v1.8.0 — Monograph, Mastermind & Security Hardening

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Monomind v1.8.0 — Monograph, Mastermind & Security Hardening
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_57b3501be7e943c5a3329118314c1794 | https://github.com/monoes/monomind/releases/tag/v1.8.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

13. 安全/权限坑 · 来源证据：Monomind v1.9.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Monomind v1.9.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_77db71f60ceb4346b348922fc31f9cb7 | https://github.com/monoes/monomind/releases/tag/v1.9.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

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

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

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

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