用 WPS 开放 API + AI Agent 重写文档自动化：一名软件工程师的实战笔记
1. 背景：文档自动化为什么需要重写
过去我们做文档自动化，套路通常是：找模板、复制、填字段、人工校验、导出 PDF、发邮件。模板一多，字段映射就散落在脚本和 Excel 里；格式一改，维护成本指数上升。WPS 开放 API 的出现，让我们可以把“文档操作”从业务代码里抽离出来，交给稳定的文档服务；而 AI Agent 则负责理解自然语言任务、规划步骤、调用工具。两者结合，不是简单堆叠，而是把流程从“人驱动脚本”变成“Agent 编排、WPS 执行、人只审核”。
2. 整体架构
系统分四层：
- 接入层：Webhook、定时任务、IM 消息、表单。
- Agent 层：LLM + 规划器 + 工具调用 + 记忆 + 规则校验。
- 工具层：封装 WPS 开放 API，包括创建文档、替换书签/占位符、导出 PDF、设置权限、读取元数据。
- 存储层：模板库、任务库、对象存储、审计日志。
关键原则：不让 LLM 直接生成复杂文档 XML，而是让它输出结构化 JSON，由工具层调用 WPS 开放 API。这样可控、可测、可回滚。
3. 准备 WPS 开放平台环境
先到 WPS官网 进入开放平台，注册开发者账号，创建应用，获取 App ID、App Secret 和回调地址。本地联调时，建议从 WPS官网 或 WPS下载 页面安装最新版 WPS Office，保证加载项、云文档和 API 版本一致。WPS下载 要认准官方渠道，避免第三方安装包带来安全风险；WPS官网 有完整的 API 文档、SDK、调试工具和错误码说明。
WPS 开放 API 常见鉴权方式包括 OAuth2 和签名鉴权。生产环境要把 token 放密钥管理，不要硬编码。access_token 要缓存，并处理过期与刷新，避免并发刷新触发限流。
4. AI Agent 的角色
Agent 的核心循环可以概括为：
- 理解任务：例如“根据销售数据生成周报，套用公司模板，导出 PDF 并发给王经理”。
- 规划步骤：取数、填模板、校验、导出、通知。
- 调用工具：get_sales_data、wps_create_doc、wps_replace_placeholders、wps_export_pdf、send_message。
- 自我反思：检查字段缺失、金额格式、日期范围、权限边界。
- 输出结果：返回文档链接、PDF、审计记录。
用 Function Calling 定义工具 schema，例如：
tools = [
{
'name': 'wps_replace_placeholders',
'description': '在 [WPS](https://www.wps.com/) 文档中替换占位符',
'parameters': {
'type': 'object',
'properties': {
'doc_id': {'type': 'string'},
'mapping': {'type': 'object'}
},
'required': ['doc_id', 'mapping']
}
}
]
注意：工具描述要准确，参数校验要严格。LLM 可能编造模板 ID 或字段，工具层必须拒绝非法请求。
5. 调用 WPS 开放 API 的代码骨架
下面是一段 Python 示例，展示认证、创建文档、替换占位符的骨架。实际路径、参数和鉴权方式以 WPS官网 开放平台文档为准。
import requests
class [WPS](https://www.wps.com/)Client:
def __init__(self, app_id, app_secret):
self.base = 'https://open.wps.cn/api/v1'
self.app_id = app_id
self.app_secret = app_secret
self.token = None
def get_token(self):
if self.token:
return self.token
resp = requests.post(
f'{self.base}/oauth/token',
json={
'app_id': self.app_id,
'app_secret': self.app_secret,
'grant_type': 'client_credentials'
},
timeout=10
)
resp.raise_for_status()
self.token = resp.json()['access_token']
return self.token
def create_doc(self, template_id, name):
headers = {'Authorization': f'Bearer {self.get_token()}'}
resp = requests.post(
f'{self.base}/docs',
headers=headers,
json={'template_id': template_id, 'name': name},
timeout=20
)
resp.raise_for_status()
return resp.json()['doc_id']
def replace_placeholders(self, doc_id, mapping):
headers = {'Authorization': f'Bearer {self.get_token()}'}
resp = requests.post(
f'{self.base}/docs/{doc_id}/replace',
headers=headers,
json={'mapping': mapping},
timeout=20
)
resp.raise_for_status()
return resp.json()
这段代码的重点不是路径本身，而是分层：WPSClient 只负责 HTTP 和鉴权，Agent 不直接拼请求。这样后期替换成 SDK 或调整 API 版本，改动面很小。
6. Agent 编排伪代码
def run_agent(task):
plan = llm_plan(task, tools)
ctx = {}
for step in plan:
tool = step['tool']
args = step['args']
if tool == 'wps_create_doc':
ctx['doc_id'] = wps.create_doc(args['template_id'], args['name'])
elif tool == 'wps_replace_placeholders':
wps.replace_placeholders(ctx['doc_id'], args['mapping'])
elif tool == 'wps_export_pdf':
ctx['pdf_url'] = wps.export_pdf(ctx['doc_id'])
return ctx
每一轮循环都要做三件事：参数校验、权限校验、审计记录。特别是权限，Agent 只能访问当前用户有权限的模板和文档。越权风险不能靠 prompt 解决，要靠工具层和鉴权系统。
7. 实战中踩过的坑
- 模板格式漂移：WPS 模板里的书签被误删，替换失败。解决：模板版本化，替换前先校验书签清单。
- Token 并发刷新：多个任务同时刷新 token，触发限流。解决：单飞 + 分布式锁 + 提前刷新。
- 大文档性能：一次替换上千字段很慢。解决：批量接口、分片、异步任务、进度回调。
- 权限边界：Agent 不能越权访问文档。解决：最小权限、用户身份透传、操作审计。
- PDF 字体缺失：导出后排版变化。解决：服务端预装字体，或使用 WPS官网 推荐方案。
- 错误码不透明：WPS 开放 API 返回错误时，要记录 request_id，方便排查。
8. 效果与总结
重写后，周报生成从 30 分钟降到 2 分钟，人工只做审核；合同生成、发票整理也在复用同一套工具层。WPS 开放 API 负责稳定的文档操作，AI Agent 负责灵活的任务理解与编排。建议从单一高频场景切入，先把工具层做稳，再让 Agent 逐步接管更多步骤。
最后提醒：从 WPS官网 获取最新 API 文档，从 WPS下载 安装官方客户端联调。WPS 开放 API + AI Agent 不是替代人，而是把工程师从重复劳动中解放出来。
