Scripta — AI 驱动的编程基础教学工具

快速开始 / Quick Start

npm install

⚠️ 不能直接用 file:// 协议打开 index.html！ 本项目依赖前端接口调用，直接双击打开或 open index.html 会导致接口无法响应。请使用以下任一方式通过 HTTP 服务器运行：

npx serve .
# 或者
python3 -m http.server 8000

然后在浏览器访问终端输出的地址（如 http://localhost:3000 或 http://localhost:8000）。

---

两种运行模式 / Two Running Modes

模式 A：Mock Server（无需 LLM，本地验证前端）

npm run mock

Mock Server 监听端口 3456，模拟 6 步引导流程。

然后启动本地文件服务器并在浏览器打开：

npx serve .

访问终端输出的地址（如 http://localhost:3000），不要直接打开 index.html，否则接口无法响应。

1. 编辑器输入文字 → 点「提交」，重复 6 次观察完整流程

Mock Server 与 Bridge Server 共用端口 3456，二者不会同时运行。

模式 B：Bridge Server — Skill Gateway（用户自带 LLM API Key）

Bridge Server v2 是 Skill Gateway：加载 W2 教学 Skill，自动组装 system prompt，用用户提供的 BYOK 凭据转发至 LLM API。

1. 创建配置文件（仅需一次）：

cp bridge-server/config.example.json bridge-server/config.local.json

config.local.json 仅配置服务端参数，不需要填 API Key 或 Model：

{
  "skill_dir": "../skills/teach",
  "port": 3456,
  "timeout_ms": 30000,
  "temperature": 0.3
}

⚠️ config.local.json 已在 .gitignore 中排除，不会被提交。

2. 启动 Bridge Server：

npm run bridge

3. 在浏览器中连接：

启动本地文件服务器：

npx serve .

访问终端输出的地址（如 http://localhost:3000），在配置面板填入你的 LLM 信息：

字段	填写内容	示例
API 端点 / Endpoint	你的 LLM API 地址	https://api.openai.com/v1/chat/completions
Model	模型名称	gpt-4o-mini
API Key	你的 API Key	sk-...

点「连接 ▶」，然后在编辑器输入文字 → 点「提交」。

配置关系 / Config Architecture

浏览器 (index.html)
  │  用户在前端配置面板输入自己的 LLM 信息:
  │    - API 端点 (e.g. https://api.openai.com/v1/chat/completions)
  │    - Model (e.g. gpt-4o-mini)
  │    - API Key (sk-...)
  │  前端自动连接本地 Bridge Server (localhost:3456)
  ▼
Bridge Server v2 — Skill Gateway (localhost:3456)
  │  config.local.json 仅含服务端配置:
  │    - skill_dir, temperature
  │  skill-loader.js 加载 W2 Skill:
  │    → system-prompt.demo.md (OPTEEG 框架)
  │    → SKILL.md (错误模式库 × 10)
  │    → 运行时配置注入
  │  组装完整 system prompt → 用用户 BYOK 凭据转发至 LLM API
  ▼
LLM API (用户自带的 Key + Endpoint + Model)

用户全程自行提供 LLM 凭据，服务端不存储任何密钥。

---

E2E 自动化测试 / E2E Automated Test

npm test

使用 Puppeteer + Mock Server 验证前端完整 6 步流程，无需 LLM API。

---

文件结构 / File Structure

├── index.html                  # 前端 HTML Shell
├── js/                         # 前端模块 (Vanilla ES Modules)
│   ├── api-bridge.js           #   fetch 封装，携带用户 LLM 配置
│   └── ...
├── mock-server.js              # Mock 服务（端口 3456，模拟 6 步流程）
├── verify-flow.test.js         # E2E 测试脚本
├── bridge-server/
│   ├── server.js               # Bridge Server v2 — Skill Gateway（端口 3456）
│   ├── skill-loader.js         # W2 Skill 加载器：解析 SKILL.md + 组装 system prompt
│   ├── config.example.json     # 配置示例（提交到仓库）
│   └── config.local.json       # 用户本地配置（.gitignore 排除）
└── docs/