Menu
AgentBay CLI 需求开发全流程规范(分支管理、推送、提交、PR),不含具体需求内容
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Basé sur la classification professionnelle SOC
| name | feature-development-workflow |
| description | AgentBay CLI 需求开发全流程规范(分支管理、推送、提交、PR),不含具体需求内容 |
规定 agentbay-cli 在接到任何新需求时的标准开发流程,覆盖从拉分支、本地开发、构建验证、提交、推送到提 PR 的全链路操作规范。
本 skill 不包含任何具体需求的代码实现细节,仅约束流程本身。
当用户提出以下诉求时触发:
本项目只保留两个远程,不使用 upstream(个人 fork):
| Remote | 地址 | 用途 |
|---|---|---|
origin | git@gitlab.alibaba-inc.com:InnoArchClub/agentbay-cli.git | 内网代码仓,归档/协作/CI |
aliyun | git@github.com:aliyun/agentbay-cli.git | 对客真实代码仓,合入主线的目标 |
验证命令:
git remote -v
# 必须只有 origin 和 aliyun,不允许出现 upstream
如出现多余 remote:
git remote remove <name>
为让每个需求都有"需求 → 设计 → 代码 → 提交 → PR → 发布"的完整追溯链,启动任何新需求前必须二选一建立变更档案,两条路径都是强制的,目的一致 — 在 Git 仓库内留下可审阅的档案:
| 路径 | 触发场景 | 产物位置 | 备注 |
|---|---|---|---|
| A. Qoder Quest Mode | 通过 ⌘ E 进入 Quest 模式,在 Design 阶段让 AI 生成 Spec,Review 后点 Download | .qoder/specs/<feature>.md(Qoder 客户端 Download 默认写盘位置,零配置) | 推荐用于复杂需求;Spec 可与 AI 协同编辑;文件默认 untracked,需 git add 入库 |
| B. 手动 CR 目录 | 未启用 Quest Mode / 轻量需求 / 已有外部设计稿需沉淀 | .qoder/changes/CR-<YYYY-MM-DD>-<feature-name>/ | 包含 spec.md / design.md / tasks.md / decisions.md / test-plan.md / rollback.md / trace.md 等 |
核心规则:
.qoder/specs/<feature>.md 由 Qoder 在点 Download 后自动落盘,必须 git add 纳入版本库,避免档案与代码脱节.qoder/changes/ 下建 CR 目录,命名严格遵守 CR-<YYYY-MM-DD>-<feature-name> 格式,与 feat 分支名强关联trace.md / 对应 Spec 中登记:feat 分支名、关键 commit SHA、推送目标 remote、PR 链接、合并 commit、release tag⚠️ 铁律:此 Phase 产出之前,不允许进入 Phase 1 拉分支。
选择一条路径建立档案:
路径 A · Quest Mode(推荐)
⌘ E 打开 Quest 面板New Task → 勾选相关文件作为 Context → 粘贴需求描述 → 回车(不要勾 Execute Directly,否则跳过 Design 阶段不会生成 Spec)Run Spec 进入执行Download → Qoder 客户端会自动写入 .qoder/specs/<feature>.md(文件名基于 Spec 标题 slug 生成,零配置)git add 纳入版本库路径 B · 手动 CR 目录
mkdir -p .qoder/changes/CR-$(date +%F)-<feature-name>.qoder/changes/TEMPLATE.md(若存在)建立:
spec.md:需求背景 / 目标 / 非目标 / 范围design.md:接口设计 / 流程图 / 状态机tasks.md:任务分解(建议映射到 todo_write 的 tasklist)decisions.md:关键决策(交互默认值 / 参数命名 / 分支策略 等)test-plan.md:单测 / 集成 / 回归rollback.md:回滚预案trace.md:后续持续更新的追溯链(分支 / commits / push / PR / release)⚠️ 重要:任何写代码动作前必须确定一条干净、起点正确的 feat 分支,禁止在 master 直接改动。
同步两个远程最新状态
git fetch origin
git fetch aliyun
判断是否可复用当前 feat 分支(避免每次都新切)
先读取当前仓库状态:
git branch --show-current # 当前分支名
git status --short # 工作区是否干净
git log --oneline aliyun/master..HEAD -1 # 是否领先 aliyun/master
git log --oneline HEAD..aliyun/master -1 # 是否落后 aliyun/master
可复用的充要条件(必须全部满足):
feat- 或 feat/ 开头,且不是 master / maingit status --short 输出为空,允许未入库的变更档案除外,但需在后续一起提交)aliyun/master(即 HEAD..aliyun/master 为空;若落后,需先 rebase 或用户确认处理策略)决策分发:
✅ 全部满足 → 主动询问用户:
"检测到当前在
feat/xxx分支,已与aliyun/master同步且工作区干净。是 直接复用当前分支 继续开发,还是 从aliyun/master新切一条 feat 分支?"
❌ 任一不满足 → 仍须先询问用户（⚠️ 不得自动新切）:
"当前分支为
<branch-name>，[简述不满足的条件，如：落后 aliyun/master / 工作区有未提交改动 / 分支名不以 feat- 开头]。请确认：是 在当前分支继续开发，还是 从aliyun/master新切一条 feat 分支？"
用户选择继续当前分支→ 跳过第 3 步，直接进入 Phase 2（由用户自行承担分支状态风险）。 用户选择新切分支→ 按第 3 步执行。
新切 feat 分支(默认路径)
基于 aliyun/master 创建(以 aliyun 主线为真源):
git checkout -b feat-<feature-name> aliyun/master
分支命名规范: feat-<短横线分隔的需求关键词>,如 feat-image-delete、feat-apikey-concurrency。
确认最终分支状态:
git log --oneline -1
git status
无论复用还是新切,后续 Phase 2-6 的所有动作都在这条 feat 分支上进行。
严格遵守 development.md 规则:
--name),不使用位置参数开发过程禁止任何自动 push 动作。
每次提交前必须本地全量验证:
go build -o agentbay .
go test ./... -count=1
两条命令全部通过后才能进入提交环节。go build -o agentbay . 必须生成项目根目录的可执行二进制，不能只用 go build ./... 替代。
⚠️ 铁律:在用户明确指示之前,不得执行
git add/git commit。
用户指示提交后:
先展示变更,供用户审阅:
git status
git diff --stat
使用 Conventional Commits 规范（确保 release-prep 可正确生成 CHANGELOG）:
git add -A
git commit -m "<type>(<scope>): <description>
- 具体改动点 1
- 具体改动点 2
- 具体改动点 3"
<type> 从以下中选: feat / fix / docs / refactor / perf / revert / test / style / chore / ci / build。
用户可感知变更优先使用会进入 CHANGELOG 的 feat / fix / docs / refactor / perf / revert；<scope> 优先使用 apikey、image、network、skills、docker、core、client。
不兼容变更必须使用 ! 或 footer BREAKING CHANGE:。
确认提交结果:
git log --oneline -3
更新变更档案:
.qoder/specs/<feature>.md 是否已加入本次 commit.qoder/changes/CR-xxx/trace.md⚠️ 铁律:在用户明确指示推送之前,不得执行任何
git push。
推送时机和目标由用户决定,只允许推送到 origin 和 aliyun,推送命令模板:
推送到 origin(内网归档):
git push origin feat-<feature-name>
推送到 aliyun(对客主线,PR 源分支):
git push aliyun feat-<feature-name>
两个远程同时推送(如用户要求):
git push origin feat-<feature-name>
git push aliyun feat-<feature-name>
禁止操作:
git push --force / git push -f 到任何远程(除非用户显式授权)master / main 主分支upstream--no-verify 跳过 hook推送完成后:
trace.md(路径 B)或 Spec 的"执行记录"章节(路径 A)当 feat 分支已推送到 aliyun 后,由用户在 GitHub 网页操作或通过 gh CLI 提 PR 到 aliyun/master,PR 模板要求:
PR 合并由用户(或指定 reviewer)审批,合并后的清理动作:
git checkout master
git fetch aliyun
git reset --hard aliyun/master
git branch -D feat-<feature-name> # 本地删除
git push origin --delete feat-<feature-name> # origin 删除
git push aliyun --delete feat-<feature-name> # aliyun 删除(可选,或由 PR 合并页勾选)
档案归档:
trace.md(路径 B)或 Quest Spec(路径 A)登记 PR 链接、合并 commit、对应的 release tag如果用户要求继续发版、准备 tag、生成 GitHub Release notes 或回灌历史 release body，立即加载 bilingual-changelog-release skill，按其 SOP 执行：
make release-prep VERSION=X.Y.Z
注意：日常 feature 分支开发完成后不要在本 workflow 中运行 git-cliff -o CHANGELOG.md 或 make changelog；CHANGELOG 版本段由发版阶段统一生成和翻译。
commit 和 push 都需要用户明确指示后才执行aliyun/master 拉出,确保起点是对客主线origin 和 aliyun,不引入额外 fork.qoder/specs/(Quest Mode Download 自动落盘)或 .qoder/changes/(手动 CR)下建立档案,档案随代码一并入库需求启动前:
git remote -v 只有 origin 和 aliyungit fetch aliyun.qoder/specs/<feature>.md Quest Spec 或 .qoder/changes/CR-xxx/ 目录)提交前:
go build -o agentbay . 通过并生成根目录二进制go test ./... -count=1 通过git status 无预期外的改动git add,与代码一同提交推送前:
feat- 开头,不是 mastertrace.md / Quest Spec 已更新本次推送意图| 陷阱 | 表现 | 规避 |
|---|---|---|
| 在 master 直接改 | git status 显示 HEAD 是 master 且有 diff | 开发前先 git checkout -b feat-xxx aliyun/master |
| 从 origin/master 起点 | feat 分支基点滞后于 aliyun 主线,PR 有冲突 | 明确从 aliyun/master 拉分支 |
| 盲目复用旧 feat 分支 | 复用了落后于 aliyun/master 或工作区有残留的分支,污染新需求 | Phase 1 步骤 2 按充要条件校验，任一不满足时先询问用户意愿，由用户决定是继续当前分支还是新切 |
| 未授权自动 push | 用户还没审查就已推送 | 推送动作必须等用户说"推送"/"push" |
| mock 漏改 CI 报错 | *mockClient does not implement agentbay.Client | 接口变更后立即 grep -r "type mock.*Client struct" 全量补齐 |
| 残留 upstream | git remote -v 仍有个人 fork | 执行 git remote remove upstream |
| 缺失变更档案 | 需求完成但仓库无 Spec / CR 目录,后续无法追溯 | 启动需求时按 Phase 0 强制二选一建立档案 |
| Quest 跳过 Design | 勾了 Execute Directly 导致 Spec 根本没生成 | New Task 时确认未勾 Execute Directly,点 Download 写盘到 .qoder/specs/ |
| 档案与代码脱节 | Spec 建好但没 git add,合并后档案丢失 | 提交前检查 git status 确保 Spec/CR 文件已进入暂存区 |
AgentBay CLI 双语 CHANGELOG 与 GitHub Release 发版 SOP。Use when preparing a release, updating bilingual CHANGELOG, translating release notes, creating tags, refreshing GitHub Release notes, or running make release-prep/backfill-release-notes.
将前端 API 能力封装成 agentbay-cli 命令的标准化流程
AgentBay CLI 命令文档同步流程（docs/、README、CHANGELOG readiness）
将当前本地分支推送到 aliyun 远程的同名分支（禁止推送到 master/main）
将当前本地分支推送到 origin 远程的同名分支（禁止推送到 master/main）