企业官网建设流程全解析

在 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 可以拆解为以下三个层次：

这种分层设计的好处非常明显：即使之后更换不同的 AI 模型，或者新增一种文件格式，只需要修改对应的模块，而不需要重写整套流程。这也是它在 AI 应用开发中最值得借鉴的地方。

1.3 常见应用场景

只要涉及“资料文件 + 整理输出”的需求，仓颉 Skill 都能派上用场。常见场景包括：

• 文档摘要生成：批量读取多份文档，生成每份文档的摘要、关键词和核心结论。
• 会议纪要转任务清单：从会议记录中提取待办事项、负责人和截止时间。
• 报表数据抽取：从 Excel 或 CSV 中抽取指定字段，转换为新的表格结构。
• 知识库构建：把散落的资料文件转换成统一的 Markdown 知识条目，便于后续检索。
• 简历筛选与候选人信息摘要：从多份 PDF 简历中抽取姓名、工作年限、技能标签。

无论你的原始资料是哪种格式，思路都是一样的：先用解析层把内容变成纯文本，再用指令层让 AI 理解任务，最后用输出层把结果标准化。

2. 环境准备与版本说明：搭建可运行的 Skill 基础环境

仓颉 Skill 的实现并不依赖某个特定的平台，只要你能够调用大模型 API，就能把它跑起来。为了让后面的实战案例可复制，我们需要先搭建一个最小可运行的环境。

2.1 运行环境清单

本文的示例以 Python 为主，具体环境如下：

如果你使用的是国内大模型平台，比如通义千问、智谱 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 的处理流程可以拆成以下步骤：

1. 扫描文件：读取指定目录下所有符合条件的文件。
2. 解析内容：针对不同文件格式，调用对应的解析器提取纯文本。
3. 构造 Prompt：根据用户的任务描述，生成结构化的提示词。
4. 调用大模型：将文本和提示词发送给大模型 API。
5. 解析输出：从大模型的回复中提取目标内容，并格式化为 Markdown 或 JSON。
6. 写入文件：把整理结果保存到输出目录。

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_name=None) text_list = [] for sheet_name, df_sheet in df.items(): text_list.append(f"工作表：{sheet_name}") text_list.append(df_sheet.to_string(index=False)) 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 └── 研发排期表.xlsx

4.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", encoding="utf-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", encoding="utf-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_description=task_description, document_text=document_text[:12000] ) def call_llm(client: OpenAI, model: str, prompt: str) -> str: response = client.chat.completions.create( model=model, messages=[ {"role": "system", "content": "你是一个严谨的资料整理助手。"}, {"role": "user", "content": prompt} ], temperature=0.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_key=config["api_key"], base_url=config["base_url"]) docs_dir = "docs" output_dir = "output" os.makedirs(output_dir, exist_ok=True) 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( client=client, model=config["model"], task_description=config["task_description"], file_path=file_path ) output_name = re.sub(r"\.[^.]+$", "", filename) + "_整理结果.md" output_path = os.path.join(output_dir, output_name) with open(output_path, "w", encoding="utf-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 请求超时或超出上下文窗口。
• temperature=0.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 表格” | | 文件路径包含中文乱码 | 操作系统编码问题 | 在代码开头设置环境变量 `PYTHONIOENCODING=utf-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_workers=5) 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 格式的结构化内容，同时保证流程可复用、可维护、可扩展。

下一步，建议你从以下几个方向继续深入学习：

1. Prompt 工程进阶：学习少样本示例、思维链提示等方法，进一步提升 AI 输出质量。
2. 文件解析增强：接入 OCR 识别扫描版 PDF，或使用向量数据库保存解析后的文本。
3. Agent 化改造：将仓颉 Skill 封装成大模型 Agent 的工具，允许 AI 在对话过程中自主调用解析和整理功能。
4. 异步任务队列：把文件处理放入消息队列，配合 Web 界面，实现一个完整的在线文档整理系统。
5. RAG 知识库集成：将整理后的结果作为知识片段写入向量数据库，实现基于企业资料的智能问答。

仓颉 Skill 的思路并不复杂，但它的价值在于让文件整理从“手动复制粘贴”升级为“自动化流水线”。希望这篇文章能帮你理清整体流程，并在自己的项目中快速落地。如果你在实际开发中遇到了有意思的问题，欢迎在评论区交流。