evidentloop/sopify

Resumable, traceable AI coding — plans, handoffs, and evidence stay with the repo across hosts.

Sopify – 可恢复、以计划为先的 AI 编码

是什么 – Sopify 是一个轻量级协议层，位于现有的 AI 编码助手（GitHub Codex、Anthropic Claude、Qoder、GitHub Copilot）之上。它会在需求不明确时强制助手暂停，强制记录计划，并将该计划及验证证据存储在由 Git 跟踪的隐藏 .sopify/ 文件夹中。当您（或团队成员）稍后在任何支持的主机上打开同一仓库时，只需输入 ~go，主机将自动从下一个未完成的任务恢复保存的工作流。

为何重要 – 许多 AI 编码工具会直接跳转到代码生成，这常常导致：

在事实未明了前就进行过早更改，
切换机器或 LLM 主机时丢失上下文，以及
设计决策未被记录。 Sopify 通过将规划和决策步骤转化为项目资产，随仓库一同移动，解决了这些问题。

核心概念

概念	作用
受控工作流	主机请求澄清，创建设计，将工作拆分为任务，并将计划写入 `.sopify/plan/`。只有在您明确确认后才会生成代码。
恢复指针	一个小型本地文件（不在 Git 中）记录您当前所处的步骤。在任何主机上输入 `~go` 会读取计划，并从下一个任务继续。
可追溯性	每个需求、设计选择和评审均以纯文本/JSON 文件形式保存在 `.sopify/` 中。您之后可以检查某行代码为何存在。
主机无关性	相同的 `.sopify/` 文件被 Codex、Claude、Qoder 以及（有限程度上）Copilot 理解，因此团队可自由切换助手而不会破坏流程。

快速开始（来自 README）

# 为特定主机（此处为 Codex，美国英语）安装 Sopify 层
curl -fsSL https://github.com/evidentloop/sopify/releases/latest/download/install.sh \
  | bash -s -- --target codex:en-US

需要 Python 3.11+。

安装后，打开已包含 .sopify/ 文件夹的仓库（或新建一个），运行：

~go            # 开始或恢复完整工作流
~go plan       # 仅创建计划，尚未生成代码
~go finalize   # 在交付证据准备就绪后关闭当前计划

安装程序可在执行前审查（`curl … -o install.sh && less install.sh`）。Windows 用户有等效的 PowerShell 脚本。

配置（示例）

# 放置在仓库根目录的 sopify.config.yaml
brand: auto
language: en-US
workflow:
  mode: adaptive   # strict | adaptive | minimal
  require_score: 7 # 主机自动推进前所需的最低置信度分数

配置文件与代码一同存放，并自身进行版本控制。

目录结构（相关部分）

.sopify/
├─ blueprint/   # 基线设计规格、缩减目标
├─ plan/        # 活跃计划 + 验证凭证
└─ history/     # 归档（完成）的计划

其他源文件（`sopify_writer/`、`skills/` 等）实现协议，但无需终端用户编辑。

典型工作流

请求 – 您请求一个功能（例如：“添加缓存层”）。
计划 – Sopify 提示主机分析需求、生成设计，并将工作拆分为任务。计划保存在 .sopify/plan/ 下。
确认 – 您批准计划后，主机才开始生成代码。
编码 – 主机编写代码，附带一份凭证，将每个变更回溯到原始任务。
恢复 – 如果您在功能中途停止，本地恢复指针会记住最后完成的任务。在另一台主机上打开仓库并输入 ~go，将从任务 N+1 继续。
归档 – 功能完成后，~go finalize 将计划及其证据归档至 .sopify/history/。

使用场景

团队交接 – 开发者可在 Codex 中启动功能，将仓库交给使用 Claude 的团队成员，后者无需重新解释上下文即可恢复。
可审计性 – 管理员可审查 .sopify/plan/ 文件，了解为何做出特定实现决策。
多语言项目 – 由于协议文件与语言无关，只要主机支持目标语言，该工作流即可用于 Python、JavaScript 等。

架构快照（如 README 所述）

协议内核 – 解释 ~go 命令并管理恢复指针的核心逻辑。
默认工作流 – 一组规则（分数阈值、自适应模式）决定主机何时必须请求澄清。
知识层 – 存储计划、设计蓝图和验证凭证的 .sopify/ 文件；这些文件随 Git 仓库一起移动。

许可证

代码与配置 – Apache 2.0
文档 – Creative Commons BY 4.0

总结

Sopify 并不取代 LLM；它添加了一个有纪律的、Git 跟踪的流程，强制规划、保留决策，并让任何支持的 AI 编码主机都能从上一次会话结束处精确接续。对于依赖 AI 助手但需要可复现性和审计追踪的团队，Sopify 提供了一种低开销、主机无关的解决方案。