Skip to content

tanweiping1012-source/travel-planner

travel-planner-mvp

Verified

Create evidence-backed, read-only travel plans using Amap, a community 12306 rail MCP, and approved browser research. Use for 行程规划、路线安排、景点取舍、高铁或机票比较、酒店住宿比价、预算分析、旅行可行性检查,以及中国境内多城市旅行规划(境外目的地降级为浏览器辅助规划)。

FileKindSize
SKILL.mdskill md12.5 KB
agents/openai.yamlconfig344 B
examples/final_plan.jsonconfig2.6 KB
examples/itinerary.jsonconfig1020 B
examples/rail_query.jsonconfig2.9 KB
examples/social_research.jsonconfig1.3 KB
examples/trip_request.jsonconfig1.1 KB
references/browser-use.mdmarkdown14.8 KB
references/client-compatibility.mdmarkdown5.4 KB
references/data-contracts.mdmarkdown26.6 KB
references/intake-template.mdmarkdown4.9 KB
references/rail-mcp.mdmarkdown4.3 KB
references/script-tools.mdmarkdown3.5 KB
references/workflow.mdmarkdown13.3 KB
scripts/audit_release.shexecutablescript3.4 KB
scripts/prepare_release.shexecutablescript1.8 KB
scripts/setup_amap_key.shexecutablescript828 B
scripts/setup_rail_mcp.shexecutablescript3.8 KB
scripts/travel_planner.pyexecutablescript11.8 KB
scripts/validate_skill.pyexecutablescript5.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.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall