# agent_interface **Repository Path**: taosong1999/agent_interface ## Basic Information - **Project Name**: agent_interface - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2026-11-11 - **Last Updated**: 2026-11-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 决胜千里 —— 赛事编排与对局驱动 服务于职工技能大赛等场景:把棋盘/战场态势通过 HTTP 发给**远端低代码平台上预构建的智能体**, 或把选手仓库拉起为独立进程接入本地推演引擎,统一完成赛程编排、对局执行、台账与积分报告。 支持两类比赛,共用同一套编排核心: | 类型 | 单场形态 | 说明 | |---|---|---| | `warchess` | 远端智能体 HTTP + 本地 Env(战棋仿真平台) | 单局由 `craft_manager.match_main` 子进程执行 | | `jsql` | 选手仓库双进程 + 决胜千里推演引擎 | 单场由 `env_communication/jsql_match` 子进程执行 | ## 架构 ``` gui/ (pywebview) CLI: python -m tournament.main │ │ └──────────────► tournament/ 编排核心 ◄───────┘ ├─ schedule.py 多阶段赛程(循环/小组/瑞士轮/手动) ├─ standings.py 积分/净胜分/小分/ELO ├─ orchestrator.py 主循环 + attempt 重试 + 判责 ├─ ledger.py / recovery.py 台账 + 断点续测 └─ executors/ ├─ warchess.py ──► craft_manager/match_main.py │ ├─ runner + player(远端智能体 HTTP) │ └─ Env(战棋仿真平台) └─ jsql.py ─────► env_communication/jsql_match └─ launcher + match_core + shim Env ``` ## 目录结构 ``` agent_interface/ ├── main.py # 单局对弈 CLI(--model 决胜千里战棋) ├── tournament/ # 统一赛事编排层 │ ├── main.py # 赛事 CLI(--dry-run/--resume/--only/--workers) │ ├── orchestrator.py # 多阶段主循环 + 瑞士轮逐轮生成 + 台账 + 报告 │ ├── schedule.py # 队伍表/赛程加载校验与赛程生成 │ ├── project.py # 项目(一套配置 + 全部运行历史) │ ├── standings.py # 积分/净胜分/小分/ELO │ ├── ledger.py / recovery.py # 事件流台账 / 崩溃续跑 │ ├── runcheck.py # 运行目录只读体检(逐文件哈希/结构化差异/续跑结论) │ ├── manifest.py # 运行清单 manifest.json(输入指纹 + 结果统计) │ ├── distribute.py # 子任务生成(含任务契约指纹) / 推送发现 / 汇总(merge) │ ├── node.py # 子节点:远端读取 → 契约校验 → 本地镜像 → 严格本机覆盖 → 运行 → 逐把推送 │ ├── machine_cfg.py # 机器相关键清单与归一化哈希 │ ├── executors/ # 比赛执行器(jsql / warchess) │ ├── engine_ctl.py # 推演平台前后端控制(Windows) │ ├── scenario_deploy.py # 想定部署(引擎 Scene + 选手侧) │ ├── repo_mgr.py # 选手仓库 clone/fetch/checkout │ ├── watchdog.py # 引擎健康监控 │ ├── TOURNAMENT.md ├── gui/ # pywebview 配置与运行前端 │ ├── main.py / api.py # 桌面入口 / js_api │ ├── schema.py # 表单字段元数据(标签·说明·控件·枚举来源) │ └── static/ # 纯静态,无构建链 │ ├── index.html / style.css │ └── js/ # core / schema-form / teams / schedule / report / distribute / app ├── craft_manager/ # 战棋单局 │ ├── match_main.py # 单局子进程入口(赛事执行器调用) │ ├── runner.py # 单局运行器(红黑交替、合法性校验、回放/SVG) │ └── player.py # 远端智能体 HTTP 客户端 ├── env_communication/ │ ├── warchess_wrap/env.py # 战棋仿真平台环境封装 │ └── jsql_match/ # 红蓝双进程推演对战(shim Env 帧屏障) ├── debug/ # 一次性调试脚本与远端智能体示例 ├── model_communication/ # 大模型直连调用(与对战链路无关) ├── mqtt_communication/ # MQTT 收发 ├── support/ # text_loader / 日志 / IP 改写等工具 ├── auto_test/ # 评测产物(整体 gitignore) │ └── projects/<项目名>/ # 项目:一套配置 + 该项目全部运行历史 │ ├── base.json / teams.json / schedule.json │ ├── jsql_engine.json / jsql_match.json / warchess.json / warchess_env.json │ ├── competition/ # 主节点赛事状态:plan.json(已物化轮次)+ events.jsonl(人工裁决/撤销) │ ├── exports/ # 有效赛果 CSV 导出 │ ├── scenarios/ # 想定库(默认从 config/scenarios 复制) │ └── runs/_<赛事名>/ # 台账 / 报告 / 本次生效配置快照 config/ └── config/ # 模板库(新建项目的初始化来源) ├── teams.json(.example) # 统一队伍表模板(含密钥的真实表不入库) ├── scenarios/ # 想定库(.SCN + 装备目录 + Translation.ini) └── tournament/ ├── base.json # 编排通用配置模板(路径/重试/并发) ├── schedule.json(.example) # 赛程模板(多阶段) ├── jsql_engine.json # 推演平台进程控制 ├── jsql_match.json # 单场推演基础配置 ├── warchess.json # 战棋:环境文件、棋种 └── warchess_env.json(.example) # 仿真平台本机路径/端口(不入库) ``` ## 图形界面(推荐) ```bash uv sync # 首次安装依赖(含 pywebview) uv run python -m gui.main ``` 主节点第一页是**任务页**(顶栏不再放任务下拉框):在这里新建或打开任务目录,查看任务问题与开工前检查。 每个任务 = 一套配置 + 全部运行历史,可放在任意本地/共享目录(`auto_test/projects/<项目名>/` 或外部目录)。 外部任务登记在本机 `auto_test/projects.json`(只存路径指针);发布/汇总/导出统一按**任务目录**定位, CLI 只给显示名时也会在登记表里找同名外部任务,找不到才报错。 新建任务使用**空白模板**:不预置 Demo 队伍、不预置赛程阶段、`defaults.duration=2000`,阶段由用户在「赛程」页手动添加。 切换/新建任务前会提示保存或丢弃未保存的修改。 启动后在顶栏左侧选择**运行角色**(本机工作模式,切换需要确认,运行中禁止切换): - **主节点(编排与判读)**:只做四件事——填选手 → 编赛程 → 生成任务 → 读结果。 主节点不运行任何对局,不提供整场运行/本机子任务/执行资源配置入口;后端也逐接口拒绝。 - **子节点(执行)**:只做两件事——填本机环境(引擎/解释器/录像)→ 选任务并运行。 子节点不能修改选手、赛程或任务划分;尝试修改会被后端拒绝。 所有字段仍按元数据渲染,字段定义在 `gui/schema.py`,不含任何本机 IP、端口、路径。 主节点顶栏顺序:**任务 → 队伍 → 赛程 → 设置 → 发布 → 结果**(设置是发布时冻结的共享规则,因此放在发布之前)。 | 页 | 能力 | |---|---| | 任务(主) | 第一页:新建任务 / 打开本地或共享任务目录 / 当前任务摘要与问题 / 可用任务列表 / 开工前检查(`master_checks`) | | 队伍(主) | 左侧列表 + 右侧表单:队伍身份、选手仓库、决策模式、百炼凭据;ID 重命名自动更新引用;密钥掩码;CSV 批量导入 | | 赛程(主) | 赛事信息(名称/想定/帧数)+ **想定库**(单个组件:逐项勾选 + 导入 `.SCN`,默认 `Scenario_LDJS2026`)+ 阶段卡片(按赛制切换字段、手动对局表格)+ **单场覆盖**(想定/红蓝/帧数);**每个配对在全部已选想定上各赛一场**(单想定保持旧场次 ID);校验并预览展开后的对局 | | 发布(主) | **只负责发布**:按子任务划分 `dist.json`(小组/阶段/场次取并集,保存即校验)、**按子节点数一键自动分配**(可选红蓝互换对手整对同节点,生成草稿后仍可手动调整)、按轮生成/发布、**生成并发布任务**(冻结场次/规则/想定/划分);页签与卡片显示「已发布 / 需重新发布」真实状态;无动态阶段时轮次区块整块隐藏;进度、占用与汇总在「结果」页 | | 结果(主) | 只读判读与汇总:**进入即自动刷新**(接口一次读齐运行历史、子任务接收进度、占用、有效赛果),只有一个「刷新最新结果」入口;有效赛果直接来自子节点推送,**不需要先汇总**;「生成汇总报告」另存独立 merged 报告,仅用于归档/导出。可裁决/撤销/补赛;报告与审计导出(全状态明细、来源节点、attempt、可选 ZIP);积分榜含得分/失分/净胜分;无任何启动对局入口 | | 设置(主) | 表单化配置**共享规则**:运行/重试、单场帧数/帧超时/**任务生成超时**、 **选手依赖同步**(uv sync)、**审计产物**(规划 JSON 匹配、关键帧态势间隔)、录像策略(是否必需、是否随结果推送、画质等); 推演平台安装位置、OBS 程序/暂存目录、解释器与端口属于各机环境,在子节点配置 | | 子节点 | 五步配置(连接主节点 / 本机程序 / 端口与网络 / 录像 / 检查与运行):**选完共享目录自动读取任务**(手输路径 800ms 防抖,失败内联提示可重试);本机程序步检测 `git`(缺失阻断)与 `uv`(启用 `dependencies.uv_sync` 时缺失阻断,否则仅警告);表单化机器覆盖 + OBS 下载(带进度/取消)/选择/自检;**选中子任务即显示本次对阵(场次/阶段轮次小组/红 vs 蓝/想定/帧数/是否执行)以及本机进度(完成/无效/准备失败/未跑、attempt、比分、是否已推送),运行中按进度增量刷新(不重建表格、不弹窗)**;一个执行入口 **「继续 / 重试待跑 N 场」**(只跑待跑场次,成功且未撤销的场次永不重跑;确认框按原因列出场次)+ 停止 + **「只推送 M 场」**(本地已成功、共享未收到的才补推,不重跑);不提供“强制新建/指定运行”;备仓在后台执行并**实时显示阶段日志**(clone/fetch/检出/uv sync,本机 `prepare.log`,不写共享);统一执行台显示「备仓 → 自检 → 运行 → 推送 → 录像」与唯一「下一步」,并保留**内部批次(审计)**列表(逐场 attempt、日志尾部);对阵表每行提供**人工判决**入口(只对本机已失败/无效的场次可用,需二次确认,可填可选比分与必填原因) | > pywebview 使用系统 WebView2(Windows 10/11 自带)。GUI 与 CLI 共用同一套项目目录与运行历史。 > 主节点 GUI 没有启动/续跑入口;续跑只在子节点(`node_start(resume=True)` / `--resume`)。 > 子任务生成后内容冻结;子节点发现赛程/规则/想定/划分变化会拒绝执行并要求重新生成。 ## 赛事编排(CLI) ```bash # 项目管理(一套配置 + 全部运行历史,落在 auto_test/projects/<名称>/) uv run python -m tournament.main --list-projects # 新建项目:空白模板(无 Demo 队伍、无预置阶段、jsql / 2000 帧) uv run python -m tournament.main --init-project LDJS2026 uv run python -m tournament.main --init-project LDJS2026 --no-copy-scenarios # 校验赛程,不跑(不创建运行目录);--json 输出机器可读结果(CI 友好) uv run python -m tournament.main --project LDJS2026 --dry-run uv run python -m tournament.main --project LDJS2026 --dry-run --json # 续跑预检:只读报告差异与结论,不启动引擎、不建目录、不写快照 uv run python -m tournament.main --project LDJS2026 --check-resume uv run python -m tournament.main --check-resume --json # 自动取最近一次运行 uv run python -m tournament.main --run-dir <运行目录> --check-resume # 主节点不再提供整场运行/本机子任务入口:生成任务后由子节点 --remote 领取 # 复制现有配置:把 config/ 下当前真实配置复制进新项目(不删除原文件) uv run python -m tournament.project --init LDJS2026 --from-config # 动态赛程:逐轮生成 → 按轮发布(本轮有效赛果齐全后才能生成下一轮) uv run python -m tournament.main --project LDJS2026 --materialize --stage 瑞士轮 --round 1 uv run python -m tournament.main --project LDJS2026 --publish-round --stage 瑞士轮 --round 1 # 主节点人工裁决 / 作废 / 重跑(不启动引擎) # 原因必填;覆盖已有赛果需要 --yes(先打印旧 winner/比分/来源) uv run python -m tournament.main --project LDJS2026 --set-result S4-R1-01 red \ --reason "现场判罚" --score 3:1 uv run python -m tournament.main --project LDJS2026 --set-result S4-R1-01 blue \ --reason "复核改判" --yes # 高级动作「作废」:只作废不重跑(幂等;已作废的场次不会追加事件) uv run python -m tournament.main --project LDJS2026 --revoke-result S4-R1-01 # 统一「重跑」:默认只预览(列出五类分派与旧结果),--yes 才执行 uv run python -m tournament.main --project LDJS2026 --rerun uv run python -m tournament.main --project LDJS2026 --rerun --yes # 一键重跑未有效完成 uv run python -m tournament.main --project LDJS2026 --rerun --scope stage \ --stage 小组赛 --reason-filter low_score --threshold 100 --yes uv run python -m tournament.main --project LDJS2026 --rerun --scope matches \ --match-id S4-R1-01 --reason-filter any --yes # 恢复最近一次撤销作废的结果(生成 manual_restore 裁决,不还原原来源) uv run python -m tournament.main --project LDJS2026 --restore-revoked S4-R1-01 \ --reason "经复核维持原判" --yes # 旧入口保留:撤销并只重发这些场次的补赛任务(等价于 --rerun --scope matches) uv run python -m tournament.main --project LDJS2026 --retry-match S4-R1-01 S4-R1-03 # 导出权威赛果审计包(CSV/JSON/Markdown + ZIP 索引;可加 --with-artifacts) uv run python -m tournament.main --project LDJS2026 --export-results uv run python -m tournament.main --project LDJS2026 --export-results --view referee # 发布/导出自检(只读):每队场次、归属空值、空快照撤销、计划是否收齐 uv run python -m tournament.main --project LDJS2026 --selfcheck uv run python -m tournament.main --project LDJS2026 --selfcheck --require-complete # 数据修复(默认只读;--apply 必须同时 --nodes-stopped --yes) uv run python -m tournament.main --project LDJS2026 --repair-attribution uv run python -m tournament.main --project LDJS2026 --repair-attribution \ --apply --nodes-stopped --yes uv run python -m tournament.main --project LDJS2026 --repair-sealed \ --match-id S1-A-R1-01-M01 --apply --nodes-stopped --yes ``` 赛制在项目的 `schedule.json` 的 `stages` 中描述: ```jsonc { "tournament_name": "LDJS2026-小组赛", "type": "jsql", "defaults": {"duration": 2000, "model": "决胜千里战棋"}, "scenarios": ["Scenario_LDJS2026"], "stages": [ {"name": "小组赛", "type": "group_stage", "group_size": 4, "format": "round_robin", "double": true}, {"name": "组内瑞士轮", "type": "group_stage", "format": "swiss", "rounds": 3, "groups": {"A": ["team_a", "team_b", "team_c"], "B": ["team_d", "team_e", "team_f"]}}, {"name": "瑞士轮", "type": "swiss", "rounds": 3}, {"name": "决赛", "type": "manual", "matches": [ {"match_id": "F1", "scenario": "Scenario_LDJS2026", "red": "team_a", "blue": "team_b"} ]} ] } ``` - `round_robin`:静态展开(红蓝互换;每个配对默认跑遍全部想定); - `group_stage`:`format=round_robin`(默认,`double` 控制红蓝互换)/ `format=swiss` (组内瑞士轮,需 `rounds`;每轮各组独立按本组积分配对,奇数队轮空); - `swiss`:每轮按**本阶段**积分+小分重新配对(避免重赛、红蓝均衡、任意队数; 奇数末位轮空,优先没轮空过的队伍;`rounds` 超过队数-1 会告警); - `manual`:完全手控对局列表(每行是配对模板,按想定池展开)。 #### 多想定:每个配对跑遍全部想定 赛程固定规则:**每个红蓝配对在阶段/赛程想定池的每个想定上各赛一场**,配对、轮空、 红蓝分配算法不变。N 个想定 → N 场,`double=true` 时为 2N 场;动态阶段每轮配对 ×N (轮空不复制),淘汰赛同一配对的 N 场为系列赛,全部有效后按胜场晋级、胜场相同比总净胜分 (仍平或缺比分需人工裁决)。 - **单想想定(N=1)不追加后缀、不写 `series_id/scenario_index`**,旧场次 ID 与 历史计划逐字节不变; - N>1 时场次 ID 追加 `-M01`、`-M02`(按想定池顺序),并带 `series_id` / `scenario_index` 随分片冻结;总榜逐场计分,按想定榜单与 `scenarios.csv` 给出每个想定单独成绩; - 旧的 `scenario_mode` 字段已废弃:`rotate` 会被拒绝,`matrix` 兼容接受;GUI 保存/预览时 自动清理该字段。想限制测试量请减少想定池; - 赛程页「想定库」把“勾选想定”和“导入 `.SCN`”合并在一个组件(位于赛事信息之前): 逐项勾选参与本赛事的想定,默认想定 `Scenario_LDJS2026` 固定展示(项目内缺失时 可一键从仓库模板导入);导入会整套复制同名装备目录与 `Translation.ini`,重名拒绝, 想定库必须在任务目录内;导入后自动勾选,仍需保存赛程。 ### 多机分布式测评(可选 · 单共享目录) 把一个项目的静态对局划成若干**子任务**,各测试机只指向主节点共享出的**一个项目目录** 即可运行,结果自动推回共享目录,主节点一条命令汇总: ```bash # 1) 主节点:生成并发布任务(dist.json → dist/subtasks/.json,含契约指纹) uv run python -m tournament.main --project LDJS2026 --split-dist # 2) 子节点(本机有代码 / 环境 / 引擎即可):列出并认领一个子任务 # 项目配置/想定增量镜像到本机 auto_test/nodes/<项目>/<子任务>/,对局运行期不访问网络 uv run python -m tournament.main --remote \\HOST\share\...\LDJS2026 --list-subtasks # 先备仓(拉取选手仓库 + uv sync,可重复执行;缓存在 auto_test/repos/<项目>/) uv run python -m tournament.main --remote \\HOST\share\...\LDJS2026 --subtask A --prepare-repos uv run python -m tournament.main --remote \\HOST\share\...\LDJS2026 --subtask A # 继续本机逻辑运行:只跑待跑场次(未跑/中断/准备失败/无效/被撤销),成功场次不重跑 uv run python -m tournament.main --remote \\HOST\share\...\LDJS2026 --subtask A --resume # 只补推“本地已成功、共享未收到”的场次(幂等;不重跑对局) uv run python -m tournament.main --remote \\HOST\share\...\LDJS2026 --subtask A --push-only # 专家:把范围缩小到这些待跑场次(已成功的会被忽略;要重跑请由主节点撤销/补赛) uv run python -m tournament.main --remote \\HOST\share\...\LDJS2026 --subtask A --retry-matches S1-A-R1-01 # 3) 主节点:自动发现共享 results/ 下的推送结果并汇总(只读) uv run python -m tournament.main --project LDJS2026 --merge-runs ``` - 分配单位是子任务(`subtasks.`:`groups` / `stages` / `match_ids` 取并集),不再绑定机器名; 每场对局必须恰好属于一个子任务,未分配/重复/瑞士轮都会报错(`allow_unassigned` 可放行并列出); - **主节点不再执行对局**:原 `--project <项目> --subtask ` 本机运行入口已移除; 主节点只生成/发布任务与汇总; - **任务即契约**:生成时冻结场次、赛程/队伍哈希、规则参数+想定内容哈希、划分哈希, 子节点在认领/镜像前逐项重算,任一漂移即拒绝并提示“子任务已过期,请主节点重新生成并发布”; 旧版无指纹的子任务必须重新生成; - **机器配置不影响契约**:引擎/解释器/参考仓库/端口等机器键在归一化哈希中**直接剪除**, 所以各机路径不同、或后来给缺省项补上默认值,都不会让已发布分片变成“已过期”; 该归一化语义更新过一次,**升级后旧分片需重新生成一次**(旧口径 fingerprint 必然不同); - 运行结束(含中断/引擎责任放弃)默认自动推送;推送以 `push.json` 最后写入作为完成判据, 幂等可重推;缺少标记的未完成推送会被汇总跳过并报告;推送失败不改对局退出码,可 `--push-only` 重试; - **未正确完成不推送**:只有退出码 0、胜负有效、非引擎/录像失败的 attempt 才上传; 任何一场失败/超时/中断都不会写运行完成标记(只写 partial `run.json`), 子节点用统一的「继续 / 重试待跑 N 场」补这些场次(成功场次不重跑); - **逻辑单运行**:一个子任务对外只有一个“当前运行”——成功且未被撤销的场次固化, 未跑/中断/准备失败/无效/被撤销的进待跑清单,本地成功但共享未收到的进待推送清单; 内部时间戳批次继续作为审计与 `(source, attempt)` 身份保留,**不迁移、不合并**; 续跑被哈希预检拒绝时,GUI 提供一次显式「新建本机批次」(旧批次只读), `--run-dir` 仅留给 `--push-only` 排障; - **主节点只有一个「重跑」动作**:按场次状态自动分派(无结果→只下发范围;自动赛果→撤销+回收+下发; 判决→撤销判决+下发;主办方裁决→默认跳过),预览时列出五类分派与将被作废的旧 winner/比分/来源, 必须显式确认“作废 N 场”才执行;分批执行(默认 20 场)并落 `competition/reruns/.json`, 重复点击幂等(已撤销场次不会追加第二条撤销事件);「作废」保留为高级动作(只作废不重跑); - **运行产物采集由主节点选择**(`base.json.artifact_capture.exclude`):默认**不采集** `engine_backend.log`,执行器在本把结束时删除,因此子节点不保留也不推送/汇总/导出; 该策略不进任务契约(改它不会让已发布分片过期),子节点不可覆盖; - **失败判决的证据全量回传**:判决时把该把日志复制到 `////evidence/_attempt//`(含 `evidence.json` 清单), 主节点能像看正常场次一样看到失败现场;它不在 `attempts/` 下,因此不会污染赛果/交付判断; 单次证据总量默认上限 256 MiB(`base.artifact_capture.evidence.max_total_bytes`),超限只记清单; 结果页有效赛果表每行都有「目录」按钮,直接打开该场在共享目录里的储存位置 (正常场次打开 `attempts/…`,判决场次打开 `evidence/…` 或 `verdicts/`); - **判负也是有效赛果**:选手缺席/断连由调度器给出明确责任方(`exit_code=2` + `forfeit`) 时,该场按对手获胜推送并计分;其余非 0 退出码仍不推送; - **全部失败的场次可由子节点人工判决**:当前分片内、已有本机终态证据的失败/无效场次 (准备失败、选手退出、引擎/基础设施/录像无效)可在执行台逐场录入胜负、可选成对红蓝比分 和必填原因;判决走独立通道(`<运行>/verdicts/.json`,**不写 `attempts/`**)推送, 主节点**无需重跑/无需先汇总**即可在结果页看到并汇总、导出;判决计交付但不与正常完赛混淆。 未跑/进行中/已成功/跨分片/主节点已裁决或撤销的场次一律拒绝;主节点裁决仍最高优先, 撤销/补赛会把该场判决移入共享回收区并在补赛新批次上自动解封;无比分判决只计胜负与积分, 不计净胜分(淘汰赛系列赛缺比分破平仍要求主节点裁决); - **补赛不会“先删后发”**:先按当前划分写出新分片,成功后才撤销旧赛果并回收旧结果; 任务划分已变化时直接报错,旧结果保持有效(需要先重新生成并发布任务); - **补赛结果会重新生效**:撤销事件记录被撤销结果的 `(source, attempt)` 快照, 只屏蔽撤销时已存在的那一批;补赛重跑并推送后(身份不同)自动恢复计分, 不会出现“补赛跑完仍待补赛 / 下一轮永远无法生成”。升级前无快照的旧撤销事件保持原行为, 需要重新补赛一次(会产生带快照的新撤销事件); - **撤销在所有视图上一致**:推送事件带稳定来源标签(子任务/节点/运行名), 结果页、汇总报告与审计导出用同一身份判断撤销;推送后尚未汇总就撤销也会被正确屏蔽与解封; - **判负可恢复**:缺席/断连判负(`exit_code=2` + `forfeit`)首次推送失败后, `--push-only` / 界面「只推送」会带着责任方重推,不需要整场重跑; - **全量发布默认只跑未完成场次**:`match_ids` 保留子任务完整归属,`run_match_ids` 只含尚未有效完成的场次;按轮局部发布时归属取“本轮 ∪ 历史仍归属场次”, 因此前几轮仍可补赛。要强制重跑已完成场次请用补赛/`--retry-matches`; - **强制重跑不自动接管占用**:子任务被其它节点占用时,`--force` 也不足以接管, 需 `--force-active` 或由主节点确认后强制释放(两个节点同时跑同一分片会重复比赛); - **同一台机器只能跑一个 jsql 运行/备仓**:本机文件锁会拒绝第二个实例(避免争用引擎端口、 受管 OBS 与选手仓库缓存);OBS 自检与正式录像共用同一把本机锁(`auto_test/locks/obs.lock`), 第二个进程不会强行接管;存在活跃占用时,`--force` 不足以接管,需 `--force-active` 或由主节点人工强制释放; - **共享盘短抖动有界重试**:网络类错误指数退避(总窗口约 45 秒),权限/配置错误立即失败; 复制不完整不会写完成标记,旧结果在替换失败时回滚; - **先规划、后引擎**:每把先拉起红蓝选手并等双方完成任务规划(默认 600 秒), 就绪后才开录像、启动前后端;**录像确认开始后再固定等待 5 秒**才拉起引擎, 给 OBS 场景/编码器稳定时间(关闭录像时不等待,不新增配置键、不影响任务契约); 选手在接入前退出会秒级失败并保留选手日志, 不会被误记为引擎责任(选手启动/接入失败为退出码 4,属确定性失败,不自动重赛); 子节点运行卡会显示“已等待 / 上限 / 已接入方”,不会把等任务生成看成没反应; - **选手依赖各自独立**:`jsql_match.dependencies.uv_sync`(默认开启,超时 20 分钟)时在选手 clone 内 执行 `uv sync`,该仓 `.venv` 就是该方解释器;仓库无 `pyproject.toml` 时跳过,缺 `uv.lock` 时降级为非冻结; 选手仓库缓存在 `auto_test/repos/<项目>/teams/<队伍>`(跨运行持久,不重复 clone/建环境), 子节点在「检查与运行」页**选定子任务**后点「备仓(仅所选子任务)」或 `--prepare-repos`, 只准备该子任务出场选手的仓库、uv 环境与专用参考仓库,把首次拉取与比赛时间分开; GUI 备仓在后台执行并**实时显示阶段日志**(`auto_test/nodes/<项目-根哈希>/prepare.log`, 只写本机、不上传),备仓期间禁止启动/推送; - **各机引擎/解释器路径可以不同**:用 `--node-config auto_test/nodes/<项目>/node_config.json` (或同路径默认文件)覆盖 `jsql_engine` / `jsql_match` / `jsql_obs` / `teams` 中的本机路径; 覆盖是**严格白名单**:非机器字段(决策方式/赛程等)与不存在的路径会直接拒绝执行, 只作用于本机镜像、不写回共享;模板见 `config/tournament/node_config.json.example`; - **开启选手依赖同步后不需要手填解释器**:各队解释器取备仓仓库的 `.venv`;共享配置里的 `engine.python`、`players.*.python`、`players.*.repo_path`、`engine.reference_repo` 在子节点会被清除 (只认本机覆盖,避免别的机器的 Linux/Windows 路径混入);`engine.reference_repo` 留空时, 执行器会从**专用参考仓库** `engine.reference_git_url`@`reference_ref`(默认 `https://gitee.com/mouxuezha/text_jsql.git`@`dev-ldjs2026`)克隆到本机缓存并建立独立 `.venv`, **不使用选手提交仓库**;可先「备仓」预拉取; 推演项目**不校验也不应用** `warchess` / `warchess_env`(旧文件里的战棋段保留但不生效), 因此残留的仿真平台占位符不会再阻断 jsql;战棋项目仍严格校验; - 测试项目(如 `test_st`)的旧配置直接编辑项目内的 JSON 即可,不再提供迁移工具; - **本机目录按任务隔离**:镜像/备仓/本机覆盖/推送回执的目录键为 `<项目名>-<规范化项目根短哈希>`,两个同名但不同共享目录的任务不会互相污染; 旧版「仅项目名」目录继续可用,但只会复用于台账 `header.remote_root` 能证明归属的任务; - **开赛前准备失败不会“卡死整批”**:备仓/`uv sync`/想定部署失败或对局无效(录像/引擎责任)时 **只跳过该场**并记为待重跑,其余场次照常跑完(退出码 2,已完成场次照常出报告并推送); 同一原因反复失败只告警不停止,修好后续跑会自动补跑这些场次; - **改划分后的旧推送不再卡死汇总**:不属于当前分片的场次被隔离为 `stale_pushes` (只隔离、不删除共享文件),真正同一分片的跨节点重复仍然阻断; - 汇总只读扫描 `<项目>/results/<子任务>/<节点>/<运行名>/`,输出 `runs/_<赛事名>_merged/` (`nodes.json` 含子任务级进度与缺失/重复信息;不写 `ledger.jsonl`,不会被 `--resume` 误认); - 动态阶段(瑞士轮 / 组内瑞士轮 / 淘汰赛)在主节点「子任务」页逐轮生成后按轮发布; 本轮全部有效完成后才能生成下一轮;旧「按机器名绑定节点」的 `dist.json` 不再支持,请按子任务结构重写。 `dist.json` 模板见 `config/tournament/dist.json.example`。GUI「子任务」页提供等价操作, 「子节点」页负责本机环境与领取任务。详见 [tournament/TOURNAMENT.md](tournament/TOURNAMENT.md)。 台账、续跑、报告与故障处理细节见 [tournament/TOURNAMENT.md](tournament/TOURNAMENT.md)。 ## 配置 > 运行期配置在 `auto_test/projects/<项目>/`(`base.json` 内的相对路径相对该项目根解析); > `config/` 仅作为新建项目的模板库,运行期不再读取其中的真实配置。 ### 1. 统一队伍表 `<项目>/teams.json` 新建项目时会自动从 `config/teams.json.example` 复制一份待填写的 `teams.json`(含密钥,`auto_test/` 已 gitignore)。 ```jsonc { "teams": { "Demo队1": { "name": "Demo队1", "warchess": {"api": {"base_url": "https://...", "api_key": "sk-xxx"}, "timeout_seconds": 60, "elo": 1500}, "jsql": {"git_url": "...", "ref": "main", "python": "", "decision_mode": "remote", "bailian": {"app_id": "", "api_key": "sk-xxx"}} } } } ``` 若尚无队伍表,可从 `config/teams.json.example` 复制后填写。GUI 在项目内 `teams.json` 不存在时会直接展示 `.example` 中的占位队伍供参考,保存后写入项目内真实队伍表。 推演比赛的单场决策模式回退链:**单场 `matches[].decision_mode` > 队伍 `jsql.decision_mode` > `remote`**; 前端下拉默认预选 `remote`。`schedule.defaults.decision_mode` 已废弃并移除。 ### 2. 战棋 `<项目>/warchess.json` ```jsonc { "env_config": "warchess_env.json", "default_model": "决胜千里战棋", "models": ["决胜千里战棋"], "max_moves": 200 } ``` > 远端智能体(阿里百炼)已内置提示词工作流,本地不再配置提示词;请求中只发送一个占位指令。 > `env_config` 相对路径按 warchess.json 所在目录优先解析,其次仓库根(兼容旧 `config/` 布局)。 战棋真机需先准备本机环境配置(新建项目会把真实文件或 `.example` 复制为项目内 `warchess_env.json`): ```bash # 仅当项目内缺失时手动补齐 cp config/tournament/warchess_env.json.example auto_test/projects/<项目>/warchess_env.json ``` 需核对前端/后端 exe 路径、`ip_to_chess`、`id_address_files`(推荐按 `key` 定位而非行号)。 三端 IP 必须一致:前端 `grpcConfig.ini` 的 `backendIp` = 后端 `craftgame.yml` 的 `grpc_bind_ip` = `ip_to_chess`。 不一致时前端建不起 gRPC 通道,表现为**棋盘无棋子、日志无「回合 x 开始」**。 ### 3. 推演 `<项目>/jsql_engine.json` / `jsql_match.json` 见 [tournament/WINDOWS_TEST.md](tournament/WINDOWS_TEST.md) 的逐字段清单。 ### 4. 想定库 `<项目>/scenarios/` 新建项目默认复制 `config/scenarios/`;若选择不复制(`--no-copy-scenarios`),`base.json` 的 `scenario_root` 会写成 `../../config/scenarios` 之类的相对引用。 ``` config/scenarios/ ├── <想定名>.SCN ├── <想定名>/ # 同名装备目录(.ASB/.CEP/.COMP,可含 Translation.ini) └── Translation.ini # 共享翻译表 ``` ## 单局对弈(无需赛事) ```bash # 默认棋种(决胜千里战棋) uv run python main.py --red "Demo队1" --blue "Demo队2" # 指定产物目录(默认 auto_test/eval/<时间戳>_<红>_<蓝>/) uv run python main.py --out-dir auto_test/eval/my_debug --red "Demo队1" --blue "Demo队2" # 列出队伍 uv run python main.py --list-players ``` 回放、SVG 棋谱、`result.json` 与日志统一保存在 `auto_test/eval/<时间戳>_<红队>_<蓝队>/`(与赛事产物 `auto_test/runs/` 同级)。 ## 远端智能体协议 远端智能体(阿里百炼)已内置提示词工作流,本仓库只发送占位指令;双方使用同一套 HTTP 协议,仅 `biz_params.chess_status` 的内容不同。 ### 请求(POST JSON) ```json { "input": [{"type": "message", "role": "user", "content": [{"type": "input_text", "text": "<占位指令;远端智能体已内置提示词工作流>"}]}], "stream": false, "biz_params": {"chess_status": {"...": "见下表"}} } ``` | 字段 | 类型 | 说明 | |---|---|---| | `status` | list[dict] | 棋子列表 | | `status[].name` | str | 棋子中文名 | | `status[].code` | str | 棋子字母代号 | | `status[].location` | str | ICCS 坐标 | | `status[].action` | list[str] | 合法终点列表(终点为敌子即攻击) | | `next` | str | `RED` / `BLACK` | | `step_num` | str | 步数 | | `time` | str | 时间戳 | | `replay` | list[dict] | 历史走法 | 战棋坐标域 `a-m × 0-13`(13×14),`status[]` 额外含 `id` / `side`。 | 战棋棋子 | 中文名 | code | 走法参考 | |---|---|---|---| | 101 | 旗舰 | f | 九宫格内移动 | | 102 | 护卫舰 | g | 九宫格内斜走 | | 103 | 巡洋舰 | c | 远程射击 | | 104 | 驱逐舰 | d | 前进(可升变) | | 105 | 战机 | a | 走"目"字 | | 106 | 潜艇 | s | 隐蔽机动 | | 107 | 预警机 | w | 走"田"字、不过河 | ### 响应 走法位于 `output[0].content[0].text`(JSON 字符串),解析后: ```json {"action": "e7e8"} ``` `action` 为 ICCS 走法(起点+终点),数组时取首元素。 ## 辅助脚本 ```bash # 战棋态势 JSON → 文本棋盘 + 自然语言(移植到低代码平台用) uv run python debug/agents/json2text_warchess.py [态势.json] # 远端智能体单步调试(战棋) uv run python debug/agents/agent_demo_warchess.py --url --key [态势.json] ``` ## 依赖与运行环境 - Python ≥ 3.12,依赖由 uv 管理:`uv sync`(已移除 `requirements.txt`,避免两份依赖不同步); - 唯一为 GUI 新增的依赖是 `pywebview`; - 推演执行器需用装了 `text_jsql` 依赖的解释器(`config/teams.json` 的 `jsql.python`)。 ## 已知限制 - 推演比赛串行执行(单引擎独占三端口);战棋可并发(每个子进程自带平台实例与端口偏移); - 推演比分取自引擎态势 JSON 的顶层 `score`(`redScore/blueScore/redDestroyScore/...`),逐帧写入 `match_log` 并贯穿台账/报告;`GetCurrentResult()` 在后端未实现(恒 0:0),仅作回退; - 小组赛晋级名单需在后续 `manual` / `swiss` 阶段显式表达,暂不自动晋级; - 只支持 Windows(引擎进程控制、仿真平台均为 Windows 可执行文件)。