andrepontesmelo/archloop

archloop

CI
Version
local gate

archloop banner

面向 git 仓库的无人值守夜间架构改进循环。一个确定性的
bash 状态机自动化了 Matt Pocock 的 improve-architecture
技能：它运行该技能，触发一个 opencode 会话来实施每一条 Strong
建议，并在每次实施之后进行一次全新上下文的审查——直到代码库
扫描报告不再有 Strong 候选项。

它做什么

archloop-loop.sh 会针对目标仓库反复运行 run.sh，直到扫描报告不再有 Strong
候选项，或者触及 MAX_ROUNDS 安全上限（默认 8——PARKED 项可能被重新提出，
所以该上限会终止一个永不收敛的夜晚）。

每一轮 run.sh 都会走一条固定的流水线：

1. 预检 — 除非规范检出目录干净、位于 main 分支，且基线
测试 + lint 均为绿色，否则中止。规范工作树永远不会被触碰。
2. 扫描 — 一个会话读取 architecture-scan 技能并列出 Strong 候选项
（跨 3 个以上位置的重复或分裂契约，或一种静默失败模式；修复
必须删除的代码多于它添加的代码）。一个计划覆盖所有 Strong 候选项，最优
者优先。没有符合条件的 → NONE 判定，停止。
3. 实施 — 每个条目一个会话，在隔离的 worktree 中进行，保持测试 + lint
为绿色。
4. 门禁 — 每个条目一个全新上下文的审查会话。每个条目判定为 SHIP 或 PARK；
一次 PARK 会重置分支，代价是一个条目，而不是整个夜晚。
5. 合并 + 推送 — SHIP 的条目以 --no-ff 合并回 main，并在运行结束时
推送（ARCHLOOP_MERGE=0 / ARCHLOOP_PUSH=0 可禁用）。

每个阶段都读写仓库 .archloop/ 目录下的文件——是产物，
而非记忆。该运行可崩溃重启，且完全可审计。

编排器是脚本，不是模型：序列是一个固定的状态机——
确定性、免费、可重启、不受夜间上下文腐化影响。模型在各
阶段内思考；脚本对它们进行排序，并 grep 单词判定文件。一个全新的 opencode
run 会话就是一个阶段边界。

它为何存在

架构债务恰恰是没人接手的工作：建议躺在审查里，而
本可以应用它们的会话从未启动。archloop 让这个循环无人值守：扫描、
实施、审查、重复——只要你愿意，每晚都行，且每一处变更在合并前
都由一次全新上下文的审查把关。

它如何流转

一轮 run.sh——脚本负责排序，模型在各阶段内思考：

flowchart TD
P["Preflight — clean tree · on main · baseline green"] -->|"abort"| X["ABORT — canonical tree untouched"]
P --> S["Scan — list Strong candidates, plan best first"]
S -->|"NONE 判定"| D["停止——没有剩余 Strong"]
S -->|"PLANNED"| I["实现——隔离的 worktree，测试 + lint 通过"]
I --> G["Gate——对每个条目进行全新上下文审查"]
G -->|"SHIP"| N{"还有更多条目？"}
G -->|"PARK——分支重置，消耗一个条目"| N
N -->|"是"| I
N -->|"否"| M["合并 SHIPped --no-ff · push"]
M --> R["REPORT.md + ledger 写入目标 .archloop/"]

什么让一个发现成为 Strong——以及每一个最终去向何处：

flowchart LR
A["架构扫描"] --> B{"Strong 候选？"}
B -->|"跨 3 个以上位置的重复或分裂契约，或静默失败模式——并且修复删除的代码多于新增的代码"| C["已规划，最优优先"]
B -->|"其他一切"| W["Weak——从不规划"]
C --> E["在 worktree 中进行全新上下文审查"]
E -->|"SHIP"| F["以 --no-ff 合并到 main"]
E -->|"PARK"| L["PARKED 记录在 ledger 中，分支重置"]

安装

克隆并运行——无需包，除 bash、git 以及 PATH 上带有已配置模型的
opencode 二进制文件外，没有其他依赖：

git clone https://github.com/andrepontesmelo/archloop
cd archloop

没有 tarball 发布，因此没有可验证的校验和——请固定一个 tag
或 commit 以保证可复现性，而不是浮动在某个分支上：

git checkout    # 固定你所运行的内容，尤其是在夜间运行时

[!WARNING]
该循环驱动会话，在 worktree 中实现代码并运行审查：
它从不触碰规范树，但它会执行由 agent 编写的代码。
在无人值守的夜间运行之前，请审查目标仓库的 .archloop/config——错误的测试/lint 命令或模型 id 会消耗配额或合并出意外。
会话运行器的配置中需要模型凭据。

使用零配额门禁验证安装（无需模型调用，无需密钥）：

bash scripts/stub-validation.sh   # 跨 6 个场景的 25 个断言

常用命令：

bash scripts/stub-validation.sh   # 本地门禁——每次 push 前运行
bash scripts/concurrency-gate.sh  # CI 并发门禁：两个并行套件运行
./run.sh /path/to/repo [max_items]
./archloop-loop.sh /path/to/repo [max_items] [max_rounds]

快速开始

一轮：扫描 → 实现 → 门禁 → 合并
./run.sh /path/to/repo [max_items]

循环直到没有剩余 Strong 候选（或达到 MAX_ROUNDS）
./archloop-loop.sh /path/to/repo [max_items] [max_rounds]

每晚：安装一次——每晚 02:17，无人值守
( crontab -l 2>/dev/null; echo "17 2 * * * /path/to/archloop/archloop-loop.sh /path/to/target-repo" ) | crontab -

计划运行完全自记录：循环驱动器将每一轮和
判定写入目标的 .archloop/loop-driver.log。systemd 用户定时器
替代方案和无人值守运行说明见 docs/nightly.md。

可选的按仓库配置从目标的 .archloop/config 读取（模型覆盖、
合并/push 开关、夜间标签）。产物落在目标的 .archloop/ 中——添加
将 .archloop/ 添加到仓库的 .git/info/exclude 中（如果缺失，循环驱动程序会自行执行此操作）。

文档

从文档索引开始：

- 架构 — 流水线、组件、判定契约、执行顺序。
- 每夜运行 — cron / systemd 用户定时器安装、无人值守运行说明。
- 开发 — 目录结构、本地门禁、约定、推送前检查清单。

贡献

欢迎提交 PR — 工作流程和本地门禁请参见 CONTRIBUTING.md。
安全问题：SECURITY.md（请勿公开提交 issue）。

路线图

- 通用 harness 编排 — 目前每个阶段都是一个 opencode run 会话。
下一步：让运行器跨 harness 通用 — DeepSeek、Claude Code、opencode、
Codex、Hermes — 使其中任何一个都能执行各阶段。

环境要求

- Bash 和 git；PATH 中有一个 opencode 二进制文件，并已配置模型。

许可证

MIT — 参见 LICENSE。