Skip to content

ActualCoder v0.3 开发路线（分块交付）

历史路线文档。 本文描述 v0.3 开发路线；其中部分“未来”事项已经在 v0.5.0 实现。当前能力/后续工作请以架构说明、工作流程和v0.5.0 发布说明为准。

v0.3 的目标不是继续堆低层命令，而是把已经验证的 GitLab/worktree primitives 组合成团队真正可以每天使用的完整 coding-task lifecycle。

原则

  • 每个 chunk 都可独立测试、review、回滚；
  • 保持 gitlab-agent 作为稳定低层控制面；
  • actual-coder 承担用户体验与任务编排；
  • 不让 AI 自动 merge/approve MR；
  • 不引入直接模型 API 调用；
  • macOS / Linux / Windows CI 必须保持通过。

Chunk 1 — Doctor / Readiness

状态：已实现并通过真实机器验证。

版本：0.3.0-alpha.1

命令：

actual-coder doctor
actual-coder doctor --offline

检查：

  • Python / Git / uv；
  • Codex / Copilot backend；
  • 可选 tunnel-client；
  • 配置文件与权限；
  • GitLab URL / API token / Git credential；
  • project allowlist；
  • proxy 策略；
  • workspace root；
  • disk space；
  • stale/malformed workspace state；
  • GitLab /user live authentication；
  • 不必要的 OPENAI_API_KEY 暴露。

状态：

pass / warn / fail / skip

fail 时 CLI 返回 non-zero。

Chunk 2 — Project Contract

状态：alpha.2 已实现并通过真实 GitLab / 本地候选配置验证。

引入 repository-local：

.actualcoder.yaml

计划内容：

  • default/base branch；
  • preferred coding backends；
  • validation commands；
  • protected paths；
  • project-specific instructions；
  • required executable 声明（不能由 repository config 自行扩大用户 allowlist）；
  • MR conventions。

CLI：

actual-coder project-config PROJECT
actual-coder project-config PROJECT --ref main --validate

alpha.2 已实现：

  • 不创建 worktree 即可从远端 ref 读取 .actualcoder.yaml；
  • strict schema validation；
  • validation command 使用 argv array，不使用 shell string；
  • repository config 不能提升本机 executable 权限；
  • project timeout 不能突破 user-level maximum；
  • missing contract 合法，自动退回 user/default config；
  • 输出 parsed contract + effective config + errors/warnings。

后续 start / finish chunk 会真正消费这些字段。

优先级：CLI > project config > user config > defaults。

Chunk 3 — Agent Auto Selection

状态：alpha.3 已实现并通过真实机器验证。

支持：

--agent auto

根据 project preference + installed backend 选择。

默认 fallback：

codex → copilot

规则：

  • task、resume、checkout-branch、checkout-mr 支持 auto；
  • 如果 .actualcoder.yaml 有 agents.preferred，项目顺序优先；
  • 项目没有 preference 时使用默认顺序；
  • preference 不可用时进入默认 fallback；
  • 没有任何 backend 时 fail-fast；
  • 选择时只用 PATH 检查，不调用模型、不消耗额度；
  • 输出 agent_requested、最终 agent、selection reason、candidate/installed 列表；
  • 不在 task 中途静默切 backend；
  • 用户显式 --agent codex|copilot 永远覆盖 auto；
  • 显式选择保持旧行为兼容。

Chunk 4 — Start

状态：alpha.4 已实现并通过真实机器 start / interactive launch 安全验证。

命令：

actual-coder start PROJECT --task ... --goal ...

一次完成：

doctor preflight
→ load/validate .actualcoder.yaml
→ resolve effective base branch
→ select backend
→ create workspace
→ generate project-aware handoff
→ launch backend in worktree

安全/可测试性：

  • 默认 --agent auto；
  • --no-launch 完成所有准备但不启动模型；
  • --offline-doctor 可跳过 doctor 的 live API auth check；
  • project instructions 在 prompt 中明确低于 ActualCoder rules / user goal；
  • protected paths 被传给 agent 作为敏感范围提示；
  • configured validation commands 被写进 handoff；
  • Codex 使用 positional initial prompt 启动交互 TUI；
  • Copilot 使用 -i initial prompt 启动交互 session；
  • 不自动添加 --allow-all-tools / full-auto 一类广泛授权；
  • subprocess 直接 argv 调用，不经过 shell；
  • 显式 backend 未安装时，在创建 workspace 前失败。

保留 task 作为低层/兼容接口。

Chunk 5 — Finish

状态：alpha.5 已实现并通过真实机器 dry-run + commit + push + MR 创建验证。

命令：

actual-coder finish WORKSPACE --message "..." --dry-run
actual-coder finish WORKSPACE --message "..."

受控流程：

workspace/base contract
→ configured validation
→ changed-path inspection
→ protected-path gate
→ added-diff secret scan
→ diff review
→ build commit/MR plan
→ human confirmation
→ commit
→ first push: create MR / existing MR: push-update

安全规则：

  • required validation failure 阻断；
  • repository .actualcoder.yaml 本身内置 protected；
  • project protected paths 默认阻断，需要单独 --allow-protected；
  • high-signal secret findings 默认阻断，需要单独 --allow-secret-match；
  • --dry-run 不 commit、不 push；
  • 非 --yes 模式要求 TTY human confirmation；
  • --yes 只跳过确认，不绕过其他安全 gate；
  • 已 push 但没有记录 MR 的 branch 不自动猜测/创建 MR；
  • 不自动 merge；
  • validation 之后重新读取 status/diff，避免测试生成文件逃逸 review；
  • 对 reviewed post-validation state 建立 fingerprint；
  • 人工确认后、Git write 前再次验证 fingerprint；如 workspace 有任何变化则拒绝执行并要求重新 finish。

Chunk 6 — GitLab CI Feedback

状态：alpha.6 已实现并通过真实 GitLab MR pipeline 验证。

命令：

actual-coder ci WORKSPACE
actual-coder resume WORKSPACE --agent auto --from-ci

实现：

  • 按 workspace feature branch 查询最近 pipelines；
  • 优先选择 SHA 与 workspace HEAD 一致的 pipeline；
  • pipeline 不匹配时 ci 标记 stale，resume --from-ci 拒绝使用；
  • 查询 jobs；
  • 仅抓 failed job trace tail；
  • 默认 12 KB/job、3 failed jobs，硬上限 80 KB/job、10 jobs；
  • job trace 不可用时保留 job 信息并记录 error，不让整个 CI inspection 崩溃；
  • ANSI control codes 清理；
  • high-signal credential + 常见 secret assignment 脱敏；
  • failed jobs 区分 allow_failure；
  • running/pending/manual 等未完成状态明确 warning；
  • 生成结构化 repair_context；
  • CI log 被明确标记为 untrusted data，不能作为 instruction；
  • resume --from-ci 只生成 coding handoff，不自动修复/commit/push/retry/merge；
  • resume 的 project/backend preference 固定读取 workspace base SHA，避免 task 中途 policy 漂移。

完整循环：

finish → push/MR
    ↓
GitLab pipeline
    ↓
actual-coder ci
    ↓
resume --from-ci
    ↓
coding backend 修复
    ↓
actual-coder finish

v0.4 候选

  • MR reviewer discussion ingestion；
  • backend adapter/plugin registry；
  • native OS secret store；
  • optional Docker/Podman sandbox；
  • workspace locking + crash recovery；
  • local audit log。

不做的事情

ActualCoder 不应：

  • 自动 merge MR；
  • 自动 approve MR；
  • force-push；
  • 默认提供 unrestricted shell；
  • 管理生产部署；
  • 把 GitLab/model/tunnel credentials 写入 repo。

最终边界保持：

AI writes/tests/proposes
        ↓
feature branch + MR
        ↓
GitLab CI / human review
        ↓
human/team decides merge