内容
Agent Royo Learn
[](README.md)
[](docs/README.es.md)
[](docs/README.fr.md)
[](docs/README.de.md)
[](docs/README.zh.md)
[](docs/README.hi.md)
[](docs/README.pt.md)
**Agent Royo Learn** 是一款用于 AI 代理的本地机构学习引擎。
它不会取代 Gentle-AI 或 Engram：
- **Gentle-AI** 配置代理、技能、工作流程和 MCP。
- **Engram** 保留会话、决策、发现和错误的持久性记忆。
- **Agent Royo Learn** 将已验证的经验转化为可重用的行为变化：知识、技能、规则、测试和重复警报。
---
## 简单来说
如果您不是开发人员，这里是 royo-learn 的作用——没有术语。
**问题。** 在每次对话中，帮助项目的 AI 助手从零开始。一个助手今天可以出色地解决问题，但明天在新的会话中，它什么也不记得了。如果相同的问题再次出现，它可能会重复相同的错误。就像一个非常有能力的员工每天早上到来，没有前一天的任何记忆。
写笔记有帮助，但这还不够。 一条写着“这出了问题”的笔记本身并不能改变 AI 的工作方式。 为了使其有意义，教训必须达到 AI 在开始工作之前读取的指令。
**royo-learn 的作用。** 它就像一个实时的项目手册，保持更新。 每当学习到重要的东西——不重复的错误、良好的实践、项目规则——它被记录下来并转化为 AI 下次读取的具体指令。 因此，下次它已经知道该怎么做和避免什么。
一句话：**royo-learn 防止项目在同一个地方跌倒两次。**
**为什么它有价值。** 记住某件事情并不会改变你的工作方式。 只有当经验教训达到 AI 实际使用的指令时，并且在人员审查和批准后，经验教训才会防止重复错误。 这双重步骤（将记忆转化为指令，并由人员批准）使 royo-learn 与简单的记事本区别开来，并使其值得信赖：不是每个想法都变成规则，只有经过验证和批准的规则。
**它如何与其他部分配合。**
| 部分 | 是什么 | 类比 |
|---|---|---|
| **Gentle-AI** | 设置 AI 的环境：其工具、技能和工作流程 | 办公室，及其规则和团队 |
| **Engram** | 早期会话中发生的事情的记忆 | 记录事件的日志 |
| **royo-learn** | 将批准的经验教训转化为 AI 必须遵循的规则 | 良好实践手册 |
简而言之：**Engram 记住；royo-learn 将记忆转化为工作方式的变化；Gentle-AI 是所有事情发生的环境。** royo-learn 也单独工作——如果存在 Engram 或 Gentle-AI，它会使用它们，如果不存在，它仍然会完成其工作。
**如何使用它。** 您不需要输入命令或知道如何编码。您可以用日常语言与 AI 对话。它发生在三个时刻：
1. **捕获** — 当发生值得记住的事情时，您告诉 AI：
*"学习这个：…"*、 *"下次保存这个：…"* 或 *"我不希望这再次发生：…"*。在后台，AI 组织您的句子并存储它。
2. **审查** — 捕获的经验教训还不是规则。人员审查它并决定：批准、拒绝或要求更多证据。此筛选器阻止噪音。
3. **发布** — 一旦获得批准，经验教训就中的真实指令。从那时起，AI 读取并应用它——如果出现问题，可以撤销更改。
对于技术用户，可以在命令行上使用相同的三个步骤（`royo-learn capture`、`curate`、`publish`）。
---
### 它是如何工作的 — 一个真实的例子
**情况**：我们发布了 v0.1.0 并更新了英文 README。但西班牙语翻译仍然显示 `v1.0.0`，并在 PowerShell 代码块中使用 `--version`。用户运行 `install.ps1 --version v1.0.0`，安装失败。经过几次迭代，我们修复了翻译和安装脚本。
**步骤 1 — 向模型请求语：**
> *"给我一个总结刚才发生的事情的学习短语：多语言 README 版本不匹配、失败原因和解决方法。"*
模型响应一个完整、结构良好的短语：
> *"捕获此为学习内容：当项目具有多语言 README 且带有翻译徽章时，在每次发布后，所有翻译必须与规范的英文源同步。 Bug：西班牙语 README 引用 v1.0.0 并Shell 中使用 `--version`，但实际发布的是 v0.1.0，PowerShell 需要带单个破折号的 `-Version`。 修复：在每次发布 `grep` 所有 `docs/README.*.md` 以验证版本一致性，并install.ps1` 接受 `-Version` 和 `--。Bash 保留 `--version`，PowerShell 使用 `-Version`。"*
**步骤 2 — 语并触发捕获： *"捕获此学习 ← 粘语
**步骤 模型通过 ro 运行 `capture。** 学习内容保数据库中，包含上下文、观察和训。在未来的会话中检索它并应用不仅存储为内存为模型可以推理**触发短语- *"给我学习……"*
- *" esto: … *"捕获此学习内容"*
- *"我再次发生"### Engram +-Learn：知识 +两个概念之间区别：
知识**：原始事实、答案 — 。今天，像 AI 为我们提供了即“知识”，而无需。
- **：处理、推理深层次认知 当我们委派一切停止思考并失理解的能力。
这两个系统到相同的区别| | Engram |-Learn |
|---|---|---|
| **角色**持久记忆 | 学习引擎 **它做什么**发生的事情 | 处理、整合 |
|比** | 知识（笔记本） | 理解（） |
**处理**：Royo-Learn原始数据并存储它。捕获流程（[架构 §4](docs/02-ARCHITECTURE.md)）验证有效载荷、规范化和哈希它、检查幂等性、进行词典搜索（FTS5）、收集确定性证据，然后才持久化记录。
**推理**：重复数据删除系统（[RF-004](docsRD.md#004-deduplicación)）在学习之间义关系：`duplicate_of`、`extends`、`supersedes`、`contr`、`narrows`、`related`。（[RF-docs/01-P#rf-005-estado)）强制决策被拒绝的吗需要证据？是否或批准？它不是中立的存储 — 它评估知识的有效性和一致性。
**整合**内容不会停留在数据库行中。它变成技能，在另一个会话中**防止或检测重复（[PR8](docs/RD.md)）。发布[架构 §5/02-ARCH.md)）— → 预览 → 批准 → 发布 → 验证 → — 将理解转化为变化。
Royo-L为模型理解* 它是使有意义的脚。 没有它，LL在一个会话中理解这种理解会蒸发。 有了它变得持久、可验证良好且可操作。
该存储库生成单个跨文件：
```royo-learn #OS
royo-learn.exe # Windows
```
### Linux / macOS / WSL
```bash -fsSL https://github.com/RoyoTech/royo-learn/releases/latest/download/install.sh | bash
```
或手动：
```bash
./install.sh --version v0.1.0 # 安装特定版本
./install.sh --uninstall 移除
```
二进制文件安装到 `~/.local/bin/royo-learn`。
### Windows (PowerShell)
```powershell
cd ~/DownloadsRequest -Uri https://github.com/Royoroyo-learn/releases/latest/download/install.ps1 -Out1
.\install.ps1
```
或：
```powershell
.\install.ps1 -0.1.0 # 安装特定版本
.ps1 -Un # 移除
文件安装到 `%PDATA%\royo\royo-learn.exe`。
> **注意**Shell 脚本需要 **PowerShell**，而不是 Git Bash 或 WSL bash。在 WSL 上，请使用上面的 Linux 说明。
### 从源代码构建
```bash
# 要求：Go 1.24+
git clone.com/RoyoTech/royo-learn.git
yo-learn
make build # 为当前平台make build-all 跨编译所有平台 install # 安装到 $GOPATH/bin clean # 删除件
make quality # 运行 fmt、test、vet、build
```
##
```bash
# 检查版本
royo --json
# 初始化项目
royo-learn init-root /path/to/your/project
# 运行
royo-learn doctor --project-root /path/to/your/project --json
捕获学习内容
\
--path/to/y \
--title "PostgreSQL 连接池" \
--context "生产部署" \
--observation池在 100 个并发时耗尽" \
--lesson "根据可用内存设置 max_connections" \
--type "procedure" \
--scope "project" \
--json
# 管理（批准/拒绝）学习内容
royo-learn curate \
--project-root /path/to/your/project \
--learning-id "<learning-id>" \
--action "approve" \
--rationale "通过负载测试验证" \
--json
# 发布前预览
royo-learn preview \
--project-root /path/to/your/project \
--learning-id "<learning-id>" \
--json
# 发布（需要预览哈希）
royo-learn publish \
--project-root /path/to/your/project \
--learning-id "<learning-id>" \
--preview-hash "<preview-hash>" \
--json
# 回滚发布
royo-learn rollback \
--project-root /path/to/your/project \
--journal-id "<publication-id>" \
--json
# 检查重复情况
royo-learn recurrences --learning-id "<learning-id>" --json
royo-learn metrics --learning-id "<learning-id>" --json
# 运行端到端烟雾测试
royo-learn e2e --temp
```
## MCP 服务器设置
`setup` 命令将 royo-learn 注册为 MCP 服务器，并一次性安装项目技能，适用于 Claude Code、Codex CLI 和 OpenCode：
```bash
# 查看当前状态
royo-learn setup status
# 在所有三个代理中安装
royo-learn setup install --agent all
# 在特定代理中安装（仅限技能，跳过 MCP）
royo-learn setup install --agent claude-code --skip-mcp
# 尝试运行
royo-learn setup install --agent all --dry-run --json
# 卸载
royo-learn setup uninstall --agent all
```
### 手动注册
如果您更喜欢手动注册：
**Codex**：
```bash
codex mcp add royo-learn -- royo-learn mcp-serve
```
**Claude Code / OpenCode** — 添加到您的 MCP 配置文件中：
```json
{
"mcpServers": {
"royo-learn": {
"command": "royo-learn",
"args": ["mcp-serve"],
"env": {}
}
}
}
```
**OpenCode** 使用 `"mcp"` 键（不是 `"mcpServers"`），并且 `"command"` 作为数组 — 使用 `setup install --agent opencode` 进行正确格式化。
**配置文件**：`minimal`（捕获、搜索、医生），`standard`（默认；包括管理、预览、列表、获取），`full`（包括发布的所有工具）。
```bash
royo-learn mcp-serve --profile full
```
## 架构
```
LLM + 技能 → 语义提议
royo-learn → 操作保证
```
定义经验含义的三个技能：
1. `capture-learning`
2. `curate-learning`
3. `publish-learning`
### 如何捕获学习内容
当 royo-learn MCP 激活时，用自然语言告诉模型：
> **"捕获此为学习内容：每次我们发布后，在更新英文 README 后，我们需要检查 docs/README.*.md 中的所有翻译。今天，西班牙语 README 仍然是 v1.0.0，而实际发布的是 v0.1.0，PowerShell 使用带单个破折号的 -Version。用户运行 install.ps1 --version v1.0.0，安装失败。经验教训是：bash 使用 --version，PowerShell 使用 -Version。在每次发布后，运行 grep -r 'v[0-9]' docs/README.*.md 以验证所有翻译是否与正确版本匹配。"**
模型自动提取标题、上下文、观察和经验教训，并将它们保存在项目数据库中。其他触发短语包括：
- *"Aprendete esto: …"*
- *"我不希望这种情况再次发生: …"*
- *"下次保存这个：…"*
二进制文件保证：
- 持久性
- 有效状态
- 幂等性
- 可追溯性
- 词典重复数据删除
- 可选的 Engram 集成
- Git 证据和测试
- 安全发布
- 人工审批
- 回滚
- 重复检测
- 基于 stdio 的 MCP
## 它解决的问题
存储记忆并不能确保下一个代理工作得更好。 该项目添加了一个明确的循环：
```
经验
↓
结构化捕获
↓
重复和先前搜索
↓
带有证据的审查
↓
批准
↓
受控发布
↓
验证
↓
重复检测
```
## 版本 1 范围
版本 1 是本地的，没有云服务或嵌入式 LLM 提供程序。 语义推理由调用的代理执行。
该应用程序即使在没有安装-AI 或 Engram 的情况下也能工作集成是可选的且可降级的x 入门
Codex 必须按读取：
1. `AGENTS.md. `CODEXERE.md`
3. `docs/01.md`
4./02-ECTURE.md`
5. `TASKS.md从此 README。
## 开发
make fmt # 格式化代码
make test # 运行测试
make vet # 运行 vet
make build # 为当前平台构建
make build-all # 跨编译所有平台
make quality # 完整的质量检查（fmt + test + vet + build）
```
## 项目结构
```text
agent-royo-learn/
├── cmd/royo-learn/ # CLI 入口点 + 端到端
├── internal/
│ ├── buildinfo/ # 版本元数据
│ ├── capture/ # 学习捕获服务
│ ├── config/ # 项目/用户配置
│ ├── curate/ # 审查服务
│ ├── doctor/ # 健康检查
│ ├── domain/ # 领域类型和转换
│ ├── engram/ # Engram 集成
│ ├── evidence/ # 证据收集（编辑、路径安全、git）
│ ├── logging/ # 结构化日志记录
│ ├── mcpserver/ # MCP 服务器实现
│ ├── project/ # 项目解析
│ ├── publish/ # 发布引擎
│ ├── recurrence/ # 重复检测
│ ├── setup/ # 设置助手（技能、MCP 注册、备份）
│ └── storage/ # SQLite 数据库（迁移、存储库、FTS5）
├── migrations/ # SQL 迁移文件
├── schemas/ # JSON 模式
├── skills/ # 项目技能
├── docs/ # 文档
├── examples/ # 示例输入
├── AGENTS.md # 代理说明
├── TASKS.md # 实现任务
├── Makefile # 构建目标
├── .goreleaser.yml # 发布配置
├── install.sh # Linux/macOS 安装程序
├── install.ps1 # Windows 安装程序
├── go.mod
└── go.sum
```
## 许可证
MIT
