root/Neo-ZQYY

Fork 0

Files

Neo 4eac07da47 在准备环境前提交次全部更改。

2026-02-19 08:35:13 +08:00

20 KiB

Raw Blame History

Kiro Agent 配置总览

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

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

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

{ "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 个服务器）

20 KiB Raw Blame History Unescape Escape