audit-flow

⚠️ 强制入口 — 执行后才能进行任何其他操作

步骤 1：读取 schema.sql

# ALWAYS read the schema first to understand tables, constraints, views
cat .claude/skills/audit-flow/schema.sql

步骤 2：检查数据库是否存在 — 绝不重新创建

# Check for existing database
ls -la .audit/audit.db 2>/dev/null && echo "DB EXISTS - DO NOT RECREATE" || echo "No DB - safe to init"

步骤 3：如果数据库存在，显示当前状态

python .claude/skills/audit-flow/scripts/audit.py list

🚫 禁止的操作

操作	禁止原因
rm .audit/audit.db	会销毁审计历史
数据库存在时运行 audit.py init	会覆盖现有数据
DROP TABLE	会销毁审计历史
数据库存在时运行 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（流程追踪）

延迟初始化： 仅在存在产物时创建子目录

• screenshots/ network-traces/ diagrams/ code-samples/ test-results/ evidence/

命名： {audit-name}-{type}.md

数据库优先原则

不变原则： SQLite = 唯一事实来源。上下文窗口具有易失性，会在不通知的情况下压缩，也会产生幻觉状态。

🚨 重要：绝不销毁现有数据

• 如果 .audit/audit.db 存在 → 其中包含无法替代的审计历史
• 数据库存在时绝不运行 init — 使用 list 查看内容
• 绝不删除、丢弃或重新创建 — 只能追加

约束：

操作	规则	禁止的借口
入口	首先读取 schema.sql，其次检查数据库是否存在	“我先直接开始工作”
初始化	仅当 .audit/audit.db 不存在时	“让我重新初始化，从头开始”
架构	执行任何 SQLite 命令前读取 schema.sql — 先了解表、约束和视图	“我根据上下文知道架构”
写入	每到一个新的代码位置前，先插入每个元组/边/发现	“我最后再批量插入”
读取	引用元组 ID、计数或流程结构前，先从数据库执行 SELECT	“我记得目前的流程”
导出	仅使用 audit.py export — 绝不根据上下文生成 mermaid/markdown	“让我直接生成 mermaid”
恢复	执行任何引用先前元组的操作前，先运行 audit.py show <session>	“完整追踪内容都在上下文里”
引用	从数据库查询元组 ID — ID 由数据库分配，绝不能推断	“元组 ID 应该是 N”
默认	不确定流程状态时 → 继续前先查询数据库	(任何未列出的借口)

检查点： 每插入 5 个元组 → 运行 audit.py show <session> <flow>

---

交互式工作流 - 始终询问用户

1. 开始会话时 — 询问：

Name: ___
Purpose: security-audit | documentation | compliance | ideation | brainstorming | debugging | architecture-review | incident-review
Description: ___ (optional)

立即初始化目录。生成构件时再按需创建子目录。

2. 粒度 — 询问：

[fine]   Function-level trace (~50-200 tuples)
         Use: Security audits, debugging

[coarse] Boundary-level trace (~10-30 tuples)
         Use: Documentation, high-level flows

Choose: fine / coarse

3. 追踪期间：

在决策点询问：要深入追踪吗？要标记关注事项吗？要添加发现项（严重程度）吗？要记录备注吗？

4. 导出时：

询问格式：json | yaml | md | mermaid | all

导出后：生成 INDEX.md 清单。按类型整理构件。清理空目录。

快速参考

命令	用途
/audit-flow start	新建会话（名称、用途、粒度）
/audit-flow flow {name}	向会话添加新流程
/audit-flow add {layer} {desc}	向当前流程添加元组
/audit-flow link {from} {to} {rel}	创建边（支持为分支设置条件）
/audit-flow finding {desc}	记录发现项
/audit-flow show	查看会话／流程详情
/audit-flow export	导出（json/yaml/md/mermaid）
/audit-flow git-setup	配置 git 合并／差异驱动程序（仅需一次）

层： CODE | API | NETWORK | AUTH | DATA

关系： TRIGGERS | READS | WRITES | VALIDATES | TRANSFORMS | BRANCHES | MERGES

关系的语义规则

关系	含义	适用场景	不适用场景
TRIGGERS	A 导致 B 执行	函数调用、事件处理程序、HTTP 请求	静态观察
READS	A 从 B 读取数据	Cookie 读取、数据库查询、配置查找	修改
WRITES	A 修改 B 中的数据	Cookie 写入、数据库插入、状态更新	只读访问
VALIDATES	A 检查／验证 B	身份验证检查、输入验证、过期检查	串联分析人员的观察
TRANSFORMS	A 为 B 转换／映射数据	令牌交换、响应格式化	无关处理
BRANCHES	A 存在条件路径	if/else、switch、错误与成功	必须带有条件标签
MERGES	多条路径在 B 汇合	并行路径重新汇合、错误恢复	单路径流程

重要：BRANCHES 必须带有条件。 每条 BRANCHES 边都必须包含描述所选路径的 condition。例如：BRANCHES [token expired] 与 BRANCHES [token valid]。

观察与流程步骤

流程步骤 = 系统执行的操作（函数调用、数据读取、网络请求）。通过追踪代码进行验证。

观察 = 分析人员记录的事项（缺失功能、潜在风险）。应记录为发现项，而非元组。

错误模式：

T50 "NO cross-tab sync"       ← observation, not a system action
T51 "React state NOT shared"  ← observation
T50 --VALIDATES--> T51         ← chaining observations as flow

正确模式：

-- Record as finding instead:
INSERT INTO findings (flow_id, session_id, severity, category, description)
VALUES (?, ?, 'medium', 'state-management',
        'No cross-tab sync: React state not shared across tabs');

规则：绝不要使用 VALIDATES 串联观察。如果描述系统未执行的操作，请使用发现项。

数据模型

Session (audit container)
  └── Flow (named DAG with entry point)
       └── Tuple (node: layer + action + subject)
            └── Edge (relation + optional condition)

存储与 CLI

# Core
python .claude/skills/audit-flow/scripts/audit.py init              # Initialize DB
python .claude/skills/audit-flow/scripts/audit.py list              # List sessions
python .claude/skills/audit-flow/scripts/audit.py show <session>    # Show flows
python .claude/skills/audit-flow/scripts/audit.py show <session> <flow>  # Show flow details
python .claude/skills/audit-flow/scripts/audit.py export <session>  # Export all
python .claude/skills/audit-flow/scripts/audit.py export <session> -f <flow>  # Export one flow
python .claude/skills/audit-flow/scripts/audit.py validate <session>         # Validate flows

# Git integration
python .claude/skills/audit-flow/scripts/audit.py git-setup         # Configure merge/diff drivers (once)
python .claude/skills/audit-flow/scripts/audit.py db-merge %O %A %B # Git merge driver (auto-called)

# CSV backup/portability (optional)
python .claude/skills/audit-flow/scripts/audit.py csv-export               # DB → .audit/csv/*.csv
python .claude/skills/audit-flow/scripts/audit.py csv-import               # .audit/csv/*.csv → DB
python .claude/skills/audit-flow/scripts/audit.py csv-merge <theirs_dir>   # Merge two CSV sets

非线性流程

**分支：**一个元组 → 多条带有条件的出边

INSERT INTO edges (from_tuple, to_tuple, relation, condition)
VALUES (5, 6, 'BRANCHES', 'token valid'),
       (5, 7, 'BRANCHES', 'token expired');

**合并：**多个元组 → 一个元组

INSERT INTO edges (from_tuple, to_tuple, relation)
VALUES (6, 8, 'TRIGGERS'),
       (9, 8, 'MERGES');  -- refresh path merges back

文件

• 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 上下文

会话开始时捕获：提交哈希、分支、工作树状态。将其包含在所有导出内容中。

Mermaid 验证

导出前运行 python .claude/skills/audit-flow/scripts/audit.py validate <session>。

检查项	严重级别	描述
BRANCHES 不带条件	ERROR	每条 BRANCHES 边都需要条件标签
节点数 >= 60	ERROR	拆分为子流程
节点数 >= 40	WARN	考虑拆分
孤立节点	WARN	没有边的节点（未连接）
重复标签	WARN	相同操作文本未通过主体消歧
无入口点	WARN	所有节点都有入边

导出后功能（自动）：

• 步骤编号：从入口点开始按 BFS 拓扑顺序排列（1. action、2. action）
• 入口点：采用体育场形状并使用绿色样式
• 边箭头：--> 实线（TRIGGERS/VALIDATES/TRANSFORMS/BRANCHES/MERGES），-.-> 虚线（READS），==> 粗线（WRITES）
• 观察项：分离到虚线边框的 OBSERVATIONS 子图中
• 方向：使用 --direction LR 标志创建水平布局

图表可读性要求

**所有图表都必须通过 audit.py export 生成。**切勿手动编写 Mermaid。导出器会强制执行：

1. 入口点标记 — 绿色体育场形状节点 ([label]):::entryPoint
2. 步骤编号 — 按 BFS 拓扑顺序排列：1. action、2. action、3. action
3. 图例块 — 为 entryPoint、concern、observation 定义 classDef 样式
4. 观察项分离 — 仅包含关注项的链路放入 OBSERVATIONS 子图，而非主流程
5. 标签安全 — 对 ()、""、<>、|、[] 字符使用 HTML 实体（自动清理）

**阅读流程必须一目了然。**读者初次打开图表时必须能立即看出：

• 从哪里开始（绿色入口节点）
• 按什么顺序阅读（步骤编号）
• 哪条路径是正常路径，哪条是错误路径（边上的分支条件）
• 颜色代表什么（图例）

节点标签规则：

• 使用具体的名词和动词：handleCallback()、exchangeCodeForTokens()
• 不要使用裸动词：“配置”、“选择”、“启用”
• 消除重复歧义：重复操作会自动添加主体后缀

大小限制：

• 40 个或更多节点 → 警告，考虑拆分
• 60 个或更多节点 → 错误，必须拆分为子流程
• 如果流程包含 5 个或更多独立子流程 → 按用途拆分

---

Git 工作流 — 自定义合并驱动程序

**问题：**SQLite 是二进制格式 — git merge 无法自动解决 .audit/audit.db 的冲突。

**解决方案：**自定义 Git 合并驱动程序。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. 将结果写入我方版本 — 干净地完成合并

合并策略

表	合并键	冲突解决方式
sessions	name（唯一）	保留较新的 updated_at
flows	(session_name, flow_name)	遵循父会话的胜出结果
tuples	父 flow	保留胜出 flow 中的所有 tuple
edges	两个端点 tuple	两个端点均保留时才保留
findings	(session_name, category, description)	按内容去重

所有 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 (recreates from scratch)

---

输出质量

原则：

• 复杂流程使用 ASCII 时序图
• 使用并排表格展示备选方案
• 引用追踪文件中的实际代码，并标注 file:line
• 遵循「是什么/为什么/示例」模式
• 不使用通用模板

完成检查清单

• 目录存在，且带有 ISO 日期后缀
• 已生成 INDEX.md 清单
• README.md（执行摘要）
• 命名规范：{name}-{type}.md
• 产物位于按类型划分的子目录中（延迟初始化）
• 已捕获 Git 上下文
• 已配置 Git 合并驱动（audit.py git-setup）
• 没有孤立文件
• 图表通过 audit.py validate 校验

反模式

扁平结构、空目录、孤立节点、未标注的分支、通用标识符、缺少 Git 上下文、没有清单、手工编写的 mermaid、仅使用动词的标签。