中文 | English
@wombat/cli 解析参数，输出文本或 JSON，并装配查询与本机 Web 启动。命令和参数以CLI 使用说明为准。
Agent 通过 api 发现本机方法与 Schema，通过 call 从标准输入提交单个有界 JSON 请求。请求包装从 Rust 生成，派发复用公开类型化客户端，并与普通命令共享退出码判断。语法、预算和恢复方式见 CLI 指南。
-
包根入口提供参数解析与
runUsageCli；./format提供结果文本格式化。 -
refresh、usage、threads、turns、steps、prices、optimize、timing经@wombat/client/node调用共享内核。 -
无子命令时输出用量文本，与
usage一致；web显式启动交互页面。 -
skill install/status/uninstall管理独立本机副本；正式插件由 Codex 管理。web --context FILE验证并打开同范围视图。 -
展示语言使用
@wombat/client/locale，详见产品语言与文案。
接口借鉴 Google Workspace CLI 的方法发现、MCP 的结构化工具协议与 CLI Guidelines。新增方法时遵循以下原则：
| 原则 | Wombat 实现 |
|---|---|
| 协议只有一个所有者 | Rust 定义产品参数与输出，生成类型、校验器和 Schema；CLI 不另建字段清单。 |
| 先发现，再组合 | 先读取小型本机方法清单，再按需读取单个输入 Schema；输出 Schema 可选。发现不扫描数据，也不调用模型。 |
| 上下文显式传入 | 使用准确的来源、项目、日期、时区和完整 ID；沿用返回的快照、读取版本和分页，避免隐藏会话默认值。 |
| 结构化读写有界 | 从标准输入读取单个已校验 JSON 请求，输出所属协议的单个 JSON 结果；进度写 stderr，支持取消、输入输出上限及方法自身预算。 |
| 能力完整开放 | 派发既有类型化客户端方法，允许使用全部生成参数；Skill 选择工作流，不替代完整业务接口。 |
| 保留证据语义 | 完整总量、分页行、省略详情、部分覆盖、未知和观测到的零分别表达；紧凑输出由内核投影。 |
| 恢复不靠猜测 | 稳定错误码与恢复提示指引下一次请求；视图过期须重新取得，参数变化须重新校验。超时或恢复提示不代表允许重试修改。 |
Schema 校验只证明结构有效；产品校验仍检查参数组合、授权目标和绑定版本的选择。验收应覆盖无效与不支持请求、固定版本分页、部分结果、取消和安装后的入口；模拟成功不代表真实 Agent 流程已经通过。
optimize 文本分别展示用户决定与理由、本次检查和原始检查，并直接呈现内核给出的复查可比性。保留、不适用和缺少依据均不代表问题已解决。
CLI 只负责参数、输出、进度与退出码，不计算费用或改变快照语义。JSON 进度写 stderr，结果写 stdout；按命令入口约定在构建后验证参数错误、部分结果与完整命令路径。
wombat timing（或 timing summary）要求完整任务和轮次身份，默认输出一个 JSON 对象；--text 选择本地化文本，与 --json 互斥。--share 请求内核独立的分享投影。timing evidence 要求相同目标和固定快照，通过不透明游标分页，每页 1..200 条。--collection 选择 turn_events（默认）、use_objects 或 use_records；仅 use_records 可用 --object 筛选对象，游标保持同一快照、目标和集合。使用对象的全轮次数与已关联次数分别呈现，缺少归属证据时不以零补齐；timing capabilities 不接受目标或来源路径，不执行扫描。耗时查询不触发自动补价、配置扫描、Hook 采集或账户观察。
摘要退出码依据内核质量：已检查范围完整时返回 0，即使可选值未知；部分或暂定结果返回 2，错误返回 1，取消返回 130。证据页导航和能力查询成功时返回 0，不据此推断整轮完整性。JSON 错误使用 v1 安全模板，不输出来源路径和底层错误详情。独立合成 CLI 测试不代表真实内核或浏览器验收。
本地化 --text 摘要展示内核提供的命令、压缩、推理和 MCP 区间并集与累加、已覆盖与未分类耗时及类别交集耗时，也输出工作指标：操作结果、文件变更记录和报告路径、用户输入/注入上下文/推理记录。按命令标签归类的时长当前不支持；新增和删除行数因没有历史仓库基线而未知。数值保留内核提供的状态与依据；未知不等于零。报告路径可能包含失败或拒绝等终态，不能证明文件已写入或产生净变化。用户输入计数是物理记录数，不是请求数；失败结果不判断代码缺陷。来源覆盖沿用现有来源覆盖行。
Wombat 会拒绝未知快照或索引格式，不会迁移或删除原数据。显式运行 wombat usage --rebuild --wait-ms 600000 --json 会把所选来源重新扫描到当前格式的新数据库；持久发布成功后才切换活动代次。失败保留原索引，原数据库仍作为恢复副本保留。用户决定、身份、授权、账户观察和处理记录继续保存在各自存储中。重建不转换旧快照，也不能恢复已不可用的来源记录。仅运行 refresh 不能修复不兼容的实时状态。其他 WOMBAT_DATA_HOME 会建立隔离存储，不会带入原用户记录。
--wait-ms 1..600000 隐含 --fresh，让单个调用者等待同一同步任务；取消只释放该等待者，后台同步继续。近期查询优先处理最近 30 天修改的文件、已索引文件和完整的已声明分支或副本家族。修改时间只是调度提示，不是用量时间；无法识别文件头时回退到完整扫描。historyDeferred 表示来源覆盖暂不完整，历史加载后近期总量和排行仍可能修正。较早日期、全部日期、refresh、完整校验、显式 --include-history 与重建都会处理全部可用来源。后续近期请求不会缩小已索引的历史。Agent usage 请求可附带最多八个 also 查询，不能另选来源或快照，也不能刷新；所有结果绑定主查询版本，整批输出预算为 2 MiB。
wombat web 动态加载本机宿主，注入 Node 客户端并使用打包的 dist/web/ 资产。启动链接和退出归 CLI 管理；来源范围固定于启动参数。
耗时文本展示重复行为汇总、耗时来源、请求出现记录与本地化覆盖说明。JSON 保持生成响应不变。计算与分享口径见核心参考。
setup 分别报告运行时、发现和注册观察，不安装或执行模型任务。collection 暴露内核偏好、状态、安全事件分页及暂停与恢复；JSON 使用生成的版本 1 响应。本机偏好修改与按项目筛选的读取分开。hook codex 是有上限的 advisory stdin 入口，不输出 stdout，接收失败时也退出 0，因此不会提供模型上下文或权限决定。CLI 指南负责命令和限制。
statistics 查询任务分布和周期增长；monitor 管理预算并显式持续检查。生成的 Agent API 将 monitor 作为独立方法。命令与运行要求由 CLI 指南拥有，计算语义由核心模块拥有。
monitor watch 将暂时检查失败报告到 stderr，并在下一轮重新读取计划，包括并发修改后的 MONITOR_CHANGED。无效请求仍终止运行。
发布元数据读取超过 4 MiB 时停止并取消输入，无长度头的响应与本地文件也受此限制；发布归档使用独立的 400 MiB 上限。