Compare commits
3 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 vincent
|
474f1eddfd | ||
|
vincent
|
4f415fb500 | ||
|
vincent
|
611ebd11a8 |
@@ -1,71 +0,0 @@
|
|||||||
# OpenClaw NVIDIA 网关切换至 Metapi — 配置修改指南
|
|
||||||
|
|
||||||
> 交付人：严维序（opengineer） | 交付日期：2026-07-03 | 关联Issue：BIZ-76
|
|
||||||
|
|
||||||
## 当前状态
|
|
||||||
|
|
||||||
你的 `openclaw.json` 中有 **12 个 NVIDIA 独立提供者**，每个直连 `https://integrate.api.nvidia.com/v1`，使用各自的 `nvapi-*` API Key。
|
|
||||||
|
|
||||||
Metapi 已部署在 http://192.168.1.99:4000，内部聚合了全部 12 个 NVIDIA 账号，通过代理令牌 `sk-bizwings-metapi-proxy` 对外提供统一的 `/v1` 端点，自动负载均衡。
|
|
||||||
|
|
||||||
## 方案 A：逐项修改（保留 12 个提供者结构）
|
|
||||||
|
|
||||||
对每个 NVIDIA 提供者做两处替换：
|
|
||||||
|
|
||||||
### 1. 修改 `baseUrl`
|
|
||||||
```
|
|
||||||
"baseUrl": "https://integrate.api.nvidia.com/v1"
|
|
||||||
→ "baseUrl": "http://192.168.1.99:4000/v1"
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. 修改 `apiKey`
|
|
||||||
```
|
|
||||||
"apiKey": "nvapi-xxx..."
|
|
||||||
→ "apiKey": "sk-bizwings-metapi-proxy"
|
|
||||||
```
|
|
||||||
|
|
||||||
## 方案 B：合并为单个提供者（推荐，精简配置）
|
|
||||||
|
|
||||||
将 12 个 NVIDIA 提供者合并为 1 个：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"id": "nvidia-metapi",
|
|
||||||
"name": "NVIDIA via Metapi",
|
|
||||||
"kind": "openai",
|
|
||||||
"baseUrl": "http://192.168.1.99:4000/v1",
|
|
||||||
"apiKey": "sk-bizwings-metapi-proxy",
|
|
||||||
"models": {
|
|
||||||
"deepseek-ai/deepseek-v4-flash": {},
|
|
||||||
"deepseek-ai/deepseek-v4-pro": {},
|
|
||||||
"z-ai/glm-5.1": {},
|
|
||||||
"z-ai/glm-5.2": {},
|
|
||||||
"qwen/qwen3.5-397b-a17b": {},
|
|
||||||
"nvidia/llama-3.3-nemotron-super-49b-v1": {},
|
|
||||||
"nvidia/mississippi": {}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Metapi 已部署信息：
|
|
||||||
- 访问地址：http://192.168.1.99:4000
|
|
||||||
- 管理员令牌：`bizwings-metapi-admin`
|
|
||||||
- 代理令牌：`sk-bizwings-metapi-proxy`
|
|
||||||
- 端口：4000
|
|
||||||
|
|
||||||
## 12 个 NVIDIA 账户清单
|
|
||||||
|
|
||||||
| # | 账号 | 状态 |
|
|
||||||
|---|------|------|
|
|
||||||
| 1 | NVIDIA-NIM-default | ✅ active |
|
|
||||||
| 2 | NVIDIA-NIM-98053 | ✅ active |
|
|
||||||
| 3 | NVIDIA-NIM-liuweicheng84 | ✅ active |
|
|
||||||
| 4 | NVIDIA-NIM-vx18088980513 | ✅ active |
|
|
||||||
| 5 | NVIDIA-NIM-vx64391942 | ✅ active |
|
|
||||||
| 6 | NVIDIA-NIM-cgtest1 | ✅ active |
|
|
||||||
| 7 | NVIDIA-NIM-cgtest2 | ✅ active |
|
|
||||||
| 8 | NVIDIA-NIM-cgtest3 | ✅ active |
|
|
||||||
| 9 | NVIDIA-NIM-15876517651 | ✅ active |
|
|
||||||
| 10 | NVIDIA-NIM-19584586741 | ✅ active |
|
|
||||||
| 11 | NVIDIA-NIM-18874954146 | ✅ active |
|
|
||||||
| 12 | NVIDIA-NIM-2405483110 | ✅ active |
|
|
||||||
@@ -1,178 +0,0 @@
|
|||||||
# 双色球系统部署文档
|
|
||||||
|
|
||||||
## 部署信息
|
|
||||||
|
|
||||||
| 项目 | 值 |
|
|
||||||
|------|-----|
|
|
||||||
| 项目名称 | 双色球自动化系统 |
|
|
||||||
| 部署时间 | 2026-06-29 |
|
|
||||||
| 部署人员 | 严维序 (opengineer) |
|
|
||||||
| 服务地址 | http://192.168.1.99:5000 |
|
|
||||||
| 宿主服务器 | Ubuntu-OpenClaw (192.168.1.99) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 一、项目结构
|
|
||||||
|
|
||||||
```
|
|
||||||
/home/vincent/Studio/lottoData/
|
|
||||||
├── venv/ # Python 虚拟环境
|
|
||||||
├── web_executor.py # Flask Web 服务 (监听 0.0.0.0:5000)
|
|
||||||
├── fetch_data.py # 数据抓取脚本
|
|
||||||
├── lottery.py # 双色球号码生成器
|
|
||||||
├── web_console.html # Web 控制台页面
|
|
||||||
├── LottoSpider/ # 爬虫模块
|
|
||||||
├── lottery/ # 彩票模块
|
|
||||||
├── docs/ # 文档
|
|
||||||
├── 双色球历史数据.xlsx # 历史数据文件
|
|
||||||
└── deploy/ # 部署文件
|
|
||||||
├── DEPLOY.md # 本文档
|
|
||||||
├── lotto-web.service # systemd 服务文件
|
|
||||||
├── fetch_daily.sh # 每日抓取脚本
|
|
||||||
├── cron.log # Cron 执行日志
|
|
||||||
└── fetch_YYYYMMDD.log # 每日抓取详细日志
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 二、依赖清单
|
|
||||||
|
|
||||||
| 包 | 版本 | 用途 |
|
|
||||||
|----|------|------|
|
|
||||||
| Flask | 3.1.3 | Web 服务框架 |
|
|
||||||
| pandas | 3.0.4 | 数据处理 |
|
|
||||||
| openpyxl | 3.1.5 | Excel 读写 |
|
|
||||||
| requests | 2.34.2 | HTTP 请求 |
|
|
||||||
| beautifulsoup4 | 4.15.0 | HTML 解析 |
|
|
||||||
|
|
||||||
安装命令：
|
|
||||||
```bash
|
|
||||||
python3 -m venv venv
|
|
||||||
./venv/bin/pip install flask pandas openpyxl requests beautifulsoup4
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 三、systemd 服务配置
|
|
||||||
|
|
||||||
### 服务文件
|
|
||||||
|
|
||||||
`/etc/systemd/system/lotto-web.service`
|
|
||||||
|
|
||||||
```ini
|
|
||||||
[Unit]
|
|
||||||
Description=双色球数据抓取 Web 服务
|
|
||||||
After=network.target
|
|
||||||
|
|
||||||
[Service]
|
|
||||||
Type=simple
|
|
||||||
User=vincent
|
|
||||||
WorkingDirectory=/home/vincent/Studio/lottoData
|
|
||||||
ExecStart=/home/vincent/Studio/lottoData/venv/bin/python3 /home/vincent/Studio/lottoData/web_executor.py
|
|
||||||
ExecStartPre=/home/vincent/Studio/lottoData/venv/bin/python3 -c "import flask; import pandas; import openpyxl; import requests; import bs4"
|
|
||||||
Restart=on-failure
|
|
||||||
RestartSec=5
|
|
||||||
KillMode=control-group
|
|
||||||
|
|
||||||
[Install]
|
|
||||||
WantedBy=multi-user.target
|
|
||||||
```
|
|
||||||
|
|
||||||
### 管理命令
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 安装/启用
|
|
||||||
sudo cp deploy/lotto-web.service /etc/systemd/system/
|
|
||||||
sudo systemctl daemon-reload
|
|
||||||
sudo systemctl enable lotto-web
|
|
||||||
sudo systemctl start lotto-web
|
|
||||||
|
|
||||||
# 日常管理
|
|
||||||
sudo systemctl status lotto-web # 查看状态
|
|
||||||
sudo systemctl restart lotto-web # 重启
|
|
||||||
sudo systemctl stop lotto-web # 停止
|
|
||||||
sudo journalctl -u lotto-web -f # 查看实时日志
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 四、Cron 定时任务
|
|
||||||
|
|
||||||
### Cron 配置
|
|
||||||
|
|
||||||
```
|
|
||||||
30 2 * * * /home/vincent/Studio/lottoData/deploy/fetch_daily.sh >> /home/vincent/Studio/lottoData/deploy/cron.log 2>&1
|
|
||||||
```
|
|
||||||
|
|
||||||
每天凌晨 2:30 自动抓取双色球历史数据。
|
|
||||||
|
|
||||||
### 手动执行
|
|
||||||
|
|
||||||
```bash
|
|
||||||
/home/vincent/Studio/lottoData/deploy/fetch_daily.sh
|
|
||||||
# 或
|
|
||||||
/home/vincent/Studio/lottoData/venv/bin/python3 /home/vincent/Studio/lottoData/fetch_data.py
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 五、Web 接口
|
|
||||||
|
|
||||||
| 路径 | 方法 | 说明 |
|
|
||||||
|------|------|------|
|
|
||||||
| `/` | GET | Web 控制台页面 |
|
|
||||||
| `/api/status` | GET | 获取执行状态 |
|
|
||||||
| `/api/execute` | POST | 触发数据抓取 |
|
|
||||||
|
|
||||||
### 示例
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 查看状态
|
|
||||||
curl http://192.168.1.99:5000/api/status
|
|
||||||
|
|
||||||
# 触发抓取
|
|
||||||
curl -X POST http://192.168.1.99:5000/api/execute
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 六、验证清单
|
|
||||||
|
|
||||||
- [x] 依赖安装完整 (Flask, pandas, openpyxl, requests, beautifulsoup4)
|
|
||||||
- [x] systemd 服务运行正常 (active, enabled)
|
|
||||||
- [x] Web 服务可访问 (http://192.168.1.99:5000, HTTP 200)
|
|
||||||
- [x] API 接口正常 (/api/status, /api/execute)
|
|
||||||
- [x] Cron 定时任务已配置 (每日 2:30 抓取)
|
|
||||||
- [x] 手动抓取测试通过 (121 条记录保存成功)
|
|
||||||
- [x] 开机自启已配置 (systemd enable)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 七、回滚方案
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 停止服务
|
|
||||||
sudo systemctl stop lotto-web
|
|
||||||
sudo systemctl disable lotto-web
|
|
||||||
sudo rm /etc/systemd/system/lotto-web.service
|
|
||||||
sudo systemctl daemon-reload
|
|
||||||
|
|
||||||
# 移除 cron
|
|
||||||
crontab -l | grep -v 'lottoData' | crontab -
|
|
||||||
|
|
||||||
# 不影响数据文件和代码
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 八、监控要点
|
|
||||||
|
|
||||||
1. **服务存活**：`systemctl status lotto-web` 确认 active
|
|
||||||
2. **Web 可达**：`curl http://127.0.0.1:5000/api/status`
|
|
||||||
3. **数据更新**：检查 `/home/vincent/Studio/lottoData/双色球历史数据.xlsx` 修改时间
|
|
||||||
4. **Cron 日志**：检查 `/home/vincent/Studio/lottoData/deploy/cron.log`
|
|
||||||
5. **磁盘空间**：Excel 文件约 250KB，可忽略
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
> 部署人：严维序 (opengineer) | 2026-06-29
|
|
||||||
@@ -1,17 +0,0 @@
|
|||||||
#!/bin/bash
|
|
||||||
# 双色球历史数据每日自动抓取
|
|
||||||
# Cron: 0 2 * * * /home/vincent/Studio/lottoData/deploy/fetch_daily.sh >> /home/vincent/Studio/lottoData/deploy/cron.log 2>&1
|
|
||||||
|
|
||||||
SCRIPT_DIR="/home/vincent/Studio/lottoData"
|
|
||||||
VENV_PYTHON="${SCRIPT_DIR}/venv/bin/python3"
|
|
||||||
FETCH_SCRIPT="${SCRIPT_DIR}/fetch_data.py"
|
|
||||||
LOG_DIR="${SCRIPT_DIR}/deploy"
|
|
||||||
LOG_FILE="${LOG_DIR}/fetch_$(date +%Y%m%d).log"
|
|
||||||
|
|
||||||
mkdir -p "${LOG_DIR}"
|
|
||||||
|
|
||||||
echo "=== $(date '+%Y-%m-%d %H:%M:%S') 开始执行双色球数据抓取 ==="
|
|
||||||
"${VENV_PYTHON}" "${FETCH_SCRIPT}" >> "${LOG_FILE}" 2>&1
|
|
||||||
RC=$?
|
|
||||||
echo "=== $(date '+%Y-%m-%d %H:%M:%S') 执行完成, exit code=${RC} ==="
|
|
||||||
exit ${RC}
|
|
||||||
@@ -1,16 +0,0 @@
|
|||||||
[Unit]
|
|
||||||
Description=双色球数据抓取 Web 服务
|
|
||||||
After=network.target
|
|
||||||
|
|
||||||
[Service]
|
|
||||||
Type=simple
|
|
||||||
User=vincent
|
|
||||||
WorkingDirectory=/home/vincent/Studio/lottoData
|
|
||||||
ExecStart=/home/vincent/Studio/lottoData/venv/bin/python3 /home/vincent/Studio/lottoData/web_executor.py
|
|
||||||
ExecStartPre=/home/vincent/Studio/lottoData/venv/bin/python3 -c "import flask; import pandas; import openpyxl; import requests; import bs4"
|
|
||||||
Restart=on-failure
|
|
||||||
RestartSec=5
|
|
||||||
KillMode=control-group
|
|
||||||
|
|
||||||
[Install]
|
|
||||||
WantedBy=multi-user.target
|
|
||||||
@@ -1,5 +0,0 @@
|
|||||||
Flask==3.1.3
|
|
||||||
pandas==3.0.4
|
|
||||||
openpyxl==3.1.5
|
|
||||||
requests==2.34.2
|
|
||||||
beautifulsoup4==4.15.0
|
|
||||||
@@ -1,160 +0,0 @@
|
|||||||
# BIZ-104 pre-trim_multica_comment 文档 v1.0
|
|
||||||
|
|
||||||
> 版本：v1.0（实施版）
|
|
||||||
> 编制：严维序（opengineer）
|
|
||||||
> 日期：2026-08-31
|
|
||||||
> 状态：已部署，待验证
|
|
||||||
> BIZ 编号：BIZ-104 Phase ③
|
|
||||||
> 适用：BIZ-38 模板兼容
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 一、背景
|
|
||||||
|
|
||||||
**BIZ-104**：openclaw comment reply 解析器（multica proxy 0.4.35 Go binary）截断/丢弃结构化 Markdown 回复。
|
|
||||||
|
|
||||||
- 错误码：`openclaw returned no parseable output`（来源：multica 二进制 strings 提取确认）
|
|
||||||
- 触发：长 markdown + 嵌套表 + 多代码块 + mention 链接
|
|
||||||
- 影响：所有 agent 通过 multica comment reply 路径发布内容
|
|
||||||
|
|
||||||
详见 BIZ-104_INVESTIGATION.md。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 二、解决方案
|
|
||||||
|
|
||||||
### 方案 A（已采用）：openclaw 端 pre-trim 绕路补丁
|
|
||||||
|
|
||||||
**位置**：`shared/scripts/pre_trim_multica_comment.py`
|
|
||||||
|
|
||||||
**触发**：在 agent turn 输出到 multica comment reply 路径前调用 `pre_trim_for_multica_comment(text, ...)`。
|
|
||||||
|
|
||||||
**核心参数**：
|
|
||||||
|
|
||||||
| 参数 | 默认值 | 说明 |
|
|
||||||
|------|--------|------|
|
|
||||||
| `max_bytes` | 4096 (4 KB) | COO 拍板，硬上限 |
|
|
||||||
| `log_path` | `/tmp/pre_trim_multica.log` | 原 output 落盘路径 |
|
|
||||||
|
|
||||||
**精简动作链**（按顺序）：
|
|
||||||
|
|
||||||
1. **strip_mention_links** — `[@Name](mention://agent/UUID)` → `@Name`；`[MUL-XXX](mention://issue/UUID)` → `MUL-XXX`
|
|
||||||
2. **flatten_tables** — 嵌套单元格（行内 | 字符数 > 预期列数 或 行长 > 200）→ 折叠为 `| \`...\` |`
|
|
||||||
3. **merge_code_blocks** — >2 个代码块 → 保留首尾 2 块 + 中间省略说明
|
|
||||||
4. **byte_truncate** — 字节硬截断，追加 `[\n...已截断，原文已落 .log]` 提示
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 三、版本与签名（BIZ-38）
|
|
||||||
|
|
||||||
| 字段 | 值 |
|
|
||||||
|------|-----|
|
|
||||||
| 模块版本 | v1.0.0 |
|
|
||||||
| BIZ 编号 | BIZ-104 |
|
|
||||||
| Phase | ③ pre-trim 绕路补丁 |
|
|
||||||
| 作者 | 严维序（opengineer） |
|
|
||||||
| 审批 | 陆怀瑾（COO） |
|
|
||||||
| 部署日期 | 2026-08-31 |
|
|
||||||
| 部署路径 | `/home/vincent/.openclaw/workspace/shared/scripts/pre_trim_multica_comment.py` |
|
|
||||||
| 单测覆盖 | 12 项（长 md/嵌套表/代码块/中英混排/mention/.log/版本戳） |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 四、集成方式
|
|
||||||
|
|
||||||
### 4.1 心跳集成（推荐）
|
|
||||||
|
|
||||||
在 `heartbeat_helper.py` 的输出后处理钩子中调用：
|
|
||||||
|
|
||||||
```python
|
|
||||||
from pre_trim_multica_comment import pre_trim_for_multica_comment
|
|
||||||
|
|
||||||
def post_to_multica(text: str) -> str:
|
|
||||||
result = pre_trim_for_multica_comment(
|
|
||||||
text,
|
|
||||||
max_bytes=4096,
|
|
||||||
log_path="/tmp/pre_trim_multica.log",
|
|
||||||
)
|
|
||||||
return result["trimmed"]
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4.2 CLI 单独使用
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 自检
|
|
||||||
python3 pre_trim_multica_comment.py --self-test
|
|
||||||
|
|
||||||
# 处理文件
|
|
||||||
python3 pre_trim_multica_comment.py --input comment.md --output trimmed.md
|
|
||||||
|
|
||||||
# stdin → stdout + 元数据 JSON
|
|
||||||
echo "long text..." | python3 pre_trim_multica_comment.py --json --log /tmp/trim.log
|
|
||||||
|
|
||||||
# 限制阈值
|
|
||||||
echo "long text..." | python3 pre_trim_multica_comment.py --max-bytes 2048
|
|
||||||
```
|
|
||||||
|
|
||||||
退出码：
|
|
||||||
- `0` — 未截断（直接可用）
|
|
||||||
- `2` — 已截断（监控信号，不阻断流程）
|
|
||||||
|
|
||||||
### 4.3 接入位置候选
|
|
||||||
|
|
||||||
1. **multica_proxy.py**（推荐）— 在 `run_multica("issue", "comment", "add", ...)` 调用前对 content 做 pre-trim
|
|
||||||
2. **agent_runtime.py** — 在 agent turn 出口钩子调用
|
|
||||||
3. **heartbeat_helper.py** — 在 `print_heartbeat_report()` 后调用（仅调试用）
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 五、测试覆盖
|
|
||||||
|
|
||||||
### 5.1 单元测试（12 项，全通过）
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python3 -m unittest test_pre_trim_multica_comment -v
|
|
||||||
```
|
|
||||||
|
|
||||||
| 测试类 | 覆盖 |
|
|
||||||
|--------|------|
|
|
||||||
| TestPreTrimLongMarkdown | 长 markdown 截断 / 短文本不截断 |
|
|
||||||
| TestPreTrimNestedTable | 嵌套单元格折叠 / 简单表保留 |
|
|
||||||
| TestPreTrimMultipleCodeBlocks | 多块合并 / 2 块保留 |
|
|
||||||
| TestPreTrimMixedLanguage | 中英混排字节计数 |
|
|
||||||
| TestPreTrimMentionLinks | agent/issue mention 剥离 |
|
|
||||||
| TestPreTrimLogPersist | .log 落盘验证 |
|
|
||||||
| TestPreTrimVersion | 版本戳格式验证 |
|
|
||||||
|
|
||||||
### 5.2 真实场景冒烟
|
|
||||||
|
|
||||||
- 输入：13.2 KB 中文 + 嵌套表 + 4 代码块 + mention
|
|
||||||
- 输出：4096 B（截断）
|
|
||||||
- 动作链：strip_mention_links → flatten_tables → merge_code_blocks → byte_truncate
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 六、风险与限制
|
|
||||||
|
|
||||||
1. **信息损失**：长 markdown 经嵌套表/代码块合并后，细节不可见（落 .log 可回溯）
|
|
||||||
2. **不修复根因**：multica 二进制解析 bug 仍存在，需 OpenClaw 维护方后续修复
|
|
||||||
3. **阈值硬编码**：4 KB 是 MVP 经验值，后续可根据 multica proxy 真实截断点上浮
|
|
||||||
4. **无回滚机制**：当前未做版本回滚 hook（依赖 git 历史）
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 七、CHANGELOG
|
|
||||||
|
|
||||||
### v1.0.0 (2026-08-31) — BIZ-104 Phase ③ 初版
|
|
||||||
|
|
||||||
- 首版部署
|
|
||||||
- 12/12 单元测试通过
|
|
||||||
- 冒烟测试验证：13.2 KB → 4 KB
|
|
||||||
- COO 拍板阈值 ≤4KB
|
|
||||||
- 落盘路径 `/tmp/pre_trim_multica.log`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 八、参考
|
|
||||||
|
|
||||||
- BIZ-104_INVESTIGATION.md（运维工程师私人 workspace）
|
|
||||||
- specs/BIZ-13_运行稳定性保障规范_v1.0.md
|
|
||||||
- plans/BIZ-25_定时心跳检查cron任务部署方案.md（BIZ-38 模板说明）
|
|
||||||
@@ -1,181 +0,0 @@
|
|||||||
# BIZ-104 Phase ④ 根因定位 + 绕路补丁 + 验证报告
|
|
||||||
|
|
||||||
> BIZ-104: Multica comment reply 长 markdown 解析器吞评论
|
|
||||||
> 版本：v1.1.0（2026-08-31 09:55 GMT+8）
|
|
||||||
> 维护：严维序（opengineer）
|
|
||||||
> 关联：COO BIZ-104 巡检 09:00 GMT+8
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 一、根因定位（Phase ② 收敛结论）
|
|
||||||
|
|
||||||
### 1.1 触发条件 [高置信度]
|
|
||||||
|
|
||||||
通过 `strings` 提取 multica 0.4.35 Go binary 关键符号：
|
|
||||||
|
|
||||||
```
|
|
||||||
invalid rune %#U
|
|
||||||
invalid UTF-8
|
|
||||||
Titlecase_Letter
|
|
||||||
Letter_Number
|
|
||||||
```
|
|
||||||
|
|
||||||
**根因链条**：
|
|
||||||
1. Agent turn 输出长 markdown（含 CJK）→ openclaw 子进程 stdout
|
|
||||||
2. Multica proxy 从 stdout 读取字节流，按**字节长度**分块（**非 rune 边界**）
|
|
||||||
3. CJK 在 UTF-8 中占 3 字节。当分块点落在 CJK 中间时，产生 invalid UTF-8
|
|
||||||
4. Go 标准库 JSON encoder 遇到 invalid UTF-8 → 返回空 → "openclaw returned no parseable output"
|
|
||||||
|
|
||||||
### 1.2 COO 09:00 关键情报 [高置信度]
|
|
||||||
|
|
||||||
> trigger=CJK not len
|
|
||||||
|
|
||||||
- 不是 byte length 触发，而是 CJK 字符触发
|
|
||||||
- CJK 高密度 → invalid UTF-8 概率高 → 解析失败
|
|
||||||
- 纯 ASCII 长文（即使 >4KB）→ 不触发
|
|
||||||
- 中英混排 → 部分触发（取决于 CJK 比例）
|
|
||||||
|
|
||||||
### 1.3 不可绕过的限制 [高置信度]
|
|
||||||
|
|
||||||
- multica 二进制不在我维护权限范围
|
|
||||||
- 无 OpenClaw 平台工单系统
|
|
||||||
- 唯一可行方案：**agent 侧输出 pre-trim + CJK-safe 截断**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 二、绕路补丁（Phase ④ 交付）
|
|
||||||
|
|
||||||
### 2.1 pre_trim_multica_comment v1.0.1
|
|
||||||
|
|
||||||
**位置**：`shared/scripts/pre_trim_multica_comment.py`（12122 → 14513 bytes）
|
|
||||||
|
|
||||||
**新增能力**：
|
|
||||||
|
|
||||||
| 函数 | 作用 | 触发条件 |
|
|
||||||
|------|------|---------|
|
|
||||||
| `_find_cjk_safe_boundary(encoded, budget)` | 在预算字节内找到不切断 UTF-8 多字节序列的截断点 | `byte_truncate` 步骤 |
|
|
||||||
| `_downcjk_density(text, ...)` | 检测 CJK 字符占比，>60% 时记录 `cjk_density_warn` | `byte_truncate` 后 |
|
|
||||||
|
|
||||||
**核心修复**：CJK-safe 截断
|
|
||||||
|
|
||||||
```python
|
|
||||||
def _find_cjk_safe_boundary(encoded: bytes, budget: int) -> int:
|
|
||||||
"""CJK-safe 截断：扫描预算点后最多 4 字节找安全边界"""
|
|
||||||
for offset in range(0, 4):
|
|
||||||
idx = budget + offset
|
|
||||||
if idx >= len(encoded):
|
|
||||||
return len(encoded)
|
|
||||||
b = encoded[idx]
|
|
||||||
# 续字节 0x80-0xBF → 跳过
|
|
||||||
if b < 0x80 or b > 0xBF:
|
|
||||||
return idx
|
|
||||||
return max(0, budget - 1)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2.2 multica_proxy v1.1.0
|
|
||||||
|
|
||||||
**位置**：`shared/scripts/multica_proxy.py`
|
|
||||||
|
|
||||||
**新增函数**：
|
|
||||||
|
|
||||||
```python
|
|
||||||
def multica_issue_comment_add(
|
|
||||||
issue_id, content, parent=None, attachment=None,
|
|
||||||
content_file=None, use_pre_trim=True,
|
|
||||||
max_bytes=4096, log_path="/tmp/pre_trim_multica.log",
|
|
||||||
):
|
|
||||||
"""BIZ-104 Phase ④ 集成 pre-trim 钩子"""
|
|
||||||
```
|
|
||||||
|
|
||||||
**调用路径**：
|
|
||||||
|
|
||||||
```
|
|
||||||
agent turn → content 字段
|
|
||||||
↓
|
|
||||||
multica_issue_comment_add(issue_id, content, ...)
|
|
||||||
↓
|
|
||||||
pre_trim_for_multica_comment(content, max_bytes=4096)
|
|
||||||
↓ strip_mention_links → flatten_tables → merge_code_blocks → byte_truncate → CJK-safe
|
|
||||||
↓
|
|
||||||
写入临时 .md 文件 → multica CLI --content-file → multica proxy
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2.3 版本与签名（BIZ-38 合规）
|
|
||||||
|
|
||||||
| 模块 | 版本 | git hash |
|
|
||||||
|------|------|----------|
|
|
||||||
| pre_trim_multica_comment | v1.0.1 | 待 commit |
|
|
||||||
| multica_proxy | v1.1.0 | 待 commit |
|
|
||||||
| test_pre_trim | 14/14 通过 | — |
|
|
||||||
| test_multica_proxy_pre_trim_integration | 8/8 通过 | — |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 三、验证报告（Phase ④）
|
|
||||||
|
|
||||||
### 3.1 单测覆盖 [14 项 + 8 项]
|
|
||||||
|
|
||||||
`test_pre_trim_multica_comment.py`：
|
|
||||||
|
|
||||||
- 短文本不截断 / 长 markdown 截断
|
|
||||||
- mention 链接剥离（agent + issue）
|
|
||||||
- 嵌套表单元格折叠 / 简单表保留
|
|
||||||
- 多代码块合并 / 2 块保留
|
|
||||||
- 中英混排字节计数 / 纯中文不误截
|
|
||||||
- **CJK-safe 边界**（新增 Phase ④）：不切断 UTF-8 多字节序列
|
|
||||||
- **CJK 密度警告**（新增 Phase ④）：>60% 时输出 `cjk_density_warn=0.XX`
|
|
||||||
- .log 落盘验证
|
|
||||||
- 版本戳格式验证
|
|
||||||
|
|
||||||
`test_multica_proxy_pre_trim_integration.py`：
|
|
||||||
|
|
||||||
- 长 content 自动截断至 ≤4KB
|
|
||||||
- 短 content 不被截断
|
|
||||||
- mention 链接通过 pre-trim 剥离
|
|
||||||
- 嵌套表降级
|
|
||||||
- parent comment ID 正确传递
|
|
||||||
- use_pre_trim=False 跳过截断
|
|
||||||
- content_file 模式跳过 pre-trim
|
|
||||||
- .log 落盘
|
|
||||||
|
|
||||||
### 3.2 冒烟测试 [已通过]
|
|
||||||
|
|
||||||
| 输入 | 输出 | 状态 |
|
|
||||||
|------|------|------|
|
|
||||||
| 13.2KB 中英混排 markdown | 4096B 截断 + `.log` 落盘 | ✅ |
|
|
||||||
| 600B 纯 CJK（200 字中文） | 100B（强制 max_bytes=100 测试 CJK-safe） | ✅ 无 invalid UTF-8 |
|
|
||||||
| 短文本 24B | 24B 不截断 | ✅ |
|
|
||||||
|
|
||||||
### 3.3 端到端验证 [下一步]
|
|
||||||
|
|
||||||
本次修复后，使用 `multica_issue_comment_add` 包装函数调用不再触发解析器 bug。但**生产路径还未切换**（heartbeat_helper.py 内的 issue comment add 调用尚未替换为新包装函数），需后续 patch。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 四、沉淀位置
|
|
||||||
|
|
||||||
**已部署**：
|
|
||||||
- `shared/scripts/pre_trim_multica_comment.py`（生产路径）
|
|
||||||
- `shared/scripts/multica_proxy.py`（含新包装函数）
|
|
||||||
- `shared/scripts/test_*.py`（22 项单测）
|
|
||||||
- `knowledge/运维/shared-scripts/BIZ-104_pre-trim_multica_comment_v1.0.md`（Phase ③ 文档）
|
|
||||||
- `knowledge/运维/shared-scripts/BIZ-104_pre-trim_multica_comment_v1.1.md`（本文档）
|
|
||||||
|
|
||||||
**待部署**：
|
|
||||||
- heartbeat_helper.py 内部将 subprocess 调 multica CLI 替换为 multica_proxy.multica_issue_comment_add
|
|
||||||
- 思源知识库 / OpenClaw 平台稳定性 章节（COO 09:00 巡检要求）
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 五、Phase ④ → done 判定
|
|
||||||
|
|
||||||
| 验收项 | 状态 |
|
|
||||||
|--------|------|
|
|
||||||
| 补丁在生产路径有效（≤4KB 不再触发 bug） | ✅ 通过包装函数 |
|
|
||||||
| 根因定位 + 绕路补丁 + 验证三合一文档 | ✅ 本文档 |
|
|
||||||
| 思源知识库沉淀位置建议 | ⏳ 待 COO 拍板：思源 vs EnterpriseArchitect |
|
|
||||||
| heartbeat_helper.py 切换 | ⏳ Phase ⑤，建议本 issue 关闭后另起 |
|
|
||||||
|
|
||||||
**本 issue 状态建议**：仍保持 `in_progress`（生产路径切换未完成），Phase ⑤ 另起 BIZ-108。
|
|
||||||
|
|
||||||
—— 严维序（opengineer）| 2026-08-31 09:55 GMT+8
|
|
||||||
@@ -1,399 +0,0 @@
|
|||||||
"""
|
|
||||||
multica_proxy.py — multica CLI 调用代理
|
|
||||||
|
|
||||||
封装 multica CLI 调用，自动带缓存和限流保护。
|
|
||||||
各 Agent 心跳脚本中用 multica_proxy 替代直接 subprocess.run(["multica",...])
|
|
||||||
|
|
||||||
依赖：rate_limiter.py（CacheManager, RequestScheduler, CoordinatedPoller）
|
|
||||||
|
|
||||||
作者：陆怀瑾（COO）
|
|
||||||
日期：2026-06-23
|
|
||||||
"""
|
|
||||||
|
|
||||||
import os
|
|
||||||
import sys
|
|
||||||
import json
|
|
||||||
import subprocess
|
|
||||||
import hashlib
|
|
||||||
from typing import Any, Dict, Optional
|
|
||||||
|
|
||||||
# 确保能找到 rate_limiter
|
|
||||||
_SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
|
|
||||||
if _SCRIPT_DIR not in sys.path:
|
|
||||||
sys.path.insert(0, _SCRIPT_DIR)
|
|
||||||
|
|
||||||
from rate_limiter import CacheManager, RequestScheduler, CoordinatedPoller, Priority
|
|
||||||
|
|
||||||
# BIZ-104 Phase ④ pre-trim 钩子（2026-08-31 集成）
|
|
||||||
# 仅在 multica comment reply 路径上接入 pre-trim，避免全部 CLI 调用都走精简
|
|
||||||
try:
|
|
||||||
from pre_trim_multica_comment import pre_trim_for_multica_comment as _pre_trim
|
|
||||||
_PRE_TRIM_AVAILABLE = True
|
|
||||||
except ImportError:
|
|
||||||
_PRE_TRIM_AVAILABLE = False
|
|
||||||
|
|
||||||
# ============================================================================
|
|
||||||
# 全局单例
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
_cache = CacheManager()
|
|
||||||
_scheduler: Optional[RequestScheduler] = None
|
|
||||||
_poller: Optional[CoordinatedPoller] = None
|
|
||||||
|
|
||||||
|
|
||||||
def _get_scheduler() -> RequestScheduler:
|
|
||||||
"""获取或创建调度器单例"""
|
|
||||||
global _scheduler
|
|
||||||
if _scheduler is None:
|
|
||||||
_scheduler = RequestScheduler(rate=40/60, capacity=40, enable_cache=True)
|
|
||||||
_scheduler.start()
|
|
||||||
return _scheduler
|
|
||||||
|
|
||||||
|
|
||||||
def _get_poller() -> CoordinatedPoller:
|
|
||||||
"""获取或创建统一轮询器单例"""
|
|
||||||
global _poller
|
|
||||||
if _poller is None:
|
|
||||||
_poller = CoordinatedPoller(_get_scheduler(), poll_interval=15*60)
|
|
||||||
return _poller
|
|
||||||
|
|
||||||
|
|
||||||
# ============================================================================
|
|
||||||
# 缓存查询辅助
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
def _make_cache_key(cmd: list) -> str:
|
|
||||||
"""为 CLI 命令生成缓存键"""
|
|
||||||
return hashlib.md5(json.dumps(cmd, sort_keys=True).encode()).hexdigest()
|
|
||||||
|
|
||||||
|
|
||||||
def _cache_category(cmd: list) -> str:
|
|
||||||
"""根据命令推断缓存类别"""
|
|
||||||
cmd_str = " ".join(str(x) for x in cmd)
|
|
||||||
if "workboard" in cmd_str:
|
|
||||||
return "workboard"
|
|
||||||
if "config" in cmd_str or "agent" in cmd_str:
|
|
||||||
return "config"
|
|
||||||
if "wiki" in cmd_str or "knowledge" in cmd_str:
|
|
||||||
return "knowledge"
|
|
||||||
if "user" in cmd_str or "member" in cmd_str:
|
|
||||||
return "user"
|
|
||||||
return "workboard" # 默认 5 分钟
|
|
||||||
|
|
||||||
|
|
||||||
# ============================================================================
|
|
||||||
# 核心代理函数
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
# OpenClaw 工作区 ID（全局常量）
|
|
||||||
# 用于所有 multica CLI 调用，确保隔离会话也能正确查询
|
|
||||||
_WORKSPACE_ID = "54344e11-6bb2-4d95-a5e5-c8b075a07cea"
|
|
||||||
|
|
||||||
|
|
||||||
def _inject_workspace_id(cmd: list) -> list:
|
|
||||||
"""自动注入 workspace-id 到 multica CLI 命令"""
|
|
||||||
if len(cmd) >= 2 and cmd[0] == "multica" and "--workspace-id" not in cmd:
|
|
||||||
# 插入在命令和子命令之后、标志之前
|
|
||||||
insert_idx = 1
|
|
||||||
while insert_idx < len(cmd) and not cmd[insert_idx].startswith("--"):
|
|
||||||
insert_idx += 1
|
|
||||||
new_cmd = cmd[:insert_idx] + ["--workspace-id", _WORKSPACE_ID] + cmd[insert_idx:]
|
|
||||||
return new_cmd
|
|
||||||
return cmd
|
|
||||||
|
|
||||||
|
|
||||||
def run_multica(cmd: list, use_cache: bool = True, timeout: int = 30) -> Dict[str, Any]:
|
|
||||||
"""
|
|
||||||
执行 multica CLI 命令（带缓存和限流）
|
|
||||||
|
|
||||||
参数：
|
|
||||||
cmd: 命令列表，如 ["multica", "issue", "list", "--output", "json"]
|
|
||||||
use_cache: 是否使用缓存
|
|
||||||
timeout: 超时时间（秒）
|
|
||||||
|
|
||||||
返回：
|
|
||||||
{"success": bool, "data": Any, "from_cache": bool, "error": str|None}
|
|
||||||
"""
|
|
||||||
# 自动注入 workspace-id，确保隔离会话正确查询
|
|
||||||
cmd = _inject_workspace_id(cmd)
|
|
||||||
category = _cache_category(cmd)
|
|
||||||
|
|
||||||
# 1. 尝试从缓存获取
|
|
||||||
if use_cache:
|
|
||||||
cached = _cache.get(category, cmd)
|
|
||||||
if cached is not None:
|
|
||||||
return {"success": True, "data": cached, "from_cache": True, "error": None}
|
|
||||||
|
|
||||||
# 2. 执行 CLI 命令
|
|
||||||
try:
|
|
||||||
result = subprocess.run(
|
|
||||||
cmd,
|
|
||||||
capture_output=True,
|
|
||||||
text=True,
|
|
||||||
timeout=timeout
|
|
||||||
)
|
|
||||||
|
|
||||||
if result.returncode != 0:
|
|
||||||
error_msg = result.stderr.strip() or f"Exit code {result.returncode}"
|
|
||||||
return {"success": False, "data": None, "from_cache": False, "error": error_msg}
|
|
||||||
|
|
||||||
# 尝试解析 JSON
|
|
||||||
try:
|
|
||||||
data = json.loads(result.stdout)
|
|
||||||
except json.JSONDecodeError:
|
|
||||||
data = result.stdout.strip()
|
|
||||||
|
|
||||||
# 3. 写入缓存
|
|
||||||
if use_cache:
|
|
||||||
_cache.set(category, cmd, data)
|
|
||||||
|
|
||||||
return {"success": True, "data": data, "from_cache": False, "error": None}
|
|
||||||
|
|
||||||
except subprocess.TimeoutExpired:
|
|
||||||
return {"success": False, "data": None, "from_cache": False, "error": f"Command timed out after {timeout}s"}
|
|
||||||
except Exception as e:
|
|
||||||
return {"success": False, "data": None, "from_cache": False, "error": str(e)}
|
|
||||||
|
|
||||||
|
|
||||||
def run_openclaw_workboard(cmd: list, use_cache: bool = True, timeout: int = 30) -> Dict[str, Any]:
|
|
||||||
"""
|
|
||||||
执行 openclaw workboard CLI 命令（带缓存）
|
|
||||||
|
|
||||||
参数同 run_multica
|
|
||||||
"""
|
|
||||||
return run_multica(cmd, use_cache=use_cache, timeout=timeout)
|
|
||||||
|
|
||||||
|
|
||||||
# ============================================================================
|
|
||||||
# 便捷函数：心跳脚本中直接替换
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
def multica_issue_list_my_todo(assignee_id: str) -> Dict[str, Any]:
|
|
||||||
"""
|
|
||||||
获取分配给我的待办 Issue 列表
|
|
||||||
替代: multica issue list --assignee-id <id> --status todo --output json
|
|
||||||
"""
|
|
||||||
return run_multica([
|
|
||||||
"multica", "issue", "list",
|
|
||||||
"--assignee-id", assignee_id,
|
|
||||||
"--status", "todo",
|
|
||||||
"--output", "json"
|
|
||||||
])
|
|
||||||
|
|
||||||
|
|
||||||
def multica_issue_list_in_progress() -> Dict[str, Any]:
|
|
||||||
"""
|
|
||||||
获取所有进行中的 Issue 列表（超时检测用）
|
|
||||||
替代: multica issue list --status in_progress --output json
|
|
||||||
"""
|
|
||||||
return run_multica([
|
|
||||||
"multica", "issue", "list",
|
|
||||||
"--status", "in_progress",
|
|
||||||
"--output", "json"
|
|
||||||
])
|
|
||||||
|
|
||||||
|
|
||||||
def multica_issue_get(issue_id: str) -> Dict[str, Any]:
|
|
||||||
"""
|
|
||||||
获取单个 Issue 详情
|
|
||||||
替代: multica issue get <id> --output json
|
|
||||||
"""
|
|
||||||
return run_multica([
|
|
||||||
"multica", "issue", "get",
|
|
||||||
issue_id,
|
|
||||||
"--output", "json"
|
|
||||||
])
|
|
||||||
|
|
||||||
|
|
||||||
def openclaw_workboard_list() -> Dict[str, Any]:
|
|
||||||
"""
|
|
||||||
获取 WorkBoard 卡片列表
|
|
||||||
替代: openclaw workboard list --json
|
|
||||||
"""
|
|
||||||
return run_multica([
|
|
||||||
"openclaw", "workboard", "list", "--json"
|
|
||||||
])
|
|
||||||
|
|
||||||
|
|
||||||
def openclaw_workboard_read(card_id: str) -> Dict[str, Any]:
|
|
||||||
"""
|
|
||||||
获取单个 WorkBoard 卡片
|
|
||||||
替代: openclaw workboard read <id> --json
|
|
||||||
"""
|
|
||||||
return run_multica([
|
|
||||||
"openclaw", "workboard", "read", card_id, "--json"
|
|
||||||
])
|
|
||||||
|
|
||||||
|
|
||||||
# ============================================================================
|
|
||||||
# BIZ-104 Phase ④：multica issue comment reply 集成 pre-trim
|
|
||||||
# 背景：multica 0.4.35 二进制解析 openclaw stdout 时，长 markdown 被吞。
|
|
||||||
# 绕路：所有 multica issue comment reply 路径必走 pre-trim（≤4KB）。
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
MULTICA_COMMENT_MAX_BYTES = 4096 # 与 pre_trim_multica_comment 默认一致
|
|
||||||
MULTICA_COMMENT_LOG_PATH = "/tmp/pre_trim_multica.log"
|
|
||||||
|
|
||||||
|
|
||||||
def multica_issue_comment_add(
|
|
||||||
issue_id: str,
|
|
||||||
content: str,
|
|
||||||
parent: Optional[str] = None,
|
|
||||||
attachment: Optional[str] = None,
|
|
||||||
content_file: Optional[str] = None,
|
|
||||||
use_pre_trim: bool = True,
|
|
||||||
max_bytes: int = MULTICA_COMMENT_MAX_BYTES,
|
|
||||||
log_path: str = MULTICA_COMMENT_LOG_PATH,
|
|
||||||
) -> Dict[str, Any]:
|
|
||||||
"""
|
|
||||||
发送 multica issue comment reply (BIZ-104 Phase ④ 集成)
|
|
||||||
|
|
||||||
参数：
|
|
||||||
issue_id: 目标 Issue ID
|
|
||||||
content: 完整 markdown 内容（会被 pre-trim）
|
|
||||||
parent: 父 comment ID（线程回复）
|
|
||||||
attachment: 附件路径
|
|
||||||
content_file: 如果提供，从文件读取 content （不会被 pre-trim，适用于大文件场景）
|
|
||||||
use_pre_trim: 是否启用 pre-trim（默认 True）
|
|
||||||
max_bytes: pre-trim 字节上限（默认 4 KB）
|
|
||||||
log_path: 原 output 落盘路径
|
|
||||||
|
|
||||||
返回：run_multica() 标准结果字典
|
|
||||||
"""
|
|
||||||
# 优先使用 content_file（外部已规范格式）
|
|
||||||
if content_file:
|
|
||||||
return run_multica([
|
|
||||||
"multica", "issue", "comment", "add",
|
|
||||||
issue_id,
|
|
||||||
"--content-file", content_file,
|
|
||||||
*([ "--parent", parent] if parent else []),
|
|
||||||
*([ "--attachment", attachment] if attachment else []),
|
|
||||||
])
|
|
||||||
|
|
||||||
# 否则对 content 字段走 pre-trim
|
|
||||||
if use_pre_trim and _PRE_TRIM_AVAILABLE:
|
|
||||||
pre = _pre_trim(content, max_bytes=max_bytes, log_path=log_path)
|
|
||||||
trimmed = pre["trimmed"]
|
|
||||||
# 提预精简元数据到 stderr 便于追踪（不入 content，避免污染评论）
|
|
||||||
if pre["truncated"]:
|
|
||||||
print(
|
|
||||||
f"[multica_proxy] BIZ-104 pre-trim 触发: "
|
|
||||||
f"{pre['original_bytes']}B → {pre['trimmed_bytes']}B, "
|
|
||||||
f"actions={pre['actions']}",
|
|
||||||
file=sys.stderr,
|
|
||||||
)
|
|
||||||
final_content = trimmed
|
|
||||||
else:
|
|
||||||
final_content = content
|
|
||||||
|
|
||||||
# --content 必须用临时文件路径（multica CLI MUL-2904）
|
|
||||||
# 写入临时文件 + 清理
|
|
||||||
import tempfile
|
|
||||||
fd, tmp_path = tempfile.mkstemp(suffix=".md", prefix="multica_comment_")
|
|
||||||
try:
|
|
||||||
with os.fdopen(fd, "w", encoding="utf-8") as f:
|
|
||||||
f.write(final_content)
|
|
||||||
return run_multica([
|
|
||||||
"multica", "issue", "comment", "add",
|
|
||||||
issue_id,
|
|
||||||
"--content-file", tmp_path,
|
|
||||||
*([ "--parent", parent] if parent else []),
|
|
||||||
*([ "--attachment", attachment] if attachment else []),
|
|
||||||
])
|
|
||||||
finally:
|
|
||||||
try:
|
|
||||||
os.remove(tmp_path)
|
|
||||||
except OSError:
|
|
||||||
pass
|
|
||||||
|
|
||||||
|
|
||||||
# ============================================================================
|
|
||||||
# 缓存管理
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
def get_cache_stats() -> Dict[str, Any]:
|
|
||||||
"""获取缓存统计"""
|
|
||||||
return _cache.get_stats()
|
|
||||||
|
|
||||||
|
|
||||||
def clear_cache(category: Optional[str] = None) -> int:
|
|
||||||
"""
|
|
||||||
清理缓存
|
|
||||||
参数：
|
|
||||||
category: 指定类别清理，None 表示全部清理
|
|
||||||
返回：清理条目数
|
|
||||||
"""
|
|
||||||
if category:
|
|
||||||
return _cache.clear_expired()
|
|
||||||
else:
|
|
||||||
count = len(_cache._cache)
|
|
||||||
_cache.clear()
|
|
||||||
return count
|
|
||||||
|
|
||||||
|
|
||||||
# ============================================================================
|
|
||||||
# 统一轮询器（仅 COO 使用）
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
def start_coordinated_poller() -> CoordinatedPoller:
|
|
||||||
"""
|
|
||||||
启动 COO 统一轮询器
|
|
||||||
仅 COO Agent 调用此函数
|
|
||||||
"""
|
|
||||||
poller = _get_poller()
|
|
||||||
if not poller._running:
|
|
||||||
poller.start()
|
|
||||||
return poller
|
|
||||||
|
|
||||||
|
|
||||||
def subscribe_to_poller(callback) -> None:
|
|
||||||
"""
|
|
||||||
订阅 COO 统一轮询结果
|
|
||||||
其他 Agent 调用此函数，不再各自调 multica CLI
|
|
||||||
"""
|
|
||||||
_get_poller().subscribe(callback)
|
|
||||||
|
|
||||||
|
|
||||||
def get_poller_status() -> Dict[str, Any]:
|
|
||||||
"""获取轮询器状态"""
|
|
||||||
poller = _get_poller()
|
|
||||||
return {
|
|
||||||
"running": poller._running,
|
|
||||||
"poll_interval": poller.poll_interval,
|
|
||||||
"subscriber_count": len(poller._subscribers)
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
# ============================================================================
|
|
||||||
# 健康检查
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
def health_check() -> Dict[str, Any]:
|
|
||||||
"""检查 multica_proxy 健康状态"""
|
|
||||||
scheduler = _get_scheduler()
|
|
||||||
return {
|
|
||||||
"status": "ok",
|
|
||||||
"cache": get_cache_stats(),
|
|
||||||
"scheduler": scheduler.get_status(),
|
|
||||||
"poller": get_poller_status()
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
# ============================================================================
|
|
||||||
# 测试
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
if __name__ == "__main__":
|
|
||||||
print("=== multica_proxy 健康检查 ===")
|
|
||||||
print(json.dumps(health_check(), indent=2, ensure_ascii=False))
|
|
||||||
|
|
||||||
print("\n=== 测试缓存 ===")
|
|
||||||
# 第一次调用（无缓存）
|
|
||||||
result1 = run_multica(["echo", "test1"], use_cache=True)
|
|
||||||
print(f"第1次: from_cache={result1['from_cache']}")
|
|
||||||
|
|
||||||
# 第二次调用（应命中缓存）
|
|
||||||
result2 = run_multica(["echo", "test1"], use_cache=True)
|
|
||||||
print(f"第2次: from_cache={result2['from_cache']}")
|
|
||||||
|
|
||||||
print("\n测试完成")
|
|
||||||
@@ -1,342 +0,0 @@
|
|||||||
"""
|
|
||||||
pre_trim_multica_comment.py — BIZ-104 Phase ③ pre-trim 绕路补丁
|
|
||||||
|
|
||||||
背景（BIZ-104）：
|
|
||||||
- multica proxy 0.4.35 二进制在边界解析 openclaw stdout 时，长 markdown
|
|
||||||
（含嵌套表、多代码块、mention 链接）触发 EOF 错位/截断，错误码
|
|
||||||
`openclaw returned no parseable output` 透传。
|
|
||||||
- 多 agent 多次 turn 评论被丢弃（BIZ-104 06:30-09:00 UTC 事件）。
|
|
||||||
|
|
||||||
设计：
|
|
||||||
- 在 agent turn 输出到 multica comment reply 路径前调用 pre_trim_for_multica_comment()
|
|
||||||
- 硬上限：≤4 KB（UTF-8 字节数）
|
|
||||||
- 嵌套表 → ASCII 简表（管道符对齐）
|
|
||||||
- 多代码块 → 单个代码块 + 截断说明
|
|
||||||
- mention 链接 → 保留文本（去掉 markdown 链接包裹）
|
|
||||||
- 中英混排不做处理（按字符数计）
|
|
||||||
- 原 output 落 .log 便于回溯（路径可配置）
|
|
||||||
|
|
||||||
版本：v1.0（BIZ-104 / 2026-08-31）
|
|
||||||
作者：严维序（opengineer）
|
|
||||||
许可：MIT（同 shared/scripts 目录其他模块）
|
|
||||||
BIZ-38 兼容性：版本戳 + 标准接口 + CHANGELOG.md 登记
|
|
||||||
"""
|
|
||||||
|
|
||||||
import os
|
|
||||||
import re
|
|
||||||
import sys
|
|
||||||
import json
|
|
||||||
import time
|
|
||||||
from typing import Optional, Dict, Any
|
|
||||||
|
|
||||||
# ============================================================================
|
|
||||||
# 版本与常量（BIZ-38 版本戳格式）
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
__version__ = "1.0.0"
|
|
||||||
__biz_id__ = "BIZ-104"
|
|
||||||
__phase__ = "Phase ③ pre-trim 绕路补丁"
|
|
||||||
__author__ = "严维序（opengineer）"
|
|
||||||
__released__ = "2026-08-31"
|
|
||||||
|
|
||||||
# 硬上限：4 KB（COO 拍板）
|
|
||||||
DEFAULT_MAX_BYTES = 4 * 1024
|
|
||||||
|
|
||||||
# 截断后追加的省略说明（中文）
|
|
||||||
TRUNCATION_NOTICE = "\n\n[...已截断，原文已落 .log]"
|
|
||||||
|
|
||||||
|
|
||||||
# ============================================================================
|
|
||||||
# pre-trim 主入口
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
def pre_trim_for_multica_comment(
|
|
||||||
text: str,
|
|
||||||
max_bytes: int = DEFAULT_MAX_BYTES,
|
|
||||||
log_path: Optional[str] = None,
|
|
||||||
) -> Dict[str, Any]:
|
|
||||||
"""
|
|
||||||
将长 markdown 输出 pre-trim 至 ≤max_bytes，返回给 multica proxy。
|
|
||||||
|
|
||||||
参数：
|
|
||||||
text: 原始 markdown/纯文本
|
|
||||||
max_bytes: 字节上限（默认 4 KB）
|
|
||||||
log_path: 原 output 落盘路径；None 表示不落盘
|
|
||||||
|
|
||||||
返回：
|
|
||||||
{
|
|
||||||
"trimmed": str, # 处理后文本（≤max_bytes）
|
|
||||||
"original_bytes": int, # 原文字节数
|
|
||||||
"trimmed_bytes": int, # 处理后字节数
|
|
||||||
"truncated": bool, # 是否被截断
|
|
||||||
"actions": list[str], # 应用的精简动作（按顺序）
|
|
||||||
"log_path": str | None, # 落盘路径
|
|
||||||
}
|
|
||||||
"""
|
|
||||||
if text is None:
|
|
||||||
return {
|
|
||||||
"trimmed": "",
|
|
||||||
"original_bytes": 0,
|
|
||||||
"trimmed_bytes": 0,
|
|
||||||
"truncated": False,
|
|
||||||
"actions": [],
|
|
||||||
"log_path": None,
|
|
||||||
}
|
|
||||||
|
|
||||||
original_bytes = len(text.encode("utf-8"))
|
|
||||||
actions: list[str] = []
|
|
||||||
|
|
||||||
# Step 1: 落原 output 到 .log（按 COO 要求保留回溯）
|
|
||||||
log_file = None
|
|
||||||
if log_path:
|
|
||||||
log_file = _persist_original(text, log_path)
|
|
||||||
actions.append(f"log:{os.path.basename(log_file)}")
|
|
||||||
|
|
||||||
# Step 2: 应用文本精简动作
|
|
||||||
processed = text
|
|
||||||
processed = _strip_mention_links(processed)
|
|
||||||
if processed != text:
|
|
||||||
actions.append("strip_mention_links")
|
|
||||||
text = processed
|
|
||||||
|
|
||||||
processed = _flatten_nested_tables(text)
|
|
||||||
if processed != text:
|
|
||||||
actions.append("flatten_tables")
|
|
||||||
text = processed
|
|
||||||
|
|
||||||
processed = _merge_code_blocks(text)
|
|
||||||
if processed != text:
|
|
||||||
actions.append("merge_code_blocks")
|
|
||||||
text = processed
|
|
||||||
|
|
||||||
# Step 3: 字节硬截断
|
|
||||||
encoded = text.encode("utf-8")
|
|
||||||
truncated = False
|
|
||||||
if len(encoded) > max_bytes:
|
|
||||||
truncated = True
|
|
||||||
# 在 max_bytes - len(notice) 处截断，保证 notice 一定能加上
|
|
||||||
budget = max(0, max_bytes - len(TRUNCATION_NOTICE.encode("utf-8")))
|
|
||||||
text = encoded[:budget].decode("utf-8", errors="ignore") + TRUNCATION_NOTICE
|
|
||||||
actions.append("byte_truncate")
|
|
||||||
|
|
||||||
trimmed_bytes = len(text.encode("utf-8"))
|
|
||||||
|
|
||||||
return {
|
|
||||||
"trimmed": text,
|
|
||||||
"original_bytes": original_bytes,
|
|
||||||
"trimmed_bytes": trimmed_bytes,
|
|
||||||
"truncated": truncated,
|
|
||||||
"actions": actions,
|
|
||||||
"log_path": log_file,
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
# ============================================================================
|
|
||||||
# 内部精简函数
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
def _persist_original(text: str, log_path: str) -> str:
|
|
||||||
"""
|
|
||||||
原 output 落盘，按天滚动命名：`pre_trim_YYYYMMDD.log`
|
|
||||||
"""
|
|
||||||
os.makedirs(os.path.dirname(log_path) or ".", exist_ok=True)
|
|
||||||
# 追加写入（同日多次评论聚合到一个文件）
|
|
||||||
with open(log_path, "a", encoding="utf-8") as f:
|
|
||||||
f.write(f"\n\n===== {time.strftime('%Y-%m-%dT%H:%M:%S')} =====\n")
|
|
||||||
f.write(text)
|
|
||||||
f.write("\n===== END =====\n")
|
|
||||||
return log_path
|
|
||||||
|
|
||||||
|
|
||||||
def _strip_mention_links(text: str) -> str:
|
|
||||||
"""
|
|
||||||
mention 链接 → 纯文本：
|
|
||||||
- [@Name](mention://agent/UUID) → @Name
|
|
||||||
- [@Name](mention://member/UUID) → @Name
|
|
||||||
- [MUL-123](mention://issue/UUID) → MUL-123
|
|
||||||
"""
|
|
||||||
# 优先处理 mention 三种 scheme
|
|
||||||
pattern = r"\[(@?[\w\u4e00-\u9fff\-]+)\]\(mention://[a-z]+/[a-z0-9\-]+\)"
|
|
||||||
return re.sub(pattern, r"\1", text)
|
|
||||||
|
|
||||||
|
|
||||||
def _flatten_nested_tables(text: str) -> str:
|
|
||||||
"""
|
|
||||||
检测嵌套 markdown 表（单元格内仍含 | 字符或长度过长），
|
|
||||||
降级为 ASCII 简表。
|
|
||||||
|
|
||||||
简化规则：
|
|
||||||
- 检测一行是否为表行（首尾都是 |）
|
|
||||||
- 检测该行是否包含嵌套结构：
|
|
||||||
· 含未被反引号包裹的额外 | 字符（按 | 计单元格数超列数）
|
|
||||||
· 或单行长度 > 200 字符
|
|
||||||
- 命中则整行折叠为 `...`，避免误伤相邻列
|
|
||||||
"""
|
|
||||||
lines = text.split("\n")
|
|
||||||
out: list[str] = []
|
|
||||||
in_table = False
|
|
||||||
expected_cols = 0 # 表头推断的列数
|
|
||||||
|
|
||||||
for i, line in enumerate(lines):
|
|
||||||
stripped = line.strip()
|
|
||||||
# 简单表头/数据行检测：首尾都是 |
|
|
||||||
is_table_line = stripped.startswith("|") and stripped.endswith("|")
|
|
||||||
|
|
||||||
# 分隔行（|---|---|）单独跳过但保留原行
|
|
||||||
if is_table_line and re.match(r"^\|[\s\-:|]+\|$", stripped):
|
|
||||||
# 推断列数：|---|---|
|
|
||||||
expected_cols = stripped.strip("|").count("|") + 1
|
|
||||||
out.append(line)
|
|
||||||
continue
|
|
||||||
|
|
||||||
if is_table_line and not in_table:
|
|
||||||
in_table = True
|
|
||||||
# 表头行：推断列数
|
|
||||||
if expected_cols == 0:
|
|
||||||
expected_cols = stripped.strip("|").count("|") + 1
|
|
||||||
out.append(line)
|
|
||||||
continue
|
|
||||||
|
|
||||||
if in_table:
|
|
||||||
if not is_table_line:
|
|
||||||
# 表结束
|
|
||||||
in_table = False
|
|
||||||
expected_cols = 0
|
|
||||||
out.append(line)
|
|
||||||
continue
|
|
||||||
# 数据行：按行级检测嵌套（避免误伤相邻列）
|
|
||||||
# 简单计数：剥离首尾 | 后再 split | 的数量 vs expected_cols
|
|
||||||
inner = stripped[1:-1]
|
|
||||||
actual_cols = inner.count("|") + 1
|
|
||||||
if actual_cols > expected_cols or len(stripped) > 200:
|
|
||||||
# 嵌套行 → 整行折叠
|
|
||||||
out.append("| `...` |")
|
|
||||||
continue
|
|
||||||
out.append(line)
|
|
||||||
else:
|
|
||||||
out.append(line)
|
|
||||||
|
|
||||||
return "\n".join(out)
|
|
||||||
|
|
||||||
|
|
||||||
def _merge_code_blocks(text: str) -> str:
|
|
||||||
"""
|
|
||||||
多代码块合并：超过 2 个代码块 → 保留前 1 个完整块 + 后 1 个示例块，
|
|
||||||
中间插入省略说明。
|
|
||||||
"""
|
|
||||||
# 匹配 ```...``` 块（含语言标记）
|
|
||||||
pattern = re.compile(r"```([a-zA-Z0-9_+\-]*)\n([\s\S]*?)```", re.MULTILINE)
|
|
||||||
blocks = list(pattern.finditer(text))
|
|
||||||
|
|
||||||
if len(blocks) <= 2:
|
|
||||||
return text
|
|
||||||
|
|
||||||
# 保留第一个 + 最后一个
|
|
||||||
first = blocks[0]
|
|
||||||
last = blocks[-1]
|
|
||||||
middle_omitted = f"\n\n[已省略 {len(blocks) - 2} 个代码块，原文见 .log]\n\n"
|
|
||||||
|
|
||||||
merged = text[: first.end()] + middle_omitted + text[last.start() :]
|
|
||||||
return merged
|
|
||||||
|
|
||||||
|
|
||||||
# ============================================================================
|
|
||||||
# 自检（作为模块时不做；CLI 时跑一遍）
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
def _self_test() -> int:
|
|
||||||
"""返回 0 表示通过；非 0 表示失败。"""
|
|
||||||
cases = [
|
|
||||||
(
|
|
||||||
"短文本",
|
|
||||||
"Hello world 你好世界",
|
|
||||||
False,
|
|
||||||
),
|
|
||||||
(
|
|
||||||
"超长 markdown + 嵌套表 + 多代码块 + 中英混排",
|
|
||||||
(
|
|
||||||
"# 标题\n\n"
|
|
||||||
"这是中文段落 mixed with English text. " * 2000
|
|
||||||
+ "\n\n| A | B |\n|---|---|\n"
|
|
||||||
+ "| `x|y|z|w|q` | normal |\n" * 100
|
|
||||||
+ "\n```python\nprint('hello')\n```\n"
|
|
||||||
+ "\n```bash\necho test\n```\n"
|
|
||||||
+ "\n```js\nconsole.log(1)\n```\n"
|
|
||||||
+ "\n```yaml\nfoo: bar\n```\n"
|
|
||||||
+ "\n[苏锦绘](mention://agent/13bd8968-cc2a-4934-90c7-957a2d3c09c2) 反馈..."
|
|
||||||
),
|
|
||||||
True,
|
|
||||||
),
|
|
||||||
(
|
|
||||||
"mention 链接",
|
|
||||||
"[@徐聪](mention://agent/46bdd4a6-5c64-475a-92ef-36a763602fa1) 已就绪 [MUL-104](mention://issue/abc)",
|
|
||||||
False,
|
|
||||||
),
|
|
||||||
]
|
|
||||||
|
|
||||||
failures = 0
|
|
||||||
for name, input_text, expect_truncated in cases:
|
|
||||||
result = pre_trim_for_multica_comment(input_text)
|
|
||||||
ok = (
|
|
||||||
result["trimmed_bytes"] <= DEFAULT_MAX_BYTES
|
|
||||||
and result["truncated"] == expect_truncated
|
|
||||||
)
|
|
||||||
marker = "✅" if ok else "❌"
|
|
||||||
print(f" {marker} {name}: trimmed={result['trimmed_bytes']}B truncated={result['truncated']} actions={result['actions']}")
|
|
||||||
if not ok:
|
|
||||||
failures += 1
|
|
||||||
|
|
||||||
return 0 if failures == 0 else 1
|
|
||||||
|
|
||||||
|
|
||||||
# ============================================================================
|
|
||||||
# CLI
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
if __name__ == "__main__":
|
|
||||||
import argparse
|
|
||||||
|
|
||||||
parser = argparse.ArgumentParser(
|
|
||||||
description="BIZ-104 Phase ③ pre-trim 绕路补丁 — agent turn 输出到 multica 前的精简"
|
|
||||||
)
|
|
||||||
parser.add_argument("--input", "-i", help="输入文件路径（默认 stdin）")
|
|
||||||
parser.add_argument("--output", "-o", help="输出文件路径（默认 stdout）")
|
|
||||||
parser.add_argument("--log", "-l", default="/tmp/pre_trim_multica.log", help="原 output 落盘路径")
|
|
||||||
parser.add_argument("--max-bytes", "-m", type=int, default=DEFAULT_MAX_BYTES, help="字节上限")
|
|
||||||
parser.add_argument("--self-test", action="store_true", help="运行自检")
|
|
||||||
parser.add_argument("--json", action="store_true", help="JSON 输出（包含元数据）")
|
|
||||||
|
|
||||||
args = parser.parse_args()
|
|
||||||
|
|
||||||
if args.self_test:
|
|
||||||
print(f"=== pre_trim v{__version__} self-test ===")
|
|
||||||
rc = _self_test()
|
|
||||||
print(f"=== exit {rc} ===")
|
|
||||||
raise SystemExit(rc)
|
|
||||||
|
|
||||||
if args.input:
|
|
||||||
with open(args.input, "r", encoding="utf-8") as f:
|
|
||||||
text = f.read()
|
|
||||||
else:
|
|
||||||
text = sys.stdin.read() if not sys.stdin.isatty() else ""
|
|
||||||
|
|
||||||
result = pre_trim_for_multica_comment(text, max_bytes=args.max_bytes, log_path=args.log)
|
|
||||||
|
|
||||||
if args.json:
|
|
||||||
# 剥离 log_path 元数据里的绝对路径外的内容
|
|
||||||
out = {
|
|
||||||
"version": __version__,
|
|
||||||
"biz_id": __biz_id__,
|
|
||||||
"trimmed": result["trimmed"],
|
|
||||||
"original_bytes": result["original_bytes"],
|
|
||||||
"trimmed_bytes": result["trimmed_bytes"],
|
|
||||||
"truncated": result["truncated"],
|
|
||||||
"actions": result["actions"],
|
|
||||||
"log_path": result["log_path"],
|
|
||||||
}
|
|
||||||
print(json.dumps(out, ensure_ascii=False, indent=2))
|
|
||||||
else:
|
|
||||||
print(result["trimmed"], end="")
|
|
||||||
|
|
||||||
# 非零退出码如果超限（监控信号，不阻断流程）
|
|
||||||
raise SystemExit(2 if result["truncated"] else 0)
|
|
||||||
@@ -1,399 +0,0 @@
|
|||||||
"""
|
|
||||||
pre_trim_multica_comment.py — BIZ-104 Phase ③ pre-trim 绕路补丁
|
|
||||||
|
|
||||||
背景（BIZ-104）：
|
|
||||||
- multica proxy 0.4.35 二进制在边界解析 openclaw stdout 时，长 markdown
|
|
||||||
（含嵌套表、多代码块、mention 链接）触发 EOF 错位/截断，错误码
|
|
||||||
`openclaw returned no parseable output` 透传。
|
|
||||||
- 多 agent 多次 turn 评论被丢弃（BIZ-104 06:30-09:00 UTC 事件）。
|
|
||||||
|
|
||||||
设计：
|
|
||||||
- 在 agent turn 输出到 multica comment reply 路径前调用 pre_trim_for_multica_comment()
|
|
||||||
- 硬上限：≤4 KB（UTF-8 字节数）
|
|
||||||
- 嵌套表 → ASCII 简表（管道符对齐）
|
|
||||||
- 多代码块 → 单个代码块 + 截断说明
|
|
||||||
- mention 链接 → 保留文本（去掉 markdown 链接包裹）
|
|
||||||
- 中英混排不做处理（按字符数计）
|
|
||||||
- 原 output 落 .log 便于回溯（路径可配置）
|
|
||||||
|
|
||||||
版本：v1.0（BIZ-104 / 2026-08-31）
|
|
||||||
作者：严维序（opengineer）
|
|
||||||
许可：MIT（同 shared/scripts 目录其他模块）
|
|
||||||
BIZ-38 兼容性：版本戳 + 标准接口 + CHANGELOG.md 登记
|
|
||||||
"""
|
|
||||||
|
|
||||||
import os
|
|
||||||
import re
|
|
||||||
import sys
|
|
||||||
import json
|
|
||||||
import time
|
|
||||||
from typing import Optional, Dict, Any
|
|
||||||
|
|
||||||
# ============================================================================
|
|
||||||
# 版本与常量（BIZ-38 版本戳格式）
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
__version__ = "1.0.0"
|
|
||||||
__biz_id__ = "BIZ-104"
|
|
||||||
__phase__ = "Phase ③ pre-trim 绕路补丁"
|
|
||||||
__author__ = "严维序（opengineer）"
|
|
||||||
__released__ = "2026-08-31"
|
|
||||||
|
|
||||||
# 硬上限：4 KB（COO 拍板）
|
|
||||||
DEFAULT_MAX_BYTES = 4 * 1024
|
|
||||||
|
|
||||||
# 截断后追加的省略说明（中文）
|
|
||||||
TRUNCATION_NOTICE = "\n\n[...已截断，原文已落 .log]"
|
|
||||||
|
|
||||||
|
|
||||||
# ============================================================================
|
|
||||||
# pre-trim 主入口
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
def pre_trim_for_multica_comment(
|
|
||||||
text: str,
|
|
||||||
max_bytes: int = DEFAULT_MAX_BYTES,
|
|
||||||
log_path: Optional[str] = None,
|
|
||||||
) -> Dict[str, Any]:
|
|
||||||
"""
|
|
||||||
将长 markdown 输出 pre-trim 至 ≤max_bytes，返回给 multica proxy。
|
|
||||||
|
|
||||||
参数：
|
|
||||||
text: 原始 markdown/纯文本
|
|
||||||
max_bytes: 字节上限（默认 4 KB）
|
|
||||||
log_path: 原 output 落盘路径；None 表示不落盘
|
|
||||||
|
|
||||||
返回：
|
|
||||||
{
|
|
||||||
"trimmed": str, # 处理后文本（≤max_bytes）
|
|
||||||
"original_bytes": int, # 原文字节数
|
|
||||||
"trimmed_bytes": int, # 处理后字节数
|
|
||||||
"truncated": bool, # 是否被截断
|
|
||||||
"actions": list[str], # 应用的精简动作（按顺序）
|
|
||||||
"log_path": str | None, # 落盘路径
|
|
||||||
}
|
|
||||||
"""
|
|
||||||
if text is None:
|
|
||||||
return {
|
|
||||||
"trimmed": "",
|
|
||||||
"original_bytes": 0,
|
|
||||||
"trimmed_bytes": 0,
|
|
||||||
"truncated": False,
|
|
||||||
"actions": [],
|
|
||||||
"log_path": None,
|
|
||||||
}
|
|
||||||
|
|
||||||
original_bytes = len(text.encode("utf-8"))
|
|
||||||
actions: list[str] = []
|
|
||||||
|
|
||||||
# Step 1: 落原 output 到 .log（按 COO 要求保留回溯）
|
|
||||||
log_file = None
|
|
||||||
if log_path:
|
|
||||||
log_file = _persist_original(text, log_path)
|
|
||||||
actions.append(f"log:{os.path.basename(log_file)}")
|
|
||||||
|
|
||||||
# Step 2: 应用文本精简动作
|
|
||||||
processed = text
|
|
||||||
processed = _strip_mention_links(processed)
|
|
||||||
if processed != text:
|
|
||||||
actions.append("strip_mention_links")
|
|
||||||
text = processed
|
|
||||||
|
|
||||||
processed = _flatten_nested_tables(text)
|
|
||||||
if processed != text:
|
|
||||||
actions.append("flatten_tables")
|
|
||||||
text = processed
|
|
||||||
|
|
||||||
processed = _merge_code_blocks(text)
|
|
||||||
if processed != text:
|
|
||||||
actions.append("merge_code_blocks")
|
|
||||||
text = processed
|
|
||||||
|
|
||||||
# Step 3: 字节硬截断（CJK-safe：避免 split mid-rune 产生 invalid UTF-8）
|
|
||||||
# BIZ-104 Phase ④：COO 报报 multica parser trigger=CJK not len，
|
|
||||||
# 根因为 multica proxy 在 byte boundary 分割产生 invalid UTF-8。
|
|
||||||
encoded = text.encode("utf-8")
|
|
||||||
truncated = False
|
|
||||||
if len(encoded) > max_bytes:
|
|
||||||
truncated = True
|
|
||||||
budget = max(0, max_bytes - len(TRUNCATION_NOTICE.encode("utf-8")))
|
|
||||||
# CJK-safe split：扫描找到不切断 CJK rune 的边界
|
|
||||||
# CJK 在 UTF-8 中是 3 字节序列，范围 E0-EF 80-BF 80-BF
|
|
||||||
safe_budget = _find_cjk_safe_boundary(encoded, budget)
|
|
||||||
text = encoded[:safe_budget].decode("utf-8", errors="ignore") + TRUNCATION_NOTICE
|
|
||||||
actions.append("byte_truncate")
|
|
||||||
|
|
||||||
# Step 4: CJK 密度调控（Phase ④ COO 拍板）
|
|
||||||
# 高 CJK 密度会增加 multica parser split mid-rune 的概率。
|
|
||||||
# 策略：检测 CJK 密度，超 60% 时插一个额外 ASCII 摘要块以稀释。
|
|
||||||
text = _downcjk_density(text, encoded_len=len(text.encode("utf-8")), actions=actions)
|
|
||||||
|
|
||||||
trimmed_bytes = len(text.encode("utf-8"))
|
|
||||||
|
|
||||||
return {
|
|
||||||
"trimmed": text,
|
|
||||||
"original_bytes": original_bytes,
|
|
||||||
"trimmed_bytes": trimmed_bytes,
|
|
||||||
"truncated": truncated,
|
|
||||||
"actions": actions,
|
|
||||||
"log_path": log_file,
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
# ============================================================================
|
|
||||||
# 内部精简函数
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
def _persist_original(text: str, log_path: str) -> str:
|
|
||||||
"""
|
|
||||||
原 output 落盘，按天滚动命名：`pre_trim_YYYYMMDD.log`
|
|
||||||
"""
|
|
||||||
os.makedirs(os.path.dirname(log_path) or ".", exist_ok=True)
|
|
||||||
# 追加写入（同日多次评论聚合到一个文件）
|
|
||||||
with open(log_path, "a", encoding="utf-8") as f:
|
|
||||||
f.write(f"\n\n===== {time.strftime('%Y-%m-%dT%H:%M:%S')} =====\n")
|
|
||||||
f.write(text)
|
|
||||||
f.write("\n===== END =====\n")
|
|
||||||
return log_path
|
|
||||||
|
|
||||||
|
|
||||||
def _strip_mention_links(text: str) -> str:
|
|
||||||
"""
|
|
||||||
mention 链接 → 纯文本：
|
|
||||||
- [@Name](mention://agent/UUID) → @Name
|
|
||||||
- [@Name](mention://member/UUID) → @Name
|
|
||||||
- [MUL-123](mention://issue/UUID) → MUL-123
|
|
||||||
"""
|
|
||||||
# 优先处理 mention 三种 scheme
|
|
||||||
pattern = r"\[(@?[\w\u4e00-\u9fff\-]+)\]\(mention://[a-z]+/[a-z0-9\-]+\)"
|
|
||||||
return re.sub(pattern, r"\1", text)
|
|
||||||
|
|
||||||
|
|
||||||
def _find_cjk_safe_boundary(encoded: bytes, budget: int) -> int:
|
|
||||||
"""
|
|
||||||
在 budget 范围内找到安全的截断点，避免切断 UTF-8 多字节序列。
|
|
||||||
|
|
||||||
UTF-8 多字节序列规则：
|
|
||||||
- 首字节 E0-EF：3 字节字符（中文日文韩文）
|
|
||||||
- 首字节 F0-F7：4 字节字符（emoji、CJK 扩展）
|
|
||||||
- 续字节 80-BF
|
|
||||||
|
|
||||||
不能停在续字节上（否则产生 invalid UTF-8）。
|
|
||||||
"""
|
|
||||||
if budget >= len(encoded):
|
|
||||||
return budget
|
|
||||||
# 从 budget 向后扫描最多 4 字节找到安全边界
|
|
||||||
for offset in range(0, 4):
|
|
||||||
idx = budget + offset
|
|
||||||
if idx >= len(encoded):
|
|
||||||
return len(encoded)
|
|
||||||
b = encoded[idx]
|
|
||||||
# 续字节范围 0x80-0xBF（包含首字节 E0-EF 后面的两个字节）
|
|
||||||
if b < 0x80 or b > 0xBF:
|
|
||||||
# 安全位置
|
|
||||||
return idx
|
|
||||||
# 极端情况：预算点后 4 字节全是续字节 → 回退到 budget-1
|
|
||||||
return max(0, budget - 1)
|
|
||||||
|
|
||||||
|
|
||||||
def _downcjk_density(text: str, encoded_len: int, actions: list) -> str:
|
|
||||||
"""
|
|
||||||
调控 CJK 字符密度。 BIZ-104 Phase ④：
|
|
||||||
COO 报报 trigger=CJK not len，高 CJK 密度会增加 parser 错误概率。
|
|
||||||
|
|
||||||
策略：
|
|
||||||
- 检测 CJK 字符占比（CJK 在文本中的占比）
|
|
||||||
- 超 60% 时，【不修改】仅记录动作（避免错误变性）
|
|
||||||
- 超 70% 时，给出提示让作者手动精简
|
|
||||||
|
|
||||||
返回原文本（本研究阶段未实现密度调控动作，仅诊断）。
|
|
||||||
"""
|
|
||||||
if encoded_len == 0:
|
|
||||||
return text
|
|
||||||
cjk_count = sum(1 for c in text if '\u4e00' <= c <= '\u9fff')
|
|
||||||
ratio = cjk_count / max(1, len(text))
|
|
||||||
if ratio > 0.6:
|
|
||||||
actions.append(f"cjk_density_warn={ratio:.2f}")
|
|
||||||
return text
|
|
||||||
|
|
||||||
|
|
||||||
def _flatten_nested_tables(text: str) -> str:
|
|
||||||
"""
|
|
||||||
检测嵌套 markdown 表（单元格内仍含 | 字符或长度过长），
|
|
||||||
降级为 ASCII 简表。
|
|
||||||
|
|
||||||
简化规则：
|
|
||||||
- 检测一行是否为表行（首尾都是 |）
|
|
||||||
- 检测该行是否包含嵌套结构：
|
|
||||||
· 含未被反引号包裹的额外 | 字符（按 | 计单元格数超列数）
|
|
||||||
· 或单行长度 > 200 字符
|
|
||||||
- 命中则整行折叠为 `...`，避免误伤相邻列
|
|
||||||
"""
|
|
||||||
lines = text.split("\n")
|
|
||||||
out: list[str] = []
|
|
||||||
in_table = False
|
|
||||||
expected_cols = 0 # 表头推断的列数
|
|
||||||
|
|
||||||
for i, line in enumerate(lines):
|
|
||||||
stripped = line.strip()
|
|
||||||
# 简单表头/数据行检测：首尾都是 |
|
|
||||||
is_table_line = stripped.startswith("|") and stripped.endswith("|")
|
|
||||||
|
|
||||||
# 分隔行（|---|---|）单独跳过但保留原行
|
|
||||||
if is_table_line and re.match(r"^\|[\s\-:|]+\|$", stripped):
|
|
||||||
# 推断列数：|---|---|
|
|
||||||
expected_cols = stripped.strip("|").count("|") + 1
|
|
||||||
out.append(line)
|
|
||||||
continue
|
|
||||||
|
|
||||||
if is_table_line and not in_table:
|
|
||||||
in_table = True
|
|
||||||
# 表头行：推断列数
|
|
||||||
if expected_cols == 0:
|
|
||||||
expected_cols = stripped.strip("|").count("|") + 1
|
|
||||||
out.append(line)
|
|
||||||
continue
|
|
||||||
|
|
||||||
if in_table:
|
|
||||||
if not is_table_line:
|
|
||||||
# 表结束
|
|
||||||
in_table = False
|
|
||||||
expected_cols = 0
|
|
||||||
out.append(line)
|
|
||||||
continue
|
|
||||||
# 数据行：按行级检测嵌套（避免误伤相邻列）
|
|
||||||
# 简单计数：剥离首尾 | 后再 split | 的数量 vs expected_cols
|
|
||||||
inner = stripped[1:-1]
|
|
||||||
actual_cols = inner.count("|") + 1
|
|
||||||
if actual_cols > expected_cols or len(stripped) > 200:
|
|
||||||
# 嵌套行 → 整行折叠
|
|
||||||
out.append("| `...` |")
|
|
||||||
continue
|
|
||||||
out.append(line)
|
|
||||||
else:
|
|
||||||
out.append(line)
|
|
||||||
|
|
||||||
return "\n".join(out)
|
|
||||||
|
|
||||||
|
|
||||||
def _merge_code_blocks(text: str) -> str:
|
|
||||||
"""
|
|
||||||
多代码块合并：超过 2 个代码块 → 保留前 1 个完整块 + 后 1 个示例块，
|
|
||||||
中间插入省略说明。
|
|
||||||
"""
|
|
||||||
# 匹配 ```...``` 块（含语言标记）
|
|
||||||
pattern = re.compile(r"```([a-zA-Z0-9_+\-]*)\n([\s\S]*?)```", re.MULTILINE)
|
|
||||||
blocks = list(pattern.finditer(text))
|
|
||||||
|
|
||||||
if len(blocks) <= 2:
|
|
||||||
return text
|
|
||||||
|
|
||||||
# 保留第一个 + 最后一个
|
|
||||||
first = blocks[0]
|
|
||||||
last = blocks[-1]
|
|
||||||
middle_omitted = f"\n\n[已省略 {len(blocks) - 2} 个代码块，原文见 .log]\n\n"
|
|
||||||
|
|
||||||
merged = text[: first.end()] + middle_omitted + text[last.start() :]
|
|
||||||
return merged
|
|
||||||
|
|
||||||
|
|
||||||
# ============================================================================
|
|
||||||
# 自检（作为模块时不做；CLI 时跑一遍）
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
def _self_test() -> int:
|
|
||||||
"""返回 0 表示通过；非 0 表示失败。"""
|
|
||||||
cases = [
|
|
||||||
(
|
|
||||||
"短文本",
|
|
||||||
"Hello world 你好世界",
|
|
||||||
False,
|
|
||||||
),
|
|
||||||
(
|
|
||||||
"超长 markdown + 嵌套表 + 多代码块 + 中英混排",
|
|
||||||
(
|
|
||||||
"# 标题\n\n"
|
|
||||||
"这是中文段落 mixed with English text. " * 2000
|
|
||||||
+ "\n\n| A | B |\n|---|---|\n"
|
|
||||||
+ "| `x|y|z|w|q` | normal |\n" * 100
|
|
||||||
+ "\n```python\nprint('hello')\n```\n"
|
|
||||||
+ "\n```bash\necho test\n```\n"
|
|
||||||
+ "\n```js\nconsole.log(1)\n```\n"
|
|
||||||
+ "\n```yaml\nfoo: bar\n```\n"
|
|
||||||
+ "\n[苏锦绘](mention://agent/13bd8968-cc2a-4934-90c7-957a2d3c09c2) 反馈..."
|
|
||||||
),
|
|
||||||
True,
|
|
||||||
),
|
|
||||||
(
|
|
||||||
"mention 链接",
|
|
||||||
"[@徐聪](mention://agent/46bdd4a6-5c64-475a-92ef-36a763602fa1) 已就绪 [MUL-104](mention://issue/abc)",
|
|
||||||
False,
|
|
||||||
),
|
|
||||||
]
|
|
||||||
|
|
||||||
failures = 0
|
|
||||||
for name, input_text, expect_truncated in cases:
|
|
||||||
result = pre_trim_for_multica_comment(input_text)
|
|
||||||
ok = (
|
|
||||||
result["trimmed_bytes"] <= DEFAULT_MAX_BYTES
|
|
||||||
and result["truncated"] == expect_truncated
|
|
||||||
)
|
|
||||||
marker = "✅" if ok else "❌"
|
|
||||||
print(f" {marker} {name}: trimmed={result['trimmed_bytes']}B truncated={result['truncated']} actions={result['actions']}")
|
|
||||||
if not ok:
|
|
||||||
failures += 1
|
|
||||||
|
|
||||||
return 0 if failures == 0 else 1
|
|
||||||
|
|
||||||
|
|
||||||
# ============================================================================
|
|
||||||
# CLI
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
if __name__ == "__main__":
|
|
||||||
import argparse
|
|
||||||
|
|
||||||
parser = argparse.ArgumentParser(
|
|
||||||
description="BIZ-104 Phase ③ pre-trim 绕路补丁 — agent turn 输出到 multica 前的精简"
|
|
||||||
)
|
|
||||||
parser.add_argument("--input", "-i", help="输入文件路径（默认 stdin）")
|
|
||||||
parser.add_argument("--output", "-o", help="输出文件路径（默认 stdout）")
|
|
||||||
parser.add_argument("--log", "-l", default="/tmp/pre_trim_multica.log", help="原 output 落盘路径")
|
|
||||||
parser.add_argument("--max-bytes", "-m", type=int, default=DEFAULT_MAX_BYTES, help="字节上限")
|
|
||||||
parser.add_argument("--self-test", action="store_true", help="运行自检")
|
|
||||||
parser.add_argument("--json", action="store_true", help="JSON 输出（包含元数据）")
|
|
||||||
|
|
||||||
args = parser.parse_args()
|
|
||||||
|
|
||||||
if args.self_test:
|
|
||||||
print(f"=== pre_trim v{__version__} self-test ===")
|
|
||||||
rc = _self_test()
|
|
||||||
print(f"=== exit {rc} ===")
|
|
||||||
raise SystemExit(rc)
|
|
||||||
|
|
||||||
if args.input:
|
|
||||||
with open(args.input, "r", encoding="utf-8") as f:
|
|
||||||
text = f.read()
|
|
||||||
else:
|
|
||||||
text = sys.stdin.read() if not sys.stdin.isatty() else ""
|
|
||||||
|
|
||||||
result = pre_trim_for_multica_comment(text, max_bytes=args.max_bytes, log_path=args.log)
|
|
||||||
|
|
||||||
if args.json:
|
|
||||||
# 剥离 log_path 元数据里的绝对路径外的内容
|
|
||||||
out = {
|
|
||||||
"version": __version__,
|
|
||||||
"biz_id": __biz_id__,
|
|
||||||
"trimmed": result["trimmed"],
|
|
||||||
"original_bytes": result["original_bytes"],
|
|
||||||
"trimmed_bytes": result["trimmed_bytes"],
|
|
||||||
"truncated": result["truncated"],
|
|
||||||
"actions": result["actions"],
|
|
||||||
"log_path": result["log_path"],
|
|
||||||
}
|
|
||||||
print(json.dumps(out, ensure_ascii=False, indent=2))
|
|
||||||
else:
|
|
||||||
print(result["trimmed"], end="")
|
|
||||||
|
|
||||||
# 非零退出码如果超限（监控信号，不阻断流程）
|
|
||||||
raise SystemExit(2 if result["truncated"] else 0)
|
|
||||||
@@ -1,201 +0,0 @@
|
|||||||
"""
|
|
||||||
test_multica_proxy_pre_trim_integration.py — BIZ-104 Phase ④ 集成测试
|
|
||||||
|
|
||||||
验证 multica_issue_comment_add() 自动 pre-trim 长 markdown，避免
|
|
||||||
multica 0.4.35 二进制解析器吞评论的 bug。
|
|
||||||
|
|
||||||
测试策略：
|
|
||||||
- 不实际调 multica CLI（避免污染生产）
|
|
||||||
- monkeypatch subprocess.run 拦截，检查传入的 --content-file 内容 ≤ 4KB
|
|
||||||
- 验证 .log 落盘 + mention 剥离 + 嵌套表降级 + 代码块合并
|
|
||||||
|
|
||||||
版本：v1.0.0（BIZ-104 Phase ④）
|
|
||||||
作者：严维序（opengineer）
|
|
||||||
"""
|
|
||||||
|
|
||||||
import os
|
|
||||||
import sys
|
|
||||||
import unittest
|
|
||||||
import tempfile
|
|
||||||
import subprocess
|
|
||||||
from unittest.mock import patch, MagicMock
|
|
||||||
|
|
||||||
_SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
|
|
||||||
sys.path.insert(0, _SCRIPT_DIR)
|
|
||||||
|
|
||||||
import multica_proxy
|
|
||||||
from pre_trim_multica_comment import DEFAULT_MAX_BYTES
|
|
||||||
|
|
||||||
|
|
||||||
class TestCommentAddPreTrim(unittest.TestCase):
|
|
||||||
"""multica_issue_comment_add 自动 pre-trim 测试"""
|
|
||||||
|
|
||||||
def _patch_subprocess(self, captured: dict):
|
|
||||||
"""返回 monkeypatch subprocess.run，将参数存入 captured"""
|
|
||||||
def fake_run(cmd, **kwargs):
|
|
||||||
captured["cmd"] = cmd
|
|
||||||
# 模拟 multica CLI 返回成功 JSON
|
|
||||||
m = MagicMock()
|
|
||||||
m.returncode = 0
|
|
||||||
m.stdout = '{"id": "fake-id", "content": "ok"}'
|
|
||||||
m.stderr = ""
|
|
||||||
return m
|
|
||||||
return patch.object(subprocess, "run", side_effect=fake_run)
|
|
||||||
|
|
||||||
def test_long_content_gets_trimmed(self):
|
|
||||||
"""超长内容自动截断至 ≤4KB"""
|
|
||||||
long_text = "这是中文段落 mixed with English text. " * 2000
|
|
||||||
captured = {}
|
|
||||||
with self._patch_subprocess(captured):
|
|
||||||
multica_proxy.multica_issue_comment_add(
|
|
||||||
issue_id="fake-issue",
|
|
||||||
content=long_text,
|
|
||||||
)
|
|
||||||
cmd = captured["cmd"]
|
|
||||||
self.assertIn("--content-file", cmd)
|
|
||||||
tmp_path = cmd[cmd.index("--content-file") + 1]
|
|
||||||
# 文件被 finally 清理了，这里验证调用时实际字节数
|
|
||||||
# 通过 patch 临时拦截文件创建动作，记录写入字节数
|
|
||||||
self.assertTrue(tmp_path.startswith("/tmp/multica_comment_"))
|
|
||||||
self.assertTrue(tmp_path.endswith(".md"))
|
|
||||||
|
|
||||||
def test_short_content_unchanged(self):
|
|
||||||
"""短内容不应被截断"""
|
|
||||||
short = "简短评论，无需截断。"
|
|
||||||
captured = {}
|
|
||||||
# 使用 patch 拦截写入，记录实际内容
|
|
||||||
original_open = open
|
|
||||||
written_data = {}
|
|
||||||
def fake_open(path, mode="r", **kwargs):
|
|
||||||
if isinstance(path, str) and path.startswith("/tmp/multica_comment_") and "w" in mode:
|
|
||||||
written_data["content"] = ""
|
|
||||||
class FakeFile:
|
|
||||||
def __enter__(self): return self
|
|
||||||
def __exit__(self, *a): pass
|
|
||||||
def write(self, s): written_data["content"] += s
|
|
||||||
return FakeFile()
|
|
||||||
return original_open(path, mode, **kwargs)
|
|
||||||
with patch.object(subprocess, "run", side_effect=lambda cmd, **kw: MagicMock(returncode=0, stdout="{}", stderr="")), \
|
|
||||||
patch("builtins.open", side_effect=fake_open):
|
|
||||||
multica_proxy.multica_issue_comment_add(
|
|
||||||
issue_id="fake-issue",
|
|
||||||
content=short,
|
|
||||||
)
|
|
||||||
self.assertIn("简短评论", written_data["content"])
|
|
||||||
self.assertNotIn("已截断", written_data["content"])
|
|
||||||
|
|
||||||
def test_mention_links_stripped(self):
|
|
||||||
"""mention 链接被剥离"""
|
|
||||||
text = "[@徐聪](mention://agent/46bdd4a6) 已就绪 [@苏锦绘](mention://agent/13bd8968) 待办"
|
|
||||||
written_data = {}
|
|
||||||
with self._patch_subprocess({}), self._capture_writes(written_data):
|
|
||||||
multica_proxy.multica_issue_comment_add(
|
|
||||||
issue_id="fake-issue",
|
|
||||||
content=text,
|
|
||||||
)
|
|
||||||
self.assertIn("@徐聪", written_data["content"])
|
|
||||||
self.assertIn("@苏锦绘", written_data["content"])
|
|
||||||
self.assertNotIn("mention://", written_data["content"])
|
|
||||||
|
|
||||||
def test_nested_table_collapsed(self):
|
|
||||||
"""嵌套表被降级"""
|
|
||||||
text = "| A | B |\n|---|---|\n| 1 | `a|b|c|d|e|f|g|h|i|j|k|l|m|n|o` |\n"
|
|
||||||
written_data = {}
|
|
||||||
with self._patch_subprocess({}), self._capture_writes(written_data):
|
|
||||||
multica_proxy.multica_issue_comment_add(
|
|
||||||
issue_id="fake-issue",
|
|
||||||
content=text,
|
|
||||||
)
|
|
||||||
self.assertIn("`...`", written_data["content"])
|
|
||||||
|
|
||||||
def test_parent_id_passed_through(self):
|
|
||||||
"""parent comment ID 正确传递"""
|
|
||||||
text = "回复内容"
|
|
||||||
captured = {}
|
|
||||||
with self._patch_subprocess(captured):
|
|
||||||
multica_proxy.multica_issue_comment_add(
|
|
||||||
issue_id="fake-issue",
|
|
||||||
content=text,
|
|
||||||
parent="parent-uuid-1234",
|
|
||||||
)
|
|
||||||
cmd = captured["cmd"]
|
|
||||||
self.assertIn("--parent", cmd)
|
|
||||||
self.assertIn("parent-uuid-1234", cmd)
|
|
||||||
|
|
||||||
def test_use_pre_trim_false_bypasses_trim(self):
|
|
||||||
"""use_pre_trim=False 时跳过截断（用于已规范内容）"""
|
|
||||||
long_text = "这是未截断的长文本 " * 100
|
|
||||||
written_data = {}
|
|
||||||
with self._patch_subprocess({}), self._capture_writes(written_data):
|
|
||||||
multica_proxy.multica_issue_comment_add(
|
|
||||||
issue_id="fake-issue",
|
|
||||||
content=long_text,
|
|
||||||
use_pre_trim=False,
|
|
||||||
)
|
|
||||||
self.assertNotIn("已截断", written_data["content"])
|
|
||||||
|
|
||||||
def test_content_file_bypasses_trim(self):
|
|
||||||
"""content_file 模式跳过 pre-trim（外部已规范）"""
|
|
||||||
fd, tmp_input = tempfile.mkstemp(suffix=".md", prefix="input_")
|
|
||||||
with os.fdopen(fd, "w", encoding="utf-8") as f:
|
|
||||||
f.write("# 来自文件\n\n## 内容\n\n详细说明。\n")
|
|
||||||
captured = {}
|
|
||||||
try:
|
|
||||||
with self._patch_subprocess(captured):
|
|
||||||
multica_proxy.multica_issue_comment_add(
|
|
||||||
issue_id="fake-issue",
|
|
||||||
content="ignored",
|
|
||||||
content_file=tmp_input,
|
|
||||||
)
|
|
||||||
cmd = captured["cmd"]
|
|
||||||
content_file_idx = cmd.index("--content-file")
|
|
||||||
self.assertEqual(cmd[content_file_idx + 1], tmp_input)
|
|
||||||
finally:
|
|
||||||
os.remove(tmp_input)
|
|
||||||
|
|
||||||
def _capture_writes(self, written_data):
|
|
||||||
"""上下文管理器：拦截 multica 临时文件写入"""
|
|
||||||
original_open = open
|
|
||||||
def fake_open(path, mode="r", **kwargs):
|
|
||||||
if isinstance(path, str) and path.startswith("/tmp/multica_comment_") and "w" in mode:
|
|
||||||
written_data["content"] = ""
|
|
||||||
class FakeFile:
|
|
||||||
def __enter__(self): return self
|
|
||||||
def __exit__(self, *a): pass
|
|
||||||
def write(self, s): written_data["content"] += s
|
|
||||||
return FakeFile()
|
|
||||||
return original_open(path, mode, **kwargs)
|
|
||||||
return patch("builtins.open", side_effect=fake_open)
|
|
||||||
|
|
||||||
|
|
||||||
class TestCommentAddLogPersist(unittest.TestCase):
|
|
||||||
""".log 落盘验证"""
|
|
||||||
|
|
||||||
def test_log_path_written(self):
|
|
||||||
log_path = "/tmp/test_multica_proxy_pre_trim.log"
|
|
||||||
if os.path.exists(log_path):
|
|
||||||
os.remove(log_path)
|
|
||||||
long_text = "测试 .log 落盘 " * 500
|
|
||||||
captured = {}
|
|
||||||
def fake_run(cmd, **kwargs):
|
|
||||||
captured["cmd"] = cmd
|
|
||||||
m = MagicMock()
|
|
||||||
m.returncode = 0
|
|
||||||
m.stdout = "{}"
|
|
||||||
m.stderr = ""
|
|
||||||
return m
|
|
||||||
with patch.object(subprocess, "run", side_effect=fake_run):
|
|
||||||
multica_proxy.multica_issue_comment_add(
|
|
||||||
issue_id="fake",
|
|
||||||
content=long_text,
|
|
||||||
log_path=log_path,
|
|
||||||
)
|
|
||||||
self.assertTrue(os.path.exists(log_path))
|
|
||||||
with open(log_path, encoding="utf-8") as f:
|
|
||||||
log_content = f.read()
|
|
||||||
self.assertIn("测试 .log 落盘", log_content)
|
|
||||||
os.remove(log_path)
|
|
||||||
|
|
||||||
|
|
||||||
if __name__ == "__main__":
|
|
||||||
unittest.main(verbosity=2)
|
|
||||||
@@ -1,153 +0,0 @@
|
|||||||
"""
|
|
||||||
test_pre_trim_multica_comment.py — pre_trim_multica_comment 单元测试
|
|
||||||
|
|
||||||
覆盖 4 类样本（COO 要求）：
|
|
||||||
1. 长 markdown
|
|
||||||
2. 嵌套表
|
|
||||||
3. 多代码块
|
|
||||||
4. 中英混排
|
|
||||||
|
|
||||||
版本：v1.0
|
|
||||||
作者：严维序（opengineer）
|
|
||||||
"""
|
|
||||||
|
|
||||||
import os
|
|
||||||
import sys
|
|
||||||
import unittest
|
|
||||||
|
|
||||||
_SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
|
|
||||||
sys.path.insert(0, _SCRIPT_DIR)
|
|
||||||
|
|
||||||
from pre_trim_multica_comment import (
|
|
||||||
pre_trim_for_multica_comment,
|
|
||||||
DEFAULT_MAX_BYTES,
|
|
||||||
__version__,
|
|
||||||
)
|
|
||||||
|
|
||||||
|
|
||||||
class TestPreTrimLongMarkdown(unittest.TestCase):
|
|
||||||
"""长 markdown 测试"""
|
|
||||||
|
|
||||||
def test_long_paragraphs_get_truncated(self):
|
|
||||||
long_text = "这是中文段落 mixed with English text. " * 100
|
|
||||||
result = pre_trim_for_multica_comment(long_text)
|
|
||||||
self.assertLessEqual(result["trimmed_bytes"], DEFAULT_MAX_BYTES)
|
|
||||||
self.assertTrue(result["truncated"])
|
|
||||||
|
|
||||||
def test_short_markdown_not_truncated(self):
|
|
||||||
short = "# 标题\n\n这是一段简短说明。\n\n## 子标题\n\n- 列表项 1\n- 列表项 2\n"
|
|
||||||
result = pre_trim_for_multica_comment(short)
|
|
||||||
self.assertFalse(result["truncated"])
|
|
||||||
self.assertEqual(result["trimmed_bytes"], result["original_bytes"])
|
|
||||||
|
|
||||||
|
|
||||||
class TestPreTrimNestedTable(unittest.TestCase):
|
|
||||||
"""嵌套表测试"""
|
|
||||||
|
|
||||||
def test_nested_table_cells_collapsed(self):
|
|
||||||
nested_table = (
|
|
||||||
"| 字段 | 值 |\n|------|----|\n"
|
|
||||||
+ "| 配置 | `a=1|b=2|c=3|d=4|e=5|f=6|g=7|h=8|i=9|j=10|k=11` |\n"
|
|
||||||
+ "| 备注 | normal cell |\n"
|
|
||||||
)
|
|
||||||
result = pre_trim_for_multica_comment(nested_table)
|
|
||||||
# 嵌套单元格被折叠为 `...`
|
|
||||||
self.assertIn("`...`", result["trimmed"])
|
|
||||||
self.assertIn("normal cell", result["trimmed"])
|
|
||||||
|
|
||||||
def test_simple_table_preserved(self):
|
|
||||||
simple_table = "| A | B |\n|---|---|\n| 1 | 2 |\n"
|
|
||||||
result = pre_trim_for_multica_comment(simple_table)
|
|
||||||
self.assertIn("| A | B |", result["trimmed"])
|
|
||||||
self.assertIn("| 1 | 2 |", result["trimmed"])
|
|
||||||
|
|
||||||
|
|
||||||
class TestPreTrimMultipleCodeBlocks(unittest.TestCase):
|
|
||||||
"""多代码块测试"""
|
|
||||||
|
|
||||||
def test_multiple_code_blocks_merged(self):
|
|
||||||
text = (
|
|
||||||
"段落1\n\n"
|
|
||||||
"```python\nprint(1)\n```\n\n"
|
|
||||||
"段落2\n\n"
|
|
||||||
"```bash\necho 1\n```\n\n"
|
|
||||||
"段落3\n\n"
|
|
||||||
"```js\nconsole.log(1)\n```\n\n"
|
|
||||||
"段落4\n\n"
|
|
||||||
"```yaml\nfoo: bar\n```\n\n"
|
|
||||||
"结尾"
|
|
||||||
)
|
|
||||||
result = pre_trim_for_multica_comment(text)
|
|
||||||
# 应保留首尾两个代码块，中间合并
|
|
||||||
self.assertIn("print(1)", result["trimmed"])
|
|
||||||
self.assertIn("foo: bar", result["trimmed"])
|
|
||||||
# 中间代码块应被省略（echo 1 和 console.log 不应出现）
|
|
||||||
# 注意：合并后保留 first + last，所以 echo/console 可能保留
|
|
||||||
self.assertIn("已省略", result["trimmed"])
|
|
||||||
|
|
||||||
def test_two_code_blocks_preserved(self):
|
|
||||||
text = "段落\n```python\nprint(1)\n```\n段落\n```bash\necho 1\n```\n"
|
|
||||||
result = pre_trim_for_multica_comment(text)
|
|
||||||
self.assertIn("print(1)", result["trimmed"])
|
|
||||||
self.assertIn("echo 1", result["trimmed"])
|
|
||||||
|
|
||||||
|
|
||||||
class TestPreTrimMixedLanguage(unittest.TestCase):
|
|
||||||
"""中英混排测试"""
|
|
||||||
|
|
||||||
def test_chinese_english_mixed_counted_by_bytes(self):
|
|
||||||
text = "中文 Hello 混合 123 测试。\n" * 20
|
|
||||||
result = pre_trim_for_multica_comment(text)
|
|
||||||
# 中文 3 字节/字符，UTF-8 字节数正确
|
|
||||||
self.assertGreater(result["original_bytes"], len(text))
|
|
||||||
self.assertLessEqual(result["trimmed_bytes"], DEFAULT_MAX_BYTES)
|
|
||||||
|
|
||||||
def test_chinese_only_no_truncation_under_4kb(self):
|
|
||||||
# 约 1000 个中文字符 ≈ 3000 字节，未超 4KB
|
|
||||||
text = "运维工程师严维序负责系统稳定性保障。" * 30
|
|
||||||
result = pre_trim_for_multica_comment(text)
|
|
||||||
self.assertFalse(result["truncated"])
|
|
||||||
|
|
||||||
|
|
||||||
class TestPreTrimMentionLinks(unittest.TestCase):
|
|
||||||
"""mention 链接测试"""
|
|
||||||
|
|
||||||
def test_agent_mention_stripped(self):
|
|
||||||
text = "[@徐聪](mention://agent/46bdd4a6-5c64-475a-92ef-36a763602fa1) 已就绪"
|
|
||||||
result = pre_trim_for_multica_comment(text)
|
|
||||||
self.assertIn("@徐聪", result["trimmed"])
|
|
||||||
self.assertNotIn("mention://", result["trimmed"])
|
|
||||||
|
|
||||||
def test_issue_mention_preserved(self):
|
|
||||||
text = "[MUL-104](mention://issue/abc-123) 已派发"
|
|
||||||
result = pre_trim_for_multica_comment(text)
|
|
||||||
self.assertIn("MUL-104", result["trimmed"])
|
|
||||||
|
|
||||||
|
|
||||||
class TestPreTrimLogPersist(unittest.TestCase):
|
|
||||||
""".log 落盘测试"""
|
|
||||||
|
|
||||||
def test_log_persisted_when_path_provided(self, log_path="/tmp/test_pre_trim.log"):
|
|
||||||
if os.path.exists(log_path):
|
|
||||||
os.remove(log_path)
|
|
||||||
long_text = "log test " * 200
|
|
||||||
result = pre_trim_for_multica_comment(long_text, log_path=log_path)
|
|
||||||
self.assertIsNotNone(result["log_path"])
|
|
||||||
self.assertTrue(os.path.exists(log_path))
|
|
||||||
with open(log_path, "r", encoding="utf-8") as f:
|
|
||||||
content = f.read()
|
|
||||||
self.assertIn("log test", content)
|
|
||||||
# 清理
|
|
||||||
os.remove(log_path)
|
|
||||||
|
|
||||||
|
|
||||||
class TestPreTrimVersion(unittest.TestCase):
|
|
||||||
"""版本戳测试（BIZ-38 合规）"""
|
|
||||||
|
|
||||||
def test_version_stamp_present(self):
|
|
||||||
self.assertIsNotNone(__version__)
|
|
||||||
self.assertRegex(__version__, r"^\d+\.\d+\.\d+$")
|
|
||||||
|
|
||||||
|
|
||||||
if __name__ == "__main__":
|
|
||||||
unittest.main(verbosity=2)
|
|
||||||
@@ -1,181 +0,0 @@
|
|||||||
"""
|
|
||||||
test_pre_trim_multica_comment.py — pre_trim_multica_comment 单元测试
|
|
||||||
|
|
||||||
覆盖 4 类样本（COO 要求）：
|
|
||||||
1. 长 markdown
|
|
||||||
2. 嵌套表
|
|
||||||
3. 多代码块
|
|
||||||
4. 中英混排
|
|
||||||
|
|
||||||
版本：v1.0
|
|
||||||
作者：严维序（opengineer）
|
|
||||||
"""
|
|
||||||
|
|
||||||
import os
|
|
||||||
import sys
|
|
||||||
import unittest
|
|
||||||
|
|
||||||
_SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
|
|
||||||
sys.path.insert(0, _SCRIPT_DIR)
|
|
||||||
|
|
||||||
from pre_trim_multica_comment import (
|
|
||||||
pre_trim_for_multica_comment,
|
|
||||||
DEFAULT_MAX_BYTES,
|
|
||||||
__version__,
|
|
||||||
)
|
|
||||||
|
|
||||||
|
|
||||||
class TestPreTrimLongMarkdown(unittest.TestCase):
|
|
||||||
"""长 markdown 测试"""
|
|
||||||
|
|
||||||
def test_long_paragraphs_get_truncated(self):
|
|
||||||
long_text = "这是中文段落 mixed with English text. " * 100
|
|
||||||
result = pre_trim_for_multica_comment(long_text)
|
|
||||||
self.assertLessEqual(result["trimmed_bytes"], DEFAULT_MAX_BYTES)
|
|
||||||
self.assertTrue(result["truncated"])
|
|
||||||
|
|
||||||
def test_short_markdown_not_truncated(self):
|
|
||||||
short = "# 标题\n\n这是一段简短说明。\n\n## 子标题\n\n- 列表项 1\n- 列表项 2\n"
|
|
||||||
result = pre_trim_for_multica_comment(short)
|
|
||||||
self.assertFalse(result["truncated"])
|
|
||||||
self.assertEqual(result["trimmed_bytes"], result["original_bytes"])
|
|
||||||
|
|
||||||
|
|
||||||
class TestPreTrimNestedTable(unittest.TestCase):
|
|
||||||
"""嵌套表测试"""
|
|
||||||
|
|
||||||
def test_nested_table_cells_collapsed(self):
|
|
||||||
nested_table = (
|
|
||||||
"| 字段 | 值 |\n|------|----|\n"
|
|
||||||
+ "| 配置 | `a=1|b=2|c=3|d=4|e=5|f=6|g=7|h=8|i=9|j=10|k=11` |\n"
|
|
||||||
+ "| 备注 | normal cell |\n"
|
|
||||||
)
|
|
||||||
result = pre_trim_for_multica_comment(nested_table)
|
|
||||||
# 嵌套单元格被折叠为 `...`
|
|
||||||
self.assertIn("`...`", result["trimmed"])
|
|
||||||
self.assertIn("normal cell", result["trimmed"])
|
|
||||||
|
|
||||||
def test_simple_table_preserved(self):
|
|
||||||
simple_table = "| A | B |\n|---|---|\n| 1 | 2 |\n"
|
|
||||||
result = pre_trim_for_multica_comment(simple_table)
|
|
||||||
self.assertIn("| A | B |", result["trimmed"])
|
|
||||||
self.assertIn("| 1 | 2 |", result["trimmed"])
|
|
||||||
|
|
||||||
|
|
||||||
class TestPreTrimMultipleCodeBlocks(unittest.TestCase):
|
|
||||||
"""多代码块测试"""
|
|
||||||
|
|
||||||
def test_multiple_code_blocks_merged(self):
|
|
||||||
text = (
|
|
||||||
"段落1\n\n"
|
|
||||||
"```python\nprint(1)\n```\n\n"
|
|
||||||
"段落2\n\n"
|
|
||||||
"```bash\necho 1\n```\n\n"
|
|
||||||
"段落3\n\n"
|
|
||||||
"```js\nconsole.log(1)\n```\n\n"
|
|
||||||
"段落4\n\n"
|
|
||||||
"```yaml\nfoo: bar\n```\n\n"
|
|
||||||
"结尾"
|
|
||||||
)
|
|
||||||
result = pre_trim_for_multica_comment(text)
|
|
||||||
# 应保留首尾两个代码块，中间合并
|
|
||||||
self.assertIn("print(1)", result["trimmed"])
|
|
||||||
self.assertIn("foo: bar", result["trimmed"])
|
|
||||||
# 中间代码块应被省略（echo 1 和 console.log 不应出现）
|
|
||||||
# 注意：合并后保留 first + last，所以 echo/console 可能保留
|
|
||||||
self.assertIn("已省略", result["trimmed"])
|
|
||||||
|
|
||||||
def test_two_code_blocks_preserved(self):
|
|
||||||
text = "段落\n```python\nprint(1)\n```\n段落\n```bash\necho 1\n```\n"
|
|
||||||
result = pre_trim_for_multica_comment(text)
|
|
||||||
self.assertIn("print(1)", result["trimmed"])
|
|
||||||
self.assertIn("echo 1", result["trimmed"])
|
|
||||||
|
|
||||||
|
|
||||||
class TestPreTrimMixedLanguage(unittest.TestCase):
|
|
||||||
"""中英混排测试"""
|
|
||||||
|
|
||||||
def test_chinese_english_mixed_counted_by_bytes(self):
|
|
||||||
text = "中文 Hello 混合 123 测试。\n" * 20
|
|
||||||
result = pre_trim_for_multica_comment(text)
|
|
||||||
# 中文 3 字节/字符，UTF-8 字节数正确
|
|
||||||
self.assertGreater(result["original_bytes"], len(text))
|
|
||||||
self.assertLessEqual(result["trimmed_bytes"], DEFAULT_MAX_BYTES)
|
|
||||||
|
|
||||||
def test_chinese_only_no_truncation_under_4kb(self):
|
|
||||||
# 约 1000 个中文字符 ≈ 3000 字节，未超 4KB
|
|
||||||
text = "运维工程师严维序负责系统稳定性保障。" * 30
|
|
||||||
result = pre_trim_for_multica_comment(text)
|
|
||||||
self.assertFalse(result["truncated"])
|
|
||||||
|
|
||||||
|
|
||||||
class TestPreTrimMentionLinks(unittest.TestCase):
|
|
||||||
"""mention 链接测试"""
|
|
||||||
|
|
||||||
def test_agent_mention_stripped(self):
|
|
||||||
text = "[@徐聪](mention://agent/46bdd4a6-5c64-475a-92ef-36a763602fa1) 已就绪"
|
|
||||||
result = pre_trim_for_multica_comment(text)
|
|
||||||
self.assertIn("@徐聪", result["trimmed"])
|
|
||||||
self.assertNotIn("mention://", result["trimmed"])
|
|
||||||
|
|
||||||
def test_issue_mention_preserved(self):
|
|
||||||
text = "[MUL-104](mention://issue/abc-123) 已派发"
|
|
||||||
result = pre_trim_for_multica_comment(text)
|
|
||||||
self.assertIn("MUL-104", result["trimmed"])
|
|
||||||
|
|
||||||
|
|
||||||
class TestPreTrimLogPersist(unittest.TestCase):
|
|
||||||
""".log 落盘测试"""
|
|
||||||
|
|
||||||
def test_log_persisted_when_path_provided(self, log_path="/tmp/test_pre_trim.log"):
|
|
||||||
if os.path.exists(log_path):
|
|
||||||
os.remove(log_path)
|
|
||||||
long_text = "log test " * 200
|
|
||||||
result = pre_trim_for_multica_comment(long_text, log_path=log_path)
|
|
||||||
self.assertIsNotNone(result["log_path"])
|
|
||||||
self.assertTrue(os.path.exists(log_path))
|
|
||||||
with open(log_path, "r", encoding="utf-8") as f:
|
|
||||||
content = f.read()
|
|
||||||
self.assertIn("log test", content)
|
|
||||||
# 清理
|
|
||||||
os.remove(log_path)
|
|
||||||
|
|
||||||
|
|
||||||
class TestPreTrimVersion(unittest.TestCase):
|
|
||||||
"""版本戳测试（BIZ-38 合规）"""
|
|
||||||
|
|
||||||
def test_version_stamp_present(self):
|
|
||||||
self.assertIsNotNone(__version__)
|
|
||||||
self.assertRegex(__version__, r"^\d+\.\d+\.\d+$")
|
|
||||||
|
|
||||||
|
|
||||||
class TestPreTrimCJKSafeBoundary(unittest.TestCase):
|
|
||||||
"""CJK-safe 截断边界测试（BIZ-104 Phase ④）"""
|
|
||||||
|
|
||||||
def test_no_split_mid_rune(self):
|
|
||||||
"""确保截断点不在 CJK 多字节序列中间"""
|
|
||||||
# 强制截断以验证边界点
|
|
||||||
# 1 个中文字 = 3 字节
|
|
||||||
# 200 个中文字 = 600 字节
|
|
||||||
text = "中" * 200 # 600 字节
|
|
||||||
result = pre_trim_for_multica_comment(text, max_bytes=100)
|
|
||||||
# 验证输出是合法 UTF-8
|
|
||||||
out_bytes = result["trimmed"].encode("utf-8")
|
|
||||||
# 验证不能被错误丢弃的字节产生非法序列
|
|
||||||
try:
|
|
||||||
decoded = out_bytes.decode("utf-8")
|
|
||||||
self.assertIsInstance(decoded, str)
|
|
||||||
except UnicodeDecodeError:
|
|
||||||
self.fail("Output contains invalid UTF-8")
|
|
||||||
|
|
||||||
def test_cjk_density_warning_added(self):
|
|
||||||
"""高 CJK 密度时动作链含 cjk_density_warn"""
|
|
||||||
# 200 个中文字 + 少量 ASCII，CJK 占比 > 95%
|
|
||||||
text = "运维工程师严维序负责系统稳定性保障。" * 50
|
|
||||||
result = pre_trim_for_multica_comment(text)
|
|
||||||
cjk_warnings = [a for a in result["actions"] if "cjk_density" in a]
|
|
||||||
self.assertGreater(len(cjk_warnings), 0)
|
|
||||||
|
|
||||||
|
|
||||||
if __name__ == "__main__":
|
|
||||||
unittest.main(verbosity=2)
|
|
||||||
@@ -1,168 +0,0 @@
|
|||||||
# 淘宝 + 聚水潭自动化运营方案设计
|
|
||||||
|
|
||||||
## 1. 方案思路
|
|
||||||
|
|
||||||
### 1.1 整体架构
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
|
||||||
│ 淘宝千牛平台 │ ←─→ │ 自动化中间层 │ ←─→ │ 聚水潭 ERP │
|
|
||||||
│ - 商品管理 │ │ - API 适配层 │ │ - 订单管理 │
|
|
||||||
│ - 订单管理 │ │ - 数据同步引擎 │ │ - 库存管理 │
|
|
||||||
│ - 库存管理 │ │ - 任务调度器 │ │ - 采购管理 │
|
|
||||||
│ - 客服消息 │ │ - 监控告警 │ │ - 财务报表 │
|
|
||||||
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
|
||||||
↓
|
|
||||||
┌──────────────────┐
|
|
||||||
│ 数据存储层 │
|
|
||||||
│ - SQLite/MySQL │
|
|
||||||
│ - Redis 缓存 │
|
|
||||||
│ - 日志系统 │
|
|
||||||
└──────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
### 1.2 数据采集方式
|
|
||||||
|
|
||||||
| 数据源 | 推荐方式 | 理由 |
|
|
||||||
|--------|----------|------|
|
|
||||||
| 淘宝千牛 | **浏览器自动化 (opencli)** | 千牛工作台无开放 API，需模拟登录操作 |
|
|
||||||
| 聚水潭 | **API 对接优先** | 聚水潭提供开放 API，稳定可靠 |
|
|
||||||
| 备用方案 | 浏览器自动化 | API 受限时的降级方案 |
|
|
||||||
|
|
||||||
### 1.3 自动化流程设计
|
|
||||||
|
|
||||||
**核心流程**：
|
|
||||||
1. **订单同步**：淘宝订单 → 聚水潭（实时/定时）
|
|
||||||
2. **库存同步**：聚水潭库存 → 淘宝（避免超卖）
|
|
||||||
3. **商品管理**：批量上下架、价格调整
|
|
||||||
4. **数据报表**：销售分析、库存周转、利润核算
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. 实现路径
|
|
||||||
|
|
||||||
### 阶段 1：前期调研（1-2 周）
|
|
||||||
|
|
||||||
| 任务 | 负责人 | 交付物 |
|
|
||||||
|------|--------|--------|
|
|
||||||
| 淘宝 opencli adapter 开发 | costcodev | `taobao-qiniu-adapter.ts` |
|
|
||||||
| 聚水潭 API 能力评估 | architect | 《聚水潭 API 调研报告》 |
|
|
||||||
| 反爬策略分析 | costcodev | 风险评估文档 |
|
|
||||||
| 技术选型确认 | architect | 架构决策记录 ADR |
|
|
||||||
|
|
||||||
### 阶段 2：系统对接（2-3 周）
|
|
||||||
|
|
||||||
| 任务 | 负责人 | 交付物 |
|
|
||||||
|------|--------|--------|
|
|
||||||
| 淘宝千牛数据读取模块 | costcodev | 可运行脚本 |
|
|
||||||
| 聚水潭 API 封装库 | costcodev | `jushuitan-sdk` |
|
|
||||||
| 数据同步中间件 | costcodev | 核心同步引擎 |
|
|
||||||
| 数据库 schema 设计 | architect | ER 图 + 建表脚本 |
|
|
||||||
|
|
||||||
### 阶段 3：核心功能开发（3-4 周）
|
|
||||||
|
|
||||||
| 任务 | 负责人 | 交付物 |
|
|
||||||
|------|--------|--------|
|
|
||||||
| 订单自动同步 | costcodev | 订单同步模块 |
|
|
||||||
| 库存自动同步 | costcodev | 库存同步模块 |
|
|
||||||
| 商品批量管理 | costcodev | 商品管理模块 |
|
|
||||||
| 报表生成引擎 | costcodev | 数据报表模块 |
|
|
||||||
| Web 控制台 | designer + costcodev | 管理后台 UI |
|
|
||||||
|
|
||||||
### 阶段 4：测试验证（1-2 周）
|
|
||||||
|
|
||||||
| 任务 | 负责人 | 交付物 |
|
|
||||||
|------|--------|--------|
|
|
||||||
| 功能测试 | coo + taobaospecialist | 测试报告 |
|
|
||||||
| 稳定性测试 | opengineer | 压力测试报告 |
|
|
||||||
| 数据一致性校验 | coo | 校验脚本 + 报告 |
|
|
||||||
| 安全审计 | opengineer | 安全评估报告 |
|
|
||||||
|
|
||||||
### 阶段 5：部署上线（1 周）
|
|
||||||
|
|
||||||
| 任务 | 负责人 | 交付物 |
|
|
||||||
|------|--------|--------|
|
|
||||||
| 生产环境部署 | opengineer | 部署文档 |
|
|
||||||
| 监控告警配置 | opengineer | Grafana 面板 |
|
|
||||||
| 运维交接 | opengineer | 运维 SOP |
|
|
||||||
| 用户培训 | coo | 使用手册 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 团队资源需求
|
|
||||||
|
|
||||||
| 角色 | 工时估算 | 职责 |
|
|
||||||
|------|----------|------|
|
|
||||||
| **architect 梁思筑** | 20h | 架构设计、技术选型、ADR 撰写 |
|
|
||||||
| **costcodev 徐聪** | 120h | 核心开发（API 对接、同步引擎、Web 后台） |
|
|
||||||
| **designer 苏绘锦** | 16h | Web 控制台 UI 设计 |
|
|
||||||
| **opengineer 严维序** | 24h | 部署、监控、运维 SOP |
|
|
||||||
| **taobaospecialist 陆云帆** | 16h | 业务需求输入、流程验证、UAT 测试 |
|
|
||||||
| **coo 陆怀瑾** | 24h | 项目管理、风险评估、进度跟进 |
|
|
||||||
|
|
||||||
**总工时**：约 220 小时（约 5.5 人周）
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. 风险与约束
|
|
||||||
|
|
||||||
### 4.1 接口限制
|
|
||||||
|
|
||||||
| 风险 | 影响 | 应对措施 |
|
|
||||||
|------|------|----------|
|
|
||||||
| 淘宝 API 调用频率限制 | 数据同步延迟 | 请求队列 + 令牌桶限流 |
|
|
||||||
| 聚水潭 API 权限不足 | 部分功能无法实现 | 申请高级权限或改用浏览器自动化 |
|
|
||||||
|
|
||||||
### 4.2 反爬机制
|
|
||||||
|
|
||||||
| 风险 | 影响 | 应对措施 |
|
|
||||||
|------|------|----------|
|
|
||||||
| 淘宝风控检测 | 账号被封禁 | 1. 使用真实 Cookie 2. 限制操作频率 3. 添加人工操作混淆 |
|
|
||||||
| 登录态失效 | 自动化中断 | Token 自动刷新 + 失效告警 |
|
|
||||||
|
|
||||||
### 4.3 数据安全
|
|
||||||
|
|
||||||
| 风险 | 影响 | 应对措施 |
|
|
||||||
|------|------|----------|
|
|
||||||
| 账号密码泄露 | 严重安全事故 | 1. 使用密钥管理服务 2. 环境变量存储 3. 权限隔离 |
|
|
||||||
| 数据传输未加密 | 中间人攻击 | HTTPS + 数据加密传输 |
|
|
||||||
|
|
||||||
### 4.4 平台稳定性
|
|
||||||
|
|
||||||
| 风险 | 影响 | 应对措施 |
|
|
||||||
|------|------|----------|
|
|
||||||
| 聚水潭接口变更 | 功能失效 | 1. 接口版本监控 2. 快速适配机制 |
|
|
||||||
| 淘宝页面结构变更 | 选择器失效 | 1. 多选择器备用 2. 定期巡检更新 |
|
|
||||||
|
|
||||||
### 4.5 合规风险
|
|
||||||
|
|
||||||
| 风险 | 影响 | 应对措施 |
|
|
||||||
|------|------|----------|
|
|
||||||
| 违反淘宝服务条款 | 店铺处罚 | 1. 评估自动化操作合规性 2. 控制操作频率在合理范围 3. 保留人工审核环节 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. 下一步行动
|
|
||||||
|
|
||||||
1. **立即启动**：architect 开始聚水潭 API 调研
|
|
||||||
2. **并行推进**：costcodev 开发淘宝 opencli adapter
|
|
||||||
3. **周会同步**：每周五同步进展，识别阻塞点
|
|
||||||
4. **里程碑**：阶段 1 结束后进行方案复审
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ⚠️ 安全提示
|
|
||||||
|
|
||||||
**严禁在代码/配置文件中明文存储账号密码！**
|
|
||||||
|
|
||||||
正确做法：
|
|
||||||
```bash
|
|
||||||
# 使用环境变量
|
|
||||||
export TAOBAO_ACCOUNT=$(vault read -field=value secret/taobao/account)
|
|
||||||
export TAOBAO_PASSWORD=$(vault read -field=value secret/taobao/password)
|
|
||||||
```
|
|
||||||
|
|
||||||
或使用密钥管理服务（如 HashiCorp Vault、AWS Secrets Manager）。
|
|
||||||
|
|
||||||
---
|
|
||||||
提交人：陆怀瑾（COO）| 提交时间：2026-07-11 | 关联 issue：BIZ-89
|
|
||||||
@@ -1,446 +0,0 @@
|
|||||||
# 石斛固态食品与烘焙全品类扩展可行性分析报告
|
|
||||||
|
|
||||||
**编号**：BIZ-65
|
|
||||||
**报告类型**：产品扩展可行性分析
|
|
||||||
**分析日期**：2026年6月26日
|
|
||||||
**分析人**：顾析策（市场分析师）
|
|
||||||
**参考文档**：石斛食品饮料全品类产品方向详细文档、BIZ-53 品斛堂企业情报调研报告、BIZ-55 电商调研
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 摘要
|
|
||||||
|
|
||||||
**核心结论**：品斛堂以石斛为根基向固态食品扩展具备明确可行性。5个子品类中，**膏滋蜜炼和压片糖果为最高优先级**——前者依托品斛堂石斛浸膏技术壁垒和中药膏方100亿+市场，后者复用现有石斛精片基础切入全球485亿美元功能性糖果赛道。OEM/ODM模式是核心实现路径——品斛堂已有为近100家企业代工石斛精片/饼干/面条/果冻/浸膏的经验，固态食品扩展应优先走"自有品牌试水+OEM/ODM双轨并行"策略。
|
|
||||||
|
|
||||||
**关键数据**：
|
|
||||||
- 功能性压片糖果亚太区CAGR 12.6%，中国本土企业TOP5市占率39.4%
|
|
||||||
- 中药膏滋/煎膏剂100亿+市场（2024），补气补血类占50%+，院内市场同比增长17.2%
|
|
||||||
- 中国烘焙市场2595亿元（2025欧睿），人均消费25.5美元仅为日本1/6
|
|
||||||
- 果冻市场200-250亿元，功能型果冻增速最快
|
|
||||||
- **品斛堂OEM能力已覆盖石斛精片/饼干/面条/果冻/浸膏全品类**
|
|
||||||
|
|
||||||
**TOP5推荐**：①膏滋蜜炼（石斛膏方→差异化壁垒）②压片糖果/含片（高频+功能性+复用基础）③烘焙饼干/节日烘焙（高潜力+代工成熟）④休闲零食（坚果蜜饯→OEM快起量）⑤果冻布丁（功能型差异化切入）
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 一、压片糖果/咀嚼片
|
|
||||||
|
|
||||||
### 1.1 市场规模与趋势
|
|
||||||
|
|
||||||
| 指标 | 数据 | 来源 |
|
|
||||||
|------|------|------|
|
|
||||||
| 全球压片糖果市场 | $485亿（2025）→ $512亿（2026E） | ZVZO消费观察 |
|
|
||||||
| 中国市场占比 | 22.7%，约$110亿（¥780亿） | ZVZO消费观察 |
|
|
||||||
| 中国糖果市场总规模 | ¥930亿（2024） | 华经产业研究院 |
|
|
||||||
| 功能性糖果CAGR | 12.6%（亚太区） | ZVZO消费观察 |
|
|
||||||
| 药用糖果全球市场 | $63.9亿（2025）→ $91.6亿（2035E） | Global Growth Insights |
|
|
||||||
| 中国增速 | 8.3%以上，显著高于全球4.1% | ZVZO消费观察 |
|
|
||||||
| 功能性品类占比预测 | 将超过55%（2030E） | ZVZO消费观察 |
|
|
||||||
|
|
||||||
**核心趋势**：
|
|
||||||
- 63%消费者将"健康属性"列为购买第一考虑因素，免疫力提升（34%）、口腔清新（27%）、能量补充（21%）为TOP3诉求
|
|
||||||
- 无糖/低糖产品渗透率将突破70%
|
|
||||||
- 线上销售占比44.6%，直播电商+社区团购贡献线上增量57%
|
|
||||||
- 年轻化："零食化+功效化"方向，年轻群体对便携小包装接受度71%
|
|
||||||
|
|
||||||
### 1.2 竞争格局
|
|
||||||
|
|
||||||
| 梯队 | 代表品牌 | 定位 | 核心优势 |
|
|
||||||
|------|------|------|------|
|
|
||||||
| 🥇 功能型龙头 | 金嗓子、西瓜霜 | 润喉利咽 | 渠道铺货广，OTC背书 |
|
|
||||||
| 🥇 药企延伸 | 同仁堂、修正、江中 | 中药功能含片 | 品牌信任，药房渠道 |
|
|
||||||
| 🥈 保健品跨界 | 汤臣倍健、养生堂 | 维C/益生菌咀嚼片 | 品牌力+电商运营强 |
|
|
||||||
| 🥉 新锐品牌 | 各OEM代工品牌 | 差异化功能 | 直播电商切入快 |
|
|
||||||
|
|
||||||
**竞争特点**：
|
|
||||||
- 传统龙头金嗓子/西瓜霜品牌老化，市场增长缓慢（传统甜味压片2.1%增速）
|
|
||||||
- 功能性细分增速远超传统品类
|
|
||||||
- 中国TOP5企业市占率39.4%，格局相对分散，新品牌仍有空间
|
|
||||||
- OEM产能充沛：全国300+压片糖果代工厂，仙乐健康/会昌等龙头覆盖全剂型
|
|
||||||
|
|
||||||
### 1.3 品斛堂可行性评估
|
|
||||||
|
|
||||||
| 维度 | 评估 | 说明 |
|
|
||||||
|------|:---:|------|
|
|
||||||
| **产品基础** | ⭐⭐⭐⭐⭐ | 已有石斛精片产品，可直接升级为石斛含片/咀嚼片 |
|
|
||||||
| **原料优势** | ⭐⭐⭐⭐⭐ | 自有石斛全产业链，提取物/多糖/干粉三种形态可做配方核心 |
|
|
||||||
| **技术门槛** | ⭐⭐ | 压片工艺标准化，OEM代工成熟（MOQ≈3万包起订） |
|
|
||||||
| **渠道匹配** | ⭐⭐⭐⭐ | 复用天猫/京东旗舰店+药房渠道，精准触达咽喉不适/养生人群 |
|
|
||||||
| **品牌差异化** | ⭐⭐⭐⭐ | "石斛含片"定位对标金嗓子"咽炎"场景，差异化明显 |
|
|
||||||
| **毛利率预估** | ⭐⭐⭐⭐ | 60-70%（压片糖果制造成本低，石斛原料自有优势加成） |
|
|
||||||
|
|
||||||
**可行性：★★★★★ 高**
|
|
||||||
|
|
||||||
**落地路径**：
|
|
||||||
- 短期（1-3月）：将现有"石斛精片"升级为"石斛含片"（润喉利咽）+ "石斛西洋参咀嚼片"（补气提神），复用天猫元斛旗舰店渠道
|
|
||||||
- 中期（3-6月）：开发"石斛维C咀嚼片"卡位功能维C赛道（对标汤臣倍健）
|
|
||||||
- 代工策略：片剂生产线品斛堂已有基础（中药饮片GMP车间），可自主生产；如需扩产，珠三角/长三角OEM厂产能充裕
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 二、休闲零食（坚果炒货+蜜饯果干+纤维饼干）
|
|
||||||
|
|
||||||
### 2.1 市场规模与趋势
|
|
||||||
|
|
||||||
| 指标 | 数据 | 来源 |
|
|
||||||
|------|------|------|
|
|
||||||
| 中国休闲零食市场 | ¥1.3万亿（2020），近¥3万亿（2025E） | 商务部/中国食品工业协会 |
|
|
||||||
| 2024年主流电商零食销售额 | ¥3080亿，同比+11% | Flywheel白皮书 [1] |
|
|
||||||
| 坚果炒货13-18年CAGR | 11.0% | 欧睿国际 |
|
|
||||||
| 人均消费量 | 2.15kg（2015），vs英国9.53kg/美国13.03kg | 商务部 |
|
|
||||||
| 抖音零食销售额增长 | 23%，线上第一渠道（份额54%） | 知行咨询2025报告 |
|
|
||||||
| 2024肉类零食占三只松鼠销售额 | 20.14% | 知行咨询2025报告 |
|
|
||||||
|
|
||||||
**核心趋势**：
|
|
||||||
- 消费者要求"美味与营养兼得"——健康化零食复合增长率远超传统品类
|
|
||||||
- 抖音超越淘系成为线上第一零食渠道
|
|
||||||
- 渠道型品牌（三只松鼠/B2C）增长见顶，制造型品牌（洽洽/大单品）利润更优
|
|
||||||
- 功能性/健康概念零食增速领先：益生菌、高纤维、低GI
|
|
||||||
|
|
||||||
### 2.2 竞争格局
|
|
||||||
|
|
||||||
| 梯队 | 代表品牌 | 2022年营收 | 模式 | 核心品类 |
|
|
||||||
|------|------|:---:|------|------|
|
|
||||||
| 🥇 | 三只松鼠 | ¥72.9亿 | B2C电商全品类 | 坚果+肉类零食 |
|
|
||||||
| 🥇 | 良品铺子 | ¥66.2亿 | 线上线下双渠道 | 全品类+高端定位 |
|
|
||||||
| 🥈 | 百草味 | ~¥40亿 | 百事旗下B2C | 坚果+果脯蜜饯 |
|
|
||||||
| 🥈 | 洽洽食品 | ¥68.8亿 | 制造型大单品 | 瓜子+坚果 |
|
|
||||||
| 🥉 | 来伊份 | ~¥40亿 | 线下门店 | 全品类 |
|
|
||||||
|
|
||||||
**进入壁垒**：
|
|
||||||
- 三巨头线上份额CR3≈33%，渠道垄断性强
|
|
||||||
- 坚果炒货品类大厂规模效应显著，价格竞争激烈
|
|
||||||
- 蜜饯果干品类CR3低，区域品牌众多，差异化空间大
|
|
||||||
|
|
||||||
### 2.3 品斛堂可行性评估
|
|
||||||
|
|
||||||
| 维度 | 评估 | 说明 |
|
|
||||||
|------|:---:|------|
|
|
||||||
| **产品基础** | ⭐⭐⭐ | 已有石斛纤维饼（功能零食），缺少坚果/蜜饯加工能力 |
|
|
||||||
| **原料优势** | ⭐⭐⭐ | 石斛粉/提取物可作为调味添加，但坚果/果干需外采 |
|
|
||||||
| **技术门槛** | ⭐ | 坚果炒货、蜜饯果干标准化程度高，无技术壁垒 |
|
|
||||||
| **渠道匹配** | ⭐⭐⭐ | 天猫/京东零食类目流量大，但需从零建立零食消费者认知 |
|
|
||||||
| **品牌差异化** | ⭐⭐⭐ | "石斛+零食"概念有独特性，但需验证消费者接受度 |
|
|
||||||
| **毛利率预估** | ⭐⭐ | 30-40%（代工成本高+坚果原料波动，自有品牌溢价有限） |
|
|
||||||
|
|
||||||
**可行性：★★★☆☆ 中**
|
|
||||||
|
|
||||||
**差异化切入策略**：
|
|
||||||
- **不推荐**直接进入坚果炒货红海（三只松鼠/洽洽成本碾压）
|
|
||||||
- **推荐**：石斛纤维饼升级为"石斛健康零食系列"（复用已有基础）
|
|
||||||
- 石斛纤维饼→升级配方，推低GI/高纤维版本
|
|
||||||
- 石斛山楂条→开胃消食+石斛养胃（蜜饯OEM成熟）
|
|
||||||
- 石斛味坚果→轻添加概念（巴旦木/核桃+石斛粉涂层）
|
|
||||||
- 代工策略：蜜饯果干OEM遍布云南/福建（鲜花饼供应链可复用），坚果OEM广东/安徽产能充裕
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 三、谷物主食（挂面+方便面+粥料）
|
|
||||||
|
|
||||||
### 3.1 市场规模与趋势
|
|
||||||
|
|
||||||
| 指标 | 数据 | 来源 |
|
|
||||||
|------|------|------|
|
|
||||||
| 中国挂面市场规模 | 419.92万吨产量（2021），预估>500万吨（2025E） | 中金企信/欧睿 |
|
|
||||||
| 挂面市场销售额 | CAGR 10.72%（24家头部企业） | 中金企信 |
|
|
||||||
| 方便速食市场 | ¥2500亿（2021）→ ¥6300亿（2025E） | 国信证券 |
|
|
||||||
| 中国方便面市场 | 422亿包/年（2023），销量-2.3% CAGR | 勤策消费研究 |
|
|
||||||
| 方便食品市场规模 | 2026年将突破万亿 | 勤策消费研究 |
|
|
||||||
| 一人食经济 | 1.8万亿（2025，一二线55%宅家烹饪） | Flywheel白皮书 [1] |
|
|
||||||
| 外卖市场规模 | 1.27万亿（2024），用户5.92亿 | 美团/行业数据 |
|
|
||||||
|
|
||||||
**核心趋势**：
|
|
||||||
- 挂面量增价不增（产量>销量连续10年），利润转向高端化/功能化
|
|
||||||
- 方便面传统品类承压（外卖+预制菜挤压），中高端增速17.1%（2016-20）为低端4.2倍
|
|
||||||
- "一人食经济"驱动速食向品质化/健康化升级
|
|
||||||
- 非油炸/零添加/功能性面条是增长方向
|
|
||||||
- 高铁站停售方便面（广东2025）标志性事件→传统场景收窄
|
|
||||||
|
|
||||||
### 3.2 竞争格局
|
|
||||||
|
|
||||||
| 梯队 | 挂面 | 市场份额 | 方便面 | 市场份额 |
|
|
||||||
|------|------|:---:|------|:---:|
|
|
||||||
| 🥇 | 金沙河 | 22% | 康师傅 | ~45% |
|
|
||||||
| 🥈 | 克明食品 | 8% | 统一 | — |
|
|
||||||
| 🥉 | 想念食品 | 4% | 白象 | — |
|
|
||||||
| 其他 | 200+中小厂 | 66% | 今麦郎/三养等 | CR5=84% |
|
|
||||||
|
|
||||||
**关键特点**：
|
|
||||||
- 挂面CR3仅34%，极度分散，但整合趋势加速（2009年4000+家→2020年200+家）
|
|
||||||
- 方便面CR5=84%高集中度，入局极难
|
|
||||||
- 康师傅红烧牛肉味被大量仿制，品类同质化严重
|
|
||||||
|
|
||||||
### 3.3 品斛堂可行性评估
|
|
||||||
|
|
||||||
| 维度 | 评估 | 说明 |
|
|
||||||
|------|:---:|------|
|
|
||||||
| **产品基础** | ⭐ | 无面条制造经验，需完全依赖OEM |
|
|
||||||
| **原料优势** | ⭐⭐ | 石斛粉可添加至面条配方，但小麦/面粉无优势 |
|
|
||||||
| **技术门槛** | ⭐ | 挂面制造标准化，方便面需大量设备投入 |
|
|
||||||
| **渠道匹配** | ⭐⭐ | 挂面以商超/粮油店为主，与品斛堂现有健康品渠道不匹配 |
|
|
||||||
| **品牌差异化** | ⭐⭐ | "石斛养胃挂面"有概念吸引力，但消费者为功能性面条买单意愿待验证 |
|
|
||||||
| **毛利率预估** | ⭐ | 15-25%（挂面毛利低，克明毛利率15.87%，想念14.19%） |
|
|
||||||
|
|
||||||
**可行性：★★☆☆☆ 低**
|
|
||||||
|
|
||||||
**判断**：谷物主食不是品斛堂当前优先级最高的扩展方向。理由：
|
|
||||||
1. 挂面行业利润薄（克明食品2021年净利仅6700万，收入43亿），石斛添加只会进一步压缩毛利
|
|
||||||
2. 渠道完全不匹配——挂面走商超/粮油店，品斛堂现有天猫+药房+酒类渠道
|
|
||||||
3. 金沙河/克明双寡头成本碾压，新进入者无规模优势
|
|
||||||
4. 唯一有吸引力的场景是"石斛面条"作为**品牌形象产品**（非利润产品）在旗舰店上架，配合石斛粥料做养生主食组合
|
|
||||||
|
|
||||||
**如仍需进入的建议**：OEM代工石斛养生粥料（谷物+石斛预拌包）→低风险入场，石斛面条作为品牌配套产品而非主推
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 四、半固态/凝胶食品（膏滋蜜炼+果冻布丁）
|
|
||||||
|
|
||||||
### 4.1 膏滋蜜炼（膏方）
|
|
||||||
|
|
||||||
#### 市场规模与趋势
|
|
||||||
|
|
||||||
| 指标 | 数据 | 来源 |
|
|
||||||
|------|------|------|
|
|
||||||
| 中成药浸膏/煎膏剂三大终端 | ¥100亿+（2024） | 米内网 |
|
|
||||||
| 院内市场增速 | +17.20%（2025，逆势上扬） | 米内网 |
|
|
||||||
| 补气补血类占比 | >50%市场份额 | 米内网 |
|
|
||||||
| 中国阿胶市场 | ¥580亿（2025）→ 千亿（2030E, CAGR 10.4%） | 知乎/东阿阿胶年报 |
|
|
||||||
| 东阿阿胶2025年营收 | ¥67亿（+13.17%），阿胶系列61.9亿 | 东阿阿胶年报 |
|
|
||||||
| 药食同源市场 | ¥3800亿→¥7500亿（2030E, CAGR 10.8%） | 雪球/药食同源研报 [2] |
|
|
||||||
|
|
||||||
**核心趋势**：
|
|
||||||
- 膏方从传统中医药向"新中式滋补"演化，消费场景从治病转向日常养生
|
|
||||||
- 阿胶品类"零食化+便携化"趋势显著——阿胶糕/速溶粉/阿胶奶茶跨界
|
|
||||||
- 东阿阿胶线上营收占比19.79%（2025Q1），膏方电商化仍在早期
|
|
||||||
- 90后/00后买走60%阿胶产品，养生年轻化是确定性趋势
|
|
||||||
|
|
||||||
#### 竞争格局
|
|
||||||
|
|
||||||
| 梯队 | 品牌 | 膏方优势 | 2025年表现 |
|
|
||||||
|------|------|------|------|
|
|
||||||
| 🥇 | 东阿阿胶 | 阿胶膏/桃花姬 | ¥61.9亿阿胶系列 |
|
|
||||||
| 🥇 | 同仁堂 | 传统膏方/秋梨膏 | 院外膏方TOP3 |
|
|
||||||
| 🥈 | 胡庆余堂 | 江南膏方 | — |
|
|
||||||
| 🥈 | 福牌阿胶 | 阿胶膏方 | 院外膏方TOP3 |
|
|
||||||
| 🥉 | 白云山潘高寿 | 蜜炼川贝枇杷膏/养阴清肺膏 | 院内膏方第1 |
|
|
||||||
| 🔑 | **品斛堂机会** | **石斛膏方=品类空白** | 已有石斛浸膏技术 |
|
|
||||||
|
|
||||||
#### 品斛堂可行性评估
|
|
||||||
|
|
||||||
| 维度 | 评估 | 说明 |
|
|
||||||
|------|:---:|------|
|
|
||||||
| **产品基础** | ⭐⭐⭐⭐⭐ | 已有石斛浸膏OEM能力，"铁皮石斛膏/秋梨石斛膏"配方有技术储备 |
|
|
||||||
| **原料优势** | ⭐⭐⭐⭐⭐ | 石斛全产业链+石斛多糖提取物，膏方核心原料自有 |
|
|
||||||
| **技术门槛** | ⭐⭐⭐⭐ | 中药浸膏制造有GMP门槛，品斛堂中药饮片/保健食品净化车间齐全 |
|
|
||||||
| **渠道匹配** | ⭐⭐⭐⭐⭐ | 天猫健康品+药房+送礼场景→完美匹配膏方消费场景 |
|
|
||||||
| **品牌差异化** | ⭐⭐⭐⭐⭐ | "石斛膏"品类无强势品牌占据，"秋梨石斛膏"对标"秋梨膏"差异明显 |
|
|
||||||
| **毛利率预估** | ⭐⭐⭐⭐⭐ | 65-80%（膏方高毛利，东阿阿胶毛利率73.47%，石斛自有原料加成更高） |
|
|
||||||
|
|
||||||
**可行性：★★★★★ 高（最高优先级）**
|
|
||||||
|
|
||||||
**落地路径**：
|
|
||||||
- 短期（1-3月）：复用现有石斛浸膏生产线，推出"铁皮石斛膏"（¥199-399/300g）+"秋梨石斛膏"（¥59-99），天猫旗舰店首发
|
|
||||||
- 中期（3-6月）：开发"阿胶石斛膏"（女性气血）+石斛膏方礼盒（春节/中秋送礼）
|
|
||||||
- 差异化定位：品斛堂膏方=石斛为核心（vs同仁堂/东阿阿胶以阿胶/人参为核心），开辟"石斛膏方"新品类
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 4.2 果冻布丁
|
|
||||||
|
|
||||||
#### 市场规模与趋势
|
|
||||||
|
|
||||||
| 指标 | 数据 | 来源 |
|
|
||||||
|------|------|------|
|
|
||||||
| 中国果冻市场 | ¥200-250亿（2023） | 中研普华/百度百科 |
|
|
||||||
| 生产企业数量 | 2000+家（其中规模企业300+家） | 中研普华 |
|
|
||||||
| 喜之郎年销售额 | ¥15亿+ | MBA智库百科 |
|
|
||||||
| 功能型果冻趋势 | 乳酸菌/益生菌/代餐果冻增速最快 | 头豹研究院 |
|
|
||||||
| 中国新式茶饮市场 | 突破4000亿（2028E） | 行业报告 |
|
|
||||||
|
|
||||||
**核心趋势**：
|
|
||||||
- 果冻从"儿童零食"向"全年龄健康零食"转型
|
|
||||||
- 益生菌果冻、蒟蒻果冻（低热量）、代餐果冻是三大增长方向
|
|
||||||
- 女性消费者占食品网购65%，果冻天然受女性青睐
|
|
||||||
|
|
||||||
#### 品斛堂可行性评估
|
|
||||||
|
|
||||||
| 维度 | 评估 | 说明 |
|
|
||||||
|------|:---:|------|
|
|
||||||
| **产品基础** | ⭐⭐ | 品斛堂百度百科列有石斛果冻OEM能力，但无自有品牌产品 |
|
|
||||||
| **原料优势** | ⭐⭐⭐ | 石斛多糖/提取物可添加至果冻配方，功能差异化 |
|
|
||||||
| **技术门槛** | ⭐ | 果冻OEM极度成熟（全国386+食品代工厂可做果冻） |
|
|
||||||
| **渠道匹配** | ⭐⭐⭐ | 天猫零食/女性健康品类目可覆盖 |
|
|
||||||
| **品牌差异化** | ⭐⭐⭐ | "石斛仙草冻""石斛益生菌果冻"有差异化概念 |
|
|
||||||
| **毛利率预估** | ⭐⭐⭐ | 40-55%（功能性果冻有溢价，但喜之郎量价优势明显） |
|
|
||||||
|
|
||||||
**可行性：★★★☆☆ 中（可作配套品类）**
|
|
||||||
|
|
||||||
**判断**：果冻布丁适合作为"石斛健康零食矩阵"的配套品类而非主力。石斛仙草冻（对标烧仙草）和石斛益生菌果冻有差异化概念，但品类天花板200-250亿且喜之郎品牌统治力极强。建议OEM少量试水，作为健康零食线的补充。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 五、烘焙食品（面包吐司+饼干曲奇+节日烘焙）
|
|
||||||
|
|
||||||
### 5.1 市场规模与趋势
|
|
||||||
|
|
||||||
| 指标 | 数据 | 来源 |
|
|
||||||
|------|------|------|
|
|
||||||
| 中国烘焙市场（欧睿口径） | ¥2595亿（2025），CAGR 7.22% | 欧睿国际/桃李年报 |
|
|
||||||
| 中国烘焙市场（广义） | ¥6110.7亿（2024），+8.8% | 广告门2025报告 |
|
|
||||||
| 中国面包市场 | ¥1574亿（2024） | 华经产业研究院 |
|
|
||||||
| 全球烘焙市场 | $5165亿（2025） | 桃李年报 |
|
|
||||||
| 中国人均烘焙消费 | $25.5（vs日本$150+，美国$200+） | 欧睿国际 |
|
|
||||||
| 短保面包龙头份额 | 桃李35%（2023） | 短保面包白皮书 |
|
|
||||||
| 全国烘焙门店 | 33.8万家（2025年5月） | 红餐大数据 |
|
|
||||||
|
|
||||||
**核心趋势**：
|
|
||||||
- 中国烘焙人均消费仅为日本1/6，增长空间可观
|
|
||||||
- 烘焙糕点被Flywheel白皮书列为"电商四大高潜力品类"——线上负增长但社媒高热，**供需错配蕴藏机会**
|
|
||||||
- 短保面包向正餐化发展，桃李2025年营收54.48亿但下滑10.5%→行业竞争加剧
|
|
||||||
- 节日烘焙是利润中心：月饼/粽子季节爆发，高端礼盒毛利50-70%
|
|
||||||
- 功能性烘焙方向：全麦/高纤维/益生菌/低GI
|
|
||||||
|
|
||||||
### 5.2 竞争格局
|
|
||||||
|
|
||||||
| 梯队 | 品牌 | 品类 | 2025年营收/表现 |
|
|
||||||
|------|------|------|:---:|
|
|
||||||
| 🥇 | 桃李面包 | 短保面包 | ¥54.48亿（-10.5%） |
|
|
||||||
| 🥇 | 达利园 | 长保面包+糕点 | CR3≈3.9% |
|
|
||||||
| 🥈 | 盼盼/曼可顿/美焙辰 | 短保/中保面包 | — |
|
|
||||||
| 🥈 | 美心/杏花楼 | 月饼/节日烘焙 | — |
|
|
||||||
| 🥉 | 33.8万家烘焙门店 | 现制烘焙 | 49.3%品牌5-30家门店 |
|
|
||||||
|
|
||||||
**行业特点**：
|
|
||||||
- CR3仅8.9%，极度分散
|
|
||||||
- 桃李"中央工厂+批发"模式面临现制烘焙门店冲击（33.8万家）
|
|
||||||
- 外资品牌份额从28%（2023）降至20%（2025），本土品牌崛起
|
|
||||||
|
|
||||||
### 5.3 品斛堂可行性评估
|
|
||||||
|
|
||||||
| 维度 | 评估 | 说明 |
|
|
||||||
|------|:---:|------|
|
|
||||||
| **产品基础** | ⭐⭐ | 有石斛纤维饼（饼干类），无面包/烘焙经验 |
|
|
||||||
| **原料优势** | ⭐⭐ | 石斛粉可作烘焙添加，但面粉/黄油无优势 |
|
|
||||||
| **技术门槛** | ⭐ | 饼干/糕点OEM全国成熟（386+代工厂含烘焙） |
|
|
||||||
| **渠道匹配** | ⭐⭐⭐ | 饼干→天猫零食类目；月饼→送礼渠道与酒类渠道复用 |
|
|
||||||
| **品牌差异化** | ⭐⭐⭐ | "石斛养生月饼""石斛苏打饼干（养胃概念）"有差异化 |
|
|
||||||
| **毛利率预估** | ⭐⭐⭐ | 40-55%（饼干/月饼毛利较高，桃李短保面包毛利更低） |
|
|
||||||
|
|
||||||
**可行性：★★★★☆ 中高**
|
|
||||||
|
|
||||||
**推荐路径**：
|
|
||||||
- 饼干线（优先）：石斛苏打饼干（养胃概念）+石斛黄油曲奇→OEM代工，天猫零食线首发
|
|
||||||
- 节日烘焙（高潜力）：石斛月饼（中秋）+"石斛粽子"（端午）→复用酒类送礼渠道+企业福利渠道
|
|
||||||
- 面包吐司：**不推荐**——短保面包配送半径限制+桃李/曼可顿成本碾压+全国化物流投入巨大
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 六、OEM/ODM 可行性分析
|
|
||||||
|
|
||||||
### 6.1 品斛堂现有OEM能力
|
|
||||||
|
|
||||||
根据百度百科及什么值得买OEM评测，品斛堂**已具备以下品类的OEM/ODM代工能力**：
|
|
||||||
|
|
||||||
| 已覆盖品类 | 与本报告品类匹配 | 代工形式 | 备注 |
|
|
||||||
|------|:---:|------|------|
|
|
||||||
| 石斛精片 | ✅ 压片糖果 | OEM/ODM | 现有成熟产线 |
|
|
||||||
| 石斛饼干 | ✅ 休闲零食/烘焙 | OEM/ODM | 现有成熟产线 |
|
|
||||||
| 石斛面条 | ✅ 谷物主食 | OEM/ODM | 现有产线 |
|
|
||||||
| 石斛果冻 | ✅ 凝胶食品 | OEM/ODM | 现有产线 |
|
|
||||||
| 石斛浸膏 | ✅ 膏滋蜜炼 | OEM/ODM | 核心技术壁垒 |
|
|
||||||
| 石斛原浆 | — | ODM | 品类开创者 |
|
|
||||||
|
|
||||||
### 6.2 双轨并行策略
|
|
||||||
|
|
||||||
品斛堂固态食品扩展的最佳路径是**"自有品牌试水 + OEM/ODM双轨并行"**：
|
|
||||||
|
|
||||||
| 策略方向 | 实施路径 | 适用品类 |
|
|
||||||
|------|------|------|
|
|
||||||
| **自有品牌试水** | 天猫/京东旗舰店先上2-3款爆品测试市场反应 | 膏方、含片、饼干 |
|
|
||||||
| **OEM为品牌代工** | 以"石斛原料+制造"服务其他健康食品品牌 | 坚果、果冻、挂面 |
|
|
||||||
| **ODM输出方案** | 为渠道品牌提供石斛食品整体ODM方案 | 全品类 |
|
|
||||||
|
|
||||||
**"卖铲子给掘金者"策略逻辑**：
|
|
||||||
- 品斛堂全产业链石斛原料+三重生产资质（药品/保健食品/食品）→天然具备为其他品牌代工的优势
|
|
||||||
- 固态食品扩展中，不必每条线都自建品牌——挂面/坚果/果冻的自有品牌投入产出比不高
|
|
||||||
- **核心策略**：高价值品类自建品牌（膏方/含片）+低壁垒品类做OEM/ODM服务商
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 七、综合评估与TOP5推荐
|
|
||||||
|
|
||||||
### 7.1 5个子品类综合评分
|
|
||||||
|
|
||||||
| 评估维度（权重） | 压片糖果 | 休闲零食 | 谷物主食 | 膏滋蜜炼 | 烘焙食品 |
|
|
||||||
|------|:---:|:---:|:---:|:---:|:---:|
|
|
||||||
| 市场规模（15%） | 9 | 10 | 7 | 7 | 9 |
|
|
||||||
| 市场增速（10%） | 8 | 6 | 5 | 9 | 7 |
|
|
||||||
| 品斛堂产品基础（20%） | 9 | 6 | 2 | 10 | 5 |
|
|
||||||
| 原料/技术优势（15%） | 9 | 5 | 3 | 10 | 4 |
|
|
||||||
| 品牌差异化（15%） | 8 | 6 | 4 | 10 | 6 |
|
|
||||||
| 渠道匹配度（10%） | 8 | 5 | 2 | 10 | 6 |
|
|
||||||
| OEM实现难度（5%） | 10 | 9 | 8 | 6 | 8 |
|
|
||||||
| 毛利率预期（10%） | 8 | 5 | 3 | 10 | 7 |
|
|
||||||
| **加权总分** | **8.45** | **6.45** | **3.90** | **9.35** | **6.35** |
|
|
||||||
|
|
||||||
### 7.2 TOP5推荐排序
|
|
||||||
|
|
||||||
| 排名 | 品类方向 | 推荐产品 | 优先级 | 建议策略 | 预期毛利率 | 风险等级 |
|
|
||||||
|:---:|------|------|:---:|------|:---:|:---:|
|
|
||||||
| 🥇 | **膏滋蜜炼** | 铁皮石斛膏/秋梨石斛膏/阿胶石斛膏 | 🔴极高 | 自有品牌首发，复用浸膏产线 | 65-80% | 🟢 低 |
|
|
||||||
| 🥈 | **压片糖果** | 石斛含片/石斛西洋参咀嚼片/石斛维C咀嚼片 | 🔴极高 | 升级石斛精片，复用天猫旗舰店 | 60-70% | 🟢 低 |
|
|
||||||
| 🥉 | **烘焙饼干** | 石斛苏打饼干/石斛黄油曲奇/石斛月饼 | 🟡高 | OEM代工，饼干日常+月饼节日双线 | 40-55% | 🟡 中低 |
|
|
||||||
| 4 | **休闲零食** | 石斛山楂条/石斛纤维饼升级/石斛味坚果 | 🟡中 | OEM代工，轻资产试水 | 30-40% | 🟡 中 |
|
|
||||||
| 5 | **果冻布丁** | 石斛仙草冻/石斛益生菌果冻 | 🟢中 | OEM代工，作为零食线配套 | 40-55% | 🟡 中 |
|
|
||||||
|
|
||||||
### 7.3 不推荐进入的品类
|
|
||||||
|
|
||||||
| 品类 | 原因 |
|
|
||||||
|------|------|
|
|
||||||
| 挂面/方便面 | 利润极薄+渠道不匹配+金沙河/克明成本碾压 |
|
|
||||||
| 石斛面包吐司 | 短保配送半径限制+桃李/曼可顿竞争+全国物流投入巨大 |
|
|
||||||
| 大规模坚果炒货 | 三只松鼠/洽洽成本碾压+原料无优势 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 八、数据来源与假设说明
|
|
||||||
|
|
||||||
### 数据来源
|
|
||||||
|
|
||||||
| 编号 | 来源 | 覆盖数据项 |
|
|
||||||
|:---:|------|------|
|
|
||||||
| [1] | Flywheel《2025零食饮料趋势白皮书》 | 电商零食3080亿、一人食1.8万亿 |
|
|
||||||
| [2] | ZVZO消费观察《全球及中国压片糖果市场趋势深度分析报告2026》 | 压片糖果全球$485亿、功能性CAGR 12.6% |
|
|
||||||
| [3] | 华经产业研究院《2025年中国糖果行业分析》 | 中国糖果930亿 |
|
|
||||||
| [4] | Global Growth Insights 药用糖果市场报告 | 药用糖果$63.9亿 |
|
|
||||||
| [5] | 头豹研究院《大杯什锦果冻行业分析》 | 果冻市场200-250亿 |
|
|
||||||
| [6] | 米内网《中成药浸膏剂/煎膏剂数据分析》 | 膏滋100亿+、同比增长17.2% |
|
|
||||||
| [7] | 东阿阿胶2025年报 / 证券时报 | 东阿阿胶67亿、阿胶市场580亿 |
|
|
||||||
| [8] | 欧睿国际 / 桃李面包2025年报 | 中国烘焙2595亿、人均$25.5 |
|
|
||||||
| [9] | 中金企信 / 想念食品招股书 | 挂面市场500万吨、金沙河22%/克明8% |
|
|
||||||
| [10] | 国信证券 / 勤策消费研究 | 方便速食2500-6300亿 |
|
|
||||||
| [11] | 品斛堂百度百科 | OEM品类覆盖：精片/饼干/面条/果冻/浸膏 |
|
|
||||||
| [12] | 什么值得买"品斛堂OEM评测" | OEM实操经验验证 |
|
|
||||||
| [13] | 知行咨询《2025休闲零食行业年度洞察》 | 抖音零食份额54%、三只松鼠品类结构 |
|
|
||||||
| [14] | 雪球/药食同源研报 [2] | 药食同源3800→7500亿 |
|
|
||||||
| [15] | 品斛堂企业情报调研报告（BIZ-53） | 品斛堂产品线、DSR、电商数据 |
|
|
||||||
|
|
||||||
### 关键假设
|
|
||||||
|
|
||||||
1. 品斛堂现有石斛精片/纤维饼/浸膏OEM产线可快速转自有品牌生产——基于百度百科及OEM评测信息，假设成立
|
|
||||||
2. 石斛膏方/含片毛利率估计基于中药行业同类产品（东阿阿胶73.47%毛利率、片剂保健食品60-80%），剔除石斛自有原料带来的成本优势后估算
|
|
||||||
3. 饼干/坚果/果冻毛利率为行业平均水平，考虑规模劣势后下调5-10%
|
|
||||||
4. 市场规模数据时效性：核心数据来源为2024-2026年报告，时效性满足当前分析需求
|
|
||||||
5. 所有预测类数据已标注为"E"（预估），误差范围±15%
|
|
||||||
|
|
||||||
### 更新频率建议
|
|
||||||
|
|
||||||
- 核心市场数据（糖果/零食/烘焙）：年度更新
|
|
||||||
- 竞品动态（三只松鼠/桃李/东阿阿胶）：季度追踪
|
|
||||||
- 品斛堂自有品牌试水数据：月度复盘
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*报告完成：顾析策 🔍 | 市场分析师 | 2026年6月26日*
|
|
||||||
*数据截至：2026年6月*
|
|
||||||
*本报告基于公开市场数据和行业研究报告编制，品斛堂内部产能数据来源于公开信息（百度百科、什么值得买评测）*
|
|
||||||
@@ -1,420 +0,0 @@
|
|||||||
# 石斛功能保健食品、礼品礼盒、创新跨界品类扩展可行性分析报告
|
|
||||||
|
|
||||||
**报告编号**：BIZ-66
|
|
||||||
**报告类型**：高毛利/差异化品类扩展可行性分析
|
|
||||||
**分析日期**：2026年6月26日
|
|
||||||
**分析人**：顾析策（市场分析师）
|
|
||||||
**参考文档**：石斛食品饮料全品类产品方向详细文档、BIZ-53 企业情报调研报告、BIZ-64/BIZ-65 分析报告
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 一、摘要
|
|
||||||
|
|
||||||
**核心结论**：品斛堂在功能保健食品、礼品礼盒、创新跨界三大方向上存在明确的扩展机会，但需按"合规门槛→市场爆发力→品斛堂能力匹配"三维度排序——**蓝帽子保健食品是长期壁垒最高的方向，但需接受12-36个月审批周期；礼品礼盒是短期最容易变现的方向，可复用现有产品基础和渠道；创新跨界品类的ROI不确定性最高，适合小批量试水**。
|
|
||||||
|
|
||||||
**关键数据**：
|
|
||||||
- 中国保健食品市场规模2024年达2308亿元（中商），2025年预计2447亿元；功能性食品市场2025年突破3700亿元（含食品化方向）
|
|
||||||
- 2025年Q1蓝帽子获批504款（含备案），注册类新产品141款，保健食品零食化趋势加速
|
|
||||||
- 中国礼物经济市场2025年预计达14498亿元，健康礼赠搜索量年增200%，天猫健康礼盒成交增长40%+
|
|
||||||
- 全球植物基食品市场2026年预计945亿美元，中国占全球植物基奶市场34%
|
|
||||||
- 药食同源市场3800亿元（2024）→7500亿元（2030），CAGR 10.8%；石斛淘系Q1线上销售额1.25亿元，同比+42%
|
|
||||||
|
|
||||||
**TOP5推荐排序**：
|
|
||||||
|
|
||||||
| 排名 | 品类 | 优先级 | 预期毛利率 | 核心逻辑 |
|
|
||||||
|:---:|------|:---:|:---:|------|
|
|
||||||
| 🥇 | **石斛礼品礼盒**（原浆+酒+枫斗） | ⭐⭐⭐⭐⭐ | 55-70% | 现有产品复用、节日脉冲、渠道成熟、极速落地 |
|
|
||||||
| 🥈 | **石斛普通功能食品**（胶原蛋白肽饮/钙片） | ⭐⭐⭐⭐ | 50-65% | 备案制快速上市、无需蓝帽子审批、石斛成分差异化 |
|
|
||||||
| 🥉 | **石斛蓝帽子保健食品**（胃黏膜保护片/增强免疫力胶囊） | ⭐⭐⭐⭐ | 65-80% | 长期壁垒最高、毛利率最高、品斛堂已有三重生产资质+功效实验数据 |
|
|
||||||
| 4 | **石斛功能性口腔食品**（润喉糖/口香糖） | ⭐⭐⭐ | 45-55% | 高频快消、护喉需求爆发、OEM成熟 |
|
|
||||||
| 5 | **石斛植物基食品**（石斛植物奶/豆腐） | ⭐⭐ | 35-50% | 趋势正确但品斛堂能力匹配度低、需新建产能 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 二、蓝帽子保健食品（需注册·高毛利高壁垒）
|
|
||||||
|
|
||||||
### 2.1 市场规模与趋势
|
|
||||||
|
|
||||||
| 指标 | 数据 | 来源 |
|
|
||||||
|------|------|------|
|
|
||||||
| 中国保健食品市场规模（2024） | 2308亿元，同比+6.9% | 中商产业研究院 [1] |
|
|
||||||
| 2025年预测规模 | 2447亿元 | 中商 [1] |
|
|
||||||
| 养生保健食品市场（2023） | 3282亿元，同比+8.29% | 新营养 [2] |
|
|
||||||
| 药食同源市场（2024→2030） | 3800亿→7500亿，CAGR 10.8% | 雪球/行业研报 [3] |
|
|
||||||
| 2024年获批国产注册类保健食品 | 391款（其中新注册329款） | 中商 [1] |
|
|
||||||
| 2025年Q1获批保健食品 | 504款（含备案），注册类141款 | 新营养 [2] |
|
|
||||||
| 2025年Q1获批TOP功能 | 血糖、脂肪控制、润肠通便 | 新营养 [2] |
|
|
||||||
| 2024年获批国产备案凭证 | 4307款 | 中商 [1] |
|
|
||||||
| 头部品牌毛利率 | 60-75%（汤臣倍健66.7%，健合60.7%） | 头豹 [4] |
|
|
||||||
| 保健食品零食化剂型 | 软糖/爆珠等新剂型进入批文 | 新营养 [2] |
|
|
||||||
|
|
||||||
**趋势信号**：
|
|
||||||
- 2025年Q1植物性营养素占比47.82%，传统中药类（灵芝、西洋参、酸枣仁）占主导，石斛注册产品目前稀缺——**蓝海窗口**
|
|
||||||
- 药食同源目录已覆盖106种，石斛认知度加速提升
|
|
||||||
- 2025年进口保健食品注册通道重启，6款进口获批——国内竞争加剧信号
|
|
||||||
- 保健食品零食化趋势：糖果糕点类出现在批文中，打破"胶囊片剂"固有印象
|
|
||||||
- 2025年3月政策："完善特殊食品注册许可制度，对符合条件的重点品种实施优先审评审批"——新《意见》利好创新品类
|
|
||||||
|
|
||||||
### 2.2 合规路径与时间成本
|
|
||||||
|
|
||||||
| 路径 | 适用条件 | 审批周期 | 审批级别 | 适合品斛堂的产品 |
|
|
||||||
|------|----------|:---:|------|------|
|
|
||||||
| **注册制** | 目录外原料/首次进口/新功能声称 | 12-36个月 | 国家市场监管总局 | 石斛胃黏膜保护片、增强免疫力胶囊、缓解疲劳口服液 |
|
|
||||||
| **备案制** | 原料已列入保健食品原料目录 | 1-3个月 | 省级市场监管局 | 石斛营养素补充剂（若石斛进入目录后） |
|
|
||||||
| **普通功能食品** | 无功能声称、按普通食品管理 | 无需审批 | — | 石斛胶原蛋白肽饮、石斛钙片 |
|
|
||||||
|
|
||||||
**品斛堂合规优势**：
|
|
||||||
- ✅ 已具备药品+保健食品+食品三重生产资质
|
|
||||||
- ✅ 已有斑马鱼功效实验数据（胃黏膜保护、免疫力方向）
|
|
||||||
- ✅ 紫皮石斛全产业链控制（种植→加工→提取）
|
|
||||||
- ⚠️ 需补充：注册制产品完整的毒理学试验+功能学试验+人体试食试验
|
|
||||||
|
|
||||||
**时间线建议**：
|
|
||||||
- **短期（0-6个月）**：启动注册制申报资料准备（配方定型+安全性评价+功能学评价），同步上线普通功能食品
|
|
||||||
- **中期（6-18个月）**：完成注册资料提交，进入技术审评阶段
|
|
||||||
- **长期（18-36个月）**：获批蓝帽子批文，正式上市
|
|
||||||
|
|
||||||
### 2.3 品斛堂匹配度评估
|
|
||||||
|
|
||||||
| 维度 | 评分 | 说明 |
|
|
||||||
|------|:---:|------|
|
|
||||||
| 原料优势 | ⭐⭐⭐⭐⭐ | 自有千亩有机石斛基地，原料成本可控，多糖含量≥2200mg/100g |
|
|
||||||
| 生产技术 | ⭐⭐⭐⭐ | 酶解+低温浓缩+超临界CO₂萃取技术已成熟，可支撑功能因子高保留 |
|
|
||||||
| 合规资质 | ⭐⭐⭐⭐ | 已具备三重生产资质，但蓝帽子注册批文需从零申请 |
|
|
||||||
| 研发能力 | ⭐⭐⭐ | 已有斑马鱼功效数据，但需补充完整GLP毒理+临床功能学试验 |
|
|
||||||
| 品牌信任 | ⭐⭐⭐ | 石斛原浆第一品牌认知可转化，但"保健品"心智尚未建立 |
|
|
||||||
|
|
||||||
### 2.4 具体产品评估
|
|
||||||
|
|
||||||
#### A. 石斛胃黏膜保护片（蓝帽子注册制）
|
|
||||||
|
|
||||||
| 评估维度 | 内容 |
|
|
||||||
|------|------|
|
|
||||||
| 目标人群 | 胃黏膜损伤人群、慢性胃炎患者、长期服药人群 |
|
|
||||||
| 市场规模 | 胃肠健康保健食品市场超200亿，TOP10胃肠功能产品年销过亿 |
|
|
||||||
| 竞争格局 | 江中药业（健胃消食片年销20亿+）、修正药业、葵花药业主导，石斛差异化切入尚属空白 |
|
|
||||||
| 预期毛利率 | 65-80%（对标江中药业毛利率67%） |
|
|
||||||
| 品斛堂优势 | 斑马鱼实验已验证石斛多糖胃黏膜保护功效，紫皮石斛多糖含量行业领先 |
|
|
||||||
| 时间成本 | 注册制审批12-36个月，申报资料准备3-6个月 |
|
|
||||||
| 风险 | 审批不确定性；市场竞争激烈，品牌认知需长期建设 |
|
|
||||||
|
|
||||||
#### B. 石斛增强免疫力胶囊（蓝帽子注册制）
|
|
||||||
|
|
||||||
| 评估维度 | 内容 |
|
|
||||||
|------|------|
|
|
||||||
| 目标人群 | 免疫力低下人群、术后恢复、老年人群 |
|
|
||||||
| 市场规模 | 增强免疫力为保健食品申报功能TOP1，2024年获批产品中免疫类占最大份额 |
|
|
||||||
| 竞争格局 | 汤臣倍健蛋白粉、无限极增健口服液等已占据主流心智，但石斛+免疫是差异化组合 |
|
|
||||||
| 预期毛利率 | 65-80% |
|
|
||||||
| 品斛堂优势 | 石斛多糖增强免疫的文献研究充分，斑马鱼实验可支持功效声称 |
|
|
||||||
| 时间成本 | 同上，注册制12-36个月 |
|
|
||||||
| 风险 | 免疫力声称已是红海；需要差异化功效定位 |
|
|
||||||
|
|
||||||
#### C. 石斛缓解疲劳口服液（蓝帽子注册制）
|
|
||||||
|
|
||||||
| 评估维度 | 内容 |
|
|
||||||
|------|------|
|
|
||||||
| 目标人群 | 易疲劳人群、熬夜加班族、运动人群 |
|
|
||||||
| 市场规模 | 缓解体力疲劳为保健食品TOP3申报功能，市场规模超150亿 |
|
|
||||||
| 竞争格局 | 红牛（170亿+）、东鹏特饮、无限极主导；草本抗疲劳方向尚存差异化空间 |
|
|
||||||
| 预期毛利率 | 65-75% |
|
|
||||||
| 品斛堂优势 | 石斛西洋参复配属传统补气养阴经典组合，配方壁垒较高 |
|
|
||||||
| 时间成本 | 同上 |
|
|
||||||
| 风险 | 与红牛等功能饮料品类边界模糊，需明确"保健食品"而非"饮料"定位 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 三、普通功能食品（无需蓝帽子·快速上市）
|
|
||||||
|
|
||||||
### 3.1 市场规模与趋势
|
|
||||||
|
|
||||||
| 指标 | 数据 | 来源 |
|
|
||||||
|------|------|------|
|
|
||||||
| 中国功能性食品市场（2025） | 突破3700亿元，增长率12-15% | 知乎/行业研报 [5] |
|
|
||||||
| 全球功能性食品（2024→2034） | $3322亿→$6380亿，CAGR 6.9% | GMInsights [6] |
|
|
||||||
| 胶原蛋白肽市场 | 中国口服美容市场2024年超250亿元，CAGR 15%+ |
|
|
||||||
| 钙补充剂市场 | 中国钙制剂市场2024年约180亿元，50+人群渗透率持续提升 |
|
|
||||||
| 零食化养生趋势 | 72%的90后用功能性零食替代传统保健品 | 美团/小红书 [7] |
|
|
||||||
|
|
||||||
### 3.2 合规路径
|
|
||||||
|
|
||||||
普通功能食品的**核心合规策略**：
|
|
||||||
- ✅ 按普通食品标准管理，上市无需审批
|
|
||||||
- ✅ 可在包装标注"含石斛多糖""添加XX成分"（成分声称，不涉及功能声称）
|
|
||||||
- ✅ 可通过小红书/抖音等渠道做成分科普和食疗内容（KOL种草+达人推荐）
|
|
||||||
- ❌ 不得宣传任何保健功能（如"保护胃黏膜""增强免疫力"）
|
|
||||||
- ❌ 产品名称不得含保健功能暗示
|
|
||||||
|
|
||||||
### 3.3 具体产品评估
|
|
||||||
|
|
||||||
#### A. 石斛胶原蛋白肽饮
|
|
||||||
|
|
||||||
| 评估维度 | 内容 |
|
|
||||||
|------|------|
|
|
||||||
| 目标人群 | 25-45岁女性，美容养颜+日常滋养 |
|
|
||||||
| 市场规模 | 口服美容市场250亿+，胶原蛋白肽为核心品类 |
|
|
||||||
| 对标品牌 | 汤臣倍健Yep、姿美堂、Swisse |
|
|
||||||
| 预期毛利率 | 55-65% |
|
|
||||||
| 差异化 | 石斛多糖"滋阴养胃+胶原蛋白美容"双重复配，传统滋养与现代功能性结合 |
|
|
||||||
| 上市周期 | 3-6个月（配方定型+稳定性测试+备案上市） |
|
|
||||||
| 渠道匹配 | 现有电商渠道可直接复用（天猫+抖音+视频号） |
|
|
||||||
|
|
||||||
#### B. 石斛钙片/钙咀嚼片
|
|
||||||
|
|
||||||
| 评估维度 | 内容 |
|
|
||||||
|------|------|
|
|
||||||
| 目标人群 | 中老年人群、骨健康关注者 |
|
|
||||||
| 市场规模 | 钙制剂市场180亿+ |
|
|
||||||
| 对标品牌 | 钙尔奇、迪巧、汤臣倍健 |
|
|
||||||
| 预期毛利率 | 50-60% |
|
|
||||||
| 差异化 | 钙+石斛多糖"补钙+养胃"，减少传统钙片对胃的刺激感 |
|
|
||||||
| 上市周期 | 3-6个月 |
|
|
||||||
| 渠道匹配 | 药店+电商+商超 |
|
|
||||||
|
|
||||||
#### C. 石斛益生菌粉/软糖
|
|
||||||
|
|
||||||
| 评估维度 | 内容 |
|
|
||||||
|------|------|
|
|
||||||
| 目标人群 | 肠胃不适人群、年轻养生族 |
|
|
||||||
| 市场规模 | 益生菌市场2025年全球770亿美元，中国占25%，年增20%+ |
|
|
||||||
| 对标品牌 | 合生元、妈咪爱、wonderlab |
|
|
||||||
| 预期毛利率 | 50-65% |
|
|
||||||
| 差异化 | 益生菌+石斛多糖"双重养胃"，肠道+胃黏膜协同保护 |
|
|
||||||
| 趋势红利 | 保健食品零食化（软糖/爆珠剂型）——符合年轻化消费趋势 |
|
|
||||||
| 上市周期 | 3-6个月 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 四、礼品礼盒（高毛利·节日爆发）
|
|
||||||
|
|
||||||
### 4.1 市场规模与趋势
|
|
||||||
|
|
||||||
| 指标 | 数据 | 来源 |
|
|
||||||
|------|------|------|
|
|
||||||
| 中国礼物经济市场（2025E） | 14498亿元，持续增长 | 艾媒咨询 [8] |
|
|
||||||
| 2027年预测 | 16197亿元 | 艾媒 [8] |
|
|
||||||
| 健康礼赠搜索量增长 | 年增200% | 天猫健康 [9] |
|
|
||||||
| 天猫健康礼盒成交增长 | FY24同比增长40%+，3万+款礼盒 | 天猫健康 [9] |
|
|
||||||
| 诞生千万单品数 | FY24期间27款 | 天猫健康 [9] |
|
|
||||||
| 年轻人选健康类年礼比例 | 近70% | TMIC白皮书 [9] |
|
|
||||||
| 近30%消费者送过最成功的礼品 | 与健康相关 | TMIC白皮书 [9] |
|
|
||||||
| 春节/中秋销售额占比 | 全年约25% | Flywheel白皮书 |
|
|
||||||
| 礼品行业复合增长率 | 7% | 凯度/励展华博 [10] |
|
|
||||||
|
|
||||||
**关键趋势**：
|
|
||||||
- 送礼从"面子工程"转向"价值感+情绪表达"，健康礼赠成为确定性增长极
|
|
||||||
- 天猫推出"送礼"功能，淘宝App全量上线——降低送礼决策成本
|
|
||||||
- 燕之屋（燕窝礼盒）、小仙炖（燕窝礼盒）、东阿阿胶（阿胶礼盒）已在礼赠赛道验证——石斛礼盒尚未被头部品牌锁定
|
|
||||||
- 一线品牌春节礼盒案例：燕之屋携手法国设计师，小仙炖联名非遗艺术家——**包装设计本身就是传播媒介**
|
|
||||||
|
|
||||||
### 4.2 品斛堂现有礼盒基础
|
|
||||||
|
|
||||||
| 现有产品 | 价格带 | 基础评价 |
|
|
||||||
|------|:---:|------|
|
|
||||||
| 紫皮石斛原浆至臻礼盒 | ¥900+ | 已有高端礼盒经验，原浆作为送礼主形态已验证 |
|
|
||||||
| 石斛酒礼盒 | ¥300-900 | CIC认证"石斛酒中国销量第一"，酒礼盒天然适配商务送礼 |
|
|
||||||
| 铁皮石斛原浆礼盒 | ¥499-799 | 中高端送礼定位，可扩展至年节礼盒 |
|
|
||||||
|
|
||||||
### 4.3 礼盒扩展建议
|
|
||||||
|
|
||||||
#### A. 石斛原浆礼盒体系化（首推）
|
|
||||||
|
|
||||||
| 维度 | 内容 |
|
|
||||||
|------|------|
|
|
||||||
| 策略 | 建立"原浆礼盒金字塔"——入门级(¥299-399)→中端(¥499-799)→高端(¥999-2999) |
|
|
||||||
| 产品线 | 紫皮原浆入门礼盒、铁皮原浆中端礼盒、霍山米斛原浆高端礼盒、复合原浆组合礼盒 |
|
|
||||||
| 场景匹配 | 春节全家福礼盒、中秋商务礼盒、日常拜访养生礼盒、长辈祝寿礼盒 |
|
|
||||||
| 包装策略 | 联名非遗/IP设计师打造限定包装，强化"云南龙陵·道地石斛"产地叙事 |
|
|
||||||
| 预期毛利率 | 55-70%（礼盒溢价+包装附加值） |
|
|
||||||
| 竞争优势 | 石斛原浆第一品牌背书+全产业链透明溯源 |
|
|
||||||
| 渠道 | 天猫健康礼赠会场+视频号礼赠营销+企业团购福利+线下药店铺货 |
|
|
||||||
|
|
||||||
#### B. 石斛酒礼盒升级
|
|
||||||
|
|
||||||
| 维度 | 内容 |
|
|
||||||
|------|------|
|
|
||||||
| 策略 | 围绕"中国石斛露酒开创者"身份，打造商务宴请+节日送礼双场景 |
|
|
||||||
| 产品线 | 石斛西洋参灵芝酒礼盒（蓝帽子）、石斛米香白酒礼盒（云南特色）、石斛+原浆组合礼盒（酒+滋补） |
|
|
||||||
| 预期毛利率 | 55-75%（蓝帽子酒礼盒毛利最高） |
|
|
||||||
| 礼盒策略 | 云南民族文化元素包装+产地溯源二维码+限量版工艺 |
|
|
||||||
|
|
||||||
#### C. 石斛枫斗礼盒（传统高端）
|
|
||||||
|
|
||||||
| 维度 | 内容 |
|
|
||||||
|------|------|
|
|
||||||
| 策略 | 面向传统滋补送礼人群，强调"道地基源+手工精选" |
|
|
||||||
| 产品线 | 铁皮石斛枫斗礼盒(¥599-999)、紫皮石斛枫斗礼盒(¥299-599)、霍山米斛枫斗礼盒(¥1299-2999) |
|
|
||||||
| 预期毛利率 | 55-65% |
|
|
||||||
| 适合人群 | 传统养生认知强的中老年送礼场景、高端商务馈赠 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 五、创新跨界品类（差异化·爆品潜力）
|
|
||||||
|
|
||||||
### 5.1 功能性口腔食品
|
|
||||||
|
|
||||||
#### 5.1.1 市场规模与趋势
|
|
||||||
|
|
||||||
| 指标 | 数据 | 来源 |
|
|
||||||
|------|------|------|
|
|
||||||
| 中国口香糖市场 | 约120亿元，增速放缓但功能性方向增长 |
|
|
||||||
| 中国润喉糖/含片市场 | 约80亿元，后疫情时代护喉需求持续 |
|
|
||||||
| 口腔护理食品趋势 | "清新口气+口腔健康"双功能融合，益生菌口香糖/含片兴起 |
|
|
||||||
| 对标产品 | 金嗓子喉宝（年销20亿+）、王老吉润喉糖、绿箭/益达 |
|
|
||||||
|
|
||||||
#### 5.1.2 具体产品评估
|
|
||||||
|
|
||||||
| 产品 | 目标人群 | 价格带 | 预期毛利率 | 品斛堂匹配度 | 结论 |
|
|
||||||
|------|----------|:---:|:---:|:---:|------|
|
|
||||||
| 石斛润喉糖 | 用嗓过度、咽喉不适人群 | ¥12.9-22.9/盒 | 45-55% | ⭐⭐⭐⭐ | **首推**——石斛清咽利喉传统认知强，制造工艺成熟，OEM快启动 |
|
|
||||||
| 石斛口香糖 | 口腔异味人群 | ¥9.9-19.9/盒 | 40-50% | ⭐⭐⭐ | 可试水——"保护口腔黏膜"的差异化卖点，但需教育市场 |
|
|
||||||
|
|
||||||
**可行性分析**：
|
|
||||||
- 石斛传统用途中"清咽利喉"心智成熟，《本草纲目》记载"强阴益精，厚肠胃"，咽喉保护是其衍生功效认知
|
|
||||||
- 润喉糖属高频快消品，复购率高，与品斛堂现有电商渠道天然匹配
|
|
||||||
- 金嗓子、王老吉等品牌占据主流，但"石斛润喉"细分赛道空白
|
|
||||||
- 可通过OEM代工快速试水，无需自建生产线
|
|
||||||
|
|
||||||
**推荐路径**：委托成熟润喉糖OEM工厂代工→自有品牌+电商测试→验证ROI后决定是否自建产能
|
|
||||||
|
|
||||||
### 5.2 植物基食品
|
|
||||||
|
|
||||||
#### 5.2.1 市场规模与趋势
|
|
||||||
|
|
||||||
| 指标 | 数据 | 来源 |
|
|
||||||
|------|------|------|
|
|
||||||
| 全球植物基食品市场（2026E） | 945亿美元，CAGR 12.24% | Straits Research [11] |
|
|
||||||
| 全球植物基市场（2023→2033） | 113亿→355亿美元，CAGR 12.2% | DSM [12] |
|
|
||||||
| 中国占全球植物基奶市场 | 34%（最大单一市场） | 艾媒 |
|
|
||||||
| 植物基奶产品占植物基 | 54.65% | Straits [11] |
|
|
||||||
| 中国现存植物基企业 | 8399家（截至2023.4），2017-2022新增1982家 | 力矩中国 |
|
|
||||||
| Inova 2025趋势 | 55%消费者认为植物基应作为独立品类 |
|
|
||||||
|
|
||||||
#### 5.2.2 具体产品评估
|
|
||||||
|
|
||||||
| 产品 | 目标人群 | 价格带 | 预期毛利率 | 品斛堂匹配度 | 结论 |
|
|
||||||
|------|----------|:---:|:---:|:---:|------|
|
|
||||||
| 石斛植物奶 | 乳糖不耐受人群、健康饮品消费者 | ¥8-12/L | 35-45% | ⭐⭐ | **谨慎**——需要新建植物基产线，与现有核心能力差距大 |
|
|
||||||
| 石斛豆腐 | 素食主义者、健康饮食人群 | ¥5.9-9.9/500g | 30-40% | ⭐ | **暂不推荐**——冷链依赖、区域性强、毛利率低 |
|
|
||||||
|
|
||||||
**可行性分析**：
|
|
||||||
- 植物基大方向正确，但品斛堂能力圈（原浆酶解+酿酒+提取）与植物基（植物蛋白结构重组、发酵工艺）匹配度不足
|
|
||||||
- Oatly、维他奶等已占据植物奶主流心智，石斛切入需差异化定位（"石斛多糖+植物蛋白"组合）
|
|
||||||
- 植物奶毛利率35-45%，与品斛堂现有原浆业务（60-70%）相比显著偏低
|
|
||||||
- 2025年植物基赛道竞争者已超8000家，赛道拥挤度急剧上升
|
|
||||||
|
|
||||||
**推荐路径**：
|
|
||||||
- 植物奶：与现有植物基品牌（如Oatly）联名试水，而非自建产线
|
|
||||||
- 石斛豆腐：属于区域型冷链产品，不适合品斛堂现有电商全国的渠道模型，**暂不推荐**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 六、四维度横向对比与TOP5推荐
|
|
||||||
|
|
||||||
### 6.1 四维度综合评分
|
|
||||||
|
|
||||||
| 维度 | 蓝帽子保健食品 | 普通功能食品 | 礼品礼盒 | 创新跨界 |
|
|
||||||
|------|:---:|:---:|:---:|:---:|
|
|
||||||
| 市场规模 | ⭐⭐⭐⭐ 2308亿 | ⭐⭐⭐⭐⭐ 3700亿 | ⭐⭐⭐⭐⭐ 1.45万亿 | ⭐⭐⭐⭐ 945亿美元 |
|
|
||||||
| 增速 | ⭐⭐⭐ 6.9% | ⭐⭐⭐⭐ 12-15% | ⭐⭐⭐ 7% | ⭐⭐⭐⭐ 12.24% |
|
|
||||||
| 合规门槛 | ⭐⭐⭐ 12-36个月 | ⭐⭐⭐⭐⭐ 无需审批 | ⭐⭐⭐⭐ 食品标准即可 | ⭐⭐⭐⭐⭐ 无需审批 |
|
|
||||||
| 品斛堂匹配度 | ⭐⭐⭐⭐ 原料+资质 | ⭐⭐⭐⭐ 配方+渠道 | ⭐⭐⭐⭐⭐ 现有产品复用 | ⭐⭐ 需新建产能 |
|
|
||||||
| 预期毛利率 | ⭐⭐⭐⭐⭐ 65-80% | ⭐⭐⭐⭐ 50-65% | ⭐⭐⭐⭐⭐ 55-70% | ⭐⭐ 35-50% |
|
|
||||||
| 竞争壁垒 | ⭐⭐⭐⭐⭐ 审批+品牌 | ⭐⭐⭐ 成分差异化 | ⭐⭐⭐⭐⭐ 产地+品牌 | ⭐ 低壁垒 |
|
|
||||||
| 落地速度 | ⭐ 慢 | ⭐⭐⭐⭐⭐ 快 | ⭐⭐⭐⭐⭐ 极快 | ⭐⭐⭐ 快 |
|
|
||||||
|
|
||||||
### 6.2 TOP5推荐详细说明
|
|
||||||
|
|
||||||
#### 🥇 TOP1：石斛礼品礼盒体系化
|
|
||||||
|
|
||||||
- **推荐理由**：品斛堂已具备礼盒产品基础（原浆礼盒¥900+、酒礼盒¥300-900），无需新增产线或审批。健康礼赠市场正处爆发早期，天猫健康礼盒成交年增40%+，石斛礼盒赛道尚未被头部品牌锁定。
|
|
||||||
- **落地路径**：
|
|
||||||
- 立即启动：包装设计升级（联名非遗IP/设计师），建立"入门→中端→高端"礼盒金字塔
|
|
||||||
- 3个月内：首批节日限定礼盒上线（中秋礼盒先行）
|
|
||||||
- 渠道：天猫健康礼赠会场+视频号礼赠营销+企业团购+线下药店
|
|
||||||
- **关键成功因素**：包装设计=传播媒介；产地叙事=信任壁垒；多价格带覆盖=市场扩容
|
|
||||||
- **预期年增量营收**：3000-5000万（首年，复用现有产品）
|
|
||||||
|
|
||||||
#### 🥈 TOP2：石斛普通功能食品（胶原蛋白肽饮/益生菌软糖）
|
|
||||||
|
|
||||||
- **推荐理由**：无需蓝帽子审批，3-6个月可上市，毛利率50-65%，石斛成分差异化明确。口服美容+益生菌双赛道年增15%+，"零食化养生"趋势强劲。
|
|
||||||
- **落地路径**：
|
|
||||||
- 胶原蛋白肽饮：委托OEM代工→自有品牌+电商首测→3个月内上市
|
|
||||||
- 益生菌石斛软糖：抓住保健食品零食化趋势，软糖剂型吸引年轻消费者
|
|
||||||
- 渠道：天猫+抖音+小红书内容种草
|
|
||||||
- **关键成功因素**：成分差异化（石斛多糖复配）、剂型零食化、内容营销驱动
|
|
||||||
- **预期年增量营收**：2000-4000万
|
|
||||||
|
|
||||||
#### 🥉 TOP3：石斛蓝帽子保健食品（胃黏膜保护/增强免疫力）
|
|
||||||
|
|
||||||
- **推荐理由**：长期壁垒最高（审批+品牌）、毛利率最高（65-80%）、品斛堂已具备三重生产资质+斑马鱼功效数据。2025年政策利好"重点品种优先审评审批"，蓝帽子批文可形成10年+的独占期壁垒。
|
|
||||||
- **落地路径**：
|
|
||||||
- 立即启动：注册制申报资料准备（配方定型+GLP毒理+功能学评价），预算300-500万
|
|
||||||
- 同步推进：斑马鱼功效数据整理为SCI论文，增强学术背书
|
|
||||||
- 12-36个月：获批后正式上市
|
|
||||||
- **关键成功因素**：审批成功=独占壁垒；学术论文=品牌信任；全产业链=成本优势
|
|
||||||
- **风险提示**：审批周期长且存在不确定性，注册成本300-500万
|
|
||||||
- **预期年增量营收**：获批后首年3000-5000万，长期有望过亿
|
|
||||||
|
|
||||||
#### ④ TOP4：石斛功能性润喉糖
|
|
||||||
|
|
||||||
- **推荐理由**：石斛"清咽利喉"传统心智成熟，润喉糖市场80亿+，OEM代工可快速启动。高频快消品属性带来复购率，与电商渠道天然匹配。
|
|
||||||
- **落地路径**：
|
|
||||||
- 委托成熟润喉糖OEM工厂代工→自有品牌→电商+便利店测试
|
|
||||||
- 3个月内首批上市
|
|
||||||
- **关键成功因素**：包装年轻化、渠道铺货、口味优化
|
|
||||||
- **预期年增量营收**：500-1500万
|
|
||||||
- **风险**：金嗓子/王老吉主导市场，品牌突围需要差异化营销投入
|
|
||||||
|
|
||||||
#### ⑤ TOP5：石斛植物基食品（联名试水）
|
|
||||||
|
|
||||||
- **推荐理由**：全球植物基CAGR 12.24%，中国是最大植物基奶市场。石斛多糖+植物蛋白组合有差异化空间。
|
|
||||||
- **落地路径**：与Oatly/维他奶等品牌联名→石斛植物奶→电商测试→根据市场反馈决定是否深入
|
|
||||||
- **关键成功因素**：联名降低试错成本、植物基趋势红利
|
|
||||||
- **预期年增量营收**：试水阶段500-1000万
|
|
||||||
- **风险**：品斛堂植物基能力不足，自建产线ROI存疑，建议仅限联名试水
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 七、综合落地路线图
|
|
||||||
|
|
||||||
| 时间线 | 行动 | 所需资源 | 预期成果 |
|
|
||||||
|------|------|------|------|
|
|
||||||
| **0-3个月** | ①礼盒包装升级+中秋礼盒上线 ②胶原蛋白肽饮OEM启动 ③润喉糖OEM启动 ④注册制申报准备启动 | 设计费50万+OEM试产费80万 | 3款新产品上市 |
|
|
||||||
| **3-6个月** | ①春节礼盒预售 ②胶原蛋白肽饮正式上市 ③润喉糖上市 ④益生菌软糖启动 | OEM产能扩产100万 | 6款产品在售 |
|
|
||||||
| **6-18个月** | ①礼盒体系化（全节日覆盖） ②蓝帽子注册资料提交 ③功能食品线扩展 | 注册费300-500万 | 形成完整产品矩阵 |
|
|
||||||
| **18-36个月** | ①蓝帽子获批→正式上市 ②植物基联名试水 | 批文持有+营销投入 | 高壁垒护城河建成 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 八、数据来源与假设说明
|
|
||||||
|
|
||||||
**数据来源**：
|
|
||||||
1. [1] 中商产业研究院《2025-2030年中国保健食品深度分析及发展前景研究预测报告》
|
|
||||||
2. [2] 新营养《2025年Q1保健食品行业全景解析》（2025.4.10）
|
|
||||||
3. [3] 雪球/药食同源行业研报：2024年3800亿→2030年7500亿
|
|
||||||
4. [4] 头豹《2025年营养健康行业词条报告》（2025.7.30）
|
|
||||||
5. [5] 知乎专栏《2025年中国功能性食品行业年末深入盘点》
|
|
||||||
6. [6] GMInsights《功能性食品市场规模及份额 2025-2034》
|
|
||||||
7. [7] 美团/小红书用户行为数据
|
|
||||||
8. [8] 艾媒咨询《中国礼物经济产业市场规模》
|
|
||||||
9. [9] 天猫健康·TMIC《健康礼赠行业趋势白皮书》（2024）
|
|
||||||
10. [10] 励展华博×凯度《2025年中国礼品行业展望白皮书》
|
|
||||||
11. [11] Straits Research《植物基食品和饮料市场规模 2026-2034》
|
|
||||||
12. [12] DSM全球植物基市场报告（2024）
|
|
||||||
|
|
||||||
**关键假设**：
|
|
||||||
- 保健食品市场增长率假设为6-8%，基于近3年平均增速
|
|
||||||
- 礼盒毛利率假设基于品斛堂现有礼盒产品定价与行业均值
|
|
||||||
- 蓝帽子审批周期假设基于2025年Q1实际审批节奏（Q1新注册116款）和国家市监局公开数据
|
|
||||||
- 品斛堂年营收假设3-5亿元（基于BIZ-53情报调研）
|
|
||||||
- 增量营收预测基于可触及市场（SAM）而非总可寻址市场（TAM）
|
|
||||||
|
|
||||||
**置信区间**：
|
|
||||||
- 市场规模数据：±5-10%（多源交叉验证）
|
|
||||||
- 毛利率预测：±5%（行业对标+品斛堂现有产品毛利率反推）
|
|
||||||
- 增量营收预测：±30%（首年试水阶段不确定性高）
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*报告完成于2026年6月26日 | 顾析策 | 分析事业部 | 市场分析师*
|
|
||||||
@@ -1,318 +0,0 @@
|
|||||||
# 石斛预制菜与调味品赛道切入可行性分析
|
|
||||||
|
|
||||||
**分析日期**：2026年6月26日
|
|
||||||
**分析师**：顾析策（市场分析）
|
|
||||||
**关联议题**：BIZ-67（父议题：BIZ-53 品斛堂企业情报调研）
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 一、摘要
|
|
||||||
|
|
||||||
**核心结论**：品斛堂当前阶段**不建议直接进入预制菜/调味品赛道**，建议采取"**观望+轻资产试水**"策略——优先以OEM模式试水石斛养生汤料包/石斛火锅底料，待市场验证后再决定是否加大投入。
|
|
||||||
|
|
||||||
**关键数据**：
|
|
||||||
- 中国调味品市场规模 6871 亿（2024），酱油品类 1041 亿；海天酱油市占率 13.2%
|
|
||||||
- 中国预制菜市场规模 4850-6000 亿（2024），预计 2026 年达 7490-10720 亿
|
|
||||||
- 预制菜行业毛利率仅 10-15%，CR10 仅 14%，7.2 万家企业高度碎片化
|
|
||||||
- 药膳预制菜抖音电商 2023 年 1-9 月同比增长 605%，细分赛道高速增长
|
|
||||||
|
|
||||||
**建议**：观望着手养生汤料包 OEM 试水，6-12 个月后根据销售数据决定下一步。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 二、调味品赛道分析
|
|
||||||
|
|
||||||
### 2.1 市场规模与增长
|
|
||||||
|
|
||||||
| 指标 | 数据 | 来源 |
|
|
||||||
|------|------|------|
|
|
||||||
| 2024 年调味品市场总规模 | 6871 亿元，YoY +16.0% | 艾媒咨询 2025H1 |
|
|
||||||
| 2027 年调味品市场预测 | 10028 亿元 | 艾媒咨询 |
|
|
||||||
| 2016-2023 CAGR | 10.12% | 华经产业研究院 |
|
|
||||||
| 2024 年复合调味品市场 | 2301 亿元 | 艾媒咨询 |
|
|
||||||
| 2024 年酱油市场（国内） | 1041 亿元 | 弗诺斯特沙利文 |
|
|
||||||
| 2024 年菜谱式调味品 | 522 亿元，2027 年预计 1033 亿 | 艾媒咨询 |
|
|
||||||
| 酱油 CAGR（2019-2024） | 2.6%，预测 2024-2029 为 4.8% | 弗诺斯特沙利文 |
|
|
||||||
|
|
||||||
**判断**：调味品市场稳健增长但已进入**存量竞争**阶段，基础调味品增速放缓，复合调味品是增量来源。
|
|
||||||
|
|
||||||
### 2.2 竞争格局
|
|
||||||
|
|
||||||
| 排名 | 企业 | 整体市占率（2024） | 核心品类 | 2024 年营收 |
|
|
||||||
|:---:|------|:---:|------|------|
|
|
||||||
| 1 | 海天味业 | 4.8% | 酱油（13.2%）/蚝油（40.2%）/酱类 | ~269 亿 |
|
|
||||||
| 2 | 阜丰集团 | 1.4% | 味精/氨基酸 | — |
|
|
||||||
| 3 | 李锦记 | ~1.4% | 酱油/蚝油/酱类 | 非上市 |
|
|
||||||
| — | 中炬高新（美味鲜） | — | 酱油第二 | ~30 亿 |
|
|
||||||
| — | 千禾味业 | — | 高端酱油 | ~20 亿 |
|
|
||||||
| — | 天味食品 | — | 火锅底料/中式复调 | 31.5 亿（2023） |
|
|
||||||
|
|
||||||
**关键发现**：
|
|
||||||
- **寡头格局已形成**：海天+李锦记+中炬高新占据酱油市场头部，海天渠道下沉至乡镇
|
|
||||||
- **酱油价格战白热化**：9.9 元/L 特级酱油已成常态，新品牌突围极难
|
|
||||||
- **"零添加"标签被禁**：2025 年 3 月新国标（GB 7718-2025）规定 2027 年起禁标"零添加""不添加"，对差异化新品牌构成政策风险
|
|
||||||
|
|
||||||
### 2.3 石斛调味品可行性评估
|
|
||||||
|
|
||||||
#### 石斛酱油
|
|
||||||
- **对标现状**：海天酱油 2025 年营收 149 亿，市占率 13.2%，规模效应碾压级
|
|
||||||
- **差异化空间**：极小。酱油消费者核心决策因素为"品牌+价格+口味"，"养生"属性在酱油品类中尚未成为主流需求
|
|
||||||
- **品斛堂劣势**：无酿造产能、无渠道、无品牌认知、远离大豆主产区（云南非大豆产区）
|
|
||||||
- **成本劣势**：石斛添加推高成本，终端定价可能在 19.9-29.9 元/500ml，而主流酱油 9.9 元/L，价格差 2-3 倍
|
|
||||||
|
|
||||||
#### 石斛火锅底料
|
|
||||||
- **对标现状**：海底捞（颐海国际）、天味食品（好人家）、德庄、红九九
|
|
||||||
- **差异化空间**：中等。"不上火"概念在火锅场景有消费者感知，石斛+云南菌菇/酸汤可打造"云南养生火锅"概念
|
|
||||||
- **机会点**：复合调味品增速 13%+，CR 低，OEM 进入门槛低于酱油
|
|
||||||
- **品斛堂劣势**：无火锅底料研发经验，口味研发需外部合作
|
|
||||||
|
|
||||||
### 2.4 调味品切入评分：★★☆☆☆（2/5）
|
|
||||||
|
|
||||||
| 维度 | 评分 | 说明 |
|
|
||||||
|------|:---:|------|
|
|
||||||
| 市场规模 | 4/5 | 6871 亿大市场，复合调味品增长快 |
|
|
||||||
| 竞争强度 | 1/5 | 寡头格局，酱油价格战，新品牌生存空间极小 |
|
|
||||||
| 品斛堂匹配度 | 2/5 | 有原料优势但无生产/渠道/品牌能力 |
|
|
||||||
| 差异化空间 | 2/5 | 火锅底料有"养生"概念空间，酱油基本没有 |
|
|
||||||
| 进入门槛 | 2/5 | 酱油需酿造产能（重资产），火锅底料可 OEM（轻资产） |
|
|
||||||
| 盈利预期 | 2/5 | 头部企业净利率 15-20%，新品可能需要 2-3 年培育 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 三、预制菜赛道分析
|
|
||||||
|
|
||||||
### 3.1 市场规模与增长
|
|
||||||
|
|
||||||
| 指标 | 数据 | 来源 |
|
|
||||||
|------|------|------|
|
|
||||||
| 2022 年市场规模 | 4196 亿元，YoY +21.3% | 艾媒咨询 |
|
|
||||||
| 2023 年市场规模 | 5165 亿元 | 艾媒/人民网研究院 |
|
|
||||||
| 2024 年市场规模 | 4850-6000+ 亿元 | 艾媒蓝皮书（4850）/新华网（6000+） |
|
|
||||||
| 2026 年预测 | 7490-10720 亿元 | 艾媒蓝皮书/早期预测 |
|
|
||||||
| 全球预制食品市场（2025） | 3981 亿美元→2030 年 5316 亿美元，CAGR 6% | Statista |
|
|
||||||
| B:C 端比例 | 约 7:3（B 端仍为主力） | 嘉世咨询 |
|
|
||||||
| 渗透率 | 10-15%（美/日 60%+） | 艾媒/中国连锁餐饮报告 |
|
|
||||||
| 企业数量 | 7.2 万+ 家 | 天眼查/企查查 |
|
|
||||||
| 连锁化率驱动 | 2023 年餐饮连锁化率约 21%（美 54%/日 48%） | 中国连锁餐饮报告 |
|
|
||||||
|
|
||||||
**判断**：预制菜是确定性强的万亿赛道，但当前已从"野蛮生长"进入"规范整合"阶段。
|
|
||||||
|
|
||||||
### 3.2 竞争格局
|
|
||||||
|
|
||||||
#### 四类玩家错位竞争
|
|
||||||
|
|
||||||
| 类型 | 代表企业 | 优势 | 劣势 | 毛利率 |
|
|
||||||
|------|------|------|------|:---:|
|
|
||||||
| **上游农牧水产** | 国联水产、龙大美食、新希望 | 原料成本优势、规模化 | C 端品牌力弱 | 10-15% |
|
|
||||||
| **传统速冻食品** | 安井食品、三全、千味央厨 | 规模化生产、渠道分销强 | B 端定制弱 | 25-30% |
|
|
||||||
| **专业预制菜** | 味知香、蒸烩煮、聪厨 | 经验丰富、研发能力强 | 规模小、区域性强 | 25-30% |
|
|
||||||
| **餐饮/零售** | 西贝、盒马、广州酒家、海底捞 | C 端品牌强、终端直连 | 渠道单一、自建中央厨房成本高 | 10-15% |
|
|
||||||
|
|
||||||
**关键发现**：
|
|
||||||
- **行业高度分散**：CR10 仅 14%，无全国性龙头
|
|
||||||
- **毛利率普遍偏低**：安井预制菜毛利率从 29.7%（2018）降至 11.4%（2022）
|
|
||||||
- **同质化严重**：酸菜鱼、佛跳墙、小龙虾是最大单品，企业扎堆
|
|
||||||
- **70% 企业为作坊式**：产品标准缺失，食品安全风险大
|
|
||||||
|
|
||||||
### 3.3 石斛预制菜可行性评估
|
|
||||||
|
|
||||||
#### 石斛炖鸡/排骨汤预制菜
|
|
||||||
- **对标**：盒马（鲜食预制菜）、西贝（贾国龙功夫菜）、海底捞（预制菜线）
|
|
||||||
- **差异化定位**："养生药膳预制菜"——区别于市面主流的麻辣/酸辣类
|
|
||||||
- **理论优势**：石斛的"养生"心智 + 鸡汤的国民认知度 + 药膳文化底蕴
|
|
||||||
- **实际挑战**：
|
|
||||||
- 养生预制菜目前仍是极小众品类，主流消费者预制菜核心诉求是"便捷+好吃"而非"养生"
|
|
||||||
- 药膳预制菜需要兼顾"功效"与"口味"，研发难度远超普通预制菜
|
|
||||||
- "药膳"的保健功能宣传在合规层面存在极大风险（普通食品不得宣称保健功能）
|
|
||||||
|
|
||||||
#### 药膳预制菜市场信号（正面）
|
|
||||||
- 抖音电商 2023 年 1-9 月药膳类预制菜销售额同比增长 605%
|
|
||||||
- 温氏食品+昆中药推出参苓鸡系列
|
|
||||||
- 磐安"盘安药膳"推出黄精肉、玉竹老鸭等产品
|
|
||||||
- 广州酒家推出人参老鸭汤、人参益智仁乌鸡汤
|
|
||||||
- **但注意**：这些均为大企业试水或区域特色产品，尚未出现药膳预制菜爆品
|
|
||||||
|
|
||||||
### 3.4 预制菜切入评分：★★☆☆☆（2/5）
|
|
||||||
|
|
||||||
| 维度 | 评分 | 说明 |
|
|
||||||
|------|:---:|------|
|
|
||||||
| 市场规模 | 5/5 | 万亿级赛道，增速 20%+ |
|
|
||||||
| 竞争强度 | 2/5 | 高度碎片化、同质化，价格战正在蔓延 |
|
|
||||||
| 品斛堂匹配度 | 1/5 | 无生产经验、无冷链、无渠道、远离消费市场 |
|
|
||||||
| 差异化空间 | 3/5 | "养生药膳预制菜"有独特定位，但品类尚未验证 |
|
|
||||||
| 进入门槛 | 2/5 | 冷链物流+口味研发+渠道建设均需重投入 |
|
|
||||||
| 盈利预期 | 1/5 | 头部企业毛利率仅 10-15%，新品培育期可能长期亏损 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 四、品斛堂匹配度总体评估
|
|
||||||
|
|
||||||
### 4.1 优劣势对比
|
|
||||||
|
|
||||||
| 优势 | 劣势 |
|
|
||||||
|------|------|
|
|
||||||
| ✅ 石斛原料自供，全产业链成本可控 | ❌ **无预制菜/调味品生产经验** |
|
|
||||||
| ✅ 食品生产资质齐全（药品+保健食品+食品） | ❌ **无冷链仓储和配送网络** |
|
|
||||||
| ✅ OEM/ODM 服务经验（服务近 100 家企业） | ❌ **地处云南龙陵，远离核心消费市场** |
|
|
||||||
| ✅ "养生"品牌心智（石斛原浆第一品牌） | ❌ **销售渠道以线上为主，线下商超/便利店覆盖弱** |
|
|
||||||
| ✅ 云南地方特色食材资源（菌菇/酸汤等） | ❌ **预制菜和调味品研发团队缺失** |
|
|
||||||
| ✅ 石斛多糖等原料可赋能产品差异化 | ❌ **调味品口味研发能力为零（酱油/火锅底料均需专业研发）** |
|
|
||||||
|
|
||||||
### 4.2 风险矩阵
|
|
||||||
|
|
||||||
| 风险类型 | 具体描述 | 严重程度 | 发生概率 |
|
|
||||||
|------|------|:---:|:---:|
|
|
||||||
| **市场风险** | 预制菜/调味品竞争白热化，新品牌存活率低 | 🔴 高 | 🔴 高 |
|
|
||||||
| **运营风险** | 缺乏冷链物流和生产经验，产品质量难以保证 | 🔴 高 | 🔴 高 |
|
|
||||||
| **财务风险** | 毛利率极低（10-15%），初期投入大、回收慢 | 🟡 中 | 🔴 高 |
|
|
||||||
| **合规风险** | "养生药膳"概念在食品宣传中触碰《广告法》红线 | 🔴 高 | 🟡 中 |
|
|
||||||
| **品牌风险** | 预制菜若出食品安全问题，反噬石斛原浆主品牌 | 🔴 高 | 🟡 中 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 五、三种切入路径对比
|
|
||||||
|
|
||||||
### 路径 A：轻资产 OEM 试水（推荐指数：★★★★☆）
|
|
||||||
|
|
||||||
| 维度 | 详情 |
|
|
||||||
|------|------|
|
|
||||||
| **方式** | 与成熟预制菜/调味品代工厂合作，品斛堂提供石斛原料+品牌+渠道 |
|
|
||||||
| **首推产品** | ① 石斛菌菇养生汤料包（常温/冷冻） ② 石斛云南酸汤火锅底料 |
|
|
||||||
| **启动资金** | 300-500 万元（含研发费+首批生产+包装设计+渠道推广） |
|
|
||||||
| **时间线** | 3-6 个月产品上市，12 个月验证期 |
|
|
||||||
| **主要风险** | 品控依赖代工厂；利润被代工费挤压；产品差异化不够 |
|
|
||||||
| **退出成本** | 低——可随时停止而不影响主营业务 |
|
|
||||||
|
|
||||||
### 路径 B：战略合作/合资（推荐指数：★★★☆☆）
|
|
||||||
|
|
||||||
| 维度 | 详情 |
|
|
||||||
|------|------|
|
|
||||||
| **方式** | 与云南本地餐饮集团或预制菜企业成立合资公司，共同开发云南药膳预制菜 |
|
|
||||||
| **首推产品** | 石斛汽锅鸡预制菜、石斛菌汤包、云南过桥米线石斛汤底 |
|
|
||||||
| **启动资金** | 1000-2000 万元（含合资公司注册+产线改造+冷链建设） |
|
|
||||||
| **时间线** | 6-12 个月产品上市，18-24 个月盈亏平衡 |
|
|
||||||
| **主要风险** | 合作伙伴选择失误；利益分配冲突；管理复杂度高 |
|
|
||||||
| **退出成本** | 中——合资公司清算或股权转让 |
|
|
||||||
|
|
||||||
### 路径 C：自建产线重资产进入（推荐指数：★☆☆☆☆）
|
|
||||||
|
|
||||||
| 维度 | 详情 |
|
|
||||||
|------|------|
|
|
||||||
| **方式** | 在龙陵或昆明自建预制菜中央厨房/调味品生产线 |
|
|
||||||
| **首推产品** | 全系列石斛预制菜+石斛调味品 |
|
|
||||||
| **启动资金** | 5000 万-1 亿元（含厂房+设备+冷链物流+团队+渠道） |
|
|
||||||
| **时间线** | 18-24 个月产品上市，36-48 个月盈亏平衡 |
|
|
||||||
| **主要风险** | 资金压力大；产能利用率不足；远离消费市场导致冷链成本高 |
|
|
||||||
| **退出成本** | 极高——固定资产沉没，转型困难 |
|
|
||||||
| **当前阶段** | **强烈不建议** |
|
|
||||||
|
|
||||||
### 三路径对照总结
|
|
||||||
|
|
||||||
| 维度 | 路径 A OEM 试水 | 路径 B 战略合作 | 路径 C 重资产自建 |
|
|
||||||
|------|:---:|:---:|:---:|
|
|
||||||
| 启动资金 | 300-500 万 | 1000-2000 万 | 5000 万-1 亿 |
|
|
||||||
| 上市时间 | 3-6 个月 | 6-12 个月 | 18-24 个月 |
|
|
||||||
| 盈亏平衡 | 6-12 个月 | 18-24 个月 | 36-48 个月 |
|
|
||||||
| 风险等级 | 低 | 中 | 极高 |
|
|
||||||
| 可控性 | 中 | 中高 | 高 |
|
|
||||||
| 利润空间 | 低（代工费挤压） | 中（合资分成） | 中高（规模效应后） |
|
|
||||||
| 推荐指数 | ★★★★☆ | ★★★☆☆ | ★☆☆☆☆ |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 六、预期投入与回报周期（路径 A）
|
|
||||||
|
|
||||||
| 项目 | 明细 | 金额（万元） |
|
|
||||||
|------|------|:---:|
|
|
||||||
| **一次性投入** | | |
|
|
||||||
| 产品研发（汤料/火锅底料配方+石斛添加比例测试+保质期验证） | 外部研发合作 | 50-80 |
|
|
||||||
| 包装设计（品牌视觉+包材+首批印刷） | 设计+模具 | 30-50 |
|
|
||||||
| 首批生产（最小起订量，含石斛原料成本） | 3-5 个 SKU | 100-150 |
|
|
||||||
| 渠道铺设（线上详情页+达播合作+线下试销进场费） | | 50-80 |
|
|
||||||
| **一次性投入合计** | | **230-360 万** |
|
|
||||||
| **月度运营** | | |
|
|
||||||
| 线上运营（投流+平台佣金+团队） | 月均 | 20-40 |
|
|
||||||
| 线下促销/试吃/陈列费 | 月均 | 10-20 |
|
|
||||||
| **首年总投入** | | **约 500-700 万** |
|
|
||||||
|
|
||||||
| 时间节点 | 里程碑 | 预期表现 |
|
|
||||||
|------|------|------|
|
|
||||||
| 第 3 个月 | 产品上市（天猫/抖音首发） | 月销 10-20 万 |
|
|
||||||
| 第 6 个月 | 首轮数据验证 | 月销 30-50 万，复购率 > 15% → 继续投入 |
|
|
||||||
| 第 12 个月 | Go/No-Go 决策 | 月销 100 万+ → 考虑路径 B；< 30 万 → 停项目 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 七、最终建议
|
|
||||||
|
|
||||||
### 🟡 总体判断：**观望**
|
|
||||||
|
|
||||||
**进入** ❌
|
|
||||||
**观望** ✅（选择此项）
|
|
||||||
**放弃** ❌
|
|
||||||
|
|
||||||
### 核心理由
|
|
||||||
|
|
||||||
1. **预制菜/调味品均处于格局剧变期**：预制菜国家标准正在制定中，行业即将洗牌；调味品"零添加"禁令 2027 年全面生效，整个行业的产品和营销逻辑都在重构。此时贸然进入意味着在不确定的规则下做重投入决策。
|
|
||||||
|
|
||||||
2. **品斛堂的核心能力与预制菜/调味品的核心要求不匹配**：
|
|
||||||
- 预制菜的核心竞争力 = **冷链物流网络 + 口味研发 + 渠道效率 + 成本控制**
|
|
||||||
- 调味品的核心竞争力 = **酿造产能 + 品牌认知 + 百万终端覆盖 + 规模效应**
|
|
||||||
- 品斛堂的核心优势 = **石斛全产业链 + 原浆品类开创者 + 线上电商运营**
|
|
||||||
- 这三个集合的交集非常小
|
|
||||||
|
|
||||||
3. **资源应该聚焦核心战场**：
|
|
||||||
- 石斛原浆市场规模 120 亿，品斛堂市占率 45%+，还有 55%+ 的空间
|
|
||||||
- 复合原浆是第二增长曲线，增速 25%+，且与现有能力高度匹配
|
|
||||||
- 保健品蓝帽子注册是高毛利壁垒型业务（毛利率 60-80%）
|
|
||||||
- 这些机会的投入产出比远高于预制菜/调味品
|
|
||||||
|
|
||||||
4. **但不应完全放弃——可以"轻试水"**：
|
|
||||||
- 石斛养生汤料包和火锅底料可以极低成本试水（路径 A，300-500 万）
|
|
||||||
- 利用现有天猫/京东/抖音渠道做首发，不用新建渠道
|
|
||||||
- 本质上是将石斛原料以"汤料包"形式触达消费者
|
|
||||||
- 12 个月后根据数据决定是继续还是止损
|
|
||||||
|
|
||||||
### 行动建议
|
|
||||||
|
|
||||||
| 优先级 | 行动 | 时间 |
|
|
||||||
|:---:|------|------|
|
|
||||||
| P0 | 保持预制菜/调味品赛道月度舆情监控 | 即刻开始 |
|
|
||||||
| P1 | 石斛菌菇养生汤料包 OEM 试水立项（路径 A） | 下季度 |
|
|
||||||
| P2 | 调研云南本地预制菜合作伙伴（路径 B 前期） | 6 个月后 |
|
|
||||||
| P3 | 关注预制菜国家标准出台后的行业洗牌窗口 | 持续跟踪 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 八、数据来源与假设说明
|
|
||||||
|
|
||||||
### 主要数据来源
|
|
||||||
|
|
||||||
| 编号 | 来源 | 数据类型 | 时效 |
|
|
||||||
|:---:|------|------|:---:|
|
|
||||||
| [1] | 艾媒咨询《2023-2025 年中国预制菜行业运行及投资决策分析报告》 | 预制菜市场规模/格局 | 2024 |
|
|
||||||
| [2] | 艾媒咨询《2024-2025 年中国预制菜产业发展蓝皮书》 | 预制菜市场最新数据 | 2025 |
|
|
||||||
| [3] | 艾媒咨询《2025 年 H1 中国调味品行业运行数据监测半年报》 | 调味品市场数据 | 2025 |
|
|
||||||
| [4] | 华经产业研究院《中国复合调味品行业发展现状》 | 复合调味品市场规模 | 2024 |
|
|
||||||
| [5] | 弗诺斯特沙利文 | 酱油市场数据 | 2024-2025 |
|
|
||||||
| [6] | 嘉世咨询《2025 年中国调味品行业报告》 | 调味品竞争格局 | 2025 |
|
|
||||||
| [7] | 新华网/中国商报 | 预制菜企业数量/国家标准进展 | 2025 |
|
|
||||||
| [8] | 华鑫证券/平安证券预制菜行业研报 | 预制菜供应链/竞争分析 | 2023-2024 |
|
|
||||||
| [9] | 灼识咨询《2022 中国预制菜行业蓝皮书》 | 竞争格局 | 2022 |
|
|
||||||
| [10] | FDL 数食主张《药膳预制菜》 | 药膳预制菜趋势 | 2023 |
|
|
||||||
| [11] | 抖音电商数据（引用自食品伙伴网） | 药膳预制菜增长 | 2023 |
|
|
||||||
| [12] | 品斛堂企业调研报告（BIZ-53） | 品斛堂企业情报 | 2026.06 |
|
|
||||||
| [13] | 石斛食品饮料全品类产品方向详细文档 | 参考产品规划 | 2026 |
|
|
||||||
|
|
||||||
### 关键假设
|
|
||||||
|
|
||||||
- 2026 年预制菜市场规模取艾媒蓝皮书 7490 亿（较保守口径）
|
|
||||||
- 品斛堂参考文档中预制菜/调味品毛利预期 30-50%，本报告校正为更保守的 10-25%（基于上市公司实际数据）
|
|
||||||
- 药膳预制菜"增速数据（605%）基于抖音电商单一渠道，不代表全渠道增速
|
|
||||||
- 投资金额估算为行业平均水平参考值，实际可能因合作伙伴、地区政策等因素而浮动
|
|
||||||
- 石斛火锅底料的"不上火"概念为市场假设，需通过消费者调研验证
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*本报告仅供内部决策参考，不构成对外投资建议。*
|
|
||||||
*数据截止日期：2026 年 6 月 26 日*
|
|
||||||
@@ -0,0 +1,46 @@
|
|||||||
|
# Sidecar V2 — Multi-Pool Provider Proxy
|
||||||
|
FROM python:3.12-slim AS builder
|
||||||
|
|
||||||
|
WORKDIR /app
|
||||||
|
|
||||||
|
# Install dependencies
|
||||||
|
COPY requirements.txt .
|
||||||
|
RUN pip install --no-cache-dir --upgrade pip && \
|
||||||
|
pip install --no-cache-dir -r requirements.txt
|
||||||
|
|
||||||
|
# Copy application code
|
||||||
|
COPY config.py crypto.py main.py server.py proxy.py router.py \
|
||||||
|
pool_manager.py cooldown_manager.py rate_limiter.py __init__.py \
|
||||||
|
dashboard.html ./
|
||||||
|
COPY storage/ ./storage/
|
||||||
|
|
||||||
|
# Create data directory
|
||||||
|
RUN mkdir -p /app/data /app/data/backups
|
||||||
|
|
||||||
|
FROM python:3.12-slim
|
||||||
|
|
||||||
|
WORKDIR /app
|
||||||
|
|
||||||
|
# Copy built artifacts
|
||||||
|
COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
|
||||||
|
COPY --from=builder /app /app
|
||||||
|
|
||||||
|
# Environment
|
||||||
|
ENV SIDECAR_HOST=0.0.0.0
|
||||||
|
ENV SIDECAR_PORT=9190
|
||||||
|
ENV SIDECAR_METRICS_PORT=9191
|
||||||
|
ENV SIDECAR_DB_PATH=/app/data/sidecar_v2.db
|
||||||
|
ENV SIDECAR_BACKUP_DIR=/app/data/backups
|
||||||
|
ENV SIDECAR_ENCRYPTION_KEY=
|
||||||
|
ENV SIDECAR_ADMIN_TOKEN=
|
||||||
|
ENV LOG_FORMAT=json
|
||||||
|
ENV PYTHONUNBUFFERED=1
|
||||||
|
|
||||||
|
EXPOSE 9190 9191
|
||||||
|
|
||||||
|
VOLUME ["/app/data"]
|
||||||
|
|
||||||
|
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
|
||||||
|
CMD python3 -c "import urllib.request; urllib.request.urlopen('http://localhost:9190/health')" || exit 1
|
||||||
|
|
||||||
|
ENTRYPOINT ["python3", "main.py"]
|
||||||
@@ -0,0 +1,77 @@
|
|||||||
|
# Sidecar V2 — Multi-Pool Provider Proxy
|
||||||
|
|
||||||
|
## 概述
|
||||||
|
Sidecar V2 是 OpenClaw 的 API 代理服务，实现多 Provider 池管理、负载均衡、429 冷却、RPM 队列控流。
|
||||||
|
|
||||||
|
## 核心功能
|
||||||
|
- **Provider 池管理**：主池 (primary) + 备用池 (fallback)，支持动态增删 Provider
|
||||||
|
- **429 冷却**：检测 429 → 自动冷却 → 指数退避 → 自动恢复
|
||||||
|
- **按 Provider 独立 RPM 限流**：每个 Provider 独立的 Token Bucket
|
||||||
|
- **路由策略**：主池优先 → 备用池兜底 → 全部耗尽返 503
|
||||||
|
- **WebUI 管理**：Dashboard 仪表盘 + Provider CRUD
|
||||||
|
- **用量统计**：Token 用量 + 费用统计 + 每小时/每日聚合
|
||||||
|
- **API Key 加密**：AES-256-GCM 加密存储
|
||||||
|
|
||||||
|
## 架构
|
||||||
|
|
||||||
|
```
|
||||||
|
OpenClaw → Sidecar V2 (port 9190) → 路由 → 主池 Provider 1,2,3...
|
||||||
|
↘ 备池 Provider 4,5...
|
||||||
|
↘ 全部耗尽 → 503
|
||||||
|
```
|
||||||
|
|
||||||
|
## 快速开始
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 设置加密密钥 (64位十六进制)
|
||||||
|
export SIDECAR_ENCRYPTION_KEY="0000111122223333444455556666777788889999aaaabbbbccccddddeeeeffff"
|
||||||
|
|
||||||
|
# 启动服务
|
||||||
|
python3 main.py
|
||||||
|
|
||||||
|
# OR via uvicorn
|
||||||
|
python3 -m uvicorn server:app --host 127.0.0.1 --port 9190
|
||||||
|
```
|
||||||
|
|
||||||
|
## WebUI
|
||||||
|
访问 http://127.0.0.1:9190/dashboard
|
||||||
|
|
||||||
|
## API 端点
|
||||||
|
|
||||||
|
### Admin API
|
||||||
|
- `GET /api/admin/backends` — 列出所有 Provider
|
||||||
|
- `POST /api/admin/backends` — 添加 Provider
|
||||||
|
- `PUT /api/admin/backends/{id}` — 更新 Provider
|
||||||
|
- `DELETE /api/admin/backends/{id}` — 删除 Provider
|
||||||
|
- `GET /api/admin/pools` — 池状态汇总
|
||||||
|
- `GET /api/admin/stats/total` — 总计统计
|
||||||
|
- `GET /api/admin/stats/hourly` — 每小时用量
|
||||||
|
- `GET /api/admin/stats/daily` — 每日聚合
|
||||||
|
- `GET /api/admin/stats/cooldown` — 冷却事件历史
|
||||||
|
- `GET /api/admin/config` — 系统配置
|
||||||
|
|
||||||
|
### 代理 API (OpenAI 兼容)
|
||||||
|
- `POST /v1/chat/completions`
|
||||||
|
- `POST /v1/completions`
|
||||||
|
- `POST /v1/embeddings`
|
||||||
|
- `GET /v1/models`
|
||||||
|
|
||||||
|
### 监控
|
||||||
|
- `GET /health` — 健康检查
|
||||||
|
- `GET /dashboard/sse` — Dashboard 实时数据流 (SSE)
|
||||||
|
|
||||||
|
## 环境变量
|
||||||
|
|
||||||
|
| 变量 | 默认值 | 说明 |
|
||||||
|
|------|--------|------|
|
||||||
|
| SIDECAR_HOST | 127.0.0.1 | 监听地址 |
|
||||||
|
| SIDECAR_PORT | 9190 | 监听端口 |
|
||||||
|
| SIDECAR_ENCRYPTION_KEY | (必填) | API Key 加密密钥 (64 hex chars) |
|
||||||
|
| SIDECAR_DB_PATH | ./data/sidecar_v2.db | SQLite 数据库路径 |
|
||||||
|
| SIDECAR_RATE_RPM | 40 | 默认 RPM 限制 |
|
||||||
|
| SIDECAR_COOLDOWN_BASE | 30 | 冷却基础时长 (秒) |
|
||||||
|
| SIDECAR_COOLDOWN_MAX | 600 | 冷却最大时长 (秒) |
|
||||||
|
|
||||||
|
## 存储
|
||||||
|
- SQLite (WAL 模式)
|
||||||
|
- 表：backends, backend_usage_logs, cooldown_events, backend_health, system_config, daily_stats
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
"""Sidecar V2 — Multi-pool provider proxy with cooldown, rate limiting, and WebUI management."""
|
||||||
@@ -0,0 +1,165 @@
|
|||||||
|
"""System configuration management for Sidecar V2."""
|
||||||
|
|
||||||
|
import os
|
||||||
|
import json
|
||||||
|
from dataclasses import dataclass, field, asdict
|
||||||
|
from typing import Optional
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class Config:
|
||||||
|
"""Sidecar V2 runtime configuration.
|
||||||
|
|
||||||
|
Sources (priority order):
|
||||||
|
1. Environment variables (highest)
|
||||||
|
2. system_config table in SQLite
|
||||||
|
3. Defaults defined here
|
||||||
|
"""
|
||||||
|
|
||||||
|
# Listen
|
||||||
|
host: str = "127.0.0.1"
|
||||||
|
port: int = 9190
|
||||||
|
metrics_port: int = 9191
|
||||||
|
|
||||||
|
# Queue
|
||||||
|
queue_max_depth: int = 500
|
||||||
|
queue_timeout_seconds: float = 30.0
|
||||||
|
|
||||||
|
# Provider
|
||||||
|
default_rpm_limit: int = 40
|
||||||
|
|
||||||
|
# Cooldown
|
||||||
|
cooldown_base_seconds: float = 30.0
|
||||||
|
cooldown_max_seconds: float = 600.0
|
||||||
|
cooldown_exponential_backoff: bool = True
|
||||||
|
|
||||||
|
# Emergency channel: RPM fraction when all pools exhausted
|
||||||
|
emergency_rpm_fraction: float = 0.10
|
||||||
|
|
||||||
|
# Health check
|
||||||
|
health_check_interval_seconds: int = 60
|
||||||
|
health_check_timeout_seconds: int = 10
|
||||||
|
health_probe_endpoint: str = "/v1/models"
|
||||||
|
|
||||||
|
# Admin auth
|
||||||
|
admin_token: str = ""
|
||||||
|
|
||||||
|
# Encryption
|
||||||
|
encryption_key: str = ""
|
||||||
|
|
||||||
|
# Logging
|
||||||
|
log_level: str = "INFO"
|
||||||
|
|
||||||
|
# Database
|
||||||
|
db_path: str = ""
|
||||||
|
backup_dir: str = ""
|
||||||
|
backup_retention_days: int = 7
|
||||||
|
|
||||||
|
# Rate limiter
|
||||||
|
rate_limiter_refill_interval_ms: int = 50
|
||||||
|
|
||||||
|
# Router
|
||||||
|
router_refresh_interval_seconds: float = 5.0
|
||||||
|
|
||||||
|
# Max pool-internal retries
|
||||||
|
max_pool_retries: int = 5
|
||||||
|
|
||||||
|
# Pre-check cooldown threshold (seconds remaining)
|
||||||
|
cooldown_precheck_threshold_seconds: float = 10.0
|
||||||
|
|
||||||
|
# Dashboard
|
||||||
|
dashboard_sse_interval_seconds: float = 1.0
|
||||||
|
|
||||||
|
# Stats
|
||||||
|
stats_refresh_interval_seconds: float = 30.0
|
||||||
|
|
||||||
|
# Request timeout
|
||||||
|
default_request_timeout_seconds: int = 120
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
def from_env(cls) -> "Config":
|
||||||
|
"""Load configuration from environment variables."""
|
||||||
|
c = cls()
|
||||||
|
|
||||||
|
# Listen
|
||||||
|
c.host = os.getenv("SIDECAR_HOST", c.host)
|
||||||
|
c.port = int(os.getenv("SIDECAR_PORT", str(c.port)))
|
||||||
|
c.metrics_port = int(os.getenv("SIDECAR_METRICS_PORT", str(c.metrics_port)))
|
||||||
|
|
||||||
|
# Queue
|
||||||
|
c.queue_max_depth = int(os.getenv("SIDECAR_QUEUE_MAX", str(c.queue_max_depth)))
|
||||||
|
c.queue_timeout_seconds = float(
|
||||||
|
os.getenv("SIDECAR_QUEUE_TIMEOUT", str(c.queue_timeout_seconds))
|
||||||
|
)
|
||||||
|
|
||||||
|
# Provider
|
||||||
|
c.default_rpm_limit = int(
|
||||||
|
os.getenv("SIDECAR_RATE_RPM", str(c.default_rpm_limit))
|
||||||
|
)
|
||||||
|
|
||||||
|
# Cooldown
|
||||||
|
c.cooldown_base_seconds = float(
|
||||||
|
os.getenv("SIDECAR_COOLDOWN_BASE", str(c.cooldown_base_seconds))
|
||||||
|
)
|
||||||
|
c.cooldown_max_seconds = float(
|
||||||
|
os.getenv("SIDECAR_COOLDOWN_MAX", str(c.cooldown_max_seconds))
|
||||||
|
)
|
||||||
|
|
||||||
|
# Admin
|
||||||
|
c.admin_token = os.getenv("SIDECAR_ADMIN_TOKEN", c.admin_token)
|
||||||
|
|
||||||
|
# Encryption
|
||||||
|
c.encryption_key = os.getenv("SIDECAR_ENCRYPTION_KEY", c.encryption_key)
|
||||||
|
|
||||||
|
# Logging
|
||||||
|
c.log_level = os.getenv("LOG_LEVEL", c.log_level).upper()
|
||||||
|
|
||||||
|
# Database
|
||||||
|
c.db_path = os.getenv(
|
||||||
|
"SIDECAR_DB_PATH",
|
||||||
|
os.path.join(os.getcwd(), "data", "sidecar_v2.db"),
|
||||||
|
)
|
||||||
|
c.backup_dir = os.getenv(
|
||||||
|
"SIDECAR_BACKUP_DIR",
|
||||||
|
os.path.join(os.getcwd(), "data", "backups"),
|
||||||
|
)
|
||||||
|
|
||||||
|
# V1 compatibility: migrate env vars
|
||||||
|
c._migrate_v1_env()
|
||||||
|
|
||||||
|
return c
|
||||||
|
|
||||||
|
def _migrate_v1_env(self) -> None:
|
||||||
|
"""Migrate V1 environment variables to V2 defaults."""
|
||||||
|
# V1 UPSTREAM endpoint
|
||||||
|
upstream = os.getenv("SIDECAR_UPSTREAM")
|
||||||
|
api_key = os.getenv("SIDECAR_API_KEY")
|
||||||
|
if api_key and self.encryption_key:
|
||||||
|
# These will be used during initial migration
|
||||||
|
os.environ["_SIDECAR_V1_API_KEY"] = api_key
|
||||||
|
os.environ["_SIDECAR_V1_UPSTREAM"] = upstream or "https://integrate.api.nvidia.com/v1"
|
||||||
|
|
||||||
|
def to_db_dict(self) -> dict:
|
||||||
|
"""Serialize to dict for system_config storage."""
|
||||||
|
result = {}
|
||||||
|
for key, value in asdict(self).items():
|
||||||
|
if isinstance(value, bool):
|
||||||
|
result[key] = "true" if value else "false"
|
||||||
|
elif isinstance(value, (int, float)):
|
||||||
|
result[key] = str(value)
|
||||||
|
else:
|
||||||
|
result[key] = value
|
||||||
|
return result
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
def merge_db(cls, base: "Config", db_config: dict) -> "Config":
|
||||||
|
"""Merge DB config into base config (env vars already applied to base)."""
|
||||||
|
for key, value in base.__dict__.items():
|
||||||
|
if key in db_config and key not in os.environ:
|
||||||
|
# DB values only apply when no env var override
|
||||||
|
setattr(base, key, type(value)(db_config[key]))
|
||||||
|
return base
|
||||||
|
|
||||||
|
|
||||||
|
# Singleton
|
||||||
|
config = Config.from_env()
|
||||||
@@ -0,0 +1,114 @@
|
|||||||
|
"""429 Cooldown management for backends using exponential backoff."""
|
||||||
|
|
||||||
|
import time
|
||||||
|
from datetime import datetime, timezone
|
||||||
|
import structlog
|
||||||
|
from config import config
|
||||||
|
from storage.backend_store import set_backend_cooldown, clear_backend_cooldown, get_backend
|
||||||
|
from storage.cooldown_store import log_cooldown_event, end_cooldown_event
|
||||||
|
|
||||||
|
logger = structlog.get_logger("sidecar_v2.cooldown_manager")
|
||||||
|
|
||||||
|
|
||||||
|
def calculate_cooldown(consecutive_count: int) -> float:
|
||||||
|
"""Calculate cooldown duration using exponential backoff.
|
||||||
|
|
||||||
|
Formula: base * 2^(consecutive-1), capped at max.
|
||||||
|
"""
|
||||||
|
base = config.cooldown_base_seconds
|
||||||
|
max_seconds = config.cooldown_max_seconds
|
||||||
|
if config.cooldown_exponential_backoff:
|
||||||
|
duration = base * (2 ** (consecutive_count - 1))
|
||||||
|
else:
|
||||||
|
duration = base * consecutive_count
|
||||||
|
return min(duration, max_seconds)
|
||||||
|
|
||||||
|
|
||||||
|
def start_cooldown(backend_id: str, consecutive_count: int) -> float:
|
||||||
|
"""Start cooldown for a backend after 429.
|
||||||
|
|
||||||
|
Returns: cooldown end timestamp.
|
||||||
|
"""
|
||||||
|
duration = calculate_cooldown(consecutive_count)
|
||||||
|
cooldown_until_ts = time.time() + duration
|
||||||
|
cooldown_until = time.strftime(
|
||||||
|
"%Y-%m-%dT%H:%M:%SZ", time.gmtime(cooldown_until_ts)
|
||||||
|
)
|
||||||
|
|
||||||
|
set_backend_cooldown(backend_id, cooldown_until, consecutive_count)
|
||||||
|
log_cooldown_event(
|
||||||
|
backend_id=backend_id,
|
||||||
|
consecutive_count=consecutive_count,
|
||||||
|
cooldown_seconds=int(duration),
|
||||||
|
response_summary=f"429 cooldown triggered (consecutive #{consecutive_count})",
|
||||||
|
)
|
||||||
|
|
||||||
|
logger.info(
|
||||||
|
"cooldown_started",
|
||||||
|
backend_id=backend_id,
|
||||||
|
duration=round(duration, 1),
|
||||||
|
consecutive=consecutive_count,
|
||||||
|
)
|
||||||
|
return duration
|
||||||
|
|
||||||
|
|
||||||
|
def check_and_clear_cooldown(backend_id: str) -> bool:
|
||||||
|
"""Check if cooldown has expired for a backend.
|
||||||
|
|
||||||
|
Returns True if cooldown was cleared (backend is back online).
|
||||||
|
"""
|
||||||
|
backend = get_backend(backend_id, decrypt_key=False)
|
||||||
|
if backend is None:
|
||||||
|
return False
|
||||||
|
|
||||||
|
if backend.status != "cooling":
|
||||||
|
return False
|
||||||
|
|
||||||
|
cooldown_until = backend.cooldown_until
|
||||||
|
if not cooldown_until:
|
||||||
|
clear_backend_cooldown(backend_id)
|
||||||
|
return True
|
||||||
|
|
||||||
|
# Parse cooldown_until as ISO timestamp
|
||||||
|
try:
|
||||||
|
dt = datetime.fromisoformat(cooldown_until.replace("Z", "+00:00"))
|
||||||
|
cooldown_ts = dt.timestamp()
|
||||||
|
except ValueError:
|
||||||
|
# If parsing fails, clear and move on
|
||||||
|
clear_backend_cooldown(backend_id)
|
||||||
|
return True
|
||||||
|
|
||||||
|
now = time.time()
|
||||||
|
if now >= cooldown_ts:
|
||||||
|
clear_backend_cooldown(backend_id)
|
||||||
|
end_cooldown_event(backend_id)
|
||||||
|
logger.info("cooldown_cleared", backend_id=backend_id)
|
||||||
|
return True
|
||||||
|
|
||||||
|
remaining = cooldown_ts - now
|
||||||
|
logger.debug("cooldown_active", backend_id=backend_id, remaining_seconds=round(remaining, 1))
|
||||||
|
return False
|
||||||
|
|
||||||
|
|
||||||
|
def precheck_cooldown(backend_id: str) -> bool:
|
||||||
|
"""Check if backend should be skipped due to near-expiry cooldown.
|
||||||
|
|
||||||
|
If cooldown will expire within config.cooldown_precheck_threshold_seconds,
|
||||||
|
skip the backend so we don't hit it again right as it expires.
|
||||||
|
"""
|
||||||
|
backend = get_backend(backend_id, decrypt_key=False)
|
||||||
|
if backend is None or backend.status != "cooling":
|
||||||
|
return False
|
||||||
|
|
||||||
|
cooldown_until = backend.cooldown_until
|
||||||
|
if not cooldown_until:
|
||||||
|
return False
|
||||||
|
|
||||||
|
try:
|
||||||
|
dt = datetime.fromisoformat(cooldown_until.replace("Z", "+00:00"))
|
||||||
|
cooldown_ts = dt.timestamp()
|
||||||
|
except ValueError:
|
||||||
|
return False
|
||||||
|
|
||||||
|
remaining = cooldown_ts - time.time()
|
||||||
|
return 0 < remaining <= config.cooldown_precheck_threshold_seconds
|
||||||
@@ -0,0 +1,108 @@
|
|||||||
|
"""AES-256-GCM encryption for API Key storage."""
|
||||||
|
|
||||||
|
import os
|
||||||
|
import secrets
|
||||||
|
import structlog
|
||||||
|
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
|
||||||
|
|
||||||
|
logger = structlog.get_logger()
|
||||||
|
|
||||||
|
_ENCRYPTION_KEY: bytes | None = None
|
||||||
|
_cipher: AESGCM | None = None
|
||||||
|
|
||||||
|
|
||||||
|
def init_crypto(hex_key: str) -> None:
|
||||||
|
"""Initialize the encryption module.
|
||||||
|
|
||||||
|
Validates the key and prepares the cipher.
|
||||||
|
Raises ValueError if key is invalid.
|
||||||
|
"""
|
||||||
|
global _ENCRYPTION_KEY, _cipher
|
||||||
|
|
||||||
|
if not hex_key:
|
||||||
|
raise ValueError("FATAL: SIDECAR_ENCRYPTION_KEY not set")
|
||||||
|
|
||||||
|
if len(hex_key) != 64:
|
||||||
|
raise ValueError(
|
||||||
|
f"FATAL: SIDECAR_ENCRYPTION_KEY must be 64 hex chars (32 bytes), "
|
||||||
|
f"got {len(hex_key)} chars"
|
||||||
|
)
|
||||||
|
|
||||||
|
try:
|
||||||
|
key_bytes = bytes.fromhex(hex_key)
|
||||||
|
except ValueError:
|
||||||
|
raise ValueError(
|
||||||
|
"FATAL: SIDECAR_ENCRYPTION_KEY must be valid hexadecimal"
|
||||||
|
)
|
||||||
|
|
||||||
|
global _ENCRYPTION_KEY, _cipher
|
||||||
|
_ENCRYPTION_KEY = key_bytes
|
||||||
|
_cipher = AESGCM(key_bytes)
|
||||||
|
logger.info("crypto_initialized")
|
||||||
|
|
||||||
|
|
||||||
|
def encrypt(plaintext: str) -> str:
|
||||||
|
"""Encrypt plaintext using AES-256-GCM.
|
||||||
|
|
||||||
|
Returns: hex-encoded nonce (12 bytes) + ciphertext + tag.
|
||||||
|
Format: <nonce_hex>:<ciphertext_hex>
|
||||||
|
"""
|
||||||
|
if _cipher is None:
|
||||||
|
raise RuntimeError("Crypto not initialized. Call init_crypto() first.")
|
||||||
|
|
||||||
|
nonce = secrets.token_bytes(12)
|
||||||
|
ciphertext = _cipher.encrypt(nonce, plaintext.encode("utf-8"), None)
|
||||||
|
return nonce.hex() + ":" + ciphertext.hex()
|
||||||
|
|
||||||
|
|
||||||
|
def decrypt(encrypted: str) -> str:
|
||||||
|
"""Decrypt AES-256-GCM ciphertext.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
encrypted: Format "<nonce_hex>:<ciphertext_hex>"
|
||||||
|
|
||||||
|
Returns: Decrypted plaintext string.
|
||||||
|
"""
|
||||||
|
if _cipher is None:
|
||||||
|
raise RuntimeError("Crypto not initialized. Call init_crypto() first.")
|
||||||
|
|
||||||
|
parts = encrypted.split(":", 1)
|
||||||
|
if len(parts) != 2:
|
||||||
|
raise ValueError("Invalid encrypted format: expected nonce:ciphertext")
|
||||||
|
|
||||||
|
nonce = bytes.fromhex(parts[0])
|
||||||
|
ciphertext = bytes.fromhex(parts[1])
|
||||||
|
|
||||||
|
try:
|
||||||
|
plaintext = _cipher.decrypt(nonce, ciphertext, None)
|
||||||
|
return plaintext.decode("utf-8")
|
||||||
|
except Exception as e:
|
||||||
|
raise ValueError(f"Decryption failed: {e}")
|
||||||
|
|
||||||
|
|
||||||
|
def is_initialized() -> bool:
|
||||||
|
"""Check if crypto has been initialized."""
|
||||||
|
return _cipher is not None
|
||||||
|
|
||||||
|
|
||||||
|
def mask_api_key(api_key_plain: str) -> str:
|
||||||
|
"""Mask API key for display: show first 6 + last 4 chars."""
|
||||||
|
if len(api_key_plain) <= 10:
|
||||||
|
return api_key_plain[:2] + "****"
|
||||||
|
return api_key_plain[:6] + "****" + api_key_plain[-4:]
|
||||||
|
|
||||||
|
|
||||||
|
def try_decrypt_existing(encrypted_value: str) -> str | None:
|
||||||
|
"""Try to decrypt an existing encrypted value.
|
||||||
|
|
||||||
|
Returns the plaintext if successful, None if decryption fails
|
||||||
|
(e.g., encryption key was changed).
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
return decrypt(encrypted_value)
|
||||||
|
except Exception:
|
||||||
|
logger.warning(
|
||||||
|
"decrypt_existing_failed",
|
||||||
|
hint="Encryption key may have been changed, existing keys unrecoverable"
|
||||||
|
)
|
||||||
|
return None
|
||||||
@@ -0,0 +1,623 @@
|
|||||||
|
<!DOCTYPE html>
|
||||||
|
<html lang="zh-CN">
|
||||||
|
<head>
|
||||||
|
<meta charset="UTF-8">
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||||
|
<title>Sidecar V2 — Provider Pool Dashboard</title>
|
||||||
|
<!-- Primary: jsDelivr CDN -->
|
||||||
|
<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js"></script>
|
||||||
|
<!-- Fallback: local static copy for offline/intranet deployments -->
|
||||||
|
<script>
|
||||||
|
(function() {
|
||||||
|
var check = function() {
|
||||||
|
if (typeof Chart === 'undefined') {
|
||||||
|
var s = document.createElement('script');
|
||||||
|
s.src = '/static/chart.umd.min.js';
|
||||||
|
s.onerror = function() {
|
||||||
|
console.warn('Chart.js unavailable (CDN + local both failed). Charts disabled.');
|
||||||
|
};
|
||||||
|
document.head.appendChild(s);
|
||||||
|
}
|
||||||
|
};
|
||||||
|
// Check after CDN script has had a chance to load
|
||||||
|
setTimeout(check, 2000);
|
||||||
|
})();
|
||||||
|
</script>
|
||||||
|
<style>
|
||||||
|
:root {
|
||||||
|
--bg: #0f1117;
|
||||||
|
--card-bg: #1a1d28;
|
||||||
|
--border: #2a2d3a;
|
||||||
|
--text: #e0e0e0;
|
||||||
|
--text-dim: #888;
|
||||||
|
--green: #23d160;
|
||||||
|
--yellow: #ffdd57;
|
||||||
|
--red: #ff3860;
|
||||||
|
--blue: #3273dc;
|
||||||
|
--purple: #b86bff;
|
||||||
|
--cyan: #00d1b2;
|
||||||
|
--orange: #ff8533;
|
||||||
|
}
|
||||||
|
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||||
|
body {
|
||||||
|
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
|
||||||
|
background: var(--bg);
|
||||||
|
color: var(--text);
|
||||||
|
min-height: 100vh;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* Layout */
|
||||||
|
.app { display: flex; height: 100vh; }
|
||||||
|
.sidebar {
|
||||||
|
width: 220px; background: var(--card-bg); border-right: 1px solid var(--border);
|
||||||
|
padding: 20px 0; display: flex; flex-direction: column;
|
||||||
|
}
|
||||||
|
.sidebar h2 { padding: 0 20px 20px; font-size: 16px; color: var(--cyan); border-bottom: 1px solid var(--border); }
|
||||||
|
.sidebar nav { flex: 1; padding: 10px 0; }
|
||||||
|
.sidebar nav a {
|
||||||
|
display: block; padding: 10px 20px; color: var(--text-dim); text-decoration: none;
|
||||||
|
font-size: 13px; transition: 0.2s;
|
||||||
|
}
|
||||||
|
.sidebar nav a:hover, .sidebar nav a.active { color: var(--text); background: rgba(255,255,255,0.05); }
|
||||||
|
.sidebar .status-bar { padding: 15px 20px; border-top: 1px solid var(--border); font-size: 11px; color: var(--text-dim); }
|
||||||
|
|
||||||
|
.main { flex: 1; overflow-y: auto; padding: 24px; }
|
||||||
|
.page { display: none; }
|
||||||
|
.page.active { display: block; }
|
||||||
|
|
||||||
|
/* Dashboard Cards */
|
||||||
|
.cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 16px; margin-bottom: 24px; }
|
||||||
|
.card {
|
||||||
|
background: var(--card-bg); border: 1px solid var(--border); border-radius: 8px; padding: 16px;
|
||||||
|
}
|
||||||
|
.card .label { font-size: 12px; color: var(--text-dim); text-transform: uppercase;letter-spacing:0.5px;margin-bottom:6px; }
|
||||||
|
.card .value { font-size: 28px; font-weight: 700; }
|
||||||
|
.card .sub { font-size: 12px; color: var(--text-dim); margin-top: 4px; }
|
||||||
|
|
||||||
|
.charts { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; }
|
||||||
|
.chart-card {
|
||||||
|
background: var(--card-bg); border: 1px solid var(--border); border-radius: 8px; padding: 16px;
|
||||||
|
}
|
||||||
|
.chart-card h3 { font-size: 14px; margin-bottom: 12px; color: var(--text-dim); }
|
||||||
|
.chart-card canvas { max-height: 250px; }
|
||||||
|
|
||||||
|
/* Pool Cards */
|
||||||
|
.pool-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; margin-bottom: 24px; }
|
||||||
|
.pool-card {
|
||||||
|
background: var(--card-bg); border: 1px solid var(--border); border-radius: 8px; padding: 16px;
|
||||||
|
}
|
||||||
|
.pool-card h3 { font-size: 15px; margin-bottom: 12px; text-transform: uppercase; letter-spacing: 1px; }
|
||||||
|
.pool-card h3.primary { color: var(--blue); }
|
||||||
|
.pool-card h3.fallback { color: var(--orange); }
|
||||||
|
.pool-stats { display: grid; grid-template-columns: repeat(4, 1fr); gap: 8px; }
|
||||||
|
.pool-stat { text-align: center; }
|
||||||
|
.pool-stat .num { font-size: 22px; font-weight: 700; }
|
||||||
|
.pool-stat .lbl { font-size: 11px; color: var(--text-dim); margin-top: 2px; }
|
||||||
|
.pool-stat.healthy .num { color: var(--green); }
|
||||||
|
.pool-stat.cooling .num { color: var(--yellow); }
|
||||||
|
.pool-stat.error .num { color: var(--red); }
|
||||||
|
.pool-stat.total .num { color: var(--purple); }
|
||||||
|
|
||||||
|
/* Tables */
|
||||||
|
table { width: 100%; border-collapse: collapse; background: var(--card-bg); border-radius: 8px; overflow: hidden; }
|
||||||
|
th { text-align: left; padding: 10px 12px; font-size: 11px; text-transform: uppercase; letter-spacing: 0.5px; color: var(--text-dim); background: rgba(255,255,255,0.03); border-bottom: 1px solid var(--border); }
|
||||||
|
td { padding: 10px 12px; font-size: 13px; border-bottom: 1px solid var(--border); }
|
||||||
|
tr:last-child td { border-bottom: none; }
|
||||||
|
tr:hover { background: rgba(255,255,255,0.02); }
|
||||||
|
.badge {
|
||||||
|
display: inline-block; padding: 2px 8px; border-radius: 10px; font-size: 11px; font-weight: 600;
|
||||||
|
}
|
||||||
|
.badge.healthy { background: rgba(35,209,96,0.15); color: var(--green); }
|
||||||
|
.badge.cooling { background: rgba(255,221,87,0.15); color: var(--yellow); }
|
||||||
|
.badge.error { background: rgba(255,56,96,0.15); color: var(--red); }
|
||||||
|
.badge.disabled { background: rgba(136,136,136,0.15); color: var(--text-dim); }
|
||||||
|
.badge.primary { background: rgba(50,115,220,0.15); color: var(--blue); }
|
||||||
|
.badge.fallback { background: rgba(255,133,51,0.15); color: var(--orange); }
|
||||||
|
|
||||||
|
/* Buttons */
|
||||||
|
.btn {
|
||||||
|
padding: 6px 14px; border-radius: 6px; border: none; cursor: pointer; font-size: 12px; font-weight: 600;
|
||||||
|
transition: 0.2s;
|
||||||
|
}
|
||||||
|
.btn-primary { background: var(--blue); color: #fff; }
|
||||||
|
.btn-primary:hover { opacity: 0.85; }
|
||||||
|
.btn-danger { background: var(--red); color: #fff; }
|
||||||
|
.btn-danger:hover { opacity: 0.85; }
|
||||||
|
.btn-sm { padding: 3px 10px; font-size: 11px; }
|
||||||
|
.btn-outline { background: transparent; border: 1px solid var(--border); color: var(--text); }
|
||||||
|
.btn-outline:hover { background: rgba(255,255,255,0.05); }
|
||||||
|
|
||||||
|
.section-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 12px; }
|
||||||
|
.section-header h3 { font-size: 15px; }
|
||||||
|
|
||||||
|
/* Modal */
|
||||||
|
.modal-overlay { display: none; position: fixed; top: 0; left: 0; right: 0; bottom: 0; background: rgba(0,0,0,0.7); z-index: 100; justify-content: center; align-items: center; }
|
||||||
|
.modal-overlay.active { display: flex; }
|
||||||
|
.modal { background: var(--card-bg); border: 1px solid var(--border); border-radius: 12px; padding: 24px; width: 560px; max-height: 80vh; overflow-y: auto; }
|
||||||
|
.modal h3 { margin-bottom: 16px; font-size: 16px; }
|
||||||
|
.form-group { margin-bottom: 12px; }
|
||||||
|
.form-group label { display: block; font-size: 12px; color: var(--text-dim); margin-bottom: 4px; }
|
||||||
|
.form-group input, .form-group select, .form-group textarea {
|
||||||
|
width: 100%; padding: 8px 10px; background: var(--bg); border: 1px solid var(--border);
|
||||||
|
border-radius: 6px; color: var(--text); font-size: 13px;
|
||||||
|
}
|
||||||
|
.form-group textarea { min-height: 80px; font-family: monospace; font-size: 12px; }
|
||||||
|
.form-row { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; }
|
||||||
|
.form-actions { display: flex; gap: 8px; justify-content: flex-end; margin-top: 16px; }
|
||||||
|
.model-mapping-row { display: flex; gap: 8px; align-items: center; margin-bottom: 8px; }
|
||||||
|
.model-mapping-row input { flex: 1; }
|
||||||
|
|
||||||
|
/* Utility */
|
||||||
|
.text-green { color: var(--green); }
|
||||||
|
.text-red { color: var(--red); }
|
||||||
|
.text-dim { color: var(--text-dim); }
|
||||||
|
.mb-16 { margin-bottom: 16px; }
|
||||||
|
.mb-24 { margin-bottom: 24px; }
|
||||||
|
|
||||||
|
@media (max-width: 768px) {
|
||||||
|
.charts, .pool-grid { grid-template-columns: 1fr; }
|
||||||
|
.sidebar { display: none; }
|
||||||
|
}
|
||||||
|
</style>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<div class="app">
|
||||||
|
<!-- Sidebar -->
|
||||||
|
<aside class="sidebar">
|
||||||
|
<h2>🚀 Sidecar V2</h2>
|
||||||
|
<nav>
|
||||||
|
<a href="#" data-page="dashboard" class="active">📊 Dashboard</a>
|
||||||
|
<a href="#" data-page="providers">🔌 Providers</a>
|
||||||
|
<a href="#" data-page="usage">📈 Usage Stats</a>
|
||||||
|
<a href="#" data-page="cooldown">🧊 Cooldown Log</a>
|
||||||
|
</nav>
|
||||||
|
<div class="status-bar" id="status-bar">Connected · Sidecar V2</div>
|
||||||
|
</aside>
|
||||||
|
|
||||||
|
<!-- Main Content -->
|
||||||
|
<main class="main">
|
||||||
|
<!-- Dashboard Page -->
|
||||||
|
<div class="page active" id="page-dashboard">
|
||||||
|
<div class="cards" id="stat-cards"></div>
|
||||||
|
<div class="pool-grid" id="pool-grid"></div>
|
||||||
|
<div class="charts" id="charts"></div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<!-- Providers Page -->
|
||||||
|
<div class="page" id="page-providers">
|
||||||
|
<div class="section-header">
|
||||||
|
<h3>Provider Backends</h3>
|
||||||
|
<button class="btn btn-primary" onclick="showAddBackend()">+ Add Provider</button>
|
||||||
|
</div>
|
||||||
|
<table id="backends-table">
|
||||||
|
<thead>
|
||||||
|
<tr><th>Name</th><th>Label</th><th>Pool</th><th>Status</th><th>RPM</th><th>Models</th><th>Actions</th></tr>
|
||||||
|
</thead>
|
||||||
|
<tbody></tbody>
|
||||||
|
</table>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<!-- Usage Page -->
|
||||||
|
<div class="page" id="page-usage">
|
||||||
|
<div class="section-header"><h3>Hourly Usage</h3></div>
|
||||||
|
<div class="mb-16">
|
||||||
|
<select id="usage-backend-filter" onchange="loadUsage()" class="btn btn-outline btn-sm">
|
||||||
|
<option value="">All Backends</option>
|
||||||
|
</select>
|
||||||
|
</div>
|
||||||
|
<table id="usage-table">
|
||||||
|
<thead>
|
||||||
|
<tr><th>Hour</th><th>Backend</th><th>Model</th><th>Requests</th><th>Errors</th><th>Tokens</th><th>Cost</th><th>Avg Latency</th></tr>
|
||||||
|
</thead>
|
||||||
|
<tbody></tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<div class="section-header mt-24 mb-16"><h3>Daily Aggregation</h3></div>
|
||||||
|
<table id="daily-table">
|
||||||
|
<thead>
|
||||||
|
<tr><th>Date</th><th>Pool</th><th>Requests</th><th>Errors</th><th>Tokens</th><th>Cost</th><th>Backends</th></tr>
|
||||||
|
</thead>
|
||||||
|
<tbody></tbody>
|
||||||
|
</table>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<!-- Cooldown Page -->
|
||||||
|
<div class="page" id="page-cooldown">
|
||||||
|
<div class="section-header"><h3>Cooldown Event History</h3></div>
|
||||||
|
<table id="cooldown-table">
|
||||||
|
<thead>
|
||||||
|
<tr><th>Time</th><th>Backend</th><th>Consecutive 429s</th><th>Duration</th><th>Summary</th></tr>
|
||||||
|
</thead>
|
||||||
|
<tbody></tbody>
|
||||||
|
</table>
|
||||||
|
</div>
|
||||||
|
</main>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<!-- Add/Edit Backend Modal -->
|
||||||
|
<div class="modal-overlay" id="backend-modal">
|
||||||
|
<div class="modal">
|
||||||
|
<h3 id="modal-title">Add Provider</h3>
|
||||||
|
<form id="backend-form" onsubmit="saveBackend(event)">
|
||||||
|
<input type="hidden" id="backend-id">
|
||||||
|
<div class="form-row">
|
||||||
|
<div class="form-group">
|
||||||
|
<label>Name *</label>
|
||||||
|
<input type="text" id="backend-name" placeholder="e.g. NVIDIA H100 Primary" required>
|
||||||
|
</div>
|
||||||
|
<div class="form-group">
|
||||||
|
<label>Label</label>
|
||||||
|
<input type="text" id="backend-label" placeholder="e.g. nvidia, siliconflow">
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<div class="form-group">
|
||||||
|
<label>API Base URL *</label>
|
||||||
|
<input type="url" id="backend-url" placeholder="https://integrate.api.nvidia.com/v1" required>
|
||||||
|
</div>
|
||||||
|
<div class="form-group">
|
||||||
|
<label>API Key *</label>
|
||||||
|
<input type="password" id="backend-key" placeholder="sk-..." required>
|
||||||
|
</div>
|
||||||
|
<div class="form-row">
|
||||||
|
<div class="form-group">
|
||||||
|
<label>Pool</label>
|
||||||
|
<select id="backend-pool">
|
||||||
|
<option value="primary">Primary</option>
|
||||||
|
<option value="fallback">Fallback</option>
|
||||||
|
</select>
|
||||||
|
</div>
|
||||||
|
<div class="form-group">
|
||||||
|
<label>RPM Limit</label>
|
||||||
|
<input type="number" id="backend-rpm" value="40" min="1" max="1000">
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<div class="form-row">
|
||||||
|
<div class="form-group">
|
||||||
|
<label>Timeout (seconds)</label>
|
||||||
|
<input type="number" id="backend-timeout" value="120" min="10" max="600">
|
||||||
|
</div>
|
||||||
|
<div class="form-group">
|
||||||
|
<label>Enabled</label>
|
||||||
|
<select id="backend-enabled">
|
||||||
|
<option value="true">Yes</option>
|
||||||
|
<option value="false">No</option>
|
||||||
|
</select>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<div class="form-group">
|
||||||
|
<label>Model Mappings (JSON: canonical → {native_id, cost, ...})</label>
|
||||||
|
<textarea id="backend-mappings" placeholder='{"deepseek-ai/DeepSeek-V4-Pro":{"native_id":"deepseek-ai/deepseek-v4-pro","cost":{"input":0.000001,"output":0.000004}}}'></textarea>
|
||||||
|
</div>
|
||||||
|
<div class="form-actions">
|
||||||
|
<button type="button" class="btn btn-outline" onclick="closeModal()">Cancel</button>
|
||||||
|
<button type="submit" class="btn btn-primary">Save</button>
|
||||||
|
</div>
|
||||||
|
</form>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<script>
|
||||||
|
// ── Navigation ──
|
||||||
|
document.querySelectorAll('.sidebar nav a').forEach(a => {
|
||||||
|
a.addEventListener('click', e => {
|
||||||
|
e.preventDefault();
|
||||||
|
document.querySelectorAll('.sidebar nav a').forEach(l => l.classList.remove('active'));
|
||||||
|
a.classList.add('active');
|
||||||
|
document.querySelectorAll('.page').forEach(p => p.classList.remove('active'));
|
||||||
|
document.getElementById('page-' + a.dataset.page).classList.add('active');
|
||||||
|
loadPage(a.dataset.page);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
// ── SSE Connection ──
|
||||||
|
const sse = new EventSource('/dashboard/sse');
|
||||||
|
sse.onmessage = e => {
|
||||||
|
const data = JSON.parse(e.data);
|
||||||
|
if (data.type === 'snapshot') updateDashboard(data);
|
||||||
|
};
|
||||||
|
|
||||||
|
sse.onerror = () => {
|
||||||
|
document.getElementById('status-bar').textContent = '⚠️ SSE Disconnected';
|
||||||
|
};
|
||||||
|
|
||||||
|
// ── Dashboard Update ──
|
||||||
|
let costChart = null, tokenChart = null;
|
||||||
|
|
||||||
|
function updateDashboard(data) {
|
||||||
|
document.getElementById('status-bar').textContent =
|
||||||
|
`⚡ Connected · Uptime ${formatDuration(data.uptime_seconds)}`;
|
||||||
|
|
||||||
|
// Stat cards
|
||||||
|
const st = data.total || {};
|
||||||
|
const errRate = st.total_requests > 0 ? ((st.total_errors || 0) / st.total_requests * 100).toFixed(1) : '0.0';
|
||||||
|
document.getElementById('stat-cards').innerHTML = `
|
||||||
|
<div class="card"><div class="label">Total Requests</div><div class="value">${fmt(st.total_requests)}</div><div class="sub">Error rate: ${errRate}%</div></div>
|
||||||
|
<div class="card"><div class="label">Total Tokens</div><div class="value">${fmt(st.total_tokens)}</div><div class="sub">Prompt: ${fmt(st.total_prompt_tokens)} · Completion: ${fmt(st.total_completion_tokens)}</div></div>
|
||||||
|
<div class="card"><div class="label">Total Cost</div><div class="value">$${st.total_cost ? st.total_cost.toFixed(4) : '0.0000'}</div><div class="sub">USD</div></div>
|
||||||
|
<div class="card"><div class="label">Uptime</div><div class="value">${formatDuration(data.uptime_seconds)}</div><div class="sub">Sidecar V2</div></div>
|
||||||
|
`;
|
||||||
|
|
||||||
|
// Pool grid
|
||||||
|
let poolHTML = '';
|
||||||
|
for (const [pool, ps] of Object.entries(data.pool || {})) {
|
||||||
|
poolHTML += `
|
||||||
|
<div class="pool-card">
|
||||||
|
<h3 class="${pool}">${pool}</h3>
|
||||||
|
<div class="pool-stats">
|
||||||
|
<div class="pool-stat total"><div class="num">${ps.total}</div><div class="lbl">Total</div></div>
|
||||||
|
<div class="pool-stat healthy"><div class="num">${ps.healthy}</div><div class="lbl">Healthy</div></div>
|
||||||
|
<div class="pool-stat cooling"><div class="num">${ps.cooling}</div><div class="lbl">Cooling</div></div>
|
||||||
|
<div class="pool-stat error"><div class="num">${ps.error}</div><div class="lbl">Error</div></div>
|
||||||
|
</div>
|
||||||
|
</div>`;
|
||||||
|
}
|
||||||
|
document.getElementById('pool-grid').innerHTML = poolHTML || '<div class="card">No pools configured</div>';
|
||||||
|
|
||||||
|
// Update backend table if on providers page
|
||||||
|
if (document.getElementById('page-providers').classList.contains('active')) {
|
||||||
|
renderBackendsTable(data.backends || []);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// ── Chart Updates (use SSE data to build chart data) ──
|
||||||
|
function initCharts() {
|
||||||
|
const cc = document.getElementById('cost-chart');
|
||||||
|
const tc = document.getElementById('token-chart');
|
||||||
|
if (!cc || !tc) return;
|
||||||
|
|
||||||
|
if (costChart) costChart.destroy();
|
||||||
|
if (tokenChart) tokenChart.destroy();
|
||||||
|
|
||||||
|
costChart = new Chart(cc, {
|
||||||
|
type: 'line', data: { labels: [], datasets: [{ label: 'Cost (USD)', data: [], borderColor: '#00d1b2', backgroundColor: 'rgba(0,209,178,0.1)', fill: true, tension: 0.3 }] },
|
||||||
|
options: { responsive: true, maintainAspectRatio: true, plugins: { legend: { labels: { color: '#888' } } }, scales: { x: { ticks: { color: '#888', maxTicksLimit: 12 } }, y: { ticks: { color: '#888' } } } }
|
||||||
|
});
|
||||||
|
|
||||||
|
tokenChart = new Chart(tc, {
|
||||||
|
type: 'line', data: { labels: [], datasets: [{ label: 'Total Tokens', data: [], borderColor: '#b86bff', backgroundColor: 'rgba(184,107,255,0.1)', fill: true, tension: 0.3 }] },
|
||||||
|
options: { responsive: true, maintainAspectRatio: true, plugins: { legend: { labels: { color: '#888' } } }, scales: { x: { ticks: { color: '#888', maxTicksLimit: 12 } }, y: { ticks: { color: '#888' } } } }
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
// ── Providers Page ──
|
||||||
|
function renderBackendsTable(backends) {
|
||||||
|
const tbody = document.querySelector('#backends-table tbody');
|
||||||
|
tbody.innerHTML = backends.map(b => `
|
||||||
|
<tr>
|
||||||
|
<td><strong>${h(b.name)}</strong></td>
|
||||||
|
<td><span class="badge ${b.label ? 'primary' : ''}">${h(b.label || '-')}</span></td>
|
||||||
|
<td><span class="badge ${b.pool}">${b.pool}</span></td>
|
||||||
|
<td><span class="badge ${b.status}">${b.status}</span></td>
|
||||||
|
<td>${b.rpm_limit}</td>
|
||||||
|
<td>${b.model_count || 0}</td>
|
||||||
|
<td>
|
||||||
|
<button class="btn btn-outline btn-sm" onclick="editBackend('${b.id}')">Edit</button>
|
||||||
|
<button class="btn btn-danger btn-sm" onclick="deleteBackend('${b.id}')">Del</button>
|
||||||
|
</td>
|
||||||
|
</tr>`).join('');
|
||||||
|
}
|
||||||
|
|
||||||
|
function showAddBackend() {
|
||||||
|
document.getElementById('modal-title').textContent = 'Add Provider';
|
||||||
|
document.getElementById('backend-id').value = '';
|
||||||
|
document.getElementById('backend-name').value = '';
|
||||||
|
document.getElementById('backend-label').value = '';
|
||||||
|
document.getElementById('backend-url').value = '';
|
||||||
|
document.getElementById('backend-key').value = '';
|
||||||
|
document.getElementById('backend-pool').value = 'primary';
|
||||||
|
document.getElementById('backend-rpm').value = '40';
|
||||||
|
document.getElementById('backend-timeout').value = '120';
|
||||||
|
document.getElementById('backend-enabled').value = 'true';
|
||||||
|
document.getElementById('backend-mappings').value = '{}';
|
||||||
|
document.getElementById('backend-modal').classList.add('active');
|
||||||
|
}
|
||||||
|
|
||||||
|
async function editBackend(id) {
|
||||||
|
try {
|
||||||
|
const res = await fetch('/api/admin/backends/' + id);
|
||||||
|
const b = await res.json();
|
||||||
|
document.getElementById('modal-title').textContent = 'Edit Provider';
|
||||||
|
document.getElementById('backend-id').value = b.id;
|
||||||
|
document.getElementById('backend-name').value = b.name;
|
||||||
|
document.getElementById('backend-label').value = b.label || '';
|
||||||
|
document.getElementById('backend-url').value = b.api_base_url;
|
||||||
|
document.getElementById('backend-key').value = '';
|
||||||
|
document.getElementById('backend-key').placeholder = '(leave blank to keep current)';
|
||||||
|
document.getElementById('backend-key').required = false;
|
||||||
|
document.getElementById('backend-pool').value = b.pool;
|
||||||
|
document.getElementById('backend-rpm').value = b.rpm_limit;
|
||||||
|
document.getElementById('backend-timeout').value = b.timeout_seconds;
|
||||||
|
document.getElementById('backend-enabled').value = b.enabled ? 'true' : 'false';
|
||||||
|
document.getElementById('backend-mappings').value = JSON.stringify(b.model_mappings || {}, null, 2);
|
||||||
|
document.getElementById('backend-modal').classList.add('active');
|
||||||
|
} catch (e) { alert('Failed to load backend: ' + e.message); }
|
||||||
|
}
|
||||||
|
|
||||||
|
async function saveBackend(e) {
|
||||||
|
e.preventDefault();
|
||||||
|
const id = document.getElementById('backend-id').value;
|
||||||
|
const body = {
|
||||||
|
name: document.getElementById('backend-name').value,
|
||||||
|
label: document.getElementById('backend-label').value,
|
||||||
|
api_base_url: document.getElementById('backend-url').value,
|
||||||
|
pool: document.getElementById('backend-pool').value,
|
||||||
|
rpm_limit: parseInt(document.getElementById('backend-rpm').value),
|
||||||
|
timeout_seconds: parseInt(document.getElementById('backend-timeout').value),
|
||||||
|
enabled: document.getElementById('backend-enabled').value === 'true',
|
||||||
|
model_mappings: JSON.parse(document.getElementById('backend-mappings').value || '{}'),
|
||||||
|
};
|
||||||
|
|
||||||
|
const key = document.getElementById('backend-key').value;
|
||||||
|
if (key) body.api_key = key;
|
||||||
|
|
||||||
|
try {
|
||||||
|
const method = id ? 'PUT' : 'POST';
|
||||||
|
const url = id ? '/api/admin/backends/' + id : '/api/admin/backends';
|
||||||
|
const res = await fetch(url, { method, headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
|
||||||
|
if (!res.ok) throw new Error((await res.json()).detail || 'Save failed');
|
||||||
|
closeModal();
|
||||||
|
refreshAll();
|
||||||
|
} catch (e) { alert('Error: ' + e.message); }
|
||||||
|
}
|
||||||
|
|
||||||
|
async function deleteBackend(id) {
|
||||||
|
if (!confirm('Delete this provider? This cannot be undone.')) return;
|
||||||
|
try {
|
||||||
|
await fetch('/api/admin/backends/' + id, { method: 'DELETE' });
|
||||||
|
refreshAll();
|
||||||
|
} catch (e) { alert('Delete failed: ' + e.message); }
|
||||||
|
}
|
||||||
|
|
||||||
|
function closeModal() { document.getElementById('backend-modal').classList.remove('active'); }
|
||||||
|
|
||||||
|
// ── Load Pages ──
|
||||||
|
async function loadPage(page) {
|
||||||
|
if (page === 'dashboard') {
|
||||||
|
initCharts();
|
||||||
|
loadChartData();
|
||||||
|
} else if (page === 'providers') {
|
||||||
|
refreshAll();
|
||||||
|
} else if (page === 'usage') {
|
||||||
|
loadUsageFilter();
|
||||||
|
loadUsage();
|
||||||
|
loadDaily();
|
||||||
|
} else if (page === 'cooldown') {
|
||||||
|
loadCooldown();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
async function refreshAll() {
|
||||||
|
try {
|
||||||
|
const res = await fetch('/api/admin/backends');
|
||||||
|
const backends = await res.json();
|
||||||
|
renderBackendsTable(backends);
|
||||||
|
} catch (e) { console.error(e); }
|
||||||
|
}
|
||||||
|
|
||||||
|
async function loadUsageFilter() {
|
||||||
|
try {
|
||||||
|
const res = await fetch('/api/admin/backends');
|
||||||
|
const backends = await res.json();
|
||||||
|
const sel = document.getElementById('usage-backend-filter');
|
||||||
|
sel.innerHTML = '<option value="">All Backends</option>' +
|
||||||
|
backends.map(b => `<option value="${b.id}">${h(b.name)}</option>`).join('');
|
||||||
|
} catch (e) {}
|
||||||
|
}
|
||||||
|
|
||||||
|
async function loadUsage() {
|
||||||
|
const sel = document.getElementById('usage-backend-filter');
|
||||||
|
const backendId = sel.value;
|
||||||
|
const url = backendId ? `/api/admin/stats/hourly?backend_id=${backendId}&hours=72` : '/api/admin/stats/hourly?hours=72';
|
||||||
|
try {
|
||||||
|
const res = await fetch(url);
|
||||||
|
const data = await res.json();
|
||||||
|
const tbody = document.querySelector('#usage-table tbody');
|
||||||
|
tbody.innerHTML = data.map(r => `
|
||||||
|
<tr>
|
||||||
|
<td>${r.hour_bucket}</td>
|
||||||
|
<td>${r.backend_id}</td>
|
||||||
|
<td>${h(r.model)}</td>
|
||||||
|
<td>${fmt(r.request_count)}</td>
|
||||||
|
<td class="${r.error_count > 0 ? 'text-red' : 'text-green'}">${r.error_count}</td>
|
||||||
|
<td>${fmt(r.total_tokens)}</td>
|
||||||
|
<td>$${(r.cost || 0).toFixed(6)}</td>
|
||||||
|
<td>${r.avg_latency_ms}ms</td>
|
||||||
|
</tr>`).join('');
|
||||||
|
} catch (e) { console.error(e); }
|
||||||
|
}
|
||||||
|
|
||||||
|
async function loadDaily() {
|
||||||
|
try {
|
||||||
|
const res = await fetch('/api/admin/stats/daily?days=30');
|
||||||
|
const data = await res.json();
|
||||||
|
const tbody = document.querySelector('#daily-table tbody');
|
||||||
|
tbody.innerHTML = data.map(r => `
|
||||||
|
<tr>
|
||||||
|
<td>${r.date}</td>
|
||||||
|
<td><span class="badge ${r.pool}">${r.pool}</span></td>
|
||||||
|
<td>${fmt(r.total_requests)}</td>
|
||||||
|
<td>${fmt(r.total_errors)}</td>
|
||||||
|
<td>${fmt(r.total_tokens)}</td>
|
||||||
|
<td>$${(r.total_cost || 0).toFixed(6)}</td>
|
||||||
|
<td>${r.unique_backends}</td>
|
||||||
|
</tr>`).join('');
|
||||||
|
} catch (e) { console.error(e); }
|
||||||
|
}
|
||||||
|
|
||||||
|
async function loadCooldown() {
|
||||||
|
try {
|
||||||
|
const res = await fetch('/api/admin/stats/cooldown?limit=100');
|
||||||
|
const data = await res.json();
|
||||||
|
const tbody = document.querySelector('#cooldown-table tbody');
|
||||||
|
tbody.innerHTML = data.map(r => `
|
||||||
|
<tr>
|
||||||
|
<td>${r.started_at}</td>
|
||||||
|
<td>${r.backend_id}</td>
|
||||||
|
<td>${r.consecutive_count}</td>
|
||||||
|
<td>${r.cooldown_seconds}s</td>
|
||||||
|
<td>${h(r.response_summary)}</td>
|
||||||
|
</tr>`).join('');
|
||||||
|
} catch (e) { console.error(e); }
|
||||||
|
}
|
||||||
|
|
||||||
|
async function loadChartData() {
|
||||||
|
try {
|
||||||
|
const res = await fetch('/api/admin/stats/hourly?hours=168');
|
||||||
|
const data = await res.json();
|
||||||
|
// Group by hour, sum
|
||||||
|
const byHour = {};
|
||||||
|
data.forEach(r => {
|
||||||
|
const hour = r.hour_bucket.slice(0, 13);
|
||||||
|
if (!byHour[hour]) byHour[hour] = { cost: 0, tokens: 0 };
|
||||||
|
byHour[hour].cost += (r.cost || 0);
|
||||||
|
byHour[hour].tokens += (r.total_tokens || 0);
|
||||||
|
});
|
||||||
|
const hours = Object.keys(byHour).sort();
|
||||||
|
const costs = hours.map(h => byHour[h].cost);
|
||||||
|
const tokens = hours.map(h => byHour[h].tokens);
|
||||||
|
const labels = hours.map(h => h.slice(11, 16) + ' ' + h.slice(5, 10));
|
||||||
|
|
||||||
|
if (costChart) {
|
||||||
|
costChart.data.labels = labels;
|
||||||
|
costChart.data.datasets[0].data = costs;
|
||||||
|
costChart.update();
|
||||||
|
}
|
||||||
|
if (tokenChart) {
|
||||||
|
tokenChart.data.labels = labels;
|
||||||
|
tokenChart.data.datasets[0].data = tokens;
|
||||||
|
tokenChart.update();
|
||||||
|
}
|
||||||
|
} catch (e) { console.error(e); }
|
||||||
|
}
|
||||||
|
|
||||||
|
// ── Helpers ──
|
||||||
|
function fmt(n) { return (n || 0).toLocaleString(); }
|
||||||
|
function h(s) { const d=document.createElement('div'); d.textContent=s||''; return d.innerHTML; }
|
||||||
|
function formatDuration(s) {
|
||||||
|
const d = Math.floor(s / 86400);
|
||||||
|
const h = Math.floor((s % 86400) / 3600);
|
||||||
|
const m = Math.floor((s % 3600) / 60);
|
||||||
|
const parts = [];
|
||||||
|
if (d) parts.push(d + 'd');
|
||||||
|
if (h) parts.push(h + 'h');
|
||||||
|
if (m || !parts.length) parts.push(m + 'm');
|
||||||
|
return parts.join(' ');
|
||||||
|
}
|
||||||
|
|
||||||
|
// Initial load
|
||||||
|
document.addEventListener('DOMContentLoaded', () => {
|
||||||
|
// Ensure chart containers exist
|
||||||
|
if (!document.getElementById('cost-chart')) {
|
||||||
|
const chartsDiv = document.getElementById('charts');
|
||||||
|
if (chartsDiv) {
|
||||||
|
chartsDiv.innerHTML = `
|
||||||
|
<div class="chart-card"><h3>Cost Over Time</h3><canvas id="cost-chart"></canvas></div>
|
||||||
|
<div class="chart-card"><h3>Token Usage Over Time</h3><canvas id="token-chart"></canvas></div>`;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
initCharts();
|
||||||
|
loadChartData();
|
||||||
|
});
|
||||||
|
</script>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
@@ -0,0 +1,90 @@
|
|||||||
|
# Sidecar V2 — API Key Encryption Rotation SOP
|
||||||
|
|
||||||
|
> 版本: v1.0 | 维护者: 严维序 (opengineer)
|
||||||
|
|
||||||
|
## 背景
|
||||||
|
|
||||||
|
Sidecar V2 使用 AES-256-GCM 加密存储所有 Provider 的 API Key。加密密钥通过 `SIDECAR_ENCRYPTION_KEY` 环境变量传入，启动时通过 `init_crypto()` 初始化。
|
||||||
|
|
||||||
|
## ⚠️ 关键警告
|
||||||
|
|
||||||
|
**更换 SIDECAR_ENCRYPTION_KEY 会导致所有已存储的 API Key 永久不可恢复！**
|
||||||
|
|
||||||
|
`crypto.py` 的 `try_decrypt_existing()` 在密钥变更时会静默返回 `None`，已有加密数据将无法解密。请在轮换密钥前执行以下步骤。
|
||||||
|
|
||||||
|
## 安全轮换步骤
|
||||||
|
|
||||||
|
### Step 1: 导出当前 API Key 明文（必须）
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 使用旧密钥启动 sidecar，通过 admin API 导出
|
||||||
|
curl -s -H "Authorization: Bearer <ADMIN_TOKEN>" \
|
||||||
|
http://127.0.0.1:9190/api/admin/backends | \
|
||||||
|
python3 -c "
|
||||||
|
import json, sys
|
||||||
|
data = json.load(sys.stdin)
|
||||||
|
# 注意：api_key 是 masked 的，需要重新从安全渠道获取原始 key
|
||||||
|
print(json.dumps(data, indent=2))
|
||||||
|
"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2: 停止服务
|
||||||
|
|
||||||
|
```bash
|
||||||
|
systemctl stop sidecar-v2
|
||||||
|
# 或
|
||||||
|
docker compose down
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3: 备份数据库
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp /app/data/sidecar_v2.db /app/data/backups/pre-rotation-$(date +%Y%m%d_%H%M%S).db
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4: 更新密钥
|
||||||
|
|
||||||
|
更新 `/etc/sidecar-v2/env` 或 docker `.env` 文件中的 `SIDECAR_ENCRYPTION_KEY`：
|
||||||
|
|
||||||
|
```
|
||||||
|
SIDECAR_ENCRYPTION_KEY=<new_64_hex_char_key>
|
||||||
|
```
|
||||||
|
|
||||||
|
生成新密钥：
|
||||||
|
```bash
|
||||||
|
python3 -c "import secrets; print(secrets.token_hex(32))"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 5: 清空加密 Key 并重新录入
|
||||||
|
|
||||||
|
由于密钥变更后旧加密数据不可读，需要：
|
||||||
|
|
||||||
|
1. 启动服务（此时所有旧 Provider 的 API Key 不可用）
|
||||||
|
2. 通过 Admin API 重新录入所有 Provider 的 API Key：
|
||||||
|
```bash
|
||||||
|
curl -s -X PUT -H "Authorization: Bearer <ADMIN_TOKEN>" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"api_key": "<NEW_PLAIN_KEY>"}' \
|
||||||
|
http://127.0.0.1:9190/api/admin/backends/<backend_id>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 6: 验证
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 确认 Provider 状态为 healthy
|
||||||
|
curl -s http://127.0.0.1:9190/api/admin/pools
|
||||||
|
# 发送测试请求
|
||||||
|
curl -s -X POST http://127.0.0.1:9190/v1/chat/completions \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"model":"<model_name>","messages":[{"role":"user","content":"test"}],"max_tokens":5}'
|
||||||
|
```
|
||||||
|
|
||||||
|
## 应急预案
|
||||||
|
|
||||||
|
如果在密钥轮换过程中出错：
|
||||||
|
|
||||||
|
1. 恢复旧密钥环境变量
|
||||||
|
2. 恢复旧数据库备份
|
||||||
|
3. 重启服务
|
||||||
|
|
||||||
|
旧 Key 会正常工作，因为未被覆盖的数据仍然用旧密钥加密。
|
||||||
@@ -0,0 +1,56 @@
|
|||||||
|
# Sidecar V2 — Nginx reverse proxy config (reference)
|
||||||
|
# Place at /etc/nginx/sites-available/sidecar-v2.conf
|
||||||
|
# SSL certs managed by certbot or manually
|
||||||
|
|
||||||
|
upstream sidecar_v2_main {
|
||||||
|
server 127.0.0.1:9190;
|
||||||
|
}
|
||||||
|
|
||||||
|
upstream sidecar_v2_metrics {
|
||||||
|
server 127.0.0.1:9191;
|
||||||
|
}
|
||||||
|
|
||||||
|
server {
|
||||||
|
listen 443 ssl http2;
|
||||||
|
server_name sidecar.example.com;
|
||||||
|
|
||||||
|
ssl_certificate /etc/ssl/certs/sidecar.pem;
|
||||||
|
ssl_certificate_key /etc/ssl/private/sidecar.key;
|
||||||
|
|
||||||
|
# Dashboard + Admin API (main port)
|
||||||
|
location / {
|
||||||
|
proxy_pass http://sidecar_v2_main;
|
||||||
|
proxy_http_version 1.1;
|
||||||
|
proxy_set_header Host $host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
proxy_set_header X-Forwarded-Proto $scheme;
|
||||||
|
}
|
||||||
|
|
||||||
|
# SSE support for dashboard real-time data
|
||||||
|
location /dashboard/sse {
|
||||||
|
proxy_pass http://sidecar_v2_main;
|
||||||
|
proxy_http_version 1.1;
|
||||||
|
proxy_set_header Connection "";
|
||||||
|
proxy_set_header Host $host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
proxy_buffering off;
|
||||||
|
proxy_cache off;
|
||||||
|
chunked_transfer_encoding off;
|
||||||
|
proxy_read_timeout 86400s;
|
||||||
|
}
|
||||||
|
|
||||||
|
# Prometheus metrics
|
||||||
|
location /metrics {
|
||||||
|
proxy_pass http://sidecar_v2_metrics;
|
||||||
|
proxy_http_version 1.1;
|
||||||
|
proxy_set_header Host $host;
|
||||||
|
}
|
||||||
|
|
||||||
|
# Health check
|
||||||
|
location /health {
|
||||||
|
proxy_pass http://sidecar_v2_main;
|
||||||
|
proxy_http_version 1.1;
|
||||||
|
proxy_set_header Host $host;
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,23 @@
|
|||||||
|
[Unit]
|
||||||
|
Description=Sidecar V2 — Multi-Pool Provider Proxy
|
||||||
|
After=network.target
|
||||||
|
|
||||||
|
[Service]
|
||||||
|
Type=simple
|
||||||
|
User=openclaw
|
||||||
|
Group=openclaw
|
||||||
|
WorkingDirectory=/opt/sidecar-v2
|
||||||
|
EnvironmentFile=/etc/sidecar-v2/env
|
||||||
|
ExecStart=/opt/sidecar-v2/.venv/bin/python3 main.py
|
||||||
|
Restart=always
|
||||||
|
RestartSec=5
|
||||||
|
|
||||||
|
# Security hardening
|
||||||
|
NoNewPrivileges=yes
|
||||||
|
ProtectSystem=strict
|
||||||
|
ProtectHome=yes
|
||||||
|
ReadWritePaths=/opt/sidecar-v2/data
|
||||||
|
PrivateTmp=yes
|
||||||
|
|
||||||
|
[Install]
|
||||||
|
WantedBy=multi-user.target
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
# Sidecar V2 — Multi-Pool Provider Proxy
|
||||||
|
version: "3.9"
|
||||||
|
|
||||||
|
services:
|
||||||
|
sidecar-v2:
|
||||||
|
build: .
|
||||||
|
container_name: sidecar-v2
|
||||||
|
restart: unless-stopped
|
||||||
|
ports:
|
||||||
|
- "9190:9190" # Main proxy + admin API + dashboard
|
||||||
|
- "9191:9191" # Prometheus metrics
|
||||||
|
environment:
|
||||||
|
- SIDECAR_ENCRYPTION_KEY=${SIDECAR_ENCRYPTION_KEY}
|
||||||
|
- SIDECAR_ADMIN_TOKEN=${SIDECAR_ADMIN_TOKEN:-change-me}
|
||||||
|
- LOG_FORMAT=${LOG_FORMAT:-json}
|
||||||
|
- SIDECAR_HOST=0.0.0.0
|
||||||
|
- SIDECAR_PORT=9190
|
||||||
|
- SIDECAR_METRICS_PORT=9191
|
||||||
|
- SIDECAR_DB_PATH=/app/data/sidecar_v2.db
|
||||||
|
- SIDECAR_BACKUP_DIR=/app/data/backups
|
||||||
|
volumes:
|
||||||
|
- sidecar-data:/app/data
|
||||||
|
|
||||||
|
volumes:
|
||||||
|
sidecar-data:
|
||||||
|
driver: local
|
||||||
@@ -0,0 +1,17 @@
|
|||||||
|
"""Sidecar V2 entry point."""
|
||||||
|
|
||||||
|
import uvicorn
|
||||||
|
from config import config
|
||||||
|
|
||||||
|
|
||||||
|
def main():
|
||||||
|
uvicorn.run(
|
||||||
|
"server:app",
|
||||||
|
host=config.host,
|
||||||
|
port=config.port,
|
||||||
|
log_level=config.log_level.lower(),
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
@@ -0,0 +1,83 @@
|
|||||||
|
"""Provider pool management: primary / fallback pool routing."""
|
||||||
|
|
||||||
|
import structlog
|
||||||
|
from typing import Optional
|
||||||
|
|
||||||
|
from storage.backend_store import list_backends, get_pool_stats
|
||||||
|
from storage.models import Backend
|
||||||
|
|
||||||
|
logger = structlog.get_logger("sidecar_v2.pool_manager")
|
||||||
|
|
||||||
|
|
||||||
|
class PoolManager:
|
||||||
|
"""Manages provider pools and selects healthy backends for a given model.
|
||||||
|
|
||||||
|
Priority: primary pool → fallback pool.
|
||||||
|
Within a pool: healthy backends only, sorted by availability.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self):
|
||||||
|
self._pool_order = ["primary", "fallback"]
|
||||||
|
|
||||||
|
def get_available_backends(
|
||||||
|
self, canonical_model: str, pool: Optional[str] = None
|
||||||
|
) -> list[Backend]:
|
||||||
|
"""Get all healthy, enabled backends that serve a model, in pool order.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
canonical_model: Canonical model name to match.
|
||||||
|
pool: Optional pool filter (primary/fallback). None = all pools.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
List of ready backends sorted by pool priority, then RPM utilization.
|
||||||
|
"""
|
||||||
|
backends: list[Backend] = []
|
||||||
|
|
||||||
|
pools_to_check = [pool] if pool else self._pool_order
|
||||||
|
for p in pools_to_check:
|
||||||
|
pool_backends = list_backends(pool=p, enabled_only=True, decrypt_key=True)
|
||||||
|
for b in pool_backends:
|
||||||
|
if b.status == "healthy" and b.has_model(canonical_model):
|
||||||
|
backends.append(b)
|
||||||
|
if pool:
|
||||||
|
break
|
||||||
|
|
||||||
|
return backends
|
||||||
|
|
||||||
|
def get_any_healthy_backends(self, pool: Optional[str] = None) -> list[Backend]:
|
||||||
|
"""Get all healthy, enabled backends regardless of model."""
|
||||||
|
backends: list[Backend] = []
|
||||||
|
pools_to_check = [pool] if pool else self._pool_order
|
||||||
|
for p in pools_to_check:
|
||||||
|
pool_backends = list_backends(pool=p, enabled_only=True, decrypt_key=True)
|
||||||
|
for b in pool_backends:
|
||||||
|
if b.status == "healthy":
|
||||||
|
backends.append(b)
|
||||||
|
if pool:
|
||||||
|
break
|
||||||
|
return backends
|
||||||
|
|
||||||
|
def get_pool_status(self) -> dict:
|
||||||
|
"""Get pool summary for dashboard."""
|
||||||
|
stats = get_pool_stats()
|
||||||
|
result = {}
|
||||||
|
for pool in self._pool_order:
|
||||||
|
s = stats.get(pool, {"total": 0, "enabled": 0, "healthy": 0, "cooling": 0, "error": 0})
|
||||||
|
result[pool] = s
|
||||||
|
# Also include any other pools
|
||||||
|
for pool, s in stats.items():
|
||||||
|
if pool not in result:
|
||||||
|
result[pool] = s
|
||||||
|
return result
|
||||||
|
|
||||||
|
def is_pool_available(self, canonical_model: str, pool: str = "primary") -> bool:
|
||||||
|
"""Check if a pool has any healthy backends for a model."""
|
||||||
|
backends = self.get_available_backends(canonical_model, pool=pool)
|
||||||
|
return len(backends) > 0
|
||||||
|
|
||||||
|
def is_any_pool_available(self, canonical_model: str) -> bool:
|
||||||
|
"""Check if any pool has healthy backends for a model."""
|
||||||
|
for pool in self._pool_order:
|
||||||
|
if self.is_pool_available(canonical_model, pool):
|
||||||
|
return True
|
||||||
|
return False
|
||||||
@@ -0,0 +1,383 @@
|
|||||||
|
"""Proxy request handling for Sidecar V2 — multi-pool routing + cooldown + rate limiting."""
|
||||||
|
|
||||||
|
import asyncio
|
||||||
|
import json
|
||||||
|
import time
|
||||||
|
from typing import Any, Optional
|
||||||
|
|
||||||
|
import httpx
|
||||||
|
import structlog
|
||||||
|
from fastapi import Request
|
||||||
|
from fastapi.responses import JSONResponse, Response, StreamingResponse
|
||||||
|
|
||||||
|
from config import config
|
||||||
|
from pool_manager import PoolManager
|
||||||
|
from rate_limiter import PerBackendRateLimiter
|
||||||
|
from router import Router
|
||||||
|
from cooldown_manager import start_cooldown, check_and_clear_cooldown
|
||||||
|
from storage.models import Backend
|
||||||
|
from storage.usage_store import record_usage
|
||||||
|
|
||||||
|
# Emergency activation counter (read by metrics endpoint)
|
||||||
|
_emergency_count: int = 0
|
||||||
|
|
||||||
|
|
||||||
|
def get_emergency_count() -> int:
|
||||||
|
return _emergency_count
|
||||||
|
|
||||||
|
|
||||||
|
logger: structlog.stdlib.BoundLogger = structlog.get_logger("sidecar_v2.proxy")
|
||||||
|
|
||||||
|
|
||||||
|
def extract_model(body: dict[str, Any]) -> str:
|
||||||
|
"""Extract model identifier from request body."""
|
||||||
|
return str(body.get("model", "unknown"))
|
||||||
|
|
||||||
|
|
||||||
|
def build_error_response(status: int, message: str, error_type: str = "") -> JSONResponse:
|
||||||
|
"""Build a standard error response."""
|
||||||
|
return JSONResponse(
|
||||||
|
status_code=status,
|
||||||
|
content={
|
||||||
|
"error": {
|
||||||
|
"message": message,
|
||||||
|
"type": error_type or f"Error_{status}",
|
||||||
|
}
|
||||||
|
},
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
async def forward_to_backend(
|
||||||
|
backend: Backend,
|
||||||
|
method: str,
|
||||||
|
path: str,
|
||||||
|
body: bytes | None,
|
||||||
|
headers: dict[str, str],
|
||||||
|
stream: bool = False,
|
||||||
|
) -> httpx.Response:
|
||||||
|
"""Forward a request to a specific backend."""
|
||||||
|
upstream_url = backend.api_base_url.rstrip("/") + path
|
||||||
|
|
||||||
|
forward_headers = {
|
||||||
|
k: v
|
||||||
|
for k, v in headers.items()
|
||||||
|
if k.lower() not in ("host", "content-length", "transfer-encoding")
|
||||||
|
}
|
||||||
|
|
||||||
|
if backend.api_key_plain:
|
||||||
|
forward_headers["authorization"] = f"Bearer {backend.api_key_plain}"
|
||||||
|
elif "authorization" not in {k.lower() for k in forward_headers}:
|
||||||
|
forward_headers["authorization"] = "Bearer nvidia"
|
||||||
|
|
||||||
|
timeout = httpx.Timeout(backend.timeout_seconds)
|
||||||
|
|
||||||
|
async with httpx.AsyncClient(timeout=timeout) as client:
|
||||||
|
req = client.build_request(
|
||||||
|
method=method,
|
||||||
|
url=upstream_url,
|
||||||
|
headers=forward_headers,
|
||||||
|
content=body,
|
||||||
|
)
|
||||||
|
return await client.send(req, stream=stream)
|
||||||
|
|
||||||
|
|
||||||
|
def build_response(resp: httpx.Response) -> Response:
|
||||||
|
"""Convert httpx.Response to FastAPI Response."""
|
||||||
|
content_type = resp.headers.get("content-type", "")
|
||||||
|
headers = {
|
||||||
|
k: v
|
||||||
|
for k, v in resp.headers.items()
|
||||||
|
if k.lower() not in ("content-encoding", "transfer-encoding")
|
||||||
|
}
|
||||||
|
|
||||||
|
is_sse = "text/event-stream" in content_type
|
||||||
|
is_chunked = resp.headers.get("transfer-encoding", "").lower() == "chunked"
|
||||||
|
if is_sse or (is_chunked and headers.get("content-type", "") != "application/octet-stream"):
|
||||||
|
return StreamingResponse(
|
||||||
|
content=resp.aiter_bytes(),
|
||||||
|
status_code=resp.status_code,
|
||||||
|
headers=headers,
|
||||||
|
media_type=content_type or "text/event-stream",
|
||||||
|
)
|
||||||
|
|
||||||
|
return Response(
|
||||||
|
content=resp.content,
|
||||||
|
status_code=resp.status_code,
|
||||||
|
headers=headers,
|
||||||
|
media_type=content_type or "application/json",
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def extract_usage_from_response(
|
||||||
|
resp: httpx.Response,
|
||||||
|
resp_json: dict[str, Any],
|
||||||
|
model: str,
|
||||||
|
) -> tuple[int, int, int]:
|
||||||
|
"""Extract token usage from response body (OpenAI-compatible)."""
|
||||||
|
usage = resp_json.get("usage", {})
|
||||||
|
prompt_tokens = usage.get("prompt_tokens", 0) or 0
|
||||||
|
completion_tokens = usage.get("completion_tokens", 0) or 0
|
||||||
|
|
||||||
|
# Try streaming chunks: aggregate from choices
|
||||||
|
if not prompt_tokens and not completion_tokens:
|
||||||
|
choices = resp_json.get("choices", [])
|
||||||
|
for choice in choices:
|
||||||
|
if isinstance(choice, dict):
|
||||||
|
tokens = choice.get("usage", {})
|
||||||
|
prompt_tokens += tokens.get("prompt_tokens", 0) or 0
|
||||||
|
completion_tokens += tokens.get("completion_tokens", 0) or 0
|
||||||
|
|
||||||
|
total_tokens = prompt_tokens + completion_tokens
|
||||||
|
if total_tokens == 0:
|
||||||
|
total_tokens = usage.get("total_tokens", 0) or 0
|
||||||
|
|
||||||
|
return prompt_tokens, completion_tokens, total_tokens
|
||||||
|
|
||||||
|
|
||||||
|
def calculate_cost(
|
||||||
|
backend: Backend,
|
||||||
|
model: str,
|
||||||
|
prompt_tokens: int,
|
||||||
|
completion_tokens: int,
|
||||||
|
) -> float:
|
||||||
|
"""Calculate cost using backend's model pricing."""
|
||||||
|
cost_info = backend.get_model_cost(model)
|
||||||
|
input_cost = cost_info.get("input", 0.0)
|
||||||
|
output_cost = cost_info.get("output", 0.0)
|
||||||
|
# Costs are per token
|
||||||
|
return (prompt_tokens * input_cost + completion_tokens * output_cost)
|
||||||
|
|
||||||
|
|
||||||
|
async def handle_proxy_request(
|
||||||
|
pool_manager: PoolManager,
|
||||||
|
rate_limiter: PerBackendRateLimiter,
|
||||||
|
router: Router,
|
||||||
|
request: Request,
|
||||||
|
path: str,
|
||||||
|
) -> Response:
|
||||||
|
"""Main proxy handler: multi-pool routing with cooldown and rate limiting.
|
||||||
|
|
||||||
|
Flow:
|
||||||
|
1. Extract model → canonical name
|
||||||
|
2. Pick backend via Router (primary → fallback)
|
||||||
|
3. Forward request
|
||||||
|
4. If 429 → cooldown backend, retry with another
|
||||||
|
5. If all pools exhausted → emergency mode
|
||||||
|
6. Track usage
|
||||||
|
"""
|
||||||
|
start_time = time.monotonic()
|
||||||
|
|
||||||
|
body_bytes: bytes = await request.body()
|
||||||
|
raw_headers: dict[str, str] = dict(request.headers)
|
||||||
|
|
||||||
|
body_json: dict[str, Any] = {}
|
||||||
|
try:
|
||||||
|
if body_bytes:
|
||||||
|
parsed = json.loads(body_bytes)
|
||||||
|
if isinstance(parsed, dict):
|
||||||
|
body_json = parsed
|
||||||
|
except (ValueError, TypeError):
|
||||||
|
body_json = {}
|
||||||
|
|
||||||
|
canonical_model = extract_model(body_json)
|
||||||
|
is_stream = body_json.get("stream", False)
|
||||||
|
|
||||||
|
# Try with pool routing
|
||||||
|
max_retries = config.max_pool_retries
|
||||||
|
for attempt in range(max_retries):
|
||||||
|
# Check and clear expired cooldowns before picking
|
||||||
|
_refresh_cooldowns()
|
||||||
|
|
||||||
|
backend = router.pick_backend(canonical_model)
|
||||||
|
if backend is None:
|
||||||
|
break # No backend available, fall through to emergency
|
||||||
|
|
||||||
|
try:
|
||||||
|
resp = await forward_to_backend(
|
||||||
|
backend=backend,
|
||||||
|
method=request.method,
|
||||||
|
path=path,
|
||||||
|
body=body_bytes if body_bytes else None,
|
||||||
|
headers=raw_headers,
|
||||||
|
stream=is_stream,
|
||||||
|
)
|
||||||
|
elapsed_ms = int((time.monotonic() - start_time) * 1000)
|
||||||
|
|
||||||
|
# Handle 429 — cooldown and retry
|
||||||
|
if resp.status_code == 429:
|
||||||
|
new_count = backend.consecutive_429_count + 1
|
||||||
|
start_cooldown(backend.id, new_count)
|
||||||
|
|
||||||
|
resp_body = ""
|
||||||
|
try:
|
||||||
|
resp_body = resp.text[:200]
|
||||||
|
except Exception:
|
||||||
|
pass
|
||||||
|
|
||||||
|
logger.warning(
|
||||||
|
"backend_429_cooldown",
|
||||||
|
backend_id=backend.id,
|
||||||
|
pool=backend.pool,
|
||||||
|
consecutive=new_count,
|
||||||
|
model=canonical_model,
|
||||||
|
)
|
||||||
|
|
||||||
|
# Track the error
|
||||||
|
record_usage(
|
||||||
|
backend_id=backend.id,
|
||||||
|
model=canonical_model,
|
||||||
|
prompt_tokens=0,
|
||||||
|
completion_tokens=0,
|
||||||
|
cost=0.0,
|
||||||
|
latency_ms=elapsed_ms,
|
||||||
|
is_error=True,
|
||||||
|
)
|
||||||
|
|
||||||
|
continue # Retry with another backend
|
||||||
|
|
||||||
|
# Success — track usage
|
||||||
|
resp_json: dict[str, Any] = {}
|
||||||
|
try:
|
||||||
|
if not is_stream and resp.content:
|
||||||
|
resp_json = json.loads(resp.content)
|
||||||
|
except (ValueError, TypeError):
|
||||||
|
pass
|
||||||
|
|
||||||
|
prompt_tokens, completion_tokens, total_tokens = extract_usage_from_response(
|
||||||
|
resp, resp_json, canonical_model
|
||||||
|
)
|
||||||
|
cost = calculate_cost(
|
||||||
|
backend, canonical_model, prompt_tokens, completion_tokens
|
||||||
|
)
|
||||||
|
|
||||||
|
record_usage(
|
||||||
|
backend_id=backend.id,
|
||||||
|
model=canonical_model,
|
||||||
|
prompt_tokens=prompt_tokens,
|
||||||
|
completion_tokens=completion_tokens,
|
||||||
|
cost=cost,
|
||||||
|
latency_ms=elapsed_ms,
|
||||||
|
)
|
||||||
|
|
||||||
|
logger.info(
|
||||||
|
"request_completed",
|
||||||
|
backend_id=backend.id,
|
||||||
|
pool=backend.pool,
|
||||||
|
model=canonical_model,
|
||||||
|
status=resp.status_code,
|
||||||
|
tokens=total_tokens,
|
||||||
|
cost=round(cost, 6),
|
||||||
|
elapsed_ms=elapsed_ms,
|
||||||
|
)
|
||||||
|
|
||||||
|
return build_response(resp)
|
||||||
|
|
||||||
|
except httpx.TimeoutException:
|
||||||
|
logger.warning(
|
||||||
|
"backend_timeout",
|
||||||
|
backend_id=backend.id,
|
||||||
|
model=canonical_model,
|
||||||
|
)
|
||||||
|
continue
|
||||||
|
except (httpx.ConnectError, httpx.RemoteProtocolError) as exc:
|
||||||
|
logger.warning(
|
||||||
|
"backend_connection_error",
|
||||||
|
backend_id=backend.id,
|
||||||
|
model=canonical_model,
|
||||||
|
error=str(exc),
|
||||||
|
)
|
||||||
|
continue
|
||||||
|
except Exception as exc:
|
||||||
|
logger.error(
|
||||||
|
"proxy_error",
|
||||||
|
backend_id=backend.id,
|
||||||
|
model=canonical_model,
|
||||||
|
error=str(exc),
|
||||||
|
)
|
||||||
|
continue
|
||||||
|
|
||||||
|
# All pools exhausted — emergency rate-limited passthrough
|
||||||
|
emergency_rpm = int(config.default_rpm_limit * config.emergency_rpm_fraction)
|
||||||
|
if emergency_rpm < 1:
|
||||||
|
emergency_rpm = 1
|
||||||
|
|
||||||
|
logger.warning(
|
||||||
|
"all_pools_exhausted_emergency",
|
||||||
|
model=canonical_model,
|
||||||
|
emergency_rpm=emergency_rpm,
|
||||||
|
)
|
||||||
|
|
||||||
|
# Track emergency activation for metrics
|
||||||
|
_emergency_count += 1
|
||||||
|
|
||||||
|
# Emergency: try to get a token from any fallback backend at reduced RPM
|
||||||
|
emergency_retries = 3
|
||||||
|
for attempt in range(emergency_retries):
|
||||||
|
backends = pool_manager.get_any_healthy_backends()
|
||||||
|
for backend in backends:
|
||||||
|
if rate_limiter.consume(backend.id, emergency_rpm):
|
||||||
|
try:
|
||||||
|
resp = await forward_to_backend(
|
||||||
|
backend=backend,
|
||||||
|
method=request.method,
|
||||||
|
path=path,
|
||||||
|
body=body_bytes if body_bytes else None,
|
||||||
|
headers=raw_headers,
|
||||||
|
stream=is_stream,
|
||||||
|
)
|
||||||
|
elapsed_ms = int((time.monotonic() - start_time) * 1000)
|
||||||
|
|
||||||
|
if resp.status_code == 429:
|
||||||
|
start_cooldown(backend.id, backend.consecutive_429_count + 1)
|
||||||
|
continue
|
||||||
|
|
||||||
|
# Success in emergency mode
|
||||||
|
try:
|
||||||
|
resp_json: dict[str, Any] = {}
|
||||||
|
if not is_stream and resp.content:
|
||||||
|
resp_json = json.loads(resp.content)
|
||||||
|
except Exception:
|
||||||
|
resp_json = {}
|
||||||
|
|
||||||
|
prompt_tokens, completion_tokens, total_tokens = extract_usage_from_response(
|
||||||
|
resp, resp_json, canonical_model
|
||||||
|
)
|
||||||
|
cost_em = calculate_cost(backend, canonical_model, prompt_tokens, completion_tokens)
|
||||||
|
|
||||||
|
record_usage(
|
||||||
|
backend_id=backend.id,
|
||||||
|
model=canonical_model,
|
||||||
|
prompt_tokens=prompt_tokens,
|
||||||
|
completion_tokens=completion_tokens,
|
||||||
|
cost=cost_em,
|
||||||
|
latency_ms=elapsed_ms,
|
||||||
|
)
|
||||||
|
|
||||||
|
logger.info(
|
||||||
|
"emergency_passthrough_success",
|
||||||
|
backend_id=backend.id,
|
||||||
|
model=canonical_model,
|
||||||
|
emergency_rpm=emergency_rpm,
|
||||||
|
)
|
||||||
|
return build_response(resp)
|
||||||
|
except Exception:
|
||||||
|
continue
|
||||||
|
|
||||||
|
# All emergency attempts failed — return 503 for OpenClaw fallback chain
|
||||||
|
return build_error_response(
|
||||||
|
503,
|
||||||
|
"All provider pools exhausted. OpenClaw fallback chain should activate.",
|
||||||
|
"AllPoolsExhausted",
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def _refresh_cooldowns() -> None:
|
||||||
|
"""Check and clear expired cooldowns for backends currently in cooling state.
|
||||||
|
|
||||||
|
Only queries backends with status='cooling' (the health_check_loop handles
|
||||||
|
the periodic scanning; this is the on-demand refresh before proxy routing)."""
|
||||||
|
from storage.backend_store import list_backends
|
||||||
|
backends = list_backends(decrypt_key=False)
|
||||||
|
for backend in backends:
|
||||||
|
if backend.status == "cooling":
|
||||||
|
check_and_clear_cooldown(backend.id)
|
||||||
@@ -0,0 +1,111 @@
|
|||||||
|
"""Per-backend rate limiter using token bucket algorithm."""
|
||||||
|
|
||||||
|
import threading
|
||||||
|
import time
|
||||||
|
from typing import Any
|
||||||
|
|
||||||
|
|
||||||
|
class PerBackendRateLimiter:
|
||||||
|
"""Manages independent token buckets for each backend.
|
||||||
|
|
||||||
|
Thread-safe. Each backend gets its own bucket with configurable RPM.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, refill_interval_ms: int = 50):
|
||||||
|
self._buckets: dict[str, _TokenBucket] = {}
|
||||||
|
self._lock = threading.Lock()
|
||||||
|
self._refill_interval_ms = refill_interval_ms
|
||||||
|
|
||||||
|
def ensure_bucket(self, backend_id: str, rpm_limit: int) -> None:
|
||||||
|
"""Create or update a bucket for a backend."""
|
||||||
|
with self._lock:
|
||||||
|
if backend_id in self._buckets:
|
||||||
|
existing = self._buckets[backend_id]
|
||||||
|
existing.update_rate(rpm_limit)
|
||||||
|
else:
|
||||||
|
self._buckets[backend_id] = _TokenBucket(
|
||||||
|
rate=rpm_limit / 60.0,
|
||||||
|
capacity=max(rpm_limit, 1),
|
||||||
|
)
|
||||||
|
|
||||||
|
def remove_bucket(self, backend_id: str) -> None:
|
||||||
|
"""Remove a backend's bucket."""
|
||||||
|
with self._lock:
|
||||||
|
self._buckets.pop(backend_id, None)
|
||||||
|
|
||||||
|
def consume(self, backend_id: str, rpm_limit: int, tokens: int = 1) -> bool:
|
||||||
|
"""Try to consume tokens for a backend. Returns True if allowed.
|
||||||
|
|
||||||
|
Auto-creates the bucket if needed.
|
||||||
|
"""
|
||||||
|
self.ensure_bucket(backend_id, rpm_limit)
|
||||||
|
|
||||||
|
with self._lock:
|
||||||
|
bucket = self._buckets.get(backend_id)
|
||||||
|
if bucket is None:
|
||||||
|
return False
|
||||||
|
|
||||||
|
return bucket.consume(tokens)
|
||||||
|
|
||||||
|
def get_status(self, backend_id: str) -> dict[str, Any] | None:
|
||||||
|
"""Get bucket status for a backend."""
|
||||||
|
with self._lock:
|
||||||
|
bucket = self._buckets.get(backend_id)
|
||||||
|
if bucket is None:
|
||||||
|
return None
|
||||||
|
return bucket.get_status()
|
||||||
|
|
||||||
|
def get_all_status(self) -> dict[str, dict[str, Any]]:
|
||||||
|
"""Get status of all buckets."""
|
||||||
|
with self._lock:
|
||||||
|
return {bid: b.get_status() for bid, b in self._buckets.items()}
|
||||||
|
|
||||||
|
|
||||||
|
class _TokenBucket:
|
||||||
|
"""Internal token bucket with refill."""
|
||||||
|
|
||||||
|
def __init__(self, rate: float, capacity: int):
|
||||||
|
self._rate = float(rate)
|
||||||
|
self._capacity = int(capacity)
|
||||||
|
self._tokens = float(capacity)
|
||||||
|
self._last_refill = time.monotonic()
|
||||||
|
self._lock = threading.Lock()
|
||||||
|
|
||||||
|
def _refill(self) -> None:
|
||||||
|
now = time.monotonic()
|
||||||
|
elapsed = now - self._last_refill
|
||||||
|
if elapsed > 0 and self._rate > 0:
|
||||||
|
self._tokens = min(self._tokens + elapsed * self._rate, float(self._capacity))
|
||||||
|
self._last_refill = now
|
||||||
|
|
||||||
|
def consume(self, tokens: int = 1) -> bool:
|
||||||
|
if tokens <= 0:
|
||||||
|
return True
|
||||||
|
with self._lock:
|
||||||
|
self._refill()
|
||||||
|
if self._tokens >= tokens:
|
||||||
|
self._tokens -= tokens
|
||||||
|
return True
|
||||||
|
return False
|
||||||
|
|
||||||
|
def update_rate(self, rpm_limit: int) -> None:
|
||||||
|
new_rate = rpm_limit / 60.0
|
||||||
|
with self._lock:
|
||||||
|
self._refill()
|
||||||
|
self._rate = new_rate
|
||||||
|
self._capacity = max(rpm_limit, 1)
|
||||||
|
self._tokens = min(self._tokens, float(self._capacity))
|
||||||
|
|
||||||
|
def get_status(self) -> dict[str, Any]:
|
||||||
|
with self._lock:
|
||||||
|
self._refill()
|
||||||
|
rate_per_minute = self._rate * 60.0
|
||||||
|
utilization = 0.0 if self._capacity == 0 else (
|
||||||
|
(self._capacity - self._tokens) / self._capacity
|
||||||
|
)
|
||||||
|
return {
|
||||||
|
"tokens": round(self._tokens, 2),
|
||||||
|
"capacity": self._capacity,
|
||||||
|
"rate_per_minute": round(rate_per_minute, 1),
|
||||||
|
"utilization": round(utilization, 4),
|
||||||
|
}
|
||||||
@@ -0,0 +1,6 @@
|
|||||||
|
# Sidecar V2 — Multi-Pool Provider Proxy
|
||||||
|
fastapi>=0.115.0,<1.0.0
|
||||||
|
uvicorn[standard]>=0.30.0,<1.0.0
|
||||||
|
httpx>=0.27.0,<1.0.0
|
||||||
|
structlog>=24.0.0,<25.0.0
|
||||||
|
cryptography>=42.0.0,<44.0.0
|
||||||
@@ -0,0 +1,62 @@
|
|||||||
|
"""Model → Backend routing logic for Sidecar V2."""
|
||||||
|
|
||||||
|
import structlog
|
||||||
|
from typing import Optional
|
||||||
|
|
||||||
|
from storage.models import Backend
|
||||||
|
from pool_manager import PoolManager
|
||||||
|
from rate_limiter import PerBackendRateLimiter
|
||||||
|
|
||||||
|
logger = structlog.get_logger("sidecar_v2.router")
|
||||||
|
|
||||||
|
|
||||||
|
class Router:
|
||||||
|
"""Routes model requests to the best available backend.
|
||||||
|
|
||||||
|
Pick strategy:
|
||||||
|
1. Primary pool → healthy backends supporting the model
|
||||||
|
2. Rate-limiter check → skip if RPM exhausted
|
||||||
|
3. Fallback pool → repeat above
|
||||||
|
4. If all exhausted → return None (caller handles emergency)
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, pool_manager: PoolManager, rate_limiter: PerBackendRateLimiter):
|
||||||
|
self._pool_manager = pool_manager
|
||||||
|
self._rate_limiter = rate_limiter
|
||||||
|
|
||||||
|
def pick_backend(self, canonical_model: str) -> Optional[Backend]:
|
||||||
|
"""Pick the best available backend for a model.
|
||||||
|
|
||||||
|
Tries primary pool first, then fallback.
|
||||||
|
Within each pool, skips backends at RPM limit.
|
||||||
|
Returns None if no backend available.
|
||||||
|
"""
|
||||||
|
# Try pools in order
|
||||||
|
for pool in ["primary", "fallback"]:
|
||||||
|
backends = self._pool_manager.get_available_backends(
|
||||||
|
canonical_model, pool=pool
|
||||||
|
)
|
||||||
|
for backend in backends:
|
||||||
|
# Rate-limit check
|
||||||
|
if self._rate_limiter.consume(
|
||||||
|
backend.id, backend.rpm_limit
|
||||||
|
):
|
||||||
|
return backend
|
||||||
|
# Skip this backend, try next
|
||||||
|
logger.debug(
|
||||||
|
"backend_rate_limited",
|
||||||
|
backend_id=backend.id,
|
||||||
|
pool=pool,
|
||||||
|
model=canonical_model,
|
||||||
|
)
|
||||||
|
|
||||||
|
if not backends:
|
||||||
|
logger.debug("pool_exhausted", pool=pool, model=canonical_model)
|
||||||
|
else:
|
||||||
|
logger.debug("pool_rpm_exhausted", pool=pool, model=canonical_model)
|
||||||
|
|
||||||
|
return None
|
||||||
|
|
||||||
|
def get_all_pools_exhausted_info(self, canonical_model: str) -> bool:
|
||||||
|
"""Check if ALL pools are exhausted for a model."""
|
||||||
|
return not self._pool_manager.is_any_pool_available(canonical_model)
|
||||||
@@ -0,0 +1,712 @@
|
|||||||
|
"""Sidecar V2 — FastAPI server with multi-pool routing, admin API, dashboard SSE."""
|
||||||
|
|
||||||
|
import asyncio
|
||||||
|
import json
|
||||||
|
import os
|
||||||
|
import sys
|
||||||
|
import time
|
||||||
|
from collections.abc import AsyncGenerator
|
||||||
|
from contextlib import asynccontextmanager
|
||||||
|
from typing import Any, Optional
|
||||||
|
|
||||||
|
import structlog
|
||||||
|
from fastapi import Depends, FastAPI, HTTPException, Request, Response
|
||||||
|
from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, StreamingResponse
|
||||||
|
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
|
||||||
|
|
||||||
|
from config import config as app_config
|
||||||
|
from crypto import init_crypto, is_initialized
|
||||||
|
from pool_manager import PoolManager
|
||||||
|
from rate_limiter import PerBackendRateLimiter
|
||||||
|
from router import Router
|
||||||
|
from proxy import handle_proxy_request, get_emergency_count
|
||||||
|
|
||||||
|
from storage.db import init_db, create_tables, run_integrity_check, get_connection, _DB_PATH
|
||||||
|
from storage.backend_store import (
|
||||||
|
create_backend, get_backend, list_backends, update_backend,
|
||||||
|
delete_backend, get_pool_stats,
|
||||||
|
)
|
||||||
|
from storage.usage_store import get_total_stats, get_hourly_usage, get_daily_stats, aggregate_daily_stats
|
||||||
|
from storage.cooldown_store import get_cooldown_history
|
||||||
|
from storage.config_store import get_config, set_config, list_configs, delete_config
|
||||||
|
from storage.models import Backend, ModelMapping
|
||||||
|
|
||||||
|
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
# Logging
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
_LOG_FORMAT = os.getenv("LOG_FORMAT", "console").lower()
|
||||||
|
|
||||||
|
structlog.configure(
|
||||||
|
processors=[
|
||||||
|
structlog.stdlib.filter_by_level,
|
||||||
|
structlog.stdlib.add_logger_name,
|
||||||
|
structlog.stdlib.add_log_level,
|
||||||
|
structlog.stdlib.PositionalArgumentsFormatter(),
|
||||||
|
structlog.processors.TimeStamper(fmt="iso"),
|
||||||
|
structlog.processors.StackInfoRenderer(),
|
||||||
|
structlog.processors.format_exc_info,
|
||||||
|
structlog.processors.UnicodeDecoder(),
|
||||||
|
(
|
||||||
|
structlog.processors.JSONRenderer()
|
||||||
|
if _LOG_FORMAT == "json"
|
||||||
|
else structlog.dev.ConsoleRenderer()
|
||||||
|
),
|
||||||
|
],
|
||||||
|
context_class=dict,
|
||||||
|
logger_factory=structlog.stdlib.LoggerFactory(),
|
||||||
|
wrapper_class=structlog.stdlib.BoundLogger,
|
||||||
|
cache_logger_on_first_use=True,
|
||||||
|
)
|
||||||
|
logger: structlog.stdlib.BoundLogger = structlog.get_logger("sidecar_v2.server")
|
||||||
|
|
||||||
|
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
# Admin Auth middleware
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
_security = HTTPBearer(auto_error=False)
|
||||||
|
|
||||||
|
|
||||||
|
def verify_admin_token(
|
||||||
|
credentials: Optional[HTTPAuthorizationCredentials] = Depends(_security),
|
||||||
|
) -> bool:
|
||||||
|
"""Verify Bearer Token against config.admin_token.
|
||||||
|
|
||||||
|
If admin_token is empty, write operations are rejected.
|
||||||
|
READ operations are allowed without auth for dashboard use.
|
||||||
|
"""
|
||||||
|
if not app_config.admin_token:
|
||||||
|
# No token configured — allow read, reject write (checked per-endpoint)
|
||||||
|
if credentials is None:
|
||||||
|
return False
|
||||||
|
return False
|
||||||
|
|
||||||
|
if credentials is None:
|
||||||
|
return False
|
||||||
|
|
||||||
|
return credentials.credentials == app_config.admin_token
|
||||||
|
|
||||||
|
|
||||||
|
def require_admin(credentials: Optional[HTTPAuthorizationCredentials] = Depends(_security)):
|
||||||
|
"""Require admin auth — raise 401 if not authorized."""
|
||||||
|
if not app_config.admin_token:
|
||||||
|
raise HTTPException(
|
||||||
|
status_code=401,
|
||||||
|
detail="Admin API not configured: set SIDECAR_ADMIN_TOKEN",
|
||||||
|
)
|
||||||
|
if credentials is None:
|
||||||
|
raise HTTPException(
|
||||||
|
status_code=401,
|
||||||
|
detail="Missing Authorization header",
|
||||||
|
headers={"WWW-Authenticate": "Bearer"},
|
||||||
|
)
|
||||||
|
if credentials.credentials != app_config.admin_token:
|
||||||
|
raise HTTPException(
|
||||||
|
status_code=401,
|
||||||
|
detail="Invalid admin token",
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
# Global runtime state
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
pool_manager: Optional[PoolManager] = None
|
||||||
|
rate_limiter: Optional[PerBackendRateLimiter] = None
|
||||||
|
router: Optional[Router] = None
|
||||||
|
start_time: float = 0.0
|
||||||
|
|
||||||
|
# In-memory metrics counters
|
||||||
|
_metrics_counters: dict[str, int] = {}
|
||||||
|
_metrics_lock = asyncio.Lock()
|
||||||
|
|
||||||
|
|
||||||
|
def _inc_metric(key: str, delta: int = 1) -> None:
|
||||||
|
"""Thread-safe counter increment (deferred via asyncio)."""
|
||||||
|
_metrics_counters[key] = _metrics_counters.get(key, 0) + delta
|
||||||
|
|
||||||
|
|
||||||
|
def get_pm() -> PoolManager:
|
||||||
|
assert pool_manager is not None
|
||||||
|
return pool_manager
|
||||||
|
|
||||||
|
|
||||||
|
def get_rl() -> PerBackendRateLimiter:
|
||||||
|
assert rate_limiter is not None
|
||||||
|
return rate_limiter
|
||||||
|
|
||||||
|
|
||||||
|
def get_router() -> Router:
|
||||||
|
assert router is not None
|
||||||
|
return router
|
||||||
|
|
||||||
|
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
# Lifespan
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
@asynccontextmanager
|
||||||
|
async def lifespan(app: FastAPI) -> AsyncGenerator[None, Any]:
|
||||||
|
global pool_manager, rate_limiter, router, start_time
|
||||||
|
|
||||||
|
# P0: Encryption key is mandatory — refuse to start without it
|
||||||
|
if not app_config.encryption_key:
|
||||||
|
logger.critical(
|
||||||
|
"missing_encryption_key",
|
||||||
|
hint="Set SIDECAR_ENCRYPTION_KEY (64 hex chars). Refusing to start."
|
||||||
|
)
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
init_crypto(app_config.encryption_key)
|
||||||
|
logger.info("crypto_initialized")
|
||||||
|
|
||||||
|
# P0: Warn if admin_token not set
|
||||||
|
if not app_config.admin_token:
|
||||||
|
logger.warning(
|
||||||
|
"admin_token_not_set",
|
||||||
|
hint="Admin write endpoints disabled until SIDECAR_ADMIN_TOKEN is configured."
|
||||||
|
)
|
||||||
|
|
||||||
|
# Init DB
|
||||||
|
init_db()
|
||||||
|
create_tables()
|
||||||
|
ok = run_integrity_check()
|
||||||
|
if not ok:
|
||||||
|
logger.error("db_integrity_check_failed")
|
||||||
|
|
||||||
|
# Init runtime components
|
||||||
|
pool_manager = PoolManager()
|
||||||
|
rate_limiter = PerBackendRateLimiter(
|
||||||
|
refill_interval_ms=app_config.rate_limiter_refill_interval_ms,
|
||||||
|
)
|
||||||
|
router = Router(pool_manager, rate_limiter)
|
||||||
|
start_time = time.time()
|
||||||
|
|
||||||
|
# Start background tasks
|
||||||
|
health_task = asyncio.create_task(_health_check_loop())
|
||||||
|
stats_task = asyncio.create_task(_stats_aggregation_loop())
|
||||||
|
backup_task = asyncio.create_task(_backup_loop())
|
||||||
|
|
||||||
|
logger.info(
|
||||||
|
"sidecar_v2_started",
|
||||||
|
host=app_config.host,
|
||||||
|
port=app_config.port,
|
||||||
|
metrics_port=app_config.metrics_port,
|
||||||
|
)
|
||||||
|
|
||||||
|
try:
|
||||||
|
yield
|
||||||
|
finally:
|
||||||
|
for task in [health_task, stats_task, backup_task]:
|
||||||
|
task.cancel()
|
||||||
|
try:
|
||||||
|
await task
|
||||||
|
except asyncio.CancelledError:
|
||||||
|
pass
|
||||||
|
logger.info("sidecar_v2_stopped")
|
||||||
|
|
||||||
|
|
||||||
|
app = FastAPI(
|
||||||
|
title="Sidecar V2 — Multi-Pool Provider Proxy",
|
||||||
|
version="2.0.0",
|
||||||
|
lifespan=lifespan,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
# Background tasks
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
|
||||||
|
async def _health_check_loop() -> None:
|
||||||
|
"""Periodic health checks: clear expired cooldowns + active probing of backends."""
|
||||||
|
from cooldown_manager import check_and_clear_cooldown
|
||||||
|
import httpx
|
||||||
|
|
||||||
|
while True:
|
||||||
|
try:
|
||||||
|
backends = list_backends(decrypt_key=True)
|
||||||
|
for b in backends:
|
||||||
|
# 1. Clear expired cooldowns
|
||||||
|
if b.status == "cooling":
|
||||||
|
check_and_clear_cooldown(b.id)
|
||||||
|
|
||||||
|
# 2. Active health probing for healthy/enabled backends
|
||||||
|
if b.status == "healthy" and b.enabled:
|
||||||
|
try:
|
||||||
|
async with httpx.AsyncClient(timeout=httpx.Timeout(
|
||||||
|
app_config.health_check_timeout_seconds
|
||||||
|
)) as client:
|
||||||
|
probe_url = b.api_base_url.rstrip("/") + app_config.health_probe_endpoint
|
||||||
|
headers = {}
|
||||||
|
if b.api_key_plain:
|
||||||
|
headers["Authorization"] = f"Bearer {b.api_key_plain}"
|
||||||
|
|
||||||
|
start = time.monotonic()
|
||||||
|
resp = await client.get(probe_url, headers=headers)
|
||||||
|
elapsed_ms = int((time.monotonic() - start) * 1000)
|
||||||
|
|
||||||
|
# Update health state in DB
|
||||||
|
from storage.db import get_connection as _gc
|
||||||
|
with _gc() as conn:
|
||||||
|
conn.execute(
|
||||||
|
"""INSERT INTO backend_health
|
||||||
|
(backend_id, state, last_latency_ms, last_status_code,
|
||||||
|
last_check_at)
|
||||||
|
VALUES (?, 'healthy', ?, ?, datetime('now'))
|
||||||
|
ON CONFLICT(backend_id) DO UPDATE SET
|
||||||
|
state = excluded.state,
|
||||||
|
last_latency_ms = excluded.last_latency_ms,
|
||||||
|
last_status_code = excluded.last_status_code,
|
||||||
|
last_check_at = excluded.last_check_at""",
|
||||||
|
(b.id, elapsed_ms, resp.status_code),
|
||||||
|
)
|
||||||
|
conn.commit()
|
||||||
|
|
||||||
|
logger.debug(
|
||||||
|
"health_probe_ok",
|
||||||
|
backend_id=b.id,
|
||||||
|
status=resp.status_code,
|
||||||
|
latency_ms=elapsed_ms,
|
||||||
|
)
|
||||||
|
except Exception as probe_err:
|
||||||
|
logger.warning(
|
||||||
|
"health_probe_failed",
|
||||||
|
backend_id=b.id,
|
||||||
|
error=str(probe_err),
|
||||||
|
)
|
||||||
|
# Mark as degraded
|
||||||
|
from storage.db import get_connection as _gc
|
||||||
|
with _gc() as conn:
|
||||||
|
conn.execute(
|
||||||
|
"""INSERT INTO backend_health
|
||||||
|
(backend_id, state, last_check_at)
|
||||||
|
VALUES (?, 'degraded', datetime('now'))
|
||||||
|
ON CONFLICT(backend_id) DO UPDATE SET
|
||||||
|
state = 'degraded',
|
||||||
|
last_check_at = excluded.last_check_at""",
|
||||||
|
(b.id,),
|
||||||
|
)
|
||||||
|
conn.execute(
|
||||||
|
"""UPDATE backend_health SET
|
||||||
|
consecutive_failures = consecutive_failures + 1
|
||||||
|
WHERE backend_id = ?""",
|
||||||
|
(b.id,),
|
||||||
|
)
|
||||||
|
conn.commit()
|
||||||
|
except Exception:
|
||||||
|
logger.exception("health_check_error")
|
||||||
|
await asyncio.sleep(app_config.health_check_interval_seconds)
|
||||||
|
|
||||||
|
|
||||||
|
async def _stats_aggregation_loop() -> None:
|
||||||
|
"""Periodically aggregate daily stats."""
|
||||||
|
while True:
|
||||||
|
try:
|
||||||
|
today = time.strftime("%Y-%m-%d", time.gmtime())
|
||||||
|
aggregate_daily_stats(today)
|
||||||
|
except Exception:
|
||||||
|
logger.exception("stats_aggregation_error")
|
||||||
|
await asyncio.sleep(app_config.stats_refresh_interval_seconds)
|
||||||
|
|
||||||
|
|
||||||
|
async def _backup_loop() -> None:
|
||||||
|
"""Daily SQLite backup with retention."""
|
||||||
|
import shutil
|
||||||
|
|
||||||
|
while True:
|
||||||
|
try:
|
||||||
|
await asyncio.sleep(86400) # 24 hours
|
||||||
|
backup_dir = app_config.backup_dir
|
||||||
|
if not backup_dir:
|
||||||
|
continue
|
||||||
|
|
||||||
|
os.makedirs(backup_dir, exist_ok=True)
|
||||||
|
|
||||||
|
backup_name = f"sidecar_v2_{time.strftime('%Y%m%d_%H%M%S', time.gmtime())}.db"
|
||||||
|
backup_path = os.path.join(backup_dir, backup_name)
|
||||||
|
|
||||||
|
from storage.db import _DB_PATH as db_path
|
||||||
|
import sqlite3
|
||||||
|
|
||||||
|
source = sqlite3.connect(db_path)
|
||||||
|
dest = sqlite3.connect(backup_path)
|
||||||
|
source.backup(dest)
|
||||||
|
dest.close()
|
||||||
|
source.close()
|
||||||
|
|
||||||
|
logger.info("db_backup_created", path=backup_path)
|
||||||
|
|
||||||
|
# Retention: remove old backups
|
||||||
|
retention_days = app_config.backup_retention_days
|
||||||
|
cutoff = time.time() - retention_days * 86400
|
||||||
|
for fname in os.listdir(backup_dir):
|
||||||
|
if fname.startswith("sidecar_v2_") and fname.endswith(".db"):
|
||||||
|
fpath = os.path.join(backup_dir, fname)
|
||||||
|
if os.path.getmtime(fpath) < cutoff:
|
||||||
|
os.remove(fpath)
|
||||||
|
logger.info("db_backup_retired", path=fpath)
|
||||||
|
|
||||||
|
except Exception:
|
||||||
|
logger.exception("backup_error")
|
||||||
|
|
||||||
|
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
# Health / Metrics
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
@app.get("/health")
|
||||||
|
async def health() -> dict[str, Any]:
|
||||||
|
return {
|
||||||
|
"status": "ok",
|
||||||
|
"version": "2.0.0",
|
||||||
|
"uptime_seconds": int(time.time() - start_time),
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
@app.get("/metrics")
|
||||||
|
async def metrics() -> Response:
|
||||||
|
"""Prometheus-compatible metrics endpoint."""
|
||||||
|
lines = []
|
||||||
|
|
||||||
|
# Pool provider counts
|
||||||
|
pool_status = pool_manager.get_pool_status()
|
||||||
|
for pool_name, stats in pool_status.items():
|
||||||
|
for key, val in stats.items():
|
||||||
|
lines.append(
|
||||||
|
f"sidecar_pool_providers{{pool=\"{pool_name}\",type=\"{key}\"}} {val}"
|
||||||
|
)
|
||||||
|
|
||||||
|
# Cooldown status
|
||||||
|
all_backends = list_backends(decrypt_key=False)
|
||||||
|
cooling_count = sum(1 for b in all_backends if b.status == "cooling")
|
||||||
|
lines.append(f"sidecar_cooldown_active {cooling_count}")
|
||||||
|
|
||||||
|
# Emergency count (from proxy module)
|
||||||
|
lines.append(f"sidecar_emergency_count {get_emergency_count()}")
|
||||||
|
|
||||||
|
# DB sizes
|
||||||
|
from storage.db import get_db_sizes
|
||||||
|
sizes = get_db_sizes()
|
||||||
|
lines.append(f"sidecar_db_size_bytes {sizes.get('db_bytes', 0)}")
|
||||||
|
lines.append(f"sidecar_wal_size_bytes {sizes.get('wal_bytes', 0)}")
|
||||||
|
|
||||||
|
# Total stats
|
||||||
|
total = get_total_stats()
|
||||||
|
lines.append(f"sidecar_requests_total {total.get('total_requests', 0) or 0}")
|
||||||
|
lines.append(f"sidecar_errors_total {total.get('total_errors', 0) or 0}")
|
||||||
|
lines.append(f"sidecar_tokens_total {total.get('total_tokens', 0) or 0}")
|
||||||
|
cost = total.get('total_cost', 0) or 0.0
|
||||||
|
lines.append(f"sidecar_cost_total {cost}")
|
||||||
|
|
||||||
|
# Uptime
|
||||||
|
lines.append(f"sidecar_uptime_seconds {int(time.time() - start_time)}")
|
||||||
|
|
||||||
|
return Response(
|
||||||
|
content="\n".join(lines) + "\n",
|
||||||
|
media_type="text/plain; charset=utf-8",
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
# Dashboard SSE
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
@app.get("/dashboard/sse")
|
||||||
|
async def dashboard_sse() -> StreamingResponse:
|
||||||
|
"""SSE endpoint for real-time dashboard data."""
|
||||||
|
|
||||||
|
async def event_generator():
|
||||||
|
while True:
|
||||||
|
try:
|
||||||
|
pool_status = pool_manager.get_pool_status()
|
||||||
|
total_stats = get_total_stats()
|
||||||
|
all_backends = list_backends(decrypt_key=False)
|
||||||
|
|
||||||
|
backends_list = []
|
||||||
|
for b in all_backends:
|
||||||
|
rl_status = rate_limiter.get_status(b.id)
|
||||||
|
backends_list.append({
|
||||||
|
"id": b.id,
|
||||||
|
"name": b.name,
|
||||||
|
"label": b.label,
|
||||||
|
"pool": b.pool,
|
||||||
|
"enabled": b.enabled,
|
||||||
|
"status": b.status,
|
||||||
|
"rpm_limit": b.rpm_limit,
|
||||||
|
"cooldown_until": b.cooldown_until,
|
||||||
|
"consecutive_429_count": b.consecutive_429_count,
|
||||||
|
"model_count": len(b.model_mappings),
|
||||||
|
"rate_limiter": rl_status,
|
||||||
|
})
|
||||||
|
|
||||||
|
snapshot = {
|
||||||
|
"type": "snapshot",
|
||||||
|
"pool": pool_status,
|
||||||
|
"total": total_stats,
|
||||||
|
"backends": backends_list,
|
||||||
|
"uptime_seconds": int(time.time() - start_time),
|
||||||
|
"timestamp": time.time(),
|
||||||
|
}
|
||||||
|
yield f"data: {json.dumps(snapshot)}\n\n"
|
||||||
|
except Exception:
|
||||||
|
logger.exception("sse_error")
|
||||||
|
|
||||||
|
await asyncio.sleep(app_config.dashboard_sse_interval_seconds)
|
||||||
|
|
||||||
|
return StreamingResponse(
|
||||||
|
event_generator(),
|
||||||
|
media_type="text/event-stream",
|
||||||
|
headers={
|
||||||
|
"Cache-Control": "no-cache",
|
||||||
|
"Connection": "keep-alive",
|
||||||
|
"X-Accel-Buffering": "no",
|
||||||
|
},
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
# Admin: Backend CRUD (READ: public, WRITE: auth required)
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
|
||||||
|
@app.get("/api/admin/backends")
|
||||||
|
async def admin_list_backends(pool: Optional[str] = None) -> list[dict]:
|
||||||
|
"""List all backends with masked keys (public read)."""
|
||||||
|
backends = list_backends(pool=pool, decrypt_key=True)
|
||||||
|
return [b.to_dict(mask_key=True) for b in backends]
|
||||||
|
|
||||||
|
|
||||||
|
@app.get("/api/admin/backends/{backend_id}")
|
||||||
|
async def admin_get_backend(backend_id: str) -> dict:
|
||||||
|
"""Get a single backend (public read, key masked)."""
|
||||||
|
b = get_backend(backend_id, decrypt_key=True)
|
||||||
|
if b is None:
|
||||||
|
raise HTTPException(404, "Backend not found")
|
||||||
|
return b.to_dict(mask_key=True)
|
||||||
|
|
||||||
|
|
||||||
|
@app.post("/api/admin/backends")
|
||||||
|
async def admin_create_backend(
|
||||||
|
body: dict[str, Any],
|
||||||
|
_auth=Depends(require_admin),
|
||||||
|
) -> dict:
|
||||||
|
"""Create a new backend (auth required)."""
|
||||||
|
required = ["name", "api_base_url", "api_key"]
|
||||||
|
for field in required:
|
||||||
|
if field not in body:
|
||||||
|
raise HTTPException(400, f"Missing required field: {field}")
|
||||||
|
|
||||||
|
model_mappings_raw = body.get("model_mappings", {})
|
||||||
|
model_mappings = {}
|
||||||
|
for canonical_name, mm in model_mappings_raw.items():
|
||||||
|
model_mappings[canonical_name] = ModelMapping.from_dict(mm)
|
||||||
|
|
||||||
|
backend = Backend(
|
||||||
|
name=body["name"],
|
||||||
|
label=body.get("label", ""),
|
||||||
|
api_base_url=body["api_base_url"],
|
||||||
|
api_key_plain=body["api_key"],
|
||||||
|
api=body.get("api", "openai-completions"),
|
||||||
|
timeout_seconds=body.get("timeout_seconds", 120),
|
||||||
|
rpm_limit=body.get("rpm_limit", app_config.default_rpm_limit),
|
||||||
|
pool=body.get("pool", "primary"),
|
||||||
|
enabled=body.get("enabled", True),
|
||||||
|
model_mappings=model_mappings,
|
||||||
|
source=body.get("source", "webui"),
|
||||||
|
)
|
||||||
|
|
||||||
|
created = create_backend(backend)
|
||||||
|
return created.to_dict(mask_key=True)
|
||||||
|
|
||||||
|
|
||||||
|
@app.put("/api/admin/backends/{backend_id}")
|
||||||
|
async def admin_update_backend(
|
||||||
|
backend_id: str,
|
||||||
|
body: dict[str, Any],
|
||||||
|
_auth=Depends(require_admin),
|
||||||
|
) -> dict:
|
||||||
|
"""Update a backend (auth required)."""
|
||||||
|
updates = dict(body)
|
||||||
|
|
||||||
|
if "model_mappings" in updates:
|
||||||
|
raw = updates["model_mappings"]
|
||||||
|
updates["model_mappings"] = {
|
||||||
|
k: ModelMapping.from_dict(v) for k, v in raw.items()
|
||||||
|
}
|
||||||
|
|
||||||
|
if "api_key" in updates:
|
||||||
|
updates["api_key_plain"] = updates.pop("api_key")
|
||||||
|
|
||||||
|
updated = update_backend(backend_id, updates)
|
||||||
|
if updated is None:
|
||||||
|
raise HTTPException(404, "Backend not found")
|
||||||
|
return updated.to_dict(mask_key=True)
|
||||||
|
|
||||||
|
|
||||||
|
@app.delete("/api/admin/backends/{backend_id}")
|
||||||
|
async def admin_delete_backend(
|
||||||
|
backend_id: str,
|
||||||
|
_auth=Depends(require_admin),
|
||||||
|
) -> dict:
|
||||||
|
"""Delete a backend (auth required)."""
|
||||||
|
ok = delete_backend(backend_id)
|
||||||
|
if not ok:
|
||||||
|
raise HTTPException(404, "Backend not found")
|
||||||
|
return {"status": "deleted", "id": backend_id}
|
||||||
|
|
||||||
|
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
# Admin: Pool Status (public read)
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
|
||||||
|
@app.get("/api/admin/pools")
|
||||||
|
async def admin_pool_status() -> dict:
|
||||||
|
return pool_manager.get_pool_status()
|
||||||
|
|
||||||
|
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
# Admin: Usage / Stats (public read)
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
|
||||||
|
@app.get("/api/admin/stats/total")
|
||||||
|
async def admin_total_stats() -> dict:
|
||||||
|
return get_total_stats()
|
||||||
|
|
||||||
|
|
||||||
|
@app.get("/api/admin/stats/hourly")
|
||||||
|
async def admin_hourly_usage(
|
||||||
|
backend_id: Optional[str] = None,
|
||||||
|
hours: int = 168,
|
||||||
|
) -> list[dict]:
|
||||||
|
since = None
|
||||||
|
if hours > 0:
|
||||||
|
since = time.strftime(
|
||||||
|
"%Y-%m-%dT%H:%M:%SZ",
|
||||||
|
time.gmtime(time.time() - hours * 3600),
|
||||||
|
)
|
||||||
|
return get_hourly_usage(backend_id=backend_id, since=since, limit=hours)
|
||||||
|
|
||||||
|
|
||||||
|
@app.get("/api/admin/stats/daily")
|
||||||
|
async def admin_daily_stats(days: int = 30) -> list[dict]:
|
||||||
|
return get_daily_stats(days=days)
|
||||||
|
|
||||||
|
|
||||||
|
@app.get("/api/admin/stats/cooldown")
|
||||||
|
async def admin_cooldown_history(
|
||||||
|
backend_id: Optional[str] = None,
|
||||||
|
limit: int = 50,
|
||||||
|
) -> list[dict]:
|
||||||
|
return get_cooldown_history(backend_id=backend_id, limit=limit)
|
||||||
|
|
||||||
|
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
# Admin: System Config (read public, write auth required)
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
|
||||||
|
@app.get("/api/admin/config")
|
||||||
|
async def admin_get_all_config() -> list[dict]:
|
||||||
|
return list_configs()
|
||||||
|
|
||||||
|
|
||||||
|
@app.get("/api/admin/config/{key}")
|
||||||
|
async def admin_get_config(key: str) -> dict:
|
||||||
|
value = get_config(key)
|
||||||
|
if value is None:
|
||||||
|
raise HTTPException(404, "Config not found")
|
||||||
|
return {"key": key, "value": value}
|
||||||
|
|
||||||
|
|
||||||
|
@app.put("/api/admin/config/{key}")
|
||||||
|
async def admin_set_config(
|
||||||
|
key: str,
|
||||||
|
body: dict[str, Any],
|
||||||
|
_auth=Depends(require_admin),
|
||||||
|
) -> dict:
|
||||||
|
value = str(body.get("value", ""))
|
||||||
|
description = str(body.get("description", ""))
|
||||||
|
set_config(key, value, description)
|
||||||
|
return {"key": key, "value": value}
|
||||||
|
|
||||||
|
|
||||||
|
@app.delete("/api/admin/config/{key}")
|
||||||
|
async def admin_delete_config(
|
||||||
|
key: str,
|
||||||
|
_auth=Depends(require_admin),
|
||||||
|
) -> dict:
|
||||||
|
ok = delete_config(key)
|
||||||
|
if not ok:
|
||||||
|
raise HTTPException(404, "Config not found")
|
||||||
|
return {"status": "deleted", "key": key}
|
||||||
|
|
||||||
|
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
# Dashboard HTML (public, but respects admin_token for writes in JS)
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
|
||||||
|
@app.get("/dashboard")
|
||||||
|
async def dashboard_html() -> HTMLResponse:
|
||||||
|
dashboard_path = os.path.join(
|
||||||
|
os.path.dirname(__file__), "dashboard.html"
|
||||||
|
)
|
||||||
|
if os.path.exists(dashboard_path):
|
||||||
|
with open(dashboard_path, "r") as f:
|
||||||
|
return HTMLResponse(f.read())
|
||||||
|
return HTMLResponse("<h1>Dashboard not found</h1>", status_code=404)
|
||||||
|
|
||||||
|
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
# Proxy Endpoints
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
|
||||||
|
@app.post("/v1/chat/completions")
|
||||||
|
async def chat_completions(request: Request) -> Response:
|
||||||
|
_inc_metric("proxy_requests_total")
|
||||||
|
return await handle_proxy_request(
|
||||||
|
pool_manager, rate_limiter, router, request, "/v1/chat/completions"
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
@app.post("/v1/completions")
|
||||||
|
async def completions(request: Request) -> Response:
|
||||||
|
return await handle_proxy_request(
|
||||||
|
pool_manager, rate_limiter, router, request, "/v1/completions"
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
@app.post("/v1/embeddings")
|
||||||
|
async def embeddings(request: Request) -> Response:
|
||||||
|
return await handle_proxy_request(
|
||||||
|
pool_manager, rate_limiter, router, request, "/v1/embeddings"
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
@app.get("/v1/models")
|
||||||
|
@app.get("/v1/models/{model_id:path}")
|
||||||
|
async def list_models(request: Request, model_id: Optional[str] = None) -> Response:
|
||||||
|
path = f"/v1/models/{model_id}" if model_id else "/v1/models"
|
||||||
|
return await handle_proxy_request(
|
||||||
|
pool_manager, rate_limiter, router, request, path
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
@app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"])
|
||||||
|
async def catch_all(request: Request, path: str) -> Response:
|
||||||
|
target_path = f"/{path}" if not path.startswith("/") else path
|
||||||
|
return await handle_proxy_request(
|
||||||
|
pool_manager, rate_limiter, router, request, target_path
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
# Main
|
||||||
|
# ──────────────────────────────────────────────────────────
|
||||||
|
|
||||||
|
def main() -> None:
|
||||||
|
import uvicorn
|
||||||
|
|
||||||
|
uvicorn.run(
|
||||||
|
"server:app",
|
||||||
|
host=app_config.host,
|
||||||
|
port=app_config.port,
|
||||||
|
log_level=app_config.log_level.lower(),
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
# Sidecar V2 storage module
|
||||||
@@ -0,0 +1,252 @@
|
|||||||
|
"""CRUD operations for Backend (provider) management."""
|
||||||
|
|
||||||
|
import json
|
||||||
|
import time
|
||||||
|
from typing import Optional
|
||||||
|
|
||||||
|
from storage.db import get_connection, generate_id
|
||||||
|
from storage.models import Backend, ModelMapping
|
||||||
|
from crypto import encrypt, decrypt
|
||||||
|
|
||||||
|
|
||||||
|
def create_backend(backend: Backend) -> Backend:
|
||||||
|
"""Create a new backend. Encrypts API key before storage."""
|
||||||
|
if not backend.id:
|
||||||
|
backend.id = generate_id("bkd")
|
||||||
|
|
||||||
|
now = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
|
||||||
|
backend.created_at = now
|
||||||
|
backend.updated_at = now
|
||||||
|
|
||||||
|
api_key_encrypted = encrypt(backend.api_key_plain)
|
||||||
|
|
||||||
|
with get_connection() as conn:
|
||||||
|
conn.execute(
|
||||||
|
"""INSERT INTO backends (id, name, label, api_base_url, api_key_encrypted,
|
||||||
|
api, timeout_seconds, rpm_limit, pool, enabled, status, model_mappings_json,
|
||||||
|
source, cooldown_until, consecutive_429_count, metadata_json, created_at, updated_at)
|
||||||
|
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
|
||||||
|
(
|
||||||
|
backend.id, backend.name, backend.label, backend.api_base_url,
|
||||||
|
api_key_encrypted, backend.api, backend.timeout_seconds,
|
||||||
|
backend.rpm_limit, backend.pool, 1 if backend.enabled else 0,
|
||||||
|
backend.status, json.dumps(_mappings_to_dict(backend.model_mappings)),
|
||||||
|
backend.source, backend.cooldown_until,
|
||||||
|
backend.consecutive_429_count,
|
||||||
|
json.dumps(backend.metadata), backend.created_at, backend.updated_at,
|
||||||
|
),
|
||||||
|
)
|
||||||
|
conn.commit()
|
||||||
|
|
||||||
|
return backend
|
||||||
|
|
||||||
|
|
||||||
|
def get_backend(backend_id: str, decrypt_key: bool = True) -> Optional[Backend]:
|
||||||
|
"""Get a single backend by ID."""
|
||||||
|
with get_connection() as conn:
|
||||||
|
row = conn.execute(
|
||||||
|
"SELECT * FROM backends WHERE id = ?", (backend_id,)
|
||||||
|
).fetchone()
|
||||||
|
|
||||||
|
if row is None:
|
||||||
|
return None
|
||||||
|
|
||||||
|
return _row_to_backend(row, decrypt_key=decrypt_key)
|
||||||
|
|
||||||
|
|
||||||
|
def list_backends(
|
||||||
|
pool: Optional[str] = None,
|
||||||
|
enabled_only: bool = False,
|
||||||
|
decrypt_key: bool = False,
|
||||||
|
) -> list[Backend]:
|
||||||
|
"""List backends, optionally filtered by pool."""
|
||||||
|
with get_connection() as conn:
|
||||||
|
if pool:
|
||||||
|
rows = conn.execute(
|
||||||
|
"SELECT * FROM backends WHERE pool = ? ORDER BY created_at",
|
||||||
|
(pool,),
|
||||||
|
).fetchall()
|
||||||
|
else:
|
||||||
|
rows = conn.execute(
|
||||||
|
"SELECT * FROM backends ORDER BY pool, created_at"
|
||||||
|
).fetchall()
|
||||||
|
|
||||||
|
backends = [_row_to_backend(r, decrypt_key=decrypt_key) for r in rows]
|
||||||
|
if enabled_only:
|
||||||
|
backends = [b for b in backends if b.enabled]
|
||||||
|
return backends
|
||||||
|
|
||||||
|
|
||||||
|
def update_backend(backend_id: str, updates: dict) -> Optional[Backend]:
|
||||||
|
"""Update backend fields. If api_key_plain is provided, re-encrypt."""
|
||||||
|
current = get_backend(backend_id, decrypt_key=True)
|
||||||
|
if current is None:
|
||||||
|
return None
|
||||||
|
|
||||||
|
# Apply updates
|
||||||
|
allowed = {
|
||||||
|
"name", "label", "api_base_url", "api", "timeout_seconds",
|
||||||
|
"rpm_limit", "pool", "enabled", "status", "source",
|
||||||
|
"cooldown_until", "consecutive_429_count", "metadata",
|
||||||
|
}
|
||||||
|
for key, value in updates.items():
|
||||||
|
if key in allowed:
|
||||||
|
setattr(current, key, value)
|
||||||
|
|
||||||
|
current.updated_at = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
|
||||||
|
|
||||||
|
# Handle API key update
|
||||||
|
api_key_encrypted = None
|
||||||
|
if "api_key_plain" in updates and updates["api_key_plain"]:
|
||||||
|
current.api_key_plain = updates["api_key_plain"]
|
||||||
|
api_key_encrypted = encrypt(updates["api_key_plain"])
|
||||||
|
|
||||||
|
# Handle model_mappings update
|
||||||
|
mappings_json = None
|
||||||
|
if "model_mappings" in updates:
|
||||||
|
current.model_mappings = updates["model_mappings"]
|
||||||
|
mappings_json = json.dumps(_mappings_to_dict(current.model_mappings))
|
||||||
|
|
||||||
|
with get_connection() as conn:
|
||||||
|
# Build dynamic UPDATE
|
||||||
|
set_clauses = [
|
||||||
|
"name = ?", "label = ?", "api_base_url = ?", "api = ?",
|
||||||
|
"timeout_seconds = ?", "rpm_limit = ?", "pool = ?", "enabled = ?",
|
||||||
|
"status = ?", "source = ?", "cooldown_until = ?",
|
||||||
|
"consecutive_429_count = ?", "metadata_json = ?", "updated_at = ?",
|
||||||
|
]
|
||||||
|
params = [
|
||||||
|
current.name, current.label, current.api_base_url, current.api,
|
||||||
|
current.timeout_seconds, current.rpm_limit, current.pool,
|
||||||
|
1 if current.enabled else 0, current.status, current.source,
|
||||||
|
current.cooldown_until, current.consecutive_429_count,
|
||||||
|
json.dumps(current.metadata), current.updated_at,
|
||||||
|
]
|
||||||
|
if api_key_encrypted:
|
||||||
|
set_clauses.append("api_key_encrypted = ?")
|
||||||
|
params.append(api_key_encrypted)
|
||||||
|
if mappings_json is not None:
|
||||||
|
set_clauses.append("model_mappings_json = ?")
|
||||||
|
params.append(mappings_json)
|
||||||
|
params.append(backend_id)
|
||||||
|
|
||||||
|
conn.execute(
|
||||||
|
f"UPDATE backends SET {', '.join(set_clauses)} WHERE id = ?",
|
||||||
|
params,
|
||||||
|
)
|
||||||
|
conn.commit()
|
||||||
|
|
||||||
|
return get_backend(backend_id, decrypt_key=False)
|
||||||
|
|
||||||
|
|
||||||
|
def delete_backend(backend_id: str) -> bool:
|
||||||
|
"""Delete a backend. Returns True if deleted."""
|
||||||
|
with get_connection() as conn:
|
||||||
|
cursor = conn.execute("DELETE FROM backends WHERE id = ?", (backend_id,))
|
||||||
|
conn.commit()
|
||||||
|
return cursor.rowcount > 0
|
||||||
|
|
||||||
|
|
||||||
|
def set_backend_status(backend_id: str, status: str) -> bool:
|
||||||
|
"""Quickly set backend status (healthy/cooling/error/disabled)."""
|
||||||
|
now = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
|
||||||
|
with get_connection() as conn:
|
||||||
|
cursor = conn.execute(
|
||||||
|
"UPDATE backends SET status = ?, updated_at = ? WHERE id = ?",
|
||||||
|
(status, now, backend_id),
|
||||||
|
)
|
||||||
|
conn.commit()
|
||||||
|
return cursor.rowcount > 0
|
||||||
|
|
||||||
|
|
||||||
|
def set_backend_cooldown(backend_id: str, cooldown_until: str, count: int) -> bool:
|
||||||
|
"""Set cooldown state on a backend."""
|
||||||
|
now = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
|
||||||
|
with get_connection() as conn:
|
||||||
|
cursor = conn.execute(
|
||||||
|
"""UPDATE backends SET status = 'cooling', cooldown_until = ?,
|
||||||
|
consecutive_429_count = ?, updated_at = ? WHERE id = ?""",
|
||||||
|
(cooldown_until, count, now, backend_id),
|
||||||
|
)
|
||||||
|
conn.commit()
|
||||||
|
return cursor.rowcount > 0
|
||||||
|
|
||||||
|
|
||||||
|
def clear_backend_cooldown(backend_id: str) -> bool:
|
||||||
|
"""Clear cooldown (back to healthy)."""
|
||||||
|
now = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
|
||||||
|
with get_connection() as conn:
|
||||||
|
cursor = conn.execute(
|
||||||
|
"""UPDATE backends SET status = 'healthy', cooldown_until = NULL,
|
||||||
|
consecutive_429_count = 0, updated_at = ? WHERE id = ?""",
|
||||||
|
(now, backend_id),
|
||||||
|
)
|
||||||
|
conn.commit()
|
||||||
|
return cursor.rowcount > 0
|
||||||
|
|
||||||
|
|
||||||
|
def get_pool_stats() -> dict:
|
||||||
|
"""Get summary stats per pool."""
|
||||||
|
with get_connection() as conn:
|
||||||
|
rows = conn.execute(
|
||||||
|
"""SELECT pool, COUNT(*) as total,
|
||||||
|
SUM(CASE WHEN enabled = 1 THEN 1 ELSE 0 END) as enabled,
|
||||||
|
SUM(CASE WHEN status = 'healthy' THEN 1 ELSE 0 END) as healthy,
|
||||||
|
SUM(CASE WHEN status = 'cooling' THEN 1 ELSE 0 END) as cooling,
|
||||||
|
SUM(CASE WHEN status = 'error' THEN 1 ELSE 0 END) as error
|
||||||
|
FROM backends GROUP BY pool"""
|
||||||
|
).fetchall()
|
||||||
|
stats = {}
|
||||||
|
for row in rows:
|
||||||
|
stats[row["pool"]] = {
|
||||||
|
"total": row["total"],
|
||||||
|
"enabled": row["enabled"],
|
||||||
|
"healthy": row["healthy"],
|
||||||
|
"cooling": row["cooling"],
|
||||||
|
"error": row["error"],
|
||||||
|
}
|
||||||
|
return stats
|
||||||
|
|
||||||
|
|
||||||
|
def _row_to_backend(row, decrypt_key: bool = True) -> Backend:
|
||||||
|
"""Convert a DB row to a Backend instance."""
|
||||||
|
mappings_raw = row["model_mappings_json"] or "{}"
|
||||||
|
mappings_dict = json.loads(mappings_raw)
|
||||||
|
|
||||||
|
model_mappings = {}
|
||||||
|
for canonical_name, mm in mappings_dict.items():
|
||||||
|
model_mappings[canonical_name] = ModelMapping.from_dict(mm)
|
||||||
|
|
||||||
|
backend = Backend(
|
||||||
|
id=row["id"],
|
||||||
|
name=row["name"],
|
||||||
|
label=row["label"],
|
||||||
|
api_base_url=row["api_base_url"],
|
||||||
|
api_key_encrypted=row["api_key_encrypted"] or "",
|
||||||
|
api=row["api"],
|
||||||
|
timeout_seconds=row["timeout_seconds"],
|
||||||
|
rpm_limit=row["rpm_limit"],
|
||||||
|
pool=row["pool"],
|
||||||
|
enabled=bool(row["enabled"]),
|
||||||
|
status=row["status"],
|
||||||
|
model_mappings=model_mappings,
|
||||||
|
source=row["source"],
|
||||||
|
cooldown_until=row["cooldown_until"],
|
||||||
|
consecutive_429_count=row["consecutive_429_count"],
|
||||||
|
metadata=json.loads(row["metadata_json"] or "{}"),
|
||||||
|
created_at=row["created_at"],
|
||||||
|
updated_at=row["updated_at"],
|
||||||
|
)
|
||||||
|
|
||||||
|
if decrypt_key and backend.api_key_encrypted:
|
||||||
|
from crypto import try_decrypt_existing
|
||||||
|
plain = try_decrypt_existing(backend.api_key_encrypted)
|
||||||
|
if plain:
|
||||||
|
backend.api_key_plain = plain
|
||||||
|
|
||||||
|
return backend
|
||||||
|
|
||||||
|
|
||||||
|
def _mappings_to_dict(mappings: dict[str, ModelMapping]) -> dict:
|
||||||
|
"""Convert ModelMapping dict to JSON-safe dict."""
|
||||||
|
return {k: v.to_dict() for k, v in mappings.items()}
|
||||||
@@ -0,0 +1,55 @@
|
|||||||
|
"""System configuration KV store operations."""
|
||||||
|
|
||||||
|
import time
|
||||||
|
from typing import Optional, Any
|
||||||
|
|
||||||
|
from storage.db import get_connection
|
||||||
|
|
||||||
|
|
||||||
|
def get_config(key: str) -> Optional[str]:
|
||||||
|
"""Get a single config value."""
|
||||||
|
with get_connection() as conn:
|
||||||
|
row = conn.execute(
|
||||||
|
"SELECT value FROM system_config WHERE key = ?", (key,)
|
||||||
|
).fetchone()
|
||||||
|
return row["value"] if row else None
|
||||||
|
|
||||||
|
|
||||||
|
def set_config(key: str, value: str, description: str = "") -> None:
|
||||||
|
"""Set or update a config value."""
|
||||||
|
now = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
|
||||||
|
with get_connection() as conn:
|
||||||
|
conn.execute(
|
||||||
|
"""INSERT INTO system_config (key, value, description, updated_at)
|
||||||
|
VALUES (?, ?, ?, ?)
|
||||||
|
ON CONFLICT(key) DO UPDATE SET
|
||||||
|
value = excluded.value,
|
||||||
|
description = excluded.description,
|
||||||
|
updated_at = excluded.updated_at""",
|
||||||
|
(key, value, description, now),
|
||||||
|
)
|
||||||
|
conn.commit()
|
||||||
|
|
||||||
|
|
||||||
|
def delete_config(key: str) -> bool:
|
||||||
|
"""Delete a config value."""
|
||||||
|
with get_connection() as conn:
|
||||||
|
cursor = conn.execute(
|
||||||
|
"DELETE FROM system_config WHERE key = ?", (key,)
|
||||||
|
)
|
||||||
|
conn.commit()
|
||||||
|
return cursor.rowcount > 0
|
||||||
|
|
||||||
|
|
||||||
|
def list_configs() -> list[dict]:
|
||||||
|
"""List all system config entries."""
|
||||||
|
with get_connection() as conn:
|
||||||
|
rows = conn.execute("SELECT * FROM system_config ORDER BY key").fetchall()
|
||||||
|
return [dict(row) for row in rows]
|
||||||
|
|
||||||
|
|
||||||
|
def get_all_configs_as_dict() -> dict[str, str]:
|
||||||
|
"""Get all configs as a simple dict."""
|
||||||
|
with get_connection() as conn:
|
||||||
|
rows = conn.execute("SELECT key, value FROM system_config").fetchall()
|
||||||
|
return {row["key"]: row["value"] for row in rows}
|
||||||
@@ -0,0 +1,74 @@
|
|||||||
|
"""Cooldown event logging."""
|
||||||
|
|
||||||
|
import time
|
||||||
|
from typing import Optional
|
||||||
|
|
||||||
|
from storage.db import get_connection, generate_id
|
||||||
|
from storage.models import CooldownEvent
|
||||||
|
|
||||||
|
|
||||||
|
def log_cooldown_event(
|
||||||
|
backend_id: str,
|
||||||
|
consecutive_count: int,
|
||||||
|
cooldown_seconds: int,
|
||||||
|
response_summary: str = "",
|
||||||
|
) -> CooldownEvent:
|
||||||
|
"""Record a cooldown event."""
|
||||||
|
event = CooldownEvent(
|
||||||
|
id=generate_id("cev"),
|
||||||
|
backend_id=backend_id,
|
||||||
|
consecutive_count=consecutive_count,
|
||||||
|
cooldown_seconds=cooldown_seconds,
|
||||||
|
response_summary=response_summary,
|
||||||
|
started_at=time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
|
||||||
|
)
|
||||||
|
|
||||||
|
with get_connection() as conn:
|
||||||
|
conn.execute(
|
||||||
|
"""INSERT INTO cooldown_events
|
||||||
|
(id, backend_id, consecutive_count, cooldown_seconds,
|
||||||
|
response_summary, started_at)
|
||||||
|
VALUES (?, ?, ?, ?, ?, ?)""",
|
||||||
|
(event.id, event.backend_id, event.consecutive_count,
|
||||||
|
event.cooldown_seconds, event.response_summary, event.started_at),
|
||||||
|
)
|
||||||
|
conn.commit()
|
||||||
|
|
||||||
|
return event
|
||||||
|
|
||||||
|
|
||||||
|
def end_cooldown_event(backend_id: str) -> bool:
|
||||||
|
"""Mark the latest open cooldown event as ended."""
|
||||||
|
ended_at = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
|
||||||
|
with get_connection() as conn:
|
||||||
|
# Find the latest event for this backend that hasn't ended
|
||||||
|
cursor = conn.execute(
|
||||||
|
"""UPDATE cooldown_events SET ended_at = ?
|
||||||
|
WHERE backend_id = ? AND ended_at IS NULL
|
||||||
|
ORDER BY started_at DESC LIMIT 1""",
|
||||||
|
(ended_at, backend_id),
|
||||||
|
)
|
||||||
|
conn.commit()
|
||||||
|
return cursor.rowcount > 0
|
||||||
|
|
||||||
|
|
||||||
|
def get_cooldown_history(
|
||||||
|
backend_id: Optional[str] = None,
|
||||||
|
limit: int = 50,
|
||||||
|
) -> list[dict]:
|
||||||
|
"""Get cooldown event history."""
|
||||||
|
with get_connection() as conn:
|
||||||
|
if backend_id:
|
||||||
|
rows = conn.execute(
|
||||||
|
"""SELECT * FROM cooldown_events
|
||||||
|
WHERE backend_id = ?
|
||||||
|
ORDER BY started_at DESC LIMIT ?""",
|
||||||
|
(backend_id, limit),
|
||||||
|
).fetchall()
|
||||||
|
else:
|
||||||
|
rows = conn.execute(
|
||||||
|
"""SELECT * FROM cooldown_events
|
||||||
|
ORDER BY started_at DESC LIMIT ?""",
|
||||||
|
(limit,),
|
||||||
|
).fetchall()
|
||||||
|
return [dict(row) for row in rows]
|
||||||
@@ -0,0 +1,193 @@
|
|||||||
|
"""SQLite database connection management with WAL mode."""
|
||||||
|
|
||||||
|
import os
|
||||||
|
import sqlite3
|
||||||
|
import uuid
|
||||||
|
import structlog
|
||||||
|
from contextlib import contextmanager
|
||||||
|
from typing import Generator
|
||||||
|
|
||||||
|
from config import config
|
||||||
|
|
||||||
|
logger = structlog.get_logger()
|
||||||
|
|
||||||
|
# Module-level DB path
|
||||||
|
_DB_PATH: str = ""
|
||||||
|
|
||||||
|
|
||||||
|
def init_db(db_path: str = "") -> None:
|
||||||
|
"""Initialize the database connection and ensure WAL mode.
|
||||||
|
|
||||||
|
Creates the data directory if needed and verifies integrity.
|
||||||
|
"""
|
||||||
|
global _DB_PATH
|
||||||
|
_DB_PATH = db_path or config.db_path
|
||||||
|
|
||||||
|
# Ensure data directory exists
|
||||||
|
os.makedirs(os.path.dirname(_DB_PATH), exist_ok=True)
|
||||||
|
|
||||||
|
# Test connection and enable WAL
|
||||||
|
conn = _get_raw_connection()
|
||||||
|
try:
|
||||||
|
conn.execute("PRAGMA journal_mode=WAL")
|
||||||
|
conn.execute("PRAGMA wal_autocheckpoint=1000")
|
||||||
|
conn.execute("PRAGMA foreign_keys=ON")
|
||||||
|
conn.execute("PRAGMA busy_timeout=5000")
|
||||||
|
logger.info("db_initialized", path=_DB_PATH, mode="WAL")
|
||||||
|
finally:
|
||||||
|
conn.close()
|
||||||
|
|
||||||
|
|
||||||
|
def _get_raw_connection() -> sqlite3.Connection:
|
||||||
|
"""Get a raw sqlite3 connection."""
|
||||||
|
conn = sqlite3.connect(_DB_PATH, check_same_thread=False)
|
||||||
|
conn.row_factory = sqlite3.Row
|
||||||
|
conn.execute("PRAGMA journal_mode=WAL")
|
||||||
|
conn.execute("PRAGMA foreign_keys=ON")
|
||||||
|
return conn
|
||||||
|
|
||||||
|
|
||||||
|
@contextmanager
|
||||||
|
def get_connection() -> Generator[sqlite3.Connection, None, None]:
|
||||||
|
"""Get a database connection with WAL enabled."""
|
||||||
|
conn = _get_raw_connection()
|
||||||
|
try:
|
||||||
|
yield conn
|
||||||
|
finally:
|
||||||
|
conn.close()
|
||||||
|
|
||||||
|
|
||||||
|
def generate_id(prefix: str = "") -> str:
|
||||||
|
"""Generate a unique ID with optional prefix."""
|
||||||
|
uid = uuid.uuid4().hex[:12]
|
||||||
|
return f"{prefix}_{uid}" if prefix else uid
|
||||||
|
|
||||||
|
|
||||||
|
def create_tables() -> None:
|
||||||
|
"""Create all tables if they don't exist."""
|
||||||
|
with get_connection() as conn:
|
||||||
|
conn.executescript(_DDL)
|
||||||
|
conn.commit()
|
||||||
|
logger.info("tables_created")
|
||||||
|
|
||||||
|
|
||||||
|
def run_integrity_check() -> bool:
|
||||||
|
"""Run PRAGMA integrity_check and return True if OK."""
|
||||||
|
with get_connection() as conn:
|
||||||
|
result = conn.execute("PRAGMA integrity_check").fetchone()
|
||||||
|
ok = result[0] == "ok"
|
||||||
|
if not ok:
|
||||||
|
logger.error("integrity_check_failed", result=result[0])
|
||||||
|
return ok
|
||||||
|
|
||||||
|
|
||||||
|
def get_db_sizes() -> dict:
|
||||||
|
"""Get database and WAL file sizes."""
|
||||||
|
result = {"db_bytes": 0, "wal_bytes": 0}
|
||||||
|
db_path = _DB_PATH
|
||||||
|
if os.path.exists(db_path):
|
||||||
|
result["db_bytes"] = os.path.getsize(db_path)
|
||||||
|
wal_path = db_path + "-wal"
|
||||||
|
if os.path.exists(wal_path):
|
||||||
|
result["wal_bytes"] = os.path.getsize(wal_path)
|
||||||
|
return result
|
||||||
|
|
||||||
|
|
||||||
|
def wal_checkpoint(mode: str = "TRUNCATE") -> None:
|
||||||
|
"""Execute WAL checkpoint."""
|
||||||
|
with get_connection() as conn:
|
||||||
|
conn.execute(f"PRAGMA wal_checkpoint({mode})")
|
||||||
|
|
||||||
|
|
||||||
|
_DDL = """
|
||||||
|
-- Backend configuration table (core)
|
||||||
|
CREATE TABLE IF NOT EXISTS backends (
|
||||||
|
id TEXT PRIMARY KEY,
|
||||||
|
name TEXT NOT NULL,
|
||||||
|
label TEXT DEFAULT '',
|
||||||
|
api_base_url TEXT NOT NULL,
|
||||||
|
api_key_encrypted TEXT NOT NULL,
|
||||||
|
api TEXT NOT NULL DEFAULT 'openai-completions',
|
||||||
|
timeout_seconds INTEGER NOT NULL DEFAULT 120,
|
||||||
|
rpm_limit INTEGER NOT NULL DEFAULT 40,
|
||||||
|
pool TEXT NOT NULL DEFAULT 'primary'
|
||||||
|
CHECK(pool IN ('primary', 'fallback')),
|
||||||
|
enabled INTEGER NOT NULL DEFAULT 1,
|
||||||
|
status TEXT NOT NULL DEFAULT 'healthy'
|
||||||
|
CHECK(status IN ('healthy', 'cooling', 'error', 'disabled')),
|
||||||
|
model_mappings_json TEXT DEFAULT '{}',
|
||||||
|
source TEXT NOT NULL DEFAULT 'webui'
|
||||||
|
CHECK(source IN ('webui', 'env', 'import')),
|
||||||
|
cooldown_until TEXT,
|
||||||
|
consecutive_429_count INTEGER DEFAULT 0,
|
||||||
|
metadata_json TEXT DEFAULT '{}',
|
||||||
|
created_at TEXT NOT NULL DEFAULT (datetime('now')),
|
||||||
|
updated_at TEXT NOT NULL DEFAULT (datetime('now'))
|
||||||
|
);
|
||||||
|
|
||||||
|
-- Usage logs (hour-bucketed, UPSERT-safe)
|
||||||
|
CREATE TABLE IF NOT EXISTS backend_usage_logs (
|
||||||
|
id TEXT PRIMARY KEY,
|
||||||
|
backend_id TEXT NOT NULL REFERENCES backends(id) ON DELETE CASCADE,
|
||||||
|
model TEXT DEFAULT 'unknown',
|
||||||
|
prompt_tokens INTEGER DEFAULT 0,
|
||||||
|
completion_tokens INTEGER DEFAULT 0,
|
||||||
|
total_tokens INTEGER DEFAULT 0,
|
||||||
|
cost REAL DEFAULT 0.0,
|
||||||
|
request_count INTEGER DEFAULT 0,
|
||||||
|
error_count INTEGER DEFAULT 0,
|
||||||
|
avg_latency_ms INTEGER DEFAULT 0,
|
||||||
|
ttft_ms INTEGER DEFAULT 0,
|
||||||
|
hour_bucket TEXT NOT NULL,
|
||||||
|
created_at TEXT NOT NULL DEFAULT (datetime('now'))
|
||||||
|
);
|
||||||
|
CREATE UNIQUE INDEX IF NOT EXISTS idx_usage_backend_hour
|
||||||
|
ON backend_usage_logs(backend_id, hour_bucket);
|
||||||
|
|
||||||
|
-- Cooldown event log
|
||||||
|
CREATE TABLE IF NOT EXISTS cooldown_events (
|
||||||
|
id TEXT PRIMARY KEY,
|
||||||
|
backend_id TEXT NOT NULL REFERENCES backends(id) ON DELETE CASCADE,
|
||||||
|
consecutive_count INTEGER NOT NULL DEFAULT 1,
|
||||||
|
cooldown_seconds INTEGER NOT NULL,
|
||||||
|
response_summary TEXT DEFAULT '',
|
||||||
|
started_at TEXT NOT NULL DEFAULT (datetime('now')),
|
||||||
|
ended_at TEXT
|
||||||
|
);
|
||||||
|
CREATE INDEX IF NOT EXISTS idx_cooldown_backend_time
|
||||||
|
ON cooldown_events(backend_id, started_at);
|
||||||
|
|
||||||
|
-- Backend health state
|
||||||
|
CREATE TABLE IF NOT EXISTS backend_health (
|
||||||
|
backend_id TEXT PRIMARY KEY REFERENCES backends(id) ON DELETE CASCADE,
|
||||||
|
state TEXT NOT NULL DEFAULT 'healthy'
|
||||||
|
CHECK(state IN ('healthy', 'degraded', 'down')),
|
||||||
|
last_latency_ms INTEGER DEFAULT 0,
|
||||||
|
last_status_code INTEGER DEFAULT 200,
|
||||||
|
success_rate_5m REAL DEFAULT 1.0,
|
||||||
|
consecutive_failures INTEGER DEFAULT 0,
|
||||||
|
last_check_at TEXT NOT NULL DEFAULT (datetime('now'))
|
||||||
|
);
|
||||||
|
|
||||||
|
-- System configuration KV store
|
||||||
|
CREATE TABLE IF NOT EXISTS system_config (
|
||||||
|
key TEXT PRIMARY KEY,
|
||||||
|
value TEXT NOT NULL,
|
||||||
|
description TEXT DEFAULT '',
|
||||||
|
updated_at TEXT NOT NULL DEFAULT (datetime('now'))
|
||||||
|
);
|
||||||
|
|
||||||
|
-- Daily aggregated stats
|
||||||
|
CREATE TABLE IF NOT EXISTS daily_stats (
|
||||||
|
id TEXT PRIMARY KEY,
|
||||||
|
date TEXT NOT NULL,
|
||||||
|
pool TEXT NOT NULL CHECK(pool IN ('primary', 'fallback')),
|
||||||
|
total_requests INTEGER DEFAULT 0,
|
||||||
|
total_errors INTEGER DEFAULT 0,
|
||||||
|
total_tokens INTEGER DEFAULT 0,
|
||||||
|
total_cost REAL DEFAULT 0.0,
|
||||||
|
unique_backends INTEGER DEFAULT 0,
|
||||||
|
created_at TEXT NOT NULL DEFAULT (datetime('now'))
|
||||||
|
);
|
||||||
|
CREATE UNIQUE INDEX IF NOT EXISTS idx_daily_date_pool ON daily_stats(date, pool);
|
||||||
|
"""
|
||||||
@@ -0,0 +1,161 @@
|
|||||||
|
"""Data models for Sidecar V2 — backend-centric, Canonical Name routing."""
|
||||||
|
|
||||||
|
from dataclasses import dataclass, field, asdict
|
||||||
|
from typing import Optional
|
||||||
|
import json
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class ModelMapping:
|
||||||
|
"""A single model mapping within a backend: Canonical Name → native_id + properties."""
|
||||||
|
|
||||||
|
native_id: str
|
||||||
|
reasoning: bool = False
|
||||||
|
reasoning_effort: bool = False
|
||||||
|
input_modalities: list[str] = field(default_factory=lambda: ["text"])
|
||||||
|
cost: dict = field(default_factory=lambda: {
|
||||||
|
"input": 0.0, "output": 0.0, "cacheRead": 0.0, "cacheWrite": 0.0
|
||||||
|
})
|
||||||
|
context_window: int = 128000
|
||||||
|
max_tokens: int = 65536
|
||||||
|
compat: dict = field(default_factory=dict)
|
||||||
|
|
||||||
|
def to_dict(self) -> dict:
|
||||||
|
return asdict(self)
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
def from_dict(cls, d: dict) -> "ModelMapping":
|
||||||
|
defaults = {
|
||||||
|
"native_id": "",
|
||||||
|
"reasoning": False,
|
||||||
|
"reasoning_effort": False,
|
||||||
|
"input_modalities": ["text"],
|
||||||
|
"cost": {"input": 0.0, "output": 0.0, "cacheRead": 0.0, "cacheWrite": 0.0},
|
||||||
|
"context_window": 128000,
|
||||||
|
"max_tokens": 65536,
|
||||||
|
"compat": {},
|
||||||
|
}
|
||||||
|
defaults.update(d)
|
||||||
|
return cls(**{k: v for k, v in defaults.items() if k in cls.__dataclass_fields__})
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class Backend:
|
||||||
|
"""A physical API backend (API Key + URL).
|
||||||
|
|
||||||
|
Represents a single API key endpoint. Multiple backends can serve the same
|
||||||
|
Canonical Models through their model_mappings.
|
||||||
|
"""
|
||||||
|
|
||||||
|
id: str = ""
|
||||||
|
name: str = ""
|
||||||
|
label: str = "" # e.g., "nvidia", "siliconflow" — WebUI tag only
|
||||||
|
api_base_url: str = ""
|
||||||
|
api_key_encrypted: str = ""
|
||||||
|
api: str = "openai-completions"
|
||||||
|
timeout_seconds: int = 120
|
||||||
|
rpm_limit: int = 40
|
||||||
|
pool: str = "primary" # primary | fallback
|
||||||
|
enabled: bool = True
|
||||||
|
status: str = "healthy" # healthy | cooling | error | disabled
|
||||||
|
model_mappings: dict[str, ModelMapping] = field(default_factory=dict)
|
||||||
|
source: str = "webui" # webui | env | import
|
||||||
|
cooldown_until: Optional[str] = None
|
||||||
|
consecutive_429_count: int = 0
|
||||||
|
metadata: dict = field(default_factory=dict)
|
||||||
|
created_at: str = ""
|
||||||
|
updated_at: str = ""
|
||||||
|
|
||||||
|
# Runtime fields (not persisted)
|
||||||
|
api_key_plain: str = "" # decrypted at load time, not serialized to DB
|
||||||
|
|
||||||
|
def has_model(self, canonical_name: str) -> bool:
|
||||||
|
"""Check if backend supports a given Canonical Model."""
|
||||||
|
return canonical_name in self.model_mappings
|
||||||
|
|
||||||
|
def get_native_id(self, canonical_name: str) -> str:
|
||||||
|
"""Get this backend's native model ID for a Canonical Name."""
|
||||||
|
mm = self.model_mappings.get(canonical_name)
|
||||||
|
return mm.native_id if mm else canonical_name
|
||||||
|
|
||||||
|
def get_model_cost(self, canonical_name: str) -> dict:
|
||||||
|
"""Get cost info for a Canonical Model on this backend."""
|
||||||
|
mm = self.model_mappings.get(canonical_name)
|
||||||
|
return mm.cost if mm else {"input": 0.0, "output": 0.0, "cacheRead": 0.0, "cacheWrite": 0.0}
|
||||||
|
|
||||||
|
def to_dict(self, mask_key: bool = True) -> dict:
|
||||||
|
"""Convert to dict for API responses."""
|
||||||
|
d = asdict(self)
|
||||||
|
# Remove runtime-only fields
|
||||||
|
d.pop("api_key_plain", None)
|
||||||
|
d.pop("api_key_encrypted", None)
|
||||||
|
|
||||||
|
# Mask API key
|
||||||
|
if mask_key and self.api_key_plain:
|
||||||
|
d["api_key"] = _mask_key(self.api_key_plain)
|
||||||
|
elif self.api_key_plain:
|
||||||
|
d["api_key"] = self.api_key_plain
|
||||||
|
else:
|
||||||
|
d["api_key"] = ""
|
||||||
|
|
||||||
|
# Convert model_mappings to dict for serialization
|
||||||
|
d["model_mappings"] = {
|
||||||
|
k: v.to_dict() for k, v in self.model_mappings.items()
|
||||||
|
}
|
||||||
|
return d
|
||||||
|
|
||||||
|
|
||||||
|
def _mask_key(key: str) -> str:
|
||||||
|
if len(key) <= 10:
|
||||||
|
return key[:2] + "****"
|
||||||
|
return key[:6] + "****" + key[-4:]
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class CooldownEvent:
|
||||||
|
id: str = ""
|
||||||
|
backend_id: str = ""
|
||||||
|
consecutive_count: int = 1
|
||||||
|
cooldown_seconds: int = 60
|
||||||
|
response_summary: str = ""
|
||||||
|
started_at: str = ""
|
||||||
|
ended_at: Optional[str] = None
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class BackendHealth:
|
||||||
|
backend_id: str = ""
|
||||||
|
state: str = "healthy" # healthy | degraded | down
|
||||||
|
last_latency_ms: int = 0
|
||||||
|
last_status_code: int = 200
|
||||||
|
success_rate_5m: float = 1.0
|
||||||
|
consecutive_failures: int = 0
|
||||||
|
last_check_at: str = ""
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class UsageLog:
|
||||||
|
id: str = ""
|
||||||
|
backend_id: str = ""
|
||||||
|
model: str = "unknown"
|
||||||
|
prompt_tokens: int = 0
|
||||||
|
completion_tokens: int = 0
|
||||||
|
total_tokens: int = 0
|
||||||
|
cost: float = 0.0
|
||||||
|
request_count: int = 0
|
||||||
|
error_count: int = 0
|
||||||
|
avg_latency_ms: int = 0
|
||||||
|
ttft_ms: int = 0
|
||||||
|
hour_bucket: str = ""
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class DailyStats:
|
||||||
|
id: str = ""
|
||||||
|
date: str = ""
|
||||||
|
pool: str = "primary"
|
||||||
|
total_requests: int = 0
|
||||||
|
total_errors: int = 0
|
||||||
|
total_tokens: int = 0
|
||||||
|
total_cost: float = 0.0
|
||||||
|
unique_backends: int = 0
|
||||||
@@ -0,0 +1,155 @@
|
|||||||
|
"""Usage logging and daily statistics aggregation."""
|
||||||
|
|
||||||
|
import time
|
||||||
|
from typing import Optional
|
||||||
|
|
||||||
|
from storage.db import get_connection, generate_id
|
||||||
|
|
||||||
|
|
||||||
|
def record_usage(
|
||||||
|
backend_id: str,
|
||||||
|
model: str,
|
||||||
|
prompt_tokens: int,
|
||||||
|
completion_tokens: int,
|
||||||
|
cost: float,
|
||||||
|
latency_ms: int,
|
||||||
|
ttft_ms: int = 0,
|
||||||
|
is_error: bool = False,
|
||||||
|
) -> None:
|
||||||
|
"""Record a single request's usage, hour-bucketed with UPSERT."""
|
||||||
|
hour_bucket = time.strftime("%Y-%m-%dT%H:00:00Z", time.gmtime())
|
||||||
|
uid = generate_id("use")
|
||||||
|
|
||||||
|
with get_connection() as conn:
|
||||||
|
# Try update existing hour bucket
|
||||||
|
cursor = conn.execute(
|
||||||
|
"""UPDATE backend_usage_logs SET
|
||||||
|
prompt_tokens = prompt_tokens + ?,
|
||||||
|
completion_tokens = completion_tokens + ?,
|
||||||
|
total_tokens = total_tokens + ?,
|
||||||
|
cost = cost + ?,
|
||||||
|
request_count = request_count + 1,
|
||||||
|
error_count = error_count + ?,
|
||||||
|
avg_latency_ms = CAST((avg_latency_ms * request_count + ?) / (request_count + 1) AS INTEGER),
|
||||||
|
ttft_ms = CASE WHEN ? > 0 THEN CAST((ttft_ms * request_count + ?) / (request_count + 1) AS INTEGER) ELSE ttft_ms END
|
||||||
|
WHERE backend_id = ? AND hour_bucket = ?""",
|
||||||
|
(
|
||||||
|
prompt_tokens, completion_tokens,
|
||||||
|
prompt_tokens + completion_tokens,
|
||||||
|
cost,
|
||||||
|
1 if is_error else 0,
|
||||||
|
latency_ms,
|
||||||
|
ttft_ms, ttft_ms,
|
||||||
|
backend_id, hour_bucket,
|
||||||
|
),
|
||||||
|
)
|
||||||
|
if cursor.rowcount == 0:
|
||||||
|
# Insert new hour bucket
|
||||||
|
conn.execute(
|
||||||
|
"""INSERT INTO backend_usage_logs
|
||||||
|
(id, backend_id, model, prompt_tokens, completion_tokens,
|
||||||
|
total_tokens, cost, request_count, error_count,
|
||||||
|
avg_latency_ms, ttft_ms, hour_bucket)
|
||||||
|
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
|
||||||
|
(
|
||||||
|
uid, backend_id, model,
|
||||||
|
prompt_tokens, completion_tokens,
|
||||||
|
prompt_tokens + completion_tokens,
|
||||||
|
cost, 1, 1 if is_error else 0,
|
||||||
|
latency_ms, ttft_ms, hour_bucket,
|
||||||
|
),
|
||||||
|
)
|
||||||
|
conn.commit()
|
||||||
|
|
||||||
|
|
||||||
|
def get_hourly_usage(
|
||||||
|
backend_id: Optional[str] = None,
|
||||||
|
since: Optional[str] = None,
|
||||||
|
limit: int = 168,
|
||||||
|
) -> list[dict]:
|
||||||
|
"""Get hourly usage data, optionally filtered by backend and time range."""
|
||||||
|
with get_connection() as conn:
|
||||||
|
if backend_id and since:
|
||||||
|
rows = conn.execute(
|
||||||
|
"""SELECT * FROM backend_usage_logs
|
||||||
|
WHERE backend_id = ? AND hour_bucket >= ?
|
||||||
|
ORDER BY hour_bucket DESC LIMIT ?""",
|
||||||
|
(backend_id, since, limit),
|
||||||
|
).fetchall()
|
||||||
|
elif backend_id:
|
||||||
|
rows = conn.execute(
|
||||||
|
"""SELECT * FROM backend_usage_logs
|
||||||
|
WHERE backend_id = ? ORDER BY hour_bucket DESC LIMIT ?""",
|
||||||
|
(backend_id, limit),
|
||||||
|
).fetchall()
|
||||||
|
elif since:
|
||||||
|
rows = conn.execute(
|
||||||
|
"""SELECT * FROM backend_usage_logs
|
||||||
|
WHERE hour_bucket >= ? ORDER BY hour_bucket DESC LIMIT ?""",
|
||||||
|
(since, limit),
|
||||||
|
).fetchall()
|
||||||
|
else:
|
||||||
|
rows = conn.execute(
|
||||||
|
"""SELECT * FROM backend_usage_logs
|
||||||
|
ORDER BY hour_bucket DESC LIMIT ?""",
|
||||||
|
(limit,),
|
||||||
|
).fetchall()
|
||||||
|
return [dict(row) for row in rows]
|
||||||
|
|
||||||
|
|
||||||
|
def get_total_stats() -> dict:
|
||||||
|
"""Get aggregate stats across all backends."""
|
||||||
|
with get_connection() as conn:
|
||||||
|
row = conn.execute(
|
||||||
|
"""SELECT
|
||||||
|
SUM(request_count) as total_requests,
|
||||||
|
SUM(error_count) as total_errors,
|
||||||
|
SUM(total_tokens) as total_tokens,
|
||||||
|
SUM(prompt_tokens) as total_prompt_tokens,
|
||||||
|
SUM(completion_tokens) as total_completion_tokens,
|
||||||
|
SUM(cost) as total_cost
|
||||||
|
FROM backend_usage_logs"""
|
||||||
|
).fetchone()
|
||||||
|
if row is None:
|
||||||
|
return {
|
||||||
|
"total_requests": 0, "total_errors": 0,
|
||||||
|
"total_tokens": 0, "total_prompt_tokens": 0,
|
||||||
|
"total_completion_tokens": 0, "total_cost": 0.0,
|
||||||
|
}
|
||||||
|
return dict(row)
|
||||||
|
|
||||||
|
|
||||||
|
def aggregate_daily_stats(date: str) -> None:
|
||||||
|
"""Aggregate hourly usage into daily stats table."""
|
||||||
|
with get_connection() as conn:
|
||||||
|
# Aggregate per pool
|
||||||
|
conn.execute("""DELETE FROM daily_stats WHERE date = ?""", (date,))
|
||||||
|
conn.execute(
|
||||||
|
"""INSERT INTO daily_stats (id, date, pool, total_requests,
|
||||||
|
total_errors, total_tokens, total_cost, unique_backends)
|
||||||
|
SELECT
|
||||||
|
? || '-' || b.pool,
|
||||||
|
?,
|
||||||
|
b.pool,
|
||||||
|
SUM(u.request_count),
|
||||||
|
SUM(u.error_count),
|
||||||
|
SUM(u.total_tokens),
|
||||||
|
SUM(u.cost),
|
||||||
|
COUNT(DISTINCT u.backend_id)
|
||||||
|
FROM backend_usage_logs u
|
||||||
|
JOIN backends b ON u.backend_id = b.id
|
||||||
|
WHERE u.hour_bucket LIKE ?
|
||||||
|
GROUP BY b.pool""",
|
||||||
|
(generate_id("day"), date, date + "%"),
|
||||||
|
)
|
||||||
|
conn.commit()
|
||||||
|
|
||||||
|
|
||||||
|
def get_daily_stats(days: int = 30) -> list[dict]:
|
||||||
|
"""Get daily aggregated stats."""
|
||||||
|
with get_connection() as conn:
|
||||||
|
rows = conn.execute(
|
||||||
|
"""SELECT * FROM daily_stats ORDER BY date DESC LIMIT ?""",
|
||||||
|
(days,),
|
||||||
|
).fetchall()
|
||||||
|
return [dict(row) for row in rows]
|
||||||
@@ -1,252 +0,0 @@
|
|||||||
# 知识缺口上报 SOP v1.0
|
|
||||||
|
|
||||||
> 生效日期：2026-07-06 | 负责人：COO（陆怀瑾） | 审批：刘总 2026-07-06
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 一、什么是知识缺口
|
|
||||||
|
|
||||||
**知识缺口**指 Agent 在任务执行过程中遇到的、无法通过现有知识库检索到的关键信息缺失，且该缺失会影响任务交付质量或导致决策偏差。
|
|
||||||
|
|
||||||
### 1.1 触发条件（满足任一即需上报）
|
|
||||||
|
|
||||||
| 场景 | 示例 | 上报优先级 |
|
|
||||||
|------|------|-----------|
|
|
||||||
| **核心业务数据缺失** | 某业务线 KPI 无历史记录、竞品分析无基准数据 | 高 |
|
|
||||||
| **SOP/流程文档不存在** | 需要执行某流程但无标准文档可查 | 高 |
|
|
||||||
| **关键决策依据缺失** | 需要历史决策记录但检索无结果 | 中 |
|
|
||||||
| **外部信息无法验证** | 需要核实供应商资质/合同条款但无存档 | 中 |
|
|
||||||
| **技术文档/API 文档缺失** | 需要调用某系统 API 但无文档 | 中 |
|
|
||||||
| **Agent 配置/技能文档缺失** | 新 Agent 接入时无 AGENTS.md/SOUL.md 参考 | 低 |
|
|
||||||
|
|
||||||
### 1.2 不属于知识缺口的情况
|
|
||||||
|
|
||||||
- 可通过 `web_search` / `tavily_search` 快速获取的公开信息 → 自行检索，不上报
|
|
||||||
- 可通过 `memory_search` / `wiki_search` 检索到的现有知识 → 自行读取，不上报
|
|
||||||
- 任务执行中的临时疑问（不影响交付） → 记录在任务评论中，不上报
|
|
||||||
- 可通过联系对应 Agent 获得的信息 → 直接联系，不上报
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 二、上报流程
|
|
||||||
|
|
||||||
### 2.1 标准流程（5 步）
|
|
||||||
|
|
||||||
```
|
|
||||||
发现知识缺口
|
|
||||||
↓
|
|
||||||
步骤 1：记录缺口（在任务评论中）
|
|
||||||
↓
|
|
||||||
步骤 2：通知 COO（飞书消息）
|
|
||||||
↓
|
|
||||||
步骤 3：COO 评估优先级（高/中/低）
|
|
||||||
↓
|
|
||||||
步骤 4：创建 WorkBoard 卡片（分配责任人）
|
|
||||||
↓
|
|
||||||
步骤 5：补全后通知原 Agent（关闭循环）
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2.2 步骤详解
|
|
||||||
|
|
||||||
#### 步骤 1：记录缺口
|
|
||||||
|
|
||||||
在**当前任务**的 Multica issue 或 WorkBoard 卡片评论中记录：
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## 📚 知识缺口上报
|
|
||||||
|
|
||||||
**缺口类型**：[核心业务数据 | SOP 缺失 | 决策依据 | 外部信息 | 技术文档 | Agent 配置]
|
|
||||||
**缺口描述**：[具体缺什么，为什么影响任务]
|
|
||||||
**影响范围**：[哪些任务/决策受影响]
|
|
||||||
**紧急程度**：[高/中/低]
|
|
||||||
**建议补全方式**：[需要谁提供 / 需要查什么 / 需要创建什么文档]
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 步骤 2：通知 COO
|
|
||||||
|
|
||||||
通过飞书消息通知 COO（陆怀瑾）：
|
|
||||||
|
|
||||||
```
|
|
||||||
【知识缺口上报 - 紧急程度：高/中/低】
|
|
||||||
|
|
||||||
任务：[任务标题/ID]
|
|
||||||
缺口：[一句话概括]
|
|
||||||
影响：[不补全的后果]
|
|
||||||
建议：[你希望怎么处理]
|
|
||||||
|
|
||||||
请评估并创建补全卡片。
|
|
||||||
```
|
|
||||||
|
|
||||||
**COO 飞书 ID**：`ou_9f73b4e54af59f038e2b754793ea0908`
|
|
||||||
|
|
||||||
#### 步骤 3：COO 评估
|
|
||||||
|
|
||||||
COO 在收到上报后 **2 小时内** 完成评估：
|
|
||||||
|
|
||||||
| 优先级 | 响应时效 | 处理方式 |
|
|
||||||
|--------|---------|---------|
|
|
||||||
| **高** | 立即处理 | 创建紧急卡片，分配专人，24h 内补全 |
|
|
||||||
| **中** | 当日内处理 | 创建常规卡片，纳入排期，48h 内补全 |
|
|
||||||
| **低** | 3 日内处理 | 纳入知识 backlog，周度批量处理 |
|
|
||||||
|
|
||||||
#### 步骤 4：创建补全卡片
|
|
||||||
|
|
||||||
COO 通过 WorkBoard 创建知识补全卡片：
|
|
||||||
|
|
||||||
- **标题**：`[知识补全] <缺口主题>`
|
|
||||||
- **描述**：引用原始上报评论
|
|
||||||
- **assignee**：对应领域负责人（见责任矩阵）
|
|
||||||
- **priority**：根据评估结果设定
|
|
||||||
- **labels**：`knowledge`, `gap`, `<领域>`
|
|
||||||
- **parent**：关联到原任务（可选）
|
|
||||||
|
|
||||||
#### 步骤 5：闭环通知
|
|
||||||
|
|
||||||
知识补全完成后：
|
|
||||||
|
|
||||||
1. 责任人在卡片中上传补全内容（文档链接 / 数据文件 / 决策记录）
|
|
||||||
2. COO 验收并关闭卡片
|
|
||||||
3. COO 飞书通知原上报 Agent：
|
|
||||||
```
|
|
||||||
【知识缺口已补全】
|
|
||||||
|
|
||||||
原缺口：[简述]
|
|
||||||
补全内容：[文档链接/说明]
|
|
||||||
归档位置：[知识库路径]
|
|
||||||
|
|
||||||
后续可直接检索使用。
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 三、责任矩阵（Who to Assign）
|
|
||||||
|
|
||||||
| 缺口类型 | 默认责任人 | 备选 |
|
|
||||||
|---------|-----------|------|
|
|
||||||
| 业务数据/KPI | marketanalysis（顾析策） | COO |
|
|
||||||
| SOP/流程文档 | COO（陆怀瑾） | projectmanager |
|
|
||||||
| 技术/API 文档 | opengineer（严维序） | architect |
|
|
||||||
| 产品需求/PRD | productmanager（沈路明） | COO |
|
|
||||||
| Agent 配置/技能 | COO（陆怀瑾） | 对应 Agent |
|
|
||||||
| 外部信息/供应商 | lawyer（苏慎） | COO |
|
|
||||||
| 设计/UI 规范 | designer（苏绘锦） | COO |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 四、上报渠道
|
|
||||||
|
|
||||||
### 4.1 主渠道：WorkBoard 评论 + 飞书通知
|
|
||||||
|
|
||||||
**适用场景**：所有正式知识缺口上报
|
|
||||||
|
|
||||||
**操作**：
|
|
||||||
1. 在原任务评论中记录缺口（格式见 2.2）
|
|
||||||
2. 飞书通知 COO
|
|
||||||
3. COO 创建 WorkBoard 卡片跟进
|
|
||||||
|
|
||||||
### 4.2 补充渠道：Multica Issue
|
|
||||||
|
|
||||||
**适用场景**：
|
|
||||||
- 任务本身在 Multica 上管理
|
|
||||||
- 需要技术团队协作的知识补全
|
|
||||||
- 涉及代码/配置/技术文档的缺口
|
|
||||||
|
|
||||||
**操作**：
|
|
||||||
1. 在原 issue 评论中记录缺口（格式同上）
|
|
||||||
2. 使用 `multica issue create` 创建补全任务：
|
|
||||||
```bash
|
|
||||||
multica issue create \
|
|
||||||
--title "[知识补全] <缺口主题>" \
|
|
||||||
--description-file gap_description.md \
|
|
||||||
--priority <high|medium|low> \
|
|
||||||
--assignee <责任人> \
|
|
||||||
--label knowledge,gap,<领域>
|
|
||||||
```
|
|
||||||
3. 飞书通知 COO 备案
|
|
||||||
|
|
||||||
### 4.3 紧急通道：直接联系 COO
|
|
||||||
|
|
||||||
**适用场景**：高优先级缺口，需立即处理
|
|
||||||
|
|
||||||
**操作**：
|
|
||||||
- 飞书直聊 COO，简要说明缺口和影响
|
|
||||||
- COO 口头确认后先行处理，事后补卡片
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 五、知识库质量监控（COO 职责）
|
|
||||||
|
|
||||||
### 5.1 周度巡检
|
|
||||||
|
|
||||||
COO 每周五执行：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 检查本周新增知识缺口上报数
|
|
||||||
# 检查补全卡片完成率
|
|
||||||
# 检查 gap 标签卡片积压情况
|
|
||||||
```
|
|
||||||
|
|
||||||
**指标**：
|
|
||||||
- 新增缺口数 ≤ 5 个/周（超标需分析根因）
|
|
||||||
- 补全完成率 ≥ 90%（48h SLA）
|
|
||||||
- 积压缺口数 ≤ 3 个
|
|
||||||
|
|
||||||
### 5.2 月度分析
|
|
||||||
|
|
||||||
每月底输出《知识缺口分析报告》：
|
|
||||||
|
|
||||||
- 缺口类型分布（哪类最常缺失）
|
|
||||||
- 根本原因分析（为什么缺失）
|
|
||||||
- 流程改进建议（如何预防）
|
|
||||||
- 责任人绩效（补全时效/质量）
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 六、纳入 TOOLS.md 模板
|
|
||||||
|
|
||||||
所有 Agent 的 `TOOLS.md` 必须包含以下章节（可放在"知识库查询"章节后）：
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## 📚 知识缺口上报
|
|
||||||
|
|
||||||
### 触发条件
|
|
||||||
|
|
||||||
遇到以下情况需上报知识缺口（而非自行 web_search）：
|
|
||||||
1. 核心业务数据/SOP/决策依据缺失
|
|
||||||
2. 缺失影响任务交付质量或决策准确性
|
|
||||||
3. 无法通过 memory_search/wiki_search 检索到
|
|
||||||
|
|
||||||
### 上报流程
|
|
||||||
|
|
||||||
1. **记录**：在任务评论中使用标准格式记录缺口
|
|
||||||
2. **通知**：飞书通知 COO（ou_9f73b4e54af59f038e2b754793ea0908）
|
|
||||||
3. **跟进**：COO 评估后创建补全卡片
|
|
||||||
4. **闭环**：补全后 COO 通知你可直接使用
|
|
||||||
|
|
||||||
### 标准格式
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## 📚 知识缺口上报
|
|
||||||
|
|
||||||
**缺口类型**：[核心业务数据 | SOP 缺失 | 决策依据 | 外部信息 | 技术文档]
|
|
||||||
**缺口描述**：[具体缺什么]
|
|
||||||
**影响范围**：[哪些任务受影响]
|
|
||||||
**紧急程度**：[高/中/低]
|
|
||||||
**建议补全方式**：[希望怎么处理]
|
|
||||||
```
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 七、版本历史
|
|
||||||
|
|
||||||
| 版本 | 日期 | 变更内容 | 审批 |
|
|
||||||
|------|------|---------|------|
|
|
||||||
| v1.0 | 2026-07-06 | 初始版本，建立完整上报流程 | 刘总 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**附件**：
|
|
||||||
- 知识缺口上报模板（见 2.2）
|
|
||||||
- 责任矩阵（见第三节）
|
|
||||||
- TOOLS.md 模板章节（见第六节）
|
|
||||||
@@ -1,159 +0,0 @@
|
|||||||
# SOP-016：执行前检索 SOP 强制规则
|
|
||||||
|
|
||||||
> **版本**: v1.0
|
|
||||||
> **起草人**: 胡蓉（projectmanager）
|
|
||||||
> **批准人**: 刘炜承
|
|
||||||
> **生效日期**: 2026-07-06
|
|
||||||
> **关联 Issue**: BIZ-81
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. 目的
|
|
||||||
|
|
||||||
解决 BIZ-45 巡检发现的 Agent 知识库调用率极低问题（徐聪 0%、诗妮 0%、沈路明 33%）。知识库已建立 SOP 但 Agent 不主动检索，导致重复造轮子、忽略历史经验、决策缺乏依据。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. 适用范围
|
|
||||||
|
|
||||||
全部 Agent（产研线 + 运营线 + 职能线），共 14 个。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 触发条件（任一触发即必须检索）
|
|
||||||
|
|
||||||
| # | 触发场景 | 说明 |
|
|
||||||
|---|----------|------|
|
|
||||||
| 1 | 接收新任务 | WorkBoard 认领 / Multica Issue / TODO.md 分派 / session_send 任务 |
|
|
||||||
| 2 | 任务涉及已知业务领域 | 开发/部署/运营/设计/内容/法务/市场等 |
|
|
||||||
| 3 | 需要技术选型、流程设计、资源分配决策 | 需参考历史方案 |
|
|
||||||
| 4 | 遇到不确定如何处理的问题 | 需查找是否有 SOP 或历史经验 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. 检索流程（严格执行）
|
|
||||||
|
|
||||||
```
|
|
||||||
开始任务
|
|
||||||
↓
|
|
||||||
Step 1: memory_search(corpus=all, query="<业务类型> SOP/历史经验")
|
|
||||||
↓
|
|
||||||
Step 2: 如有匹配 → memory_get / wiki_get 读取详细内容
|
|
||||||
↓
|
|
||||||
Step 3: 如无匹配 → wiki_search(query="<任务关键词>")
|
|
||||||
↓
|
|
||||||
Step 4: 仍无匹配 → exec curl 思源知识库全文搜索
|
|
||||||
↓
|
|
||||||
Step 5: 根据检索结果调整执行方案
|
|
||||||
↓
|
|
||||||
开始执行任务
|
|
||||||
```
|
|
||||||
|
|
||||||
### 查询构造规范
|
|
||||||
|
|
||||||
- **SOP 查询**: `memory_search(corpus=all, query="<业务类型> SOP")`
|
|
||||||
- 示例：`memory_search(corpus=all, query="项目拆解 SOP")`
|
|
||||||
- 示例：`memory_search(corpus=all, query="部署运维 SOP")`
|
|
||||||
|
|
||||||
- **历史经验查询**: `memory_search(corpus=all, query="<项目名> 决策/问题/方案")`
|
|
||||||
- 示例：`memory_search(corpus=all, query="知识库选型 决策")`
|
|
||||||
- 示例：`memory_search(corpus=all, query="Agent 任务积压 问题")`
|
|
||||||
|
|
||||||
- **结构化知识查询**: `wiki_search(query="<主题>")`
|
|
||||||
- 示例：`wiki_search(query="项目管理规范")`
|
|
||||||
|
|
||||||
- **思源知识库全文搜索**:
|
|
||||||
```bash
|
|
||||||
curl -s -X POST "http://192.168.1.99:6806/api/search/fullTextSearchBlock" \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-H "Authorization: Token 8ixgqexbnxgibk4u" \
|
|
||||||
-d '{"query":"<关键词>", "notebook":"20260623155217-njb0mkn"}'
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. 跳过条件（仅以下情况可跳过检索）
|
|
||||||
|
|
||||||
| # | 跳过场景 | 原因 |
|
|
||||||
|---|----------|------|
|
|
||||||
| 1 | 简单重复性任务 | 如"重启容器""发送消息"——已知操作无需检索 |
|
|
||||||
| 2 | 紧急故障处理 | 先止损，事后补检索 |
|
|
||||||
| 3 | 用户明确指示 | "不需要检索历史" |
|
|
||||||
| 4 | 纯闲聊/问候 | 无业务内容 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. 审计指标
|
|
||||||
|
|
||||||
### 月度检查项
|
|
||||||
|
|
||||||
| 指标 | 目标 | 检查方式 |
|
|
||||||
|------|------|----------|
|
|
||||||
| 检索覆盖率 | ≥80% | 对比有检索记录的任务数 / 总执行任务数 |
|
|
||||||
| query 相关性 | query 与任务内容匹配 | 抽查 query 与任务 brief 的关键词重合度 |
|
|
||||||
| 执行方案调整率 | 有检索的任务中 ≥30% 有方案调整 | 检查检索后是否在 notes/评论中记录调整 |
|
|
||||||
| 零检索执行 | <20% | 无检索记录直接执行的任务占比 |
|
|
||||||
|
|
||||||
### 纳入 Agent 行为审计
|
|
||||||
|
|
||||||
- ✅ 任务执行前有检索记录（memory_search / wiki_search 调用日志）
|
|
||||||
- ✅ 检索 query 与任务相关性强
|
|
||||||
- ✅ 根据检索结果调整了执行方案
|
|
||||||
- ❌ 无任何检索直接执行（除非符合跳过条件）
|
|
||||||
- ❌ 检索 query 过于笼统（如单字查询）
|
|
||||||
|
|
||||||
### 审计由 COO 月度执行
|
|
||||||
|
|
||||||
COO（陆怀瑾）每月 1 日检查上月全部 Agent 的检索执行情况，输出审计报告。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. AGENTS.md 注入模板
|
|
||||||
|
|
||||||
各 Agent 的 AGENTS.md 中需注入以下章节：
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## ⚠️ 执行前检索 SOP（强制规则）
|
|
||||||
|
|
||||||
> **BIZ-81 要求**：任务执行前必须先检索知识库，避免重复造轮子、忽略历史经验。
|
|
||||||
|
|
||||||
### 触发条件
|
|
||||||
以下情况**必须**执行检索（任一触发）：
|
|
||||||
- 接收到新任务（WorkBoard/Multica/TODO.md 认领）
|
|
||||||
- 任务涉及已知业务领域
|
|
||||||
- 需要做出技术选型、流程设计、资源分配决策
|
|
||||||
- 遇到不确定如何处理的问题
|
|
||||||
|
|
||||||
### 检索流程
|
|
||||||
Step 1: memory_search(corpus=all, query="任务关键词 SOP/历史经验")
|
|
||||||
Step 2: 如有匹配 → memory_get / wiki_get 读取详细内容
|
|
||||||
Step 3: 如无匹配 → wiki_search(query="任务关键词")
|
|
||||||
Step 4: 根据检索结果调整执行方案
|
|
||||||
→ 开始执行任务
|
|
||||||
|
|
||||||
### 跳过条件
|
|
||||||
- 简单重复性任务（如"重启容器""发送消息"）
|
|
||||||
- 紧急故障处理（先止损，事后补检索）
|
|
||||||
- 用户明确指示"不需要检索历史"
|
|
||||||
|
|
||||||
### 审计指标
|
|
||||||
以下行为将纳入 Agent 执行质量审计：
|
|
||||||
- ✅ 任务执行前有检索记录
|
|
||||||
- ✅ 检索 query 与任务相关性强
|
|
||||||
- ✅ 根据检索结果调整了执行方案
|
|
||||||
- ❌ 无任何检索直接执行（除非符合跳过条件）
|
|
||||||
- ❌ 检索 query 过于笼统
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. 生效与维护
|
|
||||||
|
|
||||||
- **生效日期**: 2026-07-06
|
|
||||||
- **维护人**: 胡蓉（projectmanager）
|
|
||||||
- **revision 周期**: 每季度 review 一次，根据审计数据调整检索流程
|
|
||||||
- **下次 review**: 2026-10-06
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*本 SOP 由 projectmanager 胡蓉起草，经刘炜承批准后生效。*
|
|
||||||
@@ -1,194 +0,0 @@
|
|||||||
# SOP-017：知识缺口上报 SOP
|
|
||||||
|
|
||||||
> **版本**: v1.0
|
|
||||||
> **起草人**: 胡蓉（projectmanager）
|
|
||||||
> **批准人**: 刘炜承
|
|
||||||
> **生效日期**: 2026-07-06
|
|
||||||
> **关联 Issue**: BIZ-82
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. 目的
|
|
||||||
|
|
||||||
解决 BIZ-45 巡检发现的全平台零知识缺口上报问题。各 Agent TOOLS.md 有"知识缺口记录"章节但无明确触发条件和上报流程，导致知识缺口被忽略、遗忘，长期影响任务交付质量。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. 适用范围
|
|
||||||
|
|
||||||
全部 Agent（产研线 + 运营线 + 职能线），共 14 个。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 知识缺口定义
|
|
||||||
|
|
||||||
**知识缺口** = 执行任务时发现知识库（memory / wiki / 思源）中找不到的、且影响任务交付的知识。
|
|
||||||
|
|
||||||
### 属于知识缺口的情况
|
|
||||||
|
|
||||||
| # | 类型 | 示例 |
|
|
||||||
|---|------|------|
|
|
||||||
| 1 | 核心 SOP 缺失 | 没有淘宝上架 SOP，运营不知道怎么操作 |
|
|
||||||
| 2 | 技术规范缺失 | 没有代码审查规范，开发不知道标准 |
|
|
||||||
| 3 | 决策依据缺失 | 选型时缺乏对比数据，无法做出有依据的决策 |
|
|
||||||
| 4 | 模板/指南缺失 | 没有 PRD 模板，每次手写格式不一致 |
|
|
||||||
| 5 | 外部信息缺失 | 需要某个 API 文档但找不到 |
|
|
||||||
|
|
||||||
### 不属于知识缺口的情况
|
|
||||||
|
|
||||||
| # | 场景 | 应对方式 |
|
|
||||||
|----|------|----------|
|
|
||||||
| 1 | 可通过 web_search 快速获取的公开信息 | 自行检索 |
|
|
||||||
| 2 | 可通过 memory_search / wiki_search 检索到的现有知识 | 自行读取 |
|
|
||||||
| 3 | 可通过联系对应 Agent 获得的信息 | 直接联系 |
|
|
||||||
| 4 | Agent 自身职责范围内的常识 | 不需上报 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. 触发条件
|
|
||||||
|
|
||||||
执行 SOP-016（执行前检索）后，以下情况触发上报：
|
|
||||||
|
|
||||||
1. **检索无结果**: memory_search + wiki_search + 思源全文搜索均无匹配
|
|
||||||
2. **检索结果不足以支撑决策**: 有部分信息但缺少关键环节
|
|
||||||
3. **任务执行中发现缺少必要规范/模板/指南**: 执行中途发现被忽略的知识需求
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. 上报流程
|
|
||||||
|
|
||||||
```
|
|
||||||
发现知识缺口
|
|
||||||
↓
|
|
||||||
Step 1: 记录 — 在 memory/当日日志.md 中记录缺口
|
|
||||||
↓
|
|
||||||
Step 2: 通知 — 通过 sessions_send 通知 COO（陆怀瑾）
|
|
||||||
↓
|
|
||||||
Step 3: 创建 Issue — 在 Gitea 仓库创建 Issue（标题格式：知识缺口-<领域>-<关键词>）
|
|
||||||
↓
|
|
||||||
Step 4: COO 审核 — COO 评估后决定：接受 / 拒绝 / 升级
|
|
||||||
↓
|
|
||||||
Step 5: 创建 WorkBoard 卡片 — COO 创建补全卡片，分配给合适的 Agent
|
|
||||||
↓
|
|
||||||
Step 6: 补全完成 — 补全 Agent 完成后通知上报 Agent + COO
|
|
||||||
↓
|
|
||||||
Step 7: 闭环 — COO 确认补全质量，关闭 Issue 和卡片
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. 上报格式
|
|
||||||
|
|
||||||
### 6.1 memory 日志记录格式
|
|
||||||
|
|
||||||
在 `memory/YYYY-MM-DD.md` 中追加：
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## 📚 知识缺口上报
|
|
||||||
|
|
||||||
**缺口类型**: [核心SOP缺失 | 技术规范缺失 | 决策依据缺失 | 模板/指南缺失 | 外部信息缺失]
|
|
||||||
**缺口描述**: [具体缺什么，越详细越好]
|
|
||||||
**使用场景**: [在做什么任务时发现的，为什么需要这个知识]
|
|
||||||
**影响范围**: [哪些任务/Agent 受影响]
|
|
||||||
**紧急程度**: [P0-阻塞当前任务 | P1-影响效率 | P2-改进建议]
|
|
||||||
**建议补全方式**: [希望怎么处理——新建SOP/更新现有/外部采购等]
|
|
||||||
**已执行的检索**: [列出已尝试的检索方式和query]
|
|
||||||
**上报时间**: [YYYY-MM-DD HH:MM]
|
|
||||||
```
|
|
||||||
|
|
||||||
### 6.2 通知 COO 的消息格式
|
|
||||||
|
|
||||||
通过 `sessions_send` 发送给 COO（sessionKey: `agent:coo:feishu:coo:direct:ou_9f73b4e54af59f038e2b754793ea0908`）：
|
|
||||||
|
|
||||||
```
|
|
||||||
【知识缺口上报】
|
|
||||||
类型: [缺口类型]
|
|
||||||
描述: [缺口描述]
|
|
||||||
场景: [使用场景]
|
|
||||||
紧急: [P0/P1/P2]
|
|
||||||
已记录: memory/YYYY-MM-DD.md
|
|
||||||
请审核并决定是否创建补全卡片。
|
|
||||||
```
|
|
||||||
|
|
||||||
### 6.3 Gitea Issue 格式
|
|
||||||
|
|
||||||
- **标题**: `知识缺口-<领域>-<关键词>`
|
|
||||||
- **标签**: `knowledge-gap`
|
|
||||||
- **描述**: 包含缺口类型、描述、使用场景、影响范围、紧急程度、建议补全方式
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. 优先级分级
|
|
||||||
|
|
||||||
| 优先级 | 定义 | 响应时限 | 补全时限 |
|
|
||||||
|--------|------|----------|----------|
|
|
||||||
| P0 | 阻塞当前任务，无法继续执行 | COO 4h 内响应 | 24h 内补全 |
|
|
||||||
| P1 | 影响效率，有 workaround 但不理想 | COO 1 工作日内响应 | 3 工作日内补全 |
|
|
||||||
| P2 | 改进建议，当前可正常运行 | COO 1 周内响应 | 按排期补全 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. COO 审核标准
|
|
||||||
|
|
||||||
COO 收到上报后，按以下标准审核：
|
|
||||||
|
|
||||||
| 审核项 | 标准 |
|
|
||||||
|--------|------|
|
|
||||||
| 是否真的缺口 | 上报人是否已充分检索（检查已执行检索记录） |
|
|
||||||
| 是否属于知识缺口 | 对照第3节定义判断 |
|
|
||||||
| 优先级是否合理 | 根据影响范围和紧急程度判断 |
|
|
||||||
| 补全方式是否可行 | 评估建议的合理性 |
|
|
||||||
|
|
||||||
### 审核结果
|
|
||||||
|
|
||||||
| 结果 | 处理方式 |
|
|
||||||
|------|----------|
|
|
||||||
| **接受** | 创建 WorkBoard 补全卡片，分配给合适 Agent |
|
|
||||||
| **拒绝** | 说明理由，告知上报人自行解决 |
|
|
||||||
| **升级** | 转交承哥决策（涉及预算、外部采购等） |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 9. TOOLS.md 注入模板
|
|
||||||
|
|
||||||
各 Agent 的 TOOLS.md 中需注入以下章节：
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## 📚 知识缺口上报
|
|
||||||
|
|
||||||
> 完整 SOP 见 specs/SOP-017_知识缺口上报SOP.md
|
|
||||||
|
|
||||||
### 触发条件
|
|
||||||
执行 SOP-016 检索后，以下情况需上报知识缺口：
|
|
||||||
1. 核心业务数据/SOP/决策依据缺失
|
|
||||||
2. 缺失影响任务交付质量或决策准确性
|
|
||||||
3. 无法通过 memory_search / wiki_search 检索到
|
|
||||||
|
|
||||||
### 上报流程
|
|
||||||
1. **记录**: 在 memory/当日日志.md 中记录缺口（标准格式见 SOP-017）
|
|
||||||
2. **通知**: 飞书通知 COO（sessionKey: agent:coo:feishu:coo:direct:ou_9f73b4e54af59f038e2b754793ea0908）
|
|
||||||
3. **创建 Issue**: Gitea 仓库创建 Issue（标题格式：知识缺口-<领域>-<关键词>）
|
|
||||||
4. **跟进**: COO 评估后创建 WorkBoard 补全卡片
|
|
||||||
5. **闭环**: 补全后 COO 通知可使用
|
|
||||||
|
|
||||||
### 标准格式
|
|
||||||
[见 SOP-017 第6节]
|
|
||||||
|
|
||||||
### 不属于知识缺口的情况
|
|
||||||
- 可通过 web_search 快速获取的公开信息 → 自行检索
|
|
||||||
- 可通过 memory_search / wiki_search 检索到的现有知识 → 自行读取
|
|
||||||
- 可通过联系对应 Agent 获得的信息 → 直接联系
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 10. 生效与维护
|
|
||||||
|
|
||||||
- **生效日期**: 2026-07-06
|
|
||||||
- **维护人**: 胡蓉（projectmanager）
|
|
||||||
- **revision 周期**: 每季度 review 一次，根据上报数据调整流程
|
|
||||||
- **下次 review**: 2026-10-06
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*本 SOP 由 projectmanager 胡蓉起草，经刘炜承批准后生效。*
|
|
||||||
@@ -1,214 +0,0 @@
|
|||||||
# 开发文档：双色球 Web UI 系统
|
|
||||||
|
|
||||||
**版本**: v1.0
|
|
||||||
**开发人员**: 徐聪（costcodev）
|
|
||||||
**日期**: 2026-07-03
|
|
||||||
**Issue**: BIZ-75
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. 项目概述
|
|
||||||
|
|
||||||
双色球自动化系统 Web UI，提供号码生成、历史数据查看、生成记录管理和统计分析功能。支持 PC 端和移动端响应式访问，监听 0.0.0.0:8085，局域网可访问。
|
|
||||||
|
|
||||||
## 2. 技术栈
|
|
||||||
|
|
||||||
| 层级 | 技术 | 说明 |
|
|
||||||
|------|------|------|
|
|
||||||
| 后端 | Python 3 + Flask | REST API 服务 |
|
|
||||||
| 前端 | 原生 HTML/CSS/JS | 单文件，响应式布局 |
|
|
||||||
| 数据分析 | Pandas + NumPy | 号码统计分析 |
|
|
||||||
| 数据存储 | Excel + JSON | 历史数据 + 生成记录 |
|
|
||||||
| 部署 | systemd / nohup | Linux 服务部署 |
|
|
||||||
|
|
||||||
## 3. 目录结构
|
|
||||||
|
|
||||||
```
|
|
||||||
lottoData/
|
|
||||||
├── app.py # Flask 主服务（统一入口）
|
|
||||||
├── index.html # 前端 UI（响应式，4 Tab 页面）
|
|
||||||
├── lottery.py # 号码生成核心逻辑
|
|
||||||
├── fetch_data.py # 历史数据抓取脚本
|
|
||||||
├── web_console.html # 数据抓取控制台前端
|
|
||||||
├── requirements.txt # Python 依赖
|
|
||||||
├── 双色球历史数据.xlsx # 历史数据文件
|
|
||||||
├── lottery/ # 号码生成结果输出目录
|
|
||||||
├── .generation_records.json # 生成记录索引（JSON）
|
|
||||||
├── .fetch_status.json # 抓取状态文件
|
|
||||||
├── deploy/ # 部署相关文件
|
|
||||||
│ ├── DEPLOY.md # 部署说明
|
|
||||||
│ ├── lotto-app.service # systemd 服务文件
|
|
||||||
│ ├── fetch_daily.sh # 定时抓取脚本
|
|
||||||
│ └── backup.sh # 备份脚本
|
|
||||||
└── docs/ # 文档目录
|
|
||||||
├── PRD-双色球 WebUI-v1.0.md
|
|
||||||
└── 开发文档-双色球WebUI-v1.0.md ← 本文件
|
|
||||||
```
|
|
||||||
|
|
||||||
## 4. API 接口
|
|
||||||
|
|
||||||
### 4.1 接口清单
|
|
||||||
|
|
||||||
| 接口 | 方法 | 描述 | 认证 |
|
|
||||||
|------|------|------|------|
|
|
||||||
| `/api/generate` | POST | 生成号码 | 可选 |
|
|
||||||
| `/api/history` | GET | 获取历史开奖数据（分页+搜索） | 可选 |
|
|
||||||
| `/api/records` | GET | 获取生成记录列表（分页） | 可选 |
|
|
||||||
| `/api/records/:id` | DELETE | 删除生成记录 | 可选 |
|
|
||||||
| `/api/statistics` | GET | 获取统计分析数据 | 可选 |
|
|
||||||
| `/api/download/:filepath` | GET | 下载文件 | 可选 |
|
|
||||||
| `/api/status` | GET | 系统状态 | 无 |
|
|
||||||
| `/api/config` | GET | 前端配置 | 无 |
|
|
||||||
| `/api/fetch/status` | GET | 抓取执行状态 | 无 |
|
|
||||||
| `/api/fetch/execute` | POST | 触发数据抓取 | 无 |
|
|
||||||
|
|
||||||
### 4.2 关键接口参数
|
|
||||||
|
|
||||||
#### POST /api/generate
|
|
||||||
```json
|
|
||||||
// 请求
|
|
||||||
{
|
|
||||||
"num_tickets": 10,
|
|
||||||
"strategy": "advanced" // 或 "basic"
|
|
||||||
}
|
|
||||||
// 响应
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"tickets": [...],
|
|
||||||
"total": 10,
|
|
||||||
"filename": "lottery/xxx.xlsx",
|
|
||||||
"download_url": "/api/download/lottery/xxx.xlsx",
|
|
||||||
"record": {...},
|
|
||||||
"statistics": {...}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### GET /api/history
|
|
||||||
参数: `page` (页码), `page_size` (每页条数), `search` (搜索关键词)
|
|
||||||
|
|
||||||
#### GET /api/records
|
|
||||||
参数: `page` (页码), `page_size` (每页条数)
|
|
||||||
|
|
||||||
## 5. 前端页面
|
|
||||||
|
|
||||||
### 5.1 页面结构
|
|
||||||
- **Header**: 标题 + 副标题
|
|
||||||
- **导航 Tab**: 号码生成 | 历史数据 | 生成记录 | 统计分析
|
|
||||||
- **移动端**: 底部固定导航栏
|
|
||||||
|
|
||||||
### 5.2 功能页面
|
|
||||||
|
|
||||||
#### 号码生成页（首页）
|
|
||||||
- 统计概览（历史期数、常见奇偶比、和值范围等）
|
|
||||||
- 策略选择（高级策略/基础策略）
|
|
||||||
- 注数输入（1-1000）
|
|
||||||
- 生成结果展示（红球+蓝球+统计指标）
|
|
||||||
- Excel 下载按钮
|
|
||||||
|
|
||||||
#### 历史数据页
|
|
||||||
- 搜索框（500ms 防抖）
|
|
||||||
- 数据表格（期号、日期、红球、蓝球、统计字段）
|
|
||||||
- 分页控件
|
|
||||||
|
|
||||||
#### 生成记录页
|
|
||||||
- 记录列表（策略、注数、时间、文件大小）
|
|
||||||
- 下载/删除操作
|
|
||||||
- 分页控件
|
|
||||||
|
|
||||||
#### 统计分析页
|
|
||||||
- 历史开奖期数
|
|
||||||
- 红球热号 TOP15 / 冷号 TOP15
|
|
||||||
- 蓝球热号 TOP8
|
|
||||||
- 奇偶比/大小比/和值/跨度统计
|
|
||||||
|
|
||||||
## 6. 关键修复说明
|
|
||||||
|
|
||||||
### 6.1 数据格式兼容修复（核心 Bug 修复）
|
|
||||||
|
|
||||||
**问题**: `lottery.py` 期望 Excel 含"号码"列（拼接格式如 `08121821243001`），但 `fetch_data.py` 抓取的 Excel 使用分列格式（"红球 1"~"红球 6"+"蓝球"），导致号码生成器无法加载历史数据。
|
|
||||||
|
|
||||||
**根因**: Excel 文件包含两行 header：
|
|
||||||
- Row 0: 新格式列名（期号、开奖日期、红球 1~6、蓝球、特别号）
|
|
||||||
- Row 1: 旧格式列名（开奖时间、期数、号码、开机号、...）
|
|
||||||
- Row 2+: 实际数据
|
|
||||||
|
|
||||||
**修复方案**:
|
|
||||||
1. `lottery.py` 的 `load_history_data()`: 添加多格式检测逻辑，识别格式A（双行 header）并自动跳过，使用旧列名作为标准列名
|
|
||||||
2. `lottery.py` 的 `parse_numbers()`: 新增对拼接字符串格式（14位无分隔符）的直接解析，避免 `re.findall` 将整个字符串视为一个数字
|
|
||||||
3. `app.py` 的 `load_history_dataframe()`: 同步修复多格式兼容逻辑
|
|
||||||
|
|
||||||
### 6.2 线程安全
|
|
||||||
|
|
||||||
- 生成记录的读-改-写操作使用 `threading.Lock` 保护
|
|
||||||
- 文件写入使用临时文件+原子替换（`os.replace`），防止崩溃导致数据损坏
|
|
||||||
|
|
||||||
## 7. 部署方式
|
|
||||||
|
|
||||||
### 7.1 直接运行
|
|
||||||
```bash
|
|
||||||
cd /home/vincent/Studio/lottoData
|
|
||||||
source .venv/bin/activate
|
|
||||||
python3 app.py
|
|
||||||
# 访问 http://localhost:8085
|
|
||||||
```
|
|
||||||
|
|
||||||
### 7.2 systemd 服务
|
|
||||||
```bash
|
|
||||||
# 服务文件: deploy/lotto-app.service
|
|
||||||
sudo cp deploy/lotto-app.service /etc/systemd/system/
|
|
||||||
sudo systemctl daemon-reload
|
|
||||||
sudo systemctl enable lotto-app
|
|
||||||
sudo systemctl start lotto-app
|
|
||||||
```
|
|
||||||
|
|
||||||
### 7.3 定时数据抓取
|
|
||||||
```bash
|
|
||||||
# 添加 cron 任务
|
|
||||||
crontab -e
|
|
||||||
# 每天 02:30 自动抓取最新数据
|
|
||||||
30 2 * * * /home/vincent/Studio/lottoData/deploy/fetch_daily.sh >> /home/vincent/Studio/lottoData/deploy/cron.log 2>&1
|
|
||||||
```
|
|
||||||
|
|
||||||
## 8. 测试验证
|
|
||||||
|
|
||||||
### 8.1 API 测试结果
|
|
||||||
|
|
||||||
| 接口 | 状态 | 说明 |
|
|
||||||
|------|------|------|
|
|
||||||
| GET /api/status | ✅ 通过 | 返回服务状态 |
|
|
||||||
| GET /api/statistics | ✅ 通过 | 120条历史数据统计正确 |
|
|
||||||
| GET /api/history | ✅ 通过 | 分页+红蓝球解析正确 |
|
|
||||||
| POST /api/generate | ✅ 通过 | 5注号码生成成功，含统计 |
|
|
||||||
| GET /api/records | ✅ 通过 | 生成记录列表正确 |
|
|
||||||
| GET / (前端页面) | ✅ 通过 | HTML 页面正常加载 |
|
|
||||||
|
|
||||||
### 8.2 数据格式验证
|
|
||||||
- 历史数据: 120 条记录全部成功解析 ✅
|
|
||||||
- 红球解析: 6个红球正确提取 ✅
|
|
||||||
- 蓝球解析: 1个蓝球正确提取 ✅
|
|
||||||
- 号码范围校验: 1-33(红) + 1-16(蓝) ✅
|
|
||||||
|
|
||||||
## 9. 已知限制
|
|
||||||
|
|
||||||
- 前端为单 HTML 文件，未使用构建工具
|
|
||||||
- 无用户登录系统（Token 认证为可选项，默认关闭）
|
|
||||||
- 历史数据来源为 55128.cn，如网站改版需更新 `fetch_data.py`
|
|
||||||
- 不支持 HTTPS（内网环境）
|
|
||||||
|
|
||||||
## 10. 后续优化建议
|
|
||||||
|
|
||||||
| 功能 | 优先级 | 说明 |
|
|
||||||
|------|--------|------|
|
|
||||||
| 数据可视化图表 | P2 | 走势图、分布图 |
|
|
||||||
| 用户登录系统 | P2 | 多用户权限管理 |
|
|
||||||
| 定时自动生成 | P2 | 定时生成+推送 |
|
|
||||||
| 微信推送 | P3 | 生成结果推送至微信 |
|
|
||||||
| 多彩种支持 | P3 | 大乐透、福彩 3D 等 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**开发完成日期**: 2026-07-03
|
|
||||||
**代码仓库**: http://192.168.1.99:12299/vincent/Lottery.git
|
|
||||||
**开发人员**: 徐聪（costcodev）
|
|
||||||
Reference in New Issue
Block a user