AI 助手通用指南

2026/2/3大约 8 分钟...

本文档为所有 AI 编程助手（Gemini、Claude、Cursor、GitHub Copilot 等）提供统一的项目规范和协作指引。

🎯 项目概览

基本信息

项目属性	详细信息
项目名称	OmniStack
项目类型	技术知识库 + 博客系统
核心框架	VuePress 2.x
前端技术	Vue 3 + Vite
主题	vuepress-theme-hope
语言	中文（简体）
开发环境	macOS + Node.js

项目定位

构建一个全面的全栈技术知识库，涵盖：

🖥️ 操作系统（Windows、Linux、macOS）
💻 编程语言（Python、JavaScript、Java 等）
🤖 AI 工具与服务
🗄️ 数据库技术
☁️ 云服务平台
🛠️ 开发工具与最佳实践

📁 项目结构

OmniStackHub/
├── docs/                          # 文档根目录
│   ├── .vuepress/                # VuePress 配置目录
│   │   ├── config.js             # 主配置文件 ⭐
│   │   ├── public/               # 静态资源
│   │   │   ├── logo.svg          # 网站 Logo
│   │   │   ├── hero.svg          # 首页大图
│   │   │   └── favicon.ico       # 网站图标
│   │   └── dist/                 # 构建输出目录
│   │
│   ├── ai/                       # AI 相关文档
│   │   ├── README.md             # AI 导航页
│   │   ├── code/                 # AI 编程助手
│   │   │   ├── antigravity.md    # Antigravity 指南
│   │   │   ├── cursor.md         # Cursor 指南
│   │   │   └── ...
│   │   ├── opencode/             # 开源编程工具
│   │   │   ├── ollama.md         # Ollama 部署
│   │   │   ├── deepseek.md       # DeepSeek 使用
│   │   │   └── ...
│   │   └── agents/               # AI 助手指南（本目录）
│   │       ├── GEMINI.md         # Gemini 专用指南
│   │       ├── CLAUDE.md         # Claude 专用指南
│   │       └── AGENTS.md         # 通用指南（本文件）
│   │
│   ├── guide/                    # 项目使用指南
│   │   ├── blog-setup.md         # 博客搭建
│   │   └── theme-hope.md         # 主题配置
│   │
│   ├── os/                       # 操作系统相关
│   ├── database/                 # 数据库相关
│   └── README.md                 # 网站首页
│
├── package.json                  # 项目依赖配置
├── package-lock.json             # 依赖锁定文件
├── vercel.json                   # Vercel 部署配置
├── .gitignore                    # Git 忽略规则
└── README.md                     # 项目说明文档

📝 文档编写规范

1. Frontmatter 规范

所有 Markdown 文件必须包含 frontmatter：

---
title: 文档标题
date: 2026-02-03
category:
  - 分类1
  - 分类2
tag:
  - 标签1
  - 标签2
  - 标签3
---

重要规则：

✅ 使用 frontmatter 的 title 字段定义标题
✅ 添加 date 字段记录文档创建/更新日期
✅ 使用 category 分类文档（支持多个分类）
✅ 使用 tag 添加标签（便于搜索和归类）
❌ 正文中不使用 H1 (#) 标题
✅ 从 H2 (##) 开始组织内容结构

2. 标题层级规范

---
title: 文档标题
---

## 第一个主要章节

内容...

### 子章节

内容...

#### 更细的章节

内容...

## 第二个主要章节

内容...

规则：

标题前后必须有空行（符合 MD022 规范）
不要跳级使用标题（如从 H2 直接到 H4）
保持标题层级的逻辑性

3. 代码块规范

必须指定语言类型：

```javascript
const config = {
  title: 'OmniStackHub',
  description: '全栈技术知识库'
};


**常用语言标识**：
- `javascript` / `js`
- `typescript` / `ts`
- `python` / `py`
- `bash` / `shell`
- `yaml` / `yml`
- `json`
- `markdown` / `md`
- `vue`
- `css` / `scss`

### 4. 列表格式规范

**无序列表**：
```markdown
- 第一项
- 第二项
  - 子项 2.1
  - 子项 2.2
- 第三项

有序列表：

1. 第一步
2. 第二步
3. 第三步

规则：

使用 - 作为无序列表标记（统一风格）
子列表使用 2 空格缩进
列表前后保留空行

5. 链接格式规范

<!-- 内部链接（相对路径） -->
[AI 编程助手](./code/)
[Antigravity 指南](./code/antigravity.md)

<!-- 外部链接 -->
[VuePress 官网](https://v2.vuepress.vuejs.org/zh/)

<!-- 锚点链接 -->
[跳转到项目结构](#项目结构)

6. 表格格式

| 列标题 1 | 列标题 2 | 列标题 3 |
|---------|---------|---------|
| 内容 1  | 内容 2  | 内容 3  |
| 内容 4  | 内容 5  | 内容 6  |

⚙️ 配置文件规范

config.js 核心结构

const { hopeTheme } = require('vuepress-theme-hope');

module.exports = {
  // 基础配置
  lang: 'zh-CN',
  title: 'OmniStackHub',
  description: '全栈技术知识库',
  
  // 主题配置
  theme: hopeTheme({
    // Logo 和站点信息
    logo: '/logo.svg',
    hostname: 'https://your-domain.com',
    
    // 导航栏配置
    navbar: [
      { text: '首页', link: '/' },
      { text: 'AI', link: '/ai/' },
      { text: '指南', link: '/guide/' }
    ],
    
    // 侧边栏配置
    sidebar: {
      '/ai/': [
        {
          text: 'AI 导航',
          link: '/ai/'
        },
        {
          text: 'AI 编程助手',
          prefix: '/ai/code/',
          children: [
            { text: '概述', link: '' },
            { text: 'Antigravity', link: 'antigravity' }
          ]
        }
      ]
    },
    
    // 插件配置
    plugins: {
      // Algolia 搜索
      docsearch: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_API_KEY',
        indexName: 'YOUR_INDEX_NAME'
      },
      
      // Waline 评论
      comment: {
        provider: 'Waline',
        serverURL: 'YOUR_SERVER_URL'
      }
    }
  })
};

配置文件更新规则

保持配置结构
- 使用 CommonJS 格式 (module.exports)
- 保持清晰的注释说明
- 遵循现有的代码风格
导航栏与侧边栏同步更新 ⭐

当在 sidebar 中添加新的文档分类时，必须同时更新 navbar（顶部导航栏），确保用户可以从顶部菜单访问新内容。

示例：添加 AI 助手指南时

✅ 在 sidebar['/ai/'] 中添加 agents 配置
✅ 在 navbar 的 AI 子菜单中添加对应链接
❌ 只更新其中一个会导致导航不一致

使用正确的容器语法

使用 VuePress Hope 主题的容器语法（::: tip、::: warning、::: important 等），不要使用 GitHub 风格的容器（> [!NOTE]、> [!IMPORTANT] 等）。

代码风格规范

// ✅ 推荐
const config = {
  title: 'OmniStackHub',  // 单引号
  items: [                 // 2 空格缩进
    'item1',
    'item2',              // 保留尾随逗号
  ],
};

// ❌ 避免
const config={title:"OmniStackHub",items:['item1','item2']}; // 格式混乱

🎨 VuePress 特殊语法

自定义容器

::: tip 提示
这是一个提示信息
:::

::: warning 注意
这是一个警告信息
:::

::: danger 危险
这是一个危险警告
:::

::: details 点击展开
这是可折叠的详细内容
:::

代码组

::: code-group

```javascript
// JavaScript 版本
console.log('Hello World');

// TypeScript 版本
console.log('Hello World' as string);

Emoji 支持

:tada: :rocket: :sparkles: :bulb: :wrench:

渲染结果：🎉 🚀 ✨ 💡 🔧

🔧 开发工作流

常用命令

# 安装项目依赖
npm install

# 启动开发服务器（支持热重载）
npm run dev
# 访问地址: http://localhost:8080

# 构建生产版本
npm run build
# 输出目录: docs/.vuepress/dist/

添加新文档的完整流程

创建文档文件

# 在对应目录创建 Markdown 文件
touch docs/ai/code/new-tool.md

编写文档内容

---
title: 新工具使用指南
---

## 简介

这是一个新工具的使用指南...

更新侧边栏配置

// 编辑 docs/.vuepress/config.js
sidebar: {
  '/ai/': [
    {
      text: 'AI 编程助手',
      prefix: '/ai/code/',
      children: [
        { text: '概述', link: '' },
        { text: '新工具', link: 'new-tool' }  // 添加这一行
      ]
    }
  ]
}

测试验证
- 启动开发服务器
- 检查导航是否正确
- 验证链接是否有效
- 确认格式是否规范

🤝 AI 助手协作原则

理解需求

分析上下文
- 查看用户当前打开的文件
- 理解用户所在的项目位置
- 考虑用户的具体需求
明确目标
- 确认用户想要实现的功能
- 了解可能的限制条件
- 评估对项目的影响范围

语言规范

中文回复
- 所有对话必须使用中文（简体）回复，除非用户明确要求使用其他语言。
- 保持专业、友好的语气。
- 技术术语可以使用英文（如 Remux, Encode, VuePress），但解释应为中文。

提供帮助

代码建议
- 遵循项目现有的代码风格
- 提供完整可运行的代码示例
- 添加必要的注释说明
文档编写
- 使用清晰简洁的中文表达
- 保持格式与现有文档一致
- 提供实用的代码示例
配置修改
- 保持配置文件的整体结构
- 说明修改的原因和影响
- 提供验证测试的方法

质量保证

格式检查
- Markdown 语法正确性
- 代码块语言标识
- 标题层级合理性
链接验证
- 内部链接路径正确
- 外部链接有效性
- 锚点链接准确性
一致性检查
- 术语使用统一
- 风格保持一致
- 结构符合规范

🚨 常见问题与解决

Markdown 格式错误

问题: 标题前后缺少空行

## 标题
内容开始...  ❌

解决:

## 标题

内容开始...  ✅

链接失效

问题: 使用了错误的相对路径

[链接](/docs/ai/code/tool.md)  ❌

解决:

[链接](./code/tool.md)  ✅

配置不生效

问题: 修改配置后未重启服务器

解决:

# 停止当前服务器 (Ctrl+C)
# 重新启动
npm run dev

💡 最佳实践

文档原则

遵循以下软件工程最佳实践：

1. DRY (Don't Repeat Yourself) - 不重复自己

原则: 避免重复内容，每个知识点只在一个地方定义。

实践:

✅ 规范只在 AGENTS.md 中定义
✅ 其他文档通过引用而非复制
❌ 避免在多个文件中重复相同的规范

示例:

<!-- ✅ 好的做法 -->
详细规范请参考: docs/ai/agents/AGENTS.md

<!-- ❌ 避免的做法 -->
## 文档规范
1. 必须包含 frontmatter...
2. 从 H2 开始...
（在多个文件中重复相同内容）

2. Single Source of Truth - 单一真相来源

原则: 每个信息只有一个权威来源，避免信息不一致。

实践:

✅ AGENTS.md 是项目规范的唯一权威来源
✅ 配置文件（如 config.js）是配置的唯一来源
✅ 更新信息时只需修改一个地方

文档层次:

AGENTS.md              ← 规范的唯一来源
    ↑
    │ 引用
    │
其他文档               ← 引用规范，不重复定义

3. Separation of Concerns - 关注点分离

原则: 不同的文档负责不同的职责，保持清晰的边界。

实践:

文档	职责	不应包含
`AGENTS.md`	项目规范定义	工具配置方法
`HOW-TO-USE.md`	配置和验证方法	具体规范内容
`GEMINI.md`	Gemini 配置	其他工具配置
`CLAUDE.md`	Claude 配置	其他工具配置

示例:

<!-- ✅ AGENTS.md - 只定义规范 -->
## 文档规范
1. 必须包含 frontmatter
2. 从 H2 开始

<!-- ✅ GEMINI.md - 只说明如何配置 -->
## 配置方法
在 Gemini Memory 中添加项目规范...

<!-- ❌ 避免混合职责 -->
在 GEMINI.md 中重复定义规范内容

开发实践

文档优先: 先规划文档结构，再编写内容
保持简洁: 避免冗长的段落，使用列表和表格
代码示例: 提供完整可运行的代码示例
及时更新: 修改功能时同步更新相关文档
测试验证: 在本地验证所有修改的效果
版本控制: 使用 Git 管理文档变更
渐进增强: 逐步添加功能，避免大规模重构

📚 参考资源

文档版本: 1.0.0
创建日期: 2026-02-03
适用范围: 所有 AI 编程助手
维护团队: OmniStackHub