Neo
a99bbd9a74
历史教训 (F2-1A): OpenAPI 抓取脚本 2026-04-06 commit 779b2f6 被
Claude Opus 4.6 在批量清理 1155 个废弃文件时误归档到
_DEL/_DEL/scripts/ops/, 导致 docs/contracts/openapi/backend-api.json
28 天 stale (137 paths -> 实际 167 paths, 缺 30 端点)。
Neo 反馈: 建立机制不要让类似事件再发生。
F3-2C 配套需求: 建立 docs/ai/system-prompts/ 独立 MD 体系后,
维护流程依赖 3 步同步 (元信息日期 / 同步历史 / _INDEX.md 状态表),
容易遗漏造成漂移。
新增 2 个 PostToolUse hook (Edit|Write matcher, timeout 5s):
- post_edit_openapi_reminder.py: 改 apps/backend/app/routers/*.py
提醒重抓 OpenAPI 具体命令
(.venv/Scripts/python.exe scripts/ops/_export_openapi.py)
- post_edit_prompt_sync_reminder.py: 改 docs/ai/system-prompts/app*.md
提醒 3 步同步 (元信息 / 同步历史 / _INDEX.md 状态表)
settings.json 注册 2 个 hook 条目 (PostToolUse 末尾追加)。
spec-close.md 步骤 5 文档同步表:
- OpenAPI 行升级为具体命令 (避免手工同步漂移描述)
- 新增 docs/ai/system-prompts/app*.md 同步行
验证: stdin 模拟测试 3 场景全部符合预期 (匹配 router 输出 OpenAPI 提醒;
匹配 system-prompts MD 输出 prompt 同步提醒; 不匹配静默)。
详见 docs/audit/changes/2026-05-05__wave1_f2_1b_defense_hooks.md
审计目录（docs/audit/）
项目级统一审计落地点。所有模块（ETL、后端、小程序、管理后台等）的审计产物均写入此目录。
子目录与文件
| 目录/文件 | 说明 |
|---|---|
changes/ |
AI 逐次变更审计记录（<YYYY-MM-DD>__<slug>.md） |
prompt_logs/ |
Prompt 日志文件（每次 prompt 生成一个独立文件，按时间戳命名） |
session_logs/ |
全量会话记录（按 YYYY-MM/DD/ 分层），含双索引和 LLM 操作摘要。详见 SESSION-LOG-GUIDE.md |
audit_dashboard.md |
审计一览表（自动生成，勿手动编辑） |
SESSION-LOG-GUIDE.md |
Session 日志使用指南（索引字段、查询方法、典型场景） |
维护约定
prompt_logs/由prompt-audit-logHook 自动管理，请勿手动编辑session_logs/由agentStopHook 自动提取，索引由提取脚本自动更新audit_dashboard.md由/audit流程自动刷新，也可通过python scripts/audit/gen_audit_dashboard.py手动重新生成- 变更审计记录由
/audit流程（audit-writer 子代理）生成，包含session_id字段与 Session 日志双向关联 - 历史记录（迁移前 ETL 子项目的审计）已合并至此目录
审计追溯链
Prompt 日志 ←→ Session 日志 ←→ 变更审计记录
(用户说了什么) (AI 做了什么) (正式变更文档)
通过 Prompt-ID 和 Session-ID 可在三者之间双向追溯。详见 SESSION-LOG-GUIDE.md。