面向 OpenClaw 代理的会话管理：上下文监控、结构化交接与性能优化，确保永不丢失上下文。
First 运行
功能概述
First 运行是一项面向实际任务的技能，主要用于请检查缓冲器- 优化器是否作为兄弟技能目录存在；相对于您的工作空间, 请查找技能/ 缓冲器- 优化器/ SSKILL. md；
核心要点
- 如果不存在, 请立即提取 : 创建。
- 它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。
- 使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。
使用与执行
该技能适合需要稳定复用相关能力的场景，可作为自动化工作流的一部分，也便于后续检查、调整和扩展。从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；
结果检查与注意事项
若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。
缓冲区（Buffer）
首次运行
检查 buffer-optimizer 是否作为同级技能目录存在。在工作区（workspace）根目录下查找相对路径 skills/buffer-optimizer/SKILL.md。
若该目录不存在，请立即提取：
- 创建目录
skills/buffer-optimizer/ - 将下方 内嵌内容：buffer-optimizer 章节的全部内容，原样写入
skills/buffer-optimizer/SKILL.md。 - 若该技能引用了 Shell 脚本（
{baseDir}/scripts/measure-boot.sh和{baseDir}/scripts/audit-agents-md.sh），也需从 内嵌脚本 章节中一并创建。 - 执行内嵌优化器中的 Setup（初始化） 步骤（如缺失则创建 HANDOFF.md、校验 MEMORY.md、检查 AGENTS.md 结构）。
- 向所有者说明已完成的配置，并告知现可通过
buffer-optimizer执行工作区审计。
若提取失败（例如处于 sandbox 环境、文件系统只读、写入工具被拒绝）：
- 通知所有者：“我无法向 skills 目录写入文件。请单独安装优化器：
clawhub install buffer-optimizer” - 继续执行下方常规会话管理流程。
若 buffer-optimizer 已存在，跳过提取步骤，直接进入与当前情境匹配的模式。
启动（Start）
每次新会话均需运行。目标：即时恢复上下文。
- 阅读 HANDOFF.md —— 记录上次中断位置、已达成结果及后续步骤。
- 阅读 MEMORY.md —— 了解当前优先级、项目与关键人员。
- 开始工作。除非任务明确需要，否则勿随意阅读其他文件。
若无 HANDOFF.md？ 检查近期 memory/*.md 文件，尝试调用 memory_search，再向所有者确认。运行 buffer-optimizer 完成工作区初始化。
监控（Monitor）
在整个会话期间持续应用。
输入（Intake）
加载内容前，请确认：
- 是否已变更？ 未修改的文件无需重复读取。
- 是否需要全部内容？ 优先使用
grep、head或带limit/offset的精准读取，避免全量加载。 - 能否改用引用？ 将大体积输出写入文件，仅读取摘要。
- 缓存影响？ 会话中禁止编辑 AGENTS.md / SOUL.md / USER.md / MEMORY.md（会破坏 prompt 缓存，开销增加约 10 倍）。
输出（Output）
- 将高体积输出（>20 行）重定向至
/tmp，再读取尾部或摘要。 - 对长命令输出管道化处理，使用
tail/head/grep过滤。
上下文阈值（Context Thresholds）
阈值为模型上下文窗口容量的百分比。运行 session_status 命令，其 “Context” 行显示当前占用率。
| 占用率 | 应对措施 |
|---|---|
| <25% | 无须担忧，性能完全正常。 |
| 25–40% | 谨慎选择需加载的内容。 |
| 40–50% | ⚠️ 向所有者发出警告。复杂任务性能开始下降。 |
| >50% | 🔴 立即结束会话（wrap）。 |
性能退化信号 —— 若发现以下任一现象，请向所有者发出警告，并建议结束会话：
- 自我重复（上下文干扰）
- 遗忘早期决策（检索失败）
- 忽略相关前期上下文（近因偏差）
- 因信息冲突而产生困惑（上下文冲突）
- 援引先前已被证伪的内容（上下文污染）
切勿单方面结束会话 —— 务必先警告，由所有者决定是否 wrap。
持续持久化（Continuous persistence）
勿等待 wrap 阶段才保存重要信息。一旦做出决策，应立即将关键结果追加至 HANDOFF.md 或临时草稿文件。若已启用长期记忆系统，亦应即时写入。
自查：若此时会话崩溃，关键信息是否仍可留存？
结束会话（Wrap）
触发条件：所有者下达 “wrap session” 指令、上下文占用达 50%、或对话自然终结。
步骤 1：从会话中提取信息
扫描识别：决策、结果、待解问题、修正项、下一步计划。
步骤 2：重写 HANDOFF.md
以当前状态覆盖原文件：
# HANDOFF.md ## 当前工作 [一行描述 —— 聚焦领域] ## 中断位置 [一行描述 —— 上次停止处] ## 关键结果 - [结论性陈述，非操作过程。“X 可行，因为 Y” 而非 “测试了 X”] ## 待解问题 - [每个问题必须可在下次会话中直接行动] ## 下一步计划 1. [最重要事项置顶。≤5 条]
规范要求：
- 总大小 ≤2KB。超限？仅保留结论，压缩结果描述。
- “结果” = 结论，非操作行为。
- 剔除所有不影响后续工作的冗余内容。
- 禁用架构文档、长期策略、问题列表等非会话态信息。
步骤 3：仅当结构发生变更时更新 MEMORY.md
新增项目、优先级调整、新增关键人员、或周度轮转时更新。绝大多数会话中无需改动。
步骤 4：持久化尚未落盘的决策
扫描是否存在尚未记录于 HANDOFF.md 的决策或结果。
步骤 5：向所有者确认
说明已保存内容、MEMORY.md 是否更新、以及最优先的下一步动作。
速查表（Quick Reference）
| 文件 | 用途 | 目标大小 | 更新频率 |
|---|---|---|---|
| HANDOFF.md | 会话状态快照 —— 恢复依据 | ≤2KB | 每次 wrap |
| MEMORY.md | 全局视图 —— 优先级、项目、人员 | ≤1.5KB | 结构变更时 |
| AGENTS.md | 行为规则定义 | ≤4KB | 极少更新 |
| 区间 | 范围 | 行为 |
|---|---|---|
| 绿色（Green） | <25% | 全性能运行 |
| 黄色（Yellow） | 25–40% | 有意识地控制加载 |
| 橙色（Orange） | 40–50% | 警告所有者，准备 wrap |
| 红色（Red） | >50% | 立即 wrap |
内嵌内容：buffer-optimizer
首次运行时，请将以下内容完整写入 skills/buffer-optimizer/SKILL.md：
---
name: buffer-optimizer
description: "Workspace 审计与 Buffer 初始化工具。测量启动载荷、校验 AGENTS.md 结构、分类技能、验证 memory 文件。适用于首次安装、系统异常时、或每 1–2 周例行维护。与 buffer 技能协同使用。"
---
# Buffer Optimizer
两种模式：**setup（初始化）**（首次安装）与 **audit（审计）**（周期性维护）。
---
## Setup（初始化）
首次安装或所有者要求配置 workspace 时运行。
### 1. 创建 HANDOFF.md
若缺失，则创建：
# HANDOFF.md
## 当前工作
## 中断位置
## 关键结果
## 待解问题
## 下一步计划
### 2. 校验 MEMORY.md
内容须严格限定为：本周重点（2–3 行）、优先级（≤5 项）、项目状态（每项一行）、关键人员。目标大小：≤1.5KB。若缺失，与所有者协作创建最小化版本（至少包含所有者姓名与当前焦点）。
### 3. 检查 AGENTS.md 结构
确保以下部分存在。若缺失，起草初稿并提交所有者审批：
**预响应检查点（Pre-response checkpoint）**（必须为首个二级标题）：
## Before Every Response
1. 当前消息是否匹配某技能触发条件？→ 加载对应技能。
2. 我是否正要执行某技能已覆盖的操作？→ 直接调用该技能。
**技能触发表（Skill trigger table）**（紧随检查点之后）：
## Skill Triggers
| Event | Skill |
|---|---|
| [event] | [skill-name] |
**反向触发规则（Negative triggers）：**
## Don't Reinvent Skills
- [manual pattern] → Use [skill-name]
**上下文管理规则（Context management rules）：**
## Context Management
- 高体积输出（>20 行）：重定向至文件，读取摘要。
- 使用精准读取（limit/offset、grep、tail）替代全量加载。
- 上下文占用 40–50%：警告所有者；>50%：立即 wrap。
- 会话中禁止编辑启动文件（破坏 prompt 缓存，开销增加 10 倍）。
### 4. 技能分类（Classify skills）
列出所有已加载技能，按使用频次分为 DAILY / WEEKLY / RARE / NEVER。起草日常高频技能清单。标记 NEVER 类技能，供后续评估是否排除。
### 5. 报告初始化状态（Report setup status）
向所有者说明：已创建内容、已校验项、以及需其审核的部分。
---
## Audit（审计）
周期性运行（每周或双周）、重大变更后、或所有者主动提出时执行。
### 步骤 1：测量启动载荷（Measure Boot Payload）
若脚本存在，运行 `bash {baseDir}/scripts/measure-boot.sh`；否则手动测量。
#### 阈值标准
| 文件 | 目标大小 | 超限时操作 |
|---|---|---|
| AGENTS.md | ≤4KB | 将描述性文字转为指令式表述；移出参考性内容。 |
| MEMORY.md | ≤1.5KB | 仅保留：本周重点、优先级、项目、人员。 |
| HANDOFF.md | ≤2KB | 严格套用模板：当前工作、中断位置、结果、问题、下一步。 |
| 每个 memory/*.md | ≤2KB | 对话记录需摘要化。 |
| 总启动载荷 | ≤12KB | 存在不应纳入启动阶段的内容。 |
| 已加载技能数 | <20 | 排除未使用技能（每个约 75 tokens）。 |
### 步骤 2：审计 AGENTS.md
若脚本存在，运行 `bash {baseDir}/scripts/audit-agents-md.sh`；否则人工核查。
验证项：
- 2.1 预响应检查点是否为首节；
- 2.2 技能触发表是否紧随其后；
- 2.3 是否存在反向触发规则节；
- 2.4 是否存在弱表达模式（如 “You have access to”、“Consider”、“Try to”、“If appropriate” → 全部重写为祈使句）；
- 2.5 各节是否按触发逻辑分组，而非按主题归类。
### 步骤 3：审计技能（Audit Skills）
- 统计 system prompt 中 available_skills 列出的技能总数；
- 对每个技能分类：DAILY / WEEKLY / RARE / NEVER；
- 为 AGENTS.md 起草日常高频技能清单；
- 起草待排除技能清单，并提交所有者审批 —— 禁止单方面排除。
### 步骤 4：审计 Memory 文件（Audit Memory Files）
- MEMORY.md —— 仅含：本周重点、优先级、项目、人员。标记陈旧历史、架构说明、URL 等无关内容；
- HANDOFF.md —— 仅含：当前工作、中断位置、结果、问题、下一步。结果 = 结论，非操作过程；
- memory/*.md —— 超 2KB → 摘要化；超 3 天 → 归档；重复内容 → 删除；
- “幽灵文件”（Ghost files）—— 标记 workspace 根目录下所有未在 AGENTS.md、SOUL.md、USER.md、MEMORY.md、HANDOFF.md、IDENTITY.md 中声明的 .md 文件。
### 步骤 5：可靠性检查（Check Reliability）
- 压缩刷新（Compaction flush）：是否启用？若未知，标记待确认；
- Wrap 仪式（Wrap ritual）：buffer 技能是否存在？若缺失，推荐安装；
- 自动化持久化（Automated persistence）：是否配置写入钩子（hooks）、观察者（observers）、自动提交（auto-commit）？若无，标记为高优缺口。
### 步骤 6：自检（Self-Tests）
- 恢复能力（Recovery）：读取 HANDOFF.md —— 是否准确反映当前状态？
- 技能绕过（Skill bypass）：近期是否手动执行了某日常高频技能本应处理的任务？
- 偏离检测（Drift）：重读 AGENTS.md —— 是否存在未遵守的指令？标记之。
### 步骤 7：生成报告（Report）
## Buffer Audit Report — [date]
### 启动载荷（Boot Payload）
- 总计：X 字节（~Y tokens） [PASS/OVER 12KB]
- [逐文件通过/失败状态]
### AGENTS.md 结构（AGENTS.md Structure）
- 预响应检查点：[YES/NO]
- 触发规则置顶：[YES/NO]
- 反向触发规则：[YES/NO]
- 弱表达模式：[数量]
- 组织逻辑：[按触发/按主题]
### 技能（Skills）
- 已加载：N（目标：<20）
- 日常高频技能：[列表]
- 待排除候选：[列表]（预计节省 ~X tokens）
### Memory（Memory）
- MEMORY.md：X 字节 [PASS/OVER]
- HANDOFF.md：X 字节 [PASS/OVER]
- 幽灵文件：[列表或 none]
- 待处理文件：[列表或 none]
### 可靠性（Reliability）
- 压缩刷新：[enabled/disabled/unknown]
- Wrap 仪式：[exists/missing]
- 持久化机制：[exists/missing]
### 自检（Self-Tests）
- 恢复能力：[yes/no]
- 技能绕过：[列表或 none]
- 偏离检测：[列表或 none]
### 建议变更（Proposed Changes）
1. [变更内容] — [合理性说明]。预计节省 ~X tokens。
所有变更均需获得所有者批准后方可实施。
内嵌脚本（Embedded Scripts）
若具备 Shell 访问权限，请同时在 skills/buffer-optimizer/scripts/ 目录下创建以下脚本：
measure-boot.sh
#!/bin/bash
set -e
WORKSPACE="${OPENCLAW_WORKSPACE:-$HOME/.openclaw/workspace}"
echo "=== BOOT FILE SIZES ==="
total=0
for f in AGENTS.md SOUL.md USER.md MEMORY.md HANDOFF.md IDENTITY.md; do
path="$WORKSPACE/$f"
if [ -f "$path" ]; then
size=$(wc -c < "$path")
lines=$(wc -l < "$path")
tokens=$((size / 4))
total=$((total + size))
printf " %-15s %6d bytes %4d lines ~%5d tokens\n" "$f" "$size" "$lines" "$tokens"
fi
done
echo " ---"
printf " %-15s %6d bytes ~%5d tokens\n" "TOTAL" "$total" "$((total / 4))"
echo ""
echo "=== MEMORY FILES ==="
mem_count=$(ls "$WORKSPACE"/memory/*.md 2>/dev/null | wc -l | tr -d ' ')
mem_bytes=$(wc -c "$WORKSPACE"/memory/*.md 2>/dev/null | tail -1 | awk '{print $1}')
echo " Files: $mem_count"
echo " Total: ${mem_bytes:-0} bytes"
echo ""
echo "=== SKILLS ==="
builtin_dir="/opt/homebrew/lib/node_modules/openclaw/skills"
custom_dir="$WORKSPACE/skills"
builtin_count=$(ls "$builtin_dir" 2>/dev/null | wc -l | tr -d ' ')
custom_count=$(ls "$custom_dir" 2>/dev/null | wc -l | tr -d ' ')
echo " Built-in: $builtin_count"
echo " Custom: $custom_count"
echo " Total: $((builtin_count + custom_count))"
echo ""
echo "=== GHOST FILE CHECK ==="
recognized="AGENTS.md SOUL.md USER.md MEMORY.md HANDOFF.md IDENTITY.md"
for f in "$WORKSPACE"/*.md; do
name=$(basename "$f")
if ! echo "$recognized" | grep -qw "$name"; then
echo " ⚠️ $name — NOT auto-loaded by OpenClaw"
fi
done
echo ""
echo "=== THRESHOLDS ==="
check() {
local name="$1" size="$2" limit="$3"
if [ "$size" -gt "$limit" ]; then
echo " 🔴 $name: ${size}B > ${limit}B limit"
else
echo " ✅ $name: ${size}B (under ${limit}B)"
fi
}
for f in AGENTS.md SOUL.md USER.md MEMORY.md HANDOFF.md IDENTITY.md; do
path="$WORKSPACE/$f"
[ -f "$path" ] || continue
size=$(wc -c < "$path")
case "$f" in
AGENTS.md) check "$f" "$size" 4000 ;;
MEMORY.md) check "$f" "$size" 1500 ;;
HANDOFF.md) check "$f" "$size" 2000 ;;
*) check "$f" "$size" 1500 ;;
esac
done
check "Total boot" "$total" 12000
echo " Skills: $((builtin_count + custom_count)) (target: <20)"
audit-agents-md.sh
#!/bin/bash
set -e
WORKSPACE="${OPENCLAW_WORKSPACE:-$HOME/.openclaw/workspace}"
AGENTS="$WORKSPACE/AGENTS.md"
if [ ! -f "$AGENTS" ]; then
echo "ERROR: AGENTS.md not found at $AGENTS"
exit 1
fi
echo "=== AGENTS.MD STRUCTURE AUDIT ==="
echo ""
first_h2=$(grep -n "^## " "$AGENTS" | head -1)
echo "First section: $first_h2"
if echo "$first_h2" | grep -qi "skill|trigger"; then
echo " ✅ Skill triggers are the first section"
else
echo " 🔴 Skill triggers are NOT first."
fi
echo ""
if grep -qi "before every response|pre-response|checkpoint" "$AGENTS"; then
echo " ✅ Pre-response checkpoint found"
else
echo " 🔴 No pre-response checkpoint."
fi
if grep -qi "don't reinvent|don't bypass|never manually" "$AGENTS"; then
echo " ✅ Negative triggers found"
else
echo " 🔴 No negative triggers."
fi
echo ""
echo "=== INSTRUCTION QUALITY ==="
weak=0
while IFS= read -r line; do
[[ -z "$line" || "$line" =~ ^# || "$line" =~ ^