┌──────────────────────┐                ┌──────────────────────────────────────┐
│  本机 agent           │   HTTPS        │  远端 nginx server                   │
│  (Claude Code /      │ ─────────────► │   ┌────────────────────────────┐     │
│   OpenCode)          │  /mcp + Bearer │   │ agent-html-drop daemon     │     │
│                      │                │   │  127.0.0.1:8765            │     │
│                      │                │   │  ├ POST /mcp    MCP server │     │
│                      │                │   │  ├ GET  /       HTML 管理页│     │
│                      │                │   │  └ /api/* + /files/        │     │
│                      │                │   └────────────┬───────────────┘     │
│  浏览器（人）         │ ──HTTPS──────► │       ┌────────▼────────────┐       │
│   https://notes...   │                │       │ nginx               │       │
│                      │                │       │  :443 → 反代 → :8765│       │
│                      │                │       │  + 直 serve /files/*│       │
│                      │                │       └─────────┬───────────┘       │
│                      │                │           docroot/                  │
└──────────────────────┘                └──────────────────────────────────────┘

# 1. 编辑 docker-compose.yaml：把 PUBLIC_BASE_URL 改成你的 HTTPS origin
# 2. 起服务（首次自动生成 token + config，持久化在 ./data/）
docker compose up -d

# 3. 取 token，配给本机 agent 的 MCP config（url = https://<origin>/mcp）
docker compose exec agent-html-drop agent-html-drop token show

# 4. 拿 nginx 反代片段，贴进你现有 nginx 的 HTTPS server block，reload
docker compose exec agent-html-drop agent-html-drop nginx-config

// Claude Code MCP config: ~/.claude.json (或类似)
{
  "mcpServers": {
    "agent-html-drop": {
      "url": "https://<origin>/mcp",
      "headers": {
        "Authorization": "Bearer <docker compose exec agent-html-drop agent-html-drop token show 输出>"
      }
    }
  }
}

# 1. 生成 HTML（agent shell）
yzr-md-tohtml file.md > /tmp/file.html

# 2. 流式上传 HTML 字节——不经过 LLM context
SHA=$(sha256sum /tmp/file.html | cut -d' ' -f1)
curl -X PUT -H "Authorization: Bearer $AGENT_HTML_DROP_TOKEN" \
     --data-binary @/tmp/file.html \
     "http://127.0.0.1:8765/files/file.html?force=true"
# 响应：{"name":"file.html","url":"https://.../files/file.html","size":...,"sha256":...}

# 3. MCP 上报（只传 ~80 字节元数据）—— LLM context 拿到 URL
upload_html(name="file.html", sha256=$SHA)

# 1. 经 MCP 通道签发 capability（MCP transport 自动带 token，agent 不碰）
prepare_upload(name="file.html")
#   → {"name":"file.html",
#      "upload_url":"http(s)://<HOST>/files/file.html?upload=<cap>&force=true",
#      "curl":"curl -X PUT --data-binary @/path/to/file.html \"<upload_url>\"",
#      "expires_in":120}

# 2. 用返回的 upload_url 上传（自带 capability + force=true，整段可直接喂给任意 HTTP client）
#    注意：没有 -H Authorization
curl -X PUT --data-binary @/tmp/file.html "<upload_url>"

# 3. MCP 上报（同前）
upload_html(name="file.html", sha256=$SHA)

agent-html-drop init [--force]                  # 创建 config + 生成 token
agent-html-drop serve [--config PATH]           # 前台启动 daemon
agent-html-drop token show                      # stdout 明文 token(CLI 路径,UI 不再使用)
agent-html-drop token rotate                    # 重生成(daemon 需重启才生效)
agent-html-drop config show                     # 打印 config (token 掩码)
agent-html-drop config path                     # 打印 config 路径
agent-html-drop config edit                     # $EDITOR 打开 config
agent-html-drop nginx-config                    # stdout 打印反代片段(location 块)

## 查询 token

token 是 daemon 的凭据，不会出现在管理页 UI / localStorage（设计原则）。
所有查询都走 CLI。两条路径：

**Classic（直接装在宿主）**

```bash
# 明文，打印到 stdout —— 复制粘贴给 agent 的 MCP config
agent-html-drop token show

# Masked（首 4 + **** + 末 4），日常检查 token 是否设置推荐
agent-html-drop config show

# 生成新 token（旧 token 立刻作废，需重启 daemon 才生效）
agent-html-drop token rotate

# 明文
docker compose exec agent-html-drop agent-html-drop token show

# 或
docker exec <container_name> agent-html-drop token show

# 容器内的 config（含 masked token）
docker compose exec agent-html-drop agent-html-drop config show

# —— 起停 ——
docker compose up -d --build       # 首次：构建镜像 + 后台启动
docker compose up -d               # 已有镜像：直接启动
docker compose restart             # 重启容器（卷 / config 保留）
docker compose down                # 停 + 删容器（卷 ./data 保留）
docker compose down --volumes      # ⚠️ 连 ./data 一起删——会丢 token + 所有 HTML

# —— 状态 / 日志 ——
docker compose ps                  # 容器状态
docker compose logs -f --tail 50   # 实时跟踪最近 50 行
docker compose logs agent-html-drop  # 只看 daemon 输出

# —— 取凭据 / 片段 ——
docker compose exec agent-html-drop agent-html-drop token show     # 明文 token
docker compose exec agent-html-drop agent-html-drop config show    # masked token
docker compose exec agent-html-drop agent-html-drop nginx-config   # nginx location 块
docker compose exec agent-html-drop agent-html-drop status         # config/token/docroot 状态

# —— 调试 / 验证 ——
docker compose exec agent-html-drop sh                             # 进容器 shell
docker compose exec agent-html-drop ls -la /data                   # 看持久化卷
bash scripts/docker-smoke.sh                                       # 一键冒烟：build → /api/health → /files → token

服务控制（用户级，无 sudo / systemd 依赖）：

> 管理页只读：`GET /` 和 `GET /api/files` 都不鉴权；`DELETE /api/files/<name>` 与
> `GET /api/nginx-config` 仍要 Bearer（给运维 / 脚本用）；`POST /mcp` 仍要 Bearer
> （agent 走）。**管理页里不再有 token 输入框，token 也不进 localStorage**——token
> 只在 server 端 `config.toml` 与本机 agent MCP config 之间手动同步。

## 文件命名 / 大小 / 覆盖规则

- **文件名 regex**：`^[A-Za-z0-9._-]+\.html$`（大小写不敏感匹配 `.html`），≤ 200 字符
- **大小**：默认上限 50 MB（`config.max_file_size` 可调）
- **同名上传**：默认 409 + `-32010`；带 `force=true` 才覆盖
- **公开 URL**：`<config.public_base_url>/files/<name>`（`public_base_url` 为纯 origin）

## 设计文档

- 设计：`docs/design.md`
- 任务书：`docs/tasks.md`

## 发布新版本（维护者）

发布流水线：push 一个 `v*` tag → GitHub Actions 自动 buildx 多架构构建（amd64 + arm64）
→ push 到 `ghcr.io/yzr95924/agent-html-drop` → post-publish smoke（pull + 起容器 + `/api/health`）。
详见 `docs/design.md` §16 / `.github/workflows/release-image.yml`。

```bash
# 1. 确保所有变更已 commit + push 到 master
# 2. 打语义化版本 tag
git tag v0.2.0
git push --tags

# 3. 看 CI：https://github.com/yzr95924/agent-html-drop/actions/workflows/release-image.yml
# 4. 镜像 tag 矩阵：v0.2.0, 0.2, 0.2.0, latest, sha-<short>
#    全部指向同一 manifest list（多架构自动挑）

pytest                    # 全量(含 install→serve→MCP→uninstall 冒烟)
pytest tests/test_cli.py -v