---
title: "四个记忆文件及工作区结构"
---

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


### 1、五类核心文件

| 文件 | 位置 | 职责 | 是否建议手写 |
|---|---|---|---|
| `settings.json` | `~/.soloncode/`、`.soloncode/` | Web 设置页维护的结构化配置 | 一般否 |
| `AGENTS.md` | `~/.soloncode/`、`.soloncode/` | 主代理系统提示词（或者当前项目规约） | 是 |
| `CODE.md` | `.soloncode/CODE.md` | 项目构建、测试、编码规约 | 可少量修订 |
| `TODO.md` | `.soloncode/sessions/{sessionId}/TODO.md` | 当前会话任务清单 | 通常由 AI 维护 |



### 2、配置读取与合并关系


#### `settings.json` 合并顺序

`settings.json` 会读取：

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

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


### 2、AGENTS.md — 智能体定义


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

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

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



#### 首次安装默认内容：

```markdown
# AI 管家工作规范

## 身份设定

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


## 核心规则 (Action Logic)

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

#### 自定义建议：

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

#### 示例：专业 Java 开发助手

```markdown
# Java 开发专家

## 身份设定

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

## 技术栈

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

## 工作规范

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


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

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

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

**内容示例：**

```markdown
## 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`。

**内容示例：**

```markdown
# 任务清单

## 进行中

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

## 待办

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

## 已完成

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

**状态标记：**

| 标记 | 含义 |
|------|------|
| `[ ]` | 待办 |
| `[/]` | 进行中（全局唯一） |
| `[x]` | 已完成 |

**特点：**

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


### 5、工作区目录结构

```text
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、全局目录结构

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


### 7、会话管理

每个会话独立存储：

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

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

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