ActualCoder v0.3.0 发布前架构与安全审计¶

历史发布审计。 本文冻结的是 v0.3.0 当时的架构/安全状态，不应作为 v0.5.0 当前能力清单。当前状态见架构说明、安全边界和v0.5.0 发布说明。

日期：2026-09-19
范围：PR #3，v0.3.0-dev → main

1. 审计结论¶

v0.3 已形成完整的受控 coding lifecycle：

doctor
  ↓
project contract
  ↓
backend selection
  ↓
start / isolated workspace
  ↓
Codex / Copilot
  ↓
finish dry-run / validation / review
  ↓
human confirmation
  ↓
commit + feature-branch push + MR
  ↓
GitLab CI
  ↓
ci / resume --from-ci
  ↓
coding backend repair
  ↓
finish / push-update

在可信开发机 + 可信公司代码仓库的使用前提下，当前实现具备发布为 v0.3.0 的条件。最终 merge 仍以 GitHub PR checks 全绿为硬门槛。

2. 已完成的真实环境验证¶

Chunk	功能	真实环境验证
1	`actual-coder doctor`	已验证 Git/Python/uv、双 backend、配置权限、allowlist、workspace、GitLab API
2	`.actualcoder.yaml`	已验证远端缺省 fallback 与本地候选 contract validation
3	`--agent auto`	已验证 Codex/Copilot 自动选择与 selection rationale
4	`actual-coder start`	已验证 preflight → contract → backend → isolated worktree；interactive launch 后 workspace 安全
5	`actual-coder finish`	已验证 dry-run、review snapshot、人工确认、commit、push、真实 GitLab MR 创建
6	GitLab CI feedback	已验证真实 MR pipeline，pipeline SHA 与 workspace HEAD 匹配、CI success/job summary 正确

真实部署 hostname、token、Tunnel ID、个人路径等不写入本审计文档。

3. Git / GitLab 写入边界¶

project write allowlist 默认开启；
managed feature branch 必须符合安全 branch prefix；
不直接 push base branch；
不 force-push；
不自动 approve/merge MR；
不自动删除 remote branch；
Git credential 通过临时 GIT_ASKPASS 注入，不写进 remote URL；
first push 与已有 MR update 明确区分；
已 push 但本地没有记录 MR 的异常状态不会由 finish 静默猜测。

最终 merge 决策继续属于正常 GitLab review / CI / human process。

4. Workspace 与 finish 安全¶

actual-coder finish 是 v0.3 的主要写入安全边界：

workspace base policy
→ configured validation
→ post-validation status/diff
→ reviewability gate
→ protected-path gate
→ added-line secret scan
→ human-facing diff
→ reviewed-state fingerprint
→ confirmation
→ fingerprint re-check
→ commit
→ push-mr / push-update

4.1 Reviewability¶

高层 finish 默认阻断无法完整审阅的变化：

binary / non-UTF-8 changed file；
symlink change；
non-regular file / submodule-like path；
单文件超过 configured max_file_bytes；
changed path 数量过大；
aggregate changed content 过大；
human-facing diff 被 output cap 截断。

这些情况不提供一键绕过。若团队明确需要提交特殊资产，应人工审查后使用低层流程。

4.2 TOCTOU / reviewed-state binding¶

validation 完成后重新读取 workspace 状态，并记录 HEAD、dirty/status、commits ahead、pushed/MR state 与完整 security-diff hash。人工确认后、Git write 前再次计算 fingerprint；如 review 后 workspace 有变化，finish abort 且 zero Git write。

5. Repository-owned `.actualcoder.yaml` 边界¶

Safe YAML loader；
duplicate mapping key 直接拒绝；
version 严格类型检查；
contract 最大 64 KiB，并在 remote/local read 前做 size gate；
instruction / protected path / validation command / argv / executable 数量与长度有限制；
base/target ref 使用保守 Git-ref grammar；
path traversal / Windows-style traversal 被拒绝；
validation executable 必须已在用户 GITLAB_ALLOWED_EXECUTABLES；
repository contract 不能提升 executable 权限；
repository timeout 不能突破 user maximum；
.actualcoder.yaml 属于 finish built-in protected path；
project instructions 在 prompt 中明确标记为 repository-owned，低于 user goal / ActualCoder rules。

重要：executable allowlist 不是 sandbox。 uv、python、pytest、make、npm 等已批准工具仍可执行 repository-controlled code。

6. CommandRunner 边界¶

shell=False；
executable bare-name allowlist；
固定 workspace cwd；
timeout/output cap；
isolated HOME；Windows 同时隔离 USERPROFILE；
清理明显 secret env；
不继承 SSH auth / Git askpass；
默认 GitLab API/Git 绕过 host proxy 环境。

但 runner 不是 filesystem/network sandbox。不可信 repository 必须使用 container/VM/disposable host。

7. Secret 与 credential 防护¶

tracked files + release-line history scanner；
CI 使用 full Git checkout；
GitGuardian PR scan；
.env / key / cert artifacts gitignore；
zero direct OpenAI model API dependency/invariant 由 CI 检查；
finish 对新增 diff 做 high-signal secret detection；
CI failed-job logs 进入输出/prompt 前进行 bounded streaming tail、ANSI cleanup、credential/secret assignment redaction。

Secret scanning/redaction 属于 defense in depth，不替代 credential rotation。

8. CI feedback trust boundary¶

CI logs 明确属于 untrusted diagnostic data；
优先要求 pipeline SHA == workspace HEAD；
stale CI 不进入 resume --from-ci handoff；
running/pending/manual 等未完成状态明确标记；
failed-job trace 使用 bounded streamed tail；
pipeline jobs 分页；超过安全分页上限时拒绝给出可能不完整的 evidence；
success pipeline 不制造不存在的 failure；
CI feedback 不自动 edit / commit / push / retry / approve / merge；
修复后仍回到 actual-coder finish。

9. 跨平台¶

Platform	Status
macOS	first-class
Linux	first-class
Windows 10/11 native PowerShell	first-class
Windows + WSL2	Linux path supported

CI matrix 持续覆盖 Ubuntu、macOS、Windows、Python compile、workflow tests、CLI packaging、Windows PowerShell parse 与 secret/history audit。Secure MCP Tunnel 的真实网络 E2E 不在公共 GitHub Actions 中执行，因为它需要 private network/credential；该链路已在真实环境独立验证。

10. 已知限制 / 非 release blocker¶

10.1 Host execution 不是 sandbox¶

敏感/不可信代码使用 VM/container。

10.2 Workspace 暂无 process locking¶

同一 workspace 同一时刻只应有一个 mutating writer。locking + crash recovery 进入后续版本。

10.3 Backend availability != authentication/quota¶

actual-coder agents / auto selection 只检查 executable，不调用 backend，因此不验证登录、subscription entitlement、quota。

10.4 Secret redaction 是 heuristic¶

不能承诺识别所有未知 credential format。

10.5 `checkout-mr` 当前只支持 same-project MR¶

fork/cross-project MR 不属于 v0.3 范围。

10.6 HTTP GitLab¶

工具支持 HTTP，但链路不加密。只能在可信 private network/VPN 使用；条件允许时迁移 HTTPS。

10.7 MR URL recovery¶

Git push-option 创建 MR 后依赖 GitLab push output 提取 MR URL。极端情况下若未返回/未解析，workspace 会保守进入“已 push、未记录 MR”状态，不会自行猜测；可通过 checkout-mr 显式恢复。

11. 机械审计结果¶

对 PR 增量做高风险 primitive scan：

no shell=True；
no os.system；
no eval/exec；
no force-push addition；
no merge/approve implementation；
no OpenAI model SDK/API endpoint；
no private-key material；
credential-shaped 命中仅为 scanner 的已知 dummy fixture；GitGuardian 未认定为 secret。

Release gate：

validate                  success
ubuntu                    success
macOS                     success
windows                   success
history secret scan       success
GitGuardian               success
PR mergeable              true

12. v0.4 后续¶

workspace locking + crash recovery；
backend adapter/plugin registry；
MR review discussion ingestion；
native OS credential store；
optional Docker/Podman sandbox；
local audit log；
richer pipeline/review iteration UX。

这些不阻塞 v0.3.0。

13. Release decision¶

若最终 release-candidate head required checks 全绿，建议：

v0.3.0-dev
   ↓ squash merge
main
   ↓
v0.3.0

并继续保持：

AI may inspect / edit / validate / propose / update its MR
Human + normal GitLab process decides merge