# 仓库维护指南

## 项目定位

这个仓库是 TransDis-CreativityAutoAssessment 的 Hugging Face Gradio Space。它使用 Transformer embedding 对发散思维数据进行评分，并对外提供两个任务：`Originality` 和 `Flexibility`。

`README.md` 是公开项目说明和 Space 入口文档；`AGENTS.md` 是后续 coding agent 的实现与维护指南。不要把维护规则塞进 README，也不要把用户说明写成 AGENTS 的主要内容。

## 主要文件

- `app.py`：Gradio UI、输入解析、行数限制、任务分发、输出 CSV 生成。
- `utils/pipeline.py`：`Originality` 和 `Flexibility` 的评分流程。
- `utils/models.py`：模型列表、embedding adapter registry、tokenizer/model 加载、pooling 行为。
- `data/description.txt`：Space 页面中展示的长篇双语说明。
- `.pre-commit-config.yaml`：本地 Ruff pre-commit hook。

## 运行时规则

- Gradio SDK 版本写在 `README.md` 顶部的 YAML metadata 中；除非 Space 部署方式改变，不要把 `gradio` 加进 `requirements.txt`。
- `requirements.txt` 只放运行时依赖。影响 Space 重建稳定性的包应使用有边界的版本范围。
- Space 运行时是 Python 3.11。检查依赖或 Gradio 行为时，本地 smoke test 也应对齐 Python 3.11。
- 除非用户明确要求改性能策略，否则保留 `concurrency_limit=1`、`max_threads=1` 和 10,000 行输入上限。

## 数据与 API 契约

- 文本输入是 CSV 文本。文件输入接受 `.csv` 和 `.xlsx`；如果文本和文件同时存在，文件输入优先。
- `Originality` 需要 `prompt` 和 `response` 列。
- `Flexibility` 需要 `id`、`prompt` 和 `response` 列。
- `process()` 按顺序返回三个输出：错误/状态文本、预览 dataframe、可下载文件路径。
- 错误输出必须是字符串，因为它由 `Textbox` 渲染。
- 输出文件应使用唯一临时 CSV 路径，不要共用固定的 `output.csv`，避免并发或重复请求互相覆盖。
- 文件输入处理应继续兼容这些 Gradio 值形态：filepath 字符串、`os.PathLike`、带 `.name` 的对象、或包含 `path` 的 dict。

## 模型与评分规则

- 除非用户明确要求模型或评分变化，不要修改模型下拉列表、默认模型、pooling 选项或评分公式。
- `utils.models.get_embedding_model()` 是评分流程的统一模型入口。legacy 模型走 `ModelWithPooling`，使用 Hugging Face `AutoTokenizer` 和 `AutoModel`；`Qwen/Qwen3-Embedding-0.6B` 走专用 adapter，自动使用官方推荐的 last-token pooling 和向量归一化。
- UI 使用 Gradio `Blocks` 实现，但视觉结构应保持原来的左右两列：左侧输入、右侧输出。legacy 模型的 pooling 选项是 `mean` 和 `cls`；选择 `Qwen/Qwen3-Embedding-0.6B` 时，UI 应切换并锁定为 `last-token`，后端也应通过 `effective_pooling()` 兜底强制。
- 避免在 app 启动时提前加载模型。模型下载和加载应只在处理请求时发生。
- 做轻量本地测试时，优先 monkeypatch `pipeline.p0_originality` / `pipeline.p1_flexibility`，不要为了普通 smoke test 下载大模型；只有真实推理验证才下载模型。

## 检查命令

交付改动前运行：

```bash
python3 -B -m py_compile app.py utils/pipeline.py utils/models.py
uvx pre-commit run --all-files
```

如果改动涉及 Gradio 或依赖升级，还要运行 Python 3.11 smoke test：导入 `app`、检查 `gradio.__version__`、确认 `app.app` 可以构建。如果可以推送到 Hugging Face，则继续确认 Space 进入 `RUNNING`，并通过 Gradio queue API 运行最小 `Originality`、`Flexibility` 和文件上传请求。