在 AI 应用开发中我们经常会遇到一个场景拿到了几十份 PDF、Word、Excel 资料希望 AI 能帮助我们按指定格式整理成表格、摘要、报告或者知识库条目。直接复制粘贴进对话框显然不现实逐份处理又太耗时。仓颉 Skill 正是为了解决这类“把资料文件交给 AI让他整理出你想要的”需求而设计的一种工程化方案。本文将围绕仓颉 Skill 的概念、核心原理、完整实战案例以及常见问题展开帮助你把分散的资料文件变成结构化、可复用的 AI 输出。1. 背景与核心概念仓颉 Skill 是什么解决什么问题在开始动手之前我们先花一点时间把“仓颉 Skill”这个概念理清楚。这不是某个官方文档里的固定专属名词而是 AI 工程实践中的一种通用能力封装思路。简单来说它是一套“技能包”告诉大模型如何处理你上传的资料文件以及最终应该输出什么结构的成果。1.1 为什么直接对话无法满足资料整理需求假设你手上有一批项目周报、技术方案、会议纪要希望 AI 帮你整理出一个带优先级、负责人和截止时间的任务清单。如果你只是简单地把文档内容粘贴给 AI经常会出现以下问题输出格式不稳定第一次给你表格第二次给你列表第三次直接变成段落。内容抓取重点不准AI 可能把不重要的背景信息当成重点而漏掉真正的待办事项。长文档处理困难超出上下文窗口后AI 往往“忘记”前面的内容。过程不可复用换一份新文档又要重新写一遍提示词。仓颉 Skill 的核心目标就是把这些不可控的交互过程变成一套“半自动化流水线”你只需要把文件放进指定目录、运行一个命令AI 就会按照预设的规则读取、分析、整理并输出结果。1.2 仓颉 Skill 的技术本质从技术实现上看仓颉 Skill 可以拆解为以下三个层次层次名称作用第一层指令层Prompt定义 AI 的角色、任务目标、处理步骤和输出格式第二层解析层Parser读取 PDF、Word、Excel 等不同格式的文件内容第三层输出层Formatter将 AI 的回复整理为 Markdown、JSON、CSV 等结构化格式这种分层设计的好处非常明显即使之后更换不同的 AI 模型或者新增一种文件格式只需要修改对应的模块而不需要重写整套流程。这也是它在 AI 应用开发中最值得借鉴的地方。1.3 常见应用场景只要涉及“资料文件 整理输出”的需求仓颉 Skill 都能派上用场。常见场景包括文档摘要生成批量读取多份文档生成每份文档的摘要、关键词和核心结论。会议纪要转任务清单从会议记录中提取待办事项、负责人和截止时间。报表数据抽取从 Excel 或 CSV 中抽取指定字段转换为新的表格结构。知识库构建把散落的资料文件转换成统一的 Markdown 知识条目便于后续检索。简历筛选与候选人信息摘要从多份 PDF 简历中抽取姓名、工作年限、技能标签。无论你的原始资料是哪种格式思路都是一样的先用解析层把内容变成纯文本再用指令层让 AI 理解任务最后用输出层把结果标准化。2. 环境准备与版本说明搭建可运行的 Skill 基础环境仓颉 Skill 的实现并不依赖某个特定的平台只要你能够调用大模型 API就能把它跑起来。为了让后面的实战案例可复制我们需要先搭建一个最小可运行的环境。2.1 运行环境清单本文的示例以 Python 为主具体环境如下依赖项说明操作系统Windows 10/11、macOS、Linux 均可Python需要 3.9 及以上版本大模型 APIOpenAI 兼容接口或国内大模型平台的 API Key关键依赖库openai、pypdf、python-docx、pandas如果你使用的是国内大模型平台比如通义千问、智谱 GLM、DeepSeek 等只要它们提供 OpenAI 兼容的 API 接口代码中的base_url和api_key替换成对应平台的值即可。2.2 创建项目目录结构为了便于管理我们建议按照下面的结构组织项目cangjie_skill_demo/ ├── docs/ # 存放待整理的原始资料文件 ├── output/ # 存放 AI 整理后的结果文件 ├── parsers/ # 文件解析模块 │ ├── __init__.py │ ├── pdf_parser.py # PDF 文件解析 │ ├── docx_parser.py # Word 文件解析 │ └── excel_parser.py # Excel 文件解析 ├── skill.py # 核心 Skill 逻辑 └── config.json # 配置文件API Key、模型参数等这个结构看起来很传统但它的优势在于把“文件来源”“处理逻辑”“最终结果”三者隔离后续扩展新的文件格式时非常方便。2.3 安装依赖库在命令行中执行以下命令pip install openai pypdf python-docx pandas如果你的环境里已经安装过部分库建议使用虚拟环境python -m venv venv # Windows venv\Scripts\activate # macOS / Linux source venv/bin/activate pip install openai pypdf python-docx pandas注意这里没有锁定具体的版本号原因是各库的版本更新速度较快。如果你在使用过程中遇到 API 兼容问题可以优先查看对应库的官方文档或更新到最新稳定版。3. 核心原理拆解从指令设计到文件解析的完整链路在实际写代码之前我们要先理解仓颉 Skill 内部的工作流。这样你才能在自己的项目中灵活调整而不是只会抄代码。3.1 整体工作流仓颉 Skill 的处理流程可以拆成以下步骤扫描文件读取指定目录下所有符合条件的文件。解析内容针对不同文件格式调用对应的解析器提取纯文本。构造 Prompt根据用户的任务描述生成结构化的提示词。调用大模型将文本和提示词发送给大模型 API。解析输出从大模型的回复中提取目标内容并格式化为 Markdown 或 JSON。写入文件把整理结果保存到输出目录。3.2 指令层设计如何写一份高质量的 Skill Prompt指令层是仓颉 Skill 最核心的部分。同一个模型使用不同的 Prompt输出质量可能天差地别。下面是一个经过实践检验的 Prompt 模板你是一名专业的资料整理助手。 我会提供一份文档的全文内容请你根据以下要求完成整理 任务{task_description} 输出要求 1. 使用 Markdown 格式输出。 2. 先给出文档的核心摘要不超过 200 字。 3. 再列出关键信息点使用无序列表。 4. 如果文档中包含明确的待办事项请单独使用表格输出包含序号、事项、负责人、截止时间。 5. 如果文档中没有相关内容请明确写“无”。 文档内容如下 {document_text}这里有几个关键点需要注意角色设定让模型代入“资料整理助手”的角色能明显提高输出规范性。输出要求明确把“表格”“列表”“字数”这些细节写清楚模型才有明确的执行标准。兜底处理要求模型在信息缺失时写“无”可以有效避免幻觉。3.3 解析层设计三种典型文件的读取方式在实际项目中PDF、Word、Excel 和纯文本是最常见的四种格式。本文以 PDF、Word、Excel 为例# parsers/pdf_parser.py from pypdf import PdfReader def parse_pdf(file_path: str) - str: reader PdfReader(file_path) text for page in reader.pages: text page.extract_text() or return text# parsers/docx_parser.py from docx import Document def parse_docx(file_path: str) - str: doc Document(file_path) paragraphs [p.text for p in doc.paragraphs if p.text.strip()] return \n.join(paragraphs)# parsers/excel_parser.py import pandas as pd def parse_excel(file_path: str) - str: df pd.read_excel(file_path, sheet_nameNone) text_list [] for sheet_name, df_sheet in df.items(): text_list.append(f工作表{sheet_name}) text_list.append(df_sheet.to_string(indexFalse)) return \n.join(text_list)这里的解析逻辑比较简单直接PDF 按页提取文本Word 提取非空段落Excel 把每个工作表转换成字符串。如果你的资料中包含图片型 PDF也就是扫描件那么需要额外接入 OCR 服务这属于进阶优化方向本文先不展开。3.4 输出层设计让结果保持稳定结构大模型的直接回复通常是 Markdown 文本。为了让结果更可靠我们可以增加一个 JSON 输出模式让模型返回可编程处理的结构化数据然后再由程序转换成 Markdown。方法如下请以 JSON 格式输出JSON 结构如下 { summary: 文档摘要, key_points: [关键点1, 关键点2], tasks: [ {index: 1, task: 任务描述, owner: 负责人, deadline: 截止时间} ] }在skill.py中我们可以用json.loads()解析模型返回的 JSON再根据需要渲染成不同的格式。这样做的好处是后续无论是保存为 Markdown、CSV 还是导入数据库都非常方便。4. 完整实战案例构建一个多文件资料整理 Skill理论部分讲完下面进入实战环节。我们将实现一个基于 Python 的仓颉 Skill它可以读取docs目录下的多份 PDF、Word、Excel 文件。自动识别文件格式。调用大模型 API 整理每份文档。将结果统一保存为 Markdown 文件。整个案例以“会议纪要和周报转任务清单”为业务背景这是实际开发中最高频的需求之一。4.1 创建项目结构首先创建项目目录mkdir cangjie_skill_demo cd cangjie_skill_demo mkdir docs output parsers然后把需要整理的资料文件放入docs目录。例如docs/ ├── 2025-04-18-项目周报.pdf ├── 产品需求评审会议纪要.docx └── 研发排期表.xlsx4.2 编写配置文件 config.json在项目根目录创建config.json{ api_key: sk-xxxxxxxxxxxxxxxxxxxx, base_url: https://api.openai.com/v1, model: gpt-4o-mini, task_description: 请从文档中提取核心信息和待办事项输出要求见提示词。 }注意api_key请换成你自己的密钥。如果你的模型服务商不同修改base_url和model即可。千万不要把真实 Key 提交到公开仓库。4.3 编写核心 Skill 逻辑 skill.py下面是完整的skill.py代码关键逻辑都加了注释# skill.py import json import os import re from openai import OpenAI from parsers.pdf_parser import parse_pdf from parsers.docx_parser import parse_docx from parsers.excel_parser import parse_excel PROMPT_TEMPLATE 你是一名专业的资料整理助手。 我会提供一份文档的全文内容请你根据以下要求完成整理 任务{task_description} 输出要求 1. 先给出文档的核心摘要不超过 200 字。 2. 再列出关键信息点使用无序列表。 3. 如果文档中包含明确的待办事项请单独使用表格输出包含序号、事项、负责人、截止时间。 4. 如果文档中没有相关内容请明确写“无”。 文档内容如下 {document_text} def load_config(config_path: str config.json) - dict: with open(config_path, r, encodingutf-8) as f: return json.load(f) def parse_file(file_path: str) - str: 根据文件扩展名调用对应的解析器 ext os.path.splitext(file_path)[1].lower() if ext .pdf: return parse_pdf(file_path) elif ext .docx: return parse_docx(file_path) elif ext in (.xlsx, .xls): return parse_excel(file_path) elif ext .txt: with open(file_path, r, encodingutf-8) as f: return f.read() else: raise ValueError(f不支持的文件格式{ext}) def build_prompt(task_description: str, document_text: str) - str: return PROMPT_TEMPLATE.format( task_descriptiontask_description, document_textdocument_text[:12000] ) def call_llm(client: OpenAI, model: str, prompt: str) - str: response client.chat.completions.create( modelmodel, messages[ {role: system, content: 你是一个严谨的资料整理助手。}, {role: user, content: prompt} ], temperature0.3 ) return response.choices[0].message.content def process_file(client: OpenAI, model: str, task_description: str, file_path: str) - str: print(f正在处理{file_path}) document_text parse_file(file_path) prompt build_prompt(task_description, document_text) result call_llm(client, model, prompt) return result def main(): config load_config() client OpenAI(api_keyconfig[api_key], base_urlconfig[base_url]) docs_dir docs output_dir output os.makedirs(output_dir, exist_okTrue) if not os.path.exists(docs_dir): print(docs 目录不存在请先创建并放入资料文件。) return for filename in os.listdir(docs_dir): file_path os.path.join(docs_dir, filename) if not os.path.isfile(file_path): continue try: result process_file( clientclient, modelconfig[model], task_descriptionconfig[task_description], file_pathfile_path ) output_name re.sub(r\.[^.]$, , filename) _整理结果.md output_path os.path.join(output_dir, output_name) with open(output_path, w, encodingutf-8) as f: f.write(f# {filename}\n\n) f.write(result) print(f已保存{output_path}) except Exception as e: print(f处理 {filename} 时发生错误{e}) if __name__ __main__: main()这段代码需要注意几个细节document_text[:12000]是对文档长度的限制避免文档过长导致 API 请求超时或超出上下文窗口。temperature0.3是为了让 AI 输出更稳定减少自由发挥。re.sub用于去掉文件扩展名生成与源文件同名的输出文件。4.4 运行与验证在项目根目录执行python skill.py预期输出效果如下正在处理docs/2025-04-18-项目周报.pdf 已保存output/2025-04-18-项目周报_整理结果.md 正在处理docs/产品需求评审会议纪要.docx 已保存output/产品需求评审会议纪要_整理结果.md 正在处理docs/研发排期表.xlsx 已保存output/研发排期表_整理结果.md打开output目录下的 Markdown 文件你会看到 AI 整理后的结构化内容。4.5 结果说明以一份会议纪要为例生成的效果大致如下# 产品需求评审会议纪要.docx ## 核心摘要 本次会议主要讨论了新版用户中心的需求方案明确了注册流程优化和权限管理两个核心模块的改造范围预计在 5 月底完成开发并上线。 ## 关键信息点 - 注册流程增加手机号验证码登录方式 - 权限管理模块采用 RBAC 模型 - UI 设计稿将在两天内输出 - 后端接口文档由张三负责编写 ## 待办事项 | 序号 | 事项 | 负责人 | 截止时间 | | --- | --- | --- | --- | | 1 | 输出 UI 设计稿 | 李四 | 2025-04-22 | | 2 | 编写后端接口文档 | 张三 | 2025-04-24 | | 3 | 完成数据库表结构设计 | 王五 | 2025-04-26 | 到这里一套完整的仓颉 Skill 最小实现已经跑通了。你可以把这个目录随手上传到服务器作为自动化文档处理服务的基础。 ## 5. 常见问题与排查思路解决 Skill 运行中的高频错误 在实际使用过程中你会发现很多问题与代码本身无关而是出在环境、文件格式或 API 调用层面。下面整理了一份高频问题排查表。 | 问题现象 | 常见原因 | 解决思路 | | --- | --- | --- | | 导入 openai 模块报错 | 未安装依赖或 Python 环境不对 | 确认虚拟环境已激活执行 pip install openai | | 读取 PDF 时中文乱码 | PDF 为扫描件或使用了非标准字体 | 检查 PDF 是否可复制文本扫描件需接入 OCR | | 读取 Excel 报错 | 文件正在被 Excel 占用 | 关闭 Excel 程序或复制一份文件后重试 | | API 调用返回 401 | API Key 无效 | 检查 config.json 中 api_key 是否正确 | | API 调用返回 429 | 请求频率超限或额度不足 | 降低请求频率或检查账户余额 | | 输出内容不完整 | 文档超过上下文窗口 | 增加截断逻辑或使用支持更长上下文的模型 | | Markdown 表格显示异常 | 模型未按表格格式输出 | 升级 Prompt明确要求“必须使用 Markdown 表格” | | 文件路径包含中文乱码 | 操作系统编码问题 | 在代码开头设置环境变量 PYTHONIOENCODINGutf-8 | ### 5.1 关键排查步骤 如果你遇到问题但不确定原因建议按以下顺序排查 1. **先跑通单个文件**在 docs 目录只放一个文件减少干扰。 2. **打印中间结果**在 parse_file() 后打印 document_text 前 500 字确认解析层是否正常。 3. **测试 API 连通性**写一个最小调用测试确认 API Key、base_url、model 三个参数是否正确。 4. **查看输出目录权限**确认 output 目录可写。 5. **开启日志**在 call_llm() 中打印 response.usage确认 token 消耗情况有助于判断是否因为超限导致异常。 ### 5.2 防止问题再现的建议 针对以上问题最好的方法是提前加好防御代码 - 对文档内容做长度截断。 - 对 API 调用做异常重试比如连续失败 3 次后跳过该文件。 - 对每个文件记录处理日志方便出错后定位。 - 不要直接修改原始资料文件所有输出统一写到 output 目录。 ## 6. 最佳实践与工程建议让仓颉 Skill 更稳定、更易维护 从“能用”到“好用”中间还有一段距离。下面分享一些在 AI 工程实践中积累下来的经验希望对你有帮助。 ### 6.1 版本管理与配置隔离 项目中的配置信息尤其是 API Key绝对不能硬编码在代码里。推荐做法是 1. **使用环境变量**通过 .env 文件保存敏感信息并用 python-dotenv 加载。 2. **区分环境**为开发、测试、生产环境准备不同的 config.json 文件。 示例 json // config.dev.json { api_key: dev-key, base_url: https://api.example.com/v1, model: gpt-4o-mini }6.2 处理逻辑模块化将文件解析、任务描述、输出格式化这三个模块彻底解耦是仓颉 Skill 持续演进的关键。比如如果未来要把输出从 Markdown 改成 HTML只需要新增一个formatter模块而不用动解析层。6.3 增加并发处理能力如果你一次要整理几十份甚至上百份文件串行处理会非常慢。可以通过线程池提高处理速度from concurrent.futures import ThreadPoolExecutor def process_batch(files): with ThreadPoolExecutor(max_workers5) as executor: futures [executor.submit(process_file, client, model, task, f) for f in files] for future in futures: print(future.result())注意并发调用 API 时要留意服务商的 QPS每秒请求数限制避免触发限流。建议先小批量测试再逐步提高并发数。6.4 结果校验与人工介入AI 的输出并不能保证 100% 正确。在自动化流程中建议增加一个“结果审查”环节。具体做法可以是将生成的结果 Markdown 文件交给第二遍 AI 校验检查是否有明显矛盾。对关键信息如金额、日期、负责人做正则提取并与原文比对。保存原始文档与整理结果的对应关系方便人工回溯。6.5 安全边界与权限控制如果在企业内部使用仓颉 Skill必须注意以下安全事项只授权给可信人员使用不要任意开放目录写入权限。限制 AI 只能访问指定目录防止敏感文件被读取。对输出文件做敏感信息脱敏处理。比如可以在 Prompt 中增加“不要输出身份证号、手机号等隐私信息”。生产环境改动前先在测试环境跑完整流程并保留日志。7. 总结与下一步学习方向本文从零开始搭建了一个“把资料文件交给 AI让他整理出你想要的”仓颉 Skill 项目涵盖文件解析、Prompt 设计、大模型调用、结果输出和异常排查全流程。通过这套方案你可以将零散的 PDF、Word、Excel 文档自动整理为 Markdown 格式的结构化内容同时保证流程可复用、可维护、可扩展。下一步建议你从以下几个方向继续深入学习Prompt 工程进阶学习少样本示例、思维链提示等方法进一步提升 AI 输出质量。文件解析增强接入 OCR 识别扫描版 PDF或使用向量数据库保存解析后的文本。Agent 化改造将仓颉 Skill 封装成大模型 Agent 的工具允许 AI 在对话过程中自主调用解析和整理功能。异步任务队列把文件处理放入消息队列配合 Web 界面实现一个完整的在线文档整理系统。RAG 知识库集成将整理后的结果作为知识片段写入向量数据库实现基于企业资料的智能问答。仓颉 Skill 的思路并不复杂但它的价值在于让文件整理从“手动复制粘贴”升级为“自动化流水线”。希望这篇文章能帮你理清整体流程并在自己的项目中快速落地。如果你在实际开发中遇到了有意思的问题欢迎在评论区交流。