Hermes Agent 与 Linear 看板双向联动需完成五步：一、获取并配置具备 Issues/Projects 权限的 API Key；二、安装 linear-toolset 插件并注册至 config.yaml；三、设置 Linear Webhook 推送事件至 Hermes Gateway；四、编写 YAML 规则定义自动创建 Issue 的触发逻辑；五、通过指令测试创建与状态回传是否准确。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您希望 Hermes Agent 与 Linear 任务看板实现双向联动，使 AI 能自动创建 Issue 并实时同步开发进度，则需完成 API 接入、权限配置与事件触发规则设定。以下是实现该功能的具体步骤：
一、获取 Linear API Key 并配置权限
Linear 使用基于团队和项目的细粒度权限模型，Hermes Agent 需以服务账户身份获得 Issue 创建与状态更新权限。必须在 Linear 团队设置中启用 API 访问，并为 Hermes 分配专用 API Key。
1、登录 Linear 官网（linear.app），进入当前团队 Settings → Developers → API keys。
2、点击 “Create API key”，填写名称为 hermes-agent-prod，勾选 “Issues: Read & Write” 和 “Projects: Read” 权限。
3、复制生成的密钥字符串，该密钥仅显示一次，丢失需重新创建。
4、将密钥写入 Hermes Agent 的环境变量文件：~/.hermes/.env，添加一行：LINEAR_API_KEY=your_copied_key_here。
二、安装并启用 Linear Toolset 插件
Hermes Agent 通过 toolset 扩展外部系统集成能力，Linear 功能由官方维护的 linear-toolset 提供，需显式安装并注册至 agent 配置中。
1、在已激活 Hermes 虚拟环境的终端中执行：pip install hermes-linear-toolset。
2、编辑 Hermes Agent 主配置文件：~/.hermes/config.yaml。
3、在 toolsets: 区块下新增条目：- linear。
4、保存后运行 hermes reload 使配置生效，确认日志中出现 Loaded toolset: linear。
三、配置 Linear Webhook 实现进度自动回传
当 Linear 中 Issue 状态变更（如从 Todo → In Progress → Done）时，需通过 Webhook 将事件推送给 Hermes Gateway，触发本地进度追踪逻辑。此步骤确保 Hermes 始终掌握最新任务状态。
1、在 Linear 团队 Settings → Developers → Webhooks → “Create webhook”。
2、URL 填写为 Hermes Gateway 的公开接入地址，格式为：https://your-gateway-domain.com/webhook/linear（若本地调试，可使用 ngrok 暴露 localhost:8000）。
3、Events 勾选：issue.updated 和 issue.created。
4、在 Webhook 设置页底部点击 “Generate secret”，复制该 secret 值。
5、将 secret 写入 ~/.hermes/.env，添加行：LINEAR_WEBHOOK_SECRET=your_generated_secret。
四、定义 Issue 自动创建规则（YAML 触发器）
Hermes Agent 支持基于自然语言指令或结构化输入自动生成 Linear Issue。需在 skills 目录下编写 YAML 规则文件，声明触发条件、字段映射与默认标签。
1、在 ~/.hermes/skills/ 下新建文件：linear-issue-auto-create.yaml。
2、填入以下内容（字段值可根据团队规范调整）：
trigger: "create linear issue for [feature|bug|task] [description]"
tool: linear.create_issue
params:
title: "{description}"
description: "Auto-created by Hermes Agent. Source: {source_context}"
projectId: "lin_abc123"
labelIds: ["lbl_def456"]
3、保存后执行 hermes skill reload 加载新规则。
五、验证双向同步功能
完成全部配置后，需通过真实交互验证 Issue 创建与状态回传是否准确无误。此步骤不可跳过，用于确认各组件间协议兼容性与认证有效性。
1、在终端运行：hermes chat "create linear issue for user login fails with 500 error"。
2、检查 Linear 看板是否在对应项目中出现新 Issue，且标题、描述、标签与项目匹配。
3、手动在 Linear 中将该 Issue 状态改为 Done。
4、等待约 10 秒，在 Hermes 终端查看是否输出类似：[INFO] Linear issue lin-789 updated to status 'Done'。
5、若第 2 或第 4 步失败，检查 hermes logs --tail 50 中的错误提示，重点关注认证失败、Webhook signature mismatch 或 project ID 不存在等信息。
