@fitlab-ai/agent-infra 0.4.2 → 0.4.4

package/templates/.agents/rules/issue-sync.zh-CN.md

@@ -0,0 +1,194 @@
+# Issue 同步规则
+
+在任务技能需要更新 GitHub Issue 时先读取本文件。
+
+## status: label 直设
+
+如果 task.md 中存在有效的 `issue_number`（非空、非 `N/A`），且 Issue 状态为 `OPEN`，则替换所有 `status:` label 并设置目标值：
+
+```bash
+state=$(gh issue view {issue-number} --json state --jq '.state' 2>/dev/null)
+if [ "$state" = "OPEN" ]; then
+  gh issue view {issue-number} --json labels \
+    --jq '.labels[].name | select(startswith("status:"))' 2>/dev/null \
+  | while IFS= read -r label; do
+      [ -z "$label" ] && continue
+      gh issue edit {issue-number} --remove-label "$label" 2>/dev/null || true
+    done
+  gh issue edit {issue-number} --add-label "{target-status-label}" 2>/dev/null || true
+fi
+```
+
+使用 `while IFS= read -r label` 按行处理，可避免 `status: in-progress` 这类含空格 label 被 shell 按空格拆开。
+
+如果 `gh` 命令失败，跳过并继续，不中断技能执行。
+
+## Assignee 同步
+
+当技能创建或导入 Issue 时，自动将当前执行者添加为 assignee：
+
+- `create-issue`：在 `gh issue create` 命令中使用 `--assignee @me` 参数
+- `import-issue`：导入后执行 `gh issue edit {issue-number} --add-assignee @me 2>/dev/null || true`
+
+`@me` 由 `gh` CLI 自动解析为当前认证用户。此操作是幂等的（重复添加不会报错）。如果命令失败（如权限不足），跳过并继续。
+
+## `in:` label 同步
+
+读取 `.agents/.airc.json` 的 `labels.in` 映射。
+
+```bash
+git diff {base-branch}...HEAD --name-only
+```
+
+`{base-branch}` 通常为 `main`；如果在 PR 上下文中，则使用 PR 的 base branch。
+
+### 有映射时（精确增删）
+
+1. 获取分支全部改动文件
+2. 对每个文件按目录前缀匹配 `labels.in` 中的值，得到"应有的 `in:` labels"集合
+3. 查询 Issue/PR 当前的 `in:` labels
+4. 差集比较：
+   - 应有但没有 → `gh issue edit {issue-number} --add-label "in: {module}" 2>/dev/null || true`
+   - 有但不应有 → `gh issue edit {issue-number} --remove-label "in: {module}" 2>/dev/null || true`
+
+### 无映射时（只增不删回退）
+
+如果 `.airc.json` 中不存在 `labels.in` 或为空对象：
+1. 查询仓库已有 `in:` labels
+2. 从改动文件提取第一级目录
+3. 仅添加匹配的 label，不移除已有 `in:` label
+
+## 产物评论发布
+
+隐藏标记必须保持兼容：
+
+```html
+<!-- sync-issue:{task-id}:{file-stem} -->
+```
+
+发布前先检查是否已存在同标记评论：
+
+```bash
+gh api "repos/{owner}/{repo}/issues/{issue-number}/comments" \
+  --paginate --jq '.[].body' \
+  | grep -qF "<!-- sync-issue:{task-id}:{file-stem} -->"
+```
+
+如果已存在则跳过。
+
+发布流程：
+
+1. 先读取本地产物文件全文
+2. 将文件全文作为 `{artifact body}` 原文内联到评论中
+3. 禁止自行组织摘要、改写或截断正文
+
+评论格式统一为：
+
+```markdown
+<!-- sync-issue:{task-id}:{file-stem} -->
+## {artifact-title}
+
+{artifact body}
+
+---
+*由 AI 自动生成 · 内部追踪：{task-id}*
+```
+
+`summary` 评论需要额外处理：
+- 先查找已有 `<!-- sync-issue:{task-id}:summary -->` 评论的 ID
+- 不存在则创建
+- 已存在且正文有变化时，使用 `gh api "repos/{owner}/{repo}/issues/comments/{comment-id}" -X PATCH -f body=...` 原地更新
+
+```bash
+summary_comment_id=$(gh api "repos/{owner}/{repo}/issues/{issue-number}/comments" \
+  --paginate --jq '.[] | select(.body | startswith("<!-- sync-issue:{task-id}:summary -->")) | .id' \
+  | head -n 1)
+gh api "repos/{owner}/{repo}/issues/comments/{comment-id}" -X PATCH -f body="$(cat <<'EOF'
+{comment-body}
+EOF
+)"
+```
+
+## task.md 评论同步
+
+隐藏标记：
+
+```html
+<!-- sync-issue:{task-id}:task -->
+```
+
+`task.md` 使用幂等更新路径：
+
+1. 读取 `task.md` 全文
+2. 将 YAML frontmatter（`---` 到 `---` 之间的内容）包裹在 `<details><summary>元数据 (frontmatter)</summary>` 和 `` ```yaml `` 代码块中，其余正文保持原样作为 Markdown 渲染
+3. 使用 `task` 作为 `{file-stem}`
+4. 查找已有标记评论 ID
+5. 不存在则创建
+6. 已存在且正文有变化则 PATCH 原地更新
+7. 已存在且正文相同则跳过
+
+task.md 评论格式：
+
+```markdown
+<!-- sync-issue:{task-id}:task -->
+## 任务文件
+
+<details><summary>元数据 (frontmatter)</summary>
+
+​```yaml
+---
+{frontmatter fields}
+---
+​```
+
+</details>
+
+{task.md body after frontmatter}
+
+---
+*由 AI 自动生成 · 内部追踪：{task-id}*
+```
+
+还原时，从 `<details>` 块中提取 frontmatter，与正文拼合恢复为原始 `task.md`。
+
+评论标题映射：
+- `task` -> `任务文件`
+
+## 补发规则（`/complete-task` 归档前执行）
+
+- 扫描任务目录中的 `task.md`、`analysis*.md`、`plan*.md`、`implementation*.md`、`review*.md`、`refinement*.md`
+- 对每个 `{file-stem}` 用隐藏标记检查是否已发布；未发布则补发，已发布则跳过
+- 补发只追加缺失评论，不删除或重排已有评论
+- 位置说明从 Activity Log 推导时间线中的前后邻居，并加在评论标题下方：
+
+```markdown
+> ⚠️ 本评论为补发产物，按时间线应位于「{前一个产物标题}」之后、「{后一个产物标题}」之前。
+```
+
+- 如果只有前邻居或后邻居，仅保留存在的一侧说明；如果两侧都不存在，则不添加位置说明
+
+标题映射：
+- `task` -> `任务文件`
+- `analysis` / `analysis-r{N}` -> `需求分析` / `需求分析（Round {N}）`
+- `plan` / `plan-r{N}` -> `技术方案` / `技术方案（Round {N}）`
+- `implementation` / `implementation-r{N}` -> `实现报告（Round 1）` / `实现报告（Round {N}）`
+- `review` / `review-r{N}` -> `审查报告（Round 1）` / `审查报告（Round {N}）`
+- `refinement` / `refinement-r{N}` -> `修复报告（Round 1）` / `修复报告（Round {N}）`
+- `summary` -> `交付摘要`
+
+## 需求复选框同步
+
+从 task.md 的 `## 需求` 段落提取已勾选的 `- [x]` 条目；如果没有，跳过。
+
+读取 Issue 当前正文：
+
+```bash
+gh issue view {issue-number} --json body --jq '.body'
+```
+
+按复选框文本匹配，将对应的 `- [ ] {text}` 单向替换为 `- [x] {text}`。只有正文实际变化时，才使用 `gh api` PATCH 更新完整 body。
+
+## Shell 安全规则
+
+1. 先用 Read 工具读取产物全文，再把实际文本内联到 heredoc 中；禁止在 `<<'EOF'` 内使用命令替换或变量展开。
+2. 构造含 `<!-- -->` 的内容时禁止使用 `echo`；统一使用 `cat <<'EOF'` heredoc 或 `printf '%s\n'`。

package/templates/.agents/rules/milestone-inference.md

@@ -0,0 +1,102 @@
+# Milestone Inference Rules
+
+Read this file before `create-issue`, `implement-task`, or `create-pr` handles a milestone.
+
+## General Principles
+
+- Narrow the milestone over the skill lifecycle: release line -> concrete version -> reuse
+- Every phase must fall back safely instead of blocking the skill
+- If `gh` is unavailable, unauthenticated, or the GitHub API call fails, skip milestone handling and continue
+- Only use milestones that actually exist in the repository; if a target milestone is unavailable, apply the fallback for that phase
+
+## Branch Mode Detection
+
+Use the following command to detect whether the repository has remote release-line branches:
+
+```bash
+git branch -r | grep -v 'HEAD' | grep -E 'origin/[0-9]+\.[0-9]+\.x$'
+```
+
+- Any output: multi-version branch mode
+- No output: trunk mode
+
+## Phase 1: `create-issue`
+
+Goal: choose a coarse-grained release line when the Issue is created.
+
+Priority:
+1. If task.md provides a valid explicit `milestone`, use it
+2. Otherwise infer a release line:
+   - Trunk mode: query open `X.Y.x` milestones and choose the lowest release line
+   - Multi-version branch mode: try open `X.Y.x` milestones and choose the lowest release line; if that is not reliable, fall back to `General Backlog`
+3. If the inferred release line does not exist, fall back to `General Backlog`
+4. If `General Backlog` also does not exist, omit `--milestone`
+
+Suggested release-line query:
+
+```bash
+gh api "repos/{owner}/{repo}/milestones?state=open&per_page=100" \
+  --jq '.[].title'
+```
+
+Only match titles in `X.Y.x` format and choose the smallest major/minor pair numerically.
+
+## Phase 2: `implement-task`
+
+Goal: narrow the Issue milestone from a release line to a concrete version when implementation starts.
+
+Preconditions:
+- task.md contains a valid `issue_number`
+- the current Issue milestone matches the release-line format `X.Y.x`
+
+Sequence:
+1. Query the current Issue milestone
+2. If it is not in `X.Y.x` format, treat it as already specific enough and keep it unchanged
+3. If it is in `X.Y.x` format, narrow it according to branch mode:
+   - Trunk mode: query open concrete-version milestones on that release line (for example `0.4.4`) and choose the latest one
+   - Multi-version branch mode:
+     - If the task branch was created from `origin/X.Y.x`, choose the latest concrete version on that line
+     - If the task branch was created from `main`, find the highest release line and choose the latest concrete version on that line
+4. When a target concrete version is found, run:
+
+```bash
+gh issue edit {issue-number} --milestone "{version}"
+```
+
+5. If the target milestone does not exist or the branch ancestry cannot be determined reliably, keep the original milestone unchanged
+
+Suggested concrete-version query:
+
+```bash
+gh api "repos/{owner}/{repo}/milestones?state=open&per_page=100" \
+  --jq '.[].title'
+```
+
+- Release-line match: `^X\.Y\.x$`
+- Concrete-version match: `^X\.Y\.[0-9]+$`
+- "Latest" means the largest patch number
+
+Suggested branch-origin checks:
+
+```bash
+git merge-base --is-ancestor origin/{release-line} HEAD
+git merge-base --is-ancestor origin/main HEAD
+```
+
+If neither check is reliable or the remote refs are unavailable, keep the original milestone and avoid guessing.
+
+## Phase 3: `create-pr`
+
+Goal: reuse the linked Issue milestone on the PR instead of inferring a new one.
+
+Sequence:
+1. If `issue_number` exists, query the Issue milestone
+2. If the Issue has a milestone, run:
+
+```bash
+gh pr edit {pr-number} --milestone "{milestone}"
+```
+
+3. If the Issue has no milestone, skip PR milestone assignment
+
+Do not infer a PR milestone separately from task.md, branch names, tags, or `General Backlog`.

package/templates/.agents/rules/milestone-inference.zh-CN.md

@@ -0,0 +1,102 @@
+# Milestone 推断规则
+
+在 `create-issue`、`implement-task` 或 `create-pr` 处理 milestone 之前先读取本文件。
+
+## 通用原则
+
+- milestone 在技能生命周期中逐步收窄：版本线 -> 具体版本 -> 复用
+- 任一步骤推断失败时都必须回退，不得阻塞技能执行
+- 如果 `gh` CLI 不可用、未认证，或 GitHub API 请求失败，跳过 milestone 处理并继续
+- 只使用仓库中实际存在的 milestone；目标 milestone 不存在时按各阶段 fallback 处理
+
+## 分支模式检测
+
+使用以下命令检测仓库是否存在远程 release line 分支：
+
+```bash
+git branch -r | grep -v 'HEAD' | grep -E 'origin/[0-9]+\.[0-9]+\.x$'
+```
+
+- 有输出：多版本分支模式
+- 无输出：主干模式
+
+## 阶段 1：`create-issue`
+
+目标：在创建 Issue 时先确定粗粒度版本线。
+
+优先级：
+1. `task.md` 显式存在 `milestone` 字段且值有效 -> 直接使用
+2. 否则推断版本线：
+   - 主干模式：查询 open 的 `X.Y.x` 里程碑，取最低版本线
+   - 多版本分支模式：优先查询 open 的 `X.Y.x` 里程碑，取最低版本线；如果无法确定则回退到 `General Backlog`
+3. 推断出的版本线不存在 -> 回退到 `General Backlog`
+4. `General Backlog` 也不存在 -> 省略 `--milestone`
+
+版本线查询建议：
+
+```bash
+gh api "repos/{owner}/{repo}/milestones?state=open&per_page=100" \
+  --jq '.[].title'
+```
+
+只匹配 `X.Y.x` 格式的标题；按 major、minor 数值升序取最小版本线。
+
+## 阶段 2：`implement-task`
+
+目标：开始开发时，把 Issue milestone 从版本线收窄到具体版本。
+
+前置条件：
+- `task.md` 存在有效 `issue_number`
+- 当前 Issue milestone 为版本线格式 `X.Y.x`
+
+执行顺序：
+1. 查询 Issue 当前 milestone
+2. 如果 milestone 不是 `X.Y.x` 格式 -> 视为已足够具体，保持不变
+3. 如果 milestone 是 `X.Y.x` -> 按分支模式收窄：
+   - 主干模式：查询该版本线下 open 的具体版本 milestone（如 `0.4.4`），取最新版本
+   - 多版本分支模式：
+     - 当前任务分支来自 `origin/X.Y.x` release line -> 在该版本线下取最新具体版本
+     - 当前任务分支来自 `main` -> 找最高版本线，再取该版本线下的最新具体版本
+4. 找到目标具体版本后，执行：
+
+```bash
+gh issue edit {issue-number} --milestone "{version}"
+```
+
+5. 如果目标 milestone 不存在或无法可靠判断 -> 保持原 milestone 不变
+
+具体版本查询建议：
+
+```bash
+gh api "repos/{owner}/{repo}/milestones?state=open&per_page=100" \
+  --jq '.[].title'
+```
+
+- 版本线匹配：`^X\.Y\.x$`
+- 具体版本匹配：`^X\.Y\.[0-9]+$`
+- “最新”按 patch 数值最大确定
+
+分支来源判断建议：
+
+```bash
+git merge-base --is-ancestor origin/{release-line} HEAD
+git merge-base --is-ancestor origin/main HEAD
+```
+
+如果两个判断都不可靠或远程引用缺失，保持原 milestone，不做错误推断。
+
+## 阶段 3：`create-pr`
+
+目标：PR 直接复用关联 Issue 的 milestone，不再独立推断。
+
+执行顺序：
+1. 如果存在 `issue_number`，查询 Issue milestone
+2. Issue 有 milestone -> 执行：
+
+```bash
+gh pr edit {pr-number} --milestone "{milestone}"
+```
+
+3. Issue 没有 milestone -> 跳过，不设置 PR milestone
+
+不要再使用 `task.md`、分支名、tag 或 `General Backlog` 为 PR 单独推断 milestone。