DotCraft Workspace 示例

这个示例提供了一个基于源码仓库的 DotCraft workspace，你可以直接在当前仓库副本中运行它，适合开发机或云服务器上的长期工作区场景。

它包含：

• start.sh：从当前仓库构建并启动 DotCraft
• start-sandbox.sh 和 start-sandbox.ps1：启动可选的 OpenSandbox 服务
• config.template.json：安全的 workspace 配置示例

开始前先说明

对大多数第一次使用 DotCraft 的用户，更安全的默认路径仍然是：

cd /path/to/your-project
dotcraft setup --language Chinese --model <model> --endpoint <endpoint> --api-key <key> --profile developer

完成 setup 后，.craft/ 会包含工作区配置和基础说明文件。

只有当你明确想要一个可复用的源码工作区，或者希望在服务器上保留一套长期运行的 workspace 时，才更适合使用 samples/workspace。

示例内容

文件	用途
start.sh	从当前仓库构建 DotCraft，并在 samples/workspace 中启动 Gateway
start-sandbox.sh	在 Linux / macOS 上启动 OpenSandbox
start-sandbox.ps1	在 Windows PowerShell 上启动 OpenSandbox
config.template.json	可作为起点复制到你自己 workspace 中的安全示例配置
.craft/config.json	你本地创建并使用的真实工作区配置；由于可能包含私密数据，不会随仓库一起分发
.craft/dashboard/*	本地运行后产生的 Dashboard 运行产物，不会随仓库一起分发
.craft/sessions/*	本地运行后产生的会话产物，不会随仓库一起分发

前置条件

推荐默认路径

• 你的机器上已经安装或构建好 DotCraft
• 你有一个实际要使用的项目目录作为 workspace

如果你要使用 start.sh

• Bash
• .NET 10 SDK
• 当前仓库已经 clone 到本地
• 如果想在 Linux 服务器上后台运行，还需要 screen

如果你要使用可选的 sandbox 脚本

• Docker 已启动，并且当前 shell 可以访问
• OpenSandbox Server 已安装，且可通过 PATH 找到
• 默认存在 ~/.sandbox.toml 基础配置，或通过 SANDBOX_CONFIG_PATH 指向该文件
• Windows：PowerShell 和 python
• Linux / macOS：bash 和 python3

快速开始

方式一：推荐给新用户

在你的真实项目目录里运行 setup，创建 .craft/：

cd /path/to/your-project
dotcraft setup --language Chinese --model <model> --endpoint <endpoint> --api-key <key> --profile developer

方式二：直接运行本示例 workspace

cd samples/workspace
mkdir -p .craft
cp config.template.json .craft/config.json
bash start.sh

如果你想复用这个 sample 里推荐的 Dashboard / Sandbox 示例字段，应该先从 config.template.json 复制。

如果你在 Linux 服务器上运行，也可以配合 screen 后台启动：

cd samples/workspace
screen -dmS dotcraft bash -c "bash start.sh"

配置说明

DotCraft 会先读取全局配置 ~/.craft/config.json，再叠加 <workspace>/.craft/config.json 中的 workspace 覆盖项。

对于这个示例：

• 密钥类信息尽量放在 ~/.craft/config.json
• 用 samples/workspace/config.template.json 作为示例参考
• 只把需要的字段复制到你自己的 <workspace>/.craft/config.json
• 不要假设仓库分发时会带上 .craft/config.json，因为它通常包含私密数据并被忽略
• 不要因为这个 sample 本地存在 .craft/config.json，就直接覆盖已经在使用中的真实配置

建议使用方式：

1. 先查看 config.template.json
2. 把你需要的字段复制到自己的 .craft/config.json
3. 不要把机器相关路径、密钥、私有服务地址直接保留在共享 sample 中

模板里最常需要修改的字段：

字段	建议修改内容
DashBoard.Host / DashBoard.Port	如果本机绑定地址或端口不同，需要按实际环境调整
Tools.Sandbox.Enabled	只有实际运行 OpenSandbox 时才开启
Tools.Sandbox.Domain	改成你自己的 OpenSandbox 地址，并且不要和 Dashboard 端口冲突
Tools.Sandbox.Image	替换成你希望 sandbox 使用的容器镜像

推荐启动顺序

不使用 sandbox

1. 用 dotcraft gateway 或 bash start.sh 启动 DotCraft
2. 如果 DotCraft 提示进入 Dashboard，先完成初始化配置
3. 保存配置后，重新正常启动 DotCraft

使用 sandbox

1. 先确认 Docker 和 OpenSandbox 前置条件满足
2. 启动对应平台的 sandbox 脚本
3. 从 config.template.json 中复制需要的 sandbox 字段到你自己的 .craft/config.json
4. 再运行 dotcraft gateway

使用 QQ / NapCat

1. 先启动 NapCat
2. 再运行 dotcraft gateway
3. 确认 QQ 外部渠道配置已启用，并且服务地址正确

可选：QQ / NapCat

这个示例本身不依赖 QQ 集成。只有在你要测试 QQ 外部渠道场景时，才需要这一步。

Linux 示例：

screen -dmS napcat bash -c "napcat"

另外仍然需要在 DotCraft 配置中单独启用 QQ 外部渠道。

可选：Tool Sandbox

sandbox 启动脚本是可选辅助工具。只有当你希望 Shell / File 工具在 OpenSandbox 容器中执行，而不是直接在宿主机执行时，才需要它们。

运行前检查

Windows PowerShell：

docker info
python --version
opensandbox-server --help

Linux / macOS：

docker info
python3 --version
opensandbox-server --help

基础配置文件

sandbox 脚本默认会读取 ~/.sandbox.toml 作为基础配置。如果你的文件放在别的位置，请先设置 SANDBOX_CONFIG_PATH。

可以用下面的命令生成默认基础配置：

opensandbox-server init-config ~/.sandbox.toml --example docker

端口注意事项

不要让 Dashboard 和 OpenSandbox 使用同一个端口。提供的 config.template.json 会特意把两者分开，避免冲突。

在 Windows 上启动

请在 PowerShell 中运行：

.\start-sandbox.ps1

如果你的机器默认禁止执行本地脚本，需要先调整 PowerShell 执行策略，或者在允许本地脚本的 PowerShell 环境里运行。

在 Linux / macOS 上启动

bash ./start-sandbox.sh

如何确认运行正常

启动后，你应该能确认：

• DotCraft 能正常启动，没有配置错误
• Dashboard 能通过配置的 host 和 port 访问
• 开启 sandbox 时，辅助脚本会输出使用的配置路径和监听端口
• 如果启用了 QQ / NapCat，对应服务也处于在线状态

常见问题

缺少 dotnet 或构建工具

先安装 .NET 10 SDK，并执行 dotnet --info 确认环境正常，再运行 start.sh。

screen: command not found

安装 screen，或者直接在前台运行 bash start.sh。

找不到 opensandbox-server

请用能把可执行文件放到 PATH 的方式安装 OpenSandbox Server，或者通过 OPENSANDBOX_SERVER_EXE 指向完整可执行文件路径。

Docker 已安装，但脚本还是失败

先在同一个 shell 里运行 docker info。在 Linux 上，还要确认当前 shell 会话已经具备访问 Docker 的权限。

缺少 sandbox 基础配置

用下面的命令创建 ~/.sandbox.toml：

opensandbox-server init-config ~/.sandbox.toml --example docker

或者把 SANDBOX_CONFIG_PATH 指向一个已存在的配置文件。

sandbox 和 Dashboard 抢同一个端口

修改 DashBoard.Port 或 Tools.Sandbox.Domain，确保两者不冲突。