技能派源码

技能文档

---
name: skillpie-code
description: 从源码启动 SkillPie 技能市场本地开发环境，自动完成数据库初始化、迁移、种子数据与应用启动，启动失败时自动诊断。当用户要求启动技能市场、源码启动 skillpie、拉起本地开发环境、或启动报错需排查时触发。
title: 技能派源码
category: 源码系统
---

# SkillPie Code - 技能派源码

基于技能内置的 SkillPie 技能市场源码（`skillpie/` 子目录），一键拉起本地开发环境（数据库 + 迁移 + 应用），启动失败时自动定位原因。技能完全自包含，不依赖外部目录。

目录约定：
- `{技能根目录}`：本技能所在目录（含 `SKILL.md` 与 `scripts/`）
- `skillpie/`：内置源码目录，所有启动命令的工作目录

## 技能工作流

调用 `todo_write` 工具创建待办任务：

选择路径 → 执行启动 → 验证服务 → 故障诊断

### 步骤 1：选择启动路径

根据场景选择两条路径之一：

| 场景 | 路径 | 说明 |
|------|------|------|
| 环境已初始化过、只需拉起服务 | 快速路径 | 在 `skillpie/` 目录直接执行 `sh start.sh` |
| 首次使用、或启动失败需排查 | 分步路径 | 按步骤 2 逐段执行，每步验证 |

判断依据：`skillpie/` 目录存在 `.env` 且 `node_modules` 已安装 → 快速路径；否则 → 分步路径。

### 步骤 2：分步启动（步骤1选择分步路径时执行）

工作目录：`{技能根目录}/skillpie`（含 `start.sh` 与 `package.json` 的目录）。

**2.1 环境检查**（在技能根目录执行）：

```bash
python3 scripts/diagnose.py --check-env
```

要求：Docker 已安装且 Docker Desktop 已启动、Node.js ≥ 20、pnpm 已安装。任一缺失时按脚本提示安装后重试。

**2.2 启动数据库**：

```bash
docker compose up -d
docker compose exec -T postgres pg_isready -U skillpie -d skillpie
```

容器名 `skillpie-db`，端口 `5432`，账号密码 `skillpie/skillpie`。`pg_isready` 返回 accepting connections 即就绪。

**2.3 配置与依赖**：

```bash
# .env 缺失时从 .env.release 复制
[ -f .env ] || cp .env.release .env
pnpm install
pnpm prisma generate
```

**2.4 数据库初始化**：

```bash
pnpm prisma migrate deploy   # 应用 prisma/migrations 下全部迁移
pnpm prisma:seed             # 写入种子数据（管理员账号等）
```

**2.5 启动应用**：

```bash
sh start.sh          # 后台启动，日志写入 .dev/next.log
# 或前台启动（便于观察报错）：
# pnpm dev
```

### 步骤 3：验证服务（步骤2完成后必做）

```bash
curl -sf http://localhost:3001 -o /dev/null && echo "✅ 服务就绪" || echo "❌ 服务未就绪"
```

验证通过后的可用入口：

| 入口 | 地址 |
|------|------|
| 市场首页 | http://localhost:3001 |
| 管理后台 | http://localhost:3001/admin |
| 管理账号 | `skillpie` / `skillpie`（种子数据创建，角色 SUPER） |

### 步骤 4：故障诊断（启动失败时执行）

执行诊断脚本定位原因（在技能根目录执行）：

```bash
python3 scripts/diagnose.py
```

诊断项：Docker 环境 → 数据库容器状态 → 端口 5432/3001 占用 → `.env` 完整性 → `.dev/next.log` 最近报错。

按脚本输出的修复建议处理后，回到步骤 3 重新验证。人工排查清单见 [references/troubleshooting.md](references/troubleshooting.md)。

## 停止与重启

在 `skillpie/` 目录执行：

```bash
sh stop.sh    # 停止应用（数据库容器保留运行）
sh start.sh   # 重新启动（自动清理旧进程、跳过已完成的迁移）
```

仅停数据库：`docker compose down`（数据卷保留）；彻底清库：`docker compose down -v`。

## 使用说明

```bash
# 快速启动（推荐）：进入技能内置源码目录
cd {技能根目录}/skillpie
sh start.sh

# 启动失败时诊断（在技能根目录执行）
cd {技能根目录}
python3 scripts/diagnose.py

# 查看运行日志
tail -f skillpie/.dev/next.log
```

## 错误处理

| 错误现象 | 处理动作 |
|----------|----------|
| `sh start.sh` 报依赖缺失（Docker/Node/pnpm） | 按报错提示安装对应工具后重跑 `sh start.sh` |
| 数据库启动超时 | 执行 `docker compose logs postgres` 查看原因，常见为 5432 端口被占用 |
| 开发服务器启动超时 | 执行 `python3 scripts/diagnose.py` 定位，再查 [references/troubleshooting.md](references/troubleshooting.md) |
| 迁移报历史不一致 | 执行 `pnpm prisma migrate status` 查看差异，处理方式见 troubleshooting 现象 4 |
| 诊断脚本提示源码目录不存在 | 确认技能目录下存在 `skillpie/` 源码子目录且包含 `start.sh` |

## 禁止事项

- ❌ 引用或操作技能目录之外的其他源码目录（本技能自包含，源码以 `skillpie/` 子目录为准）
- ❌ 在 `skillpie/` 目录之外执行 `docker compose` 命令（compose 文件位于 `skillpie/` 下）
- ❌ 跳过 `pnpm prisma generate` 直接启动（Prisma Client 未生成会报模块缺失）
- ❌ 修改 `prisma/schema.prisma` 后不执行 `pnpm prisma generate`
- ❌ 使用 `docker compose down -v` 清理数据卷（会丢失本地全部数据），除非用户明确要求重置数据库

使用说明

# SkillPie Code - 技能派源码

一句话拉起 SkillPie 技能市场本地开发环境：数据库、迁移、种子数据、应用全部自动就绪。技能自包含源码（`skillpie/` 子目录），无需外部代码。

## 快速使用

```bash
cd {技能根目录}/skillpie    # 进入内置源码目录
sh start.sh                 # 一键启动，访问 http://localhost:3001
sh stop.sh                  # 停止服务
```

## 工作原理

1. 检查 Docker / Node.js / pnpm 环境
2. 拉起 PostgreSQL 16 容器（skillpie-db，端口 5432）
3. 复制 `.env`、安装依赖、生成 Prisma Client
4. 应用数据库迁移 + 写入种子数据
5. 启动 Next.js 开发服务器（端口 3001）

## 启动后入口

| 入口 | 地址 |
|------|------|
| 市场首页 | http://localhost:3001 |
| 管理后台 | http://localhost:3001/admin |
| 管理账号 | skillpie / skillpie |

## 启动失败怎么办

对 Agent 说「技能市场启动失败了」，技能会运行诊断脚本自动定位（在技能根目录执行）：

```bash
python3 scripts/diagnose.py
```

诊断覆盖：Docker 环境、数据库容器、端口占用、`.env` 配置、应用日志报错。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。