cyrus-setup-linear

重要：切勿使用 Read、Edit 或 Write 工具读取或修改 ~/.cyrus/.env 或 ~/.cyrus/ 中的任何文件。只能使用 Bash 命令（grep、printf >> 等）与环境文件交互——绝不能将密钥读入对话上下文。切勿从网页抓取、提取或读取密钥值——应引导用户手动复制。

设置 Linear

创建 Linear OAuth 应用并配置凭据，以便 Cyrus 接收 Webhook 并响应问题。

第 1 步：检查现有配置

grep -E '^LINEAR_CLIENT_ID=' ~/.cyrus/.env 2>/dev/null

如果已设置 LINEAR_CLIENT_ID，请检查 OAuth 配置是否也已完成：

grep -q '"workspaces"' ~/.cyrus/config.json 2>/dev/null && echo "configured" || echo "not configured"

如果两者都已设置，请告知用户：

Linear 已配置。跳过此步骤。 若要重新配置，请从 ~/.cyrus/.env 中移除 LINEAR_CLIENT_ID、LINEAR_CLIENT_SECRET 和 LINEAR_WEBHOOK_SECRET，然后重新运行。

跳至完成步骤。

第 2 步：获取 CYRUS_BASE_URL

从环境文件中读取基础 URL（由 setup-endpoint 设置）：

grep '^CYRUS_BASE_URL=' ~/.cyrus/.env | cut -d= -f2-

回调和 Webhook URL 需要使用此 URL。

第 3 步：通过清单创建 Linear OAuth 应用

必须通过基于清单的设置 URL 创建 Linear OAuth 应用。不要从头创建应用，也不要手动填写每个字段。清单流程可确保应用配置可复现，并避免回调、Webhook 和事件类型设置出现偏差。

3a. 构建清单 URL

生成 JSON OAuth 应用清单，并将其编码到 Linear 的 manifest 查询参数中：

CYRUS_BASE_URL="<CYRUS_BASE_URL>" \
AGENT_NAME="<AGENT_NAME>" \
AGENT_DESCRIPTION="<AGENT_DESCRIPTION>" \
node <<'NODE'
const fs = require("node:fs");

const baseUrl = process.env.CYRUS_BASE_URL.replace(/\/+$/, "");
const agentName = process.env.AGENT_NAME || "Cyrus";
const agentDescription =
	process.env.AGENT_DESCRIPTION || "AI coding agent for automated development";

const manifest = {
	$schema: "https://linear.app/.well-known/oauth-app-manifest.schema.json",
	schemaVersion: "1.0.0",
	distribution: "private",
	display: {
		description: agentDescription,
	},
	developer: {
		name: "Self-hosted",
	},
	oauth: {
		client_name: agentName,
		client_uri: "https://github.com/ceedaragents/cyrus",
		redirect_uris: [`${baseUrl}/callback`],
		grant_types: ["authorization_code"],
	},
	webhook: {
		enabled: true,
		url: `${baseUrl}/linear-webhook`,
		resourceTypes: [
			"AgentSessionEvent",
			"AppUserNotification",
			"PermissionChange",
			"Issue",
		],
	},
};

const manifestJson = JSON.stringify(manifest, null, 2);
const manifestUrl = `https://linear.app/settings/api/applications/new?manifest=${encodeURIComponent(JSON.stringify(manifest))}`;

fs.writeFileSync("/tmp/cyrus-linear-oauth-app-manifest.json", `${manifestJson}\n`);
fs.writeFileSync("/tmp/cyrus-linear-oauth-app-url.txt", `${manifestUrl}\n`);

console.log(manifestJson);
console.log(`\n${manifestUrl}`);
NODE

LINEAR_MANIFEST_URL="$(cat /tmp/cyrus-linear-oauth-app-url.txt)"

同一 URL 现已存储在 LINEAR_MANIFEST_URL 中，供自动化命令使用；也存储在 /tmp/cyrus-linear-oauth-app-url.txt 中，供手动复制粘贴。JSON 存储在 /tmp/cyrus-linear-oauth-app-manifest.json 中，仅供审查和调试；不要要求用户根据该文件手动填写 OAuth 应用表单。

如果 <AGENT_NAME> 中包含“Linear”一词或 URL，请在构建清单前选择其他 OAuth 应用名称。Linear 会拒绝包含这些内容的 OAuth 客户端名称。

确定要使用哪种浏览器自动化模式（请参阅编排器规则）：

1. 如果有 claude-in-chrome MCP 工具 → 使用 路径 A-1（claude-in-chrome）
2. 如果已安装 agent-browser（which agent-browser），且已连接 Chrome 调试会话 → 使用 路径 A-2（agent-browser）
3. 否则 → 使用 路径 B（手动操作）

路径 A-1：claude-in-chrome 自动化

使用 mcp__claude-in-chrome__* 工具在用户现有的 Chrome 浏览器中导航并进行交互。用户很可能已经登录 Linear。

导航至 LINEAR_MANIFEST_URL。页面应会打开，并已填入应用清单配置。

仅检查非机密字段：

• 应用名称与 <AGENT_NAME> 一致
• 开发者名称为 Self-hosted
• 开发者 URL 为 https://github.com/ceedaragents/cyrus
• 重定向回调 URL 包含 <CYRUS_BASE_URL>/callback
• 已启用 Webhook，URL 为 <CYRUS_BASE_URL>/linear-webhook
• 事件类型包括 Agent 会话事件、收件箱通知、权限变更和问题
• 公开/分发状态为私有或已禁用

如果用户尚未登录，请暂停并要求其登录。检查完成后，点击 Create。**请勿截取凭据页面的屏幕截图，也不要尝试抓取密钥。**继续执行第 4 步。

路径 A-2：agent-browser 自动化

如果 agent-browser 已连接 Chrome 调试会话，请自动创建 Linear 应用。

3b. 导航至清单 URL

agent-browser navigate "$LINEAR_MANIFEST_URL"

等待页面加载。截取屏幕截图，确认打开的是正确页面且已登录。

3c. 检查并创建

检查与路径 A-1 中相同的、已应用清单的非机密字段。如果页面要求用户登录，请暂停并让其完成登录。点击 Create。

创建完成后，Linear 会重定向至应用设置页面。**请勿截取凭据页面的屏幕截图，也不要尝试抓取密钥。**继续执行第 4 步。

路径 B：手动引导设置

引导用户手动创建：

创建 Linear OAuth 应用

1. 打开此由清单支持的 Linear 应用创建 URL：

   <LINEAR_MANIFEST_URL>

2. 如果出现提示，请登录 Linear，然后检查预填的设置：

   • 应用名称： <AGENT_NAME>
   • 开发者名称： Self-hosted
   • 开发者 URL： https://github.com/ceedaragents/cyrus
   • 重定向回调 URL： <CYRUS_BASE_URL>/callback
   • Webhook URL： <CYRUS_BASE_URL>/linear-webhook
   • Webhook： ✓ 已启用
   • 事件类型： ✓ Agent 会话事件、✓ 收件箱通知、✓ 权限更改、✓ Issues
   • 公开： ✗ 保持禁用（这是一个私有的可自托管应用）

3. 点击 创建

继续执行第 4 步。

第 4 步：收集凭据

Agent 绝不能从页面抓取、读取或提取密钥。 用户需要手动将它们复制到 env 文件中。

4a. 添加凭据占位符

grep -q '^LINEAR_CLIENT_ID=' ~/.cyrus/.env || echo 'LINEAR_CLIENT_ID=' >> ~/.cyrus/.env
grep -q '^LINEAR_CLIENT_SECRET=' ~/.cyrus/.env || echo 'LINEAR_CLIENT_SECRET=' >> ~/.cyrus/.env
grep -q '^LINEAR_WEBHOOK_SECRET=' ~/.cyrus/.env || echo 'LINEAR_WEBHOOK_SECRET=' >> ~/.cyrus/.env

4b. 打开 env 文件进行编辑

# macOS
code --new-window ~/.cyrus/.env 2>/dev/null || open -a TextEdit ~/.cyrus/.env
# Linux
code --new-window ~/.cyrus/.env 2>/dev/null || xdg-open ~/.cyrus/.env

4c. 引导用户

告诉用户：

我已打开 ~/.cyrus/.env。你需要从 Linear 应用设置页面粘贴以下三个值：

1. 客户端 ID — 复制后粘贴到 LINEAR_CLIENT_ID= 后面
2. 客户端密钥 — 点击旁边的复制按钮（该值以圆点隐藏），然后粘贴到 LINEAR_CLIENT_SECRET= 后面
3. Webhook 签名密钥 — 点击旁边的复制按钮，然后粘贴到 LINEAR_WEBHOOK_SECRET= 后面

完成后保存并关闭文件。

4d. 验证

用户确认已保存后：

grep -c '^LINEAR_CLIENT_ID=.' ~/.cyrus/.env
grep -c '^LINEAR_CLIENT_SECRET=.' ~/.cyrus/.env
grep -c '^LINEAR_WEBHOOK_SECRET=.' ~/.cyrus/.env

三项都必须返回 1（= 后面的 . 可确保值不为空）。如果任何一项返回 0，请让用户检查文件。

第 5 步：使用 Linear 授权

运行 OAuth 授权流程：

cyrus self-auth-linear

这将：

1. 启动临时 OAuth 回调服务
2. 在浏览器中打开 Linear 授权页面
3. 用户点击 授权 后，将令牌保存到 ~/.cyrus/config.json

验证授权是否成功：

cat ~/.cyrus/config.json | grep -c '"workspaces"'

如果计数为 0，则授权失败。请让用户检查凭据并重试。

完成

✓ 已创建 Linear OAuth 应用 ✓ 已将凭据保存到 ~/.cyrus/.env ✓ 已通过 cyrus self-auth-linear 授权工作区