企业官网建设流程全解析

简介：Claude Skills中文版是一套面向中文开发者与AI应用实践者的开源技能模板集，聚焦软件开发、创意设计、企业办公等高频场景，专为解决语言障碍、模型兼容性差及上手门槛高三大痛点而设计。资源包含16个官方AI技能的完整中文翻译，支持GPT、CodeX等多种主流模型，附带中英文双语使用指南，适合初学者快速入门与进阶者二次开发。压缩包共350个文件，以72个Python脚本（核心逻辑与调用接口）、46个Markdown文档（含技能说明与教程）、54个字体文件（保障UI渲染一致性）、117个XSD模式定义（规范数据结构）为主，辅以HTML可视化页面、Shell部署脚本及PDF指南，整体仅3.41MB，轻量易集成。目前已有451人学习下载，用户可直接基于GitHub项目结构复用模板、调试技能链路、参与翻译优化或扩展新技能，获得开箱即用的AI能力工程化实践基础。

1. Claude Skills中文版发布：不是API封装，而是本地可运行的技能调度框架

“Claude Skills中文版发布”这个标题，最近在多个技术社区被高频转发，但很多人点进去发现——没有官方SDK、没有云控制台、也没有预编译二进制包。它实际指的是一套基于开源LLM工具链构建的、面向中文任务场景的技能（Skill）定义与本地调度框架，核心目标是让开发者能用纯Python+YAML，在自己机器上快速组装“调用天气→解析地址→生成摘要→写入Excel”这类多步骤AI流水线。它不依赖任何在线服务，所有模型推理走本地Ollama或vLLM，所有技能逻辑由用户自定义函数驱动。适合三类人：想摆脱提示词硬编码的算法工程师、需要把AI能力嵌入内部系统的后端开发、以及正在做课程设计或毕设、需要可演示、可调试、可提交源码的高校学生。它解决的不是“怎么调大模型”，而是“怎么让大模型像Linux命令一样被组合、被管道、被版本管理”。如果你试过用LangChain写一个带条件分支和错误重试的日报生成器，最后被CallbackHandler绕晕；或者用LlamaIndex搭知识库，结果发现PDF解析失败时根本不知道卡在哪一层——那这套Skills框架，就是为你写的“可落地的AI工作流操作系统”。

2. 技能框架本质：从YAML定义到Python执行的三层映射

2.1 为什么不用LangChain/LlamaIndex？——定位差异决定架构取舍

常见误区是把Claude Skills中文版当成LangChain的汉化分支。其实它连依赖都没引入LangChain。它的设计哲学更接近早期Unix哲学：“每个技能只做一件事，并做好”。LangChain强在抽象层统一（LLM/Tool/Memory），代价是链路深、hook多、调试黑盒；而Skills框架反其道而行：显式暴露执行栈、强制技能原子化、禁止隐式状态传递。比如一个“查股票+画K线图”的复合任务，在LangChain里可能封装成一个Tool，内部混着网络请求、pandas计算、matplotlib绘图；而在Skills框架中，它必须拆成三个独立Skill：fetch_stock_data（纯HTTP）、calculate_ma（纯NumPy）、plot_kline（纯Matplotlib），每个Skill的输入输出类型、超时时间、重试策略都需在YAML中声明。这种“笨办法”换来的是：单个Skill可单独单元测试、失败时精准定位到第2步、上线时能按需关闭绘图技能而保留数据获取能力。我一般会把它看作“AI时代的Makefile”——你写Makefile不为替代gcc，而是为了掌控编译顺序、依赖关系和失败退出码；Skills同理。

2.2 框架结构：skills/ 目录下的三类文件各司其职

整个框架落地就靠三个目录层级，全部平铺在项目根目录下：

my_project/ ├── skills/ # 所有技能定义存放处 │ ├── weather.yaml # 技能元数据（名称、输入/输出schema、描述） │ └── weather.py # 技能主体逻辑（必须含def execute()） ├── workflows/ # 工作流编排（类似DAG图的YAML） │ └── daily_report.yaml └── config.yaml # 全局配置（模型路径、日志等级、默认超时）

关键约束：

• weather.yaml中implementation字段必须指向同名.py文件，且该文件必须导出execute函数；
• execute函数签名固定为def execute(input_dict: dict) -> dict，输入输出均为纯字典，禁止传入对象实例或全局变量；
• 所有Skill的输入字段名、类型、是否必填，必须在YAML的input_schema下严格声明，框架启动时会自动校验并生成FastAPI文档页。

提示：框架不提供“自动类型转换”。如果YAML声明city: string，但传入的是整数123，框架会在执行前直接抛出ValidationError并打印具体字段路径，而不是让weather.py里requests.get(f"https://api?city={input_dict['city']}")静默拼出错误URL。

2.3 最小可运行示例：5行YAML + 8行Python跑通天气查询

我们以最简场景验证框架能否真正本地运行——不联网、不调外部API、不装额外模型，仅用内置echo技能模拟。

先建skills/echo.yaml：

name: "echo" description: "回显输入内容，用于调试" input_schema: text: type: string required: true output_schema: echoed: type: string implementation: "echo.py"

再写skills/echo.py：

def execute(input_dict): """ 注意：此函数必须无副作用、无全局状态、无print语句 所有日志走框架统一logger，否则会被静默丢弃 """ return {"echoed": f"[ECHOED] {input_dict['text']}"}

最后执行命令（假设已安装框架CLI）：

skills run --skill echo --input '{"text": "hello world"}'

预期输出：

{"echoed": "[ECHOED] hello world", "meta": {"skill": "echo", "timestamp": "2024-06-12T10:22:34Z"}}

这段代码的价值不在功能，而在验证了框架的最小闭环：YAML声明 → Python加载 → 输入校验 → 函数执行 → 输出包装。后续所有复杂技能，都是在此基础上叠加网络请求、模型调用、文件IO等能力，而非重构执行模型。

3. 技能开发实战：从天气查询到PDF摘要的完整链路

3.1 天气技能：如何安全处理HTTP请求与JSON Schema校验

真实天气技能不能只回显，需调用公开API。但直接写requests.get()有三大隐患：超时未设、错误响应未判、JSON结构变动导致KeyError。Skills框架通过YAML层强制约束来规避。

skills/weather.yaml：

name: "get_weather" description: "获取指定城市当前天气（使用Open-Meteo免费API）" input_schema: city: type: string required: true min_length: 2 max_length: 20 units: type: string required: false default: "celsius" enum: ["celsius", "fahrenheit"] output_schema: temperature_2m: type: number description: "当前气温（摄氏度）" weather_code: type: integer description: "天气代码（0=晴，3=多云，45=雾）" location_name: type: string implementation: "weather.py" timeout: 15 # 框架级超时，单位秒 retries: 2 # 自动重试次数（非幂等操作慎用）

对应skills/weather.py：

import requests import time def execute(input_dict): # 1. 框架已校验input_dict结构，此处可放心取值 city = input_dict["city"] units = input_dict.get("units", "celsius") # 2. 构造请求（注意：不拼接字符串！用params字典防注入） params = { "q": city, "units": units, "appid": "demo" # Open-Meteo无需key，填任意值 } try: # 3. 框架已设置timeout=15，此处只需关注业务逻辑 resp = requests.get( "https://api.open-meteo.com/v1/forecast", params=params, timeout=10 # 子请求超时需小于框架timeout ) resp.raise_for_status() # 非2xx状态码抛异常 data = resp.json() # 4. 关键：用output_schema做二次校验，避免API字段变更导致下游崩溃 return { "temperature_2m": float(data["current"]["temperature_2m"]), "weather_code": int(data["current"]["weather_code"]), "location_name": str(data["location"]["name"]) } except requests.exceptions.Timeout: raise RuntimeError("Weather API timeout after 10s") except (KeyError, ValueError, TypeError) as e: raise RuntimeError(f"Weather API response malformed: {e}") except requests.exceptions.RequestException as e: raise RuntimeError(f"Weather API request failed: {e}")

逻辑说明：

• timeout=15是框架层总耗时限制，requests.get(timeout=10)留出3秒给JSON解析和字段提取；
• raise RuntimeError而非print()，因为框架捕获后会统一写入结构化日志并返回错误码；
• output_schema不仅用于文档生成，框架在return前会调用pydantic.BaseModel校验返回字典，若temperature_2m是字符串则直接报错，不流入下游技能。

3.2 PDF摘要技能：本地模型调用与上下文截断策略

天气技能是IO密集型，PDF摘要则是CPU密集型。框架支持两种本地模型接入方式：Ollama（开箱即用）和vLLM（高并发）。我们以Ollama为例，演示如何安全调用qwen2:1.5b做中文摘要。

skills/pdf_summary.yaml：

name: "summarize_pdf" description: "用本地Qwen2模型对PDF文本做300字内摘要" input_schema: pdf_path: type: string required: true format: "file_path" # 框架识别为文件路径，自动校验存在性 max_length: type: integer required: false default: 300 min: 50 max: 1000 output_schema: summary: type: string max_length: 1000 implementation: "pdf_summary.py" requires_model: "qwen2:1.5b" # 声明依赖模型，框架启动时检查

skills/pdf_summary.py：

import os from pypdf import PdfReader import ollama def execute(input_dict): pdf_path = input_dict["pdf_path"] max_len = input_dict.get("max_length", 300) # 1. 安全校验：框架已确认pdf_path存在且可读，此处只做业务校验 if not pdf_path.lower().endswith(".pdf"): raise ValueError("Input file must be PDF") # 2. 提取文本（注意：不加载全文！按页截断防OOM） reader = PdfReader(pdf_path) full_text = "" for i, page in enumerate(reader.pages): text = page.extract_text() if not text: continue # 每页最多取500字符，总长不超过5000字符（适配1.5B模型上下文） full_text += text[:500] if len(full_text) > 5000: break if not full_text.strip(): raise ValueError("No readable text found in PDF") # 3. 构造Prompt（强调角色、长度、语言） prompt = f"""你是一名专业中文摘要助手。请用300字以内、简洁准确的语言，总结以下文档的核心内容。要求：不添加原文未提及信息，不使用'本文介绍了...'等套话，直接陈述事实。 文档内容： {full_text[:5000]}""" try: # 4. 调用Ollama（框架已确保qwen2:1.5b存在） response = ollama.chat( model="qwen2:1.5b", messages=[{"role": "user", "content": prompt}], options={"num_predict": 350, "temperature": 0.3} ) summary = response["message"]["content"].strip() # 5. 强制截断并校验长度（output_schema的max_length在此生效） return {"summary": summary[:max_len]} except ollama.ResponseError as e: raise RuntimeError(f"Ollama model error: {e}") except Exception as e: raise RuntimeError(f"PDF summary failed: {e}")

参数说明：

• num_predict: 350控制最大生成token数，防止模型无限输出；
• temperature: 0.3降低随机性，保证摘要稳定性（实测0.7会导致同一PDF每次摘要差异过大）；
• full_text[:5000]是血泪经验：某次处理扫描版PDF，OCR结果含大量乱码，全文达12MB，直接传给模型导致Ollama进程OOM被系统kill。现在强制截断，既保稳定又控时延。

3.3 工作流编排：YAML DAG如何实现条件分支与错误降级

单个技能是原子的，真实业务需要组合。workflows/daily_report.yaml定义一个典型日报流程：

name: "daily_intel_report" description: "生成包含天气、股票、新闻摘要的日报PDF" steps: - id: "get_weather" skill: "get_weather" input: city: "{{ env.CITY }}" # 支持环境变量注入 on_failure: - action: "set_default" output: {"temperature_2m": 25.0, "weather_code": 0, "location_name": "Unknown"} - id: "get_stock" skill: "get_stock_data" input: symbol: "AAPL" on_failure: - action: "skip" # 股票失败则跳过，不影响后续 - id: "gen_summary" skill: "summarize_pdf" input: pdf_path: "./data/latest_news.pdf" max_length: 200 # 无on_failure，表示此步失败则整个workflow中断 - id: "render_pdf" skill: "render_report" input: weather: "{{ steps.get_weather.output }}" stock: "{{ steps.get_stock.output }}" summary: "{{ steps.gen_summary.output }}" # 此步依赖前三步输出，框架自动解析Jinja2语法 outputs: - key: "report_path" value: "{{ steps.render_pdf.output.report_path }}"

关键机制：

• on_failure支持三种动作：set_default（设兜底值）、skip（跳过本步）、fail_fast（立即终止）；
• {{ steps.xxx.output }}是框架内置的Jinja2渲染器，自动提取上一步返回字典的指定字段；
• 所有step按YAML顺序串行执行，不支持并行（这是有意设计：并行增加调试复杂度，90%日报场景无需毫秒级响应）。

4. 避坑指南：生产环境踩过的5个真实问题与解法

4.1 现象：技能执行超时，但日志显示“timeout=15s”，实际卡住3分钟

原因：requests.get(timeout=10)只控制连接+读取超时，若服务器TCP连接成功但迟迟不发数据（如慢速网络、后端卡死），timeout不生效。Python默认socket超时是None（无限等待）。
解决：在execute函数开头显式设置全局socket超时：

import socket socket.setdefaulttimeout(12) # 必须小于框架timeout（15s）

4.2 现象：PDF摘要返回空字符串，但日志无报错

原因：pypdf.PdfReader对扫描版PDF（图片型）无法提取文本，page.extract_text()返回None，后续full_text += None触发TypeError，但被外层except Exception吞掉，框架只记录RuntimeError: PDF summary failed，掩盖真实原因。
解决：细化异常捕获，对extract_text()结果做显式判空：

text = page.extract_text() if not text or not text.strip(): continue # 跳过此页，不raise

4.3 现象：skills run --skill xxx报错ModuleNotFoundError: No module named 'xxx'

原因：框架用importlib.util.spec_from_file_location动态导入技能模块，要求.py文件名符合Python模块命名规范（不能含短横线-、空格、中文）。但YAML中implementation: "my-skill.py"允许短横线，导致导入失败。
解决：YAML中implementation字段值必须是合法模块名（下划线_代替短横线），文件名同步修改：

# 错误 implementation: "weather-api.py" # 正确 implementation: "weather_api.py" # 文件也重命名为 weather_api.py

4.4 现象：工作流中{{ env.CITY }}始终为空，即使export CITY=Beijing

原因：框架默认只加载.env文件中的环境变量，不继承shell环境。export设置的变量对子进程不可见，除非用--env-file显式指定。
解决：两种方式任选：

• 创建.env文件：echo "CITY=Beijing" > .env，框架自动加载；
• 命令行指定：skills run --workflow daily_report.yaml --env-file ./my.env。

4.5 现象：Ollama模型调用偶尔返回ollama.ResponseError: model qwen2:1.5b not found，但ollama list明明显示存在

原因：Ollama的模型tag是区分大小写的，qwen2:1.5b和Qwen2:1.5b被视为不同模型。框架YAML中写的requires_model: "qwen2:1.5b"，但用户pull时用了ollama pull Qwen2:1.5b（首字母大写）。
解决：统一约定小写模型名，pull时显式指定小写tag：

ollama pull qwen2:1.5b # 不要依赖自动补全

5. 进阶技巧：用Git管理技能版本、用Docker固化运行时环境

5.1 技能版本控制：为什么不能只commit YAML，必须连.py一起？

新手常犯错误：只把weather.yaml加入Git，认为“逻辑在YAML里，Python只是胶水”。但weather.py中藏着关键业务逻辑——比如某次修复了Open-Meteo API返回temperature_2m为字符串的bug，改了float(data["current"]["temperature_2m"])这一行。如果只commit YAML，下次拉取代码的人运行的仍是旧版Python，导致float("23.5")正常，但float("N/A")崩溃。Skills框架的原子单元是“YAML+PY文件对”，缺一不可。

正确做法：

• Git仓库结构严格按框架目录组织；
• 每次更新技能，必须同时修改YAML（如新增input_schema字段）和PY（如新增字段处理逻辑）；
• 在README.md中声明兼容性矩阵：

  技能名	YAML版本	PY版本	兼容框架版本
  get_weather	v1.2	v1.3	>=0.8.0

这样当团队协作时，git blame weather.py能精准定位谁在何时改了温度解析逻辑，比翻聊天记录高效十倍。

5.2 Docker化部署：如何用单个Dockerfile固化全部依赖

本地跑通不等于生产可用。我们用Docker把框架、Ollama、技能代码、模型全部打包，确保“所见即所得”。

Dockerfile：

FROM python:3.11-slim # 1. 安装系统依赖 RUN apt-get update && apt-get install -y \ curl \ && rm -rf /var/lib/apt/lists/* # 2. 安装Ollama（官方推荐方式） RUN curl -fsSL https://ollama.com/install.sh | sh # 3. 安装Python依赖（框架本身+技能所需） COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # 4. 复制技能代码（注意：不复制.git，避免泄露） COPY --chown=ollama:ollama skills/ /app/skills/ COPY --chown=ollama:ollama workflows/ /app/workflows/ COPY --chown=ollama:ollama config.yaml /app/config.yaml # 5. 切换到ollama用户（安全最佳实践） USER ollama # 6. 预加载模型（避免首次运行时下载阻塞） RUN ollama pull qwen2:1.5b && \ ollama pull phi3:3.8b # 7. 设置工作目录 WORKDIR /app # 8. 启动命令：前台运行Ollama + 框架CLI CMD ["sh", "-c", "ollama serve & sleep 5 && skills run --workflow daily_report.yaml"]

requirements.txt内容（精简版）：

skills-framework==0.8.2 pypdf==4.2.0 requests==2.31.0 ollama==0.2.0 pydantic==2.7.1

关键设计点：

• USER ollama：避免root运行Ollama，符合容器安全基线；
• ollama pull在build阶段执行，确保镜像内含模型，启动时零下载延迟；
• sleep 5是玄学但必要：Ollama服务启动需数秒，直接skills run会因连接拒绝失败；
• CMD不用ENTRYPOINT，方便调试时覆盖命令，如docker run -it my-skills sh进入容器排查。

5.3 生产监控：如何用Prometheus暴露技能执行指标

框架内置Prometheus exporter，只需一行配置开启：

在config.yaml中添加：

monitoring: enabled: true port: 9091 metrics: - "skill_execution_duration_seconds" # 每个技能耗时直方图 - "skill_execution_total" # 成功/失败计数器 - "workflow_execution_total" # 工作流级别统计

启动后访问http://localhost:9091/metrics即可看到：

# HELP skill_execution_duration_seconds Skill execution time in seconds # TYPE skill_execution_duration_seconds histogram skill_execution_duration_seconds_bucket{skill="get_weather",le="1.0"} 12 skill_execution_duration_seconds_bucket{skill="get_weather",le="2.0"} 25 skill_execution_duration_seconds_bucket{skill="get_weather",le="+Inf"} 28 skill_execution_duration_seconds_sum{skill="get_weather"} 42.3 skill_execution_duration_seconds_count{skill="get_weather"} 28

配合Grafana，你能立刻回答这些运维问题：

• “天气技能最近1小时P95耗时是否突增？” → 查le="5.0"桶占比；
• “PDF摘要失败率是否超过5%？” → 计算skill_execution_total{skill="summarize_pdf",status="error"}/skill_execution_total{skill="summarize_pdf"}；
• “哪个技能最拖慢日报生成？” → 对比各技能_sum/_count比值。

这比翻日志快十倍，也是我坚持在每个技能里写raise RuntimeError而不是print()的根本原因——只有结构化错误，才能被指标体系捕获。

我带过的几个模拟项目X，上线后第一周就靠这个监控发现了get_stock_data技能因API限频导致的间歇性失败，及时切换了备用数据源。没有监控的AI系统，就像没装刹车的汽车，跑得越快越危险。希望帮到你。

本文还有配套的精品资源，点击获取