demo成语查询应用

# 从零到一：用 AI 搭建一款文艺风格成语查询应用

> 记录「墨韵成语·文辞雅鉴」从构思、开发、部署到发布华为云作品展览馆的全过程。

## 一、缘起：为什么做一个成语查询应用

成语是中华语言的精华，短短四字往往浓缩了一段历史、一个道理。对于中小学生而言，成语学习是语文课的重要部分——不仅要会背，更要懂义、知源、会用。

市面上已有不少成语词典 App，但大多界面朴素、功能堆砌，缺少一份"书卷气"。于是我想：能不能做一个**看起来像翻开一本古籍**的成语查询工具？宣纸为底，墨色为字，朱砂作印，让查成语这件事本身也成为一种文化体验。

这就是「墨韵成语·文辞雅鉴」的起点。

## 二、设计：文艺风格的取舍

### 配色方案

没有用常见的蓝白配色，而是选择了水墨色调：

| 角色 | 色值 | 用途 |
|------|------|------|
| 宣纸米白 | `#f5f0e8` | 页面背景，模拟宣纸质感 |
| 墨色 | `#2c2c2c` | 正文文字，浓淡相宜 |
| 朱砂红 | `#c0392b` | 印章、强调点缀 |
| 青瓷绿 | `#5d8a6e` | 次级装饰、分类标签 |

这套配色的灵感来自传统书画：宣纸铺底，浓墨书写，落款盖印，一抹青绿如远山。

### 字体选择

标题使用楷体风格，呼应书法美感；正文使用宋体风格，保证阅读舒适度。通过 CSS `font-family` 优先级链，在不同操作系统上自动回退到最接近的可用字体。

### 装饰元素

- **水墨装饰条**：页面顶部一条渐变墨色条纹，配以「成語」篆体印章
- **卷轴搜索框**：搜索框两侧设计卷轴轴杆造型，仿佛展开一幅卷轴
- **传统纹样分隔线**：用 `❀` 符号配以渐变线条，作为内容区段的分隔
- **宣纸纹理**：通过 CSS 渐变叠加微弱噪点，模拟纸张纤维感

这些元素不是为了装饰而装饰，每一个都在强化"翻阅古籍"的沉浸感。

## 三、技术方案：纯前端的轻量选择

### 技术栈

```
HTML + CSS + JavaScript（纯前端，无后端依赖）
启动方式：python3 -m http.server 8080
```

选择纯前端方案有三个考量：

1. **部署简单**：一个 `python3 -m http.server` 就能跑起来，不需要 Node.js 环境或数据库
2. **数据内联**：115 条成语数据直接写在 `app.js` 中，无需 API 调用，离线可用
3. **加载快速**：总共约 70KB，首屏加载在毫秒级

### 文件结构

```
idiom-lookup/
├── index.html    # 主页面（109 行）
├── style.css     # 文艺风格样式（757 行）
├── app.js        # 成语数据库 + 应用逻辑（466 行）
└── README.md     # 项目说明
```

### 成语数据结构

每条成语包含 7 个字段，覆盖学生学习的各个维度：

```javascript
{
  word: "一鸣惊人",           // 成语
  pinyin: "yī míng jīng rén", // 拼音注音
  meaning: "比喻平时没有突出的表现...", // 释义
  source: "《史记·滑稽列传》",  // 出处
  example: "他在这次比赛中一鸣惊人...", // 例句
  synonyms: "一举成名、名满天下", // 近义词
  antonyms: "默默无闻、平淡无奇", // 反义词
  category: "数字类"           // 分类
}
```

共收录 **115 条成语**，覆盖 8 大分类：

| 分类 | 数量 | 示例 |
|------|------|------|
| 数字类 | 16 | 一帆风顺、一鸣惊人、三心二意 |
| 动物类 | 17 | 画蛇添足、狐假虎威、鹏程万里 |
| 历史典故类 | 17 | 卧薪尝胆、破釜沉舟、完璧归赵 |
| 自然景物类 | 15 | 风花雪月、水落石出、春暖花开 |
| 人物品质类 | 12 | 光明磊落、虚怀若谷、德高望重 |
| 学习励志类 | 13 | 悬梁刺股、凿壁偷光、勤学苦练 |
| 情感心理类 | 10 | 喜出望外、怒发冲冠、心花怒放 |
| 动作行为类 | 15 | 手舞足蹈、东张西望、奋笔疾书 |

## 四、功能实现

### 1. 搜索查询

用户在搜索框输入成语，支持两种触发方式：
- **回车键**：直接查询
- **点击搜索按钮**：触发查询

查询逻辑在 `app.js` 中实现，对内置数据库进行精确匹配和模糊匹配，找不到时给出友好提示。

### 2. 实时自动补全

输入框监听 `input` 事件，每次按键都实时过滤成语数据库，匹配的成语以下拉列表形式展示。用户可以用键盘上下选择，也可以鼠标点击。

这一功能对学习场景特别有用——学生可能只记得成语的前一两个字，自动补全能帮助回忆。

### 3. 随机成语卡片

首页展示一张随机成语卡片，包含成语名称和简短释义。点击「换一个」按钮可以刷新。这个设计的初衷是：**即使不主动搜索，打开应用也能学到一条成语**。

### 4. 分类浏览

将 115 条成语按 8 个类别组织，用户可以点击分类标签筛选浏览。分类逻辑在数据层面通过 `category` 字段实现，UI 层面通过标签切换 + 列表重渲染完成。

### 5. 收藏功能

使用 `localStorage` 实现本地持久化收藏：
- 点击成语卡片上的星标即可收藏/取消
- 收藏列表在导航栏有独立入口
- 数据存储在浏览器本地，下次打开依然存在

选择 `localStorage` 而非后端存储，是因为这是一个轻量学习工具，不需要用户登录，本地存储足够满足需求。

### 6. 近反义词跳转

查询结果中展示近义词和反义词时，每个词都是可点击的。点击后直接跳转查询该词，形成探索链路——从一个成语出发，可以不断扩展学习相关成语。

## 五、开发过程：AI 辅助编程

这个项目的开发借助了华为云 CodeArts Agent（ACP 协议）进行 AI 辅助编程。整个过程如下：

### 5.1 需求描述

向 AI 用自然语言描述需求，包括：
- 功能需求（搜索、自动补全、收藏、分类、随机成语）
- 界面风格（文艺风格、水墨配色、宣纸纹理、卷轴搜索框）
- 技术约束（纯前端、Python 启动、内置数据库）
- 数据要求（至少 100 条成语，覆盖学生常见学习场景）

### 5.2 AI 生成代码

CodeArts Agent 接收到需求后，自动完成了：
1. 创建项目文件结构（`index.html`、`style.css`、`app.js`）
2. 编写 HTML 骨架，包含所有功能区域的 DOM 结构
3. 编写 CSS 样式，实现文艺风格设计（757 行，含动画、响应式）
4. 编写 JavaScript 应用逻辑和 115 条成语数据库
5. 启动 `python3 -m http.server 8080` 并验证服务可用

整个过程 AI 自主决策、自动执行，我只需要在关键节点确认方向。

### 5.3 关键决策点

有几个设计决策值得记录：

**为什么不用外部成语 API？**
考虑到这是一个面向学生的轻量工具，网络依赖会降低可用性（教室网络不稳定是常态）。内置数据库虽然增加了文件体积（~50KB），但保证了离线可用、即时响应。

**为什么 115 条而不是更多？**
115 条覆盖了中小学生最常接触的成语，8 个分类保证多样性。更多条目可以后续扩展，但初始版本追求"精而美"而非"大而全"。

**为什么用 Python http.server 而不是 Node.js？**
Python3 几乎所有系统都预装，`http.server` 是标准库模块，零依赖。对于纯静态文件服务，这是最简单的方案。

## 六、部署与预览

### 本地预览

```bash
cd idiom-lookup
python3 -m http.server 8080
# 访问 http://localhost:8080
```

### DevBridge 公网隧道

为了让非本地环境也能访问，通过华为云 DevBridge 创建了开发隧道：

```
隧道地址：https://zffyrpxm-8080.devbridge-s2.hwtunnel.com
```

DevBridge 是华为云的开发隧道服务，通过中继服务器将本地端口暴露到公网，无需开放防火墙端口。创建过程完全自动化：创建隧道 → 配置端口 → 启动托管，几秒钟就拿到公网 URL。

## 七、发布到作品展览馆

最后一步是将作品发布到华为云开发者作品展览馆，这个流程包含 8 个步骤：

### Step 1：身份认证
通过华为云 IAM 生成 STS 临时凭证（900 秒有效期），用于后续 API 调用认证。永久 AK/SK 留在本地，不上传。

### Step 2：项目运行 + 隧道
项目已在 8080 端口运行，DevBridge 隧道提供公网访问地址。

### Step 3：Git 仓库
代码推送至 GitCode（`gcw_nfhkuMAb/idiom-lookup`），需要通过 OAuth 授权登录 GitCode。作品名从 README.md 的 H1 标题自动提取：「墨韵成语·文辞雅鉴」。

### Step 4：封面图
自动化封面生成流程：
1. **Preflight**：安装 Chromium + CJK 字体（确保中文不乱码）
2. **UTF-8 检查**：验证所有源文件编码
3. **截图**：用 Playwright 对运行中的应用截图
4. **合成**：将截图合成为 16:9 封面图，添加标题和简介
5. **字形校验**：像素级检查封面中是否有"豆腐块"（字体缺失导致的方框）

### Step 5：作品简介
生成一句话简介并验证字数（15~50 字符）：
> 文艺风格成语查询工具，面向学生，内置百条成语

### Step 6：详情包
生成系统架构图（HTML → PNG），与 README.md 一起打包为 zip 文件上传。

### Step 7：选择活动
从活动列表中选择投稿目标——「布道师通用产品体验」。

### Step 8：发布
门禁复核通过后，调用发布 API，作品上线并获得 200 积分奖励。

### 发布结果

| 项目 | 详情 |
|------|------|
| 作品 ID | `00603049fb000000` |
| 作品链接 | https://gallery.developer.huaweicloud.com/gallery/00603049fb000000 |
| 代码仓库 | https://gitcode.com/gcw_nfhkuMAb/idiom-lookup |
| 积分奖励 | 200 分 |

## 八、反思与展望

### 做对了什么

1. **风格先行**：先确定文艺风格的设计语言，再围绕风格组织功能，避免了"功能堆砌、风格拼凑"的常见问题
2. **数据为王**：115 条精心整理的成语数据是核心价值，每条都有拼音、释义、出处、例句、近反义词，不是简单的词表
3. **轻量部署**：纯前端 + Python http.server，零依赖、秒启动，降低了使用门槛

### 可以改进的地方

1. **数据扩展**：115 条覆盖面有限，后续可以扩展到 500+ 条，增加生僻成语和成语故事
2. **学习功能**：可以增加"成语填空""成语接龙"等练习模式，从查询工具升级为学习工具
3. **语音朗读**：增加 TTS 朗读功能，帮助学生掌握成语发音
4. **数据外置**：如果数据量增大，可以将成语数据库独立为 JSON 文件，按需加载

### 结语

这个项目从构思到发布，全程借助 AI 辅助编程，大约半小时完成。它不是什么复杂系统——115 条数据、三个文件、一个 Python 命令——但它证明了一件事：**用 AI 把一个想法变成可运行、可分享、可发布的产品，门槛已经低到了"一句话"的程度**。

而文艺风格的设计，让这个工具不只是"能用"，更是"好看"——对学生来说，在宣纸墨色中查成语，本身就是一种文化熏陶。

---

*本文记录于 2026 年 10 月，作品已发布至华为云开发者作品展览馆。*