微信小程序页面迁移校验之前 P5任务处理之前

.kiro/agents/audit-writer.md

@@ -8,7 +8,7 @@ tools: ["read", "write", "shell"]
 
 ## 核心原则：从预构建上下文工作，禁止全盘扫描
 
-你的唯一输入是 `.kiro/.audit_context.json`（由 `build_audit_context.py` 预构建）。
+你的唯一输入是 `.kiro/state/.audit_context.json`（由 `build_audit_context.py` 预构建）。
 该文件已包含所有你需要的信息：
 
 | 字段 | 来源 | 内容 |
@@ -22,7 +22,9 @@ tools: ["read", "write", "shell"]
 | `compliance.new_migration_sql` | compliance-prescan | 新增迁移 SQL 列表 |
 | `compliance.has_bd_manual` | compliance-prescan | 是否已有 BD_Manual 文档 |
 | `compliance.has_ddl_baseline` | compliance-prescan | 是否已更新 DDL 基线 |
-| `external_files` | agent-on-stop | 非 Kiro 操作产生的变更文件（CLI/脚本/手动编辑） |
+| `compliance.api_changed` | compliance-prescan | 是否有接口相关文件变更 |
+| `compliance.openapi_spec_stale` | compliance-prescan | OpenAPI spec 是否需要重新导出 |
+| `session_diff` | agent-on-stop (file baseline) | 本次对话期间的精确变更：`added`/`modified`/`deleted` |
 | `prompt_id` / `latest_prompt_log` | prompt-audit-log | Prompt-ID 与原文（溯源用） |
 
 **禁止操作**：
@@ -51,18 +53,60 @@ tools: ["read", "write", "shell"]
 ## 执行策略（从 context 驱动，不做冗余扫描）
 
 ### 步骤 1：读取上下文
-读取 `.kiro/.audit_context.json`，提取关键字段。
+读取 `.kiro/state/.audit_context.json`，提取关键字段。
+
+### 步骤 1b：读取 Session 索引
+读取 `docs/audit/session_logs/_session_index.json`，按 `startTime` 找到与 `audit_context.json` 中 `prompt_at` 最接近的 entry（非 `is_sub` 的主对话）。提取：
+- `description`：作为审计记录的「操作摘要」（比从 diff 推断更准确、更完整）
+- `summary.files_modified` / `summary.files_created`：交叉验证 `session_diff`
+- executionId 前 8 位：作为 `session_id` 写入审计记录，建立双向链接
+- `summary.sub_agents`：记录本次对话调用了哪些子代理
+- `summary.errors`：标注执行中的异常
+
+若索引不存在或无匹配 entry，跳过此步骤，不影响后续流程。
 
 ### 步骤 2：审计落盘（按需调用 skill）
 根据 `reasons` 判断需要哪些 skill：
 - 含 `dir:backend` / `dir:etl` / `dir:shared` 等 → 调用 `steering-readme-maintainer`
 - 含任意高风险标签 → 调用 `change-annotation-audit`（写 docs/audit/changes/ + AI_CHANGELOG + CHANGE 注释）
-- 含 `db-schema-change` → 调用 `bd-manual-db-docs`
+- 含 `db-schema-change` → 调用 `bd-manual-db-docs`，并执行 DB 文档全量对账（见步骤 2b）
 
-若 `external_files` 非空，在审计记录（`docs/audit/changes/` 文件）中增加「外部变更」段落：
-- 列出所有外部变更文件路径
-- 标注来源为"非 Kiro 操作（CLI/脚本/手动编辑）"
-- 若外部变更涉及高风险路径，额外标注 ⚠️
+所有审计记录中涉及日期时间的字段，必须精确到秒（格式：`YYYY-MM-DD HH:MM:SS`，时区 Asia/Shanghai）。包括但不限于：审计记录头部的"日期"、AI_CHANGELOG 条目的时间戳、CHANGE 标记注释中的日期。
+
+若 `session_diff` 中有 `added` 或 `deleted` 文件，在审计记录中增加「本次对话文件变更」段落，分别列出新增和删除的文件。
+
+若步骤 1b 成功获取了 Session 信息，在审计记录头部元数据中增加：
+- `session_id`：executionId 前 8 位（如 `f29acdea`）
+- `操作摘要`：Session 索引中的 `description`（LLM 生成的操作摘要）
+- `session_path`：Session 日志文件的相对路径（`output_dir` 字段值）
+
+审计记录头部模板：
+```markdown
+# 变更审计记录：<标题>
+
+| 字段 | 值 |
+|------|-----|
+| 日期 | YYYY-MM-DD HH:MM:SS |
+| Prompt-ID | <从 audit_context> |
+| Session-ID | <executionId 前 8 位> |
+| Session 路径 | <output_dir 相对路径> |
+
+## 操作摘要
+<Session 索引中的 description，或从 diff 推断的摘要>
+```
+
+### 步骤 2b：DB 文档全量对账（当 reasons 含 db-schema-change 时）
+当 `reasons` 含 `db-schema-change` 时，除了调用 `bd-manual-db-docs` skill 处理本次变更外，还必须执行全量对账：
+
+1. 连接测试库（使用 pg power 的 `pg-etl-test` / `pg-app-test`），查询 `information_schema.tables` 和 `information_schema.columns` 获取所有表和字段的实际结构
+2. 扫描 `docs/database/` 下现有文档，逐表对比：
+   - 文档中缺失的表 → 新建表结构文档
+   - 文档中字段与实际不一致（类型、nullable、默认值等）→ 更新文档
+   - 文档中存在但数据库已删除的表 → 在文档中标注已废弃
+3. 输出对账摘要到审计记录中，列出：新增文档数、更新文档数、废弃标注数
+4. 所有文档输出到 `docs/database/`，遵循现有目录结构和模板格式
+
+注意：全量对账使用测试库（TEST_DB_DSN），禁止连接正式库。
 
 ### 步骤 3：文档校对补齐
 遍历 `compliance.code_without_docs`，对每个缺失项：
@@ -71,9 +115,10 @@ tools: ["read", "write", "shell"]
 
 | 代码路径前缀 | 应同步更新的文档 |
 |---|---|
-| `apps/backend/app/routers/` | `apps/backend/docs/API-REFERENCE.md` |
+| `apps/backend/app/routers/` | `apps/backend/docs/API-REFERENCE.md` + `docs/contracts/openapi/backend-api.json` |
 | `apps/backend/app/services/` | `apps/backend/docs/API-REFERENCE.md` + `apps/backend/README.md` |
-| `apps/backend/app/auth/` | `apps/backend/docs/API-REFERENCE.md` + `apps/backend/README.md` |
+| `apps/backend/app/auth/` | `apps/backend/docs/API-REFERENCE.md` + `apps/backend/README.md` + `docs/contracts/openapi/backend-api.json` |
+| `apps/backend/app/schemas/` | `docs/contracts/openapi/backend-api.json` |
 | `apps/etl/connectors/feiqiu/tasks/` | `apps/etl/connectors/feiqiu/docs/etl_tasks/` |
 | `apps/etl/connectors/feiqiu/loaders/` | `apps/etl/connectors/feiqiu/docs/etl_tasks/` |
 | `apps/etl/connectors/feiqiu/scd/` | `apps/etl/connectors/feiqiu/docs/business-rules/scd2_rules.md` |
@@ -90,8 +135,48 @@ tools: ["read", "write", "shell"]
 - 若 `compliance.new_migration_sql` 非空且 `compliance.has_ddl_baseline` 为 false：
   - 在审计记录中标注 ⚠️ DDL 基线待合并
 
-### 步骤 5：收尾
-- 把 `.kiro/.audit_state.json` 的 `audit_required` 置为 false，清空 `reasons`/`changed_files`/`last_reminded_at`
+### 步骤 4b：OpenAPI Spec 同步检查
+- 若 `compliance.api_changed` 为 true 且 `compliance.openapi_spec_stale` 为 true：
+  - 在审计记录中标注 ⚠️ 接口代码已变更但 OpenAPI spec 未同步
+  - 运行 `python scripts/ops/_export_openapi.py` 重新导出 spec（需后端可导入）
+  - 若导出失败（后端未启动等），在审计记录中标注待手动导出
+  - 导出成功后提醒用户重连 OpenAPI Power 的 MCP server 以加载新 spec
+- 若 `compliance.api_changed` 为 true 且 `compliance.openapi_spec_stale` 为 false：
+  - spec 已同步更新，无需额外操作
+
+### 步骤 5：改动注解（Change Annotations）
+
+对本次审计涉及的所有变更文件，在审计记录（`docs/audit/changes/<YYYY-MM-DD>__<slug>.md`）中生成逐文件的改动注解段落。
+
+注解内容包括：
+- 文件路径
+- 变更类型（新增 / 修改 / 删除）
+- 原始原因：为什么要做这个改动（从 `latest_prompt_log` 和 diff 上下文推断用户意图）
+- 思路分析：改动的技术思路和设计决策（从 diff 内容和代码结构推断）
+- 修改结果：改动后的效果和影响范围
+
+格式模板（写入审计记录的 `## 改动注解` 段落）：
+
+```markdown
+## 改动注解
+
+### `<文件路径>`
+- 变更类型：新增 / 修改 / 删除
+- 原始原因：<从 prompt log 和 diff 推断的改动动机>
+- 思路分析：<技术思路、设计决策、为什么选择这种实现方式>
+- 修改结果：<改动后的效果、影响范围、与其他模块的关联>
+```
+
+执行规则：
+- 只对 `high_risk_files` 和 `session_diff.added` 中的文件写详细注解
+- 对非高风险的 `session_diff.modified` 文件写简要一行注解即可
+- 对 `session_diff.deleted` 文件只记录删除原因
+- 注解内容从 `high_risk_diff`、`latest_prompt_log`、文件内容综合推断，不要编造
+- 若某文件的 diff 被截断，可对该单个文件运行 `git diff HEAD -- <file>` 获取完整 diff
+- 注解语言使用简体中文
+
+### 步骤 6：收尾
+- 把 `.kiro/state/.audit_state.json` 的 `audit_required` 置为 false，清空 `reasons`/`changed_files`/`last_reminded_at`
 - 执行 `python scripts/audit/gen_audit_dashboard.py` 刷新审计一览表
 
 ## 输出（强制极短回执）