故障排查与诊断
插件的所有钩子均采用故障开放（fail-open）设计：一旦内部出现任何异常，钩子会静默返回空结果，让你的智能体会话照常继续，同时把错误信息写入 ~/.tokeneconomizer/errors.log。遇到疑问时，先跑一次 te doctor。
te doctor 环境自检
doctor 命令不会发起任何模型调用，也不消耗智能体轮次。它会依次检查：
- 当前使用的 Python 解释器路径与版本（要求 Python 3.10 或更高版本）；
- 状态目录
~/.tokeneconomizer的读写权限与结构； - 本机已发现的编码智能体、插件安装状态，以及当前目录是否已被 Codex 或 Copilot CLI 标记为受信任（trusted）；
- 如果启用了仓库地图（
repomap）或安装了rtk，报告其对应的可执行文件位置； - 当前工作目录被归入哪个仓库身份键（remote URL 或主检出路径），以及侧调用路由与
errors.log中最近的报错行。
# 检查当前仓库最近使用过的智能体环境
~/.tokeneconomizer/bin/te doctor
# 指定检查某一个宿主智能体（如 codex 或 copilot）
~/.tokeneconomizer/bin/te --host codex doctor
~/.tokeneconomizer/bin/te --host copilot doctor
# 如果还未跑过任何会话（~/.tokeneconomizer/bin 尚未生成），直接从克隆目录运行：
/path/to/TokenEconomizer/plugin/scripts/te doctorte probe 真机端到端探测
如果你想在自己的机器与账号配置（尤其是 Copilot CLI 的 BYOK 模式）上验证插件的三大机制是否完整跑通，可以运行内置的端到端探测命令：
~/.tokeneconomizer/bin/te --host copilot probe # 在临时仓库中连续跑 7 场真实短会话该命令会创建一个用完即删的临时仓库（配置了 pytest 测试但故意不安装 pytest，仅能用 python -m unittest 通过），并在隔离的状态目录下自动发起 7 场简短的真实会话：验证微技能是否成功学到事实并在后续会话中改变模型首条测试命令，接着应用提议的工具剪枝列表、对比工具定义 token 数变化，最后自动恢复配置。注意：这会消耗你账号上的少量真实模型调用。
插件常见故障与修复
| 症状或报错信息 | 原因与修复方式 |
|---|---|
| 命令打印导入错误（ImportError），或钩子看起来毫无反应 | 运行 ~/.tokeneconomizer/bin/te doctor（或在克隆目录运行 plugin/scripts/te doctor），查看环境检查项与末尾的 errors.log 报错行。 |
| errors.log 提示找不到插件包（package was not found for the plugin） | 安装插件时所用的 git 克隆目录被移动或删除了：请把它移回原位、重新添加 marketplace，或使用 scripts/build_plugin.py 构建自包含安装包。 |
| 提示 TokenEconomizer needs Python >= 3.10 (this is 3.x) | 安装 Python 3.10 或更高版本，或设置环境变量 TE_PYTHON=/path/to/python3.10+ 指向高版本解释器。 |
| 跑了很多次会话，工具剪枝列表依然什么都没排除 | 在 Claude Code 或 Copilot CLI 中运行一次 /tokeneconomizer:toolprune refresh-catalog，把默认加载的工具目录记录下来。 |
| Codex 上工具剪枝列表已应用，但会话里的能力包没有变化 | Codex 仅在「已信任（trusted）」的项目中读取 .codex/config.toml；在仓库里运行 ~/.tokeneconomizer/bin/te --host codex doctor 可检查当前目录是否已被 Codex 信任。 |
| errors.log 出现 sidecall copilot: no reply，且会话开始提示模型调用已暂停 | Copilot CLI 在 BYOK（自带密钥）模式下不会把 COPILOT_PROVIDER_* 环境变量传给钩子，因此侧调用无法连上你的提供商。此时微技能仍保留零调用的环境事实（可设 microskills=envfacts），循环守卫仅在 2.5× 兜底线处重定向；改回 Copilot 登录态后运行 config set microskills=on 即可恢复。 |
| 在终端直接运行 te 时显示的是另一个智能体的状态 | 不带参数时 te 默认读取最近一次在该仓库工作的智能体；请显式加上 --host claude、codex、copilot、pi 或 opencode。 |
实验复现常见故障
在运行 experiments/ 下的 SWE-Bench 与 Web-Bench 评测脚本时，如果遇到异常，可对照下表排查：
| 症状或报错信息 | 原因与修复方式 |
|---|---|
| 启动脚本打印 RUNNER=stub -- SYNTHETIC run | 未设置 RUNNER 环境变量；默认 stub 仅用于跑通流水线烟雾测试，不会调用真实智能体。请传入 RUNNER=te_harness.swebench:make_runner 或 webbench:make_runner。 |
| 评分阶段报 ModuleNotFoundError | 当前虚拟环境未安装官方 SWE-Bench 评分器；请执行 pip install -e "$DATA/SWE-bench"。 |
| Web-Bench 所有测试全部失败，应用根本无法渲染 | 数据目录路径包含了符号链接（symlink）；请用 export DATA="$(readlink -f ~/te_data)" 解析为真实规范路径。 |
| 报 Executable doesn't exist at …/chromium_headless_shell-… | Playwright 是在项目外部安装的，浏览器构建版本与 Web-Bench 子项目锁定的版本不一致；请进入 projects/calculator 目录内运行 npx playwright install chromium chromium-headless-shell。 |
| Codex 密钥有效却收到 401 Unauthorized | 该密钥签发自区域性端点（regional endpoint）；请在 experiments/.env 中显式设置 OPENAI_BASE_URL。 |
| 需要中途停止一条后台实验通道（lane） | 使用启动时打印的命令 kill -TERM -$(cat <log>.pid)；注意 PID 前面的负号（-）用于停止整个进程组。 |
常见问题解答
插件需要单独配置 API Key 吗？我的代码会被上传到外部服务器吗？
不需要任何额外 API Key，代码也绝不会离开你的机器。插件的所有状态保存在本地 ~/.tokeneconomizer（目录权限 0700，文件 0600）。当循环守卫的裁判或微技能提议器需要调用模型时，它直接通过你已登录的智能体 CLI（claude -p、codex exec、copilot -p、pi -p）发起调用，且只发送脱敏后的命令模板、文件名与归一化报错行，从不发送源码内容。
工具剪枝修改工具列表后，会不会导致正在进行的对话缓存（Prompt Cache）失效？
不会。实测验证表明，运行中的会话会保持启动时的工具列表不变；而恢复旧会话（如 claude --continue 或 codex resume）则会使用新工具列表并重写缓存。因此工具剪枝专门设计了静默等待窗口（默认 toolprune_quiet_minutes = 60）：只有当你在该仓库的所有会话空闲满 60 分钟（此时提示缓存本就已过期）后，插件才真正把拒绝列表写入本地配置文件。
如果工具剪枝把某个我偶尔才用的工具排除了，怎么恢复？
随时运行 toolprune restore（或指定工具名 toolprune restore NotebookEdit）即可一键归还。被你手动归还的工具会被永久记入保护名单，后续即使长期不用也不会再被自动排除。你也可以通过 config set toolprune_protect=工具名 提前保护特定工具，或设为 toolprune=propose 改为每次由你手动确认。
为什么微技能（microskills）默认是关闭的，而工具剪枝和循环守卫默认开启？
因为工具剪枝完全不调用模型，循环守卫也只在某一轮出现明显的重复报错循环迹象时才唤醒一次轻量裁判；而微技能的提议器默认每隔 3 个会话会调用一次模型来总结近期会话。如果你希望零模型调用开销地使用微技能，可以运行 config set microskills=envfacts，它只从跨会话重复出现的命令失败中提取确定性事实。
循环守卫判定某一轮卡住时，会不会直接强行杀掉我的智能体任务？
绝不会。插件奉行「让每个动作都可逆」的原则：第一次判定卡住时，它会在工具返回结果后附带一条简短的重定向提示，建议模型换一种思路（每轮最多 r = 1 次）；如果重定向之后这一轮依然在原地打转，插件只会打印一行提示告诉你当前智能体该如何手动中断（如按 Esc），是否停下完全由你决定。
同一个仓库有多个 git worktree 或多个克隆目录，学到的经验会共享吗？
会自动共享。插件通过 git origin 远端地址识别仓库身份，因此同一仓库的所有克隆、子目录和 git worktree 共享同一份微技能事实、工具证据与循环包络统计；而工具剪枝生成的本地配置文件（如 .claude/settings.local.json）则按各自的检出目录独立维护，并自动加入 .git/info/exclude 避免污染 git 状态。