ai-guide 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

ai-guide 是由程序员鱼皮维护的 AI 知识库与文档站点项目，仓库描述为“程序员鱼皮的 AI 资源大全 + Vibe Coding 零基础教程”。项目内容覆盖 AI 工具、大模型使用、AI 编程、提示词、Agent Skills、RAG、MCP、A2A、开发框架以及 AI 产品变现等主题。

根据仓库资料，项目 GitHub Star 数为 20208，Fork 数为 2252，主要语言为 JavaScript，默认分支为 main。GitHub 元信息中的许可证字段显示为 NOASSERTION，但仓库内的 LICENSE 对文档内容与站点源代码分别作出了许可说明，使用前应以仓库中的完整许可证文本为准。

定位与目标用户

这个项目的核心定位不是某一个 AI 模型的 SDK，也不是单独的应用源码，而是面向学习、选型和实践的开放式 AI 资料库。README 将其描述为“完全免费开放的 AI 知识共享平台”，重点在于汇总产品介绍、使用指南、工具测评、技巧分享、应用场景、行业资讯和教程资源。

目标用户覆盖面较广：零基础用户可以从 Vibe Coding（氛围编程）入门，已有编程基础的读者可以查找 AI 编程工具、模型应用开发和工程实践资料，产品或运营人员则可以阅读 AI 工具、应用场景与产品变现相关内容。这里的“目标用户”来自 README 的教程结构与学习路径，不代表项目对用户身份作出强制限制。

内容组织方式

仓库内容既包含 Markdown 教程，也包含用于构建文档站点的 VuePress 配置与脚本。在线站点承载了更适合连续阅读的课程结构，GitHub 仓库则适合查看源文件、提交修改和跟踪项目变化。

README 同时提供了 English 与繁體中文翻译入口，但资料没有说明所有内容均已完成翻译，也没有提供翻译同步策略。阅读非简体中文版本时，应以对应目录的实际内容为准。

核心功能

项目的功能重点体现在知识内容的覆盖范围与文档生成流程，而不是提供一个运行时 AI 服务。每类内容都有不同的输入、阅读方式和预期产出，使用者应按学习目标选择入口，而不是把整个仓库当作单一命令行工具安装。

Vibe Coding 零基础教程

教程从 Vibe Coding 的基础概念开始，安排了快速上手、编程工具、项目实战、经验技巧、产品变现、编程学习和资源宝库等部分。其输入主要是读者的产品想法、工具选择和实践问题，输出则是对 AI 编程流程、项目开发方法和产品化路径的理解。

README 明确提到教程包含“上千张图、几十万字”，并提供“10 分钟做出第一个作品”的基础实践描述。该规模和学习目标属于 README 的项目说明，不能据此推导学习效果、交付质量或商业收益。

大模型与 AI 工具资料

知识库收录 DeepSeek、GPT、Gemini、Claude、GLM 等大模型相关内容，也覆盖 Cursor、Claude Code、TRAE、Codex、Copilot 等 AI 编程工具。相关页面的工作方式通常表现为教程、工具说明、使用技巧或案例阅读；仓库资料没有提供统一的模型调用接口，也没有规定必须使用某一个模型。

README 中列出了 DeepSeek 基础概念、快速上手、本地部署、API 调用、提问技巧和学习资料等入口。具体模型版本、API 地址、计费规则、可用区域和配额并未在给定资料中完整说明，使用时应以对应服务的最新官方文档和项目页面为准。

AI 编程与工程知识

AI 编程部分包含 AI 智能体项目、AI 零代码平台、AI 大模型应用开发学习路线，以及 Cursor 使用技巧和实战项目。它的输入可以是一个待实现的产品需求、已有项目或开发问题，教程通过提示词、上下文管理、工具选择和代码质量实践，帮助读者形成可复用的开发流程。

项目描述还提到 Harness Engineering（缰绳工程）以及 Spring AI、LangChain 等开发框架。资料没有给出这些专题的完整章节清单、代码接口版本或兼容矩阵，因此不能将项目表述为某个框架的官方文档。

站点生成与内容维护

根据 package.json，项目使用 VuePress 生成文档站点，并提供侧边栏和 README 生成脚本。构建前会执行 generate:sidebar 与 generate:readme，输入路径为 ./AI，这说明内容目录与站点导航之间存在自动生成关系。

生成脚本的具体排序规则、忽略规则和 Markdown 解析细节没有在给定资料中展开。需要修改文档结构时，应先阅读仓库中的脚本实现和现有目录，而不是依据本文推断未提供的目录约定。

系统架构与关键模块

从可见的 package.json 和 LICENSE 信息看，项目可以分为内容层、生成层、站点层和发布层。该划分是对资料中已出现文件与依赖的结构化归纳，不等同于仓库作者公布的正式架构图。

内容层

内容层由教程 Markdown 文件及其配图组成，许可证明确将“所有 Markdown 文件及其配图”归入教程与文档内容。README 展示的内容包括 Vibe Coding 教程、AI 知识库导航、工具说明、学习路线和实战项目入口。

内容层的主要输入是 Markdown 文档、链接和图片资源，输出是可被 VuePress 处理的文档页面。资料没有提供完整的 Markdown 文件列表，因此不能在此列出未被展示的具体文件名。

生成层

生成层由 ./.vuepress/scripts/generateSidebar.js、./.vuepress/scripts/genReadme.js 和 ./.vuepress/scripts/getMdNumber.js 等脚本组成。前两个脚本分别对应侧边栏和 README 生成任务，第三个脚本从名称上看与 Markdown 编号有关，但其具体算法和使用参数未在资料中说明。

当文档结构发生变化时，pre-docs:build 会先运行侧边栏和 README 生成命令，再执行站点构建。该生命周期关系直接来自 package.json 的脚本定义。

站点层与插件层

站点层使用 VuePress，并配置返回顶部、Google Analytics、中等缩放、百度自动推送、Feed、SEO、Sitemap、Tags、代码复制和图片懒加载等插件。依赖名称来自 package.json，资料没有给出每个插件在站点中的具体配置文件内容或运行参数。

因此，能够确认的是项目具备这些插件依赖，而不能确认每个插件均已在当前站点启用、均有自定义配置，或均会在所有构建环境中产生相同结果。

依赖与运行环境

项目运行基础是 JavaScript 文档工程，依赖配置位于根目录 package.json。资料给出了 VuePress 和相关插件的版本范围，但没有给出 Node.js、npm、操作系统或浏览器的最低版本要求。

安装前应准备能够执行 npm 依赖安装和脚本命令的本地开发环境。若出现 Node.js 版本兼容、npm 锁文件或依赖解析问题，官方仓库未提供该信息，建议以最新 README、当前分支的依赖文件和构建日志为准。

已知依赖清单

• 站点框架：vuepress，版本范围为 ^1.9.10。
• 开发依赖：@vuepress/plugin-back-to-top、@vuepress/plugin-google-analytics、@vuepress/plugin-medium-zoom，版本范围均为 ^1.9.10。
• 站点插件：vuepress-plugin-baidu-autopush、vuepress-plugin-feed、vuepress-plugin-seo、vuepress-plugin-sitemap、vuepress-plugin-tags。
• 运行依赖：vuepress-plugin-code-copy 与 vuepress-plugin-img-lazy。

快速开始

快速开始的最小闭环是安装依赖、启动本地文档服务、完成页面访问验证。以下命令均来自根目录 package.json 中已经定义的脚本或标准 npm 用法，适合本地阅读与测试。

安装 → 运行 → 验证

# 进入仓库根目录后安装 package.json 中声明的依赖
npm install

# 启动 VuePress 本地开发服务
npm run docs:dev

# 在另一个终端执行生产构建，用于验证文档是否能够完成构建
npm run docs:build

npm install 会读取根目录的 package.json；npm run docs:dev 执行 vuepress dev .；npm run docs:build 执行 vuepress build .。资料未提供开发服务端口、绑定地址和构建输出目录的自定义值，因此不在此虚构访问 URL 或端口。

本地静态预览

# 完成生产构建后，使用项目已声明的 serve 脚本预览构建产物
npm run serve

该脚本对应 serve ./.vuepress/dist，说明预览目标是 ./.vuepress/dist。实际访问地址由 serve 命令在当前环境中的输出决定，官方仓库未提供固定端口信息，建议以终端输出为准。

配置说明

给定资料没有提供 .env.example、站点配置样例或模型 API 配置，因此不能列出未出现的环境变量、端口和密钥字段。下表仅整理 package.json 中确实出现的配置项，并将其原始值作为默认值记录。

表中 license 的含义需要结合仓库 LICENSE 解释：根目录 package.json 及 .vuepress 下的源代码采用 MIT，教程 Markdown 与配图不适用该字段。若要修改分析工具、统计工具或站点插件行为，应先查阅未在资料中展示的 VuePress 配置文件。

进阶用法

进阶使用的重点是理解构建前钩子与生成脚本之间的关系，而不是新增模型调用代码。对文档进行批量整理、调整章节或生成站点时，应优先使用仓库已经定义的 npm 脚本。

单独执行生成任务

# 根据 package.json 中的脚本定义生成侧边栏
npm run generate:sidebar ./AI

# 根据 package.json 中的脚本定义生成 README
npm run generate:readme ./AI

# 执行仓库已声明的 Markdown 编号相关脚本
npm run getMdNumber

前两个命令明确接收 ./AI 作为参数，因为 pre-docs:build 的脚本字符串就是这样调用的。getMdNumber 在 package.json 中没有展示参数，因此示例不为它追加未被资料确认的选项。

内容维护工作流

1. 在本地修改已有教程或新增符合仓库约定的 Markdown 内容。
2. 运行 npm run generate:sidebar ./AI 和 npm run generate:readme ./AI，检查自动生成内容是否符合预期。
3. 运行 npm run docs:build，验证站点构建过程。
4. 使用 npm run serve 预览 ./.vuepress/dist，检查链接、标题层级和代码块显示。

上述流程中的目录、脚本和构建命令均有资料依据；具体的提交规范、分支策略和自动化发布流程未在给定资料中说明。若构建结果与在线站点不一致，应以仓库当前分支和官网实际内容作为核对对象。

可观测性与运维

项目在依赖层面包含 Google Analytics、SEO、Sitemap、Feed、百度自动推送和 Tags 等插件，这表明站点具备内容分发、搜索相关和统计相关的扩展点。资料没有给出统计账号、站点地图地址、埋点字段、日志系统、告警规则或部署平台。

本地运维可用构建结果作为最基本的健康信号：执行 npm run docs:build 能够完成，说明当前依赖和文档在该环境中通过了构建阶段。该结果不等于线上可用性、链接完整性、搜索收录状态或访问性能，项目资料也没有提供 SLA、性能基准或并发指标。

建议核查项

• 构建前生成脚本是否成功执行，尤其是输入路径 ./AI 是否存在。
• VuePress 构建是否因 Markdown、链接或插件配置错误退出。
• 生成目录 ./.vuepress/dist 是否出现，并能被 npm run serve 读取。
• 线上部署使用的依赖版本是否与当前 package.json 一致。

安全与合规边界

项目内容涉及大模型、AI 编程、智能体、MCP、RAG、A2A 和工具使用，但给定资料没有显示它提供未授权访问、渗透、账号自动化、支付处理或绕过安全检测的功能。相关教程应限定在本人拥有权限的设备、项目、数据和服务环境中使用。

使用大模型工具时，输入内容可能包含代码、业务文档、提示词或其他数据；仓库资料没有提供统一的数据保留、加密、脱敏和第三方服务处理策略。涉及个人信息、商业秘密、源代码或受监管数据时，应在导入外部模型或在线工具前完成组织内部授权、数据分类与合规审查。

• 仅在获得明确授权的本地、测试或生产环境中执行自动化操作。
• API 密钥、Cookie、私钥和内部配置不得写入公开 Markdown、示例代码或提交记录。
• 教程中的模型调用、智能体和 MCP 实践应使用最小权限账号及隔离测试数据。
• 对于第三方模型、插件和工具，应分别核对其服务条款、隐私政策与数据处理边界。

项目资料没有提供漏洞披露流程、CVE 列表、威胁模型或安全审计结论，因此不能据此声明项目具备某种安全等级。

许可证与商用条款

许可证需要按内容类型区分阅读。LICENSE 明确说明，教程和文档内容，即所有 Markdown 文件及其配图，适用 Attribution-NonCommercial-ShareAlike 4.0 International（知识共享署名—非商业性使用—相同方式共享 4.0 国际许可协议）。

同一文件还明确指出，.vuepress 目录下的站点主题、Vue 组件、TypeScript 配置、构建脚本，以及根目录 package.json 不适用上述文档内容许可，而是单独采用 MIT，具体以仓库中的 LICENSE-CODE 文件为准。

使用时需要区分的事项

• 文档内容的署名、非商业使用和相同方式共享条件，应以仓库中的 CC BY-NC-SA 4.0 完整文本为准。
• 文档内容的著作权归程序员鱼皮所有，LICENSE 写明作者保留全部商业使用权利。
• 如需对教程内容进行商业使用，LICENSE 指向微信联系人 yupi996 作为商业授权联系渠道。
• 站点源代码与文档内容的许可范围不同，不能用根目录 package.json 中的 MIT 字段替代对文档内容的判断。

是否满足具体分发、改编、再发布或商业集成条件，应以仓库 LICENSE、LICENSE-CODE 及获得的书面授权为准。本文不对特定业务场景提供法律意见。

局限性与已知限制

项目资料主要描述内容范围和文档构建方式，没有提供完整目录树、运行环境矩阵、发布流水线、测试覆盖率、访问性能、接口文档或版本兼容表。因而不能从仓库 Star 数、Fork 数或依赖列表推导稳定性、并发能力和线上服务等级。

• 没有提供固定 Node.js 或 npm 版本要求。
• 没有提供开发服务端口、生产部署端口或容器化配置。
• 没有提供模型 API 密钥管理方式、统一调用接口或模型版本锁定策略。
• 没有提供各教程页面的更新频率和内容有效期。
• 没有提供完整的自动化测试、链接检查和发布回滚说明。
• GitHub 元信息的许可证字段为 NOASSERTION，需要结合仓库 LICENSE 分辨不同文件的许可范围。

根据本文作者的经验判断，AI 工具与模型资料变化速度较快，读者在照着教程操作时应额外核对所用工具的当前界面、模型名称、服务条款和 API 文档；这属于使用资料时的必要维护动作，不是项目对第三方服务持续兼容的承诺。

适合谁

这个项目适合把 AI 学习目标拆成“理解概念、选择工具、完成实践、继续深入”的读者。以下信号可以帮助判断是否适合使用它作为学习入口。

• 没有编程基础，但希望通过 Vibe Coding 完成个人工具、AI 应用、全栈应用或小程序实践。
• 已有 JavaScript 或其他编程经验，需要系统了解 Cursor、Claude Code、TRAE、Codex、Copilot 等工具的使用方法。
• 正在学习大模型应用开发，希望从 AI 智能体、RAG、MCP、A2A、Spring AI 或 LangChain 等主题建立知识索引。
• 需要同时查阅提示词、模型入门、本地部署、API 调用和产品变现相关资料，而不是只学习单一框架。
• 愿意自行验证教程中的第三方工具版本、服务条款和代码适配情况。

不适合谁

它不适合作为所有场景的唯一技术依据，尤其不适合需要正式规范、严格版本承诺或定制化交付保证的使用者。以下情况应考虑补充官方文档、内部规范或专业服务。

• 需要某个模型或开发框架的官方 API 参考、完整兼容矩阵和版本级支持承诺。
• 需要企业级 SLA、性能基准、灾备方案、审计记录或正式技术支持渠道。
• 准备直接将教程示例用于包含敏感个人信息、核心商业秘密或强监管数据的生产系统。
• 要求固定目录、固定端口、固定 Node.js 版本或 Docker 编排，而仓库资料没有提供相应定义。
• 希望把文档内容直接用于商业课程、付费产品或营销材料，却没有先核对 CC BY-NC-SA 条款及商业授权要求。

在这些场景中，项目仍可作为知识索引或选型起点，但不能替代目标框架的官方文档、组织安全审查和法律合规流程。

常见问题与排查（FAQ / Troubleshooting）

排查时应先区分“文档阅读问题”“本地构建问题”和“第三方 AI 工具问题”。仓库提供的是文档站点源码与资料，未提供所有外部模型服务的统一运行时，因此不同类别的问题处理边界不同。

为什么无法确认本地访问端口

package.json 只定义了 vuepress dev .，给定资料没有提供端口参数。运行 npm run docs:dev 后，应以终端输出的本地地址为准，不要将未在资料中出现的端口写入脚本或部署配置。

为什么构建前会执行额外命令

docs:build 前存在 pre-docs:build，它会先执行 generate:sidebar ./AI 和 generate:readme ./AI。如果 ./AI 路径、文档结构或生成脚本出现问题，生产构建可能在正式执行 VuePress 构建前失败。

为什么不能直接把根目录 MIT 当作文档许可

LICENSE 已经将站点源代码与教程内容分开说明，package.json 中的 MIT 字段不能覆盖 Markdown 文件和配图的 CC BY-NC-SA 4.0 条款。发生再发布、改编或商业使用需求时，应按文件类型核对许可证，并在不确定时以仓库 LICENSE 为准。

如何处理 AI 工具教程中的版本差异

资料没有提供每个 AI 工具的版本锁定信息，也没有承诺第三方产品界面长期不变。遇到页面、命令或模型名称不一致时，应先查看教程页面的最新内容，再核对相关工具的官方说明；官方仓库未提供该信息，建议以最新 README 和对应服务文档为准。

安装依赖失败如何定位

1. 确认当前目录包含根目录 package.json。
2. 检查本地 JavaScript 运行环境是否能够执行 npm；项目资料未提供最低 Node.js 版本。
3. 重新执行 npm install 并保留完整错误输出。
4. 如果是某个插件或 VuePress 的兼容问题，依据 package.json 中的依赖名称和版本范围核对当前解析结果。

若以上信息仍不足以定位问题，官方仓库未提供该信息，建议以最新 README、当前分支提交记录和实际构建日志为准。

项目地址与资源

以下链接均来自项目资料或 README 中出现的官方入口，适合分别用于查看源代码、在线阅读教程和进入配套学习内容。

• ai-guide GitHub 仓库：查看源文件、许可证、构建脚本和项目变更。
• 鱼皮 AI 知识库在线文档：阅读 AI 工具、模型、编程和产品相关资料。
• Vibe Coding 零基础教程：进入 README 提供的系统教程入口。
• AI 编程实战视频教程：查看 README 中列出的配套视频课程。
• 程序员鱼皮哔哩哔哩空间：README 中提供的作者视频平台入口。
• 免费 AI 学习资源：README 新手入门表格中的资料入口。
• AI 零代码平台资料：README AI 编程导航中的资源入口。
• Cursor 使用技巧与省钱方法：README 中列出的 Cursor 相关资料。

来源说明：项目定位、教程结构、学习路径、资源入口和引用描述主要来自 README；构建脚本与依赖信息来自 package.json；文档内容与站点源代码的许可区分来自 LICENSE。