wishforge-ide/docs/reference/verification-profiles.md
eust-w b38db08eeb docs: align documentation with the code and write it in Chinese
Operations, development and architecture docs, the reference pages and the
component READMEs were rewritten against the code: every documented variable
exists, and the settings operators need (runtime image, Git service, listen
addresses, Runner targets, single-tenant gateway and provisioner bindings) are
documented.

Gaps the docs used to present as working are now stated as such: IDE
workspaces do not clone the project yet (FR-H2), and in Kubernetes mode
dependency installs and image builds have no network path until an egress
proxy and builder access exist. The Kubernetes README describes what the
provisioner creates, what the Runner needs in a target namespace, and the
cluster acceptance that is still outstanding.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 18:01:39 +08:00

37 lines
2.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 受保护的验收配置
项目的验证命令保存在平台上,Agent 不能修改;但这些命令运行的测试代码在仓库里,Agent 可以修改(例如改写 `npm test` 背后的脚本)。因此生产交付除了项目的验证命令,还要求一份由平台运维独立安装的**验收配置**(verification profile)。
## 安装
运维把验收脚本构建进 verifier 镜像的 `/usr/local/lib/wishforge-verification/` 目录,属主为 root,运行用户不可写。verifier 镜像根文件系统只读;bubblewrap 以只读方式暴露 `/usr`,不暴露模型凭据与 worker 令牌。
- 命令必须使用绝对路径的可执行文件,并引用配置中列出的、固定摘要的脚本文件;所有自定义辅助文件都要列入配置,解释器等运行时依赖属于固定的 verifier 镜像。
- 验收配置是可信的平台代码:不能把仓库控制的断言库或评分规则加载进自己的进程。Web 应用的验收应在隔离的检查中把应用作为单独的子进程启动,再由可信代码断言 HTTP/浏览器行为与持久化结果。
API 通过 `WF_VERIFICATION_PROFILES_JSON` 配置(数组):
```json
[{
"id": "catalog-web",
"version": "2026-10-17.1",
"commands": [["/usr/local/bin/node", "/usr/local/lib/wishforge-verification/catalog/accept.mjs"]],
"files": [{"path": "/usr/local/lib/wishforge-verification/catalog/accept.mjs", "sha256": "<文件的 SHA-256>"}]
}]
```
## 绑定到项目
`GET /v1/verification-profiles` 列出已安装的配置及版本。owner/admin(必须是人,连接器不行)通过 `POST /v1/projects/:id/verification-profile`、body `{"profileId":"catalog-web"}` 选择一份。该接口不能上传脚本、修改命令或授予文件权限。解析后的完整配置保存到项目,随执行上下文下发,并计入证据与发布的验证策略摘要。
## 执行与证据
- verifier 在执行任何检查前核对每个文件的位置、类型、属主、大小与摘要。
- 验收配置的命令一定会执行,即使仓库测试全部通过;证据记录配置摘要。
- 修改运维配置或项目选择的配置,都会使之前的验证、构建与审批失效,需要重新验证;移除已选择的配置后无法继续发布。
- 生产模式下没有验收配置时,运行进入 `verification_unconfigured` 等待,不会退回只跑仓库测试。开发模式可以不配置,但其结果不代表受保护的生产验收。
## 测试
`tests/verification-profile.test.ts` 覆盖:缺少配置时拒绝、必须覆盖全部受保护命令、摘要绑定、配置变化后构建与审批失效、不安全路径,以及生产拒绝非沙箱证据。每个项目仍需要编写真实的业务验收断言;空的或只做表面检查的脚本不构成业务验收。