Ai Tools Checklist
AI辅助编程 - 工具配置清单与适应框架
创建日期: 2026-01-06 配套文档: ai-assisted-programming-sop-260106.md
🚀 快速启动清单(按优先级排序)
Level 1: 必须立即配置(Day 1)
1.1 核心AI工具
Claude Code CLI
# 安装 npm install -g @anthropic/claude-code # 验证 claude --version # 配置API密钥 claude auth loginIDE集成
# VS Code code --install-extension anthropic.claude-code # Cursor (可选,替代VS Code) # 下载: https://cursor.shAPI访问
- Anthropic API密钥
- 设置使用限额(防止意外超支)
- 配置重试策略
预计时间: 30分钟
1.2 版本控制增强
Git Hooks自动化
# 安装Husky npm install -g husky cd your-project husky init # 创建pre-commit hook cat > .husky/pre-commit << 'EOF' #!/bin/sh . "$(dirname "$0")/_/husky.sh" echo "🔍 运行AI辅助代码检查..." npm run lint || exit 1 npm run test:unit || exit 1 npm run type-check || exit 1 echo "✅ 所有检查通过" EOF chmod +x .husky/pre-commit.gitignore优化
# AI生成的临时文件 .ai-cache/ .ai-temp/ *.ai-backup # 敏感信息(永远不要提交) .env .env.local *.key
预计时间: 15分钟
1.3 代码质量工具
Linter(选择你的语言)
# Python pip install ruff # 配置: pyproject.toml [tool.ruff] line-length = 100 select = ["E", "F", "W", "I"] # JavaScript/TypeScript npm install -D eslint # 配置: .eslintrc.json { "extends": ["eslint:recommended"], "parser": "@typescript-eslint/parser" } # Go go install golang.org/x/lint/golint@latestFormatter
# Python pip install black # JavaScript/TypeScript npm install -D prettier # 配置.prettierrc { "semi": true, "singleQuote": true, "tabWidth": 2 }静态分析
# Python pip install mypy pylint # TypeScript(内置) # JavaScript npm install -D typescript-eslint
预计时间: 45分钟
Level 2: 本周内配置(Day 2-7)
2.1 测试框架
单元测试
# Python pip install pytest pytest-cov # JavaScript npm install -D vitest # 配置package.json { "scripts": { "test": "vitest", "test:coverage": "vitest --coverage" } }测试覆盖率报告
# Python pytest --cov=src --cov-report=html # JavaScript vitest --coverage
预计时间: 1小时
2.2 MCP服务器(Model Context Protocol)
什么是MCP? MCP允许你创建自定义工具,让AI可以访问特定功能(数据库、API、文件系统等)。
核心MCP服务器
// ~/.claude.json { "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@anthropic/mcp-server-filesystem", "/path/to/allowed/dir"] }, "git": { "command": "npx", "args": ["-y", "@anthropic/mcp-server-git", "--repository", "/path/to/repo"] }, "database": { "command": "npx", "args": ["-y", "@anthropic/mcp-server-postgres", "postgresql://user:pass@localhost/db"] } } }自定义MCP服务器模板
# mcp-mytool/server.py from mcp import MCPServer from mcp.types import Tool, TextContent server = MCPServer("my-custom-tool") @server.tool() async def analyze_logs(log_file: str) -> list[TextContent]: """分析日志文件并提取关键信息""" import re with open(log_file, 'r') as f: logs = f.read() # 提取错误 errors = re.findall(r'ERROR: (.+)', logs) return [TextContent( type="text", text=f"发现 {len(errors)} 个错误:\n" + "\n".join(errors[:10]) )] if __name__ == "__main__": server.run()测试MCP服务器
# 本地运行测试 mcp dev mcp-mytool # 在Claude Code中测试 /claude 使用analyze_logs工具分析app.log
预计时间: 2-3小时
2.3 CI/CD集成
GitHub Actions工作流
# .github/workflows/ai-assisted-ci.yml name: AI-Assisted CI on: [push, pull_request] jobs: ai-verify: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '20' - name: Install dependencies run: npm ci - name: Run linter run: npm run lint - name: Run type check run: npm run type-check - name: Run tests run: npm run test:coverage - name: AI Code Review (if PR) if: github.event_name == 'pull_request' run: | echo "Triggering AI review..." # 这里可以调用AI API进行代码审查自动化PR审查
# 创建GitHub Action # .github/workflows/ai-pr-review.yml name: AI PR Review on: pull_request: types: [opened, synchronize] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: AI Review uses:alex-courtis/ai-pr-review@v1 with: anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }} max-tokens: 4000
预计时间: 1.5小时
Level 3: 高级配置(Week 2-4)
3.1 监控与可观测性
性能监控
// 添加到你的应用 const perfObserver = new PerformanceObserver((list) => { for (const entry of list.getEntries()) { console.log(`[PERF] ${entry.name}: ${entry.duration}ms`); } }); perfObserver.observe({ entryTypes: ['measure', 'navigation'] });错误追踪
# Sentry npm install @sentry/node # 配置 Sentry.init({ dsn: process.env.SENTRY_DSN, tracesSampleRate: 1.0, });日志聚合
# docker-compose.yml version: '3' services: app: image: your-app logging: driver: "json-file" options: max-size: "10m" max-file: "3" loki: image: grafana/loki:latest ports: - "3100:3100" promtail: image: grafana/promtail:latest volumes: - /var/log:/var/log:ro - ./promtail-config.yml:/etc/promtail/config.yml
预计时间: 2-3小时
3.2 文档生成
自动API文档
# Python pip install sphinx sphinx-rtd-theme # 生成文档 sphinx-quickstart docs sphinx-build -b html docs/ docs/_build/ # JavaScript npm install -D typedoc typedoc --out docs src架构图自动生成
# 使用AI生成Mermaid图 prompt = """ 分析以下代码库,生成: 1. 系统架构图(Mermaid格式) 2. 数据流图 3. 组件依赖关系 代码库结构: {repository_structure} """
预计时间: 1-2小时
🔧 适应框架详细实现
A1框架: 工具执行信号适应
概念: AI根据工具执行结果动态调整策略
实现模板
# tools/adaptive_executor.py
from typing import Callable, Any, Dict
import subprocess
import json
class AdaptiveExecutor:
def __init__(self):
self.tool_history = {}
self.failure_patterns = {}
async def execute_with_adaptation(
self,
primary_tool: Callable,
fallback_tools: list[Callable],
context: Dict[str, Any]
) -> tuple[bool, Any]:
"""
执行工具,失败时自动适应
返回: (success, result)
"""
# 尝试主工具
try:
result = await primary_tool(**context)
self._record_success(primary_tool.__name__, context)
return True, result
except Exception as e:
error_type = type(e).__name__
error_msg = str(e)
# 分析失败模式
strategy = self._analyze_failure(error_type, error_msg)
# 根据策略选择适应方案
if strategy == "retry_with_modified_params":
modified_context = self._modify_params(context, error_msg)
return await self.execute_with_adaptation(
primary_tool, fallback_tools, modified_context
)
elif strategy == "switch_to_fallback":
for fallback in fallback_tools:
try:
result = await fallback(**context)
self._record_success(fallback.__name__, context)
return True, result
except Exception:
continue
# 所有策略都失败
return False, error_msg
def _analyze_failure(self, error_type: str, error_msg: str) -> str:
"""分析失败原因,返回适应策略"""
if "timeout" in error_msg.lower():
return "increase_timeout"
elif "permission" in error_msg.lower():
return "escalate_permissions"
elif "not found" in error_msg.lower():
return "switch_to_fallback"
else:
return "retry_with_modified_params"
def _modify_params(self, context: Dict, error_msg: str) -> Dict:
"""根据错误信息修改参数"""
modified = context.copy()
if "timeout" in error_msg:
modified["timeout"] = modified.get("timeout", 30) * 2
return modified
def _record_success(self, tool_name: str, context: Dict):
"""记录成功模式"""
key = f"{tool_name}:{json.dumps(context, sort_keys=True)}"
self.tool_history[key] = self.tool_history.get(key, 0) + 1
使用示例
# 使用A1框架
executor = AdaptiveExecutor()
async def git_push(branch: str):
subprocess.run(["git", "push", "origin", branch], check=True)
async def git_push_with_force(branch: str):
subprocess.run(["git", "push", "origin", branch, "--force-with-lease"], check=True)
async def git_push_via_ssh(branch: str):
subprocess.run(["GIT_SSH=ssh", "git", "push", "origin", branch], check=True)
# 执行(自动适应)
success, result = await executor.execute_with_adaptation(
primary_tool=git_push,
fallback_tools=[git_push_with_force, git_push_via_ssh],
context={"branch": "main"}
)
if success:
print("✅ Push成功")
else:
print(f"❌ Push失败: {result}")
A2框架: 代理输出信号适应
概念: AI根据自身输出质量调整后续行为
实现模板
# agents/quality_feedback_agent.py
from typing import List, Tuple
import subprocess
class QualityFeedbackAgent:
def __init__(self, quality_threshold: float = 0.8):
self.threshold = quality_threshold
self.feedback_history = []
async def generate_with_feedback(
self,
generator: Callable,
prompt: str,
max_iterations: int = 3
) -> Tuple[bool, str]:
"""
生成代码,根据质量反馈迭代优化
返回: (success, final_output)
"""
for iteration in range(max_iterations):
# 生成输出
output = await generator(prompt)
# 评估质量
quality = await self._evaluate_quality(output)
print(f"Iteration {iteration + 1}: Quality = {quality:.2f}")
# 如果达到阈值,返回
if quality >= self.threshold:
self._record_success(prompt, output)
return True, output
# 否则,生成反馈并重新生成
feedback = await self._generate_feedback(output, quality)
prompt = self._refine_prompt(prompt, feedback)
# 达到最大迭代次数
return False, output
async def _evaluate_quality(self, code: str) -> float:
"""评估代码质量(0-1)"""
score = 0.0
max_score = 0.0
# 1. Linting检查
try:
result = subprocess.run(
["ruff", "check", "--output-format=json", "-"],
input=code,
capture_output=True,
text=True
)
if result.returncode == 0:
score += 0.3
max_score += 0.3
except Exception:
pass
# 2. 类型检查
try:
result = subprocess.run(
["mypy", "-", "--no-error-summary"],
input=code,
capture_output=True,
text=True
)
if result.returncode == 0:
score += 0.3
max_score += 0.3
except Exception:
pass
# 3. 测试通过率
try:
# 假设测试已经设置
result = subprocess.run(
["pytest", "-q"],
capture_output=True,
text=True,
timeout=30
)
if result.returncode == 0:
score += 0.4
max_score += 0.4
except Exception:
pass
return score / max_score if max_score > 0 else 0.0
async def _generate_feedback(self, code: str, quality: float) -> str:
"""生成改进反馈"""
feedback = []
# 运行各种检查工具
checks = {
"lint": ["ruff", "check", "-"],
"type": ["mypy", "-"],
}
for check_name, cmd in checks.items():
try:
result = subprocess.run(
cmd,
input=code,
capture_output=True,
text=True
)
if result.returncode != 0:
feedback.append(f"### {check_name.upper()} 失败:\n{result.stdout}")
except Exception:
pass
return "\n\n".join(feedback)
def _refine_prompt(self, original_prompt: str, feedback: str) -> str:
"""根据反馈优化提示"""
return f"""{original_prompt}
上次尝试的反馈:
{feedback}
请根据这些反馈修复问题。"""
def _record_success(self, prompt: str, output: str):
"""记录成功模式"""
self.feedback_history.append({
"prompt": prompt,
"output": output,
"success": True
})
使用示例
# 使用A2框架
agent = QualityFeedbackAgent(quality_threshold=0.8)
async def code_generator(prompt: str) -> str:
# 这里调用Claude API
response = await claude.messages.create(
model="claude-opus-4-5",
max_tokens=4000,
messages=[{"role": "user", "content": prompt}]
)
return response.content[0].text
# 生成并迭代优化
success, code = await agent.generate_with_feedback(
generator=code_generator,
prompt="写一个Python函数来计算斐波那契数列",
max_iterations=3
)
if success:
print("✅ 代码质量达标")
print(code)
else:
print("⚠️ 未达到质量阈值,但这是最佳结果")
print(code)
📋 每日检查清单
早晨启动(5分钟)
- 打开Claude Code/Cursor
- 检查今日任务列表
- 确认AI模型版本(是否有更新)
- 快速扫描待处理的PR/Issues
工作中(按需)
- 使用AI前:压缩上下文
- AI生成后:立即验证
- 遇到问题:记录到知识库
- 发现新模式:更新提示模板
晚间复盘(10分钟)
- 记录今日成就
- 记录失败案例
- 更新生产力指标
- 规划明日任务
🎯 生产力追踪表
每日日志模板
## 260106 工作日志
### 今日任务
- [x] 任务1: XXX (2小时)
- [x] 任务2: XXX (1.5小时)
- [ ] 任务3: XXX (未完成)
### AI使用统计
- 代码生成: 15次
- 调试: 3次
- 代码审查: 5次
- 文档生成: 2次
### 生产力指标
- PR完成: 2个
- 代码行数: 500 (手动: 50, AI: 450)
- Bug修复: 3个
- 学习时间: 1小时
### 关键发现
1. 发现XX任务用AI可节省80%时间
2. 提示模板Y效果最好
3. 工具Z在XX场景下不适用
### 失败教训
- 案例: XXX
- 原因: 提示不够清晰
- 改进: 添加具体示例
### 明日计划
1. 优化XX提示模板
2. 学习YY新技术
3. 完成ZZ任务
🚨 常见问题与解决方案
Q1: AI生成的代码无法运行
症状: 直接运行报错 原因:
- 上下文不足
- 约束条件不明确
- 环境差异
解决:
- 提供完整的上下文(依赖、版本、配置)
- 明确错误处理要求
- 让AI先生成测试,再生成代码
Q2: AI给出错误建议
症状: 建议不符合实际或不安全 原因:
- AI不了解具体场景
- 缺少安全约束
- 幻觉(编造不存在的内容)
解决:
- 要求AI提供引用和证据
- 添加安全审查步骤
- 对关键决策进行人工验证
Q3: 上下文太大,AI无法处理
症状: AI回复"上下文太长"或给出不相关答案 原因:
- 代码库太大
- 信息冗余
解决:
- 使用
/rosetta-experimental-learningskill追踪数据流 - 分阶段提供上下文(先架构,再细节)
- 使用外部化规格(文档、图表)
Q4: AI修改了不该改的代码
症状: AI修改了其他功能 原因:
- 任务边界不清晰
- 缺少负样本
解决:
- 明确"只修改XXX,不要动YYY"
- 提供测试验证范围
- 使用Git diff人工审查
📚 进阶学习资源
每月学习计划
Month 1: 基础掌握
- Week 1: 熟悉Claude Code基础功能
- Week 2: 掌握提示工程
- Week 3: 学习适应框架(A1/A2)
- Week 4: 完成一个小项目
Month 2: 进阶技巧
- Week 1: 开发自定义MCP服务器
- Week 2: 集成CI/CD
- Week 3: 建立知识库
- Week 4: 优化工作流
Month 3: 规模化应用
- Week 1: 团队协作最佳实践
- Week 2: 多agent协作
- Week 3: 性能优化
- Week 4: 开源贡献
推荐阅读顺序
- Claude Code官方文档 - 了解所有功能
- “Attention Is All You Need” - 理解Transformer基础
- “Sparks of AGI” - 了解LLM能力边界
- Stanford HAI论文 - AI辅助工程框架
- Anthropic技术博客 - 最新研究进展
✅ 配置验证脚本
#!/bin/bash
# verify-ai-setup.sh - 验证AI工具配置
echo "🔍 验证AI辅助编程环境..."
# 1. Claude Code
if command -v claude &> /dev/null; then
echo "✅ Claude Code: $(claude --version)"
else
echo "❌ Claude Code未安装"
fi
# 2. Git
if command -v git &> /dev/null; then
echo "✅ Git: $(git --version)"
else
echo "❌ Git未安装"
fi
# 3. Python工具(如果适用)
if command -v python3 &> /dev/null; then
echo "✅ Python: $(python3 --version)"
if command -v ruff &> /dev/null; then
echo "✅ Ruff: $(ruff --version)"
fi
if command -v mypy &> /dev/null; then
echo "✅ MyPy: $(mypy --version)"
fi
fi
# 4. Node工具(如果适用)
if command -v node &> /dev/null; then
echo "✅ Node: $(node --version)"
if command -v eslint &> /dev/null; then
echo "✅ ESLint: $(eslint --version)"
fi
fi
# 5. MCP配置
if [ -f ~/.claude.json ]; then
echo "✅ MCP配置文件存在"
# 可以添加更多检查
else
echo "⚠️ ~/.claude.json不存在"
fi
echo "✨ 验证完成!"
总结
这份清单提供了完整的工具配置和适应框架实现。关键要点:
- 渐进式配置: 从Level 1开始,逐步添加
- 自动化优先: 能自动化的都自动化
- 持续验证: 每个配置都要验证可用性
- 记录学习: 建立个人知识库
下一步:
- 运行
verify-ai-setup.sh验证当前环境 - 从Level 1开始配置
- 完成30天行动计划
- 分享你的经验和方法