当前正式版本
v0.1.132026-03-30，当前仓库 changelog 里的最新正式公开发布。
首条成功链路
安装 → provider → doctor → 首次调用普通用户不应该先研究内部架构。
主产品逻辑
同一运行时，多种表面CLI、JSON、RPC 和原生桌面都来自同一套 maoclaw runtime。
当前升级线
原生控制面 + docs + website当前构建正围绕桌面控制面、文档和网站发布表面对齐。
使用路径
普通用户只需要先回答“我现在要做什么”
CLI one-shot
先用单次调用拿到总结、风险或解释，不要一上来就进入复杂编排。
先做： pi -p "总结这个仓库"
适合- 仓库总结
- 错误解释
- 快速结构化输出
不适合： 你已经知道这会变成长会话。
CLI interactive session
当任务需要连续上下文时，再进入会话模式。
先做： pi，然后用 pi --continue
适合- 连续修复
- 重构
- 多轮任务推进
不适合： 你只需要一个答案。
Native desktop
原生桌面版适合非终端优先用户，但仍然是同一 runtime。
先做： 先保存一个 provider，再检查本地运行时状态
适合- 图形化设置
- 本地 bridge 检查
- 原生会话入口
不适合： 你需要无头脚本化执行。
RPC mode
只有当你真的需要会话、事件和客户端控制时，才进入 RPC。
先做： pi --mode rpc
适合- IDE 前端
- 桌面壳层
- 编排器
不适合： JSON 一次调用已经足够。
JSON mode
简单脚本和流水线优先 JSON，而不是先做长连接。
先做： pi --mode json -p "返回结构化结果"
适合- CI
- 脚本
- 轻量自动化包装
不适合： 你的客户端需要持续状态。
Settings + skills
先把 provider、模型和主路径跑稳，再引入 skills 和 prompts。
先做： 先稳定 `.pi/settings.json`，再加 `.pi/skills/`
适合- 团队默认值
- 项目级行为复用
- 可治理扩展
不适合： 环境、PATH 或 auth 还没跑通。
配置梯度
个人 / 首次使用
- 用 install.sh 安装或打开原生桌面版。
- 只配置一个 provider 和一个默认模型。
- 先跑 `pi doctor`、`pi --list-providers`、`pi --list-models`。
- 完成一次真实调用后再进入 continue 或 desktop 工作流。
配置梯度
团队 / 长期使用
- 把项目默认值写进 `.pi/settings.json`。
- 把 repo 级 skills 当成第二层，而不是第一层。
- 需要客户端时再接 RPC，不要过早自建控制面。
- 把 changelog、upgrade log 和网站说明保持同一版本线。
沟通规则
公开使用说明必须遵守的规则
- 不要把桌面版和 CLI 讲成两套产品。
- 不要把当前构建升级说成已经正式发布。
- 不要在环境问题没解决前，把问题归因到 prompt。
- 不要让普通用户先读内部规划文档。
- 不要在 JSON 一次调用就足够时，一开始就进入 RPC。
权威来源
公开对外应以这些文件为准
正式发布以此为准。
CHANGELOG.md当前构建升级线和更宽的升级脉络在这里。
UPGRADE_LOG.md帮助普通用户分清正式发布和当前构建升级。
docs/i18n/en/release-and-upgrades.md