简介这份《合作协议模板》是一份面向商业合作双方的法律文书范本适合产品方与渠道推广方在确立合作前参考使用帮助中小团队、创业公司或商务人员快速搭建规范的合作框架减少条款遗漏带来的纠纷风险。模板围绕合作方式、双方权利义务、合作期限、分成结算、保密责任、不可抗力、适用法律与争议解决、协议生效及附件授权书等模块展开其中分成比例按首次成交6:4、续费7:3的约定给出具体示例付款流程明确为每月15日前对账、确认后5个工作日内结算可直接替换主体信息与产品名称后使用。资源包共1个文件为docx格式文档大小约25KB结构完整、层级清晰便于编辑修改与打印签署。目前已有83人学习下载适合需要起草合作协议、梳理分成结算流程或补全授权书附件的读者参考借鉴。1. 合作协议模板.docx 为什么不该靠复制粘贴维护商务同学发来一份合作协议模板.docx说这次要给三百多家渠道商各出一份甲方名称、统一社会信用代码、分成比例、签约日期都不一样。很多人第一反应是打开 Word 复制一份改一份改到第五十份时手开始抖改到第一百份时就开始漏字段。这个标题落到工程侧讲的不是条款怎么写而是把 docx 当成一种可解析、可渲染、可校验的文档格式来对待模板只维护一份业务数据从表格或数据库来渲染交给脚本产物统一命名归档。适合需要批量出文书的研发、行政系统集成和办公自动化同学也适合想把模板塞进审批流的产品团队。收益很直接——字段不漏、格式不飘、版本可回溯出了问题能定位到是某一行的数据错还是模板改坏了。2. 拆开合作协议模板.docxOOXML 结构与可编程改造点不搞清楚 docx 里面长什么样后面所有替换都会变成玄学。这一章先把它当二进制包拆开看再决定哪些节点能碰、哪些节点不能碰。2.1 用 zipfile 看合作协议模板.docx 里到底存了什么docx 本质是一个 zip 包把扩展名改成 .zip 也能解压。先用系统自带工具列个清单比任何文档都直观# 列出包内文件看结构而不是看正文 unzip -l 合作协议模板.docx # 解压到临时目录后面用编辑器逐份比对 mkdir -p /tmp/tpl unzip -o 合作协议模板.docx -d /tmp/tpl ls -R /tmp/tpl逻辑说明第一行只列目录树确认包内有哪些 part第二行解压后才能真正看到 XML 内容。参数上-o表示覆盖已存在文件方便反复解压同一份模板做对比-d指定输出目录避免污染当前工作目录。解压后你会看到一批以 word/ 打头的文件其中真正影响生成结果的是下面这几个包内路径内容改造时动不动word/document.xml正文段落、表格、占位符主要操作对象word/styles.xml标题、正文、表格线等样式定义只读别随手改word/header1.xml页眉常见于放 logo 和文件编号需要自动编号时动word/footer1.xml页脚页码一般保留word/_rels/document.xml.rels图片、超链接的关系映射换 logo 时动docProps/core.xml作者、修订时间等元信息生成时可写入注意样式定义集中在 styles.xml如果你在模板里直接对某段文字手动加粗、手动改字号渲染新内容时这些手动格式会跟着 run 一起被复制导致同一份文档里字号不统一。规范做法是把格式收敛到命名样式里正文只引用样式。2.2 段落、样式与书签python-docx 读模板的常用对象拆包看 XML 适合排查疑难日常操作还是用 python-docx 更稳。下面这段脚本不修改任何内容只把模板的结构打印出来先摸清有哪些段落、几个表格、run 是怎么被拆的from docx import Document doc Document(合作协议模板.docx) # 1. 按顺序输出非空段落及其样式名用来判断哪几段是条款标题 for i, p in enumerate(doc.paragraphs): if p.text.strip(): print(i, repr(p.style.name), p.text[:40]) # 2. 遍历表格第几个表、第几行、每格文本 for ti, table in enumerate(doc.tables): for ri, row in enumerate(table.rows): cells [c.text.strip() for c in row.cells] print(ftable{ti} row{ri}: {cells}) # 3. 看 run 拆分情况一个段落常被 Word 切成多段 p doc.paragraphs[0] print([(r.text, r.font.name, r.bold) for r in p.runs])逻辑说明第一步用来给条款定位样式名如 Heading 1、Normal比文本内容更可靠因为条款正文会改样式名一般不变第二步输出表格二维结构方便你确认「费用明细表」到底是第几个表、第几行是表头第三步最关键Word 会因为拼写检查、输入法切换、格式微调把一句话切成多个 run。参数说明doc.paragraphs只覆盖正文主体页眉、页脚以及嵌套在其他表格里的段落要单独取row.cells在遇到合并单元格时会把同一个单元格重复列出需要去重时改用底层row._tr.tc_lst按位置取。这也是后面做替换时最大的坑你以为在替换一个字符串实际它可能横跨三个 run。2.3 判断该用占位符替换还是整段渲染摸清结构之后选型只有三条路边界很清楚方案实现方式适合场景风险字符串替换遍历 run 手动 replace字段少于 10 个、格式固定run 拆分导致替换失败且不支持循环docxtpl 渲染Jinja2 语法的占位符有条件、有循环、批量生成模板必须按规范写占位符直接改 XML操作 document.xml 节点需要插入整段、整表结构容易破坏 OOXML 结构样式丢失我的判断标准是只要出现「费用明细行数不固定」「某些条款只在特定合作模式下出现」这两种需求中的任意一种就上 docxtpl不要留恋字符串替换。反过来如果只是把一份固定合同的签署日期改一下写十行 python-docx 代码反而更省事引入模板引擎属于过度设计。3. 给合作协议模板.docx 设计占位符与渲染管线上一章确认了 docxtpl 这条路线这一章把模板改造规范和渲染代码一次讲透。占位符设计得好后面批量出文就是填空题设计得随意每次改需求都要回去翻模板。3.1 占位符命名规范与三个必踩的坑先定命名规范字段名统一 snake_case用前缀区分归属避免几十个字段混在一起分不清占位符写法是否推荐原因{{party_a_name}}推荐Jinja2 原生语法docxtpl 直接识别{{ party_a_name }}可用空格不影响渲染但容易被 Word 拆 run${party_a_name}不推荐需要自己实现替换无法做条件和循环party_a_name禁止全角括号Jinja2 不认肉眼还很难分辨三个常见坑要提前避开。第一是 Word 的自动更正输入{{后如果中间被自动加了空格或格式花括号会被拆到不同 run渲染时匹配不到解决办法是在模板里关闭自动套用格式或者先在记事本写好再粘进 Word。第二是中文引号和全角括号肉眼几乎看不出差别建议渲染前用脚本扫一遍非 ASCII 的括号字符。第三是拼写检查把英文占位符标红虽然不影响渲染但会干扰人工校对建议在模板里把占位符语言设为「不检查拼写」。3.2 用 docxtpl 渲染合作协议模板的最小命令模板改造完成后渲染本身只有几行。下面这段是最小可用版本同时打开了严格模式from datetime import date from jinja2 import Environment, StrictUndefined from docxtpl import DocxTemplate # 严格模式字段拼错时直接抛异常而不是静默留空 env Environment(undefinedStrictUndefined) tpl DocxTemplate(合作协议模板.docx) context { party_a_name: 某某科技有限公司, party_b_name: 某某信息服务有限公司, contract_no: HZ-2024-0618-001, share_ratio: 0.35, sign_date: date(2024, 6, 18), } tpl.render(context, jinja_envenv) tpl.save(out/合作协议_某某信息服务_20240618.docx)逻辑说明DocxTemplate负责加载并解析模板包render把 context 里的变量填进去save输出新文件原模板文件不会被修改。参数说明jinja_envenv是关键默认情况下 Jinja2 对未定义变量是宽容的写错字段名只会渲染成空字符串一份漏了甲方名称的合同就发出去了换成StrictUndefined后拼错字段直接报错中断把小事故挡在生成阶段。share_ratio传浮点数没问题但如果模板里要显示成百分比需要在模板中写成{{ %.0f%%|format(share_ratio*100) }}或者注册过滤器统一处理。3.3 表格行循环与条件段落怎么写合作协议里最常见的两个动态结构是费用明细表和可选条款。明细表行数不固定用{%tr %}标签控制整行可选条款是否出现用{%p %}标签控制整段费用明细表第一行写{%tr for item in fee_items %} 中间那一行是模板行写{{ item.name }} | {{ item.amount }} | {{ item.remark }} 最后一行写{%tr endfor %} 独占条款段落写{%p if has_exclusive %}{{ exclusive_text }}{%p endif %}对应的数据结构就是一个字典列表加一个布尔值context.update({ fee_items: [ {name: 基础服务费, amount: 120,000.00, remark: 按季度支付}, {name: 增量分成, amount: 按 35% 结算, remark: 次月 15 日前对账}, ], has_exclusive: True, exclusive_text: 本协议有效期内乙方不得与同类第三方签署同类合作。, })参数说明{%tr %}的作用范围是整张表行for 和 endfor 必须分别写在两行里中间行才是被复制的模板行{%p %}作用范围是整段注意 endif 要和 if 合并在同一段否则会多出一个空段落。如果表格里有合并单元格模板行的合并结构会被保留复制但跨列数不同会导致版式错位这种情况建议拆成两张表分别循环。3.4 金额大写与日期格式的过滤器合同里金额通常要同时出现小写和大写日期也要写成中文格式。这两个转换注册成 Jinja2 过滤器最省事CN_NUM 零壹贰叁肆伍陆柒捌玖 CN_UNIT [, 拾, 佰, 仟] CN_BIG [, 万, 亿] def _four(n: int) - str: s, zero , False for i in range(3, -1, -1): d (n // 10 ** i) % 10 if d 0: zero True else: if zero and s: s 零 s CN_NUM[d] CN_UNIT[i] zero False return s def rmb_upper(amount) - str: cents int(round(float(amount) * 100)) yuan, rest divmod(cents, 100) jiao, fen divmod(rest, 10) head 零元 if yuan 0 else _four(yuan) 元 if jiao 0 and fen 0: return head 整 return head (CN_NUM[jiao] 角 if jiao else 零) (CN_NUM[fen] 分 if fen else 整) env.filters[rmb_upper] rmb_upper env.filters[date_cn] lambda d: f{d.year}年{d.month}月{d.day}日逻辑说明_four把四位以内的整数转成中文读法并处理中间的零rmb_upper先把金额放大 100 倍转成整数分避免浮点误差再分别处理元、角、分。参数说明round(float(amount), 2)先做一次两位小数取整防止 0.10.2 这类浮点尾数问题模板里写{{ total_amount | rmb_upper }}和{{ sign_date | date_cn }}即可。这版实现覆盖日常合同金额遇到上万、上亿的进位组合建议补几条单元测试别直接上生产。4. 批量生成合作协议数据校验、命名规范与产物归档单份渲染跑通只是及格线真正省时间的是批量那一环。这一章的重点不在渲染而在渲染之前的字段校验和渲染之后的产物管理。4.1 用 pandas 加 pydantic 做字段校验批量出文最大的事故来源不是模板是业务表格里的脏数据企业名称前后带空格、信用代码少一位、分成比例填了 35 而不是 0.35。用 pydantic 定义一行数据的模型把校验规则显式写出来import pandas as pd from datetime import date from pydantic import BaseModel, Field, field_validator class PartyRow(BaseModel): party_a_name: str Field(min_length2, max_length50) party_b_name: str Field(min_length2, max_length50) credit_code: str share_ratio: float Field(gt0, le1) sign_date: date contract_no: str field_validator(credit_code) classmethod def check_code(cls, v: str) - str: v v.strip().upper() if len(v) ! 18 or not v.isalnum(): raise ValueError(统一社会信用代码格式不合法) return v df pd.read_excel(parties.xlsx, dtypestr) # 全部按字符串读入避免 pandas 擅自改精度 rows [PartyRow(**r) for r in df.to_dict(orientrecords)]逻辑说明Field声明长度和区间约束field_validator处理需要自定义逻辑的字段。参数说明dtypestr很重要pandas 默认会把纯数字的合同编号读成 int把 18 位信用代码读成科学计数法后面再想还原就麻烦了pydantic v2 用field_validatorv1 里叫validator迁移时注意替换。校验失败的常见处理策略如下表字段类型校验规则失败处理party_b_namestr非空长度 2-50该行跳过并写入失败清单credit_codestr18 位字母数字转人工复核不自动生成share_ratiofloat大于 0 且不超过 1中断该行并告警sign_datedate可解析为标准日期跳过并记录原始值contract_nostr非空批次内唯一重复时追加序号4.2 批量渲染主循环与失败隔离校验通过的行走渲染失败的行不能连累整批。下面这个循环把「校验—渲染—命名—记账」串在一起import hashlib, logging from pathlib import Path from docxtpl import DocxTemplate OUT Path(out); OUT.mkdir(exist_okTrue) logging.basicConfig(levellogging.INFO, format%(levelname)s %(message)s) ok, bad [], [] for idx, row in enumerate(rows): try: tpl DocxTemplate(合作协议模板.docx) # 每份重新加载避免状态串味 tpl.render(row.model_dump(), jinja_envenv) name f合作协议_{row.party_b_name}_{row.sign_date:%Y%m%d}_{row.contract_no}.docx path OUT / name tpl.save(path) ok.append({file: name, sha256: hashlib.sha256(path.read_bytes()).hexdigest()[:16]}) except Exception as e: logging.warning(第 %s 条失败: %s, idx 2, e) bad.append({row: idx 2, party: row.party_b_name, reason: str(e)})逻辑说明try 包住单个文件的整个生成过程一条失败不影响后续条目最后分别落盘成功清单和失败清单。参数说明DocxTemplate必须在循环内部重新实例化因为 render 会修改模板对象的内部 XML 结构复用同一个实例容易出现上一份的数据残留到下一份sha256取前 16 位作为产物指纹后续如果发现某份文件被改动过比时间戳更可靠。文件名里带乙方名称和日期是为了让商务同学在文件夹里直接肉眼定位不用打开文件看内容。4.3 产物目录结构与留痕台账批量产物一多目录设计比代码更重要。我一般会按批次建目录批次号用日期加流水例如out/20240618-01/下面再分正式文件/、待复核/、台账/三个子目录。台账用 CSV 落盘字段至少包括文件名、乙方名称、合同编号、渲染时间、产物指纹这样半年后有人问「这份合同是什么时候生成的、用的哪批数据」翻台账就能答。失败清单单独一份 CSV交给业务同学去补数据补完可以只重跑失败的那一批不用全量重来。留痕的另一层含义是模板版本模板文件本身也要记版本号产物命名里可以带上模板版本例如合作协议_某某信息服务_20240618_HZ-001_v3.docx避免出了纠纷时说不清用的是哪一版条款。5. 合作协议模板.docx 的回归校验与三个进阶技巧生成完成不等于交付完成最后一步是自检。这里给三个成本很低但很值钱的技巧。5.1 渲染后扫描残留占位符最常见的事故是模板里新加了字段但数据源没有对应列渲染后文档里明晃晃留着{{party_b_contact}}。用脚本在生成后统一扫一遍import re, zipfile def scan_placeholders(path): with zipfile.ZipFile(path) as z: xml z.read(word/document.xml).decode(utf-8) text re.sub(r[^], , xml) # 先剥掉 XML 标签 return re.findall(r\{\{.*?\}\}, text) for p in sorted(Path(out).glob(*.docx)): left scan_placeholders(p) if left: print(p.name, left)逻辑说明必须先把 XML 标签剥掉再匹配因为花括号可能被拆在多个 run 里直接对原始 XML 做正则会漏判。参数说明re.sub(r[^], , xml)只是粗略去标签够用于这种扫描场景如果模板里用了条件标签渲染后残留的多半是{%打头的控制符可以把正则改成\{(?:\{|\%)一并覆盖。这个脚本适合放在批量任务的最后一步自动执行有残留就返回非零退出码。5.2 转 PDF 归档与文档差分正式归档通常要 PDF用 LibreOffice 命令行批量转换最省事soffice --headless --convert-to pdf --outdir out/pdf out/*.docx参数说明--headless表示无界面运行适合放在容器或定时任务里--outdir指定输出目录不指定会生成在源文件旁边。注意容器里要装中文字体否则转换出来的 PDF 会出现方框或字体回退导致的排版位移转完之后随机抽两三份打开看一眼比相信日志更靠谱。模板改版时把两个版本的 docx 转成 Markdown 再做 diff比在 Word 里开比较功能快得多pandoc 合作协议模板_v2.docx -t markdown -o v2.md pandoc 合作协议模板_v3.docx -t markdown -o v3.md diff -u v2.md v3.md这样能看到的是纯文本差异占位符改动、条款措辞改动一目了然评审时直接贴进工单。5.3 模板与渲染器分离的版本管理最后一个技巧是仓库拆分模板放模板仓库渲染脚本和过滤器放代码仓库两者通过一个约定好的字段清单文件对齐。字段清单就是一份 CSV列出每个占位符的名称、类型、是否必填、示例值模板仓库提交时由 CI 校验「模板里出现的占位符是否都在清单里」代码仓库提交时校验「代码里读取的字段是否都在清单里」。一份合同模板改了三版、渲染脚本改了十版只要字段清单没变两边就可以各自演进出问题也能迅速定位到是哪一侧不一致。落到日常操作上模板改动走模板仓库的 PR渲染逻辑改动走代码仓库的 PR跨仓库的字段变更必须两个 PR 一起合别让字段清单成为唯一的真相来源之外的第二套说法。本文还有配套的精品资源点击获取