@hz-rdc/hapkg

v1.2.0

Published

a month ago

HzAiPackage is the package manager for AI coding at huize.

0High
0Medium
0Low

minttt

HzAiPackage cli ai coding open package manager rules commands agents skills hapkg hapkg

hzaipackage（hapkg）

面向 AI 编程助手的配置包管理器 · 慧择内部定制版
本仓库 Fork 自 enulus/OpenPackage，在其基础上进行了慧择内部定制。

安装

npm install -g @hz/hapkg

快速上手

# 从 GitHub 安装资源包
hapkg install gh@anthropics/claude-code --plugins code-review

# 安装本地包
hapkg install ./my-package

# 查看已安装资源
hapkg list

# 更新 hzaipackage.yml 中声明的所有包
hapkg update

# 卸载包
hapkg uninstall my-package

hzaipackage.yml 编写指南

hzaipackage.yml 是每个 hapkg 包的清单文件（manifest），声明包的元信息、依赖关系和资源范围。它是工作区依赖管理的唯一真实来源（source of truth）。

最小示例

name: "@myteam/my-package"
version: 1.0.0

完整字段说明

# ── 必填 ──────────────────────────────────────────────────────────
name: "@myteam/my-package"      # 包名，推荐 @scope/name 格式
version: 1.0.0                  # semver 格式版本号

# ── 发布控制 ──────────────────────────────────────────────────────
private: true                   # true = 不发布到注册表，仅本地/私仓使用
partial: false                  # true = 仅安装 files 字段声明的文件子集

# ── 元信息 ────────────────────────────────────────────────────────
description: "代码审查工作流配置集"
keywords:
  - code-review
  - claude
author: "hz-ai-dev"
license: "MIT"
homepage: "https://git.hzins.com/ai-dev/hz-ai-package"
repository:
  type: git
  url: "https://git.hzins.com/ai-dev/hz-ai-package.git"

# ── 平台限定 ──────────────────────────────────────────────────────
# 指定此包仅适用于哪些 AI 平台，省略则所有平台均可安装
platforms:
  - claudecode
  - cursor

# ── 平铺分包（flat-package）───────────────────────────────────────
# 见下方"平铺分包"章节
include:
  - ../../skills/brainstorming
  - ../../commands/commit.md

# ── 依赖声明 ──────────────────────────────────────────────────────
dependencies:
  - name: some-registry-package        # 注册表依赖（semver 范围）
    version: "^1.2.0"

  - name: local-package                # 本地路径依赖
    path: ../local-package

  - name: remote-package               # Git 依赖
    git: https://github.com/owner/repo.git
    ref: main                          # 可选：指定 branch / tag / commit

dev-dependencies:                      # 开发依赖（不随包发布）
  - name: dev-tools
    version: "*"

字段详解

`name`（必填）

包标识符，规范写法为 @scope/name（如 @hz/my-package）。scope 用于命名空间隔离，避免同名包冲突。

name: "@hz/code-review"

`version`

遵循 semver 规范，格式为 major.minor.patch。

开发初期可使用 0.1.0
首次稳定发布使用 1.0.0
省略时工具内部以 0.0.0 处理，依赖声明中不写 version 字段

`private`

设为 true 时，该包不会被发布到注册表。适用于工作区内部的私有配置包。

`platforms`

限制此包可安装的目标平台。省略时安装到当前工作区检测到的所有平台。

可用值：claudecode、cursor、opencode、windsurf、amp、cline、continue 等（详见支持的平台）。

# 仅安装到 Claude Code 和 Cursor
platforms:
  - claudecode
  - cursor

`include`

平铺分包模式专用字段，详见平铺分包（Flat-Package）章节。

依赖声明

每条依赖项必须且只能指定以下三种来源之一：

注册表依赖（version）

从注册表按 semver 范围安装：

dependencies:
  - name: essentials
    version: "^2.0.0"     # 兼容 2.x.x

  - name: code-review
    version: "1.3.0"      # 精确锁定版本

  - name: experimental
    version: "*"          # 任意版本（始终取最新）

版本范围语法（semver）：

| 写法 | 含义 | |------|------| | ^1.2.0 | >=1.2.0 <2.0.0（兼容同主版本） | | ~1.2.0 | >=1.2.0 <1.3.0（兼容同次版本） | | 1.2.0 | 精确匹配 | | * | 任意版本 | | >=1.0.0 <2.0.0 | 自定义范围 |

本地路径依赖（path）

直接引用本地文件系统中的包目录：

dependencies:
  - name: my-local-pkg
    path: ../packages/my-local-pkg    # 相对或绝对路径

适用场景：monorepo 内部包引用、尚未发布的本地包。

Git 依赖（git）

直接从 Git 仓库安装：

dependencies:
  - name: remote-configs
    git: https://git.hzins.com/ai-dev/configs.git
    ref: main                         # branch / tag / commit hash（可选）

  - name: pinned-version
    git: https://github.com/owner/repo.git
    ref: v2.1.0                       # 锁定到具体 tag

注意：version、path、git 三者互斥，每条依赖只能选一种。

部分安装（files）

当只需安装包中的部分资源时，可在依赖项中添加 files 字段：

dependencies:
  - name: large-package
    version: "^1.0.0"
    files:
      - skills/brainstorming        # 只安装这两个路径
      - commands/commit.md

省略 files 或设为空数组则安装包内全部文件。

典型包目录结构

my-package/
├── hzaipackage.yml       # 清单文件（必须）
├── README.md
│
├── rules/                # 规则文件 → .cursor/rules/、.claude/rules/
├── commands/             # 命令文件 → .cursor/commands/、.claude/commands/
├── agents/               # Agent 文件 → .claude/agents/、.cursor/agents/
├── skills/               # Skill 文件 → .claude/skills/、.cursor/skills/
├── hooks/                # Hook 声明（见 Hooks 约定章节）
└── root/                 # 复制到工作区根目录（root/ 前缀会被剥除）

命令参考

`hapkg install`

安装包或资源到当前工作区：

# 注册表包
hapkg install <package-name>
hapkg install <package-name>@^1.2.0

# GitHub 仓库
hapkg install gh@<owner>/<repo>
hapkg install gh@anthropics/claude-code --plugins code-review

# 具体资源路径
hapkg install gh@wshobson/agents/plugins/ui-design/agents/ui-designer

# 本地路径
hapkg install ./my-package

# Git URL
hapkg install https://github.com/owner/repo.git
hapkg install [email protected]:owner/repo.git

| 选项 | 说明 | |------|------| | -g, --global | 安装到主目录（~/）而非当前工作区 | | -s, --skills <names...> | 仅安装指定 skills | | -a, --agents <names...> | 仅安装指定 agents | | -c, --commands <names...> | 仅安装指定 commands | | -r, --rules <names...> | 仅安装指定 rules | | --plugins <names...> | 仅安装指定 plugins | | --platforms <names...> | 仅安装到指定平台 | | -i, --interactive | 交互式选择要安装的资源 | | --dev | 添加到 dev-dependencies | | --force | 强制重新安装（覆盖现有文件） | | --conflicts <strategy> | 冲突策略：ask、namespace、overwrite、skip |

`hapkg list`

查看已安装的资源：

hapkg list                  # 列出工作区所有已安装包
hapkg list <package-name>   # 列出指定包的详细文件

| 选项 | 说明 | |------|------| | -s, --scope <scope> | project / global / 不填（两者） | | -f, --files | 显示每个包的文件列表 | | --flat | 平铺展示，不嵌套 | | -u, --untracked | 仅显示未被 hapkg 追踪的文件 | | --platforms <names...> | 按平台过滤 |

`hapkg uninstall`

卸载包并移除其安装的所有文件：

hapkg uninstall <package-name>

| 选项 | 说明 | |------|------| | -g, --global | 从主目录卸载 | | -i, --interactive | 交互式选择 |

`hapkg new`

创建新的包骨架：

hapkg new <package-name>
hapkg new <package-name> --scope project   # 在工作区 .hzaipackage/ 中创建
hapkg new <package-name> --path ./my-dir   # 指定路径

`hapkg add` / `hapkg remove`

向包中添加或移除文件：

hapkg add .cursor/commands/clean.md --to <package>   # 添加工作区文件到包
hapkg add --to <package>                              # 交互式选择

hapkg remove commands/clean.md --from <package>       # 从包移除文件
hapkg remove --from <package>                         # 交互式选择

`hapkg sync`

将工作区文件同步到最新版本：

hapkg sync                  # 同步所有依赖
hapkg sync <package-name>   # 同步指定包

`hapkg update`

将 hzaipackage.yml 中声明的包重新安装到最新版本：

hapkg update                       # 更新所有已声明的包
hapkg update <package-name...>     # 只更新指定的包

| 选项 | 说明 | |------|------| | -g, --global | 仅更新全局 scope（~/），默认同时更新项目和全局 | | --json | 以 JSON 格式输出结果 |

跳过规则（以下情况不会被更新）：

| 原因 | 说明 | |------|------| | path-source | 依赖来源为本地路径（path: 字段），无远程版本可拉取 | | not-installed | 该包在工作区中尚未安装 | | embedded | 该包作为父包的子集安装，由父包管理版本 | | subset-install | 安装时使用了 --skills / --agents 等子集选项，跳过以避免覆盖已选子集 |

注意：hapkg update 仅处理在 hzaipackage.yml 的 dependencies 中显式声明的包。通过命令行直接安装（未写入 yml）的包不会被更新。

平铺分包（Flat-Package）

平铺分包是团队共享资源仓库的推荐组织方式：资源文件（skills、commands、hooks 等）平铺在仓库根目录，多个 hzaipackage.yml 通过 include 字段声明各自包含哪些资源。

仓库结构

my-repo/
├── skills/
│   ├── brainstorming/
│   │   └── SKILL.md
│   ├── debugging/
│   │   └── SKILL.md
│   └── frontend/
│       └── SKILL.md
├── commands/
│   ├── commit.md
│   └── component-gen.md
├── hooks/
│   ├── pre-commit/
│   │   ├── claude.json     # Claude Code settings.json 片段
│   │   └── cursor.json     # Cursor hooks.json 片段
│   └── scripts/
│       └── lint.sh
│
└── packages/
    ├── core/
    │   └── hzaipackage.yml
    └── frontend/
        └── hzaipackage.yml

包清单示例

# packages/core/hzaipackage.yml
name: "@myteam/core"
version: 1.0.0
include:
  - ../../skills/brainstorming    # 相对于本文件，../../ 指向仓库根
  - ../../skills/debugging
  - ../../commands/commit.md
  - ../../hooks/pre-commit
  - ../../hooks/scripts

# packages/frontend/hzaipackage.yml
name: "@myteam/frontend"
version: 1.0.0
include:
  - ../../skills/brainstorming    # 与 core 重叠没关系，安装时自动去重
  - ../../skills/frontend
  - ../../commands/component-gen.md
  - ../../hooks/pre-commit
  - ../../hooks/scripts

include 路径规则：

路径相对于 hzaipackage.yml 所在目录
支持目录（递归收集目录内所有文件）和单文件两种写法
路径不存在时静默跳过（打印警告日志）
多个包引用同一资源时，安装时自动去重
有 include 字段时，包目录内的本地内容文件会被忽略

安装平铺分包

hapkg install gh@myteam/my-repo/packages/core
hapkg install gh@myteam/my-repo/packages/frontend

Hooks 目录约定

Claude Code、Cursor 和 Codex 均支持 hooks，但声明格式不同，可共用执行脚本。推荐使用两层结构分离声明层和执行层：

目录结构

hooks/
├── <功能名>/
│   ├── claude.json    # Claude Code — 合并进 .claude/settings.json
│   ├── cursor.json    # Cursor — 合并进 .cursor/hooks.json
│   └── codex.json     # Codex — 合并进 .codex/hooks.json，并启用 config.toml 里的 feature flag
└── scripts/
    └── <脚本>.sh      # 执行脚本，被声明层的 command 字段引用

claude.json 格式（Claude Code）

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/scripts/lint.sh"
          }
        ]
      }
    ]
  }
}

支持的事件：PreToolUse、PostToolUse、Notification、Stop、SubagentStop

cursor.json 格式（Cursor）

{
  "hooks": [
    {
      "event": "beforeShellExecution",
      "command": ".cursor/hooks/scripts/lint.sh"
    }
  ]
}

支持的事件：beforeShellExecution、afterShellExecution

codex.json 格式（Codex）

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "bash .codex/hooks/scripts/lint.sh"
          }
        ]
      }
    ]
  }
}

安装时会同时：

deep merge 到 .codex/hooks.json
复制脚本到 .codex/hooks/scripts/
自动在 .codex/config.toml 中写入 [features] hooks = true，并迁移旧的 codex_hooks 字段

安装行为

安装时，platforms.jsonc 中的路由规则将 hooks 分发到对应平台：

// Claude Code
{ "from": "hooks/**/claude.json",  "to": ".claude/settings.json",   "merge": "deep" }
{ "from": "hooks/**/scripts/**/*", "to": ".claude/hooks/scripts/**/*" }

// Cursor
{ "from": "hooks/**/cursor.json",  "to": ".cursor/hooks.json",      "merge": "deep" }
{ "from": "hooks/**/scripts/**/*", "to": ".cursor/hooks/scripts/**/*" }

// Codex
{ "from": "hooks/**/codex.json",   "to": ".codex/hooks.json",       "merge": "deep" }
{ "from": "hooks/**/codex.json",   "to": ".codex/config.toml",      "map": [{ "$set": { "features.hooks": true } }, { "$unset": "hooks" }], "merge": "deep" }
{ "from": "hooks/**/scripts/**/*", "to": ".codex/hooks/scripts/**/*" }

merge: deep 保证多个包的 hook 声明共存——数组字段（如 hook 监听列表）追加合并，不互相覆盖。目标配置文件不存在时自动创建。

支持的平台

hapkg 支持以下 AI 编程平台的文件安装和跨平台同步：

| 平台 | 目录 | Rules | Commands | Agents | Skills | Hooks | MCP | |------|------|-------|----------|--------|--------|-------|-----| | Claude Code | .claude/ | rules/ | commands/ | agents/ | skills/ | ✅ settings.json | .mcp.json | | Cursor | .cursor/ | rules/ | commands/ | agents/ | skills/ | ✅ hooks.json | mcp.json | | Codex | .codex/ | — | prompts/ | — | skills/ | ✅ hooks.json + config.toml feature flag | config.toml | | OpenCode | .opencode/ | — | commands/ | agents/ | skills/ | — | opencode.json | | Windsurf | .windsurf/ | rules/ | — | — | skills/ | — | — | | Amp | .agents/ | checks/ | — | — | skills/ | — | .amp/settings.json | | Cline | .cline/ | — | — | — | skills/ | — | cline_mcp_settings.json | | Continue | .continue/ | rules/ | prompts/ | — | skills/ | — | — | | GitHub Copilot | .github/ | — | — | agents/ | skills/ | — | — | | Qwen Code | .qwen/ | — | — | agents/ | skills/ | — | settings.json | | Roo Code | .roo/ | — | commands/ | — | skills/ | — | mcp.json | | Augment Code | .augment/ | rules/ | commands/ | — | skills/ | — | — | | Warp | .warp/ | — | — | — | — | — | — | | Goose | .goose/ | — | — | — | skills/ | — | config.yaml | | Kiro | .kiro/ | steering/ | — | — | skills/ | — | settings/mcp.json |

完整平台列表和配置可在 platforms.jsonc 中查看，支持按项目自定义：

全局覆盖：~/.hzaipackage/platforms.jsonc
工作区覆盖：<cwd>/.hzaipackage/platforms.jsonc

慧择 Fork 分支管理规范

分支职责

| 分支 | 职责 | 规则 | |------|------|------| | main | 上游镜像，与 enulus/OpenPackage 保持同步 | 只允许 merge upstream，禁止本地提交 | | feat-* / bug-* | 慧择定制开发分支 | 所有内部改动在此类分支进行 | | hz-release | 发布分支 = main + 慧择定制 | 实际使用版本，发布到私仓 |

Remote 配置

origin    # 慧择内部仓库：https://git.hzins.com/ai-dev/hz-ai-package.git
upstream  # 上游源仓库：https://github.com/enulus/OpenPackage.git

同步上游

# 1. 同步上游到 main
git checkout main
git fetch upstream
git merge upstream/main
git push origin main

# 2. 将定制分支 rebase 到最新 main
git checkout hz-release
git merge main
git push origin hz-release

开发新功能

# 基于 hz-release 创建功能分支
git checkout -b feat-<version>-<description>

# 开发完成后合入 hz-release（不合入 main）
git checkout hz-release
git merge feat-<version>-<description>

慧择定制改动永远不合入 main。 main 只跟踪上游，hz-release 是慧择的工作基线。