xycld · Mar 18, 2026 · Mar 14, 2026 · Mar 14, 2026 · Mar 14, 2026 · Mar 14, 2026
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -0,0 +1,24 @@
+name: Publish
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: npm
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          registry-url: https://registry.npmjs.org
+      - run: npm ci
+      - run: npm run build
+      - run: npx vitest run
+      - run: npm publish --provenance --access public
diff --git a/.gitignore b/.gitignore
@@ -6,6 +6,7 @@
 !.prettierrc
 !.node-version
 !README.md
+!LICENSE
 !tsconfig.json
 !package.json
 !package-lock.json
@@ -21,10 +22,20 @@
 !examples/**
 !scripts/
 !scripts/**
+!tests/
+!tests/**
+!.github/
+!.github/**
+
+# Within allowed dirs, re-ignore all hidden directories then whitelist .svp/ and .github/
+**/.*/
+!**/.svp/
+!**/.svp/**
 !.github/
 !.github/**
 
 # Re-ignore generated/temp files within allowed dirs
+tests/e2e/report-*
 *.swp
 *.kate-swp
 *.swo

diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SVP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -20,7 +20,7 @@ L1  Code         最终实现
 
 ## 定位
 
-SVP 不自己调 AI API，不造编译器。SVP 是 AI 编码工具（Claude Code、Cursor 等）的**增强层**：
+SVP 不自己调 AI API，不造编译器。SVP 是 AI 编码工具（Claude Code、Cursor、Windsurf、Kimi Code、Codex、GitHub Copilot）的**增强层**：
 
 - **工具链**：`svp check`（校验）、store（读写）、hash（变更追踪）
 - **Skills**：基于五层数据模型生成结构化 context，喂给用户已有的 AI 工具
@@ -59,10 +59,6 @@ SVP 不自己调 AI API，不造编译器。SVP 是 AI 编码工具（Claude Cod
 
 详见 [check 错误码参考](docs/check-reference.md)。
 
-## svp-blueprint
-
-L4/L3 的可视化编辑器——用节点图编辑流程和逻辑块。它不是一个"层"，是数据模型的一种编辑视图。
-
 ## 开发
 
 ```bash
@@ -75,9 +71,6 @@ npm run check    # tsc + eslint + prettier
 
 - [架构](docs/architecture.md) — 五层数据模型、变更传播、工具链、目录结构
 - [设计理由](docs/design-rationale.md) — 为什么这么设计，每个决策的推理过程
-- [节点规范](docs/node-spec.md) — 如何定义节点（svp-blueprint 编辑格式）
-- [编译映射](docs/compilation.md) — 节点图到 SVP 数据模型的转换规则
-- [svp-blueprint 设计](docs/design.md) — svp-blueprint 解决什么问题
 - [代码风格](docs/code-style.md) — 开发规范（命名、测试、git、依赖、版本）
 - [交互架构](docs/interaction.md) — 逐层渗透模型、虚拟文件树、聚焦视图、编译计划
 - [check 错误码](docs/check-reference.md) — svp check 的所有错误/警告及修复建议
@@ -86,7 +79,10 @@ npm run check    # tsc + eslint + prettier
 
 ```
 packages/
-└── core/        五层数据模型的 TypeScript 类型定义 + 核心函数
+├── core/        五层数据模型的 TypeScript 类型定义 + 核心函数
+├── skills/      Prompt 生成器（design-l3、compile、recompile 等）
+└── cli/         CLI 入口（svp 命令）
 
 docs/            设计文档 + 开发规范
+examples/        示例项目（hello-world、order-service）
 ```
diff --git a/docs/design.md b/docs/design.md
@@ -191,6 +191,21 @@ wires:
 
 类型定义放在 `types/` 目录，是标准 TypeScript interface。Pin.type 直接引用这些类型名称。
 
+## 蓝图查看器
+
+`svp blueprint` 命令是 svp-blueprint 的只读可视化入口——读取 `.svp/` 下已编译的 L3/L4 JSON，生成自包含 HTML 节点图在浏览器中查看。
+
+设计要点：
+
+- **UE Blueprint 风格暗色主题**：深色背景 + 点阵网格，节点卡片用深色调，减少视觉疲劳
+- **节点即契约盒**：每个节点显示 L3 block 的 name、description（2 行截断）、pins（按类型着色），点击展开查看 validate 和 constraints
+- **类型着色系统**：pin 圆点和数据流连线的颜色由类型名 hash 生成（HSL），同类型 pin 自动同色
+- **执行流标记**：节点头部左右各有三角形执行引脚（类似 UE Blueprint 的 exec pin），表示执行流方向
+- **三种 L4 变体**：Flow（主要，节点图）、EventGraph（事件处理器列表）、StateMachine（状态节点 + 转换边）
+- **零依赖自包含**：单个 HTML 文件内联所有 CSS/JS/数据，无需服务器，离线可用
+
+查看器不做编辑——编辑仍然通过 YAML 文件 + `svp compile-blueprint` 完成。查看器是数据的一种只读渲染视图。
+
 ## 不做什么
 
 - **不做 AI 编译**：svp-blueprint 只负责生成 L4Flow/L3Block 的 JSON，后续 L3→L2→L1 由用户的 AI 编码工具（Claude Code 等）配合 SVP skills 完成

diff --git a/docs/node-spec.md b/docs/node-spec.md
@@ -34,11 +34,11 @@ AI 是编译器，不是 parser。`"request.items: array, min 1, max 50"` 这种
 ## 原子节点
 
 ```yaml
-name: string                    # 节点标识
+name: string # 节点标识
 
 # ── 形式化层 ──
 
-pins:                           # 数据形状
+pins: # 数据形状
   input:
     - name: string
       type: string
@@ -47,19 +47,19 @@ pins:                           # 数据形状
     - name: string
       type: string
 
-validate:                       # 输入约束
+validate: # 输入约束
   field.path: rule [, rule ...]
 
-constraints:                    # 输出约束 + 不变量
+constraints: # 输出约束 + 不变量
   - assertion
 
 # ── 自由层 ──
 
-description: string             # 中间逻辑（自然语言）
+description: string # 中间逻辑（自然语言）
 
 # ── 可选 ──
 
-config:                         # 运行时可调参数
+config: # 运行时可调参数
   key: { type, default }
 ```
 
@@ -107,20 +107,20 @@ validate:
 
 **规则列表：**
 
-| 规则 | 含义 | 示例 |
-|---|---|---|
-| required | 不能为空/undefined | `user_id: required` |
-| optional | 可以为空 | `coupon: optional` |
-| 类型名 | 类型校验 | `age: number` |
-| uuid | UUID 格式 | `id: uuid` |
-| email | 邮箱格式 | `email: email` |
-| url | URL 格式 | `link: url` |
-| min N | 最小值/最小长度 | `items: array, min 1` |
-| max N | 最大值/最大长度 | `name: string, max 100` |
-| > N, >= N, < N, <= N | 数值比较 | `quantity: number, > 0` |
-| == V | 精确相等 | `available: == true` |
-| pattern /regex/ | 正则匹配 | `zip: pattern /^\d{6}$/` |
-| one of [a, b, c] | 枚举 | `status: one of [active, inactive]` |
+| 规则                 | 含义               | 示例                                |
+| -------------------- | ------------------ | ----------------------------------- |
+| required             | 不能为空/undefined | `user_id: required`                 |
+| optional             | 可以为空           | `coupon: optional`                  |
+| 类型名               | 类型校验           | `age: number`                       |
+| uuid                 | UUID 格式          | `id: uuid`                          |
+| email                | 邮箱格式           | `email: email`                      |
+| url                  | URL 格式           | `link: url`                         |
+| min N                | 最小值/最小长度    | `items: array, min 1`               |
+| max N                | 最大值/最大长度    | `name: string, max 100`             |
+| > N, >= N, < N, <= N | 数值比较           | `quantity: number, > 0`             |
+| == V                 | 精确相等           | `available: == true`                |
+| pattern /regex/      | 正则匹配           | `zip: pattern /^\d{6}$/`            |
+| one of [a, b, c]     | 枚举               | `status: one of [active, inactive]` |
 
 每条规则有唯一解释，不存在歧义。
 
@@ -144,17 +144,17 @@ constraints:
 
 **语法（受限的断言语言）：**
 
-| 语法 | 含义 | 示例 |
-|---|---|---|
-| X >= Y, X == Y, ... | 比较 | `total >= 0` |
-| X is type | 类型断言 | `order_id is uuid` |
-| X is empty / not empty | 空值断言 | `errors is not empty` |
-| if P then Q | 蕴含 | `if success then order_id is not empty` |
-| P iff Q | 当且仅当 | `valid iff errors is empty` |
-| count of X == N | 计数 | `count of output.items == count of input.items` |
-| X contains Y | 包含 | `errors contains all failed checks` |
-| all X satisfy P | 全称 | `all items[].quantity > 0` |
-| any X satisfies P | 存在 | `any items[].price > 100` |
+| 语法                   | 含义     | 示例                                            |
+| ---------------------- | -------- | ----------------------------------------------- |
+| X >= Y, X == Y, ...    | 比较     | `total >= 0`                                    |
+| X is type              | 类型断言 | `order_id is uuid`                              |
+| X is empty / not empty | 空值断言 | `errors is not empty`                           |
+| if P then Q            | 蕴含     | `if success then order_id is not empty`         |
+| P iff Q                | 当且仅当 | `valid iff errors is empty`                     |
+| count of X == N        | 计数     | `count of output.items == count of input.items` |
+| X contains Y           | 包含     | `errors contains all failed checks`             |
+| all X satisfy P        | 全称     | `all items[].quantity > 0`                      |
+| any X satisfies P      | 存在     | `any items[].price > 100`                       |
 
 constraints 可以引用 input 和 output，表达输入输出之间的关系。
 
@@ -264,12 +264,67 @@ wires:
 
 ---
 
+## 模块化文档 (docs.md)
+
+每个节点目录和图文件可以附带一个可选的 `docs.md` 文件，提供超出 `description` 字段的丰富上下文。
+
+### 文件位置
+
+```
+nodes/my-node/
+├── node.yaml          # 契约（pins, validate, constraints, description）
+└── docs.md            # 模块化文档（可选）
+
+graphs/
+├── main.yaml          # 图定义
+└── main.docs.md       # 图级文档（可选）
+```
+
+### 与 description 的关系
+
+- **description** 是摘要（1-4 句话），嵌入 L3Block，参与编译流程
+- **docs.md** 是详述，独立文件，按需加载，不影响 contentHash
+
+### 推荐结构
+
+```markdown
+## Intent
+
+设计意图和业务背景。
+
+## Edge Cases
+
+- 边界情况 1
+- 边界情况 2
+
+## Error Strategy
+
+错误处理策略和降级方案。
+
+## Integration Notes
+
+与其他节点/外部服务的集成约定。
+
+## Examples
+
+输入输出示例。
+```
+
+### 加载行为
+
+- `svp prompt compile/recompile/review` 时自动加载并注入 prompt
+- subagent 只拉自己需要的 docs，不加载全量
+- 不影响 `contentHash` 计算——docs 是编译辅助信息，不是契约的一部分
+
+---
+
 ## 目录约定
 
 ```
 nodes/
 ├── my-node/
-│   └── node.yaml              # 原子节点
+│   ├── node.yaml              # 原子节点
+│   └── docs.md                # 模块化文档（可选）
 ├── my-pipeline/
 │   ├── node.yaml              # 复合节点（type: composite）
 │   └── nodes/                 # 子节点
@@ -279,7 +334,8 @@ nodes/
 │           └── node.yaml
 
 graphs/
-└── main.yaml                  # 顶层连线图
+├── main.yaml                  # 顶层连线图
+└── main.docs.md               # 图级文档（可选）
 
 types/
 └── *.ts                       # 引脚类型定义
@@ -289,19 +345,19 @@ types/
 
 ## 编译映射总结
 
-| svp-blueprint | L3Block 字段 | 说明 |
-|---|---|---|
-| name | id | 直接映射 |
-| pins.input | input: Pin[] | 直接映射 |
-| pins.output | output: Pin[] | 直接映射 |
-| validate | validate: Record<string, string> | 直接映射 |
-| constraints | constraints: string[] | 直接映射 |
-| description | description: string | 直接映射 |
-| （计算）| signature | 从 input/output 生成，不存储 |
-
-| svp-blueprint | L4Flow 字段 | 说明 |
-|---|---|---|
-| 复合节点 nodes | steps: Step[] | 子节点 → 步骤 |
-| wires | steps[].next + dataFlows | 连线 → 执行顺序 + 数据流 |
-| 扇出 | action: "parallel" 步骤 | 一出多入 → 并行 |
-| 汇聚 | action: "wait" 步骤 | 多出一入 → 等待 |
+| svp-blueprint | L3Block 字段                     | 说明                         |
+| ------------- | -------------------------------- | ---------------------------- |
+| name          | id                               | 直接映射                     |
+| pins.input    | input: Pin[]                     | 直接映射                     |
+| pins.output   | output: Pin[]                    | 直接映射                     |
+| validate      | validate: Record<string, string> | 直接映射                     |
+| constraints   | constraints: string[]            | 直接映射                     |
+| description   | description: string              | 直接映射                     |
+| （计算）      | signature                        | 从 input/output 生成，不存储 |
+
+| svp-blueprint  | L4Flow 字段              | 说明                     |
+| -------------- | ------------------------ | ------------------------ |
+| 复合节点 nodes | steps: Step[]            | 子节点 → 步骤            |
+| wires          | steps[].next + dataFlows | 连线 → 执行顺序 + 数据流 |
+| 扇出           | action: "parallel" 步骤  | 一出多入 → 并行          |
+| 汇聚           | action: "wait" 步骤      | 多出一入 → 等待          |
diff --git a/docs/phase2-plan.md b/docs/phase2-plan.md
@@ -1,5 +1,7 @@
 # SVP Phase 2: AI Skill 实现 & Claude Code 集成 — 完整计划 (v2 - 用户确认完整)
 
+> **注意**：本文档是 Phase 2 的历史规划文档，当时仅支持 Claude Code。实际实现已扩展为支持 6 种 AI 编码工具（Claude Code、Cursor、Windsurf、Kimi Code、Codex、GitHub Copilot）的插件化 adapter 系统。当前架构详见 `packages/skills/adapters/` 和 `docs/project-introduction.md` 第 7.4 节。
+
 ## Context
 
 ### 现状