karuo-ai/04_卡火（火）/火炬_全栈消息/全栈开发/SKILL.md

---
name: 全栈开发
description: 卡若AI 全栈开发（火炬）— 知己及类似项目经验 + 官网/全站开发与「开发文档 1～10」标准流程；吸收 Superpowers 实施计划粒度、TDD 推荐、两阶段评审与分支收尾。含分销、RAG、向量化；官网/全站类任务时按 1～10 调研→计划→执行→评审→复盘。**以后开发新网站一律用本 Skill 做调研与执行。** 使用手册一律按卡若AI 使用手册结构（书籍式+图文+images）生成，见开发模板 9、手册。
triggers: 全栈开发/知己项目/分销/存客宝/RAG/向量化/Next.js/知识库/卡若AI官网/官网开发/全站开发/开发文档/1～10/开发模板/官网全站/v0前端/v0生成/毛玻璃/前端规格/神射手/毛狐狸/前端标准/实施计划/两阶段评审/橙色锁/配色/API调用/使用手册
owner: 火炬
group: 火
version: "2.4"
updated: "2026-03-12"
---

# 全栈开发（火炬）

> 主责：知己类项目经验 + **官网/全站开发**与开发文档 1～10 标准流程。协同：水泉（需求拆解）、金盾（存客宝）、木果（开发模板）。  
> **约定**：以后开发网站（新站、官网、全站、数据中台等）**都用本 Skill 做调研、计划与执行**，按 1～10 与卡若AI 官网标准实施。

---

## 一、官网/全站开发与开发文档 1～10（优先）

当用户需求涉及 **官网、全站、新站、开发文档、1～10 目录** 时，按本小节执行。

### 1.1 标准结构（开发文档）

- **根目录**：仅保留一个 **README.md**，作为 1～10 索引入口；**全部文档归入 10 个目录**，不在根目录散落。
- **1～10 目录**：需求 | 架构 | 原型 | 前端 | 接口 | 后端 | 数据库 | 部署 | 手册 | 项目管理。
- **入口**：第一次用先读 `1、需求/卡若AI项目使用说明.md`（或该项目等价说明），再读 `10、项目管理/开发文档使用指引（卡若交互式）.md`。
- **手册**：使用手册**一律按卡若AI 使用手册结构**书写（书籍式：README 总目录 + 篇/章多文件 + 附录），并**图文并茂**。配图放 `9、手册/images/`，在章节内引用，并在 `images/README.md` 登记。详见 `开发模板/9、手册/使用手册生成规范_卡若AI结构.md`；入口可保留 `9、手册/使用手册（带图）.md` 作导航或单页摘要。
- **复盘**：迭代结尾用 `10、项目管理/迭代复盘模板.md`（卡若复盘格式，含 Human 3.0 反思与总结）。

### 1.2 执行流程（调研 → 计划 → 执行 → 评审 → 复盘）

1. **调研**：先读目标项目的 `开发文档/README.md` 与 `1、需求` 下项目使用说明；无则按 1～10 自建目录并补 `卡若AI项目使用说明` 级总览。
2. **需求澄清**（可选，复杂需求时）：结合火眼「智能追问」、水泉「需求拆解与计划制定」，分块展示设计或任务表供确认后再实施。
3. **实施计划**（推荐，吸收 Superpowers writing-plans）：
   - 有明确功能/迭代时，先写**实施计划**再写代码；计划存 `开发文档/10、项目管理/plans/YYYY-MM-DD-<特征名>.md`。
   - 计划须含：**Goal / Architecture / Tech Stack**；每个子任务含 **Files（Create/Modify/Test 精确路径）**、**Steps**（见下「实施计划标准」）、**具体命令与预期输出**（如测试命令与 Expected: FAIL/PASS）。
   - 执行时优先按该计划逐步执行，无计划时先按 1～10 生成计划再执行。
4. **生成/更新**：按 1～10 与「开发文档使用指引」或按实施计划逐项执行；前端按 `4、前端/前端开发流程（卡若式）.md` 与组件规格、检查清单执行；**新功能推荐 TDD**（见下）。
5. **任务/迭代评审（两阶段，吸收 Superpowers）**：单任务或迭代结束时——① **规格符合**：实现是否完全符合计划/需求，有无多做或少做；② **代码质量**：可读性、重复、魔法数等。先通过①再做②，未通过则修完再进入下一任务或复盘。
6. **验收与复盘**：用 `10、项目管理/项目落地执行表` 与 `迭代复盘模板` 更新状态并写复盘；有类似需求时**用本 Skill 做调研再生成**，避免重复造轮。
7. **分支与收尾**（大功能/实验性开发）：在独立分支或 worktree 开发；完成后跑测试、再选择合并/PR/保留/丢弃并清理（见下「分支与收尾」）。

### 1.3 参考项目（标准模板）

**卡若AI 官网** 为当前标准参考项目，新站开发时按该仓库的 1～10 与能力清单对齐。

**路径**（按用户环境替换）：

- 项目根：`/Users/karuo/Documents/开发/3、自营项目/卡若ai网站/`
- 开发文档根：`开发文档/`
- 入口：`开发文档/README.md`（1～10 索引）、`1、需求/卡若AI项目使用说明.md`
- 使用指引：`10、项目管理/开发文档使用指引（卡若交互式）.md`
- 使用手册（带图）：`9、手册/使用手册（带图）.md`
- 开发进度：`10、项目管理/开发进度.md`
- 复盘模板：`10、项目管理/迭代复盘模板.md`

**官网已具备能力（做新站时对照补齐）**：首页直接对话（免登录）、/chat 对接 LLM（平台配置 + CHAT_API_KEY）、技能/流程/任务/网关/用户/平台治理 控制台、技能同步卡若AI（skills_export.json + /api/skills/sync）、控制台技能批量启用禁用、任务/流程 inline 编辑、细粒度 RBAC（viewer/operator/admin/owner）、SQLite + 可选 Prisma/Postgres 迁移（见 `7、数据库/Prisma迁移说明.md`）、苹果毛玻璃 UI、部署脚本（如 deploy.sh → NAS）。

前端需求与内容以该仓库下 `4、前端/`（规范、页面与路由、组件规格、毛玻璃与自适应、v0 融合、检查清单）及 `3、原型/` 为准；部署以 `8、部署/` 为准。

### 1.4 实施计划标准（吸收 Superpowers writing-plans）

- **粒度**：每步 = 一个可执行动作（约 2～5 分钟）。例如：写失败测试 → 运行并确认失败 → 写最小通过实现 → 运行并确认通过 → 提交。
- **每个子任务须包含**：
  - **Files**：Create/Modify/Test 的**精确路径**（含行号区间，如 `src/foo.ts:12-20`）。
  - **Steps**：具体步骤与**完整代码片段**（非「加校验」等笼统描述）、**精确命令**（如 `npm test -- --grep "xxx"` 或 `pytest path::test_name -v`）及 **Expected**（如 FAIL with "function not defined" / PASS）。
- **计划头**：Goal（一句话）、Architecture（2～3 句）、Tech Stack；并注明执行顺序与验收标准。
- **保存路径**：`开发文档/10、项目管理/plans/YYYY-MM-DD-<特征名>.md`。

### 1.5 TDD 推荐（吸收 Superpowers test-driven-development）

- **新功能**：推荐 **RED-GREEN-REFACTOR**——先写失败测试 → 运行确认失败 → 写最小实现 → 运行确认通过 → 必要时重构 → 提交。先于测试写出的代码可删或改为在测试通过后补全。
- **遗留代码**：可逐步补测，不强制一次性全测。
- **原则**：DRY、YAGNI；频繁提交，每步可提交。

### 1.6 任务/迭代两阶段评审（吸收 Superpowers 评审纪律）

- **顺序**：先 **规格符合**（代码是否完全符合计划/需求，有无多做、少做），通过后再 **代码质量**（可读性、重复、魔法数、命名等）。
- **禁止**：在规格符合未通过前做代码质量评审；跳过任一轮审或未修完就进入下一任务/复盘。
- **落地**：在 `10、项目管理/迭代复盘模板.md` 或单任务检查清单中增加「规格符合」「代码质量」两项打勾。

### 1.7 分支与收尾（吸收 Superpowers finishing-a-development-branch）

- **大功能/实验性开发**：推荐在**独立分支**或 worktree 进行；在 `10、项目管理` 中写清分支策略（如 feature/xxx、fix/xxx）。
- **完成后**：跑全量测试 → 选择 **合并 / PR / 保留 / 丢弃** → 按需清理 worktree 或分支。
- **不强制**使用独立 worktree，但须在开发文档或复盘中标明「本迭代分支」与「收尾决定」。

### 1.8 前端（见「前端开发」Skill + 开发文档 4、前端 + v0）

官网/全站/数据中台类**前端与毛玻璃风格**统一走 **「前端开发」Skill**，不再在本 Skill 内展开前端标准全文。

**前端开发（必读）**：

| 技能/文档 | 用途 |
|:---|:---|
| **火炬「前端开发」Skill** | `04_卡火（火）/火炬_全栈消息/前端开发/SKILL.md` — 苹果毛玻璃风格、执行步骤、协同说明 |
| **`前端开发/前端标准_神射手与毛狐狸.md`** | 布局、颜色、背景、卡片、按钮、气泡、底部导航、globals.css 毛玻璃类、移动端触达；所有新前端开发以此为准 |

- 参考实现：神射手项目 `开发文档/4、前端/`、`app/globals.css`、`app/page.tsx`、`app/ClientLayout.tsx`、`app/components/Sidebar.tsx`、`BottomNav.tsx`。
- 风格要点：苹果毛玻璃、`from-slate-50 via-blue-50/30 to-purple-50/20` 渐变背景、主按钮 `from-blue-500 to-purple-500`、卡片 `bg-white/70`～`bg-white/90 backdrop-blur`、骨架屏优先、lucide-react 图标、移动端 44px 触达与底部导航。

**4、前端 必读文档（项目自带开发文档时）**：

| 文档 | 用途 |
|:---|:---|
| `4、前端/前端开发流程（卡若式）.md` | 先读再做：做首页/能力页等的顺序与验收 |
| `4、前端/各页面组件规格.md` | 每页组件（GlassCard/GlassNav）、Props、验收 |
| `4、前端/苹果毛玻璃风格与自适应规范.md` | 毛玻璃 token、断点、v0 生成后替换为 glass 类 |
| `4、前端/前端能力与v0融合.md` | v0 出稿 → 套毛玻璃/自适应 → 接数据与路由 |
| `4、前端/v0使用步骤.md` | 用 v0 生成前端的步骤：打开 v0.dev → 粘贴规格 → 生成 |
| `4、前端/v0生成用-卡若AI官网前端规格.md` | 复制「复制起点～复制终点」到 v0 输入框，生成 Next + Tailwind + shadcn + 毛玻璃 |
| `4、前端/前端开发检查清单.md` | 单页与全站验收打勾 |

**v0 前端工作流（与开发文档一致）**：

1. **出稿**：在 v0.dev 新建项目，粘贴 `v0生成用-*前端规格.md` 或**前端开发** Skill 内《前端标准_神射手与毛狐狸》中的颜色/布局/组件描述，输入「按此规格生成，Next.js + Tailwind + shadcn/ui，苹果毛玻璃，移动端自适应」。
2. **落库**：将 v0 生成代码复制到项目 `site/` 或 `frontend/`，与现有结构对齐。
3. **套规范**：把 v0 的 Card/Nav 等替换为**前端开发**内《前端标准_神射手与毛狐狸》的 `glass-card`、`glass-nav` 及类名；补全 `sm:/md:/lg:` 与触达 ≥44px。
4. **验收**：用《前端开发检查清单》或前端开发标准自检；有部署到 Vercel/v0 需求时走金盾「Vercel与v0部署流水线」Skill。

### 1.9 官网配色（橙色锁）与 API 对外调用

- **配色基准**：卡若AI 官网全站（含控制台）以 **「橙色锁」** 为统一视觉基准：主色橙（`#ea580c` / `#f97316`）、背景浅石色；控制台为 stone + 橙强调。详见官网开发文档 `4、前端/配色规范_橙色锁.md`。新站或官网迭代时，前端/控制台配色以该规范为准。
- **API 对外调用**：官网提供统一出口与多接口，**各处均可通过调用卡若AI 官网 API 实现相应功能**。主要对外接口：`POST /api/gateway/chat`（推荐，统一 LLM）、`POST /api/chat`、`GET /api/skills`、`GET /api/public/overview`、`/api/workflows`、`/api/tasks` 等；鉴权与用法见官网开发文档 `5、接口/API网关统一出口.md` 第 5 节「外部调用卡若AI 能力」。做集成或第三方调用时优先读该文档。

**协同**：Word/文档类清洗用火炬「文档清洗」；部署到 v0、同步 GitHub/Vercel 用金盾「Vercel与v0部署流水线」。

---

## 二、项目经验库（知己类，必读）

**参考路径**：`运营中枢/参考资料/项目经验库_知己与类似项目.md`

开发以下类型项目时，**优先读取**该 reference：

| 类型 | 涉及内容 |
|:---|:---|
| 分销型 | 一级 20% / 二级 10%、30 天绑定、空中分账 |
| RAG / 知识库 | OpenAI Embeddings 1536 维、MongoDB 向量、占位向量 |
| 存客宝整合 | 指定 Key、线索上报、添加好友 → 金盾 Skill |
| 多 Agent 拆分 | 板块划分、职责分离 → 水泉 Skill |

---

## 三、知己核心代码结构（速查）

```
app/           # Next.js App Router
├── api/booking, cunkebao, chat, distribution, admin
├── admin/knowledge  # 知识库管理
components/    # home-page, chat-page, distribution-page, bottom-nav
lib/
├── mongodb.ts, rag.ts, cunkebao.ts
├── distribution/   # 分销服务（绑定、佣金、提现）
├── profit-sharing/ # 空中分账
└── payment/
scripts/
├── screenshot-ui.mjs        # UI 全量截图
└── vectorize-knowledge.mjs  # 知识库向量化
```

---

## 四、分销机制（知己实现）

- **规则**：一级 20%、二级 10%；30 天绑定；7 天后结算；最低提现 10 元。
- **核心**：`lib/distribution/service.ts`、`lib/profit-sharing/service.ts`。
- **类似项目**：复制 distribution + profit-sharing，改比例与集合名。

---

## 五、AI 向量化 / RAG

- **RAG**：`lib/rag.ts`，OpenAI text-embedding-3-small 1536 维。
- **向量化脚本**：`scripts/vectorize-knowledge.mjs`。
- **未配置 Key**：使用占位向量，开发可跑通。

---

## 六、已吸收 reference 一览

| 文档/项目 | 用途 |
|:---|:---|
| 项目经验库_知己与类似项目 | 核心代码、分销、AI 向量化、经验分配 |
| 项目开发能力_来自知己 | 10 目录、端口、附件、截图、经验、复盘 |
| 项目开发中整合存客宝获客功能 | 获客型项目 + 存客宝 |
| 多Agent与板块拆分（水泉） | 业务流程 vs 开发流程、十目录界定 |
| **卡若ai网站 开发文档** | **官网/全站开发标准：1～10 结构、前端需求与内容、使用手册（带图）、提示词与执行流程；以后开发网站都用本 Skill + 该参考项目能力清单实施** |
| **火炬「前端开发」Skill** | **毛玻璃风格与前端标准；前端开发必读** |
| **前端开发/前端标准_神射手与毛狐狸** | 布局/颜色/毛玻璃/组件/特效统一标准，所有项目前端开发参考 |
| **神射手 开发文档 4、前端** | 神射手项目内前端规范、核心组件代码、截图索引 |
| **Superpowers与全栈开发对比与优化建议** | `运营中枢/参考资料/Superpowers与全栈开发对比与优化建议.md` — 计划粒度、TDD、两阶段评审、分支收尾等优化方向 |

---

*官网/全站类任务：先调研开发文档（1、需求 + 10、项目管理）→ 按 1～10 生成或更新 → 复盘。知己类：先读 项目经验库_知己与类似项目 → 按需调用协同 Skill。*

---

## 七、全栈开发流程图（v2.2，吸收 Superpowers）

流程图见：`/Users/karuo/Documents/卡若Ai的文件夹/图片/全栈开发流程_吸收Superpowers_20260216.png`（已登记于 `卡若Ai的文件夹/图片/图片索引.md`）。

**流程概要**：调研 → 需求澄清（可选）→ 实施计划（精确路径+TDD）→ 按任务执行 → 规格符合审 → 代码质量审 → 下一任务 或 验收与复盘 → 分支收尾。