@issuer/cli

技能驱动的项目管理网关。拆解需求 → 通过 MCP 同步到任意平台。内置支持：GitHub、GitLab、云效、PingCode。

English | 中文

issuer 由两个精简层组成：

• 技能 (Skills) — Markdown 契约，约束编码 Agent 的 AI 如何将原始需求文本转换为结构化的 PM 工作项。issuer 本身不包含任何 AI；您已使用的 Agent 提供 AI 能力。
• CLI — 一个小型 Node.js 二进制文件，负责网络交互：将准备好的任务文件推送到 GitHub / GitLab / 云效 / PingCode。CLI 从不调用 LLM。

安装

npm i -g @issuer/cli

需要 Node.js 20+。

快速开始

# 1. 初始化项目（交互式，或传递参数）
issuer init -y --platform github --owner my-org --repo my-repo

# 2. 将捆绑的技能安装到您的 Agent 中
issuer skill install

# 3. 在您的 Agent（Claude / Qoder / Cursor / OpenCode / …）中调用：
#       /issuer
#    粘贴原始需求文本。技能链：breakdown → sync。

Agent 将：

1. 将原始文本拆分为 .issuer/tasks/YYYY-MM-DD-<slug>.md 文件，每个文件对应一个工作项，初始状态为 status: draft（issuer-breakdown）。
2. 询问您将哪些任务设置为 status: ready。
3. 将准备好的任务推送到配置的平台（issuer-sync）。

可选：添加 --refine 标志或要求 Agent 先精炼需求，再拆解任务。

工作原理

两个核心技能通过显式用户检查点链接（refine 为可选）：

原始文本
  ├─▶ [可选: issuer-refine]  →  丰富的 PRD 风格简报 (.issuer/briefs/<slug>.md)
  │         [检查点 — 用户批准]
  └─▶ 阶段 1: issuer-breakdown  →  任务文件 (.issuer/tasks/*.md, status: draft)
          [检查点 — 用户选择要提升的任务]
  └─▶ 阶段 2: issuer-sync       →  远程工作项 (status: synced)

/issuer — 编排器

主流程。通过阶段间的检查点链接 breakdown → sync。

| 阶段 | 技能 | 输出 | 检查点 | |-------|-------|--------|------------| | 0（可选） | issuer-refine | .issuer/briefs/<slug>.md | 用户批准简报文本 | | 1 | issuer-breakdown | .issuer/tasks/*.md (draft) | 用户选择哪些文件 → ready | | 2 | issuer-sync | 远程工作项 (synced) | 无 — 自动推送 ready 文件 |

三种调用模式：

• 快捷模式: /issuer <text> — 直接进入 breakdown，仍需要阶段 1 检查点
• 交互模式: /issuer — 询问是否先精炼，然后询问源范围和工作目录
• 带精炼: /issuer --refine <text> 或明确要求精炼 → 运行 refine → breakdown → sync

/issuer-refine — 精炼原始需求（可选）

注意：此技能是可选的。仅在用户明确要求时运行。

将粗糙的需求文本精炼为专业的 PRD 风格简报。

使用时机：

• 需要结构和澄清的复杂需求
• 需要记录验收标准和假设时
• 输入模糊或不完整时

关键步骤：

1. 评估输入质量 — 五维评分（结构、专业措辞、可验证性、边界、假设）
2. 揭示假设 — 在进行之前列出模糊的解释
3. 重构模糊需求 — "更快" → "≤2秒"，"更好的用户体验" → "≤3步"
4. 编写简报 — 问题 / 目标 / 假设 / 边界 / 验收标准（复选框）

输出: .issuer/briefs/<slug>.md，标题本地化以匹配用户语言。

/issuer-breakdown — 将简报拆分为任务

读取原始文本（或精炼的简报）并为每个工作项生成一个 Markdown 文件。

平台自适应风格：自动适配您平台的最佳实践 — 零配置即可使用！

| 平台 | 风格 | 验收标准 | 工作量估算 | |----------|-------|---------------------|-------------------| | 云效 (Yunxiao) | 正式、结构化 | Given-When-Then 格式 | ✅ 必需 | | GitHub | 随意、开发者友好 | Markdown 复选框 | ❌ 可选 | | GitLab | 技术、精确 | 复选框 + 技术说明 | ❌ 可选 | | PingCode | 结构化、HTML 格式化 | HTML 复选框列表 | ❌ 可选 | | Jira | 敏捷原生、严谨 | Story (GWT/DoD) / Bug (重现步骤) / Task (分阶段实施) / Epic (里程碑) | ❌ 可选（使用故事点单独估算） |

关键步骤：

1. 解析输入 — 识别工作项（bug/story/task/epic）
2. 应用平台风格 — 根据配置中的 platform 自动格式化
3. 写入任务文件 — .issuer/tasks/YYYY-MM-DD-<slug>.md，带有 YAML frontmatter
4. 展示批准提示 — 用户选择哪些文件设置为 status: ready

自定义模板（可选）：

内置了模板的平台（GitHub、GitLab、云效、PingCode、Jira）会直接使用 skills/issuer-breakdown/templates/ 中高度定制且经过优化的平台特定模板。对于完全未知的、不支持的平台或需要自定义的工作流：

# 创建自定义模板
cp .issuer/templates/breakdown.md .issuer/templates/my-custom-template.md

# 添加到 config.yml
breakdown_template: .issuer/templates/my-custom-template.md

输出格式：

---
id: 2026-05-07-fix-login
type: bug
title: 修复登录验证错误
status: draft  # → 用户选择后变为 ready
platform: github
labels: []
---

/issuer-sync — 推送任务到平台

读取所有 status: ready 任务文件并创建/更新远程工作项。

特性：

• MCP 优先：如果可用，使用 MCP 工具
• CLI 回退：如果 MCP 缺少功能，回退到平台 API
• 去重检测：将标题与缓存的远程问题进行比较
• 状态更新：将成功同步的任务标记为 status: synced

平台设置

未内置平台（MCP 优先）

任何具有 MCP 服务器的平台都可以支持 — 无需修改代码！

issuer init -y --platform "Other (MCP)" --owner my-workspace --repo my-project

初始化期间：

• 从平台列表中选择 "Other (MCP)"
• 提供您的工作空间/项目标识符
• 通过 ISSUER_<PLATFORM>_TOKEN 环境变量设置令牌
• Issuer 自动在 .issuer/templates/breakdown.md 创建通用拆解模板

CLI 使用 MCP 进行同步操作，使用通用模板进行任务生成。

GitHub

issuer init -y --platform github --owner my-org --repo my-repo

凭证（按顺序解析）：

1. ISSUER_GITHUB_TOKEN
2. GITHUB_TOKEN
3. ~/.issuer/credentials.yml → github_token: ghp_xxxx

在 github.com/settings/tokens 创建具有 repo 范围的令牌。

MCP：如果 GitHub MCP 服务器已连接到您的 Agent，issuer-sync 将直接调用这些工具 — 不需要额外的凭证。

云效 (Yunxiao)

issuer init -y --platform yunxiao --owner <organizationId> --repo <spaceIdentifierId>

• --owner → 云效 organization ID（企业标识，从 https://devops.aliyun.com/organization/<organizationId> 中获取）
• --repo → 云效 project ID（spaceIdentifierId / projectId）

凭证（按顺序解析）：

1. ISSUER_YUNXIAO_TOKEN
2. YUNXIAO_TOKEN
3. ~/.issuer/credentials.yml → yunxiao_token: xxxx

在云效 → 个人设置 → 个人访问令牌创建 Personal Access Token，勾选以下权限：

• 项目协作 (工作项读写) — 创建/更新/搜索工作项
• 组织管理 - 用户 (只读) — 首次推送时获取您的用户 ID（GetUserByToken API）

注意：首次 issuer push 时，CLI 会自动通过 GetUserByToken API 获取您的用户 ID 并保存到 .issuer/config.yml。这需要「组织管理 - 用户」(只读) 权限。

MCP：云效 MCP (alibabacloud-devops-mcp-server) 目前覆盖 create/update/search/read (4/4)。若 MCP 不可用，CLI 适配器使用 Bearer <PAT> 身份验证调用云效 OpenAPI openapi-rdc.aliyuncs.com — 提供完整的 4/4 能力覆盖。

GitLab

issuer init -y --platform gitlab --owner my-group --repo my-project

• --owner → GitLab 组或命名空间
• --repo → GitLab 项目名称或 ID

MCP：GitLab 内置 MCP 服务器（GitLab 18.6+，https://<gitlab.example.com>/api/v4/mcp）覆盖 create/update/search/read (4/4)。若 MCP 不可用，CLI 适配器处理所有操作。

PingCode

issuer init -y --platform pingcode --repo SCR

• --repo → PingCode 项目标识（identifier），不区分大小写，将自动转为大写

获取令牌：

PingCode 支持两种访问令牌。两种都需要先创建应用：

【管理后台】-【应用】-【凭据管理】

1. 创建应用（两种令牌都需要）：

   • 访问：https://<你的组织>.pingcode.com/admin/application/custom
   • 创建新应用
   • 鉴权方式选择：企业令牌：Client Credentials；用户令牌：Authorization Code
   • 设置权限：
     • 项目管理：只读
     • 工作项：读写
     • 项目配置中心：只读
   • 记录你的 client_id 和 client_secret

   Authorization Code 需要配置回调地址， 可以是 http://localhost，用于获取code.

2. 获取访问令牌：

   企业令牌：

   GET https://open.pingcode.com/v1/auth/token
     ?grant_type=client_credentials
     &client_id=YOUR_CLIENT_ID
     &client_secret=YOUR_CLIENT_SECRET

   用户令牌：

   • 使用 OAuth 2.0 Authorization Code 流程
   • 详见：https://open.pingcode.com/#api-鉴权
   • 浏览器访问: https://open.pingcode.com/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID
   • 点击【授权】等待跳转，获得redirect_uri中的code

   https://open.pingcode.com/v1/auth/token?grant_type=authorization_code&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=YOUR_CODE

3. 使用令牌：

   issuer auth
   # → Enter PingCode token: <粘贴你的 access_token>

凭证（按顺序解析）：

1. ISSUER_PINGCODE_TOKEN
2. PINGCODE_TOKEN
3. ~/.issuer/credentials.yml → pingcode_token: your_access_token
4. .issuer/credentials.yml → pingcode_token: your_access_token

项目 ID 解析：

• 只需提供项目标识（如 SCR、PROJ）
• 适配器首次使用时自动解析为项目 ID
• 解析后的 ID 保存到 .issuer/config.yml，后续操作更快

MCP：PingCode MCP Server 尚未推出。CLI 适配器使用 PingCode REST API，提供完整的功能覆盖（创建、更新、搜索、读取）。

Jira (仅通过 Atlassian Rovo MCP)

issuer init -y --platform jira --owner company.atlassian.net --repo PROJ

• --owner → Jira Cloud 域名（例如 company.atlassian.net）
• --repo → Jira 项目键（Project Key，例如 PROJ、MYAPP）

同步：Jira 是一个仅支持 MCP (MCP-only) 的平台。同步操作通过您的 AI Agent 中的 Atlassian Rovo MCP 服务 执行。不需要 CLI REST API 适配器或个人访问令牌。

首次 MCP 设置 — 在您的 AI Agent 中配置 Rovo MCP 服务：

{
  "mcpServers": {
    "atlassian-rovo": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/mcp"]
    }
  }
}

然后运行以下命令一次以完成 OAuth 2.1 浏览器授权许可：

npx -y mcp-remote https://mcp.atlassian.com/v1/mcp

重启您的 Agent，然后使用 /issuer-sync 将任务推送到 Jira。

注意：Jira 不支持 issuer push CLI 命令。请在您的 AI Agent 内使用 /issuer-sync 代替。

Linear (仅通过 Linear MCP 服务)

issuer init -y --platform linear --owner company --repo ENG

• --owner → Linear 工作区名称（Workspace Name，例如 company）
• --repo → Linear 团队标识符（Team Identifier / Team Key，例如 ENG、SWE）

同步：Linear 是一个仅支持 MCP (MCP-only) 的平台。同步操作通过您的 AI Agent 中的 Linear MCP 服务 执行。不需要 CLI REST API 适配器或个人访问令牌。

首次 MCP 设置 — 在您的 AI Agent 中配置 Linear MCP 服务：

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.linear.app/mcp"]
    }
  }
}

然后运行以下命令一次以完成授权许可：

npx -y mcp-remote https://mcp.linear.app/mcp

重启您的 Agent，然后使用 /issuer-sync 将任务推送到 Linear。

注意：Linear 不支持 issuer push CLI 命令。请在您的 AI Agent 内使用 /issuer-sync 代替。

支持的 Agent

| Agent | 技能路径 | 说明 | |-------|-------------|-------| | Claude Code | ~/.claude/skills/ | 主要目标，agentskills.io 发起者 | | Cursor | ~/.claude/skills/ | 使用 Claude 标准（Nightly 频道） | | VS Code Copilot | ~/.github/skills/ 或 ~/.copilot/skills/ | 多路径支持 | | Qoder / OpenCode | ~/.qoder/skills/ | 自定义路径 |

使用特定 Agent 快速开始

# Claude Code
issuer init -y --platform github --owner my-org --repo my-repo --agent claude
issuer skill install --target ~/.claude/skills

# Cursor
issuer init -y --platform github --owner my-org --repo my-repo --agent cursor
issuer skill install --target ~/.claude/skills

# VS Code Copilot
issuer init -y --platform github --owner my-org --repo my-repo --agent copilot
issuer skill install --target ~/.github/skills

# Qoder / OpenCode
issuer init -y --platform github --owner my-org --repo my-repo --agent qoder
issuer skill install --target ~/.qoder/skills

自动检测（默认）

如果未指定 --agent，issuer skill install 会自动检测现有的技能目录：

issuer init -y --platform github --owner my-org --repo my-repo
issuer skill install  # 检测 ~/.claude/skills, ~/.copilot/skills 等

同步通道

issuer-sync 对每个平台使用单一通道（绝不混合）：

| 平台 | MCP 可用性 | CLI 适配器 | 默认选择 | |---|---|---|---| | GitHub | 4/4（创建、更新、搜索、读取） | ✓ 完整 4/4 | MCP 可用时用 MCP，否则用 CLI | | GitLab | 4/4（创建、更新、搜索、读取） | ✓ 完整 4/4 | MCP 可用时用 MCP，否则用 CLI | | 云效 | 4/4（创建、更新、搜索、读取） | ✓ 完整 4/4（通过 OpenAPI） | MCP 可用时用 MCP，否则用 CLI | | PingCode | —（MCP 开发中） | ✓ 完整 4/4（通过 REST API） | CLI 适配器 | | Jira | 通过 Atlassian Rovo MCP 达到 4/4 | — (仅 MCP) | 仅 MCP 通道 |

通道选择逻辑：

1. MCP 优先 — 若 MCP 已配置且满足最低要求（create + read），使用 MCP 通道
2. CLI 适配器 — 若 MCP 不可用但平台有内置 CLI 适配器，使用 CLI 通道
3. 提示用户 — 若两者都不可用，引导用户安装 MCP 服务器或等待适配器支持

CLI 通道使用平台 SDK / OpenAPI，令牌从以下位置解析（按顺序）：

1. ISSUER_<PLATFORM>_TOKEN
2. <PLATFORM>_TOKEN
3. ~/.issuer/credentials.yml

已测试的平台

| 平台 | MCP 通道 | CLI (API) 通道 | 说明 | |---|---|---|---| | GitHub | ✓ 所有测试通过 | ✓ 所有测试通过 | 任一通道均完整 5/5 | | GitLab | ✓ 测试通过 | ✓ 测试通过 | 任一通道均完整 5/5 | | 云效 (Yunxiao) | ✓ 测试通过 | ✓ 所有测试通过 | 任一通道均完整 5/5 | | PingCode | —（开发中） | ✓ 所有测试通过 | CLI 适配器提供完整功能 | | Jira | ✓ 通过 Atlassian Rovo MCP | — (仅 MCP) | 在 AI Agent 中使用 /issuer-sync 进行同步 | | Linear | ✓ 通过 官方 Linear MCP 服务 | — (仅 MCP) | 官方远程 MCP 支持 OAuth 或 API Key 认证 |

两个通道对各支持的平台都处于生产就绪状态。

添加新平台（MCP 优先，零代码集成）

任何具有 MCP 服务器的平台都可以支持 — 不需要 REST API 适配器开发。

选项 1：交互式初始化（推荐）

issuer init
# 从平台列表中选择 "Other (MCP)"
# 提供工作空间/项目 ID

Issuer 自动：

• 探测 MCP 服务器功能
• 创建通用拆解模板
• 配置令牌解析（ISSUER_<PLATFORM>_TOKEN）

选项 2：手动设置

1. 在您的 Agent 中配置 MCP 服务器（Claude Code、Cursor、Qoder 等）
2. 运行 issuer init — issuer 探测 MCP 工具并将功能写入 .issuer/config.yml
3. 使用 issuer-sync — 技能直接调用 MCP 工具

如果 MCP 工具不满足最低要求，issuer 会提示您提供选项：

• 修复 MCP 服务器配置
• 使用自定义拆解模板进行任务生成
• 开发自定义 REST 适配器（参见 适配器开发）

MCP 检测工作原理

Issuer 使用启发式功能检测，通过关键字匹配：

• create + issue/workitem/task → 创建功能
• get/read + issue/workitem/task → 读取功能
• 相同逻辑用于 update、search、comment

最低要求：MCP 服务器必须至少公开 create 和 read 工具。

命令

| 命令 | 说明 | |---|---| | issuer init | 创建 .issuer/config.yml 和 .issuer/tasks/ | | issuer status | 按 draft / ready / synced 统计本地任务 | | issuer push | 推送所有 status: ready 任务；标记为 synced | | issuer list-remote | 列出配置的远程问题 | | issuer skill install | 将捆绑的技能复制到您的 Agent 技能目录 |

项目布局

.issuer/
  config.yml           # platform + owner + repo + default labels + mcp_capabilities + dedup
  credentials.yml      # 平台令牌（可选，推荐使用环境变量）
  tasks/                # 每个文件一个工作项
    2026-05-06-add-login.md
  cache.json            # 缓存的远程问题（用于去重检测）

可选：.issuer/briefs/ 目录在使用 issuer-refine 时存储精炼的 PRD 风格简报。

每个任务文件都是 YAML frontmatter + Markdown 正文。完整架构和模式请参见 docs/plans/2026-05-06-issuer-v2-design.md。

状态

MVP。支持 GitHub、GitLab、云效 (Yunxiao)、PingCode、Jira。

许可证

MIT。