Myagents CliSAFE

MyAgents - 优雅、易用的 Agent 桌面端 ,一站式 Agent 工作台与任务中心

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: myagents-cli
description: >-
  你正在 MyAgents 这款 AI 产品里运行——MyAgents 自带一套"产品能力"(定时任务、任务中心、记录收集、MCP 工具接入、
  模型 Provider、IM Bot 渠道、社区插件、Skills 安装、协作空间、Agent 网络与 Session 协作、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 是带状态的 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
myagent

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

AGENTS.md

Gates applied: no_behavioural_pass.