Linear 来源配置与自用实例

文档状态

draft

文档 Owner

DOC

事实源

canonical-docs

更新

2026/10/16

Linear 提供原生任务、项目、负责人、依赖与业务状态。Symphony 通过适配器读取这些事实；不需要先创建 Plane 工作项，也不在两者之间同步状态。

先选参考实例还是团队实例

场景	采用的规则	操作入口
独立官方参考实例	固定官方实现、自己核对的 WORKFLOW 与原生项目状态	首次运行已有完整准备、配置与观察步骤
AutoDev 自用实例	团队 adp 配置及 Backlog、执行、审核合同	首次任务 → 任务跟进

本文核对官方 be10a1b79df723d6d7612b5651c8522704dafb2e 的源码，以及已有团队实施说明；没有读取目标 live-host 配置或运行真实任务。官方参考配置不证明团队实例在线。

官方 provider 配置

以下片段只说明 tracker 部分，不能独立启动服务。完整 WORKFLOW 复用首次运行，不复制上游仓库自用项目标识或模型。

tracker:
  kind: linear
  provider:
    project_slug: YOUR_PROJECT_SLUG
    api_key: $LINEAR_API_KEY
    endpoint: https://api.linear.app/graphql
  active_states: [Todo, In Progress]
  terminal_states: [Done, Canceled, Duplicate]

先替换项目 URL 中的真实 slug，状态名按该项目实际工作流调整。api_key 省略时也可读取 LINEAR_API_KEY；既有认证须对所选项目有效。可选 assignee 接受 Linear user ID 或 me，缺省还会读取 LINEAR_ASSIGNEE；接入时要检查宿主是否已有这一变量，避免误以为没有负责人筛选。

旧 flat endpoint / api_key / project_slug / assignee 在此版本中保留兼容；新示例采用 tracker.provider。这个兼容结论不适用于其他适配器。

字段与准入差异

原生事实	归一化结果 / 行为
issue ID / identifier	id 为原生 ID，identifier 保留原生编号，native_ref 当前为 nil
state.name	保留原生状态拼写，公共调度器再按配置活跃 / 终态集合判断
assignee	参与该适配器路由匹配；me 需要先解析当前 viewer
inverse blocks 关系	转为 blocked_by；Todo 任务有非终态 blocker 时不派发
labels	修剪、转小写、去重；公共 required_labels 再检查全部所需标签
priority / timestamps	合法整数优先级与可解析时间保留；缺失或无效值按模型处理，不补造

候选读取和 ID 刷新均按项目范围读取；分页及批量刷新由 client 处理。来源依据为固定 Linear Adapter、Linear Client与 README。

原生工具与团队扩展

官方适配器可提供 linear_graphql。它使用宿主认证，能力受该凭据实际权限限制；project_slug 限定调度读取，不构成任意 GraphQL 写入的授权范围或幂等保证。

团队自用文档说明 adp 直接使用官方 Linear adapter。backlog.enabled、review.enabled、私有图片读取和审核桥属于各自团队扩展；不能套用独立参考示例的 Todo 规则绕过它们。自用边界保留在实施说明与团队产品合同，本页不重复定义。

缺任务时检查项目、状态、宿主 assignee、依赖、标签与来源访问；发现 token / scope 错误先修相应配置，不新建重复任务或改用 Plane fallback。执行问题继续查失败与恢复。