### Start Yuxi development environment with Docker Compose

Source: https://github.com/xerrors/yuxi/blob/main/README.md

Builds and starts all services in detached mode. Use this after initialization to launch the development environment.

```bash
docker compose up --build -d
```

--------------------------------

### Start and inspect Yuxi development environment with Docker Compose

Source: https://github.com/xerrors/yuxi/blob/main/CONTRIBUTING.md

Starts the development environment and checks service status and API logs. Requires Docker Compose.

```bash
docker compose up -d
docker compose ps
docker compose logs --tail=100 api
```

--------------------------------

### 安装 yuxi-cli 并验证版本

Source: https://github.com/xerrors/yuxi/blob/main/docs/intro/cli.md

使用 uv tool install 安装 yuxi-cli；使用 uvx 临时运行；使用 yuxi --version 确认安装成功。

```bash
uv tool install yuxi-cli
```

```bash
uvx --from yuxi-cli yuxi --help
```

```bash
yuxi --version
```

--------------------------------

### 复制品牌配置模板

Source: https://github.com/xerrors/yuxi/blob/main/docs/advanced/branding.md

复制 `info.template.yaml` 到 `info.local.yaml`。使用 `-n` 避免覆盖已存在的文件。

```bash
cp -n backend/package/yuxi/config/static/info.template.yaml \
  backend/package/yuxi/config/static/info.local.yaml
```

--------------------------------

### 检查 provisioner 健康状态和日志

Source: https://github.com/xerrors/yuxi/blob/main/docs/advanced/sandbox-operations.md

provisioner 只在第一次操作时创建沙盒，刚启动时看不到容器是正常的。健康响应应包含 backend、runtime_profile、idle_timeout_seconds 和 tracked_sandboxes。

```bash
curl --fail http://localhost:8002/health
```

```bash
docker compose logs --tail=100 sandbox-provisioner
```

--------------------------------

### Remote source whitelist examples

Source: https://github.com/xerrors/yuxi/blob/main/docs/agents/skills-management.md

Example remote source entries for the remote source whitelist. Hostnames must match exactly; the default allowed hosts are github.com and modelscope.cn.

```text
anthropics/skills
https://github.com/anthropics/skills
https://modelscope.cn/skills/@anthropics/pdf
https://modelscope.cn/collections/MiniMax/MiniMax-Office-skills
```

--------------------------------

### 启动开发环境

Source: https://github.com/xerrors/yuxi/blob/main/docs/advanced/sandbox-operations.md

初始化 .env 后启动开发 Compose，默认配置 Docker provisioner。

```bash
docker compose up -d
```

--------------------------------

### 复制生产配置模板

Source: https://github.com/xerrors/yuxi/blob/main/docs/advanced/deployment.md

复制 .env.template 为 .env.prod，作为生产环境配置的基础。

```bash
cp .env.template .env.prod
```

--------------------------------

### GET /api/knowledge/databases/external

Source: https://github.com/xerrors/yuxi/blob/main/docs/advanced/knowledge-base-api.md

列出可见知识库。需要知识库读取权限。

```APIDOC
## GET /api/knowledge/databases/external

### Description
列出可见知识库。需要知识库读取权限。

### Method
GET

### Endpoint
/api/knowledge/databases/external

### Response
#### Success Response
返回可见知识库列表。
```

--------------------------------

### Integration tests not run due to setup errors

Source: https://github.com/xerrors/yuxi/blob/main/docs/develop-guides/decisions/implemented/2026-09-14-agent-runtime-simplification.md

Attempted integration tests but got 51 setup errors due to timeout in HTTP read during prerequisite knowledge base evaluation cleanup. Not run.

```bash
docker compose exec api timeout --signal=INT --kill-after=5s 180s uv run --no-sync --group test pytest test/integration/services/test_agent_run_lease.py test/integration/services/test_agent_request_queue_concurrency.py test/integration/api/test_agent_request_queue_router.py test/integration/services/test_agent_run_manifest_and_attempts.py -q --tb=short --disable-warnings
```

--------------------------------

### 查看知识库依赖状态和日志

Source: https://github.com/xerrors/yuxi/blob/main/docs/intro/quick-start.md

查看 Milvus、etcd、MinIO 和 Neo4j 的状态和日志。这些服务是默认拓扑的一部分，启动脚本正常退出不等于依赖健康。

```bash
docker compose ps milvus etcd minio graph
docker compose logs --tail=100 milvus etcd minio graph
```

--------------------------------

### SKILL.md frontmatter example

Source: https://github.com/xerrors/yuxi/blob/main/docs/agents/skills-management.md

Example SKILL.md with YAML frontmatter. Required fields are name and description; slug is optional but recommended. Omitting slug uses name, which must then be lowercase letters, digits, and single hyphens.

```markdown
---
name: 文档整理
slug: document-cleanup
description: 按指定结构整理文档，并保留可核对的来源。
tool_dependencies: []
mcp_dependencies: []
skill_dependencies: []
---

# 文档整理

## 何时使用

说明这个 Skill 解决什么问题，以及什么时候不该使用。

## 操作步骤

写出 Agent 应遵循的步骤、限制和验收方式。
```

--------------------------------

### 显式注册执行后端 (Python)

Source: https://github.com/xerrors/yuxi/blob/main/docs/agents/agent-backend-development.md

在 buildin/__init__.py 中通过显式字典注册执行后端。字典键是稳定后端 ID，Python 类重命名不改变该 ID；仅增加目录或导出类不会启用后端。

```python
BUILTIN_BACKENDS = {
    "ChatbotAgent": ChatbotAgent,
    "SubAgentBackend": SubAgentBackend,
}
```

--------------------------------

### GET /api/knowledge/databases/external/{kb_id}/files

Source: https://github.com/xerrors/yuxi/blob/main/docs/advanced/knowledge-base-api.md

列出或按文件名搜索文件。需要知识库读取权限。

```APIDOC
## GET /api/knowledge/databases/external/{kb_id}/files

### Description
列出或按文件名搜索文件。需要知识库读取权限。

### Method
GET

### Endpoint
/api/knowledge/databases/external/{kb_id}/files

### Parameters
#### Path Parameters
- **kb_id** (string) - Required - 知识库 ID

#### Query Parameters
- **query** (string) - Optional - 文件名搜索关键词

### Response
#### Success Response
返回文件列表。
```

--------------------------------

### 后端目录结构 (text)

Source: https://github.com/xerrors/yuxi/blob/main/docs/agents/agent-backend-development.md

随服务发布的 Agent 后端应放在 backend/package/yuxi/agents/buildin/<your_agent>/ 目录下，包含 __init__.py、context.py 和 graph.py。

```text
backend/package/yuxi/agents/buildin/<your_agent>/
├── __init__.py
├── context.py
└── graph.py
```

--------------------------------

### 查看容器状态 (docker compose ps)

Source: https://github.com/xerrors/yuxi/blob/main/docs/advanced/deployment.md

使用 docker compose 查看生产环境容器状态，需指定环境文件 .env.prod 和 Compose 文件 docker-compose.prod.yml。

```bash
docker compose --env-file .env.prod -f docker-compose.prod.yml ps
```

--------------------------------

### GET /api/user/apikey/

Source: https://github.com/xerrors/yuxi/blob/main/docs/advanced/api-key-integration.md

查看当前用户可见的 API Key 列表。

```APIDOC
## GET /api/user/apikey/

### Description
查看当前用户可见的 API Key 列表。

### Method
GET

### Endpoint
/api/user/apikey/

### Response
#### Success Response (200)
- **api_key** (array) - 包含 id、key_prefix、name、user_id、is_enabled、last_used_at。
- **last_used_at** (string/null) - 最近一次成功认证时间，null 表示尚未使用。
- **key_prefix** (string) - 用于识别 Key，服务端不会再次返回完整 secret。
```

--------------------------------

### 应用层连接 provisioner 的环境变量

Source: https://github.com/xerrors/yuxi/blob/main/docs/advanced/sandbox-operations.md

API 和 worker 至少需要这些环境变量来连接 provisioner。`SANDBOX_PROVISIONER_TOKEN` 必须至少 32 个字符，且不能进入 `sandbox.env`、用户 Agent 环境、Skill 或模型上下文。`SANDBOX_VIRTUAL_PATH_PREFIX` 是 Agent 使用的虚拟用户数据根。

```bash
SANDBOX_PROVIDER=provisioner
SANDBOX_PROVISIONER_URL=http://sandbox-provisioner:8002
SANDBOX_PROVISIONER_TOKEN=<random-value-at-least-32-characters>
SANDBOX_VIRTUAL_PATH_PREFIX=/home/gem/user-data
SANDBOX_EXEC_TIMEOUT_SECONDS=180
SANDBOX_MAX_OUTPUT_BYTES=262144
```

--------------------------------

### GET /api/knowledge/databases/external/{kb_id}/files/{file_id}/open

Source: https://github.com/xerrors/yuxi/blob/main/docs/advanced/knowledge-base-api.md

按行打开解析后的 Markdown。需要知识库读取权限。

```APIDOC
## GET /api/knowledge/databases/external/{kb_id}/files/{file_id}/open

### Description
按行打开解析后的 Markdown。需要知识库读取权限。

### Method
GET

### Endpoint
/api/knowledge/databases/external/{kb_id}/files/{file_id}/open

### Parameters
#### Path Parameters
- **kb_id** (string) - Required - 知识库 ID
- **file_id** (string) - Required - 文件 ID

### Response
#### Success Response
返回解析后的 Markdown 内容，默认从第 0 行开始读取，单次最多 1800 行。
```

--------------------------------

### 初始化环境 (Linux/macOS)

Source: https://github.com/xerrors/yuxi/blob/main/docs/intro/quick-start.md

运行初始化脚本，交互式生成 .env 文件并拉取基础镜像。脚本不会打印密钥，Linux/macOS 下会将 .env 权限设为 600。

```bash
./scripts/init.sh
```

--------------------------------

### GET /api/agent/runs/{run_id}/result

Source: https://github.com/xerrors/yuxi/blob/main/docs/advanced/api-key-integration.md

Reads the final result of a run. This endpoint is read-only and does not re-execute the run. The final output must be read from the result bound to this `run_id`.

```APIDOC
## GET /api/agent/runs/{run_id}/result

### Description
Reads the final result of a run. This endpoint is read-only and does not re-execute the run. The final output must be read from the result bound to this `run_id`.

### Method
GET

### Endpoint
/api/agent/runs/{run_id}/result

### Parameters
#### Path Parameters
- **run_id** (string) - Required - The run ID.

### Response
#### Success Response (200)
- **result** (object) - The final result of the run.

#### Response Example
{
  "result": {}
}
```