内容
# 盐析（Yanxi）— 面向 Agent 的微模块架构
<p align="center">
<b>一个 6 MB、无依赖的 MCP 服务器，为 AI 代理构建结构化的代码库。</b>
</p>
<p align="center">
<img src="https://img.shields.io/badge/go-1.21%2B-blue" alt="Go 版本">
<img src="https://img.shields.io/badge/license-MIT-green" alt="许可证">
<img src="https://img.shields.io/badge/build-passing-brightgreen" alt="构建状态">
<img src="https://img.shields.io/badge/dependencies-zero-success" alt="零依赖">
</p>
---
## 概述
Yanxi 是一个 MCP 服务器，帮助 AI 代理导航和维护结构化的代码库。它可以与任何支持 MCP 的客户端（Claude Desktop、Cursor、VS Code 或自定义客户端）连接，为代理提供项目的结构化视图，而不是原始源代码。
> **MCP（模型上下文协议）** 是一个开放标准，允许 AI 工具与外部服务器通信。可以将其视为 AI 的 USB-C 接口：一个协议，多种工具。Yanxi 就是其中一种工具。
## 为什么使用 Yanxi
当 AI 代理进入一个项目时，它会读取源文件直到理解项目结构。对于包含 5 个以上模块的项目，这意味着需要阅读数千行代码。而对于包含 50 个模块的项目，上下文窗口将完全溢出，代理将根据不完整的项目视图做出决策。这就是 **上下文悬崖**。
Yanxi 的解决方案是 **信息密度优于信息量**。
Yanxi 执行三个主要功能：
1. **提供项目地图** — 代理进入项目，读取约 500 个令牌，了解整个项目概览。
2. **捕获错误** — 代理编写代码，立即获得跨 6 个验证阶段的反馈。
3. **记录经验** — 代理犯错，Yanxi 将其写入 `lessons-learned.md`。下一个代理不会重复相同的错误。
```
代理的任务： 决策、设计、实现
Yanxi 的任务： 结构、验证、连接、文档、记忆
```
## Yanxi 工作原理
### 三层信息架构
```
级别 1 — 项目概览（约 200 个令牌）
module_discover()
→ 项目摘要、模块数量、构建顺序
→ 警告：已弃用的模块、循环依赖、未验证的模块
→ 从以前的代理会话中学习到的经验教训
级别 2 — 模块摘要（约 300 个令牌）
→ 每个模块：名称、版本、状态、语言、入口数量、依赖模块
→ 代理决定进一步检查哪个模块
级别 3 — 模块详情（每个模块约 300 个令牌，按需）
module_read("auth")
→ AI 解释知识卡（自动生成）
→ 带有类型化模式的 interface.md
→ 源代码预览（前 2000 个字符）
```
### AI 解释知识层
每个模块都生成自动文档，代理可以阅读这些文档而不是源代码：
```
# config 模块
**状态**：进行中 | **版本**：0.1.0 | **语言**：go
## 目的
包配置管理来自各种来源的应用程序配置。
**依赖模块**：agent、api、mcpclient、permission、tools
## 接口
func Get() *Config {
### 条目
- **Get**：Get 返回全局配置实例。
- **Load**：Load 从环境变量初始化配置...
- **Save**：Save 将当前配置持久化到磁盘。
- **Validate**：Validate 验证配置
## 使用示例
config.UpdateAgentModel(input)
## 依赖模块
agent、api、mcpclient、permission、tools
```
描述从函数文档字符串中提取。依赖关系根据依赖关系图计算。设计意图必须由代理编写 — 如果描述过于通用，Yanxi 会发出警告。
### Yanxi 的不同之处
**微模块合约。** 每个模块都携带一个机器可读的 `module.json`，与源代码一起。该合约描述了类型化的入口模式、跨模块调用声明、接口提供/使用、中间件引用和错误代码 — Yanxi 可以验证、差异和推理的结构化数据。
**基于推送的合约验证。** `module_validate("auth")` 自动遍历 6 个阶段的管道，并报告发现的每个问题：
- 调用引用指向不存在的模块或入口
- 不存在的中间件函数
- 已弃用的上游模块
- 下游模块的调用不再与更改的模式匹配
- 破坏后向兼容性的模式更改
这两个形成一个闭环：合约使验证成为可能，而验证保护合约。
## 快速入门
```powershell
# 1. 构建
cd cmd\yanxi-mcp
go build -o yanxi-mcp.exe .
# → 6 MB 单个二进制文件，无依赖
# 2. 配置你的 MCP 客户端
# 添加到你的 .mcp.json：
{
"mcpServers": {
"yanxi-single": {
"command": "path\\to\\yanxi-mcp.exe",
"args": []
}
}
}
# 3. 开始使用（你的 AI 代理将调用这些）
module_discover() → 了解项目
memory_init() → 设置项目内存
module_create("my-module", "go") → 添加模块
module_validate("my-module") → 检查所有内容
module_wire() → 生成路由 + HTTP 服务器
```
## 18 种工具
### 项目入口
| 工具 | 功能 |
|------|-------------|
| `module_discover` | 级别 1 + 级别 2。项目摘要、模块摘要、警告、经验教训。代理的第一个调用。 |
| `module_report` | 项目健康仪表盘：热力图、风险评分、死模块检测。 |
### 模块生命周期
| 工具 | 功能 |
|------|-------------|
| `module_create` | 生成模块骨架（module.json + 处理程序存根）。支持 Go/Python/TS/JS + LLM 启动的语言。 |
| `module_read` | 级别 3 详情：AI 解释卡 + 接口 + 源代码预览。 |
| `module_validate` | 6 阶段验证管道。Yanxi 的核心。 |
| `module_wire` | 生成主入口路由 + HTTP 服务器（`main -http 8080`）。 |
| `module_sync` | 应用待处理更改：同步入口、调用、版本从源代码。Yanxi 检测 → 警告 → 代理确认。 |
| `module_bootstrap` | 一次性：创建 + 连接 + 同步。在失败时回滚。 |
| `module_adopt` | 分析外部目录以进行采用。返回 LLM 转换提示。 |
| `module_adopt_commit` | 完成采用：写入模块、删除原始文件、连接、同步。 |
| `module_deprecate` | 将模块标记为已弃用/存档。自动写入 ADR，警告依赖模块。 |
### 知识与记忆
| 工具 | 功能 |
|------|-------------|
| `aiexplain_generate` | 增量重新生成 AI 解释卡 + 重建搜索索引。 |
| `memory_init` | 创建项目内存 + 约定 + 测试模板。幂等。 |
| `memory_write` | 追加到 ADR/经验教训/约定。自动去重。支持全局范围。 |
### 搜索与分析
| 工具 | 功能 |
|------|-------------|
| `module_search` | 跨 AI 解释 + 源代码的 BM25/向量搜索。 |
| `module_search_loose` | 在没有微架构的情况下搜索任何目录。 |
| `module_check_imports` | 比较声明的依赖关系与实际导入。 |
### 语言扩展
| 工具 | 功能 |
|------|-------------|
| `save_lang_template` | 保存 LLM 生成的语言模板。保存后，`module_create` 支持具有完全验证覆盖的新语言。 |
## 验证管道（6 个阶段）
| 阶段 | 检查 | 失败模式 |
|-------|--------|-----------|
| 1 — 结构 | module.json 有效，必需字段存在，文件存在 | 硬性失败 |
| 2 — 源代码 | 入口函数存在，生命周期钩子存在，导入一致 | 硬性失败 |
| 3 — 跨模块 | 调用目标存在，中间件存在，无已弃用依赖，下游兼容，提供/使用匹配，粒度 | 警告/失败 |
| 4 — 深度分析 | 导入分类，副作用，流式传输，约定 | 警告 |
| 5 — 运行时 | 自定义测试（test_cases.json），自动生成的测试，延迟，严格模式 | 警告/失败 |
| 6 — 变更检测 | 模式差异，版本建议，下游通知 | 警告 |
## 模块合约
```
source/modules/auth/
├── auth.py ← 处理程序/接口实现
└── module.json ← 机器可读合约
```
```json
{
"name": "auth",
"version": "1.0.0",
"status": "active",
"language": "go",
"dependencies": ["storage", "session"],
"interface": {
"entries": {
"login": {
"description": "验证用户，返回 JWT",
"input_schema": { "type": "object", "required": ["username", "password"], ... },
"output_schema": { "type": "object", "properties": { "token": {"type": "string"}, ... } }
}
},
"provides": { "AuthService": { "methods": ["Login", "Logout", "VerifyToken"] } },
"uses": { "storage.StorageService": { "methods": ["Save", "Load"] } },
"calls": { "storage": {"save_session": {}} }
}
}
```
## Yanxi 与代理边界
| 代理拥有 | Yanxi 自动执行 |
|-----------|----------------|
| 分析需求 | 模块.json 骨架（module_create） |
| 设计模块分解 | 路由 + HTTP 服务器（module_wire） |
| 编写处理程序代码 | 6 阶段验证（module_validate） |
| 编写测试用例 | 模式差异 + 版本建议 |
| 描述设计意图 | 知识卡生成（aiexplain_generate） |
| 做出架构决策 | 项目内存 + 经验教训跟踪 |
**规则**：机械的、重复的、容易遗忘的 → Yanxi。决策、设计、业务逻辑 → 代理。
## 当前状态
Yanxi **早期但可用**。我正在使用它开发一个 14 模块的桌面应用程序 — 验证管道每天都会捕获真正的错误。
**有效的内容：**
- 三层项目发现（50 个模块 → 约 800 个令牌）
- 跨模块合约验证（调用、中间件、提供/使用、弃用）
- 从源代码到合约的自动同步（入口、调用）
- 具有自动去重的项目内存
**粗糙的部分：**
- 业务逻辑验证依赖于代理编写的测试用例
- 接口注入模式（Go 结构体 + 发布/订阅）需要更多显示工作
- 文档和上线准备工作很少
- GUI 和教程尚不存在
## Yanxi 不做的事情
- **业务逻辑验证** — 验证结构，而不是正确性。代理编写 test_cases.json。
- **代码生成 beyond stubs** — 生成 module.json + 路由。代理编写业务逻辑。
- **沙箱或进程隔离** — 仅限单机开发。
- **Dockerfile 或 CI 生成** — 部署因项目而异。
## 贡献
这是一个人夏季的项目。欢迎提出问题、错误报告和功能想法。
如果您尝试使用它时遇到问题，请打开一个问题 — 我会阅读它。
## 许可证
MIT
