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

docs/migrate/oldworkspace-kiro-agent-config-summary.md

@@ -0,0 +1,374 @@
+# 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 个服务器）
+```