# 2026-05-15 技术报告 / Technical Report

## Executive Summary

本日完成 BoosAPI 品牌迁移、ComfyUI Agent 对话助手开发、Gitea CI/CD Runner 部署、Notification Service 能力梳理及部署文档重写。核心变更包括：将项目内 `Metapi` 全局替换为 `BoosAPI`，新增 `/comfyui-agent` 对话式 AI 视频生成入口，完成 SSE streaming 前后端链路，并完善生产部署文档与通知服务说明。

---

## 1. Metapi → BoosAPI 全局改名 / Global Rename

### 1.1 变更范围 / Change Scope

| 区域 / Area | 变更内容 / Changes |
|---|---|
| UI 界面 / UI | About 页面、侧边栏、登录页品牌名更新为 `BoosAPI` |
| i18n 翻译 / Internationalization | 所有语言文件中的 `Metapi` 替换为 `BoosAPI` |
| 后端通知 / Backend Notification | `notifyService.ts` 通知前缀由 `[metapi]` 改为 `[BoosAPI]` |
| 桌面元数据 / Desktop Metadata | Electron / Docker 描述信息更新 |

### 1.2 已完成的技术标识替换 / Completed Technical Identifier Changes

| 项目 / Item | 变更说明 / Description |
|---|---|
| HTTP Header | `x-metapi-*` → `x-boosapi-*` |
| 推理签名前缀 / Inference Signature Prefix | `metapi:` → `boosapi:` |
| 运行时属性 / Runtime Properties | `__metapiTruncated` 等 → `__boosapi*` |
| 环境变量 / Environment Variables | `METAPI_*` → `BOOSAPI_*` |
| Package Name | `package.json` 中 `name` 更新为 `boosapi` |

### 1.3 验证方式 / Verification

```bash
grep -rn '[mM]etapi' src/ --include='*.ts' --include='*.tsx' --include='*.html' \
  | grep -v '.test.' | grep -v node_modules | grep -iv 'boosapi'
```

预期结果：无输出。

---

## 2. ComfyUI Agent 对话助手 / Conversational Assistant

### 2.1 功能概述 / Feature Overview

侧边栏新增「对话助手」入口，路由为 `/comfyui-agent`，提供与 AI 视频生成助手的对话式交互，支持文本、角色提示词、图像、场景、语音和 ComfyUI workflow 等多类型内容的流式渲染。

### 2.2 技术架构 / Architecture

```
用户 / User → POST /api/comfyui-agent/chat → BoosAPI → LLM 本地 API (streaming)
                                                         → SSE 事件流 → BoosAPI 转发 → 浏览器
```

### 2.3 后端实现 / Backend

| 文件 / File | 作用 / Responsibility |
|---|---|
| `src/server/routes/api/comfyuiAgent.ts` | SSE 流式聊天接口，调用本地 LLM API |
| `src/server/services/boosapi_comfy_nodes.py` | ComfyUI 自定义节点，默认连接 `http://127.0.0.1:4000/v1` |

### 2.4 前端实现 / Frontend

| 文件 / File | 作用 / Responsibility |
|---|---|
| `src/web/pages/ComfyUIAgent.tsx` | 对话界面组件，SSE 流式渲染 |
| `src/web/App.tsx` | 注册 `/comfyui-agent` 路由及侧边栏入口 |

### 2.5 SSE 事件类型 / SSE Event Types

| `type` | 含义 / Meaning | 前端渲染 / Rendering |
|---|---|---|
| `text` | 流式文本 | 追加到对话内容 |
| `character_prompts` | 四角度角色提示词 | 角色卡片 |
| `image` | 生成的角色图像 | 内联图片 |
| `scene` | 场景提示词 | 场景块 |
| `tts` | 语音音频 | 音频播放器 |
| `comfyui_workflow` | 完整 ComfyUI 工作流 JSON | 下载按钮 |
| `done` | 流结束 | 停止等待 |

### 2.6 验证结果 / Verification

| 命令 | 结果 |
|---|---|
| `npm install` | ✅ |
| `npm run typecheck:web` | ✅ 0 error |

---

## 3. Gitea CI/CD Runner 部署 / Runner Deployment

### 3.1 部署信息 / Deployment Info

| 项目 | 详情 |
|---|---|
| 系统 | Alpine Linux, OpenRC |
| 部署方式 | 裸机直跑，无 DinD |
| Runner 版本 | v0.1.3 |
| 注册模式 | `:host` 标签 |
| OpenRC 服务 | `/etc/init.d/gitea-runner` |
| 代理 | `HTTP_PROXY=http://127.0.0.1:7890` |
| `NO_PROXY` | 包含 `git.boos.lat` |
| 持久化 | `ephemeral: false` |

### 3.2 已知限制 / Known Limitations

- 不支持 Docker in Docker；CI 使用 `runs-on: host`
- 无原生 artifact 存储；构建产物需手动备份
- `actions/checkout` 偶发 timeout；可重试或使用本地 git 镜像

---

## 4. Notification Service

### 4.1 支持通道 / Supported Channels

| 通道 | 配置前缀 | 协议 |
|---|---|---|
| Telegram | `telegram*` | Bot API |
| 企业微信 | `wecom*` | Webhook |
| 飞书 | `feishu*` | Webhook |
| 通用 Webhook | `webhook*` | JSON POST |
| Bark | `bark*` | HTTP, iOS |
| Server酱 | `serverchan*` | HTTP |
| SMTP | `smtp*` | Email |

### 4.2 Telegram 消息格式

- 纯文本，不启用 HTML/Markdown 解析
- 单条最大 3900 字符，超长截断 + `...(truncated)`
- 支持 Telegram Topics（`message_thread_id`）

### 4.3 节流机制 / Throttling

- 基于通知签名的全局冷静期：`notifyCooldownSec`
- 同一签名在冷静期内重复触发时合并为一次
- 冷静期为全局共享，不按通道独立

---

## 5. 部署文档完善 / Deployment Documentation

Commit: `5bd847d`

对 `docs/deployment.md` 全量重写，修复所有 `metapi` 残留：

- 完整 `docker-compose.yml` 示例（含 healthcheck）
- `.env` 变量插值模式
- 全部环境变量参考表（20+ 变量）
- 扩展配置：外部 MySQL/PostgreSQL、Redis、资源限制
- 生产部署检查清单
- Nginx 反向代理（WebSocket + SSE）
- 管理后台 IP 白名单限制示例
- Docker run 常用选项表
- 升级/回滚操作流程

---

## 6. 待办事项 / TODO

| 优先级 | 事项 | 说明 |
|---|---|---|
| High | 服务未运行 | CI 崩溃后容器未恢复，需确定 Docker vs `npm run dev` |
| Medium | Telegram 格式优化 | 待确认 HTML/Markdown/简化 |
| Medium | CI pipeline 稳定性 | Docker 镜像拉取超时，需排查网络 |