# 启动性能：部署与排查指南

## 安装建议

- 预编译字节码对冷启动影响最大，Windows 尤甚：
  - `uv tool install comate-cli --compile-bytecode`
  - pip 安装通常会生成 `.pyc`；若使用 `uv pip install`，加 `--compile-bytecode`
- 未预编译时，首次启动需要现场编译大量模块，冷启动会明显变慢。

## Windows 专项

- Defender 实时扫描是 Windows 冷启动比 Linux 慢数倍的常见主因：每个首次打开的
  `.py` / `.pyc` 文件都可能被扫描。企业环境可在符合组织安全策略的前提下，将
  Python 安装目录与 venv 目录加入 Defender 排除列表。
- 子进程创建在 Windows 上也更贵。SDK 已将常规 git 上下文采集合并并行化，但若
  状态栏或 hook 额外调用外部命令，仍应设置硬 timeout 并避免无条件轮询。

## 排查慢启动

1. 运行 `COMATE_STARTUP_PROFILE=1 comate`，退出后查看
   `~/.comate/logs/agent.log` 中的 `startup_profile phase=... elapsed_ms=...` 行。
2. 或在仓库内运行 `cd packages/comate_cli && uv run python tools/startup_bench.py`，
   用真实 TUI 自动采集阶段表。
3. 重点看这些阶段：
   - `logo.printed`：首像素时间。Linux 热启动通常应在 0.3s 左右。
   - `agent.build.done`：Agent 构造完成时间，若明显偏高，优先检查 provider/model 导入链。
   - `main.import.tui.done`：TUI 依赖导入完成时间，prompt_toolkit 与 markdown 渲染栈会在这里体现。
   - `tui.run_async.enter`：TUI event loop 进入点，是端到端就绪指标。
4. 若启动显著变慢，先确认：
   - 安装时是否预编译字节码。
   - Windows / 企业 AV 是否正在扫描 Python、venv 或包缓存目录。
   - 在 `packages/comate_cli` 下运行时，`tests/test_import_weight.py` 与
     `tests/test_startup_import_budget.py` 是否仍然全绿。
   - 是否新增了 logo 前同步 import、无 timeout 子进程、或状态栏后台轮询。

## 排查首条消息 Enter 卡顿

启动已进入 TUI 但第一次按 Enter 后 3-4 秒才出现提交/loading 时，运行
`COMATE_FIRST_ENTER_PROFILE=1 comate`，退出后查看 `~/.comate/logs/agent.log`
中的 `first_turn_profile phase=... elapsed_ms=... delta_ms=...` 行。

优先看这些阶段：

- `tui.enter_staging.compute_file_ref_hints.*`：普通输入是否卡在本地 `@path` hint。
- `tui.submit_user_message.path_context_hint.*`：提交前是否卡在 `@path` context hint。
- `chat_session.header_snapshot.write_once.*` 与 `transcript.append.header-snapshot.*`：
  新 session 首条消息前的 header snapshot 落盘是否被 Windows 文件系统、OneDrive
  或 Defender 放大。
- `budget.token_counter.init_encoder.*`、`budget.tiktoken_cache.prepare.*`、
  `budget.token_counter.get_encoding.*`：首轮 token 估算是否在前台付了 tiktoken
  初始化或 cache seed 成本。
- `chat_session.run_turn_stream.first_event.*`：从进入 SDK turn 到第一个 runtime event
  的等待时间。

## 当前基准口径

`packages/comate_cli/tools/startup_bench.py` 使用 `COMATE_STARTUP_PROFILE=1`
启动真实 `comate`，POSIX 下通过 pty 自动启动并发送 `/exit`。它输出本次运行
新增的全部 startup_profile 阶段和关键阶段摘要。

2026-07-05 在当前 Linux 开发环境的 Task 14 第二轮样本：

| 阶段 | 耗时 |
| --- | ---: |
| `main.app_import.done` | 187.1 ms |
| `logo.printed` | 273.2 ms |
| `preflight.done` | 311.5 ms |
| `agent.build.done` | 4275.7 ms |
| `main.import.tui.done` | 4643.4 ms |
| `session.resolve.done` | 4764.6 ms |
| `tui.run_async.enter` | 4815.4 ms |

这个样本说明首像素目标已基本达到，但 TUI 就绪仍主要受 `Agent()` 构造和 provider
导入链影响。若产品验收必须达到 1.5s 级热启动，需要继续拆分 Agent 构造链，而不是
只调整 CLI 启动顺序。
