行程规划台 AntonyLang/dsh-roam-planner

dsh-roam-planner

在 DeepSeek Harness 里做行程规划：把计划聊出来，看它落到地图上，觉得合适就采纳。

智能体编辑的是草稿。候选方案会冻结下来供你审阅，只有明确点采纳才会提交，所以幻觉出来的修改永远覆盖不了你已经接受的计划。

环境要求

- DeepSeek Harness ^0.2.1-rc.2（engines.dsh）
- 不需要额外服务：不用 Docker，不用数据库，也不需要 API key

安装

plugin_manager install_bundle <this package or directory>

然后重启 DSH：宿主端在启动时加载工具和 /roam/api 路由。重启后侧边栏会出现 Roam Planner 图标，智能体也多出 roam_* 工具。

首次运行

1. 点侧边栏图标——空面板会提示你让智能体出一个计划。
2. 在任意会话里说：

Plan two relaxed days in Suzhou for me and my parents

3. 智能体依次调用 roam_get_snapshot、roam_prepare_draft（只传地点名称，地理编码由宿主完成）和 roam_fill_routes。面板每隔几秒轮询一次，跟着进度走。
4. roam_save_candidate 冻结计划，出现绿色采纳计划按钮。
5. 采纳。之后再编辑会重新打开草稿，面板会对照已采纳版本显示改动。

可选：高德 key

不填 key 也能查地点和算路线（OpenStreetMap + OSRM），但中文地址走高德解析效果好得多。

设置 → Roam Planner → 高德 Web 服务 key（不是 JS API key）。key 写入宿主凭据存储，键名 ROAM_PLANNER_AMAP_KEY，不会回传到页面，下次查询即生效，无需重启。

配置

以下各项都在 cordis.patch.yml 里插件行的 config 中：

| 键 | 默认值 | 含义 |
| basemapId | osm | 首次使用时选中的底图 |
| basemaps | null | 替换用的服务商目录（{id, label, url, attribution, maxZoom, crs} 数组）；null 表示用内置的 |
| geocoder | nominatim | nominatim、amap 或 off |
| amapKey | null | 部署级 key；设置里保存的 key 优先 |
| defaultCity | null | 追加到地点名称后的城市，例如 苏州 |
| dataDir | null | JSON 兜底存储的目录 |

外部 MCP sidecar（可选）

火车票和小红书笔记不是内置的。插件自己会说 MCP——支持 stdio 和 streamable http——所以任何 sidecar 都能通过配置挂上，服务器在第一次调用时才启动，而不是激活时。

智能体通过 roam_mcp_servers、roam_mcp_tools 和 roam_mcp_call 访问它们。

火车票：用自带的代理

server/railway-mcp.js 是我们自己的 MCP 服务器，挡在第三方 12306 sidecar 前面。它接管了铁路业务 API，所以调用方拿到的是时间窗口、车站过滤和行数上限，而不是一整天的车次：

| 参数 | 含义 |
| from_station、to_station、date | 查询条件本身（date 格式为 YYYY-MM-DD） |
| time_from、time_to | 出发时间范围，格式 HH:MM |
| station | 只保留经过该站的车次（一个城市有很多站） |
| limit | 最多返回多少趟车，默认 10，上限 50 |

- id: roam-planner
config:
mcpServers:
- name: railway
command: node
args: ['<plugin>/server/railway-mcp.js']
env:
RAILWAY_PYTHON: 'C:\...\python.exe' # has mcp-server-12306 installed
RAILWAY_PYTHONPATH: 'C:\...\site-packages'

裸的 streamable http sidecar 用 transport: http 加 url 配置。再加上 command（可选 args/env），桥接层会在首次使用时启动进程，等端口就绪后走 HTTP 通信——不需要手动启动任何东西。

| Sidecar | 来源 | 说明 |
| 12306 车票 | drfccv/mcp-server-12306 | 项目声明仅限非商业用途 |
| 小红书笔记 | xpzouying/xiaohongshu-mcp | 需要一次性登录；在 :18060 上提供 HTTP 服务 |

工具

| 工具 | 作用 |
| roam_get_snapshot | 读取会话中的行程（没有就创建一个空草稿） |
| roam_prepare_draft | 修改标题/天数；停靠点只需给名字 |
| roam_save_candidate | 冻结草稿，等待审阅 |
| roam_adopt | 提交候选版本 |
| roam_fill_routes | 补齐缺失的路段几何与时长（高德或 OSRM） |
| roam_forecast | 每天首个停靠点的当日天气（只读） |
| roam_search_places | 按关键词搜索真实地点（需要高德 key） |
| roam_mcp_servers / roam_mcp_tools / roam_mcp_call | 访问挂载的 MCP sidecar |

数据

- 行程存放在 DSH 存储域（$DSH_HOME/storages/roam_planner.json），域不可用时回退到 <dataDir>/.roam/store.json。
- 高德 key 存放在凭据库，绝不写进行程数据。
- 页面在本地记住选中的底图；这属于查看偏好，不是行程数据。

故障排查

| 现象 | 原因 / 处理 |
| 面板提示宿主路由不可用 | 宿主侧未激活——重启 DSH |
| 地图空白但日期列表正常 | 底图瓦片加载失败（网络或服务商策略） |
| 路线是笔直的虚线 | 没有路线源响应；用 roam_fill_routes 补齐 |
| 天气标签缺失 | 预报还没有这些日期的数据 |

许可证

MIT——见 LICENSE。这是独立实现；与它所借鉴的上游项目之间的边界见 PROVENANCE.md。