本地 CLI

oneai CLI 已实现，但尚未发布到包仓库。下面的输出取自验收时的实测。需要 Node.js 20.11 或更新版本。三个操作系统的实测与下载渠道随正式发布提供。

安装

渠道公布前，CLI 以 oneai-cli-<version>.tgz 文件提供，附同名 .sha256 文件。不要从别处安装同名包。

sha256sum -c oneai-cli-0.1.0.tgz.sha256
npm install -g ./oneai-cli-0.1.0.tgz
oneai version            # oneai 0.1.0

安装更新的文件即原地升级。oneai help 列出全部命令。

profile 与凭据存储

profile 记录服务地址、工作区和账号；凭据按 profile 与地址分开保存，不会发往其他 origin。

oneai profile set --endpoint "$ONEAI_ORIGIN" [--workspace <id>] [--credential-store file]

凭据默认存进系统钥匙串（macOS 钥匙串、Linux Secret Service）。没有可用钥匙串时，CLI 报credentials.unavailable；要用只有本人可读的文件，须显式选 --credential-store file。ONEAI_CONFIG_DIR 可改配置目录。

登录

oneai login 以 client oneai-cli 走设备授权，只有地址和用户码写到 stderr：

$ oneai login --scope classes:read
To sign in, open $ONEAI_ORIGIN/activate?user_code=XXXX-XXXX
and check that the page shows the code XXXX-XXXX. Waiting for confirmation...
Signed in to … as … (profile default)

不带 --scope 时，CLI 申请目前开放的 10 个 scope：profile:read、problems:read、classes:read、roster:read、students:pii、grades:read、grades:submit、files:write、ingestions:read 与 ingestions:write。学生实名仍要在激活页逐项确认。其他 scope 开放后可用 --scope 申请。改用 PAT 时从标准输入传入；CLI 先用 /me 校验再保存，不接受令牌参数：

$ oneai auth import-token --stdin < token.txt
Saved the token for … in … (profile default)
$ oneai auth status
Profile default: $ONEAI_ORIGIN, signed in (pat) as … in …

访问令牌快到期时，CLI 在 profile 锁内刷新。刷新没有得到应答时不重发，提示重新登录。

命令

命令	作用
oneai problems search [--query] [--scope public|owned]	检索题目
oneai files upload <path> --purpose grade-sheet|scheme-source|ingestion-source	上传不超过 8 MiB 的文件并输出 id
oneai grades submit <session> --manifest <file> --preview	预览清单里的答卷
oneai grades submit <session> --preview-id <id> --yes	按这份预览提交，输出任务 id
oneai classes members list <class> [--cursor <c>]	列出班级成员和成员 id；姓名、学号要有 students:pii
oneai classes accounts link <class> provision|reissue|reset-password <member>...	输出一条预选这些学生的班级页链接，由教师在网页里开号或重置密码。需要 students:manage，不输出任何密码
oneai ingestions create <path>... [--title <text>]	上传文件并开始解析：每个 PDF 或 Word 文件各是一份，所有照片合成一份试卷
oneai ingestions get|candidates <ingestion>	查看进度与候选计数，或列出解析出的候选及其 revision
oneai ingestions review|publish <ingestion> [--yes]	先展示，加 --yes 才提交候选修改或把已就绪的候选入库。需要 ingestions:review 或 ingestions:publish，默认登录不申请
oneai jobs get|wait|cancel <job>	查看或停止任务；wait 默认 300 秒超时
oneai mcp config|install|uninstall --client claude|codex	配置 Claude Code 或 Codex（见「MCP 接入」）
oneai skills install|uninstall --client claude|codex	安装或移除 oneai-grading（默认）或加 --skill ingest 的 oneai-ingest skill

加 --json 时 stdout 只有一个 JSON 对象，提示写到 stderr。退出码：0 成功，2 用法错误或其他请求错误（如对象不存在），3 授权，4 冲突，5 配额或限流，6 服务，7 超时。被拒时给出 reason 与请求 id：

$ oneai problems search --query triangle
oneai: OneAI refused the request: external.scope.denied (request a55655bf-61cb-4759-afb9-d7201456ec78)

CLI 把 profile、凭据和收卷预览存在配置目录（ONEAI_CONFIG_DIR；Linux 默认 ~/.config/oneai）。沙箱把这个目录设成只读时，命令会停在 config.unwritable，并给出目录。Codex 的 workspace-write 沙箱默认就是这样，需要放开这个目录，例如 codex -c 'sandbox_workspace_write.writable_roots=["/home/you/.config/oneai"]'。

退出登录

oneai logout 只删除本机凭据，不联系 OneAI；令牌或设备授权在过期或被撤销前仍然有效：

Removed the sign-in from this computer only. OneAI was not told; to stop it working now, revoke it under Outside access at https://<your-origin>/settings/security

需要立即失效时，到 设置 → 对外访问 撤销。