02
一次 CLI 调用的一生Life of one CLI call
退出码是代理与引擎之间最重要的契约：2 表示你的输入错了（按 error: 行修，最多重试两次），1 表示命令跑了但失败了（不要掩盖），0 才是成功。validate 是例外：它把一切失败都归为 1。The exit code is the most important contract between agent and engine: 2 means your input was wrong (fix it from the error: lines, at most two retries), 1 means the command ran but failed (do not hide it), and 0 is success. validate is the exception: it maps every failure to 1.
- build_parser().parse_args(argv)argparse 的错误被改写成 InputError，列出每个
error:行，退出码 2。argparse errors are rewritten as InputError and printed aserror:lines, exit 2. - config.load(find_config(...))按
--config、$ETRACE_CONFIG、当前目录的顺序找 trace.toml；未知键直接报错，不静默回退。trace.toml is found via--config,$ETRACE_CONFIG, then the current directory; an unknown key is an error, never a silent default. - Context(cfg)懒加载 Store、预设和时钟，所有命令共用，测试里可以注入固定时间。Lazily builds the Store, the preset and the clock for all commands; tests can inject a fixed time.
- cmd_*(ctx, args)读代理给的 JSON 文件，
check_fields先挡住缺字段和多余字段，再交给领域模块。Reads the agent's JSON file;check_fieldsstops missing and unknown fields before the domain module sees them. - 异常归类Exception mapping领域异常（PadError、XPError、DecisionError...）全部带
.errors，统一成退出码 2；StoreError、OSError、CheckpointError则是 1。Domain exceptions (PadError, XPError, DecisionError...) all carry.errorsand become exit 2;StoreError,OSErrorandCheckpointErrorbecome exit 1. - _emit(result)输出被管道接走（代理、脚本）时只向 stdout 打印一个 JSON 对象；在终端里由
render.py画成彩色视图。--json/--pretty/--no-color可放在命令行任意位置，也认 NO_COLOR 和 FORCE_COLOR。When output is piped (agents, scripts) exactly one JSON object goes to stdout; in a terminalrender.pydraws a coloured view.--json,--prettyand--no-colormay sit anywhere on the line; NO_COLOR and FORCE_COLOR are honoured.
$ python3 -m etrace pad add bad_pad.json # exit 2
error: points[0].P: must be within 0-5, got 9 error: points[0].source: required for model_inference error: points[0].confidence: required for model_inference error: points[1].bogus: unknown field
$ python3 -m etrace validate # exit 0
{
"ok": true,
"problems": []
}cli.py main(), trimmed
except InputError as exc:
for line in exc.errors:
err.write(f"error: {line}\n")
return 1 if is_validate else 2
except Failure as exc:
... # ran, but failed
return 1
except _INPUT_ERRORS as exc: # domain errors with .errors
...
return 1 if is_validate else 2
except (StoreError, checkpoint.CheckpointError, OSError) as exc:
err.write(f"failed: {exc}\n")
return 1终端里的样子What it looks like in a terminal
横幅、进度条、趋势折线、对勾提示都是真实输出（演示数据是虚构的）。不是终端时自动退回 JSON，Unicode 不可用时退回 ASCII。Banner, bars, trend sparklines and check marks are real output (the demo data is synthetic). Output that is not a terminal falls back to JSON, and a terminal without Unicode falls back to ASCII.
17 个顶层命令The 17 top-level commands
| 命令Command | 做什么What it does | 落到哪个模块Module |
|---|---|---|
init | 从预设创建新数据目录、配置和今天的笔记Creates a data directory, config and today's note from a preset | cli, presets, journal |
note new | write | 建笔记；只替换某个 ai 块并读回Create a note; replace one ai block and read it back | journal |
question add | 登记带证据的提问，去重Files an evidence-backed question, de-duplicated | container/questions |
feedback ingest | 从笔记反馈区取入反馈，并给被回答的问题收尾Ingests feedback from notes and closes answered questions | container/feedback |
decide | 写入决定及其规则变更Stores a decision and its rule changes | container/decisions, rules |
usage add | 写使用回执，必须读回核对Stores a usage receipt, which must be read back | container/usage |
outreach send | 把问题与决定报告写进笔记，可选邮件Writes questions and the decision report into the note, optionally by email | outreach/note, email |
pad add | chart | 记录 PAD 读数；画 SVG 并写回 ai:pad 块Records PAD readings; draws the SVG and writes the ai:pad block | models/pad, chart |
g predict | feedback | report | chart | 冻结预测；记录对预测的反馈（细项、B、E 或 G）；生成 G 报告块；画 B/E/G 趋势图（带宽 4.5 天）Freezes a prediction; records feedback on it (an item, B, E or G); draws the B/E/G trend (4.5-day bandwidth); builds the G report block | models/g |
xp score | 计分并追加新版本Scores a day and appends a revision | models/xp |
audit weekly | 生成周审计 md 与 jsonWrites the weekly audit as md and json | container/audit |
checkpoint | 本地 git 提交，没变化就不提交Local git commit, none when nothing changed | checkpoint |
rules list | 列出生效规则（可按作用域）Lists active rules, optionally by scope | container/rules |
prompt | 渲染某个任务的代理提示词Renders the agent prompt for a task | prompts |
notion push | 单向镜像当天笔记One-way mirror of the day's note | adapters/notion |
schedule | 为代理生成调度文件，从不安装Writes scheduler files, never installs them | adapters/scheduler |
validate | 检查整条数据链和笔记，失败时退出码 1Checks the data chain and notes; exit 1 on any failure | container/validate |