@ssbun/venom-cli

v2.3.0

Published

a month ago

CLI tool for Zhihu iOS development. Wraps make commands for project builds.

0High
0Medium
0Low

ssbun

venom-cli 中文详细说明

本文基于当前仓库代码生成，适用于 @ssbun/venom-cli 2.3.0。

venom-cli 是面向知乎 iOS 开发的命令行工具。它把常用的工程构建、组件依赖切换、环境检查、设备选择、资源代码生成等操作收敛到一个 CLI 中，减少直接手写 make、xcodebuild、git clone、customization.yml 修改和资源访问代码生成的重复工作。

适用场景

检查本机 iOS 开发环境是否满足 Venom 工程要求。
在项目中执行二进制依赖或源码依赖的 make。
编译 Xcode workspace/project，并可选择设备或模拟器运行。
管理本地组件仓库与 Venomfiles 中组件的集成关系。
生成组件资源图片和字符串的 Objective-C 访问代码。
查看构建历史统计。
保存常用项目路径和组件仓库目录。

安装与本地开发

全局安装：

npm install -g git+ssh://[email protected]/Team-iOS-Platform/venom-cli.git

本仓库本地开发：

npm install
npm link
venom-cli --help

运行要求：

Node.js ^20.17.0 || ^22.13.0 || >=23.5.0
rbenv
Ruby 2.7.3
CocoaPods 1.16.2
Git
Xcode / Xcode Command Line Tools
可访问 [email protected]

全局用法

venom-cli [options] [command]

全局选项：

| 选项 | 说明 | | --- | --- | | -v, --version | 输出当前 CLI 版本 | | -p, --project <path> | 指定项目目录，默认使用当前目录 | | -h, --help | 输出帮助信息 |

-p, --project 可以传入真实路径，也可以传入通过 venom-cli config projects add 保存过的项目名称。CLI 会优先在配置的 projects 中按名称查找，找不到时再按路径解析。

示例：

venom-cli -p /Users/me/apps/osee2unified doctor
venom-cli -p osee build --scheme OSee --run

配置文件

配置文件位置：

~/.venom/config.json

默认配置：

{
  "componentFolders": [],
  "projects": []
}

常用配置项：

| 配置项 | 类型 | 用途 | | --- | --- | --- | | componentFolders | 字符串数组 | 本地组件仓库父目录，integrate clone 会默认克隆到第一个目录下 | | projects | 对象数组 | 保存常用项目名和路径，供全局 -p 使用 | | lastDevice | 对象 | build 记录上次选择的设备，后续可自动复用 | | lastScheme | 对象 | build 按项目记录上次使用的 scheme；未指定 --scheme 时自动复用 |

配置命令：

venom-cli config
venom-cli config list
venom-cli config get componentFolders
venom-cli config set componentFolders /Users/me/components,/Users/me/other-components
venom-cli config projects add osee /Users/me/apps/osee2unified
venom-cli config projects list
venom-cli config projects remove osee

不带子命令的 venom-cli config 会进入交互式配置界面，可管理保存的项目和组件目录。

命令总览

| 命令 | 用途 | | --- | --- | | make | 在项目中执行 make all_binary | | make-source | 在项目中执行 make all_source | | doctor | 检查 Venom 所需环境 | | devices | 列出真机、已启动模拟器和可用模拟器 | | build | 编译 Xcode 工程，可安装并启动 App | | test | 运行 Xcode 测试 | | clean | 清理 Xcode DerivedData，可清理 CocoaPods 缓存 | | stats | 查看 build、make、make-source 使用统计 | | config | 管理 CLI 配置 | | integrate | 管理组件集成、克隆、切换和状态 | | gen-asset-code | 生成资源图片和字符串访问代码 |

环境检查：doctor

venom-cli -p <project> doctor
venom-cli -p <project> doctor --fix

检查项：

rbenv
目标项目通过 rbenv 选择的 Ruby 版本是否为 2.7.3
目标项目 Ruby 环境中的 CocoaPods 是否为 1.16.2
Homebrew
Git
Xcode
项目目录或一层子目录中是否存在 Makefile
到 [email protected] 的 SSH 访问

--fix 会尝试安装或修复部分依赖，例如安装 rbenv、安装 Ruby 2.7.3 并将其配置为目标项目的本地版本、在该 Ruby 环境中安装 CocoaPods 1.16.2。该选项会改动本机环境，运行前应确认你确实希望自动修复。

构建依赖：make / make-source

venom-cli -p <project> make
venom-cli -p <project> make-source

make 会查找项目目录或一层子目录中的 Makefile，然后执行：

make all_binary

make-source 执行：

make all_source

选择建议：

只验证普通代码改动能否编译：优先用 build。
添加或删除文件、修改 podspec 依赖、需要重新生成 Podfile/Pods：使用 make 或 make-source。
希望走二进制缓存：使用 make。
希望全部从源码编译：使用 make-source。

副作用：

会执行项目自己的 Makefile 逻辑。
通常会触发 CocoaPods 相关流程。
成功时会写入 ~/.venom/history.jsonl，用于 stats 统计。
成功或失败时会输出彩色日志；检测到 Nokogiri 构建失败时会打印修复提示。

设备列表：devices

venom-cli devices
venom-cli devices --format json

数据来源：

xcrun xctrace list devices
xcrun simctl list devices booted
xcrun simctl list devices available

表格输出会分组显示：

已连接真机
已启动模拟器
可用模拟器

JSON 输出结构包含：

{
  "physicalDevices": [],
  "bootedSimulators": [],
  "availableSimulators": []
}

编译与运行：build

venom-cli -p <project> build
venom-cli -p <project> build --scheme OSee
venom-cli -p <project> build --scheme OSee --run
venom-cli -p <project> build --scheme OSee --run --debug
venom-cli -p <project> build --scheme OSee --verbose
venom-cli -p <project> build --scheme OSee --reconnect

选项：

| 选项 | 说明 | | --- | --- | | --scheme <name> | 指定 Xcode scheme，并作为该项目下次构建的默认 scheme | | --run | 编译成功后安装并启动 App | | --debug | 配合 --run 使用，把 App 控制台日志写入 ~/.venom/logs/ | | --verbose | 输出完整构建日志 | | --reconnect | 忽略上次设备记录，重新选择设备 |

工作流程：

在项目目录或一层子目录中查找 .xcworkspace，找不到则查找 .xcodeproj。
通过 xcodebuild -list 获取 schemes。
未指定 --scheme 时，若该项目上次使用的 scheme 仍存在则自动复用；否则如果只有一个可用 scheme 自动选择，多个 scheme 时进入交互选择。
通过 xcodebuild -showdestinations 获取当前 scheme 兼容的 destinations；上次选择仍在列表中时自动复用，只有一个有效选项时自动选择，否则进入选择器。
--reconnect 会忽略历史 destination 记录并强制重新显示 destination 选择器。
执行 xcodebuild ... build。
成功后记录构建历史；失败时汇总包含 error: 的行。
如果传入 --run，解析构建产物 .app 并安装或启动；iOS 模拟器会先自动启动、等待就绪并显示窗口。

运行目标处理：

iOS 模拟器：使用 xcrun simctl bootstatus -b 自动启动并等待就绪，打开对应设备窗口，再执行 install 和 launch。
iOS 真机：使用 xcrun devicectl device install app，有 bundle id 时可继续 launch。
macOS App：使用 open <app> 启动，启动前会尝试退出旧实例，避免打开旧构建。

调试日志：

日志目录：~/.venom/logs/
日志文件：<scheme>.log
macOS 使用 log stream --predicate 'process == "<executable>"'。
真机 debug 使用 xcrun devicectl ... --console。
监控时按 t 可打开 tail -f -100 <log>，按 Ctrl+C 停止监控。
旧日志会做简单清理：删除 7 天前日志，最多保留 10 个 .log 文件。

额外行为：

构建后会尝试结束 Xcode 构建相关守护进程并清理 stale PIFSessionLock，降低 Xcode 打开项目时被锁住的概率。

运行测试：test

venom-cli -p <project> test
venom-cli -p <project> test --scheme OSeeTests
venom-cli -p <project> test --scheme OSeeTests --verbose

选项：

| 选项 | 说明 | | --- | --- | | --scheme <name> | 指定测试 scheme | | --verbose | 在未发现测试或需要诊断时输出更多 xcodebuild 尾部日志 |

行为：

查找 .xcworkspace 或 .xcodeproj。
通过 xcodebuild -list 获取 schemes，并过滤掉部分 Pods scheme。
选择测试 destination 时使用模拟器。
执行 xcodebuild ... test。
从输出中统计 passed、failed、total，并列出失败测试。
成功或失败都会发送本机通知。

清理缓存：clean

venom-cli -p <project> clean
venom-cli -p <project> clean --all
venom-cli -p <project> clean --pods

选项：

| 选项 | 说明 | | --- | --- | | --all | 删除整个 ~/Library/Developer/Xcode/DerivedData | | --pods | 在清理当前项目 DerivedData 后，同时删除 ~/Library/Caches/CocoaPods |

默认模式只会根据项目目录名匹配并删除对应的 DerivedData 子目录。--all 会删除全部 DerivedData，影响范围更大。

使用统计：stats

venom-cli stats
venom-cli stats --days 7
venom-cli stats --command build
venom-cli stats --format json

数据文件：

~/.venom/history.jsonl

当前会记录成功的 build、make、make-source。统计内容包括：

最近运行记录
按命令分组的运行次数
成功次数和成功率
平均耗时、最短耗时、最长耗时
JSON 模式下输出总数、成功数、按命令聚合和最近 10 条记录

组件管理：integrate

integrate 是组件管理的主入口，围绕项目中的 Venomfiles / venomfiles 目录和 customization.yml 工作。

venom-cli -p <project> integrate
venom-cli -p <project> integrate list
venom-cli -p <project> integrate switch <pod-name> --local /path/to/pod
venom-cli -p <project> integrate clone <pod-name>
venom-cli -p <project> integrate remove <pod-name>
venom-cli -p <project> integrate status

组件数据来源

CLI 会在项目目录内最多向下搜索 3 层，查找：

Venomfiles/
venomfiles/

组件基础信息来自这些目录中的 .rb 文件：

v.name
v.version
v.git
v.tag
v.branch
v.commit
v.path
v.binary
v.subspecs

开发态覆盖来自：

customization.yml
customization.json

本地仓库匹配来自配置中的 componentFolders。如果某个组件名和组件目录下的 Git 仓库目录同名，会被标记为有本地仓库。

组件状态字段：

| 字段 | 说明 | | --- | --- | | name | 组件名 | | version | 当前版本、分支、commit 或本地路径 | | versionKind | tag、branch 或 localPath | | isDeveloping | 是否在 customization 中有覆盖 | | localPath | 匹配到的本地组件路径 | | branchName | 本地 Git 分支名 | | repositoryURL | Venomfile 中的 Git 地址 | | originalVersion | 开发态组件原始版本 | | category | Venomfiles 中的相对分类目录 |

交互模式

venom-cli -p <project> integrate

首次使用且未配置 componentFolders 时，会询问本地组件仓库父目录并写入配置。

交互模式支持搜索组件，组件分组为：

Developing：已经在 customization.yml 中覆盖的组件。
Others：未覆盖的组件。

根据组件状态提供不同动作：

| 状态 | 可用动作 | | --- | --- | | developing | Deintegrate、Open in Finder、Show Git Status | | local | Integrate、Open in Finder、Show Git Status | | remote | Clone、Clone & Integrate |

动作副作用：

Integrate / Clone & Integrate 会写入 customization.yml。
Deintegrate 会从 customization.yml 删除对应组件。
Clone 会执行 git clone 到第一个 componentFolders 目录。
Open in Finder 会调用 open <path>。

列出组件：integrate list

venom-cli -p <project> integrate list
venom-cli -p <project> integrate list --filter ZHHome
venom-cli -p <project> integrate list --format json

选项：

| 选项 | 说明 | | --- | --- | | --format <format> | table 或 json，默认 table | | --filter <text> | 按组件名、版本或分支过滤 | | --all | 当前为默认行为，展示全部组件 |

表格输出会优先显示 Developing 组件，再显示 Others。

切换组件来源：integrate switch

venom-cli -p <project> integrate switch <pod-name> --local /path/to/pod
venom-cli -p <project> integrate switch <pod-name> --binary
venom-cli -p <project> integrate switch <pod-name> --source
venom-cli -p <project> integrate switch <pod-name> --branch feature/foo
venom-cli -p <project> integrate switch <pod-name> --tag 1.2.3
venom-cli -p <project> integrate switch <pod-name> --commit abc1234

规则：

每次必须且只能提供一个切换选项。
组件名必须存在于 Venomfiles。
--local 的路径必须存在，并且目录内需要有 .podspec 或 VenomFile。
成功后写入 customization.yml。

写入示例：

ZHExample:
  path: /Users/me/components/ZHExample

克隆组件：integrate clone

venom-cli -p <project> integrate clone <pod-name>
venom-cli -p <project> integrate clone <pod-name> --integrate

行为：

从 Venomfiles 中找到组件的 Git 地址。
读取 componentFolders 的第一个目录。
克隆到 <componentFolders[0]>/<pod-name>。
如果传入 --integrate，同时写入 customization.yml。

保护：

找不到 Venomfiles 会失败。
找不到组件 Git 地址会失败。
未配置 componentFolders 会失败。
目标目录已存在且非空会失败。

移除组件开发态：integrate remove

venom-cli -p <project> integrate remove <pod-name>

行为：

从 customization.yml 删除对应组件。
如果组件不在 customization.yml 中，命令失败。

查看组件 Git 状态：integrate status

venom-cli -p <project> integrate status
venom-cli -p <project> integrate status --format json

该命令只关注有本地 Git 仓库的组件。输出字段包括：

组件名
状态：developing 或 local
当前分支
dirty 文件数量
untracked 文件数量
ahead / behind
本地路径

资源代码生成：gen-asset-code

venom-cli gen-asset-code --path /path/to/component
venom-cli gen-asset-code --path /path/to/component --type resource
venom-cli gen-asset-code --path /path/to/component --type string
venom-cli gen-asset-code --type all

选项：

| 选项 | 说明 | | --- | --- | | --path <path> | 组件目录；省略时从当前目录向上查找 .xcassets 或 .xcodeproj | | --type <type> | all、resource 或 string，默认 all |

目录要求：

目标组件内需要能找到包含 Resources 的目录。
图片生成会扫描 Resources 下的 .xcassets。
字符串生成会递归扫描 .strings 文件。

图片代码生成：

每个 .xcassets 生成一组 .h / .m。
生成类名基于 .xcassets 文件名。
如果 bundle 名不以 Image 或 Resource 结尾，输出文件名会追加 Image。
会识别夜间图候选命名：Night_<name>、zhimg_<name>_night、<name>_night。
生成类继承 ZHImageModel。

字符串代码生成：

每个 .strings 文件生成同名 .h / .m。
key 中的 . 会转换成方法名中的 _。
如果存在 .xcassets，会用其名称推导 bundle 名。

副作用：

会直接在 Resources 目录写入或覆盖生成的 .h / .m 文件。
生成代码带有 do not edit manually 注释。

废弃命令

以下命令仍然存在，但在 CLI 中被隐藏，并会打印废弃提示：

| 旧命令 | 替代命令 | | --- | --- | | components | integrate list | | switch | integrate switch | | status | integrate status |

新脚本和新文档应使用 integrate 子命令。

常见工作流

第一次使用

venom-cli doctor
venom-cli config projects add osee /Users/me/apps/osee2unified
venom-cli config set componentFolders /Users/me/components
venom-cli -p osee integrate list

查看并接入本地组件开发

venom-cli -p osee integrate list --filter ZHExample
venom-cli -p osee integrate clone ZHExample --integrate
venom-cli -p osee make
venom-cli -p osee build --scheme OSee

如果组件仓库已经在本地：

venom-cli -p osee integrate switch ZHExample --local /Users/me/components/ZHExample
venom-cli -p osee make
venom-cli -p osee build --scheme OSee

退出组件开发态

venom-cli -p osee integrate remove ZHExample
venom-cli -p osee make

或者显式切回二进制：

venom-cli -p osee integrate switch ZHExample --binary
venom-cli -p osee make

普通代码改动后验证

venom-cli -p osee build --scheme OSee

需要启动 App：

venom-cli -p osee build --scheme OSee --run

需要采集日志：

venom-cli -p osee build --scheme OSee --run --debug

添加资源后生成代码

venom-cli gen-asset-code --path /Users/me/components/ZHExample --type all
venom-cli -p osee make
venom-cli -p osee build --scheme OSee

选择 build、make、make-source 的原则

| 场景 | 建议命令 | | --- | --- | | 只改 Swift / Objective-C 代码 | build | | 只想快速验证编译错误 | build | | 添加或删除源码文件 | make 或 make-source | | 修改 podspec 依赖 | make 或 make-source | | 修改 customization.yml 后需要重新集成 Pods | make 或 make-source | | 生成资源代码后要让工程纳入新文件 | make 或 make-source | | 怀疑二进制缓存问题 | make-source |

最小原则：能用 build 验证时先用 build；只有工程结构、依赖或 Pods 集成需要刷新时再用 make / make-source。

重要文件与副作用汇总

| 路径 | 用途 | | --- | --- | | ~/.venom/config.json | CLI 配置 | | ~/.venom/history.jsonl | 构建和 make 成功历史 | | ~/.venom/logs/ | build --run --debug 日志 | | <project>/Venomfiles/ 或 <project>/venomfiles/ | 组件定义 | | <Venomfiles>/customization.yml | 组件开发态覆盖 | | ~/Library/Developer/Xcode/DerivedData | clean 清理目标 | | ~/Library/Caches/CocoaPods | clean --pods 清理目标 |

高风险或写操作：

doctor --fix：可能安装或改动本机 Ruby/CocoaPods/Homebrew 相关环境。
make / make-source：执行项目 Makefile，通常会影响 Pods 和构建缓存。
build --run：会安装或启动 App。
clean --all：删除全部 Xcode DerivedData。
clean --pods：删除 CocoaPods 缓存。
integrate switch / integrate remove / integrate clone --integrate：写入 customization.yml。
integrate clone：执行 git clone。
gen-asset-code：写入或覆盖生成的 .h / .m 文件。

排查建议

找不到项目：确认 -p 指向包含 .xcworkspace、.xcodeproj、Makefile 或 Venomfiles 的项目根目录。
找不到组件：先运行 venom-cli -p <project> integrate list --format json，确认 Venomfiles 是否被解析。
克隆组件失败：确认 componentFolders 已配置、目标目录不存在或为空、Git SSH 权限可用。
构建目标选错：使用 --reconnect 重新选择设备。
scheme 不存在：运行 venom-cli -p <project> build 让 CLI 列出可选 scheme，或检查 Xcode scheme 是否共享。
make 报 Nokogiri 错误：根据命令输出中的提示配置 Nokogiri build 参数。
资源代码未更新进工程：生成资源代码后运行 make，让工程重新集成文件。

当前实现边界

findFile 只查项目根目录和一层子目录中的 .xcworkspace / .xcodeproj。
make 只查项目根目录和一层子目录中的 Makefile。
findVenomfilesDir 最多向下搜索 3 层。
integrate clone 固定使用第一个 componentFolders 作为克隆父目录。
integrate list --all 当前等同默认展示全部组件。
构建历史当前只记录成功的 build、make、make-source。