---
title: 初始化工作区
navTitle: 初始化工作区
---
# 初始化工作区

SuccApp 工作区是本地目录，也是 AI、SuccApp CLI、SuccApp for VS Code 和 Git 协作的边界。初始化工作区的目标，是让本地目录具备连接服务器、克隆项目、读取 AI 规则、检查差异、编辑脚本和提交 Git 的基础条件。

AI 低代码开发应从工作区开始，而不是从单个文件开始。工作区中包含项目元数据、目录级 `.meta`、服务器配置、类型声明、编辑器辅助配置、Git 忽略规则和 AI 协作文件，决定了 AI 能否准确理解和安全修改项目。

## 理解工作区{#workspace}

可以把一个 SuccApp 工作区理解为一个 VS Code 项目。一个工作区通常只维护同一套元数据内容对应的服务器，例如同一个客户项目的测试环境和生产环境。

这里的“同一套元数据内容对应的服务器”，不是指服务器地址必须只有一个，而是指这些服务器之间的项目、资源和元数据内容本来就属于同一套交付或同一套业务系统。

不建议把两个无关服务器直接放在同一个工作区中混合管理。如果确实需要在两个无关服务器之间做内容交互，例如一次性的升级或迁移，可以分别把 A、B 两个服务器初始化到两个工作区，再在本地从一个工作区复制需要的文件到另一个工作区，检查后再同步到目标服务器。

## 选择初始化路径{#choose-path}

初始化工作区有两种常见路径：从服务器开始创建工作区，或者从团队 Git 仓库开始恢复工作区。AI Agent 和脚本化流程建议优先使用 SuccApp CLI；人工操作也可以使用 CLI，只有需要图形化选择服务器、查看项目树或检查 Changes 时再打开 SuccApp for VS Code。

正式项目建议从一开始就启用 Git。Git 用于记录本地元数据文件的历史，SuccApp 用于连接服务器和同步元数据，两者解决的问题不同。推荐入库内容、忽略规则和提交流程见[工作区版本管理](./git-versioning.md)。

## 从服务器开始{#init-from-server}

适合团队还没有 Git 仓库，或者需要从某个 SuccApp 服务器拉出初始项目内容的场景。

```bash
mkdir sales-ops-workspace
cd sales-ops-workspace
git init
succapp auth login <test-server-url>
succapp workspace init --server <test-server-url>
succapp workspace project clone SALES_OPS
git status
```

这组命令会创建本地目录，初始化 Git，登录测试服务器，写入工作区配置，克隆 `SALES_OPS` 项目，并生成本地同步基线。克隆完成后，确认项目目录和目录级 `.meta` 已出现，再提交项目目录、目录级 `.meta` 和团队需要共享的配置。

如果服务器上还没有项目，需要先在浏览器项目管理页面创建项目，或由有权限的用户执行 `succapp server project create <project>`。创建项目后，再克隆到工作区。

人工使用 SuccApp for VS Code 时，可以在命令面板中依次执行 **SuccApp: 初始化工作区**、**SuccApp: 添加服务器** 和 **SuccApp: 克隆项目**。

## 从 Git 仓库开始{#init-from-git}

适合团队已经把工作区内容纳入 Git，或者新成员接手已有项目的场景。

```bash
git clone <repo-url> sales-ops-workspace
cd sales-ops-workspace
succapp auth login <test-server-url>
succapp workspace init --server <test-server-url>
succapp workspace status --json
```

这组命令会从 Git 取得团队已有工作区，登录测试服务器，刷新本机推荐设置和服务器配置，再输出当前工作区状态。AI Agent 可以优先读取 `workspace status --json` 结果，判断是否存在本地变化、远端变化或冲突。

从 Git 仓库开始时，不要直接用服务器克隆结果覆盖本地目录。先确认 Git 中已有的项目目录，再连接服务器并检查状态；只有确认要接受服务器版本时，再执行 `succapp workspace pull` 拉取服务器变化。

人工使用 SuccApp for VS Code 时，可以打开 Git 克隆后的目录，再执行 **SuccApp: 初始化工作区**、**SuccApp: 添加服务器** 或 **SuccApp: 使用服务器**，最后在 Changes 视图中刷新和检查变化。

添加服务器、登录服务器、使用服务器、浏览远端文件、重置和移除项目等完整操作，请阅读[连接服务器与克隆项目](./connect-and-clone.md)。

## 初始化工作区与刷新推荐设置{#recommended-settings}

执行 `succapp workspace init` 或 **SuccApp: 初始化工作区** 后，SuccApp 会创建或检查 `.succapp/config.json`，并补齐推荐工作区设置、AI 协作入口、TypeScript 诊断配置、编辑器结构提示配置和 Git 忽略规则。

这个命令不要求已经连接服务器。没有服务器连接时，会先完成本地工作区初始化；需要从服务器下载的类型声明、编辑器结构提示和前端运行时依赖清单，会在后续连接服务器、添加服务器或克隆项目时刷新。显式传入 `--server <server-url>` 时，SuccApp CLI 会先检查这台服务器的登录状态；如果尚未登录，需要先执行 `succapp auth login <server-url>`。服务器版本升级后，也可以再次执行 `succapp workspace init --server <server-url>` 或 **SuccApp: 初始化工作区**（英文界面为 **SuccApp: Initialize Workspace**）刷新推荐设置。

初始化工作区后，可以获得这些效果：

1. 将 `.tbl`、`.query`、`.dash`、`.rpt`、`.meta` 等常见 SuccApp 元数据文件识别为 JSON，便于使用 VS Code 的语法高亮、格式化和结构检查。
2. 启用 SuccApp 文件图标主题，在资源管理器中更容易区分不同类型的元数据文件。
3. 隐藏 `.succapp/remote/`、缓存、锁、日志和合并备份等运行时文件，减少日常编辑时的干扰。
4. 生成或更新 `tsconfig.json`、`.succapp/tsconfig.action.json`、`.succapp/tsconfig.browser.json`，让 VS Code TypeScript Server 能为服务端脚本和浏览器脚本提供语法诊断。
5. 在工作区存在业务 TypeScript 脚本且服务器支持时，从服务器下载并还原 `.d.ts` 类型声明到 `.succapp/succ-types/`，为脚本编辑提供类型提示和 API 补全。
6. 从当前连接服务器下载编辑器结构提示文件，并更新 `.vscode/settings.json`，为 `.dash`、`.spg`、`.rpt`、`.fapp`、`.tbl`、`.query`、`.kdb`、`.wfl`、`.afl`、`.agent`、`.theme`、`.tpg`、`.meta`、`.jdbc`、`settings.json`、`capabilities.json` 和扩展 `package.json` 等文件提供结构提示。
7. 写入推荐的 Git 忽略和 SuccApp 同步忽略配置，避免本地运行时文件进入 Git，并避免 IDE 辅助文件同步回元数据服务器。
8. 初始化常用 AI 开发工具可识别的入口文件，并在 `.agents/` 下创建计划、评审、报告、临时文件和团队规则目录。官方离线文档同步成功后，SuccApp 会写入 `.agents/skills/succapp-docs/`，并把前端运行时内置依赖清单作为文档 skill 的资源下载到本地，供 AI 辅助编写 FTL、浏览器脚本和 CSS 时参考。

SuccApp 会尽量保留团队已有的工作区配置：根 `tsconfig.json` 只追加缺失的项目引用，`.vscode/settings.json` 只补齐缺失的推荐项。`.succapp` 下由 SuccApp 生成的辅助配置会在初始化工作区时刷新。

## 工作区文件说明{#workspace-files}

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

```text
workspace/
├── AGENTS.md                     # Codex 等 AI 工具可读取的工作区说明
├── CLAUDE.md                     # Claude Code 入口，默认引用 AGENTS.md
├── .github/
│   └── copilot-instructions.md   # GitHub Copilot 仓库级说明
├── .agents/
│   ├── README.md                 # AI 工作区说明
│   ├── plans/                    # AI 实施计划、迁移计划
│   ├── reviews/                  # AI Code Review、设计评审记录
│   ├── reports/                  # AI 调查、分析、验证报告
│   ├── rules/                    # 团队长期 AI 协作规则
│   ├── skills/                   # 官方离线文档同步成功后写入 succapp-docs/
│   └── tmp/                      # AI 临时脚本、草稿和一次性排查文件
├── .gitignore                   # 根目录 Git 忽略配置，SuccApp 会写入系统临时文件忽略片段
├── .succapp/
│   ├── .gitignore               # SuccApp 运行时文件的 Git 忽略配置
│   ├── config.json              # 当前工作区的服务器地址簿和当前活跃服务器
│   ├── remote/                  # 本地服务器基线副本
│   ├── locks/                   # 同步任务锁
│   ├── cache/                   # 本地缓存
│   ├── json-schemas/            # 编辑器结构提示辅助文件
│   ├── 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                    # 记录 project1 下直接子资源的服务器资源标识和版本信息
│   └── index.spg
├── project2/                    # 同一个工作区中可以克隆多个元数据项目
│   └── .meta                    # 记录 project2 下直接子资源的服务器资源标识和版本信息
└── tsconfig.json                # 脚本 TypeScript 诊断配置
```

## 服务器配置文件{#server-config}

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

示例结构如下：

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

::: warning 注意
`.succapp/config.json` 只保存服务器地址，不保存 PAT、OAuth2 access token 或 refresh token。认证状态由 SuccApp 的本机认证文件管理，不应提交到 Git 仓库。
:::

## Git 忽略建议{#gitignore}

初始化工作区后，SuccApp 会自动补齐默认 `.gitignore` 配置，避免 `.succapp/remote/`、缓存、锁、日志、本机同步状态和临时文件进入 Git。提交前仍应检查 Git 状态，确认项目目录和目录级 `.meta` 会被提交，而 `.succapp/remote/`、`.succapp/cache/`、`.succapp/locks/`、`.succapp/merge-base/`、`.succapp/merge-backup/`、`.succapp/*.log`、`.succapp/state.json` 不会进入提交。

完整入库和忽略建议见[工作区版本管理](./git-versioning.md)。

## 初始化后检查{#checklist}

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

1. `succapp workspace status --json` 能正常输出当前工作区状态。
2. 本地项目目录已经出现。
3. `.succapp/remote/` 没有进入 Git 提交。
4. 目录级 `.meta` 文件没有被 Git 忽略。
5. 需要脚本提示的工作区已经生成 `tsconfig.json` 和 `.succapp/succ-types/`。
6. `AGENTS.md`、`CLAUDE.md`、`.github/copilot-instructions.md` 和 `.agents/` 已生成，AI 临时文件会写到 `.agents/tmp/`。
7. 当前连接的是测试服务器，而不是生产服务器。
8. 如果使用 SuccApp for VS Code，服务器视图能看到当前服务器和项目，Changes 视图可以正常刷新。

下一步可以阅读[连接服务器与克隆项目](./connect-and-clone.md)和[修改、对比、拉取与推送](./sync-changes.md)。