@jiufeng/cli

v1.0.5

Published

a month ago

汣风 AI 能力中心跨平台命令行客户端

0High
0Medium
0Low

jiufeng

jiufeng-cli

jiufeng-cli 是汣风 AI 能力中心面向 Windows 和 macOS 的命令行客户端，负责：

使用系统安全存储保存个人 API Key。
查询、下载、校验和安装已授权的 Skill。
为 Codex、Claude Code 和个人版 WorkBuddy 适配安装流程。
在业务调用前执行 CLI 和 Skill 版本检查。
调用汣风后端能力，并保持现有 RBAC 与 API Key scopes 校验。

当前状态

当前源码版本为 1.0.5，上一已发布 npm 版本为 1.0.4。正式安装器的构建、签名和更新链路已经落到代码与流水线，但公司签名证书和 OSS 正式地址尚未配置。

1.0.5 更新

新增 crystal-marketing 能力，支持 product.profile、product.search、content.submit 和 content.status；审核和发布仍由管理后台完成。
内容回传以 --skill-version 为准，输入 JSON 不能覆盖生成版本；写操作要求 --yes，--yes=false 不会提交。
能力与操作名称严格按注册表校验，未知名称返回明确错误。
新增接口适配与 CLI 调用回归测试，安装器测试使用临时目录，避免读取或修改本机已安装 Skill。

水晶营销 Skill 的 min_cli_version 必须设置为 1.0.5。使用前需部署对应后端接口，并在能力中心发布和授权 Skill。npm 发布后，后台 CLI 发布策略的 npmPackageUrl 应同步为 https://registry.npmjs.org/@jiufeng/cli/-/cli-1.0.5.tgz，员工才能通过 jiufeng-cli update 获取公司批准的新版本。

| 项目 | 状态 | 说明 | | --- | --- | --- | | npm 包 | 已发布 | 通过 npm install -g @jiufeng/cli 安装，国内可使用 npmmirror 加速 | | CLI 命令与 Windows x64 开发包 | 可用 | dist/jiufeng-cli-windows-x64.exe 可执行 | | 自动化测试 | 通过 | Skill 安装、更新签名、拍卖操作等测试已覆盖 | | Windows 安装器构建 | 已实现 | Inno Setup 每用户安装器；正式制品仍需公司 Authenticode 签名 | | macOS x64/arm64 安装器构建 | 已实现 | pkg 构建与公证步骤已接入流水线；仍需 Developer ID 证书 | | 正式下载地址 | 未配置 | 本地 release metadata 仍使用示例下载地址 | | 线上完整闭环 | 待部署验证 | 需要部署当前后端并发布 skill_cli_release |

正式交付员工前，必须完成代码签名、真实下载地址、CLI 发布记录和线上 doctor 验证。开发包只能用于内部开发测试。

环境要求

直接使用 SEA 可执行文件时不需要安装 Node.js。
从源码运行或执行测试时需要 Node.js 20.12 或更高版本。
当前只支持 Windows x64、macOS x64 和 macOS arm64。
业务调用需要后台签发的个人 jfak_v1_... API Key。

本地开发

cd jiufeng-cli
npm ci
npm test
node src/main.cjs version --json

将源码命令链接到当前用户的 npm 全局命令目录：

npm link
jiufeng-cli version --json

源码模式不会替换 Node.js 自身。强制自更新只能使用 SEA 发布产物验证。

npm 命令行安装（第一阶段）

员工电脑需要先安装 Node.js 20.12 或更高版本。发布到 npm Registry 后，Windows 和 macOS 使用同一条命令安装：

npm install -g @jiufeng/cli
jiufeng-cli version --json

国内网络可以使用 npmmirror：

npm install -g @jiufeng/cli --registry=https://registry.npmmirror.com

日常升级优先使用 CLI 自带命令。它会读取公司后台批准的最新发布策略，自动安装对应版本并校验安装结果：

jiufeng-cli update --json

首次安装或自动升级修复时仍可手工执行 npm install -g @jiufeng/cli@latest。

通过 AI Agent 安装

仓库同时提供 skills/jiufeng-cli/SKILL.md。在 Codex、Claude Code、WorkBuddy 等具备终端能力的智能体中，可以直接发送：

帮我安装并配置汣风 CLI。请先阅读：
https://cdn.jsdelivr.net/npm/@jiufeng/[email protected]/skills/jiufeng-cli/SKILL.md
按照 Skill 指引检查环境、安装或升级 CLI、验证版本并运行自检。需要登录时只在本机启动 jiufeng-cli auth login，不要要求我在聊天中发送或回显 API Key。

该引导 Skill 会先检查 Node.js/npm、已有命令路径和旧 EXE 冲突，再执行 npm 安装与验证；CLI 安装完成后还会指导能力目录查询、Skill 安装和升级。npm 包也包含这份 Skill，便于已安装客户端和其他内部工具复用同一套说明。

也可以生成标准 npm 压缩包，用于发布预演或内部分发：

生成安装包：

cd jiufeng-cli
npm ci
npm test
npm run pack:npm

产物位于：

dist/npm/jiufeng-cli-1.0.5.tgz

直接安装本地压缩包：

npm install -g ./dist/npm/jiufeng-cli-1.0.5.tgz
jiufeng-cli version --json

jiufeng-cli update 会自动获取后台批准的最新版本。npm 安装版会直接安装策略中的精确 tgz 地址并复查全局包版本；业务命令遇到强制升级时也会执行同一流程，完成后提示重新运行原命令。self-update 仅作为兼容别名保留。

发布 npm 试用版时，在 CLI 发布策略中填写 npmPackageUrl。若正式版停止提供 tgz，旧 npm 客户端会返回 INSTALLER_MIGRATION_REQUIRED 和 installerUrl，用户运行一次正式安装器后即可切换到自动更新链路。

GitHub 独立仓库

本目录可作为独立私有仓库使用，不依赖后端仓库中的源码或测试制品。推送到 GitHub 后：

.github/workflows/npm-package.yml 在 main 变更或手工触发时测试并生成 npm tgz，不需要系统代码签名证书。
.github/workflows/publish-npm.yml 在推送 npm-v<版本> Tag 时通过 npm Trusted Publishing 发布公共包。
.github/workflows/release.yml 使用 GitHub 托管的 Windows/macOS Runner 生成正式安装器。
推送 jiufeng-cli-v<版本> 形式的 Tag 后，正式产物会进入对应 GitHub Release。

仓库设置中的 Actions > General 需要允许 GitHub Actions。npm 发布优先使用 OIDC Trusted Publishing，不保存长期 npm Token；系统签名、Apple 公证和更新签名所需的秘密仅放入 Secrets and variables > Actions。任何私钥、P12、PFX、密码或 API Key 都不得提交到 Git。

发布状态与续接说明（2026-08-30）

| 项目 | 当前值或状态 | | --- | --- | | GitHub 仓库 | https://github.com/pwyyeye/jiufeng-cli.git | | npm 账户/包 | 用户 jiufeng；公共包 @jiufeng/[email protected] | | npm 安装验证 | 发布后从 Registry 下载并验证；制品内 jiufeng-cli version --json 应返回 1.0.4 | | npm 打包 workflow | npm-package.yml 已在 Windows Runner 成功运行 | | npm 自动发布 | workflow 已实现；npm Trusted Publisher 配置尚待确认 | | 正式安装器 | 构建与发布代码已实现；证书、更新密钥、OSS 地址尚未配置 |

下一次发布前，在 npm 包 Settings 中配置 Trusted Publisher：GitHub 用户 pwyyeye、仓库 jiufeng-cli、workflow 文件 publish-npm.yml、Environment 留空，并允许 npm publish。随后提升 package.json 版本并推送 npm-v<版本> Tag。npm 已发布版本不可覆盖，也不要通过 unpublish 后重发来处理传播延迟。

Tag 分工必须保持清晰：

npm-v<版本> 触发 publish-npm.yml，发布 npm 包。
jiufeng-cli-v<版本> 触发 release.yml，构建 Windows/macOS 正式安装器和 GitHub Release。

已验证的避坑事项：

npm-package.yml 必须使用 windows-latest。当前 Skill ZIP 解包首期只支持 Windows/macOS，在 Ubuntu 测试会得到 SKILL_EXTRACT_UNSUPPORTED。
workflow 使用 paths 时必须把自身 .github/workflows/npm-package.yml 加入路径，否则只修改 workflow 不会触发运行。
npm 首次发布会有 Registry/CDN 传播时间。若发布响应成功、包为 public、dist-tag 和 tarball 已存在，应等待同步，不要重复 publish 或 unpublish。
pnpm 是包管理器，registry.npmmirror.com 是 npm 官方包的只读镜像。发布只使用 registry.npmjs.org，npm 或 pnpm 均可从镜像安装。
npm WebAuthn 若在默认 Chrome 中进入跨设备二维码流程，可把 npm 授权 URL 明确用 Edge 打开并使用 Windows Hello；二维码不是一次性验证码。邮件 OTP 延迟时先搜索主题 OTP for logging in to your account。
npm 版与旧 EXE 都注册 jiufeng-cli 命令。同时进入 PATH 会由目录顺序决定实际运行版本；npm 阶段只保留 npm shim，迁移正式安装器前先执行 npm uninstall -g @jiufeng/cli。
release.yml 的 “HTTPS directory that will host the release files” 是写入元数据的稳定 URL 前缀，不会自动上传 OSS。应填写无尾斜杠、员工无需登录即可下载的公司 OSS/CDN HTTPS 目录。

后台 npm 阶段的 npmPackageUrl 应使用不可变的精确版本 tarball，例如：

https://registry.npmjs.org/@jiufeng/cli/-/cli-1.0.4.tgz

公开 npm 包意味着 CLI 源码可被查看。CLI 只能保留通用协议、安装和校验逻辑；核心业务规则、业务凭证和秘密必须留在后端。

正式安装器（第二阶段）

正式版不要求员工预装 Node.js。安装器与自更新二进制是两个不同制品：

| 字段 | 用途 | Windows 示例 | macOS 示例 | | --- | --- | --- | --- | | installerUrl | 员工首次安装或从 npm 版迁移 | jiufeng-cli-installer-windows-x64.exe | jiufeng-cli-installer-macos-arm64.pkg | | downloadUrl | 已安装 CLI 的原地强制更新 | jiufeng-cli-windows-x64.exe | jiufeng-cli-macos-arm64 | | npmPackageUrl | 第一阶段 tgz 升级，可为空 | jiufeng-cli-1.0.4.tgz | 同一个 tgz |

Windows 安装器默认安装到当前用户的 %LOCALAPPDATA%\Programs\jiufeng-cli，自动维护用户 PATH，不要求管理员权限。安装后重新打开终端：

jiufeng-cli version --json
jiufeng-cli auth login
jiufeng-cli doctor --json

macOS 安装器把 CLI 放到当前登录用户的 ~/.local/bin 并维护 ~/.zprofile。双击 .pkg 完成安装后重新打开终端：

jiufeng-cli version --json
jiufeng-cli auth login
jiufeng-cli doctor --json

正式安装版在业务命令前读取后台版本策略。低于 minSupportedVersion 时，CLI 下载 downloadUrl 的原始二进制，校验 SHA-256 和内置 Ed25519 公钥签名后原地替换；校验失败时不会执行后续业务操作。

Windows 开发包安装

仓库已有开发验证用文件：

dist/jiufeng-cli-windows-x64.exe

可以直接验证：

dist\jiufeng-cli-windows-x64.exe version --json

也可以复制到当前用户目录并加入用户 PATH：

$cliInstallDir = Join-Path $env:LOCALAPPDATA "Programs\jiufeng-cli"
New-Item -ItemType Directory -Force -Path $cliInstallDir | Out-Null

Copy-Item `
  ".\dist\jiufeng-cli-windows-x64.exe" `
  (Join-Path $cliInstallDir "jiufeng-cli.exe")

$existingUserPath = [Environment]::GetEnvironmentVariable("Path", "User")
$pathEntries = @($existingUserPath -split ";" | Where-Object { $_ })
if ($pathEntries -notcontains $cliInstallDir) {
    [Environment]::SetEnvironmentVariable(
        "Path",
        (($pathEntries + $cliInstallDir) -join ";"),
        "User"
    )
}

$env:Path = "$cliInstallDir;$env:Path"
jiufeng-cli version --json

当前开发包未进行 Windows 代码签名，可能触发系统安全提示，不应直接分发给普通员工。

首次配置

默认配置为：

API URL: https://jingxz.higuava.cn/admin-api
Tenant ID: 1

如需修改：

jiufeng-cli config set --api-url https://jingxz.higuava.cn/admin-api --tenant-id 1
jiufeng-cli config show --json

在若依管理后台个人 API Key 页面签发所需 scopes 的 jfak_v1_... Key，然后执行：

jiufeng-cli auth login

不要通过命令参数传递完整 API Key。Windows 使用当前用户 DPAPI 加密文件，macOS 使用 Keychain；CI 环境可以临时通过 JIUFENG_API_KEY 注入。

登录后运行自检：

jiufeng-cli auth status --json
jiufeng-cli doctor --json
jiufeng-cli skill list --json

doctor 应同时确认后端可访问、凭证有效、能力目录可访问和 CLI 发行策略已配置。任一检查失败时，不应继续向员工分发。

安装 Skill

标准 Skill 包只要求包含一个带合法 YAML frontmatter 的 SKILL.md，其中 name 必须与能力标识一致并提供非空 description。manifest.yaml、manifest.yml 或 manifest.json 是可选扩展元数据；包内存在 Manifest 时，CLI 才会继续校验其中声明的名称、版本和协议。

Codex

jiufeng-cli skill install jingxuan-auction --agent codex --json

默认安装目录：

~/.agents/skills/jingxuan-auction

Claude Code

jiufeng-cli skill install jingxuan-auction --agent claude --json

默认安装目录：

~/.claude/skills/jingxuan-auction

Codex 与 Claude Code 同时安装

jiufeng-cli skill install jingxuan-auction --agent all --json

个人版 WorkBuddy

个人版 WorkBuddy 暂无稳定的外部静默安装目录，先导出 ZIP：

jiufeng-cli skill fetch jingxuan-auction --output jingxuan-auction.zip --json

随后在 WorkBuddy 中手工导入 jingxuan-auction.zip。CLI 发现新版本时会刷新 ZIP 并要求重新导入，完成后可以确认：

jiufeng-cli skill confirm-import jingxuan-auction --json

常用命令

jiufeng-cli version --json
jiufeng-cli auth login
jiufeng-cli auth status --json
jiufeng-cli auth logout
jiufeng-cli config show --json
jiufeng-cli doctor --json
jiufeng-cli skill list --json
jiufeng-cli skill show jingxuan-auction --json
jiufeng-cli skill install jingxuan-auction --agent codex --json
jiufeng-cli skill update jingxuan-auction --agent codex --json
jiufeng-cli update --json

能力调用必须上报当前 Skill 版本。写操作还必须追加本次用户明确确认后的 --yes：

jiufeng-cli capability invoke jingxuan-auction session.list \
  --skill-version 1.0.2 \
  --input-file payload.json \
  --json

jiufeng-cli capability invoke jingxuan-auction session.update \
  --skill-version 1.0.2 \
  --input-file payload.json \
  --yes \
  --json

正式发布

生成并离线保存 Ed25519 密钥。私钥只进入发布环境，公钥通过 JIUFENG_UPDATE_PUBLIC_KEY 嵌入可执行文件。
在目标系统和架构上运行 npm run build:sea。Windows 和 macOS 必须使用各自的原生 Node.js 可执行文件生成 SEA。
Windows 运行 npm run build:installer:windows；macOS 运行 npm run build:installer:macos。
Windows 对原始二进制和安装器分别完成 Authenticode 签名；macOS 完成 Developer ID Application/Installer 签名和 pkg 公证。
对最终二进制和安装器运行 npm run release:metadata，确保两组 SHA-256 以及更新签名都覆盖签名后的最终字节。
将三类制品上传到公司 HTTPS OSS 地址。
把生成的 *.release.json 提交到 POST /admin-api/business/skill-hub/cli/release。
已部署数据库先执行 sql/mysql/skill_hub_cli_installer_upgrade.sql。
使用无本地凭证的环境运行 doctor，确认版本策略接口允许 CLI 在登录前查询。
使用普通员工 API Key 验证首次安装、Skill 安装、业务调用和强制更新闭环，再开放飞书 H5 下载按钮。

发布环境变量：

JIUFENG_UPDATE_PUBLIC_KEY
JIUFENG_UPDATE_PRIVATE_KEY
JIUFENG_RELEASE_FILE
JIUFENG_RELEASE_PLATFORM=windows|macos
JIUFENG_RELEASE_ARCH=x64|arm64
JIUFENG_INSTALLER_FILE=dist/jiufeng-cli-installer-...
JIUFENG_INSTALLER_DOWNLOAD_URL=https://.../jiufeng-cli-installer-...
JIUFENG_RELEASE_DOWNLOAD_URL=https://.../jiufeng-cli-...
JIUFENG_NPM_PACKAGE_URL=https://.../jiufeng-cli.tgz # 可选
JIUFENG_MIN_SUPPORTED_VERSION=1.0.0

.github/workflows/release.yml 负责 Windows x64、macOS x64 和 macOS arm64 的测试、SEA 构建、安装器构建、系统签名、公证、更新元数据签名及 GitHub Release 发布。Tag 格式为 jiufeng-cli-v<版本>；未配置证书时不能发布正式 Tag。

Windows 工作流可以配置：

JIUFENG_WINDOWS_CERT_PFX_BASE64
JIUFENG_WINDOWS_CERT_PASSWORD

macOS runner 中，JIUFENG_CODESIGN_IDENTITY 使用 Developer ID Application 身份，JIUFENG_INSTALLER_CODESIGN_IDENTITY 使用 Developer ID Installer 身份；流水线会导入 P12、签名并完成公证。

完整的流水线密钥/变量：

JIUFENG_MACOS_CERT_P12_BASE64
JIUFENG_MACOS_CERT_PASSWORD
JIUFENG_CODESIGN_IDENTITY
JIUFENG_INSTALLER_CODESIGN_IDENTITY
JIUFENG_APPLE_ID
JIUFENG_APPLE_TEAM_ID
JIUFENG_APPLE_APP_PASSWORD
JIUFENG_CLI_DOWNLOAD_BASE_URL
JIUFENG_CLI_NPM_PACKAGE_URL       # 可选

故障判断

AUTH_REQUIRED：尚未执行 auth login。
AUTH_DENIED：API Key、后台用户、租户或 RBAC 无效，或者版本策略接口尚未按登录前可查询方式部署。
CLI_UPDATE_REQUIRED：当前 CLI 低于最低支持版本，必须先更新。
UPDATE_TRUST_NOT_CONFIGURED：发行包未嵌入更新公钥，拒绝自动替换。
SKILL_CHECKSUM_MISMATCH：下载的 Skill ZIP 与后台 SHA-256 不一致。
WORKBUDDY_IMPORT_REQUIRED：个人版 WorkBuddy 需要导出 ZIP 后手工导入。
SKILL_TARGET_UNMANAGED：目标目录不是由 jiufeng-cli 创建，默认拒绝覆盖。