skills upload function handoff

handoff-2026-05-26-10-56-09.md

@@ -0,0 +1,25 @@
+# Handoff - 2026-05-26
+
+## Completed Tasks
+- 将技能合集列表从固定常量改为动态扫描 `skills/` 下包含 `index.md` 的目录，解决后台新增 `skills/interesting_physics_skills` 后前端“技能合集”下拉框不显示的问题。
+- 新增 `GET /skill-collections` 接口，用于前端实时刷新可用技能合集列表。
+- 新增 `POST /skill-collections/upload` 接口，严格限制上传 `.zip` 技能合集压缩包，并按 `skills/<压缩包文件名去掉.zip>/` 的规范解压安装。
+- 为 zip 安装流程增加校验：有效 zip、根目录必须包含 `index.md`、拒绝路径穿越、拒绝空包、拒绝无有效 `SKILL.md` 的合集。
+- 在前端新增简洁的“上传技能合集”区域，上传成功后显示提醒，并立即刷新“技能合集”下拉框且选中新上传的合集。
+- 修正首页顶部技能合集数量展示，改为显示当前动态发现的合集数量。
+- 补充测试覆盖动态发现后台新增目录、上传 zip 后解压并进入列表、拒绝非 zip、拒绝非法路径 zip。
+- 执行验证：`python -m pytest -q` 通过，结果为 `17 passed in 6.91s`；`git diff --check` 通过。
+- 启动本地 FastAPI 服务用于页面验证，当前地址为 `http://127.0.0.1:8002`。
+
+## Blockers
+- 当前 zip 格式按现有 `skills/GJB438B-2009_prd_skills.zip` 规范处理，即 `index.md` 必须位于压缩包根目录；如果后续需要支持“压缩包内再包一层目录”的格式，需要补充规范转换逻辑。
+- 上传同名合集时当前实现会用新解压内容替换 `skills/<合集名>/`，需要在后续产品设计中确认是否增加覆盖确认、版本备份或回滚能力。
+- 本地测试中 `fastapi.testclient.TestClient` 在当前环境会挂起，因此测试改为直接调用异步路由函数和安装函数；后续如升级依赖或调整测试环境，可再恢复端到端 HTTP 客户端测试。
+- 默认端口 `8000` 和 `8001` 启动失败，最终使用 `8002` 启动服务。
+
+## Next Steps
+- 明天使用真实技能合集 zip 在浏览器中做一次完整手工验证：上传、成功提示、下拉框刷新、选择新合集并执行 DOCX 分析。
+- 为上传同名合集补充更明确的管理策略，例如覆盖确认、保留上一版本备份或禁止覆盖。
+- 评估是否支持多种 zip 打包结构，并在文档中明确技能合集 zip 的标准目录格式。
+- 考虑增加前端上传状态样式区分，例如成功、失败、校验错误使用不同颜色，但保持当前页面简洁风格。
+- 如后续要正式部署，补充接口级日志，记录上传合集名称、技能数量、校验失败原因和安装时间。