Lucin 这个项目，一句话介绍就是：给 AI Agent 做静态分析，并且主动公开了自己的 false-negative 清单。AI Agent 现在不再只是套一层大模型 API 那么简单，它会自己选工具、填参数、做多步决策，甚至批量处理任务。这种程序一出问题，排查成本比传统服务高很多，因为你不知道是代码写得不对，还是模型这一轮选错了工具。Lucin 这一类工具想解决的事情，是在 Agent 真正跑起来之前，先把工具定义、权限边界、工作流配置这些能确定的内容检查一遍。适合正在接 Agent 的开发者、做 Agent 平台的人，以及被 Agent 运行结果搞到崩溃的测试同学看。最值得关注的不是它能查出多少个问题，而是它把「自己也查不出什么」写清楚了。
1. AI Agent 为什么需要静态分析，光靠运行测试为什么不够
1.1 Agent 的本质是一段「带着工具的程序」
很多人会把 AI Agent 想成一个大模型，其实落到工程上，它更像一个循环：模型根据用户请求和上下文，从工具列表里选一个，生成参数，执行工具，把结果放回上下文，然后继续下一步。真正决定 Agent 能不能稳定跑的，一半在模型能力，另一半在工具定义、权限配置、流程编排和调用约束。
这些东西不是模型的一部分，而是代码和配置的一部分。工具名拼错、参数少了必填项、描述写得含糊、权限范围放得过大、上下文里把敏感信息传给了模型，这些都属于确定性错误。它们不会因为换一个更强的模型就自动消失。
所以，Agent 的工程化程度越高，越需要一套不依赖模型输出的检查机制。静态分析刚好做这件事：不运行 Agent，直接看定义里有没有明显错误。
1.2 运行时 Eval 的短板：贵、慢、不稳定的判断标准
做 Agent 评测时很容易陷入一种状态：写一堆用例，跑一轮，发现有的通过有的不通过，再跑一遍，结果又变了。这是因为模型输出有随机性，外部工具也不一定每次返回一样的结果。我一般不会只跑一遍就下结论，至少跑三次，看稳定率。但这样一来，成本就开始涨了，API 调用费、排队时间、人工核对时间都算进去。
更麻烦的是，如果 Agent 的工作流有七八步，中间任何一步都可能失败。想通过运行测试定位到底是哪一步出了问题，需要非常完整的日志和 trace。很多项目在这个阶段就开始打退堂鼓，其实把一部分检查移到运行前，会轻松很多。
1.3 静态分析能补上的那一块确定性
静态分析的思路是：不执行程序，直接解析代码和配置，把不合法的结构找出来。它不看模型表现，只看定义本身。比如工具 schema 缺少 required 字段、工作流里某个节点指向不存在、环境变量在配置里被引用但没定义、提示词模板把用户输入直接拼进 system prompt，这些都能在几秒内扫出来。
这类检查的结果是确定的。同一份代码，跑多少次结果都一样。所以它特别适合放进 CI，每次提交都自动跑一遍，确保 Agent 定义的改动不会引入低级错误。
2. Lucin 这类工具到底检查什么，以及那串 false-negative list 意味着什么
2.1 静态分析的核心检查对象：工具定义、权限边界、工作流图和提示词
如果要给 Agent 结构化定义，最常见的几块就是工具 schema、权限配置、工作流节点和提示词模板。以工具定义为例，很多 Agent 框架会让开发者用 JSON 或 YAML 描述一个工具：
# 示例：Agent 工具定义片段 tools: - name: query_database description: 查询业务数据库并按条件返回记录 parameters: sql: type: string required: true limit: type: integer required: false default: 50静态分析器拿到这份定义后，可以检查工具名是否符合命名规范、description 是否能表达清楚用途、参数类型是否合法、必需字段是否齐全。如果项目里有两个工具同名，或者某个节点引用了不存在的工具，也能被逮住。
权限边界也适合静态检查。比如一个工具标注为只读，却在实际处理函数里执行了写操作；又或者 Agent 配置里允许访问数据库，但工具 schema 完全没有说明访问范围。这类不一致在代码评审里很容易漏掉，但静态规则能稳定发现。
2.2 一张公开的 false-negative list 比「号称全覆盖」更可靠
Lucin 这个项目最有意思的点不是它检查了哪些规则，而是它公布了一个 false-negative list。所谓 false-negative，就是工具没查出问题，但实际确实有问题的情况。
大多数静态分析工具不会主动说自己的盲区。于是用户只能靠踩坑去摸边界，踩到一次才知道原来这个也不管。公布了 false-negative list 之后，边界就透明了：哪些问题可以交给它，哪些问题它明确管不了，需要另做测试，一目了然。
从工程上看，这比挂一个「支持全面漏洞检测」的招牌要可信得多。如果工具承认自己查不出一类问题，用户反而清楚下一步该测什么；如果工具什么都不说，用户还以为没报错就是没风险。
2.3 怎么用 false-negative 清单反过来设计测试重点
拿到清单之后，不要只收藏起来，应该把它当成一份测试计划素材。它说查不出模型选错工具，那就补一组工具选择黄金样例；它说查不出外部服务返回格式变化，那就给运行时加响应校验；它说查不出一段动态拼接的提示词，那就对用户输入做单独的过滤和审计。
这套思路和传统测试中的代码覆盖率有点像。静态分析告诉你哪些是明确覆盖的，false-negative 清单告诉你哪些是明确没覆盖的。把两者加起来，再决定运行测试的优先级，就不会出现所有精力都花在静态分析已经覆盖的那部分上。
3. 落地方案：从单个 Agent 项目到分层验证流水线
3.1 环境与接入方式：配置文件、工具清单、提示词目录
静态分析工具的接入方式通常不复杂，但有一个前提：它得能读到你的 Agent 定义。我建议接入前先做一次结构盘点：
- Agent 定义在哪个文件，是纯代码还是独立配置
- 工具函数是否用统一 schema 声明，还是散落在各处
- 提示词是写死在代码里，还是放在独立模板目录
- 权限、变量、依赖关系是否集中管理
如果项目里还是大段自然语言写工具说明，静态分析能做的很有限。这倒不是工具的问题，而是结构不够机器可读。先在框架层面把工具声明、权限、prompt 分离，再接入静态分析，效果会好很多。
至于 Lucin 本身的具体命令和参数，要以项目文档为准。这一节我给的是一套通用验证顺序，也适用于同类工具：
- 先跑一次自带示例或小型项目，确认工具能正常读取项目结构
- 再指定单个配置文件或工具目录进行扫描，避免一开始就扫整个仓库
- 保存第一份完整报告，作为后续改动的基线
- 在 CI 里接入，让每次提交都自动执行一次
这里不要急着做一次全仓库扫描。Agent 定义如果比较乱，全量扫描会给出大量告警，反而不知道从哪里开始改。
3.2 第一次跑通：从最小 Agent 定义开始
第一次验证，尽量用最小的例子。比如只定义两个工具，一个查询数据、一个删除记录，然后运行静态分析。看它能不能识别这两个工具，能不能把删除工具标记为高权限操作，能不能发现参数缺 required 之类的问题。
如果最小样例检查通过，再逐步加入工作流、多步工具、条件分支、外部 API 调用。每加一种结构，就跑一遍静态分析，观察新告警。这个过程其实也是在帮你理解工具的规则：它喜欢什么结构，反感什么写法，边界在哪里。
成功结果长什么样？三种情况都值得记录：正常通过、检测到错误、以及查不出但实际有问题。最后一种最容易被忽略，但它最能验证 false-negative list 是否可信。
3.3 把静态分析结果转成可执行的修复清单
静态分析结果通常按严重级别分类，我习惯用下面这个口径去判断：
| 级别 | 含义 | 处理策略 |
|---|---|---|
| error | 结构不合法，运行大概率失败 | 必须修复后再合入 |
| warning | 可能导致异常或权限过宽 | 逐个确认后修复 |
| info | 提示优化空间 | 按团队约定处理 |
拿到报告后，先别急着全改。把 error 全部修掉，再把 warning 和具体运行失败场景建立映射。比如某个 warning 是「工具 description 过短」，对应的风险是模型可能选错工具，那就值得修；如果只是格式风格问题，可以在规则配置里关掉。
如果工具支持自定义规则，可以考虑把团队自己的约定也写成规则。例如某个工具必须写上权限级别，或者外部命令调用必须经过白名单接口。
4. 配置和参数的判断标准：哪些告警要修，哪些可以忽略
4.1 严重级别、误报率、可执行建议
判断一个静态分析工具好不好用，不是看它报了多少问题，而是看它每个问题给不给上下文。好的报告应该包含文件位置、触发规则、违反了哪条约定、为什么可能出问题、怎么改。如果只有一句「potential issue」，基本没法用。
误报率也需要关注。工具报得太激进，团队会慢慢变得麻木，最后连真问题也一起忽略。我见过的做法是：先跑两周，统计告警里误报占比。如果超过三四成，就该调整规则配置，把不适合项目现状的规则关掉或改为 info 级别。
4.2 如何判断 Agent 定义是否做得足够「可分析」
静态分析的有效性取决于定义结构化程度。可以参考下面几个标准来判断：
- 工具是否统一用 schema 声明，有没有重复和缺失
- 权限是否集中配置，而不是散落在多个模块
- 提示词是否和代码分离，用户输入是否和系统指令明确隔开
- 工作流是否用 DSL 或配置表达，路径是否可追踪
这几个标准如果答案都是否，建议先做结构重构，再上静态分析。否则你拿到的报告要么空洞，要么噪音太多。这个顺序不能反过来：指望一个静态分析器帮你理解完全混乱的工程，不现实。
4.3 低配置环境下的使用预期
静态分析不需要大显存，也不需要跑模型推理，所以资源要求比运行 Agent 低很多。但这不代表它完全没开销。扫描一个大型仓库，或者分析大量工作流配置，仍然需要 CPU 和内存，时间也可能从几秒到几分钟不等。
如果只是学习和评估阶段，跑本地命令行就够了。如果要做团队级接入，就要考虑规则库维护、告警分级、CI 执行时长和报告归档。原始材料没有给出 Lucin 的具体性能数据，建议落地时以你所在仓库的实际扫描耗时为准。
5. 一套完整的 AI Agent 质量保障流程：静态分析 + 运行 Eval 怎么分工
5.1 分层测试矩阵（静态分析层、单轮运行层、多轮会话层、线上灰度层）
单纯依赖静态分析不够，单纯依赖运行 Eval 也不够。实际可以按四层来组织：
| 测试层 | 检查内容 | 建议成本 | 执行频率 |
|---|---|---|---|
| 静态分析 | 工具 schema、权限、死节点、密钥泄漏、prompt 拼接 | 低 | 每次提交 |
| 单轮运行 | 单个工具调用的参数生成、返回格式、超时情况 | 中 | 关键路径每次改动 |
| 多轮会话 | Agent 记忆、循环终止、多步决策稳定性 | 高 | 发布前跑核心场景 |
| 线上灰度 | 真实用户输入、链路 trace、成本监控 | 高 | 持续进行 |
这四层不是替代关系，而是逐渐兜底的关系。静态分析把确定性问题挡在门外；单轮运行确认每个工具调用正常；多轮会话处理模型长期行为；线上灰度发现真实数据带来的问题。
5.2 从 false-negative 清单里长出回归用例
false-negative list 最大的价值，是能直接生成回归任务。项目每修一个新 bug，先对照一下清单，看这个 bug 是不是已经覆盖。如果已经覆盖，说明当初的静态分析和测试设计还有缺口，就把场景补进运行测试里。如果根本没覆盖，那就更值得加一条用例。
这里我建议用一个简单表格来管理：
| false-negative 描述 | 需要补的检查 | 负责人 | 状态 |
|---|---|---|---|
| 模型可能选错工具 | 工具选择黄金样例 + 手动审查 | 待定 | 进行中 |
| 外部服务返回格式变化 | 运行时响应 schema 校验 | 待定 | 待补 |
| 长会话上下文溢出 | 多轮压力测试 | 待定 | 待补 |
这样清单就不是一张收藏夹里的截图，而是活的任务池。
5.3 迭代节奏和验收标准
团队落地时，建议定一个容易执行的验收标准。我一般会这样约定：新增或修改工具定义，必须通过静态分析；修改提示词或工具描述，至少先跑一遍静态分析和对应工具的单轮用例；发布到灰度前，必须跑完多轮会话用例；线上问题出现后，24 小时内决定是补静态规则、补运行用例，还是更新 false-negative 清单。
这套节奏不复杂，但能逼着每个人在改动 Agent 时思考三层问题：定义对不对、模型会不会理解错、真实环境下会发生什么。
6. 实战排查：为什么「没报错」还是出问题，以及先看哪里
6.1 常见误判：静态分析通过不等于 Agent 行为正确
最容易踩的坑，是把静态分析通过当成 Agent 正确的证据。工具 schema 完全合法，模型照样可能选错工具；权限配置很严，外部返回内容照样可以诱导 Agent 改变行为；工作流图没有死节点，长会话照样可能上下文混乱。
所以排查问题的时候，第一个要建立的心态是：静态分析没报错，只代表确定性层面没有低级错误。真正的 Agent 行为是否可靠，还要靠运行测试和线上数据验证。这不是工具不行，而是这类程序本来就分两层，两层需要不同手段。
6.2 排查顺序：输入数据 → 运行时状态 → 模型行为 → 工具边界
当 Agent 出现问题时，我建议按下面的顺序排查，而不是一上来就怀疑静态分析漏报：
- 先确认输入数据格式、编码、长度和来源是否符合预期
- 再看运行时日志：工具调用了几个、参数是什么、返回值是否正常、耗时多少
- 然后看模型行为：是否在多轮之后偏离指令，是否输出了不匹配的格式，是否反复调用同一个工具
- 最后看工具边界：权限、超时、限流、外部服务是否故障
这样排查的好处是：每一步都有明确结果，能快速排除一批可能。很多「没报错但行为不对」的问题，最后不在静态层，而在运行时数据格式或外部服务状态上。
如果确实发现问题不在已经覆盖的规则里，也别急着给工具打差评，先对照 false-negative 清单。如果问题正好属于清单里写过的情况，说明当初的测试设计漏了这块，补运行用例就行；如果清单里没有，可以通过项目反馈渠道提交，把新边界补进文档。
6.3 维护 false-negative 清单的团队实践
最后说一点工程实践：false-negative 清单不能只写在项目 README 里，最好进入团队的日常流程。新人入职读一遍；每次事故复盘拿出来对照；新的漏检发现后马上更新。
我觉得这种透明度值得多说一句。现在很多工具都在宣传自己能覆盖所有风险，但真正落到生产环境，边界比宣传重要得多。Lucin 把边界写成清单，至少让人知道它的检查能力到哪儿为止。对使用者来说，这反而是最省事的做法：你不需要从零摸黑试探，直接按清单补测试就行。
反正，Agent 质量保障不会只靠一个工具完成。静态分析负责确定性，运行 Eval 负责行为，监控负责线上状态。先接受工具的边界，再把边界之外的部分补上，你的 Agent 才敢放到真实任务里去跑。
