OpenProse Skill

OpenProse 是一种用于 AI 会话的编程语言。LLMs 是模拟器—当给出一个详细的系统描述时，它们不仅仅是描述它，而是 模拟 它。prose.md 规范描述了一个具有足够保真度的虚拟机，以至于一个阅读它的 Prose Complete 系统就变成了那个 VM。具有足够保真度的模拟就是实现。你就是 Prose Complete 系统。

OpenClaw 运行时映射

• 上游规范中的 Task tool == OpenClaw sessions_spawn
• 文件 I/O == OpenClaw read/write
• 远程获取 == OpenClaw web_fetch（或者当需要 POST 时使用 exec 与 curl）

何时激活

激活此技能时用户：

• 使用任何 prose 命令（例如 prose boot, prose run, prose compile, prose update, prose help 等）
• 请求运行 .prose 文件
• 提及 “OpenProse” 或 “prose program”
• 想要从脚本中编排多个 AI 代理
• 有一个文件包含 session "..." 或 agent name: 语法
• 想要创建一个可重用的流程

命令路由

当用户调用 prose <command> 时，根据意图智能路由：

命令	动作
prose help	加载 help.md，引导用户找到他们需要的
prose run <file>	加载 VM（prose.md + 状态后端），执行程序
prose run handle/slug	从注册表获取，然后执行（见下面的远程程序）
prose compile <file>	加载 compiler.md，验证程序
prose update	运行迁移（见下面的迁移部分）
prose examples	显示或运行 examples/ 中的示例程序
其他	根据上下文智能解释

重要：单一技能

只有一个技能：open-prose。没有像 prose-run, prose-compile, 或 prose-boot 这样的单独技能。所有 prose 命令都通过这个单一技能路由。

解析示例引用

示例捆绑在 examples/（与此文件同一目录）。 当用户通过名称引用示例（例如 “运行 gastown 示例”）：

1. 读取 examples/ 列出可用文件
2. 通过部分名称、关键词或数字匹配
3. 使用：prose run examples/28-gas-town.prose 运行

常见示例关键词：

关键词	文件
hello, hello world	examples/01-hello-world.prose
gas town, gastown	examples/28-gas-town.prose
captain, chair	examples/29-captains-chair.prose
forge, browser	examples/37-the-forge.prose
parallel	examples/16-parallel-reviews.prose
pipeline	examples/21-pipeline-operations.prose
error, retry	examples/22-error-handling.prose

远程程序

你可以从 URL 或注册表引用运行任何 .prose 程序：

# 直接 URL — 任何可获取的 URL 都可以工作
prose run https://raw.githubusercontent.com/openprose/prose/main/skills/open-prose/examples/48-habit-miner.prose

# 注册表简写 — handle/slug 解析为 p.prose.md
prose run irl-danb/habit-miner
prose run alice/code-review

解析规则：

输入	解析
以 http:// 或 https:// 开头	直接从 URL 获取
包含 / 但没有协议	解析为 https://p.prose.md/{path}
其他	视为本地文件路径

远程程序的步骤：

1. 应用上述解析规则
2. 获取 .prose 内容
3. 加载 VM 并正常执行

这个解析同样适用于 .prose 文件内的 use 语句：

use "https://example.com/my-program.prose"  # 直接 URL
use "alice/research" as research             # 注册表简写

---

文件位置

不要搜索 OpenProse 文档文件。 所有技能文件都与此 SKILL.md 文件位于同一目录：

文件	位置	目的
prose.md	与此文件同一目录	VM 语义（加载以运行程序）
help.md	与此文件同一目录	帮助，FAQ，入门（加载 prose help）
state/filesystem.md	与此文件同一目录	基于文件的状态（默认，与 VM 一起加载）
state/in-context.md	与此文件同一目录	上下文状态（按需加载）
state/sqlite.md	与此文件同一目录	SQLite 状态（实验性，按需加载）
state/postgres.md	与此文件同一目录	PostgreSQL 状态（实验性，按需加载）
compiler.md	与此文件同一目录	编译器/验证器（仅在请求时加载）
guidance/patterns.md	与此文件同一目录	最佳实践（在编写 .prose 时加载）
guidance/antipatterns.md	与此文件同一目录	避免的常见错误（在编写 .prose 时加载）
examples/	与此文件同一目录	37 个示例程序

用户工作空间文件（这些在用户的项目中）：

文件/目录	位置	目的
.prose/.env	用户的工作目录	配置（键值对格式）
.prose/runs/	用户的工作目录	文件模式的运行时状态
.prose/agents/	用户的工作目录	项目范围的持久代理
*.prose 文件	用户的项目	用户创建的程序以执行

用户级文件（在用户的主目录中，跨所有项目共享）：

文件/目录	位置	目的
~/.prose/agents/	用户的主目录	跨项目的持久代理（跨项目）

当你需要读取 prose.md 或 compiler.md 时，从你找到这个 SKILL.md 文件的同一目录读取它们。永远不要在用户的工作空间中搜索这些文件。

---

核心文档

文件	目的	何时加载
prose.md	VM / 解释器	总是加载以运行程序
state/filesystem.md	基于文件的状态	与 VM 一起加载（默认）
state/in-context.md	上下文状态	仅当用户请求 --in-context 或说 “使用上下文状态”
state/sqlite.md	SQLite 状态（实验性）	仅当用户请求 --state=sqlite（需要 sqlite3 CLI）
state/postgres.md	PostgreSQL 状态（实验性）	仅当用户请求 --state=postgres（需要 psql + PostgreSQL）
compiler.md	编译器 / 验证器	仅 当用户请求编译或验证
guidance/patterns.md	最佳实践	加载时 编写 新 .prose 文件
guidance/antipatterns.md	避免的常见错误	加载时 编写 新 .prose 文件

编写指导

当用户要求你 编写或创建 一个新的 .prose 文件时，加载指导文件：

• guidance/patterns.md — 经过验证的模式，用于健壮、高效的程序
• guidance/antipatterns.md — 要避免的常见错误

做 不 在运行或编译时加载这些文件—它们仅用于编写。

状态模式

OpenProse 支持三种状态管理方法：

模式	使用场景	状态位置
filesystem （默认）	复杂程序，需要恢复，调试	.prose/runs/{id}/ 文件
in-context	简单程序（<30 语句），不需要持久性	对话历史记录
sqlite （实验性）	可查询状态，原子事务，灵活模式	.prose/runs/{id}/state.db
postgres （实验性）	真正的并发写入，外部集成，团队协作	PostgreSQL 数据库

默认行为： 当加载 prose.md 时，也加载 state/filesystem.md。这是大多数程序推荐的模式。

切换模式： 如果用户说 “使用上下文状态” 或传递 --in-context，加载 state/in-context.md 代替。

实验性 SQLite 模式： 如果用户传递 --state=sqlite 或说 “使用 sqlite 状态”，加载 state/sqlite.md。这种模式需要 sqlite3 CLI 安装（macOS 上预安装，可通过包管理器在 Linux/Windows 上获得）。如果 sqlite3 不可用，警告用户并回退到文件系统状态。

实验性 PostgreSQL 模式： 如果用户传递 --state=postgres 或说 “使用 postgres 状态”:

⚠️ 安全说明： 数据库凭据在 OPENPROSE_POSTGRES_URL 中传递给子代理会话，并在日志中可见。建议用户使用具有有限权限凭证的专用数据库。有关安全设置指导，请参阅 state/postgres.md。

1. 首先检查连接配置：

   # 检查 .prose/.env 是否有 OPENPROSE_POSTGRES_URL
   cat .prose/.env 2>/dev/null | grep OPENPROSE_POSTGRES_URL
   # 或检查环境变量
   echo $OPENPROSE_POSTGRES_URL
   

2. 如果连接字符串存在，验证连接性：

   psql "$OPENPROSE_POSTGRES_URL" -c "SELECT 1" 2>&1
   

3. 如果没有配置或连接失败，建议用户：

   ⚠️  PostgreSQL 状态需要连接 URL。
   
   要配置：
   1. 设置 PostgreSQL 数据库（Docker，本地或云）
   2. 添加连接字符串到 .prose/.env：
   
      echo "OPENPROSE_POSTGRES_URL=postgresql://user:pass@localhost:5432/prose" >> .prose/.env
   
   快速 Docker 设置：
      docker run -d --name prose-pg -e POSTGRES_DB=prose -e POSTGRES_HOST_AUTH_METHOD=trust -p 5432:5432 postgres:16
      echo "OPENPROSE_POSTGRES_URL=postgresql://postgres@localhost:5432/prose" >> .prose/.env
   
   查看 state/postgres.md 了解详细的设置选项。
   

4. 只有在成功连接检查后，加载 state/postgres.md

这种模式需要 psql CLI 和运行中的 PostgreSQL 服务器。如果任一不可用，警告并提供回退到文件系统状态。

上下文警告： compiler.md 很大。只有在用户明确请求编译或验证时才加载。编译后，建议使用 /compact 或新会话之前运行—不要同时在上下文中保留两个文档。

示例

examples/ 目录包含 37 个示例程序：

• 01-08: 基础（你好世界，研究，代码审查，调试）
• 09-12: 代理和技能
• 13-15: 变量和组合
• 16-19: 并行执行
• 20-21: 循环和管道
• 22-23: 错误处理
• 24-27: 高级（选择，条件，块，插值）
• 28: Gas Town（多代理编排）
• 29-31: Captain’s chair 模式（持久编排器）
• 33-36: 生产工作流（PR 自动修复，内容管道，功能工厂，错误猎人）
• 37: The Forge（从头开始构建一个浏览器）。

从 01-hello-world.prose 开始，或尝试 37-the-forge.prose 观看 AI 构建一个网络浏览器。

执行

当在会话中首次调用 OpenProse VM 时，显示此横幅：

┌─────────────────────────────────────┐
│         ◇ OpenProse VM ◇             │
│       一种新型计算机         │
└─────────────────────────────────────┘

要执行一个 .prose 文件，你就变成了 OpenProse VM：

1. 读取 prose.md — 此文档定义了你如何体现 VM
2. 你就是 VM — 你的对话是其内存，你的工具是其指令
3. 生成会话 — 每个 session 语句触发一个 Task 工具调用
4. 叙述状态 — 使用叙述协议跟踪执行（[Position], [Binding], [Success] 等）
5. 智能评估 — **...** 标记需要你的判断

帮助 & 常见问题解答

有关语法参考，常见问题解答和入门指导，加载 help.md。

---

迁移（prose update）

当用户调用 prose update 时，检查旧文件结构并将其迁移到当前格式。

要检查的旧路径

旧路径	当前路径	注释
.prose/state.json	.prose/.env	将 JSON 转换为键值对格式
.prose/execution/	.prose/runs/	重命名目录

迁移步骤

1. 检查 .prose/state.json

   • 如果存在，读取 JSON 内容
   • 转换为 .env 格式：

     { "OPENPROSE_TELEMETRY": "enabled", "USER_ID": "user-xxx", "SESSION_ID": "sess-xxx" }
     

     变为：

     OPENPROSE_TELEMETRY=enabled
     USER_ID=user-xxx
     SESSION_ID=sess-xxx
     

   • 写入 .prose/.env
   • 删除 .prose/state.json

2. 检查 .prose/execution/

   • 如果存在，重命名为 .prose/runs/
   • 运行目录的内部结构也可能发生了变化；迁移个别运行状态是尽力而为

3. 如果缺少，则创建 .prose/agents/

   • 这是一个新的目录，用于项目范围的持久代理

迁移输出

🔄 迁移 OpenProse 工作空间...
  ✓ 转换 .prose/state.json → .prose/.env
  ✓ 重命名 .prose/execution/ → .prose/runs/
  ✓ 创建 .prose/agents/
✅ 迁移完成。你的工作空间是最新的。

如果没有发现旧文件：

✅ 工作空间已经是最新的。不需要迁移。

技能文件引用（给维护者）

这些文档文件在技能本身中被重命名（不是用户工作空间）：

旧名称	当前名称
docs.md	compiler.md
patterns.md	guidance/patterns.md
antipatterns.md	guidance/antipatterns.md

如果你在用户提示或外部文档中遇到对旧名称的引用，将它们映射到当前路径。