create-dataflow-approximation

技能：创建数据流近似

数据流近似是一段代码，用于表达分析器无法追踪的方法中的数据流动——这是一个不透明调用，分析引擎看不到方法体，因此会丢失污点。你需要编写一个小型替代实现，复现该方法从输入到输出的真实传播过程，让分析器能够追踪污点经过该方法。对准备好的测试项目运行测试，并不断完善，直到示例通过。

输入

由调用方提供；未提供时使用默认值。只有在必需输入缺失且没有合理默认值时才询问

• project-root（可选）— 目标项目的根目录。Opentaint 会将所有分析产物保存在固定的 <project-root>/.opentaint/ 目录下，因此下方每个 .opentaint/... 路径都会在该目录下解析。默认值：当前目录
• language（必需）— 此项目的目标语言，以及特定于该语言的说明
• batch（必需）— 批次；该批次的 .opentaint/tracking/approximations/<batch>.yaml 提供需要建模的 dataflow 方法，并保存跟踪状态
• methods（可选）— 批次中需要（重新）建模的特定 dataflow 方法子集；默认处理所有尚未出现在 build.done 中的方法

工作流

1. 理解传播过程

找到并阅读每个数据流方法的真实源代码：处理尚未出现在 build.done 中的方法，或为修复而明确指定的 methods，即使这些方法已经构建过。不要更改明确指定子集之外已构建方法的近似源代码。应用内部方法的源代码位于项目自身源码中；库方法的源代码来自其依赖项（如何获取可参阅语言参考）。阅读源代码，了解数据如何从方法输入（接收者、参数）流向输出（返回值、被写入的参数、存储的状态），并收集理解函数行为所需的完整上下文。

2. 编写近似实现

按照语言参考中的产物布局，在 .opentaint/dataflow/<batch> 下使用特定于该语言的代码形式复现传播过程。覆盖所有指定的可调用变体；修复现有源文件中明确指定的可调用项；新增项也应添加到该文件中，而不是重写文件。分析引擎采用字段敏感分析——污点是按字段追踪的——因此应严格按照源代码的方式将数据从一个字段传递到另一个字段，而不要污染整个对象。测试项目中的负样本（如果存在）会通过在一个字段中存储污点、再读取另一个字段来验证这一点，因此过于宽泛的模型会触发这些样本。具体结构和模式请参阅语言参考。

3. 使用测试项目进行测试

直接在前台以阻塞命令运行近似测试，并等待其退出——绝不要在后台运行，也不要使用 Monitor。应用此批次的源代码并反复迭代，直到样本通过。反馈循环：样本失败可能是因为模型的目标类型/成员或签名与分析器识别的不匹配，也可能是因为方法体没有将污点从真实源代码传递到建模的输出——应诊断差异、修复并重新运行，不要为未得到结果找借口。如果原因不明显，应先按照 references/debugging.md 中的说明，通过事实可达性跟踪定位污点消失的位置，再继续推测。测试通过时，只有当方法尚未出现在 build.done 中，才将其追加进去（参见 Tracking）；已修复的方法仍应保留记录。

4. 升级处理

如果经过约 3 次修复后样本仍无法收敛——无论跟踪结果显示忠实的模型仍无法传播污点（污点在引擎本应能够传递的普通指令处消失，属于引擎限制），还是原因仍不明确——都不要将新方法添加到 build.done，也不要更改现有已修复方法的跟踪条目。按照 Output 中的要求，简要报告已查明的原因，以便协调器升级处理。不要继续重试。

输出

制品

• .opentaint/dataflow/<batch> — 扫描所需的特定语言代码近似制品；报告路径和使用的确切测试命令
• 批次文件的 build.done 中已通过的方法（新增方法追加到其中；已修复的方法已记录，见 Tracking）

摘要

• 已建模的方法及测试状态（通过 / 不收敛）

Tracking

.opentaint/tracking/approximations/<batch>.yaml — 一个批次的可调用项分类，<batch> 是计划文件名的主体。每个可调用项都恰好属于一个判定类别，使用计划中的特定语言 method 和 signature 精确标识，以便区分不同变体：

• passthrough、dataflow — 已建模的载体；每项为 { method, signature }
• skipped — 终止性非载体；每项为 { method, signature, reason }
• engine_issues — 单独的类别，用于引擎已证实无法传播的载体（已构建但仍被丢弃）；每项为 { method, signature, reason }。这是终止性类别，处理方式与 skipped 完全相同，唯一的区别是原因。merge-skipped 会将其保留在 skipped.yaml 中，作为独立的 engine_issues 组，与常规的 methods 并列。

dependencies 列出数据流测试项目所需的依赖标识符。build 块用于跟踪构建状态——test_project 记录每个数据流方法的测试项目状态（如果样例已写入该批次的测试项目，则为 done；如果无法写入样例，因此该方法未纳入测试项目，则为 failed），done 保存已完成的 { method, signature }。请通过注释明确说明

passthrough:
  - { method: "<qualified-member-a>", signature: "<language-signature-a>" }
dataflow:
  - { method: "<qualified-member-b>", signature: "<language-signature-b>" }
skipped:
  - { method: "<qualified-member-c>", signature: "<language-signature-c>", reason: "retains none of its input data" }
engine_issues: []
dependencies: []
build:
  test_project:
    - { method: "<qualified-member-b>", signature: "<language-signature-b>", status: done }
  done: []

此技能会将样例通过的每个方法以 { method, signature } 的形式追加到 build.done，前提是该项尚不存在。新分配但仍未通过的方法，或引擎已证实无法传播的方法，都不应纳入其中，并应按 Output 中的说明报告；明确修复的方法应保留其现有条目不变。不要修改分类类别（passthrough/dataflow/skipped/engine_issues），也不要编辑 build.done 中已有的条目。

约束

OpenTaint 是一种整程序、过程间、字段敏感的别名分析引擎。它已经能通过可见的应用代码、调用、别名和单个字段进行传播；自定义规则和近似仅用于建模指定的源、汇或不透明方法边界。编译时常量和字面量不携带污点，因此，输出仅为常量的源或载体不会引入任何内容。

• 仅通过测试项目上的近似测试进行验证
• 测试项目的样例源代码是固定输入，绝不要为了强行通过而修改或重新编译它们；如果忠实的模型无法通过，则将该方法排除并按 Output 中的说明报告
• 对该批次列出的每个数据流方法及重载都进行建模，不要只建模有样例的方法