| | |
|---|
| | | # 实验存储体系创建指南 |
|---|
| | | # 实验存储体系 |
|---|
| | | |
|---|
| | | 创建人员：Codex |
|---|
| | | 文件职责：指导 AI 在具体项目中创建实验体系的数据存储文档、数据目录、表 schema、读取方式和结果包组织方式。 |
|---|
| | | 管理规范/模板：common/exp-doc/实验规范.md；本文件是创建指南，不是单次实验模板。 |
|---|
| | | 引用文件：../../管理系统说明.md；实验规范.md；实验环境创建指南.md。 |
|---|
| | | 创建人员：management.admin |
|---|
| | | 文件职责：记录 `project-info` 项目实验数据、结果包、图片、日志、schema 和读取追踪方式。 |
|---|
| | | 管理规范/模板：../../common/exp-doc/实验存储体系创建指南.md；../../common/exp-doc/实验环境创建指南.md。 |
|---|
| | | 引用文件：实验规范.md；实验总纲.md；实验设计.md；实验执行日志.md；实验审计报告.md。 |
|---|
| | | 记录方式：存储体系入口；目录、结果包命名、schema 或读取规则变化时维护更新。 |
|---|
| | | |
|---|
| | | ## 1. 定位 |
|---|
| | | ## 1. 目录映射 |
|---|
| | | |
|---|
| | | 本指南用于回答： |
|---|
| | | | 路径 | 作用 | 状态 | |
|---|
| | | |---|---|---| |
|---|
| | | | `../exp-data/raw/` | 原始输入索引、抽样数据或外部文件引用 | 已创建 | |
|---|
| | | | `../exp-data/result/` | 正式结果包、manifest、summary、readout 和可复核中间产物 | 已创建 | |
|---|
| | | | `../exp-data/img/` | 图片、图表和图片 manifest | 已创建 | |
|---|
| | | | `../exp-data/tmp/` | 临时文件，不得作为正式证据入口 | 已创建 | |
|---|
| | | |
|---|
| | | ```text |
|---|
| | | 当一个项目启用实验体系时，实验数据应该放哪里、怎么存、怎么读、怎么追踪、表 schema 怎么写。 |
|---|
| | | ``` |
|---|
| | | ## 2. 结果包命名 |
|---|
| | | |
|---|
| | | 项目内应创建一个 `exp-doc/实验存储体系.md`。 |
|---|
| | | |
|---|
| | | `实验存储体系.md` 不是单次实验归档表，而是该项目实验数据的长期存储合同。 |
|---|
| | | |
|---|
| | | 创建项目级存储体系时，不得复制其他项目的专有路径、业务名词、历史实验名或旧数据口径。示例表名、字段名和对象名必须改成当前项目可解释的中性名称。 |
|---|
| | | |
|---|
| | | ## 2. 项目目录要求 |
|---|
| | | |
|---|
| | | 项目启用实验体系时，至少应创建： |
|---|
| | | |
|---|
| | | ```text |
|---|
| | | <project>/ |
|---|
| | | exp-doc/ |
|---|
| | | 目录导读.md |
|---|
| | | 实验规范.md |
|---|
| | | 实验审计规范.md |
|---|
| | | 实验存储体系.md |
|---|
| | | 实验审计报告.md |
|---|
| | | 实验问题记录.md |
|---|
| | | 实验总纲.md |
|---|
| | | 实验设计.md |
|---|
| | | 实验执行日志.md |
|---|
| | | exp-data/ |
|---|
| | | result/ |
|---|
| | | img/ |
|---|
| | | raw/ |
|---|
| | | tmp/ |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | 目录职责： |
|---|
| | | |
|---|
| | | | 目录 | 作用 | |
|---|
| | | |---|---| |
|---|
| | | | `exp-doc/` | 存实验文档、实验总纲、实验设计、审计报告、项目实验存储体系 | |
|---|
| | | | `exp-data/result/` | 存每次实验结果包，建议按 `run_id` 分目录 | |
|---|
| | | | `exp-data/img/` | 存图片、图表、业务图、人工验收图等可视化资产 | |
|---|
| | | | `exp-data/raw/` | 存原始输入快照、外部下载文件、原始响应、人工原始回执 | |
|---|
| | | | `exp-data/tmp/` | 存临时中间文件；不可作为正式结论入口 | |
|---|
| | | |
|---|
| | | 如果项目已有数据库，结构化数据优先进入数据库；文件系统保留原始证据、快照、图表和可读结果包。 |
|---|
| | | |
|---|
| | | ## 3. 实验存储体系文档必须包含什么 |
|---|
| | | |
|---|
| | | 项目内的 `exp-doc/实验存储体系.md` 至少应包含： |
|---|
| | | |
|---|
| | | 1. 数据存储目标和范围。 |
|---|
| | | 2. 目录结构说明。 |
|---|
| | | 3. 数据流说明。 |
|---|
| | | 4. 结果包组织规则。 |
|---|
| | | 5. 图片和图表存储规则。 |
|---|
| | | 6. 表清单。 |
|---|
| | | 7. 每张表的 schema，精确到字段。 |
|---|
| | | 8. 主键、唯一键、去重和版本规则。 |
|---|
| | | 9. 数据读取方式。 |
|---|
| | | 10. 临时数据和正式数据边界。 |
|---|
| | | 11. 审计和复核入口。 |
|---|
| | | |
|---|
| | | ## 4. 数据流规则 |
|---|
| | | |
|---|
| | | 推荐数据流： |
|---|
| | | |
|---|
| | | ```text |
|---|
| | | raw source |
|---|
| | | -> cleaned/input snapshot |
|---|
| | | -> experiment intermediate |
|---|
| | | -> result package |
|---|
| | | -> structured table / database |
|---|
| | | -> audit/readout |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | 每一层都要能追溯： |
|---|
| | | |
|---|
| | | 1. 来自哪个实验。 |
|---|
| | | 2. 来自哪个 run。 |
|---|
| | | 3. 来自哪个 source snapshot。 |
|---|
| | | 4. 由哪个脚本、AI 或人工步骤产生。 |
|---|
| | | 5. 后续应该怎么读。 |
|---|
| | | |
|---|
| | | ## 5. 结果包规则 |
|---|
| | | |
|---|
| | | 结果包建议路径： |
|---|
| | | 正式结果包使用： |
|---|
| | | |
|---|
| | | ```text |
|---|
| | | exp-data/result/<run_id>/ |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | 每个结果包至少应包含： |
|---|
| | | |
|---|
| | | | 文件 | 作用 | |
|---|
| | | |---|---| |
|---|
| | | | `summary.json` 或 `summary.md` | 记录关键结论、关键计数、状态 | |
|---|
| | | | `output_manifest.csv/json` | 记录结果包内所有资产路径、类型、行数、hash | |
|---|
| | | | `readout.md` | 可选，人读版结论和边界 | |
|---|
| | | | `input_manifest.csv/json` | 可选，记录输入快照 | |
|---|
| | | | `schema_or_contract_reference` | 可写在 manifest 字段里，指向 schema 文档 | |
|---|
| | | |
|---|
| | | 结果包入口应回写到实验总纲和实验设计。 |
|---|
| | | |
|---|
| | | 结果包内部资产清单应能被 `实验存储体系.md` 中的表清单或 manifest 解释。 |
|---|
| | | |
|---|
| | | ## 6. 图片和图表存储规则 |
|---|
| | | |
|---|
| | | 图片建议路径： |
|---|
| | | 推荐文件： |
|---|
| | | |
|---|
| | | ```text |
|---|
| | | exp-data/img/<experiment_id>/<run_id>/ |
|---|
| | | manifest.json |
|---|
| | | summary.md |
|---|
| | | summary.json |
|---|
| | | readout.md |
|---|
| | | intermediate/ # 需要长期复核的中间数据 |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | 图片文件名应尽量包含： |
|---|
| | | 图片放入 `exp-data/img/<experiment_id>/<run_id>/`，并用 manifest 记录来源、生成方式和用途。 |
|---|
| | | |
|---|
| | | 1. 样本 ID。 |
|---|
| | | 2. 标的或对象 ID。 |
|---|
| | | 3. 日期或窗口。 |
|---|
| | | 4. 图类型。 |
|---|
| | | ## 3. 追踪规则 |
|---|
| | | |
|---|
| | | 例如： |
|---|
| | | 1. `实验总纲.md` 记录实验 ID、状态、设计入口、结果包入口和审计入口。 |
|---|
| | | 2. `实验设计.md` 记录数据源、样本、步骤、产物和判定标准。 |
|---|
| | | 3. `实验执行日志.md` 记录 run ID、输入、命令摘要、输出路径、自检和偏离。 |
|---|
| | | 4. `实验审计报告.md` 记录设计审核、执行审核和复审结论。 |
|---|
| | | |
|---|
| | | ```text |
|---|
| | | CASE001_OBJECT001_2024-01-05_event_review.png |
|---|
| | | ``` |
|---|
| | | ## 4. 禁止事项 |
|---|
| | | |
|---|
| | | 图片必须能从表或 manifest 反查： |
|---|
| | | |
|---|
| | | 1. 这张图对应哪个样本。 |
|---|
| | | 2. 这张图用于证明什么。 |
|---|
| | | 3. 这张图由哪个 run 生成。 |
|---|
| | | 4. 这张图是否进入人工验收。 |
|---|
| | | |
|---|
| | | ## 7. 表清单要求 |
|---|
| | | |
|---|
| | | `实验存储体系.md` 必须有表清单。 |
|---|
| | | |
|---|
| | | 表清单建议字段： |
|---|
| | | |
|---|
| | | | 字段 | 说明 | |
|---|
| | | |---|---| |
|---|
| | | | table_name | 表名或文件名 | |
|---|
| | | | storage_backend | `mysql/csv/json/sqlite/parquet/image/other` | |
|---|
| | | | storage_path_or_table | 文件路径或数据库表名 | |
|---|
| | | | table_role | `raw/input/intermediate/output/audit/manifest/index` | |
|---|
| | | | row_grain | 一行代表什么 | |
|---|
| | | | primary_key | 主键 | |
|---|
| | | | unique_key | 唯一约束 | |
|---|
| | | | producer | 生产者 | |
|---|
| | | | consumer | 消费者 | |
|---|
| | | | update_mode | `append/upsert/overwrite_snapshot/manual` | |
|---|
| | | | official_flag | 是否正式数据 | |
|---|
| | | | retention_policy | 保留策略 | |
|---|
| | | |
|---|
| | | ## 8. schema 字段要求 |
|---|
| | | |
|---|
| | | 每张结构化表必须写字段级 schema。 |
|---|
| | | |
|---|
| | | 字段 schema 至少包含： |
|---|
| | | |
|---|
| | | | 字段 | 说明 | |
|---|
| | | |---|---| |
|---|
| | | | field_name | 字段名 | |
|---|
| | | | data_type | 类型 | |
|---|
| | | | required | 是否必填 | |
|---|
| | | | nullable | 是否允许空 | |
|---|
| | | | enum_values | 枚举值，如无则为空 | |
|---|
| | | | meaning | 字段含义 | |
|---|
| | | | source | 字段来源 | |
|---|
| | | | time_semantics | 时间口径，如 as-of、event-time、generated-time | |
|---|
| | | | example | 示例 | |
|---|
| | | | notes | 注意事项 | |
|---|
| | | |
|---|
| | | 涉及时序决策、事件、时间窗口、外部信息时，必须写清时间口径，避免把未来可见信息当成当时可见信息。 |
|---|
| | | |
|---|
| | | ## 9. ID 和追踪字段 |
|---|
| | | |
|---|
| | | 推荐所有核心表保留以下追踪字段： |
|---|
| | | |
|---|
| | | ```text |
|---|
| | | experiment_id |
|---|
| | | run_id |
|---|
| | | step_id |
|---|
| | | artifact_id |
|---|
| | | source_snapshot_id |
|---|
| | | producer |
|---|
| | | produced_at |
|---|
| | | record_hash |
|---|
| | | source_file_path |
|---|
| | | source_file_sha256 |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | 原则： |
|---|
| | | |
|---|
| | | 1. 不要用 `run_id` 当业务主键。 |
|---|
| | | 2. 不要用中文标题、display name、人工摘要当唯一键。 |
|---|
| | | 3. 同一对象多轮实验不得随意生成不同业务 ID。 |
|---|
| | | 4. 新结论不得覆盖旧结论，应用版本、状态或 run 记录留痕。 |
|---|
| | | |
|---|
| | | ## 10. 数据读取方式 |
|---|
| | | |
|---|
| | | `实验存储体系.md` 必须说明人和 AI 如何读取数据。 |
|---|
| | | |
|---|
| | | 至少写清： |
|---|
| | | |
|---|
| | | 1. 人优先看哪些文档。 |
|---|
| | | 2. AI 优先读哪些 manifest 或表。 |
|---|
| | | 3. 结果包从哪里进入。 |
|---|
| | | 4. 图片从哪里进入。 |
|---|
| | | 5. 数据库表怎么查询。 |
|---|
| | | 6. 单个样本如何从结果表追到原始证据。 |
|---|
| | | |
|---|
| | | 推荐读取路径： |
|---|
| | | |
|---|
| | | ```text |
|---|
| | | 实验总纲 |
|---|
| | | -> 实验设计 |
|---|
| | | -> 结果包入口 |
|---|
| | | -> output_manifest |
|---|
| | | -> schema/table registry |
|---|
| | | -> 具体数据表或图片 |
|---|
| | | -> 审计报告 |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | ## 11. 临时数据和正式数据边界 |
|---|
| | | |
|---|
| | | `tmp/` 只放临时文件。 |
|---|
| | | |
|---|
| | | 临时文件不能作为正式结论入口。 |
|---|
| | | |
|---|
| | | 如果临时结果要进入结论，必须移动到正式结果包或数据库，并在 manifest/schema 中登记。 |
|---|
| | | |
|---|
| | | ## 12. 审计要求 |
|---|
| | | |
|---|
| | | 实验存储体系审计重点： |
|---|
| | | |
|---|
| | | 1. 结果包能否找到。 |
|---|
| | | 2. 关键数据是否能追到来源。 |
|---|
| | | 3. 表 schema 是否写到字段级。 |
|---|
| | | 4. 图片是否能从样本或结果表反查。 |
|---|
| | | 5. 临时数据是否被误当正式结果。 |
|---|
| | | 6. 时间口径是否清楚。 |
|---|
| | | |
|---|
| | | 审计不应把存储体系变成重型 gate。存储体系的目标是让人和 AI 能找到、读懂、复核数据，不是给主流程层层加码。 |
|---|
| | | 1. 不得把 `exp-data/tmp/` 当正式证据入口。 |
|---|
| | | 2. 不得把数据库密码、授权 token 或私有凭据写入结果包。 |
|---|
| | | 3. 不得只有窗口文字结论而没有结果包或明确的 `HELD` 记录。 |
|---|
| | | 4. 不得把大表、大日志或批量图片直接回显到 Codex 会话窗口。 |
|---|
