# agent_interface **Repository Path**: mouxuezha/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-07-09 - **Last Updated**: 2026-11-14 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 服务于网上大模型平台和本地程序接的 ## 概述 服务于职工技能大赛等场景,从阿里云百炼等网上大模型平台接收数据并分发,驱动决胜千里战棋和中国象棋对弈。 **核心架构**: 本项目不构建本地 LLM 智能体,而是作为后端驱动程序—— 将当前棋盘/战场的 JSON 态势通过 HTTP POST 发送到**远端低代码平台上预构建好的下棋智能体**, 接收并解析走法,驱动本地引擎推进对局。 ``` 远端智能体 (低代码平台预构建) ←→ 后端驱动 (本项目) ←→ 战棋引擎 (cchess 中国象棋、决胜千里战棋仿真平台) ``` **棋种支持**: 通过 `main.py --model` 或 `runner(model=...)` 选择对弈环境: | 棋种 | 环境实现 | 说明 | |------|----------|------| | `象棋` | [debug/chinese_chess_wrap/env.py](debug/chinese_chess_wrap/env.py) | 已跑通的遗留 demo,基于 `cchess` 库,纯内存、秒级 reset | | `决胜千里战棋` | [env_communication/warchess_wrap/env.py](env_communication/warchess_wrap/env.py) | 主战场,依赖本地仿真平台(前端 exe + 后端 exe + TCP),见下方前置条件 | 两种环境对外裸露同一套接口(`reset` / `step(action, side)` / `get_legal_moves(side)` / `get_status_dic` / `check_winner` / `render`),因此 `runner`、`player` 与远端智能体的通信层完全复用。 --- ## 代码结构 ``` agent_interface/ ├── main.py # CLI 入口:--model/--red/--blue/--list-players 等 ├── craft_manager/ # 对战管理与调度(核心编排层) │ ├── CraftManager.py # 赛事管理器:生成赛程、多线程调度、ELO 积分更新 │ ├── player.py # 选手代理:向远端智能体发送态势、解析走法(棋种无关) │ └── runner.py # 单局运行器:管理红/蓝双方交替走子、棋局推进 │ ├── env_communication/ # 仿真平台交互层(只做与仿真平台的交互) │ └── warchess_wrap/ │ ├── env.py # 决胜千里战棋环境封装(起 exe、TCP、态势导出) │ ├── NavalChess.SCN # 仿真平台想定场景文件(拷贝到后端目录) │ └── chess_ai/ # 战棋 AI 基类与规则 │ ├── base.py # ChessAI 基类:TCP 握手/回合循环/收发走子 │ ├── board.py # 棋盘与棋子数据结构(BoardState/Piece) │ ├── rules.py # 7 类棋子合法走子生成器 │ ├── constants.py # 阵营/棋子类型/棋盘尺寸等枚举常量 │ └── protocol.py # TCP 消息协议(Hello/TurnStart/Move/IllegalMove/GameOver) │ ├── debug/ # 调试与中国象棋环境 │ ├── test1.py # 百度 AppBuilder 测试 │ ├── agents/ # 远端智能体调用示例与 json→自然语言脚本 │ │ ├── agent_demo.py # HTTP POST 调用远端下棋智能体的参考实现(象棋) │ │ ├── agent_demo_warchess.py # 同上的战棋版:单步远端测试 + 文本棋盘预览 │ │ ├── json2text.py # 将 JSON 象棋状态渲染为文本二维棋盘 (调试用) │ │ ├── json2text_warchess.py # 将 JSON 战棋态势渲染为文本棋盘+自然语言描述(可移植低代码平台) │ │ └── data/ │ │ ├── chinese_chess_status.json # 示例象棋状态数据 │ │ └── warchess_status.json # 示例战棋态势数据(真实初始布局) │ └── chinese_chess_wrap/ │ └── env.py # 中国象棋环境封装(基于 cchess 库) │ ├── model_communication/ # 大模型通信层(直连大模型,非本项目的对战链路) │ ├── model_comm_openai.py # OpenAI 兼容调用 │ ├── model_comm_langchain.py # LangChain 版调用(遗留) │ └── model_config.py # 模型配置 │ ├── mqtt_communication/ # MQTT 消息通信 │ ├── MQTT_listen.py # MQTT 订阅端 │ └── MQTT_send.py # MQTT 发布端 │ ├── support/ # 工具支持 │ ├── text_loader.py # JSON 配置加载(统一入口) │ ├── text_transfer.py # 文本解析 │ └── change_ip.py # 仿真平台 IP 配置改写 │ └── config/ # 配置文件 ├── IPconfig.json # 网络/MQTT 服务器配置 ├── dify_to_local_proto.json # Dify → 本地 协议模板 ├── local_to_dify_proto.json # 本地 → Dify 协议模板 ├── craft_manager/ │ ├── player_config.json # 队伍配置(队伍名、ELO、远端智能体 URL/Key;含密钥,已 gitignore) │ ├── player_config.example.json # 队伍配置模板 │ └── game_config.json # 按棋种区分发给远端智能体的提示词 └── env_config/ ├── 决胜千里战棋.json # 战棋仿真平台路径/IP/场景等配置 └── 决胜千里战棋.json.example # 战棋环境配置模板 ``` --- ## 远端智能体接口协议 两种棋种使用**同一套 HTTP 协议**,仅 `biz_params.chess_status` 的态势内容与提示词不同。 ### 请求格式 (POST JSON) `player.py` 向远端智能体发送的 HTTP 请求体: ```json { "input": [{ "type": "message", "role": "user", "content": [{ "type": "input_text", "text": "<按棋种从 config/craft_manager/game_config.json 读取的提示词>" }] }], "stream": false, "biz_params": { "chess_status": { "...": "见下方态势结构" } } } ``` 提示词按棋种在 [config/craft_manager/game_config.json](config/craft_manager/game_config.json) 中配置,由 `player.py` 经 `support.text_loader` 加载。 **`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] | 历史走法序列 | **象棋专属**(`status[]` 无 `id`/`side` 字段,坐标域 `a0~i9`): ```json { "status": [ {"name": "帅", "code": "k", "location": "e0", "action": ["e1", "f1"]}, {"name": "车", "code": "r", "location": "a0", "action": ["a1", "a2"]} ], "next": "RED", "step_num": "10", "time": "2025-01-01 12:00:00", "replay": [{"player": "RED", "action": "b2e2"}] } ``` **决胜千里战棋专属**(`status[]` 额外含 `id`/`side`,坐标域 `a-m × 0-13`,13×14 棋盘): ```json { "status": [ {"name": "旗舰", "id": "1", "side": "Red", "code": "f", "location": "g0", "action": ["g1", "f0"]}, {"name": "护卫舰", "id": "2", "side": "Red", "code": "g", "location": "f0", "action": ["g0"]} ], "next": "RED", "step_num": "5", "time": "2026-09-27 12:00:00", "replay": [] } ``` | 战棋棋子 | 中文名 | code | 走法参考 | |----------|--------|------|----------| | 101 | 旗舰 | f | 九宫格内移动(参考象棋帅/将) | | 102 | 护卫舰 | g | 九宫格内斜走(参考士/仕) | | 103 | 巡洋舰 | c | 远程射击 | | 104 | 驱逐舰 | d | 前进(参考兵/卒,可升变为巡洋舰) | | 105 | 战机 | a | 走"目"字(参考马,斜目) | | 106 | 潜艇 | s | 隐蔽机动 | | 107 | 预警机 | w | 走"田"字、不过河(参考相/象) | > 战棋态势中的 `id` 为棋子实体编号(红方 1-17,蓝方 18-34),`side` 为 `Red`/`Blue`。 ### 响应格式 远端智能体返回的 HTTP 响应体中,走法位于 `output[0].content[0].text`: ```json { "output": [{ "content": [{ "text": "{\"action\":\"e7e8\"}" }] }] } ``` `text` 字段内为 JSON 字符串,解析后: ```json {"action": "e7e8"} ``` - `action`: ICCS 格式走法字符串(起点坐标 + 终点坐标拼接,如象棋 `e7e8`、战棋 `g5g6`),或数组取首元素 --- ## 战棋 LLM 智能体构建辅助脚本 `debug/agents/` 下的两个战棋脚本用于在**远端低代码平台上构建战棋智能体**:先把 `chess_status` JSON 转成自然语言,再喂给 LLM 决策。 ### json → 自然语言:`json2text_warchess.py` 将战棋态势 JSON 渲染为「文本二维棋盘 + 自然语言态势描述」,是战棋智能体构建中的 json→NL 核心脚本。 ```bash python debug/agents/json2text_warchess.py # 用默认样例态势 python debug/agents/json2text_warchess.py <战棋态势.json> # 指定态势文件 ``` - 与 [json2text.py](debug/agents/json2text.py) 约定一致:`main()` 直接读取模块全局 `params`(`params["status"]` 为态势字典),返回 `{"board_text": <文本棋盘 + 自然语言描述>}`,可直接移植到阿里百炼等平台。 - 棋盘为 13×14(列 a~m,行 0~13),红方在下、蓝方在上,四角岛屿标为「岛」;棋子以「阵营标记 + 中文名」显示(如「红旗舰」)。 - 自然语言部分列出双方每枚棋子的 id/位置/可走终点,并标注当前走棋方与历史走法。 ### 远端单步测试:`agent_demo_warchess.py` 参照 [agent_demo.py](debug/agents/agent_demo.py) 实现,向远端战棋智能体发一次请求并解析走法,用于联调验证。 ```bash python debug/agents/agent_demo_warchess.py --url <智能体URL> --key # 用默认样例态势 python debug/agents/agent_demo_warchess.py --url <智能体URL> --key <战棋态势.json> # 指定态势文件 ``` - 远端智能体的地址与密钥通过命令行参数 `--url` / `--key` 传入(测试脚本,不读取 .env)。 - 请求体与正式链路一致(`biz_params.chess_status` + 战棋提示词);返回解析为 `{"action": [...], "others": "..."}`。 - 运行时会先打印文本棋盘,便于肉眼核对。 --- ## 当前数据流 ``` main.py (CLI入口, --model 选择棋种) └─→ runner (单局对弈, 含走法合法性校验与随机兜底) ├─→ player (红方) ──HTTP POST──→ 远端智能体 (低代码平台) ├─→ player (蓝方) ──HTTP POST──→ 远端智能体 (低代码平台) └─→ Env (象棋: cchess 1.25.5 | 战棋: 决胜千里战棋仿真平台) ``` --- ## 快速开始 ### 1. 配置队伍与远端智能体 每个队伍的远端智能体地址和密钥直接写在 [config/craft_manager/player_config.json](config/craft_manager/player_config.json) 中(**不再使用环境变量**)。可从模板复制(`player_config.json` 含密钥、已被 `.gitignore` 忽略): ```bash cp config/craft_manager/player_config.example.json config/craft_manager/player_config.json ``` ```json { "Demo队1": { "name": "Demo队1", "ELO_R": 1500, "timeout_seconds": 60, "API": { "base_url": "https://dashscope.aliyuncs.com/api/v2/apps/agent/xxx/compatible-mode/v1/responses", "api_key": "sk-xxxx" } } } ``` > `.env.example` 中的 `CHESS_AGENT_URL_* / CHESS_AGENT_KEY_*` 环境变量方式已废弃,仅存档参考。 按棋种发给远端智能体的提示词在 [config/craft_manager/game_config.json](config/craft_manager/game_config.json) 中配置(key 为棋种名)。 ### 2. 战棋前置条件 `--model 决胜千里战棋`(默认)需要本地仿真平台就绪(Windows)。 ##### 2.1 从模板生成本机配置 `决胜千里战棋.json` 含本机绝对路径,**已加入 `.gitignore` 不入库**;请从同名模板复制后按本机环境修改: ```bash cp config/env_config/决胜千里战棋.json.example config/env_config/决胜千里战棋.json ``` ##### 2.2 检查配置项 - `exe_location1/exe_name1`(前端 `MilitaryChess.exe`)、`exe_location2/exe_name2`(后端 `craftgameserver.exe`)路径正确 - `ip_to_chess`(战棋对端 IP) - `id_address_files`(需改写的 IP 配置文件列表) `id_address_files` 每项支持两种定位方式,**推荐用 `key`**: | 字段 | 说明 | |------|------| | `key` | 按配置项名匹配行改写(如 `grpc_bind_ip`、`backendIp`),同名重复行会自动去重,**不受上游文件插入注释/行漂移影响** | | `line` | 兼容旧写法的硬编码行号;上游文件一旦插入行就会改错行,不建议使用 | > ⚠️ **三端 IP 必须一致**:前端 `grpcConfig.ini` 的 `backendIp` = 后端 `craftgame.yml` 的 `grpc_bind_ip` = `ip_to_chess`。 > 若不一致,前端建不起到后端的 gRPC 通道,也就拿不到战场态势,表现为**棋盘无棋子、日志中看不到 `回合 x 开始`**,随后远端智能体收到空态势并超时。 > 可通过前端日志(`<前端目录>/logFile/MilitaryChess_*.log`)确认:正常应有 `[后端] gRPC 通道 已建立` 与 `[联机] [态势] ... simTime=0`。 ##### 2.3 运行行为 程序会自动拉起前端与后端 exe、拷贝 `NavalChess.SCN` 场景、并通过 TCP `127.0.0.1:9999` 与前端通信。启动耗时较长(`chess_ai_delay` 秒)。`Env.reset()` 会先清理残留 exe 并等待 9999 端口释放再重启平台,初始化结束时阻塞等待首个 `TurnStart`(超时会给出排查提示)。 象棋(`--model 象棋`)无此前置条件,纯内存运行。 ### 3. 查看可用队伍 ```bash uv run python main.py --list-players ``` ### 4. 运行对弈 ```bash # 默认棋种(决胜千里战棋) uv run python main.py --red "Demo队1" --blue "Demo队2" # 指定棋种为中国象棋 uv run python main.py --model 象棋 --red "Demo队1" --blue "Demo队2" # 调试模式 uv run python main.py --red "Demo队1" --blue "Demo队2" --log-level DEBUG ``` > 回放(走法序列 + SVG 棋谱)由 `runner` 自动保存到 `auto_test/{红队}_{蓝队}/`,无需手动指定。 ### 5. 运行完整联赛(多线程) ```bash uv run python -c " from craft_manager.CraftManager import craft_manager cm = craft_manager() # 默认棋种已在 CraftManager 内设为 决胜千里战棋 cm.run_mul(cm.config_dict['play_schedule'], thread_number=2) " ``` ### 6. 运行完整联赛(多线程+免uv+调试) - VScode打开工程 - 调试运行CraftManager.py - CraftManager.py中可修改线程数thread_number - 根据线程数,程序自动均衡分配所有对局(play_schedule)到各个线程(departed_schedule_list) - 根据均衡载荷结果,组织启动多线程运行。 - 结果储存在auto_test/craft_manager/目录下拆分的play_schedule_*.json文件中 --- ### 7. 运行完整联赛(多线程+多机协同) - VScode打开工程 - 调试运行CraftManager_interface.py ### 8. 小工具: - 快速打压缩包发布 - 快速改IP端口 - 从网页的提交结果直接生成player_config.json - ... ## 调试 - 远端智能体调用测试(象棋):`python debug/agents/agent_demo.py --url --key `(单次请求测试) - 远端智能体调用测试(战棋):`python debug/agents/agent_demo_warchess.py --url --key `(单次请求 + 文本棋盘预览) - 战棋 json→自然语言自测:`python debug/agents/json2text_warchess.py` - 单局对战(战棋):`uv run python main.py --red "Demo队1" --blue "Demo队2" --log-level DEBUG` - 单局对战(象棋):`uv run python main.py --model 象棋 --red "Demo队1" --blue "Demo队2" --log-level DEBUG` - 象棋环境自测:`uv run python debug/chinese_chess_wrap/env.py` - 决胜千里战棋环境自测:VScode debug 运行 [env_communication/warchess_wrap/env.py](env_communication/warchess_wrap/env.py) - LLM 对话日志:`auto_test/log_*.txt` ## 依赖安装 ```bash uv sync ``` ## 不依赖uv的模式: - VScode+Anaconda,进目录run and debug运行main.py - 依赖项用requirements.txt装,手动看着调一下。 ## 说法 - 成长曲线还是比较平滑的,前面有长沙反无后端为基础,这个整完,后面丝滑转到方案生成那一类的。 - 需要就上 MQTT,不需要就先不慌 - 决胜千里战棋依赖本地运行环境,需要关注“config\env_config\决胜千里战棋.json”配置文件看是否正确。该文件含本机路径、不入库,需从 `决胜千里战棋.json.example` 复制;其中 `id_address_files` 推荐用 `key` 而非 `line` 定位,否则上游文件插入注释后行号漂移会改错行,导致前后端 gRPC 的 IP 不一致、棋盘无棋子。