sr-connect

ScriptRunner Connect

本文件介绍理论知识。操作 CLI 前，请先阅读 references/cli-workflow.md。编写脚本前，请先阅读 references/scripting.md，以及脚本调用的每种产品在 references/product-gotchas/ 下对应的文件（如果有）。只有当用户要求编写测试时，才阅读 references/testing.md。

首次调用 CLI 前

每个会话只需确定一次要调用的命令，并且必须在进行其他 CLI 操作前完成。

1. command -v sr-connect。若找到，表示 CLI 已安装且位于 PATH 中：所有地方都调用 sr-connect <group> <verb>，包括提供给用户的命令。若未找到，则调用 npx @sr-connect/cli <group> <verb>，并将会话中的首次调用固定为 npx @sr-connect/cli@latest，以确保缓存副本是最新的。

   若未找到，请用一句简单的话告知用户，避免让他们以为出了问题：npx 可以正常使用，无需修复；若想加快调用速度，可以通过 npm install -g @sr-connect/cli 全局安装。npx 每次调用都会检查缓存，因此每次会多花几秒；某个 Agent 的测量结果为 4 到 10 s。项目本地安装不会将 sr-connect 放入 PATH，因此没有帮助。在 nvm 下，全局安装属于当前激活的 Node 版本；切换版本后，sr-connect 会再次从 PATH 中消失。如果用户在会话中途安装了它，请重新执行此步骤，以便会话切换到 sr-connect。

2. <cli> cli check-updates --agent --raw。文档包含 updateAvailable、current 和 latest，如果有更新，还会包含 command。退出码为 1 表示无法读取注册表，退出码为 4 表示注册表没有发布任何版本；这两种情况都不会阻碍工作，请说明这一点，然后继续使用当前版本。

3. 当 updateAvailable 为 true 时，说明两个版本号，附上更新日志链接（https://cdn.jsdelivr.net/npm/@sr-connect/cli@latest/CHANGELOG.md），方便用户查看更改内容，并询问用户是自行升级，还是由你代为升级。未经用户答复，绝不要升级。

command 字段是根据此副本的安装方式生成的升级命令，适用于 npm、pnpm、bun 和 npx。如果 CLI 将以下两种安装方式识别为 npm，该命令就不正确，因此在引用前请先检查：将 sr-connect 解析为其真实路径，或运行 yarn global bin 和 volta which sr-connect。

安装方式	升级命令
npm 全局安装	npm install -g @sr-connect/cli@latest
pnpm 全局安装	pnpm add -g @sr-connect/cli@latest
bun 全局安装	bun add -g @sr-connect/cli@latest
Yarn 1 全局安装	yarn global upgrade @sr-connect/cli
Volta	volta install @sr-connect/cli@latest
npx 或 Yarn 2+（不支持全局安装）	无需升级；下次调用时使用 npx @sr-connect/cli@latest

由用户运行时，请将这一行命令原样提供给他们，不带 --agent 或 --raw，然后等待。由你运行时，请运行同一行命令，并重新运行 cli check-updates，确认新版本已响应。

本文件中的快照、连接器表、限制、计划和软件包列表的数据截至 2026-09-12，并附有来源 URL。若回答取决于具体数字，请重新获取来源。

此技能是否为最新版本

每次会话中，在首次调用 CLI 之前检查一次。可以比较哈希时就比较哈希；无法比较时，则比较版本。没有网络时，跳过检查：用一行说明，然后继续使用此副本。

1. 查找已安装副本的哈希。项目锁定文件优先于主目录中的锁定文件。没有包含 sr-connect 条目的锁定文件就表示没有哈希：转到下方的版本检查。

   • 项目根目录下的 ./skills-lock.json，近期版本的 npx skills 执行项目级安装时会写入该文件。其 computedHash 采用 GitHub 不使用的方式计算已安装文件的哈希，因此不要拿它进行比较。应改为计算已安装文件夹的 git tree sha，这需要 git；没有 git 时，转到版本检查。将 s 设为加载此 SKILL.md 的文件夹。配置标志和 .DS_Store 清理操作可避免将用户的 git 设置和 Finder 文件纳入哈希：

     s=.agents/skills/sr-connect; d=$(mktemp -d) && cp -R "$s/." "$d" && find "$d" -name .DS_Store -delete && git -C "$d" init -q && git -C "$d" -c core.excludesFile=/dev/null -c core.attributesFile=/dev/null -c core.autocrlf=false add -A -f && git -C "$d" write-tree; rm -rf "$d"
     

   • ./.agents/.skill-lock.json 或 ~/.agents/.skill-lock.json：读取 skills["sr-connect"].skillFolderHash，它已经是已发布仓库中 skills/sr-connect 的 git tree sha。

2. 获取该文件夹已发布版本的 sha。此端点无需身份验证，并会列出仓库中的所有技能：

   curl -s 'https://api.github.com/repos/adaptavist/scriptrunner-skills/contents/skills?ref=main'
   

   从 name 为 sr-connect 的条目中获取 sha。如果返回 403，表示该地址每小时 60 次的 GitHub 未经身份验证调用限额已用尽：转到版本检查。

3. 哈希相同：不作说明。哈希不同：告知用户此副本与已发布的技能不同，通常意味着此副本较旧，并强烈建议更新，因为已发布版本包含此副本缺少的指导。询问用户是否希望你代为运行更新，或提供他们自行运行的命令；并说明无论哪种方式，新文件都要到下一次会话才会加载，因此当前会话会继续使用此副本。等待用户答复。未经用户同意，不要运行更新命令。

   npx skills@latest update sr-connect
   

无法比较哈希时进行版本检查。获取已发布的 SKILL.md；此操作不受 API 限额限制：

curl -s 'https://raw.githubusercontent.com/adaptavist/scriptrunner-skills/main/skills/sr-connect/SKILL.md'

读取其 frontmatter 和此文件 frontmatter 中的 metadata.version，并逐段按数字比较，因此 1.10 比 1.9 新。已发布版本较新，表示此副本较旧：按上述哈希不同的处理方式告知用户。版本相同或获取失败：不作说明。每次有技能变更的发布都会更新版本号，因此若发布时未递增版本号，就无法检测到该次发布。哈希可以捕获每一次变更，所以优先使用哈希检查。

功能介绍

ScriptRunner Connect 是一个通用的、以代码为先的集成平台即服务。你可以编写在托管运行时中执行的 TypeScript 脚本，将其连接到外部应用的事件或定时计划，并通过类型化客户端调用其他应用。它对 Atlassian 及其周边业务工具的支持最为深入，但平台并不局限于这些工具。以代码为先的特性使其非常适合 Agent：集成所需的一切都可以是脚本、配置记录或 CLI 命令。

术语：官方对外部系统的称呼是 app。请使用此术语。

可以集成 X 吗

有两个前提。如果两者都满足，答案几乎总是肯定的。

1. 应用可从互联网访问。SRC 是 SaaS。SRC 的出站调用会从每个实例的一个静态 IP 发出，欧盟为 34.251.34.27，美国为 35.163.23.171，防火墙可以将这些 IP 加入允许列表，以便访问本地网络。另一种方式是在 DMZ 中设置反向代理。对于完全无法开放访问路径的客户，可以选择私有云托管：SRC 团队会在专为客户配置的 AWS 账户中运行产品，也可以将其部署在客户自己的 VPC 中，以便直接访问内部服务；还可以选择断开互联网连接。
2. 应用有 HTTP API。

非 HTTP 协议需要在前面配置 HTTP 层，由客户端设置。SQL 数据库是常见示例。

发往 SRC 的入站流量，即 Webhook，会通过没有静态 IP 的云网关传入；受限网络要发送 Webhook，需要能够向互联网出站。OAuth 授权需要一个能够同时访问应用和 SRC 的浏览器。

来源：https://docs.adaptavist.com/src/latest/get-started/connect-to-services-behind-the-firewall、https://www.scriptrunnerhq.com/scriptrunner-connect/private-cloud-hosting

构建模块

共有五种构造。事件监听器接收来自应用的事件并调用脚本。脚本导入 API 连接以与应用通信。API 连接会替换基础 URL 和身份验证标头，并使用连接器；连接器是已授权的账户。所有内容都位于工作区中。脚本也可以手动运行、按计划运行，或由另一个脚本运行。

术语表，先列文档用词，再列 CLI 组：

概念	文档	CLI
单个集成的容器	workspace	workspace
应用的已授权账户，由用户拥有并通过团队共享	connector	connector、connector-sharing
脚本通过 ./api/<path> 导入的出站客户端	API connection	api-connection
API 连接背后的类型化客户端包	Managed API	package（类型为 MANAGED_API）
绑定到应用事件类型的入站触发器	event listener	event-listener
用于手动运行的已存储示例事件	test event payload	event-listener-test-payload
每个环境的类型化配置	parameters	environment-parameter
由 CRON 驱动的运行	scheduled trigger	scheduled-trigger
按先进先出顺序处理监听器事件	event queue	event-queue
工作区的可编辑工作版本	HEAD	没有 release 字段的环境
不可变快照	release、deployment	release create -e <env>，一次调用
环境配置所在的空间，目标为 HEAD 或某个发布版本	environment	environment；-e 接受其 ID
与 Web 应用共享的编辑锁	无	workspace-lock
团队的出站目标、连接器和主机名允许列表	Egress Firewall	egress-firewall

功能

工作区、HEAD、发布版本和环境

工作区包含脚本、API 连接、事件监听器、定时触发器、包、参数和 README。每个工作区最多属于一个团队；可见性可以是私有，即仅团队管理员和你可见，也可以是公开，即所有团队成员可见。语言可以是 js、ts 或 ts-strict。始终使用 ts-strict。

HEAD 是工作版本，始终可以编辑。发布版本是 HEAD、脚本、README 以及监听器、API 连接和触发器的发布级配置的快照，发布后无法更改。版本采用语义化版本号，且必须递增。release create -e <env> 会在一次调用中创建发布版本并将其部署到环境；environment target-release 只会将环境切换到现有发布版本或切回 HEAD。环境指向 HEAD 或单个发布版本，并保存自身特有的配置：每个 API 连接使用的连接器、每个事件监听器使用的连接器及其设置状态、通用监听器的 URL 路径、每个定时触发器的 CRON 和启用状态、每个队列的启用状态，以及参数值。在已发布的环境中，这些配置仍可编辑；其他所有内容均为只读，而在发布版本创建后新增的资源，在部署包含该资源的发布版本之前都不在适用范围内。

每个工作区都会以指向 HEAD 的单一环境 Default 开始。Default 是其名称；CLI 使用 environment list 报告的 ID 来访问该环境。始终只保留一个指向 HEAD 的环境，并在其中开发；通过创建新发布版本来修复，而不要编辑旧版本。回滚意味着将环境指向较旧的发布版本或切回 HEAD。脚本读取 context.environment.name；在 HEAD 上，context.deployment 未定义。

来源：https://docs.adaptavist.com/src/latest/workspaces/deployments-and-environments

参数

按环境设置的类型化值，脚本通过 context.environment.vars 读取；允许一层文件夹。共有十一种类型，从 TEXT 和 NUMBER 到 LIST、MAP 和 FOLDER；之后无法更改类型。默认值会为新环境和工作区副本提供初始值，但实际值不会被复制，且运行时不会读取默认值。必需参数在有值之前会阻止你在 Web 应用中保存；CLI 不会强制执行此要求，因此必需参数仍可能未设置。因此，ev-params.ts 会将所有参数声明为可选，无论是否必需；脚本在使用某个值前会检查它是否存在；必需参数会在该文件的 JSDoc 中标记为 Required: yes。

PASSWORD 永远不会传到脚本中。代码和日志中看到的都是占位符，只有在发出 HTTP 请求时才会替换为真实值。因此，无法在代码中对密码进行哈希、签名或 base64 编码；需要在运行时处理的内容应放在使用 --masked 创建的 TEXT 参数中。完整类型表、替换涵盖的内容类型，以及对 ev-params.ts 的影响，均见 references/scripting.md。

未经用户明确许可，绝不要读取参数值。 environment-parameter list 会返回参数值，而 TEXT、MULTILINE_TEXT 和 MAP 参数可能包含并非 PASSWORD 类型的机密，其中也包括经过掩码处理的 TEXT。要查看有哪些参数，请克隆工作区并查看 ev-params.ts：其中列出每个参数的描述、类型和是否必需，不包含任何值。references/cli-workflow.md 的 Posture 部分载有相关规定。

来源：https://docs.adaptavist.com/src/latest/workspaces/parameters

API 连接和 Managed API

API 连接负责出站调用：它包含一个在工作区中唯一的路径、一个供应商 API 包，以及每个环境对应的连接器。脚本会导入它，例如 import JiraCloud from './api/jira/cloud'。抽象层级分为三层，优先使用可用的最高层：Managed API；与供应商 API 一一对应的类型化客户端，例如 JiraCloud.Issue.getIssue({ issueIdOrKey })；连接上的托管 fetch，由平台提供基础 URL 和身份验证，你来编写 HTTP 请求；以及原生全局 fetch，平台不提供任何内容。每个连接器应用都有 Managed API；没有公开的按应用划分的参考文档，工作区中的类型定义就是参考。monday.com 的 Managed API 采用 GraphQL 形式，并接受 args 和 fields。关于产品 API、Managed API 和事件类型中类型定义未说明的行为、返回 410 的已弃用方法，以及事件类型遗漏的字段，每个产品都有一个文件，位于 references/product-gotchas/ 下；只有在脚本调用该产品或处理其事件时，才加载对应文件，详见 references/scripting.md 中的 Product gotchas。

来源：https://docs.adaptavist.com/src/latest/workspaces/api-connections、https://docs.adaptavist.com/src/latest/managed-apis；GraphQL 形式参见 https://docs.adaptavist.com/src/latest/managed-apis/managed-api-for-monday.com

事件监听器

事件监听器将应用事件类型绑定到脚本，还可选择通过连接器和事件队列进行绑定。事件类型、脚本和队列属于工作区级别，并由发布版本记录；连接器、URL 路径和启用状态则按环境配置。从监听器创建脚本时，脚本会获得正确的类型化事件。设置流程需由人工在应用中注册 Webhook 才算完成；CLI 会返回 webhookUrl（需要注册的回调地址）和 setupUrl（操作说明）。大多数应用无法通过程序注册 Webhook。新环境需要重新关联连接器并重新完成设置：监听器会存在于该环境中，并报告 disabled: false，但 URL 路径按环境配置，新环境中没有该路径，因此 event-listener get -e <env> 会显示 urlPath 和 webhookUrl 为 null，监听器虽已启用，却无法访问。在该环境中首次执行 event-listener update 时会分配路径：通用监听器使用 --url-path，其他情况则使用 --disabled false 等无操作更新。生成的 webhookUrl 与 HEAD 中的不同，因此需要重新注册 Webhook。大多数监听器类型不需要连接器；对于确实需要连接器的类型，event-listener get 会报告 connectionRequired。不过，如果团队已经拥有该应用的授权连接器，请将其关联到监听器：设置说明会更完善，因为应用的基础 URL 来自连接器，Webhook 深层链接也会基于该 URL 构建。如果没有连接器，就让监听器保持未关联状态；绝不要仅为了给监听器关联连接器而创建一个连接器。测试事件负载会使用已保存的样本运行监听器；新监听器会获得一个预置的 Default 负载，用于采样其事件类型。每个应用的注册步骤、应用端可设置的过滤条件，以及 Webhook 的安全机制，分别记录在 references/event-listener-setup/ 下对应的应用文件中；只有在向用户说明注册步骤时才加载对应文件，详见 references/cli-workflow.md 中的 Webhook handoff。

来源：https://docs.adaptavist.com/src/latest/workspaces/event-listeners

通用事件监听器

Generic 应用的 HTTP_ENDPOINT 监听器类型。它接受平台范围内 URL 路径唯一的任意 HTTP 请求，并将请求交给脚本处理：方法、路径、查询参数、标头、源 IP，以及根据内容类型解析为 json、text 或 base64 的正文。它有两种模式。默认是异步模式：立即向调用方返回包含调用 ID 的确认信息，随后脚本在常规的 15 分钟限制内运行。同步模式会让调用方等待脚本返回的状态、标头和正文，最长 25 秒；超时后调用方会收到 408，返回内容格式不正确则会收到 422。

它的主要用途是接收 SRC 开箱即不支持的应用所发送的事件：任何能发送 HTTP 请求的应用都可以触发脚本。它也适用于本身没有 Webhook 的应用，只要能通过其他方式发送事件即可。Confluence Cloud 就是典型例子：它不提供 Webhook，因此没有对应的监听器类型；但 ScriptRunner for Confluence Cloud 可以监听 Confluence 内部事件，并将其转发到通用监听器的 URL，从而让 SRC 获得 Confluence Cloud 事件流。另外两个应用也可以通过同样的方式接入 SRC。Trello 提供注册 Webhook 的 API，因此可以将该 Webhook 指向通用监听器。Google Calendar 和 Google Sheets 没有连接器级别的事件，但 Google Apps Script 可以监视日历或工作表，并向通用监听器的 URL 发送请求。

由于同步模式会返回响应，监听器也可以用于发布内容，而不只是接收内容。返回 JSON 的脚本可以成为你自己的小型 API，位于工作区可访问的任意系统之前，由 SRC 负责托管、身份验证标头和日志记录。返回 HTML 的脚本则可以提供自定义用户界面：状态页、表单或查询界面，直接从工作区提供服务，无需单独的 Web 主机。除此之外，同一个监听器还可以补足普通 Webhook 缺少的安全性：在执行任何操作之前检查共享密钥标头、将 sourceIp 加入允许列表，或验证签名，因为该端点本身不要求身份验证。

如果通用监听器脚本不包含检查，它就只能依靠 URL 的保密性来保护，而 URL 很容易泄露：聊天消息、浏览器历史记录、代理日志、屏幕截图、共享文档、通知负载。凡是会读取非公开数据、更改状态或触发脚本的端点，都应进行身份验证。构建此类端点时，请主动添加检查，并在结尾摘要中说明已添加；只有纯粹用于接收公开数据的端点才可以省略，并且也要说明。默认检查方式是将共享密钥标头与屏蔽的 TEXT 参数进行比较，并在验证失败时拒绝访问；代码位于 references/scripting.md 中的 Generic HTTP events 一节。发布到 Slack 的链接或邮件不得包含密钥：应链接到要求输入密钥的页面，或改为在链接中放入短时有效的签名令牌。

来源：https://docs.adaptavist.com/src/latest/workspaces/event-listeners/generic-http-events

定时触发器

按照六字段 CRON 表达式运行脚本，秒字段在前，时区为 UTC。最短间隔为 15 分钟；更短的计划会自动调整为该间隔，分钟间隔应为 15 的倍数。CRON 表达式和启用状态按环境分别设置；脚本则共享。发布后创建的触发器在已发布的环境中处于非活动状态，直到该环境重新部署。

来源：https://docs.adaptavist.com/src/latest/workspaces/scheduled-triggers

事件队列

默认情况下，并发处理事件。队列会让监听器中的事件按 FIFO 顺序处理，并根据负载中的点路径分组，拆分为最多 10 个独立流，例如 issue.key。淘汰策略：设置队列等待时间上限（分钟），并选择一项操作：乱序处理，或丢弃并发送电子邮件通知。排队运行时可访问 context.queue.{id,name,groupId} 和 context.queuedAt。仅适用于付费的非 legacy 计划；team get 会报告 features.eventQueues。

来源：https://docs.adaptavist.com/src/latest/workspaces/event-queues

软件包

分为三类。核心软件包 @sr-connect/convert、record-storage 和 trigger，以及事件库 @sr-connect/<app>，会随你创建的监听器一同提供。托管 API 软件包 @managed-api/<service>[-v<N>]-sr-connect 会随你声明的 API 连接一同提供。第三方 NPM 软件包需手动添加。添加时，这三类软件包都会固定为当时的版本，之后也需手动升级；唯一例外是 @sr-connect/runtime-types，它会始终跟踪最新版本，且无法更改。仅支持 ESM 导入。若某个软件包不含自身类型定义，请在旁边添加 @types/<name>。仅为 Node 构建的软件包无法运行；运行时仅支持部分 Web 标准。产品已验证的软件包列表见 references/scripting.md。

来源：https://docs.adaptavist.com/src/latest/workspaces/package-manager

记录存储

脚本用于在多次调用之间保存状态的键值存储：获取、设置、删除、检查是否存在、列出键。作用域包括环境（默认）、工作区、团队和调用。选项：TTL、加密、禁止覆盖。普通写入会覆盖已有值，由最后写入者胜出；启用禁止覆盖的写入则是原子性的“仅当不存在时创建”操作，多个并发写入者中恰好只有一个会成功，因此可用于实现锁、幂等保护或追加日志。每个团队均受速率限制，并会自动重试。容量取决于计划；请参阅 Limits。

来源：https://docs.adaptavist.com/src/latest/scripting/record-storage

从脚本触发脚本

@sr-connect/trigger 会异步触发同一环境中的另一个脚本，并传入 JSON 负载，返回调用 ID。可用于分发工作，也可用于构建长时间运行的任务，例如迁移任务：将其拆分为一连串调用，每次调用均不超过 15 分钟，并将进度保存在记录存储中。调用链有上限；请参阅 Limits。一个可运行的示例是 Tempo Cloud 工时记录迁移模板：https://templates.scriptrunnerconnect.com/template/tempo-cloud-worklogs-migration?expand=true。

来源：https://docs.adaptavist.com/src/latest/scripting/triggering-scripts

连接器与共享

连接器保存应用的凭据，在工作区之外创建，归属于用户，并通过团队查找。共享分为三个级别。使用权限允许他人在工作区、所有团队或指定团队中关联该连接器。编辑权限还允许重命名和重新授权。所有者权限还包括共享和删除，且归创建者所有。关联到团队工作区的连接器默认可供团队成员使用。撤销使用权限、缩小团队范围或退出团队，都会强制将连接器从工作区解除关联。大多数连接器通过浏览器授权；CLI 会创建一个尚未授权的连接器，并返回 URL。connector list 和 connector get 会报告连接器指向的基础 URL，即它获授权所用的 Atlassian 站点或自托管主机。该主机最能说明连接器连接的是哪个部署环境，也常可据此判断环境是否为生产环境。名称则不能说明任何问题，因为两个都叫 Jira Cloud 的连接器可能分别指向沙盒和正式站点。connector list --app-id <appId> 可在一次调用中列出某个应用所有连接器的该字段。连接器尚未授权时不会显示此字段。对于连接器记录中没有主机的应用，无论是否已授权，此字段都不会显示：GitHub、Azure DevOps、Bitbucket Cloud、Microsoft Teams、NetSuite、Zoom 和 Statuspage。因此，这些应用缺少该字段并不说明任何问题。Jira 和 Confluence Cloud、本地部署的连接器、GitLab、Zendesk、ServiceNow、Salesforce、monday.com 和 Opsgenie 会记录客户自己的主机；只有这些应用值得查看基础 URL。Slack 记录的是该应用在 api.slack.com 上的配置页面，它无法用于区分任何环境，但事件监听器正是在该页面注册的。快照日期为 2026-09-14，读取自一个 Jira Cloud 连接器、一个 Slack 连接器和一个未授权的 GitHub 连接器；其余两个列表中的信息可根据哪些连接器会存储主机推断。connector list 字段于 2026-10-16 再次核查。

每种连接器类型的授权方式、向导提供的方法，以及通过 Generic connector 使用固定密钥的替代方案，都各自记录在 references/connector-setup/ 下的一个文件中。仅在必须授权或重新授权连接器时加载对应文件，具体说明见 references/cli-workflow.md 中的 Connector setup 部分。

Generic connector 可连接任意 HTTP API：基础 URL 加上无、基本或自定义标头。它不支持 OAuth 2.0；如需使用 OAuth 2.0，请参阅 references/scripting.md 中的方案。其 API 连接仅提供 fetch，可通过将 connectionId 传给对应 @managed-api/*-sr-connect 包中的 <Product>Api 类，在其上构建 Managed API。

来源：https://docs.adaptavist.com/src/latest/connectors、https://docs.adaptavist.com/src/latest/connectors/generic-connector

出站防火墙

团队级允许列表，用于限制脚本可以向哪些位置发送请求。只有目标地址有获批条目时，脚本的出站调用才会运行，而且不同类型的条目互不通用：

• 连接器条目允许脚本通过该连接器发出的请求：Managed API，以及 API 连接上托管的 fetch。
• Fetch API 目标条目允许对单个主机名进行原始全局 fetch 调用。https://API.Example.com:8443/v2 会存储为 api.example.com；子域名需要单独添加条目，不接受通配符。localhost 以及私有、环回和链路本地地址（例如 10.0.0.1 或 192.168.1.1）也不接受，因为无论允许列表如何设置，脚本都无法访问这些地址；解析到这类地址的主机名则可以添加，但运行时仍会失败。

允许指向 https://api.example.com 的 Generic connector，并不意味着允许 fetch('https://api.example.com/...')；允许该主机名，也不意味着允许该连接器。 条目分为已批准或等待批准。只有在添加条目的人员在团队中拥有 Admin 或 Super Admin 角色、请求未选择退出自动批准，且团队的连接数额度有余量时，条目才会立即获批。否则，系统会将其记录为请求，并向团队管理员发送电子邮件。额度已满并不算错误：条目仍会创建，但会进入等待状态。额度是套餐的连接器数量，即 team get 中的 connections；对于无限套餐，max 为 null。已批准的条目会占用额度，包括已批准但不再被任何 API 连接使用的连接器条目（usedByApiConnection: false），这类条目会一直占用额度，直到被移除；等待中的条目不占用额度。此外，两个公开的 ScriptRunner Connect API 主机 api.scriptrunnerconnect.com 和 api.us.scriptrunnerconnect.com 也不占用额度，但仍需像其他目标一样添加条目；它们在 egress-firewall list 中标记为 exemptFromLimit: true。

条目创建后，公共 API 接受的任何操作都无法更改它。管理员再次添加等待中的条目并启用自动批准，或 API 连接再次关联该连接器时，条目仍会保持等待状态。重复添加是安全的：这两种情况都会返回已存储的条目，且不会更改它。只能在 Web 应用的 Team Settings、Egress Firewall 中批准、拒绝和移除条目。删除连接器会移除其条目并释放额度；Fetch API 目标只能在此处移除。腾出额度不会自动批准任何条目：原本因额度不足而等待的条目仍会等待，现在需要管理员批准。

在同一个调用中将连接器关联到 API 连接，会把它加入允许列表；是否批准取决于上述规则。api-connection create 和 update 会报告所关联连接器的 egressFirewall.state：已批准、等待中、未列出，或部署上未启用防火墙。对于等待中的条目，每次写入操作和列表都会说明调用方需要满足什么条件才能批准该条目：额度已满，此时在腾出额度前任何人都无法批准；调用方不是团队管理员；调用请求要求批准；或者没有阻碍，调用方可以在 Web 应用中自行批准。egress-firewall check-api-connections 可一次读取某个环境中所有 API 连接的相同信息。在团队中的某个 API 连接使用某个连接器之前，不能单独添加该连接器。

被拦截的调用会导致运行失败，错误代码为 11007。运行时写出的错误消息如下：

Request blocked by the team's Egress Firewall.
google.com is not on the allowed destinations list. A team admin can allow it under Team Settings → Egress Firewall. - ScriptRunner Connect Error code: 11007

Request blocked by the team's Egress Firewall.
The "Jira Cloud" connector is not on the allowed connectors list. A team admin can allow it under Team Settings → Egress Firewall. - ScriptRunner Connect Error code: 11007

其他错误表示的是不同问题。错误代码 10001 表示运行时连接失败，并且会在防火墙检查之前检查。Connection not allowed for URL 表示主机名无法解析，或脚本无法访问该地址；应修复 URL 或 DNS，而不是修改允许列表。其他 10001 消息会说明原因。如果消息表示发起调用的服务内存不足，或响应太大而无法返回给脚本，则说明响应过大，无法取回：请分多页获取，或使用供应商的导出功能。如果消息表示调用超时，则说明远程主机发送完整响应所花的时间过长。剩下的 Error while performing HTTP call (Fetch API) 表示连接器调用未收到响应；该消息无法说明是否涉及防火墙，因此请在相应工作区和环境中运行 egress-firewall check-api-connections。如果结果为 APPROVED，请检查供应商、连接器的基本 URL 或连接；其他任何状态都表示需要修正条目，因为它同样会拦截调用。只有错误代码 11007 且消息为 "Request blocked by the team's Egress Firewall" 时，才是防火墙本身给出的错误。 部署会说明是否启用了防火墙。私有云实例可以不启用防火墙；此时运行 egress-firewall list 会被拒绝，并返回 EGRESS_FIREWALL_DISABLED，不会过滤任何内容，这里的说明也都不适用。早于此功能的部署对相同的读取操作会返回 Path not found，退出码为 4，同样不会过滤任何内容。除非出现上述响应之一，否则请假设防火墙已启用。Agent 如何请求审批、添加条目并暂停以等待人工处理，请参阅 references/cli-workflow.md 中的 Egress Firewall。

团队

有三种角色。成员可以查看与其共享的工作区、用量和成员列表。管理员还可以打开团队的所有工作区、邀请成员、编辑超级管理员以下的角色、更改共享设置，以及在自己管理的团队之间移动工作区。超级管理员还可以编辑所有角色、方案和账单，并可以删除团队。同一时间只有一人可以编辑工作区；其他人会获得只读副本，也可以接管编辑控制权。CLI 的工作区锁就是同一种控制机制。

来源：https://docs.adaptavist.com/src/latest/collaborate-with-teams

可观测性

每个团队的调用日志保留六个月。每条记录都包含状态（Finished、Running、Denied、Timed out、Aborted、Function Error、Malformed Payload Error 和 Runtime Error 之一）、触发器类型（Manual、Manual Event Listener、External、Chained 和 Scheduled 之一），以及控制台和 HTTP 日志的数量。每次调用的控制台日志最多保留 1,000 行；超出大小限制的行会单独存储。HTTP 日志会记录每次出站调用，超过 1 KB 的标头和正文会被截断。审计日志记录每项用户操作，保留六个月。重放会使用可编辑的负载重新运行由事件触发的调用（不适用于手动或定时运行，大小上限为 4 MB）。脚本失败通知会在发生未捕获错误时发送电子邮件，按用户、工作区和环境分别设置。

来源：https://docs.adaptavist.com/src/latest/observability

安全

使用 AWS，可在欧盟爱尔兰或美国俄勒冈地区中于注册时选择；数据不会存储在所选区域之外。凭据使用 AWS KMS AES-256-GCM 加密，传输时使用 TLS 1.2。脚本在全新的 V8 隔离区中运行；增强型隔离为每个租户提供专属计算资源，但会增加冷启动。通过 ISO 27001、SOC 2 Type 2、GDPR 认证和合规要求，并经过 CREST 测试；设有 Bugcrowd 漏洞赏金计划。应用内 AI 功能使用 OpenAI 模型，不会使用你的代码进行训练。

来源：https://docs.adaptavist.com/src/latest/security

模板

模板是已发布的工作区，包含适用于某个用例的连接、触发器和代码。大多数模板都是示例。用例匹配时，可以优先从 Sync 和 Migration 类别中的现成集成开始。操作步骤：template list 会列出 ID 和预览 URL；对于同步或迁移需求，还应查看公开模板库 https://templates.scriptrunnerconnect.com/，其中 sitemap.xml 列出所有模板，/template/<slug>?expand=true 会呈现完整的 README 和源代码。使用 workspace create --source-template-id 从模板创建工作区；语言会继承模板设置，因此之后应将其升级为 ts-strict。

来源：https://docs.adaptavist.com/src/latest/templates

REST API 和 CLI

使用账户电子邮件地址和在用户菜单的 API Keys 中创建的 API 密钥进行基本身份验证；密钥只会显示一次。EU 的基础 URL 为 https://api.scriptrunnerconnect.com，US 的基础 URL 为 https://api.us.scriptrunnerconnect.com。CLI @sr-connect/cli 是该 API 的客户端，支持工作区、环境、参数、脚本、监听器、负载、队列、API 连接、连接器、共享、软件包、发布、锁、日志、重放和中止操作。

来源：https://docs.adaptavist.com/src/latest/rest-api

AI 助手

Web 应用内置了助手。从外部进行操作时，请使用自己的能力并忽略它。

计划与托管

计划	连接器	每月执行次数	事件队列	托管方式
免费版	4	5,000	无	共享 AWS，欧盟或美国
Basic	4	无限制（上限 500,000）	有	共享 AWS
Advanced	8	无限制	有	共享 AWS
Pro	无限制	无限制	有	共享 AWS
Enterprise	无限制	无限制	有	私有 AWS 账户，可选 VPC

计划归属于团队，其限制由团队中的每个工作区共享。“连接器”列表示团队的连接额度；已批准的 Egress Firewall 条目也会占用该额度；请参阅 Egress Firewall。Enterprise 以下的套餐可付费添加 SSO。免费套餐仅提供社区支持。

来源：https://www.scriptrunnerhq.com/atlassian-apps/jira/scriptrunner-connect-pricing

限制

来源：https://docs.adaptavist.com/src/latest/limits-and-quotas，以及上述页面。

限制	值
异步调用时长	15 分钟
同步 HTTP 调用时长	25 秒
每次调用的内存	400 MB；付费方案可联系支持团队申请 800 MB 版本
事件负载	6 MB
重放负载	4 MB
链式调用	200
每次调用的控制台行数	1,000
保留的 HTTP 日志正文	1 KB，超出部分将被截断
计划触发器间隔	最短 15 分钟
每个监听器的队列分组数	10
日志保留期限（审计、调用、HTTP）	6 个月
记录存储	Free 100 MB、Basic 1 GB、Advanced 5 GB、Pro 10 GB
每个工作区：API 连接、监听器、负载、触发器、环境	每项 1,000
每个工作区的部署数	10,000
每个账户的工作区、连接器数	每项 1,000
脚本调用（团队）	Free 1/s，付费方案 100/s
外部 API 调用（团队）	Free 5/s，付费方案 100/s
记录存储调用（团队）	Free 1/s，付费方案最高 50/s，具体取决于方案；由所有工作区和调用共享
触发器脚本调用（团队）	Free 1/s，付费方案 10/s
REST API 调用（用户）	Free 5/s，付费方案 20/s；由该用户的所有 API 密钥和 Agent 共享

用一段话了解运行时

不是 Node。它是在 Web 标准子集上构建的自定义 V8 运行时，语法和标准库均符合 ES2020，仅支持 ESM：fetch（响应正文会完整缓冲）、Request/Response/Headers/URL/FormData/Blob、TextEncoder/TextDecoder、btoa/atob、计时器、console、用于密钥的 crypto.getRandomValues，以及仅用于签名和验证的 crypto.subtle。每个出站调用都需要在 Egress Firewall 中为其连接器添加已批准的条目；对于原始 fetch，则需要为其主机名添加条目。不支持 Buffer、process.env、node:*、WebSocket、流、subtle.digest，也不支持任何晚于 ES2020 的库方法或选项，除非探测证明可用；已知的例外是 Intl.DateTimeFormat 的 timeStyle。@sr-connect/convert 可替代 Buffer 转换；jose-browser-runtime 用于签署 JWT。完整表格和编码规则见 references/scripting.md。

来源：https://docs.adaptavist.com/src/latest/scripting/runtime

连接器，快照日期：2026-09-15

来源：https://docs.adaptavist.com/src/latest/connectors 和 Web 应用的授权向导。每个连接器都有一个 Managed API。包含 ID 的实时目录可通过 app list 查看；构建时请查询该目录，而不要依赖此表。每个应用的事件库和 Managed API 包的 NPM 名称见 references/scripting.md；无法从此表中的应用名称推导出这些名称。“Auth”列列出的是向导本身使用的方法；各应用的具体步骤见 references/connector-setup/。

连接器	身份验证	事件监听器
AWS	IAM 角色和生成的信任策略，或访问密钥	否
Azure DevOps	OAuth 2.0，平台的 Azure 应用或自有应用	是
Bitbucket Cloud	OAuth 2.0，自有 OAuth 客户端	是
Bitbucket On-Premise	OAuth 2.0，自有入站应用链接	是
Confluence Cloud	OAuth 2.0，平台应用或自有应用	否，通过通用监听器桥接
Confluence On-Premise	应用链接和生成的密钥对	是
GitHub	OAuth 2.0，平台的 GitHub 应用	是
GitLab	OAuth 2.0，平台在 gitlab.com 上的应用或自有应用	是
Google Calendar	Google 登录，平台应用	否，通过 Google Apps Script 桥接
Google Drive	Google 登录，平台应用；仅限平台创建的文件	否
Google Sheets	Google 登录，平台应用	否，通过 Google Apps Script 桥接
Jira Cloud	OAuth 2.0，平台应用或自有应用	是
Jira On-Premise	应用链接和生成的密钥对	是
Jira Service Management Cloud	OAuth 2.0，平台应用或自有应用	是，通过 Jira Cloud Webhook
Jira Service Management Cloud Assets	电子邮件和 API 令牌	否
Jira Service Management On-Premise	与 Jira On-Premise 共用	是
Jira Service Management On-Premise Assets	与 Jira On-Premise 共用	否
Microsoft	OAuth 2.0，平台的 Azure 应用（仅限 Teams）或自有应用	是
monday.com	OAuth 2.0，由管理员安装的平台应用	是
NetSuite	客户端凭据和生成的证书	是
Opsgenie	API 密钥	是
Salesforce	OAuth 2.0，自有 Connected App	是
ServiceNow	OAuth 2.0，自有 OAuth API 端点	是
Slack	应用 ID、签名密钥、机器人令牌	是
Statuspage	API 密钥	是
Tempo Cloud	OAuth 2.0，Tempo 中的自有应用	否
Tempo Planner On-Premise	与 Jira On-Premise 共用	否
Tempo Timesheets On-Premise	与 Jira On-Premise 共用	否
Trello	自有 Power-Up 的 API 密钥和令牌	否，通过其 API 注册 Webhook
Zendesk	OAuth 2.0，自有 OAuth 客户端	是
Zoom	OAuth 2.0，自有 General 应用	是
Generic	无、基本身份验证、请求头	是，通用 HTTP 事件
大多数监听器应用都有示例测试负载。Zoom、Azure DevOps、Microsoft、NetSuite、Salesforce 和 ServiceNow 没有；请根据应用的文档编写这些负载。

询问类型

询问	首要步骤	加载	是否需要 CLI
SRC 能做 X 吗？X 是如何运作的？	根据此文件回答。如果提到了现有工作区，先读取其设置	仅在读取工作区时加载 cli-workflow.md	有时需要
出了问题，帮忙查看	询问团队、工作区和时间范围。先读取调用日志，然后读取控制台和 HTTP 日志，最后读取脚本	cli-workflow.md，然后根据修复涉及的产品加载 scripting.md 和 product-gotchas/<app>.md	是
构建或修改集成	收集需求，探查连接器和环境，获取锁，然后克隆	根据脚本调用的每种产品加载 cli-workflow.md、scripting.md 和 product-gotchas/<app>.md	是
一次性任务	按照 cli-workflow.md 中的简短步骤操作；询问该任务是否会重复，如果不会，完成后删除	cli-workflow.md、scripting.md	是
注册 webhook，或事件始终未到达	读取监听器及其连接器，然后加载对应的应用文件；参见 cli-workflow.md 中的 Webhook 移交说明	cli-workflow.md、event-listener-setup/<app>.md	是
授权连接器，或连接器停止工作	首先运行 connector list 和 connector get；只有在需要授权新的或已过期的连接器时，才加载对应的连接器文件；参见 cli-workflow.md 中的连接器设置说明	cli-workflow.md、connector-setup/<type>.md	是
运行失败，错误代码为 11007	Egress Firewall 阻止了某个目标地址。egress-firewall check-api-connections 将连接器名称映射到其 ID，egress-firewall list 显示主机；参见 cli-workflow.md 中的 Egress Firewall 说明	cli-workflow.md	是
运行失败，错误代码为 10001	Connection not allowed for URL：这不是 Egress Firewall 导致的；主机名无法解析，或其地址为私有地址；检查 URL 和 DNS，不要添加条目。内存不足或页面过大：改用较小的页面。连接器调用时出现 Error while performing HTTP call (Fetch API)：先运行 egress-firewall check-api-connections，参见 Egress Firewall 说明	scripting.md、cli-workflow.md	有时需要
测试	仅在用户提出要求时	testing.md	是

没有专用连接器时，固定密钥认证使用 Generic 连接器。对于 OAuth，请改为在工作区中设置流程；步骤见 references/scripting.md。如果已有专用连接器，但用户拒绝其向导提供的所有方法，应用在 references/connector-setup/ 下的文件会说明如何通过 Generic 连接器使用固定密钥替代方案（如果供应商提供此方案）。

发送反馈

启用 agenticFeedback 开关后，工作会向 ScriptRunner Connect 团队发送备注。备注中应包含哪些内容、何时发送，以及用于发送的动词，均在 references/cli-workflow.md 的 Feedback 部分说明。关闭开关时，用户已经明确拒绝：不要发送备注，不要提示用户启用开关，也不要在摘要中提及反馈。

提问

尽早提问。在进行首次更改之前，收集所有会影响工作开展的信息：涉及哪些应用和环境、如何界定生产环境、每个应用是否都有非生产实例；如果没有，用户是否愿意提供一个（references/dev-instances.md 说明了需要多长时间）；你是否可以进行探测，探测是否可以修改数据；你是否可以使用测试载荷运行模拟循环；是否可以自动批准工作新增的 Egress Firewall 条目；需要升级哪些包；以及如何端到端测试结果。一次性提前提问，比每隔十分钟问一次更省用户时间；这也能让你在用户允许的范围内，长时间运行模拟循环，随后一次性回来提供可供测试的成果。等待与构建不同：根据 references/cli-workflow.md 中 Posture 部分的说明，任何一次等待用户触发事件或批准的时间都不得超过 30 分钟。

非常重要：请求制定计划，并不意味着可以跳过这一轮提问。不清楚有哪些环境、如何界定生产环境，或是否可以探测，就着手编写集成计划，只是在把猜测包装成计划。无论你的工作框架提供了什么向用户提问的机制，包括计划模式，都要在编写计划之前用它来提出这些问题。计划取决于工作区和目标应用中的实际情况，因此探测应当在计划之前，而不是之后进行；但前提是用户已同意探测。没有同意就不得探测：根据 CLI 允许读取的内容和用户提供的信息编写计划，并标明哪些问题本可通过探测确认。

提前提问不代表可以擅自假设。如果工作中出现了尚未回答的问题，或探测结果与用户告知的情况相矛盾，就停下来提问。对集成作出错误假设，可能导致你需要针对线上系统进行一轮调试；提问只需一分钟。能通过探测回答的问题就去探测；只有用户才能回答的问题就去问。不要为了保持进度而跳过任何一项。

即使看起来显然匹配，也仍然只是猜测。当用户对资源的描述比较宽泛，例如“Jira 连接器”或只说了脚本名称的一部分，而查找只找到一个看似合理的候选项时，不要仅凭这一点就对其进行写入操作。说明匹配到的对象，同时提供 ID 和名称，告知用户你准备对其进行什么操作，然后等待用户确认。读取不需要这些步骤，因此先探测，再把候选对象列出来让用户确认，而不是先问用户指的是哪个。

单个匹配项是陷阱，不是保障。沙盒连接器和线上连接器经常同名；脚本名称会在不同工作区重复；视野中只有一个候选项，也可能只是因为范围设错了。如果用户的要求明确指定了 ID，或指定了没有其他相近候选项的名称，就直接继续。