从零到一：用 Flask + 大模型 API 搭建「AI 方案生成器」的实战全记录

作者：Eddygit
日期：2026-08-28
标签：Flask、大模型API、华为云DevSpace、CodeArts、IaC

一、为什么做这个工具

在日常工作中，撰写技术方案、商业方案、项目方案是一件高频但耗时的事。每次面对一个新主题，都要从零开始组织结构、斟酌措辞、补充细节。如果大模型能帮我们完成"从主题到初稿"这一步，再由人工审阅修改，效率会高很多。

于是就有了这个「AI 方案生成器」——一个轻量 Web 工具：输入主题，选择方案类型，一键生成 Markdown 格式的方案初稿。

二、技术路线

2.1 整体架构

用户浏览器 ──HTTP──▶ Flask 后端 ──HTTPS──▶ 大模型 API
                         │
                         └─▶ 无 API Key 时返回示例方案（离线演示）

选型理由：

2.2 后端设计

后端核心是一个 /api/generate 接口，流程如下：

1. 请求校验：检查 topic 是否为空，scheme_type 是否合法
2. Prompt 构建：根据方案类型拼接不同的系统提示词
3. 大模型调用：有 API_KEY 则调用真实 API，无则返回示例方案
4. 错误处理：超时、网络错误、API 返回异常均有兜底

关键设计——离线演示模式：

API_KEY = os.environ.get("API_KEY", "").strip()
# 如果没有配置 API_KEY，返回一个结构完整的示例方案
# 这样用户无需配置任何密钥就能体验工具功能

这个设计让工具"开箱即用"，降低了体验门槛。

2.3 前端设计

前端用原生 JS 实现，核心交互：

• 输入主题 → 选择方案类型 → 设置字数 → 点击生成
• 生成过程中显示 loading 状态
• 结果区域用 marked.js 渲染 Markdown
• 支持一键复制和清空

样式上用 CSS 变量定义主题色，整体风格偏暗色系（适合开发者工具的调性）。

三、实战经验

3.1 使用 CodeArts 生成代码

这个项目的代码是通过 Huawei Cloud CodeArts（码道）的 ACP 协议生成的。实际操作中遇到了一些值得记录的问题：

Python 环境冲突：DevSpace 沙箱中 PYTHONHOME 指向 Python 3.12，但 /usr/bin/python3 实际是 Python 3.9。直接用 python3 运行会报 ImportError: cannot import name 'text_encoding'。

解决方案：显式使用 /root/runtime/codearts/python3.12/bin/python3.12 解释器，绕过环境变量冲突。

PY=/root/runtime/codearts/python3.12/bin/python3.12
$PY -m pip install -r requirements.txt
$PY app.py

教训：在沙箱环境中，不要假设 python3 指向你期望的版本。先 --version 确认，再决定用哪个解释器。

3.2 DevSpace 端口预览

Huawei Cloud DevSpace 自带端口预览功能，格式为：

https://{端口}-{容器ID}.workspace.developer.huaweicloud.com/

只需在沙箱内启动服务监听对应端口，外部即可通过这个 URL 访问。不需要额外创建 DevBridge 隧道，对于开发和演示来说非常方便。

注意：启动服务前务必检查端口是否被占用：

ss -tlnp | grep ':8080'

3.3 GitCode 推送

推送代码到 GitCode 时，如果仓库用 auto_init=true 创建（有初始 README），本地 commit 与远程没有共同祖先，直接 push 会被拒绝。需要：

git fetch origin main
git merge origin/main --no-edit --allow-unrelated-histories
# 解决冲突后
git push origin main

3.4 文件从沙箱导出

CodeArts 在 bwrap 沙箱内创建文件，从外部直接 ls 看不到。需要通过 acpx 会话让 CodeArts 输出文件内容，再在主机侧重建文件。这是一个容易踩的坑——沙箱的文件系统和主机是隔离的。

四、技术心得

4.1 小工具的设计哲学

做小工具，"能用"比"完美"重要。这个工具的第一版：

• 没有用户认证
• 没有数据库
• 没有日志持久化
• 没有流式输出

但它在 5 分钟内就能跑起来，用户输入主题就能看到结果。先解决"从 0 到 1"，再考虑"从 1 到 100"。

4.2 离线演示的价值

很多 AI 工具要求用户先配置 API Key 才能体验，这一步就流失了大量用户。我们的做法是：无 Key 时返回示例方案，让用户先看到效果，再决定是否配置真实 API。

这个"降级体验"的设计思路适用于很多场景：先给用户一个"看起来对"的结果，再引导深度使用。

4.3 Prompt 工程的初步实践

不同方案类型需要不同的 Prompt 策略：

TYPE_GUIDE = {
    "技术方案": "侧重技术架构、技术选型、实现路径、风险评估与测试验证",
    "商业方案": "侧重市场分析、商业模式、盈利路径、竞争分析与运营策略",
    "项目方案": "侧重项目背景、目标范围、里程碑计划、资源配置与交付管理",
}

同一个主题，技术方案和商业方案的输出应该完全不同。通过在 Prompt 中明确"侧重点"，引导大模型生成符合场景的内容。

五、存在问题与优化空间

5.1 当前不足

5.2 优化方向

1. 流式输出（Streaming）

使用 Server-Sent Events (SSE) 或 WebSocket 实现流式输出，大模型每生成一段就推送到前端，用户可以实时看到生成进度。

# 伪代码
@app.route("/api/generate_stream")
def generate_stream():
    def stream():
        for chunk in llm_stream(prompt):
            yield f"data: {chunk}\n\n"
    return Response(stream(), mimetype="text/event-stream")

2. 方案模板化

将不同方案类型的结构模板化，让大模型"填空"而非"自由发挥"：

技术方案模板：
## 一、背景与目标
## 二、技术架构
## 三、技术选型
## 四、实现路径
## 五、风险评估
## 六、测试验证

3. 多轮对话优化

支持用户对生成的方案提出修改意见，进行多轮交互优化，而非每次从头生成。

4. 方案导出

支持将生成的方案导出为 Word、PDF 格式，方便分享和归档。

5. 生产部署

将 Flask 开发服务器替换为 Gunicorn + Nginx，支持并发请求。容器化部署到 CCE（云容器引擎），配合 ELB 负载均衡实现高可用。

六、总结

这个项目虽然小，但完整走过了"需求 → 设计 → 编码 → 部署 → 推送"的全流程。几个关键收获：

1. CodeArts ACP 协议让 AI 辅助编码变得可操作、可监控，但需要理解沙箱隔离机制
2. DevSpace 端口预览是开发调试的利器，比手动配置隧道省很多事
3. 离线演示模式是降低用户门槛的有效手段
4. 小工具先跑通再优化，不要一开始就追求完美架构

下一步计划：加入流式输出和方案模板化，让这个工具从"能用"变成"好用"。

本文为原创内容，记录了「AI 方案生成器」工具的完整开发过程。如有问题或建议，欢迎在仓库提 Issue。