# Kiro Agent 配置总览

> 生成日期：2026-02-15 | 适用仓库：NeoZQYY Monorepo

本文档完整记录当前 `.kiro/` 目录下所有 Agent 相关配置（Hooks、Steering、Skills、MCP、自定义 Agent），说明各组件的作用、协作关系，以及为节省上下文开支所做的优化设计。

---

## 目录

1. [整体架构概览](#1-整体架构概览)
2. [Hooks（事件钩子）](#2-hooks事件钩子)
3. [Steering（引导文件）](#3-steering引导文件)
4. [Skills（技能）](#4-skills技能)
5. [自定义 Agent（子代理）](#5-自定义-agent子代理)
6. [MCP（Model Context Protocol）](#6-mcpmodel-context-protocol)
7. [辅助脚本](#7-辅助脚本)
8. [上下文优化策略](#8-上下文优化策略)
9. [组件协作流程图](#9-组件协作流程图)

---

## 1. 整体架构概览

```
用户 Prompt
  │
  ├─→ [promptSubmit] audit-flagger.ps1    ← 判定是否高风险（写 .audit_state.json）
  ├─→ [promptSubmit] prompt_audit_log.ps1 ← 记录 Prompt-ID + 原文到独立日志文件
  │
  ▼
Kiro 主对话（Agent 执行）
  │  ← Steering 文件注入上下文（always / fileMatch / manual 三种模式）
  │  ← Skills 按需激活（由 Agent 或 /audit 子代理调用）
  │  ← MCP 工具按需调用（Postgres / Git / Filesystem / Playwright / OpenAPI）
  │
  ▼
[agentStop] audit-reminder.ps1
  │  ← 检查 .audit_state.json，若有待审计则提醒（15 分钟限频）
  │
  ▼
用户手动触发 /audit
  │
  ▼
audit-writer 子代理（独立执行）
  ├─→ 调用 Skills：change-annotation-audit / steering-readme-maintainer / bd-manual-db-docs
  ├─→ 写审计产物（docs/audit/changes/、AI_CHANGELOG、CHANGE 注释、docs/database/）
  ├─→ 刷新审计一览表（gen_audit_dashboard.py）
  └─→ 清除 .audit_state.json 待审计标记
```

核心设计理念：**主对话专注编码，审计写入卸载到子代理**，避免重型文档操作膨胀主对话上下文。

---

## 2. Hooks（事件钩子）

共 7 个 Hook，位于 `.kiro/hooks/`。按启用状态分为两组：

### 2.1 已启用（4 个 runCommand + 1 个 askAgent）

| Hook 文件 | 事件类型 | 动作类型 | 功能说明 |
|---|---|---|---|
| `audit-flagger.kiro.hook` | `promptSubmit` | `runCommand` | 每次提交 prompt 时运行 `audit_flagger.ps1`，基于 `git status` 判定是否存在高风险改动，结果写入 `.kiro/.audit_state.json`。不触发 LLM。 |
| `prompt-audit-log.kiro.hook` | `promptSubmit` | `runCommand` | 每次提交 prompt 时运行 `prompt_audit_log.ps1`，在 `docs/audit/prompt_logs/` 生成独立日志文件（含 Prompt-ID、时间戳、原文），同时更新 `.kiro/.last_prompt_id.json`。不触发 LLM。 |
| `audit-reminder.kiro.hook` | `agentStop` | `runCommand` | Agent 执行结束时运行 `audit_reminder.ps1`，若检测到待审计状态则通过 stderr 提醒用户运行 `/audit`。15 分钟限频，避免频繁打扰。 |
| `run-audit-writer.kiro.hook` | `userTriggered` | `askAgent` | 用户手动触发（`/audit`），启动 `audit-writer` 子代理执行完整审计流程：变更影响审查 → 文档同步 → 审计落盘 → 刷新一览表 → 清除待审计标记。仅返回极短回执。 |
| `db-docs-sync.kiro.hook` | `userTriggered` | `askAgent` | 用户按需触发，对比 Postgres 实际 schema 与 `docs/database/` 文档，自动补全或更新缺失/过时的表结构说明。 |

### 2.2 已禁用（2 个 askAgent）

| Hook 文件 | 事件类型 | 禁用原因 |
|---|---|---|
| `change-impact-review.kiro.hook` | `agentStop` | 原设计为每次 agentStop 自动执行变更影响审查 + 审计落盘。因上下文膨胀严重，已改为手动 `/audit` 子代理流程替代。 |
| `db-schema-doc-enforcer.kiro.hook` | `fileEdited`（`*.sql` 等） | 原设计为保存 SQL 文件时自动更新 DB 文档。因频繁触发导致上下文浪费，已改由 `/audit` 流程统一处理。 |

### 2.3 设计要点

- **promptSubmit 钩子全部使用 `runCommand`**（纯 Shell），不消耗 LLM token
- **agentStop 提醒也是 `runCommand`**，仅通过 stderr 输出一行文字
- **重型 askAgent 操作全部改为 `userTriggered`**，由用户主动决定何时执行
- 两个曾经自动触发的 askAgent Hook 已禁用，避免每次交互都产生大量审计写入

---

## 3. Steering（引导文件）

共 8 个文件，位于 `.kiro/steering/`。通过 front-matter 中的 `inclusion` 字段控制注入时机：

### 3.1 始终注入（`inclusion: always`）— 5 个

| 文件 | 内容摘要 | Token 开销 |
|---|---|---|
| `governance.md` | 审计治理规则：何时必须审计、执行方式（自动判定 + 半自动执行）、审计产物清单 | 小 |
| `language-zh.md` | 语言规范：输出简体中文、UTF-8 编码、注释只写"为什么" | 极小 |
| `product.md` | 产品概述：ETL/后端/小程序/GUI 功能、业务上下文、主要入口 | 中 |
| `structure-lite.md` | 项目结构精简版：顶层目录 + 关键模块边界 + 架构要点摘要 | 中 |
| `tech.md` | 技术栈：依赖、数据库、测试、常用命令、配置体系 | 中 |

### 3.2 条件注入（`inclusion: fileMatch`）— 1 个

| 文件 | 匹配模式 | 内容摘要 |
|---|---|---|
| `db-docs.md` | `**/migrations/**`, `**/*.sql`, `**/*schema*.*`, `**/*ddl*.*`, `**/*.prisma` | 数据库文档规则：变更时必须同步 `docs/database/`，含最低文档要求 |

### 3.3 手动加载（`inclusion: manual`）— 1 个

| 文件 | 内容摘要 |
|---|---|
| `steering-readme-maintainer.md` | 变更影响审查快速清单（作为 `/slash command` 参考），详细流程指向同名 Skill |

### 3.4 按需自动加载（`inclusion: auto`）— 1 个

| 文件 | 名称 | 内容摘要 |
|---|---|---|
| `structure.md` | `structure-full` | 完整目录树 + 架构模式详解。仅在大型重构、模块迁移或跨子系统变更时加载 |

### 3.5 设计要点

- **`structure-lite.md`（always）vs `structure.md`（auto）**：日常对话只注入精简版（~50 行），完整目录树（~120 行）仅在需要时手动加载，节省约 60% 的结构信息 token
- **`db-docs.md` 使用 fileMatch**：只有当上下文中出现 SQL/迁移文件时才注入，避免无关对话浪费 token
- **`steering-readme-maintainer.md` 使用 manual**：作为快速参考，不自动注入

---

## 4. Skills（技能）

共 3 个 Skill，位于 `.kiro/skills/`。每个 Skill 包含 `SKILL.md`（定义）和 `assets/`（模板）。

### 4.1 change-annotation-audit（变更标注与审计）

- **触发条件**：任何实质性代码/文档修改（特别是逻辑、资金、接口、DB 改动）
- **产出**：
  - `docs/audit/changes/<YYYY-MM-DD>__<slug>.md`（审计记录）
  - 每个被改文件内的 `AI_CHANGELOG` 条目
  - 每处逻辑变更附近的 `CHANGE` 标记注释（含 intent、assumptions、边界条件）
- **模板**：`audit-record-template.md`、`file-changelog-templates.md`

### 4.2 steering-readme-maintainer（文档同步审查）

- **触发条件**：业务规则/ETL/API/鉴权/小程序交互等逻辑改动
- **产出**：
  - 评估并更新 `product.md` / `tech.md` / `structure-lite.md` / `structure.md` / `README.md`
  - 输出审计友好摘要（Changed / Why / Risk / Verify）
- **模板**：`steering-update-checklist.md`

### 4.3 bd-manual-db-docs（数据库文档维护）

- **触发条件**：DDL/迁移脚本修改（表/字段/类型/约束/索引/外键变更）
- **产出**：
  - `docs/database/` 下的 Schema Change Log（变更日志）
  - Table Structure Doc（表结构文档更新）
  - Rollback & Verification（回滚要点 + ≥3 条验证 SQL）
- **模板**：`schema-changelog-template.md`、`table-structure-template.md`

### 4.4 设计要点

- Skills 不会自动注入上下文，仅在被 Agent 或子代理显式调用时激活
- 三个 Skill 形成完整的审计闭环：**代码标注** + **文档同步** + **DB 文档**
- 主对话中不直接调用 Skill，而是由 `audit-writer` 子代理统一调度

---

## 5. 自定义 Agent（子代理）

### 5.1 audit-writer

- **位置**：`.kiro/agents/audit-writer.md`
- **工具权限**：`read`、`write`、`shell`
- **职责**：专职"审计收口/后处理写入"，不依赖主对话上下文
- **输入来源**：
  - `git status --porcelain` + `git diff`（本次未提交变更）
  - `.kiro/.last_prompt_id.json`（最新 Prompt-ID）
  - `docs/audit/prompt_logs/`（prompt 原文，用于溯源）
- **执行策略**：
  1. 判断是否逻辑改动
  2. 按需调用三个 Skill
  3. 清除 `.kiro/.audit_state.json` 待审计标记
  4. 运行 `scripts/gen_audit_dashboard.py` 刷新审计一览表
- **输出约束**：强制极短回执（done / files_written / next_step），避免审计细节淹没主对话

---

## 6. MCP（Model Context Protocol）

### 6.1 工作区级配置

文件：`.kiro/settings/mcp.json`

```json
{ "mcpServers": {} }
```

工作区级未定义任何 MCP 服务器（全部在用户级配置）。

### 6.2 用户级配置（全局）

文件：`~/.kiro/settings/mcp.json`

| 服务器名 | 命令 | 用途 | 状态 | 自动批准 |
|---|---|---|---|---|
| `filesystem` | `npx @modelcontextprotocol/server-filesystem` | 文件系统读写（作用域：`C:\NeoZQYY`） | 启用 | 全部 |
| `git` | `uvx mcp-server-git@2025.12.18` | Git 操作（status/diff/commit/log 等） | 启用 | `git_status` |
| `postgres` | `uvx postgres-mcp --access-mode=unrestricted` | PostgreSQL 数据库操作（查询/DDL/健康检查/索引分析） | 启用 | 全部 |
| `playwright` | `npx @playwright/mcp@latest` | 浏览器自动化（截图/快照/点击/表单填写） | 启用 | 无 |
| `openapi` | `uv tool run awslabs.openapi-mcp-server` | OpenAPI 规范交互（基于 `backend-api.json`） | 启用 | 全部 |
| `trivy` | `trivy mcp` | 安全漏洞扫描 | 禁用 | — |

### 6.3 设计要点

- MCP 配置放在用户级而非工作区级，方便跨项目复用
- `postgres` 使用 `unrestricted` 模式，支持 DDL 和数据操作（配合审计流程保障安全）
- `git` 仅自动批准 `git_status`，其他操作需确认
- `trivy` 当前禁用，预留安全扫描能力

---

## 7. 辅助脚本

位于 `.kiro/scripts/`，全部为 PowerShell 脚本，由 Hook 的 `runCommand` 调用。

| 脚本 | 调用者 | 功能 |
|---|---|---|
| `audit_flagger.ps1` | `audit-flagger` Hook | 解析 `git status`，匹配高风险路径（`api/`、`cli/`、`config/`、`database/`、`loaders/` 等），计算变更指纹（SHA1），写入 `.kiro/.audit_state.json` |
| `audit_reminder.ps1` | `audit-reminder` Hook | 读取 `.audit_state.json`，若 `audit_required=true` 且距上次提醒 ≥15 分钟，则通过 stderr 输出提醒；工作树干净时自动清除标记 |
| `prompt_audit_log.ps1` | `prompt-audit-log` Hook | 生成 Prompt-ID（`P<yyyyMMdd-HHmmss>` 格式），将 prompt 原文写入 `docs/audit/prompt_logs/prompt_log_<timestamp>.md`，更新 `.kiro/.last_prompt_id.json` |

### 共同特征

- 所有脚本使用 `Taipei Standard Time`（UTC+8）时区
- 所有脚本在异常时静默退出（`exit 0`），绝不阻塞 prompt 提交
- 输出编码统一 UTF-8
- 过长 prompt（>20000 字符）自动截断，防止展开的 `#context` 污染日志

---

## 8. 上下文优化策略

本项目在 Agent 配置中做了多层上下文节省优化，核心目标是：**在保证审计完整性的前提下，最小化每次对话的 token 消耗**。

### 8.1 审计写入卸载（最大优化）

| 优化前 | 优化后 | 节省效果 |
|---|---|---|
| `change-impact-review` Hook 在每次 `agentStop` 自动触发，执行完整审计写入（含文档同步、AI_CHANGELOG、CHANGE 注释、DB 文档） | 改为 `userTriggered` + `audit-writer` 子代理，主对话仅收到极短回执 | 每次交互节省 **数千~上万 token**（审计产物的生成和写入全部在子代理独立上下文中完成） |

### 8.2 Hook 动作类型选择

| 优化点 | 说明 |
|---|---|
| promptSubmit 钩子全部用 `runCommand` | 纯 Shell 执行，零 LLM token 消耗 |
| agentStop 提醒用 `runCommand` | 仅 stderr 一行文字，不触发 Agent 回复 |
| 禁用两个自动 `askAgent` Hook | `change-impact-review` 和 `db-schema-doc-enforcer` 曾在每次交互/文件保存时触发 Agent，现已禁用 |

### 8.3 Steering 分层注入

| 策略 | 实现 | 节省效果 |
|---|---|---|
| 结构信息分级 | `structure-lite.md`（always，~50 行）vs `structure.md`（auto/manual，~120 行） | 日常对话节省约 60% 结构信息 token |
| DB 规则条件注入 | `db-docs.md` 使用 `fileMatch`，仅在上下文含 SQL 文件时注入 | 非 DB 相关对话零开销 |
| 审查清单手动加载 | `steering-readme-maintainer.md` 使用 `manual` | 仅在用户主动引用时注入 |
| always 文件精简化 | `governance.md` 采用 Lite 版本，只保留最小硬约束 | 相比完整版节省约 70% |

### 8.4 Prompt 日志优化

| 优化点 | 说明 |
|---|---|
| 独立文件而非追加 | 每次 prompt 写独立文件（`prompt_log_<timestamp>.md`），避免单文件无限增长 |
| 自动截断 | prompt 超过 20000 字符时截断，防止展开的 `#context` 污染日志 |
| 不触发 LLM | 日志写入完全由 Shell 脚本完成 |

### 8.5 子代理隔离

| 优化点 | 说明 |
|---|---|
| 独立上下文 | `audit-writer` 在独立上下文中执行，不污染主对话 |
| 自给自足 | 子代理通过 `git status/diff` + `.last_prompt_id.json` 获取信息，不依赖主对话传递 |
| 极短回执 | 强制只返回 done / files_written / next_step，避免审计细节回流主对话 |

### 8.6 限频机制

| 机制 | 说明 |
|---|---|
| 审计提醒 15 分钟限频 | `audit_reminder.ps1` 记录 `last_reminded_at`，避免每次 agentStop 都提醒 |
| 变更指纹去重 | `audit_flagger.ps1` 计算文件列表 SHA1，相同指纹不重复标记 |

---

## 9. 组件协作流程图

```
┌─────────────────────────────────────────────────────────────────┐
│                        用户提交 Prompt                           │
└──────────┬──────────────────────────────────────────────────────┘
           │
           ├──→ [Hook: promptSubmit] audit_flagger.ps1
           │      └─→ git status → 匹配高风险路径 → 写 .audit_state.json
           │
           ├──→ [Hook: promptSubmit] prompt_audit_log.ps1
           │      └─→ 生成 Prompt-ID → 写 prompt_logs/ + .last_prompt_id.json
           │
           ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Kiro 主对话执行                               │
│                                                                   │
│  注入 Steering：governance + language-zh + product                │
│                 + structure-lite + tech                           │
│                 + db-docs（仅当上下文含 SQL 文件）                  │
│                                                                   │
│  可用 MCP：postgres / git / filesystem / playwright / openapi     │
│                                                                   │
│  可用 Skills：（通常不在主对话直接调用，由子代理调度）                │
└──────────┬──────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────────┐
│  [Hook: agentStop] audit_reminder.ps1                            │
│    └─→ 检查 .audit_state.json                                    │
│    └─→ 若 audit_required=true 且 ≥15min → stderr 提醒            │
└──────────┬──────────────────────────────────────────────────────┘
           │
           ▼  （用户决定是否手动触发）
┌─────────────────────────────────────────────────────────────────┐
│  [Hook: userTriggered] /audit                                    │
│    └─→ 启动 audit-writer 子代理（独立上下文）                      │
│         ├─→ git status/diff + .last_prompt_id.json               │
│         ├─→ Skill: change-annotation-audit                       │
│         ├─→ Skill: steering-readme-maintainer                    │
│         ├─→ Skill: bd-manual-db-docs（仅 DB 变更时）              │
│         ├─→ 写审计产物 → 刷新 dashboard                           │
│         └─→ 清除 .audit_state.json → 返回极短回执                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 附录：文件清单

```
.kiro/
├── agents/
│   └── audit-writer.md              # 审计子代理定义
├── hooks/
│   ├── audit-flagger.kiro.hook      # [启用] promptSubmit → runCommand
│   ├── audit-reminder.kiro.hook     # [启用] agentStop → runCommand
│   ├── change-impact-review.kiro.hook # [禁用] agentStop → askAgent
│   ├── db-docs-sync.kiro.hook       # [启用] userTriggered → askAgent
│   ├── db-schema-doc-enforcer.kiro.hook # [禁用] fileEdited → askAgent
│   ├── prompt-audit-log.kiro.hook   # [启用] promptSubmit → runCommand
│   └── run-audit-writer.kiro.hook   # [启用] userTriggered → askAgent
├── scripts/
│   ├── audit_flagger.ps1            # 高风险判定脚本
│   ├── audit_reminder.ps1           # 审计提醒脚本（15min 限频）
│   └── prompt_audit_log.ps1         # Prompt 日志记录脚本
├── settings/
│   └── mcp.json                     # 工作区 MCP 配置（空）
├── skills/
│   ├── bd-manual-db-docs/           # DB 文档维护 Skill
│   ├── change-annotation-audit/     # 变更标注审计 Skill
│   └── steering-readme-maintainer/  # 文档同步审查 Skill
├── steering/
│   ├── db-docs.md                   # [fileMatch] DB 文档规则
│   ├── governance.md                # [always] 审计治理
│   ├── language-zh.md               # [always] 语言规范
│   ├── product.md                   # [always] 产品概述
│   ├── steering-readme-maintainer.md # [manual] 审查快速参考
│   ├── structure-lite.md            # [always] 项目结构精简版
│   ├── structure.md                 # [auto] 完整目录树
│   └── tech.md                      # [always] 技术栈
├── .audit_state.json                # 审计状态（运行时）
└── .last_prompt_id.json             # 最新 Prompt-ID（运行时）

~/.kiro/settings/mcp.json            # 用户级 MCP 配置（6 个服务器）
```