# 项目级工作区

DotCraft 把整个 AI 工作流锚定在一个真实项目目录上。当你打开一个项目，它的会话历史、技能、长期记忆、自动化任务、插件、模型选择都会沉淀在那一个 `.craft/` 目录里，跟着仓库一起被备份、被分享、被恢复——而不是散落在某个云账户、某条系统提示词或某次窗口之外。

> 一个项目，一个工作区，一份持久的 Agent 状态。

## 关键概念

| 概念 | 含义 |
|---|---|
| **Workspace** | 含 `.craft/` 子目录的项目根。Desktop、TUI、ACP、Bot、Automations 都围绕同一个 workspace 工作。 |
| **Bootstrap files** | `.craft/AGENTS.md`、`.craft/SOUL.md`、`.craft/USER.md`——分别约束 Agent 的行为规则、个性与表达、用户画像。 |
| **Memory & History** | `.craft/MEMORY.md`、`.craft/HISTORY.md`——长期记忆与历史记录，由 Agent 维护、用户可读。 |
| **Skills / Plugins** | `.craft/skills/` 与 `.craft/plugins/`——工作区内自带的能力包。 |
| **Sessions** | `.craft/sessions/` 与 `.craft/threads/`——所有入口共享的会话存档。 |
| **Config** | `.craft/config.json`——工作区级配置，叠加在全局 `~/.craft/config.json` 之上。 |

## 为什么这样组织

```mermaid
flowchart TB
  subgraph Workspace[" 项目工作区 "]
    direction TB
    Code["代码 / 文档"]
    Craft[".craft/"]
    Craft -->|载入身份| Bootstrap["AGENTS.md / SOUL.md / USER.md"]
    Craft -->|长期上下文| Memory["MEMORY.md / HISTORY.md"]
    Craft -->|可复用流程| Skills["skills/ · plugins/"]
    Craft -->|会话存档| Sessions["sessions/ · threads/"]
    Craft -->|项目级配置| Config["config.json"]
  end

  Desktop --> Workspace
  TUI --> Workspace
  Editor["IDE / Editor (ACP)"] --> Workspace
  Channels["Channels / Bots"] --> Workspace
  Automations --> Workspace
```

任何入口接入工作区时，**先读这一份目录，后做事**。这样：

- 切换入口不丢上下文：在 Desktop 开启的会话可以在 TUI 继续。
- 跨设备恢复零成本：把整个项目目录同步到另一台机器即可。
- 团队协作有共同基线：把 `.craft/` 的可分享部分（skills、commands、AGENTS.md 等）提交到仓库，团队成员一开 Desktop 就拿到同一份 Agent 行为约束。

## 全局 vs 工作区配置

DotCraft 用两层配置叠加：

| 层级 | 路径 | 用途 |
|---|---|---|
| 全局 | `~/.craft/config.json` | Provider 凭据、Endpoint、个人偏好——不进仓库 |
| 工作区 | `<workspace>/.craft/config.json` | 模型选择、入口开关、自动化、安全策略——可进仓库 |

最常用的最小工作区配置：

```json
{
  "ProviderId": "anthropic",
  "Model": "claude-sonnet-4-5",
  "DashBoard": { "Enabled": true }
}
```

```json
{
  "Providers": {
    "anthropic": {
      "DisplayName": "Anthropic",
      "Protocol": "anthropic",
      "ApiKey": "${ANTHROPIC_API_KEY}"
    },
    "openrouter": {
      "DisplayName": "OpenRouter",
      "Protocol": "openai-chat-completions",
      "ApiKey": "${OPENROUTER_API_KEY}",
      "EndPoint": "https://openrouter.ai/api/v1"
    }
  }
}
```

如果你不确定字段放哪：**Provider 放全局，工作区只覆盖 `ProviderId` 和 `Model`**。完整字段见 [配置完整参考](../developing/configuration.md)。

## Bootstrap 三件套

`.craft/` 下面这三个 Markdown 决定了"这个项目里的 Agent 是谁、要遵守什么":

- `AGENTS.md` — 角色职责、行为边界、回答规则
- `SOUL.md` — 个性、语气、表达风格
- `USER.md` — 用户画像、受众背景、沟通偏好

这些文件是普通 Markdown，没有特殊语法，DotCraft 会在每个会话启动时把它们注入系统提示词。仓库自带的 [Bootstrap 模板](../resources/samples.md) 提供了 `senior-engineer` 和 `qq-group-assistant` 两套示例，可直接复制改写。

## 第一次进入

| 步骤 | 命令或动作 |
|---|---|
| 用 Desktop 打开 | 启动 Desktop → 选择项目目录 → 按引导初始化 |
| 用终端初始化 | `cd <project>` → `dotcraft setup` 按提示填写 |
| 验证 | 在 Desktop 新建会话，问 Agent："读 README 和 docs/index.md，告诉我项目怎么启动" |

完整图文流程见 [快速开始](../getting-started.md)。

## 何时打开 / 关闭哪些能力

工作区级开关一览（默认值）：

| 能力 | 配置 | 默认 |
|---|---|---|
| 长期记忆自动整理 | `Memory.AutoConsolidateEnabled` | `true` |
| Skill 自学习 | `Skills.SelfLearning.Enabled` | `true` |
| Dashboard 可视化 | `DashBoard.Enabled` | `false` |
| 本地自动化任务 | `Automations.Enabled` | `true` |
| ACP 编辑器 | `Acp.Enabled` | `false` |

把入口类（ACP 与外部渠道）和工作区行为类（Memory / Skills / Automations）分开管理，按团队风险偏好按需开启。

## 相关入口

- [快速开始](../getting-started.md) — 第一次安装、配置、运行
- [长期记忆与 Dreams](./memory.md) — `MEMORY.md` / `HISTORY.md` 怎么自动维护
- [统一会话核心](./session-core.md) — 跨入口共享的 Thread/Turn/Item 模型
- [安全与沙箱](./security.md) — 工作区边界、黑名单、OpenSandbox
- [配置完整参考](../developing/configuration.md) — 所有字段
