scene-capability-engine 3.3.26 → 3.4.5

package/README.zh.md

@@ -3,650 +3,149 @@
 [![npm version](https://badge.fury.io/js/scene-capability-engine.svg)](https://badge.fury.io/js/scene-capability-engine)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> **⚠️ 重要说明**: `scene-capability-engine`（`sce`）是一个 **npm 包和 CLI 工具**，用于 Spec 驱动开发。  
-> 主命令为 `sce`，兼容别名保留用于迁移。
-
-**SCE（场景能力引擎）是一个面向 AI Agent 的本体感知场景编排引擎**，覆盖 plan、generate、patch、verify、release 全流程。
+**SCE 是面向 AI 原生软件交付的场景能力引擎。**  
+它提供从 `goal -> scene -> spec -> patch -> verify -> release` 的可控闭环。
 
 [English](README.md) | 简体中文
 
 ---
 
-## 什么是 sce？
-
-**SCE（场景能力引擎）是一个面向 AI 辅助开发的本体感知场景编排引擎。** 它将项目信息组织成结构化 Spec（需求 → 设计 → 任务），并通过 plan → generate → patch → verify → release 的流程路由执行。
-
-把 sce 想象成 **AI 助手的图书管理员** - 它组织和呈现项目上下文，让你的 AI 工具准确知道你在构建什么、为什么构建以及如何构建。
-
-### 工作原理
-
-```mermaid
-graph LR
-    A[你创建 Spec] --> B[sce 组织上下文]
-    B --> C[AI 工具读取上下文]
-    C --> D[AI 生成更好的代码]
-```
-
-1. **你创建 Spec** - 在结构化的 markdown 文件中编写需求、设计和任务
-2. **sce 组织上下文** - 导出为 AI 工具优化的格式
-3. **AI 工具读取上下文** - 你的 AI 助手理解项目结构
-4. **AI 生成更好的代码** - 符合你设计和需求的代码
-
-### sce 不是什么
-
-- ❌ **不是代码生成器** - sce 不写代码；你的 AI 工具写代码
-- ❌ **不是 IDE** - sce 与你现有的开发工具配合使用
-- ❌ **不是特定 AI 工具** - 适用于 Claude、Cursor、Windsurf、Copilot 等任何 AI 工具
-- ❌ **不是文档的替代品** - 它是组织项目上下文的结构化方式
-
-### 谁应该使用 sce？
-
-- ✅ 使用 AI 编码助手的开发者（Claude、Cursor、Copilot 等）
-- ✅ 需要结构化项目文档的团队
-- ✅ 构建需要清晰需求和设计的功能的任何人
-- ✅ 受益于 Spec 驱动开发的项目
-
-## 为什么 sce 更有优势
+## 为什么用 SCE
 
-| 优势点 | sce 能力 | 实际收益 |
-| --- | --- | --- |
-| 结构化先行 | 需求 → 设计 → 任务 + gate 检查 | 降低返工和需求漂移 |
-| 自动闭环交付 | 单命令闭环（`auto close-loop`） | 不再分步骤等待人工确认 |
-| 多 Agent 扩展 | DAG 编排（`orchestrate run/status/stop`） | 并行交付，不再手工开多终端 |
-| 自动主从拆分 | 目标自动拆成 Master/Sub Spec 并建立依赖 | 复杂需求自动转成可并行执行计划 |
-| 程序级自愈闭环 | `auto close-loop-program` 自动恢复 + 策略记忆 | 失败/部分失败会自动续跑，直到有界收敛 |
-| 队列驱动自治执行 | `auto close-loop-controller` 持续消费目标队列 | 程序级积压目标无需人工反复触发 |
-| 自治收敛治理 | Program Gate（最小成功率 + 最大风险）+ 审计 JSON 导出 | 完成结果可按策略验收且全程可追溯 |
-| 结果可量化 | KPI 自动化（`value metrics snapshot/baseline/trend`） | 周度趋势可追踪、可审计 |
-| 工具无锁定 | 兼容 Claude/Cursor/Windsurf/Copilot | 团队可保留现有 AI 工具链 |
-| 治理内建 | 文档治理、锁机制、审计、环境/工作区管理 | 协作更稳定，过程可回放 |
-
-### 90 秒价值验证
-
-```bash
-# 1) 在当前仓库启用 sce
-sce adopt
-
-# 2) 打开主场景会话
-sce studio plan --scene scene.demo --from-chat session-demo --goal "demo workflow bootstrap" --json
-
-# 3) 生成 Spec 工作流草稿
-sce spec bootstrap --name 01-00-demo-feature --scene scene.demo --non-interactive
+SCE 面向希望让 AI Agent 端到端推进交付、同时保持治理可控的团队。
 
-# 4) 生成 KPI 输入样例
-sce value metrics sample --out ./kpi-input.json --json
-
-# 5) 产出机器可读 KPI 快照
-sce value metrics snapshot --input ./kpi-input.json --json
-```
+- 以 Spec 先行，减少需求漂移和返工。
+- 从单任务执行扩展到多 Agent 程序级编排。
+- 通过强制门禁、ontology 校验、发布证据避免“看起来完成”。
+- 通过本地时间线快照保护过程资产，不只依赖 Git 推送。
 
 ---
 
-## 快速开始
-
-### 最简单的方式（30 秒）⚡
-
-**只需告诉你的 AI：**
-
-```
-安装 sce 并用它以 Spec 驱动开发的方式管理这个项目。
-```
-
-**你的 AI 会：**
-1. 全局安装 sce（`npm install -g scene-capability-engine`）
-2. 在项目中采用它（`sce adopt`）
-3. 阅读方法论指南（`.sce/README.md`）
-4. 按照 Spec 驱动方式开始工作
+## 核心能力矩阵
 
-**就这样！** 你的 AI 处理一切。不需要手动步骤。
+| 能力 | SCE 提供什么 | 结果 |
+| --- | --- | --- |
+| Scene + Spec 模型 | 场景主会话治理 + Spec 生命周期（需求/设计/任务） | 长周期 AI 上下文稳定 |
+| Studio 工作流 | `studio plan -> generate -> apply -> verify -> release` | 对话到发布路径结构化 |
+| 自动闭环交付 | `auto close-loop`、`close-loop-program`、`close-loop-controller` | 无人值守有界收敛 |
+| 多 Agent 编排 | DAG 调度、重试、429 自适应并行 | 并行执行稳定可控 |
+| 领域/本体治理 | problem-domain chain + scene template + gate 校验 | 降低语义回归 |
+| 问题评估路由 | 分阶段风险/证据/就绪度评分 + 强制策略 | `apply/release` 可控阻断，执行路径自适应 |
+| 本地时间线安全 | `timeline save/auto/list/show/restore/push` + 关键节点自动打点 | 本地历史可回放可恢复 |
+| Errorbook 修复体系 | 本地 + 注册表错题库 + 发布门禁 | 定位更快、修复更稳 |
+| 发布治理 | git 管理门禁、errorbook 门禁、handoff preflight、tag 发布链路 | 可审计、可复现发布 |
 
 ---
 
-### 分步指南（如果你想了解细节）📋
-
-<details>
-<summary><b>点击展开详细步骤</b></summary>
-
-#### 步骤 1：安装 sce（30 秒）
+## 3 分钟快速上手
 
 ```bash
+# 1) 安装
 npm install -g scene-capability-engine
-```
 
-验证安装：
-```bash
-sce --version
-```
-
-#### 步骤 2：在项目中采用 sce（30 秒）
-
-导航到项目目录并运行：
-
-```bash
-cd your-project
+# 2) 在项目中启用
 sce adopt
-```
-
-这会创建一个 `.sce/` 目录，包含：
-- `README.md` - 给 AI 的项目开发指南
-- `specs/` - Spec 存放位置
-- `steering/` - 开发规则（可选）
-
-#### 步骤 3：告诉 AI 项目的开发方法（30 秒）
 
-**在你的 AI 工具中（Cursor、Claude、Windsurf 等），说：**
+# 3) 打开主场景会话
+sce studio plan --scene scene.demo --from-chat session-demo --goal "bootstrap first feature" --json
 
+# 4) 生成并执行一个 Spec
+sce spec bootstrap --name 01-00-first-feature --scene scene.demo --non-interactive
+sce spec pipeline run --spec 01-00-first-feature --scene scene.demo
 ```
-请阅读 .sce/README.md 了解项目的开发方法。
-```
-
-**你的 AI 会学到：**
-- 这个项目遵循 Spec 驱动开发
-- 每个功能都从 Spec 开始（需求 + 设计 + 任务）
-- 如何按照这个方法论工作
-- 何时使用 sce 命令
 
-#### 步骤 4：开始构建功能
+需要全自动推进时：
 
-**自然地让 AI 实现功能：**
-
-```
-我需要一个用邮箱和密码登录的功能。
+```bash
+sce auto close-loop "deliver customer + order + inventory baseline"
 ```
 
-**你的 AI 会自动：**
-1. 创建包含需求、设计和任务的 Spec
-2. 按照 Spec 实现
-3. 随着工作进展更新任务状态
-4. 内部使用 sce 命令（你不需要运行它们）
-
-**示例对话：**
-- **你**："我需要用邮箱和密码登录的功能"
-- **AI**："我会为此创建一个 Spec。让我定义需求..."
-- **AI**："这是设计... 现在我会实现任务 1.1..."
-- **AI**："任务 1.1 完成。继续任务 1.2..."
-
-</details>
-
 ---
 
-**关键洞察：** 你不是"使用 sce" - 你的项目"遵循 Spec 驱动方法论"，sce 帮助执行它。AI 为你处理所有 sce 命令。
+## 推荐使用路径
 
-### 步骤 5：下一步（30 秒）
-
-- 📖 阅读[快速开始指南](docs/zh/quick-start.md)获取详细示例
-- 🔧 查看你的工具集成指南：[Cursor](docs/zh/tools/cursor-guide.md) | [Claude](docs/zh/tools/claude-guide.md) | [Windsurf](docs/zh/tools/windsurf-guide.md)
-- 💡 了解[集成模式](docs/integration-modes.md)
-
----
-
-## 核心概念
-
-### Spec
-
-**Spec** 是功能或项目组件的结构化描述。每个 Spec 包含：
-
-- **需求** (`requirements.md`) - 你要构建什么以及为什么
-- **设计** (`design.md`) - 如何构建（架构、API、组件）
-- **任务** (`tasks.md`) - 分步实现清单
-
-### 上下文导出
-
-**上下文导出**将你的 Spec 转换为 AI 工具优化的格式。它包括：
-- 所有需求、设计决策和任务
-- 项目结构和约定
-- Steering 规则（可选）用于 AI 行为
-
-### 集成模式
-
-sce 支持三种与 AI 工具协作的方式：
-
-1. **工作区直连集成** - AI 工具直接在你的工作区访问 sce
-2. **手动导出** - 你导出并粘贴上下文（Claude、ChatGPT、Cursor）
-3. **Watch 模式** - 文件更改时自动更新上下文（所有工具）
-
-了解更多：[集成模式指南](docs/integration-modes.md)
-
----
-
-## 与 AI 工具集成
-
-sce 适用于任何 AI 编码助手。选择你的工具获取具体指导：
-
-### 流行的 AI 工具
-
-- **[Cursor](docs/zh/tools/cursor-guide.md)** - 带 AI 结对编程的 IDE
-- **[Claude Code](docs/zh/tools/claude-guide.md)** - Anthropic 的编码助手
-- **[Windsurf](docs/zh/tools/windsurf-guide.md)** - 支持命令执行的 AI 代理
-- **[VS Code + Copilot](docs/zh/tools/vscode-guide.md)** - GitHub Copilot 集成
-- **[通用 AI 工具](docs/zh/tools/generic-guide.md)** - 适用于任何 AI 助手
-
-### 集成工作流
-
-```mermaid
-sequenceDiagram
-    participant 你
-    participant AI工具
-    participant sce
-    你->>AI工具: "我有一个 user-login 的 Spec，实现任务 1.1"
-    AI工具->>sce: sce context export user-login
-    sce->>AI工具: Spec 内容（需求、设计、任务）
-    AI工具->>AI工具: 根据 Spec 生成代码
-    AI工具->>你: 这是实现
-    AI工具->>sce: 更新 tasks.md（标记任务完成）
+### 1) 功能交付（默认路径）
+```bash
+sce studio plan --scene scene.customer-order --from-chat session-20260302 --goal "optimize checkout"
+sce spec bootstrap --name 02-00-checkout-optimization --scene scene.customer-order --non-interactive
+sce spec domain coverage --spec 02-00-checkout-optimization --json
+sce spec gate run --spec 02-00-checkout-optimization --scene scene.customer-order --json
 ```
 
-**关键洞察：** 你留在 AI 工具中。AI 读取 Spec 并生成符合你设计的代码。
-
----
-
-## 文档
-
-### 入门指南
-- 📖 **[快速开始指南](docs/zh/quick-start.md)** - 详细的 5 分钟教程
-- 🤔 **[常见问题](docs/faq.md)** - 常见问题解答
-- 🔧 **[故障排除](docs/troubleshooting.md)** - 常见问题和解决方案
-
-### 核心指南
-- 📋 **[Spec 工作流](docs/spec-workflow.md)** - 深入理解 Spec
-- 🔢 **[Spec 编号策略](docs/zh/spec-numbering-guide.md)** - 如何为 Spec 编号
-- 📄 **[文档治理](docs/document-governance.md)** - 自动化文档管理
-- 🎭 **[场景运行时指南](docs/scene-runtime-guide.md)** - 模板引擎、质量流水线、Ontology、Moqui ERP
-- 🤖 **[多 Agent 协调指南](docs/multi-agent-coordination-guide.md)** - 多 Agent 并行协调
-- 📈 **[Value 可观测指南](docs/zh/value-observability-guide.md)** - KPI 快照、基线、趋势与门禁证据
-- 🔌 **[集成模式](docs/integration-modes.md)** - 三种集成 sce 的方式
-- 📝 **[命令参考](docs/command-reference.md)** - 所有 sce 命令
-
-### 工具特定指南
-- [Cursor 集成](docs/zh/tools/cursor-guide.md)
-- [Claude Code 集成](docs/zh/tools/claude-guide.md)
-- [Windsurf 集成](docs/zh/tools/windsurf-guide.md)
-- [VS Code + Copilot 集成](docs/zh/tools/vscode-guide.md)
-- [通用 AI 工具](docs/zh/tools/generic-guide.md)
-
-### 示例
-- [API 功能示例](docs/examples/add-rest-api/) - RESTful API Spec
-- [UI 功能示例](docs/examples/add-user-dashboard/) - React 仪表板 Spec
-- [CLI 功能示例](docs/examples/add-export-command/) - CLI 命令 Spec
-
-### 高级主题
-- [采用指南](docs/adoption-guide.md) - 在现有项目中采用 sce
-- [升级指南](docs/upgrade-guide.md) - 版本升级说明
-- [发布归档](docs/zh/releases/README.md) - 版本化发布说明与验证报告入口
-- [GitHub Releases](https://github.com/heguangyong/scene-capability-engine/releases) - 最新发布版本与发布资产
-- [发布检查清单](docs/zh/release-checklist.md) - 可重复执行的发版前核验流程
-- [手动工作流](docs/manual-workflows-guide.md) - 分步工作流
-- [开发者指南](docs/developer-guide.md) - 贡献和扩展 sce
-
-### 完整文档
-- 📚 **[文档索引](docs/zh/README.md)** - 所有文档集中在一处
-
----
-
-## 主要功能
-
-### 当前基线能力
-- **默认 preflight 硬门禁**：发布流程强制执行 `sce auto handoff preflight-check --require-pass --json`，未通过即阻断发布。
-- **接管优先执行**：项目采用 sce 后，默认按自治/编排方式端到端推进，不再依赖逐步人工确认。
-- **Tag 驱动发版**：向 GitHub 推送 `v*` tag 即触发自动测试、发布证据门禁与 npm 发布流程。
-
-### Autonomous Control（自动闭环）🚀
-- **自动闭环推进**：`sce auto close-loop "<目标>"` 从目标拆分到编排完成全程自动推进
-- **自动主从拆分**：自动生成 Master/Sub Spec 组合、依赖关系与 Agent 分配
-- **语义分解 + 实时状态流**：按目标语义自动归类拆分，并实时输出编排进度（可用 `--no-stream` 关闭）
-- **会话恢复与归档治理**：支持 `--resume interrupted`（或 `--resume latest`）续跑，并可用 `sce auto session list/prune`、`sce auto batch-session list/prune`、`sce auto controller-session list/prune` 管理会话归档
-- **终态收敛**：输出统一执行结果（completed/failed/stopped），避免中途等待人工逐步确认
-
-### Spec 驱动开发
-使用需求 → 设计 → 任务工作流结构化你的工作
-
-### KPI 自动化与可观测 🚀
-- **统一指标契约**：从 `metric-definition.yaml` 加载并校验 KPI 定义
-- **周快照流水线**：生成包含风险级别和审计原因的 machine-readable 快照
-- **基线与趋势分析**：基于历史快照生成 baseline，并自动识别连续恶化趋势
-- **门禁可复用摘要**：输出 Day30/Day60 可直接消费的 summary 与证据路径
-- **CLI 命令**：`value metrics sample`、`value metrics snapshot`、`value metrics baseline`、`value metrics trend`，支持 `--json`
-
-### 多工作区管理 🚀
-- **工作区注册表**：从单一位置管理多个 sce 项目
-- **快速切换**：无需目录导航即可在项目间切换
-- **数据原子性**：单一数据源（`~/.sce/workspace-state.json`）
-- **跨平台**：Windows/Linux/macOS 一致的路径处理
-- **自动迁移**：从旧版工作区格式无缝升级
-
-### 环境配置管理 🚀
-- **环境注册表**：管理多个环境配置（dev, test, staging, prod）
-- **快速切换**：自动备份的环境切换
-- **自动备份**：每次切换前创建时间戳备份
-- **回滚支持**：即时恢复上一个环境配置
-- **验证功能**：切换后验证环境配置
-- **命令执行**：在特定环境上下文中运行命令
-- **跨平台**：在 Windows、Linux 和 macOS 上无缝工作
-
-### Moqui ERP 集成 🚀
-- **Moqui ERP 适配器**: 将 sce 场景运行时连接到 Moqui ERP 实例
-  - `MoquiClient` — 支持 JWT 认证生命周期（登录、刷新、重登录、登出）和重试逻辑的 HTTP 客户端
-  - `MoquiAdapter` — 处理 `spec.erp.*` 和 `moqui.*` 引用的绑定处理器，支持实体 CRUD、服务调用、屏幕发现
-- **场景模板提取器**（v1.40.0）: 分析 Moqui 资源，识别业务模式，生成可复用场景模板
-  - 按 Header/Item 后缀模式分组实体（如 OrderHeader + OrderItem → 复合模式）
-  - 基于模式的清单生成，包含治理合约
-- **CLI 命令**: `scene connect`、`scene discover`、`scene extract`，支持 `--json` 输出
-
-### 多 Agent 并行协调 🚀
-- **Agent 注册表**: 基于 MachineIdentifier 的 Agent 生命周期管理，心跳监控和不活跃清理
-- **任务锁管理器**: 基于文件的任务锁定，原子操作，单 Agent 向后兼容
-- **任务状态存储**: 并发安全的任务状态更新，指数退避重试
-- **Steering 文件锁**: 写入串行化，pending 文件降级回退
-- **合并协调器**: 每个 Agent 独立 Git 分支（`agent/{agentId}/{specName}`），冲突检测，自动合并
-- **中央协调器**: 基于依赖的就绪任务计算，任务分配，进度跟踪
-- **零开销**: 单 Agent 模式下所有组件为无操作（完全向后兼容）
-
-[了解更多多 Agent 协调 →](docs/multi-agent-coordination-guide.md)
-
-### Agent 编排器 🚀
-- **自动化多 Agent Spec 执行**: 一条命令替代手工开多个终端分配 Spec 给 Codex Agent
-- **DAG 依赖调度**: 分析 Spec 间依赖关系，拓扑排序计算执行批次
-- **并行执行**: 通过 Codex CLI 子进程同时运行多个 Spec（`--max-parallel` 控制并行度）
-- **失败传播**: 失败 Spec 的下游依赖自动标记为 skipped
-- **重试机制**: 可配置的失败自动重试
-- **实时监控**: 跟踪每个 Spec 状态和整体编排进度
-- **优雅终止**: 干净停止所有子 Agent（SIGTERM → SIGKILL）
-- **可配置**: 通过 `.sce/config/orchestrator.json` 配置 Codex 命令、参数、并行度、超时、重试次数
-
-**快速开始**:
+### 2) 程序级自动交付
 ```bash
-# 并行运行 3 个 Spec
-sce orchestrate run --specs "spec-a,spec-b,spec-c" --max-parallel 3
-
-# 查看编排进度
-sce orchestrate status
-
-# 停止所有子 Agent
-sce orchestrate stop
+sce auto close-loop-program "stabilize order lifecycle and release governance" --program-govern-until-stable --json
 ```
 
-**推荐 Codex 编排配置（`.sce/config/orchestrator.json`）**:
-```json
-{
-  "agentBackend": "codex",
-  "maxParallel": 3,
-  "timeoutSeconds": 900,
-  "maxRetries": 2,
-  "rateLimitMaxRetries": 6,
-  "rateLimitBackoffBaseMs": 1000,
-  "rateLimitBackoffMaxMs": 30000,
-  "rateLimitAdaptiveParallel": true,
-  "rateLimitParallelFloor": 1,
-  "rateLimitCooldownMs": 30000,
-  "apiKeyEnvVar": "CODEX_API_KEY",
-  "codexArgs": ["--skip-git-repo-check"],
-  "codexCommand": "npx @openai/codex"
-}
+### 3) 本地历史安全（时间线）
+```bash
+sce timeline save --summary "before risky refactor"
+sce timeline list --limit 20
+sce timeline restore <snapshot-id>
+sce timeline push origin main
 ```
 
-如果你已全局安装 Codex CLI，可将 `"codexCommand"` 改为 `"codex"`。
-可通过 `rateLimit*` 配置吸收 429/too-many-requests 等限流抖动，避免编排流程卡死。
-
-### Spec 级 Steering 与上下文同步 🚀
-- **Spec Steering (L4)**: 每个 Spec 独立的 `steering.md`，包含约束、注意事项、决策记录 — 跨 Agent 零冲突
-- **Steering 加载器**: 统一 L1-L4 四层 Steering 加载，优先级合并
-- **上下文同步管理器**: 多 Agent 友好的 CURRENT_CONTEXT.md，结构化 Spec 进度表，并发安全更新
-- **Spec 生命周期管理器**: 状态机（planned → assigned → in-progress → completed → released），自动完成检测
-- **同步屏障**: Agent 切换 Spec 时的同步检查 — 未提交更改检测 + Steering 重新加载
-- **Coordinator 集成**: 任务完成时自动检测 Spec 完成，任务分配时运行同步屏障
-
-### 场景 Ontology 增强 🚀
-- **OntologyGraph**: 绑定引用语义关系图（depends_on、composes、extends、produces）
-- **Action Abstraction**: 每个绑定的 intent、preconditions、postconditions，提升 AI 可读性
-- **Data Lineage**: governance_contract 中的数据血缘追踪（source → transform → sink）
-- **Agent-Ready Metadata**: `agent_hints` 字段（summary、complexity、duration、permissions、sequence）
-- **Agent Readiness 评分**: 质量评分新增可选加分维度（最高 +10 分）
-- **CLI 命令**: `scene ontology show|deps|validate|actions|lineage|agent-info`，支持 `--json`
-
-### 场景模板质量流水线 🚀
-- **模板 Lint 引擎**: 10 类质量检查（清单完整性、绑定引用、治理合约、一致性、变量、文档、Action Abstraction、Data Lineage、Agent Hints）
-- **质量评分计算器**: 4 维度评分 + agent_readiness 加分（合约有效性、lint 通过率、文档质量、治理完整性 + Agent Readiness 最高 +10），0-100+ 分制
-- **一站式贡献流水线**: 验证 → Lint → 评分 → 预览 → 发布，一条命令完成
-- **CLI 命令**: `scene lint`、`scene score`、`scene contribute`，支持 `--strict`、`--dry-run`、`--skip-lint`、`--json`
-
-### 场景模板引擎 🚀
-- **模板变量 Schema**: 在 scene-package.json 中定义类型化变量（string, number, boolean, enum, array）及验证规则
-- **多文件渲染**: 递归模板处理，支持 `{{variable}}` 替换、`{{#if}}` 条件、`{{#each}}` 循环
-- **三层继承**: L1-能力层 / L2-领域层 / L3-实例层包层级结构，支持 schema 和文件合并
-- **CLI 命令**: `scene template-validate`、`scene template-resolve`、`scene template-render`，支持 `--json` 输出
-
-### DevOps 集成基础 🚀
-- **运维 Spec 管理**：标准化运维文档（部署、监控、故障排查等）
-- **渐进式 AI 自主**：L1-L5 接管级别，逐步实现 AI 运维控制
-- **审计日志**：基于 SHA-256 的防篡改审计追踪
-- **反馈集成**：自动化用户反馈处理和分析
-- **权限管理**：基于环境的安全控制（开发、测试、预生产、生产）
-- **运维验证**：完整的 spec 验证和清晰的错误报告
-
-### 文档治理
-- 自动化文档生命周期管理
-- 强制执行清洁项目结构
-- 临时文件清理
-- 产物组织
-- Git hooks 合规性检查
-
-### 多用户协作
-- 团队成员的个人工作空间
-- 任务认领和跟踪
-- 工作空间同步
-
-### 跨工具兼容性
-为 Claude Code、Cursor、Windsurf、Copilot 等导出上下文
-
-### Watch 模式自动化
-自动文件监控和上下文更新
-
-### 质量增强
-- 文档质量评分（0-10 分）
-- 智能改进建议
-- 专业标准执行
-
-### 多语言支持
-英文和中文界面
+### 4) 发布基线
+```bash
+sce auto handoff preflight-check --require-pass --json
+git tag -a vX.Y.Z -m "vX.Y.Z"
+git push origin vX.Y.Z
+```
 
 ---
 
-## 命令概览
+## AI Agent 适配
 
-```bash
-# 项目设置
-sce adopt                          # 在现有项目中采用 sce
-sce create-spec <name>             # 兼容旧版：仅创建空 Spec 目录
-
-# 自动闭环主从编排（单命令）
-sce auto close-loop "<目标>"        # 自动拆分 Master/Sub Spec 并推进到完成态
-sce auto close-loop --resume interrupted # 从最近一个未完成 close-loop 会话续跑
-sce auto close-loop 继续           # 简写：续跑最近一个未完成 close-loop 会话
-sce auto continue                  # 快捷命令：续跑最近一个未完成 close-loop 会话
-sce auto close-loop "<目标>" --dry-run --json  # 仅预览拆分与依赖计划
-sce auto close-loop-program "<目标>" --program-govern-until-stable --program-govern-use-action 1 --json # 程序级自动恢复 + 治理循环（含 remediation action 执行）直到稳定
-sce auto close-loop-controller .sce/auto/program-queue.lines --wait-on-empty --dequeue-limit 2 --json # 队列驱动自治控制器，持续处理广义目标积压
-sce auto close-loop-controller --controller-resume latest --json # 从最近一次 controller 检查点恢复自治推进
-sce auto controller-session list --limit 50 --json # 查看持久化 close-loop-controller 摘要会话
-sce auto controller-session prune --keep 20 --older-than-days 14 --dry-run --json # 按保留策略清理旧 controller 摘要
-sce auto observability snapshot --days 14 --json # 统一自治可观测快照（会话 + 治理 + 趋势）
-sce auto spec status 121-00-master --json # 面向 Agent 的结构化 Spec 状态接口
-sce auto spec instructions 121-02-sub-track --json # 面向 Agent 的 Spec 执行指令接口
-sce auto schema check --json # 检查自治归档 schema 兼容性
-sce auto schema migrate --apply --json # 回填/迁移自治归档 schema_version
-
-# Spec 工作流（推荐）
-sce spec bootstrap --name <spec> --scene <scene-id> --non-interactive # 生成初稿并绑定 scene 子会话
-sce spec pipeline run --spec <spec> --scene <scene-id>                 # 执行分阶段流程并自动归档子会话
-sce spec gate run --spec <spec> --scene <scene-id> --json              # 执行闸口并自动归档子会话
-sce spec bootstrap --specs "<spec-a,spec-b>" --max-parallel <N>  # 多 Spec 默认转 orchestrate
-sce spec pipeline run --specs "<spec-a,spec-b>" --max-parallel <N> # 多 Spec 默认转 orchestrate
-sce spec gate run --specs "<spec-a,spec-b>" --max-parallel <N>     # 多 Spec 默认转 orchestrate
-
-# Spec 会话治理默认规则
-# - spec bootstrap|pipeline run|gate run 必须绑定活动中的 scene 主会话
-# - 当存在多个活动 scene 时，必须显式传入 --scene <scene-id>
-# - 多 Spec orchestrate 回退路径同样按 scene 绑定并写入每个 spec 的子会话归档
-
-# 上下文管理
-sce context export <spec-name>     # 为 AI 工具导出上下文
-sce prompt generate <spec> <task>  # 生成任务特定提示
-
-# 模板注册表
-sce templates list --type <spec-scaffold|capability-template|runtime-playbook> --compatible-with <semver> --risk <low|medium|high|critical>
-sce templates search <keyword> --type <spec-scaffold|capability-template|runtime-playbook> --compatible-with <semver>
-sce templates show <template-path>  # 查看模板元数据与兼容契约
-sce templates update [--source <name>]
-
-# KPI 自动化与可观测
-sce value metrics sample --out <path> --json               # 生成 KPI 输入样例 JSON
-sce value metrics snapshot --input <path> --json          # 生成周度 KPI 快照 + gate 摘要
-sce value metrics baseline --from-history <N> --json      # 从最早 N 个快照生成 baseline
-sce value metrics trend --window <N> --json               # 基于最近 N 个快照分析趋势与风险
-sce auto kpi trend --weeks 8 --period week --json         # 聚合自动交付 KPI 趋势（支持周/日桶 + 异常信号）
-sce auto kpi trend --weeks 8 --period day --csv --out <path> # 以 CSV 导出自动 KPI 趋势
-sce auto kpi trend --weeks 8 --mode controller --json     # 仅查看 close-loop-controller 会话趋势
-
-# 工作区管理
-sce workspace create <name> [path] # 注册新工作区
-sce workspace list                 # 列出所有工作区
-sce workspace switch <name>        # 切换活动工作区
-sce workspace info [name]          # 显示工作区详情
-sce workspace remove <name>        # 删除工作区
-
-# 环境管理
-sce env list                       # 列出所有环境
-sce env switch <name>              # 切换到环境（自动备份）
-sce env info                       # 显示活动环境详情
-sce env register <config-file>     # 注册新环境
-sce env unregister <name>          # 删除环境
-sce env rollback                   # 回滚到上一个环境
-sce env verify                     # 验证当前环境
-sce env run "<command>"            # 在环境上下文中运行命令
-
-# 场景模板引擎
-sce scene template-validate --package <path>   # 验证模板变量 schema
-sce scene template-resolve --package <name>    # 解析继承链和合并 schema
-sce scene template-render --package <name> --values <json> --out <dir>  # 渲染模板文件
-
-# Moqui ERP 集成
-sce scene connect --config <path>              # 测试 Moqui ERP 实例连接
-sce scene discover --config <path>             # 发现 Moqui 实体、服务、屏幕
-sce scene extract --config <path> --out <dir>  # 从 Moqui 提取场景模板 (v1.40.0)
-
-# 场景模板质量流水线
-sce scene lint --package <path>                # Lint 场景包质量检查
-sce scene score --package <path>               # 计算质量评分 (0-100)
-sce scene contribute --package <path>          # 一站式验证 → lint → 评分 → 发布
-
-# 场景 Ontology
-sce scene ontology show --package <path>       # 显示 Ontology 图
-sce scene ontology deps --ref <ref>            # 查询依赖链
-sce scene ontology impact --ref <ref>          # 分析反向影响面
-sce scene ontology path --from <ref> --to <ref> # 查询最短关系路径
-sce scene ontology validate --package <path>   # 验证图一致性
-sce scene ontology actions --ref <ref>         # 显示 Action Abstraction
-sce scene ontology lineage --ref <ref>         # 显示数据血缘
-sce scene ontology agent-info --package <path> # 显示 Agent Hints
-
-# Agent 编排
-sce orchestrate run --specs "<spec列表>" --max-parallel <N>  # 启动多 Agent 编排
-sce orchestrate status                         # 查看编排进度
-sce orchestrate stop                           # 停止所有子 Agent
-
-# 说明：当使用 --specs 调用 sce spec bootstrap/pipeline run/gate run 时，会默认转到 orchestrate 模式，
-# 且仍要求绑定活动 scene 主会话（多活动 scene 时必须显式 --scene）
-
-# 发布基线（CI 默认）
-sce auto handoff preflight-check --require-pass --json  # 硬门禁：preflight 不通过则阻断发布
-git tag -a vX.Y.Z -m "vX.Y.Z"                          # 创建发布 tag
-git push origin vX.Y.Z                                  # 推送 tag，触发 GitHub Release + npm 自动发布
-
-# DevOps 运维
-sce ops init <project-name>        # 初始化运维 specs
-sce ops validate [<project>]       # 验证运维完整性
-sce ops audit [options]            # 查询审计日志
-sce ops takeover <action>          # 管理 AI 接管级别
-sce ops feedback <action>          # 管理用户反馈
-
-# 任务管理
-sce task claim <spec> <task-id>    # 认领任务
-sce task list <spec>               # 列出已认领任务
-
-# 文档治理
-sce docs diagnose                  # 检查文档合规性
-sce docs cleanup                   # 删除临时文件
-sce docs validate                  # 验证文档结构
-sce docs archive --spec <name>     # 组织 Spec 产物
-sce docs hooks install             # 安装 Git pre-commit hooks
-
-# 自动化
-sce watch start                    # 启动 watch 模式
-sce watch status                   # 检查 watch 状态
-
-# 项目信息
-sce status                         # 项目状态
-sce workflows                      # 列出可用工作流
-```
+SCE 对工具无锁定，可接入 Codex、Claude Code、Cursor、Windsurf、VS Code Copilot 等。
 
-查看[命令参考](docs/command-reference.md)获取完整文档。
+- 运行时上下文统一由 `.sce/` 管理（不依赖特定 IDE 隐藏目录）。
+- 会话治理默认场景优先：`1 scene = 1 primary session`。
+- Spec 执行作为子会话自动归档，支持跨轮次追踪。
+- 启动时会自动识别已接管项目并对齐接管基线默认配置。
+- 问题评估策略默认启用（`.sce/config/problem-eval-policy.json`），Studio 各阶段都会执行评估。
+- 错误处理默认进入完整 incident 闭环：每次记录先落到 staging 试错链路，verified/promoted 后自动收束归档。
+- 也可显式审计/修正接管基线：
+  - `sce workspace takeover-audit --json`
+  - `sce workspace takeover-apply --json`
 
 ---
 
-## 贡献与支持
-
-### 获取帮助
+## 文档导航
 
-- 📖 **文档**：从[快速开始指南](docs/zh/quick-start.md)开始
-- 🐛 **Bug 报告**：[GitHub Issues](https://github.com/heguangyong/scene-capability-engine/issues)
-- 💬 **讨论**：[GitHub Discussions](https://github.com/heguangyong/scene-capability-engine/discussions)
+建议先看：
 
-### 贡献
+- [快速开始](docs/zh/quick-start.md)
+- [命令参考](docs/command-reference.md)
+- [自动闭环指南](docs/autonomous-control-guide.md)
+- [场景运行时指南](docs/scene-runtime-guide.md)
+- [Value 可观测指南](docs/zh/value-observability-guide.md)
+- [多 Agent 协同指南](docs/multi-agent-coordination-guide.md)
+- [Errorbook 注册表指南](docs/errorbook-registry.md)
+- [文档总览](docs/zh/README.md)
 
-我们欢迎贡献！查看我们的[贡献指南](CONTRIBUTING.md)了解：
-- 代码贡献
-- 文档改进
-- Bug 报告和功能请求
-- 翻译帮助
+Moqui 方向：
 
-### 开发设置
-
-```bash
-git clone https://github.com/heguangyong/scene-capability-engine.git
-cd scene-capability-engine
-npm install
-npm link  # 用于本地开发
-npm test  # 运行测试
-```
+- [Moqui 模板核心库 Playbook](docs/moqui-template-core-library-playbook.md)
+- [Moqui 标准重建指南](docs/moqui-standard-rebuild-guide.md)
 
 ---
 
-## 许可证
+## 社区
 
-MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。
+- [GitHub Discussions](https://github.com/heguangyong/scene-capability-engine/discussions)
+- [GitHub Issues](https://github.com/heguangyong/scene-capability-engine/issues)
 
----
-
-## 致谢
+<img src="docs/images/wechat-qr.png" width="200" alt="微信群二维码">
 
-- 受 **西西弗斯** 神话和高贵奋斗概念的启发
-- 建立在务实的 **Spec 驱动开发** 方法论基础上
-- 受 **oh-my-opencode** 和 Ultrawork 宣言的影响
+扫码添加微信并备注 `sce` 入群。
 
 ---
 
-**准备好增强你的 AI 辅助开发了吗？** 🚀
+## License
 
-```bash
-npm install -g scene-capability-engine
-sce adopt
-sce studio plan --scene scene.demo --from-chat session-demo --goal "bootstrap first feature" --json
-sce spec bootstrap --name 01-00-my-first-feature --scene scene.demo --non-interactive
-```
+MIT，见 [LICENSE](LICENSE)。
 
 ---
 
-**版本**：3.3.17  
-**最后更新**：2026-02-26
-
-
+**版本**：3.4.5  
+**最后更新**：2026-03-02