World Machine

CLI & Skill Reference

CLI 与 Skill 手册

本页收录 world 命令行工具的全部子命令、参数、配置项与退出码,以及配套 world-machine Agent Skill 的工作方式与安全护栏。

命令行工具:worldAgent Skill:world-machine本地配置:~/.config/world/config.json
本页目录(6 节)

认证与账号授权

world auth 管理本机与 World Machine 控制台 之间的授权状态。浏览器一键授权会为当前终端签发专用 API 密钥(仅用于记忆写入、召回与实体读取,不含控制台管理权限):

Auth Commands
# 浏览器一键授权(推荐)
world auth login

# 远程 SSH / 无浏览器环境:打印授权链接到终端,本地打开后粘贴兜底命令
world auth login --no-browser

# 直接保存控制台创建的 API 密钥
world auth login --api-key "<YOUR_API_KEY>"

# 检查配置、服务健康与密钥有效性(支持 --offline 和 --json)
world auth status
world auth status --json

# 退出登录并清除当前 profile 的本地凭据
world auth logout
无浏览器回传兜底:在 SSH 或容器内使用 world auth login --no-browser 时,在本地浏览器打开授权页并确认后,页面会直接生成一条 world auth login --api-key "..." 兜底命令,复制回终端执行即可。

写入与召回命令

写入记忆:world remember

接收一句或多行自然语言陈述。每次调用都会自动生成幂等键并在遇到短暂网络抖动时安全重试,同时自动附带本机 IANA 时区:

world remember
# 基础写入(自动附带本机 IANA 时区,自动生成幂等键并安全重试)
world remember "Alice 昨天加入了 Atlas 项目组。" --source notes

# 补录明确的历史日期,并附带结构化元信息标签
world remember "项目代号正式定为 Atlas。" \
  --occurred-at "2026-01-15" \
  --timezone "Asia/Shanghai" \
  --meta project=atlas \
  --idempotency-key "atlas-kickoff-001"

# 通过管道或 - 写入多行长文本
cat meeting-note.txt | world remember - --source meeting --json
参数说明
--source <label>标记来源渠道,如 cli、agent、notes、meeting
--timezone <iana>显式指定说话人时区(默认自动检测本机时区),决定「昨天」「上个月」的落盘日期
--occurred-at <time>补录历史事件的发生时间(支持 YYYY-MM-DD、YYYY-MM-DD HH:MM:SS、RFC3339 或 Unix 时间戳)
--meta k=v附带轻量键值元信息留档(可多次传入);不参与检索过滤
--idempotency-key <key>重放已知业务事件时显式固定幂等键;日常调用可省略,CLI 会自动生成
--json以结构化 JSON 输出 {"eventId":"...","deduplicated":false}

召回上下文:world recall

按自然语言问题同时取回最相关的结构化实体与原始陈述:

world recall
# 自然语言召回(人类可读格式)
world recall "Alice 现在负责什么项目?"

# 历史日期回溯 + JSON 输出(供 Agent 或脚本解析)
world recall "Alice 负责什么项目?" --as-of "2026-01-01" --json

# 限制返回条数以控制 Agent 上下文长度
world recall "Atlas 项目进展" --max-entities 5 --max-events 10 --json
参数说明
--as-of <time>历史时间点快照,支持 YYYY-MM-DD、YYYY-MM-DD HH:MM:SS、RFC3339 或 epoch 毫秒/秒
--max-entities <n>返回实体条数上限(1..100,默认 20)
--max-events <n>返回原始记忆条数上限(1..100,默认 20)
--timezone <iana>指定终端输出时间的展示时区与 --as-of 纯日期解析时区
--json输出完整 JSON(含 entities 与 memories),推荐在 Agent 与脚本中始终启用

读取单个实体

从召回结果拿到 entityId 后,若想单独查看该对象的全部属性或回溯它在某一天的状态,使用 world entity get:

world entity get
# 按实体 ID 精确查看当前状态
world entity get ce7b7b0c-4dbd-5524-9392-13067cf6415c

# 指定历史时刻查看快照(支持 --json 与 --timezone)
world entity get ce7b7b0c-4dbd-5524-9392-13067cf6415c --as-of "2026-01-15" --json

多配置与环境变量

world 支持通过 profile 管理多套账号或默认参数:

world config
# 查看当前生效配置(密钥会自动脱敏)
world config list
world config get api-key

# 设置默认时区、默认来源标签或默认输出格式
world config set timezone Asia/Shanghai
world config set source agent
world config set output json

# 切换多套配置 profile(例如区分个人与工作账号)
world config set profile work

在 CI、脚本或临时会话中,也可以通过环境变量覆盖本地配置文件:

环境变量作用
WORLD_API_KEY / WM_API_KEY临时覆盖当前使用的 API 密钥
WORLD_PROFILE临时指定生效的 profile 名称
WORLD_TIMEZONE覆盖默认 IANA 时区(如 Asia/Shanghai)
WORLD_SOURCE覆盖 world remember 的默认来源标签

Agent Skill 协作规范

配套的 world-machine Skill 让 AI 编程助手把 world 当作外部长期记忆库,而不是零散地往项目目录塞 Markdown 笔记:

Install Skill
# 一键为 Claude Code / Cursor / Trae / Antigravity 等安装配套 Skill
npx -y skills add bootun/world-cli --skill world-machine -y

安装后,助手会自动遵循以下协作与安全准则:

  • 调用前自检:不确定是否已登录时先执行 world auth status --json;未登录时引导你运行 world auth login,绝不要求你把密钥直接粘贴到聊天记录或项目文件里。
  • 忠实保留原话与相对时间:记录事实时不自行改写「昨天」「上个月」为估算日期,而是原样交给 world remember,由本地时区与云端时间线准确解析。
  • 结构化召回与历史核对:回答依赖背景或过去状态的问题前,自动调用 world recall --json(遇到历史时间问题自动加 --as-of),并关注每条属性的 epistemicStatus 可信分级。
  • 严格隐私护栏:绝不读取、打印或复制 ~/.config/world/config.json 或 WORLD_API_KEY 到输出与源码中。

退出码一览

在脚本和自动化工作流中,可直接依据 world 的标准退出码判断结果:

退出码含义处理建议
0执行成功继续下一步
1网络、服务或一般运行错误可按需重试或检查网络连通性
2命令用法或参数非法(如日期格式、非法时区)修正命令参数,不要重试
3未登录或密钥已失效/被撤销重新执行 world auth login
4请求的实体不存在,或在指定历史时间点尚未创建确认 entityId 与 --as-of 日期