《AI Coding 完整实战指南》AI Native

核心理念：任何事情先问 AI 能不能做！

从立项到上线运营的全流程实战手册 | 基于 100+ 真实项目经验

作者：Chico Gong

当 AI 能解决大部分执行工作时，核心竞争力在决策与验收。用 AI 做构建时，宜先让 AI 生成总览与选项，由人做决策；给 AI 的描述不必过细，避免让 AI 直接陷入细节。本指南以真实独立站等项目为例，把「AI Native」思维贯穿立项、开发、部署、运营全链路；拒绝空谈，只讲落地，帮助建立「遇事先问 AI」的习惯。

🎯 实战复盘：如何让 AI 独立完成 90% 的商业级独立站开发

核心主题：当 AI 解决 90% 执行工作时，核心竞争力何在？

直接拆解一个真实上线的独立站全案：从 AI 竞品调研到一键部署，打通研发全链路，从执行者进化为决策者。

TTS Studio 独立站案例

在线体验：https://web.realtime-ai.chat/app2.0/tts-studio/index.html

这是一个完全由 AI 辅助开发的商业级 TTS（文字转语音）工具独立站，展示了 AI Native 开发的完整流程：

核心亮点：

• 🤖 自动化调研：用 AI/Browser Agent 做竞品与市场调研，自动汇总现有 TTS 工具特性与差距
• 🎨 AI 生成 UI：从需求描述到完整界面实现
• ⚡ AI 功能开发：多引擎集成、批量处理、实时预览
• 🚀 一键部署：Vercel 自动化部署管道
• 📊 后端架构：生产级 TTS 系统（FlowTTS + vLLM 双引擎）

开发效率对比：

• ❌ 传统方式：需要 1-3 个月（需求调研 1 周 + UI 设计 1-2 周 + 前端开发 2-4 周 + 后端开发 3-6 周 + 测试联调 1-2 周）
• ✅ AI Native：约 3 周完成（AI 竞品调研 2 天 + AI 辅助 UI/前端开发 1 周 + 后端集成 1 周 + 资源协调与优化 3-5 天）

AI 参与度：

• 🤖 AI 负责约 90%：代码生成、UI 实现、功能开发、测试脚本
• 👨‍💻 人工负责约 10%：资源协调工作
  • 域名申请与备案
  • 日志系统创建
  • COS 桶配置、全球加速、CDN 部署
  • 大模型资源申请与配置
  • 腾讯云等云资源协调

📖 文档导航总览

(图：AI Coding 完整指南 - 从开发范式到运营维护的完整知识体系)

🎯 AI-First 核心理念

什么是 AI-First 开发？

传统开发思维：

遇到问题 → 查文档 → 搜 Stack Overflow → 手写代码 → 调试

AI-First 思维：

遇到问题 → 问 AI 能不能做 → AI 先生成总览/选项 → 人做决策 → AI 细化执行 → 人工验收

给 AI 的任务宜先要「总览与选项」，再由人拍板，有些情况下描述不必一次写得很细。

AI-First 适用范围

✅ 能用 AI 做的事情（90%+）：

• 命名（项目/变量/函数）
• 需求调研（DeepResearch）
• 代码生成（Claude Code/Cursor）
• 代码审查（多 AI 交叉 review）
• 冲突解决（AI 自动合并）
• 文档生成（README/API 文档）
• 测试用例生成
• 部署脚本生成
• 视频剪辑（AI 视频编辑）
• 视频转录（Gemini 3）
• 情感分析（nanobanana）
• 自动化录屏
• Chrome 自动化调试

⚠️ 需要人工介入的事情（<10%）：

• 核心架构决策（AI 辅助，人类决策）
• 敏感信息处理（人类审查）
• 最终上线审批（人类确认）

📖 目录

• 第一章：AI Coding 时代的开发范式转变与实战展示
  • 1.3 实战展示与指南基础
  • 1.4 AI 案例分享 - 真实场景中的 AI 应用
• 第二章：立项 - 从想法到仓库的第一步
• 第三章：开发 - AI 驱动的编码实践
  • 3.5 工程化 - 构建可维护的 AI 项目
  • 3.6 协作 - 多 Agent 并行与 AI 时代的 Git
• 第四章：测试与部署
• 第五章：运营 - 持续迭代与用户增长
• 附录 A：工具与 Prompt 速查 · 附录 B：故障排查

第一章：AI Coding 时代的开发范式转变与实战展示

图1.1：AI Coding 工具生态全景图

图1.2：AI Coding 工作流程图

官方 Agentic 循环概括为「gather context → take action → verify results」；下图为其在 Claude Code 中的细化：Prompt 提交、UserPromptSubmit Hook、MCP/Subagent、pre-commit/post-commit 等。

图1.3：开发效率对比（传统 vs AI 辅助）

1.1 传统开发 vs AI 辅助开发

核心理念转变：从 "How to code" 转向 "What to build"。

思维模式对比

核心差异：开发效率（如 realtime-ai 从预估 3-4 周压到 7-10 天）、代码质量（AI 生成更一致、错误处理更完善）、学习曲线（新技术栈上手时间大幅缩短）、心流（减少上下文切换与查文档）。效率与成本：编码实现占比从 50% 降到 ~10%，决策/审核升到 30%+ 成为核心竞争力；竞品分析等可从 1 周压到 1 小时（DeepResearch）。AI 悖论：试错成本极低会让人变忙，需专注有意义的事、把算力用在核心价值上。

时间分配变化

实战提效案例

学习成本下降不限于开发：设计、运营、写作、调研、运维等同样可以「需求驱动 + AI 解释 + 边做边学」，不必先系统啃完文档再动手。学习方式要转变：从「先系统学再实践」变为「先问 AI 再动手验证、在验证中补概念」。例如从零学 TRTC SDK 并集成：传统往往是阅读文档 2–3 天 + 实验 3–5 天；AI 辅助下可先让 AI 讲清关键概念与调用顺序，再直接做小 Demo，约 1 天理解 + 1–2 天出原型，在改 Bug 和扩展时顺带补文档。这种「用中学」在 AI 环境下更高效。

1.2 AI Coding 工具生态全景

代码编辑器集成：Claude Code（主推，CLI + MCP + Skills/Templates/Hooks，适合深度定制与多项目）、Cursor（VS Code fork、Composer、BugBot Agentic 调试）、GitHub Copilot（补全为主）、Windsurf 等；选型见下文对比表。

Cursor

• 特点：
  • VS Code fork，原生集成
  • Composer 多文件编辑
  • BugBot (Agentic Debug): 自动化的 Agent 调试系统，能自主推理、调用工具、动态获取上下文，而非死板的多轮检查 (参考: Building BugBot)。
  • 更直观的 UI 交互
• 适用场景：
  • 习惯 VS Code 用户
  • 重视 UI 交互体验
  • 需要 IDE 功能（调试、插件）
• 配置示例：.cursorrules 规则文件

GitHub Copilot

• 特点：
  • 代码补全为主
  • GitHub 深度集成
  • 支持多种编辑器
• 适用场景：
  • 轻量级代码补全
  • GitHub 重度用户
  • 已有固定开发流程

Windsurf

• 特点：
  • 新兴工具，AI Flow 模式
  • 多 AI 模型切换
• 适用场景：
  • 探索新工具的开发者

对比维度

工具太多、选择焦虑怎么办？ 当前 AI 编程工具很多（Claude Code、Cursor、Codex、Aider、Windsurf、Copilot 等，命令行形态也有多种），容易陷入比较和纠结。建议：多试几款，选适合自己的即可，不必求全。例如「类 Claude Code」的 CLI/Agent 就有多种，有的偏 MCP 生态、有的偏本地、有的偏云端，先挑一两个用熟再按需扩展；本指南以 Claude Code 为主示例，思路可迁移到 Cursor、CodeBuddy 等。关键是先动起来，在真实项目里用顺手再优化选型。

(图：AI 工具选择焦虑)

AI 模型选型

Claude Opus 4.5 / 4.5 Sonnet（主推）

• 优势：
  • 推理能力最强（Opus 4.5 领跑代码生成）
  • 代码生成质量高
  • 上下文窗口大（200K tokens）
  • 支持 MCP 协议
• 适用场景：
  • 复杂逻辑实现
  • 架构设计讨论
  • 需要深度理解代码
• 成本：API 调用按 token 计费
• 实际案例：realtime-ai 项目全程使用 Claude

(图：使用 AI 辅助构建的模型能力对比评测工具)

GPT-5.2

• 优势：
  • 通用性最强，知识面广 (Reasoning & Knowledge Work)
  • 插件生态丰富
  • 多模态支持（图片理解）
• 适用场景：
  • 复杂推理任务 (Thinking Model)
  • 需要广泛知识背景
  • 已有 OpenAI 生态积累
• 成本：相对较高

Gemini 3 (Pro/Flash)

• 优势：
  • 多模态能力强 (Gemini 3 Pro)
  • 免费额度大 (Flash)
  • Google 生态集成
• 适用场景：
  • 预算有限
  • 需要图片/视频处理
  • Google Cloud 用户
• 实际案例：开发了 10+ Gemini 应用（gemini-ai-english-tutor 等）

模型选择决策树

需要多模态?
  └─ 是 → Gemini 3
  └─ 否 → 需要最强推理?
            └─ 是 → Claude Opus 4.5
            └─ 否 → 预算紧张?
                      └─ 是 → Gemini 3 Flash
                      └─ 否 → GPT-5.2

国产大模型特别推荐 (China LLMs) (针对国内网络环境与中文语境的优选)

Kimi K2.5 (Moonshot AI)

• 特点：
  • 原生多模态：同时理解代码/文档/设计图/视频演示。
  • 超长思考 (Thinking Mode)：类似 o1 的深度推理能力，擅长复杂架构设计。
  • 20万字无损上下文：适合一次性喂入整个项目核心代码。
• 适用场景：读取长文档/遗留代码库、复杂逻辑推演

MiniMax-M2.1 (Abab 7)

• 特点：
  • 极致速度：专为 Coding/Agent 优化的高并发低延迟模型。
  • MoE 架构：在保持高智商的同时极大降低了推理成本。
• 适用场景：高频代码补全、自动化 Agent 任务流

GLM-4.7 (Zhipu AI)

• 特点：
  • 工具调用强者：针对 Function Call 和 Terminal 操作进行了专项微调。
  • GLM-Code：拥有更强的代码解释器能力。
• 适用场景：需要由 AI 操作终端/命令行的场景、数据分析

辅助工具链

MCP (Model Context Protocol)

• 作用：标准化 AI 工具与外部数据源的交互
• 典型应用：
  • 连接数据库查询
  • 集成 API 服务
  • 文件系统访问
• 实战案例：如何为项目配置 MCP Server；公司内部可参考 Knot MCP 平台、CodeBuddy Proxy 等
  • 🚀 公司内部最佳实践：
    • Knot MCP 平台：https://knot.woa.com/mcp/market (内部统一 MCP 市场)
    • CodeBuddy Proxy：https://git.woa.com/daweizheng/codebuddy_proxy (使用 CodeBuddy 额度调用 Claude，解决 Key 额度问题)
    • 智能巡检场景：通过组合 CLS 日志 MCP (获取报错堆栈) 与 智研 MCP (查询服务拓扑/监控)，实现 Agent 自动化的线上故障定位与巡检。

Community Resources (新增)

• AITMPL (aitmpl.com): Claude Code 专属的 Agent/Skill 模板库，包含 "BrainGrid", "Stack Builder" 等高级配置。

AI CLI 工具

• 命令行增强：
  • aichat：终端对话工具
  • sgpt：Shell GPT
  • mods：模块化 AI CLI
• 使用场景：
  • 快速查询命令
  • 脚本生成
  • 日志分析

浏览器扩展

• ChatGPT Sidebar
• Monica（AI 助手）
• 实际应用：开发 chrome-tts 扩展的经验

引用项目案例

• html-tools - 单文件 HTML 工具，纯前端无构建
• chrome-tts - Chrome TTS 浏览器扩展实战
• chrome-realtime-ai - Chrome 实时 AI 插件

Agentic 架构核心概念

随着 AI Coding 工具的进化，我们正在从简单的 "Chatbot"（问答模式）向 "Agentic"（代理模式）转变。理解这一架构对于掌握现代 AI 开发至关重要。

💡 核心架构理念： 清晰的职责分离是构建强大 Agent 系统的关键：

• Agent (决策者)：负责高层规划和决策 (Decision-making)
• Subagent (执行者)：负责具体的、隔离的任务执行 (Execution)
• Skill (工作流)：定义标准化的操作流程和 SOP (Workflow)
• MCP (连接器)：标准化的工具和数据接口 (Interface)
• Command (触发器)：用户意图的快捷入口 (Intent)

🍳 秒懂 Agent 架构：后厨的比喻

我们可以用一个专业后厨来类比这个复杂的系统：

1. Skills (菜谱)：就像Markdown 格式的菜谱。上面写着“什么时候做这道菜（触发时机）”和“具体步骤是什么”。它不是食材，只是文字说明。例如 brainstorming skill 是一份“头脑风暴指南”。
2. Agent (主厨)：就像行政总厨。他手里拿着菜谱（Skills），决定今天做什么菜，指挥大家干活。他负责决策、品控、协调，但通常不亲自切菜。
3. Subagents (临时帮厨)：就像按单结算的专业帮厨。要做 10 道复杂的菜，主厨会请 10 个临时帮厨，每个人只负责一道菜。做完这道菜他就走了，不会把上一道菜的味道（Context）带到下一道菜里，保证了上下文隔离。
4. Tools (厨具)：就像刀具、烤箱。是实际干活的工具（API、文件读写能力）。

图1.4：Agentic 架构分层图

Claude Code 的 CLAUDE.md、Skills、Templates 对应下图「知识层/规则」；MCP 对应「工具层」；Agent 系统对应「大脑层」与「执行层」。Hooks 在官方定义中为「循环外」的事件脚本（如 pre-commit/post-commit），不参与主推理链，图中未单独画出。

核心概念详解

1. Command (指令/触发器)

   • 定义：用户发起的意图触发器，通常以 / 开头（如 /test, /fix）。
   • 作用：将模糊的自然语言转化为明确的 Intent，并没有具体的执行逻辑，只是一个入口。

2. Agent (智能体/决策大脑)

   • 定义：主控 AI，拥有完整的上下文和决策能力。
   • 职责：Decision-making（决策）。它不一定亲自动手写每一行代码，而是负责“理解需求 -> 规划步骤 -> 指派任务”。
   • 类比：项目经理或技术主管。

3. Skill (技能/SOP)

   • 定义：封装好的、可复用的知识包或工作流。通常通过 .md 文件（如 SKILL.md）或 System Prompt 注入。
   • 职责：Workflow（工作流）。它告诉 Agent "如何专业地做某事"。例如 ui-ux-pro-max-skill 就是一个包含现代 UI 设计规范的知识包。
   • 特性：可插拔、可分享。

4. Subagent (子智能体/执行者)

   • 定义：由 Main Agent 唤起的、为了完成特定子任务而存在的临时智能体。通常运行在独立的上下文窗口中。
   • 职责：Execution（执行）。例如，Main Agent 决定需要调研 50 个文件，它会启动一个 "Research Subagent" 去读文件并写总结，完成后销毁，只把结果返回给主 Agent。这避免了污染主 Agent 的上下文。
   • 类比：外包专家或专项突击队。

5. MCP (Model Context Protocol)

   • 定义：Anthropic 提出的开放标准，像 "USB-C" 一样连接 AI 和所有外部数据。
   • 职责：Interface（接口）。让 Subagent 能统一地去读数据库、操作 GitHub、访问浏览器，而不需要为每个工具写特定的胶水代码。

🌟 核心概念三位一体 (The Trinity)

• Agent: 必须有自主判断力的专家 (Decision Maker)。
• Skill: 可复用的能力，可区分为指令型 (Command-based) 和知识型 (Knowledge-based)。
• MCP / Hook: 纯粹的工具 (Pure Tools)，负责连接与执行。

完整实战案例：Browser Automation Skill (来自 Factory.ai)

这是一个完美的 Skill (菜谱) + Tools (厨具) 结合的例子：

• Tools (厨具/JS 脚本)：
  • start.js: 启动 Chrome (开启调试端口)
  • nav.js: 控制页面跳转
  • eval.js: 执行 JS 抓取数据
  • pick.js: 交互式选择元素
• Skill (菜谱/SKILL.md)：
  • 定义标准流程：1. 启动浏览器 -> 2. 打开目标网页 -> 3. 提取 DOM -> 4. 截图存证。
  • Agent (主厨) 读取这份 SKILL.md，不再需要知道底层 Puppeteer 代码怎么写，只需要按步骤调用上述脚本即可完成复杂的网页自动化任务。

图1.5：典型 Agentic 工作流示例

场景：用户输入 /design 优化页面 UI

企业级 Claude Code 配置

Reference: github.com/chicogong/claude-code-config 这是一个标准化的 Claude Code 配置仓库示例，展示了如何组织 Agentic 资源。

1. 推荐目录结构 一个成熟的 Agentic 配置库应该包含以下层级：

2. 核心实践：Skills vs Commands

• Skills (技能/菜谱)：
  • 触发：自然语言 (AI 自动判断是否使用)。
  • 场景：复杂的、多步骤的业务流程。例如 "API 设计规范"，AI 会在设计 API 时自动参考。
• Commands (指令/工具)：
  • 触发：用户手动输入 / (如 /commit)。
  • 场景：明确的、原子化的动作。例如 "生成 Git Commit Message"。

3. 企业级安全 Hooks 示例 在配置库中引入 Hooks 可以极大提升安全性与体验：

• 🛡️ 危险命令拦截 (PreToolUse Hook)：
  • 自动拦截 rm -rf / 或删除核心配置文件的操作，需人工二次确认。
• 🔔 任务完成通知 (Notification Hook)：
  • 当 AI 执行耗时任务（如 Running Tests...）完成并等待用户输入时，自动发送系统通知 (如 macOS Notification)，避免用户在那傻等。

4. 配置分层策略

• Global (~/.claude/): 存放通用的 Agents (如 "Code Reviewer") 和作为兜底的 settings.json。
• Project (./.claude/): 存放项目特有的规则 (如 "本项目特有的 DB Schema Skill")，优先级高于全局。
• Local (./.claude/settings.local.json): 存放 API Keys 和个人特定的覆盖配置（永远不要提交到 Git）。

Skill 2.0 架构

随着 Skill 越来越复杂，单文件 SKILL.md 往往会遇到上下文超限和维护困难的问题。Skill 2.0 引入了文档架构的概念，通过模块化解决这些痛点。

1. 核心理念：文档架构 (Document Architecture)

告别单文件，像搭积木一样构建 Skill。

• 入口唯一：SKILL.md 是唯一强制文件，作为"目录"或"大脑"。
• 按需加载：Claude 仅在需要时通过链接读取子文件（渐进式披露），节省 Token。

2. 两种核心架构模式

(1) 知识库型 (Knowledge Base) 适用于 API 文档、设计规范等静态知识。

• 📁 my-skill/
  • 📄 SKILL.md (索引)
  • 📁 docs/ (存放 API.md, StyleGuide.md)

(2) 工作流型 (Workflow) 适用于周报、发布流程等多步骤任务。

• 📁 weekly-report/
  • 📄 SKILL.md (总指挥)
  • 📁 workflow/ (存放 step1.md, step2.md)
  • 📁 templates/ (存放 report-template.md)

3. 实战案例：AI 周报助手 (Workflow 模式)

一个能自动收集、整理、生成周报的 Skill。

目录结构：

weekly-report-ai/
├── SKILL.md              # 主控文件
├── workflow/
│   ├── step1-collect.md  # 收集信息
│   ├── step2-organize.md # 整理内容
│   └── step3-generate.md # 生成报告
├── templates/
│   └── report.md         # 周报模板
└── rules/
    └── writing.md        # 写作规范

关键文件内容示例：

SKILL.md (主控)

---
name: weekly-report-ai
description: 自动生成周报。触发词："写周报"。
---

# 🤖 AI 周报助手

请按顺序执行以下步骤：

| 步骤 | 说明     | 指引                                                     |
| ---- | -------- | -------------------------------------------------------- |
| 1️⃣   | 收集信息 | [workflow/step1-collect.md](workflow/step1-collect.md)   |
| 2️⃣   | 整理内容 | [workflow/step2-organize.md](workflow/step2-organize.md) |
| 3️⃣   | 生成周报 | [workflow/step3-generate.md](workflow/step3-generate.md) |

参考资料：

- 规范：[rules/writing.md](rules/writing.md)
- 模板：[templates/report.md](templates/report.md)

workflow/step1-collect.md (子步骤)

# 第一步：收集信息

向用户询问：

1. 本周完成了什么？
2. 遇到什么困难？
3. 下周计划？
   收集完整后，进入下一步。

4. 进阶技巧

• 配置分离：用 config/team-a.json 存储不同团队的偏好，在 SKILL.md 中引用。
• 禁止清单：创建 rules/dont-do.md (如：禁止编造数据、禁止使用 Emoji)，明确 AI 的行为边界。
• 质量自检：在 Workflow 最后增加 step4-review.md，让 AI 自查格式和语法后再输出。

5. 专家答疑与实战技巧 (FAQ)

• Q: Skill 不就是长一点的 Prompt 吗？
  • A: 不全是。虽然内容本质是 Prompt，但 Skill 的核心价值在于 文件架构 和 动态加载 (Dynamic Context)。Prompt 是一次性塞入，而 Skill 是按需挂载。没有 Skill 架构，你需要在每次对话前手动把巨大的 Prompt 贴进去，或者忍受上下文窗口爆炸。Skill 实现了"用时即取"，让 AI 的记忆更清晰。
• Q: Workflow 中涉及账号登录怎么办？（如自动化操作后台）
  • 方案 A (推荐)：MCP + Token。如果有 API，写一个专门的 MCP Server，在配置中通过环境变量注入 Token，让 AI 直接调用 API 操作。
  • 方案 B (模拟)：Browser Automation (CDP)。使用 Browser MCP 直接控制本地 Chrome (开启调试端口)，复用你本地浏览器的 Cookie/Session 登录态（类似 post-to-x skill），或者让 AI 像人一样去点击登录。

工程实践价值

"在这个时间点，理解 Claude Code 的工程实践是非常必要的。"

不仅仅是学会用一个工具，而是学习一种思维模式。

• Plugin as a Practice：写好一个 MCP Server 或 Claude Code 插件，本身就是理解 Agentic 架构最好的方式。当你试图把一个复杂的业务流程封装成一个 Skill 时，你自然而然就在实践 "Agent-Skill-Tools" 的分层思想。
• 保持信息压缩与高频更新：AI 领域变化极快，养成「高信噪比」的信息摄入习惯，并大量实践（如工作之外的 Hobby Project），是保持竞争力的关键。

官方推荐的高效工作流 (Official Best Practices)

• Plan Mode 先谋后动：
  • 在编写任何代码之前，先使用 Claude Code 的 Plan Mode (/plan 或明确指令) 探索整个 Codebase。这不仅安全（只读），还能让 AI 对项目有全局认知。
• Git Worktrees 并行开发：
  • Pro Tip: 对于多任务并行（如一边修 Bug 一边重构），不要来回切换 Context。使用 git worktree 开启多个并行的目录，每个目录运行一个独立的 Claude Code Session，互不干扰。
• Hooks for Determinism (拥抱确定性)：
  • 不要让 AI 猜测格式。使用 Hooks 强制运行 prettier, gofmt 等工具。AI 负责逻辑，工具负责格式，这是最完美的配合。

B-C-G 原则（下发任务）

如何让 AI 一次性输出满意的结果？关键在于 Prompt 的结构化。推荐使用 B-C-G 原则：

1. B - Background (背景)

   • 我是谁：告诉 AI 你的角色（如：前端专家、架构师）。
   • 上下文：当前项目的技术栈、业务背景。
   • 约束条件：什么能做，什么绝对不能做（如：不引入新库、必须兼容 IE11）。

2. C - Content (内容)

   • 任务主体：清晰、简单、明了地描述你要做什么。
   • 输入数据：提供必要的代码片段、错误日志或文档链接。
   • 原子化：尽量让一个任务只做一件事，不要把"重构数据库"和"修改前端 UI"混在一起说。

3. G - Goal (目标)

   • 输出格式：你想要 Markdown 列表、Mermaid 图表，还是直接可运行的代码？
   • 验收标准：什么样的结果是合格的（如：性能提升 20%、通过所有单元测试）。
   • 风格要求：代码风格（Google Style）、注释要求。

💡 Tip: 把复杂的任务拆解成多个 B-C-G 小任务，用 Agentic 的方式（Chain of Thought）去引导 AI，效果往往比一个超长 Prompt 好得多。

Clawd.bot / 本地 AI 操作系统

Clawd.bot 是目前 "Local-First Agent" (本地优先智能体) 的最佳实践范本。它不仅仅是一个聊天机器人，而是一个能接管你电脑操作系统的 "Agentic OS"。

1. 核心理念：Self-hosted Personal AI Agent

如果说 ChatGPT 是云端的"大脑"，那么 Clawd.bot 就是你电脑上的"管家"。它是 "Chat Interface" + "LLM Brain" + "Local Execution Tools" 的解耦组合，验证了 Agent 开发的未来方向。

2. ChatOps 工作流：无感交互

你不需要下载一个新的聊天 App。它作为"机器人好友"存在于你最常用的软件里：

• iMessage: "帮我查一下这周的日程。"
• Telegram (语音): "提醒我 20 分钟后去拿外卖。"
• Slack: "帮我 review 一下刚才的 PR。"

3. 强大的执行体系 (Skills & MCP)

Clawd.bot 内置了强大的 Skill System（即我们强调的 Tool/MCP 集合）：

• File System: 读写本地文件、整理桌面截图。
• Browser Control: 控制 Chrome 打开网页、抓取数据。
• Coding: 运行 Terminal 命令、Git 操作。
• Memory: 将对话历史和记忆保存为 Markdown 文件，用户可用 Obsidian 直接查看和编辑。

4. 给我们的启示

Clawd.bot 的走红验证了开发者对 "Privacy as a Feature" 和 "Real Automation" 的渴望。我们在构建自己的 Agent 系统时，应学习其 Local-First 的数据与 ChatOps 的交互设计，这很可能是未来 Personal AI OS 的雏形。

Browser Agent 自动化调研

场景：快速了解一个新工具/产品，3分钟完成30分钟的人工调研工作

案例：Clawd.bot 产品深度调研

使用 Antigravity Browser Agent 自动访问并分析 clawd.bot 官网，完整记录产品特性：

(图：Clawd.bot 主页顶部 - Desktop AI 助手工具，强调本地隐私与高效协作)

(图：核心功能特性与安装说明 - 支持 macOS/Windows，集成主流 IDE)

(图：实际应用案例展示 - 代码生成、文档编写、命令执行等场景)

(视频：完整功能演练 - Browser Agent 自动操作并录制全流程)

自动化调研价值：

• ⚡ 3分钟完成：传统人工调研需 30+ 分钟浏览、截图、整理
• 📸 自动截图存证：关键界面全程记录，无需手动操作
• 🎥 录屏演示：动态展示产品功能与交互流程
• 📊 结构化输出：自动生成可分享的调研报告
• 🔄 可复现：同样的 workflow 可用于调研任何产品

(图：Antigravity Browser Agent 正在通过 headless browser 操作并分析 clawd.bot 官网资源)

1.3 实战展示与指南基础

"Show me the code, show me the result." 用截图与链接建立直观印象，详细方法论见第二至第五章。

作品展示与案例分享

架构与设计（AI 协同）：从思维导图到架构图，AI 辅助完成了约 80% 的设计工作；架构图、配置与流程可由 AI 生成后人工微调。

(图：同声传译系统架构 - TRTC 与 AI Worker 交互)

(图：LLM 响应策略思维导图)

(图：配置检查逻辑流程图)

产品与界面（全流程 TTS 工作台）：TTS Studio（在线体验）从文本到音频的完整解决方案，多引擎、批量处理、多格式导出；实时翻译与多端：PC/移动端/视频通话、多 Agent 协作；界面与自动化测试均由 AI 辅助完成。

(图：TTS Studio 主界面)

(图：批量处理与路由报告)

(图：PC 端实时翻译、LKE 知识库集成)

(图：全流程演示)

(图：TTS Studio 与实时语音演示)

(图：同声传译案例截图)

TTS Studio 更多界面：语音选择、高级参数、实时预览与路由报告。

(图：TTS 语音选择、高级设置、音频预览、路由报告)

(图：TTS 测试清单)

(图：TTS Studio 仪表盘)

(图：Realtime AI 登录界面)

(图：Agent 自动操作 Web UI 进行功能验证)

性能与监控（数据驱动迭代）：通过可视化看板实时监控 AI 核心指标；多模型翻译评测、API 请求量、LLM vs TTS 延迟等看板。

(图：多模型评测、评分对比、API 流量趋势、LLM vs TTS 延迟、模型对比)

多端与工具链（生态构建）：围绕核心业务构建工具链；TRTC 应用套件、翻译评测工具设置。

(图：TRTC AI 应用套件主页、翻译评测工具设置)

Realtime AI Chat 多端适配：AI 辅助生成的 UI 完美适配 PC、移动端与视频通话场景——同一套交互在桌面浏览器、手机与多人视频会议中保持一致，便于快速迭代与维护。

(图：视频通话模式 - 连线等待界面)

(图：视频通话模式 - 多人同屏实时翻译)

(图：移动端适配效果 - 响应式设计)

Android 移动应用界面：实时翻译与语音交互在 Android 端同样由 AI 辅助实现 UI 与联调。

(图：Android 端 TRTC AI 应用 - 实时翻译与语音交互)

产品演进与 UI 组件：开发时间轴示意、AI 生成的 UI 组件库。

(图：产品演进时间轴)

(图：AI 生成的 UI 卡片、按钮与交互组件)

(图：多 Agent 协作与功能扩展界面)

开发快照与 AI 助手：

(图：开发过程快照与 AI 助手界面)

后端与监控：TTS 双引擎（Flow + vLLM）、GPU 显存、多租户隔离、自动化测试与看板监控。为让 AI 更懂项目、方便开发，创建了 dev-tts 仓库存储项目记忆信息（CLAUDE.md 示例见 assets/tts/claude-example.md），项目可交给 AI 持续迭代。

开发与交付：开发流程为「选中代码/文件 → AI 修改 → 跑起来 → 点一点测试」；编码占比从约 50% 降到 ~10%，核心从执行者转为决策者与审核者。交付用 Demo + AI 生成 PPT、参数与场景优化，交付后 AI 辅助排查与持续优化。

能力边界与展望：核心决策与敏感信息仍须人工；要知道 AI 能干什么、不能干什么。详见下方「AI 案例分享」章节。

1.4 AI 案例分享 - 真实场景中的 AI 应用

核心主题：遇到什么问题，先想想 AI 能不能做！

(图：同声传译案例截图)

1.4.1 开发场景实战演示

Cursor/Claude 工作流演示

一个典型的 AI 辅助开发流程：

选中代码 → 选中文件 → AI 修改 → 执行命令 → 跑起来 → 测试前端点一点

关键特性：

• 自然语言驱动：命令行执行完全自然语言化，不再需要记忆复杂命令；能听到、能投票、能手动选择——交互越自然，越有认同感、满足感、心流。
• 不必焦虑：Agent 框架、Prompt 提示词不必全学完再用；工具只会变得越来越好用，服务大众，多尝试多分享。

前端测试流程

• AI 辅助的 UI 自动化测试（点一点测试）
• 视觉回归测试与功能验证
• Browser Automation 自动录屏存证

1.4.2 AI 时代的工作时间分配

传统开发 vs AI 辅助开发的时间对比

核心转变：从"执行者"转变为"决策者与审核者"。

1.4.3 客户交付全流程

交付前准备

1. 写一个 Demo：快速原型，给客户增加重视度
2. 写一个 PPT：AI 辅助生成演示文档
3. 背景说明：需要完成什么、需要什么结果

交付过程 4. 参数优化：针对客户场景的模型调优5. 场景垂直优化：每个客户比较垂直定制化

• Conversational AI 例子：LLM、TTS 推荐、热词、同声传译

6. 定制化需求：根据客户业务特点深度定制

交付后支持 7. 问题排查：AI 辅助的线上故障定位 8. 高质量充分测试：提高交付效率9. 持续优化：基于用户反馈迭代

💡 实战案例：产品第一个需求，布置任务，中午去吃饭，下午就好了。

1.4.4 AI 能力边界认知

大胆实践，认清边界

AI 短期内不会取代人类

• 毕竟还需要人的输入
• 核心决策仍需人类判断
• 敏感信息处理需要人工审查

但变革已经来临

• 非常残酷的现实：可能会淘汰一些人
• 我们一定要做好这个技术大变革的准备

边界认知的重要性

• 知道 AI 能干什么、不能干什么——大胆实践、认清边界；往往很多人不知道这个事情，一定要进行实践才能真正理解。
• 会不会被替代、缩减、转型？ 直面现实：做好充实自己、跟上变化，就不必只停留在恐惧；转型与持续学习才是应对之道。

分享是认知边界的有效方式

• 每个人都有不同的方法和经验
• 为了让 AI 应用更加成熟
• 分享是一种有效的方式

1.4.5 真实案例故事集

非技术人员的 AI 应用

🌲 传统单位朋友 领导拍照需求 案例：树叶子绿的 P 成黄的 思维：有问题问 AI，AI 又不会骂你 降低了技术门槛，人人可用，是否有AI思维

📝 写报告总结

• AI 辅助生成结构化报告
• 大幅提升文档效率

技术场景的 AI 提效

✈️ AI 旅行规划

• 完整行程自动生成
• 个性化推荐与优化

🌐 一小时域名部署

• 下发一个指令
• 给二级域名、LLM Key
• 一个小时后给我已经配置好的 SSL 的全球加速的网站

🗣️ 同声传译

• Conversational AI 垂直场景优化
• 每个客户的定制化 LLM/TTS 推荐

1.4.6 未来展望：每个人都带着 Agent 工作

大家带着一堆 Agent 工作，就好比自己的下属。每个人带出来的"下属"水平参差不齐，这就是你的竞争力。

工作方式的变革

• 需求可能很快就被 AI 实现
• 不用再内卷工作时长
• 所有前后端研发都能安心做自己的事情

价值创造的升级

• 比如设计、产品在某个领域安心做自己的事情，发挥更大价值、激发创意，而不是每天为重复的事忙碌。
• 正反馈：产品做决策、架构师提需求、UI 出设计——边界在模糊，每个人都可以在创造自己的价值、做出自己的产品，有正反馈才会觉得更有价值（正如 Mark 问小龙的那句）。
• 另一面：很多人开发了几年项目都没见过产品长什么样，只知道高并发、高可用、中间件、扩缩容——也有价值，但比较枯燥；小公司像 Martin 提到的案例，很迅速、没有历史包袱；大厂变传统公司要转型，大家要跟住变化、拥抱新事物。

竞争力的新维度

• 跟上变化，拥抱变化，充实自己。
• 你的 Agent「团队」的水平参差不齐，这就是你的竞争力——好比一个人带一群 Agent 去「应聘」、去展示 Agent 怎么用，用得好就能通过面试。

1.4.7 分享与成长

工具只会变得越来越好用，服务大众，多尝试多分享！

分享平台的愿景

• 一个 AI 经验分享平台
• 不仅仅是程序员能懂的 Markdown、Skill、Agent
• 让更多人受益

AI 下如何学习

• 不必「什么都想学、什么都学不会」——用 Agent 补齐：选中代码/文件、说需求、改东西、执行命令、跑起来、点一点测试；从做中学，多尝试多分享。
• 跟上变化，拥抱变化，充实自己；未来一定是 AI 能提效、能更好完成任务的。

行业风向：Dario vs Demis 的达沃斯激辩 (2026.01)

"6-12 个月后，AI 就能干完程序员的活了" —— Dario Amodei (Anthropic CEO)

在 2026 年初的达沃斯论坛上，两位 AI 巨头展开了关于未来的"隔空对谈"，这也是对所有开发者的一记警钟：

Dario Amodei (Anthropic) 的激进预测：

• Timeline：6-12 个月内，AI 将完成软件工程师的大部分（甚至全部）工作。
• 现状：Anthropic 的工程师现在基本不再手写代码，而是只负责编辑 Claude 生成的代码。
• 案例：他们的新产品 Claude Cowork，几乎全由 AI 编写，仅用 1.5 周 就开发完成了。
• 警示：可能会出现 "Zeroth-world" 现象——少数技术人员创造极高 GDP（50% 增长），而同时伴随 10% 的高失业率。
• 布局：正在自建 100 万颗 TPU 算力集群，并扩展到生物、网络安全等领域。

Demis Hassabis (DeepMind) 的理性派观点：

• Timeline：虽然编程容易自动化（因为代码运行结果可即时验证），但科学发现验证周期长，全面通用 AI 没那么快（可能 3-5 年）。
• 短期影响：但他承认，今年（2026）就会看到初级、入门级岗位开始受到实质性冲击。
• 给新人的建议：不要试图在 AI 擅长的领域（如写 boilerplate code）跟 AI 竞争。你需要极其熟练地使用工具，利用 Capability Overhang（模型能力中尚未被发掘的潜能），实现职业能力的 "蛙跳" (Leapfrog)。

我们的启示： 不管是一年还是五年，趋势不可逆转。**"只写代码"的时代结束了，"领导 AI 写代码"的时代已经开始。**正如 Demis 所言：利用这段窗口期，成为那个驾驭 AI 的人，而不是被 AI 替代的人。

本指南的实战基础 (Context)

本指南基于 100+ 仓库经验：实时 AI 语音、开发者工具、浏览器扩展、AI 应用与基础设施；技术栈覆盖 React/Vue/纯 HTML、Python/Go/Node、LLM/ASR/TTS/TRTC、Docker/GPU 调度/CI/CD。

引用项目案例：envseal · html-tools · trtc-ai-app · chrome-tts · conversational-ai-agent · flow-tts · flowtts-byok · dgpu-scheduler · dtask-scheduler

第二章：立项 - 从想法到仓库的第一步

图2.1：项目立项完整流程

图2.2：技术选型决策树

技术选型不必自己站开发视角逐项对比，可交给 AI：让 AI 列出各方案优劣与适用场景，人做决策即可。下图为 AI 可生成的一种决策树示例；具体对比表、框架与运行时选型也可让 AI 生成后由人拍板。

图2.3：项目结构模板对比

2.1 项目构思与需求分析（AI 辅助）

2.1.1 使用 AI 进行需求梳理

需求分析框架 Prompt 模板

# 项目需求分析提示词模板

## 背景

我想开发一个 [项目类型]，主要功能是 [核心功能描述]。

## 请帮我分析：

1. 核心功能拆解（MVP 必须功能）
2. 目标用户画像（谁会用？解决什么问题？）
3. 技术可行性（需要哪些技术？难点在哪？）
4. 竞品对比（类似项目有哪些？我们的差异化在哪？）
5. 开发优先级（哪些功能先做？哪些后做？）

## 约束条件

- 开发时间：[预期时间]
- 技术栈：[熟悉的技术]
- 资源限制：[人力/资金/GPU 等]

实际对话示例：html-tools 立项

用户: 我想做一个纯前端工具集，不依赖后端，所有工具都在浏览器中运行。

Claude: 让我帮你分析这个想法：

1. 核心功能方向：
   - JSON 格式化/压缩
   - 图片压缩/格式转换
   - 文本处理（MD5/Base64/正则）
   - 代码格式化
   - 时间戳转换

2. 技术可行性：
   - ✅ 全浏览器 API 实现
   - ✅ 无需服务器，降低成本
   - ✅ 隐私保护（数据不上传）
   - ⚠️ 大文件处理性能限制

3. 差异化优势：
   - 单文件 HTML（1000+ 工具打包）
   - 离线可用（Service Worker）
   - 零构建（无需 npm build）
   - 开源免费

4. MVP 功能：
   先实现 20-30 个常用工具，验证单文件架构可行性

竞品分析提示词

# 竞品分析 Prompt

帮我分析以下竞品：

- [竞品 A]
- [竞品 B]

对比维度：

1. 功能覆盖
2. 用户体验
3. 技术实现
4. 商业模式
5. 优缺点

我的项目差异化机会在哪？

2.1.2 真实案例深度拆解

案例 1：html-tools 立项全过程

阶段 1：灵感来源

• 痛点：经常需要在线工具，但担心隐私泄露
• 现有方案不足：
  • 需要联网
  • 广告多
  • 功能分散

阶段 2：AI 辅助需求分析

我: 市面上的在线工具有什么问题？

Claude: 主要问题：
1. 隐私风险：数据上传到服务器
2. 依赖网络：离线无法使用
3. 广告干扰：影响体验
4. 功能分散：需要多个网站

你的机会：
- 做成单文件 HTML，1000+ 工具打包
- 完全离线可用
- 无广告，开源

阶段 3：技术可行性验证

• 使用 Claude 快速实现 5 个工具原型
• 验证单文件架构可行性
• 测试浏览器 API 兼容性

阶段 4：功能优先级规划

MVP（第一版）：
- 基础工具：JSON/Base64/MD5
- 图片工具：压缩/裁剪/格式转换
- 文本工具：正则/Diff/计数

迭代计划：
- V1.1: 增加 PDF 工具
- V1.2: 增加开发者工具（JWT/UUID）
- V2.0: 达到 1000+ 工具

结果：

• 开发时间：2周（AI 辅助）
• 功能数量：1023+ 工具
• GitHub Stars: 2
• 实际使用：高频工具集

案例 2：realtime-ai 立项过程

背景： 需要一个实时 AI 语音对话平台，支持流式 STT/LLM/TTS

AI 辅助需求拆解：

我: 我想做一个类似 OpenAI Realtime API 的服务，
    但要支持更多 ASR/TTS 提供商

Claude: 核心需求分解：

1. 架构选择：
   - WebSocket 双向通信
   - 流式处理（不等完整语音）
   - 低延迟优化

2. 技术栈：
   - 后端：Python + FastAPI
   - 实时通信：WebSocket
   - ASR：Fun-ASR（阿里）
   - LLM：OpenAI 流式 API
   - TTS：FlowTTS

3. 难点：
   - 音频流处理
   - VAD（语音活动检测）
   - 延迟优化（目标 <500ms）
   - 多并发支持

4. MVP 功能：
   - 基础对话流程
   - 支持 1 种 ASR/LLM/TTS
   - 单用户测试

技术选型讨论：

我: WebSocket 还是 HTTP/2 SSE？

Claude: 对比分析：

WebSocket:
✅ 双向通信（适合实时对话）
✅ 更低延迟
✅ 更好的音频流支持
⚠️ 需要处理连接管理

HTTP/2 SSE:
✅ 更简单的实现
⚠️ 单向通信（需要两个连接）
⚠️ 不适合音频流

推荐：WebSocket

结果：

• 从构思到 MVP：10天
• 功能完整度：90%
• GitHub Stars: 4
• 实际应用：多个项目基于此开发

其他实战案例快览 (Other Scenarios)

除了上述两个核心案例，AI 在其他场景下同样展现出强大的 "需求 -> 落地" 转化能力。

💡 核心启示： 这些案例的共同点在于，AI 不仅是写代码的手 (Coder)，更是思考需求的脑 (Analyst)。 它能帮你做竞品调研、用户场景分析、技术选型对比，让你在写第一行代码前就想清楚 "What to build"。

引用项目案例

• html-tools - 纯前端工具集
• conversational-ai-agent - 实时 AI 语音系统
• trtc-ai-build-quickly - 企业级 AI 框架
• chrome-tts - 浏览器扩展实战

Prompt 模板代码

# 需求分析框架

# 竞品分析框架

# 技术可行性评估框架

# 用户调研问卷生成

# 技术选型对比模板

# 用户场景分析模板

# API 能力评估模板

2.2 仓库命名与项目结构设计

2.2.1 仓库命名哲学

命名原则

1. 简洁性原则（Short & Memorable）

• 优秀案例：
  • envseal - 环境变量封存（env + seal）
  • clipvault - 视频剪辑库（clip + vault）
  • codepod - 代码容器（code + pod）
• 命名技巧：
  • 使用组合词（2个单词）
  • 避免缩写（除非业内通用）
  • 易于拼写和记忆

2. 描述性原则（Self-Explanatory）

• 优秀案例：
  • trtc-ai-build-quickly - 快速构建 TRTC AI
  • realtime-ai - 实时 AI 系统
  • python-observability-monitor - Python 可观测性监控
• 适用场景：
  • 技术栈工具
  • 明确功能的库
  • 企业级项目

3. 品牌化原则（Brandable）

• 优秀案例：
  • aimake - AI 制作平台（ai + make）
  • startpage - 浏览器起始页
  • html-tools - HTML 工具集
• 命名技巧：
  • 可以注册域名
  • 易于传播
  • 有品牌联想

命名反例与改进

❌ my-project-2024-v1-final
✅ project-name

❌ trtc_ai_demo_test_v2
✅ trtc-ai-demo

❌ super-awesome-amazing-tool
✅ toolname

命名检查清单

• 长度 < 30 字符
• 使用小写 + 连字符（kebab-case）
• 避免数字结尾（除非版本号）
• GitHub/npm 上未被占用
• 对应域名可注册（如需要）
• 易于搜索（不与常见词冲突）

实际案例分析

2.2.2 项目结构设计

标准项目结构模板

my-ai-project/
├── .github/                    # GitHub 配置
│   ├── workflows/              # CI/CD 工作流
│   │   ├── test.yml           # 测试流程
│   │   ├── build.yml          # 构建流程
│   │   └── deploy.yml         # 部署流程
│   ├── ISSUE_TEMPLATE/        # Issue 模板
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── dependabot.yml         # 依赖更新配置
│
├── docs/                       # 文档目录
│   ├── README.md              # 文档入口
│   ├── architecture.md        # 架构设计
│   ├── api.md                 # API 文档
│   └── deployment.md          # 部署指南
│
├── src/                        # 源代码
│   ├── __init__.py            # Python 包初始化
│   ├── main.py                # 主入口
│   ├── api/                   # API 路由
│   ├── services/              # 业务逻辑
│   ├── models/                # 数据模型
│   └── utils/                 # 工具函数
│
├── tests/                      # 测试目录
│   ├── unit/                  # 单元测试
│   ├── integration/           # 集成测试
│   └── e2e/                   # 端到端测试
│
├── scripts/                    # 脚本工具
│   ├── setup.sh               # 初始化脚本
│   ├── deploy.sh              # 部署脚本
│   └── backup.sh              # 备份脚本
│
├── .claude/                    # Claude Code 配置
│   ├── CLAUDE.md              # 项目规则
│   ├── skills/                # 自定义命令
│   └── templates/             # 代码模板
│
├── .cursorrules                # Cursor 规则文件
├── .gitignore                  # Git 忽略文件
├── .env.example                # 环境变量示例
├── README.md                   # 项目说明
├── LICENSE                     # 开源协议
├── pyproject.toml              # Python 项目配置
└── requirements.txt            # Python 依赖

不同类型项目的结构差异

前端项目（React/Vue）

frontend-app/
├── src/
│   ├── components/            # 组件
│   ├── pages/                 # 页面
│   ├── hooks/                 # 自定义 hooks
│   ├── utils/                 # 工具函数
│   ├── styles/                # 样式
│   ├── assets/                # 静态资源
│   └── App.tsx                # 根组件
├── public/                    # 公共资源
├── package.json
└── vite.config.ts             # 构建配置

CLI 工具项目

cli-tool/
├── src/
│   ├── commands/              # 命令实现
│   ├── cli.py                 # CLI 入口
│   └── utils/
├── setup.py                   # 打包配置
└── README.md

Obsidian 插件项目

obsidian-plugin/
├── src/
│   ├── main.ts                # 插件入口
│   ├── settings.ts            # 设置面板
│   └── components/
├── manifest.json              # 插件配置
├── versions.json              # 版本兼容性
└── styles.css                 # 样式

实时 AI 服务项目

realtime-ai-service/
├── src/
│   ├── websocket/             # WebSocket 处理
│   ├── asr/                   # 语音识别
│   ├── llm/                   # 大语言模型
│   ├── tts/                   # 语音合成
│   └── utils/
├── docker/                    # Docker 配置
├── k8s/                       # Kubernetes 配置
└── docker-compose.yml

引用项目案例

• html-tools - 单文件结构
• conversational-ai-agent - 完整后端结构
• a2a-multiagent-server - Go 微服务结构
• envseal - CLI 工具结构

2.3 技术选型：AI 给优劣，人做决策

前端（React / Vue / 纯 HTML）、后端（Python / Go / Node）、CLI/插件等，均可交给 AI：让 AI 生成「优劣对比表 + 决策树」（上图 2.2 即为一例），人定结论后再让 AI 写 Dockerfile、依赖与模板。作品用截图 + 仓库链接展示即可，不必在正文重复罗列技术栈与案例。

2.3.1 前端 / 后端 / AI 能力：统一用法

前端：让 AI 对比 React / Vue / 纯 HTML、TypeScript vs JavaScript、Vite / Next.js / 单文件，给出适用场景与推荐，人拍板。后端：让 AI 对比 Python / Go / Node 的维度（开发速度、性能、AI 生态、部署等），人定语言与框架。AI 能力（LLM、ASR/TTS、实时音视频）：选型由人定，集成代码与配置交给 AI 生成。详见上方图 2.2 与引用链接。

2.3.2 AI 能力集成选型

LLM：OpenAI（生态成熟）、Claude（推理与代码）、Gemini（多模态、免费额度大）——按需求与预算选，人定 API，AI 写调用代码。ASR/TTS：开源可部署（Fun-ASR、Whisper、FlowTTS / flow matching）或云 API（按需付费）。实时音视频：可用腾讯云 TRTC 等 SDK。选型后让 AI 生成集成示例与配置即可，不必在正文堆案例。

引用项目案例

• html-tools - 纯 HTML + Vanilla JS
• trtc-ai-app - Vue 3 + TRTC
• a2a-multiagent-server - Go + Gin
• dtask-scheduler - Go 分布式
• flow-tts - TypeScript + Node.js

2.4 项目初始化清单

六步：① Git init + .gitignore（AI 生成「[语言] 项目 .gitignore」）② License（MIT/Apache/GPL，问 AI 推荐）③ README（项目名+功能+技术栈，要 Features/Quick Start/Contributing/License）④ 代码风格（Black/ESLint/gofmt，AI 生成配置）⑤ AI 工具（.claude/CLAUDE.md 或 .cursorrules，见第三章 3.1.1）⑥ 依赖管理（poetry/pnpm/go mod，AI 填依赖与脚本）。可选：CI/CD、src/tests/docs、Issues/PR 模板。完整检查清单可让 AI 按「[语言] 项目初始化检查清单」生成；也可让 AI 生成 init-project.sh 做占位骨架。

引用项目案例

• html-tools - MIT License, 单文件项目
• flow-tts - TypeScript + pnpm
• flowtts-byok - Python 项目结构
• envseal - CLI 工具配置

第三章：开发 - AI 驱动的编码实践

图3.1：Claude Code 配置体系

图3.2：AI 辅助开发生命周期

图3.3：不同项目类型开发流程对比

图3.4：CodeBuddy 工作流编排

图3.5：Agent 系统架构

3.1 Claude Code 深度实践

3.1.1 配置文件最佳实践

.claude/CLAUDE.md 建议结构：项目概述（类型 + 技术栈）→ 代码风格（Black/isort/type hints、命名规范、docstring 约定）→ 测试要求（单元测试、覆盖率 >80%、pytest）→ Git 提交规范（Conventional Commits）→ 项目特定规则（错误处理、异步、API 设计、依赖/安全/性能、禁止事项）。按项目裁剪即可；可让 AI 根据「[语言] 项目 CLAUDE.md 模板」生成初版。

Skills：在 .claude/skills/ 下放可执行脚本（如 test.sh 跑 pytest、deploy.sh 跑 docker-compose），Agent 可被调度执行。Templates：在 .claude/templates/ 放带占位符的代码片段（如 FastAPI 路由模板）。Hooks：在 .claude/hooks/ 放 pre-commit 等钩子（格式化 + lint + 测试），提交前自动跑。

3.1.2 实战技巧（Agent 构建导向）

当前以 Agent 构建为主：选中代码或文件，直接说需求；复杂流程用 Code Review Agent、Subagent、Skill 完成。下面按「日常协作」「代码质量」「设计与实现」「工程与交付」「文档与决策」五类整理，只保留真正常用的做法。

一、和 Agent 协作的日常姿势

• 说需求：自然语言说清「目标 + 约束 + 参考」即可，不必写长 Prompt；Agent 结合 CLAUDE.md 与仓库理解上下文。
• 上下文：大任务（读很多文件、调研）交给 Subagent，主会话只收摘要；用 /context 看占用，常驻规则放 CLAUDE.md；项目结构清晰、单文件 <500 行，便于 Agent 按需读。
• 多文件：按层/模块分步说（先 Model 再 Service 再 API），Agent 跨文件编辑。
• 错误修复：贴错误栈或选中报错文件，说「分析原因并修复」「是否还有类似问题」。
• 零散需求：正则、对比两段代码、解释复杂代码、生成 Commit message —— 直接说一句需求即可，或交给 IDE/CLI 自带能力。

二、代码质量：审查、测试、重构、安全

• 格式化与规范：说「按 Black/Prettier/ESLint 格式化本项目并统一风格」或「统一缩进、引号、尾逗号、命名」；把规则写进 CLAUDE.md，用 Hooks 提交前自动格式化 + lint。
• 审查：选中文件/目录，说「审查这段代码」或用 Code Review Agent、/code-review、审查类 Skill。
• 测试：选中函数/文件，说「生成 pytest 测试，覆盖正常/边界/异常」；可用 Skill 或 /test 统一风格（如覆盖率 >90%）。
• 重构：先「分析问题与重构建议」，再「按步骤重构」或「先写测试再重构」；大文件交给 Subagent 单步执行。
• 安全与漏洞审查：说「做安全审计，重点 SQL 注入、XSS、CSRF、敏感信息」或触发安全/Code Review 类 Skill；依赖漏洞：选中 package.json/requirements.txt，说「分析依赖漏洞并给出修复方案」或先跑 npm audit/pip-audit/Dependabot 再让 Agent 解读与改版本。

三、设计与实现：API、数据、前端、性能

• API：说「为 XX 资源设计 RESTful API：CRUD、格式、错误码、分页、认证」→ 生成路由/OpenAPI；再说「生成 API 文档」即可。
• 数据：说「设计 XX 系统数据库，给 ER 图（Mermaid）、DDL、索引」；说「生成 Mock 数据 N 条、含边界」。
• 前端：说「创建 XX 组件，用 React/Vue+TS+Tailwind，含 Props 类型」。
• 性能：贴慢代码或 SQL，说「分析瓶颈、优化、索引/重写」；同步改异步说「改成 asyncio 并发、加超时与错误处理」。

四、工程与交付：环境、CI/CD、部署、监控

• 环境：说「生成 .env.example、docker-compose.yml」。
• 依赖：选中 package.json/requirements.txt，说「分析过时与漏洞、推荐升级」；或先跑 npm audit/pip-audit 再让 Agent 解读。
• CI/CD：说「生成 GitHub Actions：测试、lint、构建、部署到 XX，仅 main 触发」。
• 部署：说「生成 Docker 配置：多阶段、非 root、健康检查」。
• 排错与监控：贴日志/堆栈，说「分析原因、修复、预防」；说「配置 Sentry：仅 prod、过滤 404/health、上下文、采样」。

五、文档与决策

• 文档：说「生成 README，含徽章、快速开始、特性、安装、示例、贡献、许可证」或让 Agent 根据仓库自动生成。
• 技术选型：说「为 XX 项目选 XX 技术，候选 A/B/C，对比给推荐」（详见第二章 2.3）。

引用项目案例

• conversational-ai-agent - 大型 AI 项目配置实践
• trtc-ai-build-quickly - 快速开发脚手架
• html-tools - 简单项目配置

代码示例

• .claude/CLAUDE.md 完整配置（30+ 行）
• Skills 脚本示例（5+ 个）
• Templates 模板示例（3+ 个）
• Hooks 示例（2+ 个）

3.2 不同类型项目的开发实践

3.2.1 前端应用开发

AI 用法要点：纯前端单页/工具集可让 AI 按「单文件、无构建、离线优先」生成模板，再批量衍生相似工具；React/Vue 项目可先让 AI 搭好脚手架（Vite + TypeScript + 状态与 API 层），再按「流式接口、组件规范」迭代。在 CLAUDE.md 中写明技术栈与构建命令即可。

引用：html-tools（纯前端工具集）、Gemini 系列应用（React + Vite + 流式 API）。

3.2.2 CLI 工具开发

AI 用法要点：在 CLAUDE.md 中说明 CLI 框架（如 Click/argparse）与子命令结构，让 AI 生成入口、子命令、参数校验与错误处理；涉及加密/扫描/Git 等可拆成「先接口后实现」的小任务逐步补全。

引用：envseal（环境变量加密与跨仓库扫描，AI 辅助约 3–4 天完成核心能力）。

3.2.3 其他类型项目简述

除前端与 CLI 外，AI 同样适用于浏览器扩展（Manifest V3、Content Scripts）、编辑器/笔记插件（如 Obsidian API + 终端集成）、实时 AI 服务（WebSocket、ASR/TTS 管道）等。共性做法：在 CLAUDE.md 中写明项目类型与运行方式，用「先跑通最小闭环、再让 AI 补全」的方式迭代；复杂领域（如多 GPU 调度、语音栈）可先写好接口与配置，再让 AI 生成实现与部署脚本。

引用项目案例（按类型）

• chrome-tts - Chrome TTS 扩展
• obsidian-claude-code - Obsidian 内嵌 Claude Code
• conversational-ai-agent - 实时 AI 语音与语音栈集成

3.3 AI 辅助的代码质量提升

3.3.1 代码审查（AI Review）

多 AI 交叉审查策略

审查流程

代码提交 → Claude 初审 → GPT-5 安全审查 → Gemini 文档审查 → 人工确认

Claude Code 审查实践

# 审查单个文件
claude review src/api/routes.py

# 审查整个 PR
git diff main...HEAD | claude review

# 特定问题审查
claude review --focus=security src/
claude review --focus=performance src/

审查维度

1. 功能正确性

   • 逻辑正确性
   • 边界条件
   • 错误处理

2. 安全性

   • SQL 注入
   • XSS 漏洞
   • 权限校验

3. 性能

   • N+1 查询
   • 内存泄漏
   • 算法复杂度

4. 可维护性

   • 代码风格
   • 命名规范
   • 注释清晰度

自动化 Linting

Pre-commit Hook 示例：

#!/bin/bash
# Python 项目
black src/ tests/ --check
isort src/ tests/ --check-only
flake8 src/ tests/
mypy src/

# TypeScript 项目
npx eslint src/ --fix
npx prettier --write "src/**/*.{ts,tsx}"

安全漏洞扫描

• Dependabot（依赖扫描）
• Bandit（Python 安全）
• Safety（依赖漏洞）
• Snyk（多语言支持）
• CodeQL（代码分析）

3.3.2 测试驱动开发

单元测试生成（AI 辅助）

测试覆盖维度

1. 正常情况测试
2. 边界条件测试
3. 异常情况测试
4. 安全性测试（SQL 注入、XSS）

集成测试设计

WebSocket 集成测试示例：

@pytest.mark.asyncio
async def test_full_conversation_flow(client):
    with client.websocket_connect("/ws/test") as ws:
        # 发送音频
        ws.send_bytes(audio_data)

        # 接收转录
        response = ws.receive_json()
        assert response['type'] == 'transcript'

        # 接收音频响应
        response = ws.receive_json()
        assert response['type'] == 'audio'

E2E 测试（Playwright）

async def test_ui_conversation():
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        page = await browser.new_page()

        await page.goto("http://localhost:3000")
        await page.click("button:has-text('开始')")

        # 验证功能
        await page.wait_for_selector(".transcript")

测试覆盖率

• 目标：> 80%
• 工具：pytest-cov
• CI 集成：自动运行

3.3.3 文档生成

README、API 文档、架构图等均可让 AI 按项目结构描述生成，此处不展开。

3.4 常见问题与解决方案

问题 1：AI 生成代码不符合项目风格

解决方案：配置 .claude/CLAUDE.md

示例配置：

# 代码风格

- Python: Black + isort
- 函数命名：snake_case
- 类命名：PascalCase

# 禁止事项

- ❌ 不用 print() 调试
- ❌ 不硬编码配置

问题 2：上下文过长导致理解偏差

解决方案

1. 优化项目结构

   • 单文件 <500 行
   • 清晰模块划分

2. 使用 MCP 管理上下文

   {
     "important_files": ["src/api/routes.py"],
     "ignore_patterns": ["*/migrations/*"]
   }

3. 分步骤重构

   • 一次一个模块
   • 频繁提交

问题 3：多文件修改导致冲突

解决方案 1：git worktree 并行开发（多 Agent 与 Worktree 完整用法见 第三章 3.6）

# 创建多个 worktree
git worktree add ../project-auth feature/auth
git worktree add ../project-payment feature/payment

# 在不同目录并行开发
cd ../project-auth
claude code  # 开发认证功能

cd ../project-payment
claude code  # 开发支付功能

解决方案 2：增量开发

• 小步提交
• 频繁集成
• 定期同步

解决方案 3：使用 AI 解决冲突

我: Git 冲突中有两个版本：
当前分支：def get_user(id): ...
功能分支：async def get_user(id): ...

Claude: 保留异步版本：
async def get_user(id): ...

3.5 工程化 - 构建可维护的 AI 项目

图3.5.1：分层架构设计

图3.5.2：Docker 多阶段构建流程

图3.5.3：微服务架构（以 realtime-ai 为例）

3.5.1 代码组织与模块化

分层架构设计

# 推荐的项目结构
realtime-ai/
├── src/
│   ├── api/              # 表现层
│   │   ├── routes.py
│   │   └── dependencies.py
│   ├── services/         # 业务层
│   │   ├── asr_service.py
│   │   ├── llm_service.py
│   │   └── tts_service.py
│   ├── models/           # 数据层
│   │   ├── user.py
│   │   └── conversation.py
│   └── utils/            # 工具层
│       ├── logger.py
│       └── config.py
├── tests/
├── docs/
└── docker/

依赖注入实践

• FastAPI Depends
• 构造函数注入
• 配置注入

微服务架构（model-services-framework 案例）

• 服务拆分原则
• API Gateway 设计
• 服务间通信（gRPC/HTTP）

3.5.2 依赖管理

不同语言的依赖管理

Python 依赖管理

# pyproject.toml (Poetry 推荐)
[tool.poetry]
name = "realtime-ai"
version = "1.0.0"

[tool.poetry.dependencies]
python = "^3.9"
fastapi = "^0.104.0"
openai = "^1.0.0"

[tool.poetry.dev-dependencies]
pytest = "^7.0.0"
black = "^23.0.0"

Node.js 依赖管理

{
  "name": "gemini-app",
  "dependencies": {
    "react": "^18.0.0",
    "@google/generative-ai": "^0.1.0"
  },
  "devDependencies": {
    "vitest": "^0.34.0"
  }
}

Go 依赖管理

// go.mod
module github.com/chicogong/stream-relay-go

go 1.21

require (
    github.com/gin-gonic/gin v1.9.1
    github.com/gorilla/websocket v1.5.0
)

依赖安全：envseal 实践

• SOPS 加密敏感依赖配置
• .env 文件加密存储
• secrets-vault 管理

3.5.3 环境管理

Docker Compose 本地开发

# docker-compose.yml
version: "3.8"

services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    volumes:
      - ./src:/app/src
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

多环境配置

# config.py
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    environment: str = "dev"
    openai_api_key: str
    database_url: str

    class Config:
        env_file = f".env.{os.getenv('ENVIRONMENT', 'dev')}"

# 使用
settings = Settings()

本地 GPU 环境配置

FROM nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu22.04

RUN pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

3.5.4 日志与监控

要点简述

日志：用 structlog 等输出 JSON 结构化日志，便于采集与检索。分布式追踪：OpenTelemetry 打点（ASR/LLM/TTS 等 span）。指标：Prometheus Counter/Histogram + 暴露 /metrics。错误：Sentry 初始化 + capture_exception，按环境配置采样率。具体实现可让 AI 按「[语言] + [框架] 日志/追踪/监控」生成，无需在正文贴完整代码。

3.5.5 基础设施即代码

要点简述

Docker：多阶段构建（builder 装依赖 → runtime 只拷产物）、非 root 用户、健康检查。GPU 镜像：基于 nvidia/cuda，安装 PyTorch 与推理依赖。K8s：Deployment 里 limits: nvidia.com/gpu: 1、暴露端口。让 AI 按「[项目类型] Dockerfile / deployment.yaml」生成即可。

引用项目案例

• audio-pipeline - 分层架构重构

• a2a-multiagent-server - Go 微服务架构

• envseal - 依赖安全管理

• trtc-ai-cloudbase - Serverless 部署实践

• 图4.5：Docker 构建流程

• 图4.6：日志追踪链路图

3.6 协作 - 多 Agent 并行与 AI 时代的 Git

本章不讲基础 Git（如 init、commit、PR 流程等），只讲 多 Agent 并行 与 AI 场景下的 Git 用法：Claude Code 等 Agent 工具、单机多 Worktree、多物理机/多机、以及多 Agent 下的提交与冲突策略。

图3.6.1：多 Agent 并行架构（Worktree + 多机）

3.6.1 多 Agent 并行工作流

"Be the Manager, not just the Coder." 当你熟练掌握 AI Coding 后，下一步就是让多个 Agent 并行工作，成为「一个人就是一个团队」的超级个体。

传统 AI 辅助开发往往是串行的：思考 → 问 AI → 等待生成 → 验证代码。在 Claude Code、Cursor、CodeBuddy 等 Agent 工具下，可以打破这种线性流程，让多个 Agent 同时干活。

单 Agent vs 多 Agent：

核心思路：单机用 Git Worktree 开多个工作目录，每目录一个 Claude Code Session；多机则用多台物理机或云端 IDE 跑 headless/临时 Agent。下面分单机、多机、工作流与 AI Git 实践说明。

3.6.2 单机并行：Git Worktree + Claude Code

Git Worktree 是同一台机器上、同一仓库的多个「并行工作目录」，每个目录对应一个分支，可同时开多个终端各跑一个 Claude Code（或 Cursor、CodeBuddy）Session，互不抢上下文。

典型场景：

1. 主目录 (Main)：你负责 Merge、统筹。
2. Worktree A (feature/backend)：claude →「实现 User 模型和 API 接口」。
3. Worktree B (feature/frontend)：claude →「实现登录页」。
4. Worktree C (docs)：claude →「根据最新代码更新 README 和 API 文档」。

操作示例：

# 创建 worktree（每个目录一个分支）
git worktree add ../my-app-backend feature/backend
git worktree add ../my-app-frontend feature/frontend

# 多终端（Tmux / iTerm2 分屏）
# Terminal 1 - Backend Agent
cd ../my-app-backend
claude
# > "请实现 User 模型和对应的 API 接口..."

# Terminal 2 - Frontend Agent
cd ../my-app-frontend
claude
# > "请根据 UI 设计图实现登录页面..."

# 主目录：Review 与 Merge
git worktree list

常用命令速查见 附录 A.1 Git Worktree。

3.6.3 多机与多物理机

单机 Worktree 足够多数场景；若有多台设备或需要隔离环境，可做 多机分布式：

• 主力机（如 MacBook Pro）：核心架构、Code Review、最终集成。
• 旧 PC / Linux Server / Mac mini：跑 headless 模式 的 Claude Code（或 Cursor/CodeBuddy），专门执行耗时任务（大规模重构、批量测试生成等）。
• 云端 IDE（如 GitHub Codespaces）：按需拉起临时 Agent 环境，用完即删。

这样同一仓库可在多台物理机上有多个 checkout，通过 push/pull 同步；每个机器上同样可以用 Worktree 再开多分支并行。注意权限与密钥不要提交进仓库（用 .env 或本地配置）。

3.6.4 "The Matrix" 工作流：分发、异步、聚合

多 Agent 下，你的角色从「写代码」变成「调度与验收」：

1. 分发 (Dispatch)：不再问「这个函数怎么写」，而是「Agent A 做后端接口，Agent B 做前端页面，Agent C 更新文档」。
2. 异步 (Async)：不必盯着屏幕等输出；下完指令可切到别的窗口或机器处理其他事。
3. 聚合 (Merge)：Agent 各自提交或提 PR 后，你以 Code Reviewer 身份合并；遇到冲突可交给 AI 解决（见下节）。

3.6.5 AI 的 Git 使用：多 Agent 下的提交与冲突

不教基础 Git 命令，只强调多 Agent 协作时的用法：

1. 原子化提交
   让每个 Agent「小步提交、每次只做一件事」：
   Prompt 示例：「每完成一个小功能点就 commit 一次，message 写清楚做了什么。」

2. 冲突交给 AI 解
   Worktree A 和 B 改到同一文件时，merge 会冲突。既然代码多是 AI 写的，解冲突也可交给 AI：
   git merge feature/backend 出现冲突后，在同一目录打开 claude：「帮我解决当前的 merge conflict，保留两边的合理逻辑。」

3. 语义化分支命名
   便于区分哪个 Agent/哪类任务：

   • agent/backend/feature-x
   • agent/frontend/fix-y
   • agent/docs/readme-update

专职 PR 合并与代码 Review 的 Agent：可固定一两个 Agent（如单独一台机或固定 Worktree）只做「拉取各 feature 分支的 PR、跑 CI、做 AI 代码审查、给出合并建议或自动合并」。你只需在关键决策点人工确认，或通过手机/电脑看结果再干预。

如何看 AI 开发进度：不必一直盯屏。手机：用 GitHub App、飞书/钉钉机器人、或自建小站推送「今日提交 / PR 列表 / CI 状态」；电脑：看提交历史（git log）、PR 列表与 CI 结果即可。需要时再打开对应 PR 做人工干预（改描述、关掉自动合并、亲自解冲突等）。

💡 终极形态：你是 「算力指挥官」——多机多 Worktree 上的 Agent 并行开发，专职 Agent 负责 PR 与 Review；你手机/电脑看进度，必要时人工干预，其余交给自动化。

引用：conversational-ai-agent · trtc-ai-build-quickly · envseal

第四章：测试与部署

4.1 测试 - 保证代码质量的防线

图4.1：测试金字塔

图4.2：CI 测试流程

4.1.1 测试策略金字塔

建议比例：单元测试 70%（pytest/Jest 等）、集成测试 20%、E2E 10%。单元测试用 AI 生成即可：说明被测接口/函数与边界条件，让 Claude 生成用例；Python 用 pytest、JS/TS 用 Jest，覆盖率目标 >80%。

4.1.2 AI 辅助测试

使用 Claude Code 生成测试

Prompt 示例：「为 POST /api/users（参数 username/email/password，返回 user_id）生成完整测试，覆盖：成功创建、缺字段、无效邮箱、弱密码、重复用户、SQL 注入/XSS 防护。」 AI 会生成用例；用 pytest --cov=src 或 npm run test -- --coverage 查覆盖率即可。

4.1.3 特殊场景测试

4.1.3.1 AI 模型测试（ASR/TTS）

ASR：用 WER（词错误率）等指标，对 reference vs hypothesis 做断言（如 assert wer == pytest.approx(0.2, rel=0.01)）。TTS：可做 MOS 自动评估或主观听测断言。具体用例可让 AI 根据项目评估脚本生成。

4.1.3.2 实时系统测试（realtime-ai 案例）

延迟：测 WebSocket 往返时间（发送→接收），断言如 < 500ms。并发：用 asyncio.gather 模拟多连接，断言全部成功。负载：用 Locust 等压测 WebSocket 端点。示例可让 AI 按「pytest asyncio 测 WebSocket 延迟与并发」生成。

4.1.4 持续测试（CI 集成）

GitHub Actions 配置

# .github/workflows/test.yml
name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.9"

      - name: Install dependencies
        run: |
          pip install poetry
          poetry install

      - name: Run tests
        run: |
          poetry run pytest tests/ \
            --cov=src \
            --cov-report=xml \
            --cov-report=term

      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          files: ./coverage.xml
          fail_ci_if_error: true

测试结果展示：

• Codecov 徽章
• 覆盖率趋势图
• PR 评论自动添加测试报告

引用项目案例

• conversational-ai-agent - 实时系统测试
• asr_eval - ASR 识别率评估
• translate_eval - 翻译质量评测
• asr_evaluation - 语音识别测试

4.2 部署 - 从本地到生产环境

图4.3：部署方式决策树

图4.4：CI/CD 完整流程

图4.5：多环境部署架构

图4.6：GPU 调度架构（dgpu-scheduler）

4.2.1 部署方式决策矩阵

4.2.2 前端部署实践

4.2.2.1 静态站点部署（html-tools 案例）

GitHub Pages 配置：

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

自定义域名 + HTTPS：

1. DNS 配置：
   CNAME: tools.example.com -> chicogong.github.io

2. GitHub Pages 设置：
   ✅ Enforce HTTPS
   ✅ Custom domain: tools.example.com

4.2.2.2 Vercel 部署（Gemini 应用）

# 一键部署
npm install -g vercel
vercel

# 环境变量配置
vercel env add VITE_GEMINI_API_KEY

vercel.json 配置：

{
  "builds": [
    {
      "src": "package.json",
      "use": "@vercel/static-build"
    }
  ],
  "routes": [
    { "src": "/api/(.*)", "dest": "/api/$1" },
    { "handle": "filesystem" },
    { "src": "/(.*)", "dest": "/index.html" }
  ]
}

4.2.3 后端服务部署

4.2.3.1 Docker 容器化部署

realtime-ai Docker 配置：

# Dockerfile
FROM python:3.9-slim

WORKDIR /app

# 安装依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制代码
COPY src/ ./src/

# 暴露端口
EXPOSE 8000

# 启动命令
CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

docker-compose.yml：

version: "3.8"

services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

volumes:
  redis_data:

4.2.3.2 Serverless 部署（腾讯云 SCF）

结合用户反馈（强调腾讯云 SCF, CloudBase, COS + CNAME + ICP 备案）：

腾讯云 SCF 部署：

# serverless.yml
service: realtime-ai-api

provider:
  name: tencentcloud
  runtime: Python3.9
  region: ap-guangzhou
  credentials: ~/.tencentcloud/credentials

functions:
  api:
    handler: index.main_handler
    events:
      - apigw:
          name: api
          parameters:
            serviceId: service-xxx
            environment: release
    environment:
      OPENAI_API_KEY: ${env:OPENAI_API_KEY}

CloudBase 全栈部署：

# 安装 CLI
npm install -g @cloudbase/cli

# 登录
tcb login

# 初始化
tcb init

# 部署
tcb deploy

COS 静态网站托管 + CNAME：

1. 创建 COS 存储桶：

# 上传静态文件到 COS
coscmd upload -r ./dist/ /

2. 配置自定义域名：

存储桶设置 → 域名管理 → 添加自定义域名
- 自定义域名：static.example.com
- 回源配置：默认回源
- HTTPS 配置：申请免费证书

3. ICP 备案（重要！）：

中国大陆访问需要 ICP 备案：
1. 购买域名
2. 准备备案资料（身份证、营业执照）
3. 提交备案申请（腾讯云备案系统）
4. 等待审核（7-20 天）

4.2.3.3 GPU 服务部署（FlowTTS / flow matching）

要点：NVIDIA 基础镜像 + requirements + 模型下载可让 AI 生成 Docker 配置；多 GPU 调度可说「生成多卡推理队列/调度脚本」或参考 dgpu-scheduler 分布式调度（节点与配额配置可 AI 生成）。

4.2.4 包发布与分发

要点：PyPI（pyproject.toml / poetry build & publish）、npm（package.json、npm publish --access public）、Chrome 扩展（manifest.json、打包 zip、商店上传与审核）——配置与流程均可说「为当前项目生成 XX 发布配置与步骤」由 AI 生成。

4.2.5 自动化 CI/CD（AI 驱动）

CI/CD 可全由 AI 搭好：说「根据我当前项目生成 GitHub Actions：test → build → deploy 到 [Vercel/Pages/Docker]」即可生成 workflow；合并 main 后自动部署，PR 只跑测试；多环境策略如 develop→Staging、main→Production（可加手动审批），关键发布时人工确认或回滚即可。

4.2.6 部署检查清单

部署前：环境变量、DB 迁移、CDN/静态资源、SSL、DNS、健康检查 /health、日志（Sentry）、监控与告警、备份与回滚方案。部署后：服务启动、API 可访问、DB/缓存/日志/监控正常。

引用项目案例

• html-tools - GitHub Pages 静态站部署
• trtc-ai-app - Vercel 前端部署
• conversational-ai-agent - Docker 容器化部署
• trtc-ai-cloudbase - Serverless 云开发部署
• dgpu-scheduler - 分布式 GPU 调度
• scf-deploy-demo - 腾讯云 SCF

第五章：运营 - 持续迭代与用户增长

图5.1：项目生命周期管理

图5.2：用户增长漏斗

本章概览：运营阶段用 AI 做文档与 SEO、版本管理、用户反馈与迭代、商业化与数据分析；全流程回顾见文末「全书总结」。

5.1 项目文档与 AI 自动 SEO 持续运营

文档：README、API 文档、部署说明等均可让 AI 生成；结构要含简介、快速开始、贡献与 License。

AI 自动 SEO 与持续运营：上线后可持续用 AI 做运营，而不必天天手写。例如：用 AI 定期根据产品更新生成/改写 meta 描述、关键词、sitemap 文案；用 AI 生成博客或 Release Notes 以拉搜索与回流；结合 GitHub Actions 或定时任务，让 AI 产出「本周变更摘要」「SEO 文案建议」等。你只需设定规则与发布节奏，必要时人工审一遍再发布。

5.2 版本管理（AI 辅助）

语义化版本（MAJOR.MINOR.PATCH）与 CHANGELOG 可让 AI 根据 git log 或 PR 列表生成；发布流程可写成脚本或让 AI 生成（含 gh release create、semantic-release 等）。

5.3 用户反馈与迭代

用户调研：说「为 [项目名] 生成用户调研问卷」即可，AI 可产出使用时长、场景、改进点、付费意愿等题目；按需增删选项。

Roadmap（产品路线图）：说「根据当前功能生成 v1.1 / v1.2 规划与 CHANGELOG 要点」；版本规划、功能清单、时间线均可让 AI 生成后人工调整。

📝 课后作业：以前觉得 AI 做不到的事，现在用 AI 做到了

请分享一个你的真实经历（任选其一）：

1. ✅ 破局：以前觉得 AI 做不到（或做不好），现在用 AI 完美解决的事
2. ✅ 提效：以前需要 1 天，现在用 AI 10 分钟搞定的事
3. ✅ 创新：通过 AI 发现的全新应用场景

💡 提交方式：截图或文字描述，展示你的 AI 应用实践成果。

🙏 感谢聆听

感谢您的耐心阅读！希望本指南能帮助您建立起 AI Native 的工作模式。

欢迎与我交流心得：

📧 Email: chicogong@tencent.com

期待听到您在 AI 辅助开发实践中的经验和想法！

5.4 商业化路径

开源项目商业化策略

1. 双重许可（Dual Licensing）

• 开源版：MIT License（功能限制）
• 商业版：付费许可（完整功能）

2. 托管服务（Hosted Service）

• 提供云端托管版本
• 按使用量计费
• 免运维

3. 支持与咨询

• 企业技术支持
• 定制开发
• 培训服务

4. 赞助（GitHub Sponsors）

# .github/FUNDING.yml

github: chicogong
patreon: chicogong
open_collective: realtime-ai

5.5 运营数据分析（可选）

需要时让 AI 根据仓库数据做 Stars/留存/Issue 响应等分析并生成脚本即可，此处不展开。

全书总结

核心收获

1. AI-First 理念：任何事情先问 AI 能不能做
2. 工具矩阵：Claude Code + Cursor + MCP + Agent
3. 并行开发：git worktree + 多 AI 协作
4. 自动化一切：Hook + CI/CD + 视频剪辑
5. 全流程实践：立项 → 开发 → 部署 → 运营

关键数据

• AI 覆盖开发工作：80-90%
• 开发效率提升：3-5倍
• 100+ 真实项目经验
• 6-8万字实战指南

下一步行动

1. 配置 Claude Code（.claude/CLAUDE.md）
2. 创建第一个 AI-First 项目
3. 使用 git worktree 并行开发
4. 部署到生产环境
5. 持续迭代优化

附录 A：工具与 Prompt 速查

Claude Code 常用命令：claude / claude . 启动；claude --model sonnet 指定模型；/skills、/commit、/review-pr 为 Skill 命令；claude mcp list 查看 MCP。完整说明见正文 3.1。

Git Worktree：git worktree add ../feat-auth feature/auth 创建；git worktree list 列出；git worktree remove ../feat-auth 删除。多 Agent 并行与 AI 下 Git 用法见 第三章 3.6。

MCP 与 CLI：常用 MCP 如 Filesystem、Git、Brave Search、Context7 等，配置在 ~/.claude/mcp.json。常用 CLI：aichat、gh、jq、rg，按需安装。更多见正文 1.2。

Prompt 通用框架：[Context] + [Task] + [Constraint] + [Output]。需求分析要可行性+技术选型+MVP+风险；代码实现要完整实现+依赖+示例；代码审查要安全/性能/可维护性+修复建议；测试生成要单元测试+覆盖率 90%+、正常/异常路径、Mock 外部依赖。正文 2.1、3.1 有示例。

附录 B：故障排查

B.1 Claude Code 常见问题

B.2 依赖与环境问题