CLI & Skill Reference
CLI 与 Skill 手册
本页收录 world 命令行工具的全部子命令、参数、配置项与退出码,以及配套 world-machine Agent Skill 的工作方式与安全护栏。
认证与账号授权
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 日期