Linear 工作流机器人

自动化流水线：Linear → Webhook 平台 → 通知通道 → 任务执行 → Git 同步

在 Linear 创建的任务自动触发处理，实时通知、执行、回写结果并同步到 Git 仓库。

平台选型决策表

选型规则：

• 预算敏感 + 任务量 < 1000/月 → Make.com
• 任务量 > 1000/月 或需即时 → 自建 webhook 接收器（Node/Python 单文件）
• 已有 Zapier 付费 → Zapier

快速开始

5 步完成首次接入：

1. 配置 Linear API — 在 ~/.linearbot/linear.env 写入 LINEAR_API_KEY
2. 获取团队/状态 ID — ./scripts/linear-api.sh teams 与 states
3. 写配置中心 — 编辑 ~/.linearbot/config.json（schema 见下文）
4. 接 Webhook 平台 — 按选型表选一个，按对应章节配置
5. 跑健康检查 — ./scripts/linearbot doctor 验证全链路

配置中心 schema

替代原版散落多文件，单一 JSON 管理：

{
  "$schema": "linearbot/v1",
  "linear": {
    "teamId": "team-uuid",
    "states": {
      "todo": "state-uuid",
      "inProgress": "state-uuid",
      "done": "state-uuid",
      "canceled": "state-uuid"
    },
    "watchFilter": "state.name = \"Todo\" AND assignee.id = \"<your-id>\""
  },
  "notify": {
    "channel": "discord",
    "discord": {
      "botToken": "${DISCORD_BOT_TOKEN}",
      "notifyUserId": "discord-user-id",
      "taskChannelId": "channel-id",
      "allowBots": true
    }
  },
  "git": {
    "repo": "/path/to/repo",
    "autoPush": true,
    "commitPrefix": "task:",
    "branch": "main",
    "conflictStrategy": "rebase"
  },
  "quota": {
    "platform": "make",
    "monthlyLimit": 1000,
    "warningThreshold": 0.8,
    "degradeStrategy": "batch-daily"
  }
}

变量引用 ${VAR} 从环境变量读取，避免明文 secrets 入库。

Webhook 平台配置

Make.com（推荐）

1. 新建 scenario → 添加 Linear "Watch Issues" 触发器
2. 加 filter：state.name = "Todo"（与配置中心 watchFilter 对齐）
3. 加 "Webhook" 动作 → 指向你的任务执行端点
4. 加 "Discord" 动作发通知（可选，避免与执行端重复）
5. 启用 scenario，记录 scenario ID 用于额度监控

Pipedream（需即时）

1. 新建 workflow，HTTP webhook 触发器
2. 在 Linear 配置 webhook 指向 Pipedream URL
3. 加 "Send Message" 步骤到 Discord
4. 消息模板：

<@BOT_ID>
New task: {{steps.trigger.event.data.title}}
Status: {{steps.trigger.event.data.state.name}}
ID: {{steps.trigger.event.data.identifier}}
URL: {{steps.trigger.event.data.url}}

自建 webhook 接收器（无额度限制）

# receiver.py - 单文件 Flask 接收器
from flask import Flask, request
import subprocess
app = Flask(__name__)

@app.route("/linear", methods=["POST"])
def linear():
    event = request.json
    if event.get("action") == "create":
        subprocess.Popen(["./scripts/handle-task.sh", event["data"]["identifier"]])
    return "", 200

部署到任意 VPS，配合 systemd 守护。

任务处理闭环

任务到达通道后的处理流程，每步都有失败补偿：

状态机

Todo ──(收到)──> In Progress ──(成功)──> Done
                       │
                       ├──(超时)──> Stalled ──(用户介入)──> In Progress / Canceled
                       │
                       └──(失败)──> In Progress + 评论告警

Webhook 自愈流程

每小时心跳：
 ├─ 调 Make/Pipedream API 查 scenario 最近运行
 ├─ 30 min 无运行 → 发测试 webhook 探活
 ├─ 探活失败：
 │   ├─ 重投最近 5 条历史任务（去重）
 │   ├─ 通知用户 webhook 异常
 │   └─ 切换到备用平台（若配置了 fallback）
 └─ 死信队列：3 次失败的任务进 DLQ，等用户手动处理

免费额度监控

# 每日检查 Make.com 用量
./scripts/linearbot quota-check
# 输出：本月已用 823/1000 ops (82%)，临近阈值，启用降级

降级策略（degradeStrategy）：

• batch-daily：把即时触发改为每日 22:00 批量处理
• drop-low-priority：丢弃低优先级标签的任务
• switch-platform：自动切到备用平台

脚本参考

scripts/linear-api.sh 命令：

scripts/linearbot 命令：

任务类型与产出归档

真实场景示例

场景1：研究类任务自动归档

Linear 任务 ENG-456 "调研 wasm 在边缘计算的应用"
1. 收到 → Discord 通知 + DM
2. start ENG-456
3. 子 Agent 调研，生成 research/wasm-edge-computing.md
4. comment ENG-456 "已完成，见 research/wasm-edge-computing.md"
5. done ENG-456
6. git add research/ && commit -m "task: ENG-456 wasm调研" && push

场景2：内容批量生产

Linear 任务 ENG-457 "写 5 篇产品文案"
1. 收到 → 通知
2. start
3. 子 Agent 按 5 个主题各生成一篇，存 content/
4. comment-file ENG-457 /tmp/summary.md（含 5 篇链接）
5. done + git push

场景3：Webhook 故障自愈

doctor 发现 Make scenario 30 min 无运行
1. 发测试 webhook → 失败
2. 重投最近 5 条任务到备用 Pipedream workflow
3. Discord 告警 "Make 异常，已切 Pipedream"
4. 用户收到通知后修复 Make，linearbot resume 回切

FAQ

Q1: 免费 1000 ops 会超吗？ A: 单人日均任务 < 30 条基本够。每条任务平均消耗 2-3 ops（触发 + 通知）。超过 80% 阈值自动降级到 batch-daily。

Q2: Git push 冲突怎么办？ A: 按 conflictStrategy：rebase（默认，自动 rebase 后重试 3 次）、merge（生成 merge commit）、abort（放弃同步并告警）。

Q3: 子 Agent 执行超时？ A: 默认 30 min 超时标记 Stalled。可在 config 中调 executionTimeout。Stalled 任务不自动取消，等用户介入。

Q4: 多个 Linear 团队怎么配？ A: 配置中心支持 teams 数组，每个团队独立 watchFilter 与通知通道。Git 同步可按团队分仓库或分目录。

Q5: 凭证安全？ A: 所有 secrets 用 ${VAR} 引用环境变量，不写入 config.json。~/.linearbot/ 目录权限设为 600。

故障排查

依赖说明

运行环境

• Agent 平台: 任意支持 SKILL.md 的 AI Agent
• 操作系统: Windows / macOS / Linux
• Shell: bash 推荐（脚本依赖）
• Git: 已配置 remote 与认证

第三方依赖

API Key 配置

• LINEAR_API_KEY：Linear → Settings → API → Personal API keys
• DISCORD_BOT_TOKEN：Discord Developer Portal → Bot → Token
• Make/Pipedream API Token：对应平台账号设置
• 全部存于环境变量或 ~/.linearbot/*.env（权限 600），勿入库

可用性分类

• 分类: MD+EXEC（Markdown 指令 + 必须通过 exec 执行脚本与 webhook 调用）
• 说明: 基于自然语言指令驱动 Agent 搭建并运维 Linear 任务流水线，含自愈与降级机制