人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载导读GitHub 本身没有为ghCLI 提供原生的milestone子命令因此对里程碑Milestone的完整生命周期管理必须借助 REST API 或第三方库来实现。本文基于仓库 milestones.md 文档系统讲解在 AI Agent 与自动化脚本场景下管理 GitHub Milestones 的三种成熟模式gh apiREST 快速操作、PyGithubPython 多步脚本、octokit/restClaude Code Hook / JavaScript并深入分析仓库内置的github_project_setup.py自动化脚本中里程碑相关的完整实现与测试验证。读完本文你将掌握从创建、更新、关闭里程碑到批量把 Issue 分配进里程碑、再批量推进状态的一整套可落地命令与代码。一、三种工具模式的选择策略gh没有原生的milestone子命令但这并不意味着必须直接手工拼接 HTTP 请求。milestones.md 给出了一个清晰的选择矩阵适用于不同场景使用场景推荐工具一次性快速操作gh api repos/{owner}/{repo}/milestonesREST 端点脚本化 / 多步骤操作PyGithub—repo.create_milestone()Claude Code Hookoctokit/rest选择的原则很明确临时、快速的操作用gh api需要在脚本中串联多步骤流程时用编程库且不要通过 shell 去调用gh命令这一点在 issue-stories.md 和 labels.md 中同样强调——脚本化场景统一使用原生库避免 shell 转义与可观测性问题。代理环境提示当前仓库的 git remote 可能指向本地代理而非github.com此时所有gh命令都必须显式传-R owner/repo或--repo否则会报failed to determine base repo。该规则适用于pr、issue、api、release、project等全部子命令详见 gh SKILL 文档。文档示例中的Jamie-BitFlight/claude_skills请替换为你实际操作的仓库名。二、gh CLIREST快速命令全集2.1 列出里程碑List Milestonesgh api访问repos/{owner}/{repo}/milestones端点即可列出全部里程碑配合--jq可以输出为便于阅读的 TSV 表格gh api repos/Jamie-BitFlight/claude_skills/milestones \ --jq .[] | [.number, .title, .state, .open_issues, .due_on] | tsv输出各列含义number里程碑编号后续操作的核心标识、title标题、stateopen/closed、open_issues仍处于打开状态的 Issue 数、due_on截止时间ISO 8601 格式或空。2.2 创建里程碑Create a Milestone使用-X POST创建-f以字符串形式提交字段gh api repos/Jamie-BitFlight/claude_skills/milestones \ -X POST \ -f titlev1.0 — Skills Foundation \ -f descriptionCore skills for the claude_skills plugin marketplace \ -f due_on2026-03-31T00:00:00Z \ -f stateopen创建成功后返回的 JSON 中包含number字段——务必保存该编号后续给 Issue 分配里程碑时需要使用它。due_on必须使用 ISO 8601 UTC 时间格式如2026-03-31T00:00:00Z而非YYYY-MM-DD。2.3 更新里程碑Update a Milestone-X PATCH只传需要修改的字段即可例如仅推迟截止日期gh api repos/Jamie-BitFlight/claude_skills/milestones/1 \ -X PATCH -f due_on2026-04-15T00:00:00Z2.4 给 Issue 分配 / 移除里程碑这里有一个关键细节milestone 字段是整数类型必须使用-F强制按原值发送不做字符串处理而不是-f# 分配里程碑-F 将 1 作为整数发送milestone 字段必需 gh api repos/Jamie-BitFlight/claude_skills/issues/42 \ -X PATCH -F milestone1 # 移除里程碑 gh api repos/Jamie-BitFlight/claude_skills/issues/42 \ -X PATCH -F milestonenull如果误用-f milestone1GitHub API 会因类型不匹配而报错——这是最常见的踩坑点。2.5 列出某个里程碑下的全部 Issuegh issue list支持按里程碑名过滤gh issue list -R Jamie-BitFlight/claude_skills \ --milestone v1.0 — Skills Foundation \ --json number,title,state,labels在代理环境下务必保留-R参数以显式指定仓库。三、PyGithub — 脚本化操作Python对于 Python 脚本应使用PyGithub原生库而不是在脚本里调用gh。milestones.md 给出的完整可运行脚本如下脚本内嵌uv依赖声明可直接通过uv run执行#!/usr/bin/env -S uv run --quiet --script # /// script # requires-python 3.11 # dependencies [PyGithub2.1.1] # /// from __future__ import annotations import os from datetime import datetime, timezone from github import Auth, Github gh Github(authAuth.Token(os.environ[GITHUB_TOKEN])) repo gh.get_repo(Jamie-BitFlight/claude_skills) # Create milestone milestone repo.create_milestone( titlev1.0 — Skills Foundation, descriptionCore skills for the claude_skills plugin marketplace, due_ondatetime(2026, 3, 31, tzinfotimezone.utc), ) # List milestones for m in repo.get_milestones(stateall): print(f#{m.number} {m.title}) # Assign milestone to issue repo.get_issue(42).edit(milestonerepo.get_milestone(1)) # Close milestone m repo.get_milestone(1) m.edit(titlem.title, stateclosed)要点说明认证统一走GITHUB_TOKEN环境变量通过Auth.Token(...)构造不推荐直接传 token 字符串的旧式写法。create_milestone的due_on参数需要的是datetime对象且建议带tzinfotimezone.utc。get_milestones(stateall)会同时返回已关闭的里程碑get_milestone(number)按编号精确获取单个对象。issue.edit(milestone...)传入Milestone对象本身即可完成分配传入None可移除里程碑。四、octokit/rest — Claude Code HooksJavaScript在 Claude Code 的.cjshook 文件中使用octokit/rest同样不要用child_process去调ghconst { Octokit } require(octokit/rest); const octokit new Octokit({ auth: process.env.GITHUB_TOKEN }); // Create milestone const { data: milestone } await octokit.rest.issues.createMilestone({ owner: Jamie-BitFlight, repo: claude_skills, title: v1.0 — Skills Foundation, due_on: 2026-03-31T00:00:00Z, }); // Assign milestone to issue await octokit.rest.issues.update({ owner: Jamie-BitFlight, repo: claude_skills, issue_number: 42, milestone: milestone.number, });注意createMilestone返回的milestone.number要保存下来供后续issues.update的milestone字段使用。这种方式尤其适合在 Agent 的 hook 生命周期如PostToolUse、Stop等事件中自动完成里程碑维护。五、仓库内置自动化脚本github_project_setup.py在 github-workflows 技能目录 下仓库提供了完整的里程碑自动化实现github_project_setup.py。该脚本基于typerPyGithub通过子命令milestone暴露了四个操作list、create、start、close。5.1 命令速查uv run .claude/skills/gh/scripts/github_project_setup.py milestone list uv run .claude/skills/gh/scripts/github_project_setup.py milestone create \ --title v1.0 — Skills Foundation --due 2026-03-31 uv run .claude/skills/gh/scripts/github_project_setup.py milestone start \ --number 3 uv run .claude/skills/gh/scripts/github_project_setup.py milestone start \ --number 3 --dry-run实际执行时按仓库当前路径使用src/resources/skills/github-workflows/references/gh/scripts/github_project_setup.py脚本头部的uv指令会解析typer0.21.0与PyGithub2.1.1依赖。各子命令的完整参数子命令必填参数可选参数行为milestone list--repo OWNER/REPO—列出全部里程碑输出编号、状态、开放/关闭 Issue 数与截止日期milestone create--title TITLE--description、--due YYYY-MM-DD创建里程碑打印编号与 URLmilestone start--number N--dry-run、--project-number、--owner将该里程碑下所有开放 Issue 从status:needs-grooming批量推进为status:in-progress指定 project 时同步更新 Projects V2 的 Status 字段milestone close--number N--dry-run、--project-number、--owner将开放 Issue 批量标记status:done并关闭里程碑同步更新 Projects V2 Status5.2 源码级解析状态机如何与里程碑联动脚本内部定义了完整的标签状态机LABELS常量共 16 个标签里程碑操作围绕其中的状态标签展开milestone start的核心调用链milestone_start()→_get_open_milestone()校验里程碑存在且未关闭→repository.get_issues(milestone..., stateopen)→_transition_issues()逐条执行issue.edit(labels...)将status:needs-grooming替换为status:in-progress。注意_transition_issues只移除status:needs-grooming保留所有非状态标签如priority:p1、type:feature。milestone close调用_transition_to_done()移除status:in-progress/status:needs-grooming并追加status:done随后调用milestone.edit(titlemilestone.title, stateclosed)关闭里程碑。_ensure_label()实现标签自愈若status:in-progress或status:done标签不存在会自动创建避免流程中断。若指定了--project-number脚本通过_bulk_update_project_status()用 gh CLI 执行 GraphQL mutationaddProjectV2ItemById、updateProjectV2ItemFieldValue同步 Projects V2 看板的 Status 字段——这正是该技能中 PyGithub 负责 REST、gh CLI 负责 Projects V2 GraphQL 的分工策略。--dry-run模式只打印将要执行的操作含 Projects V2 的状态变更预览不产生任何写操作适合在正式批量操作前做安全演练。5.3 健壮性设计get_github()在缺少GITHUB_TOKEN时直接打印错误并以退出码 1 结束。_get_open_milestone()在编号不存在时列出当前开放里程碑辅助排查对已关闭里程碑则明确报错拒绝操作。milestone start对没有任何开放 Issue的里程碑会打印警告并安全退出退出码 0提示先用/group-items-to-milestone添加条目。单条 Issue 操作失败如 403会被捕获记录其余 Issue 继续处理最终以非零退出码反映部分失败避免一次异常中断整个批次。5.4 测试验证test_github_project_setup.py 使用typer.testing.CliRunnerunittest.mock无网络验证了完整工作流六步labels → milestone list → milestone create → issue create → milestone start → issue list。与里程碑直接相关的关键断言包括TestMilestoneList列表包含开放/关闭两种状态空仓库输出No milestones.TestMilestoneCreate--due 2026-03-31被正确解析为带时区的datetime传入create_milestone--description会透传给 APITestMilestoneStarthappy path 验证status:needs-grooming被移除、status:in-progress被添加已处于 in-progress 的 Issue 会被跳过不重复编辑标签缺失时自动创建单个失败不影响其他 Issue 且退出码为 1非状态标签如priority:p1、type:feature得到完整保留。这些测试把文档描述的每一步流程都固化成了可回归验证的契约是理解该工作流行为的可靠参照。六、里程碑命名规范milestones.md 给出了与版本节奏、质量门禁、季度梳理相匹配的命名范式可直接复用v1.0 — Skills Foundation # initial stable release v1.1 — Quality Gates # linting/validation improvements v2.0 — GitHub Integration # issues, projects, milestones support Backlog Grooming — 2026-Q1 # quarterly grooming milestone规律总结版本型里程碑用v{major}.{minor} — {主题描述}功能主题用一句话点明交付范围周期性整理类里程碑如每季度 Backlog 梳理用主题 — 时间窗。建议在仓库中统一维护该约定便于gh api与脚本按标题检索。七、与周边技能的配合关系里程碑不是孤立存在的它和本仓库 GitHub 工作流技能中的其他三个引用文档构成完整闭环issue-stories.md每个 Issue 作为一条用户故事其生命周期Open → status:needs-grooming → status:in-progress → 关闭与里程碑的状态推进一一对应gh issue create可直接用--milestone v1.0 — Skills Foundation在创建时分配里程碑labels.mdstatus:in-milestone、status:in-progress、status:done等状态标签是里程碑 start/close 批量转换的核心载体projects-v2.mdProjects V2 看板用于里程碑进度的可视化由脚本中的 GraphQL mutation 同步。典型组合拳用milestone create建号 →issue create --milestone N批量录入 →milestone start开工 →milestone close收尾并同步看板状态全程由 github_project_setup.py 完成无需手工执行任何 REST 调用。结语GitHub Milestones 虽然没有官方 CLI 子命令但通过gh api、PyGithub、octokit/rest三套工具可以覆盖从一次性查询到全自动状态机流转的全部场景。仓库内置的github_project_setup.py将这套方法论固化为可复用的命令行工具并以完整测试锁定行为契约——无论是手工执行还是由 AI Agent 驱动都能在代理环境、批量操作与失败恢复等真实约束下可靠运行。赞分享人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载相关推荐gsd-2 GitHub Labels 标签体系与自动化管理实战从 gh CLI 到 PyGithub 与 Octokit Hookgsd 2 GitHub Labels 标签体系与自动化管理实战从 gh CLI 到 PyGithub 与 Octokit Hook 导读 本文以 gsd 2人工智能AI Agent代码智能体Agent 编排CLIAI 应用离线翻译工具完整指南三步用上Argos Translate离线翻译工具完整指南三步用上Argos Translate 出差到了没信号的山区翻译软件全废了Argos Translate 是一款开源的 Python人工智能NLP本地部署Gemini CLI github-issue-creator 技能基于模板驱动与 gh CLI 的 GitHub Issue 自动化创建流程Gemini CLI github issue creator 技能基于模板驱动与 gh CLI 的 GitHub Issue 自动化创建流程 gemini人工智能AI Agent交互助手CLIMCP Clients上一篇告别正则噩梦JavaVerbalExpressions让复杂模式匹配像说话一样简单下一篇prima.cpp设备选择算法如何自动识别并优化异构设备集群创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考