--- name: hacklyc/myagents-cli source: https://app.decimal.ai/s/hacklyc-myagents-cli@2/SKILL.md source_sha256: d398d338497e --- # 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 ` 就能跑。它通过 HTTP 走 Sidecar Admin API（端口由环境变量 `MYAGENTS_PORT` 注入）。 - 遇到 `command not found`：让用户重启一次应用触发 CLI 同步 - 遇到 `ECONNREFUSED`：Sidecar 没起来，让用户检查应用是否在运行 ## 使用模式 1. **探索先行**：不熟的命令组用 `myagents --help`；不知道某个 runtime 支持什么 model/permissionMode 用 `myagents runtime describe `，**不要靠猜** 2. **按 leaf 契约预览**：只有精确 leaf help 明确声明支持的命令才使用 `--dry-run`；不支持的 mutation 会 fail closed，不能声称已预览 3. **机器可读**：加 `--json` 解析结构化输出 4. **失败即恢复**：CLI 失败响应会带 `→ Run: ` 恢复提示，照着跑就行 ## 安全规范 - **改配置前先读精确 leaf help**——该 leaf 明确支持 `--dry-run` 时先预览；未声明支持时不要假装存在 preview - **API Key**：用户在对话里明确给了你才写入；没给就引导他去 **设置 → 对应页面** 填，不要追问 - **删除前确认**：用户说"删了吧"也要回读"我要删的是 X，确认吗" ## 生效时机 - **MCP 工具变更**（增删改 / 启禁用 / 环境变量 / OAuth）：磁盘立即写入，但工具在**下一轮对话**才能调用——MCP server 在 session 创建时绑定。当前轮配完后告诉用户："发条新消息我就能用了" - **其他配置**（Provider / Agent / cron / skill / plugin / config）：写入即时生效 --- ## 命令速查 + 何时使用 ### MCP 工具（mcp） ```bash myagents mcp list # 看用户配了哪些 MCP myagents mcp show # 看某个 MCP 的完整配置（command/args/env/headers） myagents mcp add --id --type ... # 新增 myagents mcp remove # 删除 myagents mcp enable --scope # 启用 myagents mcp disable --scope # 禁用 myagents mcp test # 实际握手测试连通性 myagents mcp env set KEY=val [KEY2=val2 ...] # 设环境变量（覆盖） myagents mcp env get [KEY ...] # 读环境变量 myagents mcp env delete KEY [KEY2 ...] # 删环境变量 myagents mcp oauth discover # 探测 MCP server 是否支持 OAuth + 拿到 metadata myagents mcp oauth start [--clientId X --clientSecret Y --scopes "..." --callbackPort N] # 启动 OAuth 授权流程（会打开浏览器） myagents mcp oauth status # 看授权状态（已授权 / token 是否过期） myagents mcp oauth revoke # 撤销授权 ``` **何时用：** - "帮我接个 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 `，过期就重跑 `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 须含 tool.json + 入口脚本；不在 # ~/.myagents/tools/ 下会自动拷入）[--dry-run] myagents tool info # 看 manifest + enabled + 缺失 env myagents tool enable # 进新 session 的上下文 myagents tool disable # 从上下文隐藏（shim 仍在 PATH，可手动调） myagents tool remove [--purge] # 反注册（--purge 连工具目录一起删） myagents tool env set KEY=val # 设 per-tool 环境变量（API key；工具启动时读） myagents tool env get # 读（值已脱敏） myagents tool env delete KEY # 删 ``` **何时用：** - 用户说"把这个脚本/能力注册成工具、以后直接用" → 先走 `tool-creator` skill 把它规范化，再 `tool add` - "我有哪些自己的工具" → `tool list` - 工具报缺 API key（退出码 3）→ `tool env set KEY=<用户提供的值>` - 注册名撞系统命令会被打回（`~/.myagents/bin` 在 PATH 前列，重名会遮蔽系统命令）→ 换带领域前缀的名字 - 注册成功后 MUST 在回复中告知用户：工具名 + 干什么 + 可在 设置 → 工具箱 管理 ### 官方图片理解工具（vision） 这是 MyAgents 内置官方 CLI 工具，不属于 MCP，也不属于用户注册 `tool` 实验功能。它用于在当前会话启用“图片理解”工具时，让不支持多模态的主模型把本地工作区图片交给用户在「设置 → 工具箱」里配置好的读图模型分析。 ```bash myagents vision readme myagents vision analyze --image [--image ...] [--prompt "what to inspect"] myagents vision analyze --image --prompt-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 --name <显示名> --base-url --models [其它] myagents model remove # 删除自定义 Provider（内置的删不掉） myagents model set-key # 设 API Key myagents model set-default # 设为默认 Provider myagents model verify [--model <某个具体模型>] # 实际发一条测试消息验证 ``` **何时用：** - "帮我配 DeepSeek" → 内置 Provider 直接 `model set-key deepseek ` → `model verify` - "我要用一个新厂商" → 详见下方 §配置模型服务流程 - "把默认改成智谱" → `model set-default zhipu` - "我之前加的那个废 Provider 删了吧" → `model remove ` ### Agent + Channel（agent） ```bash myagents agent list # 列出所有 Agent myagents agent current --json # 只看当前 Agent/workspace/Session myagents agent list --active # 只列出未归档 Agent 工作区 myagents agent list --archived # 只列出已归档 Agent 工作区 myagents agent show # 看某 Agent 的 effective 默认（runtime/model/permissionMode） myagents agent enable # 启用 myagents agent disable # 禁用 myagents agent archive # 归档 Agent 工作区，并暂停 proactive Channel myagents agent unarchive # 取消归档；若归档前是 proactive，会恢复启用 myagents agent set # 改单个字段（key/value 形式，value 必须是合法 JSON） # key 仅限 enabled/runtime/runtimeConfig/providerId/model/permissionMode # id / channels 用专用命令；未知 key 会在写盘前拒绝 myagents agent channel list # 列出某 Agent 的所有 Channel myagents agent channel add --type <平台> --<凭证flag> ... # 添加 Channel（平台 = telegram / dingtalk / openclaw:xxx） myagents agent channel remove # 删除 Channel myagents agent runtime-status # 看所有 Agent 的实时连接状态（在线/离线/uptime/最近消息） ``` **何时用：** - "我那个 Agent 现在啥配置" → `agent show `，按 runtime 正确解析过 effective 值 - "把 Agent X 的 model 改成 Y" → `agent set X model '"Y"'`（注意 JSON 字符串要双层引号） - "把 permissionMode 改成 plan" → `agent set X permissionMode '"plan"'` - "项目结束了，先收起来" → `agent archive `；需要恢复时用 `agent unarchive ` - "飞书 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） ```bash myagents runtime list # 4 个 runtime（builtin/claude-code/codex/gemini）的装机情况 + 版本 myagents runtime list --json # 机读：installed/version/path myagents runtime describe # 某 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） ```bash myagents skill list # 已装 skill（全局 + 项目级） myagents skill info # 某 skill 的详情 myagents skill add [--scope user|project] [--plugin X] [--skill Y] [--force] [--dry-run] myagents skill remove # 删除 myagents skill enable # 启用 myagents skill disable # 禁用非 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` | 直连 zip/tar.gz | **不支持**：GitLab、私有仓库、git SSH。 **何时用：** - 用户贴 GitHub 链接或 `npx skills add ...` → 直接 `skill add "<原文>"`，resolver 自己剥前缀 - "装 React 最佳实践" → `skill add vercel-labs/skills --skill react-best-practices` - 报错 `该仓库是 Claude Plugins 市场` → 按提示加 `--plugin `，比如 `skill add anthropics/skills --plugin document-skills` 一次装 docx/pdf/pptx/xlsx - 报错 `技能 X 已存在` → 跟用户确认要不要 `--force` 覆盖 - 用户在 `~/.claude/skills/` 自己塞了东西 MyAgents 看不见 → `skill sync` ### 定时与未来自动化 Task ```bash myagents task readme # 统一自动化模型与当前命令 myagents agent current --json # 仅诊断当前 Agent/workspace/Session myagents task get --json # 权威配置与运行状态 myagents task run # 首次启用 Todo Task myagents task start # 恢复 schedule；看回执 nextExecutionAt myagents task stop # 暂停并停止活跃执行 myagents task runs [--limit N] # 看 AI 执行历史 myagents task run-now # 绕过 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 `、`--max-executions <正整数>`、`--ai-can-exit ` 设置已有结束条件；deadline 是最晚停止时间，不是延迟开始。 - 当前会话进入 Goal 后，你完成了用户目标 → `goal update --status complete` - 你连续尝试后确认缺关键输入/外部状态，无法继续推进 → `goal update --status blocked` - 用户问"现在目标是什么/状态如何" → `goal get` - 不要用 `goal update` 表示用户取消；取消由 UI/宿主控制。 ### 任务中心（task / thought） 用户要定时、未来唤醒、循环执行或满足条件才叫醒 AI 时，统一加载 `myagents-task-automation`。command Detector 的协议、fixture 和测试由该 Skill 按需路由到自己的 reference；这里仅保留 Task Center 的通用命令索引。 ```bash myagents thought list [--tag X --query X --limit N] # 列想法（用户先记下来、后续派发的轻量条目） myagents thought create '...' # 记一条想法（首选：单引号包裹防 shell 注入； # 用 #xxx 内联打 tag —— 没有 --tag flag） myagents thought create --content "..." # 显式 flag 形态，跟单引号等价 myagents thought create --content-file # 内容含多行 / CJK / shell 元字符 / # Windows 下单引号失灵时的保底通道 myagents task list [--status X --tag X --query X --limit N --includeDeleted] # 默认当前 workspace；JSON 是紧凑投影 myagents task get # 详情 + statusHistory + 各 .md 文档路径 myagents task create-direct --name "..." \ [--taskMdFile | --taskMdContent "..."] \ [--runtime X --providerId X --model X --permissionMode X --runtimeConfig --mcpEnabledServers a,b] \ [--executor agent --executionMode once --runMode X --tags x,y --sourceThoughtId X] myagents task create-from-alignment --name "..." [--run] [其它同 create-direct] # 从 AI 对齐会话物化任务（workspaceId/Path/sourceThoughtId 自动继承） # --run 创建后立刻派发，省一步 myagents task run # 派发 todo 任务 myagents task start # 按保留 anchor 恢复，以 nextExecutionAt 为准 myagents task stop # 暂停 schedule 并停止活跃执行 myagents task runs [--limit N] # 查看最近 AI 执行历史 myagents task exit [--reason "..."] # 仅在允许 AI exit 的 scheduled Task 内 myagents task rerun # 从 blocked/stopped/done 重新派发 myagents task update-status [--message "..."] # 状态机：todo→running→verifying→done（或 →blocked/stopped）、done→archived myagents task append-session # 把一个聊天 session 关联到任务（任务过程中开了新会话用这个登记） myagents task archive [--message "..."] # 归档（仅用户可操作；AI 走会被拒） myagents task delete # 不可恢复地移出产品使用；不删工作区脚本 ``` `create-direct` 和 `task list` 正常会继承当前 workspace，不需要先枚举 Agent 再手工拼 `workspaceId/path`；只有明确跨 workspace 时才传两者。`myagents agent current --json` 是紧凑诊断入口，不是 happy path 前置步骤。 创建 scheduled/recurring Task 可用 `--deadline `、`--maxExecutions <正整数>`、`--aiCanExit true|false` 设置结束条件；quiet Detector 检查不消耗 maxExecutions。固定 interval 第一次 `run` 默认约 2 秒后产生首次 tick；要延后首次机会时传 `--startAt `。Cron 等下一个墙钟点，scheduled 等 `dispatchAt`。 **任务级 runtime/provider/model/permissionMode 覆盖**：`create-direct` / `create-from-alignment` 支持仅对该任务生效的覆盖 flag，**不会改 Agent 工作区默认**。典型场景："实现用 Claude Code、review 用 Codex" → 创两个任务，`--runtime` 不一样，工作区配置不变。 | Flag | 语义 | |------|------| | `--runtime` | `builtin` / `claude-code` / `codex` / `gemini`，不传则继承 | | `--providerId` | builtin Provider id；必须与 `--model` 成对设置，不传则继承 | | `--model` | 值取决于 runtime，**先 `runtime describe ` 查** | | `--permissionMode` | 值取决于 runtime，**同样先 `runtime describe`** | | `--runtimeConfig` | JSON 对象字符串，runtime 专属配置（罕用） | | `--mcpEnabledServers` | 逗号分隔 MCP id；`""` 表示该任务显式不用 MCP | `task update ` 清覆盖用显式 flag：`--clearProviderOverride` / `--clearRuntimeOverride` / `--clearMcpOverride`。注意 `--mcpEnabledServers ""` 不是清回继承，而是显式无 MCP。 **何时用：** - "看我还有啥没做完的" → `task list --status running` / `task list` - "这个想法派发出去" → `task create-from-alignment --name "..." --run` - "创个 review PR 的任务用 codex" → `task create-direct ... --runtime codex --model gpt-5.2 --permissionMode full-auto` - "任务过程中我开了个新对话登记一下" → `task append-session ` - "标记完成" → `task update-status done --message "..."` - "重新跑一遍" → `task rerun ` - `task list --json` 只返回紧凑发现字段和 `sessionCount`，不会展开历史 `sessionIds`；拿到 ID 后用 `task get` 读取完整状态与各 `.md` 文档路径 **验证与恢复**：CLI 在转发给 Rust 前会前置校验 `--runtime` / `--model` / `--permissionMode`，不合法直接拒绝并带 `→ Run: myagents runtime describe ` 指引；输出会打印 `overridesRequested` vs `overridden`，传了 override 但没落到持久化态会明确提示 drift。 **归档与删除**：`task archive` 是仅用户可执行、长期可恢复的归档状态，Agent 调用会被 Task authority 拒绝；`task delete` 经确认后不可恢复，没有 30 天恢复或 undelete 承诺。删除会停止调度并清平台 Trigger state/pending activation，但内部 tombstone/审计仍用于 authority 与迁移安全，工作区脚本和脚本自持状态不归 TaskStore 删除。 ### MyAgents Cloud Space（space） ```bash myagents space list --json myagents space whoami --space --json myagents space goal list --space --json myagents space assignee list --space --json myagents space issue create --space --title "..." --body-file issue.md \ [--goal ] [--assignee agent:|user:] [--attachment ...] myagents space issue list --space --goal --state todo --limit 30 myagents space issue view --space --comments --json # current Issue + latest 5 comments myagents space issue update --space --goal --json myagents space issue update --space --clear-goal --json myagents space issue update --space --human-only false --json myagents space issue comments --space --json [--limit 20] [--cursor ] myagents space issue comment get --space --json myagents space issue comment --space \ [--body-file ] [--attachment ...] myagents space issue claim --space --deliveryId --create-attached \ --workspaceId --workspacePath --name "..." --taskMdContent-file task.md myagents space issue complete --space --workspacePath \ --taskId --body-file result.md [--attachment ...] --message "completed Space issue" myagents space issue attachment add --space --file [--file ...] myagents space attachment download --space [--output myagents_files/space/file.bin] ``` **何时用：** - 普通会话先 `myagents space list --json` 选择明确的 slug；所有 Space 业务命令都必须带 `--space `，不猜“默认社区”或上次使用的 Space。 - CLI 只有在当前 Session 持久化了精确的 `spaceId + registeredAgentId` origin 时，才以该 Registered Agent 身份执行；显式 legacy Agent ID 仅作旧调用兼容。workspace 只校验执行边界，绝不用于猜测 actor。没有 Registered Agent origin 的普通 Session 始终使用当前 User 身份；origin、Space 或 workspace 不匹配会直接拒绝，不会静默降级。身份不确定时先 `space whoami`。 - 需要创建、筛选或移动 Issue 时，先 `space goal list --json`，只复制 active `data.items[].id`；不要把 Goal title 或 `goalPathLabel` 当 ID。`myagents goal ...` 是本地 Session Goal Mode，`myagents space goal ...` 是 Cloud Space Goal，两者不是同一资源。 - `issue create` 不传 `--goal` 会进入 Inbox；已发布 Issue 用 `issue update --goal ` 移动，使用 `--clear-goal` 清回 Inbox。不要用 `--goal null`、`--goal inbox` 或空字符串表达清除。更新后用 `issue view --json` 核对权威 `goalId/goalPathLabel`。 - 具体命令参数优先运行精确 leaf help，例如 `myagents space issue comment --help`；这些 help 是给 Agent 的完整调用说明。 - 收到 Space delivery → 先 `myagents space issue view --space --comments --json` 读取当前服务端状态；delivery trigger 只用于定位，不替代当前状态。 - trigger 的 comment 标记为截断 → 用 `myagents space issue comment get --space --json` 精确读取，不要扫描分页猜触发评论。 - subscription 通知只表示该 Issue 在路由时匹配订阅，不等于已经指派责任。读取当前 Issue 后，可以不做进一步动作、评论或更新而不 claim；只有确认该 Agent 应负责完成时，才用 `claim`（需要持久本地执行跟踪时再加 `--create-attached`）。Delivery 会由本地 connector 自动确认，不存在 Agent-facing ignore/handled/acknowledge 命令。 - assignment 表示责任已经明确交给当前 Agent；仍用 `claim --create-attached` 确认并建立本地 Task/Session 关联，不要 ignore 或自行取消指派。 - Issue/评论里有附件 → 用 `myagents space attachment download --space ` 下载到当前工作区，再读取本地文件。 - 需要回写结论 → `space issue comment` 可原子提交正文和附件；只有附件也合法。评论附件只属于该评论，不会跑到 Issue 顶部。 - 需要给已发布的 Issue 正文单独补附件 → 用 `space issue attachment add`，它会立即生效并触发正常的 Issue 更新投送。 - 工作完成 → 使用一次 `space issue complete --taskId ... --body-file ...`，它会原子完成 Cloud 结果评论 + Issue，再将 attached Task 标为 done；成功后不要再调用 `task update-status done`。 **安全边界：** - CLI 在 Rust 内解析并持有 User/Registered Agent token；不要让用户提供 token，也不要传显式 actor。 - Space mutation 当前不支持 preview；携带 `--dry-run` 会在网络前返回 `DRY_RUN_UNSUPPORTED`。确认写入意图后按精确 leaf help 调用，不能把失败说成已经预览。 - `--body-file`、`--taskMdContent-file` 与附件只能读取当前 workspace 内的普通文件，拒绝 symlink 和 workspace 外路径；每次最多 5 个附件、每个最多 25 MB；`attachment download --output` 也只能写在当前 workspace 内。 - `view --comments` 固定最新 5 条；更早历史使用 `issue comments --limit 20 --cursor `，有 `nextCursor` 再继续拉。 ### 社区插件（plugin） ```bash myagents plugin list # 已装的 OpenClaw 社区插件 myagents plugin install # 从 npm 安装（如 @anthropic/wechat） myagents plugin remove # 卸载 ``` **何时用：** - "装个微信插件" → `plugin install ` - "我哪里能找到飞书插件" → 让用户去 OpenClaw 仓库找 npm 包名，再 install 安装走内置 Node.js 的 npm，可能需要 10-30 秒。卸载前会检查是否有 Channel 还在用这个插件——有的话先把 Channel 移掉。 ### Claude 插件（cc-plugin） — PRD 0.2.17 ```bash myagents cc-plugin list # 已装 Claude 插件 + 启停状态 myagents cc-plugin install # 来源：owner/repo / GitHub URL / 直链 zip / file:///abs myagents cc-plugin uninstall [--purgeData] # 卸载（数据目录默认保留） myagents cc-plugin enable # 启用（下次 session 生效） myagents cc-plugin disable # 禁用 myagents cc-plugin show # 详情（含 manifest + 组件清单） ``` **与上面 `plugin` 的区别：** `cc-plugin` 是 Anthropic 官方的 Claude Plugin 协议（自带 skills/agents/MCP/hooks 的目录），落在 `~/.myagents/plugins//`；启用后由 SDK 自动装载组件。`plugin`（无前缀）则是 OpenClaw 的 IM 渠道插件，两套体系不冲突。 **何时用：** - "粘个 GitHub URL 装个插件" → `cc-plugin install owner/repo` - "装本地正在调的插件" → `cc-plugin install file:///path/to/plugin` - "禁掉 X 插件" → `cc-plugin disable X` 启停 / 安装 / 卸载后会触发 SDK 柔性重启（500ms 防抖），下一次发消息时 plugin 内组件才生效。外部 Runtime（Claude Code CLI / Codex / Gemini）下不读取这里——它们各自管自己的 plugin 体系。 ### 通用配置 + 状态（config / status / version / reload） ```bash myagents config get # 读，支持点号路径如 proxySettings.host myagents config set [--dry-run] # 写，value 是 JSON 字面量（字符串要带引号） myagents status # 应用整体运行状态 myagents version # 应用版本号 myagents reload [--workspacePath ] # 热加载配置（不重启进程） ``` **何时用：** - "现在配的代理是啥" → `config get proxySettings` - "把代理 host 改成 X" → `config set proxySettings.host '"X"'` - "应用版本" → `version` - "改完手动让它生效" → `reload`（多数命令已经自动 broadcast，这个是兜底） ### IM 媒体下发（im） ```bash myagents im send-media --file <绝对路径> [--caption "..."] # 仅在 IM Bot / Agent Channel session 内可用 myagents im readme # 拉 IM 工具完整文档 ``` **何时用：** - 你正在某个 IM 渠道（Telegram / 飞书 / 钉钉 / OpenClaw）的会话里跟用户聊，要发图片 / 视频 / 文件给对方时用 `im send-media` - `--file` 必须是绝对路径，且路径白名单：必须落在 workspace / `/tmp` / MyAgents scratch 目录之一——这是为了防 prompt injection 把 `~/.ssh/id_rsa` 之类发给聊天对方 - 不在 IM session 内调用会返回 "No IM context"，正常——这命令本来就是 session-scoped ### Agent 身份与 Session 协作（agent / session, PRD 0.4.3） 每个 user-visible Workspace 都有一个稳定 Agent identity。Agent 是工作区 及其执行默认的长期地址；`enabled=false` 只关闭 channel / heartbeat 等主动 能力，不会取消身份，也不妨碍显式发起 Session。一个 Agent 可以拥有多个 相互隔离的 Session。 ```bash # 先发现 Agent，并确认哪个是当前 CLI 调用方 myagents agent list myagents agent show # 查看某 Agent 最近可复用的历史上下文（只读，不唤醒） myagents session list --agent [--limit 10] # 在目标 Agent 下开启干净的新上下文 myagents session start --agent -p "" myagents session start --agent --prompt-file # 在已知 Session 的既有上下文里继续做新工作 myagents session send -p "" myagents session send --prompt-file # 多行/长文本(>4KB)必用,跨平台稳定 # start / send 默认在目标 turn 结束后把结果推回当前 Session # 仅通知、不需要结果回流时加 --no-reply myagents session start --agent -p "" --no-reply # 只观察另一个 Session；不注入新工作 myagents session watch myagents agent --help # Agent identity 完整契约 myagents session --help # 完整用法 / EXIT CODES / 示例 ``` **何时用:** - 使用 `agent list/show`: 发现目标 Agent、当前调用方身份和目标执行默认 - 使用 `session list --agent`: 判断最近上下文是否值得复用；它不证明目标正在运行 - 使用 `start`: 需要目标 Agent 在全新隔离上下文中执行 - 使用 `send`: 另一个 session 需要做新工作、接收通知、澄清或后续指令 - 使用 `watch`: 当前任务依赖另一个 session 的工作,或用户明确希望你监听另一个 session 的当前/最新结果 - `start` 创建 fresh context；`send` 保留现有 context；`watch` 不注入工作 - **不要用**于答复当前用户(直接回复就行);不要用于给 IM peer 发消息(用 `im send-media`) - AI 身份(from label)系统会自动从你所在 session 元数据推导——你不需要也不应该手动指定 - 只使用 discovery 命令返回的 ID，不猜 ID，也不用 workspace path 充当 selector **异步语义(关键):** - `start` / `send` CLI 成功只表示首条请求已接纳，**不表示工作完成** - `start` 必须从真实 MyAgents Session 发起；目标按自己的 runtime/model/permission/MCP/plugin/tool 配置执行，不接受调用方覆盖 - `start` receipt 返回新的 `sessionId`、`messageId`；`messageId` 对应稍后 `send.result.requestEventId` - 默认期待结果推回：对方处理完后，你将在新 turn 收到 `` - `--no-reply`:仅通知,reply 不回流(对方按自己呈现路径输出) - `send` 的 target session idle/dead 不影响投递——系统会自动唤起 - `watch` 只观察目标 session 当前工作；目标已经 idle 时,CLI 会直接返回 `` 和最近结果 - `watch` 不会向目标 session 注入新 prompt；需要新工作时用 `send` - 若 `start` 返回 admission unconfirmed，保留 receipt IDs，用 `session list --agent` 辅助观察，**不要自动重试** **Windows 安全:** - `-p` 内容含 `\n` 或 > 4KB → CLI 立即 fail-fast(exit 3),提示切到 `--prompt-file` - 习惯上长 / 多行内容**永远**走 `--prompt-file`,跨平台一致 ### Generative UI Widget 设计文档（widget） ```bash myagents widget readme # 看有哪些 widget 模块（chart/diagram/interactive/dashboard/art） myagents widget readme [ ...] # 拉具体模块的完整设计规范 ``` **何时用：** - 用户让你"做个图表 / 仪表盘 / SVG 流程图"前，先 `widget readme ` 拉对应模块的完整规范（含输出格式契约、palette、组件库），**不要凭印象写** - 模块清单：`chart`（Chart.js 图表）/ `diagram`（SVG 流程图）/ `interactive`（滑块/计算器/对比卡）/ `dashboard`（多图表 + 控件）/ `art`（SVG 插画） - 渲染输出有严格 `` 格式契约——readme 开头会说明，跳读会出错 `task readme` / `im readme` / `widget readme` 都是 progressive disclosure：brief 已经在系统 prompt 里，要用时才 fetch full doc。 --- ## 典型工作流 ### 接入 MCP 工具 1. 从用户给的文档提取：server ID、类型（stdio/sse/http）、command 或 URL、所需环境变量 2. `myagents mcp add --dry-run ...` 预览 3. 给用户看预览，确认 4. 执行：`mcp add` → `mcp enable --scope both` → 配 env（如需）→ 如果是 OAuth 类的再 `mcp oauth start` 5. `myagents mcp test ` 实际握手测试 6. `myagents reload` 7. 告诉用户："发条新消息我就能用了" ### 配置模型服务（最常见、最有价值） #### 协议优先级：Anthropic 协议永远先于 OpenAI 兼容 MyAgents 基于 Claude Agent SDK，原生协议是 Anthropic Messages API。接入第三方 API 时： 1. **Anthropic 协议（最优先）**：原生协议，零转换开销，所有 SDK 能力（工具调用 / 流式 / Extended Thinking）都正常 2. **OpenAI 兼容（兜底）**：服务商只给 `/v1/chat/completions` 时用 `--protocol openai`，过协议桥接层转换，部分高级功能受限 #### 从文档提取配置 **第一步：找 Anthropic / Claude Code 接入板块（优先）** 大多数支持 Anthropic 协议的服务商，会在文档里以「接入 Claude Code」的形式呈现——MyAgents 和 Claude Code 共享 SDK，所以 Claude Code 的接入方式就是我们最原生的接入方式。 文档里搜：`Claude Code` / `Anthropic` / `ANTHROPIC_BASE_URL` / `ANTHROPIC_API_KEY` / `/anthropic`。 提取： - `ANTHROPIC_BASE_URL` → `--base-url` - 认证方式（Bearer Token vs API Key）→ `--auth-type` - 模型名称列表 → `--models` **即使文档同时给了 OpenAI 兼容方式，只要有 Anthropic 方式就用 Anthropic。** **第二步：实在没 Anthropic 才用 OpenAI 兼容** 搜：`OpenAI 兼容` / `/v1/chat/completions` / `chat completions`。 - API base → `--base-url`（通常 `/v1` 结尾或去掉 `/chat/completions`） - 加 `--protocol openai` - `--upstream-format`：多数 `chat_completions`（默认），少数新服务商支持 `responses` #### Claude Code 环境变量 → CLI flag 映射 | Claude Code 环境变量 | MyAgents CLI | |---------------------|------------| | `ANTHROPIC_BASE_URL` | `--base-url` | | `ANTHROPIC_API_KEY` | `model set-key` 设置 | | `ANTHROPIC_AUTH_TOKEN` | 同上，区别在 `--auth-type` | **`--auth-type` 选择**： - 文档说设 `ANTHROPIC_AUTH_TOKEN` → `auth_token` - 文档说设 `ANTHROPIC_API_KEY` → `api_key` - 两个都设 / 没说清 → `both`（默认，最安全） - OpenRouter 等特殊服务商 → `auth_token_clear_api_key` #### model add 完整 flag ``` myagents model add \ --id <唯一ID> # 必填 --name <显示名> # 必填 --base-url # 必填 --models <模型ID列表> # 必填，逗号分隔或多次 --models --model-names <显示名列表> # 可选，与 models 一一对应 --model-series <系列名> # 可选，默认取 provider ID --primary-model <默认模型> # 可选，默认取第一个 model --auth-type <认证类型> # 可选，默认 auth_token --protocol <协议> # 可选，anthropic(默认) 或 openai --upstream-format <格式> # 可选（仅 openai），chat_completions(默认) 或 responses --max-output-tokens <数字> # 可选（仅 openai），默认 8192 --vendor <供应商名> # 可选，默认取 name --website-url <官网> # 可选 --dry-run ``` #### 免费模型优先策略 很多 Provider 同时提供付费模型和免费模型。`model verify` 会用 `primaryModel` 发一条测试消息——如果用户还没充值，验付费模型会失败。 **策略**：Provider 既有免费也有付费时，把免费模型放在 `--models` 列表第一位，`primaryModel` 自动选中免费模型，验证更易过。**例外**：用户明确说要哪个就用哪个。 #### 完整流程 1. `model list` 看是不是已有内置 Provider 2. 是内置 → 直接 `model set-key` 3. 要新增 → `model add --dry-run ...` 预览 4. 给用户看预览，确认 5. `model add ...` 正式加 6. `model set-key ` 7. `model verify ` 8. 验证失败按报错排查： - 认证失败 → 检查 Key 和 `--auth-type` - 模型不存在 → 检查模型名称 - 余额不足 → 切到免费模型验证 - 协议不对 → `--protocol` 在 anthropic / openai 之间切 9. 视情况 `model set-default ` ### 配置 Agent Channel ```bash myagents agent channel list # 看现有 myagents agent channel add --type telegram --bot-token myagents agent channel add --type feishu --feishu-app-id --feishu-app-secret myagents agent channel add --type dingtalk --dingtalk-client-id --dingtalk-client-secret myagents agent channel remove ``` 不同平台需要不同凭证（flag 名必须与配置字段一致）。OpenClaw 社区插件（如飞书 `openclaw-lark`、微信）的 `--type` 是 `openclaw:`，并需要先 `plugin install` 装好对应插件。