chore(repo): keep only current main snapshot

History squashed to one root commit to permanently drop old branch history and objects.
2026-02-28 16:41:12 +08:00
commit 8df2095acf
89 changed files with 21634 additions and 0 deletions
--- a/docs/gpio-map.md
+++ b/docs/gpio-map.md
@@ -0,0 +1,65 @@
+# ESP32-S3 GPIO Mapping
+
+本文件记录当前板级 GPIO 分配，来源于硬件对接表（2026-02-26）。
+
+## GPIO Table
+
+| Board Pin | GPIO | Signal | Direction | Notes |
+| --- | --- | --- | --- | --- |
+| 1 | GND | GND | - | Ground |
+| 2 | 3V3 | 3V3 | - | 3.3V Power |
+| 3 | EN/RST | EN | Input | Chip enable/reset |
+| 4 | IO4 | PRINT_STB5_6 | Output | Printer strobe 5/6 |
+| 5 | IO5 | PRINT_STB3_4 | Output | Printer strobe 3/4 |
+| 6 | IO6 | ES8311_I2C_SDA | Bidirectional | Voice codec I2C SDA |
+| 7 | IO7 | ES8311_I2C_SCL | Output | Voice codec I2C SCL |
+| 8 | IO15 | BATTERY_ADC | Input | Battery voltage ADC detect |
+| 9 | IO16 | PRINT_STB1_2 | Output | Printer strobe 1/2 |
+| 10 | IO17 | PRINT_PAPER | Input | Paper detect |
+| 11 | IO18 | NTC_ADC | Input | NTC ADC |
+| 12 | IO8 | PRINT_OUTA_P | Output | Printer OUTA+ |
+| 13 | IO19 | PRINT_OUTA_N | Output | Printer OUTA- |
+| 14 | IO20 | ES8311_PA | Output | PA control |
+| 15 | IO3 | PRINT_OUTB_P | Output | Printer OUTB+ |
+| 16 | IO46 | PRINT_OUTB_N | Output | Printer OUTB- |
+| 17 | IO9 | SPI_SHARED_MOSI | Output | Printer/Screen shared MOSI |
+| 18 | IO10 | PRINTER_MISO | Input | Printer MISO |
+| 19 | IO11 | SPI_SHARED_CLK | Output | Printer/Screen shared CLK |
+| 20 | IO12 | SCREEN_DC | Output | ST7789 DC |
+| 21 | IO13 | SCREEN_CS1 | Output | ST7789 CS |
+| 22 | IO14 | MIC_KEY | Input | Mic key (can ADC-mux 2 keys if needed) |
+| 23 | IO21 | LED_G | Output | Green LED |
+| 24 | IO47 | POWER_KEY | Input | Hold low for 2s to request power-off logic |
+| 25 | IO48 | SCREEN_BACKLIGHT | Output | High level turns backlight on |
+| 26 | IO45 | PRINT_LAT | Output | Printer LAT |
+| 27 | IO0 | KEY_PRINT / BOOST_CTRL | Input/Output | Print confirm key or 7.2V boost control |
+| 28 | IO35 | N/A | - | Not available |
+| 29 | IO36 | N/A | - | Not available |
+| 30 | IO37 | N/A | - | Not available |
+| 31 | IO38 | I2S_MCLK | Output | Voice I2S MCLK |
+| 32 | IO39 | I2S_BCLK | Output | Voice I2S BCLK |
+| 33 | IO40 | I2S_DI | Input | Voice I2S data in |
+| 34 | IO41 | I2S_WS | Output | Voice I2S WS |
+| 35 | IO42 | I2S_DO | Output | Voice I2S data out |
+| 36 | TXD0 | UART0_TX | Output | Serial log/program |
+| 37 | RXD0 | UART0_RX | Input | Serial log/program |
+| 38 | IO2 | LED_R | Output | Red LED |
+| 39 | IO1 | POWER_HOLD | Output | Must drive high at boot to keep board powered |
+| 40 | GND | GND | - | Ground |
+| 41 | GND | GND | - | Ground |
+
+## Firmware Mapping Notes
+
+- `main/Kconfig.projbuild` contains board pin configs prefixed with `TQ_*`.
+- `components/platform/src/platform_bootstrap.c` initializes critical GPIO on startup:
+  - `POWER_HOLD` asserted high early.
+  - `SCREEN_DC/SCREEN_CS/SCREEN_BACKLIGHT` default states.
+  - `KEY_PRINT` defaults to boost-enable output mode (`CONFIG_TQ_KEY_PRINT_BOOST_ENABLE_ON_BOOT=y`).
+  - key/sensor inputs (`POWER_KEY`, `MIC_KEY`, `PRINT_PAPER`, ADC inputs) default directions.
+- `components/platform/src/display_st7789.c` provides ST7789 driver integration:
+  - SPI bus (`MOSI=IO9`, `CLK=IO11`) + `esp_lcd_new_panel_st7789`.
+  - Optional boot test pattern via `CONFIG_TQ_SCREEN_TEST_PATTERN_ON_BOOT`.
+- Voice codec and I2S pin defaults are aligned to this table:
+  - I2C: `SDA=6`, `SCL=7`
+  - I2S: `MCLK=38`, `BCLK=39`, `WS=41`, `DIN=40`, `DOUT=42`
+  - PA: `IO20`
--- a/docs/websocket.md
+++ b/docs/websocket.md
--- a/docs/z-image.md
+++ b/docs/z-image.md
@@ -0,0 +1,268 @@
+# Z-Image 文生图 API 指南
+
+Z-Image 是一款轻量级文生图模型，支持快速出图、中英文文本渲染，以及多种分辨率和宽高比。
+
+## 快速入口
+
+- 在线体验（北京）：<https://bailian.console.aliyun.com/cn-beijing/?tab=model#/efm/model_experience_center/vision?currentTab=imageGenerate&modelId=z-image-turbo>
+- 在线体验（新加坡）：<https://modelstudio.console.aliyun.com/ap-southeast-1?tab=dashboard#/efm/model_experience_center/vision?currentTab=imageGenerate&modelId=z-image-turbo>
+- 技术博客：<https://tongyi-mai.github.io/Z-Image-blog/>
+- 模型列表（按地域）：<https://help.aliyun.com/zh/model-studio/models#b77c038c56b7y>
+
+## 效果示例
+
+### 输入提示词
+
+```text
+film grain, analog film texture, soft film lighting, Kodak Portra 400 style,
+cinematic grainy texture, photorealistic details, subtle noise, (film grain:1.2)。
+采用近景特写镜头拍摄的东亚年轻女性，站在户外雪地中，神情带有轻微惊讶。
+整体画面清新自然，主色调为蓝、白、黑。
+```
+
+### 输出图像
+
+![Z-Image 输出示例](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/6915736671/p1036890.png)
+
+## 模型概览
+
+| 模型名称 | 模型简介 | 输出规格 |
+| --- | --- | --- |
+| `z-image-turbo` | 轻量模型，快速生图 | 图像格式：PNG；单次固定返回 1 张；总像素范围：`[512*512, 2048*2048]` |
+
+## 前提条件
+
+1. 获取 API Key：<https://help.aliyun.com/zh/model-studio/get-api-key>
+2. 配置环境变量：<https://help.aliyun.com/zh/model-studio/configure-api-key-through-environment-variables>
+
+示例：
+
+```bash
+export DASHSCOPE_API_KEY="sk-xxxxxxxx"
+```
+
+## HTTP 同步调用
+
+- 北京地域：`POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation`
+- 新加坡地域：`POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation`
+
+### 请求示例
+
+`prompt_extend=false` 时响应更快，仅返回图像与提示词；
+`prompt_extend=true` 时会返回优化后的提示词和推理过程，但耗时与费用更高。
+
+```bash
+curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
+  --header 'Content-Type: application/json' \
+  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
+  --data '{
+    "model": "z-image-turbo",
+    "input": {
+      "messages": [
+        {
+          "role": "user",
+          "content": [
+            {
+              "text": "一只坐在窗边的橘猫，午后阳光，胶片质感，写实风格。"
+            }
+          ]
+        }
+      ]
+    },
+    "parameters": {
+      "prompt_extend": false,
+      "size": "1120*1440"
+    }
+  }'
+```
+
+## 请求参数
+
+### Headers
+
+| 参数 | 类型 | 必选 | 说明 |
+| --- | --- | --- | --- |
+| `Content-Type` | string | 是 | 固定为 `application/json` |
+| `Authorization` | string | 是 | 鉴权信息，格式：`Bearer $DASHSCOPE_API_KEY` |
+
+### Body
+
+| 参数路径 | 类型 | 必选 | 说明 |
+| --- | --- | --- | --- |
+| `model` | string | 是 | 模型名称，固定为 `z-image-turbo` |
+| `input` | object | 是 | 输入对象 |
+| `input.messages` | array | 是 | 消息数组，仅支持单轮输入 |
+| `input.messages[0].role` | string | 是 | 固定为 `user` |
+| `input.messages[0].content` | array | 是 | 内容数组，必须且仅能包含 1 个 `text` 对象 |
+| `input.messages[0].content[0].text` | string | 是 | 正向提示词（中英文均可），长度上限 800 字符，超长自动截断 |
+| `parameters` | object | 否 | 生成参数对象 |
+| `parameters.size` | string | 否 | 输出分辨率，格式 `宽*高`，默认 `1024*1536` |
+| `parameters.prompt_extend` | bool | 否 | 是否启用提示词智能改写，默认 `false` |
+| `parameters.seed` | integer | 否 | 随机种子，范围 `[0, 2147483647]` |
+
+### size 参数说明
+
+- 总像素限制：`[512*512, 2048*2048]`
+- 推荐总像素范围：`[1024*1024, 1536*1536]`
+- 同一 `seed` 可提升结果稳定性，但不能保证完全一致
+
+### 推荐分辨率
+
+#### 总像素约 1024x1024
+
+| 宽高比 | 分辨率 |
+| --- | --- |
+| 1:1 | `1024*1024` |
+| 2:3 | `832*1248` |
+| 3:2 | `1248*832` |
+| 3:4 | `864*1152` |
+| 4:3 | `1152*864` |
+| 7:9 | `896*1152` |
+| 9:7 | `1152*896` |
+| 9:16 | `720*1280` |
+| 9:21 | `576*1344` |
+| 16:9 | `1280*720` |
+| 21:9 | `1344*576` |
+
+#### 总像素约 1280x1280
+
+| 宽高比 | 分辨率 |
+| --- | --- |
+| 1:1 | `1280*1280` |
+| 2:3 | `1024*1536` |
+| 3:2 | `1536*1024` |
+| 3:4 | `1104*1472` |
+| 4:3 | `1472*1104` |
+| 7:9 | `1120*1440` |
+| 9:7 | `1440*1120` |
+| 9:16 | `864*1536` |
+| 9:21 | `720*1680` |
+| 16:9 | `1536*864` |
+| 21:9 | `1680*720` |
+
+#### 总像素约 1536x1536
+
+| 宽高比 | 分辨率 |
+| --- | --- |
+| 1:1 | `1536*1536` |
+| 2:3 | `1248*1872` |
+| 3:2 | `1872*1248` |
+| 3:4 | `1296*1728` |
+| 4:3 | `1728*1296` |
+| 7:9 | `1344*1728` |
+| 9:7 | `1728*1344` |
+| 9:16 | `1152*2048` |
+| 9:21 | `864*2016` |
+| 16:9 | `2048*1152` |
+| 21:9 | `2016*864` |
+
+## 响应示例
+
+### 成功响应
+
+任务数据（如图像 URL）仅保留 24 小时，请及时保存。
+
+```json
+{
+  "output": {
+    "choices": [
+      {
+        "finish_reason": "stop",
+        "message": {
+          "role": "assistant",
+          "content": [
+            {
+              "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.png?Expires=xxx"
+            },
+            {
+              "text": "一只坐在窗边的橘猫，午后阳光，胶片质感，写实风格。"
+            }
+          ],
+          "reasoning_content": ""
+        }
+      }
+    ]
+  },
+  "usage": {
+    "width": 1120,
+    "height": 1440,
+    "image_count": 1,
+    "input_tokens": 0,
+    "output_tokens": 0,
+    "total_tokens": 0
+  },
+  "request_id": "8a0809b4-a796-47f4-a095-394b02b62xxx"
+}
+```
+
+### 失败响应
+
+```json
+{
+  "request_id": "a4d78a5f-655f-9639-8437-xxxxxx",
+  "code": "InvalidParameter",
+  "message": "num_images_per_prompt must be 1"
+}
+```
+
+## 响应字段说明
+
+| 参数路径 | 类型 | 说明 |
+| --- | --- | --- |
+| `output` | object | 任务输出信息 |
+| `output.choices` | array | 模型输出数组，仅包含 1 个元素 |
+| `output.choices[0].finish_reason` | string | 停止原因，正常完成为 `stop` |
+| `output.choices[0].message.role` | string | 固定为 `assistant` |
+| `output.choices[0].message.content[].image` | string | 生成图像 URL（PNG，24 小时有效） |
+| `output.choices[0].message.content[].text` | string | `prompt_extend=false` 返回原提示词；`true` 返回改写后提示词 |
+| `output.choices[0].message.reasoning_content` | string | 推理过程，仅 `prompt_extend=true` 时返回 |
+| `usage` | object | 统计信息 |
+| `usage.width` | integer | 图像宽度（像素） |
+| `usage.height` | integer | 图像高度（像素） |
+| `usage.image_count` | integer | 图像数量，固定为 1 |
+| `usage.input_tokens` | integer | 输入 token 数，`prompt_extend=false` 时固定为 0 |
+| `usage.output_tokens` | integer | 输出 token 数，`prompt_extend=false` 时固定为 0 |
+| `usage.output_tokens_details.reasoning_tokens` | integer | 推理 token 数，仅 `prompt_extend=true` 时返回 |
+| `usage.total_tokens` | integer | 总 token 数，`prompt_extend=false` 时固定为 0 |
+| `request_id` | string | 请求唯一标识，可用于排障 |
+| `code` | string | 错误码，仅失败时返回 |
+| `message` | string | 错误详情，仅失败时返回 |
+
+## 使用限制
+
+- 图像 URL 仅保留 24 小时，请及时下载。
+- 输入 `prompt` 与输出图像均经过内容安全审核，违规请求可能返回 `IPInfringementSuspect` 或 `DataInspectionFailed`。
+- 若业务网络禁止访问公网 OSS，请将下列域名加入白名单：
+
+```text
+dashscope-result-bj.oss-cn-beijing.aliyuncs.com
+dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com
+dashscope-result-sh.oss-cn-shanghai.aliyuncs.com
+dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com
+dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com
+dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com
+dashscope-result-hy.oss-cn-heyuan.aliyuncs.com
+dashscope-result-cd.oss-cn-chengdu.aliyuncs.com
+dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com
+dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com
+```
+
+## 计费与限流
+
+- 模型价格与免费额度：<https://help.aliyun.com/zh/model-studio/model-pricing#6713612f55h4l>
+- 限流说明：<https://help.aliyun.com/zh/model-studio/rate-limit#e17ad85fd8wwl>
+- 计费按成功生成的图像张数统计；失败请求不计费，也不消耗免费额度：<https://help.aliyun.com/zh/model-studio/new-free-quota>
+
+## 错误码
+
+错误码总览：<https://help.aliyun.com/zh/model-studio/error-code>
+
+## 常见问题
+
+### 如何查看模型调用量？
+
+模型调用约 1 小时后，可在以下页面查看调用次数、成功率等指标：
+
+- 模型监控（北京）：<https://bailian.console.aliyun.com/cn-beijing/?tab=model#/model-telemetry>
+- 模型监控（新加坡）：<https://modelstudio.console.aliyuncs.com/ap-southeast-1?tab=dashboard#/model-telemetry>
+- 账单查询与成本管理：<https://help.aliyun.com/zh/model-studio/bill-query-and-cost-management>