| name | exomind-rt-agent-access |
| description | Teach an AI Agent to connect to ExoMind Runtime via HTTP/curl. Prefer `/act/*` feature APIs first, and fall back to raw resource routes only when `/act` has no matching action or when low-level truth/debugging is required. Use when the user mentions ExoMind, `/act`, await, event log, RT access, curl, profiles, tasks, or timeblocks in ExoMind. |
ExoMind Runtime Agent / curl 接入指南
核心约束：Agent 接入外心的目标是辅助人类、引导人类成长，不是替代人类做决策。
定位：
- 本 skill 是 ExoMind Runtime HTTP/curl 接入的唯一真源。
- Agent 默认优先使用
/act/* feature API；只有 /act/* 暂无对应动作，才回退 raw RT 资源路由。
- raw RT 资源路由主要用于真相回读、低层排障、联调和兼容期补能力。
- 历史上的独立 curl 手册内容已收口到本 skill，不再保留第二份真源。
- 具体端点细节按渐进披露拆到
references/，主 SKILL.md 只保留入口层规则、核心流程与风险边界。
- 若任务是维护本 skill，或刚执行完一次 curl 实测需要回写经验，先读
references/maintenance.md，不要只盯主文档。
渐进披露规则：
- 不要默认一次性把全部 references 读入上下文。
- 先用本文件确定任务类型，再按需加载 1-2 份最相关的 reference。
- 如果任务只涉及
eventlog，不要顺手加载 tasks 或 timeblocks 细节。
同步维护约束：
- 若在实际使用 curl 时发现经验与本 skill 内容冲突，不得直接凭印象修改，必须先结合当前 RT live 版本信息、当前工作区代码、GitHub 对应 issue / PR / 文档信息核验该差异是否已证实为“本文过时”。
- 一旦证实过时，则在完成本次 curl 使用后，必须持续回写本 skill 的对应章节或 reference，不能只把经验留在对话、issue 评论或临时笔记里。
- 进入维护环节时，必须先反思“本次执行过程相对参考章节出现了哪些新变化或差异”，再定位需要维护的 skill 文档，而不是直接修改主
SKILL.md。
- 每次对本 skill 的主文件或 reference 做增删改，都必须同步更新该文件顶部维护元数据，并在
references/maintenance.md 追加维护记录。
版本与时效性
- 最后更新日期：
2026-05-18
- 更新者：
Claude Code
- 更新内容概要：
去硬编码：将所有http://127.0.0.1:9124` 和 profile-argon 替换为 <RT> 和 <PROFILE> 占位符；新增"设备配置优先"规则，指向 exomind-monitor skill 的 config.json；禁止凭名字猜测档案`
- 核验依据：
GET /version 等 live 版本信息- 当前工作区代码与相关路由实现
- GitHub 对应 issue / PR / 文档信息
- 基线提交：
da88bc11
- 真相源：
../../crates/exomind-runtime/src/lib.rs../../crates/exomind-runtime/src/agent_await.rs../../crates/exomind-runtime/src/routes/eventlog.rs../../crates/exomind-runtime/src/routes/agent_await.rs../../crates/exomind-runtime/src/routes/tasks.rs../../crates/exomind-runtime/src/routes/timeblocks.rs../../crates/exomind-runtime/src/routes/profiles.rs../../crates/exomind-runtime/src/routes/signals.rs../../crates/exomind-runtime/src/routes/topology.rs
- 当前覆盖范围：
- 已覆盖：当前 ExoMind Runtime HTTP/curl 接入分层、
/act/* 优先规则、raw RT 直读/排障、profile-<slug> scope 规则、当前鉴权现状、tasks/timeblocks/eventlog 的排障要点、常见 /act/await 自然语言意图映射
- 不覆盖：
/agents/* SSE 会话细节、/act/today-planner/* 的完整 feature 语义、/act/await 全量 condition / fulfilled payload 细节、mesh peer token / grant 的完整运维流程
读取顺序
- 运行态：
- 先读本文件，确认任务域、风险等级与真相源优先级
- 再读
references/index.md 或直接按任务域加载 1-2 份 reference
- 维护态：
- 如果任务是整理 skill 本身，或你刚执行过一次 raw RT curl 任务准备回写经验，先读
references/maintenance.md
- 维护时先做“执行后差异反思”，再决定更新
SKILL.md 还是某个具体 reference
维护记录与维护检查清单统一放在 references/maintenance.md，避免主入口重新膨胀。
什么时候用这个 skill
以下场景直接触发：
- 用户提到 ExoMind RT、
/act/*、await、eventlog、profiles、tasks、timeblocks、signals、curl、raw HTTP 端点
- 需要绕过 UI，直接对 RT 做联调、排障、回读或实测
- 需要判断某个动作应该走
/act/* 还是 raw 资源路由
- 需要判断某个 RT 行为究竟是代码真相、live 真相，还是旧文档残留
以下场景不要把本 skill 当唯一资料：
/agents/* 的 SSE / session 语义/act/today-planner/* 或 /act/await 的完整 feature contract 设计- mesh peer token / pairing / grant 的完整运维流程
先读哪份 reference
按任务类型只读需要的那份：
| 场景 | 读取文件 |
|---|
| 先确认 references 目录地图、关键词和跨域组合方式 | references/index.md |
| 健康检查、版本、拓扑、profiles、signals、PowerShell curl 约定、鉴权边界 | references/discovery-and-diagnostics.md |
| eventlog 读写、raw watch、备份、导入、清空 | references/eventlog.md |
| tasks 列表、创建、更新、迁移、取消、导入导出 | references/tasks.md |
| timeblocks 活动块、start/stop/end、pause/resume、describe、import/export | references/timeblocks.md |
| 执行后差异反思、维护记录、更新路由 | references/maintenance.md |
如果任务跨域：
eventlog + tasks：先读 eventlog.md，再读 tasks.mdtimeblocks + tasks：先读 timeblocks.md，再读 tasks.md- 只需要确认档案和端口：只读
discovery-and-diagnostics.md
如果任务还没确定该走 /act/* 还是 raw 路由：
- 先留在本文件做入口判断，不要一上来就跳到 raw reference
先做入口判断
默认按这条优先级执行：
- 如果
/act/* 已有对应动作，默认使用 /act/*。
- 如果任务是“等待一个未来条件成立一次后返回”，默认使用
POST /act/await。
- 只有在
/act/* 暂无对应动作，或你需要直接读取资源真相、raw cursor / catch-up 语义、低层排障时，才回退 raw RT 资源路由。
- 即使走 raw 路由，写入后也必须回读验证，不得把 raw 路由当成隐式成功。
当前已落地、值得优先检查的 /act/* 入口至少包括：
POST /act/await/act/today-planner/*
核心流程
执行 ExoMind Runtime HTTP/curl 任务时，默认按这条流程：
- 先确认目标 RT 可访问：
/health、/version
- 确认档案 scope：优先回读
/profiles
- 先判断
/act/* 是否已有对应动作
- 若是等待/监听一次结果，优先用
POST /act/await
- 只有在
/act/* 不覆盖或需要低层排障时，才识别 raw 任务域：eventlog、tasks、timeblocks、signals、topology
- 只加载对应 reference，不要一口气读全套
- 如涉及写操作，先套用“行为分级”
- 写入后必须回读验证
- 如果实测与本文不一致，做 live / 代码 / GitHub 三重核验
- 若确认本文过时，回写本 skill 或对应 reference，并补维护记录
先记住这几个差异
如果你看过更早的 skill / 手册，先用这组差异校正心智：
GET /health 现在只返回 {"status":"ok"}，版本信息已经拆到 GET /version。- 清空事件日志的真端点是
DELETE /eventlog，不是 /eventlog/clear。
eventlog 的档案作用域参数是 user_id；tasks / timeblocks 接受 profile_id 或 user_id，如果两者同时传入则 profile_id 优先。GET /eventlog/watch 默认是 watch from now；只有显式给 since_id 或 since_timestamp 才会先补 backlog。- 时间块的结束流程不是单步“直接结束”，而是
start -> stop -> end。
- 对 Agent 的默认入口，先检查
/act/*；当前已经落地的等待入口是 POST /act/await，不是 raw GET /eventlog/watch。
GET /eventlog/watch 是 raw EventLog watch / cursor / catch-up / debug 工具；如果只是要“等待下一事件”或“等待任务 / 时间块 / 提案条件成立一次”，默认走 /act/await。- raw RT 仍然是重要调试面，但角色是直读真相、低层排障和兼容期补能力；只有
/act/* 没有对应动作时才回退。
- 目前并非所有能力都已封装到
/act/*；例如时间块等多数工作流仍经常需要回退 raw 路由，这正是回退存在的原因。
- 时间块 await 语义要分清：
timeblock_stopped = 专注结束 = active block 进入 feedback_in_progress- raw EventLog 的
block_end / 文案“时间块结束”只是 stop 痕迹，不表示 feedback 已提交
timeblock_ended = 时间块完成 = feedback 提交后进入 completed history
最小 raw fallback 接入三步
设备配置优先：若本机安装了 exomind-monitor skill，先从 ~/.claude/skills/exomind-monitor/references/config.json 读取 rt.baseUrl 和 rt.profile，不要凭本文示例值猜测端口和档案。本文示例使用 <RT> 和 <PROFILE> 占位符。
以下示例只适用于当前没有对应 /act/* 动作，或你明确需要 raw 直连时。
用户通常会给你两个信息：RT 地址和档案名。
Step 1：确认连接
curl -sS http://<RT>/health
curl -sS http://<RT>/version
Step 2：确认档案作用域
curl -sS “http://<RT>/profiles”
返回值中的 id 即 raw RT 的 user_id 参数（格式通常为 profile-<slug>）。禁止凭名字猜测，必须以 /profiles 实际返回或设备配置文件为准。
Step 3：写入后必须回读
curl -sS -X POST “http://<RT>/eventlog?user_id=<PROFILE>” \
-H 'Content-Type: application/json' \
-d '{“timestamp”:<毫秒时间戳>,”content”:”消息内容”,”tags”:[“agent_feedback”,”note”]}'
curl -sS “http://<RT>/eventlog?user_id=<PROFILE>&limit=1”
不要假设写入一定成功。网络中断、格式错误、RT 重启都可能导致丢失。
等待/监听默认走 /act/await
如果 Agent 的目标是”等未来条件成立一次后返回”，默认先用 POST /act/await，而不是 raw GET /eventlog/watch。
最小例子：
curl -N -X POST “http://<RT>/act/await?user_id=<PROFILE>” \
-H “Content-Type: application/json” \
--data-binary '{“condition”:{“type”:”next_event”}}'
先记住这几点：
- 这是单次 fulfill 的 feature API：通常先收到
ready，等待中收到 heartbeat，命中后收到 fulfilled 并结束连接
- 当前默认
timeoutSecs=1800，默认 heartbeatSecs=15
- 等待
task_completed、timeblock_stopped、timeblock_ended、proposal_* 等 feature 条件时，也优先走 /act/await
- 只有在你需要 raw event arrival / cursor / catch-up 语义，或需要排查
/act/await 内部到底等到了哪条底层事件时，才回去读 references/eventlog.md
常见自然语言 -> /act/await 参数速记
把用户常说的话直接翻成下面这组参数：
- 等“下一条事件”
{"condition":{"type":"next_event"}}
- 等“任务完成”
- 若上下文里已经有明确
taskId：{"condition":{"type":"task_completed","taskId":"<task-id>"}}
- 若用户说的是“等任意一个任务完成”：
{"condition":{"type":"task_completed"}}
- 等“当前时间块完成”
- 先在同一 scope 读取
GET /timeblocks/active
- 取返回里的
startId
- 再等待：
{"condition":{"type":"timeblock_ended","startId":"<active-start-id>"}}
- 等“当前时间块专注结束 / 当前时间块结束”
- 先读当前 active block 的
startId
- 再等待：
{"condition":{"type":"timeblock_stopped","startId":"<active-start-id>"}}
- 等“任意一个时间块完成”
{"condition":{"type":"timeblock_ended"}}
- 等“超时 1 小时”
- 在 body 里显式传：
"timeoutSecs": 3600
注意两条硬区别：
- “当前时间块” = 指向一个已经存在的 active block，不要省略
startId
- 省略
taskId / startId = 等这个 scope 下从现在开始命中的任意 future 资源
当前块、任意块、匿名域三件事不要混
- 如果监听的是匿名 / 无 scope 事件流：
- 直接请求
POST /act/await
- 不要传
user_id
- 如果监听的是具体档案：
- 用
POST /act/await?user_id=<PROFILE>（以设备配置或 /profiles 返回为准）
- 如果用户说“等待当前时间块完成”：
- 先读当前 active block，再把它的
startId 放进 timeblock_ended
- 不要偷懒写成不带
startId 的 timeblock_ended，否则语义会变成“等任意未来时间块完成”
- 如果用户说“等待任务完成并告诉我反馈”：
- 先监听
task_completed
- 命中后回读任务详情
- 如果需要反馈原文，继续回读关联 completed timeblock、
block_feedback 与 note/task_completed
两个高频例子：
curl.exe -N -X POST "http://<RT>/act/await" \
-H "Content-Type: application/json" \
--data-binary "{\"condition\":{\"type\":\"task_completed\"},\"timeoutSecs\":3600}"
curl.exe -sS "http://<RT>/timeblocks/active?user_id=<PROFILE>"
curl.exe -N -X POST "http://<RT>/act/await?user_id=<PROFILE>" \
-H "Content-Type: application/json" \
--data-binary "{\"condition\":{\"type\":\"timeblock_ended\",\"startId\":\"<active-start-id>\"},\"timeoutSecs\":3600}"
时间块 await 语义速记
如果你要监听时间块，不要把 raw EventLog 文案和 feature 条件混在一起：
timeblock_stopped
- 含义：专注结束
- 真相：当前 active block 进入
feedback_in_progress
- 典型场景：用户刚点了
stop，准备填写反馈
block_end
- 含义：raw EventLog 中的“时间块停止: ...”文案
- 角色：只是
POST /timeblocks/stop 写出的痕迹
- 关键点：它不是 feedback 完成，不应替代
timeblock_ended
timeblock_ended
- 含义：时间块完成 / 反馈完成
- 真相：该时间块已经进入 completed history
- 典型场景：用户已提交反馈，
POST /timeblocks/end 完成
实操时可直接这样记：
- 要等“专注结束” -> 监听
timeblock_stopped
- 要等“反馈结束后的时间块完成” -> 监听
timeblock_ended
- 如果只是在 EventLog 里看到了
block_end，只能说明块已经 stop 并进入反馈阶段，不能据此断言块已 completed
身份规范
metadata.source 是你在外心中的身份标识：
| 字段 | 含义 | 建议 |
|---|
app | 运行环境 | 如 "Claude Code"、"Codex CLI"、"Termux" |
platform | 模型/平台 | 如 "GPT-5"、"o3" |
deviceName | 身份名 | 用于区分不同 Agent / 设备 |
deviceId | 可选设备 ID | 如 "codex-curl" |
辨识度靠 deviceName。选一个能区分你和其他 Agent 的名字。
行为分级
| 风险等级 | 操作 | 要求 |
|---|
| 低 | 读取事件日志、任务、时间块、signals、topology | 直接执行 |
| 低 | 向事件日志写入消息 | 直接执行 |
| 中 | 创建新任务 | 至少告知人类一轮 |
| 高 | 完成/取消任务（状态迁移） | 必须主动询问人类确认 |
| 高 | 启动/结束时间块 | 必须主动询问人类确认 |
| 高 | 清空事件日志 | 必须主动询问人类确认 |
核心原则：你是人类的助手。任何改变人类数据状态的操作，至少要有一轮主动询问。
读取上下文与信号归属
如果只是理解上下文，默认先看：
curl -sS "http://<RT>/eventlog?user_id=<PROFILE>&limit=20"
识别消息来源时，优先看结构化字段：
tagsmetadata.source.deviceNamemetadata.replyToEventId
不要在 /signals/history 看到一条消息就假设它属于当前档案。具体归属必须回到 /eventlog?user_id=... 复核。
快速外部边界
以下内容不在本 skill 详述：
环境踩坑
主入口层只保留最常踩的几条：
- PowerShell 下优先用
curl.exe，不要依赖 curl 别名
- 长 JSON body 优先写临时文件，再
--data-binary @file.json
- 调
/act/await 这类 SSE 端点时，记得加 -N / --no-buffer
eventlog / tasks 多数 body 用 snake_case，多个 timeblocks body 用 camelCase- 涉及具体端点字段时，不要猜；去读对应 reference
更完整的环境与命令细节，读 references/discovery-and-diagnostics.md。
维护提醒
- 更新或使用本 skill 时，除了核对 RT 行为本身，还要核对 references 分流是否仍然合理。
- 详细维护闭环、差异反思问题单、文件路由表与维护记录，见
references/maintenance.md。
参考
