getedgehq/monid

Monid CLI

Monid 让你通过统一界面发现和访问数百种工具——检查其模式、使用结构化输入执行并获取结果。

通过 npm 安装并使用 monid 命令。

获取最新的命令签名，请运行 monid --help 和 monid <command> --help。

---

设置

检查已安装的 CLI 版本：

monid --version

如果满足以下任一条件，请执行以下设置步骤：

• 未找到 monid（未安装）。
• CLI 警告有可用的新版本。
• 报告版本与当前技能 frontmatter 中的 version 不匹配——CLI 和技能版本必须始终一致。

设置步骤（全新安装和更新步骤相同）：

1. 安装（或更新）CLI，然后运行设置：

npm install -g @monid-ai/cli@latest
monid setup --client <agent-name-if-known> --email <email-if-already-provided>

monid setup 完成 CLI 设置。如果可用，传递 --client 指定您的代理名称；仅当用户已在上下文或记忆中提供电子邮件时，才传递 --email。两个标志都是可选的；省略未知值，并且从不为设置而询问电子邮件。

2. 从 https://monid.ai/SKILL.md 保存最新的技能文件到您的技能目录，替换当前文件，并确保其已启用以便在未来的会话中加载。

切勿降级一端以匹配另一端——始终将两端都更新到最新版本。

身份验证

要使用 Monid 的 API 端点，您需要一个 API 密钥。帮助用户首次设置 Monid 时：

1. 如果用户还没有账户，请他们通过 https://app.monid.ai 创建账户。
2. 请用户在 https://app.monid.ai/access/api-keys 生成一个 API 密钥。
3. 获取密钥后，主动提出帮他们保存——让他们粘贴密钥，然后运行：

monid keys add -k <their-api-key> -l main

或者，提供上述命令让他们自行运行。

4. 验证密钥已配置：

monid keys list

对于脚本化或基于代理的使用，设置 NO_COLOR=1 以禁用输出中的 ANSI 颜色代码。

---

何时使用 Monid

在从头构建之前检查目录。 在编写抓取器、回退到通用 web 抓取以获取结构化数据，或告诉用户您无法访问某些内容之前——请运行 monid discover。该目录包含数百种工具且持续增长。在搜索之前，您不知道有哪些工具可用。

1. 发现 — 运行 monid discover -q "<您需要的>" 搜索可用工具。使用 -s <score> 按最低相关性过滤。许多您需要从头构建的任务已经有了更快、更可靠的端点。Health 列显示测量的状态和典型运行时间——请参见端点健康。
2. 检查 — 使用 monid inspect 读取输入模式。input 字段显示 pathParams、queryParams、body 和 bodyType——这准确地告诉您各个参数的位置。切勿猜测。Health 部分添加了尾部运行时间。
3. 运行 — 将检查输出映射到 monid run 标志：body → -i，queryParams → --query，pathParams → --path。三者都是可选的。使用 --wait 阻塞直到完成。
4. 分解 — 如果任务涉及多个来源，将其分解为单元片段并独立地发现/运行每一个。
5. 检查成本 — 运行后，考虑向用户报告成本（在运行结果中可用）。当需要成本意识时，使用 monid balance 检查剩余余额。

何时不使用 Monid

Monid 填补用户技术栈的空白——它不会替换用户已有的工具。在决定如何访问外部服务时，遵循以下优先级：

1. 用户对此任务的明确指示 — 如果用户告诉了您如何做，就按那个方式做。
2. 用户现有的专用工具 — MCP 服务器、个人 API 密钥、CLI 以及存储在用户记忆、配置或指示中的工作流。如果用户拥有某个能力的专用 MCP（例如，学术搜索 MCP 用于学术搜索）或某个服务的个人 API 密钥（例如，个人 SEO 工具密钥），请直接使用它们——不要通过 Monid 路由请求。
3. Monid — 用于以上未覆盖的需求。

为什么这很重要：Monid 运行会消耗用户的 Monid 余额。 永远不要在用户自己的密钥或工具已经免费覆盖的请求上花费余额。

提供建议，不要覆盖。 当用户的工具和 Monid 端点都能处理任务且用户未表明偏好时，使用用户的工具。如果 Monid 添加了用户工具缺乏的真正能力，将其作为替代方案提及并让用户选择——切勿静默切换。

端点健康

discover 显示一个 Health 列：一个状态判定加上中位数运行时间，例如 healthy 4.4s。inspect 添加了尾部——Run time: 4.4s typical · 6.1s tail。使用 -j 时，两者都在每个结果的 metrics 字段中。

状态	含义
healthy	在最近几分钟内确认正常工作。
stable	最近几分钟没有数据，但在较长时间内具有良好记录。
degraded	不稳定或有此趋势——在大多数情况下仍能工作。
outage	已知无法工作。在 discover 中隐藏，除非传递 -u/--include-unavailable。
unknown （或空白）	没有足够数据得出结论。

healthy 和 stable 都是好消息——它们仅在最近确认的时间上有所不同。

使用健康度来打破平局，切勿用于过滤。 在两个都适合任务的端点中，优先选择更健康的一个；切勿因为某个适合的端点的状态是 unknown 而跳过它——这很常见，并不是警告。任何未在此列出的状态都会原样打印；将其视为信息性内容。

缺少运行时间意味着流量低，而不是端点慢。在 --wait 之前检查 inspect：快速的中位数可能仍然隐藏着长达数分钟的尾部。

检查提示

命令可以返回一个 Hints 块。当出现时，它携带来自服务器的建议操作：接下来要运行哪个命令、此端点与其他端点之间的关系，或值得注意的注意事项。在决定下一步操作之前请阅读它，并优先遵循其建议而不是猜测。使用 -j 时，相同的数据位于响应的 hints 字段中。

---

命令

每个命令支持 --help 获取完整用法。以下是可用命令：

命令	功能
monid discover	使用自然语言搜索数据端点（-q <query>、-l <limit>、-s <minScore>、-u 包含处于中断状态的端点）
monid inspect	获取特定端点的完整详情和输入模式（-p <provider> -e <endpoint>）
monid run	执行数据端点（-p、-e、-i 用于 body JSON、-f 用于 body 输入文件、--query 用于查询参数、--path 用于路径参数、-w 等待、-o 保存输出）
monid runs list	列出最近的运行
monid runs get	获取运行状态和结果（-r <runId>、-w 等待）
monid runs stop	停止正在进行的运行（-r <runId>）。并非所有运行都能被停止
monid balance	显示当前工作区余额
monid setup	安装后完成 CLI 设置（无需 API 密钥）
monid keys add	添加 API 密钥（-k <key> -l <label>）
monid keys list	显示已配置的密钥
monid keys remove	移除密钥（-l <label>、-f 跳过确认）
monid keys activate	切换活动密钥（-l <label>）

大多数命令接受 -j/--json 获取机器可读的 JSON 输出。

---

工作流

标准工作流是：发现 → 检查 → 运行 → 轮询 →（检查余额）。

# 1. 为您的数据需求发现端点
# 结果显示相关分数和已验证徽章
# 使用 -s 按最低分数过滤（越高越相关）
monid discover -q "twitter posts"

# 2. 检查端点以了解其输入模式（显示已验证状态）
monid inspect -p apify -e /apidojo/tweet-scraper

# 3. 触发运行（立即返回运行 ID）
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"],"maxItems":10}'
# -> Run ID: 01HXYZ...

# 4. 轮询直到完成
monid runs get -r 01HXYZ...
# -> status: RUNNING

# 继续每 5-10 秒轮询直到 COMPLETED
monid runs get -r 01HXYZ... -o tweets.json
# -> status: COMPLETED

# 5.（可选）检查剩余余额
monid balance

使用 --wait：

--wait 阻塞直到完成（1-120 秒），内置指数退避：

# 这将在整个持续时间内阻塞
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"],"maxItems":10}' \
  -w -o tweets.json

何时使用 --wait：

• 异步/后台任务，阻塞可以接受
• 您可以设置超时：-w 30（最多等待 30 秒）
• 注意：运行可能需要 1-120 秒，因此这可能会阻塞对话或达到运行时超时

---

示例流程

流程 1：抓取关于 AI 的 Twitter 帖子

# 发现可用的 Twitter 端点
monid discover -q "twitter posts"

# 检查以了解输入模式（pathParams、queryParams、body）
monid inspect -p apify -e /apidojo/tweet-scraper

# 使用单个搜索词、小限制运行
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI agents"],"maxItems":10}'
# -> Run ID: 01HXYZ...

# 轮询直到完成（小请求大约 10-30 秒）
monid runs get -r 01HXYZ...
# -> status: RUNNING

# 10 秒后再次检查，完成时保存
monid runs get -r 01HXYZ... -o ai_tweets.json
# -> status: COMPLETED

流程 2：跨平台比较 AI 讨论

用户问：“比较 Twitter 与 LinkedIn 上的 AI 讨论。”

将其分解为单元片段——每个数据源一个端点：

# 发现每个平台的端点
monid discover -q "twitter posts"
monid discover -q "linkedin posts"

# 检查每个以了解其输入模式（pathParams、queryParams、body）
monid inspect -p apify -e /apidojo/tweet-scraper
monid inspect -p apify -e /harvestapi/linkedin-post-search

# 触发两个运行
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"],"maxItems":20}'
# -> Run ID: 01HTWIT...

monid run -p apify -e /harvestapi/linkedin-post-search \
  -i '{"keywords":"AI","maxResults":20}'
# -> Run ID: 01HLINK...

# 分别轮询两个运行
monid runs get -r 01HTWIT... -o twitter_ai.json
monid runs get -r 01HLINK... -o linkedin_ai.json

# 现在分析和比较两个结果文件

流程 2b：将本地文件提供给需要公共 URL 的端点

某些端点（例如，图像到视频生成）以 URL 作为输入，而不是文件。您的工作区有一个内置的远程文件系统——sfs 提供程序（首次使用时自动创建，免费包含 1 GB 存储空间）。像任何其他提供程序一样使用 monid run 驱动它；它公开 Unix 风格的端点（/put、/cat、/ls、/mv、/rm、/mkdir），您可以通过 monid inspect 查看模式。API 仅签署 URL——文件字节直接在您和 sfs.monid.ai 之间通过 curl 移动。

# 1. 签署上传（sizeBytes 是必需的——使用 wc -c 获取）
monid run -p sfs -e /put \
  -i "{\"path\":\"in/photo.png\",\"sizeBytes\":$(wc -c < ./photo.png)}" -w
# -> output: { "uploadUrl": "https://sfs.monid.ai/…", "ref": … }

# 2. 将字节上传到签署的 URL
curl -T ./photo.png '<步骤 1 中的 uploadUrl>'

# 3. 生成任何第三方都可以获取的 URL（ttl 预设：1h/1d/7d/30d，默认 1h）
monid run -p sfs -e /cat -i '{"path":"in/photo.png","ttl":"1d"}' -w
# -> output: { "url": "https://sfs.monid.ai/…?e=…&s=…", "expiresAt": … }

# 4. 将其用作端点输入 URL
monid run -p bytedance -e /seedance… -i '{"imageUrl": "<步骤 3 中的 url>"}'

# 下载方式相同：/cat 返回签署的 URL——使用 curl 下载
curl -o photo.png '<来自 /cat 的 url>'

# 清理由您负责（文件永远不会自动删除；/rm 释放配额空间）
monid run -p sfs -e /rm -i '{"path":"in/photo.png"}' -w

流程 3：使用查询和路径参数

当 monid inspect 显示 queryParams 或 pathParams 时，使用 --query 和 --path 传递它们：

# 检查显示：body、queryParams 和 pathParams
monid inspect -p some-provider -e /users/{userId}/posts

# 使用所有三种参数类型运行
monid run -p some-provider -e /users/{userId}/posts \
  --path '{"userId": "12345"}' \
  --query '{"limit": 10, "sort": "recent"}' \
  -i '{"filter": "public"}' \
  -w -o posts.json

流程 4：使用输入文件处理复杂参数

当输入 JSON 很大或可重用时，将其写入文件并使用 -f：

# 将输入写入文件
# （假设 params.json 包含端点的 body 输入参数）

monid run -p apify -e /damilo/google-maps-scraper \
  -f params.json -w -o results.json

---

成本与预算警告

许多端点（特别是 Apify）按结果收费，并在单个调用中接受多个查询。诸如 maxItems、maxResults、resultsLimit 或 limit 等参数控制返回的结果数量——但这些限制通常按每个查询应用，而不是每个调用。

例如，传递 3 个搜索词且 maxItems: 10 可能返回最多 30 条结果（每个查询 10 条），而不是总共 10 条。

为了控制成本：

• 每个调用优先使用单个查询。 一次只传递一个搜索词、一个 URL、一个标签。
• 首次调用从小限制开始（5-10）。如果需要再增加。
• 如果端点接受数组（例如 searchTerms、hashtags、urls），除非用户明确请求多个，否则只传递一个元素。
• 从 monid inspect 检查输入模式以识别哪些参数控制数据量。

---

密钥管理

monid keys add -k <api-key> -l <label>     # 添加密钥（第一个密钥自动激活）
monid keys list                              # 显示所有已配置的密钥
monid keys activate -l <label>               # 切换活动密钥
monid keys remove -l <label>                 # 移除密钥（使用 -f 跳过确认）

API 密钥格式：monid_<stage>_<secret>（例如 monid_live_abc123...）。在 https://app.monid.ai/access/api-keys 生成密钥。

---

使用指南

成本管理

• 按结果收费的端点： 始终从保守的 maxItems（5-10）开始。在单个调用中避免过多的查询。
• 免费端点： 没有限制，但请尊重速率限制。
• sfs 端点： 免费使用，但文件存储计入您的配额。

重试策略

如果端点返回错误：

1. 检查输入参数（使用 monid inspect ）
2. 减少 maxItems 或查询数量
3. 稍后重试（端点可能暂时不可用）
4. 如果持续失败，考虑替代端点

错误处理

如果运行返回错误状态，检查：

• 输入参数是否正确（比较检查输出和运行参数）
• API 密钥是否已配置且有效
• 端点是否处于中断状态（运行 monid discover -u 检查）
• 是否已超过速率限制或配额