myagents-cli

# myagents-cli — MyAgents 产品能力的 CLI 入口 MyAgents 是带状态的 Agent 平台：Goal、Task、Record、IM Bot、MCP、Provider、插件、Skill、协作空间、Agent 网络与 Session 协作、Widget。CLI 负责产品操作；使用知识与功能边界查 `/myagents-docs`，登录、入网和开放 Agent 等没有 CLI 写入口的操作使用产品 UI。 **这个 skill 不只是"管理工具"，它是 MyAgents 产品能力的执行入口**。用户表达的需求只要能映射到产品能力，就该用 CLI 主动帮用户做掉，而不是给用户一堆操作步骤让他自己去 Settings 点。这份文档列出全部能力以及"什么时候应该用哪条命令"。 ## 前置：CLI 是否可用 CLI 通过 `~/.myagents/bin/myagents` 暴露，App 内 Agent 的 PATH 和调用上下文由产品注入，直接运行命令。它通过 Sidecar Admin API 操作（端口由 `MYAGENTS_PORT` 注入）。外部终端或 AI 需用户在「设置 → 外部调用」主动开启并取得受保护的 `MYAGENTS_API_TOKEN`，只允许公开命令；不要读取内部凭据来绕过授权，也不要输出 token。 - 遇到 `command not found`：让用户重启一次应用触发 CLI 同步 - 遇到 `ECONNREFUSED`：Sidecar 没起来，让用户检查应用是否在运行 ## 使用模式 1. **探索先行**：不熟的命令组用 `myagents <group> --help`；不知道某个 runtime 支持什么 model/permissionMode 用 `myagents runtime describe <runtime>`，**不要靠猜** 2. **按 leaf 契约预览**：只有精确 leaf help 明确声明支持的命令才使用 `--dry-run`；不支持的 mutation 会 fail closed，不能声称已预览 3. **机器可读**：加 `--json` 解析结构化输出 4. **按失败阶段恢复**：读取错误 code 与恢复提示；只读查询可重试。写入、发送工作或接纳未知时，先查询真实状态，不能盲目重复执行。 ## 安全规范 - **改配置前先读精确 leaf help**——该 leaf 明确支持 `--dry-run` 时先预览；未声明支持时不要假装存在 preview - **API Key**：用户在对话里明确给了你才写入；没给就引导他去 **设置 → 对应页面** 填，不要追问 - **明确对象与影响**：删除/覆盖等操作应有具体对象与授权；用户已经明确授权时不重复确认。对象含混、超出授权或会中断未说明的活跃工作时，先澄清。 ## 生效时机 - 配置写入与当前 Session 实际生效是不同事实。Agent 默认值不改写已有 Session identity；Provider、权限、MCP、Skill 与 Plugin 由对应 Runtime 在自己的边界应用。 - builtin MCP/扩展通常在后续对话边界更新；DSH 与 Managed Codex 按支持的 extension admission 更新，不能承诺全部 Plugin 组件通用。查看 `status`、`skill list --verbose` 与实际工具状态，再说明下轮、新 Session 或重启要求。 - `reload` 请求产品重新读取配置，不能保证当前执行轮立即更换工具，也不能把另一 Session 的状态当验证。 --- ## 命令速查 + 何时使用 ### AnyDoc 本地文档转换 MyAgents 内置 AnyDoc 本地文档转 Markdown/OCR 能力。先运行 `myagents anydoc --help`；需要详细使用说明时加载 `/myagents-anydoc`。 ### 本地附件语音识别 MyAgents 能把当前 Workspace 内的单个本地音频或视频附件提交给 App-owned 离线异步转写任务。先运行 `myagents speech --help`；需要完整 Session 隔离、输入格式与任务生命周期说明时加载 `/myagents-speech-recognition`。Session 与 Workspace 由产品自动绑定，不自行传参。 ### MCP 工具（mcp） ```bash myagents mcp list # 看用户配了哪些 MCP myagents mcp show <id> # 看某个 MCP 的完整配置（command/args/env/headers） myagents mcp add --id <id> --type <stdio|sse|http> ... # 新增 myagents mcp remove <id> # 删除 myagents mcp enable <id> --scope <user|project|both> # 启用 myagents mcp disable <id> --scope <user|project|both> # 禁用 myagents mcp test <id> # 实际握手测试连通性 myagents mcp env <id> set KEY=val [KEY2=val2 ...] # 设环境变量（覆盖） myagents mcp env <id> get [KEY ...] # 读环境变量 myagents mcp env <id> delete KEY [KEY2 ...] # 删环境变量 myagents mcp oauth discover <id> # 探测 MCP server 是否支持 OAuth + 拿到 metadata myagents mcp oauth start <id> [--clientId X --clientSecret Y --scopes "..." --callbackPort N] # 启动 OAuth 授权流程（会打开浏览器） myagents mcp oauth status <id> # 看授权状态（已授权 / token 是否过期） myagents mcp oauth revoke <id> # 撤销授权 ``` **何时用：** - "帮我接个 X 工具" → `mcp add` → `mcp enable --scope both` → `mcp test` - "看下 playwright 配的啥" → `mcp show playwright` - "Notion MCP 怎么登录" → `mcp oauth discover` 看支持的 scopes，再 `mcp oauth start` - "X 工具用不了，是不是登录过期了" → `mcp oauth status <id>`，过期就重跑 `oauth start` - "给 fetch 加个 API Key 环境变量" → `mcp env fetch set FETCH_API_KEY=sk-xxx` ### CLI 工具注册表（tool） — PRD 0.2.36，实验室开启后可用 这是实验功能，默认关闭。使用前先运行 `myagents tool --help`： - 如果 help 提示去「设置 → 关于&反馈 → 实验室 → CLI 工具注册表」开启，说明当前会话不能创建、注册或管理用户 CLI 工具；不要继续尝试 `tool-creator` / `myagents tool add`，转而完成一次性任务或请用户打开实验开关。 - 如果 help 返回完整 `list/add/remove/env` 用法，才按下面流程处理。 注册的 CLI 工具会投 shim 到 `~/.myagents/bin/`（全 runtime + 终端的 PATH 上）， description 自动注入所有新 session 的上下文——未来的 AI 会自己发现并使用它。 **写一个新工具**用 `tool-creator` skill（钉死 Agent-CLI 契约：非交互 / 退出码 / --json / readme 子命令 / ≤800 字 description）；这里只管注册与管理。 ```bash myagents tool list # 注册表总览（含 enabled 状态 + 缺失 env key） myagents tool add <dir> # 注册（dir 须含 tool.json + 入口脚本；不在 # ~/.myagents/tools/ 下会自动拷入）[--dry-run] myagents tool info <name> # 看 manifest + enabled + 缺失 env myagents tool enable <name> # 进新 session 的上下文 myagents tool disable <name> # 从上下文隐藏（shim 仍在 PATH，可手动调） myagents tool remove <name> [--purge] # 反注册（--purge 连工具目录一起删） myagents tool env <name> set KEY=val # 设 per-tool 环境变量（API key；工具启动时读） myagents tool env <name> get # 读（值已脱敏） myagents tool env <name> delete KEY # 删 ``` **何时用：** - 用户说"把这个脚本/能力注册成工具、以后直接用" → 先走 `tool-creator` skill 把它规范化，再 `tool add` - "我有哪些自己的工具" → `tool list` - 工具报缺 API key（退出码 3）→ `tool env <name> set KEY=<用户提供的值>` - 注册名撞系统命令会被打回（`~/.myagents/bin` 在 PATH 前列，重名会遮蔽系统命令）→ 换带领域前缀的名字 - 注册成功后 MUST 在回复中告知用户：工具名 + 干什么 + 可在 设置 → 工具箱 管理 ### 官方图片理解工具（vision） 这是 MyAgents 内置官方 CLI 工具，不属于 MCP，也不属于用户注册 `tool` 实验功能。它用于在当前会话启用“图片理解”工具时，让不支持多模态的主模型把本地工作区图片交给用户在「设置 → 工具箱」里配置好的读图模型分析。 ```bash myagents vision readme myagents vision analyze --image <path> [--image <path> ...] [--prompt "what to inspect"] myagents vision analyze --image <path> --prompt-file <workspace-relative-text-file> myagents vision analyze --image @myagents_files/screenshot.png --prompt "Extract the error text and UI state" ``` **约束：** - 只接受当前 MyAgents 工作区内的本地图片路径；不要传 URL。 - `--prompt` 是短指令；长/多行/含引号的检查指令写进当前 workspace 内的文本文件，再用 `--prompt-file`。 - `--prompt-file` 路径也按当前 workspace 安全解析；不要传 URL、symlink 或 workspace 外路径。 - 如果报“not enabled / not configured”，让用户在「设置 → 工具箱」启用图片理解并选择支持图片输入的模型。 **何时用：** - 当前主模型不支持图片，但会话里出现截图 / 图片附件，并且系统提示里说明 vision 工具可用。 - 用户要求“看这张图 / 截图里写了什么 / 读一下错误信息”，先 `vision analyze` 拿文字观察，再基于观察继续回答。 ### 模型 Provider（model） ```bash myagents model list # 看所有 Provider、验证状态、主模型与模型清单 myagents model add --id <id> --name <显示名> --base-url <url> --models <m1,m2,...> [其它] myagents model remove <id> # 删除自定义 Provider（内置的删不掉） myagents model set-key <id> <apiKey> # 设 API Key myagents model set-default <id> # 设为默认 Provider myagents model verify <id> [--model <某个具体模型>] # 实际发一条测试消息验证 ``` **何时用：** - "帮我配 DeepSeek" → 内置 Provider 直接 `model set-key deepseek <key>` → `model verify` - "我要用一个新厂商" → 详见下方 §配置模型服务流程 - "把默认改成智谱" → `model set-default zhipu` - "我之前加的那个废 Provider 删了吧" → `model remove <id>` ### Agent + Channel（agent） ```bash myagents agent list # 发现本机和同账号在线设备的可调用 Agent myagents agent create --workspacePath /absolute/path # 把既有目录幂等注册成 Project-backed Agent myagents agent current --json # 只看当前 Agent/workspace/Session myagents agent list --active # 只列出未归档 Agent 工作区 myagents agent list --archived # 只列出已归档 Agent 工作区 myagents agent show <id> # 看某 Agent 的 effective 默认（runtime/model/permissionMode） myagents agent enable <id> # 启用本机 Agent 主动能力，非网络开放或 Channel 开关 myagents agent disable <id> # 暂停主动能力，不关闭显式 Session 协作 myagents agent archive <id> # 归档 Agent 工作区，并暂停 proactive Channel myagents agent unarchive <id> # 取消归档；若归档前是 proactive，会恢复启用 myagents agent set <id> <key> <value> # 改本机单个字段；合法 JSON 会解析，否则保留字符串 # key 仅限 enabled/runtime/runtimeConfig/providerId/model/permissionMode # id / channels 用专用命令；未知 key 会在写盘前拒绝 myagents agent channel list <agentId> # 列出某 Agent 的所有 Channel myagents agent channel add <agentId> --type <平台> --<凭证flag> ... # 添加 Channel（telegram / feishu / dingtalk / openclaw:xxx；先查 help） myagents agent channel remove <agentId> <channelId> # 删除 Channel myagents agent runtime-status # 看本机 Channel 运行状态，非 Agent 网络在线状态 ``` **何时用：** - "我那个 Agent 现在啥配置" → `agent show <id>`，按 runtime 正确解析过 effective 值 - "把这个本地目录注册成 Agent 工作区" → `agent create --workspacePath <绝对且已存在的目录>`；不创建目录，不初始化 Git/模板 - "把 Agent X 的 model 改成 Y" → `agent set X model '"Y"'`（注意 JSON 字符串要双层引号） - "把 permissionMode 改成 plan" → `agent set X permissionMode '"plan"'` - "项目结束了，先收起来" → `agent archive <id>`；需要恢复时用 `agent unarchive <id>` - "飞书 Bot 在线吗" → `agent runtime-status`；`agent list` 的网络发现不证明 Channel 在线 - 配 Channel 详见下方 §配置 Agent Channel 流程 `agent show` 读 Agent 的执行默认，`agent set` 写本机单个字段。只使用 canonical key；`provider` / `permission` 不是 alias，分别用 `providerId` / `permissionMode`。Provider/model/permission 会校验后同步 Project 镜像和运行中的 Channel；已有 Session 仍由自己的生命周期管理。权限值先查 `runtime describe` 和 leaf help，不复用旧 Codex 模式映射。复杂 Channel 改动走 `agent channel`；这些写命令不管理远端 Agent。 ### Agent Runtime 发现（runtime） ```bash myagents runtime list # builtin/dsh/claude-code/codex 的装机情况 + 版本 myagents runtime list --json # 机读：installed/version/path myagents runtime describe <runtime> # 某 runtime 的 model 清单 + permissionMode 枚举 myagents runtime diagnose codex [--workspacePath PATH] # Codex 的 auth/features/MCP/apps/effective-env 快照（issue #194） myagents diagnose runtime codex # 同上的 sugar 写法 myagents diagnose runtime dsh # 资源校验、当前进程/模型/权限/代理/扩展，不启动新 Session ``` **何时用：** - 在跑 `task create-direct --runtime X --model Y --permissionMode Z` **之前**先 `runtime describe X` 把合法值查清楚——`--help` 只列 flag，值靠这俩命令现场查，不会因为文档漂移而错 - "我装了哪些 Agent CLI" → `runtime list` - 用户问"codex 支持什么 model" → `runtime describe codex` - 「@oai/artifact-tool 我从终端能调用、MyAgents 里就不行」/「Codex MCP 在 MyAgents 里看不到」/「Codex 是不是用错代理了」→ `runtime diagnose codex`。它 spawn 一个临时 codex app-server，跑 `getAuthStatus` / `experimentalFeature/list` / `mcpServerStatus/list` / `app/list` 四个 RPC，把 Codex 自己看到的状态原样吐出来，省得猜。effectiveEnv 节里能看到 MyAgents 注入的代理是不是真到了子进程，feature flag 是不是真生效。 每个 Runtime 有自己的 model 清单、权限模式和计划状态。DSH 模型目录查 `model list`；Codex 模型通过当前 Runtime 查询。不要把旧 CLI 名称、产品权限与 Runtime 原生策略混用；Codex system-cli probe 不能代替 `codex-sub` 的 Managed Codex 诊断。 ### Skills（skill） ```bash myagents skill list [--verbose] # 已装 skill（全局 + 项目级） myagents skill info <name> # 某 skill 的详情 myagents skill add <source> [--scope user|project] [--plugin X] [--skill Y] [--force] [--dry-run] myagents skill remove <name> # 删除 myagents skill enable <name> # 启用 myagents skill disable <name> # 禁用非 Required Skill；Required System Skill 会拒绝 myagents skill sync [name ...] # 预览 ~/.claude/skills 的导入候选，不写入 myagents skill sync [name ...] --apply # 导入选定候选；新导入默认禁用，需 skill enable ``` **`skill add` 输入形态**（同一 resolver 全吃）： | 输入 | 说明 | |------|------| | `foo/bar` | GitHub owner/repo 简写 | | `https://github.com/foo/bar` | 完整 URL | | `https://github.com/foo/bar/tree/main/skills/baz` | 子路径，只装 baz | | `foo/bar@baz` | 仓库内多 skill 选其一 | | `"npx skills add foo/bar --skill baz"` | 用户从 README 复制的整条命令（用引号包） | | `https://example.com/x.zip` | HTTPS 直连 zip | | `./private-skill` / `../private.skill` | 相对当前 CLI 调用目录的本地目录、`.zip` 或 `.skill`；必须显式写 `./` / `../` | | `/absolute/path/private-skill` | 本地绝对路径（Windows 也支持 drive-letter 路径） | | `file:///absolute/path/private.skill` | 本地 file URL | 本地来源会物化复制到 MyAgents 管理目录，不保留 source symlink；`--dry-run` 只解析和预览，不写目标或 staging。 **不支持**：`.tar.gz/.tgz`、GitLab、私有仓库、git SSH。 **何时用：** - 用户贴 GitHub 链接或 `npx skills add ...` → 直接 `skill add "<原文>"`，resolver 自己剥前缀 - 用户给出私有本地 Skill → 保留显式 `./` / `../` 或绝对路径，直接 `skill add <source>`；不要先复制进 `~/.claude/skills` - "装 React 最佳实践" → `skill add vercel-labs/skills --skill react-best-practices` - 报错 `该仓库是 Claude Plugins 市场` → 按提示加 `--plugin <name>`，比如 `skill add anthropics/skills --plugin document-skills` 一次装 docx/pdf/pptx/xlsx - 报错 `技能 X 已存在` → 跟用户确认要不要 `--force` 覆盖 - 用户在 `~/.claude/skills/` 自己塞了东西 MyAgents 看不见 → `skill sync` 预览，再按授权 `--apply` 导入并启用 ### 定时与未来自动化 Task ```bash myagents task readme # 统一自动化模型与当前命令 myagents agent current --json # 仅诊断当前 Agent/workspace/Session myagents task get <taskId> --json # 权威配置与运行状态 myagents task run <taskId> # 首次启用 Todo Task myagents task start <taskId> # 恢复 schedule；看回执 nextExecutionAt myagents task stop <taskId> # 暂停并停止活跃执行 myagents task runs <taskId> [--limit N] # 看 AI 执行历史 myagents task run-now <taskId> # 绕过 Detector 立即执行 myagents task exit [--reason "..."] # 仅在允许 AI exit 的 Task run 内 ``` 定时、未来唤醒、循环执行和“满足条件才处理”是同一类 Task 意图。先加载 `myagents-task-automation`，由它选择普通 always 激活或 command Detector，并完成创建、回读和启动。不要让用户先选择 Cron 或 Sensor。 `myagents cron ...` 继续作为旧用户/脚本的兼容 alias，但不是 Agent 新建自动化的规范入口。不要调用系统 `cron/crontab/at/launchctl/schtasks`。 ### Goal 目标模式（goal） Goal 是当前会话内的持续执行模式：宿主会在每轮完成后自动发起下一轮，直到 AI 主动标记完成/受阻，或用户在 UI 中取消。它复用当前 session 上下文，不是独立任务中心任务。 ```bash myagents goal get # 查看当前 session 的 Goal myagents goal create --objective-file goal-objective.txt --max-executions 12 # 本地任意普通文本文件；可选 deadline/max/AI exit 条件 myagents goal update --status complete # AI 判断目标完成时主动退出 myagents goal update --status blocked # AI 判断无法继续时主动退出 ``` **何时用：** - 用户明确要求进入 Goal 时，先用标准文件工具把 objective 写入本地文本文件（workspace 或系统 temp 均可），再传 `--objective-file`；不要把用户文本拼入 Shell 命令。可用 `--deadline <ISO-8601-with-offset>`、`--max-executions <正整数>`、`--ai-can-exit <true|false>` 设置已有结束条件；deadline 是最晚停止时间，不是延迟开始。 - 当前会话进入 Goal 后，你完成了用户目标 → `goal update --status complete` - 你连续尝试后确认缺关键输入/外部状态，无法继续推进 → `goal update --status blocked` - 用户问"现在目标是什么/状态如何" → `goal get` - 不要用 `goal update` 表示用户取消；取消由 UI/宿主控制。 ### 记录与任务中心（record / task） 用户要定时、未来唤醒、循环执行或满足条件才叫醒 AI 时，统一加载 `myagents-task-automation`。command Detector 的协议、fixture 和测试由该 Skill 按需路由到自己的 reference；这里仅保留 Task Center 的通用命令索引。 ```bash myagents record list [--kind text|audio --tag X --query X --limit N] # 列统一记录；省略 --kind 时同时包含文字与音频 myagents record create '...' # 记一条文字 Record（首选：单引号包裹防 shell 注入； # 用 #xxx 内联打 tag —— 没有 --tag flag） myagents record create --content '...' # 显式 flag 形态，同样使用单引号 myagents record create --content-file <abs-path> # 内容含多行 / CJK / shell 元字符 / # Windows 下单引号失灵时的保底通道 myagents task list [--status X --tag X --query X --limit N --includeDeleted] # 默认当前 workspace；JSON 是紧凑投影 myagents task get <taskId> # 详情 + statusHistory + 各 .md 文档路径 myagents task create-direct --name "..." \ [--taskMdFile <path> | --taskMdContent "..."] \ [--runtime X --providerId X --model X --permissionMode X --runtimeConfig <jsonStr> --mcpEnabledServers a,b] \ [--executor agent --executionMode once --runMode X --tags x,y --sourceRecordId X] # 从完整 task.md 物化普通任务（当前 workspace 可自动继承） myagents task comments <taskId> [--limit 50 --before <cursor>] # 读取本地线性评论时间线 myagents task comment [<taskId>] --body-file <path> [--reply-to <commentId>] # Agent 显式写回本地 Task；执行上下文可继承 taskId myagents task run <taskId> # 派发 todo 任务 myagents task start <taskId> # 按保留 anchor 恢复，以 nextExecutionAt 为准 myagents task stop <taskId> # 暂停 schedule 并停止活跃执行 myagents task runs <taskId> [--limit N] # 查看最近 AI 执行历史 myagents task exit [--reason "..."] # 仅在允许 AI exit 的 scheduled Task 内 myagents task rerun <taskId> # 从 blocked/stopped/done 重新派发 myagents task update-status <taskId> <status> [--message "..."] # 状态机：todo→running→verifying→done（或 →blocked/stopped）、done→archived myagents task append-session <taskId> <sessionId> # 把一个聊天 session 关联到任务（任务过程中开了新会话用这个登记） myagents task archive <taskId> [--message "..."] # 归档（仅用户可操作；AI 走会被拒） myagents task delete <taskId> # 不可恢复地移出产品使用；不删工作区脚本 ``` `create-direct` 和 `task list` 正常会继承当前 workspace，不需要先枚举 Agent 再手工拼 `workspaceId/path`；只有明确跨 workspace 时才传两者。`myagents agent current --json` 是紧凑诊断入口，不是 happy path 前置步骤。 创建 scheduled/recurring Task 可用 `--deadline <ISO-8601-with-offset>`、`--maxExecutions <正整数>`、`--aiCanExit true|false` 设置结束条件；quiet Detector 检查不消耗 maxExecutions。固定 interval 第一次 `run` 默认约 2 秒后产生首次 tick；要延后首次机会时传 `--startAt <ISO-8601-with-offset>`。Cron 等下一个墙钟点，scheduled 等 `dispatchAt`。 **任务级 runtime/provider/model/permissionMode 覆盖**：`create-direct` 支持仅对该任务生效的覆盖 flag，**不会改 Agent 工作区默认**。典型场景："实现用 Claude Code、review 用 Codex" → 创两个任务，`--runtime` 不一样，工作区配置不变。 | Flag | 语义 | |------|------| | `--runtime` | `builtin` / `dsh` / `claude-code` / `codex`，不传则继承 |