半桶水式 Codex 学习项目改造规格
约 2674 字大约 9 分钟
半桶水式 Codex 学习项目改造规格
当前状态
本规格用于指导 CodexGuide 的渐进式课程化改造。当前执行策略是：先保证课程骨架、入口、核心入门页、案例页和轻量交互可运行，再进入视觉一致性和内容质量审查。
- Phase 1：课程骨架、首页、课程入口和轻量交互已进入可构建状态。
- Phase 2：核心入门章节已按“小白友好 + 验收标准”方向改造，后续继续补齐非核心页。
- Phase 3：案例库已从工具清单改为工作流场景课，
credits.md保持来源致谢属性。 - Phase 4：已采用 VuePress 全局组件实现学习地图、任务拆解器、工作流护照和能力矩阵；AetherViz Master 暂作为后续动态教学图参考，不引入重型 3D。
- Phase 5：进入构建、链接、截图、移动端和内容 QA 的循环验证。
目标
把当前 CodexGuide 改造成半桶水主导的 Codex 小白学习课程站。它不只是解释 Codex 有哪些入口和配置，而是帮助学习者从真实工作问题出发，学会把 Codex 放进自己的资料整理、内容生产、办公交付、网页/PPT/视觉表达和开发协作流程里。
改造不能把原项目变成一个只有营销口号的页面。它必须继续保留 CodexGuide 的资料价值，同时用课程结构把学习顺序、判断点和验收标准讲清楚。
受众
- 主要受众：非技术工作者，包括老板、主理人、运营、内容创作者、设计师、销售顾问、行政办公和培训老师。
- 兼容受众：零基础开发者和想把 Codex 用进真实仓库的人。
- 学习者共同状态：听过 AI 很强，但不知道怎么把它稳定放进自己的日常工作。
内容原则
- 从场景进入，不从工具名进入。
- 每一页都回答：为什么学、什么时候用、怎么开始、哪里需要人判断、怎么验收。
- 避免低幼化、被动喂养式和过度承诺式表达，改成“真实工作者一步步长出能力”。
- 保留专业边界：涉及账号、权限、命令、费用、隐私和安全时，要明确提醒。
- 课程承诺固定为：帮助学习者用 Codex 把真实工作改造成可验证、可复用的 AI 工作流。
叙事风格
半桶水风格要保持三件事：
- 通俗：少讲术语堆叠，多讲真实工作里的动作和判断。
- 专业：账号、权限、隐私、费用、生产环境、医疗法律金融等边界必须明确。
- 人性化：承认学习者一开始会不确定，但不把学习者写成被动等待喂养的人。
避免使用低幼化、过度承诺和暗示 AI 可以替代人工判断的表达。推荐使用“先跑通一个低风险任务”“用验收标准判断结果”“把一次成功沉淀成模板”等表达。
信息架构
采用 5 层学习路径：
- 看见 AI 能做什么：理解 Codex 不是聊天框，而是能读文件、跑命令、整理流程的工作伙伴。
- 跑通第一个低风险任务：用桌面 App 或 CLI 完成一次可复核的小任务。
- 学会任务拆解与验证：把目标、材料、边界、验证和交付说清楚。
- 建立个人工作流：把一次成功任务保存成模板、Skill、案例或团队规则。
- 形成工作流护照：记录自己的工具组合、常用任务、素材库、风险边界和下一步升级计划。
页面改造
- 首页：半桶水课程入口，突出真实工作痛点、5 层学习路径、三类人群路线、交互练习和精选案例。
- 学习路线：从“入口分类”改为“小白如何由浅入深学习 Codex”。
- 课程入口
/course/：解释 3 天线下 + 4 周陪跑如何与站内教程对应。 - 导航：新增“课程入口”，保留 Codex 入门、工作流案例、配置排障。
- 侧栏：新增
/course/分组，首页 fallback 也加入课程入口。
教学页面模板
核心教学页应尽量靠近以下结构。不是每页都机械套满，但至少要让学习者知道为什么学、怎么做、怎么验收。
- 这节解决什么：用真实工作问题开场。
- 适合谁：告诉不同起点的人如何进入。
- 工作流卡：说明输入、过程、输出、验收。
- 操作步骤：保持具体、可执行、不过度堆概念。
- 你要重点检查什么：标出人的判断点。
- 验收标准：说明什么叫完成，而不是只讲步骤。
- 复用方式：把一次任务沉淀成模板、案例、Skill 或团队规则。
- 风险边界：涉及敏感信息、账号权限、生产环境和专业建议时显性提醒。
案例页模板
案例页不是展示“这个工具很厉害”，而是展示“这个工作流如何迁移到你的工作”。
- 场景：这件事在真实工作里解决什么问题。
- 输入：需要准备哪些文件、链接、账号、素材或背景。
- 过程：Codex 做哪些动作，人在哪些节点判断。
- 输出：最终得到什么交付物。
- 验收：如何检查结果正确、可用、可交付。
- 复用：如何换成自己的行业材料。
- 边界：哪些内容不能让 AI 直接决定。
交互组件
LearningPathMap：展示 5 层学习路径，每层对应目标、行动和验收。TaskBriefBuilder：让学习者把模糊需求拆成目标、材料、边界、验证和交付。WorkflowPassport：预览最终工作流护照结构，让学习者知道课程终点是什么。CapabilityMatrix：帮助学习者从资料整理、内容表达、办公交付、视觉页面、工程协作和沉淀复用中选择练习入口。
如果 AetherViz Master 可用，后续用于动态学习地图和能力矩阵；如果不可用，继续使用 VuePress 全局 Vue 组件、SVG 和 CSS 实现。
视觉方向
视觉目标是“专业、克制、有人味”，而不是强营销或重装饰。
- 首页和课程页可以更有引导感，但正文页要优先可读。
- 卡片用于重复项目、交互组件和信息块，不把每个段落都做成卡片。
- 色彩以清晰层级和状态表达为主，避免单一色系铺满页面。
- 移动端优先保证文字不溢出、交互控件可点击、侧栏导航可理解。
- 动态交互只服务教学理解，不为了炫技增加学习负担。
分阶段实施
Phase 1：课程骨架改造
范围：
- 首页改为“半桶水 Codex AI 工作流实战课”。
- 新增
/course/和能力矩阵入口。 - 改造学习路线、导航、侧栏和 SEO。
- 注册轻量交互组件。
验收：
- 首页、课程入口、学习路线和案例入口可访问。
- 新手能在 1 分钟内判断自己应该从哪里开始。
- 构建通过，桌面和移动端首屏不出现明显遮挡。
Phase 2：教学模板统一
范围：
- 优先改造 App 入门、第一个任务、任务执行、权限、Skills、CLI、IDE、AGENTS.md、沙盒和排障。
- 补强任务设计页，让它成为课程里的核心方法页。
验收：
- 核心页包含学习目的、适合人群、判断点和验收标准。
- 敏感操作都有边界提醒。
- 不把 Codex 描述成无需人工判断的万能按钮。
Phase 3：案例课程化
范围：
- 把 PPT、浏览器、知识库、飞书、Figma、Notion、远程排障、CI、医学文献、视觉生成和安卓协同等案例改造成工作流场景课。
credits.md保持参考来源与致谢，不强行套教学模板。
验收：
- 案例页说明输入、过程、输出、验收和复用方式。
- 高风险案例有明确人工复核和权限边界。
- 案例总览能按工作场景引导，而不是只列工具名。
Phase 4：交互与视觉增强
范围：
- 用 VuePress 组件承载学习地图、任务拆解器、工作流护照和能力矩阵。
- 需要动态教学图时，优先参考 AetherViz Master 的教学可视化方法；当前阶段保持轻量实现。
验收：
- 组件不依赖外部服务。
- 键盘可访问，移动端不横向溢出。
- 交互能帮助学习者做选择或理解结构，而不是只增加视觉效果。
Phase 5：质量审查与迭代
范围：
- 构建检查、关键页面 HTTP 检查、关键词检查、桌面与移动截图检查。
- 内容 QA：用新手视角检查“能不能照做、知不知道为什么做、知不知道如何验收”。
验收：
corepack pnpm build通过。- 首页、课程页、学习路线、任务设计、案例总览和代表性案例在桌面与移动端可读。
- 禁用语和不合适承诺没有命中。
- 审查结果记录剩余风险，不把未检查内容默认说成完成。
公共接口与内容合同
/course/是一级课程入口。/course/capability-matrix.md是学习者选择任务入口的辅助页。/guide/00-overview.md是学习路线页。/practice/task-design.md是任务拆解方法页。/recipes/是工作流案例库入口。- 首页承诺固定为：帮助学习者用 Codex 把真实工作改造成可验证、可复用的 AI 工作流。
检查命令
每阶段至少运行：
corepack pnpm build关键词检查：
rg -n "[禁用表达清单]" docs/guide docs/course docs/practice docs/recipes docs/index.md代表性链接检查：
python3 -m http.server 8801 --directory docs/.vuepress/dist然后检查：
//course//course/capability-matrix.html/guide/00-overview.html/practice/task-design.html/recipes/
内容 QA 问题
每阶段至少完成：
pnpm build通过。- 首页、课程页、学习路线页在桌面和移动端可读。
- 导航和侧栏链接可访问。
- 新增交互组件不依赖外部服务。
- 内容回答 5 个问题：新手从哪开始、为什么学、是否有真实场景、是否有验收标准、是否符合半桶水专业但通俗的人性化表达。
补充检查：
- 这页有没有说明学习者要准备什么输入？
- 这页有没有说明 Codex 的动作和人的判断分别是什么？
- 这页有没有说明失败时先检查哪里？
- 这页有没有说明如何迁移到自己的真实工作？
- 这页有没有避免把高风险判断交给 AI？