# Handoff - 2026-05-18

## Completed Tasks
- 创建并完善 `AGENTS.md`，明确仓库结构、文档规范、测试方式和贡献要求。
- 编写 `plan.md`，完成 DOCX 规范分析 Web 应用的方案设计，比较 Python 与 HTML/CSS/JavaScript 技术路线，并确定 FastAPI + 简洁前端的实现方案。
- 基于 TDD 开发简易 DOCX 规范分析 Web 应用，新增 FastAPI 后端、DOCX 解析、技能加载、技能匹配、模型调用、Markdown 报告生成和下载功能。
- 添加简洁 Web UI，支持上传 `.docx` 文件、选择模型供应商、提交分析任务并下载 Markdown 分析报告。
- 增加分析进度提示栏，将 `/analyze` 改为后台任务模式，并通过 `/tasks/{task_id}` 实时轮询分析状态。
- 暂停 DOCX 报告下载入口，仅保留 Markdown 分析文档下载。
- 使用 `test/测评报告.docx` 完成本地分析验证，并用 DeepSeek 配置验证 OpenAI 兼容模型 API 调用链路。
- 使用 `uv` 管理项目依赖，补充 `pyproject.toml`、`uv.lock`、测试用例和命令行分析脚本。
- 编写并多次修订 `plant.md`，形成 Ubuntu 20.04 内网离线迁移步骤，包括 wheelhouse 打包、清华源使用、`lxml` 构建依赖、便携 Python 运行时准备和 `uv` 离线同步。

## Blockers
- `uv pip download` 在当前 `uv` 版本中不可用，需要改用 `pip wheel` 或 `pip download`。
- 当前 `.venv/bin/python3.12` 只是指向系统 Python 的符号链接，不能作为独立可移植 Python 运行时打包。
- 系统 `/usr/bin/python3` 初始缺少 `pip`，需要安装 `python3-pip`。
- 下载或构建 `lxml==6.1.0` 时可能因镜像源不全或缺少系统编译依赖失败，需要安装 `build-essential`、`libxml2-dev`、`libxslt1-dev`、`zlib1g-dev`、`python3-dev`，并可切换到官方 PyPI。
- 使用 `uv python install --install-dir /opt/python-3.12` 需要写入 `/opt` 权限；`sudo uv` 找不到命令时，需要使用 `/home/zjz/.local/bin/uv` 的绝对路径或将 `uv` 复制到 `/usr/local/bin/uv`。
- `uv python install` 生成的 Python 可执行文件位于版本子目录，如 `/opt/python-3.12/cpython-3.12.13-linux-x86_64-gnu/bin/python3.12`，不是 `/opt/python-3.12/bin/python3.12`。

## Next Steps
- 按 `plant.md` 在准备机上重新执行离线打包流程，确认 `wheelhouse/` 中包含所有运行依赖。
- 使用 `find /opt/python-3.12 -path '*/bin/python3.12' -print` 确认便携 Python 真实路径，并打包 `python-3.12-runtime.tar.gz`。
- 将项目源码、`wheelhouse/`、`requirements.txt`、`uv.lock`、`uv` 可执行文件和 Python 运行时包拷贝到 Ubuntu 20.04 内网服务器。
- 在内网服务器上创建 `.venv`，执行 `uv sync --frozen --offline` 或使用 wheelhouse 离线安装依赖。
- 启动 FastAPI 服务并用 `test/测评报告.docx` 验证上传、进度轮询、模型调用和 Markdown 报告下载流程。
- 确认 `configs/api_config.yaml` 的 `intranet` 模型地址、端口和网络连通性，并在验证通过后编写 `systemd` 服务文件用于长期运行。
