@fitlab-ai/agent-infra 0.3.1 → 0.4.0

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

@@ -17,17 +17,17 @@ description: >
 - 纯数字（如 `123`）或 `#` + 数字（如 `#123`）-> 视为 issue number
 - `TASK-` 开头 -> 视为 task-id（现有格式）
 
-如果参数是 issue number，使用 Bash 搜索关联任务（注意：`.agent-workspace` 是隐藏目录，Grep/Glob 工具会跳过，必须使用 Bash）：
+如果参数是 issue number，使用 Bash 搜索关联任务（注意：`.agents/workspace` 是隐藏目录，Grep/Glob 工具会跳过，必须使用 Bash）：
 
 ```bash
 grep -rl "^issue_number: {issue-number}$" \
-  .agent-workspace/active/ \
-  .agent-workspace/blocked/ \
-  .agent-workspace/completed/ \
+  .agents/workspace/active/ \
+  .agents/workspace/blocked/ \
+  .agents/workspace/completed/ \
   2>/dev/null | head -1
 ```
 
-- 如果返回文件路径（如 `.agent-workspace/completed/TASK-xxx/task.md`），从路径中提取 `{task-id}` 和任务目录，继续执行步骤 2
+- 如果返回文件路径（如 `.agents/workspace/completed/TASK-xxx/task.md`），从路径中提取 `{task-id}` 和任务目录，继续执行步骤 2
 - 如果无返回，提示 `No task found associated with Issue #{issue-number}`
 
 如果参数是 task-id，继续执行步骤 2 的现有逻辑。
@@ -35,9 +35,9 @@ grep -rl "^issue_number: {issue-number}$" \
 ### 2. 验证任务存在
 
 对于 `task-id` 路径，按优先顺序搜索任务：
-- `.agent-workspace/active/{task-id}/task.md`
-- `.agent-workspace/blocked/{task-id}/task.md`
-- `.agent-workspace/completed/{task-id}/task.md`
+- `.agents/workspace/active/{task-id}/task.md`
+- `.agents/workspace/blocked/{task-id}/task.md`
+- `.agents/workspace/completed/{task-id}/task.md`
 
 注意：`{task-id}` 格式为 `TASK-{yyyyMMdd-HHmmss}`，例如 `TASK-20260306-143022`
 
@@ -105,17 +105,7 @@ gh pr view {pr-number} --json state,mergedAt
 
 根据返回结果识别 PR 是 `OPEN`、`MERGED` 还是其他状态。
 
-**d) 检测 Issue 状态**
-
-执行：
-
-```bash
-gh issue view {issue-number} --json state
-```
-
-记录 Issue 当前是 `OPEN` 还是 `CLOSED`。
-
-**e) 综合判定交付模式**
+**d) 综合判定交付模式**
 
 按以下优先级确定摘要模式：
 
@@ -149,30 +139,7 @@ gh label list --search "type:" --limit 1 --json name --jq 'length'
 - 返回 `0` -> 说明标准 label 体系缺失。先执行 `init-labels` 技能（幂等），然后重新执行本步骤
 - 返回非 `0` -> 继续后续 label 同步
 
-**b) 同步 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` |
-| 其他 | 跳过 |
-
-如果映射到具体 label，执行：
-
-```bash
-gh issue edit {issue-number} --add-label "{type-label}"
-```
-
-未映射到标准 type label 时跳过，不创建新 label。
-
-**c) 同步 status label**
+**b) 同步 status label**
 
 先读取 Issue 上已有的 `status:` labels：
 
@@ -203,7 +170,7 @@ gh issue edit {issue-number} --remove-label "{status-label}"
 gh issue edit {issue-number} --add-label "{status-label}"
 ```
 
-**d) 同步 in: label**
+**c) 同步 in: label**
 
 从实现报告（优先）或 `analysis.md` 中提取受影响文件路径：
 - 优先读取 `implementation.md` 与 `implementation-r*.md` 中 `## 修改文件` / `## 新建文件` 的文件列表
@@ -226,7 +193,7 @@ gh issue edit {issue-number} --add-label "in: {module}"
 
 5. **只添加，不移除**现有的 `in:` labels
 
-**e) 同步 Issue Type 字段**
+**d) 同步 Issue Type 字段**
 
 根据 task.md 的 `type` 字段映射 GitHub 原生 Issue Type：
 
@@ -408,11 +375,13 @@ summary_comment_id="$(
 )"
 ```
 
+在步骤 9 结束前，基于上述已发布/未发布结果，预先判断 `has_unpublished_artifacts`：是否存在任何尚未发布的非 `summary` 产物。该判断在步骤 10 执行期间保持不变，仅用于决定 `summary` 是原地更新还是删除后在尾部重建。
+
 幂等要求：
 - 第一次执行时，只发布当前已存在产物对应的文件评论
 - 第二次执行时，必须跳过已发布文件，只补发新增产物（例如 `implementation-r2`、`review-r2`）
 - 如果所有产物文件评论都已发布，且 `summary` 内容没有变化，则本次不发布任何新评论
-- 如果 `summary` 已发布但交付状态发生变化，只更新原评论，不新增第二条 summary 评论
+- 如果 `summary` 已发布但交付状态发生变化：当本次有新产物发布时，删除旧 `summary` 并在尾部重建；当本次无新产物发布时，原地更新原评论
 
 ### 10. 按时间线逐条发布上下文文件
 
@@ -473,16 +442,14 @@ summary_comment_id="$(
 |---|---|
 | 分支 | `{branch 或 N/A}` |
 | Commit | [`{commit-short}`](https://github.com/{owner}/{repo}/commit/{commit-hash}) 或 `N/A` |
-| PR | [#{pr-number}](https://github.com/{owner}/{repo}/pull/{pr-number}) 或 `N/A` |
-| Issue | `{issue-state}` |
 
 ---
 *由 AI 自动生成 · 内部追踪：{task-id}*
 ```
 
 模式化状态描述要求：
-- 模式 A：`✅ 已完成，代码已合入 {branch}`
-- 模式 B：`PR 阶段，当前为 #{pr-number}（OPEN 或 MERGED）`
+- 模式 A：`✅ 已完成`
+- 模式 B：`PR 阶段`
 - 模式 C：`开发中，当前步骤为 {current_step}`
 
 **b) 跳过已发布或缺失的产物**
@@ -502,19 +469,30 @@ EOF
 )"
 ```
 
-**d) 仅更新已有 summary 评论**
+**d) 发布或重建 summary 评论**
+
+`summary` 必须始终保持为最后一条评论。根据以下条件决定处理方式：
 
-如果 `summary` 标识已存在，且新生成内容与已有内容不同，则编辑原评论：
+- `summary` 不存在：按步骤 10c 发布新的 `summary` 评论
+- `summary` 已存在且 `has_unpublished_artifacts=true`：先删除旧 `summary` 评论，再按步骤 10c 发布新的 `summary` 评论
+- `summary` 已存在且 `has_unpublished_artifacts=false` 且新生成内容与已有内容不同：原地更新原评论
+- `summary` 已存在且 `has_unpublished_artifacts=false` 且内容相同：不做任何操作
+
+删除旧 `summary` 评论时，执行：
+
+```bash
+gh api "repos/$repo/issues/comments/{summary_comment_id}" -X DELETE
+```
+
+原地更新已有 `summary` 评论时，执行：
 
 ```bash
-gh api "repos/$repo/issues/comments/{comment-id}" -X PATCH -f body="$(cat <<'EOF'
+gh api "repos/$repo/issues/comments/{summary_comment_id}" -X PATCH -f body="$(cat <<'EOF'
 {comment-body}
 EOF
 )"
 ```
 
-如果内容相同，则不做任何操作。
-
 **e) 零操作场景**
 
 如果所有产物都已同步，且 `summary` 无需更新：
@@ -545,7 +523,7 @@ date "+%Y-%m-%d %H:%M:%S"
 - 更新评论：{数量}
 - 已跳过步骤：{步骤列表或 `无`}
 - 当前状态：{状态}
-- Labels：type={type-label 或 skipped}，status={status-label 或 cleared}，in:={新增数量}
+- Labels：status={status-label 或 cleared}，in:={新增数量}
 - Issue Type：{Bug / Feature / Task / skipped}
 - Milestone：{preserved / assigned / fallback / skipped}
 - Development：{已追加 Closes 关联 / 已存在关联 / 无 PR，跳过}

package/templates/.agents/skills/sync-pr/SKILL.md

@@ -14,9 +14,9 @@ Sync task progress to the related Pull Request. Argument: task-id.
 ### 1. Verify the Task Exists
 
 Search for the task in this order:
-- `.agent-workspace/active/{task-id}/task.md`
-- `.agent-workspace/completed/{task-id}/task.md`
-- `.agent-workspace/blocked/{task-id}/task.md`
+- `.agents/workspace/active/{task-id}/task.md`
+- `.agents/workspace/completed/{task-id}/task.md`
+- `.agents/workspace/blocked/{task-id}/task.md`
 
 Note: `{task-id}` format is `TASK-{yyyyMMdd-HHmmss}`, for example `TASK-20260306-143022`
 
@@ -84,7 +84,7 @@ Do not create new type labels.
 ### 6. Sync `in:` Labels
 
 Extract affected modules from implementation reports first, or analysis as fallback:
-- prefer file paths listed under `## 修改文件` / `## 新建文件` in `implementation.md` and `implementation-r{N}.md`
+- prefer file paths listed under `## Modified Files`, especially `### New Files` / `### Modified Files`, in `implementation.md` and `implementation-r{N}.md`
 - if implementation reports do not exist yet, fall back to affected files from analysis
 
 For each file path:
@@ -197,19 +197,7 @@ EOF
 
 5. If task.md does not contain `issue_number`, record `Development: N/A`
 
-### 9. Detect the Linked Issue State
-
-If task.md contains `issue_number`, run:
-
-```bash
-gh issue view {issue-number} --json state
-```
-
-Record whether the Issue is `OPEN` or `CLOSED`.
-
-If task.md does not contain `issue_number`, record `Issue: N/A`.
-
-### 10. Create or Update the Single Idempotent Review Summary
+### 9. Create or Update the Single Idempotent Review Summary
 
 Reuse the repository coordinates resolved in step 4, then fetch existing PR comments:
 
@@ -242,7 +230,6 @@ Summary requirements:
 - each key technical decision must be self-contained; do not reference internal document labels or jargon such as `Option A/B`
 - build a review-history table from `review.md`, `review-r{N}.md`, `refinement.md`, and `refinement-r{N}.md`
 - extract test results from `implementation.md` or `refinement.md`
-- include Issue state in the relationship table
 
 Recommended review-history columns:
 - `Round`
@@ -276,12 +263,6 @@ Candidate comment format:
 
 - {test-summary}
 
-### Relationships
-
-| Type | Content |
-|------|---------|
-| Issue | #{issue-number} ({state}) or `N/A` |
-
 ---
 *Generated by AI · Internal Tracking: {task-id}*
 ```
@@ -309,7 +290,7 @@ EOF
 )"
 ```
 
-### 11. Update Task Status
+### 10. Update Task Status
 
 Get the current time:
 
@@ -323,7 +304,7 @@ Add or update `last_synced_to_pr_at` in task.md with `{current-time}`.
   - {yyyy-MM-dd HH:mm:ss} — **Sync to PR** by {agent} — PR metadata synced, summary {created|updated|skipped} on PR #{pr-number}
   ```
 
-### 12. Inform the User
+### 11. Inform the User
 
 ```
 Progress synced to PR #{pr-number}.
@@ -333,7 +314,6 @@ Synchronized:
 - Milestone: {milestone-result}
 - Development: {development-result}
 - Summary: {created|updated|skipped}
-- Issue: {OPEN|CLOSED|N/A}
 
 View: https://github.com/{owner}/{repo}/pull/{pr-number}
 ```
@@ -343,7 +323,7 @@ View: https://github.com/{owner}/{repo}/pull/{pr-number}
 1. `sync-pr` is reviewer-facing. Keep one summary comment only, rather than publishing every artifact round to the PR.
 2. PR metadata sync must be safe to repeat. Re-runs should fill gaps without creating noise.
 3. Because Pull Requests share the Issue comments API, create the summary comment through `issues/{pr-number}/comments`.
-4. If `issue_number` is missing, record `Development: N/A` and `Issue: N/A` instead of failing the whole flow.
+4. If `issue_number` is missing, record `Development: N/A` instead of failing the whole flow.
 
 ## Error Handling
 

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

@@ -14,9 +14,9 @@ description: >
 ### 1. 验证任务存在
 
 按优先顺序搜索任务：
-- `.agent-workspace/active/{task-id}/task.md`
-- `.agent-workspace/completed/{task-id}/task.md`
-- `.agent-workspace/blocked/{task-id}/task.md`
+- `.agents/workspace/active/{task-id}/task.md`
+- `.agents/workspace/completed/{task-id}/task.md`
+- `.agents/workspace/blocked/{task-id}/task.md`
 
 注意：`{task-id}` 格式为 `TASK-{yyyyMMdd-HHmmss}`，例如 `TASK-20260306-143022`
 
@@ -197,19 +197,7 @@ EOF
 
 5. 如果 task.md 不包含 `issue_number`，记录 `Development: N/A`
 
-### 9. 探测关联 Issue 状态
-
-如果 task.md 包含 `issue_number`，执行：
-
-```bash
-gh issue view {issue-number} --json state
-```
-
-记录 Issue 当前是 `OPEN` 还是 `CLOSED`。
-
-如果 task.md 不包含 `issue_number`，记录 `Issue: N/A`。
-
-### 10. 生成或更新单条幂等审查摘要
+### 9. 生成或更新单条幂等审查摘要
 
 复用步骤 4 已获取的仓库坐标，并拉取 PR 已有评论：
 
@@ -242,7 +230,6 @@ summary_comment_id="$(
 - 关键技术决策的描述必须自包含，不要引用内部文档的编号或术语（如 `方案 A/B`）；审查者应能独立理解每条决策的含义
 - 从 `review.md`、`review-r{N}.md`、`refinement.md`、`refinement-r{N}.md` 构建审查历程表格
 - 从 `implementation.md` 或 `refinement.md` 的测试章节提取测试结果
-- 在关联表格中记录 Issue 状态
 
 审查历程表格建议字段：
 - `轮次`
@@ -276,12 +263,6 @@ summary_comment_id="$(
 
 - {test-summary}
 
-### 关联
-
-| 类型 | 内容 |
-|------|------|
-| Issue | #{issue-number}（{state}）或 `N/A` |
-
 ---
 *由 AI 自动生成 · 内部追踪：{task-id}*
 ```
@@ -309,7 +290,7 @@ EOF
 )"
 ```
 
-### 11. 更新任务状态
+### 10. 更新任务状态
 
 获取当前时间：
 
@@ -323,7 +304,7 @@ date "+%Y-%m-%d %H:%M:%S"
   - {yyyy-MM-dd HH:mm:ss} — **Sync to PR** by {agent} — PR metadata synced, summary {created|updated|skipped} on PR #{pr-number}
   ```
 
-### 12. 告知用户
+### 11. 告知用户
 
 ```
 进度已同步到 PR #{pr-number}。
@@ -333,7 +314,6 @@ date "+%Y-%m-%d %H:%M:%S"
 - Milestone：{milestone-result}
 - Development：{development-result}
 - Summary：{created|updated|skipped}
-- Issue：{OPEN|CLOSED|N/A}
 
 查看：https://github.com/{owner}/{repo}/pull/{pr-number}
 ```
@@ -343,7 +323,7 @@ date "+%Y-%m-%d %H:%M:%S"
 1. `sync-pr` 面向代码审查者，只维护一条 reviewer-facing summary 评论，不逐轮发布完整产物。
 2. PR 元数据同步必须可重复执行；重复执行时仅补齐缺失信息，不制造额外噪音。
 3. 由于 Pull Request 共享 Issue 评论接口，summary 评论应使用 `issues/{pr-number}/comments` API 创建。
-4. 如果 `issue_number` 缺失，Development 和 Issue 状态探测都应记录为 `N/A`，不要让整个流程失败。
+4. 如果 `issue_number` 缺失，Development 应记录为 `N/A`，不要让整个流程失败。
 
 ## 错误处理
 

package/templates/.agents/skills/update-agent-infra/SKILL.md

@@ -28,12 +28,12 @@ Execute the following command to handle all deterministic steps at once:
 node .agents/skills/update-agent-infra/scripts/sync-templates.js
 ```
 
-The script reads `.airc.json` (including `templateSource`, default `templates/`) and automatically performs:
-- git pull to fetch latest templates
-- File registry sync (`defaults.json` → `.airc.json`)
+The script reads `.agents/.airc.json` (including `templateSource`, default `templates/`) and automatically performs:
+- detect the template source version
+- File registry sync (`defaults.json` → `.agents/.airc.json`)
 - All managed files (language selection → exclude merged/ejected → placeholder rendering → overwrite)
 - Ejected files (create only on first install)
-- `.airc.json` update (`templateVersion`, file lists)
+- `.agents/.airc.json` update (`templateVersion`, file lists)
 
 The script outputs JSON to stdout. Parse and record the report.
 
@@ -46,14 +46,14 @@ The script outputs JSON to stdout. Parse and record the report.
   - Each item has `target` (project-relative path) and `template` (template-root-relative path)
 - `registryAdded`: newly added file registry entries
 - `selfUpdate`: whether this is a self-update scenario
-- `configUpdated`: whether `.airc.json` was updated
+- `configUpdated`: whether `.agents/.airc.json` was updated
 
 ## Phase B: Process merged files (AI intelligent merge)
 
 Process each item in the report's `merged.pending` list:
 
 1. Read the template file from `<templateRoot>/<template>`
-2. Render placeholders: replace double-brace `project` and `org` placeholders with actual values from .airc.json
+2. Render placeholders: replace double-brace `project` and `org` placeholders with actual values from .agents/.airc.json
 3. Read the current local file (`<project-root>/<target>`)
 
 **If the local file does not exist** (first-time setup), write the rendered

package/templates/.agents/skills/update-agent-infra/SKILL.zh-CN.md

@@ -24,12 +24,12 @@ description: >
 node .agents/skills/update-agent-infra/scripts/sync-templates.js
 ```
 
-脚本读取 `.airc.json`（含 `templateSource`，默认 `templates/`），自动完成：
-- git pull 拉取最新模板
-- 同步文件注册表（`defaults.json` → `.airc.json`）
+脚本读取 `.agents/.airc.json`（含 `templateSource`，默认 `templates/`），自动完成：
+- 检测模板源版本
+- 同步文件注册表（`defaults.json` → `.agents/.airc.json`）
 - 处理所有 managed 文件（语言选择 → 排除 merged/ejected → 占位符渲染 → 覆盖写入）
 - 处理 ejected 文件（仅首次安装时创建）
-- 更新 `.airc.json`（`templateVersion`、文件列表）
+- 更新 `.agents/.airc.json`（`templateVersion`、文件列表）
 
 脚本输出 JSON 到 stdout，解析并记录报告内容。
 
@@ -42,14 +42,14 @@ node .agents/skills/update-agent-infra/scripts/sync-templates.js
   - 每项包含 `target`（项目中的目标路径）和 `template`（模板根目录下的相对路径）
 - `registryAdded`：新增的文件注册条目
 - `selfUpdate`：是否为自更新模式
-- `configUpdated`：`.airc.json` 是否已更新
+- `configUpdated`：`.agents/.airc.json` 是否已更新
 
 ## 阶段 B：处理 merged 文件（AI 智能合并）
 
 根据报告中 `merged.pending` 列表，逐个文件处理。对于每个条目：
 
 1. 从 `<templateRoot>/<template>` 读取模板文件
-2. 渲染占位符：将双花括号包裹的 `project` 和 `org` 占位符替换为 .airc.json 中的实际值
+2. 渲染占位符：将双花括号包裹的 `project` 和 `org` 占位符替换为 .agents/.airc.json 中的实际值
 3. 读取本地当前文件（`<项目根>/<target>`）
 
 **如果本地文件不存在**（首次安装），直接写入渲染后的模板，跳过合并。