docs: README 顶部增加生产部署快速索引锚点

Co-authored-by: multica-agent <github@multica.ai>

docs/Metapi_NVIDIA网关切换配置指南.md

@@ -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 |

docs/architecture/BIZ-46_Phase3_Architecture_Design.md

@@ -0,0 +1,644 @@
+# BIZ-46 Phase3: NVIDIA Sidecar Follow-up 架构设计
+
+> **架构师**: 梁思筑 (architect)  
+> **日期**: 2026-06-24  
+> **状态**: 已批准，推进实施  
+> **来源**: BIZ-42 Phase2 二轮评审 follow-up  
+
+---
+
+## 1. 架构解耦 / 依赖注入 — SidecarContext
+
+### 1.1 现状分析
+
+当前 `server.py` 使用 **模块级全局变量** 管理所有核心组件：
+
+```python
+# server.py 全局状态（当前）
+_config: SidecarConfig
+_http_client: httpx.AsyncClient
+_priority_queue: PriorityRequestQueue
+_token_bucket: AdaptiveTokenBucket
+_prometheus: PrometheusMetrics
+_health_service: HealthService
+_pending_requests: dict[str, tuple[asyncio.Future, float]]
+_stats: dict[str, int]
+_stats_lock: asyncio.Lock
+```
+
+**问题**：
+- `webui.py` 通过 `from nvidia_sidecar import server` 反向导入全局变量（循环依赖风险）
+- 单元测试需要 mock 模块级变量，无法并行运行测试
+- 未来多实例/多租户扩展需重写全部模块访问逻辑
+
+### 1.2 设计方案 — SidecarContext + FastAPI Dependency Injection
+
+#### 1.2.1 核心数据结构
+
+```python
+# context.py
+from dataclasses import dataclass, field
+import asyncio
+import httpx
+from typing import Any
+
+@dataclass
+class SidecarContext:
+    """Sidecar 全局运行时上下文 — 所有核心组件的唯一容器。
+    
+    通过 app.state.sidecar 注入 FastAPI，路由通过 Depends 获取。
+    """
+    config: 'SidecarConfig'
+    http_client: httpx.AsyncClient
+    token_bucket: 'AdaptiveTokenBucket'
+    priority_queue: 'PriorityRequestQueue'
+    prometheus: 'PrometheusMetrics'
+    health: 'HealthService'
+    pending_requests: dict[str, tuple['asyncio.Future', float]] = field(default_factory=dict)
+    stats: dict[str, int] = field(default_factory=lambda: {
+        "total_requests": 0,
+        "nvidia_requests": 0,
+        "passthrough_requests": 0,
+        "ratelimited_requests": 0,
+        "queue_full_rejects": 0,
+        "upstream_errors": 0,
+        "start_time": 0,
+    })
+    stats_lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+    
+    async def increment_stat(self, key: str, delta: int = 1) -> None:
+        """线程安全的统计计数器自增。"""
+        async with self.stats_lock:
+            self.stats[key] = self.stats.get(key, 0) + delta
+```
+
+#### 1.2.2 注入方式
+
+```python
+# server.py — lifespan 中创建 context
+from nvidia_sidecar.context import SidecarContext
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    ctx = SidecarContext(
+        config=load_config(),
+        http_client=httpx.AsyncClient(...),
+        token_bucket=AdaptiveTokenBucket(...),
+        priority_queue=PriorityRequestQueue(...),
+        prometheus=PrometheusMetrics(),
+        health=HealthService(),
+    )
+    app.state.sidecar = ctx  # 注入 FastAPI
+    # ... worker 启动 ...
+    yield
+    # ... 清理 ...
+
+# 依赖注入函数
+def get_context(request: Request) -> SidecarContext:
+    return request.app.state.sidecar
+
+# 路由使用
+@app.post("/v1/chat/completions")
+async def chat_completions(request: Request, ctx: SidecarContext = Depends(get_context)):
+    return await _handle_proxy_request(request, "/v1/chat/completions", ctx)
+```
+
+#### 1.2.3 webui.py 解耦
+
+```python
+# webui.py — 不再反向导入 server
+from nvidia_sidecar.context import SidecarContext
+from fastapi import Depends
+
+def get_webui_router():
+    router = APIRouter(prefix="/api", tags=["webui"])
+    
+    def _get_ctx(request: Request) -> SidecarContext:
+        return request.app.state.sidecar
+    
+    @router.get("/dashboard/stream")
+    async def dashboard_stream(request: Request, ctx: SidecarContext = Depends(_get_ctx)):
+        return await _dashboard_stream(request, ctx)
+    
+    @router.get("/admin/config")
+    async def admin_get_config(ctx: SidecarContext = Depends(_get_ctx)):
+        return await get_config(ctx)
+    
+    return router
+```
+
+#### 1.2.4 Trade-off 分析
+
+| 维度 | 当前（全局变量） | 方案A（SidecarContext） | 方案B（FastAPI Dependency 全函数式） |
+|------|------------------|------------------------|-------------------------------------|
+| 可测试性 | 差（需 mock 模块） | 好（注入 mock context） | 优（每个依赖独立注入） |
+| 改动量 | 无 | 中等（~8 文件） | 大（每个函数签名变更） |
+| 可读性 | 一般 | 好（ctx 一目了然） | 差（参数列表膨胀） |
+| 多实例支持 | 不支持 | 支持（多 app 多 ctx） | 支持 |
+| 循环依赖 | 有（webui→server） | 消除 | 消除 |
+
+**决策**: 采用方案A（SidecarContext），平衡改动量与收益。
+
+### 1.3 迁移计划
+
+分 3 步渐进迁移，每步可独立合入：
+
+1. **Step 1**: 创建 `context.py`，定义 `SidecarContext`，在 `lifespan` 中实例化并挂到 `app.state`
+2. **Step 2**: 路由函数改为 `Depends(get_context)`，删除模块级 `_config`、`_http_client` 等
+3. **Step 3**: `webui.py` 移除 `from nvidia_sidecar import server`，改用依赖注入
+
+---
+
+## 2. Prometheus 标签基数治理
+
+### 2.1 现状
+
+当前使用 `model_id` 作为 label 的指标：
+
+| 指标 | Label | 风险 |
+|------|-------|------|
+| `sidecar_upstream_latency_seconds` | `model_id` | **高** — NVIDIA 模型名含版本号，可能无界增长 |
+| `sidecar_upstream_errors_total` | `status_code`, `model_id` | **中** — 组合基数 = 模型数 × 状态码数 |
+
+### 2.2 基数评估
+
+NVIDIA API 当前已知模型约 20-30 个，但：
+- 新模型持续发布（每月 2-5 个）
+- 模型名含版本后缀（`nvidia/deepseek-ai/deepseek-v4-pro`、`nvidia/llama-3.1-70b-instruct` 等）
+- 长期运行（6 个月+）可能累积 100+ 标签组合
+
+**结论**: 当前基数可控（<200 组合），但长期存在膨胀风险，应提前治理。
+
+### 2.3 治理方案
+
+| 指标 | 当前 Label | 调整后 Label | 理由 |
+|------|-----------|-------------|------|
+| `upstream_latency_seconds` | `model_id` | `provider` | provider 固定为 `nvidia`，基数=1 |
+| `upstream_errors_total` | `status_code`, `model_id` | `status_code`, `provider` | 同上 |
+
+**模型级信息迁移路径**：
+- 模型 ID → 结构化 JSON 日志（structlog 已支持）
+- 需要模型级延迟分析时 → 临时 `/status` API 查询或日志聚合
+
+```python
+# metrics.py 调整
+self.upstream_latency_seconds: Histogram = Histogram(
+    "sidecar_upstream_latency_seconds",
+    "Upstream response latency in seconds",
+    labelnames=["provider"],  # 原: ["model_id"]
+    buckets=(...),
+)
+
+self.upstream_errors_total: Counter = Counter(
+    "sidecar_upstream_errors_total",
+    "Upstream error count by status code",
+    labelnames=["status_code", "provider"],  # 原: ["status_code", "model_id"]
+)
+```
+
+```python
+# server.py 调整 — 模型信息改记日志
+model_id = _extract_model(payload) or "unknown"
+provider = "nvidia"  # 固定值，因为只有 NVIDIA 请求走 worker
+_prometheus.record_upstream_latency(provider, upstream_latency)
+if not resp.is_success:
+    _prometheus.record_upstream_error(resp.status_code, provider)
+logger.info("request_completed", model_id=model_id, ...)  # JSON 日志保留模型信息
+```
+
+### 2.4 Trade-off
+
+| 维度 | 保留 model_id | 收敛为 provider |
+|------|--------------|----------------|
+| 基数风险 | 高（无界） | 无（固定=1） |
+| 模型级分析 | Prometheus 原生查询 | 需日志聚合 |
+| 迁移成本 | 无 | 低（改 2 个指标定义 + 调用点） |
+
+**决策**: 收敛为 `provider`，模型级分析通过 JSON 日志 + 日志聚合系统（ELK/Loki）完成。
+
+---
+
+## 3. SSE 快照共享缓存
+
+### 3.1 现状
+
+每个 SSE 客户端每秒独立调用 `_build_snapshot()`，该方法：
+- 获取 `_stats` 字典（需锁）
+- 调用 `_token_bucket.get_status()`（需锁）
+- 调用 `_priority_queue.get_stats()`（需 asyncio.Lock）
+
+当 N 个仪表盘同时打开时，每秒 N 次锁竞争 + N 次重复计算。
+
+### 3.2 设计方案 — 1s TTL 共享缓存
+
+```python
+# webui.py
+_snapshot_cache: tuple[dict[str, Any], float] | None = None  # (data, timestamp)
+_snapshot_lock: asyncio.Lock = asyncio.Lock()
+_SNAPSHOT_TTL: float = 1.0  # 1 秒 TTL
+
+async def _build_snapshot_cached(ctx: SidecarContext) -> dict[str, Any]:
+    """带 1s TTL 的共享快照缓存。
+    
+    多个 SSE 客户端共享同一份快照，避免重复计算和锁竞争。
+    """
+    global _snapshot_cache
+    
+    now = time.monotonic()
+    if _snapshot_cache is not None:
+        data, ts = _snapshot_cache
+        if now - ts < _SNAPSHOT_TTL:
+            return data
+    
+    async with _snapshot_lock:
+        # Double-check（避免多个协程同时 miss 后重复构建）
+        if _snapshot_cache is not None:
+            data, ts = _snapshot_cache
+            if now - ts < _SNAPSHOT_TTL:
+                return data
+        
+        snapshot = await _build_snapshot(ctx)
+        _snapshot_cache = (snapshot, now)
+        return snapshot
+```
+
+### 3.3 性能收益
+
+| 场景 | 当前 | 优化后 |
+|------|------|--------|
+| 1 客户端 | 1 次/s 计算 | 1 次/s 计算（无变化） |
+| 5 客户端 | 5 次/s 计算，5 次锁竞争 | 1 次/s 计算，1 次锁竞争 |
+| 20 客户端 | 20 次/s 计算，20 次锁竞争 | 1 次/s 计算，1 次锁竞争 |
+
+---
+
+## 4. 部署支撑
+
+### 4.1 Dockerfile
+
+```dockerfile
+# services/nvidia_sidecar/Dockerfile
+FROM python:3.12-slim AS base
+
+WORKDIR /app
+
+# 安装依赖（利用 Docker 层缓存）
+COPY pyproject.toml .
+RUN pip install --no-cache-dir -e .
+
+# 复制源码
+COPY . .
+
+# 非 root 用户运行
+RUN useradd -r -s /bin/false sidecar
+USER sidecar
+
+# 健康检查
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+    CMD python -c "import httpx; r=httpx.get('http://127.0.0.1:9190/health'); exit(0 if r.status_code==200 else 1)"
+
+EXPOSE 9190 9191
+
+CMD ["uvicorn", "nvidia_sidecar.server:app", "--host", "0.0.0.0", "--port", "9190"]
+```
+
+### 4.2 systemd Service
+
+```ini
+# services/nvidia_sidecar/deploy/nvidia-sidecar.service
+[Unit]
+Description=NVIDIA Sidecar Rate-Limiting Proxy
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=sidecar
+Group=sidecar
+WorkingDirectory=/opt/nvidia-sidecar
+ExecStart=/opt/nvidia-sidecar/.venv/bin/uvicorn nvidia_sidecar.server:app \
+    --host 127.0.0.1 \
+    --port 9190 \
+    --log-level info
+Restart=always
+RestartSec=5
+
+# 环境变量
+EnvironmentFile=/opt/nvidia-sidecar/.env
+
+# 安全加固
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+PrivateTmp=true
+ReadWritePaths=/opt/nvidia-sidecar/logs
+
+# 资源限制
+LimitNOFILE=65536
+MemoryMax=512M
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### 4.3 环境变量清单
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `SIDECAR_HOST` | `127.0.0.1` | 监听地址 |
+| `SIDECAR_PORT` | `9190` | 代理端口 |
+| `SIDECAR_METRICS_PORT` | `9191` | Prometheus 指标端口 |
+| `SIDECAR_UPSTREAM` | `https://integrate.api.nvidia.com/v1` | 上游 API |
+| `SIDECAR_API_KEY` | (必填) | NVIDIA API Key |
+| `SIDECAR_RATE_RPM` | `40` | 限流速率 (RPM) |
+| `SIDECAR_BUCKET_CAPACITY` | `40` | 令牌桶容量 |
+| `SIDECAR_TIMEOUT` | `60` | 请求超时 (秒) |
+| `SIDECAR_QUEUE_MAX` | `500` | 队列最大容量 |
+| `SIDECAR_LOW_TIMEOUT` | `2` | 低优先级超时 (秒) |
+| `SIDECAR_FALLBACK_PASSTHROUGH` | `true` | 队列满时是否直通 |
+| `SIDECAR_LOG_LEVEL` | `INFO` | 日志级别 |
+| `SIDECAR_ADMIN_TOKEN` | (可选) | Admin API 认证 Token |
+
+### 4.4 防火墙建议
+
+```
+# 仅允许内网访问代理端口
+sudo ufw allow from 192.168.1.0/24 to any port 9190
+sudo ufw allow from 192.168.1.0/24 to any port 9191
+# 禁止外网访问
+sudo ufw deny 9190
+sudo ufw deny 9191
+```
+
+---
+
+## 5. Readiness HTTP Client 复用
+
+### 5.1 现状
+
+`HealthService.check_upstream()` 每次调用创建新的 `httpx.AsyncClient`：
+
+```python
+# health.py — 当前
+async def check_upstream(self, upstream_url: str, timeout: float = 5.0, api_key: str = "") -> bool:
+    async with httpx.AsyncClient(timeout=timeout) as client:  # 每次新建！
+        resp = await client.get(...)
+```
+
+K8s/systemd 每 10-30s 探测一次，每次创建+销毁 HTTP client 带来不必要的 TCP 连接开销。
+
+### 5.2 方案 — 复用主 http_client
+
+```python
+# health.py — 优化后
+async def check_upstream(
+    self,
+    upstream_url: str,
+    http_client: httpx.AsyncClient,  # 注入主 client
+    api_key: str = "",
+    timeout: float = 5.0,
+) -> bool:
+    try:
+        headers = {}
+        if api_key:
+            headers["authorization"] = f"Bearer {api_key}"
+        resp = await http_client.get(
+            f"{upstream_url.rstrip('/')}/v1/models",
+            headers=headers,
+            timeout=timeout,
+        )
+        return resp.status_code < 500
+    except Exception:
+        return False
+```
+
+```python
+# server.py — 路由调用处
+@app.get("/health/ready")
+async def health_ready(ctx: SidecarContext = Depends(get_context)):
+    queue_size = await ctx.priority_queue.get_queue_size()
+    bucket_status = ctx.token_bucket.get_status()
+    return await ctx.health.readiness(
+        upstream_url=ctx.config.upstream_url,
+        http_client=ctx.http_client,  # 复用主 client
+        upstream_api_key=ctx.config.upstream_api_key or "",
+        queue_current_size=queue_size,
+        queue_max_size=ctx.config.queue_max_size,
+        available_tokens=bucket_status["tokens"],
+        bucket_capacity=bucket_status["capacity"],
+    )
+```
+
+**注意**: readiness 检查使用较短 timeout (5s)，不影响主代理请求的 timeout 配置。httpx 支持per-request timeout 覆盖。
+
+---
+
+## 6. Retreat 并发/死锁回归测试
+
+### 6.1 风险点
+
+`AdaptiveTokenBucket` 有两把锁：
+- `_lock` (Lock): 保护令牌消费/补充
+- `_retreat_lock` (RLock): 保护避退状态机
+
+潜在死锁路径：
+1. `evaluate_retreat()` 持有 `_retreat_lock` → 调用 `get_429_rate()` (也获取 `_retreat_lock`，RLock 可重入 ✅)
+2. `evaluate_retreat()` → `_apply_retreat()` → `set_rate()` → 获取 `_lock` (另一把锁)
+3. Worker 线程: `consume()` 持有 `_lock` → 不调用 `_retreat_lock` (无交叉 ✅)
+
+当前设计使用 RLock 已规避了重入死锁，但需要回归测试确保未来修改不引入死锁。
+
+### 6.2 测试用例
+
+```python
+# tests/test_retreat_concurrency.py
+import pytest
+import asyncio
+import threading
+from nvidia_sidecar.rate_limiter import AdaptiveTokenBucket, RetreatState
+
+class TestRetreatConcurrency:
+    """避退模式并发安全回归测试。"""
+
+    @pytest.mark.asyncio
+    async def test_concurrent_record_and_evaluate(self):
+        """多线程同时 record_response + evaluate_retreat 不死锁。"""
+        bucket = AdaptiveTokenBucket(rate=40/60, capacity=40)
+        errors: list[Exception] = []
+        
+        def worker_record():
+            for i in range(1000):
+                try:
+                    bucket.record_response(is_429=(i % 10 == 0))
+                except Exception as e:
+                    errors.append(e)
+        
+        def worker_evaluate():
+            for _ in range(1000):
+                try:
+                    bucket.evaluate_retreat()
+                except Exception as e:
+                    errors.append(e)
+        
+        threads = [
+            threading.Thread(target=worker_record),
+            threading.Thread(target=worker_record),
+            threading.Thread(target=worker_evaluate),
+            threading.Thread(target=worker_evaluate),
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join(timeout=10)
+        
+        # 所有线程必须在 10s 内完成（无死锁）
+        assert all(not t.is_alive() for t in threads), "线程未完成，疑似死锁"
+        assert not errors, f"并发错误: {errors}"
+
+    @pytest.mark.asyncio
+    async def test_concurrent_consume_and_retreat(self):
+        """多线程同时 consume + evaluate_retreat 不死锁。"""
+        bucket = AdaptiveTokenBucket(rate=40/60, capacity=40)
+        errors: list[Exception] = []
+        
+        def worker_consume():
+            for _ in range(500):
+                try:
+                    bucket.consume(tokens=1)
+                except Exception as e:
+                    errors.append(e)
+        
+        def worker_retreat():
+            for _ in range(500):
+                try:
+                    bucket.record_response(is_429=False)
+                    bucket.evaluate_retreat()
+                except Exception as e:
+                    errors.append(e)
+        
+        threads = [
+            threading.Thread(target=worker_consume),
+            threading.Thread(target=worker_consume),
+            threading.Thread(target=worker_retreat),
+            threading.Thread(target=worker_retreat),
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join(timeout=10)
+        
+        assert all(not t.is_alive() for t in threads), "线程未完成，疑似死锁"
+        assert not errors, f"并发错误: {errors}"
+
+    def test_retreat_state_transitions_under_load(self):
+        """高负载下避退状态转换正确。"""
+        bucket = AdaptiveTokenBucket(
+            rate=40/60, capacity=40,
+            retreat_429_threshold=0.05,
+            retreat_factor=0.75,
+        )
+        
+        # 模拟高 429 率
+        for _ in range(100):
+            bucket.record_response(is_429=True)
+        
+        state = bucket.evaluate_retreat()
+        assert state == RetreatState.RETREAT
+        assert bucket.get_effective_rate_rpm() < bucket.get_base_rate_rpm()
+        
+        # 模拟恢复
+        for _ in range(200):
+            bucket.record_response(is_429=False)
+        
+        # 需要等待 RECOVER_WINDOW
+        import time
+        time.sleep(0.1)  # 确保时间窗口过去
+        bucket._last_state_change = 0  # 强制触发时间条件
+        state = bucket.evaluate_retreat()
+        assert state in (RetreatState.RECOVER, RetreatState.NORMAL)
+```
+
+---
+
+## 7. Dashboard UX 优化
+
+### 7.1 优化项清单
+
+| # | 优化项 | 实现方式 | 优先级 |
+|---|--------|---------|--------|
+| 1 | 队列柱状图 300ms 平滑动画 | CSS `transition: height 300ms ease` | P1 |
+| 2 | SSE 断连 5s 遮罩 | JS 定时器 + DOM 遮罩层 | P1 |
+| 3 | 队列图标题显示总排队数 | SSE 数据已有 `current_size`，更新标题 | P2 |
+| 4 | 页面加载同步配置 | `fetch('/api/admin/config')` 初始化表单 | P2 |
+
+### 7.2 关键实现
+
+```javascript
+// dashboard.html — SSE 断连检测
+let lastSSETime = Date.now();
+let reconnectMask = document.getElementById('reconnect-mask');
+
+eventSource.onmessage = (event) => {
+    lastSSETime = Date.now();
+    reconnectMask.style.display = 'none';
+    // ... 更新 UI ...
+};
+
+// 5s 无数据 → 显示遮罩
+setInterval(() => {
+    if (Date.now() - lastSSETime > 5000) {
+        reconnectMask.style.display = 'flex';
+    }
+}, 1000);
+
+// 队列柱状图动画
+// CSS: .queue-bar { transition: height 0.3s ease; }
+```
+
+```javascript
+// 页面加载时同步配置
+async function loadConfig() {
+    try {
+        const resp = await fetch('/api/admin/config');
+        if (resp.ok) {
+            const config = await resp.json();
+            document.getElementById('rate-rpm').value = config.rate_rpm;
+            document.getElementById('queue-max').value = config.queue_max_size;
+            // ...
+        }
+    } catch (e) {
+        console.warn('配置加载失败（可能需要 Admin Token）', e);
+    }
+}
+loadConfig();
+```
+
+---
+
+## 8. 实施排期
+
+| 阶段 | 内容 | 预估工时 | 依赖 |
+|------|------|---------|------|
+| **D1** | SidecarContext Step 1-3（解耦迁移） | 8h | 无 |
+| **D2** | Prometheus 标签收敛 + 日志增强 | 2h | D1 |
+| **D2** | SSE 共享缓存 | 2h | D1 |
+| **D2** | Readiness HTTP client 复用 | 1h | D1 |
+| **D3** | Dockerfile + systemd service | 2h | 无 |
+| **D3** | Dashboard UX 优化 | 3h | 无 |
+| **D3** | Retreat 并发回归测试 | 3h | 无 |
+| **D4** | 集成测试 + mypy strict | 4h | D1-D3 |
+| **合计** | | **25h** | |
+
+---
+
+## 9. 验收标准映射
+
+| Issue 要求 | 本文档章节 | 状态 |
+|-----------|-----------|------|
+| SidecarContext / DI 方案落地或 ADR | §1 | ✅ 详细设计 + 迁移计划 |
+| Prometheus 高基数 label 收敛 | §2 | ✅ 收敛为 provider |
+| SSE snapshot 共享缓存 | §3 | ✅ 1s TTL 设计 |
+| Dockerfile + systemd + 部署 SOP | §4 | ✅ 完整文件 |
+| readiness 复用 HTTP client | §5 | ✅ 注入主 client |
+| retreat 并发/死锁回归测试 | §6 | ✅ 测试用例 |
+| Dashboard UX 细节 | §7 | ✅ 4 项优化 |

knowledge/运维/lotto-deploy/DEPLOY.md

@@ -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

knowledge/运维/lotto-deploy/fetch_daily.sh

@@ -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}

knowledge/运维/lotto-deploy/lotto-web.service

@@ -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

knowledge/运维/lotto-deploy/requirements.txt

@@ -1,5 +0,0 @@
-Flask==3.1.3
-pandas==3.0.4
-openpyxl==3.1.5
-requests==2.34.2
-beautifulsoup4==4.15.0

knowledge/运维/shared-scripts/BIZ-104_pre-trim_multica_comment_v1.0.md

@@ -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 模板说明）

knowledge/运维/shared-scripts/BIZ-104_pre-trim_multica_comment_v1.1.md

@@ -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

knowledge/运维/shared-scripts/multica_proxy_v1.1.0.py

@@ -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测试完成")

knowledge/运维/shared-scripts/pre_trim_multica_comment_v1.0.0.py

@@ -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)

knowledge/运维/shared-scripts/pre_trim_multica_comment_v1.0.1.py

@@ -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)

knowledge/运维/shared-scripts/test_multica_proxy_pre_trim_integration_v1.0.0.py

@@ -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)

knowledge/运维/shared-scripts/test_pre_trim_multica_comment_v1.0.0.py

@@ -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)

knowledge/运维/shared-scripts/test_pre_trim_multica_comment_v1.0.1.py

@@ -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)

plans/BIZ-89/淘宝聚水潭自动化运营方案.md

@@ -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

reports/BIZ-65_石斛固态食品与烘焙全品类扩展可行性分析.md

@@ -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月*  
-*本报告基于公开市场数据和行业研究报告编制，品斛堂内部产能数据来源于公开信息（百度百科、什么值得买评测）*

reports/BIZ-66_石斛功能保健食品礼品创新跨界可行性分析.md

@@ -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日 | 顾析策 | 分析事业部 | 市场分析师*

reports/BIZ-67_石斛预制菜与调味品赛道切入可行性分析.md

@@ -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 日*

services/nvidia_sidecar/.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.egg-info/
+.mypy_cache/

services/nvidia_sidecar/Dockerfile

@@ -0,0 +1,40 @@
+# NVIDIA Sidecar 限流代理 — 生产 Docker 镜像 (BIZ-46 Phase3 §4)
+#
+# 构建：
+#   docker build -t nvidia-sidecar:latest .
+#
+# 运行：
+#   docker run -d --name nvidia-sidecar \
+#     -p 127.0.0.1:9190:9190 \
+#     -p 127.0.0.1:9191:9191 \
+#     -e SIDECAR_API_KEY="nvapi-xxx" \
+#     -e SIDECAR_RATE_RPM=40 \
+#     -v $(pwd)/logs:/opt/nvidia-sidecar/logs \
+#     nvidia-sidecar:latest
+
+FROM python:3.12-slim AS base
+
+WORKDIR /app
+
+# 安装依赖（利用 Docker 层缓存）
+COPY pyproject.toml .
+RUN pip install --no-cache-dir fastapi>=0.115 \
+    "uvicorn[standard]>=0.34" httpx>=0.28 PyYAML>=6.0 \
+    structlog>=24.4 "prometheus-client>=0.21" pydantic>=2.0
+
+# 复制源码
+COPY . .
+
+# 非 root 用户运行
+RUN useradd -r -m -s /bin/false sidecar \
+    && mkdir -p /opt/nvidia-sidecar/logs \
+    && chown -R sidecar:sidecar /app /opt/nvidia-sidecar/logs
+USER sidecar
+
+# 健康检查
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+    CMD python -c "import httpx; r=httpx.get('http://127.0.0.1:9190/health'); exit(0 if r.status_code==200 else 1)"
+
+EXPOSE 9190 9191
+
+CMD ["uvicorn", "nvidia_sidecar.server:app", "--host", "0.0.0.0", "--port", "9190"]

services/nvidia_sidecar/README.md

@@ -0,0 +1,120 @@
+# NVIDIA Sidecar 限流代理
+
+为 NVIDIA API 提供**优先级排队 + 令牌桶限流**的透明代理层。
+
+> BIZ-46 Phase3: 架构解耦、Prometheus 标签治理、SSE 共享缓存、部署支撑、测试完善、Dashboard UX 优化。
+
+**生产部署入口：** [Docker 部署](#docker推荐) | [systemd 部署](#systemd) | [防火墙配置](#防火墙建议) | [环境变量清单](#环境变量)
+
+## 快速启动
+
+```bash
+pip install .
+nvidia-sidecar
+```
+
+监听 `127.0.0.1:9190`，代理到 NVIDIA API。
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `SIDECAR_HOST` | `127.0.0.1` | 监听地址 |
+| `SIDECAR_PORT` | `9190` | 监听端口 |
+| `SIDECAR_METRICS_PORT` | `9191` | Metrics 端口 |
+| `SIDECAR_UPSTREAM` | `https://integrate.api.nvidia.com/v1` | 上游 API 地址 |
+| `SIDECAR_API_KEY` | — | NVIDIA API Key（必填） |
+| `SIDECAR_RATE_RPM` | `40` | 每分钟请求数限制 |
+| `SIDECAR_BUCKET_CAPACITY` | `40` | 令牌桶容量 |
+| `SIDECAR_TIMEOUT` | `60` | 上游请求超时（秒） |
+| `SIDECAR_QUEUE_MAX` | `500` | 队列最大长度 |
+| `SIDECAR_LOW_TIMEOUT` | `2.0` | 低优先级令牌等待超时（秒） |
+| `SIDECAR_FALLBACK_PASSTHROUGH` | `true` | 队列满时是否直通上游 |
+| `SIDECAR_LOG_LEVEL` | `INFO` | 日志级别 |
+
+## YAML 配置
+
+```yaml
+listen_port: 9292
+rate_rpm: 60
+upstream_api_key: "nvapi-xxx"
+```
+
+```bash
+nvidia-sidecar --config /etc/nvidia-sidecar.yaml
+```
+
+## API 端点
+
+| 路径 | 方法 | 说明 |
+|------|------|------|
+| `/v1/chat/completions` | POST | OpenAI Chat Completions 代理 |
+| `/v1/completions` | POST | OpenAI Completions 代理（legacy） |
+| `/v1/embeddings` | POST | OpenAI Embeddings 代理 |
+| `/v1/models` | GET | 模型列表代理 |
+| `/health` | GET | 存活检查 (liveness) |
+| `/health/ready` | GET | 就绪检查 (readiness，含上游连通性) |
+| `/status` | GET | 调试用完整状态（限流器 + 队列 + 避退） |
+| `/api/dashboard/stream` | GET | SSE 仪表盘实时推送 |
+| `/api/dashboard` | GET | 仪表盘 HTML 页面 |
+| `/api/admin/config` | GET/POST | 配置查询/热重载（需 Admin Token） |
+| `/metrics` | :9191 | Prometheus 指标端点（独立端口） |
+
+## 部署方式
+
+### Docker（推荐）
+
+```bash
+# 构建
+docker build -t nvidia-sidecar:latest .
+
+# 运行
+docker run -d --name nvidia-sidecar \
+  -p 127.0.0.1:9190:9190 \
+  -p 127.0.0.1:9191:9191 \
+  -e SIDECAR_API_KEY="nvapi-xxx" \
+  nvidia-sidecar:latest
+```
+
+### systemd
+
+```bash
+# 安装
+sudo cp deploy/nvidia-sidecar.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable nvidia-sidecar
+
+# 配置环境变量
+sudo cp deploy/.env.example /opt/nvidia-sidecar/.env
+sudo vim /opt/nvidia-sidecar/.env  # 填入实际值
+
+# 启动
+sudo systemctl start nvidia-sidecar
+sudo journalctl -u nvidia-sidecar -f  # 查看日志
+```
+
+### 环境变量清单
+
+详见 `deploy/.env.example`。
+
+### 防火墙建议
+
+```bash
+# 仅允许内网访问代理端口
+sudo ufw allow from 192.168.1.0/24 to any port 9190
+sudo ufw allow from 192.168.1.0/24 to any port 9191
+# 禁止外网访问
+sudo ufw deny 9190
+sudo ufw deny 9191
+```
+
+## 架构
+
+```
+请求 → 网关识别 → [NVIDIA: 优先级排队 → 令牌桶限流] → httpx → NVIDIA API
+                → [非 NVIDIA: 直通] → httpx → 上游
+```
+
+- **四级优先级**: URGENT > HIGH > NORMAL > LOW（通过 `X-Priority` header 指定）
+- **队列满策略**: PASSTHROUGH（直通）/ REJECT（503）/ DROP_LOWEST（丢弃最低优先级）
+- **令牌桶**: 40 RPM，线程安全，支持阻塞/非阻塞消费

services/nvidia_sidecar/__init__.py

@@ -0,0 +1,41 @@
+"""
+NVIDIA Sidecar 限流代理 — 核心代理模块。
+
+为 OpenAI Chat Completions 兼容 API 提供四层防护：
+    1. 请求接收（FastAPI）
+    2. 网关识别 → 非 NVIDIA 直通
+    3. 优先级排队 → 令牌桶限流
+    4. httpx 异步转发到 NVIDIA 上游
+"""
+
+from __future__ import annotations
+
+from nvidia_sidecar.config import SidecarConfig, load_config
+from nvidia_sidecar.rate_limiter import (
+    Priority,
+    TokenBucket,
+    is_nvidia_gateway,
+    normalize_gateway_name,
+)
+from nvidia_sidecar.priority_queue import (
+    PriorityQueueItem,
+    PriorityRequestQueue,
+    QueueFullError,
+    QueueFullPassthrough,
+    QueueFullPolicy,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "SidecarConfig",
+    "load_config",
+    "Priority",
+    "TokenBucket",
+    "is_nvidia_gateway",
+    "normalize_gateway_name",
+    "PriorityQueueItem",
+    "PriorityRequestQueue",
+    "QueueFullError",
+    "QueueFullPassthrough",
+    "QueueFullPolicy",
+]

services/nvidia_sidecar/config.py

@@ -0,0 +1,221 @@
+"""
+NVIDIA Sidecar 限流代理 — 配置管理模块 (§3.1)
+
+集中管理 Sidecar 运行参数，支持环境变量覆盖和 YAML 配置文件。
+"""
+
+from __future__ import annotations
+
+import os
+import warnings
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class SidecarConfig:
+    """Sidecar 运行配置数据类。
+
+    所有字段可通过环境变量覆盖，优先级：环境变量 > YAML 配置文件 > 默认值。
+    """
+
+    # ---- 网络 ----
+    listen_host: str = field(
+        default="127.0.0.1",
+        metadata={"env": "SIDECAR_HOST"},
+    )
+    listen_port: int = field(
+        default=9190,
+        metadata={"env": "SIDECAR_PORT"},
+    )
+    metrics_port: int = field(
+        default=9191,
+        metadata={"env": "SIDECAR_METRICS_PORT"},
+    )
+
+    # ---- 上游 ----
+    upstream_url: str = field(
+        default="https://integrate.api.nvidia.com/v1",
+        metadata={"env": "SIDECAR_UPSTREAM"},
+    )
+    upstream_api_key: str = field(
+        default="",
+        metadata={"env": "SIDECAR_API_KEY"},
+    )
+
+    # ---- 限流 ----
+    rate_rpm: int = field(
+        default=40,
+        metadata={"env": "SIDECAR_RATE_RPM"},
+    )
+    bucket_capacity: int = field(
+        default=40,
+        metadata={"env": "SIDECAR_BUCKET_CAPACITY"},
+    )
+
+    # ---- 超时 ----
+    request_timeout: float = field(
+        default=60.0,
+        metadata={"env": "SIDECAR_TIMEOUT"},
+    )
+
+    # ---- 队列 ----
+    queue_max_size: int = field(
+        default=500,
+        metadata={"env": "SIDECAR_QUEUE_MAX"},
+    )
+    low_priority_timeout: float = field(
+        default=2.0,
+        metadata={"env": "SIDECAR_LOW_TIMEOUT"},
+    )
+
+    # ---- 降级 ----
+    fallback_enabled_passthrough: bool = field(
+        default=True,
+        metadata={"env": "SIDECAR_FALLBACK_PASSTHROUGH"},
+    )
+
+    # ---- 日志 ----
+    log_level: str = field(
+        default="INFO",
+        metadata={"env": "SIDECAR_LOG_LEVEL"},
+    )
+
+
+def _apply_env_overrides(config: SidecarConfig) -> SidecarConfig:
+    """用环境变量覆盖配置字段。
+
+    遍历 SidecarConfig 的 dataclass fields，对每个声明了 ``metadata={"env": ...}``
+    的字段检查环境变量是否存在，存在则用对应类型转换后覆盖。
+    """
+    import dataclasses as _dc
+
+    # 使用 typing.get_type_hints 解析 from __future__ import annotations
+    # 引入的字符串化类型注解 (PEP 563)
+    try:
+        resolved_types = __import__("typing").get_type_hints(type(config))
+    except Exception:
+        resolved_types = {}
+
+    for fld in _dc.fields(config):
+        env_key: str | None = fld.metadata.get("env")
+        if env_key is None:
+            continue
+        env_val = os.environ.get(env_key)
+        if env_val is None:
+            continue
+
+        target_type = resolved_types.get(fld.name, fld.type)
+        target_type_name: str = getattr(target_type, "__name__", str(target_type))
+        try:
+            if target_type is bool or target_type == "bool":
+                parsed: bool = env_val.strip().lower() in ("true", "1", "yes", "on")
+                setattr(config, fld.name, parsed)
+            elif target_type is int or target_type == "int":
+                setattr(config, fld.name, int(env_val))
+            elif target_type is float or target_type == "float":
+                setattr(config, fld.name, float(env_val))
+            else:
+                setattr(config, fld.name, env_val)
+        except (ValueError, TypeError) as exc:
+            warnings.warn(
+                f"无法将环境变量 {env_key}={env_val!r} 转换为 {target_type_name}: {exc}"
+            )
+
+    return config
+
+
+def _validate_config(config: SidecarConfig) -> list[str]:
+    """验证配置合理性，返回警告/问题列表。"""
+    issues: list[str] = []
+
+    # 端口冲突检查
+    if config.listen_port == config.metrics_port:
+        issues.append(
+            f"listen_port ({config.listen_port}) 与 metrics_port ({config.metrics_port}) 相同"
+        )
+
+    # rate_rpm 边界检查
+    if config.rate_rpm <= 0:
+        issues.append(
+            f"rate_rpm ({config.rate_rpm}) 无效，回退到默认值 40"
+        )
+        config.rate_rpm = 40
+
+    # queue_max_size 合理性
+    if config.queue_max_size <= 0:
+        issues.append(
+            f"queue_max_size ({config.queue_max_size}) 无效，回退到默认值 500"
+        )
+        config.queue_max_size = 500
+
+    # request_timeout 合理性
+    if config.request_timeout <= 0:
+        issues.append(
+            f"request_timeout ({config.request_timeout}) 无效，回退到默认值 60"
+        )
+        config.request_timeout = 60.0
+    elif config.request_timeout > 300.0:
+        issues.append(
+            f"request_timeout ({config.request_timeout}) 异常偏高，已截断为 300"
+        )
+        config.request_timeout = 300.0
+
+    return issues
+
+
+def load_config(path: str | None = None) -> SidecarConfig:
+    """加载 Sidecar 配置。
+
+    加载顺序（后者覆盖前者）：
+    1. 默认值（SidecarConfig dataclass defaults）
+    2. YAML 配置文件（如果 path 提供）
+    3. 环境变量覆盖
+
+    Args:
+        path: 可选 YAML 配置文件路径。为 None 时只使用默认值 + 环境变量。
+
+    Returns:
+        经过验证的 SidecarConfig 实例。
+
+    Raises:
+        FileNotFoundError: path 指定的文件不存在。
+        yaml.YAMLError: YAML 解析失败。
+    """
+    config = SidecarConfig()
+
+    if path is not None:
+        import yaml
+
+        cfg_path = Path(path)
+        if not cfg_path.is_file():
+            raise FileNotFoundError(f"配置文件不存在: {cfg_path}")
+
+        try:
+            raw: dict[str, Any] = yaml.safe_load(cfg_path.read_text(encoding="utf-8")) or {}
+        except yaml.YAMLError as exc:
+            raise yaml.YAMLError(f"YAML 解析失败 ({cfg_path}): {exc}") from exc
+
+        # 覆盖已声明的字段
+        for fld_name in (
+            "listen_host", "listen_port", "metrics_port",
+            "upstream_url", "upstream_api_key",
+            "rate_rpm", "bucket_capacity",
+            "request_timeout",
+            "queue_max_size", "low_priority_timeout",
+            "fallback_enabled_passthrough",
+            "log_level",
+        ):
+            if fld_name in raw:
+                setattr(config, fld_name, raw[fld_name])
+
+    # 环境变量覆盖（最高优先级）
+    config = _apply_env_overrides(config)
+
+    # 验证
+    issues = _validate_config(config)
+    for issue in issues:
+        warnings.warn(issue)
+
+    return config

services/nvidia_sidecar/context.py

@@ -0,0 +1,75 @@
+"""
+NVIDIA Sidecar — SidecarContext 依赖注入容器 (§BIZ-46 Phase3)
+
+将所有模块级全局状态收敛为单一 dataclass，通过 FastAPI app.state 注入，
+消除 webui.py → server 的反向导入，支持可测试性和多实例扩展。
+
+设计文档: docs/architecture/BIZ-46_Phase3_Architecture_Design.md §1
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+if TYPE_CHECKING:
+    from nvidia_sidecar.config import SidecarConfig
+    from nvidia_sidecar.rate_limiter import AdaptiveTokenBucket
+    from nvidia_sidecar.priority_queue import PriorityRequestQueue
+    from nvidia_sidecar.metrics import PrometheusMetrics
+    from nvidia_sidecar.health import HealthService
+
+
+@dataclass
+class SidecarContext:
+    """Sidecar 全局运行时上下文 — 所有核心组件的唯一容器。
+
+    通过 ``app.state.sidecar`` 注入 FastAPI，路由通过 ``Depends(get_context)`` 获取。
+    """
+
+    # ---- 核心组件 ----
+    config: SidecarConfig
+    http_client: httpx.AsyncClient
+    token_bucket: AdaptiveTokenBucket
+    priority_queue: PriorityRequestQueue
+    prometheus: PrometheusMetrics
+    health: HealthService
+
+    # ---- 运行时状态 ----
+    pending_requests: dict[str, tuple["asyncio.Future[Any]", float]] = field(default_factory=dict)
+    """request_id → (response future, enqueued_at) 的映射。"""
+
+    stats: dict[str, int] = field(default_factory=lambda: {
+        "total_requests": 0,
+        "nvidia_requests": 0,
+        "passthrough_requests": 0,
+        "ratelimited_requests": 0,
+        "queue_full_rejects": 0,
+        "upstream_errors": 0,
+        "start_time": 0,
+    })
+
+    stats_lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+
+    # ---- 缓存 ----
+    snapshot_cache: tuple["dict[str, Any]", float] | None = None
+    """SSE 快照共享缓存: (data, timestamp)。"""
+    snapshot_cache_lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+    SNAPSHOT_CACHE_TTL: float = 1.0
+
+    # ---- 便捷方法 ----
+
+    async def increment_stat(self, key: str, delta: int = 1) -> None:
+        """线程安全的统计计数器自增。"""
+        async with self.stats_lock:
+            self.stats[key] = self.stats.get(key, 0) + delta
+
+    @property
+    def uptime_seconds(self) -> int:
+        """服务运行时长（秒）。"""
+        st = self.stats.get("start_time", 0)
+        return int(time.time() - st) if st else 0

services/nvidia_sidecar/deploy/.env.example

@@ -0,0 +1,31 @@
+# NVIDIA Sidecar 环境变量清单 (BIZ-46 Phase3 §4)
+# 复制为 .env 后按需修改，供 Docker / systemd 使用。
+
+# 网络
+SIDECAR_HOST=127.0.0.1
+SIDECAR_PORT=9190
+SIDECAR_METRICS_PORT=9191
+
+# 上游 API（必填）
+SIDECAR_UPSTREAM=https://integrate.api.nvidia.com/v1
+SIDECAR_API_KEY=nvapi-your-key-here
+
+# 限流
+SIDECAR_RATE_RPM=40
+SIDECAR_BUCKET_CAPACITY=40
+
+# 超时
+SIDECAR_TIMEOUT=60
+
+# 队列
+SIDECAR_QUEUE_MAX=500
+SIDECAR_LOW_TIMEOUT=2
+
+# 降级
+SIDECAR_FALLBACK_PASSTHROUGH=true
+
+# 日志
+SIDECAR_LOG_LEVEL=INFO
+
+# Admin API 认证（可选，不设置则跳过认证）
+# SIDECAR_ADMIN_TOKEN=your-admin-token-here

services/nvidia_sidecar/deploy/nvidia-sidecar.service

@@ -0,0 +1,49 @@
+# NVIDIA Sidecar 限流代理 — systemd service (BIZ-46 Phase3 §4)
+#
+# 安装：
+#   sudo cp deploy/nvidia-sidecar.service /etc/systemd/system/
+#   sudo systemctl daemon-reload
+#   sudo systemctl enable nvidia-sidecar
+#   sudo systemctl start nvidia-sidecar
+#
+# 运维：
+#   sudo systemctl status nvidia-sidecar
+#   sudo journalctl -u nvidia-sidecar -f
+
+[Unit]
+Description=NVIDIA Sidecar Rate-Limiting Proxy
+Documentation=https://github.com/bizwings/nvidia-sidecar
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=sidecar
+Group=sidecar
+WorkingDirectory=/opt/nvidia-sidecar
+ExecStart=/opt/nvidia-sidecar/.venv/bin/uvicorn nvidia_sidecar.server:app \
+    --host 127.0.0.1 \
+    --port 9190 \
+    --log-level info
+Restart=always
+RestartSec=5
+
+# 环境变量
+EnvironmentFile=/opt/nvidia-sidecar/.env
+
+# 安全加固
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+PrivateTmp=true
+ReadWritePaths=/opt/nvidia-sidecar/logs
+
+# 资源限制
+LimitNOFILE=65536
+MemoryMax=512M
+
+# 启动延迟（等待网络就绪）
+ExecStartPre=/bin/sleep 1
+
+[Install]
+WantedBy=multi-user.target

services/nvidia_sidecar/health.py

@@ -0,0 +1,198 @@
+"""
+NVIDIA Sidecar 限流代理 — 健康检查端点 (§3.6)
+
+提供 Kubernetes / systemd 兼容的健康检查：
+    GET /health       — 存活检查
+    GET /health/ready — 就绪检查（含上游连通性）
+
+BIZ-46 Phase3: Readiness HTTP Client 复用 — 注入主 http_client，
+不再每次检查创建新 client，降低 K8s/systemd 高频探测的连接开销。
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+
+@dataclass
+class HealthService:
+    """健康检查服务。
+
+    封装存活检查和就绪检查的逻辑，供 server.py 路由调用。
+    """
+
+    start_time: float = 0.0
+    version: str = "0.1.0"
+
+    def __post_init__(self) -> None:
+        if self.start_time == 0.0:
+            self.start_time = time.time()
+
+    @property
+    def uptime_seconds(self) -> float:
+        """服务运行时长（秒）。"""
+        return time.time() - self.start_time
+
+    async def check_upstream(
+        self,
+        upstream_url: str,
+        http_client: httpx.AsyncClient,
+        timeout: float = 5.0,
+        api_key: str = "",
+    ) -> bool:
+        """检查上游连通性（复用注入的 http_client，BIZ-46 Phase3）。
+
+        Args:
+            upstream_url: NVIDIA API base URL。
+            http_client: 复用的 httpx.AsyncClient（来自 ctx）。
+            timeout: 超时秒数（per-request override）。
+            api_key: 可选的 API Key 用于认证。
+
+        Returns:
+            True 上游可达。
+        """
+        try:
+            headers: dict[str, str] = {}
+            if api_key:
+                headers["authorization"] = f"Bearer {api_key}"
+
+            resp = await http_client.get(
+                f"{upstream_url.rstrip('/')}/v1/models",
+                headers=headers,
+                timeout=timeout,
+            )
+            return resp.status_code < 500
+        except Exception:
+            return False
+
+    def check_queue_healthy(
+        self,
+        current_size: int,
+        max_size: int,
+        threshold_ratio: float = 0.9,
+    ) -> bool:
+        """检查队列是否健康（未接近满载）。
+
+        Args:
+            current_size: 当前队列长度。
+            max_size: 队列最大容量。
+            threshold_ratio: 告警阈值比例，默认 0.9。
+
+        Returns:
+            True 队列健康。
+        """
+        if max_size <= 0:
+            return True
+        return current_size < max_size * threshold_ratio
+
+    def check_token_bucket_healthy(
+        self,
+        available_tokens: float,
+        capacity: int,
+        threshold: float = 0.05,
+    ) -> bool:
+        """检查令牌桶是否健康（token 未耗尽）。
+
+        Args:
+            available_tokens: 当前可用令牌数。
+            capacity: 桶容量。
+            threshold: 令牌数低于此比例视为不健康。
+
+        Returns:
+            True 令牌桶健康。
+        """
+        if capacity <= 0:
+            return False
+        return available_tokens > capacity * threshold
+
+    def liveness(self) -> dict[str, Any]:
+        """存活检查响应。
+
+        Returns:
+            liveness JSON payload。
+        """
+        return {
+            "status": "ok",
+            "uptime": round(self.uptime_seconds, 1),
+            "version": self.version,
+        }
+
+    async def readiness(
+        self,
+        upstream_url: str,
+        upstream_api_key: str = "",
+        queue_current_size: int = 0,
+        queue_max_size: int = 500,
+        available_tokens: float = 0.0,
+        bucket_capacity: int = 40,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> dict[str, Any]:
+        """就绪检查响应。
+
+        Args:
+            upstream_url: 上游 API 地址。
+            upstream_api_key: API Key。
+            queue_current_size: 当前队列长度。
+            queue_max_size: 队列最大容量。
+            available_tokens: 当前令牌数。
+            bucket_capacity: 桶容量。
+            http_client: 复用的 httpx.AsyncClient（BIZ-46 Phase3）。
+                为 None 时回退到每次创建新 client（兼容旧调用）。
+
+        Returns:
+            readiness JSON payload。
+        """
+        if http_client is not None:
+            upstream_ok = await self.check_upstream(
+                upstream_url, http_client=http_client, api_key=upstream_api_key,
+            )
+        else:
+            # 向后兼容：无 http_client 时沿用旧行为
+            upstream_ok = await self.check_upstream_standalone(
+                upstream_url, api_key=upstream_api_key,
+            )
+
+        queue_ok = self.check_queue_healthy(queue_current_size, queue_max_size)
+        token_ok = self.check_token_bucket_healthy(available_tokens, bucket_capacity)
+        all_ready = upstream_ok and queue_ok and token_ok
+
+        return {
+            "ready": all_ready,
+            "upstream_reachable": upstream_ok,
+            "queue_healthy": queue_ok,
+            "token_bucket_healthy": token_ok,
+        }
+
+    async def check_upstream_standalone(
+        self,
+        upstream_url: str,
+        timeout: float = 5.0,
+        api_key: str = "",
+    ) -> bool:
+        """独立检查上游连通性（向后兼容，每次创建新 client）。
+
+        Args:
+            upstream_url: NVIDIA API base URL。
+            timeout: 超时秒数。
+            api_key: 可选的 API Key。
+
+        Returns:
+            True 上游可达。
+        """
+        try:
+            headers: dict[str, str] = {}
+            if api_key:
+                headers["authorization"] = f"Bearer {api_key}"
+
+            async with httpx.AsyncClient(timeout=timeout) as client:
+                resp = await client.get(
+                    f"{upstream_url.rstrip('/')}/v1/models",
+                    headers=headers,
+                )
+                return resp.status_code < 500
+        except Exception:
+            return False

services/nvidia_sidecar/metrics.py

@@ -0,0 +1,277 @@
+"""
+NVIDIA Sidecar 限流代理 — Prometheus 指标端点 (§3.5)
+
+10 个指标，独立端口 :9191，与代理端口 :9190 分离。
+
+BIZ-46 Phase3: Prometheus 标签基数治理 — model_id label 收敛为 provider。
+- upstream_latency_seconds: model_id → provider (固定值 "nvidia", 基数=1)
+- upstream_errors_total: model_id → provider
+- 模型级信息迁移到 structlog JSON 日志
+"""
+
+from __future__ import annotations
+
+import time
+import threading
+from typing import Any
+
+from prometheus_client import (
+    CollectorRegistry,
+    Counter,
+    Gauge,
+    Histogram,
+    generate_latest,
+    make_asgi_app,
+)
+
+
+class PrometheusMetrics:
+    """Sidecar Prometheus 指标收集器。
+
+    线程安全，所有公开方法通过 ``threading.Lock`` 保护。
+    """
+
+    def __init__(self, registry: CollectorRegistry | None = None) -> None:
+        """初始化所有 10 个 Prometheus 指标。
+
+        Args:
+            registry: 可选自定义 Registry；None 则使用默认全局 registry。
+        """
+        self._registry: CollectorRegistry = registry or CollectorRegistry()
+        self._lock: threading.Lock = threading.Lock()
+        self._start_time: float = time.time()
+
+        # ---- 1. 总请求数（按优先级 + 状态分组） ----
+        self.requests_total: Counter = Counter(
+            "sidecar_requests_total",
+            "Total requests processed by priority and status",
+            labelnames=["priority", "status"],
+            registry=self._registry,
+        )
+
+        # ---- 2. 可用令牌数 ----
+        self.tokens_available: Gauge = Gauge(
+            "sidecar_tokens_available",
+            "Current number of available tokens",
+            registry=self._registry,
+        )
+
+        # ---- 3. 令牌生成速率 ----
+        self.tokens_rate: Gauge = Gauge(
+            "sidecar_tokens_rate",
+            "Current token generation rate (tokens per minute)",
+            registry=self._registry,
+        )
+
+        # ---- 4. 各优先级队列深度 ----
+        self.queue_depth: Gauge = Gauge(
+            "sidecar_queue_depth",
+            "Queue depth by priority",
+            labelnames=["priority"],
+            registry=self._registry,
+        )
+
+        # ---- 5. 队列等待时间 Histogram ----
+        self.queue_latency_seconds: Histogram = Histogram(
+            "sidecar_queue_latency_seconds",
+            "Request wait time in queue in seconds",
+            labelnames=["priority"],
+            buckets=(0.01, 0.05, 0.1, 0.5, 1.0, 2.0, 5.0, 10.0, 30.0, 60.0, 120.0),
+            registry=self._registry,
+        )
+
+        # ---- 6. 上游响应延迟 Histogram（label 收敛: model_id → provider） ----
+        self.upstream_latency_seconds: Histogram = Histogram(
+            "sidecar_upstream_latency_seconds",
+            "Upstream response latency in seconds",
+            labelnames=["provider"],  # BIZ-46: was ["model_id"], converged to fixed-cardinality provider
+            buckets=(0.1, 0.5, 1.0, 2.0, 5.0, 10.0, 30.0, 60.0, 120.0, 300.0, 600.0),
+            registry=self._registry,
+        )
+
+        # ---- 7. 上游错误计数（label 收敛: model_id → provider） ----
+        self.upstream_errors_total: Counter = Counter(
+            "sidecar_upstream_errors_total",
+            "Upstream error count by status code and provider",
+            labelnames=["status_code", "provider"],  # BIZ-46: was ["model_id"], converged
+            registry=self._registry,
+        )
+
+        # ---- 8. 降级直通次数 ----
+        self.fallback_passthrough_total: Counter = Counter(
+            "sidecar_fallback_passthrough_total",
+            "Total fallback / passthrough events (queue full or sidecar unavailable)",
+            registry=self._registry,
+        )
+
+        # ---- 9. 健康状态 ----
+        self.health_status: Gauge = Gauge(
+            "sidecar_health_status",
+            "Sidecar health: 0=unhealthy, 1=healthy",
+            registry=self._registry,
+        )
+
+        # ---- 10. 运行时长 ----
+        self.uptime_seconds: Gauge = Gauge(
+            "sidecar_uptime_seconds",
+            "Process uptime in seconds",
+            registry=self._registry,
+        )
+
+        # 避退模式指标（附加，不计入基础 10 个）
+        self.retreat_state: Gauge = Gauge(
+            "sidecar_retreat_state",
+            "Adaptive retreat state: 0=NORMAL, 1=RETREAT, 2=RECOVER",
+            registry=self._registry,
+        )
+        self.effective_rate_rpm: Gauge = Gauge(
+            "sidecar_effective_rate_rpm",
+            "Current effective rate in RPM (after retreat adjustments)",
+            registry=self._registry,
+        )
+        self.upstream_429_rate: Gauge = Gauge(
+            "sidecar_upstream_429_rate",
+            "Upstream 429 rate over the retreat observation window (0.0-1.0)",
+            registry=self._registry,
+        )
+
+        # 初始化
+        self.health_status.set(1)
+
+    # ---- ASGI app 生成 ----
+
+    def build_asgi_app(self) -> Any:
+        """生成 Prometheus ASGI 应用，挂载到独立端口。
+
+        Returns:
+            可传给 uvicorn 的 ASGI app。
+        """
+        return make_asgi_app(registry=self._registry)
+
+    # ---- 指标记录方法 ----
+
+    def record_request(self, priority: str, status: str) -> None:
+        """记录一次请求。
+
+        Args:
+            priority: 优先级名（URGENT / HIGH / NORMAL / LOW）。
+            status: 状态（success / ratelimited / error）。
+        """
+        with self._lock:
+            self.requests_total.labels(priority=priority, status=status).inc()
+
+    def record_queue_latency(self, priority: str, seconds: float) -> None:
+        """记录排队延迟。
+
+        Args:
+            priority: 优先级名。
+            seconds: 排队等待秒数。
+        """
+        with self._lock:
+            self.queue_latency_seconds.labels(priority=priority).observe(seconds)
+
+    def record_upstream(self, status_code: int, provider: str) -> None:
+        """记录上游响应（label 收敛: provider 替代 model_id，BIZ-46 Phase3）。
+
+        Args:
+            status_code: HTTP 状态码。
+            provider: 上游提供商标识（固定 "nvidia"）。
+        """
+        with self._lock:
+            self.upstream_latency_seconds.labels(provider=provider).observe(0.0)
+
+    def record_upstream_error(self, status_code: int, provider: str) -> None:
+        """记录上游错误（label 收敛: provider 替代 model_id，BIZ-46 Phase3）。
+
+        Args:
+            status_code: 错误 HTTP 状态码。
+            provider: 上游提供商标识（固定 "nvidia"）。
+        """
+        with self._lock:
+            self.upstream_errors_total.labels(
+                status_code=str(status_code), provider=provider
+            ).inc()
+
+    def record_upstream_latency(self, provider: str, seconds: float) -> None:
+        """记录上游响应延迟（label 收敛: provider 替代 model_id，BIZ-46 Phase3）。
+
+        Args:
+            provider: 上游提供商标识（固定 "nvidia"）。
+            seconds: 响应延迟秒数。
+        """
+        with self._lock:
+            self.upstream_latency_seconds.labels(provider=provider).observe(seconds)
+
+    def update_token_status(self, tokens: float, rate_per_minute: float) -> None:
+        """更新令牌桶状态。
+
+        Args:
+            tokens: 当前可用令牌数。
+            rate_per_minute: 每分钟速率。
+        """
+        with self._lock:
+            self.tokens_available.set(tokens)
+            self.tokens_rate.set(rate_per_minute)
+
+    def update_queue_depth(self, depths: dict[str, int]) -> None:
+        """更新各优先级队列深度。
+
+        Args:
+            depths: {priority_name: count} 映射。
+        """
+        with self._lock:
+            # 先清零所有已知标签再设置，避免残留旧值
+            for pri in ("URGENT", "HIGH", "NORMAL", "LOW"):
+                self.queue_depth.labels(priority=pri).set(depths.get(pri, 0))
+
+    def increment_fallback(self) -> None:
+        """降级直通计数 +1。"""
+        with self._lock:
+            self.fallback_passthrough_total.inc()
+
+    def set_health(self, healthy: bool) -> None:
+        """设置健康状态。
+
+        Args:
+            healthy: True=健康, False=不健康。
+        """
+        with self._lock:
+            self.health_status.set(1 if healthy else 0)
+
+    def update_uptime(self) -> None:
+        """更新运行时长。"""
+        with self._lock:
+            self.uptime_seconds.set(time.time() - self._start_time)
+
+    # ---- 避退模式指标 ----
+
+    def update_retreat_metrics(
+        self,
+        retreat_state: str,
+        effective_rate_rpm: float,
+        upstream_429_rate: float,
+    ) -> None:
+        """更新避退模式指标。
+
+        Args:
+            retreat_state: "normal" / "retreat" / "recover".
+            effective_rate_rpm: 当前实际速率 (RPM)。
+            upstream_429_rate: 上游 429 率 (0.0-1.0)。
+        """
+        state_map: dict[str, int] = {"normal": 0, "retreat": 1, "recover": 2}
+        with self._lock:
+            self.retreat_state.set(state_map.get(retreat_state, 0))
+            self.effective_rate_rpm.set(effective_rate_rpm)
+            self.upstream_429_rate.set(upstream_429_rate)
+
+    # ---- 导出 ----
+
+    def generate_latest(self) -> bytes:
+        """生成 Prometheus 文本格式的指标数据。
+
+        Returns:
+            Prometheus 文本格式 bytes。
+        """
+        with self._lock:
+            self.update_uptime()
+        return generate_latest(self._registry)

services/nvidia_sidecar/priority_queue.py

@@ -0,0 +1,253 @@
+"""
+NVIDIA Sidecar 限流代理 — 四级优先级请求队列模块 (§3.3)
+
+管理待处理的 NVIDIA API 请求，按优先级 + FIFO 出队。
+支持三种队列满策略：PASSTHROUGH / REJECT / DROP_LOWEST。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import heapq
+import time
+import uuid
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from nvidia_sidecar.rate_limiter import Priority
+
+
+# ---------------------------------------------------------------------------
+# 队列满策略
+# ---------------------------------------------------------------------------
+
+class QueueFullPolicy(str, Enum):
+    """队列满时的处理策略。"""
+    PASSTHROUGH = "passthrough"   # 直通上游，绕过排队（fail-open 子策略）
+    REJECT = "reject"             # 返回 503 Service Unavailable
+    DROP_LOWEST = "drop_lowest"   # 丢弃队列中最低优先级元素，插入新请求
+
+
+# ---------------------------------------------------------------------------
+# 队列元素
+# ---------------------------------------------------------------------------
+
+@dataclass(order=True)
+class PriorityQueueItem:
+    """优先级队列元素。
+
+    ``sort_index`` 由 ``(priority, timestamp)`` 组成，
+    Python 的 ``__lt__`` 按字段顺序比较：先比 priority，再比 timestamp。
+    数值越小越优先（URGENT=1 优于 HIGH=2）。
+    """
+    sort_index: tuple[int, float] = field(compare=True)
+    priority: Priority = field(compare=False)
+    request_id: str = field(compare=False)
+    payload: dict[str, Any] = field(compare=False)
+    enqueued_at: float = field(compare=False)
+    headers: dict[str, str] = field(default_factory=dict, compare=False)
+
+
+# ---------------------------------------------------------------------------
+# 优先级请求队列
+# ---------------------------------------------------------------------------
+
+class QueueFullError(Exception):
+    """队列已满且策略为 REJECT 时抛出。"""
+    pass
+
+
+class QueueFullPassthrough(Exception):
+    """队列已满且策略为 PASSTHROUGH 时抛出，由调用方绕过队列直通上游。"""
+    pass
+
+
+class PriorityRequestQueue:
+    """异步线程安全的四级优先级请求队列。
+
+    内部使用 ``asyncio.Lock`` 保护并发操作，
+    基于 ``heapq`` + ``asyncio.Event`` 实现阻塞出队。
+    """
+
+    def __init__(self, max_size: int = 500) -> None:
+        """初始化优先级队列。
+
+        Args:
+            max_size: 队列最大容量。
+
+        Raises:
+            ValueError: max_size <= 0。
+        """
+        if max_size <= 0:
+            raise ValueError(f"max_size 必须为正整数，当前值: {max_size}")
+        self.max_size: int = max_size
+        self._heap: list[PriorityQueueItem] = []
+        self._lock: asyncio.Lock = asyncio.Lock()
+        self._not_empty: asyncio.Event = asyncio.Event()
+        self._full_policy: QueueFullPolicy = QueueFullPolicy.PASSTHROUGH
+
+        # 统计
+        self._total_enqueued: int = 0
+        self._total_dequeued: int = 0
+        self._total_dropped: int = 0
+
+    # ---- 队列满策略 ---- 
+
+    def set_full_policy(self, policy: QueueFullPolicy) -> None:
+        """设置队列满时的处理策略。
+
+        Args:
+            policy: QueueFullPolicy 枚举值。
+        """
+        self._full_policy = policy
+
+    @property
+    def full_policy(self) -> QueueFullPolicy:
+        """当前队列满策略。"""
+        return self._full_policy
+
+    # ---- 动态容量调整 ----
+
+    def set_max_size(self, new_size: int) -> tuple[bool, str]:
+        """动态调整队列最大容量（热重载）。
+
+        缩小操作受保护：如果 new_size 小于当前排队数，拒绝变更并
+        提示当前队列深度。
+
+        Args:
+            new_size: 新的最大容量。
+
+        Returns:
+            (成功标志, 消息)。成功时标志为 True，消息含新旧容量对比；
+            失败时标志为 False，消息含拒绝原因和当前深度。
+
+        Raises:
+            ValueError: new_size <= 0。
+        """
+        if new_size <= 0:
+            raise ValueError(f"max_size 必须为正整数，当前值: {new_size}")
+        current = len(self._heap)
+        if new_size < current:
+            return (False, f"拒绝缩小：新上限 {new_size} < 当前排队数 {current}，需要先排空或提升上限")
+        old = self.max_size
+        self.max_size = new_size
+        return (True, f"队列上限已调整：{old} → {new_size}{'（当前排队 ' + str(current) + '）' if current > 0 else ''}")
+
+    # ---- 入队 ----
+
+    async def put(
+        self,
+        item: dict[str, Any],
+        priority: Priority = Priority.NORMAL,
+        headers: dict[str, str] | None = None,
+    ) -> str:
+        """将请求放入队列。
+
+        Args:
+            item: 请求体（JSON 序列化的 dict）。
+            priority: 请求优先级，默认 NORMAL。
+            headers: 原始请求 headers。
+
+        Returns:
+            分配的唯一 request_id。
+
+        Raises:
+            QueueFullError: 队列满且策略为 REJECT。
+        """
+        request_id = str(uuid.uuid4())
+        headers = headers or {}
+
+        queue_item = PriorityQueueItem(
+            sort_index=(int(priority), time.monotonic()),
+            priority=priority,
+            request_id=request_id,
+            payload=item,
+            enqueued_at=time.monotonic(),
+            headers=headers,
+        )
+
+        async with self._lock:
+            queue_size = len(self._heap)
+            if queue_size >= self.max_size:
+                if self._full_policy == QueueFullPolicy.REJECT:
+                    raise QueueFullError(
+                        f"队列已满 ({queue_size}/{self.max_size})，策略: reject"
+                    )
+                elif self._full_policy == QueueFullPolicy.DROP_LOWEST:
+                    # 丢弃 heap 中优先级最低（值最大）的元素
+                    # heap 是最小堆，找最大值需要遍历
+                    max_val_item = max(self._heap, key=lambda x: x.sort_index)
+                    self._heap.remove(max_val_item)
+                    heapq.heapify(self._heap)
+                    self._total_dropped += 1
+                # PASSTHROUGH 策略：不插入队列，抛异常让调用方绕过排队
+                else:
+                    raise QueueFullPassthrough(
+                        f"队列已满 ({queue_size}/{self.max_size})，策略: passthrough"
+                    )
+
+            heapq.heappush(self._heap, queue_item)
+            self._total_enqueued += 1
+
+        self._not_empty.set()
+        return request_id
+
+    # ---- 出队 ----
+
+    async def get(self, timeout: float = 1.0) -> PriorityQueueItem | None:
+        """从队列取出下一个元素（阻塞、优先级排序）。
+
+        Args:
+            timeout: 阻塞等待的最大秒数，默认 1.0。
+
+        Returns:
+            优先级最高的队列元素；超时无元素时返回 None。
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            async with self._lock:
+                if self._heap:
+                    item = heapq.heappop(self._heap)
+                    self._total_dequeued += 1
+                    if not self._heap:
+                        self._not_empty.clear()
+                    return item
+
+            # 队列为空，等待新元素入队
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return None
+            try:
+                await asyncio.wait_for(
+                    self._not_empty.wait(),
+                    timeout=remaining,
+                )
+            except asyncio.TimeoutError:
+                return None
+
+    # ---- 状态查询 ----
+
+    async def get_queue_size(self) -> int:
+        """返回当前队列长度。"""
+        async with self._lock:
+            return len(self._heap)
+
+    async def get_stats(self) -> dict[str, Any]:
+        """返回队列统计信息。"""
+        async with self._lock:
+            depth_by_priority: dict[str, int] = {}
+            for item in self._heap:
+                key = item.priority.name
+                depth_by_priority[key] = depth_by_priority.get(key, 0) + 1
+
+            return {
+                "max_size": self.max_size,
+                "current_size": len(self._heap),
+                "total_enqueued": self._total_enqueued,
+                "total_dequeued": self._total_dequeued,
+                "total_dropped": self._total_dropped,
+                "depth_by_priority": depth_by_priority,
+                "full_policy": self._full_policy.value,
+                "utilization": len(self._heap) / self.max_size if self.max_size > 0 else 0.0,
+            }

services/nvidia_sidecar/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "nvidia_sidecar"
+version = "0.1.0"
+description = "NVIDIA Sidecar 限流代理 — 为 NVIDIA API 提供优先级排队 + 令牌桶限流"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.34",
+    "httpx>=0.28",
+    "PyYAML>=6.0",
+    "structlog>=24.4",
+    "prometheus-client>=0.21",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+    "httpx>=0.28",
+    "mypy>=1.14",
+    "types-PyYAML",
+]
+
+[project.scripts]
+nvidia-sidecar = "nvidia_sidecar.server:main"
+
+[build-system]
+requires = ["setuptools>=75", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["nvidia_sidecar"]
+
+[tool.setuptools.package-dir]
+# Flat layout: __init__.py + all .py files at project root
+"nvidia_sidecar" = "."
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+[[tool.mypy.overrides]]
+module = "structlog.*"
+ignore_missing_imports = true

services/nvidia_sidecar/rate_limiter.py

@@ -0,0 +1,438 @@
+"""
+NVIDIA Sidecar 限流代理 — 令牌桶 + 网关识别模块 (§3.2)
+
+从 BIZ-26 rate_limiter.py 提取核心限流逻辑，去除多线程调度器、缓存管理等。
+保留：Priority, TokenBucket, is_nvidia_gateway, normalize_gateway_name。
+"""
+
+from __future__ import annotations
+
+import time
+import threading
+from enum import IntEnum
+from typing import Any
+
+
+# ---------------------------------------------------------------------------
+# 优先级枚举
+# ---------------------------------------------------------------------------
+
+class Priority(IntEnum):
+    """请求优先级（数值越小优先级越高）。"""
+    URGENT = 1
+    HIGH = 2
+    NORMAL = 3
+    LOW = 4
+
+
+# ---------------------------------------------------------------------------
+# NVIDIA 网关别名集
+# ---------------------------------------------------------------------------
+
+NVIDIA_GATEWAY_ALIASES: set[str] = {
+    "nvidia",
+    "nvidia-gateway",
+    "nvidiavx",
+    "nvidiavx18088980513",
+}
+
+
+def is_nvidia_gateway(value: str | None) -> bool:
+    """判断给定网关名/模型全路径是否属于 NVIDIA 网关。
+
+    Args:
+        value: 网关名（如 ``"nvidia"``）或模型全路径前缀
+               （如 ``"nvidia/deepseek-ai/deepseek-v4-pro"``）。
+               None 时直接返回 False。
+
+    Returns:
+        True 当 value 的 provider 部分匹配已知 NVIDIA 别名。
+    """
+    if value is None:
+        return False
+
+    # 提取 provider 前缀：取 "/" 前第一个部分
+    provider = value.split("/", 1)[0].lower().strip()
+    return provider in NVIDIA_GATEWAY_ALIASES
+
+
+def normalize_gateway_name(value: str | None) -> str | None:
+    """规范化网关名：提取 provider 前缀并转为小写。
+
+    Args:
+        value: 网关名或模型全路径。None 时返回 None。
+
+    Returns:
+        provider 前缀的小写形式，或 None。
+    """
+    if value is None:
+        return None
+    return value.split("/", 1)[0].lower().strip()
+
+
+# ---------------------------------------------------------------------------
+# 令牌桶（线程安全）
+# ---------------------------------------------------------------------------
+
+class TokenBucket:
+    """线程安全的令牌桶实现。
+
+    支持固定速率令牌补充和消费，带有溢出保护和可选的阻塞等待。
+    """
+
+    def __init__(self, rate: float = 40 / 60, capacity: int = 40) -> None:
+        """初始化令牌桶。
+
+        Args:
+            rate: 令牌补充速率（令牌/秒）。默认 40/60 ≈ 0.667 token/s（40 RPM）。
+            capacity: 桶最大容量（令牌数）。默认 40。
+        """
+        self._rate: float = float(rate)
+        self._capacity: int = int(capacity)
+        self._tokens: float = float(capacity)  # 启动时桶满
+        self._last_refill: float = time.monotonic()
+        self._lock: threading.Lock = threading.Lock()
+
+    # ---- 内部方法 ----
+
+    def _refill(self) -> None:
+        """补充令牌（调用方需持有 _lock）。
+
+        根据距上次补充的时间差计算新增令牌数，不超过 capacity。
+        """
+        now = time.monotonic()
+        elapsed = now - self._last_refill
+        if elapsed > 0 and self._rate > 0:
+            new_tokens = elapsed * self._rate
+            self._tokens = min(self._tokens + new_tokens, float(self._capacity))
+        self._last_refill = now
+
+    # ---- 公开方法 ----
+
+    def consume(self, tokens: int = 1) -> bool:
+        """尝试立即消费令牌（非阻塞）。
+
+        Args:
+            tokens: 要消费的令牌数，默认 1。
+
+        Returns:
+            True 消费成功；False 令牌不足。
+        """
+        if tokens <= 0:
+            return True
+
+        with self._lock:
+            self._refill()
+            if self._tokens >= tokens:
+                self._tokens -= tokens
+                return True
+            return False
+
+    def try_consume(self, tokens: int = 1, timeout: float = 2.0) -> bool:
+        """尝试在指定时间内消费令牌（阻塞）。
+
+        Args:
+            tokens: 要消费的令牌数，默认 1。
+            timeout: 最大等待秒数，默认 2.0。
+
+        Returns:
+            True 在超时前成功消费；False 超时。
+        """
+        if tokens <= 0:
+            return True
+
+        deadline = time.monotonic() + timeout
+        while True:
+            with self._lock:
+                self._refill()
+                if self._tokens >= tokens:
+                    self._tokens -= tokens
+                    return True
+
+            # 释放锁后计算剩余等待时间
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return False
+            # 等待到下一个令牌应该补充的时间点
+            sleep_time = min(remaining, max(0.05, 1.0 / self._rate) if self._rate > 0 else remaining)
+            time.sleep(sleep_time)
+
+    def wait_for_token(self, timeout: float | None = None) -> bool:
+        """等待并尝试消费 1 个令牌。
+
+        Args:
+            timeout: 最大等待秒数；None 表示无限等待（不推荐）。
+
+        Returns:
+            True 成功消费；False 超时。
+        """
+        return self.try_consume(tokens=1, timeout=timeout if timeout is not None else float("inf"))
+
+    def get_status(self) -> dict[str, Any]:
+        """获取令牌桶当前状态。
+
+        Returns:
+            包含 tokens, capacity, rate_per_minute, utilization 的字典。
+        """
+        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),
+            }
+
+    # ---- 属性 ----
+
+    @property
+    def rate(self) -> float:
+        """当前令牌补充速率（令牌/秒）。"""
+        return self._rate
+
+    @property
+    def capacity(self) -> int:
+        """桶容量。"""
+        return self._capacity
+
+    # ---- 动态速率调整（供 AdaptiveTokenBucket 使用） ----
+
+    def set_rate(self, rate: float) -> None:
+        """动态调整令牌补充速率（令牌/秒）。
+
+        Args:
+            rate: 新速率（令牌/秒）。
+        """
+        with self._lock:
+            self._refill()  # 先补充现有令牌再切换速率
+            self._rate = float(rate)
+
+
+# ---------------------------------------------------------------------------
+# 避退模式：AdaptiveTokenBucket (§ADR-009)
+# ---------------------------------------------------------------------------
+
+class RetreatState:
+    """避退状态机常量。"""
+    NORMAL: str = "normal"
+    RETREAT: str = "retreat"
+    RECOVER: str = "recover"
+
+
+class AdaptiveTokenBucket(TokenBucket):
+    """自适应避退令牌桶（ADR-009）。
+
+    监控上游 429 率（60s 滑动窗口），自动调整发射速率：
+
+    - 429 率 < 5%   → NORMAL，保持基准速率
+    - 429 率 5-10%  → RETREAT，速率 × 0.75
+    - 429 率 10-20% → RETREAT，再次降速
+    - 429 率 > 20%  → RETREAT，最低 5 RPM + 告警
+    - 连续 120s 429 率 < 2% → RECOVER，逐步 +2 RPM 恢复
+
+    线程安全，继承 TokenBucket 的所有公共接口。
+    """
+
+    # ADR-009 参数（可通过构造函数覆盖）
+    RETREAT_WINDOW_SECONDS: float = 60.0
+    RETREAT_429_THRESHOLD: float = 0.05
+    RETREAT_FACTOR: float = 0.75
+    RETREAT_MIN_RPM: float = 5.0
+    RECOVER_WINDOW_SECONDS: float = 120.0
+    RECOVER_429_THRESHOLD: float = 0.02
+    RECOVER_INCREMENT_RPM: float = 2.0
+
+    def __init__(
+        self,
+        rate: float = 40 / 60,
+        capacity: int = 40,
+        *,
+        retreat_window_seconds: float = 60.0,
+        retreat_429_threshold: float = 0.05,
+        retreat_factor: float = 0.75,
+        retreat_min_rpm: float = 5.0,
+        recover_window_seconds: float = 120.0,
+        recover_429_threshold: float = 0.02,
+        recover_increment_rpm: float = 2.0,
+    ) -> None:
+        """初始化自适应避退令牌桶。
+
+        Args:
+            rate: 基准令牌补充速率（令牌/秒）。默认 40/60 ≈ 0.667 token/s。
+            capacity: 桶最大容量。默认 40。
+            retreat_window_seconds: 429 率滑动窗口大小（秒）。
+            retreat_429_threshold: 触发避退的 429 率阈值。
+            retreat_factor: 每次避退速率乘数。
+            retreat_min_rpm: 避退最低 RPM。
+            recover_window_seconds: 恢复观察窗口大小（秒）。
+            recover_429_threshold: 触发恢复的 429 率阈值。
+            recover_increment_rpm: 每次恢复增加的 RPM。
+        """
+        super().__init__(rate=rate, capacity=capacity)
+
+        # 基准速率（不变）
+        self._base_rate: float = float(rate)
+
+        # 避退参数
+        self.RETREAT_WINDOW_SECONDS = retreat_window_seconds
+        self.RETREAT_429_THRESHOLD = retreat_429_threshold
+        self.RETREAT_FACTOR = retreat_factor
+        self.RETREAT_MIN_RPM = retreat_min_rpm
+        self.RECOVER_WINDOW_SECONDS = recover_window_seconds
+        self.RECOVER_429_THRESHOLD = recover_429_threshold
+        self.RECOVER_INCREMENT_RPM = recover_increment_rpm
+
+        # 避退状态机
+        self._retreat_state: str = RetreatState.NORMAL
+
+        # 429 滑动窗口：[(timestamp, is_429), ...]
+        self._429_window: list[tuple[float, bool]] = []
+
+        # 上次状态变更时间
+        self._last_state_change: float = time.monotonic()
+
+        # 避退状态锁（RLock 防止 evaluate_retreat() → get_429_rate() 重入死锁）
+        self._retreat_lock: threading.RLock = threading.RLock()
+
+    # ---- 429 反馈 ----
+
+    def record_response(self, is_429: bool) -> None:
+        """记录一次上游响应是否为 429。
+
+        Args:
+            is_429: True 表示上游返回了 429。
+        """
+        now = time.monotonic()
+        with self._retreat_lock:
+            self._429_window.append((now, is_429))
+            # 清理超出观察窗口的旧记录
+            cutoff = now - max(
+                self.RETREAT_WINDOW_SECONDS,
+                self.RECOVER_WINDOW_SECONDS,
+            )
+            self._429_window = [
+                (ts, flag) for ts, flag in self._429_window
+                if ts >= cutoff
+            ]
+
+    def get_429_rate(self, window_seconds: float | None = None) -> float:
+        """获取指定窗口内的 429 率。
+
+        Args:
+            window_seconds: 滑动窗口大小；None 使用 RETREAT_WINDOW_SECONDS。
+
+        Returns:
+            0.0-1.0 之间的 429 率。
+        """
+        ws = window_seconds or self.RETREAT_WINDOW_SECONDS
+        now = time.monotonic()
+        with self._retreat_lock:
+            in_window = [flag for ts, flag in self._429_window if now - ts <= ws]
+            if not in_window:
+                return 0.0
+            return sum(1 for f in in_window if f) / len(in_window)
+
+    # ---- 避退状态评估 ----
+
+    def evaluate_retreat(self) -> str:
+        """评估并更新避退状态，返回新状态名。
+
+        每次调用根据当前 429 率 + 持续时间决定是否进入 RETREAT / RECOVER。
+
+        Returns:
+            "normal" / "retreat" / "recover"。
+        """
+        now = time.monotonic()
+        with self._retreat_lock:
+            retreat_rate = self.get_429_rate(self.RETREAT_WINDOW_SECONDS)
+            recover_rate = self.get_429_rate(self.RECOVER_WINDOW_SECONDS)
+
+            if self._retreat_state == RetreatState.NORMAL:
+                if retreat_rate >= self.RETREAT_429_THRESHOLD:
+                    self._retreat_state = RetreatState.RETREAT
+                    self._last_state_change = now
+                    self._apply_retreat()
+
+            elif self._retreat_state == RetreatState.RETREAT:
+                # 持续高 429 率 → 再次降速
+                if retreat_rate >= self.RETREAT_429_THRESHOLD * 2:
+                    # 429 > 10%，再次降速
+                    if self._rate > self.RETREAT_MIN_RPM / 60.0:
+                        self._apply_retreat()
+                elif recover_rate < self.RECOVER_429_THRESHOLD:
+                    time_in_low = now - self._last_state_change
+                    if time_in_low >= self.RECOVER_WINDOW_SECONDS:
+                        self._retreat_state = RetreatState.RECOVER
+                        self._last_state_change = now
+                        self._apply_recover()
+
+            elif self._retreat_state == RetreatState.RECOVER:
+                if retreat_rate >= self.RETREAT_429_THRESHOLD:
+                    # 恢复期间 429 回升，重新进入避退
+                    self._retreat_state = RetreatState.RETREAT
+                    self._last_state_change = now
+                    self._apply_retreat()
+                elif self._rate >= self._base_rate:
+                    # 已恢复到基准速率
+                    self._rate = self._base_rate
+                    self._retreat_state = RetreatState.NORMAL
+                    self._last_state_change = now
+                else:
+                    # 继续逐步恢复
+                    self._apply_recover()
+
+            return self._retreat_state
+
+    def _apply_retreat(self) -> None:
+        """执行一次避退降速。"""
+        new_rate: float = max(
+            self.RETREAT_MIN_RPM / 60.0,
+            self._rate * self.RETREAT_FACTOR,
+        )
+        self._rate = new_rate
+
+    def _apply_recover(self) -> None:
+        """执行一次恢复提速。"""
+        increment: float = self.RECOVER_INCREMENT_RPM / 60.0
+        new_rate: float = min(self._base_rate, self._rate + increment)
+        self._rate = new_rate
+
+    # ---- 状态查询 ----
+
+    def get_retreat_state(self) -> str:
+        """获取当前避退状态。
+
+        Returns:
+            "normal" / "retreat" / "recover"。
+        """
+        with self._retreat_lock:
+            return self._retreat_state
+
+    def get_effective_rate_rpm(self) -> float:
+        """获取当前实际速率（RPM），考虑避退乘数。
+
+        Returns:
+            当前每分钟速率。
+        """
+        with self._lock:
+            return self._rate * 60.0
+
+    def get_base_rate_rpm(self) -> float:
+        """获取基准速率（RPM），即未避退时的速率。
+
+        Returns:
+            基准每分钟速率。
+        """
+        return self._base_rate * 60.0
+
+    def reset_to_base(self) -> None:
+        """手动重置到基准速率（用于运维干预）。"""
+        with self._retreat_lock:
+            self._rate = self._base_rate
+            self._retreat_state = RetreatState.NORMAL
+            self._last_state_change = time.monotonic()
+            self._429_window.clear()

services/nvidia_sidecar/server.py

@@ -0,0 +1,822 @@
+"""
+NVIDIA Sidecar 限流代理 — FastAPI 代理主入口 (§3.4)
+
+完整的 API 代理链路：
+    接收 → 网关识别 → [NVIDIA: 排队 → 令牌限流] → httpx 转发 → 返回
+
+非 NVIDIA 请求直通上游，NVIDIA 请求经过四级优先级队列 + 令牌桶限流。
+
+BIZ-46 Phase3: 架构解耦 — 所有全局状态收敛为 SidecarContext (§1)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import Any
+
+import httpx
+import structlog
+import uvicorn
+from fastapi import Depends, FastAPI, Request, Response
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse, StreamingResponse
+
+from nvidia_sidecar.config import load_config, SidecarConfig
+from nvidia_sidecar.context import SidecarContext
+from nvidia_sidecar.rate_limiter import (
+    Priority,
+    AdaptiveTokenBucket,
+    is_nvidia_gateway,
+)
+from nvidia_sidecar.priority_queue import (
+    PriorityRequestQueue,
+    QueueFullError,
+    QueueFullPassthrough,
+    QueueFullPolicy,
+)
+from nvidia_sidecar.metrics import PrometheusMetrics
+from nvidia_sidecar.health import HealthService
+from nvidia_sidecar.webui import webui_router
+
+# ---------------------------------------------------------------------------
+# 结构化日志
+# ---------------------------------------------------------------------------
+
+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(),
+    ],
+    context_class=dict,
+    logger_factory=structlog.PrintLoggerFactory(),
+    wrapper_class=structlog.stdlib.BoundLogger,
+    cache_logger_on_first_use=True,
+)
+logger: structlog.stdlib.BoundLogger = structlog.get_logger("nvidia_sidecar")
+
+
+# ---------------------------------------------------------------------------
+# FastAPI 依赖注入
+# ---------------------------------------------------------------------------
+
+def get_context(request: Request) -> SidecarContext:
+    """从 app.state 获取 SidecarContext（FastAPI 依赖注入）。"""
+    return request.app.state.sidecar  # type: ignore[no-any-return]
+
+
+# ---------------------------------------------------------------------------
+# 工具函数
+# ---------------------------------------------------------------------------
+
+def _extract_model(body: Any) -> str | None:
+    """从请求体中提取模型标识符（兼容 OpenAI Chat/Completions 格式）。
+
+    Args:
+        body: 已解析的 JSON 请求体。
+
+    Returns:
+        模型标识符字符串，或 None。
+    """
+    if isinstance(body, dict):
+        return str(body.get("model", "")) or None
+    return None
+
+
+def _resolve_priority(headers: dict[str, str]) -> Priority:
+    """从请求 headers 解析优先级。
+
+    检查 ``X-Priority`` header，值为 ``urgent``/``high``/``normal``/``low``，
+    不区分大小写。默认 NORMAL。
+    """
+    raw = headers.get("x-priority", "").strip().lower()
+    mapping: dict[str, Priority] = {
+        "urgent": Priority.URGENT,
+        "high": Priority.HIGH,
+        "normal": Priority.NORMAL,
+        "low": Priority.LOW,
+    }
+    return mapping.get(raw, Priority.NORMAL)
+
+
+# ---------------------------------------------------------------------------
+# 上游转发
+# ---------------------------------------------------------------------------
+
+async def _forward_to_upstream(
+    ctx: SidecarContext,
+    method: str,
+    path: str,
+    body: bytes | None,
+    headers: dict[str, str],
+    stream: bool = False,
+) -> httpx.Response:
+    """将请求转发到 NVIDIA 上游 API。
+
+    Args:
+        ctx: SidecarContext 运行时上下文。
+        method: HTTP 方法。
+        path: 请求路径（如 ``/v1/chat/completions``）。
+        body: 原始请求体 bytes。
+        headers: 要转发的请求 headers（会追加 Authorization）。
+        stream: 是否请求流式响应。
+
+    Returns:
+        httpx.Response 对象。
+
+    Raises:
+        httpx.HTTPError: HTTP 请求失败。
+    """
+    upstream_url = ctx.config.upstream_url.rstrip("/") + path
+    forward_headers: dict[str, str] = {
+        k: v for k, v in headers.items()
+        if k.lower() not in ("host", "content-length", "transfer-encoding")
+    }
+    if ctx.config.upstream_api_key:
+        forward_headers["authorization"] = f"Bearer {ctx.config.upstream_api_key}"
+    elif "authorization" not in {k.lower() for k in forward_headers}:
+        forward_headers["authorization"] = "Bearer nvidia"
+
+    try:
+        req = ctx.http_client.build_request(
+            method=method,
+            url=upstream_url,
+            headers=forward_headers,
+            content=body,
+            timeout=ctx.config.request_timeout,
+        )
+        response = await ctx.http_client.send(req, stream=stream)
+        return response
+    except httpx.TimeoutException:
+        logger.warning("upstream_timeout", path=path, timeout=ctx.config.request_timeout)
+        raise
+    except httpx.HTTPError as exc:
+        logger.error("upstream_error", path=path, error=str(exc))
+        raise
+
+
+# ---------------------------------------------------------------------------
+# worker 协程：消费优先级队列 + 令牌桶 + 转发
+# ---------------------------------------------------------------------------
+
+async def _worker_loop(ctx: SidecarContext) -> None:
+    """后台 worker：持续从优先级队列取请求 → 令牌限流 → 转发 → 设置 future 结果。
+
+    Args:
+        ctx: SidecarContext 运行时上下文。
+    """
+    log = logger.bind(worker="main")
+    log.info("worker_started")
+
+    while True:
+        try:
+            queue_item = await ctx.priority_queue.get(timeout=1.0)
+            if queue_item is None:
+                continue
+
+            request_id = queue_item.request_id
+            payload = queue_item.payload
+            headers = queue_item.headers
+            enqueued_at = queue_item.enqueued_at
+
+            # 查找对应的 pending future
+            pending_entry = ctx.pending_requests.get(request_id)
+            if pending_entry is None:
+                log.warning("orphan_request", request_id=request_id)
+                continue
+            future, _ = pending_entry
+
+            # 低优先级令牌等待超时处理
+            if queue_item.priority == Priority.LOW:
+                # 放线程池执行阻塞的令牌桶调用
+                got_token = await asyncio.to_thread(
+                    ctx.token_bucket.try_consume,
+                    tokens=1,
+                    timeout=ctx.config.low_priority_timeout,
+                )
+                if not got_token:
+                    log.info("low_priority_timeout", request_id=request_id)
+                    await ctx.increment_stat("ratelimited_requests")
+                    ctx.prometheus.record_request(queue_item.priority.name, "ratelimited")
+                    if not future.done():
+                        future.set_exception(
+                            _RateLimitedError(
+                                f"低优先级请求令牌等待超时 ({ctx.config.low_priority_timeout}s)"
+                            )
+                        )
+                    ctx.pending_requests.pop(request_id, None)
+                    continue
+            else:
+                # 非低优先级：在 worker 内轮询等待令牌，避免重入队导致 future 悬挂
+                got_token = await asyncio.to_thread(ctx.token_bucket.consume, tokens=1)
+                if not got_token:
+                    token_deadline = time.monotonic() + ctx.config.request_timeout
+                    while not got_token:
+                        await asyncio.sleep(0.1)
+                        got_token = await asyncio.to_thread(ctx.token_bucket.consume, tokens=1)
+                        if time.monotonic() > token_deadline:
+                            break
+                    if not got_token:
+                        log.warning(
+                            "token_wait_timeout",
+                            request_id=request_id,
+                            priority=queue_item.priority.name,
+                            timeout=ctx.config.request_timeout,
+                        )
+                        await ctx.increment_stat("ratelimited_requests")
+                        ctx.prometheus.record_request(queue_item.priority.name, "ratelimited")
+                        if not future.done():
+                            future.set_exception(
+                                _RateLimitedError(
+                                    f"令牌等待超时 ({ctx.config.request_timeout:.0f}s)"
+                                )
+                            )
+                        ctx.pending_requests.pop(request_id, None)
+                        continue
+
+            # 转发到上游
+            upstream_start = time.monotonic()
+            try:
+                path = headers.get("x-original-path", "/v1/chat/completions")
+                method = headers.get("x-original-method", "POST")
+                # 过滤内部 headers
+                clean_headers = {
+                    k: v for k, v in headers.items()
+                    if not k.startswith("x-original-") and not k.startswith("x-request-id")
+                }
+
+                resp = await _forward_to_upstream(
+                    ctx=ctx,
+                    method=method,
+                    path=path,
+                    body=payload.get("_raw_body"),
+                    headers=clean_headers,
+                    stream=payload.get("stream", False),
+                )
+
+                upstream_latency = time.monotonic() - upstream_start
+                queue_latency = time.monotonic() - enqueued_at
+                total_latency = upstream_latency + queue_latency
+
+                is_429: bool = resp.status_code == 429
+                ctx.token_bucket.record_response(is_429)
+
+                # 避退状态评估 + 指标更新
+                ctx.token_bucket.evaluate_retreat()
+                retreat_state = ctx.token_bucket.get_retreat_state()
+                effective_rpm = ctx.token_bucket.get_effective_rate_rpm()
+                upstream_429_rate = ctx.token_bucket.get_429_rate()
+                ctx.prometheus.update_retreat_metrics(retreat_state, effective_rpm, upstream_429_rate)
+
+                # 模型级信息写入 JSON 日志 (BIZ-46 Phase3: provider label 收敛后保留)
+                model_id = _extract_model(payload) or "unknown"
+                log.info(
+                    "request_completed",
+                    request_id=request_id,
+                    status=resp.status_code,
+                    model_id=model_id,
+                    upstream_latency=round(upstream_latency, 3),
+                    queue_latency=round(queue_latency, 3),
+                    total_latency=round(total_latency, 3),
+                    retreat_state=retreat_state,
+                    effective_rpm=round(effective_rpm, 1),
+                )
+
+                # 记录 Prometheus 指标 — provider 收敛（BIZ-46 Phase3）
+                provider = "nvidia"
+                ctx.prometheus.record_upstream_latency(provider, upstream_latency)
+                if not resp.is_success:
+                    ctx.prometheus.record_upstream_error(resp.status_code, provider)
+                ctx.prometheus.record_request(queue_item.priority.name, "success" if resp.is_success else "error")
+                ctx.prometheus.record_queue_latency(queue_item.priority.name, queue_latency)
+
+                if not future.done():
+                    future.set_result(resp)
+
+            except (httpx.HTTPError, OSError) as exc:
+                log.error("upstream_request_failed", request_id=request_id, error=str(exc))
+                await ctx.increment_stat("upstream_errors")
+                ctx.prometheus.record_request(queue_item.priority.name, "error")
+                ctx.prometheus.set_health(False)
+                if not future.done():
+                    future.set_exception(exc)
+
+            ctx.pending_requests.pop(request_id, None)
+
+        except asyncio.CancelledError:
+            log.info("worker_cancelled")
+            break
+        except Exception:
+            log.exception("worker_unexpected_error")
+
+
+# ---------------------------------------------------------------------------
+# PASSTHROUGH 直通路径（队列满 + PASSTHROUGH 策略）
+# ---------------------------------------------------------------------------
+
+async def _passthrough_with_rate_limit(
+    ctx: SidecarContext,
+    request: Request,
+    path: str,
+    body_bytes: bytes,
+    raw_headers: dict[str, str],
+    priority: Priority,
+) -> Response:
+    """队列满时的 PASSSTHROUGH 直通路径：仍受令牌桶限流，但不排队。
+
+    Args:
+        ctx: SidecarContext 运行时上下文。
+        request: FastAPI Request。
+        path: 请求路径。
+        body_bytes: 原始请求体。
+        raw_headers: 请求 headers。
+        priority: 请求优先级。
+
+    Returns:
+        FastAPI Response。
+    """
+    await ctx.increment_stat("passthrough_requests")
+    ctx.prometheus.increment_fallback()
+
+    # 低优先级走令牌桶等待
+    if priority == Priority.LOW:
+        got_token = await asyncio.to_thread(
+            ctx.token_bucket.try_consume,
+            tokens=1,
+            timeout=ctx.config.low_priority_timeout,
+        )
+        if not got_token:
+            await ctx.increment_stat("ratelimited_requests")
+            ctx.prometheus.record_request(priority.name, "ratelimited")
+            return JSONResponse(
+                status_code=429,
+                content={
+                    "error": {
+                        "message": f"令牌不足（队列满 + passthrough），超时 {ctx.config.low_priority_timeout}s",
+                        "type": "RateLimitedError",
+                    }
+                },
+            )
+    else:
+        got_token = await asyncio.to_thread(ctx.token_bucket.consume, tokens=1)
+        if not got_token:
+            deadline = time.monotonic() + ctx.config.request_timeout
+            while not got_token:
+                await asyncio.sleep(0.1)
+                got_token = await asyncio.to_thread(ctx.token_bucket.consume, tokens=1)
+                if time.monotonic() > deadline:
+                    await ctx.increment_stat("ratelimited_requests")
+                    ctx.prometheus.record_request(priority.name, "ratelimited")
+                    return JSONResponse(
+                        status_code=429,
+                        content={
+                            "error": {
+                                "message": f"令牌不足（队列满 + passthrough），等待超时 {ctx.config.request_timeout:.0f}s",
+                                "type": "RateLimitedError",
+                            }
+                        },
+                    )
+
+    # 拿到令牌，直接转发
+    try:
+        clean_headers = {k: v for k, v in raw_headers.items()}
+        resp = await _forward_to_upstream(
+            ctx=ctx,
+            method=request.method,
+            path=path,
+            body=body_bytes if body_bytes else None,
+            headers=clean_headers,
+            stream=False,
+        )
+        retreat_state = ctx.token_bucket.get_retreat_state()
+        ctx.token_bucket.evaluate_retreat()
+        ctx.prometheus.update_retreat_metrics(
+            retreat_state,
+            ctx.token_bucket.get_effective_rate_rpm(),
+            ctx.token_bucket.get_429_rate(),
+        )
+        return _build_response(resp)
+    except Exception as exc:
+        status, msg = _map_exception(exc)
+        logger.error("passthrough_error", path=path, error=str(exc))
+        ctx.prometheus.set_health(False)
+        return JSONResponse(
+            status_code=status,
+            content={"error": {"message": msg, "type": type(exc).__name__}},
+        )
+
+
+# ---------------------------------------------------------------------------
+# 自定义异常
+# ---------------------------------------------------------------------------
+
+class _RateLimitedError(Exception):
+    """429 限流错误。"""
+    pass
+
+
+# ---------------------------------------------------------------------------
+# 异常处理矩阵 (§3.4)
+# ---------------------------------------------------------------------------
+
+_EXCEPTION_MATRIX: dict[type[Exception], tuple[int, str]] = {
+    _RateLimitedError: (429, "Too Many Requests — 令牌不足"),
+    QueueFullError: (503, "Service Unavailable — 队列已满"),
+    httpx.TimeoutException: (504, "Gateway Timeout — 上游超时"),
+    httpx.ConnectError: (502, "Bad Gateway — 上游连接失败"),
+    httpx.HTTPStatusError: (502, "Bad Gateway — 上游返回错误状态"),
+}
+
+
+def _map_exception(exc: Exception) -> tuple[int, str]:
+    """将异常映射为 HTTP 状态码 + 错误信息。"""
+    for exc_type, (status, msg) in _EXCEPTION_MATRIX.items():
+        if isinstance(exc, exc_type):
+            return status, msg
+    return 500, f"Internal Server Error — {type(exc).__name__}"
+
+
+# ---------------------------------------------------------------------------
+# FastAPI 应用 + lifespan
+# ---------------------------------------------------------------------------
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncGenerator[None, Any]:
+    """应用生命周期管理：初始化/清理全局资源。
+
+    BIZ-46 Phase3: 所有资源收敛到 SidecarContext，挂载于 app.state.sidecar。
+    """
+    # 启动
+    config: SidecarConfig = load_config()
+    logging.getLogger().setLevel(config.log_level.upper())
+
+    http_client: httpx.AsyncClient = httpx.AsyncClient(
+        timeout=httpx.Timeout(config.request_timeout),
+        limits=httpx.Limits(
+            max_connections=100,
+            max_keepalive_connections=20,
+        ),
+    )
+    priority_queue: PriorityRequestQueue = PriorityRequestQueue(max_size=config.queue_max_size)
+    token_bucket: AdaptiveTokenBucket = AdaptiveTokenBucket(
+        rate=config.rate_rpm / 60.0,
+        capacity=config.bucket_capacity,
+    )
+    prometheus: PrometheusMetrics = PrometheusMetrics()
+    health: HealthService = HealthService()
+
+    ctx: SidecarContext = SidecarContext(
+        config=config,
+        http_client=http_client,
+        token_bucket=token_bucket,
+        priority_queue=priority_queue,
+        prometheus=prometheus,
+        health=health,
+    )
+    ctx.stats["start_time"] = int(time.time())
+    app.state.sidecar = ctx  # 注入 FastAPI
+
+    # 启动 worker 协程
+    worker_task = asyncio.create_task(_worker_loop(ctx))
+
+    # 在独立端口 :9191 启动 Prometheus metrics 服务器
+    metrics_app = prometheus.build_asgi_app()
+    metrics_config = uvicorn.Config(
+        metrics_app,
+        host=config.listen_host,
+        port=config.metrics_port,
+        log_level="error",
+    )
+    metrics_server = uvicorn.Server(metrics_config)
+    _metrics_task = asyncio.create_task(metrics_server.serve())
+
+    # CORS 中间件（严维序评审 #8）
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=False,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # 挂载 webui 子路由
+    app.include_router(webui_router)
+
+    # upstream_api_key 启动检查（严维序评审 #5）
+    if not config.upstream_api_key:
+        logger.warning(
+            "upstream_api_key_empty",
+            message="SIDECAR_API_KEY 未设置，NVIDIA 请求将因 401 认证失败",
+        )
+
+    logger.info(
+        "sidecar_started",
+        host=config.listen_host,
+        port=config.listen_port,
+        metrics_port=config.metrics_port,
+        rate_rpm=config.rate_rpm,
+        queue_max=config.queue_max_size,
+        retreat_enabled=True,
+    )
+
+    yield  # app 运行中
+
+    # 关闭
+    worker_task.cancel()
+    try:
+        await worker_task
+    except asyncio.CancelledError:
+        pass
+
+    _metrics_task.cancel()
+    try:
+        await _metrics_task
+    except asyncio.CancelledError:
+        pass
+
+    await http_client.aclose()
+    logger.info("sidecar_stopped")
+
+
+def _mask_api_key(key: str) -> str:
+    """对 API Key 进行脱敏处理，仅保留前 4 位以供识别。"""
+    if not key:
+        return ""
+    if len(key) <= 4:
+        return key[:2] + "****"
+    return key[:4] + "****"
+
+
+app: FastAPI = FastAPI(
+    title="NVIDIA Sidecar Rate-Limiting Proxy",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+
+# ---------------------------------------------------------------------------
+# 核心代理处理器
+# ---------------------------------------------------------------------------
+
+async def _handle_proxy_request(ctx: SidecarContext, request: Request, path: str) -> Response:
+    """统一的代理请求处理入口。
+
+    执行完整链路：
+    1. 解析请求体 → 提取 model
+    2. 网关识别 → 非 NVIDIA 直通
+    3. NVIDIA → 排队 + 令牌限流 + 转发
+    """
+    await ctx.increment_stat("total_requests")
+
+    # 解析请求
+    body_bytes: bytes = await request.body()
+    raw_headers: dict[str, str] = dict(request.headers)
+
+    # 尝试解析 JSON body
+    body_json: dict[str, Any] = {}
+    try:
+        if body_bytes:
+            body_json = __import__("json").loads(body_bytes)
+    except (ValueError, TypeError):
+        body_json = {}
+
+    # 提取 model 进行网关识别
+    model: str | None = _extract_model(body_json)
+    is_nvidia: bool = is_nvidia_gateway(model)
+
+    # 非 NVIDIA → 直接转发
+    if not is_nvidia:
+        await ctx.increment_stat("passthrough_requests")
+        try:
+            resp = await _forward_to_upstream(
+                ctx=ctx,
+                method=request.method,
+                path=path,
+                body=body_bytes if body_bytes else None,
+                headers=raw_headers,
+                stream=body_json.get("stream", False),
+            )
+            return _build_response(resp)
+        except Exception as exc:
+            status, msg = _map_exception(exc)
+            logger.error("passthrough_error", path=path, error=str(exc))
+            return JSONResponse(
+                status_code=status,
+                content={"error": {"message": msg, "type": type(exc).__name__}},
+            )
+
+    # NVIDIA → 排队 + 限流 + 转发
+    await ctx.increment_stat("nvidia_requests")
+    priority: Priority = _resolve_priority(raw_headers)
+
+    # 注入内部元数据到 payload
+    payload_for_queue: dict[str, Any] = dict(body_json)
+    payload_for_queue["_raw_body"] = body_bytes
+
+    # 尝试入队；PASSTHROUGH 策略下队列满时走直通路径
+    try:
+        request_id = await ctx.priority_queue.put(
+            item=payload_for_queue,
+            priority=priority,
+            headers={
+                **raw_headers,
+                "x-original-path": path,
+                "x-original-method": request.method,
+            },
+        )
+    except QueueFullError:
+        await ctx.increment_stat("queue_full_rejects")
+        return JSONResponse(
+            status_code=503,
+            content={
+                "error": {
+                    "message": "队列已满，当前策略: reject",
+                    "type": "QueueFullError",
+                }
+            },
+        )
+    except QueueFullPassthrough:
+        await ctx.increment_stat("passthrough_requests")
+        logger.info("queue_full_passthrough", path=path)
+        return await _passthrough_with_rate_limit(ctx, request, path, body_bytes, raw_headers, priority)
+
+    # 创建 future 并注册到 pending
+    loop = asyncio.get_running_loop()
+    future: asyncio.Future[httpx.Response] = loop.create_future()
+    ctx.pending_requests[request_id] = (future, time.monotonic())
+
+    try:
+        resp = await future
+        return _build_response(resp)
+    except _RateLimitedError as exc:
+        return JSONResponse(
+            status_code=429,
+            content={
+                "error": {
+                    "message": str(exc),
+                    "type": "RateLimitedError",
+                }
+            },
+        )
+    except Exception as exc:
+        status, msg = _map_exception(exc)
+        logger.error("proxy_error", path=path, request_id=request_id, error=str(exc))
+        return JSONResponse(
+            status_code=status,
+            content={"error": {"message": msg, "type": type(exc).__name__}},
+        )
+
+
+def _build_response(resp: httpx.Response) -> Response:
+    """将 httpx.Response 转换为 FastAPI Response。
+
+    支持 JSON 和流式 (SSE) 两种响应类型。
+    """
+    content_type = resp.headers.get("content-type", "")
+
+    # 流式响应 (SSE)
+    if "text/event-stream" in content_type or "stream" in content_type:
+        return StreamingResponse(
+            content=resp.aiter_bytes(),
+            status_code=resp.status_code,
+            headers={
+                k: v for k, v in resp.headers.items()
+                if k.lower() not in ("content-encoding", "transfer-encoding")
+            },
+            media_type="text/event-stream",
+        )
+
+    # 普通 JSON 响应
+    return Response(
+        content=resp.content,
+        status_code=resp.status_code,
+        headers={
+            k: v for k, v in resp.headers.items()
+            if k.lower() not in ("content-encoding", "transfer-encoding")
+        },
+        media_type=content_type or "application/json",
+    )
+
+
+# ---------------------------------------------------------------------------
+# 路由
+# ---------------------------------------------------------------------------
+
+@app.get("/health")
+async def health(ctx: SidecarContext = Depends(get_context)) -> dict[str, Any]:
+    """存活检查 (liveness)。"""
+    return ctx.health.liveness()
+
+
+@app.get("/health/ready")
+async def health_ready(ctx: SidecarContext = Depends(get_context)) -> dict[str, Any]:
+    """就绪检查 (readiness)，含上游连通性。
+
+    BIZ-46 Phase3: 复用 ctx.http_client，不再每次创建新 client。
+    """
+    queue_size = await ctx.priority_queue.get_queue_size()
+    bucket_status = ctx.token_bucket.get_status()
+    return await ctx.health.readiness(
+        upstream_url=ctx.config.upstream_url,
+        upstream_api_key=ctx.config.upstream_api_key or "",
+        queue_current_size=queue_size,
+        queue_max_size=ctx.config.queue_max_size,
+        available_tokens=bucket_status["tokens"],
+        bucket_capacity=bucket_status["capacity"],
+        http_client=ctx.http_client,  # 复用主 client
+    )
+
+
+@app.get("/status")
+async def status(ctx: SidecarContext = Depends(get_context)) -> dict[str, Any]:
+    """调试用：限流器 + 队列 + 避退完整状态。"""
+    queue_stats = await ctx.priority_queue.get_stats()
+    bucket_status = ctx.token_bucket.get_status()
+    return {
+        "requests": {
+            "total": ctx.stats["total_requests"],
+            "nvidia": ctx.stats["nvidia_requests"],
+            "passthrough": ctx.stats["passthrough_requests"],
+            "ratelimited": ctx.stats["ratelimited_requests"],
+        },
+        "errors": {
+            "queue_full_rejects": ctx.stats["queue_full_rejects"],
+            "upstream_errors": ctx.stats["upstream_errors"],
+        },
+        "queue": queue_stats,
+        "token_bucket": bucket_status,
+        "retreat": {
+            "state": ctx.token_bucket.get_retreat_state(),
+            "effective_rpm": round(ctx.token_bucket.get_effective_rate_rpm(), 1),
+            "base_rpm": round(ctx.token_bucket.get_base_rate_rpm(), 1),
+            "upstream_429_rate": round(ctx.token_bucket.get_429_rate(), 4),
+        },
+        "uptime_seconds": ctx.uptime_seconds,
+    }
+
+
+# ---- OpenAI 兼容端点 ----
+
+@app.post("/v1/chat/completions")
+async def chat_completions(request: Request, ctx: SidecarContext = Depends(get_context)) -> Response:
+    """OpenAI Chat Completions API 代理（含流式支持）。"""
+    return await _handle_proxy_request(ctx, request, "/v1/chat/completions")
+
+
+@app.post("/v1/completions")
+async def completions(request: Request, ctx: SidecarContext = Depends(get_context)) -> Response:
+    """OpenAI Completions API 代理（legacy）。"""
+    return await _handle_proxy_request(ctx, request, "/v1/completions")
+
+
+@app.post("/v1/embeddings")
+async def embeddings(request: Request, ctx: SidecarContext = Depends(get_context)) -> Response:
+    """OpenAI Embeddings API 代理。"""
+    return await _handle_proxy_request(ctx, request, "/v1/embeddings")
+
+
+@app.get("/v1/models")
+@app.get("/v1/models/{model_id:path}")
+async def list_models(request: Request, model_id: str | None = None, ctx: SidecarContext = Depends(get_context)) -> Response:
+    """OpenAI Models API 代理。"""
+    path = f"/v1/models/{model_id}" if model_id else "/v1/models"
+    return await _handle_proxy_request(ctx, request, path)
+
+
+# ---- 通用代理（catch-all 用于非标准 NVIDIA 端点） ----
+
+@app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"])
+async def catch_all(request: Request, path: str, ctx: SidecarContext = Depends(get_context)) -> Response:
+    """通用代理端点：转发任何未匹配的路径到上游。"""
+    target_path = f"/{path}" if not path.startswith("/") else path
+    return await _handle_proxy_request(ctx, request, target_path)
+
+
+# ---------------------------------------------------------------------------
+# 入口
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    """开发/调试入口。"""
+    import uvicorn
+    cfg: SidecarConfig = load_config()
+    uvicorn.run(
+        "nvidia_sidecar.server:app",
+        host=cfg.listen_host,
+        port=cfg.listen_port,
+        log_level=cfg.log_level.lower(),
+    )
+
+
+if __name__ == "__main__":
+    main()

services/nvidia_sidecar/static/dashboard.html

@@ -0,0 +1,327 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>NVIDIA Sidecar — 实时仪表盘</title>
+  <script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.7/dist/chart.umd.min.js"></script>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #0f172a; color: #e2e8f0; padding: 24px; }
+    h1 { font-size: 22px; font-weight: 600; margin-bottom: 4px; color: #f8fafc; }
+    .subtitle { color: #94a3b8; font-size: 13px; margin-bottom: 24px; }
+    .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(380px, 1fr)); gap: 20px; margin-bottom: 24px; }
+    .card { background: #1e293b; border-radius: 12px; padding: 20px; border: 1px solid #334155; }
+    .card h2 { font-size: 15px; font-weight: 600; color: #94a3b8; margin-bottom: 14px; text-transform: uppercase; letter-spacing: 0.05em; }
+    .card canvas { max-height: 220px; }
+    .stat-row { display: flex; gap: 16px; flex-wrap: wrap; }
+    .stat { flex: 1; min-width: 100px; background: #0f172a; border-radius: 8px; padding: 12px; text-align: center; border: 1px solid #334155; }
+    .stat .value { font-size: 28px; font-weight: 700; color: #38bdf8; }
+    .stat .label { font-size: 11px; color: #64748b; margin-top: 4px; text-transform: uppercase; }
+    .stat.warn .value { color: #f59e0b; }
+    .stat.danger .value { color: #ef4444; }
+    .retreat-badge { display: inline-block; padding: 2px 10px; border-radius: 999px; font-size: 12px; font-weight: 600; }
+    .retreat-badge.normal { background: #065f46; color: #6ee7b7; }
+    .retreat-badge.retreat { background: #78350f; color: #fbbf24; }
+    .retreat-badge.recover { background: #1e3a5f; color: #60a5fa; }
+    .config-panel { background: #1e293b; border-radius: 12px; padding: 20px; border: 1px solid #334155; }
+    .config-panel h2 { font-size: 15px; font-weight: 600; color: #94a3b8; margin-bottom: 14px; text-transform: uppercase; letter-spacing: 0.05em; }
+    .config-row { display: flex; align-items: center; gap: 12px; margin-bottom: 12px; flex-wrap: wrap; }
+    .config-row label { min-width: 100px; font-size: 13px; color: #cbd5e1; }
+    .config-row input, .config-row select { background: #0f172a; border: 1px solid #334155; border-radius: 6px; color: #e2e8f0; padding: 6px 10px; font-size: 13px; }
+    .config-row input[type="range"] { width: 140px; }
+    .config-row button { background: #38bdf8; color: #0f172a; border: none; border-radius: 6px; padding: 6px 16px; font-size: 13px; font-weight: 600; cursor: pointer; }
+    .config-row button:hover { background: #7dd3fc; }
+    .config-row button:disabled { background: #475569; cursor: not-allowed; }
+    .toast { position: fixed; top: 16px; right: 16px; padding: 10px 20px; border-radius: 8px; font-size: 13px; z-index: 999; animation: fadeInOut 3s; }
+    .toast.success { background: #065f46; color: #6ee7b7; }
+    .toast.error { background: #7f1d1d; color: #fca5a5; }
+    @keyframes fadeInOut { 0% { opacity: 0; transform: translateY(-8px); } 10% { opacity: 1; transform: translateY(0); } 80% { opacity: 1; } 100% { opacity: 0; } }
+    .disconnected { background: #7f1d1d; color: #fca5a5; padding: 4px 10px; border-radius: 4px; font-size: 12px; display: inline-block; margin-left: 8px; }
+    .connected { background: #065f46; color: #6ee7b7; padding: 4px 10px; border-radius: 4px; font-size: 12px; display: inline-block; margin-left: 8px; }
+
+    /* BIZ-46 Phase3: 队列柱状图 300ms 平滑动画 */
+    .queue-bar { transition: height 0.3s ease; }
+
+    /* BIZ-46 Phase3: SSE 断连 5s 半透明遮罩 */
+    #reconnect-mask {
+      display: none;
+      position: fixed;
+      top: 0; left: 0; right: 0; bottom: 0;
+      background: rgba(15, 23, 42, 0.85);
+      z-index: 1000;
+      justify-content: center;
+      align-items: center;
+      flex-direction: column;
+    }
+    #reconnect-mask.visible { display: flex; }
+    #reconnect-mask .mask-icon { font-size: 48px; margin-bottom: 16px; }
+    #reconnect-mask .mask-text { color: #94a3b8; font-size: 16px; font-weight: 500; }
+    #reconnect-mask .mask-sub { color: #64748b; font-size: 13px; margin-top: 8px; }
+  </style>
+</head>
+<body>
+  <!-- BIZ-46 Phase3: SSE 断连遮罩 -->
+  <div id="reconnect-mask">
+    <div class="mask-icon">⚠️</div>
+    <div class="mask-text">数据暂不可用</div>
+    <div class="mask-sub">SSE 连接中断，正在重连…</div>
+  </div>
+
+  <h1>🚀 NVIDIA Sidecar 实时仪表盘
+    <span id="conn-status" class="connected">已连接</span>
+  </h1>
+  <p class="subtitle">令牌桶限流 · 优先级队列 · 避退模式 · 实时监控</p>
+
+  <!-- 状态卡片 -->
+  <div class="stat-row" style="margin-bottom: 24px;">
+    <div class="stat"><div class="value" id="val-total">0</div><div class="label">总请求</div></div>
+    <div class="stat"><div class="value" id="val-nvidia">0</div><div class="label">NVIDIA 请求</div></div>
+    <div class="stat"><div class="value" id="val-rate">0</div><div class="label">当前 RPM</div></div>
+    <div class="stat"><div class="value" id="val-429">0%</div><div class="label">上游 429 率</div></div>
+    <div class="stat"><div class="value" id="val-retreat">正常</div><div class="label">避退状态</div></div>
+    <div class="stat"><div class="value" id="val-uptime">0s</div><div class="label">运行时间</div></div>
+  </div>
+
+  <!-- 图表 -->
+  <div class="grid">
+    <div class="card">
+      <h2>📊 令牌桶使用率</h2>
+      <canvas id="chart-tokens"></canvas>
+    </div>
+    <div class="card">
+      <!-- BIZ-46 Phase3: 队列图标题显示总排队数 -->
+      <h2>📈 队列深度 <span id="queue-total" style="font-size:13px;color:#38bdf8;">(共 0)</span></h2>
+      <canvas id="chart-queue"></canvas>
+    </div>
+    <div class="card">
+      <h2>📉 请求吞吐量 (最近 20 点)</h2>
+      <canvas id="chart-throughput"></canvas>
+    </div>
+    <div class="card">
+      <h2>⚙️ 速率历史</h2>
+      <canvas id="chart-rate"></canvas>
+    </div>
+  </div>
+
+  <!-- 配置面板 -->
+  <div class="config-panel">
+    <h2>🔧 实时配置</h2>
+    <div class="config-row">
+      <label>速率 (RPM)</label>
+      <input type="range" id="cfg-rate-rpm" min="1" max="100" value="40" oninput="document.getElementById('cfg-rate-val').textContent=this.value">
+      <span id="cfg-rate-val" style="min-width:30px;">40</span>
+    </div>
+    <div class="config-row">
+      <label>队列上限</label>
+      <input type="number" id="cfg-queue-max" value="500" min="1" max="2000" style="width:80px;">
+    </div>
+    <div class="config-row">
+      <button onclick="applyConfig()">应用配置</button>
+    </div>
+  </div>
+
+<script>
+// SSE 连接
+let evtSource = null;
+let dataHistory = { throughput: [], rates: [] };
+const MAX_HISTORY = 20;
+let lastSSETime = Date.now();
+
+// BIZ-46 Phase3: SSE 断连 5s 遮罩
+function checkReconnect() {
+  const mask = document.getElementById('reconnect-mask');
+  if (Date.now() - lastSSETime > 5000) {
+    mask.classList.add('visible');
+  }
+}
+setInterval(checkReconnect, 1000);
+
+function connectSSE() {
+  if (evtSource) evtSource.close();
+  evtSource = new EventSource('/api/dashboard/stream');
+  evtSource.onmessage = (e) => {
+    try {
+      const snap = JSON.parse(e.data);
+      lastSSETime = Date.now();
+      // 隐藏断连遮罩
+      document.getElementById('reconnect-mask').classList.remove('visible');
+      updateDashboard(snap);
+      document.getElementById('conn-status').className = 'connected';
+      document.getElementById('conn-status').textContent = '已连接';
+    } catch (err) {
+      document.getElementById('conn-status').className = 'disconnected';
+      document.getElementById('conn-status').textContent = '解析错误';
+    }
+  };
+  evtSource.onerror = () => {
+    document.getElementById('conn-status').className = 'disconnected';
+    document.getElementById('conn-status').textContent = '断开 - 重连中';
+  };
+}
+
+// 初始化 Chart.js
+const ctxTokens = document.getElementById('chart-tokens').getContext('2d');
+const chartTokens = new Chart(ctxTokens, {
+  type: 'doughnut',
+  data: {
+    labels: ['已用令牌', '可用令牌'],
+    datasets: [{ data: [0, 40], backgroundColor: ['#ef4444', '#22c55e'], borderWidth: 0 }]
+  },
+  options: { responsive: true, maintainAspectRatio: true, cutout: '65%', plugins: { legend: { position: 'bottom', labels: { color: '#94a3b8' } } },
+    // BIZ-46 Phase3: 300ms 平滑动画
+    animation: { duration: 300 } }
+});
+
+const ctxQueue = document.getElementById('chart-queue').getContext('2d');
+const chartQueue = new Chart(ctxQueue, {
+  type: 'bar',
+  data: {
+    labels: ['URGENT', 'HIGH', 'NORMAL', 'LOW'],
+    datasets: [{ label: '排队数', data: [0, 0, 0, 0], backgroundColor: ['#ef4444', '#f59e0b', '#38bdf8', '#a78bfa'] }]
+  },
+  options: { responsive: true, maintainAspectRatio: true,
+    scales: { y: { beginAtZero: true, ticks: { color: '#94a3b8' } }, x: { ticks: { color: '#94a3b8' } } },
+    plugins: { legend: { display: false } },
+    // BIZ-46 Phase3: 300ms 平滑动画
+    animation: { duration: 300 } }
+});
+
+const ctxThroughput = document.getElementById('chart-throughput').getContext('2d');
+const chartThroughput = new Chart(ctxThroughput, {
+  type: 'line',
+  data: { labels: [], datasets: [
+    { label: '成功', data: [], borderColor: '#22c55e', backgroundColor: '#22c55e20', fill: false, tension: 0.3, pointRadius: 2 },
+    { label: '429', data: [], borderColor: '#f59e0b', backgroundColor: '#f59e0b20', fill: false, tension: 0.3, pointRadius: 2 },
+    { label: '直通', data: [], borderColor: '#a78bfa', backgroundColor: '#a78bfa20', fill: false, tension: 0.3, pointRadius: 2 },
+  ]},
+  options: { responsive: true, maintainAspectRatio: true,
+    scales: { y: { beginAtZero: true, ticks: { color: '#94a3b8' } }, x: { ticks: { color: '#94a3b8' } } },
+    plugins: { legend: { position: 'bottom', labels: { color: '#94a3b8' } } },
+    animation: { duration: 300 } }
+});
+
+const ctxRate = document.getElementById('chart-rate').getContext('2d');
+const chartRate = new Chart(ctxRate, {
+  type: 'line',
+  data: { labels: [], datasets: [
+    { label: '有效 RPM', data: [], borderColor: '#38bdf8', fill: false, tension: 0.3, pointRadius: 2 },
+    { label: '基准 RPM', data: [], borderColor: '#64748b', fill: false, tension: 0.3, pointRadius: 2, borderDash: [4, 4] },
+  ]},
+  options: { responsive: true, maintainAspectRatio: true,
+    scales: { y: { beginAtZero: true, ticks: { color: '#94a3b8' } }, x: { ticks: { color: '#94a3b8' } } },
+    plugins: { legend: { position: 'bottom', labels: { color: '#94a3b8' } } },
+    animation: { duration: 300 } }
+});
+
+function updateDashboard(snap) {
+  const r = snap.requests || {};
+  const tb = snap.token_bucket || {};
+  const rt = snap.retreat || {};
+
+  document.getElementById('val-total').textContent = (r.total || 0).toLocaleString();
+  document.getElementById('val-nvidia').textContent = (r.nvidia || 0).toLocaleString();
+  document.getElementById('val-rate').textContent = Math.round(rt.effective_rpm || 40);
+  document.getElementById('val-429').textContent = ((rt.upstream_429_rate || 0) * 100).toFixed(1) + '%';
+  document.getElementById('val-uptime').textContent = fmtDuration(snap.uptime_seconds || 0);
+
+  const retreatEl = document.getElementById('val-retreat');
+  const state = rt.state || 'normal';
+  retreatEl.textContent = state === 'retreat' ? '⚠️ 避退' : state === 'recover' ? '↗ 恢复中' : '✅ 正常';
+  retreatEl.style.color = state === 'retreat' ? '#f59e0b' : state === 'recover' ? '#60a5fa' : '#22c55e';
+
+  chartTokens.data.datasets[0].data = [
+    Math.round((tb.capacity || 40) - (tb.tokens || 40)),
+    Math.round(tb.tokens || 0)
+  ];
+  chartTokens.update();
+
+  const qs = snap.queue || {};
+  const perPriority = qs.per_priority || {};
+  const totalQueued = perPriority.URGENT + perPriority.HIGH + perPriority.NORMAL + perPriority.LOW || qs.current_size || 0;
+  chartQueue.data.datasets[0].data = [
+    perPriority.URGENT || 0,
+    perPriority.HIGH || 0,
+    perPriority.NORMAL || 0,
+    perPriority.LOW || 0
+  ];
+  chartQueue.update();
+
+  // BIZ-46 Phase3: 队列图标题显示总排队数
+  document.getElementById('queue-total').textContent = '(共 ' + totalQueued + ')';
+
+  const now = new Date().toLocaleTimeString();
+  const prev = dataHistory.throughput.length > 0 ? dataHistory.throughput[dataHistory.throughput.length - 1].nvidia : 0;
+  const throughput = Math.max(0, (r.nvidia || 0) - prev);
+
+  dataHistory.throughput.push({ time: now, nvidia: throughput, ratelimited: r.ratelimited || 0, passthrough: r.passthrough || 0 });
+  dataHistory.rates.push({ time: now, effective: rt.effective_rpm || 40, base: rt.base_rpm || 40 });
+  if (dataHistory.throughput.length > MAX_HISTORY) dataHistory.throughput.shift();
+  if (dataHistory.rates.length > MAX_HISTORY) dataHistory.rates.shift();
+
+  chartThroughput.data.labels = dataHistory.throughput.map(d => d.time);
+  chartThroughput.data.datasets[0].data = dataHistory.throughput.map(d => d.nvidia);
+  chartThroughput.data.datasets[1].data = dataHistory.throughput.map(d => d.ratelimited);
+  chartThroughput.data.datasets[2].data = dataHistory.throughput.map(d => d.passthrough);
+  chartThroughput.update();
+
+  chartRate.data.labels = dataHistory.rates.map(d => d.time);
+  chartRate.data.datasets[0].data = dataHistory.rates.map(d => d.effective);
+  chartRate.data.datasets[1].data = dataHistory.rates.map(d => d.base);
+  chartRate.update();
+}
+
+function fmtDuration(s) {
+  if (s < 60) return s + 's';
+  if (s < 3600) return Math.floor(s/60) + 'm ' + (s%60) + 's';
+  return Math.floor(s/3600) + 'h ' + Math.floor((s%3600)/60) + 'm';
+}
+
+async function applyConfig() {
+  const btn = document.querySelector('.config-row button');
+  btn.disabled = true;
+  try {
+    const resp = await fetch('/api/admin/config', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        rate_rpm: parseInt(document.getElementById('cfg-rate-rpm').value),
+        queue_max_size: parseInt(document.getElementById('cfg-queue-max').value),
+      })
+    });
+    const result = await resp.json();
+    showToast(resp.ok ? 'success' : 'error', resp.ok ? '配置已更新' : (result.detail || '配置更新失败'));
+  } catch (err) {
+    showToast('error', '请求失败: ' + err.message);
+  }
+  btn.disabled = false;
+}
+
+function showToast(type, msg) {
+  const t = document.createElement('div');
+  t.className = 'toast ' + type;
+  t.textContent = msg;
+  document.body.appendChild(t);
+  setTimeout(() => t.remove(), 3000);
+}
+
+// BIZ-46 Phase3: 页面加载时同步当前配置值
+async function loadConfig() {
+  try {
+    const resp = await fetch('/api/admin/config');
+    if (resp.ok) {
+      const config = await resp.json();
+      document.getElementById('cfg-rate-rpm').value = config.rate_rpm || 40;
+      document.getElementById('cfg-rate-val').textContent = config.rate_rpm || 40;
+      document.getElementById('cfg-queue-max').value = config.queue_max_size || 500;
+    }
+  } catch (e) {
+    console.warn('配置加载失败（可能需要 Admin Token）', e);
+  }
+}
+
+loadConfig();
+connectSSE();
+</script>
+</body>
+</html>

services/nvidia_sidecar/tests/__init__.py

@@ -0,0 +1 @@
+# nvidia_sidecar tests

services/nvidia_sidecar/tests/test_retreat_concurrency.py

@@ -0,0 +1,207 @@
+"""
+避退模式并发/死锁回归测试 (BIZ-46 Phase3 6)
+
+覆盖多线程场景下的 AdaptiveTokenBucket 线程安全性：
+- 并发 record_response + evaluate_retreat
+- 并发 consume + record_response + evaluate_retreat
+- 高负载下避退状态转换正确性
+
+设计文档: docs/architecture/BIZ-46_Phase3_Architecture_Design.md 6
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+
+import pytest
+
+from nvidia_sidecar.rate_limiter import AdaptiveTokenBucket, RetreatState
+
+
+class TestRetreatConcurrency:
+    """避退模式并发安全回归测试。"""
+
+    @pytest.mark.asyncio
+    async def test_concurrent_record_and_evaluate(self) -> None:
+        """多线程同时 record_response + evaluate_retreat 不死锁。
+
+        4 个线程同时操作：
+        - 2 个线程执行 record_response (1000 次)
+        - 2 个线程执行 evaluate_retreat (1000 次)
+
+        所有线程必须在 10s 内完成，否则判定为死锁。
+        """
+        bucket = AdaptiveTokenBucket(rate=40 / 60, capacity=40)
+        errors: list[Exception] = []
+
+        def worker_record() -> None:
+            for i in range(1000):
+                try:
+                    bucket.record_response(is_429=(i % 10 == 0))
+                except Exception as e:
+                    errors.append(e)
+
+        def worker_evaluate() -> None:
+            for _ in range(1000):
+                try:
+                    bucket.evaluate_retreat()
+                except Exception as e:
+                    errors.append(e)
+
+        threads = [
+            threading.Thread(target=worker_record),
+            threading.Thread(target=worker_record),
+            threading.Thread(target=worker_evaluate),
+            threading.Thread(target=worker_evaluate),
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join(timeout=10)
+
+        alive_threads = [t for t in threads if t.is_alive()]
+        assert not alive_threads, (
+            f"{len(alive_threads)} 个线程未完成，疑似死锁"
+        )
+        assert not errors, f"并发错误: {errors}"
+
+    @pytest.mark.asyncio
+    async def test_concurrent_consume_and_retreat(self) -> None:
+        """多线程同时 consume + record_response + evaluate_retreat 不死锁。
+
+        覆盖 _lock (TokenBucket) 和 _retreat_lock (AdaptiveTokenBucket)
+        同时被不同线程持有时的交叉锁场景。
+        """
+        bucket = AdaptiveTokenBucket(rate=40 / 60, capacity=40)
+        errors: list[Exception] = []
+
+        def worker_consume() -> None:
+            for _ in range(500):
+                try:
+                    bucket.consume(tokens=1)
+                except Exception as e:
+                    errors.append(e)
+
+        def worker_retreat() -> None:
+            for _ in range(500):
+                try:
+                    bucket.record_response(is_429=False)
+                    bucket.evaluate_retreat()
+                except Exception as e:
+                    errors.append(e)
+
+        threads = [
+            threading.Thread(target=worker_consume),
+            threading.Thread(target=worker_consume),
+            threading.Thread(target=worker_retreat),
+            threading.Thread(target=worker_retreat),
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join(timeout=10)
+
+        alive_threads = [t for t in threads if t.is_alive()]
+        assert not alive_threads, (
+            f"{len(alive_threads)} 个线程未完成，疑似死锁"
+        )
+        assert not errors, f"并发错误: {errors}"
+
+    @pytest.mark.asyncio
+    async def test_retreat_state_transitions_under_load(self) -> None:
+        """高负载下避退状态转换正确。
+
+        1. 注入 100 个 429 → 验证进入 RETREAT
+        2. 注入 200 个成功 → 手动推进时间 → 验证恢复
+        """
+        bucket = AdaptiveTokenBucket(
+            rate=40 / 60,
+            capacity=40,
+            retreat_window_seconds=0.1,
+            retreat_429_threshold=0.05,
+            retreat_factor=0.75,
+            retreat_min_rpm=5.0,
+            recover_window_seconds=0.01,
+        )
+
+        # 阶段 1：模拟高 429 率
+        for _ in range(100):
+            bucket.record_response(is_429=True)
+
+        state = bucket.evaluate_retreat()
+        assert state == RetreatState.RETREAT, (
+            f"高 429 率应触发避退，实际: {state}"
+        )
+        assert bucket.get_effective_rate_rpm() < bucket.get_base_rate_rpm(), (
+            f"避退后速率应低于基准，实际: "
+            f"{bucket.get_effective_rate_rpm()} vs {bucket.get_base_rate_rpm()}"
+        )
+
+        # 阶段 2：模拟恢复
+        time.sleep(0.15)  # 等待 429 从短窗口中过期
+        for _ in range(200):
+            bucket.record_response(is_429=False)
+
+        for _ in range(10):
+            state = bucket.evaluate_retreat()
+
+        assert state in (RetreatState.RECOVER, RetreatState.NORMAL), (
+            f"恢复后应为 RECOVER 或 NORMAL，实际: {state}"
+        )
+
+    @pytest.mark.asyncio
+    async def test_try_consume_concurrency_safety(self) -> None:
+        """并发 try_consume 不死锁。"""
+        bucket = AdaptiveTokenBucket(rate=40 / 60, capacity=40)
+        errors: list[Exception] = []
+        results: list[bool] = []
+
+        def worker() -> None:
+            for _ in range(200):
+                try:
+                    got = bucket.try_consume(tokens=1, timeout=0.1)
+                    results.append(got)
+                except Exception as e:
+                    errors.append(e)
+
+        threads = [threading.Thread(target=worker) for _ in range(8)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join(timeout=10)
+
+        alive = [t for t in threads if t.is_alive()]
+        assert not alive, f"{len(alive)} 个线程未完成，疑似死锁"
+        assert not errors, f"并发错误: {errors}"
+        successful = sum(1 for r in results if r)
+        assert successful > 0, (
+            f"令牌桶应至少成功消费一些令牌，成功: {successful}/{len(results)}"
+        )
+
+    @pytest.mark.asyncio
+    async def test_high_load_state_coherence(self) -> None:
+        """高负载下令牌桶状态一致性：消费总量 ≤ 初始 token + 补充量。"""
+        bucket = AdaptiveTokenBucket(rate=10.0, capacity=100)
+        consumed_count: list[int] = [0]
+        lock = threading.Lock()
+
+        def worker() -> None:
+            local_consumed = 0
+            for _ in range(50):
+                if bucket.consume(tokens=1):
+                    local_consumed += 1
+                time.sleep(0.001)
+            with lock:
+                consumed_count[0] += local_consumed
+
+        threads = [threading.Thread(target=worker) for _ in range(10)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join(timeout=15)
+
+        max_expected = 100 + int(10.0 * 5)
+        assert consumed_count[0] <= max_expected, (
+            f"消费量异常: {consumed_count[0]}，应 ≤ {max_expected}"
+        )

services/nvidia_sidecar/webui.py

@@ -0,0 +1,325 @@
+"""
+NVIDIA Sidecar — WebUI 后端 API
+
+提供仪表盘 SSE 实时推送 + 配置热重载 API。
+
+BIZ-46 Phase3:
+- 架构解耦：移除反向导入 server，改用 Depends(get_context) (§1)
+- SSE 共享缓存：1s TTL snapshot cache，多客户端不重复构建 (§3)
+- Dashboard UX：页面加载同步配置 + 队列深度标题 (§7)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any, AsyncGenerator
+
+import structlog
+from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import HTMLResponse, JSONResponse, StreamingResponse
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from pydantic import BaseModel
+
+from nvidia_sidecar.context import SidecarContext
+
+webui_router: APIRouter = APIRouter(prefix="/api", tags=["webui"])
+logger: structlog.stdlib.BoundLogger = structlog.get_logger("nvidia_sidecar.webui")
+
+STATIC_DIR: Path = Path(__file__).parent / "static"
+
+# dashboard.html 缓存（严维序评审 #6 / 梁思筑评审 #8：避免每次请求读磁盘）
+_dashboard_html_cache: tuple[str, float] | None = None
+_DASHBOARD_CACHE_TTL: float = 300.0  # 5 分钟
+
+# Admin API 认证（严维序评审 #1）
+_ADMIN_TOKEN: str | None = os.environ.get("SIDECAR_ADMIN_TOKEN")
+_admin_auth_scheme: HTTPBearer = HTTPBearer(auto_error=False)
+
+
+def _get_ctx(request: Request) -> SidecarContext:
+    """获取 SidecarContext（webui 路由级注入，避免循环导入 server）。"""
+    return request.app.state.sidecar  # type: ignore[no-any-return]
+
+
+# ---------------------------------------------------------------------------
+# 配置热重载模型
+# ---------------------------------------------------------------------------
+
+class ConfigPatch(BaseModel):
+    """可在线修改的配置字段。"""
+    rate_rpm: int | None = None
+    queue_max_size: int | None = None
+    fallback_enabled_passthrough: bool | None = None
+
+
+# ---------------------------------------------------------------------------
+# SSE 快照构建（BIZ-46 Phase3: 1s TTL 共享缓存）
+# ---------------------------------------------------------------------------
+
+async def _build_snapshot(ctx: SidecarContext) -> dict[str, Any]:
+    """构建当前状态快照（从 SidecarContext 读取，含队列深度）。
+
+    BIZ-46 Phase3: 不再通过反向导入 server 访问全局变量。
+    """
+    try:
+        bucket_status = ctx.token_bucket.get_status()
+        now = time.time()
+
+        queue_data: dict[str, Any] = {"current_size": 0, "per_priority": {}}
+        try:
+            queue_stats = await ctx.priority_queue.get_stats()
+            queue_data = {
+                "max_size": queue_stats.get("max_size", 0),
+                "current_size": queue_stats.get("current_size", 0),
+                "per_priority": queue_stats.get("depth_by_priority", {}),
+                "total_enqueued": queue_stats.get("total_enqueued", 0),
+                "total_dequeued": queue_stats.get("total_dequeued", 0),
+                "total_dropped": queue_stats.get("total_dropped", 0),
+            }
+        except Exception:
+            logger.warning(
+                "queue_stats_unavailable",
+                message="队列统计获取失败，仪表盘队列深度可能不准确",
+            )
+
+        return {
+            "timestamp": now,
+            "uptime_seconds": ctx.uptime_seconds,
+            "token_bucket": bucket_status,
+            "queue": queue_data,
+            "retreat": {
+                "state": ctx.token_bucket.get_retreat_state(),
+                "effective_rpm": round(ctx.token_bucket.get_effective_rate_rpm(), 1),
+                "base_rpm": round(ctx.token_bucket.get_base_rate_rpm(), 1),
+                "upstream_429_rate": round(ctx.token_bucket.get_429_rate(), 4),
+            },
+            "requests": {
+                "total": ctx.stats.get("total_requests", 0),
+                "nvidia": ctx.stats.get("nvidia_requests", 0),
+                "passthrough": ctx.stats.get("passthrough_requests", 0),
+                "ratelimited": ctx.stats.get("ratelimited_requests", 0),
+            },
+            "errors": {
+                "queue_full_rejects": ctx.stats.get("queue_full_rejects", 0),
+                "upstream_errors": ctx.stats.get("upstream_errors", 0),
+            },
+        }
+    except Exception:
+        logger.exception("snapshot_build_error")
+        return {"error": "snapshot_unavailable", "timestamp": time.time()}
+
+
+async def _build_snapshot_cached(ctx: SidecarContext) -> dict[str, Any]:
+    """带 1s TTL 的共享快照缓存（BIZ-46 Phase3 §3）。
+
+    多个 SSE 客户端共享同一份快照，避免重复计算和锁竞争。
+
+    性能收益：
+    - 1 客户端: 1 次/s 计算（无变化）
+    - 5 客户端: ~5 次/s → 1 次/s
+    - 20 客户端: ~20 次/s → 1 次/s
+    """
+    now_cache = time.monotonic()
+    if ctx.snapshot_cache is not None:
+        data, ts = ctx.snapshot_cache
+        if now_cache - ts < ctx.SNAPSHOT_CACHE_TTL:
+            return data
+
+    async with ctx.snapshot_cache_lock:
+        # Double-check（避免多个协程同时 miss 后重复构建）
+        if ctx.snapshot_cache is not None:
+            data, ts = ctx.snapshot_cache
+            if now_cache - ts < ctx.SNAPSHOT_CACHE_TTL:
+                return data
+
+        snapshot = await _build_snapshot(ctx)
+        ctx.snapshot_cache = (snapshot, now_cache)
+        return snapshot
+
+
+# ---------------------------------------------------------------------------
+# 仪表盘 SSE 推送
+# ---------------------------------------------------------------------------
+
+async def _dashboard_stream(request: Request, ctx: SidecarContext) -> StreamingResponse:
+    """SSE 实时推送 Sidecar 完整状态快照（每秒一次）。
+
+    供 dashboard.html 的 EventSource 消费。
+
+    BIZ-46 Phase3: 使用共享缓存 _build_snapshot_cached，多客户端不重复计算。
+    """
+    async def event_generator() -> AsyncGenerator[str, None]:
+        first_frame = True
+        while True:
+            if await request.is_disconnected():
+                break
+            try:
+                snapshot: dict[str, Any] = await _build_snapshot_cached(ctx)
+                payload_sse = f"data: {json.dumps(snapshot, ensure_ascii=False)}\n\n"
+                if first_frame:
+                    payload_sse = f"retry: 3000\n{payload_sse}"
+                    first_frame = False
+                yield payload_sse
+            except Exception:
+                logger.exception("dashboard_sse_error")
+                yield f"data: {json.dumps({'error': 'internal'})}\n\n"
+            await asyncio.sleep(1.0)
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+# ---------------------------------------------------------------------------
+# 配置热重载
+# ---------------------------------------------------------------------------
+
+async def get_config(ctx: SidecarContext) -> dict[str, Any]:
+    """获取当前完整配置（从 SidecarContext 读取）。"""
+    config = ctx.config
+    effective_rpm = float(ctx.token_bucket.get_effective_rate_rpm())
+    return {
+        "listen_host": config.listen_host,
+        "listen_port": config.listen_port,
+        "metrics_port": config.metrics_port,
+        "upstream_url": config.upstream_url,
+        "upstream_api_key": _mask_api_key(config.upstream_api_key),
+        "rate_rpm": round(effective_rpm, 1),
+        "bucket_capacity": config.bucket_capacity,
+        "request_timeout": config.request_timeout,
+        "queue_max_size": config.queue_max_size,
+        "low_priority_timeout": config.low_priority_timeout,
+        "fallback_enabled_passthrough": config.fallback_enabled_passthrough,
+        "log_level": config.log_level,
+    }
+
+
+async def update_config(body: ConfigPatch, ctx: SidecarContext) -> JSONResponse:
+    """在线修改配置项并即时生效。"""
+    config = ctx.config
+    changed: list[str] = []
+
+    if body.rate_rpm is not None:
+        if body.rate_rpm <= 0:
+            raise HTTPException(status_code=400, detail="rate_rpm must be > 0")
+        config.rate_rpm = body.rate_rpm
+        ctx.token_bucket.set_rate(body.rate_rpm / 60.0)
+        changed.append("rate_rpm")
+
+    if body.queue_max_size is not None:
+        if body.queue_max_size <= 0:
+            raise HTTPException(status_code=400, detail="queue_max_size must be > 0")
+        ok, msg = ctx.priority_queue.set_max_size(body.queue_max_size)
+        if not ok:
+            raise HTTPException(status_code=400, detail=msg)
+        config.queue_max_size = body.queue_max_size
+        changed.append("queue_max_size")
+        logger.info("queue_max_size_updated", detail=msg)
+
+    if body.fallback_enabled_passthrough is not None:
+        config.fallback_enabled_passthrough = body.fallback_enabled_passthrough
+        changed.append("fallback_enabled_passthrough")
+
+    logger.info("config_updated", changed=changed)
+    return JSONResponse(
+        content={"status": "ok", "changed": changed},
+    )
+
+
+def _mask_api_key(key: str) -> str:
+    """对 API Key 进行脱敏处理，仅保留前 4 位以供识别。
+
+    严维序评审 #2 / 沈路明评审 #3：防止 API Key 明文泄露。
+    """
+    if not key:
+        return ""
+    if len(key) <= 4:
+        return key[:2] + "****"
+    return key[:4] + "****"
+
+
+# ---------------------------------------------------------------------------
+# 路由注册
+# ---------------------------------------------------------------------------
+
+@webui_router.get("/dashboard/stream")
+async def dashboard_stream(
+    request: Request,
+    ctx: SidecarContext = Depends(_get_ctx),
+) -> StreamingResponse:
+    """SSE 仪表盘实时推送端点（BIZ-46 Phase3: 使用共享缓存）。"""
+    return await _dashboard_stream(request, ctx)
+
+
+async def _verify_admin_auth(
+    credentials: HTTPAuthorizationCredentials | None = Depends(_admin_auth_scheme),
+) -> None:
+    """Admin API Bearer Token 认证（严维序评审 #1）。
+
+    若设置了 SIDECAR_ADMIN_TOKEN 环境变量，则要求请求携带匹配的 Bearer Token。
+    未设置时跳过认证（开发/测试环境）。
+    """
+    if _ADMIN_TOKEN is None:
+        return  # 未配置认证 token，允许无认证访问
+    if credentials is None:
+        raise HTTPException(status_code=401, detail="需要 Bearer Token 认证（Admin API）")
+    if credentials.credentials != _ADMIN_TOKEN:
+        raise HTTPException(status_code=403, detail="Admin Token 无效")
+
+
+@webui_router.get("/admin/config")
+async def admin_get_config(
+    _auth: None = Depends(_verify_admin_auth),
+    ctx: SidecarContext = Depends(_get_ctx),
+) -> JSONResponse:
+    """获取当前配置（需要 Admin 认证）。"""
+    return JSONResponse(content=await get_config(ctx))
+
+
+@webui_router.post("/admin/config")
+async def admin_update_config(
+    body: ConfigPatch,
+    _auth: None = Depends(_verify_admin_auth),
+    ctx: SidecarContext = Depends(_get_ctx),
+) -> JSONResponse:
+    """在线修改配置（热重载，需要 Admin 认证）。"""
+    return await update_config(body, ctx)
+
+
+# ---------------------------------------------------------------------------
+# 仪表盘静态页面
+# ---------------------------------------------------------------------------
+
+def _get_dashboard_html() -> str:
+    """获取仪表盘 HTML（带缓存，严维序评审 #6 / 梁思筑评审 #8）。
+
+    首次加载后缓存 5 分钟，避免每次请求读磁盘。
+    """
+    global _dashboard_html_cache
+    now = time.monotonic()
+    if _dashboard_html_cache is not None:
+        cached_content, cached_at = _dashboard_html_cache
+        if now - cached_at < _DASHBOARD_CACHE_TTL:
+            return cached_content
+
+    dashboard_path = STATIC_DIR / "dashboard.html"
+    if dashboard_path.is_file():
+        content = dashboard_path.read_text(encoding="utf-8")
+        _dashboard_html_cache = (content, now)
+        return content
+    return "<h1>dashboard.html not found</h1>"
+
+
+@webui_router.get("/dashboard", include_in_schema=False)
+async def dashboard_page() -> HTMLResponse:
+    """仪表盘 HTML 页面（含缓存策略）。"""
+    return HTMLResponse(content=_get_dashboard_html())

specs/BIZ-84_知识缺口上报 SOP_v1.0.md

@@ -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 模板章节（见第六节）

specs/SOP-016_执行前检索强制规则.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 胡蓉起草，经刘炜承批准后生效。*

specs/SOP-017_知识缺口上报SOP.md

@@ -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 胡蓉起草，经刘炜承批准后生效。*

specs/lottery/开发文档-双色球WebUI-v1.0.md

@@ -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）