初始化工作区

SuccIDE 工作区是 VS Code 打开的本地目录。初始化工作区的目标，是让本地目录具备连接服务器、克隆项目、检查差异、编辑脚本和提交 Git 的基础条件。

准备本地目录

在 VS Code 中选择 文件 > 打开文件夹，选择一个本地目录作为 SuccIDE 工作区。

建议按客户项目或交付项目创建独立工作区。例如：

customer-a-bi-workspace
customer-b-bi-workspace

不要把多个无关客户或多个无关项目放在同一个工作区里混合管理。

建议启用 Git

正式项目建议从一开始就启用 Git。Git 用于记录本地元数据文件的历史，SuccIDE 用于连接服务器和同步元数据，两者解决的问题不同。

如果团队已经有 Git 仓库，先从仓库拉取工作区内容，再连接服务器。若是新项目，应先由团队确认仓库结构、分支和 .gitignore 规则。

完成首次连接和克隆

准备好本地目录后，需要至少连接一个 SuccBI 服务器，并把当前任务需要的服务器项目克隆到本地。

首次初始化时，可以按以下顺序完成：

1. 打开命令面板（Windows / Linux：Ctrl+Shift+P；macOS：Cmd+Shift+P），执行 SuccIDE: 添加服务器（英文界面为 SuccIDE: Add Server），输入 SuccBI 服务器地址并登录。
2. 登录成功后，执行 SuccIDE: 克隆项目（英文界面为 SuccIDE: Clone Project），把服务器项目下载到本地工作区。

克隆完成后，工作区中通常会生成：

1. 从服务器下载的项目目录。
2. 项目目录中的 .meta 文件。
3. .succide/config.json 服务器配置。
4. .succide/remote/ 本地服务器基线。
5. SuccIDE 推荐的工作区设置和 Git 忽略规则。

服务器登录、重新登录、切换服务器、浏览远端文件、重置和移除项目等完整操作，请阅读连接服务器与下载元数据。

应用推荐工作区设置

连接服务器或克隆项目后，SuccIDE 会自动检查并引导应用推荐工作区设置。一般情况下无需手动执行该命令。

如果服务器版本升级后，推荐工作区设置发生变化，可以手动打开命令面板，执行 SuccIDE: 应用推荐工作区设置（英文界面为 SuccIDE: Apply Recommended Workspace Settings）。

应用推荐工作区设置后，可以获得这些效果：

1. 将 .tbl、.query、.dash、.rpt、.meta 等常见 SuccBI 元数据文件识别为 JSON，便于使用 VS Code 的语法高亮、格式化和结构检查。
2. 启用 SuccIDE 文件图标主题，在资源管理器中更容易区分不同类型的元数据文件。
3. 隐藏 .succide/remote/、缓存、锁、日志和合并备份等运行时文件，减少日常编辑时的干扰。
4. 生成或更新 tsconfig.json、.succide/tsconfig.action.json、.succide/tsconfig.browser.json，让 VS Code TypeScript Server 能为服务端脚本和浏览器脚本提供语法诊断。
5. 在工作区存在业务 TypeScript 脚本且服务器支持时，从服务器下载并还原 .d.ts 类型声明到 .succide/succ-types/，为脚本编辑提供类型提示和 API 补全。
6. 从当前连接服务器下载 JSON Schema 到 .succide/json-schemas/，并在 .vscode/settings.json 中补齐 json.schemas，为 .case、.testsuite、.query、.jdbc、settings.json 和扩展 package.json 等文件提供结构提示和校验。
7. 写入推荐的 Git 忽略和 SuccIDE 同步忽略配置，避免本地运行时文件进入 Git，并避免 IDE 辅助文件同步回元数据服务器。

如果团队已经维护了自己的工作区配置，应用推荐设置前应查看提示，避免覆盖团队自定义配置。

工作区文件说明

SuccIDE 工作区中常见文件如下：

workspace/
├── .gitignore                   # 根目录 Git 忽略配置，SuccIDE 会写入系统临时文件忽略片段
├── .succide/
│   ├── .gitignore               # SuccIDE 运行时文件的 Git 忽略配置
│   ├── config.json              # 当前工作区的服务器地址簿和当前活跃服务器
│   ├── remote/                  # 本地服务器基线副本
│   ├── locks/                   # 同步任务锁
│   ├── cache/                   # 本地缓存
│   ├── json-schemas/            # JSON 文件结构提示使用的 schema 文件
│   │   ├── json-schema-support.json       # JSON Schema 注册清单
│   │   └── json-schema-support-state.json # JSON Schema 支持的服务器版本记录
│   ├── merge-base/              # 拉取和合并前保存的服务器基线副本
│   ├── merge-backup/            # 拉取和合并前保存的本地文件备份
│   ├── succ-types/              # 脚本 TypeScript 诊断使用的类型声明
│   ├── succ-types.tmp-*/        # 刷新类型声明时使用的临时目录
│   ├── tsconfig.action.json     # 服务端脚本 TypeScript 诊断配置
│   ├── tsconfig.browser.json    # 浏览器脚本 TypeScript 诊断配置
│   ├── typescript-support.json  # TypeScript 诊断支持的服务器版本记录
│   ├── *.log                    # 日志文件
│   └── state.json               # 本地同步状态文件
├── .vscode/
│   └── settings.json            # VS Code 工作区设置
├── project1/                    # 从服务器克隆下来的元数据项目
│   └── .meta                    # 记录服务器资源标识和版本信息
├── project2/                    # 同一个工作区中可以克隆多个元数据项目
│   └── .meta                    # 记录服务器资源标识和版本信息
└── tsconfig.json                # 脚本 TypeScript 诊断配置

服务器配置文件

添加服务器后，当前工作区会生成 .succide/config.json。该文件保存服务器地址列表和当前活跃服务器。

示例结构如下：

{
	"version": 2,
	"servers": [
		"http://localhost:8080"
	],
	"activeServerUrl": "http://localhost:8080"
}

注意

.succide/config.json 只保存服务器地址，不保存用户密码。账号登录态由 VS Code 安全存储管理。

Git 忽略建议

正式项目中，建议提交项目元数据文件和 .meta 文件，不提交 SuccIDE 运行时文件。

应用推荐工作区设置后，SuccIDE 会自动补齐默认 .gitignore 配置，忽略 .DS_Store、Thumbs.db、.succide/remote/、.succide/cache/、.succide/locks/、.succide/*.log、.succide/state.json 等本地文件。

通常不应提交这些本地运行时文件：

workspace/
└── .succide/
    ├── remote/                  # 本地服务器基线副本
    ├── cache/                   # 本地缓存
    ├── locks/                   # 同步任务锁
    ├── merge-base/              # 拉取和合并前保存的服务器基线副本
    ├── merge-backup/            # 拉取和合并前保存的本地文件备份
    ├── *.log                    # 日志文件
    └── state.json               # 本地同步状态文件

如果团队使用 Git 管理工作区，通常提交项目目录和项目中的 .meta 文件；.vscode/settings.json、tsconfig.json、.succide/succ-types/ 等配置和诊断文件是否提交，由团队统一约定。.succide/config.json 可能包含客户现场的服务器地址，默认不提交。

更多 Git 管理建议请阅读用 Git 管理元数据版本。

初始化后检查

初始化完成后，建议检查：

1. SuccIDE 服务器视图中能看到当前服务器和项目。
2. 本地项目目录已经出现。
3. Changes 视图可以正常刷新。
4. .succide/remote/ 没有进入 Git 提交。
5. .meta 文件没有被 Git 忽略。
6. 需要脚本提示的工作区已经生成 tsconfig.json 和 .succide/succ-types/。
7. 当前连接的是测试服务器，而不是生产服务器。

下一步可以阅读连接服务器与下载元数据和修改、对比、拉取与推送。