# Sparkit

**Repository Path**: lzdjack/sparkit

## Basic Information

- **Project Name**: Sparkit
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: 001-sparkit-ai-product-workflow
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-15
- **Last Updated**: 2026-06-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Sparkit

[English](./README.en.md)

From spark to shipped product.

## 项目介绍

Sparkit 是一个本地优先的 AI 产品工作流平台，目标是把自然语言产品想法转化为可追溯、可审阅、可执行、可验证、可修复、可发布审批的软件交付流程。

第一版聚焦单前端仓库和人工审批闭环：用户输入想法后，Sparkit 生成 PRD、UI 线框级计划、前端任务拆解，随后驱动受控实现、测试、bug 修复循环和 release readiness 审批准备。

## 当前状态

- 当前 feature 分支：`001-sparkit-ai-product-workflow`
- 当前版本：`0.1.0`
- 产品需求源头：`specs/001-sparkit-ai-product-workflow/prd.md`
- Spec Kit 规格：`specs/001-sparkit-ai-product-workflow/spec.md`
- 实施计划：`specs/001-sparkit-ai-product-workflow/plan.md`
- 任务清单：`specs/001-sparkit-ai-product-workflow/tasks.md`

## 技术栈

- TypeScript
- React + Vite
- NestJS
- Temporal TypeScript SDK
- Prisma
- PostgreSQL
- Redis
- Docker Compose
- Vitest
- Playwright
- opencode

## Monorepo 结构

```text
apps/
├── web/       # React + Vite Web UI
├── api/       # NestJS API
└── worker/    # Temporal worker

packages/
├── shared/    # 共享类型、schema 和状态规则
├── prompts/   # AI prompt templates
└── config/    # 共享工具链配置

infra/
├── docker-compose.yml
└── temporal/

specs/
└── 001-sparkit-ai-product-workflow/
```

## 安装

### 前置条件

- Docker Desktop 或兼容 Docker runtime。
- pnpm `>=11`。
- Node.js `>=24`，用于本机运行非 Docker 命令。
- 已安装并配置至少一个 model provider 的 opencode。
- 一个用于受控 implementation run 的本地前端目标仓库。

默认开发启动走 Docker Compose。Node.js 和 pnpm 主要用于触发 package scripts、运行本机校验命令，以及后续非容器化工具链操作。

### 获取代码

```bash
git clone https://gitee.com/lzdjack/sparkit.git
cd sparkit
git checkout 001-sparkit-ai-product-workflow
```

### 配置环境

```bash
cp .env.example .env
```

常用变量：

- `WEB_PORT`: Web UI host 端口，默认 `3000`
- `API_PORT`: API host 端口，默认 `4000`
- `DATABASE_URL`: 本机非容器化数据库连接串
- `REDIS_URL`: 本机非容器化 Redis 连接串
- `TEMPORAL_ADDRESS`: Temporal 地址
- `SPARKIT_RUNTIME_DIR`: 本地运行产物目录

Docker Compose 内部服务使用容器网络名连接，例如 `postgres:5432`、`redis:6379`、`temporal:7233`。

### 一键启动

前台启动：

```bash
pnpm dev
```

后台启动：

```bash
pnpm dev:docker:detach
```

查看状态：

```bash
pnpm dev:status
```

查看日志：

```bash
pnpm dev:logs
```

停止全部本地容器：

```bash
pnpm dev:stop
```

启动后服务地址：

- Web UI: `http://localhost:3000`
- API: `http://localhost:4000`
- Temporal UI: `http://localhost:8233`
- PostgreSQL: `localhost:5432`
- Redis: `localhost:6379`
- Temporal: `localhost:7233`

## 开发

### 常用命令

```bash
pnpm dev                # Docker Compose 前台启动完整本地栈
pnpm dev:docker:detach  # Docker Compose 后台启动完整本地栈
pnpm dev:status         # 查看容器状态
pnpm dev:logs           # 跟随查看容器日志
pnpm dev:restart        # 重启 web/api/worker
pnpm dev:stop           # 停止并移除本地容器
pnpm dev:infra          # 仅启动 postgres/redis/temporal/temporal-ui
pnpm dev:infra:down     # 停止基础设施容器
pnpm db:migrate         # 运行 Prisma migration
pnpm typecheck          # TypeScript 类型检查
pnpm lint               # ESLint
pnpm test               # Vitest
pnpm test:contract      # Contract tests
pnpm test:e2e           # Playwright e2e
pnpm build              # 构建所有 workspace
```

### 开发约定

- 面向用户和产品文档默认使用简体中文。
- 代码、命令、路径、状态值、接口名和文件名保持英文或原始拼写。
- React 使用函数组件和 Hooks。
- 提交信息使用 Conventional Commits。
- 不要直接推送 `main` 或 `master`。
- 不要提交 `.env`、runtime logs、build output 或本地 IDE 配置。

## 验证

基础启动验证：

```bash
pnpm dev:docker:detach
pnpm dev:status
curl http://localhost:3000
curl http://localhost:8233
docker compose -f infra/docker-compose.yml exec -T temporal temporal --address temporal:7233 operator cluster health
```

质量门禁：

```bash
pnpm typecheck
pnpm lint
pnpm test
pnpm test:contract
pnpm test:e2e
pnpm build
```

## 部署

### 本地部署

Sparkit 当前默认通过 Docker Compose 实现本地部署：

```bash
pnpm dev:docker:detach
```

停止本地部署：

```bash
pnpm dev:stop
```

### 云端部署

云端部署应尽量复用同一套 Dockerfile 和 Compose 服务定义，保持本地和云端一致。实际部署时需要按目标环境调整：

- 镜像仓库地址和 tag。
- `WEB_PORT`、`API_PORT` 等端口暴露策略。
- 数据库、Redis、Temporal 的持久化和备份策略。
- secrets 和环境变量注入方式。
- 日志、监控和告警。
- 反向代理、TLS 和域名配置。

第一版 Sparkit 仍是本地优先 MVP，不包含自动生产发布能力。上线前必须由人工审阅 release readiness。

## Spec Kit 工作流

Sparkit 按以下顺序推进需求和实现：

```text
prd.md -> spec.md -> plan.md -> tasks.md -> implementation
```

规则：

- 所有需求变化先更新 `specs/001-sparkit-ai-product-workflow/prd.md`。
- 影响可验证行为的需求必须同步到 `spec.md`。
- `plan.md` 只能基于已确认的 PRD 和 spec。
- `tasks.md` 只能基于已确认的 plan。
- 进入实现前，任务必须能追溯到 PRD 章节和 Spec FR 编号。
- 完成任务后必须在 `tasks.md` 中将对应任务标记为 `[X]`。

## MVP 边界

- 本地优先。
- 单前端目标仓库。
- 线框级 UI 计划，不做高保真设计。
- PRD、UI 计划、任务拆解和 release readiness 都需要人工审批。
- 不做自动生产发布。
- 测试失败必须进入 bug 修复循环或人工 blocked 状态。
- AI 输出必须可审阅、可编辑、可打回、可追溯。

## 贡献

### 分支

- 从当前 feature 分支或最新集成分支创建工作分支。
- 禁止直接向 `main` 或 `master` 推送。
- 分支名称建议使用 `feature/*`、`fix/*`、`chore/*` 或 Spec Kit feature 编号。

### 需求变更

任何需求变化都必须先更新 PRD，再同步到 spec：

```text
prd.md -> spec.md -> plan.md -> tasks.md -> implementation
```

如果只是修正文档错别字或开发脚本，不需要改变产品需求，但仍应保持 quickstart、README 和 tasks 状态一致。

### 提交

提交信息使用 Conventional Commits，例如：

```text
feat: add workflow intake API
fix: correct temporal docker config
docs: update local deployment guide
chore: run local stack with docker compose
```

### 合并前检查

合并前根据改动范围运行必要检查：

```bash
pnpm typecheck
pnpm lint
pnpm test
pnpm test:contract
pnpm test:e2e
pnpm build
```

如果改动影响本地启动或部署，还需要验证：

```bash
pnpm dev:docker:detach
pnpm dev:status
pnpm dev:stop
```

### 文档与任务状态

- 完成 `tasks.md` 中的任务后，将对应任务从 `[ ]` 改为 `[X]`。
- 修改启动、部署、测试或开发流程时，同步更新 README 和 quickstart。
- 每次打版本必须更新 `CHANGELOG.md`。

## 发布与变更日志

版本号遵循 SemVer：`MAJOR.MINOR.PATCH`。

每次打版本必须更新 `CHANGELOG.md`，并把 `Unreleased` 中的内容移动到对应版本章节。发布前至少完成：

1. 更新 `CHANGELOG.md`。
2. 确认 `package.json` 中的 `version` 与发布版本一致。
3. 运行必要质量门禁。
4. 确认 release note 覆盖用户可见变化、迁移说明和已知风险。
5. 使用 Conventional Commits 提交发布变更。

## 相关文档

- `specs/001-sparkit-ai-product-workflow/prd.md`
- `specs/001-sparkit-ai-product-workflow/spec.md`
- `specs/001-sparkit-ai-product-workflow/plan.md`
- `specs/001-sparkit-ai-product-workflow/tasks.md`
- `specs/001-sparkit-ai-product-workflow/quickstart.md`
- `specs/001-sparkit-ai-product-workflow/contracts/sparkit-api.openapi.yaml`