企业官网建设流程全解析

AI CLI工具项目复盘：从Python脚本到跨平台分发包的产品化之路

一、从"给我写个脚本"到"可以公开发布"

一切从一句"帮我写个脚本"开始：每天需要把本地Markdown文件中的Mermaid图表自动渲染为PNG并嵌入文档。Python脚本15分钟写完，能用。但很快需求扩展——需要支持批量处理、自定义主题、导出PDF。脚本从50行膨胀到400行，开始在同事之间传阅。某天有人问："这玩意能不能brew install？"

这句话开启了从脚本到产品的产品化过程。技术本质没变——调用mermaid-cli渲染图表。但用户体验的期望从"我能跑"变成了"我能install"、"我能配置"、"我能CI集成"。

二、从Python脚本到独立二进制

第一步：PyPI发布 —— 让Python用户能装

将脚本改造成标准的Python包结构：

mmd-render/ setup.py mmd_render/ __init__.py cli.py renderer.py themes/ README.md

# setup.py from setuptools import setup, find_packages setup( name="mmd-render", version="0.1.0", packages=find_packages(), install_requires=["click", "playwright"], entry_points={ "console_scripts": [ "mmd-render=mmd_render.cli:main", ], }, python_requires=">=3.9", )

发布到PyPI后，用户只需pip install mmd-render即可使用。但问题随之而来：有些用户没有Python环境，或Python版本不对（系统自带Python 3.7，需要3.9+）。"这工具很好，但我装不上"——这是用户的原话。

第二步：PyInstaller打包 —— 消除Python依赖

PyInstaller能将Python脚本打包为独立可执行文件（包含Python解释器和所有依赖）：

pip install pyinstaller pyinstaller --onefile --name mmd-render cli.py

生成的单个二进制文件约25MB（主要是Playwright的浏览器内核），但不需要任何Python环境。在GitHub Release中为三个平台提供下载：

• mmd-render-darwin-amd64
• mmd-render-darwin-arm64
• mmd-render-linux-amd64

第三步：包管理器分发 —— 消除"下载zip"的摩擦

"curl下载→chmod→移动到PATH"的三步安装在开发者社区是不容忽视的摩擦。接入包管理器：

# Homebrew Formula class MmdRender < Formula desc "Render Mermaid diagrams from Markdown files" homepage "https://github.com/user/mmd-render" url "https://github.com/user/mmd-render/releases/download/v0.2.0/mmd-render-darwin-arm64" sha256 "abc123..." version "0.2.0" def install bin.install "mmd-render-darwin-arm64" => "mmd-render" end test do system "#{bin}/mmd-render", "--version" end end

brew install mmd-render——一行命令搞定安装。安装量从PyPI的约200次/月增长到brew+PyPI合计约1200次/月。

三、CLI的用户体验设计

命令设计的渐进式暴露：

# 简单路径：零配置即可用 mmd-render docs/ # 中级路径：常用参数 mmd-render docs/ --theme dark --output-dir rendered/ --watch # 高级路径：配置文件 mmd-render docs/ --config mmd-render.yml

配置文件支持（.mmd-render.yml或mmd-render.yml）：

theme: dark output_format: png scale: 2 watch: true # CI模式——非交互，失败即退出 ci: false # 排除模式 exclude: - "**/node_modules/**" - "**/.git/**"

错误信息的友好化：

# 用户犯错时，不报Python Traceback，而是给出清晰的诊断 def validate_input(path: str): if not os.path.exists(path): click.echo(f"错误: 路径 '{path}' 不存在", err=True) click.echo("提示: 检查路径是否正确，或使用 --help 查看用法") sys.exit(1) mermaid_files = glob.glob(os.path.join(path, "**/*.md"), recursive=True) if not mermaid_files: click.echo(f"警告: 在 '{path}' 中未找到Markdown文件", err=True) sys.exit(0)

四、产品化过程中的坑

坑1：Playwright依赖的大小问题。mermaid-cli依赖Playwright的Chromium内核（约150MB）。PyInstaller打包后二进制从3MB膨胀到25MB，GitHub Release的单文件限制（2GB）虽然没触及，但用户下载体验明显变差。方案：将Chromium作为外部依赖——如果系统已安装Chromium则复用，否则提示安装。

坑2：Homebrew Formula的审核流程。提交Homebrew Formula需要满足严格的审核标准：必须有test do块、依赖声明完整、无网络请求、无sudo。第一次提交因为缺少test do被拒。

坑3：版本管理的语义化。早期版本号随意（0.1.2→0.1.3a→0.1.3b），导致用户和CI脚本难以追踪。引入SemVer + 自动发布：Git Tag → GitHub Actions → 构建→ PyPI + GitHub Release。

五、总结

从脚本到产品的产品化过程，核心经验：

• 包管理器分发（brew/pip/npm）是CLI工具分发的最佳方式——"一行命令安装"是准入门槛
• 独立二进制消除了Python版本依赖——打包后的25MB对用户的便利性是值得的
• CLI设计遵循"渐进式暴露"——零配置可用，高级功能可配，CI模式可脚本化
• 错误信息不要暴露Traceback——用户要的是诊断，不是调试信息
• SemVer + 自动发布是可持续维护的基础

最大的教训：从脚本到产品最大的工作量不在代码（400行Python扩展到了约800行），而在分发。PyPI搭建、Homebrew Formula编写、GitHub Actions CI配置、多平台测试——这些"非代码工作"约占总工期的60%。如果知道最终要公开发布，应该从一开始就按标准Python包组织代码，避免后续重构。