DvalinCode

English · 中文 · 🌐 dvalincode.dev

Release Downloads Tests License OpenSSF Scorecard Platforms LLM Support English / 中文

为人类和 AI Agent 编写的代码提供开放安全工程能力。
每一次修复，都自带证明。

Agent 修好了一个安全问题之后，总得有人判断它到底修好没有。市面上几乎所有工具都是 去问那个写下修复的模型 —— 而这恰恰是模型最无法违背自身利益去诚实回答的问题。 **Dvalin 自己来判断，并把证明交给你。** 它重新扫描、亲自跑你项目的测试，看的是它 自己启动的进程返回的退出码。修复是谁写的 —— 我们的 agent、Claude Code、Codex、 Copilot，还是人 —— 只被记录，绝不参与判定。产物是一份 **Verified Fix Record**： 一个很小的 JSON，任何人都能离线复验，不需要联网，也不需要任何 Dvalin 的本地状态。 ```sh 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 ``` 这份记录声称的东西刻意很窄：*这些 finding 消失了，这些检查被观察到通过了。* 它不是 「你的代码安全了」这种断言，Dvalin 也不允许它被这样解读 —— 每份记录都带着这次扫描 究竟覆盖了什么，而一个没有任何检查能确认的修复，不会通过。 [开放规范 →](docs/spec/FIX-VERIFICATION.md) 修复本身也是一次改动，而改动既会移除问题，也可能带来新问题。所以记录里还带着复扫 看到、而首扫没有看到的东西，以及这次判定所依据的门禁阈值：一个删掉了 `eval`、却引入 了 SQL 注入的修复，会被记为 `regressed`，不予通过。签发方根本没去看的记录同样不通过 —— `introduced: not determined` 直接失败，因为「不去查」绝不能比「查了并且查出问题」 得分更高。 Dvalin 是放在“代码生成”和“允许合并”之间的独立安全运行时。人类开发者、Coding Agent 和 CI 调用同一套版本化协议完成发现、修复与验证。它既可以独立运行，也可以通过 可移植的 SARIF 与 Codex Security 等专业系统互操作。内置 Coding 能力只负责可靠地执行 聚焦修复，不是安全结论的信任边界，也不以打败所有通用 Coding Agent 为目标。 详见[安全 Agent 战略](docs/SECURITY-AGENT-STRATEGY.md)。 --- ## ⏱️ 30 秒，免安装，不需要 API Key ```sh npx dvalincode security scan . # 安装 npm 包后也可直接运行：dvalin scan . ``` 就这一条。它用内置规则扫描当前目录里的注入、硬编码密钥、XSS、`eval` 和不安全的 shell 调用，然后把结果打出来。不需要注册、不需要模型、不需要配置，代码不出本机。 默认只启用一定存在的 Dvalin Built-in；可选引擎必须显式启用，其固定安装命令可以先审查： ```sh dvalin scanners list dvalin scanners install semgrep # 只显示并审查命令 dvalin scanners install semgrep --yes # 在 Dvalin 策略约束下执行 ``` 要建立“禁止新增高风险问题”的增量门禁，把策略和基线一并提交到仓库： ```sh dvalin init dvalin baseline dvalin scan ``` 这会创建 `dvalin.security.json` 和 `.dvalin/baseline.json`。每条 suppression 都必须 写原因，还可以设置 owner 和过期时间。扫描输出是版本化 envelope，包含确定性 gate 结果和可恢复的 workflow ID。 ### 或者挂到每个 PR 上 —— 完全不用装任何东西 ```yaml # .github/workflows/security.yml permissions: contents: read security-events: write steps: - uses: actions/checkout@v5 with: fetch-depth: 0 # 让扫描能取到 base commit - uses: arthurpanhku/dvalincode@v0.18.0 with: fail-on: high diff: true # 只报告这个 PR 改动的部分 ``` 扫描结果会直接标注在 PR 的 diff 上，同时进入仓库的 Security 页。不需要 API Key、 不需要任何 secret、不调用模型 —— 扫描是确定性的，且只在 runner 本地进行。 [完整示例 →](docs/examples/dvalin-scan.yml) `diff: true` 只报告 PR 改动到的行，因此这道门禁拦的是这次改动**新引入**的问题， 而不是仓库里本来就有的一堆存量问题。这正是它能在一个并不干净的代码库上被接受的 原因。去掉它就是全仓库扫描。 每条评论都会在结论旁边写明这次扫描的**覆盖率** —— `complete` / `partial` / `unknown`。因为「没发现问题」在半数引擎没装的情况下，和在完整扫描下，根本不是同一个 答案。 ### 再把证明贴到 diff 旁边 如果你的流水线产出了 fix record，把它交给同一个 action： ```yaml - uses: arthurpanhku/dvalincode@v0.18.0 with: fix-record: fix-record.json ``` runner 会仅凭这个文件本身重新推导它 —— 重算哈希，并从它自己的证据重新推出结论 —— 然后把结果发到 PR 上。一份签发之后被改过的记录会在这里失败，并让整个 job 失败。 审查者不需要信任产出它的流水线，也不需要信任我们。 ``` 🔏 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 ``` 引入了新问题的修复，会在同一个地方说清楚，并让这个 job 失败： ``` ❌ 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 ``` ### 或者让你的 agent 调用它 如果代码是 agent 写的，那检查它的就不能是同一个 agent。DvalinCode 本身是个 MCP server，任何支持 MCP 的 agent 都能接： ```sh claude mcp add dvalin -- npx -y dvalincode mcp-serve --workspace . ``` 一条命令配好你实际在用的编辑器： ```sh 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 的 key 是 `servers`，Cursor 是 `mcpServers`，填反了编辑器会照单全收然后当没看见。这条命令会写对，并且合并进已有 配置而不是覆盖。[编辑器与 MCP →](integrations/mcp/) `dvalin_scan` 支持 `diff: "uncommitted"`，只报告 agent 刚写的部分，而不是仓库里的全部存量问题。它不跑模型、不修改目标 workspace、也不持久化 Dvalin 状态，因此客户端可以默认允许这次预览。确认要修复某条发现后，Agent 再显式调用 `dvalin_begin_verification` 创建精简的本地安全 workflow，用 fingerprint 精确读取单条发现，再通过 `dvalin_get_finding` 和 `dvalin_verify_findings` 请求独立复扫。响应包含 MCP `structuredContent`，并可通过 `dvalin_list_scanners` 查询组件是否就绪。同一 server 也提供可选的 `dvalin_run_task` 实现助手，以及 session 和审计证据工具。 下面每一个客户端都被驱动到了真实的工具调用，而不只是握手成功 —— 具体是哪个客户端、 哪个版本、哪一天验的，写成了表格而不是一句话，因为手写的版本号会悄无声息地过期。 [集成支持 ↓](#-集成支持) · [Agent 集成 →](integrations/) 仓库还提供一份 [Codex/Claude 双兼容插件](integrations/dvalin-security/)：同时包含两套 原生 manifest、共享安全门禁 skill 和本地 MCP server 配置。安装后，agent 可根据任务 上下文自动发现门禁，不再依赖每位开发者记住扫描提示词。 Codex 会采纳扫描工具的只读 MCP 标注；Claude Code 按其安全设计仍需显式授权一次。 插件给出精确到只读扫描工具的 allow 规则，不要求用户绕过所有权限。 ### 你在哪儿干活，它就在哪儿 同一个 server，按每个工具各自的方式接进去： | Harness | 怎么接 | |---|---| | **Claude Code** | [双兼容插件](integrations/dvalin-security/)，或 `claude mcp add` · [独立 skill](integrations/claude-code/) | | **Codex** | [双兼容插件](integrations/dvalin-security/)，或 `codex mcp add` · 与 Codex Security 的 [SARIF 互操作](integrations/codex-security/) | | **Cursor** | `dvalincode mcp-install cursor` | | **VS Code** | `dvalincode mcp-install vscode` · 在 Problems、coverage/gate 状态和离线 VFR 校验中展示结果的[扩展](editors/vscode/) —— *已构建，尚未发布* | | **Windsurf · Zed** | 在各自设置里配 stdio MCP —— [server 命令](integrations/mcp/) | | **任意 MCP 客户端** | [MCP registry](https://registry.modelcontextprotocol.io/)：`io.github.arthurpanhku/dvalincode` | | **GitHub Actions** | [Marketplace action](https://github.com/marketplace/actions/dvalin-security-scan) —— 结果直接标在 PR diff 上 | | **任意 CI** | `dvalin scan . --fail-on high`，输出 SARIF 供 code scanning 用 | 各家的 MCP 配置格式并不通用——VS Code 的 key 是 `servers`，Cursor 是 `mcpServers`， 填错了不会报错只会静默失效——所以 `mcp-install` 会写对格式，并合并进已有配置。 [编辑器与 MCP →](integrations/mcp/) ### 或者和 Codex Security 互操作 [Codex Security](https://github.com/openai/codex-security) 可以把已完成且密封的扫描 导出为 SARIF。Dvalin 只导入这个可移植投影，不耦合 Codex Security 的私有状态目录： ```sh 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 remediation case；`--no-persist` 可以只校验交接件而不修改 backlog。请继续保存 Codex Security 原始的 manifest、findings 和 coverage 工件——Dvalin 只导入 SARIF finding 投影，不会改写其密封 bundle，也不会重新解释其覆盖率。 [集成指南 →](integrations/codex-security/) ### 然后让它把找到的问题修掉 ```sh dvalincode dvalin . --fix --verify --draft-pr ``` 这一步**才**会用到模型 —— 你自己的模型，任何 OpenAI 兼容端点。它在隔离的 worktree 里准备聚焦修复，运行你的测试，并且必须通过一次干净的复扫，才允许进入 Draft PR。 它不会自动合并，也不会把「扫描干净」当成「代码安全」的证明。

Dvalin 扫描有漏洞的 OWASP NodeGoat 示例得到 22/100 F 与 10 条发现，修复后复扫为 100/100 A

这段动图来自真实应用，不是设计稿。输入代码改编自 Apache-2.0 许可的 [OWASP NodeGoat](https://github.com/OWASP/NodeGoat/tree/c5cb68a7084e4ae7dcc60e6a98768720a81841e8/app/routes)， 原始 contribution route 会执行用户可控文本。 ## 🛡️ 上面那次运行到底做了什么 Dvalin 把开源扫描器的证据组织成受控的“扫描 → 修复 → 测试 → 复扫 → Draft PR” 闭环。上面动图里那次运行，量化如下： | NodeGoat 改编案例真实运行 | 修复前 | Dvalin 修复后 | |---|---:|---:| | 安全健康分（分诊启发式） | 22 / 100 · F | 100 / 100 · A | | 发现项 | 10 条（2 个引擎、3 条规则命中 `eval`） | 0 条 | | 测试 | 2 条通过 | 3 条通过，新增注入回归测试 | | 扫描器 | 4 / 4 完成 | 4 / 4 完成 | 扫描与加固的**控制平面**采用开源组件： - [Semgrep CE](https://github.com/semgrep/semgrep) 与社区规则：语义 SAST。 - [Trivy](https://github.com/aquasecurity/trivy)：文件系统漏洞、Secrets 与错误配置。 - [OSV-Scanner](https://github.com/google/osv-scanner) 与开放的 [OSV 数据库](https://osv.dev/)：依赖漏洞。 - DvalinCode 自身 MIT 许可的内置规则、修复编排、测试/复扫门禁，以及用于接入 其他扫描器的 [SARIF 2.1](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html)。 扫描器负责发现和排序证据；配置的模型提出源码修改；DvalinCode 约束执行范围、 记录 diff、运行项目测试、重新扫描变更树，并要求用户显式发布 PR。它不会自动合并， 也不会把一次干净扫描宣称为“没有漏洞”。若修复建议也必须完全本地、开放，可通过 Ollama 选择开放权重模型；托管模型的许可取决于相应 provider。 事后仍可证明 agent 做过什么： ```sh dvalincode report verify # 重新推导上次运行审计日志的哈希链 ``` --- ## 🧩 集成支持 AI 协助写出来的代码，在合并之前会经过四道手：写它的 agent、开发者读它的编辑器、 拦它的 Pull Request，以及最后必须相信这个结论的评审者。一个只存在于其中一处的安全 结论不是门禁，只是一条下一环节可以无视的建议。 Dvalin 在这四处背后是同一个 MCP server、同一次确定性扫描 —— 所以答案不会因为谁在问 而改变。 | 开发环节 | 你在哪儿 | Dvalin 怎么接进去 | 状态 | |---|---|---|---| | **写代码** | Claude Code | [双兼容插件](integrations/dvalin-security/) · `claude mcp add` · `mcp-install claude-code` | ✅ 会话已验证 | | | Codex | [双兼容插件](integrations/dvalin-security/) · `codex mcp add` · [SARIF 互操作](integrations/codex-security/) | ✅ 会话已验证 · 见下方截图 | | | Cursor | `dvalincode mcp-install cursor` | ⚙️ 配置已验证 | | | Windsurf · Zed | 通过它们自己的设置接 stdio MCP | ⚙️ 已文档化，未验证 | | | 任意 MCP 客户端 | registry `io.github.arthurpanhku/dvalincode` | ⚙️ 已发布 | | **回头读代码** | VS Code | `mcp-install vscode` · [扩展](editors/vscode/)：Problems、覆盖度与门禁状态 | ✅ 编辑器内已验证 | | **卡住合并** | GitHub Actions | [Marketplace action](https://github.com/marketplace/actions/dvalin-security-scan) —— finding 落在 diff 上，fix record 在 runner 上重新推导 | ✅ 本仓库自己的 CI 就在跑 | | | 任意 CI | `dvalin scan . --fail-on high`，输出 SARIF | ✅ 退出码就是契约 | | **相信这个结论** | 任何人，离线 | `dvalin verify-fix record.json` | ✅ 不需要 workspace、网络或任何 Dvalin 状态 | **✅** 表示真实客户端被端到端驱动过，并且观察到了工具调用。 **⚙️** 表示配置能生成、格式经过测试，但还没有抓到会话记录。这个区别这里不含糊过去 —— 一个能被加载的配置文件，不能证明工具真的被调用过。 ### 每一条结论的依据 | 客户端 | 版本 | 检查时间 | 怎么检查的 | |---|---|---|---| | Claude Code | CLI 2.1.260 | 2026-09-04 | server 连上，只放行 `dvalin_scan` 一个工具并被真实调用，返回 3 条 finding —— 见下方截图 | | Claude Code | CLI 2.1.251 | 2026-08-31 | 每周的 [`harness-interop`](.github/workflows/harness-interop.yml)：对构建产物做真实握手，这一步不需要任何凭据 | | Codex | CLI 0.153.2 | 2026-09-18 | 在临时只读沙箱中真实调用 `dvalin_scan`；完成的 MCP 事件以 JSONL 记录，返回 1 条 `dvalin/eval` finding —— 见下方截图 | | Codex | CLI 0.151.0 | 2026-08-31 | 每周的 `harness-interop`：server 配置被接受并按 stdio 存下。**这不是握手** —— 在设置 `CODEX_API_KEY` 之前，调用工具那一步一直是 skipped | | VS Code | 1.134.0 · 扩展 0.18.0 | 2026-09-03 | 干净 profile 里安装打包好的 VSIX；finding、门禁和覆盖度都出现在编辑器里 —— 见下方截图 | | Cursor | — | 2026-09-04 | `mcp-install cursor` 会把 `.cursor/mcp.json` 写成 `mcpServers` 结构；但还没有抓到会话记录 | 那个每周任务之所以存在，是因为这段话的早期版本手写了两个 CLI 版本号，两个都在几周内 过期，而没有任何东西提醒过。现在它每周对着这些工具的当周版本重跑一次 —— 上面这些日期 要么自己往前走，要么就公开地停在那里。 ### 同一条 finding，在不同的地方 **Claude Code** —— 只放行了一个只读工具，以及那次 MCP 调用本身： ![Claude Code 会话调用 Dvalin MCP server](docs/screenshots/10-claude-code-session.png) **Codex** —— 一次只读 MCP 调用，并单独展示完成态的 JSONL 工具事件： ![Codex 会话调用 Dvalin MCP server](docs/screenshots/11-codex-session.png) **VS Code** —— 同一套扫描器契约，变成波浪线和状态栏： ![VS Code 里的 Dvalin finding 与覆盖度状态](docs/screenshots/09-vscode-dvalin-integration.png) --- ## 🏛️ 而且它过得了安全评审 当依赖这套工具的不止你一个人时，上面那条命令才是真正要紧的东西。DvalinCode 是一个 完整的编码代理 —— 终端、Web GUI、桌面应用 —— 但它的设计前提是：**由组织、而不是 开发者本人**来划定它能做什么。策略文件约束模式、命令、路径、工具和模型；每次运行 都以哈希链写入防篡改审计日志；没有被出网守卫放行的东西不会到达任何 provider。 仓库级策略只能**收紧**机器级策略，永远不能放宽。 如果你正是那个需要审批这类工具的人，请从 [APPROVABILITY-PLAN.md](docs/APPROVABILITY-PLAN.md) 和每个版本随包发布的 [Evidence Pack](docs/EVIDENCE-PACK.md) 开始看。 ---
🏠 Home统一容纳只读 Ask 与逐操作审批的 Collaborate，切换意图时不离开当前项目和对话。
⚡ Code专注自主编码，支持 Ask / Plan / Auto / Bypass 权限级别；旧 Security 与 Routines 已从 Code 移除。
🛡️ Dvalin专用白盒安全工程工作区：编排内置扫描器、Semgrep CE、Trivy、OSV-Scanner，分诊并修复发现项，运行测试和复扫，最后显式发布可审查的 Draft PR。Dvalin 指南 →
🏦 高合规团队为金融、医疗、安全敏感 SaaS、内部平台团队设计：AI 编码不仅要方便开发者，还要满足策略约束、审计、数据最小化和供应链审查。
🛡️ 安全修复闭环运行本地安全扫描，或导入 CodeQL、GitHub Code Scanning、Semgrep 及兼容扫描器的 SARIF；随后创建隔离 remediation worktree，把发现项转成带源码上下文和 PR 就绪报告的聚焦修复任务。流程 →
📚 Skills上传、下载和查看本地 skill bundle。DvalinCode 内置 secure-code-scan 与 secure-code-remediation skills，并提供列出 skill、读取 skill 说明、扫描、列出 case、准备 remediation worktree 的 agent tools。格式 →
🛡️ 审计日志每次运行都生成防篡改、哈希链式的 JSONL 日志 —— 每次文件读写、每条命令、每次审批都被记录。Run Report 将其渲染为 Markdown；dvalincode report verify 可验证链条完好。威胁模型 →
🔒 组织级策略 & trust由公司、而非开发者来约束 Agent。一个 dvalin.policy.json 限定模式、shell 命令、文件路径、工具与模型；仓库级策略只能让机器级策略更严、永不放宽。每次运行都记录所遵循策略的哈希。dvalincode trust 直接打印本机的实时安全态势 —— 生效策略 + 哈希、审计状态、运行时 —— 让审批人自行核验。策略参考 → · 可审批性方案 →
🏛️ 治理证据仓库维护 OpenSSF Scorecard、CodeQL、Dependabot、固定 SHA 的 GitHub Actions、CODEOWNERS，以及 ISO/IEC 42001 AIMS 对齐文档，作为可审查的项目治理证据；每个 release 还附带一份由该二进制给自己生成的 Evidence Pack。Scorecard 映射 → · ISO 42001 对齐 → · 发布证据 →
📐 开放规范PCP-1 —— 把模型提供方边界的约束（出网收敛、凭据收敛、审计、策略绑定）写成与厂商无关、带测试步骤的开放规范，任何 agent 运行时都可以拿它跑自己的 adapter 并公开结果。它不是 DvalinCode 的一个测试文件，而是别人同样可以用来衡量我们的清单。Provider Conformance Profile →
🖥️ 一流的 GUI现代化 Web UI，包含代码语法高亮、@ 文件引用、/ 斜杠命令、Git 分支显示、实时 Token 与费用统计、多 LLM Profile，以及暗色 / 浅色 / 跟随系统的主题切换。
🖥️ 终端或 Web，同一个二进制直接运行进入交互式终端代理，支持流式输出、行内审批和红绿 diff；或 dvalincode serve 启动 Web GUI 供浏览器/远程使用。两个前端共用同一套 agent 内核。
🖥️ 原生桌面应用DvalinCode.app —— 真正的 Dock 应用（系统原生 webview，非 Electron），驱动同一套引擎。macOS 上一行安装命令会自动装进 /Applications，从启动台直接打开。
🪶 零依赖二进制每平台单文件可执行程序 ~25MB。无需 Node、Python、Docker。
🔐 本地优先Session、配置、Profile、审计日志均保存在 ~/.dvalincode/。.dvalincodeignore 阻止 Agent 访问敏感文件。仓库根目录的 AGENTS.md 作为项目级持久指令自动加载。
💾 可导出、可迁移把所有本地数据（记忆、Session、配置、审计）导出为一个文件，在另一台机器导入 —— 整套环境随身带走。任意对话都能下载为干净的 Markdown 记录。
--- ## 🎯 核心目标 > **让每一个写代码的人类或 Agent，都通过同一套独立安全门禁。** DvalinCode 的定位是 **Agent 可调用的安全运行时**，而不是又一个通用 Coding Agent 榜单参赛者。核心产品是扫描证据、策略、基线、确定性验证，以及能被人类、外部 Agent 和 CI 共同调用的便携接口。自带 Coding Agent 只需保持可靠完成聚焦修复和测试的能力； 模型的文字声明永远不能决定安全 gate 是否通过。 - **模型自由** —— 任何 OpenAI 兼容端点都是一等公民，包括本地模型。你的工作流不应被任何一家厂商的定价、限流或质量波动绑架。 - **默认安全** —— 三档审批 + diff 预审、撤销栈、沙箱化 shell 执行。一个敢放心开全自动的 Agent。 - **小到可审计** —— 单个 ~25MB 二进制、个位数运行时依赖、一个周末就能读完的代码库。信任来自可检查，而非口头承诺。自 v0.5 起，**每一次运行同样可审计**：一份记录所有动作、可事后验证的防篡改哈希链日志。 - **开放到可嵌入** —— Agent 核心通过干净的 REST + WebSocket API 暴露，可直接接入你自己的产品、CI 或内部工具。 - **任何公司都能批准** —— 治理是内建的，而非事后附加：组织级策略约束影响面（**可控**），`dvalincode trust` 让安全态势可自证（**透明**），哈希链日志证明每次运行做了什么（**可审计**）。这三者正是安全评审说"yes"所需要的 —— 也是上云、闭源、日志可改的 Agent 在结构上很难完整提供的。[可审批性方案 →](docs/APPROVABILITY-PLAN.md) 自带的 **Web GUI 是这个运行时的参考实现与展示窗** —— 它是这套公开 API 的第一个消费者，演示运行时的全部能力。 --- ## ✅ 为什么团队选择 DvalinCode DvalinCode 的差异化在于 **可审批性**。它面向那些必须先通过安全、合规与数据治理评审，才能让 AI 编码接触生产仓库的团队。 - **闭环安全修复** —— 本地扫描或导入 CodeQL、GitHub Code Scanning、Semgrep 及兼容扫描器的 SARIF；将发现项持久化为本地 remediation cases；创建隔离 `dvalin/remediate/...` worktree；再生成带源码上下文和验证说明的聚焦修复 prompt。 - **Skills 作为受治理的操作流程** —— 上传、下载和查看本地 skill bundle。 内置安全扫描与修复 skills 会告诉 agent 该调用哪些工具，并让流程能跨机器迁移。 - **模型自由但策略不漂移** —— 可使用 DeepSeek、OpenAI、Claude via OpenRouter、 Groq、Ollama 或任何 OpenAI 兼容端点，同时保持工具权限、审计和 workspace policy 一致。 - **安全证据，而不只是安全口号** —— OpenSSF Scorecard 支持、CodeQL、Dependabot、 固定 SHA 的 Actions、CODEOWNERS、ISO/IEC 42001 对齐文档、AI 变更影响记录、 哈希链运行日志，都是项目的一部分。 - **默认本地优先** —— Session、配置、Profile、记忆和审计日志保存在 `~/.dvalincode/`；`.dvalincodeignore` 和策略控制限制 agent 能读、写、执行什么。 --- ## 🛡️ 安全与治理

ISO/IEC 42001 AIMS aligned Compliance evidence pack DevSecOps native

DvalinCode 维护项目级治理证据，便于开源用户和企业安全评审。这是面向 高合规团队的核心差异化：AI 编码工具进入生产仓库前，必须先能过安全审批。 - **威胁模型** —— 覆盖 agentic coding runtime 的完整攻击面（恶意 `AGENTS.md`、 被投毒的 MCP server、prompt-injection 提权、egress、审计篡改、供应链、 沙箱逃逸），并将每个风险映射到防护控制和诚实的剩余缺口。 [威胁模型 →](docs/THREAT-MODEL.md) - **OpenSSF Scorecard 支持** —— 定时 Scorecard workflow、SARIF 上传、 CodeQL、Dependabot、CODEOWNERS、最小权限 workflow permissions，以及固定 SHA 的 GitHub Actions。[控制映射 →](docs/security/OPENSSF-SCORECARD.md) - **ISO/IEC 42001 对齐** —— AI 管理体系范围、AI policy、角色映射、风险登记、 AI 变更分级、必留记录和审查节奏。[AIMS 对齐 →](docs/governance/ISO-42001-AIMS.md) - **AI 变更影响评估** —— 面向模型/provider 行为、prompt、权限、工具、审计日志 或发布安全变更的可复用模板。[模板 →](docs/governance/AI-CHANGE-IMPACT-ASSESSMENT.md) - **高合规使用姿态** —— 本地优先的数据处理、策略约束的自主性、最小化审计记录， 以及面向金融、医疗、安全敏感 SaaS 和企业内部使用的发布供应链证据。 - **安全修复闭环** —— 内置本地扫描与 SARIF 导入，可把 CodeQL、GitHub Code Scanning、Semgrep 及兼容扫描器的发现项转成本地 remediation cases 和隔离 worktree 修复任务，并带源码上下文、验证说明和报告说明。 [流程 →](docs/SECURE-REMEDIATION.md) 这些文档是实现证据和运行流程，不代表项目已经获得第三方 ISO 认证。 --- ## ⭐ v0.14.0 新功能 —— Dvalin 安全工程 - **Home 合并 Chat 与 Cowork** —— Home 统一提供只读 Ask 与审批式 Collaborate， 保持同一个项目和对话上下文。 - **Code 回归专注开发** —— 旧 Security 与 Routines 面板已移除，侧栏只服务项目与 自主实现工作流。 - **Dvalin 成为一等工作区** —— 编排内置扫描器、Semgrep CE、Trivy、OSV-Scanner； 导入 SARIF；评分并分诊发现项；持久化 remediation case；创建隔离修复 worktree。 - **从证据到 Draft PR 的闭环** —— 选中的发现项可启动带源码证据的 Agent 修复， 运行测试、类型检查、构建与复扫，审查 diff 后再显式发布 Draft PR，永不自动合并。 - **Agent loop 更早收敛、成本更低** —— 编辑前调查、停滞检测、统一工具输出上限、 append-only prompt 缓存，以及 provider cache hit/miss 统计均已落地。 --- ## ⭐ v0.12.3 新功能 —— 长时间 Code 模式更可靠 - **长编程任务持续执行** —— Code 模式现在会在工具循环执行过程中动态压缩上下文， Token 估算覆盖完整 provider 请求，并将默认迭代检查点从 10 提升到 40。 - **中断后可以续接** —— 回合被中断或连接关闭时，会保存已经完成的工具状态；后续发送 `continue` 即可从工作区的真实进度继续。 - **Agent 活动清晰而安静** —— 运行中的 session 会在侧栏显示 loading 状态；每次回复 显示工作耗时，点击即可查看 Action 时间线，原始 Tool Call 默认保持折叠。 - **Code 模式支持 GitHub 工作流** —— 具备网络感知的 `git` 与 GitHub CLI（`gh`） 操作现在可通过受控 shell 审批路径执行 pull、push、创建 PR，以及 Actions / 仓库命令。 - **更安全的发布流程** —— package 与 CLI 版本保持同步，`prepublishOnly` 会在发布前运行 构建、类型检查和完整测试。 - **简单需求保持简单** —— Action 预算现在对整轮生效，不再每次模型迭代重置；Code 模式 会优先选择最短直接路径，并在针对性验证通过后停止。 --- ## ⭐ v0.12.2 新功能 —— 🖥️ 桌面应用里程碑：开箱即用 - **🖥️ 原生桌面应用在 macOS 上开箱即用** —— `DvalinCode.app` 现在能真正打开 一个原生 Dock 窗口（WKWebView，非 Electron），驱动内嵌引擎。修复了此前所有 桌面构建都存在的两个线程问题：阻塞式 webview 循环不再饿死内嵌服务器（空白 窗口），webview 按 macOS 要求跑在主线程（否则窗口根本不出现）—— 服务器改由 同一二进制的子进程承载。 - **📦 一行安装命令即装桌面应用** —— macOS 上 `curl … install.sh | bash` 现在会把带 DvalinCode 图标的 `DvalinCode.app` 装进 `/Applications`， CLI 装完即可从启动台直接打开桌面窗口。`DVALINCODE_NO_APP=1` 可跳过， `DVALINCODE_GUI_VERSION` 可固定版本。 - **✅ macOS 桌面版不再是"实验性"** —— 窗口与内嵌服务器均已验证可用； Windows 与 Linux 桌面构建为交叉编译，仍属预览。
v0.9.0 —— 🛡️ 安全修复闭环 · Skills · CodeQL 加固 - **🛡️ 安全修复闭环** —— 支持运行内置本地扫描，或导入 CodeQL、GitHub Code Scanning、Semgrep 及兼容扫描器的 SARIF；发现项会转成本地修复 case， 并带有源码上下文、验证说明和隔离 worktree 修复任务。 - **📚 Skills** —— 支持上传、下载、查看和复用本地 skill bundle。DvalinCode 内置 secure-code-scan 与 secure-code-remediation skills，并提供 agent tools 用于列出 skill、读取说明、扫描、列出修复 case、准备修复 worktree。 - **🔐 CodeQL 路径加固** —— workspace、remediation、skill 相关的用户可控路径 现在都经过显式 root-containment 校验，并新增路径遍历与 skill 导入边界回归测试。 - **🎨 应用图标** —— Web bundle 与桌面构建输入现在包含暗色和亮色主题应用图标。
v0.8.0 —— 🔒 治理：可控 · 透明 · 可审计 - **🔒 组织级策略** —— 一个 `dvalin.policy.json` 让*公司*、而非开发者来约束 Agent：允许哪些模式、shell 命令、文件路径、工具与模型。两层(机器级 `~/.dvalincode/policy.json` + 仓库级)按**收窄**解析 —— 仓库策略只能让机器策略更严、永不放宽。没有策略文件时,行为与之前完全一致。在唯一关卡强制执行;每次拦截都是行内 `⛔ Blocked by policy` 加一条 `policy_violation` 审计事件。[策略参考 →](docs/POLICY-REFERENCE.md) - **🔎 `dvalincode trust`** —— 一条命令打印本机的实时安全态势:生效策略 + 来源哈希、审计状态、运行时、依赖 —— 让审批人直接核验 Agent 能做什么、不能做什么,而不是听口头承诺。`--json` 供工具消费。 - **🧾 策略感知的审计** —— 每次运行都在 `run_start` 记录所遵循策略的哈希(以及哪些文件参与),让防篡改日志能证明*当时生效的是哪套规则*。 - **📐 可审批性方案** —— 这条主线记录在 [docs/APPROVABILITY-PLAN.md](docs/APPROVABILITY-PLAN.md):让 DvalinCode 能被任何公司轻松批准 —— 可控、透明、可审计。
v0.7.0 —— 🧪 桌面应用（beta） - **🧠 记忆与全量数据导出 / 导入** —— 升级后的本地记忆机制,连同所有 Session、配置、Profile、审计日志,现在都能打包成一个文件并在另一台机器上还原。一步迁移整套环境:`dvalincode export` / `dvalincode import`,或 GUI 设置面板里的 **Export / Import** 按钮。 - **📝 任意 AI 交互都能下载为 Markdown** —— 每段对话都能存成干净的 Markdown 记录(用户消息、助手回复、工具调用 + 结果、决策,全部内联)。用侧栏里每个 Session 的下载图标、`dvalincode session md `,或 `GET /api/sessions/:id/markdown`。 - **🖥️ 原生桌面应用** —— 一个真正的应用窗口（不是浏览器标签页），跑在同一套内核之上：macOS 的 `DvalinCode.app`，外加 Windows / Linux 版本。基于 [webview-bun](https://github.com/tr1ckydev/webview-bun)，使用系统原生 webview（WKWebView / WebView2 / WebKitGTK）—— 不用 Electron，仍是小巧自包含的二进制。 - **🧩 第三个前端，同一内核** —— 桌面应用、终端 UI、Web GUI 都驱动同一套共享回合执行器。现有的 `dvalincode` 二进制现在纯粹定位为 **CLI**（终端 + `serve`）。 - **状态：** 桌面二进制目前**实验性 / 未验证** —— 请从最新的 **pre-release** 下载，并反馈窗口在你系统上的表现。
v0.6.0 —— 终端代理 · serve · 共享回合执行器 - **🖥️ 终端代理** —— 直接运行 `dvalincode` 进入交互式终端编码代理（Claude Code 风格）：流式输出、行内 `[y/N]` 写入审批 + 红绿 diff、`/mode` · `/clear` · `/git` · `/plan` · `/compact` · `/undo` · `/help`、Ctrl-C 中断，以及首次启动的引导式 Provider 配置。默认只读 **Chat**，可随时切换。 - **🌐 `dvalincode serve`** —— Web GUI 现在收归于一个命令，因此*同一个*二进制即可无头部署在服务器上：`dvalincode serve --host 0.0.0.0 --no-open`。 - **🧩 一套内核，两个前端** —— 终端 UI 与 Web GUI 共同驱动一个传输无关的共享回合执行器（`src/agent/session.ts`），始终保持功能对齐。
v0.5.0 —— 安全级审计日志 · Run Report · 主题切换 - **🛡️ 安全级审计日志** —— 每次 Cowork/Code 运行都向 `~/.dvalincode/audit/` 写入防篡改、哈希链式的 JSONL 日志（`run_start`、每次 `tool_call` / `file_*` / `shell_exec` / `approval`、`run_end`）。哈希链让任何事后修改都可被检测。本地编码 Agent 中尚无可验证的行为日志。[格式与威胁模型 →](docs/AUDIT-TRAIL.md) - **📋 Run Report + `dvalincode report` 命令** —— 每次运行的 Markdown 摘要（读取/变更的文件、执行的命令、决策、测试结果），在 GUI 中以可折叠卡片呈现，也可在命令行查看： ```sh dvalincode report --last # 渲染最近一次运行 dvalincode report --format json dvalincode report verify # ✓ 链条完好 / ✗ 在第 N 条断裂 ``` - **🎨 主题切换** —— 在设置中选择 **暗色 / 浅色 / 跟随系统**。`跟随系统` 会实时跟随操作系统主题；选择会持久保存。
v0.4.0 —— /compact · dvalin.json 团队 playbook · 自包含二进制 - **`/compact`** —— 基于 LLM 的上下文压缩：把对话历史替换为五段式结构化摘要（目标 / 已完成 / 决策 / 当前状态 / 待办）。聊天线程中的分隔条会显示 Token 缩减量（如 `8,412 → 1,203 tokens −85%`）。 - **`dvalin.json` 团队 playbook** —— 把一组共享的自动化提示提交到仓库。侧栏自动加载，让队友无需任何手动配置即可运行相同的一键 Routine。导出按钮一键把你的个人 Routine 转换为 `dvalin.json`。 - **自包含二进制** —— 每平台单个 ~25 MB 可执行程序；无需 Node、Python、Docker。启动后自动打开浏览器。用 `bun --compile` 构建，Web UI 与服务端二进制打包在一起。
v0.3.0 —— 模式感知侧边栏 · 一行安装脚本 · 多 Profile LLM 配置 - **模式感知的侧边栏** —— Chat 显示快速提示 **Templates**，Cowork 显示 **Projects** 文件夹树，Code 显示自定义 **Routines**（一键命令如 "Run tests" / "Git status" / "Type check"）。可在侧栏中添加自己的 Routine，保存在 `localStorage`。 - **一行安装脚本** —— `curl … | bash` 自动检测系统和架构，将二进制放入 `~/.dvalincode/`，自动配置 `PATH`，无需任何包管理器依赖。 - **多 Profile LLM 配置** —— 保存命名的 (provider, model, API key) 组合，侧栏一键切换；顶栏实时显示当前 session 费用，随时横向对比不同 Provider。
--- ## 📸 预览 **真实漏洞代码的 Dvalin 扫描——安全健康分 22/100 · F，以及引擎实际报出的 10 条发现，逐行定位：**

Dvalin 安全健康分显示 22/100 F、4 条高危与 6 条中危，Findings 列表把每处 eval 定位到 NodeGoat 改编路由的具体行

**验证后的结果——真实模型驱动的 Verify 回合检查修复、运行回归测试和 4 个开源引擎， 随后服务端确定性复扫显示完整覆盖、gate 通过、0 条发现、100/100 · A：**

Dvalin 本地真实模型 Verify 回合及其确定性复扫：100/100 A、四引擎完整覆盖、gate 通过、0 条发现

### 当前 Mac mini 冒烟测试 2026-09-18，在 Apple 芯片 Mac mini（macOS 27.0）上构建并运行了提交 `d4bf02b` 的本地应用。一次性测试项目未配置 API Key 或模型，只选择无需网络的 内置扫描器。Dvalin 在 `quantity.js:3` 定位到刻意植入的 `eval`，报告 **1 条高危、88/100 · B**，记录所选引擎 **1/1** 完整覆盖，并正确阻断 `high` 安全门禁：

Mac mini 上的 Dvalin 本地扫描：1 条 eval 高危发现、88/100 B、内置扫描器完整覆盖，high 门禁被阻断

把 `eval` 换成受约束的整数解析器，并补充可执行输入回归测试后，**3/3** 测试 全部通过；所选引擎复扫得到 **0 条发现、100/100 · A**、覆盖完整、门禁通过：

Mac mini 上的 Dvalin 本地复扫：0 条发现、100/100 A、内置扫描器完整覆盖，high 门禁通过

同一个 CLI 工作流以退出码 0 运行 `npm run test`，生成 `dvalin-fix-record/v2`，随后 `dvalin verify-fix` 在离线条件下重新推导并返回 `ok: true`。干净复扫截图拍摄时尚未导入记录，因此仍显示 **Offline fix record: Not attached**。Web 工作区现在可以导入这份便携 JSON，在离线条件下重新推导哈希与 判定，并展示执行者、检查命令和退出码。这张干净复扫只说明所选引擎没有发现问题， 不代表代码被证明绝对安全。 **Home → Code → Dvalin——当前三个工作区：**

DvalinCode 在 Home、Code 与 Dvalin 之间切换

以上扫描画面是文档所述 NodeGoat 改编案例上一次真实运行的未修图截图：先运行扫描器， 再由模型修复源码，然后运行项目测试并复扫。没有任何摆拍；100/A 只代表所配置的引擎 未发现问题，不代表代码已被证明安全。 --- ## 🆚 什么时候选择 DvalinCode | 如果你需要… | DvalinCode 的解法 | |---|---| | **安全团队真正批得下来的 Agent** | 策略约束工具权限、明确审批模式、`dvalincode trust`、审计日志、OpenSSF 证据和 ISO/IEC 42001 对齐文档。 | | **在高合规仓库里使用 AI 编码** —— 金融、医疗、企业数据、客户保密代码 | 本地优先运行时、自带模型、`.dvalincodeignore`、受控 egress、最小化审计记录。 | | **比通用自主编码 Agent 更安全的选择** | 产品主线是可控 / 透明 / 可审计，而不仅仅是“模型可以改文件”。 | | **偏 IDE 的 AI 工作流** | 单二进制 (~25 MB)，无需任何 IDE。macOS shell 调用默认运行在 `sandbox-exec` 沙箱中——拒绝网络访问，写入范围限制在 `cwd`。 | | **偏终端的 AI 工作流** | CLI 启动后自动打开现代 Web UI，支持代码高亮和红绿 Diff 逐文件审批。一行安装命令，无需其他依赖。 | | **仅云端的 AI 工作流** | 所有 OpenAI Compatible 端点均为一等公民。用 Ollama 跑 Qwen2.5-Coder：无需 API Key，无需联网，零 Token 费用。 | | **单机 AI 配置** | `AGENTS.md` 提交到仓库，随 `git clone` 把 AI 上下文同步给所有人。`dvalin.json` 以同样方式共享团队自动化命令集 —— 从侧栏导出、提交、完成。 | --- ## 🚀 一行安装 ### Homebrew（macOS / Linux） ```sh brew tap arthurpanhku/dvalincode https://github.com/arthurpanhku/dvalincode brew install arthurpanhku/dvalincode/dvalincode ``` 安装的是和一行命令同一份、按校验和固定的发布归档，之后 `brew upgrade` 即可保持更新。 Homebrew 不会给文件打上 macOS 隔离属性，所以这条路径不受 Gatekeeper 干预。 ### macOS / Linux（一行命令） ```sh curl -fsSL https://raw.githubusercontent.com/arthurpanhku/dvalincode/main/scripts/install.sh | bash ``` 自动检测系统和架构、下载对应二进制、安装到 `~/.dvalincode/`、添加到 `PATH`。macOS 上还会把原生桌面应用 **DvalinCode.app** 装进 `/Applications`（可用 `DVALINCODE_NO_APP=1` 跳过），装完即可直接从启动台打开图形界面。重新加载 shell 后： ```sh source ~/.zshrc # 或 ~/.bashrc dvalincode # 交互式终端代理 dvalincode dvalin . # 白盒安全扫描 dvalincode dvalin . --fix --verify --draft-pr # 隔离修复、验证并创建草稿 PR dvalincode serve # 启动 Web GUI 并打开浏览器 dvalincode serve --host 0.0.0.0 --no-open # 部署到服务器，供远程/浏览器访问 echo "检查 src 并总结" | dvalincode run - --output-format stream-json dvalincode mcp-serve # 供外部 Agent 调用的任务级 stdio MCP 服务 ``` 无头 `run` 和 `mcp-serve` 与交互客户端共用同一个策略与审计关卡。cron、CI 和外部 Agent 示例见[无人值守配方](docs/RECIPES-UNATTENDED.md)。 扫描过、或者产出过 fix record 的运行，还会在结果旁边带上一份 `verification` 信封 —— `json`、`stream-json` 以及 MCP `dvalin_run_task` 的返回里都有。`coverageStatus` 取的 是这次运行**有证据支持的最弱**覆盖度，因此一次完整扫描不能替一次部分扫描背书；产出 的记录按路径列出，可离线复验。CI 门禁可以直接读它： ```sh jq -e '.verification.coverageStatus == "complete"' run.json || exit 1 ``` 这和 PR 评论用的是同一条规则，只是用在没有人盯着的那个界面上。 [Harness 模式 →](docs/HARNESS-MODE.md) ### Windows 从 [Releases](https://github.com/arthurpanhku/dvalincode/releases/latest) 下载 `dvalincode-v*-windows-x64.zip`，解压后双击 `start.bat`。 ### 手动下载 从 [Releases 页面](https://github.com/arthurpanhku/dvalincode/releases/latest) 获取对应平台的压缩包： | 平台 | 文件 | |---|---| | macOS Apple Silicon (M1/M2/M3) | `dvalincode-v*-macos-arm64.tar.gz` | | macOS Intel | `dvalincode-v*-macos-x64.tar.gz` | | Windows x64 | `dvalincode-v*-windows-x64.zip` | | Linux ARM64 | `dvalincode-v*-linux-arm64.tar.gz` | | Linux x64 | `dvalincode-v*-linux-x64.tar.gz` | 每个 release 都附带 `SHA256SUMS.txt` 用于校验。 每个 release 还附带 **`dvalincode-v*-evidence.json`** —— 由发布出去的那个二进制在构建机上给自己生成的 Evidence Pack：两次真实的受治理运行（一次放行、一次被策略拦截）及其哈希链。安装之前就可以自己核验本页的说法： ```sh dvalincode evidence verify dvalincode-v0.14.0-evidence.json # 离线，只读这一个文件 ``` 该文件的校验和写在 `SHA256SUMS.txt` 里，而 `SHA256SUMS.txt` 正是 release 构建溯源签名（build provenance attestation）的签署对象。[生成方式 →](docs/RELEASE-EVIDENCE.md) > **macOS Gatekeeper：** 二进制未签名。首次运行可执行 `xattr -dr com.apple.quarantine ~/.dvalincode`，或在 Finder 中右键 → 打开一次。 ### 保持更新 DvalinCode 可自我更新，无需重新运行安装脚本： ```sh dvalincode update --check # 检查是否有新版本（只读） dvalincode update # 下载、校验并安装最新版本 ``` 它会在 GitHub 上找到最新 release；对二进制安装，会下载对应平台的归档，**在替换任何文件之前先用 release 的 `SHA256SUMS.txt` 校验**，然后就地替换 `~/.dvalincode/`。npm 安装通过 `npm i -g` 更新，源码检出则提示 `git pull`。可用 `-y` 跳过确认、`--prerelease` 跟踪预发布、`--json` 用于脚本。 --- ## 🎬 首次配置 **终端（默认）：** 运行 `dvalincode`。首次启动会引导你完成一次性的 Provider 配置（选择 Provider、粘贴 API Key、选择模型），保存到 `~/.dvalincode/config.json`。随后即进入对话提示符 —— 直接输入即可对话，`/mode` 切换 Home / Code / Dvalin，`/help` 查看命令。 **Web GUI：** 运行 `dvalincode serve`： 1. 服务在 `http://localhost:3000` 启动，浏览器自动打开。 2. 点击侧边栏底部的 **LLM Configuration**。 3. 选择 Provider、粘贴 API Key、选择模型、保存。 4. 可选：将当前配置保存为命名 Profile（如 `fast`、`cheap`、`local-ollama`），日后一键切换。 两种方式共享 `~/.dvalincode/` 下的同一份配置与 Session。 --- ## ✨ 功能列表 | 类别 | 功能 | 说明 | |---|---|---| | **模式** | Home / Code / Dvalin | Home 包含只读 Ask 与审批式 Collaborate；Code 专注开发；Dvalin 是扫描到修复的安全工作区 | | **Code 权限** | Ask Permissions / Plan Mode / Auto Mode / Bypass permissions | 已验证行为：Ask 在写入/命令前请求批准，Plan 只读且不写文件，Auto 自动执行操作，Bypass 不再弹出确认 | | **工作区** | 打开文件夹 / 导入 Git / 添加 worktree | Home、Code 与 Dvalin 可使用本地文件夹、Git 项目和隔离 remediation worktree | | **治理** | OpenSSF Scorecard / ISO 42001 AIMS 对齐 | Scorecard、CodeQL、Dependabot、固定 SHA 的 Actions、AI 影响评估、风险登记和审查节奏记录在 `docs/security/` 与 `docs/governance/` | | **安全修复** | 内置 + Semgrep CE + Trivy + OSV-Scanner / SARIF / 测试 / Draft PR | Dvalin 检测已安装引擎、统一 SARIF、风险评分、驱动证据化修复、验证变更，并只在用户显式操作后发布 Draft PR | | **Skills** | 上传 / 下载 / 内置安全 skills | Skills 保存在 `~/.dvalincode/skills`；内置 skills 用专门的 agent tools 引导安全扫描与修复。[格式 →](docs/SKILLS.md) | | **输入框** | `@` 文件引用 | 输入 `@` 触发模糊文件搜索，选中文件自动插入到 prompt | | | `/` 斜杠命令 | `/clear` `/compact` `/git` `/plan` `/undo` `/help` | | | 多行输入 + 中断 | Shift+Enter 换行，Stop 按钮中断生成 | | **工具 UI** | 行内 diff | `edit_file` 与 `write_file` 结果以红绿统一 diff 呈现，默认折叠 | | | 审批对话框含 diff | Home → Collaborate 下，文件变更在执行前显示 diff | | | 实时工具计数 + Token + 费用 | 顶栏实时显示当前 session 累计数据 | | **Agent** | LLM 上下文压缩 | `/compact` 将历史压缩为 目标/已完成/决策/待办 结构化摘要 | | | 持久化 Undo 栈 | `/undo [N]` 撤销最近 N 个工具调用 | | | Run Report | 每次运行的 Markdown 摘要（文件、命令、决策、测试结果）—— GUI 卡片 + `dvalincode report` | | | Git 感知 | 顶栏显示分支名；`git_status` 工具；Git 上下文自动注入 prompt | | | `AGENTS.md` 项目记忆 | 每个仓库的持久指令，每轮对话自动加载 | | **安全** | 防篡改审计日志 | 每次运行在 `~/.dvalincode/audit/` 生成哈希链 JSONL；`dvalincode report verify` 可检测修改 | | | macOS Shell 沙箱 | `sandbox-exec` 拒绝网络；写入仅限 cwd 与 `/tmp` | | | `.dvalincodeignore` | 类 gitignore 排除；阻止 `read_file` / `list_files` / `search_text` | | | 逐操作审批 | Home → Collaborate 下每次写入/删除/shell 都需用户批准 | | **外观** | 主题切换 | 暗色 / 浅色 / 跟随系统，持久保存；`跟随系统` 实时跟随 OS | | **Providers** | OpenAI 兼容端点 | DeepSeek · OpenAI · Groq · OpenRouter · Ollama · 自定义 | | | 多 Profile 配置 | 保存并切换多组 (provider, model, API key) 命名配置 | | **Session** | 自动保存与恢复 | 所有 session 以 JSON 持久化到 `~/.dvalincode/sessions/` | | | LLM 摘要记忆 | 跨 session 摘要在重启后保持 Agent 上下文 | | **记忆** | 本地用户/项目记忆 | 可搜索的事实、偏好、决策,存于 `~/.dvalincode/memory/`;支持从 Claude/Hermes/Markdown 导入 | | **数据可迁移** | 导出 / 导入全部数据 | 记忆 + Session + 配置 + 审计打包成一个文件 —— `dvalincode export` / `import`,或 GUI 设置 → Export / Import | | | Markdown 记录 | 任意对话下载为 Markdown —— 侧栏下载图标、`dvalincode session md `,或 `/api/sessions/:id/markdown` | --- ## ⌨️ 斜杠命令 | 命令 | 说明 | |---|---| | `/clear` | 清空当前对话（客户端，开启新 session） | | `/compact` | 调用 LLM 生成结构化摘要压缩上下文 | | `/undo [N]` | 撤销最近 N 个工具调用（默认 1） | | `/git` | 执行 `git_status`，显示分支、最近提交、变更文件 | | `/plan ` | 让 Agent 逐步规划任务而**不**执行 | | `/help` | 显示所有可用命令 | > 审计日志通过 `dvalincode report` **命令行**查看（`--last` / `` / `verify`），不是斜杠命令。 --- ## 🛠️ 架构 ``` ┌───────────────────────────┐ ┌─────────────────────────┐ │ 终端 UI (readline) │ │ 浏览器 GUI (React/Vite) │ │ 流式输出 · 行内审批 │ │ ChatThread · DiffViewer │ └─────────────┬─────────────┘ └────────────┬────────────┘ │ 进程内调用 HTTP / WebSocket │ ┌───────────────▼─────────────┐ │ │ Express + ws 服务 │ │ │ /api/* · `dvalincode serve` │ │ └───────────────┬─────────────┘ └──────────────┬─────────────────┘ ┌────────────────────────────▼────────────────────────────┐ │ runAgentTurn —— 共享回合执行器 (src/agent/session) │ │ provider · prompt（mode · git · AGENTS.md）· session │ └────────────────────────────┬────────────────────────────┘ │ ┌────────────────────────────▼────────────────────────────┐ │ Agent 引擎 │ │ AgentLoop（8 状态机） → AgentRunner │ │ 流式输出 · 中断 · Undo 栈 · LLM 压缩 │ │ run_start / run_end → AuditSink（哈希链 JSONL） │ └──────────────────────────┬──────────────────────────────┘ │ run() ┌──────────────────────────▼──────────────────────────────┐ │ ToolRegistry — Zod schema + 权限控制 │ │ + 审计埋点：tool_call · file_* · shell_exec │ │ read_file · list_files · search_text · git_status · │ │ write_file · edit_file · delete_file · shell │ └─────────────────────────────────────────────────────────┘ ``` ### Agent Loop — 8 状态 ``` RESTORE → COMPACT → COMMAND → BUILD → RUN → SAVE → RESPOND → DONE ``` 1. **RESTORE** —— 从 `~/.dvalincode/sessions/` 加载 session 2. **COMPACT** —— 上下文接近上限时压缩历史（LLM 摘要） 3. **COMMAND** —— 处理内置斜杠命令 4. **BUILD** —— 组装系统 prompt（模式 prompt + 项目 + git + AGENTS.md） 5. **RUN** —— 交给 `AgentRunner` 执行 LLM 工具调用循环 6. **SAVE** —— 持久化 session 7. **RESPOND** —— 生成跨 session 摘要记忆 8. **DONE** --- ## 🧪 测试 ```sh npm test ``` **584 个核心测试 · 74 个文件 · 全部通过。** VS Code 扩展另有 37 个测试， 以及一个可选的已发布包集成测试。 --- ## 🏗️ 源码构建 需要 [Bun](https://bun.sh)（`curl -fsSL https://bun.sh/install | bash`）。 ```sh git clone https://github.com/arthurpanhku/dvalincode cd dvalincode npm install npm run dev:all # 后端 (3001) + Vite (5173) ``` 构建所有平台 release 二进制： ```sh bash scripts/build-release.sh # → release/ 包含 tar.gz / zip + SHA256SUMS.txt bash scripts/build-release.sh darwin # 仅 macOS bash scripts/build-release.sh windows # 仅 Windows ``` 发布前校验： ```sh (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` 解析到解压出的可执行文件旁边。 注意：Bun 仅在 Windows 上编译时才允许注入 Windows `.exe` 图标/元数据。macOS/Linux 交叉编译仍会产出有效的 Windows 压缩包，但不带内嵌的 `.exe` 图标。 --- ## 🌐 Providers DvalinCode 支持任意 OpenAI 兼容端点。内置预设，按价格排序： | Provider | 最便宜模型 | 输入 / 输出价格 | 说明 | |---|---|---|---| | **Groq** | `llama-3.1-8b-instant` | 免费额度 | 最快的开源模型 —— Llama 3.3 70B、Mixtral | | **Ollama** | `qwen2.5-coder` | $0（本地）| 无需 API Key，本机运行 | | **DeepSeek** | `deepseek-chat` | $0.14 / $0.28 每 1M | 便宜且强；v3 几乎媲美 GPT-4 质量 | | **OpenRouter** | `google/gemini-2.0-flash-001` | $0.10 / $0.40 每 1M | 200+ 模型，包括 Claude、Gemini、Llama | | **OpenAI** | `gpt-4o-mini` | $0.15 / $0.60 每 1M | 可靠；`o1` 用于深度推理 | | **Custom** | — | 取决于服务方 | 任意 OpenAI 兼容 base URL | DvalinCode 顶栏实时显示本 session 的费用 —— 在 **LLM Configuration** 中切换 Provider、保存命名 Profile、实时比较。 --- ## ❓ 常见问题
会把我的代码发送到第三方吗？
只发送 Agent 向你配置的 LLM 发送的内容。Session、配置、Profile 全部保存在本地 ~/.dvalincode/。如需排除敏感文件，在仓库根目录放置 .dvalincodeignore（语法同 gitignore）。
没 API Key 能用吗？
能 —— 用 Ollama。本地拉模型（ollama pull qwen2.5-coder），在 LLM Configuration 中选择 Ollama Provider。无需 Key、无需网络、无 Token 费用。
为什么三种模式？只用一种不行吗？
它们面向不同结果和安全默认值：Home 统一只读 Ask 与审批式 Collaborate；Code 专注软件开发；Dvalin 用扫描证据、修复 case、隔离 worktree、测试复扫与显式 Draft PR 完成安全加固。任何时候都可切换并保留项目上下文。
Shell 工具有沙箱吗？
macOS 使用 sandbox-exec；Linux 在限制性网络策略下会在已安装 Bubblewrap 时启用它。Windows 暂无受支持的子进程网络沙箱，因此限制性策略会安全关闭执行，不会静默降级为无限制运行。原生命令运行器本身支持这三个平台。
支持哪些操作系统终端？
Linux 与 macOS 命令通过 /bin/sh 执行；Windows 命令通过系统 ComSpec（默认为 cmd.exe）执行。完整原生命令行支持管道、重定向与条件操作符；拆分的 command + args 形式会按宿主 shell 规则引用可执行文件路径及参数。
怎么查看 Agent 到底做了什么 —— 日志可信吗？
每次运行都向 ~/.dvalincode/audit/run-<timestamp>-<id>.jsonl 写入 JSONL 审计日志。用 dvalincode report --last 渲染（或在 GUI 看可折叠的 Run Report 卡片）。每条记录都用 SHA-256 哈希与上一条相连，因此任何事后修改都可被检测 —— dvalincode report verify <run-id> 会报告 ✓ chain intact 或断裂的确切位置。它是防篡改可检测，而非不可篡改：能重写整个文件的本地攻击者可重算整条链。其价值在于取证与可问责。完整威胁模型见 docs/AUDIT-TRAIL.md。
会不会不经询问就覆盖我的文件？
取决于模式。Home → Ask 永不写入；Home → Collaborate 每个文件都需逐一批准（批准前可见红绿 diff）；Code 与 Dvalin 遵循所选权限级别，Auto 只应在受信任工作区或隔离分支中使用。
macOS 二进制无法打开 —— "未验证的开发者"
二进制未签名。执行一次清除隔离标记： 
xattr -dr com.apple.quarantine ~/.dvalincode
或在 Finder 中右键 → 打开 → 确认。
Dvalin 必须安装所有外部扫描器吗？
不需要。Dvalin 的内置扫描器始终可用；若 PATH 中检测到 Semgrep CE、Trivy 或 OSV-Scanner，工作区会自动加入相应引擎。也可以导入任意兼容的 SARIF 2.1 结果。
AGENTS.md 每轮都会发送吗？
是的 —— DvalinCode 每轮对话前读取项目根目录的 AGENTS.md，注入系统 prompt 的 === PROJECT INSTRUCTIONS === 段。保持精简 —— 它会占用 token 预算。
--- ## 🤝 贡献 欢迎贡献！代码库保持紧凑、不堆叠 —— 详见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ```sh git clone https://github.com/arthurpanhku/dvalincode cd dvalincode && npm install npm test # 584/584 核心测试 ✅ npm run typecheck ``` --- ## 📄 License MIT —— 详见 [LICENSE](LICENSE)。 --- ## 🔗 独立声明与致谢 DvalinCode 是一个独立实现的项目，与 Anthropic、Claude、Claude Code、 OpenAI、OpenAI Codex、GitHub、Cursor、Aider、opencode、Cline、 HKUDS/nanobot，或本节提到的任何其他项目/厂商不存在从属、赞助、背书或商业关联。 我们感谢公开研究、开源项目、论文、标准、release notes 和业界通用工作流共同塑造了 agentic coding 生态；DvalinCode 的产品方向和架构设计也受到了这些公开经验的启发： - [HKUDS/nanobot](https://github.com/HKUDS/nanobot)（MIT）帮助验证了 DvalinCode `TurnState` 流程中显式 turn-state 的设计方向。 - [ReAct 论文](https://arxiv.org/abs/2210.03629)（Yao et al., 2022）提出的 “reason, act, observe” 循环，是许多现代工具调用型 Agent 的共同基础。 - OpenAI `tool_calls` 消息格式，以及更广泛的 OpenAI-compatible provider 生态，为 DvalinCode 的模型/工具交互提供了可移植接口。 - OpenAI Codex / Codex CLI、Claude Code、Aider、opencode、Cursor、Cline 等编码 Agent 帮助明确了用户对终端 Agent、plan/build 模式、权限提示、 项目本地上下文、沙箱、session lifecycle、MCP 集成和 diff-first 编辑工作流的期待。 - [OpenAI Codex Security](https://github.com/openai/codex-security) 及其公开文档为 Dvalin 的专业安全 Agent 研究和可移植 SARIF 交接提供了参考；Dvalin 仍是独立且参与 竞争的安全运行时。 - `AGENTS.md` 项目指令约定在编码 Agent 工具中较常见，也影响了 DvalinCode 加载项目本地指令的行为设计。 - CodeQL、GitHub Code Scanning、Semgrep、SARIF、OpenSSF Scorecard 与 ISO/IEC 42001 影响了 DvalinCode 的安全修复闭环和 approvability 定位。 - Git worktree、MCP 与 local-first 开发者工具模式，影响了隔离修复、受治理工具 访问和可审计执行等产品方向。 这些参考帮助我们理解用户对编码 Agent 的期待。除非明确标注，DvalinCode 的源代码、 prompt、UI 文案、工具 schema、模块布局和产品实现均为原创；未复制上述项目的 源代码、prompt 或 UI 文案。 完整来源参考：[docs/REFERENCES.md](docs/REFERENCES.md) --- ## 💛 感谢每一位贡献者

每一个 Issue、想法、文档改进、测试和代码贡献，都在帮助 DvalinCode 变得更好。

| 贡献者 | GitHub 主页 | | --- | --- | | Arthur Pan | [@arthurpanhku](https://github.com/arthurpanhku) | | Shivas | [@shivasb42](https://github.com/shivasb42) | | Aditya | [@adity982](https://github.com/adity982) | | badhope | [@weed33834](https://github.com/weed33834) | | Samran Asif | [@webdevsamran](https://github.com/webdevsamran) | | dchaudhari7177 | [@dchaudhari7177](https://github.com/dchaudhari7177) | 查看[完整贡献记录](https://github.com/arthurpanhku/dvalincode/graphs/contributors)，其中也包含自动依赖更新和维护记录。

也想加入？阅读贡献指南，提交你的第一个 Pull Request。