clearai-dsh 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (154) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/LICENSE +201 -0
  3. package/README.md +138 -0
  4. package/README.zh-CN.md +138 -0
  5. package/bin/clearai.mjs +224 -0
  6. package/brand/README.md +41 -0
  7. package/brand/logo-512-dark.png +0 -0
  8. package/brand/logo-512.png +0 -0
  9. package/brand/logo-lockup-dark.png +0 -0
  10. package/brand/logo-lockup.png +0 -0
  11. package/brand/logo-lockup.svg +12 -0
  12. package/brand/logo-wordmark.svg +6 -0
  13. package/brand/logo.svg +19 -0
  14. package/cordis.patch.yml +39 -0
  15. package/lib/client.js +3071 -0
  16. package/lib/fold.js +1576 -0
  17. package/lib/host.js +605 -0
  18. package/package.json +65 -0
  19. package/presets/clearai/agent.cordis.yml +226 -0
  20. package/presets/clearai/plugins/brain.js +547 -0
  21. package/presets/clearai/plugins/clearai-kernel.js +5485 -0
  22. package/presets/clearai/plugins/ontology.js +306 -0
  23. package/presets/clearai/plugins/prompts.js +312 -0
  24. package/presets/clearai/preset.yml +5 -0
  25. package/presets/clearai/skills/clearai-loop/SKILL.md +89 -0
  26. package/presets/clearai/template/knowledge/README.md +25 -0
  27. package/presets/clearai/template/memory/README.md +34 -0
  28. package/presets/clearai/template/project.md +49 -0
  29. package/presets/clearai/template/skills/README.md +37 -0
  30. package/presets/clearai/template/skills/chart-diagram-qa/SKILL.md +43 -0
  31. package/presets/clearai/template/skills/citation-management/SKILL.md +73 -0
  32. package/presets/clearai/template/skills/citation-management/references/bibtex_formatting.md +908 -0
  33. package/presets/clearai/template/skills/citation-management/references/citation_validation.md +794 -0
  34. package/presets/clearai/template/skills/citation-management/references/google_scholar_search.md +725 -0
  35. package/presets/clearai/template/skills/citation-management/references/metadata_extraction.md +870 -0
  36. package/presets/clearai/template/skills/citation-management/references/pubmed_search.md +839 -0
  37. package/presets/clearai/template/skills/citation-management/scripts/doi_to_bibtex.py +204 -0
  38. package/presets/clearai/template/skills/citation-management/scripts/extract_metadata.py +569 -0
  39. package/presets/clearai/template/skills/citation-management/scripts/format_bibtex.py +349 -0
  40. package/presets/clearai/template/skills/citation-management/scripts/generate_schematic.py +139 -0
  41. package/presets/clearai/template/skills/citation-management/scripts/generate_schematic_ai.py +817 -0
  42. package/presets/clearai/template/skills/citation-management/scripts/search_google_scholar.py +282 -0
  43. package/presets/clearai/template/skills/citation-management/scripts/search_pubmed.py +398 -0
  44. package/presets/clearai/template/skills/citation-management/scripts/validate_citations.py +497 -0
  45. package/presets/clearai/template/skills/data-analysis/SKILL.md +92 -0
  46. package/presets/clearai/template/skills/data-analysis/checklists/readiness_check.md +23 -0
  47. package/presets/clearai/template/skills/data-analysis/templates/analysis_report.md.tpl +63 -0
  48. package/presets/clearai/template/skills/data-analysis/templates/cleaning_rules_draft.yaml.tpl +32 -0
  49. package/presets/clearai/template/skills/data-analysis/templates/data_dictionary.md.tpl +12 -0
  50. package/presets/clearai/template/skills/data-analysis/templates/domain_knowledge_template.md.tpl +316 -0
  51. package/presets/clearai/template/skills/data-analysis/templates/feature_candidates.json.tpl +20 -0
  52. package/presets/clearai/template/skills/data-analysis/templates/quality_scorecard.md.tpl +30 -0
  53. package/presets/clearai/template/skills/data-analysis/workflows/01-data-profiling.md +42 -0
  54. package/presets/clearai/template/skills/data-analysis/workflows/02-quality-audit.md +36 -0
  55. package/presets/clearai/template/skills/data-analysis/workflows/03-physical-correlation.md +25 -0
  56. package/presets/clearai/template/skills/data-analysis/workflows/04-unstructured-mining.md +26 -0
  57. package/presets/clearai/template/skills/data-qa-analysis/SKILL.md +102 -0
  58. package/presets/clearai/template/skills/data-qa-analysis/checklists/readiness_check.md +62 -0
  59. package/presets/clearai/template/skills/data-qa-analysis/templates/best_in_class_report.md.tpl +56 -0
  60. package/presets/clearai/template/skills/data-qa-analysis/templates/cleaning_rules_draft.yaml.tpl +56 -0
  61. package/presets/clearai/template/skills/data-qa-analysis/templates/data_dictionary.md.tpl +13 -0
  62. package/presets/clearai/template/skills/data-qa-analysis/templates/data_source_inventory_and_lineage.md.tpl +146 -0
  63. package/presets/clearai/template/skills/data-qa-analysis/templates/data_status_report.md.tpl +60 -0
  64. package/presets/clearai/template/skills/data-qa-analysis/templates/steady_state_rules.yaml.tpl +41 -0
  65. package/presets/clearai/template/skills/data-qa-analysis/templates/subsystem_registry.md.tpl +101 -0
  66. package/presets/clearai/template/skills/data-qa-analysis/templates/unified_execution_plan.md.tpl +100 -0
  67. package/presets/clearai/template/skills/data-qa-analysis/workflows/01-data-source-inventory-and-lineage.md +194 -0
  68. package/presets/clearai/template/skills/data-qa-analysis/workflows/02-data-alignment-and-tag-semantics.md +122 -0
  69. package/presets/clearai/template/skills/data-qa-analysis/workflows/03-steady-state-identification.md +126 -0
  70. package/presets/clearai/template/skills/data-qa-analysis/workflows/04-consumption-analysis.md +152 -0
  71. package/presets/clearai/template/skills/data-qa-analysis/workflows/05-best-in-class-and-optimization-space.md +78 -0
  72. package/presets/clearai/template/skills/domain-presearch/SKILL.md +131 -0
  73. package/presets/clearai/template/skills/domain-presearch/checklists/domain_checklist.md +24 -0
  74. package/presets/clearai/template/skills/domain-presearch/references/figure_code.md +78 -0
  75. package/presets/clearai/template/skills/domain-presearch/references/strategic_frameworks.md +38 -0
  76. package/presets/clearai/template/skills/exploration-loop/SKILL.md +81 -0
  77. package/presets/clearai/template/skills/exploratory-data-analysis/SKILL.md +77 -0
  78. package/presets/clearai/template/skills/exploratory-data-analysis/references/bioinformatics_genomics_formats.md +664 -0
  79. package/presets/clearai/template/skills/exploratory-data-analysis/references/chemistry_molecular_formats.md +664 -0
  80. package/presets/clearai/template/skills/exploratory-data-analysis/references/general_scientific_formats.md +518 -0
  81. package/presets/clearai/template/skills/exploratory-data-analysis/references/microscopy_imaging_formats.md +620 -0
  82. package/presets/clearai/template/skills/exploratory-data-analysis/references/proteomics_metabolomics_formats.md +517 -0
  83. package/presets/clearai/template/skills/exploratory-data-analysis/references/spectroscopy_analytical_formats.md +633 -0
  84. package/presets/clearai/template/skills/exploratory-data-analysis/scripts/eda_analyzer.py +547 -0
  85. package/presets/clearai/template/skills/hypothesis-generation/SKILL.md +73 -0
  86. package/presets/clearai/template/skills/hypothesis-generation/references/experimental_design_patterns.md +329 -0
  87. package/presets/clearai/template/skills/hypothesis-generation/references/hypothesis_quality_criteria.md +198 -0
  88. package/presets/clearai/template/skills/hypothesis-generation/references/literature_search_strategies.md +622 -0
  89. package/presets/clearai/template/skills/hypothesis-generation/scripts/generate_schematic.py +139 -0
  90. package/presets/clearai/template/skills/hypothesis-generation/scripts/generate_schematic_ai.py +817 -0
  91. package/presets/clearai/template/skills/literature-review/SKILL.md +72 -0
  92. package/presets/clearai/template/skills/literature-review/references/citation_styles.md +166 -0
  93. package/presets/clearai/template/skills/literature-review/references/database_strategies.md +455 -0
  94. package/presets/clearai/template/skills/literature-review/scripts/generate_pdf.py +176 -0
  95. package/presets/clearai/template/skills/literature-review/scripts/generate_schematic.py +139 -0
  96. package/presets/clearai/template/skills/literature-review/scripts/generate_schematic_ai.py +817 -0
  97. package/presets/clearai/template/skills/literature-review/scripts/search_databases.py +303 -0
  98. package/presets/clearai/template/skills/literature-review/scripts/verify_citations.py +221 -0
  99. package/presets/clearai/template/skills/paper-lookup/SKILL.md +59 -0
  100. package/presets/clearai/template/skills/paper-lookup/references/arxiv.md +161 -0
  101. package/presets/clearai/template/skills/paper-lookup/references/biorxiv.md +118 -0
  102. package/presets/clearai/template/skills/paper-lookup/references/core.md +150 -0
  103. package/presets/clearai/template/skills/paper-lookup/references/crossref.md +181 -0
  104. package/presets/clearai/template/skills/paper-lookup/references/medrxiv.md +104 -0
  105. package/presets/clearai/template/skills/paper-lookup/references/openalex.md +174 -0
  106. package/presets/clearai/template/skills/paper-lookup/references/pmc.md +152 -0
  107. package/presets/clearai/template/skills/paper-lookup/references/pubmed.md +124 -0
  108. package/presets/clearai/template/skills/paper-lookup/references/semantic-scholar.md +203 -0
  109. package/presets/clearai/template/skills/paper-lookup/references/unpaywall.md +127 -0
  110. package/presets/clearai/template/skills/process-presearch/SKILL.md +196 -0
  111. package/presets/clearai/template/skills/process-presearch/checklists/process_checklist.md +18 -0
  112. package/presets/clearai/template/skills/process-presearch/references/figure_code.md +107 -0
  113. package/presets/clearai/template/skills/process-presearch/references/source_attribution_example.md +22 -0
  114. package/presets/clearai/template/skills/process-understanding-extraction/SKILL.md +69 -0
  115. package/presets/clearai/template/skills/process-understanding-extraction/checklists/readiness_check.md +34 -0
  116. package/presets/clearai/template/skills/process-understanding-extraction/templates/docx_raw_dump_extractor.py.tpl +132 -0
  117. package/presets/clearai/template/skills/process-understanding-extraction/templates/entity_map_unit_topology.json.tpl +86 -0
  118. package/presets/clearai/template/skills/process-understanding-extraction/templates/process_brief.md.tpl +89 -0
  119. package/presets/clearai/template/skills/process-understanding-extraction/templates/process_brief_builder_from_raw_dump.py.tpl +203 -0
  120. package/presets/clearai/template/skills/process-understanding-extraction/templates/process_flow_mermaid.md.tpl +41 -0
  121. package/presets/clearai/template/skills/process-understanding-extraction/templates/unified_execution_plan.md.tpl +53 -0
  122. package/presets/clearai/template/skills/process-understanding-extraction/workflows/01-process-doc-discovery.md +173 -0
  123. package/presets/clearai/template/skills/process-understanding-extraction/workflows/02-process-understanding-and-diagramming.md +106 -0
  124. package/presets/clearai/template/skills/scientific-brainstorming/SKILL.md +64 -0
  125. package/presets/clearai/template/skills/scientific-brainstorming/references/brainstorming_methods.md +326 -0
  126. package/presets/clearai/template/skills/scientific-critical-thinking/SKILL.md +72 -0
  127. package/presets/clearai/template/skills/scientific-critical-thinking/references/common_biases.md +364 -0
  128. package/presets/clearai/template/skills/scientific-critical-thinking/references/evidence_hierarchy.md +485 -0
  129. package/presets/clearai/template/skills/scientific-critical-thinking/references/experimental_design.md +496 -0
  130. package/presets/clearai/template/skills/scientific-critical-thinking/references/logical_fallacies.md +478 -0
  131. package/presets/clearai/template/skills/scientific-critical-thinking/references/scientific_method.md +169 -0
  132. package/presets/clearai/template/skills/scientific-critical-thinking/references/statistical_pitfalls.md +506 -0
  133. package/presets/clearai/template/skills/skill-creator/SKILL.md +109 -0
  134. package/presets/clearai/template/skills/skill-creator/references/authoring-guide.md +89 -0
  135. package/presets/clearai/template/skills/statistical-analysis/SKILL.md +79 -0
  136. package/presets/clearai/template/skills/statistical-analysis/references/assumptions_and_diagnostics.md +369 -0
  137. package/presets/clearai/template/skills/statistical-analysis/references/bayesian_statistics.md +653 -0
  138. package/presets/clearai/template/skills/statistical-analysis/references/effect_sizes_and_power.md +578 -0
  139. package/presets/clearai/template/skills/statistical-analysis/references/reporting_standards.md +469 -0
  140. package/presets/clearai/template/skills/statistical-analysis/references/test_selection_guide.md +129 -0
  141. package/presets/clearai/template/skills/statistical-analysis/scripts/assumption_checks.py +538 -0
  142. package/presets/clearai/template/skills/web-artifact/SKILL.md +165 -0
  143. package/presets/clearai/template/skills/web-artifact/assets/renderer/renderer.css +229 -0
  144. package/presets/clearai/template/skills/web-artifact/assets/renderer/renderer.js +373 -0
  145. package/presets/clearai/template/skills/web-artifact/assets/vendor/elkjs/LICENSE +263 -0
  146. package/presets/clearai/template/skills/web-artifact/assets/vendor/elkjs/UPSTREAM.md +26 -0
  147. package/presets/clearai/template/skills/web-artifact/assets/vendor/elkjs/elk.bundled.js +6605 -0
  148. package/presets/clearai/template/skills/web-artifact/references/when-drawing-a-topology.md +150 -0
  149. package/presets/clearai/template/skills/web-artifact/references/when-the-page-must-work-offline.md +62 -0
  150. package/presets/clearai/template/skills/web-artifact/scripts/check_artifact.py +167 -0
  151. package/presets/clearai/template/skills/web-artifact/scripts/render_topology.js +272 -0
  152. package/presets/clearai/template/skills/what-if-oracle/LICENSE.txt +5 -0
  153. package/presets/clearai/template/skills/what-if-oracle/SKILL.md +72 -0
  154. package/presets/clearai/template/skills/what-if-oracle/references/scenario-templates.md +154 -0
@@ -0,0 +1,194 @@
1
+ # Workflow 1: 数据源盘点与数据血缘 (Data Source Inventory & Lineage)
2
+
3
+ ## 目标
4
+ 建议在你已经具备“上游系统边界与结构骨架”的前提下(例如已拿到 `products/extracted/unit_inventory.md`、`products/extracted/segment_boundary.md`、`products/extracted/entity_map.json`),先回答两个问题:
5
+ 1. **我正在分析的数据从哪里来?**(数据源盘点)
6
+ 2. **我现在已有的数据是否已经“对齐可用”?如果没有,我如何用已有数据合成一张“对齐的母表/指标母表”?**(时间对齐 + 信息对齐 + 可追溯)
7
+
8
+ > **Rule**:未完成最小血缘交付物(数据源清单 + 血缘图 + 冲突优先级)前,禁止进入稳态、单位代价、BiC/P20 等下游分析。
9
+
10
+ ## 输入
11
+ - 原始数据导出(历史 CSV、采集系统导出、离线检测/人工记录、报警/事件日志)
12
+ - 元数据(通道清单、单位、设计值/告警限、实验方案/操作说明文本)
13
+ - 现有合并/清洗产物(若已存在)
14
+
15
+ ## 步骤
16
+
17
+ ### Step 1: 盘点所有数据源(Inventory)
18
+ 至少列出以下字段:
19
+ - **路径**:文件夹/文件名模式(含通配)
20
+ - **来源系统**:采集系统/时序数据库/历史库/手工记录表/检测系统/公开数据集/管理系统
21
+ - **数据类型**:连续模拟量/离散状态/事件日志/离线检测点检/设计值与告警限
22
+ - **时间范围**:起止时间、时区
23
+ - **采样频率/粒度**:1min/5min/1h/按事件
24
+ - **关键字段**:时间列、主键(如实验批次号)、Tag/通道列
25
+ - **表头结构**:是否存在多行表头(描述/要点/设计值/告警限),以及其行含义
26
+ - **编码与单位**:utf-8-sig/gbk;单位是否统一
27
+
28
+ 产出填入:`templates/data_source_inventory_and_lineage.md.tpl` 的“数据源清单”章节。
29
+
30
+ ### Step 2: 定义“对齐母表”的目标与表结构(Mother Table Alignment Spec)
31
+ 把项目中真正用于计算 KPI/稳态/标杆的表明确为 **母表**。然后用“对齐视角”写清楚它的规格(Spec):
32
+ - **时间对齐**:时间列字段名、时区、解析规则、采样粒度(1min/5min/1h)、重采样策略(如需)
33
+ - **通道对齐**:通道全集来自哪些数据源?是否需要 Tag 归一化(`-/_`、`.PV/.OUT`)与映射表?
34
+ - **元数据对齐**:描述/要点/方案/设计值/告警限/正常范围来自哪一层?如何与数据层绑定?
35
+ - **单位与口径对齐**:g/s vs kg/h、计数 vs 速率;净输入/净输出/内部循环规则是否已与系统边界一致?
36
+
37
+ > **建议**:母表命名统一包含“合并后 / filtered / mother”关键词,避免多人协作时搞混版本。
38
+
39
+ ### Step 3: 绘制“对齐流水线血缘”(Alignment Lineage)
40
+ 使用 Mermaid 画出“从**已有数据源/已有产物** → 对齐加工 → 母表”的链路,并给每一条边补充:
41
+ - **时间轴处理**:join key、outer/left、dedup、resample
42
+ - **通道处理**:归一化/映射、冲突优先级(同通道同时间)、缺失补齐策略
43
+ - **元数据处理**:多行表头保留策略/结构化拆分策略、元数据优先级
44
+
45
+ > **说明**:很多项目并不会要求你从“最原始导出”开始复现整条加工链路,而是直接给到若干**已有中间产物**(例如 `历史数据_合并/`、`补充_合并大表.csv`)。
46
+ > 此时血缘图的起点应以“已有中间产物”为准;同时在备注中保留“可选的上游追溯路径”(用于审计与复现)。
47
+
48
+ 最小血缘图应包含:
49
+ - **原始数据节点**(按来源系统划分)
50
+ - **中间产物节点**(按加工阶段划分)
51
+ - **母表节点**
52
+
53
+ #### 3.1 母表合成模式库(Patterns,非唯一,但必须选一种并声明)
54
+ 不同项目拿到的“上游数据形态”不同,母表(`products/extracted/mother_table_aligned.csv`)的合成链路也不同。下列模式是常见情形,但不是唯一方式。
55
+ > **强制要求**:你必须明确声明“本项目采用哪一种 Pattern(P0~P5)”,并在 `products/extracted/data_lineage.mmd` 的首段写清理由与各 stage 的输入/输出文件名模式(用占位路径表达)。
56
+ > **禁止**:只画一个“FullTable→MotherTable”而不解释 FullTable 的来源与阶段(否则无法追溯)。
57
+
58
+ **Pattern P0(最小交付)**:只拿到现成母表或同等对齐宽表
59
+ - 输入:`lab/data/mother_table_aligned.csv`(或 `input/` 中等价文件,对齐后落 `products/extracted/`)
60
+ - 要求:仍需补齐 Step 2 的 Spec 与 Step 4 的 Contract(否则口径不可复现)
61
+
62
+ **Pattern P1(分阶段合并)**:原始历史导出 → 历史合并产物 → 项目级合并产物 → 对齐母表
63
+ - 形态:`lab/data/raw_history_exports/` → `lab/data/history_merged/` → `lab/data/project_merged/` → `products/extracted/mother_table_aligned.csv`
64
+ - 适用:你确实看到了“先把历史数据合成一个合并目录/宽表”,再进入“项目级合并后目录/宽表”的情况
65
+
66
+ **Pattern P2(已有项目级宽表直对齐)**:只拿到项目级合并宽表,再按 Spec/Contract 对齐
67
+ - 形态:`lab/data/project_merged/` → `products/extracted/mother_table_aligned.csv`
68
+
69
+ **Pattern P3(直连历史库查询对齐)**:从时序数据库/历史库按 tag 清单拉取对齐宽表
70
+ - 形态:`historian_query(tags,time_range)` → `lab/data/aligned_wide_table.csv` → `products/extracted/mother_table_aligned.csv`
71
+
72
+ **Pattern P4(多观测段多母表)**:一个项目多个观测段/实验阶段,各自母表,再汇总系统母表
73
+ - 形态:`products/extracted/mother_segment_*/` → `products/extracted/system_mother_table_aligned.csv`
74
+ - 要求:必须写清“系统级口径如何合并”(并行子系统相加/取加权平均/按边界重算)
75
+
76
+ **Pattern P5(增量追加滚动重算)**:按月/按批追加,周期性去重、冲突覆盖,滚动产出母表
77
+ - 形态:`lab/data/monthly_append/` → `lab/data/rolling_merged/` → `products/extracted/mother_table_aligned.csv`
78
+
79
+ #### 3.2 选型闸门(强制写入血缘交付)
80
+ 在 `products/extracted/data_lineage.mmd` 的开头(非 Mermaid 图内)必须写出:
81
+ - 选用 Pattern:P0/P1/P2/P3/P4/P5
82
+ - 选型理由:你拿到的上游产物是什么、为什么跳过/包含某些阶段
83
+ - Stage 列表:每一层的输入/输出文件名模式(glob),以及该层的关键加工动作(concat/dedup/outer join/priority/meta header)
84
+
85
+ #### 3.3 同一项目存在多张母表(必须支持)
86
+ 同一项目中同时存在多张母表是常见情况,例如:
87
+ - **按观测段拆分**:不同 segment 各自一张 `products/extracted/mother_table_aligned.csv`(对应 Pattern P4)
88
+ - **按粒度拆分**:1min 母表用于稳态/波动,1h 母表用于代价/报表
89
+ - **按用途拆分**:全量对齐母表(保护所有通道)与若干派生表(如稳态表);需要明确“谁是母表、谁是派生表”
90
+
91
+ > **Rule(强制)**:当存在多张母表时,不允许只写“一个母表路径”。必须建立并维护一份“母表清单(Mother Table Registry)”,让每张母表都可追溯、可复现、可对齐口径。
92
+
93
+ **强制产出**:`products/extracted/mother_table_registry.md`(或 `.csv`,二选一即可)
94
+
95
+ Registry 至少包含以下字段(建议按表格输出):
96
+ - `mother_id`:母表唯一标识(例如 `segment_fieldtest_1min`)
97
+ - `path`:母表文件路径(例如 `products/extracted/mother_tables/<segment>/mother_table_aligned.csv`)
98
+ - `boundary_or_segment`:对应边界/观测段(引用上游结构骨架的边界定义口径)
99
+ - `time_grain`:时间粒度(1min/5min/1h/…)
100
+ - `intended_use`:用途(稳态识别/单位代价/诊断/报表/…)
101
+ - `pattern_id`:采用的 Pattern(P0~P5)
102
+ - `upstream_artifacts`:上游输入产物(glob)
103
+ - `merge_contract_ref`:合并契约引用(`products/extracted/merge_contract.md` 的章节或补充文件)
104
+ - `notes`:例如“这是系统级母表/这是 segment 母表/这是派生表(非母表)”
105
+
106
+ ### Step 4: 固化“冲突优先级”和“时间去重规则”
107
+ 连续观测/长期实验常见的冲突:
108
+ - **同一 Tag + 同一时间点**,来自多个源(历史库 vs 补充导出)
109
+ - **同一时间点多行重复**(通讯重传/导出重复/拼接重复)
110
+ - **同一 Tag 多种命名**(下划线/横线、后缀 `.PV/.OUT/.MV`)
111
+
112
+ 必须明确:
113
+ - **冲突优先级**:谁覆盖谁、谁用于填空
114
+ - **去重规则**:`keep="first"` / `keep="last"` / 聚合(平均/中位数)
115
+ - **时间解析**:时区、字符串格式、非法值处理
116
+
117
+ ### Step 5: (可选)把“多行表头”当作元数据层处理
118
+ 如果 CSV/Excel 不是“单行表头”,而是多行(如“描述/要点/方案/设计值/告警限”),建议将其拆为:
119
+ - `header_meta`:通道 → (描述/要点/方案片段/设计值/告警限/正常范围/仪器量程)
120
+ - `data_table`:时间点 → 通道值
121
+
122
+ 并在后续 pipeline 中做到:
123
+ - **元数据优先合并/覆盖**(通常来自权威通道清单/实验方案)
124
+ - **数据层按时间点对齐**(outer join)
125
+
126
+ ### Step 6: 生成“对齐母表”(强制产出)
127
+ 基于 Step 2 的母表规格(Spec)与 Step 4 的合并契约(Contract),必须落地生成一份“可直接用于稳态/单位代价/BiC”的对齐母表。
128
+
129
+ **强制要求**:
130
+ - **时间对齐**:以时间列为 join key,采用 outer join 得到“时间点并集”(除非 Spec 明确要求 left join)。
131
+ - **通道保护**:采用 outer join 合并通道全集,默认不因缺失率/疑似异常而删列(列删除必须在 Contract 中显式声明)。
132
+ - **冲突可追溯**:同通道同时间冲突严格按优先级覆盖,并在 `products/extracted/merge_contract.md` 说明覆盖/填空策略。
133
+ - **元数据不丢**:如果存在多行表头/元数据行,必须结构化拆分为 `header_meta`(元数据层)+ `data_table`(数据层),并在 Contract 中固定。
134
+ - `products/extracted/mother_table_aligned.csv` **必须是数据层(data_table)**,用于后续所有统计/稳态/标杆计算。
135
+ - `products/extracted/header_meta.csv` 用于解释与治理(描述/单位/量程/设计值/告警限/来源),不得与数据行混排进入后续计算。
136
+
137
+ **下游依赖(强制)**:
138
+ - 从本 workflow 结束开始,后续所有分析(稳态、代价、波动、BiC、改进空间)**只能**基于本步骤产出的 `products/extracted/mother_table_aligned.csv`(以及可选的 `products/extracted/header_meta.csv`、`products/extracted/tag_map.csv`)。
139
+ - 禁止后续 workflow 直接读取“上游原始导出文件”进行指标计算(否则口径会漂移、结论不可复现)。
140
+
141
+ > **补充**:如果本项目存在多张母表(按观测段/按粒度/按用途),则 Step 6 需要为每张母表分别执行一次 Spec+Contract 的对齐落地,并在 `products/extracted/mother_table_registry.md` 中登记清楚(母表之间的关系、用途、是否为系统级母表)。
142
+
143
+ ## 产出物(Outputs)
144
+ - `products/extracted/data_source_inventory.md`:数据源盘点清单(可复用)
145
+ - `products/extracted/data_lineage.mmd`:血缘图(Mermaid)
146
+ - `products/extracted/merge_contract.md`:合并契约(冲突优先级、去重策略、表头行策略)
147
+ - `products/extracted/mother_table_aligned.csv`:对齐母表(时间点对齐 + 通道全集;若多母表则为其中之一或以文件夹承载)
148
+ - `products/extracted/mother_table_registry.md`:母表清单(当存在多张母表时强制;推荐始终产出)
149
+ - (可选,但推荐)`products/extracted/header_meta.csv`:通道元数据层(描述/单位/量程/设计值/告警限/来源)
150
+ - (可选)`products/extracted/tag_map.csv`:通道归一化与映射(raw_tag → canonical_tag → role/PV/MV/KPI)
151
+
152
+ ## 闸门(确认后进入下一 Workflow)
153
+ 在进入 `workflows/02-data-alignment-and-tag-semantics.md`(通道语义与对齐)或任何下游分析前,必须确认本 workflow 产出无误,并在 `products/extracted/merge_contract.md` 或 `products/extracted/data_source_inventory.md` 末尾追加“确认记录”(日期/确认人/结论/疑点与后续动作)。最少确认:
154
+ - **强制产出物是否齐全**:`products/extracted/data_source_inventory.md`、`products/extracted/data_lineage.mmd`、`products/extracted/merge_contract.md`、`products/extracted/mother_table_aligned.csv` 已生成;若存在多母表,`products/extracted/mother_table_registry.md` 已生成并登记清楚。
155
+ - Pattern 选型闸门已声明(P0~P5),且血缘图能解释每个 stage 的输入/输出与关键加工动作(不是“FullTable→MotherTable”一句话带过)。
156
+ - `products/extracted/merge_contract.md` 中 outer join/dedup/priority/meta header 策略可复现,且与实际产物一致。
157
+ - `products/extracted/mother_table_aligned.csv` 的时间轴连续性/去重/列保护策略符合 Spec;若存在多母表,`products/extracted/mother_table_registry.md` 已登记用途、边界、粒度与关系。
158
+
159
+ ## 示例(Example,仅展示写法,不依赖具体文件路径)
160
+
161
+ > **说明**:下面示例展示“不同 Pattern 下的主链路长相”。交付时你只需要画出你项目实际采用的那一种(并在图上写清 merge/对齐动作)。
162
+
163
+ ### 示例 1(Pattern P1):分阶段合并(raw_history_exports → history_merged → project_merged → mother)
164
+
165
+ ```mermaid
166
+ flowchart LR
167
+ rawHistoryExports["raw_history_exports/ (raw)"] -->|"concat+sort+dedup + metaHeaderExtract"| historyMerged["history_merged/ (stage1)"]
168
+ historyMerged -->|"outerJoinOnTime + priorityRule + tagNormalize"| projectMerged["project_merged/ (stage2)"]
169
+ projectMerged -->|"alignSpec + protectAllTags + dataTableOnly"| motherAligned["products/extracted/mother_table_aligned.csv (aligned)"]
170
+
171
+ supplementWide["supplement_wide_table.csv (optional)"] -.->|"outerJoinOnTime + fillNA_byPriority"| projectMerged
172
+ ```
173
+
174
+ ### 示例 2(Pattern P2):已有项目级宽表直对齐(project_merged → mother)
175
+
176
+ ```mermaid
177
+ flowchart LR
178
+ projectMerged["project_merged/ (existing artifacts)"] -->|"alignSpec + protectAllTags + dataTableOnly"| motherAligned["products/extracted/mother_table_aligned.csv (aligned)"]
179
+ ```
180
+
181
+ ### 示例 3(Pattern P3):直连历史库查询对齐(historian_query → aligned_wide_table → mother)
182
+
183
+ ```mermaid
184
+ flowchart LR
185
+ historianQuery["historian_query(tags,time_range)"] -->|"timeAlign+resample + tagNormalize"| alignedWide["aligned_wide_table.csv"]
186
+ alignedWide -->|"alignSpec + protectAllTags + dataTableOnly"| motherAligned["products/extracted/mother_table_aligned.csv (aligned)"]
187
+ ```
188
+
189
+ ### 示例 2:合并契约(冲突优先级)
190
+ 以一个“历史库数据 + 补充导出数据”的常见组合为例,关键约束通常包括:
191
+ - **按时间点 outer join 取并集**
192
+ - **同通道同时间冲突:历史数据优先**;补充数据仅用于填充历史空值
193
+ - **表头多行需要整体保留**(描述/要点/方案/设计值/告警限/正常范围)
194
+ - 历史 CSV 常见编码 **gbk**;且存在“第 1 行为通道名、第 2 行为描述”的结构
@@ -0,0 +1,122 @@
1
+ # Workflow 2: 数据对齐与通道语义 (Data Alignment & Tag Semantics)
2
+
3
+ ## 目标
4
+ 把“能算”的数据变成“算得对”的数据:
5
+ - 时间戳可对齐、可去重、可定义连续性
6
+ - 通道名可统一、可匹配到语义与单位
7
+ - 多源数据可合并且冲突规则清晰
8
+
9
+ > **前置依赖**:必须先完成本 skill 的 `workflows/01-data-source-inventory-and-lineage.md`,明确“对齐母表规格(Spec)”与合并契约;并已具备上游结构 skill 的 `products/extracted/unit_inventory.md`(存在性三态)与 `products/extracted/entity_map.json`(单元级结构骨架,topology-only)。
10
+
11
+ ## 步骤
12
+
13
+ ### Step 1: 时间列识别与解析(Time Contract)
14
+ 必须明确:
15
+ - 时间列字段名(通常为第 2 列)
16
+ - 时区与格式(`YYYY-MM-DD HH:MM:SS` 等)
17
+ - 非法时间处理(`errors='coerce'` → NaT → 后续剔除/回溯)
18
+ - 采样频率(1min/5min/1h),以及对“连续”的定义(如相邻间隔 ≤ 30min)
19
+
20
+ ### Step 2: 重复时间点处理(Dedup)
21
+ 常见原因:
22
+ - 导出重复
23
+ - 多文件拼接重复
24
+ - 通讯重传
25
+
26
+ 规则必须写清楚:
27
+ - `drop_duplicates(subset=[timestamp], keep='first')` 或 `keep='last'`
28
+ - 如同一时间点来自多源,按 `merge_contract` 的优先级处理
29
+
30
+ ### Step 3: 多行表头(元数据层)处理
31
+ 如果表格存在“多行表头”(描述/要点/方案/设计值/告警限等),建议拆成两层:
32
+ - **元数据层 header_meta**:通道 → 描述/单位/量程/设计值/告警限/来源
33
+ - **数据层 data_table**:时间点 → 通道值
34
+
35
+ 后续处理要确保:
36
+ - 表头行在输出中**整体保留**(若业务需要)
37
+ - 或以结构化元数据文件输出(推荐,便于治理)
38
+
39
+ ### Step 4: 通道名归一化(Tag Normalization)
40
+ 推荐最小归一化规则:
41
+ - 分隔符统一:`-` → `_`
42
+ - 后缀忽略:`.PV/.MV/.OUT/.VALUE/.SP/.OP` 等按需去除
43
+ - 大小写统一:建议 upper
44
+
45
+ > **注意**:后缀忽略只用于“匹配/映射”,不建议直接丢弃在最终列名中(否则 PV/MV/OUT 可能混淆)。
46
+
47
+ ### Step 5: 通道语义来源优先级(Description Priority)
48
+ 为每个通道填充“物理含义/单位/量程/来源”,建议优先级如下(从高到低,项目可调整):
49
+ 1. **权威通道清单/测点清单**(如仪器台账、传感器部署表、数据集官方 codebook)
50
+ 2. **历史 CSV 的描述行**(常见结构:第 1 行通道名、第 2 行描述)
51
+ 3. **报警/事件统计表、补充通道信息表**
52
+ 4. **实验方案/操作说明文本抽取/AI 摘要**(必须标注来源路径与置信度)
53
+
54
+ ### Step 6: 生成数据字典与清洗规则草案
55
+ 输出:
56
+ - `products/extracted/data_dictionary.md`(通道、含义、单位、类型、频率、量程、备注)
57
+ - `products/extracted/cleaning_rules.yaml`(物理越限、冻结值、重复时间点、短缺口填补策略等)
58
+ - `products/extracted/missing_tags.md`(缺失/未匹配通道清单 + 建议补齐路径)
59
+
60
+ #### 6.1 通道“缺失/未匹配”的类型(必须区分)
61
+ 为了避免把“没有列”与“有列但没值”混为一谈,必须把缺失拆开统计:
62
+ 0. **存在性未确认(ObjectNotConfirmed)**:来自上游结构 skill 的 `products/extracted/unit_inventory.md` 中,条目为 **State_C(未确认存在)** 的观测单元/流转关系/产物。
63
+ - 这类问题是“系统侧证据不足”,不是“通道缺失”,禁止在此阶段写成“无测量通道”。
64
+ - 处理动作:回到上游结构 skill 补证据(系统叙述/结构图/设备或仪器清单/下游去向证据),把条目提升到 State_A 或 State_B 后再进入测量匹配。
65
+ 1. **Schema 缺失(列缺失)**:母表中没有某个关键通道列(Tag 不存在)→ 属于对齐/合并问题,必须在此 workflow 解决。
66
+ 2. **语义缺失(描述/单位缺失)**:列存在但没有可靠的含义/单位/量程 → 属于元数据治理问题,必须在此 workflow 补齐或标注来源等级。
67
+ 3. **数据缺失(值缺失/NaN)**:列存在但某些时间段缺值 → 属于数据质量与稳态齐全性问题,需在 `workflows/03-steady-state-identification.md` 按连续段检查与处理。
68
+
69
+ 建议在 `products/extracted/missing_tags.md` 中按上述各类分别输出清单与处理建议。
70
+
71
+ #### 6.2 “叙述口径 vs 测量口径”强制对齐(设备编号≠测量通道)
72
+ 在很多观测/实验项目中,资料常以“设备/环节编号”描述(例如“由某泵输送样品/由某加热模块控温”),但数据计算必须以**实际测量通道**为准(流量计/温度计/计数器/功率计等)。
73
+
74
+ 必须产出一份“测量口径映射”(建议以 `products/extracted/tag_map.csv` 与 `products/extracted/entity_map_enriched.json` 表达):
75
+ - 资料对象(设备/环节/流转关系/资源注入) → 测量通道(流量/温度/压力/累计量/功率/计数等)
76
+ - 并指明“指标口径的唯一合法来源”(metric-of-record):例如负荷口径必须使用流量计通道,而非设备运行信号
77
+
78
+ **存在性闸门(必须)**:
79
+ - 仅当对象在 `products/extracted/unit_inventory.md` 中为 **State_A/State_B** 时,才允许进入“测量通道匹配/metric-of-record 确认”。
80
+ - 若对象为 **State_C**,在 `products/extracted/missing_tags.md` 中归类为 **ObjectNotConfirmed**,并回到上游结构 skill 补证据;禁止将其写成“无测量通道/需要代理”。
81
+ - 若对象为 **State_A/State_B** 但确实无法匹配到任何测量通道,才允许将其标注为“**可能无测量通道(候选代理待定)**”,并给出候选代理规则与证据链(例如:累计量替代瞬时速率、下游合并通道替代、功率/状态信号作为弱代理等)。
82
+
83
+ > **Rule**:任何 KPI/单位代价/标杆计算,必须引用该映射中的“metric-of-record”通道;禁止直接用设备编号/环节编号替代测量通道。
84
+
85
+ #### 6.3 基于结构骨架补齐通道(Topology Enrichment)
86
+ 输入:
87
+ - `products/extracted/entity_map.json`(来自上游结构 skill,节点=观测单元+支持设施,边=物质或信号流/资源接口;不含通道号)
88
+ - `products/extracted/unit_inventory.md`(来自上游结构 skill,存在性三态)
89
+ - `products/extracted/mother_table_aligned.csv` 的列名(来自本 skill workflow01)与/或权威通道清单
90
+
91
+ 目标:把结构图变成“能计算”的映射,并进行可用性校验:
92
+ - **对每条物质/信号流边(material edge)**:补齐 `flow_tag`(优先流量/累计量类通道)与单位;必要时补齐 `composition_tags`(可选)。
93
+ - **对每条资源边(resource edge)**:补齐 `power_tag` / `coolant_flow_tag` / `reagent_usage_tag` 等,并标注规格/单位(如适用)。
94
+ - **对每个单元节点(unit node)**:按项目需要补齐 `temp_tag` / `pressure_tag` / `level_tag` / `status_tag` 等(用于稳态判据或诊断)。
95
+
96
+ 校验(必须):
97
+ - 补齐的每个 tag 必须能在母表列名或通道清单中找到;找不到则进入 `products/extracted/missing_tags.md`,并按本 workflow 的缺失类型分类输出。
98
+ - 若某对象在 `products/extracted/unit_inventory.md` 为 State_C,则该对象的任何“边/节点补齐”都应停下并归类为 `ObjectNotConfirmed`(不得写成无测量通道)。
99
+
100
+ 输出(新增):
101
+ - `products/extracted/tag_map.csv`:一行一个 mapping(对象/边/节点 → tag → role → 单位/来源/置信度)
102
+ - `products/extracted/entity_map_enriched.json`:在 `products/extracted/entity_map.json` 的 nodes/edges 上补齐 tags 与 role(用于自动校验与下游计算)
103
+
104
+ ## 产出物
105
+ - `products/extracted/data_dictionary.md`(建议使用模板:`templates/data_dictionary.md.tpl`)
106
+ - `products/extracted/cleaning_rules.yaml`(建议使用模板:`templates/cleaning_rules_draft.yaml.tpl`)
107
+ - `products/extracted/missing_tags.md`
108
+ - `products/extracted/tag_map.csv`(结构补齐后的测量口径映射)
109
+ - `products/extracted/entity_map_enriched.json`(topology + tags)
110
+
111
+ ## 闸门(确认后进入下一 Workflow)
112
+ 在进入 `workflows/03-steady-state-identification.md`(稳态识别)或任何 KPI/单位代价/标杆计算前,必须确认本 workflow 产出无误,并在 `products/extracted/data_dictionary.md` 或 `products/extracted/missing_tags.md` 末尾追加“确认记录”(日期/确认人/结论/疑点与后续动作)。最少确认:
113
+ - **强制产出物是否齐全**:`products/extracted/data_dictionary.md`、`products/extracted/cleaning_rules.yaml`、`products/extracted/missing_tags.md`、`products/extracted/tag_map.csv`、`products/extracted/entity_map_enriched.json` 是否都已生成且内容完整。
114
+ - 通道语义来源优先级已执行:权威通道清单/描述行/补充通道信息表等来源记录清晰、置信度合理。
115
+ - `products/extracted/missing_tags.md` 已区分 `ObjectNotConfirmed` 与 schema/语义/数据缺失,避免“存在性未确认”被误写成“无测量通道”。
116
+ - `products/extracted/tag_map.csv`/`products/extracted/entity_map_enriched.json` 的 metric-of-record 映射可用于计算,且能在母表列名/通道清单中验证存在。
117
+
118
+ ## 示例(Example)
119
+ 常见做法示例(仅展示方法,不依赖具体项目文件):
120
+ - 通道清单/仪器台账/数据集官方 codebook 作为“通道语义与单位”的第一权威来源
121
+ - 历史 CSV 第二行常包含“描述行”,可作为语义补齐来源之一
122
+ - 多行表头建议拆为 `header_meta`(元数据)+ `data_table`(数据层),避免后续误读
@@ -0,0 +1,126 @@
1
+ # Workflow 3: 稳态识别与异常段剔除 (Steady-State Identification)
2
+
3
+ ## 目标
4
+ 在连续观测/长期实验中,很多项目把“稳态”用于表达**系统处于正常有效观测(In-observation)**:即已过启停/校准/维护等异常状态、输入通量达到一定水平后进入可代表的运行区间。
5
+ 本 workflow 的目标是:
6
+ - 先固化“有效观测/非启停校准”的可复现判据(以输入通量/负荷阈值为核心)
7
+ - 在对齐母表上筛出“有效(稳态口径)”时间点集合(并检查连续性与通道齐全性)
8
+ - 产出可审计的剔除段落、稳态表格与规则文件
9
+
10
+ > **强制输入**:本 workflow 的唯一数据输入是 `products/extracted/mother_table_aligned.csv`(来自 `workflows/01-data-source-inventory-and-lineage.md`)。禁止直接使用上游原始导出表。
11
+
12
+ ## 步骤
13
+
14
+ ### Step 0: 输出数据状况报告(稳态前强制)
15
+ 在写任何稳态判据前,必须先回答“这份母表数据是否适合找稳态?”并输出可审计报告(类似数据集的概览页)。
16
+
17
+ **必须统计的最小项**:
18
+ - **时间范围**:最小/最大时间、总点数、覆盖天数/小时数
19
+ - **时间间隔**:相邻时间差分布(P50/P90/P95/Max)、是否存在固定采样周期、是否存在大间隔断点
20
+ - **重复时间点**:重复行数与占比、去重策略(在 `products/extracted/merge_contract.md` 对应)
21
+ - **连续时间段**:按连续性定义(例如相邻间隔 ≤ 30min)切分段,输出段数、最长/最短/平均段长、TopN 段列表
22
+ - **关键通道齐全性(仅针对稳态判据所需通道集合)**:非空率、最大连续缺失时长、缺失最严重的 TopN 通道
23
+
24
+ **强制产出**:
25
+ - `products/extracted/data_status_report.md`(上述摘要 + 关键表格)
26
+ - `products/extracted/time_gap_summary.csv`(时间差分布统计)
27
+ - `products/extracted/continuous_segments.csv`(连续段清单:start/end/duration/points)
28
+
29
+ > **Rule**:如果数据状况报告显示“采样间隔高度不稳定/大段缺失/关键通道长期缺失”,必须先回到 `workflows/01-data-source-inventory-and-lineage.md` / `workflows/02-data-alignment-and-tag-semantics.md` 修正母表对齐或通道语义,再进入稳态判定。
30
+
31
+ ### Step 1: 定义“稳态=有效观测”的工程判据(In-observation Contract)
32
+ 本 Skill 默认把“稳态”定义为:**系统处于有效观测状态(非启停/非校准维护/非明显失真)**,核心判据是**输入通量/负荷高于阈值**(或等价的“实验/采集正常进行”指标)。
33
+
34
+ > **说明(保持通用性)**:
35
+ > - 在许多连续观测场景中,“波动小/方差小”更像是“高质量稳态/深稳态”的精细筛选,并非“是否有效观测”的必要条件。
36
+ > - 本 workflow 的强制交付以“有效稳态(In-observation)”为主;如项目确实需要“深稳态(波动小)”,请把它作为可选的二级筛选(见 Step 3 的可选项)。
37
+
38
+ 本步骤必须先输出“稳态识别依据”(让用户确认后再跑后续识别与拆解),避免“规则一边跑一边改”导致结果不可复现。
39
+
40
+ **强制产出(先产出,先确认)**:
41
+ - `products/extracted/steady_state_basis.md`:稳态识别依据(判据口径、关键通道集合、窗口/连续性/NaN 策略、阈值选型依据、与边界契约的一致性说明)
42
+ - `products/extracted/steady_state_rules.yaml`:基于 `templates/steady_state_rules.yaml.tpl` 的规则草案(阈值需结合数据分布校准)
43
+
44
+ `products/extracted/steady_state_basis.md` 至少应包含:
45
+ - **输入母表**:`products/extracted/mother_table_aligned.csv`(时间范围、采样间隔特征,引用 `products/extracted/data_status_report.md` 的结论)
46
+ - **有效判据口径**:负荷/输入通量口径 \(L\)(来自 `workflow02` 的语义/role)与阈值 \(L_{min}\) 的选型依据
47
+ - **状态切换过渡段处理**:过渡剔除窗口半径(±X 分钟),以及为何需要(避免刚启动/刚停止的瞬态)
48
+ - **窗口与连续性定义**:连续段切分规则(continuous_gap)、短段处理规则
49
+ - **缺失值策略**:NaN 视为异常/跳过/插值(必须选一种并解释原因)
50
+ - **阈值选型依据**:基于分布(Pxx/直方图/实验设计的最小工作点)或领域经验;写明默认值与待校准项
51
+ - **验证计划**:抽检策略(保留段/剔除段各抽多少、看哪些关键曲线)
52
+
53
+ ### Step 1.5: 用户确认闸门(必须通过,才能继续)
54
+ 在执行 Step 2~Step 6(生成 mask/segments/table 等)之前,必须让用户确认:
55
+ - `products/extracted/steady_state_basis.md` 已完整填写,且所有口径/阈值/窗口/缺失值策略可复现
56
+ - `products/extracted/steady_state_rules.yaml` 与 basis 一致
57
+
58
+ 确认方式(二选一,必须有记录):
59
+ 1. 在 `products/extracted/steady_state_basis.md` 末尾追加“确认记录”(日期/确认人/结论/是否允许继续)
60
+ 2. 在统一 plan 的确认区记录本步骤已确认(并引用 `products/extracted/steady_state_basis.md` 路径)
61
+
62
+ ### Step 2: 有效观测标记(In-observation Mask)
63
+ 用“黄金指标”生成有效标记(mask),推荐优先级:
64
+ - **首选**:输入通量/负荷(系统净输入) \(L > L_{min}\)
65
+ - **备选(辅助证据)**:关键资源消耗 \(Q > Q_{min}\)(如功率/流速)、工作条件已建立(温度/压力/真空进入运行区间)等
66
+
67
+ > **关键点**:本步骤生成的是“有效稳态口径”的主判据(不是可选项)。后续所有稳态表格均基于该 mask 及过渡窗口剔除。
68
+
69
+ ### Step 3: 状态切换过渡段窗口剔除(Transition Window Exclusion)
70
+ 对有效标记的“进入/退出边界”(on/off transition),按系统惯性剔除过渡段,推荐:
71
+ - 过渡窗口半径:±30min 或 ±60min(取决于系统响应/热惯性时间尺度)
72
+ - 规则:在“on→off”或“off→on”的切换点附近,窗口内时间点不计入稳态样本
73
+
74
+ 必须写清楚:
75
+ - **过渡窗口大小**与依据(例如升温平衡/建立真空/换批切换的时间尺度)
76
+ - **NaN 的处理**:NaN 视为 off / abnormal / skip(必须选一种并解释原因)
77
+ - **连续性定义**:相邻时间间隔 ≤ 30min 视为连续
78
+
79
+ > **可选(仅当业务需要“深稳态”)**:在完成“有效 + 过渡剔除”后,可再叠加二级筛选(例如关键状态变量 CV/变化率阈值)。若启用,必须在 `products/extracted/steady_state_basis.md` 中明确声明其目的(例如用于建模而非用于覆盖统计)。
80
+
81
+ ### Step 4: 连续性与齐全性检查(必须)
82
+ 对“被判定为稳态”的时间点集合,必须再做两类工程约束检查:
83
+ 1. **时间段连续性**:将稳态时间点按“相邻时间间隔 ≤ continuous_gap”切分为连续段(segment)。
84
+ - 短段(例如 < 1h 或 < N 点)通常代表瞬态残留/通讯断点,应按业务规则处理(剔除或单独标注)。
85
+ 2. **通道齐全性(针对用于稳态判据的通道)**:对每个连续段,检查稳态判据所需通道的非空率。
86
+ - 若某段内关键通道缺失严重(例如非空率 < 95% 或连续缺失超过阈值),该段不能作为稳态分析样本。
87
+
88
+ > **注意**:齐全性检查只针对“稳态判据所需通道集合”,不要把全通道缺失率当作稳态门槛(否则会误删大量可用信息)。
89
+ > 这里检查的是 **数据缺失(值缺失/NaN)**,不是 **列缺失(Schema 缺失)**;列缺失必须回到 `workflows/02-data-alignment-and-tag-semantics.md` 解决。
90
+
91
+ ### Step 5: 产出稳态表格 + 说明文档(强制)
92
+ 必须输出:
93
+ - **稳态掩码**:时间点 → 是否稳态、所属连续段 ID、剔除原因(如有)
94
+ - **稳态段表**:每段起止、时长、样本数、关键通道齐全性、是否通过
95
+ - **稳态数据表**:从 `products/extracted/mother_table_aligned.csv` 过滤得到的“稳态母表”
96
+
97
+ ### Step 6: 人工抽检闭环(建议)
98
+ 抽检建议:
99
+ - 每条规则随机抽 5 段(剔除段与保留段各抽),对照关键曲线确认合理性,并记录证据
100
+
101
+ ## 产出物
102
+ - `products/extracted/data_status_report.md`(稳态前数据状况报告:时间范围/间隔/连续段/关键通道齐全性)
103
+ - `products/extracted/time_gap_summary.csv`(时间差分布统计)
104
+ - `products/extracted/continuous_segments.csv`(连续段清单:start/end/duration/points)
105
+ - `products/extracted/steady_state_basis.md`(稳态识别依据 + 用户确认记录)
106
+ - `products/extracted/steady_state_rules.yaml`
107
+ - `products/extracted/steady_state_mask.csv`(时间点 → 是否稳态 + segment_id + reason)
108
+ - `products/extracted/steady_state_segments.csv`(连续段统计 + 齐全性)
109
+ - `products/extracted/steady_state_table.csv`(稳态母表:从 mother_table_aligned 过滤得到)
110
+ - `products/extracted/steady_state_summary.md`(稳态识别结果说明:样本覆盖、连续段分布、剔除原因 TopN)
111
+ - `products/extracted/steady_state_validation.md`(抽检记录与结论)
112
+
113
+ ## 闸门(确认后进入下一 Workflow)
114
+ 在进入 `workflows/04-consumption-analysis.md` 或 `workflows/05-best-in-class-and-optimization-space.md` 前,必须确认本 workflow 产出无误,并在 `products/extracted/steady_state_summary.md` 或 `products/extracted/steady_state_validation.md` 末尾追加“确认记录”(日期/确认人/结论/疑点与后续动作)。最少确认:
115
+ - **强制产出物是否齐全**:`products/extracted/data_status_report.md`、`products/extracted/time_gap_summary.csv`、`products/extracted/continuous_segments.csv`、`products/extracted/steady_state_basis.md`、`products/extracted/steady_state_rules.yaml`、`products/extracted/steady_state_mask.csv`、`products/extracted/steady_state_segments.csv`、`products/extracted/steady_state_table.csv`、`products/extracted/steady_state_summary.md` 是否都已生成且内容完整。
116
+ - `products/extracted/steady_state_basis.md` 是否包含“用户确认记录”,且确认发生在生成 `steady_state_mask/segments/table` 之前(可追溯)。
117
+ - 稳态规则文件版本已固化(阈值/窗口/连续性/NaN 策略清晰),且与 `steady_state_mask/segments` 的输出一致。
118
+ - 稳态段连续性与关键通道齐全性检查已通过(或已明确剔除/标注未通过段)。
119
+ - 抽检记录存在:保留段与剔除段各有证据,能解释为何进入/退出稳态。
120
+
121
+ ## 示例(Example:异常段剔除的“窗口逻辑”)
122
+ 在连续观测数据中,常用“关键指标阈值 + ±30min 窗口”做预剔除,其关键特征是:
123
+ - **异常条件(OR)**:某些关键通量低于阈值,或关键列存在 NaN
124
+ - **窗口规则**:对每个时间点检查 ±30min,若窗口内全异常则剔除;若窗口内存在至少 1 个正常点则保留
125
+
126
+ 该类规则适合作为“预剔除/质量门槛”,再叠加稳态判据进入代价/效率分析。
@@ -0,0 +1,152 @@
1
+ # Workflow 4: 代价/效率与波动分析 (Cost & Variability Analysis)
2
+
3
+ ## 目标
4
+ 在稳态数据集上,完成两类任务(同一 workflow 内交付,但必须分别写清楚方法与结论):
5
+ 1. **代价/单位代价(Cost & Specific Cost)**:按系统与子系统分别给出资源消耗水平、单位代价分布、负荷影响与长周期基线外推。资源可以是能耗、机时、试剂用量、算力时长、采样成本等。
6
+ 2. **波动(Variability)**:不仅是单位代价波动,也包括系统状态指标(温度/压力/信号强度等)与控制/干预动作(设定值/控制输出)的波动;并要求按观测单元逐一输出诊断与下一步核对建议(不是只列高波动通道)。
7
+
8
+ > **强制输入**:本 workflow 的唯一数据输入是 `products/extracted/steady_state_table.csv`(来自 `workflows/03-steady-state-identification.md`)。
9
+ > 禁止直接使用 `products/extracted/mother_table_aligned.csv` 或上游原始导出表进行代价/单位代价/波动统计(否则会混入无效/过渡段)。
10
+
11
+ > **强制依赖(口径与清单)**:
12
+ > - `workflows/02-data-alignment-and-tag-semantics.md` 的 `products/extracted/tag_map.csv` / `products/extracted/entity_map_enriched.json`(用于负荷口径、代价口径、系统状态指标的 tag 选择与校验)
13
+ > - 上游结构 skill 的 `products/extracted/unit_inventory.md`(用于识别资源接口与“哪些单元应计入某类资源消耗”)
14
+
15
+ ## 步骤
16
+
17
+ > **取证要求**:本 workflow 所有数值须先通过 read/bash 从 `products/extracted/steady_state_table.csv` 等源数据取得,并标注 `来源: <path>`;无法取得则写「待确认」。
18
+
19
+ ### Part A:代价 / 单位代价(Cost & Specific Cost)
20
+
21
+ ### Step 1: 识别“最大代价口径”(Primary Cost Driver)并做覆盖完整性检查
22
+ 不同场景的最大代价资源可能不同:
23
+ - 运行资源:电力/冷却水/压缩气体/机时
24
+ - 消耗品:关键试剂、溶剂、标准品、耗材
25
+ - 其他:算力时长、存储、人工采样工时等
26
+
27
+ 你需要选定“最大代价资源”并明确其 **测量口径**(可追溯):
28
+ - 消耗量 \(Q\):kW、mL/h、样本/h、GPU·h/d 等
29
+ - 负荷 \(L\):样本/h、m³/h、次/h、mol/h(通常优先选**输入通量/系统净输入**)
30
+ - 单位代价 \(SSC\):\(Q/L\)
31
+
32
+ **额外强制(用于分规格资源)**:必须显式声明资源“类型 + 规格/等级”,例如:
33
+ - `power@kW` / `coolant@m3h` / `reagent@gradeA` / `compute@GPUh`
34
+
35
+ 并必须做一次 **消耗方覆盖完整性检查**(确保没有遗漏“使用该资源/规格的单元”):
36
+ 1) 从上游 `products/extracted/unit_inventory.md` 的 `energy_interfaces`(资源接口)与/或 `products/extracted/entity_map_enriched.json` 的 resource edges,列出“理论上应计入该资源规格消耗”的单元清单(expected_consumers)。
37
+ 2) 从 `products/extracted/tag_map.csv` 列出“实际已计量且将纳入 Q 汇总”的单元清单(metered_consumers)。
38
+ 3) 输出缺口:expected_consumers - metered_consumers,并分类:
39
+ - `ObjectNotConfirmed`(单元未确认存在)
40
+ - `Unmetered`(单元确认存在但找不到任何测量 tag)
41
+ - `TagMissingInMotherTable`(tag 有但母表列缺失)
42
+
43
+ > 覆盖检查结果必须写入 `products/extracted/subsystem_registry.md`(见 Step 2)。
44
+
45
+ ### Step 2: 子系统登记(Subsystem Registry,强制)
46
+ 当系统存在多路输入、并且可以合理拆成多个子系统时,必须先落地“子系统登记表”,作为后续单位代价/外推/波动分析的唯一口径约束。
47
+
48
+ 强制产出:`products/extracted/subsystem_registry.md`(建议使用模板:`templates/subsystem_registry.md.tpl`)。
49
+
50
+ **拆分原则(强制,保持通用性)**:
51
+ - 如果多路输入进入**不同的直接接收单元/不同入口位置**(例如分别进入不同处理单元/不同实验线路),则默认应拆分为不同子系统(每路输入对应一个子系统),分别建立负荷口径与代价口径。
52
+ - “直接接收单元/入口位置”优先以**上游结构 skill**的“输入去向映射表”(Feed → DirectReceivingUnit)与 `products/extracted/entity_map_enriched.json` 的边界输入边(Boundary_Feed_* → Unit)为证据。
53
+ - 只有在能提供明确证据证明“这些输入在上游很快汇合、共享同一套主要资源/主要单元链路、且合并不会导致口径缺路或重复计入”时,才允许合并为单一子系统。
54
+ - 若存在共享计量表/共享设备,必须在登记表中明确分摊或不分摊规则与风险(禁止默认忽略)。
55
+
56
+ `products/extracted/subsystem_registry.md` 至少包含:
57
+ - **子系统列表**:子系统 id/name、输入/负荷 tags、包含的 unit 清单。
58
+ - **负荷定义**:子系统负荷公式(单路/多路求和/模式拆分),以及“为何这样拆分”的判定依据(互斥/并行、系统边界等)。
59
+ - **代价口径定义**:本 workflow 选定的代价资源(含规格/等级),以及子系统内“应计入的消耗方单元清单”。
60
+ - **覆盖完整性检查**:expected vs metered 的差集与处理策略(补测/代理/风险)。
61
+ - **共享项处理**:共享计量表/共享设备/共享测量通道如何分摊(或不分摊并标注风险)。
62
+
63
+ > **规则**:后续 Step 3~Step 6 的所有统计必须以 `products/extracted/subsystem_registry.md` 为准,禁止“临时改变子系统边界”。
64
+
65
+ ### Step 3: 子系统负荷口径(Load Contract)与系统总计规则(强制)
66
+ 基于 `products/extracted/subsystem_registry.md`,固化:
67
+ - 每个子系统的负荷 \(L_s(t)\) 与消耗 \(Q_s(t)\)
68
+ - 系统总计:
69
+ - `L_total = sum(L_s)`(若子系统互斥,需避免重复计入)
70
+ - `Q_total = sum(Q_s)`(共享项按登记表分摊/不分摊规则执行)
71
+
72
+ > 强制写入:在 `products/extracted/consumption_summary.md` 中必须明确写出子系统口径、系统总计规则与任何分摊假设。
73
+
74
+ ### Step 4: 单位代价分布与去极值(Trimming,按子系统分别输出)
75
+ 对每个子系统 \(s\),在稳态数据上输出:
76
+ - SSC 分布(均值/中位数/P10/P20/P80/P90)
77
+ - trim 规则(P1-P99 / P5-P95)与 trim 前后对比
78
+
79
+ ### Step 5: 负荷-单位代价关系(Load vs SSC,按子系统分别输出)
80
+ 对每个子系统 \(s\):
81
+ - 分负荷段(binning)比较 SSC 分布
82
+ - 输出:每个 bin 的样本数、平均负荷、SSC 的 P20/P50/P80
83
+
84
+ ### Step 6: 用历史负荷分布外推长周期负荷分布与消耗基线(按子系统)
85
+ 基于历史稳态负荷分布推测长周期(如全年/全实验周期)的负荷分布与消耗基线,用于管理口径与后续改进空间测算输入。
86
+
87
+ **输入锚点(强制)**:基准期运行小时 `reference_hours`(例如 8000 h/周期)。
88
+
89
+ **方法(推荐)**:对每个子系统 \(s\):
90
+ 1) 统计每个 bin 的历史小时占比 `share_hist_bin`。
91
+ 2) 外推基准期小时:`hours_ref_bin = reference_hours * share_hist_bin`。
92
+ 3) 外推基准期消耗基线:`Q_ref = sum(Q_mean_bin * hours_ref_bin)`。
93
+
94
+ **强制产出**:`products/extracted/load_distribution.csv`(必须包含 `subsystem_id` 字段;至少包含:subsystem_id、bin、hours_hist、share_hist、reference_hours、hours_ref、L_mean、Q_mean、SSC_mean)。
95
+
96
+ > **风险声明(强制)**:若历史数据覆盖不足以代表整个基准期(季节性/维护停机/条件切换/换批期等),必须在 `products/extracted/consumption_summary.md` 写出风险与可能修正方案。
97
+
98
+ ### Part B:波动(Variability)
99
+
100
+ ### Step 7: SSC/Q/L 的波动(系统 + 子系统)
101
+ 在系统总计与每个子系统上输出:
102
+ - SSC、Q、L 的波动强度(CV / IQR / MAD / P90-P10 等)
103
+ - 负荷扰动强度(例如 dL/dt 的分布、扰动方向一致性线索)
104
+
105
+ ### Step 8: 按观测单元逐一做波动诊断(必选结构)
106
+ 本 workflow 要求 **分别对每个关键观测单元(unit)** 做波动诊断,而不是只列 TopN 通道。
107
+
108
+ 写入 `products/extracted/variability_summary.md` 的强制结构(建议一单元一节,且每节至少包含下列字段):
109
+ - **Unit 基本信息**:unit_id、所属子系统(来自 `products/extracted/subsystem_registry.md`)
110
+ - **关键状态指标(PV)**:温度/压力/信号强度/液位等(来自 `workflow02` 语义)
111
+ - **关键控制/干预动作(MV/CO)**:设定值/控制输出/干预记录等
112
+ - **波动强度摘要**:PV/MV 的 CV/稳健指标
113
+ - **波动形态**:趋势/周期/突变/与负荷关系(至少写一种可复核的描述)
114
+ - **对结论的影响假设**:该波动可能如何影响 SSC/Q/产出量/测量偏差(允许假设,但必须可验证)
115
+ - **解释/假设**:扰动来源/控制策略/设备或环境约束(允许多条假设,但必须可验证)
116
+ - **证据与下一步核对**:需要对照的曲线/需要补齐的 tag/需要核对的工况或事件(必须给出下一步动作)
117
+
118
+ > **防错**:对均值接近 0 的变量直接计算 CV 会失真,应使用稳健指标或设置最小均值门槛。
119
+
120
+ ### Step 9: 波动与单位代价的对应分析(必选)
121
+ 必须至少完成一次“单位代价异常段 ↔ 单元波动特征”的对应分析:
122
+ - 在同负荷 bin 内,挑选 SSC 高/低的样本段
123
+ - 对照各 unit 的 PV/MV 波动特征,形成可核对的解释线索(不强制因果,但必须可复核)
124
+
125
+ ### Step 10: 图表与可视化交付(必选)
126
+ 以下图表必须产出(可嵌入 Markdown 或单独成图并在索引中引用):
127
+ - 子系统级:负荷-单位代价散点(含 trim 前后对比)、负荷分段箱线图/分位数图、历史负荷分布 + 长周期外推
128
+ - 单元级:每个子系统 TopN 高波动 unit 的 PV/MV 时序或分布图
129
+
130
+ 强制产出:`products/extracted/workflow06_figures.md`(图表索引:图表清单 + 口径 + 文件路径;PNG 落 `lab/diagrams/`)。
131
+
132
+ ### Step 11: 形成“解释性结论”(不写方法,只写原因)
133
+ 将发现落成结论句式(示例):
134
+ - “单位代价改善/变差是否主要由负荷变化驱动?”
135
+ - “同负荷差异是否与某子系统/某单元的波动相关?”
136
+ - “哪些单元/回路是系统波动的主要贡献者?对应的可验证假设是什么?”
137
+
138
+ ## 产出物
139
+ - `products/extracted/subsystem_registry.md`:子系统登记(边界、负荷口径、代价资源规格、覆盖检查与分摊规则)
140
+ - `products/extracted/consumption_summary.md`:代价与单位代价摘要(按子系统 + 系统总计;含外推假设与风险)
141
+ - `products/extracted/load_distribution.csv`:历史负荷分布与长周期外推(按子系统)
142
+ - `products/extracted/variability_summary.md`:波动指标与诊断(系统 + 子系统 + 按 unit 逐一诊断)
143
+ - `products/extracted/workflow06_figures.md`:图表索引(必选图表清单 + 口径 + 文件路径/嵌入位置)
144
+
145
+ ## 闸门(确认后进入下一 Workflow)
146
+ 在进入 `workflows/05-best-in-class-and-optimization-space.md` 前,必须确认本 workflow 产出无误,并在 `products/extracted/consumption_summary.md` 末尾追加“确认记录”(日期/确认人/结论/疑点与后续动作)。最少确认:
147
+ - **强制产出物是否齐全**:`products/extracted/subsystem_registry.md`、`products/extracted/consumption_summary.md`、`products/extracted/load_distribution.csv`、`products/extracted/variability_summary.md`、`products/extracted/workflow06_figures.md` 是否都已生成且内容完整。
148
+ - Step 1 的“资源规格 + 消耗方覆盖完整性检查”已完成,且覆盖检查结论写入 `products/extracted/subsystem_registry.md`(无遗漏或已明确缺口与风险)。
149
+ - 子系统边界、负荷口径、共享项分摊规则已固化(`products/extracted/subsystem_registry.md`),且与 `products/extracted/consumption_summary.md` 一致。
150
+ - 基准期运行小时(reference_hours)与外推口径已显式声明,且 `products/extracted/load_distribution.csv` 可复现。
151
+ - 波动分析已覆盖:SSC/Q/L(系统+子系统)+ 系统状态 PV + 控制/干预动作 MV/CO,并且 `products/extracted/variability_summary.md` 含“按 unit 逐一诊断”的必选结构。
152
+ - 必选图表已产出,且 `products/extracted/workflow06_figures.md` 可追溯口径与文件落点。