@fitlab-ai/agent-infra 0.3.2 → 0.4.1

package/templates/.agents/skills/sync-issue/reference/comment-publish.zh-CN.md

@@ -0,0 +1,88 @@
+# 评论发布规则
+
+在创建或更新 Issue 评论之前先读取本文件。
+
+## 拉取已有评论并构建已发布产物集合
+
+使用如下隐藏标记：
+
+```html
+<!-- sync-issue:{task-id}:{file-stem} -->
+```
+
+产物提取规则：
+- 用 `/→\s+(\S+\.md)\s*$/` 从 Activity Log 中提取产物文件名
+- 去掉 `.md` 后缀得到 `{file-stem}`
+- 按 Activity Log 顺序构建产物时间线
+- 固定把 `summary` 追加到最后
+
+产物时间线必须按 Activity Log 顺序构建。只包含任务目录中仍然存在的产物文件。
+常见产物文件名包括 `implementation-r*.md` 和 `review-r*.md`。
+
+已发布集合检测：
+
+```bash
+grep -qF "<!-- sync-issue:{task-id}:{file-stem} -->" "$comments_jsonl"
+```
+
+含义：
+- 找到匹配 -> 该产物已经发布过
+- 没有匹配 -> 该产物本轮可以创建
+
+在开始发布评论前，先定义 `has_unpublished_artifacts`：即时间线中是否还存在任何未发布的非 `summary` 产物。该标志在本轮同步过程中保持不变。
+
+推荐标题映射：
+
+| file-stem | title |
+|---|---|
+| `analysis` | `需求分析` |
+| `analysis-r{N}` | `需求分析（Round {N}）` |
+| `plan` | `技术方案` |
+| `plan-r{N}` | `技术方案（Round {N}）` |
+| `implementation` | `实现报告（Round 1）` |
+| `implementation-r{N}` | `实现报告（Round {N}）` |
+| `refinement` | `修复报告（Round 1）` |
+| `refinement-r{N}` | `修复报告（Round {N}）` |
+| `review` | `审查报告（Round 1）` |
+| `review-r{N}` | `审查报告（Round {N}）` |
+| `summary` | `交付摘要` |
+
+## 按时间线顺序逐个发布上下文产物
+
+始终把 `summary` 放在最后。不要把多个轮次折叠成一条评论。
+
+统一评论格式：
+
+```markdown
+<!-- sync-issue:{task-id}:{file-stem} -->
+## {artifact-title}
+
+{artifact original body or summary body}
+
+---
+*由 AI 自动生成 · 内部追踪：{task-id}*
+```
+
+`summary` 处理规则：
+- 如果 `summary` 不存在，就创建它
+- 如果 `summary` 已存在且 `has_unpublished_artifacts=true`，删除旧的 `summary`，并在最后重新创建
+- 如果 `summary` 已存在、`has_unpublished_artifacts=false`，且内容发生变化，则原地 patch 该评论
+- 如果 `summary` 已存在、`has_unpublished_artifacts=false`，且内容没有变化，则不做任何操作
+
+零操作规则：
+- 如果所有产物都已同步，且 `summary` 内容未变化，则不要发布任何内容，并报告 `所有产物已同步，无新内容`
+
+更新已有 `summary` 评论时，使用：
+
+```bash
+gh api "repos/$repo/issues/comments/{summary_comment_id}" -X PATCH -f body="$(cat <<'EOF'
+{comment-body}
+EOF
+)"
+```
+
+必须使用以下绝对链接格式：
+- `https://github.com/{owner}/{repo}/commit/{commit-hash}`
+- `https://github.com/{owner}/{repo}/pull/{pr-number}`
+
+不要回退到固定的 `analysis -> plan -> implementation -> review -> summary` 顺序。

package/templates/.agents/skills/sync-issue/reference/delivery-detection.md

@@ -0,0 +1,42 @@
+# Delivery Detection
+
+Read this file before deciding whether the task is completed, in PR stage, or still in development.
+
+## Detect Delivery Status
+
+Resolve repository coordinates first:
+
+```bash
+repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
+owner="${repo%%/*}"
+repo_url="https://github.com/$repo"
+```
+
+Delivery checks:
+- extract the last commit hash from `**Commit** by` in Activity Log
+- inspect protected branches with `git branch -a --contains {commit-hash} 2>/dev/null`
+- inspect PR state with `gh pr view {pr-number} --json state,mergedAt`
+
+Protected branch matching rules:
+- output contains `main` or `master` -> treat as protected mainline
+- output matches `{major}.{minor}.x` -> treat as a protected release line
+- otherwise -> not on a protected branch
+
+Scenario decision matrix:
+
+| Condition | Scenario |
+|---|---|
+| commit is already on a protected branch | Scenario A: Completed |
+| PR exists and its state is `OPEN` or `MERGED` | Scenario B: PR stage |
+| all other cases | Scenario C: In development |
+
+Scenario priority:
+- Scenario A: Completed
+- Scenario B: PR stage
+- Scenario C: In development
+
+Priority rule: `Scenario A > Scenario B > Scenario C`. Even if a PR exists, once the commit is on `main`, `master`, or `{major}.{minor}.x`, report the task as completed.
+
+Absolute links must use:
+- `https://github.com/{owner}/{repo}/commit/{commit-hash}`
+- `https://github.com/{owner}/{repo}/pull/{pr-number}`

package/templates/.agents/skills/sync-issue/reference/delivery-detection.zh-CN.md

@@ -0,0 +1,42 @@
+# 交付状态探测
+
+在判断任务是已完成、处于 PR 阶段还是仍在开发中之前先读取本文件。
+
+## 探测交付状态
+
+先解析仓库坐标：
+
+```bash
+repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
+owner="${repo%%/*}"
+repo_url="https://github.com/$repo"
+```
+
+交付状态检查：
+- 从 Activity Log 中的 `**Commit** by` 提取最后一个 commit hash
+- 用 `git branch -a --contains {commit-hash} 2>/dev/null` 检查受保护分支
+- 用 `gh pr view {pr-number} --json state,mergedAt` 检查 PR 状态
+
+受保护分支匹配规则：
+- 输出包含 `main` 或 `master` -> 视为受保护主线分支
+- 输出匹配 `{major}.{minor}.x` -> 视为受保护版本线分支
+- 其他情况 -> 不在受保护分支上
+
+场景判断矩阵：
+
+| 条件 | 场景 |
+|---|---|
+| commit 已经位于受保护分支上 | 场景 A：已完成 |
+| 存在 PR，且其状态为 `OPEN` 或 `MERGED` | 场景 B：PR 阶段 |
+| 其他所有情况 | 场景 C：开发中 |
+
+场景优先级：
+- 场景 A：已完成
+- 场景 B：PR 阶段
+- 场景 C：开发中
+
+优先级规则：`场景 A > 场景 B > 场景 C`。即使存在 PR，只要 commit 已经位于 `main`、`master` 或 `{major}.{minor}.x` 上，就应将任务报告为已完成。
+
+绝对链接必须使用：
+- `https://github.com/{owner}/{repo}/commit/{commit-hash}`
+- `https://github.com/{owner}/{repo}/pull/{pr-number}`

package/templates/.agents/skills/sync-issue/reference/label-sync.md

@@ -0,0 +1,63 @@
+# Label and Issue Type Sync
+
+Read this file before editing `status:`, `in:`, or Issue Type metadata.
+
+## Sync Labels and Issue Type
+
+Initialize labels when needed:
+
+```bash
+gh label list --search "type:" --limit 1 --json name --jq 'length'
+```
+
+If the result is `0`, run `init-labels` and retry this step.
+
+Status label workflow:
+
+```bash
+gh issue view {issue-number} --json labels --jq '.labels[].name | select(startswith("status:"))'
+gh issue edit {issue-number} --remove-label "{status-label}"
+gh issue edit {issue-number} --add-label "{status-label}"
+```
+
+Status decision table:
+
+| Condition | Action |
+|---|---|
+| task lives under `blocked/` | add `status: blocked` |
+| Scenario A: completed | add no new `status:` label |
+| Scenario B: PR is `MERGED` | add no new `status:` label |
+| Scenario B: PR is `OPEN` | add `status: in-progress` |
+| Scenario C + `current_step` ∈ {`requirement-analysis`, `technical-design`} | add `status: pending-design-work` |
+| Scenario C + `current_step` ∈ {`implementation`, `code-review`, `refinement`} | add `status: in-progress` |
+
+`in:` label workflow:
+
+```bash
+gh label list --search "in: {module}" --limit 10 --json name --jq '.[].name'
+gh issue edit {issue-number} --add-label "in: {module}"
+```
+
+`in:` label flow:
+1. extract changed file paths from implementation artifacts first; fall back to analysis artifacts only when implementation artifacts do not exist
+2. take the first path segment as `{module}`
+3. de-duplicate all inferred modules
+4. check whether each exact `in: {module}` label exists before adding it
+5. add matching labels only; never remove existing `in:` labels
+
+Issue Type workflow:
+
+```bash
+gh api "orgs/$owner/issue-types" --jq '.[].name'
+gh api "repos/$repo/issues/{issue-number}" -X PATCH -f type="{name}"
+```
+
+Issue Type mapping:
+
+| task.md type | GitHub Issue Type |
+|---|---|
+| `bug`, `bugfix` | `Bug` |
+| `feature`, `enhancement` | `Feature` |
+| `task`, `documentation`, `dependency-upgrade`, `chore`, `docs`, `refactor`, `refactoring`, and all other values | `Task` |
+
+If Issue Types are unavailable, record `Issue Type: skipped (not enabled)` and continue.

package/templates/.agents/skills/sync-issue/reference/label-sync.zh-CN.md

@@ -0,0 +1,63 @@
+# Label 和 Issue 类型同步
+
+在编辑 `status:`、`in:` 或 Issue 类型元数据之前先读取本文件。
+
+## 同步 Label 和 Issue 类型
+
+必要时先初始化 label：
+
+```bash
+gh label list --search "type:" --limit 1 --json name --jq 'length'
+```
+
+如果结果是 `0`，先执行 `init-labels`，然后重新执行本步骤。
+
+`status:` label 工作流：
+
+```bash
+gh issue view {issue-number} --json labels --jq '.labels[].name | select(startswith("status:"))'
+gh issue edit {issue-number} --remove-label "{status-label}"
+gh issue edit {issue-number} --add-label "{status-label}"
+```
+
+`status:` 判断表：
+
+| 条件 | 操作 |
+|---|---|
+| 任务位于 `blocked/` 目录下 | 添加 `status: blocked` |
+| 场景 A：已完成 | 不新增 `status:` label |
+| 场景 B：PR 状态为 `MERGED` | 不新增 `status:` label |
+| 场景 B：PR 状态为 `OPEN` | 添加 `status: in-progress` |
+| 场景 C + `current_step` ∈ {`requirement-analysis`, `technical-design`} | 添加 `status: pending-design-work` |
+| 场景 C + `current_step` ∈ {`implementation`, `code-review`, `refinement`} | 添加 `status: in-progress` |
+
+`in:` label 工作流：
+
+```bash
+gh label list --search "in: {module}" --limit 10 --json name --jq '.[].name'
+gh issue edit {issue-number} --add-label "in: {module}"
+```
+
+`in:` label 流程：
+1. 优先从实现产物中提取改动文件路径；只有在不存在实现产物时，才回退到分析产物
+2. 取路径的第一级目录作为 `{module}`
+3. 对推断出的所有模块去重
+4. 仅在对应的精确 `in: {module}` label 存在时才添加
+5. 只添加匹配的 label；绝不移除已有的 `in:` label
+
+Issue 类型工作流：
+
+```bash
+gh api "orgs/$owner/issue-types" --jq '.[].name'
+gh api "repos/$repo/issues/{issue-number}" -X PATCH -f type="{name}"
+```
+
+Issue 类型映射：
+
+| task.md 类型 | GitHub Issue 类型 |
+|---|---|
+| `bug`, `bugfix` | `Bug` |
+| `feature`, `enhancement` | `Feature` |
+| `task`, `documentation`, `dependency-upgrade`, `chore`, `docs`, `refactor`, `refactoring` 以及其他所有值 | `Task` |
+
+如果 Issue 类型不可用，记录 `Issue Type: skipped (not enabled)`，然后继续执行。

package/templates/.agents/skills/sync-issue/reference/milestone-sync.md

@@ -0,0 +1,37 @@
+# Milestone Sync
+
+Read this file before selecting or editing the Issue milestone.
+
+## Sync the Milestone
+
+Milestone priority:
+1. existing Issue milestone
+2. explicit `milestone` field in task.md
+3. inferred version line from the current branch
+4. `General Backlog`
+
+Inference scenarios when `task.md` does not set `milestone` explicitly:
+1. detect the current branch with `git branch --show-current`
+2. Scenario A: if the current branch matches `{major}.{minor}.x`, use that exact line milestone
+3. Scenario B: if the current branch is `main` or `master`, inspect existing `{major}.{minor}.x` branches
+4. Scenario B result: when a highest existing line `X.Y.x` exists, target `(X+1).0.x`
+5. Scenario C: if no branch rule yields a version line, inspect the latest `vX.Y.Z` tag and fall back to `X.Y.x`
+6. Scenario C fallback: if no branch or tag rule yields a version line, fall back to `General Backlog`
+
+Fallback and assignment logic:
+1. preserve an existing Issue milestone when one is already set
+2. otherwise prefer an explicit `milestone` field from `task.md`
+3. otherwise apply the branch/tag scenario inference above
+4. if the inferred target milestone does not exist, downgrade to `General Backlog`
+5. if `General Backlog` also does not exist, record `Milestone: skipped (not found)` and stop milestone sync
+6. once a milestone title is resolved, assign it and record either `{target} (assigned)` or `General Backlog (fallback)`
+
+Useful commands:
+
+```bash
+gh issue view {issue-number} --json milestone
+git branch --show-current
+git branch -a | grep -oE '[0-9]+\.[0-9]+\.x'
+git tag --list 'v*' --sort=-v:refname | head -1
+gh issue edit {issue-number} --milestone "{milestone-title}"
+```

package/templates/.agents/skills/sync-issue/reference/milestone-sync.zh-CN.md

@@ -0,0 +1,37 @@
+# 里程碑同步
+
+在选择或编辑 Issue 里程碑之前先读取本文件。
+
+## 同步里程碑
+
+里程碑优先级：
+1. Issue 当前已有的里程碑
+2. task.md 中显式设置的 `milestone` 字段
+3. 从当前分支推断出的版本线里程碑
+4. `General Backlog`
+
+当 task.md 没有显式设置 `milestone` 时，按以下场景推断：
+1. 用 `git branch --show-current` 检测当前分支
+2. 场景 A：如果当前分支匹配 `{major}.{minor}.x`，直接使用该版本线里程碑
+3. 场景 B：如果当前分支是 `main` 或 `master`，检查现有的 `{major}.{minor}.x` 分支
+4. 场景 B 结果：当存在最高版本线 `X.Y.x` 时，目标使用 `(X+1).0.x`
+5. 场景 C：如果分支规则无法得出版本线，则检查最新的 `vX.Y.Z` tag，并回退到 `X.Y.x`
+6. 场景 C 回退：如果分支和 tag 规则都无法得出版本线，则回退到 `General Backlog`
+
+回退与赋值逻辑：
+1. 如果 Issue 已经有里程碑，优先保留
+2. 否则优先使用 task.md 中显式设置的 `milestone`
+3. 否则应用上面的分支 / tag 场景推断规则
+4. 如果推断出的目标里程碑不存在，则降级为 `General Backlog`
+5. 如果 `General Backlog` 也不存在，则记录 `Milestone: skipped (not found)`，并停止 milestone 同步
+6. 一旦解析出里程碑标题，就执行赋值，并记录 `{target} (assigned)` 或 `General Backlog (fallback)`
+
+常用命令：
+
+```bash
+gh issue view {issue-number} --json milestone
+git branch --show-current
+git branch -a | grep -oE '[0-9]+\.[0-9]+\.x'
+git tag --list 'v*' --sort=-v:refname | head -1
+gh issue edit {issue-number} --milestone "{milestone-title}"
+```