# https://github.com/monoes/monomind 项目说明书
生成时间：2026-05-14 23:55:13 UTC
## 目录
- [项目介绍](#page-introduction)
- [快速开始](#page-quickstart)
- [系统架构](#page-architecture)
- [核心包结构](#page-package-structure)
- [代理目录](#page-agent-catalog)
- [智能路由系统](#page-routing)
- [蜂群编排引擎](#page-swarm-orchestration)
- [共识协议](#page-consensus-protocols)
- [记忆系统](#page-memory-system)
- [知识图谱(Monograph)](#page-knowledge-graph)
## 项目介绍
### 相关页面
相关主题：[系统架构](#page-architecture), [快速开始](#page-quickstart)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/monoes/monomind/blob/main/README.md)
- [packages/@monomind/cli/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/README.md)
- [packages/@monomind/memory/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/memory/README.md)
- [packages/@monomind/mcp/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/mcp/README.md)
- [packages/@monomind/cli/src/commands/agent.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/commands/agent.ts)
- [packages/@monomind/cli/src/commands/session.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/commands/session.ts)
- [packages/@monomind/cli/src/commands/plugins.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/commands/plugins.ts)
- [packages/@monomind/cli/src/init/claudemd-generator.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/init/claudemd-generator.ts)
- [plugin/commands/monograph/README.md](https://github.com/monoes/monomind/blob/main/plugin/commands/monograph/README.md)
# 项目介绍
## 概述
Monomind 是一个模块化的 AI Agent 编排框架（Modular AI Agent Orchestration Framework），旨在为开发团队提供生产级别的 AI 协作基础设施。该项目通过整合多种 AI 能力、记忆系统和编排机制，使多个 AI Agent 能够协同工作完成复杂任务。
资料来源：[README.md](https://github.com/monoes/monomind/blob/main/README.md)
## 核心定位
Monomind 的核心价值主张是"Stop prompting. Start orchestrating."（停止提示工程，开始编排）。它不是一个简单的聊天界面，而是一个完整的 Agent 协作平台，具有以下特点：
- **多 Agent 编排**：支持多种专业化的 Agent 类型协同工作
- **持久化记忆**：跨会话的向量记忆和知识图谱
- **神经网络学习**：SONA（Self-Optimizing Neural Adaptation）自优化神经适应机制
- **插件生态**：通过插件系统扩展功能
- **WASM 运行时**：支持 WebAssembly 沙箱化的 Agent 执行
资料来源：[README.md](https://github.com/monoes/monomind/blob/main/README.md)
## 系统架构
Monomind 采用模块化架构设计，主要包含以下核心组件：
```mermaid
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](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/README.md)
## 主要功能模块
### 1. Agent 管理系统
Monomind 支持多种专业化的 Agent 类型，每个 Agent 具有特定的能力范围：
| Agent 类型 | 主要能力 | 适用场景 |
|------------|----------|----------|
| `coder` | 代码生成、重构、调试、测试 | 开发任务 |
| `researcher` | 网络搜索、数据分析、摘要、引用 | 研究调查 |
| `tester` | 单元测试、集成测试、覆盖率分析 | 测试验证 |
| `reviewer` | 代码审查、安全审计、质量检查 | 代码质量 |
| `architect` | 系统设计、模式分析、可扩展性 | 架构规划 |
| `coordinator` | 任务编排、Agent 管理、工作流控制 | 任务协调 |
| `security-architect` | 威胁建模、安全模式、合规审计 | 安全领域 |
| `memory-specialist` | 向量搜索、AgentDB、缓存、优化 | 记忆管理 |
资料来源：[packages/@monomind/cli/src/commands/agent.ts](https://github.com/monoes/monomind/blob/main/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 提供完整的会话生命周期管理功能：
| 子命令 | 功能说明 |
|--------|----------|
| `list` | 列出所有会话 |
| `save` | 保存当前会话状态 |
| `restore` | 恢复已保存的会话 |
| `delete` | 删除已保存的会话 |
| `export` | 将会话导出到文件 |
| `import` | 从文件导入会话 |
| `current` | 显示当前活动会话 |
会话检查器（Session Inspector）提供完整的对话回放和工具使用分析功能。
资料来源：[packages/@monomind/cli/src/commands/session.ts](https://github.com/monoes/monomind/blob/main/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 笔记链接结构。
#### 记忆作用域
| 作用域 | 路径 | 用途 |
|--------|------|------|
| `project` | `/.claude/agent-memory//` | 项目特定的学习 |
| `local` | `/.claude/agent-memory-local//` | 本机数据 |
| `user` | `~/.claude/agent-memory//` | 跨项目用户知识 |
资料来源：[packages/@monomind/memory/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/memory/README.md)
### 4. Knowledge Graph 知识图谱（Monograph）
Monograph 构建代码库的完整依赖图，在每个任务之前自动查询：
```bash
# 查找与任务相关的文件
monograph_suggest "add webhook retry logic"
# → 返回带相关性评分的文件排名列表
# 查询依赖关系
monograph_query "UserService dependencies"
# → 返回文件路径和行号
# 查找高连通性的核心文件
monograph_god_nodes
# → 返回高中心性的内部文件（过滤外部/测试文件）
```
所有 monograph 工具都由 hooks 和斜杠命令自动调用，无需手动调用。
资料来源：[README.md](https://github.com/monoes/monomind/blob/main/README.md)
#### 节点类型
| 节点类型 | 含义 |
|----------|------|
| `File` | 源代码文件 |
| `Function` / `Class` | 函数或类 |
| `Interface` | 接口定义 |
| `Concept` | 提取的语义概念 |
| `PDF` | PDF 文档块 |
#### 边类型
| 关系 | 含义 |
|------|------|
| `IMPORTS` | 代码导入依赖 |
| `DEFINES` | 文件定义符号 |
| `TAGGED_AS` | 部分标记为概念 |
| `CO_OCCURS` | 概念共同出现 |
| `INFERRED` | Claude 提取的语义关系 |
| `DESCRIBES` / `CAUSES` / `PART_OF` | LLM 丰富的语义边 |
资料来源：[plugin/commands/monograph/README.md](https://github.com/monoes/monomind/blob/main/plugin/commands/monograph/README.md)
### 5. SONA 神经学习系统
SONA（Self-Optimizing Neural Adaptation）是 Monomind 的自优化神经适应机制：
- **模式识别**：随着时间推移改进 Agent 路由
- **轨迹追踪**：识别什么有效、什么无效
- **自动模型适配**：开销 <0.05ms
资料来源：[README.md](https://github.com/monoes/monomind/blob/main/README.md)
### 6. MCP 服务器
Monomind 提供 Model Context Protocol（MCP）服务器实现，支持与 Claude Code 集成：
#### 核心接口
**Tool 接口**：
```typescript
interface MCPTool {
name: string;
description: string;
inputSchema: JSONSchema;
handler: (input: TInput, context?: ToolContext) => Promise;
category?: string;
tags?: string[];
cacheable?: boolean;
cacheTTL?: number;
timeout?: number;
}
```
**Transport 接口**：
```typescript
interface ITransport {
readonly type: TransportType;
start(): Promise;
stop(): Promise;
onRequest(handler: RequestHandler): void;
onNotification(handler: NotificationHandler): void;
sendNotification?(notification: MCPNotification): Promise;
getHealthStatus(): Promise;
}
```
#### 内置工具
| 工具 | 功能 |
|------|------|
| `system/info` | 获取服务器信息 |
| `system/health` | 获取健康状态 |
| `system/metrics` | 获取服务器指标 |
| `tools/list-detailed` | 列出所有工具详情 |
#### 资源系统
MCP 服务器支持注册资源处理器，支持 URI 方案和 MIME 类型：
```typescript
const { resource, handler } = createTextResource(
'file://readme.txt',
'README',
'Welcome to the application!',
{ mimeType: 'text/plain' }
);
resourceRegistry.registerResource(resource, handler);
```
资料来源：[packages/@monomind/mcp/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/mcp/README.md)
### 7. 插件系统
Monomind 采用去中心化的插件注册表设计，支持 IPNS 发现和 Ed25519 签名验证。
#### 插件命令
| 子命令 | 功能 |
|--------|------|
| `list` | 列出已安装的插件 |
| `install` | 安装新插件 |
| `uninstall` | 移除已安装的插件 |
| `upgrade` | 升级已安装的插件 |
| `toggle` | 启用或禁用插件 |
| `info` | 显示插件详细信息 |
| `create` | 脚手架新插件项目 |
#### IPFS 特性
- 通过 IPNS 实现去中心化注册表以便发现
- 内容寻址存储用于完整性验证
- Ed25519 签名用于插件验证
- 信任级别：未验证、社区、已验证、官方
- 安全审计跟踪和漏洞报告
#### 官方插件
| 插件 | 功能 |
|------|------|
| `@monomind/neural` | 神经模式和推理（WASM SIMD） |
| `@monomind/security` | 安全扫描和 CVE 检测 |
| `@monomind/embeddings` | 向量嵌入（支持双曲空间） |
| `@monomind/claims` | 基于声明的授权 |
| `@monomind/performance` | 性能分析和基准测试 |
| `@monomind/plugin-gastown-bridge` | Gas Town 编排器集成（WASM 加速） |
资料来源：[packages/@monomind/cli/src/commands/plugins.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/commands/plugins.ts)
### 8. Swarm 编排系统
Swarm 是 Monomind 的 Agent 编排引擎，支持多 Agent 协作和工作流自动化。
#### Worker 类型与触发器
| Worker 类型 | 触发关键词 |
|-------------|------------|
| `map` | 代码库映射 |
| `preload` | 缓存预加载、预取、预热 |
| `deepdive` | 深度分析、深入分析、全面审查 |
| `document` | 文档生成、API 文档、JSdoc |
| `refactor` | 重构、代码质量改进 |
| `benchmark` | 性能测试、压力测试、负载测试 |
| `testgaps` | 测试覆盖率、缺失测试、测试差距 |
#### Worker 子命令
| 子命令 | 功能 |
|--------|------|
| `list` | 列出所有 Worker 及其能力 |
| `dispatch` | 分派 Worker |
| `status` | 检查 Worker 状态 |
| `detect` | 从提示检测触发器 |
| `cancel` | 取消正在运行的 Worker |
资料来源：[packages/@monomind/swarm/src/workers/worker-dispatch.js](https://github.com/monoes/monomind/blob/main/packages/@monomind/swarm/src/workers/worker-dispatch.js)
## CLAUDE.md 配置模板
Monomind 提供多种 CLAUDE.md 配置模板，用于初始化项目环境：
| 模板名称 | 描述 | 适用场景 |
|----------|------|----------|
| `minimal` | 快速启动 - 行为规则、反漂移配置 | 小型项目 |
| `standard` | 标准配置 - 包含完整功能集 | 一般项目 |
| `full` | 完整配置 - 所有高级功能 | 复杂项目 |
| `security` | 安全优先 - 安全规则和审计 | 安全敏感项目 |
| `performance` | 性能优先 - 性能优化规则 | 性能关键项目 |
| `solo` | 单一 Agent - 简化配置 | 单人开发 |
模板优先级：`options.runtime.claudeMdTemplate > 显式参数 > 'standard'`
资料来源：[packages/@monomind/cli/src/init/claudemd-generator.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/init/claudemd-generator.ts)
## Hooks 系统
Monomind 提供智能钩子系统，在任务执行过程中自动触发特定行为：
| Hook 命令 | 功能 |
|-----------|------|
| `map` | 代码库映射 |
| `preload` | 资源预加载 |
| `deepdive` | 深度代码分析 |
| `document` | 自动文档生成 |
| `refactor` | 重构建议 |
| `benchmark` | 性能基准测试 |
| `testgaps` | 测试覆盖率分析 |
资料来源：[packages/@monomind/cli/src/commands/hooks.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/commands/hooks.ts)
## 适用场景
Monomind 设计用于以下场景：
- **大型代码库**：需要多 Agent 协作处理复杂任务
- **企业开发**：团队需要共享知识和最佳实践
- **模块化项目**：多模块或多仓库管理
- **游戏工作室**：使用 Unity/Unreal/Godot 的专业 Agent
- **营销团队**：领域特定 Agent 运行内容运营
- **安全团队**：自动化审计和合规工作流
资料来源：[packages/@monomind/cli/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/README.md)
## 快速开始
```bash
# 克隆仓库
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](https://github.com/monoes/monomind/blob/main/README.md)
---
## 快速开始
### 相关页面
相关主题：[项目介绍](#page-introduction)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/monoes/monomind/blob/main/README.md)
- [packages/@monomind/cli/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/README.md)
- [packages/implementation/adrs/README.md](https://github.com/monoes/monomind/blob/main/packages/implementation/adrs/README.md)
- [packages/@monomind/memory/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/memory/README.md)
- [packages/implementation/plugins/README.md](https://github.com/monoes/monomind/blob/main/packages/implementation/plugins/README.md)
- [packages/@monomind/hooks/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/hooks/README.md)
# 快速开始
Monomind 是一个由 Sonr AI 驱动的多智能体协调系统，为开发者提供命令行工具、工作流自动化和智能记忆管理能力。本文档将帮助你在本地环境中快速安装和配置 Monomind，开始构建智能化的开发工作流。
## 系统要求
在开始安装之前，请确保你的开发环境满足以下要求：
| 要求项 | 最低版本 | 推荐版本 |
|--------|----------|----------|
| Node.js | 18.0.0 | 20.x LTS |
| npm / pnpm / yarn | npm 9.x / pnpm 8.x | 最新稳定版 |
| 操作系统 | macOS 12+ / Ubuntu 20.04+ / Windows 11 | 主流发行版 |
| 磁盘空间 | 500 MB | 1 GB+ |
| 内存 | 4 GB | 8 GB+ |
资料来源：[README.md:1-20]()
## 安装步骤
### 通过 npm 安装（推荐）
Monomind 提供全局 CLI 工具，安装过程简单快捷：
```bash
npm install -g @monomind/cli
```
或者使用 pnpm：
```bash
pnpm add -g @monomind/cli
```
### 验证安装
安装完成后，运行以下命令验证安装是否成功：
```bash
monomind doctor
```
该命令会检查环境配置并在必要时自动修复问题：
```bash
monomind doctor --fix
```
资料来源：[README.md:85-90]()
## 核心命令一览
Monomind CLI 提供丰富的命令集，涵盖任务管理、会话控制、配置管理等多个方面。
### 基础命令
| 命令 | 功能 | 状态 |
|------|------|------|
| `task` | 任务管理（创建、状态、列表、完成、取消） | ✅ 完成 |
| `session` | 会话管理（保存、恢复、列表、删除、导出） | ✅ 完成 |
| `config` | 配置管理（获取、设置、列表、重置、导出、导入） | ✅ 完成 |
| `memory` | 记忆管理（存储、检索、列表、删除、搜索） | ✅ 完成 |
| `workflow` | 工作流管理（创建、执行、列表、状态、删除） | ✅ 完成 |
| `shutdown` | 关闭系统 | ✅ 完成 |
资料来源：[packages/implementation/adrs/README.md:1-20]()
### 高级命令（V1 版本）
| 命令 | 描述 | 子命令 |
|------|------|--------|
| `neural` | 神经模式训练、MoE、Flash Attention | train, status, patterns, predict, optimize |
| `security` | 安全扫描、CVE 检测、威胁建模 | scan, cve, threats, audit, secrets |
| `performance` | 性能分析、基准测试、优化 | benchmark, profile, metrics, optimize, bottleneck |
| `providers` | AI 提供商管理、模型、配置 | list, configure, test, models, usage |
| `plugins` | 插件管理、安装、生命周期 | list, install, uninstall, toggle, info, create |
| `deployment` | 部署管理、环境、回滚 | deploy, status, rollback, history, environments, logs |
| `claims` | 声明式授权、访问控制 | list, check, grant, revoke, roles, policies |
| `embeddings` | 向量嵌入管理 | - |
资料来源：[packages/implementation/adrs/README.md:25-40]()
## 首次配置
### 初始化项目
在项目根目录运行初始化命令：
```bash
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 模板，适用于不同场景：
| 模板名称 | 适用场景 | 包含内容 |
|----------|----------|----------|
| `minimal` | 快速启动、轻量级项目 | 行为规则、反漂移配置、执行规则 |
| `standard` | 通用项目 | 标准配置 + 智能体类型 + 记忆命令 |
| `full` | 复杂企业项目 | 完整功能 + 钩子系统 + 学习协议 |
| `security` | 安全敏感项目 | 安全规则 + 安全验证 + 审计配置 |
资料来源：[packages/@monomind/cli/src/init/claudemd-generator.ts:25-50]()
## 核心功能模块
### 记忆与智能系统
Monomind 的记忆系统由三个核心组件构成：
```mermaid
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）
自动构建代码库的完整依赖图，在每个任务前自动查询：
```bash
# 查询相关文件
monograph_suggest "add webhook retry logic"
# 查询依赖关系
monograph_query "UserService dependencies"
# 查找高连接度文件
monograph_god_nodes
```
资料来源：[README.md:50-65]()
#### 向量记忆（AgentDB + HNSW）
通过 HNSW 索引实现高效的语义搜索：
| 特性 | 性能提升 |
|------|----------|
| 搜索速度 | 比暴力搜索快 150x-12,500x |
| 存储后端 | SQLite + AgentDB 混合 |
| 跨会话持久化 | 上下文跨重启保持 |
资料来源：[README.md:66-75]()
#### 神经适应（SONA）
自我优化神经适应系统从每个任务中学习：
- 模式识别提升智能体路由效率
- 轨迹追踪识别有效和无效的策略
- 自动模型适应，延迟低于 0.05ms
资料来源：[README.md:76-82]()
### 插件系统
Monomind 采用插件化架构，允许扩展核心功能：
```mermaid
graph LR
A[Monomind Core] --> B[Plugin A]
A --> C[Plugin B]
A --> D[Plugin C]
B --> E[注册智能体类型]
C --> F[注册 MCP 工具]
D --> G[注册 CLI 命令]
```
#### 插件接口
所有插件必须实现以下接口：
```typescript
interface MonomindPlugin {
readonly name: string;
readonly version: string;
initialize(context: PluginContext): Promise;
shutdown(): Promise;
// 可选扩展点
dependencies?: string[];
registerAgentTypes?(): AgentTypeDefinition[];
registerMCPTools?(): MCPToolDefinition[];
registerCLICommands?(): CLICommandDefinition[];
}
```
资料来源：[packages/implementation/plugins/README.md:40-65]()
### MCP 服务器管理
Monomind 内置 MCP（Model Context Protocol）服务器支持：
| 子命令 | 功能 |
|--------|------|
| `start` | 启动 MCP 服务器 |
| `stop` | 停止 MCP 服务器 |
| `status` | 显示服务器状态 |
| `health` | 检查服务器健康状态 |
| `restart` | 重启 MCP 服务器 |
| `tools` | 列出可用工具 |
| `toggle` | 启用/禁用工具 |
| `logs` | 显示服务器日志 |
资料来源：[packages/@monomind/cli/src/commands/mcp.ts:1-30]()
## 会话管理
Monomind 提供完整的会话管理功能，支持工作状态的保存与恢复：
| 子命令 | 功能 |
|--------|------|
| `list` | 列出所有会话 |
| `save` | 保存当前会话状态 |
| `restore` | 恢复已保存的会话 |
| `delete` | 删除已保存的会话 |
| `export` | 将会话导出到文件 |
| `import` | 从文件导入会话 |
| `current` | 显示当前活动会话 |
资料来源：[packages/@monomind/cli/src/commands/session.ts:1-25]()
## 工作流自动化
### 创建工作流
```bash
monomind workflow create --steps
```
### 执行工作流
```bash
monomind workflow execute
```
### 监控状态
```bash
monomind workflow status
```
## 故障排除
### 常见问题
| 问题 | 解决方案 |
|------|----------|
| 安装失败 | 运行 `monomind doctor --fix` 检查环境 |
| 命令未识别 | 确认已正确安装并重启终端 |
| 插件加载失败 | 检查插件版本兼容性 |
### 健康检查
```bash
# 运行完整诊断
monomind doctor
# 自动修复问题
monomind doctor --fix
```
资料来源：[README.md:85-95]()
## 下一步
- 查看 [CLAUDE.md 模板配置](packages/@monomind/cli/src/init/claudemd-generator.ts) 自定义你的项目
- 探索 [插件系统](packages/implementation/plugins/README.md) 扩展功能
- 了解 [记忆系统](packages/@monomind/memory/README.md) 的高级用法
- 配置 [钩子系统](packages/@monomind/hooks/README.md) 实现自动化工作流
---
## 系统架构
### 相关页面
相关主题：[核心包结构](#page-package-structure), [代理目录](#page-agent-catalog), [蜂群编排引擎](#page-swarm-orchestration)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/@monomind/shared/src/index.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/shared/src/index.ts)
- [packages/@monomind/shared/src/hooks/safety/file-organization.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/shared/src/hooks/safety/file-organization.ts)
- [packages/@monomind/swarm/src/queen-coordinator.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/swarm/src/queen-coordinator.ts)
- [packages/@monomind/cli/src/commands/agent.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/commands/agent.ts)
- [packages/@monomind/cli/src/commands/mcp.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/commands/mcp.ts)
- [packages/implementation/adrs/README.md](https://github.com/monoes/monomind/blob/main/packages/implementation/adrs/README.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 是整个系统的基础层，提供跨包共享的类型定义、常量、工具函数和安全规则。
#### 核心导出结构
| 导出模块 | 描述 |
|---------|------|
| `orchestrator` | 编排器核心实现 |
| `hooks/*` | 安全和验证钩子 |
| `safety/*` | 文件组织规则、安全策略 |
| `core/*` | 核心类型和接口 |
资料来源：[packages/@monomind/shared/src/index.ts:1-50]()
#### 安全与文件组织规则
系统通过正则表达式模式定义文件组织规范：
```typescript
// 源代码文件定位规则
{ 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 管理 | `create`, `list`, `status`, `stop`, `start`, `metrics`, `pool`, `health`, `logs`, `wasm-*` |
| `task` | 任务管理 | `create`, `list`, `status`, `cancel`, `assign`, `retry` |
| `session` | 会话管理 | `list`, `save`, `restore`, `delete`, `export`, `import`, `current` |
| `mcp` | MCP 服务 | `start`, `stop`, `status`, `health`, `restart`, `tools`, `toggle`, `exec`, `logs` |
| `plugins` | 插件管理 | `list`, `install`, `uninstall`, `upgrade`, `toggle`, `info`, `create` |
#### Agent 类型与能力
系统支持多种专用 Agent 类型：
```typescript
const capabilities: Record = {
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）服务器提供工具调用能力：
```mermaid
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 将复杂任务分解为子任务链：
```mermaid
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
```
#### 子任务结构
```typescript
interface SubTask {
id: string; // 唯一标识符
name: string; // 任务名称
description: string; // 任务描述
type: string; // 任务类型
priority: number; // 优先级
dependencies: string[]; // 依赖的子任务ID
estimatedDurationMs: number; // 预估执行时间
requiredCapabilities: string[];// 所需能力
recommendedDomain: string; // 推荐执行域
}
```
#### 任务类型与分解策略
| 任务类型 | 子任务链 | 预估时间 |
|---------|---------|----------|
| Research | gather → analyze | 20000ms |
| Coordination | plan → execute | 15000ms |
| Generic | execute | 20000ms |
资料来源：[packages/@monomind/swarm/src/queen-coordinator.ts:1-120]()
### Memory 层
Memory 层提供向量记忆和知识存储能力。
#### 存储层级
| 层级 | 路径模式 | 用途 |
|------|---------|------|
| `project` | `/.claude/agent-memory//` | 项目特定学习 |
| `local` | `/.claude/agent-memory-local//` | 机器本地数据 |
| `user` | `~/.claude/agent-memory//` | 跨项目用户知识 |
#### A-MEM 自动链接
当配置 `embeddingGenerator` 时，系统自动实现 Zettelkasten 笔记链接结构：
```typescript
const backend = new HybridBackend({
embeddingGenerator: async (text) => myEmbeddingModel.embed(text),
// 启用后自动进行 A-MEM 自动链接
});
```
资料来源：[packages/@monomind/memory/README.md:1-30]()
### Monograph 知识图谱
Monograph 构建代码库的完整依赖图，提供语义查询能力。
#### 图谱节点类型
| 节点类型 | 描述 |
|---------|------|
| `File` | 代码文件 |
| `Function` | 函数定义 |
| `Class` | 类定义 |
| `Concept` | 提取的语义概念 |
| `PDF` | PDF 文档块 |
#### 边类型
| 关系 | 含义 |
|-----|------|
| `IMPORTS` | 代码导入依赖 |
| `DEFINES` | 文件定义符号 |
| `TAGGED_AS` | 概念标记关联 |
| `CO_OCCURS` | 概念共现 |
| `INFERRED` | LLM 推断的语义关系 |
| `DESCRIBES/CAUSES/PART_OF` | LLM 丰富的语义边 |
#### Monograph 配置
```typescript
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]()
## 编排器架构
### 编排流程
```mermaid
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: 输出结果
```
### 编排配置
| 配置项 | 默认值 | 描述 |
|-------|-------|------|
| `production` | `true` | 生产模式标识 |
| `detection` | `'default'` | 检测策略 |
| `normalize.stripComments` | `true` | 移除注释 |
| `normalize.normalizeWhitespace` | `true` | 规范化空白 |
| `health.cyclomaticThreshold` | `10` | 圈复杂度阈值 |
| `health.cognitiveThreshold` | `15` | 认知复杂度阈值 |
## 插件系统
### 官方插件
| 插件 | 功能 |
|-----|------|
| `@monomind/neural` | 神经模式训练、MoE、Flash Attention |
| `@monomind/security` | 安全扫描、CVE 检测、威胁建模 |
| `@monomind/embeddings` | 向量嵌入、双曲空间支持 |
| `@monomind/claims` | 声明式授权、访问控制 |
| `@monomind/performance` | 性能分析、基准测试、优化 |
### 插件特性
- **IPFS 去中心化注册**：通过 IPNS 实现可发现性
- **内容寻址存储**：完整性验证
- **Ed25519 签名**：插件验证
- **信任等级**：未验证、社区验证、官方验证
## V1 命令状态
| 模块 | 命令 | 状态 |
|-----|------|------|
| Agent | create, status, list, stop, start | ✅ 完成 |
| Task | create, status, list, complete, cancel | ✅ 完成 |
| Session | save, restore, list, delete, export | ✅ 完成 |
| Config | get, set, list, reset, export, import | ✅ 完成 |
| Memory | store, retrieve, list, delete, search | ✅ 完成 |
| Workflow | create, execute, list, status, delete | ✅ 完成 |
资料来源：[packages/implementation/adrs/README.md:1-50]()
## 技术栈总结
| 层级 | 技术选型 | 用途 |
|------|---------|------|
| 运行时 | Node.js + TypeScript | 跨平台执行 |
| 向量存储 | SQLite + AgentDB + HNSW | 高性能语义搜索 |
| 图计算 | Graph Neural Networks (GNN) | 知识图谱构建 |
| 神经网络 | SONA (Self-Optimizing Neural Architecture) | 模式学习和路由优化 |
| 安全沙箱 | WASM | Agent 隔离执行 |
| 协议 | MCP (Model Context Protocol) | 工具调用标准 |
---
## 相关文档
- [CLAUDE.md 生成器](./CLAUDE.md-生成器.md)
- [插件系统](./插件系统.md)
- [Monograph 知识图谱](./monograph.md)
- [Memory 记忆系统](./memory.md)
---
## 核心包结构
### 相关页面
相关主题：[系统架构](#page-architecture), [记忆系统](#page-memory-system)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/package.json](https://github.com/monoes/monomind/blob/main/packages/package.json)
- [pnpm-workspace.yaml](https://github.com/monoes/monomind/blob/main/pnpm-workspace.yaml)
- [packages/README.md](https://github.com/monoes/monomind/blob/main/packages/README.md)
- [packages/@monomind/cli/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/README.md)
- [packages/@monomind/memory/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/memory/README.md)
- [packages/@monomind/aidefence/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/aidefence/README.md)
- [packages/implementation/adrs/README.md](https://github.com/monoes/monomind/blob/main/packages/implementation/adrs/README.md)
# 核心包结构
## 概述
Monomind 是一个采用 pnpm monorepo 架构的 AI 协调系统，由多个功能专一的 npm 包组成。核心包结构涵盖了命令行接口、向量记忆、知识图谱、安全防护、共享工具和多智能体协调等关键子系统。 资料来源：[packages/package.json](https://github.com/monoes/monomind/blob/main/packages/package.json)
---
## 架构总览
Monomind 采用分层模块化设计，各包职责清晰、边界明确：
```mermaid
graph TD
subgraph "用户交互层"
CLI["@monomind/cli
命令行接口"]
end
subgraph "核心智能层"
MEM["@monomind/memory
向量记忆系统"]
MONO["@monomind/monograph
知识图谱引擎"]
SWARM["@monomind/swarm
多智能体协调"]
end
subgraph "安全防护层"
AIDF["@monomind/aidefence
AI 防御系统"]
SAFETY["@monomind/shared
安全钩子"]
end
subgraph "扩展生态"
PLUGIN["teammate-plugin
Claude Code 插件"]
WASM["agentic-flow
WASM 代理引擎"]
end
CLI --> MEM
CLI --> MONO
CLI --> AIDF
MONO --> MEM
SWARM --> MEM
PLUGIN --> CLI
```
资料来源：[packages/README.md](https://github.com/monoes/monomind/blob/main/packages/README.md)
---
## 包结构详解
### 1. @monomind/cli — 命令行接口
**定位**：Monomind 的主要用户交互入口，提供完整的 CLI 命令体系。
**核心功能**：
| 功能模块 | 子命令 | 说明 |
|---------|--------|------|
| 会话管理 | `save`, `restore`, `list`, `delete`, `export` | 跨会话状态持久化 |
| 配置管理 | `get`, `set`, `list`, `reset`, `export`, `import` | 全局与项目配置 |
| 记忆存储 | `store`, `retrieve`, `search`, `list`, `delete` | 向量记忆操作 |
| 任务管理 | `create`, `status`, `list`, `complete`, `cancel` | 任务生命周期管理 |
| 工作流 | `create`, `execute`, `list`, `status`, `delete` | 自动化工作流编排 |
| MCP 服务 | `start`, `stop`, `status`, `health`, `restart` | MCP 协议服务管理 |
| 神经学习 | `train`, `status`, `patterns`, `predict`, `optimize` | SONA 神经网络适配 |
| 安全扫描 | `scan`, `cve`, `threats`, `audit`, `secrets` | 安全漏洞检测 |
| 性能分析 | `benchmark`, `profile`, `metrics`, `bottleneck` | 性能优化工具 |
| 知识图谱 | `suggest`, `query`, `god_nodes` | 代码依赖关系分析 |
| 部署管理 | `deploy`, `status`, `rollback`, `history` | 部署与环境管理 |
| 授权管理 | `list`, `check`, `grant`, `revoke`, `roles` | Claims 授权系统 |
| 插件系统 | `list`, `install`, `uninstall`, `toggle`, `info` | 插件生命周期管理 |
**架构特点**：
- 基于命令模式设计，每个子命令独立模块
- 支持 `suggest` 命令提供智能纠错（Levenshtein 距离算法）
- 集成 Session Inspector 可视化工具
资料来源：[packages/@monomind/cli/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/README.md)
资料来源：[packages/@monomind/cli/src/commands/session.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/commands/session.ts)
资料来源：[packages/@monomind/cli/src/commands/mcp.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/commands/mcp.ts)
资料来源：[packages/@monomind/cli/src/suggest.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/suggest.ts)
---
### 2. @monomind/memory — 向量记忆系统
**定位**：持久化语义记忆层，基于 HNSW 算法实现高速向量检索。
**核心组件**：
| 组件 | 说明 |
|------|------|
| HybridBackend | SQLite + AgentDB 混合后端 |
| HNSW Index | 150x-12,500x 加速比向量索引 |
| A-MEM | 自动链接最近语义邻居（arXiv:2409.11987） |
**存储层级**：
| 作用域 | 路径 | 用途 |
|--------|------|------|
| `project` | `/.claude/agent-memory//` | 项目级学习 |
| `local` | `/.claude/agent-memory-local//` | 机器本地数据 |
| `user` | `~/.claude/agent-memory//` | 跨项目用户知识 |
**关键 API**：
```typescript
import {
resolveAgentMemoryDir, // 获取作用域目录路径
createAgentBridge, // 创建作用域化 AutoMemoryBridge
transferKnowledge, // 跨智能体知识共享
listAgentScopes, // 发现现有智能体作用域
} from '@monomind/memory';
```
**A-MEM 自动链接机制**：当配置 `embeddingGenerator` 时，每次存储条目自动发现 Top-3 语义邻居并创建双向 `references` 边，实现 Zettelkasten 笔记链接结构。
资料来源：[packages/@monomind/memory/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/memory/README.md)
---
### 3. @monomind/monograph — 知识图谱引擎
**定位**：代码库依赖关系图谱构建与分析系统，为每次任务提供上下文相关性查询。
**核心能力**：
```bash
# 查询相关文件
monograph_suggest "add webhook retry logic"
# → 返回带相关性评分排序的文件列表
# 查询依赖关系
monograph_query "UserService dependencies"
# → 返回文件路径 + 行号
# 发现核心文件
monograph_god_nodes
# → 返回高中心性内部文件（排除外部/测试文件）
```
**图谱节点类型**：
| 节点类型 | 说明 |
|---------|------|
| `File` | 源代码文件 |
| `Class` / `Interface` | 类或接口定义 |
| `Concept` | 提取的语义概念 |
| `PDF` | PDF 文档块 |
**图谱边类型**：
| 关系类型 | 含义 |
|---------|------|
| `IMPORTS` | 代码导入依赖 |
| `DEFINES` | 文件定义符号 |
| `TAGGED_AS` | 概念标记 |
| `CO_OCCURS` | 概念共现 |
| `INFERRED` | Claude 推断的语义关系 |
| `DESCRIBES` / `CAUSES` / `PART_OF` | LLM 丰富的语义边 |
**配置结构**：
```typescript
interface MonographConfig {
root: string; // 项目根目录
entry: string[]; // 入口文件
detection: 'default'; // 检测模式
ignore: string[]; // 忽略路径
normalization: {
stripComments: boolean;
normalizeWhitespace: boolean;
normalizeIdentifiers: boolean;
};
health: {
cyclomaticThreshold: number; // 圈复杂度阈值
cognitiveThreshold: number; // 认知复杂度阈值
crapThreshold: number; // CRAP 指数阈值
};
}
```
资料来源：[plugin/commands/monograph/README.md](https://github.com/monoes/monomind/blob/main/plugin/commands/monograph/README.md)
资料来源：[packages/@monomind/monograph/src/config/types.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/monograph/src/config/types.ts)
---
### 4. @monomind/aidefence — AI 防御系统
**定位**：安全防护层，检测和阻止潜在的有害操作、敏感信息泄露和安全威胁。
**功能覆盖**：
- 安全模式识别与阻断
- 敏感信息检测（如 API 密钥、密码、令牌）
- 威胁建模与分析
- CVE 漏洞扫描
- 权限边界控制
资料来源：[packages/@monomind/aidefence/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/aidefence/README.md)
---
### 5. @monomind/shared — 共享工具库
**定位**：跨包共享的基础设施，包括工具函数、安全钩子和通用配置。
**安全文件组织规则**（示例）：
| 文件类型 | 位置规则 | 根目录限制 |
|---------|---------|-----------|
| 配置文件 | `./`, `config/` | 否 |
| 环境变量 | `./` | 否 |
| 样式表 | `styles/`, `src/styles/`, `assets/css/` | 是 |
| 字体文件 | `assets/fonts/`, `fonts/`, `public/fonts/` | 是 |
| Shell 脚本 | `scripts/`, `bin/` | 是 |
| SQL 文件 | `migrations/`, `db/`, `database/` | 是 |
| 图像资源 | `assets/`, `public/`, `images/`, `static/` | 是 |
资料来源：[packages/@monomind/shared/src/hooks/safety/file-organization.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/shared/src/hooks/safety/file-organization.ts)
---
### 6. @monomind/swarm — 多智能体协调
**定位**：多智能体系统协调器，支持任务分解和跨域协作。
**协调架构**：
```mermaid
graph LR
subgraph "任务类型"
GATHER["信息收集
Gather Task"]
ANALYZE["分析任务
Analysis Task"]
COORD["协调任务
Coordination Task"]
GENERIC["通用任务
Generic Task"]
end
GATHER -->|分解| QUERY["查询分解"]
ANALYZE -->|依赖| GATHER
QUERY --> QUERY_EXEC["执行查询"]
QUERY --> QUERY_MERGE["合并结果"]
COORD --> PLAN["规划"]
PLAN --> EXECUTE["执行"]
```
**任务分解模式**：
| 任务类型 | 子任务 | 能力要求 |
|---------|--------|---------|
| Gather | gather, merge | research, web |
| Analysis | gather, analyze | analysis, synthesis |
| Coordination | plan, execute | planning, oversight |
| Generic | execute | 动态推断 |
资料来源：[packages/@monomind/swarm/src/queen-coordinator.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/swarm/src/queen-coordinator.ts)
---
### 7. teammate-plugin — Claude Code 集成插件
**定位**：将 Monomind 能力桥接到 Claude Code 的官方插件。
**安装方式**：
```bash
# 通过 Claude Code CLI
claude plugins install @monomind/teammate-plugin
# 通过 npm
npm install @monomind/teammate-plugin
# 通过 Monomind CLI
npx @monomind/cli@latest plugins install --name @monomind/teammate-plugin
```
**核心功能**：
- 创建 Teammate Bridge 实现版本兼容检测
- 支持 Claude Code >= 2.1.19
- 提供跨会话上下文持久化
资料来源：[packages/plugins/teammate-plugin/README.md](https://github.com/monoes/monomind/blob/main/packages/plugins/teammate-plugin/README.md)
---
## 扩展包体系
### agentic-flow
高性能 WASM 驱动的代理执行引擎，提供：
- 66+ 预置代理模板
- QUIC 传输层支持
- 联邦学习框架
- ReasoningBank 推理库
### ruvector 集成
| 包 | 版本 | 说明 |
|---|------|------|
| `@ruvector/core` | 0.1.30 | Rust 原生向量数据库（52K+ 插入/秒） |
| `@ruvector/attention` | 0.1.4 | Flash Attention 机制 |
| `@ruvector/sona` | 0.1.5 | 自优化神经架构（LoRA, EWC++） |
| `@ruvector/gnn` | 0.1.22 | 图神经网络 |
资料来源：[packages/implementation/adrs/README.md](https://github.com/monoes/monomind/blob/main/packages/implementation/adrs/README.md)
---
## 工作区配置
Monomind 使用 pnpm workspaces 管理 monorepo 结构：
```yaml
# pnpm-workspace.yaml
packages:
- 'packages/**'
- 'plugin/**'
```
CLI 入口点配置：
```json
{
"bin": {
"monomind": "./bin/monomind.js"
}
}
```
资料来源：[packages/package.json](https://github.com/monoes/monomind/blob/main/packages/package.json)
---
## SONA 神经学习模块
**Self-Optimizing Neural Adaptation** — 自优化神经适配系统：
- **模式识别**：持续改进智能体路由策略
- **轨迹追踪**：识别有效/无效的工作模式
- **自动模型适配**：开销 < 0.05ms
**命令接口**：
| 子命令 | 功能 |
|--------|------|
| `neural train` | 训练神经模式 |
| `neural status` | 查看训练状态 |
| `neural patterns` | 列出已学模式 |
| `neural predict` | 预测最优路由 |
| `neural optimize` | 自动优化参数 |
---
## CLAUDE.md 生成器
`@monomind/cli` 内置 CLAUDE.md 配置生成器，支持模板化生成：
```typescript
// 模板类型
type ClaudeMdTemplate = 'standard' | 'minimal' | 'solo';
// 使用示例
import { generateClaudeMd } from './claudemd-generator';
const config = { runtime: { claudMdTemplate: 'standard' } };
const content = generateClaudeMd(config);
```
**可用模板**：
| 模板 | 用途 |
|------|------|
| `minimal` | 快速启动：行为规则、防漂移 |
| `standard` | 标准配置：完整规则集 |
| `solo` | 单人开发：简化约束 |
资料来源：[packages/@monomind/cli/src/init/claudemd-generator.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/init/claudemd-generator.ts)
---
## 依赖关系图
```mermaid
graph TD
CLI["@monomind/cli"]
MEM["@monomind/memory"]
MONO["@monomind/monograph"]
AIDF["@monomind/aidefence"]
SHARED["@monomind/shared"]
SWARM["@monomind/swarm"]
PLUGIN["teammate-plugin"]
AF["agentic-flow"]
CLI --> MEM
CLI --> MONO
CLI --> AIDF
CLI --> SHARED
CLI --> SWARM
MONO --> MEM
SWARM --> MEM
PLUGIN --> CLI
AF --> MEM
```
---
## 快速入门
```bash
# 克隆并安装
git clone https://github.com/nokhodian/monomind.git
cd monomind
pnpm install
# 诊断环境
monomind doctor --fix
# 初始化项目
monomind init
# 查看帮助
monomind --help
```
资料来源：[packages/@monomind/cli/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/README.md)
---
## 代理目录
### 相关页面
相关主题：[智能路由系统](#page-routing), [蜂群编排引擎](#page-swarm-orchestration)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/@monomind/cli/src/commands/agent.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/commands/agent.ts)
- [packages/@monomind/cli/src/commands/hooks.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/commands/hooks.ts)
- [packages/@monomind/swarm/src/workers/worker-dispatch.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/swarm/src/workers/worker-dispatch.ts)
- [packages/@monomind/cli/src/init/claudemd-generator.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/init/claudemd-generator.ts)
- [packages/@monomind/cli/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/README.md)
# 代理目录
## 概述
代理目录（Agent Directory）是 Monomind 框架中用于组织、管理和调度各类 AI 代理的核心系统。它定义了一套标准化的代理类型体系，提供了统一的代理能力描述和路由机制，使开发者能够根据任务需求选择合适的代理，并支持通过 WASM 技术实现沙箱化的安全执行环境。
Monomind 的代理目录不仅是一个静态的类型列表，更是一个动态的代理生态系统，支持自定义代理配置、代理池管理、健康监控和指标统计等功能。
## 代理类型体系
Monomind 定义了多种专业化的代理类型，每种类型针对特定的应用场景进行了优化和配置。以下是系统中支持的代理类型及其核心能力。
### 代理类型列表
| 代理类型 | 标识符 | 核心能力 |
|---------|--------|----------|
| 编码代理 | `coder` | 代码生成、重构、调试、测试 |
| 研究代理 | `researcher` | 网络搜索、数据分析、摘要、引用 |
| 测试代理 | `tester` | 单元测试、集成测试、覆盖率分析、自动化 |
| 审查代理 | `reviewer` | 代码审查、安全审计、质量检查、文档 |
| 架构代理 | `architect` | 系统设计、模式分析、可扩展性、文档 |
| 协调代理 | `coordinator` | 任务编排、代理管理、工作流控制 |
| 安全架构师 | `security-architect` | 威胁建模、安全模式、合规、审计 |
| 记忆专家 | `memory-specialist` | 向量搜索、AgentDB、缓存、优化 |
| 性能工程师 | `performance-engineer` | 性能分析、基准测试、瓶颈识别、优化 |
资料来源：[packages/@monomind/cli/src/commands/agent.ts:40-60]()
### 代理能力矩阵
每个代理类型都拥有一组特定的能力标签，用于任务路由和代理选择。以下是能力与代理类型的映射关系。
```mermaid
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` 子命令访问。
### 核心命令
| 命令 | 功能描述 |
|------|----------|
| `monomind agent list` | 列出所有已注册的代理 |
| `monomind agent start` | 启动指定代理 |
| `monomind agent stop` | 停止运行中的代理 |
| `monomind agent status` | 查看代理状态信息 |
| `monomind agent config` | 管理代理配置 |
| `monomind agent metrics` | 显示代理性能指标 |
| `monomind agent pool` | 管理代理池 |
| `monomind agent health` | 显示代理健康状态 |
| `monomind agent logs` | 查看代理日志 |
资料来源：[packages/@monomind/cli/src/commands/agent.ts:10-20]()
### WASM 沙箱代理
Monomind 支持通过 WASM 技术运行沙箱化的代理实例，提供额外的安全隔离层。
| WASM 命令 | 功能描述 |
|-----------|----------|
| `monomind agent wasm-status` | 检查 WASM 运行时可用性 |
| `monomind agent wasm-create` | 创建 WASM 沙箱化代理 |
| `monomind agent wasm-prompt` | 向 WASM 代理发送提示 |
| `monomind agent wasm-gallery` | 列出 WASM 代理模板库 |
```mermaid
graph LR
A[主进程] -->|安全通信| B[WASM Runtime]
B --> C[沙箱代理 1]
B --> D[沙箱代理 2]
B --> E[沙箱代理 N]
C -->|隔离执行| F[独立内存空间]
D -->|隔离执行| G[独立内存空间]
E -->|隔离执行| H[独立内存空间]
```
## 代理路由机制
代理路由是智能任务分配的核心组件，Monomind 通过多层决策流程将任务导向最合适的代理。
### 路由钩子命令
| 钩子命令 | 功能描述 |
|----------|----------|
| `pre-task` | 任务开始时记录并获取代理建议 |
| `post-task` | 记录任务完成用于学习 |
| `session-end` | 结束当前会话并持久化状态 |
| `session-restore` | 恢复之前的会话 |
| `route` | 将任务路由到最优代理 |
| `explain` | 解释路由决策 |
资料来源：[packages/@monomind/cli/src/commands/hooks.ts:15-25]()
### 路由触发器配置
Monomind Swarm 模块定义了基于关键词匹配的路由触发器，用于自动识别任务意图。
| 触发器 | 匹配关键词 |
|--------|------------|
| `codebase` | codebase, architecture overview, project structure, dependency graph |
| `preload` | preload, cache ahead, prefetch, warm cache |
| `deepdive` | deep dive, analyze thoroughly, in-depth analysis, comprehensive review |
| `document` | document, generate docs, add documentation, write readme |
| `refactor` | refactor, clean up code, improve code quality, restructure |
| `benchmark` | benchmark, performance test, measure speed, stress test |
| `testgaps` | test coverage, missing tests, untested code, coverage report |
资料来源：[packages/@monomind/swarm/src/workers/worker-dispatch.ts:1-50]()
## 代理配置模板
Monomind 通过 CLAUDE.md 配置文件定义代理行为，支持多种预定义模板以适应不同场景。
### 模板类型
| 模板名称 | 适用场景 |
|----------|----------|
| `minimal` | 快速启动，仅包含行为规则和防漂移配置 |
| `standard` | 标准项目，包含完整的功能模块 |
| `full` | 完整配置，包含所有高级特性 |
| `security` | 安全优先项目，强化安全检查 |
| `performance` | 性能优先项目，优化执行效率 |
| `solo` | 单人开发，简化协作相关功能 |
资料来源：[packages/@monomind/cli/src/init/claudemd-generator.ts:30-60]()
### 模板生成流程
```mermaid
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）允许同时运行多个代理实例，实现负载均衡和高可用。
### 池管理操作
| 操作 | 命令 |
|------|------|
| 查看池状态 | `monomind agent pool status` |
| 扩缩容 | `monomind agent pool scale ` |
| 健康检查 | `monomind agent pool health` |
| 分配任务 | `monomind agent pool dispatch ` |
### 代理选择策略
```mermaid
graph TD
A[新任务] --> B[检查代理可用性]
B --> C{代理池状态}
C -->|有空闲代理| D[分配任务]
C -->|无空闲代理| E[排队等待]
C -->|池已满| F[创建新实例或拒绝]
D --> G[执行任务]
E --> B
F --> G
G --> H[任务完成]
H --> I[释放代理回池]
```
## 代理指标与监控
Monomind 提供了全面的代理性能监控体系。
### 指标类型
| 指标类别 | 监控内容 |
|----------|----------|
| 执行指标 | 任务数量、成功率、平均耗时 |
| 资源指标 | CPU 使用率、内存占用、令牌消耗 |
| 学习指标 | SONA 适应度、模式识别准确率 |
| 路由指标 | 模型选择命中率、路由延迟 |
资料来源：[packages/@monomind/cli/src/commands/hooks.ts:20-30]()
### 模型路由统计
系统支持基于任务特征动态选择最优模型：
| 模型层级 | 用途 | 延迟特性 |
|----------|------|----------|
| `haiku` | 快速轻量任务 | 极低延迟 |
| `sonnet` | 平衡性能任务 | 中等延迟 |
| `opus` | 复杂推理任务 | 较高延迟 |
## 最佳实践
### 代理配置建议
1. **选择合适的模板**：根据项目规模和复杂度选择适当的 CLAUDE.md 模板
2. **自定义代理能力**：基于 YAML 配置文件扩展代理类型
3. **启用 WASM 沙箱**：对不受信任的代码执行启用沙箱隔离
4. **配置代理池**：根据并发需求设置合理的池大小
### 性能优化
1. **预热缓存**：使用 `preload` 触发器预加载常用资源
2. **任务批处理**：将多个小任务合并为批处理
3. **智能路由**：利用 `route` 和 `coverage-route` 优化任务分配
4. **令牌优化**：启用 `token-optimize` 实现 30-50% 的令牌节省
## 相关文档
- [CLI 命令参考](../cli/commands.md)
- [记忆系统](./memory/README.md)
- [Monograph 知识图谱](../monograph/README.md)
- [ruvector 向量引擎](../implementation/adrs/README.md)
---
## 智能路由系统
### 相关页面
相关主题：[代理目录](#page-agent-catalog)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/@monomind/routing/src/route-layer.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/routing/src/route-layer.ts) - **未在当前上下文提供**
- [packages/@monomind/routing/src/encoder.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/routing/src/encoder.ts) - **未在当前上下文提供**
- [packages/@monomind/routing/src/routes/index.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/routing/src/routes/index.ts) - **未在当前上下文提供**
- [packages/@monomind/cli/src/mcp-tools/agent-tools.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/mcp-tools/agent-tools.ts) - **未在当前上下文提供**
**注意：** 当前提供的代码上下文中未包含上述指定文件的内容。以下文档基于仓库中实际提供的其他相关文件（如 swarm/queen-coordinator.ts、hooks.ts 等）进行说明。
# 智能路由系统
> ⚠️ **文档状态：** 本页描述的智能路由系统基于 `packages/@monomind/routing` 包的预期功能设计。核心源码文件（`route-layer.ts`、`encoder.ts`、`routes/index.ts`）未包含在当前检索结果中。以下内容结合仓库中提供的其他相关模块（如 Swarm 协调器、Hook 系统）进行推断性说明。
## 概述
智能路由系统（Intelligent Routing System）是 Monomind 框架的核心组件之一，负责将任务、请求和事件动态分配到最合适的处理节点（Agent、工作器或服务）。该系统根据多维度上下文信息（如任务类型、负载状态、Agent 能力、覆盖范围等）做出路由决策，实现多代理环境下的高效协作与资源优化。
Monomind 的路由能力通过以下子模块协同实现：
| 模块 | 职责 | 源码位置 |
|------|------|----------|
| 任务分解与分配 | 将复杂任务拆分为子任务并分配 | `swarm/queen-coordinator.ts` |
| Hook 驱动的路由 | 基于 Hook 生命周期动态路由 | `commands/hooks.ts` |
| Agent 能力匹配 | 根据能力标签匹配合适的 Agent | `commands/agent.ts` |
| 覆盖范围路由 | 任务覆盖感知的多 Agent 协调 | `swarm/queen-coordinator.ts` |
资料来源：[packages/@monomind/swarm/src/queen-coordinator.ts](packages/@monomind/swarm/src/queen-coordinator.ts)
资料来源：[packages/@monomind/cli/src/commands/hooks.ts](packages/@monomind/cli/src/commands/hooks.ts)
## 核心架构
### 任务分解与子任务路由
智能路由系统的核心之一是 Queen Coordinator 的任务分解机制。当收到一个复杂任务时，系统会将其分解为多个原子子任务，并根据依赖关系构建执行图。
```mermaid
graph TD
A[接收任务请求] --> B{任务类型判断}
B -->|信息收集型| C[分解为 gather + analyze]
B -->|协调型| D[分解为 plan + execute]
B -->|通用型| E[分解为单一 execute]
C --> F[按依赖顺序执行子任务]
D --> F
E --> F
F --> G[结果聚合与返回]
```
子任务数据结构定义如下：
```typescript
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](packages/@monomind/swarm/src/queen-coordinator.ts)
### 能力匹配路由
不同类型的 Agent 具备不同的专业能力。路由系统根据任务需求匹配最合适的 Agent：
| Agent 类型 | 核心能力 |
|-----------|----------|
| `coder` | 代码生成、重构、调试、测试 |
| `researcher` | 网络搜索、数据分析、摘要、引用 |
| `tester` | 单元测试、集成测试、覆盖率分析 |
| `reviewer` | 代码审查、安全审计、质量检查 |
| `architect` | 系统设计、模式分析、可扩展性 |
| `coordinator` | 任务编排、Agent 管理、工作流控制 |
| `security-architect` | 威胁建模、安全模式、合规、审计 |
| `memory-specialist` | 向量搜索、AgentDB、缓存、优化 |
| `performance-engineer` | 性能分析、基准测试、优化 |
资料来源：[packages/@monomind/cli/src/commands/agent.ts](packages/@monomind/cli/src/commands/agent.ts)
## Hook 驱动的动态路由
Monomind 提供了一套完整的 Hook 系统，支持在任务生命周期的各个阶段进行动态路由和干预。
### 路由相关 Hook 命令
| Hook 命令 | 功能描述 |
|----------|----------|
| `pre-task` | 任务开始前记录并获取 Agent 建议 |
| `post-task` | 任务完成后记录学习数据 |
| `route` | 将任务路由到最优 Agent |
| `explain` | 解释路由决策的依据 |
| `model-route` | 根据模型能力路由到最优模型（haiku/sonnet/opus） |
| `coverage-route` | 基于覆盖率缺口进行任务路由 |
| `token-optimize` | Token 优化路由（节省 30-50%） |
资料来源：[packages/@monomind/cli/src/commands/hooks.ts](packages/@monomind/cli/src/commands/hooks.ts)
### 路由决策流程
```mermaid
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: 记录学习数据
```
## 模型路由
智能路由系统支持多模型路由，根据任务复杂度选择最合适的语言模型：
| 模型 | 适用场景 | 成本效率 |
|------|----------|----------|
| `haiku` | 简单分类、快速查询 | 最高 |
| `sonnet` | 标准推理、代码生成 | 中等 |
| `opus` | 复杂分析、长上下文 | 较低 |
相关 Hook 命令：
- `model-route` — 路由到最优模型
- `model-outcome` — 记录模型路由结果
- `model-stats` — 查看模型路由统计
资料来源：[packages/@monomind/cli/src/commands/hooks.ts](packages/@monomind/cli/src/commands/hooks.ts)
## 任务编排与执行
### 任务命令体系
| 子命令 | 功能 |
|--------|------|
| `create` | 创建新任务 |
| `list` | 列出所有任务 |
| `status` | 获取任务详情 |
| `cancel` | 取消运行中的任务 |
| `assign` | 分配任务给 Agent |
| `retry` | 重试失败的任务 |
资料来源：[packages/@monomind/cli/src/commands/task.ts](packages/@monomind/cli/src/commands/task.ts)
### Session 管理
路由系统支持 Session 级别的状态保持，便于复杂工作流的恢复：
| 子命令 | 功能 |
|--------|------|
| `list` | 列出所有 Session |
| `save` | 保存当前 Session 状态 |
| `restore` | 恢复已保存的 Session |
| `delete` | 删除已保存的 Session |
| `export` | 导出 Session 到文件 |
| `import` | 从文件导入 Session |
| `current` | 显示当前活动 Session |
资料来源：[packages/@monomind/cli/src/commands/session.ts](packages/@monomind/cli/src/commands/session.ts)
## 配置与扩展
### CLI 命令行使用
```bash
# 基础任务路由
monomind task create --description "分析代码库性能"
# Agent 路由
monomind agent route --task-id --capabilities "code-analysis"
# 模型路由
monomind hooks model-route --task "optimization"
# 查看路由统计
monomind hooks model-stats
```
### Agent 池管理
```bash
# 管理 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](packages/@monomind/cli/src/commands/agent.ts)
## 已知限制与注意事项
1. **源码文件缺失：** `packages/@monomind/routing/` 目录下的核心路由实现文件未包含在当前检索结果中。上述文档基于仓库中其他相关模块推断。
2. **覆盖范围路由：** Queen Coordinator 的 `inferDomainFromType` 和 `inferDomainFromCoverage` 方法需要完整的 routing 包实现。
3. **动态模型路由：** Token 优化（30-50% 节省）和模型选择功能依赖完整的 routing 和 intelligence 系统集成。
## 相关文档
- [Swarm 协调系统](./swarm-coordination.md)
- [Hook 系统](./hooks-system.md)
- [Agent 管理](../agent/overview.md)
- [MCP 服务器集成](./mcp-integration.md)
---
## 蜂群编排引擎
### 相关页面
相关主题：[共识协议](#page-consensus-protocols), [代理目录](#page-agent-catalog)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/@monomind/swarm/src/queen-coordinator.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/swarm/src/queen-coordinator.ts)
- [packages/@monomind/swarm/src/topology-manager.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/swarm/src/topology-manager.ts)
- [packages/@monomind/swarm/src/attention-coordinator.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/swarm/src/attention-coordinator.ts)
- [packages/@monomind/cli/src/commands/swarm.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/commands/swarm.ts)
- [packages/@monomind/swarm/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/swarm/README.md)
# 蜂群编排引擎
## 概述
蜂群编排引擎是 Monomind 项目中的核心协调系统，负责管理和协调多智能体（Multi-Agent）的协作工作。该引擎通过统一的协调器（UnifiedSwarmCoordinator）实现蜂群生命周期管理、任务编排、域间路由和共识机制。
蜂群编排引擎的主要职责包括：
- **智能体注册与注销**：管理蜂群中所有智能体的注册生命周期
- **任务分解与分配**：将复杂任务分解为子任务并智能分配到合适的域
- **拓扑管理**：维护蜂群网络拓扑结构，支持多种网络拓扑类型
- **共识协调**：通过 Hive-Mind 共识机制协调多智能体决策
- **域间通信**：实现基于域（Domain）的消息路由和广播
资料来源：[packages/@monomind/swarm/README.md]()
## 架构设计
### 核心组件
```mermaid
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]()
```mermaid
graph LR
subgraph "任务分解流程"
Task[复杂任务] --> Queen[Queen协调器]
Queen --> Analyze[分析任务类型]
Analyze --> Gather[信息收集子任务]
Analyze --> Plan[规划子任务]
Analyze --> Execute[执行子任务]
Gather --> |依赖| Plan
Plan --> |依赖| Execute
end
```
## 任务编排系统
### 任务生命周期
任务在蜂群中经历完整的生命周期管理：
| 阶段 | 状态 | 描述 |
|------|------|------|
| 提交 | `pending` | 任务已提交，等待处理 |
| 分析 | `analyzing` | Queen 协调器正在分析任务 |
| 分解 | `decomposing` | 任务被分解为子任务 |
| 分配 | `assigning` | 子任务分配到执行域 |
| 执行 | `executing` | 智能体正在执行任务 |
| 完成 | `completed` | 任务执行成功 |
| 失败 | `failed` | 任务执行失败 |
资料来源：[packages/@monomind/swarm/src/coordination/task-orchestrator.ts]()
### 子任务分解策略
Queen 协调器根据任务类型采用不同的分解策略：
#### 分析类任务分解
```typescript
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]()
#### 协调类任务分解
```typescript
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]()
#### 通用任务分解
```typescript
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),
},
];
}
```
## 拓扑管理器
拓扑管理器负责维护蜂群的网络拓扑结构，支持动态调整和多种拓扑类型。
### 拓扑类型
| 拓扑类型 | 描述 | 适用场景 |
|----------|------|----------|
| `mesh` | 全互联Mesh拓扑 | 高度协作型任务 |
| `star` | 星型拓扑 | 中心协调型任务 |
| `tree` | 树形拓扑 | 分层管理型任务 |
| `ring` | 环形拓扑 | 循环依赖型任务 |
| `line` | 线性拓扑 | 顺序执行型任务 |
资料来源：[packages/@monomind/swarm/src/topology-manager.ts]()
### 拓扑配置示例
```typescript
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）负责智能体间的注意力分配和资源调度，确保关键任务获得足够的计算资源。
### 注意力机制
```mermaid
graph TD
subgraph "注意力分配流程"
Request[注意力请求] --> Priority[优先级评估]
Priority --> Resource[资源可用性检查]
Resource --> Allocate[分配注意力]
Allocate --> Update[更新状态]
end
```
资料来源：[packages/@monomind/swarm/src/attention-coordinator.ts]()
### 注意力参数
| 参数 | 类型 | 描述 | 默认值 |
|------|------|------|--------|
| `attentionBudget` | `number` | 注意力预算上限 | 100 |
| `allocationStrategy` | `string` | 分配策略 | `priority` |
| `decayRate` | `number` | 注意力衰减率 | 0.95 |
| `minAllocation` | `number` | 最小分配量 | 5 |
## API 参考
### UnifiedSwarmCoordinator
#### 生命周期管理
| 方法 | 参数 | 返回值 | 描述 |
|------|------|--------|------|
| `initialize()` | - | `Promise` | 初始化协调器 |
| `shutdown()` | - | `Promise` | 关闭协调器 |
| `pause()` | - | `Promise` | 暂停操作 |
| `resume()` | - | `Promise` | 恢复操作 |
资料来源：[packages/@monomind/swarm/README.md]()
#### 智能体管理
| 方法 | 参数 | 返回值 | 描述 |
|------|------|--------|------|
| `registerAgent(agent)` | `AgentState` | `Promise` | 注册智能体 |
| `registerAgentWithDomain(agent, domain)` | `AgentState, number` | `Promise<{agentId, domain}>` | 带域注册 |
| `unregisterAgent(id)` | `AgentId` | `Promise` | 注销智能体 |
| `spawnFullHierarchy()` | - | `Promise>` | 生成15个智能体 |
| `getAgent(id)` | `AgentId` | `AgentState \| undefined` | 获取智能体 |
| `getAllAgents()` | - | `AgentState[]` | 获取所有智能体 |
| `getAgentsByDomain(domain)` | `number` | `AgentState[]` | 按域获取 |
#### 任务管理
| 方法 | 参数 | 返回值 | 描述 |
|------|------|--------|------|
| `submitTask(task)` | `TaskDefinition` | `Promise` | 提交任务 |
| `assignTaskToDomain(taskId, domain)` | `string, number` | `Promise` | 分配到域 |
| `executeParallel(tasks)` | `TaskDefinition[]` | `Promise` | 并行执行 |
| `cancelTask(taskId)` | `string` | `Promise` | 取消任务 |
| `getTask(id)` | `string` | `TaskDefinition \| undefined` | 获取任务 |
#### 协调机制
| 方法 | 参数 | 返回值 | 描述 |
|------|------|--------|------|
| `proposeConsensus(value)` | `any` | `Promise` | 提出共识 |
| `broadcastMessage(payload, priority)` | `any, Priority` | `Promise` | 广播消息 |
#### 监控接口
| 方法 | 参数 | 返回值 | 描述 |
|------|------|--------|------|
| `getState()` | - | `CoordinatorState` | 获取状态 |
| `getMetrics()` | - | `CoordinatorMetrics` | 获取指标 |
| `getPerformanceReport()` | - | `PerformanceReport` | 性能报告 |
| `getStatus()` | - | `{swarmId, status, domains, metrics}` | 综合状态 |
## CLI 命令
蜂群编排引擎提供完整的命令行界面支持：
```bash
# 初始化蜂群
monomind swarm init
# 查看蜂群状态
monomind swarm status
# 列出所有域
monomind swarm domains
# 生成完整层级（15个智能体）
monomind swarm spawn --all
# 查看拓扑结构
monomind swarm topology
# 管理域成员
monomind swarm domain add
monomind swarm domain remove
# 广播消息
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]()
### 子命令详情
| 子命令 | 描述 |
|--------|------|
| `init` | 初始化新蜂群 |
| `status` | 显示蜂群状态 |
| `domains` | 列出所有域 |
| `spawn` | 生成智能体 |
| `topology` | 查看/修改拓扑 |
| `domain` | 域管理 |
| `broadcast` | 广播消息 |
| `node` | 节点管理 |
| `consensus` | 共识操作 |
## 配置选项
### 蜂群配置
```typescript
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;
};
}
```
### 域配置
```typescript
interface DomainConfig {
id: number;
name: string;
capabilities: string[];
priority: number;
maxAgents: number;
parentDomain?: number;
}
```
## 路线图
### 优先级 1（高优先级）
| 功能 | 状态 | 描述 |
|------|------|------|
| 原生 QUIC 传输 | 待实现 | 支持 HTTP/2 回退的 QUIC 传输 |
| 蜂群学习优化器 | 待实现 | 自动拓扑优化 |
| P2P 提供商集成 | 待实现 | GunDB、IPFS 集成 |
### 优先级 2（中优先级）
| 功能 | 状态 | 描述 |
|------|------|------|
| WASM 加速索引 | 待实现 | 智能体索引加速 |
| 沙箱智能体特化 | 待实现 | 隔离执行环境 |
| 增强消息类型 | 待实现 | 燃料/内存预算支持 |
### 优先级 3（可选功能）
| 功能 | 状态 | 描述 |
|------|------|------|
| 高级 Gossip 变体 | 待实现 | 高级消息传播算法 |
| CRDT 同步 | 待实现 | 最终一致性保证 |
| Ed25519/X25519 加密 | 待实现 | 生产级加密支持 |
资料来源：[packages/@monomind/swarm/README.md]()
## 贡献指南
本模块遵循 ADR-003: Single Coordination Engine 规范。贡献时请遵循以下原则：
1. **所有协调逻辑**必须放在 `UnifiedSwarmCoordinator` 中
2. **SwarmHub** 是薄封装层，禁止在此添加新逻辑
3. **基于域的路由**应用于组织分层结构
4. **性能目标**必须满足（协调延迟 <100ms）
5. **新功能**应通过扩展机制集成
---
## 共识协议
### 相关页面
相关主题：[蜂群编排引擎](#page-swarm-orchestration)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/@monomind/swarm/src/consensus/raft.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/swarm/src/consensus/raft.ts)
- [packages/@monomind/swarm/src/consensus/byzantine.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/swarm/src/consensus/byzantine.ts)
- [packages/@monomind/swarm/src/consensus/gossip.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/swarm/src/consensus/gossip.ts)
- [packages/@monomind/cli/src/consensus/index.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/consensus/index.ts)
# 共识协议
## 概述
Monomind 的共识协议模块是 swarm（群体协作）子系统的核心组件，负责在分布式多代理环境中实现状态一致性、领导节点选举和故障容错。该模块位于 `packages/@monomind/swarm/src/consensus/` 目录下，提供了三种可选的共识算法实现，以适应不同的应用场景和容错需求。
共识协议在 Monomind 架构中扮演着关键角色，确保多个代理（Agent）之间能够就任务分配、状态更新和决策结果达成一致意见。这对于需要协调多个代理完成复杂任务的场景尤为重要，例如代码生成、测试编排和安全审计等。
## 架构设计
### 模块位置与导出结构
Monomind 的共识模块采用策略模式设计，通过统一的接口抽象不同共识算法的实现细节。CLI 层通过 `packages/@monomind/cli/src/consensus/index.ts` 提供命令行交互能力，允许用户动态切换和配置共识策略。
```mermaid
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
```
### 核心接口抽象
共识模块定义了统一的接口规范，所有具体实现都必须遵循该接口契约：
| 接口方法 | 参数 | 返回值 | 说明 |
|---------|------|--------|------|
| `initialize` | config: ConsensusConfig | Promise | 初始化共识组件 |
| `elect` | term: number | Promise | 触发领导选举 |
| `propose` | value: Proposal | Promise | 提交提案 |
| `replicate` | entries: LogEntry[] | Promise | 复制日志条目 |
| `handleMessage` | message: Message | Promise | 处理来自其他节点的消息 |
## Raft 共识协议
### 协议特点
Raft 共识协议是 Monomind 中默认的共识算法选择，其设计目标是为分布式系统提供易于理解的一致性保证。相比于 Paxos，Raft 通过分离领导选举、日志复制和安全性三个子问题来降低实现复杂度。
Raft 协议在 Monomind 中的典型应用场景包括：
- **任务队列一致性**：确保任务在多个代理间的有序分配
- **状态同步**：在代理集群中维护一致的状态视图
- **领导选举**：在代理池中选出协调者角色
### 节点角色与状态转换
```mermaid
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 阶段**：收到足够数量的准备消息后进入提交阶段
```mermaid
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 协议的核心是周期性的对等节点间消息交换：
```mermaid
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` 命令用于管理共识配置和监控集群状态：
```bash
monomind consensus [options]
```
| 子命令 | 功能描述 |
|--------|----------|
| `status` | 查看当前共识状态和集群健康状况 |
| `configure` | 配置共识参数和协议选择 |
| `metrics` | 显示共识性能指标 |
| `repair` | 修复分区后的节点状态 |
| `transfer` | 执行领导权转移 |
### 配置选项
共识协议支持通过配置文件或环境变量进行参数调整：
| 参数 | 可选值 | 默认值 | 说明 |
|------|--------|--------|------|
| `protocol` | raft, byzantine, gossip | raft | 使用的共识协议 |
| `electionTimeout` | 150-300ms | 200ms | Raft 选举超时时间 |
| `heartbeatInterval` | 50-150ms | 100ms | Raft 心跳间隔 |
| `clusterSize` | ≥1 | 3 | 集群节点数 |
| `byzantineF` | ≥0 | 1 | Byzantine 容错参数 |
| `gossipFanout` | 1-10 | 3 | Gossip 消息扇出数 |
### 运行时切换
Monomind 支持在运行时动态切换共识协议，无需停止集群服务。CLI 提供交互式向导引导用户完成配置变更：
```bash
monomind consensus configure --protocol byzantine
monomind consensus configure --protocol raft --election-timeout 250ms
```
配置变更通过共识协议本身传播到所有节点，确保集群配置的一致性。
## 安全性考量
### 网络隔离防护
共识模块实现了多种防护机制应对网络分区和节点故障。Raft 和 Byzantine 实现采用任期号（Term）机制识别过期消息，防止旧领导者的误操作。
### 消息验证
所有跨节点通信都经过完整性校验。Raft 协议通过日志条目的前置索引和任期号验证消息有效性；Byzantine 协议在此基础上增加数字签名以抵御伪造攻击。
### 故障检测
采用自适应心跳机制检测节点存活状态。当节点在配置的超时时间内未响应心跳，系统将其标记为可疑状态并触发相应的恢复流程。对于 Raft，可疑状态会触发新的选举；对于 Gossip，会增加消息传播路径以绕过故障节点。
## 性能特征
### 吞吐量对比
| 协议 | 理论吞吐量 | 延迟 | 适用规模 |
|------|-----------|------|----------|
| Raft | 高 | 低-中 | 3-50 节点 |
| Byzantine | 中-低 | 中-高 | 4-20 节点 |
| Gossip | 极高 | 中 | 50+ 节点 |
### 延迟优化
Raft 实现通过批量日志复制和流水线技术优化写延迟。在高速网络环境下，写操作延迟可控制在毫秒级别。Byzantine 实现由于消息签名开销和额外的通信轮次，延迟相对较高但仍在可接受范围内。
## 相关资源
- **CLI 命令文档**：[packages/@monomind/cli/src/commands/consensus.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/commands/consensus.ts)
- **Swarm 模块主文档**：[packages/@monomind/swarm/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/swarm/README.md)
- **开发者指南**：[CONTRIBUTING.md](https://github.com/monoes/monomind/blob/main/CONTRIBUTING.md)
---
## 记忆系统
### 相关页面
相关主题：[知识图谱(Monograph)](#page-knowledge-graph)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/@monomind/memory/src/agentdb-backend.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/memory/src/agentdb-backend.ts)
- [packages/@monomind/memory/src/hnsw-index.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/memory/src/hnsw-index.ts)
- [packages/@monomind/memory/src/hybrid-backend.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/memory/src/hybrid-backend.ts)
- [packages/@monomind/memory/src/agent-memory-scope.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/memory/src/agent-memory-scope.ts)
# 记忆系统
## 概述
Monomind 的记忆系统是一个多层次、智能化的向量记忆存储与检索系统，旨在为 AI Agent 提供持久化、跨会话的上下文记忆能力。该系统通过结合 HNSW（分层可导航小世界图）索引、混合后端架构和 A-MEM 自动链接机制，实现了高速语义搜索与知识关联的有机统一。
记忆系统的核心设计目标包括：
- **高性能向量检索**：利用 HNSW 索引实现比暴力搜索快 150 倍至 12,500 倍的检索速度
- **混合存储架构**：结合 SQLite 的结构化数据存储与 AgentDB 的语义搜索能力
- **跨会话持久化**：确保 Agent 的上下文和知识跨越重启会话持续有效
- **智能知识关联**：通过 A-MEM 算法自动发现语义相邻的知识条目并建立双向链接
---
## 系统架构
### 整体架构图
```mermaid
graph TB
subgraph "记忆系统核心层"
HB[HybridBackend
混合后端]
AB[AgentDBBackend
AgentDB 后端]
HN[HNSWIndex
HNSW 索引]
SQ[SQLite
结构化存储]
end
subgraph "存储层级"
PD[项目级别
project]
LD[机器本地
local]
UD[用户级别
user]
end
subgraph "功能模块"
AM[AgentMemoryScope
作用域管理]
ABridge[AutoMemoryBridge
自动记忆桥接]
TK[transferKnowledge
知识转移]
end
HB --> AB
HB --> SQ
AB --> HN
AM --> PD
AM --> LD
AM --> UD
HB --> AM
ABridge --> HB
TK --> ABridge
```
### 核心组件
| 组件名称 | 类型 | 职责描述 |
|---------|------|---------|
| `HybridBackend` | 类 | 混合存储引擎，整合 AgentDB 与 SQLite，统一管理向量与结构化数据 |
| `AgentDBBackend` | 类 | 基于 HNSW 的向量数据库后端，提供语义搜索能力 |
| `HNSWIndex` | 类 | HNSW 分层可导航小世界图索引实现，支持高效最近邻搜索 |
| `AgentMemoryScope` | 类 | 管理 Agent 记忆的作用域，支持项目、本地、用户三个层级 |
| `AutoMemoryBridge` | 接口 | 自动记忆同步桥接器，负责跨作用域的记忆同步 |
| `embeddingGenerator` | 函数 | 向量嵌入生成器，为 A-MEM 自动链接提供语义编码能力 |
---
## HNSW 索引机制
### 什么是 HNSW
HNSW（Hierarchical Navigable Small World，分层可导航小世界）是一种基于图的近似最近邻搜索算法。它通过构建多层跳跃链接的导航结构，在保证搜索精度的同时实现对数级别的查询复杂度。
Monomind 记忆系统使用 HNSW 索引实现 **150x-12,500x** 的搜索性能提升，相比传统的暴力搜索具有显著优势。
### HNSW 索引特点
```mermaid
graph LR
A[查询向量] --> B[顶层搜索]
B --> C[逐层下沉]
C --> D[精确近邻]
E[O(n) 暴力搜索] -.-> F[低效]
G[O(log n) HNSW] -.-> H[高效]
```
| 特性 | 说明 |
|------|------|
| 分层结构 | 多层图结构，上层稀疏下层密集 |
| 贪婪搜索 | 每层使用贪婪策略寻找最近邻 |
| 候选集扩展 | 搜索时维护候选队列平衡精度与速度 |
| 内存优化 | 支持增量构建与内存映射 |
资料来源：[packages/@monomind/memory/src/hnsw-index.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/memory/src/hnsw-index.ts)
---
## 混合后端架构
### HybridBackend 设计
`HybridBackend` 是记忆系统的核心存储引擎，它将结构化数据存储与向量语义搜索有机结合：
```mermaid
flowchart LR
subgraph HybridBackend
direction TB
V[(向量存储
AgentDB)]
S[(结构化存储
SQLite)]
end
Store[存储请求] --> Parse{解析类型}
Parse -->|向量数据| V
Parse -->|结构化数据| S
Query[查询请求] --> Q{查询类型}
Q -->|语义搜索| V
Q -->|精确查询| S
```
### 核心功能
| 功能 | 描述 | 性能指标 |
|------|------|---------|
| 向量存储 | 存储嵌入向量与关联元数据 | 支持批量操作 |
| 语义搜索 | 基于余弦相似度或欧氏距离的向量检索 | 150x-12,500x 加速 |
| 结构化存储 | SQLite 管理的键值与表格数据 | ACID 事务支持 |
| A-MEM 自动链接 | 存储时自动发现语义邻居并建立双向引用 | 异步执行 |
### A-MEM 自动链接
A-MEM（论文 arXiv:2409.11987）是一种基于注意力的记忆增强方法。当 `HybridBackend` 配置了 `embeddingGenerator` 时，系统会自动：
1. 为每个新存储的条目生成向量嵌入
2. 在已有记忆中查找语义最相似的 Top-3 条目
3. 自动创建双向 `references` 边，实现 Zettelkasten 笔记链接结构
```typescript
const backend = new HybridBackend({
embeddingGenerator: async (text) => myEmbeddingModel.embed(text),
// A-MEM auto-linking is automatically active when embeddingGenerator is set
});
```
资料来源：[packages/@monomind/memory/src/hybrid-backend.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/memory/src/hybrid-backend.ts)
---
## 作用域管理
### AgentMemoryScope 层级架构
记忆系统通过 `AgentMemoryScope` 支持三种作用域，实现不同范围的知识共享与隔离：
| 作用域 | 路径格式 | 用途 | 可见范围 |
|--------|----------|------|----------|
| `project` | `/.claude/agent-memory//` | 项目特定学习内容 | 仅当前项目 |
| `local` | `/.claude/agent-memory-local//` | 机器本地数据 | 当前机器所有项目 |
| `user` | `~/.claude/agent-memory//` | 跨项目用户知识 | 用户所有设备 |
```mermaid
graph TD
subgraph "作用域层级"
User["👤 User
~/.claude/agent-memory/"]
Local["💻 Local
.claude/agent-memory-local/"]
Project["📁 Project
.claude/agent-memory/"]
end
User -->|继承| Local
Local -->|继承| Project
```
### 作用域管理 API
```typescript
import {
resolveAgentMemoryDir, // 获取作用域目录路径
createAgentBridge, // 创建作用域限定的 AutoMemoryBridge
transferKnowledge, // 跨 Agent 知识共享
listAgentScopes, // 发现现有 Agent 作用域
} from '@monomind/memory';
// 获取特定作用域的路径
const dir = resolveAgentMemoryDir('my-agent', 'project');
// → /workspaces/my-project/.claude/agent-memory/my-agent/
// 列出所有 Agent 作用域
const scopes = await listAgentScopes('/workspaces/my-project');
// [{ agentName: 'coder', scope: 'project', path: '...' }, ...]
```
资料来源：[packages/@monomind/memory/src/agent-memory-scope.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/memory/src/agent-memory-scope.ts)
---
## CLI 命令接口
记忆系统提供完整的命令行接口，支持多种操作：
| 命令 | 功能描述 | 关键参数 |
|------|----------|----------|
| `monomind memory init` | 初始化记忆数据库 | sql.js |
| `monomind memory store` | 存储数据到记忆 | -k/-k, --key |
| `monomind memory retrieve` | 检索记忆数据 | -k/-k, --key |
| `monomind memory search` | 语义/向量搜索 | -q, --query |
| `monomind memory list` | 列出记忆条目 | -t, --type |
| `monomind memory delete` | 删除记忆条目 | -k/-k, --key |
| `monomind memory stats` | 显示统计信息 | - |
| `monomind memory configure` | 配置后端 | - |
| `monomind memory cleanup` | 清理过期条目 | --older-than |
| `monomind memory compress` | 压缩数据库 | - |
| `monomind memory export` | 导出记忆到文件 | -o, --output |
| `monomind memory import` | 从文件导入 | -i, --input |
### 常用操作示例
```bash
# 初始化记忆数据库
monomind memory init
# 存储知识条目
monomind memory store --key "design-pattern:observer" --value "观察者模式用于..."
# 语义搜索
monomind memory search --query "如何实现观察者模式"
# 查看统计信息
monomind memory stats
# 导出记忆
monomind memory export --output ./backup/memory.json
```
资料来源：[packages/@monomind/cli/src/commands/memory.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/commands/memory.ts)
---
## 数据模型
### AgentDB 后端数据模型
```typescript
interface MemoryEntry {
id: string; // 唯一标识符
key: string; // 检索键
value: string; // 存储值
metadata?: { // 可选元数据
createdAt: number;
updatedAt: number;
tags?: string[];
references?: string[]; // A-MEM 自动链接的引用
};
vector?: number[]; // 向量嵌入（可选）
}
interface SearchResult {
id: string;
score: number; // 相似度得分
entry: MemoryEntry;
}
```
### 索引配置选项
| 选项 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `m` | number | 16 | 每层最大连接数 |
| `efConstruction` | number | 200 | 构建时搜索范围 |
| `efSearch` | number | 100 | 搜索时搜索范围 |
| `mult` | number | 1.0 | 距离归一化系数 |
资料来源：[packages/@monomind/memory/src/agentdb-backend.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/memory/src/agentdb-backend.ts)
---
## 性能优化
### 向量检索性能基准
| 数据规模 | 暴力搜索 | HNSW 索引 | 加速比 |
|----------|----------|-----------|--------|
| 1,000 条 | 基准 | 150x | 150 倍 |
| 10,000 条 | 基准 | 1,000x | 1,000 倍 |
| 100,000 条 | 基准 | 5,000x | 5,000 倍 |
| 1,000,000 条 | 基准 | 12,500x | 12,500 倍 |
### 优化策略
1. **批量写入**：使用批量 API 减少索引重建开销
2. **EFSearch 调优**：根据精度要求调整搜索范围
3. **内存映射**：对大规模数据集启用内存映射
4. **异步 A-MEM**：自动链接在后台异步执行，不阻塞存储操作
---
## 与其他模块的集成
### 集成关系图
```mermaid
graph LR
subgraph "Monomind 核心模块"
M[记忆系统
@monomind/memory]
G[图谱系统
@monomind/monograph]
I[智能系统
Intelligence]
C[CLI
@monomind/cli]
end
G -->|Monograph Suggest| M
I -->|Pattern Learning| M
C -->|Command Interface| M
M -->|知识存储| G
M -->|学习数据| I
```
### 与 Monograph 图谱的关系
记忆系统与 Monograph 知识图谱形成互补：
- **Monograph**：基于代码依赖和语义的图结构知识
- **Memory**：基于向量嵌入的语义记忆存储
两者可以协同工作：Monograph 提供代码结构洞察，Memory 存储决策上下文和模式学习结果。
---
## 最佳实践
### 1. 选择合适的作用域
```mermaid
flowchart TD
A{知识用途?}
A -->|仅限当前项目| B[使用 project 作用域]
A -->|本机多项目共享| C[使用 local 作用域]
A -->|跨设备用户知识| D[使用 user 作用域]
B --> E[项目特定配置]
C --> F[机器本地缓存]
D --> G[用户通用知识]
```
### 2. 配置 A-MEM 自动链接
```typescript
// 推荐：为 HybridBackend 配置嵌入生成器以启用 A-MEM
const backend = new HybridBackend({
embeddingGenerator: async (text) =>
await embeddingModel.embed(text),
});
```
### 3. 定期维护
```bash
# 清理过期条目
monomind memory cleanup --older-than 30d
# 压缩数据库
monomind memory compress
# 导出备份
monomind memory export --output backup-$(date +%Y%m%d).json
```
---
## 相关资源
- **npm 包**：[@monomind/memory](https://www.npmjs.com/package/@monomind/memory)
- **向量数据库**：[agentdb](https://www.npmjs.com/package/agentdb) - HNSW 向量数据库
- **CLI 文档**：[packages/@monomind/cli/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/README.md)
- **A-MEM 论文**：[arXiv:2409.11987](https://arxiv.org/abs/2409.11987)
---
## 知识图谱(Monograph)
### 相关页面
相关主题：[记忆系统](#page-memory-system)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/@monomind/monograph/src/config/types.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/monograph/src/config/types.ts)
- [packages/@monomind/cli/src/mcp-tools/monograph-tools.ts](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/src/mcp-tools/monograph-tools.ts)
- [packages/@monomind/cli/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/cli/README.md)
- [plugin/commands/monograph/README.md](https://github.com/monoes/monomind/blob/main/plugin/commands/monograph/README.md)
- [packages/@monomind/memory/README.md](https://github.com/monoes/monomind/blob/main/packages/@monomind/memory/README.md)
# 知识图谱(Monograph)
## 概述
Monograph 是 Monomind 项目中的**代码知识图谱系统**，用于自动构建和分析代码库的完整依赖关系图谱。它在每次任务执行前自动查询图谱，确保 AI 代理能够准确理解代码结构、依赖关系和语义关联。
Monograph 的核心价值在于将静态代码分析升级为可推理的知识网络，使代码理解和任务执行变得更加精准和高效。
## 核心功能
### 依赖图谱构建
Monograph 自动分析代码库，提取以下关键信息：
| 功能 | 说明 |
|------|------|
| **文件关系** | 追踪文件间的导入依赖路径 |
| **符号定义** | 记录每个文件定义的符号（类、接口、函数） |
| **语义概念** | 从代码注释和文档中提取语义概念 |
| **边界检测** | 识别跨模块、跨层的违规导入 |
| **热点分析** | 发现高连接度和高复杂度的关键文件 |
### 图谱查询工具
```bash
# 查询与任务相关的文件（带相关性评分）
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 │
└─────────────────┴─────────────────┴─────────────────────────┘
```
### 边类型定义
| 关系类型 | 含义 |
|----------|------|
| `IMPORTS` | 代码导入依赖关系 |
| `DEFINES` | 文件定义某个符号 |
| `TAGGED_AS` | 代码段被标记为某概念 |
| `CO_OCCURS` | 多个概念同时出现 |
| `INFERRED` | Claude 提取的语义关系 |
| `DESCRIBES` | 描述性关系 |
| `CAUSES` | 因果关系 |
| `PART_OF` | 组成关系 |
资料来源：[plugin/commands/monograph/README.md]()
### 节点类型
| 类型 | 说明 |
|------|------|
| `File` | 源代码文件 |
| `Symbol` | 代码符号（类、接口、函数） |
| `Concept` | 提取的语义概念 |
| `PDF` | PDF 文档块 |
## 配置系统
### MonographConfig 结构
```typescript
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]()
### 默认配置
```typescript
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）
```typescript
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;
duplicates?: DuplicateConfig;
}
```
## MCP 工具集成
Monograph 通过 MCP（Model Context Protocol）提供程序化查询能力，可与 Claude Code 无缝集成。
### 核心 MCP 工具
#### monograph_dead_code
检测代码库中无法到达的死代码。
```json
{
"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
检查边界区域违规，识别跨区域的未授权导入。
```json
{
"name": "monograph_boundary_check",
"inputSchema": {
"type": "object",
"properties": {
"path": { "type": "string" },
"fix": { "type": "boolean" }
}
}
}
```
#### monograph_fix_orchestrator
验证修复前置条件并汇总修复计划。
```json
{
"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 使用场景对比
| 场景 | 推荐方式 |
|------|----------|
| 一次性构建 | CLI (`npx monomind monograph ...`) |
| 手动搜索 | CLI |
| 终端监控 | CLI |
| Claude Code 集成 | MCP Tools (`mcp__monomind__monograph_*`) |
| 任务中程序化查询 | MCP Tools |
## 健康检测
### 检测指标
| 指标 | 默认阈值 | 说明 |
|------|----------|------|
| 圈复杂度 | 10 | 函数/方法的决策分支数 |
| 认知复杂度 | 15 | 代码理解的难度度量 |
| CRAP 指数 | 30 | 变更风险和复杂度综合指数 |
| 最小代码行数 | 5 | 过滤短小函数 |
### 审计配置
```typescript
audit: {
gate: 'error', // 'error' | 'warning' | 'off'
includeHealthGate: false // 是否包含健康检测门控
}
```
## 工作流程
### 标准分析流程
```mermaid
graph TD
A[代码库入口] --> B[解析依赖]
B --> C[提取符号定义]
C --> D[构建图谱节点]
D --> E[识别边关系]
E --> F[健康检测]
F --> G{通过检测?}
G -->|是| H[生成报告]
G -->|否| I[触发审计门控]
I --> J[标记问题区域]
J --> H
```
### 边界检测流程
```mermaid
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 代理正确理解和操作代码结构。
## 使用示例
### 基本查询
```bash
# 构建图谱
monomind monograph build
# 搜索相关文件
monomind monograph suggest "用户认证模块"
# 查询依赖
monomind monograph query "AuthService --depends-on"
# 发现核心文件
monomind monograph god-nodes
```
### 边界检查
```bash
# 检查所有区域边界
monomind monograph boundary-check
# 检查特定区域
monomind monograph boundary-check --zone api
```
### 死代码检测
```bash
# 列出所有无法到达的代码
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`
---
---
## Doramagic 踩坑日志
项目：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