macos-tools/AI-CONTEXT-GUIDE.md

AI 上下文使用指南

概述

AI-CONTEXT.md 是一个自动生成的系统配置汇总文档，专为 AI 辅助开发设计。它包含了完整的系统环境、服务配置、开发工具和运行状态等信息，帮助 AI 助手（如 Claude Code）更准确地理解你的开发环境。

为什么需要这个上下文？

在使用 AI 辅助开发时，AI 需要了解：

• 你的系统配置和硬件能力
• 已安装的工具和版本
• 正在运行的服务和端口
• 可用的资源和存储
• 项目结构和关键路径
• 常用的工作流程

有了这个上下文，AI 可以：

• ✅ 提供更精确的命令建议
• ✅ 避免推荐未安装的工具
• ✅ 使用正确的端口和路径
• ✅ 理解系统限制和容量
• ✅ 给出符合现有架构的方案

---

快速开始

1. 生成上下文

cd /Users/brunogao/work/codes/tools/macos
./scripts/generate-ai-context.sh

输出: AI-CONTEXT.md (约 30-50KB)

2. 在 AI 开发中使用

方式一：直接引用（推荐）

在与 Claude Code 对话时，直接引用这个文件：

请阅读 AI-CONTEXT.md 文件，了解我的系统配置。

Claude 会自动读取并理解你的完整环境。

方式二：针对性引用

只引用你需要的部分：

请查看 AI-CONTEXT.md 中的 DevOps 服务配置部分。

方式三：问题驱动

让 AI 根据上下文回答问题：

根据 AI-CONTEXT.md，我的 Harbor 服务运行在哪个端口？
我应该如何配置镜像缓存？

---

上下文结构说明

1. 系统基础信息

## 🖥️ 系统基础信息
- 硬件配置（CPU、内存、磁盘）
- 操作系统版本
- 网络配置（IP、DNS）

用途:

• 了解系统能力和限制
• 确认网络访问地址
• 评估资源是否充足

2. 开发工具和环境

## 🛠️ 开发工具和环境
- 包管理器（Homebrew）
- 容器运行时（Docker、OrbStack）
- Kubernetes（kubectl、Helm）
- 编程语言（Python、Node.js、Go）
- AI 工具（Ollama、Claude-Qwen）

用途:

• 确认可用的开发工具
• 验证版本兼容性
• 了解 AI 模型列表

3. DevOps 服务配置

## 🚀 DevOps 服务配置
- Gitea（Git 托管 + CI/CD）
- Harbor（容器镜像仓库）
- GitLab（可选）

用途:

• 获取服务访问地址
• 查看服务运行状态
• 了解管理命令

4. Kubernetes 集群状态

## ☸️ Kubernetes 集群状态
- 集群信息
- 节点状态
- 命名空间列表
- 关键工作负载
- Helm Releases

用途:

• 检查集群健康状态
• 了解已部署的应用
• 发现异常 Pod

5. 项目结构和关键路径

## 📁 项目结构和关键路径
- 核心目录结构
- 工具脚本位置
- 配置文件路径

用途:

• 快速定位文件
• 了解项目组织方式
• 找到管理脚本

6. 常用工作流

## 🔄 常用工作流
- AI 辅助开发流程
- 容器镜像管理
- Kubernetes 部署
- 备份和恢复

用途:

• 学习最佳实践
• 复用现有流程
• 快速执行任务

7. 快速参考

## 📚 快速参考
- 服务访问地址表
- 常用命令速查
- 故障排查指南

用途:

• 快速查找信息
• 解决常见问题
• 获取访问凭据

8. 系统健康检查

## 🏥 系统健康检查
- 关键服务状态
- 资源使用情况
- 改进建议

用途:

• 发现潜在问题
• 优化系统性能
• 预防故障

---

实际使用案例

案例 1: 部署新应用

场景: 你想在 Kubernetes 中部署一个新的 Web 应用

与 Claude 的对话:

我想在 Kubernetes 中部署一个 Nginx 应用，请先查看 AI-CONTEXT.md
了解我的集群状态，然后给我一个完整的部署方案。

Claude 会:

1. 读取你的 K8s 集群信息
2. 检查可用的命名空间
3. 确认 Harbor 镜像仓库地址
4. 生成适合你环境的 YAML 配置
5. 提供正确的部署命令

案例 2: 故障排查

场景: 某个 Pod 一直处于 ImagePullBackOff 状态

与 Claude 的对话:

根据 AI-CONTEXT.md 中的信息，我有一个 Pod 处于 ImagePullBackOff 状态，
应该如何修复？

Claude 会:

1. 检查你的 Harbor 配置
2. 找到镜像缓存脚本位置
3. 提供具体的修复命令
4. 解释工作原理

案例 3: 性能优化

场景: 系统运行缓慢，需要优化

与 Claude 的对话:

查看 AI-CONTEXT.md 中的系统健康检查部分，分析当前系统性能，
并给出优化建议。

Claude 会:

1. 分析资源使用情况
2. 检查异常服务
3. 评估磁盘和内存压力
4. 提供针对性的优化方案

案例 4: 配置新服务

场景: 想添加一个新的监控服务

与 Claude 的对话:

我想添加 Prometheus + Grafana 监控，根据 AI-CONTEXT.md 中的配置，
请帮我规划部署方案，包括端口分配和存储配置。

Claude 会:

1. 检查已占用的端口
2. 确认可用的存储空间
3. 规划服务部署位置
4. 生成完整的配置文件
5. 提供部署和验证步骤

---

更新策略

何时更新？

建议定期更新的场景:

1. 每日更新 (推荐)

   # 添加到每日工作流
   cd ~/work/codes/tools/macos && ./scripts/generate-ai-context.sh
   

2. 配置变更后

   • 安装新服务
   • 部署新应用
   • 更新工具版本
   • 修改网络配置

3. 故障排查前

   • 确保信息最新
   • 获取实时状态
   • 准确诊断问题

4. 开始新项目前

   • 了解可用资源
   • 规划架构设计
   • 避免冲突

自动化更新

方法 1: Cron 定时任务

# 编辑 crontab
crontab -e

# 添加每天早上 9 点更新
0 9 * * * cd /Users/brunogao/work/codes/tools/macos && ./scripts/generate-ai-context.sh

方法 2: Shell 别名

# 添加到 ~/.zshrc
alias update-ai-context='cd /Users/brunogao/work/codes/tools/macos && ./scripts/generate-ai-context.sh'

# 使用
update-ai-context

方法 3: Git Hook

# 在 .git/hooks/post-commit
#!/bin/bash
cd /Users/brunogao/work/codes/tools/macos
./scripts/generate-ai-context.sh

---

高级技巧

1. 自定义输出位置

# 生成到自定义位置
./scripts/generate-ai-context.sh /path/to/custom/context.md

2. 多环境管理

# 开发环境
./scripts/generate-ai-context.sh ~/contexts/dev-context.md

# 生产环境
./scripts/generate-ai-context.sh ~/contexts/prod-context.md

3. 版本控制

# 带时间戳的备份
./scripts/generate-ai-context.sh ~/contexts/context-$(date +%Y%m%d).md

4. 差异对比

# 对比两次生成的差异
diff ~/contexts/context-old.md ~/contexts/context-new.md

5. 精简版本

如果完整上下文太大，可以创建精简版：

# 只提取关键部分
grep -A 20 "## 🚀 DevOps 服务配置" AI-CONTEXT.md > AI-CONTEXT-MINIMAL.md
grep -A 30 "## ☸️ Kubernetes 集群状态" AI-CONTEXT.md >> AI-CONTEXT-MINIMAL.md
grep -A 20 "## 📚 快速参考" AI-CONTEXT.md >> AI-CONTEXT-MINIMAL.md

---

与团队分享

1. 文档化环境

将 AI-CONTEXT.md 加入版本控制：

# .gitignore 中移除
# !AI-CONTEXT.md

git add AI-CONTEXT.md
git commit -m "docs: 添加系统配置上下文"

2. 标准化环境

团队成员可以对比配置差异：

# 对比你的环境和标准环境
diff AI-CONTEXT.md ../teammate/AI-CONTEXT.md

3. 环境迁移

使用上下文帮助新成员快速了解环境：

# 新成员入职清单
1. 克隆仓库
2. 生成 AI-CONTEXT.md
3. 对比与标准配置的差异
4. 安装缺失的工具
5. 配置服务

---

故障排查

问题 1: 脚本执行失败

症状: permission denied

解决:

chmod +x /Users/brunogao/work/codes/tools/macos/scripts/generate-ai-context.sh

问题 2: 信息不完整

症状: 某些服务信息显示为 "N/A"

原因: 服务未运行或权限不足

解决:

# 启动服务
docker-compose up -d

# 检查权限
docker ps
kubectl get nodes

问题 3: 文件太大

症状: AI-CONTEXT.md 超过 100KB

原因: 容器或 Pod 数量太多

解决: 使用精简模式或过滤输出

问题 4: 信息过时

症状: 上下文中的信息与实际不符

解决: 重新生成

./scripts/generate-ai-context.sh

---

最佳实践

✅ 推荐做法

1. 定期更新: 每天或每次重大配置变更后更新
2. 版本控制: 保留历史版本用于对比
3. 针对性引用: 只让 AI 读取需要的部分
4. 及时验证: 更新后检查关键信息是否正确
5. 团队共享: 将上下文作为环境文档

❌ 避免做法

1. 过度依赖: 不要完全依赖自动生成的信息
2. 忽视更新: 长期不更新导致信息过时
3. 无差别共享: 注意敏感信息（密码、密钥）
4. 盲目执行: AI 建议的命令应该理解后再执行
5. 忽视差异: 不同环境的配置可能不同

---

扩展和定制

添加自定义信息

编辑 scripts/generate-ai-context.sh，在相应位置添加：

# 示例：添加自定义工具检查
cat >> "$OUTPUT_FILE" << EOF
### 自定义工具
$(if check_command your-tool; then
    echo "- **Your Tool**: $(your-tool --version)"
else
    echo "- **Your Tool**: ❌ 未安装"
fi)
EOF

集成其他监控

# 添加 Prometheus 指标
cat >> "$OUTPUT_FILE" << EOF
### Prometheus 指标
\`\`\`
$(curl -s http://localhost:9090/api/v1/targets | jq '.data.activeTargets[] | {job, health}')
\`\`\`
EOF

---

总结

AI-CONTEXT.md 是你的环境配置的"数字孪生"，它让 AI 助手能够：

• 🎯 精准理解你的环境
• 🚀 快速响应你的需求
• 💡 智能建议最佳方案
• 🛡️ 避免错误配置

记住三个关键点:

1. 保持更新: 定期重新生成上下文
2. 善用引用: 让 AI 读取相关部分
3. 验证建议: 理解 AI 的建议再执行

立即开始:

cd /Users/brunogao/work/codes/tools/macos
./scripts/generate-ai-context.sh

然后在 Claude Code 中说：

请阅读 AI-CONTEXT.md，了解我的系统配置。

享受更智能、更高效的 AI 辅助开发体验！