myagents-cli

name	myagents-cli
description	你正在 MyAgents 这款 AI 产品里运行——MyAgents 自带一套"产品能力"（定时任务、任务中心、记录收集、MCP 工具接入、 模型 Provider、IM Bot 渠道、社区插件、Skills 安装、MyAgents Cloud Space、Generative UI Widget、Goal 目标模式等），全部通过内置 `myagents` CLI 暴露给你。 当用户的需求**落在 MyAgents 产品能力的射程内**，就加载并使用这个 skill，用 CLI 主动帮用户把事情做掉， 而不是让用户去 GUI 点击。 典型触发场景：用户说"每天 X 点帮我 Y / 等 X 发生后继续 / 持续盯着，命中才处理"（→ myagents-task-automation）、"记一下这个想法"（→ record）、"派发成任务"（→ task）、 "接个 X 工具进来"（→ mcp）、"配 X 模型/Provider"（→ model）、"在飞书/钉钉/Telegram 里跟我聊"（→ agent channel）、 "装个 X 插件 / 装个 X skill"（→ plugin / skill）、"处理 Space Issue / 下载附件 / 回复 Issue"（→ space）、 "把图发到 IM 里"（→ im send-media）、"用已配置的读图模型理解图片"（→ vision analyze）、"持续执行直到目标完成"（→ goal）、 "做个图表/仪表盘" （→ widget readme）、"看下我有啥任务/定时/Runtime/版本"（→ list / status / version）、"改下应用设置"（→ config）。 即使用户没说"用 MyAgents 做"几个字，只要意图能映射到上述能力之一，就该走这个 skill。 反向边界：纯业务任务（立即写代码、查资料、读文件）不归这里；只有需要操作 MyAgents 产品状态或未来自动化时才使用本 Skill。
metadata	{"author":"MyAgents"}

myagents-cli — MyAgents 产品能力的 CLI 入口

你正运行在 MyAgents 产品内。MyAgents 不只是一个 chat UI，它是一套带状态的 Agent 平台：Goal 目标模式、定时任务、任务中心、IM Bot、MCP、Provider、插件、Skill、Cloud Space、Widget——这些都是产品能力，由内置 myagents CLI 一站暴露给你。

这个 skill 不只是"管理工具"，它是 MyAgents 产品能力的执行入口。用户表达的需求只要能映射到产品能力，就该用 CLI 主动帮用户做掉，而不是给用户一堆操作步骤让他自己去 Settings 点。这份文档列出全部能力以及"什么时候应该用哪条命令"。

前置：CLI 是否可用

CLI 通过 ~/.myagents/bin/myagents 暴露，你的 SDK 子进程 PATH 已注入这个目录，直接 myagents <command> 就能跑。它通过 HTTP 走 Sidecar Admin API（端口由环境变量 MYAGENTS_PORT 注入）。

• 遇到 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. 失败即恢复：CLI 失败响应会带 → Run: <cmd> 恢复提示，照着跑就行

安全规范

• 改配置前先读精确 leaf help——该 leaf 明确支持 --dry-run 时先预览；未声明支持时不要假装存在 preview
• API Key：用户在对话里明确给了你才写入；没给就引导他去 设置 → 对应页面 填，不要追问
• 删除前确认：用户说"删了吧"也要回读"我要删的是 X，确认吗"

生效时机

• MCP 工具变更（增删改 / 启禁用 / 环境变量 / OAuth）：磁盘立即写入，但工具在下一轮对话才能调用——MCP server 在 session 创建时绑定。当前轮配完后告诉用户："发条新消息我就能用了"
• 其他配置（Provider / Agent / cron / skill / plugin / config）：写入即时生效

---

命令速查 + 何时使用

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）

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）；这里只管注册与管理。

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 实验功能。它用于在当前会话启用“图片理解”工具时，让不支持多模态的主模型把本地工作区图片交给用户在「设置 → 工具箱」里配置好的读图模型分析。

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）

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）

myagents agent list                                     # 列出所有 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>                              # 启用
myagents agent disable <id>                             # 禁用
myagents agent archive <id>                             # 归档 Agent 工作区，并暂停 proactive Channel
myagents agent unarchive <id>                           # 取消归档；若归档前是 proactive，会恢复启用
myagents agent set <id> <key> <jsonValue>               # 改单个字段（key/value 形式，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 / dingtalk / openclaw:xxx）
myagents agent channel remove <agentId> <channelId>     # 删除 Channel
myagents agent runtime-status                           # 看所有 Agent 的实时连接状态（在线/离线/uptime/最近消息）

何时用：

• "我那个 Agent 现在啥配置" → agent show <id>，按 runtime 正确解析过 effective 值
• "把 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 详见下方 §配置 Agent Channel 流程

agent set 和 agent show 互补：show 读 effective 值（含 runtime 分层解析），set 写单个字段。只使用上面列出的 canonical key；provider / permission 不是 alias，分别改用 providerId / permissionMode。providerId/model/permissionMode 会先按当前 Provider 的 credential/readiness 与 model 目录校验，再同步 Agent 权威记录、Project 兼容镜像和运行中的 Channel；Managed Codex 的 permissionMode 可传 suggest/auto-edit/no-restrictions 或产品值 plan/auto/fullAgency，落盘统一规范化为产品值。full-auto 无法无损映射（它保留 workspace-write sandbox，而 fullAgency 会投影成 no-restrictions），因此 setter 会拒绝。复杂 Channel 改动走 agent channel，别用 agent set channels——会被拒。

Agent Runtime 发现（runtime）

myagents runtime list                                   # 4 个 runtime（builtin/claude-code/codex/gemini）的装机情况 + 版本
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 写法

何时用：

• 在跑 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 清单（Codex/Gemini 会 spawn CLI 查）和自己的 permissionMode 枚举（suggest / auto-edit / full-auto ≠ 内置的 auto / plan / fullAgency）——别混。

Skills（skill）

myagents skill list                                     # 已装 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                                     # 把 ~/.claude/skills 里用户自己装的同步过来

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

定时与未来自动化 Task

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 上下文，不是独立任务中心任务。

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 的通用命令索引。

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	语义