重构项目为LLM 驱动

.agents/docs/README.md

@@ -0,0 +1,12 @@
+# 项目维护人员文档
+
+本目录存放维护人员与自动化代理相关资料，主要用于项目运维，不属于对外公开的用户文档。
+
+- standards/：存放维护人员需遵守的规范制度与校验规则
+- plans/：存放实施方案与工作交接说明
+- error-experience/、good-experience/：存放内部经验总结文档
+- guides/：面向维护人员的工作流程及集成实操手册
+- architecture/manifest.yaml：记录可读性检查所覆盖的文件路径
+
+对外用户文档及说明文件请统一放置在 docs/ 目录下。
+

.agents/docs/error-experience/2026-06-08-LlamaIndex多模态消息格式错误.md

@@ -0,0 +1,59 @@
+---
+last_reviewed: 2026-06-09
+---
+
+# LlamaIndex 多模态消息格式错误
+
+## 错误现象
+
+```
+pydantic_core._pydantic_core.ValidationError: 2 validation errors for ChatMessage
+blocks.0
+  Unable to extract tag using discriminator 'block_type' [type=union_tag_not_found, ...
+blocks.1
+  Unable to extract tag using discriminator 'block_type' [type=union_tag_not_found, ...
+```
+
+## 触发条件
+
+- llama-index-core >= 0.14.x
+- 使用 `ChatMessage` 构造多模态消息（文本 + 图片）
+- 传入 OpenAI 格式的 `content` 列表：`[{"type": "text", ...}, {"type": "image_url", ...}]`
+
+## 原因
+
+`llama-index-core 0.14.x` 重构了 `ChatMessage` 的内部结构：
+
+| 版本 | 字段 | 多模态 content 格式 |
+|------|------|-------------------|
+| 0.14.x | `role`, `blocks`, `additional_kwargs` | `TextBlock` / `ImageBlock` 实例 |
+| 旧版本 | `role`, `content` | OpenAI 风格字典列表 |
+
+底层 Pydantic 模型使用 `block_type` 作为 union discriminator，OpenAI 格式的 `{"type": "text", ...}` 字典不包含该字段，导致验证失败。
+
+## 修复方法
+
+**正确写法（llama-index 原生 blocks 格式）：**
+
+```python
+from llama_index.core.llms import ChatMessage
+from llama_index.core.base.llms.types import ImageBlock, TextBlock
+
+messages = [
+    ChatMessage(role="system", content=system_prompt),
+    ChatMessage(
+        role="user",
+        blocks=[
+            TextBlock(text="请分析这张图片"),
+            ImageBlock(
+                url=f"data:image/jpeg;base64,{image_b64}",
+                detail="high",
+            ),
+        ],
+    ),
+]
+```
+## 适用版本
+
+- llama-index-core: 0.14.22
+- llama-index-llms-openai-like: 0.7.2

.agents/docs/guides/工程实践指南.md

@@ -0,0 +1,261 @@
+---
+last_reviewed: 2026-06-09
+---
+
+# 工程实践指南
+
+创建或修改任何 Python 项目时，必须严格遵守以下工程规范。
+
+---
+
+## 1. 包管理与虚拟环境
+
+- **唯一包管理器**：使用 `uv`，不使用 `pip`、`pipenv`、`poetry`。
+- **依赖声明**：所有依赖统一在 `pyproject.toml` 中管理，遵循 PEP 621 + PEP 735。
+  - `[project].dependencies` 仅放运行时依赖。
+  - `[dependency-groups].dev` 放开发依赖（测试、lint、类型检查等）。
+- **版本锁定**：使用 `uv.lock` 锁定依赖版本，提交到版本控制。
+- **安装命令**：`uv sync` 创建虚拟环境并安装所有依赖。
+- **运行命令**：所有 Python 命令通过 `uv run` 前缀执行，确保使用项目虚拟环境。
+- **禁止**：全局安装 Python 包、手动 `python -m venv`、使用 `requirements.txt` 作为主要依赖文件。
+
+### `pyproject.toml` 必填字段模板
+
+```toml
+[project]
+name = "<project-name>"
+version = "0.1.0"
+description = "<项目描述>"
+requires-python = ">=3.12"
+dependencies = [
+    # 运行时依赖
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.9",
+    "mypy>=1.14",
+    "deptry>=0.22",
+    "pre-commit>=4.0",
+]
+```
+
+---
+
+## 2. 目录结构
+
+```
+<project-root>/
+├── pyproject.toml          # 项目配置（依赖 + 工具配置）
+├── uv.lock                 # 依赖锁定文件
+├── .pre-commit-config.yaml # 提交前检查配置
+├── Makefile                # Unix 任务脚本
+├── tasks.py                # Windows/跨平台任务脚本
+├── .cursorignore           # IDE 忽略配置
+├── src/                    # 源代码目录
+│   └── main.py
+├── tests/                  # 测试目录
+│   └── test_main.py
+└── logs/                   # 运行时产物（不提交）
+```
+
+- 源码统一放在 `src/` 下，不直接在根目录放业务代码。
+- 测试统一放在 `tests/` 下。
+- 运行时产物（日志、缓存、临时文件）不提交到版本控制。
+
+---
+
+## 3. 代码质量工具链
+
+### 3.1 Ruff（Lint + Format）
+
+在 `pyproject.toml` 中配置：
+
+```toml
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B"]
+ignore = ["E501"]
+```
+
+- **规则覆盖**：格式错误(E/F/W)、导入排序(I)、命名规范(N)、语法升级(UP)、常见 Bug(B)。
+- **格式化**：使用 `ruff format` 替代 Black。
+- **运行方式**：
+  - `uv run ruff check .` — 检查问题
+  - `uv run ruff check --fix .` — 自动修复
+  - `uv run ruff format .` — 格式化代码
+  - `uv run ruff format --check .` — 仅检查格式
+
+### 3.2 MyPy（静态类型检查）
+
+```toml
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+ignore_errors = true
+```
+
+- 启用严格模式，测试文件豁免。
+- **运行方式**：`uv run mypy src/main.py`
+
+### 3.3 Deptry（依赖审计）
+
+```toml
+[tool.deptry]
+ignore_notebooks = true
+```
+
+- 检测未使用、缺失、重复的依赖。
+- **运行方式**：`uv run deptry .`
+
+---
+
+## 4. 测试规范
+
+### 4.1 Pytest 配置
+
+```toml
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+```
+
+### 4.2 测试要求
+
+- 测试文件命名：`test_*.py`，放在 `tests/` 目录。
+- 测试函数/类命名：以 `test_` 或 `Test` 开头。
+- 使用 `pytest.fixture` 管理测试资源。
+- 必须使用 `pytest-cov` 生成覆盖率报告。
+- **运行方式**：
+  ```bash
+  uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=term-missing
+  ```
+
+---
+
+## 5. Pre-commit Hooks
+
+`.pre-commit-config.yaml` 必须包含：
+
+```yaml
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+```
+
+- 安装：`uv run pre-commit install`
+- 手动运行：`uv run pre-commit run --all-files`
+
+---
+
+## 6. 任务运行器
+
+### 6.1 Makefile（Unix）
+
+```makefile
+.PHONY: install check test run clean
+
+install:
+	@uv sync
+	@uv run pre-commit install
+
+check:
+	@uv lock --locked
+	@uv run ruff check .
+	@uv run ruff format --check .
+	@uv run mypy src/main.py
+	@uv run deptry .
+
+test:
+	@uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=term-missing
+
+run:
+	@uv run python src/main.py
+
+clean:
+	@rm -rf .venv __pycache__ .pytest_cache .mypy_cache .ruff_cache
+```
+
+### 6.2 tasks.py（跨平台）
+
+提供 `tasks.py` 作为 Windows 兼容的任务运行器，支持相同任务名：`install`、`check`、`test`、`run`、`clean`。
+
+---
+
+## 7. 版本控制忽略
+
+`.cursorignore` / `.gitignore` 必须排除：
+
+```
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.pyc
+logs/
+```
+
+---
+
+## 8. 开发工作流
+
+新项目初始化顺序：
+
+1. 创建 `pyproject.toml`，声明项目元数据和依赖。
+2. 运行 `uv sync` 创建虚拟环境。
+3. 创建 `.pre-commit-config.yaml`，运行 `uv run pre-commit install`。
+4. 创建 `src/` 目录和入口文件。
+5. 创建 `tests/` 目录和基础测试。
+6. 创建 `Makefile` + `tasks.py`。
+7. 运行 `make check` 或 `python tasks.py check` 验证代码质量。
+8. 运行 `make test` 或 `python tasks.py test` 验证测试通过。
+
+日常开发顺序：
+
+1. `uv run ruff check --fix .` — 先修复 lint 问题。
+2. `uv run ruff format .` — 格式化代码。
+3. `uv run mypy src/` — 类型检查。
+4. `uv run python -m pytest` — 运行测试。
+5. 提交前 pre-commit 会自动执行检查和格式化。
+
+---
+
+## 9. 编码风格
+
+- Python 3.12+ 语法，使用现代特性（如 `match/case`、类型合并 `X | Y`）。
+- 函数和模块必须有 docstring。
+- 优先使用类型注解，返回值类型必须标注。
+- 行长度限制 120 字符。
+- 导入按标准库 → 第三方 → 本地模块分组排序。
+- 偏好函数式编程风格，避免不必要的面向对象封装。
+- 配置与代码分离，使用常量或配置模块管理可变参数。
+
+---
+
+## 10. 强制检查清单
+
+在提交代码或声明任务完成前，必须确认：
+
+- [ ] `uv lock --locked` 通过（锁定文件与 pyproject.toml 一致）
+- [ ] `uv run ruff check .` 无错误
+- [ ] `uv run ruff format --check .` 无差异
+- [ ] `uv run mypy src/` 无类型错误
+- [ ] `uv run deptry .` 无依赖问题
+- [ ] `uv run python -m pytest --cov` 全部通过且覆盖率合理
+- [ ] 所有命令使用 `uv run` 前缀，无全局 pip 操作

.agents/docs/standards/README.md

@@ -0,0 +1,9 @@
+---
+last_reviewed: 2026-06-09
+---
+
+# 标准元数据
+
+`.agents/docs/standards/*.md` 下所有文件都必须包含 frontmatter，字段包括：
+
+- `last_reviewed`：最近一次策略审查的 ISO 日期 `YYYY-MM-DD`。

.agents/docs/standards/复利式工程实践.md

@@ -0,0 +1,13 @@
+---
+last_reviewed: 2026-06-09
+---
+
+# 复利式工程实践
+
+记录经验教训：
+* 错误经验：`.agents/docs/error-experience/YYYY-MM-DD-<slug>.md`
+* 正向经验：`.agents/docs/good-experience/YYYY-MM-DD-<slug>.md`
+* 计划：`.agents/docs/plans/`
+* 指南：`agents/docs/guides/`
+
+在出现重大 bug、CI 失败或发现有价值模式后，创建一条条目并记录根因与经验。

.agents/docs/standards/调试规范.md

@@ -0,0 +1,34 @@
+---
+last_reviewed: 2026-06-09
+---
+# 调试规范
+
+## 调试前检查清单
+
+在循环调试任务前，需完成以下检查：
+
+1. 梳理代码链路（最长耗时 5 分钟）。从入口函数追踪至异常执行环节，排查硬编码值、参数缺失或分支逻辑异常等问题。
+2. 对比正常与异常场景。若功能 A 运行正常、功能 B 出现故障，梳理二者代码链路的差异，问题通常就出在差异部分。
+3. 排查基础配置项。检查代理设置、环境变量、端口号、功能开关等。多数故障由配置问题导致，而非代码逻辑错误。
+
+## 调试过程要求
+
+1. 两次尝试原则。若同一排查方式（重跑测试、调整参数等）连续失败两次，立即停止，更换排查思路：
+    * 增加针对性日志或打印语句
+    * 阅读异常依赖库的源码
+    * 精简代码，复现最小故障案例
+    * 反思：自身哪些预设判断可能存在偏差
+2. 禁止无限循环调试。定时任务仅用于监控正常运行的进程，不可作为调试工具。若定时循环连续两轮无进展，关闭循环，转为人工调试。
+3. 记录排查思路。每开始一次尝试前，做好记录：
+    * 初步判断的问题原因
+    * 用于验证猜想的依据
+    * 本次准备执行的操作
+    * 避免重复无效尝试与逻辑死循环
+
+## 调试收尾工作
+
+1. 编写经验文档。所有非简单故障的调试工作，均需在`.agents/docs/error-experience/` 目录下新建记录文档，内容包含：
+    * 故障现象
+    * 历次排查操作及失败原因
+    * 最终解决方案
+    * 后续可借鉴的调试经验