diff --git a/README.md b/README.md index 4b61fa1..1df42c0 100644 --- a/README.md +++ b/README.md @@ -54,13 +54,17 @@ CodexGuide 致力于建设一份面向真实工程流程的中文知识库：结 | [入口地图](./docs/platform/index.md) | CLI、Desktop App、Cloud/Web、IDE、ChatGPT 的选择方法 | | [安装与登录](./docs/guide/01-installation.md) | Codex CLI 安装、更新、登录和第一次进入项目 | | [第一次改代码](./docs/guide/02-first-run.md) | 选择低风险任务，并完成一次可验证修改 | -| [提示词与任务说明](./docs/guide/03-prompting.md) | 写出更稳定、更可控的 Codex 任务 | -| [真实工程工作流](./docs/guide/04-workflows.md) | 修 bug、补测试、重构、代码审查和文档生成 | +| [了解 Codex 项目和聊天](./docs/guide/03-projects-chats.md) | 认识 Project、对话和基础使用方式 | +| [任务顺序执行与并行](./docs/guide/04-task-execution.md) | 理解排队、插入引导和多任务并行 | +| [权限管理](./docs/guide/05-permissions.md) | 了解不同审批与执行模式的边界 | +| [真实工程工作流](./docs/guide/06-workflows.md) | 修 bug、补测试、重构、代码审查和文档生成 | | [配置与扩展](./docs/configuration/index.md) | CLI 选项、config.toml、MCP、Skills、Subagents、安全审批 | | [实践方法](./docs/practice/index.md) | 任务设计、非开发工作流和团队实践 | -| [AGENTS.md](./docs/guide/05-agents-md.md) | 给 Codex 编写项目级规则和协作边界 | -| [沙盒与审批](./docs/guide/06-sandbox-approvals.md) | 文件、命令、网络、凭据和生产资源的安全边界 | -| [Cloud、IDE 与 App](./docs/guide/07-cloud-ide-app.md) | 不同 Codex 使用入口的适用场景 | +| [AGENTS.md](./docs/guide/07-agents-md.md) | 给 Codex 编写项目级规则和协作边界 | +| [沙盒与审批](./docs/guide/08-sandbox-approvals.md) | 文件、命令、网络、凭据和生产资源的安全边界 | +| [技能与插件](./docs/guide/09-skills-plugins.md) | 理解 Skills、Plugins 和扩展能力 | +| [自动化](./docs/guide/10-automation.md) | 理解什么时候把重复流程交给后台执行 | +| [Cloud、IDE 与 App](./docs/guide/11-cloud-ide-app.md) | 不同 Codex 使用入口的适用场景 | | [实战案例库](./docs/recipes/index.md) | 可复制到真实项目的任务模板和复盘结构 | | [官方资料索引](./docs/reference/index.md) | OpenAI 官方资料、GitHub 仓库和关键链接 | diff --git a/docs/.vuepress/navbar.ts b/docs/.vuepress/navbar.ts index 80c6f3e..e918685 100644 --- a/docs/.vuepress/navbar.ts +++ b/docs/.vuepress/navbar.ts @@ -20,24 +20,45 @@ export default navbar([ icon: "box", children: [ { text: "实践方法", icon: "tool", link: "/practice/" }, - { text: "实战案例", icon: "lightbulb", link: "/recipes/" }, { text: "官方资料", icon: "link", link: "/reference/" }, { text: "共建路线图", icon: "people", link: "/community/roadmap.md" }, ], }, + { + text: "实战案例", + icon: "lightbulb", + children: [ + { text: "案例总览", icon: "layout", link: "/recipes/" }, + { text: "01 Codex 控制 Chrome 浏览器", icon: "chrome", link: "/recipes/chrome-browser-plugin.md" }, + { text: "02 安装并使用 PPT Skill", icon: "slides", link: "/recipes/ppt-skill-walkthrough.md" }, + { text: "03 修复一个测试失败", icon: "debug", link: "/recipes/fix-failing-test.md" }, + { text: "04 让 Codex 做代码审查", icon: "review", link: "/recipes/code-review.md" }, + { text: "05 从零补 AGENTS.md", icon: "file", link: "/recipes/agents-md-setup.md" }, + { text: "06 给旧项目补第一批测试", icon: "test", link: "/recipes/add-tests.md" }, + { text: "07 修复 CI 失败", icon: "ci", link: "/recipes/fix-ci.md" }, + { text: "08 拆分超大文件", icon: "code", link: "/recipes/refactor-large-file.md" }, + { text: "09 生成发布说明", icon: "log", link: "/recipes/generate-release-notes.md" }, + { text: "10 Codex 不适合的场景", icon: "warning", link: "/recipes/failure-scenarios.md" }, + { text: "11 官方与社区优秀案例", icon: "people", link: "/recipes/official-community-cases.md" }, + ], + }, { text: "教程", icon: "book", children: [ - { text: "安装与登录", icon: "download", link: "/guide/01-installation.md" }, - { text: "第一次改代码", icon: "code", link: "/guide/02-first-run.md" }, - { text: "提示词与任务说明", icon: "pen", link: "/guide/03-prompting.md" }, - { text: "真实工程工作流", icon: "project", link: "/guide/04-workflows.md" }, - { text: "AGENTS.md", icon: "file", link: "/guide/05-agents-md.md" }, - { text: "沙盒与审批", icon: "safe", link: "/guide/06-sandbox-approvals.md" }, - { text: "Cloud、IDE 与 App", icon: "cloud", link: "/guide/07-cloud-ide-app.md" }, - { text: "Skills 与 Automations", icon: "tool", link: "/guide/08-skills-automations.md" }, - { text: "排障手册", icon: "debug", link: "/guide/09-troubleshooting.md" }, + { text: "01 安装与登录", icon: "download", link: "/guide/01-installation.md" }, + { text: "02 第一次改代码", icon: "code", link: "/guide/02-first-run.md" }, + { text: "03 了解 Codex 项目和聊天", icon: "folder", link: "/guide/03-projects-chats.md" }, + { text: "04 任务顺序执行与并行", icon: "list", link: "/guide/04-task-execution.md" }, + { text: "05 权限管理", icon: "safe", link: "/guide/05-permissions.md" }, + { text: "06 真实工程工作流", icon: "project", link: "/guide/06-workflows.md" }, + { text: "07 AGENTS.md", icon: "file", link: "/guide/07-agents-md.md" }, + { text: "08 沙盒与审批", icon: "lock", link: "/guide/08-sandbox-approvals.md" }, + { text: "09 技能与插件", icon: "plugin", link: "/guide/09-skills-plugins.md" }, + { text: "10 自动化", icon: "time", link: "/guide/10-automation.md" }, + { text: "11 Cloud、IDE 与 App", icon: "cloud", link: "/guide/11-cloud-ide-app.md" }, + { text: "12 Skills 与 Automations", icon: "tool", link: "/guide/12-skills-automations.md" }, + { text: "13 排障手册", icon: "debug", link: "/guide/13-troubleshooting.md" }, ], }, ]); diff --git a/docs/.vuepress/sidebar/index.ts b/docs/.vuepress/sidebar/index.ts index be6f96c..46d448e 100644 --- a/docs/.vuepress/sidebar/index.ts +++ b/docs/.vuepress/sidebar/index.ts @@ -7,16 +7,20 @@ export default sidebar({ icon: "book", prefix: "/guide/", children: [ - "00-overview.md", - "01-installation.md", - "02-first-run.md", - "03-prompting.md", - "04-workflows.md", - "05-agents-md.md", - "06-sandbox-approvals.md", - "07-cloud-ide-app.md", - "08-skills-automations.md", - "09-troubleshooting.md", + { text: "00 学习路线", link: "00-overview.md" }, + { text: "01 安装与登录", link: "01-installation.md" }, + { text: "02 第一次改代码", link: "02-first-run.md" }, + { text: "03 了解 Codex 项目和聊天", link: "03-projects-chats.md" }, + { text: "04 任务顺序执行与并行", link: "04-task-execution.md" }, + { text: "05 权限管理", link: "05-permissions.md" }, + { text: "06 真实工程工作流", link: "06-workflows.md" }, + { text: "07 AGENTS.md", link: "07-agents-md.md" }, + { text: "08 沙盒与审批", link: "08-sandbox-approvals.md" }, + { text: "09 技能与插件", link: "09-skills-plugins.md" }, + { text: "10 自动化", link: "10-automation.md" }, + { text: "11 Cloud、IDE 与 App", link: "11-cloud-ide-app.md" }, + { text: "12 Skills 与 Automations", link: "12-skills-automations.md" }, + { text: "13 排障手册", link: "13-troubleshooting.md" }, ], }, ], @@ -26,7 +30,20 @@ export default sidebar({ text: "实战案例", icon: "lightbulb", prefix: "/recipes/", - children: ["index.md", "fix-failing-test.md", "code-review.md", "official-community-cases.md"], + children: [ + { text: "案例总览", link: "index.md" }, + { text: "01 Codex 控制 Chrome 浏览器", link: "chrome-browser-plugin.md" }, + { text: "02 安装并使用 PPT Skill", link: "ppt-skill-walkthrough.md" }, + { text: "03 修复一个测试失败", link: "fix-failing-test.md" }, + { text: "04 让 Codex 做代码审查", link: "code-review.md" }, + { text: "05 从零补 AGENTS.md", link: "agents-md-setup.md" }, + { text: "06 给旧项目补第一批测试", link: "add-tests.md" }, + { text: "07 修复 CI 失败", link: "fix-ci.md" }, + { text: "08 拆分超大文件", link: "refactor-large-file.md" }, + { text: "09 生成发布说明", link: "generate-release-notes.md" }, + { text: "10 Codex 不适合的场景", link: "failure-scenarios.md" }, + { text: "11 官方与社区优秀案例", link: "official-community-cases.md" }, + ], }, ], diff --git a/docs/configuration/cli-options.md b/docs/configuration/cli-options.md index fae3a48..de5c20e 100644 --- a/docs/configuration/cli-options.md +++ b/docs/configuration/cli-options.md @@ -177,3 +177,4 @@ codex exec "请阅读最近一次测试失败日志，提取失败测试名、 - Slash Commands 是观察 Codex 状态的窗口。 - 会话恢复前先写阶段总结。 - 参数变化以当前 CLI 帮助和官方文档为准。 + diff --git a/docs/guide/00-overview.md b/docs/guide/00-overview.md index ef35903..92cd544 100644 --- a/docs/guide/00-overview.md +++ b/docs/guide/00-overview.md @@ -23,9 +23,9 @@ Codex 是 OpenAI 面向软件工程与知识工作场景的代理式工作流。 | 阶段 | 目标 | 推荐页面 | 验收标准 | | --- | --- | --- | --- | | 入门 | 跑通一个低风险任务 | [安装与登录](./01-installation.md)、[第一次改代码](./02-first-run.md) | 能让 Codex 阅读仓库、修改一个小问题并运行验证 | -| 进阶 | 形成稳定任务方法 | [提示词与任务说明](./03-prompting.md)、[实践方法](/practice/) | 能写清楚目标、范围、约束、验证和交付 | -| 工程化 | 进入真实项目流程 | [真实工程工作流](./04-workflows.md)、[配置与扩展](/configuration/) | 每次改动都有 diff、测试结果和风险说明 | -| 团队化 | 沉淀规则和案例 | [AGENTS.md](./05-agents-md.md)、[团队实践](/practice/team-playbook.md) | 项目有规则文件、案例库、排障手册和贡献路径 | +| 进阶 | 形成稳定任务方法 | [了解 Codex 项目和聊天](./03-projects-chats.md)、[实践方法](/practice/) | 能写清楚目标、范围、约束、验证和交付 | +| 工程化 | 进入真实项目流程 | [真实工程工作流](./06-workflows.md)、[配置与扩展](/configuration/) | 每次改动都有 diff、测试结果和风险说明 | +| 团队化 | 沉淀规则和案例 | [AGENTS.md](./07-agents-md.md)、[团队实践](/practice/team-playbook.md) | 项目有规则文件、案例库、排障手册和贡献路径 | ## 新手推荐路径 diff --git a/docs/guide/02-first-run.md b/docs/guide/02-first-run.md index dd458f5..f88703a 100644 --- a/docs/guide/02-first-run.md +++ b/docs/guide/02-first-run.md @@ -153,4 +153,4 @@ git commit -m "fix: resolve failing test" - 一个可复用的任务模板。 - 对 Codex 权限和审批的初步理解。 -下一步继续读：[提示词与任务说明](./03-prompting.md)。 +下一步继续读：[了解 Codex 项目和聊天](./03-projects-chats.md)。 diff --git a/docs/guide/03-projects-chats.md b/docs/guide/03-projects-chats.md new file mode 100644 index 0000000..07c93cd --- /dev/null +++ b/docs/guide/03-projects-chats.md @@ -0,0 +1,19 @@ +# 了解codex-项目和聊天 + +打开codex app，我们可以看到两个选项：对话和项目 + +![image-20260510133930030](https://zzy-1326340203.cos.ap-beijing.myqcloud.com//image-20260510133930030.png?imageSlim) + +左边分为两个不同的目录，分别是 Project（项目）以及 Chat（聊天）。 + +1. Chat 聊天 + 这是最好理解的，它相当于在本地桌面 App 里面和 ChatGPT 进行对话，和我们在网页端对话的效果一模一样。这适合处理一些非常琐碎、日常的任务交流。 + +2. Project 项目 + 如果你需要让 AI 收集资料、撰写文档，或者进行一些生成式任务和文件相关的操作（比如帮你制作 PPT、写 Word 文档、写报告书，去完成一个具体的任务），那么我们就可以使用 Project。 + + 在里面创建一个新的项目后，所有与之相关的内容——无论是文档还是 PPT——都会保存在这个文件夹里，非常方便管理。我们可以创建一个空项目，也可以直接选择本地电脑里的文件夹作为项目。 + +![image-20260510134119967](https://zzy-1326340203.cos.ap-beijing.myqcloud.com//image-20260510134119967.png?imageSlim) + +这样一来，我们在项目里下达指令后，codex的修改可以直接应用到我们本地的文件和文档上。 diff --git a/docs/guide/03-prompting.md b/docs/guide/03-prompting.md deleted file mode 100644 index 0058f5d..0000000 --- a/docs/guide/03-prompting.md +++ /dev/null @@ -1,68 +0,0 @@ -# 高质量任务说明与提示词 - -Codex 的输出质量很大程度取决于任务边界。好的任务说明追求清楚、可执行、可验证。 - -## 基础结构 - -一个稳定的任务说明通常包含： - -- 背景：这个项目、模块或 bug 是什么。 -- 目标：希望完成的具体结果。 -- 范围：哪些文件或行为可以改，哪些不要动。 -- 约束：风格、兼容性、性能、安全、依赖限制。 -- 验证：要运行哪些测试、命令或手动检查。 -- 交付：最后需要总结哪些信息。 - -## 通用模板 - -```text -请处理：[一句话目标] - -背景： -- [项目或模块背景] -- [当前问题或期望行为] - -范围： -- 可以修改：[文件/目录/模块] -- 不要修改：[明确排除项] - -要求： -1. 先阅读相关代码再动手。 -2. 保持现有代码风格。 -3. 不做无关重构。 -4. 修改后运行：[验证命令] -5. 最后说明改动、验证结果和剩余风险。 -``` - -## 让 Codex 更可靠的说法 - -优先说： - -- “修改最少必要文件。” -- “先给我确认你找到的入口点，再实现。” -- “如果测试失败，继续定位并修复，直到相关测试通过或明确说明阻塞原因。” -- “不要引入新依赖，除非现有实现无法满足，并说明理由。” -- “保持公开 API 兼容。” - -少说： - -- “帮我优化一下。” -- “把项目做得更好。” -- “顺便重构。” -- “你看着办。” - -“你看着办”很省字，也很容易把范围交给命运。 - -## 大任务拆法 - -把大任务拆成三层： - -- 探索：让 Codex 只读代码、画出影响面。 -- 计划：让它提出分步方案和验证方式。 -- 实施：一次只做一个可验证切片。 - -示例： - -```text -请先不要改代码。阅读认证模块、路由和测试，找出把登录页改成双因素登录会影响哪些文件。请输出实施步骤、风险和建议的第一步最小改动。 -``` diff --git a/docs/guide/04-task-execution.md b/docs/guide/04-task-execution.md new file mode 100644 index 0000000..71e8d66 --- /dev/null +++ b/docs/guide/04-task-execution.md @@ -0,0 +1,44 @@ +# 任务的顺序执行和并行 + +本小节来介绍一下，在使用 codex 的过程中，如何进行任务顺序执行的管理以及任务的并行操作。 + +我们使用codex开发obsidian新手教程网站作为示例：来说明任务的顺序执行管理和并行操作 + +# 1.顺序执行 + +选择本地项目/创建新的项目，该项目实际上就对应我们本地的一个文件夹，它存储在我们的本地。 + +然后点击创建新的对话。 + +![image-20260510135415030](https://zzy-1326340203.cos.ap-beijing.myqcloud.com//image-20260510135415030.png?imageSlim) + +我们向 CodeX 发送任务，让他帮我们设计一个网站，这个时候他就会开始执行。 + +![image-20260510135815048](https://zzy-1326340203.cos.ap-beijing.myqcloud.com//image-20260510135815048.png?imageSlim) + +在这个任务没有执行的过程中，如果我们去给他下达新的命令，就只能等待。显示的是下面这种情况： + +![image-20260510135902883](https://zzy-1326340203.cos.ap-beijing.myqcloud.com//image-20260510135902883.png?imageSlim) + +这种相当于当前他正在执行一个任务，我们给他的另外两个命令就需要排队，必须等前面的任务执行完成之后才能执行。 + +但是如果我们想修改一下要求，比如想让他明确这个网站的背景风格为“手绘风格”，如果等他设计完成之后再去修改就会比较麻烦。我希望他在正在设计的时候就知道我的风格要求。 + +这时候，我们可以点击**引导**选项。这样操作后，他就会执行一个“插队”的操作： + +1. 原本的任务顺序： + (a) 执行网站设计 + (b) 介绍技术选型 + (c) 执行手绘风格要求（原定第三个任务） + +2. 插队后的效果： + 我们想让“手绘风格”在设计过程中就发挥作用，通过点击引导提示，这个任务就会直接插队到当前正在执行的任务当中。 + +这实际上就是通过这样一个过程，演示如何对顺序执行的任务进行管理以及相关的插队操作。 + +# 2.如何并行 + +实际上就是一个项目（Project）里面，我们同时去执行多个任务。 + +这个时候，我们只需要在左侧边栏点击“新建对话”就可以了。这样的话，它的几个任务就会并行执行，互不干扰。 + diff --git a/docs/guide/05-permissions.md b/docs/guide/05-permissions.md new file mode 100644 index 0000000..c609984 --- /dev/null +++ b/docs/guide/05-permissions.md @@ -0,0 +1,32 @@ +# 权限管理 + +这一节介绍 Codex 中常见的权限与审批模式。不同入口的界面文案可能会略有差异，但核心问题始终是一样的：Codex 能不能自动改文件、能不能自动执行命令、哪些操作需要你确认。 + +::: tip 最后核对 +官方资料最后核对日期：2026-05-10。本文参考 [OpenAI Codex CLI – Getting Started](https://help.openai.com/en/articles/11096431-openai-codex-cli-getting-started) 与 [Using Codex with your ChatGPT plan](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan)。具体名称、入口和可用选项请以你当前使用的客户端界面为准。 +::: + +![image-20260510140738323](https://zzy-1326340203.cos.ap-beijing.myqcloud.com//image-20260510140738323.png?imageSlim) + +## 三种常见模式 + +1. `Suggest` + 这是最保守的模式。Codex 可以读取文件并提出修改建议，但真正改文件或执行命令前，通常仍需要你确认。它适合初次了解陌生仓库、做代码审查、或者你希望全程掌控关键操作的时候使用。 + +2. `Auto Edit` + 这个模式通常允许 Codex 自动写文件，但在执行 shell 命令时仍会保留人工确认。它适合你已经比较了解项目结构，想让 Codex 快速完成重构、批量改文档或局部实现，但又不想完全放开命令执行权限的场景。 + +3. `Full Auto` + 这是自主性最高的模式。Codex 会在受限环境中自动读取、写入并执行命令，适合较长的连续任务，比如修复构建、跑一轮验证或完成一个边界明确的小功能。因为风险更高，最好只在版本可回退、任务范围清晰、并且你理解当前沙盒边界时使用。 + +## 怎么选更稳妥 + +- 第一次进入新项目，优先从 `Suggest` 开始。 +- 需要批量修改文档、样式或测试时，可以考虑 `Auto Edit`。 +- 只有在任务边界明确、仓库可回滚、并且你接受它连续执行命令时，再考虑 `Full Auto`。 + +## 使用时的提醒 + +- 不同客户端可能不会把权限模式写成完全一样的中文名，建议优先认官方英文模式名。 +- 即使使用更自动化的模式，也要保留对高风险操作的复核，比如安装依赖、删除文件、访问网络、推送代码或处理敏感信息。 +- 如果你不确定当前模式会不会执行某个动作，先让 Codex 说明它准备运行哪些命令、会改哪些文件，再决定是否继续。 diff --git a/docs/guide/04-workflows.md b/docs/guide/06-workflows.md similarity index 100% rename from docs/guide/04-workflows.md rename to docs/guide/06-workflows.md diff --git a/docs/guide/05-agents-md.md b/docs/guide/07-agents-md.md similarity index 100% rename from docs/guide/05-agents-md.md rename to docs/guide/07-agents-md.md diff --git a/docs/guide/06-sandbox-approvals.md b/docs/guide/08-sandbox-approvals.md similarity index 100% rename from docs/guide/06-sandbox-approvals.md rename to docs/guide/08-sandbox-approvals.md diff --git a/docs/guide/09-skills-plugins.md b/docs/guide/09-skills-plugins.md new file mode 100644 index 0000000..b377afe --- /dev/null +++ b/docs/guide/09-skills-plugins.md @@ -0,0 +1,64 @@ +# Skills 和 Plugins + +这一节介绍 Codex 里的 `Skills` 和 `Plugins`。不同版本的 App 或工作区里，入口位置和展示方式可能会调整，但核心区别相对稳定：`Skill` 更像可复用的工作流程说明，`Plugin` 更像把一组能力打包后分发和安装的方式。 + +::: tip 最后核对 +官方资料最后核对日期：2026-05-10。本文参考 [Codex Skills](https://developers.openai.com/codex/skills) 与 [Using Codex with your ChatGPT plan](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan)。如果你的界面与本文截图不完全一致，请优先以当前客户端和工作区可用功能为准。 +::: + +如果你在 App 中看到了和技能、插件相关的入口，可以结合下面的概念来理解它们： + +![image-20260510141515793](https://zzy-1326340203.cos.ap-beijing.myqcloud.com//image-20260510141515793.png?imageSlim) + +## Skill 是什么 + +`Skill` 可以理解为一份让 Codex 稳定执行重复任务的操作手册。当某个工作流已经很固定，例如“审查 PR”“整理文档”“补案例索引”，就可以把它沉淀成一个 Skill，减少每次重复描述的成本。 + +一个 Skill 通常会包含： + +1. 一个 `SKILL.md` 文件 + 这里会写清触发场景、执行步骤、输出格式和注意事项。 +2. 必要时配套脚本、模板或参考文件 + 用来帮助 Codex 更稳定地完成任务。 + +![image-20260510141816289](https://zzy-1326340203.cos.ap-beijing.myqcloud.com//image-20260510141816289.png?imageSlim) + +常见使用方式是： + +- 先准备或安装可用的 Skill。 +- 在发起任务时明确说明你希望使用哪个 Skill。 +- 让 Codex 按这个 Skill 的流程执行，再根据结果继续追问或迭代。 + +有些工作区会提供更直接的安装或启用方式；也有一些场景里，需要先把 Skill 放到约定目录，或者通过现有插件能力来分发。稳妥起见，不建议把“给一个 GitHub 链接就一定能自动安装”写成固定结论，更好的表述是：可以把 Skill 来源交给 Codex 协助识别和安装，但具体流程会受客户端能力和工作区设置影响。 + +![image-20260510141948099](https://zzy-1326340203.cos.ap-beijing.myqcloud.com//image-20260510141948099.png?imageSlim) + +## Plugin 是什么 + +`Plugin` 更像一种打包和分发机制，用来把可复用工作流、应用集成、MCP 服务配置等能力组合起来，方便在项目或团队中统一安装和使用。 + +简单理解： + +- `Skill` 关注“这件事应该怎么做”。 +- `Plugin` 关注“把哪些能力打包起来，方便安装和复用”。 + +所以 Skill 往往是具体流程本身，而 Plugin 更像承载这些流程和集成能力的安装单元。 + +![image-20260510142335056](https://zzy-1326340203.cos.ap-beijing.myqcloud.com//image-20260510142335056.png?imageSlim) + +## 怎么理解它们的关系 + +你可以把两者想成： + +- Skill 是“工作说明书” +- Plugin 是“装着说明书、工具和连接配置的工具箱” + +有些插件里会包含一个或多个 Skills，也可能附带应用集成或 MCP 配置。这样团队在迁移环境时，不用手动一个个配置。 + +## 使用时的提醒 + +- 插件和技能的具体入口会随版本变化，不要把某个截图里的按钮位置当成永远不变。 +- 如果插件涉及外部系统、浏览器、邮箱、知识库或项目管理工具，先确认它是只读还是可写。 +- 涉及安装、写回外部系统或共享给团队时，最好保留人工复核。 + +![image-20260510142434210](https://zzy-1326340203.cos.ap-beijing.myqcloud.com//image-20260510142434210.png?imageSlim) diff --git a/docs/guide/10-automation.md b/docs/guide/10-automation.md new file mode 100644 index 0000000..3416051 --- /dev/null +++ b/docs/guide/10-automation.md @@ -0,0 +1,65 @@ +# 自动化 + +这一节介绍 Codex 中的 `Automation`。如果说 Skill 更关注“怎么做”，那么 Automation 更关注“什么时候自动去做”。 + +::: tip 最后核对 +官方资料最后核对日期：2026-05-10。本文参考 [Using Codex with your ChatGPT plan](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan) 与 [Codex use cases](https://developers.openai.com/codex/use-cases/)。不同客户端、工作区套餐和权限设置下，自动化入口和可选项可能会有所不同。 +::: + +当一个工作流已经足够稳定、而且会重复发生时，就可以考虑把它交给 Automation，在后台按计划触发，而不是每次都手动发起。 + +适合自动化的任务包括： + +- 定期检查文档死链 +- 每周整理一次 issue 或 PR 摘要 +- 每天汇总 failing CI +- 在固定时间提醒补复盘或更新文档 + +## 可以怎么理解自动化 + +一个自动化任务通常至少会包含三部分： + +1. 目标对象 + 它对应哪个项目、仓库或线程。 +2. 触发时机 + 比如固定时间、固定间隔，或者稍后回到当前任务继续跟进。 +3. 执行内容 + 也就是让 Codex 到时具体去完成什么。 + +## 常见使用流程 + +在支持 Automations 的界面里，你通常会经历类似下面的流程： + +1. 选择对应的项目、仓库或当前线程。 +2. 设定执行时间或执行周期。 +3. 写清楚自动化任务本身的目标、输出格式和边界。 +4. 保存后观察第一次运行结果，再决定是否长期保留。 + +这里最容易被忽略的一点是：自动化 prompt 要尽量写成”自包含”的任务说明。不要默认它会记得你之前说过什么，最好把检查范围、输出格式和验证要求写完整。 + +❌ 不够自包含的写法： + +```text +请检查一下文档里的链接有没有问题。 +``` + +✅ 推荐的写法： + +```text +请检查 docs/ 目录下所有 .md 文件中的外部链接是否有效。 + +检查范围：仅检查以 http:// 或 https:// 开头的链接，忽略锚点和相对路径。 +输出格式：按”文件路径 | 行号 | 链接 | 状态”列出失效链接；全部正常时输出”全部链接正常”。 +验证方式：对每个链接发起 HEAD 请求，超时 5 秒视为失效。 +限制：不修改任何文件，不创建新文件。 +``` + +两者的区别在于：第一种每次触发时 Codex 都要靠猜测来填补缺失的细节，结果容易不稳定；第二种把边界、格式、验证方式都写明白了，无论在哪次执行、哪个上下文里，行为都是一致可预期的。 + +## 使用时的提醒 + +- 不同工作区里的自动化能力可能并不完全一样，有些支持项目级任务，有些更偏向提醒和跟进。 +- 第一次配置时，建议先从低风险、只读型任务开始。 +- 如果自动化会写文件、访问外部系统或触发通知，最好先确认权限边界和人工复核方式。 + +![image-20260510143038188](https://zzy-1326340203.cos.ap-beijing.myqcloud.com//image-20260510143038188.png?imageSlim) diff --git a/docs/guide/07-cloud-ide-app.md b/docs/guide/11-cloud-ide-app.md similarity index 100% rename from docs/guide/07-cloud-ide-app.md rename to docs/guide/11-cloud-ide-app.md diff --git a/docs/guide/08-skills-automations.md b/docs/guide/12-skills-automations.md similarity index 100% rename from docs/guide/08-skills-automations.md rename to docs/guide/12-skills-automations.md diff --git a/docs/guide/09-troubleshooting.md b/docs/guide/13-troubleshooting.md similarity index 100% rename from docs/guide/09-troubleshooting.md rename to docs/guide/13-troubleshooting.md diff --git a/docs/index.md b/docs/index.md index d84dfe0..9124b0f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -46,7 +46,7 @@ features: 2. 按顺序完成 [安装与登录](/guide/01-installation.html) 和 [第一次改代码](/guide/02-first-run.html)。 3. 用 [任务设计](/practice/task-design.html) 改写自己的真实需求。 4. 遇到具体任务时去 [实战案例库](/recipes/) 找模板。 -5. 如果要在团队内推广，优先补齐 [AGENTS.md](/guide/05-agents-md.html) 和 [沙盒与审批](/guide/06-sandbox-approvals.html)。 +5. 如果要在团队内推广，优先补齐 [AGENTS.md](/guide/07-agents-md.html) 和 [沙盒与审批](/guide/08-sandbox-approvals.html)。 ::: tip 最后核对 基础资料最后核对日期：2026-05-04。 diff --git a/docs/platform/index.md b/docs/platform/index.md index d479850..bc5a644 100644 --- a/docs/platform/index.md +++ b/docs/platform/index.md @@ -38,7 +38,7 @@ CodexGuide 把 Codex 看成一组入口协同的工作系统。学习时不要 | 配置主题 | 主要影响入口 | 学习页 | | --- | --- | --- | -| `AGENTS.md` | CLI / App / Cloud | [AGENTS.md](/guide/05-agents-md.md) | +| `AGENTS.md` | CLI / App / Cloud | [AGENTS.md](/guide/07-agents-md.md) | | CLI 选项 | CLI | [CLI 选项与命令](/configuration/cli-options.md) | | `config.toml` | CLI | [配置文件 config.toml](/configuration/config-file.md) | | Skills | App / CLI | [MCP、Skills 与 Subagents](/configuration/mcp-skills-subagents.md) | diff --git a/docs/recipes/chrome-browser-plugin.md b/docs/recipes/chrome-browser-plugin.md new file mode 100644 index 0000000..b954700 --- /dev/null +++ b/docs/recipes/chrome-browser-plugin.md @@ -0,0 +1,67 @@ +# Codex 控制 Chrome 浏览器 + +这个案例介绍如何让 Codex 借助浏览器相关能力完成网页操作任务，比如打开页面、搜索内容、点击结果和返回链接。 + +::: tip 最后核对 +官方资料最后核对日期：2026-05-10。本文参考 [Using Codex with your ChatGPT plan](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan) 与 [Codex use cases](https://developers.openai.com/codex/explore/)。具体插件名称、安装流程和入口位置可能会随客户端版本或工作区配置变化。 +::: + +## 适用场景 + +- 让 Codex 帮你在网页里搜索资料。 +- 让 Codex 打开某个站点并完成简单点击流程。 +- 在不离开当前工作区的前提下，把浏览器操作接入任务链路。 + +## 使用前先理解一件事 + +这里说的“控制浏览器”，更准确地说，是让 Codex 借助浏览器或浏览器插件能力去完成网页交互。不同工作区里，入口可能叫 `Chrome`、`Browser`，也可能表现为浏览器插件或内置浏览能力。 + +因此，更稳妥的理解方式是： + +1. 在当前工作区确认是否已经启用了相关浏览器能力。 +2. 如果是第一次使用，按界面引导完成浏览器侧安装或授权。 +3. 安装完成后，再在任务里明确告诉 Codex 你想让它做什么。 + +## 一个常见流程 + +如果你的客户端提供了 Chrome 相关插件或浏览器能力，常见流程通常类似这样： + +1. 在 Codex App 中找到对应的浏览器能力并启用。 +2. 按引导完成浏览器侧的插件安装或连接配置。 +3. 回到任务中，明确描述目标网页、搜索词和预期输出。 + +![image-20260510150638133](https://zzy-1326340203.cos.ap-beijing.myqcloud.com//image-20260510150638133.png?imageSlim) + +有些环境下，第一次点击后会跳转到浏览器插件安装页，或者提示你连接现有浏览器。 + +![image-20260510150753382](https://zzy-1326340203.cos.ap-beijing.myqcloud.com//image-20260510150753382.png?imageSlim) + +## 任务示例 + +你可以像下面这样给出一个明确任务： + +```text +请使用浏览器能力打开 Bilibili，搜索“IG 知识库 教程”，找一个适合新手入门的视频，并把标题和链接返回给我。 +``` + +一个类似任务完成后，Codex 可能会： + +1. 打开目标站点。 +2. 搜索你提供的关键词。 +3. 进入相关结果页。 +4. 把它认为最合适的结果链接返回给你。 + +![image-20260510150851878](https://zzy-1326340203.cos.ap-beijing.myqcloud.com//image-20260510150851878.png?imageSlim) + +## 你要重点检查什么 + +- 它打开的网站是不是你指定的那个站点。 +- 搜索词有没有被错误改写。 +- 点击结果后返回的是不是你真正需要的页面，而不是广告页或无关页。 +- 如果涉及登录态、个人数据或付费后台，是否会超出你愿意授权的范围。 + +## 风险提醒 + +- 浏览器相关能力通常比纯文本任务权限更高，第一次使用时建议从只读、低风险页面开始。 +- 不要直接让 Codex 操作带有支付、删除、发帖、提交表单等高风险页面，除非你准备全程复核。 +- 如果教程依赖插件安装，未来界面名称或入口位置可能变化，因此文档里应优先描述“能力和流程”，而不是把某个按钮位置写死。 diff --git a/docs/recipes/ppt-skill-walkthrough.md b/docs/recipes/ppt-skill-walkthrough.md new file mode 100644 index 0000000..c13e5a4 --- /dev/null +++ b/docs/recipes/ppt-skill-walkthrough.md @@ -0,0 +1,75 @@ +# 安装并使用 PPT Skill + +这个案例演示一个对新手很有帮助的流程：如何让 Codex 协助安装一个开源 Skill，并在安装完成后立即调用它完成任务。 + +::: tip 最后核对 +官方资料最后核对日期：2026-05-10。本文关于 Skill 机制参考 [Codex Skills](https://developers.openai.com/codex/skills)。案例中使用的 PPT Skill 来自社区仓库：[guizang-ppt-skill](https://github.com/op7418/guizang-ppt-skill)。第三方 Skill 的安装方式、依赖要求和输出格式请以原仓库说明为准。 +::: + +## 适用场景 + +- 你已经找到一个想用的社区 Skill。 +- 你想让 Codex 帮你完成安装，而不是手动整理目录和文件。 +- 你希望安装后立刻用一个真实任务验证它是否可用。 + +## 准备一个 Skill 来源 + +首先要有这个 Skill 的来源地址。很多开发者会把自己做好的 Skill 放在 GitHub 仓库里，供其他人安装和复用。 + +这个案例里使用的是一个社区 PPT Skill： + +[guizang-ppt-skill](https://github.com/op7418/guizang-ppt-skill) + +## 第一步：安装 + +你可以把 Skill 仓库地址交给 Codex，请它协助识别并完成安装流程。 + +例如： + +```text +请帮我安装这个 Skill：https://github.com/op7418/guizang-ppt-skill +安装完成后，告诉我它的用途、依赖要求，以及应该如何调用。 +``` + +![image-20260510151307889](https://zzy-1326340203.cos.ap-beijing.myqcloud.com//image-20260510151307889.png?imageSlim) + +不同工作区里，安装方式可能不完全一样。有些会直接支持安装，有些则会先分析仓库结构，再提示你确认放置位置或依赖要求。 + +## 第二步：调用使用 + +安装完成后，可以直接让 Codex 调用这个 Skill 去完成一项真实任务。 + +如果这个 Skill 已经提前安装过，你通常也可以通过斜杠命令、技能选择器，或者在任务里明确点名的方式来调用它。 + +![image-20260510151643570](https://zzy-1326340203.cos.ap-beijing.myqcloud.com//image-20260510151643570.png?imageSlim) + +例如： + +```text +请使用刚刚安装的 PPT Skill，根据“AI 编程工具入门”这个主题生成一份适合分享的演示稿。先告诉我还缺哪些关键信息。 +``` + +如果你没有给足上下文，Codex 往往会先回到这个 Skill 的操作手册里，看看它需要什么输入，然后再向你追问必要信息。 + +![image-20260510151805687](https://zzy-1326340203.cos.ap-beijing.myqcloud.com//image-20260510151805687.png?imageSlim) + +当你补齐背景、主题、受众或风格要求后，它会按该 Skill 的流程去读取 README、模板和相关文档，再生成结果。 + +![image-20260510152138213](https://zzy-1326340203.cos.ap-beijing.myqcloud.com//image-20260510152138213.png?imageSlim) + +如果这个 Skill 的默认产物是 HTML 演示稿，你通常可以直接在 Codex 内置浏览器里打开预览。 + +![image-20260510152225951](https://zzy-1326340203.cos.ap-beijing.myqcloud.com//image-20260510152225951.png?imageSlim) + +## 你要重点检查什么 + +- Codex 安装的是不是你指定的那个 Skill，而不是名称相似的别的仓库。 +- 安装后有没有说明依赖要求、输出格式和调用方式。 +- 生成结果是否符合这个 Skill 原仓库描述的能力边界。 +- 如果结果不理想，是 Skill 本身限制，还是你提供的输入信息不够。 + +## 风险提醒 + +- 社区 Skill 不是官方能力，质量和维护状态差异会很大，使用前最好先看仓库 README。 +- 不要默认“给出 GitHub 链接就一定能一步安装成功”，有些 Skill 还会依赖额外脚本、模板或本地环境。 +- 第一次验证时，优先选一个小任务，确认 Skill 能正常运行后，再拿去做正式产物。