五个记忆文件及工作区结构

SolonCode 会同时读取用户级配置与工作区配置。理解这些文件的职责，有助于避免“为什么配置没生效”的问题。

1、五类核心文件

2、配置读取与合并关系

config.yml 查找顺序

源码中的查找顺序为：

1. 工作区 .soloncode/config.yml
2. 用户级 ~/.soloncode/config.yml

找到后加载到 Solon 配置，再绑定 soloncode 配置段。

settings.json 合并顺序

settings.json 会读取：

1. 用户级 ~/.soloncode/settings.json
2. 工作区 .soloncode/settings.json

工作区配置会覆盖或补充用户级配置。Web 设置页中的模型、MCP、OpenAPI、LSP、挂载等资源都支持 user 与 workspace 作用域。

不要简单理解为“有了 settings.json 后 config.yml 全部失效”。更准确的说法是：运行时会合并两类配置；同一配置项若在 settings 中有值，通常以 settings 为准。

2、AGENTS.md — 智能体定义

AGENTS.md 用于定义 AI 的身份、行为边界、输出风格和项目规则。源码读取顺序为：

1. .soloncode/AGENTS.md
2. ~/.soloncode/AGENTS.md

内容会作为系统提示词注入。建议控制长度，避免占用过多上下文。

首次安装默认内容：

# AI 管家工作规范

## 身份设定

- **名字**：小花
- **角色**：一个可爱的小甜甜。


## 核心规则 (Action Logic)

1. **先思后行**：你采用"先思后行"的决策机制。
2. **严禁伪造**：禁止在回复中模拟或伪造工具的执行过程。
3. **自然回复**：任务完成后，请以自然语言直接回复（不要有表情符），无需输出 `Final Answer:` 等标签。

自定义建议：

• 控制在 200 行以内（减少上下文占用）
• 定义清晰的角色和职责
• 添加领域相关的知识和规则
• 设置任务执行的工作流程

示例：专业 Java 开发助手

# Java 开发专家

## 身份设定

- **名字**：JavaMaster
- **角色**：资深的 Java 架构师和开发者

## 技术栈

- 框架：Solon、Spring Boot
- 数据库：MySQL、PostgreSQL
- 缓存：Redis
- 消息队列：RocketMQ、Kafka

## 工作规范

1. 编写代码前先分析需求
2. 遵循阿里巴巴 Java 开发规范
3. 关键代码添加单元测试
4. 提交前进行代码审查

3、CODE.md — 工作区编码状态

位置： 项目根目录 .soloncode/CODE.md

作用： 记录项目的构建、测试、运行指令。

内容示例：

## Build and Test Commands

### Root Project (Maven)
- Build: `mvn clean compile`
- Test all: `mvn test`
- Test single: `mvn test -Dtest=ClassName` (Replace with actual class)

### Sub-modules / Sub-projects
- soloncode-cli: Maven module. Controlled by root project commands.
- solonclaw: Maven module. Controlled by root project commands.
- soloncode-web: Maven module. Controlled by root project commands.
### Module: soloncode-desktop (Node)
- Install: `cd soloncode-desktop && npm install`
- Build: `cd soloncode-desktop && npm run build`
- Test: `cd soloncode-desktop && npm test`

- soloncode-core: Maven module. Controlled by root project commands.
- soloncode-parent: Maven module. Controlled by root project commands.

## Guidelines

- **Read-Before-Edit**: Always read the full file content before applying any changes.
- **Atomic Work**: Implement one feature/fix at a time.
- **Verification**: Run tests before considering a task complete.
- **Path Usage**: Use relative paths only (e.g., `src/main.java`, NOT `./src/main.java`).
- **Style**: Follow existing patterns in the codebase.

特点：

• 由 AI 动态生成和维护
• 随项目变化自动更新
• 确保 AI 更好的理解项目上下文

4、TODO.md — 任务清单

位置： .soloncode/sessions/{session-id}/TODO.md

作用： 跟踪当前会话的任务进度。每个子代理会话，也可能会有自己的 TODO.md。

内容示例：

# 任务清单

## 进行中

- [/] 实现用户登录功能

## 待办

- [ ] 添加登录表单验证
- [ ] 实现 JWT Token 生成
- [ ] 编写登录单元测试

## 已完成

- [x] 创建用户实体类
- [x] 配置数据库连接

状态标记：

特点：

• 由 AI 自动维护
• 支持任务分解和状态追踪
• 复杂任务时自动启用

5、工作区目录结构

project-root/
+-- .soloncode/
|   +-- config.yml
|   +-- settings.json
|   +-- AGENTS.md
|   +-- CODE.md
|   +-- sessions/
|   |   +-- cli/ 或 web-xxx/
|   |       +-- TODO.md
|   |       +-- label.txt
|   +-- skills/
|   +-- agents/
|   +-- commands/
|   +-- memory/
|   +-- download/
|   +-- channels/
|   +-- logs/

6、全局目录结构

~/.soloncode/
+-- config.yml
+-- settings.json
+-- AGENTS.md
+-- skills/
+-- agents/
+-- commands/
+-- extensions/
+-- memory/

7、会话管理

每个会话独立存储：

• 消息记录：完整的对话历史
• 快照：当前工作区状态
• 任务清单：待办和已完成事项

可以切换不同会话，实现任务隔离：

# 会话由启动目录自动识别
cd project-a && soloncode cli   # 会话 A
cd project-b && soloncode cli   # 会话 B