# VLC 使用手册

适用版本：VLC / VLCode-Lite **1.250.5**（2026-07-11 更新；1.190–1.250 变化要点见下）

> **1.250.x 基线要点（先读这段再看正文）**
> - **本地优先**：工具栏顺序为 语法检查（Lint）→ 编译（Compile）→ **预览（本地 Preview，主路径，127.0.0.1 本地 rustBase，无需 GID/登录/云资源）**；云端动作已归入独立「云端」分组（云端预览 / 发布），发布走计费云算力且受 SECRET preflight 门控（未绑定的 SECRET 键会在 compile/deploy 前显式拦截）。
> - **端口**：安装版/真实实例固定 `4000`；AI 源码调试用 `4001`；中文版为 `4002`。文中旧端口描述以此为准。
> - **新建项目**：项目名必须是单段英文（首字母开头，`A-Za-z0-9._-`，≤64，无空格/斜杠/`..`），父目录默认 `~/Documents/VLProjects`。空白新项目没有可编译入口（无 `Apps/*.vx` 或 `Services/*.vs`）时，Compile 会给出明确指引而不是内部错误。
> - **未保存守卫**：切换文件/Theme 前如有未保存修改会弹出「保存 / 放弃 / 取消」确认，不再静默丢失草稿；仍建议随手 `Cmd+S`。
> - **LLM 接入**：支持 provider **API Key** 和已验证的 **Codex CLI** 登录（Settings → Connect Codex CLI → Save）；Chat 与 Workflow 保持所选连接。Claude CLI 的 AWS 5× / 20× 订阅席位仍通过 Matrix Task 使用，尚未接入 VLC 的普通连接选择器；不要用本机 Claude 网关代替。
> - **CLI**：在仓库根执行 `node bin/vlc-cli.js <cmd> --port <port>`（`ping` / `project tree|preflight` / `workflow list|show|status` / `chat` / `cloud …`）。外部/破坏性动作需 `--confirm`，包括 `cloud deploy|launch|publish|rebind|unbind|create-and-bind` 以及 **`cloud sync-pull`（会覆盖本地文件）**。
> - **统一安装包**：桌面推荐安装 unified **VisualLogic** 包（一次安装 Build/Flow/Team 三工作台 + 共享底座，含启动自检）；见 releases.visuallogic.ai。

本文面向日常使用者、工作流作者和项目交付人员，覆盖从创建 VL 项目、使用 AI 工作流、上传 `.vflow`、Lint/Compile 验证，到设计优先生成与设计文件导入。

## 1. VLC 是什么

VLC 是面向 VL（Visual Language）项目的本地 AI IDE。它负责：

- 管理本地 VL 项目 workspace。
- 编辑 `Apps/`、`Sections/`、`ExtComponents/`、`Services/`、`Database/`、`Theme/` 等 VL 工程文件。
- 调用 AI 工作流生成、补全、调整、修复 VL 代码。
- 通过平台 API 执行 Lint、Compile、Preview、Deploy 等验证链路。
- 通过 SysDoc / Resource Center 同步核心文档，避免过期 VL 语法或 Theme 规范进入生产线。

VLC 不是通用代码编辑器。对于 VL 项目，所有代码生成、修复、验证都应该以当前绑定的 VL 语法文档、Theme 文档和平台 API 为准。

## 2. 核心概念

| 名称 | 说明 |
|------|------|
| Workspace | 当前打开的本地 VL 项目目录。新项目应放在 `~/Documents/VLProjects/<ProjectName>/`。 |
| VL 源文件 | `.vx` 应用入口、`.sc` Section、`.cp` Component、`.vs` Service、`.vdb` Database、`.vth` Theme。 |
| Process | 工作流中间产物目录，例如 `Process/ProjectMeta.json`、`Process/HtmlFirst/Prototype.html`。 |
| SysDoc | 系统文档源，核心包括 VL 语法、Theme、Workflow Spec。 |
| Flow / Workflow | 由节点组成的自动化 DAG，用于生成、修复、导入、验证项目。 |
| `.vflow` | 工作流包，包含 workflow JSON、manifest、support docs/prompts。它描述“工作怎么跑”，不是应用交付包。 |
| Lint | 快速 VL 代码验证，成本低，适合在 Compile 前反复使用。 |
| Compile | 平台编译验证，较重，用于确认可运行、可预览。 |

## 3. 推荐项目目录

新建 VL 项目时使用：

```text
~/Documents/VLProjects/<ProjectName>/
├── Config/
├── Apps/
├── Sections/
├── ExtComponents/
├── Services/
├── Database/
├── Theme/
├── Process/
└── .vl-code/
    └── project.json
```

重要规则：

- 项目名和 VL 文件名必须是英文 PascalCase。
- 不要把生成项目写进 VLC 自身源码目录。
- 线上 GID 由 `.vl-code/project.json` 的 `groupId` + `gidBinding` 托管，普通开发时不要手动改；首次预览/编译会自动创建绑定，复制项目遇到无权限旧 GID 时会重新取号并保留历史记录。
- `Config/ProjectConfig` 只作为旧项目兼容入口，读取后会迁移到 `.vl-code/project.json`。
- 工作流中间文件统一放入 `Process/`，不要混到源代码目录里。

## 4. 主界面

VLC 常用区域如下：

- 左侧文件树：浏览、打开、拖拽导入当前 workspace 文件。
- 中央编辑器：编辑 VL 源文件、文档、workflow JSON。
- 右侧 Detail Log：显示 workflow 节点进度、工具调用、文件写入、Lint/Compile 结果、错误和自动修复记录。
- AI Chat：提交自然语言需求、查看最终摘要、处理需要人工输入的卡片。
- 底部状态栏：当前工作流步骤、平台连接、核心文档版本、快速状态。
- Flow Tab：查看和运行 workflow DAG。
- Resource 页面：浏览 docs、flows、components 等资源。

日志分工：

- Chat 只放最终摘要、需要用户决策的问题、关键错误。
- Detail Log 放完整过程。
- Status Bar 显示当前正在做什么。
- Flow Tab 负责 DAG 高亮，不承担详细日志。

## 5. 打开或创建项目

### 创建新项目

1. 打开 workspace 入口。
2. 选择新建项目。
3. 输入英文 PascalCase 项目名，例如 `TeamPM`。
4. 默认放在 `~/Documents/VLProjects/`。
5. VLC 创建标准目录并切换到该 workspace。

### 打开已有项目

1. 选择 workspace 切换。
2. 指向已有项目根目录。
3. 文件树刷新后，确认 `Apps/`、`Sections/`、`Database/`、`Theme/` 等目录存在。

## 6. 核心文档版本同步

几乎所有生产级工作流都依赖核心文档：

- VL Syntax：VL 语法规则。
- ThemeDefault：Theme / StyleSpace 规范。
- Workflow Spec：工作流节点规范。

VLC 的关键保护：

- 工作流启动前检查核心文档版本。
- 若本地缓存与 SysDoc 不一致，自动同步正确文件。
- 底部四个核心文件版本号刷新，做二次对齐。
- 如果同步失败，工作流应停止，而不是继续使用过期文档。

使用建议：

- 生成或修复 VL 代码前，先确认底部文档版本没有红色或未知状态。
- 当你怀疑语法规则变化时，优先同步 SysDoc，不要凭旧经验修改 VL。
- VL 是专用语言，遇到未知语法应查 VL Syntax，而不是用 HTML/JS/CSS 直觉猜。

## 7. AI 工作流使用

常用生成流程（与 Flow Tab 的 Generate / Enterprise / Clone 分组一致；默认值取自当前 UI 绑定）：

Generate（常规生成，默认 `Meta Sharded` / `meta-sharded-codegen`）：

- `Meta Sharded`（`meta-sharded-codegen`，**默认**）：分片式 Meta 生成，模块并行、合并 ProjectMeta、带 Lint 关卡。一般项目首选。
- `Meta Fast Fanout`（`meta-fast-fanout`）：分阶段元数据 + 实现波次并行扇出，速度优先，带 VLLint 修复与 parser 关卡。
- `Meta Stream Fast`（`meta-stream-fast-codegen`）：流式 Meta 生成，面向分布式 worker 与 parser 校验。
- `Parallel Codegen`（`parallel-codegen`）：归档的并行快车道，页面覆盖广。
- `Meta Direct`（`meta-direct-codegen`）：直连 Meta-first 路径；仅保留作手动 / 回归用，**已非默认**（部分 provider 下会产出过时语法）。
- `HTML First VL`（`html-first-vl-codegen`）：先出 HTML 视觉稿，抽取视觉契约后合成 VL。

Enterprise（企业级，默认 `Enterprise Design Parallel` / `enterprise-design-parallel-cascade-codegen`）：

- `Enterprise Design Parallel`（**默认**）、`Enterprise Design Compact`、`Enterprise Meta Cascade`、`Enterprise Design Cascade`：大型项目的级联生成，覆盖更多页面 / 服务。

Clone / 其它：

- `Site Clone`（`site-clone-codegen`）：抓取站点 + 截图 + 视觉分析，合成复刻蓝图后交给 codegen。
- `CompleteFiles`（`complete-files`）：项目半途中断或缺文件时补齐。
- `CompileFix`（`compile-fix`）：根据编译错误做最小修复。

运行方式：

1. 打开 Flow Tab 或通过 Chat 触发。
2. 选择 workflow。
3. 填写参数，例如 `userRequest`、`projectName`、`targetLang`。
4. 启动后 Detail Log 自动打开。
5. 如出现人工卡片，在 Chat 中提交。
6. 完成后查看生成文件、Lint、Compile 结果。

工作流完成后，建议顺序：

1. Lint。
2. Compile。
3. 预览。
4. 如有问题，先用 Lint/CompileFix 修复，再重新 Compile。

## 8. Lint 与 Compile

### Lint

Lint 是快速验证工具，适合：

- 生成 VL 文件后立即验证。
- 编译前做低成本检查。
- 修复循环中确认语法问题是否消失。
- 作为独立 tool 被 workflow 调用。

使用建议：

- 每次生成或重新生成 `.vx`、`.sc`、`.cp`、`.vs`、`.vdb`、`.vth` 后都跑 Lint。
- Lint 报错时，先修 Lint，不要直接进入 Compile。
- 有云端 GID 绑定时优先使用平台 Lint。

### Compile

Compile 是较重验证，用于确认项目可编译和预览。

使用建议：

- 不要把 Compile 当作反复试错工具。
- 同一轮修复最多 Compile 两次。
- 相同错误重复出现时，回到 VL Syntax 或 Lint，而不是继续编译。

## 9. `.vflow` 上传功能

### `.vflow` 是什么

`.vflow` 是 workflow bundle，也可以是 Agent App authoring bundle。普通 workflow `.vflow` 只描述“工作怎么执行”；Agent App `.vflow` 会额外在 workflow 顶层携带 `app` 块，用来声明入口、权限、Shell 和节点胶囊编辑模型。

普通 `.vflow` 通常包含：

- 主 workflow JSON。
- manifest。
- 子流程引用。
- support docs、prompts、配置文件。

Agent App `.vflow` 还可以包含：

- `app.surface.dagShell.logic`：Shell 的 Event Panel events / AST，不能只保存 VL 字符串。
- `step.capsule.contract/resources/llmRuntime/samples`：节点声明式边界、资源、LLM 调用和示例输入。
- `step.capsule.logic`：节点内部唯一命令式逻辑入口，使用 Event Panel events / AST。
- `resources.skills[]`：节点内联 skills，使用 `{name, content}`，不要另建 `skillRefs` 指针。

它不等于：

- `.vl` 项目包。
- 已生成的 VL 源代码。

普通 `.vflow` 的边界是“工作怎么执行”。Agent App `.vflow` 的边界是“一个可运行 Agent App 如何被 host 打开和治理”：Shell / Capsule 是作者层，run ledger、checkpoint、artifact、evidence、error 属于运行态 control plane，不写回作者层。

### 上传入口

1. 打开 Resource 页面。
2. 切换到 `Flows`。
3. 点击右上角 `Upload .vflow`。
4. 选择本地 `.vflow` 文件。

### 上传过程

VLC 会按下面顺序处理：

1. 读取本地 `.vflow` 文件为 base64。
2. 调用 `/api/bundle/read-vflow` 做预读和校验。
3. 从 manifest / workflow 中解析 flow id、title、support 文件。
4. 检查当前工作区是否已有同名 flow。
5. 如果同名，弹出确认；确认后替换，取消则不导入。
6. 调用 `/api/bundle/import-vflow` 执行导入。
7. 写入主 workflow 到 `.vl-code/workflows/<flow-id>.json`。
8. 写入 support docs 到 `.vl-code/docs/flow-support/<flow-id>/`。
9. 清空 flow resource 缓存。
10. 刷新 workflow 选择器、Flow 列表、Resource 详情。
11. 自动聚焦新导入 flow 的 manifest/detail。

### 上传成功后怎么用

上传成功后：

- 在 Flow Tab 中可以看到新 flow。
- 在 Resource `Flows` 中可以查看 manifest、workflow JSON、支持文档和产物声明。
- 可以直接运行，也可以作为子流程被 `WorkflowRun` 调用。

### 常见失败

| 现象 | 处理 |
|------|------|
| `Please choose a .vflow bundle` | 文件扩展名不是 `.vflow`。 |
| `Invalid .vflow bundle` | 包内结构不符合 vflow bundle 规范，先检查 manifest 和主 workflow。 |
| 同名 flow 提示替换 | 确认是否要覆盖现有 `.vl-code/workflows/<id>.json`。 |
| 上传后列表没变化 | 重新进入 Resource `Flows` 或刷新 workflow 列表。 |
| 支持文档缺失 | 检查 `.vl-code/docs/flow-support/<id>/` 是否被写入。 |

## 10. 设计驱动生成与设计文件上传

> **变更说明（v1.189.0）**：早期版本随附的三个设计上传工作流——`DesignUpload-Intake`、`DesignUpload-MetaDirect-CodeGen`、`DesignUpload-DesignReference-CodeGen`——已从发行包中移除。`public/seed-workflows/` 和 `.vl-code/workflows/` 不再包含任何 `design-upload-*.json`，被它们调用的 `DesignReference-CodeGen` 子流程也不存在；任何随附工作流都不再生成 `Process/DesignUploads/` 目录或 `DesignUploadManifest.json`。下面是当前真实可用的设计相关能力。

### 10.1 设计优先生成（从文字需求生成设计）

当前的设计相关生成走 **design-first（设计优先）** 路线：先由文字需求合成一套设计，再转成 VL，而**不是**上传现成设计稿。随附工作流：

| 工作流 | 文件 | 用途 |
|--------|------|------|
| `SmartDesign-FullStack-CodeGen` | `smart-design-fullstack-codegen.json` | 把一句话需求扩展成完整产品 brief + 设计系统，先产出 HTML 原型（`Process/HtmlFirst/Prototype.html`），再转成 VL 设计契约，并行生成前后端 VL，最后跑 lint 修复。适合把一个简单想法变成一个好看、完整的应用。 |
| `EnterpriseDesignCascadeCodegen` 及其 compact / parallel 变体 | `enterprise-design-cascade-codegen.json`、`enterprise-design-compact-cascade-codegen.json`、`enterprise-design-parallel-cascade-codegen.json` | 企业级设计级联生成，适合更大、分层的项目。 |

这些工作流通过标准 Generate 输入接收需求文字（`userRequest` / `projectName` 等），**不接收上传文件**。

### 10.2 设计文件上传（通用人工卡片能力）

把设计文件带进生成流程的能力仍然存在，但它**不再是某个打包工作流**，而是 InteractiveCard 人工卡片协议里的一个**通用文件上传字段**：

- 工作流的 Pause / human-task 节点在 `humanTask.fields` 里声明一个文件上传字段，可带 `accept`、`maxFiles`、`uploadDir`、`uploadMode`。
- 用户在卡片里选择文件后，VLC 通过 `_uploadInteractiveCardFiles()` 安全化文件名，POST 到 `/api/upload-folder`，按字段指定的 `uploadDir` 写入当前 workspace（默认 `merge`）。
- 上传目标目录由卡片的 `uploadDir` 决定，**不再固定**为 `Process/DesignUploads/`。

注意：

- 这是一个通用机制——目前**没有任何随附工作流**使用它来接收设计文件。要用它，需要工作流作者自己在工作流里加这个上传字段（见 §11 与 InteractiveCard 协议，SysDoc key `InteractiveCardProtocol`）。
- 上传前必须有当前 workspace；文件名会做安全化处理，避免路径穿越和非安全字符。

### 10.3 把现成设计文件带进 workspace

如果只是想把现有 HTML、截图、PDF、ZIP 设计包放进项目供参考，用文件树的拖拽 / ZIP 导入即可（见 §12）。它走的是同一个 `/api/upload-folder` 路由，把文件按目录结构写入当前 workspace。

## 11. 如何为工作流接入设计文件上传

由于不再有打包好的设计上传流程，若要让某个工作流真正“接收上传的设计文件并进入生成”，需要工作流作者自己搭建。基本骨架：

1. 在工作流里加一个 Pause / human-task 节点，`humanTask.fields` 含一个文件上传字段（用 `accept` 限定设计文件类型，`uploadDir` 指向比如 `Process/DesignUploads/`，`uploadMode: merge`）。
2. 提交后文件写入 workspace，并作为人工任务响应回到工作流变量，供后续节点读取路径。
3. 在上传节点之后嫁接解析 / 生成节点。

可嫁接的下游能力（均需自行实现，当前未随附）：

- HTML/CSS 解析节点：抽取 DOM 层级、布局、颜色、字体、交互元素。
- ZIP 解包节点：解压上传的设计包，重新整理文件清单。
- Figma 解析节点：把 `.fig` 或链接解析成 frame、component、token。
- 多图分析节点：把多张截图按页面聚类后交给视觉分析。
- 设计 token 提取节点：把颜色、字号、间距、圆角映射到 Theme / StyleSpace。
- 工作流选择节点：根据文件类型分流到不同生成流程（如 §10.1 的设计优先流程或 SiteClone 系列）。

解析结果可在调用下游 `WorkflowRun` 前合并进 `userRequest`，交给生成流程使用。

## 12. 文件导入与拖拽

VLC 支持把常见项目文件拖入文件树。用于项目导入时：

- `.vl` 走 bundle 打开。
- `.zip` 走 ZIP 项目导入。
- 常见代码/文本文件按目录结构导入。

两种把文件带进项目的方式：

- 拖拽 / ZIP 导入：偏项目文件导入，按目录结构写入当前 workspace（通常 `mode: replace`）。
- 人工卡片文件上传（§10.2）：偏 workflow 表单输入，写入卡片 `uploadDir` 指定的目录（默认 `merge`）。目前没有随附工作流使用它。

两者都走同一个 `/api/upload-folder` 路由。

## 13. 典型工作步骤

### 从自然语言生成小项目

1. 新建 workspace。
2. 提交需求或选择默认生成流程 `Meta Sharded`（`meta-sharded-codegen`）。
3. 等待生成完成。
4. 跑 Lint。
5. 跑 Compile。
6. 预览并微调。

### 设计驱动生成项目

1. 新建 workspace。
2.（可选）把现成 HTML / 截图 / PDF / ZIP 设计稿用拖拽或 ZIP 导入放进 workspace 供参考（见 §12）。
3. 运行设计优先生成流程 `SmartDesign-FullStack-CodeGen`（企业级项目用 Enterprise Design Cascade 系列）。
4. 在需求里描述设计方向、页面和功能；流程先产出 HTML 原型再转成 VL。
5. 查看 Lint / Compile 结果。
6. 对视觉或业务差异运行调整流程。

### 导入外部 workflow

1. 打开 Resource `Flows`。
2. 点击 `Upload .vflow`。
3. 选择 `.vflow`。
4. 确认是否覆盖同名 flow。
5. 上传成功后在 Flow Tab 运行。

## 14. 故障排查

| 问题 | 优先检查 |
|------|----------|
| 工作流没有出现上传卡片 | workflow 的 Pause 节点是否包含 `humanTask.fields`，且字段类型为文件上传（带 `accept`/`uploadDir`）。 |
| 上传文件没有写入 | 是否有当前 workspace，`/api/upload-folder` 是否返回错误。 |
| 导入的设计文件没进 workspace | 用拖拽 / ZIP 导入（§12）；确认已选 workspace 且 `/api/upload-folder` 未报错。 |
| Compile 反复失败 | 先跑 Lint，再查 VL Syntax；不要用 Compile 做循环试错。 |
| 生成文件缺失 | 跑 `CompleteFiles`，不要直接重跑完整大流程。 |
| 核心文档版本不对 | 先同步 SysDoc，再运行工作流。 |

## 15. 最佳实践

- 新项目使用 `~/Documents/VLProjects/<ProjectName>/`。
- 每次大生成后先 Lint，再 Compile。
- 普通 `.vflow` 用于迁移和复用工作流，不要塞应用身份和生产权限策略；Agent App `.vflow` 若携带 `app` 块，则必须显式声明 `app.permissions`、`app.surface.dagShell.logic` 和每个复杂节点的 `step.capsule`。
- 设计优先生成会先产出 HTML 原型（`Process/HtmlFirst/Prototype.html`），保留它便于追踪和复现。
- 导入的 HTML/CSS 设计文件不应直接当作 VL 代码，需要经过解析、摘要和 VL 语法映射。
- VL 文件名保持英文 PascalCase。
- 不要手动删除不理解的 workflow 支持文件；先查看 Resource `Flows` 详情。
