Composio Jira Toolkit 实战指南自定义 OAuth 凭证配置与 JQL 搜索的三种姿势【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio本文基于 Composio 仓库中的 Jira Toolkit FAQdocs/content/toolkits/faq/jira.md完整回答两个高频问题如何为 Jira 配置自定义 OAuth 凭证BYOA以及JQL GET、JQL POST与Search Issues三种搜索方式的区别与选型建议。全文结合仓库中的 toolkit 数据文件、知识库文章与认证文档逐条佐证读完你可以独立完成 Jira 自定义 OAuth 应用的授权配置并正确选择与调用 Jira 搜索工具。Jira Toolkit 在 Composio 中的整体形态在展开两个 FAQ 之前先给出仓库内可核验的基础事实。toolkit 元数据文件 docs/public/data/toolkits.json 中 Jira 的条目显示属性值说明slugjira工具路由与 SDK 中引用的标识categoryproject management项目管理类authSchemesOAUTH2、S2S_OAUTH2、API_KEY支持的三种认证方案composioManagedAuthSchemesOAUTH2官方托管认证仅覆盖 OAUTH2S2S 与 API Key 需要客户自备凭证toolCount/triggerCount102/3102 个工具、3 个触发器三种触发器分别为JIRA_NEW_ISSUE_TRIGGER新建 issue、JIRA_NEW_PROJECT_TRIGGER新建项目、JIRA_UPDATED_ISSUE_TRIGGERissue 变更明确不监听评论活动均来自同一数据文件。认证细节同样写在authConfigDetails中这对后文的 OAuth 配置问题非常关键OAUTH2 模式配置名jira_oauth创建 auth config 时必填client_id、client_secret可选字段为oauth_redirect_uri默认值https://backend.composio.dev/api/v1/auth-apps/add和scopes默认值为一串逗号分隔的 scope包括read:jira-work、write:jira-work、manage:jira-project、read:jira-user、manage:jira-webhook、read:servicedesk-request、offline_access等。API_KEY 模式在创建 connected account 时必填subdomain并有可选的 basic encode 相关字段。connected account 初始化OAUTH2 与 API_KEY 均适用必填subdomain字段官方描述为“Jira 地址中.atlassian.net之前的部分例如acme.atlassian.net中的acme”。也就是说无论走哪种认证方案subdomain都是连接 Jira 实例时的基础输入——Jira 期望租户地址形如https://subdomain.atlassian.net这一点在知识库文章 docs/kb/articles/toolkits-jira.md 中也有明确记录。问题一如何为 Jira 配置自定义 OAuth 凭证FAQ 原文的结论是配置自定义 Jira OAuth 凭证需按步骤创建并配置自己的 Jira OAuth 应用BYOABring Your Own App。FAQ 原文指向外部指南而在本仓库中与“自定义凭证 vs 托管凭证”及 auth config 相关的实现性文档位于 custom-app-vs-managed-app.mdx 与 custom-auth-configs.mdx可结合上述 toolkits.json 中的authConfigDetails完整还原配置步骤在 Atlassian 开发者平台创建 OAuth 2.0 应用拿到client_id与client_secret。把 Composio 回调地址加入应用白名单。oauth_redirect_uri的默认值为https://backend.composio.dev/api/v1/auth-apps/add。知识库文章特别强调Jira/Atlassian OAuth 要求Composio auth config 与 Atlassian OAuth 应用中的 redirect URI 完全一致应以当前 auth-config 流程展示的回调为准不要沿用旧版示例中的 legacy v1/v3 回调路径。提交 auth config。必填client_id、client_secret可选地覆写oauth_redirect_uri与scopes。创建 connected account 时传入subdomain完成授权。与 Atlassian OAuth 机制相关的三个易错点以下三点在 docs/kb/articles/toolkits-jira.md 与 docs/kb/source/toolkits/jira/public.md 中都有沉淀是自定义 OAuth 凭证最容易踩的坑Scope 限制Atlassian 对单个 OAuth 应用限制 50 个 scope不支持或错配的 scope 会导致 consent 直接失败。因此自定义 auth config 的scopes必须与 Atlassian 应用上已批准的 scope 对齐。toolkits.json中的默认 scope 串可直接作为起始清单。audienceapi.atlassian.com参数Atlassian OAuth 2.0 要求授权 URL 携带audienceapi.atlassian.com。缺少该参数时Atlassian 可能不响应offline_access即不返回 refresh token访问令牌过期后无法续期。若发现 Jira 凭证“立刻过期”应检查 connected account 是否缺少offline_access以及 Jira OAuth 配置是否包含audience参数紧急情况下可用 Atlassian 邮箱 API token 的 API key 认证作为不失效的替代方案。不要依赖旧 SDK 的customConnectionData注入原始 access token 的变通方式应通过subdomain正规发起连接。JIRA_GET_SERVER_INFO工具可用来确认 base URL 与实例信息。使用 Tool Router 时务必显式绑定自定义 auth configFAQ 讲的是“配置”实践中还有一步“让系统用对配置”当你的 agent 走 Tool Router 而非直接指定工具时如果会话没有显式指定 Jira auth configTool Router 可能回退到自动生成的默认 Jira 配置从而看不到你用自定义凭证建立的 active 连接。解决方案是在创建会话时显式 pin 住 BYOA 配置例如auth_configs: { jira: auth_config_id }该建议完整记录在 docs/kb/articles/toolkits-jira.md 的 “Pin custom Jira authConfig when creating Tool Router sessions” 一节是自定义 OAuth 凭证落地闭环的最后一环。问题二JQL GET、JQL POST 与 Search Issues 有什么区别FAQ 原文的回答可以概括为三句话JQL GET与JQL POST指向同一搜索功能只是 HTTP 方法不同POST 支持在请求体中携带复杂查询。Search Issues底层使用 JQL POST 的实现并额外提供更丰富的参数与过滤能力。为保证结果一致复杂查询优先选 POST用fields参数请求指定字段或传[*all]请求全部字段。结合 toolkits.json 中的工具描述当前仓库中对应的实际工具映射如下FAQ 说法对应工具仓库中的当前状态JQL GETJIRA_SEARCH_FOR_ISSUES_USING_JQL_GETSearch Issues Using JQL (GET)可用。带分页与字段选择的 JQL 搜索JQL POSTJIRA_SEARCH_FOR_ISSUES_USING_JQL_POSTSearch Issues Using JQL Enhanced (POST)已标记 DEPRECATED描述中明确 “UseJIRA_SEARCH_ISSUESinstead”POST 端点用于长/复杂 JQL 以避免 GET 方式的 HTTP 414 错误且仅限 Jira Cloud不适用于 Server/Data CenterSearch IssuesJIRA_SEARCH_ISSUESSearch issues当前主推。支持结构化过滤与原始 JQL至少需要一个过滤参数如jql、project_key、updated_after空参数调用会被拒绝可以这样理解演进关系早期 GET/POST 两个工具分别对应 Jira REST API 的两种调用方式随着 POST 端点成为复杂查询的事实标准Composio 把结构化过滤参数叠加在 POST 之上收敛为JIRA_SEARCH_ISSUES旧 POST 工具随之弃用。因此今天做“复杂 JQL 查询”时正确的选择是JIRA_SEARCH_ISSUES或简单场景下的 GET 工具而不是继续调用已弃用的 POST 工具。字段选择与分页的正确用法FAQ 提到的fields参数在两个搜索工具的描述中都有对应JIRA_GET_ISSUE的描述同样提醒“只请求需要的fields与 expansions避免超大响应并可用具体的customfield_*键校验字段值”搜索类工具则支持[*all]请求全量字段。分页方面docs/kb/articles/toolkits-jira.md 给出了比 FAQ 更细的约束值得逐条执行当前 Jira 搜索工具会把 provider 的分页 token 与原搜索上下文一起包装返回。把同一个 Composio 动作返回的next_page_token原样传给该动作的下次调用即可。如果调用方直接提供原始 JiranextPageToken则必须同时提供原始 JQL。不要把一个动作返回的 token 传给另一个动作token 应立即用于取下一页不要持久化旧 token 或对被拒绝的 token 重试。若 Jira 在同一上下文下仍返回invalid or expired丢弃 token 并从第 1 页重新开始分页。另外如果只需要“有多少条 issue”而不需要明细可以使用JIRA_SEARCH_APPROXIMATE_COUNT基于 approximate count 端点注意其 JQL 必须是有界查询至少包含一个检索限制条件。由 FAQ 延伸的四个 Jira 实操要点Jira 知识库文章docs/kb/articles/toolkits-jira.md 与 docs/kb/source/toolkits/jira/public.md中还有若干与 FAQ 主题直接相关的补充一并归纳如下创建 issue 前的元数据探测Jira 已弃用旧的 create-metadata API 行为替代工具是JIRA_GET_CREATE_METADATA_ISSUE_TYPE_FIELDS替代JIRA_GET_ISSUE_CREATE_METADATA后者在 toolkits.json 中同样标记为 Deprecated。当JIRA_CREATE_ISSUE报 “field X is required” 时用该工具传入projectIdOrKey与issueTypeId发现项目所需的自定义字段再通过additional_properties传入 JSON 字符串形式的自定义字段值。附件下载用JIRA_GET_ATTACHMENT按附件 ID 获取 Jira 附件的二进制内容配套的JIRA_GET_ATTACHMENT_META可先确认附件功能是否启用及最大上传体积。日志保留策略Composio 管理 Jira OAuth token 并把 Jira API 响应返回给客户应用请求/响应 payload 是否保留在 Composio 工具日志中取决于项目的 log-storage 设置——“Dont store data” 选项会让新日志行省略 payload 内容但保留审计元数据。服务账号场景在没有对应托管认证应用可用时服务账号式用法应使用客户自己的凭证并配置所需的 Jira 及 Jira service-account scopes。延伸阅读Jira Toolkit FAQ 原文本文所依据的两个问题原文。docs/public/data/toolkits.jsonJira 全部 102 个工具、3 个触发器、认证方案与 authConfig 默认字段的权威数据源。docs/kb/articles/toolkits-jira.mdJira 支持的公共知识库文章涵盖 OAuth scope、audience 参数、分页 token 等排障经验。自定义应用 vs 托管应用 与 自定义 Auth Configs自定义 OAuth 凭证配置的系统性文档。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Composio Jira Toolkit 实战指南自定义 OAuth 凭证配置与 JQL 搜索的三种姿势【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio本文基于 Composio 仓库中的 Jira Toolkit FAQdocs/content/toolkits/faq/jira.md完整回答两个高频问题如何为 Jira 配置自定义 OAuth 凭证BYOA以及JQL GET、JQL POST与Search Issues三种搜索方式的区别与选型建议。全文结合仓库中的 toolkit 数据文件、知识库文章与认证文档逐条佐证读完你可以独立完成 Jira 自定义 OAuth 应用的授权配置并正确选择与调用 Jira 搜索工具。Jira Toolkit 在 Composio 中的整体形态在展开两个 FAQ 之前先给出仓库内可核验的基础事实。toolkit 元数据文件 docs/public/data/toolkits.json 中 Jira 的条目显示属性值说明slugjira工具路由与 SDK 中引用的标识categoryproject management项目管理类authSchemesOAUTH2、S2S_OAUTH2、API_KEY支持的三种认证方案composioManagedAuthSchemesOAUTH2官方托管认证仅覆盖 OAUTH2S2S 与 API Key 需要客户自备凭证toolCount/triggerCount102/3102 个工具、3 个触发器三种触发器分别为JIRA_NEW_ISSUE_TRIGGER新建 issue、JIRA_NEW_PROJECT_TRIGGER新建项目、JIRA_UPDATED_ISSUE_TRIGGERissue 变更明确不监听评论活动均来自同一数据文件。认证细节同样写在authConfigDetails中这对后文的 OAuth 配置问题非常关键OAUTH2 模式配置名jira_oauth创建 auth config 时必填client_id、client_secret可选字段为oauth_redirect_uri默认值https://backend.composio.dev/api/v1/auth-apps/add和scopes默认值为一串逗号分隔的 scope包括read:jira-work、write:jira-work、manage:jira-project、read:jira-user、manage:jira-webhook、read:servicedesk-request、offline_access等。API_KEY 模式在创建 connected account 时必填subdomain并有可选的 basic encode 相关字段。connected account 初始化OAUTH2 与 API_KEY 均适用必填subdomain字段官方描述为“Jira 地址中.atlassian.net之前的部分例如acme.atlassian.net中的acme”。也就是说无论走哪种认证方案subdomain都是连接 Jira 实例时的基础输入——Jira 期望租户地址形如https://subdomain.atlassian.net这一点在知识库文章 docs/kb/articles/toolkits-jira.md 中也有明确记录。问题一如何为 Jira 配置自定义 OAuth 凭证FAQ 原文的结论是配置自定义 Jira OAuth 凭证需按步骤创建并配置自己的 Jira OAuth 应用BYOABring Your Own App。FAQ 原文指向外部指南而在本仓库中与“自定义凭证 vs 托管凭证”及 auth config 相关的实现性文档位于 custom-app-vs-managed-app.mdx 与 custom-auth-configs.mdx可结合上述 toolkits.json 中的authConfigDetails完整还原配置步骤在 Atlassian 开发者平台创建 OAuth 2.0 应用拿到client_id与client_secret。把 Composio 回调地址加入应用白名单。oauth_redirect_uri的默认值为https://backend.composio.dev/api/v1/auth-apps/add。知识库文章特别强调Jira/Atlassian OAuth 要求Composio auth config 与 Atlassian OAuth 应用中的 redirect URI 完全一致应以当前 auth-config 流程展示的回调为准不要沿用旧版示例中的 legacy v1/v3 回调路径。提交 auth config。必填client_id、client_secret可选地覆写oauth_redirect_uri与scopes。创建 connected account 时传入subdomain完成授权。与 Atlassian OAuth 机制相关的三个易错点以下三点在 docs/kb/articles/toolkits-jira.md 与 docs/kb/source/toolkits/jira/public.md 中都有沉淀是自定义 OAuth 凭证最容易踩的坑Scope 限制Atlassian 对单个 OAuth 应用限制 50 个 scope不支持或错配的 scope 会导致 consent 直接失败。因此自定义 auth config 的scopes必须与 Atlassian 应用上已批准的 scope 对齐。toolkits.json中的默认 scope 串可直接作为起始清单。audienceapi.atlassian.com参数Atlassian OAuth 2.0 要求授权 URL 携带audienceapi.atlassian.com。缺少该参数时Atlassian 可能不响应offline_access即不返回 refresh token访问令牌过期后无法续期。若发现 Jira 凭证“立刻过期”应检查 connected account 是否缺少offline_access以及 Jira OAuth 配置是否包含audience参数紧急情况下可用 Atlassian 邮箱 API token 的 API key 认证作为不失效的替代方案。不要依赖旧 SDK 的customConnectionData注入原始 access token 的变通方式应通过subdomain正规发起连接。JIRA_GET_SERVER_INFO工具可用来确认 base URL 与实例信息。使用 Tool Router 时务必显式绑定自定义 auth configFAQ 讲的是“配置”实践中还有一步“让系统用对配置”当你的 agent 走 Tool Router 而非直接指定工具时如果会话没有显式指定 Jira auth configTool Router 可能回退到自动生成的默认 Jira 配置从而看不到你用自定义凭证建立的 active 连接。解决方案是在创建会话时显式 pin 住 BYOA 配置例如auth_configs: { jira: auth_config_id }该建议完整记录在 docs/kb/articles/toolkits-jira.md 的 “Pin custom Jira authConfig when creating Tool Router sessions” 一节是自定义 OAuth 凭证落地闭环的最后一环。问题二JQL GET、JQL POST 与 Search Issues 有什么区别FAQ 原文的回答可以概括为三句话JQL GET与JQL POST指向同一搜索功能只是 HTTP 方法不同POST 支持在请求体中携带复杂查询。Search Issues底层使用 JQL POST 的实现并额外提供更丰富的参数与过滤能力。为保证结果一致复杂查询优先选 POST用fields参数请求指定字段或传[*all]请求全部字段。结合 toolkits.json 中的工具描述当前仓库中对应的实际工具映射如下FAQ 说法对应工具仓库中的当前状态JQL GETJIRA_SEARCH_FOR_ISSUES_USING_JQL_GETSearch Issues Using JQL (GET)可用。带分页与字段选择的 JQL 搜索JQL POSTJIRA_SEARCH_FOR_ISSUES_USING_JQL_POSTSearch Issues Using JQL Enhanced (POST)已标记 DEPRECATED描述中明确 “UseJIRA_SEARCH_ISSUESinstead”POST 端点用于长/复杂 JQL 以避免 GET 方式的 HTTP 414 错误且仅限 Jira Cloud不适用于 Server/Data CenterSearch IssuesJIRA_SEARCH_ISSUESSearch issues当前主推。支持结构化过滤与原始 JQL至少需要一个过滤参数如jql、project_key、updated_after空参数调用会被拒绝可以这样理解演进关系早期 GET/POST 两个工具分别对应 Jira REST API 的两种调用方式随着 POST 端点成为复杂查询的事实标准Composio 把结构化过滤参数叠加在 POST 之上收敛为JIRA_SEARCH_ISSUES旧 POST 工具随之弃用。因此今天做“复杂 JQL 查询”时正确的选择是JIRA_SEARCH_ISSUES或简单场景下的 GET 工具而不是继续调用已弃用的 POST 工具。字段选择与分页的正确用法FAQ 提到的fields参数在两个搜索工具的描述中都有对应JIRA_GET_ISSUE的描述同样提醒“只请求需要的fields与 expansions避免超大响应并可用具体的customfield_*键校验字段值”搜索类工具则支持[*all]请求全量字段。分页方面docs/kb/articles/toolkits-jira.md 给出了比 FAQ 更细的约束值得逐条执行当前 Jira 搜索工具会把 provider 的分页 token 与原搜索上下文一起包装返回。把同一个 Composio 动作返回的next_page_token原样传给该动作的下次调用即可。如果调用方直接提供原始 JiranextPageToken则必须同时提供原始 JQL。不要把一个动作返回的 token 传给另一个动作token 应立即用于取下一页不要持久化旧 token 或对被拒绝的 token 重试。若 Jira 在同一上下文下仍返回invalid or expired丢弃 token 并从第 1 页重新开始分页。另外如果只需要“有多少条 issue”而不需要明细可以使用JIRA_SEARCH_APPROXIMATE_COUNT基于 approximate count 端点注意其 JQL 必须是有界查询至少包含一个检索限制条件。由 FAQ 延伸的四个 Jira 实操要点Jira 知识库文章docs/kb/articles/toolkits-jira.md 与 docs/kb/source/toolkits/jira/public.md中还有若干与 FAQ 主题直接相关的补充一并归纳如下创建 issue 前的元数据探测Jira 已弃用旧的 create-metadata API 行为替代工具是JIRA_GET_CREATE_METADATA_ISSUE_TYPE_FIELDS替代JIRA_GET_ISSUE_CREATE_METADATA后者在 toolkits.json 中同样标记为 Deprecated。当JIRA_CREATE_ISSUE报 “field X is required” 时用该工具传入projectIdOrKey与issueTypeId发现项目所需的自定义字段再通过additional_properties传入 JSON 字符串形式的自定义字段值。附件下载用JIRA_GET_ATTACHMENT按附件 ID 获取 Jira 附件的二进制内容配套的JIRA_GET_ATTACHMENT_META可先确认附件功能是否启用及最大上传体积。日志保留策略Composio 管理 Jira OAuth token 并把 Jira API 响应返回给客户应用请求/响应 payload 是否保留在 Composio 工具日志中取决于项目的 log-storage 设置——“Dont store data” 选项会让新日志行省略 payload 内容但保留审计元数据。服务账号场景在没有对应托管认证应用可用时服务账号式用法应使用客户自己的凭证并配置所需的 Jira 及 Jira service-account scopes。延伸阅读Jira Toolkit FAQ 原文本文所依据的两个问题原文。docs/public/data/toolkits.jsonJira 全部 102 个工具、3 个触发器、认证方案与 authConfig 默认字段的权威数据源。docs/kb/articles/toolkits-jira.mdJira 支持的公共知识库文章涵盖 OAuth scope、audience 参数、分页 token 等排障经验。自定义应用 vs 托管应用 与 自定义 Auth Configs自定义 OAuth 凭证配置的系统性文档。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
