本文档是 ret2console 的唯一设计权威。任何实现偏差都以本文档为准;发现文档与事实冲突时,先改文档再改代码。
ret2console(简称 r2c)是 ret2shell(回归终端,github:ret2shell/ret2shell)比赛平台的终端用户接口(CLI 客户端)。类比:Codex CLI 之于 ChatGPT。ret2console 本身不实现权限管理、不保存业务数据,一切业务逻辑与权限均以 ret2shell 后端为准。
- 后端:https://github.com/ret2shell/ret2shell(Rust + Axum,Postgres + Valkey + NATS + K8s)
- API 文档:https://www.woooo.tech/zh-cn/ret2shell/references/
- 默认 API 地址:
https://ctf.xidian.edu.cn/api(西电 CTF 终端,可在 config 中修改) - 界面语言:全中文
- Python ≥ 3.11,单包
ret2console,uv + pyproject.toml,hatchling 构建 - 双入口:
ret2console与r2c(指向同一 main) - 依赖:prompt-toolkit(REPL/补全/高亮)、rich(表格/输出渲染)、httpx(异步 HTTP)
- 全部 async:REPL 用
PromptSession.prompt_async,API 用httpx.AsyncClient - 测试:pytest;API 层用 httpx MockTransport 离线打桩;REPL 逻辑抽成纯函数测试
无参数启动即进入常驻 shell,提示符见 §5。
一次性执行,支持分号分隔多条命令,执行后退出;失败退出码透传(非零);非 TTY 自动去色。
#!/usr/bin/env ret2console 或 ret2console <script>:逐行执行,# 开头为注释,空行跳过;失败即停(类似 bash -e),退出码透传;非 TTY 输出去色。
脚本模式认证策略:需要认证的命令若无已保存会话 → 报错退出(不交互);有则直接使用已保存的认证信息。交互式密码输入只属于 REPL。
r2c 后第一个参数按以下优先级解析:
- 现有文件路径 → 脚本模式(保持 shebang 语义);
- 已注册命令(如
r2c contest list、r2c auth show)→ 执行单条命令后退出,等价r2c -c "<命令>",但保留 shell 已解析的空格/引号边界; - 否则报「找不到脚本文件」,退出码 127。
mcp 为首命令时直接进入 MCP 子命令(见 §19),不构建 App。one-shot 复用与 REPL 相同的 App 生命周期(退出时依次关闭 wsrx 会话与 HTTP 客户端);exit 的 EXIT_CODE 映射为 0,ApiError 与其他异常打印 ✗ 后返回 1。
ret2shell 为 CLI 提供专用验证码通道,登录/注册一律走 PoW,不做终端内图形验证码显示:
GET /api/account/captcha/cli→ 永远返回ValidatorType::Pow(不依赖平台配置)- 响应:
{id, validator: "pow", challenge: "<difficulty>#<seed16位>"}(criteria 可能被脱敏,从 challenge 解析即可) - 求解:答案
ans必须ans.startswith(seed)且sha256(ans)的十六进制以difficulty个0开头;暴力递增后缀,难度 4 平均 65536 次,毫秒级 - 提交:
{account, password, captcha_id, captcha_answer} - 注意:同一账号连续失败 5 次冻结 30 分钟
- 登录成功响应体为空,token 通过响应头
Set-Token下发 - 之后所有请求带
Authorization: Bearer <jwt>;token 有效性依赖服务端缓存(非纯无状态 JWT) - token 临近过期时服务端会自动续期,新 token 同样通过任何响应的
Set-Token头返回——客户端必须监听每个响应头并更新本地 token - 登出使服务端 token 失效
| 端点 | 方法 | 说明 |
|---|---|---|
/api/account/captcha/cli |
GET | PoW 验证码 |
/api/account/login |
POST | {account, password, captcha_id, captcha_answer} |
/api/account/register |
POST | {account, nickname, email, password, captcha_id, captcha_answer} |
/api/account/logout |
POST | 登出 |
/api/account/profile |
GET | 当前用户信息 |
未登录 绿色 [guest@ret2console:/path]$
已登录 绿色 [user@ret2console:/path]$
管理员 红色 [admin@ret2console:/path]# (管理员以 # 结尾,类似 root)
/path 为虚拟文件系统当前路径(§7),完整显示;超过终端宽度截断左端保留尾部。登录后显示 nickname;管理员判定依据登录时返回的权限集。
- 合法命令(命令集内)→ 绿色 bold + 下划线(对齐 zsh-syntax-highlighting 的 suffix-alias/precommand 样式);未知命令 → 红色 bold
- 路径(以
/开头或命中 fs 节点)→ 蓝色下划线 - 普通参数 → 默认色;注释(
#开头)→ 亮灰(fg=black,bold);引号内容 → 黄色;glob(* ? [])→ 蓝色 - flag 整行匹配(§8)→ 整行金色,输入区下方实时提示「将以 flag 提交」
配色对齐 zsh-syntax-highlighting 默认主题(ANSI 8 色 + bold 亮化),不使用偏暗的 256 色。
- 输入提示:
? 标题:(青色问号 + 粗体标题);密码隐藏回显 - 确认:
? 标题 [y/N] - 选择器:↑↓ 高亮 + Enter + 数字快捷(autoplay 的 Agent 选择)
- 成功/失败/提示前缀:
✓绿 /✗红 /!黄
终端内模拟只读虚拟文件系统,cd 即 use 语义:
/
├── notice # 全局公告(bulletin)
├── contests/ # ls = 比赛列表(动态,来自 API)
│ └── <game_id>/
│ ├── info # cat = 比赛详情
│ ├── notice # cat = 比赛通知
│ ├── scoreboard# cat = 排行榜(GET /api/game/{id}/team?min_state=passed&order=score&asc=false)
│ ├── docs/ # readme / training / rules(GET /api/game/{id}/doc/{doc})
│ ├── team # cat = 当前队伍(GET /api/game/{id}/team/self)
│ └── challenges/ # ls = 题目列表(动态)
│ └── <challenge_id>/
│ ├── README # cat = 题面(markdown 渲染)
│ ├── hint # cat = 提示
│ ├── files/ # ls = 附件列表;zip 附件 cat 给出提示信息(不直接输出)
│ ├── instance # cat = 靶机实例状态
│ └── flag # 提交入口(见 §8)
- 节点用 id(game_id / challenge_id)命名,
ls显示 id → 标题映射 - 进入比赛目录 = 设定当前比赛上下文;进入题目目录 = 设定当前题目上下文
- 命令与 fs 共享同一套上下文:
cd /contests/3/challenges/5后submit、hint、instance默认作用于题目 5;命令式contest use 3/challenge show 5等价于 cd,互为镜像 - 附件下载:
download <题目> <文件>下载到真实 cwd(像 wget),文件名冲突自动加(1)后缀 - 公告:根
/notice= 全局公告;比赛下notice= 比赛通知
- 显式:
submit <flag>;submit无参进入安全粘贴模式 - 粘贴即提交:整行匹配
^[A-Za-z0-9_]+\{[^{}\n]+\}$(先 trim 首尾空白/换行)自动走提交流程,无确认弹窗 - 命中 flag 的行不进命令历史(防泄露)
- 无登录/无当前题目上下文时给出明确提示,不静默失败
- 提交结果即时反馈(正确/错误/其他后端语义)
- 限流:后端 10 次/窗口
- 提交 API:
POST /api/game/{gid}/challenge/{cid}/submission,body{"content": "<flag>"}
| 分组 | 命令 |
|---|---|
| 认证 | auth login auth logout auth register auth status auth endpoint [URL] [--insecure](切换 API 地址,清除旧登录态;reset 恢复默认) `auth profile <list |
| 比赛 | contest list [--page N] [--page-size N] [--type training|game] contest show [比赛] [--intro|--rules|--cover] contest use <比赛>(= cd) contest doc <比赛> [readme|training|rules] contest notice [比赛] scoreboard [比赛] [--page N] [--page-size N] |
| 队伍 | team create <name> [tag] [--yes] team join <token> [--yes] team modify <name> [tag] team info team rank [队伍id] team member [队伍id] team solve [队伍id] team leave |
| 题目 | challenge list challenge show <id>(cat) challenge hint <id> challenge unlock <id> <hint_id> challenge files [题目] challenge solve [题目] challenge start <id> challenge instance <id> challenge renew <id> |
| 附件 | download [--dir PATH] [题目id] [文件名](无文件名 = 全部附件) |
| 提交 | submit [flag] submissions [比赛] |
| 管理 | `admin bulletin <list |
| MCP | mcp serve(stdio,需在 shell 运行)mcp tools mcp setup [--agent claude|codex|opencode|omp] [--profile NAME] mcp status |
| 系统 | help exit clear version echo pwd ls cd status completion <bash|zsh|fish> [--output PATH] [--force] |
比赛/题目参数一律支持名称解析:缺省取当前上下文,纯数字按 id,名称先大小写不敏感精确匹配、再唯一前缀匹配;无匹配 ✗ 找不到…,多匹配 ✗ …名称不唯一 并附候选表。
team create / team join 在发请求前展示 doc/rules(后端不可用或为空则跳过)并确认;--yes 跳过确认,非 TTY 且未传 --yes 直接报错。
shell 彩蛋别名:ls = challenge list、cat = challenge show(仅限题目上下文内)、wget = download。公告/通知:notice。
[green]✓[/green]— 操作成功(确定态)[yellow]➜[/yellow]— 已提交/完成态但不一定成功(如已进入评测队列、实例启动请求已提交)[red]✗[/red]— 操作失败(API 错误、无效参数、未知子命令)[yellow]![/yellow]— 提示/拒绝(未登录、缺少上下文、需要确认的警告)- 用法引导
用法: ...与 bash 语义的command not found不带符号
- 静态命令/子命令补全(离线)
- fs 路径补全(
cd/ls/cat/download输入时 Tab 补目录与文件;同步遍历已加载节点,未加载目录自动异步加载(限时 3s);相对路径保留相对形式) - 动态数据补全:比赛/题目列表首次拉取后缓存进会话,
challenge show <Tab>补题目 id;ls时刷新缓存
补全菜单 zsh 风格:比赛/题目目录与动态 id 右侧同时显示描述(比赛标题/题目标题,来自 API 缓存)。末尾空白后 Tab 视为开始新词(auth<空格> 直接补子命令,不替换已输入内容)。
外部 shell 补全:r2c completion bash|zsh|fish 生成脚本。命令列表来自注册表(含别名),第二级来自 _SUBCOMMANDS;脚本直接写 stdout(不经 Rich,避免 [ 被解析),--output PATH 落盘且默认拒绝覆盖(--force 覆盖)。bash 用 _r2c_completions + compgen -W,zsh 用 #compdef + _describe/_values,fish 用 complete -c ... -n '__fish_use_subcommand'。
REPL 内输入 zsh / bash / fish(检测本机已安装)交互式启动该 shell,注入 handler 提取 flag:
- bash:临时 rc 文件 +
bash --rcfile ...;rc 内定义submit()函数 +DEBUG trap,每条命令执行前检查整行是否匹配 flag 格式,命中自动提交 - zsh:
ZDOTDIR指向临时目录,注册preexec钩子 - fish:
fish_preexec事件监听 - 提交通道:
ret2console -c "submit -",flag 从 stdin 喂入(零注入风险,flag 内含引号/分号/反引号均安全) - 只对交互式启动注入;
-c "bash script.sh"非交互场景直接透传 - 不注册
r2c函数——r2c是可执行文件,天然在 PATH 中可用 - 未登录时子 shell 内提交按 §3.3 策略报错提示
- 检测到 flag 自动提交 + 打印结果(静默,无确认)
autoplay 命令流程:
- 检测可用 Agent(
shutil.which):codex/claude/opencode/omp/reasonix/kimi,多个时弹出 gh 风格交互式选择器(↑↓ 高亮 + Enter,prompt_toolkit 实现,支持数字快捷) - 确认提示:「警告:使用一把梭功能可能导致您的亲人遭受损失(物理),是否仍要继续?[y/N]」(文案原样保留)
- 自动下载当前题目附件到
~/.ret2console/autoplay/<题目id>/,生成「任务书」markdown(题面全文 + 附件绝对路径 + 目标说明) - 用参数把提示词传进去直接启动 Agent 的标准 TUI(继承终端),选手继续操作;不回收 flag,选手退出后自行粘贴提交。 不支持 TUI 初始消息的 Agent(kimi / reasonix):先打印提示词,选手自行复制、启动后粘贴到首条消息,确认后启动
Agent 启动方式(实测/待实测):
codex→codex "<prompt>"(无子命令 + PROMPT 参数直接进交互式 TUI 并带初始消息 ✓ 已实测)claude→claude "<prompt>"(交互式,首条消息)opencode→opencode --prompt "<prompt>"(交互式 TUI 带初始消息)omp→omp "<prompt>"(直接进交互式 TUI 并带初始消息,omp 文档确认)kimi→ Kimi Code CLI:kimi进交互式 TUI(-p为单次非交互);不支持 TUI 初始消息 → 打印提示词供复制,确认后启动reasonix→reasonix code进 code 模式 TUI;不支持 TUI 初始消息 → 打印提示词供复制,确认后启动- 执行方式以各家
--help实测为准,任务书兜底永远在
ret2console 直接依赖 Python 包 libwsrx,不检测或下载 wsrx CLI,不启动 daemon,
也不注册或调用 wsrx-desktop。App.wsrx 是当前应用进程内唯一的隧道所有者。
- 每条新隧道调用
await libwsrx.ClientEndpoint.bind("127.0.0.1:0", remote);端口由 操作系统在 bind 时原子分配,命令使用endpoint.local_addr返回的实际地址。 - 管理器保留
ClientEndpoint,并记录 remote、local、game_id、challenge_id。remote URL 是唯一键;同一进程内重复连接完全相同的 remote 时复用现有端点。 pool_instances()仅展示当前管理器实际保留的 live 端点;challenge instance和 VFS 状态都从该列表读取,不使用第二份注册表或磁盘状态。remove、remove_for和close先从内存移除记录,再等待endpoint.shutdown()。 批量清理会尝试关闭所有选中端点;重复close()是安全的。
- 端点只在创建它的 ret2console 进程存活期间可用。交互式 REPL 和 autoplay 运行期间, 管理器持续持有端点。
- REPL、
-c和脚本模式退出时都先await app.wsrx.close(),再关闭 API 客户端。 因此通过-c或脚本执行challenge connect后,隧道会随该一次性进程退出而关闭。 challenge disconnect、challenge stop和进程退出均确定性关闭相应 listener 与活跃连接; 不存在 daemon pid、secret、HTTP/pool、desktop lock/control 或tunnel.json状态文件。
- 选手实例查询走
GET /api/game/{gid}/instance(challenge 级 GET 是管理员接口),再按challenge_id过滤。 instance.traffic是平台 nanoid;每个暴露端口的 remote 为wss|ws://{平台域名}/api/traffic/{nanoid}?port={端口},与前端getWsrxLink一致。- 每个端口建立独立
ClientEndpoint,输出其实际127.0.0.1:PORT。若多端口连接中 后续 bind 失败,本次命令新建的端点全部回滚;此前已存在的端点不受影响。 challenge disconnect [id]按 game_id/challenge_id 关闭当前进程持有的端点,不停止实例。challenge stop [id]先关闭对应端点,再 DELETE/api/game/{gid}/challenge/{cid}/instance;端点关闭错误不阻止远端实例删除。challenge start冲突时提示challenge instance/challenge stop <题目id>。challenge start的 POST 成功后,最多等待 30 秒,直到实例同时满足running且traffic可用;该就绪期限包含状态查询耗时,并独立于每次 HTTP 请求的传输超时。 到期时命令返回状态0,提示远端启动仍可能继续,并引导稍后查询状态和连接。- 在上述提交后等待期间按 Ctrl-C 只停止本地轮询,返回状态
130,不撤销服务器端启动, 交互式客户端随后返回提示符。challenge connect仍是绑定本地隧道的独立命令。
- 所有路径前缀
${API_BASE}(默认/api),无/v1 - 认证中间件:Public / Guest-aware / Basic(登录)/ Verified(登录+邮箱验证)/ 权限分级(Permission::User 等)
- 比赛:
GET /api/game(列表,分页)、GET /api/game/{id}、GET /api/game/{id}/doc/{doc}(readme|training|rules)、GET /api/game/{id}/notification(比赛通知) - 排行榜:
GET /api/game/{id}/team?min_state=passed&order=score&asc=false(分页,返回[Team[], count]) - 队伍:
GET /api/game/{id}/team/(列表)、POST /api/game/{id}/team/(创建)、PATCH /api/game/{id}/team/(加入,带 token)、PATCH /api/game/{id}/team/self(修改本队:name 必填,tag 传 null 清空)、GET /api/game/{id}/team/query?token=、GET /api/game/{id}/team/self、GET /api/game/{id}/team/{tid}、.../rank、.../member、.../solve、.../extra - 题目:
GET /api/game/{gid}/challenge(列表)、GET /api/game/{gid}/challenge/{cid}(详情,题面为 markdown 文本)、GET /api/game/{gid}/challenge/{cid}/hint、POST /api/game/{gid}/challenge/{cid}/hint/unlock、GET /api/game/{gid}/challenge/{cid}/file(附件列表/下载,query: folder/file)、GET /api/game/{gid}/challenge/{cid}/submit(解题状态{solved, solves};带?id=<提交id>返回该次提交详情) - 提交(评测队列,不是
/submission,那是管理员接口):POST /api/game/{gid}/challenge/{cid}/submit(body{"content": ...})→ 返回 submission{id, solved: null, result: null}入队;随后GET /api/game/{gid}/challenge/{cid}/submit?id=<id>轮询,checker 完成后solved: bool+result: 文本(失败样例为 "checker fails on your input, incorrect.");submit命令 POST 后轮询(最多 10 次 × 0.8s),超时提示稍后重查 - 实例(选手):
GET /api/game/{gid}/instance(本人实例列表)、POST/PATCH/DELETE /api/game/{gid}/challenge/{cid}/instance(启动/续期/关闭);返回简化 Pod:state/name/traffic/ports/renew_count/created_at/user_id/user_name/team_id/team_name/challenge_id/challenge_name - 公告:
GET /api/bulletin(分页) - 事件 WS:
WS /api/game/{id}/event/connect?game_id=&token=—— 需要 game token(主办方大屏专用),普通用户不可用,通知一律轮询
- 权限门禁:r2s 服务端校验(Bulletin/User/Game/Host/DevOps/Calendar/Wiki/Statistics);本地仅要求已登录且权限集非空
- 公告:
POST /api/bulletin、PATCH/DELETE /api/bulletin/{id}(article model:title 必填,path/publisher_id/created_at 等由命令补齐默认值) - 用户:
GET /api/user(filter/page)、GET/PATCH/DELETE /api/user/{id}(email 必填,命令先 GET 现状再合并)、GET /api/user/{id}/ip;permissions传game,host或 JSON 数组 - 比赛:
POST /api/game(model 全字段,命令填默认值:host_type=Game、hidden=true、sync=2、时间=now,k=v 覆盖)、PATCH/DELETE /api/game/{id}(--force删已建题的比赛)、POST /api/game/{id}/token、GET/PATCH /api/game/{id}/administrator、GET /api/game/{id}/submission、GET /api/game/{id}/audit+PATCH /api/game/{id}/audit/{aid}(state:1 驳回 / 2 确认,reason 必填)、GET /api/game/{id}/statistics - 题目:
POST /api/game/{gid}/challenge(创建即 hidden,发布用 publish)、PATCH/DELETE /api/game/{gid}/challenge/{cid}、POST/DELETE .../publish(上/下架)、GET/PATCH .../answer(body 为裸 JSON 字符串,如"flag{xxx}")、GET .../history|submission|instance、POST .../file?folder=static|mapped|checker(multipart 上传) - 平台:
GET /api/platform/statistics、GET /api/platform/logs(query/level/limit/from/account/trace)、GET /api/platform/config - 集群:
GET /api/cluster/node、GET /api/cluster/config、GET /api/cluster/calmdown - 时间参数:unix 秒 / ISO8601 /
YYYY-MM-DD HH:MM(本地时区),自动转 ts_seconds
- 目录:
~/.ret2console/ nix run .直接运行(flake 定义packages.default/ret2console与apps.r2c;仓库文件需 git tracked)config.json:API 地址、下载目录等(权限 644)session.json:JWT、账号、昵称、权限集(权限 600)history:REPL 历史(flag 行过滤后写入)- JWT 过期自动回到 guest 态,不崩溃;监听
Set-Token头实时更新(§4.2)
/home/deepslate/dev_ret2shell/:docker-compose.yml一键起全套(postgres/valkey/nats/vlogs/registry:2 + platform 镜像构建自 ret2shell Containerfile)+ .env + config/config.toml(已按 compose 服务名配置)+ README- 启动:
docker compose up -d --build(首次构建 Rust release 约 10-20 分钟;R2S_SRC可覆盖源码路径) - 访问:http://localhost:8080(Web +
/api);调试 ret2console 时把 config.json 的api_base指向http://localhost:8080/api - 平台数据持久化于
platformvolume;config 挂载到容器/etc/ret2shell/ - 本机现状:codex ✓、opencode ✓、claude/omp/reasonix/kimi/wsrx 未安装
- ✅ 设计定案(本文档)
- ✅ 骨架:pyproject + 双入口 + REPL + 三态提示符 + 分词高亮 + 静态补全 + config/session 存储
- ✅ API 客户端 +
auth(PoW 登录/登出/status;register 参数式 + 交互式) - ✅ VFS +
contest/challenge命令(列表/详情/use/doc/notice;team全套;docs/files/instance 节点已挂接) - ✅ 提交:
submit+ flag 粘贴识别 + 历史过滤(含分号内 flag 识别) - ✅ 附件下载 + 实例
connect+ 进程内 libwsrx 端点(start/instance/renew/connect可用) - ✅
bulletin(根/notice)+ 动态补全缓存(比赛/题目 id + 描述列) - ✅ 子 shell 注入(bash/zsh/fish)
- ✅
autoplay - 🚧 打磨:README 已补全;
help <命令>可用;交互式 register 完成 - ✅
admin命令集(bulletin/user/game/challenge/platform/cluster)+ 输出符号约定(✓/➜/✗/!)全量统一 - ✅ 功能补齐:
auth show/edit/code/ping、submissions、challenge files/solve、附件批量下载、比赛筛选与名称解析、队伍规则确认、shell 补全脚本 - ✅ MCP stdio 服务:dual-era 协议(2025-11-25
initialize+ 2026-07-28_meta)、33 个选手侧工具、r2c mcp setup配置片段(§19)
- 子 shell 三种 shell 的真实环境冒烟(本机仅 zsh 可用)
- MCP 现代协议(2026-07-28
server/discover)尚无真实客户端实测,当前以单元测试 + stdio 烟测覆盖
新增 ret2console/service.py:所有函数只返回 JSON 可序列化数据或抛 ServiceError(code/message/status/data),不打印任何内容。CLI 命令与 MCP 工具共用该层,保证两条入口的数据形状与错误语义一致:
- 名称解析:
resolve_game/resolve_challenge/resolve_team(上下文默认 → 数字 id → 精确匹配 → 唯一前缀;多匹配ambiguous附candidates)。 - 账号:
get_status/get_account/ping/update_account/make_code。 - 比赛:
list_contests/get_contest/get_contest_doc/get_contest_notices/get_scoreboard。 - 题目:
list_challenges/get_challenge/list_hints/unlock_hint/list_files/download_files/submit_flag。 - 实例:
list_instances(附expires_at/remaining_seconds)/start_instance(先查后建)/stop_instance/renew_instance。 - 队伍:
team_info/team_rank/team_members/team_solves/team_create/team_join/team_update(_KEEP哨兵保留 tag)/team_leave。 - 其他:
list_submissions/ls/read。
附件下载规则:单文件目标 Path(output_dir or ".")/safe(file);批量目标 <output_dir 或配置 download_dir>/<题目id>-<题目名>/<folder>/<file>(空 folder 不产生层级);safe(p) 只取末段且 ""/./.. 视为 _;同名目标追加 (1)、 (2)…;题目名 slug 保留 [A-Za-z0-9._-]、其余替换并折叠 -、截断 40。
r2c mcp serve:stdio JSON-RPC 服务(stdout 只允许 MCP 报文,verbose日志写 stderr,且只记录方法名/工具名,不记录 arguments)。协议期进程内其他 stdout 写入(Rich console、终端图片转义、意外 print)统一重定向到 stderr,保证协议流纯净。r2c mcp tools:列出工具(不加载凭据)。r2c mcp setup [--agent claude|codex|opencode|omp] [--profile NAME]:打印接入配置片段,不写任何文件;无--agent时 TTY 走 gh 风格选择器,非 TTY 报错。r2c mcp status:显示版本、profile、endpoint、登录态、协议版本与工具数。- REPL 内
mcp serve只提示需在 shell 中运行(不阻塞当前会话)。
全局选项(r2c mcp 任意位置均可):--profile NAME、--url URL、--token TOKEN、--insecure、--verbose;环境变量默认 R2C_PROFILE / R2C_API_BASE / R2C_TOKEN,命令行优先,空字符串视为未设置。
凭据规则:--url 覆盖时不带 profile token;仅 --token 时沿用 profile endpoint;两种覆盖都不把 token 写回会话文件(Set-Token 续期同样不落盘)。
纯标准库 dual-era 实现,不新增依赖:
- 传统:
initialize握手,支持2024-11-05/2025-03-26/2025-06-18/2025-11-25(未知版本回落2025-11-25);tools/list返回{tools};ping返回{}。 - 现代:请求
params._meta["io.modelcontextprotocol/protocolVersion"] == "2026-07-28"时走无状态分支;server/discover返回supportedVersions/capabilities/instructions/ttlMs=60000/cacheScope="private";所有结果附resultType="complete"与_meta["io.modelcontextprotocol/serverInfo"]。 - 不支持的现代版本 → 错误
-32022,data.supported列出全部支持版本。 - 错误码:
-32700解析失败、-32600非法请求(含 batch,MCP 不支持 batch)、-32601未知方法、-32602未知工具/参数非法/缺少必填参数。 - 工具执行失败不升级为 JSON-RPC 错误:返回
isError: true,文本为{"error": {"code","message","status","data"}},不向 stdout 写堆栈。 - 无
id的通知(notifications/initialized/notifications/cancelled等)一律静默。
| 工具 | 参数 | 行为 |
|---|---|---|
r2c_context |
— | 当前 profile/endpoint/登录/权限/比赛/题目/VFS 路径(只读) |
r2c_use_contest |
game |
解析并切换比赛上下文 |
r2c_use_challenge |
challenge, game? |
解析并切换题目上下文 |
r2c_ls |
path? |
列虚拟目录 |
r2c_read |
path |
读虚拟文件 |
r2c_auth_status |
— | 登录状态(只读) |
r2c_account_show |
— | 账号资料(不含 token) |
r2c_ping |
— | 会话检测 + 延迟 |
r2c_contest_list |
page?, page_size?, host_type? |
分页比赛列表 |
r2c_contest_show |
game? |
比赛详情 |
r2c_contest_doc |
doc, game? |
readme/training/rules |
r2c_contest_notice |
game? |
比赛通知 |
r2c_scoreboard |
game?, page?, page_size? |
排行榜 |
r2c_challenge_list |
game? |
题目列表 |
r2c_challenge_show |
challenge?, game? |
题面 |
r2c_challenge_hints |
challenge?, game? |
提示列表 |
r2c_challenge_unlock_hint |
hint_id, challenge?, game? |
解锁提示(写) |
r2c_challenge_files |
challenge?, game? |
附件列表 |
r2c_challenge_download |
file?, output_dir?, challenge?, game? |
单文件/批量下载 |
r2c_challenge_submit |
flag, challenge?, game? |
提交并轮询评测 |
r2c_instance_status |
challenge?, game? |
实例列表与剩余时间 |
r2c_instance_start |
challenge?, game? |
启动(已有实例不重复创建) |
r2c_instance_stop |
challenge?, game? |
停止(destructive) |
r2c_instance_renew |
challenge?, game? |
续期 |
r2c_team_info |
game? |
我的队伍 |
r2c_team_rank |
team_id?, game? |
队伍排名 |
r2c_team_members |
team_id?, game? |
成员列表 |
r2c_team_solves |
team_id?, game? |
队伍解题 |
r2c_team_create |
name, tag?, game? |
创建队伍(返回邀请 token) |
r2c_team_join |
token, game? |
加入队伍 |
r2c_team_update |
name, tag?(null 清空), game? |
修改队伍 |
r2c_team_leave |
game? |
退出队伍(destructive) |
r2c_submission_list |
game? |
提交记录 |
上下文语义:game / challenge 缺省取当前上下文;显式 game 与当前上下文不同时必须同时给 challenge(否则 invalid_context),避免「比赛 A + 题目 B」的错配。
输出约定:列表类工具返回 {items, total?}(r2c_ls 返回 {path, entries});r2c_team_info 返回 {team: dict|null};r2c_team_rank 返回 {rank};写工具返回对应状态布尔(started / already_started / stopped / renewed / left 等)。
注解:只读工具 readOnlyHint=true, openWorldHint=true;上下文切换 idempotentHint=true;写工具 readOnlyHint=false, destructiveHint=false;r2c_instance_stop / r2c_team_leave 标 destructiveHint=true。
MCP 仅暴露选手侧能力:不含 admin 命令、autoplay、子 shell、账号资料修改/临时身份码/密码操作。工具结果不包含登录 token。r2c_team_create / r2c_team_join 在 MCP 中不弹确认,描述里要求调用前先用 r2c_contest_doc 读取 rules。