做技术的人大概都有过这种经历桌面上堆了三年的技术方案、会议纪要、产品需求文档文件名整理得还算整齐但真要从中整理出一条完整的技术演进路径得翻半天。这时候你可能会想能不能把这些资料丢给 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 什么是 SkillSkill 在 AI Agent 体系里通常指一个可被 Agent 调用、完成特定任务的“能力包”。它不同于普通函数普通函数执行的是确定性逻辑而 Skill 内部可能混用代码和大模型调用对外暴露统一的输入输出契约。举个例子。一个“会议纪要整理”Skill输入是会议录音转写的文本文件输出是包含“会议主题、结论、待办事项、负责人”的结构化文档。Agent 不需要知道 Skill 内部用了什么模型、怎么解析文本它只需要知道这个 Skill 能完成什么任务、需要什么输入、返回什么结构。这种封装方式和后端开发里的服务接口非常像。Skill 本质上就是 AI 时代的“接口”模型负责不可控的理解和生成代码负责可控的流程和校验两者的交接点就是输入输出协议。2.3 Skill 如何与大模型配合一个“资料整理型 Skill”的核心链路可以拆成五段文件读取把 txt、markdown、pdf、docx 等文件转成纯文本。上下文构造把原始内容和“输出要求”拼成提示词。模型调用调用大模型生成整理结果。结构解析从模型返回的文本中取出 JSON 或 Markdown。校验输出检查字段是否完整内容是否偏离原文再写回文件。这个链路里真正依赖大模型智能的只有第二段和第三段。第一段是文件处理第四段是文本解析第五段是数据校验这些都可以用确定性代码完成。这也是为什么说不要让大模型去做所有事情它只负责最擅长的那部分工程可靠性会高很多。2.4 Skill 与普通脚本的对比维度普通文件处理脚本仓颉 Skill输入理解靠规则和正则匹配靠大模型语义理解输出格式代码写死通过 Schema 动态指定扩展能力每个需求改代码可被 Agent 动态调用出错处理通常直接失败可让模型重新生成或人工复核复用方式工具函数级复用能力包级复用维护边界逻辑容易越写越杂输入、处理、输出结构清晰对比之后能看出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, encodingutf-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: fBearer {api_key}, Content-Type: application/json, }, json{ model: model, messages: [{role: user, content: prompt}], temperature: 0.2, }, timeout60, ) 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, encodingutf-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(fDone: {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): ArrayString { // 按段落切分为构造提示词做准备 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_URLhttps://your-llm-endpoint/v1/chat/completions export LLM_API_KEYyour-api-key export LLM_MODELyour-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. 常见问题与排查思路问题现象可能原因排查方式解决方案模型输出包含额外文本JSON 解析失败模型没有严格遵守输出格式打印模型原始输出看是否有解释性文字先裁剪 JSON 边界再解析提示词里明确“只输出 JSON”整理结果里出现了原文没有的内容模型幻觉过度补充信息将结果与原文对照提示词要求“只能基于原文”必要时增加人工复核环节PDF 读取出现乱码扫描版 PDF 缺少文本层查看解析后的文本内容使用 OCR 工具或先转成图片再识别资料内容太长超出模型上下文窗口单次输入超过限制查看模型接口返回的错误码分块整理先把长文本切成多个片段分别处理再合并结果接口请求超时文件太大或模型生成太慢查看日志中的耗时调大 timeout对大文件做摘要预处理本地模型输出不稳定每次结果差异大temperature 过高或模型能力不足多次运行观察输出调低 temperature增加重试逻辑换更大模型输出字段和 Schema 不一致提示词结构说明不清楚检查模型返回的 JSON 字段给模型提供一个完整的 JSON 示例而不仅是字段描述这些问题是资料整理类 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 的另一个原因它不是一次性的脚本而是可以沉淀、复用、组合的能力单元。建议你先从一个小目录、三个文件开始跑通闭环再逐步扩展。