clearai-dsh 0.1.0

package/presets/clearai/template/skills/process-understanding-extraction/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: process-understanding-extraction
+description: |
+  【流程理解·证据抽取】流程叙述定位、边界单元、单元级拓扑骨架（可审计摘录）。适用：对任意流程/系统资料（实验方案、方法论文、业务流程文档、操作规程）的理解与制图。不适用：领域/行业背景预研（用 domain-presearch）；下游数据 QA（用 data-qa-analysis）。
+version: 1.0
+metadata:
+  tier: system
+  origin: template
+  created_at: '2026-06-12T02:47:05.409743+00:00'
+---
+
+# 流程理解与提取 Skill (SOP)
+
+> 本 Skill 是“流程型系统分析”的上游理解部分：先把系统讲清楚（流程叙述、边界、单元与能量/资源接口、流程图/拓扑），再允许进入任何数据对齐与数据分析。
+
+## 落盘约定
+
+- **最终交付**：`products/extracted/`（process_brief、unit_inventory、process_flow、entity_map 等）
+- **过程转储**：`lab/`（raw dump、OCR 中间文本、一次性脚本）
+- 文中若出现 `extracted/` 逻辑别名，**write 必须使用** `products/extracted/` 完整路径
+
+## 1. 核心方法论 (Core Method)
+
+- **Evidence-First（证据优先）**：流程必须来自权威资料的“流程叙述”原文；找不到就明确声明未找到，禁止补写流程。
+- **Auditable Extraction（可审计抽取）**：`products/extracted/process_brief.md` 的“原文摘录”必须由代码从 raw dump/OCR 文本生成，避免模型逐字代写。
+- **Boundary-First（边界优先）**：边界口径先行；净输入/净输出/回流（循环）/旁路规则必须写清楚。
+- **Topology Skeleton（拓扑骨架）**：节点以“单元/装置”为主，边为“物料/对象流动 + 能量或资源注入/移除”；不写具体测点/字段名，测点映射后置到数据 skill。
+
+## 2. 决策树 (Decision Tree)
+
+根据用户意图选择工作流：
+1. **“我需要找到流程介绍/定义系统边界”** -> `workflows/01-process-doc-discovery.md`
+2. **“我要画流程图/把物流能流讲清楚”** -> `workflows/02-process-understanding-and-diagramming.md`
+3. **“全面体检（流程部分）”** -> 按顺序执行 01 -> 02。
+
+## 3. 核心指令 (Core Instructions)
+
+<instruction>
+<role>
+你是流程型系统的理解与证据抽取专家。你对“流程叙述主证据”与“补充证据（控制逻辑/启停程序）”严格区分；对边界口径、回流/旁路、能量与资源接口非常敏感；对“按编号推断流向”的错误高度警惕。
+</role>
+
+<rule>
+1. **必须先输出统一 plan 并确认（强制）**：执行本次任务涉及的**第一个 workflow**之前，必须先输出一份覆盖本 skill 全部 workflows（01-02）的统一 plan 供用户确认（确认后再执行）。
+   - plan 必须逐 workflow 列出强制产出物清单（逐项列文件名/路径），并声明 `lab/`（过程） vs `products/`（最终）分区与落点。
+   - plan 必须包含“产出物对照表”，逐条对照 workflows 文件中的 `## 产出物` 清单逐行复制，禁止概括/省略/合并。
+2. **资料优先级粘性（强制）**：一旦已找到操作规程/实验方案/流程图等高优先级文件，必须优先尽可能读取与抽取（paragraph+table、转纯文本、OCR），不得因抽取困难而自动下沉用低优先级资料替代流程叙述主证据。
+3. **流程叙述主证据硬规则（强制）**：未定位到“流程叙述/流程概述/方法描述/Process Description”等段落前，禁止基于猜测补写流程；找不到必须明确写“未找到”，并列出尝试路径。
+4. **process_brief 原文摘录必须由代码生成（强制）**：禁止模型在对话/笔记中逐字输出原文再手工粘贴；必须先产出 raw dump，再用范围抽取脚本生成 `products/extracted/process_brief.md`。
+5. **Workflow 闸门（强制）**：每个 workflow 的产出物必须经确认无误并记录确认记录后，才允许进入下一 workflow。
+6. **拓扑只做骨架（强制）**：`products/extracted/entity_map.json` 仅包含单元/公用支撑系统/边界的 nodes 与 material/energy edges，并带 evidence；禁止写入任何具体测点/字段名（流量计、传感器编号、数据列名等）。
+7. **流程参数须标注来源**：对话或报告中引用流程参数数值（温度、压力、流量、浓度等）时，须标注 `来源: products/extracted/process_brief.md 原文摘录` 或「推断」。
+</rule>
+</instruction>
+
+## 4. 资源索引 (Resource Index)
+
+- **Workflows**:
+  - `workflows/01-process-doc-discovery.md`
+  - `workflows/02-process-understanding-and-diagramming.md`
+- **Templates**:
+  - `templates/unified_execution_plan.md.tpl`（统一 plan 模板：仅覆盖 workflow01-02）
+  - `templates/process_brief.md.tpl`（Workflow 01 强制输出骨架）
+  - `templates/docx_raw_dump_extractor.py.tpl`（Workflow 01 代码抽取 raw dump）
+  - `templates/process_brief_builder_from_raw_dump.py.tpl`（Workflow 01 用代码生成 process_brief）
+  - `templates/process_flow_mermaid.md.tpl`（Workflow 02 Mermaid 图模板）
+  - `templates/entity_map_unit_topology.json.tpl`（Workflow 02 单元级拓扑骨架）
+- **Checklists**:
+  - `checklists/readiness_check.md`

package/presets/clearai/template/skills/process-understanding-extraction/checklists/readiness_check.md

@@ -0,0 +1,34 @@
+# 流程提取交付自检清单（Readiness Checklist：Workflow01-02）
+
+> 在宣布“流程提取完成（可进入数据对齐/分析）”前，必须通过以下所有检查。
+
+## 0. 执行计划与交付分区 (Plan & Delivery)
+- [ ] 已在执行第一个 workflow 前输出“覆盖本次所有 workflows（仅限本 skill）的统一 plan”并获得用户确认（确认后再执行）。
+- [ ] plan 已逐 workflow 列出 01-02，且每一步明确标注强制产出物清单（含文件路径）。
+- [ ] plan 已显式声明产物分区：过程文件/中间产物输出至 `lab/`，最终交付输出至 `products/`，且每一步标明输出落点。
+- [ ] plan 包含“产出物对照表”，并已逐条对照所选 workflows 的 `## 产出物` 清单逐行复制（无漏项、无概括省略）。
+- [ ] 最终交付物（workflows 声明的 `products/extracted/*`）已按 plan 约定落在 `products/`（推荐 `products/extracted/*`），过程转储/临时产物不混入最终交付目录。
+
+## 1. 流程资料与证据链 (Process Evidence)
+- [ ] 已遵守“资料优先级粘性”：找到操作规程/实验方案/流程图等高优先级资料后，已尽可能完成鲁棒抽取（paragraph+table、转纯文本、OCR 等），未在高优先级尚可读取时直接降级用低优先级资料替代流程叙述。
+- [ ] `products/extracted/process_brief.md` 的流程叙述段落通过“段落选型闸门”：标题类型匹配、包含流向要素、覆盖性满足；若未找到流程叙述，已明确写出“未找到”并列出已尝试路径（而不是补写流程）。
+- [ ] `products/extracted/process_brief.md` 的“原文摘录”由代码从 raw dump（或 OCR 文本）生成，且填写了 `raw dump 路径 + 定位范围`（可审计、可复查）。
+- [ ] `products/extracted/process_brief.md` 的“补充证据/控制逻辑摘要（可选）”如有填写：已标注来源与性质（补充证据，非流程叙述），且未用其替代流程叙述主证据。
+
+## 2. 单元清单与边界契约 (Inventory & Boundary)
+- [ ] `products/extracted/unit_inventory.md` 已覆盖关键单元（尤其核心装置）的输入/输出与能量/资源接口（蒸汽/冷却水/电/燃气/真空等），并能从单元视角复原流向/能流走向（不要求测点/字段名）。
+- [ ] 存在性三态输出正确：State_A/State_B/State_C 定义清晰，State_B 有证据链（来源/位置/置信度/why_not_high）。
+- [ ] 对 State_C（未确认存在）条目未写成“无计量点/unmetered_stream”（计量点匹配后置到后续数据对齐）。
+- [ ] `products/extracted/segment_boundary.md` 的净输入/净输出/回流/旁路规则与流程叙述一致；无证据时均标注“待确认/待匹配”，不存在强断言测点编号或凭空设备数量。
+
+## 3. 流程图与拓扑骨架 (Diagram & Topology Skeleton)
+- [ ] `products/extracted/process_flow.md` 开头包含“输入去向映射表”，且每股输入的“直接接收单元”都有逐字原文依据（不得按编号顺序推测）。
+- [ ] Mermaid 流程图至少包含：主流程图（净输入/净输出/回流区分清楚）与能量/资源视角图（主要支撑介质表达完整）。
+- [ ] 若存在推断连接：已在图中用 `【推断】` 文本标注，并在文档中给出“推断清单”（理由/依据来源/置信度/验证动作）。
+- [ ] `products/extracted/entity_map.json` 的节点=单元/公用支撑系统/边界；边=流股/能量；每条 edge 有 evidence；不包含任何具体测点/字段名（测点补齐后置）。
+
+---
+
+**自检结论**:
+- [ ] 通过 (Ready to Handover)
+- [ ] 需返工 (Needs Rework)

package/presets/clearai/template/skills/process-understanding-extraction/templates/docx_raw_dump_extractor.py.tpl

@@ -0,0 +1,132 @@
+"""
+DOCX Raw Dump Extractor (Template)
+
+目的：
+- 用“代码”把复杂 DOCX 的段落 + 表格单元格按文档顺序转储为可检索的纯文本/Markdown（raw dump）
+- 为 workflow01 的 `products/extracted/process_brief.md` 提供“逐字粘贴”的来源，避免大模型凭空生成
+
+依赖：
+  pip install python-docx
+
+用法（示例）：
+  python docx_raw_dump_extractor.py \
+    --input "/path/to/file.docx" \
+    --output "lab/raw_dumps/file.raw_dump.md"
+
+说明：
+- 输出文件会保留 block 顺序（paragraph/table），并标注 style 与索引
+- 你可以在输出里搜索“流程叙述/流程概述/Process Description”等关键词，再逐字复制目标段落到 `products/extracted/process_brief.md`
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from typing import Iterator, List, Union
+
+from docx import Document
+from docx.oxml.table import CT_Tbl
+from docx.oxml.text.paragraph import CT_P
+from docx.table import Table
+from docx.text.paragraph import Paragraph
+
+Block = Union[Paragraph, Table]
+
+
+def iter_block_items(doc: Document) -> Iterator[Block]:
+    """
+    Iterate over document blocks (paragraphs and tables) in order.
+    Ref: python-docx does not provide a built-in ordered iterator.
+    """
+    body = doc.element.body
+    for child in body.iterchildren():
+        if isinstance(child, CT_P):
+            yield Paragraph(child, doc)
+        elif isinstance(child, CT_Tbl):
+            yield Table(child, doc)
+
+
+def table_to_markdown(table: Table, max_cell_chars: int = 500) -> str:
+    rows: List[List[str]] = []
+    for r in table.rows:
+        row: List[str] = []
+        for c in r.cells:
+            txt = "\n".join(p.text.strip() for p in c.paragraphs if p.text and p.text.strip())
+            txt = txt.replace("|", "\\|")
+            if len(txt) > max_cell_chars:
+                txt = txt[: max_cell_chars - 3] + "..."
+            row.append(txt)
+        rows.append(row)
+
+    if not rows:
+        return ""
+
+    col_count = max(len(r) for r in rows)
+    for r in rows:
+        if len(r) < col_count:
+            r.extend([""] * (col_count - len(r)))
+
+    header = rows[0]
+    sep = ["---"] * col_count
+    body = rows[1:] if len(rows) > 1 else []
+
+    def fmt_row(r: List[str]) -> str:
+        return "| " + " | ".join(r) + " |"
+
+    lines = [fmt_row(header), fmt_row(sep)]
+    lines.extend(fmt_row(r) for r in body)
+    return "\n".join(lines)
+
+
+def dump_docx(input_path: str) -> str:
+    doc = Document(input_path)
+    out: List[str] = []
+    out.append("# DOCX Raw Dump\n")
+    out.append(f"- source: `{input_path}`")
+    out.append("")
+
+    p_idx = 0
+    t_idx = 0
+    for b in iter_block_items(doc):
+        if isinstance(b, Paragraph):
+            text = (b.text or "").rstrip()
+            if not text.strip():
+                continue
+            p_idx += 1
+            style = getattr(getattr(b, "style", None), "name", "") or "UnknownStyle"
+            out.append(f"## [P{p_idx:05d}] style={style}")
+            out.append(text)
+            out.append("")
+        else:
+            t_idx += 1
+            out.append(f"## [T{t_idx:05d}] table")
+            md = table_to_markdown(b)
+            if md.strip():
+                out.append(md)
+            else:
+                out.append("_<empty table>_")
+            out.append("")
+
+    return "\n".join(out).strip() + "\n"
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--input", required=True, help="Input .docx path")
+    ap.add_argument("--output", required=True, help="Output .md path")
+    args = ap.parse_args()
+
+    input_path = os.path.abspath(args.input)
+    output_path = os.path.abspath(args.output)
+    os.makedirs(os.path.dirname(output_path), exist_ok=True)
+
+    content = dump_docx(input_path)
+    with open(output_path, "w", encoding="utf-8") as f:
+        f.write(content)
+
+    print(f"OK: wrote raw dump to {output_path}")
+
+
+if __name__ == "__main__":
+    main()
+

package/presets/clearai/template/skills/process-understanding-extraction/templates/entity_map_unit_topology.json.tpl

@@ -0,0 +1,86 @@
+{
+  "schema_version": "1.0",
+  "description": "Unit-level topology for process-style systems. Nodes are units/utilities/boundaries; edges are material/energy. No measurement tag or field names in this file; tags are added in the data skill workflow02 enrichment. Each edge should carry an evidence object that points to products/extracted/process_brief.md or products/extracted/unit_inventory.md; inferred edges must be explicitly marked.",
+  "nodes": [
+    {
+      "id": "Unit_S201",
+      "type": "unit",
+      "label": "S201",
+      "notes": "Separation unit (example)"
+    },
+    {
+      "id": "SteamHeader_HP",
+      "type": "utility",
+      "label": "SteamHeader_HP",
+      "notes": "High-pressure steam header (example utility)"
+    },
+    {
+      "id": "Boundary_Feed",
+      "type": "boundary",
+      "label": "Feed",
+      "notes": "Net input boundary"
+    },
+    {
+      "id": "Boundary_Product",
+      "type": "boundary",
+      "label": "Product",
+      "notes": "Net output boundary"
+    }
+  ],
+  "edges": [
+    {
+      "id": "Edge_Feed_to_S201",
+      "kind": "material",
+      "from": "Boundary_Feed",
+      "to": "Unit_S201",
+      "stream_name": "Feed",
+      "direction": "in",
+      "measurement_slots": [
+        "flow"
+      ],
+      "evidence": {
+        "type": "process_brief_quote",
+        "source": "products/extracted/process_brief.md",
+        "location": "§2 原文摘录, 第x段",
+        "excerpt": "在此粘贴支持该连接的逐字引用（或说明来自 products/extracted/unit_inventory.md）"
+      },
+      "notes": "Data skill workflow02 should enrich this edge with flow_tag and unit."
+    },
+    {
+      "id": "Edge_S201_to_Product",
+      "kind": "material",
+      "from": "Unit_S201",
+      "to": "Boundary_Product",
+      "stream_name": "Product",
+      "direction": "out",
+      "measurement_slots": [
+        "flow"
+      ],
+      "evidence": {
+        "type": "process_brief_quote",
+        "source": "products/extracted/process_brief.md",
+        "location": "§2 原文摘录, 第x段",
+        "excerpt": "在此粘贴支持该连接的逐字引用（或说明来自 products/extracted/unit_inventory.md）"
+      },
+      "notes": "Avoid treating reflux/internal recycle as net product."
+    },
+    {
+      "id": "Edge_HPSteam_to_S201",
+      "kind": "energy",
+      "from": "SteamHeader_HP",
+      "to": "Unit_S201",
+      "energy_medium": "steam",
+      "direction": "in",
+      "measurement_slots": [
+        "steam_flow"
+      ],
+      "evidence": {
+        "type": "process_brief_quote",
+        "source": "products/extracted/process_brief.md",
+        "location": "§2 原文摘录, 第x段",
+        "excerpt": "在此粘贴支持该连接的逐字引用；若为推断，type 写 inferred 并说明验证方法"
+      },
+      "notes": "Data skill workflow02 should enrich with steam_flow_tag, pressure_level, unit."
+    }
+  ]
+}

package/presets/clearai/template/skills/process-understanding-extraction/templates/process_brief.md.tpl

@@ -0,0 +1,89 @@
+# 流程简介 (Process Brief)
+
+**对象系统**: ${SYSTEM_NAME}
+**分析日期**: ${DATE}
+**负责人**: ${OWNER}
+
+---
+
+## 1. 定位信息
+
+- **目标文件**：${SOURCE_FILE_PATH}
+- **目标章节**：${TARGET_SECTION}（例如：5.2.2 流程叙述）
+- **代码抽取产物（raw dump）路径**：${RAW_DUMP_PATH}（建议：`lab/raw_dumps/<doc>.raw_dump.md`）
+- **raw dump 定位范围**：${RAW_DUMP_RANGE}（例如：P00123-P00168 或 “Heading 5.2.2 前后各 2 级标题范围”）
+- **抽取方式**：${EXTRACTION_METHOD}（code_raw_dump / paragraph+table / pandoc / docx2txt / mammoth / OCR）
+- **定位证据**：${LOCATION_EVIDENCE}（标题路径 / 页码 / 表格位置 / 截图说明）
+
+> 段落选型闸门是否通过？
+> - [ ] 标题类型匹配（指向"流程叙述/流程说明/方法描述"一类，不是"启动/停止/参数调整/联锁/报警"等排除项）
+> - [ ] 内容包含流向要素（至少 1 个净输入 + 至少 1 个净输出/去向 + 能读出"从 A 到 B"的流向）
+> - [ ] 覆盖性满足（若系统含多个关键单元，原文能覆盖其主流向关系）
+
+---
+
+## 2. 原文摘录（逐字粘贴，必须）
+
+> **硬规则**：本区域必须由**代码**从“raw dump / OCR 转文本”自动生成填充，不允许大模型在对话中逐字输出原文后再手工粘贴（避免错贴/漏贴/不可审计）。
+> 若原文过长，可分段粘贴并标注每段的标题路径/页码。
+> 若原文中有表格，请以表格形式复现。
+
+```
+<在此处逐字粘贴原文>
+```
+
+---
+
+## 3. AI 摘要（可选）
+
+> **硬规则**：本区域只能在"原文摘录"完成后才允许填写。必须明确标注为"摘要"，禁止与原文混排。
+> 若不需要摘要，删除本区域或留空即可。
+
+${AI_SUMMARY_IF_NEEDED}
+
+---
+
+## 4. 疑点清单
+
+> 若原文存在歧义、抽取不完整、或你无法确认某些信息，必须在此列出。
+> 禁止在后续 `products/extracted/unit_inventory.md` / `products/extracted/segment_boundary.md` 中用强断言填空（改用"待确认"）。
+
+| 序号 | 疑点/缺口 | 影响范围 | 建议下一步 |
+|------|-----------|----------|-----------|
+| 1 | ${GAP_1} | ${IMPACT_1} | ${NEXT_STEP_1} |
+
+---
+
+## 5. 补充证据 / 控制逻辑摘要（可选，但推荐）
+
+> 允许收录"启动/停止/参数调整/控制逻辑/动态平衡机理"等段落作为补充证据。
+> 必须标注：章节来源（标题路径/页码）、性质（补充证据，非流程叙述）。
+> 不得据此在 `products/extracted/segment_boundary.md` 中写出无证据的测点编号/设备数量等强断言。
+
+### 5.1 补充段落 1
+
+- **来源**：${SUPPLEMENT_SOURCE_1}（标题路径/页码）
+- **性质**：补充证据（非流程叙述）
+- **原文摘录或摘要**：
+
+```
+<在此处粘贴补充段落原文或写摘要（需标明哪种）>
+```
+
+- **对分析的价值**：${VALUE_1}（例如：控制逻辑理解 / 真空建立顺序 / 回流策略 / 稳态判据参考）
+
+---
+
+## 6. 确认记录（闸门，进入下一 Workflow 前必填）
+
+- **确认日期**：${CONFIRM_DATE}
+- **确认人**：${CONFIRMER}
+- **强制产出物是否齐全**：
+  - [ ] `products/extracted/process_brief.md`（本文件）
+  - [ ] `products/extracted/unit_inventory.md`
+  - [ ] `products/extracted/segment_boundary.md`
+- **段落选型闸门是否通过**：[ ] 是 / [ ] 否（若否，必须继续回到 Step 2 搜索）
+- **"原文摘录"区域是否为逐字粘贴**：[ ] 是 / [ ] 否（若否，必须回退重做原文摘录）
+- **是否存在无证据强断言**：[ ] 否 / [ ] 是（若是，列出问题并回退或标为"待确认"）
+- **结论**：${CONCLUSION}
+- **疑点与后续动作**：${REMAINING_ISSUES}

package/presets/clearai/template/skills/process-understanding-extraction/templates/process_brief_builder_from_raw_dump.py.tpl

@@ -0,0 +1,203 @@
+"""
+Process Brief Builder (Template)
+
+目标：
+- 从 docx raw dump（由 `lab/scripts/docx_raw_dump_extractor.py` 生成）中按 range 抽取原文块
+- 自动生成 `products/extracted/process_brief.md`，把“原文摘录”区域由代码填充
+- 从机制上避免大模型在对话中“逐字输出原文”
+
+依赖：
+  Python 3.x (标准库即可)
+
+用法（示例）：
+  python process_brief_builder_from_raw_dump.py \
+    --raw-dump "lab/raw_dumps/sop.raw_dump.md" \
+    --range "P00376-P00420" \
+    --source-file "input/xxx.docx" \
+    --target-section "5.2.2 流程叙述（第24页）" \
+    --output "products/extracted/process_brief.md"
+
+说明：
+- raw dump block 的标题格式来自 `docx_raw_dump_extractor.py`：`## [P00001] style=...` 或 `## [T00001] table`
+- range 支持：
+  - P 起止：P00376-P00420
+  - T 起止：T00012-T00019
+  - 单点：P00376
+  - 混合范围暂不支持（需要时可拆两次追加或扩大范围）
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+
+BLOCK_RE = re.compile(r"^## \[(?P<kind>[PT])(?P<idx>\d{5})\].*$")
+
+
+@dataclass
+class Block:
+    kind: str  # 'P' or 'T'
+    idx: int
+    header_line: str
+    lines: List[str]
+
+
+def parse_raw_dump(md_text: str) -> List[Block]:
+    lines = md_text.splitlines()
+    blocks: List[Block] = []
+    cur: Optional[Block] = None
+
+    for line in lines:
+        m = BLOCK_RE.match(line.strip())
+        if m:
+            if cur is not None:
+                blocks.append(cur)
+            cur = Block(
+                kind=m.group("kind"),
+                idx=int(m.group("idx")),
+                header_line=line,
+                lines=[],
+            )
+            continue
+        if cur is not None:
+            cur.lines.append(line)
+
+    if cur is not None:
+        blocks.append(cur)
+    return blocks
+
+
+def parse_range(rng: str) -> Tuple[str, int, int]:
+    s = rng.strip()
+    if "-" in s:
+        a, b = s.split("-", 1)
+        kind_a, idx_a = a[0].upper(), int(a[1:])
+        kind_b, idx_b = b[0].upper(), int(b[1:])
+        if kind_a != kind_b:
+            raise ValueError("Mixed kind range is not supported. Use Pxxxxx-Pyyyyy or Txxxxx-Tyyyyy.")
+        if idx_b < idx_a:
+            raise ValueError("Range end must be >= start.")
+        return kind_a, idx_a, idx_b
+    kind, idx = s[0].upper(), int(s[1:])
+    return kind, idx, idx
+
+
+def extract_blocks(blocks: List[Block], kind: str, start: int, end: int) -> List[Block]:
+    selected = [b for b in blocks if b.kind == kind and start <= b.idx <= end]
+    if not selected:
+        raise ValueError(f"No blocks matched range {kind}{start:05d}-{kind}{end:05d}.")
+    return selected
+
+
+def build_process_brief(
+    *,
+    source_file: str,
+    target_section: str,
+    raw_dump_path: str,
+    raw_dump_range: str,
+    extraction_method: str,
+    excerpt_blocks: List[Block],
+) -> str:
+    excerpt_lines: List[str] = []
+    for b in excerpt_blocks:
+        excerpt_lines.append(b.header_line)
+        excerpt_lines.extend(b.lines)
+        excerpt_lines.append("")
+
+    excerpt_text = "\n".join(excerpt_lines).strip()
+
+    return f"""# 流程简介 (Process Brief)
+
+<!-- GENERATED_BY: process_brief_builder_from_raw_dump.py -->
+
+## 1. 定位信息
+
+- **目标文件**：{source_file}
+- **目标章节**：{target_section}
+- **代码抽取产物（raw dump）路径**：{raw_dump_path}
+- **raw dump 定位范围**：{raw_dump_range}
+- **抽取方式**：{extraction_method}
+- **定位证据**：见 raw dump block 标题（P/T 编号 + style/table）
+
+---
+
+## 2. 原文摘录（由代码填充，禁止手工改写）
+
+> **硬规则**：本区域为“代码从 raw dump 抽取的逐字原文”。禁止大模型在对话中逐字输出原文、禁止人工改写替换。
+
+```text
+{excerpt_text}
+```
+
+---
+
+## 3. AI 摘要（可选）
+
+（可选，需明确标注为摘要；禁止与原文混排）
+
+---
+
+## 4. 疑点清单
+
+| 序号 | 疑点/缺口 | 影响范围 | 建议下一步 |
+|------|-----------|----------|-----------|
+| 1 |  |  |  |
+
+---
+
+## 5. 补充证据 / 控制逻辑摘要（可选）
+
+（允许，但必须标注来源与性质：补充证据，非流程叙述）
+
+---
+
+## 6. 确认记录（闸门）
+
+- **确认日期**：
+- **确认人**：
+- **"原文摘录"是否由代码生成**：[ ] 是 / [ ] 否（若否，不合格，必须回退用代码生成）
+"""
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--raw-dump", required=True, help="Path to raw dump markdown")
+    ap.add_argument("--range", required=True, help="Block range, e.g. P00376-P00420")
+    ap.add_argument("--source-file", required=True, help="Original doc path")
+    ap.add_argument("--target-section", required=True, help="Target section name/page")
+    ap.add_argument("--output", required=True, help="Output process_brief.md path")
+    ap.add_argument("--extraction-method", default="code_raw_dump", help="Extraction method label")
+    args = ap.parse_args()
+
+    raw_dump_path = os.path.abspath(args.raw_dump)
+    with open(raw_dump_path, "r", encoding="utf-8") as f:
+        md_text = f.read()
+
+    blocks = parse_raw_dump(md_text)
+    kind, start, end = parse_range(args.range)
+    excerpt_blocks = extract_blocks(blocks, kind, start, end)
+
+    content = build_process_brief(
+        source_file=args.source_file,
+        target_section=args.target_section,
+        raw_dump_path=args.raw_dump,
+        raw_dump_range=args.range,
+        extraction_method=args.extraction_method,
+        excerpt_blocks=excerpt_blocks,
+    )
+
+    out_path = os.path.abspath(args.output)
+    os.makedirs(os.path.dirname(out_path), exist_ok=True)
+    with open(out_path, "w", encoding="utf-8") as f:
+        f.write(content)
+
+    print(f"OK: wrote {out_path}")
+
+
+if __name__ == "__main__":
+    main()
+

package/presets/clearai/template/skills/process-understanding-extraction/templates/process_flow_mermaid.md.tpl

@@ -0,0 +1,41 @@
+# 流程图模板（Mermaid）
+
+## 模板说明
+建议输出两张图：
+1. 主流程（只画对象/物料流）
+2. 能量/资源视角（补充蒸汽/冷却水/电等支撑介质）
+
+---
+
+# 1) 主流程（对象/物料流）
+
+```mermaid
+flowchart LR
+  Feed["Feed"] --> UnitA["UnitA"]
+  UnitA --> UnitB["UnitB"]
+  UnitB --> Product["Product"]
+  UnitB --> Recycle["Recycle"]
+  Recycle --> UnitA
+```
+
+## 关键流股说明
+- Feed：${FEED_DESC}（代表测点/字段：${FEED_TAG}）
+- Product：${PRODUCT_DESC}（代表测点/字段：${PRODUCT_TAG}）
+- Recycle：${RECYCLE_DESC}（是否计入净输出：${RECYCLE_POLICY}）
+
+---
+
+# 2) 能量/资源视角（公用支撑系统）
+
+```mermaid
+flowchart LR
+  Steam["Steam"] --> Heater["Heater"]
+  Heater --> UnitB["UnitB"]
+  UnitB --> Condenser["Condenser"]
+  Condenser --> CW["CoolingWater"]
+  Vacuum["VacuumSystem"] --> UnitB
+```
+
+## 能量口径说明
+- 蒸汽计量点：${STEAM_TAGS}（单位：${STEAM_UNIT}）
+- 电耗计量点：${POWER_TAGS}（单位：kW）