# Kiro CLI 运行环境配置详细指南

本文档详细描述 Kiro CLI 的所有配置项、配置文件位置、参数说明及示例。

---

## 目录

1. [配置体系概览](#1-配置体系概览)
2. [目录结构](#2-目录结构)
3. [全局设置 (cli.json)](#3-全局设置-clijson)
4. [Agent 配置](#4-agent-配置)
5. [Steering 文件（引导文件）](#5-steering-文件引导文件)
6. [Skills 技能文件](#6-skills-技能文件)
7. [Hooks 钩子系统](#7-hooks-钩子系统)
8. [MCP 服务器配置](#8-mcp-服务器配置)
9. [LSP 代码智能配置](#9-lsp-代码智能配置)
10. [环境变量](#10-环境变量)
11. [常用命令速查](#11-常用命令速查)

---

## 1. 配置体系概览

Kiro CLI 的配置分为多个层级，优先级从高到低：

```
Session（会话级）> Workspace（工作区级）> Global（全局级）
```

| 层级      | 说明                       | 适用范围   |
| --------- | -------------------------- | ---------- |
| Session   | 当前会话临时设置           | 仅当前会话 |
| Workspace | 项目目录下的`.kiro/`     | 仅当前项目 |
| Global    | 用户主目录下的`~/.kiro/` | 所有项目   |

---

## 2. 目录结构

### 全局目录 `~/.kiro/`

```
~/.kiro/
├── agents/                    # 全局 Agent 配置
│   ├── my-agent.json
│   └── rust-expert.json
├── prompts/                   # 全局提示词文件
│   └── rust-expert.txt
├── skills/                    # 全局技能文件
│   └── my-skill/
│       └── SKILL.md
├── steering/                  # 全局引导文件
│   ├── coding-standards.md
│   └── preferences.md
├── settings/
│   ├── cli.json               # 全局设置
│   └── mcp.json               # 全局 MCP 配置
├── hooks/                     # 钩子脚本存放目录（可自定义）
│   └── validate-write.sh
├── sessions/cli/              # 保存的聊天会话
└── .cli_bash_history          # Shell 命令历史
```

### 工作区目录 `.kiro/`（项目根目录下）

```
.kiro/
├── agents/                    # 工作区 Agent 配置（优先级高于全局）
│   └── project-helper.json
├── skills/                    # 工作区技能文件
│   └── db-helper/
│       └── SKILL.md
├── steering/                  # 工作区引导文件
│   └── team-conventions.md
└── settings/
    ├── cli.json               # 工作区设置（覆盖全局）
    └── mcp.json               # 工作区 MCP 配置
```

### 项目根目录其他配置文件

```
项目根目录/
├── AGENTS.md                  # 项目 Agent 指令（自动加载）
├── README.md                  # 项目说明（自动加载）
├── AmazonQ.md                 # 旧版项目指令（如存在则加载）
├── lsp.json                   # LSP 代码智能配置
└── .amazonq/                  # 旧版配置（向后兼容）
    ├── mcp.json
    └── rules/**/*.md
```

---

## 3. 全局设置 (cli.json)

### 文件位置

| 作用域 | 文件路径                      |
| ------ | ----------------------------- |
| 全局   | `~/.kiro/settings/cli.json` |
| 工作区 | `.kiro/settings/cli.json`   |

### 完整设置项列表

#### 3.1 Chat 聊天相关

| 设置项                                     | 类型    | 默认值      | 说明                                      |
| ------------------------------------------ | ------- | ----------- | ----------------------------------------- |
| `chat.defaultAgent`                      | string  | _(无)_    | 新会话使用的默认 Agent 名称               |
| `chat.defaultModel`                      | string  | _(无)_    | 默认 AI 模型 ID                           |
| `chat.enableThinking`                    | boolean | -           | 启用思考工具                              |
| `chat.showThinking`                      | boolean | `false`   | 显示思考/推理块（仅启动时生效）           |
| `chat.enableKnowledge`                   | boolean | -           | 启用知识库功能                            |
| `chat.enableCodeIntelligence`            | boolean | -           | 启用代码智能（LSP）                       |
| `chat.enableSubagent`                    | boolean | -           | 启用子 Agent 功能                         |
| `chat.enableTodoList`                    | boolean | -           | 启用待办列表功能                          |
| `chat.enableNotifications`               | boolean | -           | 启用桌面通知                              |
| `chat.greeting.enabled`                  | boolean | -           | 启动时显示欢迎消息                        |
| `chat.allowAnimations`                   | boolean | `true`    | 启用加载动画（旋转、进度条）              |
| `chat.allowAsciiArt`                     | boolean | `true`    | 启用 Unicode 符号，false 则降级为纯 ASCII |
| `chat.allowIcons`                        | boolean | `true`    | 显示状态指示图标                          |
| `chat.terminalTitle`                     | boolean | `false`   | 通过 OSC 0 更新终端窗口标题               |
| `chat.disableAutoCompaction`             | boolean | -           | 禁用自动上下文压缩                        |
| `chat.disableGranularTrust`              | boolean | -           | 禁用细粒度信任选项                        |
| `chat.disableInheritingDefaultResources` | boolean | `false`   | 禁用自定义 Agent 继承默认资源             |
| `chat.autoExpandToolOutput`              | boolean | -           | 始终展示完整工具输出                      |
| `chat.disableWrap`                       | boolean | -           | 禁用聊天输出自动换行                      |
| `chat.historyMode`                       | string  | `session` | 提示历史范围：`session` 或 `global`   |

#### 3.2 快捷键

| 设置项                            | 类型   | 默认值     | 说明           |
| --------------------------------- | ------ | ---------- | -------------- |
| `chat.keybindings.cancelStream` | string | `esc`    | 取消流式输出   |
| `chat.keybindings.closeMenu`    | string | `esc`    | 关闭菜单/面板  |
| `chat.keybindings.quit`         | string | `ctrl+c` | 退出（需双击） |

快捷键语法：`修饰符+键`，大小写不敏感。

- 修饰符：`ctrl`、`shift`、`alt`（别名 `meta`、`cmd`）
- 键名：`esc`、`enter`、`tab`、`up`/`down`/`left`/`right`、`space`、`backspace`、`delete`、`home`、`end`、`pageup`/`pagedown`、`a-z`、`0-9`

#### 3.3 遥测

| 设置项                | 类型    | 默认值 | 说明                                                |
| --------------------- | ------- | ------ | --------------------------------------------------- |
| `telemetry.enabled` | boolean | -      | 启用/禁用遥测（**全局设置，不可工作区覆盖**） |

#### 3.4 知识库

| 设置项                               | 类型   | 默认值 | 说明                                              |
| ------------------------------------ | ------ | ------ | ------------------------------------------------- |
| `knowledge.defaultIncludePatterns` | array  | -      | 索引时包含的文件 glob 模式                        |
| `knowledge.defaultExcludePatterns` | array  | -      | 索引时排除的文件 glob 模式                        |
| `knowledge.maxFiles`               | number | -      | 索引的最大文件数                                  |
| `knowledge.chunkSize`              | number | -      | 文本分块大小                                      |
| `knowledge.chunkOverlap`           | number | -      | 分块之间的重叠大小                                |
| `knowledge.indexType`              | string | -      | 索引类型：`fast`（BM25）或 `best`（语义搜索） |

#### 3.5 API

| 设置项                        | 类型   | 默认值 | 说明                                     |
| ----------------------------- | ------ | ------ | ---------------------------------------- |
| `api.timeout`               | number | -      | API 请求超时（毫秒）                     |
| `api.codewhisperer.service` | string | -      | CodeWhisperer 端点（**全局设置**） |
| `api.q.service`             | string | -      | Q 服务端点（**全局设置**）         |

#### 3.6 MCP

| 设置项                       | 类型   | 默认值 | 说明                         |
| ---------------------------- | ------ | ------ | ---------------------------- |
| `mcp.initTimeout`          | number | -      | MCP 服务器初始化超时（毫秒） |
| `mcp.noInteractiveTimeout` | number | -      | 非交互式 MCP 超时（毫秒）    |

#### 3.7 上下文压缩

| 设置项                                     | 类型   | 默认值 | 说明                           |
| ------------------------------------------ | ------ | ------ | ------------------------------ |
| `compaction.excludeContextWindowPercent` | number | -      | 从压缩中排除的上下文窗口百分比 |
| `compaction.excludeMessages`             | number | -      | 从压缩中排除的最近消息数量     |

#### 3.8 Hooks

| 设置项               | 类型    | 默认值 | 说明                                            |
| -------------------- | ------- | ------ | ----------------------------------------------- |
| `hooks.showStatus` | boolean | -      | 是否显示 hook 执行状态（设为 false 则静默运行） |

### cli.json 完整示例

**文件位置：`~/.kiro/settings/cli.json`**

```json
{
  "chat.defaultAgent": "my-vue-agent",
  "chat.defaultModel": "anthropic.claude-3-5-sonnet-20241022-v2:0",
  "chat.enableThinking": true,
  "chat.showThinking": false,
  "chat.enableKnowledge": true,
  "chat.enableCodeIntelligence": true,
  "chat.enableSubagent": true,
  "chat.enableTodoList": true,
  "chat.enableNotifications": true,
  "chat.greeting.enabled": true,
  "chat.allowAnimations": true,
  "chat.allowAsciiArt": true,
  "chat.allowIcons": true,
  "chat.terminalTitle": false,
  "chat.disableAutoCompaction": false,
  "chat.disableGranularTrust": false,
  "chat.disableInheritingDefaultResources": false,
  "chat.autoExpandToolOutput": false,
  "chat.disableWrap": false,
  "chat.historyMode": "global",
  "chat.keybindings.cancelStream": "esc",
  "chat.keybindings.closeMenu": "esc",
  "chat.keybindings.quit": "ctrl+c",
  "telemetry.enabled": true,
  "knowledge.defaultIncludePatterns": ["**/*.ts", "**/*.vue", "**/*.md"],
  "knowledge.defaultExcludePatterns": ["node_modules/**", "dist/**"],
  "knowledge.maxFiles": 1000,
  "knowledge.chunkSize": 512,
  "knowledge.chunkOverlap": 50,
  "knowledge.indexType": "best",
  "api.timeout": 30000,
  "mcp.initTimeout": 120000,
  "mcp.noInteractiveTimeout": 30000,
  "compaction.excludeContextWindowPercent": 10,
  "compaction.excludeMessages": 5
}
```

---

## 4. Agent 配置

### 文件位置

| 作用域 | 文件路径                       | 优先级                   |
| ------ | ------------------------------ | ------------------------ |
| 工作区 | `.kiro/agents/<name>.json`   | 高（覆盖同名全局 Agent） |
| 全局   | `~/.kiro/agents/<name>.json` | 低                       |

文件名（不含 `.json`）即为 Agent 名称。

### 所有字段说明

| 字段                 | 类型         | 必填 | 说明                                                      |
| -------------------- | ------------ | ---- | --------------------------------------------------------- |
| `name`             | string       | 否   | Agent 名称标识                                            |
| `description`      | string       | 否   | 人类可读描述                                              |
| `prompt`           | string       | 否   | 系统提示词（支持内联文本或`file:///path` 引用外部文件） |
| `model`            | string       | 否   | 指定模型 ID，未指定则使用默认模型                         |
| `tools`            | array        | 否   | 可用工具列表                                              |
| `allowedTools`     | array        | 否   | 自动批准的工具（无需用户确认），支持通配符                |
| `toolsSettings`    | object       | 否   | 工具级别的详细配置                                        |
| `resources`        | array        | 否   | 上下文资源列表                                            |
| `hooks`            | object/array | 否   | 触发器钩子配置                                            |
| `mcpServers`       | object       | 否   | MCP 服务器配置                                            |
| `toolAliases`      | object       | 否   | 工具名称重映射（解决命名冲突）                            |
| `useLegacyMcpJson` | boolean      | 否   | 是否加载旧版`mcp.json` 配置                             |
| `keyboardShortcut` | string       | 否   | 快速切换到此 Agent 的快捷键                               |
| `welcomeMessage`   | string       | 否   | 切换到此 Agent 时显示的欢迎消息                           |

### 内置工具列表

以下工具可在 `tools` 字段中使用：

| 工具名         | 别名                              | 说明                      |
| -------------- | --------------------------------- | ------------------------- |
| `read`       | `fs_read`, `fsRead`           | 读取文件/目录/图片        |
| `write`      | `fs_write`, `fsWrite`         | 创建/编辑文件             |
| `shell`      | `execute_bash`, `execute_cmd` | 执行终端命令              |
| `grep`       | -                                 | 正则文本搜索              |
| `glob`       | -                                 | 文件路径模式匹配          |
| `code`       | -                                 | 代码智能（AST 搜索、LSP） |
| `use_aws`    | -                                 | AWS CLI API 调用          |
| `web_fetch`  | `webFetch`                      | 获取 URL 内容             |
| `web_search` | -                                 | 网络搜索                  |
| `knowledge`  | -                                 | 知识库索引和搜索          |
| `subagent`   | `agent_crew`, `use_subagent`  | 子 Agent 流水线           |
| `todo_list`  | `task`, `todo`                | 待办任务管理              |
| `introspect` | -                                 | 查询 Kiro CLI 自身文档    |

特殊值：

- `"*"` — 所有工具（仅用于 `tools` 字段）
- `"@builtin"` — 所有内置工具（可用于 `allowedTools`）

### tools 与 allowedTools 的区别

- **`tools`**：Agent 能使用哪些工具（能力范围）
- **`allowedTools`**：哪些工具使用时无需用户确认（信任范围）

### allowedTools 通配符模式

```json
{
  "allowedTools": [
    "read",              // 精确匹配内置工具
    "fs_*",             // 前缀通配：匹配 fs_read, fs_write
    "@git/git_status",  // 精确匹配 MCP 工具
    "@server/read_*",   // MCP 工具通配
    "@git",             // 该 MCP 服务器的所有工具
    "@builtin"          // 所有内置工具
  ]
}
```

### toolsSettings 详细配置

#### write 工具设置

```json
{
  "toolsSettings": {
    "write": {
      "allowedPaths": ["src/**", "tests/**"],
      "deniedPaths": ["node_modules/**", "/etc/**"]
    }
  }
}
```

| 参数             | 类型  | 说明                     |
| ---------------- | ----- | ------------------------ |
| `allowedPaths` | array | 允许写入的路径 glob 模式 |
| `deniedPaths`  | array | 禁止写入的路径 glob 模式 |

#### shell 工具设置

```json
{
  "toolsSettings": {
    "shell": {
      "allowedCommands": ["git status", "npm test", "pnpm build"],
      "deniedCommands": ["rm -rf *", "sudo *", "shutdown"],
      "autoAllowReadonly": true,
      "denyByDefault": false
    }
  }
}
```

| 参数                  | 类型    | 默认值    | 说明                                                  |
| --------------------- | ------- | --------- | ----------------------------------------------------- |
| `allowedCommands`   | array   | -         | 自动批准的命令（正则模式）                            |
| `deniedCommands`    | array   | -         | 始终拒绝的命令（正则模式）                            |
| `autoAllowReadonly` | boolean | -         | 自动批准只读命令（如`ls`、`cat`、`git status`） |
| `denyByDefault`     | boolean | `false` | 默认拒绝未在 allowedCommands 中的命令                 |

#### web_fetch 工具设置

```json
{
  "toolsSettings": {
    "web_fetch": {
      "trusted": [".*docs\\.aws\\.amazon\\.com.*", ".*vuejs\\.org.*"],
      "blocked": [".*pastebin\\.com.*"]
    }
  }
}
```

| 参数        | 类型  | 说明                                          |
| ----------- | ----- | --------------------------------------------- |
| `trusted` | array | 自动允许的 URL 正则模式                       |
| `blocked` | array | 始终阻止的 URL 正则模式（优先级高于 trusted） |

### resources 资源配置

支持两种 URI 协议：

| 协议         | 加载方式 | 说明                                         |
| ------------ | -------- | -------------------------------------------- |
| `file://`  | 始终加载 | 内容始终存在于上下文窗口                     |
| `skill://` | 按需加载 | 仅元数据（名称、描述）初始加载，内容按需加载 |

```json
{
  "resources": [
    "file://README.md",
    "file://src/**/*.vue",
    "file://docs/api.md",
    "skill://.kiro/skills/**/SKILL.md"
  ]
}
```

### 默认资源继承

自定义 Agent 默认会自动继承以下资源：

| 资源                                  | 说明               |
| ------------------------------------- | ------------------ |
| `file://AGENTS.md`                  | 项目 Agent 指令    |
| `file://README.md`                  | 项目说明           |
| `skill://.kiro/skills/*/SKILL.md`   | 工作区技能         |
| `skill://~/.kiro/skills/*/SKILL.md` | 全局技能           |
| `file://~/.kiro/steering/**/*.md`   | 全局引导文件       |
| `file://.kiro/steering/**/*.md`     | 工作区引导文件     |
| `file://AmazonQ.md`                 | 旧版指令（如存在） |

设置 `chat.disableInheritingDefaultResources` 为 `true` 可禁用此继承。

### Agent 完整示例

**文件位置：`.kiro/agents/vue-dev.json`**

```json
{
  "name": "vue-dev",
  "description": "Vue 3 + TypeScript 开发助手",
  "prompt": "你是一个 Vue 3 + TypeScript 专家。使用 Composition API、Naive UI 组件库和 UnoCSS。遵循项目现有的代码风格和架构。",
  "model": "anthropic.claude-3-5-sonnet-20241022-v2:0",
  "tools": [
    "read", "write", "shell", "grep", "glob", "code", "web_fetch", "knowledge"
  ],
  "allowedTools": [
    "read", "grep", "glob", "code"
  ],
  "toolsSettings": {
    "write": {
      "allowedPaths": ["src/**", "docs/**", "tests/**"],
      "deniedPaths": ["node_modules/**", "dist/**"]
    },
    "shell": {
      "allowedCommands": [
        "pnpm (dev|build|test|lint)",
        "git (status|diff|log|branch)",
        "npx vue-tsc"
      ],
      "deniedCommands": ["rm -rf", "sudo"],
      "autoAllowReadonly": true
    },
    "web_fetch": {
      "trusted": [".*vuejs\\.org.*", ".*naiveui\\.com.*"],
      "blocked": [".*pastebin\\.com.*"]
    }
  },
  "resources": [
    "file://src/**/*.vue",
    "file://src/**/*.ts",
    "file://package.json",
    "file://tsconfig.json",
    "skill://.kiro/skills/**/SKILL.md"
  ],
  "hooks": {
    "agentSpawn": [
      { "command": "git branch --show-current && node -v" }
    ],
    "preToolUse": [
      {
        "matcher": "write",
        "command": "echo 'Writing file...'"
      }
    ]
  },
  "mcpServers": {
    "git": {
      "command": "mcp-server-git",
      "args": ["--stdio"]
    }
  },
  "keyboardShortcut": "ctrl+shift+v",
  "welcomeMessage": "Vue 3 开发助手已就绪！有什么可以帮你的？"
}
```

---

## 5. Steering 文件（引导文件）

Steering 文件是持久化的指令文档，用于在所有会话中引导 Agent 行为。

### 文件位置

| 作用域 | 目录路径              |
| ------ | --------------------- |
| 工作区 | `.kiro/steering/`   |
| 全局   | `~/.kiro/steering/` |

目录会被递归扫描，任何层级的 `.md` 文件都会被加载。

### 加载规则

- **内置默认 Agent (`kiro_default`)**：自动加载 steering 文件
- **自定义 Agent**：需要手动在 `resources` 中声明：
  ```json
  { "resources": ["file://.kiro/steering/**/*.md"] }
  ```

### inclusion 控制

Steering 文件支持可选的 YAML frontmatter 来控制加载时机：

| inclusion 值         | 行为                                   |
| -------------------- | -------------------------------------- |
| `always`           | 始终加载（默认，等同于无 frontmatter） |
| `fileMatch`        | 仅在处理匹配文件时加载（排除自动加载） |
| `manual`           | 仅通过`/context add` 手动加载        |
| _(无 frontmatter)_ | 始终加载                               |

### Steering 文件示例

**文件位置：`.kiro/steering/coding-standards.md`**

```markdown
# 项目编码规范

## Vue 组件
- 使用 Composition API + `<script setup>` 语法
- 组件命名使用 PascalCase
- Props 必须使用 TypeScript 类型定义
- 使用 Naive UI 组件库

## TypeScript
- 严格模式，禁止 `any`
- 函数参数和返回值必须有类型标注
- 使用 `es-toolkit` 代替 lodash

## 样式
- 使用 UnoCSS 原子类
- 避免写自定义 CSS，除非必要
- 暗色模式必须适配
```

**文件位置：`~/.kiro/steering/personal-preferences.md`**

```markdown
# 个人偏好

- 回答使用中文
- 代码注释使用英文
- 优先给出完整可运行的代码
- 修改代码前先阅读现有实现
- 保持简洁，不要过度设计
```

**带 inclusion 控制的示例：`.kiro/steering/vue-rules.md`**

```markdown
---
inclusion: always
---

# Vue 开发规则

- 所有组件必须定义 `name` 选项
- 使用 `defineProps` 和 `defineEmits` 宏
- 大型表单使用 Naive UI 的 NForm
```

---

## 6. Skills 技能文件

Skills 是按需加载的资源，启动时仅加载元数据，实际内容在需要时才加载，节省上下文窗口空间。

### 文件位置

| 作用域 | 目录路径                                 |
| ------ | ---------------------------------------- |
| 工作区 | `.kiro/skills/<skill-name>/SKILL.md`   |
| 全局   | `~/.kiro/skills/<skill-name>/SKILL.md` |

### 格式要求

Skill 文件**必须**以 YAML frontmatter 开头：

```markdown
---
name: vue-component-patterns
description: Vue 3 组件设计模式指南。在设计新组件或重构现有组件时使用。
---

# Vue 3 组件设计模式

## Compound Components Pattern

...详细内容...
```

| frontmatter 字段 | 必填 | 说明                                     |
| ---------------- | ---- | ---------------------------------------- |
| `name`         | 是   | 技能名称                                 |
| `description`  | 是   | 描述（Agent 根据此决定是否加载完整内容） |

### 在 Agent 中引用 Skills

```json
{
  "resources": [
    "skill://.kiro/skills/**/SKILL.md",
    "skill://~/.kiro/skills/**/SKILL.md"
  ]
}
```

### Skills 示例

**文件位置：`.kiro/skills/naive-ui-patterns/SKILL.md`**

```markdown
---
name: naive-ui-patterns
description: Naive UI 组件库常用模式和最佳实践。在使用 Naive UI 组件开发界面时参考。
---

# Naive UI 常用模式

## 表格 (DataTable)

使用 `NDataTable` 时的标准模式：

\`\`\`vue
<script setup lang="ts">
import { NDataTable } from 'naive-ui'
import type { DataTableColumns } from 'naive-ui'

interface RowData {
  id: string
  name: string
}

const columns: DataTableColumns<RowData> = [
  { title: 'ID', key: 'id' },
  { title: '名称', key: 'name' }
]
</script>
\`\`\`

## 表单 (Form)

...
```

---

## 7. Hooks 钩子系统

Hooks 允许在 Agent 生命周期的特定时间点执行自定义命令。

### 配置位置

Hooks 配置在 **Agent 配置文件** 中（`.kiro/agents/<name>.json` 或 `~/.kiro/agents/<name>.json`）。

### 触发时机

| 触发器               | 时机                 | 可否阻止工具执行       |
| -------------------- | -------------------- | ---------------------- |
| `agentSpawn`       | Agent 初始化时       | -                      |
| `userPromptSubmit` | 用户提交消息时       | -                      |
| `preToolUse`       | 工具执行前           | ✅ 可通过退出码 2 阻止 |
| `postToolUse`      | 工具执行后           | -                      |
| `stop`             | Assistant 完成回复时 | -                      |

### 退出码含义

| 退出码 | 含义                                             |
| ------ | ------------------------------------------------ |
| `0`  | 成功，STDOUT 加入 Agent 上下文                   |
| `2`  | （仅 preToolUse）阻止工具执行，STDERR 返回给 LLM |
| 其他   | 失败，STDERR 作为警告显示给用户                  |

### 两种配置格式

#### Object 格式（推荐）

```json
{
  "hooks": {
    "agentSpawn": [
      {
        "command": "git status && git branch --show-current",
        "timeout_ms": 5000,
        "cache_ttl_seconds": 0
      }
    ],
    "userPromptSubmit": [
      { "command": "date '+%Y-%m-%d %H:%M:%S'" }
    ],
    "preToolUse": [
      {
        "matcher": "write",
        "command": "~/.kiro/hooks/validate-write.sh",
        "timeout_ms": 10000,
        "max_output_size": 10240
      }
    ],
    "postToolUse": [
      {
        "matcher": "shell",
        "command": "echo 'Command executed'"
      }
    ],
    "stop": [
      { "command": "echo 'Turn complete'" }
    ]
  }
}
```

Object 格式字段：

| 字段                  | 必填 | 类型   | 默认值    | 说明                                      |
| --------------------- | ---- | ------ | --------- | ----------------------------------------- |
| `command`           | 是   | string | -         | 要执行的命令                              |
| `matcher`           | 否   | string | -         | 工具匹配模式（仅 preToolUse/postToolUse） |
| `timeout_ms`        | 否   | number | `10000` | 最大执行时间（毫秒）                      |
| `max_output_size`   | 否   | number | `10240` | 最大输出字节数（超出则截断）              |
| `cache_ttl_seconds` | 否   | number | `0`     | 缓存成功结果的秒数（0=不缓存）            |

#### Array 格式

```json
{
  "hooks": [
    {
      "name": "show-git-status",
      "trigger": "agentSpawn",
      "action": { "type": "command", "command": "git status" },
      "timeout": 10,
      "enabled": true
    },
    {
      "name": "validate-write",
      "trigger": "preToolUse",
      "matcher": "write",
      "action": { "type": "command", "command": "~/.kiro/hooks/validate-write.sh" },
      "timeout": 30,
      "enabled": true
    }
  ]
}
```

Array 格式字段：

| 字段        | 必填 | 类型    | 默认值   | 说明                                        |
| ----------- | ---- | ------- | -------- | ------------------------------------------- |
| `name`    | 否   | string  | -        | 可读名称                                    |
| `trigger` | 是   | string  | -        | 触发器名称                                  |
| `matcher` | 否   | string  | -        | 工具匹配模式                                |
| `action`  | 是   | object  | -        | `{ "type": "command", "command": "..." }` |
| `timeout` | 否   | number  | `10`   | 最大执行时间（**秒**）                |
| `enabled` | 否   | boolean | `true` | 设为 false 可禁用而不删除                   |

### Matcher 匹配模式

| 模式               | 说明                      | 示例                     |
| ------------------ | ------------------------- | ------------------------ |
| 精确匹配           | 匹配特定工具              | `"write"`、`"shell"` |
| 通配符             | 匹配工具名模式            | `"fs_*"`               |
| MCP 服务器全部工具 | 匹配某个 MCP 服务器       | `"@git"`               |
| MCP 特定工具       | 匹配 MCP 服务器的特定工具 | `"@git/status"`        |
| 所有工具           | 匹配所有                  | `"*"`                  |
| 所有内置工具       | 仅内置                    | `"@builtin"`           |
| 无 matcher         | 应用于所有工具            | _(不设置)_             |

### Hook 收到的 STDIN 数据

Hook 通过 STDIN 接收 JSON 格式的事件数据：

```json
{
  "hook_event_name": "preToolUse",
  "cwd": "/home/user/project",
  "tool_name": "fs_write",
  "tool_input": {
    "path": "/home/user/project/src/App.vue",
    "command": "create",
    "content": "..."
  }
}
```

### 环境变量

Hook 脚本可访问 `KIRO_SESSION_ID` 环境变量（当前会话 UUID）。

### Hook 脚本示例

**文件位置：`~/.kiro/hooks/validate-write.sh`**

```bash
#!/bin/bash
# 读取 hook 事件
EVENT=$(cat)

# 提取文件路径
FILE=$(echo "$EVENT" | jq -r '.tool_input.path // empty')

# 阻止写入 .env 文件
if [[ "$FILE" == *".env"* ]]; then
  echo "禁止修改 .env 文件" >&2
  exit 2  # 退出码 2 = 阻止工具执行
fi

exit 0  # 允许执行
```

---

## 8. MCP 服务器配置

MCP (Model Context Protocol) 服务器为 Agent 提供额外的工具能力。

### 配置位置

MCP 服务器可在以下位置配置：

| 位置       | 路径                                                | 说明                           |
| ---------- | --------------------------------------------------- | ------------------------------ |
| Agent 配置 | `.kiro/agents/<name>.json` 的 `mcpServers` 字段 | 特定 Agent 专用                |
| 全局 MCP   | `~/.kiro/settings/mcp.json`                       | 所有 Agent 可用                |
| 工作区 MCP | `.kiro/settings/mcp.json`                         | 当前项目所有 Agent 可用        |
| 旧版全局   | `~/.aws/amazonq/mcp.json`                         | 需要`useLegacyMcpJson: true` |
| 旧版工作区 | `.amazonq/mcp.json`                               | 需要`useLegacyMcpJson: true` |

### 三种服务器类型

#### 8.1 本地 (stdio) 服务器

通过子进程启动，使用标准输入/输出通信。

```json
{
  "mcpServers": {
    "git": {
      "command": "mcp-server-git",
      "args": ["--stdio"],
      "env": {
        "GIT_DIR": "/path/to/repo"
      },
      "timeout": 120000,
      "disabled": false,
      "disabledTools": ["dangerous_tool"]
    }
  }
}
```

| 字段              | 必填 | 类型    | 默认值     | 说明                   |
| ----------------- | ---- | ------- | ---------- | ---------------------- |
| `command`       | 是   | string  | -          | 启动服务器的命令       |
| `args`          | 否   | array   | -          | 命令参数               |
| `env`           | 否   | object  | -          | 环境变量               |
| `timeout`       | 否   | number  | `120000` | 请求超时（毫秒）       |
| `disabled`      | 否   | boolean | `false`  | 是否禁用此服务器       |
| `disabledTools` | 否   | array   | -          | 禁用该服务器的特定工具 |

#### 8.2 远程 (HTTP) 服务器

通过 HTTP/SSE 连接远程服务器。

```json
{
  "mcpServers": {
    "remote-api": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer $API_TOKEN"
      },
      "timeout": 120000,
      "disabled": false,
      "disabledTools": [],
      "forceAuth": false
    }
  }
}
```

| 字段              | 必填 | 类型    | 默认值     | 说明                         |
| ----------------- | ---- | ------- | ---------- | ---------------------------- |
| `url`           | 是   | string  | -          | HTTP 端点 URL                |
| `headers`       | 否   | object  | -          | HTTP 请求头                  |
| `oauth`         | 否   | object  | -          | OAuth 配置对象               |
| `oauthScopes`   | 否   | array   | -          | OAuth 作用域                 |
| `timeout`       | 否   | number  | `120000` | 请求超时（毫秒）             |
| `disabled`      | 否   | boolean | `false`  | 是否禁用                     |
| `disabledTools` | 否   | array   | -          | 禁用特定工具                 |
| `forceAuth`     | 否   | boolean | `false`  | 跳过无认证尝试，直接走 OAuth |

**OAuth 配置对象**：

```json
{
  "mcpServers": {
    "slack": {
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "clientId": "my-app-id",
        "clientSecret": "my-secret",
        "redirectUri": "http://localhost:7778/oauth/callback",
        "oauthScopes": ["search:read", "channels:read"]
      }
    }
  }
}
```

| oauth 字段       | 说明                                                  |
| ---------------- | ----------------------------------------------------- |
| `clientId`     | 预注册的 OAuth 客户端 ID（设置后跳过动态客户端注册）  |
| `clientSecret` | OAuth 客户端密钥（机密客户端）                        |
| `redirectUri`  | 回调 URI（格式：`host:port`、`:port` 或完整 URL） |
| `oauthScopes`  | 请求的 OAuth 作用域                                   |

#### 8.3 Registry 服务器

从组织 MCP 注册表解析的服务器（企业版功能）。

```json
{
  "mcpServers": {
    "github": {
      "type": "registry",
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      },
      "timeout": 60000
    }
  }
}
```

| 字段        | 必填 | 类型   | 说明                               |
| ----------- | ---- | ------ | ---------------------------------- |
| `type`    | 是   | string | 必须为`"registry"`               |
| `env`     | 否   | object | 环境变量（覆盖注册表默认值）       |
| `headers` | 否   | object | HTTP 头（远程 registry 服务器）    |
| `timeout` | 否   | number | 请求超时                           |
| `oauth`   | 否   | object | OAuth 配置（远程 registry 服务器） |

### MCP 配置完整示例

**在 Agent 配置中（`.kiro/agents/full-stack.json`）：**

```json
{
  "name": "full-stack",
  "tools": ["read", "write", "shell", "code"],
  "mcpServers": {
    "git": {
      "command": "mcp-server-git",
      "args": ["--stdio"]
    },
    "github": {
      "command": "mcp-server-github",
      "args": ["--stdio"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      }
    },
    "postgres": {
      "command": "mcp-server-postgres",
      "args": ["--stdio"],
      "env": {
        "DATABASE_URL": "$DATABASE_URL"
      },
      "disabledTools": ["drop_table", "truncate"]
    }
  }
}
```

---

## 9. LSP 代码智能配置

### 文件位置

项目根目录下的 `lsp.json`。

### 初始化

```bash
# 在聊天中执行
/code init

# 强制重新初始化
/code init -f
```

首次执行 `/code init` 后会创建 `lsp.json`，后续启动时自动加载。删除 `lsp.json` 即可禁用。

### 预配置的语言服务器

| 语言          | 文件扩展名                        | 服务器                     | 安装命令                                                     |
| ------------- | --------------------------------- | -------------------------- | ------------------------------------------------------------ |
| TypeScript/JS | `.ts` `.js` `.tsx` `.jsx` | typescript-language-server | `npm install -g typescript-language-server typescript`     |
| Rust          | `.rs`                           | rust-analyzer              | `rustup component add rust-analyzer`                       |
| Python        | `.py`                           | pyright                    | `pip install pyright`                                      |
| Go            | `.go`                           | gopls                      | `go install golang.org/x/tools/gopls@latest`               |
| Java          | `.java`                         | jdtls                      | `brew install jdtls` (macOS)                               |
| Kotlin        | `.kt` `.kts`                  | kotlin-lsp                 | [GitHub 下载](https://github.com/fwcd/kotlin-language-server) |
| Ruby          | `.rb`                           | solargraph                 | `gem install solargraph`                                   |
| C/C++         | `.c` `.cpp` `.h` `.hpp`   | clangd                     | `apt install clangd` (Linux)                               |

### 自定义语言服务器

**文件位置：项目根目录 `lsp.json`**

```json
{
  "languages": {
    "vue": {
      "name": "vue-language-server",
      "command": "vue-language-server",
      "args": ["--stdio"],
      "file_extensions": ["vue"],
      "project_patterns": ["package.json", "vite.config.ts"],
      "exclude_patterns": ["**/node_modules/**", "**/dist/**"],
      "multi_workspace": false,
      "initialization_options": {
        "typescript": {
          "tsdk": "node_modules/typescript/lib"
        }
      },
      "request_timeout_secs": 60
    }
  }
}
```

| 字段                       | 必填 | 类型    | 默认值    | 说明                            |
| -------------------------- | ---- | ------- | --------- | ------------------------------- |
| `name`                   | 是   | string  | -         | 语言服务器显示名                |
| `command`                | 是   | string  | -         | 启动命令                        |
| `args`                   | 否   | array   | -         | 命令参数（通常`["--stdio"]`） |
| `file_extensions`        | 是   | array   | -         | 处理的文件扩展名                |
| `project_patterns`       | 否   | array   | -         | 项目根标识文件                  |
| `exclude_patterns`       | 否   | array   | -         | 排除的 glob 模式                |
| `multi_workspace`        | 否   | boolean | `false` | 是否支持多工作区                |
| `initialization_options` | 否   | object  | -         | LSP 初始化选项                  |
| `request_timeout_secs`   | 否   | number  | `60`    | 请求超时（秒）                  |

---

## 10. 环境变量

以下环境变量可影响 Kiro CLI 的运行行为：

| 变量名                  | 说明                                             |
| ----------------------- | ------------------------------------------------ |
| `KIRO_HOME`           | 覆盖全局配置目录（默认`~/.kiro`）              |
| `KIRO_DATA_DIR`       | 覆盖运行时数据目录（默认因平台而异）             |
| `KIRO_ASCII_MODE=1`   | 强制 ASCII 模式，忽略`chat.allowAsciiArt` 设置 |
| `KIRO_CHAT_LOG_FILE`  | 自定义日志文件路径                               |
| `KIRO_LOG_NO_COLOR=1` | 禁用日志中的 ANSI 颜色                           |
| `KIRO_SESSION_ID`     | （Hook 脚本可用）当前会话 UUID                   |
| `$EDITOR`             | 编辑 Agent 配置时使用的编辑器                    |

### 数据目录默认位置

| 平台    | 路径                                       |
| ------- | ------------------------------------------ |
| macOS   | `~/Library/Application Support/kiro-cli` |
| Linux   | `~/.local/share/kiro-cli`                |
| Windows | `%LOCALAPPDATA%\kiro-cli`                |

### 日志文件默认位置

| 平台    | 路径                                        |
| ------- | ------------------------------------------- |
| macOS   | `$TMPDIR/kiro-log/kiro-chat.log`          |
| Linux   | `$XDG_RUNTIME_DIR/kiro-log/kiro-chat.log` |
| Windows | `%TEMP%/kiro-log/logs/kiro-chat.log`      |

### 示例

```bash
# 使用自定义配置目录
KIRO_HOME=/opt/team/kiro kiro-cli chat

# 使用自定义数据目录（企业部署场景）
KIRO_DATA_DIR=/opt/kiro/data kiro-cli chat

# 自定义日志路径
KIRO_CHAT_LOG_FILE=/tmp/kiro-debug.log kiro-cli chat

# 强制 ASCII 模式（SSH/无 Unicode 终端）
KIRO_ASCII_MODE=1 kiro-cli chat
```

---

## 11. 常用命令速查

### 设置管理

```bash
# 查看所有可用设置
kiro-cli settings list --all

# 获取设置值
kiro-cli settings chat.defaultModel

# 修改设置
kiro-cli settings chat.defaultModel "anthropic.claude-3-5-sonnet-20241022-v2:0"
kiro-cli settings chat.defaultAgent "vue-dev"
kiro-cli settings telemetry.enabled false
kiro-cli settings knowledge.indexType "best"

# 删除设置（恢复默认）
kiro-cli settings --delete chat.defaultModel

# 通配符删除
kiro-cli settings --delete "knowledge.*"

# 在编辑器中打开设置文件
kiro-cli settings open
```

### Agent 管理

```bash
# 列出所有 Agent
kiro-cli agent list

# 创建 Agent
kiro-cli agent create my-agent
kiro-cli agent create my-agent --from kiro_default
kiro-cli agent create my-agent --directory .kiro/agents

# 编辑 Agent
kiro-cli agent edit my-agent

# 验证配置
kiro-cli agent validate --path .kiro/agents/my-agent.json

# 设置默认 Agent
kiro-cli agent set-default my-agent
```

### 聊天会话

```bash
# 启动聊天
kiro-cli chat

# 使用指定 Agent 和模型
kiro-cli chat --agent vue-dev --model <model-id>

# 信任所有工具（无需确认）
kiro-cli chat --trust-all-tools

# 信任特定工具
kiro-cli chat --trust-tools=read,grep,code

# 恢复上次会话
kiro-cli chat --resume

# 选择会话恢复
kiro-cli chat --resume-picker

# 无头模式（自动化）
kiro-cli chat --no-interactive --trust-all-tools "运行测试并汇总结果"

# 设置推理强度
kiro-cli chat --effort high "Review this code"
```

### TUI 内斜杠命令

```
/settings              打开设置菜单
/settings display      显示设置（动画、ASCII、图标）
/settings theme        主题设置
/settings terminal     终端多行输入配置
/settings history      历史记录范围

/agent                 列出/切换 Agent
/agent create          创建新 Agent
/agent edit            编辑当前 Agent

/model                 切换模型
/tools                 查看可用工具
/hooks                 查看当前 Hook 配置
/context               查看上下文窗口使用情况
/context show          显示上下文文件详情
/context add <path>    添加临时上下文文件

/code init             初始化代码智能
/code init -f          强制重新初始化
/code status           查看 LSP 状态
/code overview         代码库概览

/mcp                   查看 MCP 服务器状态
/mcp add               添加 MCP 服务器
/mcp remove            移除 MCP 服务器

/chat save             保存当前会话
/chat load             加载历史会话

/guide                 切换到帮助 Agent
/help                  查看所有斜杠命令
```

---

## 快速上手：为当前项目配置 Kiro CLI

### 步骤 1：创建工作区配置目录

```bash
mkdir -p .kiro/agents .kiro/steering .kiro/skills
```

### 步骤 2：创建项目 Agent

创建 `.kiro/agents/project-dev.json`：

```json
{
  "name": "project-dev",
  "description": "FranklinWH ToolBox 项目开发助手",
  "prompt": "你是一个 Vue 3 + TypeScript + Naive UI 项目的开发助手。项目使用 Vite 构建，pnpm 管理依赖，UnoCSS 编写样式。",
  "tools": ["read", "write", "shell", "grep", "glob", "code", "web_fetch"],
  "allowedTools": ["read", "grep", "glob", "code"],
  "toolsSettings": {
    "shell": {
      "allowedCommands": ["pnpm", "npx", "git (status|diff|log|branch)"],
      "autoAllowReadonly": true
    },
    "write": {
      "deniedPaths": ["node_modules/**", "dist/**"]
    }
  },
  "resources": [
    "file://src/**/*.vue",
    "file://src/**/*.ts",
    "file://package.json"
  ],
  "hooks": {
    "agentSpawn": [
      { "command": "git branch --show-current" }
    ]
  }
}
```

### 步骤 3：添加引导文件

创建 `.kiro/steering/project-rules.md`：

```markdown
# 项目规范

- 使用 Vue 3 Composition API + <script setup>
- UI 库：Naive UI
- 样式：UnoCSS 原子类
- 工具函数库：es-toolkit
- 日期处理：dayjs
- 图表：@antv/g2 和 uplot
- 包管理器：pnpm（使用 pnpm@10）
```

### 步骤 4：设为默认 Agent

```bash
kiro-cli settings chat.defaultAgent project-dev
```

---

> 本文档基于 Kiro CLI 官方文档整理，配置项可能随版本更新而变化。使用 `kiro-cli settings list --all` 查看当前版本支持的所有设置。