diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index 033747e..ec37a0d 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -398,6 +398,20 @@ const stage3SidebarEn = [ { text: 'Claude Code 工作流最佳实践', link: '/zh-cn/stage-3/core-skills/workflow/' + }, + { + text: 'Claude Code 手机远程开发', + link: '/zh-cn/stage-3/core-skills/mobile-development/' + }, + { + text: 'Claude Agent SDK 完全指南', + link: '/zh-cn/stage-3/core-skills/claude-agent-sdk/', + items: [ + { + text: 'Spec Coding：规范驱动开发', + link: '/zh-cn/stage-3/core-skills/claude-agent-sdk/spec-coding' + } + ] } ] }, @@ -1245,6 +1259,18 @@ export default defineConfig({ { text: 'Claude Code 工作流最佳实践', link: '/zh-cn/stage-3/core-skills/workflow/' + }, + { + text: 'Claude Code 手机远程开发', + link: '/zh-cn/stage-3/core-skills/mobile-development/' + }, + { + text: 'Claude Agent SDK 完全指南', + link: '/zh-cn/stage-3/core-skills/claude-agent-sdk/' + }, + { + text: '从 Vibe Coding 到 Spec Coding', + link: '/zh-cn/stage-3/core-skills/spec-coding/' } ] }, diff --git a/docs/zh-cn/stage-3/core-skills/basics/index.md b/docs/zh-cn/stage-3/core-skills/basics/index.md index 6173b81..029115d 100644 --- a/docs/zh-cn/stage-3/core-skills/basics/index.md +++ b/docs/zh-cn/stage-3/core-skills/basics/index.md @@ -569,6 +569,67 @@ Token 使用：45,230 / 200,000 (22.6%) 2. **优化 .claudeignore**：将不相关的文件（如 node_modules、构建产物）加入忽略列表 3. **决定何时压缩**：当使用率超过 70% 时，考虑使用 `/compact` +### 技巧 11：/resume 恢复会话 —— 切换多任务对话 + +当你在处理多个任务时，可能会开启多段对话。`/resume` 能让你在当前聊天中快速切换回之前的会话，而不需要退出重新启动。 + +**使用方式：** + +``` +/resume +``` + +**工作原理：** + +Claude Code 会自动记录你之前的对话会话。当你使用 `/resume` 时，它会切换回上一段会话的上下文，保留之前的所有讨论内容和状态。 + +**使用场景：** + +**场景 A：多任务并行处理** +``` +# 任务 1：修复 bug +claude> 修复登录页面的验证问题 +# ... 进行了一段对话... + +# 任务 2：添加新功能（新开一段会话） +claude> 添加用户注册功能 +# ... 进行了另一段对话... + +# 切换回任务 1 +claude> /resume +# 继续之前的 bug 修复工作 +``` + +**场景 B：临时查询后返回** +``` +claude> 解释一下这个算法 +# ... 讨论算法... + +claude> /resume +# 自动切换回之前的代码开发工作 +``` + +**场景 C：对话中断后继续** +``` +claude> 继续之前的工作 +# 如果你之前中断了某个任务，可以用 /resume 返回 +``` + +**与相关命令的对比：** + +| 命令 | 作用 | 使用场景 | +|------|------|----------| +| `/resume` | 在当前聊天中切换回上一段会话 | 多任务并行，需要来回切换 | +| `claude -c` | 继续最近的一次会话 | 退出后重新连接同一会话 | +| `claude -r` | 恢复上一段会话 | 退出后恢复到之前的会话状态 | +| `双击 Esc` | 回退到上一次对话状态 | 撤销最近一轮对话 | + +**使用建议：** + +1. **多任务管理**：当你需要在多个任务之间切换时，使用 `/resume` 比重新描述上下文更高效 +2. **会话记忆**：每段会话都有独立的上下文，`/resume` 能帮你保留这些上下文 +3. **配合 /compact**：在长会话中，可以先 `/compact` 压缩，再 `/resume` 切换，保持上下文清晰 + --- ## 核心配置 diff --git a/docs/zh-cn/stage-3/core-skills/claude-agent-sdk/index.md b/docs/zh-cn/stage-3/core-skills/claude-agent-sdk/index.md new file mode 100644 index 0000000..134678b --- /dev/null +++ b/docs/zh-cn/stage-3/core-skills/claude-agent-sdk/index.md @@ -0,0 +1,689 @@ +# Claude Agent SDK 完全指南 + +## 引言 + +你可能已经用过 Claude 的基础 API——发一条消息，拿一个回复，就像聊天一样。但如果你想让 Claude 帮你读文件、跑命令、搜代码、改 bug，然后自己验证结果，再继续改……这种"自主干活"的能力，基础 API 是做不到的。 + +Claude Agent SDK 就是为这个场景而生的。它把 Claude Code 的全部能力——读写文件、执行命令、搜索代码、编辑文件、浏览网页——封装成了一个可编程的库。你不需要自己写工具调用循环，Claude 会自主执行工具、自主迭代，直到任务真正完成。 + +一句话总结：基础 SDK 是"你问它答"，Agent SDK 是"你下单它干活"。 + +--- + +## 它和基础 SDK 到底有什么区别？ + +先看代码，一目了然： + +```python +# 基础 anthropic SDK：你得自己写循环处理工具调用 +import anthropic + +client = anthropic.Anthropic() +response = client.messages.create( + model="claude-sonnet-4-6", + max_tokens=1024, + messages=[{"role": "user", "content": "修复 auth.py 的 bug"}], + tools=[...] # 你得自己定义工具 +) +# Claude 说要调用某个工具 +while response.stop_reason == "tool_use": + result = your_tool_executor(response.tool_use) # 你得自己执行 + response = client.messages.create(tool_result=result, **params) # 你得自己喂回去 +``` + +```python +# Agent SDK：一行搞定，Claude 自己读文件、找 bug、改代码 +from claude_agent_sdk import query, ClaudeAgentOptions + +async for message in query( + prompt="修复 auth.py 的 bug", + options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]), +): + print(message) # Claude 自己读文件、定位问题、修改代码 +``` + +区别很明显： + +| 对比项 | 基础 anthropic SDK | Claude Agent SDK | +|--------|-------------------|-----------------| +| 工具执行 | 你自己写 | Claude 自己来 | +| 工具循环 | 你自己实现 | 内置 agent loop | +| 内置工具 | 无，全靠你定义 | 读写文件、Bash、搜索等开箱即用 | +| 上下文管理 | 你自己维护 | 自动压缩、自动管理 | +| 适合场景 | 聊天、生成、简单 tool use | 自主完成复杂任务 | + +--- + +## 安装和配置 + +### 安装 + +Python 需要 3.10+，TypeScript 需要 Node.js 18+： + +```bash +# Python +pip install claude-agent-sdk + +# TypeScript +npm install @anthropic-ai/claude-agent-sdk +``` + +### 认证 + +设置 API Key 环境变量即可： + +```bash +export ANTHROPIC_API_KEY=your-api-key +``` + +也支持云平台认证： +- AWS Bedrock：设置 `CLAUDE_CODE_USE_BEDROCK=1` + AWS 凭证 +- Google Vertex AI：设置 `CLAUDE_CODE_USE_VERTEX=1` + GCP 凭证 +- Microsoft Azure：设置 `CLAUDE_CODE_USE_FOUNDRY=1` + Azure 凭证 + +### 自定义 API 地址 + +如果你用的是代理、网关或者自建的 API 端点，可以通过 `env` 参数修改默认的 API URL： + +```python +from claude_agent_sdk import query, ClaudeAgentOptions + +async for message in query( + prompt="Hello", + options=ClaudeAgentOptions( + env={ + "ANTHROPIC_BASE_URL": "https://your-proxy.example.com", + "ANTHROPIC_API_KEY": "your-api-key", + } + ), +): + print(message) +``` + +`ClaudeAgentOptions` 没有直接的 `base_url` 参数，但 `env` 字段可以传入任意环境变量给底层的 Claude Code CLI。常用的环境变量： + +| 环境变量 | 用途 | +|---------|------| +| `ANTHROPIC_BASE_URL` | 自定义 API 端点（代理、网关） | +| `ANTHROPIC_API_KEY` | API 密钥 | +| `ANTHROPIC_AUTH_TOKEN` | 替代认证 token | +| `ANTHROPIC_CUSTOM_HEADERS` | 自定义请求头 | + +--- + +## 核心概念 + +Agent SDK 的运行原理可以用一句话概括：**收集上下文 → 执行动作 → 验证结果 → 重复**。 + +这和人类开发者的工作方式一模一样——先看代码，再改代码，然后跑测试看结果，不对就继续改。Agent SDK 把这个循环自动化了。 + +### 两种使用模式 + +**模式一：`query()` 函数 —— 无状态，适合单次任务** + +```python +import asyncio +from claude_agent_sdk import query, ClaudeAgentOptions + +async def main(): + async for message in query( + prompt="这个目录下有哪些文件？", + options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]), + ): + if hasattr(message, "result"): + print(message.result) + +asyncio.run(main()) +``` + +**模式二：`ClaudeSDKClient` —— 有状态，适合多轮对话** + +当你需要保持上下文、多轮交互时使用。比如先让 Claude 读一个模块，再让它找所有调用这个模块的地方——第二轮它还记得第一轮读了什么。 + +```python +import asyncio +from claude_agent_sdk import query, ClaudeAgentOptions + +async def main(): + session_id = None + + # 第一轮：读认证模块 + async for message in query( + prompt="读一下认证模块的代码", + options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]), + ): + if hasattr(message, "subtype") and message.subtype == "init": + session_id = message.session_id + + # 第二轮：基于上下文继续工作 + async for message in query( + prompt="找出所有调用它的地方", + options=ClaudeAgentOptions(resume=session_id), + ): + if hasattr(message, "result"): + print(message.result) + +asyncio.run(main()) +``` + +--- + +## 内置工具：开箱即用 + +这是 Agent SDK 最爽的地方——你不需要自己实现任何工具，Claude 直接就能用： + +| 工具 | 功能 | 典型用途 | +|------|------|---------| +| Read | 读取文件 | 看代码、读配置 | +| Write | 创建文件 | 生成新文件 | +| Edit | 精确编辑文件 | 改 bug、重构 | +| Bash | 执行终端命令 | 跑测试、装依赖、git 操作 | +| Glob | 按模式找文件 | `**/*.py`、`src/**/*.ts` | +| Grep | 正则搜索文件内容 | 找函数定义、找 TODO | +| WebSearch | 搜索网页 | 查文档、找方案 | +| WebFetch | 抓取网页内容 | 读在线文档 | +| Task | 启动子 agent | 并行处理子任务 | + +通过 `allowed_tools` 参数控制 agent 能用哪些工具： + +```python +# 只读 agent：只能看，不能改 +options = ClaudeAgentOptions( + allowed_tools=["Read", "Glob", "Grep"], + permission_mode="bypassPermissions" +) + +# 全能 agent：能读能写能跑命令 +options = ClaudeAgentOptions( + allowed_tools=["Read", "Write", "Edit", "Bash", "Glob", "Grep"] +) +``` + +--- + +## 高级功能 + +### Hooks：在关键节点插入你的逻辑 + +Hooks 让你在 agent 执行的关键时刻插入自定义代码——比如记录日志、拦截危险操作、审计文件变更。 + +支持的 Hook 类型：`PreToolUse`（工具执行前）、`PostToolUse`（工具执行后）、`Stop`（agent 停止时）、`SessionStart`、`SessionEnd` 等。 + +```python +from datetime import datetime +from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher + +# 每次文件被修改时，记录到审计日志 +async def log_file_change(input_data, tool_use_id, context): + file_path = input_data.get("tool_input", {}).get("file_path", "unknown") + with open("./audit.log", "a") as f: + f.write(f"{datetime.now()}: modified {file_path}\n") + return {} + +async def main(): + async for message in query( + prompt="重构 utils.py 提升可读性", + options=ClaudeAgentOptions( + permission_mode="acceptEdits", + hooks={ + "PostToolUse": [ + HookMatcher(matcher="Edit|Write", hooks=[log_file_change]) + ] + }, + ), + ): + if hasattr(message, "result"): + print(message.result) +``` + +实际用途： +- 审计日志：记录 agent 的每一步操作 +- 安全拦截：阻止 agent 修改某些关键文件 +- 通知推送：agent 完成任务时发送消息 +- 成本监控：统计工具调用次数和 token 消耗 + +### 子 Agent：把大任务拆给专家 + +当任务足够复杂时，你可以定义多个专门的子 agent，让主 agent 把子任务分配给它们。每个子 agent 有自己的指令和工具权限，互不干扰。 + +```python +from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition + +async for message in query( + prompt="用 code-reviewer agent 审查这个项目的代码质量", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Glob", "Grep", "Task"], + agents={ + "code-reviewer": AgentDefinition( + description="专业代码审查员，负责质量和安全审查", + prompt="分析代码质量，找出潜在问题并给出改进建议。", + tools=["Read", "Glob", "Grep"], + ), + "test-writer": AgentDefinition( + description="测试专家，负责编写单元测试", + prompt="为缺少测试的函数编写单元测试。", + tools=["Read", "Write", "Bash"], + ), + }, + ), +): + if hasattr(message, "result"): + print(message.result) +``` + +子 agent 的消息会带有 `parent_tool_use_id` 字段，方便你追踪哪些消息来自哪个子 agent。 + +### MCP 集成：接入外部世界 + +通过 Model Context Protocol（MCP），你的 agent 可以连接数据库、浏览器、第三方 API 等外部系统。社区已经有[数百个 MCP 服务器](https://github.com/modelcontextprotocol/servers)可以直接用。 + +```python +# 接入 Playwright，让 agent 能操作浏览器 +async for message in query( + prompt="打开 example.com 并描述你看到了什么", + options=ClaudeAgentOptions( + mcp_servers={ + "playwright": { + "command": "npx", + "args": ["@playwright/mcp@latest"] + } + } + ), +): + if hasattr(message, "result"): + print(message.result) +``` + +常见的 MCP 集成场景： +- Playwright：浏览器自动化，爬取网页、填写表单 +- PostgreSQL/MySQL：直接查询和操作数据库 +- Slack/Email：发送通知和消息 +- GitHub：操作 PR、Issue、代码仓库 + +--- + +## 能用来做什么？实战场景 + +理解了功能之后，最重要的问题是：这东西到底能干嘛？下面是经过社区验证的真实场景。 + +### 场景一：自动修 Bug Agent + +给它一个 bug 描述，它自己找代码、定位问题、修复、跑测试验证： + +```python +async for message in query( + prompt="用户反馈登录时偶尔报 500 错误，请排查 src/auth/ 目录下的代码并修复", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Edit", "Bash", "Glob", "Grep"], + permission_mode="acceptEdits", + ), +): + print(message) +``` + +Claude 会自己 grep 错误日志、读相关代码、找到 bug、改代码、跑测试确认修复。 + +### 场景二：代码审查 Agent + +构建一个只读的代码审查 agent，审查代码质量但不做任何修改： + +```python +async for message in query( + prompt="审查 src/ 目录下的代码，关注安全漏洞、性能问题和代码规范", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Glob", "Grep"], + permission_mode="bypassPermissions", + ), +): + if hasattr(message, "result"): + print(message.result) +``` + +### 场景三：CI/CD 集成 + +在持续集成流水线中，让 agent 自动分析失败的测试并尝试修复： + +```python +async for message in query( + prompt="运行 npm test，分析失败的测试用例，修复代码使所有测试通过", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Edit", "Bash", "Glob"], + max_turns=20, + ), +): + print(message) +``` + +这是 Agent SDK 相比 CLI 最大的优势场景——CLI 适合人坐在终端前交互，SDK 适合嵌入到自动化流程中。 + +### 场景四：研究 Agent + +让 agent 搜索网络、阅读文档、综合信息并输出报告： + +```python +async for message in query( + prompt="调研 2026 年主流的 Python Web 框架，对比 FastAPI、Django、Litestar，输出技术选型报告到 report.md", + options=ClaudeAgentOptions( + allowed_tools=["WebSearch", "WebFetch", "Write"], + ), +): + print(message) +``` + +### 场景五：带浏览器的全栈 Agent + +通过 MCP 接入 Playwright，agent 不仅能写代码，还能打开浏览器验证效果： + +```python +async for message in query( + prompt="修复首页的样式问题，然后打开浏览器截图确认效果", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Edit", "Bash"], + mcp_servers={ + "playwright": { + "command": "npx", + "args": ["@playwright/mcp@latest"] + } + }, + ), +): + print(message) +``` + +### 场景速查表 + +| 场景 | 核心工具 | 难度 | +|------|---------|------| +| 自动修 Bug | Read, Edit, Bash, Grep | 入门 | +| 代码审查 | Read, Glob, Grep | 入门 | +| CI/CD 自动修复 | Read, Edit, Bash | 中级 | +| 技术调研报告 | WebSearch, WebFetch, Write | 入门 | +| 浏览器自动化 | MCP (Playwright) | 中级 | +| 多 Agent 协作 | Task + AgentDefinition | 高级 | +| 数据库操作 | MCP (PostgreSQL/MySQL) | 中级 | +| 邮件/通知助手 | MCP (Slack/Email) | 中级 | + +--- + +## 什么时候该用 Agent SDK？ + +不是所有场景都需要 Agent SDK。选对工具很重要： + +| 你想做的事 | 该用什么 | +|-----------|---------| +| 简单对话、文本生成、翻译 | 基础 `anthropic` SDK | +| 单次 tool use（查天气、算数） | 基础 `anthropic` SDK | +| 自主完成多步骤开发任务 | Agent SDK | +| 嵌入 CI/CD 流水线 | Agent SDK | +| 构建能操作文件系统的应用 | Agent SDK | +| 日常交互式开发 | Claude Code CLI | +| 一次性快速任务 | Claude Code CLI | + +简单来说：如果你的任务需要 Claude "自己动手干活"（读文件、改代码、跑命令），用 Agent SDK。如果只是"问答"，用基础 SDK 就够了。 + +--- + +## 企业级实战：构建代码质量守护流水线 + +前面的场景都是单个 agent 做单件事。但在真实的企业环境中，你需要的是一条完整的流水线——多个 agent 串联协作，每个环节有明确的输入输出，有审计、有回滚、有通知。 + +下面我们构建一个真实场景：**每次 PR 提交后，自动触发代码审查 → 安全扫描 → 自动修复 → 测试验证 → 生成报告**的完整流水线。 + +### 架构设计 + +``` +PR 提交 + │ + ▼ +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ 代码审查 │───▶│ 安全扫描 │───▶│ 自动修复 │ +│ Agent │ │ Agent │ │ Agent │ +│ (只读) │ │ (只读) │ │ (可写) │ +└─────────────┘ └─────────────┘ └─────────────┘ + │ + ▼ + ┌─────────────┐ ┌─────────────┐ + │ 测试验证 │───▶│ 报告生成 │ + │ Agent │ │ Agent │ + │ (Bash) │ │ (Write) │ + └─────────────┘ └─────────────┘ + │ + ▼ + Slack 通知 +``` + +核心思想：**每个 agent 只做一件事，权限最小化，结果串联传递**。 + +### 第一步：定义流水线框架 + +```python +import asyncio +import json +from datetime import datetime +from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher + +# 审计日志：记录每个 agent 的每一步操作 +audit_log = [] + +async def audit_hook(input_data, tool_use_id, context): + audit_log.append({ + "time": datetime.now().isoformat(), + "tool": input_data.get("tool_name"), + "input": input_data.get("tool_input", {}), + }) + return {} + +# 通用 hook 配置：所有 agent 共享审计能力 +audit_hooks = { + "PostToolUse": [HookMatcher(matcher=".*", hooks=[audit_hook])] +} +``` + +### 第二步：代码审查 Agent（只读） + +```python +async def run_code_review(pr_diff: str) -> str: + """只读 agent，审查代码质量，输出结构化报告""" + result_text = "" + async for message in query( + prompt=f"""审查以下 PR diff，从这几个维度分析： +1. 代码规范：命名、格式、注释 +2. 逻辑问题：边界条件、空指针、竞态 +3. 性能隐患：N+1 查询、内存泄漏、不必要的循环 +4. 可维护性：函数过长、职责不清、魔法数字 + +PR Diff: +{pr_diff} + +输出 JSON 格式：{{"issues": [{{"severity": "high/medium/low", "file": "...", "line": ..., "description": "..."}}], "summary": "..."}}""", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Glob", "Grep"], + permission_mode="bypassPermissions", + hooks=audit_hooks, + max_turns=10, + ), + ): + if hasattr(message, "result"): + result_text = message.result + return result_text +``` + +### 第三步：安全扫描 Agent（只读） + +```python +async def run_security_scan() -> str: + """只读 agent，专注安全漏洞扫描""" + result_text = "" + async for message in query( + prompt="""扫描项目代码中的安全漏洞： +1. SQL 注入、XSS、CSRF +2. 硬编码的密钥或凭证 +3. 不安全的依赖版本 +4. 权限校验缺失 + +输出 JSON：{{"vulnerabilities": [{{"severity": "critical/high/medium", "type": "...", "file": "...", "description": "...", "fix_suggestion": "..."}}]}}""", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Glob", "Grep", "Bash"], + permission_mode="bypassPermissions", + hooks=audit_hooks, + max_turns=15, + ), + ): + if hasattr(message, "result"): + result_text = message.result + return result_text +``` + +### 第四步：自动修复 Agent（可写） + +```python +async def run_auto_fix(review_result: str, security_result: str) -> str: + """可写 agent，根据审查和扫描结果自动修复代码""" + result_text = "" + async for message in query( + prompt=f"""根据以下审查结果修复代码： + +代码审查报告： +{review_result} + +安全扫描报告： +{security_result} + +修复规则： +1. 只修复 severity 为 high 或 critical 的问题 +2. 每次修改后运行相关测试确认没有破坏现有功能 +3. 不要重构无关代码，只做最小修复 +4. 修复完成后输出修改文件列表""", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Edit", "Bash", "Glob", "Grep"], + permission_mode="acceptEdits", + hooks=audit_hooks, + max_turns=30, + ), + ): + if hasattr(message, "result"): + result_text = message.result + return result_text +``` + +### 第五步：测试验证 + 报告生成 + +```python +async def run_test_and_report(fix_result: str) -> str: + """运行测试，生成最终报告""" + result_text = "" + async for message in query( + prompt=f"""执行以下操作： +1. 运行完整测试套件（npm test 或 pytest） +2. 统计测试通过率 +3. 生成 Markdown 格式的质量报告到 pr-report.md，包含： + - 代码审查发现的问题数量和严重程度分布 + - 安全漏洞数量 + - 自动修复的内容：{fix_result} + - 测试通过率 + - 最终结论：是否建议合并""", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Bash", "Write", "Glob"], + hooks=audit_hooks, + max_turns=15, + ), + ): + if hasattr(message, "result"): + result_text = message.result + return result_text +``` + +### 第六步：串联整条流水线 + +```python +import subprocess + +async def run_pipeline(): + """完整的 PR 质量守护流水线""" + print("🔍 阶段 1/4：代码审查...") + pr_diff = subprocess.run( + ["git", "diff", "main...HEAD"], capture_output=True, text=True + ).stdout + review_result = await run_code_review(pr_diff) + + print("🛡️ 阶段 2/4：安全扫描...") + security_result = await run_security_scan() + + print("🔧 阶段 3/4：自动修复...") + fix_result = await run_auto_fix(review_result, security_result) + + print("✅ 阶段 4/4：测试验证 + 生成报告...") + report = await run_test_and_report(fix_result) + + # 保存审计日志 + with open("audit-log.json", "w") as f: + json.dump(audit_log, f, indent=2, ensure_ascii=False) + + print(f"流水线完成，审计日志已保存（共 {len(audit_log)} 条操作记录）") + return report + +asyncio.run(run_pipeline()) +``` + +### 企业级设计思考 + +这条流水线体现了几个关键的企业级设计原则： + +**权限最小化**：代码审查和安全扫描 agent 只有只读权限，不可能误改代码。只有自动修复 agent 才有写权限，而且限定了 `acceptEdits` 模式。 + +**可审计**：每个 agent 的每一步操作都通过 Hook 记录到审计日志。出了问题可以回溯是哪个 agent 在什么时间做了什么操作。 + +**结果串联**：上一个 agent 的输出是下一个 agent 的输入。代码审查的结果喂给自动修复，自动修复的结果喂给测试验证。每个环节都有明确的输入输出契约。 + +**成本可控**：每个 agent 都设置了 `max_turns` 限制，防止某个环节失控空转。生产环境中还可以加上 `max_budget_usd` 做预算控制。 + +**可扩展**：想加新环节？比如加一个"文档检查 agent"或"性能基准测试 agent"，只需要写一个新函数，插入流水线即可。 + +这个模式可以直接嵌入 GitHub Actions 或 GitLab CI，每次 PR 自动触发，真正实现"AI 驱动的代码质量守护"。 + +--- + +## 错误处理 + +Agent SDK 提供了清晰的异常类型，方便你在生产环境中做好容错： + +```python +from claude_agent_sdk import query, CLINotFoundError, ProcessError + +try: + async for msg in query(prompt="分析代码"): + print(msg) +except CLINotFoundError: + print("Claude Code CLI 未安装，请先安装") +except ProcessError as e: + print(f"进程异常退出，退出码: {e.exit_code}") +``` + +--- + +## 总结 + +Claude Agent SDK 的核心价值是把"模型推理"升级为"可控执行"。它不只是生成文本，而是能在一个可审计、可约束的工具系统中真正完成任务。 + +记住 Anthropic 官方博客中的一句话：Agent SDK 的设计哲学是"给 agent 一台电脑，让它像人一样工作"。 + +好的 agent 应用 = 清晰的工具设计 + 明确的任务边界 + 适当的人工监督。工具给了 agent 能力，边界给了它约束，监督给了你信心。三者缺一不可。 + +--- + +## 参考资料 + +### 官方资源 + +- [Agent SDK 官方文档](https://platform.claude.com/docs/en/agent-sdk/overview) - 最权威的参考 +- [GitHub - claude-agent-sdk-python](https://github.com/anthropics/claude-code-sdk-python) - Python SDK 源码 +- [GitHub - claude-agent-sdk-typescript](https://github.com/anthropics/claude-agent-sdk-typescript) - TypeScript SDK 源码 +- [示例 Agent 项目](https://github.com/anthropics/claude-agent-sdk-demos) - 邮件助手、研究 agent 等 + +### 博客与教程 + +- [Building agents with the Claude Agent SDK](https://claude.com/blog/building-agents-with-the-claude-agent-sdk) - Anthropic 官方工程博客，讲解设计哲学和架构 +- [Claude Agent SDK Python 学习指南](https://redreamality.com/blog/claude-agent-sdk-python-) - 中文友好，从零开始的完整教程 +- [Claude Agent SDK 完整教程](https://blog.wenhaofree.com/en/posts/articles/claude-agent-sdk-tutorial/) - 工具系统、Agent Loop、可控执行实战 +- [12 个 Agent SDK 实用场景](https://skywork.ai/blog/claude-agent-sdk-use-cases-2025/) - 覆盖编码、数据、自动化等 +- [Step-by-Step Agent 教程](https://skywork.ai/blog/how-to-use-claude-agent-sdk-step-by-step-ai-agent-tutorial/) - TypeScript + Python 双轨教程 diff --git a/docs/zh-cn/stage-3/core-skills/mobile-development/index.md b/docs/zh-cn/stage-3/core-skills/mobile-development/index.md new file mode 100644 index 0000000..ef0b8f8 --- /dev/null +++ b/docs/zh-cn/stage-3/core-skills/mobile-development/index.md @@ -0,0 +1,904 @@ +# Claude Code 手机远程开发 + +## 引言 + +想象一下这些场景：你在通勤的地铁上突然想到一个绝妙的 bug 修复方案；你在咖啡厅排队时收到线上故障的紧急通知；你在陪女朋友逛街时想看看 AI 构建的项目进展如何。 + +传统开发模式下，这些场景意味着你需要找个地方打开电脑，或者无奈地把事情推迟。但在 AI 辅助编程时代，规则变了。Claude Code 的出现让我们可以把开发环境装进口袋，随时随地保持生产力。 + +2025 年夏天，随着 Claude Code 的普及，开发者们开始探索各种"手机编程"方案。从简单的 Termux 本地运行，到复杂的 SSH + Tailscale 远程连接，再到专门的 Happy Coder 应用，一个完整的移动开发生态逐渐形成。 + +本章要解决的核心问题是：如何让 Claude Code 跟随你的手机，成为真正的"口袋开发助手"。 + +--- + +## 核心原理：手机开发的架构模式 + +在介绍各种方案之前，先理解问题的本质。 + +### 为什么手机开发是个问题？ + +传统的 IDE（如 VS Code、IntelliJ）需要完整的操作系统环境、强大的 CPU、大量内存和存储空间。手机虽然性能越来越强，但在开发体验上仍有天然限制： + +**输入限制**：虚拟键盘输入代码效率低，复杂语法容易出错 + +**屏幕限制**：小屏幕难以同时查看代码、终端和浏览器 + +**环境限制**：手机无法运行完整的开发工具链（编译器、数据库、调试器） + +**连接限制**：移动网络不稳定，SSH 连接容易断开 + +### 核心思想：瘦客户端架构 + +所有手机开发方案的核心思想都是：手机只是"控制台"，真正的开发工作在别处完成。 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ │ +│ ┌─────────────┐ ┌─────────────┐ │ +│ │ 手机 │ │ 主机/云端 │ │ +│ │ (控制端) │ ────────► │ (执行端) │ │ +│ │ │ 指令/结果 │ │ │ +│ │ • 输入指令 │ │ • 运行 CLI │ │ +│ │ • 查看输出 │ │ • 执行代码 │ │ +│ │ • 审查更改 │ │ • 访问文件 │ │ +│ └─────────────┘ └─────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +这种架构让手机只需要负责"人机交互"，把繁重的计算工作交给主机或云端。 + +--- + +## 方案一：iOS 官方 App + +2025 年 10 月，Anthropic 正式在 iOS App 中推出了 Claude Code 移动版，这是最简单的手机开发方案。 + +### 地区限制 + +⚠️ **重要提示**：Claude App 在中国大陆地区**无法直接使用**。 + +如果你在中国大陆，推荐直接使用 **Happy Coder**（方案二），它可以通过配置国内 API 中转服务正常工作。 + +如果你有海外 Apple ID，可以通过切换地区下载 Claude App。 + +### 工作原理 + +``` +┌─────────────┐ ┌─────────────────┐ +│ iOS App │ ──────────────────► │ Anthropic 云端 │ +│ (手机) │ HTTPS + OAuth │ Claude Code │ +└─────────────┘ └────────┬────────┘ + │ + ▼ + ┌───────────────┐ + │ GitHub API │ + └───────────────┘ +``` + +你的手机 App 只是发送指令，所有代码执行都在 Anthropic 的云端沙盒中进行，结果通过 GitHub 同步。 + +### 基本使用 + +**前提条件**： + +- iPhone iOS 15 或更高版本 +- Claude Pro/Team/Enterprise 订阅（免费版不支持） +- GitHub 账号 + +**使用步骤**： + +1. 从 App Store 下载 Claude App +2. 登录你的 Anthropic 账号 +3. 在 App 中找到"Code"标签页 +4. 通过 OAuth 连接你的 GitHub 仓库 +5. 开始创建任务 + +### 优缺点 + +优点是配置零门槛、体验流畅、有推送通知。缺点是只支持 iOS、主要支持 GitHub、功能相对受限（不能访问本地文件系统）、中国大陆无法使用。 + +--- + +## 方案二：Happy Coder + +Happy Coder 是一个为 Claude Code 和 Codex 设计的开源移动和 Web 客户端，支持端到端加密，可以从任何地方控制你的 AI 编程助手。 + +### 工作原理 + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ Happy App │ ────────► │ Happy Server │ ◄──────── │happy-coder │ +│ (手机/Web) │ 加密WebSocket│ (中继服务器) │ WebSocket │ (电脑CLI) │ +└─────────────┘ └─────────────┘ └──────┬──────┘ + │ + ▼ + ┌─────────────┐ + │Claude Code │ + │ CLI │ + └─────────────┘ +``` + +在电脑上运行 `happy` 代替 `claude` 启动 AI 编程助手。当需要在手机上控制时，会话会自动切换到远程模式。电脑上按任意键即可切回本地控制。 + +### 安装和使用 + +**步骤 1：下载 App** + +| 平台 | 链接 | +|------|------| +| iOS | [App Store](https://apps.apple.com/us/app/happy-claude-code-client/id6748571505) | +| Android | [Google Play](https://play.google.com/store/apps/details?id=com.ex3ndr.happy) | +| Web | [app.happy.engineering](https://app.happy.engineering) | + +**步骤 2：电脑安装 CLI** + +```bash +npm install -g happy-coder +``` + +**步骤 3：启动并配对** + +```bash +# 在项目目录中运行 +cd ~/my-project +happy + +# 会显示配对二维码 +``` + +**步骤 4：手机扫码配对** + +打开 Happy App，扫描电脑上显示的二维码。配对成功后即可在手机上控制 Claude Code。 + +**步骤 5：使用** + +```bash +# 启动 Claude Code +happy + +# 或启动 Codex +happy codex +``` + +### 资源链接 + +- [GitHub 项目](https://github.com/slopus/happy) - 源代码 +- [文档网站](https://happy.engineering/docs) - 使用文档 +- [Discord 社区](https://discord.gg/fX9WBAhyfD) - 社区讨论 + +### 优缺点 + +优点是配置简单、跨平台支持、端到端加密、开源可审计。缺点是需要依赖第三方中继服务器、手机应用需要自行验证可用性。 + +--- + +## 方案三：HAPI + +HAPI 是 Happy Coder 的替代方案，采用本地优先的设计理念，支持无缝切换设备和多种 AI 模型。 + +### 工作原理 + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ HAPI App │ ────────► │ HAPI Server │ ◄──────── │ hapi │ +│(手机/PWA/ │ WireGuard │ (自建中继) │ WireGuard │ (电脑CLI) │ +│ Telegram) │ + TLS │ │ + TLS │ │ +└─────────────┘ └─────────────┘ └──────┬──────┘ + │ + ▼ + ┌─────────────┐ + │Claude Code │ + │ / Codex / │ + │ Gemini等 │ + └─────────────┘ +``` + +HAPI 使用 WireGuard 配合 TLS 实现端到端加密，所有通信经过加密中继服务器。你可以自建中继服务器，完全掌控数据流。 + +### 核心特性 + +- **无缝切换**：在电脑和手机之间无缝切换控制，按任意键即可回到本地控制 +- **原生优先**：使用原生技术封装移动应用，提供流畅的交互体验 +- **AFK 审批**：离开电脑时，手机可以接收审批请求，无需中断工作流 +- **多模型支持**：支持 Claude Code、Codex、Gemini、OpenCode 等多种 AI 编程助手 +- **随时随地终端**：通过 PWA、Telegram Mini App 等多种方式访问 +- **语音控制**：支持语音输入指令，解放双手 + +### 安装和使用 + +**步骤 1：启动中继服务器** + +```bash +# 在你的服务器上运行（或使用 npx 直接启动） +npx @twsxtd/hapi hub --relay +``` + +**步骤 2：电脑安装 CLI** + +```bash +# 在项目目录中运行 +cd ~/my-project +npx @twsxtd/hapi + +# 或全局安装 +npm install -g @twsxtd/hapi +hapi +``` + +**步骤 3：配对设备** + +按照终端提示，在手机上打开 HAPI App 并扫描二维码完成配对。 + +**步骤 4：访问方式** + +| 访问方式 | 说明 | +|---------|------| +| Web PWA | 浏览器访问，支持安装到桌面 | +| Telegram Mini App | 在 Telegram 内直接使用 | +| 移动应用 | 原生应用体验（如已发布） | + +### 与 Happy Coder 的区别 + +| 特性 | Happy Coder | HAPI | +|------|-------------|------| +| 设计理念 | 云端优先 | 本地优先 | +| 加密方式 | WebSocket + E2E | WireGuard + TLS | +| 多模型支持 | Claude Code, Codex | Claude, Codex, Gemini, OpenCode | +| 访问方式 | iOS/Android/Web | PWA, Telegram, 更多 | +| 语音控制 | ❌ | ✅ 支持 | +| AFK 审批 | ❌ | ✅ 支持 | +| 自建中继 | ⚠️ 需手动部署 | ✅ 开箱即用 | + +### 资源链接 + +- [GitHub 项目](https://github.com/tiann/hapi) - 源代码 +- [PWA 使用文档](https://github.com/tiann/hapi/blob/main/docs/pwa.md) - PWA 安装和使用 +- [工作原理](https://github.com/tiann/hapi/blob/main/docs/how-it-works.md) - 技术实现细节 +- [语音助手](https://github.com/tiann/hapi/blob/main/docs/voice.md) - 语音控制功能 +- [为什么选择 HAPI](https://github.com/tiann/hapi/blob/main/docs/why-hapi.md) - 设计理念 +- [常见问题](https://github.com/tiann/hapi/blob/main/docs/faq.md) - FAQ + +### 优缺点 + +优点是本地优先设计、多模型支持、端到端加密、支持语音控制、可自建中继。缺点是项目相对较新、社区生态仍在发展中。 + +--- + +## 方案四：SSH + Tailscale + Tmux + +这是最适合专业开发者的方案，通过 SSH 远程连接到你的开发机器，配合 Tmux 保持会话持久化。 + +### 工作原理 + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ 手机 │ ────────► │ Tailscale │ ◄──────── │ 电脑 │ +│ (SSH客户端)│ VPN P2P │ 中继/打洞 │ VPN P2P │ (开发机) │ +└─────────────┘ └─────────────┘ └──────┬──────┘ + │ + ▼ + ┌─────────────┐ + │ Tmux │ + │ (会话保持) │ + └─────────────┘ +``` + +Tailscale 创建一个点对点 VPN 网络，让你在任何网络环境下都能直接访问家里的电脑。Tmux 确保即使 SSH 断开，Claude Code 仍在后台运行。 + +### 为什么需要 Tailscale？ + +**传统的 SSH 连接问题**： + +``` +手机 (4G) ──XX──> 路由器 NAT ──XX──> 家里电脑 + (无法穿透) (内网隔离) +``` + +你的电脑在内网，手机在外网无法直接访问。传统的解决方案是配置端口转发和动态 DNS，过程复杂且有安全风险。 + +**Tailscale 的解决方案**： + +``` +手机 (4G) ──► Tailscale 中继 ──◄── 家里电脑 + (自动打洞或中继) +``` + +Tailscale 使用 NAT 打洞技术，如果打洞失败会自动使用中继服务器，全程加密。 + +### 完整配置步骤 + +**步骤 1：在电脑上安装 Tailscale** + +```bash +# macOS +brew install --cask tailscale + +# 或下载安装包 +# https://tailscale.com/download +``` + +**步骤 2：登录并获取 IP** + +```bash +# 启动 Tailscale +sudo tailscale up + +# 查看 Tailscale IP +tailscale ip -4 +# 输出示例: 100.x.x.x +``` + +**步骤 3：在手机上安装 Tailscale** + +从 App Store 或 Google Play 下载 Tailscale，用同一账号登录。 + +**步骤 4：安装并配置 Tmux** + +```bash +# macOS +brew install tmux + +# 创建配置文件 ~/.tmux.conf +cat > ~/.tmux.conf << 'EOF' +# 启用鼠标支持 +set -g mouse on + +# 设置默认终端模式为 256 色 +set -g default-terminal "screen-256color" + +# 更改按键绑定为 Ctrl+A（可选） +unbind C-b +set -g prefix C-a + +# 简化的分割面板快捷键 +bind v split-window -h +bind h split-window +``` + +**步骤 5：创建持久化会话** + +```bash +# 创建名为 "claude" 的会话 +tmux new -s claude + +# 在这个会话中启动 Claude Code +cd ~/my-project +claude + +# 分离会话（不关闭） +# 按 Ctrl+B 然后按 D +``` + +**步骤 6：手机 SSH 客户端连接** + +推荐使用的 SSH 客户端： + +| 客户端 | 平台 | 特点 | +|--------|------|------| +| Blink Shell | iOS | 支持 MOSH，适合不稳定网络 | +| Termius | iOS/Android | 跨平台，界面美观 | +| a-Shell | iOS | 免费，轻量级 | + +连接配置： + +``` +Host: 100.x.x.x (你的 Tailscale IP) +Port: 22 +Username: 你的电脑用户名 +``` + +连接后附加到 Tmux 会话： + +```bash +tmux attach -t claude +``` + +### 进阶技巧 + +**防止电脑休眠**： + +```bash +# macOS +caffeinate -dimsu & + +# 或设置系统偏好 > 能源节能 > 防止自动休眠 +``` + +**使用 MOSH 应对不稳定网络**： + +MOSH (Mobile Shell) 是专门为移动网络优化的 SSH 替代品，支持网络切换无缝恢复。 + +```bash +# 在电脑上安装 +brew install mosh + +# 在手机上使用 MOSH 连接 +# Blink Shell 原生支持 MOSH +``` + +**一键连接脚本**： + +在 SSH 客户端中设置启动命令： + +```bash +tmux attach -t claude || tmux new -s claude +``` + +这样连接后会自动附加到现有会话，或创建新会话。 + +### 优缺点 + +优点是功能完整、体验与桌面一致、支持所有开发工具。缺点是配置相对复杂、需要电脑保持运行。 + +--- + +## 方案五：Termux 本地运行 + +如果你是 Android 用户，可以直接在手机上运行 Claude Code，无需连接外部设备。 + +### 工作原理 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ │ +│ ┌─────────────┐ │ +│ │ Termux │ │ +│ │ (Linux环境) │ │ +│ │ │ │ +│ │ • Node.js │ │ +│ │ • Claude │ │ +│ │ Code CLI │ │ +│ │ │ │ +│ │ • 项目文件 │ │ +│ │ • Git │ │ +│ └─────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌─────────────┐ │ +│ │Anthropic API│ │ +│ └─────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +Termux 是 Android 上的终端模拟器和 Linux 环境，你可以直接在上面安装 Node.js 和 Claude Code。 + +### 安装步骤 + +**重要**：从 [F-Droid](https://f-droid.org/) 下载 Termux，不要用 Google Play 版本（已过时）。 + +**步骤 1：安装基础工具** + +```bash +# 更新包管理器 +pkg update && pkg upgrade + +# 安装开发工具 +pkg install git nodejs python vim +``` + +**步骤 2：安装 Claude Code** + +```bash +npm install -g @anthropic-ai/claude-code +``` + +**步骤 3：配置环境** + +```bash +# 创建工作目录 +mkdir -p ~/projects +cd ~/projects + +# 初始化项目 +git clone https://github.com/your-repo.git +cd your-repo + +# 启动 Claude Code +claude +``` + +**步骤 4：配置外部键盘（推荐）** + +在 Termux 中： + +```bash +# 启用扩展键行 +# 长按屏幕 > More > Extra keys row + +# 配置快捷键 +# 在 ~/.termux/termux.properties 中添加 +extra-keys = [['ESC','/','-','HOME','UP','END','PGUP','~'], \ + ['TAB','CTRL','ALT','LEFT','DOWN','RIGHT','PGDN','|']] +``` + +### 性能考虑 + +| 任务类型 | Android 表现 | +|---------|-------------| +| Web 开发 (HTML/CSS/JS) | ✅ 优秀 | +| Python 脚本 | ✅ 优秀 | +| Node.js 应用 | ✅ 良好 | +| 运行测试套件 | ⚠️ 中等 | +| 编译大型项目 | ❌ 不推荐 | + +### 优缺点 + +优点是完全本地化、无需网络、完全掌控。缺点是手机性能有限、输入体验差、仅限 Android。 + +--- + +## 方案六：Claude Code UI + +Claude Code UI（又名 CloudCLI）是一个开源项目，为 Claude Code 提供 Web 界面，支持手机浏览器访问。 + +### 工作原理 + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ 手机浏览器 │ ────────► │ Web 服务器 │ ◄──────── │Claude Code │ +│ │ HTTP/HTTPS │ (localhost) │ 调用 │ CLI │ +└─────────────┘ └─────────────┘ └─────────────┘ +``` + +在电脑上运行 Web 服务器，手机通过浏览器访问。这需要内网穿透或局域网访问。 + +### 安装和使用 + +**步骤 1：安装** + +```bash +# 一键启动（推荐） +npx @siteboon/claude-code-ui + +# 或全局安装 +npm install -g @siteboon/claude-code-ui +claude-code-ui +``` + +**步骤 2：访问界面** + +服务器默认运行在 `http://localhost:3001` + +**步骤 3：手机访问** + +方法 A - 局域网访问（同一 WiFi）： + +```bash +# 启动时绑定所有接口 +claude-code-ui --host 0.0.0.0 + +# 手机访问 +http://电脑局域网IP:3001 +``` + +方法 B - 使用 ngrok 内网穿透： + +```bash +# 安装 ngrok +brew install ngrok + +# 启动隧道 +ngrok http 3001 + +# 手机访问 ngrok 提供的 URL +``` + +### 功能 + +- 响应式设计，支持移动端 +- 内置聊天界面 +- 文件浏览器 +- Git 操作界面 +- 会话管理 + +### 优缺点 + +优点是有图形界面、功能完整。缺点是需要内网穿透（除非局域网）、配置相对复杂。 + +--- + +## 方案七：云端开发环境 + +如果你没有常开的电脑，可以使用云端开发环境，Claude Code 运行在云服务器上。 + +### 工作原理 + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ 手机 │ ────────► │ 云端容器 │ ─────────► │Claude Code │ +│ (浏览器/App)│ HTTPS │ (DevBox) │ │ CLI │ +└─────────────┘ └─────────────┘ └─────────────┘ +``` + +云容器中预装了 Claude Code，你通过浏览器或手机 App 访问。 + +### 使用 Sealos DevBox + +**步骤 1：创建环境** + +访问 [Sealos DevBox](https://sealos.io/devbox)，选择 Claude Code 模板创建环境。 + +**步骤 2：启动开发环境** + +约 30-60 秒后环境就绪，你得到一个 Web 终端。 + +**步骤 3：配置 Claude API** + +```bash +export ANTHROPIC_API_KEY="your-api-key" +``` + +**步骤 4：连接 Happy App** + +```bash +# 安装 happy-coder（已预装） +npm install -g happy-coder + +# 生成配对二维码 +happy +``` + +手机扫码后即可使用。 + +### 云端方案对比 + +| 平台 | Claude Code | 移动优化 | 启动时间 | 定价 | +|------|------------|----------|----------|------| +| Sealos DevBox | ✅ 预装 | ✅ Happy | ~60秒 | 按量付费 | +| GitHub Codespaces | ⚠️ 手动 | ⚠️ 浏览器 | ~2-3分钟 | 免费额度+按小时 | +| Gitpod | ⚠️ 手动 | ⚠️ 浏览器 | ~1-2分钟 | 免费额度+按小时 | +| Replit | ❌ | ✅ 原生App | 即时 | 免费+订阅 | + +### 优缺点 + +优点是无需本地电脑、环境一致、可扩展。缺点是需要付费、依赖网络、代码在云端。 + +--- + +## 方案对比与选择 + +各种方案各有特点，适合不同场景。 + +### 对比表 + +| 方案 | 难度 | 需要内网穿透 | 费用 | 适用场景 | +|------|------|-------------|------|----------| +| iOS 官方 App | 简单 | ❌ | $20/月 | 快速查看、简单任务 | +| Happy Coder | 较简单 | ❌ | 免费 | 日常使用、便利性 | +| HAPI | 中等 | ❌ | 免费 | 多模型支持、本地优先 | +| SSH + Tailscale | 较复杂 | ❌ | 免费 | 专业开发、完整功能 | +| Termux | 中等 | ❌ | 免费 | Android 本地开发 | +| Claude Code UI | 中等 | ✅ 需要 | 免费 | 需要 Web 界面 | +| 云端 DevBox | 简单 | ❌ | 按量付费 | 无本地电脑 | + +### 选择指南 + +**如果你在中国大陆**：推荐使用 **Happy Coder**，可以通过配置国内 API 中转服务正常工作。 + +**如果你追求便利性**：Happy Coder 最省心，扫码即用。 + +**如果需要多模型支持**：HAPI 支持多种 AI 编程助手，适合需要在不同模型间切换的开发者。 + +**如果你有常开的电脑**：SSH + Tailscale 是最佳选择，体验最完整。 + +**如果你是 iPhone 用户（非大陆）**：官方 App 是最简单的入门方式。 + +**如果你只有 Android 手机**：Termux 可以让你完全在手机上开发。 + +**如果你没有电脑**：云端 DevBox 是理想选择。 + +--- + +## 安全性与隐私 + +手机开发涉及代码在网络上传输，需要特别注意安全。 + +### 中继服务器的风险 + +使用 Happy Coder、HAPI 等需要中继的服务时，考虑以下问题： + +``` +┌─────────────────────────────────────────────────────────────┐ +│ │ +│ 中继服务器能看到什么？ │ +│ │ +│ • 加密前的数据（如果端到端加密实现不当） │ +│ • 元数据（何时连接、连接多长时间） │ +│ • 你的 API Key（如果配置不当） │ +│ │ +│ 中继服务器能做什么？ │ +│ │ +│ • 记录你的代码内容 │ +│ • 窃取 API 密钥 │ +│ • 注入恶意命令 │ +│ • 把你的设备当作节点攻击其他人 │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 安全最佳实践 + +**1. 代码敏感度分级** + +``` +┌─────────────────────────────────────────────────────────────┐ +│ │ +│ 公开项目/学习代码 ──► 可以用任何方案 │ +│ │ +│ 私人项目 ──► 推荐 SSH+Tailscale 或 自建中继 │ +│ │ +│ 商业代码 ──► 只用 SSH+Tailscale，禁用所有第三方中继 │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +**2. 密钥管理** + +```bash +# ❌ 不要在代码中硬编码密钥 +const apiKey = "sk-ant-xxxxx" + +# ✅ 使用环境变量 +const apiKey = process.env.ANTHROPIC_API_KEY + +# ✅ 使用 .env 文件（加入 .gitignore） +ANTHROPIC_API_KEY=sk-ant-xxxxx +``` + +**3. 使用沙盒** + +Claude Code 支持沙盒模式，限制其访问范围： + +```bash +claude --sandbox /path/to/project +``` + +**4. 自建中继** + +如果你使用 Happy Coder，可以考虑自建中继服务器： + +```bash +# 克隆项目（包含服务器代码） +git clone https://github.com/slopus/happy.git +cd happy + +# 部署服务器代码到你的 VPS +# 具体步骤参考项目文档 +``` + +**5. 使用 Headscale** + +Headscale 是 Tailscale 的开源实现，可以自建中继服务器： + +```bash +# Docker 一键部署 +docker run -d \ + --name headscale \ + -v /srv/headscale:/etc/headscale \ + -p 3478:3478/udp \ + -p 8080:8080 \ + headscale/headscale:latest +``` + +--- + +## 常见问题 + +### 需要内网穿透吗？ + +大部分现代方案**不需要**内网穿透： + +| 方案 | 原理 | +|------|------| +| Happy Coder | 中继模式，双方主动连接服务器 | +| HAPI | 中继模式，WireGuard + TLS | +| Tailscale | NAT 打洞或中继 | +| iOS App | 云端执行 | +| Claude Code UI | 需要（被动入站） | + +### 为什么中继模式不需要穿透？ + +``` +主动出站（NAT允许）： +电脑 ──► 中继服务器 ✓ + +主动入站（NAT阻挡）： +外部 ──► 电脑 ✗ + +中继模式的巧妙之处： +双方都主动连接中继服务器，都不需要入站！ +``` + +### 手机开发会影响电池吗？ + +不同方案耗电不同： + +| 方案 | 耗电量 | 原因 | +|------|--------|------| +| SSH 终端 | 低 | 只是文本显示 | +| iOS App | 中 | 云端执行，手机只做控制 | +| Termux | 高 | 本地运行 CLI | +| 浏览器 | 中 | Web 界面渲染 | + +建议长时间使用时连接充电器。 + +### 网络断开会怎样？ + +| 方案 | 网络断开影响 | +|------|-------------| +| SSH + Tmux | Claude 继续运行，重连后可恢复 | +| Happy Coder | 自动重连 | +| HAPI | 自动重连 | +| iOS App | 云端继续，App 提示断开 | +| Termux | 会话中断 | + +### 能在手机上编译大型项目吗？ + +不推荐。手机 CPU 和内存有限，大型编译会导致： + +- 手机发烫 +- 电池快速消耗 +- 编译时间过长 + +建议将编译任务放到远程服务器或云端执行。 + +--- + +## 总结 + +Claude Code 手机开发的核心思想是：**手机只是控制端，真正的开发工作在别处完成**。 + +选择哪种方案取决于你的具体需求。 + +如果你在中国大陆，推荐 **Happy Coder**，配置国内 API 中转即可使用。 + +如果想要最省心的方案，用 **Happy Coder**。扫码即用，推送通知，设备切换流畅。 + +如果需要多模型支持或本地优先设计，用 **HAPI**。支持多种 AI 编程助手，可自建中继。 + +如果想要最完整的开发体验，用 **SSH + Tailscale**。配置稍复杂，但功能最全，体验与桌面一致。 + +如果是 iOS 用户（非大陆），**官方 App** 是最简单的入门方式。 + +如果是 Android 用户，**Termux** 让你完全在手机上开发。 + +如果没有常开的电脑，**云端 DevBox** 是理想选择。 + +无论哪种方案，都要注意安全性：敏感代码要慎用第三方中继，API 密钥要妥善管理，重要项目最好用自建中继。 + +--- + +## 参考资料 + +### 官方资源 + +- [Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code) - Claude Code 的完整官方文档 +- [Claude iOS App](https://apps.apple.com/app/claude/id6473753684) - 官方 iOS 应用 + +### 开源项目 + +- [slopus/happy](https://github.com/slopus/happy) (2.5k⭐) - Happy Coder 移动客户端 +- [tiann/hapi](https://github.com/tiann/hapi) - HAPI 本地优先的多模型 AI 编程助手 +- [siteboon/claudecodeui](https://github.com/siteboon/claudecodeui) - Claude Code UI (CloudCLI) +- [juanfont/headscale](https://github.com/juanfont/headscale) (19k⭐) - Tailscale 的开源实现 + +### 中文教程 + +- [随时随地大小编，手机也能配置Claude Code](https://m.blog.csdn.net/haa_y/article/details/151156494) - Termux 配置教程 +- [口袋里的 AI 实验室：永不掉线的 Claude Code 移动工作流](https://www.cnblogs.com/swizard/p/19308983) - Tmux + Docker 方案 +- [陪女朋友逛街时，我带上了 Claude Code](https://post.m.smzdm.com/p/a3r7d63d/) - Tailscale 远程连接 +- [手机就能写上线级App](https://m.toutiao.com/article/7611823834756301318/) - 移动开发实战案例 + +### 英文资源 + +- [The Definitive Guide to Using Claude Code on Your Phone | Sealos Blog](https://sealos.io/blog/claude-code-on-phone/) - 最全面的手机开发指南 +- [SSH + Tailscale + Termius Complete Guide](https://m.blog.csdn.net/Lvyizhuo/article/details/157692953) - 远程连接详细教程 + +### 工具下载 + +- [Tailscale](https://tailscale.com/download) - 点对点 VPN 工具 +- [Termux (F-Droid)](https://f-droid.org/en/packages/com.termux/) - Android 终端模拟器 +- [Blink Shell](https://blink.sh/) - iOS SSH 客户端（支持 MOSH） +- [Termius](https://termius.com/) - 跨平台 SSH 客户端 diff --git a/docs/zh-cn/stage-3/core-skills/spec-coding/index.md b/docs/zh-cn/stage-3/core-skills/spec-coding/index.md new file mode 100644 index 0000000..b164eb9 --- /dev/null +++ b/docs/zh-cn/stage-3/core-skills/spec-coding/index.md @@ -0,0 +1,613 @@ +# 从 Vibe Coding 到 Spec Coding：AI 编程的进化之路 + +> "Code is a lossy projection of intent." +> 代码是意图的有损投影。 +> —— Sean Grove, OpenAI, AI Engineer World's Fair 2025 + +## Spec Coding 的核心理念：万物皆 Markdown + +在深入 Spec Coding 之前，先理解 Claude Code 的底层哲学：**万物皆 Markdown**。 + +Claude Code 的设计哲学中，所有过程记载、信息传递、甚至与模型的对话，都可以是 Markdown： + +- **CLAUDE.md**：项目规范的 Markdown 文档 +- **.claude/rules/**：分层规范的 Markdown 文件集合 +- **specs/**：功能需求的 Markdown 描述 +- **对话历史**：Claude Code 的对话记录本身就是 Markdown 格式 +- **AGENTS.md**：Agent 行为规范的 Markdown 指令 + +这正是 Spec Coding 的内核：**规范本身就是代码**。当你用 Markdown 写下需求、设计、验收标准时，你已经在写"代码"了——AI 会读取这些 Markdown，然后生成真正的代码实现。 + +Josh Beckman 对 Grove 演讲的总结一针见血： + +> "Software engineering (and lawmaking and legal review) is specification repair." +> 软件工程（以及立法和法律审查）的本质是规范修复。 + +在 Claude Code 中，这个"规范修复"的过程就是：**修改 Markdown → AI 读取 Markdown → 生成/修改代码 → 验证结果**。整个过程都是 Markdown 驱动的。 + +--- + +## 1. Sean Grove 的 "The New Code"：一场改变思维的演讲 + +2025 年，OpenAI 研究员 **Sean Grove** 在 AI Engineer World's Fair 上发表了一场题为 **"The New Code"** 的演讲，震动了整个开发者社区。他提出了一个颠覆性的观点：**70 年来我们一直在写代码来解决问题，但代码只是意图的有损投影——规范才是真正的"新代码"**。 + +这场演讲催生了一种新的开发范式：**Spec Coding**（规范编程）——以规范文档而非代码作为开发的核心产物，让 AI 根据规范生成代码。 + +本文将从 Grove 的演讲出发，带你理解 Spec Coding 的核心思想，回顾 Vibe Coding 的局限，并结合 Claude Code 的实践，展示如何在真实开发中运用这种方法论。 + +::: info 📚 你将学到 + +1. 理解 Sean Grove "The New Code" 演讲的关键思想 +2. 掌握 Spec Coding 的核心理念和方法论 +3. 认识 Vibe Coding 的价值与天花板 +4. 学会在 Claude Code 中实践 Spec Coding 工作流 +5. 掌握从 Vibe Coding 到 Spec Coding 的渐进式过渡策略 + +::: + +--- + +## 1. Sean Grove 的 "The New Code"：一场改变思维的演讲 + +2025 年，OpenAI 研究员 Sean Grove 在 AI Engineer World's Fair 上发表了题为 **"The New Code"** 的演讲。这场演讲被广泛认为是 Spec Coding 运动的思想源头。 + +Grove 此前创办了 OneGraph（一个 GraphQL 开发工具公司，后被 Netlify 收购），目前在 OpenAI 从事 alignment reasoning 工作——帮助将高层意图转化为可执行的规范和评估标准。 + +### 1.1 核心论点：代码是意图的有损投影 + +Grove 演讲的核心概念可以用一句话概括： + +> **Code is a lossy projection of intent.** +> 代码是意图的有损投影。 + +什么意思？当你脑子里有一个想法，把它变成代码的过程中，大量的上下文信息会丢失——**为什么**要这样做、**权衡了哪些方案**、**考虑了什么约束**。最终的代码只保留了"怎么做"，却丢掉了"为什么这样做"。 + +这就像把一本书压缩成一条推文——信息量大幅缩减，原始意图被严重损耗。 + +### 1.2 编程的本质是沟通 + +Grove 提出了一个看似简单却深刻的观点： + +> "If you can communicate effectively, you can program." +> 如果你能有效沟通，你就能编程。 + +他认为，实际编码工作只占开发的 **10-20%**，剩下的 80% 是围绕需求和目标的**结构化沟通**——理解用户要什么、和团队对齐方案、定义验收标准、处理边界情况。 + +这意味着编程能力的核心不是掌握某种语言的语法，而是**把模糊的意图转化为精确描述的能力**。 + +### 1.3 写规范的人就是程序员 + +这是 Grove 最具颠覆性的观点： + +> "Whoever writes the spec — be it a PM, a lawmaker, an engineer, a marketer — is now the programmer." +> 无论是产品经理、律师、工程师还是市场人员，写规范的人就是程序员。 + +随着 AI 越来越擅长把规范转化为代码，**真正的编程工作**从"写代码"变成了"写规范"。谁能最精确地表达意图，谁就是最有价值的"程序员"。 + +### 1.4 规范拥有类似代码的工具链 + +Grove 指出，规范可以像代码一样拥有完整的工具链： + +> "Specs actually give us a very similar toolchain, but it's targeted at intentions rather than syntax." + +- **组合**：规范可以模块化组合，就像代码模块 +- **测试**：规范可以嵌入单元测试，验证行为是否符合预期 +- **Lint 检查**：可以检测规范中的模糊语言，就像代码 linter 检测语法问题 +- **一致性验证**：跨部门的规范可以做一致性检查，类似类型检查器 + +### 1.5 OpenAI Model Spec：活的证明 + +Grove 用 OpenAI 自己的 **Model Spec** 文档作为实证。 + +当 OpenAI 发现模型存在 sycophancy（过度迎合用户）问题时，他们没有重新训练模型，而是**修改了规范文档**。改动自动传播到整个系统，问题得到修正。 + +这证明了一个关键点：**规范本身可以作为"可执行代码"发挥作用**。修改规范就等于修改行为，不需要碰一行传统代码。 + +Josh Beckman 对 Grove 演讲的总结一针见血： + +> "Software engineering (and lawmaking and legal review) is specification repair." +> 软件工程（以及立法和法律审查）的本质是规范修复。 + +--- + +## 2. Spec Coding：规范即代码 + +### 2.1 什么是 Spec Coding + +Spec Coding（规范编程），也叫 Spec-Driven Development（SDD），是一种以**规范文档作为开发核心产物**的方法论。 + +核心思路：**先写清楚规范，再让 AI 根据规范生成代码。规范是 source of truth，代码只是规范的实现产物。** + +Robert C. Martin 在《Clean Code》中的经典论断在 AI 时代被重新激活： + +> "Specifying requirements so precisely that a machine can execute them is programming." +> 把需求描述得足够精确以至于机器能执行它——这就是编程。 + +### 2.2 Vibe Coding vs Spec Coding 对比 + +| 维度 | Vibe Coding | Spec Coding | +|------|------------|-------------| +| **方式** | 即兴 prompt，逐条迭代 | 先写完整规范，再生成代码 | +| **适用场景** | 原型、hackathon、探索 | 生产系统、团队协作、企业级 | +| **代码质量** | 快但脆弱 | 结构化、可测试、可审计 | +| **首次通过率** | 不稳定 | 目标 95%+ | +| **可复用性** | 一次性 prompt | 规范可跨项目复用 | +| **安全性** | 容易遗漏 | 从规范层面内建 | +| **文档** | 无或滞后 | 规范即文档，自维护 | +| **团队协作** | 依赖个人 prompt 技巧 | 共享规范，统一标准 | + +两者并非对立。Brad Jolicoeur 指出： + +> "Clever engineers will even use vibe coding as a first step to generate the initial draft of a specification." +> 聪明的工程师会用 Vibe Coding 作为第一步，生成规范的初始草稿。 + +### 2.3 Spec Coding 的三层规范结构 + +Red Hat 的工程师总结了一个实用的三层规范模型： + +**第一层：功能规范（What）** + +用自然语言描述期望结果，回答"做什么"： + +```markdown +## 用户认证功能 + +### 用户故事 +- 作为新用户，我希望能通过邮箱注册账号 +- 作为已注册用户，我希望能用邮箱和密码登录 +- 作为忘记密码的用户，我希望能通过邮件重置密码 + +### 验收标准 +- 注册时验证邮箱格式和密码强度 +- 登录失败 5 次后锁定账号 15 分钟 +- 密码重置链接 30 分钟内有效 +``` + +**第二层：语言无关规范（How - 架构层）** + +定义数据结构、架构模式、安全要求： + +```markdown +## 技术设计 + +### 数据模型 +- users 表：id, email, password_hash, created_at, locked_until +- sessions 表：id, user_id, token, expires_at + +### API 设计 +- POST /api/auth/register → 201 Created +- POST /api/auth/login → 200 OK + JWT +- POST /api/auth/reset-password → 202 Accepted + +### 安全要求 +- 密码使用 bcrypt 加密，cost factor ≥ 12 +- JWT 有效期 15 分钟，refresh token 7 天 +- 所有端点启用 rate limiting +``` + +**第三层：语言特定规范（How - 实现层）** + +版本要求、测试框架、文档标准： + +```markdown +## 实现约束 + +### 技术栈 +- Runtime: Node.js 20+ +- Framework: Express 5 +- ORM: Prisma +- Testing: Vitest + +### 代码规范 +- 使用 TypeScript strict mode +- 错误处理使用自定义 AppError 类 +- 所有 API 端点需要 JSDoc 注释 +``` + +--- + +## 3. 在 Claude Code 中实践 Spec Coding + +理解了理论，接下来看如何在 Claude Code 中落地。Claude Code 的设计哲学天然契合 Spec Coding——它的 `CLAUDE.md`、Rules 目录、`/plan` 命令，本质上都是在做"规范驱动"。 + +OpenAI 自己用 Codex 构建项目时，也采用了类似的方式：用 `AGENTS.md` 文件作为规范来引导 AI agent。他们的核心经验是——**当 agent 遇到困难时，把它当作信号：找出缺少什么（工具、护栏、文档），然后补充到仓库中**。这和 Spec Coding 的理念完全一致：规范是活的，需要持续演进。 + +Augment Code 的研究也印证了这一点：**可执行规范之所以保持准确，是因为 AI agent 直接从规范生成代码，形成了一个强制函数——过时的规范会产生坏掉的实现**。这意味着规范不会像传统文档那样腐烂。 + +### 3.1 第一步：用 CLAUDE.md 建立项目规范 + +`CLAUDE.md` 就是你项目的"活规范"。每次 Claude Code 启动时都会读取它，相当于给 AI 一份持久的项目说明书。 + +在前面的 [Claude Code 快速上手核心指南](../basics/) 中，我们学过如何创建 `CLAUDE.md`。在 Spec Coding 的语境下，它的角色更加重要——**它不只是配置文件，而是项目规范的入口**。 + +LogRocket 的工程师强调：**坚实的上下文对于 AI agent 至关重要，它能防止幻觉和低效**。没有规范的 AI agent 可能会对项目做出大范围的、不受控的修改。`CLAUDE.md` 就是提供这个"坚实上下文"的第一道防线。 + +```markdown +# 电商项目规范 + +## 项目定位 +面向中小商家的 SaaS 电商平台，支持多店铺、多支付渠道。 + +## 架构决策 +- 前后端分离，API-first 设计 +- 后端微服务架构，服务间通过消息队列通信 +- 数据库读写分离 + +## 核心约束 +- 所有金额使用整数（分）存储，避免浮点精度问题 +- 订单状态机严格遵循：待支付 → 已支付 → 已发货 → 已完成 +- 支付相关接口必须幂等 +``` + +Aviator 的团队总结了规范应该捕获的关键信息——这也是你写 `CLAUDE.md` 时应该覆盖的： + +- 输入/输出格式和数据类型 +- 业务规则和边界情况 +- 系统依赖和约束 +- 性能和扩展要求 +- 错误处理和安全需求 + +### 3.2 第二步：用 Rules 目录管理分层规范 + +当项目变大，单个 `CLAUDE.md` 不够用。这时候用 `.claude/rules/` 目录来组织分层规范。 + +这正是 Augment Code 所说的"可执行规范"理念：**规范不是静态文档，而是 AI agent 直接消费的活的指令**。当你把规范拆分到 Rules 目录中，每个规范文件只在相关文件被编辑时加载，既节省 token 又保证精准。 + +Tessl 的工程师发现，将需求分解为结构化文档——PRD 定义"做什么和为什么"，技术规范定义"怎么做"——能有效防止 AI 在长对话中"混淆累积"，显著提升输出一致性。 + +``` +.claude/rules/ +├── 00-architecture.md # 架构规范（全局） +├── 01-security.md # 安全规范（全局） +├── 10-api-design.md # API 设计规范 +├── 11-frontend-patterns.md # 前端模式规范 +├── 12-database.md # 数据库规范 +└── 20-testing.md # 测试规范 +``` + +每个规范文件可以通过 frontmatter 指定适用范围： + +```markdown +--- +globs: + - "src/api/**/*.ts" + - "src/services/**/*.ts" +--- + +# API 设计规范 + +## 路由设计 +- RESTful 风格，使用名词复数：/api/v1/orders +- 嵌套资源最多两层：/api/v1/users/123/orders + +## 响应格式 +- 成功：{ data, pagination? } +- 错误：{ error: { code, message, details? } } + +## 必须遵守 +- 所有写操作需要认证 +- 列表接口必须支持分页 +- 敏感操作记录审计日志 +``` + +这样，当 Claude Code 编辑 API 相关文件时，会自动加载这份规范，确保生成的代码符合标准。 + +### 3.3 第三步：用 /plan 实现 Specify → Plan → Tasks → Implement + +Spec Coding 的标准工作流是四阶段循环。GitHub Spec Kit 将其标准化为 Specify → Plan → Tasks → Implement，而 Claude Code 的 `/plan` 命令天然支持这个流程。 + +SpecThis 的团队强调了一个关键原则：**在 agent 运行之前定义边界——在代码变更之前就知道什么应该改变**。这正是 `/plan` 的价值所在。 + +**阶段一：Specify（定义规范）** + +先写清楚要做什么，不急着写代码： + +``` +/plan +我需要实现订单退款功能，规范如下： + +功能需求： +- 用户可以在发货前申请全额退款 +- 发货后 7 天内可以申请退货退款 +- 退款需要管理员审批 + +验收标准： +- 退款金额不能超过订单实付金额 +- 退款状态机：申请中 → 审批通过 → 退款中 → 已退款 +- 退款完成后恢复库存 +- 全程记录操作日志 +``` + +**阶段二：Plan（技术规划）** + +Claude 会基于你的规范生成技术方案： + +``` +📋 退款功能实施计划 + +1. 数据模型设计 + - 创建 refunds 表 + - 添加订单状态机的退款相关状态 + +2. API 设计 + - POST /api/orders/:id/refund - 申请退款 + - PUT /api/refunds/:id/approve - 审批退款 + - GET /api/refunds - 退款列表 + +3. 业务逻辑 + - 退款资格校验 + - 退款金额计算 + - 库存恢复逻辑 + +4. 集成 + - 对接支付渠道退款接口 + - 发送退款通知 +``` + +**阶段三：Tasks（任务拆解）** + +将计划拆分为可独立执行的小任务，每个任务有明确的完成标准。 + +**阶段四：Implement（逐步实现）** + +按任务逐个实现，每完成一个就验证一次。 + +### 3.4 实战案例：用 Spec Coding 构建用户通知系统 + +让我们通过一个完整的例子，对比 Vibe Coding 和 Spec Coding 的差异。Orchestrator.dev 的数据显示，2025 Stack Overflow 调查中 84% 的开发者使用或计划使用 AI 工具，但只有 22% 对结果满意，46% 认为准确性有问题。Spec Coding 正是解决这个满意度鸿沟的关键。 + +**Vibe Coding 方式：** + +``` +你：做一个通知功能 +AI：[直接开始写代码，生成了一个简单的通知列表] + +你：要支持已读未读 +AI：[修改代码，加了个 read 字段] + +你：还要支持不同类型的通知 +AI：[又改，加了 type 字段] + +你：要能推送到手机 +AI：[大改一通，之前的结构不太适配了...] +``` + +结果：改了 4 轮，架构被反复推翻，代码越来越乱。 + +**Spec Coding 方式：** + +先写规范文档 `specs/notification.md`： + +```markdown +# 用户通知系统规范 + +## 功能需求 +1. 支持站内通知、邮件通知、推送通知三种渠道 +2. 通知类型：系统公告、订单状态、促销活动、安全提醒 +3. 用户可以按渠道和类型配置通知偏好 +4. 支持已读/未读状态，支持批量标记已读 + +## 数据模型 +- notifications 表：id, user_id, type, channel, title, content, + is_read, created_at +- notification_preferences 表：user_id, type, channel, enabled + +## API 设计 +- GET /api/notifications?type=&is_read= - 获取通知列表（分页） +- PUT /api/notifications/:id/read - 标记已读 +- PUT /api/notifications/read-all - 全部标记已读 +- GET /api/notification-preferences - 获取偏好设置 +- PUT /api/notification-preferences - 更新偏好设置 + +## 验收标准 +- 未读通知数实时更新 +- 通知列表支持无限滚动 +- 推送通知延迟 < 3 秒 +- 偏好设置变更立即生效 +``` + +然后在 Claude Code 中： + +``` +@specs/notification.md +按照这份规范实现用户通知系统。 +先从数据模型开始，然后实现 API，最后做前端组件。 +每完成一个模块暂停一下，我确认后再继续。 +``` + +结果：一次到位，架构清晰，不需要反复推翻重来。 + +### 3.5 结合 Superpowers 强化 Spec Coding + +在前面的 [Superpowers 工程级开发](../superpowers/) 章节中，我们学过 Superpowers 的技能体系。Spec Coding 和 Superpowers 是天然的搭档： + +| Spec Coding 阶段 | 对应 Superpowers 技能 | +|------------------|---------------------| +| 定义规范 | `brainstorming` — 苏格拉底式提问澄清需求 | +| 技术规划 | `writing-plans` — 将规范拆解为小任务 | +| 逐步实现 | `test-driven-development` — TDD 红绿重构 | +| 质量验证 | `code-review` + `verification-before-completion` | + +**组合使用示例：** + +``` +@specs/notification.md +用 TDD 方式按照这份规范实现通知系统， +完成后帮我做代码审查 +``` + +这条指令同时触发了 Spec Coding 工作流和 Superpowers 的 TDD + Code Review 技能，形成完整的工程级开发流程。 + +### 3.6 规范的版本控制与持续演进 + +The Vibe Coding Substack 提出了一个重要观点：**Specs are now code**。既然规范是代码，就应该像代码一样管理： + +- **版本控制**：规范文件放在 Git 仓库中，和代码一起提交 +- **变更追踪**：每次修改规范都有 commit 记录，知道谁改了什么、为什么改 +- **Code Review**：规范的修改也需要 PR 审查，确保团队对齐 +- **CI 集成**：规范变更触发自动化测试，验证实现是否仍然符合规范 + +在 Claude Code 中，这意味着你的 `CLAUDE.md`、`.claude/rules/` 和 `specs/` 目录都应该纳入版本控制。Robomotion 的经验是：**规范和实现一起版本化，防止漂移，保持可审计性**。 + +OpenAI 的 Harness Engineering 实践也验证了这一点：他们的 `AGENTS.md` 文件本身就是由 Codex 编写的，并且随着项目演进持续更新。当 agent 遇到困难时，修复方案不是改代码，而是**让 Codex 自己更新规范**——形成规范的自我修复循环。 + +--- + +## 4. 混合策略：从 Vibe 到 Spec 的渐进式过渡 + +行业共识并非"抛弃 Vibe Coding"，而是**根据场景选择合适的方式**。 + +### 4.1 什么时候用 Vibe Coding + +- 验证一个想法是否可行（30 分钟内的原型） +- 探索不熟悉的技术或框架 +- Hackathon 或内部 demo +- 一次性脚本或工具 + +### 4.2 什么时候用 Spec Coding + +- 生产级功能开发 +- 多人协作的项目 +- 需要长期维护的代码 +- 涉及安全、支付、数据等敏感领域 +- API 设计和系统集成 + +### 4.3 推荐的渐进式工作流 + +**阶段一：Vibe 探索** + +用 Vibe Coding 快速验证想法，不写规范，不管代码质量： + +``` +做一个简单的通知弹窗，看看效果 +``` + +**阶段二：提炼规范** + +验证可行后，把探索中的发现整理成规范。你甚至可以让 AI 帮你： + +``` +基于我们刚才做的通知功能原型， +帮我整理一份正式的功能规范文档， +包括数据模型、API 设计和验收标准 +``` + +**阶段三：Spec 重建** + +基于规范，用 Spec Coding 方式重新实现生产级版本： + +``` +@specs/notification.md +按照这份规范从零实现，不要参考之前的原型代码 +``` + +这个流程的好处是：**用 Vibe Coding 的速度验证方向，用 Spec Coding 的质量交付产品**。 + +Robomotion 的总结很到位： + +> "The spec is the source of truth. The AI generated output is the draft implementation. Validation is not optional." +> 规范是唯一的真相来源。AI 生成的代码只是草稿实现。验证不是可选的。 + +--- + +## 5. 常见问题 + +### Q1：Spec Coding 会不会太慢了？ + +写规范确实需要前期投入。但 Greg Ceccarelli 的团队用 Spec Coding 方式，**3 个人在 4 周内交付了一个完整的 macOS 产品**——这在传统开发中几乎不可能。 + +前期写规范的时间，会在后期通过减少返工、减少 bug、减少沟通成本来回收。 + +### Q2：规范写多详细才够？ + +Robomotion 的建议是：**一份高质量的规范可以只有一页**。关键是回答 8 个问题： + +1. 我们在自动化什么？ +2. 输入是什么？ +3. 输出是什么？ +4. 约束条件是什么？ +5. 失败模式有哪些？ +6. 安全要求是什么？ +7. 性能要求是什么？ +8. 什么测试能证明它工作？ + +### Q3：AI 只做规范说的事，遗漏了"显而易见"的功能怎么办？ + +这确实是 Spec Coding 的一个局限。GitHub Spec Kit 的用户反馈：AI 会"exactly and only"做规范里写的事。 + +解决方法：在规范中加一个"非功能性需求"部分，列出通用期望（错误处理、日志、可访问性等）。或者在 `CLAUDE.md` 中设置全局规则。 + +### Q4：小项目也需要 Spec Coding 吗？ + +不需要。Spec Coding 适合： +- 生产级项目 +- 多人协作项目 +- 需要长期维护的项目 + +对于快速原型、一次性脚本、学习实验，Vibe Coding 更合适。 + +### Q5：怎么让团队接受 Spec Coding？ + +从一个小功能开始试点。让团队看到 Spec Coding 减少返工、提高首次通过率的效果。Stack Overflow 2025 调查显示，84% 的开发者使用或计划使用 AI 工具，但只有 22% 对结果满意——Spec Coding 正是提升满意度的关键。 + +--- + +## 6. 总结 + +从 Vibe Coding 到 Spec Coding，不是一次革命，而是一次进化。 + +Sean Grove 在 "The New Code" 中说得很清楚：**70 年来我们一直在写代码来解决问题，现在应该写规范来生成代码**。代码是意图的有损投影，而规范才能完整地捕获意图、上下文和约束。 + +对于使用 Claude Code 的开发者来说，这个转变其实已经在发生： + +- 你写的 `CLAUDE.md` 就是项目规范 +- 你配置的 Rules 目录就是分层规范 +- 你用 `/plan` 做的规划就是 Specify → Plan → Tasks 流程 +- 你结合 Superpowers 的 TDD 和 Code Review 就是完整的 Spec Coding 工作流 + +**关键要点：** + +- Vibe Coding 适合探索和原型，Spec Coding 适合生产和协作 +- 规范是 source of truth，代码是规范的实现产物 +- 写规范的能力 = 编程能力，沟通能力 > 语法能力 +- 从小处开始：先把 `CLAUDE.md` 写好，就已经迈出了 Spec Coding 的第一步 + +::: tip 💡 下一步 +在下一章节中，我们将学习如何使用 Claude Code 的 Agent Teams 功能，让多个 AI 实例像真正的开发团队一样协同工作。 +::: + +--- + +## 参考资料 + +### Sean Grove "The New Code" 演讲相关 + +- [Code is just a lossy projection of intent — The Decoder](https://the-decoder.com/code-is-just-a-lossy-projection-of-intent-according-to-openai-researcher-sean-grove/) +- [The End of Coding? How Specifications Are Becoming the New Source Code — Implicator](https://www.implicator.ai/the-end-of-coding-how-specifications-are-becoming-the-new-source-code/) +- [OpenAI: Intent, Not Code, Drives Future Software Development — AI Tech Suite](https://www.aitechsuite.com/ai-news/openai-intent-not-code-drives-future-software-development) +- [Note on The New Code — Josh Beckman](https://www.joshbeckman.org/notes/914234100) +- [The New Code 演讲完整文字稿](https://lawwu.github.io/transcripts/8rABwKRsec4.html) + +### Spec Coding 方法论 + +- [How spec-driven development improves AI coding quality — Red Hat](https://developers.redhat.com/articles/2025/10/22/how-spec-driven-development-improves-ai-coding-quality) +- [Spec-Driven Development with AI: Complete 2025 Guide — Dplooy](https://www.dplooy.com/blog/spec-driven-development-with-ai-complete-2025-guide) +- [Spec-Driven Development: Building Production-Ready Software with AI — Orchestrator.dev](https://orchestrator.dev/blog/2025-12-16-spec_driven_dev_article) +- [Agents Code but the Problem of Clear Specification Remains — Greg Ceccarelli](https://www.gregceccarelli.com/writing/beyond-code-centric) + +### Vibe Coding vs Spec Coding + +- [Vibe Coding vs Spec Driven — Cosmo Edge](https://cosmo-edge.com/vibe-coding-vs-spec-driven-ai-development/) +- [Master AI in Software Engineering: Vibe vs. Spec Coding — Brad Jolicoeur](https://bradjolicoeur.com/article/ai-software-engineering-vibe-spec-prompting) +- [From Vibe Coding to Spec-Driven Development — Tessl](https://tessl.io/blog/from-vibe-coding-to-spec-driven-development/) +- [Spec first approach for enterprise — Robomotion](https://robomotion.io/blog/spec-first-approach-the-way-to-adapt-vibe-coding-for-enterprise-work) + +### 工具与实践 + +- [GitHub Spec Kit vs Vibe Coding — Ossels](https://ossels.ai/github-spec-kit-spec-driven-development/) +- [A spec-first workflow for agentic AI — LogRocket](https://blog.logrocket.com/spec-first-workflow-agentic-ai/) +- [Specs Are Now Code — The Vibe Coding Substack](https://thevibecoding.substack.com/p/specs-are-now-code) +- [Harness Engineering — Martin Fowler](https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html) +- [Spec-Driven Development & AI Agents Explained — Augment Code](https://www.augmentcode.com/guides/spec-driven-development-ai-agents-explained) +- [Spec-Driven Development: The Key to Scalable AI Agents — Aviator](https://www.aviator.co/blog/spec-driven-development/) +