106 lines
3.2 KiB
Markdown
106 lines
3.2 KiB
Markdown
# Skill Loom
|
||
|
||
一个可直接运行的单会话 AI Skill 工作台。用户可以组合多个 Skill 发起一轮对话，也可以通过与 AI 对话，按顺序完成五个节点来创建或编辑 Skill。
|
||
|
||
## 已实现
|
||
|
||
- 单会话聊天、SQLite 持久化与首轮 AI 主题标题
|
||
- 标题编辑、会话重置（重置后标题清空）
|
||
- DeepSeek V4 Flash 流式回答
|
||
- Skill 多选、拖拽排序、标签移除与 `/` 快速提示
|
||
- 每轮由 AI 独立判断实际使用哪些已选 Skill
|
||
- 候选 Skill 与实际使用 Skill 的差异化高亮反馈
|
||
- 回答中止；中止作为本轮终态处理，并清空本轮 Skill
|
||
- SSE 事件持久化、序号去重与断线续传
|
||
- Skill 新建、AI 对话编辑、删除与列表自动刷新
|
||
- 五节点严格顺序：触发条件、输入参数、执行步骤、输出格式、约束与测试
|
||
- 已完成节点可回改，未解锁节点不可跳过
|
||
- 右侧节点内容完全只读，只能通过 AI 对话修改
|
||
- 所有节点完成后才允许保存
|
||
- AI JSON 输出经过严格结构校验、纠错重试和服务端二次约束
|
||
- 无 API Key 时自动进入可操作的本地演示模式
|
||
|
||
## 本地运行
|
||
|
||
要求 Node.js 24 或更高版本（项目使用 Node 内置的 `node:sqlite`）。
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
复制环境变量模板：
|
||
|
||
```powershell
|
||
Copy-Item .env.example .env.local
|
||
```
|
||
|
||
在 `.env.local` 中设置：
|
||
|
||
```env
|
||
DEEPSEEK_API_KEY=你的_API_Key
|
||
DEEPSEEK_MODEL=deepseek-v4-flash
|
||
DEEPSEEK_BASE_URL=https://api.deepseek.com
|
||
DATABASE_PATH=./data/skillloom.db
|
||
```
|
||
|
||
启动：
|
||
|
||
```bash
|
||
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`
|
||
|
||
主聊天采用“两步式 Run”：
|
||
|
||
1. `POST /api/chat` 幂等创建回答任务。
|
||
2. `GET /api/chat/runs/:id/stream?after=:seq` 订阅 SSE。
|
||
|
||
每个事件先写入 SQLite 并获得单调递增的 `seq`，浏览器断线后携带最后序号重连，因此不会重复拼接 token。显式中止使用独立接口，不会把普通网络断开误判为用户中止。
|
||
|
||
结构化 AI 输出经过四层保护：
|
||
|
||
1. DeepSeek JSON Output；
|
||
2. Zod `.strict()` 结构校验；
|
||
3. 校验失败后自动纠错重试一次；
|
||
4. 服务端过滤非法 Skill ID，并强制 Skill 节点顺序。
|
||
|
||
## 验证
|
||
|
||
```bash
|
||
npm run lint
|
||
npm run build
|
||
npm run test:acceptance
|
||
```
|
||
|
||
自动验收会使用独立临时 SQLite 和本地演示模型，覆盖：
|
||
|
||
- AI 对话按序创建 Skill
|
||
- 仅通过 AI 对话编辑 Skill
|
||
- 删除 Skill 与列表刷新
|
||
- 聊天选择和实际调用 Skill
|
||
- 返回是否调用及具体 Skill
|
||
- 中止作为终态
|
||
- 首轮 AI 主题标题、标题编辑与会话重置
|
||
- SSE 断线重连、事件去重和继续生成
|
||
|
||
## 主要目录
|
||
|
||
```text
|
||
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 自动验收
|
||
```
|