在用Qoder开发几个web tools之后，发现一堆东西扔的到处都是，无法集中展现、修改也是一团乱麻。所以，我就将做好的工具集合到一块，然后使用统一的接口引入，这样也方便修改。

2026.06 北京·丰台·丽泽商务区

环境准备

安装 Claude Code

Claude Code 是 Anthropic 推出的命令行 AI 编程助手，可以直接在终端中与 AI 对话来编写、修改和调试代码。安装非常简单：

# 需要 Node.js 18+ 环境
npm install -g @anthropic-ai/claude-code

安装完成后，在项目目录下执行 claude 即可进入交互式会话。Claude Code 能读写文件、执行命令、搜索代码库，本质上就是一个拥有完整开发工具链的 AI 程序员。

对接 DeepSeek

Claude Code 原生支持 Anthropic API，但也可以通过 OpenAI 兼容协议对接国产大模型。鹊随金印项目中 AI 功能（文本纠错、格式识别、智能文件名等）使用的是 DeepSeek v4 Flash，配置方式如下：

# .env 文件
DOCSTAMP_DEEPSEEK_API_KEY=sk-xxxxxx
AI_API_URL=https://api.deepseek.com/v1
AI_MODEL=deepseek-chat

未配置 API Key 时，所有 AI 功能自动降级——返回原文而非报错，这种「可选增强」的设计让工具在任何环境下都能正常运行。

配置 Skills

Skills 是 Claude Code 的扩展能力包，以 Markdown 文件的形式教会 AI 如何执行特定任务。在 .claude/ 目录下放置 Skill 文件，Claude Code 启动时自动加载。本项目配置了前端设计、代码审查等 Skill，让 AI 在生成代码时自动遵循 Flat Design 设计语言、WCAG 2.1 无障碍标准等项目规范。

Vibe Coding

总结

先说结果，其实我也没想到最后一个办公工具集会有如此庞大的代码量。

分类 行数
后端 Python（14 services + 15 blueprints + utils） 6,727
前端 Vue（16 pages + 20 components） 3,938
前端 TypeScript（6 composables + 2 plugins + config） 1,274
前端 CSS（main.css） 122
测试（pytest + vitest） 747
i18n 翻译（zh-CN + en） 786
文档（SPEC + README + CLAUDE） 2,367
Docker/Shell（5 compose + install + manage + publish） 1,440

核心应用代码：~12,800 行（不含文档/配置/翻译）。含全部约 17,400 行

寻找需求

作为一个 IT 售前和运维工程师，日常工作中有大量文档处理需求：Markdown 写的工作方案要转成符合 GB/T 9704-2012 标准的公文、PDF 需要加水印或去水印、多个 Excel 表格需要合并、视频要转成 WMV 格式才能嵌入 PPT……这些操作分散在不同工具之间，每次都要来回切换。

最初我只是用 Qoder 做了几个独立的 Web 小工具，用一段时间后发现工具越做越多，扔得到处都是，代码散落、接口不统一、修改起来一团乱麻。于是萌生了做一个一站式文档处理工具箱的想法——把做好的工具集合到一块，使用统一的接口引入，方便展示和修改。这就是「鹊随金印」的由来。

需求梳理下来，核心功能定为 13 个模块：MD 转公文、文档转 MD、水印管理、属性修改、Excel 合并、格式规范、文件组装、打印分组、PDF 编辑、调整 PDF、PDF 合并、视频转换、使用统计。定位也很明确：单体工具，无用户系统，无认证，即开即用，随用随走。

UX/UI 设计

Vibe Coding 的设计阶段，我直接让 AI 根据需求生成了完整的 UI 规范。项目采用 Flat Design（扁平化设计） 风格，定义了完整的设计 Token 体系：

  • 品牌色：#008A3D（绿鹃绿）作为主色，#F9F7E8（米黄）作为页面底色，整体走「暖纸」色调
  • 字体：Plus Jakarta Sans + PingFang SC / Microsoft YaHei，中西文混排
  • 布局：左侧 240px 可折叠侧边导航 + 右侧内容区，移动端（<1024px）切换为悬浮遮罩模式
  • 仪表盘：7 段数码管 LED 数字时钟 + 工具卡片网格（3 列）
  • 无障碍：全局 :focus-visible 轮廓、skip-to-content 跳转、prefers-reduced-motion 适配、最小触摸目标 44×44px

前端使用 Nuxt 3 + Nuxt UI v2 + Tailwind CSS v3 技术栈，所有 UI 文本通过 $t() 实现中英文双语，颜色统一走 CSS 变量，禁止硬编码。组件库直接复用 Nuxt UI v2 的 UFormGroup、UButton、UTabs 等原子组件，图标使用 Heroicons。

这套设计系统的关键在于一开始就让 AI 建立完整的设计规范文档（SPEC.md），后续的每个功能模块都在同一套 Token 和组件体系下开发，视觉一致性自然就保持了。

实施编码

编码过程是典型的 Vibe Coding 模式：我描述需求，AI 写代码，我审查修改。 整个过程大致分为几个阶段：

第一阶段：架构搭建。 先让 AI 建立项目骨架——后端 Flask 工厂模式（app.py 不到 70 行，只做蓝图注册和 SPA fallback）、前端 Nuxt 3 SPA 配置、Celery 异步任务框架。核心的分层原则从第一天就定好了：Blueprint 层只做 HTTP 请求/响应，Service 层是零 Flask 依赖的纯函数，所有 Service 函数强制返回 ServiceResult[T]，全局异常拦截输出标准化 JSON。

第二阶段：功能逐个实现。 从最初的 5 个核心功能（MD 转公文、水印管理、属性修改、文件组装、打印分组）开始，每个功能按「Service → Blueprint → 前端页面 → i18n」的顺序实现。后来通过多次迭代，逐步扩展到 13 个功能模块，后端也从最初一个 1278 行的 app.py 拆分成了 15 个独立 Blueprint + 14 个 Service。

第三阶段：生产加固。 这部分是让 AI 做得最爽的部分——文件安全三层校验（大小限制/扩展名白名单/魔数签名）、IP 级别速率限制、AES-256 加密、Celery 3 队列隔离、JSON 结构化日志、操作审计、Pydantic v2 参数校验……这些工程化能力只需要用自然语言描述需求，AI 就能生成符合规范的完整实现。

整个编码过程中，CLAUDE.md 文件扮演了「AI 工作手册」的角色——项目结构、命名规范、Service 层规范、前端规范、设计 Token 全部写在里面，Claude Code 每次启动时自动加载，确保生成的代码始终符合项目标准。

运行测试

测试环节同样交给 AI 完成。后端使用 pytest，针对关键 Service 编写单元测试。以 v3.6 版本为例，为 video_converter、pdf_merger、properties、metadata_cleaner 四个 Service 编写了 12 条测试，过程中还发现了 3 个未处理的异常：read_properties 缺少 FileNotFoundError 处理、clean_metadata 缺少 FileNotFoundError 处理、modify_properties 缺少 PackageNotFoundError 处理——这些都是人工审查容易遗漏的边界情况。

前端使用 npm run build 做构建验证，确保所有页面和组件能正确编译。执行方式很简单：

./manage.sh test              # 后端 pytest
cd frontend && npm run build  # 前端构建验证

Code Review

Code Review 贯穿整个开发过程。我主要依赖两种方式：

一是Claude Code 内置的审查能力。每次较大改动后，让 AI 对自己的代码做一轮 Review，重点检查逻辑 Bug 和安全漏洞。实际效果不错——transition: all 违规、API 错误处理中 .text() + JSON.parse 手动拼接的问题、CSS 变量名拼写错误等，都是 Code Review 阶段发现的。

二是版本发布前的全量审查。每个大版本发布前，我会让 AI 对照 SPEC.md 和 CLAUDE.md 做一次全面检查，确保新增功能符合规范、没有引入死代码、i18n 翻译完整。v3.5.1 的全量审查就发现了 AppHeader.vue、ButtonPrimary.vue、ProgressBar.vue 三个已废弃但未删除的组件，以及多处硬编码颜色值。

这种「AI 写码 + AI 审码」的循环，让代码质量保持在较高水平，同时也暴露了一些 AI 编程的典型问题：批量替换时只改定义不改引用、变量名前后不一致、版本号遗漏更新等——这些都需要人工把关。

部署上线

鹊随金印提供了完整的部署方案，从开发到生产全覆盖：

本地开发用 manage.sh start 启动 Flask + Nuxt 双进程，支持 HMR 热更新。Docker 部署提供 Full（6 容器：API + Redis + 3×Celery Worker + Beat）和 Lite（3 容器：API + Redis + 合并 Celery）两种模式，Full 模式适合 4GB+ 服务器，Lite 模式适配 2C2G 低配 ECS。所有容器均配置健康检查，以非 root 用户 docstamp 运行。

裸机部署通过 install.sh 一键安装 Systemd 服务，Lite 模式包含 Redis + API + Celery + Beat 四个服务，并做了 12 项安全加固（NoNewPrivileges、ProtectSystem=strict、PrivateTmp 等）。

发布流程用 publish.sh 完成构建 → 推送阿里云 ACR → ECS 拉取镜像的完整链路，ECS 端无需编译前端。Nginx 做反向代理，/_nuxt/ 静态资源设置 1 年强缓存，API 请求转发到 Gunicorn。

最终项目部署在了一台 2C2G 的 ECS 上，Lite 模式内存占用约 800MB，运行稳定。从 v1.0 的 Buefy + Flask 5 功能初始版本，到 v3.6 的 Nuxt 3 + Flask 13 功能完整版，整个过程不到一个月——这就是 Vibe Coding 的效率。