tanweiping1012-source/travel-planner
travel-planner-mvp
VerifiedCreate evidence-backed, read-only travel plans using Amap, a community 12306 rail MCP, and approved browser research. Use for 行程规划、路线安排、景点取舍、高铁或机票比较、酒店住宿比价、预算分析、旅行可行性检查,以及中国境内多城市旅行规划(境外目的地降级为浏览器辅助规划)。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.5 KB |
| agents/openai.yaml | config | 344 B |
| examples/final_plan.json | config | 2.6 KB |
| examples/itinerary.json | config | 1020 B |
| examples/rail_query.json | config | 2.9 KB |
| examples/social_research.json | config | 1.3 KB |
| examples/trip_request.json | config | 1.1 KB |
| references/browser-use.md | markdown | 14.8 KB |
| references/client-compatibility.md | markdown | 5.4 KB |
| references/data-contracts.md | markdown | 26.6 KB |
| references/intake-template.md | markdown | 4.9 KB |
| references/rail-mcp.md | markdown | 4.3 KB |
| references/script-tools.md | markdown | 3.5 KB |
| references/workflow.md | markdown | 13.3 KB |
| scripts/audit_release.shexecutable | script | 3.4 KB |
| scripts/prepare_release.shexecutable | script | 1.8 KB |
| scripts/setup_amap_key.shexecutable | script | 828 B |
| scripts/setup_rail_mcp.shexecutable | script | 3.8 KB |
| scripts/travel_planner.pyexecutable | script | 11.8 KB |
| scripts/validate_skill.pyexecutable | script | 5.5 KB |
references/client-compatibility.md
View on GitHub# Client Compatibility
## Portability Layers
The repository contains four layers with different portability:
| Layer | Portability | Requirement |
|---|---|---|
| Data models, intake, research compiler, feasibility and plan validation | Fully portable | Python 3.9+ and shell/file access |
| Amap POI and route connector | Fully portable | Network access and `AMAP_API_KEY` or macOS Keychain |
| Community 12306 rail connector | MCP portable | Any client that supports local stdio MCP |
| OTA and Xiaohongshu research | Adapter dependent | Interactive browser automation with manual login handoff |
The Skill degrades safely. Without browser automation, users can provide
normalized `social_research.json` and `flight_offers.json`, or run map/rail-only
planning.
## Skill Installation Paths
The repository itself is the Skill directory. Clone it once, then copy or
symlink it to the client's discovery location.
### TRAE
```text
<workspace>/.trae/skills/travel-planner-mvp/
```
Status: full workflow tested with TRAE Browser Use, shell tools, Amap, and local
12306 MCP.
### Claude Code
Project scope:
```text
<workspace>/.claude/skills/travel-planner-mvp/
```
Personal scope:
```text
~/.claude/skills/travel-planner-mvp/
```
Status: full workflow live-tested with the Claude Browser tool, shell tools,
Amap, and local 12306 MCP — real 12306 queries, real Ctrip flight and hotel
pages, and real Xiaohongshu research including carousel-image reading, across
several complete planning runs. This is the client the coverage gate, the
login-handoff pattern, and the lodging login-gating rule were all discovered
on; see [`CONTRIBUTING.md`](../CONTRIBUTING.md) for what each run found.
### OpenAI Codex
Preferred installation: ask `$skill-installer` to install the GitHub repository
root as `travel-planner-mvp`. Use the absolute path returned by the installer for
all setup commands. Manual discovery paths are:
Repository scope:
```text
<workspace>/.agents/skills/travel-planner-mvp/
```
User scope:
```text
~/.agents/skills/travel-planner-mvp/
```
Status: Skill structure, `agents/openai.yaml`, and scripts are compatible.
Configure the local 12306 MCP and a browser automation tool separately. The
repository does not currently include an OpenAI plugin manifest.
### Cursor and Other Agents
Use the client's documented Agent Skills directory when it supports the open
`SKILL.md` structure. Otherwise:
1. Load `SKILL.md` as a project rule or reusable prompt.
2. Make `references/` readable to the Agent.
3. Allow execution of `scripts/travel_planner.py`.
4. Configure the local stdio 12306 MCP.
5. Provide a browser adapter satisfying `browser-use.md`.
Status: capability-compatible, but automatic Skill discovery and tool names
depend on the client and version.
## MCP Configuration
Run `bash <SKILL_ROOT>/scripts/setup_rail_mcp.sh`. The script installs the
runtime outside the Skill directory and prints a standard stdio MCP
configuration:
```json
{
"mcpServers": {
"12306": {
"command": "uv",
"args": [
"--directory",
"/absolute/user-data-path/mcp-server-12306",
"run",
"mcp-server-12306"
]
}
}
}
```
Import the server using the client's MCP settings. If the client uses a
different configuration schema, preserve the same command and argument list.
For Codex, run:
```bash
bash <SKILL_ROOT>/scripts/setup_rail_mcp.sh --register-codex
codex mcp list
```
Then restart Codex. Alternatively, add the printed command and arguments as a
local STDIO server under `Settings -> MCP servers`.
## Browser Adapter Mapping
Map these logical operations to the client:
| Logical operation | Typical implementation |
|---|---|
| `list_tabs`, `activate_tab`, `close_tab` | Browser or Playwright tab/page tools |
| `observe_page` | DOM snapshot, accessibility tree, or visible page text |
| `navigate`, `click`, `type`, `select`, `scroll`, `wait` | Browser interaction tools |
| `extract_visible_data` | DOM evaluation or structured extraction |
| `request_user_handoff` | Client confirmation/user interaction mechanism |
Do not map `request_user_handoff` to automated credential entry.
## Capability Modes
### Full
Requirements:
- Skill discovery
- Shell/Python execution
- Local stdio MCP
- Interactive browser automation
- User login/CAPTCHA handoff
Provides map, rail, flight, lodging, and Xiaohongshu-assisted planning.
Lodging additionally requires the login handoff every time — unlike flights,
Ctrip shows a signed-out visitor no room price at all.
### Browserless
Requirements:
- Skill or instruction loading
- Shell/Python execution
- Optional local stdio MCP
Provides deterministic planning, Amap, and rail. Flight, lodging, and social
research must be user-provided or marked unavailable.
### Script Only
Run:
```bash
python3 <SKILL_ROOT>/scripts/travel_planner.py --help
```
Provides intake validation, Amap queries, research compilation, feasibility
evaluation, and plan validation without an Agent client.
## Known Non-Portable Parts
- `setup_amap_key.sh` uses macOS Keychain.
- Linux and Windows should supply `AMAP_API_KEY` from their own secret manager.
- The rail runtime uses a per-user data directory and survives Skill upgrades.
- Browser login persistence is client-specific.
- Native app prices are not available through generic browser automation.
- Tool names differ across browser implementations; use the logical contract,
not TRAE-specific names.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |