01 / GET STARTED
安装 CLI
需要 Python 3。CLI 仅使用标准库,无需安装 Python 第三方包。
以上 PATH 设置对当前终端生效。新终端如找不到命令,可使用 ~/.local/bin/questionhub,或把 PATH 设置加入自己的 shell 配置。
02 / PREPARE WITH AN AGENT
安装上传 skill
下载 skill 包,解压后将 questionhub-upload 目录放入你的 Agent 支持的 skills 目录,然后让 Agent 读取其中的 SKILL.md。
可以给 Agent 这样的任务:
使用 questionhub-upload skill,检查并补齐这个题包的中英文题面和中文题目解读,查询网站已有方向后上传,并下载一次核对。
Skill 指导 Agent 直接翻译并核对语义。CLI 的结构检查不能代替科学核对。交互图解由平台后续制作。
03 / CHOOSE A DIRECTION
查询领域与研究方向
上传时使用命令返回的领域 ID 与方向 ID;界面名称与命令参数分开显示。
核聚变现有仿星器的 12 个研究方向,后续会继续扩充。请使用命令实际返回的可用方向,不自行填写新的方向名称。
04 / CHECK THE PACKAGE
检查题包
同一题目根目录必须包含 instruction_ch.md、instruction_en.md 和 interpretation.md。解读使用中文;保留题目实际需要的数据、代码及运行文件。
解读与题面的目录关系
三个文件名使用以下小写拼写,并且必须同层。一个 ZIP 只包含一道题,只有一个完整题目根;数据和代码的子目录按原题实际需要保留。
question-pack/ # 可选角色外层
task/ # 可保留已有题目目录,名称不限
instruction_ch.md
instruction_en.md
interpretation.md # 与两版题面同层
data/ # 如题目需要
src/ # 如题目需要也可去掉外层目录,直接将三个文档和运行文件放在 ZIP 根层。检查会识别唯一题目根 task_root;上例为 task,根层打包时为 .。上传后网站保存该路径,按当前题包版本读取其下的 interpretation.md,避免读到示例目录的同名文件。缺少文档、三份文档不在同一目录或存在多个完整题目根时,检查失败。
把题目讲给领域零基础读者听
解读要直白解释:科研问题与价值、已有方法、主要复现 baseline 及其已知结果和卡点、本题目标、优化指标及含义、得分判定与依据,以及突破可能带来的科研价值。
解释必要术语,用具体例子连接问题与指标;未运行的复现、未知结果如实写明。写作模板位于 skill 包的 questionhub-upload/references/interpretation-template.md,目录细则位于 references/package-checklist.md。
先修复检查结果列出的缺项,再上传。
05 / UPLOAD A QUESTION
独立上传题包
下面以量子领域的“纠错码搜索”为例。名称填写真实中文标题,标识用于后续更新。
上传命令会再次检查题包结构。更新已有条目时保留原标识、领域和方向;未提交的其他资源保持不变。题面和解读上传后立即展示。可选上传自定义静态图谱;未提供时进入平台制作队列。
06 / UPLOAD MATERIALS
独立上传参考材料
材料使用自己的 ZIP 和条目标识,可直接放参考文件,或使用 source_materials/ 外层。无需双语题面、题目解读或 README;不运行题包内容检查。
07 / OPTIONAL VISUALIZATION
可选上传自定义交互图谱
通过 CLI 上传一个静态 ZIP,根目录为 index.html。章节、图表与交互形式自由,不要求固定的五部分。React、Vue 等项目先构建成静态文件,再打包构建产物。
visualization.zip
├── index.html
├── assets/
│ ├── app.js
│ └── style.css
└── data/
└── metrics.json入口、CSS、JS、字体、图片和数据都放在 ZIP 内,使用相对路径;数据请求相对于入口页面,模块导入相对于模块文件。不依赖 CDN、外部接口、服务器进程或登录状态。论文链接可作为普通链接打开。
随题包上传时,在 upload-question 的参数中增加 --visualization visualization.zip;也可以题包上传成功后单独添加或更新。ZIP 上限 50 MiB,解压总量上限 100 MiB。必须共用重复内容资源,不能包含重复路径、符号链接或越界路径。
检查通过直接展示。平台检查归档、入口和可识别的本地资源引用,并在隔离页面中运行图谱;检查不代替作者对科学内容、动态资源与交互效果的核对。页面不访问本站上传接口、父页面、Cookie 或浏览器存储;可以嵌入包内的静态子页面,不支持 eval 或远程依赖。
图谱绑定上传时的准确题包版本。单独更新图谱只更新图谱及题目集合版本;更新材料会保留有效图谱;题包更新后旧图谱隐藏,需要针对新题包重新上传。题包和图谱分两步上传,若图谱步骤失败,已经成功的题包会保留,可用 upload-visualization 重试。手动上传页面只支持题包和材料。
07 / BROWSE AND VERIFY
查看与下载
--part 支持 question_pack、source_materials 、visualization 与 all。上传后下载一次,核对文件与语言版本是否齐全。
遇到问题
- 提示缺少文档
- 按照错误列出的具体路径补齐文件,并再次执行 check。把几个题包混装到一个 ZIP 不能代替同一题目根目录。
- 方向不可用或与原条目不一致
- 重新运行 directions;更新时使用原领域与方向。
- 上传等待较久或连接中断
- 先运行 list 确认条目是否已登记,必要时下载核对;避免未查结果便反复重传。
全局参数 --url 放在子命令前。更详细的参数以 questionhub --help 和对应子命令的 --help 为准。