Skip to content

Commit a430014

Browse files
Li-SanzeLi-Sanze
authored
Merge pull request #57 from evidentloop/release/p9-w0-public-surface
release: 2026-06-13 public surface refresh + W0 version model
2 parents fb19833 + 679fdca commit a430014

28 files changed

Lines changed: 1141 additions & 168 deletions

‎.sopify/blueprint/README.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,21 @@
11
# 项目蓝图索引
22

3-
状态: L3 history-ready
3+
状态: L2 active
44
维护方式: Sopify 托管自动区块；本页只保留状态、当前目标、当前焦点与阅读入口。
55

66
## 当前目标
77

88
<!-- sopify:auto:goal:start -->
9-
- 项目：`sopify-skills`。
9+
- 项目：`sopify`。
1010
- 长期目标与范围收敛到 `./background.md`；本索引只保留索引必需区块，不展开正文。
1111
<!-- sopify:auto:goal:end -->
1212

1313
## 当前焦点
1414

1515
<!-- sopify:auto:focus:start -->
16-
- 当前活动 plan：无（P8 已归档）。
17-
- P8 Protocol Kernel & Runtime Retirement 已归档至 `../history/2026-06/20260605_p8_protocol_kernel_runtime_retirement`（runtime 删除 + canonical root .sopify + Qoder host proof + 蓝图全量对齐）。
18-
- history 归档：已可用；最近归档为 `../history/2026-06/20260605_p8_protocol_kernel_runtime_retirement`。
16+
- 当前活动 plan：`../plan/20260611_p9_host_uplift_protocol_cleanup`（architecture 级，版本模型闭环 + 公共展示面刷新；W1a 四宿主验证后置）。
17+
- P8 Protocol Kernel & Runtime Retirement 已归档至 `../history/2026-06/20260605_p8_protocol_kernel_runtime_retirement`。
18+
- history 归档：已可用；最近归档：`../history/2026-06/20260605_p8_protocol_kernel_runtime_retirement`。
1919
<!-- sopify:auto:focus:end -->
2020

2121
## 深入阅读入口

‎.sopify/blueprint/background.md‎

Lines changed: 13 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -12,35 +12,34 @@ Sopify 官方在 core 之上提供一个轻量、可插拔、收敛式的 bluepr
1212

1313
| 层 | 职责 | 生存性 |
1414
|----|------|--------|
15-
| **Core**（证据与授权层） | 协议规范 + Validator 授权 + 收据/接力/归档 truth | Durable：不随宿主生态变化而 sunset |
16-
| **Default Workflow** | blueprint 驱动的分析 → 计划讨论 → 标准方案包 → 开发验证 → 归档回写 | 用户买到的主体验，建构在 core 之上，不硬绑 runtime 状态机 |
17-
| **Plugins / Skills** | cross-review、graphify、宿主自带分析/开发/验证增强 | Sopify 定义接入点（Producer/Verifier/Knowledge Provider），不做 skill 分发 |
15+
| **Protocol Kernel**（协议内核） | 协议规范 + sopify_writer + 收据/接力/归档 truth | Durable：不随宿主生态变化而 sunset |
16+
| **Default Workflow** | blueprint 驱动的分析 → 计划讨论 → 标准方案包 → 开发验证 → 归档回写 | 用户买到的主体验，建构在 protocol kernel 之上 |
17+
| **Plugins / Skills** | cross-review、graphify、宿主自带分析/开发/验证增强 | Sopify 定义接入点，不做 skill 分发 |
1818

1919
核心价值不在于"能调 skill"或"能编排 workflow"，而在于：
2020

2121
- **证据规范**：定义任务事实、方案事实、交接事实、归档事实的标准格式
22-
- **授权判定**：Validator 是唯一授权者——判断当前上下文下行动是否可执行
23-
- **收据生成**：fail-closed 授权回执让每次决策可追溯、可审计
22+
- **收据生成**：每次决策可追溯、可审计
2423
- **跨宿主接力**：`.sopify/` 纯文件协议让任务中断后在不同宿主/模型间精确恢复
25-
- **知识沉淀**：只有跨任务可复用、能改变后续授权或验证基线的稳定结论，才进入长期知识层（blueprint / history）
24+
- **知识沉淀**：只有跨任务可复用、能改变后续验证基线的稳定结论，才进入长期知识层（blueprint / history）
2625

27-
**外插原则**：谁负责"把事做好"（生产、验证、知识处理），谁外插；谁负责"把结果变成可验证事实"（证据规范、授权判定、收据生成），谁进 Sopify core。
26+
**外插原则**：谁负责"把事做好"（生产、验证、知识处理），谁外插；谁负责"把结果变成可验证事实"（证据规范、收据生成），谁进 Sopify protocol kernel。
2827

29-
**产品形态锚点**：Protocol 是新宿主的唯一硬依赖（Convention 模式下无需 runtime 即可合规工作）；Validator 是宿主吸收执行编排后 Sopify 最后保留的面（durable core 的生存底线）；Runtime 是确定性加固线，不是接入前提（新接入方不应被要求先跑完整 runtime）；一切外部验证与生产能力通过 integration contract 外插，不进 core（边界判定原则）。
28+
**产品形态锚点**：Protocol 是宿主的唯一硬依赖；宿主执行、Sopify 保存、任意宿主恢复——这是 P8 runtime 退场后的三层分工。一切外部验证与生产能力通过 integration contract 外插，不进 kernel。
3029

3130
## 核心架构模式
3231

33-
Sopify 的一切交互遵循一条管线：
32+
P8 后 Sopify 不再运行进程。一切交互通过纯文件协议：
3433

3534
```
3635
用户自然语言
37-
→ Host LLM 映射为 ActionProposal（结构化工单）
38-
→ Validator 校验 schema + 事实 + side effect
39-
→ Deterministic action 按结构化字段执行
40-
→ Handoff / Receipt 暴露机器事实
36+
→ Host LLM 读取 .sopify/blueprint + plan + state
37+
→ Host LLM 按协议约定生成 ActionProposal
38+
→ sopify_writer 写入 state / receipt / handoff
39+
→ 下次会话（同宿主或跨宿主）通过 4-step read chain 恢复上下文
4140
```
4241

43-
Host LLM 只是 proposal source，不是 authorizer。Validator 是唯一授权者。执行层不理解人话，只按结构化字段和文件事实做事。
42+
Host LLM 是 proposal source 和 executor。sopify_writer 是唯一的 machine truth 写入路径。协议文件是跨会话、跨宿主的持久真相。
4443

4544
## 当前现实
4645

‎.sopify/project.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# 项目技术约定
22

33
## Runtime 快照
4-
- 项目名：sopify-skills
4+
- 项目名：sopify
55
- 工作目录：项目根目录
66
- 运行时目录：`.sopify`
77
- 根配置：`sopify.config.yaml`

‎.sopify/sopify.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,5 @@
33
"capabilities": [],
44
"locator_mode": "global_first",
55
"schema_version": "1",
6-
"workspace_kind": "external"
6+
"workspace_kind": "deep"
77
}

‎CHANGELOG.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,39 @@ Format: Summary → Changed → Plan Packages. File-level details live in `git l
66

77
## [Unreleased]
88

9+
## [2026-06-13.221525] - 2026-06-13
10+
11+
### Summary
12+
13+
- Changes across: Docs, Scripts, Tests, Changed.
14+
15+
### Changed
16+
17+
- **Docs**: Refined public documentation (4 files)
18+
- **Scripts**: Adjusted maintenance scripts (2 files)
19+
- **Tests**: Updated automated coverage (2 files)
20+
- **Changed**: Updated project files (15 files)
21+
22+
## [2026-06-13.220854] - 2026-06-13
23+
24+
### Summary
25+
26+
Public surface refresh + W0 version model hardening: README rewrite with new hero tagline ("Resumable AI coding — ask first, plans stay with the repo"), bilingual scene illustrations, product-form diagrams, architecture SVG update, installer fail-loud version handling, 4-state status/doctor classifier, and protocol check continuation semantics fix.
27+
28+
### Changed
29+
30+
- **README**: New hero tagline (EN/CN), "how it works" body paragraph (managed workflow scoping, git-tracked plans/receipts vs local resume pointers), host compatibility badges (Codex / Claude / Qoder / Copilot), `for-the-badge` style for all shields.
31+
- **Illustrations**: 3 bilingual scene images (ask / cross-host / decision), 2 product-form release SVGs (EN/CN), architecture SVG regenerated.
32+
- **Installer (W0)**: Fail-loud version handling — 3 silent `0.0.0-dev` fallbacks replaced with `InstallError`; 4-state inspection classifier (`up_to_date` / `pinned_old_but_healthy` / `stale` / `broken`) with status/doctor rendering; bootstrap workspace stale-pin diagnostics.
33+
- **Protocol check**: Continuation semantics fix for handoff pointer handling.
34+
- **Docs**: Release process preflight updated; getting-started bundle_version example aligned to version model.
35+
- **Blueprint**: Status L2 active; focus updated to "版本模型闭环 + 公共展示面刷新".
36+
37+
### Host Support
38+
39+
- Codex / Claude / Qoder: PROTOCOL_VERIFIED
40+
- Copilot: BASELINE_SUPPORTED (verification planned for W1a)
41+
942
## [2026-06-10.191940] - 2026-06-10
1043

1144
### Summary

‎README.md‎

Lines changed: 37 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,31 +2,38 @@
22

33
<div align="center">
44

5-
**AI coding that asks before it acts**
5+
**Resumable AI coding — ask first, plans stay with the repo**
66

7-
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)
8-
[![Docs](https://img.shields.io/badge/docs-CC%20BY%204.0-green.svg)](./LICENSE-docs)
9-
[![Version](https://img.shields.io/badge/version-2026--06--10.191940-orange.svg)](#version-history)
10-
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
7+
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge)](./LICENSE)
8+
[![Docs](https://img.shields.io/badge/docs-CC%20BY%204.0-green.svg?style=for-the-badge)](./LICENSE-docs)
9+
[![Version](https://img.shields.io/badge/version-2026--06--13.221525-orange.svg?style=for-the-badge)](#version-history)
10+
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge)](./CONTRIBUTING.md)
11+
12+
[![Codex](https://img.shields.io/badge/host-Codex-4A9EFF.svg?style=for-the-badge)](#quick-start)
13+
[![Claude](https://img.shields.io/badge/host-Claude-CC785C.svg?style=for-the-badge)](#quick-start)
14+
[![Qoder](https://img.shields.io/badge/host-Qoder-7C3AED.svg?style=for-the-badge)](#quick-start)
15+
[![Copilot](https://img.shields.io/badge/host-Copilot-000000.svg?style=for-the-badge)](#quick-start)
1116

1217
English · [简体中文](./README.zh-CN.md) · [Quick Start](#quick-start) · [Contributors](./CONTRIBUTORS.md)
1318

1419
</div>
1520

1621
<div align="center">
17-
<img src="./assets/sopify-cover.jpg" width="660" alt="Sopify — AI coding that asks before it acts" />
22+
<img src="./assets/sopify-cover.jpg" width="660" alt="Sopify — Resumable AI coding, ask first, plans stay with the repo" />
1823
</div>
1924

2025
---
2126

22-
AI coding tools are fast. But when they jump to code without understanding what's needed, speed becomes rework. Sopify is a development process protocol layer for AI coding — it turns plans, decisions, handoffs, and verification records into project assets, so work can stop, resume, and be traced.
27+
AI coding tools are fast. But when they jump to code before the facts are clear, speed turns into rework. Sopify is a development process protocol layer for AI coding: in managed workflows, the host asks before coding when requirements are incomplete or a decision still needs you.
28+
29+
Sopify stores plans and verification receipts in `.sopify/` as project files tracked by git. Only the local resume pointers stay out of git. Open the same repo on another host, and it reads those files to continue from where the work stopped.
2330

2431
No new editor, no new CLI. Install into the host you already use — Codex, Claude, Qoder, or Copilot.
2532

2633
**Design principles:**
2734

2835
- **Stop when unsure** — score every requirement; ask before assuming
29-
- **Resume from anywhere** — plans, decisions, and verification records are tracked in `.sopify/`; open the repo on any host and pick up where you left off
36+
- **Resume from anywhere** — plans and verification receipts are tracked in `.sopify/`; open the repo on any host and pick up where you left off
3037
- **Trace every decision** — plans, choices, and reviews persist in `.sopify/`
3138

3239
**What Sopify prevents:**
@@ -58,16 +65,28 @@ After install, use `~go` to start a managed workflow. See [Installation](#instal
5865
**When requirements are unclear, it stops to plan first.**
5966
You say "add a caching layer." Sopify doesn't start coding — it plans first: analyze, design, split into tasks, then save to `.sopify/plan/`. Only after you confirm the plan does it write code. Every line changed traces back to a decision.
6067

68+
<div align="center">
69+
<img src="./assets/readme-visuals/sopify-scene-ask-en.jpg" width="720" alt="Plan first, code second — discuss, record, execute" />
70+
</div>
71+
6172
**Your teammate picks up where you left off.**
6273
You start a feature in Codex, finish the design, and implement two of four tasks. Next week your teammate opens the same repo in Claude, types `~go`. Sopify reads the checkpoint and continues from task 3 — no handoff doc, no re-explaining context.
6374

75+
<div align="center">
76+
<img src="./assets/readme-visuals/sopify-scene-cross-host-en.jpg" width="720" alt="Seamless cross-host handoff" />
77+
</div>
78+
6479
**Every decision leaves a trace.**
6580
A month later, someone asks why the cache key includes the user ID. The answer is in `.sopify/plan/` — the requirement that prompted the decision, the design that resolved it, the review that approved it.
6681

67-
## Architecture
82+
<div align="center">
83+
<img src="./assets/readme-visuals/sopify-scene-decision-en.jpg" width="720" alt="Every decision traced — auditable and reviewable" />
84+
</div>
85+
86+
## Product Form
6887

6988
<div align="center">
70-
<img src="./assets/sopify-architecture.svg" width="760" alt="Sopify Architecture — protocol kernel + workflow + host adapters" />
89+
<img src="./assets/sopify-product-form-release-en.svg" width="900" alt="Sopify Product Form — host executes, skill guides, assets preserved, any host resumes" />
7190
</div>
7291

7392
The host LLM executes. Sopify preserves auditable development assets — plans, decisions, handoffs, and verification evidence — in `.sopify/`, accessible across sessions, hosts, and teammates.
@@ -79,6 +98,14 @@ How Sopify achieves stability and quality:
7998
- **Resumes from where you stopped** — the host reads the current plan, picks up the last handoff, and checks what's already been verified before continuing
8099
- **Runtime retired; workflow retained** — the analyze → design → develop → finalize workflow is unchanged; what changed is that rules live in files, not a runtime process
81100

101+
## Architecture Details
102+
103+
For readers who want the internal layering behind the product form, the technical structure is below.
104+
105+
<div align="center">
106+
<img src="./assets/sopify-architecture.svg" width="760" alt="Sopify Architecture — protocol kernel + default workflow + knowledge layer" />
107+
</div>
108+
82109
## Installation
83110

84111
Audit-first install:

‎README.zh-CN.md‎

Lines changed: 25 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,31 +2,38 @@
22

33
<div align="center">
44

5-
**先问再写、随时恢复的 AI 编程**
5+
**可恢复的 AI 编程 — 先问再写，方案跟着项目走**
66

7-
[![许可证](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)
8-
[![文档](https://img.shields.io/badge/docs-CC%20BY%204.0-green.svg)](./LICENSE-docs)
9-
[![版本](https://img.shields.io/badge/version-2026--06--10.191940-orange.svg)](#版本历史)
10-
[![欢迎PR](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING_CN.md)
7+
[![许可证](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge)](./LICENSE)
8+
[![文档](https://img.shields.io/badge/docs-CC%20BY%204.0-green.svg?style=for-the-badge)](./LICENSE-docs)
9+
[![版本](https://img.shields.io/badge/version-2026--06--13.221525-orange.svg?style=for-the-badge)](#版本历史)
10+
[![欢迎PR](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge)](./CONTRIBUTING_CN.md)
11+
12+
[![Codex](https://img.shields.io/badge/host-Codex-4A9EFF.svg?style=for-the-badge)](#快速开始)
13+
[![Claude](https://img.shields.io/badge/host-Claude-CC785C.svg?style=for-the-badge)](#快速开始)
14+
[![Qoder](https://img.shields.io/badge/host-Qoder-7C3AED.svg?style=for-the-badge)](#快速开始)
15+
[![Copilot](https://img.shields.io/badge/host-Copilot-000000.svg?style=for-the-badge)](#快速开始)
1116

1217
[English](./README.md) · 简体中文 · [快速开始](#快速开始) · [贡献者](./CONTRIBUTORS.md)
1318

1419
</div>
1520

1621
<div align="center">
17-
<img src="./assets/sopify-cover-cn.jpg" width="660" alt="Sopify — 先问再写、随时恢复的 AI 编程" />
22+
<img src="./assets/sopify-cover-cn.jpg" width="660" alt="Sopify — 可恢复的 AI 编程，先问再写，方案跟着项目走" />
1823
</div>
1924

2025
---
2126

22-
AI 工具写代码很快。但没搞清楚需求就动手，快就变成了返工。Sopify 是 AI 编程的开发过程协议层——把方案、决策、交接和验证记录沉淀成项目资产，让任务能停、能接、能查。
27+
AI 工具写代码很快。但在事实没搞清、关键决策还没拍板前就直接动手，快就会变成返工。Sopify 是 AI 编程的开发过程协议层：在托管流程里，需求不全或决策未定时，宿主会先追问，再写代码。
28+
29+
Sopify 把方案和验证收据保存在 `.sopify/` 中，作为可纳入 git 的项目文件；只有恢复用的本地指针不进 git。换一个宿主打开同一个仓库，它会读取这些文件，从上次停下的地方继续。
2330

2431
无需新编辑器、无需新 CLI。安装到你已有的宿主：Codex、Claude、Qoder、Copilot 均支持。
2532

2633
**设计原则：**
2734

2835
- **不确定就停下** — 需求不全时先追问，再动手
29-
- **随时恢复** — 方案、决策、验证记录都持久保存在 `.sopify/` 里；换宿主、换机器、换人接手都能从项目状态继续
36+
- **随时恢复** — 方案和验证收据都持久保存在 `.sopify/` 里；换宿主、换机器、换人接手都能从项目状态继续
3037
- **决策留痕** — 方案、取舍、审查持久保存在 `.sopify/`
3138

3239
**Sopify 主要在防什么：**
@@ -76,10 +83,10 @@ curl -fsSL https://github.com/evidentloop/sopify/releases/latest/download/instal
7683
<img src="./assets/readme-visuals/sopify-scene-decision.jpg" width="720" alt="决策留痕 可追溯" />
7784
</div>
7885

79-
## 架构
86+
## 产品形态
8087

8188
<div align="center">
82-
<img src="./assets/sopify-architecture.svg" width="760" alt="Sopify 架构 — 协议内核 + 工作流 + 宿主适配" />
89+
<img src="./assets/sopify-product-form-release.svg" width="900" alt="Sopify 产品形态 — 宿主执行、技能引导、资产留存、任意宿主接续" />
8390
</div>
8491

8592
宿主 LLM 负责执行。Sopify 把 AI 开发过程中的审计资产——方案、决策、交接、验证证据——持久保留在 `.sopify/` 中，跨 session、宿主和团队成员均可访问。
@@ -91,6 +98,14 @@ Sopify 靠四件事做到稳定可控、质量可靠：
9198
- **从上次停下的地方继续** — 宿主读取当前方案、上次交接记录和已验证内容，然后接着干
9299
- **Runtime 已退场；工作流保留** — analyze → design → develop → finalize 流程不变；变的是规则活在文件里，不再依赖 runtime 进程
93100

101+
## 架构细节
102+
103+
想了解产品形态背后的内部层次，可以看下面的技术结构图。
104+
105+
<div align="center">
106+
<img src="./assets/sopify-architecture.svg" width="760" alt="Sopify 架构 — 协议内核 + 默认工作流 + 知识层" />
107+
</div>
108+
94109
## 安装说明
95110

96111
审查优先安装：

‎assets/readme-visuals/sopify-scene-ask-en.jpg‎

337 KB
Loading

‎assets/readme-visuals/sopify-scene-ask.jpg‎

177 KB
Loading

‎assets/readme-visuals/sopify-scene-cross-host-en.jpg‎

275 KB
Loading

0 commit comments

Comments
 (0)