灵克三层审计流程 (Three-Layer Audit Process)

概述

三层审计流程是 LingYi 为 LingFlow 提交流程设计的标准审计方法，确保代码质量、接口一致性和团队协作质量。

核心理念：每个 AI 助手都有自己的盲区，必须有另一个 AI 独立复查才能发现审计者自己看不到的问题。

---

三层架构

┌─────────────────────────────────────────────────────────┐
│  提交流程开始 (Commit Process)               │
└──────────────┬──────────────────────────────────────┘
               ↓
┌─────────────────────────────────────────────────────────┐
│  Layer 1: 单文件审计 (AI-A)               │
│  ──────────────────────────────────────────────       │
│  • 逐文件检查逻辑正确性                    │
│  • 边界条件处理 (None/空值)                 │
│  • 错误处理完整性                            │
│  • 代码风格符合规范                            │
└──────────────┬──────────────────────────────────────┘
               ↓
┌─────────────────────────────────────────────────────────┐
│  Layer 2: 交叉文件验证 (AI-A)             │
│  ──────────────────────────────────────────────       │
│  • 接口一致性检查 (import vs export)          │
│  • 数据流完整性 (producer → consumer 类型匹配)    │
│  • 影响传播验证 (导出/命名变更不影响现有调用) │
└──────────────┬──────────────────────────────────────┘
               ↓
┌─────────────────────────────────────────────────────────┐
│  Layer 3: 交叉审计 / Peer Review (AI-B)      │
│  ──────────────────────────────────────────────       │
│  • 抽查 PASS 项（验证 AI-A 标记通过的项）     │
│  • 排除误报（验证 AI-A 发现的问题是否真实）  │
│  • 发现遗漏（寻找 AI-A 审计盲区）           │
│  • 评估修复质量（治本 vs band-aid）          │
└──────────────┬──────────────────────────────────────┘
               ↓
        最终裁决 (Final Verdict)
        ACCEPT / ACCEPT with Reservations / REJECT

---

Layer 1: 单文件审计

目标

每个修改的文件独立检查，确保： - 逻辑正确性 - 边界条件处理（空值、None、边界数值） - 错误处理完整性 - 代码风格符合项目规范

检查维度

维度	检查项	工具
逻辑正确性	代码实现是否符合预期逻辑	代码审查 + 单元测试
边界条件	None/空值/0/负数等边界处理	代码审查 + 单元测试
错误处理	try/except 覆盖、错误日志、优雅降级	flake8 + 代码审查
代码风格	命名规范、类型提示、文档字符串	flake8 + black/isort

示例问题

# ❌ 错误：边界条件未处理
def calculate_avg(values):
    return sum(values) / len(values)  # values=[] 时 ZeroDivisionError

# ✅ 修复：边界条件处理
def calculate_avg(values):
    if not values:
        return 0.0
    return sum(values) / len(values)

---

Layer 2: 交叉文件验证

目标

验证文件之间的接口契约和数据流，确保改动不会破坏现有集成。

检查维度

维度	检查项	示例
接口一致性	import 的符号在目标模块中实际存在	A imports B.export_func()，但 B 只导出了 _export_func()（私有）
数据流完整性	生产者输出类型匹配消费者输入期望	Collector 返回 MentionData(platform=str)，但 Analyzer 期望 MentionData(platform=Enum)
影响传播	init.py 导出变更不影响现有调用方	新增 TrendAnalyzer 导出，但已有代码通过 from analyzers import * 导入，可能引入命名冲突

示例问题

# ❌ 问题：接口不一致
# File A: transports/http.py
from .transport import TransportAdapter

# File B: transport.py
class TransportAdapter(ABC):
    @abstractmethod
    def connect():  # 缺少此方法
        pass

# Result: http.py 无法满足 ABC 合约

---

Layer 3: 交叉审计 (Peer Review)

目标

另一个 AI 助手（AI-B）独立复查 AI-A 的审计报告，防止审计者自身的盲区。

检查动作

动作	目的	示例
抽查 PASS 项	验证 AI-A 标记通过的项真的没问题	AI-A 说 "接口一致性 PASS"，AI-B 阅读代码确认
排除误报	确认 AI-A 发现的问题是否真实	AI-A 说 "asyncio.Future 风险"，AI-B 验证后发现是误报（已在 async 函数内）
发现遗漏	找 AI-A 审计盲区	AI-A 检查了 trend.py 但漏了同模式的 feedback.py 的 except:pass
评估修复质量	判断是治本还是贴创可贴	Bug 1 修复用了 set 解决 list.discard()，是治本；Bug 2 绕行而非统一数据模型，是 band-aid

价值量化

真实案例数据（LingFlow commit 9a49943）：

• AI-A 真阳性率: 83% (10/12 findings confirmed as real bugs)
• AI-B 发现遗漏: 5 个新问题（包括 1 个由 Bug 1 修复引入的新问题）
• AI-B 排除误报: 2 个（Future 风险、labels=None）

结论：如果没有 Layer 3，Bug 1 修复引入的 set 迭代崩溃问题会进入生产环境；Layer 3 发现了这个隐藏问题。

---

工具集成

LingYi 审计工具

在 LingYi 中，审计通过 audit_commit 工具调用执行：

# 工具调用示例
{
    "name": "audit_commit",
    "arguments": {
        "repo_path": "/home/ai/LingFlow",
        "commit_hash": "9a49943",  # 可选，默认 HEAD
        "save_report": True  # 可选，默认 True
    }
}

返回格式

{
  "status": "complete",
  "commit": "9a49943",
  "changed_files": 12,
  "files_list": ["lingflow/communication/transports/http.py", ...],
  "layer1": {
    "pass": false,
    "issues": [...],
    "summary": "Layer 1: 7 issues found"
  },
  "layer2": {
    "pass": false,
    "issues": [...],
    "summary": "Layer 2: 1 issues found"
  },
  "layer3": {
    "pass": true,
    "issues": [],
    "summary": "Layer 3: 0 potential false positives",
    "recommendation": "Full peer review should be performed by independent AI agent"
  },
  "tests": {
    "pass": true,
    "message": "30 passed in 0.67s",
    "exit_code": 0
  },
  "verdict": "REJECT",
  "verdict_detail": "Found 8 issues that must be fixed",
  "total_issues": 8,
  "report_saved_to": "/home/ai/LingFlow/AUDIT_REPORT.md"
}

裁决标准

裁决	条件	含义
ACCEPT	total_issues == 0	所有审计通过，可以提交
ACCEPT with Reservations	layer3.pass == true 但 total_issues > 0	核心问题已修复，但有非关键问题或技术债务
REJECT	total_issues > 0 且 layer3.pass == false	存在必须修复的问题，阻止提交

---

提交流程集成

提交流程图

┌──────────────────────┐
│  编码完成         │
└────────┬───────────┘
         ↓
┌──────────────────────┐
│  git add          │  → 暂存文件
└────────┬───────────┘
         ↓
┌──────────────────────┐
│  audit_commit     │  → 三层审计
└────────┬───────────┘
         ↓
   ┌─────┴──────┐
   │ Verdict?     │
   └─────┬──────┘
    YES         NO
     ↓           ↓
┌──────────────┐  ┌──────────────────┐
│  git commit  │  │  修复问题       │
└──────┬──────┘  └──────┬───────┘
       ↓                 ↓
┌──────────────────────┐
│  git push        │  → 推送到远程仓库
└──────────────────────┘

LingYi CLI 命令

审计工具已集成到 LingYi 的 agent 系统，可通过对话调用：

用户: 审计一下 LingFlow 最新的提交
灵依: 执行三层审计...

或直接通过工具调用：

from lingyi.agent_tools import _audit_commit

result = _audit_commit("/home/ai/LingFlow")
print(result)

---

最佳实践

对 AI-A（主审计者）

1. 逐行审查代码，不要只看函数签名
2. 思考数据流，思考"这个数据从哪里来，到哪去，中间会经过什么转换"
3. 检查依赖关系，每次 import 都要 verify 目标存在
4. 记录清晰的问题描述，包含文件路径、行号、具体问题
5. 不要假设测试通过，要实际运行测试验证

对 AI-B（Peer Reviewer）

1. 不要盲目信任 AI-A，抽查至少 3-5 个 PASS 项
2. 从不同角度思考，AI-A 看了逻辑，你看看架构和数据流
3. 检查同模式遗漏，如果 AI-A 发现了 trend.py 的 except:pass，检查 feedback.py 是否有同样问题
4. 区分真 bug vs 编码风格，风格问题标注为建议而非阻断性 bug
5. 评估修复质量，问"这个修复是否解决了根本原因，还是绕过了问题"

对提交流程

1. 每次提交前必须执行审计，audit_commit 应该在 git commit 之前
2. REJECT 时不提交，修复所有 REJECT 级别问题后重新审计
3. ACCEPT with Reservations 时谨慎，确认技术债务在可接受范围内
4. 保留审计报告，每次审计保存到 AUDIT_REPORT.md 作为历史记录

---

常见问题

Q1: 为什么需要三层审计？单层不够吗？

A: 单文件审计只能看到单个文件的内部问题。交叉文件验证能发现接口断裂和数据流不匹配，但这些都是审计者自己定义的规则。Peer Review 引入了另一个审计者的视角，可以发现：

• 审计者的认知偏见（如过度关注某些模式）
• 同类问题在不同文件中的遗漏
• 修复方案的质量判断（治本 vs 绕行）
• 审计过程中引入的新问题

Q2: Layer 3 可以自动化吗？

A: 理论上可以自动化一些检查（如真阳性率统计），但 Peer Review 的核心是"不同视角的独立思考"，这本质上是人类（或 AI）的认知过程。完全自动化会丢失多样性。LingYi 当前设计是：AI-B 独立分析 AI-A 的审计报告，这是一个半自动化过程。

Q3: 审计失败后怎么办？

A: 1. 修复所有 REJECT 级别问题 2. 重新运行 audit_commit 验证修复 3. 直到获得 ACCEPT 或 ACCEPT with Reservations 才提交 4. 技术债务可以在后续专门修复，但必须在文档中记录

Q4: 审计耗时很长，如何快速迭代？

A: 1. 开发阶段可以只做 Layer 1（单文件审计） 2. 提交前执行完整三层审计 3. 使用 --no-verify 绕过 git hook 不推荐，应该在审计工具层面处理快速迭代

---

参考资源

• LingYi 代码: /home/ai/LingYi/src/lingyi/
• 审计工具: /home/ai/LingYi/src/lingyi/audit_tools.py
• 约束验证: /home/ai/LingYi/src/lingyi/_constraint_validators_ext.py
• LingFlow 技能: /home/ai/LingFlow/skills/verification-before-completion/
• AGENTS.md: /home/ai/LingFlow/AGENTS.md（包含系统审计章节）

---

版本: v1.0 最后更新: 2026-04-09 维护者: LingYi Development Team