# DotCraft Dashboard API

Dashboard API 面向调试界面和内部工具。普通用户通常只需要使用 Dashboard 页面；需要写集成或排查前端问题时再查本页。

## 独立只读查看器

可以只启动 Dashboard，不启动 AppServer、Desktop、TUI、channels、Dreams、Automations、MCP 或 LSP：

```bash
dotcraft dashboard --workspace /path/to/workspace
dotcraft dashboard --workspace /path/to/workspace --host 127.0.0.1 --port 8081
```

`--workspace` 可以传工作区根目录，也可以传 `.craft` 目录；不传时使用当前目录。该模式会忽略 `DashBoard.Enabled`，但会复用配置里的 `DashBoard.Host`、`DashBoard.Port`、`Username` 和 `Password`，除非命令行传入 `--host` 或 `--port` 覆盖。

只读模式只暴露 trace、会话列表、token 用量、工具、runtime 元数据和事件流接口。它不会注册 Settings 写入接口、Dreams 接口、Automations 接口或 session/thread 删除接口，并且只读取已有的 `state.db`，不会创建或迁移工作区状态。

## Trace 事件类型

| 类型 | 说明 |
|------|------|
| `SessionMetadata` | 会话系统提示词和工具 schema 元数据 |
| `Request` | 用户请求 |
| `Response` | 模型响应内容段 |
| `ToolCallStarted` | 工具调用开始 |
| `ToolCallCompleted` | 工具调用完成 |
| `ToolInjection` | simulated 延迟加载向下一轮模型请求注入工具 schema |
| `DeferredToolLoading` | Responses native 延迟加载通过 `tool_search` 激活 deferred tools |
| `TokenUsage` | 单次 LLM 请求 token 用量 |
| `Error` | 运行错误 |
| `ContextCompaction` | 上下文压缩 |
| `Thinking` | 模型思考内容段 |
| `PromptCachePoint` | prompt cache 断点摘要 |
| `PromptCacheDiagnostic` | prompt cache 命中/断裂诊断 |
| `MaintenanceForkRequest` | 维护型 fork 请求 |
| `MaintenanceForkResponse` | 维护型 fork 响应 |

Dashboard 的 `Thinking` 和 `Response` trace 事件按连续 streaming 内容段记录，而不是按每个 chunk 记录，也不是整轮强制合并为单条。`ThinkingCount` 和 `ResponseCount` 因此表示对应内容段数量。实时事件流会在当前段结束并落库时发送该段事件；历史 trace 不迁移，旧数据可能仍保留旧粒度。

上下文压缩和记忆整理等维护请求会额外记录 `MaintenanceForkRequest` / `MaintenanceForkResponse`。这些事件保留维护请求的 snapshot/cache 元数据、模型原始文本、tool-call-only 响应、空响应和 fallback reason，便于从 Dashboard 诊断 `summary_unavailable` 一类问题。

`DeferredToolLoading` 用于 Responses native 延迟工具加载。它记录本次由 `tool_search` 新激活的工具、配置策略、实际生效模式和 provider protocol；该事件不代表顶层 `tools` 被注入，也不会标记为 prompt-cache tool extension。

## 端点

### `GET /DashBoard`

返回 Dashboard 页面。

### `GET /DashBoard/api/summary`

返回运行摘要，包括会话数量、最近事件和模块状态。

### `GET /DashBoard/api/sessions`

返回 Dashboard 可见的会话列表。

### `GET /DashBoard/api/sessions/{sessionKey}/events`

返回指定会话的 Trace 事件。

### `GET /dashboard/api/runtime`

返回 Dashboard 宿主模式和能力标记。在独立只读模式下，`mode` 为 `readOnly`，`readOnly` 为 `true`，并且 `settings`、`dreams`、`automations`、`sessionDeletion` 能力均为 `false`。

### `GET /dashboard/api/orchestrators/automations/state`

返回 Automations 编排器状态，包括本地任务和 Cron 摘要。

### `POST /dashboard/api/orchestrators/automations/refresh`

请求刷新 Automations 状态。

### `GET /dashboard/api/config/schema`

返回 Dashboard Settings 页面使用的配置 schema。

### `GET /dashboard/api/dreams/status`

返回当前工作区 Dreams 配置、运行状态、active store 和最近一次运行。

### `GET /dashboard/api/dreams/runs`

返回 Dreams 运行记录。默认不包含 archived 运行。

### `GET /dashboard/api/dreams/runs/{runId}`

返回单次 Dreams 运行详情、active/output index 预览和 topic 路径，供 Dashboard 审阅页使用。

### `POST /dashboard/api/dreams/run`

请求立即运行一次 Dreams。

### `POST /dashboard/api/dreams/runs/{runId}/{action}`

执行 Dreams 审阅动作。`action` 支持 `apply`、`discard`、`archive`、`cancel`。
`apply` 也用于将任意成功且未丢弃/归档的 run 设为 active store。

### `DELETE /api/sessions/{sessionKey}`

删除指定 Dashboard 会话记录。

### `DELETE /api/sessions`

清空 Dashboard 会话记录。

### `GET /api/events/stream`

返回 Dashboard 使用的事件流。

## 使用建议

- API 路径大小写沿用现有 Dashboard 路由。
- 独立只读模式下，被禁用的功能和写入接口会返回 404 或 405，因为这些路由不会被注册。
- 调试本地页面时优先绑定 `127.0.0.1`。
- 生产或共享网络环境中不要暴露未加保护的 Dashboard。
