OpenClaw OpenProse 文件系统状态管理：用 .prose/ 目录实现可检查、可恢复的多 Agent 执行状态

人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载本文围绕 OpenClaw 仓库中 OpenProse 技能包的核心文档 filesystem.md 展开详解 OpenProse VM 如何用.prose/目录下的纯 Markdown 文件承载多 Agent 程序的执行状态——包括目录结构、state.md带注释代码片段的追踪格式、bindings 作用域文件、agent 记忆分段机制以及子 Agent 输出写入与执行恢复协议。读完本文你将能够读懂并手工检查一次.prose运行的完整执行痕迹理解递归调用下的绑定命名规则并在程序中断后基于状态文件恢复执行。1. 概览文件即可检查的执行状态OpenProse VM 是 OpenClaw 中负责执行.prose程序的智能虚拟机它通过 Task 类工具派生真实子 Agent 会话来逐条执行语句。VM 需要持久化执行到哪了、变量值是什么、Agent 记住了什么这类信息仓库为此定义了两种状态管理方案文件系统状态本文主题默认方案把全部执行产物落盘到.prose/目录上下文内状态in-context把状态写进对话历史见 in-context.md。文件化状态把每一个执行产物都持久化到磁盘从而天然获得四类能力可检查性Inspection精确看到每一步发生了什么可恢复性Resumption从中断的程序继续执行长时工作流承载超出上下文窗口限制的长程序可调试性Debugging沿着执行历史回溯问题。原文档给出的核心原则值得单独强调文件就是可检查的产物目录结构本身就是执行状态Files are inspectable artifacts. The directory structure IS the execution state.。从源码结构看这个原则贯穿了 VM 语义文档 prose.md 的组件映射表传统 VM 的程序计数器、调用栈、寄存器/变量分别对应记录在state.md或旁白中的执行位置、state.md 或旁白协议追踪的块调用链、存储在bindings/{name}.md中的命名绑定而持久存储层就是.prose/目录本身。技能清单 SKILL.md 也把 filesystem 标注为默认模式并给出适用场景对照模式适用场景状态位置filesystem默认复杂程序、需要断点恢复、需要调试.prose/runs/{id}/文件in-context简单程序30 条语句无需持久化对话历史sqlite实验性可查询状态、原子事务、灵活模式.prose/runs/{id}/state.dbpostgres实验性真正并发写入、外部集成、团队协作PostgreSQL 数据库2. 目录结构两次运行之间不会冲突的状态布局文件状态按项目级与用户级两个层次组织。完整结构如下继承自原文档# 项目级状态位于工作目录 .prose/ ├── .env # 配置简单 keyvalue 格式 ├── runs/ │ └── {YYYYMMDD}-{HHMMSS}-{random}/ │ ├── program.prose # 正在运行的程序副本 │ ├── state.md # 带代码片段的执行状态 │ ├── bindings/ │ │ ├── {name}.md # 根作用域绑定 │ │ └── {name}__{execution_id}.md # 作用域绑定块调用 │ ├── imports/ │ │ └── {handle}--{slug}/ # 嵌套程序执行递归同构 │ └── agents/ │ └── {name}/ │ ├── memory.md # Agent 当前状态 │ ├── {name}-001.md # 历史分段扁平存放 │ ├── {name}-002.md │ └── ... └── agents/ # 项目级 Agent 记忆 └── {name}/ ├── memory.md ├── {name}-001.md └── ... # 用户级状态位于主目录 ~/.prose/ └── agents/ # 用户级 Agent 记忆跨项目 └── {name}/ ├── memory.md ├── {name}-001.md └── ...2.1 Run ID 格式每次运行占用一个以时间戳加随机数命名的目录格式{YYYYMMDD}-{HHMMSS}-{random6} 示例20260115-143052-a7b3c9注意刻意不带 run- 前缀——目录名本身就足以表达上下文。2.2 Agent 记忆分段编号分段segment文件使用 3 位零填充编号captain-001.md、captain-002.md等。当某个 Agent 超过 999 段时扩展到 4 位captain-1000.md。3. 文件格式详解3.1.prose/.env简单键值配置.prose/.env采用最简单的keyvalue格式原文档示例OPENPROSE_TELEMETRYenabled USER_IDuser-a7b3c9d4e5f6 SESSION_IDsess-1704326400000-x9y8z7选择这种格式的理由是自明self-evident、无需 JSON 解析、开发者熟悉。实验性的 PostgreSQL 状态模式同样从这里读取连接串例如OPENPROSE_POSTGRES_URL见 SKILL.md。3.2state.md用带注释的代码片段标记执行位置state.md是执行状态的核心文件。它用带注释的代码片段呈现程序当前位置使执行到哪、发生过什么一目了然。关键约束只有 VM 写这个文件子 Agent 永远不修改state.md。文件格式包含四个部分已执行代码的完整历史带行内注释用状态标记清晰标出的当前位置当前位置之后约 5~10 行即将执行的内容所有 bindings 与 agents 及其文件路径的索引。原文档给出的完整示例# Execution State run: 20260115-143052-a7b3c9 program: feature-implementation.prose started: 2026-01-15T14:30:52Z updated: 2026-01-15T14:35:22Z ## Execution Trace prose agent researcher: model: sonnet prompt: You research topics thoroughly agent captain: model: opus persist: true prompt: You coordinate and review let research session: researcher # -- bindings/research.md prompt: Research AI safety parallel: a session Analyze risk A # -- bindings/a.md (complete) b session Analyze risk B # -- EXECUTING loop until **analysis complete** (max: 3): # [not yet entered] session Synthesize context: { a, b, research } resume: captain # [...next...] prompt: Review the synthesis context: synthesis ## Active Constructs ### Parallel (lines 14-16) - a: complete - b: executing ### Loop (lines 18-21) - status: not yet entered - iteration: 0/3 - condition: **analysis complete** ## Index ### Bindings | Name | Kind | Path | Execution ID | | -------- | ---- | ------------------------ | ------------ | | research | let | bindings/research.md | (root) | | a | let | bindings/a.md | (root) | | result | let | bindings/result__43.md | 43 | ### Agents | Name | Scope | Path | | ------- | --------- | --------------- | | captain | execution | agents/captain/ | ## Call Stack | execution_id | block | depth | status | | ------------ | ------- | ----- | --------- | | 43 | process | 3 | executing | | 42 | process | 2 | waiting | | 41 | process | 1 | waiting |行内注释状态标记含义如下注释含义# -- bindings/name.md输出已写入该文件# -- EXECUTING当前正在执行此语句# (complete)语句已成功完成# [not yet entered]该块尚未到达# [...next...]接下来将执行# -- RETRYING (attempt 2/3)正在进行重试从源码结构看Call Stack 中的execution_id、block、depth、status字段与 prose.md 的栈帧结构一一对应每次块调用获得一个从 1 开始单调递增、运行内不复用的execution_id根作用域概念上为 0文件系统后端把根作用域表现为不带后缀与数据库后端用NULL表示的约定保持一致。3.3bindings/{name}.md命名值全部落盘所有命名值input、output、let、const都存为 binding 文件。原文档示例# research kind: let source: prose let research session: researcher prompt: Research AI safety --- AI safety research covers several key areas including alignment, robustness, and interpretability. The field has grown significantly since 2020 with major contributions from...文件结构固定为四段以绑定名开头的标题标明类型的kind:字段展示来源的source:代码片段---分隔线之下是实际值。kind字段的取值Kind含义input从调用方接收的值output将返回给调用方的值let可变变量const不可变变量3.4 匿名会话绑定没有显式let x ...捕获的会话依然会产生结果session Analyze the codebase # 无 let x ... 捕获这类会话的输出会被自动命名为anon_前缀的文件bindings/anon_001.md、bindings/anon_002.md等。由此保证所有会话输出都被持久化且可检查。3.5 作用域绑定块调用下的防冲突命名当一个绑定创建在块调用block invocation内部时它被限定在该执行帧内以防止递归调用之间相互覆盖。命名规则为{name}__{execution_id}.md示例bindings/result__43.md— execution_id 43 中的绑定resultbindings/parts__44.md— execution_id 44 中的绑定parts。带执行作用域的文件格式# result kind: let execution_id: 43 source: prose let result session Process chunk --- Processed chunk into 3 sub-parts...作用域解析顺序VM 解析变量引用时依次检查{name}__{current_execution_id}.md{name}__{parent_execution_id}.md沿调用栈继续向上{name}.md根作用域第一个命中者生效。递归调用场景下的目录示例bindings/ ├── data.md # 根作用域输入 ├── result__1.md # 第一次 process() 调用 ├── parts__1.md # 第一次调用产生的 parts ├── result__2.md # 递归调用深度 2 ├── parts__2.md # 深度 2 产生的 parts ├── result__3.md # 递归调用深度 3 └── ...这一设计在语言规范中有直接依据。compiler.md 的扁平命名空间要求解释了原因由于绑定以bindings/{name}.md形式存储同名变量在文件系统中会物理冲突因此编译器强制一个程序内变量名唯一、禁止跨作用域遮蔽唯一的例外是导入的程序运行在隔离命名空间——主程序的result与导入程序的result写入不同的imports/{handle}--{slug}/bindings/目录互不冲突。3.6 Agent 记忆文件agents/{name}/memory.md当前累积状态# Agent Memory: captain ## Current Understanding The project is implementing a REST API for user management. Architecture uses Express PostgreSQL. Test coverage target is 80%. ## Decisions Made - 2026-01-15: Approved JWT over session tokens (simpler stateless auth) - 2026-01-15: Set 80% coverage threshold (balances quality vs velocity) ## Open Concerns - Rate limiting not yet implemented on login endpoint - Need to verify OAuth flow works with new token formatagents/{name}/{name}-NNN.md历史分段每次resume:调用的历史记录扁平地存放在同一目录# Segment 001 timestamp: 2026-01-15T14:32:15Z prompt: Review the research findings ## Summary - Reviewed: docs from parallel research session - Found: good coverage of core concepts, missing edge cases - Decided: proceed with implementation, note gaps for later - Next: review implementation against identified gaps4. 写入权责谁写哪个文件原文档定义了严格的写入分工文件写入者state.md仅 VMbindings/{name}.md子 Agentagents/{name}/memory.md持久化 Agentagents/{name}/{name}-NNN.md持久化 Agent分工背后的设计是VM 负责编排子 Agent 直接把输出写到文件系统。VM 从不持有完整的绑定值——它只追踪文件路径。prose.md 进一步把这上升为关键设计VM 只记录位置并传递引用不读取完整绑定——这使得 VM 的上下文保持精简也允许中间值任意大。5. 子 Agent 输出写入协议当 VM 派生一个会话时它会告知子 Agent 输出应写到哪里。5.1 普通会话VM 在派生提示中附带写入指令与格式模板When you complete this task, write your output to: .prose/runs/20260115-143052-a7b3c9/bindings/research.md Format: # research kind: let source: prose let research session: researcher prompt: Research AI safety --- [Your output here]5.2 持久化 Agentresume:Your memory is at: .prose/runs/20260115-143052-a7b3c9/agents/captain/memory.md Read it first to understand your prior context. When done, update it with your compacted state following the guidelines in primitives/session.md. Also write your segment record to: .prose/runs/20260115-143052-a7b3c9/agents/captain/captain-003.md这里的压缩compaction规范由子 Agent 侧文档 session.md 定义——该文档会被载入每一个子 Agent 会话指导其理解外层状态、自身记忆与任务上下文三层信息。5.3 子 Agent 返回给 VM 的只是确认消息写完输出后子 Agent 返回确认消息而非完整内容。根作用域块调用之外Binding written: research Location: .prose/runs/20260115-143052-a7b3c9/bindings/research.md Summary: AI safety research covering alignment, robustness, and interpretability with 15 citations.块调用之内需附带 execution_idBinding written: result Location: .prose/runs/20260115-143052-a7b3c9/bindings/result__43.md Execution ID: 43 Summary: Processed chunk into 3 sub-parts for recursive processing.VM 随后记录位置并继续执行——它不读取该文件只是把引用传递给后续需要该上下文的会话。6. Imports 的递归同构结构被导入的程序使用同一套统一结构递归展开.prose/runs/{id}/imports/{handle}--{slug}/ ├── program.prose ├── state.md ├── bindings/ │ └── {name}.md ├── imports/ # 更深层的导入放这里 │ └── {handle2}--{slug2}/ │ └── ... └── agents/ └── {name}/由此可以在保持每一层结构一致的前提下实现任意嵌套深度配合第 3.5 节提到的导入程序隔离命名空间规则形成层次化的状态隔离。7. 持久化 Agent 的记忆作用域persist属性决定 Agent 记忆的落盘位置与生命周期与 compiler.md 中的定义一致作用域声明方式路径生命周期Execution默认persist: true.prose/runs/{id}/agents/{name}/随运行消亡Projectpersist: project.prose/agents/{name}/在项目中跨运行存活Userpersist: user~/.prose/agents/{name}/跨项目存活Custompersist: path指定路径用户自行控制对应声明示例# 运行级持久化记忆随 run 消亡 agent captain: model: opus persist: true prompt: You coordinate and review # 项目级持久化记忆跨 run 存活 agent advisor: model: opus persist: project prompt: You provide architectural guidance # 自定义路径 agent shared: model: opus persist: .prose/custom/shared-agent/ prompt: Shared across programs8. VM 更新协议与执行恢复8.1 每条语句之后的更新三步每条语句完成后VM 执行确认子 Agent 已写出其输出文件更新state.md写入新位置与新注释继续下一条语句。其中压缩上下文这一动作 VM 从不做——那是子 Agent 自身职责。8.2 恢复中断的执行若执行被中断恢复流程为读取.prose/runs/{id}/state.md定位当前位置从bindings/加载全部绑定从被标记的位置继续执行。state.md中包含了理解执行停在哪里、已经完成了什么所需的一切——这正是目录结构即执行状态原则的落地。9. 源码级佐证状态文件如何被仓库内工具消费文件系统状态并非只是设计文档仓库中的 OpenProse 技能库lib/目录已把它当作可查询的数据源error-forensics.prose 的 investigator Agent 指令明确写着读取 state.md 查看执行轨迹并把调查顺序定为state.md执行轨迹、停在哪→bindings/哪些绑定存在、有无错误或空值inspector.prose、profiler.prose 等库程序同样通过解析state.md、bindings/例如正则/bindings/([^.])\.md提取绑定名来生成运行检查与性能画像。这说明文件即状态的可检查性直接转化为可组合的诊断能力任何.prose程序都可以把.prose/runs/{id}/当作输入来做回顾分析。10. 与 in-context 状态的选型边界原文档将 filesystem 与 in-context.md 定位为二选一的独立方案而非互补——应在程序开始时选定模式。in-context 文档给出了量化选型表可直接用于决策因素用 in-context改用 filesystem语句数 30 条 30 条并行分支 5 个并发 5 个并发导入程序0–2 个 3 个嵌套深度 2 层 2 层预期时长 5 分钟 5 分钟另一个关键差异是上下文传递语义in-context 状态传值不传引用VM 直接在对话历史中持有绑定值且按 2000 / 2000–8000 / 8000 字符分档处理上下文大小因此无法支持 RLM 式环境即变量的大绑定查询而 filesystem 状态传引用不传值中间值可以任意大。这也解释了为什么 SKILL.md 把 filesystem 设为加载 VM 时的默认状态文档。11. 实践入口在 OpenClaw 中启用并查看状态OpenProse 以插件形式随仓库发布见 open-prose/README.md 与 index.ts启用后即可通过/prose斜杠命令执行.prose程序。按 README 说明内置插件默认关闭需在配置中启用open-prose条目并重启 Gateway。启用后运行一个.prose程序技能包内置了从01-hello-world.prose到49-prose-run-retrospective.prose的完整示例集位于 examples 目录你可以在工作目录下观察.prose/runs/中按时间戳新建的运行目录内含program.prose、state.md、bindings/、agents/子树state.md中# -- EXECUTING标记随执行推进的位移递归块调用产生的bindings/{name}__{execution_id}.md系列文件持久化 Agent 的memory.md与递增的{name}-NNN.md分段记录。调试中断或失败运行时可直接对照第 8.2 节的三步恢复流程操作或参照lib/error-forensics.prose的state.md → bindings/调查顺序手工排查。适用前提与限制以上结构与协议以当前仓库open-prose/skills/prose/state/filesystem.md及同目录 prose.md、compiler.md、SKILL.md 的现行内容为准sqlite 与 postgres 属于文档标注的实验性模式不在本文讨论范围。filesystem 状态模式下VM 只传引用的特性使中间结果理论上可以任意大但也意味着排查问题必须回到文件本身——这正是该方案把可检查性放在第一优先级的取舍所在。赞分享人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载相关推荐OpenClaw OpenProse 文件系统状态管理实战解析用 .prose 目录支撑可检查、可恢复、可长时间运行的 AI 工作流OpenClaw OpenProse 文件系统状态管理实战解析用 .prose 目录支撑可检查、可恢复、可长时间运行的 AI 工作流 导读 本文以 OpenC人工智能大模型LLM 网关AI Agent即时通讯OpenProse 程序状态管理实战基于 PostgreSQL 的并发写入、团队协作与可查询执行状态openclaw-zero-token 仓库OpenProse 程序状态管理实战基于 PostgreSQL 的并发写入、团队协作与可查询执行状态openclaw zero token 仓库 本文面向人工智能大模型LLM 网关AI Agent即时通讯OpenClaw 中的 OpenProse用 .prose 文件编排多智能体工作流插件安装、VM 执行模型与状态存储全指南OpenClaw 中的 OpenProse用 .prose 文件编排多智能体工作流插件安装、VM 执行模型与状态存储全指南 OpenProse 是一种可移人工智能大模型LLM 网关AI Agent即时通讯上一篇Stable-Worldmodel中的约束规划如何使用LagrangianSolver解决复杂任务约束下一篇Soundflower完整指南解锁Mac音频路由的高效方法创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考