feat: add vendored bundle control plane

Author: Li-Sanze

.github/workflows/ci.yml

@@ -35,7 +35,7 @@ jobs:
           python-version: "3.11"
 
       - name: Run runtime unit tests
-        run: python3 -m unittest tests/test_runtime.py
+        run: python3 -m unittest tests/test_runtime.py tests/test_installer.py
 
       - name: Run runtime smoke check
         run: bash scripts/check-runtime-smoke.sh

CHANGELOG.md

@@ -17,6 +17,8 @@ This changelog is maintained manually (not auto-generated).
 ### Added
 
 - Minimal KB bootstrap in `runtime/kb.py`, creating `project.md`, `wiki/overview.md`, `user/preferences.md`, and `history/index.md` on first runtime execution.
+- New bundle manifest contract in `runtime/manifest.py`, written to `.sopify-runtime/manifest.json` during bundle sync.
+- New runtime handoff contract in `runtime/handoff.py`, written to `.sopify-skills/state/current_handoff.json` for non-terminal routes.
 - New sub-skill `model-compare` (CN/EN) for configuration-driven multi-model parallel comparison with manual user selection.
 - New compare trigger contract:
   - Command: `~compare <question>`
@@ -25,16 +27,24 @@ This changelog is maintained manually (not auto-generated).
 - New GitHub Actions workflow `.github/workflows/ci.yml` to gate PR/Push with sync and version checks.
 - Default repo-local raw-input runtime entry `scripts/sopify_runtime.py` and plan-only helper `scripts/go_plan_runtime.py`.
 - Runtime bundle sync script `scripts/sync-runtime-assets.sh` for vendoring `.sopify-runtime/` into another repository.
+- One-command installer entry `scripts/install-sopify.sh` with a Python installer core and host adapters for `codex:zh-CN`, `codex:en-US`, `claude:zh-CN`, and `claude:en-US`.
 - Runtime smoke check script `scripts/check-runtime-smoke.sh`.
 - Runtime behavior test coverage in `tests/test_runtime.py`, including vendored bundle validation.
+- Installer test coverage in `tests/test_installer.py` for Codex/Claude sample install paths.
 
 ### Changed
 
+- Updated bundle sync, installer validation, and smoke checks to treat `.sopify-runtime/manifest.json` as a required control-plane artifact.
+- Updated runtime output to render `Next:` from the structured handoff contract before falling back to route-only copy.
+- Refactored runtime builtin-skill discovery to a catalog-first model via `runtime/builtin_catalog.py`, so vendored bundles no longer depend on scanning `Codex/Skills` or `Claude/Skills` trees.
+- Extended `SkillMeta` and external skill manifests with forward-compatible catalog fields: `entry_kind`, `handoff_kind`, `contract_version`, and `supports_routes`.
+- Added explicit builtin override policy in `runtime/skill_registry.py`: external skills can only replace builtin ids when `override_builtin: true` is declared.
 - Updated CN/EN AGENTS routing and command references to include `~compare` and `model-compare`.
 - Updated `README.md` and `README_EN.md` with:
   - 7-skill install verification list
   - Multi-model MVP quick start
   - Environment-variable-only API key setup (`export ...`, including `~/.zshrc` persistence guidance)
+  - Recommended one-command installer usage for host prompt setup + vendored bundle sync
 - Added MVP fallback rule: when no usable multi-model config exists, `~compare` / `对比分析：` should not fail and must fallback to single-model with a clear notice.
 - Clarified two-layer compare switches:
   - `multi_model.enabled` = feature-level gate

Claude/Skills/CN/CLAUDE.md

@@ -133,7 +133,8 @@ Next: {下一步提示}
  | `~go exec` | 执行已有方案 |
  | `~compare` | 多模型并发对比（默认含当前会话模型；可用模型数不足 2 时降级并给出原因） |
 
-说明：当前仓库若存在 `scripts/sopify_runtime.py`，原始输入应优先走该默认 repo-local runtime 入口；若 runtime 以 bundle 方式接入到其他仓库，则优先走 `.sopify-runtime/scripts/sopify_runtime.py`；仅在明确只走 `~go plan` 时使用对应的 `go_plan_runtime.py` helper。
+说明：当前仓库若存在 `scripts/sopify_runtime.py`，原始输入应优先走该默认 repo-local runtime 入口；若 runtime 以 bundle 方式接入到其他仓库，则宿主应优先读取 `.sopify-runtime/manifest.json` 决定入口，默认再回退到 `.sopify-runtime/scripts/sopify_runtime.py`；仅在明确只走 `~go plan` 时使用对应的 `go_plan_runtime.py` helper。
+说明：runtime 执行后，若存在 `.sopify-skills/state/current_handoff.json`，宿主应优先按其中的 `required_host_action`、`recommended_skill_ids` 与 `artifacts` 决定下一步；`Next:` 行仅作为面向人的摘要提示，不应作为唯一机器依据。
 
 **workflow-learning 主动记录策略：**
 ```yaml
@@ -283,6 +284,11 @@ progressive: 按需创建文件 (默认)
 | 轻量迭代 | 3-5 文件，清晰需求 | light 方案 + 执行 |
 | 完整开发 | >5 文件或架构变更 | 3 阶段完整流程 |
 
+**宿主接入约定：**
+- `Claude/Skills` 只承担提示层职责，不作为 vendored runtime 的机器契约来源。
+- vendored runtime 的机器入口以 `.sopify-runtime/manifest.json` 为准。
+- runtime 执行后的机器交接以 `.sopify-skills/state/current_handoff.json` 为准；仅当 handoff 缺失时才回退到输出文案中的 `Next:`。
+
 ---
 
 ## 阶段执行
@@ -411,9 +417,11 @@ scripts/sopify_runtime.py                    # 当前仓库默认原始输入入
 scripts/go_plan_runtime.py                   # 当前仓库用于 plan-only slice 的 helper
 .sopify-runtime/scripts/go_plan_runtime.py   # vendored plan-only helper
 scripts/model_compare_runtime.py             # ~compare 的运行时实现，不是默认通用入口
+.sopify-runtime/manifest.json                # vendored bundle 机器契约，宿主应优先读取
+.sopify-skills/state/current_handoff.json    # runtime 写出的结构化交接文件，宿主应优先读取
 ```
 
-说明：当前默认入口是 `scripts/sopify_runtime.py`；若以 bundle 方式接入则入口对应 `.sopify-runtime/scripts/sopify_runtime.py`；`go_plan_runtime.py` 只负责 plan-only；`~compare` 仍依赖宿主侧专用桥接。
+说明：当前默认入口是 `scripts/sopify_runtime.py`；若以 bundle 方式接入，优先按 `.sopify-runtime/manifest.json` 选入口，再回退到 `.sopify-runtime/scripts/sopify_runtime.py`；`go_plan_runtime.py` 只负责 plan-only；执行结束后宿主应优先读取 `.sopify-skills/state/current_handoff.json` 决定下一步；`~compare` 仍依赖宿主侧专用桥接。
 
 **配置文件：** `sopify.config.yaml` (项目根目录)
 

Claude/Skills/EN/CLAUDE.md

@@ -133,7 +133,8 @@ Complex Task (full 3 phases):
 | `~go exec` | Execute existing plan |
 | `~compare` | Multi-model parallel comparison (includes session default model by default; falls back with reasons when usable model count is below 2) |
 
-Note: when the current repository provides `scripts/sopify_runtime.py`, raw input should prefer that default repo-local runtime entry; when the runtime is vendored into another repository, prefer `.sopify-runtime/scripts/sopify_runtime.py`; use the matching `go_plan_runtime.py` helper only when you explicitly want the plan-only path.
+Note: when the current repository provides `scripts/sopify_runtime.py`, raw input should prefer that default repo-local runtime entry; when the runtime is vendored into another repository, the host should read `.sopify-runtime/manifest.json` first to choose the entry, and only then fall back to `.sopify-runtime/scripts/sopify_runtime.py`; use the matching `go_plan_runtime.py` helper only when you explicitly want the plan-only path.
+Note: after runtime execution, if `.sopify-skills/state/current_handoff.json` exists, the host should prioritize its `required_host_action`, `recommended_skill_ids`, and `artifacts` to decide the next step; the rendered `Next:` line is only a human-facing summary, not the sole machine contract.
 
 **workflow-learning proactive capture policy:**
 ```yaml
@@ -283,6 +284,11 @@ Semantic analysis routing:
 | Light Iteration | 3-5 files, clear requirements | Light plan + execution |
 | Full Development | >5 files or architectural changes | Full 3-phase workflow |
 
+**Host Integration Contract:**
+- `Claude/Skills` is prompt-layer guidance only; it is not the machine contract for the vendored runtime.
+- For vendored runtime entry selection, treat `.sopify-runtime/manifest.json` as the source of truth.
+- For post-run continuation, treat `.sopify-skills/state/current_handoff.json` as the source of truth and fall back to the rendered `Next:` text only when the handoff file is missing.
+
 ---
 
 ## Phase Execution
@@ -411,9 +417,11 @@ scripts/sopify_runtime.py                    # default repo-local raw-input entr
 scripts/go_plan_runtime.py                   # helper for the plan-only slice
 .sopify-runtime/scripts/go_plan_runtime.py   # vendored helper for the plan-only slice
 scripts/model_compare_runtime.py             # runtime implementation for ~compare, not the default generic entry
+.sopify-runtime/manifest.json                # vendored bundle machine contract; hosts should read this first
+.sopify-skills/state/current_handoff.json    # structured handoff written by the runtime; hosts should read this first after execution
 ```
 
-Note: the default entry is `scripts/sopify_runtime.py`; when vendored, the entry becomes `.sopify-runtime/scripts/sopify_runtime.py`; `go_plan_runtime.py` is only for plan-only; `~compare` still depends on a host-side dedicated bridge.
+Note: the default entry is `scripts/sopify_runtime.py`; when vendored, prefer `.sopify-runtime/manifest.json` to select the entry and fall back to `.sopify-runtime/scripts/sopify_runtime.py`; `go_plan_runtime.py` is only for plan-only; after execution the host should read `.sopify-skills/state/current_handoff.json` before trusting `Next:`; `~compare` still depends on a host-side dedicated bridge.
 
 **Configuration File:** `sopify.config.yaml` (project root)
 

Codex/Skills/CN/AGENTS.md

@@ -133,7 +133,8 @@ Next: {下一步提示}
  | `~go exec` | 执行已有方案 |
  | `~compare` | 多模型并发对比（默认含当前会话模型；可用模型数不足 2 时降级并给出原因） |
 
-说明：当前仓库若存在 `scripts/sopify_runtime.py`，原始输入应优先走该默认 repo-local runtime 入口；若 runtime 以 bundle 方式接入到其他仓库，则优先走 `.sopify-runtime/scripts/sopify_runtime.py`；仅在明确只走 `~go plan` 时使用对应的 `go_plan_runtime.py` helper。
+说明：当前仓库若存在 `scripts/sopify_runtime.py`，原始输入应优先走该默认 repo-local runtime 入口；若 runtime 以 bundle 方式接入到其他仓库，则宿主应优先读取 `.sopify-runtime/manifest.json` 决定入口，默认再回退到 `.sopify-runtime/scripts/sopify_runtime.py`；仅在明确只走 `~go plan` 时使用对应的 `go_plan_runtime.py` helper。
+说明：runtime 执行后，若存在 `.sopify-skills/state/current_handoff.json`，宿主应优先按其中的 `required_host_action`、`recommended_skill_ids` 与 `artifacts` 决定下一步；`Next:` 行仅作为面向人的摘要提示，不应作为唯一机器依据。
 
 **workflow-learning 主动记录策略：**
 ```yaml
@@ -283,6 +284,11 @@ progressive: 按需创建文件 (默认)
 | 轻量迭代 | 3-5 文件，清晰需求 | light 方案 + 执行 |
 | 完整开发 | >5 文件或架构变更 | 3 阶段完整流程 |
 
+**宿主接入约定：**
+- `Codex/Skills` 只承担提示层职责，不作为 vendored runtime 的机器契约来源。
+- vendored runtime 的机器入口以 `.sopify-runtime/manifest.json` 为准。
+- runtime 执行后的机器交接以 `.sopify-skills/state/current_handoff.json` 为准；仅当 handoff 缺失时才回退到输出文案中的 `Next:`。
+
 ---
 
 ## 阶段执行
@@ -411,9 +417,11 @@ scripts/sopify_runtime.py                    # 当前仓库默认原始输入入
 scripts/go_plan_runtime.py                   # 当前仓库用于 plan-only slice 的 helper
 .sopify-runtime/scripts/go_plan_runtime.py   # vendored plan-only helper
 scripts/model_compare_runtime.py             # ~compare 的运行时实现，不是默认通用入口
+.sopify-runtime/manifest.json                # vendored bundle 机器契约，宿主应优先读取
+.sopify-skills/state/current_handoff.json    # runtime 写出的结构化交接文件，宿主应优先读取
 ```
 
-说明：当前默认入口是 `scripts/sopify_runtime.py`；若以 bundle 方式接入则入口对应 `.sopify-runtime/scripts/sopify_runtime.py`；`go_plan_runtime.py` 只负责 plan-only；`~compare` 仍依赖宿主侧专用桥接。
+说明：当前默认入口是 `scripts/sopify_runtime.py`；若以 bundle 方式接入，优先按 `.sopify-runtime/manifest.json` 选入口，再回退到 `.sopify-runtime/scripts/sopify_runtime.py`；`go_plan_runtime.py` 只负责 plan-only；执行结束后宿主应优先读取 `.sopify-skills/state/current_handoff.json` 决定下一步；`~compare` 仍依赖宿主侧专用桥接。
 
 **配置文件：** `sopify.config.yaml` (项目根目录)
 

Codex/Skills/EN/AGENTS.md

@@ -133,7 +133,8 @@ Complex Task (full 3 phases):
 | `~go exec` | Execute existing plan |
 | `~compare` | Multi-model parallel comparison (includes session default model by default; falls back with reasons when usable model count is below 2) |
 
-Note: when the current repository provides `scripts/sopify_runtime.py`, raw input should prefer that default repo-local runtime entry; when the runtime is vendored into another repository, prefer `.sopify-runtime/scripts/sopify_runtime.py`; use the matching `go_plan_runtime.py` helper only when you explicitly want the plan-only path.
+Note: when the current repository provides `scripts/sopify_runtime.py`, raw input should prefer that default repo-local runtime entry; when the runtime is vendored into another repository, the host should read `.sopify-runtime/manifest.json` first to choose the entry, and only then fall back to `.sopify-runtime/scripts/sopify_runtime.py`; use the matching `go_plan_runtime.py` helper only when you explicitly want the plan-only path.
+Note: after runtime execution, if `.sopify-skills/state/current_handoff.json` exists, the host should prioritize its `required_host_action`, `recommended_skill_ids`, and `artifacts` to decide the next step; the rendered `Next:` line is only a human-facing summary, not the sole machine contract.
 
 **workflow-learning proactive capture policy:**
 ```yaml
@@ -283,6 +284,11 @@ Semantic analysis routing:
 | Light Iteration | 3-5 files, clear requirements | Light plan + execution |
 | Full Development | >5 files or architectural changes | Full 3-phase workflow |
 
+**Host Integration Contract:**
+- `Codex/Skills` is prompt-layer guidance only; it is not the machine contract for the vendored runtime.
+- For vendored runtime entry selection, treat `.sopify-runtime/manifest.json` as the source of truth.
+- For post-run continuation, treat `.sopify-skills/state/current_handoff.json` as the source of truth and fall back to the rendered `Next:` text only when the handoff file is missing.
+
 ---
 
 ## Phase Execution
@@ -411,9 +417,11 @@ scripts/sopify_runtime.py                    # default repo-local raw-input entr
 scripts/go_plan_runtime.py                   # helper for the plan-only slice
 .sopify-runtime/scripts/go_plan_runtime.py   # vendored helper for the plan-only slice
 scripts/model_compare_runtime.py             # runtime implementation for ~compare, not the default generic entry
+.sopify-runtime/manifest.json                # vendored bundle machine contract; hosts should read this first
+.sopify-skills/state/current_handoff.json    # structured handoff written by the runtime; hosts should read this first after execution
 ```
 
-Note: the default entry is `scripts/sopify_runtime.py`; when vendored, the entry becomes `.sopify-runtime/scripts/sopify_runtime.py`; `go_plan_runtime.py` is only for plan-only; `~compare` still depends on a host-side dedicated bridge.
+Note: the default entry is `scripts/sopify_runtime.py`; when vendored, prefer `.sopify-runtime/manifest.json` to select the entry and fall back to `.sopify-runtime/scripts/sopify_runtime.py`; `go_plan_runtime.py` is only for plan-only; after execution the host should read `.sopify-skills/state/current_handoff.json` before trusting `Next:`; `~compare` still depends on a host-side dedicated bridge.
 
 **Configuration File:** `sopify.config.yaml` (project root)
 

README.md

@@ -48,35 +48,28 @@
 
 ### 安装
 
-**Claude Code 用户：**
+**一键接入（推荐）：**
 
 ```bash
-# 中文版
-cp -r Claude/Skills/CN/* ~/.claude/
+# 当前目录作为目标仓库
+bash scripts/install-sopify.sh --target codex:zh-CN
 
-# 英文版
-cp -r Claude/Skills/EN/* ~/.claude/
+# 指定目标仓库
+bash scripts/install-sopify.sh --target claude:en-US --workspace /path/to/project
 ```
 
-**Codex CLI 用户：**
+当前支持的 `target`：
 
-```bash
-# 中文版
-cp -r Codex/Skills/CN/* ~/.codex/
-
-# 英文版
-cp -r Codex/Skills/EN/* ~/.codex/
-```
+- `codex:zh-CN`
+- `codex:en-US`
+- `claude:zh-CN`
+- `claude:en-US`
 
 说明：
 
-- 上述复制命令同步的是技能文档、模板和子技能目录，不会单独把仓库根目录下的 `runtime/` 与 `scripts/` 自动安装到目标项目
-- 如果要把 runtime 资产同步到另一个仓库，执行 `bash scripts/sync-runtime-assets.sh /path/to/project`，默认会在目标仓库生成一份自包含的 `.sopify-runtime/` bundle
-- 当前仓库内已经收口的 repo-local runtime 入口有两个：
-  - `scripts/sopify_runtime.py`：默认原始输入入口，直接交给 router 分流
-  - `scripts/go_plan_runtime.py`：plan-only helper，强制走 `~go plan`
-- `scripts/model_compare_runtime.py` 是 `~compare` 的运行时实现，不是默认通用 CLI 入口
-- 二次接入时不要只复制 `Codex/Skills/*` 或 `Claude/Skills/*`；应同时同步 `.sopify-runtime/` bundle
+- installer 会同时安装宿主提示层，并把 `.sopify-runtime/` bundle 同步到目标仓库
+- `--workspace` 可省略，默认使用当前目录
+- 该命令适合作为最终用户的一键接入入口
 
 ### 验证安装
 
@@ -89,7 +82,7 @@ cp -r Codex/Skills/EN/* ~/.codex/
 
 ### 二次接入 runtime bundle
 
-如果要在另一个仓库里直接复用这套 runtime：
+如果需要从维护者视角手工控制 bundle 同步过程，可以单独执行：
 
 ```bash
 # 1. 从当前仓库同步 runtime bundle
@@ -106,8 +99,11 @@ bash /path/to/project/.sopify-runtime/scripts/check-runtime-smoke.sh
 说明：
 
 - `.sopify-runtime/` 保持 `runtime/` + `scripts/` + `tests/` 的自包含布局
+- `.sopify-runtime/manifest.json` 是 bundle 的机器契约；宿主接入应优先读取 manifest，再回退到默认脚本路径
 - vendored 入口默认是 `.sopify-runtime/scripts/sopify_runtime.py`
 - plan-only helper 对应 `.sopify-runtime/scripts/go_plan_runtime.py`
+- builtin skill 发现由 `runtime/builtin_catalog.py` 负责，不依赖 bundle 内再携带 `Codex/Skills` 或 `Claude/Skills` 文档目录
+- 非闭环路由现在会写入 `.sopify-skills/state/current_handoff.json`，`Next:` 文案优先基于 handoff contract 渲染
 
 ### 首次使用
 
@@ -172,6 +168,8 @@ bash scripts/check-runtime-smoke.sh
   - `scripts/sopify_runtime.py`：默认原始输入入口
   - `scripts/go_plan_runtime.py`：plan-only helper
 - 已提供 `scripts/sync-runtime-assets.sh`，用于把 runtime bundle 同步到目标仓库的 `.sopify-runtime/`
+- bundle 同步后会生成 `.sopify-runtime/manifest.json`，用于描述入口、支持路由、builtin catalog 与 handoff 文件位置
+- runtime 现已真正写入 `.sopify-skills/state/current_handoff.json`，供宿主读取结构化下一步动作
 - `.sopify-runtime/` bundle 内已包含便携 `tests/test_runtime.py` 与 `scripts/check-runtime-smoke.sh`
 - 当前 `P1-A` 已落地：首次运行会 bootstrap 最小 KB 骨架，但还不包含选择性历史回收或 history 归档
 - 当前 KB 快照只读取根配置、manifest 与顶层目录，不做源码级扫描