1. 项目概述一个为AI编码代理设计的开源技能库如果你和我一样每天都在和Claude、Cursor、Copilot这类AI编码助手打交道那你肯定也遇到过这个痛点每次想让AI帮你处理一个稍微复杂点的任务比如把一堆JSON数据转成CSV、生成一个Dockerfile或者从PDF里提取表格你都得花时间给它解释上下文、提供代码片段甚至手把手教它怎么调用某个库。这个过程重复、低效而且AI的“记忆”是临时的下次遇到同样的问题一切又得重来。SkillForge原名yaratai-skill这个项目就是冲着解决这个“重复造轮子”的问题来的。它的核心思路非常直接把开发者日常工作中那些高频、通用的任务打包成一个个独立的、标准化的“技能”Skill。这些技能就像乐高积木每个都有明确的输入输出接口可以被任何AI代理通过一个统一的REST API来调用。你不再需要每次都教AI怎么写代码只需要告诉它“去调用data.json-to-csv这个技能把这份数据传给它。”这个项目最吸引我的地方在于它的“无状态”和“Docker优先”设计。整个运行时就是一个Docker容器拉下来、跑起来一个Web管理面板和51个开箱即用的技能就全准备好了。没有数据库没有复杂的配置没有全局状态。每个技能的执行都是纯函数式的输入JSON输出JSON。这种极简主义的设计让集成变得异常简单无论是嵌入到你的自动化流程里还是让AI助手直接调用都几乎没有心智负担。2. 核心设计理念与架构拆解2.1 为什么是“无状态”和“Docker优先”在深入代码之前我们先聊聊SkillForge背后的设计哲学。为什么“无状态”如此重要在分布式系统和微服务架构里无状态服务意味着每个请求都是独立的服务本身不保存任何会话或上下文信息。这带来了几个巨大的优势极致的可扩展性你可以轻松地启动多个SkillForge容器实例前面挂个负载均衡器就能线性地提升处理能力。因为每个请求都是独立的不需要考虑会话粘滞或状态同步的问题。简化运维与部署没有数据库就意味着你不需要维护数据库的备份、迁移、性能调优。部署就是docker run或docker compose up回滚就是重启容器。这大大降低了运维复杂度尤其适合个人开发者或小团队快速搭建服务。确定性的行为无状态确保了技能的执行结果是完全由输入决定的。同样的输入无论何时、在哪个实例上执行都应该得到同样的输出假设没有外部依赖的变动。这对于构建可靠的自动化流程至关重要。那么“Docker优先”呢这其实是“无状态”理念的自然延伸。Docker容器提供了一个轻量级、一致性的运行时环境。SkillForge将所有依赖Python环境、第三方库、技能代码都打包进一个镜像里。这意味着环境一致性你在本地开发机测试通过的功能在生产环境的Docker容器里会以完全相同的方式运行彻底告别“在我机器上是好的”这类问题。一键部署用户获取价值的路径被缩短到极致。不需要懂Python虚拟环境不需要处理复杂的依赖冲突只需要有Docker一条命令就能获得完整功能。隔离与安全每个技能都在同一个受控的容器环境内运行与宿主机和其他服务隔离。即使某个技能的代码有问题也较难影响到宿主系统。2.2 技能Skill的标准化契约一切皆JSONSkillForge的另一个核心是它对“技能”的严格定义。这不是一个松散的概念而是一个由四个文件构成的、具有强制契约的标准化模块。skills/category/skill-name/ ├── schema.json # 输入输出的JSON Schema定义是技能的“合同” ├── worker.py # 技能的具体实现一个Python类 ├── SKILL.md # 面向人类和AI的详细文档 └── test.py # 自动化测试确保技能行为符合预期我们重点看schema.json和worker.py它们是技能的灵魂。schema.json机器可读的合同这个文件定义了技能的“接口”。它使用JSON Schema标准明确规定了skill_id和version技能的全局唯一标识和版本。description人类可读的描述。input一个详细的JSON Schema对象定义调用者必须required或可以properties提供哪些参数每个参数的类型type、格式format、描述description甚至枚举值enum。output同样定义了技能成功执行后返回的数据结构。为什么这如此重要因为这让AI代理能够“理解”技能。AI可以通过查询/api/skills/{id}/info端点获取这个schema从而动态地知道“哦调用data.json-to-csv需要我提供一个名为records的数组参数”然后它就能自动构造出正确的请求体。这是实现AI自动发现和调用技能的基础。worker.py合同的履行者这是技能逻辑的实现。它必须继承自BaseWorker基类并实现run方法。run方法接收一个SkillInput对象其中包含data字段即来自schema的输入并返回一个SkillOutput对象。SkillOutput的结构是固定的{“success”: bool, “data”: dict, “error”: str, “metadata”: dict}。这种统一的响应格式使得调用方无论是AI还是其他程序可以用完全相同的方式处理任何技能的结果先检查success字段如果为真就使用data如果为假就查看error信息。metadata则可以包含一些执行过程的元信息比如处理时长、记录条数等。这种“契约优先”的开发模式强制开发者先思考接口设计再实现逻辑最终产出的技能天然就是可组合、可复用的。2.3 整体架构轻量但高效从项目结构看SkillForge的架构清晰且专注核心引擎 (skillforge/): 包含registry.py技能自动发现与注册、orchestrator.py未来支持技能流水线、sync.py社区技能同步。API层 (skillforge/api/): 基于FastAPI构建的REST API和Dashboard前端。FastAPI的选择非常明智它自动生成OpenAPI文档性能优异与Python的异步特性结合得很好完美支撑了这种IO可能密集如文件处理、调用LLM的技能执行场景。技能仓库 (skills/): 所有技能按类别组织存放。_template目录提供了创建新技能的完美起点。CLI工具 (cli/): 提供了命令行界面方便在开发、测试或服务器环境中直接操作技能。节点适配器 (skillforge/nodes/): 这是项目面向未来的设计。目前有local_node.py连接本地Ollama和cloud_node.py连接RunPod等云服务。这为技能提供了调用外部计算资源尤其是大语言模型的能力而无需将LLM推理逻辑硬编码在技能内部。整个系统通过Docker Compose编排通常与一个Ollama服务提供本地LLM推理能力协同工作形成了一个功能完整、自包含的AI工具运行时环境。3. 从零开始部署与初体验3.1 两种部署方式详解SkillForge提供了两种部署方式适合不同场景。方式一Docker Compose生产与快速体验推荐这是最推荐的方式尤其对于只想快速使用技能的用户。git clone https://github.com/ilhankilic/yaratai-skill.git cd yaratai-skill docker compose up -d执行完这三条命令后访问http://localhost:9147你就能看到SkillForge的Web Dashboard了。这里我解释一下docker-compose.yml里的一些关键点version: 3.8 services: skillforge: build: . ports: - 9147:9147 environment: - OLLAMA_BASE_URLhttp://ollama:11434 - SKILLFORGE_ENVdocker volumes: - ./skills/community:/app/skills/community depends_on: - ollama ollama: image: ollama/ollama:latest ports: - 11434:11434 volumes: - ollama_data:/root/.ollama端口9147这是SkillForge的默认端口选择它是为了避免与常见的Web服务端口如80, 443, 3000, 8080冲突。环境变量OLLAMA_BASE_URL指向了名为ollama的服务Docker Compose网络内的服务名这使得SkillForge容器内的技能可以访问Ollama服务。SKILLAFORGE_ENVdocker可能被用于一些容器内的特定配置。数据卷./skills/community:/app/skills/community将宿主机的skills/community目录挂载到容器内。这意味着你从社区同步下来的技能会持久化保存在本地即使容器重建也不会丢失。Ollama服务同时启动了一个Ollama容器用于支持那些需要LLM能力的技能如ai.prompt-engineer,mediscreen.triage。Ollama的数据也通过卷ollama_data持久化避免每次重启重新下载模型。注意首次启动时由于需要构建SkillForge镜像并拉取Ollama镜像可能需要几分钟时间。启动后建议运行docker compose logs -f skillforge查看启动日志确保服务正常。方式二本地Python环境开发与贡献者如果你想修改代码、开发新技能或者深入研究内部机制需要在本地Python环境运行。git clone https://github.com/ilhankilic/yaratai-skill.git cd yaratai-skill # 推荐使用虚拟环境 python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows # 安装依赖[all]表示安装所有可选依赖如处理PDF、地理信息的库 pip install -e .[all] # 启动服务 uvicorn skillforge.api.app:app --reload --port 9147pip install -e “.[all]”中的-e代表“可编辑模式安装”这样你对本地代码的修改会立即生效无需重新安装包。[all]是一个“extras”标识它会安装pyproject.toml中定义的所有可选依赖组确保所有技能包括那些需要pdfplumber,geopandas等库的都能运行。避坑提示在本地开发时如果你不需要用到所有技能可以只安装核心依赖pip install -e .。当你要测试某个特定技能如PDF提取时再单独安装其依赖pip install pdfplumber这样可以保持环境更干净。3.2 验证与首次API调用服务启动后首先进行健康检查curl http://localhost:9147/health预期返回类似{“status”: “healthy”, “version”: “0.1.0”, “skills_loaded”: 51}这证明API服务运行正常并且成功加载了所有技能。接下来探索可用的技能。你可以通过Dashboard直观查看也可以用API# 列出所有技能 curl http://localhost:9147/api/skills | python -m json.tool # 或者按类别筛选 curl “http://localhost:9147/api/skills?categorydata”现在让我们尝试调用一个最简单的技能来感受一下。我们选择data.json-to-csv这是一个将JSON数组转换为CSV格式的技能。首先查看它的“合同”schema了解它需要什么curl http://localhost:9147/api/skills/data.json-to-csv/info在返回的JSON中找到input_schema部分。它会告诉我们这个技能需要一个records参数其类型是array数组中的每个元素是object。这意味着我们需要传递一个JSON对象的列表。然后我们构造一个符合该schema的请求并执行curl -X POST http://localhost:9147/api/skills/data.json-to-csv/run \ -H “Content-Type: application/json” \ -d ‘{ “data”: { “records”: [ {“name”: “Alice”, “age”: 30, “city”: “New York”}, {“name”: “Bob”, “age”: 25, “city”: “London”}, {“name”: “Charlie”, “age”: 35, “city”: “Tokyo”} ] } }’如果一切正常你会收到一个成功的响应其中的data字段就包含了生成的CSV字符串。这就是SkillForge最基本的工作流程发现技能 - 查看契约 - 构造合规输入 - 执行 - 获取标准化输出。4. 深度集成让AI代理成为技能大师SkillForge的真正威力在于它与AI编码代理如Claude Code、Cursor、GitHub Copilot的无缝集成。其设计目标就是让AI能够自动发现、理解并调用这些技能从而极大地扩展AI的能力边界。4.1 集成原理AGENTS.md与系统提示词项目根目录下的AGENTS.md文件是整个集成机制的关键。这个文件是写给AI看的“说明书”。当你把SkillForge项目克隆到本地并在Claude Desktop或Cursor中打开这个项目时AI会读取这个文件从而理解这里有一个SkillForge运行时可以通过http://localhost:9147访问。它提供了一系列技能可以通过REST API调用。调用模式是固定的先GET /api/skills发现技能再GET /api/skills/{id}/info查看详情最后POST /api/skills/{id}/run执行。每个响应都有固定的格式{“success”: …, “data”: …, “error”: …}。对于Claude Desktop你需要手动将一段系统提示词添加到设置中。这段提示词本质上就是把AGENTS.md的精华浓缩后告诉Claude让它将SkillForge视为一个可用的工具集。对于Cursor则更简单。你可以在项目根目录创建一个.cursorrules文件内容就是关于SkillForge的规则描述。Cursor在分析项目时会自动读取这个文件从而在其代码补全和聊天建议中融入调用SkillForge技能的知识。4.2 实战引导AI完成一个复杂任务假设你正在用Cursor开发一个项目需要处理用户上传的Excel文件并将其内容导入数据库。传统的做法是你告诉Cursor“写一个用pandas读取Excel的函数然后处理一下数据再生成SQL插入语句。” 这个过程繁琐且生成的代码质量不稳定。有了SkillForge对话可以变成这样你“我们有一个用户上传的Excel文件data.xlsx需要把它的内容转换成能直接插入到PostgreSQL数据库的SQL语句。表名是users。”Cursor在理解了.cursorrules后“我看到了这个项目集成了SkillForge。我可以分两步利用现有技能来完成这个任务首先调用data.excel-to-json技能将Excel文件转换为JSON格式。我需要先将文件读取为Base64编码或二进制数据传入。然后将得到的JSON数据结合表名users构思一个技能来处理。不过我注意到当前技能库中没有直接生成SQL的。我可以为你编写一个简单的Python脚本调用第一个技能然后处理JSON生成SQL。或者你是否考虑在SkillForge中创建一个data.json-to-sql技能”看AI的思考过程发生了变化。它首先尝试利用现有的、经过验证的标准化组件data.excel-to-json而不是从头开始编写可能充满错误的pandas代码。即使最终步骤需要额外开发目标也变成了“创建一个可复用的SkillForge技能”这比写一次性的脚本价值高得多。4.3 高级用法技能流水线Pipeline虽然当前版本的SkillForge主要侧重于单个技能的调用但其架构已经为技能编排留出了空间。查看项目结构有一个pipelines/目录而orchestrator.py文件也暗示了流水线执行引擎的可能性。流水线的概念非常强大。你可以定义一个YAML文件将多个技能串联起来前一个技能的输出作为后一个技能的输入。例如一个数据处理流水线可以这样设计name: “user-data-processing” description: “Process uploaded user data and generate reports” steps: - skill: “data.excel-to-json” input: file_data: “{{ input.file }}” # 从初始输入中获取文件 output_key: “json_data” # 将输出存储为变量 - skill: “data.csv-clean” input: csv_data: “{{ steps.step1.output.csv }}” # 引用上一步的输出 options: remove_empty: true normalize_dates: true output_key: “cleaned_data” - skill: “code.pr-summary” input: diff_content: “{{ steps.step2.output.cleaned_data | to_diff_format }}” # 可能需要一个格式化过滤器 output_key: “report_summary”通过CLI你可以执行这个流水线skillforge pipe user-data-processing -i input.json。这种编排能力可以将简单的原子技能组合成复杂的业务流程非常适合自动化场景。实操心得在与AI协同工作时你可以先利用现有技能解决大部分标准化任务然后将AI的创造力引导至更值得投入的地方——比如设计这样的流水线或是开发现有技能库中缺失的、你业务特有的新技能。这才是人机协作的正确打开方式。5. 技能开发实战从构思到贡献作为开发者使用现有技能固然方便但SkillForge的生态活力来自于社区贡献。创建并分享自己的技能是深入理解该项目和回馈社区的最佳方式。5.1 技能构思与schema设计在动手写代码之前最关键的步骤是设计schema.json。一个好的schema应该清晰属性名和描述要让人和AI一眼就能看懂。完整定义所有必需的参数和可选的参数。严格使用JSON Schema的约束条件如minLength,maximum,pattern,enum来验证输入将错误扼杀在调用之前。面向未来考虑可能的扩展为metadata留出空间。假设我们要创建一个utils.markdown-to-html技能将Markdown文本转换为HTML。首先创建技能目录结构cd yaratai-skill cp -r skills/_template skills/utils/markdown-to-html cd skills/utils/markdown-to-html然后编辑schema.json{ “skill_id”: “utils.markdown-to-html”, “version”: “1.0.0”, “description”: “Convert Markdown formatted text to HTML.”, “input”: { “type”: “object”, “required”: [“markdown_text”], “properties”: { “markdown_text”: { “type”: “string”, “description”: “The Markdown text to convert.” }, “extensions”: { “type”: “array”, “description”: “Optional list of Markdown extensions to enable (e.g., ‘tables’, ‘fenced_code’, ‘footnotes’).”, “items”: { “type”: “string” }, “default”: [“extra”, “codehilite”] }, “safe_mode”: { “type”: “boolean”, “description”: “If true, strip out all raw HTML and avoid XSS attacks.”, “default”: true } } }, “output”: { “type”: “object”, “properties”: { “html”: { “type”: “string”, “description”: “The converted HTML string.” }, “warnings”: { “type”: “array”, “items”: {“type”: “string”}, “description”: “Any warnings generated during conversion.” } } } }这个schema定义了必需的输入markdown_text以及两个可选配置项。输出包括转换后的html和可能的warnings。5.2 实现worker.py接下来实现worker.py。我们需要选择一个Markdown解析库比如markdown或mistune。假设我们使用markdown。from skillforge.base import BaseWorker, SkillInput, SkillOutput import markdown from typing import List, Optional class Worker(BaseWorker): “”“Convert Markdown text to HTML.”“” skill_id “utils.markdown-to-html” version “1.0.0” def run(self, input: SkillInput) - SkillOutput: # 1. 从输入中获取数据 markdown_text: str input.data.get(“markdown_text”) extensions: List[str] input.data.get(“extensions”, [“extra”, “codehilite”]) safe_mode: bool input.data.get(“safe_mode”, True) # 2. 输入验证 (schema已做基础验证这里可做额外检查) if not markdown_text or not isinstance(markdown_text, str): return SkillOutput(successFalse, error“Invalid input: ‘markdown_text’ must be a non-empty string.”) # 3. 核心逻辑 try: # 构建扩展列表 md_extensions extensions.copy() # 安全模式处理 if safe_mode: # 在安全模式下可以禁用某些可能不安全的扩展或使用库的安全模式 # 这里我们假设使用markdown库的safe_mode参数实际库参数可能不同 # 为了示例我们简单处理如果safe_mode为True确保使用‘safe’扩展 if ‘safe’ not in md_extensions: md_extensions.append(‘safe’) # 执行转换 html_output markdown.markdown(markdown_text, extensionsmd_extensions) # 4. 构造成功输出 output_data { “html”: html_output, “warnings”: [] # 实际可以收集转换过程中的警告 } return SkillOutput(successTrue, dataoutput_data) except Exception as e: # 5. 异常处理 return SkillOutput(successFalse, errorf“Markdown conversion failed: {str(e)}”)关键点解析继承与属性类必须继承BaseWorker并设置skill_id和version这与schema.json对应。输入提取从input.data字典中获取参数。由于schema.json已经定义了required和default这里的数据相对可靠但仍需做防御性检查。核心逻辑在try块中实现主要功能。这里调用了markdown.markdown()函数。输出构造返回的SkillOutput的data字段必须符合schema.json中output的定义。错误处理任何异常都应被捕获并返回successFalse和清晰的error信息。这是技能健壮性的关键。5.3 编写文档与测试SKILL.md这是技能的“用户手册”。你需要用清晰的语言描述技能的功能、输入输出字段的含义、使用示例以及任何注意事项。好的文档能极大降低使用门槛也是AI理解技能的重要依据。test.py测试是保证技能质量的生命线。至少应包含三类测试快乐路径测试使用正常的输入验证输出符合预期。边界情况测试测试空输入、极长字符串、特殊字符等。错误输入测试测试缺少必需参数、参数类型错误等情况确保技能能优雅地失败并返回有意义的错误信息。import pytest from .worker import Worker from skillforge.base import SkillInput def test_markdown_to_html_basic(): “”“Test basic markdown conversion.”“” worker Worker() input_data {“markdown_text”: “# Hello, World!\n\nThis is **bold**.”} result worker.run(SkillInput(datainput_data)) assert result.success is True assert “h1Hello, World!/h1” in result.data[“html”] assert “strongbold/strong” in result.data[“html”] def test_markdown_to_html_with_extensions(): “”“Test conversion with table extension.”“” worker Worker() input_data { “markdown_text”: “| Header |\n|--------|\n| Cell |”, “extensions”: [“tables”] } result worker.run(SkillInput(datainput_data)) assert result.success is True assert “table” in result.data[“html”] def test_markdown_to_html_missing_input(): “”“Test error handling for missing required input.”“” worker Worker() input_data {} # 缺少 markdown_text result worker.run(SkillInput(datainput_data)) assert result.success is False assert “markdown_text” in result.error.lower()运行测试pytest skills/utils/markdown-to-html/test.py -v。确保所有测试通过。5.4 提交与贡献流程完成开发后你可以通过GitHub Pull Request向官方仓库贡献你的技能。Fork官方仓库到你的GitHub账号。在本地切换到dev分支这是开发分支。将你的技能目录skills/utils/markdown-to-html/复制到你的fork中。确保代码风格一致并通过所有测试包括项目的整体测试pytest。提交代码并推送到你fork的仓库。在GitHub上创建Pull Request目标分支选择原仓库的dev分支。在PR描述中清晰说明你的技能功能、使用场景和测试情况。项目维护者会审核你的代码和schema设计。一旦合并你的技能就会出现在下一次官方发布中所有用户通过docker compose up或git pull就能获得它。6. 生产环境考量与高级配置6.1 性能、安全与监控将SkillForge用于生产环境需要考虑以下几个层面性能技能本身确保你的技能代码是高效的。避免在技能中进行耗时的同步IO操作如大文件读写、网络请求。对于耗时操作应考虑异步实现或未来利用SkillForge可能提供的WebSocket/异步任务支持。FastAPI服务器可以通过调整Uvicorn的工作进程数–workers来利用多核CPU。例如uvicorn skillforge.api.app:app –host 0.0.0.0 –port 9147 –workers 4。在Docker中可以通过docker-compose.yml的command覆盖默认启动命令。资源限制在Docker Compose中为容器设置CPU和内存限制防止某个异常技能耗尽资源。安全输入验证这是第一道防线。SkillForge会使用schema.json进行基础的JSON Schema验证。但在worker.py中你仍需对输入进行业务逻辑上的验证和清理特别是处理用户上传的文件、执行系统命令或进行字符串拼接时要警惕路径遍历、命令注入和跨站脚本XSS攻击。网络隔离SkillForge容器默认会与Ollama容器通信。在生产环境中应考虑将这两个服务部署在同一个内部网络并严格限制对外暴露的端口。通常只将SkillForge的API端口9147通过反向代理如Nginx暴露给内部网络或特定的客户端而不是公网。技能审核对于从社区同步的技能务必进行代码审查。SkillForge的同步功能很强大但也意味着可能运行不受信任的代码。建议在生产环境中关闭自动同步或者只同步你信任的源。监控健康检查/health端点提供了基本的健康状态。你可以将其集成到Kubernetes的存活探针或Docker的健康检查中。日志SkillForge使用Python的标准logging模块。确保将日志输出到标准输出stdout或文件并配置日志聚合工具如ELK Stack、Loki进行收集和分析。在Docker中日志会自动被Docker Daemon捕获。指标目前SkillForge没有内置的指标暴露如Prometheus metrics。对于生产环境你可能需要自己添加或通过反向代理如Nginx收集基本的HTTP请求指标。6.2 与现有系统集成SkillForge可以作为微服务架构中的一个“工具服务”来集成。场景一后端服务调用你的主应用后端如Django、Spring Boot可以通过HTTP客户端直接调用SkillForge的API。例如在处理用户上传的图片时调用media.img-compress技能在导出数据报表时调用data.json-to-csv技能。这可以将一些通用的、非核心的业务逻辑剥离出去让主服务更专注于核心业务。场景二自动化脚本与CI/CD在CI/CD流水线中你可以编写脚本调用SkillForge。例如在代码合并前调用devops.env-secret-scan技能扫描代码中是否包含敏感信息在构建镜像后调用code.changelog技能基于Git历史生成版本变更日志。场景三内部开发者门户你可以将SkillForge的Dashboard嵌入到公司的内部开发者门户中为其他部门的同事如产品、运营提供一个自助式的工具平台。他们不需要懂代码就可以通过Web界面使用这些技能处理数据、生成文档等。6.3 配置详解与环境变量SkillForge通过环境变量进行配置这非常符合十二要素应用的原则。环境变量默认值描述与生产建议OLLAMA_BASE_URLhttp://localhost:11434关键配置。在Docker Compose中它指向服务名ollama。如果你使用外部的Ollama服务或云LLM API需要修改此值。例如http://your-ollama-server:11434。OLLAMA_MODELgemma3:4b默认使用的Ollama模型。如果你的技能如ai.prompt-engineer需要特定模型可以在这里全局设置或在技能内部覆盖。OLLAMA_TIMEOUT60LLM请求超时时间秒。对于生成复杂内容的技能可能需要调高。RUNPOD_API_KEY(空)如果使用RunPod等云GPU服务来运行LLM技能需要设置此API密钥。务必通过Docker secrets或K8s Secret管理切勿硬编码。RUNPOD_ENDPOINT(空)对应的RunPod端点URL。ANTHROPIC_API_KEY(空)用于skillforge create命令该命令可以利用Claude API自动生成技能代码。同样需要安全地管理此密钥。SKILLFORGE_ENV(空)环境标识。设置为docker时可能会影响一些路径或行为如社区技能的存储位置。LOG_LEVELINFO控制日志输出级别。生产环境可设置为WARNING或ERROR以减少日志量排查问题时临时改为DEBUG。在docker-compose.yml中配置环境变量的示例services: skillforge: … environment: - OLLAMA_BASE_URLhttp://ollama:11434 - OLLAMA_MODELllama3.2:3b # 使用更小的模型 - LOG_LEVELWARNING # 更安全的方式是使用env_file或secrets # env_file: # - .env.production # secrets: # - runpod_api_key7. 常见问题排查与社区资源7.1 问题排查速查表在实际使用和开发中你可能会遇到以下问题问题现象可能原因排查步骤与解决方案访问localhost:9147失败1. 服务未启动。2. 端口被占用。3. Docker Desktop网络问题Windows/macOS。1. 运行docker compose ps确认容器状态。2. 运行docker compose logs skillforge查看启动日志。3. 检查端口占用netstat -ano | findstr :9147(Win) 或lsof -i :9147(Mac/Linux)。4. 尝试修改docker-compose.yml中的主机端口映射如“9180:9147”。调用技能返回{“success”: false, “error”: “Skill ‘xxx’ not found.”}1. 技能ID拼写错误。2. 技能未成功加载。1. 通过GET /api/skills确认正确的技能ID。2. 查看服务启动日志确认是否有技能加载失败如Python语法错误、依赖缺失。3. 检查技能目录结构是否正确schema.json格式是否合法。技能执行成功但返回数据为空或不符合预期。1. 输入数据不符合schema要求。2. 技能内部逻辑有bug。3. 依赖库版本不兼容。1. 使用GET /api/skills/{id}/info仔细核对输入schema。2. 在技能目录下运行pytest test.py -v -s查看详细的测试输出。3. 在worker.py中添加调试日志或使用print语句查看容器日志。4. 检查技能所需的Python包是否已安装在容器内执行pip list | grep package-name。AI代理如Cursor无法发现或调用技能。1..cursorrules或系统提示词未正确配置。2. SkillForge服务地址不对。3. AI的上下文长度限制未读取完整AGENTS.md。1. 确认.cursorrules文件在项目根目录且内容正确。2. 确认AI代理能访问http://localhost:9147/health。3. 尝试在AI对话中手动粘贴关键的API调用示例和技能列表。从社区同步技能失败。1. 网络问题无法访问GitHub。2. 社区仓库的目录结构不符合SkillForge标准。3. 技能验证失败。1. 在Dashboard的“Sync Import”页面查看具体的错误信息。2. 手动检查目标仓库的skills/目录结构。3. 使用API端点/api/sync/validate预先验证技能格式。技能执行速度慢尤其是涉及LLM的技能。1. Ollama服务未启动或模型未加载。2. 模型太大本地硬件资源不足。3. 网络延迟如果使用远程LLM。1. 检查Ollama容器日志docker compose logs ollama。2. 在Ollama容器内运行ollama list确认模型已下载。3. 考虑使用更小的模型如gemma3:4b或增加Ollama服务的资源分配。4. 对于生产环境考虑使用云GPU服务配置RUNPOD_*环境变量。7.2 社区、生态与未来展望SkillForge作为一个开源项目其生命力在于社区。目前项目已经有了一个非常坚实的开端清晰的架构、丰富的初始技能、完善的开发标准。如何参与社区使用与反馈最简单的方式就是使用它并在GitHub Issues中报告bug或提出功能建议。贡献技能这是最直接的贡献方式。将你工作中常用的工具函数封装成技能。从简单的工具开始比如格式化工具、数据验证器等。改进文档如果你发现文档中有不清楚的地方或者有更好的示例可以提交PR改进SKILL.md或项目主README。分享用例在社交媒体、技术论坛或博客上分享你是如何使用SkillForge解决实际问题的。这能帮助项目吸引更多的用户和贡献者。生态展望 从项目的Roadmap可以看到一些令人兴奋的方向技能市场一个带有评分和评论的技能商店让用户可以轻松发现和安装高质量的技能。多语言支持目前技能只能用Python编写。未来支持TypeScript、Go等语言将吸引更多不同技术背景的开发者。WebSocket与长任务当前技能执行是同步HTTP请求不适合长时间运行的任务。WebSocket支持将允许技能流式输出结果或处理长时间任务。技能依赖与流水线更强大的编排能力允许技能声明其依赖如“本技能需要先运行data.clean”让复杂的多步骤工作流更容易构建。SkillForge代表了一种思路的转变我们不再仅仅让AI生成代码而是为AI构建一个可编程的、由高质量代码模块组成的“工具手”。这或许是人机协作编程范式演进中的一个重要节点。作为开发者我们现在就可以参与其中亲手塑造这个未来。