From e87cfdcb76a359d217130b33ffb4ed917b64d230 Mon Sep 17 00:00:00 2001 From: 1 <wentingyear@gmail.com> Date: Thu, 25 Jun 2026 20:56:54 +0800 Subject: [PATCH] fix: rebuild project-info system documents --- exp-doc/实验存储体系.md | 268 ++++++----------------------------------------------- 1 files changed, 32 insertions(+), 236 deletions(-) diff --git "a/exp-doc/\345\256\236\351\252\214\345\255\230\345\202\250\344\275\223\347\263\273.md" "b/exp-doc/\345\256\236\351\252\214\345\255\230\345\202\250\344\275\223\347\263\273.md" index e8f075d..0c8f595 100644 --- "a/exp-doc/\345\256\236\351\252\214\345\255\230\345\202\250\344\275\223\347\263\273.md" +++ "b/exp-doc/\345\256\236\351\252\214\345\255\230\345\202\250\344\275\223\347\263\273.md" @@ -1,254 +1,50 @@ -# 实验存储体系创建指南 +# 实验存储体系 -创建人员：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 会话窗口。 -- Gitblit v1.9.3