企业官网建设流程全解析

本篇指南基于 Plannotator 官方文档 Kiro CLI 及其配套源码包 apps/kiro-cli，完整讲解 Kiro CLI 如何以「按需调用的可安装 skills + 示例自定义 agent」的方式接入 Plannotator：包括自动检测与安装流程、每个已安装 skill 的实际命令形态、plannotator自定义 agent 的完整 JSON 配置及其逐字段原理，以及应对 Kiro schema 演变的适配建议。读完你可以零配置地为 Kiro CLI 装上 Plannotator 的代码评审与文档批注能力，并能自行编写一个复用这些 skill 的 agent。

接入方式总览：按需调用的 Skills，而非后台钩子

Plannotator 支持 Kiro CLI 的方式是「可安装的 skills 加上一个示例自定义 agent」。skills 在需要时由模型或用户显式调用，没有任何后台 hooks——这与 Plannotator 集成 Droid 和 Copilot CLI 的模式一致。

从源码结构看，Kiro 集成是一个独立的源码包 apps/kiro-cli，其中的文件由主安装器 scripts/install.sh 消费，不存在单独的 Kiro 安装器：Kiro 用户与所有其他 agent 用户执行同一条安装命令即可。该包包含三类内容：

• skills/ — Kiro 专属 skill 包（plannotator-review、plannotator-annotate），各自把PLANNOTATOR_ORIGIN=kiro-cli硬编码进命令；
• agents/plannotator.json — 示例 Kiro 自定义 agent，通过skill://resources 暴露 Plannotator 全部 skills，并限定plannotator命令的shell工具；
• 共享扩展 skills（plannotator-setup-goal、plannotator-visual-explainer）直接从仓库的apps/skills/extra/目录安装，不在 Kiro 包里重复维护。

README 中有一条明确的源码维护约定：Kiro 专属的 skill 副本是故意独立的（因为要硬编码PLANNOTATOR_ORIGIN=kiro-cli），被豁免于「单一来源」原则，不能用apps/skills/core/下的核心副本替换。

安装：自动检测 Kiro，一条命令完成

自动检测逻辑

Kiro 是自动检测的：当运行安装器时，只要~/.kiro目录存在，或kiro-cli在 PATH 中，Kiro skills 就会自动安装——这是 Codex 和 Gemini 使用的同一套约定，无需任何额外参数。安装器中的检测逻辑见 scripts/install.sh：

kiro_available=0 if command -v kiro-cli >/dev/null 2>&1 || [ -d "$HOME/.kiro" ]; then kiro_available=1

自动检测在所有平台生效，使用你操作系统对应的安装器即可：

macOS / Linux / WSL：

curl -fsSL https://plannotator.ai/install.sh | bash

Windows PowerShell：

irm https://plannotator.ai/install.ps1 | iex

Windows CMD：

curl -fsSL https://plannotator.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

安装到哪些位置

安装器把 Kiro skills 写入~/.kiro/skills，把 Plannotator agent 写入~/.kiro/agents/plannotator.json。如果安装 Plannotator之后才安装 Kiro，只需重新运行一次安装器即可补装。

从 scripts/install.sh 的安装块可以看到完整的落盘行为：

if [ "$kiro_available" -eq 1 ] && [ "$skip_kiro" -eq 0 ] && [ -d "apps/kiro-cli/skills" ]; then mkdir -p "$KIRO_SKILLS_DIR" # Kiro-specific skills (origin baked in) come from apps/kiro-cli/skills. copy_skill_if_present apps/kiro-cli/skills/plannotator-review "$KIRO_SKILLS_DIR" copy_skill_if_present apps/kiro-cli/skills/plannotator-annotate "$KIRO_SKILLS_DIR" # 核心知识 skill 没有 Kiro 专属形态，其他 scope 装什么它就装什么 copy_skill_if_present apps/skills/core/plannotator "$KIRO_SKILLS_DIR" # 扩展 skills 来自 apps/skills/extra（不在 apps/kiro-cli/skills 中重复） copy_skill_if_present apps/skills/extra/plannotator-setup-goal "$KIRO_SKILLS_DIR" copy_skill_if_present apps/skills/extra/plannotator-visual-explainer "$KIRO_SKILLS_DIR" # 自定义 agent —— 绝不覆盖用户已有的同名文件 if [ ! -f "$HOME/.kiro/agents/plannotator.json" ] && [ -f "apps/kiro-cli/agents/plannotator.json" ]; then mkdir -p "$HOME/.kiro/agents" cp apps/kiro-cli/agents/plannotator.json "$HOME/.kiro/agents/plannotator.json" fi

几个值得注意的安装行为：

1. agent 文件从不覆盖：plannotator.json已存在时安装器直接跳过，用户手工修改过的配置不会被冲掉；
2. 核心知识 skill 也会装上：除文档列出的 4 个 skill 外，安装器还会复制 apps/skills/core/plannotator 这份 CLI 参考（知识型）skill，源码注释说明这是为了让 Kiro 用户也拥有完整的命令参考；
3. 支持显式退出安装：安装器提供--skip-kiro参数，对应环境变量PLANNOTATOR_SKIP_KIRO_INSTALL，也可通过配置项skipInstall.kiro关闭（见 scripts/install.sh 的帮助文本）。退出安装时安装器对~/.kiro完全不写不删，包括对陈旧 skill 的清理扫尾也会跳过 Kiro 目录。

已安装的 Kiro Skills 详解

Kiro 专属 skills（带 origin 的命令形态）

两个 Kiro 专属 skill 都在命令中烤入了PLANNOTATOR_ORIGIN=kiro-cli，这一点可以从各自的 SKILL.md 中直接看到。

plannotator-review（源码：plannotator-review/SKILL.md）——打开基于浏览器的代码评审 UI，并处理返回的反馈：

# 基本用法：评审当前改动（git/jj diff） PLANNOTATOR_ORIGIN=kiro-cli plannotator review # 附加一个 PR URL 进行评审 PLANNOTATOR_ORIGIN=kiro-cli plannotator review <pr-url> # 指定 base / diff 模式（仅会话生效、仅 git 仓库可用； # 对堆叠分支，--base 指向「你下面的那个分支」只评审本层） PLANNOTATOR_ORIGIN=kiro-cli plannotator review --base <ref> [--diff-type <type>]

plannotator-annotate（源码：plannotator-annotate/SKILL.md）——打开针对文件、文件夹或 URL 的批注 UI，然后处理返回的批注：

PLANNOTATOR_ORIGIN=kiro-cli plannotator annotate $ARGUMENTS

$ARGUMENTS应是一个 markdown/纯文本配置文件路径（.md、.txt、.yaml、.json、.toml、.ini、.csv、.log等）、文件夹路径、HTML 文件路径或 URL。SKILL.md 还要求：如果命令报告参数无法解析为文件、URL 或文件夹，模型应自行判断用户实际指的是哪个目标，并用具体的路径或 URL 重新运行命令。

两个 skill 的 frontmatter 都设置了disable-model-invocation: true，意味着它们只能按需触发，不会被模型自主唤起——这是「无后台钩子」设计在 skill 层面的具体体现。

关于PLANNOTATOR_ORIGIN的作用边界：它由服务端对照AGENT_CONFIG白名单校验（见 packages/server/index.ts，其中"kiro-cli"是合法取值之一）。但对 Kiro 而言 origin 是纯装饰性的，没有功能性影响。

共享扩展 skills（单一来源，不重复维护）

• plannotator-setup-goal：把想法访谈成一个结构化的 goal 包；
• plannotator-visual-explainer：生成精致的自包含 HTML 可视化说明。

这两个 skill 安装自 Plannotator 的规范目录 apps/skills/extra/，不在 Kiro 包中复制副本。由于它们来自共享来源，展示的是默认 agent 徽章而非 "Kiro CLI"——再次印证 origin 对 Kiro 只是装饰。

使用 Plannotator 自定义 Agent

安装器把 agent 写入~/.kiro/agents/plannotator.json。仓库中的规范版本是 agents/plannotator.json，完整内容如下，并逐字段说明：

{ "name": "plannotator", "description": "Kiro custom agent wiring for Plannotator review and annotation workflows.", "prompt": "You run Plannotator, which opens a browser UI for human review and annotation. Choose the skill that matches the task:\n- plannotator-review: review the current code changes (git/jj diff) or a pull request before continuing; optionally pass a PR URL, or --base <ref> / --diff-type <type> to pin the session's opening diff (git-only, session-only — e.g. --base <the branch below yours> for one layer of a stack).\n- plannotator-annotate: annotate a markdown or HTML file, a folder of docs, or a URL, then act on the returned annotations.\n- plannotator-setup-goal: turn an idea into a structured goal package by interviewing the user, building a fact sheet, then a plan.\n- plannotator-visual-explainer: generate a polished, self-contained HTML visual (implementation plan, PR walkthrough, or diagram) and open it for review.\nEach skill runs a `plannotator` shell command. plannotator-review and plannotator-annotate set PLANNOTATOR_ORIGIN=kiro-cli.", "tools": ["shell"], "allowedTools": ["shell"], "toolsSettings": { "shell": { "allowedCommands": ["plannotator .*"] } }, "resources": [ "skill://.kiro/skills/plannotator-*/SKILL.md", "skill://~/.kiro/skills/plannotator-*/SKILL.md" ] }

逐字段拆解：

文档中给出的「skill → 用途」对照表：

启动 agent

kiro-cli chat --agent plannotator

复用 skills 构建自己的 agent

如果你更喜欢自己的 agent，把同样的skill://~/.kiro/skills/plannotator-*/SKILL.mdresources 加进任意自定义 agent 的resources列表即可复用全部四个 skill，无需改动 skill 本身。

前提与 Schema 注意事项

自定义 agent 的 JSON 是刻意保守的，因为 Kiro 的 schema 可能演变。如果你的 Kiro 版本对 resources 或工具权限期望不同的字段名，直接编辑本机安装的~/.kiro/agents/plannotator.json适配你的运行时即可。

这一保守姿态在仓库中有两处呼应：其一，apps/kiro-cli/README.md 专门设有 "Schema note" 一节，提示若 Kiro 变更了 custom-agent schema 就修改已安装副本；其二，安装器在覆盖保护上同样保守——plannotator.json一旦存在就永不被安装器覆盖（见 scripts/install.sh 中的if [ ! -f ... ]判断），这保证了你手工适配后的字段修改在升级 Plannotator 后依然保留。