375 lines
20 KiB
Markdown
375 lines
20 KiB
Markdown
# 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 个服务器）
|
||
```
|