| name | resmax-init |
| description | Initialize a freshly cloned Resmax checkout. Use when Codex needs to guide first-time setup, materialize local env files from templates, collect required API keys or machine config through questions, restore or build paper_database artifacts, explain hard vs soft requirements, and verify the repo is ready for resmax-database, resmax-embedding, or resmax-survey. |
resmax-init
目标
用于新 clone 的 resmax 仓库初始化：生成本地 .env、通过问答补齐必要配置、选择数据库/评审/embedding 产物来源，并把最终状态验证到能安全进入生产流程。
不要把它当成“静默 bootstrap 脚本”。用户相关的决定必须显式询问；脚本只负责审计状态和给出缺口。
固定入口
当用户要求执行 resmax-init skill 时，agent 先运行审计；新 clone 或模板缺失时加 --materialize。如果初始化目标需要同时处理大文件数据恢复，加 --with-data。这些命令是 skill 内部入口，不是 README 面向普通用户的主流程：
python3 .agents/skills/resmax-init/scripts/resmax_init_check.py --materialize
python3 .agents/skills/resmax-init/scripts/resmax_init_check.py --materialize --with-data
需要机器可读输出时：
python3 .agents/skills/resmax-init/scripts/resmax_init_check.py --materialize --json
普通审计只创建空的本地 .env，不会填入密钥，不会下载数据，不会启动长任务。--with-data 是交互模式：当 accepted_index.csv、manifest.json、qwen3_8b.npz 或 review package 缺失时，必须先询问用户是否有 max6616/resmax 私有 HF dataset 的 read token。
问答原则
- 所有用户特定信息都用提问获得，不猜测、不硬编码。
- 选择类问题提供有限选项；例如初始化目标、数据库来源、是否允许 Sci-Hub、是否配置远程 GPU。
- API key、密码、token、用户名、邮箱、SSH host、HF repo id 使用自由填写；不要提供假选项。
- optional / soft 字段允许用户留空；说明留空后的降级结果。
- hard-required 字段缺失时，终止当前步骤，说明需要哪个值、写入哪个
.env、为什么需要，然后等待用户补充。
- 如果当前客户端支持结构化提问工具，choice 问题用选项，secret/config 问题用自由输入；否则在聊天里逐题问。不要在最终回复复述密钥原文。
初始化问卷
按审计结果裁剪问题，避免一次性索要无关信息。
1. 初始化目标
先问用户要做到哪一层：
config-only：只补配置文件，不准备数据库。database-ready：准备 accepted_index.csv、manifest、reviews；若没有 embedding cache，只能算数据库层准备好，不能宣称 validator overall=PASS。survey-ready：数据库和 embedding cache 都可用，可跑 resmax-survey 生产检索。embedding-build：配置远程 GPU 并构建/刷新 embedding cache。
2. 大文件数据来源
如果 paper_database/accepted_index.csv、paper_database/manifest.json、paper_database/embedding_cache/qwen3_8b.npz 或 paper_database/hf_export/reviews/reviews_manifest.json 任一缺失，只问一个问题：
skip-no-token-build-from-sources：用户没有 read token，完全跳过 HF 文件下载；明确提示需要用 resmax-database 从头构建 CSV/reviews，再用 resmax-embedding 构建 .npz，不能把当前状态当成 survey-ready。use-read-token-download：用户有 read token，读取 token 后自动调用统一数据命令：
python3 scripts/resmax_data.py pull --repo-id max6616/resmax
token 不写入 git-tracked 文件，也不写入 .localconfig/；只通过本次进程环境传给下载脚本。若用户已经 hf auth login 或设置了 HF_TOKEN，token 输入可留空。
3. 从源头构建时的 embedding
如果用户选择 skip-no-token-build-from-sources，CSV/reviews 需要先由 resmax-database 从源头构建，embedding 再按生产目标处理：
remote-build：配置 SSH GPU 并运行 resmax-embedding。skip-production：只允许开发 smoke 的关键词降级，不能作为生产验收。
4. 灰色来源策略
Sci-Hub 默认关闭。只有用户明确选择才可在 Stage 5.5 deepcheck 传 --enable-sci-hub：
disabled：默认；只使用合法 OA / publisher / arXiv / OpenReview 等来源。ask-each-time：每次 deepcheck 前再确认。enabled-for-this-run：仅本次运行允许；不要写成全局默认。
如用户选择启用且需要自定义镜像，再让用户自由填写 RESMAX_SCI_HUB_MIRRORS；否则不要创建该变量。
配置字段规则
硬依赖：
OPENREVIEW_USERNAME / OPENREVIEW_PASSWORD：仅在 OpenReview fetch 模式必填；--rehydrate / --mark-unavailable 不需要。RESMAX_SSH_HOST：仅当本机无法编码 query 且需要 SSH fallback，或要远程构建 embedding 时必填。RESMAX_HF_DATASET_REPO：非密钥，默认 max6616/resmax；只有使用自定义 HF dataset repo 时需要修改。
软依赖：
GITHUB_TOKEN：缺失时 GitHub API 降到 60 req/h。OPENALEX_API_KEY：缺失时期刊抓取额度低。S2_API_KEY：缺失时 Semantic Scholar 仍可用但更容易限流。SERPAPI_KEY：缺失时跳过 Google fallback。RESMAX_CONTACT_EMAIL：缺失时使用默认联系邮箱，礼貌池和限流表现可能变差。RESMAX_SSH_REMOTE_DIR / RESMAX_SSH_REMOTE_SCRIPT / RESMAX_SSH_CONDA_ENV / RESMAX_SSH_CONDA_INIT：有模板默认值，按用户机器修改。RESMAX_HF_REVIEWS_PATH / RESMAX_HF_REPO_TYPE：有默认值，通常无需改。
写入协议
- 真实值只写入
.secrets/*.env 或 .localconfig/*.env，这些文件被 gitignore。
.secrets/*.env 创建或改写后设置为 0600。- 如果目标
.env 不存在，先从对应 .env.example 复制。
- 写入格式使用
export KEY='value'；已有同名 key 时更新，不重复追加。
- 不要把用户密钥写入
README、SKILL.md、Python 脚本、git-tracked config 或最终总结。
执行路线
配置完成后按目标运行：
database-ready：
python3 scripts/resmax_data.py pull --repo-id max6616/resmax
如果没有 HF read token，则使用从源头构建路线：
python3 .agents/skills/resmax-database/scripts/normalize_database.py \
--csv paper_database/accepted_index.csv \
--manifest paper_database/manifest.json
python3 .agents/skills/resmax-database/scripts/ensure_reviews_available.py \
--csv paper_database/accepted_index.csv \
--reviews-dir paper_database/reviews \
--package-dir paper_database/hf_export/reviews
如果 embedding cache 已存在，继续跑完整验证：
python3 .agents/skills/resmax-database/scripts/validate_database.py \
--csv paper_database/accepted_index.csv \
--cache paper_database/embedding_cache/qwen3_8b.npz \
--manifest paper_database/manifest.json \
--out paper_database/validate_report.json
如果 embedding cache 不存在，停止在数据库层并明确告诉用户：validate_database.py 的 hard requirement 包含 cache 对齐，不能把该状态当成 survey-ready。
survey-ready：先确保 database-ready，再确认 embedding cache 存在且 validator overall=PASS。缺 cache 时转 resmax-embedding，不要绕过生产门槛。
embedding-build：转 resmax-embedding，先确认远程 GPU 空闲，再运行长任务。
终止条件
- hard-required 值缺失且用户未提供：停止，不重试。
- 用户选择
skip-no-token-build-from-sources：停止 HF 下载路线，只报告从源头构建 CSV/reviews 和 embedding 的下一步。
- 下载、checksum、CSV hash、manifest 或 validator 失败：停止并报告失败原因，不降级。
- 用户未明确允许 Sci-Hub：不得启用 Sci-Hub fallback。
