用仓颉 Skill 构建 AI 资料整理工具：从 Schema 到结构化输出

做技术的人，大概都有过这种经历：桌面上堆了三年的技术方案、会议纪要、产品需求文档，文件名整理得还算整齐，但真要从中整理出一条完整的技术演进路径，得翻半天。这时候你可能会想，能不能把这些资料丢给 AI，让它直接整理成一份我想要的文档？

这个需求听起来很简单，真正动手做才发现，难点不在“AI 能不能读文件”，而在“怎么让 AI 按照你的结构输出”。因为大模型默认给你的是自然语言回复，而你要的是一份字段固定、层级清晰、可以直接二次编辑的结构化文档。这中间缺的不是模型能力，而是一个工程化的整理框架。

这篇文章要讲的，就是这种框架的一种落地方式：仓颉 Skill。简单来说，它把“资料文件”作为输入，把“整理后的结构化文档”作为输出，用 Skill 的形式把大模型的推理能力封装成可复用的自动化组件。仓颉是一个相当新的编程语言，Skill 又是 AI Agent 体系里的高频词，两者结合，看到的其实是 AI 应用开发的一个方向：确定性逻辑交给代码，非确定性理解交给模型，两者通过清晰的接口协作。

读完这篇文章，你会理解 Skill 的运行原理，能自己搭出一个最小可运行的资料整理工具，也会知道在实际项目里，哪些环节最容易出问题。

1. 这篇文章真正要解决的问题

先说一个反直觉的判断：把资料文件交给 AI 整理，卡住大多数人的不是 AI，不是模型，而是“工程组织方式”。

如果你只是想在对话框里把一份文档粘贴给大模型，让它帮你总结，那当然很方便。但“整理出你想要的”这件事，意味着输出必须满足固定格式：有标题、有摘要、有分级要点、有关键词，甚至要能直接生成 Markdown 或 Word 文件。这就不是聊天能解决的问题了，而是需要一套代码逻辑去完成：

• 读取本地文件，处理不同格式。
• 把资料内容和大模型的提示词拼装起来。
• 调用模型接口，拿回结果。
• 校验结果是否符合结构要求。
• 把结果写回指定文件。

传统自动化脚本也能做文件处理，但过去主要靠正则、模板、规则引擎。遇到格式多变的非结构化文本，规则会越写越长，最后变成一堆补丁。AI 的引入改变了这一层：结构可以交给 Schema 定义，理解可以交给模型完成，代码只负责编排和校验。这正是 Skill 模式的价值。

这篇文章主要面向三类读者：

• 正在做 AI Agent 开发，需要给 Agent 增加“文件理解与整理”能力的开发者。
• 有大量文档需要归档、清洗、汇总，想用大模型提升效率的产品、运营或技术同学。
• 对仓颉语言感兴趣，想了解这门新语言在 AI 工程方向能做什么的人。

2. 仓颉 Skill 的基础概念与核心原理

2.1 什么是仓颉语言

仓颉语言是近年来公开推出的一门新一代编程语言。从官方公开信息看，它定位为面向全场景应用开发的静态类型语言，支持多范式表达，包括面向对象、泛型、函数式等风格，设计目标是让开发者尽量用一门语言覆盖后端、移动端、桌面端和嵌入式等场景。

仓颉语言这个名字本身有很强的寓意：仓颉造字，是中文信息表达的起点；而一门编程语言本质上也是在定义一套“表达计算逻辑的符号系统”。虽然生态还在建设阶段，第三方库和资料丰富度不如 Java 或 Python，但它的静态类型和编译执行特性，让它在构建需要稳定运行、持续维护的工程化组件时，有一定优势。

我建议把仓颉语言当作“Skill 的承载语言”来理解，而不是一上来就去比较它和 Java、Go 的性能。在 AI 应用开发里，语言选型最重要的不是快，而是“写出来的模块是否边界清晰、是否容易被 Agent 调度”。仓颉语言在这方面的工程化表达值得关注。

2.2 什么是 Skill

Skill 在 AI Agent 体系里，通常指一个可被 Agent 调用、完成特定任务的“能力包”。它不同于普通函数：普通函数执行的是确定性逻辑，而 Skill 内部可能混用代码和大模型调用，对外暴露统一的输入输出契约。

举个例子。一个“会议纪要整理”Skill，输入是会议录音转写的文本文件，输出是包含“会议主题、结论、待办事项、负责人”的结构化文档。Agent 不需要知道 Skill 内部用了什么模型、怎么解析文本，它只需要知道这个 Skill 能完成什么任务、需要什么输入、返回什么结构。

这种封装方式和后端开发里的服务接口非常像。Skill 本质上就是 AI 时代的“接口”：模型负责不可控的理解和生成，代码负责可控的流程和校验，两者的交接点就是输入输出协议。

2.3 Skill 如何与大模型配合

一个“资料整理型 Skill”的核心链路可以拆成五段：

1. 文件读取：把 txt、markdown、pdf、docx 等文件转成纯文本。
2. 上下文构造：把原始内容和“输出要求”拼成提示词。
3. 模型调用：调用大模型生成整理结果。
4. 结构解析：从模型返回的文本中取出 JSON 或 Markdown。
5. 校验输出：检查字段是否完整，内容是否偏离原文，再写回文件。

这个链路里，真正依赖大模型智能的只有第二段和第三段。第一段是文件处理，第四段是文本解析，第五段是数据校验，这些都可以用确定性代码完成。这也是为什么说，不要让大模型去做所有事情，它只负责最擅长的那部分，工程可靠性会高很多。

2.4 Skill 与普通脚本的对比

对比之后能看出，Skill 不是简单地把“脚本”换个名字，而是把“人写规则”变成“人定义结构和流程，模型理解内容”。这在需求多变、文本格式不固定的场景下，维护成本会低很多。

3. 能力边界：哪些资料适合交给 AI 整理

写这篇文章时，我不想把“资料整理”说成一个万能方案。事实上，不是所有资料都适合用 AI 整理，也不是所有整理需求都能达到理想效果。

适合交给 AI 整理的场景：

• 会议纪要多轮讨论内容，整理成结论和待办。
• 技术方案文档，抽取背景、方案对比、最终结论。
• 需求描述碎片化描述，归类成功能清单和验收点。
• 多份行业资料，合并去重，提炼共性观点。
• 日常笔记、访谈记录，清洗成可发布的文章素材。

不太适合交给 AI 整理的场景：

• 需要精确计算的报表数据。
• 涉及合规审计、必须逐字保留原文的文档。
• 超大文件超过上下文窗口，且无法分块的场景。
• 对时效要求极高，不允许模型多次重试的任务。

还有一个容易被忽略的点：AI 整理出来的结果，应该被当作“初稿”，而不是“终稿”。即使输出格式完全符合要求，模型也可能在细节上写错、过度概括、或者脑补出原文没有的信息。所以 Skill 的方案里一定要保留人的复核环节，这也是它和“直接把文件喂给 AI 聊天框”最大的区别之一。

4. 环境准备与前置条件

这里给出一套通用前置条件，具体版本请以实际项目为准，下面演示的是通用思路。

需要准备的环境包括：

• Python 3.9 及以上，用于运行原型示例。如果你打算直接用仓颉语言实现，则需要安装仓颉语言工具链，具体安装方式以官方仓库 README 为准。
• Python 的 requests 库，用于调用大模型接口。
• 一个可访问的大模型服务。可以是企业已采购的模型 API，也可以是本地部署的模型，只要接口风格是 OpenAI 兼容格式即可。调用模型服务时，请使用符合法律法规和平台规范的方式。
• 资料文件建议先用 txt 或 Markdown 测试，跑通流程后再扩展 PDF、Word。

环境检查可以用下面两条命令：

python --version pip show requests

如果 requests 没有安装，执行：

pip install requests

这里真正容易踩坑的地方是：很多同学把资料整理工具部署在服务器上，但服务器环境没有外网访问模型接口的权限，或者模型服务本身使用了特殊的网络策略。建议第一步先把“本机能连通模型接口”验证通过，再开始写业务代码，否则很多问题会混在一起，排查起来很痛苦。

5. 核心流程拆解

5.1 定义输入输出 Schema

整理资料的第一个动作，不是写代码，而是确定“你想要的整理结果长什么样”。输出是一份 Markdown 文档，还是一个 JSON 对象？必须包含哪些字段？

比如一份会议纪要，可能有这样的 Schema：

{ "title": "会议标题", "date": "会议日期", "attendees": ["参会人"], "conclusions": ["会议结论"], "action_items": [ {"owner": "负责人", "task": "待办事项", "deadline": "截止时间"} ] }

Schema 是整个 Skill 的契约。模型看不懂代码，但它能看懂你写进提示词里的格式要求。越早把 Schema 定清楚，后面写提示词、解析结果、生成文件都会越顺利。

5.2 准备提示词模板

提示词模板的作用，是把“固定框架”和“可变内容”分开。固定框架告诉模型它是什么角色、输出必须满足什么格式；可变内容是每次传入的原始资料。

提示词模板不要硬编码在业务代码里。更推荐的做法是把它单独放到一个文件或配置项中，这样调整提示词时不需要重新部署程序，这个习惯在后续维护中会非常受益。

5.3 解析资料文件

这一步是最“不智能”但最容易踩坑的环节。txt 和 Markdown 文件读取比较简单，直接按 UTF-8 读文本即可。PDF 和 Word 文件则依赖额外解析库，而且 PDF 还分为文本型 PDF 和扫描版 PDF，扫描版必须走 OCR，处理复杂度会明显上升。

建议最小化验证时先用 txt 文件，跑通整个链路后再逐步增加格式支持。

5.4 调用大模型

调用环节的核心是控制不确定性。资料整理任务希望输出稳定，因此建议把 temperature 调低，比如 0.2 左右，同时在提示词里明确要求模型“只输出 JSON，不要输出多余解释”。

调用接口时必须设置超时时间。资料文件较长时，模型生成耗时可能超过默认超时，建议根据实际情况调整。

5.5 结构化输出与文件写回

模型返回的原始结果，不一定是你想要的格式。常见问题是模型在 JSON 外面多说了几句话，或者在 JSON 内部字段命名和你 Schema 不一致。因此需要一段“结果清理”代码：从模型输出中截取 JSON 片段、解析成字典、再检查必填字段。

最后一步才是写文件。到此，一个最小可用的资料整理 Skill 就算跑通了。

6. 完整示例与代码实现

6.1 最小可运行的 Python 版资料整理 Skill

下面用 Python 实现一个最小可运行的示例。它读取一个本地文本文件，调用 OpenAI 兼容接口的大模型，把整理结果写成 Markdown 文件。

# 文件路径：skill_core/run.py """最小资料整理 Skill：读取本地文件 -> 调用大模型 -> 输出整理后的 Markdown 文件。""" import json import os import requests def read_file(path: str) -> str: """读取本地文本文件。""" with open(path, "r", encoding="utf-8") as f: return f.read() def build_prompt(content: str, output_schema: str) -> str: """构造提示词：把原始资料和输出格式要求拼在一起。""" return f"""你是一名资料整理助手。 请阅读下面的原始资料，按指定格式整理后输出。 输出格式要求（只输出 JSON，不要输出多余解释）： {output_schema} 原始资料： {content[:6000]} """ def call_llm(prompt: str, api_url: str, api_key: str, model: str) -> str: """调用 OpenAI 兼容接口的大模型。""" resp = requests.post( api_url, headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", }, json={ "model": model, "messages": [{"role": "user", "content": prompt}], "temperature": 0.2, }, timeout=60, ) resp.raise_for_status() data = resp.json() return data["choices"][0]["message"]["content"] def parse_json_response(text: str) -> dict: """从模型输出中裁剪出 JSON 并解析。""" start = text.find("{") end = text.rfind("}") + 1 if start == -1 or end == 0: raise ValueError("模型输出中找不到 JSON 结构") return json.loads(text[start:end]) def main(): api_url = os.getenv("LLM_API_URL") api_key = os.getenv("LLM_API_KEY") model = os.getenv("LLM_MODEL", "default-model") input_path = os.getenv("INPUT_FILE", "./raw_notes.txt") output_path = os.getenv("OUTPUT_FILE", "./output.md") schema = '''{ "title": "资料标题", "summary": "一段中文摘要，不超过200字", "keywords": ["关键词1", "关键词2"], "structured_points": [ {"heading": "要点标题", "content": "要点内容"} ] }''' content = read_file(input_path) prompt = build_prompt(content, schema) raw_output = call_llm(prompt, api_url, api_key, model) result = parse_json_response(raw_output) with open(output_path, "w", encoding="utf-8") as f: f.write(f"# {result['title']}\n\n") f.write(f"> {result['summary']}\n\n") f.write("## 关键词\n\n") f.write(", ".join(result["keywords"]) + "\n\n") f.write("## 整理要点\n\n") for point in result["structured_points"]: f.write(f"### {point['heading']}\n\n") f.write(point["content"] + "\n\n") print(f"Done: {output_path}") if __name__ == "__main__": main()

这段代码的核心逻辑有三点：

• build_prompt 把输出 Schema 直接写进提示词，这是让模型遵循结构的关键。
• parse_json_response 没有直接使用 json.loads，而是先截取第一个“{”到最后一个“}”之间的内容，因为模型经常会在 JSON 外面输出解释文字。
• 全程使用环境变量配置 API 地址、密钥、模型名和文件路径，避免把敏感信息写死在代码里。

6.2 仓颉语言侧 Skill 编排示例

如果你选择了仓颉语言作为 Skill 的实现语言，重点其实不在“用仓颉写文件读写”，而在如何用静态类型语言把 Skill 的输入、输出和管理边界定义清楚。下面是一段示意结构，用来表达 Skill 的组织思路，具体编译器 API 请以仓颉官方开发文档为准。

// 文件路径：skill/FileTool.cj // 注意：以下代码为 Skill 模块的组织示意，运行时请替换为仓颉官方标准库 API。 public struct FileTask { var inputPath: String var outputPath: String var schema: String } public struct SkillResult { var success: Bool var message: String var outputPath: String } public func readFile(path: String): String { // 通过仓颉标准库读取文本文件内容 return "" } public func parseContent(content: String): Array<String> { // 按段落切分，为构造提示词做准备 return content.split("\n") } public func writeMarkdown(path: String, markdown: String) { // 通过仓颉标准库写入文件 }

这段代码的重点不是实现细节，而是类型定义。FileTask 描述任务输入，SkillResult 描述任务输出，函数签名明确了“读取、切分、写回”三个动作。仓颉语言的静态类型在这里的价值是：十几个人协作维护几十个 Skill 时，函数签名和结构体本身就是文档，编译器能帮你拦住大部分低级错误。这正是它相比动态脚本语言的优势。

6.3 Skill 配置文件示例

“资料整理成什么样”这件事，最好用配置来表达。下面是一个 skill.yaml 的示例配置，用来声明 Skill 的输入、输出和模型参数。

# 文件路径：skill.yaml name: document-organizer description: 读取资料文件，按指定结构整理为 Markdown version: 0.1.0 input: - name: input_file type: string required: true description: 待整理的本地文件路径 - name: schema type: object required: false description: 自定义输出结构，不传则使用默认结构 model: provider: openai-compatible model_name: ${LLM_MODEL} temperature: 0.2 timeout_seconds: 60 output: format: markdown target: ${OUTPUT_FILE}

配置文件的价值在于：同样的代码，只需要更换 schema 和提示词模板，就能整理出完全不同风格的文档。它把一个“写死的脚本”变成了“可配置的能力”。

6.4 运行命令与依赖安装

安装依赖：

pip install requests

配置环境变量并运行：

export LLM_API_URL="https://your-llm-endpoint/v1/chat/completions" export LLM_API_KEY="your-api-key" export LLM_MODEL="your-model-name" export INPUT_FILE="./raw_notes.txt" export OUTPUT_FILE="./output.md" python skill_core/run.py

注意：这里的 LLM_API_URL、LLM_API_KEY、LLM_MODEL 需要替换成你自己可用的模型服务信息。不同厂商的接口风格可能略有差异，以实际接口文档为准。

7. 运行结果与效果验证

为了验证，可以先准备一个简单的输入文件。

# 文件路径：raw_notes.txt 今天下午讨论了 v2.0 版本的首页改版。 参会人员：小王、小李、老张。 结论： 1. 新版首页要突出检索功能，弱化广告位。 2. 移动端适配优先级提升到 P0。 3. 下周二前完成原型评审。 待办： - 小李负责输出交互原型，下周一给初稿。 - 老张联系数据分析组，提供当前首页漏斗数据。

运行上面的 Python 示例后，预期输出是一个 Markdown 文件，内容类似：

# 首页改版 v2.0 需求对齐会 > 本次会议明确了 v2.0 首页改版的方向：突出检索功能，弱化广告位；移动端适配提升到 P0；并确定了原型评审时间和数据支持方式。 ## 关键词 首页改版, 检索功能, 移动端适配, 原型评审, 数据分析 ## 整理要点 ### 改版方向 新版首页要突出检索功能，弱化广告位。 ### 优先级调整 移动端适配优先级提升到 P0。 ### 下一步安排 下周二前完成原型评审；小李负责交互原型，老张负责协调数据分析。

怎么判断整理成功？可以从三个维度看：

• 结构完整：title、summary、keywords、structured_points 都存在。
• 内容忠实：整理结果里的信息都能在原文里找到，没有模型自己编造的细节。
• 文件可用：生成的 Markdown 能直接复制到笔记软件或文档工具中二次编辑。

如果运行失败，第一步先看终端打印的异常类型。是网络不通，可以去检查 LLM_API_URL；是密钥无效，去看 LLM_API_KEY；是 JSON 解析失败，说明模型输出格式偏离了要求，需要调整提示词或改用更强的模型。

8. 常见问题与排查思路

这些问题是资料整理类 Skill 最常见的几种。遇到问题时，不要急着改代码，先把“模型原始输出”打出来看。很多时候问题出在提示词，而不是代码逻辑。

9. 最佳实践与工程建议

9.1 Schema 设计要先行

先想清楚“整理后文档的结构”，再写代码。Schema 就是你和模型之间的契约。你给模型的示例越具体，它输出的内容越稳定。一份输出结构里，建议同时给出“字段说明”和“完整示例”，这对模型的理解帮助最大。

9.2 提示词模板与代码分离

把提示词模板放到独立文件或配置项中，不要让提示词散落在业务逻辑里。原因很简单：提示词的改动频率远高于代码。如果每次调整提示词都要重新发布程序，这个 Skill 很快会变得难以维护。

9.3 控制大模型幻觉

幻觉是整理类任务里最需要警惕的问题。控制手段可以分三层：

• 提示词层面：要求模型只使用原文信息，不要补充常识。
• 解析层面：对输出做关键词匹配，检查关键结论是否能在原文中找到对应片段。
• 流程层面：对高风险任务，保留“人工复核”步骤，不要让模型输出直接落地。

9.4 文件解析顺序

先支持纯文本，再扩展其他格式。很多团队一上来就想处理 PDF，结果被版式解析和 OCR 问题拖住，连核心链路都没跑通。建议先搞定 txt，再考虑 Markdown、Word、PDF。

9.5 安全与隐私边界

涉及敏感、隐私或未公开资料时，要确认是否符合公司规定和法律法规，不要随意把涉密文件传到未经授权的第三方模型服务。企业环境里，优先使用已通过合规审批的模型服务或私有化部署方案。

9.6 成本与性能优化

大模型调用是有成本的。对内容相似的重复任务，可以按文件哈希做结果缓存；对超长文档，先让模型生成摘要，再对摘要做二次整理；对批量任务，考虑加入队列和限流，避免在高峰时段挤占资源。

9.7 从脚本到 Agent Skill 的演进

当你跑通了单个资料整理脚本，可以再往前走一步：把它封装成 Agent 可调用的 Skill 并注册到 Agent 的能力列表里。这样，用户对 Agent 说“帮我整理一下这份会议纪要”，Agent 会自动判断该调用哪个 Skill、传入什么参数、返回什么结果。这正是 AI Agent 开发里很关键的一环：Agent 提供规划和执行框架，Skill 提供真实可用的工具能力，两边通过统一接口协作。

这里的实践点在于：不要把一个复杂的整理需求做成一个巨大的 Skill，而是拆成“文本读取”“内容清洗”“结构化整理”“格式导出”等更小的能力单元，让 Agent 自行组合。小 Skill 更容易测试和复用，大 Skill 则很难维护。

10. 总结与后续学习方向

把“把资料文件交给 AI”这件事拆开，实际上五段链路：文件解析、上下文构造、模型调用、结构校验、文件输出。前端两段考验工程功底，中间一段依赖模型能力，后两段决定结果稳定性。所谓仓颉 Skill，核心就是用一门工程型语言，把这五段链路封装成可复用的能力组件。

这篇文章里最想强调的判断是：AI 资料整理的工程重点，不在模型选择，而在流程设计。模型负责理解和生成，代码负责定义结构和校验结果，两者必须通过清晰的 Schema 和提示词模板衔接。没有这套工程框架，再强的模型也只能停留在“聊天能总结，落地不能用”的状态。

对于想继续深入的同学，我建议按这个顺序学习：先跑通本文的 Python 最小示例，理解 Skill 的执行链路；再尝试用仓颉语言重写一遍，体会静态类型语言对 Skill 边界的约束力；接下来学习 AI Agent 开发，了解 Skill 如何被 Agent 注册、调用和编排；最后进阶到模型部署和性能优化，把成本、时延、稳定性这几个工程指标真正管起来。

真正高效的资料整理工具，不是把所有逻辑都交给大模型，而是把文件解析、结构定义、结果校验这些确定性工作做扎实，让模型只做最擅长的理解和生成。这也是我把它称为 Skill 的另一个原因：它不是一次性的脚本，而是可以沉淀、复用、组合的能力单元。建议你先从一个小目录、三个文件开始跑通闭环，再逐步扩展。