motel-debug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Motel Debug

Motel 调试

You are in debug mode. Debug with runtime evidence, not guesswork.

Agents guess based on code alone. You need actual runtime data. Motel is the local OpenTelemetry server that collects traces and logs — use it as your evidence loop.

Default local server details:

Base URL:
```
http://127.0.0.1:27686
```
OTLP traces:
```
POST /v1/traces
```
OTLP logs:
```
POST /v1/logs
```
Query API:
```
GET /api/*
```
OpenAPI:
```
GET /openapi.json
```
Header:
```
Content-Type: application/json
```
Auth: none by default

If the user provides a different motel URL, use that instead of the default.

你当前处于调试模式。基于运行时证据而非猜测进行调试。

Agent仅基于代码进行猜测，而你需要实际的运行时数据。Motel是收集追踪数据与日志的本地OpenTelemetry服务器——将其作为你的证据循环工具。

默认本地服务器详情：

基础URL：
```
http://127.0.0.1:27686
```
OTLP追踪：
```
POST /v1/traces
```
OTLP日志：
```
POST /v1/logs
```
查询API：
```
GET /api/*
```
OpenAPI：
```
GET /openapi.json
```
请求头：
```
Content-Type: application/json
```
认证：默认无

如果用户提供了不同的motel URL，请使用该URL而非默认值。

Workflow

工作流程

1. Verify motel is running — and start it if not

1. 确认motel正在运行——若未运行则启动它

Check

GET /api/health

. If it returns 200, continue.

If it fails (connection refused, timeout, non-200), motel isn't running. Start it as a background daemon — do not launch the TUI, which is interactive and will block your shell:

bash

motel start

motel start

ensures a managed daemon process is running, writes a lockfile under

.motel-data/

, and returns a JSON status blob. It's idempotent — safe to call repeatedly. If motel isn't on

PATH

, fall back to

bunx @kitlangton/motel start

After starting, re-check

GET /api/health

(may take 1–2s to become ready). If it still fails, read

.motel-data/daemon.log

for the error and surface it to the user.

Other lifecycle commands, for reference:

bash

motel status   # JSON status (running? pid? workdir?)
motel stop     # stop the managed daemon for this workdir

Discover reporting services with

GET /api/services

when needed.

检查

GET /api/health

接口。如果返回200状态码，继续后续步骤。

如果请求失败（连接被拒绝、超时或返回非200状态码），说明motel未运行。将其作为后台守护进程启动——不要启动交互式TUI，否则会阻塞你的Shell：

bash

motel start

motel start

命令会确保一个受管理的守护进程运行，在

.motel-data/

目录下写入锁文件，并返回JSON格式的状态信息。该命令具有幂等性——可安全重复调用。如果motel不在

PATH

中，可退而使用

bunx @kitlangton/motel start

。

启动后，重新检查

GET /api/health

接口（可能需要1-2秒才能就绪）。如果仍然失败，请读取

.motel-data/daemon.log

查看错误信息并告知用户。

以下是其他生命周期命令，供参考：

bash

motel status   # 返回JSON格式状态（是否运行？进程ID？工作目录？）
motel stop     # 停止当前工作目录下受管理的守护进程

必要时可通过

GET /api/services

发现上报服务。

2. Generate hypotheses

2. 生成假设

Before touching any code, generate 3-5 specific hypotheses about why the bug occurs. Be precise — "the cache key doesn't include the user ID" is better than "something is wrong with caching."

在修改任何代码之前，生成3-5个具体假设来解释bug产生的原因。假设要精准——比如“缓存键未包含用户ID”比“缓存存在问题”更好。

3. Instrument with tagged debug blocks

3. 添加带标签的调试代码块

Add the minimum instrumentation needed to confirm or reject all hypotheses in parallel. Every debug block must:

Be wrapped in

#region motel debug

#endregion motel debug

markers

Include a
```
debug.hypothesis
```
attribute linking it to a specific hypothesis
Use whatever tracing/logging mechanism the codebase already has (spans, structured logs, annotations — not raw
```
fetch
```
calls)

Tag every piece of debug instrumentation with structured attributes so you can query it later. Reuse these keys:

Key	Purpose
`debug.session`	Groups all instrumentation for this debug session
`debug.hypothesis`	Links to a specific hypothesis (e.g. `"cache-miss"` , `"A"` )
`debug.step`	Position in the flow (e.g. `"entry"` , `"before-write"` , `"after-read"` )
`debug.label`	Human-readable description of what this point captures

Choose log placements based on your hypotheses:

Function entry with parameters
Function exit with return values
Values before and after critical operations
Branch execution paths (which if/else ran)
State mutations and intermediate values
Suspected error or edge-case values

Guidelines:

At least 1 instrumentation point is required; never skip instrumentation
Do not exceed 10 — if you think you need more, narrow your hypotheses
Typical range is 2-6

添加最少的埋点代码，以并行验证或推翻所有假设。每个调试代码块必须：

使用

#region motel debug

#endregion motel debug

标记包裹

包含
```
debug.hypothesis
```
属性，关联到特定假设
使用代码库已有的追踪/日志机制（如span、结构化日志、注解——不要使用原生
```
fetch
```
调用）

为每一处调试埋点添加结构化属性标签，以便后续查询。请复用以下键：

键	用途
`debug.session`	分组本次调试会话的所有埋点
`debug.hypothesis`	关联到特定假设（例如 `"cache-miss"` 、 `"A"` ）
`debug.step`	流程中的位置（例如 `"entry"` 、 `"before-write"` 、 `"after-read"` ）
`debug.label`	该埋点捕获内容的可读描述

根据假设选择日志埋点位置：

函数入口（包含参数）
函数出口（包含返回值）
关键操作前后的值
分支执行路径（哪个if/else分支被执行）
状态变更与中间值
疑似错误或边缘情况的值

指导原则：

至少需要1个埋点；绝不能跳过埋点步骤
埋点数量不要超过10个——如果认为需要更多，请缩小假设范围
典型范围是2-6个

4. Reproduce the issue

4. 复现问题

If a failing test exists, run it directly
If reproduction is straightforward (CLI command, curl, simple script), write and run it yourself
Otherwise, ask the user to reproduce — provide clear numbered steps and remind them to restart if needed
Once a reproduction pathway is established, reuse it for all subsequent iterations

如果存在失败的测试用例，直接运行该测试
如果复现步骤简单（CLI命令、curl、简单脚本），自行编写并运行
否则，请用户协助复现——提供清晰的分步说明，并提醒用户必要时重启服务
一旦确定复现路径，后续迭代均复用该路径

5. Analyze evidence

5. 分析证据

Query motel for the debug instrumentation:

bash

curl "http://127.0.0.1:27686/api/spans/search?service=<service>&attr.debug.hypothesis=<id>"
curl "http://127.0.0.1:27686/api/logs/search?service=<service>&attr.debug.session=<session>"
curl "http://127.0.0.1:27686/api/traces/search?service=<service>&attr.debug.hypothesis=<id>"

For each hypothesis, evaluate: CONFIRMED, REJECTED, or INCONCLUSIVE — cite specific spans, logs, or attribute values as evidence.

查询motel获取调试埋点数据：

bash

curl "http://127.0.0.1:27686/api/spans/search?service=<service>&attr.debug.hypothesis=<id>"
curl "http://127.0.0.1:27686/api/logs/search?service=<service>&attr.debug.session=<session>"
curl "http://127.0.0.1:27686/api/traces/search?service=<service>&attr.debug.hypothesis=<id>"

针对每个假设，评估结果：已确认、已推翻或无法确定——引用具体的span、日志或属性值作为证据。

6. Fix only with evidence

6. 基于证据修复

Do not fix without runtime evidence. When you fix:

Keep all debug instrumentation in place — do not remove it yet
Make the fix as small and targeted as possible
Reuse existing architecture and patterns; do not overengineer

不要在没有运行时证据的情况下修复问题。修复时：

保留所有调试埋点——暂不删除
修复要尽可能小且针对性强
复用现有架构与模式；不要过度设计

7. Verify the fix

7. 验证修复效果

Reproduce the issue again with instrumentation still active. Compare before/after evidence:

Cite specific log lines or span attributes that prove the fix works
If the fix failed: revert code changes from rejected hypotheses (do not let speculative fixes accumulate), generate new hypotheses from different subsystems, add more instrumentation, and iterate
Iteration is expected. Taking longer with more data yields better fixes.

在保留埋点的情况下再次复现问题。对比修复前后的证据：

引用具体的日志行或span属性来证明修复有效
如果修复失败：回退被推翻假设对应的代码变更（不要积累推测性修复），从不同子系统生成新假设，添加更多埋点并迭代
迭代是正常流程。花费更多时间收集数据能得到更优质的修复方案。

8. Clean up

8. 清理

Only after the fix is verified and the user confirms there are no remaining issues:

Run the cleanup script or remove blocks manually (see Cleanup section below)
Run
```
git diff
```
to confirm only the intentional fix remains

只有在修复验证通过且用户确认无遗留问题后：

运行清理脚本或手动移除调试代码块（见下文清理部分）
运行
```
git diff
```
确认仅保留了预期的修复代码

Instrumentation Rules

埋点规则

Wrap every temporary debug block in these exact markers:

// #region motel debug
// temporary debug instrumentation
// #endregion motel debug

Use whatever the codebase already provides for tracing and logging. The markers are language-comment wrappers — adapt the comment syntax for non-JS/TS files (e.g.

# #region motel debug

for Python).

Do not:

Log secrets, tokens, passwords, or raw PII
Remove instrumentation before post-fix verification succeeds
Use
```
setTimeout
```
,
```
sleep
```
, or artificial delays as a "fix"
Let code changes from rejected hypotheses accumulate — revert them

所有临时调试代码块必须使用以下标记包裹：

// #region motel debug
// 临时调试埋点代码
// #endregion motel debug

使用代码库已有的追踪与日志机制。这些标记是语言注释包裹器——针对非JS/TS文件需调整注释语法（例如Python使用

# #region motel debug

）。

禁止：

记录密钥、令牌、密码或原始PII（个人可识别信息）
在修复后验证通过前移除埋点
使用
```
setTimeout
```
、
```
sleep
```
或人为延迟作为“修复方案”
积累被推翻假设对应的代码变更——请回退

Query Patterns

查询模式

Two filter prefixes for attribute search:

Prefix	Match type	Example
`attr.<key>=<value>`	Exact match	`attr.debug.hypothesis=cache-miss`
`attrContains.<key>=<substring>`	Case-insensitive substring	`attrContains.ai.prompt.messages=hello world`

bash

curl http://127.0.0.1:27686/api/health
curl http://127.0.0.1:27686/api/services

属性搜索支持两种过滤前缀：

前缀	匹配类型	示例
`attr.<key>=<value>`	精确匹配	`attr.debug.hypothesis=cache-miss`
`attrContains.<key>=<substring>`	不区分大小写的子串匹配	`attrContains.ai.prompt.messages=hello world`

bash

curl http://127.0.0.1:27686/api/health
curl http://127.0.0.1:27686/api/services

Trace search

追踪数据搜索

curl "http://127.0.0.1:27686/api/traces/search?service=<service>&operation=<text>&attr.debug.session=<session>"

Span search (supports traceId to scope to one trace)

Span搜索（支持通过traceId限定到单个追踪）

curl "http://127.0.0.1:27686/api/spans/search?service=<service>&traceId=<trace-id>&attr.debug.hypothesis=<id>" curl "http://127.0.0.1:27686/api/spans/search?service=<service>&attrContains.ai.prompt.messages=<phrase>"

Log search (supports severity filter, case-insensitive body search)

日志搜索（支持级别过滤、不区分大小写的内容搜索）

curl "http://127.0.0.1:27686/api/logs/search?service=<service>&severity=ERROR&body=<text>" curl "http://127.0.0.1:27686/api/logs/search?service=<service>&attrContains.debug.label=<substring>"

AI call search (compact summaries with previews)

AI调用搜索（带预览的紧凑摘要）

curl "http://127.0.0.1:27686/api/ai/calls?model=gpt-5.4&sessionId=<session>" curl "http://127.0.0.1:27686/api/ai/calls?text=<phrase>&status=error"

AI call detail (full prompt/response payloads)

AI调用详情（完整的提示词/响应 payload）

curl "http://127.0.0.1:27686/api/ai/calls/<span-id>"

AI stats

AI统计数据

curl "http://127.0.0.1:27686/api/ai/stats?groupBy=model&agg=total_input_tokens"

curl http://127.0.0.1:27686/openapi.json


List and search responses include `meta.nextCursor` when more data is available.

Motel gives you trace-correlated data — you can see which span a debug log belongs to, the parent operation, timing, and the full trace tree. Use `GET /api/traces/<trace-id>/spans` and `GET /api/spans/<span-id>/logs` to navigate the correlation.

For AI/LLM calls, use `/api/ai/calls` for compact searchable summaries (with prompt/response previews and token usage), and `/api/ai/calls/<span-id>` for full payloads.

curl "http://127.0.0.1:27686/api/ai/stats?groupBy=model&agg=total_input_tokens"

curl http://127.0.0.1:27686/openapi.json


列表与搜索结果在存在更多数据时会包含`meta.nextCursor`。

Motel提供追踪关联的数据——你可以查看调试日志所属的span、父操作、时序以及完整的追踪树。使用`GET /api/traces/<trace-id>/spans`和`GET /api/spans/<span-id>/logs`来浏览关联关系。

对于AI/LLM调用，使用`/api/ai/calls`获取可搜索的紧凑摘要（带提示词/响应预览与令牌使用量），使用`/api/ai/calls/<span-id>`获取完整payload。

Effect

If the target repo uses Effect, read

references/effect.md

before changing runtime wiring or adding instrumentation.

如果目标仓库使用Effect，请在修改运行时配置或添加埋点前阅读

references/effect.md

。

Cleanup

清理

Use the bundled script at

scripts/clear-motel-debug.ts

when you want deterministic cleanup. It removes every block between

#region motel debug

and

#endregion motel debug

in JS/TS files and fails on unmatched markers.

If you cannot run the script, delete every marked block manually and then grep for

#region motel debug

to confirm none remain.

如需确定性清理，可使用

scripts/clear-motel-debug.ts

脚本。该脚本会移除JS/TS文件中所有

#region motel debug

与

#endregion motel debug

之间的代码块，并在标记不匹配时报错。

如果无法运行脚本，请手动删除所有标记包裹的代码块，然后通过

grep

搜索

#region motel debug

确认无残留。