@templmf/temp-solf-lmf 0.0.43 → 0.0.45

package/ai-gateway/.env

@@ -0,0 +1,42 @@
+# ════════════════════════════════════════════
+# AI Gateway 配置文件
+# 复制为 .env 后填写实际值
+# ════════════════════════════════════════════
+
+# ── 上游模型服务（内网 Qwen）────────────────
+UPSTREAM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
+UPSTREAM_API_KEY=sk-d88521262e58456384f6a4af78f6afcc
+UPSTREAM_TIMEOUT_MS=120000
+
+# 默认模型（请求未指定 model 时使用）
+DEFAULT_MODEL=qwen3-coder-30b-a3b-instruct
+
+# 所有可用模型（逗号分隔，用于 /v1/models 接口）
+AVAILABLE_MODELS=qwen3-coder-30b-a3b-instruct,
+
+# ── 网关自身配置 ─────────────────────────────
+PORT=3000
+
+# 客户端调用网关时需要携带的 Key（逗号分隔）
+# 留空则跳过鉴权（仅开发环境）
+# 生成示例: node -e "console.log('gw-' + require('crypto').randomBytes(16).toString('hex'))"
+GATEWAY_API_KEYS=gw-4c0a15b223a012b8e5d85763def024af
+
+# ── 限流配置 ─────────────────────────────────
+RATE_LIMIT_WINDOW_MS=60000
+RATE_LIMIT_MAX_PER_CLIENT=100
+RATE_LIMIT_MAX_PER_IP=200
+
+# ── 会话配置 ─────────────────────────────────
+SESSION_TTL_MS=86400000
+MAX_HISTORY_MESSAGES=50
+MAX_CONTEXT_TOKENS=6000
+
+# ── Skill 配置 ────────────────────────────────
+SKILLS_DIR=./src/skills
+
+# ── 日志 ─────────────────────────────────────
+LOG_LEVEL=info
+
+# ── 开启 AI 筛选 ───────────────────────────────────
+USE_AI_SKILL_DETECTION=true

package/ai-gateway/README.md

@@ -0,0 +1,295 @@
+# AI Gateway
+
+内网 AI API 网关服务，兼容 OpenAI 格式，对接 Qwen 等内网模型。
+
+## 功能特性
+
+- **单一接口**：`POST /v1/chat/completions`，完全兼容 OpenAI 格式
+- **Skill 自动加载**：根据对话内容自动检测并注入对应操作规范
+- **结构化响应**：支持 JSON、Markdown、HTML、React/Vue 组件、提单表单等结构化输出
+- **Tool Use 适配**：自动处理不同模型的 function calling 差异（含 qwen3-coder）
+- **Streaming**：SSE 流式输出透传，自动过滤 qwen3 thinking block
+- **VSCode Roo 兼容**：提供 `/v1/models` 接口，可直接配置为 Roo 的 AI Provider
+
+---
+
+## 快速开始
+
+```bash
+# 1. 安装依赖
+npm install
+
+# 2. 配置环境变量
+cp .env.example .env
+# 编辑 .env，填写内网 Qwen 服务地址和 Key
+
+# 3. 启动
+npm start
+
+# 开发模式（文件变更自动重启）
+npm run dev
+```
+
+---
+
+## 环境变量说明
+
+| 变量名 | 必填 | 说明 |
+|--------|------|------|
+| `UPSTREAM_BASE_URL` | ✅ | 内网 Qwen 服务地址，如 `http://192.168.1.100:8000/v1` |
+| `UPSTREAM_API_KEY` | ✅ | 内网 Qwen 服务的 API Key |
+| `DEFAULT_MODEL` | ✅ | 默认模型名，如 `qwen2.5-72b-instruct` |
+| `GATEWAY_API_KEYS` | 推荐 | 客户端调用网关时需要的 Key，逗号分隔，留空则跳过鉴权 |
+| `AVAILABLE_MODELS` | 否 | 模型列表，逗号分隔，用于 `/v1/models` 接口 |
+| `PORT` | 否 | 监听端口，默认 `3000` |
+| `SKILLS_DIR` | 否 | Skill 文件目录，默认 `./src/skills` |
+
+---
+
+## 接口说明
+
+### POST /v1/chat/completions
+
+标准 OpenAI 格式，额外支持以下网关扩展字段：
+
+#### 网关扩展字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `response_format` | object/string | 结构化输出格式（见下方） |
+| `x_skill_override` | string/array | 手动指定加载哪些 Skill，跳过自动检测 |
+| `x_keep_thinking` | boolean | 是否保留 qwen3-coder 的 thinking block，默认 false |
+
+#### response_format 支持的类型
+
+| type | 说明 |
+|------|------|
+| `json_object` | 通用 JSON 对象 |
+| `json_schema` | 按指定 Schema 返回，需同时传 `schema` 字段 |
+| `markdown` | Markdown 文档 |
+| `html` | HTML 片段 |
+| `ticket_form` | 提单助手专用，返回 `{reply, form_draft, missing_fields, is_complete}` |
+| `react_component` | React JSX 组件代码 |
+| `vue_component` | Vue 3 SFC 代码 |
+
+#### 响应中的额外字段
+
+网关在响应体中追加 `_gateway` 字段：
+```json
+{
+  "_gateway": {
+    "request_id": "uuid",
+    "skills_loaded": ["ticket", "markdown"],
+    "model_caps": { "toolSupport": "native" },
+    "latency_ms": 320
+  }
+}
+```
+
+对于 JSON 类 `response_format`，每个 choice 额外包含：
+- `message.parsed`：已解析的 JSON 对象（直接可用，无需再 JSON.parse）
+- `message.parse_error`：解析失败时的错误信息
+
+---
+
+## 使用示例
+
+### 基础对话
+
+```bash
+curl http://localhost:3000/v1/chat/completions \
+  -H "Authorization: Bearer gw-key-abc123" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "qwen2.5-72b-instruct",
+    "messages": [{"role": "user", "content": "你好"}]
+  }'
+```
+
+### 提单助手（自动加载 ticket skill）
+
+```bash
+curl http://localhost:3000/v1/chat/completions \
+  -H "Authorization: Bearer gw-key-abc123" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [{"role": "user", "content": "我要提一个生产环境数据库连接超时的故障单"}],
+    "response_format": { "type": "ticket_form" }
+  }'
+```
+
+响应示例：
+```json
+{
+  "choices": [{
+    "message": {
+      "content": "{\"reply\":\"好的，这是一个故障单。严重程度是 P1 还是 P2？\",\"form_draft\":{\"title\":\"生产环境数据库连接超时\",\"type\":\"incident\",\"affected_system\":\"数据库\"},\"missing_fields\":[\"severity\",\"description\"],\"is_complete\":false}",
+      "parsed": {
+        "reply": "好的，这是一个故障单。严重程度是 P1 还是 P2？",
+        "form_draft": { "title": "生产环境数据库连接超时", "type": "incident" },
+        "missing_fields": ["severity", "description"],
+        "is_complete": false
+      }
+    }
+  }],
+  "_gateway": { "skills_loaded": ["ticket"], "latency_ms": 450 }
+}
+```
+
+### Markdown 文档生成
+
+```bash
+curl http://localhost:3000/v1/chat/completions \
+  -H "Authorization: Bearer gw-key-abc123" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [{"role": "user", "content": "写一份 Redis 缓存设计规范文档"}],
+    "response_format": { "type": "markdown" }
+  }'
+```
+
+### JSON Schema 结构化输出
+
+```bash
+curl http://localhost:3000/v1/chat/completions \
+  -H "Authorization: Bearer gw-key-abc123" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [{"role": "user", "content": "提取以下文本中的人名和职位：张三是产品经理，李四是工程师"}],
+    "response_format": {
+      "type": "json_schema",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "people": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": { "type": "string" },
+                "role": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }'
+```
+
+### qwen3-coder Tool Use
+
+```bash
+curl http://localhost:3000/v1/chat/completions \
+  -H "Authorization: Bearer gw-key-abc123" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "qwen3-coder",
+    "messages": [{"role": "user", "content": "查询用户 ID 为 123 的订单"}],
+    "tools": [{
+      "type": "function",
+      "function": {
+        "name": "get_orders",
+        "description": "查询用户订单",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "user_id": { "type": "string" }
+          },
+          "required": ["user_id"]
+        }
+      }
+    }]
+  }'
+```
+
+### 手动指定 Skill（跳过自动检测）
+
+```bash
+curl http://localhost:3000/v1/chat/completions \
+  -H "Authorization: Bearer gw-key-abc123" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [{"role": "user", "content": "帮我写一个登录表单"}],
+    "x_skill_override": ["react", "html"],
+    "response_format": { "type": "react_component" }
+  }'
+```
+
+### Streaming
+
+```bash
+curl http://localhost:3000/v1/chat/completions \
+  -H "Authorization: Bearer gw-key-abc123" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [{"role": "user", "content": "写一篇关于微服务架构的技术博客"}],
+    "stream": true
+  }'
+```
+
+---
+
+## VSCode Roo 配置
+
+在 Roo 的 AI Provider 配置中填写：
+
+```
+API Provider:  OpenAI Compatible
+Base URL:      http://localhost:3000/v1
+API Key:       gw-key-abc123   （GATEWAY_API_KEYS 中配置的任意一个）
+Model:         qwen2.5-72b-instruct
+```
+
+Roo 会自动请求 `/v1/models` 获取模型列表。
+
+---
+
+## Skill 文件管理
+
+在 `src/skills/` 目录下放置 `.md` 文件，文件名对应 `registry.js` 中的定义：
+
+```
+src/skills/
+  ticket.md       提单助手规范
+  markdown.md     Markdown 生成规范
+  html.md         HTML 生成规范
+  react.md        React 组件规范
+  vue.md          Vue 组件规范
+  docx.md         Word 文档生成规范（可从 docx skill 复制）
+  pptx.md         PPT 生成规范
+  xlsx.md         Excel 生成规范
+```
+
+添加新 Skill：
+1. 在 `src/skills/` 放入 `.md` 文件
+2. 在 `src/skills/registry.js` 的 `SKILL_DEFINITIONS` 中添加对应条目
+3. 重启服务，`/health` 接口会显示新 Skill 的加载状态
+
+---
+
+## 项目结构
+
+```
+ai-gateway/
+├── src/
+│   ├── index.js                 入口，路由注册，服务启动
+│   ├── middleware/
+│   │   └── auth.js              API Key 鉴权
+│   ├── routes/
+│   │   └── chat.js              POST /v1/chat/completions 核心逻辑
+│   ├── skills/
+│   │   ├── registry.js          Skill 注册表、加载器、自动检测
+│   │   ├── ticket.md            提单助手 Skill
+│   │   ├── markdown.md          Markdown Skill
+│   │   ├── html.md              HTML Skill
+│   │   ├── react.md             React Skill
+│   │   └── vue.md               Vue Skill
+│   └── utils/
+│       ├── toolAdapter.js       Tool Use 多模型适配
+│       ├── structuredResponse.js 结构化响应协议
+│       └── logger.js            日志
+├── .env.example
+├── package.json
+└── README.md
+```