setup

设置 — 先决条件与 MCP 配置

安装命令行工具，完成 GitHub/GitLab 身份验证，并为 OpenCode 配置 mcp-atlassian Jira 集成。

先决条件

• 使用 apt 包管理器的 Linux 系统
• 已安装 bash 和 curl
• 可访问互联网（用于安装 apt 软件包和 uv 安装程序）

触发条件

用户说：“设置”“安装先决条件”“配置 Jira”或类似内容。

重要 — 仅限交互式技能。 此技能需要用户交互（身份验证提示、Jira 凭据）。不得将其作为自主技能工作流（fast-meeting、issue-review 等）的子步骤调用，否则工作流会停滞，等待永远不会到来的输入。

---

工作流

阶段 1 — 安装命令行工具

运行随附脚本以安装缺少的工具（可重复执行 — 跳过已安装的工具）：

bash "$(dirname "$0")/reference/setup.sh"

脚本会安装以下工具（如果尚未安装，则通过 apt 安装）：

• gh — GitHub CLI
• glab — GitLab CLI
• jq — JSON 处理器
• uvx — 通过官方 uv 安装程序安装（curl -LsSf https://astral.sh/uv/install.sh | sh）

运行后，告知用户哪些工具是新安装的，哪些已存在。

阶段 2 — CLI 身份验证

检查每个 CLI 并完成身份验证：

gh auth status 2>&1

• 向用户显示完整输出（当前登录的账户、令牌权限范围等）
• 如果尚未通过身份验证 → 告诉用户：“运行 gh auth login 并按照提示操作。”
• 不要自动运行 gh auth login（需要交互式输入）。

glab auth status 2>&1

• 向用户显示完整输出（GitLab 实例、当前用户、令牌有效性等）
• 如果尚未通过身份验证 → 告诉用户：“运行 glab auth login 并按照提示操作。”
• 不要自动运行 glab auth login。

阶段 3 — 为 Jira 配置 mcp-atlassian

步骤 3.1 — 检查 uvx 是否可用：

uvx --version 2>&1 || ~/.local/bin/uvx --version 2>&1

如果未找到，请提醒用户在阶段 1 脚本运行后重启 shell，或加载 ~/.bashrc / ~/.profile。

步骤 3.2 — 读取现有 OpenCode 配置：

使用 Read 工具读取 ~/.config/opencode/opencode.json。

• 如果文件不存在，则将其视为 {}。
• 如果已存在 mcp.mcp-atlassian → 向用户确认并跳过阶段 3 的其余步骤。

步骤 3.3 — 收集凭据（如果尚未配置）：

在一条消息中向用户询问以下两个问题：

1. Jira URL — 默认值为 https://jira.dedalus.com/（Server/Data Center）。按 Enter 接受默认值。
2. Jira Personal Access Token (PAT) — 生成步骤：
   • 登录 Jira 实例
   • 前往 个人资料 → Personal Access Tokens
   • 点击 Create token，为令牌命名并设置到期时间
   • 复制令牌并粘贴到此处

对于 Jira Cloud 用户：使用 JIRA_USERNAME（电子邮件地址）和 JIRA_API_TOKEN（从 https://id.atlassian.com/manage-profile/security/api-tokens 获取），而不是 PAT。

步骤 3.4 — 写入配置：

将 mcp-atlassian 配置块合并到 ~/.config/opencode/opencode.json，保留所有现有内容。使用 Write 工具写入最终 JSON。

对于 Server/Data Center（默认）：

{
  "mcp": {
    "mcp-atlassian": {
      "type": "local",
      "command": ["uvx", "mcp-atlassian"],
      "environment": {
        "JIRA_URL": "<jira-url>",
        "JIRA_PERSONAL_TOKEN": "<pat>"
      },
      "enabled": true
    }
  }
}

对于 Cloud（如果用户指定）：

{
  "mcp": {
    "mcp-atlassian": {
      "type": "local",
      "command": ["uvx", "mcp-atlassian"],
      "environment": {
        "JIRA_URL": "<jira-url>",
        "JIRA_USERNAME": "<email>",
        "JIRA_API_TOKEN": "<api-token>"
      },
      "enabled": true
    }
  }
}

步骤 3.5 — 保护配置文件：

chmod 600 ~/.config/opencode/opencode.json

阶段 4 — 总结

打印清晰的汇总表：

组件	状态
gh	已安装 / 已就绪
glab	已安装 / 已就绪
jq	已安装 / 已就绪
uvx	已安装 / 已就绪
gh auth	已通过身份验证 / 需要操作
glab auth	已通过身份验证 / 需要操作
mcp-atlassian	已配置 / 已就绪 / 已跳过

最后提示：“重启 OpenCode 以加载新的 MCP 配置。”