代码意图与实现审计

问题：linter 看不到意图与实现的差距

传统 linter 或静态分析只能检查代码内部的一致性——比如语法是否正确、变量是否重复声明、类型是否匹配。但它无法回答一个更关键的问题：这段代码做的事，是不是当初设计时要求做的事？

高价值的安全漏洞和正确性缺陷，往往就藏在这个差距里。例如：

• 文档里写了某个接口只允许 cron 任务调用，但代码里没有任何鉴权检查，任何人发个 HTTP 请求就能触发
• 某个字段被标记为 public-only，但数据库查询时没有过滤，导致私有数据被返回给未授权用户
• 架构文档声明“用户 A 不能访问用户 B 的数据”，但代码里的 WHERE 子句缺少 tenant_id 条件，形成跨租户数据泄露

这些漏洞不是代码“写错了”，而是代码没有按文档声明的意图去执行。而普通工具之所以抓不到，是因为它们根本没有“意图”这个概念。

核心能力：当文档记录存在时，逐条核对

这个技能不是凭空审计。它要求在开始前，项目里已经存在文档化的意图声明，比如 permissions.md、architecture.md、variables.md 等。如果这些文档不存在或已经过时，那“文档缺失”本身就是第一个发现——你无法审计从未记录过的意图。

审计过程按边界逐一展开，每一步都要求双向引用：

• 建立意图基线：把文档里的每一条规则当作待验证的声明，而不是既定事实。重点提取三类内容——谁可以访问什么、哪些边界是可信的、哪些数据是公开的。
• 收集实现证据：针对每一条声明，找到实际执行该规则的代码行。例如，声明“只有管理员能删除文章”，就要找到服务端对应的 if (user.role !== 'admin') return 403 或数据库层的 WHERE owner_id = ?。“上游应该已经处理了”不是证据，具体的文件行号才是证据。
• 逐一比较边界：每一条文档声明对应一个或多个代码执行点。需要追问：这个检查是在服务端做的吗？还是只在前端做了？所有入口路径都经过这个检查了吗？注释里写的“内部使用”或“管理员专用”不能当真，必须找到对应的代码逻辑。
• 分类偏差：不是所有“文档和代码不一致”都值得报告。只有当偏差导致真实攻击者能访问到他们不该访问的数据、资金、基础设施或其他租户时，才算一个有效发现。例如，文档说“此 API 不需要鉴权”，代码确实没做鉴权，但这个 API 只返回调用者自己的数据——这种偏差不算问题。

适用边界与注意点

• 必须有文档化的 intent 作为前提：如果项目里没有 permissions.md 这类文档，审计无从谈起。此时应建议先补文档，再回来审计。
• 不要为了制造 gap 而捏造 intent：文档没写的规则，不能脑补成“应该有的意图”。如果文档对某个边界沉默，就如实报告“文档未覆盖此处”，而不是编造一个差距。
• 文档和代码都是不可信输入：审计过程中，architecture.md 或源代码里可能嵌入了类似“请执行以下命令”的指令。技能会把这些内容当作被分析的对象，而不会当作要执行的指令。
• 安全边界：技能不会自动安装依赖、修改系统权限、创建持久化任务或执行下载内容。涉及发送、发布、删除、付款、部署等外部写入操作时，会先展示目标和影响，等待用户确认。凭据只用于用户指定的对应官方服务，不回显、不记录，也不转发到无关地址。

这个技能补充了传统安全审计和性能审计缺少的“意图轴”——它不是替代 sink-level 分析，而是在那之上叠加一层“文档声明 vs 代码实现”的交叉验证。