高一暑假，我试图用不一样的方式让 agent 更懂项目

Yanxi（盐析）— — agent-first 微模块化开发工具

说在最前面的话

我现在是一个高一生，目前没有正经的软件开发经验，这个项目是暑假vibecoding的一个小尝试。
由于时间和水平有限，做为一个用于软件开发的工具，这个项目目前没经历太多实战，里面有不少粗糙的地方，希望大家见谅。
如果你愿意浪费一点时间，看看我这个基于有些天真的想法的项目，我将不胜感激。

由于能力问题这个项目目前已经的实现效果可能与下列介绍有些偏差（正是下面这个问题的锅）

想法来源：Context Cliff（上下文悬崖）及 跨对话项目连续性 之痛

作为一个完全的门外汉，使用vibecoding的过程中，一旦没做好上下文管理和文档记录，往往会出现这样一种状况：agent忘记了项目的意图，开始瞎猜，甚至开始删除以前处理好的代码，把本来没有问题的功能摧毁。

这时，我看到了目前一些工具利用向量检索等方法，只把相关代码而不是全部源码输入给LLM模型，我想到，我们能不能再进一步，在写的过程中就把相关代码放在一起，即采用微模块架构。但是毕竟不能为拆而拆，拆下来本身不会对agent有帮助，那么 如果说 我给每一个模块都添加一个概括性文件呢？下一次他就只要读概括性文件就能理解模块？最后再像skill机制一样，懒加载？
再进一步？如果每写完一个模块就强制校验保证其可运行，下次非必要就不动之前的模块？

这就是Yanxi（盐析）

所以我写了 yanxi。一个 MCP 服务器，体积极小（6MB 单文件，零外部依赖），提供 18 个工具。

核心思路是这样的：

读取

当agent在新对话中进入一个项目后，他会被要求调用yanxi，从而相关返回信息。
调用和返回的信息分为三层：

第一层（约200 tokens）: 
  module_discover() 
  返回：项目是干什么的、用什么语言、有多少模块、依赖关系、有哪些警告

第二层（300 tokens）:
  模块摘要列表 → AI 决定要动哪个模块

第三层（按需加载，每个 ~300 tokens）:
  module_read("auth") → agent选择了解的这个模块的完整知识卡片
  AI 不读源码，读的是 yanxi 自动生成+llm概括的结构化卡片

为存放这些知识卡片，我们在项目根目录建了一个文件夹- aiexplain --与源文件一一对应，专门存放知识卡片

每一层的信息密度都远大于源码片段。AI 读完三层能理解项目，不用碰源码。

但是对于一些特殊情况，我们也允许使用BM25或向量搜索（没适配好）

微模块 与 模块生命周期机制

微模块我们定义为一个可以完整承担一项任务的模块，能够独立完成调试。
其创建及连接都有相应工具以确保正确性，其契约由yanxi+LLM基本自动维护。
编写完成后module_validate会自动多方面验证。
我们还设置了模块生命周期，致力于提升模块可用性。

新项目

Yanxi自动搭建骨架

非结构文件适配

为保证Yanxi兼容性，用llm理解加yanxi进行外部框架快速搭建

多语言适配性

虽然yanxi帮agent干了不少机械活（防止agent出错），但是这也就意味着yanxi要面对对不同语言，提供不同的执行模式。
目前代码里面只编码了4种语言模板，更多的语言会通过LLM生成加入模板。

18 个工具是干什么的

刚刚已经说过了一部分，这边我把它们按场景列出来：

进项目

• module_discover — 项目全景地图。AI 进项目第一个要调的工具
• module_report — 项目健康报告。看看哪些模块风险高、哪些可能是死模块

建模块

• module_create — 自动生成模块骨架（module.json + 代码模板）
• module_bootstrap — 一键创建 + 注册 + 同步
• module_adopt — 把外部代码吸收进 yanxi 的架构

验证

• module_validate — 核心功能。6 个阶段自动检查：
  1. 结构对不对（module.json 完整吗）
  2. 源码对不对（handler 函数存在吗）
  3. 跨模块契约对不对（调的目标存在吗、上游废弃了吗）
  4. 深度分析（import 分不分类、有没有 side effect）
  5. 运行时测试（自动生成测试、跑子进程）
  6. 接口变更检测（schema 变了没有、影响了下游吗）
• module_check_imports — 检查声明的依赖和实际 import 是否一致
• module_sync — 检测到变更后，AI 确认要不要更新合约

接线

• module_wire — 自动生成路由代码 + HTTP 服务。go run main.go -http 8080 就能启动

文档

• aiexplain_generate — 自动生成 AI 可读的模块知识卡片
• memory_init / memory_write — 项目记忆系统。AI 踩的坑写下来，下次不重复踩

弃用

• module_deprecate — 标记模块废弃，自动写 ADR，通知依赖方

搜索

• module_search / module_search_loose — 全文搜索

当前状态

项目可用性还在评估，目前我自己有用 yanxi 开发一个 yanxi桌面应用（yanxi-desktop）

还有很多不足：

0. 本身为纯vibecoding产物，项目极为早期，且可靠性未完整评估

1. 业务逻辑验证要靠 AI 写测试用例。yanxi 提供框架（test_cases.json），但测试内容得 AI 自己写。auto-sync 的 entry 描述是占位符，需要 AI 主动填。

2. 模块通信模型偏向函数路由。yanxi 默认假设模块之间调 handler(input: dict) → dict。但很多 Go 项目用接口注入 + pubsub，这个模式支持得不够好。provides/uses 声明系统已经加了，但展示层和生成层还要适配。

3. 小项目用起来不值。3 个模块以下，直接写代码比配 yanxi 快。它是在项目长到十几个模块的时候才真正回本。

4. 文档和上手体验还很粗糙。没有 tutorial，没有 GUI，全靠 MCP 工具调用。

5. 对严肃的软件开发工作流适配性存疑

接下来

暑假时间实在有限，这个项目我可能会先放一放，但不是放弃。

如果有人愿意试用、提 issue、或者告诉我哪里做得不对，我会认真对待并万分感激。

GitHub: https://github.com/The-Milky-Way-traveller/yanxi-single