# 3. 核心概念：工作空间 / 项目 / 任务 + Provider

CC-Panes 用一个简单的**三层模型**来组织你的工作。理解了它，后面所有功能都会变得顺理成章。

## 三层模型：工作空间 → 项目 → 任务

```
工作空间 (Workspace)        例：「公司后端」
├── 项目 (Project)          例：用户服务（一个 Git 仓库）
│   └── 任务 (Task)         例：一个终端标签，正在跑 Claude 改 Bug
├── 项目                    例：订单服务
└── 项目                    例：公共库
```

打个比方：

- **工作空间** = 一个**文件柜**，把相关的项目收在一起。比如「公司后端」「我的开源项目」各放一个工作空间。
- **项目** = 文件柜里的一个**抽屉**，通常**对应一个 Git 仓库**。
- **任务** = 你在某个项目里**正在做的一件事**，在界面上就是**一个终端标签页**（比如一个正在运行的 Claude Code 会话）。

### 各层分别记着什么

| 层级 | 它独有的东西 |
| --- | --- |
| **项目** | 独立的启动历史、任务、Todo、本地历史（Local History）、MCP 配置 |
| **工作空间** | 默认运行环境、默认 Provider、会话日志、工作空间级 Todo |

也就是说：换项目，启动历史和文件版本是各算各的；而同一个工作空间下的项目，可以共享一套默认 Provider 和运行环境设置，省得每个项目重配。

## 干净的工作空间：把工作空间目录和 Git 仓库分开

一个强烈推荐的组织习惯：**工作空间目录是收纳容器，不是代码仓库**。

```
D:\work\erp-workspace\        ← 工作空间目录（本身不是 Git 仓库，不要 git init）
├── erp-backend\              ← Git 仓库，注册为项目
├── erp-frontend\             ← Git 仓库，注册为项目
├── erp-admin\                ← Git 仓库，注册为项目
└── docs\                     ← 跨项目的文档、方案、临时产物，随便放
```

做法很简单：为每个业务线建一个专门目录（如 `erp-workspace`），各 Git 仓库作为**子目录**放进去，然后在 CC-Panes 里对这个目录用「**扫描目录导入**」——它会自动找出下面所有 Git 仓库批量注册为项目，而容器目录本身不会被当成项目。

为什么要这样分：

- **跨项目的东西有地方放**。方案文档、会议记录、AI 产出的调研报告、临时脚本——这些不属于任何一个仓库，放在工作空间目录里就不会污染任何仓库的 `git status`。
- **仓库保持干净**。AI 干活时经常看 `git status` 判断改了什么；如果工作台杂物混在仓库里，每次都是一堆噪音，还得往 `.gitignore` 里塞例外。
- **增删互不牵连**。加一个新仓库就是 clone 进来再导入；淘汰一个仓库直接删掉子目录，其他项目不受影响。

**反例**：把工作空间直接指到某个 Git 仓库的根目录。之后所有跨项目杂物都会混进这个仓库的变更列表，AI 和你自己都分不清哪些是代码改动、哪些是工作台垃圾。

> 在侧边栏的工作空间上右键 →「**设置工作空间路径**」，把这个容器目录设为它的根目录后，文件浏览视图会以它为单根展示——整个业务线的仓库和文档都在一棵树里。

**这整套也可以让 AI 代办**：建目录、`create_workspace`（可带根目录）、`scan_directory` 扫描、批量导入项目全是 MCP 工具。在任何一个 CC-Panes 启动的 AI 会话里说一句「建一个 xxx-workspace 容器目录和同名工作空间，把某某目录下的仓库导入进来」即可，不必手点 UI。

## Provider 是什么、为什么要配

**Provider = 给 CLI 提供模型能力的"供应商通道"。**

同样是跑 Claude Code，背后连的可能是 Anthropic 官方、Bedrock、Vertex、某个 OpenAI 兼容代理，或你本地的配置。Provider 就是用来管理"这次启动到底连哪条通道、用哪个 Key"。

为什么值得配：

- **多账号切换**：公司 API 和个人 API 一键切换，不用改环境变量。
- **成本与合规**：不同供应商计费、区域不同，按需选。
- **可靠性**：主通道不可用时换备用。

### 启动时的三种 Provider 模式

每次启动一个 CLI，你可以选：

| 模式 | 含义 |
| --- | --- |
| **继承**（不指定，继承系统） | 用项目 / 工作空间的默认 Provider，最省心 |
| **显式指定** | 这一次就用我选的这个 Provider |
| **不注入** | 不传任何 Provider 环境变量，让 CLI 用它自己的本地配置 |

> 刚上手时，直接用「**不指定（继承系统）**」即可——等你有多个 API 来源了，再回来配 Provider 也不迟。

## 运行环境：本机 / WSL / SSH

启动任务时还能选**在哪里运行**：

- **本机**：直接在当前系统里跑。
- **WSL**（Windows）：在 WSL 的 Linux 环境里跑，工具链更顺手。
- **SSH**：在远程服务器上跑，本地只是个控制台。

工作空间可以设一个默认运行环境，单次启动时也能临时改。

## 你的数据存在哪

知道这个，方便你备份和排障：

```
~/.cc-panes/                  # 全局控制中心（发布版；开发版是 ~/.cc-panes-dev/）
├── config.toml               # 全局配置
├── workspaces/<名字>/        # 各工作空间（含 workspace.json、会话日志）
├── providers/providers.json  # Provider 配置
├── screenshots/              # 截图
└── data.db                   # SQLite：项目、启动历史、Todo 等

<项目路径>/.ccpanes/          # 项目级数据（跟着仓库走）
├── config.toml               # 项目配置
├── history/                  # 本地文件历史
└── hooks/                    # 工作流定义
```

此外，Claude / Codex 各自的会话上下文存在它们自己的目录（如 `~/.claude/`、`~/.codex/`），CC-Panes 的"恢复会话"正是借助这些来续上下文。

## 下一步

概念清楚了，开始动手 → [4. 上手五步](04-getting-started-5-steps.md)