AiDOPWarehouse/doc/_gen_agent_plan_reading_docx.py

"""生成《Ai-DOP 本体驱动智能体建设方案：理解与解读》Word 文档（V1.0）。

基于用户提供的《Ai-DOP 本体驱动智能体建设方案》(7)(1) 撰写：逐章解读方案逻辑主线、
关键概念地图、核心设计逐点分析、就绪度判定与分阶段计划的理解、总体评价与注意点，
供评审团队快速建立对方案的一致认知。
"""

from __future__ import annotations

import os

from docx import Document
from docx.enum.text import WD_ALIGN_PARAGRAPH, WD_LINE_SPACING
from docx.oxml.ns import qn
from docx.shared import Cm, Pt

BASE = os.path.dirname(os.path.abspath(__file__))
OUT = os.path.join(BASE, "plan", "Ai-DOP本体驱动智能体建设方案_理解与解读.docx")

doc = Document()
sec = doc.sections[0]
sec.page_width = Cm(21.0)
sec.page_height = Cm(29.7)
sec.top_margin = Cm(2.54)
sec.bottom_margin = Cm(2.54)
sec.left_margin = Cm(2.4)
sec.right_margin = Cm(2.4)


def set_run_font(run, name_cn="宋体", name_en="Times New Roman", size=12, bold=False, color=None):
    run.font.name = name_en
    run._element.rPr.rFonts.set(qn("w:eastAsia"), name_cn)
    run.font.size = Pt(size)
    run.bold = bold
    if color is not None:
        run.font.color.rgb = color


def style_normal():
    style = doc.styles["Normal"]
    style.font.name = "Times New Roman"
    style.font.size = Pt(12)
    style._element.rPr.rFonts.set(qn("w:eastAsia"), "宋体")
    pf = style.paragraph_format
    pf.line_spacing_rule = WD_LINE_SPACING.ONE_POINT_FIVE
    pf.space_after = Pt(6)


def add_title(text: str):
    p = doc.add_paragraph()
    p.alignment = WD_ALIGN_PARAGRAPH.CENTER
    p.paragraph_format.space_after = Pt(12)
    run = p.add_run(text)
    set_run_font(run, "黑体", "SimHei", 18, True)


def add_subtitle(text: str):
    p = doc.add_paragraph()
    p.alignment = WD_ALIGN_PARAGRAPH.CENTER
    p.paragraph_format.space_after = Pt(12)
    run = p.add_run(text)
    set_run_font(run, "黑体", "SimHei", 14, True)


def add_meta(text: str):
    p = doc.add_paragraph()
    p.alignment = WD_ALIGN_PARAGRAPH.CENTER
    p.paragraph_format.space_after = Pt(4)
    run = p.add_run(text)
    set_run_font(run, "宋体", "Times New Roman", 10.5)


def add_h1(text: str):
    p = doc.add_paragraph()
    p.paragraph_format.space_before = Pt(14)
    p.paragraph_format.space_after = Pt(8)
    run = p.add_run(text)
    set_run_font(run, "黑体", "SimHei", 14, True)


def add_h2(text: str):
    p = doc.add_paragraph()
    p.paragraph_format.space_before = Pt(10)
    p.paragraph_format.space_after = Pt(6)
    run = p.add_run(text)
    set_run_font(run, "黑体", "SimHei", 12, True)


def add_body(text: str, indent=True):
    p = doc.add_paragraph()
    p.paragraph_format.first_line_indent = Pt(24) if indent else Pt(0)
    p.paragraph_format.space_after = Pt(6)
    run = p.add_run(text)
    set_run_font(run, "宋体", "Times New Roman", 12)


def add_bullet(text: str, ordered=False, index=None):
    p = doc.add_paragraph()
    p.paragraph_format.left_indent = Cm(0.74)
    p.paragraph_format.first_line_indent = Pt(0)
    p.paragraph_format.space_after = Pt(3)
    prefix = f"{index}." if ordered else "•"
    run = p.add_run(f"{prefix} {text}")
    set_run_font(run, "宋体", "Times New Roman", 12)


def add_table(headers, rows, col_widths=None):
    table = doc.add_table(rows=1 + len(rows), cols=len(headers))
    table.style = "Table Grid"
    table.autofit = True

    for i, h in enumerate(headers):
        cell = table.rows[0].cells[i]
        cell.text = ""
        p = cell.paragraphs[0]
        p.alignment = WD_ALIGN_PARAGRAPH.CENTER
        run = p.add_run(h)
        set_run_font(run, "宋体", "Times New Roman", 10.5, True)
        tc = cell._tc
        tcPr = tc.get_or_add_tcPr()
        shd = tcPr.makeelement(qn("w:shd"), {qn("w:val"): "clear", qn("w:fill"): "D9E2F3"})
        tcPr.append(shd)

    for ri, row in enumerate(rows):
        for ci, val in enumerate(row):
            cell = table.rows[ri + 1].cells[ci]
            cell.text = ""
            p = cell.paragraphs[0]
            run = p.add_run(str(val))
            set_run_font(run, "宋体", "Times New Roman", 10.5)

    if col_widths is not None:
        table.autofit = False
        for ci, w in enumerate(col_widths):
            for row in table.rows:
                row.cells[ci].width = Cm(w)
    return table


style_normal()

# ============ 封面信息 ============
add_title("《Ai-DOP 本体驱动智能体建设方案》理解与解读")
add_subtitle("——对方案 (7)(1) 版文档的阅后理解、逻辑主线与注意点")
add_meta("文档版本：V1.0　　编制日期：2026 年 10 月")
add_meta("解读对象：《Ai-DOP 本体驱动智能体建设方案》(7)(1)（十章，26 表 2 图）")
add_meta("配套文档：《Ai-DOP 智能体建设任务计划》V1.0（本方案第七章的执行分解）")

# ============ 一、文档定位 ============
add_h1("一、文档定位与核心主张")
add_h2("1.1 一句话理解")
add_body(
    "这份方案回答一个问题：如何在不新建旁路系统、不重构现有业务的前提下，让 Ai-DOP 从「人看数据、人做判断」"
    "进化到「系统自动感知、自动推理、自动给出可执行建议」——做法是给现有系统补一层「本体语义底座」（四张配置表），"
    "再在其上挂四类职能智能体（巡检 Job + LLM 编排 Planner），一切写操作仍走现有审批流。"
)
add_h2("1.2 三层定位")
add_table(
    ["层次", "文档/载体", "内容", "我的理解"],
    [
        ["战略层", "《Ai-DOP 应用智能体方案》（md）", "三阶段演进路径（任务级→流程级→企业级）", "愿景与方向，不指导实现"],
        ["方案层", "《Ai-DOP 本体驱动智能体建设方案》(7)(1)", "本体底座设计、四类+九域智能体、三大能力路径、P0~P4 计划", "本文档解读对象；可开发、可验收的落地方案"],
        ["任务层", "《Ai-DOP 智能体建设任务计划》V1.0", "24 项 WBS 任务、里程碑、依赖、质量闸门", "方案第七章的执行分解，逐项可跟踪"],
    ],
    col_widths=[1.8, 4.6, 4.6, 5.2],
)
add_h2("1.3 核心主张（我的概括）")
add_bullet("本体是「语义胶水」，不是新系统：四张登记表把分散在 S0~S9 的业务对象、关联、动作、工具统一登记，让智能体在同一套业务语言上工作；", ordered=True, index=1)
add_bullet("智能体是「巡检 + 推理 + 起草」，不是执行者：只做感知、分析与建议，落库一律经审批流人工确认（L2 默认，L3 白名单，L4 不开放）；", ordered=True, index=2)
add_bullet("证据链是「可信底线」：任何结论必须附表名、字段、记录号，无证据不下结论，从机制上抑制 LLM 幻觉；", ordered=True, index=3)
add_bullet("缺省关闭是「安全阀」：所有新能力初始关闭、逐租户灰度、可回退，未启用租户行为与现状完全一致。", ordered=True, index=4)

# ============ 二、章节结构与逻辑主线 ============
add_h1("二、章节结构与逻辑主线")
add_table(
    ["章节", "内容", "在逻辑主线中的位置"],
    [
        ["一、背景与目标", "Palantir Ontology 理念 → DOP 四层架构与 S0~S9 定位 → 现状盘点 → 四大建设目标 → 九域智能体画像", "「为什么做、做成什么样」"],
        ["二、总体思路", "零旁路增量四原则 + 本体理念落地形态映射 + 治理红线", "「按什么规矩做」"],
        ["三、本体语义底座", "四要素落 4 张配置表（实体/关联/动作链/工具注册）", "「语义层怎么建」"],
        ["四、四类智能体设计", "数据感知/关系推理/风险预警/执行调度 × 九域矩阵", "「智能体怎么搭」"],
        ["五、三大能力落地路径", "自动预警（四规则巡检）→ 自动分析（Planner+证据链）→ 自动优化（建议-审批-执行-验证闭环）+ 5.5~5.9 试点场景", "「能力怎么一步步长出来」"],
        ["六、与现有代码的对接点", "新增内容清单、复用与不改动边界、6.3 就绪度判定与需求卡标准", "「落在代码的哪里、还缺什么」"],
        ["七、分阶段实施计划", "P0 底座 → P1 预警 → P2 分析 → P3 优化 → P4 扩展，P0~P3 约 11 周", "「分几步走」"],
        ["八~十", "风险与应对 / 预期效果与价值量化 / 术语对照", "「风险、收益与口径」"],
    ],
    col_widths=[2.6, 7.0, 6.0],
)
add_body(
    "主线读法：前三章回答「是什么」（理念→原则→底座），第四、五章回答「怎么做」（智能体→能力路径），"
    "第六、七章回答「落哪、何时」（代码对接→计划），第八至十章回答「风险与收益」。"
    "第一章新增的「Order To Delivery 端到端订单执行周期动态价值流图（VSM）」是全文业务主线的可视化总纲："
    "以订单从下达到签收的端到端周期为轴，标注各环节的体征点与九域智能体的监控位置。"
)

# ============ 三、关键概念地图 ============
add_h1("三、关键概念地图")
add_table(
    ["概念", "方案定义", "我的理解（与代码的对应）"],
    [
        ["本体四要素", "实体/属性/关联/动作", "实体=业务对象（订单、工单、物料…）；属性由现有业务表字段承载，不重复建模；关联=对象间关系（订单→工单→工序）；动作=业务行为（下单、排产、发货）"],
        ["四类职能智能体", "数据感知/关系推理/风险预警/执行调度", "横向能力层：感知=巡检扫描事实，推理=沿登记链路找根因，预警=分级登记 S8，调度=起草建议；复用 22 个 Job、SmartDiagnosisEvidenceRegistry、ado_s8_exception、SmartOpsImprovement* 等现有资产"],
        ["九域模块智能体", "S1~S9 各一个", "纵向场景层 = 四类职能能力在每域的实例化；1.6 节「画像—现有代码承载」表已逐域列出复用服务与 Job"],
        ["L0~L4 自动化等级", "L2 默认、L3 白名单、L4 不开放", "平衡「自主执行」目标与「审批不可绕过」红线：L2=起草+审批后执行；L3=预设额度/白名单内自动执行+事后审计；L4 需一季度 L3 数据后评审"],
        ["证据链", "结论附表名/字段/记录号 + 快照时间 + 口径版本", "抑制 LLM 幻觉的机制性设计：LLM 只做语义整理与候选排序，推理骨架由登记表与证据校验代码决定"],
        ["工具注册闸门", "tool_code 显式注册 + 语义描述", "防越权：未注册 API 不可被智能体调用；动作/函数/工具分开登记、编码不混用"],
        ["改善闭环", "建议—审批—执行—验证回写", "复用 S9 已验证范式：IFlowBizHandler 审批 + ImprovementApproverGuard 守卫 + ImprovementEffectiveness 验证"],
    ],
    col_widths=[2.6, 4.6, 8.4],
)

# ============ 四、核心设计逐点解读 ============
add_h1("四、核心设计逐点解读")
add_h2("4.1 为什么是「零旁路增量」而不是另建智能体平台")
add_body(
    "方案的选型逻辑是：Ai-DOP 已具备巡检 Job、审批流、租户隔离、S9 诊断闭环、LLM 客户端等全部「零件」，"
    "另建平台意味着重复建设调度、认证、审批与数据通道，还会产生双份口径与越权风险。零旁路增量把智能体能力"
    "作为现有系统的「新零件」挂入：本体四要素用 4 张自建配置表承载（不引入 OWL/RDF 推理机、不在 Java/Spring 侧"
    "另建本体服务，适配本项目 .NET + Vue + MySQL 技术栈），智能体实现为插件 Job 目录下的独立巡检 Job 与一个 "
    "Planner。我的判断：这是与代码资产匹配度最高的选型，也是评审风险最低的路径。"
)
add_h2("4.2 本体四表是「登记制」而非「重新建模」")
add_body(
    "实体表（aidop_agent_entity）登记对象与数据落点、状态字典与属性口径；关联表（aidop_agent_relation）登记"
    "对象间 JOIN 条件；动作链表（aidop_agent_action_chain）登记可执行动作与自动化等级/幂等键/回滚方式；"
    "工具注册表（aidop_agent_tool_registry）是调用闸门。关键点：属性不重复建模，直接指向现有业务表字段——"
    "这避免了「双份模型漂移」，也让证据链天然可追溯到真实数据。"
)
add_h2("4.3 三大能力与四大目标、四类智能体的对应")
add_table(
    ["四大建设目标（1.5）", "三大能力（第五章）", "落地载体"],
    [
        ["数据感知和任务理解", "自动预警", "四规则巡检引擎 + 数据感知/风险预警 Job + S8 对接"],
        ["归因分析和任务规划", "自动分析", "关系推理智能体 + Planner + 证据校验 + ChatBI 增强"],
        ["长期记忆和智能决策", "自动优化", "建议-审批-执行-验证闭环 + 规则库回写（记忆沉淀）"],
        ["多智能体协同和自主执行", "自动优化（L2/L3）", "执行调度智能体 + 审批流 + 白名单 L3"],
    ],
    col_widths=[4.0, 3.2, 8.4],
)
add_body(
    "注意：四大目标中「长期记忆」的实现方式方案没有单独立表，而是通过「执行结果经有效性验证回写规则库与登记表」"
    "沉淀为持续进化的规则资产——这与「不另建系统」的总纲一致，但评审时应确认记忆的检索与冲突处理规则是否需要在"
    "需求卡 C5/C9 中补充明确。"
)
add_h2("4.4 5.5~5.9 试点与场景：全部站在现有代码肩膀上")
add_table(
    ["场景", "核心动作", "数据来源（方案已给出现有代码落点）"],
    [
        ["5.5 齐套四量问答（P2 试点）", "注册聚合工具 + 证据回答", "WorkOrdTemp 四量列、165 InvMaster、ic_item_stockoccupy / srm_po_occupy、dwd_requirement_examine_detail.lack_qty"],
        ["5.6 S1 交期提前影响分析", "沿订单→工单→物料→采购→交货→发货链路推演", "crm_seorderentry.sys_capacity_date、WorkOrdMaster、三级计划重排接口、srm_pr_main/srm_po_main"],
        ["5.7 S2 理论/实际产能与建议人数", "产能偏差归因 + 出勤人数建议", "ProdLineDetail.Rate、ExecutableDailyPlanService 实绩、OEE KPI、AdoS0LineSkillMaster"],
        ["5.8 S3 物料交期与自动选供", "履约偏差分析 + 供应商推荐", "DeliveryScheduleService DueDate、收货实绩、货源表 quota_rate/lead_time"],
        ["5.9 库存与安全库存建议", "安全库存/再订货点/补货量计算", "AdoS0ItemMaster.SafetyStk、S5 对账 Job 结果、发料记录、供应商 lead_time"],
    ],
    col_widths=[3.4, 4.4, 7.8],
)

# ============ 五、就绪度与计划的理解 ============
add_h1("五、就绪度判定与分阶段计划的理解")
add_h2("5.1 6.3 就绪度判定的实质：瓶颈在规格文档，不在代码")
add_body(
    "6.3 节对 S1~S9 九域做六维判定（业务目标/KPI、对象与本体、触发与事件、规则与算法、动作与权限、验收与评测），"
    "结论是：9 个域六维全部「部分」以上，仅 S2 验收评测、S7 KPI 为「缺失」——且方案明确「缺失」指需求卡文档未写或"
    "评测资产空缺，不代表代码能力不存在。我的理解：判定结果说明开发瓶颈不在代码（各域服务、Job、规则引擎、测试"
    "资产均已齐备），而在「规格的可开发化」——把业务期望写成 C0~C13 一页需求卡（尤其 C1 目标 KPI、C5 规则、"
    "C11 验收三硬项）。这也解释了为什么任务计划把「九域需求卡补齐」列为与 P0~P2 并行的独立任务线：需求卡不达标，"
    "任何域都不能进入开发排期。"
)
add_h2("5.2 分阶段计划的设计意图")
add_body(
    "P0（底座）→ P1（预警）→ P2（分析）→ P3（优化）是「能力逐级叠加」：每一阶段都建立在前一阶段的可核对结论之上"
    "（预警事实 → 根因证据 → 改善建议），且每阶段独立交付、可回退。P4 扩展按「数据就绪度 × 规则确定性」排序而非"
    "模块重要性：S4 采购执行先行（已有 AGT-S4-001 完整参照卡），S6 生产执行殿后（依赖车间实时数据，须 S4/S5 先"
    "跑通 L2 闭环）。P0~P3 合计约 11 周，P4 首个里程碑（S4 域 L2 全闭环）预计在第 15~16 周。"
)

# ============ 六、总体评价与注意点 ============
add_h1("六、我的总体评价与注意点")
add_h2("6.1 我认为方案的四个亮点")
add_bullet("务实：全程「复用现有代码」思维，每个能力点都标注了现有服务/表/Job 落点，可执行性高；", ordered=True, index=1)
add_bullet("可信：证据链 + 工具闸门 + 审批流三重约束，把 LLM 的角色限定在「语义整理与候选排序」，机制上抑制幻觉；", ordered=True, index=2)
add_bullet("可回退：缺省关闭、逐租户灰度、阶段独立交付，风险可控，不阻塞现有发版；", ordered=True, index=3)
add_bullet("可验收：需求卡 C0~C13 + 三硬闸门 + 数字型验收口径（准确率 ≥98%/≥90%、误报 ≤10%、证据完整率 100%），把「做没做好」变成可判定问题。", ordered=True, index=4)
add_h2("6.2 评审前建议确认的四个注意点")
add_table(
    ["注意点", "位置", "说明与建议"],
    [
        ["「长期记忆」的实现载体", "1.5 目标 3 / 第五章", "方案以规则库与登记表回写承载记忆，未单独立表；建议在需求卡 C5/C9 中明确记忆检索范围与冲突处理，避免跨域口径漂移"],
        ["S2 验收评测缺失", "6.3 矩阵 B", "排程域无测试资产；P4 排期前须补齐评测样例（专家标注 + 质量指标），任务计划已列为 S2 需求卡评审闸门"],
        ["S7 KPI 缺失", "6.3 矩阵 B", "成品物流 KPI 无注册证据；须先定义并注册（公式/口径/数据源）再开发"],
        ["术语表「S0~S10」表述", "第十章 OTD 词条", "全文模块编号为 S0~S9，该处「S10」疑为笔误，建议统一为 S0~S9"],
    ],
    col_widths=[3.4, 2.8, 9.4],
)
add_body(
    "总体结论：方案完整、自洽、可落地，与任务计划构成「方案—执行」两层闭环。建议按任务计划 1.3 节三项硬闸门"
    "推进：需求卡达标（C1/C5/C11）→ 6.3 销项 → P0 基线锁定，即可启动开发。"
)

doc.save(OUT)
print(OUT)