kiro — 下游 agent 委派规范

kiro 是独立的终端 AI agent，拥有完整的文件读写和命令执行能力。正确委派给它，可以解放主 agent 的 context，让 kiro 在更大范围内自主探索和实施。

调用脚本

~/.local/bin/kiro 已封装所有清理逻辑，直接使用：

# 默认模型（sonnet），静默执行，输出返回给 Cursor Shell
kiro "任务描述"

# 指定模型
kiro --model claude-haiku-4.5 "任务描述"

# 环境变量覆盖默认模型
KIRO_MODEL=claude-opus-4.6 kiro "任务描述"

# 在新 iTerm2 标签页中实时查看，同时阻塞直到完成并回传输出
kiro --iterm "任务描述"
kiro --iterm --model claude-opus-4.6 "任务描述"

两种模式的选择：

默认模式：输出返回给 Cursor，适合需要读取结果继续决策的场景
--iterm 模式：在当前 iTerm2 窗口开新 tab 实时展示彩色进度，同时阻塞等待完成后回传清洗后的输出给 Cursor；任务完成后显示倒计时提示，按空格立即关闭，60 秒后自动关闭；适合耗时长、想实时盯进度的任务

并行多任务写法（用 wait 零 token 阻塞，不要轮询）：

kiro --iterm "任务一" &
PID1=$!
kiro --iterm "任务二" &
PID2=$!
wait $PID1 $PID2
echo "全部完成"

模型选型

模型	适用场景
`claude-haiku-4.5`	文件统计、代码搜索、命令执行汇总等机械任务
`claude-sonnet-4.6`	模块结构分析、独立组件生成（默认）
`claude-opus-4.6`	多模块深度调研、需要跨文件推理的复杂分析

每次调用必须有明确模型，省略则 fallback 到旧版。

核心原则：委派目标，不委派实现

判断标准：你的 prompt 里不应出现大段具体实现代码。如果写了，说明你在自己实现，kiro 只是粘贴工具——还不如直接用 StrReplace。

❌ 错误：给 kiro 贴完整代码让它"写入第 430 行"
✅ 正确：告诉 kiro 目标和约束，让它自己读文件、定位、实现

原则：给目录，不给文件列表

委派调研任务时，给 kiro 目录路径，让它自己探索文件范围：

❌ 错误：
  "读取 A.vue、B.vue、C.vue 三个文件"
  （主 agent 预判了范围，漏掉子组件、composable、store 等关联文件）

✅ 正确：
  "探索 src/views 和 src/components/videoStudio 目录，
   找出视频生成模块涉及的所有相关文件，自行判断读取范围"

原则：复杂任务必须多轮，不能一气呵成

触发条件：prompt 里同时包含"读取/分析"和"修改/保存"，就必须拆轮。

❌ 一轮包揽：
  "读技能包 → 调研代码 → 直接改文件保存"
  （kiro 全程自跑，主 agent 完全没有介入点，方向错了才发现）

✅ 正确的多轮流程：

  第一轮（禁止改文件）→ kiro 调研 + audit，输出报告
       ↓
  主 agent 介入：审阅报告，决定做哪些/不做哪些/调整优先级
       ↓
  第二轮 → kiro 按批准方向实施
       ↓
  主 agent 验收：有问题打回重来

典型委派模式

模式一：调研先行

# 第一轮：只读不改，输出调研报告
kiro '探索 src/components/videoStudio 目录，找出所有子组件，
分析各组件的主要职责、对外 props/emit 接口，
输出模块结构概要，**禁止修改任何文件**'

# 主 agent 审阅后，第二轮再实施

模式二：自主 audit + 方案输出

# 让 kiro 读技能包、调研代码，只输出问题清单和建议，不动文件
kiro '先读取 /path/to/SKILL.md，再探索 src/views 目录，
对照技能包原则列出所有 UI 问题，按 P0/P1/P2 分级，
每个问题写修复建议（一句话），**禁止修改任何文件**'

模式三：批量机械操作

# 适合一次性、边界清晰的改动
kiro --model claude-haiku-4.5 \
  '统计 src 下所有 .vue 文件行数，按从大到小排列'

模式四：独立模块生成

kiro '按以下接口规范生成工具函数，保存到 src/utils/format.ts：
- formatDuration(ms: number): string  // 毫秒 → "1分30秒"
- formatFileSize(bytes: number): string  // 字节 → "1.2 MB"
使用 TypeScript，加中文注释，文件头署名 guohao.cheng'

不适合委派给 kiro 的场景

需要感知当前对话上下文（kiro 是全新会话，看不到历史）
需要用户确认后才能继续的交互式决策
有 lint 错误需要反复迭代修复（主 agent 自己用 StrReplace 更可靠）
架构决策（kiro 做执行，主 agent 做决策）

注意事项

任务描述说清楚目标、约束，不写实现代码
kiro 生成的代码需要主 agent 审查后再使用
默认模式单次耗时 10–90 秒，需要后台运行时用 block_until_ms: 0
--iterm 模式本身是阻塞的（内部 wait），后台并行时加 & 然后用 wait $PID 等待
多个相互依赖的任务串行调用；相互独立的任务可并行启动
--iterm 模式会自动过滤 kiro 的 trust 横幅和 ANSI 颜色码，回传给 Cursor 的输出是干净文本

kiro-cli