## ⚠️ 强制入口点 — 在任何其他操作之前执行 **第1步：读取schema.sql** # 始终首先阅读模式来理解表、约束、视图 cat .claude/skills/audit-flow/schema.sql **第 2 步：检查数据库是否存在 - 切勿重新创建** # 检查现有数据库 ls -la .audit/audit.db 2>/dev/null && echo "数据库存在 - 不要重新创建" || echo“无数据库 - 可以安全初始化” **第3步：如果数据库存在，则显示当前状态** python .claude/skills/audit-flow/scripts/audit.py 列表 ### 🚫 禁止行为行动|为什么被禁止 ---|--- `rm .audit/audit.db` |销毁审计历史记录当数据库存在时`audit.py init`覆盖现有数据 `删除表` |销毁审计历史记录当数据库存在时`sqlite3 .audit/audit.db < schema.sql`覆盖现有数据 **规则：** 如果 `.audit/audit.db` 存在，则仅使用 `audit.py list`、`show`、`export` 或 INSERT 操作。永远不要重新创建。 ** ** # 审核流程使用 SQLite 持久性对系统流进行交互式跟踪。支持每个会话多个命名流、非线性流（分支/合并）和多格式导出。 ## 组织原则 **按用途划分的目录结构：** * **审核/文档/合规性：** `docs/audits/{name}-{YYYY-MM-DD}/` * **创意/头脑风暴：** `docs/ideation/{name}-{YYYY-MM-DD}.md` （单个文件，没有子目录，除非需要工件） * **调试/事件审查：** `docs/audits/{name}-{YYYY-MM-DD}/` （与审核相同 - 捕获证据） * **架构审查：** `docs/audits/{name}-{YYYY-MM-DD}/` （与审计相同 — 捕获结构分析） **所需文件：** * INDEX.md（清单，入口点） * README.md（执行摘要） * {name}-audit.md（流程跟踪） **延迟初始化：**仅当工件存在时才创建子目录 * `屏幕截图/` `网络跟踪/` `图表/` `代码示例/` `测试结果/` `证据/` **命名：** `{审计名称}-{类型}.md` ## DB 优先原则 **不变：** SQLite = 唯一的事实来源。上下文窗口：易失性、压缩而不通知、幻觉状态。 **🚨 关键：切勿破坏现有数据** * 如果 `.audit/audit.db` 存在 → 它包含不可替代的审计历史记录 * 当数据库存在时，永远不要运行 `init` — 使用 `list` 来查看那里有什么 * 切勿删除、删除或重新创建 — 只能追加 **限制：** 运营|规则|合理化受阻 ---|---|--- **条目** |首先读取 `schema.sql`，然后检查数据库是否存在 | “我要开始工作了” **初始化** |仅当“.audit/audit.db”不存在时 | “让我重新初始化，重新开始” 架构|在执行任何 SQLite 命令之前阅读 `schema.sql` — 首先了解表、约束、视图 | “我从上下文中了解了模式” 写 |在移动到下一个代码位置之前插入每个元组/边/查找 | “我将在最后批量插入” 阅读 |在引用元组 ID、计数或流结构之前从 DB 中进行 SELECT | “我记得到目前为止的流程” 出口|仅“audit.py导出”——永远不会从上下文生成mermaid/markdown | “让我直接生成美人鱼吧” 简历 |在引用先前元组的任何操作之前`audit.py show ` “我在上下文中有完整的痕迹” 参考|从数据库查询元组 ID — ID 是数据库分配的，从不推断 | “元组 ID 应该是 N” **默认** | **当不确定流程状态时→在继续之前查询数据库** | _（任何未列出的合理化）_ **检查点：** 每 5 个元组 → `audit.py show ` ** ** ## 交互式工作流程 - 始终询问用户 ### 1\.会话开始 - 询问：姓名：___ 目的：安全审计|文档 |合规|构思|集思广益|调试|架构评论 |事件回顾描述：___（可选）立即初始化目录。生成工件时延迟创建子目录。 ### 2\.粒度 - 询问： [细] 函数级跟踪（~50-200 元组）用途：安全审计、调试 [粗略] 边界级跟踪（~10-30 元组）用途：文档、高级流程选择：细/粗 ### 3\.跟踪期间：在决策点询问：更深入地追踪？标记关注？添加发现（严重性）？笔记？ ### 4\.关于出口：询问格式：`json | yaml |医学博士 |美人鱼|全部` 导出后：生成 INDEX.md 清单。按类型组织工件。修剪空目录。 ## 快速参考命令 |目的 ---|--- `/审核流程开始` |新会话（名称、目的、粒度） `/audit-flow 流程{名称}` |将新流程添加到会话 `/audit-flow add {layer} {desc}` |将元组添加到当前流 `/audit-flow 链接{从} {到} {rel}` |创建边（支持分支条件） `/audit-flow 发现 {desc}` |记录发现 `/audit-flow show` |查看会话/流详细信息 `/审计流导出` |导出（json/yaml/md/mermaid） `/audit-flow git-setup` |配置 git merge/diff 驱动程序（一次） **层：** `代码` | `API` | `网络` | `验证` | `数据` **关系：** `触发` | `阅读` | `写` | `验证` | '转变' | '分支机构' | `合并` ## 关系的语义规则关系 |意义|使用时间 |不适合 ---|---|---|--- `触发` | A 导致 B 执行 |函数调用、事件处理程序、HTTP 请求 |静态观察 `阅读` | A 消耗来自 B 的数据 | Cookie 读取、数据库查询、配置查找 |突变 `写` | A 改变 B 中的数据 | Cookie 写入、DB 插入、状态更新 |只读访问 `验证` | A 检查/验证 B |身份验证检查、输入验证、过期检查 |链接分析师观察 '转变' | A 为 B 转换/映射数据 |令牌交换、响应格式化 |无关处理 '分支机构' | A 有条件路径 | if/else、切换、错误与成功 | **必须有状况标签** `合并` |多条路径汇聚于 B |并行路径重新连接、错误恢复 |单路流 **关键：分支必须有条件。** 每个分支边缘都需要一个描述路径的“条件”。示例：“BRANCHES [令牌已过期]”与“BRANCHES [令牌有效]”。 ## 观察与流程步骤 **流程步骤** = 系统所做的事情（函数调用、数据读取、网络请求）。通过跟踪代码验证。 **观察** = 分析师注释的内容（缺失的功能、潜在的风险）。记录为 **findings** ，而不是元组。 **错误模式：** T50“没有跨表同步”←观察，不是系统操作 T51“反应状态不共享”←观察 T50 --VALIDATES--> T51 ← 将观察值链接为流 **正确模式：** -- 记录为查找结果：插入结果（flow_id、session_id、严重性、类别、描述）值 (?, ?, '中等', '状态管理', '无跨选项卡同步：React 状态未跨选项卡共享'); **规则：** 切勿将观察结果与验证链接起来。如果描述系统不做什么，请使用发现。 ## 数据模型会话（审核容器） └── 流（命名为DAG，有入口点） └── 元组（节点：层+动作+主题） └── 边（关系+可选条件） ## 存储和 CLI # 核心 python .claude/skills/audit-flow/scripts/audit.py init # 初始化数据库 python .claude/skills/audit-flow/scripts/audit.py list # 列出会话 python .claude/skills/audit-flow/scripts/audit.py show # 显示流程 python .claude/skills/audit-flow/scripts/audit.py show # 显示流程详细信息 python .claude/skills/audit-flow/scripts/audit.py export # 导出全部 python .claude/skills/audit-flow/scripts/audit.py export -f # 导出一个流程 python .claude/skills/audit-flow/scripts/audit.py validate # 验证流程 # Git 集成 python .claude/skills/audit-flow/scripts/audit.py git-setup # 配置合并/差异驱动程序（一次） python .claude/skills/audit-flow/scripts/audit.py db-merge %O %A %B # Git 合并驱动程序（自动调用） # CSV 备份/可移植性（可选） python .claude/skills/audit-flow/scripts/audit.py csv-export # 数据库 → .audit/csv/*.csv python .claude/skills/audit-flow/scripts/audit.py csv-import # .audit/csv/*.csv → 数据库 python .claude/skills/audit-flow/scripts/audit.py csv-merge # 合并两个 CSV 集 ## 非线性流 **分支：** 一个元组→多个带条件的出边 INSERT INTO 边（from_tuple、to_tuple、关系、条件） VALUES (5, 6, '分支', '令牌有效'), (5, 7, '分支机构', '令牌已过期'); **合并：** 多个元组 → 一个元组 INSERT INTO 边（from_tuple、to_tuple、关系）值（6、8、“触发器”）、 (9, 8, '合并'); -- 刷新路径合并回来 ## 文件 * [scripts/audit.py]() \- 所有命令的 CLI（init、list、show、export、validate、db-merge、git-setup、csv-*） * [COMMANDS.md]() \- 详细的 SQL 参考 * [EXAMPLES.md]() \- 非线性流的完整示例 * [schema.sql]() \- 数据库模式 * `.gitattributes` \-audit.db 的 Git 合并/差异驱动程序配置 ## Git 上下文会话启动时捕获：提交哈希、分支、工作树状态。包括在所有出口中。 ## 美人鱼验证导出前运行 `python .claude/skills/audit-flow/scripts/audit.py validate `。检查 |严重性 |描述 ---|---|--- 无条件分支|错误|每个 BRANCHES 边都需要一个条件标签节点数 >= 60 |错误|分成子流节点数 >= 40 |警告 |考虑拆分孤儿节点 |警告 |没有边的节点（断开连接）重复标签 |警告 |相同的动作文本，没有主语消歧没有切入点|警告 |所有节点都有传入边 **导出后功能（自动）：** * **步骤号** ：从入口点开始的 BFS 拓扑顺序（`1.action`、`2.action`） * **入口点**：带有绿色造型的体育场形状 * **边缘箭头**：`-->` 实线（触发/验证/转换/分支/合并），`-.->` 点线（读取），`==>` 粗线（写入） * **观察**：分为虚线边框观察子图 * **Direction** ：水平布局的 `--direction LR` 标志 ## 图表可读性要求 **所有图表必须由`audit.py export`生成。**切勿手工制作美人鱼。出口商强制执行： 1. **入口点标记** — 绿色体育场形状节点 `([label]):::entryPoint` 2. **步数** — BFS 拓扑顺序：`1。行动`,`2.行动`,`3.行动` 3. **图例块** — 入口点、关注点、观察点的 classDef 样式 4. **观察分离**——仅关注链进入观察子图，而不是主流 5. **标签安全** - `()`、`""`、`<>`、`|`、`[]` 字符的 HTML 实体（自动清理） **阅读流程必须是显而易见的。** 读者打开图表后必须立即看到： * 从哪里开始（绿色入口节点） * 阅读顺序（步骤编号） * 哪个路径是快乐的还是错误的（边缘的分支条件） * 颜色的含义（图例） **节点标签规则：** * 使用具体的名词/动词：`handleCallback()`、`exchangeCodeForTokens()` * 不是纯粹的动词：~~“配置”~~，~~“选择”~~，~~“启用”~~ * 消除重复歧义：重复操作时自动添加主题后缀 **尺寸限制：** * 40+节点→警告，考虑分裂 * 60+节点→错误，必须分成子流 * 如果流有 5 个以上独立的子流 → 按目的拆分 ** ** ## Git 工作流程 — 自定义合并驱动程序 **问题：** SQLite 是二进制的 — `git merge` 无法自动解析 `.audit/audit.db`。 **解决方案：** 自定义 git merge 驱动程序。 `audit.db` 保留在 git （小、单个文件）中。当发生冲突时，git 调用 `audit.py db-merge` 使用 SQL 自动合并。 ### 一次性设置 python .claude/skills/audit-flow/scripts/audit.py git-setup 配置（在`.git/config`中）： * **合并驱动程序：** `merge.sqlite-audit` — 在发生冲突时调用 `audit.py db-merge %O %A %B` * **差异驱动程序：** `diff.sqlite` — `sqlite3 .dump` 用于可读的 `git diff` 输出还需要`.gitattributes`（已经在仓库中）： .audit/audit.db diff=sqlite merge=sqlite-audit ### 它是如何运作的 1.正常提交 `audit.db` — `git add .audit/audit.db && git commit` 2. `git diff` 显示 SQL 文本（通过 textconv） 3.关于有冲突的`git merge`→git自动调用合并驱动程序 4. 驱动程序打开两个数据库，按名称合并会话（后来“updated_at”获胜），重新映射 ID 5. 结果写入我们的 — 合并干净地完成 ### 合并策略表|合并键 |冲突解决 ---|---|--- 会议 | `名称`（唯一）|稍后保留“updated_at” 流量| `（会话名称，流程名称）` |关注家长会议获胜者元组|家长流程 |保留获胜流中的所有元组边缘 |两个端点元组 |如果两个端点都存活则保留调查结果| `（会话名称、类别、描述）` |按内容重复数据删除所有 INTEGER PK 均按顺序重新映射。外键已更新。 ### CSV 备份（可选） CSV 导出/导入仍然可用于便携性和备份： python .claude/skills/audit-flow/scripts/audit.py csv-export # DB → .audit/csv/*.csv (QUOTE_ALL) python .claude/skills/audit-flow/scripts/audit.py csv-import # CSV → DB（从头开始重新创建） ** ** ## 输出质量 **原则：** * 复杂流程的 ASCII 序列图 * 并排表格用于替代方案 * 来自带有“file:line”引用的跟踪文件的真实代码 * 什么/为什么/示例模式 * 没有通用模板 ## 完成清单 * 存在带有 ISO 日期后缀的目录 * 生成 INDEX.md 清单 * README.md（执行摘要） * 命名约定：`{name}-{type}.md` * 类型化子目录中的工件（惰性初始化） * 捕获 Git 上下文 * 配置 Git 合并驱动程序 (`audit.py git-setup`) * 没有孤立文件 * 图表通过 `audit.py validate` ## 反模式扁平结构、空目录、孤立节点、未标记分支、通用标识符、缺少 git 上下文、没有清单、手工制作的美人鱼、裸动词标签。

审核流程

包含技能