@icode-js/icode v3

@icode-js/icode 是一个面向 Git 日常操作的命令行工具，安装后可直接使用 icode 命令。

目标：

• 更稳定地处理复杂 Git 场景
• 更好支持 husky/git hooks 校验链路
• 默认识别“继承父级 Git 仓库”的目录结构
• 提供面向人类和 AI agent 的安全场景入口，而不是复刻 Git 子命令
• 采用更现代的 Node 20+ ESM 架构（无运行时第三方依赖）

安装

npm i -g @icode-js/icode

快速开始

icode help # 查看命令总览
icode info
icode ready
icode save -m "feat: add login form"
icode doctor
icode config ai list

Shell Tab 补全

icode 现在支持生成 bash / zsh 的 tab 补全脚本。

临时启用：

source <(icode completion bash)
source <(icode completion zsh)

持久启用可以把对应命令追加到 ~/.bashrc 或 ~/.zshrc。

补全范围包括：

• 顶层命令和嵌套子命令
• 已知参数开关与枚举值
• 常见 Git 分支 / ref
• icode config ai ... 下已配置的 profile 名称

全局参数

• -h, --help：查看帮助（也可 icode <command> -h 查看子命令参数）
• -d, --debug：开启调试日志（输出更多细节）

AI 能力配置

先配置一个 AI profile（支持 OpenAI/Anthropic/Ollama 三种接口格式）：

icode config ai set openai \
  --format openai \
  --base-url https://api.openai.com/v1 \
  --api-key sk-xxx \
  --model gpt-4o-mini \
  --activate

Anthropic 示例：

icode config ai set claude \
  --format anthropic \
  --base-url https://api.anthropic.com/v1 \
  --api-key xxx \
  --model claude-3-5-sonnet-20241022 \
  --activate

Ollama 本地模型示例：

icode config ai set ollama \
  --format ollama \
  --base-url http://127.0.0.1:11434 \
  --model qwen2.5:7b \
  --activate

常用命令：

icode config ai list
icode config ai show
icode config ai use claude
icode config ai test

可选：为常用命令预设默认 options（命令行显式传参优先级更高）：

icode config ai options set commit --json '{"profile":"ollama","lang":"zh","yes":true}'
icode config ai options set explain --json '{"profile":"ollama","base":"origin/main"}'
icode config ai options set push --json '{"aiProfile":"ollama","aiCommitLang":"zh"}'

健康检查

icode doctor
icode doctor --json

doctor 会检查 Git 命令、origin、hooks、AI profile 与远程合并配置，并给出修复建议。建议新成员初始化环境后先执行一次。

参数说明：

• --repo-mode auto|strict：仓库模式（自动继承父仓库/禁止继承）
• --json：输出机器可读 JSON，适合脚本或 CI 读取
• -h, --help：查看帮助

核心命令

ready

icode ready
icode ready --json

ready 是继续开发、保存或推送前的场景化检查入口，不会修改 Git 状态。它会检查：

• 当前是否在明确分支上
• 是否存在未完成的 merge/rebase/cherry-pick/revert
• 是否存在未提交改动或冲突文件
• 当前分支与 upstream 的 ahead/behind 关系
• AI profile 与远程合并配置是否可用

参数说明：

• --repo-mode auto|strict：仓库模式（自动继承父仓库/禁止继承）
• --json：输出机器可读 JSON，适合 AI agent 或脚本判断下一步
• -h, --help：查看帮助

save

icode save -m "feat: add login form"
icode save --ai-commit -y
icode save -m "fix: adjust copy" --dry-run
icode save --ai-commit --dry-run --json

save 是安全快速提交场景：检查状态 -> 暂存全部改动 -> 创建本地 commit。它不会 push，也不会隐式生成提交信息。

• 无改动会直接失败
• 存在冲突会直接失败
• 存在未完成 Git 操作会直接失败
• --message 和 --ai-commit 必须二选一
• --dry-run 只检查并展示计划，不执行 git add 或 git commit
• --ai-commit 必须使用已配置的 AI profile，不做静默降级

参数说明：

• -m, --message <msg>：指定提交信息
• --ai-commit：使用 AI 根据全部未提交改动生成提交信息
• --profile <name>：指定 AI profile（仅 --ai-commit 使用）
• --lang <zh|en>：AI 提交信息语言，默认 zh
• --dry-run：只检查并展示将提交的信息，不执行 add/commit
• --json：输出机器可读 JSON
• --repo-mode auto|strict：仓库模式（自动继承父仓库/禁止继承）
• --no-verify：commit 时跳过 hook/husky 校验
• -y, --yes：自动确认 AI 提交
• -h, --help：查看帮助

checkout

icode checkout <branch> [base] [--push-origin] [--pull-main] [--repo-mode auto|strict]

• 本地存在分支: 直接切换
• 远程存在分支: 本地创建 tracking 分支并切换
• 都不存在: 从 base 或默认主分支创建
• 执行前要求工作区干净，且不存在未完成的 merge/rebase/cherry-pick/revert

参数说明：

• <branch>：目标分支名（必填）
• [base]：新建分支基线，默认主分支
• --push-origin：新建分支后立即推送到 origin
• --pull-main：切换后同步主分支到当前分支
• --repo-mode auto|strict：仓库模式（自动继承父仓库/禁止继承）
• --no-verify：跳过 hook/husky 校验
• -y, --yes：自动确认（跳过交互提示）
• -h, --help：查看帮助

push

icode push [targetBranch...] [-m "commit message"] [--ai-commit] [--pull-main] [--not-push-current] [-r|--remote-merge] [--dry-run]

示例：

icode push -m "feat: release" # 提交并推送当前分支
icode push release test -m "feat: batch publish" -y # 默认本地 merge 推送到多个分支
icode push release test --dry-run # 只查看计划，不执行任何 Git/远程合并副作用
icode push release test -r -y # 使用远程 MR 模式合并到多个目标分支

• 自动 add + commit + push
• 存在冲突或未完成 Git 操作时会直接停止
• 本地 merge 冲突会暂停在目标分支现场；解决后执行 icode undo --recover continue，或执行 icode undo --recover abort 中止
• 支持 --ai-commit 在 push 前自动生成并应用 AI 提交信息
• 若仓库存在 husky/hooks/commitlint 规则，AI commit 会先扫描本地规范再生成提交信息
• 支持把当前分支合并到多个目标分支
• 默认使用本地 merge 模式（会生成 merge commit）
• 支持远程 PR/MR API 模式（需配置平台密钥）
• 支持受保护分支策略（通过 icode config protect ... 管理）

参数说明：

• [targetBranch...]：目标分支列表（可多个，空则默认当前分支）
• -m, --message <msg>：提交信息（未填会提示输入）
• -y, --yes：自动确认（跳过确认提示）
• --local-merge：显式声明使用本地 merge 模式（当前为默认行为，会切换分支并生成 merge commit）
• -r, --remote-merge：改为远程 PR/MR 模式；会先推送源分支，再通过 API 创建合并请求；若发生冲突会暂停，并输出明确失败原因
• --dry-run：只展示计划，不执行 commit/fetch/pull/push/merge/MR
• --ai-commit：push 前自动执行 AI commit
• --ai-profile <name>：指定 AI profile（用于 --ai-commit）
• --pull-main：提交前同步主分支到当前分支
• --not-push-current：不推送当前分支，只处理目标分支
• --force-protected：强制处理配置里的受保护分支
• --repo-mode auto|strict：仓库模式（自动继承父仓库/禁止继承）
• --no-verify：跳过 hook/husky 校验
• -h, --help：查看帮助

说明：

• push 的布尔开关（如 --ai-commit、--pull-main、--no-verify、-y）仅在命令行显式传入时生效。

远程合并配置示例：

icode config platform remote-merge set --provider gitlab --api-key rm_xxx

建议：

• 密钥按平台维度管理，例如 GitLab / GitHub / 自建平台。
• GitLab API 地址固定为仓库 origin 对应站点的 /api/v4，无需再单独配置服务地址。
• 项目/仓库默认启用远程合并；如个别仓库不希望启用，可显式设置 repositories.<repo>.remoteMerge.enabled=false。
• 远程合并始终根据 origin 自动提取 GitLab 项目地址；若无法识别，会提示你修正仓库 remote 配置。
• GitLab 审批规则由 merge API 统一判断；若审批不足，会在 merge 阶段输出明确失败原因。
• GitLab 合并检查会展示等待进度，并在长时间 pending 后超时退出，避免命令无限卡住。
• 这样更符合密钥复用与安全边界，避免多个仓库重复维护同一平台 API 地址。

ai

icode ai commit [--apply]
icode ai conflict
icode ai codereview
icode codereview [--base origin/main --head HEAD]

• ai commit: 基于 diff 生成 Conventional Commit 信息；若检测到本地 hook/commitlint 规则，会优先遵循项目规范
• ai conflict: 解析冲突块并生成合并建议
• ai codereview: 默认评审暂存区 + 工作区未提交改动；传 --base/--head 时可改为评审分支 diff

参数说明：

• ai commit 参数
  • --apply：直接使用 AI 信息执行 commit
  • --lang <zh|en>：输出语言（默认 zh）
  • --profile <name>：指定 AI profile
  • --repo-mode auto|strict：仓库模式（自动继承父仓库/禁止继承）
  • --no-verify：commit 时跳过 hook/husky 校验
  • -y, --yes：自动确认（跳过确认提示）
  • -h, --help：查看帮助
• ai conflict 参数
  • --profile <name>：指定 AI profile
  • --repo-mode auto|strict：仓库模式（自动继承父仓库/禁止继承）
  • -h, --help：查看帮助
• ai codereview / codereview 参数
  • --base <ref>：指定分支 diff 基线；未传时默认评审暂存区 + 工作区未提交改动
  • --head <ref>：指定分支 diff 终点（默认 HEAD）
  • --focus <text>：评审重点（安全/性能/测试等）
  • --profile <name>：指定 AI profile
  • --repo-mode auto|strict：仓库模式（自动继承父仓库/禁止继承）
  • --dump-response：输出 AI 原始响应（调试数据格式）
  • -h, --help：查看帮助

sync

icode sync [branch...] [--all-local] [--merge-main] [--push]

• 批量同步多个分支（fetch + pull）
• 执行前要求当前处于普通分支、工作区干净，且不存在未完成 Git 操作
• 可选自动同步全部本地分支（--all-local）
• 可选把主分支自动 merge 到目标分支（--merge-main）
• 可选同步后自动推送（--push）

参数说明：

• [branch...]：需要同步的分支列表（可多个）
• --all-local：自动同步全部本地分支
• --merge-main：同步后把主分支 merge 到目标分支
• --rebase：pull 时使用 rebase
• --push：同步后自动 push
• -y, --yes：自动确认（跳过确认提示）
• --repo-mode auto|strict：仓库模式（自动继承父仓库/禁止继承）
• --no-verify：push 时跳过 hook/husky 校验
• -h, --help：查看帮助

clean

icode clean [--merged-target <branch>] [--remote] [--force]

• 安全清理“已合并”本地分支
• 执行前要求当前处于普通分支、工作区干净，且不存在未完成 Git 操作
• 默认保护当前分支/主分支/配置中的受保护分支
• 可选同步删除远程分支（--remote）

参数说明：

• --merged-target <branch>：基于该分支判断“已合并”状态
• --keep <branch|csv>：额外保留分支，可重复或逗号分隔
• --remote：同时删除远程分支
• --force：强制删除本地分支（-D）
• -y, --yes：自动确认（跳过确认提示）
• --repo-mode auto|strict：仓库模式（自动继承父仓库/禁止继承）
• -h, --help：查看帮助

tag

icode tag [--name <tag>] [--message <msg>] [--from <ref>]

默认 tag 规则：vYYYYMMDD_NN（例如 v20260309_01）

参数说明：

• -n, --name <tag>：指定 tag 名（默认 vYYYYMMDD_NN）
• -m, --message <msg>：tag 备注
• --from <ref>：从指定分支/commit 创建 tag
• --repo-mode auto|strict：仓库模式（自动继承父仓库/禁止继承）
• --no-verify：跳过 hook/husky 校验
• -h, --help：查看帮助

undo

icode undo [ref] [--mode revert|soft|mixed|hard] [--ref <ref>] [--hash <hash>] [--recover continue|abort|keep]
icode undo --mode revert --ref HEAD --json

• 向导式撤销命令（交互选择回滚策略）
• 适合新人或低频 Git 操作场景
• 也支持非交互参数：--mode + --ref / --hash
• 支持用位置参数指定 commit hash，例如：icode undo a1b2c3d --mode revert -y
• 检测到 merge/revert/cherry-pick 冲突时，会提示继续或中止
• 支持 --json 输出结构化结果；适合 AI agent 判断是否已恢复现场

参数说明：

• --mode <mode>：回滚模式（revert|soft|mixed|hard）
• --ref <ref>：回滚目标，默认按 mode 自动给出
• --hash <hash>：按 commit hash 指定回滚目标（等同 --ref）
• --recover <action>：冲突恢复策略（continue|abort|keep）
• --json：输出机器可读 JSON
• -y, --yes：自动确认（跳过确认提示）
• --repo-mode auto|strict：仓库模式（自动继承父仓库/禁止继承）
• -h, --help：查看帮助

migrate

icode migrate <sourceBranch> <targetBranch> [--range <from..to>] [--push]
icode migrate <sourceBranch> <targetBranch> --dry-run --json

• 将 source 分支的提交迁移到 target（底层是 cherry-pick）
• 默认迁移 target..source 的增量提交
• 可通过 --range 精确指定迁移范围
• 执行前要求工作区干净，且不能存在未完成的 merge/rebase/cherry-pick/revert
• 支持 --dry-run 输出 checkout/pull/cherry-pick/push 计划，不产生 Git 副作用
• 支持 --json 输出结构化计划或执行结果，适合 AI agent 消费
• 如果迁移冲突，可使用 icode undo --recover continue|abort|keep 处理现场

参数说明：

• <sourceBranch>：迁移来源分支
• <targetBranch>：迁移目标分支
• -i, --interactive：交互模式（单选/多选 source/target 与迁移范围）
• --range <from..to>：指定提交范围，例如 main..feature-x
• --dry-run：只展示迁移计划，不 checkout/pull/cherry-pick/push
• --json：输出机器可读 JSON
• --push：迁移后自动推送 target 分支
• -y, --yes：自动确认（跳过确认提示）
• --repo-mode auto|strict：仓库模式（自动继承父仓库/禁止继承）
• --no-verify：推送时跳过 hook/husky 校验
• -h, --help：查看帮助

config

icode config list
icode config get defaults.repoMode
icode config set defaults.repoMode strict
icode config protect add main release
icode config protect list
icode config platform remote-merge set --provider gitlab --api-key rm_xxx

参数说明：

• list：查看全部配置
• get <path>：读取指定配置项
• set <path> <value>：写入配置项（支持数字/布尔/JSON）
• delete <path>：删除配置项
• protect list：查看受保护分支
• protect add <branch...>：添加受保护分支
• protect remove <branch...>：移除受保护分支
• ai <subcommand>：AI profile 管理（见上文“AI 能力配置”）
• platform remote-merge show：查看远程合并平台配置（密钥脱敏）
• platform remote-merge set --provider gitlab --api-key <key>：写入 GitLab 远程合并密钥
• --repo-mode auto|strict：仓库模式（仅影响 protect）
• -h, --help：查看帮助

info

icode info

输出 Git 版本、仓库根路径、当前分支、hook/husky 状态、受保护分支等信息。

复杂场景支持

1) Husky / Git Hook 校验

当 commit/push 被 hooks 拦截时，会明确提示：

• 当前被 hook 拦截
• 可使用 --no-verify 进行跳过

示例：

icode push -m "chore: hotfix" --no-verify

2) 继承父级 Git 仓库

当你在子目录执行命令，而 .git 在父目录：

• 默认 --repo-mode auto：自动定位到父仓库根目录执行
• --repo-mode strict：检测到继承时直接阻断，避免误操作

3) 非 Git 目录

icode 不会在非 Git 目录中隐式执行 git init。如果需要初始化仓库，请先手动执行 git init，再运行 icode 命令。

开发

npm test
node bin/icode.js help
node bin/icode.js undo

发布

当前 npm 包名：

@icode-js/icode

首次发布 scoped 包请显式指定公开访问权限：

npm publish --access public