PRD / TRD

modelzoo

产品与技术说明书 · PRD + TRD

查模型，跟适配，看性能。

3核心数据对象

7适配阶段

4模型详情区域

文档版本：v0.1 讨论稿｜用途：先对齐产品范围与业务规则，再指导研发和验收。

本稿基于 modelzoo 当前工程整理，采用参考说明书“产品范围—核心规则—功能设计—技术设计—验收”的组织方式。正文描述目标需求；需确认的取舍和工程差异集中列于附录 B，供下一轮逐项调整。页面插图来自工程的只读演示数据，不作为真实适配或性能结论。

PRD

第一部分 · 产品定位与范围

1.1 背景与目标

modelzoo 将模型清单、配置级适配进展和性能结果放到同一个入口。使用者先找到模型，再确认具体硬件、框架、精度和软件版本下的支持情况，并查看对应测试记录，减少在清单、沟通记录和测试表之间反复查找。

交付、产品及方案人员：查模型、查版本、查支持范围，引用对应配置和测试依据。
适配研发人员：维护部署配置和适配阶段，记录进展与状态变化。
测试人员：按适配任务记录测试条件、性能指标和精度结论，开展有条件说明的对比。

1.2 本期范围与边界

范围	本期内容	边界
模型目录	LLM／AIGC 分类入口、卡片与表格视图、查询、模型详情和元数据维护	目录信息与具体配置验证结果分开；来源未知不补造
适配管理	一个模型下的多种部署配置、七阶段进展、状态变化记录	管理记录，不直接调度 GPU、执行适配脚本或替代研发流水线
性能数据	关联适配任务，记录测试配置与指标，选择记录进行对比	测试结果先支持人工录入；自动采集及可复现实验规范另行接入
查询与协作	总览、筛选、详情下钻、可分享的筛选链接、简单读写权限	企业身份、分团队权限和审批流程见附录 B
暂不纳入	模型训练、在线推理服务、资源调度、权重及镜像仓库、成本结算	产物链接和 CI/MR 集成留作后续，不混入本期验收

交付项目看板维护“客户项目需要哪些模型”；modelzoo 维护“模型在什么条件下获得怎样的支持”。两者通过稳定模型标识关联，客户需求、项目优先级和项目备注不写入 modelzoo。

PRD

第二部分 · 业务对象与核心规则

2.1 业务对象、来源与维护边界

对象	来源与维护	关系及页面作用
模型 models	官方模型资料＋内部模型清单；内部支持信息由维护人员确认	一个模型对应多项适配；形成目录及详情页主对象
适配任务 adaptations	本系统维护模型、部署配置、负责人及适配阶段	每项任务属于一个模型，可关联多条性能记录
性能记录 benchmarks	人工录入测试条件、指标、精度结论；未来由测试系统回填	每条记录属于一项适配任务，不跨模型复用测量结果
状态历史 history	状态变化时由业务服务追加	追溯任务变化；不等同于完整字段审计日志
支持矩阵／统计	按模型、任务、性能记录计算	阅读结果，不作为另一份独立维护的业务数据

模型 models（1）
└── 适配任务 adaptations（N）
    ├── 配置：硬件 × 框架 × 精度 × 软件版本 × PD 部署参数
    ├── 状态历史 history（N）
    └── 性能记录 benchmarks（N）
        ├── 测试条件：batch / seqLen / gpus / 测试日期
        └── 指标：TTFT / TPOT / 吞吐与单位 / 显存 / 精度结论

同一个模型可以同时存在不同精度、不同版本的多项任务。稳定 ID 决定关联，名称修改不改变关系；配置维度用于说明适用范围，不直接替代任务 ID。是否限制重复配置，见附录 B。

2.2 适配阶段与版本语义

待适配 → 适配中 → 功能验证 → 精度对齐 → 性能调优 → 已发布 → 退役

状态值	业务含义	状态说明
queued	待适配	新建任务的默认阶段，尚未开始或等待处理
adapting	适配中	正在完成框架、算子及运行链路适配
functional	功能验证	验证模型能否在指定配置下正常运行
accuracy	精度对齐	对照参考结果验证精度
perf	性能调优	在已明确测试条件下优化性能
released	已发布	该任务配置已形成可供使用的发布结论
deprecated	退役	该项配置退出推荐使用，既有结果保留用于追溯

默认按相邻阶段推进，确认前展示当前阶段、下一阶段及流转说明。状态改变后保留变化记录；同状态保存不新增流转记录。跳阶段、回退以及发布证据门槛需单独明确，不将“已发布”理解为该模型在所有环境均已支持。

字段	含义	使用规则
models.supportVersions	模型级版本支持摘要，例如“v1.1.1 已支持”	目录展示；来源和完整原文保留，不自动充当某项部署配置的验证结论
adaptations.swVersion	单项配置的软件栈及框架版本配套	跟随具体任务，例如软件栈与 SGLang 版本要求，不与模型摘要互相覆盖
models.retiredAt / adaptations.status	模型资料中的退役日期／任务配置的退役状态	作用对象不同，不因某一任务退役自动将整个模型退役

优先级 P0／P1／P2 用于安排模型关注顺序，默认 P2；不参与适配状态计算。全局支持摘要与七阶段任务之间的映射、以及对项目看板的输出口径，集中在集成设计中明确。

2.3 统计、支持矩阵与性能对比口径

结果	计算规则	阅读边界
模型数／家族数	按模型 ID 计数；家族去重且排除空值	不按任务数量放大模型数量
已发布／进行中	统计适配任务；已发布为 released，进行中为 queued 至 perf	一个模型可以同时有已发布任务和进行中任务
未适配模型	不存在任何适配任务	仅有退役任务不算“从未适配”
支持矩阵	单模型内按硬件 × 框架聚合；优先级 released > perf > accuracy > functional > adapting > queued > deprecated	单元格展示推进最远状态和任务条数；不表示其他精度或版本都达到该状态
矩阵空格	该硬件、框架组合没有任务	显示“—”；与有任务但待适配区分
最近更新	按适配任务更新时间倒序，展示最近 8 条	不表述为全部业务操作历史
性能对比	从选中记录读取吞吐、TTFT 等原始指标	条件与单位必须可见；不同吞吐单位不放入同一数值排行榜

TTFT：首个 Token 的响应时延，单位 ms；TPOT：生成后续 Token 的平均时延，单位 ms。
吞吐：值和单位共同构成指标，tok/s、img/s、样本/s 不直接比较大小。
显存：明确测量范围后比较；单卡峰值、均值或总显存的口径尚待测试规范统一。
不同 batch、序列长度、卡数、硬件、精度或软件版本的结果可以并列查看，但必须展示差异，不据此自动宣称性能优劣。
缺测值显示“未测／—”，真实的 0 才显示为 0；图表不把缺测解释为零性能。相关工程差异见附录 B。

2.4 操作权限

能力	查看人员	维护人员
目录、详情、统计、性能对比	可查看可见数据	可查看
模型、任务、性能记录维护	不可修改	可维护业务范围内的数据
状态推进	不可修改	可确认推进并填写说明
删除	不可操作	确认关联影响后执行；正式删除策略见附录 B
离线演示	只读	同样只读，不生成已保存事实

先区分查看与维护两类能力；负责人字段仅描述任务归属，不等同于登录身份或权限。真实账号、团队范围和维护授权需在正式身份接入时确认。恢复种子数据属于演示管理操作，不进入正式用户工作流程。

PRD

第三部分 · 功能与交互设计

3.1 页面总览与核心路径

核心路径：查模型 → 看配置 → 跟进适配 → 记录性能 → 对比与引用。点击查看原图

modelzoo
├── 总览：模型规模、任务状态分布、最近更新
├── 模型目录
│   ├── LLM / AIGC 模块与子类
│   ├── 卡片 / 表格、关键词、家族多选、适配情况筛选
│   └── 模型详情：概览 → 支持矩阵 → 部署配置 → 性能记录
├── 适配任务：模型 / 状态筛选、配置维护、阶段推进、流转历史
└── 性能数据：条件与指标录入、记录选择、吞吐 / TTFT 对比

查询路径：从目录定位模型，在详情确认支持范围，必要时下钻到具体任务及测试记录。维护路径：先有模型，再建适配任务，随后录入该配置下的性能记录。只看信息的用户不必先创建或编辑任何数据。

3.2 总览与模型目录

功能区	信息与操作	交互要求
总览	模型数、家族数、任务数、已发布、进行中、性能记录；七态分布及最近更新	统计对象明确，数字可追溯到对应清单；无数据与读取失败分开
模块入口	LLM 对应文本模型；AIGC 包含多模态、文生视频、文生图、小模型	目录默认 LLM；模块卡显示模型数量及框架摘要；AIGC 可切子类
卡片视图	按家族组织，展示名称、参数、开源状态、优先级、负责人和任务计数	用于浏览；点击模型进入详情，维护人员可由模型快捷新建适配
表格视图	分类、名称、家族、参数量、支持版本、框架、OS、卡数、精度、任务进展与操作	用于横向比对和维护；长名称、长版本可查看完整信息
搜索与筛选	关键词匹配名称、家族、任务描述及模型描述；家族连续多选，适配情况单选	同类家族取并集，跨类条件取交集；条件变化回到第一页；清空条件后结果恢复
来源标记	内部模型清单、官方资料、内部测试结果	逐字段说明来源类别；不把类别标记当成单条来源已核实的证据
筛选链接	将模块、子类、视图、关键词、家族、适配情况带入 URL	重新打开同一链接可还原指定条件；未携带条件的恢复规则需保持一致

卡片与表格是同一目录的两种阅读形式。切换时应明确哪些筛选仍生效，不能出现工具栏隐藏但结果仍被不可见条件过滤的情况；交互差异列于附录 B。

模型目录表格：展示模块入口、筛选、11 列资料及字段来源。工程只读演示界面。点击查看原图

3.3 模型详情与支持下钻

区域	主要信息	操作和结果
① 模型概览	模型身份、参数、家族、优先级、简介、仓库／文档／官网链接及关联计数	编辑模型资料；从本模型发起适配时预填模型身份
② 支持矩阵	GPU 硬件为行、框架为列；显示最佳进展与对应任务数	点击单元格定位本模型＋本硬件＋本框架的全部相关任务，保留计数可追溯性
③ 部署配置矩阵	硬件、框架、精度、软件配套、Prefill、Decode、总节点数、状态、负责人、更新	配置在任务级维护；相似配置仍通过任务 ID 区分
④ 性能数据	同模型各任务的测试条件、指标、日期及备注	由任务进入录入；能定位到测试所对应的完整部署配置

模型详情不能仅凭“已发布”徽章作出通用支持承诺。支持矩阵是摘要；具体适用范围以任务的精度、版本和部署配置为准。暂无任务、无性能记录分别给出空态，不将两者混成“不支持”。

模型详情四区：模型概览、支持矩阵、部署配置、性能数据。截图中的测试值为演示数据。点击查看原图

3.4 适配任务维护与阶段推进

入口：从模型详情新建，或从任务列表选择模型新建；模型、GPU 型号、框架为必填。
配置：维护精度、软件版本配套、Prefill／Decode、节点信息、负责人、分支／MR 和备注。PD 文本、节点数和测试卡数分别保留，不按未经确认的固定“每节点 8 卡”规则自动推算。
列表：按模型及任务状态定位，显示更新时间、负责人和配置概要；筛选改变后回第一页。
编辑：先读取当前任务；若读取失败，应提示重试，不把缓存中的旧信息当作已刷新结果。
推进：展示当前阶段与下一阶段，填写说明后确认。保存中防重复提交，成功后同步状态、统计和历史；失败保留输入。
退役：任务退役保留既有测试证据，不自动删除关联性能记录，不自动改变其他任务状态。

适配任务列表：模型、GPU、框架、精度、PD 配比与七态进展。工程只读演示界面。点击查看原图

3.5 性能记录与对比

步骤	要求	结果
选择任务	从任务进入时锁定关联；独立录入时选择准确任务	记录归属明确，模型和配置可反查
填写测试条件	测试日期、batch、序列长度、卡数；补充测试输入和方法说明	保留足以理解指标的实验条件；未知信息不伪造
记录指标	TTFT、TPOT、吞吐及单位、显存、精度结论、备注	缺测与零值分开，非法数值和超长文本给出字段原因
修改记录	按字段更新；只改一个指标不清空其余配置与指标	保存后详情和清单一致
选择对比	可选择多条记录；显示已选数量，并支持移除和清空	图表与已选集合一致，翻页后选择状态可辨识
阅读结论	吞吐和 TTFT 分开展示；附带配置差异和单位	不混合不同单位，不把高吞吐单独等同于整体更优

性能记录与对比：示例选择两条记录；仅展示交互与字段，不作为真实性能结论。点击查看原图

3.6 保存、删除、异常与恢复

场景	页面反馈	处理规则
普通保存	保存中／已保存／字段错误／失败留稿	校验通过后提交；收到可信成功结果再更新事实；保存后刷新失败应与保存失败区分
状态流转	当前值、目标值、说明和确认按钮	状态和历史作为同一业务操作保存；仅变化时追加历史
多人修改	提示对象已变化、最新值及本次输入	避免静默覆盖；并发控制方案见附录 B，失败不丢草稿
关闭编辑	有未保存输入时提示保留编辑或放弃	保存中阻止重复提交及误关闭；放弃只丢未提交内容
写入超时	结果待核对	先查询对象或历史确认结果，不立即重发创建、推进或删除
业务读取失败	来源异常及重试入口	保留已知数据并标明未刷新；不能静默改用演示快照冒充当前业务
明确离线演示	明显的只读演示标识	写入口隐藏；用户知道当前结果是样例快照
无数据／无匹配	分别说明未有记录或筛选无结果	提供新建入口或清除筛选；权限不足时不显示不可执行入口
删除模型／任务	列明受影响任务和性能记录，二次确认	关联删除必须整体一致；正式数据的保留与恢复策略待定
登录过期	提示重新登录	保留尚可恢复的输入；客户端显示不能代替服务端鉴权

请求等待采用有限超时；工程现有请求超时参数为 6 秒，正式阈值结合部署网络校准。界面中“无记录”“读取失败”“写入结果未明”是不同状态。完整字段审计、撤销和自动恢复草稿不视为现成能力。

TRD

第四部分 · 技术设计

4.1 总体架构与数据流

浏览器 · public/index.html
├── data.js：数据快照、状态契约、三表查询、支持矩阵派生
├── api.js：HTTP 请求、令牌、超时、结果与错误处理
├── ui.js：表单、弹窗、路由、徽章、SVG 图表
├── views.js：总览／目录／详情／任务／性能视图
├── app.js：事件、表单提交、筛选深链、启动编排
└── fallback.js：由种子数据生成的离线演示快照
        ⇅ HTTP API / JSON（正式环境 HTTPS）
后端 · server.js（Node.js 内置 http）
├── lib/validate.js：必填、枚举、引用、长度、数值校验
├── lib/clean.js：字段归一、默认值、服务端时间
├── lib/auth.js：管理令牌与会话鉴权
├── lib/statuses.js ← data/statuses.json：七态契约
├── lib/log.js：访问日志、文件轮转
└── 持久化：内存数据 → 临时 JSON 文件 → rename 替换
        ⇅
数据层
├── models：模型资料与内部支持摘要
├── adaptations：任务配置、当前状态、历史
└── benchmarks：任务下的测试条件与结果

当前 Demo 是原生前端＋Node.js 服务＋JSON 持久化，运行时无第三方框架及构建步骤。现有职责划分适合快速验证；正式存储可以采用关系数据库，但不是完成这一版 PRD 的前提。技术复用以模块职责和已验证行为为参考，不要求后续研发原样沿用实现。

4.2 前后端职责与状态管理

职责	前端	后端
数据读取	请求、加载与错误反馈，显示当前来源	过滤、分页、查询、必要的汇总
业务规则	枚举与输入提示，派生结果展示	引用和字段校验、权限、状态变化、持久化一致性
阅读状态	模块、视图、筛选、分页偏移、性能选择集合；需要分享的条件写入 URL	不将临时阅读状态写入业务数据
编辑状态	草稿、保存中、失败／待核对；成功后刷新受影响视图	返回稳定 ID 与完整结果，错误可区分，不由客户端决定成功
历史	按对象读取与呈现	服务端产生时间、可信操作者及变化记录；状态定义保持一致

前端状态	用途	约束
db	models／adaptations／benchmarks 快照	渲染读取，写操作走 API
STATUS／ST	状态顺序、标签和颜色	优先读取服务端 meta.statuses；内嵌回退同源
filters	目录关键词、家族集合、模块／子类／视图、任务筛选	同一条件在 UI、URL 和查询中保持一致
pageState	各列表 offset／limit／total	切条件重置，删除导致页越界时回到有效页
selBms	参与对比的记录 ID 集合	跨页选择仍可见、可取消；对象消失时清理
dataSource／令牌	后端／离线与会话信息	客户端状态不授予写权限；正式凭据不进入 URL

4.3 数据模型、字段字典与关键约束

以下沿用工程字段名，便于研发直接对应。类型为逻辑类型，不代表已经建成关系数据库。空字符串表示可选文本未提供；未知数值与真实 0 的区分按目标规则设计，现有清洗差异列在附录 B。新增业务记录 ID 由服务端生成，所有关联使用 ID。

4.3.1 模型 models

字段	类型／上限	必填／缺省	业务定义与规则
id	ID 字符串	必有／服务端生成	模型主键；修改名称不改变 ID
name	字符串 100	必填／无默认	模型名称，去首尾空格后不能为空
family	字符串 100	可空／空串	模型家族，用于分组与多选筛选
type	字符串 50	新建时选择	文本模型、多模态、文生视频、文生图、小模型；未知来源值需核对
task	字符串 100	可空／空串	任务描述，参与关键词查询
params	字符串 100	可空／空串	参数规模原文，如 235B-A22B，不强转为数值
openSource	字符串 20	可空／未标注	开源／闭源；未知不自动推断
source	字符串 300	可空／空串	来源说明；不等同于独立字段的核实证据
license	字符串 100	可空／空串	许可证原文
owner	字符串 100	可空／空串	模型负责人描述，不自动授予权限
priority	枚举	可省／P2	P0、P1、P2
onboardedAt	日期文本 20	可空／空串	接入日期，YYYY-MM-DD
retiredAt	日期文本 20	可空／空串	模型退役日期，需与接入日期保持合理关系
repoUrl	URL 300	可空／空串	模型仓库链接，仅允许可信 http/https 协议
docsUrl	URL 300	可空／空串	使用或适配文档链接
homepageUrl	URL 300	可空／空串	官方主页
desc	文本 2000	可空／空串	模型说明，作为文本安全展示
supportVersions	字符串 300	可空／空串	内部确认的模型版本支持摘要，保留版本与结论原文
framework	字符串 200	可空／空串	模型级框架支持摘要，与任务级 framework 分开
os	字符串 200	可空／空串	内部验证操作系统摘要
cards	字符串 50	可空／空串	卡数支持描述，如单卡／2卡，不替代某次测试 gpus
precision	字符串 50	可空／空串	模型级精度摘要，不自动传播到所有任务

4.3.2 适配任务 adaptations

字段	类型／上限	必填／缺省	业务定义与规则
id	ID 字符串	必有／服务端生成	任务主键
modelId	ID 字符串	必填／无默认	关联 models.id，必须存在
hardware	字符串 100	必填／无默认	GPU 型号或明确硬件方案，后续标准化字典
framework	字符串 200	必填／无默认	运行框架／引擎，具体版本放 swVersion
precision	字符串 50	可省／未标注	任务精度；表单推荐初值 FP16 不等同于 API 强制缺省
swVersion	字符串 200	可空／空串	该任务的软件栈、框架版本配套
prefill	字符串 50	可空／空串	Prefill 部署配置原文，例如 1P2；不适用时明确标注
decode	字符串 50	可空／空串	Decode 部署配置原文，例如 1D4
totalNodes	字符串 50	可空／空串	节点数量或部署说明；暂不由 PD 文本自动计算
status	七态枚举	可省／queued	目标状态迁移由服务端统一约束
owner	字符串 100	可空／空串	任务负责人
branch	字符串 200	可空／空串	代码分支或 MR 引用文本
notes	文本 2000	可空／空串	任务说明，不代替状态历史
updatedAt	时间字符串	必有／服务端生成	任务更新时间；当前精度为分钟，正式时区与精度另确认
history	历史数组	必有／创建事件	任务状态记录，应用只读；不接收客户端伪造的历史
transitionNote	请求文本 500	可空／空串	流转说明；仅用于本次状态变更，写入 history.note，不作为独立任务字段

4.3.3 性能记录 benchmarks

字段	类型／上限	必填／缺省	业务定义与规则
id	ID 字符串	必有／服务端生成	性能记录主键
adaptationId	ID 字符串	必填／无默认	关联 adaptations.id，模型和硬件由任务反查
date	日期文本 20	必填／表单当天	测试日期 YYYY-MM-DD，允许人工修改为实际日期
config.batch	正整数	可缺测／未知	批量大小；计数不能为负数或小数
config.seqLen	正整数	可缺测／未知	序列长度；输入／输出长度与测试模式的细分见附录 B
config.gpus	正整数	可缺测／未知	本次测试实际使用卡数，不由总节点数自动推算
metrics.TTFT_ms	非负数	可缺测／未知	首 Token 时延，ms
metrics.TPOT_ms	非负数	可缺测／未知	后续 Token 时延，ms
metrics.throughput	非负数	可缺测／未知	吞吐值，有值时须有单位
metrics.unit	字符串 30	按指标选择	tok/s、img/s、样本/s；不能跨单位直接排名
metrics.gpuMem_GB	非负数	可缺测／未知	显存数值，GB；单卡／总量与峰值口径需补测量说明
metrics.accuracy	字符串 300	可空／空串	精度结论原文，保留参考对象和容差说明
notes	文本 2000	可空／空串	测试方法、输入条件和结果说明

数值上限沿用现有校验边界 1e9 作为技术保护，不表示每项业务指标的合理范围。具体指标须增加单位、缺测和业务合理性校验。更新 config 或 metrics 的局部字段时深合并，只改变显式提交字段。

4.3.4 历史、索引与一致性

内容	定义	实施约束
history.status / at / note	目标状态、服务端时间、变化说明	状态与历史同一操作保存；需补原状态、可信操作者与稳定事件 ID 时另定字段
关联完整性	models 1:N adaptations；adaptations 1:N benchmarks	创建及更新检查父对象存在；删除关联整体提交
主键与索引	各主实体主键；任务 modelId／status／updatedAt；性能 adaptationId／date	关系数据库落地时建立适配索引；不对未经确认的完整配置直接加唯一约束
来源保护	官方元数据、内部支持摘要、任务结果分别管理	后续同步不能覆盖人工维护的任务、历史或性能数据
事务边界	数据变更、关联变更与历史一致提交	内存成功不等于落盘成功，失败不能继续提供一份未持久化的新事实

4.4 接口与一致性处理

方法／路径	用途	请求与结果要点
GET /api/state	初始业务快照及 meta	模型、任务、性能数据；不随全量快照下发任务 history
GET /api/summary	总览汇总	计数、七态分布、最近 8 条任务更新
GET /api/models	目录查询	q、family 多值、type 多值、adapt；offset／limit
GET /api/adaptations	任务查询	model、status、offset／limit；硬件与框架下钻参数待补
GET /api/benchmarks	性能列表	offset／limit；更细测试条件过滤后续补
GET /api/{resource}/:id	单条详情	适配任务详情含 history；不存在返回 404
POST /api/{resource}	创建模型／任务／性能记录	服务端生成 ID；校验通过并落盘后 201＋完整对象
PUT /api/{resource}/:id	局部字段更新	沿用现有路径；保留未提交字段；不能信任客户端 history、时间和身份
DELETE /api/{resource}/:id	删除对象及关联	确认影响后执行；响应明确结果，恢复策略见附录 B
POST /api/login；GET /api/auth-status	维护登录与会话状态	当前管理令牌换取 8 小时会话；正式身份另接入
GET /api/health	服务健康检查	返回运行及数据库文件探测状态
POST /api/reset	演示环境重置	正式业务环境关闭或隔离，不作为业务数据恢复机制

分页沿用 offset／limit，默认 20、范围 1—100，响应含 items、total、offset、limit。非法字段及枚举返回 400，未授权 401，缺失引用或对象 404；正式并发冲突建议返回 409，服务及落盘故障与用户输入错误分开。更新响应须能验证对象身份和字段完整性。

并发保存建议携带记录修订号或编辑前原值，在事务内比较；服务端给出冲突详情，前端保留草稿。创建与状态推进需可核对或使用幂等标识，防止超时后的重复提交。该约束是目标设计，当前工程的缺口及优先级见附录 B。

4.5 数据接入、部署与恢复

主题	设计说明
启动与样例	seed.json 用于首次演示初始化；db.json 是运行业务数据；fallback.js 是同源生成的只读样例。不能通过重置种子代替业务备份
来源接入	官方资料、内部清单、测试结果分别维护字段归属；接入更新保留本系统任务和历史。单字段来源证据、核实时间和来源版本逐步补齐
与项目看板衔接	通过稳定 modelId 输出支持摘要与版本字段；七态压缩为项目看板三态的映射、多个配置的聚合及退役口径需确认后实施
本地形态	Node.js 单进程服务，默认 8090，静态资源限定 public；可使用 MODEL_ZOO_DB 指定独立数据库路径
正式形态	HTTPS、真实身份、按角色控制写入、可恢复备份；并发需求上升时迁移 SQLite/PostgreSQL 等事务存储
公网演示	Cloudflare Pages 承载只读快照；不据此宣称保存、适配流水线和测试回填已上线
性能策略	列表分页、汇总查询、历史按详情加载；全量 state 与文件重写的增长成本需测量，避免只做分页 UI 却仍传输所有数据
可观测与恢复	健康检查、访问日志和故障分类；备份、恢复演练与失败留稿一并验证。日志不记录令牌或敏感请求正文

ACCEPTANCE

第五部分 · 实施与验收（供参考）

5.1 实施顺序与测试准备

顺序	工作内容	完成依据
1. 明确口径	确认实体、配置维度、版本摘要、缺测语义及状态变更规则	第二部分与 4.3 的字典可用于样例验算
2. 打通查询	总览、目录、详情、精确下钻和筛选链接	同一对象在列表、详情和统计中一致
3. 打通维护	模型／任务／性能保存、状态历史、权限与异常恢复	明确失败不丢稿、结果未知可核对、并发不静默覆盖
4. 接入与运维	正式数据来源、项目看板映射、部署、备份和性能验证	待确认项形成明确规则后逐项验收

测试使用独立数据集与独立存储路径；样例涵盖无任务模型、仅退役任务、同硬件框架多精度／多版本任务、缺测指标、跨单位结果和关联删除。不对现有业务库运行重置或测试写入。本稿不预设工期和人员承诺。

5.2 功能验收

验收点	操作样例	预期结果
目录与筛选	切 LLM／AIGC，组合关键词、两个家族和适配情况	结果按既定并集／交集展示，切条件回第一页，链接可还原
模型／任务计数	同模型有 released 与 adapting 各 1 条	模型数只加 1，已发布和进行中任务各计 1
仅退役模型	模型只有 1 条 deprecated 任务	不落入“没有任何任务”的未适配集合
矩阵聚合	同硬件框架下有 released、accuracy 两任务	显示已发布和任务数 2；点击能看到该组合的全部两条
状态推进	queued 确认推进到 adapting	状态和 1 条历史同时生效，重复点击不重复执行
配置与版本	同模型创建不同精度、软件版本的任务	任务相互独立，不反向覆盖模型级版本摘要
指标局部更新	仅修改 throughput	TTFT、TPOT、显存及 config 保持原值
性能对比	选择不同单位及不同测试条件的结果	条件明确可见，跨单位分开，缺测不显示为真实 0
读写权限	查看人员调用写接口；维护会话过期	服务端拒绝；前端提示且保留可恢复输入
关联删除	删除含任务和性能数据的模型	先明确影响；按确认的策略整体删除或整体拒绝，不出现悬空记录

5.3 性能、数据与恢复验收

首轮基线使用当前种子中的 46 个模型、16 项适配、8 条性能记录；这些是演示样本数，不是容量上限。
建议在约定设备与网络下将常用页面首次可交互 ≤2 秒、筛选及详情反馈 ≤500ms 作为待实测目标；分别记录 P50/P95，不把当前代码测试数量当作性能证明。
增加到预期业务规模后测量 state 体积、列表查询、图表渲染、单次写入与内存占用，再确定是否拆分全量接口和迁移存储。
模拟读取失败、网络超时、会话失效、磁盘写入失败、并发修改和刷新失败，分别验证界面反馈与数据最终状态。
备份恢复后核对主键、关联数量、状态、历史及性能值；恢复种子不计作业务恢复通过。

REFERENCE

附录 A · Demo 工程与参考

A.1 工程定位与可参考的实现

工程位置	可参考内容	使用注意
public/data.js · supportMatrixOf	按硬件与框架聚合、最佳状态与计数分开	摘要必须下钻到准确配置，不把最高状态理解为全部支持
data/statuses.json＋lib/statuses.js	前后端共用状态枚举	枚举一致不等于迁移限制已经执行
public/views.js · FIELD_SOURCES	字段来源分类标记	需逐步补真实来源证据；不是运行时同步器
public/app.js · queryForView / applyQuery	筛选状态与 URL 同步	需覆盖返回／刷新／清空等边界
server.js · PUT benchmarks	嵌套 config／metrics 深合并	扩展字段时保持未提交值不丢失
server.js · persist	临时文件＋rename，减少半文件风险	不等于数据库事务或多人并发保护
tools/gen-fallback.js	种子到离线快照的同源生成	快照明确标记为演示，不混入生产事实
test/ 与 e2e/	数据完整性、接口、前端逻辑和浏览器验证框架	本次仅做文档与只读截图验证，没有重新运行工程全量测试

工程仓库：Behappybehealth/model-zoo

现有公网 Demo 地址（只读部署地址，来自工程配置；本稿不将其作为当前代码的发布证明）

工程参考：当前本地工作区，Git 基线 13d2a2c；已有样式及素材改动保留。本稿截图直接渲染现有前端和离线样例，未修改功能代码和业务数据。

TODO

附录 B · 待确认事项与工程差异

以下集中列出目标需求尚需拍板或实现补齐的部分。优先级是本稿建议，便于下一轮逐项讨论；不代表本次已经修改工程。

优先级／事项	已观察到的工程事实	下一步建议
优先｜矩阵下钻范围	supportMatrixOf 按硬件×框架聚合，但链接只携带模型与最佳状态，缺少硬件／框架	补精确组合过滤；计数对应的全部任务均应可追溯
优先｜状态迁移边界	“下一步”按顺序推进，但编辑下拉与后端仅校验枚举，允许任意阶段切换	确认是否允许跳转／回退，统一服务端约束；明确发布证据门槛
优先｜指标缺测与零值	cleanBenchmark 将空数值归为 0；图表过滤 ≤0；计数字段可接受小数	区分未测与 0，计数字段校验正整数；明确合理范围
优先｜跨单位／条件对比	吞吐图可同时画出不同单位记录，未按测试条件分组；选中集合保留但跨页勾选回显需核对	同单位分组，对比区展示条件差异；补已选摘要及清空操作
优先｜业务失败与演示	loadData 失败回退内嵌快照，来源信息仅写控制台；分页失败也可回退快照过滤	业务模式失败明确重试，演示模式明显只读标识，不能静默混淆来源
优先｜保存完整性	弹窗先关闭再刷新，写入成功但刷新失败可能仍报操作失败；无结果核对与并发原值校验	拆分写入结果与刷新结果；补留稿、冲突和超时核对
优先｜落盘及系统字段	修改内存后再 persist，写盘失败未恢复内存；创建清洗可接收传入 id／history／updatedAt 等	服务器生成并保护系统字段；落盘失败不能留下内存与文件不一致；补故障测试
优先｜外链与 API 地址	API_BASE 直接采用 ?api= 并附带令牌；外链转义但缺少协议白名单	限制后端可信地址，限制外链协议，避免将令牌发送到任意地址
待确认｜权限与审计	只有管理令牌会话；owner 为文本；历史缺操作者与原状态	确认真实维护角色与范围，再补可信身份和审计字段
待确认｜删除与恢复	当前模型／任务删除级联，reset 会恢复种子，未形成业务恢复机制	确认是否软删除／禁止有引用删除，定义备份与保留期
待确认｜配置和测试协议	PD 为文本，节点数为文本，表单写“每节点8卡”；seqLen、显存及精度基准口径不完整	定义 PD 符号、节点卡数、输入／输出长度、并发方式和测量范围，禁止猜测换算
待确认｜版本输出与去重	模型支持摘要和任务软件版本并存，没有任务配置唯一键或对项目看板的固定映射	明确模型标识、三态输出及多配置聚合规则；决定重复配置是否允许
待完善｜目录与来源	卡片、表格的筛选展示不同；类型／日期／URL 的后端校验不完整；来源多为类别提示	统一视图切换规则，补日期和分类校验，逐步完善来源证据
后续｜存储和自动化	单进程 JSON，state 仍含大量全量数据；CI 回填、产物管理未接入	按真实规模选择事务数据库；后续接测试系统与产物链接，不扩大首版范围