using-islo

使用 Islo

在帮助用户基于 Islo 构建内容时，使用此技能。

Islo 为 Agent 提供安全的云沙箱、用于多阶段自动化的 Factory 流程、由网关管理的提供商凭据，以及生成的 SDK。作业和 Webhook 是更底层的构建块，Factory 流程会对其进行组合。沙箱中预装了 Claude Code、Cursor agent 和 Codex；如果在使用沙箱前已连接集成，它们无需在沙箱内进行身份验证即可运行。使用 islo login --tool 连接集成；对于大多数工作，default 网关配置文件会处理凭据注入。优先检索，而非依赖记忆。Islo 更新很快。

首要检查

1. 如果有文档 MCP 服务可用，请通过它搜索 Islo 文档：https://docs.islo.dev/_mcp/server。
2. 如果已安装 islo CLI，请使用 CLI 探索准确的标志：
   • islo schema
   • islo schema <command>
   • ISLO_HELP=full islo
3. 编写或编辑清单前，务必先生成脚手架：
   • Factory：islo schema factory，然后运行 islo factory line deploy line.toml --dry-run
   • Factory 集成触发器：islo factory triggers list --with-status
   • 作业：islo job init <name> → 编辑 → islo schema job → islo job deploy <name> --dry-run
   • Webhook：islo schema webhook
   • 沙箱配置：islo schema use
   • 知识：islo schema knowledge
   • 不要凭记忆编写清单字段结构——已安装的 CLI 才是事实依据
   • 将技能示例视为模式，而非可直接使用的清单
4. 在尝试使用 Claude Code、Cursor agent 或 Codex 之前，不要要求用户在沙箱内安装或验证这些工具。它们已预装，已连接的集成会提供身份验证。
5. 除非用户明确选择这种变通方式，否则不要让用户将 GitHub、Slack、模型提供商或其他提供商的令牌放进沙箱。优先使用已连接的提供商和 default 网关配置文件。
6. 对于可复用的沙箱变量和密钥，请使用 islo environment，并检查 islo schema use，了解环境如何附加到沙箱和作业。

何时使用什么

用户目标	从这里开始
自动化（默认）	Factory 流程 — factory.md
交互式沙箱或临时 Agent 工作	islo use — sandbox-lifecycle.md
Harness、模型或推理路由	agents-and-inference.md
HTTP 事件 → 沙箱，无流程编排	传入 Webhook — webhooks.md
用于 Agent 步骤的可复用策略、技能或规则	islo knowledge — knowledge.md
无需在沙箱内放置令牌的提供商凭据	gateway-integrations.md
在代码中集成产品	SDK — sdk.md
可运行的起点	factory.md — islo-labs/islo-agents
独立的单阶段作业（高级）	作业 — jobs.md

默认建议： 使用 Factory 流程实现自动化。作业是流程中的阶段构建块——除非用户明确需要不经流程编排的单阶段持久化运行或定时运行，否则他们很少会直接编写 job.toml。

选择正确的参考文档

• Factory 流程、阶段、转换、触发器、流程运行和决策暂停： 阅读 factory.md。
• Harness、模型和 Islo 推理选择（包括 Factory 中的 Islo 推理）： 阅读 agents-and-inference.md。
• 独立作业（高级）： 仅当用户明确需要不经流程编排的单阶段作业时，才阅读 jobs.md。
• 底层传入／传出 Webhook： 阅读 webhooks.md。
• 知识条目（记忆、技能、规则）： 阅读 knowledge.md。
• 沙箱创建／连接／执行／暂停／恢复／停止／删除流程： 阅读 sandbox-lifecycle.md。
• 网关配置文件、提供商集成、幻影令牌、GitHub、Slack，以及沙箱内无需令牌的模式： 阅读 gateway-integrations.md。
• 使用生成的 SDK 进行编程调用，而不是通过 Shell 调用 CLI： 阅读 sdk.md。
• 可运行的自动化示例（例如 PR 审查）： 阅读 factory.md。

工作规则

• 将 Factory 线路视为主要的自动化产品。当工作涉及多个阶段、循环、决策、计划任务、webhook 或集成触发器时，优先使用线路。
• 将 job 用作 Factory 线路中的阶段构建模块。只有当用户明确希望在没有线路编排的情况下执行单阶段持久化或计划任务时，才建议使用独立的 job.toml——参见 jobs.md。
• 使用 webhook 处理 HTTP 事件的接收与发送；Factory 线路也可以由 webhook 或集成事件触发。
• 对于交互式或临时的沙盒工作，优先使用 islo use。它会创建或重新连接沙盒，然后打开 shell 或运行命令。
• 对于可复用的沙盒环境变量或由环境管理的网关注入密钥，使用 islo environment 管理命名环境，并在创建沙盒时使用 islo use --environment <name> 应用该环境。
• 对于沙盒中的 Agent 工作，优先使用 islo use --agent claude、islo use --agent cursor 或 islo use --agent codex；使用 --task 设置后台提示词。
• 对于 Factory 阶段 job 中的 Agent 工作，优先使用 run_agent 步骤，并根据 islo schema job 的要求嵌套绑定提示词。除非 islo schema job 显示必须使用 exec 模式路径，否则不要通过 shell 封装 claude、agent 或 codex CLI 入口。
• 运行启动后，使用 islo factory line-run 控制 Factory 线路运行（status、events、stop、steer、retry、follow-up、agent-turn）。stop 会暂停线路，而非彻底取消；仅对已暂停或已完成的运行执行 steer，并使用 retry 重试最新的失败阶段。
• 对于需要大量判断的自动化任务，在 job 阶段或沙盒中运行 Agent。不要用手写的 shell 业务逻辑替代 Agent。
• Harness 代码（服务端、CLI、场景资源）存放在阶段 job 引用的 沙盒快照中——不要在 job.toml 中使用 base64 或 heredoc 进行引导。参见 jobs.md 和 factory.md。
• 对于内部工具、仪表板和自定义启动器，优先使用 SDK。