Docs: normalize zh-CN terminology + tone

What: switch to 你/你的 tone; standardize Skills/Gateway网关/local loopback/私信 wording
Why: align zh-CN docs with issue 6995 feedback + idiomatic tech style
Tests: pnpm docs:build
This commit is contained in:
Josh Palmer
2026-02-02 15:46:45 +01:00
parent 2b1f68c928
commit 5676a6b38d
237 changed files with 2322 additions and 2337 deletions

View File

@@ -1,8 +1,8 @@
---
read_when:
- 需要调试会话 ID、对话记录 JSONL 或 sessions.json 字段
- 正在修改自动压缩行为或添加"压缩前"清理逻辑
- 想要实现记忆刷写或静默系统轮次
- 需要调试会话 ID、对话记录 JSONL 或 sessions.json 字段
- 正在修改自动压缩行为或添加"压缩前"清理逻辑
- 想要实现记忆刷写或静默系统轮次
summary: 深入解析:会话存储 + 对话记录、生命周期及(自动)压缩内部机制
title: 会话管理深入解析
x-i18n:
@@ -26,7 +26,7 @@ x-i18n:
- **压缩**(手动 + 自动压缩)以及压缩前工作的挂钩位置
- **静默清理**(例如不应产生用户可见输出的记忆写入)
如果想先了解更高层级的概览,请从以下内容开始:
如果想先了解更高层级的概览,请从以下内容开始:
- [/concepts/session](/concepts/session)
- [/concepts/compaction](/concepts/compaction)
@@ -35,12 +35,12 @@ x-i18n:
---
## 数据源Gateway
## 数据源Gateway网关
OpenClaw 围绕单个 **Gateway 进程**设计,该进程拥有会话状态。
OpenClaw 围绕单个 **Gateway网关进程**设计,该进程拥有会话状态。
- UImacOS 应用、Web 控制界面、TUI应向 Gateway 查询会话列表和 token 计数。
- 在远程模式下,会话文件位于远程主机上;"检查本地 Mac 文件"不会反映 Gateway 正在使用的内容。
- UImacOS 应用、Web 控制界面、TUI应向 Gateway网关查询会话列表和 token 计数。
- 在远程模式下,会话文件位于远程主机上;"检查本地 Mac 文件"不会反映 Gateway网关正在使用的内容。
---
@@ -62,7 +62,7 @@ OpenClaw 通过两个层持久化会话:
## 磁盘位置
每个智能体,在 Gateway 主机上:
每个智能体,在 Gateway网关主机上:
- 存储:`~/.openclaw/agents/<agentId>/sessions/sessions.json`
- 对话记录:`~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl`
@@ -74,7 +74,7 @@ OpenClaw 通过 `src/config/sessions.ts` 解析这些路径。
## 会话键(`sessionKey`
`sessionKey` 标识*所在的对话桶*(路由 + 隔离)。
`sessionKey` 标识*所在的对话桶*(路由 + 隔离)。
常见模式:
@@ -95,7 +95,7 @@ OpenClaw 通过 `src/config/sessions.ts` 解析这些路径。
经验法则:
- **重置**`/new``/reset`)为该 `sessionKey` 创建新的 `sessionId`
- **每日重置**(默认为 Gateway 主机本地时间凌晨 4:00在重置边界后的下一条消息时创建新的 `sessionId`
- **每日重置**(默认为 Gateway网关主机本地时间凌晨 4:00在重置边界后的下一条消息时创建新的 `sessionId`
- **空闲过期**`session.reset.idleMinutes` 或旧版 `session.idleMinutes`)在空闲窗口后收到消息时创建新的 `sessionId`。当每日重置和空闲过期同时配置时,先到期的优先。
实现细节:决策发生在 `src/auto-reply/reply/session.ts` 中的 `initSessionState()` 函数。
@@ -124,7 +124,7 @@ OpenClaw 通过 `src/config/sessions.ts` 解析这些路径。
- `memoryFlushAt`:上次压缩前记忆刷写的时间戳
- `memoryFlushCompactionCount`:上次刷写运行时的压缩计数
存储可安全编辑,但 Gateway 是权威来源:随着会话运行,它可能重写或重新注入条目。
存储可安全编辑,但 Gateway网关是权威来源:随着会话运行,它可能重写或重新注入条目。
---
@@ -145,7 +145,7 @@ OpenClaw 通过 `src/config/sessions.ts` 解析这些路径。
- `compaction`:持久化的压缩摘要,包含 `firstKeptEntryId``tokensBefore`
- `branch_summary`:导航树分支时的持久化摘要
OpenClaw 有意**不**"修复"对话记录Gateway 使用 `SessionManager` 来读写它们。
OpenClaw 有意**不**"修复"对话记录Gateway网关使用 `SessionManager` 来读写它们。
---
@@ -156,7 +156,7 @@ OpenClaw 有意**不**"修复"对话记录Gateway 使用 `SessionManager` 来
1. **模型上下文窗口**:每个模型的硬上限(模型可见的 token 数)
2. **会话存储计数器**:写入 `sessions.json` 的滚动统计(用于 /status 和仪表板)
如果正在调整限制:
如果正在调整限制:
- 上下文窗口来自模型目录(可通过配置覆盖)。
- 存储中的 `contextTokens` 是运行时估算/报告值;不要将其视为严格保证。
@@ -226,7 +226,7 @@ OpenClaw 还为嵌入式运行强制执行安全下限:
## 用户可见界面
可以通过以下方式观察压缩和会话状态:
可以通过以下方式观察压缩和会话状态:
- `/status`(在任何聊天会话中)
- `openclaw status`CLI
@@ -273,16 +273,16 @@ OpenClaw 使用**预阈值刷写**方法:
- 当会话工作区为只读(`workspaceAccess: "ro"``"none"`)时跳过刷写。
- 工作区文件布局和写入模式参阅[记忆](/concepts/memory)。
Pi 也在扩展 API 中暴露了 `session_before_compact` 钩子,但 OpenClaw 的刷写逻辑目前在 Gateway 侧。
Pi 也在扩展 API 中暴露了 `session_before_compact` 钩子,但 OpenClaw 的刷写逻辑目前在 Gateway网关侧。
---
## 故障排除清单
- 会话键错误?从 [/concepts/session](/concepts/session) 开始,确认 `/status` 中的 `sessionKey`
- 存储与对话记录不匹配?确认 Gateway 主机以及 `openclaw status` 中的存储路径。
- 存储与对话记录不匹配?确认 Gateway网关主机以及 `openclaw status` 中的存储路径。
- 压缩过于频繁?检查:
- 模型上下文窗口(太小)
- 压缩设置(`reserveTokens` 相对于模型窗口过高可能导致更早触发压缩)
- 工具结果膨胀:启用/调整会话修剪
- 静默轮次泄露?确认回复以 `NO_REPLY`(精确 token开头使用的构建版本包含流式传输抑制修复。
- 静默轮次泄露?确认回复以 `NO_REPLY`(精确 token开头使用的构建版本包含流式传输抑制修复。