dvalincode

English · 中文 · 🌐 dvalincode.dev

为人类和 AI Agent 编写的代码提供开放的安全工程。
每项修复都附带自己的证明。

当 Agent 修复一项安全问题时，必须有人判断修复是否有效。几乎所有工具都会询问编写修复的模型——而模型无法客观回答这个对自身有利的问题。

Dvalin 会自行判断，并向你提供证明。它会重新扫描，亲自运行项目自身的测试，并读取自己启动的进程的退出代码。修复由谁编写——我们的 Agent、Claude Code、Codex、Copilot 还是某个人——都会被记录，且不会作为判断依据。最终结果是已验证修复记录：一个小型 JSON 文件，任何人都可以离线重新检查，即使笔记本电脑没有网络，也没有 Dvalin 状态。

dvalin verify-fix fix-record.json

Fix record 2c9d71ac03e0 · VERIFIED · scan-and-checks
  executor: claude-code (recorded, not consulted)
  targets: 1 before · 0 remaining
  coverage: complete → complete
  introduced: 0 (gate high/new)
  outcome: verified
  ✓ test: npm run test (exit 0)
  audit: run verify-36509f42 @ 414644c75af0

这份记录刻意只说明一件有限的事：*这些问题已不复存在，并且观察到这些检查通过了。*它并不声称你的代码是安全的，Dvalin 也不会让它被解读为这种声明——每份记录都会注明扫描实际覆盖的范围，而无法通过任何检查确认的修复不会被判定为通过。 开放配置文件 →

修复是一项变更，而变更既可能消除问题，也可能引入问题。因此，记录还会包含重新扫描发现但首次扫描未发现的内容，以及得出判定时所依据的门槛：如果修复移除了 eval 却引入了 SQL 注入，记录会标记为 regressed，且验证不通过。签发者从未检查引入问题的记录也同样不通过——introduced: not determined 会导致失败，因为跳过这个问题的验证者，不应比提出问题并发现问题的验证者得分更高。

Dvalin 是位于代码生成与合并之间的独立安全运行时。人类、编码 Agent 和 CI 都会调用同一套有版本管理的契约来进行发现、修复和验证。它可以独立运行，也可以通过可移植的 SARIF 与 Codex Security 等专业系统互操作。其内置编码能力是一个修复执行器——而非信任边界，也不试图与所有通用编码 Agent 竞争。请参阅安全 Agent 策略。

⏱️ 30 秒，无需安装，无需 API 密钥

npx dvalincode security scan .
# After installing the package: dvalin scan .

就是全部内容。它会针对当前目录运行内置规则，检查注入、硬编码密钥、XSS、eval 和不安全的 Shell 用法，并打印检查结果。无需账户、模型或配置，代码也不会离开你的设备。默认策略仅运行 Dvalin Built-in，因此首次扫描始终有效。可明确添加可选引擎，或查看其固定安装命令：

dvalin scanners list
dvalin scanners install semgrep       # review the command
dvalin scanners install semgrep --yes # execute it under Dvalin policy

使用 CI 门禁所用的扫描器进行度量

如果 Snyk 会阻止你的合并，就用 Snyk 进行验证。某个修复被其他引擎判定为“干净”，并不代表门禁不会拒绝它；这种不一致会让一次 Agent 修复演变成多轮推送、失败和变基。

npm install -g snyk && snyk auth      # or set SNYK_TOKEN
dvalin scan . --scanners builtin,snyk-code,snyk-oss

snyk-code（SAST）和 snyk-oss（依赖项）与其他引擎一样：其发现结果具有相同的指纹、覆盖范围和门禁；登录失败会作为引擎错误报告，因此扫描结果会是 partial，绝不会是干净结果。它们仅在被点名时运行，因为 Snyk Code 会将源代码上传到 Snyk。在 dvalin.security.json 中点名它们，将其纳入策略；之后 reverify 会使用它们评估每一项修复。

Snyk 自身报告为已接受的忽略项会被遵从，并列为覆盖范围排除项。此次审查中的更改新增的忽略项则不会：评估修复时，.snyk、.semgrepignore、.trivyignore 和 .dvalincodeignore 会恢复为基础提交中的版本，新的内联标记（deepcode ignore、nosemgrep、nosec、NOSONAR、……）会被清空，因此通过屏蔽而非修复的发现仍会导致修复失败。抑制是一项由人员在自己的更改中做出的风险决策，而不是修复。

Dvalin 标记为“已验证”的所有场景都采用相同的评估方式：修复循环、dvalin verify、MCP dvalin_verify_findings 工具、单轮 --fix --verify，以及 CI reverify。这些记录采用 dvalin-fix-record/v3，如果修复通过隐藏发现而非修复来规避问题，也会判定失败——包括同类漏洞汇、删除存在漏洞的文件、删除测试或断言。在 Git 仓库之外，由于无法确定更改内容，记录仍采用 v2，并说明未评估规避行为。

让循环持续运行，直到通过门槛

dvalincode dvalin . --scanners builtin,snyk-code,snyk-oss --until-clean --max-rounds 3 --executor codex

--until-clean 会将一次修复尝试变成有次数上限的循环。执行器负责编辑；Dvalin 使用相同的引擎重新扫描，并自行运行项目检查；随后只向执行器发送仍有问题的内容——仍然存在的目标、其更改引入的问题、未通过的检查及其最后几行输出、它添加的抑制项——然后再次修复。依赖项问题优先处理。

当所有目标都已消失、没有引入任何阻碍问题且所有检查均通过（verified），或轮次预算耗尽，或某轮结束后仍有相同问题未解决，或未解决问题集合不再缩小（stalled），或目标需要人工处理——例如依赖项没有固定版本（not-auto-fixable），或引擎或检查无法运行（unverifiable）时，循环就会停止，并说明停止原因。执行器添加的抑制项会在每次扫描前撤销，在移除之前始终作为未解决问题保留。每种结果都会生成修复记录，每轮也都会记录在 ~/.dvalincode/security/fix-loops/ 下；dvalin loop-stats 会汇总这些日志——循环达到 verified 的频率、到达通过状态的轮次数中位数和第 90 百分位数、触发的停止规则，以及循环停滞时仍未解决的问题（可使用 --json、--since、--executor 进行筛选）。

在不改变判定依据的前提下，尽量缩短每轮耗时。各引擎并行运行，因此扫描耗时取决于最慢的引擎，而非各引擎耗时之和。在各轮之间，逐个文件进行分析的引擎（Dvalin Built-in、Semgrep）只重新扫描更改涉及的文件和目标所在的文件；其他引擎始终扫描整个代码树。缩小扫描范围只用于指导执行器：任何可能导致循环停止的轮次，都要在同一代码树上进行完整扫描并重新判定；只有完整扫描结果才决定最终结果并写入记录。--full-rescan 会在每轮扫描所有内容，而 loop-stats 会报告每轮扫描耗时，以及完整扫描改变判定结果的频率。

对于代码问题，循环会先要求提供复现：仅包含测试；Dvalin 会在未修复的代码上运行这些测试，并要求测试确实失败——失败原因必须是断言失败，而不是缺少运行器或尚未编写的导入语句。测试会进行哈希校验；修复后必须让测试在不做任何更改的情况下通过，这次测试运行也会作为检查记录在案。若没有测试能证明某个问题，循环会在进行任何修复之前以 not-reproduced 状态停止：该问题可能是误报，需要由人工进行分类。运行器会自动推断（vitest、jest、mocha、node --test、pytest、go test），也可以通过 --repro-command 'npx vitest run {files}' 或在 dvalin.security.json 中设置 reproduce 来指定——绝不由执行器选择。

每轮修复还会拒绝 Agent 为了达成“扫描器不再报警”而采取的规避手段：将危险调用移到相近的替代项（eval → new Function、exec → spawn 并设置 shell: true）、删除存在漏洞的文件、删除测试、移除断言。实际上，只有第一种做法会骗过扫描器本身——因为规则不再匹配；复现测试和规避检查则能识破它们。

让它跟上今天的 main，并在 CI 中完成验证

dvalincode dvalin . --scanners builtin,snyk-code,snyk-oss --until-clean \
  --rebase-onto origin/main --executor codex --draft-pr --sign-key ci.key

使用 --rebase-onto 时，循环会在开始前以及每轮结束后拉取并将修复变基到上游，然后在该基线上进行判断。冲突会交给执行器处理——仅提供冲突文件，并注明“不要运行 git”——Dvalin 会继续自行完成变基；文件中残留标记就表示冲突尚未解决。如果无法解决冲突，就会中止变基、保持工作树原样，并以 rebase-conflict 状态停止循环。每次变基后，都会在新的基线上重新扫描基线，因此，队友已合入 main 的发现不会被归咎于这项修复。

--draft-pr 会提交 .dvalin/fix-record.json 中的记录，而 docs/examples/dvalin-fix-loop.yml 会在拉取请求中使用 reverify: true 重新执行该记录：重新扫描基线和提交，重新运行检查，并在撤销修复后（必须失败）和恢复修复后（必须通过）重新运行复现过程，最后使用 CI 密钥签名。

若要设置“无新增高风险发现”的增量门禁，请将策略和基线与仓库一同提交：

dvalin init
dvalin baseline
dvalin scan

这会创建 dvalin.security.json 和 .dvalin/baseline.json。抑制项必须说明理由，还可以指定负责人和到期日期。扫描输出是带版本的封装，其中包含确定性的门禁结果和可恢复的工作流 ID。

或者在每个拉取请求中运行——完全无需安装

# .github/workflows/security.yml
permissions:
  contents: read
  security-events: write
steps:
  - uses: actions/checkout@v5
    with:
      fetch-depth: 0        # so the scan can reach the base commit
  - uses: arthurpanhku/[email protected]
    with:
      fail-on: high
      diff: true            # only report on what this PR changed

发现会以内联评论的形式显示在拉取请求的差异中，也会显示在 Security 选项卡中。 无需 API 密钥、无需密钥、无需模型——扫描是确定性的，并在运行器本地进行。完整示例 →

diff: true 只报告拉取请求更改行上的结果，因此门禁会拦截此更改新增的内容，而不是仓库中原本就存在的所有问题。 这使得原本就不干净的代码库也能采用该检查。删掉它即可扫描整个仓库。

每条评论都会在结果旁注明扫描的覆盖范围——complete、partial 或 unknown——因为在缺少一半引擎的运行中得到“未发现问题”，与在完整运行中得到“未发现问题”并不相同。

并将证明发布在差异旁边

如果你的流水线生成了修复记录，请将它交给同一个 Action：

  - uses: arthurpanhku/[email protected]
    with:
      fix-record: fix-record.json

运行器会仅根据文件重新推导记录——重新计算其哈希值，并根据自身证据重新推导其判定结果——然后将结果发布到拉取请求中。记录若在签发后被编辑，就会在此处验证失败，并导致作业失败。

重新推导可以证明记录自洽。但它无法证明记录是由实际运行过任何操作的人签发的：记录中的每个字段，包括退出代码，都可以由伪造者写入，而自洽的伪造记录也能通过重新推导。要弥补这一差距，需要做两件事——在运行器上重新执行声明，并对运行器观察到的内容签名。

🔏 Verified Fix Record
✅ ce504a995395 · VERIFIED · scan-and-checks
- repaired by claude-code — recorded, and not consulted for this verdict
- targets: 1 before → 0 remaining
- coverage: complete → complete
- introduced: none (gate high/new)
- outcome: verified
- ✓ test: `npm run test` (exit 0)
- audit chain: verify-eeb1bae7 @ 80881867270d

如果修复导致回归，系统会在同一处说明，并因此使作业失败：

❌ 916e2eeaf065 · NOT VERIFIED · scan-and-checks
- introduced: 1 finding(s) the first scan did not report (gate high/new)
  - critical dvalin/sql-injection — src/db.ts:31
- outcome: regressed

在执行器上重新执行，并签署所见内容

  - uses: actions/checkout@v5
    with:
      fetch-depth: 0              # the base commit has to be reachable
  - run: npm ci                   # the project's checks run on the runner
  - uses: arthurpanhku/[email protected]
    with:
      fix-record: fix-record.json
      reverify: true
      signing-key: ${{ secrets.DVALIN_SIGNING_KEY }}   # optional

设置 reverify: true 后，所声明的记录仅提供其声称已修复的目标以及执行者的身份。其余内容都会重新观测：

• 检出并扫描 base 提交，因此每个声称的目标都必须确实存在于该提交中——记录不能把功劳归于自己，声称移除了一个原本就不存在的问题；
• 扫描 head，因此会在执行器上观测问题是否“已消失”；
• 在执行器上运行项目检查，检查项、门禁和扫描器均从 base 提交的 dvalin.security.json 中读取——拉取请求若放宽自己的门禁或删除自己的检查，就会按其试图更改的规则进行评判；
• 根据这些观测生成一条新记录，除非验证通过，否则作业将失败。

设置 signing-key 后，新记录会被签名（Ed25519，针对其哈希值）。密钥会载入内存，并在项目检查运行前从环境中移除，因此正在审查的代码无法读取它。下游——发布作业、其他代码仓库或审计人员——随后可以要求提供该签名：

dvalin keygen --out ci                          # once; store ci.key as a secret, publish ci.pub
dvalin verify-fix record.json --trusted-key ci.pub

未签名的记录，或仅由未指定密钥签名的记录，都会在 --trusted-key 下验证失败。有效签名表明哪个密钥为这条记录背书；是否信任该密钥由你决定。信任 CI 密钥的理由在于，CI 作业重新执行了验证，而非照搬验证结果。在本地，dvalin reverify <record> --base origin/main 会执行相同的重新验证，而 dvalin sign-fix 会为重新推导出的记录签名。 FVP-1 §4a, §5a →

或让你的 Agent 调用它

如果 Agent 正在编写代码，就必须由其他对象来检查代码。DvalinCode 是一个 MCP 服务，因此任何支持 MCP 的 Agent 都可以：

claude mcp add dvalin -- npx -y dvalincode mcp-serve --workspace .

只需一条命令，即可配置你实际使用的编辑器：

npx dvalincode mcp-install cursor        # .cursor/mcp.json
npx dvalincode mcp-install vscode        # .vscode/mcp.json
npx dvalincode mcp-install claude-code   # .mcp.json

这些格式有一个差异，若配置错误则不会有任何提示——VS Code 将服务器配置放在 servers 下，Cursor 则放在 mcpServers 下——因此，该命令会写入正确的格式，并合并到已有配置中。编辑器与 MCP →

dvalin_scan 接受 diff: "uncommitted"，只报告 Agent 刚刚编写的内容，而非仓库中原本就存在的所有问题——这就是可用的答案与一大堆既有发现之间的区别。它绝不会运行模型、编辑目标工作区或持久化 Dvalin 状态，因此客户端可以默认允许预览。如果要修复某项发现，Agent 会显式调用 dvalin_begin_verification 来记录一个简短的本地工作流；随后，它可以通过 dvalin_get_finding 和 dvalin_verify_findings，按指纹检索该发现并请求独立重新扫描。

最后这一点才是关键：刚刚编写修复的 Agent 可以请求对修复进行独立判定。Dvalin 会重新扫描、自行运行项目的检查，并返回一份 Verified Fix Record——包括修复针对的内容、仍然存在的问题、修复引入的新问题、作出判定所依据的门槛、运行过的命令及 Dvalin 观察到的退出代码，以及实际覆盖的代码库范围。修复的编写者会被记录下来，但绝不会参与评估。dvalin_verify_fix 可离线重新推导这份记录，因此接收记录的审核者无需信任签发该记录的工具。 FVP-1 → 响应包含 MCP structuredContent；可通过 dvalin_list_scanners 查看扫描器就绪状态。同一服务还提供 dvalin_run_task，作为可选的实现辅助工具，以及会话和审计证据工具。

下方列出的每个客户端都经过实际工具调用验证，而不只是完成握手——具体客户端、版本和日期以表格形式列出，而非写在句子里，因为手写的版本号很容易悄然过时。 集成支持 ↓ · Agent 集成 →

仓库还包含一个 同时适用于 Codex/Claude 的插件载荷，其中包括两种原生清单、共用的安全门控技能，以及本地 MCP 服务配置。安装后，用户可以直接从任务上下文中发现安全门控，而无需每位开发者都记住扫描提示词。 Codex 会遵循扫描的只读 MCP 注解。Claude Code 按设计要求显式授予一项 MCP 权限；插件会说明精确的、仅允许扫描的规则，而不是要求用户绕过所有权限。

无论你在哪里工作

同一项服务，按每种工具所需的方式访问：

MCP 配置格式不能互换——VS Code 将服务配置在 servers 下，而 Cursor 使用 mcpServers，配置错误时会静默失败——因此 mcp-install 会写入正确的格式，并合并到现有配置中。 编辑器和 MCP →

或与 Codex Security 互操作

Codex Security 可以将已完成且封存的扫描导出为 SARIF。导入这一可移植的投影，无需让 Dvalin 依赖 Codex Security 的私有状态目录：

DVALIN_CODEX_SCAN_DIR=/tmp/codex-security-results
npx @openai/codex-security scan . --output-dir "$DVALIN_CODEX_SCAN_DIR"
npx @openai/codex-security export "$DVALIN_CODEX_SCAN_DIR" \
  --export-format sarif --source-root "$PWD" --output /tmp/codex-security.sarif

dvalin import /tmp/codex-security.sarif .
dvalin scan . --fail-on high

导入会创建稳定的 Dvalin 修复案例；--no-persist 会验证交接过程，但不会更改待办列表。请将 Codex Security 的原始清单、 发现项和覆盖率产物保存在一起——Dvalin 会导入 SARIF 发现项投影， 但不会重写其封存包或重新解读其中的覆盖率。 集成指南 →

然后让它修复发现的问题

dvalincode dvalin . --fix --verify --draft-pr

此步骤会使用模型——你的模型，以及任何兼容 OpenAI 的端点。它会在隔离的工作树中准备有针对性的修复，运行你的测试，并要求重新扫描结果干净后，才允许继续创建草稿 PR。它绝不会自动合并，也绝不会将扫描结果干净视为代码安全的证明。

此动画取自真实应用，而非模拟效果。输入是一个采用 Apache-2.0 许可证的示例，改编自 OWASP NodeGoat， 其贡献路由会执行用户控制的文本。

🛡️ 这次运行实际做了什么

Dvalin 将开源扫描器的证据转化为受控的扫描 → 修复 → 测试 → 重新扫描 → 起草 PR 工作流。以下是上方动画中这次运行的实际数据：

扫描和加固的控制平面使用开源组件：

• Semgrep CE 及其社区规则，用于语义 SAST。
• Trivy，用于文件系统漏洞、机密信息和错误配置。
• OSV-Scanner 搭配开放的 OSV 数据库，用于依赖项漏洞。
• DvalinCode 采用 MIT 许可证的内置规则、修复编排、测试和重新扫描门禁，以及用于导入其他兼容扫描器结果的 SARIF 2.1。

扫描器负责发现并排列证据。配置好的模型会提出源代码更改；DvalinCode 会约束此工作、记录差异、运行项目测试、重新扫描已更改的代码树，并明确控制 PR 发布。它不会自动合并，也不会声称扫描结果干净就证明不存在 Bug。如果修复建议步骤也必须完全在本地运行并保持开放，可以通过 Ollama 选择开放权重模型；托管模型的许可取决于提供商。

事后仍可证明 Agent 做了什么：

dvalincode report verify    # re-derive the hash chain of the last run's audit log

🧩 集成支持

AI 助手编写的代码在合并前会经过四方：编写代码的 Agent、开发者用来查看代码的编辑器、负责把关的拉取请求，以及必须相信结果的审查者。如果安全结论只存在于其中一处，就不算门禁——而只是下一阶段可以忽略的建议。

Dvalin 通过一个 MCP 服务和一次确定性扫描覆盖这四个环节，因此无论谁来询问，得到的答案都不会改变。

✅ 表示已端到端驱动真实客户端，并观察到工具调用。 ⚙️ 表示配置已生成且其格式经过测试，但尚未捕获会话。这里不会掩盖两者的区别，因为配置文件能够加载，并不能证明工具曾被调用。

各项声明的依据

之所以创建每周运行的工作流，是因为早期版本的声明手动写入了两个 CLI 版本号，几周内二者都已过时，却没有任何提示。现在，它会根据这些工具当周发布的版本重新检查，因此上述日期要么自动更新，要么就不再公开变动。

同一条发现，在不同位置的呈现

Claude Code——仅将一个只读工具列入允许列表，并直接调用 MCP：

Codex——进行一次只读 MCP 调用，并单独显示已完成的 JSONL 工具事件：

VS Code——以波浪线和状态栏显示相同的扫描器约定：

🏛️ 它经得起安全审查

当不止一个人依赖这个工具时，最后这条命令才是关键。DvalinCode 是一个完整的编码 Agent——包含终端、Web GUI 和桌面应用——其设计目标是由组织而非开发者来限定它可以执行的操作：策略文件会限制模式、命令、路径、工具和模型；每次运行都会被哈希链式记录到防篡改审计日志中；任何内容都不会发送给出口防护机制未放行的提供方。仓库策略永远只能收紧机器级策略，不能放宽。

如果你负责批准这类工具，请从 APPROVABILITY-PLAN.md 以及每个版本都会附带的证据包开始。

🎯 核心目标

让每一位编写代码的人类或 Agent 都通过同一道独立的安全关卡。

DvalinCode 构建为一个兼容 Agent 的安全运行时，而不是又一个通用编码 Agent 基准测试项目。它的核心产品是扫描证据、策略、基线、确定性验证和可移植接口，人类开发者、外部 Agent 或 CI 都可以调用这些功能。内置编码 Agent 的能力足以可靠地实现和测试有针对性的修复；其模型生成的文字说明绝不决定安全关卡是否通过。

• 支持任何模型——每个兼容 OpenAI 的端点都是一等公民，也包括本地模型。你的工作流不应受制于某一家供应商的定价、速率限制或质量波动。
• 默认安全——提供三级审批、差异预览、撤销堆栈和沙盒化的 shell 执行。让你可以放心地让 Agent 全自动运行。
• 体积小，易于审计——一个约 25MB 的二进制文件、少量运行时依赖，以及一个周末就能读完的代码库。通过检查建立信任，而非空口承诺。从 v0.5 开始，每次 Agent 运行也都可审计：所有操作均记录在防篡改的哈希链日志中，事后可供验证。
• 开放且易于嵌入——Agent 核心提供简洁的 REST + WebSocket API，可直接接入你自己的产品、CI 或内部工具。
• 满足任何公司的审批要求——治理能力是内置的，而非事后附加。组织策略限制影响范围（可控），dvalincode trust 使安全态势可自行验证（透明），哈希链日志则证明每次运行执行了哪些操作（可审计）。这三项能力正是安全评审所需的全部保障，能够让审批顺利通过；而云端、封闭式、日志可变的 Agent 在结构上很难提供这些保障。审批计划 →

内置的Web GUI 是该运行时的参考实现和展示平台——它是公共 API 的首个使用者，展示了运行时的所有功能。

✅ 团队为何选择 DvalinCode

DvalinCode 的差异化优势在于可获审批。它专为需要在 AI 编码接触生产代码仓库之前，通过安全、合规和数据治理审查的团队打造。

• 闭环安全修复——在本地扫描，或导入来自 CodeQL、GitHub Code Scanning、Semgrep 或兼容扫描器的 SARIF；将发现项保存为本地修复案例；创建隔离的 dvalin/remediate/... 工作树；然后发送包含源代码上下文和验证说明的针对性修复提示词。
• 将技能作为受治理的操作流程——上传、下载和检查本地技能包。内置的安全扫描与修复技能会告知 Agent 应使用哪些工具，并让工作流可在不同机器间移植。
• 模型选择自由，不偏离策略——可使用 DeepSeek、OpenAI、通过 OpenRouter 使用 Claude、Groq、Ollama 或任何兼容 OpenAI 的端点，同时保持工具权限、审计和工作区策略一致。
• 安全证据，而非空谈安全——项目包含 OpenSSF Scorecard 支持、CodeQL、Dependabot、固定版本的 Actions、CODEOWNERS、ISO/IEC 42001 对齐文档、AI 变更影响记录和哈希链运行日志。
• 默认本地优先——会话、配置、配置档案、记忆和审计日志都保存在 ~/.dvalincode/ 下；.dvalincodeignore 和策略控制会限制 Agent 可读取、写入或执行的内容。

🛡️ 安全与治理

DvalinCode 为开源和企业审查维护项目级治理证据。这是其区别所在：对于这些团队，AI 编码必须通过安全审批，才能进入生产代码仓库：

• 威胁模型 — 全面覆盖 Agent 编码运行时的攻击面 （恶意的 AGENTS.md、遭投毒的 MCP 服务、提示词注入升级、 出站流量、审计篡改、供应链、沙箱逃逸），并为每项威胁映射 防御控制措施和真实存在的剩余风险。威胁模型 →
• 支持 OpenSSF Scorecard — 定时运行 Scorecard 工作流、上传 SARIF、CodeQL、Dependabot、CODEOWNERS、最小权限工作流权限，以及 固定 SHA 的 GitHub Actions。控制措施映射 →
• 符合 ISO/IEC 42001 — AI 管理体系范围、AI 政策、角色映射、 风险登记册、AI 变更分类、必需记录和审查周期。 AIMS 符合性 →
• AI 变更影响评估 — 可重复使用的模板，用于评估影响模型/提供商行为、 提示词、权限、工具、审计日志或发布安全的变更。 模板 →
• 受监管用途的安全态势 — 本地优先的数据处理、受策略控制的自主性、 最精简的审计记录，以及面向金融、医疗、安全敏感型 SaaS 和企业内部 使用的发布供应链证据。
• Dvalin 安全工程 — 专用的 Dvalin 工作区将内置扫描器与已安装的 Semgrep CE、Trivy 和 OSV-Scanner 结合使用，规范化 SARIF 发现项， 推动有测试支持的隔离修复，并明确准备可供审查的 PR 草稿，不会自动合并。 工作流 →

这些文档是实施证据和操作流程；它们不声称获得了第三方 ISO 认证。

⭐ v0.14.0 新增内容 — Dvalin 安全工程

• Home 整合 Chat 和 Cowork — GUI 现在提供统一的 Home 工作区， 包含只读的 Ask 意图和需审批的 Collaborate 意图，同时保留相同的项目 和对话上下文。
• Code 再次聚焦 — 已从 Code 中移除旧版 Security 和 Routines 面板， 其侧边栏现在专用于项目和自主实现。
• Dvalin 成为一等工作区 — 协同使用内置扫描器以及已安装的 Semgrep CE、Trivy 和 OSV-Scanner；导入 SARIF；为发现项评分并进行分诊； 持久化修复案例；并创建隔离的修复工作树。
• 从证据到 PR 草稿，一条龙完成 — 选定的发现项可以启动有证据支持的 Agent 修复，运行针对性测试、类型检查、构建和新一轮扫描， 审查差异，并明确发布 PR 草稿，不会自动合并。
• Agent 循环更快收敛、成本更低 — 先调查再编辑和停滞检测可减少重复 失败操作，通用工具输出受到限制，提示词保持只追加以便复用缓存， 提供商用量统计现已计入缓存命中/未命中。
• 提供商与评估升级 — 现在支持原生 Anthropic 提示词缓存和缓存统计， SWE-bench Docker 测试框架会报告官方分数、策略违规、停滞情况以及 Token/缓存指标。

⭐ v0.12.4 新增内容 — 完成任务后再停止

• 过程说明不再终止任务 — 类似“让我验证一下文件”的回复会被识别为待完成工作，Agent 会立即继续执行承诺的操作，而不是将其视为最终答复。
• 截断的回复会自动恢复 — 保留提供方的结束原因，因此因令牌上限而截断的输出会触发下一步模型调用。
• 常规编码轮次有充足时间完成 — 每轮操作上限现在是紧急情况下的 100 次操作保护阈值，而非常规的 15 次操作停止点；更严格的组织策略上限仍优先适用。
• 明确标记任务完成 — 系统会指示 Code 模式仅在完成请求的工作和针对性验证后，才返回不包含工具调用的答复。

⭐ v0.12.3 新增内容 — 更可靠地运行长时间 Code 模式

• 长时间编码轮次会持续运行 — Code 模式现在会在活动工具循环期间压缩上下文，在估算令牌数时计入完整的提供方请求，并将默认迭代检查点从 10 次提高到 40 次。
• 中断后可以恢复 — 轮次中断或连接关闭时，会保留已完成的工具状态，因此后续的 continue 会从工作区的实际进度继续。
• Agent 活动清晰可见，干扰更少 — 运行中的会话会显示侧边栏加载状态，每条回复都会报告耗时；点击即可查看其操作时间线，而原始工具调用默认折叠。
• 通过 Code 模式使用 GitHub 工作流 — 现在可通过受管控的 Shell 审批流程，执行支持网络的 git 和 GitHub CLI（gh）操作，包括拉取、推送、创建 PR 以及 Actions／仓库命令。
• 发布更安全 — 软件包和 CLI 版本保持同步，发布前会运行 prepublishOnly，执行构建、类型检查和测试套件。
• 简单任务保持简单 — 操作预算按整个轮次执行，而不是在每次模型迭代时重置；系统会提示 Code 模式选择最直接的最短路径，并在针对性验证通过后停止。

⭐ v0.12.2 新增内容 — 🖥️ 桌面应用里程碑：开箱即用

• 🖥️ 原生桌面应用现在可在 macOS 上开箱即用 — DvalinCode.app 会在嵌入式引擎上打开真实的程序坞窗口（WKWebView，不使用 Electron）。 修复了所有早期桌面版本中都存在的两个线程错误： 阻塞式 WebView 循环不再让嵌入式服务无法运行（导致空白窗口）， WebView 也会按 macOS 要求在主线程上运行（不再出现窗口完全不显示的情况）—— 服务现在运行在同一二进制文件的子进程中。
• 📦 一行安装命令即可安装应用 — 在 macOS 上， curl … install.sh | bash 现在还会将 DvalinCode.app（带有 DvalinCode 图标）安装到 /Applications，因此通过 CLI 安装后， 可直接从 Launchpad 启动桌面窗口。使用 DVALINCODE_NO_APP=1 选择不安装；使用 DVALINCODE_GUI_VERSION 固定版本。
• ✅ macOS 桌面版不再是“实验性”版本 — 已验证窗口和 嵌入式服务均正常运行；Windows 和 Linux 桌面版为交叉编译版本， 仍处于预览阶段。

📸 预览

一次真实的 Dvalin 漏洞代码扫描 — 安全健康度 22/100 · F，列出了引擎实际报告的 10 项发现，并精确定位到行：

已验证的结果 — 一次由模型驱动的真实 Verify 轮次检查了修复，运行了回归测试和全部四个开源引擎，随后确定性服务端重新扫描报告覆盖完整、门禁通过、发现数为 0、100/100 · A：

当前 Mac mini 冒烟测试

2026-09-18，提交 d4bf02b 在搭载 macOS 27.0 的 Apple 芯片 Mac mini 上构建并作为本地应用运行。临时测试项目没有 API 密钥或已配置的模型，并且只选择了不依赖网络的内置扫描器。Dvalin 在 quantity.js:3 定位到一个故意引入漏洞的 eval，报告 1 项高危发现，88/100 · B，记录了完整的已选引擎覆盖率 1/1，并阻止了 high 安全门禁：

将 eval 替换为受约束的整数解析器并添加可执行输入回归测试后，全部 3/3 项测试均通过。随后，所选引擎报告 发现数为 0，100/100 · A、覆盖完整且门禁通过：

同一 CLI 工作流运行了 npm run test，退出代码为 0，生成了一个 dvalin-fix-record/v2，并且 dvalin verify-fix 在离线状态下重新推导出该记录，结果为 ok: true。干净扫描的截图是在导入该记录前截取的，因此仍显示 离线修复记录：未附加。Web 工作区现在可以导入可移植的 JSON 记录，在离线状态下重新推导其哈希和判定结果，并显示执行器、检查项和退出代码。干净扫描只是所选引擎的证据，并不代表代码已被证明安全。

Home → Code → Dvalin — 当前工作区：

上方扫描图片是对文档所述的派生自 NodeGoat 的案例进行真实运行后直接截取、未经编辑的画面：扫描器已运行，模型修复了源代码，项目测试已运行，代码树也已重新扫描。没有暂存任何内容；100/A 表示配置的引擎未发现问题，并不代表代码已被证明安全。

🆚 何时选择 DvalinCode

🚀 快速安装

Homebrew（macOS / Linux）

brew tap arthurpanhku/dvalincode https://github.com/arthurpanhku/dvalincode
brew install arthurpanhku/dvalincode/dvalincode

安装的内容与一键安装命令所用的校验和签名发布归档相同，且 brew upgrade 会让它保持最新。Homebrew 不会应用 macOS 隔离属性， 因此此安装方式不受 Gatekeeper 限制。

macOS / Linux（一键安装）

curl -fsSL https://raw.githubusercontent.com/arthurpanhku/dvalincode/main/scripts/install.sh | bash

检测你的操作系统和架构，下载对应的二进制文件，安装到 ~/.dvalincode/，并将其添加到 PATH。在 macOS 上还会将原生 DvalinCode.app 安装到 /Applications（使用 DVALINCODE_NO_APP=1 可跳过），这样桌面窗口便可直接从 Launchpad 启动。重新加载后：

source ~/.zshrc    # or ~/.bashrc
dvalincode                       # interactive terminal agent
dvalincode dvalin .              # white-box security scan (GUI-independent)
dvalincode serve                 # start the web GUI, open the browser
dvalincode serve --host 0.0.0.0 --no-open   # host it on a server for remote/browser use
echo "inspect src and summarize" | dvalincode run - --output-format stream-json
dvalincode mcp-serve             # task-level stdio MCP server for external agents

无头模式下的 run 和 mcp-serve 与交互式客户端一样，使用相同的策略和审计关卡。有关 cron、CI 和外部 Agent 示例，请参阅无人值守操作示例。

扫描或创建修复记录的运行，还会在回答旁附带一个 verification 封套 — 在 json、stream-json 和 MCP dvalin_run_task 结果中都如此。coverageStatus 表示此次运行有证据支持的最低覆盖率，因此一次完整扫描不能代表一次部分扫描；运行生成的任何记录也会按路径列出，以便离线重新推导。CI 门禁可以直接读取：

jq -e '.verification.coverageStatus == "complete"' run.json || exit 1

这与拉取请求评论采用的是同一规则，只不过是在没有人工监看的情况下执行。Harness 模式 →

Windows

从 Releases 下载 dvalincode-v*-windows-x64.zip，解压，然后双击 start.bat。

手动下载

从发布页面下载适用于你平台的归档文件：

请使用 SHA256SUMS.txt（包含在每个版本中）进行校验。

每个版本还会附带 dvalincode-v*-evidence.json——这是随附二进制文件在构建机器上为自身生成的证据包：包含两次真实的受治理运行，一次获准，一次被策略拦截，并附有各自的哈希链。在安装任何内容之前，你可以先检查本页面上的声明：

dvalincode evidence verify dvalincode-v0.14.0-evidence.json   # offline, reads only the file

证据包的校验和包含在 SHA256SUMS.txt 中，该文件是此版本构建来源证明的对象。了解其生成方式 →

**macOS Gatekeeper：**二进制文件未经签名。首次运行时，可使用 xattr -dr com.apple.quarantine ~/.dvalincode 清除隔离标记，或在 Finder 中右键点击二进制文件 → 打开 → 确认。

保持最新

DvalinCode 会自行更新，无需重新运行安装程序：

dvalincode update --check   # is a newer release out? (read-only)
dvalincode update           # download, verify, and install the latest

它会在 GitHub 上查找最新版本；对于二进制安装，会下载相应的归档文件，在替换任何内容之前，先根据版本的 SHA256SUMS.txt 进行校验，然后就地替换 ~/.dvalincode/。npm 安装会通过 npm i -g 更新，源码检出则会执行 git pull。添加 -y 可跳过提示，添加 --prerelease 可跟踪预发布版本，添加 --json 可用于脚本。

macOS 桌面应用启动时会检查单独的 gui-v* 发布通道。如果有更新版本的 GUI，它会在下载前征求同意，根据 SHA256SUMS-gui.txt 校验归档文件，验证应用版本，然后替换并重启 DvalinCode.app。替换失败时会回滚到之前的应用。

🎬 首次设置

**终端（默认）：**运行 dvalincode。首次启动时，它会引导你完成一次性服务商设置（选择服务商、粘贴 API 密钥、选择模型），并将设置保存到 ~/.dvalincode/config.json。随后即可在提示符下开始使用：输入内容即可聊天，输入 /mode 可在 Chat / Cowork / Code / Dvalin 之间切换，输入 /help 可查看命令。在 GUI 中，Chat 和 Cowork 位于 Home 下。

**Web GUI：**运行 dvalincode serve，然后：

1. 服务会在 http://localhost:3000 启动，并自动打开浏览器。
2. 点击侧边栏左下角的 LLM Configuration。
3. 选择服务商，粘贴 API 密钥，选择模型，然后点击 Save。
4. 可选：将当前配置保存为命名配置文件（例如 fast、cheap、local-ollama），以便之后快速切换。

两种方式共用 ~/.dvalincode/ 中的配置和会话。

✨ 功能

⌨️ 斜杠命令

🛠️ 架构

┌───────────────────────────┐   ┌─────────────────────────┐
│  Terminal UI (readline)   │   │  Browser GUI (React/Vite)│
│  streaming · approvals    │   │  ChatThread · DiffViewer │
└─────────────┬─────────────┘   └────────────┬────────────┘
              │ in-process          HTTP / WebSocket
              │                ┌───────────────▼─────────────┐
              │                │  Express + ws server         │
              │                │  /api/* · `dvalincode serve` │
              │                └───────────────┬─────────────┘
              └──────────────┬─────────────────┘
┌────────────────────────────▼────────────────────────────┐
│  runAgentTurn — shared turn-runner (src/agent/session)   │
│  provider · prompt (mode · git · AGENTS.md) · session    │
└────────────────────────────┬────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────┐
│                    Agent Engine                          │
│  AgentLoop (8-state machine) → AgentRunner              │
│  Streaming · Interrupt · Undo stack · LLM compaction    │
│  run_start / run_end → AuditSink (hash-chained JSONL)   │
└──────────────────────────┬──────────────────────────────┘
                           │ run()
┌──────────────────────────▼──────────────────────────────┐
│  ToolRegistry — Zod schemas + permission gating         │
│  + audit taps: tool_call · file_* · shell_exec          │
│  read_file · list_files · search_text · git_status ·    │
│  write_file · edit_file · delete_file · shell           │
└─────────────────────────────────────────────────────────┘

Agent 循环 — 8 个状态

RESTORE → COMPACT → COMMAND → BUILD → RUN → SAVE → RESPOND → DONE

1. RESTORE — 从 ~/.dvalincode/sessions/ 加载会话
2. COMPACT — 如果上下文接近上限，则压缩历史记录（大模型摘要）
3. COMMAND — 处理内置斜杠命令
4. BUILD — 组装系统提示词（模式提示词 + 项目 + git + AGENTS.md）
5. RUN — 将任务交给 AgentRunner，执行大模型工具调用循环
6. SAVE — 保存会话
7. RESPOND — 生成跨会话摘要记忆
8. DONE

🧪 测试

npm test

584 项核心测试 · 74 个文件 · 全部通过。 VS Code 扩展有单独的 37 项测试套件，另有一项可选的已发布软件包集成测试。

🏗️ 从源代码构建

需要 Bun（curl -fsSL https://bun.sh/install | bash）。

git clone https://github.com/arthurpanhku/dvalincode
cd dvalincode
npm install
npm run dev:all                 # start backend (3001) + Vite (5173)

为所有平台构建发布二进制文件：

bash scripts/build-release.sh   # → release/ with tar.gz / zip + SHA256SUMS.txt
bash scripts/build-release.sh darwin    # macOS only
bash scripts/build-release.sh windows   # Windows only

发布版本前：

(cd release && shasum -a 256 -c SHA256SUMS.txt)
unzip -l release/dvalincode-v*-windows-x64.zip | grep 'web/dist/index.html'
tar tzf release/dvalincode-v*-macos-arm64.tar.gz | grep 'DvalinCode.app/Contents/Resources/AppIcon.icns'

Windows 冒烟测试：在 Windows 上解压 dvalincode-v*-windows-x64.zip，并从解压后的文件夹运行 start.bat。服务应打开 http://localhost:3000。如果报告 B:\~BUN\root\web\dist 下的 ENOENT 路径错误，则表示编译后的 Bun 虚拟路径检测出现回归；打包后的二进制文件必须能解析到解压后的可执行文件旁边的 web/dist。

注意：只有在 Windows 上编译时，Bun 才允许注入 Windows .exe 图标和元数据。macOS/Linux 跨平台构建仍会生成有效的 Windows 压缩包，但其中的 .exe 不含嵌入式图标。

🌐 提供商

DvalinCode 支持任何兼容 OpenAI 的端点。内置预设按成本排序：

DvalinCode 会在顶部栏实时显示每个会话的费用 — 在 LLM 配置对话框中切换提供商、保存命名配置文件，并随时比较。

❓ 常见问题

xattr -dr com.apple.quarantine ~/.dvalincode

🤝 参与贡献

欢迎贡献。此代码库刻意保持小巧且精简 — 请参见 CONTRIBUTING.md。

git clone https://github.com/arthurpanhku/dvalincode
cd dvalincode && npm install
npm test                # 584/584 core tests ✅
npm run typecheck

📄 许可证

MIT — 请参见 LICENSE。

🔗 独立性与致谢

DvalinCode 是一项独立实现。它与 Anthropic、Claude、Claude Code、OpenAI、OpenAI Codex、GitHub、Cursor、Aider、opencode、Cline、HKUDS/nanobot 或此处提及的任何其他 项目或供应商均无关联，也未获得其赞助或认可。

我们衷心感谢公开研究、开源项目、已发表论文、标准、发行说明，以及 Agent 编码 生态系统中的常见工作流模式，为 DvalinCode 的产品方向和架构提供了参考：

• HKUDS/nanobot（MIT）帮助验证了 DvalinCode 的 TurnState 流程所采用的显式轮次状态方案。
• ReAct 论文（Yao 等人，2022） 提出了广泛使用的“推理、行动、观察”循环，为许多现代工具调用型 Agent 提供了参考。
• OpenAI 的 tool_calls 消息格式，以及更广泛的 OpenAI 兼容供应商生态系统，为 DvalinCode 的模型／工具交互提供了可移植的接口。
• OpenAI Codex / Codex CLI、Claude Code、Aider、opencode、Cursor、Cline 及 类似的编码 Agent，明确了用户对终端 Agent、计划／构建模式、权限提示、项目本地上下文、 沙箱、会话生命周期、MCP 集成和以差异优先的编辑工作流的预期。
• OpenAI Codex Security 及其 公开文档为 Dvalin 的专业安全 Agent 研究和可移植的 SARIF 交接提供了参考。Dvalin 仍是独立且具有竞争力的安全运行时。
• 编码 Agent 工具中常见的 AGENTS.md 项目指令约定，为 DvalinCode 加载项目本地指令的行为提供了参考。
• CodeQL、GitHub Code Scanning、Semgrep、SARIF、OpenSSF Scorecard 和 ISO/IEC 42001 为 DvalinCode 的安全修复和可审批性方针提供了参考。
• Git worktree、MCP 和本地优先的开发者工具模式，影响了产品在隔离修复、受治理的工具访问和 可审计执行方面的方向。

这些参考帮助我们理解用户对编码 Agent 的期待。除非明确注明，DvalinCode 的源代码、提示词、UI 文本、工具架构、模块布局 和产品实现均为原创。我们没有复制上述项目中的源代码、提示词或 UI 文本。

完整来源参考：docs/REFERENCES.md

💛 感谢我们的贡献者

每个问题、想法、文档改进、测试和代码贡献，都有助于让 DvalinCode 变得更好。

查看完整贡献历史，其中包括自动化依赖更新和维护更新。

_{想加入他们吗？请阅读贡献指南并提交你的第一个拉取请求。}