sensorium 的定位是记录程序实际做过什么，然后在事后针对这次记录提问。它认为读日志像是在读日记，而它做的是观察执行过程本身。
主要能力与记录方式
它把程序的一次运行——每一次调用、返回和异常，以及捕获到的值——记录进一个 SQLite 追踪文件，再从该追踪中用密集纯文本回答调试问题，文本形态是为语言模型阅读而设计的。三种记录器共用同一格式：
- Python：sensorium run -- <command> 用 PEP 669（sys.monitoring）插桩包装一次运行，要求 Python 3.12+，无运行时依赖。在 3.11 上它会拒绝启动，而不是退回到更弱的方式。追踪是用标准库写入的 SQLite 文件。有一项能力受版本限制：见证 multiprocessing spawn 需要 3.14 才出现的 _posixsubprocess.fork_exec 审计事件，低于该版本此类 spawn 不被见证。
- Rust：cargo sensorium test|run 在构建期对工作区自身 crate 插桩，每个进程写入一份追踪。稳定版 rustc，Linux。Rust 记录器是独立的构建与安装。
- TypeScript：sensorium ts run [--focus <spec>]… -- vitest run …（或 -- node --test …）在加载时转换使用者自己的源码，每个测试文件进程写入一份追踪。要求 Node 24、vitest 4.1。
三者都写入 trace format 4，因此下面的每一条查询都能作用于这三种追踪。按行状态捕获是记录时可选开启的，所以针对局部变量的谓词需要在记录了这些变量的那次运行上提问；若针对未开启该 --focus 的运行提问，watch 不会报告零命中，而是报告 NOTHING WAS CHECKED 并打印出确切的重录命令。
记录范围与帧模型
记录捕获运行起始工作目录下代码的调用、返回、抛出与已处理事件，因此 sensorium run -- pytest ... 追踪的是你的测试和你的代码，而不是 pytest 自身的。--focus module:qualname 为指定代码加入行级捕获与局部变量变化；--window QUALNAME 把该捕获限制在一个函数的活动范围内。追踪文件落在 ~/.sensorium/traces（或 $SENSORIUM_DIR/traces），每次运行一个 SQLite 文件，Rust 与 TypeScript 记录器写入同一目录。
在 asyncio 程序上，树按任务分组；自 trace format 3 起，每个被追踪的代码对象都会开一个帧——函数、生成器、协程或异步生成器皆然——因此协程的被调用者会像普通函数一样嵌套在其下，并在种类不是函数时标注 [generator]、[coroutine] 或 [async_generator]。挂起的帧会带一个派生的尾部状态，如 ~ cancelled、~ abandoned、~ unwound by X thrown in at Ln、~ suspended at Ln 等。父链接是调用者帧，经代码身份验证，而不是“该线程上最后打开的帧”。
查询与使用方式
运行引用可以是完整 run id、唯一前缀或 last。查询用 eN 指代事件、fN 指代帧，这些 id 稳定，因此一个命令的答案可以作为下一个命令的参数。--fn NAME 在 grep 和 frame 中先精确匹配 qualname，再回退到对追踪内不同 qualname 的子串匹配；只有一处子串命中时按精确命名处理，多于一处则作为歧义调用被拒绝，并列出所有候选。frame --fn NAME --nth N 在重复活动之间选择；flow --object 接受 e<id>:<name> 或 <qualname>:<name>。
它还包括：diff 比较两次运行的因果流；refocus 用更深捕获重跑被记录的命令，再判断重跑是否为同一次执行；tree 展示派生的父子关系；watch 等命令基于追踪回答问题。sensorium mcp 通过 Model Context Protocol 以 stdio 把同一存储提供给模型，无运行时依赖，上面除 redact 外的每条查询命令都是一个工具，record 和 refocus 仅在 --allow-run 下可用。任意 MCP 客户端均可注册同一二进制。
严谨性与限制
每个命令的输出都力求精确说明自身局限。diff 比较的是形状而非位置：MATCH 表示执行形状相同，而非值相同；函数换文件会导致每个事件的文件变化，纯移动会读作 DIVERGED，diff --ignore-moves 可在配对唯一时把移动配对出来并标注 moved。refocus 给出三种判定与有界许可：完全无法 refocus 时（如原追踪 INCOMPLETE、原运行消费了 stdin、目标不再可解析、原工作目录已消失等）以退出码 2 结束且不重跑；能重跑时，MATCH 只允许一个结论，即重跑走了同一路径，因此更深捕获描述的是同一路径。许可旁列出实际通过并一致的检查项，任何无法运行的检查也会扣留许可并逐条说明原因。DIVERGED 不是工具失败：对控制流依赖进程外状态的程序，DIVERGED 就是正确答案，新追踪仍被记录且永久标注。
每次调用会以一行 JSON 追加到 <trace root>/invocations.jsonl（默认 ~/.sensorium/invocations.jsonl 或 $SENSORIUM_DIR 下），只含 utc、argv、exit 和 error，不含环境与工作目录；设置 SENSORIUM_NO_INVOCATION_LOG 为非 0 的非空值可对单个进程关闭该日志。
其他事实（如具体安装命令、MCP 工具清单与结果头、上限、审计文件、服务器拒绝行为的完整说明，以及 Rust、TypeScript 的完整参考）详见仓库文件 docs/mcp.md、docs/agent.md、rust/README.md、typescript/README.md，此处暂未提供其全部内容。
