# MindOS Instruction Set

MindOS 的元操作规则。本文件定义 Agent 与人类在知识库中协作的底层协议。

> **本文件只包含固定规则。** 所有可变内容（目录结构、用户偏好、具体 SOP）应在独立文件中维护。
>
> **措辞约定**：`MUST` = 必须遵守；`SHOULD` = 强烈建议。

---

## 1. 启动协议

Agent 进入知识库时，按以下顺序加载上下文：

1. 读取根 `INSTRUCTION.md`（本文件）
2. 读取根 `README.md`（目录索引与导航）
3. 读取 `CONFIG.json`（配置值 + 命名语义）
4. 路由到目标目录
5. 若目标目录含 `INSTRUCTION.md`，先读取局部规则
6. 再读取目标目录 `README.md` 与目标文件
7. 开始执行

步骤 1 为 **MUST**。步骤 2-6 为 **SHOULD**，但涉及写入、删除、重命名时不得跳过。

---

## 2. 文件角色与优先级

### 2.1 文件角色

| 文件 | 职责 |
|------|------|
| 根 `INSTRUCTION.md` | 全局不可变规则、优先级定义 |
| 子目录 `INSTRUCTION.md` | 该目录局部执行规则 |
| `README.md` | 目录导航与使用说明 |
| 普通内容文件 | 实际业务内容（SOP、Profile、记录等） |

### 2.2 优先级（严格）

`根 INSTRUCTION.md` > `子目录 INSTRUCTION.md` > `README.md` > `普通内容文件`

- 冲突时按上面顺序裁决。
- `README.md` 不能覆盖或改写 `INSTRUCTION.md` 规则。

### 2.3 README.md 规范

每个一级子目录（如 `👤 画像/`、`🔗 关系/`、`🔄 流程/`）应包含 `README.md`，固定包含：

1. **一句话说明**（目录职责）
2. **📁 目录结构**（文件树 + 注释）
3. **💡 使用说明**（文件/子目录用途）

> “更新规则、执行边界、优先级”属于规则层内容，写在 `INSTRUCTION.md`，不写在 README 规范里。

---

## 3. 子目录 INSTRUCTION.md 创建规范

仅当目录出现可复用的局部规则时才创建，避免滥建。

### 3.1 适合创建的场景

- 同一目录下多个文件共享一套执行约束
- 该目录有独立字段规范/安全边界
- 该目录被高频调用且误操作成本高

### 3.2 不建议创建的场景

- 仅做目录介绍（应写 README）
- 一次性说明，无法复用
- 规则频繁变化且无稳定边界

### 3.3 创建步骤（标准）

1. 在目标目录创建 `INSTRUCTION.md`
2. 只写局部规则，不重复根规则
3. 第一段显式声明：若与根规则冲突，根规则优先
4. 在该目录 `README.md` 的使用说明中增加一句：执行前先读本目录 `INSTRUCTION.md`

### 3.4 最小模板

```markdown
# <Domain> Instruction Set

## 目标
- 本目录局部目标

## 局部规则
- 规则 1
- 规则 2

## 执行顺序
1. 根 `INSTRUCTION.md`
2. 本目录 `INSTRUCTION.md`
3. 本目录 `README.md` 与目标文件

## 边界
- 与根规则冲突时，根规则优先
```

### 3.5 一级目录建议（项目根目录的子目录）

- 一级目录指项目根目录下的直接子目录，例如：`🔗 关系/`、`🔄 流程/`、`👤 画像/`、`🚀 项目/`。
- 建议这些一级目录默认提供一个轻量 `INSTRUCTION.md`。
- 轻量版至少包含：
  - 本目录目标
  - 本目录局部规则（2-5 条）
  - 执行顺序（根规则 -> 本目录规则 -> README/目标文件）
  - 冲突回退声明（根规则优先）
- 若某一级目录确实没有稳定规则，可暂不创建；但一旦出现重复操作约束，应立即补齐。

---

## 4. 文件系统规则

### 4.1 文件类型

- 文档：`.md`
- 数据：`.csv`
- 配置：`.json`

### 4.2 命名规则

- 内容文件：可用 `emoji + 名称`
- 目录名：按 `languagePreference.folderNamingLanguage` 生成；中文模板默认中文，英文模板默认英文。
- 系统文件：`README.md`、`INSTRUCTION.md`、`TODO.md`、`CHANGELOG.md`、`CONFIG.json`

### 4.3 读写前置

- 写入前 **MUST** 先读取目标文件。
- CSV 追加前 **SHOULD** 先确认表头字段。

---

## 5. 同步与变更

### 5.1 必须同步

- 新增/删除/重命名一级目录：同步更新根 `README.md`
- 删除/重命名文件：同步更新所有引用路径

### 5.2 建议同步

- 新增文件：同步更新所属目录 `README.md` 目录树
- CSV 追加行：无需同步 README

---

## 6. 安全边界

- **MUST** 不删除用户未明确指定的文件
- **MUST** 不写入密钥、Token、密码等敏感信息
- 批量删除或结构重组前应先确认

---

## 7. 记录机制

- `TODO.md`：待办入口
- `CHANGELOG.md`：完成记录（按日期倒序）

---

## 8. 示例数据隔离（命名约束）

- 所有示例文件或目录必须使用 `_example` 或 `_examples` 命名。
- 不使用 `.example` 或 `.examples`，避免与隐藏文件语义混淆。
- 名称包含 `_example` 或 `_examples` 的内容一律视为示例，不属于用户正式数据。
- 示例可用于结构与写法演示，但不得作为真实资料源参与执行决策。

---

## 9. 配置文件读取规则（CONFIG）

- `CONFIG.json` 是配置的唯一权威源。
- 字段语义内嵌于 `keySpecs`；目录命名规则内嵌于 `naming`。
