From 873dca205129f123d5ea9dd768bfa1c2e5452830 Mon Sep 17 00:00:00 2001 From: MB-X Bilibili Pipeline <mbx-bili-pipeline@localhost> Date: Sat, 05 Sep 2026 22:27:58 +0800 Subject: [PATCH] chore(project-info): archive Bilibili dynamic 66e47c0ffa2d --- exp-doc/实验规范.md | 508 +++----------------------------------------------------- 1 files changed, 29 insertions(+), 479 deletions(-) diff --git "a/exp-doc/\345\256\236\351\252\214\350\247\204\350\214\203.md" "b/exp-doc/\345\256\236\351\252\214\350\247\204\350\214\203.md" index 0d21671..a01f949 100644 --- "a/exp-doc/\345\256\236\351\252\214\350\247\204\350\214\203.md" +++ "b/exp-doc/\345\256\236\351\252\214\350\247\204\350\214\203.md" @@ -1,492 +1,42 @@ -# 实验规范 +# 实验规范 -创建人员：Codex -文件职责：定义通用实验体系的文档结构、实验设计流程、实验执行流程、审计入口和模板使用规则。 -管理规范/模板：项目通用实验体系架构文档；本文件不是模板文档，模板文档放在 `common/exp-doc/*模版.md`。 -引用文件：../../管理系统说明.md；../../体系说明.md；../pro-doc/需求规范.md；../dev-doc/编码规范.md；历史实验总纲、实验设计、实验计划、执行约定已去项目化抽象。 +创建人员：management.admin +文件职责：记录 `project-info` 项目实验员必须遵守的本地实验规范。本文件引用 common 实验规范，不得削弱 common 硬约束。 +管理规范/模板：../../common/exp-doc/实验规范.md；../../common/exp-doc/实验环境创建指南.md。 +引用文件：目录导读.md；实验总纲.md；实验设计.md；实验执行日志.md；实验存储体系.md；实验审计报告.md；../项目配置清单.md。 +记录方式：项目本地规范；本项目实验流程或补充规则变化时更新。 -统一依赖：本规范必须同时遵守 `../../全局规范.md` 和 `../project-doc/项目规范.md`；项目本地实验规范可补充流程，但不得违反全局规范、全局项目规范和本体系硬约束。 +## 1. 基本口径 -## 1. 定位 +本项目所有实验员必须同时遵守 `../../common/exp-doc/实验规范.md` 和本文件。本文件当前只做项目化补充；如后续设计本地实验流程，必须满足 common 实验规范硬约束，流程通过审核后执行。 -实验是一种事项类型。 +## 2. 项目实验范围 -实验不是单纯跑脚本，也不是只看 summary。实验必须把一个问题从“为什么要做”推进到“怎么验证、怎么执行、证据在哪里、结论能读到什么程度、是否通过审核”。 +本项目实验用于验证股市信息分析相关问题，包括： -实验体系的目标： +1. K 线、成交量、市场广度、行业表现等数据统计或回放。 +2. 研报、新闻、公告、公开网络信息形成的规则或假设。 +3. 案例体系提出的假设是否能通过数据或证据包验证。 +4. darkline 信息拓扑方法的局部验证。 -1. 让实验目标、背景、原理来源可追踪。 -2. 让实验设计能证明总纲里的目标。 -3. 让实验执行过程、关键数据、结果包可复核。 -4. 让设计和执行都经过审核，具体审核规则见 `实验审核规范.md`。 -5. 让总纲、设计、执行日志、审计报告能用统一 ID 串成证据链。 -6. 让结论能回写到方法论、需求、代码、数据或下一轮实验。 +实验结论必须降读为实验范围内结论，不得外推为交易建议、收益承诺或预测能力。 -## 1A. 全局规范和项目本地规范 +## 3. 核心实验文档作用 -`common/exp-doc/实验规范.md` 是全局通用实验规范。 +| 文档 | 作用 | +|---|---| +| `实验总纲.md` | 记录本项目所有实验事项的背景、目标、边界、状态、结果包入口和结论 | +| `实验设计.md` | 记录实验设计、步骤、依赖、产物和判定标准 | +| `实验执行日志.md` | 记录实验 run、输入、关键中间过程、中间数据路径、输出、异常、自检和重跑 | +| `实验存储体系.md` | 说明实验数据、结果包、图片、表 schema 和读取追踪方式 | +| `实验审计报告.md` | 记录设计审核、执行审核和复审结论 | +| `实验问题记录.md` | 记录非审计来源实验问题；审计问题只记录索引 | -所有项目的实验员都必须遵守本文件。每个项目创建实验环境时都必须创建项目本地 `exp-doc/实验规范.md`。项目本地规范默认可以很短，只引用本文件并声明必须遵守；如果补充项目特化规则，不能违反本文件的硬约束。具体流程可以按 1A.1 设计本地版本。 +## 4. 轻量实验和正式实验 -项目本地 `实验规范.md` 即使没有额外项目规则，也必须说明本项目核心实验文档的作用和入口，至少覆盖：`实验总纲.md`、`实验设计.md`、`实验执行日志.md`、`实验存储体系.md`、`实验审计报告.md`、`实验问题记录.md`。这样实验员进入项目后，不需要回头翻 common 文档也能知道本项目实验证据链怎么走。 +- 轻量实验：用于环境 dry-run、口径确认或一次性只读统计；仍要写总纲、设计、执行日志和审计记录，但可不生成复杂结果包。 +- 正式实验：会影响项目结论或后续案例判断；必须先设计审核，通过后执行，执行后提交执行审核。 -项目本地规范允许补充： +## 5. 数据和上下文保护 -1. 项目目录映射。 -2. 项目专用数据源和结果包路径。 -3. 项目专用命名规则。 -4. 项目专用实验类型和轻重流程区分。 -5. 项目专用角色分工。 - -项目本地规范不得削弱： - -1. 实验必须有目标和边界。 -2. 实验设计和执行必须可追踪。 -3. 设计和执行必须有审核闭环。 -4. 关键来源聊天记录必须能被审核员看到。 -5. 结论不得超过证据范围。 - -如果项目本地规范与 common 规范冲突，必须先修项目本地规范；冲突未解决前，不应把对应实验标为完成。 - -### 1A.1 本地实验流程优先级 - -common 实验规范规定底线和默认流程，项目本地 `实验规范.md` 可以设计更贴合项目的实验流程。 - -本地流程设计必须先满足 common 硬约束：目标和边界清楚、来源聊天记录可见、设计和执行可追踪、设计和执行有审核闭环、结论不过读。 - -本地流程可以做两类调整： - -1. 新增流程：例如新增项目专用样本验收流程、人工复核流程、案例回放流程。 -2. 修改默认流程：例如把 common 默认步骤拆分、合并、替换为项目内更合适的步骤。 - -如果只是新增流程，只要不违反 common 硬约束即可放行。 -如果是修改默认流程，必须在本地 `实验规范.md` 或对应实验设计中写清楚覆盖范围、替换原因、输入输出、关键证据链和审核点。 - -本地流程一旦设计完成并通过审核，执行时以本地流程为准；审核员也应按已通过的本地流程审计执行结果。只有发现本地流程违反 common 硬约束时，才回到 common 规范要求整改。 - -## 2. 适用范围 - -适用于以下事项： - -1. 理论验证实验。 -2. 策略实验。 -3. 数据实验。 -4. 工程验证实验。 -5. 性能实验。 -6. 样本验收实验。 -7. 案例分析实验。 -8. 外部信息或人工反馈验证实验。 - -临时探索如果要被后续引用为结论，必须补齐为正式实验记录。 - -## 3. 核心文档 - -实验体系的正式文档分为核心文档和模板文档。 - -核心文档用于说明体系和记录具体实验。 - -模板文档用于创建新项目或新实验时实例化，不是具体实验结论。 - -### 3.1 实验规范 - -`实验规范.md` 是实验体系架构文档。 - -它负责说明： - -1. 实验体系有哪些核心文档。 -2. 实验设计和执行的标准流程。 -3. 实验总纲、实验设计、执行日志、结果包、审计报告分别负责什么。 -4. 什么情况下实验可以结束。 - -### 3.1A 实验环境创建指南 - -`实验环境创建指南.md` 是项目启用实验体系时的初始化手册。 - -它负责说明： - -1. 新项目要创建哪些实验目录。 -2. 项目级实验入口、实验存储体系、审计报告和问题记录怎么建。 -3. 单个实验事项如何从总纲、设计、执行日志开始。 -4. 什么情况下实验员环境算 ready。 - -如果一个 AI 要在新项目里创建实验员工作环境，应先读 `实验环境创建指南.md`，再实例化具体模板。 - -### 3.2 实验总纲 - -实验总纲是实验事项入口，对应管理系统里的“事项总纲”。 - -项目内默认只有一个 `exp-doc/实验总纲.md`，用于持续记录所有实验事项的背景、目标、边界、状态、结果包入口和结论。不要默认按实验 ID 创建多份 `<EXP-ID>_实验总纲.md`，否则 AI 和审核员容易漏看版本和上下文。 - -实验总纲必须采用滚动账本方式维护：新实验、新结论、新修订追加到文件末尾，最新内容在最后。文件开头可以维护“当前总览”和固定入口，但不得把最新实验插到前面，也不得覆盖历史记录。 - -实验总纲必须包含事项总纲要求的字段： - -1. 实验事项 ID。 -2. 实验名称。 -3. 背景、由来和原理。 -4. 创建人员。 -5. 创建时间，精确到秒。 -6. 希望达成的目标。 -7. 当前状态。 -8. 当前结论。 -9. 唯一事项 ID。 -10. 事项名称。 -11. 完整来源聊天记录或来源记录路径。 - -实验总纲还应补充： - -1. 原理来源。 -2. 本轮边界。 -3. 实验设计入口。 -4. 结果包入口。 -5. 审计入口。 - -### 3.3 实验设计 - -实验设计已经合并原“实验设计”和“实验计划”的职责。 - -原因：设计回答“如何验证目标”，计划回答“如何分步骤执行”。两者必须绑定，否则容易出现设计和执行脱节。 - -项目内默认只有一个 `exp-doc/实验设计.md`，用于持续记录所有实验的设计、步骤、依赖、产物和判定标准。新实验应追加到该文件，不要默认按实验 ID 创建多份设计文件。 - -实验设计必须采用滚动账本方式维护：新设计、新修订、执行结果回填追加到文件末尾，最新内容在最后。设计可以有顶部“当前设计总览”，但详细设计块必须按时间顺序追加，不能用单实验表单替代长期账本。 - -实验设计对应管理系统里的“事项计划”，必须包含事项计划要求的字段： - -1. 所属事项名称。 -2. 所属事项 ID。 -3. 执行人。 -4. 创建时间，精确到秒。 -5. 目标。 -6. 当前状态。 -7. 当前结论。 -8. 唯一步骤 ID。 -9. 步骤名称。 -10. 来源聊天记录，可为空。 - -实验设计还应包含： - -1. 假设或要验证的问题。 -2. 数据源和样本范围。 -3. 实验组、对照组和边界样本。 -4. 方法步骤。 -5. 防偏差要求；是否需要防未来函数必须由实验目标决定。 -6. 输出产物。 -7. PASS / FAIL / HELD 判定。 -8. 设计审核记录。 - -### 3.4 实验执行日志 - -实验执行日志记录实际执行过程。 - -项目内默认只有一个 `exp-doc/实验执行日志.md`，用于持续记录所有实验 run、输入、关键中间过程、中间数据路径、输出、异常、自检和重跑记录。新 run 应追加到该文件，不要默认按实验 ID 创建多份执行日志。 - -实验执行日志同样采用 append-only 方式维护；每次运行、重跑、失败、暂停、人工操作和复验都追加到文件末尾，最新内容在最后。 - -它负责回答： - -1. 哪天、谁、运行了什么。 -2. 用了什么输入。 -3. 中间过程做了哪些关键处理。 -4. 中间数据或中间表存在哪里。 -5. 生成了什么输出。 -6. 关键计数和关键异常是什么。 -7. 是否偏离设计。 - -执行日志可以简洁，但不能只写“已跑完”。凡是会影响实验结论的关键节点，都要在执行日志中留下可追踪记录。 - -最低要求： - -1. 记录输入冻结或输入快照路径。 -2. 记录每个关键处理节点，例如清洗、特征生成、过滤、抽样、人工标注、模型运行、结果聚合、画图、summary/readout 生成。 -3. 记录每个关键节点的输入、关键中间过程、中间数据路径和输出。 -4. 记录关键计数，例如输入行数、过滤后行数、样本数、图数量、失败数、命中数。 -5. 记录关键校验，例如 schema、路径存在、hash、样本覆盖、目标相关防偏差检查。 -6. 记录异常、偏离设计、补跑、重跑、降读和复审需求。 - -如果中间数据是审计员或后续实验复核结论所必需的，应保存到 `exp-data/result/<run_id>/intermediate/` 或项目内等价正式结果包目录，并在执行日志中写明路径。`exp-data/tmp/` 只适合临时脚本和临时缓存，不能作为正式证据入口。 - -### 3.5 实验结果包 - -实验结果包是产物目录，不是必备模板文档。 - -结果包入口和状态应回写到实验总纲。 - -预期产物、实际产物、验收标准和关键读法应回写到实验设计。 - -数据文件、图表、日志、summary 等资产应符合项目内 `实验存储体系.md` 的规则。 - -如果某个结果包特别复杂，可以在结果包目录内临时放 readme，但它不是实验体系必备模板。 - -结果包应能回答： - -1. 结果包在哪里。 -2. 输入快照是什么。 -3. 输出文件有哪些。 -4. 关键指标是什么。 -5. 自检结果是什么。 -6. 哪些结论可以读，哪些不能读。 -7. 如何复跑或复核。 - -### 3.6 实验存储体系 - -实验存储体系是项目级数据存储合同，不是单次实验模板。 - -项目启用实验体系时，应按 `实验存储体系创建指南.md` 创建项目内 `exp-doc/实验存储体系.md`。 - -它负责回答： - -1. 实验数据存在哪里。 -2. 结果包怎么组织。 -3. 图片和图表怎么存。 -4. 表清单是什么。 -5. 每张表的 schema 和字段含义是什么。 -6. 数据怎么读、怎么取、怎么追到原始来源。 - -### 3.7 实验审核和实验审计报告 - -实验审核的详细规则见 `实验审核规范.md`。 - -实验审计报告覆盖设计审核和执行审核。 - -设计和执行都必须审核。审核未通过时，不得把实验标为完成。 - -审核结果必须记录到对应项目的 `exp-doc/实验审计报告.md`。 - -实验审计报告采用 append-only 方式维护；每次设计审核、执行审核和复审都追加到文件末尾，最新内容在最后。 - -### 3.8 实验问题记录 - -实验问题记录用于记录非审计人员在实验过程中发现的问题，也用于登记需要跨轮跟踪的审计问题索引。 - -审核员在设计审核、执行审核和复审中发现的问题，主记录写入 `实验审计报告.md`；只有需要跨轮跟踪、跨实验汇总或由执行者长期处理时，才在 `实验问题记录.md` 中建立索引，不重复全文。 - -实验员、执行 AI、人工同事或其他非审计角色发现的问题，主记录写入 `实验问题记录.md`。 - -实验问题记录采用 append-only 方式维护；新问题、修复、复验和关闭记录都追加到文件末尾，最新内容在最后。 - -问题必须区分： - -1. 设计问题。 -2. 执行问题。 -3. 数据问题。 -4. 代码问题。 -5. 结论过读。 -6. 需要下一轮实验的问题。 - -### 3.9 结论回写 - -结论回写是实验收尾动作，不是必备独立模板文档。 - -结论回写应记录在实验总纲和实验审计报告里。 - -常见回写目标： - -1. 方法论文档。 -2. 需求文档。 -3. 代码实现方案。 -4. 数据存储规范。 -5. 下一轮实验总纲。 -6. 放弃或暂停说明。 - -如果某个实验产生大量跨文档回写动作，可以在项目内临时建立回写清单，但它不属于实验体系必备模板。 - -## 4. 模板文档 - -`common/exp-doc` 下应提供以下模板： - -1. `实验环境创建指南.md`。 -2. `实验总纲模版.md`。 -3. `实验设计模版.md`。 -4. `实验执行日志模版.md`。 -5. `实验存储体系创建指南.md`。 -6. `实验审核规范.md`。 -7. `实验审计报告模版.md`。 -8. `实验问题记录模版.md`。 -实验体系不强制提供实验导读或实验总纲列表模板。项目如果需要实验目录索引，可在项目总索引里维护；AI 审查实验时直接读取实验总纲。 - -创建新项目或新实验体系时，应按这些模板实例化项目内的实验文档。默认实例化为项目级账本文件：`实验总纲.md`、`实验设计.md`、`实验执行日志.md`，而不是每个实验一份独立文件。 - -这些项目级账本默认学习长期滚动实验文档的写法：顶部保留当前总览和固定口径，正文按时间追加实验块。字段完整性服务于追踪和审计，不应把文档写成难读的厚重表单。 - -模板文档开头也必须保留管理系统要求的文件头： - -1. 创建人员。 -2. 文件职责。 -3. 管理规范或模板。 -4. 引用文件。 - -项目内文档引用项目内文件时，应默认使用相对路径，避免写入依赖个人机器的绝对路径。只有跨项目、跨磁盘或引用 common 规范时，才允许使用绝对路径，并应说明原因。 - -## 5. 实验状态 - -实验状态建议统一使用： - -1. `未开始`：已登记，未设计。 -2. `设计中`：正在写实验总纲或实验设计。 -3. `待设计审核`：设计完成，等待审核。 -4. `设计审核未通过`：设计存在阻断问题，需要修改。 -5. `设计审核通过`：可以进入执行。 -6. `执行中`：正在跑实验或整理结果。 -7. `待执行审核`：执行完成，等待审核。 -8. `执行审核未通过`：执行或结果存在阻断问题，需要修复或重跑。 -9. `完成`：执行审核通过，结论和结果包已归档。 -10. `暂停`：因数据、方向、资源或上游问题暂停。 -11. `取消`：实验不再执行。 - -## 6. 实验设计流程 - -实验设计流程必须有审核闭环。 - -标准流程： - -```text -提出实验问题 --> 创建实验总纲 --> 编写实验设计 --> 设计自检 --> 提交设计审核 --> 审核员审核 --> 审核通过：设计完成，进入执行 --> 审核不通过：修改总纲或实验设计，再次提交审核 -``` - -设计审核的检查项、问题分级、通过条件和记录方式，按 `实验审核规范.md` 执行。 - -## 7. 实验执行流程 - -实验执行流程也必须有审核闭环。 - -标准流程： - -```text -确认设计审核通过 --> 准备输入数据和执行环境 --> 执行实验步骤 --> 记录执行日志 --> 生成结果包 --> 执行自检 --> 提交执行审核 --> 审核员审核 --> 审核通过：实验完成，结论可归档 --> 审核不通过：修复、补证据或重跑，再次提交审核 -``` - -执行审核的检查项、问题分级、通过条件和记录方式，按 `实验审核规范.md` 执行。 - -执行审核通过前，实验不得标记为完成。 - -## 8. 证据链要求 - -每个正式实验必须用统一 ID 串起证据链。 - -最低要求： - -1. `experiment_id`：实验事项唯一 ID，必须出现在实验总纲、实验设计、执行日志、审计报告、结果包或 manifest。 -2. `step_id`：实验设计里的步骤 ID，必须能在执行日志和审计报告里被引用。 -3. `run_id`：每次实际执行的运行 ID，必须能从执行日志追到结果包。 -4. `audit_id`：每次审核 ID，必须能追到对应实验、设计版本、执行 run 或复审对象。 -5. `source_chat_record`：关键来源聊天记录，必须在实验总纲背景中保存原文或路径。 - -推荐证据链： - -```text -实验总纲 experiment_id + source_chat_record --> 实验设计 experiment_id + step_id --> 执行日志 experiment_id + step_id + run_id --> 结果包 run_id --> 审计报告 audit_id + experiment_id + step_id/run_id -``` - -如果证据链断裂，审核员必须指出断在哪一环。 - -## 9. 来源聊天记录要求 - -实验总纲的背景中必须包含最重要的来源聊天记录。 - -可以保存原文，也可以保存明确路径，但必须能让审核员看到用户原始要求。 - -最低要求： - -1. 实验总纲必须记录关键聊天原文或路径。 -2. 实验设计必须说明如何承接这些聊天要求。 -3. 审计报告必须检查聊天要求、实验目标、实验设计是否一致。 -4. 不一致时必须提出，不能只按实验设计本身审核。 - -## 10. 防偏差要求 - -实验设计和执行中必须显式考虑以下风险： - -1. 未来函数。 -2. 样本污染。 -3. 幸存者偏差。 -4. 只看成功样本。 -5. 源数据切换但未记录。 -6. 规则执行和文档描述不一致。 -7. 结论过读。 -8. 把探索结果误读成正式结论。 - -不是每个实验都需要防未来函数。 - -是否必须防未来函数，应根据实验目标判断： - -1. 如果实验目标涉及时序决策、预测、收益率、回放、实时筛选、自动动作，必须检查未来函数。 -2. 如果实验目标是后验理解、图形归纳、案例复盘、方法论总结，可以不按实时决策时点安全要求审核，但结论必须降读，不能写成可实时使用或 prediction ready。 -3. 如果实验目标没有说明是否需要时点安全，设计审核应要求补清楚。 - -其他偏差如果会影响结论，也必须记录处理方式。 - -## 11. 数据和结果归档 - -实验产物应尽量形成结果包。 - -结果包至少应包含： - -1. `summary` 或结果说明。 -2. 输入数据说明。 -3. 输出数据说明。 -4. 关键表或图。 -5. 自检结果。 -6. 审核入口或审核结论。 - -大文件可以只记录索引、路径和 hash，不要求全部塞进文档。 - -## 12. 结论边界 - -实验结论必须写清： - -1. 本轮证明了什么。 -2. 本轮没有证明什么。 -3. 哪些结果可以进入下游。 -4. 哪些结果只能作为观察。 -5. 哪些问题需要下一轮实验。 - -禁止把“样本看起来不错”直接写成“规则已成立”。 - -## 13. 轻量实验 - -轻量实验可以减少文档数量，但不能没有目标、边界和结果记录。 - -轻量实验最低要求： - -1. 在实验总纲或导读里登记。 -2. 写清目标和边界。 -3. 记录结果位置。 -4. 写清结论不能读到什么程度。 - -如果轻量实验结果要进入正式决策，必须补齐实验设计、结果包入口和产物清单、审核报告。 - -## 14. 交付标准 - -一个正式实验完成的最低标准： - -1. 实验总纲存在。 -2. 实验设计存在，并通过设计审核。 -3. 实验执行日志或等价执行记录存在。 -4. 结果包存在，且入口已回写到实验总纲和实验设计。 -5. 实验审计报告存在，并通过执行审核。 -6. 结论边界明确。 -7. 来源聊天记录、实验目标、实验设计已经由审核员确认一致，或已明确记录不一致及处理方式。 -8. 必要结论已回写或记录待回写。 - -缺少执行审核通过结论时，实验状态只能是 `待执行审核`、`执行审核未通过`、`暂停` 或 `HELD`，不能标为 `完成`。 +实验涉及大表、日志、搜索结果或图片时，主体内容必须落到 `exp-data/result/`、readout、manifest 或审计附件；Codex 窗口和 MB-X 消息只展示摘要、关键路径和结论边界。 -- Gitblit v1.9.3