@fitlab-ai/agent-infra 0.3.2 → 0.4.1

package/templates/.agents/skills/create-pr/SKILL.zh-CN.md

@@ -1,201 +1,46 @@
 ---
 name: create-pr
-description: >
-  创建 Pull Request 到指定或自动推断的目标分支。
-  当用户要求创建 PR 时触发。可选参数：目标分支。
+description: "创建 Pull Request 到目标分支"
 ---
 
 # 创建 Pull Request
 
-创建 Pull Request。可选参数：目标分支。
+创建 Pull Request，并在与任务关联时立即补齐核心元数据。
 
 ## 执行流程
 
 ### 1. 确定目标分支
 
-- 如果用户提供了参数（例如 `main`、`develop`、`3.6.x`），使用其作为目标分支
-- 如果没有参数，自动检测：
-  ```bash
-  git branch --show-current
-  git log --oneline --decorate --first-parent -20
-  ```
-  **检测规则**：
-  - 当前在 main/trunk 分支 -> 目标是该分支
-  - 当前在 feature 分支 -> 从日志装饰中找到最近的父分支
-  - 无法确定 -> 询问用户
+如果用户显式提供参数就直接使用；否则根据 Git 历史和分支拓扑自动推断。
 
-### 2. 读取 PR 模板
+> 详细分支判断规则见 `reference/branch-strategy.md`。自动推断 base 分支前，先读取 `reference/branch-strategy.md`。
 
-从仓库中读取 `.github/PULL_REQUEST_TEMPLATE.md`。
+### 2. 准备 PR 正文
 
-如果模板不存在，使用标准格式。
+读取 `.github/PULL_REQUEST_TEMPLATE.md`（如存在），参考最近合并的 PR 风格，并收集 `<target-branch>` 到 `HEAD` 的全部提交。
 
-### 3. 参考最近合并的 PR
+> 模板处理、HEREDOC 正文生成和 `Generated with AI assistance` 要求见 `reference/pr-body-template.md`。编写正文前先读取 `reference/pr-body-template.md`。
 
-```bash
-gh pr list --limit 3 --state merged --json number,title,body
-```
-
-以此作为风格和格式参考。
-
-### 4. 分析当前分支变更
-
-```bash
-git status
-git log <target-branch>..HEAD --oneline
-git diff <target-branch>...HEAD --stat
-git diff <target-branch>...HEAD
-```
-
-理解将包含在此 PR 中的所有提交和变更。查看**所有**提交，而不仅仅是最新的。
+### 3. 检查远程分支状态
 
-### 5. 检查远程分支状态
+确认当前分支是否已有 upstream；必要时执行 `git push -u origin <current-branch>`。
 
-```bash
-git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null
-```
+### 4. 创建 PR
 
-### 6. 如未推送则先推送
-
-```bash
-git push -u origin <current-branch>
-```
-
-### 7. 创建 PR
-
-- 如果存在关联的活跃任务，从 task.md 提取 `issue_number`
-- 如果 `issue_number` 存在，查询 Issue 信息（容错，失败时跳过）：
-  ```bash
-  gh issue view {issue-number} --json number,title --jq '.number' 2>/dev/null
-  ```
-- 遵循 `.github/PULL_REQUEST_TEMPLATE.md` 格式填写所有部分
-- 参考最近合并的 PR 的风格
-- 使用 HEREDOC 格式传递 body
-- 如果 `issue_number` 存在：
-  - 将模板中的 `{$IssueNumber}` 替换为实际 Issue 编号
-  - 在 `Related Issue` 部分使用 `Closes #{issue_number}`
-- 如果 `issue_number` 不存在，保持原有行为
-- PR 必须以 `Generated with AI assistance` 结尾
-
-```bash
-gh pr create --base <target-branch> --title "<title>" --assignee @me --body "$(cat <<'EOF'
-<按模板填写的完整 PR 描述>
-
-Generated with AI assistance
-EOF
-)"
-```
+使用 `gh pr create --base <target-branch> --title "<title>" --assignee @me --body ...` 创建 PR。
 
-### 8. 同步 PR 元数据（如果与任务相关）
+如果关联任务提供了 `issue_number`，必须在 PR 正文中保留 `Closes #{issue-number}`。
 
-如果存在关联的活跃任务，在创建 PR 后立即同步以下元数据：
+### 5. 同步 PR 元数据
 
-**a) 检查 label 体系是否已初始化**
+对任务关联 PR，立即同步这些核心元数据：
+- 执行 `gh label list --search "type:" --limit 1 --json name --jq 'length'`
+- 使用 `gh pr edit {pr-number} --add-label "{type-label}"` 添加 type label
+- 使用 `gh pr edit {pr-number} --add-label "in: {module}"` 添加相关 `in:` labels
+- 使用 `gh pr edit {pr-number} --milestone "{milestone-title}"` 设置里程碑
+- 通过 `Closes #{issue-number}` 保持 Development 关联
 
-执行：
-
-```bash
-gh label list --search "type:" --limit 1 --json name --jq 'length'
-```
-
-- 返回 `0` -> 先执行 `init-labels` 技能，然后重新执行本步骤
-- 返回非 `0` -> 继续
-
-**b) 查询 Issue 元数据**
-
-如果 task.md 包含 `issue_number`，查询 Issue 的 Labels 和 Milestone（容错）：
-
-```bash
-gh issue view {issue-number} --json labels,milestone 2>/dev/null
-```
-
-如果查询失败（Issue 不存在、权限不足等），跳过 Issue 元数据继承，后续步骤仅使用 task.md 静态映射。
-
-记录查询结果供后续子步骤使用：
-- `{issue-labels}` — Issue 上的 Labels 列表
-- `{issue-milestone}` — Issue 上的 Milestone 标题（如有）
-
-**c) 同步 type label**
-
-根据 task.md 的 `type` 字段按下表映射：
-
-| task.md type | GitHub label |
-|---|---|
-| bug、bugfix | `type: bug` |
-| feature | `type: feature` |
-| enhancement | `type: enhancement` |
-| refactor、refactoring | `type: enhancement` |
-| documentation | `type: documentation` |
-| dependency-upgrade | `type: dependency-upgrade` |
-| task | `type: task` |
-| 其他 | 跳过 |
-
-如果 task.md 的 `type` 可以映射到标准 type label，执行：
-
-```bash
-gh pr edit {pr-number} --add-label "{type-label}"
-```
-
-**d) 继承 Issue Labels**
-
-如果 `{issue-labels}` 非空，筛选出不以 `type:` 或 `status:` 开头的 labels，对每个 label 执行（容错，label 不存在时跳过）：
-
-```bash
-gh pr edit {pr-number} --add-label "{label-name}"
-```
-
-只添加，不移除 PR 上现有的 labels。
-
-**e) 同步 in: label**
-
-从实现报告或分析报告提取受影响模块，确认对应 label 存在后执行：
-
-```bash
-gh pr edit {pr-number} --add-label "in: {module}"
-```
-
-只添加，不移除现有的 `in:` labels。
-
-**f) 同步 Milestone**
-
-基于 `sync-pr` 的里程碑推断策略，并扩展 Issue Milestone 优先级：
-- 先检查 PR 是否已有 milestone
-- 再检查 task.md 是否显式指定 `milestone`
-- 再检查 Issue 是否已有 milestone（使用 `{issue-milestone}`）
-- 否则基于当前分支、版本分支或最新 tag 推断
-- 最终回退到 `General Backlog`
-
-找到目标后执行：
-
-```bash
-gh pr edit {pr-number} --milestone "{milestone-title}"
-```
-
-**g) 同步 Development 关联**
-
-如果 task.md 包含 `issue_number`，读取 PR body：
-
-```bash
-gh pr view {pr-number} --json body --jq '.body // ""'
-```
-
-如果 body 不包含以下任一关键词：
-- `Closes #{issue-number}`
-- `Fixes #{issue-number}`
-- `Resolves #{issue-number}`
-
-则在末尾追加：
-
-```bash
-gh pr edit {pr-number} --body "$(cat <<'EOF'
-{existing-body}
-
-Closes #{issue-number}
-EOF
-)"
-```
-
-### 9. 更新任务状态（如果与任务相关）
+### 6. 更新任务状态
 
 获取当前时间：
 
@@ -203,58 +48,23 @@ EOF
 date "+%Y-%m-%d %H:%M:%S"
 ```
 
-如果有关联的活跃任务，更新 `.agent-workspace/active/{task-id}/task.md`：
-- `pr_number`：{pr-number}
-- `updated_at`：{当前时间}
-- **追加**到 `## Activity Log`（不要覆盖之前的记录）：
-  ```
-  - {yyyy-MM-dd HH:mm:ss} — **PR Created** by {agent} — PR #{pr-number} created
-  ```
-
-### 10. 输出结果
-
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
+如果当前 PR 关联任务，更新 task.md 的 `pr_number`、`updated_at`，并追加 PR Created 的 Activity Log。
 
-> **⚠️ 下一步判断 — 你必须先判断创建 PR 后的真实下一步，再展示下面的命令：**
->
-> - 如果 `task.md` 有有效 `issue_number`，且需要把 PR 状态或审查摘要同步回任务上下文，优先提示「发布审查摘要（可选）」
-> - 如果所有工作流步骤已经完成，或创建 PR 后下一步就是归档任务，提示「完成任务」
-> - 如果以上两者都适用，必须明确顺序：**先同步 PR 进度，再完成任务**
->
-> **禁止把「完成任务」写成唯一下一步，如果仍需要同步进度或补充 PR 上下文。**
+### 7. 告知用户
 
-```
-PR 已创建：{pr-url}
-
-元数据同步：
-- Labels：{type-label-result}, {in-label-result}
-- Milestone：{milestone-result}
-- Development：{development-result}
-
-下一步（如在任务工作流中）：
-- 发布审查摘要（可选；有关联任务或需要同步 PR 状态时建议先执行）：
-  - Claude Code / OpenCode：/sync-pr {task-id}
-  - Gemini CLI：/{{project}}:sync-pr {task-id}
-  - Codex CLI：$sync-pr {task-id}
-- 完成任务（所有工作流步骤完成后执行）：
-  - Claude Code / OpenCode：/complete-task {task-id}
-  - Gemini CLI：/{{project}}:complete-task {task-id}
-  - Codex CLI：$complete-task {task-id}
-```
+说明 PR URL、元数据同步结果，并按顺序给出两个后续动作：
+- 可选执行 `sync-pr {task-id}`，发布面向 reviewer 的上下文摘要
+- 当整个工作流真正完成后执行 `complete-task {task-id}`
 
 ## 注意事项
 
-1. **遵循 PR 模板**：填写模板中所有必要部分
-2. **参考风格**：匹配最近合并的 PR 的格式和风格
-3. **标题格式**：遵循 Conventional Commits 或项目规范
-4. **所有提交都重要**：分析分支中的**所有**提交，而不仅仅是最新的
-5. **自动同步元数据**：如果与任务相关，create-pr 必须在创建后立即补齐 labels、milestone 和 development 关联
+- 必须检查分支中的全部提交，而不是只看最后一个
+- `create-pr` 不能把 type label 映射委托给 `sync-pr`，必须在本技能内内联处理
+- 如果从 Issue 继承元数据失败，继续使用 task.md 和分支推断兜底
 
 ## 错误处理
 
-- 无提交可推送：提示 "No commits found between {target} and HEAD"
-- 推送被拒绝：建议先执行 `git pull --rebase`
-- PR 已存在：显示已有的 PR URL
-- Issue 不存在或无权限：跳过 Issue 元数据继承，记录 "Issue #{number} not accessible, skipping metadata inheritance"
-- Issue Label 不可用：跳过对应 label，记录 "Label '{name}' not found, skipping"
-- Issue Milestone 不可用：回退到分支推断策略
+- `{target}` 与 `HEAD` 之间没有可提交内容
+- 推送被拒绝：建议执行 `git pull --rebase`
+- 已存在 PR：直接输出当前 PR URL
+- 无法访问 Issue 元数据：跳过继承并继续

package/templates/.agents/skills/create-pr/reference/branch-strategy.md

@@ -0,0 +1,29 @@
+# Branch Strategy
+
+Read this file before inferring the base branch.
+
+## Determine Target Branch
+
+- If the user provides an argument such as `main`, `develop`, or `3.6.x`, use it directly.
+- If no argument is provided, inspect:
+
+```bash
+git branch --show-current
+git log --oneline --decorate --first-parent -20
+```
+
+Decision rules:
+- current branch is `main` or `trunk` -> use that branch
+- current branch is a feature branch -> infer the nearest parent branch from log decorations
+- cannot determine -> ask the user
+
+Feature-branch parent inference details:
+- inspect the nearest decorated ancestor in first-parent history
+- prefer `{major}.{minor}.x` release lines over `main` / `master` when the feature branch was cut from a release line
+- if both a release line and `main` seem plausible, choose the nearer ancestor in history
+- if no reliable parent can be inferred, stop and ask the user instead of guessing
+
+Next-step rule after PR creation:
+- if `issue_number` exists and reviewer-facing context still needs publishing, recommend `sync-pr {task-id}` first
+- if all workflow work is complete after PR creation, recommend `complete-task {task-id}` second
+- never present `complete-task` as the only next step when PR context still needs syncing

package/templates/.agents/skills/create-pr/reference/branch-strategy.zh-CN.md

@@ -0,0 +1,29 @@
+# 分支策略
+
+在推断 base branch 之前先读取本文件。
+
+## 确定目标分支
+
+- 如果用户显式提供了参数，例如 `main`、`develop` 或 `3.6.x`，直接使用它。
+- 如果没有提供参数，检查：
+
+```bash
+git branch --show-current
+git log --oneline --decorate --first-parent -20
+```
+
+判断规则：
+- 当前分支是 `main` 或 `trunk` -> 使用该分支
+- 当前分支是 feature branch -> 从 log decoration 推断最近的父分支
+- 无法可靠判断 -> 直接询问用户
+
+Feature branch 父分支推断细则：
+- 在 first-parent 历史中检查最近的已标记祖先
+- 如果该 feature branch 是从 release line 切出的，优先选择 `{major}.{minor}.x`，而不是 `main` / `master`
+- 如果 release line 和 `main` 看起来都合理，选择历史上更近的那个祖先
+- 如果无法可靠推断父分支，不要猜测，直接停止并询问用户
+
+创建 PR 后的下一步规则：
+- 如果存在 `issue_number`，且面向 reviewer 的上下文还未发布，优先推荐 `sync-pr {task-id}`
+- 如果 PR 创建后工作流已经真正结束，再把 `complete-task {task-id}` 作为第二步推荐
+- 当 PR 上下文仍需同步时，绝对不要把 `complete-task` 作为唯一下一步

package/templates/.agents/skills/create-pr/reference/pr-body-template.md

@@ -0,0 +1,86 @@
+# PR Body Template Rules
+
+Read this file before generating the PR title and body.
+
+## Read the PR Template
+
+Read `.github/PULL_REQUEST_TEMPLATE.md` from the repository. If it does not exist, use the standard format.
+
+## Review Recent Merged PRs for Reference
+
+```bash
+gh pr list --limit 3 --state merged --json number,title,body
+```
+
+Use the recent merged PRs as style and formatting references.
+
+## Analyze Current Branch Changes
+
+```bash
+git status
+git log <target-branch>..HEAD --oneline
+git diff <target-branch>...HEAD --stat
+git diff <target-branch>...HEAD
+```
+
+## Sync PR Metadata
+
+Before syncing labels, verify the standard label system:
+
+```bash
+gh label list --search "type:" --limit 1 --json name --jq 'length'
+```
+
+If the result is `0`, run `init-labels` before retrying metadata sync.
+
+Type label mapping:
+
+| task.md type | GitHub label |
+|---|---|
+| `bug`, `bugfix` | `type: bug` |
+| `feature` | `type: feature` |
+| `enhancement` | `type: enhancement` |
+| `refactor`, `refactoring` | `type: enhancement` |
+| `documentation` | `type: documentation` |
+| `dependency-upgrade` | `type: dependency-upgrade` |
+| `task` | `type: task` |
+| other values | skip |
+
+Metadata sync order:
+1. query Issue labels and milestone best-effort with `gh issue view {issue-number} --json labels,milestone`
+2. add the mapped type label with `gh pr edit {pr-number} --add-label "{type-label}"`
+3. inherit non-`type:` and non-`status:` Issue labels with repeated `gh pr edit ... --add-label`
+4. add relevant `in: {module}` labels without removing existing ones
+5. resolve milestone in order: PR -> task.md -> Issue -> branch/tag inference -> `General Backlog`
+6. ensure the PR body contains `Closes #{issue-number}` or an equivalent closing keyword
+
+## Create the PR
+
+- Extract `issue_number` from task.md when this work belongs to an active task
+- If `issue_number` exists, query the Issue best-effort with `gh issue view {issue-number} --json number,title --jq '.number'`
+- Use HEREDOC to pass the PR body
+- Replace `{$IssueNumber}` in the template when present
+- End the PR body with `Generated with AI assistance`
+
+```bash
+gh pr create --base <target-branch> --title "<title>" --assignee @me --body "$(cat <<'EOF'
+<Complete PR description following template>
+
+Generated with AI assistance
+EOF
+)"
+```
+
+Final user output should include both follow-up paths in order:
+
+```text
+Next steps:
+  - optional reviewer summary sync:
+    - Claude Code / OpenCode: /sync-pr {task-id}
+    - Gemini CLI: /agent-infra:sync-pr {task-id}
+    - Codex CLI: $sync-pr {task-id}
+  - complete the task after the workflow truly finishes:
+    - Claude Code / OpenCode: /complete-task {task-id}
+    - Gemini CLI: /agent-infra:complete-task {task-id}
+    - Codex CLI: $complete-task {task-id}
+```

package/templates/.agents/skills/create-pr/reference/pr-body-template.zh-CN.md

@@ -0,0 +1,86 @@
+# PR 正文模板规则
+
+在生成 PR 标题和正文之前先读取本文件。
+
+## 读取 PR 模板
+
+读取仓库中的 `.github/PULL_REQUEST_TEMPLATE.md`。如果不存在，则使用标准格式。
+
+## 参考最近合并的 PR
+
+```bash
+gh pr list --limit 3 --state merged --json number,title,body
+```
+
+把最近合并的 PR 当作风格和排版参考。
+
+## 分析当前分支变更
+
+```bash
+git status
+git log <target-branch>..HEAD --oneline
+git diff <target-branch>...HEAD --stat
+git diff <target-branch>...HEAD
+```
+
+## 同步 PR 元数据
+
+在同步 label 之前，先确认标准 label 体系已经存在：
+
+```bash
+gh label list --search "type:" --limit 1 --json name --jq 'length'
+```
+
+如果结果是 `0`，先执行 `init-labels`，再重试元数据同步。
+
+Type label 映射：
+
+| task.md type | GitHub label |
+|---|---|
+| `bug`, `bugfix` | `type: bug` |
+| `feature` | `type: feature` |
+| `enhancement` | `type: enhancement` |
+| `refactor`, `refactoring` | `type: enhancement` |
+| `documentation` | `type: documentation` |
+| `dependency-upgrade` | `type: dependency-upgrade` |
+| `task` | `type: task` |
+| 其他值 | 跳过 |
+
+元数据同步顺序：
+1. 用 `gh issue view {issue-number} --json labels,milestone` 尽力查询 Issue 的 labels 和 milestone
+2. 用 `gh pr edit {pr-number} --add-label "{type-label}"` 添加映射后的 type label
+3. 用重复的 `gh pr edit ... --add-label` 继承非 `type:`、非 `status:` 的 Issue labels
+4. 添加相关的 `in: {module}` label，但不要移除已有 label
+5. 按 `PR -> task.md -> Issue -> branch/tag inference -> General Backlog` 的顺序解析 milestone
+6. 确保 PR 正文包含 `Closes #{issue-number}` 或等价的 closing keyword
+
+## 创建 PR
+
+- 当当前工作属于活动任务时，从 task.md 中提取 `issue_number`
+- 如果存在 `issue_number`，用 `gh issue view {issue-number} --json number,title --jq '.number'` 尽力查询对应 Issue
+- 使用 HEREDOC 传递 PR 正文
+- 如果模板中存在 `{$IssueNumber}`，替换它
+- PR 正文结尾必须带上 `Generated with AI assistance`
+
+```bash
+gh pr create --base <target-branch> --title "<title>" --assignee @me --body "$(cat <<'EOF'
+<Complete PR description following template>
+
+Generated with AI assistance
+EOF
+)"
+```
+
+最终用户输出必须按顺序包含这两类后续动作：
+
+```text
+下一步：
+  - 可选：同步 reviewer 摘要：
+    - Claude Code / OpenCode: /sync-pr {task-id}
+    - Gemini CLI: /agent-infra:sync-pr {task-id}
+    - Codex CLI: $sync-pr {task-id}
+  - 工作流真正结束后完成任务：
+    - Claude Code / OpenCode: /complete-task {task-id}
+    - Gemini CLI: /agent-infra:complete-task {task-id}
+    - Codex CLI: $complete-task {task-id}
+```

package/templates/.agents/skills/create-release-note/SKILL.md

@@ -1,9 +1,6 @@
 ---
 name: create-release-note
-description: >
-  Generate release notes from PRs and commits between two versions.
-  Triggered when the user requests release note generation.
-  Arguments: version number, optional previous version.
+description: "Generate release notes from PRs and commits"
 ---
 
 # Create Release Notes
@@ -12,13 +9,13 @@ Generate comprehensive release notes for a version based on merged PRs and commi
 
 ## Execution Flow
 
-### Step 1: Parse Arguments
+### 1. Parse Arguments
 
 From arguments:
 - `<version>`: Current release version (required), format `X.Y.Z`
 - `<prev-version>`: Previous version (optional), auto-detected if not provided
 
-### Step 2: Determine Version Range
+### 2. Determine Version Range
 
 **Current tag**: `v<version>`
 
@@ -34,7 +31,7 @@ git rev-parse v<version>
 git rev-parse v<prev-version>
 ```
 
-### Step 3: Reference Historical Release Notes Format and Categories
+### 3. Reference Historical Release Notes Format and Categories
 
 Fetch multiple published release notes as format references, then use a predefined complete category list:
 
@@ -59,7 +56,7 @@ done
 - When generating release notes in Step 7, **must** follow both the historical format style and the full category list gathered in Step 3
 - If no historical release notes exist, use the default format defined in Step 7
 
-### Step 4: Collect Merged PRs
+### 4. Collect Merged PRs
 
 Get the date range between tags, then query merged PRs:
 
@@ -79,7 +76,7 @@ Also collect direct commits without PRs:
 git log v<prev-version>..v<version> --format="%H %s" --no-merges
 ```
 
-### Step 5: Collect Related Issues
+### 5. Collect Related Issues
 
 From each PR body, extract linked Issues:
 - Match patterns: `Closes #N`, `Fixes #N`, `Resolves #N` (case-insensitive)
@@ -88,7 +85,7 @@ From each PR body, extract linked Issues:
 gh issue view <N> --json number,title,labels,url
 ```
 
-### Step 6: Classify Changes
+### 6. Classify Changes
 
 **By type** (from PR title conventional commit prefix):
 - `feat`, `perf`, `refactor`, dependency upgrades -> Enhancement
@@ -99,7 +96,7 @@ gh issue view <N> --json number,title,labels,url
 - Infer module from PR title brackets like `[module]` or conventional scope `feat(module):`
 - Fallback: analyze changed files
 
-### Step 7: Generate Release Notes
+### 7. Generate Release Notes
 
 **Prioritize the historical format style obtained in Step 3 and ensure all categories listed in Step 3 are covered.** If historical release notes exist, strictly follow their section structure, heading style (including emojis), item format, and bilingual layout.
 
@@ -128,7 +125,7 @@ If no historical release notes exist, use the following default Markdown format:
 4. Contributors: Deduplicated, sorted by contribution count (descending)
 5. Empty sections: Omit sections with no entries
 
-### Step 8: Present and Confirm
+### 8. Present and Confirm
 
 Show the generated release notes to the user.
 
@@ -136,7 +133,7 @@ Ask:
 1. Need any adjustments?
 2. Create a GitHub Draft Release?
 
-### Step 9: Create Draft Release (If Confirmed)
+### 9. Create Draft Release (If Confirmed)
 
 ```bash
 gh release create v<version> \