name: software-system-architectdescription: 以资深软件/系统架构师和数据库架构师的视角分析软件需求，将需求拆分为业务领域、功能模块、详细功能设计、数据/接口/安全/运维架构，并输出名为“系统构架设计.md”或“项目名称系统构架设计.md”的中文 Markdown 架构设计文档。适用于用户提供产品构想、业务需求、RFP/需求文档、遗留系统说明、电信 BOSS 需求，或提出软件系统构架、架构设计、模块拆解、功能设计、系统设计文档、系统构架设计.md 等需求的场景。软件系统构架师概述使用此技能将用户提供的软件需求整理为可复用的中文架构设计文档。你应以资深软件工程师、系统架构师、数据库架构师的身份开展工作；在相关场景下，还应具备电信 BOSS/BSS/OSS 架构师的专业视角。默认交付物：在当前工作区创建名为 系统构架设计.md 的 Markdown 文件。如果项目或系统名称明确，则命名为 <项目名称>系统构架设计.md。除非用户明确要求，否则不要修改原始需求文件。工作流程从用户消息、附件、所引用的本地文件或代码仓库文档中收集原始需求。在开始设计前，应先阅读可用的需求材料。使用业务语言重构需求，包括：业务目标、目标用户、核心场景、范围边界、上下游系统、约束条件和成功标准。识别缺失的关键信息。在合理情况下，可基于明确说明的假设继续设计；只有当缺少澄清会使设计产生重大风险或无法继续时，才向用户提问。优先按照稳定的业务能力拆分系统，而不是按照界面页面拆分。模块划分应综合考虑领域边界、生命周期归属、数据归属、事务一致性、集成边界和运维责任。将每个模块设计到详细功能层级，包括：模块职责、功能、流程、数据对象、API/事件、权限、校验、异常、依赖关系和验收标准。完成交叉领域架构设计，包括：数据架构、集成架构、安全与授权、审计、可观测性、部署、性能、可用性、迁移和分阶段交付。编写 Markdown 文档，确认文件已经生成，并报告其绝对路径。设计启发式原则优先采用边界清晰的限界上下文和业务能力模块，而不是模糊的技术分层。明确模块归属：每个重要数据对象和业务流程都应由一个主要模块负责。当命令流程、查询/报表流程、后台任务、集成适配器和审计轨迹在扩展性或可靠性要求上不同时，应分别设计。对复杂流程，应提供状态机或 Mermaid 流程图。对分布式系统或集成密集型系统，应明确说明幂等、重试、补偿、消息顺序、超时处理和对账机制。数据库设计应提供概念实体和关键数据表建议；除非用户明确要求，否则不要过度细化到 DDL 层级。对企业级系统，应包含角色/权限边界、审批流程、审计日志、配置管理和运维支持设计。对电信 BOSS/BSS/OSS 场景，应视需求考虑客户、账户、用户、产品、销售品、订单、资源、开通、计费、支付、工单、渠道和结算等维度。当需求涉及这些能力时，应明确区分 CRM、订单中心、产品目录、资源中心、计费/账务、开通、工作流和集成等职责。输出规则除非用户要求使用其他语言，否则使用中文编写。表述应明确、具体，避免使用适用于任何系统的泛化描述。使用表格呈现模块清单、接口清单、数据实体、非功能需求和实施阶段。将假设明确标注为 设计假设。将未决问题明确标注为 待确认问题；不要将不确定性隐藏在普通叙述中。文档应包含足够细节，使开发团队能够据此进行任务拆解、接口规划和数据库规划。不要编写营销式方案，应输出工程设计文档。文档模板除非用户提供了更严格的模板，否则使用以下结构：# <项目/系统名称>系统构架设计 ## 1. 文档说明 | 项目 | 内容 | | --- | --- | | 文档名称 | <项目/系统名称>系统构架设计 | | 需求来源 | <用户描述/需求文件/仓库路径> | | 设计角色 | 软件系统构架师 | | 版本 | v1.0 | | 日期 | <YYYY-MM-DD> | ## 2. 需求理解 ### 2.1 业务背景 ### 2.2 建设目标 ### 2.3 用户角色与使用场景 ### 2.4 业务范围 ### 2.5 非业务范围 ### 2.6 关键约束 ### 2.7 设计假设 ## 3. 总体架构设计 ### 3.1 架构目标 ### 3.2 架构原则 ### 3.3 逻辑架构 ### 3.4 应用架构 ### 3.5 数据架构概览 ### 3.6 集成架构概览 ### 3.7 部署架构概览 ## 4. 功能模块划分 | 模块 | 业务职责 | 核心功能 | 主要数据 | 对外接口/事件 | 依赖模块 | | --- | --- | --- | --- | --- | --- | ## 5. 详细功能设计 ### 5.x <模块名称> #### 5.x.1 设计目标 #### 5.x.2 功能清单 #### 5.x.3 业务流程 #### 5.x.4 关键业务规则 #### 5.x.5 数据对象与表建议 #### 5.x.6 接口/事件设计 #### 5.x.7 权限与校验 #### 5.x.8 异常与补偿 #### 5.x.9 验收标准 ## 6. 数据架构设计 ### 6.1 核心实体关系 ### 6.2 关键数据表建议 ### 6.3 数据生命周期 ### 6.4 数据质量与一致性 ## 7. 接口与集成设计 | 集成对象 | 集成方式 | 主要数据 | 触发时机 | 可靠性要求 | 异常处理 | | --- | --- | --- | --- | --- | --- | ## 8. 权限、安全与审计设计 ## 9. 非功能需求设计 | 类别 | 设计要求 | 建议方案 | 验收指标 | | --- | --- | --- | --- | ## 10. 运维与可观测性设计 ## 11. 分期实施计划 | 阶段 | 建设目标 | 交付范围 | 前置条件 | 风险 | | --- | --- | --- | --- | --- | ## 12. 风险、取舍与待确认问题 ### 12.1 关键风险 ### 12.2 架构取舍 ### 12.3 待确认问题质量检查清单完成前，请确认：文档包含明确的系统名称，或至少包含清晰的占位符。每项主要需求都映射到至少一个模块，或被明确标记为不在范围内。每个模块都包含业务职责、数据归属、接口和验收标准。数据、集成、安全、运维和分阶段交付设计均未缺失。假设和待确认问题均已明确列出。目标工作区中已存在 .md 文件，且最终答复中包含该文件的绝对路径。SKILL下载：software-system-architect.rar使用方法：将压缩包解压后放到.codex\skills 目录下即可
一文读懂 Agent Skills：原理、机制、架构、代码与 AI 工程化落地全解析
AI摘要 本文全面解析了Agent Skills的概念、原理、架构和代码实现，以及AI工程化落地的策略。Agent Skills是一系列可被Agent在运行时发现、理解、调用和组合的能力模块，旨在解决AI助手在执行任务时缺乏稳定、可复用的能力链的问题。文章通过比较Skill和Prompt的区别，强调了Skill在发现性、执行性和复用性方面的优势。同时，文章还讨论了Agent Skills在工程架构中解决的三个痛点，包括巨型提示词灾难、执行能力和专业知识脱节以及企业级可靠性缺失。文章详细介绍了Agent如何决定调用哪个Skill的决策流程，以及Skill的结构和代码实现，包括使用OpenAI SDK和LangChain框架的示例。最后，文章讨论了Skills、Function Calling和MCP之间的边界，并分享了生产环境中常见的问题和解决方案。 document.addEventListener('DOMContentLoaded', function() { const urlDisplay = document.getElementById('urlDisplay'); urlDisplay.textContent = "此内容根据文章生成，更内容请访问：" + window.location.href; }); 一文读懂 Agent Skills：原理、机制、架构、代码与 AI 工程化落地全解析作者：多模态智能体发布时间：2026年6月9日 08:21原始链接：https://mp.weixin.qq.com/s/hWtN3cPszsVKJd94tSQM7A你有没有遇到过这种情况：写了一个函数，需要补充单元测试。你打开 AI 助手，发了一句话过去。AI 给了你几个测试用例。但你看了一眼，发现边界条件根本没有覆盖，Jest 框架也没用，覆盖率更是没有任何说明。你只好重新发一条："要用 Jest 框架，要覆盖边界情况，要生成覆盖率报告……"下周同样的事情再发生一次，你又要从头解释一遍。或者这个场景：团队里积累了几十个 Markdown 文档，格式乱、目录缺、链接死。你告诉 AI "帮我整理一下这些文档"，AI 只是改了改标题格式，其他什么都没动。你想要的是统一格式、提取关键信息、生成目录、验证链接——这些它压根不知道。问题不是 AI 不聪明。问题是：它没有一套稳定的、可复用的能力链来完成这类任务。每次都要重新解释，每次执行结果都不一样，每次都是一次性的。这才是真正的痛点。Agent Skills 要解决的，就是这个问题。 什么是 Agent Skills 先给一个干净的定义： Skill 是一个可被 Agent 在运行时发现、理解、调用和组合的能力模块。 这句话里有四个动词——发现、理解、调用、组合——缺少任何一个，它都不能叫 Skill。用一个生活场景来理解：你手机里装了几十个 App。当你想导航的时候，不需要自己写路线规划算法，直接打开地图 App 就好。App 帮你把"导航这件事"封装好了——如何定位、如何规划、如何播报，全在里面。Agent Skills 的逻辑完全一样。Agent 是那部手机，负责理解你的意图并调度能力Skill 是那个 App，给 Agent 增加一项可调用的能力生态 是应用商店，让能力被发现、安装和管理再讲一个更贴近工程场景的类比是：你刚入职一家公司。你智商很高，学东西快，但完全不懂这家公司的业务。老板让你"处理一下这批退款并生成财务报告"。如果没有任何参考资料，你大概率会做错。但如果书架上有一本《退款处理与财务报告生成 SOP》，你只需要按照手册里的步骤，用公司的工具（电脑、系统账号）一步步执行，结果就会是对的。这本手册，就是 Skill。它给 Agent 发的不是命令，而是一张图书馆借阅证——不是强迫它背下整个图书馆，而是让它在需要的时候去查。 Skill 和 Prompt 有什么本质区别 很多人第一反应是：Skill 不就是一个很长的 Prompt 吗？写详细点，不就行了？不一样，差别很大。我们从三个维度来看：发现性Prompt 需要用户主动提供。你每次要用，就得自己把 Prompt 粘贴进去。Skill 不一样，Agent 可以根据你的任务描述，自动匹配到合适的 Skill，你不需要知道它叫什么名字。执行性Prompt 本质上是"告诉 AI 做什么"，但执行过程是 AI 自由发挥的。Skill 内部有结构化的 Workflow，每一步要做什么、怎么做、不能做什么，全都有明确规定。复用性Prompt 是一次性的，散落在对话历史里，下次遇到同样的任务，你还得从头写。Skill 是独立的模块，一次定义，到处复用，还能持续迭代优化。举个具体例子：用 Prompt 的方式补充单元测试，你需要写："帮我给这个函数补充单元测试，要用 Jest 框架，要覆盖边界情况，要检查覆盖率，要……"——每次都要重复，容易遗漏，结果不稳定。用 Skill 的方式，你只需要说"帮我补充单元测试"，Agent 识别到这是一个测试相关任务，自动加载 test-driven-development Skill，按照里面定义好的流程执行：理解代码 → 设计测试场景 → 编写测试代码 → 验证覆盖率。结果一致，流程稳定，不用每次解释。 为什么需要它：三个架构级的痛点 上面说的是表层体验。从工程架构的角度看，Agent Skills 解决的是三个更深层的问题。痛点一：巨型提示词灾难很多团队的第一反应是：把所有业务规则、操作流程、边界条件全写进系统提示词。结果是上下文越来越长，几千 Token 变成几万 Token。这不只是钱的问题。当提示词超过模型能高质量处理的范围，会出现一个现象叫"注意力丢失（Lost in the Middle）"——中间部分的指令，模型大概率会忽略。越长的 Prompt，指令遵循能力越差。痛点二：执行能力和专业知识脱节现在的 Agent 系统通常配了很多工具：能执行代码、能读写文件、能调 API。但拥有工具，不等于知道如何专业地使用工具。给 Agent 一个能执行 SQL 查询的工具，它能查。但它知道针对你这张五百万行的宽表应该怎么写查询吗？知道如何做多步关联验证吗？知道数据异常了该怎么回退吗？这些"操作智慧"，工具给不了，必须单独注入。痛点三：企业级可靠性缺失生产环境有一个基本要求：相同输入，相同输出。但依赖动态生成的提示词，系统行为会有大量随机性。今天跑正确，明天换个措辞就跑歪了。工程化系统需要确定性。需要把专家的隐性知识，转换成模型可以稳定执行的标准操作流程。这三个痛点，指向同一个缺失：缺少一种"可插拔的领域专家大脑"机制。 Agent Skills 填的就是这个空。 Agent 是怎么决定调用哪个 Skill 的 这是一个很多人想搞清楚的问题：我说一句话，Agent 是怎么判断要不要调用 Skill，调用哪个的？整个决策流程分五步：第一步：识别任务类型。 Agent 先判断你的请求是什么性质的任务——测试相关？文档处理？代码审查？这一步相当于分类。第二步：判断是否需要 Skill。 不是所有任务都需要 Skill。"Python 是什么语言"这种问题，直接回答就好，不需要任何流程。判断标准是：这个任务是否需要结构化的多步骤执行？是否有明确的验证标准？第三步：语义匹配。 如果判断需要 Skill，Agent 会在所有可用 Skill 的描述（description）里做语义搜索，找到最匹配的那一个。第四步：注入并执行。 找到 Skill 后，把 Skill 的完整内容注入到系统提示词，Agent 按照里面的 Workflow 一步步执行。第五步：整合输出。 Skill 执行完成，结果返回给你。这背后有一个精妙的设计——渐进式信息披露。系统启动时，只加载所有 Skill 的元数据（名字和描述），每个大约一百个 Token。等到识别到具体任务，才加载完整的 SKILL.md（几千 Token）。如果任务还需要外部参考资料，才在执行过程中按需加载（可能几万 Token）。这种设计让 Agent 能"知道"几百个 Skill 的存在，但只在真正需要的时候才"学习"具体内容。既保持了广度，又控制了成本。 Skill 长什么样：从外到内拆解 理解了调用机制，我们来看 Skill 本身的结构。从三个层次来看：第一层：使用者视角（黑盒）对用户来说，Skill 就是"我说一句话，Agent 按某套流程处理，然后给我结果"。不需要知道里面是什么。第二层：文件夹视角打开一个 Skill 的目录，通常长这样：my-skill/ ├── SKILL.md # 必需：核心文件 ├── scripts/ # 可选：可执行脚本 ├── references/ # 可选：参考文档 ├── assets/ # 可选：静态资产 └── templates/ # 可选：输出模板只有 SKILL.md 是必须的，其他都是按需添加。第三层：SKILL.md 的内部结构一个典型的 SKILL.md 长这样：--- name: test-driven-development description: 在实现任何新功能或修复 Bug 时使用，必须在编写实现代码之前调用 --- # 测试驱动开发 ## Goal 引导使用 TDD 方法论来实现具体功能。 ## Workflow 1. 理解需求：阅读功能描述，识别验收标准 2. 设计测试用例：列举测试场景，按优先级排序 3. 测试先行：用项目指定框架实现测试，确保初始失败 4. 实现代码：编写最小代码使测试通过 5. 重构：在不改变行为的前提下提升代码质量 ## Constraints - 绝对不能在写测试之前写实现代码 - 代码覆盖率最低要求 80% - 每个测试必须独立、可重复运行结构很清晰：frontmatter 是路由的入口，body 是执行的指南。description 字段尤其关键，它直接决定了这个 Skill 会不会在合适的时机被找到。写好和写差的区别很大：根据复杂度不同，Skill 分三种类型：简单型：只有一个 SKILL.md，3-5 步线性流程，比如生成 Git 提交信息。五分钟就能写完。多步骤工作流型：仍然只有 SKILL.md，但 Workflow 有分支逻辑，5-10 步，比如 TDD 开发流程。资源依赖型：SKILL.md 加上外部资源目录，适合需要参考文档、执行脚本、使用模板的复杂任务。* 代码落地：两种框架的完整实现 理论说完了，来看代码。我们用一个具体任务串起来：实现一个天气查询 Skill，分别用 OpenAI SDK 和 LangChain 两套框架落地。 先定义这个 Skill --- name: get-weather description: 获取指定城市的天气信息。在用户询问天气、气温或出行建议时使用。 --- # 获取天气信息 ## Goal 根据用户询问，提供准确的天气信息。 ## Workflow 1. 从用户请求中提取城市名称 2. 获取该城市当前天气数据（温度、天气状况、湿度、风速） 3. 以自然对话口吻返回结果 4. 如需对比多城市，分别获取后整合展示 ## Constraints - 默认使用摄氏度 - 只提供当前天气，不做长期预测 - 空气质量差时主动提醒 ## Examples 用户："北京今天天气怎么样？" 回答："北京今天晴天，25°C，空气质量良好，适合出行。" 核心引擎架构 两套框架共用同一套三层架构：SkillRegistry（加载所有 Skill） ↓ SkillRouter（根据用户输入选择 Skill） ↓ SkillExecutor（注入 Skill 文档并执行） 方案一：OpenAI SDK 版本 import os, re, json from pathlib import Path from typing import Dict, List, Optional, Tuple from dataclasses import dataclass from openai import OpenAI from dotenv import load_dotenv load_dotenv() client = OpenAI( api_key=os.getenv("DEEPSEEK_API_KEY"), base_url=os.getenv("DEEPSEEK_BASE_URL", "https://api.deepseek.com") ) @dataclass class SkillMetadata: name: str description: str file_path: str full_content: Optional[str] = None class SkillRegistry: """扫描目录，加载所有 Skill 文件""" def __init__(self, skills_dir: str): self.skills_dir = Path(skills_dir) self.skills: Dict[str, SkillMetadata] = {} self._load_all_skills() def _parse_skill_file(self, file_path: Path) -> Optional[SkillMetadata]: with open(file_path, 'r', encoding='utf-8') as f: content = f.read() # 提取 YAML frontmatter match = re.search(r'^---\s*\n(.*?)\n---', content, re.DOTALL) ifnot match: returnNone frontmatter = match.group(1) name_match = re.search(r'name:\s*(.+)', frontmatter) desc_match = re.search(r'description:\s*(.+)', frontmatter) ifnot name_match ornot desc_match: returnNone return SkillMetadata( name=name_match.group(1).strip(), description=desc_match.group(1).strip(), file_path=str(file_path), full_content=content ) def _load_all_skills(self): skill_files = ( list(self.skills_dir.glob("*.skill")) + list(self.skills_dir.glob("*.md")) ) for f in skill_files: skill = self._parse_skill_file(f) if skill: self.skills[skill.name] = skill def get_all_skills_summary(self) -> str: return"\n".join( f"- {s.name}: {s.description}" for s in self.skills.values() ) class SkillRouter: """调用 LLM，根据用户输入选择合适的 Skill""" def __init__(self, registry: SkillRegistry): self.registry = registry def route(self, user_input: str) -> Optional[str]: prompt = f""" 你是一个 Skill 路由器。根据用户输入选择最合适的 Skill。 可用 Skills： {self.registry.get_all_skills_summary()} 用户输入：{user_input} 只返回 Skill 名称，没有合适的返回 NONE。 """ response = client.chat.completions.create( model=os.getenv("DEEPSEEK_MODEL", "deepseek-chat"), messages=[{"role": "user", "content": prompt}], temperature=0, max_tokens=50 ) skill_name = response.choices[0].message.content.strip() return skill_name if skill_name in self.registry.skills elseNone class SkillExecutor: """加载完整 Skill 文档，注入系统提示词后执行""" def __init__(self, registry: SkillRegistry): self.registry = registry def execute(self, skill_name: str, user_input: str) -> str: skill = self.registry.skills.get(skill_name) ifnot skill: returnf"Skill '{skill_name}' 不存在" system_prompt = f""" 你现在要执行以下 Skill： {skill.full_content} 严格按照 Workflow 执行，遵守所有 Constraints，直接返回结果。 """ response = client.chat.completions.create( model=os.getenv("DEEPSEEK_MODEL", "deepseek-chat"), messages=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": user_input} ], temperature=0.7 ) return response.choices[0].message.content class AgentSkillsEngine: """系统入口，协调 Registry / Router / Executor""" def __init__(self, skills_dir: str): self.registry = SkillRegistry(skills_dir) self.router = SkillRouter(self.registry) self.executor = SkillExecutor(self.registry) def process(self, user_input: str) -> Tuple[str, Optional[str]]: skill_name = self.router.route(user_input) ifnot skill_name: return"抱歉，没有找到合适的 Skill 处理这个请求。", None result = self.executor.execute(skill_name, user_input) return result, skill_name def list_skills(self) -> List[str]: return list(self.registry.skills.keys())调用方式：engine = AgentSkillsEngine(skills_dir="./skills") result, skill = engine.process("北京今天天气怎么样？") print(f"回复：{result}") print(f"使用 Skill：{skill}") result, skill = engine.process("对比北京和长沙的天气") print(f"回复：{result}") 方案二：LangChain 版本 LangChain 版本在架构上完全一致，换成 LCEL（LangChain Expression Language）的写法，用 | 操作符串联各组件：from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser class SkillRouter: def __init__(self, registry): self.registry = registry self.llm = ChatOpenAI( model=os.getenv("DEEPSEEK_MODEL", "deepseek-chat"), api_key=os.getenv("DEEPSEEK_API_KEY"), base_url=os.getenv("DEEPSEEK_BASE_URL", "https://api.deepseek.com"), temperature=0 ) self.prompt = ChatPromptTemplate.from_messages([ ("system", """你是一个 Skill 路由器。 {skills_summary} 规则：只返回 Skill 名称，没有合适的返回 NONE。"""), ("human", "{user_input}") ]) # LCEL 链：提示词 → 模型 → 解析输出 self.chain = self.prompt | self.llm | StrOutputParser() def route(self, user_input: str) -> Optional[str]: result = self.chain.invoke({ "skills_summary": self.registry.get_all_skills_summary(), "user_input": user_input }) skill_name = result.strip() return skill_name if skill_name in self.registry.skills elseNone class SkillExecutor: def __init__(self, registry): self.registry = registry self.llm = ChatOpenAI( model=os.getenv("DEEPSEEK_MODEL", "deepseek-chat"), api_key=os.getenv("DEEPSEEK_API_KEY"), base_url=os.getenv("DEEPSEEK_BASE_URL", "https://api.deepseek.com"), temperature=0.7 ) self.prompt = ChatPromptTemplate.from_messages([ ("system", """执行以下 Skill： {skill_content} 严格按照 Workflow 执行，直接返回结果。"""), ("human", "{user_input}") ]) self.chain = self.prompt | self.llm | StrOutputParser() def execute(self, skill_name: str, user_input: str) -> str: skill = self.registry.skills.get(skill_name) ifnot skill: returnf"Skill '{skill_name}' 不存在" return self.chain.invoke({ "skill_content": skill.full_content, "user_input": user_input })LangChain 版本和 OpenAI SDK 版本的逻辑完全相同，差别只是表达方式。如果你的项目里已经在用 LangChain 的生态，直接接入就好；如果是新项目，两种都可以，OpenAI SDK 版本更轻量。 怎么选：Skills、Function Calling、MCP 的边界 用了这么久，有一个绕不开的问题：这三个东西什么时候用哪个？先理清各自的定位：Function Calling：代码级函数调用。你定义函数签名，AI 决定什么时候调用它，调用后你处理结果。执行是确定的，代码写什么就跑什么。MCP（Model Context Protocol）：协议级能力接入。标准化的接口协议，让 AI 能接入各种外部系统（数据库、文件系统、第三方服务）。解决"如何连接"的问题。Agent Skills：语义级能力模块。用 Markdown 描述"做什么、怎么做、不能做什么"，AI 按照描述执行。解决"如何专业地完成"的问题。判断用哪个，看这几个维度：确定性要求高不高？ 金融交易、数据库写入、触发支付——这些场景不允许任何随机性，必须用 Function Calling。给定相同输入，一定要得到相同输出。需不需要快速迭代？ 如果你还在验证阶段，需求每周都在变，Agent Skills 的优势很明显。改 Markdown 比改代码快，也不需要重新部署。等流程稳定了，再考虑要不要换成 Function Calling。团队里有没有非技术人员？ 产品经理、运营想定义工作流，但不会写代码——Agent Skills 是唯一的选项。描述清楚流程和规则，就能用起来。需不需要跨平台复用？ 同一套能力要在多个 AI 系统里用，MCP 的标准化协议价值才体现出来。如果只在一个系统里用，MCP 的开发成本未必值得。实际项目里，这三个通常是组合使用的：高层工作流用 Skills，底层精确操作用 Function Calling，跨系统集成用 MCP。 不是非此即彼，是各司其职。 生产环境里最容易踩的四个坑 最后说一些真正上线之后才会遇到的问题。坑一：路由瘫痪——Skills 互相打架当你的 Skill 库积累到几十个，如果各个 Skill 的 description 语义重叠，Agent 就会开始"选择困难"。用户说"处理这个文件"，Agent 在 file-processor、document-analyzer、data-extractor 之间反复横跳。解法：每个 Skill 的 description 要有清晰的边界，而且要加"负向触发器"——明确写出"本 Skill 不处理 X 类任务"。比如：description: | 当用户需要提取文本或处理 PDF 结构时使用。 不用于处理纯文本文件或代码仓库扫描。坑二：上下文隐性膨胀Skill 里定义了"读取 references/ 目录下的文档"，但没有限制读取量。执行时 Agent 把整个目录的内容全加载进来，几万 Token 一下就打满了。解法：在 SKILL.md 里明确限制："每次最多读取 5000 Token，使用 grep 过滤后再读取，不要全量加载。"坑三：description 写成了说明书新手最常见的错误：把 description 写得很详细，一段话解释背景、功能、使用场景、注意事项。结果适得其反——description 太长太复杂，路由器反而判断不准了。description 要短、精、关键词密度高。一两句话，清晰说明触发时机和核心能力。坑四：Skill 过了保质期Skill 里引用了某个外部接口的格式，接口升级了，Skill 没更新。或者团队的代码规范变了，Skill 里的标准没跟上。这种"静默降级"很隐蔽——系统不报错，但结果越来越偏。解法：建立定期审计机制。每隔一段时间，人工检查 Skill 的 Workflow 和 Constraints 是否还与实际情况对齐。 最后说一句 Agent Skills 不是什么革命性的新概念。它做的事情，说穿了很朴素：把专家的知识和流程，结构化地写下来，让 AI 能稳定地照着执行。就像公司有了流程手册，新人上手更快，老员工犯错更少，团队整体输出更稳定。AI 也一样。给它一本好的手册，它就能更好地工作。Prompt 是你告诉 AI"去做这件事"。Skill 是你提前准备好了"这件事怎么做"。区别就在这里。
AI摘要 本文详细解析了AI助手Agent Skills的运行全流程，从用户请求到结果返回共16步，分为任务接收、技能发现、技能执行和结果回传四个阶段。文章通过泳道图展示了7个角色和5个层次的协作过程，强调了职责边界清晰、Agent与工具解耦以及工具链支撑复杂任务的重要性。最后，提出了几个技术问题供读者思考，以深入理解Agent体系的工程逻辑。 document.addEventListener('DOMContentLoaded', function() { const urlDisplay = document.getElementById('urlDisplay'); urlDisplay.textContent = "此内容根据文章生成，更内容请访问：" + window.location.href; }); 一文看懂 Agent Skills 运行全流程：从用户请求到结果返回的 16 步拆解作者：多模态智能体发布时间：2026年6月12日 07:30原始链接：https://mp.weixin.qq.com/s/hz82vgn5n6Y8E4VSqCQKIQ你有没有想过，当你对着一个 AI 助手说"帮我分析上个月各区域的销售数据，生成一份经营报告"，它背后到底在做什么？直觉上，可能会觉得这无非就是模型接收了你的话，然后吐出一段文字。但如果这件事真的是这样完成的，那你拿到的报告大概率是一堆凭空捏造的数字。事实上，一个真正能干活的 Agent，背后跑的是一套完整的调度链路。这篇文章就从下面这张泳道图出发，把这条链路从头到尾拆清楚。 ︱一、先看全局：7 个角色，分 5 层 读泳道图有个窍门：先别急着看箭头，先看"泳道"本身——每一列代表一个角色，每个角色只做自己这一列里的事。这张图里一共有 7 个角色，从左到右排开，但它们并不是平等的。按职责层次来看，可以分成 5 层：交互决策层：用户 + Agent用户是任务的发起方，不关心背后用了什么技能，只关心最后拿到的结果。Agent 是决策中枢，负责理解意图，判断这件事能不能自己解决，解决不了的就往下传。路由调度层：Skill Router这是整张图里参与步骤最多的模块——从第②步开始介入，一直到第⑮步才完成使命。它的核心职责只有一件事：找到合适的技能，并把任务交出去。注册发现层：Skill Registry看图会发现，Skill Registry 只出现在第④⑤两步，进来、出去，干净利落。它的角色很像一本"技能目录"，被查的时候出现，查完就退场。很多文章会把它描述成一个复杂的管理系统，但从执行链路来看，它的职责其实非常单一。执行管理层：Skill Center技能找到了之后，真正负责把任务跑起来的是 Skill Center。它负责加载能力体、下发任务、汇总结果，是链路里的执行调度者。能力承载层 + 底层执行层：能力体 + 工具/引擎能力体是具体业务逻辑的载体，比如数据分析、文档总结、报告生成等等。而工具/引擎是更底层的资源，比如数据库、代码执行器、搜索接口。能力体调用工具，工具真正干活。有了这个分层概念，再回头看泳道图，箭头的流向会清晰很多。 ︱二、16 步流程，分 4 个阶段来看 图里的 16 个步骤乍看密密麻麻，但如果按流程阶段分组，结构马上就清楚了。 第一阶段：任务接收（步骤①②） ① 用户发送消息 → Agent这一步没什么好说的，就是用户输入了一个请求。值得注意的是，用户输入的往往是自然语言，比如"帮我生成一份报告"，这背后隐含了大量模糊性——分析哪些数据？什么维度？什么格式？② Agent 接收请求，并向 Skill Router 发起技能请求这一步才是真正有意思的地方。Agent 在这里需要做一个判断：这件事我自己能搞定吗？如果是"明天天气怎么样"这类简单问题，Agent 大概率直接回答，不会触发后面那 14 步。但如果是"分析数据并生成报告"，Agent 判断出这需要外部能力，于是才会把请求转发给 Skill Router。这个判断逻辑，是 Agent 系统能不能用好的关键之一。 第二阶段：技能发现（步骤③④⑤⑥） ③ Skill Router 向 Skill Registry 发起查询Skill Router 接手请求后，先要解决的问题是：现在系统里有哪些技能可以用？于是它向 Skill Registry 发起查询请求。这里要注意，③是 Skill Router 发出的查询动作，而④是 Skill Registry 内部的处理动作——两者是不同主体的行为，不能混在一起说。④ Skill Registry 查询内部技能注册表Skill Registry 里存的是每个技能的元信息：名称、适用场景、输入输出参数、版本、权限等等。收到查询请求后，它在自己的注册表里比对，找出候选技能。⑤ Skill Registry 返回技能列表把匹配到的技能列表返回给 Skill Router。注意，到这里 Skill Registry 就完成使命了，后续流程里它不会再出现。⑥ Skill Router 调用 Skill CenterSkill Router 拿到技能列表后，确定要调用哪个（或哪几个）技能，然后把请求连同目标技能 ID、任务参数、权限信息等一并转发给 Skill Center。从这一步开始，任务进入执行阶段。 第三阶段：技能执行（步骤⑦⑧⑨⑩⑪⑫） 这一阶段是整张图最核心的部分，也是原图里箭头最密集的地方。⑦ Skill Center 加载能力体Skill Center 收到请求后，根据技能 ID 找到对应的能力体，把它加载起来。这一步相当于把"一个抽象的技能"映射到"一个具体可运行的执行单元"。⑧ 能力体返回能力详情能力体加载完成后，会把自己的状态反馈给 Skill Center：当前是否可用、支持哪些参数、是否有前置条件，等等。这是一次确认握手，确保后续可以正常执行。⑨ Skill Center 下发执行任务确认能力体可用之后，Skill Center 正式向能力体下达执行指令。到这里，任务才算真正开始跑了。⑩ 能力体调用工具/引擎，工具链启动能力体在执行过程中，往往需要调用底层工具。比如数据分析能力体，可能需要先从数据库里拉数据，再调用计算模块，再调用图表生成器。图中在这一步特意画了一个循环箭头，说明工具调用不是一次就完事的，而是可能经历多轮。这就是"工具链"的含义——一个任务可以串联多个工具依次执行。⑪ 执行中（持续状态）这是图中单独标注的一个状态节点，区别于⑩的"启动动作"。它表示工具/引擎正在持续运行，可能需要一段时间才能完成。这种设计在工程上很重要，因为涉及到超时控制、状态轮询、异常中断等问题。⑫ 工具/引擎返回执行结果工具执行完毕，把结果返回给能力体。返回内容可能是原始数据、计算结果、文件链接，也可能是报错信息。 第四阶段：结果回传（步骤⑬⑭⑮⑯） 这一阶段是正向调用的镜像——结果沿着调用链原路返回，每一层都要做自己的处理。⑬ 能力体将结果返回给 Skill Center能力体拿到工具返回的原始结果后，会做一层处理：格式统一、异常兜底、多工具结果合并等，然后把处理后的结果上交给 Skill Center。⑭ Skill Center 处理结果，返回给 Skill RouterSkill Center 收到后继续处理：结果聚合、状态判断、日志记录、链路追踪等，然后交给 Skill Router。⑮ Skill Router 将结果返回给 AgentSkill Router 在这里会做最后一轮封装，确保返回格式符合 Agent 的预期，然后上交。⑯ Agent 返回最终结果给用户Agent 拿到结构化结果后，还需要做最后一件事：把它变成用户能读懂的自然语言。这不是简单转发，而是包含了语言组织、解释说明、格式调整，有时候还需要判断是否要继续追问或调用另一个技能。最终用户看到的，是一个干净、完整、可理解的答案。而背后，是 7 个模块协作跑完的 16 步。 ︱三、为什么要设计成这样？ 看完流程之后，一个自然而然的问题是：为什么不让 Agent 直接调用工具？这中间绕了这么多层，不是多此一举吗？这里有三个真正值得说的原因。第一，职责边界清晰，各管各的Skill Registry 只参与两步，Skill Router 只负责找技能，工具/引擎完全不感知上层逻辑。这种设计让每个模块都可以独立演化——你换一套工具不会影响路由逻辑，你改了注册表格式不会让能力体崩掉。第二，Agent 和工具完全解耦从图中可以看到，Agent 只和 Skill Router 交互，从头到尾没有直接碰过工具/引擎。这意味着：当你接入一个新工具，Agent 完全不需要改造。对于一个要持续扩展能力的 Agent 平台，这个属性非常关键。第三，工具链支撑复杂任务步骤⑩⑪的循环结构告诉我们，工具执行是可以迭代的，不是一次性的。这是 Agent 能处理复杂任务的底层基础——读文件、清洗数据、计算指标、生成图表、输出报告，可以是一条串联的工具链，而不需要用户一步步手动触发。 ︱四、用一个真实场景串起来 说了这么多抽象概念，用一个具体场景把整条链路走一遍： 用户输入：帮我分析上个月各区域销售数据，生成一份经营分析报告。 ①用户发送请求，②Agent 判断这需要数据分析 + 报告生成能力，向 Skill Router 发起请求。③Skill Router 查询 Skill Registry，④Skill Registry 在注册表里找到"数据分析 Skill"和"报告生成 Skill"，⑤把列表返回给 Skill Router，⑥Skill Router 携带任务参数调用 Skill Center。⑦Skill Center 加载数据分析能力体，⑧能力体确认可用，⑨Skill Center 下发执行任务。⑩能力体调用数据库工具拉取销售数据，工具链开始运转：拉数据 → 清洗 → 计算各区域指标 → 生成趋势图，⑪工具持续执行中，⑫执行完毕返回结果给能力体。⑬能力体整合结果交给 Skill Center，⑭Skill Center 处理后交给 Skill Router，⑮Skill Router 返回给 Agent，⑯Agent 把结构化的分析结果组织成一份完整的经营分析报告，呈现给用户。整个过程用户只做了一件事：说了一句话。 ︱五、留给技术读者的几个问题 如果你是做 Agent 平台的，有几个问题值得深入想：步骤⑧"返回能力详情"之后，如果能力体返回"不可用"，系统应该如何降级？是报错，还是尝试调用备用技能？这套降级策略应该定义在哪一层？Skill Registry 的技能元数据里，应该包含哪些字段才算足够用？只有名称和描述显然不够，但字段太多又会让注册和维护成本升高，边界在哪？当一个用户请求需要同时调用多个技能时，Skill Center 是串行调度还是并行调度？并行的话，结果聚合的逻辑应该怎么设计？这些问题没有标准答案，但每一个都指向真实的工程决策。 ︱六、最后说一句 Agent 体系里，"会对话"只是入场券，真正的门槛是"会执行"。这张 16 步的泳道图，说白了就是在回答一个问题：当用户说出那句话之后，系统怎么把它变成真实世界里发生的动作，然后再把结果送回来。搞清楚这条链路，才算是真正理解了 Agent 从对话入口走向任务执行平台这件事背后的工程逻辑。
AI摘要 本文推荐了五个热门的Skill，包括自我进化能力的self-improving-agent、Skill生态入口型能力的find-skills、多源内容总结工具summarize、浏览器自动化代表agent-browser和Skill安全审查刚需代表skill-vetter。这些Skill在开发调试、团队协作、内容工作流、自动化测试和安全审查等方面具有广泛的应用。 document.addEventListener('DOMContentLoaded', function() { const urlDisplay = document.getElementById('urlDisplay'); urlDisplay.textContent = "此内容根据文章生成，更内容请访问：" + window.location.href; }); 1、self-improving-agent：Agent 自我进化能力代表推荐理由：基础能力强、复用门槛低，可记录错误、吸收反馈、沉淀长期经验。 使用方法：启用后，Agent 会在失败、纠正或发现知识缺口时自动记录，如 LEARNINGS.md、ERRORS.md。 场景：开发调试中，若因依赖版本、脚本路径或 API 参数错误失败，会记录原因和修正方式，下次可先读取经验，减少重复犯错。 2、find-skills：Skill 生态入口型能力推荐理由：“找 Skill、装 Skill、扩展 Agent 能力”的入口，具备高频属性。 使用方法：用户提出需求后，Agent 判断领域，通过 npx skills find pr review 等命令搜索候选 Skill，并给出安装建议。 场景：研发团队想强化前端测试，却不确定选 Playwright、E2E还是代码审查类 Skill。find-skills 可将模糊需求转成关键词，输出候选清单。 3、summarize：多源内容总结工具推荐理由：summarize 支持网页、文件、PDF、图片、音视频、YouTube、播客等输入，是内容工作流底座。 使用方法：可用 summarize "网址" 总结网页，summarize "YouTube 链接" 总结视频；只抽取内容可用 --extract。 场景：市场团队需快速消化报告和竞品视频时，Agent 可处理 PDF、网页等，输出统一摘要和关键观点。 4、agent-browser：浏览器自动化代表推荐理由：让 Agent 从“回答问题”升级为“操作网页”，是自动化、测试、表单填写、网页数据抽取等场景的基础组件。 使用方法：安装 CLI 后，Agent 可基于网页快照识别元素，执行打开页面、点击、输入、提交、截图、抽取内容等动作。 场景：运营团队每天需登录多个后台查看订单、广告、库存或线索数据。agent-browser 可自动进入页面、填写筛选条件并提取结果。 5、skill-vetter：Skill 安全审查刚需代表推荐理由：安全类 Skill 数量少但下载量高，说明用户安装第三方 Skill 时关注权限、脚本和外部连接风险。 使用方法：安装陌生 Skill 前，让 Agent 读取其 SKILL.md 或仓库内容，检查作者、权限、curl、wget、混淆字符串、敏感目录读取等风险。 场景：用户想安装“加密货币自动交易”类 Skill，但其要求网络访问和 shell 执行权限。skill-vetter 可先输出安全审查报告，提示密钥读取、未知域名、远程脚本等风险。AlphaMoat ｜ 用数据寻找长期复利🌐 AlphaMoat.ai📧 sales@alphamoat.ai
一万字Codex保姆级教程：小白从安装到跑通项目
AI摘要 这篇文章是一份详尽的Codex新手教程，旨在帮助初学者从安装到运行项目。文章首先强调了Codex不仅仅是一个聊天工具，而是一个能够直接操作项目文件的工作助手。接着，作者详细介绍了Codex的不同使用方式，并建议新手从Codex App开始。文章还提供了关于安装、基础设置、项目文件夹创建和配置的指导，包括如何编写README.md、AGENTS.md和CONTEXT.md文件。此外，还讨论了插件、Skills和MCP的理解和使用，以及如何在VS Code中使用Codex。最后，文章通过一个AI工具资料整理项目的实例，展示了如何跑通第一个真实项目，并提供了一个启动检查清单，以确保新手能够顺利开始使用Codex。 document.addEventListener('DOMContentLoaded', function() { const urlDisplay = document.getElementById('urlDisplay'); urlDisplay.textContent = "此内容根据文章生成，更内容请访问：" + window.location.href; }); 1.1万字 Codex保姆级教程：小白从安装到跑通项目作者：AI778发布时间：2026年5月16日 21:24https://mp.weixin.qq.com/s/DuIOd6qLH8_4_3iP9XKXwg最近我发现Claude+deepseek还是差点意思，就转到codex体验一下顶级模型。但是，习惯了终端中使用Claude code之后，打开codex之后，我竟然不知道怎么用！相信很多朋友跟我一样，第一次打开 Codex，第一反应不是“哇，好强”，而是：这东西到底从哪开始用？它看起来像一个聊天软件，但又能读文件、改项目、开浏览器、装插件、跑命令、接 MCP。软件界面的左边是一堆入口，中间是对话，右边还会弹出文件、网页、预览、代码变化。如果你是小白，很容易犯一个错误：什么都没配置好，就直接让它干活。最后不是文件乱飞，就是不知道产物放哪（我整理乱糟糟的文件，头都大了！大家一定注意一些）；不是插件装了一堆不会用，就是项目里没有任何规则，Codex 每次都要重新理解你。所以这篇教程，只讲新手第一次真正上手时最需要配置的东西。我们只解决一个问题：一个 Windows 小白，怎么把 Codex 从“能聊天”，配置到“真的能做项目”。看完这篇，你至少应该能完成三件事：知道 Codex 可以在哪些地方用。在 Windows 上建立一个适合 Codex 工作的项目文件夹。配好基础规则、插件、Skills，并跑通一个真实项目。先说结论：新手第一次用 Codex，最该先配置的不是模型，而是项目文件夹。一、先别急着提问：Codex 不是普通聊天框如果你只把 Codex 当成 ChatGPT 的另一个入口，那它确实就是一个聊天框。但 Codex 真正厉害的地方，不是“回答问题”，而是“直接进入项目文件，扮演你的工作助手帮你做事”。它可以做这些事：读取你指定的本地文件。修改项目里的文档和代码。运行终端命令。打开网页查资料。通过插件处理文档、表格、PPT。用 Skills 按固定流程完成任务。通过 MCP 连接外部工具。在 IDE 或云端继续处理项目。这也是为什么新手会懵。普通聊天工具不会随便碰你的本地文件，但 Codex 会。普通聊天工具通常只给你答案，但 Codex 可能会真的帮你新建文件、改文件、生成项目、跑脚本。能力越强，越需要边界。所以小白要先建立一个最重要的意识：不要一上来就问“Codex 能做什么”，先问“我准备让它在哪个项目里做事”。项目位置选错了，后面全乱。二、Codex 到底能在哪些地方用截至 2026-05-16，OpenAI 官方资料里提到，Codex 可以在多个入口使用，比如 App、CLI、Web/Cloud、IDE extension 等。具体入口和按钮名称会更新，你以自己当前看到的界面为准。小白先看这张表就够了：使用方式解释适合谁小白建议Codex App装在电脑上的 Codex 工作台想管理本地项目的人主推，从这里开始Codex Web / Cloud在网页或云端委托任务想让任务离开本地持续跑的人后面再学Codex CLI命令行里的 Codex会终端的人小白先不用IDE / VS Code 扩展在代码编辑器里用 Codex写代码、改网页、改项目的人有项目后再用GitHub 里的 Codex在代码仓库里委托任务管 GitHub 仓库的人后期再学这篇文章只重点讲一条路线：Windows 上用 Codex App，把项目真正跑起来。为什么不一上来讲 CLI、GitHub、云端？因为小白最先要解决的不是“入口不够多”，而是“我到底该把文件放哪、规则怎么写、权限怎么给、结果怎么看”。把本地 App 这条路跑通，后面去 VS Code、Cloud、GitHub 都会顺很多。三、Windows 上怎么安装 Codex App安装这件事本身不复杂，最重要的是别乱下载。建议只从 OpenAI 官方入口下载：https://openai.com/codex/基本流程是：打开官方入口。下载 Windows 版 Codex App。按提示安装。打开 Codex。用 ChatGPT / OpenAI 账号登录。如果你已经习惯用 Windows 终端，也可以用官方文档提到的 winget 方式安装。先打开 PowerShell，再执行：winget install Codex -s msstore如果你后面要让 Codex 改网页、跑脚本、处理代码项目，建议顺手装几个常用工具。OpenAI Windows 文档也提到，Git、Node.js、Python 这类开发工具会让 Codex 做项目更顺。可以先装这三个：winget install --id Git.Git winget install --id OpenJS.NodeJS.LTS winget install --id Python.Python.3.14装完以后，重启 Codex App 或重新打开终端，再让 Codex 检查：git --version node --version python --version如果你只是体验，优先用账号登录，不要一上来研究 API Key。免费账号能不能用，要看当时官方开放策略和额度。长期使用，通常还是建议至少准备 Plus 或更高套餐。因为 Codex 一旦进入项目、读文件、改文件、跑长任务，消耗会比普通聊天更明显。小白成功标志：你已经能打开 Codex App。你已经登录账号。你能新建一个普通对话。你能看到项目或类似项目入口。到这里，先别急着让它改文件。先做设置。四、第一次打开后，先做 5 个基础设置Codex 的设置会随着版本变化，但小白可以先关注 5 类设置。你不需要把每个按钮都研究透。先把最影响使用体验和安全边界的地方搞清楚。1. 语言和回答风格：先让它按小白方式说话如果 Codex 支持个性化、自定义说明、偏好设置之类的入口，可以先写一段固定说明。你可以直接复制这一段：请默认用中文回答。 如果涉及代码或命令，请先用大白话解释目的，再给具体操作。 如果要修改文件、运行命令、访问外部账号，请先告诉我风险。 教程类内容请写成小白能照着做的步骤，并标注每一步的成功标志。 如果我的需求信息不完整，请先问我缺什么，不要直接编。这段话的作用很大。它不是让 Codex 变强，而是让 Codex 更适合你。小白最怕的不是 AI 不会做，而是它一上来就抛术语、跑命令、改文件，你完全不知道发生了什么。2. 权限：不要一上来开放整个硬盘Codex 会请求权限，比如读文件、改文件、运行命令、访问网页、连接账号。新手最容易犯的错误是：看到确认按钮就点。不要这样。第一次使用，建议只给当前项目文件夹权限。比如你要做网页工具项目，就只让 Codex 访问这个项目目录：D:\codex_projects_by_jack\网页工具项目不要一上来给：C:\ D:\ 整个用户目录 下载目录 个人文件夹 桌面全部文件如果看不懂权限请求，就直接问 Codex：请用小白能懂的话解释：你现在请求的权限会访问什么？为什么这个任务需要它？有没有更低风险的做法？3. 发送方式：避免写长需求时误发送如果设置里有“Enter 发送”或“组合键发送”之类的选项，建议新手选择不容易误触的方式。因为你后面写项目需求时，经常会写很长：项目目标。输出格式。不要做什么。目录结构。验证方式。如果写一半按回车就发出去了，Codex 可能会拿着半截需求开始干活。（我吃了很多次亏才想起来要设置一下）4. 模型和推理强度：先默认，复杂任务再提高小白不需要一上来研究每个模型。建议：普通问答：默认即可。长文写作：用更强模型或更高推理。代码修改、复杂项目：用更强模型或更高推理。简单格式整理：不用开太高。一句话：小任务别浪费额度，大任务别省过头。5. 自动化先别急自动化听起来很诱人：每天自动总结。每周自动检查。定时抓资料。到点继续写文章。但新手别急。先把手动流程跑通，再自动化。如果你手动都没说清楚“输入是什么、输出到哪里、失败怎么办”，自动化只会把混乱定时重复一遍。五、真正开始前，先建一个项目根目录这一步是全文最重要的地方。小白用 Codex，第一件事不是装插件，而是建立项目根目录。你可以建一个这样的文件夹：D:\codex_projects_by_jack或者更简单：D:\codex_projects这个目录以后专门放 Codex 项目。不要把项目直接放在：桌面。下载目录。聊天软件接收文件夹。笔记库内部。同步盘里随手建的杂乱目录。系统盘乱七八糟的位置。为什么？因为 Codex 会读文件、写文件、生成中间数据、跑脚本。例如，如果你把项目塞进日常笔记库，它可能把一堆日志、配置、代码、缓存都放进去。笔记库就被污染了。如果你把项目放桌面，时间久了你会分不清哪些是成品、哪些是临时文件。如果你把项目散在下载目录，三个月后你自己都找不到。所以先建一个干净的项目根目录。如果你会打开 PowerShell，可以直接复制这条命令：New-Item -ItemType Directory -Path "D:\codex_projects_by_jack" -Force这条命令的意思是：在 D 盘创建一个叫 codex_projects_by_jack 的文件夹；如果它已经存在，就不重复创建，也不会报错。小白成功标志：D:\codex_projects_by_jack下面只放项目，不放随手下载的东西。六、第一个项目文件夹应该长什么样有了项目根目录，每个新项目再建一个独立文件夹。比如：D:\codex_projects_by_jack\项目1 D:\codex_projects_by_jack\项目2 D:\codex_projects_by_jack\项目3新项目推荐结构：我的第一个Codex项目/ README.md AGENTS.md CONTEXT.md docs/ src/ scripts/ data/ raw/ processed/ export/ assets/ logs/ tmp/如果你想一次性建好这些文件夹，可以在 PowerShell 里执行：$project = "D:\codex_projects_by_jack\我的第一个Codex项目" New-Item -ItemType Directory -Path $project -Force New-Item -ItemType Directory -Path "$project\docs","$project\src","$project\scripts","$project\data\raw","$project\data\processed","$project\data\export","$project\assets","$project\logs","$project\tmp" -Force New-Item -ItemType File -Path "$project\README.md","$project\AGENTS.md","$project\CONTEXT.md" -Force执行完之后，你应该能在资源管理器里看到这个项目文件夹。你不一定每个目录一开始都用得上，但先知道它们干什么。文件/目录大白话解释README.md给人看的项目说明AGENTS.md给 Codex 看的工作规则CONTEXT.md给 Codex 看的业务背景docs/长期说明、方案、运行手册src/正式代码scripts/采集、清洗、维护脚本data/raw/原始数据，不要乱改data/processed/处理后的中间结果data/export/最终导出成果assets/图片、模板、素材logs/运行日志tmp/临时文件如果你不是程序员，也不用怕 src、scripts 这些词。它们只是帮你把项目分区。真正关键的是三个文件：README.md AGENTS.md CONTEXT.md这三个文件写好，Codex 就不会每次都像第一次见你。七、README.md 怎么写：让未来的你也能看懂README.md 是给人看的。不是写给 AI 炫技的，是写给未来的你。一个最简单的 README 可以这样写：# 项目名称 这个项目用于： ## 快速开始 1. 把原始素材放到 data/raw/ 2. 运行脚本或让 Codex 处理 3. 最终结果输出到 data/export/ ## 目录说明 - docs/：说明文档 - data/raw/：原始数据 - data/export/：最终结果 - logs/：运行日志 ## 常用命令 暂无。 ## 注意事项 - 不要删除 data/raw/ - 不要把真实密钥写进文档README 的目的不是漂亮，而是让你下次打开项目时知道：这项目是什么，怎么用，文件放哪。八、AGENTS.md 怎么写：让 Codex 不再每次重新理解你AGENTS.md 是给 Codex 看的。你可以把它理解成“项目里的工作规则”。它告诉 Codex：这个项目目标是什么。哪些文件不能动。修改前要不要先说明。修改后怎么验证。输出应该放在哪里。小白可以先写一个很短的版本：# 项目协作规则 ## 项目目标 这个项目用于： ## 不要改动 - 不要删除 data/raw/。 - 不要展示 .env 中的真实密钥。 - 不要把临时文件放到项目根目录。 ## 工作方式 - 修改前先说明准备改什么。 - 修改后做最小验证。 - 如果新增运行方式，同步更新 README.md。 ## 常用命令 - 启动： - 验证：很多人第一次用 Codex，项目体验不好，不是因为模型不行，而是因为项目没有规则。你每次都临时告诉它“不要删这个”“输出放那里”“先问我再改”，当然累。写进 AGENTS.md，就是把这些长期规则固定下来。注意，这里只写 Codex 自己会读取、会影响当前项目协作方式的规则文件。其他工具的专属规则文件，不放进这篇文章里展开。九、CONTEXT.md 怎么写：让 Codex 知道业务背景AGENTS.md 管“怎么工作”。CONTEXT.md 管“这个项目是什么”。比如你做一个 AI 工具资料整理项目，Codex 需要知道：这个项目要整理什么资料。目标读者是谁。原始链接放在哪里。体验记录放在哪里。最终报告放在哪里。哪些信息不能编造。可以这样写：# 项目上下文 ## 一句话说明 这个项目用于整理 AI 工具资料，把零散链接、使用记录和测试结果整理成可读的 Markdown 报告。 ## 目标读者 - 想选择 AI 工具的普通用户 - 想提高效率的办公人群 - 不想看一堆官网宣传语的人 ## 输入 - 工具链接 - 网页摘录 - 使用体验 - 截图描述 - 价格、平台和限制信息 ## 输出 - 工具对比表 - 每个工具的优缺点 - 适合场景 - 不适合场景 - 最终选择建议 ## 写作要求 - 不写空泛宣传。 - 不确定的信息标注“待核实”。 - 多写真实任务和使用场景。 - 不要编造工具功能、价格和亲测体验。 ## 当前状态 正在搭建 AI 工具资料整理流程。你看，这些信息如果不写，Codex 也能写，但很容易写偏。写了之后，它就知道你不是要一篇泛泛而谈的介绍，而是要一份“普通用户今天就能拿来做选择”的资料整理报告。十、插件怎么理解：给 Codex 装能力包现在来说插件。小白最容易把 Plugin、Connector、Skill、MCP 混在一起。先别纠结技术定义，看这张表：名词小白理解什么时候用Plugin 插件给 Codex 装能力包做表格、PPT、文档、浏览器操作Connector 连接器连接外部账号Gmail、GitHub、Google DriveSkill 技能工作流说明书固定写作流程、项目规范、测评流程MCP外部工具通道连接更专业的本地或远程工具你刚开始不需要全懂。记住一个顺序：先用 App 自带能力 → 不够再装插件 → 重复任务沉淀成 Skill → 特殊工具再考虑 MCP不要一上来装一堆插件。插件不是越多越强，而是越明确越好。比如：你要做 PPT，再考虑 Presentations。你要处理 Excel，再考虑 Spreadsheets。你要读写 Google Drive，再考虑 Google Drive Connector。你要操作浏览器，再考虑 Browser 或 Chrome 相关能力。每次只为一个明确任务装一个插件。十一、Skills 怎么用：不是魔法，是工作流说明书Skill 很容易被说玄。其实它最适合小白理解成：一套固定工作流说明书。比如你经常让 Codex 整理工具资料，每次都要说：先问我缺什么信息。再判断哪些资料已经够用。再整理资料。再生成对比表。再写 Markdown 报告。最后检查哪些信息还需要核实。你每次都打一遍，很麻烦。那就可以把它写成一个 Skill 或项目内流程文件。以后你只要说：请按 AI 工具资料整理流程处理这个任务。Codex 就知道要先问信息缺口，而不是上来就生成最终报告。Skill 适合这些任务：新项目初始化。PPT 生成流程。文档审校流程。数据清洗流程。小白先不需要自己写复杂 Skill。你可以先在项目里建一个 workflow.md，把流程写清楚。等你反复用很多次，再考虑沉淀成正式 Skill。比如 AI 工具资料整理项目里，可以先建：D:\codex_projects_by_jack\AI工具资料整理\workflow.md然后写一条很简单的流程：# AI 工具资料整理流程 1. 先判断信息是否完整。 2. 信息不完整时，先问 3-7 个问题。 3. 再整理资料。 4. 再生成工具对比表。 5. 再写 Markdown 报告。 6. 最后检查事实风险和待核实信息。以后你就可以对 Codex 说：请读取 workflow.md，并按这个流程整理 input\tools.md。十二、MCP 怎么理解：小白先知道，不必急着装MCP 是 Model Context Protocol。这名字听起来很吓人。小白可以先这样理解：MCP 是让 Codex 连接外部工具或外部资料的一种通道。比如 OpenAI 官方有开发者文档 MCP，可以让 Codex 在 CLI 或 IDE extension 里读取 OpenAI 相关文档。官方文档里也给了添加和验证的命令。如果你只是想知道“命令长什么样”，可以先看这个例子：codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp codex mcp list第一行是添加 OpenAI 开发者文档 MCP，第二行是查看当前 MCP 列表。如果你是在 VS Code 里配置，也可以在项目根目录新建：.vscode\mcp.json内容示例：{ "servers":{ "openaiDeveloperDocs":{ "type":"http", "url":"https://developers.openai.com/mcp" } } }但注意：如果你还没装 Codex CLI，或者看不懂 MCP 配置文件，就先不要急着执行。小白阶段知道它的用途，比立刻装上更重要。但对大多数小白来说，前期不用急着配 MCP。为什么？因为你一开始最需要的是：建好项目文件夹。写好 README。写好 AGENTS。写好 CONTEXT。学会看权限。学会让 Codex 解释它做了什么。这些都不需要 MCP。所以小白顺序还是那句：插件优先，Skill 其次，MCP 最后。什么时候再研究 MCP？你明确知道要接哪个工具。官方插件满足不了。你需要在 VS Code / CLI 里接入某个资料源。你能看懂基本配置文件。十三、Chrome / 浏览器到底能不能用这个问题要分清三层。第一层：Codex App 里的浏览器能力。它可以打开网页、查看页面、搜索资料、测试本地网页。有些时候右侧会出现网页预览或浏览器界面。第二层：Browser / Chrome 相关插件或能力。如果你的 Codex 环境里有 Browser 或 Chrome 相关插件，它可能可以操作浏览器页面，甚至使用你已经登录的账号状态。具体能力取决于你当前安装和授权的插件。第三层：真实账号操作风险。这才是小白最该注意的。浏览器能力很强，但不要第一次就让它操作：聊天软件。支付页面。内容发布后台。电商后台。公司系统。会删除、发布、付款的页面。第一次练习，可以让它做低风险任务：打开一个公开网页，帮我总结页面结构。或者：打开我本地生成的网页，检查按钮有没有重叠。成功标志：Codex 能打开或查看页面。它没有进行付款、发布、删除等高风险动作。它能告诉你它看到了什么。十四、VS Code 里怎么用 Codex如果你完全不写代码，先不用急着打开 VS Code。Codex App 已经足够你做：写文章。整理资料。做文档。处理表格。生成 PPT。管理项目。那什么时候需要 VS Code？当你开始让 Codex 做这些事：改网页。写脚本。改代码项目。做插件。改复杂配置。看很多文件之间的关系。VS Code 更像代码项目的工作现场。Codex App 更像项目管理和多任务工作台。两者可以服务同一个项目文件夹。比如你的项目在：D:\codex_projects_by_jack\我的第一个Codex项目你可以：用 Codex App 打开这个项目，让它理解需求。用 VS Code 打开同一个文件夹，看文件结构。如果你安装了官方 Codex IDE extension，就可以在 VS Code 里继续让 Codex 辅助修改。如果你已经安装 VS Code，也可以用命令打开项目：code "D:\codex_projects_by_jack\我的第一个Codex项目"如果这条命令提示 code 不存在，说明 VS Code 的命令行入口还没配置。小白不用纠结，直接在 VS Code 里点：File → Open Folder → 选择 D:\codex_projects_by_jack\我的第一个Codex项目小白路线：先用 Codex App → 项目变复杂后，再用 VS Code 打开同一文件夹 → 真要改代码，再研究 IDE extension不要为了“看起来专业”一上来就进 VS Code。工具是为任务服务的。十五、跑通第一个真实项目现在我们来跑一个最小真实项目。不要一上来做复杂网站。我们用一个“AI 工具资料整理项目”举例。这个项目很适合新手练手。它不涉及真实账号，也不需要连接复杂后台。你只要准备几个工具链接、几段使用记录，Codex 就能帮你整理成对比表、使用建议和 Markdown 报告。这类项目的好处是：文件结构简单。不需要写很多代码。能练习项目目录、规则文件、资料输入、结果输出。做完之后真的有用。第一步：建项目文件夹在你的项目根目录下建：D:\codex_projects_by_jack\AI工具资料整理里面建这些目录：AI工具资料整理/ README.md AGENTS.md CONTEXT.md input/ notes/ output/ logs/ tmp/可以直接用 PowerShell 一次建好：$project = "D:\codex_projects_by_jack\AI工具资料整理" New-Item -ItemType Directory -Path $project -Force New-Item -ItemType Directory -Path "$project\input","$project\notes","$project\output","$project\logs","$project\tmp" -Force New-Item -ItemType File -Path "$project\README.md","$project\AGENTS.md","$project\CONTEXT.md" -Force这几行命令做了三件事：创建项目主文件夹。创建输入、笔记、输出、日志、临时文件目录。创建 README.md、AGENTS.md、CONTEXT.md 三个关键文件。如果你不想用命令，也可以手动新建。效果一样。第二步：写 README.md# AI 工具资料整理 这个项目用于整理 AI 工具资料，把零散链接、笔记和测试结果整理成可读的 Markdown 报告。 ## 目录 - input/：原始链接、网页摘录、截图说明 - notes/：手动记录的使用体验 - output/：Codex 整理后的报告 - logs/：处理记录 - tmp/：临时文件 ## 使用方式 1. 把工具链接和原始材料放到 input/ 2. 把自己的体验记录放到 notes/ 3. 让 Codex 读取项目规则并整理 4. 最终报告输出到 output/第三步：写 AGENTS.md# 项目协作规则 ## 项目目标 帮助我把 AI 工具资料整理成结构清晰、可复用的 Markdown 报告。 ## 工作方式 - 先读取 README.md、AGENTS.md、CONTEXT.md。 - 信息不完整时，先问我缺什么。 - 不要编造工具功能、价格、链接和使用体验。 - 不确定的信息标注为“待核实”。 - 输出报告放到 output/。 - 临时分析放到 tmp/。 ## 禁止事项 - 不要删除 input/ 和 notes/ 里的原始材料。 - 不要泄露任何账号、Cookie、API Key 或私人文件路径。 - 不要把未验证的信息写成确定结论。第四步：写 CONTEXT.md# 项目上下文 ## 项目用途 把多个 AI 工具的资料整理成一份普通用户能看懂的对比报告。 ## 目标读者 - 想选择 AI 工具的普通用户 - 想提高效率的办公人群 - 不想看一堆官网宣传语的人 ## 整理要求 - 先说这个工具解决什么问题。 - 再说适合谁、不适合谁。 - 如果有价格、平台、限制，要单独列出。 - 不确定的信息不要猜，标注“待核实”。 - 最后给出场景化选择建议。 ## 输出要求 - 工具对比表 - 每个工具的优缺点 - 适合场景 - 不适合场景 - 最终选择建议第五步：放入一份原始资料比如放到：input\tools.md这个文件可以很简单，像这样：# 待整理工具 ## 工具 A 官网： 我知道的信息： - ## 工具 B 官网： 我知道的信息： - ## 工具 C 官网： 我知道的信息： -如果你已经有一份资料，可以复制到这个目录。命令示例：Copy-Item-LiteralPath"D:\你的原始资料\tools.md"-Destination"D:\codex_projects_by_jack\AI工具资料整理\input\tools.md"看不懂也没关系，手动复制文件也完全可以。第六步：让 Codex 开始工作你可以这样说：请先阅读 README.md、AGENTS.md、CONTEXT.md。 然后读取 input\tools.md。 按项目规则，先告诉我这份资料还缺哪些信息，不要直接生成最终报告。这句话很重要。它会强制 Codex 先做信息补全，而不是一上来生成一份看似完整、其实很多地方靠猜的报告。等它问完缺口，你再补一句：请基于已确认资料，生成一份 Markdown 报告，放到 output\AI工具对比报告.md。 报告里必须包含：工具对比表、适合谁、不适合谁、使用门槛、最终选择建议。 不确定的信息请标注“待核实”。成功标志：Codex 能读到你的项目文件。Codex 会先问你缺什么。它不会编造工具功能或使用体验。它知道输出应该放到哪里。output/里出现一份结构清晰的 Markdown 报告。这就叫项目开始跑起来了。十六、小白最容易踩的 10 个坑1. 没建项目文件夹就开始干活结果就是文件到处飞。先建项目，再开始。2. 把项目放进日常笔记库或同步盘如果只是普通 Markdown 笔记，放进去没问题。但如果这个项目会运行脚本、生成数据、下载文件、写日志，最好单独放到项目目录。否则几天后你会发现，笔记、缓存、日志、临时文件混在一起，很难收拾。3. 没写 AGENTS.mdCodex 每次都要重新猜你想怎么工作。4. 没写 CONTEXT.mdCodex 不知道项目背景、目标用户、输出格式和边界条件。5. 看到权限确认就点这是最危险的习惯。不懂就问它解释。6. 插件装太多插件不是越多越好。先明确任务，再装插件。7. 把 API Key 写进 Markdown不要把密钥、Cookie、密码写进 README、AGENTS、CONTEXT。真实配置放 .env，并且不要公开。8. 不看右侧文件变化Codex 改了什么文件，你要看。看不懂就让它解释：请按文件逐个解释这次改动，用非程序员能懂的话说。9. 结果不满意就重开不要动不动重开。直接让它基于现有结果改：保留现在结构，但把每个工具的适合场景写得更具体，并补充“不适合谁”。10. 不做最小验证每次完成后，至少问一句：请告诉我这次怎么验证结果是成功的。十七、Codex 小白启动检查清单最后给你一张清单。第一次用 Codex，照着勾就行。## Codex 小白启动检查清单 - [ ] 我已经从官方入口安装 Codex。 - [ ] 我知道 Codex App、Web、CLI、VS Code 大概区别。 - [ ] 我有一个独立项目根目录。 - [ ] 我每个项目都有单独文件夹。 - [ ] 项目里有 README.md。 - [ ] 项目里有 AGENTS.md。 - [ ] 项目里有 CONTEXT.md。 - [ ] 我知道插件、Skill、MCP 的区别。 - [ ] 我不会随便授权整个硬盘。 - [ ] 我知道输出文件应该放在哪里。 - [ ] 我会让 Codex 先问缺什么，而不是直接编。 - [ ] 我会让 Codex 解释它改了什么。如果这张清单你都能勾上，恭喜你，你已经不是“打开 Codex 只会聊天”的小白了。你已经开始把它当成一个真正的项目助手。结语Codex 最容易被低估的地方，不是它会不会写代码。而是它能不能进入你的真实工作流。对小白来说，真正的分水岭不是会不会写提示词，而是有没有建立项目意识。你有一个干净的项目根目录。你知道每个项目都有独立文件夹。你知道 README 给人看，AGENTS 给 Codex 看，CONTEXT 给项目背景。你知道插件不是乱装，Skill 是工作流，MCP 是进阶工具通道。你知道权限要谨慎，结果要验证，文件变化要看。到了这一步，Codex 就不再只是一个聊天框。它会慢慢变成你电脑里的工作台。先别急着追求高级玩法。先把第一个项目跑通。从一个干净的文件夹开始。事实核查备注本文涉及 Codex 支持平台、App、IDE extension、MCP 等内容，基于 2026-05-16 前后 OpenAI 官方公开资料和当前 Codex App 使用经验整理。Codex 更新很快，具体按钮名称、插件入口和可用功能以你当前账号和官方界面为准。
AI摘要 松果大佬@songguoxiansen开发了一个神级Skill，将Claude Code变成了AI视频提示词大师，专门为字节的Seedance 2.0写提示词。这个Skill通过一个Markdown文件实现，零代码、零服务器、零成本。用户只需描述视频创意，Claude会确认参数并生成2-3个版本的提示词，然后用户可以选择一个版本用于Seedance 2.0。这个Skill大大降低了使用Seedance 2.0的门槛，可以用于电商产品视频、短剧/故事视频、知识科普视频、MV/音乐视频和仙侠/动画等多种场景。项目开源地址为：https://github.com/songguoxs/seedance-prompt-skill。 document.addEventListener('DOMContentLoaded', function() { const urlDisplay = document.getElementById('urlDisplay'); urlDisplay.textContent = "此内容根据文章生成，更内容请访问：" + window.location.href; }); 卧了个槽，又搞到一个神级 Skill！！！松果大佬@songguoxiansen把 Claude Code 变成了 AI 视频提示词大师，专门给字节的 Seedance 2.0 写提示词！你知道现在 AI 生视频最大的痛点是啥吗？不是工具不行，是提示词写不好啊！！！同样的 Seedance 2.0，别人生出来的视频是电影级，你生出来的像 PPT 动画😂这个 Skill 直接把 Claude 调教成视频提示词工程师，你只需要说人话，它帮你翻译成 Seedance 能懂的结构化提示词！！！核心思路超简单：一个 Markdown 文件搞定一切，零代码、零服务器、零成本！【第一步：理解 Seedance 2.0 的提示词规则】要解决的问题：Seedance 2.0 的提示词有自己的语法规则，普通人根本记不住开发思路：研究 Seedance 2.0 官方文档，整理出所有支持的参数和语法把 @图片、@视频、@音频 这套引用系统摸透总结出时间戳分镜、负面提示词、多段拼接等高级技巧让AI帮你写代码的Prompt：帮我整理 Seedance 2.0视频生成平台的所有提示词规则，包括：多模态引用语法（@图片/@视频/@音频）、时间戳分镜格式、技术参数（宽高比/帧率/调色）、负面提示词用法，输出为结构化的Markdown 文档【第二步：设计 SKILL.md 核心文件】要解决的问题：怎么让 Claude 理解用户的自然语言，然后输出专业的视频提示词开发思路：定义 Claude 的角色：AI 视频提示词工程师设计十大核心能力：纯文本生视频、角色一致性、镜头复刻、特效复刻、分镜生成、视频延展、声音克隆、长镜头、视频编辑、音乐同步针对不同场景（电商、短剧、仙侠、科教、MV）写专门的提示词策略设计参数确认流程，让 Claude 主动问用户要关键信息让AI帮你写代码的Prompt：帮我设计一个 Claude Code SKILL，角色是 Seedance 2.0视频提示词工程师。需要支持10种核心能力（纯文本生视频、角色一致性控制、镜头运动复刻等），每种能力要有对应的提示词模板。还要支持5种场景策略（电商广告、短剧、仙侠动画、科教、MV），每种场景有专门的提示词结构【第三步：部署和使用】要解决的问题：怎么让用户最快速度用上这个 SKILL开发思路：克隆仓库，把 SKILL.md 复制到 .claude/skills/seedance/ 目录全局安装放 ~/.claude/skills/seedance/，所有项目都能用用 /seedance 命令触发，或者直接说视频相关的话题自动激活使用流程超简单：描述你的视频创意（用人话就行）Claude 确认参数（时长、比例、风格）生成 2-3 个版本的提示词挑一个丢进 Seedance 2.0 就完事了！【踩坑提醒】Seedance 2.0 不支持真人面部：别想着生成真人视频，平台限制！用动画风格或者产品展示更靠谱单段视频最长15秒：超过15秒要用多段拼接方案，SKILL 会自动帮你规划分段参考素材有限制：图片最多9张（每张<30MB）、视频最多3个（2-15秒，<50MB）、音频最多3个（≤15秒，<15MB）输出分辨率最高2K：够用了，但别指望4K【成本算一下】SKILL 本身：免费，就一个 Markdown 文件，MIT 开源Claude Code：按 API 计费，一次对话大概 $0.01-0.05Seedance 2.0：按即梦平台计费，有免费额度服务器：零成本，不需要任何服务器总成本：几乎为零！！！【能干啥？玩法太多了】电商产品视频：产品360度旋转展示、使用场景演示，以前找视频团队拍一条要几千块，现在几毛钱搞定短剧/故事视频：自动生成分镜脚本，带对白和情绪标签，小说改编视频不是梦知识科普视频：医学CGI、解剖可视化、科学实验演示，教育博主的福音MV/音乐视频：自动对齐音乐节拍，镜头切换跟着节奏走仙侠/动画：武术动作、法术特效，网文作者可以直接把小说变成动画预告片懂 AI 视频的推友赶紧冲！！！这个 SKILL 真的是把 Seedance 2.0 的门槛直接踩到地板上了 🚀 以前写视频提示词要研究半天文档，现在说句人话就行！项目开源地址：https://github.com/songguoxs/seedance-prompt-skill