fnvtk/karuo-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c43de335eb52cbd283e4d8457248e6b78360f820
karuo-ai/04_卡火（火）/火炬_全栈消息/全栈开发/SKILL.md

15 KiB
Raw Blame History

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