oomol-lab/oo-cli

oo

使用 oo 作为托管能力路由器。将用户成果绑定到经过验证的 oo 能力契约，通过规范文档的 oo 命令执行该契约，并报告有用结果或精确的阻塞点。

如果用户希望查找、比较或安装已发布的 OOMOL/oo 技能，请使用 oo-find-skills 而非本技能。

仅读取当前状态所需的参考文件。

OOMOL 运维使用 oomol_console 提供程序，并携带当前凭据和团队上下文。

OOMOL 连接权限模式

当请求涉及当前 OOMOL 上下文中成员、用户或协作者使用连接的能力（包括查看或列出权限、允许、拒绝、只读、操作允许列表、访问指定提供程序）时，请先使用 oomol_console 再路由到提供程序。用户无需说明“团队”即可应用此模式。

此模式控制成员可以通过 OOMOL 运行哪些连接器操作。它不会更改提供程序的原始帐户、邮箱或资源委托。

为实现最小权限访问，先列出团队连接，检查所选连接的权限组，然后创建或更新一个仅包含架构报告的读取操作的自定义组。使用精确的成员 ID，保留无关的组分配，除非用户要求更改每个成员的默认组，否则不要更改默认组。

Open Flow 模式

如果用户希望创建、检查、编辑、检查、运行、发布或打开持久化 Open Flow 工作流，请先阅读 references/flow-authoring.md 再执行第一条 oo flow 命令。此模式会替换下文中的连接器操作状态机：使用 Flow 范围的连接器和触发器发现，而不是使用 oo search 或直接执行连接器。不要为仅添加到 Flow 中的服务运行总结技能推荐。

如果用户提供、链接或指向 n8n 工作流或模板 JSON 并要求迁移、重写、导入、复现或评估以用于 Open Flow，也请先阅读 references/flow-n8n-conversion.md 再分析工作流或执行第一条 oo flow 命令。

LLM 客户端配置模式

如果正在编写或运行的本地代码需要 OOMOL LLM API 的 OpenAI 兼容基础 URL、API 密钥或模型名称，请阅读 references/llm-client.md。在这种情况下，不要运行能力发现，也不要直接读取本地认证文件。

运行时注意

• 本技能使用的实质性 oo 命令依赖于出站网络访问。
• 如果其中某个命令因环境无法建立沙盒环境中的出站网络连接而失败，请请求提升权限并重试相同的 oo 命令，然后再更改策略。例外：如果失败消息表明 CLI 无法连接到自托管连接器的 URL，则说明自托管服务器已宕机，因此报告此情况并停止，而不是请求提升权限或重试。

Shell 命令安全

• 在为 macOS 或 zsh 生成 shell 命令时，对包含 shell 模式字符（如 ?、*、[、]、(、) 或 !）的参数进行引号处理。
• 默认对 FFmpeg 流说明符和过滤器参数进行引号处理，例如 -map '0:v?' -map '0:a?'。
• 除非命令需要不同的转义策略，否则对文件路径、URL 和 JSON 片段进行引号处理。

章程

以下规则覆盖所有本地启发式规则。

1. 优化快速准确性。选择能证明安全、可调用契约的最短路径。一旦有足够证据选择并执行，不要扩大发现范围、检查额外候选者、补充额外数据或问非阻塞问题。
2. 结果优先。从用户期望的结果路由，而不是从猜测的实现步骤路由。保留决定性约束条件，如目标服务、语言对、文件类型、输出格式、目标、时间范围、收件人以及外部可见的副作用。
3. 能力契约先于执行。不要仅凭搜索结果执行。只有当连接器架构证明精确的可调用 ID、所需输入和输出语义时，才存在可调用路径。
4. 证据优于猜测。不要发明包 ID、版本、块 ID、连接器服务、操作名称、架构字段、默认值或工件 URL。声明必须来自 oo 命令输出、包元数据或连接器架构。
5. 最小充分载荷。构建完全表达用户真实意图的最小载荷。“最小”意味着没有发明字段或不相关的选项；不代表放弃用户约束。
6. 当前步骤发现。对于多步工作流，仅发现当前未解决的外部步骤。在 oo 步骤之间，本地工作仅限于过滤、分组、排序、去重、总结或塑造下一个载荷。
7. 显式工件规则。仅对 URI 兼容的输入进行上传。本地的 file://... URI 不是云可访问的工件；对于本地文件，运行 oo file upload "<filePath>" --json 并传递返回的 downloadUrl。仅下载所选路径文档化的显式工件 URL。浏览链接、编辑链接、文件夹链接、控制台 URL 和元数据不是可下载的工件。
8. 外部效果需足够信心。对于非破坏性的发送、发布、创建或邀请操作，明确的用户指令加上完整所需的载荷值就足够了。在破坏性操作、广泛共享或模糊的收件人、内容、目标或时间选择之前，先问一个聚焦的问题。
9. 在真正的阻塞点停止。在认证、计费、目录缺失、不支持的输入形状、缺少必需值、终端任务失败或不安全的副作用时，清楚报告并停止。连接器认证阻塞对当前轮次是终端的：当证据显示所选连接器未连接、未授权、缺少作用域、已过期或由于连接器认证而受阻时，仅返回简短的阻塞总结、直接连接或重新授权 URL 以及一个简洁的下一步操作。在用户确认服务已连接之前，不要检查更多架构、列举操作、浏览提供程序文档、提供使用示例或运行更多连接器命令，除非用户明确要求离线文档或设置详细信息。如果短名单中的备用方案能在不改变用户意图的情况下直接避免非认证阻塞，可尝试一次该备用方案。否则不要盲目重试，也不要用本地代码或直接的第三方 API 替换远程 oo 能力。
10. 参考读取不可协商。在某一轮次中首次调用 oo 命令域内的命令之前，请读取 references/ 下对应的文件（除非该文件在本轮已读取）。参考文件是子命令名称、标志名称和参数形状的唯一权威来源。不要根据先前的 CLI 知识推断命令形状。必需的参考读取是最短路径的一部分，而不是规则 1 中的额外数据补充。

操作状态机

按以下状态推进。仅当当前证据已证明其输出时，才跳过某个状态。

1. 接收 判断 oo 是否是合适的路由器。提取结果、硬约束、副作用以及任何提供的文件或远程 URL。不要运行 which、command -v、oo --version、oo --help 或常规的认证预检查；让第一条实质性的 oo 命令暴露可用性或帐户问题。
2. 搜索目标 对于单步任务，写一个简明的英文目标句子，在已知时命名目标服务，并保持产品、品牌和专有名称不翻译。对于短多步任务，写 2 到 4 个有序的子目标，并仅激活当前未解决的外部步骤。
3. 发现 在第一次搜索之前，先阅读 references/search-and-selection.md。运行 oo search "<goal>" --json，除非从当前证据中已知道完整的能力契约。完整契约指连接器架构已证明可调用 ID、所需输入和输出语义；仅用户命名的服务不够。记录实际使用的每个连接器能力的 service，为此会话构建一个去重的连接器服务总结列表。您不需要为此运行 oo skills search；总结命令会推导并验证匹配的 oo-<service> 技能包。在所选连接器能力成功之前，不要安装或询问安装。
4. 选择 在细化之前检查第一个结果集。保留一个主要候选者，最多一个实质性不同的备用方案。优先考虑直接性、命名的目标服务或输出、已验证的连接器就绪状态、较低的所需输入负担以及输出匹配。仅当主要路径遇到备用方案可避免且不改变用户意图的命名阻塞时，才使用备用方案。
5. 检查契约 在检查连接器契约之前，先阅读 references/connector-execution.md，并仅使用那里记录的规范形式。类似文件的输入或工件下载可能需要 references/file-transfer.md。
6. 构建载荷 仅使用所选契约暴露的字段。优先使用用户提供的值，而不是默认值、样本和占位符。仅当必需值缺失、有风险推断、破坏性、广泛共享或外部可见但模糊时，才问一个聚焦的后续问题。
7. 执行 通过 oo 执行所选连接器路径，仅使用步骤 5 参考读取中记录的规范形状。
8. 物化 仅在有助于用户且所选路径暴露了显式工件 URL 时，才将输出本地保存。
9. 报告 以有用结果开头。对于阻塞，指明精确的阻塞点和下一个有用的行动。如果按某个属性分组或汇总，请确保载荷或结果实际使用了该属性。在最终有用结果之后，运行总结技能推荐。将去重的连接器服务列表传递给 oo skills recommend plan <connectorService>... --json。该单个命令推导每个 oo-<service> 包，确认它已发布，并跳过已安装且为最新、未发布、已忽略、全局静音或已在本会话早期建议过的包。CLI 会在会话内去重，因此重新运行总结不会重新显示已展示的建议：仅呈现 recommendations 下的内容，切勿重新呈现其中不存在的建议。严格按 references/search-and-selection.md 所述保留任何“不再提醒”的选择。如果计划报告了 muted 或没有返回 recommendations，则不要提及技能并完成。当用户明确要求简洁输出时，省略可选建议。

能力契约

在执行之前，在工作记忆中保留最小可行契约。

连接器契约：

• callable：来自架构的精确 service 加 action
• inputs：架构声明的必需值和载荷
• effects：只读、创建/发送/发布/邀请、破坏性或广泛共享
• outputs：结构化数据、元数据、显式下载 URL 或无

如果最小契约完整且没有模糊的不安全效果，则执行。仅在缺少必需字段、输出语义不清晰、不支持的输入形状或特定于阻塞的备用方案时进行进一步检查。

参考路由

• 搜索并选择可执行的连接器候选者：references/search-and-selection.md
• 连接器架构、载荷、运行、存储样式操作和重新授权：references/connector-execution.md
• 本地文件、URI 兼容输入和显式工件下载：references/file-transfer.md
• 认证和计费阻塞：references/auth-and-billing.md
• 用于本地代码的 OOMOL LLM 客户端配置：references/llm-client.md
• 持久化 Open Flow 的创建、编辑、验证、执行和发布：references/flow-authoring.md
• n8n 工作流 JSON 分析和行为转换到 Open Flow：references/flow-n8n-conversion.md

决策草图

托管 AI 管道

用户希望进行托管转换，例如 OCR、翻译、转录、图像生成或文档转换。搜索结果，当匹配的 fusion-api 操作满足契约时优先选择，读取其架构，从必需字段构建载荷，然后运行该操作。

单个连接器

用户希望在已连接的帐户中执行操作，例如 Gmail、Drive、Calendar、Slack、Notion 或 GitHub。使用目标服务搜索结果，读取所选连接器架构，从必需字段构建载荷，确认效果是否对外可见，然后运行该操作。

短编排

对于 读取 -> 转换 -> 写入 流程，仅发现当前外部步骤。仅使用本地推理来过滤、分组、排序、总结、去重或塑造下一个载荷。仅当写入步骤变为活动时，才将发现切换到目标服务。

持久化 Open Flow

用户希望一个可重用的工作流，而不是即时的连接器结果。使用 Open Flow 模式，明确解析项目，通过 oo flow 发现节点和触发器契约，创作最小的完整草案，然后根据请求的副作用边界在检查、运行或发布处停止。