external-myagents-cli

# MyAgents 外部调用指南 ## 1. MyAgents 是什么 MyAgents 是一个在用户电脑上运行的桌面 Agent 产品。它把本地目录、AI 执行环境和长期工作状态组织成几个可以组合的产品实体： - **Workspace Agent**：绑定一个已有本地目录的长期 Agent 身份。它是工作区、默认 Runtime 和后续 Session 的稳定地址。 - **Session**：某个 Agent 下相互隔离的对话与执行上下文。可以新建干净上下文，也可以向已知 Session 继续发送任务并读取文本历史。 - **Task**：可持久化、可执行、可调度的工作项。适合待办、一次性执行、定时执行和满足条件后激活的自动化。 - **Record**：轻量的信息收集入口，用来保存文字记录，之后可以再整理或转成 Task。 - **Runtime**：真正执行 Agent 的运行环境。MyAgents 可以发现本机已支持的 Runtime，以及它们各自可用的模型和权限模式。 MyAgents App 是这些状态和执行生命周期的本机 Host；CLI 只是调用入口。你是运行在 MyAgents 之外的 AI，能够通过公开 CLI 委托和观察工作，但不会因此获得 MyAgents 内部 Session 身份、全部管理能力或隐藏 API 权限。 MyAgents 产品内部还可以管理模型 Provider、MCP/工具、Skill/Plugin、IM Channel、Cloud Space、Goal、文档与语音等能力；它们帮助 Agent 接入模型、工具、外部沟通渠道和更丰富的工作流。但当前外部 token 契约只开放本文后面介绍的 Agent、Runtime discovery、Session、Task、Record 和状态查询。知道某项产品能力存在，不等于可以从外部 CLI 调用它。 ## 2. MyAgents 能解决什么任务 把这些能力组合起来，可以完成几类典型工作： | 用户意图 | 能力组合 | 结果 | | --- | --- | --- | | 让一个本地项目拥有可持续对话的 AI | 注册目录为 Workspace Agent → 新建 Session → 后续 send/get | 获得稳定 Agent ID 和可继续的独立上下文 | | 把一件工作交给另一个 Agent 完成 | 找到目标 Agent → start 新 Session → 保存 Session ID → get 结果 | 当前 AI 不需要自己进入目标工作区 | | 委托同账号另一台设备上的 Agent | agent list 发现在线目标 → 使用完整跨设备 ID → start/send/get | 由目标设备的 MyAgents 执行，并可主动读取结果 | | 创建待办、定时任务或条件自动化 | 明确 Workspace → 创建 Task → 配置/启动 → get/runs 查看状态 | 工作进入 MyAgents 的持久 Task 生命周期 | | 先记下来，稍后再处理 | 创建 Record → 后续查看并整理为 Task | 信息不会只停留在当前对话里 | | 在创建 Task 前选择执行环境 | runtime list/describe → 使用返回的合法值 | 避免猜测 Runtime、模型或权限模式 | 最常见的主链路是： ```text 已有本地目录 → Workspace Agent → Session start → Session send → Session get ``` Task 和 Record 可以在这条链路之外保存更长期的工作意图；Runtime discovery 用来了解当前机器真实支持的环境，并为支持 override 的 Task 选择合法值。新 Session 继承目标 Agent 的配置，已有 Session 继续使用自己的执行配置；外部 Session 调用不能临时覆盖。 ### 开始调用前 1. MyAgents App 必须保持运行。 2. 用户在 MyAgents 的「设置 → 外部调用」中开启 **MyAgents CLI 外部调用**。 3. 设置页复制的交接 Prompt 可能已经携带当前 `MYAGENTS_API_TOKEN` 设置命令。只用它配置调用进程环境；你不能通过 CLI 读取 token，也不要在后续回复、命令输出或文件中复述、记录它。 4. 始终使用交接 Prompt 给出的 **CLI 绝对路径**。普通终端和外部 Agent 的 PATH 不保证能发现 `myagents`。 POSIX shell： ```sh export MYAGENTS_API_TOKEN="<token>" ``` PowerShell： ```powershell $env:MYAGENTS_API_TOKEN = "<token>" ``` 下文用 `<CLI>` 代表交接 Prompt 给出的绝对路径。实际执行时替换它，并按当前 shell 安全引用路径：POSIX 可用 `"/absolute/path/myagents" ...`，PowerShell 可用 `& "C:\\...\\myagents.cmd" ...`。 ### 先用帮助发现，再调用 不要靠记忆猜参数。按层级读取当前安装版本的帮助： ```text <CLI> --help <CLI> agent --help <CLI> agent create --help ``` - 顶层帮助列出当前外部公开能力。 - group help 用来选择子功能；leaf help 是 flags、输入要求和失败语义的权威。 - 外部命令只接受 leaf help 明确列出的参数；未知命令、额外位置参数和未知 flag 会在发起 HTTP 前直接拒绝，不会静默忽略。 - 业务调用优先加 `--json`。stdout 返回一份机器可解析 JSON，诊断信息走 stderr。 - 退出状态 `0` 只表示该命令达到自身定义的成功边界；非零状态必须按失败处理，并优先读取 JSON 中的稳定 `code`。精确退出码以 leaf help 为准。 ## 3. CLI 能力入口 ### App 状态与版本 适合在工作开始前确认 MyAgents Host 是否可用，以及记录当前 App 版本。 ```text <CLI> status --json <CLI> version --json ``` `status` 只表示 Host 状态，不代表某个 Session 或 Task 已经完成。 ### Workspace Agent 适合把一个已经存在的本地目录注册成长期 Agent、发现已有 Agent，或确认目标 Agent 的默认执行配置。 先读： ```text <CLI> agent --help <CLI> agent create --help ``` 核心动作： ```text <CLI> agent create --workspacePath <absolute-existing-directory> --json <CLI> agent list --json <CLI> agent show <agentId> --json ``` `agent create` 不会创建目录、初始化 Git、复制模板或自动启动 Session。同一未归档、正常可见的 workspace 重复注册会返回同一个 Agent。保存成功响应中的 `agentId`；不要用显示名称或路径猜 ID。 ### 同账号跨设备 Agent `agent list` 合并本地 Agent 与同账号其它设备上在线、已开放调用的 Agent；`--archived` 只列本地归档对象。JSON 中 `isLocal` 区分归属，`deviceName` 帮助选择目标，`agentId` / `selector` 才是调用地址。`networkStatus` 和 `complete` 表示网络发现状态与目录是否完整；网络异常时本地结果仍可返回，不能把不完整目录当作没有远端 Agent。 - 本地 Agent 使用返回的普通 ID；跨设备 Agent 使用完整的 `ma-agent:1:...` ID，跨设备 Session 使用完整的 `ma-session:1:...` ID。原样保存和传递，不截短、解码或按名称拼接。 - `agent show`、`session list/start` 接受 Agent ID；`session send/get/state` 接受 Session ID。本地和跨设备使用相同命令，无需额外网络参数。 - 跨设备调用要求本机网络连接可用，目标设备在线且目标 Agent 已开放。目标离线时调用失败，没有离线补投或自动重发。 - Session 在目标设备执行，继承目标 Agent 的配置；本地 `--prompt-file` 由调用方 CLI 读取后发送文字，不是让远端读取该文件路径。 跨设备路径同样先从成功 discovery 响应选目标： ```text <CLI> agent list --json <CLI> agent show <returned-agentId> --json <CLI> session list --agent <returned-agentId> --json <CLI> session start --agent <returned-agentId> --prompt-file <local-request-file> --json <CLI> session get <returned-sessionId> --json ``` Agent 的注册、Task、Record 与 Runtime discovery 仍操作本机 Host；跨设备寻址不开放远端配置或文件管理。 ### Runtime 发现 适合查看当前机器安装了哪些执行 Runtime，以及某个 Runtime 支持哪些模型和权限模式。它只做发现，不修改 Provider 或 Agent 配置。 ```text <CLI> runtime --help <CLI> runtime list --json <CLI> runtime describe <runtime> --json ``` 在为支持 override 的 Task 选择 runtime/model/permissionMode 前先 describe，不要凭经验硬编码值。`models` 可能为空，例如 builtin 的模型来自 Provider；这不表示 Runtime 不支持模型。外部调用可读取 `agent show` 的未来 Session 默认值，未公开的 Provider 目录或诊断需在 App 内查看，不因响应中的恢复建议而调用非公开命令。Session start 不接受临时 override，而是继承目标 Agent 的配置。 ### Session：委托、续聊与读取结果 适合把工作交给一个 Agent 的新上下文、向已知上下文追加指令，或读取当前可见的文本历史。 先读： ```text <CLI> session --help <CLI> session list --help <CLI> session start --help <CLI> session send --help <CLI> session get --help <CLI> session state --help ``` 核心链路： ```text <CLI> session list --agent <agentId> --limit 5 --json <CLI> session start --agent <agentId> --prompt-file <request-file> --json <CLI> session send <sessionId> --prompt-file <follow-up-file> --json <CLI> session state <sessionId> --json <CLI> session get <sessionId> --limit 5 --json ``` - 保存 `start` 返回的 Product Session ID；后续 `send/get` 都使用这个 ID，不要替换成 Runtime 自己的 session 标识或投递 messageId。 - 多行、较长或来自外部输入的 prompt 优先写入普通文本文件，再使用 `--prompt-file`，避免 shell 转义和注入。 - 外部 `start/send` 是 one-way。成功回执只表示请求已接受或投递，不代表 AI 已执行成功；需要结果时主动 `session get`。外部调用不提供自动结果回调或 `session watch/watches/unwatch`。 - `session state` 只读返回 `idle`、`running` 或 `waiting_user_action`；后者要求目标用户处理审批、确认或必须回答的问题。查询不唤醒模型、不代替用户批准，`idle` 也不表示任务成功。 - 状态不可读时返回查询错误，可按错误提示重试读取；不要把查询失败解释成目标 idle。 - `session get` 默认返回最近 5 条非空 user/assistant 文本，按旧到新排列；工具调用、thinking 和隐藏协议不会作为正文返回。`isLive=true` 时 `liveSessionState` 投影目标当前状态；`isLive=false` 时它为 `null`，不代表错误。暂时没有新 assistant 正文不等于失败或完成。更早内容按 leaf help 使用 `before` 分页。 - transport failure 或 `admission_unconfirmed` 可能表示结果不确定。保留已取得的 ID 并先查询，**不要自动重发**。 ### Task Center 与自动化 适合创建持久工作项、派发执行、维护状态、查看运行历史，以及配置定时或条件触发。Task 子能力较多，不要一次加载或猜测全部命令。 先从产品说明和 group help 选择路径： ```text <CLI> task readme <CLI> task --help ``` 常用入口： ```text <CLI> task create-direct --help <CLI> task get <taskId> --json <CLI> task runs <taskId> --limit 5 --json ``` - 外部进程没有“当前 MyAgents Workspace/Session”上下文。`task list` 和 `task create-direct` 至少显式提供 `--workspaceId` 或 `--workspacePath` 之一；MyAgents 会补齐并核对这对 identity。不要用 shell cwd 猜目标。 - `task get/start/stop/runs/run/rerun/run-now/update/archive/delete` 等精确 Task ID 操作以该 ID 为 selector，不要求附带当前 workspace；`task remove` 是 `task delete` 的显式兼容别名。Cron 命令不是外部公开面。 - `task readme` 解释 Task/自动化模型；`task --help` 列出当前公开动作；选定动作后再读该 leaf help。 - 调度、trigger、checkpoint、运行控制、状态更新、归档和删除等细节都按需发现，不需要预先注入整张命令表。 - 执行接纳不等于最终成功。使用 `task get` 查看权威状态，使用 `task runs` 查看执行历史。 - 删除等不可逆动作前，核对准确目标并取得用户授权；已有明确授权时不重复确认。 ### Record：轻量记录 适合把想法、材料或待整理的信息先存进 MyAgents，而不是只留在当前聊天里。 ```text <CLI> record --help <CLI> record create --help <CLI> record list --json <CLI> record get <recordId> --json ``` 创建多行、CJK 或包含 shell 元字符的文字时，优先按 leaf help 使用 content-file 输入。外部公开面提供文字 Record 创建、已有文字/音频 Record 的列表与详情读取，以及精确 ID 删除；不提供录音发起、转录任务控制或修改。 确需删除时，先读取详情核对准确目标并取得用户授权，再查 leaf help： ```text <CLI> record delete --help <CLI> record delete <recordId> --json ``` ## 4. 调用边界与失败恢复 - 访问 token 只从 `MYAGENTS_API_TOKEN` 读取。交接 Prompt 是一次性的凭据传递入口；不要在后续 prompt、回复、命令参数、日志、文件或 transcript 中再次传播它。 - 只使用顶层外部帮助展示的命令。token 不会解锁内部命令、内部 Session 身份或隐藏 API；不要探测端口、伪造来源或直连 localhost 管理路由。 - ID 只能来自成功响应或公开 discovery 命令。不要猜 ID，也不要把 Workspace path、显示名称或投递 messageId 当作其它资源的 selector。 - App 不可用时请用户启动 MyAgents；CLI 不会自动启动或聚焦 App。 - 开关关闭或 token 失效时，请用户在「设置 → 外部调用」重新开启或注入当前 token，不要尝试绕过。 - 参数、路径或 lifecycle 冲突时，根据 JSON `code`、错误说明和 suggestion 修正输入。mutation 响应丢失时先用只读命令核实，不自动重放。 外部 token 只用于本机 CLI 访问本机 Host；CLI 可借助 MyAgents Agent 网络委托同账号其它设备上的已开放 Agent。这不提供远程直连 Host 的 HTTP/OpenAPI/SDK/MCP 接口。当前公开面不提供自动结果回调、exactly-once、Provider/MCP/Plugin/Skill/Tool/Channel/Space/Goal/Speech 管理，也不自动创建目录、初始化 Workspace 模板或 Git。目标超出公开帮助时，明确告诉用户需要在 MyAgents App 或 MyAgents 内部 Agent 中完成。