--- 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）→ 按任务执行 → 规格符合审 → 代码质量审 → 下一任务 或 验收与复盘 → 分支收尾。