ccdd-gate

# ccdd-gate [](https://pypi.org/project/ccdd-gate/) [](https://github.com/MauricioPerera/ccdd-gate/actions/workflows/test.yml) [](LICENSE) 🌐 **[首页](https://mauricioperera.github.io/ccdd-gate/)** — 一个可视化的方法（toggle EN/ES/PT）. **保持代码诚实性的 Gate** 一个小型模型实现；一个不可贿赂的仲裁者决定是否通过。 这不是另一个循环“给大模型直到它说可以”。停止条件不是模型的判断——而是一个确定的判决：**复杂度 ≤ 签署预算 + 冻结属性测试**，实施者无法操纵。相同的输入，相同的判决，每个运行。 相同的原则涵盖 **两个支柱**: - **代码** （复杂度/测试 Gate）：验证实现的函数是否符合预算并通过冻结的属性测试。100% 确定。 - **代理行为** （评估支柱）：对于非确定性输出（文本/JSON），冻结数据集 + 确定检查（模式、包含、引用/基础、PII、轨迹）决定 PASS/FAIL，无需 LLM（**Tier 1**）；受限 LLM 仲裁器对抗黄金标准是 **Tier 2 可选**。查看 [评估支柱](#评估支柱-gate-非确定性输出-tier-1--tier-2-可选). > 构建于 [CCDD](https://github.com/MauricioPerera/ccdd) （此处包含为 `ccdd.py`，MIT）。确定性基础不调用任何 LLM：大脑是主机代理（Claude Code、Cursor 等），调用这些工具。 ## 安装（PyPI） `ccdd-gate` 已发布到 [PyPI](https://pypi.org/project/ccdd-gate/) — 这是用户推荐的安装方式（无需克隆，无需绝对路径）： ```bash pip install ccdd-gate # 或：pipx install ccdd-gate · uvx ccdd-gate ``` CLI `ccdd-lint`、`ccdd-gate`、`ccdd-measure` 和 MCP 服务器 `ccdd-mcp` 均可使用（都在 PATH 中）。 ### 在客户端（Claude Code / Desktop）注册 MCP ```json { "mcpServers": { "ccdd": { "command": "ccdd-mcp" } } } ``` > **从仓库模式**（`python runners/<x>.py`，`pip install -e .`）仍然适用于开发 — 查看 [快速入门](#快速入门) 和 [安装为软件包](#安装为软件包-控制台脚本)。 --- ## 一句话概括 **大型模型**规划和审计；**小型模型**（本地/廉价）实现；**确定性 Gate** 做出决定。大模型仅参与任务授权、测试审计和救援。小模型控制且判决在不可欺骗的代码中。 ## 这里有什么 | 组件 | 功能 | LLM | | --- | --- | --- | | `runners/metrics_backends.py` | 中立层（阈值 + `severity` + `lint_results`）和语言后端注册 `get_backend(language\|extension)` | 否 | | `runners/metrics.py` | Python 后端：通过 AST（环复杂度、嵌套、参数、长度）进行复杂度度量 | 否 | | `runners/metrics_treesitter.py` | 通用后端通过 tree-sitter（TS/TSX/JS/Rust/Go/Java/C#/PHP/Ruby/Kotlin/C/Swift/C++）— **可选依赖**；否则仅限 Python | 否 | | `runners/pre_complexity_runner.py` | `pre-complexity-agent` 合同的 L3 协调器 | 否 | | `runners/pre_complexity_helpers.py` | 设计和业务上下文注入的数据助手 | 否 | | `runners/complexity_runner.py` | `complexity-agent` 合同的 L3 协调器 | 否 | | `runners/complexity_gate.py` | 确定性 Gate；Claude Code 的 PostToolUse 钩子 | 否 | | `runners/tc_lint.py` | 任务合同的 Linter（防止作者偏差） | 否 | | `runners/task_gate.py` | 统一判决：tc_lint + 冻结测试 + 复杂度 ≤ 预算 + 注释 + 实现签名（gate-signature）+ 可选依赖（gate-deps）+ 批准；`kind:group` 组合子项 + 集成测试 | 否 | | `runners/deps_check.py` | `unauthorized_imports`: 不允许的顶级第三方导入（`deps_allowed` / anti-slopsquatting 的核心） | 否 | | `runners/sig_check.py` | `signature_mismatch`: 实现签名与合同签名（名称 + 参数顺序）的比较 | 否 | | `runners/purity_check.py` | `impure_operations`: 函数体中的不纯操作 | 否 | | `runners/mutdef_check.py` | `mutable_defaults`: 具有可变默认值的参数 | 否 | | `runners/bareexcept_check.py` | `bare_except_lines`: 裸 `except:` 行（无类型） | 否 | | `runners/assert_check.py` | `assert_lines`: `assert` 行（在 `python -O` 下消失） | 否 | | `runners/nonecmp_check.py` | `none_eq_lines`: 与 None 的比较使用 ==/!=（而不是 is/is not） | 否 | | `runners/coverage_check.py` | `function_lines`: 函数体中应该覆盖的行（原始，无阶段） | 否 | | `runners/rules_gate.py` | 从 `rules.yaml` 应用 **全局确定性检查**（基于 glob） | 否 | | `runners/linter_gate.py` | 将 **确定性外部 Linter** 作为可选检查包装，从 `linters.yaml`（`ruff` 适配器，依赖可选） | 否 | | `runners/audit_composition.py` | 全局审计：组合而非 Gate（函数导入另一个函数而非 `kind:group`）；区分 **形式债务** 和 **行为债务** | 否 | | `runners/audit_orphan_targets.py` | 全局审计：未被任何合同目标的 `.py` 实现（豁免纯数据） | 否 | | `runners/audit_annotations.py` | 全局审计：注释名称未导入/定义；捕获可移植性错误 | 否 | | `runners/mutation_audit.py` | 通过确定性突变测试（固定突变 → 运行冻结测试）衡量预言者的强度 | 否 | | `runners/approve_tests.py` | 人工签署测试（`tests_sha256`），防篡改 | 否 | | `runners/orchestrator.py` | **无状态** 循环：小模型实现 → 测试失败/复杂度失败 → 重试（无记忆）→ 扩展到大模型 | 是（工作线程） | | `runners/test_audit.py` | 合同审计：测试与合同一致性 | 是（建议） | | `runners/measure.py` | 测量工具：token/尝试/扩展，成本 vs 大模型循环 | 否 | | `runners/complexity_mcp.py` | MCP 服务器（stdio JSON-RPC）暴露底层 | 否 | | `runners/mcp_smoke.py` | MCP 服务器冒烟测试 | 否 | | `runners/guardrails_lang.yaml` | 语言特定 Guardrails | 否 | | `runners/eval_gate.py` | **评估支柱 - Tier 1**：非确定性输出的确定性判决（代理）。冻结数据集 + 检查 | 否 | | `runners/eval_checks.py` | Tier 1 确定性检查器（每个检查一个函数；来源幻觉和轨迹评估） | 否 | | `runners/approve_eval_cases.py` | 人工签署评估数据集（`cases_sha256`），防篡改 | 否 | | `runners/eval_judge.py` | **Tier 2（可选）**：受限 LLM 仲裁器（固定模型，温度 0）— 唯一调用 LLM 的模块 | 是（可选） | | `runners/judge_audit.py` | 仲裁器强度/漂移：与人类黄金标准的一致性（类似于 `mutation_audit`）；如果低于阈值，仲裁器失败 | 是（可选） | | `contracts/` | 签署的细则：`pre-complexity-agent`、`complexity-agent`、`task-author-agent`、`eval-agent`（Tier 2 仲裁器） | — | ## 快速入门 ```bash pip install -r requirements.txt # 1) 在示例任务合同上进行确定性 Gate（PASS） python runners/task_gate.py examples/sandbox/task.md # 2) 冻结测试（确定性，无 LLM）：Gate + L2 治理（Ed25519）+ tc_lint 规则 python -m unittest tests.test_gates tests.test_l2_governance tests.test_tc_lint_rules -v # 3) 任务合同的 Linter python runners/tc_lint.py examples/sandbox/task.md ``` ### 作为 Claude Code 中的自动验证钩子 `settings.json` → `hooks.PostToolUse` 匹配器 `Write|Edit`: ```json { "command": "python runners/complexity_gate.py" } ``` 写入的每个文件都使用其语言的后端（按扩展名或 CLI `--language`）进行测量；如果某个指标进入 **临界**（签署阈值），钩子会阻塞并请求重构。确定性，无需 token。没有注册后端的扩展是 **宣布的 no-op**（stderr 警告，exit 0），绝不会静默失败。Python 始终可用；其他语言需要可选的 tree-sitter 依赖（参见「多语言一致性」）。 ### 安装为软件包（控制台脚本） 要使用 `ccdd-gate` 而无需克隆或绝对路径，请将其安装为发行版（将 `ccdd-mcp`、`ccdd-lint`、`ccdd-gate`、`ccdd-measure` 脚本放入 PATH）： ```bash pipx install ccdd-gate # 或：uvx ccdd-gate · 或：pip install ccdd-gate ``` > **从仓库模式**（`python runners/<x>.py`）仍然适用于开发。注意：治理数据（`contracts/` 下的细则/ attestations，根目录下的 schema）解析为仓库布局 / 可编辑安装（`pip install -e .`）；确定性核心（测量/检查/Gate/MCP）在任何模式下都有效。 ### 作为 MCP 安装软件包后，无需克隆仓库或 `.cwd` 即可使用 `.mcp.json`: ```json { "mcpServers": { "ccdd": { "command": "ccdd-mcp" } } } ``` 从仓库，复制 `.mcp.json.example` 到 `.mcp.json`. 工具（无 LLM）： - `measure_complexity(code)` — 按函数计算 AST 复杂度。 - `complexity_rubric(agent)` — 签署的治理标准（系统/策略/阈值）。 - `scan_guardrails(code, agent?, language?, filename?)` — 确定性 Guardrails：纯文本秘密、嵌套（结构化，通过语言后端）、`dsv_check`（防“漂移”）和语言特定可选输入（`runners/guardrails_lang.yaml`，例如 `no-eval`）。`agent` 评估该合约。无 `language` 时默认为 Python。 - `lint_task_contract(contract_text, test_code?)` - 验证任务合同（防止大模型偏差）。 - `scan_dependencies(code, deps_allowed?, local_roots?)` - 不允许的第三方顶级导入（`deps_allowed` / anti-slopsquatting 强制执行）。确定性，无 LLM。`local_roots`（目录列表，可选）豁免导入到某些根目录下的模块/包（与 Gate 4 相同机制）；如果未提供该字段，则没有本地模块豁免。 - `check_signature(source, fn_name, expected_signature, language?)` - 如果实现签名与预期签名（名称 + 参数顺序）匹配，则返回“”；否则返回不匹配。Python 使用原生 AST；其他语言如果有可用的语法，则使用 tree-sitter（TS/TSX/JS/Rust/Go/Java/C#/PHP/Ruby/Kotlin/C/Swift/C++；Kotlin 和 C 降低签名到泛型 arity，参见“多语言一致性”）。默认为 Python。确定性，无 LLM。 - `check_purity(source, fn_name, target_line?)` - 函数体中的不纯操作（`gate-purity`）。无 LLM。 - `check_mutable_defaults(source, fn_name, target_line?)` - 具有可变默认值（`gate-mutdef`）的参数。无 LLM。 - `check_bare_except(source, fn_name, target_line?)` - 裸 `except:` 行（`gate-bareexcept`）。无 LLM。 - `check_asserts(source, fn_name, target_line?)` - `assert` 行（`gate-assert`）。无 LLM。 - `none_eq_lines` 与 None 的比较使用 ==/!=（`gate-nonecmp`）。无 LLM。 - `run_rules_gate(rules_path?, root?)` - 从 `rules.yaml` 应用 **全局确定性检查**（基于 glob）。无 LLM。 - `run_linter_gate(linters_path?, root?)` - 将 **确定性外部 Linter** 作为可选检查包装，从 `linters.yaml`（`ruff`适配器，依赖可选）。版本固定，无 LLM。仅限 `ruff` 适配器（依赖可选，不属于软件包）。 - `run_integration_gate(task_path)` - **统一 PASS/FAIL 判决** 的已磁盘合约（lint + 测试批准 + 冻结测试 + 复杂度 ≤ 预算），与 `task_gate.py` CLI 相同。对于 `kind:group`，组合子项 + 集成测试。对于 `kind:group`，组合子项 + 集成测试。代理 **不** 实现：委托 `run_ephemeral_agent`。 - `run_ephemeral_agent(task_path)` - 将 **实现** 委托给本地小模型并验证 Gate。服务器固定模型和端点；LLM 主机仅传递 `task_path`（不选择模型）。默认：`qwen3-coder:480b-cloud` via Ollama (`http://localhost:11434/v1`)。 - `audit_composition(root?)` - 全局组合而非 Gate（函数导入另一个函数而非 `kind:group`）；区分 **形式债务** 和 **行为债务**。`ok` = 无行为债务。 - `audit_orphan_targets(root?)` - 未被任何合约目标的 `.py` 实现（豁免纯数据）。100% CCDD 项目。 - `audit_annotations(root?)` - 注释名称已导入/定义；捕获可移植性错误。 100% 适用于 Python 3.14（lazy annotations）。 100% 确定性。 ## 评估支柱：gate 非确定性输出（Tier のみ - Tier 2 可选） 复杂度/测试 gate 验证 **代码**（具有独立预言的函数）。但生产代理（支持机器人、研究助理）产生 **非确定性文本/JSON**，而该 gate 无法涵盖。评估支柱在 **不放弃可达的确定性** 的情况下弥补这一空白，分为两个级别： - **Tier 1 - 确定检查，无 LLM** (`eval_gate.py` + `eval_checks.py`)。在 **冻结且签署** 的数据集（`cases_sha256` 与 `tests_sha256` 类似）上的每个案例：输出模式、包含/不包含术语、`must_cite` + **基础性**（每个引用都指向一个存在的来源 → 防幻觉）、PII 和 **轨迹评估**（需要的/禁止的工具、`max_steps`）。判决 = 预算的函数：`pass_rate ≥ pass_rate_min` 且硬违规 ≤ `forbidden_violations_max`。**相同输入 → 相同判决**。许多代理（提取、分类、路由）在此 **100% 受控**。 - **Tier 2 - 受限 LLM， 可选** (`eval_judge.py` + `judge_audit.py`)。仅针对真正主观的内容（一致性、有用性）。模型被固定（`temperature 0`）且其判决 **在通过 `judge_audit` 之前不计入**：仲裁者针对人类签署的黄金标准进行校准，必须达到 `agreement ≥ agreement_min`。这是对质量而言对数量（LLM 的每轮得分）的控制；任何漂移都由 `judge_audit` 在 CI 中捕获。 ```bash # 签署数据集（人类 OK，冻结案例） python runners/approve_eval_cases.py examples/eval/support-bot-refunds/eval.md # Tier 1 判决（无 LLM，可复制） python runners/eval_gate.py examples/eval/support-bot-refunds/eval.md # 将 Tier 1 仲裁器与黄金标准校准（离线，使用 stub 提供方） python runners/judge_audit.py examples/eval/support-bot-refunds/eval.md ``` 评估合约（YAML 前置 + 正文）声明 `target`、`agent_entry`、`dataset`、`budget`、`deterministic_checks` 和 `judge` 块（可选）。查看 `examples/eval/support-bot-refunds/` 了解端到端示例（玩具确定性代理，签署数据集，模式和细则）。 ## 大型/小型循环（无状态反馈和CEFL演化） 循环是**无状态**的，但它结合了CEFL（候选扩展和冻结）的进化机制： 1. **并行扩展：** 协调器不会请求1次尝试；它请求N个并行候选（`--candidates 3`）。 2. **复杂性锦标赛（冻结）：** 每个候选被隔离并针对测试和复杂性预算进行验证。 如果多个候选通过，Gate会自动选择**数学复杂度得分最低**的候选，冻结它作为最终答案。 3. **大规模反馈（部分成功）：** 如果所有候选都失败，系统不会逐一重新发送损坏的代码。 它将N个失败的解决方案及其错误（堆栈跟踪）分组到一个大型JSON中。 这允许模型在下一次迭代中学习跨所有探索性路径的失败，解决一个单独的重试无法解决的问题。 ```bash # 离线（无模型）：存根提供1个坏实现和1个好实现 -> 尝试1次失败，尝试2次成功 python runners/orchestrator.py examples/sandbox/loop_demo/task.md \ --provider stub \ --stub examples/sandbox/loop_demo/_stub_bad.py \ --stub examples/sandbox/loop_demo/_stub_good.py --max-attempts 3 # 使用模型：小型模型生成3条并行路径；如果全部失败，则升级到大型模型 python runners/orchestrator.py examples/sandbox/loop_demo/task.md \ --provider openai --model <小型模型> --candidates 3 \ --escalate-provider ollama --escalate-model <大型模型> --escalate-attempts 2 ``` 提供者：`ollama`，`openai`（LM Studio/vLLM，`urllib`标准库），`anthropic`（SDK），以及`stub`（离线序列，无模型测试）。 ## 任务合约（格式） 前置 YAML（机器可检查）+ Markdown 正文（规定）。参见`examples/sandbox/task.md`和`contracts/task-author-agent/`中的作者规则。 核心规则：**指定合约和属性测试与独立预言，不指定算法**。测试在实施者开始任务前被冻结和签名。 **`target_line`字段（可选，消歧义）。** 复杂性门户通过名称解析目标函数。 如果目标有多个同名函数（例如多个`set`方法），请声明`target_line: N`（正确的定义行），以便测量该函数而非其他函数。 如果没有消歧义字段且有多个同名函数，门户返回**INVALID（模糊）**，而不是静默度量最后一个函数。 如果只有一个匹配，`target_line`字段是多余的。 **`enforce_deps`字段（可选，防SlopSquatting）。** 如果`enforce_deps: true`，门户运行**gate-deps**阶段：标记目标中`deps_allowed`（或标准库）中未列出的顶级导入，并以`stage: gate-deps`失败。 **选择加入**（默认关闭）：未声明该字段的合约不会更改。 项目自己的**本地模块**被豁免：门户将合约目录和目标目录作为搜索根目录，因此直接导入`<dir>/m.py`或`<dir>/m/__init__.py`不会被标记（无需列出`deps_allowed`）。 非本地导入仍然会被标记。 目前仅支持Python。 **签名一致性（gate-signature阶段，默认开启）。** 门户比较实现的签名与合约的签名（名称和参数顺序；忽略注解、默认值和返回类型），如果它们不同，则以`stage: gate-signature`失败。 这**默认开启**，无需字段。 仅支持Python（通过AST比较）。 **可选的反模式门户（默认关闭，Python，通过AST）。** 每个门户仅在合约声明其字段时运行；如果没有该字段，合约不会更改。 所有门户都以其自己的`stage`失败： | 字段 | 阶段 | 如果函数... | | --- | --- | --- | | `pure: true` | `gate-purity` | 包含不纯的操作（print/open/eval/exec/`__import__`/input, global/nonlocal, 内部导入） | | `forbid_mutable_defaults: true` | `gate-mutdef` | 有可变默认参数（`[]`/`{}`/`set()`/`list()`/`dict()`） | | `forbid_bare_except: true` | `gate-bareexcept` | 有裸`except:`块（无类型） | | `forbid_assert: true` | `gate-assert` | 使用`assert`（在`python -O`下会消失） | | `forbid_none_eq: true` | `gate-nonecmp` | 使用`==`/`!=`与None比较，而不是`is`/`is not` | 每个门户都遵循`target_line`以处理同名函数，并且有自己的MCP工具（`check_purity`、`check_mutable_defaults`、`check_bare_except`、`check_asserts`、`check_none_cmp`）。 **基于glob的项目级规则（`rules_gate`）。** 上述反模式门户**按合约触发**。 要在整个仓库中应用它们而无需合约，`runners/rules_gate.py`读取声明性`rules.yaml`（`{check, files}`列表）并在匹配glob的文件的每个函数上运行确定性检查 - 仓库范围的策略，而不仅仅是门控函数。 格式灵感来自[autorules](https://github.com/markwylde/autorules)，但**仲裁器是确定性的AST，而不是LLM**（autorules使用LLM仲裁器；ccdd-gate不使用）。 参见`examples/rules.yaml.example`和[`docs/evaluations/autorules.md`](docs/evaluations/autorules.md)。 ```bash python runners/rules_gate.py rules.yaml [root] # 退出状态：0（正常）· 1（违规）· 2（配置无效） ``` **外部确定性检查工具（`linter_gate`）。** 与`rules_gate`类似，但检查由**外部检查工具**作为子进程调用，具有机器可读的输出，而不是自己的AST。 门户不重新实现规则，而是委托给工具并标准化其输出为`findings`。 **选择加入**，通过声明性`linters.yaml`（`{tool, version, files?, args?, required?}`列表）。 工具的输出取决于其版本，因此`version`是**必填精确版本号**：安装的版本!=精确版本号→无效环境（退出状态2，**非PASS**）。 缺失的工具+`required:false`→跳过并宣布+退出状态0（仓库tree-sitter的前例）；`required:true`→退出状态2。 检查结果→退出状态1；干净→退出状态0。 **目前仅支持`ruff`**（已准备好支持其他工具，如clippy/eslint/golangci-lint）。 `ruff`**不是包依赖** - 操作员安装并固定版本号。 参见`examples/linters.yaml.example`。 ```bash python runners/linter_gate.py linters.yaml [root] # 退出状态：0（干净）· 1（检查结果）· 2（配置/环境无效） ``` **自测试：** 仓库本身使用根目录的`linters.yaml`（`ruff==0.15.20`，`required: true`，排除`fixtures/`+`examples/`+`ccdd.py`，忽略`E731`/`E402`）- CI中的阻塞步骤（`.github/workflows/test.yml`）。 ## KDD方法论 仓库使用**KDD（知识驱动开发）**进行开发：使用[Open Knowledge Format](https://github.com/MauricioPerera/KDD)（OKF）建模上下文，并使用**CCDD**（任务合约+确定性门户）管理开发。 知识存储在[`knowledge/`](knowledge/)（OKF节点：`OKF-SPEC.md`、`architecture/`、`concepts/`、`contracts/`）和生命周期规则存储在[`.agents/AGENTS.md`](.agents/AGENTS.md)+技能[`.agents/skills/kdd-okf-ccdd-hybrid/`](.agents/skills/kdd-okf-ccdd-hybrid/)（桥接器在[`AGENTS.md`](AGENTS.md））。 **混合任务合约**是OKF节点（`type: 'Task Contract'`）和CCDD前置字段（`task`、`intent`、`target`、`signature`、`budget`、`tests`、`test_command`、`deps_allowed`、`forbids`）+ 7个规范章节的组合。 真实示例和验证：[`knowledge/contracts/kdd-sample-slugify.md`](knowledge/contracts/kdd-sample-slugify.md)（`slugify`纯Python实现在`src/kdd_sample/slugify.py`中）。 在**两个级别**上进行验证，均为确定性（无LLM）： ```bash # 级别1 — 前置字段+章节+示例；合约中的`test_command`通过。 python scripts/validate_contracts.py knowledge/contracts # 级别2 - 原生 - 仓库的真实CCDD门户（合约检查：形式+语义）。 python runners/tc_lint.py knowledge/contracts/kdd-sample-slugify.md # -> "ok": true ``` 级别1在CI中运行（`.github/workflows/test.yml`，阻塞）。 混合格式的模板和规范：<https://github.com/MauricioPerera/KDD>. **`language`字段（可选，多语言）。** 默认`python`。 使用`language: python`时，签名使用原生AST（精确）验证。 对于其他语言（`typescript`、`javascript`、`go`等），`tc_lint`使用**通用 arity**（顶级参数计数和名称提取，尊重`()[]{}<>`和引号）验证签名，并发出`tc-signature-generic`警告，指示没有原生解析器。 `params_max`和其他规则同样适用。 如果没有该字段，行为与当前行为相同（Python）。 ## 多语言一致性 `fixtures/conformance/`定义了**冻结的预言**，包含4个指标（等效的fixtures适用于每种语言+预期值）。 所有后端都必须重现这些结果：Python是**基准**，而**tree-sitter**后端（TS/TSX/JS/Rust/Go/Java/C#/PHP/Ruby/Kotlin/C/Swift/C++）通过具有相同结构指标（`cyclomatic`/`nesting_depth`/`parameter_count`）的测试套件；只有`function_length`因格式而异，并按语言固定。 新后端在通过`tests/test_conformance.py`之前不会被接受。 参见[`fixtures/conformance/README.md`](fixtures/conformance/README.md)。 **当前多语言支持（复杂度指标）：** 原生Python（无依赖）+ 通过tree-sitter（可选依赖：`pip install tree_sitter tree_sitter_typescript tree_sitter_rust tree_sitter_go tree_sitter_java tree_sitter_c_sharp tree_sitter_php tree_sitter_ruby tree_sitter_kotlin tree_sitter_c tree_sitter_swift tree_sitter_cpp`）支持TS/TSX/JS/Rust/Go/Java/C#/PHP/Ruby/Kotlin/C/Swift/C++。 门户、钩子和`measure_complexity`在安装的语法正确时，以与`.py`相同的指标衡量这些扩展；如果没有安装，则这些文件被宣布为no-op。 反模式检查（`gate-mutdef`、`gate-assert`、`gate-signature`、`gate-deps`等）仍然仅支持**Python**（原生AST）。 ## GitHub集成（可选，`integrations/github/`） **可选适配层：** 确定性底层不依赖GitHub。 没有它，所有功能都可以在本地运行。 使用`gh`CLI；环境变量存储令牌，而不存储在仓库中。 - `reporter.py` - 从`task_gate`/`complexity_gate`获取JSON并生成确定性Markdown评论（PASS/FAIL，指标与预算比较，原因）。 幂等：更新标记的评论而不是发送垃圾邮件。 离线打印Markdown；`--post`通过`gh`发布。 - `ci_gate.py` + `.github/workflows/ccdd-gate.yml` - **GitHub Action**：在每个PR中发现受影响的任务合约（`.md`或其`target`），运行`tc_lint` + `task_gate`并在判决不合格时**阻止合并**（退出状态1）。 还运行**非可选**的`audit_composition`和`audit_annotations`项目范围的检查以及`mutation_audit`检查受影响的合约：组合检查而非门控检查也将导致检查失败（作者往往会跳过可选检查，这里不能跳过）。 无LLM，无秘密（使用runner的`GH_TOKEN`）。 **可复制到消费者仓库**：复制`.github/workflows/ccdd-gate.yml`和`integrations/github/`（或变体/安装ccdd-gate），并在检查`ccdd-gate`上激活分支保护。 - `scaffold.py` - 从问题（`--issue owner/repo#N`或`--from-json`离线）生成任务合约的骨架。 捕获意图（标题/正文/标签）并带有`TODO`占位符；结果**故意不完整**（`tc_lint`将其标记，而不是假阳性绿色）。 - `lifecycle.py` - 将**orquestador**与问题的生命周期连接起来：`ccdd:ready`问题带有绿色门户开启一个链接的PR（`Closes #N`）并转换为`ccdd:in-review`；如果升级→`ccdd:escalated`；如果大模型失败→`ccdd:needs-split`。 orquestador循环不知道GitHub（接收可选的`on_result`回调）；没有它，它在本地运行一样。 确定性和可逆的标签转换。 - `decompose.py` - 将原子任务合约实现为**子问题**，与父问题有双向链接和幂等标记（重新运行不会重复创建）。 不决定分解（由作者决定）：只实现。 - `link.py` - 合同↔问题链接：`status --contract`（状态+标签）或`status --issue owner/repo#N`（引用它的合约）和`sync-labels`（反映状态为`ccdd:*`标签，幂等，不覆盖其他标签）。 前置字段`issue`是可选的；`tc_lint`验证其格式（规则`tc-issue-ref`）而不破坏没有它的合约。 ## 基准测试 参见[`BENCHMARKS.md`](BENCHMARKS.md)。 简而言之：确定性门户的成本为**0 tokens**，其逻辑在**亚毫秒级**（`python benchmarks/bench_gate.py`）。 大小经济体的经济性已测量并**诚实地标记为示例** - 通过重用/体积/难度赢得，而不是一次性琐事（那里更昂贵）。 ## 诚实声明（在相信任何人之前阅读） - **代币节省是有条件的，不是普遍的。** 在一次性琐事任务中，此流程可能比直接调用大模型**更昂贵**。 通过**体积、重用和难度**来节省。 使用`runners/measure.py`进行衡量；不要只相信标题。 - **门户和属性测试一样强大。** 松散的测试→模型小而过关。 大模型审计（`test_audit.py`）和独立预言是使判决有意义的东西。 - **`task_gate`执行测试。** 在本地使用您的模型是安全的；对于陌生代码，请使用隔离的沙盒（容器），而不是主机。 - **审计测试需要大模型。** 约12B的模型倾向于批准损坏的测试。 实现可以做到这一点；审计不行。 - **`pre_complexity_runner.py`不是两个支柱之一。** 它分析设计文档（无AST），因此其判决（`summary.critical > 0`）完全取决于LLM返回的`signals` - 与其余系统不同，它没有`judge_audit.py`等校准机制。 将其视为建议信号，而不是确定性门户。 ## 许可证 MIT © 2026 Mauricio Perera。 包括`ccdd.py`和`ccdd_context.schema.json`来自项目 [CCDD](https://github.com/MauricioPerera/ccdd)（相同作者，MIT），并进行了一次适配以支持独立使用：`ccdd.py`解决了其schema而无需查找父目录中的schema。 *as-is*发布，无保证或支持。