Usage Guides
使用与协作指南
面向日常 CLI 用户与 AI 编程助手的实战经验,每一节都可以按需单独查阅。如果你正在开发自有后端直接调用 HTTP 接口,另请参阅 底层 REST API 中的幂等重试与错误码章节。
1. 怎么写出一句高质量的记忆
单条记忆支持最长 8192 字节。以下几条写作习惯能显著提升后台结构化与后续召回的准确度:
| 场景 | 推荐做法 |
|---|---|
| 记录对话或偏好 | 直接保留原句,不要让模型先改写成模糊摘要——人名、项目名、地点和时间词是精准归档的关键。 |
| 一次包含多件独立变化 | 拆成多条 world remember 写入,让每件事实拥有清晰的独立发生时间。 |
| 相对时间词 | 保留「昨天」「上个月」「上周五」等原样表达,不要手工换算成模糊日期,world 会自动附带本机时区交由云端准确解析。 |
使用 --source 与 --meta | --source 适合标记来源(如 agent、meeting),--meta k=v 仅随原文留档,不会出现在召回结果里也不参与检索;需要能搜到的关键信息请直接写进正文。 |
2. 处理历史日期与时区
实时记录当下发生的事情时,直接运行 world remember "..." 即可,无需手动传时间。只有在补录过去某一天发生的事件时,再显式加上 --occurred-at:
Historical Entry
# 补录一条过去的明确事件(CLI 自动识别常见日期格式) world remember "项目架构评审通过,确定采用 Go 编写核心引擎。" \ --occurred-at "2025-10-01" \ --timezone "Asia/Shanghai" \ --source decision
不要用未来时间记录「待办预约」。事件发生时间允许的上限是当前时间加 24 小时,超出会被拒绝。要记录未来的计划,按当前时间写进自然语言正文即可(例如「计划下周五上线 v1.2」)。
3. 写错了某句话如何更正?
World Machine 的原文记录是只追加的,没有「删改单条历史原话」的操作。如果之前记错了一条信息,正确做法是直接再记一条清晰的更正陈述:
Correction
# 不需要删旧记录,直接追加一条更正陈述即可 world remember "更正:Atlas 项目的交付日期已经调整到 12 月 20 日,不再是 12 月 15 日。" --source decision
旧原话仍保留在历史记录中可供审计,而实体当前状态会自动演进为最新的更正结论。
4. 多设备、远程 SSH 与多配置管理
- 多台电脑共用同一账号:在每台机器分别运行一次
world auth login,建议在控制台授权页用设备名(如macbook-pro、linux-workstation)区分密钥,方便日后单独撤销。 - 远程 SSH 或无桌面服务器:运行
world auth login --no-browser,在本地浏览器完成确认后,复制页面给出的world auth login --api-key "..."回到远程终端执行即可。 - 区分个人与工作账号:使用
world config set profile创建并切换不同的配置档:
Profiles
# 切换到名为 work 的配置档并授权工作账号 world config set profile work world auth login # 单次命令临时覆盖配置档 WORLD_PROFILE=default world recall "个人偏好"
5. 让 AI 助手召回更精准
当你在自定义脚本、Hook 或 Agent 工作流里调用 world recall 时,建议做好三件事:
Agent Recall
# Agent / 脚本调用时加 --json 并限制返回数量,避免上下文膨胀 world recall "当前项目的技术选型与约定" --max-entities 8 --max-events 10 --json
- 始终加
--json:让模型直接读取结构化实体、生效时间与epistemicStatus,比解析纯文本更稳定。 - 按需收紧
--max-entities/--max-events:默认各返回最多 20 条;日常编码或问答通常设 5–10 条就足够精准且省 Token。 - 区分「现在」与「过去」:当用户问「上个月」「去年」的状态时,务必传
--as-of,不要让模型自己对着当前状态硬猜过去。
6. 安全与密钥管理清单
| 检查项 | 推荐实践 |
|---|---|
| 绝不提交本地配置 | ~/.config/world/config.json 和 WORLD_API_KEY 仅留在本机或受保护的环境变量中,切勿写入 Git 仓库或聊天记录 |
| 按设备独立签发密钥 | 每个终端或应用各自使用独立命名的 API 密钥,离职、换机或怀疑泄漏时立即在 控制台 一键撤销 |
| 谨慎看待口述声明 | 涉及资金、权限或生产变更前,提醒 Agent 对 stated_claim 级别的历史记忆做二次确认 |