# 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     自动验收
```