fix(coding): 使用 uv 管理窗口预热依赖

Author: mudssky

.gitignore

@@ -49,4 +49,5 @@ vitest-report.xml
 
 
 # python
-*.pyc
+*.pyc
+.venv/

.trellis/spec/infra/coding-plan-window-warmer.md

@@ -15,15 +15,16 @@
 ### 2. Signatures
 
 - Direct run:
-  - `uv run --script ai/coding/window-warmer/window_warmer.py --config ai/coding/window-warmer/window-warmer.toml`
-  - `uv run --script ai/coding/window-warmer/window_warmer.py --config ai/coding/window-warmer/window-warmer.toml --print-next`
-  - `uv run --script ai/coding/window-warmer/window_warmer.py --config ai/coding/window-warmer/window-warmer.toml --once --dry-run`
+  - From `ai/coding/window-warmer`: `uv run python window_warmer.py --config window-warmer.toml`
+  - From `ai/coding/window-warmer`: `uv run python window_warmer.py --config window-warmer.toml --print-next`
+  - From `ai/coding/window-warmer`: `uv run python window_warmer.py --config window-warmer.toml --once --dry-run`
 - PM2:
   - `pm2 start ai/coding/window-warmer/window-warmer.pm2.config.cjs`
   - PM2 app name: `coding-window-warmer`
 - Python script:
   - Entry file: `ai/coding/window-warmer/window_warmer.py`
-  - Dependency declaration: PEP 723 script metadata with `litellm>=1.81.0`
+  - Dependency declaration: `ai/coding/window-warmer/pyproject.toml`
+  - Locked dependencies: `ai/coding/window-warmer/uv.lock`
   - Helper package: `ai/coding/window-warmer/window_warmer_lib/`
 
 ### 3. Contracts
@@ -33,7 +34,7 @@
   - `base_url`: direct upstream OpenAI-compatible API base URL. Default points to `https://open.bigmodel.cn/api/coding/paas/v4`, not local LiteLLM Proxy.
   - `container_name`: optional local Docker readiness gate. When set to `litellm`, it only proves the local gateway container is running; it must not change the warm request destination.
   - `api_key_env`: optional environment variable for upstream API key. Default for Z.ai Coding Plan is `Z_AI_API_KEY`.
-  - `env_file`: optional dotenv-style file path, resolved relative to the TOML file.
+  - `env_file`: optional dotenv file path, resolved relative to the TOML file. Default is `.env.local` in the warmer directory.
   - `health_path`: optional direct target health path. Default is `/models`.
   - `request_timeout_seconds`: timeout used by health check and LiteLLM SDK completion.
 - Plan config `[[plans]]`:
@@ -65,7 +66,8 @@
 ### 5. Good/Base/Bad Cases
 
 - Good: Default config checks optional local `litellm` container but sends `openai/GLM-5.1` to `https://open.bigmodel.cn/api/coding/paas/v4` through LiteLLM SDK.
-- Good: `uv run --script` handles LiteLLM SDK dependency without creating repo-level `requirements.txt`, `pyproject.toml`, or a committed virtual environment.
+- Good: `uv add litellm` records the direct dependency in tool-local `pyproject.toml` and locks it in `uv.lock`; `uv run` syncs the environment before execution.
+- Good: Put real API keys in ignored `.env.local`; commit only `.env.example`.
 - Good: Time calculation is pure and unit-tested separately from HTTP/LiteLLM SDK calls.
 - Base: `fixed_times = ["08:00", "13:00", "18:00", "23:00"]` with `jitter_seconds = 120` schedules each event within two minutes after the base time.
 - Bad: Pointing `[target].base_url` at `http://127.0.0.1:34000` for default GLM warmup, because the request can enter LiteLLM Proxy fallback chains.
@@ -85,8 +87,8 @@
   - prompt, max tokens, temperature and timeout are passed.
 - Dry-run test asserting readiness checks are skipped.
 - Smoke commands:
-  - `uv run --script ai/coding/window-warmer/window_warmer.py --config ai/coding/window-warmer/window-warmer.toml --print-next`
-  - `uv run --script ai/coding/window-warmer/window_warmer.py --config ai/coding/window-warmer/window-warmer.toml --once --dry-run`
+  - From `ai/coding/window-warmer`: `uv run python window_warmer.py --config window-warmer.toml --print-next`
+  - From `ai/coding/window-warmer`: `uv run python window_warmer.py --config window-warmer.toml --once --dry-run`
   - `node -c ai/coding/window-warmer/window-warmer.pm2.config.cjs`
 
 ### 7. Wrong vs Correct
@@ -115,6 +117,7 @@ name = "z-ai-coding-plan"
 base_url = "https://open.bigmodel.cn/api/coding/paas/v4"
 container_name = "litellm"
 api_key_env = "Z_AI_API_KEY"
+env_file = ".env.local"
 health_path = "/models"
 
 [[plans]]

.trellis/tasks/05-13-litellm-coding-plan-window-warmer/prd.md

@@ -14,7 +14,8 @@
 * 用户选择长期 watch 模式：脚本启动后常驻运行，自行等待并触发后续预热。
 * 脚本需要支持窗口配置以适配多种套餐：一种按“指定开始时间 + 窗口时长”推导后续发送时间；另一种精确配置发送时间点。
 * 用户最初希望尽量减少标准库之外的依赖；后续明确可以引入 LiteLLM SDK，并用 `uv` 安装和运行依赖。
-* 用户不打算创建传统 venv 或独立 Python 项目；目标是一个可通过 `uv run --script` 直接运行的脚本工具。
+* 用户接受在工具目录内使用 uv 管理依赖；目标是一个可通过 `uv run` 直接运行的轻量脚本工具。
+* 用户询问模型与 API key 如何加载；当前约定是模型写入 `[[plans]].model`，API key 按 `api_key_env` 先读进程环境变量，再读 `env_file` 指向的 dotenv 文件。
 * 本机 `python3 --version` 为 3.13.5，可使用标准库 `tomllib` 读取 TOML 配置。
 * 脚本在宿主机运行，不进入容器；因此它不能天然随 Docker 容器启动，除非由 `start.ps1`、手动命令或宿主机计划任务显式启动。
 * 用户倾向用 PM2 启动和管理长期脚本进程，方便查看日志、重启和开机恢复。
@@ -57,11 +58,12 @@
 * 配置必须支持多个 `[[plans]]`，每个 plan 独立配置 model、prompt、调度和重试；脚本合并所有 plan 的下一次触发时间统一调度。
 * 两种调度模式都应叠加随机偏移窗口，默认整点后 `0-120` 秒。
 * 调度计算应能跨天运行，避免 23 点之后无法正确计算次日首个窗口。
-* 脚本使用 LiteLLM Python SDK 处理 OpenAI 兼容 completion 调用，通过 PEP 723 script metadata 和 `uv run --script` 管理依赖。
+* 脚本使用 LiteLLM Python SDK 处理 OpenAI 兼容 completion 调用，通过工具目录内 `pyproject.toml` 与 `uv.lock` 管理依赖。
 * 预热相关文件应集中放在 `ai/coding/window-warmer/`，避免堆在 LiteLLM 网关目录。
 * 配置文件建议使用 TOML，例如 `ai/coding/window-warmer/window-warmer.toml`。
-* 不创建 `requirements.txt`、`pyproject.toml` 或仓库级虚拟环境；脚本入口和模块化 helper 作为轻量工具维护。
-* 启动方式采用 PM2 管理宿主机脚本，PM2 调用 `uv run --script`。
+* 密钥文件使用同目录 `.env.local`，只提交 `.env.example`，不提交真实密钥。
+* 不创建仓库级虚拟环境；脚本入口和模块化 helper 作为轻量工具维护。
+* 启动方式采用 PM2 管理宿主机脚本，PM2 在工具目录内调用 `uv run python window_warmer.py`。
 * 仓库内提供 PM2 ecosystem 配置文件，减少用户手写启动命令的概率。
 
 ## Acceptance Criteria (evolving)
@@ -78,7 +80,7 @@
 * [ ] `fixed_times` 模式可按每日时间点列表触发预热。
 * [ ] 多个 `[[plans]]` 可以并存，且脚本会分别触发每个 plan 的预热请求。
 * [ ] 长期 watch 模式可从当前时间计算下一次触发时间，并支持跨天。
-* [ ] 脚本可以通过 `uv run --script ai/coding/window-warmer/window_warmer.py` 直接启动并自动准备 LiteLLM SDK 依赖。
+* [ ] 脚本可以在 `ai/coding/window-warmer/` 下通过 `uv run python window_warmer.py` 直接启动并自动准备 LiteLLM SDK 依赖。
 * [ ] 文档提供 PM2 启动、查看日志、重启、停止和持久化命令。
 * [ ] 仓库内 PM2 ecosystem 配置可直接启动默认 warmer。
 * [ ] PM2 管理脚本时，脚本仍会在每次发送前检查配置的 Docker 前置条件和直连 API 健康端点。
@@ -226,12 +228,12 @@ MVP 实现中，`[[plans]]` 内使用 `schedule_mode`、`start_time`、`window`
 
 * 命令示例：`pm2 start ai/coding/window-warmer/window-warmer.pm2.config.cjs`
 * 常用操作：`pm2 logs coding-window-warmer`、`pm2 restart coding-window-warmer`、`pm2 stop coding-window-warmer`、`pm2 save`。
-* 优点：不创建仓库级 Python 项目；依赖由 `uv run --script` 准备；进程重启、日志、开机恢复交给 PM2。
+* 优点：依赖由工具目录内 `pyproject.toml` / `uv.lock` 管理；进程重启、日志、开机恢复交给 PM2。
 * 缺点：需要用户本机已有 PM2 与 uv。
 
 **Option B: 手动 / 前台运行**
 
-* 命令：`uv run --script ai/coding/window-warmer/window_warmer.py --config ai/coding/window-warmer/window-warmer.toml`
+* 命令：`cd ai/coding/window-warmer && uv run python window_warmer.py --config window-warmer.toml`
 * 优点：最少魔法，日志直接在终端可见，停止方式清晰。
 * 缺点：用户需要单独启动这个脚本。
 

.trellis/tasks/05-13-litellm-coding-plan-window-warmer/research/litellm-callback-scheduler.md

@@ -110,9 +110,11 @@ Context7 查询 `/websites/litellm_ai` 后，还查到两类相关但不完全
 ## 最终实现约束
 
 * 文件位于 `ai/coding/window-warmer/`，不是 LiteLLM 网关子目录。
-* 启动命令使用 `uv run --script ai/coding/window-warmer/window_warmer.py`，脚本元数据声明 `litellm` 依赖。
-* PM2 配置调用 `uv run --script`，进程名为 `coding-window-warmer`。
+* `ai/coding/window-warmer/pyproject.toml` 通过 `uv add litellm` 声明 LiteLLM SDK 依赖，并提交 `uv.lock` 锁定解析结果。
+* 启动命令在 `ai/coding/window-warmer/` 下使用 `uv run python window_warmer.py`。
+* PM2 配置调用 `uv run python window_warmer.py`，进程名为 `coding-window-warmer`。
 * 默认 `[target].base_url` 指向 `https://open.bigmodel.cn/api/coding/paas/v4`，`api_key_env` 使用 `Z_AI_API_KEY`。
+* 默认 `[target].env_file` 指向 warmer 同目录 `.env.local`；真实 key 不入库，只提交 `.env.example`。
 * 默认 plan 模型使用 `openai/GLM-5.1`，避免 LiteLLM SDK provider 推断歧义。
 * 代码拆分为 `config`、`scheduler`、`target`、`runner`、`cli` 等模块，入口脚本保持薄封装。
 

ai/coding/window-warmer/.env.example

@@ -0,0 +1,2 @@
+# 智谱 Coding Plan API Key；window-warmer.toml 默认通过 Z_AI_API_KEY 读取。
+Z_AI_API_KEY=sk-zai-dev-xxxx

ai/coding/window-warmer/README.md

@@ -4,10 +4,12 @@
 
 ## 文件说明
 
-- `window_warmer.py`：长期运行的预热脚本，使用 PEP 723 script metadata 声明 LiteLLM 依赖。
+- `pyproject.toml` / `uv.lock`：uv 项目依赖声明与锁文件，包含 LiteLLM SDK。
+- `window_warmer.py`：长期运行的预热脚本入口。
 - `window_warmer_lib/`：配置、调度、目标检查和运行循环拆分模块。
 - `window-warmer.toml`：预热配置，支持多个 Coding Plan。
 - `window-warmer.pm2.config.cjs`：PM2 进程管理配置。
+- `.env.example`：本地 API key 示例；复制为 `.env.local` 后填写真实密钥。
 - `tests/test_window_warmer.py`：标准库 `unittest` 回归测试。
 
 ## 工作方式
@@ -20,36 +22,61 @@
 
 只有这些条件满足后，脚本才会通过 `litellm.completion(api_base=base_url, api_key=...)` 直连目标端点发送轻量预热请求。默认配置示例直连智谱 Coding Plan 官方 OpenAI 兼容端点，同时用 `container_name = "litellm"` 作为“本机网关已启动”的可选前置条件。
 
+如果不希望依赖本机 LiteLLM 容器启动状态，可以删除 `container_name`，或把它配置为空字符串。
+
+## 密钥与模型
+
+模型名写在 `window-warmer.toml` 的 `[[plans]].model` 中。使用 LiteLLM SDK 直连 OpenAI 兼容上游时，建议写成带 provider 前缀的形式，例如：
+
+```toml
+[[plans]]
+model = "openai/GLM-5.1"
+```
+
+API key 由 `[target].api_key_env` 指定变量名，脚本读取顺序是：
+
+1. 当前进程环境变量，例如 shell 里已有 `Z_AI_API_KEY=...`。
+2. `[target].env_file` 指向的 dotenv 文件，例如默认 `.env.local`。
+
+默认配置等价于读取同目录 `.env.local` 中的 `Z_AI_API_KEY`：
+
+```dotenv
+Z_AI_API_KEY=sk-zai-dev-xxxx
+```
+
+本地第一次使用时可以创建自己的密钥文件：
+
+```bash
+cd ai/coding/window-warmer
+cp .env.example .env.local
+```
+
 ## 直接运行
 
 ```bash
-uv run --script ai/coding/window-warmer/window_warmer.py \
-  --config ai/coding/window-warmer/window-warmer.toml
+cd ai/coding/window-warmer
+uv run python window_warmer.py --config window-warmer.toml
 ```
 
 查看下一次触发时间：
 
 ```bash
-uv run --script ai/coding/window-warmer/window_warmer.py \
-  --config ai/coding/window-warmer/window-warmer.toml \
-  --print-next
+cd ai/coding/window-warmer
+uv run python window_warmer.py --config window-warmer.toml --print-next
 ```
 
 立即对所有启用 plan 试跑一次：
 
 ```bash
-uv run --script ai/coding/window-warmer/window_warmer.py \
-  --config ai/coding/window-warmer/window-warmer.toml \
-  --once
+cd ai/coding/window-warmer
+uv run python window_warmer.py --config window-warmer.toml --once
 ```
 
 只打印，不发送真实请求：
 
 ```bash
-uv run --script ai/coding/window-warmer/window_warmer.py \
-  --config ai/coding/window-warmer/window-warmer.toml \
-  --once \
-  --dry-run
+cd ai/coding/window-warmer
+uv run python window_warmer.py --config window-warmer.toml --once --dry-run
 ```
 
 ## PM2 管理
@@ -132,7 +159,7 @@ retry_count = 1
 - `[target].base_url`：直连上游 OpenAI 兼容 API 的基础地址。
 - `[target].container_name`：可选 Docker 容器名；默认示例为 `litellm`。
 - `[target].api_key_env`：可选 API key 环境变量名；默认示例为 `Z_AI_API_KEY`。
-- `[target].env_file`：相对当前 TOML 文件的环境变量文件路径；默认示例指向 `../../gateway/litellm/.env.local`。
+- `[target].env_file`：相对当前 TOML 文件的 dotenv 文件路径；默认示例指向同目录 `.env.local`。
 - `[target].health_path`：可选健康检查路径；默认示例为 `/models`。
 - `[scheduler].default_jitter_seconds`：plan 未单独配置时使用的随机延迟上限。
 - `[scheduler].default_retry_count`：plan 未单独配置时的失败重试次数。
@@ -142,7 +169,8 @@ retry_count = 1
 ## 测试
 
 ```bash
-uv run --with litellm python -m unittest discover \
-  -s ai/coding/window-warmer/tests \
+cd ai/coding/window-warmer
+uv run python -m unittest discover \
+  -s tests \
   -p 'test_*.py'
 ```

ai/coding/window-warmer/pyproject.toml

@@ -0,0 +1,8 @@
+[project]
+name = "coding-window-warmer"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+    "litellm>=1.81.0",
+    "python-dotenv>=1.0.0",
+]

ai/coding/window-warmer/tests/test_window_warmer.py

@@ -4,6 +4,7 @@
 
 import random
 import sys
+import tempfile
 import unittest
 from datetime import datetime, time
 from pathlib import Path
@@ -251,6 +252,30 @@ def test_dry_run_skips_readiness_checks(self) -> None:
 
         self.assertTrue(warmer.warm_plan(config, plan, dry_run=True))
 
+    def test_read_api_key_falls_back_to_dotenv_file(self) -> None:
+        """API key 应支持从配置指定的 dotenv 文件读取。
+
+        Args:
+            None.
+
+        Returns:
+            无返回值。
+        """
+        with tempfile.TemporaryDirectory() as temp_dir:
+            env_path = Path(temp_dir) / ".env.local"
+            env_path.write_text('Z_AI_API_KEY="sk-from-file"\n', encoding="utf-8")
+            config = warmer.TargetConfig(
+                name="z-ai",
+                base_url="https://open.bigmodel.cn/api/coding/paas/v4",
+                container_name=None,
+                api_key_env="Z_AI_API_KEY",
+                env_file=env_path,
+                health_path=None,
+                request_timeout_seconds=30,
+            )
+
+            self.assertEqual(warmer.read_api_key(config), "sk-from-file")
+
 
 if __name__ == "__main__":
     unittest.main()