# Operator 入门

Operator Memory 将智能体的工作转化为持久的项目知识。你分配正常的开发任务，智能体在工作中记录、更新并塑造持久文档。你无需进行任何记忆管理工作。你的职责是把握智能体的结构性决策；日常记录由智能体负责。

### Operator 的工作原理

这些知识保存在大脑中 —— 一组人类可读的 Markdown 文件，分为三个分区：

- `~/.operator/user/` —— 用户/全局分区。项目无关的记忆：你的沟通偏好、工程标准和可复用的提示与技能。
- `.operator/` —— 项目私有分区。本地项目知识，例如进行中的工作、私有计划和内部研究。
- `.operator-shared/` —— 项目共享分区。随仓库一起发布、供协作者和未来克隆使用的知识。

每个分区内有四类内容协同工作：

- Operator 指令（`operator.md`）承载该范围内智能体工作方式的常驻规则 —— `AGENTS.md`，但更强大。指令冲突时，优先级为：Private > User > Shared。
- 分区目录（`catalog.md`）映射该分区的知识：每份文档覆盖什么、何时打开。
- 项目索引（`index/`）映射代码库本身，智能体无需重新摸索布局即可导航代码。目录映射大脑知识；索引映射代码。
- 自由文档是其余的一切 —— 规格、计划、研究、指南 —— 按目录指引按需读取。

每次会话开始时，Operator 加载一段简短的 preamble：Operator 引导（固定框架规则）、按优先级合并的 Operator 指令、分区目录，以及主项目索引。更深的内容保存在磁盘上，仅在任务需要时读取。

**大脑不是代码的摘要。** 大脑用于存储上下文、契约、需求、约定、决策，以及其他代码无法承载的元信息。

完整架构见[架构文档](architecture.md)（英文）。

### 开始使用

1. 在新会话中运行 `/operator:user-init`，建立全局用户工作指令。这是一次性步骤，随时可以重新运行以更新用户指令。
2. 在新会话中运行 `/operator:project-init`，初始化私有分区、配置共享规则并为仓库建立索引。项目设置在每个项目中运行一次。
3. 开启新会话，给智能体普通的开发工作。

如果大脑失去同步 —— 例如上游发生重大变化 —— 让智能体拉取并更新大脑。智能体会自动更新大脑和索引。

### 日常使用

给智能体正常的开发工作：功能、修复、重构。Operator 自动为每个会话定位方向；智能体查阅大脑材料、记录持久知识，并在文档所承载的事实发生变化时更新现有文档。

如果在现有项目上使用，一开始大脑会比较空缺。由于惯性，智能体可能对编写第一批文档犹豫不决；你应该直接要求它为你正在开发的模块或系统编写第一批规格或研究。文档建立后，后续会话会更自然地将其维护和扩展为日常工作的一部分。

---

#### 示例：

你在一个现有项目上初始化 Operator，并开始开发一个你非常熟悉的模块。大脑中还没有关于它的文档。

让智能体分析该模块：它的结构如何、如何融入项目其余部分、实际做什么。提供在线文档链接作为背景信息。鼓励提问、做出澄清，并让智能体汇报一份简要总结。

评估智能体的理解程度。向智能体提供它无法推断的元信息：该模块为何存在、解决什么问题、需求和约束等。之后，让智能体编写一份规格或其他上下文文档。

未来的智能体在接触该模块之前会先打开这份文档，立即获得对该模块用途的完整认识，以及代码或注释无法提供的深层动机。

---

### 引导智能体

智能体会读取并更新已有文档。然而，当前的智能体倾向于维持现状，有时可能会犹豫：

- 创建新类型的文档
- 将两份相关文档合并为一份
- 将一份过大的文档拆分为两份

某些更大的架构性调整需要你对项目长期需求做出判断。这些情况下，你必须引导智能体：

- "为这次变更起草一份计划，并记录到大脑中。"
- "把这次研究记录为可复用的指南，避免重复调查。"
- "克隆这个源码树并创建一个子索引，供未来参考。"
- "这两份文档有重叠。合并它们。"
- "这份文档太大了。拆分它。"
- "把这份规格提升到共享分区，让团队也能收到。"

---

#### 示例：

你经常使用某个第三方库，而你的智能体对它并不熟悉。智能体经常花大量时间在网上搜索资料。

有了 Operator，这会改变。

将该库的源码树克隆到 .gitignore 的 `references/` 目录。让智能体为该源码树创建子索引。让智能体为你常用的 API 或系统创建可复用的 Operator 指南。

未来的会话将直接使用指南，而不是搜索网络。遇到不确定之处，智能体通过子索引深入源码，以源码为准。

---

### 大脑

大脑是磁盘上的普通 Markdown。它透明、灵活、高度可扩展。举几个你能用大脑做的事：

- 让智能体在 `~/.operator/user/writing-style.md` 中创建一份符合你个人风格的写作指南。
- 让智能体把 PR 审查工作流捕获为用户分区 `~/.operator/user/` 中的可复用全局技能。
- 让智能体在私有分区中维护某个竞品架构的档案，每次你让它 `git pull` 参考代码时更新。
- 让智能体创建实现新功能的检查清单，确保它再也不会忘记更新 `changelog.md`。
- 让智能体通过在 `.operator-shared/operator.md` 中添加共享约定，来强制执行某个实习生总是违反的全仓库标准。

随心所欲地定制你的大脑和智能体的行为。有了 Operator，世界是你的。

### 附录：命令

提示：在新的会话中逐个运行 Operator 命令，让智能体以干净的工作上下文专注于设置或修复。

- `/operator:user-init` —— 在当前会话中初始化或修订私有的用户全局记忆（指令和自由文档）。
- `/operator:project-init` —— 初始化或修订项目设置，不覆盖已有内容。它配置私有分区、引导可选的共享激活，并为仓库建立索引。
- `/operator:index` —— 构建或刷新项目索引，让未来的智能体能够导航仓库结构和适用的子系统上下文。
- `/operator:repair` —— 在当前会话中诊断并修复缺失、格式错误或无法加载的 Operator 上下文。见[故障排除](troubleshooting.md)（英文）。