cc-monitor (dsh-cc-monitor)

1. 安装并启动 DeepSeek Harness：npx @deepseek-ai/dsh web
2. 在终端执行上面的安装命令（CLI 会解析插件并核验来源）
3. 用 dsh plugins list 确认已安装，必要时重启 Harness 生效

插件以当前 dsh 进程的权限运行，安装时可能执行代码。请先通读仓库源码与许可证，确认无破坏性命令与越权访问；本站只做索引，不对第三方插件安全性作担保。

事实信息来自公开插件目录快照（2026-10-01），介绍文案由本站再加工。

以下为插件仓库 README 全文（原始内容，由公开目录抓取整理）。

**[English](#english)** | **[中文](#chinese)**

---

# 🚦 cc-monitor — Cyber Traffic Light for Claude Code & DSH
Claude Code / DSH 赛博红绿灯

[**→ Open Dashboard**](https://bolunhan.github.io/cc-monitor/)

[![gitlab](https://gitlab.com/BolunHan/cc-monitor/badges/main/pipeline.svg)](https://gitlab.com/BolunHan/cc-monitor/-/pipelines)

> **CI runs on the GitLab mirror pipeline.** GitHub Actions is disabled in this
> repository — see `.github/workflows/README.md`.

**Know when Claude needs you — before you waste time staring at the screen.**

Physical "Claude Code traffic light" gadgets sell for serious money. cc-monitor is the **free, open-source version** — it runs on any machine, pushes notifications to your phone and browser, and costs nothing. All you need is an Android phone or a browser tab.

> 🛡️ **Guard your vibe-coding flow.** When Claude is working, you're free. The moment it needs approval, hits an error, or finishes a review — you get pinged. No more babysitting the terminal.

---

## ⚠️ Security Warning

**Only install this tool from a trusted source.** The hook installer modifies `~/.claude/settings.json` — Claude Code's global configuration file. **A malicious hook script can steal your Claude API token** and gain full access to your Anthropic account. Never install hooks from a server you don't control.

- **Always inspect** the install script before running it: `curl -skSL /static/install-hooks.sh | less`
- **Verify the source** — this repo is the only official distribution
- **Do NOT use sudo** — the hook scripts do not require root privileges and only modify your user-level Claude Code settings
- **Use localhost** when the server runs on the same machine (no auth required)

---

## Quick Start

### Option A: Docker from GHCR (no clone needed)

Pulls the pre-built image from GitHub Container Registry:

```bash
mkdir cc-monitor && cd cc-monitor
curl -O https://raw.githubusercontent.com/BolunHan/cc-monitor/main/docker-compose.yaml
docker compose up -d
```

### Option B: Docker local build (clone repo)

Build the image yourself from source:

```bash
git clone https://github.com/BolunHan/cc-monitor.git
cd cc-monitor
docker build -t ghcr.io/bolunhan/cc-monitor:latest .
docker compose up -d
```

> **💾 Data persistence:** all state (sessions, pairing tokens, approved
> devices, certs) lives in `~/.cc-monitor/docker/data` — a plain host folder
> bind-mounted at `/data/.cc-monitor` inside the container. It survives
> `docker compose restart`, `down`, `down -v`, and image upgrades, and is easy
> to back up. It stays **out** of `~/.cc-monitor` itself so a native cc-monitor
> on the same host doesn't share/conflict with the same files. If you run
> compose via `sudo`, preserve your home directory:
> `sudo env HOME=$HOME docker compose up -d` (the Makefile already does this).
> The server auto-detects the mount and warns at startup when no persistent
> storage is found.

### Option C: Native Python

```bash
git clone https://github.com/BolunHan/cc-monitor.git
cd cc-monitor
pip install .
cc-monitor --port 9876 --host 0.0.0.0
```

### Then: Install Hooks

On the machine where Claude Code runs:
```bash
curl -skSL https://:9876/static/install-hooks.sh | SERVER_URL=https://:9876 bash
```

> **🔐 One-time cert step:** Open `https://:9876` in your browser, click **Advanced** → **Proceed to site** to trust the self-signed certificate. Required when using the remote dashboard.

### Install the DSH Reporter Plugin

On the machine running DeepSeek Harness (DSH), install from npm (the default,
published automatically by the GitHub Actions release):

```bash
dsh plugin --profile web add dsh-cc-monitor
```

Fallback — install from the GitHub release tarball:

```bash
bash <(curl -fsSL https://raw.githubusercontent.com/BolunHan/cc-monitor/main/scripts/install-dsh-plugin.sh) https://github.com/BolunHan/cc-monitor/releases/latest/download/dsh-cc-monitor.tgz
```

Then restart `dsh web`. Verify with `dsh --profile web --dump-config` — you
should see a `cc-monitor` row. The plugin appears in **DSH Web UI → Settings →
Plugins → Plugin configuration**, where you can configure Enabled, Server URL,
Host, Port, and Installation UID. It defaults to `http://127.0.0.1:9876`,
auto-falls-back to HTTPS, and accepts the local self-signed cert. DSH sessions
appear with a blue `DSH` badge in the same dashboard, next to Claude Code's
orange-red `CC` badge.

---

## Web Dashboard

Powerful zero-install monitoring — works from any browser.

**Local:** Open `https://localhost:9876` — connects automatically.

**Remote (GitHub Pages):** Go to [bolunhan.github.io/cc-monitor](https://bolunhan.github.io/cc-monitor/), open **Settings** (⚙), enter your server IP and port, then **Save & Reconnect**.

> 💡 **Browser notifications** work as a free alternative to the Android app — enable them when prompted and get pinged on state changes even without your phone nearby.

### What you can do

| Action               | How                                                                  |
| -------------------- | -------------------------------------------------------------------- |
| See all sessions     | Active / Complete / Archived tabs with live state breakdown          |
| Get notified         | Browser push notifications on idle, pending review, pending approval |
| **Answer approvals** | A pending prompt appears on the session card — Allow / Deny (or pick an option for `AskUserQuestion`, Approve / Reject a plan) |
| **Send a directive** | Type into the session card's input and press Enter                   |
| **Stop a task**      | Stop button on the session card; Resume (or sending a directive) lifts it |
| Pair devices         | QR code + 6-digit approval flow for the Android app                  |
| Manage hooks         | One-click install / uninstall / check from the Settings panel        |
| Switch language      | EN / 中文 toggle in the top bar                                      |

### Remote control

cc-monitor is not just a viewer — it is a two-way channel, and the agent is
steered from the dashboard.

**Approvals.** When a hook has a UI connected, its `PermissionRequest` hook
holds the local dialog open and waits for an answer from the dashboard. If
nobody answers — or no UI is connected at all — the hook returns immediately
and the normal terminal prompt appears, exactly as it would without
cc-monitor. That gating is deliberate: remote approval must never slow down
the terminal for someone who is sitting at it.

**Directives.** A directive is queued and handed to the agent by the `Stop`
hook at its next turn boundary, as hook feedback. At that boundary, a
connected UI also gets a short window to send a follow-up, so the common case
("it just finished, one more thing…") lands without waiting for another turn.

**Stop.** Claude Code exposes no external interrupt, so stop is cooperative:
the `PreToolUse` hook denies tool calls and ends the turn. The agent stops
touching things and summarizes where it got to. Sending a directive (or
pressing Resume) clears the stop.

> ⚠️ An answer sent after the terminal prompt has already been answered is
> reported as **"Too late — answer at the terminal"** rather than silently
> claiming success.

---

## Android App

Turn your phone into a dedicated Claude Code status monitor.

### Getting the app

Download the latest APK from [Releases](https://github.com/BolunHan/cc-monitor/releases) and install via ADB:
```bash
adb install cc-monitor-app-release.apk
```

### Connecting to a server

**LAN Scan (auto-discovery):**
1. Make sure the server is running with `--host 0.0.0.0` (mDNS is on by default)
2. Open the app — it auto-scans your local network
3. Tap a discovered server to pair

**QR Code Scan:**
1. In the web dashboard, click **⧉** (Pair Device) to show a QR code
2. In the app, tap **Scan QR Code** and point your camera
3. Pairing completes automatically

**Manual Entry:**
1. Tap **Manual Entry** in the app
2. Enter the server IP, port, and token (from the web dashboard's pairing panel)

### Managing servers

Open **Settings** (⚙) from the dashboard. You'll see:
- **Server cards** with connection status dots (green = connected, orange = disconnected, grey = inactive)
- **Forget** button on every server — removes it from your list
- **Pair New Server** to add another Claude Code instance
- **Language** switcher (System default / English / 中文)

---

## Session States — Your Traffic Light

| Light | State              | What it means                                              | Your move            |
| ----- | ------------------ | ---------------------------------------------------------- | -------------------- |
| 🔵     | `working`          | Claude is coding, running tools, generating output         | Go grab coffee ☕     |
| 🟢     | `pending_review`   | Claude finished — output ready for you                     | Review the results   |
| 🟡     | `pending_approval` | Claude needs permission (tool approval, permission prompt) | Approve or deny      |
| ⚪     | `idle`             | Nothing happening — session dormant                        | Send the next prompt |
| ✅     | `all_done`         | Session ended                                              | Archive and move on  |

**You get notified instantly** via browser push and/or Android notification on every state change that needs your attention.

---

## How It Works

```
Claude Code                    cc-monitor                  Web Dashboard
  (hooks)                        Server                    Android App
     |                             |  |
     |  POST /api/event            |  |  SSE stream
     +-----------------------------+  +---------------------->
                                   |
                                   +-- State files (~/.cc-monitor/)
                                   +-- mDNS (LAN discovery)
                                   +-- TLS + Token Auth
```

The server listens for 7 Claude Code hook events, tracks session state in memory, persists to disk, and pushes real-time updates to all connected clients via Server-Sent Events. The web dashboard and Android app render live session cards with color-coded states.

For the full technical reference, see [API Reference](#api-reference) and [Architecture](#architecture).

---

## API Reference

| Method   | Path                                  | Auth   | Description                                    |
| -------- | ------------------------------------- | ------ | ---------------------------------------------- |
| `POST`   | `/api/event`                          | Yes    | Submit a hook event                            |
| `GET`    | `/api/status`                         | Yes    | All sessions                                   |
| `GET`    | `/api/status/`                    | Yes    | Single session                                 |
| `GET`    | `/api/stream`                         | Token¹ | SSE stream (state_update + heartbeat every 3s) |
| `GET`    | `/api/version`                        | No     | Server version                                 |
| `GET`    | `/api/hooks-status`                   | Yes    | Hook installation status                       |
| `POST`   | `/api/install-hooks`                  | Yes²   | Install hooks globally                         |
| `POST`   | `/api/uninstall-hooks`                | Yes²   | Remove cc-monitor hooks                        |
| `POST`   | `/api/session//archive`           | Yes    | Archive session                                |
| `POST`   | `/api/session//unarchive`         | Yes    | Unarchive session                              |
| `POST`   | `/api/session//complete`          | Yes    | Mark session done                              |
| `POST`   | `/api/session//respond`           | Yes    | Answer a pending request                       |
| `POST`   | `/api/session//directive`         | Yes    | Queue a directive for the agent                |
| `GET`    | `/api/session//directive/next`    | Yes    | Long-poll for a directive (Stop hook)          |
| `POST`   | `/api/session//stop`              | Yes    | Ask the agent to stop                          |
| `POST`   | `/api/session//resume`            | Yes    | Clear a stop request                           |
| `GET`    | `/api/request//decision`         | Yes    | Long-poll for an approval (PermissionRequest hook) |
| `GET`    | `/api/auth/pair/qr`                   | No     | QR pairing payload                             |
| `POST`   | `/api/auth/pair/request`              | No     | Submit pairing request                         |
| `GET`    | `/api/auth/pair/request//status`  | No     | Poll request status                            |
| `POST`   | `/api/auth/pair/request//approve` | No     | Approve (localhost only)                       |
| `DELETE` | `/api/auth/devices/`              | Yes    | Revoke device                                  |
| `GET`    | `/api/auth/devices`                   | Yes    | List paired devices                            |

¹ Token via `?token=` query parameter (EventSource limitation)
² Requires localhost access

---

## Architecture

```
cc-monitor/
|--  src/cc_monitor/       # Python package (FastAPI server)
|--  hooks/                # Hook scripts (stdlib-only, no deps)
|--  static/               # Web dashboard (vanilla HTML/CSS/JS)
|--  scripts/              # install-hooks.sh, uninstall-hooks.sh, build-dev-docker.sh
|--  android_app/          # Flutter Android app
|--  tests/                # pytest suite (229 tests)
|--  Dockerfile            # Python server image
|--  Dockerfile.dev        # Agent sandbox for development/testing
|--  Dockerfile.flutter    # Flutter build image
|--  docker-compose.yaml   # Docker deployment
+--  docker-compose.dev.yaml  # Dev sandbox (separate port, separate state)
```

## Development

```bash
pip install -e ".[dev]"
pytest tests/ -q          # 229 tests
cc-monitor --port 9876    # Start dev server
```

### Testing against a real agent

The host's cc-monitor is often in use, so there is a sandbox: a throwaway
container with Claude Code CLI + dsh + cc-monitor on its own port, own state
directory, and no shared state with the live instance.

```bash
./scripts/build-dev-docker.sh          # build (cached) + start on :9877
./scripts/build-dev-docker.sh --shell  # run an agent inside it
```

See **[DEV-DOCKER.md](DEV-DOCKER.md)** for the caching model, the auth seeding,
and the known limitations.

---

# 🚦 cc-monitor — Claude Code / DSH 赛博红绿灯

[**→ 打开仪表盘**](https://bolunhan.github.io/cc-monitor/)

[![gitlab](https://gitlab.com/BolunHan/cc-monitor/badges/main/pipeline.svg)](https://gitlab.com/BolunHan/cc-monitor/-/pipelines)

> **CI 运行在 GitLab 镜像流水线上。** 本仓库已停用 GitHub Actions — 见
> `.github/workflows/README.md`。

**Claude 需要你的时候，第一时间知道 — 不再白白盯着屏幕浪费时间。**

市面上那些"Claude Code 物理红绿灯"小玩意卖得可不便宜。cc-monitor 是**免费的、开源的替代方案** — 跑在任何机器上，推送到你的手机和浏览器，一毛钱不花。你只需要一台 Android 手机或一个浏览器标签页。

> 🛡️ **守护摸鱼时光安全，及时提醒手动接管 Claude Code。** Claude 干活时你自由，需要审批、出错、或完成审查的那一刻 — 你立刻收到通知。再也不用守着终端。

---

## ⚠️ 安全警告

**仅从可信来源安装此工具。** Hook 安装脚本会修改 `~/.claude/settings.json` — Claude Code 的全局配置文件。**恶意 hook 脚本可以窃取你的 Claude API token**，获得对你 Anthropic 账户的完全访问权限。切勿从不受你控制的服务器安装 hook。

- **务必先检查**安装脚本：`curl -skSL /static/install-hooks.sh | less`
- **验证来源** — 此仓库是唯一的官方分发渠道
- **切勿使用 sudo** — hook 脚本无需 root 权限，仅修改用户级别的 Claude Code 配置
- **优先使用 localhost** — 当服务器运行在同一台机器上时无需认证

---

## 快速开始

### 方案 A：Docker（无需克隆仓库）

从 GitHub Container Registry 拉取预构建镜像：

```bash
mkdir cc-monitor && cd cc-monitor
curl -O https://raw.githubusercontent.com/BolunHan/cc-monitor/main/docker-compose.yaml
docker compose up -d
```

### 方案 B：Docker 本地构建（克隆仓库）

从源码自行构建镜像：

```bash
git clone https://github.com/BolunHan/cc-monitor.git
cd cc-monitor
docker build -t ghcr.io/bolunhan/cc-monitor:latest .
docker compose up -d
```

### 方案 C：原生 Python

```bash
git clone https://github.com/BolunHan/cc-monitor.git
cd cc-monitor
pip install .
cc-monitor --port 9876 --host 0.0.0.0
```

### 然后：安装 Hook

在运行 Claude Code 的机器上执行：
```bash
curl -skSL https://<服务器IP>:9876/static/install-hooks.sh | SERVER_URL=https://<服务器IP>:9876 bash
```

> **🔐 一次性证书步骤：** 在浏览器中打开 `https://<服务器IP>:9876`，点击 **高级** → **继续访问** 以信任自签名证书。使用远程仪表盘时必须执行此步骤。

### 安装 DSH 上报插件

在运行 DeepSeek Harness（DSH）的机器上，从 npm 安装（默认方式，由 GitHub Actions 发布自动发布）：

```bash
dsh plugin --profile web add dsh-cc-monitor
```

备用方式 — 从 GitHub Release tarball 安装：

```bash
bash <(curl -fsSL https://raw.githubusercontent.com/BolunHan/cc-monitor/main/scripts/install-dsh-plugin.sh) https://github.com/BolunHan/cc-monitor/releases/latest/download/dsh-cc-monitor.tgz
```

然后重启 `dsh web`。运行 `dsh --profile web --dump-config` 验证，应该能看到 `cc-monitor` 行。插件会出现在 **DSH Web UI → Settings → Plugins → Plugin configuration** 中，可配置 Enabled、Server URL、Host、Port 和 Installation UID。默认上报到 `http://127.0.0.1:9876`，并会自动回退到 HTTPS、接受本机自签名证书。DSH 会话会在同一仪表盘中显示蓝色 `DSH` 徽章，与 Claude Code 的橙红色 `CC` 徽章并列。

---

## Web 仪表盘

功能强大的零安装监控 — 任何浏览器都能用。

**本地访问：** 打开 `https://localhost:9876` — 自动连接。

**远程访问（GitHub Pages）：** 前往 [bolunhan.github.io/cc-monitor](https://bolunhan.github.io/cc-monitor/)，打开 **设置**（⚙），输入服务器 IP 和端口，然后 **保存并重连**。

> 💡 **浏览器通知** 可作为 Android 应用的免费替代 — 被提示时启用，即可在状态变化时收到提醒，即使手机不在身边。

### 功能一览

| 功能             | 操作方式                                                 |
| ---------------- | -------------------------------------------------------- |
| 查看所有会话     | Active / Complete / Archived 标签页，含实时状态统计      |
| 接收通知         | 浏览器推送通知（idle、pending review、pending approval） |
| **远程审批**     | 待审批请求直接显示在会话卡片上 —— 允许 / 拒绝（`AskUserQuestion` 可选具体选项，计划则可批准 / 驳回） |
| **发送指令**     | 在会话卡片的输入框中输入后回车                           |
| **停止任务**     | 会话卡片上的「停止」按钮；「继续」或发送指令可解除       |
| 配对设备         | 二维码 + 6 位数字审批流程（供 Android 应用使用）         |
| 管理 Hook        | 设置面板中一键安装 / 卸载 / 检查                         |
| 切换语言         | 顶部 EN / 中文 切换按钮                                  |

### 远程控制

cc-monitor 不只是查看器 —— 它是一条双向通道，可以在仪表盘上直接操控智能体。

**审批。** 当有 UI 连接时，`PermissionRequest` hook 会挂起本地对话框，等待仪表盘给出答复。
若无人应答（或根本没有 UI 连接），hook 会立即返回，终端照常弹出原生提示 ——
这一取舍是刻意的：远程审批绝不能让坐在终端前的人变慢。

**指令。** 指令会先入队，由 `Stop` hook 在下一个回合边界作为 hook 反馈交给智能体。
在该边界时刻，已连接的 UI 还会获得一小段窗口期来发送后续消息，
因此最常见的情形（「刚做完，再加一件事…」）无需等到下一回合。

**停止。** Claude Code 没有对外暴露中断接口，因此停止是协作式的：
`PreToolUse` hook 拒绝工具调用并结束当前回合。智能体会停止一切操作并总结当前进展。
发送指令（或点击「继续」）即可解除停止状态。

> ⚠️ 若在终端提示已被回答之后才提交答复，界面会明确提示
> **「已超时 — 请在终端回答」**，而不是默默假装成功。

---

## Android 应用

将手机变成专属的 Claude Code 状态监视器。

### 获取应用

从 [Releases](https://github.com/BolunHan/cc-monitor/releases) 下载最新 APK，通过 ADB 安装：
```bash
adb install cc-monitor-app-release.apk
```

### 连接服务器

**局域网扫描（自动发现）：**
1. 确保服务器以 `--host 0.0.0.0` 运行（mDNS 默认开启）
2. 打开应用 — 自动扫描本地网络
3. 点击发现的服务器进行配对

**二维码扫描：**
1. 在 Web 仪表盘中，点击 **⧉**（配对设备）显示二维码
2. 在应用中，点击 **扫描二维码**，将摄像头对准二维码
3. 配对自动完成

**手动输入：**
1. 在应用中点击 **手动输入**
2. 输入服务器 IP、端口和 token（从 Web 仪表盘配对面板获取）

### 管理服务器

从仪表盘打开 **设置**（⚙），你将看到：
- **服务器卡片** — 带连接状态圆点（绿色 = 已连接，橙色 = 已断开，灰色 = 未激活）
- **移除**按钮在每个服务器上 — 从列表中删除
- **配对新服务器** — 添加另一个 Claude Code 实例
- **语言**切换（跟随系统 / English / 中文）

---

## 会话状态 — 你的红绿灯

| 灯光 | 状态               | 含义                                  | 你该做什么           |
| ---- | ------------------ | ------------------------------------- | -------------------- |
| 🔵    | `working`          | Claude 正在写代码、执行工具、生成输出 | 去喝杯咖啡 ☕         |
| 🟢    | `pending_review`   | Claude 完成 — 输出等待审查            | 检查结果             |
| 🟡    | `pending_approval` | Claude 需要权限（工具审批、权限提示） | 批准或拒绝           |
| ⚪    | `idle`             | 无活动 — 会话休眠                     | 发送下一条提示       |
| ✅    | `all_done`         | 会话已结束                            | 归档，继续下一个任务 |

**每次需要你关注的状态变化，你都会立即通过浏览器推送和/或 Android 通知收到提醒。**

---

## 工作原理

```
Claude Code                    cc-monitor                  Web 仪表盘
  (hooks)                        Server                    Android 应用
     |                             |  |
     |  POST /api/event            |  |  SSE stream
     +-----------------------------+  +---------------------->
                                   |
                                   +-- 状态文件 (~/.cc-monitor/)
                                   +-- mDNS (局域网发现)
                                   +-- TLS + Token 认证
```

服务器监听 7 个 Claude Code hook 事件，在内存中追踪会话状态，持久化到磁盘，并通过 Server-Sent Events 向所有连接的客户端推送实时更新。Web 仪表盘和 Android 应用渲染带有颜色编码状态的实时会话卡片。

完整技术参考见 [API 接口](#api-接口) 和 [架构](#架构-1)。

---

## API 接口

| 方法     | 路径                                  | 说明                                           |
| -------- | ------------------------------------- | ---------------------------------------------- |
| `POST`   | `/api/event`                          | 提交 hook 事件                                 |
| `GET`    | `/api/status`                         | 所有会话状态                                   |
| `GET`    | `/api/status/`                    | 单个会话状态                                   |
| `GET`    | `/api/stream`                         | SSE 实时推送（state_update + 每 3s heartbeat） |
| `GET`    | `/api/version`                        | 服务器版本                                     |
| `GET`    | `/api/hooks-status`                   | 检查 hook 安装状态                             |
| `POST`   | `/api/install-hooks`                  | 安装 hook 到全局配置                           |
| `POST`   | `/api/uninstall-hooks`                | 移除 cc-monitor hook                           |
| `POST`   | `/api/session//archive`           | 归档会话                                       |
| `POST`   | `/api/session//unarchive`         | 取消归档                                       |
| `POST`   | `/api/session//complete`          | 标记会话完成                                   |
| `POST`   | `/api/session//respond`           | 答复待审批请求                                 |
| `POST`   | `/api/session//directive`         | 向智能体投递指令                               |
| `GET`    | `/api/session//directive/next`    | 长轮询等待指令（Stop hook 调用）               |
| `POST`   | `/api/session//stop`              | 请求智能体停止                                 |
| `POST`   | `/api/session//resume`            | 解除停止                                       |
| `GET`    | `/api/request//decision`         | 长轮询等待审批结果（PermissionRequest hook 调用） |
| `GET`    | `/api/auth/pair/qr`                   | 二维码配对数据                                 |
| `POST`   | `/api/auth/pair/request`              | 提交配对请求                                   |
| `GET`    | `/api/auth/pair/request//status`  | 查询请求状态                                   |
| `POST`   | `/api/auth/pair/request//approve` | 批准配对（仅限 localhost）                     |
| `DELETE` | `/api/auth/devices/`              | 撤销设备                                       |
| `GET`    | `/api/auth/devices`                   | 列出已配对设备                                 |

---

## 架构

```
cc-monitor/
|--  src/cc_monitor/       # Python 包（FastAPI 服务器）
|--  hooks/                # Hook 脚本（纯 stdlib，无依赖）
|--  static/               # Web 仪表盘（原生 HTML/CSS/JS）
|--  scripts/              # install-hooks.sh, uninstall-hooks.sh, build-dev-docker.sh
|--  android_app/          # Flutter Android 应用
|--  tests/                # pytest 测试套件（229 个测试）
|--  Dockerfile            # Python 服务器镜像
|--  Dockerfile.dev        # 开发/测试用智能体沙箱
|--  Dockerfile.flutter    # Flutter 构建镜像
|--  docker-compose.yaml   # Docker 部署
+--  docker-compose.dev.yaml  # 开发沙箱（独立端口、独立状态）
```

## 开发

```bash
pip install -e ".[dev]"
pytest tests/ -q          # 229 个测试
cc-monitor --port 9876    # 启动开发服务器
```

### 用真实智能体做测试

主机上的 cc-monitor 经常正在被使用，因此提供了一个沙箱：
一个内含 Claude Code CLI + dsh + cc-monitor 的一次性容器，
使用独立端口、独立状态目录，与线上实例不共享任何状态。

```bash
./scripts/build-dev-docker.sh          # 构建（走缓存）并在 :9877 启动
./scripts/build-dev-docker.sh --shell  # 在沙箱内运行智能体
```

缓存模型、登录态注入方式与已知限制见 **[DEV-DOCKER.md](DEV-DOCKER.md)**。