{"id":"62a76d8b-4144-42eb-915f-40422624bb4d","entityType":"agent","slug":"clawhub-super21-bat-trek-agent-control","name":"trek-agent-control","canonicalUrl":"https://www.xpersona.co/agent/clawhub-super21-bat-trek-agent-control","canonicalPath":"/agent/clawhub-super21-bat-trek-agent-control","generatedAt":"2026-10-11T10:51:11.585Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T07:56:19.215Z","emptyReason":null},"description":"配套 Trek 微信旅行小程序的自动化 Skill，主要面向 WorkBuddy，也兼容 Codex、Claude、OpenClaw、Hermes 等 Agent。通过认证的远程 MCP 研究国内外目的地、读取或修改行程，并把日程、地点、预订、住宿、费用、清单、待办、附件和协作提案安全同步回小程序。Use when WorkBuddy or another agent needs to plan travel, inspect Trek data, synchronize structured itinerary fields, upload tickets, or run safe diagnostics with a user-provided Trek Agent Key. Skill: trek-agent-control Owner: super21-bat Summary: 配套 Trek 微信旅行小程序的自动化 Skill，主要面向 WorkBuddy，也兼容 Codex、Claude、OpenClaw、Hermes 等 Agent。通过认证的远程 MCP 研究国内外目的地、读取或修改行程，并把日程、地点、预订、住宿、费用、清单、待办、附件和协作提案安全同步回小程序。Use when WorkBuddy or another agent needs to plan travel, inspect Trek data, synchronize structured itinerary fields, upload tickets, or run safe diagnostics with a user-provided Trek Agent Key. Tags: latest:1.1.3 Ve","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s175az8cpcd2sbfx08gyskcaen83hyj2:trek-agent-control","sourceUrl":"https://clawhub.ai/super21-bat/trek-agent-control","homepage":"https://clawhub.ai/super21-bat/skills/trek-agent-control","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/super21-bat/trek-agent-control","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/super21-bat/skills/trek-agent-control","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"配套 Trek 微信旅行小程序的自动化 Skill，主要面向 WorkBuddy，也兼容 Codex、Claude、OpenClaw、Hermes 等 Agent。通过认证的远程 MCP 研究国内外目的地、读取或修改行程，并把日程、地点、预订、住宿、费用、清单、待办、附件和协作提案安全同步回小程序。Use when W"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T07:56:19.215Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T07:56:19.215Z","emptyReason":null},"stars":null,"forks":null,"downloads":1119,"packageName":null,"latestVersion":"1.1.3","tractionLabel":"1.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T07:56:19.207Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T07:56:19.215Z","lastCrawledAt":"2026-10-11T07:56:19.207Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T07:56:19.207Z","lastVerifiedAt":null,"highlights":[{"version":"1.1.3","createdAt":"2026-09-23T08:26:20.760Z","changelog":"创建新地点或安排已有地点时可一条动作写入开始和结束时间，batch无需二次取ID","fileCount":6,"zipByteSize":19946},{"version":"1.1.2","createdAt":"2026-09-23T07:53:03.297Z","changelog":"同步自动天气与当天信息契约，修复提醒换行保存和逐行显示说明","fileCount":6,"zipByteSize":19480},{"version":"1.1.1","createdAt":"2026-09-20T07:27:10.992Z","changelog":"备注默认折叠并可手动编辑删除；天气独立主动开启，清空提醒即隐藏；补充缓存及实际预报范围契约","fileCount":6,"zipByteSize":19124},{"version":"1.1.0","createdAt":"2026-09-20T02:39:25.648Z","changelog":"每日备注可见性、可填写的今日提醒、天气回退及读回核验；更新 CLI 0.3.0 调用指引","fileCount":6,"zipByteSize":18061},{"version":"1.0.5","createdAt":"2026-08-24T07:23:27.753Z","changelog":"收藏与待决定复用地点，保留介绍、图片、备注、网站和电话等投票上下文","fileCount":6,"zipByteSize":16613},{"version":"1.0.4","createdAt":"2026-08-20T08:26:35.975Z","changelog":"清单支持当前行程自定义分类复用，Agent 写入同名分类自动归组","fileCount":6,"zipByteSize":15864},{"version":"1.0.3","createdAt":"2026-08-20T07:12:36.036Z","changelog":"同步清单四类语义、数量字段与写后回读规则","fileCount":7,"zipByteSize":103058},{"version":"1.0.2","createdAt":"2026-07-29T11:15:34.420Z","changelog":"增加 Trek 微信小程序介绍、二维码入口与 Agent 自动化说明","fileCount":6,"zipByteSize":13155}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s175az8cpcd2sbfx08gyskcaen83hyj2:trek-agent-control","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-super21-bat-trek-agent-control/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-super21-bat-trek-agent-control/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-super21-bat-trek-agent-control/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-super21-bat-trek-agent-control/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-super21-bat-trek-agent-control/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-super21-bat-trek-agent-control/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T10:51:11.581Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-super21-bat-trek-agent-control/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-super21-bat-trek-agent-control/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-super21-bat-trek-agent-control/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-super21-bat-trek-agent-control/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T07:56:19.215Z","emptyReason":null},"readme":"Skill: trek-agent-control\n\nOwner: super21-bat\n\nSummary: 配套 Trek 微信旅行小程序的自动化 Skill，主要面向 WorkBuddy，也兼容 Codex、Claude、OpenClaw、Hermes 等 Agent。通过认证的远程 MCP 研究国内外目的地、读取或修改行程，并把日程、地点、预订、住宿、费用、清单、待办、附件和协作提案安全同步回小程序。Use when WorkBuddy or another agent needs to plan travel, inspect Trek data, synchronize structured itinerary fields, upload tickets, or run safe diagnostics with a user-provided Trek Agent Key.\n\nTags: latest:1.1.3\n\nVersion history:\n\nv1.1.3 | 2026-09-23T08:26:20.760Z | user\n\n创建新地点或安排已有地点时可一条动作写入开始和结束时间，batch无需二次取ID\n\nv1.1.2 | 2026-09-23T07:53:03.297Z | user\n\n同步自动天气与当天信息契约，修复提醒换行保存和逐行显示说明\n\nv1.1.1 | 2026-09-20T07:27:10.992Z | user\n\n备注默认折叠并可手动编辑删除；天气独立主动开启，清空提醒即隐藏；补充缓存及实际预报范围契约\n\nv1.1.0 | 2026-09-20T02:39:25.648Z | user\n\n每日备注可见性、可填写的今日提醒、天气回退及读回核验；更新 CLI 0.3.0 调用指引\n\nv1.0.5 | 2026-08-24T07:23:27.753Z | user\n\n收藏与待决定复用地点，保留介绍、图片、备注、网站和电话等投票上下文\n\nv1.0.4 | 2026-08-20T08:26:35.975Z | user\n\n清单支持当前行程自定义分类复用，Agent 写入同名分类自动归组\n\nv1.0.3 | 2026-08-20T07:12:36.036Z | user\n\n同步清单四类语义、数量字段与写后回读规则\n\nv1.0.2 | 2026-07-29T11:15:34.420Z | user\n\n增加 Trek 微信小程序介绍、二维码入口与 Agent 自动化说明\n\nv1.0.1 | 2026-07-29T10:14:41.748Z | user\n\n补充中文技能介绍和触发说明；Skill 包仅保留运行所需说明与字段参考\n\nv0.1.0 | 2026-07-29T09:50:59.960Z | auto\n\nInitial public release introducing Trek Agent Control.\n\n- Provides a CLI and agent integration to securely connect agents to Trek China via MCP endpoint using a user-provided key.\n- Supports trip research, itinerary synchronization, reservations, accommodations, budgets, packing, todos, notes, and proposals with the Trek WeChat mini program.\n- Includes rigorous authentication, failure handling, and safety workflow instructions to protect user data.\n- Offers comprehensive CLI tools for configuration, synchronization, planning audits, batch actions, and safe diagnostics.\n- Extensive documentation and references for setup and safe/robust operation across different agent environments.\n\nv1.0.0 | 2026-07-29T08:56:28.063Z | user\n\n同步最新 MCP 字段归属、写后回读规则与 Git/ClawHub 维护说明\n\nArchive index:\n\nArchive v1.1.3: 6 files, 19946 bytes\n\nFiles: references/configuration.md (4307b), references/field-guide.md (14499b), references/workflows.md (6315b), skill-card.md (2725b), SKILL.md (13008b), _meta.json (137b)\n\nFile v1.1.3:SKILL.md\n\n---\nname: trek-agent-control\ndescription: 配套 Trek 微信旅行小程序的自动化 Skill，主要面向 WorkBuddy，也兼容 Codex、Claude、OpenClaw、Hermes 等 Agent。通过认证的远程 MCP 研究国内外目的地、读取或修改行程，并把日程、地点、预订、住宿、费用、清单、待办、附件和协作提案安全同步回小程序。Use when WorkBuddy or another agent needs to plan travel, inspect Trek data, synchronize structured itinerary fields, upload tickets, or run safe diagnostics with a user-provided Trek Agent Key.\n---\n\n# Trek Agent Control\n\nControl the user's real Trek data through MCP. Treat web research and Trek synchronization as separate phases: research first, then show a concrete change preview, then write and read back.\n\n## Product workspace\n\nTrek 微信旅行小程序是用户查看、编辑、导航、分享和协作的行程工作区；本\nSkill 是它的 Agent 自动化层。用户先在小程序创建行程和独立 Agent Key，\nAgent 再研究资料并把结构化结果同步回同一行程。不要创建与小程序脱离的第二份\n行程数据，也不要把聊天回答误报成已同步。\n\n![微信扫码打开 Trek 旅行小程序](https://raw.githubusercontent.com/super21-bat/trek-agent-control/main/assets/trek-miniapp-code.png)\n\n当前二维码为测试阶段入口，是否可直接进入以微信侧体验权限为准。\n\n## Connect\n\n1. Never paste the `trek_` key into files, prompts, logs, screenshots, commits, or shell history intended for sharing.\n2. Prefer the agent's native Streamable HTTP MCP support. Configure:\n - URL: `https://api.superd.fun/mcp`\n - Header: `Authorization: Bearer `\n3. Use the Trek CLI to install/sync this Skill, verify the connection, and diagnose failures:\n\n```bash\nnpm install -g https://github.com/super21-bat/trek-agent-control/archive/refs/heads/main.tar.gz\ntrek config init --api-key 'trek_...' --url 'https://api.superd.fun/mcp'\ntrek skill sync --global\ntrek doctor\n```\n\nThe mini program presents this to ordinary users as two steps: copy once, then send the copied bundle to WorkBuddy. WorkBuddy should complete installation, configuration, Skill sync, and `doctor` without asking the user to run commands manually. Treat the whole bundle as a secret. If native remote MCP is unavailable or unreliable, execute all operations through `trek`; it calls the same MCP endpoint. Read [references/configuration.md](references/configuration.md) for runtime details.\n\n## Fast paths for common user requests\n\nDo not load the large-planning workflow for these small writes. Use the exact\nrecipe, then stop:\n\n- “加到待定/候选地点”：resolve the trip with `list_trips`, then run\n `trek add-pending [--place-id <saved-place-id>]` or call\n native MCP `add_pending_place`. If the place already exists in 收藏, pass its\n `placeId`; the server links/reuses that place instead of creating a duplicate.\n For a newly researched candidate, include a short stable `description` and a\n representative `imageUrl` when available; put the trip-specific recommendation\n in `reason`. A name plus address alone is not enough context for group voting.\n `apply_trip_change` with `action: \"add_pending\"` remains a compatible fallback.\n Never use `create_place` for 待选/候选/待决定.\n- “设置行程封面”：run `trek set-cover <trip-id>\n <absolute-image>` or call native MCP `apply_trip_change` with `action:\n \"set_cover\"`. The server owns upload, binding and readback as one semantic\n operation; do not compose primitive upload/update calls when this tool exists.\n\nFor either fast path, if readback fails, report “未同步” and the exact failed\nstage. Never continue into unrelated planning or claim the mini program will\neventually refresh.\n\n## Mandatory workflow\n\n1. Run `doctor` or native `tools/list`. Stop on authentication, network, or missing-tool failure.\n2. Read existing state with `list_trips` and `get_trip_summary`. Never assume a trip ID. Use top-level `places[]` for every trip place, including unassigned places; use `packing.bags[]` for all bags, including empty bags.\n3. Research current facts with primary/official sources first. Separate confirmed facts, recommendations, and unresolved items.\n4. Build a dated plan and an `expectedAssignmentsByDate` checklist containing every POI/activity that must appear in the mini program. Use exact local dates and times. Do not invent reservations, confirmation numbers, phone numbers, opening hours, prices, or addresses.\n5. Show the user a compact change preview before destructive, bulk, financial, membership, proposal-decision, or rescheduling writes.\n6. Write in small batches. Reuse existing entities and detect duplicates by normalized name/date before creating.\n7. Every real location visit must be a Place plus Assignment. Use `create_and_assign_place` for a new POI and `assign_place_to_day` for an existing one. Pass known `place_time` and `end_time` directly in either creation call; both save the visit time atomically and return the assignment ID. Use `update_assignment_time` for later edits, not as a mandatory second step after creation. Location-free actions (wake up, bring tickets, meet a friend) can be timed day notes: visible in the notes part of the collapsed day-information section in mini program 0.3.18+, but not map stops. Never fabricate a POI just to make a note visible; older clients must upgrade.\n8. Model accommodation separately. `create_place_accommodation`/`create_accommodation` create a lodging date range but no visible day assignment. If a hotel or check-in is in the daily plan, also assign its place to that day.\n9. Populate only meaningful fields, but use the complete model when relevant: trip dates/description, days, places and coordinates, assignment start/end/duration/transport/notes, reservations, accommodations, costs, packing, todos, collaboration notes, proposals and members.\n10. Read back with `get_trip_summary` plus the relevant `list_*` tool. Compare `expectedAssignmentsByDate` to actual `days[].assignments` by date and normalized place name/ID, not only counts. A planned day must not have zero assignments; explicitly document intentional rest/location-free travel days.\n11. Do not report synchronization complete while any expected assignment is missing or only mentioned in a day note. Repair the gap or disclose it to the user.\n12. Report what changed, what remains uncertain, and what the user must confirm.\n\nRead [references/workflows.md](references/workflows.md) for detailed planning and synchronization recipes. Read [references/field-guide.md](references/field-guide.md) before a large or unfamiliar write.\n\n## CLI\n\n```bash\ntrek doctor\ntrek update --check\ntrek tools place\ntrek call list_trips '{\"include_archived\":false}'\ntrek summary 3\ntrek audit-plan 3 /absolute/path/expected-assignments.json\ntrek add-pending 3 '西湖游船' --reason '同行者表态后再排日程'\ntrek upload-file 3 /absolute/path/ticket.pdf --assignment 42 --description '景区电子票'\ntrek set-cover 3 /absolute/path/cover.jpg --description '行程封面'\ntrek rename-file 3 19 '金门大桥门票.pdf'\ntrek batch /absolute/path/actions.json\ntrek batch /absolute/path/actions.json --apply\ntrek smoke --allow-write-smoke\n```\n\n`doctor` reports local configuration, endpoint, credential presence, Skill integrity, authentication, live tool count, and trip readback. Failures include a category, hint, and next command; retain that structured output when diagnosing. `update --check` compares CLI versions; `update` upgrades the CLI and resynchronizes the Skill. `audit-plan` compares an expected JSON date-to-place mapping with live `days[].assignments` and exits non-zero on missing items. `add-pending` creates or reuses a candidate and verifies the open proposal by ID. `upload-file` reads a local attachment without printing its base64 and supports files up to 10 MB. `set-cover` uploads, binds, and verifies a visible trip cover as one command. `rename-file` changes only the display name and keeps the extension. `batch` is dry-run unless `--apply` is present. Applied actions always expose `ok`, `resourceType`, `resource`, `warnings`, and the original `result`; execution stops on the first failed action. It refuses high-risk tool names unless `--confirm-high-risk` is also present. `smoke` creates temporary data, exercises the proposal lifecycle, deletes it, and closes the MCP session.\n\n## Safety invariants\n\n- Treat the key as a password. Ask the user to revoke it immediately if exposed.\n- Never delete or overwrite real data during diagnostics. Use the bundled temporary smoke only.\n- Do not mark bookings confirmed without order evidence. Use `pending` or a todo for unresolved bookings.\n- Do not create fake coordinates. Use `search_place` with `market: \"china\"` plus `region` in Mainland China, or `market: \"global\"` plus an ISO `countryCode` for overseas trips. Preserve the returned provider IDs and coordinates.\n- For minors, medical needs, border crossings, flights, and tight transfers, add safety buffers and explicit adult-confirmation tasks.\n- Respect 429 responses. Do not disable server limits or fire requests in parallel; the bundled client retries with bounded backoff.\n- Static `trek_` keys currently grant broad user access. Create one per Agent, revoke unused keys, and prefer scoped OAuth when the target agent supports it.\n- Close every MCP session, including failed runs.\n\n## Failure handling\n\n- `401`: key missing, revoked, malformed, or sent without `Bearer`.\n- `403`: user lacks trip permission or scope; do not retry as another user.\n- `404`: wrong trip/entity ID or inaccessible resource; refresh state.\n- `429`: wait and retry sequentially; reduce batch size.\n- `isError: true`: treat as failed even if HTTP succeeded. Preserve the error text and stop dependent writes.\n- Unknown fields/tools: call `tools/list`; never guess a schema from an older document.\n\nWhen native MCP and the bundled client disagree, trust a fresh `tools/list` response and production readback.\n\n## Daily notes and reminders (mini program 0.3.22+)\n\n- Keep day titles short (about 25 characters). Use `update_day.daily_brief` for an optional user-authored clothing/tickets/packing reminder, up to 500 characters. Keep it concise, use actual newline characters to separate ideas, and avoid Markdown because the mini program renders plain text; empty or null hides the reminder. Mini program 0.3.24+ renders each line separately. `trek set-day-brief <trip-id> <day-id> @brief.txt` preserves line breaks from the file; a literal `\\n` in a CLI argument is also normalized. Weather appears automatically below the day title when location and data are available: MET Norway is preferred for the first nine days, extended forecasts cover days 10–15, and dates beyond day 15 show a clearly labeled historical temperature estimate. It refreshes at most once per day. Do not set or ask the user to set `weather_enabled`.\n- `create_day_note` stores a timed action in the notes part of the collapsed day-information section, without adding a map stop. These notes were invisible in 0.3.16 and older.\n- `trek day-view <trip-id> <day-id>` / `preview_day_view` returns the content contract and minimum client version, not a screenshot or proof the user installed that version. Compare notes using `trek audit-notes <trip-id> expected-notes.json`; `audit-plan` checks assignments only.\n- Use the current authorized tool schema. With semantic profile, discover these advanced tools and reconnect using full profile if needed. For exact fields and boundaries read [references/field-guide.md](references/field-guide.md).\n\n### Optional day extras (0.3.18)\n\n- Day notes are grouped under “当天备注 · count”, collapsed by default. Expand to read; tap a note to edit/delete in place. Notes are not route/map stops. Empty notes and reminders have no content panel.\n- Weather is derived from the day's date and first located assignment, not a user-managed field. Missing coordinates or unavailable forecast/reference data produce no weather summary. Reminder and notes are the only editable sections in the day-information disclosure. Dates beyond day 15 use a historical temperature estimate, never a real forecast.\n- Weather is cached on the client for the day and shared by rounded location on the server. MET Norway attribution and update time are shown. Authored text is not automatically refreshed.\n- Use `preview_day_view.notesPresentation` to explain collapsed state; `renderedNotes` means available after expansion, not all rows visible on first opening. Preview does not fetch weather or prove a screenshot.\n- Keep each note as one action/supporting item (text <=500); `text` is the editable label/body, so no separate name field is needed. Assignment notes from assign/update tools refer to the same visit-specific field. Packing and budget remain in their own tabs; do not duplicate them as itinerary stops.\n\nFile v1.1.3:_meta.json\n\n{\n \"ownerId\": \"kn70axt20cegjzmp4nnsrs1fmx82khb0\",\n \"slug\": \"trek-agent-control\",\n \"version\": \"1.1.3\",\n \"publishedAt\": 1790151980760\n}\n\nFile v1.1.3:references/configuration.md\n\n# Runtime configuration\n\n## WorkBuddy first\n\nThe mini program gives the user only two steps: tap “创建并复制”, then send the copied bundle to WorkBuddy. WorkBuddy must complete the commands, Skill sync, and `doctor` itself. Do not ask a non-technical user to choose between MCP and CLI.\n\nUse native Streamable HTTP MCP when WorkBuddy exposes it. Otherwise use the CLI fallback from the same copied bundle.\n\n## Native Streamable HTTP MCP\n\nUse the runtime's secret manager for `TREK_MCP_TOKEN`. The common configuration shape is:\n\n```json\n{\n \"mcpServers\": {\n \"trek\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://api.superd.fun/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${TREK_MCP_TOKEN}\"\n }\n }\n }\n}\n```\n\nRuntimes may spell the type `http`, `streamable_http`, or `streamable-http`. Do not copy the key into a shared JSON file if that runtime cannot expand environment variables.\n\n## Universal shell fallback\n\nRequirements: Node.js 18 or newer and outbound HTTPS.\n\n```bash\nnpm install -g https://github.com/super21-bat/trek-agent-control/archive/refs/heads/main.tar.gz\ntrek config init --api-key 'trek_...' --url 'https://api.superd.fun/mcp'\ntrek skill sync --global\ntrek doctor\n```\n\nThe mini program provides the endpoint, commands, and one-time key in one copied Agent access bundle. Do not split or repost that bundle. `trek config init` stores the key in `~/.trek/config.json` with mode `0600` on POSIX systems.\n\nThe public bootstrap source is the repository's stable branch tarball. Do not use\nthe `github:owner/repo` npm shorthand for global installation: some npm versions\nlink it to a temporary clone and leave a broken `trek` command after cleanup.\nAfter `@trek-cn/cli` is published to npm, the shorter\n`npm install -g @trek-cn/cli@latest` command may replace the GitHub install.\n\nOptional environment overrides:\n\n- `TREK_CONFIG`: custom config path.\n- `TREK_MCP_TOKEN`: override the stored key.\n- `TREK_MCP_URL`: defaults to `https://api.superd.fun/mcp`.\n- `TREK_MCP_TIMEOUT_MS`: per-request timeout, default `20000`.\n- `TREK_MCP_RETRIES`: retry count for 429/502/503/504 and network errors, default `7`.\n\n## Other compatible agents\n\nCodex, Claude, OpenClaw, Hermes and other terminal-capable agents follow the same connection sequence:\n\n1. Install the CLI and run `trek skill sync --global`.\n2. Run `trek config init` with the user's one-time key.\n3. Add the native MCP block when supported.\n4. Otherwise allow the agent to execute `trek ...`.\n5. Run `doctor`; require `ok: true`, a protocol version, a positive tool count, and successful `list_trips` before giving write access.\n\n`trek skill sync --global` delegates common Agent locations to the installed\nSkills runner. Trek also installs real copies into detected WorkBuddy\n`~/.workbuddy/skills/trek-agent-control` and Hermes\n`~/.hermes/skills/trek-agent-control` directories. Start a new WorkBuddy task or\nrestart the Hermes gateway after syncing. A cross-directory symlink is not\nenough for Hermes: it resolves symlinks before enforcing its trusted Skill\ndirectory.\n\nHermes native remote MCP support is optional. Hermes installations that include\nthe MCP extra may configure the Streamable HTTP endpoint directly; installations\nwithout it can use the Trek CLI fallback with the same capabilities. Trek must\nnot install or modify Hermes' Python environment automatically. Follow the\nHermes version's own installation instructions when native MCP is desired, and\ndo not hard-code another user's virtual-environment path.\n\n## Diagnostics\n\nRun `trek doctor` first. Its failure category determines the next check:\n\n- `configuration`: inspect `trek config get`, then re-run `config init`.\n- `network`: verify HTTPS/DNS/proxy access to the endpoint.\n- `authentication`: create a fresh Agent Key, initialize it, and revoke the old key.\n- `permission`: refresh `list_trips`; do not retry against another user's trip.\n- `rate_limit`: wait and retry sequentially.\n- `capability`: run `trek skill sync --global`, then inspect `trek tools`.\n\n## Key rotation\n\nCreate one key per external agent so access can be revoked independently. After rotating:\n\n1. Replace the secret in that runtime only.\n2. Run `doctor` with the new key.\n3. Revoke the old key in the mini program.\n4. Confirm the old key returns 401.\n\nFile v1.1.3:references/field-guide.md\n\n# Dynamic tool and field guide\n\nAlways discover the live schemas with `tools/list`. The server evolves and the live schema is authoritative.\n\n## Core read path\n\n- `list_trips`: identify accessible trips.\n- `get_trip_summary`: trip, top-level deduplicated places, days, assignments, reservations, accommodations, budget, packing items and bags, todos, notes and members.\n- Relevant `list_*`: obtain full records before editing or deleting.\n\n## Common write groups\n\n- Trip: `create_trip`, `update_trip`, `delete_trip`.\n- Schedule: day, place and assignment tools.\n- Search: `search_place` with `query`, explicit `market` (`china` or `global`), and either a Mainland `region` or overseas ISO `countryCode`.\n- Decisions: `*_trip_proposal` and collaboration polls.\n- Logistics: reservation and accommodation tools.\n- Money: budget item, member, payer and settlement tools.\n- Preparation: packing and todo tools.\n- Collaboration: note, poll and chat tools when enabled.\n\n## Idempotency keys for agent reasoning\n\nThe MCP tools do not promise a universal idempotency token. Before creating, compare:\n\n- trip: normalized title + start/end dates\n- place: normalized name + address + coordinates\n- assignment: day ID + place ID + start time\n- reservation: type + title + linked day/place\n- accommodation: place + start/end day\n- cost: category + name + amount\n- packing/todo: normalized name\n- note: normalized title\n\nReuse/update a match instead of creating a duplicate.\n\n## Saved and pending place visibility\n\n- 收藏 and 待决定 share the same place facts: name, address, description, notes,\n image, website and phone. Moving between the two states must preserve them.\n- For a researched candidate, `description` answers “what is this place”; `reason`\n answers “why consider it for this trip”. Do not put both meanings into one field.\n- Include a representative image only when its source is usable and stable. Never\n fabricate a photo URL. A candidate without verified media may omit `imageUrl`,\n but should still have a concise description whenever facts are available.\n- Verify rich candidate fields with `list_trip_proposals`; verify 收藏 fields with\n `list_places`. Do not report synchronization if the description was dropped.\n\n## Itinerary detail and ticket fields\n\nThe mini program opens an itinerary detail sheet when the user taps a day assignment. To make agent-written plans useful there:\n\n- Route fields by ownership instead of putting everything into one note:\n\n| User meaning | MCP field/tool | Mini program visibility |\n| --- | --- | --- |\n| Instructions for this specific visit | `update_assignment_time.notes` | `本次安排` in the assignment detail |\n| Start/end time for this visit | `create_and_assign_place.place_time` / `.end_time` for a new place; `assign_place_to_day.place_time` / `.end_time` for a saved place; `update_assignment_time` for later edits | Time shown on that day's assignment, not a reusable place field |\n| Stable POI introduction | `create_place.description` / `update_place.description` | `地点信息 → 地点介绍`, shown automatically when non-empty |\n| Reusable POI caveat | `create_place.notes` / `update_place.notes` | `地点信息 → 地点备注`, shown automatically when non-empty |\n| Address and contact | place `address`, `phone`, `website` | Primary address facts plus direct phone/website actions |\n| Trip cover | `upload_trip_file`, then `update_trip.cover_image` with the returned `file.url` | Trip list, Home hero and trip detail cover |\n| Place image | `upload_trip_file` with `place_id`, then `create_place.image_url` / `update_place.image_url` with the returned `file.url` | Place detail image and Home fallback image |\n| Booked time and voucher facts | reservation `reservation_time`, `reservation_end_time`, `confirmation_number`, `notes`, `url` | `预订信息`, linked through `assignment_id` |\n| Expense | budget `name`, `total_price`, `category`, `currency`, `expense_date`, `payers`, `member_ids`, `note` | Top-level `费用` tab |\n| Ticket image or PDF | `upload_trip_file` / `link_trip_file` with `assignment_id` or `reservation_id` | `票据与附件` in the assignment detail |\n\n- Put arrival instructions, meeting points, age restrictions, what to bring, and other readable guidance in the assignment or reservation `notes`.\n- Use `update_assignment_time.notes` for guidance specific to this visit. Use `update_place.notes` only for reusable place notes, and `update_place.description` for the public place introduction.\n- Keep the UI visibility contract intact: assignment `notes` appear as \"本次安排\"; place `address` appears in the primary facts; place `phone` and `website` appear as direct actions. Since mini program 0.2.18, place `description` and `notes` are shown directly in \"地点信息\" when at least one exists; the section is hidden when both are empty.\n- Treat every written field as a readback obligation. After `create_place`, `create_and_assign_place`, `update_place`, or `update_assignment_time`, call `list_places` or `get_trip_summary` and verify the exact value. Do not write opaque data to fields that the user cannot reach in the mini program.\n- Create a reservation for a ticket, restaurant, tour, study activity, or event and link it with `assignment_id`.\n- Use `confirmation_number` only for a real order/booking code.\n- Use `reservation_time` and `reservation_end_time` for the booked time window.\n- Use `url` for the official voucher, ticket, or booking page.\n- Uploaded images and PDFs remain trip files. Link them to the reservation or assignment instead of placing base64 data or long image URLs in notes.\n- For a visible trip cover or place image, upload the image as a trip file, persist the returned authenticated relative `file.url` in `cover_image` or `image_url`, then read back both the file link and entity field. Uploading bytes alone does not make an image visible.\n- Use `upload_trip_file` for an attachment up to 10 MB, or the bundled `upload-file` command so raw base64 never appears in terminal output. Use `list_trip_files` for readback, `link_trip_file` to add another relationship, and `trash_trip_file` to remove it from the active trip.\n- Keep the reservation `pending` until the user supplies booking evidence; then update it to `confirmed`.\n- The mini program's \"预订\" tab is the single editable reservation inventory. Legacy `day_assignments.reservation_*` fields are read-only compatibility data; do not write new booking data there.\n- Use fixed budget category keys such as `accommodation`, `food`, `transport`, `activities`, `shopping`, or `other`. Record `expense_date`, currency and payers when known.\n\n## Packing checklist fields\n\n- Prefer the mini program's three low-effort built-in packing locations: `随身必带`, `衣物`, and `日用健康`. “自定义” is an action, not a category name: when the user needs a special grouping, write the actual reusable category name.\n- Do not ask the user for a category when the item name makes it obvious. Infer it: identity documents, phone accessories, wallet and keys -> `随身必带`; clothing and footwear -> `衣物`; toiletries, sun protection, medicine, umbrella and tissues -> `日用健康`. If there is no stronger match and the user did not request a special grouping, omit `category` and let the service use the safe `随身必带` default.\n- For a real trip-specific need, pass a concise custom category such as `露营装备`, `摄影器材`, or `儿童用品`. Once one item uses that category, the mini program offers it directly for later items in the same trip and groups all same-category items together. Reuse the exact existing category spelling from readback instead of creating near-duplicates.\n- Legacy English/Chinese categories and historical `其他` remain readable. Do not create a category named after a place such as “为酒店准备”; use a reusable packing concept instead.\n- Always send `quantity` when the user needs more than one item. Valid values are integers from 1 to 999.\n- After `create_packing_item` or `update_packing_item`, read back the item and verify `name`, `category`, and `quantity`; do not report a successful packing update from the write response alone.\n- Reuse or update an existing normalized name instead of creating a duplicate, unless the same item genuinely belongs to different people or bags.\n\n## Batch file format\n\n`scripts/trek-mcp.mjs batch` accepts a JSON array:\n\n```json\n[\n {\n \"label\": \"Inspect current trips\",\n \"tool\": \"list_trips\",\n \"arguments\": { \"include_archived\": false }\n },\n {\n \"label\": \"Search official hotel POI\",\n \"tool\": \"search_place\",\n \"arguments\": { \"query\": \"清远狮子湖喜来登度假酒店\", \"market\": \"china\", \"region\": \"清远\", \"countryCode\": \"CN\" }\n }\n]\n```\n\nWithout `--apply`, the client prints the planned calls and performs no tools. With `--apply`, calls run sequentially and stop on the first error. Every result has the same compatibility envelope: `ok`, `resourceType`, `resource`, `warnings`, and the original tool payload in `result`. Tool names containing delete/remove/decide/schedule/settle/restore/rotate require `--confirm-high-risk`.\n\nFor a new timed stop, put `place_time` and `end_time` in the `create_and_assign_place` action's `arguments` alongside `tripId`, `dayId`, and `name`. For an existing saved place, use `assign_place_to_day` with the same time fields. One action creates the timed visit; the batch format does not interpolate an `assignmentId` from an earlier action. Read back `days[].assignments` after applying the batch.\n\n## Readback checklist\n\nVerify:\n\n- exact trip dates and day count\n- actual assignments by date/place equal the pre-write `expectedAssignmentsByDate` checklist\n- every detailed-plan POI/activity is a visible assignment, not only day-note text\n- any planned day with zero assignments is treated as a failure; intentional rest/location-free travel days are explicitly marked\n- a hotel listed as a daily activity has both its accommodation range and a day assignment\n- fixed assignments retain start/end times\n- chronological order places untimed items last\n- coordinates and addresses belong to the intended city\n- reservations use honest status and no fabricated confirmation number\n- assignment-linked reservations expose confirmation numbers, notes, voucher URLs and files in the mini program detail sheet\n- accommodation day span and check-in/out\n- budget currency, amount, persons/days and notes\n- every expense and reservation created by the agent is editable and visible in the mini program's corresponding top-level tab\n- no duplicate packing/todo/note names\n- top-level `places[]` includes assigned and unassigned places\n- `packing.bags[]` includes empty bags as well as bags referenced by items\n- unresolved facts remain todos or explicit notes\n\n## Day view contract — mini program 0.3.22+\n\n| User meaning | MCP write | Mini program visibility |\n| --- | --- | --- |\n| Short daily title | `update_day.title`, max 200; recommend <=25 characters | Date tab (one line) and section heading (two lines); long text is shortened |\n| Daily clothing/tickets/things to bring | `update_day.daily_brief`, max 500; keep concise plain text, use actual newline characters between ideas; no Markdown; empty/null clears | Reminder and notes share one collapsed day-information group; mini program 0.3.24+ renders each reminder line separately; weather is separate in the day title |\n| Timed action with no map stop | `create_day_note` / `update_day_note`: text max 500, optional time | 当天备注 rows, including existing stored notes; long text expands in place |\n| Actual visit/route stop | `assign_place_to_day`, `update_assignment_time` | Ordered itinerary and route map |\n| Visit instructions | Both tools above write the same assignment `notes` | 本次安排 in the visit details |\n| Hotel date range | `create_accommodation` | Reservation data; an assignment is still needed for a route stop |\n| Packing / budget / unassigned reservation | Respective tools | Their own sections, not automatic day itinerary rows |\n\nDo not substitute a long title for daily_brief. Do not invent nearby POIs for location-free actions. Do not delete or duplicate existing notes to compensate for old clients. Notes require mini program 0.3.18+; check the user's installed version when visibility is disputed.\n\n`preview_day_view {tripId,dayId}` returns authored reminder, automatic weather display metadata, renderedNotes and ordered renderedAssignments. Weather is not fetched by this preview. It is a server-side content contract, not a screenshot; assignment details require places:read. `get_trip_summary.days[].notes` contains note entries while REST days use `notes_items`.\n\nWeather guidance: research current weather before authoring a brief, distinguish forecast from historical climate, and include source/date in text when useful. Do not invent a forecast outside the provider window. Clearing the brief hides only the authored reminder; it does not control automatic weather. Custom text stays exactly as authored until changed.\n\n### Optional day extras (0.3.18)\n\n- Reminders and notes share one “当天信息” group, collapsed by default. Expand to read; enter edit mode to add/edit/delete each in place. Notes are not route/map stops. Weather is not in this group.\n- Weather is automatic: weather for the selected date and first located assignment appears below the day title when data is available. MET Norway is preferred for the first nine days; extended forecasts cover days 10–15; dates beyond day 15 show historical temperature estimates labeled “历史预估”. Weather refresh is cached daily. Do not set `weather_enabled`.\n- Weather is cached for a day on the client and shared by rounded location on the server. The mini program shows a compact summary below the day title; source and update metadata stay in the provider/service contract. Authored text is not automatically refreshed.\n- Use `preview_day_view.notesPresentation` to explain collapsed state; `renderedNotes` means available after expansion, not all rows visible on first opening. Preview does not fetch weather or prove a screenshot.\n- Keep each note as one action/supporting item (text <=500); `text` is the editable label/body, so no separate name field is needed. Assignment notes from assign/update tools refer to the same visit-specific field. Packing and budget remain in their own tabs; do not duplicate them as itinerary stops.\n\nFile v1.1.3:references/workflows.md\n\n# Research and synchronization workflows\n\n## Research a new trip\n\n1. Collect hard constraints: travelers, ages, accessibility, origin, dates, fixed bookings, work/school windows, budget and transport.\n2. Verify time-sensitive claims online. Prefer official attraction, venue, carrier, hotel, government and map sources.\n3. Use `search_place` for each real destination. In Mainland China pass `market: \"china\"` and an administrative region such as `深圳` or `清远`; overseas pass `market: \"global\"` and a two-letter country code such as `JP` or `FR`.\n4. Design each day around geography, opening windows, heat/rain, meals, rest and transfer buffers. Extract every planned POI/activity into `expectedAssignmentsByDate`; do not leave locations only in narrative text.\n5. Mark every item as confirmed, recommended, optional or pending confirmation.\n6. Preview the plan before creating data.\n\n## Create or update a trip\n\n1. `list_trips` and normalize titles/dates to detect an existing trip.\n2. Create only when no match exists; otherwise use the current trip ID.\n3. `get_trip_summary` and map its day IDs to ISO dates.\n4. Create/reuse places, then assign every expected POI/activity to the correct day with start/end time, duration, transport mode and assignment notes. New place: `create_and_assign_place`; existing place: `assign_place_to_day`. Pass `place_time`/`end_time` in that same creation call when known; both fields belong to the daily assignment. Use `update_assignment_time` only for later edits. A CLI batch can therefore contain one create action per visit without referencing a previous action's assignment ID.\n5. Add reservations/accommodations only from evidence. Accommodation tools create a date range, not a daily assignment; if the hotel/check-in is part of the visible daily plan, also assign the hotel place to that day.\n6. Add costs as estimates unless receipts/orders establish actual values.\n7. Add packing items for traveler and destination needs.\n8. Add todos for unresolved bookings, deadlines, safety checks and missing documents. Use due dates and priority.\n9. Add collaboration notes for cross-cutting instructions that must remain visible.\n10. When adding a trip cover or place image, upload the image, write the returned authenticated `file.url` to `trip.cover_image` or `place.image_url`, and verify both values on readback. A successful file upload without the entity field is incomplete.\n11. Read back and compare each date's normalized assignment place names/IDs to `expectedAssignmentsByDate`. Any planned day with zero assignments, any expected place missing, or any POI present only in day-note text is a failed synchronization. Fix it before reporting completion. Intentional rest/location-free travel days must be marked explicitly.\n\nSave the full expected checklist as a JSON object when using the bundled audit command. An empty array explicitly marks a rest/location-free day:\n\n```json\n{\n \"2026-09-23\": [\"金门大桥\", \"Presidio\"],\n \"2026-09-24\": [],\n \"2026-09-25\": [\"Stanford University\", \"Apple Park Visitor Center\"]\n}\n```\n\nRun `node scripts/trek-mcp.mjs audit-plan <trip-id> /absolute/path/expected-assignments.json`. Exit code `2` means at least one date is missing, has missing assignments, or contains unexpected assignments; do not report completion.\n\n## Collaborative planning\n\nUse proposals before formal itinerary writes when a group has not decided:\n\n1. `create_trip_proposal`\n2. `react_trip_proposal`\n3. `decide_trip_proposal` only after the owner confirms\n4. `schedule_trip_proposal` only after choosing a day\n5. `list_trip_proposals` to verify final status\n\nUse polls for broad group choices and proposals for candidate places that may become scheduled items.\n\n### Add one pending place\n\nPrefer the semantic tool; do not assemble this from primitive writes:\n\n1. If the place is already in 收藏, obtain its ID from `list_places`.\n2. Call `add_pending_place({ tripId, placeId, title, ... })`; `placeId` is preferred\n for an existing saved place and prevents duplicate data.\n For a new candidate, pass `description`, `imageUrl`, `website`, `phone` and\n `placeNotes` when verified. Keep `reason` short and specific to this trip.\n3. Require `persisted: true`, `destination: \"pending\"`, and an `open` proposal\n in the returned readback.\n4. To remove it from active discussion but keep it saved, call\n `move_pending_place_to_saved({ tripId, proposalId })` after user confirmation.\n\nDo not use `create_place`: a saved place is not the mini program's “待决定” item.\nDo not report success without the semantic tool's persisted readback.\n\n## Change an existing trip safely\n\nCreate a diff with:\n\n- current value\n- proposed value\n- reason/source\n- affected reservations, costs, members and travel time\n\nGet confirmation before deleting, moving fixed bookings, changing financial data, or replacing confirmed reservations. Apply changes in dependency order and read back after each group.\n\n## Daily briefing\n\nRead the trip summary, today's day, reservations, todos and weather. Return:\n\n- next fixed event and departure deadline\n- route and buffer\n- weather/clothing\n- tickets/documents\n- meal plan\n- unresolved high-priority todo\n\nDo not write anything for a briefing unless the user explicitly asks to update the trip.\n\n## Evidence policy\n\n- A map result establishes name/address/coordinates, not quality or current opening hours.\n- A social post is a recommendation signal, not proof of current policy.\n- A reservation is confirmed only with user/order evidence.\n- If exact time, address, price, phone or booking status is unknown, preserve the uncertainty in a todo or note.\n\n## Verify notes and daily reminders\n\nAfter synchronization, use `trek day-view TRIP_ID DAY_ID` to read the 0.3.18+ display contract. `audit-plan` verifies assignment names only; it does not verify notes, reminders, client version or screenshots.\n\nFor timed notes, create an expected JSON file (no real user content in shared examples):\n\n```json\n{\"2026-10-01\":[{\"text\":\"带好演出门票和证件\",\"time\":\"18:00\"}]}\n```\n\nRun `trek audit-notes TRIP_ID expected-notes.json`. Missing, unexpected or duplicate text/time entries fail the audit (exit 2). Read back the exact daily brief through `day-view`; do not write again simply because an old client cannot show it.\n\nFile v1.1.3:skill-card.md\n\n## Description:\n\nTrek Agent Control lets compatible agents use authenticated MCP or the Trek CLI to research trips and safely synchronize structured itinerary data with the Trek WeChat mini program.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[super21-bat](https://clawhub.ai/user/super21-bat)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and compatible agent runtimes use this skill to research trips and synchronize itinerary data, reservations, accommodations, costs, packing lists, todos, files, and collaboration proposals with the Trek WeChat mini program. It supports authenticated MCP access and a CLI fallback for configuration, diagnostics, writes, and readback verification.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill uses a broad persistent Trek Agent Key for access to user travel data and writes.\n\nMitigation: Create one dedicated key per agent, store it in a runtime secret manager, avoid exposing it in files or logs, run diagnostics before writes, and revoke the key when access is no longer needed.\n\nRisk: The skill can install mutable remote CLI code and synchronize globally into agent skill directories.\n\nMitigation: Install only when the Trek service and GitHub-published CLI source are trusted, verify the connection with doctor, and review global sync behavior before enabling write operations.\n\nRisk: Write operations can affect bookings, costs, deletions, proposal decisions, or rescheduled itinerary data.\n\nMitigation: Preview high-impact changes, write in small batches, use readback verification, and require user confirmation for destructive, financial, membership, proposal-decision, or rescheduling actions.\n\n## Reference(s):\n\n- [Trek Agent Control Skill Page](https://clawhub.ai/super21-bat/skills/trek-agent-control)\n- [Runtime Configuration](references/configuration.md)\n- [Dynamic Tool and Field Guide](references/field-guide.md)\n- [Research and Synchronization Workflows](references/workflows.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with JSON and shell command examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May perform authenticated MCP calls or Trek CLI operations when configured with a user-provided Trek Agent Key.]\n\n## Skill Version(s):\n\n1.1.3 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.1.2: 6 files, 19480 bytes\n\nFiles: references/configuration.md (4307b), references/field-guide.md (13817b), references/workflows.md (6035b), skill-card.md (2539b), SKILL.md (12776b), _meta.json (137b)\n\nFile v1.1.2:SKILL.md\n\n---\nname: trek-agent-control\ndescription: 配套 Trek 微信旅行小程序的自动化 Skill，主要面向 WorkBuddy，也兼容 Codex、Claude、OpenClaw、Hermes 等 Agent。通过认证的远程 MCP 研究国内外目的地、读取或修改行程，并把日程、地点、预订、住宿、费用、清单、待办、附件和协作提案安全同步回小程序。Use when WorkBuddy or another agent needs to plan travel, inspect Trek data, synchronize structured itinerary fields, upload tickets, or run safe diagnostics with a user-provided Trek Agent Key.\n---\n\n# Trek Agent Control\n\nControl the user's real Trek data through MCP. Treat web research and Trek synchronization as separate phases: research first, then show a concrete change preview, then write and read back.\n\n## Product workspace\n\nTrek 微信旅行小程序是用户查看、编辑、导航、分享和协作的行程工作区；本\nSkill 是它的 Agent 自动化层。用户先在小程序创建行程和独立 Agent Key，\nAgent 再研究资料并把结构化结果同步回同一行程。不要创建与小程序脱离的第二份\n行程数据，也不要把聊天回答误报成已同步。\n\n![微信扫码打开 Trek 旅行小程序](https://raw.githubusercontent.com/super21-bat/trek-agent-control/main/assets/trek-miniapp-code.png)\n\n当前二维码为测试阶段入口，是否可直接进入以微信侧体验权限为准。\n\n## Connect\n\n1. Never paste the `trek_` key into files, prompts, logs, screenshots, commits, or shell history intended for sharing.\n2. Prefer the agent's native Streamable HTTP MCP support. Configure:\n - URL: `https://api.superd.fun/mcp`\n - Header: `Authorization: Bearer <user-key>`\n3. Use the Trek CLI to install/sync this Skill, verify the connection, and diagnose failures:\n\n```bash\nnpm install -g https://github.com/super21-bat/trek-agent-control/archive/refs/heads/main.tar.gz\ntrek config init --api-key 'trek_...' --url 'https://api.superd.fun/mcp'\ntrek skill sync --global\ntrek doctor\n```\n\nThe mini program presents this to ordinary users as two steps: copy once, then send the copied bundle to WorkBuddy. WorkBuddy should complete installation, configuration, Skill sync, and `doctor` without asking the user to run commands manually. Treat the whole bundle as a secret. If native remote MCP is unavailable or unreliable, execute all operations through `trek`; it calls the same MCP endpoint. Read [references/configuration.md](references/configuration.md) for runtime details.\n\n## Fast paths for common user requests\n\nDo not load the large-planning workflow for these small writes. Use the exact\nrecipe, then stop:\n\n- “加到待定/候选地点”：resolve the trip with `list_trips`, then run\n `trek add-pending <trip-id> <title> [--place-id <saved-place-id>]` or call\n native MCP `add_pending_place`. If the place already exists in 收藏, pass its\n `placeId`; the server links/reuses that place instead of creating a duplicate.\n For a newly researched candidate, include a short stable `description` and a\n representative `imageUrl` when available; put the trip-specific recommendation\n in `reason`. A name plus address alone is not enough context for group voting.\n `apply_trip_change` with `action: \"add_pending\"` remains a compatible fallback.\n Never use `create_place` for 待选/候选/待决定.\n- “设置行程封面”：run `trek set-cover <trip-id>\n <absolute-image>` or call native MCP `apply_trip_change` with `action:\n \"set_cover\"`. The server owns upload, binding and readback as one semantic\n operation; do not compose primitive upload/update calls when this tool exists.\n\nFor either fast path, if readback fails, report “未同步” and the exact failed\nstage. Never continue into unrelated planning or claim the mini program will\neventually refresh.\n\n## Mandatory workflow\n\n1. Run `doctor` or native `tools/list`. Stop on authentication, network, or missing-tool failure.\n2. Read existing state with `list_trips` and `get_trip_summary`. Never assume a trip ID. Use top-level `places[]` for every trip place, including unassigned places; use `packing.bags[]` for all bags, including empty bags.\n3. Research current facts with primary/official sources first. Separate confirmed facts, recommendations, and unresolved items.\n4. Build a dated plan and an `expectedAssignmentsByDate` checklist containing every POI/activity that must appear in the mini program. Use exact local dates and times. Do not invent reservations, confirmation numbers, phone numbers, opening hours, prices, or addresses.\n5. Show the user a compact change preview before destructive, bulk, financial, membership, proposal-decision, or rescheduling writes.\n6. Write in small batches. Reuse existing entities and detect duplicates by normalized name/date before creating.\n7. Every real location visit must be a Place plus Assignment. Use `create_and_assign_place` for a new POI and `assign_place_to_day` for an existing one. Location-free actions (wake up, bring tickets, meet a friend) can be timed day notes: visible in the notes part of the collapsed day-information section in mini program 0.3.18+, but not map stops. Never fabricate a POI just to make a note visible; older clients must upgrade.\n8. Model accommodation separately. `create_place_accommodation`/`create_accommodation` create a lodging date range but no visible day assignment. If a hotel or check-in is in the daily plan, also assign its place to that day.\n9. Populate only meaningful fields, but use the complete model when relevant: trip dates/description, days, places and coordinates, assignment start/end/duration/transport/notes, reservations, accommodations, costs, packing, todos, collaboration notes, proposals and members.\n10. Read back with `get_trip_summary` plus the relevant `list_*` tool. Compare `expectedAssignmentsByDate` to actual `days[].assignments` by date and normalized place name/ID, not only counts. A planned day must not have zero assignments; explicitly document intentional rest/location-free travel days.\n11. Do not report synchronization complete while any expected assignment is missing or only mentioned in a day note. Repair the gap or disclose it to the user.\n12. Report what changed, what remains uncertain, and what the user must confirm.\n\nRead [references/workflows.md](references/workflows.md) for detailed planning and synchronization recipes. Read [references/field-guide.md](references/field-guide.md) before a large or unfamiliar write.\n\n## CLI\n\n```bash\ntrek doctor\ntrek update --check\ntrek tools place\ntrek call list_trips '{\"include_archived\":false}'\ntrek summary 3\ntrek audit-plan 3 /absolute/path/expected-assignments.json\ntrek add-pending 3 '西湖游船' --reason '同行者表态后再排日程'\ntrek upload-file 3 /absolute/path/ticket.pdf --assignment 42 --description '景区电子票'\ntrek set-cover 3 /absolute/path/cover.jpg --description '行程封面'\ntrek rename-file 3 19 '金门大桥门票.pdf'\ntrek batch /absolute/path/actions.json\ntrek batch /absolute/path/actions.json --apply\ntrek smoke --allow-write-smoke\n```\n\n`doctor` reports local configuration, endpoint, credential presence, Skill integrity, authentication, live tool count, and trip readback. Failures include a category, hint, and next command; retain that structured output when diagnosing. `update --check` compares CLI versions; `update` upgrades the CLI and resynchronizes the Skill. `audit-plan` compares an expected JSON date-to-place mapping with live `days[].assignments` and exits non-zero on missing items. `add-pending` creates or reuses a candidate and verifies the open proposal by ID. `upload-file` reads a local attachment without printing its base64 and supports files up to 10 MB. `set-cover` uploads, binds, and verifies a visible trip cover as one command. `rename-file` changes only the display name and keeps the extension. `batch` is dry-run unless `--apply` is present. Applied actions always expose `ok`, `resourceType`, `resource`, `warnings`, and the original `result`; execution stops on the first failed action. It refuses high-risk tool names unless `--confirm-high-risk` is also present. `smoke` creates temporary data, exercises the proposal lifecycle, deletes it, and closes the MCP session.\n\n## Safety invariants\n\n- Treat the key as a password. Ask the user to revoke it immediately if exposed.\n- Never delete or overwrite real data during diagnostics. Use the bundled temporary smoke only.\n- Do not mark bookings confirmed without order evidence. Use `pending` or a todo for unresolved bookings.\n- Do not create fake coordinates. Use `search_place` with `market: \"china\"` plus `region` in Mainland China, or `market: \"global\"` plus an ISO `countryCode` for overseas trips. Preserve the returned provider IDs and coordinates.\n- For minors, medical needs, border crossings, flights, and tight transfers, add safety buffers and explicit adult-confirmation tasks.\n- Respect 429 responses. Do not disable server limits or fire requests in parallel; the bundled client retries with bounded backoff.\n- Static `trek_` keys currently grant broad user access. Create one per Agent, revoke unused keys, and prefer scoped OAuth when the target agent supports it.\n- Close every MCP session, including failed runs.\n\n## Failure handling\n\n- `401`: key missing, revoked, malformed, or sent without `Bearer`.\n- `403`: user lacks trip permission or scope; do not retry as another user.\n- `404`: wrong trip/entity ID or inaccessible resource; refresh state.\n- `429`: wait and retry sequentially; reduce batch size.\n- `isError: true`: treat as failed even if HTTP succeeded. Preserve the error text and stop dependent writes.\n- Unknown fields/tools: call `tools/list`; never guess a schema from an older document.\n\nWhen native MCP and the bundled client disagree, trust a fresh `tools/list` response and production readback.\n\n## Daily notes and reminders (mini program 0.3.22+)\n\n- Keep day titles short (about 25 characters). Use `update_day.daily_brief` for an optional user-authored clothing/tickets/packing reminder, up to 500 characters. Keep it concise, use actual newline characters to separate ideas, and avoid Markdown because the mini program renders plain text; empty or null hides the reminder. Mini program 0.3.24+ renders each line separately. `trek set-day-brief <trip-id> <day-id> @brief.txt` preserves line breaks from the file; a literal `\\n` in a CLI argument is also normalized. Weather appears automatically below the day title when location and data are available: MET Norway is preferred for the first nine days, extended forecasts cover days 10–15, and dates beyond day 15 show a clearly labeled historical temperature estimate. It refreshes at most once per day. Do not set or ask the user to set `weather_enabled`.\n- `create_day_note` stores a timed action in the notes part of the collapsed day-information section, without adding a map stop. These notes were invisible in 0.3.16 and older.\n- `trek day-view <trip-id> <day-id>` / `preview_day_view` returns the content contract and minimum client version, not a screenshot or proof the user installed that version. Compare notes using `trek audit-notes <trip-id> expected-notes.json`; `audit-plan` checks assignments only.\n- Use the current authorized tool schema. With semantic profile, discover these advanced tools and reconnect using full profile if needed. For exact fields and boundaries read [references/field-guide.md](references/field-guide.md).\n\n### Optional day extras (0.3.18)\n\n- Day notes are grouped under “当天备注 · count”, collapsed by default. Expand to read; tap a note to edit/delete in place. Notes are not route/map stops. Empty notes and reminders have no content panel.\n- Weather is derived from the day's date and first located assignment, not a user-managed field. Missing coordinates or unavailable forecast/reference data produce no weather summary. Reminder and notes are the only editable sections in the day-information disclosure. Dates beyond day 15 use a historical temperature estimate, never a real forecast.\n- Weather is cached on the client for the day and shared by rounded location on the server. MET Norway attribution and update time are shown. Authored text is not automatically refreshed.\n- Use `preview_day_view.notesPresentation` to explain collapsed state; `renderedNotes` means available after expansion, not all rows visible on first opening. Preview does not fetch weather or prove a screenshot.\n- Keep each note as one action/supporting item (text <=500); `text` is the editable label/body, so no separate name field is needed. Assignment notes from assign/update tools refer to the same visit-specific field. Packing and budget remain in their own tabs; do not duplicate them as itinerary stops.\n\nFile v1.1.2:_meta.json\n\n{\n \"ownerId\": \"kn70axt20cegjzmp4nnsrs1fmx82khb0\",\n \"slug\": \"trek-agent-control\",\n \"version\": \"1.1.2\",\n \"publishedAt\": 1790149983297\n}\n\nFile v1.1.2:references/configuration.md\n\n# Runtime configuration\n\n## WorkBuddy first\n\nThe mini program gives the user only two steps: tap “创建并复制”, then send the copied bundle to WorkBuddy. WorkBuddy must complete the commands, Skill sync, and `doctor` itself. Do not ask a non-technical user to choose between MCP and CLI.\n\nUse native Streamable HTTP MCP when WorkBuddy exposes it. Otherwise use the CLI fallback from the same copied bundle.\n\n## Native Streamable HTTP MCP\n\nUse the runtime's secret manager for `TREK_MCP_TOKEN`. The common configuration shape is:\n\n```json\n{\n \"mcpServers\": {\n \"trek\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://api.superd.fun/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${TREK_MCP_TOKEN}\"\n }\n }\n }\n}\n```\n\nRuntimes may spell the type `http`, `streamable_http`, or `streamable-http`. Do not copy the key into a shared JSON file if that runtime cannot expand environment variables.\n\n## Universal shell fallback\n\nRequirements: Node.js 18 or newer and outbound HTTPS.\n\n```bash\nnpm install -g https://github.com/super21-bat/trek-agent-control/archive/refs/heads/main.tar.gz\ntrek config init --api-key 'trek_...' --url 'https://api.superd.fun/mcp'\ntrek skill sync --global\ntrek doctor\n```\n\nThe mini program provides the endpoint, commands, and one-time key in one copied Agent access bundle. Do not split or repost that bundle. `trek config init` stores the key in `~/.trek/config.json` with mode `0600` on POSIX systems.\n\nThe public bootstrap source is the repository's stable branch tarball. Do not use\nthe `github:owner/repo` npm shorthand for global installation: some npm versions\nlink it to a temporary clone and leave a broken `trek` command after cleanup.\nAfter `@trek-cn/cli` is published to npm, the shorter\n`npm install -g @trek-cn/cli@latest` command may replace the GitHub install.\n\nOptional environment overrides:\n\n- `TREK_CONFIG`: custom config path.\n- `TREK_MCP_TOKEN`: override the stored key.\n- `TREK_MCP_URL`: defaults to `https://api.superd.fun/mcp`.\n- `TREK_MCP_TIMEOUT_MS`: per-request timeout, default `20000`.\n- `TREK_MCP_RETRIES`: retry count for 429/502/503/504 and network errors, default `7`.\n\n## Other compatible agents\n\nCodex, Claude, OpenClaw, Hermes and other terminal-capable agents follow the same connection sequence:\n\n1. Install the CLI and run `trek skill sync --global`.\n2. Run `trek config init` with the user's one-time key.\n3. Add the native MCP block when supported.\n4. Otherwise allow the agent to execute `trek ...`.\n5. Run `doctor`; require `ok: true`, a protocol version, a positive tool count, and successful `list_trips` before giving write access.\n\n`trek skill sync --global` delegates common Agent locations to the installed\nSkills runner. Trek also installs real copies into detected WorkBuddy\n`~/.workbuddy/skills/trek-agent-control` and Hermes\n`~/.hermes/skills/trek-agent-control` directories. Start a new WorkBuddy task or\nrestart the Hermes gateway after syncing. A cross-directory symlink is not\nenough for Hermes: it resolves symlinks before enforcing its trusted Skill\ndirectory.\n\nHermes native remote MCP support is optional. Hermes installations that include\nthe MCP extra may configure the Streamable HTTP endpoint directly; installations\nwithout it can use the Trek CLI fallback with the same capabilities. Trek must\nnot install or modify Hermes' Python environment automatically. Follow the\nHermes version's own installation instructions when native MCP is desired, and\ndo not hard-code another user's virtual-environment path.\n\n## Diagnostics\n\nRun `trek doctor` first. Its failure category determines the next check:\n\n- `configuration`: inspect `trek config get`, then re-run `config init`.\n- `network`: verify HTTPS/DNS/proxy access to the endpoint.\n- `authentication`: create a fresh Agent Key, initialize it, and revoke the old key.\n- `permission`: refresh `list_trips`; do not retry against another user's trip.\n- `rate_limit`: wait and retry sequentially.\n- `capability`: run `trek skill sync --global`, then inspect `trek tools`.\n\n## Key rotation\n\nCreate one key per external agent so access can be revoked independently. After rotating:\n\n1. Replace the secret in that runtime only.\n2. Run `doctor` with the new key.\n3. Revoke the old key in the mini program.\n4. Confirm the old key returns 401.\n\nFile v1.1.2:references/field-guide.md\n\n# Dynamic tool and field guide\n\nAlways discover the live schemas with `tools/list`. The server evolves and the live schema is authoritative.\n\n## Core read path\n\n- `list_trips`: identify accessible trips.\n- `get_trip_summary`: trip, top-level deduplicated places, days, assignments, reservations, accommodations, budget, packing items and bags, todos, notes and members.\n- Relevant `list_*`: obtain full records before editing or deleting.\n\n## Common write groups\n\n- Trip: `create_trip`, `update_trip`, `delete_trip`.\n- Schedule: day, place and assignment tools.\n- Search: `search_place` with `query`, explicit `market` (`china` or `global`), and either a Mainland `region` or overseas ISO `countryCode`.\n- Decisions: `*_trip_proposal` and collaboration polls.\n- Logistics: reservation and accommodation tools.\n- Money: budget item, member, payer and settlement tools.\n- Preparation: packing and todo tools.\n- Collaboration: note, poll and chat tools when enabled.\n\n## Idempotency keys for agent reasoning\n\nThe MCP tools do not promise a universal idempotency token. Before creating, compare:\n\n- trip: normalized title + start/end dates\n- place: normalized name + address + coordinates\n- assignment: day ID + place ID + start time\n- reservation: type + title + linked day/place\n- accommodation: place + start/end day\n- cost: category + name + amount\n- packing/todo: normalized name\n- note: normalized title\n\nReuse/update a match instead of creating a duplicate.\n\n## Saved and pending place visibility\n\n- 收藏 and 待决定 share the same place facts: name, address, description, notes,\n image, website and phone. Moving between the two states must preserve them.\n- For a researched candidate, `description` answers “what is this place”; `reason`\n answers “why consider it for this trip”. Do not put both meanings into one field.\n- Include a representative image only when its source is usable and stable. Never\n fabricate a photo URL. A candidate without verified media may omit `imageUrl`,\n but should still have a concise description whenever facts are available.\n- Verify rich candidate fields with `list_trip_proposals`; verify 收藏 fields with\n `list_places`. Do not report synchronization if the description was dropped.\n\n## Itinerary detail and ticket fields\n\nThe mini program opens an itinerary detail sheet when the user taps a day assignment. To make agent-written plans useful there:\n\n- Route fields by ownership instead of putting everything into one note:\n\n| User meaning | MCP field/tool | Mini program visibility |\n| --- | --- | --- |\n| Instructions for this specific visit | `update_assignment_time.notes` | `本次安排` in the assignment detail |\n| Stable POI introduction | `create_place.description` / `update_place.description` | `地点信息 → 地点介绍`, shown automatically when non-empty |\n| Reusable POI caveat | `create_place.notes` / `update_place.notes` | `地点信息 → 地点备注`, shown automatically when non-empty |\n| Address and contact | place `address`, `phone`, `website` | Primary address facts plus direct phone/website actions |\n| Trip cover | `upload_trip_file`, then `update_trip.cover_image` with the returned `file.url` | Trip list, Home hero and trip detail cover |\n| Place image | `upload_trip_file` with `place_id`, then `create_place.image_url` / `update_place.image_url` with the returned `file.url` | Place detail image and Home fallback image |\n| Booked time and voucher facts | reservation `reservation_time`, `reservation_end_time`, `confirmation_number`, `notes`, `url` | `预订信息`, linked through `assignment_id` |\n| Expense | budget `name`, `total_price`, `category`, `currency`, `expense_date`, `payers`, `member_ids`, `note` | Top-level `费用` tab |\n| Ticket image or PDF | `upload_trip_file` / `link_trip_file` with `assignment_id` or `reservation_id` | `票据与附件` in the assignment detail |\n\n- Put arrival instructions, meeting points, age restrictions, what to bring, and other readable guidance in the assignment or reservation `notes`.\n- Use `update_assignment_time.notes` for guidance specific to this visit. Use `update_place.notes` only for reusable place notes, and `update_place.description` for the public place introduction.\n- Keep the UI visibility contract intact: assignment `notes` appear as \"本次安排\"; place `address` appears in the primary facts; place `phone` and `website` appear as direct actions. Since mini program 0.2.18, place `description` and `notes` are shown directly in \"地点信息\" when at least one exists; the section is hidden when both are empty.\n- Treat every written field as a readback obligation. After `create_place`, `create_and_assign_place`, `update_place`, or `update_assignment_time`, call `list_places` or `get_trip_summary` and verify the exact value. Do not write opaque data to fields that the user cannot reach in the mini program.\n- Create a reservation for a ticket, restaurant, tour, study activity, or event and link it with `assignment_id`.\n- Use `confirmation_number` only for a real order/booking code.\n- Use `reservation_time` and `reservation_end_time` for the booked time window.\n- Use `url` for the official voucher, ticket, or booking page.\n- Uploaded images and PDFs remain trip files. Link them to the reservation or assignment instead of placing base64 data or long image URLs in notes.\n- For a visible trip cover or place image, upload the image as a trip file, persist the returned authenticated relative `file.url` in `cover_image` or `image_url`, then read back both the file link and entity field. Uploading bytes alone does not make an image visible.\n- Use `upload_trip_file` for an attachment up to 10 MB, or the bundled `upload-file` command so raw base64 never appears in terminal output. Use `list_trip_files` for readback, `link_trip_file` to add another relationship, and `trash_trip_file` to remove it from the active trip.\n- Keep the reservation `pending` until the user supplies booking evidence; then update it to `confirmed`.\n- The mini program's \"预订\" tab is the single editable reservation inventory. Legacy `day_assignments.reservation_*` fields are read-only compatibility data; do not write new booking data there.\n- Use fixed budget category keys such as `accommodation`, `food`, `transport`, `activities`, `shopping`, or `other`. Record `expense_date`, currency and payers when known.\n\n## Packing checklist fields\n\n- Prefer the mini program's three low-effort built-in packing locations: `随身必带`, `衣物`, and `日用健康`. “自定义” is an action, not a category name: when the user needs a special grouping, write the actual reusable category name.\n- Do not ask the user for a category when the item name makes it obvious. Infer it: identity documents, phone accessories, wallet and keys -> `随身必带`; clothing and footwear -> `衣物`; toiletries, sun protection, medicine, umbrella and tissues -> `日用健康`. If there is no stronger match and the user did not request a special grouping, omit `category` and let the service use the safe `随身必带` default.\n- For a real trip-specific need, pass a concise custom category such as `露营装备`, `摄影器材`, or `儿童用品`. Once one item uses that category, the mini program offers it directly for later items in the same trip and groups all same-category items together. Reuse the exact existing category spelling from readback instead of creating near-duplicates.\n- Legacy English/Chinese categories and historical `其他` remain readable. Do not create a category named after a place such as “为酒店准备”; use a reusable packing concept instead.\n- Always send `quantity` when the user needs more than one item. Valid values are integers from 1 to 999.\n- After `create_packing_item` or `update_packing_item`, read back the item and verify `name`, `category`, and `quantity`; do not report a successful packing update from the write response alone.\n- Reuse or update an existing normalized name instead of creating a duplicate, unless the same item genuinely belongs to different people or bags.\n\n## Batch file format\n\n`scripts/trek-mcp.mjs batch` accepts a JSON array:\n\n```json\n[\n {\n \"label\": \"Inspect current trips\",\n \"tool\": \"list_trips\",\n \"arguments\": { \"include_archived\": false }\n },\n {\n \"label\": \"Search official hotel POI\",\n \"tool\": \"search_place\",\n \"arguments\": { \"query\": \"清远狮子湖喜来登度假酒店\", \"market\": \"china\", \"region\": \"清远\", \"countryCode\": \"CN\" }\n }\n]\n```\n\nWithout `--apply`, the client prints the planned calls and performs no tools. With `--apply`, calls run sequentially and stop on the first error. Every result has the same compatibility envelope: `ok`, `resourceType`, `resource`, `warnings`, and the original tool payload in `result`. Tool names containing delete/remove/decide/schedule/settle/restore/rotate require `--confirm-high-risk`.\n\n## Readback checklist\n\nVerify:\n\n- exact trip dates and day count\n- actual assignments by date/place equal the pre-write `expectedAssignmentsByDate` checklist\n- every detailed-plan POI/activity is a visible assignment, not only day-note text\n- any planned day with zero assignments is treated as a failure; intentional rest/location-free travel days are explicitly marked\n- a hotel listed as a daily activity has both its accommodation range and a day assignment\n- fixed assignments retain start/end times\n- chronological order places untimed items last\n- coordinates and addresses belong to the intended city\n- reservations use honest status and no fabricated confirmation number\n- assignment-linked reservations expose confirmation numbers, notes, voucher URLs and files in the mini program detail sheet\n- accommodation day span and check-in/out\n- budget currency, amount, persons/days and notes\n- every expense and reservation created by the agent is editable and visible in the mini program's corresponding top-level tab\n- no duplicate packing/todo/note names\n- top-level `places[]` includes assigned and unassigned places\n- `packing.bags[]` includes empty bags as well as bags referenced by items\n- unresolved facts remain todos or explicit notes\n\n## Day view contract — mini program 0.3.22+\n\n| User meaning | MCP write | Mini program visibility |\n| --- | --- | --- |\n| Short daily title | `update_day.title`, max 200; recommend <=25 characters | Date tab (one line) and section heading (two lines); long text is shortened |\n| Daily clothing/tickets/things to bring | `update_day.daily_brief`, max 500; keep concise plain text, use actual newline characters between ideas; no Markdown; empty/null clears | Reminder and notes share one collapsed day-information group; mini program 0.3.24+ renders each reminder line separately; weather is separate in the day title |\n| Timed action with no map stop | `create_day_note` / `update_day_note`: text max 500, optional time | 当天备注 rows, including existing stored notes; long text expands in place |\n| Actual visit/route stop | `assign_place_to_day`, `update_assignment_time` | Ordered itinerary and route map |\n| Visit instructions | Both tools above write the same assignment `notes` | 本次安排 in the visit details |\n| Hotel date range | `create_accommodation` | Reservation data; an assignment is still needed for a route stop |\n| Packing / budget / unassigned reservation | Respective tools | Their own sections, not automatic day itinerary rows |\n\nDo not substitute a long title for daily_brief. Do not invent nearby POIs for location-free actions. Do not delete or duplicate existing notes to compensate for old clients. Notes require mini program 0.3.18+; check the user's installed version when visibility is disputed.\n\n`preview_day_view {tripId,dayId}` returns authored reminder, automatic weather display metadata, renderedNotes and ordered renderedAssignments. Weather is not fetched by this preview. It is a server-side content contract, not a screenshot; assignment details require places:read. `get_trip_summary.days[].notes` contains note entries while REST days use `notes_items`.\n\nWeather guidance: research current weather before authoring a brief, distinguish forecast from historical climate, and include source/date in text when useful. Do not invent a forecast outside the provider window. Clearing the brief hides only the authored reminder; it does not control automatic weather. Custom text stays exactly as authored until changed.\n\n### Optional day extras (0.3.18)\n\n- Reminders and notes share one “当天信息” group, collapsed by default. Expand to read; enter edit mode to add/edit/delete each in place. Notes are not route/map stops. Weather is not in this group.\n- Weather is automatic: weather for the selected date and first located assignment appears below the day title when data is available. MET Norway is preferred for the first nine days; extended forecasts cover days 10–15; dates beyond day 15 show historical temperature estimates labeled “历史预估”. Weather refresh is cached daily. Do not set `weather_enabled`.\n- Weather is cached for a day on the client and shared by rounded location on the server. The mini program shows a compact summary below the day title; source and update metadata stay in the provider/service contract. Authored text is not automatically refreshed.\n- Use `preview_day_view.notesPresentation` to explain collapsed state; `renderedNotes` means available after expansion, not all rows visible on first opening. Preview does not fetch weather or prove a screenshot.\n- Keep each note as one action/supporting item (text <=500); `text` is the editable label/body, so no separate name field is needed. Assignment notes from assign/update tools refer to the same visit-specific field. Packing and budget remain in their own tabs; do not duplicate them as itinerary stops.\n\nFile v1.1.2:references/workflows.md\n\n# Research and synchronization workflows\n\n## Research a new trip\n\n1. Collect hard constraints: travelers, ages, accessibility, origin, dates, fixed bookings, work/school windows, budget and transport.\n2. Verify time-sensitive claims online. Prefer official attraction, venue, carrier, hotel, government and map sources.\n3. Use `search_place` for each real destination. In Mainland China pass `market: \"china\"` and an administrative region such as `深圳` or `清远`; overseas pass `market: \"global\"` and a two-letter country code such as `JP` or `FR`.\n4. Design each day around geography, opening windows, heat/rain, meals, rest and transfer buffers. Extract every planned POI/activity into `expectedAssignmentsByDate`; do not leave locations only in narrative text.\n5. Mark every item as confirmed, recommended, optional or pending confirmation.\n6. Preview the plan before creating data.\n\n## Create or update a trip\n\n1. `list_trips` and normalize titles/dates to detect an existing trip.\n2. Create only when no match exists; otherwise use the current trip ID.\n3. `get_trip_summary` and map its day IDs to ISO dates.\n4. Create/reuse places, then assign every expected POI/activity to the correct day with start/end time, duration, transport mode and assignment notes. New place: `create_and_assign_place`; existing place: `assign_place_to_day`.\n5. Add reservations/accommodations only from evidence. Accommodation tools create a date range, not a daily assignment; if the hotel/check-in is part of the visible daily plan, also assign the hotel place to that day.\n6. Add costs as estimates unless receipts/orders establish actual values.\n7. Add packing items for traveler and destination needs.\n8. Add todos for unresolved bookings, deadlines, safety checks and missing documents. Use due dates and priority.\n9. Add collaboration notes for cross-cutting instructions that must remain visible.\n10. When adding a trip cover or place image, upload the image, write the returned authenticated `file.url` to `trip.cover_image` or `place.image_url`, and verify both values on readback. A successful file upload without the entity field is incomplete.\n11. Read back and compare each date's normalized assignment place names/IDs to `expectedAssignmentsByDate`. Any planned day with zero assignments, any expected place missing, or any POI present only in day-note text is a failed synchronization. Fix it before reporting completion. Intentional rest/location-free travel days must be marked explicitly.\n\nSave the full expected checklist as a JSON object when using the bundled audit command. An empty array explicitly marks a rest/location-free day:\n\n```json\n{\n \"2026-09-23\": [\"金门大桥\", \"Presidio\"],\n \"2026-09-24\": [],\n \"2026-09-25\": [\"Stanford University\", \"Apple Park Visitor Center\"]\n}\n```\n\nRun `node scripts/trek-mcp.mjs audit-plan <trip-id> /absolute/path/expected-assignments.json`. Exit code `2` means at least one date is missing, has missing assignments, or contains unexpected assignments; do not report completion.\n\n## Collaborative planning\n\nUse proposals before formal itinerary writes when a group has not decided:\n\n1. `create_trip_proposal`\n2. `react_trip_proposal`\n3. `decide_trip_proposal` only after the owner confirms\n4. `schedule_trip_proposal` only after choosing a day\n5. `list_trip_proposals` to verify final status\n\nUse polls for broad group choices and proposals for candidate places that may become scheduled items.\n\n### Add one pending place\n\nPrefer the semantic tool; do not assemble this from primitive writes:\n\n1. If the place is already in 收藏, obtain its ID from `list_places`.\n2. Call `add_pending_place({ tripId, placeId, title, ... })`; `placeId` is preferred\n for an existing saved place and prevents duplicate data.\n For a new candidate, pass `description`, `imageUrl`, `website`, `phone` and\n `placeNotes` when verified. Keep `reason` short and specific to this trip.\n3. Require `persisted: true`, `destination: \"pending\"`, and an `open` proposal\n in the returned readback.\n4. To remove it from active discussion but keep it saved, call\n `move_pending_place_to_saved({ tripId, proposalId })` after user confirmation.\n\nDo not use `create_place`: a saved place is not the mini program's “待决定” item.\nDo not report success without the semantic tool's persisted readback.\n\n## Change an existing trip safely\n\nCreate a diff with:\n\n- current value\n- proposed value\n- reason/source\n- affected reservations, costs, members and travel time\n\nGet confirmation before deleting, moving fixed bookings, changing financial data, or replacing confirmed reservations. Apply changes in dependency order and read back after each group.\n\n## Daily briefing\n\nRead the trip summary, today's day, reservations, todos and weather. Return:\n\n- next fixed event and departure deadline\n- route and buffer\n- weather/clothing\n- tickets/documents\n- meal plan\n- unresolved high-priority todo\n\nDo not write anything for a briefing unless the user explicitly asks to update the trip.\n\n## Evidence policy\n\n- A map result establishes name/address/coordinates, not quality or current opening hours.\n- A social post is a recommendation signal, not proof of current policy.\n- A reservation is confirmed only with user/order evidence.\n- If exact time, address, price, phone or booking status is unknown, preserve the uncertainty in a todo or note.\n\n## Verify notes and daily reminders\n\nAfter synchronization, use `trek day-view TRIP_ID DAY_ID` to read the 0.3.18+ display contract. `audit-plan` verifies assignment names only; it does not verify notes, reminders, client version or screenshots.\n\nFor timed notes, create an expected JSON file (no real user content in shared examples):\n\n```json\n{\"2026-10-01\":[{\"text\":\"带好演出门票和证件\",\"time\":\"18:00\"}]}\n```\n\nRun `trek audit-notes TRIP_ID expected-notes.json`. Missing, unexpected or duplicate text/time entries fail the audit (exit 2). Read back the exact daily brief through `day-view`; do not write again simply because an old client cannot show it.\n\nFile v1.1.2:skill-card.md\n\n## Description:\n\nTrek Agent Control helps agents connect to the Trek travel mini program through authenticated MCP or CLI flows to plan trips, inspect and update itinerary data, upload tickets, run diagnostics, and synchronize readback-verified changes.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[super21-bat](https://clawhub.ai/user/super21-bat)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users, developers, and terminal-capable agents use this skill to operate a user's Trek travel workspace: connect with a Trek Agent Key, research travel plans, preview and apply itinerary changes, manage reservations, attachments, packing, todos, costs, and collaboration proposals, then verify the synchronized state.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill installs mutable global code.\n\nMitigation: Review before installing and prefer a pinned or registry-published CLI release over installing from a live GitHub branch.\n\nRisk: A broad Trek Agent Key may be persisted or exposed.\n\nMitigation: Use a dedicated Trek Agent Key for each agent, treat copied bundles as secrets, and revoke the key when finished or if exposed.\n\nRisk: The skill can modify real itinerary, reservation, attachment, collaboration, and budget data.\n\nMitigation: Grant it only to trusted agents, preview destructive or high-impact writes, apply changes in small batches, and verify changes through readback before reporting synchronization complete.\n\n## Reference(s):\n\n- [Runtime configuration](references/configuration.md)\n- [Dynamic tool and field guide](references/field-guide.md)\n- [Research and synchronization workflows](references/workflows.md)\n- [ClawHub skill page](https://clawhub.ai/super21-bat/skills/trek-agent-control)\n\n## Skill Output:\n\n**Output Type(s):** [guidance, markdown, shell commands, configuration, JSON, API calls]\n\n**Output Format:** [Markdown with inline shell commands, JSON snippets, and MCP tool guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May direct agents to perform readback checks, create expected-assignment JSON, and preserve diagnostic output when synchronization fails.]\n\n## Skill Version(s):\n\n1.1.2 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.1.1: 6 files, 19124 bytes\n\nFiles: references/configuration.md (4307b), references/field-guide.md (13552b), references/workflows.md (6035b), skill-card.md (2509b), SKILL.md (12166b), _meta.json (137b)\n\nFile v1.1.1:SKILL.md\n\n---\nname: trek-agent-control\ndescription: 配套 Trek 微信旅行小程序的自动化 Skill，主要面向 WorkBuddy，也兼容 Codex、Claude、OpenClaw、Hermes 等 Agent。通过认证的远程 MCP 研究国内外目的地、读取或修改行程，并把日程、地点、预订、住宿、费用、清单、待办、附件和协作提案安全同步回小程序。Use when WorkBuddy or another agent needs to plan travel, inspect Trek data, synchronize structured itinerary fields, upload tickets, or run safe diagnostics with a user-provided Trek Agent Key.\n---\n\n# Trek Agent Control\n\nControl the user's real Trek data through MCP. Treat web research and Trek synchronization as separate phases: research first, then show a concrete change preview, then write and read back.\n\n## Product workspace\n\nTrek 微信旅行小程序是用户查看、编辑、导航、分享和协作的行程工作区；本\nSkill 是它的 Agent 自动化层。用户先在小程序创建行程和独立 Agent Key，\nAgent 再研究资料并把结构化结果同步回同一行程。不要创建与小程序脱离的第二份\n行程数据，也不要把聊天回答误报成已同步。\n\n![微信扫码打开 Trek 旅行小程序](https://raw.githubusercontent.com/super21-bat/trek-agent-control/main/assets/trek-miniapp-code.png)\n\n当前二维码为测试阶段入口，是否可直接进入以微信侧体验权限为准。\n\n## Connect\n\n1. Never paste the `trek_` key into files, prompts, logs, screenshots, commits, or shell history intended for sharing.\n2. Prefer the agent's native Streamable HTTP MCP support. Configure:\n - URL: `https://api.superd.fun/mcp`\n - Header: `Authorization: Bearer <user-key>`\n3. Use the Trek CLI to install/sync this Skill, verify the connection, and diagnose failures:\n\n```bash\nnpm install -g https://github.com/super21-bat/trek-agent-control/archive/refs/heads/main.tar.gz\ntrek config init --api-key 'trek_...' --url 'https://api.superd.fun/mcp'\ntrek skill sync --global\ntrek doctor\n```\n\nThe mini program presents this to ordinary users as two steps: copy once, then send the copied bundle to WorkBuddy. WorkBuddy should complete installation, configuration, Skill sync, and `doctor` without asking the user to run commands manually. Treat the whole bundle as a secret. If native remote MCP is unavailable or unreliable, execute all operations through `trek`; it calls the same MCP endpoint. Read [references/configuration.md](references/configuration.md) for runtime details.\n\n## Fast paths for common user requests\n\nDo not load the large-planning workflow for these small writes. Use the exact\nrecipe, then stop:\n\n- “加到待定/候选地点”：resolve the trip with `list_trips`, then run\n `trek add-pending <trip-id> <title> [--place-id <saved-place-id>]` or call\n native MCP `add_pending_place`. If the place already exists in 收藏, pass its\n `placeId`; the server links/reuses that place instead of creating a duplicate.\n For a newly researched candidate, include a short stable `description` and a\n representative `imageUrl` when available; put the trip-specific recommendation\n in `reason`. A name plus address alone is not enough context for group voting.\n `apply_trip_change` with `action: \"add_pending\"` remains a compatible fallback.\n Never use `create_place` for 待选/候选/待决定.\n- “设置行程封面”：run `trek set-cover <trip-id>\n <absolute-image>` or call native MCP `apply_trip_change` with `action:\n \"set_cover\"`. The server owns upload, binding and readback as one semantic\n operation; do not compose primitive upload/update calls when this tool exists.\n\nFor either fast path, if readback fails, report “未同步” and the exact failed\nstage. Never continue into unrelated planning or claim the mini program will\neventually refresh.\n\n## Mandatory workflow\n\n1. Run `doctor` or native `tools/list`. Stop on authentication, network, or missing-tool failure.\n2. Read existing state with `list_trips` and `get_trip_summary`. Never assume a trip ID. Use top-level `places[]` for every trip place, including unassigned places; use `packing.bags[]` for all bags, including empty bags.\n3. Research current facts with primary/official sources first. Separate confirmed facts, recommendations, and unresolved items.\n4. Build a dated plan and an `expectedAssignmentsByDate` checklist containing every POI/activity that must appear in the mini program. Use exact local dates and times. Do not invent reservations, confirmation numbers, phone numbers, opening hours, prices, or addresses.\n5. Show the user a compact change preview before destructive, bulk, financial, membership, proposal-decision, or rescheduling writes.\n6. Write in small batches. Reuse existing entities and detect duplicates by normalized name/date before creating.\n7. Every real location visit must be a Place plus Assignment. Use `create_and_assign_place` for a new POI and `assign_place_to_day` for an existing one. Location-free actions (wake up, bring tickets, meet a friend) can be timed day notes: visible in the day-notes section in mini program 0.3.18+, but not map stops. Never fabricate a POI just to make a note visible; older clients must upgrade.\n8. Model accommodation separately. `create_place_accommodation`/`create_accommodation` create a lodging date range but no visible day assignment. If a hotel or check-in is in the daily plan, also assign its place to that day.\n9. Populate only meaningful fields, but use the complete model when relevant: trip dates/description, days, places and coordinates, assignment start/end/duration/transport/notes, reservations, accommodations, costs, packing, todos, collaboration notes, proposals and members.\n10. Read back with `get_trip_summary` plus the relevant `list_*` tool. Compare `expectedAssignmentsByDate` to actual `days[].assignments` by date and normalized place name/ID, not only counts. A planned day must not have zero assignments; explicitly document intentional rest/location-free travel days.\n11. Do not report synchronization complete while any expected assignment is missing or only mentioned in a day note. Repair the gap or disclose it to the user.\n12. Report what changed, what remains uncertain, and what the user must confirm.\n\nRead [references/workflows.md](references/workflows.md) for detailed planning and synchronization recipes. Read [references/field-guide.md](references/field-guide.md) before a large or unfamiliar write.\n\n## CLI\n\n```bash\ntrek doctor\ntrek update --check\ntrek tools place\ntrek call list_trips '{\"include_archived\":false}'\ntrek summary 3\ntrek audit-plan 3 /absolute/path/expected-assignments.json\ntrek add-pending 3 '西湖游船' --reason '同行者表态后再排日程'\ntrek upload-file 3 /absolute/path/ticket.pdf --assignment 42 --description '景区电子票'\ntrek set-cover 3 /absolute/path/cover.jpg --description '行程封面'\ntrek rename-file 3 19 '金门大桥门票.pdf'\ntrek batch /absolute/path/actions.json\ntrek batch /absolute/path/actions.json --apply\ntrek smoke --allow-write-smoke\n```\n\n`doctor` reports local configuration, endpoint, credential presence, Skill integrity, authentication, live tool count, and trip readback. Failures include a category, hint, and next command; retain that structured output when diagnosing. `update --check` compares CLI versions; `update` upgrades the CLI and resynchronizes the Skill. `audit-plan` compares an expected JSON date-to-place mapping with live `days[].assignments` and exits non-zero on missing items. `add-pending` creates or reuses a candidate and verifies the open proposal by ID. `upload-file` reads a local attachment without printing its base64 and supports files up to 10 MB. `set-cover` uploads, binds, and verifies a visible trip cover as one command. `rename-file` changes only the display name and keeps the extension. `batch` is dry-run unless `--apply` is present. Applied actions always expose `ok`, `resourceType`, `resource`, `warnings`, and the original `result`; execution stops on the first failed action. It refuses high-risk tool names unless `--confirm-high-risk` is also present. `smoke` creates temporary data, exercises the proposal lifecycle, deletes it, and closes the MCP session.\n\n## Safety invariants\n\n- Treat the key as a password. Ask the user to revoke it immediately if exposed.\n- Never delete or overwrite real data during diagnostics. Use the bundled temporary smoke only.\n- Do not mark bookings confirmed without order evidence. Use `pending` or a todo for unresolved bookings.\n- Do not create fake coordinates. Use `search_place` with `market: \"china\"` plus `region` in Mainland China, or `market: \"global\"` plus an ISO `countryCode` for overseas trips. Preserve the returned provider IDs and coordinates.\n- For minors, medical needs, border crossings, flights, and tight transfers, add safety buffers and explicit adult-confirmation tasks.\n- Respect 429 responses. Do not disable server limits or fire requests in parallel; the bundled client retries with bounded backoff.\n- Static `trek_` keys currently grant broad user access. Create one per Agent, revoke unused keys, and prefer scoped OAuth when the target agent supports it.\n- Close every MCP session, including failed runs.\n\n## Failure handling\n\n- `401`: key missing, revoked, malformed, or sent without `Bearer`.\n- `403`: user lacks trip permission or scope; do not retry as another user.\n- `404`: wrong trip/entity ID or inaccessible resource; refresh state.\n- `429`: wait and retry sequentially; reduce batch size.\n- `isError: true`: treat as failed even if HTTP succeeded. Preserve the error text and stop dependent writes.\n- Unknown fields/tools: call `tools/list`; never guess a schema from an older document.\n\nWhen native MCP and the bundled client disagree, trust a fresh `tools/list` response and production readback.\n\n## Daily notes and reminders (mini program 0.3.18+)\n\n- Keep day titles short (about 25 characters). Use `update_day.daily_brief` for a user-authored weather/clothing/tickets/packing reminder, up to 500 characters; empty or null hides the reminder; weather is independent and off by default. Enable it only when requested via `update_day.weather_enabled=true`. `trek set-day-brief <trip-id> <day-id> @brief.txt` writes and reads back.\n- `create_day_note` stores a timed action in the visible day-notes section, without adding a map stop. These notes were invisible in 0.3.16 and older.\n- `trek day-view <trip-id> <day-id>` / `preview_day_view` returns the content contract and minimum client version, not a screenshot or proof the user installed that version. Compare notes using `trek audit-notes <trip-id> expected-notes.json`; `audit-plan` checks assignments only.\n- Use the current authorized tool schema. With semantic profile, discover these advanced tools and reconnect using full profile if needed. For exact fields and boundaries read [references/field-guide.md](references/field-guide.md).\n\n### Optional day extras (0.3.18)\n\n- Day notes are grouped under “当天备注 · count”, collapsed by default. Expand to read; tap a note to edit/delete in place. Notes are not route/map stops. Empty notes and reminders have no content panel.\n- `update_day.weather_enabled` is an independent boolean, default false. Enable only when requested; clearing `daily_brief` never turns weather on. Dates beyond MET Norway's actual forecast (up to about nine days), missing coordinates, or unavailable forecasts show no weather card.\n- Weather is cached on the client for the day and shared by rounded location on the server. MET Norway attribution and update time are shown. Authored text is not automatically refreshed.\n- Use `preview_day_view.notesPresentation` to explain collapsed state; `renderedNotes` means available after expansion, not all rows visible on first opening. Preview does not fetch weather or prove a screenshot.\n- Keep each note as one action/supporting item (text <=500); `text` is the editable label/body, so no separate name field is needed. Assignment notes from assign/update tools refer to the same visit-specific field. Packing and budget remain in their own tabs; do not duplicate them as itinerary stops.\n\nFile v1.1.1:_meta.json\n\n{\n \"ownerId\": \"kn70axt20cegjzmp4nnsrs1fmx82khb0\",\n \"slug\": \"trek-agent-control\",\n \"version\": \"1.1.1\",\n \"publishedAt\": 1789889230992\n}\n\nFile v1.1.1:references/configuration.md\n\n# Runtime configuration\n\n## WorkBuddy first\n\nThe mini program gives the user only two steps: tap “创建并复制”, then send the copied bundle to WorkBuddy. WorkBuddy must complete the commands, Skill sync, and `doctor` itself. Do not ask a non-technical user to choose between MCP and CLI.\n\nUse native Streamable HTTP MCP when WorkBuddy exposes it. Otherwise use the CLI fallback from the same copied bundle.\n\n## Native Streamable HTTP MCP\n\nUse the runtime's secret manager for `TREK_MCP_TOKEN`. The common configuration shape is:\n\n```json\n{\n \"mcpServers\": {\n \"trek\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://api.superd.fun/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${TREK_MCP_TOKEN}\"\n }\n }\n }\n}\n```\n\nRuntimes may spell the type `http`, `streamable_http`, or `streamable-http`. Do not copy the key into a shared JSON file if that runtime cannot expand environment variables.\n\n## Universal shell fallback\n\nRequirements: Node.js 18 or newer and outbound HTTPS.\n\n```bash\nnpm install -g https://github.com/super21-bat/trek-agent-control/archive/refs/heads/main.tar.gz\ntrek config init --api-key 'trek_...' --url 'https://api.superd.fun/mcp'\ntrek skill sync --global\ntrek doctor\n```\n\nThe mini program provides the endpoint, commands, and one-time key in one copied Agent access bundle. Do not split or repost that bundle. `trek config init` stores the key in `~/.trek/config.json` with mode `0600` on POSIX systems.\n\nThe public bootstrap source is the repository's stable branch tarball. Do not use\nthe `github:owner/repo` npm shorthand for global installation: some npm versions\nlink it to a temporary clone and leave a broken `trek` command after cleanup.\nAfter `@trek-cn/cli` is published to npm, the shorter\n`npm install -g @trek-cn/cli@latest` command may replace the GitHub install.\n\nOptional environment overrides:\n\n- `TREK_CONFIG`: custom config path.\n- `TREK_MCP_TOKEN`: override the stored key.\n- `TREK_MCP_URL`: defaults to `https://api.superd.fun/mcp`.\n- `TREK_MCP_TIMEOUT_MS`: per-request timeout, default `20000`.\n- `TREK_MCP_RETRIES`: retry count for 429/502/503/504 and network errors, default `7`.\n\n## Other compatible agents\n\nCodex, Claude, OpenClaw, Hermes and other terminal-capable agents follow the same connection sequence:\n\n1. Install the CLI and run `trek skill sync --global`.\n2. Run `trek config init` with the user's one-time key.\n3. Add the native MCP block when supported.\n4. Otherwise allow the agent to execute `trek ...`.\n5. Run `doctor`; require `ok: true`, a protocol version, a positive tool count, and successful `list_trips` before giving write access.\n\n`trek skill sync --global` delegates common Agent locations to the installed\nSkills runner. Trek also installs real copies into detected WorkBuddy\n`~/.workbuddy/skills/trek-agent-control` and Hermes\n`~/.hermes/skills/trek-agent-control` directories. Start a new WorkBuddy task or\nrestart the Hermes gateway after syncing. A cross-directory symlink is not\nenough for Hermes: it resolves symlinks before enforcing its trusted Skill\ndirectory.\n\nHermes native remote MCP support is optional. Hermes installations that include\nthe MCP extra may configure the Streamable HTTP endpoint directly; installations\nwithout it can use the Trek CLI fallback with the same capabilities. Trek must\nnot install or modify Hermes' Python environment automatically. Follow the\nHermes version's own installation instructions when native MCP is desired, and\ndo not hard-code another user's virtual-environment path.\n\n## Diagnostics\n\nRun `trek doctor` first. Its failure category determines the next check:\n\n- `configuration`: inspect `trek config get`, then re-run `config init`.\n- `network`: verify HTTPS/DNS/proxy access to the endpoint.\n- `authentication`: create a fresh Agent Key, initialize it, and revoke the old key.\n- `permission`: refresh `list_trips`; do not retry against another user's trip.\n- `rate_limit`: wait and retry sequentially.\n- `capability`: run `trek skill sync --global`, then inspect `trek tools`.\n\n## Key rotation\n\nCreate one key per external agent so access can be revoked independently. After rotating:\n\n1. Replace the secret in that runtime only.\n2. Run `doctor` with the new key.\n3. Revoke the old key in the mini program.\n4. Confirm the old key returns 401.\n\nFile v1.1.1:references/field-guide.md\n\n# Dynamic tool and field guide\n\nAlways discover the live schemas with `tools/list`. The server evolves and the live schema is authoritative.\n\n## Core read path\n\n- `list_trips`: identify accessible trips.\n- `get_trip_summary`: trip, top-level deduplicated places, days, assignments, reservations, accommodations, budget, packing items and bags, todos, notes and members.\n- Relevant `list_*`: obtain full records before editing or deleting.\n\n## Common write groups\n\n- Trip: `create_trip`, `update_trip`, `delete_trip`.\n- Schedule: day, place and assignment tools.\n- Search: `search_place` with `query`, explicit `market` (`china` or `global`), and either a Mainland `region` or overseas ISO `countryCode`.\n- Decisions: `*_trip_proposal` and collaboration polls.\n- Logistics: reservation and accommodation tools.\n- Money: budget item, member, payer and settlement tools.\n- Preparation: packing and todo tools.\n- Collaboration: note, poll and chat tools when enabled.\n\n## Idempotency keys for agent reasoning\n\nThe MCP tools do not promise a universal idempotency token. Before creating, compare:\n\n- trip: normalized title + start/end dates\n- place: normalized name + address + coordinates\n- assignment: day ID + place ID + start time\n- reservation: type + title + linked day/place\n- accommodation: place + start/end day\n- cost: category + name + amount\n- packing/todo: normalized name\n- note: normalized title\n\nReuse/update a match instead of creating a duplicate.\n\n## Saved and pending place visibility\n\n- 收藏 and 待决定 share the same place facts: name, address, description, notes,\n image, website and phone. Moving between the two states must preserve them.\n- For a researched candidate, `description` answers “what is this place”; `reason`\n answers “why consider it for this trip”. Do not put both meanings into one field.\n- Include a representative image only when its source is usable and stable. Never\n fabricate a photo URL. A candidate without verified media may omit `imageUrl`,\n but should still have a concise description whenever facts are available.\n- Verify rich candidate fields with `list_trip_proposals`; verify 收藏 fields with\n `list_places`. Do not report synchronization if the description was dropped.\n\n## Itinerary detail and ticket fields\n\nThe mini program opens an itinerary detail sheet when the user taps a day assignment. To make agent-written plans useful there:\n\n- Route fields by ownership instead of putting everything into one note:\n\n| User meaning | MCP field/tool | Mini program visibility |\n| --- | --- | --- |\n| Instructions for this specific visit | `update_assignment_time.notes` | `本次安排` in the assignment detail |\n| Stable POI introduction | `create_place.description` / `update_place.description` | `地点信息 → 地点介绍`, shown automatically when non-empty |\n| Reusable POI caveat | `create_place.notes` / `update_place.notes` | `地点信息 → 地点备注`, shown automatically when non-empty |\n| Address and contact | place `address`, `phone`, `website` | Primary address facts plus direct phone/website actions |\n| Trip cover | `upload_trip_file`, then `update_trip.cover_image` with the returned `file.url` | Trip list, Home hero and trip detail cover |\n| Place image | `upload_trip_file` with `place_id`, then `create_place.image_url` / `update_place.image_url` with the returned `file.url` | Place detail image and Home fallback image |\n| Booked time and voucher facts | reservation `reservation_time`, `reservation_end_time`, `confirmation_number`, `notes`, `url` | `预订信息`, linked through `assignment_id` |\n| Expense | budget `name`, `total_price`, `category`, `currency`, `expense_date`, `payers`, `member_ids`, `note` | Top-level `费用` tab |\n| Ticket image or PDF | `upload_trip_file` / `link_trip_file` with `assignment_id` or `reservation_id` | `票据与附件` in the assignment detail |\n\n- Put arrival instructions, meeting points, age restrictions, what to bring, and other readable guidance in the assignment or reservation `notes`.\n- Use `update_assignment_time.notes` for guidance specific to this visit. Use `update_place.notes` only for reusable place notes, and `update_place.description` for the public place introduction.\n- Keep the UI visibility contract intact: assignment `notes` appear as \"本次安排\"; place `address` appears in the primary facts; place `phone` and `website` appear as direct actions. Since mini program 0.2.18, place `description` and `notes` are shown directly in \"地点信息\" when at least one exists; the section is hidden when both are empty.\n- Treat every written field as a readback obligation. After `create_place`, `create_and_assign_place`, `update_place`, or `update_assignment_time`, call `list_places` or `get_trip_summary` and verify the exact value. Do not write opaque data to fields that the user cannot reach in the mini program.\n- Create a reservation for a ticket, restaurant, tour, study activity, or event and link it with `assignment_id`.\n- Use `confirmation_number` only for a real order/booking code.\n- Use `reservation_time` and `reservation_end_time` for the booked time window.\n- Use `url` for the official voucher, ticket, or booking page.\n- Uploaded images and PDFs remain trip files. Link them to the reservation or assignment instead of placing base64 data or long image URLs in notes.\n- For a visible trip cover or place image, upload the image as a trip file, persist the returned authenticated relative `file.url` in `cover_image` or `image_url`, then read back both the file link and entity field. Uploading bytes alone does not make an image visible.\n- Use `upload_trip_file` for an attachment up to 10 MB, or the bundled `upload-file` command so raw base64 never appears in terminal output. Use `list_trip_files` for readback, `link_trip_file` to add another relationship, and `trash_trip_file` to remove it from the active trip.\n- Keep the reservation `pending` until the user supplies booking evidence; then update it to `confirmed`.\n- The mini program's \"预订\" tab is the single editable reservation inventory. Legacy `day_assignments.reservation_*` fields are read-only compatibility data; do not write new booking data there.\n- Use fixed budget category keys such as `accommodation`, `food`, `transport`, `activities`, `shopping`, or `other`. Record `expense_date`, currency and payers when known.\n\n## Packing checklist fields\n\n- Prefer the mini program's three low-effort built-in packing locations: `随身必带`, `衣物`, and `日用健康`. “自定义” is an action, not a category name: when the user needs a special grouping, write the actual reusable category name.\n- Do not ask the user for a category when the item name makes it obvious. Infer it: identity documents, phone accessories, wallet and keys -> `随身必带`; clothing and footwear -> `衣物`; toiletries, sun protection, medicine, umbrella and tissues -> `日用健康`. If there is no stronger match and the user did not request a special grouping, omit `category` and let the service use the safe `随身必带` default.\n- For a real trip-specific need, pass a concise custom category such as `露营装备`, `摄影器材`, or `儿童用品`. Once one item uses that category, the mini program offers it directly for later items in the same trip and groups all same-category items together. Reuse the exact existing category spelling from readback instead of creating near-duplicates.\n- Legacy English/Chinese categories and historical `其他` remain readable. Do not create a category named after a place such as “为酒店准备”; use a reusable packing concept instead.\n- Always send `quantity` when the user needs more than one item. Valid values are integers from 1 to 999.\n- After `create_packing_item` or `update_packing_item`, read back the item and verify `name`, `category`, and `quantity`; do not report a successful packing update from the write response alone.\n- Reuse or update an existing normalized name instead of creating a duplicate, unless the same item genuinely belongs to different people or bags.\n\n## Batch file format\n\n`scripts/trek-mcp.mjs batch` accepts a JSON array:\n\n```json\n[\n {\n \"label\": \"Inspect current trips\",\n \"tool\": \"list_trips\",\n \"arguments\": { \"include_archived\": false }\n },\n {\n \"label\": \"Search official hotel POI\",\n \"tool\": \"search_place\",\n \"arguments\": { \"query\": \"清远狮子湖喜来登度假酒店\", \"market\": \"china\", \"region\": \"清远\", \"countryCode\": \"CN\" }\n }\n]\n```\n\nWithout `--apply`, the client prints the planned calls and performs no tools. With `--apply`, calls run sequentially and stop on the first error. Every result has the same compatibility envelope: `ok`, `resourceType`, `resource`, `warnings`, and the original tool payload in `result`. Tool names containing delete/remove/decide/schedule/settle/restore/rotate require `--confirm-high-risk`.\n\n## Readback checklist\n\nVerify:\n\n- exact trip dates and day count\n- actual assignments by date/place equal the pre-write `expectedAssignmentsByDate` checklist\n- every detailed-plan POI/activity is a visible assignment, not only day-note text\n- any planned day with zero assignments is treated as a failure; intentional rest/location-free travel days are explicitly marked\n- a hotel listed as a daily activity has both its accommodation range and a day assignment\n- fixed assignments retain start/end times\n- chronological order places untimed items last\n- coordinates and addresses belong to the intended city\n- reservations use honest status and no fabricated confirmation number\n- assignment-linked reservations expose confirmation numbers, notes, voucher URLs and files in the mini program detail sheet\n- accommodation day span and check-in/out\n- budget currency, amount, persons/days and notes\n- every expense and reservation created by the agent is editable and visible in the mini program's corresponding top-level tab\n- no duplicate packing/todo/note names\n- top-level `places[]` includes assigned and unassigned places\n- `packing.bags[]` includes empty bags as well as bags referenced by items\n- unresolved facts remain todos or explicit notes\n\n## Day view contract — mini program 0.3.18+\n\n| User meaning | MCP write | Mini program visibility |\n| --- | --- | --- |\n| Short daily title | `update_day.title`, max 200; recommend <=25 characters | Date tab (one line) and section heading (two lines); long text is shortened |\n| Daily weather/clothing/tickets/things to bring | `update_day.daily_brief`, max 500; empty/null clears | Top 今日提醒; empty content is hidden; independent weather requires `weather_enabled=true` and an actual forecast for the selected date/first located assignment |\n| Timed action with no map stop | `create_day_note` / `update_day_note`: text max 500, optional time | 当天备注 rows, including existing stored notes; long text expands in place |\n| Actual visit/route stop | `assign_place_to_day`, `update_assignment_time` | Ordered itinerary and route map |\n| Visit instructions | Both tools above write the same assignment `notes` | 本次安排 in the visit details |\n| Hotel date range | `create_accommodation` | Reservation data; an assignment is still needed for a route stop |\n| Packing / budget / unassigned reservation | Respective tools | Their own sections, not automatic day itinerary rows |\n\nDo not substitute a long title for daily_brief. Do not invent nearby POIs for location-free actions. Do not delete or duplicate existing notes to compensate for old clients. Notes require mini program 0.3.18+; check the user's installed version when visibility is disputed.\n\n`preview_day_view {tripId,dayId}` returns authored reminder, date/location for weather lookup, renderedNotes and ordered renderedAssignments. Weather is not fetched by this preview. It is a server-side content contract, not a screenshot; assignment details require places:read. `get_trip_summary.days[].notes` contains note entries while REST days use `notes_items`.\n\nWeather guidance: research current weather before authoring a brief, distinguish forecast from historical climate, and include source/date in text when useful. Do not invent a forecast outside the provider window. Clearing the brief hides it and does not enable weather; custom text stays exactly as authored until changed.\n\n### Optional day extras (0.3.18)\n\n- Day notes are grouped under “当天备注 · count”, collapsed by default. Expand to read; tap a note to edit/delete in place. Notes are not route/map stops. Empty notes and reminders have no content panel.\n- `update_day.weather_enabled` is an independent boolean, default false. Enable only when requested; clearing `daily_brief` never turns weather on. Dates beyond MET Norway's actual forecast (up to about nine days), missing coordinates, or unavailable forecasts show no weather card.\n- Weather is cached on the client for the day and shared by rounded location on the server. MET Norway attribution and update time are shown. Authored text is not automatically refreshed.\n- Use `preview_day_view.notesPresentation` to explain collapsed state; `renderedNotes` means available after expansion, not all rows visible on first opening. Preview does not fetch weather or prove a screenshot.\n- Keep each note as one action/supporting item (text <=500); `text` is the editable label/body, so no separate name field is needed. Assignment notes from assign/update tools refer to the same visit-specific field. Packing and budget remain in their own tabs; do not duplicate them as itinerary stops.\n\nFile v1.1.1:references/workflows.md\n\n# Research and synchronization workflows\n\n## Research a new trip\n\n1. Collect hard constraints: travelers, ages, accessibility, origin, dates, fixed bookings, work/school windows, budget and transport.\n2. Verify time-sensitive claims online. Prefer official attraction, venue, carrier, hotel, government and map sources.\n3. Use `search_place` for each real destination. In Mainland China pass `market: \"china\"` and an administrative region such as `深圳` or `清远`; overseas pass `market: \"global\"` and a two-letter country code such as `JP` or `FR`.\n4. Design each day around geography, opening windows, heat/rain, meals, rest and transfer buffers. Extract every planned POI/activity into `expectedAssignmentsByDate`; do not leave locations only in narrative text.\n5. Mark every item as confirmed, recommended, optional or pending confirmation.\n6. Preview the plan before creating data.\n\n## Create or update a trip\n\n1. `list_trips` and normalize titles/dates to detect an existing trip.\n2. Create only when no match exists; otherwise use the current trip ID.\n3. `get_trip_summary` and map its day IDs to ISO dates.\n4. Create/reuse places, then assign every expected POI/activity to the correct day with start/end time, duration, transport mode and assignment notes. New place: `create_and_assign_place`; existing place: `assign_place_to_day`.\n5. Add reservations/accommodations only from evidence. Accommodation tools create a date range, not a daily assignment; if the hotel/check-in is part of the visible daily plan, also assign the hotel place to that day.\n6. Add costs as estimates unless receipts/orders establish actual values.\n7. Add packing items for traveler and destination needs.\n8. Add todos for unresolved bookings, deadlines, safety checks and missing documents. Use due dates and priority.\n9. Add collaboration notes for cross-cutting instructions that must remain visible.\n10. When adding a trip cover or place image, upload the image, write the returned authenticated `file.url` to `trip.cover_image` or `place.image_url`, and verify both values on readback. A successful file upload without the entity field is incomplete.\n11. Read back and compare each date's normalized assignment place names/IDs to `expectedAssignmentsByDate`. Any planned day with zero assignments, any expected place missing, or any POI present only in day-note text is a failed synchronization. Fix it before reporting completion. Intentional rest/location-free travel days must be marked explicitly.\n\nSave the full expected checklist as a JSON object when using the bundled audit command. An empty array explicitly marks a rest/location-free day:\n\n```json\n{\n \"2026-09-23\": [\"金门大桥\", \"Presidio\"],\n \"2026-09-24\": [],\n \"2026-09-25\": [\"Stanford University\", \"Apple Park Visitor Center\"]\n}\n```\n\nRun `node scripts/trek-mcp.mjs audit-plan <trip-id> /absolute/path/expected-assignments.json`. Exit code `2` means at least one date is missing, has missing assignments, or contains unexpected assignments; do not report completion.\n\n## Collaborative planning\n\nUse proposals before formal itinerary writes when a group has not decided:\n\n1. `create_trip_proposal`\n2. `react_trip_proposal`\n3. `decide_trip_proposal` only after the owner confirms\n4. `schedule_trip_proposal` only after choosing a day\n5. `list_trip_proposals` to verify final status\n\nUse polls for broad group choices and proposals for candidate places that may become scheduled items.\n\n### Add one pending place\n\nPrefer the semantic tool; do not assemble this from primitive writes:\n\n1. If the place is already in 收藏, obtain its ID from `list_places`.\n2. Call `add_pending_place({ tripId, placeId, title, ... })`; `placeId` is preferred\n for an existing saved place and prevents duplicate data.\n For a new candidate, pass `description`, `imageUrl`, `website`, `phone` and\n `placeNotes` when verified. Keep `reason` short and specific to this trip.\n3. Require `persisted: true`, `destination: \"pending\"`, and an `open` proposal\n in the returned readback.\n4. To remove it from active discussion but keep it saved, call\n `move_pending_place_to_saved({ tripId, proposalId })` after user confirmation.\n\nDo not use `create_place`: a saved place is not the mini program's “待决定” item.\nDo not report success without the semantic tool's persisted readback.\n\n## Change an existing trip safely\n\nCreate a diff with:\n\n- current value\n- proposed value\n- reason/source\n- affected reservations, costs, members and travel time\n\nGet confirmation before deleting, moving fixed bookings, changing financial data, or replacing confirmed reservations. Apply changes in dependency order and read back after each group.\n\n## Daily briefing\n\nRead the trip summary, today's day, reservations, todos and weather. Return:\n\n- next fixed event and departure deadline\n- route and buffer\n- weather/clothing\n- tickets/documents\n- meal plan\n- unresolved high-priority todo\n\nDo not write anything for a briefing unless the user explicitly asks to update the trip.\n\n## Evidence policy\n\n- A map result establishes name/address/coordinates, not quality or current opening hours.\n- A social post is a recommendation signal, not proof of current policy.\n- A reservation is confirmed only with user/order evidence.\n- If exact time, address, price, phone or booking status is unknown, preserve the uncertainty in a todo or note.\n\n## Verify notes and daily reminders\n\nAfter synchronization, use `trek day-view TRIP_ID DAY_ID` to read the 0.3.18+ display contract. `audit-plan` verifies assignment names only; it does not verify notes, reminders, client version or screenshots.\n\nFor timed notes, create an expected JSON file (no real user content in shared examples):\n\n```json\n{\"2026-10-01\":[{\"text\":\"带好演出门票和证件\",\"time\":\"18:00\"}]}\n```\n\nRun `trek audit-notes TRIP_ID expected-notes.json`. Missing, unexpected or duplicate text/time entries fail the audit (exit 2). Read back the exact daily brief through `day-view`; do not write again simply because an old client cannot show it.\n\nFile v1.1.1:skill-card.md\n\n## Description:\n\nTrek Agent Control helps WorkBuddy and other agents use an authenticated Trek Agent Key to research travel, inspect Trek trip data, and safely synchronize itinerary, reservation, budget, packing, todo, attachment, and proposal updates back to the Trek mini program.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[super21-bat](https://clawhub.ai/user/super21-bat)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and developers use this skill to let an agent plan travel, read current Trek trip state, preview proposed changes, and write structured itinerary data back to the Trek mini program with readback checks.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill installs mutable global CLI code and connects to a third-party Trek service.\n\nMitigation: Install only if the Trek service and publisher are trusted; prefer a pinned release or verified package over the mutable branch install, and confirm the exact endpoint and commands before setup.\n\nRisk: A persistent Trek Agent Key can grant broad access to read and modify real trip data.\n\nMitigation: Create a separate key for each agent, store it only in a runtime secret manager or protected config, and revoke it when no longer needed or if exposed.\n\nRisk: Agent writes can affect reservations, costs, deletes, proposal decisions, and schedule changes.\n\nMitigation: Use the skill's previews, confirmation steps, small batches, and readback checks before allowing high-impact writes.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/super21-bat/skills/trek-agent-control)\n- [Runtime configuration](references/configuration.md)\n- [Dynamic tool and field guide](references/field-guide.md)\n- [Research and synchronization workflows](references/workflows.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands and JSON configuration snippets]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include change previews, diagnostics, and readback checks before or after writes.]\n\n## Skill Version(s):\n\n1.1.1 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.1.0: 6 files, 18061 bytes\n\nFiles: references/configuration.md (4307b), references/field-guide.md (12254b), references/workflows.md (6035b), skill-card.md (2568b), SKILL.md (10832b), _meta.json (137b)\n\nFile v1.1.0:SKILL.md\n\n---\nname: trek-agent-control\ndescription: 配套 Trek 微信旅行小程序的自动化 Skill，主要面向 WorkBuddy，也兼容 Codex、Claude、OpenClaw、Hermes 等 Agent。通过认证的远程 MCP 研究国内外目的地、读取或修改行程，并把日程、地点、预订、住宿、费用、清单、待办、附件和协作提案安全同步回小程序。Use when WorkBuddy or another agent needs to plan travel, inspect Trek data, synchronize structured itinerary fields, upload tickets, or run safe diagnostics with a user-provided Trek Agent Key.\n---\n\n# Trek Agent Control\n\nControl the user's real Trek data through MCP. Treat web research and Trek synchronization as separate phases: research first, then show a concrete change preview, then write and read back.\n\n## Product workspace\n\nTrek 微信旅行小程序是用户查看、编辑、导航、分享和协作的行程工作区；本\nSkill 是它的 Agent 自动化层。用户先在小程序创建行程和独立 Agent Key，\nAgent 再研究资料并把结构化结果同步回同一行程。不要创建与小程序脱离的第二份\n行程数据，也不要把聊天回答误报成已同步。\n\n![微信扫码打开 Trek 旅行小程序](https://raw.githubusercontent.com/super21-bat/trek-agent-control/main/assets/trek-miniapp-code.png)\n\n当前二维码为测试阶段入口，是否可直接进入以微信侧体验权限为准。\n\n## Connect\n\n1. Never paste the `trek_` key into files, prompts, logs, screenshots, commits, or shell history intended for sharing.\n2. Prefer the agent's native Streamable HTTP MCP support. Configure:\n - URL: `https://api.superd.fun/mcp`\n - Header: `Authorization: Bearer <user-key>`\n3. Use the Trek CLI to install/sync this Skill, verify the connection, and diagnose failures:\n\n```bash\nnpm install -g https://github.com/super21-bat/trek-agent-control/archive/refs/heads/main.tar.gz\ntrek config init --api-key 'trek_...' --url 'https://api.superd.fun/mcp'\ntrek skill sync --global\ntrek doctor\n```\n\nThe mini program presents this to ordinary users as two steps: copy once, then send the copied bundle to WorkBuddy. WorkBuddy should complete installation, configuration, Skill sync, and `doctor` without asking the user to run commands manually. Treat the whole bundle as a secret. If native remote MCP is unavailable or unreliable, execute all operations through `trek`; it calls the same MCP endpoint. Read [references/configuration.md](references/configuration.md) for runtime details.\n\n## Fast paths for common user requests\n\nDo not load the large-planning workflow for these small writes. Use the exact\nrecipe, then stop:\n\n- “加到待定/候选地点”：resolve the trip with `list_trips`, then run\n `trek add-pending <trip-id> <title> [--place-id <saved-place-id>]` or call\n native MCP `add_pending_place`. If the place already exists in 收藏, pass its\n `placeId`; the server links/reuses that place instead of creating a duplicate.\n For a newly researched candidate, include a short stable `description` and a\n representative `imageUrl` when available; put the trip-specific recommendation\n in `reason`. A name plus address alone is not enough context for group voting.\n `apply_trip_change` with `action: \"add_pending\"` remains a compatible fallback.\n Never use `create_place` for 待选/候选/待决定.\n- “设置行程封面”：run `trek set-cover <trip-id>\n <absolute-image>` or call native MCP `apply_trip_change` with `action:\n \"set_cover\"`. The server owns upload, binding and readback as one semantic\n operation; do not compose primitive upload/update calls when this tool exists.\n\nFor either fast path, if readback fails, report “未同步” and the exact failed\nstage. Never continue into unrelated planning or claim the mini program will\neventually refresh.\n\n## Mandatory workflow\n\n1. Run `doctor` or native `tools/list`. Stop on authentication, network, or missing-tool failure.\n2. Read existing state with `list_trips` and `get_trip_summary`. Never assume a trip ID. Use top-level `places[]` for every trip place, including unassigned places; use `packing.bags[]` for all bags, including empty bags.\n3. Research current facts with primary/official sources first. Separate confirmed facts, recommendations, and unresolved items.\n4. Build a dated plan and an `expectedAssignmentsByDate` checklist containing every POI/activity that must appear in the mini program. Use exact local dates and times. Do not invent reservations, confirmation numbers, phone numbers, opening hours, prices, or addresses.\n5. Show the user a compact change preview before destructive, bulk, financial, membership, proposal-decision, or rescheduling writes.\n6. Write in small batches. Reuse existing entities and detect duplicates by normalized name/date before creating.\n7. Every real location visit must be a Place plus Assignment. Use `create_and_assign_place` for a new POI and `assign_place_to_day` for an existing one. Location-free actions (wake up, bring tickets, meet a friend) can be timed day notes: visible in the day-notes section in mini program 0.3.17+, but not map stops. Never fabricate a POI just to make a note visible; older clients must upgrade.\n8. Model accommodation separately. `create_place_accommodation`/`create_accommodation` create a lodging date range but no visible day assignment. If a hotel or check-in is in the daily plan, also assign its place to that day.\n9. Populate only meaningful fields, but use the complete model when relevant: trip dates/description, days, places and coordinates, assignment start/end/duration/transport/notes, reservations, accommodations, costs, packing, todos, collaboration notes, proposals and members.\n10. Read back with `get_trip_summary` plus the relevant `list_*` tool. Compare `expectedAssignmentsByDate` to actual `days[].assignments` by date and normalized place name/ID, not only counts. A planned day must not have zero assignments; explicitly document intentional rest/location-free travel days.\n11. Do not report synchronization complete while any expected assignment is missing or only mentioned in a day note. Repair the gap or disclose it to the user.\n12. Report what changed, what remains uncertain, and what the user must confirm.\n\nRead [references/workflows.md](references/workflows.md) for detailed planning and synchronization recipes. Read [references/field-guide.md](references/field-guide.md) before a large or unfamiliar write.\n\n## CLI\n\n```bash\ntrek doctor\ntrek update --check\ntrek tools place\ntrek call list_trips '{\"include_archived\":false}'\ntrek summary 3\ntrek audit-plan 3 /absolute/path/expected-assignments.json\ntrek add-pending 3 '西湖游船' --reason '同行者表态后再排日程'\ntrek upload-file 3 /absolute/path/ticket.pdf --assignment 42 --description '景区电子票'\ntrek set-cover 3 /absolute/path/cover.jpg --description '行程封面'\ntrek rename-file 3 19 '金门大桥门票.pdf'\ntrek batch /absolute/path/actions.json\ntrek batch /absolute/path/actions.json --apply\ntrek smoke --allow-write-smoke\n```\n\n`doctor` reports local configuration, endpoint, credential presence, Skill integrity, authentication, live tool count, and trip readback. Failures include a category, hint, and next command; retain that structured output when diagnosing. `update --check` compares CLI versions; `update` upgrades the CLI and resynchronizes the Skill. `audit-plan` compares an expected JSON date-to-place mapping with live `days[].assignments` and exits non-zero on missing items. `add-pending` creates or reuses a candidate and verifies the open proposal by ID. `upload-file` reads a local attachment without printing its base64 and supports files up to 10 MB. `set-cover` uploads, binds, and verifies a visible trip cover as one command. `rename-file` changes only the display name and keeps the extension. `batch` is dry-run unless `--apply` is present. Applied actions always expose `ok`, `resourceType`, `resource`, `warnings`, and the original `result`; execution stops on the first failed action. It refuses high-risk tool names unless `--confirm-high-risk` is also present. `smoke` creates temporary data, exercises the proposal lifecycle, deletes it, and closes the MCP session.\n\n## Safety invariants\n\n- Treat the key as a password. Ask the user to revoke it immediately if exposed.\n- Never delete or overwrite real data during diagnostics. Use the bundled temporary smoke only.\n- Do not mark bookings confirmed without order evidence. Use `pending` or a todo for unresolved bookings.\n- Do not create fake coordinates. Use `search_place` with `market: \"china\"` plus `region` in Mainland China, or `market: \"global\"` plus an ISO `countryCode` for overseas trips. Preserve the returned provider IDs and coordinates.\n- For minors, medical needs, border crossings, flights, and tight transfers, add safety buffers and explicit adult-confirmation tasks.\n- Respect 429 responses. Do not disable server limits or fire requests in parallel; the bundled client retries with bounded backoff.\n- Static `trek_` keys currently grant broad user access. Create one per Agent, revoke unused keys, and prefer scoped OAuth when the target agent supports it.\n- Close every MCP session, including failed runs.\n\n## Failure handling\n\n- `401`: key missing, revoked, malformed, or sent without `Bearer`.\n- `403`: user lacks trip permission or scope; do not retry as another user.\n- `404`: wrong trip/entity ID or inaccessible resource; refresh state.\n- `429`: wait and retry sequentially; reduce batch size.\n- `isError: true`: treat as failed even if HTTP succeeded. Preserve the error text and stop dependent writes.\n- Unknown fields/tools: call `tools/list`; never guess a schema from an older document.\n\nWhen native MCP and the bundled client disagree, trust a fresh `tools/list` response and production readback.\n\n## Daily notes and reminders (mini program 0.3.17+)\n\n- Keep day titles short (about 25 characters). Use `update_day.daily_brief` for a user-authored weather/clothing/tickets/packing reminder, up to 500 characters; empty or null restores date-specific weather. `trek set-day-brief <trip-id> <day-id> @brief.txt` writes and reads back.\n- `create_day_note` stores a timed action in the visible day-notes section, without adding a map stop. These notes were invisible in 0.3.16 and older.\n- `trek day-view <trip-id> <day-id>` / `preview_day_view` returns the content contract and minimum client version, not a screenshot or proof the user installed that version. Compare notes using `trek audit-notes <trip-id> expected-notes.json`; `audit-plan` checks assignments only.\n- Use the current authorized tool schema. With semantic profile, discover these advanced tools and reconnect using full profile if needed. For exact fields and boundaries read [references/field-guide.md](references/field-guide.md).\n\nFile v1.1.0:_meta.json\n\n{\n \"ownerId\": \"kn70axt20cegjzmp4nnsrs1fmx82khb0\",\n \"slug\": \"trek-agent-control\",\n \"version\": \"1.1.0\",\n \"publishedAt\": 1789871965648\n}\n\nFile v1.1.0:references/configuration.md\n\n# Runtime configuration\n\n## WorkBuddy first\n\nThe mini program gives the user only two steps: tap “创建并复制”, then send the copied bundle to WorkBuddy. WorkBuddy must complete the commands, Skill sync, and `doctor` itself. Do not ask a non-technical user to choose between MCP and CLI.\n\nUse native Streamable HTTP MCP when WorkBuddy exposes it. Otherwise use the CLI fallback from the same copied bundle.\n\n## Native Streamable HTTP MCP\n\nUse the runtime's secret manager for `TREK_MCP_TOKEN`. The common configuration shape is:\n\n```json\n{\n \"mcpServers\": {\n \"trek\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://api.superd.fun/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${TREK_MCP_TOKEN}\"\n }\n }\n }\n}\n```\n\nRuntimes may spell the type `http`, `streamable_http`, or `streamable-http`. Do not copy the key into a shared JSON file if that runtime cannot expand environment variables.\n\n## Universal shell fallback\n\nRequirements: Node.js 18 or newer and outbound HTTPS.\n\n```bash\nnpm install -g https://github.com/super21-bat/trek-agent-control/archive/refs/heads/main.tar.gz\ntrek config init --api-key 'trek_...' --url 'https://api.superd.fun/mcp'\ntrek skill sync --global\ntrek doctor\n```\n\nThe mini program provides the endpoint, commands, and one-time key in one copied Agent access bundle. Do not split or repost that bundle. `trek config init` stores the key in `~/.trek/config.json` with mode `0600` on POSIX systems.\n\nThe public bootstrap source is the repository's stable branch tarball. Do not use\nthe `github:owner/repo` npm shorthand for global installation: some npm versions\nlink it to a temporary clone and leave a broken `trek` command after cleanup.\nAfter `@trek-cn/cli` is published to npm, the shorter\n`npm install -g @trek-cn/cli@latest` command may replace the GitHub install.\n\nOptional environment overrides:\n\n- `TREK_CONFIG`: custom config path.\n- `TREK_MCP_TOKEN`: override the stored key.\n- `TREK_MCP_URL`: defaults to `https://api.superd.fun/mcp`.\n- `TREK_MCP_TIMEOUT_MS`: per-request timeout, default `20000`.\n- `TREK_MCP_RETRIES`: retry count for 429/502/503/504 and network errors, default `7`.\n\n## Other compatible agents\n\nCodex, Claude, OpenClaw, Hermes and other terminal-capable agents follow the same connection sequence:\n\n1. Install the CLI and run `trek skill sync --global`.\n2. Run `trek config init` with the user's one-time key.\n3. Add the native MCP block when supported.\n4. Otherwise allow the agent to execute `trek ...`.\n5. Run `doctor`; require `ok: true`, a protocol version, a positive tool count, and successful `list_trips` before giving write access.\n\n`trek skill sync --global` delegates common Agent locations to the installed\nSkills runner. Trek also installs real copies into detected WorkBuddy\n`~/.workbuddy/skills/trek-agent-control` and Hermes\n`~/.hermes/skills/trek-agent-control` directories. Start a new WorkBuddy task or\nrestart the Hermes gateway after syncing. A cross-directory symlink is not\nenough for Hermes: it resolves symlinks before enforcing its trusted Skill\ndirectory.\n\nHermes native remote MCP support is optional. Hermes installations that include\nthe MCP extra may configure the Streamable HTTP endpoint directly; installations\nwithout it can use the Trek CLI fallback with the same capabilities. Trek must\nnot install or modify Hermes' Python environment automatically. Follow the\nHermes version's own installation instructions when native MCP is desired, and\ndo not hard-code another user's virtual-environment path.\n\n## Diagnostics\n\nRun `trek doctor` first. Its failure category determines the next check:\n\n- `configuration`: inspect `trek config get`, then re-run `config init`.\n- `network`: verify HTTPS/DNS/proxy access to the endpoint.\n- `authentication`: create a fresh Agent Key, initialize it, and revoke the old key.\n- `permission`: refresh `list_trips`; do not retry against another user's trip.\n- `rate_limit`: wait and retry sequentially.\n- `capability`: run `trek skill sync --global`, then inspect `trek tools`.\n\n## Key rotation\n\nCreate one key per external agent so access can be revoked independently. After rotating:\n\n1. Replace the secret in that runtime only.\n2. Run `doctor` with the new key.\n3. Revoke the old key in the mini program.\n4. Confirm the old key returns 401.\n\nFile v1.1.0:references/field-guide.md\n\n# Dynamic tool and field guide\n\nAlways discover the live schemas with `tools/list`. The server evolves and the live schema is authoritative.\n\n## Core read path\n\n- `list_trips`: identify accessible trips.\n- `get_trip_summary`: trip, top-level deduplicated places, days, assignments, reservations, accommodations, budget, packing items and bags, todos, notes and members.\n- Relevant `list_*`: obtain full records before editing or deleting.\n\n## Common write groups\n\n- Trip: `create_trip`, `update_trip`, `delete_trip`.\n- Schedule: day, place and assignment tools.\n- Search: `search_place` with `query`, explicit `market` (`china` or `global`), and either a Mainland `region` or overseas ISO `countryCode`.\n- Decisions: `*_trip_proposal` and collaboration polls.\n- Logistics: reservation and accommodation tools.\n- Money: budget item, member, payer and settlement tools.\n- Preparation: packing and todo tools.\n- Collaboration: note, poll and chat tools when enabled.\n\n## Idempotency keys for agent reasoning\n\nThe MCP tools do not promise a universal idempotency token. Before creating, compare:\n\n- trip: normalized title + start/end dates\n- place: normalized name + address + coordinates\n- assignment: day ID + place ID + start time\n- reservation: type + title + linked day/place\n- accommodation: place + start/end day\n- cost: category + name + amount\n- packing/todo: normalized name\n- note: normalized title\n\nReuse/update a match instead of creating a duplicate.\n\n## Saved and pending place visibility\n\n- 收藏 and 待决定 share the same place facts: name, address, description, notes,\n image, website and phone. Moving between the two states must preserve them.\n- For a researched candidate, `description` answers “what is this place”; `reason`\n answers “why consider it for this trip”. Do not put both meanings into one field.\n- Include a representative image only when its source is usable and stable. Never\n fabricate a photo URL. A candidate without verified media may omit `imageUrl`,\n but should still have a concise description whenever facts are available.\n- Verify rich candidate fields with `list_trip_proposals`; verify 收藏 fields with\n `list_places`. Do not report synchronization if the description was dropped.\n\n## Itinerary detail and ticket fields\n\nThe mini program opens an itinerary detail sheet when the user taps a day assignment. To make agent-written plans useful there:\n\n- Route fields by ownership instead of putting everything into one note:\n\n| User meaning | MCP field/tool | Mini program visibility |\n| --- | --- | --- |\n| Instructions for this specific visit | `update_assignment_time.notes` | `本次安排` in the assignment detail |\n| Stable POI introduction | `create_place.description` / `update_place.description` | `地点信息 → 地点介绍`, shown automatically when non-empty |\n| Reusable POI caveat | `create_place.notes` / `update_place.notes` | `地点信息 → 地点备注`, shown automatically when non-empty |\n| Address and contact | place `address`, `phone`, `website` | Primary address facts plus direct phone/website actions |\n| Trip cover | `upload_trip_file`, then `update_trip.cover_image` with the returned `file.url` | Trip list, Home hero and trip detail cover |\n| Place image | `upload_trip_file` with `place_id`, then `create_place.image_url` / `update_place.image_url` with the returned `file.url` | Place detail image and Home fallback image |\n| Booked time and voucher facts | reservation `reservation_time`, `reservation_end_time`, `confirmation_number`, `notes`, `url` | `预订信息`, linked through `assignment_id` |\n| Expense | budget `name`, `total_price`, `category`, `currency`, `expense_date`, `payers`, `member_ids`, `note` | Top-level `费用` tab |\n| Ticket image or PDF | `upload_trip_file` / `link_trip_file` with `assignment_id` or `reservation_id` | `票据与附件` in the assignment detail |\n\n- Put arrival instructions, meeting points, age restrictions, what to bring, and other readable guidance in the assignment or reservation `notes`.\n- Use `update_assignment_time.notes` for guidance specific to this visit. Use `update_place.notes` only for reusable place notes, and `update_place.description` for the public place introduction.\n- Keep the UI visibility contract intact: assignment `notes` appear as \"本次安排\"; place `address` appears in the primary facts; place `phone` and `website` appear as direct actions. Since mini program 0.2.18, place `description` and `notes` are shown directly in \"地点信息\" when at least one exists; the section is hidden when both are empty.\n- Treat every written field as a readback obligation. After `create_place`, `create_and_assign_place`, `update_place`, or `update_assignment_time`, call `list_places` or `get_trip_summary` and verify the exact value. Do not write opaque data to fields that the user cannot reach in the mini program.\n- Create a reservation for a ticket, restaurant, tour, study activity, or event and link it with `assignment_id`.\n- Use `confirmation_number` only for a real order/booking code.\n- Use `reservation_time` and `reservation_end_time` for the booked time window.\n- Use `url` for the official voucher, ticket, or booking page.\n- Uploaded images and PDFs remain trip files. Link them to the reservation or assignment instead of placing base64 data or long image URLs in notes.\n- For a visible trip cover or place image, upload the image as a trip file, persist the returned authenticated relative `file.url` in `cover_image` or `image_url`, then read back both the file link and entity field. Uploading bytes alone does not make an image visible.\n- Use `upload_trip_file` for an attachment up to 10 MB, or the bundled `upload-file` command so raw base64 never appears in terminal output. Use `list_trip_files` for readback, `link_trip_file` to add another relationship, and `trash_trip_file` to remove it from the active trip.\n- Keep the reservation `pending` until the user supplies booking evidence; then update it to `confirmed`.\n- The mini program's \"预订\" tab is the single editable reservation inventory. Legacy `day_assignments.reservation_*` fields are read-only compatibility data; do not write new booking data there.\n- Use fixed budget category keys such as `accommodation`, `food`, `transport`, `activities`, `shopping`, or `other`. Record `expense_date`, currency and payers when known.\n\n## Packing checklist fields\n\n- Prefer the mini program's three low-effort built-in packing locations: `随身必带`, `衣物`, and `日用健康`. “自定义” is an action, not a category name: when the user needs a special grouping, write the actual reusable category name.\n- Do not ask the user for a category when the item name makes it obvious. Infer it: identity documents, phone accessories, wallet and keys -> `随身必带`; clothing and footwear -> `衣物`; toiletries, sun protection, medicine, umbrella and tissues -> `日用健康`. If there is no stronger match and the user did not request a special grouping, omit `category` and let the service use the safe `随身必带` default.\n- For a real trip-specific need, pass a concise custom category such as `露营装备`, `摄影器材`, or `儿童用品`. Once one item uses that category, the mini program offers it directly for later items in the same trip and groups all same-category items together. Reuse the exact existing category spelling from readback instead of creating near-duplicates.\n- Legacy English/Chinese categories and historical `其他` remain readable. Do not create a category named after a place such as “为酒店准备”; use a reusable packing concept instead.\n- Always send `quantity` when the user needs more than one item. Valid values are integers from 1 to 999.\n- After `create_packing_item` or `update_packing_item`, read back the item and verify `name`, `category`, and `quantity`; do not report a successful packing update from the write response alone.\n- Reuse or update an existing normalized name instead of creating a duplicate, unless the same item genuinely belongs to different people or bags.\n\n## Batch file format\n\n`scripts/trek-mcp.mjs batch` accepts a JSON array:\n\n```json\n[\n {\n \"label\": \"Inspect current trips\",\n \"tool\": \"list_trips\",\n \"arguments\": { \"include_archived\": false }\n },\n {\n \"label\": \"Search official hotel POI\",\n \"tool\": \"search_place\",\n \"arguments\": { \"query\": \"清远狮子湖喜来登度假酒店\", \"market\": \"china\", \"region\": \"清远\", \"countryCode\": \"CN\" }\n }\n]\n```\n\nWithout `--apply`, the client prints the planned calls and performs no tools. With `--apply`, calls run sequentially and stop on the first error. Every result has the same compatibility envelope: `ok`, `resourceType`, `resource`, `warnings`, and the original tool payload in `result`. Tool names containing delete/remove/decide/schedule/settle/restore/rotate require `--confirm-high-risk`.\n\n## Readback checklist\n\nVerify:\n\n- exact trip dates and day count\n- actual assignments by date/place equal the pre-write `expectedAssignmentsByDate` checklist\n- every detailed-plan POI/activity is a visible assignment, not only day-note text\n- any planned day with zero assig\n\nArchive v1.0.5: 6 files, 16613 bytes\n\nFiles: references/configuration.md (4307b), references/field-guide.md (10156b), references/workflows.md (5369b), skill-card.md (3139b), SKILL.md (9663b), _meta.json (137b)\n\nArchive v1.0.4: 6 files, 15864 bytes\n\nFiles: references/configuration.md (4307b), references/field-guide.md (9374b), references/workflows.md (5003b), skill-card.md (3115b), SKILL.md (9234b), _meta.json (137b)\n\nArchive v1.0.3: 7 files, 103058 bytes\n\nFiles: assets/trek-miniapp-code.png (87378b), references/configuration.md (4307b), references/field-guide.md (8847b), references/workflows.md (5003b), skill-card.md (2954b), SKILL.md (9234b), _meta.json (137b)\n\nArchive v1.0.2: 6 files, 13155 bytes\n\nFiles: references/configuration.md (2888b), references/field-guide.md (6744b), references/workflows.md (4231b), skill-card.md (3129b), SKILL.md (7650b), _meta.json (137b)\n\nArchive v1.0.1: 6 files, 12657 bytes\n\nFiles: references/configuration.md (2888b), references/field-guide.md (6744b), references/workflows.md (4231b), skill-card.md (3506b), SKILL.md (6978b), _meta.json (137b)\n\nArchive v0.1.0: 19 files, 38862 bytes\n\nFiles: .github (0b), .github/workflows (0b), .github/workflows/release.yml (940b), .gitignore (37b), agents (0b), agents/openai.yaml (251b), LICENSE (34523b), MAINTAINING.md (7946b), package.json (771b), references (0b), references/configuration.md (2888b), references/field-guide.md (6744b), references/workflows.md (4231b), scripts (0b), scripts/trek-mcp.mjs (27274b), SKILL.md (6912b), tests (0b), tests/trek-cli.test.mjs (2169b), _meta.json (137b)","readmeExcerpt":"Skill: trek-agent-control Owner: super21-bat Summary: 配套 Trek 微信旅行小程序的自动化 Skill，主要面向 WorkBuddy，也兼容 Codex、Claude、OpenClaw、Hermes 等 Agent。通过认证的远程 MCP 研究国内外目的地、读取或修改行程，并把日程、地点、预订、住宿、费用、清单、待办、附件和协作提案安全同步回小程序。Use when WorkBuddy or another agent needs to plan travel, inspect Trek data, synchronize structured itinerary fields, upload tickets, or run safe diagnostics with a user-provided Trek Agent Key. Tags: latest:1.1.3 Ve","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"npm install -g https://github.com/super21-bat/trek-agent-control/archive/refs/heads/main.tar.gz\ntrek config init --api-key 'trek_...' --url 'https://api.superd.fun/mcp'\ntrek skill sync --global\ntrek doctor"},{"language":"bash","snippet":"trek doctor\ntrek update --check\ntrek tools place\ntrek call list_trips '{\"include_archived\":false}'\ntrek summary 3\ntrek audit-plan 3 /absolute/path/expected-assignments.json\ntrek add-pending 3 '西湖游船' --reason '同行者表态后再排日程'\ntrek upload-file 3 /absolute/path/ticket.pdf --assignment 42 --description '景区电子票'\ntrek set-cover 3 /absolute/path/cover.jpg --description '行程封面'\ntrek rename-file 3 19 '金门大桥门票.pdf'\ntrek batch /absolute/path/actions.json\ntrek batch /absolute/path/actions.json --apply\ntrek smoke --allow-write-smoke"},{"language":"json","snippet":"{\n \"mcpServers\": {\n \"trek\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://api.superd.fun/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${TREK_MCP_TOKEN}\"\n }\n }\n }\n}"},{"language":"bash","snippet":"npm install -g https://github.com/super21-bat/trek-agent-control/archive/refs/heads/main.tar.gz\ntrek config init --api-key 'trek_...' --url 'https://api.superd.fun/mcp'\ntrek skill sync --global\ntrek doctor"},{"language":"json","snippet":"[\n {\n \"label\": \"Inspect current trips\",\n \"tool\": \"list_trips\",\n \"arguments\": { \"include_archived\": false }\n },\n {\n \"label\": \"Search official hotel POI\",\n \"tool\": \"search_place\",\n \"arguments\": { \"query\": \"清远狮子湖喜来登度假酒店\", \"market\": \"china\", \"region\": \"清远\", \"countryCode\": \"CN\" }\n }\n]"},{"language":"json","snippet":"{\n \"2026-09-23\": [\"金门大桥\", \"Presidio\"],\n \"2026-09-24\": [],\n \"2026-09-25\": [\"Stanford University\", \"Apple Park Visitor Center\"]\n}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: trek-agent-control\ndescription: 配套 Trek 微信旅行小程序的自动化 Skill，主要面向 WorkBuddy，也兼容 Codex、Claude、OpenClaw、Hermes 等 Agent。通过认证的远程 MCP 研究国内外目的地、读取或修改行程，并把日程、地点、预订、住宿、费用、清单、待办、附件和协作提案安全同步回小程序。Use when WorkBuddy or another agent needs to plan travel, inspect Trek data, synchronize structured itinerary fields, upload tickets, or run safe diagnostics with a user-provided Trek Agent Key.\n---\n\n# Trek Agent Control\n\nControl the user's real Trek data through MCP. Treat web research and Trek synchronization as separate phases: research first, then show a concrete change preview, then write and read back.\n\n## Product workspace\n\nTrek 微信旅行小程序是用户查看、编辑、导航、分享和协作的行程工作区；本\nSkill 是它的 Agent 自动化层。用户先在小程序创建行程和独立 Agent Key，\nAgent 再研究资料并把结构化结果同步回同一行程。不要创建与小程序脱离的第二份\n行程数据，也不要把聊天回答误报成已同步。\n\n![微信扫码打开 Trek 旅行小程序](https://raw.githubusercontent.com/super21-bat/trek-agent-control/main/assets/trek-miniapp-code.png)\n\n当前二维码为测试阶段入口，是否可直接进入以微信侧体验权限为准。\n\n## Connect\n\n1. Never paste the `trek_` key into files, prompts, logs, screenshots, commits, or shell history intended for sharing.\n2. Prefer the agent's native Streamable HTTP MCP support. Configure:\n - URL: `https://api.superd.fun/mcp`\n - Header: `Authorization: Bearer <user-key>`\n3. Use the Trek CLI to install/sync this Skill, verify the connection, and diagnose failures:\n\n```bash\nnpm install -g https://github.com/super21-bat/trek-agent-control/archive/refs/heads/main.tar.gz\ntrek config init --api-key 'trek_...' --url 'https://api.superd.fun/mcp'\ntrek skill sync --global\ntrek doctor\n```\n\nThe mini program presents this to ordinary users as two steps: copy once, then send the copied bundle to WorkBuddy. WorkBuddy should complete installation, configuration, Skill sync, and `doctor` without asking the user to run commands manually. Treat the whole bundle as a secret. If native remote MCP is unavailable or unreliable, execute all operations through `trek`; it calls the same MCP endpoint. Read [references/configuration.md](references/configuration.md) for runtime details.\n\n## Fast paths for common user requests\n\nDo not load the large-planning workflow for these small writes. Use the exact\nrecipe, then stop:\n\n- “加到待定/候选地点”：resolve the trip with `list_trips`, then run\n `trek add-pending <trip-id> <title> [--place-id <saved-place-id>]` or call\n native MCP `add_pending_place`. If the place already exists in 收藏, pass its\n `placeId`; the server links/reuses that place instead of creating a duplicate.\n For a newly researched candidate, include a short stable `description` and a\n representative `imageUrl` when available; put the trip-specific recommendation\n in `reason`. A name plus address alone is not enough context for group voting.\n `apply_trip_change` with `action: \"add_pending\"` remains a compatible fallback.\n Never use `create_place` for 待选/候选/待决定.\n- “设置行程封面”：run `trek set-cover <trip-id>\n <absolute-image>` or call native MCP `apply_trip_change` with `action:\n \"set_cover\"`. The server owns upload, binding and readback as one"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn70axt20cegjzmp4nnsrs1fmx82khb0\",\n \"slug\": \"trek-agent-control\",\n \"version\": \"1.1.3\",\n \"publishedAt\": 1790151980760\n}"},{"path":"references/configuration.md","content":"# Runtime configuration\n\n## WorkBuddy first\n\nThe mini program gives the user only two steps: tap “创建并复制”, then send the copied bundle to WorkBuddy. WorkBuddy must complete the commands, Skill sync, and `doctor` itself. Do not ask a non-technical user to choose between MCP and CLI.\n\nUse native Streamable HTTP MCP when WorkBuddy exposes it. Otherwise use the CLI fallback from the same copied bundle.\n\n## Native Streamable HTTP MCP\n\nUse the runtime's secret manager for `TREK_MCP_TOKEN`. The common configuration shape is:\n\n```json\n{\n \"mcpServers\": {\n \"trek\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://api.superd.fun/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${TREK_MCP_TOKEN}\"\n }\n }\n }\n}\n```\n\nRuntimes may spell the type `http`, `streamable_http`, or `streamable-http`. Do not copy the key into a shared JSON file if that runtime cannot expand environment variables.\n\n## Universal shell fallback\n\nRequirements: Node.js 18 or newer and outbound HTTPS.\n\n```bash\nnpm install -g https://github.com/super21-bat/trek-agent-control/archive/refs/heads/main.tar.gz\ntrek config init --api-key 'trek_...' --url 'https://api.superd.fun/mcp'\ntrek skill sync --global\ntrek doctor\n```\n\nThe mini program provides the endpoint, commands, and one-time key in one copied Agent access bundle. Do not split or repost that bundle. `trek config init` stores the key in `~/.trek/config.json` with mode `0600` on POSIX systems.\n\nThe public bootstrap source is the repository's stable branch tarball. Do not use\nthe `github:owner/repo` npm shorthand for global installation: some npm versions\nlink it to a temporary clone and leave a broken `trek` command after cleanup.\nAfter `@trek-cn/cli` is published to npm, the shorter\n`npm install -g @trek-cn/cli@latest` command may replace the GitHub install.\n\nOptional environment overrides:\n\n- `TREK_CONFIG`: custom config path.\n- `TREK_MCP_TOKEN`: override the stored key.\n- `TREK_MCP_URL`: defaults to `https://api.superd.fun/mcp`.\n- `TREK_MCP_TIMEOUT_MS`: per-request timeout, default `20000`.\n- `TREK_MCP_RETRIES`: retry count for 429/502/503/504 and network errors, default `7`.\n\n## Other compatible agents\n\nCodex, Claude, OpenClaw, Hermes and other terminal-capable agents follow the same connection sequence:\n\n1. Install the CLI and run `trek skill sync --global`.\n2. Run `trek config init` with the user's one-time key.\n3. Add the native MCP block when supported.\n4. Otherwise allow the agent to execute `trek ...`.\n5. Run `doctor`; require `ok: true`, a protocol version, a positive tool count, and successful `list_trips` before giving write access.\n\n`trek skill sync --global` delegates common Agent locations to the installed\nSkills runner. Trek also installs real copies into detected WorkBuddy\n`~/.workbuddy/skills/trek-agent-control` and Hermes\n`~/.hermes/skills/trek-agent-control` directories. Start a new WorkBuddy task or\nrestart the Hermes gateway after syncing. A cross-directory symlink is not\nenough for Hermes: it"},{"path":"references/field-guide.md","content":"# Dynamic tool and field guide\n\nAlways discover the live schemas with `tools/list`. The server evolves and the live schema is authoritative.\n\n## Core read path\n\n- `list_trips`: identify accessible trips.\n- `get_trip_summary`: trip, top-level deduplicated places, days, assignments, reservations, accommodations, budget, packing items and bags, todos, notes and members.\n- Relevant `list_*`: obtain full records before editing or deleting.\n\n## Common write groups\n\n- Trip: `create_trip`, `update_trip`, `delete_trip`.\n- Schedule: day, place and assignment tools.\n- Search: `search_place` with `query`, explicit `market` (`china` or `global`), and either a Mainland `region` or overseas ISO `countryCode`.\n- Decisions: `*_trip_proposal` and collaboration polls.\n- Logistics: reservation and accommodation tools.\n- Money: budget item, member, payer and settlement tools.\n- Preparation: packing and todo tools.\n- Collaboration: note, poll and chat tools when enabled.\n\n## Idempotency keys for agent reasoning\n\nThe MCP tools do not promise a universal idempotency token. Before creating, compare:\n\n- trip: normalized title + start/end dates\n- place: normalized name + address + coordinates\n- assignment: day ID + place ID + start time\n- reservation: type + title + linked day/place\n- accommodation: place + start/end day\n- cost: category + name + amount\n- packing/todo: normalized name\n- note: normalized title\n\nReuse/update a match instead of creating a duplicate.\n\n## Saved and pending place visibility\n\n- 收藏 and 待决定 share the same place facts: name, address, description, notes,\n image, website and phone. Moving between the two states must preserve them.\n- For a researched candidate, `description` answers “what is this place”; `reason`\n answers “why consider it for this trip”. Do not put both meanings into one field.\n- Include a representative image only when its source is usable and stable. Never\n fabricate a photo URL. A candidate without verified media may omit `imageUrl`,\n but should still have a concise description whenever facts are available.\n- Verify rich candidate fields with `list_trip_proposals`; verify 收藏 fields with\n `list_places`. Do not report synchronization if the description was dropped.\n\n## Itinerary detail and ticket fields\n\nThe mini program opens an itinerary detail sheet when the user taps a day assignment. To make agent-written plans useful there:\n\n- Route fields by ownership instead of putting everything into one note:\n\n| User meaning | MCP field/tool | Mini program visibility |\n| --- | --- | --- |\n| Instructions for this specific visit | `update_assignment_time.notes` | `本次安排` in the assignment detail |\n| Start/end time for this visit | `create_and_assign_place.place_time` / `.end_time` for a new place; `assign_place_to_day.place_time` / `.end_time` for a saved place; `update_assignment_time` for later edits | Time shown on that day's assignment, not a reusable place field |\n| Stable POI introduction | `create_place.description` / `update_place."},{"path":"references/workflows.md","content":"# Research and synchronization workflows\n\n## Research a new trip\n\n1. Collect hard constraints: travelers, ages, accessibility, origin, dates, fixed bookings, work/school windows, budget and transport.\n2. Verify time-sensitive claims online. Prefer official attraction, venue, carrier, hotel, government and map sources.\n3. Use `search_place` for each real destination. In Mainland China pass `market: \"china\"` and an administrative region such as `深圳` or `清远`; overseas pass `market: \"global\"` and a two-letter country code such as `JP` or `FR`.\n4. Design each day around geography, opening windows, heat/rain, meals, rest and transfer buffers. Extract every planned POI/activity into `expectedAssignmentsByDate`; do not leave locations only in narrative text.\n5. Mark every item as confirmed, recommended, optional or pending confirmation.\n6. Preview the plan before creating data.\n\n## Create or update a trip\n\n1. `list_trips` and normalize titles/dates to detect an existing trip.\n2. Create only when no match exists; otherwise use the current trip ID.\n3. `get_trip_summary` and map its day IDs to ISO dates.\n4. Create/reuse places, then assign every expected POI/activity to the correct day with start/end time, duration, transport mode and assignment notes. New place: `create_and_assign_place`; existing place: `assign_place_to_day`. Pass `place_time`/`end_time` in that same creation call when known; both fields belong to the daily assignment. Use `update_assignment_time` only for later edits. A CLI batch can therefore contain one create action per visit without referencing a previous action's assignment ID.\n5. Add reservations/accommodations only from evidence. Accommodation tools create a date range, not a daily assignment; if the hotel/check-in is part of the visible daily plan, also assign the hotel place to that day.\n6. Add costs as estimates unless receipts/orders establish actual values.\n7. Add packing items for traveler and destination needs.\n8. Add todos for unresolved bookings, deadlines, safety checks and missing documents. Use due dates and priority.\n9. Add collaboration notes for cross-cutting instructions that must remain visible.\n10. When adding a trip cover or place image, upload the image, write the returned authenticated `file.url` to `trip.cover_image` or `place.image_url`, and verify both values on readback. A successful file upload without the entity field is incomplete.\n11. Read back and compare each date's normalized assignment place names/IDs to `expectedAssignmentsByDate`. Any planned day with zero assignments, any expected place missing, or any POI present only in day-note text is a failed synchronization. Fix it before reporting completion. Intentional rest/location-free travel days must be marked explicitly.\n\nSave the full expected checklist as a JSON object when using the bundled audit command. An empty array explicitly marks a rest/location-free day:\n\n```json\n{\n \"2026-09-23\": [\"金门大桥\", \"Presidio\"],\n \"2026-09-24\": [],\n \"2026-09-25\":"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"配套 Trek 微信旅行小程序的自动化 Skill，主要面向 WorkBuddy，也兼容 Codex、Claude、OpenClaw、Hermes 等 Agent。通过认证的远程 MCP 研究国内外目的地、读取或修改行程，并把日程、地点、预订、住宿、费用、清单、待办、附件和协作提案安全同步回小程序。Use when WorkBuddy or another agent needs to plan travel, inspect Trek data, synchronize structured itinerary fields, upload tickets, or run safe diagnostics with a user-provided Trek Agent Key. Skill: trek-agent-control Owner: super21-bat Summary: 配套 Trek 微信旅行小程序的自动化 Skill，主要面向 WorkBuddy，也兼容 Codex、Claude、OpenClaw、Hermes 等 Agent。通过认证的远程 MCP 研究国内外目的地、读取或修改行程，并把日程、地点、预订、住宿、费用、清单、待办、附件和协作提案安全同步回小程序。Use when WorkBuddy or another agent needs to plan travel, inspect Trek data, synchronize structured itinerary fields, upload tickets, or run safe diagnostics with a user-provided Trek Agent Key. Tags: latest:1.1.3 Ve","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":2003,"uniquenessScore":45,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T07:56:19.215Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T07:56:19.215Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T10:51:11.585Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}