前置基础概念

OpenClaw/UpClaw 基于 AgentScope 做企业提示词工程改造，全部提示词、规则、身份、技能、记忆、路由均通过标准化 .md 文件外置管理，实现配置分离；所有md文件分为两大类：

1. 全局静态Prompt配置MD（会话初始化一次性加载，构成System Prompt骨架）
2. 技能/子代理/记忆动态MD（运行时按需增量加载）
3. rules.md 规则MD（独立规则引擎，优先级高于所有业务提示词，安全硬约束）

整体上下文拼装层级（模型接收顺序，从上至下，上层约束下层）：
rules.md安全规则 → 全局身份/系统MD → 子代理/角色MD → 技能SKILL.md → LongTermMemory召回片段 → 会话短时对话历史 → 当前用户输入

一、全部MD文件分层与优先级（从高到低，高优先级覆盖低优先级冲突内容）

层级0：全局规则层（最高，不可被任何提示词覆盖）

rules.md

• 作用：风控、权限、推理预算、risk-on/risk-off、合规拦截、路由硬规则
• 约束：所有提示词必须在rules划定边界内执行，高危操作直接拦截，无视下层prompt

层级1：全局工作区基线MD（平台全局，所有会话共享）

1. IDENTITY.md 身份基线（最高业务提示词）
   主代理身份、岗位、权责、模型基础约束、输出强制格式
2. AGENTS.md 多智能体调度规范
   子代理委派、SFA2A通信、任务分发、协作流程、父子代理权限
3. BOOTSTRAP.md 会话启动引导
   会话初始化标准流程、首次推理前置动作、上下文裁剪策略
4. SOUL.md 基础人格与推理范式
   ReAct思考逻辑、深度推理规范、思维链约束、输出语气
5. TOOLS.md Toolkit全局工具总说明
   全部工具通用调用规范、参数格式、错误重试逻辑、工具输出解析规则
6. HEARTBEAT.md 自动化调度提示
   定时归档、记忆自动整理、会话保活、闲置回收策略
7. MEMORY.md LongTermMemory读写规范
   记忆写入/召回/过期/摘要规则、向量检索阈值、记忆分层策略

层级2：租户/用户私有MD（覆盖全局基线，同租户所有会话生效）

USER.md
用户/租户专属偏好、业务域背景、脱敏规则、行业话术、专属输出模板

层级3：角色/子代理专属MD（单代理隔离，覆盖租户+全局）

子代理目录下 agent.md
独立子代理专属身份、专属技能范围、专属推理约束、独立记忆隔离规则

层级4：会话私有MD（单次会话临时生效，优先级最低，仅补充）

session.md
单次任务临时指令、临时上下文、临时风险开关，会话销毁自动失效

层级5：技能动态MD（运行时按需加载，不常驻System Prompt）

各技能目录 SKILL.md
仅当模型判定需要调用该工具时，才增量拼入上下文；同名技能遵循目录优先级：
workspace/skills > ~/.openclaw/skills > 框架内置bundled skills

优先级总表（从高→低，覆盖关系）

1. rules.md（规则引擎，独立最高）
2. 会话私有 session.md
3. 子代理专属 agent.md
4. 租户 USER.md
5. 全局基线：IDENTITY.md > AGENTS.md > BOOTSTRAP.md > SOUL.md > TOOLS.md > HEARTBEAT.md > MEMORY.md
6. 技能 SKILL.md（动态按需加载）
7. LongTermMemory召回记忆片段（纯补充，无覆盖能力）

核心覆盖逻辑：高优先级文件可重写、补充低优先级字段；低优先级无法推翻上层刚性约束（尤其rules.md）

二、完整MD提示词加载全流程（分两大阶段：会话初始化静态加载 + 推理运行时动态加载）

阶段1：会话初始化（onSessionCreate 生命周期钩子，一次性全量解析静态MD）

1. 文件扫描发现
   框架递归扫描三层目录：全局工作区 → 租户目录 → 当前子代理目录，收集全部.md配置文件，做文件变更快照对比，无变更直接复用内存缓存，减少IO开销。
2. 优先级排序与冲突合并
   按上述优先级从高到低依次读取文本，同名配置段（如输出格式、工具限制）高优先级覆盖低优先级；
   rules.md单独解析为规则引擎树，不混入Prompt文本，但全局生效拦截。
3. 静态片段拼装完整System Prompt骨架
   按固定顺序拼接：IDENTITY → AGENTS → BOOTSTRAP → SOUL → TOOLS → HEARTBEAT → MEMORY → USER.md → agent.md → session.md；
   自动插入分段分隔标记，方便模型区分不同模块约束。
4. Token预算校验与上下文裁剪
   读取rules.md中推理预算规则，若静态Prompt总token超限，自动压缩低优先级片段（MEMORY.md/USER.md优先裁剪），生成轻量化系统提示快照缓存至会话内存。
5. 基础Toolkit与LongTermMemory绑定
   TOOLS.md解析为工具元数据注入Toolkit；MEMORY.md规则写入长期记忆读写钩子，初始化记忆检索阈值。

阶段2：单次推理循环动态加载（onReasoningStart / onToolCall 运行时增量加载）

1. 用户消息入站 → rules.md前置校验（风险拦截、路由分流）
2. 加载静态System Prompt骨架（初始化缓存快照，无需重复读文件）
3. LongTermMemory 按MEMORY.md规则检索历史记忆，召回片段追加至上下文
4. 模型思考判断是否需要调用技能
    ├─ 不需要：直接携带静态Prompt+记忆+用户输入请求LLM
    └─ 需要：触发SKILL.md动态加载流程
       1. 按技能目录优先级读取对应SKILL.md
       2. 校验rules.md工具黑白名单，禁止技能直接阻断
       3. 将SKILL.md技能指令增量拼入上下文
       4. 执行Toolkit工具调用，捕获返回结果
5. 工具执行完成后，清理临时SKILL.md片段（不污染下一轮基础Prompt）
6. 后置审计：输出内容匹配rules.md合规规则，违规拦截返回
7. 本轮推理结束，按MEMORY.md规则写入本次交互至长期记忆

阶段3：文件热更新加载（不中断在线会话）

1. 后台监听所有md文件变更；
2. 变更触发重新扫描、合并、生成新Prompt快照；
3. 新会话自动使用新版快照，活跃会话复用旧快照直至会话销毁（无会话中断）；
4. 记录配置变更审计日志，存入可观测链路。

三、各MD文件在Agent完整生命周期的参与阶段与作用

AgentScope标准生命周期：
会话创建初始化 → 消息入站前置校验 → 推理启动准备 → 模型思考阶段 → 工具执行阶段 → 记忆读写阶段 → 结果输出后置审计 → 会话销毁/归档

1. rules.md（全生命周期持续生效）

• 会话创建：加载规则引擎，初始化权限、预算、风险模式（risk-on/risk-off）
• 消息入站：第一道拦截，风险识别、任务路由、敏感内容阻断
• 推理启动：校验token上限、工具调用次数预算、模型降级策略
• 工具执行：校验工具黑白名单、并发安全锁、人工确认触发
• 记忆读写：管控记忆隔离、读写权限、归档清理
• 输出后置：合规审计、脱敏、违规结果回滚
• 会话销毁：释放会话资源、重置计数器、归档会话快照

2. 全局基线MD（IDENTITY/AGENTS/BOOTSTRAP/SOUL/TOOLS/HEARTBEAT/MEMORY）

仅会话初始化阶段完整加载，全会话常驻System Prompt

• onSessionCreate：拼装基础系统提示，绑定Toolkit、Memory、子代理调度逻辑
• onReasoningStart：每轮推理自动携带，约束模型基础行为、思考范式、工具使用规范
• onMemoryRead/Write：MEMORY.md全程管控记忆召回、写入逻辑
• onSubAgentDispatch：AGENTS.md控制子代理委派、SFA2A跨代理通信格式
• onSessionDestroy：HEARTBEAT.md执行会话归档、记忆持久化、资源回收

3. USER.md（租户私有）

• 会话初始化加载，全会话生效；
• 每轮推理注入租户行业背景、用户偏好，微调模型输出风格，不突破IDENTITY/rules刚性约束。

4. agent.md（子代理专属）

• 子代理实例创建时加载；
• 仅当前子代理推理循环生效，独立隔离提示词，实现多代理差异化行为。

5. session.md（会话临时）

• 会话初始化/任务启动时加载；
• 仅当前单次会话生效，会话销毁自动丢弃，适合临时任务约束。

6. SKILL.md（技能动态MD）

• onToolCall 工具触发阶段按需加载；
• 仅工具执行本轮上下文临时注入，工具执行完毕即清理，不污染后续推理；
• 复用内存技能快照，避免重复读取文件。

7. MEMORY.md 控制LongTermMemory片段注入

• onReasoningStart：每轮推理前执行记忆检索，将召回片段追加上下文；
• onAgentOutput：推理结束后按规则写入新记忆至向量库。

四、企业生产价值（对应UpClaw 19大改造板块）

1. 配置分离：提示词、规则全部外置md，无需改代码重启服务，支持灰度更新；
2. 安全隔离&权限合规：rules.md最高优先级硬兜底，多层md分层隔离租户/子代理提示词；
3. 上下文管理：分层Prompt+动态技能加载+记忆按需召回，解决上下文超限问题；
4. 推理预算优化：md内置token、工具调用次数约束，配合rules熔断无限推理；
5. 子代理委派/SFA2A：AGENTS.md统一规范多代理通信、分工；
6. 可观测性：所有md加载、变更、命中、拦截行为全埋点审计；
7. 提示词工程标准化：拆分身份、人格、工具、记忆、调度多模块，便于维护、版本管理、多人协作；
8. 模型韧性：BOOTSTRAP.md内置模型重试、降级、异常输出修复逻辑；
9. 并发安全：md快照缓存机制，多并发会话不重复IO解析配置文件。

五、risk-on / risk-off 与MD提示词联动逻辑

risk模式开关在rules.md顶层配置，会动态调整所有md片段的生效逻辑：

1. risk-off（高安全）
   裁剪SKILL.md高危工具、限制MEMORY.md召回条数、禁用session.md临时高权限指令、严格压缩Prompt总长度；
2. risk-on（可信内网）
   完整加载全部技能md、放开记忆召回上限、允许session.md临时增强指令、放宽token预算限制；
3. 所有切换仅修改rules.md开关，底层md文件无需改动，全局Prompt拼装逻辑自动适配。