Merge pull request #45 from zixuangui-rgb/main

Update build chapter1-6 index.md from revised version

Author: zixuangui-rgb

docs/cn/build/chapter1/index.md

@@ -20,7 +20,7 @@
 
 它**知道怎么做**，但它**不能替你做**。
 
-这就是对话式AI的本质局限——一个博学的"空想家"。它掌握了人类知识的精华，却没有一双手。具体表现在于：无行动力、无状态、无记忆、无主动性。
+这就是对话式AI的本质局限——一个博学的"空想家"。它掌握了人类知识的精华，却没有一双手。具体表小在于：无行动力、无状态、无记忆、无主动性。
 
 这四个"无"，构成了对话时代的天花板。AI是一个百科全书，但不是一个助手。
 
@@ -105,7 +105,7 @@ OpenClaw的使用门槛：
 
 有人把OpenClaw比作一个"数字生命体"——这不是夸张。一个能够自主行动的Agent，确实需要像生命体一样具备完整的功能系统：
 
-- **ReAct循环** —— 引擎（驱动一切运转的核心动力）
+- **Agent Loop** —— 引擎（驱动一切运转的核心动力）
 - **提示词系统** —— 灵魂（定义"我是谁"的持久身份）
 - **工具系统** —— 手脚（与外部世界交互的能力）
 - **消息循环** —— 心跳（保持持续运转的生命节律）
@@ -114,7 +114,7 @@ OpenClaw的使用门槛：
 
 接下来，我们逐一理解每个支柱的设计思想。对于每一个“支柱”，我们只讲两个问题： **旧架构的局限是什么？OpenClaw的优势是什么？**
 
-### 2.1 支柱一：ReAct循环——从"一问一答"到"持续迭代"
+### 2.1 支柱一：Agent Loop——从"一问一答"到"持续迭代"
 
 **旧架构的局限**
 
@@ -124,19 +124,34 @@ OpenClaw的使用门槛：
 
 **OpenClaw的优势**
 
-OpenClaw的核心引擎是一个**观察-思考-行动**的永动循环：
+OpenClaw 的核心引擎是一个**Agent Loop**，这是一个基于 ReAct 的“观察-思考-行动”的思想的工程实现。
+
+ReAct 强调的是“边判断边行动” —— 根据每一次行动的结果，灵活地规划下一步的行动，而不将所有步骤都写死。
 
 ![ReAct循环](./images/react-loop.png)
 
+ReAct 只定义了一个基本的循环框架，agent loop 的具体实现流程是：
+
+```text
+收到消息
+→ 组装当前上下文
+→ 模型判断下一步
+→ 需要动手就调用工具
+→ 把结果写回会话历史
+→ 再来一轮，直到任务完成
+```
+
+OpenClaw 的 agent loop 可以说是融合了 **ReAct “边判断边行动”的思想** 与 **如今大模型在训练中内化的决定如何调用工具的能力**。
+
 这个循环有三个关键特性：
 
-1. **错误不是终点，而是新的观察**。命令执行失败了？Agent不会崩溃，而是把错误信息当作新的观察，重新思考、调整策略
-2. **模型无关**。无论底层用Claude、GPT还是本地模型，都运行同一套循环引擎
-3. **有约束的自由**。框架是固定的（观察→思考→行动），但每一轮的具体行动是灵活的
+1. **任务没做完，它不会自己停下来**。普通对话是一问一答；Agent loop 则会持续推进，直到任务完成，或者明确碰到边界。
+2. **它会根据结果随时改方向**。上一步成功、失败、返回空结果，都会改变下一步。它不是沿着固定脚本往前跑，而是边做边调整。
+3. **它会把每一步的结果接回下一轮**。工具输出、报错信息、已经完成的步骤，都会回到上下文里，成为下一轮判断的依据。
 
 这不是简单的"多问多答"，而是一个**真正的迭代过程**——Agent能像人类一样，面对复杂任务时分步探索、逐步逼近目标。
 
-→ 详见[第二章 ReAct循环](../chapter2/index.md)
+→ 详见[第二章 Agent Loop](../chapter2/index.md)
 
 ### 2.2 支柱二：提示词系统——从"临时指令"到"持久人格"
 
@@ -146,7 +161,7 @@ OpenClaw的核心引擎是一个**观察-思考-行动**的永动循环：
 
 **OpenClaw的优势**
 
-OpenClaw用**八个Markdown文件**定义了Agent的完整人格：
+OpenClaw会用**一组工作区 Markdown 文件**定义 Agent 的默认身份与协作现场：
 
 | 文件 | 一句话说明 |
 |------|-----------|
@@ -159,7 +174,8 @@ OpenClaw用**八个Markdown文件**定义了Agent的完整人格：
 | HEARTBEAT.md | 定时任务清单 |
 | BOOTSTRAP.md | 首次运行的初始化引导 |
 
-这些文件在每次对话时被自动注入系统提示词，Agent**始终知道自己是谁、在跟谁说话、应该怎么做事**。
+这些文件并不都是以同样的方式进入一次 run。像 `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 这类 bootstrap 文件，通常会进入 Project Context；`BOOTSTRAP.md` 只在 brand-new workspace 的首次引导时出现；`MEMORY.md` 现在也会作为长期记忆文件注入，而 `memory/` 里的日记文件更多是靠工具按需召回。  
+也正因为如此，Agent 才能**始终知道自己是谁、在跟谁说话、应该怎么做事**，同时又不会把所有资料都无差别塞进同一个 prompt。
 
 更重要的是**热更新**机制：你修改任何一个`.md`文件，保存后的下一秒，Agent的行为就会改变。不需要重启，不需要重新部署。这让调试和优化Agent变得和编辑文档一样简单。
 
@@ -188,9 +204,9 @@ edit  → 修改（精确修改已有内容）
 exec  → 执行（运行Shell命令，与外部世界交互）
 ```
 
-为什么四个就够了？因为一个能**读文件、写文件、改文件、跑命令**的Agent，通过组合这四个原语，几乎可以完成**任何本地计算任务**。就像Unix的`cat`、`grep`、`sed`、`awk`可以组合出无穷的功能一样。
+为什么这四个重要？因为一个能**读文件、写文件、改文件、跑命令**的Agent，通过组合这四个原语，已经能覆盖大量本地计算任务。就像 Unix 的 `cat`、`grep`、`sed`、`awk` 一样，它们更像一套稳定的底层动作，而不是今天完整工具面的全部。
 
-在四个基础工具之上，OpenClaw通过**Skills（技能）** 机制实现能力的模块化扩展。技能本质上也是Markdown文件——描述了某个领域的专业知识和工作流程——Agent按需加载，不会撑爆上下文窗口。
+在这套底层原语之上，OpenClaw 还继续长出了 memory、sessions、web、messaging、automation、media 等一整套内置工具面；再往上，系统又通过 **Skills（技能）** 机制实现能力的模块化扩展。技能本质上也是 Markdown 文件——描述了某个领域的专业知识和工作流程——Agent 按需加载，不会撑爆上下文窗口。
 
 → 详见[第四章 工具系统](../chapter4/index.md)
 
@@ -204,9 +220,9 @@ exec  → 执行（运行Shell命令，与外部世界交互）
 
 OpenClaw的消息系统有三个核心设计：
 
-**泳道模型**。每个会话是一条独立的"泳道"——同一用户的消息按顺序处理（防止"创建文件"和"读取文件"乱序），不同用户的消息并行处理（你的5分钟任务不会阻塞我的快速查询）。
+**泳道模型**。每个 `session key` 都会落到自己的执行泳道里——同一条 session lane 保证串行，避免同一个任务现场乱序；不同 session 可以并行推进，而系统还会再用一条 global lane 去限制整体并发，不让所有任务同时挤爆运行时。
 
-**心跳机制**。Agent有自己的"生物钟"。你在`HEARTBEAT.md`里写下一个检查清单，系统会定期唤醒Agent来执行。如果没有需要关注的事，Agent静默返回`HEARTBEAT_OK`，不打扰你。如果有重要发现——比如你让它监控Stripe的收入仪表板——它会主动发消息告诉你。
+**心跳机制**。Agent 有自己的“生物钟”。你在 `HEARTBEAT.md` 里写下一个检查清单，系统会定期唤醒 Agent 做一次巡检。默认情况下，heartbeat 可以只在内部静默运行，不对外发送；如果确实发现了值得打扰你的事，或者你明确把 `target` 配到了某个外部目标，它才会主动提醒。没什么需要关注时，Agent 通常会返回 `HEARTBEAT_OK` 作为巡检完成的确认。
 
 **分层容错**。三层兜底机制：任务级（工具调用失败→重试或换方案）→ 会话级（任务失败→隔离影响，保持会话活跃）→ 服务级（底层服务崩溃→切换备用提供商或优雅降级）。
 
@@ -230,7 +246,7 @@ OpenClaw的Gateway（网关）像一位翻译官：
 
 更精妙的是**优雅降级**。Agent回复的内容通常是Markdown格式。Discord支持富文本卡片？翻译官就把Markdown转成精美的嵌入式消息。飞书支持交互按钮？翻译官就渲染出"确认/取消"按钮。纯文本平台？降级为简洁的文字。**统一而不单调，多样而不混乱**。
 
-跨平台身份识别通过`identityLinks`配置实现——你在Telegram、Discord、Slack上是同一个人，Agent记得你在所有渠道的偏好。
+跨平台身份关联可以通过 `identityLinks` 配置参与私聊 session key 的计算——它能帮助系统在某些 `dmScope` 下把同一个人的多个平台 ID 归到同一个规范身份；但这并不等于“默认所有平台共用一段上下文”，最终是否合并还要看会话粒度怎么配。
 
 → 详见[第六章 统一网关](../chapter6/index.md)
 
@@ -244,19 +260,19 @@ Agent能力越强，潜在破坏力越大。一个能执行Shell命令的Agent
 
 OpenClaw的安全哲学是：**不是限制能力，而是给能力加上安全护栏**。
 
-三层纵深防御：
+三层关键控制面：
 
-| 层级 | 防御对象 | 机制 |
+| 层级 | 主要问题 | 机制 |
 |------|---------|------|
-| 文件系统沙箱 | 防止越权访问 | Agent只能在指定工作目录内操作 |
-| 命令执行沙箱 | 防止危险命令 | Security模式（deny/allowlist/full） + Ask模式（确认机制） |
-| 网络访问沙箱 | 防止恶意外联 | 白名单域名控制 |
+| 工具策略 | 模型能不能看见某个工具 | `tools.profile` + `allow` / `deny` + provider / agent / sandbox / subagent policy |
+| 运行边界 | 工具具体在哪儿跑 | `sandbox.mode` + workspace / container / network 配置 |
+| 升级通道 | 少数情况下能不能从沙箱走到 host | `elevated` + approvals |
 
 以`exec`工具为例，它有三层安全模型：
 
-1. **Security模式**决定基本权限——deny（全部禁止）、allowlist（白名单）、full（全部允许）
-2. **Ask模式**决定何时需要人工确认——off（从不）、on-miss（不在白名单时）、always（每次都问）
-3. **安全命令列表（safeBins）** 提供只读工具的便捷通道——`jq`、`head`、`tail`等安全命令可以直接执行
+1. **运行边界** 先决定命令在哪儿跑——是在 sandbox、gateway host，还是特定 node 上执行
+2. **Security模式** 和 **Ask模式** 决定这条命令允不允许、要不要先人工确认
+3. **安全命令列表（safeBins）** 给少量 stdin-only 的低风险小工具开窄门，默认更像 `head`、`tail`、`tr`、`wc` 这一类，而不是一份通用命令白名单
 
 这种设计让你可以**渐进式地建立信任**：从只读模式开始，逐步开放执行权限，最终在安全护栏的保护下放心地让Agent自主操作。
 
@@ -279,10 +295,10 @@ OpenClaw的整个执行链条如下：
   → 统一网关（感知，翻译格式）
   → 消息循环（调度，防并发混乱）
   → 提示词系统（装配上下文，注入灵魂）
-  → ReAct循环（观察→思考→行动，反复迭代）
+  → Agent Loop（吸收了 ReAct 的方法，反复迭代）
   → 安全沙箱（每次工具调用必经的安全门）
   → 工具系统（真正动手执行）
-  → 结果回到 ReAct 循环，直到任务完成
+  → 结果回到 Agent Loop，直到任务完成
   → 统一网关（输出，翻译格式）
 → 用户收到回复
 ```
@@ -398,7 +414,7 @@ OpenClaw 真正值得重视的地方，在于它给了你一套把经验沉淀
 - 我能不能在关键地方做出靠谱判断
 
 这也是为什么第一章前面讲的那些架构设计，不只是技术细节。  
-ReAct 循环决定了它不是一次性回答，而是会持续推进；  
+Agent Loop 决定了它不是一次性回答，而是会持续推进；  
 提示词系统决定了你的经验可以变成默认规则；  
 工具系统和安全沙箱决定了它既能做事，也必须被管住。
 
@@ -414,7 +430,7 @@ ReAct 循环决定了它不是一次性回答，而是会持续推进；
 
 1. **历史的必然**。从对话模型到个人自主Agent，每一步演化都在解决上一代的核心局限。OpenClaw不是凭空出现的，它是AI从"能说"到"能做"这条演化链上的自然延伸。
 
-2. **六大支柱的协同**。ReAct循环是引擎，提示词系统是灵魂，工具系统是手脚，消息循环是心跳，统一网关是感官，安全沙箱是免疫系统——六者缺一不可，共同构成一个完整的"数字生命体"。
+2. **六大支柱的协同**。Agent Loop 是引擎，方法论上吸收了 ReAct；提示词系统是灵魂，工具系统是手脚，消息循环是心跳，统一网关是感官，安全沙箱是免疫系统——六者缺一不可，共同构成一个完整的"数字生命体"。
 
 3. **方向已定，细节未稳**。个人自主Agent的大方向已经明确，大厂纷纷跟进，但具体实现仍在快速迭代。理解底层设计思想，比追逐具体工具更重要。
 
@@ -424,4 +440,4 @@ ReAct 循环决定了它不是一次性回答，而是会持续推进；
 - 如果你想**快速上手** → 跳到实践篇
 - 如果你想**把握全局** → 本章已经给出完整的认知地图
 
-**下一步**：[第二章 ReAct循环](../chapter2/index.md)——深入探讨Agent的核心引擎，理解"观察-思考-行动"的永动机制。
+**下一步**：[第二章 Agent Loop](../chapter2/index.md)——深入探讨 Agent 的核心引擎，理解“观察-思考-行动”怎样在系统里持续跑起来。