# AI智能体

**Repository Path**: gookee/ai-agent

## Basic Information

- **Project Name**: AI智能体
- **Description**: 专属AI智能体开发，自带记忆功能
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-22
- **Last Updated**: 2026-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent-AMT — AI 协作体系

> 让 AI 越用越懂你，经验越沉淀越多，而不是每次都从零开始。

---

## 这个项目解决什么问题？

日常和 AI 协作，你一定遇到过：

- 同一个坑踩了又踩，AI 不记得上次怎么解决的
- 换个客户端、换个项目，之前的经验全丢了
- AI 给的建议飘忽不定，没有可复现的规则

本体系的目标就是**让 AI 协作越用越好**：沉淀经验、防重复踩坑、规则透明可查。

核心原则：
- **实证**——规则不是拍脑袋的，是从真实踩坑中提炼的
- **主动沉淀**——AI 发现值得记的东西就主动写下来
- **边界清晰**——每个文件只管一件事，不串

---

## 架构

两层结构 + 工具目录，简单明了：

```
项目层（<project>/.agent-amt/）    ← 每个项目独立，安装时创建
├── config/        # 配置（规则、协议等，从 Git 同步）
├── rules/         # 规则（从 Git 同步）
├── guides/        # 指南（从 Git 同步）
├── templates/     # 模板（从 Git 同步）
├── memory/        # 项目记忆（本地积累，不同步）
├── MEMORY.md      # 长期记忆（本地积累，不同步）
└── chroma/        # 项目向量库（本地积累）

源码层（Git 仓库）                ← 配置的权威源
https://gitee.com/gookee/ai-agent.git
├── config/        # 配置模板
├── rules/         # 规则模板
├── guides/        # 指南模板
├── templates/     # 项目模板
├── bin/           # CLI wrapper
└── runtime/       # 运行时源码

工具目录（~/.agent-amt/）         ← 系统级工具，所有项目共享，已在 PATH 中
├── .venv/         # Python 虚拟环境
├── bin/           # CLI 工具（agent-mem, agent-setup, agent-update 等）
├── runtime/       # 运行时脚本（向量引擎、MCP server 等）
└── config/        # 工具配置（vector_search.json 等）
```

**配置从哪来？** Git 仓库（`https://gitee.com/gookee/ai-agent.git`）是配置的权威源。`agent-update` 命令从 Git 拉取最新配置到项目的 `.agent-amt/` 目录。

**AI 怎么工作？** AI 客户端进入项目后读 `AGENTS.md`，按指引加载项目层的配置、规则、记忆。每个项目一套，互不干扰。

---

## 一键安装

### Linux / macOS

```bash
curl -fsSL https://gitee.com/gookee/ai-agent/raw/master/install/install.sh | bash
```

### Windows

```powershell
irm https://gitee.com/gookee/ai-agent/raw/master/install/install.ps1 | iex
```

### 自定义安装目录

```bash
# Linux/macOS
AGENT_AMT_ROOT=~/my-agent curl -fsSL ... | bash

# Windows PowerShell
$env:AGENT_AMT_ROOT = "D:\my-agent"; irm ... | iex
```

### 安装过程

1. **检查依赖** — git + curl + uv（uv 未安装时自动安装）
2. **创建目录** — `~/.agent-amt/`
3. **下载文件** — bin/ 和 runtime/ 直接下载到安装目录
4. **创建 venv** — Python 虚拟环境
5. **安装依赖** — 基础包 + 向量记忆栈 + embedding 模型
6. **添加 PATH** — 自动把 `~/.agent-amt/bin` 加到系统 PATH

---

## 推荐：按项目拆分 workspace

如果你用 QwenPaw、Cursor、Cline 这类支持多 workspace 的工具，**强烈建议每个项目一个独立 workspace**。

为什么？记忆、对话历史、MCP 配置物理隔离，不会串项目。切 workspace 就是切上下文。

---

## 源码目录结构

本仓库是安装脚本和配置的**源码**。安装后工具在 `~/.agent-amt/`。

```
<本仓库>/
├── AGENTS.md              项目入口（AI 读的第一个文件）
├── README.md              你正在读的文件
├── install/               一键安装脚本（.bat / .ps1 / .sh）
├── bin/                   CLI wrapper（agent-mem, agent-setup, agent-update 等）
├── runtime/               运行时源码（向量引擎、MCP server 等）
├── config/                配置源码（规则、协议等）
├── rules/                 规则源码（扁平结构）
├── guides/                指南文档
├── templates/             项目初始化模板
├── dev-tools/             开发辅助工具（健康检查、一致性校验等）
├── git_hooks/             pre-commit 钩子
└── .agent-amt/            本项目的智能体数据（记忆、向量库等）
```

> 💡 子目录里不会放额外的 README——找东西看本文件或 `guides/index.md` 就行。

---

## 架构说明

**两层架构 + 工具目录**：
- **源码层**（Git 仓库）：配置的权威源，规则/配置/模板/运行时代码
- **项目层**（`.agent-amt/`）：每个项目的配置、规则、记忆、向量库等
- **工具目录**（`~/.agent-amt/`）：系统级工具，已在 PATH 中，所有项目共享

**配置同步**：
- 源码层的 `config/`、`rules/`、`guides/`、`templates/` 等是**模板**
- `agent-update` 从 Git 拉取最新配置到项目的 `.agent-amt/` 目录
- 用户在项目层积累的内容不会被 `agent-update` 覆盖

---

## 关键文件速查

| 文件 | 说明 |
|------|------|
| `AGENTS.md` | AI 进入项目后读的第一个文件 |
| `config/platform_rules.md` | 所有触发规则的全文 |
| `config/system_protocol.md` | 体系运转的完整协议 |
| `config/rules_registry.yaml` | 规则池元数据（机器可读） |
| `config/health_checklist.md` | 体系体检清单 |
| `rules/index.md` | 规则总索引 |
| `guides/index.md` | 指南索引 |
| `templates/index.md` | 模板总索引 |

---

## 改了源码后怎么同步？

修改了 `config/`、`rules/`、`guides/`、`templates/` 等配置文件后：

```bash
# 1. 提交到 Git
git add -A && git commit -m "..." && git push

# 2. 在各项目中同步（项目记忆不会被覆盖）
agent-update /path/to/project
```

修改了 `bin/`、`runtime/` 等运行时文件后：

```bash
# 升级工具（从 Git 下载最新 bin/ 和 runtime/ 到 ~/.agent-amt/）
agent-setup upgrade
```

---

## 架构图

```
┌─────────────────────────────────────────────────────────────┐
│                      客户端层                                │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  QwenPaw workspace / Cursor / Cline 等              │  │
│  │  ├── AGENTS.md（指向项目层）                          │  │
│  │  ├── skills/（客户端特有技能）                        │  │
│  │  └── agent.json（客户端配置）                         │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              ↓ 加载
┌─────────────────────────────────────────────────────────────┐
│                      项目层                                  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  <project>/.agent-amt/                               │  │
│  │  ├── config/（规则、协议等）                           │  │
│  │  ├── rules/（规则）                                   │  │
│  │  ├── guides/（指南）                                  │  │
│  │  ├── templates/（模板）                               │  │
│  │  ├── memory/（项目记忆）                              │  │
│  │  ├── MEMORY.md（长期记忆）                            │  │
│  │  └── chroma/（向量库）                                │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              ↑ agent-update 同步
┌─────────────────────────────────────────────────────────────┐
│                      源码层（Git 仓库）                      │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  https://gitee.com/gookee/ai-agent.git               │  │
│  │  ├── config/（配置模板）                              │  │
│  │  ├── rules/（规则模板）                               │  │
│  │  ├── guides/（指南模板）                              │  │
│  │  ├── templates/（项目模板）                           │  │
│  │  ├── bin/（CLI wrapper）                             │  │
│  │  └── runtime/（运行时源码）                           │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              ↑ agent-setup upgrade
┌─────────────────────────────────────────────────────────────┐
│                      工具目录                                │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  ~/.agent-amt/                                       │  │
│  │  ├── .venv/（Python 虚拟环境）                        │  │
│  │  ├── bin/（CLI 工具）                                 │  │
│  │  ├── runtime/（运行时脚本）                           │  │
│  │  └── config/（工具配置）                              │  │
│  │      └── vector_search.json（向量搜索配置）            │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

---

## 许可证

本项目采用 [CC BY-NC-SA 4.0](LICENSE) 协议发布。

简单说：你可以看、可以学、可以改，但**不能拿去商用**，改动后也必须用同样协议分享。

---

## 附录：CLI 命令参考

### agent-setup

配置工具，负责安装、初始化项目骨架、升级和体检。

```bash
agent-setup [命令] [选项]
```

| 命令 | 用途 |
|------|------|
| `install` | 安装（含向量栈） |
| `init` | 初始化项目骨架 |
| `upgrade` | 升级运行时（从 Git 下载最新） |
| `health` | 体系健康度体检 |
| `uninstall` | 卸载 |

#### agent-setup install

安装 Agent-AMT 运行时（含 Python venv、向量栈、embedding 模型）。

```bash
agent-setup install        # 安装
agent-setup install -f     # 强制覆盖已有安装
```

#### agent-setup init

为项目创建 `.agent-amt/` 骨架：目录结构、模板文件、AGENTS.md、MEMORY.md 等。

```bash
agent-setup init                        # 在当前目录初始化
agent-setup init /path/to/project       # 指定项目路径
agent-setup init -f                     # 强制覆盖已有文件
agent-setup init --ide <IDE>            # 初始化 + 生成 IDE 的 MCP 配置
```

`--ide` 参数支持的 IDE：

| IDE | 参数值 | 行为 |
|-----|--------|------|
| Trae | `trae` | 自动生成 `.trae/mcp.json` |
| Cursor | `cursor` | 自动生成 `.cursor/mcp.json` |
| VS Code | `vscode` | 自动生成 `.vscode/mcp.json` |
| Claude Code | `claude` | 自动生成 `.mcp.json` |
| QwenPaw | `qwenpaw` | 提示在 agent.json 中手动配置 |
| Cline | `cline` | 提示手动配置 |
| Kilo | `kilo` | 提示手动配置 |
| OpenCode | `opencode` | 提示手动配置 |
| Qoder | `qoder` | 提示手动配置 |
| Hermes | `hermes` | 提示手动配置 |

> 自动生成的 MCP 配置会注入 `AGENT_MEM_SCOPE` 环境变量，锁定当前项目的向量搜索范围。

#### agent-setup upgrade

从 Git 仓库下载最新 bin/ 和 runtime/ 到 `~/.agent-amt/`。

```bash
agent-setup upgrade        # 升级
agent-setup upgrade -f     # 强制覆盖
```

#### agent-setup health

体系健康度体检，检查安装完整性、配置一致性、向量库状态等。

```bash
agent-setup health          # 标准体检
agent-setup health --dev    # 开发者模式（16 项全检查）
```

#### agent-setup uninstall

卸载 Agent-AMT 运行时。

```bash
agent-setup uninstall
```

---

### agent-update

从 Git 仓库拉取最新配置到项目的 `.agent-amt/` 目录。项目记忆（memory/、MEMORY.md）不会被覆盖。

```bash
agent-update [项目路径] [选项]
```

| 参数 | 说明 |
|------|------|
| `[项目路径]` | 项目根目录，默认当前目录 |
| `--branch <分支>` | 指定 Git 分支，默认 master |
| `--force` | 强制覆盖所有文件（忽略项目层修改） |

```bash
agent-update                        # 更新当前项目
agent-update D:\项目\ai-work        # 更新指定项目
agent-update --branch main          # 从 main 分支拉取
agent-update --force                # 强制覆盖
```

**同步策略**：
- 默认模式：文件级比较，项目层有修改的文件保留不动
- `--force` 模式：强制覆盖所有文件
- 永不同步：`memory/`、`MEMORY.md`、`chroma/`

---

### agent-mem

向量记忆栈 CLI，提供语义检索、索引管理、健康检查等功能。底层是 bge 向量 + jieba 分词 + BM25 + RRF 融合，100% 本地，不需要联网。

```bash
agent-mem <子命令> [选项]
```

#### agent-mem search — 语义检索

混合检索（向量 bge + BM25 jieba + RRF 融合），秒级返回。

```bash
agent-mem search "查询词" [选项]
```

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `查询词` | 搜索内容（必填） | — |
| `--scope <名称>` | 限定搜索范围（如 `global`、项目名） | 搜索所有 scope |
| `--top <N>` | 返回前 N 条 | 5 |
| `--min-score <浮点>` | 最低分数阈值（0-1） | 0.0 |
| `--no-sync` | 跳过自动增量同步 | 自动同步 |
| `--no-hybrid` | 关掉 BM25，走纯向量检索 | 混合检索 |
| `--no-daemon` | 跳过 daemon，直接走 fork 模式 | 优先 daemon |
| `-v, --verbose` | 详细输出 | 关闭 |

```bash
agent-mem search "怎么处理异常"
agent-mem search "数据库配置" --scope ai-work --top 10
agent-mem search "部署流程" --min-score 0.3
```

#### agent-mem rebuild — 前台重建索引

强制删除后重新索引（耗时长，bge-large CPU 约 10-20 分钟）。

```bash
agent-mem rebuild [--scope <名称>]
```

#### agent-mem rebuild-bg — 后台重建索引

推荐！不占终端、不怕 timeout。

```bash
agent-mem rebuild-bg [--scope <名称>]
```

#### agent-mem status — 查看库状态

```bash
agent-mem status [--scope <名称>]
```

#### agent-mem projects — 列出所有项目

列出所有已注册的项目 scope 和路径。

```bash
agent-mem projects
```

#### agent-mem stats — 记忆使用统计

查看记忆热度和归档状态（热门/归档候选）。

```bash
agent-mem stats [--scope <名称>]
```

#### agent-mem archive — 自动归档

自动检测归档候选项（6 个月未用 + 仅用 1 次）和复活检测。

```bash
agent-mem archive [选项]
```

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--scope <名称>` | 只检测指定 scope | 所有 |
| `--months <N>` | 未使用月数阈值 | 6 |
| `--max-count <N>` | 最大使用次数阈值 | 1 |
| `--revive-threshold <N>` | 复活所需命中数 | 3 |
| `--apply` | 确认执行（不加默认只预览） | dry-run |

```bash
agent-mem archive                    # 预览归档候选
agent-mem archive --apply            # 执行归档
agent-mem archive --months 3         # 3 个月未用就归档
```

#### agent-mem doctor — 健康自检

全方位健康自检，跨电脑迁移或升级后必跑。

```bash
agent-mem doctor
```

#### agent-mem init — 初始化项目向量库

在指定目录初始化项目向量库。

```bash
agent-mem init [目录]     # 不指定则用当前目录
```

#### agent-mem install-model — 下载 embedding 模型

```bash
agent-mem install-model                    # 交互式选择模型
agent-mem install-model --model BAAI/bge-base-zh-v1.5   # 直接指定
agent-mem install-model --yes              # 非交互，按硬件推荐
```

可选模型：

| 模型 | 大小 | 内存 | 适用场景 |
|------|------|------|---------|
| `bge-small-zh-v1.5` | 95MB | 300MB | 资源紧张（手机/嵌入式） |
| `bge-base-zh-v1.5` | 400MB | 800MB | 中文办公推荐 |
| `bge-large-zh-v1.5` | 1.3GB | 2GB | 纯中文最强 |
| `bge-m3` | 2.3GB | 3GB | 多语言 + 长文本 |

#### agent-mem where — 显示安装位置

```bash
agent-mem where
```

#### agent-mem check-project — 检查项目合规性

```bash
agent-mem check-project [目录]
```

#### agent-mem migrate-project — 迁移项目到新标准

```bash
agent-mem migrate-project [目录] [--apply]
```

#### agent-mem daemon — 向量检索常驻服务

```bash
agent-mem daemon start      # 后台启动
agent-mem daemon stop       # 停止
agent-mem daemon restart    # 重启
agent-mem daemon status     # 查看状态
agent-mem daemon run        # 前台运行（调试用）
```

#### agent-mem progress — 查看后台重建进度

```bash
agent-mem progress
```

> ⚠️ Windows 用户命令加 `.bat` 后缀，如 `agent-mem.bat search "查询词"`

**AI 客户端也能直接用**：`agent-mem` 同时以 MCP server 提供 `knowledge_base_search` 和 `recall_memory` 两个工具。注册方法见 `guides/agent_mem_mcp_registration.md`。

---

### agent-rules

规则池管理 CLI，用于查看、检索、统计规则。

```bash
agent-rules <子命令> [选项]
```

| 子命令 | 用途 |
|--------|------|
| `list` | 列出所有规则（按 status/tier/weight 过滤） |
| `show <id>` | 查看单条规则详情 |
| `suggest <query>` | 按关键词+向量混合检索相关规则 |
| `stats` | 规则池统计（活跃数/沉睡数/触发热度） |
| `doctor` | 检查规则池健康度 |
| `lifecycle` | 生命周期检查（30 天 0 触发的规则降级） |
| `top <N>` | 返回 top-N 高权重活跃规则 |

```bash
agent-rules list                    # 列出所有规则
agent-rules suggest "异常处理"      # 搜索相关规则
agent-rules stats                   # 查看统计
agent-rules top 10                  # 查看前 10 条高权重规则
```

---

### agent-audit

事后审计 + 反馈闭环，扫描对话日志统计规则触发/违反情况。

```bash
agent-audit <子命令> [选项]
```

| 子命令 | 用途 |
|--------|------|
| `scan` | 扫描指定日期的对话 |
| `report` | 读 runtime + feedback 输出报告 |
| `feedback` | 仅输出 feedback（供 AGENTS.md 注入） |

```bash
agent-audit scan --date 2025-06-01          # 扫描指定日期
agent-audit scan --client qwenpaw           # 指定客户端
agent-audit report                           # 查看报告
```

环境变量 `AGENT_AUDIT=0` 可禁用审计。

---

### agent-recent

查看最近的 changelog 沉淀，用于跨会话连续性。

```bash
agent-recent [选项]
```

| 参数 | 说明 |
|------|------|
| （无参数） | 列最近 5 条 changelog 标题 |
| `-n <N>` | 列最近 N 条 |
| `--show <id>` | 显示某条 changelog 全文 |
| `--search <关键词>` | 在所有 changelogs 里搜索 |

```bash
agent-recent                    # 最近 5 条
agent-recent -n 10              # 最近 10 条
agent-recent --show 3           # 查看第 3 条全文
agent-recent --search "向量"    # 搜索关键词
```