ai-skill-chat/README.md

Skill Loom

一个可直接运行的单会话 AI Skill 工作台。用户可以组合多个 Skill 发起一轮对话，也可以通过与 AI 对话，按顺序完成五个节点来创建或编辑 Skill。

已实现

• 单会话聊天、SQLite 持久化与首轮 AI 主题标题
• 首屏由 Server Component 直接读取 SQLite，客户端 hydration 前即可显示工作台
• 标题编辑、会话重置（重置后标题清空）
• DeepSeek V4 Flash 流式回答
• Skill 多选、拖拽排序、标签移除与 / 快速提示
• 勾选集合绑定当前需求生命周期，直到需求完成或明确放弃
• 每轮由 AI 独立判断实际使用哪些已勾选 Skill
• 候选 Skill 与实际使用 Skill 的差异化高亮反馈
• Skill 编辑自动递增版本；进行中的需求固定使用开始时的完整快照
• 回答中止采用 SQLite 原子终态；只结束 Run，不清空需求的 Skill
• SSE 事件持久化、序号去重与断线续传
• Skill 新建、AI 对话编辑、删除与列表自动刷新
• 五节点严格顺序：触发条件、输入参数、执行步骤、输出格式、约束与测试
• 已完成节点可回改，未解锁节点不可跳过
• 右侧节点内容完全只读，只能通过 AI 对话修改
• AI 先在聊天中展示待写入提案，用户确认后才更新节点
• 所有节点完成后才允许保存
• AI JSON 输出经过严格结构校验、纠错重试和服务端二次约束
• 无 API Key 时自动进入可操作的本地演示模式

本地运行

要求 Node.js 24 或更高版本（项目使用 Node 内置的 node:sqlite）。

npm install

复制环境变量模板：

Copy-Item .env.example .env.local

在 .env.local 中设置：

DEEPSEEK_API_KEY=你的_API_Key
DEEPSEEK_MODEL=deepseek-v4-flash
DEEPSEEK_BASE_URL=https://api.deepseek.com
DATABASE_PATH=./data/skillloom.db

启动：

npm run dev

访问 http://localhost:3000。未配置 DEEPSEEK_API_KEY 时也可以完整体验 UI、Skill 创建流程、流式状态、中止和重连。

数据与流式设计

SQLite 默认写入 data/skillloom.db，包含：

• skills / skill_nodes
• conversations / messages
• chat_runs / chat_run_events

skills.version 记录可编辑版本；messages.skill_snapshots_json 保存每轮 审计快照；conversations.task_state 与 retained_skill_snapshots 保存进行中需求的生命周期和固定版本。

主聊天采用“两步式 Run”：

1. POST /api/chat 幂等创建回答任务。
2. GET /api/chat/runs/:id/stream?after=:seq 订阅 SSE。

每个事件先写入 SQLite 并获得单调递增的 seq，浏览器断线后携带最后序号重连，因此不会重复拼接 token。显式中止使用独立接口，并在同一事务中写入可见内容、用量、Skill 保留状态、终态事件和 Run 状态，避免停止请求与后台流式写入相互覆盖。

Skill 有三组彼此独立的状态：

1. 用户勾选集合：当前需求允许使用哪些 Skill；
2. 当轮使用集合：路由器从勾选集合中实际选择的子集；
3. 需求状态：active、awaiting_input、offer_pending、 complete 或 abandoned。

只有 complete 和 abandoned 会清空勾选集合。回答失败、中止或服务重启 只结束本次 Run，需求和已固定的 Skill 快照仍保留。

结构化 AI 输出经过四层保护：

1. DeepSeek JSON Output；
2. Zod .strict() 结构校验；
3. 校验失败后自动纠错重试一次；
4. 服务端过滤非法 Skill ID，并强制 Skill 节点顺序。

验证

npm run lint
npm run build
npm run test:acceptance

自动验收会使用独立临时 SQLite 和本地演示模型，覆盖：

• AI 对话按序创建 Skill
• 仅通过 AI 对话编辑 Skill
• 删除 Skill 与列表刷新
• 聊天选择和实际调用 Skill
• 返回是否调用及具体 Skill
• 多选 Skill 的需求级保留与单轮子集路由
• Skill 编辑版本递增与跨轮快照固定
• 中止内容、事件与需求状态的原子终态
• 首轮 AI 主题标题、标题编辑与会话重置
• SSE 断线重连、事件去重和继续生成

主要目录

src/
  app/api/                 API 与 SSE 路由
  components/              聊天、Skill 面板与 Builder UI
  lib/db.ts                SQLite schema 与数据访问
  lib/deepseek.ts          DeepSeek、严格 JSON 与提示词
  lib/chat-runs.ts         可恢复的聊天 Run
scripts/acceptance.mjs     自动验收