CARLA交通场景MCP服务

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

0.2.5修复跨道路终点漏采，增加选址转路线、平滑变道、真实包围盒净距与整车通过判定；收紧传感器附着参数，服务失联时跳过重复远程清理等待。单角色方向与车道条件绑定同一连接。默认观察模式使用主窗口，不额外创建RGB相机。保留trace_route采样时的原始Waypoint身份，并据此匹配当前路口通行段的真实停止线，处理重叠道路和略在几何入口内侧的停止点。保留已有CARLA接口检查、天气辅助和精简交付协议：MCP返回短组装清单，百炼沙箱用同版本包确定性组装和校验，避免模型反复抄写公共骨架。通用运行辅助、多方向连接检索和完整精度道路定位继续保留，使用与部署版本一致的学生提示词。提示词核验服务版本和runtime_helpers，避免服务与提示词不配套。

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

0.2.6 通用等待与观察

新增三个运行辅助方法，MCP仍只有三个工具；新辅助方法随单文件产物运行于学生CARLA端。源码、安装包和协议验证不等于Windows实机验收，真实课堂链路仍需独立确认。

• ctx.spawn_waiting_vehicle(blueprint, route, ...)：使用原生路线的真实身份，按优先距离寻找等待点。距离为偏好，不是硬下限；严格距离可传distance_tolerance_m。候选预算按同身份非路口区间分配，目标距离支持采样点间插值，仍核验实际道路；以实际车辆包围盒和可配置余量采样检查同一非路口Driving车道。找不到合法点或候选被占用时明确失败；拒绝的车辆立即回收，异常情况下仍交给运行骨架清理。普通道路可以传reference_s，不限定地图、路口、方向或车型。
• ctx.observe_overview(actors=..., routes=..., locations=..., ...)：首个step之后，按本次对象包围盒和观察范围计算固定正俯视，沿路线额外覆盖最大车身包围半径，包含转向及末端车身。显式窗口尺寸、水平FOV、边距、高度上限和可辨识像素阈值；过大范围或过小对象明确失败，不静默裁切。默认投影参数是1280×720、水平90度估计，须与实际主窗口一致；不证明遮挡或渲染效果。跟随视角继续使用已有接口。
• ctx.inspect_actors(actors, ...)：记录任意对象的存活、坐标和真实速度，可绘ASCII角色标签。等待辅助方法创建的车辆自动以出生位置为基线检查漂移；其他对象仅在显式给定预期位置时检查等待状态。初始落地瞬态需与持续异常区分，观测结果不等于需求验收。

等待道路采样使用最大0.5米网格，当前约束要求车身及余量在同一原生车道身份内；这是保守的几何检查，不是连续碰撞证明。上游路线不足时应调整布局或选址，不自动换路口、不绕过检查。候选尝试、采样数量均有明确上限。

测试覆盖实采Town03_Opt两路口间7.49米道路边界、任意道路方向/偏移/不同车长、候选占用/回收失败、横竖窗口和多个观察对象。该短路段是回归数据，生产算法不包含其地图/道路ID。实际课堂验收还需Windows、CARLA 0.9.12和生成后的完整场景。

环境与内置资料

• 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，在分支或道路末端前停止延伸并返回实际长度，路口内部路径仍须完整。学生指定精确距离时保留严格模式。

trace_route同时返回waypoint_provenance，逐点保留原始road_id、section_id、lane_id、道路s和路口身份，与points严格一一对齐。需要选灯时直接使用这份原始路线，保留points、distances、waypoint_provenance及junction_start/junction_end的对应关系；不要单独切片、重排或重采样其中一项，也不要用make_route(route['points'])重建后丢掉身份。改变路线时重新调用trace_route。模型不应通过Map.get_waypoint按几何坐标反推道路身份，因为重叠道路上的投影可能落在另一条道路。

使用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通信等待，不会强行中断模型回调内的无限循环。

0.2.5生成检查与运行辅助

• 已知CARLA调用验证可确认的构造/方法签名、必需/重复/过多参数、确定字面量类型与非有限数值；保守识别简单别名、绑定方法和明确的CARLA返回类型。
• 已知CARLA调用的未知*args/**kwargs、动态getattr、无可核验构造签名的直接构造，返回needs_fix要求显式改写。普通未知Python对象和动态标量不声称全部推断；这不是Python安全沙箱。
• ctx公开辅助方法必须直接ctx.method(...)调用；宽泛Exception、裸except、API类型/属性错误不能被静默吞掉，应记录原始上下文后重新raise，或捕获明确的预期运行异常进行有限处理。
• ctx.set_weather(...)支持0.9.12的13个全名字段，校验类型、有限值及官方给定范围。None保留原值，公共骨架恢复原天气。
• ctx.traffic_lights_for_route(route)使用trace_route保留的原始Waypoint身份，先核对真实停止路点的道路、section、车道和道路s区间，再核对几何、方向与停止位置歧义，返回traffic_lights、stop_s、stop_location和evidence。范围从入口前指定距离到本次junction_end，允许属于当前通行段且略在几何入口内侧的真实停止线，排除after段和下一个路口；不能自行要求停止线必须在entry_s之前。stop_s使用route['distances']的累计距离坐标，evidence.road_s才是道路s。模型直接调用此助手，不手写Map坐标反推或用入口/灯杆位置猜停止线；无匹配返回空，歧义和RPC错误明确失败。
• DURATION_SECONDS可声明为大于0且不超过600的数字字面量；清单、默认运行时长和运行命令保持一致，显式--duration仍可覆盖。缺省兼容30秒。没有修改学生的一键运行器。

静态检查和文件摘要不代表每个生成场景已在CARLA运行。具体路线、障碍物几何、车辆响应及画面仍须本机验收；版本验收区分工具单测、正式包安装与实机接口证据。

从源码启动

uv run carla-traffic-mcp

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

uvx --from carla-traffic-mcp==0.2.5 carla-traffic-mcp

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

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

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

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

百炼Managed Agent文件交付

0.2.5首选prepare，与旧assemble、verify_written兼容。新版提示词必须与新版MCP配套，不能只改一边。公开工具仍为三个，不增加学生本机依赖。

1. 模型通过write保存业务代码到/mnt/session/scene_logic.py，再把相同业务代码提交build_python_file(mode="prepare", source=..., scenario_name=..., target_map=...)。
2. MCP静态检查并使用公共组装函数计算最终产物，返回小型JSON清单，包含schema_version、package_version、场景名称、目标地图、业务源码摘要/长度和完整产物摘要/长度。不会返回完整源码，也不依赖FC临时目录。
3. 将原始清单保存为/mnt/session/build_plan.json；百炼沙箱用同版本PyPI包的carla_mcp.delivery读取业务源码并自动拼装公共骨架。仅安装主包即可，生成命令没有MCP第三方依赖。
4. 命令从实际文件字节计算摘要；源码、版本或完整产物与原清单不一致就失败，拒绝交付。成功输出短JSON，直接mark_artifacts登记完整.py，不再回读完整源码、不再向MCP全文校验。
5. 学生从产物区下载单个scenario.py。内部业务文件和清单不交给学生拼接；Files API下载仍需核对真实文件摘要。静态通过与文件一致不证明CARLA场景效果通过。

部署版本正式发布后，在百炼文件环境中首次使用时执行（后续同会话复用）：

python3 -m pip install --disable-pip-version-check --no-deps --only-binary=:all: --target /mnt/session/.carla-builder/0.2.5 --index-url https://pypi.org/simple --timeout 20 --retries 1 carla-traffic-mcp==0.2.5
mkdir -p /mnt/session/outputs
PYTHONPATH=/mnt/session/.carla-builder/0.2.5 python3 -m carla_mcp.delivery --source /mnt/session/scene_logic.py --manifest /mnt/session/build_plan.json --output /mnt/session/outputs/scenario.py

已有输出默认不覆盖；有明确替换需要时添加--overwrite，通过所有摘要检查后才原子替换。业务源码仅规范化为source.strip() + "\n"，内部字符和换行不会被自动改写。安装/连接错误最多重试一次，禁止按SHA暴力枚举字节来猜测原稿。

仅百炼沙箱的组装命令需要Python>=3.10；学生本机仍为课程Python3.8.10。MCP与沙箱不共享文件系统，不能把FC产物路径当成沙箱文件或下载地址。默认不增加OSS或下载服务。

MCP是生成前置条件；未取得真实prepare成功清单不能绕过工具直接登记文件。旧assemble若仍使用，应在沙箱本地核对实际字节与原始SHA，避免无意义的全文回传。/artifacts/{id}仅HTTP部署模式暴露，stdio不能直接用于下载。

官方依据：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资料的许可说明。

0.2.7：公共返回结构

部署状态以发布验收记录为准。三个MCP工具及运行辅助函数签名保持不变；运行骨架和几何算法未改。geometry_result_contract中obstacle_clearance、actor_passed_route_point和observe_overview现在明确使用type/fields/example/note结构，runtime_helpers提供对应返回类型和合同路径。旧版前两个项目是字段名数组，不能再把它误解成结果按位置排列。

公共静态检查增加返回值检查：直接ctx调用、顺序块中单次赋值及可确定的简单别名；检查已知字典数字下标及logging/百分号数值格式误用已知列表或字典。变量重新赋值、可变别名、参数逃逸、嵌套作用域、复杂控制流和跨函数传播等不作全面推断；不是Python完整类型检查器，不声称所有动态错误都能发现。正常列表、数字键字典、列表记录取字段及%s输出继续允许。

源码、MCP远程prepare和工作区deliver_file共用检查规则。新版本包不能混用旧版本清单；正式启用前须另行发布并同步MCP与工作区版本。此修改不证明场景物理行为或Windows实机通过。