smqjh-agent/docs/build_agent_brief_doc.py

from __future__ import annotations

from pathlib import Path

from docx import Document
from docx.enum.section import WD_SECTION_START
from docx.enum.table import WD_TABLE_ALIGNMENT, WD_CELL_VERTICAL_ALIGNMENT
from docx.enum.text import WD_ALIGN_PARAGRAPH
from docx.oxml import OxmlElement
from docx.oxml.ns import qn
from docx.shared import Inches, Pt, RGBColor


ROOT = Path(__file__).resolve().parents[1]
OUT = ROOT / "docs" / "市民请集合智能助手Agent简版建设方案.docx"


BLUE = "2E74B5"
DARK_BLUE = "1F4D78"
INK = "0B2545"
MUTED = "667085"
LIGHT_FILL = "F2F4F7"
CALLOUT_FILL = "F4F6F9"
BORDER = "D0D5DD"


def set_cell_shading(cell, fill: str) -> None:
    tc_pr = cell._tc.get_or_add_tcPr()
    shd = tc_pr.find(qn("w:shd"))
    if shd is None:
        shd = OxmlElement("w:shd")
        tc_pr.append(shd)
    shd.set(qn("w:fill"), fill)


def set_cell_margins(cell, top=80, bottom=80, start=120, end=120) -> None:
    tc_pr = cell._tc.get_or_add_tcPr()
    tc_mar = tc_pr.first_child_found_in("w:tcMar")
    if tc_mar is None:
        tc_mar = OxmlElement("w:tcMar")
        tc_pr.append(tc_mar)
    for edge, value in (("top", top), ("bottom", bottom), ("start", start), ("end", end)):
        node = tc_mar.find(qn(f"w:{edge}"))
        if node is None:
            node = OxmlElement(f"w:{edge}")
            tc_mar.append(node)
        node.set(qn("w:w"), str(value))
        node.set(qn("w:type"), "dxa")


def set_table_width(table, widths_dxa: list[int]) -> None:
    tbl_pr = table._tbl.tblPr
    tbl_w = tbl_pr.find(qn("w:tblW"))
    if tbl_w is None:
        tbl_w = OxmlElement("w:tblW")
        tbl_pr.append(tbl_w)
    tbl_w.set(qn("w:w"), str(sum(widths_dxa)))
    tbl_w.set(qn("w:type"), "dxa")
    tbl_ind = tbl_pr.find(qn("w:tblInd"))
    if tbl_ind is None:
        tbl_ind = OxmlElement("w:tblInd")
        tbl_pr.append(tbl_ind)
    tbl_ind.set(qn("w:w"), "120")
    tbl_ind.set(qn("w:type"), "dxa")

    grid = table._tbl.tblGrid
    if grid is None:
        grid = OxmlElement("w:tblGrid")
        table._tbl.insert(0, grid)
    for child in list(grid):
        grid.remove(child)
    for width in widths_dxa:
        col = OxmlElement("w:gridCol")
        col.set(qn("w:w"), str(width))
        grid.append(col)

    for row in table.rows:
        for cell, width in zip(row.cells, widths_dxa):
            tc_pr = cell._tc.get_or_add_tcPr()
            tc_w = tc_pr.find(qn("w:tcW"))
            if tc_w is None:
                tc_w = OxmlElement("w:tcW")
                tc_pr.append(tc_w)
            tc_w.set(qn("w:w"), str(width))
            tc_w.set(qn("w:type"), "dxa")
            cell.vertical_alignment = WD_CELL_VERTICAL_ALIGNMENT.CENTER
            set_cell_margins(cell)


def set_east_asia_font(run, font_name="Microsoft YaHei") -> None:
    run.font.name = font_name
    run._element.rPr.rFonts.set(qn("w:eastAsia"), font_name)


def add_para(doc, text: str, style: str | None = None, bold_prefix: str | None = None):
    p = doc.add_paragraph(style=style)
    if bold_prefix and text.startswith(bold_prefix):
        r = p.add_run(bold_prefix)
        r.bold = True
        set_east_asia_font(r)
        tail = p.add_run(text[len(bold_prefix):])
        set_east_asia_font(tail)
    else:
        r = p.add_run(text)
        set_east_asia_font(r)
    return p


def add_bullet(doc, text: str):
    p = doc.add_paragraph(style="List Bullet")
    r = p.add_run(text)
    set_east_asia_font(r)
    return p


def add_number(doc, text: str):
    p = doc.add_paragraph(style="List Number")
    r = p.add_run(text)
    set_east_asia_font(r)
    return p


def add_heading(doc, text: str, level: int):
    p = doc.add_heading(text, level=level)
    for run in p.runs:
        set_east_asia_font(run)
    return p


def add_callout(doc, title: str, body: str):
    table = doc.add_table(rows=1, cols=1)
    table.alignment = WD_TABLE_ALIGNMENT.LEFT
    table.style = "Table Grid"
    set_table_width(table, [9360])
    cell = table.cell(0, 0)
    set_cell_shading(cell, CALLOUT_FILL)
    p = cell.paragraphs[0]
    r = p.add_run(title)
    r.bold = True
    r.font.color.rgb = RGBColor.from_string(DARK_BLUE)
    set_east_asia_font(r)
    p2 = cell.add_paragraph()
    r2 = p2.add_run(body)
    set_east_asia_font(r2)
    doc.add_paragraph()


def add_table(doc, headers: list[str], rows: list[list[str]], widths_dxa: list[int]):
    table = doc.add_table(rows=1, cols=len(headers))
    table.alignment = WD_TABLE_ALIGNMENT.LEFT
    table.style = "Table Grid"
    set_table_width(table, widths_dxa)
    hdr = table.rows[0]
    for i, text in enumerate(headers):
        cell = hdr.cells[i]
        set_cell_shading(cell, LIGHT_FILL)
        p = cell.paragraphs[0]
        p.alignment = WD_ALIGN_PARAGRAPH.CENTER
        r = p.add_run(text)
        r.bold = True
        r.font.color.rgb = RGBColor.from_string(INK)
        set_east_asia_font(r)
    for row in rows:
        cells = table.add_row().cells
        for i, text in enumerate(row):
            p = cells[i].paragraphs[0]
            p.alignment = WD_ALIGN_PARAGRAPH.LEFT
            r = p.add_run(text)
            set_east_asia_font(r)
    set_table_width(table, widths_dxa)
    doc.add_paragraph()
    return table


def configure_styles(doc: Document) -> None:
    section = doc.sections[0]
    section.page_width = Inches(8.5)
    section.page_height = Inches(11)
    for margin in ("top_margin", "bottom_margin", "left_margin", "right_margin"):
        setattr(section, margin, Inches(1))
    section.header_distance = Inches(0.492)
    section.footer_distance = Inches(0.492)

    styles = doc.styles
    normal = styles["Normal"]
    normal.font.name = "Calibri"
    normal._element.rPr.rFonts.set(qn("w:eastAsia"), "Microsoft YaHei")
    normal.font.size = Pt(11)
    normal.paragraph_format.space_after = Pt(6)
    normal.paragraph_format.line_spacing = 1.10

    title = styles["Title"]
    title.font.name = "Calibri"
    title._element.rPr.rFonts.set(qn("w:eastAsia"), "Microsoft YaHei")
    title.font.size = Pt(22)
    title.font.bold = True
    title.font.color.rgb = RGBColor.from_string(INK)
    title.paragraph_format.space_after = Pt(8)

    subtitle = styles["Subtitle"]
    subtitle.font.name = "Calibri"
    subtitle._element.rPr.rFonts.set(qn("w:eastAsia"), "Microsoft YaHei")
    subtitle.font.size = Pt(11)
    subtitle.font.color.rgb = RGBColor.from_string(MUTED)
    subtitle.paragraph_format.space_after = Pt(14)

    for name, size, color, before, after in [
        ("Heading 1", 16, BLUE, 16, 8),
        ("Heading 2", 13, BLUE, 12, 6),
        ("Heading 3", 12, DARK_BLUE, 8, 4),
    ]:
        style = styles[name]
        style.font.name = "Calibri"
        style._element.rPr.rFonts.set(qn("w:eastAsia"), "Microsoft YaHei")
        style.font.size = Pt(size)
        style.font.bold = True
        style.font.color.rgb = RGBColor.from_string(color)
        style.paragraph_format.space_before = Pt(before)
        style.paragraph_format.space_after = Pt(after)

    for name in ("List Bullet", "List Number"):
        style = styles[name]
        style.font.name = "Calibri"
        style._element.rPr.rFonts.set(qn("w:eastAsia"), "Microsoft YaHei")
        style.font.size = Pt(11)
        style.paragraph_format.space_after = Pt(8)
        style.paragraph_format.line_spacing = 1.167

    footer = section.footer.paragraphs[0]
    footer.alignment = WD_ALIGN_PARAGRAPH.RIGHT
    r = footer.add_run("市民请集合智能助手 Agent 简版建设方案")
    r.font.size = Pt(9)
    r.font.color.rgb = RGBColor.from_string(MUTED)
    set_east_asia_font(r)


def build_doc() -> None:
    doc = Document()
    configure_styles(doc)

    p = doc.add_paragraph(style="Title")
    r = p.add_run("市民请集合智能助手 Agent 简版建设方案")
    set_east_asia_font(r)
    p = doc.add_paragraph(style="Subtitle")
    r = p.add_run("结合当前 smqjh-agent 项目、Agent 设计复盘方案与结算需求文档整理")
    set_east_asia_font(r)
    add_para(doc, "版本：讨论稿 v0.1    日期：2026-06-08    适用：内部产品/研发/运营沟通")

    add_callout(
        doc,
        "核心判断",
        "这个产品不应只是一个聊天框，而应逐步升级为“模型自主规划、MCP 统一工具、业务系统只读查询、结果表格化/文件化、关键动作人工确认”的内部业务 Agent。"
    )

    add_heading(doc, "1. 项目定位", 1)
    add_para(doc, "市民请集合智能助手定位为面向后台管理员和运营人员的桌面端业务 Agent。第一版先解决“查数据、看依据、生成表格、辅助结算、记录人工确认事项”，后续再扩展到充值、消费履约、发券、对账、运维巡检等流程。")
    add_bullet(doc, "不是通用聊天机器人：回答范围限定在 smqjh 项目业务和日常简单问答。")
    add_bullet(doc, "不是简单任务按钮集合：模型应根据用户目标判断是否需要查询数据库、调用接口、生成文件或进入人工确认。")
    add_bullet(doc, "不是自动写入业务系统：涉及结算确认、充值导入、发券、扣减等动作必须进入人工确认。")

    add_heading(doc, "2. 当前项目已具备的底座", 1)
    add_table(
        doc,
        ["能力", "当前状态", "下一步意义"],
        [
            ["桌面端界面", "Electron 已搭建，包含对话、任务、配置、日志。", "继续作为管理员统一入口，重点优化过程展示和文件入口。"],
            ["MCP 服务", "Java MCP 已接管 DeepSeek、数据库配置和工具注册。", "后续把更多业务工具迁到 MCP，桌面端少做业务判断。"],
            ["只读数据库", "已支持 SELECT 校验、白名单表、默认 LIMIT、超时和只读事务。", "业务事实查询默认由 Agent 自动完成，不让用户自己执行 SQL。"],
            ["智能 SQL 查询", "已新增 smart query，由 DeepSeek 生成 SQL，MCP 安全执行并返回表格。", "解决“识别到了但不执行”的关键问题。"],
            ["Excel 产物", "已支持通用表格导出和价格对比导出。", "用户说“做成表格/导出 Excel”时可以直接产出文件。"],
            ["结算雏形", "已建立月结企业清单和企业月结处理计划工具。", "作为第一个明确业务场景继续深化。"],
        ],
        [1700, 3650, 4010],
    )

    add_heading(doc, "3. 推荐目标架构", 1)
    add_number(doc, "桌面端：只负责登录、对话、结果展示、文件打开、人工确认和日志查看。")
    add_number(doc, "Agent Runtime：负责多步循环，按“规划 -> 调工具 -> 观察 -> 再规划 -> 总结”的方式完成任务。")
    add_number(doc, "Java MCP：统一暴露业务工具、schema、业务口径、DeepSeek 调用、数据库只读查询和后续文件产物工具。")
    add_number(doc, "业务系统/数据库：提供只读查询和导出接口；写入类动作必须经过人工确认。")
    add_number(doc, "审计与评测：记录用户问题、工具调用、SQL、结果行数、耗时、失败原因，形成可回放链路。")

    add_heading(doc, "4. 一期建议功能清单", 1)
    add_table(
        doc,
        ["模块", "一期功能", "验收口径"],
        [
            ["对话工作台", "自然语言输入、多轮上下文、表格结果展示。", "用户问商品、订单、会员、物流时，Agent 能自动查并直接回答。"],
            ["工具调用", "MCP 工具规划、智能 SQL、商品查询、订单统计、月结计划。", "工具调用过程有日志，有失败提示，不再让用户自己查后台。"],
            ["文件产物", "把任意表格结果导出 Excel，后续扩展为结算报告。", "上一轮表格可直接导出并打开。"],
            ["人工确认", "差异、金额、写入、发券、充值导入统一标记人工确认。", "Agent 只给建议和待确认项，不擅自改业务系统。"],
            ["配置与权限", "DeepSeek、数据库、MCP 配置集中在 MCP；顶级 admin 不强制租户 ID。", "配置可持久化，重启后不反复输入。"],
            ["日志追踪", "记录工具、SQL、导出文件、异常和耗时。", "出现错误时能定位是模型、SQL、数据库还是接口问题。"],
        ],
        [1700, 4300, 3860],
    )

    add_heading(doc, "5. 第一个业务需求：结算、充值、消费", 1)
    add_para(doc, "结算需求来自你提供的《结算.docx》，目前可拆成三个业务场景：")
    add_heading(doc, "5.1 结算流程", 2)
    add_number(doc, "平台生成结算报告，包含产品订单/商品费用、运费、积分抵扣、现金支付等数据。")
    add_number(doc, "补齐海博编码、商品编码、SKU 编码等业务字段。")
    add_number(doc, "价格浮动或金额差异时只标记“需人工确认”，不自动修改系统。")
    add_number(doc, "发送客户核对，之后打印盖章、开具电子发票、等待客户付款。")
    add_heading(doc, "5.2 充值流程", 2)
    add_number(doc, "从企业获取客户充值信息表。")
    add_number(doc, "Agent 辅助排错、匹配企业/员工/手机号/金额。")
    add_number(doc, "人工确认后导入业务系统。")
    add_number(doc, "生成上账成功凭据和上账记录。")
    add_heading(doc, "5.3 消费履约流程", 2)
    add_number(doc, "C 端用户即时发货配送。")
    add_number(doc, "企业用户统一发货，非及时性发货需要导出订单并按仓库分配。")
    add_number(doc, "联系供应商配合入库，再选择闪送、物流快递等配送方式。")

    add_heading(doc, "6. 结算 Agent 功能拆解", 1)
    add_table(
        doc,
        ["子能力", "Agent 需要做的事", "输出产物", "人工确认"],
        [
            ["月结企业识别", "识别铜仁移动、招商银行贵阳分行、中数未来等月结企业，匹配 channelId/channelNo。", "月结企业清单。", "企业范围变化时确认。"],
            ["月份选择", "由管理员选择月份，自动计算开始/结束时间。", "结算月份和筛选条件。", "跨月、补单时确认。"],
            ["数据导出", "调用员工列表、订单表、商品订单、运费账单、对账汇总模板等接口。", "原始导出表。", "接口失败或字段缺失时确认。"],
            ["数据补齐", "从商品表补齐商品编码、SKU、海博编码等。", "补齐后的订单/商品明细。", "商品匹配不唯一时确认。"],
            ["汇总核对", "计算商品总额、运费、积分抵扣、现金支付、差异。", "结算汇总表和蓝色核对区。", "任意差异非 0 时确认。"],
            ["报告生成", "生成客户可核对的结算报告。", "Excel/Word/PDF 结算报告。", "发送客户前确认。"],
            ["状态记录", "记录待客户核对、待盖章、待开票、待付款、已完成。", "结算状态和提醒。", "状态变更确认。"],
        ],
        [1450, 3350, 2300, 2270],
    )

    add_heading(doc, "7. 落地路线", 1)
    add_table(
        doc,
        ["阶段", "目标", "交付内容"],
        [
            ["阶段 1：Agent 底座稳定", "让业务查询不再依赖固定任务匹配。", "多步 Agent loop、smart query、schema 工具、通用表格导出。"],
            ["阶段 2：结算场景跑通", "先完成铜仁移动等月结企业的报告生成闭环。", "导出接口调用、Excel 合并、汇总计算、差异标记、人工确认清单。"],
            ["阶段 3：充值/消费扩展", "把充值导入、消费履约、配送状态纳入 Agent。", "充值校验、分仓订单、供应商/物流状态查询。"],
            ["阶段 4：治理与上线", "支持多人使用，同时可审计、可限流、可回归测试。", "中心 MCP、连接池、权限、trace 面板、评测集。"],
        ],
        [1500, 3300, 4560],
    )

    add_heading(doc, "8. 后续需要确认的信息", 1)
    add_bullet(doc, "结算表最终标准模板：客户侧希望看到的列、盖章版格式、开票字段。")
    add_bullet(doc, "各导出接口真实参数：月份、企业渠道、订单状态、是否已付款、是否排除逻辑删除。")
    add_bullet(doc, "运费账单和订单表的稳定关联字段：订单号、第三方订单号、运单号是否一一对应。")
    add_bullet(doc, "商品编码补齐口径：海博编码、商品编码、SKU 编码分别来自哪些表和字段。")
    add_bullet(doc, "人工确认流程入口：是在 Agent 对话里确认，还是推到业务系统待办/审批。")

    add_callout(
        doc,
        "建议",
        "下一步优先把“铜仁移动 2026 年 5 月结算”作为第一条端到端样例做穿：导出原始表、补齐商品字段、计算汇总、标记差异、生成 Excel 报告。等这条链路稳定，再复制到招商银行贵阳分行和中数未来。"
    )

    OUT.parent.mkdir(parents=True, exist_ok=True)
    doc.save(OUT)
    print(OUT)


if __name__ == "__main__":
    build_doc()