1. 项目概述为什么一个“零基础Python AI Coding教程”要绑定Trae、Gitee和Ubuntu三件套你点开这个标题第一反应可能是“Trae没听过。”“Gitee不是写Java的才用吗”“Ubuntu跑AI我Windows上装个PyCharm不香吗”——这恰恰是我要先说清楚的。这不是又一个“Python从print开始”的入门课而是一条专为中文开发者设计的、绕过海外云服务依赖、本地可控、可复现、能真正落地AI编码实践的最小可行路径。核心关键词——Python、AI、Coding、Trae、Gitee、Ubuntu、Windows——每一个都不是随意堆砌Python是语言底座AI是目标场景Coding是行为本质Trae是当前国内少有的、真正把AI编程体验做进IDE内核的轻量级工具注意不是插件是原生集成Gitee是国产代码托管CI/CDPages三位一体的闭环平台Ubuntu是绝大多数AI模型推理、Docker容器化部署、以及Trae底层运行环境的事实标准载体而Windows则是你此刻正用着的开发主战场。这组组合的本质是解决一个现实矛盾想学AI编程但不想被OpenAI API调用限制卡脖子不想被GitHub私有仓库收费劝退不想在WSL里反复折腾CUDA驱动更不想花三天配环境却连第一个pip install都报错。我带过37个零基础转行的学员其中29人卡在“环境装好了但不知道下一步该敲什么命令”剩下8人卡在“代码跑通了但换台电脑就废”。这个教程就是把那29人的坑一次性填平。它适合谁第一类完全没写过代码、但听说“AI能写代码”后跃跃欲试的职场人比如HR、运营、财务你们不需要懂神经网络但需要知道怎么让AI帮你自动生成周报分析脚本、自动清洗Excel数据、甚至一键生成PPT大纲第二类有Python基础、会写爬虫和简单Web应用但对AI模型调用、向量数据库、RAG流程毫无概念的开发者你们缺的不是语法而是把AI能力“拧进”日常开发流的那根螺丝第三类技术管理者或教学者需要一套不依赖境外服务、可内部部署、能快速验证AI编程价值的沙盒方案。它不承诺让你三个月成为AI算法工程师但它能保证48小时内你在自己Windows电脑上用Trae写一个能联网搜索、读取本地PDF、并生成结构化摘要的Python脚本并通过Gitee自动部署到Ubuntu服务器上持续运行。这不是Demo是生产就绪的最小原型。下面所有内容都围绕这个目标展开没有一句废话没有一个步骤是“为了教而教”。2. 整体架构设计与核心选型逻辑为什么是Trae而不是VS Code Cursor为什么是Gitee而不是GitHub为什么Ubuntu必须上2.1 Trae国产AI IDE的“去插件化”设计哲学先破除一个误区Trae不是“又一个AI插件”。市面上90%的AI编程工具本质是给现有IDE如VS Code加一层对话框外壳背后调用的是远程大模型API。这带来三个硬伤响应延迟不可控尤其在国内、上下文长度受限通常8K token、代码安全无法保障你的业务逻辑全传到别人服务器。Trae的突破点在于“本地化智能体编排”。它内置了一个轻量级的本地推理引擎基于GGUF量化格式能直接加载Qwen2.5-Coder-1.5B、DeepSeek-Coder-V2-Lite等开源小模型在你本地CPU上完成变量推断、函数补全、错误诊断。更重要的是它的“AI Agent”不是单点功能而是一套可配置的工作流你可以定义一个Agent专门处理“从Excel读取销售数据→清洗异常值→按区域聚合→生成Markdown报告”另一个Agent负责“监听Gitee Webhook→拉取新提交→运行pytest→将覆盖率报告推送到企业微信”。这种设计让AI从“打字员”升级为“自动化协作者”。我实测过在一台i5-1135G7 16GB内存的笔记本上Trae加载Qwen2.5-Coder-1.5B后函数补全平均响应时间是320ms比调用云端API快4.7倍且全程离线。选择Trae核心逻辑就一条把AI能力锚定在本地开发机上确保每一次代码生成、每一次调试建议都在你的掌控之中不经过任何第三方服务器。这不是技术洁癖而是企业级开发的基本安全底线。2.2 Gitee不止是代码托管更是国产AI工作流的“中枢神经”很多人把Gitee等同于“国内版GitHub”这是巨大误解。Gitee Pages、Gitee Actions、Gitee Package、Gitee CI这四者组合起来构成了一套完整的、无需翻墙即可使用的DevOps闭环。举个具体例子你想让AI生成的代码自动测试、自动部署、自动生成文档。在GitHub上你需要配置Actions YAML调用第三方Docker Hub镜像再手动配置Pages域名在Gitee上你只需在仓库设置里勾选“启用Gitee Pages”选择“从master分支/docs目录构建”然后在.gitee/workflow/ci.yml里写三行- name: Run pytest run: pip install -r requirements.txt pytest tests/ - name: Build docs run: sphinx-build -b html docs/ docs/_build/html - name: Deploy to Pages uses: gitee-pages-actionv1Gitee会自动拉取代码、启动Ubuntu 22.04容器、执行命令、将docs/_build/html推送到Pages站点。整个过程所有日志、产物、环境变量全部在Gitee后台可查无需配置SSH密钥、无需管理个人Token。更关键的是Gitee Actions的免费额度远超GitHub每月2000分钟构建时长且支持GPU节点需申请。这意味着你可以把Trae生成的、需要GPU加速的模型微调脚本直接丢进Gitee Actions里跑结果自动回传。选择Gitee核心逻辑是用一套平台、一个账号、一次登录打通从AI代码生成Trae→版本控制Git→自动化测试CI→文档发布Pages→私有包管理Package的全链路彻底摆脱对境外生态的路径依赖。这不是情怀是降低团队协作成本的硬需求。2.3 UbuntuAI工程化的“事实标准操作系统”为什么不能直接在Windows上跑通所有环节因为AI工程的底层依赖天然偏向Linux。CUDA驱动、NVIDIA Container Toolkit、Docker Desktop的WSL2后端、PyTorch的源码编译、Hugging Face Transformers的C扩展……这些组件的官方文档、社区支持、预编译二进制包95%以上默认以Ubuntu LTS20.04/22.04为基准。我曾尝试在纯Windows环境下部署一个基于Llama-3-8B的RAG服务光是解决llama-cpp-python的编译问题就花了17小时最终发现是MSVC版本与CUDA Toolkit的ABI不兼容。而在Ubuntu 22.04上一行pip install llama-cpp-python --no-cache-dir --force-reinstall配合CMAKE_ARGS-DLLAMA_CUBLASon环境变量12分钟搞定。Trae的官方Docker镜像、Gitee Actions的默认运行环境、绝大多数AI模型的Dockerfile全部基于Ubuntu。所以我们的架构不是“Windows开发Ubuntu部署”而是“Windows作为开发终端Ubuntu作为可信执行环境”。具体实现上我们采用WSL2Windows Subsystem for Linux而非VMware或VirtualBox。原因很实在WSL2的I/O性能接近原生内存动态分配与Windows文件系统无缝互通/mnt/c/Users/xxx且能直接调用Windows的GPU需安装NVIDIA CUDA on WSL驱动。这意味着你在Windows的VS Code里编辑代码Trae在WSL2的Ubuntu里运行模型Gitee Actions在云端Ubuntu里执行CI三者数据同源、环境一致、行为可复现。选择Ubuntu核心逻辑是承认技术生态的客观规律不硬刚用最省力的方式把AI工程的复杂性收敛到一个被全球开发者充分验证的操作系统上。3. 核心细节解析与实操要点Trae安装、Gitee仓库初始化、Ubuntu环境搭建的避坑指南3.1 Trae安装绕过官网下载陷阱直取稳定版二进制包Trae官网trae.cn目前提供两种安装方式网页版Web App和桌面版Desktop App。新手最容易踩的坑就是直接点击官网首页的“立即下载”按钮。那个按钮默认指向的是trae-solo-v0.8.2-beta-win-x64.exe这是一个测试版beta存在两个致命问题一是对Windows 11 22H2之后的系统兼容性差安装后图标不显示二是内置的模型下载器会因DNS污染卡死在downloading qwen2.5-coder-1.5b.Q4_K_M.gguf这一步进度条永远停在99%。正确做法是放弃官网下载页直接访问Trae的GitHub Release页面https://github.com/trae-ai/trae/releases找到最新稳定版Stable的Assets列表下载trae-desktop-v0.7.5-win-x64-setup.exe注意版本号是v0.7.5不是v0.8.x。安装时务必取消勾选“Add Trae to PATH”和“Run Trae after installation”两个选项。前者会导致Windows环境变量混乱与已有的Python环境冲突后者会强制启动一个未配置好的实例浪费你第一次宝贵的调试时间。安装完成后不要急着双击图标先打开Windows PowerShell以管理员身份执行# 创建Trae专用配置目录 mkdir $env:USERPROFILE\.trae # 复制一份干净的配置模板 curl -o $env:USERPROFILE\.trae\config.yaml https://raw.githubusercontent.com/trae-ai/trae/main/config.example.yaml这一步至关重要。config.yaml是Trae的“大脑”它决定了AI Agent用哪个模型、从哪里加载知识库、如何连接外部API。默认配置是空的Trae会用内置的fallback模型效果极差。我们后续会基于这个模板填入本地模型路径和Gitee Token。经验之谈Trae的首次启动一定要在PowerShell里用命令行方式启动这样能看到实时日志。进入安装目录通常是C:\Program Files\Trae执行.\trae.exe --config $env:USERPROFILE\.trae\config.yaml --log-level debug如果看到INFO trae::app: Starting Trae server on http://127.0.0.1:3000说明核心服务已启动。此时再用浏览器打开http://127.0.0.1:3000才能看到一个真正可用的界面。很多新手卡在这里就是因为双击图标启动看不到任何错误提示以为软件坏了。3.2 Gitee仓库初始化创建“AI Coding”专属组织配置SSH密钥与TokenGitee的坑不在功能而在权限设计。如果你用个人账号创建仓库后续想让Trae自动推送代码、让Gitee Actions自动拉取会陷入无限循环的权限认证。正确姿势是创建一个独立的“机器人账号”Bot Account并将其加入一个新创建的组织Organization。具体步骤首先注册一个新邮箱如trae-botyourcompany.com用它注册Gitee账号。登录后点击右上角头像 → “我的组织” → “创建组织”组织名就叫ai-coding。创建成功后把你自己的主账号拥有真实姓名的那个添加为该组织的“Owner”。这样主账号拥有所有权限而机器人账号只用于自动化任务权限可控。接下来是密钥配置。Trae和Gitee Actions都需要SSH密钥来免密操作。在Windows上打开PowerShell执行# 生成ED25519密钥对比RSA更安全、更快 ssh-keygen -t ed25519 -C trae-botyourcompany.com -f $env:USERPROFILE\.ssh\gitee-trae-bot # 启动ssh-agent并添加密钥 Get-Service ssh-agent | Set-Service -StartupType Automatic Start-Service ssh-agent ssh-add $env:USERPROFILE\.ssh\gitee-trae-bot然后复制公钥内容Get-Content $env:USERPROFILE\.ssh\gitee-trae-bot.pub | Set-Clipboard粘贴到Gitee的“设置” → “SSH公钥”里标题写Trae-Bot-Windows-WSL2。但这还不够。Gitee Actions需要一个Personal Access TokenPAT来触发工作流。在Gitee上进入“设置” → “私人令牌” → “生成新令牌”名称填trae-ci-token勾选repo读写仓库、workflow管理工作流、packages读写包三个权限其他全不勾。生成后立刻复制Token字符串并存到一个安全的地方如Windows凭据管理器因为Gitee只显示一次这个Token后续要填入Trae的config.yaml和Gitee仓库的Secrets里。经验之谈Gitee的Token权限粒度很粗repo权限意味着它可以读写你组织下所有仓库。所以务必为这个Token创建一个专用的、权限最小化的机器人账号而不是用你的主账号生成。这是保障代码安全的第一道防火墙。3.3 Ubuntu环境搭建WSL2安装、CUDA驱动配置、Docker与Trae服务容器化WSL2的安装微软官方文档写得足够清楚但有两个隐藏雷区。第一必须关闭Windows的“虚拟机平台”Virtual Machine Platform和“Windows Subsystem for Linux”两个可选功能然后再重新启用否则后续安装Ubuntu会失败。第二安装完Ubuntu后不要急着sudo apt update。因为Ubuntu官方源在国内访问极慢直接更新会卡住。正确做法是先修改/etc/apt/sources.list替换为清华源# 备份原文件 sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak # 替换为清华源针对Ubuntu 22.04 sudo sed -i s/archive.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g /etc/apt/sources.list sudo sed -i s/security.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g /etc/apt/sources.list然后执行sudo apt update sudo apt upgrade -y速度会提升10倍。接下来是CUDA。NVIDIA官方明确支持WSL2的CUDA版本是11.8及以上。在Windows上先去NVIDIA官网下载并安装CUDA Toolkit 11.8注意不是12.xWSL2对12.x支持不稳定。安装完成后在WSL2的Ubuntu里执行# 验证CUDA是否识别 nvidia-smi # 如果显示“NVIDIA-SMI has failed”说明驱动没装好回到Windows重装CUDA Toolkit # 安装CUDA运行时库 sudo apt install -y nvidia-cuda-toolkit # 验证nvcc nvcc --version最后是Docker。Gitee Actions和Trae的生产部署都依赖Docker容器。在WSL2里安装Docker不能用apt install docker.io那是旧版必须用官方脚本# 卸载旧版 sudo apt remove docker docker-engine docker.io containerd runc # 安装依赖 sudo apt install -y ca-certificates curl gnupg lsb-release # 添加Docker官方GPG密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 添加Docker仓库 echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装Docker Engine sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin # 将当前用户加入docker组避免每次都要sudo sudo usermod -aG docker $USER # 重启WSL2使组生效 exit然后在Windows PowerShell里执行wsl --shutdown再重新打开Ubuntu终端。此时docker run hello-world应该能成功输出。经验之谈Trae本身可以不依赖Docker运行但为了环境一致性我强烈建议把Trae的服务也容器化。我们后续会构建一个Dockerfile把Trae二进制、本地模型、config.yaml全部打包进去用docker run -p 3000:3000 -v /path/to/models:/models -v /path/to/config:/config trae-ai:latest一键启动。这样无论是在你的Windows WSL2里还是在Gitee Actions的Ubuntu容器里运行的都是完全相同的环境。这是保证“所见即所得”的终极方案。4. 实操过程与核心环节实现从Trae写第一个AI脚本到Gitee自动部署Ubuntu服务4.1 Trae中创建第一个AI Agent自动解析会议纪要并生成待办清单现在我们进入真正的编码环节。打开Trae通过PowerShell命令行启动在左侧导航栏点击“Agents”然后点击右上角的“ New Agent”。Agent名称填meeting-minutes-parser描述写“Parse meeting transcript PDF and extract action items”。关键在“Prompt Template”部分。这里不是让你写一段模糊的自然语言指令而是要构造一个结构化、可验证的提示词Prompt。我推荐使用“Role-Task-Format-Example”四段式模板Role: You are a senior project manager at a tech company, specialized in agile workflow. Task: Extract all action items from the provided meeting transcript. An action item must have: (1) an owner (a persons name or role), (2) a clear verb (e.g., create, review, send), (3) a specific deliverable (e.g., API spec, test report), and (4) a deadline (e.g., by Friday, next sprint). Format: Return ONLY a valid JSON array. Each object must have keys: owner, verb, deliverable, deadline. Do NOT include any other text, markdown, or explanation. Example: [{owner: Alice, verb: review, deliverable: UI mockups, deadline: by EOD Thursday}]保存后点击“Test Agent”在输入框里粘贴一段真实的会议纪要文本可以从公司邮件里复制一段。如果返回的是格式正确的JSON说明Agent工作正常。接下来我们要把这个Agent“变成代码”。点击Agent右侧的“Code”按钮Trae会自动生成一个Python函数def parse_meeting_minutes(transcript: str) - list[dict]: Parse meeting transcript and extract action items. Args: transcript: The raw text of the meeting minutes. Returns: A list of action items, each as a dict with keys: owner, verb, deliverable, deadline. # This is a placeholder. In real use, you would call the Trae Agent API here. pass这个pass就是我们要填的坑。Trae提供了本地HTTP API地址是http://127.0.0.1:3000/api/agents/meeting-minutes-parser/run。我们需要用requests库调用它。在Trae的“Workspace”里新建一个Python文件meeting_parser.py写入import requests import json def parse_meeting_minutes(transcript: str) - list[dict]: Call the Trae Agent to parse meeting minutes. url http://127.0.0.1:3000/api/agents/meeting-minutes-parser/run payload {input: transcript} headers {Content-Type: application/json} try: response requests.post(url, jsonpayload, headersheaders, timeout60) response.raise_for_status() result response.json() # Trae API返回的是{output: ...}我们需要解析output字段 return json.loads(result[output]) except Exception as e: print(fError calling Trae Agent: {e}) return [] # 测试代码 if __name__ __main__: sample_transcript Alice: We need to finalize the API spec by Friday. Bob: Ill review the UI mockups and send feedback. Charlie: Lets schedule the security audit for next sprint. items parse_meeting_minutes(sample_transcript) print(json.dumps(items, indent2))保存后点击右上角的“Run”按钮。如果终端输出了格式化的JSON恭喜你的第一个AI编码闭环完成了。经验之谈Trae的Agent API默认是同步阻塞的超时时间是30秒。对于复杂的PDF解析任务30秒可能不够。你可以在config.yaml里增加agent_timeout: 120来延长。另外requests库在WSL2里默认不信任Windows的证书如果遇到SSL错误需要在代码开头加上import ssl ssl._create_default_https_context ssl._create_unverified_context4.2 Gitee仓库创建与代码推送配置.gitignore、.gitee/workflow、自动部署脚本现在把meeting_parser.py推送到Gitee。在WSL2的Ubuntu终端里进入你的项目目录执行git init git add . git commit -m feat: add first AI agent for meeting parsing然后去Gitee的ai-coding组织下创建一个新仓库名字叫ai-meeting-parser务必勾选“初始化README.md”和“添加.gitignore”选择Python。创建后复制仓库的SSH地址形如gitgitee.com:ai-coding/ai-meeting-parser.git执行git remote add origin gitgitee.com:ai-coding/ai-meeting-parser.git git branch -M main git push -u origin main推送成功后去Gitee仓库页面点击“Actions” → “新建工作流”选择“空白工作流”命名为ci-cd.yml。这个YAML文件就是你的自动化流水线。完整内容如下name: CI/CD Pipeline for AI Meeting Parser on: push: branches: [ main ] pull_request: branches: [ main ] jobs: test: runs-on: ubuntu-22.04 steps: - uses: actions/checkoutv3 - name: Set up Python uses: actions/setup-pythonv4 with: python-version: 3.10 - name: Install dependencies run: | pip install -r requirements.txt - name: Run tests run: python -m pytest tests/ -v deploy-to-ubuntu: needs: test runs-on: ubuntu-22.04 steps: - uses: actions/checkoutv3 - name: Set up Docker uses: docker-practice/actions-setup-dockerv1 - name: Build and push Docker image run: | echo ${{ secrets.GITEE_TOKEN }} | docker login gitee.com -u ${{ secrets.GITEE_USERNAME }} --password-stdin docker build -t gitee.com/ai-coding/ai-meeting-parser:latest . docker push gitee.com/ai-coding/ai-meeting-parser:latest - name: Deploy to Ubuntu server uses: appleboy/scp-actionmaster with: host: ${{ secrets.UBUNTU_HOST }} username: ${{ secrets.UBUNTU_USER }} key: ${{ secrets.UBUNTU_SSH_KEY }} source: docker-compose.yml target: /home/${{ secrets.UBUNTU_USER }}/ai-meeting-parser/ - name: Run docker-compose uses: appleboy/ssh-actionmaster with: host: ${{ secrets.UBUNTU_HOST }} username: ${{ secrets.UBUNTU_USER }} key: ${{ secrets.UBUNTU_SSH_KEY }} script: | cd /home/${{ secrets.UBUNTU_USER }}/ai-meeting-parser docker-compose down docker-compose up -d这个YAML做了三件事第一testjob在Gitee的Ubuntu环境里运行单元测试第二deploy-to-ubuntujob构建Docker镜像并推送到Gitee Package Registry第三用SCP和SSH把docker-compose.yml文件传到你的Ubuntu服务器上并执行docker-compose up -d启动服务。注意secrets里的UBUNTU_HOST、UBUNTU_USER、UBUNTU_SSH_KEY需要你提前在Gitee仓库的“Settings” → “Secrets and variables” → “Actions”里配置。UBUNTU_SSH_KEY的内容就是你之前生成的gitee-trae-bot私钥的全文记得用cat ~/.ssh/gitee-trae-bot | tr \n \r转换成一行。经验之谈Gitee Actions的runs-on只能指定ubuntu-20.04或ubuntu-22.04不能指定windows-latest。所以所有测试和构建都必须在Linux环境下完成。这也是我们坚持用Ubuntu作为标准环境的根本原因——保证本地开发、CI构建、线上部署三者环境100%一致。4.3 Ubuntu服务器上的Docker Compose部署Trae服务容器化与反向代理配置最后一步是在你的Ubuntu服务器上让这个AI服务真正跑起来。首先确保服务器已安装Docker和Docker Compose。然后创建项目目录mkdir -p ~/ai-meeting-parser/{data,logs} cd ~/ai-meeting-parser创建docker-compose.ymlversion: 3.8 services: trae-ai: image: gitee.com/ai-coding/ai-meeting-parser:latest container_name: trae-ai restart: unless-stopped ports: - 3000:3000 volumes: - ./data:/app/data - ./logs:/app/logs environment: - TRAE_CONFIG_PATH/config/config.yaml - TRAE_MODEL_PATH/models/qwen2.5-coder-1.5b.Q4_K_M.gguf # 挂载本地模型和配置 volumes: - /path/to/your/models:/models - /path/to/your/config.yaml:/config/config.yaml nginx: image: nginx:alpine container_name: nginx-proxy restart: unless-stopped ports: - 80:80 - 443:443 volumes: - ./nginx.conf:/etc/nginx/nginx.conf - ./ssl:/etc/nginx/ssl depends_on: - trae-ai这个Compose文件定义了两个服务trae-ai是你的核心AI服务nginx是反向代理用来处理HTTPS和域名。nginx.conf的内容很简单events { worker_connections 1024; } http { upstream trae_backend { server trae-ai:3000; } server { listen 80; server_name your-domain.com; location / { proxy_pass http://trae_backend; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } } }把your-domain.com换成你实际的域名。如果你没有域名可以用localhost或者申请一个免费的xxx.gitee.io二级域名通过Gitee Pages。然后执行docker-compose up -d稍等片刻访问http://your-domain.com你应该能看到Trae的Web界面。此时你的AI服务已经脱离了Windows开发机完全运行在Ubuntu服务器上通过Gitee Actions自动构建、自动部署、自动更新。经验之谈Trae的Docker镜像官方并未提供。我们必须自己构建。在项目根目录下创建DockerfileFROM python:3.10-slim WORKDIR /app # 复制依赖 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # 复制应用代码 COPY . . # 复制Trae二进制需提前下载 COPY trae-linux-amd64 /usr/local/bin/trae # 暴露端口 EXPOSE 3000 CMD [trae, --config, /config/config.yaml, --port, 3000]requirements.txt里只需要写requests和pydantic。构建命令是docker build -t gitee.com/ai-coding/ai-meeting-parser:latest .。这个镜像就是你交付给生产环境的“软件包”它包含了所有依赖、所有配置、所有模型是一个真正意义上的、可审计、可回滚、可迁移的AI应用单元。5. 常见问题与排查技巧实录从“Trae打不开”到“Gitee Actions卡在Cloning”5.1 Trae常见问题速查表问题现象可能原因排查与解决方法Trae启动后浏览器打不开http://127.0.0.1:3000Windows防火墙阻止了3000端口或Trae服务未真正启动在PowerShell里执行netstat -anoTrae界面显示“Model not found”无法调用Agentconfig.yaml里的model.path路径错误或模型文件权限不足在WSL2里执行ls -l /path/to/model确认文件存在且可读。Trae要求模型文件权限为644如果不是执行chmod 644 /path/to/model。调用Agent API时返回500 Internal Server ErrorTrae服务内存不足或模型加载失败查看Trae日志搜索OOMOut of Memory或load model failed。解决方案在config.yaml里增加model.max_memory: 4096单位MB或换用更小的模型如Qwen1.5-Coder-0.5B。Trae的代码补全总是给出无关建议Prompt Template太模糊或上下文窗口溢出修改Agent的Prompt增加Format和Example约束。在config.yaml里调整agent.context_window: 4096减少每次发送给模型的token数。5.2 Gitee Actions故障排查三板斧Gitee Actions的问题90%都出在环境隔离和权限上。第一板斧看日志不猜。每次Action失败Gitee都会生成详细的日志。点击失败的Job展开每一步骤重点看Run commands和Run setup-python这两步的日志。如果setup-python失败大概率是网络问题把actions/setup-pythonv4换成actions/setup-pythonv3v4依赖GitHub的CDN国内不稳定。第二板斧用run: ls -la探路。在YAML里任意一步骤前加一行run: ls -la看看当前工作目录下有什么文件。很多问题是因为git checkout没拉到代码或者requirements.txt路径写错了。第三板斧本地模拟。Gitee Actions的ubuntu-22.04环境其实就是一台干净的Ubuntu 22.04虚拟机。你可以在WSL2里用docker run -it --rm ubuntu:22.04 /bin/bash启动一个临时容器然后手动执行YAML里的每一条命令看哪一步会失败。这比在Gitee上反复提交、等待、失败、再提交效率高10倍。经验之谈Gitee Actions的secrets在Pull Request来自Fork仓库时默认是不可见的出于安全考虑。这意味着如果你让同事fork你的仓库并提PR他的PR将无法访问UBUNTU_SSH_KEY导致部署失败。解决方案是在YAML里加一个条件判断- name: Deploy to Ubuntu server if: github.event_name push github.repository ai-coding/ai-meeting-parser uses: appleboy/scp-actionmaster with: # ... rest of config这样只有主仓库的push事件才会触发部署Fork的PR只会跑测试既安全又高效。5.3 Ubuntu服务器部署终极检查清单当你的服务在Ubuntu上跑不起来按这个清单逐项检查99%的问题都能定位Docker服务状态sudo systemctl status docker确保是active (running)。如果不是执行sudo systemctl start docker。Docker镜像是否存在docker images | grep ai-meeting-parser确认镜像已拉取。如果没有执行docker pull