@fitlab-ai/agent-infra 0.5.3 → 0.5.5

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

@@ -2,38 +2,114 @@
 
 在任务技能需要更新 GitHub Issue 时先读取本文件。
 
-## status: label 直设
+## Upstream 仓库检测
 
-如果 task.md 中存在有效的 `issue_number`（非空、非 `N/A`），且 Issue 状态为 `OPEN`，则替换所有 `status:` label 并设置目标值：
+外部开发者在 fork 仓库中执行 `gh` 命令时，默认目标会指向 fork，而不是原始仓库。所有后续 `gh issue` 和 `gh api "repos/..."` 操作都必须先检测 upstream 仓库，并统一复用 `upstream_repo`。
 
 ```bash
-state=$(gh issue view {issue-number} --json state --jq '.state' 2>/dev/null)
+upstream_repo=$(gh api "repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)" \
+  --jq 'if .fork then .parent.full_name else .full_name end' 2>/dev/null)
+```
+
+- 非 fork 仓库：返回当前仓库自身的 `full_name`
+- fork 仓库：返回父仓库的 `full_name`
+- 后续所有 `gh issue` 命令统一使用 `-R "$upstream_repo"`
+- 后续所有 `gh api "repos/..."` 命令统一使用 `"repos/$upstream_repo/..."`
+
+## 权限检测
+
+所有需要写权限的操作都先对 upstream 仓库做一次权限检测。检测失败时按无权限处理，确保安全降级。
+
+```bash
+repo_perms=$(gh api "repos/$upstream_repo" --jq '.permissions' 2>/dev/null || echo '{}')
+has_triage=$(printf '%s' "$repo_perms" | grep -q '"triage":true' 2>/dev/null && echo true || echo false)
+has_push=$(printf '%s' "$repo_perms" | grep -q '"push":true' 2>/dev/null && echo true || echo false)
+```
+
+操作与权限映射：
+
+| 操作 | 所需权限 | 说明 |
+|------|---------|------|
+| 设置/移除 label | `has_triage` | triage 是最低权限 |
+| 设置/移除 milestone | `has_triage` | 同上 |
+| 编辑 Issue body | `has_triage` | 需求复选框同步使用 |
+| 设置 Issue Type | `has_push` | 需要 write 权限 |
+| 设置 assignee | 不检测 | 无权限时直接跳过 |
+| 发布/更新评论 | 无需检测 | 公开仓库中认证用户可执行 |
+
+## 降级行为定义
+
+| 层级 | 操作类型 | 有权限 | 无权限 |
+|------|---------|--------|--------|
+| 静默降级 | label / milestone / Issue Type | 直接执行 `gh` 命令，同时更新 task 留言 | 跳过 `gh` 直接操作，仅更新 task 留言，由 bot 补位 |
+| 直接跳过 | assignee | 直接执行 `gh` 命令 | 不做任何替代 |
+| 正常执行 | 评论 | 正常执行 | 正常执行 |
+
+关键原则：
+
+- 无论是否有写权限，task 留言同步都必须继续执行
+- 权限不足只影响直接写 Issue 元数据的步骤，不中断整个技能
+- 现有 `2>/dev/null || true` 容错模式保持不变
+
+## 外部开发者锁定机制
+
+维护者（`has_triage=true`）不受限制。外部开发者（`has_triage=false`）在开始任务前，必须先检查 Issue 上是否已有当前任务的 `task` 留言作者。
+
+```bash
+task_comment_author=$(gh api "repos/$upstream_repo/issues/{issue-number}/comments" \
+  --paginate --jq '[.[] | select(.body | test("<!-- sync-issue:{task-id}:task -->")) | .user.login] | first' \
+  2>/dev/null || echo "")
+current_user=$(gh api user --jq '.login' 2>/dev/null || echo "")
+```
+
+判定规则：
+
+- 没有 `task` 留言：允许开始
+- `task` 留言作者等于当前用户：允许继续
+- `task` 留言作者不等于当前用户：立即停止，并提示先与维护者协调，避免多人同时接手同一任务
+
+## status label 设置
+
+算法说明：下面的流程与 `.github/scripts/sync-labels-to-set.sh` 保持一致（集合差集）。本章节是 AI Agent 侧的等价实现（`target_set = {"{target-status-label}"}` 的特例）。修改任一侧时，必须同步另一侧，避免 Agent 与 Bot 的行为漂移。
+
+如果 task.md 中存在有效的 `issue_number`（非空、非 `N/A`），且 Issue 状态为 `OPEN`，则按幂等差集方式将 `status:` label 同步到目标值：
+
+```bash
+state=$(gh issue view {issue-number} -R "$upstream_repo" --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
+  current_status_labels=$(gh issue view {issue-number} -R "$upstream_repo" \
+    --json labels --jq '.labels[].name | select(startswith("status:"))' 2>/dev/null || true)
+  printf '%s\n' "$current_status_labels" | while IFS= read -r label; do
+    [ -z "$label" ] && continue
+    if [ "$label" != "{target-status-label}" ] && [ "$has_triage" = "true" ]; then
+      gh issue edit {issue-number} -R "$upstream_repo" --remove-label "$label" 2>/dev/null || true
+    fi
+  done
+  if [ "$has_triage" = "true" ] && ! printf '%s\n' "$current_status_labels" | grep -qxF "{target-status-label}"; then
+    gh issue edit {issue-number} -R "$upstream_repo" --add-label "{target-status-label}" 2>/dev/null || true
+  fi
 fi
 ```
 
 使用 `while IFS= read -r label` 按行处理，可避免 `status: in-progress` 这类含空格 label 被 shell 按空格拆开。
 
+如果 `has_triage=false`，则跳过直接设置 label，只更新 task 留言，由 bot 根据最新 task 元数据补位。
+
 如果 `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`
+- `create-issue`：在 `gh issue create` 命令中使用 `--assignee @me` 参数，并附带 `-R "$upstream_repo"`
+- `import-issue`：导入后执行 `gh issue edit {issue-number} -R "$upstream_repo" --add-assignee @me 2>/dev/null || true`
 
-`@me` 由 `gh` CLI 自动解析为当前认证用户。此操作是幂等的（重复添加不会报错）。如果命令失败（如权限不足），跳过并继续。
+`@me` 由 `gh` CLI 自动解析为当前认证用户。此操作是幂等的（重复添加不会报错）。如果命令失败（如权限不足），直接跳过，不做任何替代。
 
 ## `in:` label 同步
 
+> **触发时机**：`in:` label 同步应在代码提交后（commit 技能）执行，不在 implement-task 或 refine-task 阶段执行。create-pr 阶段仅从 Issue 复制到 PR，不重新计算。
+
 读取 `.agents/.airc.json` 的 `labels.in` 映射。
 
 ```bash
@@ -48,15 +124,18 @@ git diff {base-branch}...HEAD --name-only
 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`
+   - 应有但没有：仅当 `has_triage=true` 时执行 `gh issue edit {issue-number} -R "$upstream_repo" --add-label "in: {module}" 2>/dev/null || true`
+   - 有但不应有：仅当 `has_triage=true` 时执行 `gh issue edit {issue-number} -R "$upstream_repo" --remove-label "in: {module}" 2>/dev/null || true`
 
 ### 无映射时（只增不删回退）
 
 如果 `.airc.json` 中不存在 `labels.in` 或为空对象：
+
 1. 查询仓库已有 `in:` labels
 2. 从改动文件提取第一级目录
-3. 仅添加匹配的 label，不移除已有 `in:` label
+3. 仅当 `has_triage=true` 时添加匹配的 label，不移除已有 `in:` label
+
+如果 `has_triage=false`，则跳过直接修改 `in:` label，只保留 task 留言同步，由后续自动化补位。
 
 ## 产物评论发布
 
@@ -69,7 +148,7 @@ git diff {base-branch}...HEAD --name-only
 发布前先检查是否已存在同标记评论：
 
 ```bash
-gh api "repos/{owner}/{repo}/issues/{issue-number}/comments" \
+gh api "repos/$upstream_repo/issues/{issue-number}/comments" \
   --paginate --jq '.[].body' \
   | grep -qF "<!-- sync-issue:{task-id}:{file-stem} -->"
 ```
@@ -99,20 +178,23 @@ gh api "repos/{owner}/{repo}/issues/{issue-number}/comments" \
 其中 `{agent}` 使用当前执行该技能的 AI 代理名称（如 `claude`、`codex`、`gemini`）。
 
 `summary` 评论需要额外处理：
+
 - 先查找已有 `<!-- sync-issue:{task-id}:summary -->` 评论的 ID
 - 不存在则创建
-- 已存在且正文有变化时，使用 `gh api "repos/{owner}/{repo}/issues/comments/{comment-id}" -X PATCH -f body=...` 原地更新
+- 已存在且正文有变化时，使用 `gh api "repos/$upstream_repo/issues/comments/{comment-id}" -X PATCH -f body=...` 原地更新
 
 ```bash
-summary_comment_id=$(gh api "repos/{owner}/{repo}/issues/{issue-number}/comments" \
+summary_comment_id=$(gh api "repos/$upstream_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'
+gh api "repos/$upstream_repo/issues/comments/{comment-id}" -X PATCH -f body="$(cat <<'EOF'
 {comment-body}
 EOF
 )"
 ```
 
+评论发布不受 `has_triage` / `has_push` 限制，认证用户可正常执行。
+
 ## task.md 评论同步
 
 隐藏标记：
@@ -158,8 +240,11 @@ task.md 评论格式：
 还原时，从 `<details>` 块中提取 frontmatter，与正文拼合恢复为原始 `task.md`。
 
 评论标题映射：
+
 - `task` -> `任务文件`
 
+task 留言同步始终执行，不受权限降级影响。
+
 ## 补发规则（`/complete-task` 归档前执行）
 
 - 扫描任务目录中的 `task.md`、`analysis*.md`、`plan*.md`、`implementation*.md`、`review*.md`、`refinement*.md`
@@ -178,6 +263,7 @@ task.md 评论格式：
 - 如果只有前邻居或后邻居，仅保留存在的一侧说明；如果两侧都不存在，则不添加位置说明
 
 标题映射：
+
 - `task` -> `任务文件`
 - `analysis` / `analysis-r{N}` -> `需求分析` / `需求分析（Round {N}）`
 - `plan` / `plan-r{N}` -> `技术方案` / `技术方案（Round {N}）`
@@ -186,6 +272,8 @@ task.md 评论格式：
 - `refinement` / `refinement-r{N}` -> `修复报告（Round 1）` / `修复报告（Round {N}）`
 - `summary` -> `交付摘要`
 
+补发评论同样不受 `has_triage` / `has_push` 限制。
+
 ## 需求复选框同步
 
 从 task.md 的 `## 需求` 段落提取已勾选的 `- [x]` 条目；如果没有，跳过。
@@ -193,10 +281,12 @@ task.md 评论格式：
 读取 Issue 当前正文：
 
 ```bash
-gh issue view {issue-number} --json body --jq '.body'
+gh issue view {issue-number} -R "$upstream_repo" --json body --jq '.body'
 ```
 
-按复选框文本匹配，将对应的 `- [ ] {text}` 单向替换为 `- [x] {text}`。只有正文实际变化时，才使用 `gh api` PATCH 更新完整 body。
+按复选框文本匹配，将对应的 `- [ ] {text}` 单向替换为 `- [x] {text}`。只有正文实际变化且 `has_triage=true` 时，才使用 `gh api` PATCH 更新完整 body。
+
+如果 `has_triage=false`，则跳过正文 PATCH，只更新 task 留言，由 bot 根据最新任务状态补位。
 
 ## Shell 安全规则
 

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

@@ -7,6 +7,7 @@ Read this file before `create-issue`, `implement-task`, or `create-pr` handles a
 - 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
+- Before any repository-scoped `gh api`, `gh issue edit`, or Issue lookup runs, the caller must resolve `upstream_repo` and `has_triage`
 - Only use milestones that actually exist in the repository; if a target milestone is unavailable, apply the fallback for that phase
 
 ## Branch Mode Detection
@@ -35,12 +36,14 @@ Priority:
 Suggested release-line query:
 
 ```bash
-gh api "repos/{owner}/{repo}/milestones?state=open&per_page=100" \
+gh api "repos/$upstream_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.
 
+Direct milestone writes are triage-gated. When the caller detected `has_triage=false`, omit `--milestone` and continue.
+
 ## Phase 2: `implement-task`
 
 Goal: narrow the Issue milestone from a release line to a concrete version when implementation starts.
@@ -60,15 +63,17 @@ Sequence:
 4. When a target concrete version is found, run:
 
 ```bash
-gh issue edit {issue-number} --milestone "{version}"
+if [ "$has_triage" = "true" ]; then
+  gh issue edit {issue-number} -R "$upstream_repo" --milestone "{version}"
+fi
 ```
 
-5. If the target milestone does not exist or the branch ancestry cannot be determined reliably, keep the original milestone unchanged
+5. If `has_triage=false`, 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" \
+gh api "repos/$upstream_repo/milestones?state=open&per_page=100" \
   --jq '.[].title'
 ```
 
@@ -94,9 +99,11 @@ Sequence:
 2. If the Issue has a milestone, run:
 
 ```bash
-gh pr edit {pr-number} --milestone "{milestone}"
+if [ "$has_triage" = "true" ]; then
+  gh pr edit {pr-number} --milestone "{milestone}"
+fi
 ```
 
-3. If the Issue has no milestone, skip PR milestone assignment
+3. If the Issue has no milestone, or `has_triage=false`, 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.github.zh-CN.md

@@ -7,6 +7,7 @@
 - milestone 在技能生命周期中逐步收窄：版本线 -> 具体版本 -> 复用
 - 任一步骤推断失败时都必须回退，不得阻塞技能执行
 - 如果 `gh` CLI 不可用、未认证，或 GitHub API 请求失败，跳过 milestone 处理并继续
+- 在执行 repo 级 `gh api`、`gh issue edit` 或 Issue 查询前，调用方必须先完成 `upstream_repo` / `has_triage` 检测
 - 只使用仓库中实际存在的 milestone；目标 milestone 不存在时按各阶段 fallback 处理
 
 ## 分支模式检测
@@ -35,12 +36,14 @@ git branch -r | grep -v 'HEAD' | grep -E 'origin/[0-9]+\.[0-9]+\.x$'
 版本线查询建议：
 
 ```bash
-gh api "repos/{owner}/{repo}/milestones?state=open&per_page=100" \
+gh api "repos/$upstream_repo/milestones?state=open&per_page=100" \
   --jq '.[].title'
 ```
 
 只匹配 `X.Y.x` 格式的标题；按 major、minor 数值升序取最小版本线。
 
+Milestone 设置属于 `has_triage` 权限范围；如果调用方检测到 `has_triage=false`，则省略 `--milestone` 并继续。
+
 ## 阶段 2：`implement-task`
 
 目标：开始开发时，把 Issue milestone 从版本线收窄到具体版本。
@@ -60,15 +63,17 @@ gh api "repos/{owner}/{repo}/milestones?state=open&per_page=100" \
 4. 找到目标具体版本后，执行：
 
 ```bash
-gh issue edit {issue-number} --milestone "{version}"
+if [ "$has_triage" = "true" ]; then
+  gh issue edit {issue-number} -R "$upstream_repo" --milestone "{version}"
+fi
 ```
 
-5. 如果目标 milestone 不存在或无法可靠判断 -> 保持原 milestone 不变
+5. 如果 `has_triage=false`、目标 milestone 不存在，或无法可靠判断 -> 保持原 milestone 不变
 
 具体版本查询建议：
 
 ```bash
-gh api "repos/{owner}/{repo}/milestones?state=open&per_page=100" \
+gh api "repos/$upstream_repo/milestones?state=open&per_page=100" \
   --jq '.[].title'
 ```
 
@@ -94,9 +99,11 @@ git merge-base --is-ancestor origin/main HEAD
 2. Issue 有 milestone -> 执行：
 
 ```bash
-gh pr edit {pr-number} --milestone "{milestone}"
+if [ "$has_triage" = "true" ]; then
+  gh pr edit {pr-number} --milestone "{milestone}"
+fi
 ```
 
-3. Issue 没有 milestone -> 跳过，不设置 PR milestone
+3. Issue 没有 milestone，或 `has_triage=false` -> 跳过，不设置 PR milestone
 
 不要再使用 `task.md`、分支名、tag 或 `General Backlog` 为 PR 单独推断 milestone。

package/templates/.agents/rules/pr-sync.github.en.md

@@ -70,6 +70,8 @@ Use this canonical comment body template:
 
 Fetch existing comments through the Issues comments API, not the dedicated PR comments API.
 
+Before this section runs, the caller must resolve `upstream_repo` by following `.agents/rules/issue-pr-commands.md` / `.agents/rules/issue-sync.md`.
+
 Process:
 1. Fetch existing PR comments and locate the comment ID that starts with `<!-- sync-pr:{task-id}:summary -->`
 2. When rendering the body, always write the current `git rev-parse HEAD` result into `<!-- last-commit: {git-head-sha} -->`
@@ -80,7 +82,7 @@ Process:
 When updating an existing comment, use:
 
 ```bash
-gh api "repos/{owner}/{repo}/issues/comments/{comment-id}" -X PATCH -f body="$(cat <<'EOF'
+gh api "repos/$upstream_repo/issues/comments/{comment-id}" -X PATCH -f body="$(cat <<'EOF'
 {comment-body}
 EOF
 )"

package/templates/.agents/rules/pr-sync.github.zh-CN.md

@@ -70,6 +70,8 @@
 
 已有评论必须通过 Issues comments API 获取，而不是单独的 PR comments API。
 
+调用方在执行本章节前，必须先按 `.agents/rules/issue-pr-commands.md` / `.agents/rules/issue-sync.md` 完成 `upstream_repo` 检测。
+
 处理顺序：
 1. 获取 PR 上现有 comments，查找以 `<!-- sync-pr:{task-id}:summary -->` 开头的评论 ID
 2. 渲染评论正文时，始终写入当前 `git rev-parse HEAD` 的结果到 `<!-- last-commit: {git-head-sha} -->`
@@ -80,7 +82,7 @@
 更新已有评论时，使用如下模式：
 
 ```bash
-gh api "repos/{owner}/{repo}/issues/comments/{comment-id}" -X PATCH -f body="$(cat <<'EOF'
+gh api "repos/$upstream_repo/issues/comments/{comment-id}" -X PATCH -f body="$(cat <<'EOF'
 {comment-body}
 EOF
 )"