main
mula.liu 2026-11-05 16:53:24 +08:00
parent 9d62b88b05
commit 9614b2d225
35 changed files with 1982 additions and 605 deletions

View File

@ -75,8 +75,9 @@ COMFYUI_RPM=6
# VIDEO_MODEL=minimax-h3
# ---------- 配音 TTS ----------
# macOS 本机真实人声可设为 macos-say;声线在项目的「资产库 → 声线」中配置
# (Tingting / Meijia / Sinji / Fred,params.effect=alien 可生成外星语效果)。
# 真实配音用 comfyui_tts(IndexTTS2,部署机 ComfyUI 提供,Linux 可用);
# 声线在「资产库 → 声线」配置:绑真人参考音频走 zero-shot 克隆,
# 只填「音色描述」则由描述词直出。
TTS_PROVIDER=mock
TTS_API_BASE_URL=
TTS_API_KEY=

View File

@ -135,7 +135,7 @@ DEV-only,拿 `NEX_UI_BASE=:4173` 量构建产物时它恒为 0,别把那份
| `scripts/dev.sh` | 开发态前后端两个进程(后端 8000 + Vite 5173),缺 `.env` / `.venv` / `node_modules` 自己补 | 开发机 |
| `scripts/server.sh` | 服务形态全生命周期:`install` `build` `start` `stop` `restart` `status` `verify` `logs` `systemd` | 服务器 |
| `scripts/deploy.sh` | 打部署包(白名单 + 体检),或直接 rsync 上服务器并自动安装、重启 | 开发机 |
| `scripts/seed.py` | 迁移「模型配置 + 加密主密钥 + 管理员」:`export` 导出、`install` 幂等落地 | 两端 |
| `scripts/seed.py` | 迁移「模型配置 + 加密主密钥 + 管理员」:`doctor` 体检数据集与代码是否对得上、`export --fix` 校准并导出、`install` 装前自动体检再幂等落地、`boundary` 数据边界一览 | 两端 |
| `scripts/e2e_selfcheck.py` | 图2 全 12 节点端到端自检(真实 HTTP + ffprobe 实测产物) | 两端 |
| `scripts/evidence_prune.py` | 清理 `reports/` 下过期的验收证据目录 | 开发机 |
@ -328,15 +328,17 @@ React Router 的 history 回退已经处理好(地址栏直接刷 `/projects/3
`SERVE_FRONTEND` 默认 `off`,所以开发与测试行为完全不变。
```bash
# ---- 开发机:打包(内容白名单 + 体检,体检不过直接报错不产出包)----
./scripts/deploy.sh --check # 只看会带上什么、排掉什么
# ---- 开发机:数据集 → 打包(内容白名单 + 体检,体检不过直接报错不产出包)----
.venv/bin/python scripts/seed.py doctor # 量一遍「开发库数据集 vs 当前代码」,只读
.venv/bin/python scripts/seed.py export --fix # 补齐能力位/工作流键 → 体检 → 导出 scripts/seed/
./scripts/deploy.sh --check # 只看会带上什么、排掉什么、数据能不能装
./scripts/deploy.sh # → .local/deploy/nex_animation-<时间戳>.tar.gz
./scripts/deploy.sh --host deploy@10.0.0.8 \
--path /opt/nex_animation # 上传 + 远端 install + restart + status
# ---- 服务器:落地 ----
tar -xzf nex_animation-*.tar.gz && cd nex_animation
./scripts/server.sh install # venv + 依赖 + npm build + 听写模型 + 建表灌种子数据
./scripts/server.sh install # venv + 依赖 + npm build + 听写模型 + 体检 + 建表灌种子数据
./scripts/server.sh start # 单进程 uvicorn,默认 :8000
./scripts/server.sh verify # 图2 全 12 节点真实 HTTP + ffprobe 自检
./scripts/server.sh status # 端口 / 健康 / 默认模型 / ComfyUI 连通性 / 数据边界
@ -356,12 +358,20 @@ sudo ./scripts/server.sh systemd > /etc/systemd/system/nex-animation.service \
| 表结构:应用首启 `app/db.py:init_db()` 自己 `create_all` + 补列 | `media/` 产物库——换环境是「迁移」不是「部署」,单独 rsync |
| 模型配置 `model_specs` + 加密主密钥 `model_secret_keys`(`scripts/seed/`) | 项目 / 分镜 / 任务等业务数据(开发库全是过程产物) |
| 管理员账号 `users`(仅 `admin`,沿用导出的口令哈希) | `.env`——ComfyUI 地址、数据库串都是机器相关的 |
| 启动脚本与 `DEPLOY-INFO.txt`(包里有什么、服务器三步) | `backend/tests`、`reports/`、`docs/`、`models/`、`frontend/dist`(远端 build;`--with-dist` 可带上) |
| 启动脚本与 `DEPLOY-INFO.txt`(包里有什么、服务器三步、默认位是哪几个) | `backend/tests`、`reports/`、`.git/`、`models/`(听写权重远端下载)、`frontend/dist`(远端 build;`--with-dist` 可带上) |
主密钥跟包走是有意的:`model_specs.api_key` 是密文,换机器解不开就等于每台服务器都要重录一遍
各家 Key。代价是 `scripts/seed/` 属于**机密**——已 gitignore、随包走、包内是密文但主密钥也在里面,
按密钥对待。装完 `seed.py install` 会自检解密并打印当前默认模型;`--only-missing` 只补缺不覆盖
已有配置,`--dry-run` 先看将要发生什么,主密钥冲突时区分「没有解密依赖 → 换」与「有依赖 → 中止等你决策」。
按密钥对待。装完 `seed.py install` 会自检解密并打印当前默认模型;`install --only-missing`
(`seed.py` 与 `server.sh` 都收这个开关)只补缺、不覆盖同名配置,`--dry-run` 先看将要发生什么,
主密钥冲突时区分「没有解密依赖 → 换」与「有依赖 → 中止等你决策」。
**数据集与代码必须对得上**:`deploy.sh --check`、`deploy.sh` 打包、`seed.py install` 装库之前,
跑的都是同一个 `doctor`(列对得上表结构 / 适配器在代码里注册过 / `modes` 不比适配器声明的能力少 /
每类能力有且仅有一个默认 / 包里的密文能被包里的主密钥解开)。任何一条 error 就停住,
因为数据集旧的后果不是报错而是**功能在页面上凭空消失**——比如 `modes` 少一个
`voice_instruct`,「音色描述直出」整块就不渲染,而 ComfyUI 侧看起来一切正常。
修复动作永远在开发机:`seed.py doctor --fix`(只补缺,不动人工调过的值)→ 重新 `export --fix` → 重新打包。
> 服务器上没有 `whisper-cli` / 听写模型时,只有「台词听写质检」这一项不生效,其余流程照常;
> `server.sh status` 会把它标成黄色告警而不是静默降级。`--no-asr` 可以跳过下载(465M 权重)。

View File

@ -337,7 +337,8 @@ def voice_reference_status(project_id: int, voice_id: int, db: Session = Depends
deps.get_project(db, project_id)
voice = deps.get_voice(db, project_id, voice_id)
spec, _adapter = model_registry.resolve_voice(db, None, None)
return {"ok": True, "result": timbre.reference_status(db, voice, clone=timbre.clone_model(spec))}
return {"ok": True, "result": timbre.reference_status(
db, voice, clone=timbre.clone_model(spec), instruct=timbre.instruct_model(spec))}
@router.delete("/api/projects/{project_id}/voices/{voice_id}")

View File

@ -966,7 +966,7 @@ def platform_reference_status(owner_type: str, asset_id: int, db: Session = Depe
owner = _owner(db, owner_type, asset_id)
spec, _adapter = model_registry.resolve_voice(db, None, None)
return {"ok": True, "result": timbre.reference_status(
db, owner, clone=timbre.clone_model(spec))}
db, owner, clone=timbre.clone_model(spec), instruct=timbre.instruct_model(spec))}
@router.post("/api/platform/{owner_type}/{asset_id}/generate")
@ -995,7 +995,7 @@ def generate_platform_asset(owner_type: str, asset_id: int, data: schemas.Platfo
reference = timbre.resolve_reference(
db, owner,
explicit=str(storage.to_absolute(reference_media.path)) if reference_media else "",
clone=timbre.clone_model(spec))
clone=timbre.clone_model(spec), instruct=timbre.instruct_model(spec))
if not reference["path"] and reference.get("source") == "none":
raise HTTPException(409, reference["note"])
# 交给模型的是绝对路径(供应商要直接读文件);声线列里存 media_root 相对路径,
@ -1005,6 +1005,8 @@ def generate_platform_asset(owner_type: str, asset_id: int, data: schemas.Platfo
text=text, voice_id=owner.name, provider_voice_id=reference_path,
language=owner.language, speed=float((owner.tuning or {}).get("speed", 1.0)),
seed=data.seed, params=(owner.tuning or {}).get("params") or {},
# 没有参考音频时靠它出音,有参考音频时用它微调音色(见 comfy_assets.graph)
instruct_text=timbre.instruct_text_of(owner) if timbre.instruct_model(spec) else "",
idempotency_key=f"platform-voice:{owner.id}:{asset_id}",
label=f"PLATFORM-VOICE-{owner.id}", output_path=out,
)

View File

@ -33,7 +33,9 @@ MODEL_ADAPTERS = {
"llm": ["mock_llm", "http_llm"],
"video": ["mock", "http", "comfyui"],
"image": ["mock_image", "http_image", "comfyui_image"],
"tts": ["mock", "http", "macos_say", "comfyui_tts"],
# 没有 macos_say:部署服务器是 Linux,没有系统 say 命令,
# 开发机上能用的本地嗓门不是产品能力。
"tts": ["mock", "http", "comfyui_tts"],
}

View File

@ -578,8 +578,10 @@ def _generate_voice_sample(db: Session, task: Task, project: Project, payload: d
# 参考音频决定音色,「性别」对 zero-shot 克隆模型只是元数据:
# 缺参考时必须换成同性别参考或明确报错,不能让男声悄悄用上模型默认的女声底模。
clone = timbre.clone_model(spec)
instruct = timbre.instruct_model(spec)
reference = timbre.resolve_reference(
db, owner, explicit=reference_paths[0] if reference_paths else "", clone=clone)
db, owner, explicit=reference_paths[0] if reference_paths else "",
clone=clone, instruct=instruct)
if not reference["path"] and reference.get("source") == "none":
raise ProviderError(reference["note"], code="missing_reference_audio", retryable=False)
request = VoiceGenRequest(
@ -588,7 +590,9 @@ def _generate_voice_sample(db: Session, task: Task, project: Project, payload: d
language=owner.language, speed=float(tuning.get("speed", 1.0)),
pitch=float(tuning.get("pitch", 1.0)), volume=float(tuning.get("volume", 1.0)),
sample_rate=int(tuning.get("sample_rate", 24000)), seed=payload.get("seed"),
params=tuning.get("params") or {}, idempotency_key=f"asset-voice:{owner.id}",
params=tuning.get("params") or {},
instruct_text=timbre.instruct_text_of(owner) if instruct else "",
idempotency_key=f"asset-voice:{owner.id}",
label=f"VOICE-{owner.id}", output_path=out,
)
dispatch.heartbeat(db, task, progress=0.3, note=f"调用 {spec.provider}/{spec.model} 生成试听")

View File

@ -120,6 +120,9 @@ class VoiceGenRequest:
idempotency_key: str = ""
label: str = ""
output_path: Path | None = None
#: 音色/情绪描述(声线的「音色描述」)。支持 voice_instruct 的模型在
#: **没有参考音频**时靠它出音;有参考音频时用它做音色偏移与情绪控制。
instruct_text: str = ""
@dataclass

View File

@ -403,9 +403,11 @@ class ComfyTTSProvider(VoiceProviderAdapter):
return self._name
def capabilities(self, config: dict | None = None) -> Capabilities:
return Capabilities(modes=("voice", "voice_clone"), resolutions=(), aspect_ratios=(),
return Capabilities(modes=("voice", "voice_clone", "voice_instruct"),
resolutions=(), aspect_ratios=(),
min_duration=0, max_duration=0, max_reference_images=1,
notes="IndexTTS2 本地推理;使用参考音频做 zero-shot 音色克隆")
notes="IndexTTS2 本地推理:有声线参考音频时做 zero-shot 音色克隆;"
"没有参考音频时用「音色描述」直接生成")
_probe = _ProbeCache()
@ -442,8 +444,18 @@ class ComfyTTSProvider(VoiceProviderAdapter):
except FatalProviderError:
cls._probe.invalidate()
#: easy indexTTSGenerate(全参节点)的必填项。描述词模式必须走这个节点——
#: ``easy indexTTSGenerateSimple`` 不接 emotions 输入,描述词写进去也是聋子。
#: 数值取 ComfyUI-Index-TTS 节点自身的默认值,模型配置 generate_full_inputs 可逐项覆盖。
FULL_DEFAULTS: dict[str, Any] = {
"do_sample": True, "temperature": 0.8, "top_p": 0.9, "top_k": 30,
"num_beams": 3, "repetition_penalty": 10.0, "length_penalty": 0.0,
"max_mel_tokens": 1815, "max_tokens_per_sentence": 120, "speech_speed": 1.0,
}
@staticmethod
def graph(request: VoiceGenRequest, config: dict, seed: int, reference: str) -> dict[str, Any]:
def graph(request: VoiceGenRequest, config: dict, seed: int, reference: str,
instruct: str = "") -> dict[str, Any]:
loader = str(config.get("load_node") or "easy downloadIndexTTSAndLoadModel")
generate = str(config.get("generate_node") or "easy indexTTSGenerateSimple")
model_name = str(config.get("model") or "IndexTTS-2")
@ -460,7 +472,7 @@ class ComfyTTSProvider(VoiceProviderAdapter):
"seed": seed,
}
generate_inputs.update(config.get("generate_inputs") or {})
return {
graph: dict[str, Any] = {
"1": {"class_type": loader, "inputs": load_inputs},
"2": {"class_type": "LoadAudio", "inputs": {"audio": reference}},
"3": {"class_type": generate, "inputs": generate_inputs},
@ -468,6 +480,23 @@ class ComfyTTSProvider(VoiceProviderAdapter):
"audio": ["3", 0],
"filename_prefix": str(config.get("filename_prefix") or "audio/nex")}},
}
if instruct:
full: dict[str, Any] = dict(ComfyTTSProvider.FULL_DEFAULTS)
full.update(config.get("generate_full_inputs") or {})
full.update({"indextts_model": ["1", 0], "text": request.text,
"unload_model": False, "seed": seed})
# 有声线参考时克隆照旧:描述词只做音色偏移与情绪,不该把克隆来的嗓子丢掉。
if reference:
full["reference_audio"] = ["2", 0]
graph["3"] = {"class_type": str(config.get("generate_full_node") or "easy indexTTSGenerate"),
"inputs": full}
graph["5"] = {"class_type": str(config.get("instruct_node") or "easy indexTTSEmotionText"),
"inputs": {"reference_audio": ["2", 0],
"voice_name": str(request.label or request.voice_id or "s1"),
"description": instruct,
"use_random": bool(config.get("instruct_random"))}}
graph["3"]["inputs"]["emotions"] = ["5", 0]
return graph
def synthesize(self, request: VoiceGenRequest, config: dict | None = None) -> VoiceGenResult:
cfg = dict(config or {})
@ -489,9 +518,19 @@ class ComfyTTSProvider(VoiceProviderAdapter):
# reference_source 会进配音记录:排查「全片都是同一个陌生人音色」时,
# 必须能一眼看出这条配音用的是角色自己的参考音频还是模型默认参考。
reference_source = "voice_asset" if candidate else "model_default"
# 描述词直出:声线没有参考音频也能出音。emotion 节点的 reference_audio 是必填,
# 所以锚点仍取模型默认参考——音色由描述词决定(9200 实测:同一句台词,
# 「年幼小女孩」中位基频 241Hz、「低沉老年男性」189Hz,描述词真的在改音色)。
instruct = str(request.instruct_text or (request.params or {}).get("instruct") or "").strip()
if not reference and instruct:
reference = configured_reference
reference_source = "instruct_anchor"
mode = "voice_clone" if candidate else ("voice_instruct" if instruct else "voice_default")
if not reference:
raise FatalProviderError("IndexTTS2 需要参考音频:请给声线填写 provider_voice_id"
" 或给模型配置 reference_audio", code="missing_reference_audio")
raise FatalProviderError(
"IndexTTS2 既没有参考音频也没有音色描述:"
"请给声线上传参考音频(克隆),或填写「音色描述」(描述词直出)",
code="missing_reference_audio")
seed = request.seed if request.seed is not None else int(
hashlib.sha256((request.idempotency_key or request.text).encode()).hexdigest()[:12], 16
)
@ -503,12 +542,17 @@ class ComfyTTSProvider(VoiceProviderAdapter):
nodes = client.get(f"{base}/object_info", timeout=60)
raise_for(nodes, context="读取 ComfyUI 节点清单")
available_nodes = set((nodes.json() or {}).keys())
required = {str(cfg.get("load_node") or "easy downloadIndexTTSAndLoadModel"),
str(cfg.get("generate_node") or "easy indexTTSGenerateSimple")}
required = {str(cfg.get("load_node") or "easy downloadIndexTTSAndLoadModel")}
if instruct:
required |= {str(cfg.get("generate_full_node") or "easy indexTTSGenerate"),
str(cfg.get("instruct_node") or "easy indexTTSEmotionText")}
else:
required.add(str(cfg.get("generate_node") or "easy indexTTSGenerateSimple"))
missing = sorted(required - available_nodes)
if missing:
raise FatalProviderError(
"ComfyUI 缺少 IndexTTS2 节点:" + "、".join(missing)
+ ("(描述词模式还需要全参生成节点与音色描述节点)" if instruct else "")
+ "。请在 9200 实例安装并启用对应的 IndexTTS 自定义节点后重试",
code="missing_comfy_node",
)
@ -524,7 +568,7 @@ class ComfyTTSProvider(VoiceProviderAdapter):
# 覆盖模型默认参考音频,否则每次生成都会在 LoadAudio 校验阶段失败。
reference = configured_reference
reference_source = "model_default"
graph = self.graph(request, cfg, int(seed), reference)
graph = self.graph(request, cfg, int(seed), reference, instruct)
prompt_id = submit_graph(client, base, graph,
stable_client_id(request.idempotency_key or request.label or request.text),
idempotency_key=request.idempotency_key)
@ -554,12 +598,16 @@ class ComfyTTSProvider(VoiceProviderAdapter):
metadata={"provider": "comfyui_tts", "base_url": base, "seed": seed,
"reference_audio": reference,
"reference_source": reference_source,
"mode": mode, "instruct_text": instruct,
"tuning": tuning,
"comfy_output": f"{item.get('subfolder', '')}/{item['filename']}".strip("/")})
def diagnose(self, config: dict | None = None) -> dict:
return _diagnose(config or {}, required_nodes=(
"easy downloadIndexTTSAndLoadModel", "easy indexTTSGenerateSimple",
# 描述词直出的两个节点一起查:缺了它们「填了音色描述却只会克隆」
# 要等到第一次生成才暴露,太晚了。
"easy indexTTSGenerate", "easy indexTTSEmotionText",
"LoadAudio", "SaveAudio",
))

View File

@ -1,119 +0,0 @@
"""macOS 系统语音适配器:把真实 TTS 能力接入统一配音流水线。
``say`` 是 macOS 自带命令,适合本地开发与离线成片。适配器统一输出单声道
PCM WAV,并可对音色追加滤镜,例如铁血战士的外星语效果。
"""
from __future__ import annotations
import shutil
import subprocess
import tempfile
from pathlib import Path
from app.config import settings
from app.providers.base import (FatalProviderError, VoiceGenRequest, VoiceGenResult,
VoiceProviderAdapter)
from app.services import ffmpeg as ff
# 低频化 + 金属共振 + 颗粒噪声;保持原始语速的同时明显降低音高。
ALIEN_AUDIO_FILTER = (
"asetrate=22050*0.62,aresample=22050,atempo=1.6129,"
"flanger=delay=4:depth=3:regen=25:width=60:speed=0.4,"
"aecho=0.8:0.7:40|90:0.35|0.2,"
"acrusher=bits=8:mode=log:aa=1,lowpass=f=4800,tremolo=f=7:d=0.25"
)
class MacOSSayVoiceProvider(VoiceProviderAdapter):
"""使用 macOS ``say`` 合成可听的真实语音。
声线通过 ``provider_voice_id`` 指定,例如 ``Tingting``、``Meijia``、
``Sinji`` 或 ``Fred``。``request.params.effect = "alien"`` 会启用外星语
滤镜链。模型配置中的 ``voice`` 和 ``effect`` 可作为默认值。
"""
_name = "macos_say"
@property
def name(self) -> str:
return self._name
def is_available(self, config: dict | None = None) -> bool:
return bool(shutil.which("say")) and ff.available()
def synthesize(self, request: VoiceGenRequest, config: dict | None = None) -> VoiceGenResult:
config = config or {}
say_bin = shutil.which("say")
if not say_bin:
raise FatalProviderError("当前系统没有 macOS say 命令,无法使用 macos_say 配音",
code="say_unavailable")
if not ff.available():
raise FatalProviderError("本机缺少 ffmpeg/ffprobe,无法转换 say 音频",
code="ffmpeg_unavailable")
text = (request.text or "").strip()
if not text:
raise FatalProviderError("配音文本为空", code="empty_text")
voice = (request.provider_voice_id or config.get("voice") or "Tingting").strip()
if not voice:
raise FatalProviderError("未配置 macOS 系统声线 ID", code="missing_voice")
speed = max(0.5, min(float(request.speed or 1.0), 2.0))
rate = max(80, min(420, int(round(180 * speed))))
out = Path(request.output_path or settings.media_root / "macos_say" / "voice.wav")
out.parent.mkdir(parents=True, exist_ok=True)
with tempfile.TemporaryDirectory(prefix="nex-say-") as tmp:
raw = Path(tmp) / "speech.aiff"
say_cmd = [say_bin, "-v", voice, "-r", str(rate), "-o", str(raw), "--", text]
try:
proc = subprocess.run(say_cmd, capture_output=True, text=True, timeout=120)
except subprocess.TimeoutExpired as exc:
raise FatalProviderError("macOS say 合成超时", code="say_timeout") from exc
if proc.returncode != 0:
detail = (proc.stderr or proc.stdout or "未知错误").strip()
raise FatalProviderError(
f"macOS say 合成失败(声线 {voice}):{detail}",
code="say_failed", detail={"voice": voice, "stderr": detail})
if not raw.exists() or raw.stat().st_size < 512:
raise FatalProviderError(
f"声线「{voice}」没有生成有效音频,可能尚未下载到本机",
code="say_empty_output", detail={"voice": voice})
filters = []
effect = str(request.params.get("effect") or config.get("effect") or "").lower()
pitch = max(0.5, min(float(request.pitch or 1.0), 2.0))
if effect == "alien":
filters.append(ALIEN_AUDIO_FILTER)
elif abs(pitch - 1.0) > 0.01:
sample_rate = max(8000, min(int(request.sample_rate or 24000), 48000))
filters.extend([
f"asetrate={sample_rate}*{pitch:.4f}",
f"aresample={sample_rate}",
f"atempo={1.0 / pitch:.4f}",
])
cmd = [ff.FFMPEG, "-v", "error", "-y", "-i", str(raw), "-vn"]
if filters:
cmd += ["-af", ",".join(filters)]
cmd += ["-ar", str(max(8000, min(int(request.sample_rate or 24000), 48000))),
"-ac", "1", "-c:a", "pcm_s16le", str(out)]
ff.run(cmd, timeout=180)
probed = ff.probe(out)
duration = float(probed.duration or 0.0)
if not out.exists() or out.stat().st_size < 512 or duration < 0.3:
raise FatalProviderError(
f"声线「{voice}」输出的音频过短({duration:.3f}s),请换用已下载的系统语音",
code="say_invalid_audio", detail={"voice": voice, "duration": duration})
return VoiceGenResult(
file_path=str(out),
duration_ms=int(round(duration * 1000)),
provider_job_id=f"macos-say-{abs(hash((voice, text, effect))) % 10**10}",
cost=0.0,
metadata={"provider": "macos_say", "voice": voice, "effect": effect,
"rate": rate, "duration": duration, "real": True},
)

View File

@ -14,7 +14,6 @@ from app.providers.comfy_assets import ComfyImageProvider, ComfyTTSProvider
from app.providers.comfyui import ComfyVideoProvider
from app.providers.http_generic import HttpVideoProvider, HttpVoiceProvider
from app.providers.llm import HttpLLMProvider, MockLLMProvider
from app.providers.macos_say import MacOSSayVoiceProvider
from app.providers.mock import MockVideoProvider, MockVoiceProvider
from app.providers.studio_assets import (HttpImageProvider, HttpTextProvider, MockImageProvider,
MockTextProvider)
@ -25,7 +24,6 @@ _VIDEO_ADAPTERS: dict[str, VideoProviderAdapter] = {"mock": MockVideoProvider(),
_VOICE_ADAPTERS: dict[str, VoiceProviderAdapter] = {
"mock": MockVoiceProvider(),
"http": HttpVoiceProvider(),
"macos_say": MacOSSayVoiceProvider(),
"comfyui_tts": ComfyTTSProvider(),
}
_IMAGE_ADAPTERS: dict[str, ImageProviderAdapter] = {
@ -320,7 +318,10 @@ def comfyui_tts_config(**overrides) -> dict:
"download_from": "modelscope",
"load_node": "easy downloadIndexTTSAndLoadModel",
"generate_node": "easy indexTTSGenerateSimple",
"reference_audio": "nex_tts_reference.wav",
# 描述词直出(voice_instruct)走全参节点 + 音色描述节点;
# 锚点音频沿用 reference_audio:它只当地音,音色由声线的「音色描述」决定。
"generate_full_node": "easy indexTTSGenerate",
"instruct_node": "easy indexTTSEmotionText",
"input_subfolder": "nex_animation",
"filename_prefix": "audio/nex",
"poll_interval": 1,
@ -365,12 +366,42 @@ def _has_real_spec(db: Session, media_type: str) -> bool:
ModelSpec.enabled.is_(True)).first() is not None
def _retire_macos_say(db: Session) -> bool:
"""删掉历史遗留的 macOS 系统语音模型,返回是否改动过数据库。
部署目标是 Linux,`say` 命令在服务器上不存在:这台开发机上登记过 macos-say
的话,模型列表里会永远挂着一个在生产环境不可用的「mac 本地」音频模型。
以前靠 ``is_available()`` 兜着——本机有 say 就登记,看着没错,
实际是把开发机的能力当成了产品能力。现在直接不登记,并把旧行删干净。
"""
from app.models import ModelSpec
rows = list(db.scalars(select(ModelSpec).where(ModelSpec.provider == "macos-say")).all())
if not rows:
return False
media_types = {row.media_type for row in rows}
for row in rows:
db.delete(row)
db.flush()
# 被删的行里如果有默认模型,那个能力就没人兜底了:把剩下最早的真实模型提为默认。
for media_type in media_types:
if db.query(ModelSpec.id).filter(ModelSpec.media_type == media_type,
ModelSpec.is_default.is_(True)).first():
continue
successor = db.scalars(select(ModelSpec).where(ModelSpec.media_type == media_type)
.order_by(ModelSpec.is_default.desc(), ModelSpec.id)).first()
if successor is not None:
successor.is_default = True
db.flush()
return True
def seed_specs(db: Session) -> None:
"""首次启动时注册 mock 模型;如配置了自定义 HTTP 供应商则一并注册。"""
from app.models import ModelSpec
existing = {(s.provider, s.model, s.media_type) for s in db.scalars(select(ModelSpec)).all()}
added = _normalize_llm_specs(db)
added = _normalize_llm_specs(db) or _retire_macos_say(db)
def ensure(**kwargs) -> None:
nonlocal added
@ -416,16 +447,6 @@ def seed_specs(db: Session) -> None:
modes=["chat", "prompt"], min_duration=0, max_duration=0,
max_reference_images=0, currency=settings.cost_currency,
notes="离线大模型:仅验证结构化文本与提示词链路;图像生成请使用独立图像模型")
say_provider = MacOSSayVoiceProvider()
if say_provider.is_available():
ensure(provider="macos-say", model="system-voice",
display_name="macOS 系统语音(真实人声)", media_type="tts",
adapter="macos_say", is_default=settings.tts_provider == "macos-say",
max_concurrency=2, requests_per_minute=30, modes=["voice"],
price_per_1k_chars=0.0, currency=settings.cost_currency,
config_json={"voice": "Tingting"},
notes="使用 macOS say 在本地合成真实语音;声线 ID 可填 Tingting、Meijia、"
"Sinji、Fred 等系统语音,params.effect=alien 可生成外星语效果")
if settings.comfyui_base_url:
ensure(provider="comfyui", model=settings.comfyui_model,
display_name=f"ComfyUI · {settings.comfyui_model}", media_type="video",
@ -448,11 +469,13 @@ def seed_specs(db: Session) -> None:
ensure(provider="comfyui", model="indextts2",
display_name="IndexTTS2(本地音色克隆)", media_type="tts",
adapter="comfyui_tts", is_default=False,
max_concurrency=1, requests_per_minute=12, modes=["voice", "voice_clone"],
max_concurrency=1, requests_per_minute=12,
modes=["voice", "voice_clone", "voice_instruct"],
min_duration=0, max_duration=0, max_reference_images=1,
price_per_1k_chars=0.0, currency=settings.cost_currency,
config_json=comfyui_tts_config(),
notes="9200 本地 IndexTTS2;通过声线的参考音频 ID / 本地音频文件做音色克隆")
notes="9200 本地 IndexTTS2;声线带参考音频时做 zero-shot 音色克隆,"
"没有参考音频时按声线的「音色描述」直接生成语音")
if settings.video_api_base_url:
ensure(provider="http", model=settings.video_model or "custom-video",
display_name="自定义 HTTP 视频供应商", media_type="video", adapter="http",

View File

@ -14,7 +14,7 @@ from app.config import settings
from app.models import Character, Project, Shot, VoiceAsset
from app.providers import registry as model_registry
from app.providers.base import VoiceGenRequest
from app.services import costing, events, storage
from app.services import costing, events, storage, timbre
from app.services import ffmpeg as ff
# 多角色对白逐行合成时,换人之间留的静音(毫秒)
@ -571,6 +571,9 @@ def _tts_produce(db: Session, project: Project, shot: Shot, text: str, voice: Vo
pitch=float(tuning.get("pitch", 1.0)), volume=float(tuning.get("volume", 1.0)),
sample_rate=int(tuning.get("sample_rate", 24000)), seed=(int(shot.seed or 0) + index),
params={**(tuning.get("params") or {}), "shot_code": shot.code},
# 描述词直出:声线没录过音也能配上音(音色由「音色描述」决定)
instruct_text=(timbre.instruct_text_of(voice)
if voice is not None and timbre.instruct_model(spec) else ""),
idempotency_key=f"voice-{shot.id}-{index}", label=f"SHOT-{shot.order_index:02d}-{index + 1:02d}",
output_path=out)
result = model_registry.generate_voice(db, request, spec.provider, spec.model)

View File

@ -273,7 +273,7 @@ def new_voiceover_task(db: Session, project: Project, shot: Shot, *, priority: i
from app.services import audio
# 任务必须记录镜头实际绑定的声线供应商。之前一律按全局默认 TTS 落库,
# 会出现任务显示 mock、产物却由 macos-say 生成的可观测性断层。
# 会出现任务显示 mock、产物却由 IndexTTS2 生成的可观测性断层。
voice = audio.resolve_voice_asset(db, project, shot)
spec, _ = audio.resolve_tts_spec(db, voice)
text = (shot.dialogue or "").strip()

View File

@ -6,10 +6,13 @@
生成时回退到模型配置里的那一段默认参考(女声),出来的试听样本是女声,
界面却全绿、什么都不说。
这里做两件事:
这里做三件事:
1. ``resolve_reference()``:生成前按性别挑一段**真正能决定音色**的参考音频,
挑不到就明确报错,绝不静默用默认嗓;
2. ``check_voice()``:生成后量一次中位基频,与设定性别比对,
例外是 ``voice_instruct`` 模型(IndexTTS2 的描述词直出):
声线填了「音色描述」就走 ``source="instruct"``,没有参考音频也算可用;
2. ``instruct_text_of()``:把声线的音色描述取出来交给适配器;
3. ``check_voice()``:生成后量一次中位基频,与设定性别比对,
结果写进素材 metadata,界面能直接看到「音色与设定不符」。
"""
from __future__ import annotations
@ -249,6 +252,23 @@ def clone_model(spec) -> bool:
return bool((getattr(spec, "config_json", None) or {}).get("clone_reference"))
def instruct_model(spec) -> bool:
"""这个 TTS 能否只靠「音色描述」出音(声线没有参考音频也算可用)。
IndexTTS2 除了 zero-shot 克隆还接受文本描述控制音色与情绪,登记在
``modes`` 里的 ``voice_instruct`` 就是这个能力。以前只认参考音频,
没录过音的角色一律生成不了试听,用户只能先随便塞一段音频凑数。
"""
if spec is None:
return False
return "voice_instruct" in (getattr(spec, "modes", None) or [])
def instruct_text_of(owner) -> str:
"""声线/平台声线的「音色描述」;没有返回空串。"""
return str(getattr(owner, "description", "") or "").strip()
def audio_path_or_empty(value: str | None) -> str:
"""声线记录里的 provider_voice_id 可能是显示名(如「低沉男声」),只有真音频路径才算数。"""
from app.services.audio import AUDIO_SUFFIXES
@ -402,7 +422,8 @@ def _same_gender_voices(db: Session, owner, gender: str) -> list:
return sorted(peers, key=lambda row: (not getattr(row, "is_default", False), -row.id))
def resolve_reference(db: Session, owner, *, explicit: str = "", clone: bool = True) -> dict:
def resolve_reference(db: Session, owner, *, explicit: str = "", clone: bool = True,
instruct: bool = False) -> dict:
"""挑一段真正能决定音色的参考音频,并说明它是谁。
优先级:人工指定 → 本声线自己的参考 → 引入自的平台母版 → **同性别的其他声线** → 模型默认。
@ -411,11 +432,15 @@ def resolve_reference(db: Session, owner, *, explicit: str = "", clone: bool = T
``clone=False`` 表示这个 TTS 走云端音色库(provider_voice_id 是音色 ID,不是参考音频),
此时没有本地参考音频不算问题,交回供应商音色 ID 处理。
``instruct=True`` 表示这个模型支持「音色描述直出」(``voice_instruct``):
找不到任何参考音频时不再报错,改成按声线自己填的音色描述生成(``source="instruct"``)。
参考音频仍然优先——克隆出来的嗓子比描述词精确得多。
"""
chosen = audio_path_or_empty(explicit)
if not clone:
# 云端音色库靠 provider_voice_id 选音色,本地参考**不能**顶替它:
# 把 WAV 路径当音色 ID 发过去,macos_say 之类会直接拿到一个不存在的嗓门。
# 把 WAV 路径当音色 ID 发过去,供应商会直接拿到一个不存在的嗓门。
# 但用户手动挂上来的参考仍然记进 attached,供素材元数据回溯用了哪段音频。
return {"path": "", "attached": chosen, "source": "provider_voice",
"note": ("该模型用供应商音色 ID 选音色,本地参考音频只作记录、不决定音色"
@ -456,6 +481,11 @@ def resolve_reference(db: Session, owner, *, explicit: str = "", clone: bool = T
if bound_generated else
f"本声线还没有参考音频,本次以同性别声线「{sibling.name}」的音色为底生成;"
f"想固定成自己的嗓子,请上传一段{GENDER_LABELS[gender]}参考音频")}
if instruct and instruct_text_of(owner):
return {"path": "", "source": "instruct", "bound_generated": bound_generated,
"note": f"没有{GENDER_LABELS[gender]}参考音频可用,本次按声线的「音色描述」生成"
f"(IndexTTS2 描述词直出);想要更稳的嗓子,"
f"仍可上传一段{GENDER_LABELS[gender]}真人参考音频"}
return {"path": "", "source": "none", "bound_generated": bound_generated,
"note": (_AI_BOUND_NOTE + f"库里也没有任何{GENDER_LABELS[gender]}参考音频可用:"
f"请上传一段{GENDER_LABELS[gender]}真人参考音频再生成"
@ -463,15 +493,18 @@ def resolve_reference(db: Session, owner, *, explicit: str = "", clone: bool = T
f"库里没有任何{GENDER_LABELS[gender]}参考音频可用:"
f"请上传一段{GENDER_LABELS[gender]}参考音频再生成,"
f"否则会拿到与设定不符的音色")}
if instruct and instruct_text_of(owner):
return {"path": "", "source": "instruct", "bound_generated": bound_generated,
"note": "本次按声线的「音色描述」生成:模型默认参考音频只作底声,音色由描述词决定"}
return {"path": "", "source": "model_default", "bound_generated": bound_generated,
"note": (_AI_BOUND_NOTE + "本次使用模型配置的默认参考音频(音色不受表单控制)"
if bound_generated else
"声线未限定性别,本次使用模型配置的默认参考音频(音色不受表单控制)")}
def reference_status(db: Session, owner, *, clone: bool = True) -> dict:
def reference_status(db: Session, owner, *, clone: bool = True, instruct: bool = False) -> dict:
"""给界面用的预告:现在点「生成」会拿到谁的嗓子,值不值得先传参考音频。"""
resolved = resolve_reference(db, owner, clone=clone)
resolved = resolve_reference(db, owner, clone=clone, instruct=instruct)
gender = str(getattr(owner, "gender", "") or "").strip()
return {
"gender": gender,
@ -481,5 +514,9 @@ def reference_status(db: Session, owner, *, clone: bool = True) -> dict:
"borrowed": resolved["source"] in ("gender_sibling", "platform_master"),
# 用户视角的「我明明传过声音」:绑定的是 AI 样本时界面必须说清楚为什么不算
"bound_generated": bool(resolved.get("bound_generated")),
"ready": (bool(resolved["path"]) or resolved["source"] in ("model_default", "provider_voice")),
"ready": (bool(resolved["path"])
or resolved["source"] in ("model_default", "provider_voice", "instruct")),
# 界面据此区分「克隆」与「描述词直出」两种音色来源,别把描述词画成「没有音色」
"instruct": resolved["source"] == "instruct",
"instruct_text": instruct_text_of(owner) if instruct else "",
}

View File

@ -0,0 +1,190 @@
"""回归用例:音频模型不许有「mac 本地」,IndexTTS2 必须能用「音色描述」直出。
用户口径(2026-11 第六轮):
1. 部署服务器是 Linux,没有系统 ``say`` 命令——「mac 本地(macos-say)」这条音频模型
在这台机器上永远跑不通,登记在库里只会让人选中一个不可用的模型;
2. IndexTTS2 除了参考音频克隆,还要支持**直接用描述词生成语音**:
只填「音色描述」(例:年幼小女孩、低沉老年男性)就该出对应的嗓子,
而不是必须先上传一段参考音频。
实测依据(直连 10.100.53.199:9200 提交图验证):
``easy indexTTSGenerateSimple`` 没有 emotions 输入,描述词写进去不生效;
描述词必须走 ``easy indexTTSGenerate``(全参)+ ``easy indexTTSEmotionText``
(reference_audio / voice_name / description / use_random → 输出 emotions)。
同一句台词用两组描述词实测中位基频 241.4 Hz ↔ 189.2 Hz,音色确实在变。
"""
from __future__ import annotations
import importlib
from app.models import ModelSpec, PlatformVoice
from app.providers.base import VoiceGenRequest
from app.providers.comfy_assets import ComfyTTSProvider
from app.services import timbre
CFG = {"base_url": "http://127.0.0.1:9200"}
def _req(**kw) -> VoiceGenRequest:
base = dict(text="你好,我是这条声线。", label="声线A", output_path="/tmp/x.wav",
provider_voice_id="")
base.update(kw)
return VoiceGenRequest(**base)
# ------------------------------------------------------------------ 描述词图
def test_instruct_switches_graph_to_full_node_with_emotion():
"""填了音色描述 → 换全参生成节点,并挂上描述词节点(Simple 节点不接 emotions)。"""
graph = ComfyTTSProvider.graph(_req(), CFG, 1234, "nex_animation/ref.wav",
instruct="低沉老年男性")
assert graph["3"]["class_type"] == "easy indexTTSGenerate"
assert graph["5"]["class_type"] == "easy indexTTSEmotionText"
assert graph["5"]["inputs"]["description"] == "低沉老年男性"
assert graph["5"]["inputs"]["reference_audio"] == ["2", 0]
assert graph["3"]["inputs"]["emotions"] == ["5", 0]
# 全参节点的必填项一个都不能少,缺一项 ComfyUI 会在提交阶段直接拒绝整张图
for key, value in ComfyTTSProvider.FULL_DEFAULTS.items():
assert graph["3"]["inputs"][key] == value, key
assert graph["3"]["inputs"]["text"] == "你好,我是这条声线。"
assert graph["3"]["inputs"]["seed"] == 1234
def test_instruct_keeps_clone_reference_when_present():
"""有真人参考音频时克隆优先:描述词只做偏移,不该把克隆来的嗓子丢掉。"""
graph = ComfyTTSProvider.graph(_req(), CFG, 7, "nex_animation/ref.wav",
instruct="年幼小女孩")
assert graph["3"]["inputs"]["reference_audio"] == ["2", 0]
def test_description_only_mode_still_loads_the_anchor_audio():
"""只填描述词时仍要一段底声锚点:ComfyUI-Index-TTS 的 emotion 节点
``reference_audio`` 是必填项,缺了它整张图提交就被拒。
锚点用模型配置的默认参考音频,音色由描述词决定——实测同一句台词两组描述词
中位基频 241.4 Hz ↔ 189.2 Hz,锚点相同而嗓子不同。
"""
graph = ComfyTTSProvider.graph(_req(), CFG, 7, "nex_default.wav",
instruct="年幼小女孩")
assert graph["2"]["inputs"]["audio"] == "nex_default.wav"
assert graph["5"]["inputs"]["reference_audio"] == ["2", 0]
assert graph["3"]["inputs"]["reference_audio"] == ["2", 0]
assert graph["3"]["inputs"]["emotions"] == ["5", 0]
def test_plain_clone_graph_is_unchanged():
"""没填描述词时仍是原来的 zero-shot 克隆图,老行为不受影响。"""
graph = ComfyTTSProvider.graph(_req(), CFG, 7, "nex_animation/ref.wav", instruct="")
assert graph["3"]["class_type"] == "easy indexTTSGenerateSimple"
assert "emotions" not in graph["3"]["inputs"]
assert "5" not in graph
def test_capabilities_declare_voice_instruct():
caps = ComfyTTSProvider().capabilities(CFG)
assert "voice_instruct" in caps.modes
assert "voice_clone" in caps.modes
# ------------------------------------------------------------------ mac 本地下线
def test_macos_say_adapter_is_gone():
assert importlib.util.find_spec("app.providers.macos_say") is None
def test_registry_no_longer_seeds_macos_say(db):
from app.providers import registry
registry.seed_specs(db)
db.commit()
assert db.query(ModelSpec).filter(ModelSpec.provider == "macos-say").count() == 0
rows = list(db.query(ModelSpec).filter(ModelSpec.media_type == "tts").all())
assert rows, "音频模型整类不能因为下线 macos-say 而被清空"
assert "macos-say" not in {r.provider for r in rows}
indextts = [r for r in rows if r.adapter == "comfyui_tts"]
assert indextts, "IndexTTS2 必须仍在册"
assert "voice_instruct" in (indextts[0].modes or [])
def test_legacy_macos_say_row_is_retired_and_default_promoted(db):
"""库里已经登记过 macos-say(开发机残留):启动时删掉,默认值顺延给后继模型。"""
from app.providers import registry
stale = ModelSpec(media_type="tts", provider="macos-say", adapter="macos_say",
display_name="mac 本地", model="system-voice",
model_code="macos-say/system-voice", is_default=True, enabled=True)
keeper = ModelSpec(media_type="tts", provider="comfyui_tts", adapter="comfyui_tts",
display_name="IndexTTS2", model="IndexTTS-2",
model_code="comfyui/indextts2", is_default=False, enabled=True,
modes=["voice", "voice_clone", "voice_instruct"])
db.add_all([stale, keeper])
db.commit()
assert registry._retire_macos_say(db) is True
db.commit()
assert db.query(ModelSpec).filter(ModelSpec.provider == "macos-say").count() == 0
db.refresh(keeper)
assert keeper.is_default is True
# 幂等:第二次没有 macos-say 行可删,不再动默认标记
assert registry._retire_macos_say(db) is False
# ------------------------------------------------------------------ 音色解析
def test_instruct_model_is_detected_from_modes():
spec = ModelSpec(media_type="tts", provider="comfyui_tts", adapter="comfyui_tts",
display_name="IndexTTS2", model="IndexTTS-2",
modes=["voice", "voice_clone", "voice_instruct"])
assert timbre.instruct_model(spec) is True
clone_only = ModelSpec(media_type="tts", provider="comfyui_tts", adapter="comfyui_tts",
display_name="只认参考音频的模型", model="x",
modes=["voice", "voice_clone"])
assert timbre.instruct_model(clone_only) is False
def test_description_only_voice_resolves_to_instruct(db):
"""没参考音频、没性别的声线:以前只能拿模型默认参考(音色不受控),现在走描述词。"""
voice = PlatformVoice(name="描述词声线", code="instruct-only", gender="",
description="年幼小女孩,音色清亮,语速偏快",
is_active=True, is_default=False, provider_voice_id="")
db.add(voice)
db.commit()
assert timbre.instruct_text_of(voice) == "年幼小女孩,音色清亮,语速偏快"
resolved = timbre.resolve_reference(db, voice, instruct=True)
assert resolved["source"] == "instruct"
assert resolved["path"] == ""
assert "音色描述" in resolved["note"]
status = timbre.reference_status(db, voice, instruct=True)
assert status["instruct"] is True
assert status["ready"] is True
assert status["instruct_text"] == "年幼小女孩,音色清亮,语速偏快"
# 关掉描述词能力(换回只认参考音频的模型)时,预告回到原来的口径
plain = timbre.reference_status(db, voice, instruct=False)
assert plain["instruct"] is False
assert plain["source"] == "model_default"
def test_instruct_needs_a_description(db):
"""描述词是空的:不能谎称「按描述词生成」,仍按模型默认参考处理。"""
voice = PlatformVoice(name="空描述", code="instruct-empty", gender="",
description="", is_active=True, is_default=False,
provider_voice_id="")
db.add(voice)
db.commit()
assert timbre.resolve_reference(db, voice, instruct=True)["source"] == "model_default"
def test_reference_audio_still_wins_over_description(db, tmp_path):
"""参考音频优先于描述词:克隆出来的嗓子比描述词精确得多。"""
anchor = tmp_path / "anchor.wav"
anchor.write_bytes(b"RIFF" + b"\0" * 40)
voice = PlatformVoice(name="有参考", code="instruct-ref", gender="male",
description="低沉老年男性", is_active=True, is_default=False,
provider_voice_id=str(anchor))
db.add(voice)
db.commit()
resolved = timbre.resolve_reference(db, voice, instruct=True)
assert resolved["source"] == "self"
assert resolved["path"] == str(anchor)

View File

@ -1,77 +0,0 @@
from __future__ import annotations
import shutil
import pytest
from app.providers.base import FatalProviderError, VoiceGenRequest
from app.providers.macos_say import ALIEN_AUDIO_FILTER, MacOSSayVoiceProvider
from app.services import ffmpeg as ff
pytestmark = pytest.mark.skipif(
not shutil.which("say") or not ff.available(),
reason="需要 macOS say 与 ffmpeg",
)
def test_macos_say_generates_real_chinese_speech(tmp_path):
output = tmp_path / "waiter.wav"
result = MacOSSayVoiceProvider().synthesize(
VoiceGenRequest(
text="先生您好,今晚的头道菜是炭烤战斧牛排。",
provider_voice_id="Tingting",
language="zh-CN",
output_path=output,
)
)
assert output.exists()
assert result.duration_ms >= 1000
assert result.metadata["real"] is True
assert ff.probe(output).has_audio
def test_macos_say_alien_effect_produces_audible_audio(tmp_path):
output = tmp_path / "predator.wav"
result = MacOSSayVoiceProvider().synthesize(
VoiceGenRequest(
text="Sssth. Ka-laa, tuuk. Hsss, raa-ka-ta.",
provider_voice_id="Fred",
language="en",
params={"effect": "alien"},
output_path=output,
)
)
assert output.exists()
assert result.duration_ms >= 1000
assert result.metadata["effect"] == "alien"
assert "acrusher" in ALIEN_AUDIO_FILTER
def test_macos_say_rejects_empty_text(tmp_path):
with pytest.raises(FatalProviderError, match="配音文本为空"):
MacOSSayVoiceProvider().synthesize(
VoiceGenRequest(text=" ", provider_voice_id="Tingting", output_path=tmp_path / "empty.wav")
)
def test_voiceover_task_records_the_bound_macos_provider(api):
pid = api.project()
voice = api.post(f"/api/projects/{pid}/voices", json={
"name": "真实中文女声",
"provider": "macos-say",
"provider_voice_id": "Tingting",
"language": "zh-CN",
})["result"]
shot = api.post(f"/api/projects/{pid}/shots", json={
"title": "报菜名", "description": "服务员端上菜", "duration": 5,
"dialogue": "您的牛排,请慢用。", "voice_asset_id": voice["id"],
})["result"]
api.post(f"/api/projects/{pid}/voiceover", json={"shot_ids": [shot["id"]]})
task = next(t for t in api.get(f"/api/tasks?project_id={pid}&kind=voiceover")["tasks"]
if t["shot_id"] == shot["id"])
assert task["provider"] == "macos-say", task
assert task["model"] == "system-voice", task

View File

@ -42,7 +42,7 @@
| R13 | **布局 utility 压在 antd 组件根节点上,依赖三处层叠声明**:`app/providers.tsx` 的 `<StyleProvider layer>`;`styles/index.css` 里拆开 import **之前**的 `@layer theme, base, components, antd, utilities;`;以及 `@import "tailwindcss/preflight.css" layer(antd)`——**preflight 必须与 antd 同层**,写回 `layer(base)` 会被 antd 的 prepend 反超、全站复位反吃组件样式。两者任一被摘掉,`max-md:hidden` 这类 utility 会**静默失效**(tsc / build 全绿,只有浏览器能看出来)(详见 §1.1) | Tailwind v4 把 utility 放进 `@layer`,而 antd 默认注入的 CSS 未分层;按 CSS 层叠规则「未分层永远赢过分层」, antd 会把我们的布局 utility 全量盖掉 |
| R14 | **按钮与浮层底部只用 antd 原生词汇**:`type` / `danger` / `size` / `icon` / `shape` / `loading`,自造 `variant` 方言已废;浮层底部一律「辅助 → 取消 → 主行动」右对齐、整条 md 档、最多一颗 `type="primary"`(详见 §5.1、§10)。裸 `<button>` 只许出现在 §5.2 的自定义表面族白名单里 | 219 处 `variant=` 是靠 codemod 迁完的:只要方言还在,下一个页面就会接着发明名字,主题与档位又收不口 |
| R15 | **按钮一律是图标按钮**:凡有动作语义的按钮都写 `icon={<IconXxx />}`,`FilePick` / `RecordAudio` 这两个自带触发元素的封装也走 `icon` 槽;一个意思全站只许一只图形(§5.1.1) | 一排纯文字按钮要逐个读完才知道哪颗是什么,图标剪影一眼分得开;用户截图原话「按钮都要使用图标按钮」 |
| R16 | **信息块三件套各有唯一写法**(§13.1):① **统计**=`Stat`/`StatGrid`,自带 `bg-fill-tertiary` 底纹 + 右下角语义水印图形,页面不再手涂 `bg-[#...]`;② **只读回显**=`Info`(antd `Descriptions`),「灰盒 + label 在上」和用 `Input disabled` 装只读值一律废止,只读 `Tag` 不许描边,统计用途的计数不许用无底纹灰胶囊;③ **语义提示**=`Notice`(自绘语义块,读 ① ② 同一把 `BLOCK_TONE` 底纹尺),页面不再自拼 `border + warning-bg` 当告警 | 白底数字块与卡片同色,扫不出「这是结论」还是「这是容器」;灰盒回显和旁边的输入框长得一样,用户去找可点的框,框里却没有可改的东西;底纹与告警底色都是 antd 自己的 fill / 语义色层,明暗两档跟主题走,不需要再养一套私有皮肤 |
| R16 | **信息块三件套各有唯一写法**(§13.1):① **统计**=`Stat`/`StatGrid`,卡面就是 antd Card 的 `colorBgContainer`(**纯色、无底纹、无渐变、无水印**),识别度全部交给数字左侧那只 32px 圆角色块(底色 = 本卡语义色 `color-mix` 12%,深色档 18%;图形 = 同一条语义色),页面不再手涂 `bg-[#...]`;② **只读回显**=`Info`(antd `Descriptions`),「灰盒 + label 在上」和用 `Input disabled` 装只读值一律废止,只读 `Tag` 不许描边,统计用途的计数不许用无底纹灰胶囊;③ **语义提示**=`Notice`(自绘语义块,读 ① ② 同一把 `BLOCK_TONE` 底纹尺),页面不再自拼 `border + warning-bg` 当告警 | 白底数字块与卡片同色,扫不出「这是结论」还是「这是容器」;灰盒回显和旁边的输入框长得一样,用户去找可点的框,框里却没有可改的东西;底纹与告警底色都是 antd 自己的 fill / 语义色层,明暗两档跟主题走,不需要再养一套私有皮肤 |
| R17 | **表格行不许被子元素撑高**(§13.2):① 先做列宽预算——`Table` 默认 `minWidth={false}`,定宽列合计必须回到容器里,长文列**不写 `width`** 吃掉剩余宽度且扣掉内边距后 ≥ 200px;② 单元格里的长文案一律 `<Clamp>` 封顶(标题 1 行 / 说明与报错 2 行)并把全文挂原生 `title`,表格里的 `ErrorText` 同样必须给 `lines`;③ 动作列按「`颗数×32 + (颗数−1)×6 + 16`」算宽、图标化一行放完;④ 格子里并排的内容不许越出
自己的盒子、不许互相压叠(> 2px 立案)。一个格子的预算是**正文两行 + 次要元信息一行 ≈ 84px**,超了就是返工。**这条由 `scripts/ui/tableaudit.py` 常驻量,不靠自觉** | 「列宽」与「文案长度」两头堵,只调列宽永远调不完:审核留痕一句质检长文把行顶到 255px、生成记录一条 prompt 顶到 227px,一屏只剩三条记录,表格退化成段落。用户第 28 轮原话「表格行不要被子元素撑高(长文折 8 行 = 设计失败)」 |
| R18 | **每一级的身份与动作只在该级说一遍**(§6.5 四级层次):项目名 / 状态 / 进度 / 归档 / 删除只属于**项目层**(顶栏那颗流程控制台胶囊是唯一入口,点开右侧「项目概况」抽屉);「这是哪一站 + 这一站的主操作」只属于**环节层**(`PageHead`:一张带底纹描边的独立门牌卡);数据与筛选只属于**内容层**(`Panel`)。工作台外壳 `pages/ProjectDetail.tsx` 除兜底(载入 / 未找到 / 报错)外**不渲染任何可见块** | 用户第 11 轮原话「要进一步把各级的信息归拢并提供交互的层次清晰」:当时同一条项目身份在顶栏、外壳面包屑、概览页页头各说一遍,而**项目级**的「归档」坐在**环节级**页头上 |
@ -1114,14 +1114,20 @@ antd 的 `Tag.CheckableTag` 未选中态是**完全透明**的。铺进等宽格
| 种类 | 它在回答什么 | 唯一写法 | 已废止的写法 |
|---|---|---|---|
| **统计** | 「现在有多少 / 达没达标」 | `Stat`(= antd `Statistic` + 卡)/ `StatGrid` | 自绘大数字、白底数字块、把计数写成无底纹的灰 `Tag` 胶囊 |
| **统计** | 「现在有多少 / 达没达标」 | `Stat`(= antd `Statistic` + 纯色卡 + 32px 色块图形)/ `StatGrid` | 自绘大数字、无容器的裸数字块、卡面涂底纹 / 压水印、把计数写成灰 `Tag` 胶囊 |
| **只读回显** | 「它被配置成了什么」 | `Info`(= antd `Descriptions`,`bordered` + `size=small` + `colon=false`) | 灰盒 + `label` 在上的假输入框、`<Input disabled>` 装只读值、带描边的只读 `Tag`、`a · b · c` 散文属性行 |
| **语义提示** | 「这一步会发生什么 / 为什么不能做」 | `Notice`(自绘语义块,四档 `type` + `description` 第二层 + `action` 位;2026-11 第十三轮起不再包 antd `Alert`) | 自拼 `border border-warning-border + bg-warning-bg`、`<b>` + `<small>` 造二层 |
**① 统计卡:底纹 + 背景图形。** `Stat` 的卡档自带 `bg-fill-tertiary`,并给右下角压一枚同语义的
`--nex-stat-mark` 水印图标(`opacity 0.09`、84px、`pointer-events:none`,文字层 `z-index:1` 抬在之上)。
水印只在给了 `icon` 时出现,配色取 `--nex-stat-tint`(与 `tone` 同一支语义色),不是新的色值。
栅格一律 `StatGrid`,卡片列数走 `steps`,别在页面写 `grid-cols-*` 定宽。
**① 统计卡:纯色卡面 + 配套色块图标。** `Stat` 的卡面就是 antd `Card` 自己的 `colorBgContainer`
——没有底纹、没有渐变、没有水印(第六轮之前压过右上径向渐晕 + 135° 斜纹 + 右下角 84px 水印,
四张卡并排时那层纹理连成一片灰,最该跳出来的数字反被压住,用户原话「不要底纹,用配套的色块和图标区分」)。
识别度全部交给数字左侧那只 32px 圆角色块:底色 = 本卡语义色 `color-mix(in srgb, … 12%, transparent)`
(深色档提到 18%,压在 `#141414` 上 12% 读不出来),图形 = 同一条语义色;色调由 `tone` 经
`--nex-stat-tint` 下发,`app.css` 的色块族再转读 `--nex-mark-tint`(统计卡 / 概况抽屉七站行 / 吐司 /
提示条 / 确认框同一族,一大一小两档几何)。**不传 `icon` 就没有色块,正文满宽**;色块顶对齐标题
(它标的是「这一格是什么」),说明文字缩进正文列,不许钻到色块底下。
栅格一律 `StatGrid`,卡片列数走 `steps`,别在页面写 `grid-cols-*` 定宽;**每页卡数由内容决定**
(概览 8、用户 5、调度与交付 2),不为了凑齐一行删掉真实指标。
**② 只读回显:一律 `Info`。** `Info` 的 label 列由 antd 上 `colorFillAlter` 底纹(深色档在 `app.css`
抬到 7% 白,4% 压不出「这一列是标签」),值列 `overflow-wrap:anywhere`。用法三约束:
@ -1559,7 +1565,9 @@ NEX_ROUTES="/projects/{id}/review" NEX_THEMES=light \
交回自动档后再跑:576/430 两档 ×(library、review)`BTNROWS_TOTAL 0`,1440 档页头
一字未动(`phprobe` 量的 `flexDirection`:430 竖排 / 1440 横排);全量闸七档 × 13 路由
`BTNROWS_GROUPS 308 EXEMPT_STACK 38` → `BTNROWS_TOTAL 0`、`HEAD_BREAK_TOTAL 0`
(页头改造落地前同一批是 3 条命中)。
(页头改造落地前同一批是 3 条命中)。2026-11-04 全树收口后再复扫:
`BTNROWS_GROUPS 413 EXEMPT_STACK 59 / BTNROWS_TOTAL 0 / HEAD_BREAK_TOTAL 0`——组数涨到 413 是
这一轮把散落的按钮排收进 `ActionGroup` 的结果,**组数涨、违规数恒 0** 才是这条尺子要的走向。
**判据② `HEAD_BREAK`(第 17 轮补)——卡头不许拿标题断行换宽度**。同一把尺子的另一面:
判据① 管「一整组不该被劈开」,这条管「该行装不下时该走的是整块」。
@ -1672,6 +1680,47 @@ provider 漏渲染、store 被引成第二份实例,都会让 `notify()` 静
**`FOOTER_PROBED 30 FOOTER_BAD_TOTAL 0`**(改前同一批是 430 档 2 条)。
单档耗时约 19 分钟(每条 CASE 都要开层、量、`Esc`),别把它塞进秒级反馈回路里。
### 15.11 `.venv/bin/python scripts/ui/btnclustercheck.py` —— 不认类名量「一组按钮被劈开」(§7 · 用户第 2 条)
第 17 轮(续)立项。`btnrowcheck` 只认 kit 的 `.nex-action-group`、`footercheck` 只认浮层吸底条,
于是**「页面自己 `flex flex-wrap gap-2` 摆几颗按钮」这一族从头到尾没进过任何一把尺子的视野**——
它连类名都没有,往既有闸门里加选择器都无处可加(§15.7 那条「扫不到就等于没有」的第三个变种)。
这条尺子不读类名,只看 DOM 邻接:
| 项 | 内容 |
|---|---|
| 一簇 | 父元素**直接子节点**里**连续**的可见 `button` / `[role=button]`(中间只容得下空白与注释;隔一个非按钮子节点就是两簇,各自判) |
| 不是它的对象 | `flex-direction:column` / `display:grid` 的父容器(多行是设计)、`td` / `th` / `[role=cell]`(一行一格、格内本就一颗)、`position:absolute` / `fixed` 的角标(不参与流内换行)、`.nex-chipbar` / `.nex-taggroup`(胶囊流是**选项集合**不是协同动作,与 `btnrowcheck` 同一条豁免,§7.1) |
| 判据 | 同一簇按钮的垂直中心落在 **≥2 条水平线** = 被劈开;唯一合法的多行 = **整簇换行且每颗宽 ≥ 父内容宽的 92%** |
| 口径 | `BTNCLUSTER_CLUSTERS`(**覆盖面**:量到多少簇,单行的也记)/ `MULTI`(其中多行的)/ `BAD_TOTAL`(违规的) |
| 死闸门底线 | `CLUSTERS < NEX_MIN_CLUSTERS`(默认 60)→ 退出码 2「尺子自己瞎了」 |
| env | `NEX_BASE` / `NEX_WIDTHS` / `NEX_THEMES` / `NEX_ROUTES` / `NEX_MIN_CLUSTERS` / `NEX_SETTLE`(打 :5173 冷编译要 2600,否则只有壳;静态包 900 够) |
| 退出码 | 0 = 干净;1 = 有点名;2 = 一簇都没量到 |
**首扫(5 档 × 13 路由)点名三类,两类是真缺陷**:
① `/models` 模型卡底 `启用 / 设为默认 / 检测连接 / 删除` 四颗全平铺在 `CardActions` 上,
430 档实测「删除」孤零零掉进第二行,卡再窄一点就会把「设为默认 / 检测连接」这一对劈成 1+1;
② `/projects/10/storyboard` 镜头卡底:左端 `改文案 / 重生成` 把宽度吃掉之后 `BarRight` 只剩 **89px**,
**1440 档**就把 `审核 + 复制` 摆一行、`删除` 单独甩到第二行;
③ `/assets` 封面角标「使用中 + 删除」——**误伤**,它们 `absolute` 定位各占一角,据此才加「跳过绝对定位」那条豁免。
两处修复都按 §7 的分组判据把成对动作套进 `<ActionGroup>`(对象级操作一组、破坏性操作单独一组,
整块换行而不是组内换行),另把 `/projects/10/library` 素材行的「登记新版本 + 删除」预防性包了一组
(改前三档实测未劈开,但那一行同样没有类名,是这条尺子的天然猎物)。
2026-11-03 修后全量(light · 1440/992/768/576/430 × 13 路由):
**`BTNCLUSTER_CLUSTERS 159 MULTI 0 BAD_TOTAL 0`**(159 = 五档量到的簇数;
表格单元格里的那些按定义不算簇,所以这个数比 `btnrowcheck` 的 413 组小)。
两次自纠 + 一次口径纠错,都值得记:
① **第一版把「一簇」定义成父元素的*全部*子节点都是按钮** → 13 条路由 **0 簇**,被自己的底线当场拦下。
素材行是「缩略图 + 标签 + 两颗按钮」,那两颗仍然是一组——改成「连续按钮段」才对。
② **第二版把封面角标算进簇** → `/assets` 12 张封面全点名。先量清楚它们是绝对定位、不参与换行,
再写豁免;豁免是量出来的,不是先验写下的。
③ **底线本身错过一次口径**:初版只 push 多行的那几簇,于是 `PROBED` 数的是「被劈开的簇」而不是
「量到的簇」——页面修干净之后它恒等于 0,`MIN_CLUSTERS` 那条**永远红**,把健康态当成失灵。
现在覆盖面与违规分开报(`CLUSTERS` / `MULTI` / `BAD_TOTAL`),
道理和 `btnrowcheck` 的 `GROUPS 413 / TOTAL 0` 是同一条:**覆盖面是分子非零的前提,违规是判据**。
反向验证见 §15.12 的 `pb-cluster`(260 内宽三颗 120px → 2+1 必须响)/ `pg-cluster`(三颗满宽换行必须静)。
### 15.12 `.venv/bin/python scripts/ui/gateprobe.py` —— 反向验证七张闸门的十一条判据
第 30 轮立项、第 14 轮补齐到 **6/6**、第 16 轮补 `tagcheck.SPILL` 到 **7/7**、
@ -1698,7 +1747,7 @@ provider 漏渲染、store 被引成第二份实例,都会让 `notify()` 静
| `tableaudit` | 300px 定宽单元格里 284px 的条 + nowrap 文本右溢 10px(`格子内容越界`) | 同样布局换成 220px 的条——摆得下就不许报 |
任一条对不上退出码 1(“闸门瞎了或过敏,先修闸门再谈页面”),最后一行必须打出
`GATEPROBE_OK 10/10`(10 = 闸门条目数,不是断言数)。**改动这些闸的判据或豁免时必须跑它**:
`GATEPROBE_OK 11/11`(11 = 闸门条目数,不是断言数)。**改动这些闸的判据或豁免时必须跑它**:
`ctl` 与 `spill` 两条就是靠 `pb-ctl` / `pb-tspill` 证明「坏了会响」之后才当退出条件用的;
反过来 `pg-ctl` / `pg-tspill` 挡的是另一种失败——判据太敏感,把合法布局也报成缺陷。
第 14 轮补 `ctl` / `spill` 时先跑的正是它:先看到两条新判据各自「坏 fixture 响、好 fixture 静」,

View File

@ -88,7 +88,7 @@ api/ → app/ → pages/ → components/{ui,forms,media}/ → theme/ · lib/ ·
| `dev.sh` | 开发机上启停前后端(Vite 热更新 + `--reload`) |
| `server.sh` | 服务器上安装、构建、启停、看状态、跑验收 |
| `deploy.sh` | 开发机上打部署包 / 推到服务器 |
| `seed.py` | 导出与导入「部署数据」(模型配置 + 主密钥 + 管理员) |
| `seed.py` | 「部署数据」(模型配置 + 主密钥 + 管理员)的体检与搬运:`doctor` 量数据集与代码是否对得上、`export --fix` 校准并导出、`install` 装前先体检再幂等落地、`boundary` 列数据边界 |
| `e2e_selfcheck.py` | 对着真实运行的服务跑一遍 12 节点全流程 |
| `evidence_prune.py` | 整理验收台账 `.local/acceptance/evidence.jsonl` |
| `ui/audit.py` | **前端 UI 体检**:14 视图(含未登录的登录页)× 3 宽度 × 明暗 + 10 个浮层 × 4 宽度 × 明暗,七项判据(裸控件 / 字段错位 / 溢出 / 档位 / 下拉 / console 报错 / **浮层是否真的在视口内**),退出码非 0 就是没过。改过任何控件、表单、主题都要跑(口径见 UI规范 §1.3) |
@ -111,7 +111,7 @@ api/ → app/ → pages/ → components/{ui,forms,media}/ → theme/ · lib/ ·
## 3. 测试规范
- **归属**:自动化用例一律放 `backend/tests/`(当前 43 个文件、495 条)。
- **归属**:自动化用例一律放 `backend/tests/`(当前 43 个文件、503 条)。
新增能力必须同时带用例;修 bug 必须先写能复现的用例,再改代码。
- **两类测试分工明确**:
- `backend/tests/`(pytest + TestClient,进程内):契约、状态机、边界值,
@ -172,19 +172,20 @@ api/ → app/ → pages/ → components/{ui,forms,media}/ → theme/ · lib/ ·
| 内容 | 怎么到新机器上 |
|---|---|
| 表结构 + 列迁移 | `app/db.py:init_db()`,应用启动自动执行,无需手工 SQL |
| 模型配置(`model_specs`) | `scripts/seed.py export` → `scripts/seed/model_specs.json` → `install` |
| 模型配置(`model_specs`) | `scripts/seed.py export --fix` → `scripts/seed/model_specs.json` → 包内 `install`(装前 doctor 再量一次) |
| 加密主密钥(`model_secret_keys`) | 同上,**必须与密文同行**:缺了它 `api_key_encrypted` 解不开 |
| 管理员账号(`users` 里 role=admin) | 同上,导 `password_hash`,不带明文口令 |
| 项目 / 镜头 / 任务 / 事件日志 | **不部署**,服务器从空库开始 |
| `media/` 媒体、平台资源库 | **不部署**;需要时走 `seed.py --with-platform-library` + 手工拷 `media/platform/` |
| whisper 听写权重 | `server.sh install` 自动下载(`--no-asr` 跳过) |
**开发机打包**:
**开发机打包**(`export --fix` 与 `deploy.sh` 都会体检,区别只是拦在哪一步):
```bash
.venv/bin/python scripts/seed.py export # 更新 scripts/seed/*.json(含机密,不进 git)
./scripts/deploy.sh --check # 只体检:会带上什么、会排掉什么
./scripts/deploy.sh # → .local/deploy/nex_animation-<时间戳>.tar.gz
.venv/bin/python scripts/seed.py doctor # 只量不改:开发库 vs 当前代码
.venv/bin/python scripts/seed.py export --fix # 校准 + 体检 + 更新 scripts/seed/*.json(含机密,不进 git)
./scripts/deploy.sh --check # 只体检:会带上什么、会排掉什么、数据能不能装
./scripts/deploy.sh # → .local/deploy/nex_animation-<时间戳>.tar.gz
./scripts/deploy.sh --host deploy@10.0.0.8 --path /opt/nex_animation # 打包+上传+远端安装
```
@ -192,14 +193,18 @@ api/ → app/ → pages/ → components/{ui,forms,media}/ → theme/ · lib/ ·
```bash
tar -xzf nex_animation-<时间戳>.tar.gz && cd nex_animation
./scripts/server.sh install # 依赖 → 前端构建 → 听写模型 → 建表 + 导入部署数据
./scripts/server.sh install # 依赖 → 前端构建 → 听写模型 → 体检 + 建表 + 导入部署数据
./scripts/server.sh start # 单进程 uvicorn,顺带托管前端产物(SERVE_FRONTEND=on)
./scripts/server.sh status # 端口 / 默认模型 / ComfyUI 连通性 / 数据边界
./scripts/server.sh status # 端口 / 默认模型 / ComfyUI 连通性 / 数据边界(seed.py boundary)
./scripts/server.sh verify # 12 节点全流程自检
sudo ./scripts/server.sh systemd > /etc/systemd/system/nex-animation.service # 可选常驻
```
三条部署硬约束(写在 `server.sh` 头部,这里给原因):
同一台机器已经跑过一段、服务器上模型被人工调过时的重复部署:
`./scripts/server.sh install --only-missing`(透传给 `seed.py install`,只补库里没有的模型,
不覆盖同名配置的端点与参数)。`--allow-drift` 是体检报 error 时的逃生门,默认关。
四条部署硬约束(写在 `server.sh` 头部,这里给原因):
1. **只起一个 uvicorn 进程**。`TASK_EXECUTOR=inline` 时调度守护线程在进程内,
`--workers 4` 就是四份守护线程抢同一批任务、重复派发。要扩展就切 celery。
@ -207,14 +212,28 @@ sudo ./scripts/server.sh systemd > /etc/systemd/system/nex-animation.service #
主密钥并把 mock 播成默认,导入时还得再纠正一次默认位。
3. **`.env` 不随包走**。它是机器相关配置;`server.sh install` 会生成单机版
(SQLite + inline + `SERVE_FRONTEND=on`),而不是照抄 docker 版 `.env.example`。
4. **灌数据之前先体检**。快照比代码旧时后果是「静默少功能」而不是报错,而 `install`
一旦跑过就改掉了表结构与默认位、回不到原样,所以 `seed.py install` 先量后写。
原因与实测见下面「第四条不变量」。
**体检的三条不变量**(`deploy.sh`,2026-11-01 加):
**体检的五条不变量**(`deploy.sh`,2026-11-01 加第 1/3/5 条,2026-11-05 补第 2/4 条):
1. **打包别少带**:`backend/app` 下的 `.py` 文件数必须与源目录一致;
2. **带了要能起**:直接在暂存目录里 `import app.main`,数一遍路由条数;
3. **提交别少带**(它的镜像):把 `backend/app` + `frontend/src` 全部源文件喂给
1. **打包别少带**:`backend/app` 下的 `.py`、`frontend/src` 下的 `.ts/.tsx/.css`
文件数必须与源目录一致;
2. **前端入口链必须闭合**:从 `index.html` 的 `<script type="module">` 出发,把 static
import、`export … from`、路由懒加载的 `import('../pages/X')`、CSS 里的
`@import "./app.css"` 全部解析到底。说明符在源码里解析不到 = 本地就断链;
解析到了但包里没有 = 某条 `--exclude` 精准误伤了它。这一条同时取代了上一版手写的
源码清单:`REQUIRED` 里点名的 `styles/tokens.css` 在 antd 改版时被拆成
`app.css` + `index.css`,没人记得回来改这行,`--check` 从此天天红。
**清单会随重构腐烂,入口链不会。**
3. **带了要能起**:直接在暂存目录里 `import app.main`,数一遍路由条数;
4. **数据必须配得上代码**:用**包里的** `seed.py doctor --src` 量**包里的**数据集
(列 / 适配器 / 能力位 / 默认位 / 主密钥能否解开密文)。用包内副本而不是开发机
工作树,过检的才是「这份代码 + 这份数据」这个组合本身。原因见下一节。
5. **提交别少带**(第 1 条的镜像):把 `backend/app` + `frontend/src` 全部源文件喂给
`git check-ignore --no-index`,任何命中都说明某条忽略规则写宽了。
当前 112 个源文件必须 0 命中。
当前 156 个源文件必须 0 命中。
原因是一次真实翻车:`--exclude 'models/'` 本意是排仓库根的 whisper 权重目录(465M),
但 rsync/gitignore 的**裸目录名在任意层级生效**,把 `backend/app/models/` 这 11 个 ORM
@ -232,9 +251,31 @@ sudo ./scripts/server.sh systemd > /etc/systemd/system/nex-animation.service #
斜杠结尾只匹配**目录**,`api/media.py`、`src/media.ts` 这类代码文件不受影响 |
| `dist/` `reports/` `.local/` `.trash/` | 锚根 | 都是单点目录,没必要放开 |
不变量 3 就是这条口诀的自动执行:`.gitignore` 改坏时 `deploy.sh` 当场 die 并把吃掉的
不变量 5 就是这条口诀的自动执行:`.gitignore` 改坏时 `deploy.sh` 当场 die 并把吃掉的
文件列出来(反向验证:临时加一条 `backend/app/models/`,11 个 ORM 文件立刻被点名)。
### 第四条不变量的原因:数据集是快照,代码是活水
`scripts/seed/*.json` 是某一天从开发库导出来的快照。快照落后于代码时,服务器上的表现
不是报错而是**静默降级**,比崩掉难查得多:
| 快照缺什么 | 服务器上的现象 | 谁在读它 |
|---|---|---|
| `modes` 少 `voice_instruct` | 「音色描述直出」在模型中心和声线页整个看不见,排查的人会去查 ComfyUI | `services/timbre.py:supports_instruct()`、`stores/models.ts` |
| `config_json` 少工作流节点键(`generate_full_node` / `instruct_node`) | 走到描述词分支才炸 | `providers/comfy_assets.py`(键名默认值在 `registry.comfyui_tts_config()`) |
| 已下线的模型还在包里 | 派发选中一个不存在的适配器 | `providers/registry.py` |
| ORM 新增非空列而快照没有 | `install` 抛 IntegrityError,离根因隔 40 行 traceback | `db.py:init_db()` |
所以体检把「代码比数据新」判成 **error 而不是提示**:唯一的修复动作在开发机上
(`seed.py doctor --fix` 只补缺、从不覆盖人工调过的值,然后重新 `export`),
在服务器上用 `--allow-drift` 硬闯才是合理的逃生门。三道口子共用同一个
`audit_dataset()`:`export` 前量库、`install` 前量包、`deploy.sh` 打包前量包,
不存在「导出时没说、装上才发现」的缝。
2026-11-05 第一次跑就抓到两条:`tts/comfyui/indextts2` 的 `modes` 缺
`voice_instruct`、`video/comfyui/minimax-h3` 的 `config_json` 缺
`resolution_policy`;同时清掉了快照里已下线的 `macos-say` 规格。
**回滚**:部署包不解覆盖式删除远端文件(不加 `--delete`),`.env` 与 `media/` 原地保留,
把 `.env` 指回旧目录即可回退。
@ -245,17 +286,22 @@ sudo ./scripts/server.sh systemd > /etc/systemd/system/nex-animation.service #
1. 一律 `mv` 到 `.trash/YYYY-MM-DD/<分类>/`,**禁止 `rm -rf`**。
2. 同名冲突时换目标名,不要图省事直接覆盖(本轮就有两个 `.DS_Store` 因 `mv -n` 撞名而漏清)。
3. `.trash/` 保留一个发布周期,确认无用再整体清空——清空这一步由人做,不由脚本做。
4. 数据库里的历史遗留表同理:`_bak_spec3`(一次改表手术留下的备份表)当前仍在库里,
等确认后 `DROP`,不在代码里偷偷处理。
4. 数据库里的历史遗留表同理:`_bak_spec3`(一次改表手术留下的备份表)已于 2026-11-05
先导出为 `CREATE + INSERT` 存到 `.trash/2026-11-05/db/_bak_spec3.sql`,再 `DROP`,
开发库表数与 ORM 一致(30 张)。仍然不在代码里偷偷处理:`seed.py doctor` 只把
「代码不认识的表」报成 warn 交给人决策,绝不自动 DROP——脚本偷偷删表等于把
「备份」这个唯一的退路删掉。
## 7. 改动后的最低验收
按顺序,任一步不过就不要提交:
```bash
cd backend && ../.venv/bin/python -m pytest -q # 494 passed, 1 skipped(约 3 分钟)
cd backend && ../.venv/bin/python -m pytest -q # 502 passed, 1 skipped(约 3 分钟)
bash -n scripts/*.sh # 改过脚本就必须过,shell 没有编译器兜底
# 改过 .gitignore:跑 ./scripts/deploy.sh --check,第 3 条不变量会验它没吃掉代码
# 改过 .gitignore:跑 ./scripts/deploy.sh --check,第 5 条不变量会验它没吃掉代码
# 改过模型适配器 / 工作流 / ORM 列:先量数据集,再决定要不要重新导出
.venv/bin/python scripts/seed.py doctor # 只量不改;有 error 说明导出包会比代码旧
cd frontend && npm run build # 前端类型与打包(= tsc --noEmit + vite build)
.venv/bin/python scripts/ui/vocab.py # 前端词汇表 lint(只读源码,不用起服务)
# 改过控件 / 表单 / 主题:再跑 UI 体检(前端 :5173 与后端 :8000 必须在跑)

View File

@ -1,4 +1,4 @@
import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
import { useMemo } from 'react'
import { openNode, allNodesDone } from '../../lib/pipeline'
import { cn } from '../../lib/cn'
import { FlowCaption, Steps } from '../ui/Steps'
@ -6,10 +6,12 @@ import { FlowCaption, Steps } from '../ui/Steps'
/**
* 12 节点流程条(GL-1)。
*
* 流程条比屏幕宽时以前只是「能横向滚」,但没有任何提示,
* 用户以为只有 8 个节点;而且当前节点常常在滚动区外。
* 现在:右缘渐隐提示还有内容 + 自动把「进行中 / 需处理」的节点滚进视野 +
* 节点 title 悬浮出完整说明(compact 模式也不会丢信息)。
* 这一层以前干两件事:量 rail 的 scrollWidth 决定要不要画左右渐隐,
* 以及把「进行中」的节点 scrollTo 到中间。2026-11 第十轮把 rail 换成
* 容器自适应网格(见 ui/Steps 的注释)之后两件事一起消失了——
* 网格不分页、不滚动,12 个节点在 1440 / 1024 / 576 / 430 任何一档都一次排完,
* 「当前在哪」由那一格的主色描边自己说,不需要把别的格子弹出视野。
* 现在它只剩语义:算出当前节点 + 底部那一行「已完成 x / y · 当前:xxx」。
*/
export function WorkflowBar({ workflow, compact, className }: {
workflow: any[] | null | undefined
@ -17,47 +19,13 @@ export function WorkflowBar({ workflow, compact, className }: {
className?: string
}) {
const stages = useMemo(() => workflow || [], [workflow])
const rail = useRef<HTMLDivElement | null>(null)
const [overflowing, setOverflowing] = useState(false)
const currentKey = openNode(stages)?.key || ''
const currentLabel = (stages as any[]).find((s) => s.key === currentKey)?.label || ''
const flowDone = allNodesDone(stages)
/** 只有真的需要滚的时候才显示渐隐,否则渐隐像渲染残留 */
const measure = () => {
const box = rail.current
if (box) setOverflowing(box.scrollWidth - box.clientWidth > 2)
}
useLayoutEffect(measure, [stages])
useEffect(() => {
const box = rail.current
if (typeof ResizeObserver === 'undefined' || !box) return
const ro = new ResizeObserver(measure)
ro.observe(box)
if (box.firstElementChild) ro.observe(box.firstElementChild)
return () => ro.disconnect()
}, [stages])
/** 把当前节点滚到可视区中间;只在流程变化时做一次,不打断用户手动滚动 */
useEffect(() => {
const box = rail.current
if (!box) return
const target = box.querySelector<HTMLElement>('[data-current="1"]')
if (!target) return
const left = target.offsetLeft - (box.clientWidth - target.clientWidth) / 2
box.scrollTo({ left: Math.max(0, left), behavior: 'smooth' })
measure()
}, [currentKey])
return (
<div className={cn('relative', className)}>
{overflowing && (
<>
<span aria-hidden className="pointer-events-none absolute top-0 right-0 bottom-4 w-[46px] rounded-r-lg bg-[linear-gradient(90deg,rgba(0,0,0,0),var(--ant-color-bg-container))]" />
<span aria-hidden className="pointer-events-none absolute top-0 left-0 bottom-4 w-[22px] rounded-l-lg bg-[linear-gradient(270deg,rgba(0,0,0,0),var(--ant-color-bg-container))]" />
</>
)}
<Steps ref={rail} nodes={stages} currentKey={currentKey} compact={compact} scrollSmooth />
<div className={cn('min-w-0', className)}>
<Steps nodes={stages} currentKey={currentKey} compact={compact} />
{!!stages.length && <FlowCaption nodes={stages} current={currentKey ? currentLabel : ''} allDone={flowDone} />}
</div>
)

View File

@ -65,7 +65,7 @@ export function Tag({ tone = 'default', size = 'md', icon, children, className,
style={style} bordered={false}>
{v ? <span className="nex-tag-dot" aria-hidden /> : null}
{icon && <span className="nex-tag-icon" aria-hidden>{icon}</span>}
{children}
<span className="nex-tag-text">{children}</span>
</AntTag>
)
}
@ -118,7 +118,7 @@ export function Badge({ children, tone = 'default', size = 'md', className }: {
const style = v ? { color: `var(--ant-color-${v})` } : undefined
return (
<AntTag className={cn('nex-tag nex-badge', size === 'sm' && 'nex-tag-solo-sm', className)} style={style} bordered={false}>
{children}
<span className="nex-tag-text">{children}</span>
</AntTag>
)
}

View File

@ -1,12 +1,13 @@
import { forwardRef, type ReactNode } from 'react'
import { type ReactNode } from 'react'
import { cn } from '../../lib/cn'
import { IconCaution, IconCheck, IconPlay } from '../icons'
/**
* 流程节点条里的「一格」(全站唯一一份:WorkflowBar 与项目列表、概览共用)。
*
* 宽度下限只有 min-w-[96px] 一个:这里不能再挂 min-w-0——cn() 走 tailwind-merge,
* 同一个 min-width 组只留最后一个,1280 下节点被压到 10px、序号圆点溢出 6px。
* 内部要缩的字段各自带 min-w-0(进度那一行),外层交给 Steps 的 overflow-x-auto 滚动。
* 宽度完全交给 Steps 的网格轨道(`.nex-steps` 的 auto-fill minmax),格子只留一个
* min-w-0:让内部要缩的字段(进度那一行的 truncate)能真的缩,而不是把格子捅破。
* 以前这里是 `flex-1 basis-[118px] min-w-[96px]` 的自然排列,12 格在任何宽度下都
* 放不下,只能整条横向滚——见 Steps 上面的注释里那组实测数。
*
* 节点状态口径来自 lib/pipeline.ts:done / active / failed / pending。
* 「当前节点」只有 openNode() 一个算法——以前五个地方各算各的,草稿项目会喊
@ -58,20 +59,17 @@ const NUM: Record<string, string> = {
pending: 'bg-fill-secondary text-text-tertiary'
}
export function Step({ node, index, current, compact, onClick, className }: {
export function Step({ node, index, current, compact, className }: {
node: any
index: number
current?: boolean
compact?: boolean
onClick?: (node: any) => void
className?: string
}) {
const st = node.state === 'done' ? 'done' : node.state === 'failed' ? 'failed' : node.state === 'active' ? 'active' : 'pending'
return (
<div role="listitem" title={nodeHint(node)} data-current={current ? '1' : undefined}
onClick={onClick ? () => onClick(node) : undefined}
className={cn('flex-1 basis-[118px] min-w-[96px] bg-bg-container border rounded-lg py-2 px-3 relative transition-colors',
onClick && 'cursor-pointer',
<div role="listitem" title={nodeHint(node)}
className={cn('min-w-0 bg-bg-container border rounded-lg py-2 px-3 relative transition-colors',
current && 'shadow-[0_0_0_1px_var(--ant-color-primary-border)]',
st === 'done' && 'border-border-secondary',
st === 'active' && 'border-primary-border bg-primary-bg shadow-[inset_0_0_0_1px_var(--ant-color-primary-border)]',
@ -92,29 +90,46 @@ export function Step({ node, index, current, compact, onClick, className }: {
)
}
export const Steps = forwardRef<HTMLDivElement, {
/** 网格轨道下限(px):完整档要装下「导入分镜图与脚本」8 个汉字 + 左右内边距 */
const STEP_MIN = { full: 140, compact: 128 }
/**
* 12 节点流程条的容器:一张**容器自适应的网格**,不是横向滚动的自然排列。
*
* 症状(2026-11 第十轮实测,`minmax` 之前 `flex-1 basis-[118px] min-w-[96px]`):
* 12 格 × 96 + 11 × 8 = 1244px,任何宽度都放不下,于是整条只能横向滚,
* 并且 WorkflowBar 会把「进行中」那一格滚进视野——项目概览 1440 档
* scrollLeft=126(第 1 格被切掉一半)、1024 档 542(前 5 格根本看不见)、
* 430 档 943(只剩最后 3 格);总控台那条 526px 宽,溢出 718px=12 格里
* 9 格在视野外。底部明明写着「已完成 10 / 12 个节点」,屏幕上却只有 4 格。
* 96px 的格子还让中文标题折成「任务队列调 / 度」「导出完整视 / 频」这种断句。
* 做法:`repeat(auto-fill, minmax(var(--nex-step-min), 1fr))`(见 app.css `.nex-steps`)。
* 轨道按**容器**宽度分列而不是按视口,所以同一条 rail 在项目页 1118px 里
* 给到 7 列 2 排、在总控台 526px 的半栏里给到 3 列、在 430 手机档给到 2 列,
* 每一格都放得下标题,12 个节点一次全部可见,没有滚动、没有渐隐、没有裁切。
* 为什么不用 antd Row/Col:Col 的断点读的是**视口**,总控台那条坐在半栏网格里
* (视口 1440 → xl 档 → 8 列 ÷ 半栏 = 每格 60px),只有容器宽度的 auto-fill
* 能同时喂饱这两种容器;Row/Col 是页面级 24 栅格,这里是卡片内的一条 rail。
*/
export function Steps({ nodes, currentKey, compact, className }: {
nodes: any[]
currentKey?: string
/** 精简档:只排标题与状态(总控台那条坐在半栏里),格子窄一档 */
compact?: boolean
onStep?: (node: any, at: number) => void
className?: string
id?: string
scrollSmooth?: boolean
}>(function Steps({ nodes, currentKey, compact, onStep, className, id, scrollSmooth }, ref) {
/* ref 指的就是这块横向滚动容器:WorkflowBar 要量它、并把当前节点滚进视野。
React 18 里它必须是 forwardRef 的第二参数——写成普通 prop 会静默拿到 undefined
(症状见 lib/ref.ts),流程条就再也不跟着当前节点走,编译器一声不吭。 */
}) {
const list = nodes || []
return (
<div ref={ref} id={id} role="list"
className={cn('flex gap-2 overflow-x-auto scrollbar-slim pt-1 pr-0.5 pb-3 pl-0.5', scrollSmooth && 'scroll-smooth', className)}>
<div role="list" className={cn('nex-steps pt-1 pb-3', className)}
/* 网格轨道的下限:写在元素上而不是拆成两条类名,档位和组件的 compact 语义只有一个来源 */
style={{ ['--nex-step-min' as string]: `${compact ? STEP_MIN.compact : STEP_MIN.full}px` }}>
{(list.length ? list : [{ state: 'pending', label: '暂无流程数据' }]).map((n: any, at: number) => (
<Step key={n.key ?? at} node={n} index={at} compact={compact} current={!!currentKey && n.key === currentKey}
onClick={onStep && list.length ? (node) => onStep(node, at) : undefined} />
<Step key={n.key ?? at} node={n} index={at} compact={compact}
current={!!currentKey && n.key === currentKey} />
))}
</div>
)
})
}
/** 流程条底部那一行「已完成 x / y · 当前:xxx」;全绿时不再报最后一个节点名 */
export function FlowCaption({ nodes, current, allDone, className }: {

View File

@ -42,8 +42,8 @@ import { RecordAudio, type RecordPickMeta } from '../components/media/RecordAudi
import { useAutoRefresh } from '../hooks'
import { useRecordingBusy } from '../stores/recording'
import { confirmAction } from '../stores/confirm'
import { ActionGroup, BarRight, Between, Block, Button, CardActions, Check, Checkbox, Chip, ChipBar, Ctlbar, Drawer, Empty, ErrorText, Field, FieldBlock, FilePick, FormGrid, FormRow, Grid, Input, LINK_CLS, MONO, MUTED, MUTED_MONO, Modal, Notice, NumberInput, PageHead, Pager, Panel, PanelHead, Row, SearchInput, SectionTitle, Spinner, Stat, StatGrid, Tabs, Tag, TagGroup, TextArea, Tile, Value, ViewSwitch } from '../components/ui'
import { IconAdd, IconBlocks, IconBolt, IconCheck, IconUpload, IconClose, IconDelete, IconEdit, IconGrid, IconImage, IconLibrary, IconList, IconRobot, IconSound, IconTag, IconUser, IconVoice } from '../components/icons'
import { ActionGroup, BarRight, Between, Block, Button, CardActions, Check, Checkbox, Chip, ChipBar, Ctlbar, Drawer, Empty, ErrorText, Field, FieldBlock, FilePick, FormGrid, FormRow, Grid, Input, LINK_CLS, MONO, MUTED, MUTED_MONO, Modal, Notice, NumberInput, PageHead, Pager, PageStack, Panel, PanelHead, Row, SearchInput, SectionTitle, Spinner, Stat, StatGrid, Tabs, Tag, TagGroup, TextArea, Tile, Value, ViewSwitch } from '../components/ui'
import { IconAdd, IconBlocks, IconBolt, IconCaution, IconCheck, IconClose, IconCopy, IconDelete, IconEdit, IconGrid, IconImage, IconLibrary, IconList, IconRobot, IconSound, IconTag, IconUpload, IconUser, IconVoice } from '../components/icons'
type AssetType = 'human' | 'scene' | 'voice'
type ViewMode = 'grid' | 'list' | 'media'
@ -83,15 +83,6 @@ const GENDERS = [
{ value: '', label: '未指定' }, { value: 'female', label: '女声' },
{ value: 'male', label: '男声' }, { value: 'neutral', label: '中性' }
]
/**
* 「外星低吼」是 macOS 系统语音适配器的滤镜参数,IndexTTS2 等模型会忽略它。
* 后端整字典覆盖 tuning,已保留的采样率等参数不会被这次保存清掉。
*/
const EFFECTS = [
{ value: '', label: '真实人声' },
{ value: 'alien', label: '外星低吼(仅 macos-say 支持)' }
]
const VIEW_ITEMS: { value: ViewMode; label: ReactNode; hint: string }[] = [
{ value: 'grid', label: <><IconGrid />网格</>, hint: '网格视图:卡片信息最全' },
{ value: 'list', label: <><IconList />列表</>, hint: '列表视图:一屏看更多母版,便于批量勾选' },
@ -106,7 +97,7 @@ function blankForm(kind: AssetType) {
tags: '', notes: '', is_active: true, description: '', prompt: '', lighting: '',
time_of_day: '', palette: '', provider: '',
provider_voice_id: '', language: 'zh-CN', gender: '', version: 'v1',
is_default: false, tuning: {} as Record<string, any>, tuning_speed: 1, tuning_effect: ''
is_default: false, tuning: {} as Record<string, any>, tuning_speed: 1
}
}
type MasterForm = ReturnType<typeof blankForm>
@ -187,8 +178,9 @@ function provenanceBadge(media: any) {
/**
* 音色自检标记。后端生成试听时会量一次中位基频,和声线设定的性别比对
* (见 services/timbre.py):zero-shot 克隆模型只认参考音频,表单里填「男声」
* 并不会让它变成男声,所以必须由界面把实测结论摊开说,而不是让用户自己听出来。
* (见 services/timbre.py):克隆路径只认参考音频,表单里填「男声」并不会让它变成男声,
* 所以必须由界面把实测结论摊开说,而不是让用户自己听出来。
* 描述词直出的音色确实由描述决定,但同样要量:描述词写「男声」出成女声也是失败。
*/
function timbreBadge(media: any): { tone: 'ok' | 'bad' | 'warn'; label: string; title: string } | null {
const check = media?.metadata?.timbre_check
@ -555,7 +547,6 @@ export default function AssetLibrary() {
tags: (row.tags || []).join(' '),
tuning: { ...(row.tuning || {}) },
tuning_speed: Number(row.tuning?.speed || 1),
tuning_effect: row.tuning?.params?.effect || ''
})
setDrawer(true)
setNotice('')
@ -577,11 +568,11 @@ export default function AssetLibrary() {
time_of_day: form.time_of_day, palette: form.palette
}
}
// tuning 是整字典覆盖:先保留后端已有键(如 sample_rate),再改界面能控制的两项
// tuning 是整字典覆盖:先保留后端已有键(如 sample_rate),再改界面能控制的那一项。
// 「效果 / alien」随 macos-say 一起退役:IndexTTS2 没有这个滤镜,
// 旧数据里残留的键原样保留,不再由表单写回。
const base = { ...(form.tuning && typeof form.tuning === 'object' ? form.tuning : {}) }
const params = { ...((base.params as Record<string, any>) || {}) }
if (form.tuning_effect) params.effect = form.tuning_effect
else delete params.effect
return {
...common, provider: form.provider, provider_voice_id: form.provider_voice_id,
language: form.language, gender: form.gender, description: form.description,
@ -883,7 +874,14 @@ export default function AssetLibrary() {
}
}
function voiceHasReference(row: any) {
/**
* 这条声线现在能不能出音(第 4 点):参考音频克隆 **或** 音色描述直出,两条路任一成立即可。
*
* 以前只有「有没有参考音频」一条路,没录过音的角色点生成就被拦下,
* 用户只能随便塞一段音频凑数。IndexTTS2 登记了 `voice_instruct`,
* 声线填了「音色描述」后端就走描述词直出(source=instruct),界面必须放行。
*/
function voiceHasTimbre(row: any) {
const draft = draftOf(row)
const caps = specCaps(row)
if (!caps.requiresReference || draft.reference_media_id) return true
@ -891,6 +889,7 @@ export default function AssetLibrary() {
// 实际不能当克隆参考(否则错音色会自我强化),按钮必须跟后端口径一致。
if (voiceRefStatus) return !!voiceRefStatus.ready
if (isAudioPath(row.provider_voice_id)) return true
if (caps.voiceInstruct && String(row.description || '').trim()) return true
return !!generationSpec(row)?.config?.reference_audio
}
@ -957,8 +956,9 @@ export default function AssetLibrary() {
setError('请先填写试听文本:它是模型要朗读的台词,「音色描述」是声线设定,不会被念出来')
return
}
if (type === 'voice' && specCaps(row).requiresReference && !voiceHasReference(row)) {
setError('该声线模型需要参考音色,请上传参考音频或使用模型默认参考音频')
if (type === 'voice' && specCaps(row).requiresReference && !voiceHasTimbre(row)) {
setError('这条声线还没有可用的音色:上传一段参考音频做克隆,'
+ '或先在声线里填写「音色描述」用描述词直出')
return
}
const body: any = type === 'voice'
@ -998,6 +998,7 @@ export default function AssetLibrary() {
return (
<div className="min-w-0">
<PageStack>
<PageHead
title={<span title="人物、场景与声线在这里沉淀为可复用母版;项目可随时引入快照,已锁定的版本会随生成记录一起留痕。">平台资产库</span>}
actions={<Button type="primary" onClick={openCreate} icon={<IconAdd />}>新建{typeMeta.label}</Button>}
@ -1009,20 +1010,20 @@ export default function AssetLibrary() {
{/* AS-7:四张卡本身就是筛选入口,数字点下去就到对应视角,不用先去翻筛选下拉。
窄屏收列走断点变体(4 → ≤1180 两列 → ≤820 一列 → 手机上再并回两列,
四行竖条在一屏里等于整页都是统计卡)。 */}
<StatGrid cols={4} className="mb-4" steps={[{ at: 'xl', cols: 2 }, { at: 'lg', cols: 1 }, { at: 'sm', cols: 2 }]}>
<Stat tone="lead" label="母版资产" value={totals.human + totals.scene + totals.voice}
<StatGrid>
<Stat tone="lead" icon={<IconLibrary />} label="母版资产" value={totals.human + totals.scene + totals.voice}
title="查看全部母版:清空筛选并回到网格视图"
active={view !== 'media' && !filtersActive} onClick={focusMasters}
hint={`人物 ${totals.human} · 场景 ${totals.scene} · 声线 ${totals.voice}`} />
<Stat label="已登记素材" value={totals.media}
<Stat icon={<IconBlocks />} label="已登记素材" value={totals.media}
title="切换到跨母版的「全部素材」视角,直接翻找图片与音频"
active={view === 'media'} onClick={focusWall}
hint={`${fmtBytes(stats.media_bytes || 0)} · ${stats.versions || 0} 个版本 · 平均 ${mediaAverageKb} KB/个`} />
<Stat label="待补素材" value={stats.without_media || 0}
<Stat icon={<IconCaution />} label="待补素材" value={stats.without_media || 0}
title="只看还没有任何素材的母版(补齐定妆图 / 试听样本)"
active={filters.has_media === 'without' && view !== 'media'} onClick={focusWithout}
hint="母版已建档,但一张图 / 一段音都没有" />
<Stat tone="warn" label="疑似重复" value={stats.duplicate_masters || 0}
<Stat tone="warn" icon={<IconCopy />} label="疑似重复" value={stats.duplicate_masters || 0}
title="同名或同代号的母版分组,建议人工确认后合并"
active={filters.duplicate_only && view !== 'media'} onClick={focusDuplicates}
hint={`${stats.duplicate_groups || 0} 组同名 / 同代号 · 已引用母版 ${stats.referenced || 0}`} />
@ -1030,7 +1031,7 @@ export default function AssetLibrary() {
{/* 大分类 = 页面内部页签(三类的母版/素材是三个内部页面,不是同一批数据换排法)。
新增一类只改 TYPE_META;每类的 hint 落在页签的 title 上,不额外占版面。 */}
<Tabs className="mt-1" activeKey={type} onChange={(k) => chooseType(k as AssetType)}
<Tabs activeKey={type} onChange={(k) => chooseType(k as AssetType)}
items={TYPE_KEYS.map((key) => ({
key,
label: TYPE_META[key].label,
@ -1058,7 +1059,9 @@ export default function AssetLibrary() {
{/* 筛选栏:坐在卡正文里,不再自己描边(站内有边框的横块只有 Card 一种)。
「每页」不在这里——分页条是 page_size 唯一的家(UI规范 §5)。 */}
<Ctlbar className="mb-1">
{/* 5 个同类筛选字段=栅格(R7:三个以上同类字段并排必须铺列)。
自然排列时它们是 330 / 170 / 170 / 142 / 177——标签字数不同盒子就参差。 */}
<Ctlbar className="mb-1" cols={5}>
<Field inline label="搜索" width="grow" title="跨字段匹配名称、代号、设定、提示词与标签">
<SearchInput value={search} onChange={(e) => setSearch(e.target.value)} aria-label="搜索平台资产" placeholder="名称 / 代号 / 设定 / 提示词 / 标签(跨字段)" />
</Field>
@ -1171,7 +1174,7 @@ export default function AssetLibrary() {
<div className="grid gap-2 grid-cols-[repeat(auto-fill,minmax(148px,1fr))] min-w-0 [&>*]:min-w-0">
{wall.items.map((media: any, idx: number) => (
<Tile key={media.id} as="div" variant="pick" active={selectedMedia.has(media.id)}
className="relative flex-col items-start gap-1 p-2">
className="relative flex-col items-stretch gap-1 p-2">
<MediaPick title="勾选后可批量删除(Shift 范围选择)" className="left-[12px] top-[12px]">
<Checkbox checked={selectedMedia.has(media.id)}
onClick={(e) => { e.stopPropagation(); toggleMedia(media, idx, e.shiftKey) }} />
@ -1287,13 +1290,16 @@ export default function AssetLibrary() {
))}
</div>
) : (
/* 网格视图:卡片信息最全,一屏两张 */
<Grid cols={2} gap={10} oneAt="xl">
/* 网格视图:卡片信息最全,一屏两张。
[&>.ant-col>*]:h-full 把同一行两张卡拉到同一高度——Col 会被 Row 拉伸,
差的是卡自己没有 height:100%。不拉平的话左卡三行设定、右卡一行,
两张卡的标签行与素材条各排在不同高度(用户说的「不对齐」有一半是这里)。 */
<Grid cols={2} gap={10} oneAt="xl" className="[&>.ant-col>*]:h-full">
{rows.map((row: any, idx: number) => {
const audios = (row.assets || []).filter(isAudio)
return (
<Tile key={row.id} as="div" variant="pick" active={isSelected(row)}
className={cn('relative flex-col items-start gap-0 p-4',
className={cn('relative flex-col items-stretch gap-3 p-4',
row.duplicate_of?.length && 'border-warning-border')}>
<MediaPick title={isSelected(row) ? '取消选择' : '勾选后可批量引入 / 打标签 / 删除(Shift 范围选择)'}>
<Checkbox checked={isSelected(row)}
@ -1323,7 +1329,7 @@ export default function AssetLibrary() {
{row.persona_prompt || row.appearance || row.description || row.prompt || row.voice_profile || '尚未填写设定。'}
</p>
<TagGroup size="sm" className="mb-0">
<TagGroup size="sm" className="!mb-0">
{(row.tags || []).slice(0, 5).map((tag: string) => (
<Chip key={tag} size="sm" title={`只看标签「${tag}」`}
onClick={() => patchFilters({ tag })}>{tag}</Chip>
@ -1332,9 +1338,14 @@ export default function AssetLibrary() {
{type === 'human' && !!row.default_voice_name && (
<Tag title={`默认声线:${row.default_voice_name}`}>声线 · {row.default_voice_name}</Tag>
)}
{type === 'scene' && (
<Tag>{[row.lighting, row.time_of_day, row.palette].filter(Boolean).join(' · ') || '未设定光线'}</Tag>
)}
{type === 'scene' && (sceneMeta(row).length
// 一格一枚:整句「光线」和「白天 · 原木暖调」缝成一枚标签时,
// 这枚标签能长到 600px 以上,把整行挤到只剩它自己。
// 拆开后短句各归各的,长句由 kit 的 ellipsis 收尾(悬停看全文)。
? sceneMeta(row).map((m: any) => (
<Tag key={m.k} title={`${m.k}:${m.v}`}>{m.v}</Tag>
))
: <Tag tone="warn">未设定光线</Tag>)}
{type === 'voice' && <Tag>{row.provider || '生成时选模型'} · {row.language || 'zh-CN'}</Tag>}
<ScopeTag row={row} />
<Tag title={`共 ${row.media_count} 个素材,占 ${fmtBytes(row.media_bytes)}`}>
@ -1343,7 +1354,7 @@ export default function AssetLibrary() {
</TagGroup>
{!!stripOf(row).length && (
<div className="mt-3 grid grid-cols-4 gap-1 max-sm:grid-cols-2 min-w-0 [&>*]:min-w-0">
<div className="grid grid-cols-4 gap-1 max-sm:grid-cols-2 min-w-0 [&>*]:min-w-0">
{stripOf(row).map((media: any) => (
<MediaTile key={media.id} media={media} size="sm"
queue={itemsOf(row)} index={mediaIndex(row, media)}
@ -1356,7 +1367,7 @@ export default function AssetLibrary() {
const provenance = provenanceBadge(media)
return (
<div key={`audio-${media.id}`}
className="flex items-center gap-1 mt-1.5 min-w-0">
className="flex items-center gap-1 min-w-0">
<div className="flex-1 min-w-0">
<AudioPlay src={media.url} size="sm" label={media.name || media.kind_label}
durationMs={media.duration_ms} hint={versionHint(media)} />
@ -1381,12 +1392,17 @@ export default function AssetLibrary() {
)
})}
{!row.assets?.length && (
<div className="mt-3 grid place-items-center min-h-[55px] px-2 rounded-md border border-dashed border-border-secondary text-text-quaternary text-xs text-center">
暂无素材:用下方「AI 生成」出图 / 出试听,或直接上传现成文件。
<div className="flex min-h-[46px] items-center gap-2 rounded-md bg-fill-secondary px-3 py-2 text-xs leading-normal text-text-quaternary">
<IconImage className="flex-none" />
<span className="min-w-0">暂无素材:用下方「AI 生成」出图 / 出试听,或直接上传现成文件。</span>
</div>
)}
<CardActions className="mt-auto pt-3 border-t border-fill-secondary">
{/* 动作在左、版本元数据在右:钉成两列栅格。
以前靠 BarRight 的 ml-auto 自然排列,一超宽那段元数据就独自
折到第二行的最右端(实测左边缘比同排按钮低 310px),像掉出去的孤儿。 */}
<div className="mt-auto grid grid-cols-[minmax(0,1fr)_auto] items-center gap-x-3 gap-y-2 border-t border-fill-secondary pt-3 max-lg:grid-cols-1">
<CardActions className="!mt-0">
<Button type="primary" onClick={() => openGenerate(row)} icon={<IconBolt />}>
{isVoice ? '生成试听' : 'AI 生成'}
</Button>
@ -1410,11 +1426,12 @@ export default function AssetLibrary() {
<Button icon={<IconLibrary />} onClick={() => openImportSelection(row)}>引入项目</Button>
<Button icon={<IconDelete />} type="text" danger title="删除这个资源" onClick={() => setConfirmDelete(row)} aria-label="删除这个资源" />
</ActionGroup>
{/* 版本 / 更新时间是元数据,不是动作:靠右自成一段,别混在动作流里被挤上换行 */}
<BarRight className={STAMP}>
</CardActions>
{/* 版本 / 更新时间是元数据,不是动作:坐在右列,永远不换到动作下面 */}
<span className={cn(STAMP, 'max-lg:justify-self-start')}>
{row.style_version || row.version || 'v1'} · 更新于 {fmtAgo(row.updated_at)}
</BarRight>
</CardActions>
</span>
</div>
</Tile>
)
})}
@ -1434,6 +1451,7 @@ export default function AssetLibrary() {
onPage={(next) => patchWall({ page: next })} />
)}
</Panel>
</PageStack>
{/* ── 新建 / 编辑母版 ────────────────────────────────────────
抽屉而不是模态:这个表单最长有 11 个字段,模态里滚到一半就会把「保存」
@ -1532,12 +1550,7 @@ export default function AssetLibrary() {
<Field label="语速">
<NumberInput min={0.5} max={2} step={0.05} value={form.tuning_speed} onChange={ (v) => patchForm({ tuning_speed: v })} />
</Field>
<Field label="效果" title={EFFECT_HINT}>
<Select value={form.tuning_effect} options={EFFECTS}
onChange={(next) => patchForm({ tuning_effect: String(next ?? '') })}
ariaLabel="声音效果" />
</Field>
<Check className="self-end h-8" checked={form.is_default}
<Check checked={form.is_default}
onChange={(next) => patchForm({ is_default: next })}>
设为平台默认声线
</Check>
@ -1683,34 +1696,41 @@ export default function AssetLibrary() {
names={existingNames(genTarget.assets)}
hint="弹出小面板:对着麦克风念几句话即可当作克隆参考,录完自动转成 WAV"
onPick={(file, meta) => void recordReference(genTarget, file, meta)} />
{voiceRefBusy && <div className={cn(REF_FULL, REF_STATUS, 'text-text-quaternary')}>正在确认这次会用谁的嗓子…</div>}
{!voiceRefBusy && voiceRefStatus && (
<div className={cn(REF_FULL, REF_STATUS,
!voiceRefStatus.ready && REF_BAD,
(voiceRefStatus.borrowed || voiceRefStatus.bound_generated) && REF_WARN)}>
<b>本次音色:{voiceRefStatus.note}</b>
{voiceRefStatus.bound_generated
? <small>
这条声线现在挂着的是<b>模型生成的试听样本</b>,不是真人录音:可以拿去给镜头配音,
但不能反过来当克隆参考,否则第一次生成错了性别,之后每次重试都会继续克隆那个错的嗓子。
上传一段{voiceRefStatus.gender_label}真人参考音频就能固定成这个角色自己的音色。
</small>
: <small>
设定性别:{voiceRefStatus.gender_label}。音色由参考音频决定,「性别 / 音色描述」只是标注——
要给这个角色一副自己的嗓子,请上传一段同性别参考音频。
</small>}
</div>
)}
{/* 「这次会用谁的嗓子」原先是自绘灰盒(描边 + bg-bg-container + 三套 tone 常量),
和旁边的输入框一个长相。换成 antd Alert:底色 / 图标 / 语义色由主题给,
正文(为什么会被借走、怎么固定成自己的音色)走 description 的第二层。 */}
{voiceRefBusy
? <Value muted className={cn('block', REF_FULL)}><Spinner /> 正在确认这次会用谁的嗓子…</Value>
: voiceRefStatus && (
<Notice className={cn('!mb-0', REF_FULL)}
type={!voiceRefStatus.ready ? 'error'
: (voiceRefStatus.borrowed || voiceRefStatus.bound_generated) ? 'warning' : 'success'}
description={voiceRefStatus.bound_generated
? <>这条声线现在挂着的是<b>模型生成的试听样本</b>,不是真人录音:可以拿去给镜头配音,
但不能反过来当克隆参考,否则第一次生成错了性别,之后每次重试都会继续克隆那个错的嗓子。
上传一段{voiceRefStatus.gender_label}真人参考音频就能固定成这个角色自己的音色。</>
: voiceRefStatus.instruct
? <>这条声线没有参考音频,本次走<b>音色描述直出</b>:
音色由「{voiceRefStatus.instruct_text || '声线里填的音色描述'}」决定。
想更稳地固定成一副嗓子,仍可上传一段真人参考音频做克隆。</>
: <>设定性别:{voiceRefStatus.gender_label}。参考音频决定底色,
「音色描述」在克隆之上做偏移——要给这个角色一副自己的嗓子,
请上传一段同性别参考音频。</>}>
本次音色:{voiceRefStatus.note}
</Notice>
)}
<small className={REF_HINT}>
需要参考音频的模型(如 IndexTTS2)用参考音频做 zero-shot 音色克隆;
设定了性别却没有任何同性别参考时,平台会直接拒绝生成,而不是悄悄给你一个陌生人的嗓门。
IndexTTS2 有两条定音色的路:上传参考音频做 zero-shot 克隆,
或只填声线的「音色描述」由描述词直出(描述词走全参节点 + 音色描述节点,
模型默认参考只作底声锚点)。两条都没有时平台会直接拒绝生成,
而不是悄悄给你一个陌生人的嗓门。
</small>
</div>
)}
<Button type="primary" size="sm"
disabled={!!busy || !genModels.length || !generationSpec(genTarget)
|| (isVoice && (!String(draft.sample_text || '').trim() || !voiceHasReference(genTarget)))}
|| (isVoice && (!String(draft.sample_text || '').trim() || !voiceHasTimbre(genTarget)))}
onClick={() => void generate(genTarget)} loading={!!busy}
icon={isVoice ? <IconVoice /> : <IconImage />}>
{isVoice ? '生成试听样本' : '生成母版图像'}
@ -1720,14 +1740,14 @@ export default function AssetLibrary() {
{/* 注册表不在首屏:所以这里必须解释「为什么模型下拉是空的」,
否则用户只会看到一个空下拉,以为平台没接模型。 */}
{registryError
? <small className={PROVIDER_WARN}>模型注册表读取失败:{registryError}</small>
? <Notice className="mt-2 !mb-0" type="error">模型注册表读取失败:{registryError}</Notice>
: registryBusy
? <small className={PROVIDER_WARN}>正在读取模型注册表…</small>
? <Notice className="mt-2 !mb-0" type="info"><Spinner /> 正在读取模型注册表…</Notice>
: !genModels.length
? <small className={PROVIDER_WARN}>
? <Notice className="mt-2 !mb-0" type="warning">
当前没有已启用的真实{isVoice ? '声音' : '图像'}模型(mock 演练通道不出正式素材),请先到{' '}
<Link to="/models" className={LINK_CLS}>模型中心</Link> 启用。
</small>
</Notice>
: null}
</FormGrid>
</Panel>
@ -1943,9 +1963,13 @@ function MediaTile({ media, size = 'sm', radius, width, queue, index, onRemove }
const FILE_TILE = 'flex flex-col justify-between p-2 rounded-md bg-fill-tertiary '
+ '[&>b]:text-text-secondary [&>b]:text-xs [&>span]:text-text-quaternary [&>span]:text-xs'
const SUMMARY = 'line-clamp-3 min-h-[46px] mt-3 mb-2 text-xs leading-normal text-text-tertiary'
const SUMMARY = 'line-clamp-3 min-h-[46px] text-xs leading-normal text-text-tertiary'
/** 场景卡的「光线 / 时段 / 色板」:散文级的光线单独成枚,短字段各成一枚 */
const sceneMeta = (row: any) => [['光线', row.lighting], ['时段', row.time_of_day], ['色板', row.palette]]
.filter(([, v]: any) => !!v).map(([k, v]: any) => ({ k, v }))
/** 卡片右下角的「哪一版 / 什么时候改的」:等宽 + 截断,不参与挤压标题 */
const STAMP = 'ml-auto min-w-0 max-w-[140px] truncate font-mono text-xs text-text-quaternary'
const STAMP = 'min-w-0 max-w-[140px] truncate font-mono text-xs text-text-quaternary'
/** 确认框里那段「动的是什么」:左边一条重色竖线,比整块描边更像一个引用块 */
const IMPORT_SUBJECT = 'my-4 py-3 px-3 border-l-2 border-l-primary bg-bg-container text-text-tertiary text-xs '
+ 'leading-relaxed [&_b]:text-primary-hover'
@ -1953,8 +1977,7 @@ const IMPORT_SUBJECT = 'my-4 py-3 px-3 border-l-2 border-l-primary bg-bg-contain
const DIALOG_LIST = 'flex flex-col gap-1 max-h-[258px] overflow-y-auto m-0 p-0 list-none '
+ '[&>li]:flex [&>li]:items-center [&>li]:gap-2 [&>li]:flex-wrap [&>li]:py-2 px-2 '
+ '[&>li]:border [&>li]:border-fill [&>li]:rounded-md [&>li]:bg-bg-container [&>li>b]:text-xs'
const PROVIDER_WARN = 'block mt-2 py-2 px-2 border border-warning-border rounded-sm bg-warning-bg text-warning '
+ 'text-xs leading-normal'
/* 注册表状态不再自拼告警条:统一走 Notice(antd Alert),底色与图标由主题给 */
/**
* 参考素材区(图 / 音共用)。
*
@ -1966,12 +1989,9 @@ const REF_BOX = 'flex items-end flex-wrap gap-2 mt-2 p-2 border border-border ro
/** 参考区里的上传按钮:绿色描边表示「这一步不会改母版本体,只是喂料」 */
const REF_PICK = 'justify-center border-primary-border text-primary'
const REF_HINT = 'basis-full text-text-quaternary text-xs leading-normal'
/** 参考区里的整行元素(状态盒) */
/** 参考区里需要顶满一行的元素(Alert / 说明行) */
const REF_FULL = 'basis-full'
const REF_STATUS = 'grid gap-1 py-2 px-2 rounded-md border border-border bg-bg-container text-xs '
+ '[&>b]:text-xs [&>b]:leading-normal [&>small]:text-text-quaternary [&>small]:leading-normal'
const REF_WARN = 'border-warning-border bg-warning-bg [&>b]:text-warning-hover'
const REF_BAD = 'border-error-border bg-error-bg [&>b]:text-error'
/* 音色状态不再自绘灰盒:REF_STATUS / REF_WARN / REF_BAD 三件套已并入 antd Alert(Notice) */
/** 「没有可用模型」这句话在标签、占位符、警告里出现三次,措辞必须一致 */
const noModelHint = (voice: boolean) => `没有已启用的真实${voice ? '声音' : '图像'}模型`
@ -1981,5 +2001,3 @@ const KIND_CHOICES: Record<'human' | 'scene', { value: string; label: string }[]
{ value: 'expression', label: '表情参考' }],
scene: [{ value: 'scene_image', label: '场景图' }, { value: 'reference', label: '氛围图' }]
}
const EFFECT_HINT = '「外星低吼」是 macOS 系统语音适配器的滤镜参数,IndexTTS2 等模型会忽略它;'
+ '后端整字典覆盖 tuning,已保留的采样率等参数不会被这次保存清掉。'

View File

@ -18,11 +18,11 @@ import { fmtAgo, fmtSeconds } from '../lib/format'
import { useAutoRefresh } from '../hooks'
import { cn } from '../lib/cn'
import { EyeIcon, SecretInput, Select } from '../components/forms'
import { Between, Block, Button, CardActions, Check, Chip, ChipBar, Ctlbar, Dense, Drawer, Empty, Field, FieldBlock, FormGrid, FormRow, Grid, IconText, Input, Layout, LinkButton, MONO, MUTED, Notice, NumberInput, PageHead, Panel, PanelHead, Row, SearchInput, SectionTitle, Slider, Spinner, Stat, StatGrid, Tabs, Tag, TagGroup, TextArea, Tile, Value } from '../components/ui'
import { ActionGroup, Between, Block, Button, CardActions, Check, Chip, ChipBar, Dense, Drawer, Empty, Field, FieldBlock, FormGrid, FormRow, Grid, IconText, Info, Input, Layout, LinkButton, MONO, MUTED, Notice, NumberInput, PageHead, PageStack, Panel, PanelHead, Row, SearchInput, SectionTitle, Slider, Spinner, Stat, StatGrid, Tabs, Tag, TagGroup, TextArea, Tile, Value } from '../components/ui'
import { useAuthStore } from '../stores/auth'
import { confirmAction } from '../stores/confirm'
import { useProjectStore } from '../stores/project'
import { IconAdd, IconBolt, IconChart, IconCheck, IconChevronUp, IconClose, IconDelete, IconGrid, IconImage, IconNodeIndex, IconParams, IconPlayCircle, IconReload, IconVoice, IconWarn } from '../components/icons'
import { confirmAction } from '../stores/confirm'
import { IconAdd, IconApi, IconBolt, IconChart, IconCheck, IconChevronDown, IconChevronUp, IconClose, IconDelete, IconGrid, IconImage, IconNodeIndex, IconParams, IconPlayCircle, IconReload, IconShield, IconStar, IconVoice, IconWarn } from '../components/icons'
/** /api/providers 还没回来(或后端挂了这个接口)时左栏仍要能渲染 */
const FALLBACK_TYPES = ['llm', 'video', 'image', 'tts']
@ -407,10 +407,14 @@ export default function ModelCenter() {
setError(`高级 JSON 格式错误:${exc.message}`)
return
}
/* 模型编码从表单里收进了「高级字段」,留空时按「适配器:能力:模型标识」补一个,
卡片的「来源 / 编码」那一行才不会永远是「未设置编码」。 */
const modelCode = form.model_code.trim()
|| `${String(form.adapter).trim() || 'adapter'}:${form.media_type}:${form.model.trim()}`
const body: any = {
provider: form.provider.trim(), model: form.model.trim(), display_name: displayName,
media_type: form.media_type, adapter: form.adapter, enabled: form.enabled,
is_default: form.is_default, model_code: form.model_code.trim(),
is_default: form.is_default, model_code: modelCode,
timeout_seconds: Number(form.timeout_seconds) || 120,
max_concurrency: Number(form.max_concurrency) || 1,
requests_per_minute: Number(form.requests_per_minute) || 1,
@ -517,6 +521,7 @@ export default function ModelCenter() {
return (
<div className="min-w-0">
<PageStack>
<PageHead
title={<span title="本地 H3、Qwen-Image 与 IndexTTS2 共用一张 GPU;大模型通过 OpenAI 兼容接口接入。配置按能力拆分,密钥只加密保存并以掩码回显。">模型控制台</span>}
actions={<>
@ -531,17 +536,17 @@ export default function ModelCenter() {
{notice && <Notice onClose={() => setNotice('')}>{notice}</Notice>}
{/* 全库口径的四张卡:这张注册表与「当前项目」无关,所以汇总也不能跟着项目走 */}
<StatGrid cols={4} className="mb-4" steps={[{ at: 'xl', cols: 2 }, { at: 'lg', cols: 1 }, { at: 'sm', cols: 2 }]}>
<Stat label="全库模型配置" value={providers.length}
<StatGrid>
<Stat icon={<IconApi />} label="全库模型配置" value={providers.length}
hint={`${types.length} 类能力 · 所有项目共用,与当前项目无关`} />
<Stat label="已启用" value={<>{enabledCount}<i>/{providers.length}</i></>}
<Stat icon={<IconCheck />} label="已启用" value={<>{enabledCount}<i>/{providers.length}</i></>}
hint="只有启用项会被工作流与调度选用" />
<Stat tone={availableCount < enabledCount ? 'warn' : undefined} label="启用且可达"
<Stat tone={availableCount < enabledCount ? 'warn' : undefined} icon={<IconShield />} label="启用且可达"
value={<>{availableCount}<i>/{enabledCount}</i></>}
hint={availableCount < enabledCount
? `另有 ${enabledCount - availableCount} 个启用模型探测失败,见卡片状态`
: '全部启用模型均通过连接探测'} />
<Stat tone="lead" valueSize="title" label={`当前默认 · ${rail(selectedType).label}`}
<Stat tone="lead" icon={<IconStar />} valueSize="title" label={`当前默认 · ${rail(selectedType).label}`}
value={defaultRow?.display_name || '未设置'}
hint={`台账累计 ${usageTotal.calls} 次调用 · ${usageTotal.assets} 个素材 · ${fmtSeconds(usageTotal.seconds)}`} />
</StatGrid>
@ -556,7 +561,7 @@ export default function ModelCenter() {
{/* 能力分类 = 页面内部页签(四类模型是四个内部页面)。新增一类只改 TYPE_META。
「同卡串行」是全平台约束、不属于某一类,挂在页签条右端而不是某一页里。 */}
<Tabs className="mt-1" activeKey={selectedType} onChange={(k) => chooseType(k)}
<Tabs activeKey={selectedType} onChange={(k) => chooseType(k)}
tabBarExtraContent={{
right: (
<span title="H3 / Qwen-Image / IndexTTS2 统一归属 comfyui:9200 ,平台会在模型适配器层持有 GPU 锁,避免显存争抢。"
@ -576,19 +581,22 @@ export default function ModelCenter() {
<section className="min-w-0">
<Panel className="bg-bg-container">
{/* 同项目总览:卡头右端只放计数,筛选条放正文(见 Dashboard 同处注释) */}
{/* 「搜索」以前独占一行且右端全空:一个控件不配一行,收进卡头右端与计数同排(R2) */}
<PanelHead
title={<span title={selectedMeta?.description}>{selectedMeta?.label}</span>}
right={<Value>{currentRows.length} / {countOf(selectedType)} 个配置</Value>} />
<Ctlbar className="mb-3">
<Field inline label="搜索" width="grow">
<SearchInput value={keyword} aria-label="搜索模型" placeholder="名称 / 模型标识 / 编码" onChange={(e) => setKeyword(e.target.value)} />
</Field>
</Ctlbar>
right={<>
<Value>{currentRows.length} / {countOf(selectedType)} 个配置</Value>
<Field inline label="搜索" width="wide">
<SearchInput value={keyword} aria-label="搜索模型" placeholder="名称 / 模型标识 / 编码" onChange={(e) => setKeyword(e.target.value)} />
</Field>
</>} />
{!currentRows.length
? <Empty>当前能力还没有配置。添加后即可在资产生成、分镜与调度中选择。</Empty>
: (
<Grid cols={2} gap={10} oneAt="xl">
/* 同一行两张卡拉到同一高度:卡底那一排(启用 / 设为默认 / 检测连接)
本来写了 mt-auto,卡撑满 Col 之后两张卡的动作排就落在同一条线上。 */
<Grid cols={2} gap={10} oneAt="xl" className="[&>.ant-col>*]:h-full">
{currentRows.map((row) => (
<ModelCard key={row.id} row={row} rail={rail} busy={!!busy} canReveal={canRevealKey}
revealed={revealed[row.id]} revealing={keyRevealing === row.id}
@ -643,6 +651,7 @@ export default function ModelCenter() {
)}
</Panel>
</section>
</PageStack>
<Drawer open={showForm} onClose={closeForm}
title={<span title={rail(form.media_type).hint}>{editingId ? '编辑' : '添加'}{rail(form.media_type).label}</span>}
@ -658,6 +667,15 @@ export default function ModelCenter() {
{/* 锁 76px:这张表同时有 FieldBlock(标签在上)和行内 Field(Temperature / 并发 / RPM)。
行内标签只要有一个超过 66px 下限,整表控件左边界就错开(900px 实测 2px)。 */}
<FormGrid>
{/* 「高级」开关在表单最上方:它管的是下面**所有**段落(供应商标识 / 适配器 /
模型编码 / 工作流模板 / CLIP 类型 / Sigma / 自定义端点 / 原始 JSON)。
以前这颗按钮在最底下,展开之后没人知道新冒出来的是哪几栏。 */}
<div className="flex justify-end mb-1">
<Button type="text" size="sm" icon={showAdvanced ? <IconChevronUp /> : <IconChevronDown />}
onClick={toggleAdvanced}>
{showAdvanced ? '收起高级字段' : '显示高级字段'}
</Button>
</div>
{form.media_type === 'llm' && (
<>
<DrawerSection first title="供应商连接" note="OpenAI 兼容协议">
@ -722,12 +740,16 @@ export default function ModelCenter() {
<Input value={form.audio_vae} onChange={(e) => patch({ audio_vae: e.target.value })} />
</Field>
)}
<Field label="CLIP 类型">
<Input value={form.clip_type} onChange={(e) => patch({ clip_type: e.target.value })} />
</Field>
<Field label="工作流模板">
<Input value={form.workflow} onChange={(e) => patch({ workflow: e.target.value })} />
</Field>
{showAdvanced && (
<Field label="CLIP 类型">
<Input value={form.clip_type} onChange={(e) => patch({ clip_type: e.target.value })} />
</Field>
)}
{showAdvanced && (
<Field label="工作流模板">
<Input value={form.workflow} onChange={(e) => patch({ workflow: e.target.value })} />
</Field>
)}
<Field label="采样器">
<Input value={form.sampler} onChange={(e) => patch({ sampler: e.target.value })} />
</Field>
@ -743,7 +765,7 @@ export default function ModelCenter() {
<NumberInput min={1} value={form.fps} onChange={ (v) => patch({ fps: v })} />
</Field>
</FormRow>
{form.media_type === 'image' && (
{showAdvanced && form.media_type === 'image' && (
<FieldBlock label="固定 Sigma 序列">
<TextArea rows={2} className={MONO} value={form.sigmas} onChange={(e) => patch({ sigmas: e.target.value })} />
</FieldBlock>
@ -766,9 +788,11 @@ export default function ModelCenter() {
{ value: 'huggingface', label: 'HuggingFace' },
{ value: 'local', label: '仅本地' }]} />
</Field>
<Field label="工作流模板">
<Input value={form.workflow} onChange={(e) => patch({ workflow: e.target.value })} />
</Field>
{showAdvanced && (
<Field label="工作流模板">
<Input value={form.workflow} onChange={(e) => patch({ workflow: e.target.value })} />
</Field>
)}
<Field title="声线资产中的「供应商音色 ID」可填 ComfyUI input 文件名,或客户端本地音频路径;平台会自动上传本地参考音频。"
label="参考音频">
<Input value={form.reference_audio} onChange={(e) => patch({ reference_audio: e.target.value })} />
@ -782,53 +806,50 @@ export default function ModelCenter() {
<FieldBlock label="Base URL">
<Input value={form.base_url} onChange={(e) => patch({ base_url: e.target.value })} />
</FieldBlock>
<FieldBlock label="自定义端点">
<Input value={form.endpoint} placeholder="可留空,默认 /chat/completions" onChange={(e) => patch({ endpoint: e.target.value })} />
</FieldBlock>
{showAdvanced && (
<FieldBlock label="自定义端点">
<Input value={form.endpoint} placeholder="可留空,默认 /chat/completions" onChange={(e) => patch({ endpoint: e.target.value })} />
</FieldBlock>
)}
</DrawerSection>
)}
<DrawerSection title="模型身份与调度" note="所有能力通用,仅在此处填写一次">
{/* 日常要填的就三格:显示名称 / 模型标识 / 超时。
供应商标识、适配器、模型编码是接入工程师才碰的坐标,收进「显示高级字段」。 */}
<FormRow cols={3}>
<Field label="显示名称" required>
<Input value={form.display_name} onChange={(e) => patch({ display_name: e.target.value })} />
</Field>
<Field label="供应商标识">
<Input value={form.provider} onChange={(e) => patch({ provider: e.target.value })} />
</Field>
<Field label="适配器">
{/* 能力由左栏决定,抽屉里不切换媒体类型,所以适配器下拉只需要给出本能力的候选 */}
<Select value={form.adapter} onChange={(v) => patch({ adapter: v })}
options={adapters[form.media_type] || []} />
</Field>
<Field label="模型标识" required>
<Input value={form.model} onChange={(e) => patch({ model: e.target.value })} />
</Field>
<Field label="模型编码" required>
<Input value={form.model_code} onChange={(e) => patch({ model_code: e.target.value })} />
</Field>
<Field label="超时(秒)">
<NumberInput min={1} value={form.timeout_seconds} onChange={ (v) => patch({ timeout_seconds: v })} />
</Field>
</FormRow>
<FormRow cols={4} tight>
{/* 四个窄字段恰好占满一行;LLM / 图像没有时长概念,就退成两格宽 */}
<FormRow cols={form.media_type !== 'llm' && form.media_type !== 'image' ? 4 : 2} tight>
<Field label="并发">
<NumberInput min={1} value={form.max_concurrency} onChange={ (v) => patch({ max_concurrency: v })} />
</Field>
<Field label="RPM">
<NumberInput min={1} value={form.requests_per_minute} onChange={ (v) => patch({ requests_per_minute: v })} />
</Field>
{/* 两个字段各自是一个条件子节点:写成 `cond && <>…</>` 的话
Children.toArray 只看到 1 个孩子,两条时长会被塞进同一格竖排。 */}
{form.media_type !== 'llm' && form.media_type !== 'image' && (
<>
<Field label="最短时长">
<NumberInput step={0.5} value={form.min_duration} onChange={ (v) => patch({ min_duration: v })} />
</Field>
<Field label="最长时长">
<NumberInput step={0.5} value={form.max_duration} onChange={ (v) => patch({ max_duration: v })} />
</Field>
</>
<Field label="最短时长">
<NumberInput step={0.5} value={form.min_duration} onChange={ (v) => patch({ min_duration: v })} />
</Field>
)}
{form.media_type !== 'llm' && form.media_type !== 'image' && (
<Field label="最长时长">
<NumberInput step={0.5} value={form.max_duration} onChange={ (v) => patch({ max_duration: v })} />
</Field>
)}
</FormRow>
{/* 上一排是 tight 栅格(下边距 8),勾选项自己补 12 才凑成 20≈表单 24 的节奏 */}
<Row className="gap-5 mt-3 mb-1">
<Check checked={form.enabled} onChange={(v) => patch({ enabled: v })}>启用模型</Check>
<Check checked={form.is_default} onChange={(v) => patch({ is_default: v })}>设为该能力默认</Check>
@ -837,10 +858,24 @@ export default function ModelCenter() {
<TextArea rows={2} placeholder="模型约束、显存策略或接入说明" value={form.notes} onChange={(e) => patch({ notes: e.target.value })} />
</FieldBlock>
<Button icon={<IconChevronUp />} onClick={toggleAdvanced}
className="w-full mt-5 h-8 border-dashed text-xs">
{showAdvanced ? '收起高级 JSON' : '展开高级 JSON / 原始适配器参数'}
</Button>
{showAdvanced && (
/* 接入坐标:供应商标识 / 适配器 / 模型编码。新模型由 blank() 按能力预置,
所以留空也能保存;模型编码为空时保存前自动生成一个(见 save)。 */
<FormRow cols={3}>
<Field label="供应商标识">
<Input value={form.provider} onChange={(e) => patch({ provider: e.target.value })} />
</Field>
<Field label="适配器">
{/* 能力由左栏决定,抽屉里不切换媒体类型,所以适配器下拉只需要给出本能力的候选 */}
<Select value={form.adapter} onChange={(v) => patch({ adapter: v })}
options={adapters[form.media_type] || []} />
</Field>
<Field label="模型编码" title="内部唯一标识;留空时保存前自动生成「适配器:能力:模型标识」">
<Input value={form.model_code} placeholder="留空自动生成"
onChange={(e) => patch({ model_code: e.target.value })} />
</Field>
</FormRow>
)}
{showAdvanced && (
/* 比例是本页特有的(config 比 default_params 长得多),但栅格仍是 antd 的那一套 */
<Layout spans={[14, 10]} oneAt="lg" gutter={12} className="mt-3">
@ -927,79 +962,88 @@ function ModelCard({ row, rail, busy, canReveal, revealed, revealing, probing,
</Tag>
{fault > 0 && <Tag tone="bad">故障注入 {(fault * 100).toFixed(0)}%</Tag>}
</div>
<div className={cn(ID_MONO, 'mt-1 text-text')}>{row.model}</div>
<div className={cn(ID_MONO, 'mt-1 text-text-quaternary')}>
{row.provider} · {row.model_code || '未设置编码'} · {row.adapter}
</div>
<div className={cn(ID_MONO, 'mt-0.5 text-text-quaternary')}>{row.model}</div>
</div>
<Button icon={<IconParams />} onClick={onEdit}>配置</Button>
</div>
{/* 密钥默认只有掩码;展开明文后允许换行 —— 密钥 40+ 字符,省略号等于没显示 */}
<Block tone="default" vertical gap={0} className="mt-3 min-w-0">
<span className="block text-text-quaternary text-xs">{row.media_type === 'llm' ? 'Endpoint / Key' : '资源地址 / 参考'}</span>
<div className="flex items-center gap-1.5 mt-1 min-w-0">
<b title={shown}
className={cn('flex-1 basis-auto min-w-0 font-medium text-text-tertiary overflow-hidden text-ellipsis whitespace-nowrap',
revealed && 'whitespace-normal overflow-visible text-text [overflow-wrap:anywhere]')}>
{shown}
</b>
{/* 密钥明文开关:小一档的圆形图标按钮(antd size=small 就是 24px,
与这一行 19px 高的掩码文字同高,不会把行顶开)。
显隐状态由图形本身表达(睁眼 / 斜线眼 / 转圈),不另设选中色。 */}
{row.has_api_key && (
<Button type="text" shape="circle" onClick={onReveal} disabled={revealing}
aria-label={eyeTitle} title={eyeTitle}
icon={<EyeIcon shown={!!revealed} loading={revealing} size={14} />} />
)}
</div>
</Block>
{files.length > 0 && (
<div className="mt-2 flex min-w-0 flex-col gap-1">
{files.slice(0, 3).map((file) => (
<span key={file} title={file} className={cn(MONO, 'block text-text-quaternary text-xs overflow-hidden text-ellipsis whitespace-nowrap')}>
{file}
{/*
卡内只读属性一张表讲完(R16.3 Info):原先这里是「灰盒 + 标签排 + 虚线盒」三件
各自成盒的回显,容器三种圆角、三套描边,读者的眼睛要重新切三次分。
单列一行为一问,短属性合并在同一个 label 下(来源 / 编码、能力 / 限制),
高度与原来那只灰盒相当,读法却是一张表而不是一个框。
*/}
<Info className="mt-3" column={1} items={[
{
label: row.media_type === 'llm' ? 'API Key' : '资源地址',
value: (
<span className="flex min-w-0 items-center gap-1">
{/* 密钥默认只有掩码;展开明文后允许换行——密钥 40+ 字符,省略号等于没显示 */}
<span title={shown}
className={cn('min-w-0 font-medium text-text-tertiary overflow-hidden text-ellipsis whitespace-nowrap',
revealed && 'whitespace-normal overflow-visible text-text wrap-anywhere')}>
{shown}
</span>
{/* 密钥明文开关:小一档的圆形图标按钮(antd size=small 就是 24px,
与这一行 19px 高的掩码文字同高,不会把行顶开)。
显隐状态由图形本身表达(睁眼 / 斜线眼 / 转圈),不另设选中色。 */}
{row.has_api_key && (
<Button type="text" shape="circle" onClick={onReveal} disabled={revealing}
aria-label={eyeTitle} title={eyeTitle}
icon={<EyeIcon shown={!!revealed} loading={revealing} size={14} />} />
)}
</span>
))}
</div>
)}
{/* 这些是「这张卡是什么配置」的只读标签,不是可点的筛选项:用 Tag,不用 ChipBar / Chip */}
<TagGroup>
{(row.modes || []).slice(0, 5).map((mode: string) => <Tag key={mode}>{mode}</Tag>)}
{!!row.timeout_seconds && <Tag>超时 {row.timeout_seconds}s</Tag>}
{!!row.max_concurrency && <Tag>并发 {row.max_concurrency}</Tag>}
</TagGroup>
{row.notes && <p className="mt-2 mb-0 text-text-quaternary text-xs leading-normal">{row.notes}</p>}
<Block tone="default" gap={8} title="统计来自生成台账,为全平台累计(含历史项目与失败重试);只读,不影响配置"
className={cn('mt-auto !border-dashed text-text-tertiary text-xs',
!usage.calls && 'text-text-quaternary')}>
<span className="text-primary"><IconChart /></span>
{usageParts(row).map((part, idx) => (
<span key={part} className="min-w-0">
{idx > 0 && <em className="not-italic mr-2 text-text-quaternary">·</em>}
<b className={cn('font-normal', idx === 0 && (usage.calls ? 'font-semibold text-primary-hover' : 'font-medium'))}>
{part}
</b>
</span>
))}
</Block>
)
},
{ label: '来源 / 编码', mono: true, value: [row.provider, row.adapter, row.model_code || '未设置编码'].join(' · ') },
{
label: '能力 / 限制',
value: <TagGroup size="sm" className="!mb-0">
{(row.modes || []).slice(0, 5).map((mode: string) => <Tag key={mode}>{mode}</Tag>)}
{!!row.timeout_seconds && <Tag>超时 {row.timeout_seconds}s</Tag>}
{!!row.max_concurrency && <Tag>并发 {row.max_concurrency}</Tag>}
{!(row.modes || []).length && !row.timeout_seconds && !row.max_concurrency
&& <span className="text-text-quaternary text-xs">未声明</span>}
</TagGroup>
},
...(files.length
? [{
label: '权重文件',
value: <span className="flex flex-col">{files.slice(0, 3).map((file) => (
<span key={file} title={file} className={cn(MONO, 'truncate')}>{file}</span>))}</span>
}]
: []),
...(row.notes ? [{ label: '备注', value: <Value>{row.notes}</Value> }] : []),
{
label: '台账用量',
value: <Value className="!text-text-tertiary" title="统计来自生成台账,为全平台累计(含历史项目与失败重试);只读,不影响配置">
<IconText icon={<IconChart />}>
<b className={cn('font-normal', usage.calls && 'font-semibold text-primary-hover')}>
{usageParts(row)[0]}</b>
{usageParts(row).slice(1).map((part) => <span key={part}> · {part}</span>)}
</IconText>
</Value>
}
]} />
<CardActions className="min-w-0 border-t border-fill-secondary mt-auto pt-2">
<Check checked={!!row.enabled} disabled={busy} className="mr-auto"
onChange={() => onPatch({ enabled: !row.enabled }, row.enabled ? '停用模型' : '启用模型')}>
启用
</Check>
<Button icon={<IconCheck />} disabled={busy || !!row.is_default}
onClick={() => onPatch({ is_default: true }, '设为默认')}>
{row.is_default ? '当前默认' : '设为默认'}
</Button>
<Button icon={<IconReload />} disabled={busy || probing} onClick={onProbe}>
{probing ? '探测中…' : '检测连接'}
</Button>
{/* 第 17 轮续(闸门 §15.11 btnclustercheck):这四块原先全平铺在 CardActions 上,
430 档实测「启用 + 设为默认 + 检测连接」占满一行、删除孤零零掉到第二行,
卡再窄一点就会把「设为默认 / 检测连接」这一对劈成 1+1。
按 §7 的分组判据:对象级操作一组,破坏性操作单独一组(整块换行,不组内换行)。 */}
<ActionGroup>
<Button icon={<IconCheck />} disabled={busy || !!row.is_default}
onClick={() => onPatch({ is_default: true }, '设为默认')}>
{row.is_default ? '当前默认' : '设为默认'}
</Button>
<Button icon={<IconReload />} disabled={busy || probing} onClick={onProbe}>
{probing ? '探测中…' : '检测连接'}
</Button>
</ActionGroup>
<Button icon={<IconDelete />} type="text" danger disabled={busy} title="删除这个模型" onClick={onRemove} aria-label="删除这个模型" />
</CardActions>
</Tile>

View File

@ -857,9 +857,13 @@ export default function Library() {
title={`${assetKindLabel(a.kind)} · ${a.name} · v${a.version}`} />
<Tag size="sm">{assetKindLabel(a.kind)} v{a.version}</Tag>
{a.metadata?.model && <Tag size="sm">{a.metadata.provider}/{a.metadata.model}</Tag>}
<Button size="sm" title="登记新版本" aria-label="登记新版本"
onClick={() => refreshAsset(a)} icon={<IconSync />} />
<Button type="text" danger size="sm" title="删除素材" aria-label="删除素材" onClick={() => dropAsset(a)} icon={<IconDelete />} />
{/* 两颗图标按钮是对**这份素材**的一组操作,粘成一组整块换行
(闸门 §15.11 的候选:这一行没有类名,前两道按钮闸都扫不到它)。 */}
<ActionGroup>
<Button size="sm" title="登记新版本" aria-label="登记新版本"
onClick={() => refreshAsset(a)} icon={<IconSync />} />
<Button type="text" danger size="sm" title="删除素材" aria-label="删除素材" onClick={() => dropAsset(a)} icon={<IconDelete />} />
</ActionGroup>
</div>
))}
</CardActions>

View File

@ -2007,8 +2007,13 @@ function ShotCard({
</LinkButton>
<BarRight>
<Link to={`/projects/${projectId}/review?shot=${s.id}`} className={LINK_CLS}>审核</Link>
<Button size="sm" disabled={busy} onClick={onDuplicate} title="复制这一镜" aria-label="复制这一镜" icon={<IconCopy />} />
<Button type="text" danger title="删除这一镜" aria-label="删除这一镜" onClick={onRemove} icon={<IconDelete />} />
{/* 这一条原先在 1440 就被劈开过(闸门 §15.11):左端「生成/重生成」把宽度吃掉之后
BarRight 只剩 89px,「审核 + 复制」占一行、删除单独掉到第二行。
复制 / 删除是这一镜的对象级操作,粘成一组整块换行。 */}
<ActionGroup>
<Button size="sm" disabled={busy} onClick={onDuplicate} title="复制这一镜" aria-label="复制这一镜" icon={<IconCopy />} />
<Button type="text" danger title="删除这一镜" aria-label="删除这一镜" onClick={onRemove} icon={<IconDelete />} />
</ActionGroup>
</BarRight>
</div>
</div>

View File

@ -149,6 +149,8 @@ export type Caps = {
maxDuration: number
maxReferenceImages: number
requiresReference: boolean
/** 能不能只靠「音色描述」出音(IndexTTS2 的 voice_instruct):不能把没录过音的角色判死 */
voiceInstruct: boolean
adapter: string
mock: boolean
}
@ -156,7 +158,7 @@ export type Caps = {
const EMPTY_CAPS: Caps = {
known: false, label: '', resolutions: [], upscaleTo: [], aspectRatios: [], modes: [], fps: 0,
minDuration: 0, maxDuration: 0, maxReferenceImages: 0, requiresReference: false,
adapter: '', mock: false
voiceInstruct: false, adapter: '', mock: false
}
/** 读取一个模型的真实能力;ComfyUI 的帧率写在工作流 config 里 */
@ -175,6 +177,7 @@ export function capsOf(provider?: string | null, model?: string | null): Caps {
maxDuration: Number(row.max_duration || 0),
maxReferenceImages: Number(row.max_reference_images || 0),
requiresReference: row.requires_reference === true,
voiceInstruct: (row.modes || []).includes('voice_instruct'),
adapter: String(row.adapter || ''),
mock: isMock(row)
}

View File

@ -11,12 +11,20 @@
#
# 部署包 = 代码 + 表结构定义 + 模型配置与管理员(scripts/seed/)+ 启动脚本。
#
# 打包前四道闸门,任一条不过就不出包(--check 只跑闸门、不落盘):
# 1) 文件层 backend/app 与 frontend/src 各数一遍文件,证明排除清单没误伤代码
# 2) 启动层 包里的后端 import app.main 跑一次;前端从 index.html 沿 import 链走到底,
# 每个被引用的模块与样式都必须存在且真的进了包
# 3) 数据层 包里的 scripts/seed.py doctor --src 量一遍包里的数据集
# (列 / 适配器 / 能力位 / 默认位 / 主密钥能否解开密文),与代码对不上就拦下
# 4) 忽略层 .gitignore 没在吃掉源码
#
# 刻意**不在**包里的东西,每一条都有理由:
# *.db / nex_animation.db 开发库全是过程产物(项目、镜头、任务、5000 行事件日志),
# 新环境要的是干净起点,表结构由应用启动时自己建
# media/ (1.7G) 已生成的视频/图片/上传素材属于数据,换环境是「迁移」不是「部署」
# models/ (465M) whisper.cpp 权重,server.sh install 会自己下
# backend/tests/ 开发自检资产(487 条用例);服务器不需要 pytest 才能跑
# backend/tests/ 开发自检资产(503 条用例);服务器不需要 pytest 才能跑
# frontend/dist/ 构建产物,server.sh build 在服务器上重建,避免带过期哈希
# .venv/ node_modules/ 跨机的二进制与依赖目录,必须在目标机重装
# .env 机器相关配置(ComfyUI 地址、数据库串),首装由 .env.example 生成
@ -54,7 +62,10 @@ while [ $# -gt 0 ]; do
--no-seed) WITH_SEED=0 ;;
--with-dist) WITH_DIST=1 ;;
--dry-run) DRY_REMOTE=1 ;;
-h|--help) sed -n '3,32p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;;
# 帮助就是文件头那段注释。取范围靠「第一条 # === 到第二条 # ===」,不写死行号——
# 上一版是 sed -n '3,32p',头注释每加一行就要回来挪一次数字,很容易忘。
-h|--help) awk '/^# ={10,}/{n++; next} n==1{sub(/^# ?/, ""); print} n>1{exit}' \
"${BASH_SOURCE[0]}"; exit 0 ;;
*) die "未知参数:$1(./scripts/deploy.sh --help)" ;;
esac
shift
@ -96,15 +107,20 @@ fi
# ---------------------------------------------------------------- 体检
D="$STAGE/nex_animation"
head2 "体检"
# 这份清单只留「不在任何 import 链上的构建与启动文件」:package.json、vite.config.ts、
# Dockerfile、requirements.txt 这类靠工具链而非代码引用生效的东西。
# 刻意不再列 frontend/src/ 下的源码文件名——源码谁该进包由下面的入口链路检查说了算。
# 教训就写在这一行的历史里:上一版列了 styles/tokens.css,antd 改版把它拆成
# app.css + index.css,没人记得回来改这条,--check 从此每次都死在「缺少关键文件」。
REQUIRED=(backend/app/main.py backend/app/models/__init__.py backend/requirements.txt
backend/Dockerfile frontend/package.json frontend/src/main.tsx frontend/index.html
frontend/vite.config.ts frontend/src/styles/tokens.css
scripts/server.sh scripts/dev.sh scripts/e2e_selfcheck.py .env.example
docker-compose.yml README.md)
backend/Dockerfile frontend/package.json frontend/tsconfig.json
frontend/index.html frontend/vite.config.ts
scripts/server.sh scripts/dev.sh scripts/seed.py scripts/e2e_selfcheck.py
.env.example docker-compose.yml README.md)
for f in "${REQUIRED[@]}"; do
[ -e "$D/$f" ] || die "部署包缺少关键文件:$f"
done
ok "关键入口齐全(${#REQUIRED[@]} 项)"
ok "构建与启动入口齐全(${#REQUIRED[@]} 项)"
# backend/app 下的 .py 必须一个不少。教训来自 --exclude 'models/':本意是排仓库根的
# whisper 权重目录(465M),rsync 的裸目录名在任意层级生效,把 backend/app/models/
@ -135,6 +151,84 @@ if [ "$src_fe" != "$pkg_fe" ]; then
fi
ok "前端代码完整(frontend/src ${pkg_fe} 个源文件全部入包)"
# 数文件只证明「没少带」,不证明「接得上」。这一段从 index.html 的
# <script type="module"> 出发,把 static import、`export … from`、路由懒加载的
# `import('../pages/X')`、以及 CSS 里的 `@import "./app.css"` 一路解析到底:
# · 说明符在源码树里解析不到 = 本地就断链,npm build 同样过不去;
# · 解析到了但包里没这个文件 = 某条 --exclude 精准误伤了它,服务器构建才炸。
# 两种情况都在这里停住。用入口链当清单还有个额外好处:文件改名、拆分、挪目录
# 都不需要回来维护任何人手写的列表(上一条 REQUIRED 里的 tokens.css 就是这么烂掉的)。
# 裸名 import(react、antd、zustand…)跳过:那是 npm 依赖,服务器 npm install 提供,
# 而 node_modules/ 是刻意不带进包的跨机二进制。
fe_log="$STAGE/fe-graph.txt" fe_err="$STAGE/fe-graph.err"
# 输出走文件而不是 $( … ):bash 找右括号时会被 python 里的 r'''…''' 引号
# 绕晕,报 unexpected EOF while looking for matching `)',症状离病根很远,别踩。
if ! "$PY" - "$ROOT/frontend" "$D/frontend" > "$fe_log" 2> "$fe_err" <<'PYEOF'
import os, re, sys
root, pkg = sys.argv[1], sys.argv[2]
# 说明符常常不写扩展名('./Button'、'../pages/Login'),按 Vite 的习惯逐个试;
# 目录形式补 index.*,这是 src/components/ui/index.ts 那批桶文件的引用方式。
EXTS = ["", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".css", ".json",
"/index.ts", "/index.tsx", "/index.css"]
ENTRY = re.compile(r'''<script[^>]*\btype=["']module["'][^>]*\bsrc=["']([^"']+)''', re.I)
JS = re.compile(r'''(?:^|[\s;{}()])(?:import|export)\s(?:[^'"()]*?\sfrom\s*)?["']([^"']+)["']'''
r'''|\bimport[ \t]*\(\s*["']([^"']+)["']\s*\)''', re.M)
CSS = re.compile(r'''@import\s+(?:url\(\s*)?["']([^"']+)["']''', re.M)
def resolve(spec, base):
"""import 说明符 → frontend/ 下的相对路径;解析不到返回 None。"""
if spec.startswith("@/"): # vite.config.ts 里的 alias
cands = [os.path.join("src", spec[2:] + e) for e in EXTS]
elif spec.startswith("/"): # index.html 的 /src/main.tsx
cands = [spec.lstrip("/") + e for e in EXTS]
else:
d = os.path.dirname(base)
cands = [os.path.normpath(os.path.join(d, spec + e)) for e in EXTS]
for c in cands:
if os.path.isfile(os.path.join(root, c)):
return c
return None
html = open(os.path.join(root, "index.html"), encoding="utf-8").read()
entries = [m.group(1).lstrip("/") for m in ENTRY.finditer(html)]
if not entries:
sys.exit("index.html 里找不到 <script type=\"module\">,前端入口是什么?")
broken, todo, seen = [], list(entries), set()
for p in entries:
if not os.path.isfile(os.path.join(root, p)):
broken.append(f"index.html 的入口 {p} 不存在")
while todo:
f = todo.pop()
if f in seen or not os.path.isfile(os.path.join(root, f)):
continue
seen.add(f)
text = open(os.path.join(root, f), encoding="utf-8").read()
for m in (CSS if f.endswith(".css") else JS).finditer(text):
spec = m.group(1) or m.group(2)
if not spec or not spec.startswith((".", "/", "@/")):
continue
hit = resolve(spec, f)
if hit is None:
broken.append(f"源码断链:{f} 引用 {spec},文件不存在")
elif hit not in seen:
todo.append(hit)
lost = sorted(f for f in seen if not os.path.isfile(os.path.join(pkg, f)))
for line in broken:
print(line, file=sys.stderr)
for f in lost:
print(f"包内缺失:{f} 被入口引用,却没进部署包(检查 --exclude)", file=sys.stderr)
print(f"{len(entries)} 个入口 → {len(seen)} 个模块/样式全部可达且全部在包内")
sys.exit(1 if (broken or lost) else 0)
PYEOF
then
sed -n '1,20p' "$fe_err" >&2
die "前端入口链路不通:服务器上 npm run build 会原样失败"
fi
ok "前端入口链路完整:$(cat "$fe_log")"
# 再往前一步:直接 import 一次。文件数对了不代表包能起来(少 __init__.py、
# 循环依赖、误排子包都会在这里现形),而它在开发机上只要一秒。
# 用临时 SQLite 库:默认 DATABASE_URL 指向 Postgres,开发机的 venv 里没装 psycopg。
@ -188,15 +282,29 @@ else
warn "没装 git,跳过 .gitignore 误伤检查"
fi
SEED_SUMMARY="" SEED_DEFAULTS="" SEED_STAMP=""
if [ "$WITH_SEED" = 1 ]; then
for f in model_specs.json model_secret_keys.json users.json; do
[ -s "$D/scripts/seed/$f" ] || die "scripts/seed/$f 缺失或为空:先在开发机跑 .venv/bin/python scripts/seed.py export"
[ -s "$D/scripts/seed/$f" ] || die "scripts/seed/$f 缺失或为空:先在开发机跑 .venv/bin/python scripts/seed.py export --fix"
done
n=$("$ROOT/.venv/bin/python" -c "import json;print(json.load(open('$D/scripts/seed/model_specs.json'))['_meta']['count'])" 2>/dev/null || echo "?")
ok "部署数据就绪:模型配置 $n 条 + 加密主密钥 + 管理员账号"
if grep -l '"api_key_encrypted": "sk-' "$D"/scripts/seed/*.json >/dev/null 2>&1; then
die "seed 里出现明文 API Key(sk-…),请先在模型中心重填 Key 再导出"
# 数据层闸门:跑**包里的** seed.py 量**包里的** JSON。两边都用包内副本,
# 过检的才是「这份代码 + 这份数据」这个组合本身——服务器上 install 执行的正是它们;
# 拿开发机工作树的脚本来量包,代码改了却没重新导出时照样绿灯。
# DATABASE_URL 指内存库:doctor --src 只读 JSON 不碰库,但 seed.py import 时会建 engine,
# 默认串指向 Postgres 的话开发机上这一步会直接连不上。
seed_log="$STAGE/seed-doctor.txt"
if ! (cd "$D" && PYTHONDONTWRITEBYTECODE=1 DATABASE_URL="sqlite:///:memory:" \
"$PY" scripts/seed.py doctor --src scripts/seed) > "$seed_log" 2>&1; then
printf ' %sXX%s 部署数据集与包内代码对不上(服务器上 install 会拒装):\n' "$C_R" "$C_0" >&2
sed -n '1,40p' "$seed_log" >&2
die "开发机上跑 .venv/bin/python scripts/seed.py doctor --fix,重新 export --fix 后再打包"
fi
SEED_SUMMARY=$(sed -n 's/^ 数据集://p' "$seed_log" | head -1)
SEED_DEFAULTS=$(sed -n 's/^ 默认位://p' "$seed_log" | head -1)
SEED_STAMP=$("$PY" -c "import json,sys;print(json.load(open(sys.argv[1]))['_meta'].get('exported_at','?'))" \
"$D/scripts/seed/model_specs.json" 2>/dev/null || echo "?")
ok "部署数据集体检通过:$SEED_SUMMARY"
info "${C_D}导出时间 $SEED_STAMP · 默认位 $SEED_DEFAULTS${C_0}"
else
warn "--no-seed:服务器将从空库启动,只有 mock 模型可用"
fi
@ -215,8 +323,11 @@ printf ' %s目录概览%s\n' "$C_D" "$C_0"
echo "生成机器 : $(hostname)"
echo "源目录 : $ROOT"
echo "文件数 : $TOTAL_FILES 体积: $TOTAL_SIZE"
echo "模型配置 : $([ "$WITH_SEED" = 1 ] && echo '随包(scripts/seed/)' || echo '未随包')"
echo "模型配置 : $([ "$WITH_SEED" = 1 ] && echo "随包(scripts/seed/,导出于 $SEED_STAMP)· $SEED_SUMMARY" || echo '未随包(--no-seed,空库起 mock)')"
echo "默认位 : $([ "$WITH_SEED" = 1 ] && echo "${SEED_DEFAULTS:-(未标注)}" || echo '(无)')"
echo "前端产物 : $([ "$WITH_DIST" = 1 ] && echo '随包' || echo '服务器上 server.sh build 生成')"
echo "体检 : 打包前已通过 backend import / 前端入口链路 / seed doctor 三道闸门"
echo " (seed.py doctor 与服务器 install 用的是同一把尺子,装前还会再量一次)"
echo
echo "服务器三步:"
echo " tar -xzf $PKG_NAME.tar.gz && cd nex_animation"

View File

@ -1,6 +1,6 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""部署数据集的导出与安装:表结构 + 模型配置 + 管理员账号。
"""部署数据集的体检、导出与安装:表结构 + 模型配置 + 管理员账号。
服务器部署**不搬开发库**。14MB 的 nex_animation.db 里绝大多数是开发过程产物
(项目、镜头、任务、事件日志、演示账号),新环境真正需要的是三样东西:
@ -17,12 +17,22 @@
必须和密文一起走**——换机器只带 model_specs,密文会解成空串,
表现为「模型中心显示已配置,派发却报缺 Key」。
# 开发机:导出
.venv/bin/python scripts/seed.py export
# 开发机:体检 →(必要时校准)→ 导出
.venv/bin/python scripts/seed.py doctor # 只量不改,退出码非 0 = 有别部署
.venv/bin/python scripts/seed.py doctor --fix # 把库补齐到当前代码(只补缺)
.venv/bin/python scripts/seed.py export --fix # 校准 + 体检 + 导出(部署前就这一条)
.venv/bin/python scripts/seed.py export --with-platform-library # 顺带平台资源库
# 服务器:安装(空库;先建表再灌数据,幂等,可反复执行)
# 服务器:安装(空库;先量包再建表再灌数据,幂等,可反复执行)
.venv/bin/python scripts/seed.py install
.venv/bin/python scripts/seed.py install --only-missing # 只补库里没有的,本机已调的不动
.venv/bin/python scripts/seed.py doctor --src scripts/seed # 只量部署包(deploy.sh 用这条)
.venv/bin/python scripts/seed.py boundary # 数据边界一览(server.sh status 用这条)
**体检(doctor)是这三条命令共用的同一把尺子**:列对得上表结构、适配器在代码里注册过、
`modes` 不比代码声明的能力少、每类能力恰好一个默认、密文能被包里的主密钥解开、管理员登得进来。
导出前量库、安装前量包,两边用的是同一个 `audit_dataset()`——
否则「导出时没说、装上才发现」的老路会一直走下去(详见下面体检小节的注释)。
安装顺序刻意是「主密钥 → 模型配置 → 账号」:主密钥先到位,后面导入的密文才可解。
`model_secret_keys` 已有值且与导出值不同时默认**中止**(不是覆盖),
@ -34,13 +44,16 @@ from __future__ import annotations
import argparse
import datetime as dt
import json
import os
import sys
from pathlib import Path
from types import SimpleNamespace
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / "backend"))
from sqlalchemy import inspect, select, text, types as sa_types # noqa: E402
from sqlalchemy.orm import Session # noqa: E402
from app.db import Base, SessionLocal, engine, init_db # noqa: E402
from app.models import ModelSecretKey, ModelSpec, User # noqa: E402
@ -105,11 +118,329 @@ def _apply(row, data: dict, *, skip: tuple[str, ...] = ()) -> None:
setattr(row, key, val)
# ================================================================== 体检(doctor)
# 为什么必须有这一节:部署数据集是「快照」,代码是「活水」。快照一旦落后于代码,
# 服务器上的表现不是报错而是**静默降级**,比崩掉更难查:
#
# * 导出时 modes 里还没有 `voice_instruct` → 装上之后「音色描述直出」整个功能
# 在模型中心和声线页都看不见(`services/timbre.py:supports_instruct()` 读的是
# `model_specs.modes`,不是代码里的 Capabilities),排查的人会去查 ComfyUI;
# * 导出之后代码给工作流加了新节点键(`generate_full_node` / `instruct_node`)
# → 配置里少键,走到描述词分支才炸;
# * 导出之后 ORM 加了非空列 → `install` 在服务器上抛 IntegrityError,
# 而这句话离真正的根因(数据集是旧的)隔了 40 行 traceback;
# * 开发机改了模型、删了模型,忘了重新 export → 包里还是上周那套端点。
#
# 所以体检做三件事:**列对得上、能力对得上、密钥对得上**,并且把「代码比数据新」
# 当成错误而不是提示——它唯一的修复动作在开发机上(`doctor --fix` + 重新 export),
# 在服务器上加 --allow-drift 硬闯才是合理的逃生门。
CAPABILITY_MEDIA_TYPES = ("video", "image", "tts", "llm")
SEED_TABLES = ("model_specs", "model_secret_keys", "users")
# 这几张表非空 = 目标库已经在跑业务,不该拿它当首装库
BUSINESS_TABLES = ("projects", "shots", "tasks", "assets", "generation_records", "event_logs")
class Report:
"""体检结论:error 会挡住 export/install,warn 只打印。"""
def __init__(self) -> None:
self.items: list[tuple[str, str, str]] = []
def error(self, code: str, msg: str) -> None:
self.items.append(("error", code, msg))
def warn(self, code: str, msg: str) -> None:
self.items.append(("warn", code, msg))
@property
def errors(self) -> list[tuple[str, str, str]]:
return [i for i in self.items if i[0] == "error"]
@property
def warns(self) -> list[tuple[str, str, str]]:
return [i for i in self.items if i[0] == "warn"]
def show(self) -> None:
for level, code, msg in self.items:
mark = "XX" if level == "error" else " !"
color = "\033[31m" if level == "error" else "\033[33m"
print(f" {color}{mark}\033[0m [{code}] {msg}")
if not self.items:
print(" \033[32mok\033[0m 没有告警")
def _adapter_of(media_type: str, adapter: str, provider: str):
"""按 media_type/adapter 取适配器;取不到返回 None(调用方记错误)。"""
from app.providers import registry as model_registry
from app.providers.base import FatalProviderError
try:
return model_registry.adapter_for_spec(
SimpleNamespace(media_type=media_type, adapter=adapter, provider=provider, config_json={}))
except FatalProviderError:
return None
def _code_defaults_for(adapter_name: str) -> dict:
"""代码里维护的本地工作流默认配置(用于「只补缺失键」,不覆盖既有值)。"""
from app.providers import registry as model_registry
builders = {"comfyui": model_registry.comfyui_config,
"comfyui_image": model_registry.comfyui_image_config,
"comfyui_tts": model_registry.comfyui_tts_config}
build = builders.get((adapter_name or "").lower())
return build() if build else {}
def _rows_decrypt(keys: list[dict], specs: list[dict]) -> list[str]:
"""用「包里的主密钥」试解「包里的密文」,返回解不开的那几条。
临时摘掉 MODEL_SECRET_KEY:不然这里量到的是本机环境变量的密钥,
服务器上没有这个变量时反而会漏报(用 env 的那条检查单独告警)。
"""
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from app.services import secrets as secret_svc
ciphered = [(f"{s.get('provider')}/{s.get('model')}", s.get("api_key_encrypted") or "")
for s in specs if s.get("api_key_encrypted")]
if not ciphered:
return []
if not keys or not (keys[0].get("key_value") or ""):
return [name for name, _ in ciphered]
engine = create_engine("sqlite://", future=True)
Base.metadata.create_all(engine, tables=[ModelSecretKey.__table__])
session = sessionmaker(bind=engine, class_=Session, future=True)()
row = ModelSecretKey()
_apply(row, keys[0], skip=("id",))
session.add(row)
session.commit()
saved = os.environ.pop("MODEL_SECRET_KEY", None)
try:
bad = [name for name, cipher in ciphered
if not secret_svc.decrypt_value(session, cipher)]
finally:
if saved is not None:
os.environ["MODEL_SECRET_KEY"] = saved
session.close()
engine.dispose()
return bad
def audit_specs(rep: Report, specs: list[dict], keys: list[dict], *, origin: str) -> None:
"""模型配置:列 ⇄ 表结构、适配器、能力位、默认位、端点、密钥。"""
table = Base.metadata.tables["model_specs"]
known_cols = {c.key for c in inspect(table).columns}
required_cols = {c.key for c in inspect(table).columns
if not c.nullable and c.default is None and c.server_default is None
and c.key != "id"}
def label(row: dict) -> str:
return f"{row.get('provider')}/{row.get('model')}({row.get('media_type')})"
# ---- 列:数据集与当前表结构的差集
unknown = sorted({k for r in specs for k in r} - known_cols - {"_meta"})
if unknown:
rep.warn("列", f"{origin} 里有当前表结构没有的列,导入时会被静默丢弃:{unknown}")
for row in specs:
missing = sorted(required_cols - set(row))
if missing:
rep.error("列", f"{label(row)} 缺非空列 {missing}:数据集比表结构旧,"
"在开发机跑 scripts/seed.py doctor --fix 再 export")
break
# ---- 适配器 + 能力位
for row in specs:
adapter = _adapter_of(row.get("media_type") or "", row.get("adapter") or "",
row.get("provider") or "")
if adapter is None:
rep.error("适配器", f"{label(row)} 的 adapter={row.get('adapter')!r} 代码里没注册,"
"派发时直接 FatalProviderError")
continue
try:
caps = adapter.capabilities(row.get("config_json") or {})
except Exception as exc: # noqa: BLE001
rep.warn("适配器", f"{label(row)} 读适配器能力失败:{type(exc).__name__}: {exc}")
continue
drift = sorted(set(caps.modes) - set(row.get("modes") or []))
if drift:
rep.error("能力位", f"{label(row)} 的 modes 缺 {drift}:代码已支持、数据集还是旧的。"
"装上去这些能力在模型中心/派发热路径里都不存在"
"(修复:开发机 doctor --fix + 重新 export;确认要收窄就加 --allow-drift)")
# ---- 默认位:每类能力必须恰好一个默认,且它自己必须是启用的
for media_type in sorted({r.get("media_type") for r in specs}):
group = [r for r in specs if r.get("media_type") == media_type]
wanted = [r for r in group if r.get("is_default")]
if len(wanted) != 1:
rep.error("默认位", f"{media_type} 有 {len(wanted)} 个默认模型"
f"({'、'.join(label(r) for r in wanted) or '无'}):"
"0 个会让这类能力退回 mock,>1 个则派发按排序偶然选中")
continue
if not wanted[0].get("enabled", True):
rep.error("默认位", f"{media_type} 的默认模型 {label(wanted[0])} 是停用状态")
missing_caps = [m for m in CAPABILITY_MEDIA_TYPES
if not any(r.get("media_type") == m and not (r.get("provider") or "").startswith("mock")
for r in specs)]
if missing_caps:
rep.warn("默认位", f"这几类能力只有 mock 可用:{missing_caps}(部署后跑不出真片)")
# ---- 端点:真实模型没端点 = 装上去必然连不上
for row in specs:
if (row.get("provider") or "").startswith("mock"):
continue
cfg = row.get("config_json") or {}
base = str(cfg.get("base_url") or "").strip()
if not base:
rep.error("端点", f"{label(row)} 的 config_json.base_url 是空的:服务器上无处可连")
elif base.startswith(("http://localhost", "http://127.0.0.1")):
rep.warn("端点", f"{label(row)} 指向 localhost:服务器与模型不同机时连不上")
if row.get("media_type") == "llm" and not (row.get("api_key_encrypted") or ""):
rep.warn("端点", f"{label(row)} 没有 API Key(若该端点免鉴权可忽略)")
# ---- 密钥:主密钥与密文必须成对
if os.environ.get("MODEL_SECRET_KEY"):
rep.warn("密钥", "本机设了 MODEL_SECRET_KEY:密文是它加密的,包里的 model_secret_keys "
"在服务器上不起作用——部署时必须把同一个变量写进服务器 .env")
ciphered = [f"{r.get('provider')}/{r.get('model')}" for r in specs if r.get("api_key_encrypted")]
leaks = [f"{r.get('provider')}/{r.get('model')}" for r in specs
if str(r.get("api_key_encrypted") or "").startswith("sk-")]
if leaks:
rep.error("密钥", f"疑似明文 API Key 直接入库:{leaks};在模型中心重填一次再导出")
bad = _rows_decrypt(keys, specs)
if bad:
rep.error("密钥", f"这些模型配置的 Key 用包内主密钥解不开:{bad}"
"(表现是模型中心显示已配置、派发报缺 Key)")
def audit_users(rep: Report, users: list[dict], *, origin: str = "数据集") -> None:
"""管理员:能登进来、没有跨机无意义的登录流水列。"""
from app.services import auth as auth_service
table = Base.metadata.tables["users"]
known_cols = {c.key for c in inspect(table).columns}
unknown = sorted({k for u in users for k in u} - known_cols)
if unknown:
rep.warn("账号", f"{origin} 里有表结构没有的列,导入时会被丢弃:{unknown}")
# 「有没有登录流水列」只对导出文件成立:直接从库里读出来的行当然带这些列,
# 是 export 负责在写文件前剔掉它们(USER_DROP)。
if origin != "开发库":
stale = [k for u in users for k in USER_DROP if k in u]
if stale:
rep.warn("账号", f"{origin} 带着机器相关的登录流水列 {sorted(set(stale))}:"
"跨机无意义,建议重新 export")
admins = [u for u in users if u.get("role") == "admin"]
if not admins:
rep.error("账号", "部署包里没有 role=admin 的账号:服务器首启会另建一个 admin,"
"口令与这台机器不同")
for u in users:
if not (u.get("password_hash") or ""):
rep.error("账号", f"账号 {u.get('username')} 没有口令哈希,登不进去")
continue
try:
auth_service.verify_password("probe-only", u["password_hash"])
except Exception as exc: # noqa: BLE001
rep.error("账号", f"账号 {u.get('username')} 的 password_hash 解析失败:"
f"{type(exc).__name__}: {exc}")
if not u.get("is_active", True):
rep.warn("账号", f"账号 {u.get('username')} 在导出机上是停用状态")
def audit_dataset(specs: list[dict], keys: list[dict], users: list[dict], *, origin: str,
rep: Report | None = None) -> Report:
"""量一份数据集。`rep` 传进来时可以与其他检查(如目标库现状)汇到同一份结论里。"""
rep = rep or Report()
if not specs:
rep.error("数据集", f"{origin}:model_specs 一条都没有,装上只有 mock")
audit_specs(rep, specs, keys, origin=origin)
audit_users(rep, users, origin=origin)
return rep
def _table_counts(bind, names: tuple[str, ...]) -> dict[str, int]:
from sqlalchemy import text as sa_text
existing = set(inspect(bind).get_table_names())
out: dict[str, int] = {}
with bind.begin() as conn:
for name in names:
if name in existing:
out[name] = conn.execute(sa_text(f"SELECT COUNT(*) FROM {name}")).scalar() or 0
return out
def audit_orphan_tables(rep: Report, bind) -> None:
"""库里躺着代码不认识的表 = 历史手术留下的备份表,它不该跟着部署走。
只报不删:工程规范 §6 说得很清楚,这种表要人确认后手工 DROP,
脚本偷偷删表等于把「备份」这个唯一的退路删掉。
"""
orphan = sorted(set(inspect(bind).get_table_names()) - set(Base.metadata.tables))
if orphan:
rep.warn("边界", f"库里有代码不认识的表 {orphan}:历史遗留备份表,"
"确认后手工 DROP(它不影响部署包,但会让 status 的数据边界说不清)")
def audit_target_db(rep: Report, db) -> None:
"""install 的目标库现状:别把部署数据灌进一个正在跑业务的库。"""
counts = {k: v for k, v in _table_counts(db.bind, BUSINESS_TABLES).items() if v}
if counts:
rep.warn("边界", f"目标库里已有业务数据 {counts}:部署数据集只该进干净库,"
"确认 DATABASE_URL 没指到开发库(覆盖式导入会改掉这些模型配置)")
audit_orphan_tables(rep, db.bind)
# ------------------------------------------------------------------ 校准(--fix)
def calibrate_specs(db, *, apply: bool) -> list[str]:
"""把开发库的模型配置补齐到当前代码:只加不减,从不覆盖已有值。
只做两件事,因为这两件事代码才是权威:
1. `modes` 补上适配器已声明、行里却缺的能力位;
2. `config_json` 补上代码默认配置里新增、行里却缺的键(工作流节点等)。
其余字段(端点、限流、单价、notes)都是人工在页面上调的,代码一律不猜。
"""
changes: list[str] = []
for spec in db.scalars(select(ModelSpec).order_by(ModelSpec.id)).all():
adapter = _adapter_of(spec.media_type, spec.adapter, spec.provider)
if adapter is None:
continue
caps = adapter.capabilities(spec.config_json or {})
missing_modes = sorted(set(caps.modes) - set(spec.modes or []))
defaults = _code_defaults_for(spec.adapter)
cfg = dict(spec.config_json or {})
missing_cfg = sorted(k for k in defaults if k not in cfg)
if not missing_modes and not missing_cfg:
continue
if apply:
if missing_modes:
spec.modes = list(spec.modes or []) + missing_modes
for key in missing_cfg:
cfg[key] = defaults[key]
spec.config_json = cfg
changes.append(f"{spec.provider}/{spec.model}({spec.media_type}):"
+ (f"补 modes {missing_modes}" if missing_modes else "")
+ ("、" if missing_modes and missing_cfg else "")
+ (f"补 config_json 键 {missing_cfg}" if missing_cfg else ""))
if apply and changes:
db.commit()
return changes
# ================================================================== export
def do_export(args) -> None:
out = Path(args.out)
db = SessionLocal()
try:
if args.fix:
changes = calibrate_specs(db, apply=True)
if changes:
print("校准开发库(只补缺,不覆盖人工调过的值)")
for line in changes:
print(f" · {line}")
# 不在这里量「库里有没有业务数据」:开发库当然有,那条检查是给 install
# 挡「把部署数据灌进正在跑的库」用的(见 do_install)。
specs = [row_to_dict(s) for s in db.scalars(select(ModelSpec).order_by(ModelSpec.id)).all()]
keys = [row_to_dict(k) for k in db.scalars(select(ModelSecretKey).order_by(ModelSecretKey.id)).all()]
admins = [row_to_dict(u) for u in db.scalars(
@ -119,12 +450,15 @@ def do_export(args) -> None:
if not admins:
sys.exit("users 里没有 admin 角色账号。")
# 明文密钥自检:导出文件里只允许出现密文。任何一条看起来像
# "sk-xxxx" 的明文都说明有人绕过 secrets.py 直接写了库。
leaks = [f"{s['provider']}/{s['model']}" for s in specs
if s.get("api_key_encrypted", "").startswith("sk-")]
if leaks:
sys.exit(f"疑似明文 API Key 直接入库:{leaks};请先在模型中心重填一次。")
# 导出与安装用同一把尺子量:量库一次、装前量包一次,不会出现
# 「导出时没说、装到服务器才发现」的错配。明文 Key 自检也在体检里
# (secrets.py 只该写密文,出现 sk- 开头的明文就是有人绕过了封装)。
rep = audit_dataset(specs, keys, admins, origin="开发库")
print("体检(部署数据集)")
rep.show()
print_dataset_summary(rep, specs, keys, admins)
if rep.errors and not args.allow_drift:
sys.exit("导出中止:上面是 error。修完再导;确认要带着这些问题部署,加 --allow-drift。")
write_json(out / "model_specs.json", {
"_meta": {"table": "model_specs", "count": len(specs),
@ -218,6 +552,7 @@ def _install_master_key(db, rows, *, dry: bool, force: bool) -> None:
def _install_specs(db, rows, *, dry: bool, only_missing: bool = False) -> None:
added = updated = skipped = 0
added_keys: set[tuple[str, str, str]] = set()
for data in rows:
key = {"provider": data["provider"], "model": data.get("model", ""),
"media_type": data["media_type"]}
@ -230,16 +565,25 @@ def _install_specs(db, rows, *, dry: bool, only_missing: bool = False) -> None:
_apply(row, data, skip=("id", "created_at", "updated_at"))
db.add(row)
added += 1
added_keys.add((row.provider, row.model, row.media_type))
else:
_apply(row, data, skip=("id", "created_at"))
updated += 1
# 默认位以导出包为准:同能力下不在包里的旧默认必须让位,
# 否则 seed_specs / resolve_* 会因为排序偶然选中开发机没在用的那个模型。
# 例外是 --only-missing:这个开关的承诺是「这台机器已有的东西一概不动」,
# 所以只有当包里的默认模型是这次**新插进来**的那一条时才设默认。
# 早先无例外时翻过车:一次「新增 0、跳过 8」的导入什么都没写,却把服务器上
# 自选的 tts 默认悄悄改回开发机那套,日志上还是一片祥和。
db.flush()
kept: list[str] = []
for media_type in {d["media_type"] for d in rows}:
want = next((d for d in rows if d["media_type"] == media_type and d["is_default"]), None)
if want is None:
continue
if only_missing and (want["provider"], want.get("model", ""), media_type) not in added_keys:
kept.append(f"{media_type}={want['provider']}/{want['model']}")
continue
others = db.query(ModelSpec).filter(
ModelSpec.media_type == media_type,
ModelSpec.is_default.is_(True),
@ -248,6 +592,8 @@ def _install_specs(db, rows, *, dry: bool, only_missing: bool = False) -> None:
if others:
print(f" · {media_type}: 取消 {others} 条旧默认,改为 "
f"{want['provider']}/{want['model']}")
if kept:
print(f" · --only-missing:保留本机默认位不改(包里的是 {'、'.join(sorted(kept))})")
if not dry:
db.commit()
note = ",--only-missing 跳过 " + str(skipped) if skipped else ""
@ -311,12 +657,28 @@ def do_install(args) -> None:
if args.with_platform_library:
lib = read_json(src, "platform_library.json")["rows"]
# 先量包再动库:数据集比代码旧时,装上去的后果是「静默少功能」,而 install 一旦
# 跑过就改掉了表结构与默认位、回不到原样,所以宁可在这里停住不动。
print(f"体检部署数据集({src})")
rep = audit_dataset(specs, keys, users, origin=f"部署包 {src.name}")
rep.show()
print_dataset_summary(rep, specs, keys, users)
if rep.errors and not args.allow_drift:
sys.exit("导入中止:部署包与当前代码对不上(上面 error 条目)。"
"在开发机 doctor --fix + 重新 export 再打包;确认无碍加 --allow-drift。")
if args.schema:
init_db() # 建表 + 列迁移,幂等
print(f" ✓ 表结构就绪:{engine.url.render_as_string(hide_password=True)}")
db = SessionLocal()
try:
if not args.dry_run:
target = Report()
audit_target_db(target, db)
if target.items:
print("体检目标库")
target.show()
print("安装部署数据集(幂等,可反复执行)")
_install_master_key(db, keys, dry=args.dry_run, force=args.force_master_key)
_install_specs(db, specs, dry=args.dry_run, only_missing=args.only_missing)
@ -346,6 +708,87 @@ def do_install(args) -> None:
db.close()
def print_dataset_summary(rep: Report, specs: list[dict], keys: list[dict],
users: list[dict]) -> None:
"""把数据集摊开给人看:装到服务器上的到底是什么,一行一个结论。"""
defaults = sorted(f"{s['media_type']}={s['provider']}/{s['model']}"
for s in specs if s.get("is_default"))
real = sorted(f"{s['media_type']}/{s['provider']}/{s['model']}"
for s in specs if not (s["provider"] or "").startswith("mock"))
with_key = sorted(f"{s['provider']}/{s['model']}"
for s in specs if s.get("api_key_encrypted"))
print(f" 数据集:模型配置 {len(specs)} 条(真实模型 {'、'.join(real) or '无'})")
print(f" 默认位:{'、'.join(defaults) or '(无)'}")
print(f" 凭据:带 API Key {len(with_key)} 条"
+ ("(" + "、".join(with_key) + ")" if with_key else "")
+ f" · 主密钥 {len(keys)} 条 · 管理员 "
+ ("、".join(u["username"] for u in users) or "(无)"))
def do_doctor(args) -> None:
"""体检:默认量当前库(导出前自查),--src 时量部署包(deploy.sh 用这条)。
退出码非 0 = 有 error。`deploy.sh` 把它当打包闸门:在开发机上就把「数据比代码旧」
拦下来,比到了服务器上 install 才炸便宜得多——那时人已经不在终端前了。
"""
if args.src:
src = Path(args.src)
specs = read_json(src, "model_specs.json")["rows"]
keys = read_json(src, "model_secret_keys.json")["rows"]
users = read_json(src, "users.json")["rows"]
rep = audit_dataset(specs, keys, users, origin=f"部署包 {src}")
else:
db = SessionLocal()
try:
if args.fix:
changes = calibrate_specs(db, apply=True)
print("校准模型配置(只补缺,不覆盖人工调过的值)")
for line in changes or ["没有需要补的:数据与当前代码一致"]:
print(f" · {line}")
specs = [row_to_dict(s) for s in db.scalars(select(ModelSpec).order_by(ModelSpec.id)).all()]
keys = [row_to_dict(k) for k in db.scalars(select(ModelSecretKey).order_by(ModelSecretKey.id)).all()]
users = [{k: v for k, v in row_to_dict(u).items() if k not in USER_DROP}
for u in db.scalars(select(User).where(User.role == "admin")
.order_by(User.id)).all()]
rep = Report()
# 开发库里当然有业务数据,所以这里只查遗留表,不查「是不是干净库」
audit_orphan_tables(rep, engine)
audit_dataset(specs, keys, users, origin=f"开发库 {engine.url.database}", rep=rep)
finally:
db.close()
print_dataset_summary(rep, specs, keys, users)
print("体检结论")
rep.show()
if rep.errors and not args.allow_drift:
sys.exit(f"体检未过:{len(rep.errors)} 条 error、{len(rep.warns)} 条 warn")
print(f" → 判定通过(error 0 · warn {len(rep.warns)})")
# ================================================================== boundary
def do_boundary(args) -> None:
"""数据边界一览:这台机器上「部署包带来的」和「本机业务跑出来的」各有多少行。
给 `server.sh status` 用。写在 seed.py 而不是 shell 里内嵌 SQL,是为了和体检共用
同一批常量(SEED_TABLES / BUSINESS_TABLES):边界定义哪天变了,两边不会各说一套——
「部署只带配置、不带业务数据」这条约定最怕的就是两个地方各数各的。
"""
cfg = _table_counts(engine, SEED_TABLES)
if not cfg:
print(" 表结构还没建:先 ./scripts/server.sh install")
return
biz = _table_counts(engine, BUSINESS_TABLES)
print(" 配置(随部署包):" + "、".join(f"{k} {v}" for k, v in sorted(cfg.items())))
print(" 业务(本机产生):" + ("、".join(f"{k} {v}" for k, v in sorted(biz.items())) or "(表还没建)"))
if not any(biz.values()):
print(" → 业务表全空:干净起点,符合部署边界")
else:
print(f" → 本机已产生 {sum(biz.values())} 行业务数据。它不在部署包里,"
"换机器属于迁移,要单独备份 media/ 与库文件")
orphan = sorted(set(inspect(engine).get_table_names()) - set(Base.metadata.tables))
if orphan:
print(f" ! 代码不认识的表:{'、'.join(orphan)}(确认后手工 DROP,见工程规范 §6)")
# ================================================================== CLI
def main() -> None:
ap = argparse.ArgumentParser(description=__doc__.splitlines()[0],
@ -355,6 +798,9 @@ def main() -> None:
e = sub.add_parser("export", help="导出模型配置 + 主密钥 + 管理员到 JSON")
e.add_argument("--out", default=str(SEED_DIR), help="输出目录(默认 scripts/seed)")
e.add_argument("--with-platform-library", action="store_true", help="顺带导出平台资源库")
e.add_argument("--fix", action="store_true",
help="导出前先把库里的模型配置补齐到当前代码(补 modes、补工作流节点键)")
e.add_argument("--allow-drift", action="store_true", help="体检有 error 也照样导出")
e.set_defaults(func=do_export)
i = sub.add_parser("install", help="把 JSON 装进目标库(服务器首次部署用)")
@ -365,8 +811,18 @@ def main() -> None:
i.add_argument("--with-platform-library", action="store_true", help="顺带导入平台资源库")
i.add_argument("--only-missing", action="store_true",
help="模型配置只补缺,不覆盖服务器上已有的同名模型")
i.add_argument("--allow-drift", action="store_true", help="体检有 error 也照样导入")
i.set_defaults(func=do_install)
d = sub.add_parser("doctor", help="体检:量开发库(默认)或量部署包(--src),不改数据")
d.add_argument("--src", default="", help="改量部署包:JSON 目录(如 scripts/seed)")
d.add_argument("--fix", action="store_true", help="量库时把模型配置补齐到当前代码(只补缺)")
d.add_argument("--allow-drift", action="store_true", help="有 error 也返回 0(只打印不拦)")
d.set_defaults(func=do_doctor)
b = sub.add_parser("boundary", help="数据边界一览:配置表与业务表各多少行(server.sh status 用)")
b.set_defaults(func=do_boundary)
args = ap.parse_args()
args.func(args)

View File

@ -2,7 +2,7 @@
# ============================================================
# Nex Animation Studio · 服务器部署与运行(单机生产模式)
#
# ./scripts/server.sh install 装依赖 → 构建前端 → 建表 → 导入模型配置与管理员
# ./scripts/server.sh install 装依赖 → 构建前端 → 建表 → 体检并导入模型配置与管理员
# ./scripts/server.sh build 只重新构建前端(改了页面时用)
# ./scripts/server.sh start 启动(前端产物由后端一并托管,单进程)
# ./scripts/server.sh stop 停止
@ -13,12 +13,13 @@
# ./scripts/server.sh systemd 打印 systemd 单元(交给 root 安装)
#
# 选项:--port N --host ADDR --no-asr --skip-deps --skip-build --db URL
# install 专用:--only-missing(模型配置只补缺)、--allow-drift(体检不过也硬装)
#
# 与 scripts/dev.sh 的分工:dev.sh 面向开发(Vite 热更新 + uvicorn --reload),
# server.sh 面向部署(构建产物 + 不重载 + 首装数据)。两者共用 .local/run 与
# .local/logs,但 pid 名不同(server vs backend/frontend),可以并存,只要端口错开。
#
# 三个必须写在这里的为什么:
# 四个必须写在这里的为什么:
# 1) 只起一个 uvicorn 进程,绝不加 --workers。TASK_EXECUTOR=inline 时调度守护线程
# 跑在进程内,多 worker 就是 N 份守护线程同时抢同一批任务、重复派发;
# 要横向扩展请切 TASK_EXECUTOR=celery 并另起 worker(见 docker-compose.yml)。
@ -26,6 +27,10 @@
# 反向代理只需转发一处,/api、/media、/docs 与页面同源,不再有 CORS 与代理漂移。
# 3) 首装顺序是「建表 + 灌数据 → 再启动服务」。先启动也能跑,但应用首启会自己
# 生成一把模型主密钥、把 mock 播成默认,导入时就得再纠正一次默认位。
# 4) 灌数据之前先体检。部署包里的 scripts/seed/*.json 是某天的快照,代码是活水:
# 快照落后时代码新增的能力位(例如 IndexTTS2 的 voice_instruct)不会报错,
# 只会让功能在页面上凭空消失。`seed.py install` 因此先跑 doctor 再写库,
# 不过就停住——install 一旦跑过就改掉了表结构与默认位,回不到原样。
# ============================================================
set -euo pipefail
@ -41,6 +46,8 @@ ASR_URL="https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bi
WANT_ASR=1
SKIP_DEPS=0
SKIP_BUILD=0
SEED_ONLY_MISSING=0 # install:模型配置只补缺,不动服务器上已调好的同名模型
SEED_ALLOW_DRIFT=0 # install:数据体检报 error 也继续装(逃生门,默认关)
EXPLICIT_DB="${DATABASE_URL:-}"
if [ -t 1 ]; then C_G=$'\033[32m'; C_Y=$'\033[33m'; C_R=$'\033[31m'; C_B=$'\033[36m'; C_D=$'\033[2m'; C_0=$'\033[0m'
@ -133,8 +140,18 @@ seed_data() {
warn "没有 scripts/seed/:跳过数据导入,服务器将用 mock 模型 + admin/admin1234 起步"
return 0
fi
"$PYBIN" "$ROOT/scripts/seed.py" install || die "导入模型配置与管理员失败"
# 体检不在这层重复实现:seed.py install 自己会先量包(列 / 适配器 / 能力位 /
# 默认位 / 主密钥能否解开包里的密文),量不过就不写库,这里只透传两个开关。
# --only-missing:只补库里没有的模型,不覆盖这台机器上已经调好的端点与参数
# (场景:同一台服务器换新包,想带上开发机新增的模型);
# --allow-drift :体检报 error 也照装,给「服务器代码比数据集新、但确认无碍」留门。
local -a seed_args=()
[ "$SEED_ONLY_MISSING" = 1 ] && seed_args+=(--only-missing)
[ "$SEED_ALLOW_DRIFT" = 1 ] && seed_args+=(--allow-drift)
"$PYBIN" "$ROOT/scripts/seed.py" install ${seed_args[@]+"${seed_args[@]}"} \
|| die "导入模型配置与管理员失败(多半是体检没过:上面每条 error 都写了怎么修)"
info "${C_D}数据边界:表结构 + 模型配置 + 管理员。项目/镜头/媒体不在部署包里,服务器从空库开始。${C_0}"
"$PYBIN" "$ROOT/scripts/seed.py" boundary || true
}
# 单机 .env:不能直接 cp .env.example —— 那份模板是给 docker-compose 用的
@ -298,6 +315,11 @@ PY
else
info "${C_D}服务未启动,健康检查与默认模型跳过${C_0}"
fi
# 数据边界:这台机器上「部署包带来的」与「本机业务跑出来的」各多少行。
# 直接读库而不是打 HTTP——装完还没 start 时也需要知道导入了什么,
# 而且这一眼能回答部署后最常见的问题:「业务数据是不是被我覆盖掉了」。
head2 "数据边界"
"$PYBIN" "$ROOT/scripts/seed.py" boundary || warn "读不到库:先 ./scripts/server.sh install,或 --db 指对连接串"
}
verify_server() {
@ -335,7 +357,9 @@ WantedBy=multi-user.target
UNIT
}
usage() { sed -n '3,30p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; }
# 帮助 = 文件头那段注释。取范围靠「第一条 # === 到第二条 # ===」而不是写死行号:
# 上一版是 sed -n '3,30p',头注释每加一行就得回来挪一次数字,很容易忘(deploy.sh 同修)。
usage() { awk '/^# ={10,}/{n++; next} n==1{sub(/^# ?/, ""); print} n>1{exit}' "${BASH_SOURCE[0]}"; }
ACTION=start
while [ $# -gt 0 ]; do
@ -347,6 +371,8 @@ while [ $# -gt 0 ]; do
--no-asr) WANT_ASR=0 ;;
--skip-deps) SKIP_DEPS=1 ;;
--skip-build) SKIP_BUILD=1 ;;
--only-missing) SEED_ONLY_MISSING=1 ;;
--allow-drift) SEED_ALLOW_DRIFT=1 ;;
-h|--help) usage; exit 0 ;;
*) die "未知参数:$1(./scripts/server.sh --help)" ;;
esac

View File

@ -0,0 +1,139 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""通用「同一父元素下的按钮簇」尺子:不限 `.nex-action-group`(UI规范 §7 · 用户第 2 条)。
`btnrowcheck` / `footercheck` 量的是**已知的动作条**(前者认 kit 类名、后者认吸底选择器)。
这条尺子不认类名:**任何** DOM 父元素,只要它下面有 ≥2 颗**相邻的兄弟按钮**(同一概念的一组),
它们的垂直中心就必须落在同一条水平线上,或者整簇竖排等宽。
于是「页面自己手搓了一个 flex 摆按钮、忘了套 ActionGroup」这一族盲区第一次被量到——
结构上,前两道闸都扫不到它(没类名 / 不是浮层)。
判据(与 btnrowcheck 同一条尺子,只量渲染结果):
· 一簇 = 父元素的直接子节点里**连续**的按钮(`button` / `[role=button]`,中间只容得下空白与注释);
· 竖排的父容器(`flex-direction:column` / `display:grid`)与表格单元格(一行一格、格内本就一颗)不是它的对象;
· 胶囊流 / 标签流(`.nex-chipbar` / `.nex-taggroup`)不是它管的:那一排是**从固定集合里挑**的
选项(§7.1 表第三行),每个胶囊独立成行是设计,不是「一组协同动作被劈开」——与 btnrowcheck 同一条豁免;
· 同一簇按钮中心落在 ≥2 条水平线 → 立案;
· 唯一合法的多行 = **整簇竖排等宽**(每行一颗,且每颗宽 ≥ 父内容宽的 92%)。
口径(`BTNCLUSTER_CLUSTERS` 是**覆盖面**,不是违规数):每一簇都记一条,单行的也记。
第一版只 push 多行那几条,于是全站修干净之后 `PROBED` 恒等于 0,
`MIN_CLUSTERS` 那条「尺子自己瞎了」的底线**永远红**——底线把健康态当成了失灵(第 17 轮续踩过)。
用法:NEX_WIDTHS=1440,992,768,576,430 .venv/bin/python scripts/ui/btnclustercheck.py
输出:`BTNCLUSTER_CLUSTERS 全站量到的簇数 / MULTI 其中多行的 / BAD_TOTAL 违规`。
退出码:0 = 干净;1 = 有点名;2 = 一簇都没量到(尺子自己瞎了)。
"""
import json
import os
import sys
from playwright.sync_api import sync_playwright
BASE = os.environ.get("NEX_BASE", "http://127.0.0.1:5173")
WIDTHS = [int(x) for x in os.environ.get("NEX_WIDTHS", "1440,992,768,576,430").split(",")]
THEMES = os.environ.get("NEX_THEMES", "light").split(",")
USER, PWD = os.environ.get("NEX_USER", "admin"), os.environ.get("NEX_PASS", "admin1234")
ROUTES = os.environ.get("NEX_ROUTES",
"/,/assets,/models,/users,/account,/projects/10/overview,/projects/10/library,"
"/projects/10/storyboard,/projects/10/dispatch,/projects/10/timeline,"
"/projects/10/review,/projects/10/delivery,/help").split(",")
MIN_CLUSTERS = int(os.environ.get("NEX_MIN_CLUSTERS", "60"))
# dev(:5173) 首访每条路由都要现编 chunk,900ms 只够出壳 → 一簇都量不到;预览(:4188) 静态资源 900ms 够。
SETTLE = int(os.environ.get("NEX_SETTLE", "900"))
JS = r"""() => {
const out = [];
const isBtn = (el) => el && el.nodeType === 1 &&
(el.tagName === 'BUTTON' || el.getAttribute('role') === 'button') &&
!el.disabled && el.offsetParent !== null &&
// 绝对定位的角标不参与流内换行:素材封面的「右上删除 / 左下版本」本来就各占一角,
// 把它们算成一簇会永远报(第一版就是这么误伤 /assets 的 12 张封面)。
['absolute','fixed'].indexOf(getComputedStyle(el).position) < 0 &&
(() => { const r = el.getBoundingClientRect(); return r.width > 1 && r.height > 1; })();
for (const parent of document.querySelectorAll('body *')) {
const cs = getComputedStyle(parent);
if (cs.display === 'none' || cs.display === 'contents') continue;
// 竖排容器与栅格列:多行是设计,不是被劈开
if (cs.display === 'grid' || (cs.display === 'flex' && cs.flexDirection === 'column')) continue;
if (parent.closest('td,th,[role="cell"],[role="gridcell"]')) continue;
// 胶囊流 / 标签流不是「一组协同动作」,是选项集合:独立成行是设计(§7.1 第三行)
if (parent.closest('.nex-chipbar,.nex-taggroup')) continue;
// 一簇 = 直接子节点里**连续**的按钮段(中间隔着非按钮的,是两块不同的东西,分开算)。
// 「段」而不是「全部子节点都是按钮」才贴语义:素材行是 缩略图 + 标签 + 两颗按钮,
// 那两颗按钮仍然是一组,被劈开一样要报(第一版写成「全子节点皆按钮」,
// 13 条路由一簇都没量到,MIN_CLUSTERS 底线当场把它拦下——这就是底线的意义)。
const kids = [...parent.children].filter((c) => {
const s = getComputedStyle(c);
return s.display !== 'none' && s.display !== 'contents';
});
const runs = [];
let open = null;
for (const c of kids) {
if (isBtn(c)) {
if (!open) { open = []; runs.push(open); }
open.push(c);
} else open = null; // 隔着非按钮的子节点就是两簇,各自判
}
const direct = runs.filter((r) => r.length >= 2).sort((a, b) => b.length - a.length)[0];
if (!direct) continue;
const rects = direct.map((b) => b.getBoundingClientRect());
const cy = rects.map((r) => r.top + r.height / 2);
const lines = [];
for (const y of cy) if (!lines.some((l) => Math.abs(l - y) <= 2)) lines.push(y);
const pw = parent.clientWidth || 1;
const full = rects.every((r) => r.width >= pw * 0.92);
// 单行的那一簇也要记账:覆盖面(CLUSTERS)与违规(BAD)是两件事,
// 只记多行的话,页面修干净 = 尺子看起来瞎了。
out.push({
tag: parent.tagName.toLowerCase(), cls: String(parent.className).slice(0, 90),
n: direct.length, lines: lines.length,
inner: Math.round(pw), ws: rects.map((r) => Math.round(r.width)),
full, one: lines.length === 1,
bad: lines.length > 1 && !(full && lines.length === direct.length),
});
}
return out;
}"""
def main():
with sync_playwright() as p:
b = p.chromium.launch()
ctx = b.new_context(viewport={"width": WIDTHS[0], "height": 1400})
pg = ctx.new_page()
pg.goto(BASE + "/login")
pg.wait_for_selector("#login-user")
pg.fill("#login-user", USER)
pg.fill("#login-pass", PWD)
pg.click("button[type=submit]")
pg.wait_for_url(lambda u: "/login" not in u, timeout=20000)
total = multi = bad_total = 0
for theme in THEMES:
pg.evaluate("t => localStorage.setItem('nex-the', t)", theme)
for w in WIDTHS:
pg.set_viewport_size({"width": w, "height": 1400})
for route in ROUTES:
try:
pg.goto(BASE + route, wait_until="load")
pg.wait_for_timeout(SETTLE)
except Exception as e:
print(f" !! {route} @{w}: {e}")
continue
rows = pg.evaluate(JS)
bad = [r for r in rows if r["bad"]]
total += len(rows)
multi += len([r for r in rows if r["lines"] > 1])
bad_total += len(bad)
for r in bad:
print(f"SPLIT {theme}/{w} {route} <{r['tag']} class=\"{r['cls']}\"> "
f"{r['n']} 颗 / {r['lines']} 行 内宽{r['inner']} 宽{r['ws']}")
print(f"BTNCLUSTER_CLUSTERS {total} MULTI {multi} BAD_TOTAL {bad_total}")
if total < MIN_CLUSTERS:
print(f"BTNCLUSTER_CLUSTERS {total} < MIN {MIN_CLUSTERS} —— 一簇都没量到,尺子自己瞎了")
return 2
b.close()
return 1 if bad_total else 0
if __name__ == "__main__":
sys.exit(main())

View File

@ -1,15 +1,29 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""反向验证:证明三道新闸门「坏了会响、好了不响」(2026-11 第七轮起常驻)。
"""反向验证:证明七张像素闸门的十一条判据「坏了会响、好了不响」(2026-11 第七轮起常驻)。
`gridcheck` / `rhythmcheck` / `tagcheck` 都是对着渲染结果量像素的探针,
它们自己也需要被体检一次:豁免写宽一格,闸门就会永远安静地返回 0。
`gridcheck` / `rhythmcheck` / `tagcheck` / `btnrowcheck` / `footercheck` / `btnclustercheck` /
`tableaudit` 都是对着渲染结果量像素的探针,它们自己也需要被体检一次:豁免写宽一格、阈值调松一档,
闸门就会永远安静地返回 0,而页面该修的地方一个都没修。
这里不碰源码、不触发 HMR——直接在页面上种两块 fixture:
· `pb-*`(bad) :故意造出「栅格该用却自然排列 / 同一容器两档纵向间距 /
收缩错位 / 标签铺语义色块」四种缺陷,三个闸门必须**点名**到它;
· `pg-*`(good):故意造出四种**合法**形态(卡底 mt-auto 钉底、整块居中的排版、
正文 max-w-[72ch] 栏宽、.nex-chipbar 胶囊流),闸门必须放行。
· `pb-*`(bad) :故意造出十二种缺陷——同族子块该用栅格却自然排列、流程条横向滚动、
同一行裸控件没坐进控件行(中心差 35px)、同一容器两档纵向间距、
收缩错位、标签铺语义色块、按钮组被劈成 2+1、
格子里并排内容越出单元格、整句散文当只读标签捅出容器右缘、
卡头行里还剩一整块没挪走却先把标题切成两行、
header 里那组横排按钮被劈成 2+1(第 17 轮删掉的旧豁免不许复活)、
浮层底部三颗按钮挤成 2+1(footercheck 管的那一族)、
不带任何类名的一簇按钮挤成 2+1(btnclustercheck 管的那一族)
——十二条缺陷,每条判据必须**点名**到它;
· `pg-*`(good):故意造出十二种**合法**形态(卡底 mt-auto 钉底、整块居中的排版、
正文 max-w-[72ch] 栏宽、.nex-chipbar 胶囊流、
容器自适应的流程条、让位后与字段同行的复选框、
放得下的「进度条 + 百分数」单元格、
kit Tag 自己收窄成 ellipsis 的长标签、
右端整块掉到第二行之后标题拿到整行的卡头、
整组竖排等宽的按钮组(现行唯一那条豁免)、
整组竖排等宽的浮层底部(ActionGroup 翻竖排之后的形状),闸门必须放行。
任何一条对不上就退出 1——说明闸门瞎了或者过敏,先修闸门再谈页面。
用法:
@ -39,6 +53,10 @@ def load(mod_name: str):
tagcheck = load("tagcheck")
rhythmcheck = load("rhythmcheck")
gridcheck = load("gridcheck")
btnrowcheck = load("btnrowcheck")
footercheck = load("footercheck")
btnclustercheck = load("btnclustercheck")
tableaudit = load("tableaudit")
FIXTURE = r"""() => {
const old = document.getElementById('nex-gateprobe'); if (old) old.remove();
@ -78,10 +96,136 @@ FIXTURE = r"""() => {
<div style="height:30px;max-width:200px"></div>
<div style="height:30px;max-width:240px"></div>
</div>
<div class="nex-action-group pb-btn" style="display:flex;flex-direction:row;flex-wrap:wrap;gap:8px;width:260px">
<button class="ant-btn" style="width:120px;height:32px">甲</button>
<button class="ant-btn" style="width:120px;height:32px">乙</button>
<button class="ant-btn" style="width:120px;height:32px">丙</button>
</div>
<!-- 判据① 唯一的豁免(第 17 轮起):竖排等宽里子项本来就在不同水平线,必须放行 -->
<div class="nex-action-group ant-flex-vertical pg-stack"
style="display:flex;flex-direction:column;gap:8px;width:260px">
<button class="ant-btn" style="width:260px;height:32px">甲</button>
<button class="ant-btn" style="width:260px;height:32px">乙</button>
</div>
<!-- 被删掉的那条「<header> 里的组在 <1024 允许分行」不许悄悄回来:
坐在 header 里的横排组被劈成 2+1,一样要响 -->
<header><div class="nex-action-group pb-header"
style="display:flex;flex-direction:row;flex-wrap:wrap;gap:8px;width:260px">
<button class="ant-btn" style="width:120px;height:32px">甲</button>
<button class="ant-btn" style="width:120px;height:32px">乙</button>
<button class="ant-btn" style="width:120px;height:32px">丙</button>
</div></header>
<div class="nex-chipbar pg-chipbar" style="display:flex;flex-direction:row;flex-wrap:wrap;gap:8px;width:900px">
<span class="nex-chip ant-tag ant-tag-checkable" style="display:inline-block;width:80px;height:24px">甲</span>
<span class="nex-chip ant-tag ant-tag-checkable" style="display:inline-block;width:210px;height:24px">乙乙乙</span>
<span class="nex-chip ant-tag ant-tag-checkable" style="display:inline-block;width:120px;height:24px">丙丙</span>
</div>
<div role="list" class="pb-rail" style="display:flex;flex-direction:row;gap:8px;width:400px;
overflow-x:auto">
<div style="flex:none;width:200px;height:30px">完整视频</div>
<div style="flex:none;width:200px;height:30px">音效</div>
<div style="flex:none;width:200px;height:30px">字幕</div>
<div style="flex:none;width:200px;height:30px">交付包</div>
</div>
<div role="list" class="pg-rail" style="display:grid;width:900px;gap:8px;
grid-template-columns:repeat(auto-fill,minmax(140px,1fr))">
<div style="min-width:0;height:30px">完整视频</div>
<div style="min-width:0;height:30px">音效</div>
<div style="min-width:0;height:30px">字幕</div>
<div style="min-width:0;height:30px">交付包</div>
</div>
<div class="ant-row nex-form-row pb-ctl" style="display:flex;width:700px">
<div class="ant-col" style="width:300px">
<div class="ant-form-item">
<div class="ant-form-item-label" style="height:30px;line-height:30px;padding:0">环境声</div>
<div class="ant-form-item-control"><div class="ant-form-item-control-input"
style="height:32px"><input class="ant-input" style="width:100%" value="底噪"></div></div>
</div>
</div>
<div class="ant-col" style="width:300px">
<label class="ant-checkbox-wrapper" style="display:inline-block;margin-top:0;height:auto">启用字幕</label>
</div>
</div>
<div class="ant-row nex-form-row pg-ctl" style="display:flex;width:700px">
<div class="ant-col" style="width:300px">
<div class="ant-form-item">
<div class="ant-form-item-label" style="height:30px;line-height:30px;padding:0">环境声</div>
<div class="ant-form-item-control"><div class="ant-form-item-control-input"
style="height:32px"><input class="ant-input" style="width:100%" value="底噪"></div></div>
</div>
</div>
<div class="ant-col" style="width:300px">
<label class="ant-checkbox-wrapper" style="display:flex;align-items:center;height:32px;margin-top:30px">启用字幕</label>
</div>
</div>
<div class="nex-taggroup" style="width:220px"><span class="ant-tag pb-spill"
style="white-space:nowrap">反向验证长标签整句散文当只读标签必然捅出容器右缘</span></div>
<div class="nex-taggroup" style="width:220px"><span class="ant-tag nex-tag pg-spill"
><span class="nex-tag-text">合法长标签整句散文当只读标签由 kit 收在容器内</span></span></div>
<div class="ant-card" style="width:320px"><div class="ant-card-head-title">pb-tspill</div>
<div class="ant-table-wrapper"><div class="ant-table-content">
<table style="table-layout:fixed;width:300px"><tbody class="ant-table-tbody"><tr>
<td style="width:300px;padding:8px;white-space:nowrap;text-align:right">
<div style="display:inline-block;width:284px;height:6px;background:#1677ff"></div>
<small class="pb-tspill">100%</small>
</td>
</tr></tbody></table>
</div></div>
</div>
<div class="ant-card" style="width:320px"><div class="ant-card-head-title">pg-tspill</div>
<div class="ant-table-wrapper"><div class="ant-table-content">
<table style="table-layout:fixed;width:300px"><tbody class="ant-table-tbody"><tr>
<td style="width:300px;padding:8px;white-space:nowrap;text-align:right">
<div style="display:inline-block;width:220px;height:6px;background:#1677ff"></div>
<small class="pg-tspill">100%</small>
</td>
</tr></tbody></table>
</div></div>
</div>
<!-- 判据②(btnrowcheck.HEAD):320 的卡头里标题只剩 82px,
「还有一整块可以挪下去」却把标题切成两行 = 必须响 -->
<div class="ant-card nex-panel" style="width:320px"><div class="ant-card-head">
<div class="ant-card-head-wrapper" style="display:flex;flex-wrap:wrap">
<div class="ant-card-head-title" style="flex:1 1 0">
<span>pb-head镜头质检结论汇总清单表</span></div>
<div class="ant-card-extra" style="flex:0 0 auto;width:190px">重新质检 / 导出报告</div>
</div></div>
</div>
<!-- 浮层底部(footercheck):和页头同一个毛病,只是它长在抽屉里。
300 宽 260 内宽里三颗 120 的按钮挤成 2+1 = 必须响 -->
<div class="ant-drawer-footer pb-footer"
style="width:300px;padding:12px 20px;display:flex;flex-wrap:wrap;gap:8px;justify-content:flex-end">
<button class="ant-btn" style="width:120px;height:32px">甲</button>
<button class="ant-btn" style="width:120px;height:32px">乙</button>
<button class="ant-btn" style="width:120px;height:32px">丙</button>
</div>
<!-- 裸按钮簇(btnclustercheck):没有 kit 类名、不是浮层底部,前两道按钮闸结构上扫不到。
260px 里三颗 120 的按钮挤成 2+1 = 必须响(证明这把新尺子真的在看 DOM) -->
<div class="pb-cluster" style="width:260px;display:flex;flex-wrap:wrap;gap:8px">
<button class="ant-btn" style="width:120px;height:32px">甲</button>
<button class="ant-btn" style="width:120px;height:32px">乙</button>
<button class="ant-btn" style="width:120px;height:32px">丙</button>
</div>
<!-- 同一簇整组换行、每颗占满内宽(ActionGroup 的竖排档就是这个形状)= 必须放行 -->
<div class="pg-cluster" style="width:260px;display:flex;flex-wrap:wrap;gap:8px">
<button class="ant-btn" style="width:100%;height:32px">甲</button>
<button class="ant-btn" style="width:100%;height:32px">乙</button>
<button class="ant-btn" style="width:100%;height:32px">丙</button>
</div>
<!-- 底部交给 ActionGroup 之后窄屏的样子:整组竖排等宽 = 必须放行 -->
<div class="ant-drawer-footer pg-footer"
style="width:300px;padding:12px 20px;display:flex;flex-direction:column;gap:8px">
<button class="ant-btn" style="width:100%;height:32px">甲</button>
<button class="ant-btn" style="width:100%;height:32px">乙</button>
</div>
<!-- 同一句长标题,右端整块掉到第二行(kit 的 nex-head-stack 就是这个形状):
标题拿到整行,折行是排版 = 必须放行 -->
<div class="ant-card nex-panel" style="width:320px"><div class="ant-card-head">
<div class="ant-card-head-wrapper" style="display:flex;flex-wrap:wrap;row-gap:8px">
<div class="ant-card-head-title" style="flex:1 1 auto">
<span>pg-head模型配置已迁移至独立管理中心请前往模型控制台</span></div>
<div class="ant-card-extra" style="flex:1 1 100%">重新质检 / 导出报告</div>
</div></div>
</div>`;
(document.querySelector('main') || document.body).appendChild(host);
return [...host.querySelectorAll('[class]')].length;
@ -89,7 +233,14 @@ FIXTURE = r"""() => {
def names(rows, key):
"""把检出结果摊平成「元素标记串」,再用 fixture 的类名点名。"""
"""把检出结果摊平成「元素标记串」,再用 fixture 的类名点名。
`key` 可以是字段名,也可以是函数:tableaudit 的 PROBE 会把页面上**每一张**表
都返回(不管有没有违规),按 `title` 摊平的话合法 fixture 也会出现在串里,
「必须放行」永远对不上——所以给它一个只摊平违规明细的函数。
"""
if callable(key):
return " | ".join(str(x) for r in rows for x in key(r))
return " | ".join(str(r.get(key, "")) for r in rows)
@ -113,12 +264,48 @@ def main() -> int:
checks = [
("tagcheck", tagcheck.JS, "el", [("pb-tag", True), ("ant-input", False)]),
# 整句散文当只读标签、捅出容器右缘必须响;换成 kit Tag(max-width+ellipsis 自己收窄)必须放行
("tagcheck.SPILL", tagcheck.SPILL, "el",
[("pb-spill", True), ("pg-spill", False)]),
("rhythmcheck.GAP", rhythmcheck.GAP, "el",
[("pb-gap", True), ("pg-pin", False)]),
("rhythmcheck.RAG", rhythmcheck.RAG, "el",
[("pb-rag", True), ("pg-center", False), ("pg-measure", False)]),
("gridcheck", gridcheck.JS, "el",
[("pb-grid", True), ("pg-chipbar", False)]),
[("pb-grid", True), ("pg-chipbar", False),
# 流程条横滚必须响;容器自适应 grid 铺开的流程条必须放行
("pb-rail", True), ("pg-rail", False),
# 同行裸复选框贴着标签行(中心差 35px)必须响;
# 让出标签块、坐进 32px 控件行的必须放行(glue ⑥ 的形态)
("pb-ctl", True), ("pg-ctl", False)]),
# 按钮组被劈成 2+1 必须响;栅格那块(三种宽度三种控件的横排)与胶囊流不是它管的
("btnrowcheck", btnrowcheck.JS, "el",
[("pb-btn", True), ("pb-grid", False), ("pg-chipbar", False)]),
# 唯一那条豁免必须放行;旧那条「父级是 header 的组在 <1024 允许分行」
# 第 17 轮删了,这里钉住它不许悄悄复活:header 里的横排组被劈成 2+1 一样要响
("btnrowcheck.exempt", btnrowcheck.JS, "el",
[("pg-stack", False), ("pb-header", True)]),
# 卡头标题被切成两行(行里还剩着一整块没挪走)必须响;
# 右端整块掉到下一行、标题拿到整行的必须放行——判据②的两面
("btnrowcheck.HEAD", btnrowcheck.HEAD, "el",
[("pb-head", True), ("pg-head", False)]),
# 浮层底部(第 17 轮补):抽屉/对话框吸底那几条按钮以前不在任何闸门的路线表里,
# 现在 Overlay.DRAWER_ACTIONS = ActionGroup,底部由 footercheck 开层量。
# 摊平用函数:只看判据算下来真违规的那几条的类名。
("footercheck", footercheck.JS,
(lambda r: [r["cls"]] if r.get("bad") else []),
[("pb-footer", True), ("pg-footer", False)]),
# 裸按钮簇(第 17 轮续):不带任何 kit 类名的一组按钮被劈成 2+1 必须响;
# 整簇换行、每颗占满内宽必须放行——这把尺子的价值全在「不认类名」,
# 没有这对 fixture,它绿了也证明不了自己在看东西。
("btnclustercheck", btnclustercheck.JS,
(lambda r: [r["cls"]] if r.get("bad") else []),
[("pb-cluster", True), ("pg-cluster", False)]),
# 格子里并排内容越出单元格 / 互相压叠必须响,放得下必须放行。
# 摊平用函数:只看 spill 明细里的元素标识,不看那些本来就没违规的表名。
("tableaudit", tableaudit.PROBE,
lambda r: [it["k"] for it in r.get("spill", [])],
[("pb-tspill", True), ("pg-tspill", False)]),
]
for label, js, key, expectations in checks:
rows = pg.evaluate(js)
@ -138,7 +325,7 @@ def main() -> int:
print("GATEPROBE_FAIL", " ".join(fails))
print("→ 闸门本身出问题:不是漏检(豁免写宽了)就是误报(豁免没生效),先修闸门")
return 1
print("GATEPROBE_OK 4/4 闸门坏了会响、好了不响")
print(f"GATEPROBE_OK {len(checks)}/{len(checks)} 闸门坏了会响、好了不响")
return 0

View File

@ -20,6 +20,22 @@
btn 按钮组本就该按内容自然排列(同概念不跨行由 visualcheck 的 ActionGroup 断言管)
span .nex-chipbar / .nex-taggroup 里的胶囊与只读标签:筛已有内容 = 胶囊流,
宽度**必须**跟着文案走,等宽反而读不出区别
判据②(同一句话的另一半:横滚不是栅格):`[role="list"]` 是 kit `Steps`
流程条专用(全站唯一),它是一串**等宽重复卡片**,必须容器自适应铺开。
命中条件(任一):容器自身横向可滚 `scrollWidth-clientWidth > 2`;
或有子块右缘越出容器右缘 > 2px。
为什么单独立一条:横滚容器里 `flex-wrap` 根本不折行,判据①(看 rag/折行)
永远安静——第七轮实测流程条 12 格在 1440 宽度下 `scrollLeft=126`、
总控台那条 526px 容器装 1244px 内容,**9 格藏在视野外**而下面写着「已完成 10/12」,
正是判据① 看不见的那类「该用 grid 却在自然排列」。
判据③(同一行表单的「控件不对齐」):`.nex-form-row` 的一条视觉行里,
带标签字段的控件行(`.ant-form-item-control-input`)与**裸控件**(复选框 / 开关 /
按钮 / 下拉……直接坐在 Col 里、自己没标签)中心线相差 > 4px 立案。
为什么必须量像素:FormRow 的列是块级 Col,调用点在裸控件上写的
`self-center` / `self-end` 在块容器里根本不参与对齐——分镜检查器「环境声 / 启用字幕」
那颗复选框实测顶在标签行,和右边输入框的中心差 35px,写 class 的人以为对齐了。
现在由 app.css 表单 glue ⑥ 统一让位(让出标签块再在 controlHeight 里垂直居中),
这条判据盯的是「又有人在调用点自己写对齐」或「glue 被改坏」。
用法:
NEX_THEMES=light NEX_WIDTHS=1440,1280,1024 .venv/bin/python scripts/ui/gridcheck.py
退出码:0 = 干净,1 = 有立案。
@ -112,8 +128,65 @@ JS = r"""() => {
texts:set.slice(0,6).map(k=>((k.innerText||'').trim().slice(0,10)))});
}
}
/* 判据②:重复卡片排成一条 = 容器自适应 grid,横向滚动 / 越界一律立案。
`role="list"` 全站只有 kit 的 Steps(流程条)在用;格子宽窄由 `.nex-steps`
的 auto-fill minmax 轨道决定,容器宽度变了就多排几列,而不是把尾巴滚掉。
rag 复用成「容器还能滚多少 px」,misalign 复用成「子块越出右缘多少 px」。 */
// 不加 main 前缀:流程条现在住在「项目概况」抽屉里(antd Drawer 挂到 body 的 portal,
// 实测 inMain=false),只查 main 会正好漏掉唯一那条长文流程条。
for (const el of document.querySelectorAll('[role="list"]')) {
const cs=getComputedStyle(el);
if (cs.display==='none'||cs.visibility==='hidden') continue;
const box=el.getBoundingClientRect();
if (box.width<40) continue;
const kids=[...el.children].filter(c=>{const k=getComputedStyle(c),r=c.getBoundingClientRect();
return k.display!=='none'&&k.position!=='absolute'&&k.position!=='fixed'&&r.height>4&&r.width>20;});
if (kids.length<3) continue;
const over=Math.max(0, Math.round(el.scrollWidth-el.clientWidth));
const spill=Math.max(0, ...kids.map(k=>Math.round(k.getBoundingClientRect().right-box.right)));
if (over<=2 && spill<=2) continue;
out.push({kind:'rail',n:kids.length,rag:over,misalign:spill,rows:1,
el:el.tagName.toLowerCase()+'.'+cls(el).slice(0,70),
widths:kids.slice(0,8).map(k=>Math.round(k.getBoundingClientRect().width)),
texts:kids.slice(0,6).map(k=>((k.innerText||'').trim().replace(/\s+/g,'').slice(0,10)))});
}
/* 判据③:一行表单里的裸控件必须和同排字段的控件行对齐(kind=ctl)。
rag/misalign 都复用成「离控件中心线差多少 px」;按视觉行分组,窄屏折行之后
每行各量各的。比中心线而不是顶边:复选框 22 高、输入框 32 高,比顶边会误报。 */
for (const row of document.querySelectorAll('.nex-form-row')) {
const cs=getComputedStyle(row);
if (cs.display==='none'||cs.visibility==='hidden') continue;
const cols=[...row.children].filter(c=>c.matches('.ant-col')&&c.getBoundingClientRect().height>4);
if (cols.length<2) continue;
const lines=[];
for (const c of cols) {
const t=c.getBoundingClientRect().top;
const g=lines.find(l=>Math.abs(l.t-t)<=10); if (g) g.cs.push(c); else lines.push({t,cs:[c]});
}
for (const l of lines) {
if (l.cs.length<2) continue;
const labeled=[], bare=[];
for (const c of l.cs) {
const ctl=c.querySelector('.ant-form-item-control-input');
if (ctl) { labeled.push(ctl); continue; }
const k=[...c.children].find(x=>{const xg=getComputedStyle(x);
return xg.display!=='none'&&xg.position!=='absolute'&&xg.position!=='fixed'&&x.getBoundingClientRect().height>4;});
if (k&&k.matches('.ant-checkbox-wrapper,.ant-switch,.ant-btn,.ant-select,.ant-input,.ant-input-number,.ant-radio-group,.nex-chip')) bare.push(k);
}
if (!labeled.length||!bare.length) continue;
const mid=(e)=>{const r=e.getBoundingClientRect();return r.top+r.height/2};
const base=labeled.reduce((a,e)=>a+mid(e),0)/labeled.length;
const off=Math.round(Math.max(...bare.map(e=>Math.abs(mid(e)-base))));
if (off<=4) continue;
out.push({kind:'ctl',n:labeled.length+bare.length,rag:off,misalign:off,rows:1,
el:'div.'+cls(row).slice(0,70),
widths:l.cs.map(c=>Math.round(c.getBoundingClientRect().width)).slice(0,8),
texts:[...labeled,...bare].map(e=>(e.innerText||String(e.className)||'').trim().slice(0,12)).filter(Boolean).slice(0,6)});
}
}
return out;
}"""
}
"""
def main() -> int:
@ -155,8 +228,13 @@ def main() -> int:
total = sum(seen.values())
print("GRID_TOTAL", total, "unique", len(seen))
if total:
print("→ 这些容器同族子块 ≥3 却没走栅格:改 Ctlbar cols={n} / Row+Col / OptionGrid,"
print("→ kind≠rail:同族子块 ≥3 却没走栅格,改 Ctlbar cols={n} / Row+Col / OptionGrid,"
"或确认它属于胶囊流(应在 .nex-chipbar / .nex-taggroup 里)")
print("→ kind=rail:流程条在横滚/越界(rag=还能滚 px,mis=越界 px),"
"格子别钉宽度,交给 .nex-steps 的 auto-fill minmax 轨道")
print("→ kind=ctl:同一行的裸控件没坐进控件行(rag=离控件中心线 px),"
"别在调用点写 self-center/self-end,交给 app.css 表单 glue ⑥")
return 1
return 0

View File

@ -11,9 +11,9 @@
· 主题锁 **light**:12 张彼此要一致,且浅色才是这套「标准现代」皮肤的门面。
· 拍摄主角 = 项目 12《告诉你个小秘密第2期》:已交付、12 个节点全通、4 镜头 4 合格、
117 任务、5 条导出记录、有真实剧照。空草稿项目拍出来一片 0,半程项目缺内容。
· 五个项目子页(分镜 / 调度 / 质检 / 时间线 / 导出)**先收起「项目概况」再拍**:
那条折叠区(四张统计卡 + 流程进度 12 格)在所有子页顶部都一样,不收起的话每张
构图雷同、真正要教的看板被推到首屏之外。`/projects/12/overview` 反过来要展开。
· 项目子页**不再需要收起任何东西**(2026-11 第十一轮):项目身份 / 指标 / 流程条
从每一页顶部收进顶栏那颗项目胶囊点开的「项目概况」抽屉,`展开概况` 那颗按钮整颗删了,
子页进来就是看板本身。以前那段「先收起概况」的口径随按钮一起作废。
· 资产管理三张拍的是 **平台资产库**(/assets 的人物 / 场景 / 声线三页签),沿用历史选题。
用法:`.venv/bin/python scripts/ui/helpshots.py [输出目录]`
@ -47,7 +47,6 @@ SHOTS = [
("timeline", f"/projects/{PROJECT}/timeline"),
("delivery", f"/projects/{PROJECT}/delivery"),
]
COLLAPSED = {"storyboard", "storyboard-inspector", "dispatch", "review", "timeline", "delivery"}
ASSET_TABS = {"scene-assets": "场景", "voice-assets": "声线"}
@ -69,8 +68,6 @@ def main() -> int:
tab = ASSET_TABS.get(name)
if tab:
click_tab(pg, tab)
if name in COLLAPSED:
collapse_summary(pg)
save(pg, name)
b.close()
return 0
@ -112,15 +109,6 @@ def click_tab(pg, label: str) -> None:
pg.wait_for_timeout(1200)
def collapse_summary(pg) -> None:
"""收起 ProjectDetail 的「项目概况」。ProjectDetail 在子路由间保持挂载,
所以第一张收起后其余几张进来就是收起态,这里点不到按钮是正常的。"""
btn = pg.query_selector('button:has-text("收起概况")')
if btn:
btn.click()
pg.wait_for_timeout(700)
def save(pg, name: str) -> None:
pg.wait_for_timeout(900)
pg.evaluate("() => window.scrollTo(0,0)")

View File

@ -9,6 +9,8 @@ build、classaudit 全都测不出来,visualcheck 也只管溢出不管行高
红线钉死(见 docs/UI规范.md §13.2 R17):
1) 数据行最高 ≤ NEX_ROW_H_MAX(默认 84px ≈ 正文两行 + 一行次要元信息);
2) 横向溢出 ≤ NEX_SCROLL_SLACK(默认 40px,定宽列合计必须回到容器内)。
3) 一个格子里并排 ≥2 个子元素时:任何一个都不许越出该格内容盒 > 2px,
也不许互相压叠 > 2px(nowrap 的单元格会把整条线顶出盒子,2+3 一起看才抓得住)。
空态行(.ant-table-placeholder)是 antd 自己那条 60px 占位,不算数据行,跳过。
用法:
@ -72,9 +74,33 @@ PROBE = r"""() => [...document.querySelectorAll('.ant-table-wrapper')].map((w, i
});
return { h: Math.round(r.getBoundingClientRect().height), cells };
}).sort((a, b) => b.h - a.h)[0] || null;
/* 判据③:格子里的并排内容不许越出自己的盒子,也不许互相压叠。
症状(首页项目列表「进度」列):条是占满 100% 的行内盒,右边又跟了百分数,
单元格 nowrap 不折行,整条线被 text-align:right 往左推——百分数越出内容盒右缘
最多 32px,压到「时长」那一列的右边界上。行高和列宽都正常,只有像素看得见。 */
const spill=[];
w.querySelectorAll('.ant-table-tbody tr td').forEach(td=>{
if (td.closest('tr')?.className.includes('placeholder')) return;
const kids=[...td.children].filter(k=>{const kg=getComputedStyle(k),r=k.getBoundingClientRect();
return kg.display!=='none'&&kg.position!=='absolute'&&kg.position!=='fixed'&&r.height>2&&r.width>2;});
if (kids.length<2) return;
const r=td.getBoundingClientRect(), tg=getComputedStyle(td);
const L=r.left+parseFloat(tg.paddingLeft), R=r.right-parseFloat(tg.paddingRight);
kids.forEach(k=>{const kr=k.getBoundingClientRect();
const overR=Math.round(kr.right-R), overL=Math.round(L-kr.left);
if (overR>2||overL>2) spill.push({col:td.cellIndex,t:(td.textContent||'').trim().slice(0,14),
k:k.tagName+'.'+String(k.className).slice(0,26),overR,overL});});
for (let i=0;i<kids.length;i++) for (let j=i+1;j<kids.length;j++){
const a=kids[i].getBoundingClientRect(), bb=kids[j].getBoundingClientRect();
const ox=Math.round(Math.min(a.right,bb.right)-Math.max(a.left,bb.left));
const oy=Math.round(Math.min(a.bottom,bb.bottom)-Math.max(a.top,bb.top));
if (ox>2&&oy>2) spill.push({col:td.cellIndex,t:(td.textContent||'').trim().slice(0,14),
k:kids[i].tagName+'×'+kids[j].tagName,overR:ox,overlap:true});}
});
const title = (w.closest('.ant-card')?.querySelector('.ant-card-head-title')?.textContent || '').trim().slice(0, 18);
return { i, title, rows: rows.length,
boxW: Math.round(w.getBoundingClientRect().width),
spill,
clientW: body ? body.clientWidth : 0, scrollW: body ? body.scrollWidth : 0,
maxRowH: tall ? tall.h : 0, head, tall };
})"""
@ -115,6 +141,8 @@ def main() -> int:
flags.append(f"行高超 {ROW_H_MAX}")
if over_w > SCROLL_SLACK:
flags.append(f"横向溢出 {over_w}")
if t["spill"]:
flags.append("格子内容越界 " + str(len(t["spill"])) + " 处")
mark = " ⚠ " + "、".join(flags) if flags else ""
print(f'#{t["i"]} 「{t["title"]}」 容器{t["boxW"]} 可视{t["clientW"]}/内容{t["scrollW"]} '
f'行{t["rows"]} 最高行{t["maxRowH"]}{mark}')
@ -126,6 +154,10 @@ def main() -> int:
key=lambda x: x["h"], default=None)
if worst:
print(f' 元凶 h={worst["h"]} {worst["s"]}')
for sp in t["spill"][:4]:
print(' 越界 第', sp["col"], '格', repr(sp["t"]), sp["k"],
('压叠宽 ' if sp.get("overlap") else '右溢 ') + str(sp["overR"]) + 'px',
('左溢 ' + str(sp["overL"]) + 'px') if sp.get("overL") else '')
if flags:
bad += 1
browser.close()

View File

@ -19,9 +19,25 @@
只看合成底不行——标签坐在一块蓝底信息块上时会整片误判。
2) **文字色**:合成后极差 ≤ 40(正文灰 18、语义绿 #52c41a 166)。
唯一例外:**选中态胶囊**(`.ant-tag-checkable-checked`)——点亮就是它表达「选了这颗」的方式。
**判据二(`SPILL`):标签不许捅出所坐容器的右缘**(第 16 轮加的,起因是 /assets 场景卡)。
症状:场景卡把「光线 / 时段 / 色板」缝成一枚只读标签,而 `lighting` 本身是整句散文
(「红灯笼暖橙主光从桌面…」),nowrap 的标签比卡片内容盒还宽 204px,
文字冲出卡片右缘被裁掉,用户读到的是半句话。
口径:只读标签行只放**短标签**;成句的说明走 `<Clamp>` + 悬停 title。
kit 侧同时给了兜底(`app.css` 的 `.nex-tag.ant-tag{max-width:100%}`
+ `.nex-tag-text` 的 ellipsis),所以这条闸现在是「回归探针」:
谁绕过 kit 自己写 `.ant-tag`、或者把兜底删了,它就得响。
判定(两条子规则,命中任一即立案):
· S1 标签右缘 > 最近**块级**父盒的内容盒右缘(>2px)。祖先链里有**真在横滚**的容器
(overflow-x:auto/scroll 且 scrollWidth>clientWidth)就整支跳过——那里的「越界」
是设计,用户自己滚。⚠ 别只看 overflow-x:内容区 overflow-y:auto 会让浏览器把
overflow-x 也算成 auto,那样 S1 会在 main 里全片跳过、永远抓不到东西。
· S2 标签组(`.nex-taggroup` / `.nex-chipbar`)自身 `scrollWidth-clientWidth` > 2
=组里有一枚成员比整组还宽,wrap 也救不回来。
用法:
NEX_THEMES=light,dark .venv/bin/python scripts/ui/tagcheck.py
退出码:0 = 干净,1 = 有立案。
退出码:0 = 干净,1 = 有立案(两条判据任一有立案)。
"""
import os
import sys
@ -105,8 +121,49 @@ JS = r"""() => {
}"""
SPILL = r"""() => {
const cls=(el)=>(typeof el.className==='string'?el.className:'').trim().split(/\s+/).slice(0,4).join('.');
const row=(el,rule,over)=>({el:cls(el).slice(0,60), rule, over,
text:(el.innerText||'').trim().replace(/\s+/g,' ').slice(0,28)});
const blockish=(el)=>{ const d=getComputedStyle(el).display;
return !/^(inline|contents)/.test(d) && el.getBoundingClientRect().width>0; };
const out=[];
/* S1 逐枚标签:右缘不许越过最近块级父盒的内容盒 */
for (const el of document.querySelectorAll('main .ant-tag, .ant-tag')) {
const r=el.getBoundingClientRect();
if (!r.width||!r.height) continue;
/* 只有**真的在横向滚动**的容器才算「设计上允许越界」(内容比容器宽)。
⚠ 不能只看不看 overflow-x:内容区是 overflow-y:auto,浏览器会把它的
overflow-x 一起算成 auto——按 overflow-x 判会整片跳过,S1 永远抓不到东西。 */
let scrolled=false;
for (let cur=el.parentElement; cur && cur!==document.documentElement; cur=cur.parentElement) {
const cs=getComputedStyle(cur);
if ((cs.overflowX==='auto'||cs.overflowX==='scroll') && cur.scrollWidth>cur.clientWidth+1)
{ scrolled=true; break; }
}
if (scrolled) continue;
let par=el.parentElement;
while (par && par!==document.documentElement && !blockish(par)) par=par.parentElement;
if (!par) continue;
const pcs=getComputedStyle(par), pr=par.getBoundingClientRect();
const right=pr.right-parseFloat(pcs.paddingRight||0)-parseFloat(pcs.borderRightWidth||0);
const over=Math.round(r.right-right);
if (over>2) out.push(row(el,'S1',over));
}
/* S2 标签组:组里有一枚比整组还宽(wrap 也放不下) */
for (const el of document.querySelectorAll('.nex-taggroup, .nex-chipbar')) {
const r=el.getBoundingClientRect();
if (!r.width) continue;
const over=el.scrollWidth-el.clientWidth;
if (over>2) out.push(row(el,'S2',Math.round(over)));
}
return out;
}"""
def main() -> int:
bad = []
spilled = []
with sync_playwright() as pw:
b = pw.chromium.launch()
pg = b.new_context(viewport={"width": 1440, "height": 900}).new_page()
@ -122,6 +179,9 @@ def main() -> int:
for row in pg.evaluate(JS):
row["where"] = f"/login/{theme}"
bad.append(row)
for row in pg.evaluate(SPILL):
row["where"] = f"/login/{theme}"
spilled.append(row)
pg.fill("#login-user", USER)
pg.fill("#login-pass", PWD)
pg.click("button[type=submit]")
@ -140,6 +200,9 @@ def main() -> int:
for row in pg.evaluate(JS):
row["where"] = f"{route}@{width}/{theme}"
bad.append(row)
for row in pg.evaluate(SPILL):
row["where"] = f"{route}@{width}/{theme}"
spilled.append(row)
b.close()
seen = set()
@ -151,11 +214,21 @@ def main() -> int:
print(f"TINT {x['where']:<32} {x['el'][:56]:<56} bg={x['bg']}(chroma {x['bgc']}) "
f"fg={x['fg']}(chroma {x['fgc']}) «{x['text']}»")
print("TAG_TINTED_TOTAL", len(bad), "unique", len(seen))
seens = set()
for x in spilled:
k = (x["where"].split("@")[0], x["el"], x["text"])
if k in seens:
continue
seens.add(k)
print(f"SPILL {x['where']:<32} {x['rule']} {x['over']:>5}px {x['el'][:48]:<48} «{x['text']}»")
print("TAG_SPILL_TOTAL", len(spilled), "unique", len(seens))
if bad:
print("→ 标签又铺上语义色块了:底色一律走 kit Tag(中性 fill-tertiary + 圆点),"
"别在页面上写 antd 的 <Tag color=\"success\">")
return 1
return 0
if spilled:
print("→ 标签捅出容器右缘:只读标签行只放短标签,成句的说明改走 <Clamp>+title;"
"自己写的 .ant-tag 没有 kit 的 max-width 兜底,一律换成 kit Tag")
return 1 if (bad or spilled) else 0
if __name__ == "__main__":

View File

@ -313,6 +313,13 @@ LAYOUT = r"""() => {
const r = el.getBoundingClientRect();
if (r.width < 2 || r.height < 2) return;
if (el.closest('.nex-prose-value')) return; // 整句型选项值:见上面的豁免说明
// 顶栏那颗项目胶囊(.nex-console)属于**外壳**,不是页面里的控件:56px 高的 Header
// 要同时装项目名 + 状态 + 12 段轨道 + 百分比 + 「当前 · …」整句(自然宽 651px),
// 而它自己只分到 327~640px。全文三条路都在:按钮 title(《名字》流程进度 83% ·
// 已完成 10/12 · 当前节点:X)、两段文字各自的 ellipsis tooltip、点开就是「项目概况」抽屉。
// 与「菜单不在名单里:侧栏项目名截断是设计」同一条口径(见本函数末行注释)。
// 它管住的是「不许塌成 30px 的残字」——那由组件里 flex-none 的项目名保证(实测 ≥149)。
if (el.closest('.nex-console')) return;
if (overflows(el)) return;
[...el.querySelectorAll('*')].some(overflows);
});