codesstar · Oct 8, 2026 · Oct 8, 2026
diff --git a/README.en.md b/README.en.md
@@ -95,6 +95,7 @@ Loci is an MIT-licensed open-source project. Models and third-party services may
 
 - [English getting started guide](docs/getting-started.md) · [中文指南](docs/getting-started.zh-CN.md)
 - [AI installation](docs/AI-INSTALL.md)
+- [Connect a new agent to an existing brain (中文)](docs/connect-existing-brain.md) · [Entry, startup map, and rules explained (中文)](docs/context-explained.md)
 - [Dashboard](docs/dashboard.md) · [API](docs/api.md)
 - [Example brain](examples/alex/)
 - [Contributing](CONTRIBUTING.md) · [MIT License](LICENSE)

diff --git a/README.md b/README.md
@@ -93,6 +93,7 @@ node loci/scripts/loci-install.js --connect auto --lang zh
 
 - [中文入门指南](docs/getting-started.zh-CN.md) · [English guide](docs/getting-started.md)
 - [AI 安装说明](docs/AI-INSTALL.md)
+- [已有大脑，接入新 Agent](docs/connect-existing-brain.md) · [短入口、启动地图与完整规则逐项拆解](docs/context-explained.md)
 - [Dashboard](docs/dashboard.md) · [API](docs/api.md)
 - [示例大脑](examples/alex/)
 - [参与贡献](CONTRIBUTING.md) · [MIT License](LICENSE)

diff --git a/docs/AI-INSTALL.md b/docs/AI-INSTALL.md
@@ -5,7 +5,7 @@
 ## 1. 检查环境与已有安装
 
 - 需要 Node.js 18+、Git，以及能读写本地文件和执行命令的 Agent。用 `node --version`、`git --version` 检查。缺少运行环境时说明具体缺项，按用户授权安装依赖；不能声称纯网页聊天也能访问用户磁盘。
-- 读取用户主目录下 `.loci/brain-path`（如果存在），检查指向的大脑。已有可用大脑时走**升级**，不要再建第二份、不要覆盖个人数据。
+- 读取用户主目录下 `.loci/brain-path`（如果存在），检查指向的大脑。先区分用户要**新装、仅连接新 Agent、还是升级**：已有可用大脑且只新增 Agent 时走第3节，不默认下载、升级或重建；用户要升级或旧版本缺少必要文件时，再按第4节处理。路径冲突或多个大脑时先辨认，不静默切换。
 - 主目录、临时目录和目标路径由当前系统确定；所有示例占位符都须替换。不要假设 Windows 有 Bash，不要把含空格或特殊字符的路径/用户文本拼进未经转义的 Shell 命令。优先用参数数组调用进程。
 - 默认新大脑目录为用户主目录下 `loci`。目标非空且不是刚下载的 Loci 时停止覆盖，选择空目录或明确已有安装的用途。可直接使用已知称呼和语言，不必进行个人信息问卷。
 
@@ -26,12 +26,24 @@ node <brain-path>/scripts/loci-install.js --brain <brain-path> --connect auto --
 
 ## 3. 接入不同 Agent
 
+**大脑装一份，Agent 分别接入。** 已经连接 Claude Code/Codex，后来新装千问、豆包等，按 [已有大脑接入指南](connect-existing-brain.md) 操作；其中有给原 Agent、给新 Agent 的可复制指令，以及新会话验收方法。
+
+对当前版本已有大脑，只刷新一个现成适配入口，例如新增 WorkBuddy：
+
+```text
+node "<existing-brain-path>/scripts/loci-install.js" --brain "<existing-brain-path>" --connect workbuddy --refresh
+node "<existing-brain-path>/scripts/loci-install.js" --brain "<existing-brain-path>" --connect workbuddy --check
+```
+
+`--refresh` 跳过初始资料/空数据池准备，但会刷新托管入口和配置；检查返回的备份与警告。它不下载新版本。发现旧版缺文件时说明需要升级，不强行覆盖。自动适配器只接受下表前三个名称，不支持 `--connect qwen` 或 `--connect doubao`。
+
 | 客户端 | 本版本接入入口 | 验证要求 |
 | --- | --- | --- |
 | Claude Code | `~/.claude/CLAUDE.md`，可选 SessionStart Hook | 新会话验证偏好、手册读取、写入工具权限 |
 | Codex | `~/.codex/AGENTS.md`，安装器提供 Hook 配置 | Hook 是否执行取决于客户端版本与功能支持；无 Hook 时用同一入口的读取后备路径 |
 | WorkBuddy | `~/.workbuddy/MEMORY.md` | 验证当前版本实际加载该入口；不承诺原生 Hook |
-| 千问办公、豆包工作及其他客户端 | 先核实该版本的自定义指令、项目规则或技能入口 | 不猜配置文件路径、不写入任意位置；必须具备本地文件和命令能力 |
+| 千问办公国内桌面版 | 官方文档提供“意识 → 工作手册（AGENTS.md）”；从应用确认实际位置后手动合并 | [具体步骤和依据](connect-existing-brain.md#千问办公国内桌面版通过已核实的工作手册入口)；不属于当前自动适配器，仍需本地访问和新会话实测 |
+| 豆包工作及其他客户端 | 先核实该版本的自定义指令、项目规则或技能入口 | 不猜配置文件路径、不写入任意位置；必须具备本地文件和命令能力；只有会话粘贴时明确属于临时接入 |
 
 其他客户端：把 `<brain-path>/LOCI.md` 中 `<brain-path>` 替换为实际绝对路径，将该短入口放进**已核实会加载的指令位置**；保留详细手册在大脑内。若只能手动粘贴指令，给用户生成完整、可复制的一段。若客户端不能访问本地文件/运行 Node，说明当前未接通，不声称适配完成。
 

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -24,6 +24,8 @@ Loci 的核心是让不同 Agent 通过自己的原生指令入口，使用同
 
 `CLAUDE.md`、`AGENTS.md`、WorkBuddy 的 `MEMORY.md` 是安装结果所在的入口；不各写一套业务规则。修改产品规则时，主要维护前两个文件；需要改变执行行为才修改相应脚本。
 
+想看它们究竟写了什么，可读 [短入口、启动地图与完整规则逐项拆解](context-explained.md)：包括 `LOCI.md` 原文、用虚构偏好实际生成的地图示例，以及完整规则的11个分块。启动地图是读取器的输出，不是第三份需要维护的规则文件。
+
 ## 一次对话怎样运行
 
 1. **会话启动**：客户端加载短入口。有有效 Hook 输出则使用它；没有则让 Agent 执行同一个 `loci-context.js`。启动输出只有时间、路径、短偏好和手册指针，不再携带任务路由表、状态摘要或项目正文。

diff --git a/docs/connect-existing-brain.md b/docs/connect-existing-brain.md
@@ -0,0 +1,116 @@
+# 已有 Loci，怎样接入一个新 Agent
+
+[中文首页](../README.md) · [AI 安装指南](AI-INSTALL.md) · [架构说明](architecture.md)
+
+**大脑只需要一份，每个 Agent 分别连接它。** 如果 Claude Code 和 Codex 已经在用同一个大脑，新装千问办公或其他工具时，通常只需接入现有目录。新 Agent 的应用本身仍从其官方渠道安装；这和下载 Loci 是两件事。
+
+## 先判断是哪一种情况
+
+| 当前情况 | 应做的事 |
+| --- | --- |
+| 这台电脑还没有 Loci | 按 [AI 安装指南](AI-INSTALL.md) 下载并初始化一次 |
+| 已有大脑，只新增一个 Agent | 找到现有大脑，将相同短入口接到新 Agent，再做新会话验收 |
+| 已有大脑，想用新版 Loci | 按升级流程下载新程序、备份、迁移；保持原数据目录 |
+| 换了一台电脑 | 先迁移或恢复大脑，确认数据完整，再用新电脑上的实际路径接入；本机路径不能直接让另一台电脑共享数据 |
+
+新 Agent 不会自动继承 Claude Code 的 `CLAUDE.md` 或 Codex 的 `AGENTS.md`。Loci 也不会仅因一个新应用被安装，就自动修改它的配置。
+
+## 第一步：让已经接好的 Claude Code / Codex 找到大脑
+
+把下面的话发给已经能用 Loci 的 Agent：
+
+```text
+我已经在这台电脑上使用 Loci，现在准备连接一个新 Agent。
+请读取用户主目录 .loci/brain-path，结合当前 Loci 入口，
+确认实际大脑的绝对路径，以及 LOCI.md、LOCI-RULES.md 和 scripts 是否存在。
+只检查，不重新下载、不升级、不创建第二份大脑。
+如果登记路径失效，或发现多个大脑，请列出候选让我辨认，不要静默切换。
+最后给我一段可发给新 Agent 的连接说明，填好实际路径，
+并附上已替换 <brain-path> 的完整 LOCI.md 短入口。
+```
+
+如果旧大脑还没有 `LOCI.md` / `LOCI-RULES.md`，先说明版本差异；需要迁移时再按升级流程处理，不能把当前模板硬塞进不兼容的旧目录。
+
+## 第二步：选择连接方式
+
+### Claude Code、Codex、WorkBuddy：使用已有适配器
+
+已有大脑为当前版本时，可只刷新入口。下面以新增 WorkBuddy 为例，执行前替换路径：
+
+```text
+node "<已有大脑绝对路径>/scripts/loci-install.js" --brain "<已有大脑绝对路径>" --connect workbuddy --refresh
+node "<已有大脑绝对路径>/scripts/loci-install.js" --brain "<已有大脑绝对路径>" --connect workbuddy --check
+```
+
+`--refresh` 跳过初始个人资料和空数据池的准备，刷新规则入口、登记和所选客户端的可用 Hook；仍可能更新托管配置，并返回备份和警告，应检查结果。指定单个客户端，不需要把已经连接的其他客户端全部重装。
+
+现成名称只有 `claude`、`codex`、`workbuddy`。`--connect auto` 也只检测这三个目标；不能编造 `--connect qwen` 或 `--connect doubao`。
+
+### 千问办公国内桌面版：通过已核实的工作手册入口
+
+截至2026年10月8日，官方文档列出了“意识”页面中的“工作手册（`AGENTS.md`）”，并列明意识目录为 `~/.qwenworkcn/awareness/main`。按该文档定位，候选文件是该目录下的 `AGENTS.md`；仍应以当前应用“打开所在文件夹”展示的位置为准，其他地区版或版本可能不同。[官方说明](https://docs.qwenwork.cn/desktop/memory)
+
+1. 打开千问办公的“意识”页面，确认当前版本提供工作手册，并检查相关功能是否启用。
+2. 打开工作手册并备份原内容，将第一步得到的 **Loci 短入口** 合并进去。保留原有规则；已有 Loci 标记区就替换该区，不重复追加。
+3. 确认千问的实际任务环境能访问大脑目录并执行 Node。若处于隔离环境，按产品提供的目录授权方式开放这一目录；把路径写进规则并不等于获得访问权限。
+4. 开新任务，执行下文的只读验收。
+
+这是依据官方入口的**手动接入路径**，不是 Loci 安装器已经内置的千问适配器，也不代表已在该客户端完成读写实测。此路径使用无 Hook 后备调用即可，不假设千问的 Hook 与 Claude Code 的配置通用。
+
+千问自身的用户画像、长期记忆与 Loci 数据是不同存储；放入短入口不会自动合并、搬迁或关闭原生记忆。使用时明确需要保存到 Loci，验收也检查 Loci 文件结果。
+
+### 豆包工作及其他客户端：先确认具体版本的能力
+
+本次查阅的 [豆包官方桌面页](https://www.doubao.com/download/desktop) 没有提供足以确认 Loci 所需指令入口和 Node 执行能力的说明。这不等于所有版本都不支持，但不能据此编造配置路径，或把 Trae 等其他产品的规则目录当成豆包的目录。
+
+请先确认两件事：**能否实际读写本机大脑并执行工具；是否有在新会话中加载的自定义指令或工作区规则。** 能确认时，将相同短入口放入该位置。若只有项目规则，连接只在相应工作区有效；若只有当前聊天可粘贴，属于临时接入；若只有云端聊天或上传附件，不能宣称已经连上本机大脑。
+
+## 给新 Agent 的通用连接指令
+
+将 `<已有大脑绝对路径>` 换成第一步查到的真实路径，然后发给新装的客户端：
+
+```text
+我这台电脑已经有 Loci 大脑：<已有大脑绝对路径>。
+Claude Code / Codex 正在使用它，现在请把你也连接到同一份大脑。
+
+这次只连接：不要重新下载或初始化大脑，不要自动升级，不要复制全部记忆。
+先实际检查能否读取该目录下的 LOCI.md、LOCI-RULES.md，
+以及能否通过当前工具执行 Node；不能访问就说明具体缺项。
+
+核实你这个客户端、这个版本实际加载的原生指令入口。
+把 LOCI.md 里的 <brain-path> 替换为上述绝对路径，
+合并到已核实的入口，保留原有内容，备份修改，替换已有 Loci 标记区以免重复。
+详细手册和个人数据留在大脑中，不全文复制进你的原生记忆文件。
+如果只能通过设置界面手动粘贴，请输出可复制的完整短入口和准确操作位置。
+如果只能当前会话临时使用，明确说明，不报告为永久接入成功。
+
+没有可用 Hook 就按短入口调用同一 loci-context.js，不新建第二份启动地图。
+最后告诉我实际使用的指令入口、生效范围、文件与命令检查结果，
+并给出下一次新会话的只读验收步骤。不要新增测试任务或改我的偏好。
+```
+
+新客户端无法配置自己时，也可以让原来的 Claude Code / Codex 在核实入口后准备配置。但**原 Agent 能修改文件，不代表新 Agent 一定能读取或执行它**；验收必须在新 Agent 里做。
+
+## 第三步：在新会话中验证，区分配置和生效
+
+持久入口应在新会话自动生效，所以第一次验收不要重新贴入完整入口，也不要附上正确大脑路径让它照抄。可发：
+
+```text
+请检查你是否已经接入 Loci：
+1. 根据当前实际收到的指令，告诉我连接的大脑路径。
+2. 若未收到入口或无法访问，直接说明，不猜测路径。
+3. 已接入则按入口获取短偏好，完整读取操作手册，列出已有待办。
+只读验证，不新增、修改、删除或记录这次测试。
+```
+
+将它实际读取的目录与旧 Agent 的目录对照；待办和已有偏好应来自同一份数据。文件检查通过、模型说“已连接”，都不能单独证明实际加载成功。
+
+只读通过只证明读取链路。首次真实保存后，再在原 Agent 或 Dashboard 核对同一条记录；没有实际写入结果时，不宣称写入也已验证。提醒还需另查调度与设备送达。
+
+| 遇到的现象 | 下一步 |
+| --- | --- |
+| 每次换对话都忘记 Loci | 核对指令是否只在旧会话或某个工作区生效 |
+| 知道路径，但文件打不开 | 核对本机/云端环境、路径和目录权限 |
+| 文件能读，但 Node 不能执行 | 说明缺少命令能力或运行环境；不能声称完整工具链可用 |
+| 找到的大脑内容与旧 Agent 不同 | 比对实际绝对路径，避免误连另一份目录 |
+| 只在新 Agent 原生记忆里出现记录 | 确认是否调用了 Loci 的操作路径，不把原生记忆当作 Loci 数据 |