AutoGPT 平台 Linear Issues 系列 Block 实战指南：基于 GraphQL 的 Issue 创建、检索与搜索

2026-09-07 10:49:48作者：宗隆裙

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

项目地址：https://gitcode.com/GitHub_Trending/au/AutoGPT

导读

本文聚焦 AutoGPT 平台内置的 Linear Issues 系列 Block，完整讲解 Linear Create Issue、Linear Get Project Issues、Linear Search Issues 三个积木块（Block）的功能定位、输入输出参数、典型应用场景与底层实现原理。文章将文档说明与 backend/backend/blocks/linear/ 下的真实源码逐一对照，帮助你准确掌握每个参数的取值范围与默认行为，进而在可视化工作流（Agent Graph）中正确编排任务管理、缺陷上报、冲刺报告等自动化流程。

该文档对应仓库位置：docs/integrations/block-integrations/linear/issues.md，同目录下还提供了 Linear 评论与项目的配套文档（comment.md、projects.md），可组合阅读。

前置知识：Linear 凭据与权限范围（Scope）

在动手编排任何 Linear Block 之前，需要先了解这些 Block 的凭据模型。所有 Linear Block 共用一个在 _config.py 中声明的 Provider：

OAuth2 认证：支持标准 OAuth2 流程，需要配置 LINEAR_CLIENT_ID 与 LINEAR_CLIENT_SECRET 两个环境变量；
API Key 认证：支持直接在界面中填入 Linear 个人 API Key，对应的环境变量名为 LINEAR_API_KEY；
费用模型：每次 Block 运行计 1 个单位的 Base Cost（BlockCostType.RUN）。

OAuth 默认申请 read、write、issues:create、comments:create 四个作用域（Scope）。其中 LinearScope 枚举还定义了更多可选权限，源码注释对此有明确说明：

Scope	含义
`read`	账号的只读访问权，默认总是存在
`write`	账号的写访问权；若应用只需要建评论，建议使用更精确的 `comments:create`
`issues:create`	允许创建新 Issue 及其附件
`comments:create`	允许创建新 Issue 评论
`timeSchedule:write`	允许创建与修改时间排程
`admin`	管理员级端点全量访问，非必要绝不申请

从源码看，LinearCreateIssueBlock 的凭据要求 issues:create 权限（required_scopes={LinearScope.ISSUES_CREATE}），而查询类 Block 只要求 read 权限（required_scopes={LinearScope.READ}）。这意味着在 Graph 中你需要为"创建"与"查询"两类 Block 分别准备满足最低权限要求的凭据，遵循最小权限原则。

提示：本文是 Issues 主题文档的展开，Linear 集成还包含创建评论、项目管理等 Block，可在 docs/integrations/block-integrations/linear 目录下找到对应说明。

一、Linear Create Issue：创建工作流中的 Issue

1.1 功能定位与工作原理

Linear Create Issue 在 Linear 中创建一个新 Issue。按照 issues.md 的说明，它通过 GraphQL API 提交变更（mutation），只要提供团队（team）、标题、描述，即可立即创建 Issue 并归入指定团队的流程（workflow），可选指定优先级与所属项目。

从源码 issues.py 看，该 Block 在 AutoGPT 中注册为：

Block ID：f9c68f55-dcca-40a8-8771-abf9601680aa
分类：PRODUCTIVITY（生产力）与 ISSUE_TRACKING（Issue 跟踪）

它的完整执行链路为：

run() → create_issue() 静态方法
  ├─ LinearClient(credentials)           # 构造 GraphQL 客户端
  ├─ try_get_team_by_name(team_name)     # 按名称/Key 解析 team_id
  ├─ try_search_projects(project_name)   # （可选）搜索项目并取第一个作为 project_id
  └─ try_create_issue(team_id, ...)      # 提交 IssueCreate mutation

上述客户端方法均实现在 _api.py 中。团队解析 try_get_team_by_name 使用 eqIgnoreCase 过滤，同时支持团队全名与团队 Key（如 ENG）；如果解析失败会抛出 404 错误 Team '<name>' not found. Check the team name or key and try again.。项目解析 try_search_projects 走 Linear 的 searchProjects 查询，取命中结果的第一个项目；若搜索无结果，则抛出 Project not found（404）。

创建成功后，try_create_issue 发出的 GraphQL mutation 会返回 Issue 的 identifier（即 TST-123 这种带前缀的展示编号）与 title，它们作为 Block 的核心输出。

1.2 输入参数

文档给出的输入如下表，并结合源码补充默认值与约束：

输入	说明	类型	是否必填	源码补充（默认值 / 约束）
`title`	Issue 的标题	`str`	是	无默认值
`description`	Issue 的描述	`str`	文档标为 Yes，源码中为 `str \| None`	可为空
`team_name`	要创建 Issue 的团队名称	`str`	是	内部会先解析为 team_id
`priority`	Issue 优先级	`int`	否	默认 `None`；范围 0–4（源码约束 `ge=0, le=4`）
`project_name`	要创建 Issue 的项目名称	`str`	否	默认 `None`；内部解析为 project_id
`credentials`	Linear 凭据	`CredentialsMetaInput`	是	需要 `issues:create` 作用域

注意 priority 与 Linear 惯例一致：0 表示无优先级（No priority），1 最高、4 最低，超出范围的数值会在 Schema 校验阶段被拒绝。字段级校验得益于 ge/le 约束，具体定义见 issues.py。

1.3 输出参数

输出	说明	类型
`issue_id`	创建成功的 Issue ID（即 `identifier`，如 `TST-123`）	`str`
`issue_title`	创建成功的 Issue 标题	`str`
`error`	操作失败时的错误信息	`str`

需要说明的是：文档只列出前两项业务输出，而源码的 run() 方法在捕获 LinearAPIException（或其它异常）时会额外 yield "error" 输出错误消息，即 error 是每个 Linear Block 统一保留的隐式失败出口。查询类 Block 的输出表虽然显式列出了 error，但创建类 Block 同样具备该行为（见 issues.py）。在画布上编排时，应把 error 出口接到通知/日志等处理节点上，避免失败被静默吞掉。

1.4 典型应用场景

issues.md 给出的三类场景：

Bug 上报（Bug Reporting）：由错误监控系统或客户反馈自动生成 Issue。典型编排为——监控 Webhook / HTTP 触发 → 解析错误内容 → Linear Create Issue 写入对应团队；
功能请求转化（Feature Requests）：将表单或支持工单中的功能请求结构化后转成 Linear Issue；
任务自动化（Task Automation）：基于定时事件（如 Cron/Time Block）或外部触发器批量建档。

这些场景共同点是"触发源在 Linear 之外"，Block 充当了外部系统与项目 Issue 库之间的写入口。

二、Linear Get Project Issues：按状态与负责人筛选查询

2.1 功能定位与工作原理

Linear Get Project Issues 从指定项目拉取 Issue，支持按状态与负责人（是否已分配）两个维度过滤，可选附带评论。文档明确其会调用 Linear GraphQL API 并返回命中的 Issue 详情。

对应源码 Block 注册信息见 issues.py：ID 为 c7d3f1e8-45a9-4b2c-9f81-3e6a8d7c5b1a，同样归属 PRODUCTIVITY 与 ISSUE_TRACKING。

其底层 GraphQL 查询（IssuesByProjectStatusAndAssignee）使用过滤式 issues 查询，三个维度分别是：

issues(
  filter: {
    project: { name: { eq: $projectName } }
    state: { name: { eq: $statusName } }
    assignee: { null: $isAssigned }
  }
)

一个值得注意的实现细节：GraphQL 过滤条件里 assignee: { null: $isAssigned } 的 null 语义是"负责人为空"。而在 try_get_issues 的变量组装处，代码把 Python 层的入参取反后传入：

"isAssigned": not is_assigned,

也就是说：Block 输入 is_assigned=True（只要已分配）对应 GraphQL 的 assignee.null = false；输入 is_assigned=False（查未分配）对应 assignee.null = true。理解这层取反逻辑有助于你调试过滤结果。

评论的引入通过 GraphQL 指令 comments @include(if: $includeComments) 实现——仅当 include_comments=True 时才发起评论子查询，从而在默认关闭时节省不必要的响应负载。

2.2 输入参数

输入	说明	类型	是否必填	源码补充（默认值）
`project`	要查询的项目名称	`str`	是	需与 Linear 中项目名完全一致（`eq` 精确匹配）
`status`	按状态/流程状态名过滤（如 `In Progress`、`Done`）	`str`	是	同样走 `eq` 精确匹配，需与工作流状态名一致
`is_assigned`	按负责人过滤：`True` 取已分配，`False` 取未分配	`bool`	否	默认 `False`
`include_comments`	响应中是否包含评论	`bool`	否	默认 `False`
`credentials`	Linear 凭据	`CredentialsMetaInput`	是	需要 `read` 作用域

字段定义见 issues.py。由于项目名与状态名都是 eq 精确匹配而非模糊搜索，请务必核对 Linear 工作区内的实际拼写（含大小写），否则会返回空列表而不会报错。

2.3 输出参数

输出	说明	类型
`issues`	符合条件的 Issue 列表	`List[Issue]`
`error`	查询失败时的错误信息	`str`

返回的 Issue 结构体（定义见 models.py）字段相当丰富，除 id、identifier、title、description、priority 外，还包括嵌套的 state（状态名与类型，如 triage/started/completed）、project、assignee，以及开启评论时的 comments 列表（每条含 body、createdAt 与作者 user）。也就是说，下游可以直接消费这些结构化字段做统计或渲染，无需再额外调用 Linear API。

2.4 典型应用场景

文档给出的三类场景（issues.md）：

冲刺报告（Sprint Reports）：定期拉取特定状态（如 In Progress、Done）的 Issue，汇总生成冲刺复盘材料；
工作量分析（Workload Analysis）：跨项目找出未分配（is_assigned=False）或积压的 Issue，辅助排期与再分配；
状态看板（Status Dashboards）：把不同状态的 Issue 分发到可视化节点，构建轻量级分布看板。

从实现看它更像只读聚合源：典型的后续编排是"Get Project Issues → 统计/分类 Block → 生成报告（如 Email/文档）"，或搭配"按状态分别查询"并行形成看板数据。

三、Linear Search Issues：全文式关键词检索

3.1 功能定位与工作原理

Linear Search Issues 使用文本关键词对 Linear Issue 做跨字段搜索，覆盖标题、描述等文本内容。它与上一个 Block 的区别在于：搜索是"模糊、全文式"的，而按项目/状态过滤是"结构化精确匹配"的，二者互补。

对应源码 Block 见 issues.py：ID 为 b5a2a0e6-26b4-4c5b-8a42-bc79e9cb65c2。

其底层 try_search_issues 走 Linear 的 searchIssues 查询：

query SearchIssues($term: String!, $first: Int, $teamId: String) {
  searchIssues(term: $term, first: $first, teamId: $teamId) {
    nodes {
      id identifier title description priority createdAt
      state { id name type }
      project { id name }
      assignee { id name }
    }
  }
}

每条结果都带有状态、创建时间、项目与负责人信息；teamId 传空表示全局搜索，传值则限定在某一团队内。可选团队过滤的处理逻辑在 search_issues：只有当 team_name 提供时，才先调用 try_get_team_by_name 把它解析为团队 ID 再传入查询；团队不存在时抛出带描述的错误信息。

3.2 输入参数

输入	说明	类型	是否必填	源码补充（默认值 / 约束）
`term`	搜索 Issue 的关键词	`str`	是	无默认值
`max_results`	最大返回条数	`int`	否	默认 `10`，合法范围 1–100
`team_name`	可选团队名过滤（如 `Internal`、`Open Source`）	`str`	否	默认 `None`；提供时解析为 team_id
`credentials`	Linear 凭据	`CredentialsMetaInput`	是	需要 `read` 作用域

字段定义见 issues.py，其中 max_results 的约束为 ge=1, le=100，超出会在 Schema 校验层被拦截。文档特别提示：控制 max_results 能同时控制 Token 消耗与响应体大小——当你把搜索结果直接送入 LLM 做摘要或判重时，较大的 max_results 会显著推高后续模型的输入成本，建议按需取小值。

3.3 输出参数

输出	说明	类型
`issues`	命中搜索条件的 Issue 列表	`List[Issue]`
`error`	搜索或团队解析失败时的错误信息	`str`

3.4 典型应用场景

文档给出的三类场景（issues.md）：

重复检测（Duplicate Detection）：在创建新 Issue 之前先用关键词搜一遍历史，防止重复建档；
关联查找（Related Issues）：按功能或主题关键词找出彼此相关的 Issue，便于批量评审；
快速查询（Quick Lookup）：面向客服或调研场景，按关键词快速定位问题。

其中"创建前查重"与上一节的 Linear Create Issue 是天然搭档：Search Issues 作为前置哨兵，命中为空时才放行到 Create Issue，可以在一个 Graph 内实现去重写入闭环。

四、源码视角：三个 Block 的统一设计与错误处理

4.1 统一的 GraphQL 客户端

三个 Block 复用一个 LinearClient（_api.py），其核心是一个面向 https://api.linear.app/graphql 的通用执行器：

_execute_graphql_request(query, variables) 统一处理 HTTP 请求、query/mutate 两种语义；
所有方法以 try_ 前缀命名，内部把失败统一收敛为 LinearAPIException(message, status_code)，携带可读的 API 错误消息与 HTTP 状态码；
请求封装走平台提供的 Requests 工具，并把 api.linear.app 声明为 trusted_origins。

因此三个 Block 的 run() 实现高度一致：成功则 yield 业务输出；捕获 LinearAPIException 输出 error；其它未知异常则以 Unexpected error: ... 形式兜底（见 issues.py）。在画布上排查失败时，直接看 error 输出的文本即可定位是网络/API 错误还是团队、项目不存在等业务错误。

4.2 测试与数据模型

每个 Block 在注册时都内置了 test_input、test_credentials、test_output 与 test_mock（如 LinearCreateIssueBlock 把 create_issue mock 成固定返回 ("abc123", "Test issue")），这意味着它们可以脱离真实凭据在沙箱中一键试跑。测试凭据 TEST_CREDENTIALS_OAUTH 与 TEST_CREDENTIALS_API_KEY 的定义见 _config.py。

Issue、State、Project、Comment 等数据模型集中在 models.py，其中 Issue.identifier（如 TST-123）对应 Create Issue 输出的 issue_id，是全平台通用的 Issue 展示与引用 ID；State.type 记录工作流状态类别（triage、backlog、started、completed、canceled 等），可在下游逻辑中作为状态分类的依据。

4.3 编排建议（组合示例）

把三个 Block 连成一条"查重 → 创建 → 回读验证"的闭环，可直观展示其组合价值：

Linear Search Issues 以 term 搜索相似标题，max_results 设小值控制成本；
分支节点判断 issues 是否为空：为空走 Linear Create Issue（填 team_name、title、description，可选 priority 0–4 与 project_name）；
创建成功后，可用 Linear Get Project Issues 按项目 + 状态（如 In Progress）拉回数据做验证或进入统计流程；
全程把各 Block 的 error 出口汇总到日志或通知节点，便于人工介入。

当然，这三个 Block 也可以独立挂到 Webhook 触发、定时触发、Agent（LLM）决策分支等上游节点之下，与 Linear 生态的其它能力（评论、项目管理，见 comment.md 与 projects.md）自由组合。

五、快速上手指引

准备凭据：进入平台的 Credentials 管理，选择 Linear Provider，可通过 OAuth2 授权登录，或在设置中填入 Personal API Key；查询类 Block 最低需 read，创建类需 issues:create。
拖入 Block：在 Agent Graph 画布中添加 Linear Create Issue / Linear Get Project Issues / Linear Search Issues，为其绑定已授权的 Linear 凭据。
试跑验证：先点 Block 的测试运行（利用其内置 test input/mock），确认 Schema 与输出结构符合预期，再接入真实数据。
接入业务流：把 error 输出接到处理节点，把 issues / issue_id 输出接到下游 LLM 或统计、通知节点，形成完整自动化。