seeyonjf-ai-tool 0.1.1

package/README.md

@@ -0,0 +1,107 @@
+# seeyonjf-ai-tool
+
+`seeyonjf-ai-tool` 是一个用于配置 AI 网关的 Node.js CLI。目前聚焦 `chat/completions` 模式，支持自动配置 `opencode` 的用户级配置文件。
+
+## 功能
+
+- 配置 `opencode` 使用 `seeyonjf-ai` 网关。
+- `Codex` 相关入口暂保留为提示项，待协议支持建设完成后再开放配置。
+- 写入前自动备份原配置文件。
+- 支持交互式恢复备份。
+- 配置前检查 `opencode` 和 `codex` 命令是否已在 `PATH` 中。
+- 网关基础地址由用户运行时输入，不在包内内置固定地址。
+- 纯 Node.js 标准库实现，无需安装第三方依赖。
+- 支持 Windows、macOS、Linux。
+
+## 环境要求
+
+```text
+Node.js 18+
+```
+
+## 快速使用
+
+交互式配置会先检查 `opencode` 和 `codex` 是否已安装，然后引导你选择配置对象。当前仅 `opencode` 会继续输入 chat/completions 网关基础地址和 token，并自动写入模型配置；`Codex` 相关选项会提示待协议支持建设中，不会修改配置。
+
+不安装，直接运行：
+
+```bash
+npx seeyonjf-ai-tool@latest configure
+```
+
+全局安装后运行：
+
+```bash
+npm install -g seeyonjf-ai-tool
+seeyonjf-ai-tool configure
+```
+
+仅配置 `opencode`：
+
+```bash
+npx seeyonjf-ai-tool@latest configure --tool opencode --base-url "你的网关基础地址"
+```
+
+`Codex` 暂不可配置：
+
+```bash
+npx seeyonjf-ai-tool@latest configure --tool codex --base-url "你的网关基础地址"
+```
+
+该命令只会提示待协议支持建设中，不会写入配置。
+
+恢复备份：
+
+```bash
+npx seeyonjf-ai-tool@latest restore
+```
+
+列出备份：
+
+```bash
+npx seeyonjf-ai-tool@latest list-backups
+```
+
+查看帮助：
+
+```bash
+npx seeyonjf-ai-tool@latest --help
+```
+
+## 文档
+
+- `docs/chat-completions-gateway-config.md`：手动配置和自动配置工具说明。
+- `docs/gateway-config.html`：面向用户的静态配置指南页面。
+
+## 网关地址
+
+运行配置时需要输入你的 chat/completions 网关基础地址。基础地址不要追加 `/chat/completions`，客户端会自动拼接实际请求路径。
+
+```text
+https://你的网关域名/v1/你的路径
+```
+
+支持模型：
+
+- `gpt-5.5`
+- `qwen3.7-max`
+- `deepseek-v4-pro`
+
+## 开发验证
+
+```bash
+npm run check
+npm run help
+```
+
+## 发布
+
+发布需要先设置带 publish 权限且可 bypass 2FA 的 npm token：
+
+```bash
+export NPM_TOKEN="你的 npm token"
+npm run publish:npm:dry-run
+npm run publish:npm
+```
+
+发布脚本会临时生成 `.npmrc` 使用 `NPM_TOKEN`，结束后自动删除，不会把 token 写入项目文件。

package/docs/chat-completions-gateway-config.md

@@ -0,0 +1,299 @@
+# chat/completions 网关配置说明
+
+本文说明如何在 `opencode` 和 `Codex` 中使用 AI 网关的 `chat/completions` 模式，并提供自动配置工具用于写入用户级配置文件。
+
+## 1. 网关信息
+
+chat/completions 基础地址：
+
+```text
+https://你的网关域名/v1/你的路径
+```
+
+实际请求路径通常由客户端自动拼接为：
+
+```text
+https://你的网关域名/v1/你的路径/chat/completions
+```
+
+认证方式：
+
+```http
+Authorization: Bearer <你的 chat token>
+```
+
+支持模型：
+
+| 模型 ID | 文本 | 流式 | 工具调用 | 图片 | 文件块 |
+|---|---|---|---|---|---|
+| `gpt-5.5` | 支持 | 支持 | 支持，含强制工具调用 | 支持 | 不建议，实测未读取到附件 |
+| `qwen3.7-max` | 支持 | 支持 | 自动工具调用支持，强制 `tool_choice` object 不支持 | 不支持 | 不支持 |
+| `deepseek-v4-pro` | 支持 | 支持 | 支持，含强制工具调用 | 不建议，实测模型表现为未真正看到图片 | 不建议，实测未读取到附件 |
+
+使用建议：
+
+| 场景 | 推荐模型 |
+|---|---|
+| 默认主模型 | `gpt-5.5` |
+| opencode 小模型、标题、轻量任务 | `qwen3.7-max` |
+| DeepSeek 风格推理任务 | `deepseek-v4-pro` |
+| 图片输入 | 只建议 `gpt-5.5` |
+| 文件处理 | 让工具读取文件内容后作为文本发送，不依赖 chat file block |
+
+## 2. opencode 手动配置
+
+opencode 用户级配置文件位置：
+
+| 系统 | 路径 |
+|---|---|
+| Windows | `%USERPROFILE%\.config\opencode\opencode.json` |
+| macOS/Linux | `~/.config/opencode/opencode.json` |
+
+参考配置：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "seeyonjf-ai/gpt-5.5",
+  "small_model": "seeyonjf-ai/qwen3.7-max",
+  "provider": {
+    "seeyonjf-ai": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "SeeyonJF-AI",
+      "options": {
+        "baseURL": "https://你的网关域名/v1/你的路径",
+        "apiKey": "替换为你的 chat token",
+        "timeout": false
+      },
+      "models": {
+        "gpt-5.5": {
+          "name": "gpt-5.5",
+          "tool_call": true,
+          "reasoning": true,
+          "attachment": true,
+          "modalities": {
+            "input": ["text", "image"],
+            "output": ["text"]
+          }
+        },
+        "qwen3.7-max": {
+          "name": "qwen3.7-max",
+          "tool_call": true,
+          "reasoning": true,
+          "interleaved": {
+            "field": "reasoning_content"
+          }
+        },
+        "deepseek-v4-pro": {
+          "name": "deepseek-v4-pro",
+          "tool_call": true,
+          "reasoning": true,
+          "interleaved": {
+            "field": "reasoning_content"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+关键配置项说明：
+
+| 配置项 | 说明 |
+|---|---|
+| `model` | opencode 默认模型，格式必须是 `provider/model-id` |
+| `small_model` | opencode 用于标题、摘要等轻量任务的小模型 |
+| `provider.seeyonjf-ai.npm` | 使用 OpenAI-compatible provider |
+| `provider.seeyonjf-ai.options.baseURL` | 填基础地址，不要手动追加 `/chat/completions` |
+| `provider.seeyonjf-ai.options.apiKey` | chat token |
+| `provider.seeyonjf-ai.options.timeout` | `false` 表示不限制完整请求超时，适合长任务 |
+| `models.gpt-5.5.modalities.input` | 标记 `gpt-5.5` 支持文本和图片输入 |
+| `interleaved.field` | 告诉客户端推理内容字段是 `reasoning_content` |
+
+注意事项：
+
+| 项目 | 说明 |
+|---|---|
+| 配置生效 | 修改 `opencode.json` 后需要重启 opencode |
+| 图片 | 只建议使用 `gpt-5.5` |
+| 文件 | 不建议依赖模型附件能力，优先让 opencode 读取文件后作为文本上下文发送 |
+| token 安全 | 不建议把带 token 的配置文件提交到 Git 仓库 |
+
+## 3. Codex 手动配置
+
+Codex 用户级配置文件位置：
+
+| 系统 | 路径 |
+|---|---|
+| Windows | `%USERPROFILE%\.codex\config.toml` |
+| macOS/Linux | `~/.codex/config.toml` |
+
+chat/completions 模式参考配置：
+
+```toml
+model = "gpt-5.5"
+model_provider = "seeyonjf-ai"
+
+[model_providers.seeyonjf-ai]
+name = "SeeyonJF-AI"
+base_url = "https://你的网关域名/v1/你的路径"
+wire_api = "chat"
+experimental_bearer_token = "替换为你的 chat token"
+```
+
+关键配置项说明：
+
+| 配置项 | 说明 |
+|---|---|
+| `model` | Codex 默认模型 ID，使用网关支持的模型 ID |
+| `model_provider` | 指向下方 `[model_providers.<name>]` 的 provider 名称 |
+| `base_url` | 填基础地址，不要追加 `/chat/completions` |
+| `wire_api` | 这里必须使用 `chat`，表示按 Chat Completions 协议请求 |
+| `experimental_bearer_token` | 用 Bearer token 认证，等价于 `Authorization: Bearer <token>` |
+
+Codex 下的模型建议：
+
+| 模型 | 建议 |
+|---|---|
+| `gpt-5.5` | chat 模式下最稳，推荐默认使用 |
+| `deepseek-v4-pro` | 可作为备用推理模型，但不建议处理图片/附件 |
+| `qwen3.7-max` | 可做普通问答或轻量任务，不建议作为 Codex 主力 Agent 模型 |
+
+如果希望把 token 放到环境变量中，需要确认本机 Codex 版本支持 `env_key`。支持时可改成：
+
+```toml
+model = "gpt-5.5"
+model_provider = "seeyonjf-ai"
+
+[model_providers.seeyonjf-ai]
+name = "SeeyonJF-AI"
+base_url = "https://你的网关域名/v1/你的路径"
+wire_api = "chat"
+env_key = "SEEYONJF_AI_CHAT_TOKEN"
+```
+
+启动前设置环境变量：
+
+Windows PowerShell：
+
+```powershell
+$env:SEEYONJF_AI_CHAT_TOKEN = "你的 chat token"
+codex
+```
+
+macOS/Linux：
+
+```bash
+export SEEYONJF_AI_CHAT_TOKEN="你的 chat token"
+codex
+```
+
+## 4. 自动配置工具
+
+包名：
+
+```text
+seeyonjf-ai-tool
+```
+
+该工具会完成：
+
+| 功能 | 说明 |
+|---|---|
+| 环境检查 | 配置前检查 `opencode` 和 `codex` 命令是否已在 `PATH` 中 |
+| 选择工具 | 当前支持配置 `opencode`；`codex` 和同时配置两者会提示待协议支持建设中 |
+| 输入网关 | 交互输入或通过 `--base-url` 传入 chat/completions 网关基础地址 |
+| 输入 token | 交互输入或通过 `--key` 传入网关 token |
+| 写入配置 | 自动写入用户级配置文件 |
+| 自动备份 | 写入前备份源配置文件，备份名为 `.bak-时间戳` |
+| 恢复配置 | 支持通过 `restore` 子命令交互恢复备份 |
+| 跨平台 | 使用 Node.js 标准库实现，支持 Windows、macOS、Linux |
+
+运行要求：
+
+```text
+Node.js 18+
+```
+
+交互式运行：
+
+```bash
+npx seeyonjf-ai-tool@latest configure
+```
+
+全局安装后运行：
+
+```bash
+npm install -g seeyonjf-ai-tool
+seeyonjf-ai-tool configure
+```
+
+非交互式配置 opencode：
+
+```bash
+npx seeyonjf-ai-tool@latest configure --tool opencode --base-url "https://你的网关域名/v1/你的路径"
+```
+
+Codex 暂不可配置：
+
+```bash
+npx seeyonjf-ai-tool@latest configure --tool codex --base-url "https://你的网关域名/v1/你的路径"
+```
+
+该命令只会提示待协议支持建设中，不会写入配置。
+
+同时配置两者暂不可用：
+
+```bash
+npx seeyonjf-ai-tool@latest configure --tool both --base-url "https://你的网关域名/v1/你的路径"
+```
+
+该命令包含 Codex，也只会提示待协议支持建设中，不会写入配置。
+
+指定默认模型：
+
+```bash
+npx seeyonjf-ai-tool@latest configure --tool opencode --base-url "https://你的网关域名/v1/你的路径" --model gpt-5.5 --small-model qwen3.7-max
+```
+
+查看帮助：
+
+```bash
+npx seeyonjf-ai-tool@latest --help
+```
+
+恢复备份：
+
+```bash
+npx seeyonjf-ai-tool@latest restore
+```
+
+列出备份：
+
+```bash
+npx seeyonjf-ai-tool@latest list-backups
+```
+
+手动恢复方式：
+
+| 工具 | 原配置 | 备份文件格式 |
+|---|---|---|
+| opencode | `~/.config/opencode/opencode.json` | `opencode.json.bak-YYYYMMDD-HHMMSS` |
+| Codex | `~/.codex/config.toml` | `config.toml.bak-YYYYMMDD-HHMMSS` |
+
+把对应备份文件复制回原配置路径即可恢复。
+
+## 5. 兼容性建议
+
+推荐把工具设计为跨平台 Node.js CLI，而不是只支持 Windows。
+
+原因：
+
+| 方案 | 评价 |
+|---|---|
+| 只做 Windows `.bat`/PowerShell | Windows 用户方便，但 macOS/Linux 不能复用 |
+| 做 Node.js CLI | Windows、macOS、Linux 都可执行，维护成本低 |
+| 打包成 exe | 对非技术用户友好，但发布和杀软误报处理成本更高 |
+
+当前脚本是纯 Node.js 标准库实现，不依赖 npm install，适合先作为内部配置工具使用。后续如需面向普通用户分发，可以再增加 npm 发布配置或使用 `pkg`/`nexe` 打包。

package/docs/gateway-config.html

@@ -0,0 +1,487 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>SeeyonJF-AI 网关配置指南</title>
+  <style>
+    :root {
+      --bg: #f7f3ea;
+      --panel: #fffaf1;
+      --panel-strong: #f0e6d6;
+      --text: #221f1a;
+      --muted: #6f6659;
+      --line: #ded2c1;
+      --accent: #c96442;
+      --accent-dark: #9c4329;
+      --ok: #367a55;
+      --warn: #9b6a1d;
+      --code: #2d2923;
+      --code-bg: #eee5d7;
+      --shadow: 0 24px 80px rgba(59, 42, 24, 0.12);
+    }
+
+    * { box-sizing: border-box; }
+
+    body {
+      margin: 0;
+      color: var(--text);
+      background:
+        radial-gradient(circle at 15% 0%, rgba(201, 100, 66, 0.16), transparent 34rem),
+        radial-gradient(circle at 90% 10%, rgba(95, 72, 46, 0.10), transparent 28rem),
+        var(--bg);
+      font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      line-height: 1.65;
+    }
+
+    .page {
+      width: min(1120px, calc(100% - 40px));
+      margin: 0 auto;
+      padding: 48px 0 72px;
+    }
+
+    .hero {
+      margin-bottom: 28px;
+    }
+
+    .hero-card, .card {
+      background: rgba(255, 250, 241, 0.86);
+      border: 1px solid rgba(222, 210, 193, 0.9);
+      border-radius: 24px;
+      box-shadow: var(--shadow);
+      backdrop-filter: blur(16px);
+    }
+
+    .hero-card { padding: 36px; }
+    .card { padding: 28px; margin-top: 22px; }
+
+    .eyebrow {
+      display: inline-flex;
+      align-items: center;
+      gap: 8px;
+      margin-bottom: 16px;
+      padding: 6px 10px;
+      border: 1px solid var(--line);
+      border-radius: 999px;
+      color: var(--accent-dark);
+      background: rgba(240, 230, 214, 0.74);
+      font-size: 13px;
+      font-weight: 650;
+    }
+
+    h1, h2, h3 { line-height: 1.16; margin: 0; letter-spacing: -0.03em; }
+    h1 { max-width: 720px; font-size: clamp(38px, 6vw, 72px); }
+    h2 { font-size: clamp(26px, 3vw, 38px); }
+    h3 { font-size: 19px; margin-bottom: 10px; }
+
+    .lead {
+      max-width: 920px;
+      margin: 20px 0 0;
+      color: var(--muted);
+      font-size: 18px;
+    }
+
+    .aside {
+      padding: 26px;
+      display: flex;
+      flex-direction: column;
+      justify-content: space-between;
+      gap: 18px;
+    }
+
+    .meta-grid {
+      display: grid;
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+      gap: 12px;
+      margin-top: 26px;
+    }
+
+    .meta {
+      padding: 14px;
+      border: 1px solid var(--line);
+      border-radius: 16px;
+      background: rgba(255, 255, 255, 0.34);
+    }
+
+    .meta span, .label {
+      display: block;
+      margin-bottom: 5px;
+      color: var(--muted);
+      font-size: 12px;
+      font-weight: 700;
+      letter-spacing: 0.05em;
+      text-transform: uppercase;
+    }
+
+    .meta strong { font-size: 15px; }
+
+    .notice {
+      padding: 16px 18px;
+      border: 1px solid rgba(155, 106, 29, 0.35);
+      border-radius: 18px;
+      background: rgba(255, 245, 218, 0.78);
+      color: #5d4218;
+    }
+
+    .notice strong { color: #442f0f; }
+
+    .gateway-box {
+      display: grid;
+      grid-template-columns: minmax(0, 1fr) auto;
+      gap: 12px;
+      align-items: center;
+      margin-top: 16px;
+      padding: 14px;
+      border: 1px solid var(--line);
+      border-radius: 18px;
+      background: #fffdf7;
+    }
+
+    code, pre {
+      font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace;
+    }
+
+    code {
+      color: var(--code);
+      background: var(--code-bg);
+      border-radius: 7px;
+      padding: 2px 6px;
+      font-size: 0.92em;
+    }
+
+    pre {
+      overflow-x: auto;
+      margin: 14px 0 0;
+      padding: 18px;
+      color: #f7efe2;
+      background: #2f2921;
+      border-radius: 18px;
+      font-size: 13px;
+      line-height: 1.55;
+      white-space: pre;
+    }
+
+    .copy-row {
+      position: relative;
+    }
+
+    .copy-row .copy {
+      position: absolute;
+      top: 12px;
+      right: 12px;
+    }
+
+    button.copy {
+      border: 1px solid rgba(156, 67, 41, 0.25);
+      border-radius: 999px;
+      padding: 8px 12px;
+      color: #fff;
+      background: var(--accent);
+      cursor: pointer;
+      font-weight: 700;
+      transition: transform 0.15s ease, background 0.15s ease;
+    }
+
+    button.copy:hover { background: var(--accent-dark); transform: translateY(-1px); }
+    button.copy:focus-visible { outline: 3px solid rgba(201, 100, 66, 0.28); outline-offset: 2px; }
+
+    .section-title {
+      display: flex;
+      align-items: flex-end;
+      justify-content: space-between;
+      gap: 16px;
+      margin-bottom: 16px;
+    }
+
+    .section-title p {
+      max-width: 900px;
+      margin: 0;
+      color: var(--muted);
+    }
+
+    .steps {
+      display: grid;
+      grid-template-columns: repeat(3, minmax(0, 1fr));
+      gap: 14px;
+      margin-top: 18px;
+    }
+
+    .step {
+      padding: 18px;
+      border: 1px solid var(--line);
+      border-radius: 18px;
+      background: rgba(255, 255, 255, 0.42);
+    }
+
+    .step-num {
+      display: inline-grid;
+      width: 28px;
+      height: 28px;
+      place-items: center;
+      margin-bottom: 12px;
+      border-radius: 50%;
+      color: #fff;
+      background: var(--accent);
+      font-size: 13px;
+      font-weight: 800;
+    }
+
+    .two-col {
+      display: grid;
+      grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+      gap: 18px;
+      margin-top: 18px;
+    }
+
+    ul { margin: 12px 0 0; padding-left: 20px; }
+    li + li { margin-top: 8px; }
+
+    .pill-list {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 10px;
+      margin-top: 16px;
+    }
+
+    .pill {
+      padding: 7px 10px;
+      border: 1px solid var(--line);
+      border-radius: 999px;
+      background: rgba(255, 255, 255, 0.45);
+      font-size: 13px;
+      font-weight: 700;
+    }
+
+    .status {
+      display: inline-flex;
+      align-items: center;
+      gap: 8px;
+      color: var(--warn);
+      font-weight: 800;
+    }
+
+    .footer {
+      margin-top: 32px;
+      color: var(--muted);
+      font-size: 13px;
+      text-align: center;
+    }
+
+    @media (max-width: 860px) {
+      .page { width: min(100% - 24px, 1120px); padding-top: 24px; }
+      .two-col, .steps { grid-template-columns: 1fr; }
+      .hero-card, .card, .aside { padding: 22px; border-radius: 20px; }
+      .meta-grid { grid-template-columns: 1fr; }
+      .gateway-box { grid-template-columns: 1fr; }
+      .copy-row .copy { position: static; margin-top: 10px; }
+      pre { font-size: 12px; }
+    }
+  </style>
+</head>
+<body>
+  <main class="page">
+    <section class="hero">
+      <div class="hero-card">
+        <div class="eyebrow">SeeyonJF-AI Gateway</div>
+        <h1>AI 服务网关配置指南</h1>
+        <p class="lead">当前网关聚焦 <code>chat/completions</code> 模式，面向AI工具提供统一的模型访问入口。</p>
+        <div class="meta-grid">
+          <div class="meta"><span>当前协议</span><strong>OpenAI-compatible chat/completions</strong></div>
+          <div class="meta"><span>支持模型</span><strong>gpt-5.5 / qwen3.7-max / deepseek-v4-pro</strong></div>
+          <div class="meta"><span>后续规划</span><strong>Codex / Claude Code 协议适配</strong></div>
+        </div>
+        <div style="margin-top: 22px;">
+          <span class="label">网关基础地址</span>
+          <div class="copy-row">
+            <button class="copy" data-copy-target="gateway-url">复制地址</button>
+            <pre id="gateway-url">https://aigateway.edgecloudapp.com/v1/a9b63c35216bb24537b1644f64957654/seeyonkekai-chat</pre>
+          </div>
+          <p style="margin: 10px 0 0; color: var(--muted); font-size: 13px;">基础地址不要追加 <code>/chat/completions</code>，客户端会自动拼接实际请求路径。</p>
+        </div>
+      </div>
+
+    </section>
+
+    <section class="card">
+      <div class="section-title">
+        <div>
+          <h2>防泄漏提醒</h2>
+          <p>配置过程中会涉及网关地址和认证 key，请区分可共享信息和敏感信息。</p>
+        </div>
+      </div>
+      <div class="notice">
+        <strong>不要把认证 key 粘贴到公开仓库、Issue、聊天截图或共享文档。</strong><br>
+        网关地址可用于配置说明；认证 key 必须联系平台管理员或业务负责人单独获取、单独保管。如需分享配置说明，请使用占位符 <code>&lt;你的认证 key&gt;</code>，不要包含真实 key。
+      </div>
+    </section>
+
+    <section class="card">
+      <div class="section-title">
+        <div>
+          <h2>方式一：使用工具自动配置</h2>
+          <p>适合大多数用户。工具会先检查环境，再引导输入网关地址和认证 key，并在写入前备份原配置。</p>
+        </div>
+      </div>
+
+      <div class="copy-row">
+        <button class="copy" data-copy-target="auto-command">复制命令</button>
+        <pre id="auto-command">npx --registry https://registry.npmjs.org/ seeyonjf-ai-tool@latest configure</pre>
+      </div>
+
+      <div class="steps">
+        <div class="step">
+          <div class="step-num">1</div>
+          <h3>选择工具</h3>
+          <p>当前请选择 <code>opencode</code>。<code>Codex</code> 和 <code>Claude Code</code> 因协议差异，待网关侧协议支持完善后开放。</p>
+        </div>
+        <div class="step">
+          <div class="step-num">2</div>
+          <h3>填写网关地址</h3>
+          <p>输入页面上方的网关基础地址，不要追加 <code>/chat/completions</code>。</p>
+        </div>
+        <div class="step">
+          <div class="step-num">3</div>
+          <h3>填写认证 key</h3>
+          <p>认证 key 请联系平台管理员或业务负责人获取。工具会写入本机用户配置文件，请勿提交到代码仓库。</p>
+        </div>
+      </div>
+    </section>
+
+    <section class="card">
+      <div class="section-title">
+        <div>
+          <h2>方式二：把协议说明交给工具处理</h2>
+          <p>如果你使用的 AI 工具支持读取本地配置并理解 OpenAI-compatible chat/completions 协议，可以复制下面这段通用说明，让工具分析自身配置方式并完成配置。认证 key 请单独输入，不要写进共享文本。</p>
+        </div>
+      </div>
+
+      <div class="copy-row">
+        <button class="copy" data-copy-target="prompt-template">复制说明</button>
+        <pre id="prompt-template">请根据当前工具自身的配置机制，帮我接入 SeeyonJF-AI 网关。
+
+请先判断当前工具是否支持 OpenAI-compatible chat/completions 协议，或者是否支持 OpenAI-compatible provider/baseURL/apiKey 形式的配置。若支持，请完成配置；若不支持，请明确说明原因，不要强行写入错误配置。
+
+关键信息如下：
+- 协议：OpenAI-compatible chat/completions
+- provider id：seeyonjf-ai
+- provider 显示名：SeeyonJF-AI
+- 网关基础地址：https://aigateway.edgecloudapp.com/v1/a9b63c35216bb24537b1644f64957654/seeyonkekai-chat
+- 默认模型：gpt-5.5
+- 小模型/轻量任务模型：qwen3.7-max
+- 其他可用模型：qwen3.7-max、deepseek-v4-pro
+- 请求路径说明：配置时填写基础地址，不要手动追加 /chat/completions
+
+安全要求：
+- 认证 key 请单独向我询问，不要写入任何仓库、文档、日志或共享文件。
+- 写入用户配置文件前请先备份原配置。
+- 只修改当前工具所需的用户级配置，不要改动项目源码。
+- 配置完成后提醒我重启或重新打开对应工具，使配置生效。</pre>
+      </div>
+    </section>
+
+    <section class="card">
+      <div class="section-title">
+        <div>
+          <h2>opencode 配置示例</h2>
+          <p>以下为参考示例。请把 <code>baseURL</code> 替换为实际网关基础地址，把 <code>apiKey</code> 替换为你单独获取的认证 key。</p>
+        </div>
+      </div>
+
+      <div class="copy-row">
+        <button class="copy" data-copy-target="opencode-json">复制示例</button>
+        <pre id="opencode-json">{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "seeyonjf-ai/gpt-5.5",
+  "small_model": "seeyonjf-ai/qwen3.7-max",
+  "provider": {
+    "seeyonjf-ai": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "SeeyonJF-AI",
+      "options": {
+        "baseURL": "https://你的网关域名/v1/你的路径",
+        "apiKey": "替换为你的认证 key",
+        "timeout": false
+      },
+      "models": {
+        "gpt-5.5": {
+          "name": "gpt-5.5",
+          "tool_call": true,
+          "reasoning": true,
+          "attachment": true,
+          "modalities": {
+            "input": ["text", "image"],
+            "output": ["text"]
+          }
+        },
+        "qwen3.7-max": {
+          "name": "qwen3.7-max",
+          "tool_call": true,
+          "reasoning": true,
+          "interleaved": {
+            "field": "reasoning_content"
+          }
+        },
+        "deepseek-v4-pro": {
+          "name": "deepseek-v4-pro",
+          "tool_call": true,
+          "reasoning": true,
+          "interleaved": {
+            "field": "reasoning_content"
+          }
+        }
+      }
+    }
+  }
+}</pre>
+      </div>
+    </section>
+
+    <section class="card">
+      <div class="section-title">
+        <div>
+          <h2>协议支持状态</h2>
+          <p>不同工具依赖的协议不同，当前只开放已验证的 chat/completions 配置能力。</p>
+        </div>
+      </div>
+      <div class="two-col">
+        <div class="step">
+          <h3>当前可用</h3>
+          <div class="pill-list">
+            <span class="pill">chat/completions</span>
+            <span class="pill">OpenAI-compatible</span>
+          </div>
+        </div>
+        <div class="step">
+          <h3>建设中</h3>
+          <p class="status">Codex / Claude Code 待协议支持完善</p>
+          <p>Codex 当前不再适配本工具现有的 chat 配置方式；Claude Code 需要 Anthropic Messages 等协议能力。待网关侧协议建设完成后再开放自动配置。</p>
+        </div>
+      </div>
+    </section>
+
+    <p class="footer">SeeyonJF-AI Gateway · 请妥善保管认证 key，配置文件仅保存在本机用户目录。</p>
+  </main>
+
+  <script>
+    const buttons = document.querySelectorAll("[data-copy-target]");
+    for (const button of buttons) {
+      button.addEventListener("click", async () => {
+        const target = document.getElementById(button.dataset.copyTarget);
+        const text = target ? target.innerText.trim() : "";
+        try {
+          await navigator.clipboard.writeText(text);
+          const previous = button.textContent;
+          button.textContent = "已复制";
+          setTimeout(() => { button.textContent = previous; }, 1400);
+        } catch {
+          const range = document.createRange();
+          range.selectNodeContents(target);
+          const selection = window.getSelection();
+          selection.removeAllRanges();
+          selection.addRange(range);
+        }
+      });
+    }
+  </script>
+</body>
+</html>

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "seeyonjf-ai-tool",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "SeeyonJF-AI chat/completions gateway configuration helper for opencode and Codex.",
+  "bin": {
+    "seeyonjf-ai-tool": "tools/configure-chat-gateway.mjs"
+  },
+  "files": [
+    "README.md",
+    "docs/chat-completions-gateway-config.md",
+    "docs/gateway-config.html",
+    "tools/configure-chat-gateway.mjs"
+  ],
+  "scripts": {
+    "configure": "node tools/configure-chat-gateway.mjs configure",
+    "check": "node --check tools/configure-chat-gateway.mjs",
+    "help": "node tools/configure-chat-gateway.mjs --help",
+    "publish:npm": "node tools/publish-npm.mjs",
+    "publish:npm:dry-run": "node tools/publish-npm.mjs --dry-run"
+  },
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/tools/configure-chat-gateway.mjs

@@ -0,0 +1,470 @@
+#!/usr/bin/env node
+
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import * as readline from "node:readline/promises"
+import { stdin as input, stdout as output } from "node:process"
+
+const CHAT_MODELS = ["gpt-5.5", "qwen3.7-max", "deepseek-v4-pro"]
+const DEFAULT_MODEL = "gpt-5.5"
+const DEFAULT_SMALL_MODEL = "qwen3.7-max"
+const PROVIDER_ID = "seeyonjf-ai"
+const PACKAGE_NAME = "seeyonjf-ai-tool"
+
+const args = process.argv.slice(2)
+const colorEnabled = Boolean(output.isTTY && !process.env.NO_COLOR)
+
+function color(code, text) {
+  return colorEnabled ? `\x1b[${code}m${text}\x1b[0m` : text
+}
+
+const ui = {
+  title: (text) => color("1;36", text),
+  info: (text) => color("36", text),
+  success: (text) => color("32", text),
+  warning: (text) => color("33", text),
+  error: (text) => color("31", text),
+  muted: (text) => color("2", text),
+  value: (text) => color("1", text),
+}
+
+function section(title) {
+  output.write(`${ui.title(`== ${title} ==`)}\n`)
+}
+
+function usage() {
+  return `SeeyonJF-AI chat/completions 网关配置工具
+
+用法:
+  seeyonjf-ai-tool configure
+  seeyonjf-ai-tool configure --tool opencode --base-url <url>
+  seeyonjf-ai-tool restore
+  seeyonjf-ai-tool list-backups
+
+npx 用法:
+  npx ${PACKAGE_NAME}@latest configure
+  npx ${PACKAGE_NAME}@latest configure --tool opencode --base-url <url>
+
+选项:
+  --tool <opencode|codex|both>   需要配置的工具；codex/both 待协议支持建设中
+  --base-url <url>               chat/completions 网关基础地址，不要追加 /chat/completions
+  --key <token>                  chat/completions 网关 token
+  --model <model>                默认模型，默认 ${DEFAULT_MODEL}
+  --small-model <model>          opencode small_model，默认 ${DEFAULT_SMALL_MODEL}
+  --help                         显示帮助
+  --version                      显示版本
+
+支持模型:
+  ${CHAT_MODELS.join(", ")}
+`
+}
+
+function parseArgs(argv) {
+  const parsed = { command: "configure" }
+  let start = 0
+  if (argv[0] && !argv[0].startsWith("-")) {
+    parsed.command = argv[0]
+    start = 1
+  }
+  for (let i = start; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === "--help" || arg === "-h") parsed.help = true
+    else if (arg === "--version" || arg === "-v") parsed.version = true
+    else if (arg === "--tool") parsed.tool = argv[++i]
+    else if (arg === "--base-url") parsed.baseUrl = argv[++i]
+    else if (arg === "--key") parsed.key = argv[++i]
+    else if (arg === "--model") parsed.model = argv[++i]
+    else if (arg === "--small-model") parsed.smallModel = argv[++i]
+    else throw new Error(`未知参数: ${arg}`)
+  }
+  return parsed
+}
+
+function packageVersion() {
+  const packagePath = new URL("../package.json", import.meta.url)
+  const raw = fs.readFileSync(packagePath, "utf8")
+  return JSON.parse(raw).version
+}
+
+function configPaths() {
+  return {
+    opencode: path.join(os.homedir(), ".config", "opencode", "opencode.json"),
+    codex: path.join(os.homedir(), ".codex", "config.toml"),
+  }
+}
+
+function ensureDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+}
+
+function commandExists(command) {
+  const pathValue = process.env.PATH ?? ""
+  const pathExts = process.platform === "win32"
+    ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")
+    : [""]
+  for (const dir of pathValue.split(path.delimiter)) {
+    if (!dir) continue
+    for (const ext of pathExts) {
+      const commandPath = path.join(dir, `${command}${ext}`)
+      try {
+        fs.accessSync(commandPath, fs.constants.X_OK)
+        return commandPath
+      } catch {
+        // Continue searching other PATH entries.
+      }
+    }
+  }
+  return null
+}
+
+function checkTools() {
+  return {
+    opencode: commandExists("opencode"),
+    codex: commandExists("codex"),
+  }
+}
+
+function printToolCheck(tools) {
+  section("环境检查")
+  for (const [tool, commandPath] of Object.entries(tools)) {
+    if (commandPath) output.write(`${ui.success("✓")} ${tool}: 已安装 ${ui.muted(`(${commandPath})`)}\n`)
+    else output.write(`${ui.warning("!")} ${tool}: 未在 PATH 中找到，仍可先写入配置。\n`)
+  }
+  output.write("\n")
+}
+
+function timestamp() {
+  const date = new Date()
+  const pad = (value) => String(value).padStart(2, "0")
+  return [
+    date.getFullYear(),
+    pad(date.getMonth() + 1),
+    pad(date.getDate()),
+    "-",
+    pad(date.getHours()),
+    pad(date.getMinutes()),
+    pad(date.getSeconds()),
+  ].join("")
+}
+
+function backupFile(filePath) {
+  if (!fs.existsSync(filePath)) return null
+  const backupPath = `${filePath}.bak-${timestamp()}`
+  fs.copyFileSync(filePath, backupPath)
+  return backupPath
+}
+
+function readJsonIfExists(filePath) {
+  if (!fs.existsSync(filePath)) return {}
+  const raw = fs.readFileSync(filePath, "utf8").trim()
+  if (!raw) return {}
+  try {
+    return JSON.parse(raw)
+  } catch (error) {
+    throw new Error(`${filePath} 不是有效 JSON，已停止写入。请先修复或手动备份后重试。\n${error.message}`)
+  }
+}
+
+function mergeOpenCodeConfig(existing, token, baseUrl, model, smallModel) {
+  return {
+    ...existing,
+    $schema: existing.$schema ?? "https://opencode.ai/config.json",
+    model: `${PROVIDER_ID}/${model}`,
+    small_model: `${PROVIDER_ID}/${smallModel}`,
+    provider: {
+      ...(existing.provider ?? {}),
+      [PROVIDER_ID]: {
+        ...((existing.provider ?? {})[PROVIDER_ID] ?? {}),
+        npm: "@ai-sdk/openai-compatible",
+        name: "SeeyonJF-AI",
+        options: {
+          ...(((existing.provider ?? {})[PROVIDER_ID] ?? {}).options ?? {}),
+          baseURL: baseUrl,
+          apiKey: token,
+          timeout: false,
+        },
+        models: {
+          ...((((existing.provider ?? {})[PROVIDER_ID] ?? {}).models) ?? {}),
+          "gpt-5.5": {
+            name: "gpt-5.5",
+            tool_call: true,
+            reasoning: true,
+            attachment: true,
+            modalities: {
+              input: ["text", "image"],
+              output: ["text"],
+            },
+          },
+          "qwen3.7-max": {
+            name: "qwen3.7-max",
+            tool_call: true,
+            reasoning: true,
+            interleaved: {
+              field: "reasoning_content",
+            },
+          },
+          "deepseek-v4-pro": {
+            name: "deepseek-v4-pro",
+            tool_call: true,
+            reasoning: true,
+            interleaved: {
+              field: "reasoning_content",
+            },
+          },
+        },
+      },
+    },
+  }
+}
+
+function configureOpenCode(token, baseUrl, model, smallModel) {
+  const filePath = configPaths().opencode
+  ensureDir(filePath)
+  const backupPath = backupFile(filePath)
+  const existing = readJsonIfExists(filePath)
+  const next = mergeOpenCodeConfig(existing, token, baseUrl, model, smallModel)
+  fs.writeFileSync(filePath, `${JSON.stringify(next, null, 2)}\n`, "utf8")
+  return { filePath, backupPath }
+}
+
+function tomlString(value) {
+  return JSON.stringify(value)
+}
+
+function stripManagedCodexBlock(raw) {
+  const begin = "# >>> seeyonjf-ai managed >>>"
+  const end = "# <<< seeyonjf-ai managed <<<"
+  const start = raw.indexOf(begin)
+  if (start === -1) return raw.trimEnd()
+  const finish = raw.indexOf(end, start)
+  if (finish === -1) {
+    throw new Error("Codex 配置中存在未闭合的 seeyonjf-ai managed block，请手动处理后重试。")
+  }
+  return `${raw.slice(0, start)}${raw.slice(finish + end.length)}`.trimEnd()
+}
+
+function stripCodexTopLevelSelection(raw) {
+  const lines = raw.split(/\r?\n/)
+  let inTable = false
+  return lines.filter((line) => {
+    if (/^\s*\[/.test(line)) inTable = true
+    if (inTable) return true
+    return !/^\s*(model|model_provider)\s*=/.test(line)
+  }).join("\n").trimEnd()
+}
+
+function codexManagedBlock(token, baseUrl, model) {
+  return `# >>> seeyonjf-ai managed >>>
+# 由 tools/configure-chat-gateway.mjs 自动生成。重新运行工具会替换本段。
+model = ${tomlString(model)}
+model_provider = ${tomlString(PROVIDER_ID)}
+
+[model_providers.${PROVIDER_ID}]
+name = "SeeyonJF-AI"
+base_url = ${tomlString(baseUrl)}
+wire_api = "chat"
+experimental_bearer_token = ${tomlString(token)}
+# <<< seeyonjf-ai managed <<<`
+}
+
+function configureCodex(token, baseUrl, model) {
+  const filePath = configPaths().codex
+  ensureDir(filePath)
+  const backupPath = backupFile(filePath)
+  const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : ""
+  const preserved = stripCodexTopLevelSelection(stripManagedCodexBlock(existing))
+  const next = [codexManagedBlock(token, baseUrl, model), preserved].filter(Boolean).join("\n\n")
+  fs.writeFileSync(filePath, `${next}\n`, "utf8")
+  return { filePath, backupPath }
+}
+
+function listBackups(filePath) {
+  const dir = path.dirname(filePath)
+  const base = path.basename(filePath)
+  if (!fs.existsSync(dir)) return []
+  return fs.readdirSync(dir)
+    .filter((entry) => entry.startsWith(`${base}.bak-`))
+    .map((entry) => path.join(dir, entry))
+    .sort()
+    .reverse()
+}
+
+async function promptChoice(rl, question, choices) {
+  section(question)
+  choices.forEach((choice, index) => {
+    const suffix = choice.disabled ? ` ${ui.warning("[待协议支持]")}` : ""
+    output.write(`  ${ui.value(`${index + 1}.`)} ${choice.label}${suffix}\n`)
+    if (choice.description) output.write(`     ${ui.muted(choice.description)}\n`)
+  })
+  while (true) {
+    const answer = (await rl.question("请输入序号: ")).trim()
+    const index = Number(answer) - 1
+    if (Number.isInteger(index) && choices[index]) return choices[index].value
+    output.write(`${ui.warning("输入无效，请重新输入。")}\n`)
+  }
+}
+
+function isCodexUnavailable(tool) {
+  return tool === "codex" || tool === "both"
+}
+
+function printCodexUnavailable(tool) {
+  section("暂不支持")
+  const target = tool === "both" ? "opencode + codex" : "Codex"
+  output.write(`${ui.warning("!")} 当前选择: ${target}\n`)
+  output.write("Codex 当前不再支持本工具现有的 chat/completions 配置方式。\n")
+  output.write("Codex 配置需等待网关侧协议支持建设完成后再开放。\n")
+  output.write("本次不会写入任何配置，也不会修改现有文件。\n\n")
+  output.write(`如需配置当前可用能力，请选择 ${ui.value("opencode")}。\n`)
+}
+
+async function restoreFlow() {
+  const rl = readline.createInterface({ input, output })
+  try {
+    const tool = await promptChoice(rl, "请选择需要恢复的工具", [
+      { label: "opencode", value: "opencode" },
+      { label: "codex", value: "codex" },
+    ])
+    const targetPath = configPaths()[tool]
+    const backups = listBackups(targetPath)
+    if (backups.length === 0) {
+      output.write(`未找到备份文件: ${targetPath}.bak-*\n`)
+      return
+    }
+    const backupPath = await promptChoice(rl, "请选择要恢复的备份", backups.map((backup) => ({ label: backup, value: backup })))
+    const currentBackup = backupFile(targetPath)
+    ensureDir(targetPath)
+    fs.copyFileSync(backupPath, targetPath)
+    output.write(`已恢复 ${targetPath}\n`)
+    output.write(`来源备份: ${backupPath}\n`)
+    if (currentBackup) output.write(`恢复前的当前配置已再次备份: ${currentBackup}\n`)
+  } finally {
+    rl.close()
+  }
+}
+
+function validateTool(tool) {
+  if (!["opencode", "codex", "both"].includes(tool)) {
+    throw new Error("--tool 只能是 opencode、codex 或 both")
+  }
+}
+
+function validateModel(model, label) {
+  if (!CHAT_MODELS.includes(model)) {
+    throw new Error(`${label} 不在支持列表中: ${CHAT_MODELS.join(", ")}`)
+  }
+}
+
+function validateBaseUrl(baseUrl) {
+  const normalized = baseUrl.trim().replace(/\/+$/, "")
+  let url
+  try {
+    url = new URL(normalized)
+  } catch {
+    throw new Error("--base-url 必须是有效 URL")
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new Error("--base-url 只支持 http 或 https URL")
+  }
+  if (url.pathname.replace(/\/+$/, "").endsWith("/chat/completions")) {
+    throw new Error("--base-url 请填写基础地址，不要追加 /chat/completions")
+  }
+  return normalized
+}
+
+function printBackups() {
+  const paths = configPaths()
+  for (const [tool, filePath] of Object.entries(paths)) {
+    const backups = listBackups(filePath)
+    output.write(`${tool}: ${filePath}\n`)
+    if (backups.length === 0) {
+      output.write("  未找到备份。\n")
+      continue
+    }
+    for (const backup of backups) output.write(`  ${backup}\n`)
+  }
+}
+
+async function configureFlow(parsed) {
+  const rl = readline.createInterface({ input, output })
+  try {
+    printToolCheck(checkTools())
+
+    const tool = parsed.tool ?? await promptChoice(rl, "请选择需要配置的工具", [
+      { label: "opencode", value: "opencode", description: "当前支持 chat/completions 网关配置。" },
+      { label: "codex", value: "codex", disabled: true, description: "待协议支持建设中，当前不会写入配置。" },
+      { label: "opencode + codex", value: "both", disabled: true, description: "包含 Codex，待协议支持建设中，当前不会写入配置。" },
+    ])
+    validateTool(tool)
+    if (isCodexUnavailable(tool)) {
+      printCodexUnavailable(tool)
+      return
+    }
+
+    const model = parsed.model ?? DEFAULT_MODEL
+    const smallModel = parsed.smallModel ?? DEFAULT_SMALL_MODEL
+    validateModel(model, "默认模型")
+    validateModel(smallModel, "small_model")
+
+    let baseUrl = parsed.baseUrl
+    if (!baseUrl) baseUrl = (await rl.question("请输入 chat/completions 网关基础地址: ")).trim()
+    if (!baseUrl) throw new Error("网关基础地址不能为空")
+    baseUrl = validateBaseUrl(baseUrl)
+
+    let token = parsed.key
+    if (!token) token = (await rl.question("请输入 chat/completions 网关 token: ")).trim()
+    if (!token) throw new Error("token 不能为空")
+
+    const results = []
+    results.push({ tool: "opencode", ...configureOpenCode(token, baseUrl, model, smallModel) })
+
+    output.write("\n")
+    section("配置完成")
+    output.write(`${ui.success("✓")} 网关基础地址: ${ui.value(baseUrl)}\n`)
+    output.write(`${ui.success("✓")} 默认模型: ${ui.value(model)}\n`)
+    output.write(`${ui.success("✓")} opencode small_model: ${ui.value(smallModel)}\n`)
+    for (const result of results) {
+      output.write(`${ui.success("✓")} ${result.tool}: ${result.filePath}\n`)
+      if (result.backupPath) output.write(`  备份文件: ${result.backupPath}\n`)
+      else output.write(`  ${ui.muted("原配置不存在，本次未生成备份。")}\n`)
+    }
+    output.write("\n")
+    section("恢复方式")
+    output.write("- 交互恢复: seeyonjf-ai-tool restore\n")
+    output.write("- 手动恢复: 将对应 .bak-时间戳 文件复制回原配置路径。\n")
+    output.write(`\n${ui.warning("提示:")} opencode 配置修改后需要重启 opencode。\n`)
+  } finally {
+    rl.close()
+  }
+}
+
+async function main() {
+  const parsed = parseArgs(args)
+  if (parsed.version) {
+    output.write(`${packageVersion()}\n`)
+    return
+  }
+  if (parsed.help) {
+    output.write(usage())
+    return
+  }
+  if (parsed.command === "configure") {
+    await configureFlow(parsed)
+    return
+  }
+  if (parsed.command === "restore") {
+    await restoreFlow()
+    return
+  }
+  if (parsed.command === "list-backups") {
+    printBackups()
+    return
+  }
+  throw new Error(`未知命令: ${parsed.command}`)
+}
+
+main().catch((error) => {
+  console.error(`错误: ${error.message}`)
+  process.exitCode = 1
+})