前言¶
在 DSH 里让智能体帮你规划旅行，常见问题是：计划写在对话里，地点和路线难以对照；模型改一版就可能覆盖你已经认可的安排。若再要查火车票或小红书攻略，往往还要另开工具或手写脚本挂 MCP。
dsh-roam-planner（维护者 AntonyLang，分类为客户端插件）把行程规划做成 DSH 内的工作区：侧边栏地图面板、会话级行程存储，以及一组 roam_* 工具；可选通过配置挂载外部 MCP sidecar（如 12306、小红书）。下面介绍它的定位、安装方式与典型用法。事实依据见 GitHub 仓库 README 与 SkillHub 目录页。
这是什么¶
插件全名 dsh-roam-planner（npm 包名同称，当前版本 0.2.3，MIT 许可证）。一句话定位：在 DeepSeek Harness 中通过对话生成旅行计划，在地图面板上查看，并在你确认后再正式采纳。
核心设计是 草稿 → 候选 → 采纳：智能体只改草稿；roam_save_candidate 冻结为待审候选；只有显式 Adopt（roam_adopt）才会提交，避免幻觉式修改覆盖已接受的行程。
运行要求（engines.dsh）：DeepSeek Harness ^0.2.1-rc.2。无需 Docker、数据库或额外 API Key 即可使用基础能力（OpenStreetMap + OSRM 地理编码与路线）。
核心功能¶
客户端与宿主¶
安装并重启 DSH 后，宿主侧加载 roam_* 工具与 /roam/api 路由；侧边栏出现 Roam Planner 图标，智能体获得行程相关工具。面板会周期性拉取状态，跟随智能体编辑进度。
行程工具（节选）¶
| 工具 | 作用 |
|---|---|
roam_get_snapshot |
读取当前会话行程（无则创建空草稿） |
roam_prepare_draft |
改标题/天数与停靠点（停靠点仅需名称，由宿主地理编码） |
roam_save_candidate |
冻结草稿供审阅 |
roam_adopt |
提交候选为正式行程 |
roam_fill_routes |
补全缺失路段几何与时长（Amap 或 OSRM） |
roam_forecast |
各日首站天气（只读） |
roam_search_places |
关键词搜真实地点（需 Amap Key） |
roam_mcp_servers / roam_mcp_tools / roam_mcp_call |
访问已配置的 MCP sidecar |
地图与地理¶
默认底图与地理编码可在 cordis.patch.yml 插件行的 config 中配置（见下文）。无 Key 时可用 Nominatim + OSRM；国内地址建议在 Settings → Roam Planner → Amap Web-service key（非 JS API Key）填写高德 Web 服务 Key，写入宿主凭证库 ROAM_PLANNER_AMAP_KEY，下次查询生效，无需重启。
数据存放¶
行程默认落在 DSH 存储域 $DSH_HOME/storages/roam_planner.json；存储域不可用时回退到 <dataDir>/.roam/store.json。Amap Key 不进行程 JSON；底图选择为页面本地偏好。
可选 MCP sidecar¶
火车票、小红书笔记未内置。插件支持通过配置以 stdio 或 streamable HTTP 挂载 MCP，首次调用时再启动进程。仓库提供 server/railway-mcp.js 作为 12306 第三方 sidecar 的代理（参数含 from_station、to_station、date、time_from/time_to、station、limit 等）。12306 相关项目声明仅限非商业使用；小红书 MCP 需一次性登录并在 :18060 提供 HTTP。具体 YAML 示例见 README「External MCP sidecars」。
安装与启用¶
在 DSH 环境中执行（将 <this package or directory> 换成本地包路径或目录）：
plugin_manager install_bundle <this package or directory>
然后 重启 DSH：宿主加载工具与路由后，侧边栏可见 Roam Planner，智能体可用 roam_* 工具。
可选配置项（插件行 config，摘自 README）：
| Key | 默认 | 含义 |
|---|---|---|
basemapId |
osm |
首次使用的底图 |
basemaps |
null |
自定义底图目录；null 用内置 |
geocoder |
nominatim |
nominatim、amap 或 off |
amapKey |
null |
部署级 Key；Settings 中保存的优先 |
defaultCity |
null |
拼接到地名后，如 苏州 |
dataDir |
null |
JSON 回退存储目录 |
典型用法¶
经过上面的安装与重启，可按 README「First run」复现：
- 点击侧边栏 Roam Planner；空面板会提示向智能体要一份计划。
- 在任意会话中发送类似需求，例如：
Plan two relaxed days in Suzhou for me and my parents
- 智能体通常会调用
roam_get_snapshot、roam_prepare_draft（仅地名）和roam_fill_routes；面板数秒内跟进显示。 - 调用
roam_save_candidate后会出现绿色 Adopt plan；确认后采纳。 - 采纳后再编辑会重新打开草稿，面板可对照已采纳版本的差异。
适用场景与注意¶
适合谁：已在用 DSH ^0.2.1-rc.2、希望用自然语言起草多日行程、在地图上看站点与路线、并用手动采纳锁住终稿的开发者或自用用户；需要火车票或小红书时可自行配置 MCP，接受相应 sidecar 的安装与许可约束。
权限与安全：插件以当前 DSH 进程权限运行，会访问网络做地理编码、路线与可选 MCP；安装前请阅读仓库源码、LICENSE 与 PROVENANCE.md。社区目录 SkillHub 为独立站点，与 DeepSeek / 幻方无官方从属关系。
排障（摘自 README）：面板提示宿主路由不可用 → 宿主未激活，重启 DSH；有日程但地图空白 → 底图瓦片加载失败；路线为直线虚线 → 调用 roam_fill_routes；天气芯片缺失 → 对应日期尚无预报数据。
结尾¶
dsh-roam-planner 把「对话写行程、地图对照、显式采纳」收进 DSH 客户端工作区，并保留 MCP 扩展火车票与攻略检索的空间。进一步了解可访问目录页 https://www.skillhub.cn/plugins/AntonyLang/dsh-roam-planner 与 GitHub https://github.com/AntonyLang/dsh-roam-planner 。
