CARLA交通场景MCP服务

本项目面向学生实验：学生在百炼Managed Agent中用自然语言描述交通场景，大模型编写场景业务逻辑，MCP提供版本参考、地图位置检索、经过测试的通用运行能力、静态检查和单文件组装，学生下载Python文件并在本机CARLA运行、观察和反馈。

0.2.1提供通用运行辅助、同一路口多条行驶连接检索及完整精度的道路定位，配套新版学生提示词。提示词会核验服务是否提供runtime_helpers，避免服务与提示词不配套。

场景逻辑由模型动态编写，样例不限制学生的问法或轨迹生成方式。MCP不执行模型生成的场景代码，静态检查通过不等于真实场景已运行或满足要求。

环境与内置资料

• MCP服务端：Python 3.10及以上，不需要安装或启动CARLA。
• 学生实采基线：Windows 64位、Python 3.8.10、CARLA客户端/服务端0.9.12。输出保持Python 3.7语法兼容初筛，这不是Python 3.7实机验收结论。
• 依赖限定为CARLA客户端及工具返回的Python标准库清单，不默认接受numpy、networkx或agents。
• 随包包含11张完整采集地图的检索目录、184个实采蓝图及属性、固定0.9.12提交的API参考。
• 地图包括Town01、Town02、Town04、Town05、Town10HD的普通版与_Opt，以及Town03_Opt。普通Town03在采集环境加载异常，未纳入可生成目标地图。

目录包含2,868条候选记录，其中18条环岛通行记录。它们来自实际采集和明确的几何推导，不是2,868个独立路口，也不保证任意自然语言要求都有匹配。

三个工具

参考查询：

{"topics":["maps","actors","control"]}

需要蓝图时可加入resource:vehicle.*、resource:vehicle.tesla.model3或resource:static.prop.*barrier*。每个模式最多返回20项，截断后应缩小范围。需要类方法参数时，可加入api:carla.Map或api:carla.Vehicle等，每次最多返回20类。

地图检索

默认读取包内目录，无需教师或学生上传地图索引，也无需设置CARLA_MAP_CATALOG。需要测试其他同格式目录时可以设置该变量覆盖。

支持的条件：

• junction_type：any、road、T、cross、roundabout、multi_way。
• turn：any、left、right、straight。
• signal_required：布尔值。
• min_exit_lanes、max_exit_lanes：出口车道数量范围。
• min_exit_length_m：目录中连续出口段的最小长度。
• lane_change：any、left、right、either。
• map、junction_id：按明确地图或路口查询；学生一般不需要填写。
• exclude_junction_ids、exclude_location_ids：换址时排除已用位置。
• limit：返回1至10条候选，默认3条。
• movements：同一路口1至16条连接要求，每项包含entry_from或exit_to，可带turn和role；这不是车辆数量限制。方向采用世界+X东、-Y北。返回movement_matches逐条保留真实定位和证据；顶层条件仅筛选锚点连接。

例如：

{"requirements":{"junction_type":"T","turn":"right","min_exit_lanes":2,"lane_change":"left"}}

matched返回候选及证据；no_match_in_index返回未满足条件和备选建议，备选不能当作已经匹配；unsupported_condition表示条件没有结构化查询依据；invalid_request表示参数或要求冲突；catalog_error表示目录读取异常。无匹配不等于所有官方地图都不存在该场景。

同一物理路口的普通版与_Opt会去重。route_hint是稀疏定位/路径提示，模型仍需在本机查询waypoint、核验车道并编写连续路线及控制逻辑。

生成程序契约

模型提交以下函数及必要辅助代码：

def setup_scene(ctx):
    pass


def step_scene(ctx, elapsed_seconds, frame_index):
    return False

公共骨架负责连接、地图加载、同步主循环、观察更新和清理。创建对象用ctx.spawn_actor，其他方式创建后立即ctx.register_actor；状态保存到ctx.state。恢复操作通过ctx.restore_after_run登记。

get_carla_context.runtime_helpers直接从随包源码提取公开方法签名与说明。优先使用waypoint将真实定位记录转为CARLA路点、spawn_vehicle的有限同路线候选、trace_route的连续路径和准确出口检查、route_progress的实际进度、drive_route的跟踪与末端停车、conflict_region的路径几何参考以及set_traffic_lights的先登记恢复后修改。模型仍决定角色、动作、事件条件和参数，可生成特殊算法。辅助源码在组装时直接嵌入完整脚本，学生本机不需要安装MCP包。

定位记录的s保留实采原始精度，不四舍五入。waypoint对旧记录的小误差只允许恢复同道路、车道且位置/方向匹配的真实端点，歧义或超差明确失败。trace_route默认严格满足前后延伸长度；自动布局可显式设置allow_shorter=True，在分支或道路末端前停止延伸并返回实际长度，路口内部路径仍须完整。学生指定精确距离时保留严格模式。

使用ctx.follow_actor(actor, distance=8, height=5, pitch=-20)设置主窗口跟随，或用ctx.observe(location, height=30, yaw=0, pitch=-75)设置俯视。每帧函数必须有界、非阻塞，不自行tick、切图或建立主循环。

生成脚本支持--help、--check、--host、--port、--duration、--timeout和--realtime。--realtime按墙钟限速，保持0.05秒同步步长；--check只读核对连接、版本和地图可用性，不创建场景；--timeout限制单次CARLA通信等待，不会强行中断模型回调内的无限循环。

从源码启动

uv run carla-traffic-mcp

默认stdio协议，启动后等待MCP客户端请求。安装时显式固定版本：

uvx --from carla-traffic-mcp==0.2.1 carla-traffic-mcp

部署前确认所选版本已经在PyPI发布；正式课程版本和云端部署结果以本次发布记录及课程参数单为准。

标准百炼托管配置与开发诊断

课堂发布门槛是学生按手册复制标准uvx配置后可直接部署并调用MCP，不要求学生进入函数计算控制台修改启动参数。

使用标准uvx托管配置；云端的已部署版本与工具调用结果以具体服务验收记录为准。开发诊断不作为学生操作步骤，发布PyPI后不会自动更新既有云端服务。

百炼Managed Agent文件交付

本课程使用Managed Agent的write、read和mark_artifacts。配置中应显式启用write和read，mark_artifacts由平台运行时提供并返回真实file_id。产物通过控制台会话产物区或Files API获取，不再配置已下线的download_file。

MCP是生成前置条件：会话必须实际可调用三个课程工具。工具未挂载或首次参考调用因服务故障失败时，应停止生成与文件交付，提示修复服务；不能让模型用bash、记忆或write绕过检查交付替代程序。

1. 模型调用build_python_file(mode="assemble")，保留返回的完整source和sha256。
2. 用write原样写入文件，再用read回读实际文件文本。
3. 调用build_python_file(mode="verify_written", source=回读文本, expected_sha256=assemble原始sha256)。
4. 返回verified后，用mark_artifacts登记实际.py文件，保存平台返回的file_id。
5. 控制台用户从会话产物区下载；API客户端依据file_id调用Files API取回文件。没有平台提供的下载URL时，不把file_id或沙箱路径编造成链接。

摘要模式不依赖跨函数计算实例的本地文件状态。它只证明收到的文本与调用方给定摘要一致，不证明摘要来自可信原始产物、沙箱文件确实被读取或最终下载字节一致；平台联调必须另核对真实下载。

保留artifact_id的旧校验方式依赖同一文件系统，在百炼跨实例调用中不宜作为默认链路。/tmp不是跨实例持久存储。

MCP包仍采用PyPI发布和uvx托管。Managed Agent如何连接该托管服务，应以实际联调确认的接入配置为准；本文不把旧FlowAgent界面入口当作Managed Agent的操作步骤。

官方依据：Managed Agents内置工具、Managed Agent产物取回示例。

本地HTTP模式

MCP_TRANSPORT=streamable-http HOST=127.0.0.1 PORT=8000 uv run carla-traffic-mcp

MCP端点为http://127.0.0.1:8000/mcp。可在真实服务地址后拼接工具返回的download_path下载；该路由与百炼原生文件工具链路不同，stdio部署不会直接暴露HTTP下载端点。

验证范围与兼容

检查器可以拦截可确定的错误API、枚举、命名参数、蓝图ID和不可修改属性，但不推断所有动态类型，不完整验证物理效果或路线行为。完整课堂验收还应覆盖真实模型、百炼文件工具和Windows CARLA。

本地开发与测试方法见LOCAL_TESTING.md。0.1.x模板入口保留为carla-traffic-mcp-legacy；新版默认入口只暴露上述三个工具。

许可证

MIT。随包保留CARLA上游API资料的许可说明。