tombaldwin/candor-spec

# 坦率

**让代码的*行为*变得清晰易读——对人类如此，对 AI agent 尤为如此。** candor 是一系列针对特定语言的工具，它们能报告每个函数执行的副作用——网络、文件系统、数据库、子进程、环境变量、时钟、IPC、日志、随机数、剪贴板——并且是*传递性*的，同时对其无法解析的部分保持诚实。 这个仓库是**与语言无关的规范**：包含共享的副作用词汇表、报告 schema、诊断代码、模式，以及每个实现都需遵守的 agent 合同。其*设计*可跨语言移植；每个实现的*引擎*则是针对其专属工具链定制的。 **网站：** [candor.poly.io](https://candor.poly.io) —— 五分钟内了解实测案例：展示案例、预先注册的评估，以及在你自己的仓库中验证它的路径。 ## 实现 | 语言 | 仓库 | 引擎 | 状态 | |---|---|---|---| | Rust | [candor-rust](https://github.com/tombaldwin/candor-rust) | dylint (HIR + CHA) + 稳定的 `syn` 扫描器 | **已发布** — 参考实现 (`cargo install candor-scan`) | | Java / JVM | [candor-java](https://github.com/tombaldwin/candor-java) | ASM bytecode + CHA | **alpha (v0.3.x)** — 完整模式集；支持 Spring；支持 Java/Kotlin/Scala/Groovy | | TypeScript | [candor-ts](https://github.com/tombaldwin/candor-ts) | TS compiler API | **早期引擎 (0.1.x)** — 项目扫描、拦截门、查询；源自仅基于规范的验证切片；是符合性 CI 中的第三个引擎 | | C# / .NET | _计划中_ | Roslyn analyzer | 计划中 | | Go | _计划中_ | `go/analysis` + SSA | 计划中 | ## 文档 - **[SPEC.md](SPEC.md)** — 合同：副作用词汇表、JSON 报告 schema、`AS-EFF-00x` 代码、各种模式以及信任合同。即“作为一个 candor 实现”意味着什么。 - **[SEMANTICS.md](SEMANTICS.md)** — 形式化分析：effect lattice、调用点解析规则、传递性不动点、跨 crate 组合、一致性谓词，以及健全性/精度/终止性属性（明确指出了两项关于诚实度的警告）。 - **[PRINCIPLES.md](PRINCIPLES.md)** — 构建该工具家族的基础理念（不确定状态下的诚实性）。 - **[AGENTS.md](AGENTS.md)** — AI agent 如何*消费* candor 报告（适用于任何语言）。 - **[CLASSIFIER.md](CLASSIFIER.md)** — 如何为新语言构建副作用分类器，以及从惨痛教训中总结出的精度经验。 - **[conformance/](conformance/)** — 一个*可执行的*差分测试：在多个引擎（Rust + JVM，以及作为仅基于规范的第三个引擎 candor-ts）上运行相同的测试夹具，断言它们都能推断出规范规定的副作用集，并在策略判定、查询形状和 §6.2 语法上达成一致（`bash conformance/run.sh`）。一次运行即可验证一致性与跨实现的一致性。 ## 为什么需要共享同一规范的特定语言工具 “这段代码做了什么？”这一问题是由特定语言的底层机制——类型解析、调用图构建——来解答的，因此*引擎*无法共享。但*输出*应该是相同的：副作用词汇表、报告、信任合同、采用阶梯。这样，AI agent（或人类，或 CI 拦截门）就可以以完全相同的方式使用 Rust 报告和 Java 报告。这个仓库就是那套共享定义；各个实现都接入其中。 这是一条特定语言工具（如 CodeQL、Semgrep、ArchUnit）无法跨越的界线。它们可以为每种语言制定*规则*，但永远无法保证这些规则*表达相同的意思*。candor 可以做到——而且这不是一句空话：[`conformance/`](conformance/) 是一个由 CI 强制执行的差分测试，它会在等效的测试夹具上运行这些引擎，一旦它们在**副作用集**、**策略判定**或 **§6.2 语法**上出现分歧就会失败——*在这些测试夹具上*：该差分测试覆盖了测试集所编码的内容（并且该测试集会随着在现实中发现的每一次分歧而不断扩充），而不是覆盖所有能想到的程序。因此，对于多语言代码库，`deny Net in ` 的边界限制从构建层面就得到了*完全一致*的执行。这种跨语言的一致性——而非原始的分析能力——才是其持久的立足点：无论是更智能的模型、单一语言的 effect system，还是特定语言的规则集，都无法提供这一点。 ## 许可证 根据您的选择，采用 [MIT](LICENSE-MIT) 或 [Apache-2.0](LICENSE-APACHE) 双重许可。

标签：AI智能体, 云安全监控, 副作用检查, 威胁情报, 开发者工具, 静态分析