Semaphore UI 最新动态 2.21

Semaphore UI 2.21 可以运行 AI 编程智能体。两个新应用 Claude Code Agent 和 Codex Agent 会在仓库中启动智能体的命令行工具，并向它提供提示词。智能体自主工作，并把所做的事情报告到任务日志中。提示词可以取用变量组和调查变量的值，智能体可以调用 MCP 服务器的工具，日志则以对话记录的形式展示它的工作。

Semaphore 2.21 正在开发中。 它尚未发布：本页描述的是开发分支中已有的内容，并会在发布前持续补充。细节仍可能变化。

亮点 #

• Claude Code Agent 和 Codex Agent 模板：智能体与其他模板一样，也是一个模板。可以手动启动，也可以通过计划任务、集成启动，或作为工作流的一个步骤启动。
• 提示词表达式：${{ vars.extra.NAME }}、${{ vars.env.NAME }}、${{ secrets.extra.NAME }} 和 ${{ secrets.env.NAME }} 把变量组和调查变量的值放入提示词，与 GitHub Actions 中的写法相同。
• 任务的提示词：模板可以允许启动任务的人在单次运行中替换提示词。
• MCP 清单：一种新的清单类型，包含智能体可调用其工具的远程 MCP 服务器。令牌以加密方式存储。
• 智能体任务日志：智能体的文本、工具调用、子智能体，以及包含令牌数和费用的摘要，在智能体工作期间实时更新。
• 隔离：每个任务都有自己的、空的智能体配置目录。令牌和放入提示词的密钥在日志中会被掩码。

AI 智能体模板 #

智能体模板会在仓库的某个目录中启动 Claude Code 或 Codex，并向它提供提示词。可以把它用于那些原本需要向同事说明的工作：审查最近一次提交、找出并修复失败的测试、更新依赖并创建 pull request。

要创建智能体模板，请进入任务模板，点击新建模板，然后选择 Claude Code Agent 或 Codex Agent。

前提条件。 智能体的命令行工具必须安装在执行任务的机器上，即 Semaphore 服务器或 runner：

Semaphore 启动时如果在 PATH 中找到应用的命令，就会启用该应用。管理员也可以在应用页面启用它并设置可执行文件的路径。

智能体如何运行。 Semaphore 在仓库目录中启动智能体，并通过标准输入传入提示词，因此提示词不会出现在进程列表中：

• 任务之间不保留任何内容。 每次运行都是智能体的一个新会话。需要在运行之后保留的内容应放在仓库中：一次提交、一个 pull request、一个文件。
• 在 Docker 和 Kubernetes runner 上，智能体在容器中运行，因此执行器镜像必须包含 claude 或 codex 命令。

API 密钥 #

智能体从环境变量中获取 API 密钥。请把密钥作为密钥环境变量添加到模板的某个变量组中：

运行 Semaphore 的用户的登录信息不会被使用：智能体的配置目录是为任务创建的，并且是空的，因此变量组中的密钥是唯一的认证方式。如果这些变量都没有设置，任务日志会说明需要添加哪一个。

提示词表达式 #

模板的提示词可以取用模板变量组中的值。像在 GitHub Actions 中那样用双花括号写一个表达式，Semaphore 会在任务启动时替换它：

Find the flaky tests in services/api and fix them.
Open a pull request against ${{ vars.extra.base_branch }} and post its link
to ${{ vars.env.TRACKER_URL }} with the token ${{ secrets.env.TRACKER_TOKEN }}.

• 调查变量属于额外变量：调查变量 version 的答案是 ${{ vars.extra.version }}，密钥类型的则是 ${{ secrets.extra.NAME }}。以环境变量形式传递的调查变量位于 env 下。未回答的调查变量得到空字符串。
• 不存在的变量会使任务失败，失败发生在智能体启动之前，并给出指明该表达式的消息。Semaphore 不会用有缺口的提示词运行智能体。
• 拼写错误的表达式会在保存模板时被拒绝：${{ secrets.TOKEN }} 中没有 extra 或 env。
• 其他表达式保持原样。 只有 vars.… 和 secrets.… 属于 Semaphore，因此提示词可以要求智能体编写包含 ${{ github.sha }} 的工作流。要把 vars 或 secrets 表达式保留为文本，请在它前面再加一个美元符号：$${{ secrets.env.NAME }}。
• 值按原样放入。 字符串按其书写形式使用，列表或对象以 JSON 形式使用。值不会被再次查找表达式。
• 放入提示词的密钥会被掩码：无论智能体在任务日志的何处重复它。

提示词中的密钥会随提示词的其余部分一起发送给模型提供商。更好的做法是把密钥交给智能体的工具：作为变量组的密钥环境变量，或作为 MCP 服务器的令牌。

任务的提示词 #

在模板中启用提示词复选框后，任务表单会显示模板的提示词，并允许在单次运行中修改它。计划任务、集成或工作流步骤也可以用同样的方式保存自己的提示词。通过 API 时，请在任务参数中发送它：

{
  "template_id": 12,
  "params": {
    "prompt": "Review the changes of the last release and list the risky ones."
  }
}

任务提供的提示词会完全按其书写形式使用：提示词表达式只在模板中存储的提示词里被替换。这样，只能运行任务的人就接触不到项目的变量和密钥。如果模板不允许，带有提示词的任务会被拒绝。

MCP 服务器 #

智能体可以调用远程 MCP 服务器的工具：问题跟踪器、文档搜索、你自己的服务。这些服务器保存在新的 MCP 清单类型的清单中，同一个清单可同时用于 Claude Code 和 Codex 模板。

• 已保存的令牌以加密方式存储，并且不再显示：输入新令牌即可替换它，也可以将其删除。
• 令牌以环境变量的形式到达智能体的进程。它不会写入智能体的配置文件、命令行或任务日志。
• 智能体得到的正是这些服务器。 它们的工具已预先批准，因为没有人在场确认调用；为运行 Semaphore 的用户配置的 MCP 服务器不会被使用。

任务日志 #

任务日志实时展示智能体的工作，形式是对话记录，而不是命令行工具输出的 JSON 事件：

• 智能体的文本，逐行显示。Codex 在消息完成后才输出它。
• 工具调用，每个调用占一行：状态、MCP 服务器和工具、参数。点击某一行可查看参数和结果。失败的调用一开始就是展开的。
• 子智能体：子智能体的行会标有它的名称。
• Claude Code 运行的第一行给出模型和 MCP 服务器，未能连接的服务器以红色显示。
• 末尾的摘要：轮数、耗时、令牌数和费用，以智能体报告的内容为限。

原始日志以纯文本显示同一份日志。

安全 #

• 智能体会执行命令。 在其命令行工具赋予的权限范围内，智能体可以读取和修改仓库目录，以执行任务的用户身份运行程序，并调用其 MCP 服务器的工具。请为智能体模板提供权限刚好够完成工作的仓库和令牌，并为希望与服务器隔离的工作使用单独的 runner。
• 每个任务都有自己的智能体配置目录（CLAUDE_CONFIG_DIR、CODEX_HOME），为任务创建并在任务结束后删除。运行 Semaphore 的用户的设置、登录信息和 MCP 服务器不会到达智能体，变量组的变量也无法重定向该目录。
• 提示词和智能体读取的内容会发送给模型提供商：仓库的文件、命令的输出、工具的结果。
• 仓库可以向智能体下达指令。 智能体读取的文件、issue 或工具结果中的文本都可能改变智能体的行为。不要让持有高权限令牌的智能体处理你无法控制的内容。
• 令牌和密钥在任务日志中会被掩码：MCP 服务器的令牌和放入提示词的密钥会被替换为 ********。
• 变量和密钥不会出现在智能体的命令行上，否则进程列表会显示它们。

文档 #

用户指南中有一个页面列出了所有字段和规则：AI 智能体。