AGENTS.md

仓库维护指南

项目定位

这个仓库是 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 下载大模型；只有真实推理验证才下载模型。

检查命令

交付改动前运行：

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 和文件上传请求。