@fitlab-ai/agent-infra 0.5.6 → 0.5.8

package/templates/.agents/README.zh-CN.md

@@ -108,7 +108,7 @@
 | `status:` | Yes | — | PR 有自身状态流转（Open / Draft / Merged / Closed）；Issue 使用 `status:` label 标记等待反馈、已确认等项目管理状态 |
 | `in:` | Yes | Yes | Issue 和 PR 均可按模块筛选 |
 
-默认 GitHub 配置下，可使用 `/init-labels` 命令一次性创建标准 labels。
+使用 `/init-labels` 命令可通过平台适配器一次性创建标准 labels。
 
 ## 私有平台扩展
 
@@ -120,6 +120,27 @@
 4. 如果你维护的是模板源码分支或私有 fork，需要先补齐对应的 `.{platform}.` 模板变体，再把该平台标识加入模板同步逻辑。
 5. 在正式推广前，先用一个测试任务完整验证工作流和 gate 校验。
 
+## 外部模板与 Skill 源
+
+团队可以在 `.agents/.airc.json` 中配置外部模板源和共享 skill 源，用于接入私有平台模板、私有规则和团队维护的自定义 skill：
+
+```json
+{
+  "templates": {
+    "sources": [
+      { "type": "local", "path": "~/private-templates" }
+    ]
+  },
+  "skills": {
+    "sources": [
+      { "type": "local", "path": "~/private-skills" }
+    ]
+  }
+}
+```
+
+模板源优先级为内置模板优先，外部模板只做补充；多个外部模板源之间，后面的 source 覆盖前面的 source。同步报告会在 `templateSources.conflicts` 中列出被忽略的同名文件。外部模板和 skill 可能包含会被 AI 工作流执行的脚本，只配置可信路径。
+
 ## 自定义 Skills
 
 项目可以在内置任务工作流之外增加自己的 skill。
@@ -156,7 +177,7 @@ args: "<task-id>"   # 可选
 {
   "skills": {
     "sources": [
-      { "type": "local", "path": "~/company-skills" }
+      { "type": "local", "path": "~/private-skills" }
     ]
   }
 }
@@ -172,6 +193,54 @@ args: "<task-id>"   # 可选
 - 自定义 source 不能覆盖内置 skill；如果与内置 skill 同名，会跳过该 source skill
 - 如果项目必须接管某个内置 skill 或命令，请使用 `files.ejected`
 
+## 自定义 TUI 配置
+
+当团队使用的 AI TUI 不属于内置命令目标时，可以在 `.agents/.airc.json` 顶层配置 `customTUIs` 数组。该配置用于让 agent-infra 输出正确的下一步命令，并通过学习自定义 TUI 目录中的既有命令文件，为项目自定义 skill 生成同格式命令。
+
+| 字段 | 必填 | 含义 |
+|------|------|------|
+| `name` | 是 | 报告和下一步提示中展示的工具名称，例如 `Acme TUI`。 |
+| `dir` | 是 | 相对项目根目录的命令目录，例如 `.acme/commands`。路径必须位于项目根目录内。 |
+| `invoke` | 是 | 面向用户展示的命令模板，用于生成下一步提示。 |
+
+`invoke` 支持的占位符：
+
+| 占位符 | 替换为 | 示例 |
+|--------|--------|------|
+| `${skillName}` | skill 命令名，例如 `review-task` 或 `commit`。 | `acme ${skillName}` -> `acme review-task` |
+| `${projectName}` | `.airc.json` 中的 `project` 值，适用于带命名空间的命令。 | `/${projectName}:${skillName}` -> `/agent-infra:review-task` |
+
+不带命名空间的自定义 TUI：
+
+```json
+{
+  "customTUIs": [
+    {
+      "name": "Acme TUI",
+      "dir": ".acme/commands",
+      "invoke": "acme ${skillName}"
+    }
+  ]
+}
+```
+
+带命名空间的自定义 TUI：
+
+```json
+{
+  "project": "agent-infra",
+  "customTUIs": [
+    {
+      "name": "Internal Gemini",
+      "dir": ".internal-gemini/commands",
+      "invoke": "/${projectName}:${skillName}"
+    }
+  ]
+}
+```
+
+`customTUIs` 每个条目对应一个自定义 TUI。若希望 `update-agent-infra` 为自定义 skill 生成命令文件，请在 `dir` 中保留至少一个引用内置 skill 路径的既有命令文件，例如 `.agents/skills/analyze-task/SKILL.md`；agent-infra 会以该文件作为格式参考。
+
 ## Skill 编写规范
 
 编写或维护 `.agents/skills/*/SKILL.md` 及其模板时，步骤编号遵循以下规则：

package/templates/.agents/rules/issue-pr-commands.en.md

@@ -0,0 +1,5 @@
+# Issue and PR Commands
+
+This code platform does not provide built-in issue or pull request commands.
+
+Platform-specific automation is skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates. Keep local task artifacts as the source of truth, or install a platform-specific template pack before running the workflow.

package/templates/.agents/rules/issue-pr-commands.github.en.md

@@ -22,6 +22,44 @@ Before any later `gh issue` or `gh api "repos/..."` call, follow `.agents/rules/
 - keep `gh pr *` commands on the current repository without adding `-R`
 - keep organization-scoped commands such as `gh api "orgs/{owner}/..."` unchanged
 
+## Issue Template Detection
+
+Detect GitHub Issue Forms with:
+
+```bash
+rg --files .github/ISSUE_TEMPLATE -g '*.yml' -g '!config.yml'
+```
+
+Read matching form files locally before creating the Issue. If the directory is missing or no form matches the task, use the caller's fallback body format.
+
+Typical candidate templates:
+- `bug_report.yml` for bug work
+- `question.yml` for question or investigation work
+- `feature_request.yml` for feature work
+- `documentation.yml` for documentation work
+- `other.yml` as the general fallback
+
+For GitHub Issue Forms, inspect the matched form's:
+- `name`
+- `type:`
+- `labels:`
+- `body:`
+
+Field handling rules:
+- `textarea` and `input`: use `attributes.label` as the markdown heading and fill values from task.md
+- `markdown`: skip template explanation prose
+- `dropdown` and `checkboxes`: skip
+- when task.md lacks a suitable value, write `N/A`
+
+Suggested field mapping:
+
+| Template field hint | task.md source |
+|---|---|
+| `summary`, `title` | task title |
+| `description`, `problem`, `what happened`, `issue-description`, `current-content` | task description |
+| `solution`, `requirements`, `steps`, `suggested-content`, `impact`, `context`, `alternatives`, `expected` | requirements list |
+| other `textarea` / `input` fields | task description, otherwise `N/A` |
+
 ## Read and Create Issues
 
 Read an Issue:
@@ -82,6 +120,28 @@ Read Issue comments or search for existing hidden markers:
 gh api "repos/$upstream_repo/issues/{issue-number}/comments" --paginate
 ```
 
+## PR Template and Metadata Helpers
+
+Read a repository PR template when present:
+
+```bash
+cat .github/PULL_REQUEST_TEMPLATE.md
+```
+
+Review recent merged PRs for style:
+
+```bash
+gh pr list --limit 3 --state merged --json number,title,body
+```
+
+Verify that standard type labels exist before PR metadata sync:
+
+```bash
+gh label list --search "type:" --limit 1 --json name --jq 'length'
+```
+
+If the result is `0`, run `init-labels` before retrying PR metadata sync.
+
 ## Read and Create PRs
 
 Read a PR:

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

@@ -22,6 +22,44 @@ gh repo view --json nameWithOwner
 - `gh pr *` 命令保持作用于当前仓库，不额外加 `-R`
 - `gh api "orgs/{owner}/..."` 这类 org 级命令保持不变
 
+## Issue 模板检测
+
+使用以下命令检测 GitHub Issue Forms：
+
+```bash
+rg --files .github/ISSUE_TEMPLATE -g '*.yml' -g '!config.yml'
+```
+
+创建 Issue 前先读取匹配的 form 文件。目录不存在或没有匹配 form 时，使用调用方定义的 fallback 正文格式。
+
+常见候选模板：
+- `bug_report.yml`：bug 工作
+- `question.yml`：问题或排查工作
+- `feature_request.yml`：功能工作
+- `documentation.yml`：文档工作
+- `other.yml`：通用 fallback
+
+对 GitHub Issue Forms，检查匹配 form 的：
+- `name`
+- `type:`
+- `labels:`
+- `body:`
+
+字段处理规则：
+- `textarea` 和 `input`：使用 `attributes.label` 作为 markdown 标题，并从 task.md 填充值
+- `markdown`：跳过模板说明文案
+- `dropdown` 和 `checkboxes`：跳过
+- task.md 缺少合适值时，写入 `N/A`
+
+建议字段映射：
+
+| 模板字段提示 | task.md 来源 |
+|---|---|
+| `summary`, `title` | 任务标题 |
+| `description`, `problem`, `what happened`, `issue-description`, `current-content` | 任务描述 |
+| `solution`, `requirements`, `steps`, `suggested-content`, `impact`, `context`, `alternatives`, `expected` | 需求列表 |
+| 其他 `textarea` / `input` 字段 | 任务描述，否则 `N/A` |
+
 ## Issue 读取与创建
 
 读取 Issue：
@@ -82,6 +120,28 @@ gh issue close {issue-number} -R "$upstream_repo" --reason "{reason}"
 gh api "repos/$upstream_repo/issues/{issue-number}/comments" --paginate
 ```
 
+## PR 模板与元数据辅助命令
+
+存在仓库 PR 模板时读取：
+
+```bash
+cat .github/PULL_REQUEST_TEMPLATE.md
+```
+
+参考最近合并的 PR 风格：
+
+```bash
+gh pr list --limit 3 --state merged --json number,title,body
+```
+
+PR 元数据同步前验证标准 type labels 是否存在：
+
+```bash
+gh label list --search "type:" --limit 1 --json name --jq 'length'
+```
+
+如果结果是 `0`，先运行 `init-labels`，再重试 PR 元数据同步。
+
 ## PR 读取与创建
 
 读取 PR：

package/templates/.agents/rules/issue-pr-commands.zh-CN.md

@@ -0,0 +1,5 @@
+# Issue 和 PR 命令
+
+当前代码平台未内置 Issue 或 Pull Request 命令支持。
+
+自定义平台会跳过平台专属自动化，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板。请以本地任务产物作为事实来源，或先安装平台专属模板包再运行工作流。

package/templates/.agents/rules/issue-sync.en.md

@@ -0,0 +1,19 @@
+# Issue Sync
+
+## Marker Registry
+
+These hidden markers are the canonical registry for Issue synchronization:
+
+| Key | Marker |
+|---|---|
+| `task` | `<!-- sync-issue:{task-id}:task -->` |
+| `artifact` | `<!-- sync-issue:{task-id}:{artifact-stem} -->` |
+| `artifactChunk` | `<!-- sync-issue:{task-id}:{artifact-stem}:{part}/{total} -->` |
+| `summary` | `<!-- sync-issue:{task-id}:summary -->` |
+| `cancel` | `<!-- sync-issue:{task-id}:cancel -->` |
+
+Callers should refer to the marker key in skill prose and keep concrete marker strings in this rule or the platform adapter defaults.
+
+This code platform does not provide built-in issue synchronization.
+
+Issue metadata, labels, milestones, assignees, and comments are skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates and platform adapters. Continue writing local task artifacts normally.

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

@@ -1,5 +1,19 @@
 # Issue Sync Rules
 
+## Marker Registry
+
+These hidden markers are the canonical registry for Issue synchronization:
+
+| Key | Marker |
+|---|---|
+| `task` | `<!-- sync-issue:{task-id}:task -->` |
+| `artifact` | `<!-- sync-issue:{task-id}:{artifact-stem} -->` |
+| `artifactChunk` | `<!-- sync-issue:{task-id}:{artifact-stem}:{part}/{total} -->` |
+| `summary` | `<!-- sync-issue:{task-id}:summary -->` |
+| `cancel` | `<!-- sync-issue:{task-id}:cancel -->` |
+
+Callers should refer to the marker key in skill prose and keep concrete marker strings in this rule or the platform adapter defaults.
+
 Read this file before a task skill updates a GitHub Issue.
 
 ## Upstream Repository Detection

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

@@ -1,5 +1,19 @@
 # Issue 同步规则
 
+## Marker 注册表
+
+以下隐藏标记是 Issue 同步的唯一权威注册表：
+
+| Key | Marker |
+|---|---|
+| `task` | `<!-- sync-issue:{task-id}:task -->` |
+| `artifact` | `<!-- sync-issue:{task-id}:{artifact-stem} -->` |
+| `artifactChunk` | `<!-- sync-issue:{task-id}:{artifact-stem}:{part}/{total} -->` |
+| `summary` | `<!-- sync-issue:{task-id}:summary -->` |
+| `cancel` | `<!-- sync-issue:{task-id}:cancel -->` |
+
+Skill 正文应引用 marker key，具体 marker 字符串只保留在本规则或平台适配器默认值中。
+
 在任务技能需要更新 GitHub Issue 时先读取本文件。
 
 ## Upstream 仓库检测

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

@@ -0,0 +1,19 @@
+# Issue 同步
+
+## Marker 注册表
+
+以下隐藏标记是 Issue 同步的唯一权威注册表：
+
+| Key | Marker |
+|---|---|
+| `task` | `<!-- sync-issue:{task-id}:task -->` |
+| `artifact` | `<!-- sync-issue:{task-id}:{artifact-stem} -->` |
+| `artifactChunk` | `<!-- sync-issue:{task-id}:{artifact-stem}:{part}/{total} -->` |
+| `summary` | `<!-- sync-issue:{task-id}:summary -->` |
+| `cancel` | `<!-- sync-issue:{task-id}:cancel -->` |
+
+Skill 正文应引用 marker key，具体 marker 字符串只保留在本规则或平台适配器默认值中。
+
+当前代码平台未内置 Issue 同步支持。
+
+自定义平台会跳过 Issue 元数据、标签、里程碑、负责人和评论同步，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板和平台适配器。请继续正常写入本地任务产物。

package/templates/.agents/rules/label-milestone-setup.en.md

@@ -0,0 +1,5 @@
+# Label and Milestone Setup
+
+This code platform does not provide built-in label or milestone setup.
+
+Initialization of remote labels and milestones is skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates and scripts. Local task workflow files remain usable without remote metadata setup.

package/templates/.agents/rules/label-milestone-setup.github.en.md

@@ -43,6 +43,16 @@ Update a milestone:
 gh api "repos/$repo/milestones/{number}" -X PATCH -f state="{state}" -f description="{description}"
 ```
 
+## Error Prompt Templates
+
+Use these normalized prompts when the GitHub setup scripts fail:
+
+| Condition | Prompt |
+|---|---|
+| CLI missing | GitHub CLI (`gh`) is not installed |
+| Authentication failed | `GitHub CLI is not authenticated` |
+| API rate limit | `GitHub API rate limit reached, please retry later` |
+
 ## Constraints
 
 - use label names as the idempotency key

package/templates/.agents/rules/label-milestone-setup.github.zh-CN.md

@@ -43,6 +43,16 @@ gh api "repos/$repo/milestones" -f title="{title}" -f description="{description}
 gh api "repos/$repo/milestones/{number}" -X PATCH -f state="{state}" -f description="{description}"
 ```
 
+## 错误提示模板
+
+GitHub 初始化脚本失败时使用以下标准提示：
+
+| 条件 | 提示 |
+|---|---|
+| CLI 缺失 | GitHub CLI (`gh`) is not installed |
+| 认证失败 | `GitHub CLI is not authenticated` |
+| API 限流 | `GitHub API rate limit reached, please retry later` |
+
 ## 约束
 
 - label 以名称作为幂等键

package/templates/.agents/rules/label-milestone-setup.zh-CN.md

@@ -0,0 +1,5 @@
+# Label 和 Milestone 初始化
+
+当前代码平台未内置标签或里程碑初始化支持。
+
+自定义平台会跳过远端标签和里程碑初始化，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板和脚本。即使没有远端元数据初始化，本地任务工作流文件仍可使用。

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

@@ -0,0 +1,5 @@
+# Milestone Inference
+
+This code platform does not provide built-in milestone inference.
+
+Milestone narrowing and reuse are skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates. Do not block task progress when no platform-specific milestone implementation is available.

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

@@ -0,0 +1,5 @@
+# Milestone 推断
+
+当前代码平台未内置里程碑推断支持。
+
+自定义平台会跳过里程碑收窄和复用逻辑，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板。没有平台专属里程碑实现时，不要阻塞任务推进。

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

@@ -0,0 +1,5 @@
+# PR Sync
+
+This code platform does not provide built-in pull request synchronization.
+
+PR creation, metadata updates, labels, milestones, assignees, and summary comments are skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates and adapters. Keep local task artifacts up to date.

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

@@ -0,0 +1,5 @@
+# PR 同步
+
+当前代码平台未内置 Pull Request 同步支持。
+
+自定义平台会跳过 PR 创建、元数据更新、标签、里程碑、负责人和摘要评论同步，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板和适配器。请保持本地任务产物更新。

package/templates/.agents/rules/release-commands.en.md

@@ -0,0 +1,5 @@
+# Release Commands
+
+This code platform does not provide built-in release commands.
+
+Remote release automation is skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates and scripts. Continue using local release artifacts or your platform-specific release process.

package/templates/.agents/rules/release-commands.github.en.md

@@ -21,6 +21,22 @@ When needed, read the linked Issue:
 gh issue view {issue-number} --json number,title,labels,url
 ```
 
+## Contributor Mapping Helpers
+
+Merged PR queries used for release notes should include authors when contributors are needed:
+
+```bash
+gh pr list --state merged --base "{branch}" --json number,title,mergedAt,labels,author
+```
+
+Linked Issue queries used for reporter attribution should include the author:
+
+```bash
+gh issue view {issue-number} --json number,title,labels,url,author
+```
+
+Map GitHub no-reply emails with this rule: if `Name <email>` contains an email matching `(\d+\+)?(\S+?)@users\.noreply\.github\.com`, use the second capture group lowercased as the login. This covers both `{id}+{login}@users.noreply.github.com` and `{login}@users.noreply.github.com`.
+
 ## Create a Draft Release
 
 ```bash

package/templates/.agents/rules/release-commands.github.zh-CN.md

@@ -21,6 +21,22 @@ gh pr list --state merged --base "{branch}" --json number,title,mergedAt,labels
 gh issue view {issue-number} --json number,title,labels,url
 ```
 
+## Contributor 映射辅助规则
+
+release notes 需要 contributors 时，已合并 PR 查询应包含 author：
+
+```bash
+gh pr list --state merged --base "{branch}" --json number,title,mergedAt,labels,author
+```
+
+关联 Issue 用于 reporter 归因时，查询应包含 author：
+
+```bash
+gh issue view {issue-number} --json number,title,labels,url,author
+```
+
+GitHub no-reply 邮箱映射规则：如果 `Name <email>` 中的 email 匹配 `(\d+\+)?(\S+?)@users\.noreply\.github\.com`，使用第二个捕获组的小写形式作为 login。该规则同时覆盖 `{id}+{login}@users.noreply.github.com` 和 `{login}@users.noreply.github.com`。
+
 ## 创建 Draft Release
 
 ```bash

package/templates/.agents/rules/release-commands.zh-CN.md

@@ -0,0 +1,5 @@
+# Release 命令
+
+当前代码平台未内置发布命令支持。
+
+自定义平台会跳过远端发布自动化，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板和脚本。请继续使用本地发布产物或你的平台专属发布流程。

package/templates/.agents/rules/security-alerts.en.md

@@ -0,0 +1,5 @@
+# Security Alerts
+
+This code platform does not provide built-in security alert integration.
+
+Code scanning and dependency alert import or close actions are skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates and adapters. Track security work through local task artifacts or a platform-specific integration.

package/templates/.agents/rules/security-alerts.zh-CN.md

@@ -0,0 +1,5 @@
+# 安全告警
+
+当前代码平台未内置安全告警集成。
+
+自定义平台会跳过代码扫描和依赖告警的导入或关闭操作，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板和适配器。请通过本地任务产物或平台专属集成跟踪安全工作。