dsh-roam-planner

dsh-roam-planner

Trip planning inside DeepSeek Harness: talk a plan into existence, watch it land on a map, and adopt it when it looks right.

The agent edits a draft. A candidate is frozen for review, and only an explicit Adopt commits it — so a hallucinated revision can never overwrite a plan you already accepted.

Requirements

• DeepSeek Harness ^0.2.1-rc.2 (engines.dsh)
• No extra services: no Docker, no database, no API key required

Install

plugin_manager install_bundle <this package or directory>

Then restart DSH: the host half loads its tools and /roam/api routes at startup. After the restart the sidebar shows a Roam Planner icon, and the agent gains the roam_* tools.

First run

1. Click the sidebar icon — an empty panel says to ask the agent for a plan.

2. In any conversation:

   Plan two relaxed days in Suzhou for me and my parents

3. The agent calls roam_get_snapshot, roam_prepare_draft (place names only — the host geocodes them) and roam_fill_routes. The panel polls every few seconds and follows along.

4. roam_save_candidate freezes the plan; a green Adopt plan button appears.

5. Adopt it. Editing afterwards reopens a draft, and the panel shows what changed against the adopted version.

Optional: Amap key

Place lookup and routing work without a key (OpenStreetMap + OSRM), but Chinese addresses resolve far better through Amap.

Settings → Roam Planner → Amap Web-service key (not a JS API key). The key is written to the host credential store under ROAM_PLANNER_AMAP_KEY, is never sent back to the page, and takes effect on the next lookup — no restart.

Configuration

Everything below lives in the plugin row's config in cordis.patch.yml:

Key	Default	Meaning
basemapId	osm	Basemap selected on first use
basemaps	null	Replacement provider catalogue (array of {id, label, url, attribution, maxZoom, crs}); null uses the built-ins
geocoder	nominatim	nominatim, amap, or off
amapKey	null	Deployment-level key; a key saved in Settings wins
defaultCity	null	City appended to place names, e.g. 苏州
dataDir	null	Directory for the JSON fallback store

External MCP sidecars (optional)

Railway tickets and Xiaohongshu notes are not built in. The plugin speaks MCP itself — stdio and streamable http — so any sidecar can be attached through config, and servers start on the first call rather than at activation.

The agent reaches them through roam_mcp_servers, roam_mcp_tools and roam_mcp_call.

Railway: use the bundled proxy

server/railway-mcp.js is our own MCP server in front of the third-party 12306 sidecar. It owns the railway business API, so the caller gets a time window, a station filter and a row cap instead of an entire day of trains:

Parameter	Meaning
from_station, to_station, date	The query itself (date = YYYY-MM-DD)
time_from, time_to	Departure window, HH:MM
station	Keep trains serving this station (a city has many)
limit	Maximum trains returned, default 10, max 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'

A raw streamable http sidecar is configured with transport: http and url. Add command (plus optional args/env) and the bridge starts the process on first use, waits for the port and then speaks HTTP — nothing has to be launched by hand.

Sidecar	Source	Notes
12306 tickets	drfccv/mcp-server-12306	The project states non-commercial use only
Xiaohongshu notes	xpzouying/xiaohongshu-mcp	Needs a one-time login; serves HTTP on :18060

Tools

Tool	Effect
roam_get_snapshot	Read the session trip (creates an empty draft if none)
roam_prepare_draft	Apply a title/days change; stops need only a name
roam_save_candidate	Freeze the draft for review
roam_adopt	Commit the candidate
roam_fill_routes	Fill missing leg geometry and durations (Amap or OSRM)
roam_forecast	Daily weather at each day's first stop (read-only)
roam_search_places	Keyword search for real places (needs an Amap key)
roam_mcp_servers / roam_mcp_tools / roam_mcp_call	Reach an attached MCP sidecar

Data

• Trips live in the DSH storage domain ($DSH_HOME/storages/roam_planner.json), falling back to <dataDir>/.roam/store.json when the domain is unavailable.
• The Amap key lives in the credential store, never in the trip data.
• The page remembers the chosen basemap locally; that is a viewing preference, not trip data.

Troubleshooting

Symptom	Cause / fix
Panel says the host routes are unavailable	The host half failed to activate — restart DSH
Map is blank but the day list renders	Basemap tiles could not load (network or provider policy)
Routes are straight dashed lines	No route source answered; fill them with roam_fill_routes
Weather chips missing	The forecast has no data for those dates yet

License

MIT — see LICENSE. This is an independent implementation; see PROVENANCE.md for the boundary against the upstream project it was inspired by.