docs: add chinese project docs

.pre-commit-config.yaml

@@ -0,0 +1,6 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.12
+    hooks:
+      - id: ruff-check
+        args: [--fix]

AGENTS.md

@@ -0,0 +1,50 @@
+# 仓库维护指南
+
+## 项目定位
+
+这个仓库是 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`：模型列表、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 选项或评分公式。
+- `ModelWithPooling` 使用 Hugging Face `AutoTokenizer` 和 `AutoModel`；UI 暴露的 pooling 模式是 `mean` 和 `cls`。
+- 避免在 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` 和文件上传请求。

README.md

@@ -11,6 +11,80 @@ pinned: false
 license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## 项目用途
 
-["Automatic Assessment of Divergent Thinking in Chinese Language with TransDis: A Transformer-Based Language Model Approach"](https://arxiv.org/abs/2306.14790)
+TransDis-CreativityAutoAssessment 是一个用于自动评估发散思维回答的 Gradio 应用。它目前支持两类评分：
+
+- **Originality**：计算每条 `prompt` 与 `response` 之间的语义距离，用于估计回答的独创性。
+- **Flexibility**：计算同一 `id` + `prompt` 分组内多条回答之间的语义距离，用于估计回答的灵活性。
+
+本应用基于论文 ["Automatic Assessment of Divergent Thinking in Chinese Language with TransDis: A Transformer-Based Language Model Approach"](https://arxiv.org/abs/2306.14790)。
+
+## 输入格式
+
+可以直接在文本框中粘贴 CSV 文本，也可以上传 `.csv` / `.xlsx` 文件。如果同时提供文本框和文件输入，上传文件优先。
+
+`Originality` 任务需要提供：
+
+```csv
+id,prompt,response
+1,床单,过滤器
+1,bedsheet,used as a filter
+```
+
+`Flexibility` 任务需要为同一个被试和同一个提示词提供多条回答：
+
+```csv
+id,prompt,response
+1,床单,过滤器
+1,床单,做成渔网捞鱼
+1,床单,做成枕头
+```
+
+单次请求最多处理 10,000 行数据。
+
+## 模型选择
+
+应用会在下拉菜单中提供多语言、英文和中文 Transformer 检查点。默认模型是：
+
+```text
+sentence-transformers/paraphrase-multilingual-mpnet-base-v2
+```
+
+可选 pooling 方式是 `mean` 和 `cls`。如果使用 `bert-base-chinese`，建议选择 `mean` pooling。
+
+## 本地开发
+
+此 Space 使用 Python 3.11 和 Gradio 6.14.0。Gradio 版本由 README 顶部的 Space metadata 控制，因此不会写入 `requirements.txt`。
+
+```bash
+python3.11 -m venv .venv
+source .venv/bin/activate
+pip install gradio==6.14.0 -r requirements.txt
+python app.py
+```
+
+安装并运行 pre-commit：
+
+```bash
+uvx pre-commit install
+uvx pre-commit run --all-files
+```
+
+推送前建议运行：
+
+```bash
+python3 -B -m py_compile app.py utils/pipeline.py utils/models.py
+uvx pre-commit run --all-files
+```
+
+## Hugging Face Space
+
+此 Space 由 README 顶部的 YAML 配置：
+
+- `sdk: gradio`
+- `sdk_version: 6.14.0`
+- `python_version: "3.11"`
+- `app_file: app.py`
+
+推送到 Space 仓库后，Hugging Face 会自动重建并重启应用。