更新日期：2026 年 2 月 14 日

Hajimi Code 使用文档

Hajimi Code 是一款 AI 命令行助手，支持交互对话、一次性任务、Web 界面和多平台渠道桥接。内置技能系统、自定义命令、项目记忆和会话管理，让 AI 真正融入你的开发工作流。当前版本：0.3.14。

概览

Hajimi Code 提供四种使用方式，你可以根据场景灵活选择：

交互对话（REPL）

输入 hajimi 进入持续对话模式，像聊天一样与 AI 交互。支持上下文记忆、命令补全和会话恢复。

一次性执行（run）

使用 hajimi run 执行单次任务，完成即退出。支持 JSON 输出，适合脚本和 CI/CD。

Web 界面（web）

使用 hajimi web 启动本地 Web 服务，通过浏览器与 AI 交互，支持审批确认和会话管理。

渠道桥接（channel）

通过 hajimi channel 将 AI 接入 Telegram、Discord、Slack、Mattermost 或飞书。

种模型协议

OpenAI · Anthropic · Gemini · OpenAI Response

个内置命令

/commit · /review · /fix · /explain …

个渠道平台

Telegram · Discord · Slack · Mattermost · 飞书

安装与启动

1) 通过 Homebrew 安装（推荐）
macOS 和 Linux 用户推荐使用 Homebrew 一键安装：
brew tap hajimi-work/tap brew install hajimi
安装完成后，可以使用 hajimi 或简写 h 来调用。
2) 手动下载安装
前往 Releases 页面下载对应平台的二进制文件，解压后放入 PATH 目录即可。
3) 首次运行配置
首次运行会自动启动配置向导：
hajimi # 按提示选择 API 协议（OpenAI / Anthropic / Gemini） # 输入你的 API Key 和 Base URL # 选择默认模型
配置完成后即可开始使用。后续可通过 hajimi config 随时修改。
4) 验证安装
hajimi version hajimi run 你好，请做个自我介绍

环境变量快速配置—如果你已有 API Key，可以通过环境变量跳过向导：export OPENAI_API_KEY=sk-xxx，Hajimi 会自动识别并创建供应商。

命令参考

命令	说明
`hajimi`	进入交互式对话模式（REPL）。首次运行会触发配置向导。
`hajimi run <任务>`	一次性执行任务，完成后自动退出。适合快速提问或脚本调用。
`hajimi run --json <任务>`	以 JSON 格式输出结果，适合 CI/CD 流水线集成。
`hajimi run --json -o <路径> <任务>`	将 JSON 结果保存到指定文件。
`hajimi web`	启动本地 Web 界面（默认端口 3000），通过浏览器与 AI 交互。
`hajimi web --port 8080`	指定端口启动 Web 界面。
`hajimi channel`	启动渠道桥接服务，连接 Telegram、Discord 等平台。
`hajimi channel --print-template`	打印渠道配置模板到终端。
`hajimi channel --once`	单次轮询，用于验证渠道配置是否正确。
`hajimi channel -c <路径>`	指定渠道配置文件路径（默认 ~/.hajimi/channels.toml）。
`hajimi config`	打开配置 Web 页面，管理供应商、模型和全局设置。
`hajimi version`	查看当前版本号。
`hajimi help`	查看所有可用命令和选项。

快捷别名 `h`

通过 Homebrew 安装后，可以使用 h 作为 hajimi 的简写：

你输入的	实际执行
`h`	进入交互对话模式（等同于 hajimi）
`h 修复这个函数`	自动改写为 hajimi run 修复这个函数
`h config`	识别为子命令，执行 hajimi config
`h --help`	识别为 CLI 选项，执行 hajimi --help

交互模式（REPL）

输入 hajimi 进入交互模式后，你可以持续与 AI 对话，并使用各种内置命令。支持 Tab 键补全命令名。

命令	别名	说明
`/help`	`/帮助`	查看所有可用命令
`/exit`	`/quit, /退出`	退出交互模式
`/clear`	`/铲屎, /清空`	清空当前上下文
`/compact`	`/压缩`	压缩上下文（保留关键信息，释放 Token）
`/memory`	`/记忆`	管理项目记忆（查看、固定、清空）
`/skills`	`/技能`	管理技能（查看、启用、禁用、安装）
`/yolo`	`—`	切换审批模式（YOLO ↔ Default）
`/sessions`	`/会话`	查看和恢复历史会话
`/model`	`—`	切换模型或供应商
`/rollback`	`/回滚`	回滚到之前的检查点
`/<命令名>`	`—`	执行内置或自定义命令（如 /review、/commit）

/memory 子命令

/memory show [N] — 查看最近 N 条记忆
/memory pin <内容> — 固定一条记忆
/memory clear — 清空项目记忆

/sessions 子命令

/sessions — 列出最近会话
/sessions resume <ID> — 恢复指定会话

/rollback 子命令

/rollback <N> — 回滚 N 步
/rollback step <S> — 回滚到第 S 步

/model 子命令

/model — 打开模型选择菜单
/model <model_id> — 直接切换到指定模型

崩溃恢复—如果上次会话异常退出，再次启动 hajimi 时会提示恢复，你可以选择继续上次的对话。

内置命令

在交互模式中，输入 / 开头的命令可以快速执行常见任务。所有内置命令都支持中文别名：

命令	中文别名	说明
`/commit`	`/提交`	生成 Git 提交信息并提交
`/review`	`/审查`	审查当前代码改动
`/fix`	`/修复`	修复指定问题
`/explain`	`/解释`	解释代码逻辑
`/refactor`	`/重构`	重构代码
`/test`	`/测试`	编写测试用例
`/doc`	`/文档`	生成代码文档
`/init`	`/初始化`	分析项目结构并生成概览

使用示例

# 审查当前改动
/review

# 审查并附加说明
/review 重点关注性能问题

# 提交代码
/commit

# 为指定文件写测试
/test src/utils.ts

命令后面可以追加参数，AI 会将其作为补充说明。例如 /review 重点关注安全问题。

自定义命令

你可以创建自己的命令模板，减少重复输入。自定义命令会覆盖同名的内置命令。

全局命令

放在 ~/.hajimi/commands/ 目录下，所有项目通用。

项目命令

放在 .hajimi/commands/（项目根目录），仅当前项目生效，优先级高于全局。

创建步骤

1. 创建 Markdown 文件，如 ~/.hajimi/commands/deploy.md
2. 文件内容就是发给 AI 的提示词模板
3. 在交互模式中输入 /deploy 即可使用

# 示例：创建一个部署检查命令
# 文件：~/.hajimi/commands/deploy-check.md

检查当前项目的部署配置：
1. 验证环境变量是否完整
2. 检查 Dockerfile 是否存在且正确
3. 确认 CI/CD 配置文件语法正确
4. 列出可能影响部署的未提交改动

加载优先级：内置命令 → 全局命令 → 项目命令。项目级命令可以覆盖全局和内置命令。

技能系统

技能（Skills）是一种让 AI 掌握特定领域知识的扩展机制。每个技能是一个包含 SKILL.md 的目录。

内置技能

code-review — 代码审查
commit-message — 提交信息生成
explain — 代码解释
refactor — 代码重构
write-tests — 测试编写

技能位置

~/.hajimi/skills/ — 全局技能（最高优先级）
.hajimi/skills/ — 项目技能
内置技能 — 最低优先级

创建自定义技能

在技能目录下创建一个文件夹，包含 SKILL.md 文件：

# 目录结构
~/.hajimi/skills/my-skill/
└── SKILL.md

# SKILL.md 示例
---
name: my-skill
description: "我的自定义技能"
when_to_use: "当用户需要处理 XXX 时"
tags:
  - custom
---

你是一个专注于 XXX 领域的专家。

## 工作流程
1. 首先分析用户的需求
2. 然后按照以下规范处理
...

## 注意事项
- 始终遵循 XXX 规范
- 输出格式使用 XXX

管理技能

在交互模式中使用 /skills 命令管理：

/skills          # 打开技能管理菜单
                 # 可以查看、启用、禁用或从远程安装技能

SKILL.md 支持 YAML frontmatter，可以指定触发条件（when_to_use）、文件匹配模式（applicable_patterns）、需要的工具（requires_tools）等。

使用场景

以下是一些常见的使用场景和对应命令：

代码审查

让 AI 审查你的代码改动，发现潜在问题和优化建议。

hajimi run 帮我审查当前 git 改动，指出潜在问题

代码重构

交给 AI 处理重复性的重构工作，提高代码质量。

hajimi run 把这个文件里的 class 组件重构为函数组件

编写测试

快速为现有代码生成单元测试。

hajimi run 为 src/utils.ts 编写单元测试

文档生成

自动为函数和模块生成注释和文档。

hajimi run 为当前目录下所有导出函数添加 JSDoc 注释

问题排查

描述遇到的问题，让 AI 帮你定位和修复。

hajimi run 这个接口返回 500 错误，帮我排查原因

CI/CD 集成

在流水线中自动执行代码检查并输出结构化结果。

hajimi run --json --output report.json 检查代码规范

run --json 输出结构

在 CI/CD 或自动化脚本中，使用 --json 获得结构化输出：

hajimi run --json --output result.json 帮我整理本次改动

{
  "final_response": "AI 的最终回复内容",
  "changed_files": ["src/main.rs", "README.md"],
  "tokens": {
    "prompt": 1234,
    "completion": 456,
    "cache_read": 0,
    "total": 1690
  },
  "elapsed_ms": 8421
}

字段	类型	说明
`final_response`	string	AI 的最终回复文本
`changed_files`	string[]	本次任务修改的文件列表（相对路径）
`tokens`	object	Token 统计：prompt / completion / cache_read / total
`elapsed_ms`	number	任务执行总耗时（毫秒）

渠道桥接

渠道桥接可以将 Hajimi 接入团队通讯平台，让成员通过聊天消息直接与 AI 交互。

1) 生成配置模板
hajimi channel --print-template > ~/.hajimi/channels.toml
2) 编辑配置文件
打开 ~/.hajimi/channels.toml，填入对应平台的配置。
3) 启动桥接服务
hajimi channel
4) 验证连接
hajimi channel --once # 单次轮询，确认配置正确

支持的平台

平台	kind 值	主要配置字段
Telegram	`telegram`	`bot_token, allowed_chat_ids, poll_timeout_secs`
Discord	`discord`	`bot_token, channel_ids, limit`
Slack	`slack`	`bot_token, channel_ids, limit`
Mattermost	`mattermost`	`bot_token, api_base, channel_ids, limit`
飞书	`feishu`	`app_id, app_secret, allowed_chat_ids, command_prefixes`

全局配置

poll_interval_ms — 轮询间隔（默认 1500ms）
seen_cache_size — 已处理消息缓存大小（默认 4096）

安全建议—建议开启受控聊天范围（如 allowed_chat_ids / channel_ids），飞书平台还支持 require_command_prefix 和 require_bot_mention 来避免误触发。

Web 界面

hajimi web 启动一个本地 Web 服务，提供图形化的交互界面。

hajimi web              # 默认端口 3000
hajimi web --port 8080  # 指定端口

对话与审批

通过浏览器与 AI 对话，文件写入和命令执行会弹出审批确认框。

会话管理

查看历史会话列表，恢复之前的对话。支持检查点和回滚。

记忆管理

查看和管理项目记忆，固定重要信息，清除过期记忆。

模型切换

在 Web 界面中切换供应商和模型，实时生效。

hajimi config 也会启动一个 Web 页面（随机端口），专门用于配置管理，自动打开浏览器。

审批模式

审批模式控制 AI 执行操作时是否需要你的确认。你可以根据信任程度选择合适的模式：

默认模式

default

只读操作自动通过；文件写入、命令执行、MCP 调用需要你确认。

自动编辑

auto_edit

文件编辑操作自动通过；命令执行和 MCP 调用仍需确认。

YOLO 模式

yolo

所有操作自动通过（危险命令除外）。适合你完全信任 AI 的场景。

操作分类

始终自动通过

文件读取、搜索、目录列表、思考等只读操作。

受审批模式控制

文件写入、命令执行、MCP 调用等可能产生副作用的操作。

切换方式

• 交互模式中输入 /yolo 快速切换 YOLO ↔ Default
• 在 ~/.hajimi/config.toml 中设置 approval_mode
• 通过环境变量 HAJIMI_APPROVAL_MODE 覆盖
• 在 hajimi config Web 页面中修改

即使在 YOLO 模式下，明显危险的命令（如 rm -rf /）仍然会被拒绝。

项目记忆

项目记忆让 AI 记住关于当前项目的重要信息，在后续对话中自动参考。

自动记忆

AI 在工作过程中会自动记录项目的关键信息（如技术栈、代码规范、架构决策等）。

手动固定

你可以用 /memory pin 手动固定重要信息，确保 AI 始终记住。

/memory show       # 查看当前项目的所有记忆
/memory show 5     # 查看最近 5 条
/memory pin 这个项目使用 pnpm 作为包管理器
/memory clear      # 清空项目记忆

记忆按项目隔离，存储在 ~/.hajimi/memory/ 目录下。不同项目的记忆互不影响。

会话管理

每次对话都会自动保存为会话，你可以随时恢复之前的对话继续工作。

会话状态

Active — 进行中
Completed — 已完成
Crashed — 异常退出

恢复会话

使用 /sessions 查看列表，/sessions resume <ID> 恢复指定会话。

检查点回滚

每轮对话自动创建检查点，使用 /rollback 可以回到之前的状态。

/sessions                  # 列出最近会话
/sessions resume abc123    # 恢复指定会话
/rollback 3                # 回滚 3 步
/rollback step 5           # 回滚到第 5 步

会话数据存储在 ~/.hajimi/sessions/，与 Hajimi Work 桌面端共享。

MCP 与 Hooks

MCP（Model Context Protocol）服务器和 Hooks 让你扩展 AI 的能力和自定义工作流程。

MCP 服务器

在 ~/.hajimi/config.toml 中配置 MCP 服务器，AI 可以调用其提供的工具：

# ~/.hajimi/config.toml

[[mcp.servers]]
name = "my-server"
command = "npx"
args = ["-y", "my-mcp-server"]
env = { API_KEY = "xxx" }

Hooks（钩子）

Hooks 让你在 AI 执行特定操作前后自动运行脚本：

# ~/.hajimi/config.toml

[[hooks.hooks]]
event = "before_tool"    # 工具调用前
command = "check.sh"
timeout_secs = 15

[[hooks.hooks]]
event = "session_end"    # 会话结束后
command = "notify.sh"

工具相关

before_tool
after_tool

模型相关

before_model
after_model

会话相关

session_start
session_end

配置参考

所有配置文件都在 ~/.hajimi 目录下。项目级配置放在 .hajimi/（项目根目录），优先级更高。

config.toml 字段说明

字段	类型	默认值	说明
`approval_mode`	string	`"default"`	审批模式：default / auto_edit / yolo
`log_level`	string	`"info"`	日志级别：error / warn / info / debug / trace
`max_steps`	number	`300`	代理最大执行步数
`log_retention_days`	number	`7`	日志保留天数
`max_context_tokens`	number	`0 (=200000)`	上下文窗口大小（0 表示使用默认 200000）
`max_output_tokens`	number	`8000`	单次最大输出 Token 数
`custom_prompt_file`	string	`—`	自定义系统提示词文件路径
`max_concurrent_subagents`	number	`—`	最大并发子代理数

HAJIMI.md（自定义指令）

创建 HAJIMI.md 文件，写入你的偏好指令，AI 会在每次对话中参考：

# ~/.hajimi/HAJIMI.md（全局）或 .hajimi/HAJIMI.md（项目级）

- 回复使用中文
- 代码风格偏好函数式编程
- 使用 pnpm 而不是 npm
- 提交信息使用英文

加载优先级—项目级 .hajimi/HAJIMI.md → 全局 ~/.hajimi/HAJIMI.md → custom_prompt_file 指定的文件。

目录结构一览

~/.hajimi/
├── config.toml              # 全局配置
├── HAJIMI.md                # 全局自定义指令
├── channels.toml            # 渠道桥接配置
├── skills.json              # 技能启用/禁用状态
├── settings/
│   ├── providers.toml       # API 供应商配置
│   └── active.toml          # 角色模型绑定
├── commands/                # 全局自定义命令
│   └── my-command.md
├── skills/                  # 全局技能
│   └── my-skill/
│       └── SKILL.md
├── sessions/                # 会话数据
│   └── <session-id>/
│       ├── state.json
│       └── messages.jsonl
└── memory/                  # 项目记忆
    └── <project-hash>/
        └── memory.md

环境变量

环境变量的优先级高于配置文件，适合在 CI/CD 或临时场景中使用：

环境变量	说明
`HAJIMI_APPROVAL_MODE`	覆盖审批模式（default / auto_edit / yolo）
`HAJIMI_LOG`	覆盖日志级别
`HAJIMI_MAX_STEPS`	覆盖最大步数
`HAJIMI_MAX_CONTEXT_TOKENS`	覆盖上下文 Token 上限
`HAJIMI_MAX_OUTPUT_TOKENS`	覆盖输出 Token 上限
`OPENAI_API_KEY / OPENAI_BASE_URL`	自动创建 OpenAI 环境供应商
`ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL`	自动创建 Anthropic 环境供应商
`GEMINI_API_KEY`	自动创建 Gemini 环境供应商

配置优先级—内置默认 → 全局 config.toml → 项目 config.toml → 环境变量 → CLI 参数

常见问题

首次运行提示配置缺失

直接运行 hajimi 进入交互模式，会自动触发配置向导。也可以设置环境变量 OPENAI_API_KEY 快速跳过。

--output 参数报错

--output 必须和 --json 一起使用。正确写法：hajimi run --json --output result.json 任务描述

渠道桥接无响应

先用 hajimi channel --once 进行单次轮询测试。检查 Bot Token 和频道 ID 是否正确，确认网络能访问对应平台 API。

模型切换不生效

运行 hajimi config 检查角色绑定。确认 ~/.hajimi/settings/active.toml 中 General / Fast / Pro 指向了正确的模型。

API 调用超时或失败

检查网络连接和 API Key 是否有效。如使用代理，确认代理设置正确。可以用 hajimi run 你好 做简单测试。

会话恢复失败

确认 ~/.hajimi/sessions/ 目录存在且有权限读取。如果会话数据损坏，可以删除对应的会话目录。

自定义命令不生效

检查文件是否放在正确位置（~/.hajimi/commands/ 或 .hajimi/commands/），文件扩展名必须是 .md。

技能没有被触发

用 /skills 确认技能已启用。检查 SKILL.md 中的 when_to_use 和 applicable_patterns 是否匹配当前场景。

概览

交互对话（REPL）

一次性执行（run）

Web 界面（web）

渠道桥接（channel）

安装与启动

1) 通过 Homebrew 安装（推荐）

2) 手动下载安装

3) 首次运行配置

4) 验证安装

命令参考

快捷别名 h

交互模式（REPL）

/memory 子命令

/sessions 子命令

/rollback 子命令

/model 子命令

内置命令

使用示例

自定义命令

全局命令

项目命令

创建步骤

技能系统

内置技能

技能位置

创建自定义技能

管理技能

使用场景

代码审查

代码重构

编写测试

文档生成

问题排查

CI/CD 集成

run --json 输出结构

渠道桥接

1) 生成配置模板

2) 编辑配置文件

3) 启动桥接服务

4) 验证连接

支持的平台

全局配置

Web 界面

对话与审批

会话管理

记忆管理

模型切换

审批模式

默认模式

自动编辑

YOLO 模式

操作分类

始终自动通过

受审批模式控制

切换方式

项目记忆

自动记忆

手动固定

会话管理

会话状态

恢复会话

检查点回滚

MCP 与 Hooks

MCP 服务器

Hooks（钩子）

工具相关

模型相关

会话相关

配置参考

config.toml 字段说明

HAJIMI.md（自定义指令）

目录结构一览

环境变量

常见问题

首次运行提示配置缺失

--output 参数报错

渠道桥接无响应

模型切换不生效

API 调用超时或失败

快捷别名 `h`