# 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`）。

```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`

`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 节点顺序。

## 验证

```bash
npm run lint
npm run build
npm run test:acceptance
```

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

- AI 对话按序创建 Skill
- 仅通过 AI 对话编辑 Skill
- 删除 Skill 与列表刷新
- 聊天选择和实际调用 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     自动验收
```