# 学员使用说明

你拿到的是一个可本地运行、也可部署到 Cloudflare 的 Skill 管理平台练习包。你不需要先读懂代码，也不需要自己准备开发环境。最简单的方式是打开 [START-HERE.md](START-HERE.md)，把 [AI-CODING-PROMPT.md](AI-CODING-PROMPT.md) 交给 AI Coding 工具。

## 方式一：让 AI coding 工具帮你跑

1. 解压这个 zip。
2. 用 Cursor、Codex、Claude Code、Qoder 或其他 AI coding 工具打开文件夹。
3. 打开 [AI-CODING-PROMPT.md](AI-CODING-PROMPT.md)。
4. 把里面的提示词复制给 AI coding 工具。
5. 按 AI 工具的提示授权它执行命令。

如果电脑上没有 Node.js、npm 或本地 AI CLI，AI 工具会按 [ENVIRONMENT.md](ENVIRONMENT.md) 先帮你安装，再启动服务。

AI 工具应该优先运行：

```bash
npm start
```

`npm start` 会自动识别本机已有的 Codex、Qoder、Claude Code、CodeBuddy 或 Trae，并注册为 Skill 生成、评测、运行的本地运行时。

如果你想手动指定运行时，再使用：

```bash
npm run runtime:setup -- qoder
npm run runtime:setup -- claude-code
npm run runtime:setup -- codebuddy
npm run runtime:setup -- trae
```

## 方式二：自己在终端运行

进入项目目录后执行：

```bash
npm start
```

如果提示 Node.js 版本过低或 npm 不存在，把错误信息交给 AI Coding 工具，让它按 [ENVIRONMENT.md](ENVIRONMENT.md) 处理。

## 运行成功后会看到什么

终端会输出类似：

```text
访问地址：http://localhost:4000
```

浏览器打开后进入登录页。首次填写邮箱和手机号会自动注册本地账号。

## 这个命令具体做了什么

`npm start` 会自动：

1. 检查 Node.js 版本。
2. 识别本机已有的 AI CLI，并配置本地运行时。
3. 如果没有依赖，执行 `npm ci`。
4. 初始化后端 SQLite 数据库。
5. 把 315 个流程架构节点写入数据库。
6. 构建前端页面。
7. 用后端服务同时托管 API 和前端页面。
8. 打开浏览器。

也就是说，本地部署后只需要访问一个地址。

启动后进入“智能体配置 / 运行时注册”，可以看到对应的本地 Codex/Qoder/Claude Code/CodeBuddy/Trae 运行时，并执行测试。

## 常见问题

### 1. 提示 Node.js 版本过低

安装 Node.js 22 或 24。不会安装时，把错误信息交给 AI Coding 工具，让它按 [ENVIRONMENT.md](ENVIRONMENT.md) 查官方 Node.js 文档并帮你安装。

### 2. 4000 端口被占用

脚本会自动找下一个可用端口。看终端里最终打印的访问地址即可。

### 3. 看到 SQLite experimental warning

这是 Node.js 对内置 SQLite 模块的提示，不影响本课程本地运行。

### 4. 技能列表为空

新数据库默认没有 Skill，这是正常的。你可以上传 `.md`、`.txt`、`.zip` Skill 包。

### 5. AI 创建、评测或运行不能用

先确认本机对应的 AI CLI 已安装并登录，再运行一次：

```bash
npm run runtime:setup -- codex
npm run local
```

如果命令不叫 `codex`，可以指定真实路径：

```bash
npm run runtime:setup -- codex -- --command /usr/local/bin/codex
```

云端部署时再配置 AgentRun 这类公网运行时。

### 6. 想清空本地数据

删除：

```text
cf-worker/data/
cf-worker/uploads/
```

然后重新运行：

```bash
npm run local
```

## 部署到云端

如果你有 Cloudflare 账号，或者愿意注册一个，运行：

```bash
npm run cloudflare:deploy
```

脚本会打开浏览器进行 Cloudflare 授权，并引导创建 D1、R2、Worker 和 Pages。详细说明见 [CLOUDFLARE-STUDENT.md](CLOUDFLARE-STUDENT.md)。
