@longzai-intelligence-git/cli

Longzai Intelligence Git 命令行工具（lzi-git）。

在原生 git 之上叠加多仓库管理、巨量 commit 同步、巡检诊断与多租户 server 协作能力。 未识别的命令原样透传给系统 git，可作为 git 的完整替代（alias git=lzi-git）。

安装

本包位于 monorepo 内，通过 bun workspace 引用：

# 在仓库根目录
bun install

# 构建产物
cd apps/cli
bun run build

构建后通过 bin/lzi-git 暴露命令。也可在开发期直接 bun apps/cli/src/index.ts 运行。

全局选项

• --json, -j：以 JSON 格式输出（适用于 repository / inspection / tenant / task 命令族）
• --tenant <id>：指定租户标识，注入 X-Tenant-Id 请求头走 server HTTP（适用于 repository / inspection / massive-task；task 命令族必填）
• 环境变量 LZI_GIT_SERVER_URL：server 基址，默认 http://127.0.0.1:7780

命令族

tenant —— 租户管理

调用 server /tenants 端点（管理员视角，无需 X-Tenant-Id 头）。

# 列出所有租户
lzi-git tenant list
lzi-git tenant list --json

# 创建租户（--slug 作为租户唯一标识 id）
lzi-git tenant add --name "团队甲" --slug team-alpha
lzi-git tenant add --name "团队甲" --slug team-alpha --description "可选描述"

# 查询单个租户
lzi-git tenant get team-alpha

# 软删除租户
lzi-git tenant remove team-alpha

task —— 同步任务查询与取消

调用 server /tasks 端点，必须传入 --tenant <id>（注入 X-Tenant-Id 头）。

# 分页查询任务列表
lzi-git task list --tenant team-alpha
lzi-git task list --tenant team-alpha --status running --skip 0 --take 20

# 查询单个任务详情
lzi-git task get --tenant team-alpha task_xxx

# 取消任务
lzi-git task cancel --tenant team-alpha task_xxx

# 查询任务进度历史
lzi-git task progress --tenant team-alpha task_xxx
lzi-git task progress --tenant team-alpha task_xxx --skip 0 --take 20

repository —— 仓库元数据管理

• 不传 --tenant：走本地 JSON 文件存储（~/.lzi/git/repositories.json），保持兼容
• 传入 --tenant <id>：走 server /repositories HTTP 端点（多租户隔离）

# 列出仓库
lzi-git repository list
lzi-git repository list --tenant team-alpha --json

# 新增仓库
lzi-git repository add --name my-repo --path /path/to/repo
lzi-git repository add --name my-repo --path /path/to/repo --tenant team-alpha \
  --runtime native --default-branch main

# 查询仓库（本地模式用 --id，server 模式同样用 --id）
lzi-git repository get --id repo_xxx
lzi-git repository get --id repo_xxx --tenant team-alpha

# 移除仓库（软删除）
lzi-git repository remove --id repo_xxx
lzi-git repository remove --id repo_xxx --tenant team-alpha

inspection —— 巡检记录管理

• 不传 --tenant：走本地 JSON 文件存储（~/.lzi/git/inspections.json）
• 传入 --tenant <id>：走 server /inspections HTTP 端点（多租户隔离）

# 列出巡检记录
lzi-git inspection list
lzi-git inspection list --tenant team-alpha

# 新增巡检记录（交互式收集输入，server 模式下 POST 到 /inspections）
lzi-git inspection add
lzi-git inspection add --tenant team-alpha

massive-task —— 巨量 commit 同步

针对单仓积累数千~数万 commit 的场景，分步执行 fetch → rebase/merge → push， 支持断点续传与进度观测。

# 执行完整同步
lzi-git massive-task run --repo /path/to/repo
lzi-git massive-task run --repo /path/to/repo --tenant team-alpha \
  --remote origin --ref refs/heads/main --strategy rebase --segment-size 1000

# 从断点恢复
lzi-git massive-task resume --repo /path/to/repo
lzi-git massive-task resume --repo /path/to/repo --tenant team-alpha

# 查询同步断点
lzi-git massive-task status --repo /path/to/repo

--tenant 可选：传入时绑定任务到指定租户（多租户隔离）；不传时使用默认租户 default， 保持与历史无租户场景兼容（内存仓储）。

inspect —— 仓库拓扑诊断

lzi-git inspect --repo /path/to/repo
lzi-git inspect --repo /path/to/repo --remote origin --ref refs/heads/main --json

输出八项只读探测报告：detached HEAD / shallow / partial clone / force-push 痕迹 / merge-base / 悬空 commit / 对象库健康度 / LFS。

config —— 配置管理

lzi-git config init
lzi-git config show

交互模式

无参数运行进入交互式菜单：

lzi-git

git 透传

未识别的命令原样透传给系统 git：

lzi-git status        # ≡ git status
lzi-git log --oneline # ≡ git log --oneline
lzi-git commit -m "feat: xxx"  # ≡ git commit -m "..."

massive 强化原子操作

fetch / push / rebase / unshallow 配合 --massive 标志走分步/分段强化实现：

lzi-git fetch --massive --repo /path/to/repo
lzi-git push --massive --repo /path/to/repo
lzi-git rebase --massive --repo /path/to/repo
lzi-git unshallow --massive --repo /path/to/repo

多租户说明

CLI 通过 --tenant <id> 参数与 server 进行多租户协作：

1. 租户管理（tenant 命令族）：管理员视角，先创建租户获得 tenant id，无需 X-Tenant-Id 头
2. 业务数据隔离（task / repository / inspection 命令族）：传入 --tenant <id> 后， CLI 自动在 HTTP 请求中注入 X-Tenant-Id: <id> 头，server 端按租户隔离数据
3. 同步任务绑定（massive-task 命令族）：--tenant <id> 将同步任务绑定到指定租户

server 端通过 X-Tenant-Id 请求头（或 ?tenantId= query）解析租户上下文， 缺失时返回 401；跨租户访问返回 404，不泄露数据存在性。

开发

# 类型检查（使用 tsgo）
bun run typecheck

# 单元测试
bun test

# 构建
bun run build

测试文件位于 src/__tests__/，通过 mock globalThis.fetch 拦截 HTTP 请求，不依赖真实 server。