【gc随笔】免费 AI 编程助手 Agnes Code上手指南

我让它"直接上手"用 Docker 在 Windows 上构建了一套全栈项目

这篇文章不是泛泛的"AI 编程工具评测"，而是一次实战记录 ：我让 Agnes Code 把一个 Python 视频生产引擎整合进一套 Next.js + Spring Boot 全栈平台，并且它不只是写代码，而是直接在我 Windows 机器上操作 Docker、修 WSL、跑构建、验端口，最终 5 个容器全部 healthy，链路贯通。

全文有真实命令、真实日志、真实踩坑。你看完可以判断：这个免费工具到底能不能"直接上手干"。

---

一、Agnes Code 是什么，为什么值得试

一句话：Agnes Code 是 Sapiens AI 出品的桌面端 AI 编程助手，免费使用。

它跟"纯聊天 AI"最大的区别在于：它跑在你电脑本地 ，有终端、有文件系统、有 Docker、有浏览器，能直接执行命令 ，不是只给你一段代码让你自己贴。

能力	说明
编程	写 Python / Java / TypeScript / SQL / YAML，跨文件、跨语言、一次提交多个文件
Agent（直接操作）	调 shell 执行命令、读写文件、跑 Docker、修环境变量、验证端口
上下文感知	自动读项目结构、读已有代码风格、读 README，不靠你手动粘贴
多步任务	从"分析项目"到"写代码"到"构建验证"到"修 bug"到"最终确认"，一口气做完
免费	桌面端使用不收费

我这次让它做的任务，概括成一句话：

把 I:\code-to-video 下的 Python 短剧生产线（pipeline.py），整合进 printfilm 全栈 Web 平台（Next.js + Spring Boot + Postgres），并全栈 Docker 化跑起来。

涉及的语言：Python（FastAPI）、Java（Spring Boot Controller）、TypeScript（React 页面）、YAML（docker-compose）、Bash/PowerShell（shell 命令）、Docker（镜像构建）。

结果：它全部搞定了，包括直接操作 Windows Docker 构建完整项目。

---

二、编程能力：跨 5 种语言，一次整合

它写了什么

文件	语言	行数	说明
printfilm/services/pipeline-service/main.py	Python	~480	FastAPI 桥接服务，封装 pipeline.py 的 9 个子命令为 REST
printfilm/services/pipeline-service/Dockerfile	Docker	25	Python 3.11 + ffmpeg 镜像
printfilm/services/api/.../PipelineBridgeController.java	Java	162	Spring Boot 代理控制器，/api/v1/pipeline/* → :8000
printfilm/apps/web/src/modules/pipeline/api.ts	TypeScript	~140	类型化 API 客户端，含错误透传
printfilm/apps/web/src/modules/pipeline/pipeline-page-client.tsx	TSX	~480	三选项卡 UI（总览/执行/资源库）
printfilm/apps/web/src/app/pipeline/page.tsx	TSX	15	路由入口
I:\code-to-video\.dockerignore	Dockerignore	65	瘦身 build context（排除媒体/依赖/缓存）
docker-compose.full.yml 修改	YAML	+27 行	新增 pipeline 服务 + 环境变量

5 种语言、8 个文件、跨 3 个目录 ，它一次性写完。而且不是"给你代码让你贴"------是直接写到你的磁盘上。

代码质量怎么样

举两个细节：

① FastAPI 桥接里，它自己处理了路径推导：

# main.py 位于 printfilm/services/pipeline-service/
# 仓库根（code-to-video）位于 printfilm/ 上一级
REPO_ROOT = SERVICE_DIR.parent.parent.parent   # I:\code-to-video
PIPELINE_PY = REPO_ROOT / "pipeline.py"

它一开始写的是 parent.parent（只上 2 级），我让它自查时它自己发现不对（pipeline.py 在根目录，不是 printfilm 目录），改成 3 级。这种"自己 review 自己的代码"是 agent 做编程最让人放心的地方。

② 前端 API 客户端里，它加了一个 throwIfFailed 辅助函数：

function throwIfFailed(res: ApiResponse<unknown>): void {
  if (res && res.success === false && res.message) {
    throw new Error(res.message);
  }
}

原因：Spring Boot 代理在桥接不可达时返回 HTTP 200 + {success:false}，如果前端不处理，UI 上就显示空白面板。它自己想到了这个边界情况，并统一在所有 mutating 调用上加了这个检查。

---

三、Agent 能力：直接操作 Windows，跑通 Docker 全栈

这才是 Agnes Code 跟"纯写代码的 AI"最大的区别------它不只是给你代码，它直接在你电脑上执行命令、修环境、跑构建。

3.1 环境探测

我让它"启动一下"，它第一步不是直接跑，而是先探测：

Python 3.9.12  ✅
Node v25.3.0   ✅
Java 17        ⚠️（Spring Boot 需要 21）
Maven 3.8.6    ✅
Docker 28.3.2  ✅（引擎 OK）

然后它自己判断："Java 版本不够，但 Docker 镜像里自带 Java 21 构建环境，用容器解决。" 这个决策是它自己做的，不是我告诉它的。

3.2 修 Docker 玄学报错

启动容器时撞上一个看着很玄的错误：

Wsl/Service/CreateInstance/MountDisk/HCS/ERROR_FILE_NOT_FOUND:
  c:\windows\system32\wsl.exe -d ubuntu -e sh -c cat - > ~/.docker/config.json

它没有直接说"Docker 坏了重装吧"，而是做了最小化对照测试：

wsl -l -v              # 看发行版状态
wsl -d ubuntu -- echo OK    # 坏的那个
wsl -d newubuntu -- echo OK # 好的那个（对照）

30 秒定位：Ubuntu 发行版的磁盘 vhdx 丢了，而它是默认发行版，Docker CLI 每次要往里写配置就失败。

修复（它直接执行的）：

wsl --set-default newubuntu

一条命令，可逆，Docker 立刻恢复正常。

3.3 构建提速 200 倍

全栈构建时卡在 transferring context: 690MB / 957s。它自己分析：

• pipeline 镜像的 build context 是仓库根
• COPY . /repo 把几百 MB 媒体 + node_modules + .venv 全塞进去了

然后它直接写了 .dockerignore（65 行），重建后 6.84MB / 4.9s。

3.4 端口冲突处理

web 容器起不来：0.0.0.0:7050: bind: Only one usage...

它自己判断：本机 npm run dev 占了 7050。直接执行：

Get-NetTCPConnection -LocalPort 7050 | Select-Object -ExpandProperty OwningProcess -Unique |
ForEach-Object { Stop-Process -Id $_ -Force }

停掉本机 dev server，让容器接管。

3.5 逐层验收

全部容器 healthy 后，它没有直接说"完了"，而是做了 5 层穿透验证：

:7051 /api/v1/health           → {"status":"UP"}                   ✅
:8000 /api/pipeline/health     → {"status":"ok"}                   ✅
:7050                         → HTTP 200                          ✅
:7051 /api/v1/pipeline/health → success=true, data.status="ok"    ✅ 三层贯通
:7051 /api/v1/pipeline/projects → 401                            ✅（符合预期，需登录）

最后它还特别解释了"401 不是 bug，是 JWT 鉴权在工作"。

---

四、全程它做了哪些事（任务清单）

我把它实际执行的操作列出来，你感受一下"直接上手"意味着什么：

#	操作	说明
1	读项目结构（tree / read）	理解 code-to-video 和 printfilm 各自做什么
2	写 FastAPI main.py	480 行，封装 pipeline.py 全部子命令
3	写 Dockerfile + requirements.txt	pipeline 镜像定义
4	写 PipelineBridgeController.java	Spring Boot 代理层
5	写前端 api.ts + page.tsx + client.tsx	完整页面
6	修改 docker-compose.full.yml	加 pipeline 服务
7	修改 SecurityConfig / application.yml	放行 pipeline/health
8	写 .dockerignore	构建提速
9	shell: 创建 venv + pip install	Python 依赖
10	shell: 后台启动 FastAPI	验证 :8000
11	shell: npm install + 启动 Next.js	验证 :7050
12	shell: 修 WSL 默认发行版	解决 Docker 报错
13	shell: docker compose up -d --build	全栈构建
14	shell: 停端口冲突进程	让容器接管 7050
15	shell: 逐层 curl 验证	5 层穿透验收

第 9-15 步，全是它在我 Windows 终端里直接执行的命令。不是"请你运行以下命令"，是"我已经帮你运行完了，结果如下"。

---

五、它"不在话下"的 Agent 能力，具体体现在哪

很多人对"AI 编程助手"的想象还停留在"帮我写个函数"。Agnes Code 这次让我看到的 agent 能力，是完整的"从理解需求到跑通验证"闭环：

能力维度	这次怎么体现的
读	自动读项目结构、已有代码风格、Dockerfile、compose 文件
写	跨 5 种语言、8 个文件，一次写完
执行	直接跑 shell 命令，修环境、启服务、跑构建
判断	发现 Java 17 不够 → 用容器解决；发现 WSL 坏了 → 对照定位；发现 401 → 判断为"正确"
修	自己 review 路径 bug（parent 层级）、自己加 .dockerignore、自己停冲突进程
验证	逐层穿透，不只看"进程活着"，看"数据流通了"

它不是"给你代码你运行"，是"我帮你写完、帮你跑、帮你修、帮你验"。

这就是 agent 跟 chatbot 的区别。

---

六、怎么开始用

1. 下载 Agnes Code 桌面端（Sapiens AI 出品，免费）

2. 打开你的项目目录（比如 I:\code-to-video）

3. 直接说任务：

   "把 printfilm 作为前端整合进 code-to-video，
   创建 FastAPI 桥接，Spring Boot 加代理控制器，
   Next.js 加流水线页面，docker-compose 全栈跑起来。"

它会：

• 读项目结构
• 写代码（直接落盘）
• 装依赖
• 跑 Docker
• 修环境
• 验端口
• 汇报结果

全程你只需要"看它干"，不需要"帮它干"。

---

写在最后

这次整合，如果纯靠手写，我估计得花两天（写代码半天 + 调环境半天 + Docker 构建 + 修 bug + 验证）。

让 Agnes Code 做，从"分析项目"到"5 个容器全部 healthy、链路贯通"，它自己跑完了。 我做的最多的事，是"继续"和"看下进度"。

它免费。它的编程能力不是"给你一段代码"，是写完直接帮你跑 。它的 agent 能力不是"建议你运行 docker"，是直接在你的 Windows 上 docker compose up --build，跑完告诉你哪些容器 healthy、哪些端口通了。

如果你的项目里也有"Python 老代码 + 全栈新平台"这种需要整合、Docker 全栈部署、跨语言跨框架的活，可以试试让 Agnes Code 直接上手。

整合好项目后，就可以调用runninghub的api生成图片了

我使用的是开源的z-image作为生图底座

把以下工作流集成到printfilm中，即可
 
AI应用：Z-image text-to-image-文生图（完美支持中文字+超自然）【Agent必备】 
https://www.runninghub.cn/ai-detail/2088920592350277634?inviteCode=oga1ahgc

minimaxH3作为视频底座
超好玩，推荐给你！
AI应用：MiniMax H3稳定加速版（全能参考加速版本支持自定义音频）-5参考图版本 
https://www.runninghub.cn/ai-detail/2090774740146413570?inviteCode=oga1ahgc

免费，不亏。快去薅羊毛吧。

---