ljz
1aac220084
在单次 Jacobian 构建内按完整输入精确复用储气物性、PH 反算、密度和管路求根结果，保持原有求值副作用、差分政策与失败回退。八路模型求解 CPU 中位数减少 19.27%，循环和不循环的完整原始采样均与恢复基线一致。 增加独立的跨平台时间剖析工具，记录互斥阶段耗时、Newton/LU 统计、矩阵复用与内核复用，保存 UD00 两种工况的调查报告和机器可读汇总。 补充 Windows/Linux 运行、测试、原生编译和剖析所需依赖文档及索引，不修改依赖清单、版本锁或安装环境。 验证：8 项新增专项回归通过；2270 次完整 Jacobian 核对零差异；16 次剖析配对及预热运行保持完整数值一致。既有固定样本哈希失败和 Linux 实机验收限制见报告。
67 lines
8.2 KiB
Markdown
67 lines
8.2 KiB
Markdown
# 现行规范索引
|
||
|
||
索引版本：1.1.3；索引更新日期：2026-09-16。
|
||
|
||
新增组件从[注册流程](component-registration-workflow-v1.md)开始，再按涉及的能力读取专项规范。[注册示例](component-registration-example-v1.md)包含实际失败阶段、修订对照和复现方法。本目录保存现行版本，修订时更新正文版本、日期及变更说明；历史实现报告仍在 `docs/other/`，不覆盖其历史结论。
|
||
|
||
| 文件 | 文档版本 / 本次修订日期 | 用途 |
|
||
| --- | --- | --- |
|
||
| [component-registration-workflow-v1.md](component-registration-workflow-v1.md) | 1.1.0 / 2026-09-12 | 总流程、条件修改范围、交付资料与完成状态 |
|
||
| [component-registration-example-v1.md](component-registration-example-v1.md) | 1.0.0 / 2026-09-12 | 斜坡信号源完整注册演练、规范差异、复现与验证记录 |
|
||
| [component-library-spec-v1.md](component-library-spec-v1.md) | 1.2.0 / 2026-09-12 | 库清单、身份版本、注册与目录/工程读取 |
|
||
| [component-model-authoring-spec-v1.md](component-model-authoring-spec-v1.md) | 1.2.0 / 2026-09-12 | 参数、端口、状态、结果、C 模块和代码生成要求 |
|
||
| [port-computation-contract.md](port-computation-contract.md) | 1.1.1 / 2026-09-12 | 端口逐变量供需、固定参考关系与连接合法性 |
|
||
| [native-evaluation-schedule.md](native-evaluation-schedule.md) | 1.1.1 / 2026-09-12 | 计算依赖、局部求解，以及新模型的依赖检查 |
|
||
| [跨平台交付约定.md](跨平台交付约定.md) | 1.1.1 / 2026-09-12 | Windows/Linux 构建、缓存、文件系统和实际验收 |
|
||
| [backend-interface-version-spec-v1.md](backend-interface-version-spec-v1.md) | 1.2.0 / 2026-09-12 | 接口、模型与工程格式各自的版本边界 |
|
||
|
||
文档文件名中的 `v1` 是文档主版本，正文另标修订版本。当前协议为目录 schema `1`、工程 JSON `2`（兼容读 `1`）、System XML `3`；本次工程格式升级没有改变各组件 `MODEL_VERSION`。
|
||
|
||
其他配套规范本轮也完成核对并补上文档版本：
|
||
|
||
| 文件 | 文档版本 / 核对日期 | 本轮调整 |
|
||
| --- | --- | --- |
|
||
| [System XML v3](system-xml-v3.md) | 1.1.1 / 2026-09-13 | 纠正求解方法的 XSD 描述；说明示例可执行边界、参数输入及连接检查层次 |
|
||
| [优化基准模型](optimization-benchmark-model.md) | 1.1.0 / 2026-09-12 | 计时口径、当前/历史输入隔离、按需 XML 与可执行测试入口 |
|
||
| [平台依赖说明](platform-dependencies.md) | 1.0.0 / 2026-09-16 | Windows/Linux 的运行、测试、原生编译和时间剖析依赖 |
|
||
| [Jacobian 确定性复用](native-jacobian-reuse.md) | 2026-09-15 | 单次矩阵构建中的输入键、复用边界与回退 |
|
||
| [求解器时间剖析](native-solver-profiling.md) | 2026-09-16 | 互斥耗时、求解计数、独立诊断副本及复现入口 |
|
||
|
||
以上版本仅表示文档，XML Schema 和用户指定的八路基准未改变。
|
||
|
||
## 文件迁移与后续删改
|
||
|
||
| 原位置 | 现位置 | 处理 |
|
||
| --- | --- | --- |
|
||
| `docs/standard/新组件注册流程与规范草案.md` | `docs/standard/component-registration-workflow-v1.md` | 校正后转为现行流程，移除草案副本 |
|
||
| `app/simulation/components/example.md` | `docs/standard/component-registration-example-v1.md` | 迁入本目录并替换为可复现的新组件示例，删除旧入口 |
|
||
| 既有组件、端口、求值与跨平台规范 | 原有 `docs/standard/` 路径 | 原位更新，保持稳定链接 |
|
||
|
||
后续调整流程先改总流程；字段或行为规则改对应专项规范；演练方法和证据改示例。移动或删除文件时同步本索引、仓库 README 与其他规范中的链接。可执行演练工具保留在 `tests/manual/`；本地生成项目、源码副本和缓存位于被 Git 忽略的 `test/component-registration-20260912*`，停掉其临时服务后可删除，并可按示例重新生成。
|
||
|
||
## 2026-09-12 全目录代码一致性复核
|
||
|
||
本轮核对本目录全部 11 份文档（含本索引）。修改现行规范以描述当前代码；Windows 实际验收、八路优先、固定精度和独立参考等用户约束继续保留，不能因代码尚未自动完成就删去要求。注册示例的历史实测记录保持原版本，没有把本轮静态核对写成重新执行整套网页演练。
|
||
|
||
| 核对项 | 确认的代码行为及本轮修订 | 主要代码依据 |
|
||
| --- | --- | --- |
|
||
| XML 积分方法 | XSD 仅要求 `method` 为非空字符串，不枚举方法；语义层和执行层只支持 RK45/BDF，其他值在语义层返回 SIMULATION_METHOD_UNSUPPORTED（2026-09-13 纠正原表述） | [XML 校验](../../app/system_xml.py)、[XSD](../../schemas/system-simulation-v3.xsd)、[原生 runner](../../app/simulation/native_codegen/runner.py) |
|
||
| XML 示例和编译 API | 文档示例是结构有效但机械无惯性锚点的系统；compile-model 只构造网络，C 生成仍可能失败 | [HTTP/网络入口](../../app/main.py)、[扩展生成](../../app/simulation/native_codegen/extended.py) |
|
||
| 存储与执行 | 版本不同在输入层警告后使用当前模型；类型/端口/参数仍严查，XML 精确版本不变 | [请求与存储](../../app/main.py)、[前端解析](../../frontend/src/App.tsx) |
|
||
| 参数表达式与单位 | 已统一：外部 v2 数值与表达式按所选单位，v1 保持旧 SI 数字；预处理后才进入数值内核 | [网页表达式](../../frontend/src/parameterExpression.ts)、[CLI 输入](../../app/simulation/native_codegen/input.py)、[HTTP 转换](../../app/main.py) |
|
||
| 组件元数据 | DISPLAY 的介质 role 参与识别；数值基类需配套；输出过滤 visible/活动端口，editor 为受控枚举 | [注册器](../../app/simulation/registry.py)、[组件基类](../../app/simulation/core/base.py)、[元数据](../../app/simulation/core/metadata.py) |
|
||
| 连接入口 | XML/网络允许信号扇出，网页检查限制显示端口一条边；存储不做供需校验 | [网络](../../app/simulation/systems/network.py)、[XML](../../app/system_xml.py)、[前端](../../frontend/src/App.tsx) |
|
||
| 雅可比与误差尺度 | 有收益时着色差分，矩阵/LU 仍稠密；扩展路径使用统一的物性差分求值；核对选项传给 EXE | [雅可比结构](../../app/simulation/native_codegen/jacobian.py)、[CVODE](../../native/runtime/cvode_solver.c)、[容差](../../app/simulation/native_codegen/tolerances.py) |
|
||
| 缓存和平台 | 缓存命中仍预处理；按模块复用，有清理预算及超限例外；Windows 使用 GCC/MinGW 接口 | [构建](../../app/simulation/native_codegen/build.py)、[缓存](../../app/simulation/native_codegen/cache_storage.py)、[CI](../../.github/workflows/solver-regression.yml) |
|
||
| 结果与耗时 | C JSON 字节直传、IndexedDB 保存、Worker CSV 是不同阶段；任务内存保留与终态清理有明确边界 | [结果传输](../../app/simulation/native_codegen/transport.py)、[结果持久化](../../frontend/src/resultPersistence.ts)、[CSV](../../frontend/src/resultCsvExport.ts)、[C 计时](../../native/runtime/common.c) |
|
||
|
||
验证：64 项注册、目录、元数据、工程格式、XML、端口供需、雅可比结构和原生结果传输测试通过。另外直接核对六种积分方法、示例原生拒绝原因、存储/执行版本差异、数字/表达式单位和网页函数表达式行为。原始结果在被 Git 忽略的 `test/standard-code-audit-20260912/`：`regression.log`、`probe.json`、`frontend-expression.json`。该次审计未改业务实现。后续已按用户决定实现两项输入合同改动，另见下方新验收记录。
|
||
|
||
## 输入合同实现 / 2026-09-12
|
||
|
||
旧组件版本警告、工程 JSON v2 参数单位与表达式统一的现行规则见[接口规范 1.2.0](backend-interface-version-spec-v1.md#61-工程存储与执行入口)。测试与独立版本检查计时见[验收报告](../other/2026-09-12-project-contract-acceptance.md)。端口快照精简及其他求解优化未纳入此改动。
|
||
|
||
## 求解方法说明纠正 / 2026-09-13
|
||
|
||
System XML 规范更新至 1.1.1，同步纠正本索引中“XSD 列六种”的错误描述：当前 XSD 只要求 `method` 为非空字符串，可执行方法由语义校验及原生执行入口限制为 RK45/BDF。本次仅修正文档并静态核对代码，未修改协议或业务实现，未重新运行上述历史验收测试。
|