Trek Agent Control

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install trek-agent-control
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 trek-agent-control。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

Trek Agent Control 是 Trek 微信旅行小程序的代理自动化层。它通过远程 MCP 端点或 Trek CLI 将兼容的代理（包括 WorkBuddy、Codex、Claude、OpenClaw 和 Hermes）连接到用户的真实行程数据。代理可以检查行程、研究目的地、更新结构化计划以及管理与旅行相关的信息，而无需创建与行程脱节的第二份副本。
该工作流专为安全、可验证的更改而设计，将研究与同步分离：检查现有数据、研究当前事实、预览重要更改、分小批次写入并回读结果。这使得 Trek Agent Control 成为 Openclaw Skills 用户的实用选择，他们既希望实现旅行规划自动化，又希望针对重复、虚构或未经验证的行程数据提供明确的安全保障。

应用场景

研究目的地并将确定的信息转化为带日期的结构化行程。
检查现有的 Trek 行程、地点、分配、住宿、费用、打包清单、待办事项和协作数据。
添加候选项目的地以供群组讨论，而不将其视为已确定的行程站点。
上传机票或预订附件、设置行程封面或重命名现有文件。
为非地图站点的操作添加带时间戳的日记和简明的提醒。
审核同步后期望的地点是否出现在正确的行程日期上。
使用 CLI 诊断连接、身份验证、缺少工具或同步问题。

工作原理

使用代理的 Streamable HTTP MCP 支持或捆绑的 CLI 连接到 Trek，将用户的密钥安全地作为 bearer 凭据提供。
运行 doctor 或使用 tools/list 发现可用工具；如果身份验证、网络访问或所需工具失败，则停止。
使用 list_trips 和 get_trip_summary 读取实时行程状态。解析正确的行程，而不是假设一个 ID。
研究当前的旅行事实，首选主要和官方来源。将确定的事实、建议和未解决的细节区分开来。
使用 expectedAssignmentsByDate 检查表构建带日期的计划。在高影响、批量、财务、会员资格、提案决策或重新安排写入之前显示更改预览。
分小批次应用更改，重复使用现有实体并检查重复项。为每次真实位置访问创建一个 Place 加 Assignment；对无位置操作使用日记。
回读行程摘要和相关列表。按日期以及规范化地点名称或 ID 将期望的地点与实际分配进行比较。
修复丢失的分配或披露不完整的同步。报告更改了什么、什么仍然不确定以及用户必须确认什么。

配置指南

在 Trek 小程序中创建一个行程和一个单独的 Agent Key。将此密钥视为密码；切勿将其泄露在共享提示词、文件、日志、截图、提交记录或 shell 历史记录中。
安装 Trek CLI 并使用用户的本地密钥初始化其连接：
npm install -g https://github.com/super21-bat/trek-agent-control/archive/refs/heads/main.tar.gz
trek config init --api-key '' --url 'https://api.superd.fun/mcp'
trek skill sync --global
trek doctor
或者，使用 URL https://api.superd.fun/mcp 和标头 Authorization: Bearer 配置原生的 Streamable HTTP MCP。
使用 trek doctor 确认连接和实时行程回读。诊断报告会报告配置、端点、凭据存在性、Skill 完整性、身份验证、工具数量和行程回读。
如果原生 MCP 不可用或不可靠，请使用调用同一 MCP 端点的 Trek CLI。在进行复杂写入之前，请参阅 references/configuration.md 了解运行时的详细信息，并参阅 references/workflows.md 或 references/field-guide.md。
立即吊销暴露的密钥。每个代理最好使用单独的密钥，吊销未使用的密钥，并在目标代理支持时使用作用域 OAuth。

数据架构

Trek Agent Control 读取和更新用户现有的 Trek 行程数据；它无意维护单独的行程数据库。该 skill 围绕以下实体和检查组织更改：
数据区域 代表什么 重要处理
行程和天数 行程日期、描述、天数标题和带日期的行程结构 从实时数据中解析行程；使用确切的本地日期和时间。
地点和分配 地点及其计划访问，包括坐标、时间、持续时间、交通和备注 每次真实访问都应该是一个 Place 加一个 Assignment。按日期检查分配，而不仅仅是总数。
待定地点和提案 用于考虑或群组投票的候选地点 使用待定地点流程；不要为候选人创建一个已确认的地点。
住宿 住宿及其日期范围 住宿记录不会自动创建可见的当天的 Assignment。当酒店或入住属于每日计划时，请添加一个。
预订、费用、打包和待办事项 预订详情, 费用, 包裹和物品以及任务 填写有意义的字段；在没有订单证据的情况下，请勿声称预订已确认。
备注和提醒 带时间的日间操作和可选的日间简介 备注不是地图站点。日间简介是纯文本，最多 500 个字符，并支持换行符。
附件和封面 机票等行程文件和行程封面图片 upload-file 支持最大 10 MB 的本地文件；set-cover 将上传、绑定和验证执行为一项操作。
协作 成员、协作备注和提案 在写入之前预览敏感的提案或成员资格更改。
对于批量操作，trek batch 接受一个 actions JSON 文件并且默认是预演（dry-run）模式；--apply 启用执行。trek audit-plan 将期望的 JSON 日期到地点映射与实时分配进行比较，并在缺少项目时以非零状态退出。trek audit-notes 检查期望的备注。CLI 输出和实时回读（而不仅仅是聊天文本）是报告同步成功的依据。

高级特性

支持远程 MCP 以及到达同一端点的 CLI 回退；可以在运行时发现工具，而不是从陈旧的架构中推断。
为添加或重用待定地点以及设置已验证的行程封面提供快速通道。
包括结构化诊断、版本检查、计划和备注审核、文件上传和重命名命令以及预演批量执行。
批量执行在第一个失败的操作时停止，并且对于高风险工具名称需要额外的确认标志。
提供一个临时数据冒烟测试，用于演练提案生命周期、删除其测试数据并关闭 MCP 会话。
支持带时间的日记、日间简介和日视图预览，同时将日记与地图分配和天气信息区分开来。
当当前架构支持时，处理带有天数偏移量和本地时间考量的跨午夜日程安排；在同步之前，请参阅专用的跨午夜参考资料。
针对凭据、速率限制、破坏性诊断、预订声明、位置坐标以及失败或部分写入应用安全控件——对于修改真实旅行数据的 Openclaw Skills 而言，这是实用的安全保障。

name: trek-agent-control 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.

Trek Agent Control

Control 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.

Product workspace

Trek 微信旅行小程序是用户查看、编辑、导航、分享和协作的行程工作区；本 Skill 是它的 Agent 自动化层。用户先在小程序创建行程和独立 Agent Key， Agent 再研究资料并把结构化结果同步回同一行程。不要创建与小程序脱离的第二份 行程数据，也不要把聊天回答误报成已同步。

当前二维码为测试阶段入口，是否可直接进入以微信侧体验权限为准。

Connect

Never paste the trek_ key into files, prompts, logs, screenshots, commits, or shell history intended for sharing.
Prefer the agent's native Streamable HTTP MCP support. Configure:
URL: https://api.superd.fun/mcp
Header: Authorization: Bearer
Use the Trek CLI to install/sync this Skill, verify the connection, and diagnose failures:

npm install -g https://github.com/super21-bat/trek-agent-control/archive/refs/heads/main.tar.gz

trek config init --api-key 'trek_...' --url 'https://api.superd.fun/mcp'
trek skill sync --global
trek doctor

The 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 for runtime details.

Fast paths for common user requests

Do not load the large-planning workflow for these small writes. Use the exact recipe, then stop:

“加到待定/候选地点”：resolve the trip with list_trips, then run trek add-pending [--place-id ] or call native MCP add_pending_place. If the place already exists in 收藏, pass its placeId; the server links/reuses that place instead of creating a duplicate. For a newly researched candidate, include a short stable description and a representative imageUrl when available; put the trip-specific recommendation in reason. A name plus address alone is not enough context for group voting. apply_trip_change with action: "add_pending" remains a compatible fallback. Never use create_place for 待选/候选/待决定.
“设置行程封面”：run trek set-cover or call native MCP apply_trip_change with action: "set_cover". The server owns upload, binding and readback as one semantic operation; do not compose primitive upload/update calls when this tool exists.

For either fast path, if readback fails, report “未同步” and the exact failed stage. Never continue into unrelated planning or claim the mini program will eventually refresh.

Mandatory workflow

Run doctor or native tools/list. Stop on authentication, network, or missing-tool failure.
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.
Research current facts with primary/official sources first. Separate confirmed facts, recommendations, and unresolved items.
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.
Show the user a compact change preview before destructive, bulk, financial, membership, proposal-decision, or rescheduling writes.
Write in small batches. Reuse existing entities and detect duplicates by normalized name/date before creating.
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.
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.
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.
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.
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.
Report what changed, what remains uncertain, and what the user must confirm.

Read references/workflows.md for detailed planning and synchronization recipes. Read references/field-guide.md before a large or unfamiliar write.

CLI

trek doctor
trek update --check
trek tools place
trek call list_trips '{"include_archived":false}'
trek summary 3
trek audit-plan 3 /absolute/path/expected-assignments.json
trek add-pending 3 '西湖游船' --reason '同行者表态后再排日程'
trek upload-file 3 /absolute/path/ticket.pdf --assignment 42 --description '景区电子票'
trek set-cover 3 /absolute/path/cover.jpg --description '行程封面'
trek rename-file 3 19 '金门大桥门票.pdf'
trek batch /absolute/path/actions.json
trek batch /absolute/path/actions.json --apply
trek smoke --allow-write-smoke

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.

Safety invariants

Treat the key as a password. Ask the user to revoke it immediately if exposed.
Never delete or overwrite real data during diagnostics. Use the bundled temporary smoke only.
Do not mark bookings confirmed without order evidence. Use pending or a todo for unresolved bookings.
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.
For minors, medical needs, border crossings, flights, and tight transfers, add safety buffers and explicit adult-confirmation tasks.
Respect 429 responses. Do not disable server limits or fire requests in parallel; the bundled client retries with bounded backoff.
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.
Close every MCP session, including failed runs.

Failure handling

401: key missing, revoked, malformed, or sent without Bearer. 403: user lacks trip permission or scope; do not retry as another user. 404: wrong trip/entity ID or inaccessible resource; refresh state. 429: wait and retry sequentially; reduce batch size. isError: true: treat as failed even if HTTP succeeded. Preserve the error text and stop dependent writes.
Unknown fields/tools: call tools/list; never guess a schema from an older document.

When native MCP and the bundled client disagree, trust a fresh tools/list response and production readback.

Daily notes and reminders (mini program 0.3.22+)
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 @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.
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.
trek day-view / 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 expected-notes.json; audit-plan checks assignments only.
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.
Optional day extras (0.3.18)
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.
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.
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.
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.
Keep each note as one action/supporting item (text