Use the mcporter CLI to list, configure, auth, and call MCP servers/tools directly (HTTP or stdio), including ad-hoc servers, config edits, and CLI/type generation.

2026-06-245

debate

tiancaiamao/ai

Orchestrate a real-time alternating debate between two subagents using ai serve/send. Judge controls rounds by prompting each agent in turn.

2026-06-235

planning

tiancaiamao/ai

任务规划与进度追踪。当任务有 5+ 步骤、多文件改动、或长执行链时使用。核心机制：用 checkbox 列表追踪进度，每完成一步立即更新，利用"重写列表"将完整任务清单重新注入 context。

2026-06-235

subagent

tiancaiamao/ai

使用 ai serve/send/watch/kill 控制子 agent 的通用指引。所有需要子 agent 的技能都应参考此技能，而非重复定义 spawn/cleanup 流程。

2026-06-215

name	review
description	Code review skill using codex-rs methodology with ai CLI
tools	["bash"]

Review Skill

使用 codex-rs 的 review 方法论执行代码审查。通过 ai serve + ai send + ai watch 运行独立的 review agent。

子 agent 生命周期遵循 subagent 技能： spawn → watch → cleanup（ai kill）。本技能不重复定义 spawn/watch/kill 流程。

⚠️ MUST：在执行任何子 agent 操作前，确认 subagent 技能已加载到当前上下文。如果未加载，先调用 find_skill 工具（参数 name="subagent", load=true）加载它。

使用方式

/skill:review 帮我 review 这个 pr https://github.com/tiancaiamao/ai/pull/42
/skill:review review 当前未提交的代码
/skill:review review commit abc123

支持的 Review 模式

模式	命令示例	说明
PR Review	`/skill:review review PR #42`	Review GitHub PR
Uncommitted	`/skill:review review 当前未提交的代码`	Review 本地未提交更改
Commit	`/skill:review review commit abc123`	Review 指定 commit
Base Branch	`/skill:review review against main`	Review 相对于 base branch 的变更

执行流程

解析用户输入 - 识别 review 模式（PR/commit/uncommitted）
确定项目目录和变更范围 - 解析出项目路径和需要 review 的变更描述
启动 review agent - 用 ai serve --id-file（tmux）启动独立 agent，传入 reviewer system prompt 和任务
发送任务 - 用 ai send 发送 review 指令
等待完成 - 用 ai watch --follow --pretty 实时观察直到 agent_end
读取结果 - agent 将 JSON 输出写到指定文件，读取并格式化展示

Diff 策略

先 --stat 看规模，再决定怎么读 diff。

Step 1: 看全貌

# 本地模式（commit / uncommitted）
git diff --stat <base>..<head>

# PR 模式 — 已 fetch 到 FETCH_HEAD（推荐，见下方"获取 PR 源分支"）
git diff --stat <base-sha>..FETCH_HEAD -- . ':!生成文件路径'

# PR 模式 — 无法 fetch 时退而用 GitHub API（只看文件列表，不含 diff 内容）
gh api repos/<owner>/<repo>/pulls/<pr>/files --paginate -q '.[] | "\(.filename)\t+\(.additions)\t-\(.deletions)"'

Step 2: 根据规模选策略

规模	策略
≤ ~300 行	单个 `git diff` 即可，一步读完
> ~300 行	逐文件 `git diff <base>..<head> -- <file>`，避免生成文件撑爆、截断后续内容
含生成文件	用 `-- . ':!pkg/parser/parser.go'` 等排除，或直接逐文件 diff

Step 3: 逐文件 diff 时的工作节奏

git diff <base>..<head> -- <file>   # 看改动
grep / read                         # 需要上下文时读源文件

不要把整个 diff 写入文件再 sed 分页读取——大 diff 里生成文件会占大量空间并截断后续内容。

生成文件检测

Review 时跳过生成文件，只看它的源文件。通用识别方法：

文件头部注释含 Code generated by ...、DO NOT EDIT、auto-generated
项目 AGENTS.md 或构建文档中标注的生成关系
Makefile / build target 里有生成步骤的输出文件
文件名模式：*_generated.go、mock_*.go、*.pb.go

常见生成关系举例：

模式	说明
`parser.go` from `parser.y`	yacc/bison 语法文件生成
`BUILD.bazel` from `make bazel_prepare`	构建系统自动生成
`mock_*.go` from `mockgen`	mock 代码生成
`*.pb.go` from `protoc`	protobuf 生成

Agent 应查阅项目的 AGENTS.md 或构建文档确认生成关系，项目特定的生成文件列表写在项目的 AGENTS.md 中。

获取 PR 源分支

需要本地 git diff 时，先 fetch PR 源分支：

# 1. 获取 fork repo 和分支名
gh api repos/<owner>/<repo>/pulls/<pr> --jq '.head.repo.full_name + " " + .head.ref'
# 输出: <user>/<repo> <branch>

# 2. 获取 base SHA
gh api repos/<owner>/<repo>/pulls/<pr> --jq '.base.sha'

# 3. Fetch 源分支（depth=1 即可，只要 diff）
git fetch https://github.com/<user>/<repo>.git <branch> --depth=1

# 4. 本地 diff
git diff <base-sha>..FETCH_HEAD -- <specific-file>

Review Role

审查使用专用的 reviewer role（~/.ai/roles/reviewer/，非 git 管理），已预置：

System Prompt: codex-rs 方法论（同 ~/.ai/skills/review/reviewer.md）
审查标准: 影响准确性/性能/安全性/可维护性的问题
优先级: P0 (阻塞) / P1 (紧急) / P2 (普通) / P3 (建议)
默认模型: opencode/deepseek-v4-flash（可在 ~/.ai/roles/reviewer/agent.yaml 中调整）
评论规范:
- 不超过 1 段落
- 代码块不超过 3 行
- 使用 suggestion block 提供修复建议
- 保持客观、不带恭维

输出格式

{
  "findings": [
    {
      "title": "[P1] Fix null pointer risk in auth handler",
      "body": "在 user.go:45 处，user 可能是 nil...",
      "confidence_score": 0.9,
      "priority": 1,
      "code_location": {
        "absolute_file_path": "/path/to/user.go",
        "line_range": {"start": 44, "end": 46}
      }
    }
  ],
  "overall_correctness": "patch is correct",
  "overall_explanation": "代码质量良好，无阻塞问题",
  "overall_confidence_score": 0.85
}

示例

Review PR

PR_NUM=42
REVIEW_OUT="/tmp/review-${PR_NUM}.json"

用 subagent 技能 Single Task 模式 spawn 子 agent，参数：

参数	值
role	`reviewer`
input	`'You are in the project directory. Review PR #'"${PR_NUM}"'. Steps: 1) Run gh pr diff '"${PR_NUM}"' to see the changes. 2) Read relevant source files for context. 3) Write your review findings as JSON to '"${REVIEW_OUT}"' following the output format in your system prompt.'`
name	`reviewer-$PR_NUM`
timeout	`10m`

完成后读取 $REVIEW_OUT，然后遵循 subagent 技能 Cleanup 阶段清理。

Review uncommitted changes

REVIEW_OUT="/tmp/review-local.json"

用 subagent 技能 Single Task 模式 spawn 子 agent，参数：

参数	值
role	`reviewer`
input	`'You are in the project directory. Review the current uncommitted changes. Steps: 1) Run git diff and/or git diff --cached to see the changes. 2) Read relevant source files for context. 3) Write your review findings as JSON to '"${REVIEW_OUT}"' following the output format in your system prompt.'`
name	`rev-local`
timeout	`10m`

Review a specific commit

COMMIT=abc123
REVIEW_OUT="/tmp/review-${COMMIT}.json"

用 subagent 技能 Single Task 模式 spawn 子 agent，参数：

参数	值
role	`reviewer`
input	`'You are in the project directory. Review commit '"${COMMIT}"'. Steps: 1) Run git show '"${COMMIT}"' to see the changes. 2) Read relevant source files for context. 3) Write your review findings as JSON to '"${REVIEW_OUT}"' following the output format in your system prompt.'`
name	`rev-${COMMIT}`
timeout	`10m`

⚠️ 常见错误

Spawn/watch/kill 的常见陷阱详见 subagent 技能 Common Pitfalls 章节。Review 特有的错误：

错误	说明
agent 失败后自己代做	⛔ 严格禁止。停下来向用户汇报，等待指示
传递 diff 文件路径	❌ 应传递项目目录，让 agent 自己 `git diff`
JSON 解析失败	尝试修复 JSON 或要求 agent 重试
id 文件为空	增加 sleep 等待时间或检查 serve 是否启动失败

关键规则

所有子 agent 操作遵循 subagent 技能 — spawn、watch、kill 的具体代码见 subagent 技能
传递项目目录而非 diff 文件 — 让 agent 自己 git diff 和读取源文件
解析 JSON 格式输出 — 从指定文件读取 JSON 结果
如果没有 findings — 输出 "No issues found"
overall_correctness — 只能是 "patch is correct" 或 "patch is incorrect"

常见问题

问题	解决方案
PR 不存在	提示用户检查 PR 链接
无变更	输出 "No changes to review"
Agent 超时	增加 `timeout` 值或简化 review 范围
JSON 解析失败	尝试修复 JSON 或要求 agent 重试
id 文件为空	增加 sleep 等待时间或检查 serve 是否启动失败

参考文档

~/.ai/roles/reviewer/ — Reviewer role 配置（agent.yaml + system prompt，非 git 管理）
~/.ai/skills/review/reviewer.md — Reviewer system prompt 源文件