项目管理API集成

通过项目管理工具的 GraphQL API 操作工作项全生命周期,从创建到状态推进,覆盖项目、周期、标签、评论与关联管理。

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux

依赖项

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

• 分类: MD+EXEC（）

API Key配置方式:

export API_KEY="your_api_key_here"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统。

核心能力

1. 工作项管理

• createIssue 创建工作项:含 title、description、teamId、priority
• updateIssue 更新工作项:状态、指派、估算、标签
• archiveIssue 归档工作项,保留历史但不显示在默认视图
• 工作项字段:title、description、priority、estimate、assignee、labels、state、project、cycle
• 优先级数值:0=紧急、1=高、2=中、3=低、4=无(对应 priorityUrgent 到 priorityNone)

输入: 用户提供工作项管理所需的指令和必要参数。 处理: 按照skill规范执行工作项管理操作,遵循单一意图原则。

2. 项目管理

• createProject 创建项目:含 name、description、teamIds
• updateProject 更新项目状态:planned、started、paused、completed、canceled
• projectIssues 查询项目下所有工作项
• 项目作为跨周期的工作容器,工作项可关联到项目

输入: 用户提供项目管理所需的指令和必要参数。 处理: 按照skill规范执行项目管理操作,遵循单一意图原则。

3. 团队管理

• teams 查询所有团队:含 id、name、key
• team 查询单个团队详情:含 workflow、states、labels
• 工作项必须归属于一个团队,teamId 是创建工作项的必填字段
• 团队 key 作为工作项标识前缀(如 ENG-123)

输入: 用户提供团队管理所需的指令和必要参数。 处理: 按照skill规范执行团队管理操作,遵循单一意图原则。

4. 周期管理

• createCycle 创建周期:含 name、startsAt、endsAt、teamId
• 标准周期14天,可自定义
• cycleIssues 查询周期内工作项
• 周期状态:active、upcoming、past,过去周期不可添加工作项
• updateIssue 的 cycleId 字段将工作项加入周期

输入: 用户提供周期管理所需的指令和必要参数。 处理: 按照skill规范执行周期管理操作,遵循单一意图原则。

5. 标签管理

• createLabel 创建标签:含 name、color、teamId
• updateIssue 的 labelIds 字段为工作项添加标签
• 标签用于分类筛选:bug、feature、tech-debt、customer-request
• 标签颜色用十六进制(如 #E5484D 表示红色)

处理: 按照skill规范执行标签管理操作,遵循单一意图原则。

6. 评论管理

• createComment 创建评论:含 body、issueId
• updateComment 编辑评论,deleteComment 删除评论
• 评论支持 Markdown 格式
• issueComments 查询工作项所有评论

输入: 用户提供评论管理所需的指令和必要参数。 处理: 按照skill规范执行评论管理操作,遵循单一意图原则。

7. 工作项关联

• issueRelation 建立关联:type=blocks、is blocked by、relates to、duplicate
• 关联方向有向:blocks 表示 A 阻塞 B
• issueRelations 查询工作项的所有关联

输入: 用户提供工作项关联所需的指令和必要参数。 处理: 按照skill规范执行工作项关联操作,遵循单一意图原则。 输出: 返回工作项关联的执行结果,包含操作状态和输出数据。

8. 工作流状态

• teamWorkflow 查询团队工作流:含 states 与 transitions
• 默认状态:Backlog、Triage、Todo、In Progress、In Review、Done、Canceled
• updateIssue 的 stateId 字段转换状态
• 状态类型:backlog、unstarted、started、completed、canceled

输入: 用户提供工作流状态所需的指令和必要参数。 输出: 返回工作流状态的执行结果,包含操作状态和输出数据。

9. 自定义视图

• createView 创建视图:含 name、query、filters
• 视图查询语法:status = "In Progress" AND priority = 1
• views 查询所有视图,viewIssues 获取视图内工作项

输入: 用户提供自定义视图所需的指令和必要参数。 处理: 按照skill规范执行自定义视图操作,遵循单一意图原则。

10. GraphQL查询构造

• 查询用 query 关键字,变更用 mutation
• 字段选择:只查询需要的字段,减少响应体积
• 分页:用 first、after 参数,默认 first 50
• 变量:用 $variable 参数化,避免字符串拼接

处理: 按照skill规范执行GraphQL查询构造操作,遵循单一意图原则。 输出: 返回GraphQL查询构造的执行结果,包含操作状态和输出数据。

能力覆盖范围

本skill还覆盖以下能力场景: 操作工作项、标签与评论、覆盖创建查询转换、全流程、通过项目管理工具、API、操作工作项全生命、CRUD、评论与关联、工作流状态转换与、适用于独立开发者、企业团队、和自动化工作流场。这些能力在上述核心功能中均有对应处理逻辑。

源能力映射

本skill覆盖源skill的以下能力点:

输入: 用户提供源能力映射所需的指令和必要参数。 处理: 按照skill规范执行源能力映射操作,遵循单一意图原则。 输出: 返回源能力映射的执行结果,包含操作状态和输出数据。

领域术语

本skill涉及以下领域术语: before, list, oauth, permissions, 系统连接时使用, post, 不适用于逆向工程, uuids, authorization, getting, 接口对接, verify, content, homebrew, correct

处理: 按照skill规范执行领域术语操作,遵循单一意图原则。 输出: 返回领域术语的执行结果,包含操作状态和输出数据。

适用场景

不适用于:项目管理工具配置(工作流设计、团队设置)、SSO配置、账单管理。

使用流程

1. 确认 API Key 配置,获取团队 ID 与工作流状态 ID
2. 用 createIssue 创建工作项,填 title、teamId、priority
3. 用 updateIssue 关联项目、周期、标签
4. 用 createCycle 规划周期,将工作项加入
5. 用 GraphQL query 配合筛选跟踪进度
6. 用 updateIssue 的 stateId 推进工作流状态

命令参数说明

• -uuid-in-progress: 命令参数,用于指定操作选项
• -W30: 命令参数,用于指定操作选项
• -uuid-feature: 命令参数,用于指定操作选项
• -uuid-789: 命令参数,用于指定操作选项
• -uuid-456: 命令参数,用于指定操作选项

结果处理: 执行完成后,查看输出结果确认操作状态。成功时输出包含处理摘要和结果数据;失败时根据错误信息排查问题,参考错误处理章节获取恢复步骤。

命令参数说明

• -W30: 命令参数,用于指定操作选项

命令参数说明

• -W30: 命令参数,用于指定操作选项

命令参数说明

• -W30: 命令参数,用于指定操作选项

命令参数说明

• -W30: 命令参数,用于指定操作选项

命令参数说明

• -W30: 命令参数,用于指定操作选项

命令参数说明

• -W30: 命令参数,用于指定操作选项

命令参数说明

• -W30: 命令参数,用于指定操作选项

命令参数说明

• -W30: 命令参数,用于指定操作选项

示例

示例1:创建工作项(GraphQL mutation)

mutation {
  issueCreate(input: {
    title: "实现用户登录接口"
    description: "支持邮箱+密码登录,返回JWT"
    teamId: "team-uuid-123"
    priority: 1
    estimate: 5
    labelIds: ["label-uuid-feature"]
  }) {
    success
    issue {
      id
      identifier
      title
      state { name }
    }
  }
}
// 返回: {"success": true, "issue": {"id": "issue-uuid-456", "identifier": "ENG-101", "title": "实现用户登录接口", "state": {"name": "Triage"}}}

示例2:GraphQL查询工作项

query {
  team(id: "team-uuid-123") {
    issues(first: 50, filter: {
      state: { type: { eq: "started" } }
      priority: { lte: 1 }
    }) {
      nodes {
        identifier
        title
        priority
        estimate
        assignee { name }
        state { name }
      }
    }
  }
}

示例3:周期规划

mutation {
  cycleCreate(input: {
    name: "Cycle 2026-W30"
    startsAt: "2026-07-21"
    endsAt: "2026-08-04"
    teamId: "team-uuid-123"
  }) {
    success
    cycle { id number }
  }
}
// 返回: {"success": true, "cycle": {"id": "cycle-uuid-789", "number": 30}}

// 将工作项加入周期
mutation {
  issueUpdate(input: {
    id: "issue-uuid-456"
    cycleId: "cycle-uuid-789"
  }) { success }
}

示例4:状态转换

mutation {
  issueUpdate(input: {
    id: "issue-uuid-456"
    stateId: "state-uuid-in-progress"
  }) {
    success
    issue { state { name type } }
  }
}
// 返回: {"success": true, "issue": {"state": {"name": "In Progress", "type": "started"}}}

错误处理

常见问题

Q1: 优先级数值 0-4 如何映射?

A: 0=priorityUrgent(紧急)、1=priorityHigh(高)、2=priorityMedium(中)、3=priorityLow(低)、4=priorityNone(无)。创建工作项时传整数,查询时返回对应枚举标签。

Q2: GraphQL 查询默认返回多少条?

A: 默认 first: 50。需要更多时显式传 first: 100(上限250),并用 after 游标分页:issues(first: 50, after: "cursor-xyz")。

Q3: estimate 估算值用哪些数字?

A: 与故事点一致,用斐波那契数列:1、2、3、5、8、13。也可配置为任意整数,但建议团队统一数列便于速率对比。

Q4: updateIssue 的 stateId 与 state name 有何区别?

A: stateId 是状态的唯一标识(如 state-uuid-123),state name 是显示名(如 "In Progress")。updateIssue 必须用 stateId,不能用 name。用 teamWorkflow 查询获取所有 stateId。

Q5: issueRelation 的 blocks 与 is blocked by 有何区别?

A: 方向相反。A blocks B 表示 A 阻塞 B(B 等 A 完成);A is blocked by B 表示 A 被 B 阻塞(A 等 B 完成)。建立关联时需明确方向,否则依赖图会反,且不可形成循环。

Q6: 周期14天如何调整?

A: createCycle 时指定 startsAt 与 endsAt,可设为7天或30天。建议团队统一周期长度,避免不同周期影响速率(burndown)对比。过去周期不可修改,只能创建新周期。

已知限制

• 需要项目管理工具的 API Key 与团队访问权限
• GraphQL 查询受 first 上限(250)限制,大结果集需分页
• 工作流状态 ID 因团队而异,不可硬编码
• 过去周期不可添加工作项,只能移到当前或未来周期
• 不覆盖工作流设计、SSO配置与账单管理