太强了!用 Java 写了个 AI 编程助手

最近，在github看到一个迷你版的claude code 叫做jcode。非常适合初学者学习如何基于harness工程搭建一个coding agent。

https://github.com/ruokkkkk/jcode

jcode 是一个基于 Java 的 AI 命令行编程助手，灵感来自 Claude Code，由 AgentScope Java Harness 驱动。它能读写文件、搜索代码、执行 shell 命令，并通过持久化记忆与会话跨进程保持上下文。

jcode> read README.md and summarize the build steps

特性

文件操作：读、写、编辑、搜索项目文件（基于 AgentScope LocalFilesystemWithShell）
Shell 执行：运行构建、测试和任意 shell 命令；Windows 下自动复用 Git Bash 的 sh.exe
持久化记忆：每日事实日志 + 长期记忆双层结构，跨会话保留
上下文压缩：历史过长时自动摘要，长会话也不会爆 token
会话管理：固定 session ID 持久化，或按编号恢复最近的工作区会话
流式输出：助手回复随生成增量渲染，不必等待整轮完成
REPL 体验：持久输入历史、多行续行（\、未闭合 fence/括号）、斜杠命令补全
健康诊断：/doctor 一键自检文件系统与 shell 能力

先决条件

条件	说明
JDK 21+	推荐 Eclipse Temurin 21
OpenAI 兼容 API Key	官方 OpenAI、LongCat、DeepSeek、Azure OpenAI、自部署 vLLM 等任一 OpenAI 协议端点均可
Git Bash(Windows 仅)	提供 `sh.exe` 给 shell 工具调用；安装 Git for Windows 即可

不需要预装 Maven —— 仓库内置 Maven Wrapper（mvnw / mvnw.cmd），首次构建会自动下载 Maven 3.9.9。

快速开始

1. 获取代码

git clone <repo-url>
cd jcode

2. 配置 API Key

方式 A — 环境变量（推荐，不入库）

# macOS / Linux
export OPENAI_API_KEY=sk-...

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-..."

方式 B — application.properties

编辑 src/main/resources/application.properties：

openai.api.key=sk-...
openai.base.url=https://api.openai.com/v1   # 可选，自定义端点
openai.model=gpt-4o                          # 可选

如果你打算把项目入库到公开仓库，把这个文件加入 .gitignore。

3. 构建并运行

Windows

.\mvnw.cmd package -DskipTests
java -jar target\jcode-0.1.0-SNAPSHOT.jar

或直接用打包好的脚本（自动校验 API Key、注入 sh.exe 到 PATH）：

.\jcode.bat

macOS / Linux

./mvnw package -DskipTests
java -jar target/jcode-0.1.0-SNAPSHOT.jar

开发模式（不打包，直接 exec）：

./mvnw exec:java        # macOS / Linux
.\mvnw.cmd exec:java    # Windows

启动后将看到：

jcode 0.1.0
Type /help for available commands.

jcode>

配置

属性	环境变量	默认值	说明
`openai.api.key`	`OPENAI_API_KEY`	(必填)	OpenAI 兼容 API Key
`openai.base.url`	`OPENAI_BASE_URL`	`https://api.openai.com/v1`	API 端点，可指向第三方代理
`openai.model`	`JCODE_MODEL`	`gpt-4o`	模型名
`jcode.workspace`	`JCODE_WORKSPACE`	`.jcode/workspace`	工作区目录（持久化记忆位置）
`jcode.session`	`JCODE_SESSION`	(自动生成)	固定 session ID，跨进程恢复同一会话

优先级（从高到低）：环境变量 → application.properties → 内置默认值。

使用

启动后进入 REPL，普通输入会发送给 AI 智能体；以 / 开头的输入会被解释为本地命令。

斜杠命令

命令	描述
`/help`	显示所有可用命令
`/exit` 或 `/quit`	退出 jcode
`/clear`	清屏
`/model`	显示当前模型与端点信息
`/session`(或 `/session list`)	显示当前 session ID 或列出最近工作区会话
`/resume <编号或 ID>`	恢复指定的工作区会话（如 `/resume 1` 或 `/resume jcode-4527b76d`）
`/compact`	显示上下文统计或清空内存中的历史
`/doctor`	诊断文件系统、shell、工作区、模型等运行环境
`/rm <path>`	删除一个工作区文件（不经过 shell）

多行输入

需要粘贴多行代码或长 prompt 时：

行末加 \ 显式续行
未闭合的 围栏 会自动续行
未闭合的 ()、[]、{} 会自动续行
历史可用 ↑/↓ 翻阅，跨进程持久化

会话与恢复

jcode> /session
Current session: jcode-4527b76d

jcode> /session list
1  jcode-4527b76d   (last used 5m ago)
2  jcode-91ac2f01   (last used 2h ago)

jcode> /resume 2
Resumed session jcode-91ac2f01

或者启动时直接固定 session：

JCODE_SESSION=my-project java -jar target/jcode-0.1.0-SNAPSHOT.jar

架构

┌────────────┐    ┌────────────────┐    ┌─────────────────────────┐
│ User Input │───▶│  JCodeShell    │───▶│   CommandDispatcher     │
└────────────┘    └────────────────┘    └────────────┬────────────┘
                                                     │
                              ┌──────────────────────┴──────────────────────┐
                              ▼                                             ▼
              ┌──────────────────────────┐               ┌──────────────────────────┐
              │ AgentConversationService │               │     SlashCommands        │
              │  (HarnessAgent + Tools)  │               │ help/exit/model/...      │
              └────────────┬─────────────┘               └──────────────────────────┘
                           │
                           ▼
                ┌──────────────────────┐
                │  AgentScope Harness  │
                │  • Filesystem Tool   │
                │  • Shell Tool        │
                │  • Memory & Compact  │
                │  • Session Persist   │
                └──────────────────────┘

底层依赖 AgentScope Java Harness 提供：

Workspace 上下文注入：从工作区文件加载 agent persona 与领域知识
两层记忆：每日事实日志 + 长期合并记忆
自动压缩：历史过长时摘要后再继续
会话持久化：跨进程恢复同一会话状态

项目结构

jcode/
├── mvnw / mvnw.cmd               # Maven Wrapper
├── .mvn/wrapper/                 # Wrapper 配置
├── pom.xml                       # 构建定义
├── jcode.bat                     # Windows 一键启动脚本
├── docs/                         # 详细文档
│   ├── INSTALLATION.md
│   └── DOCKER_DEPLOYMENT.md
├── src/main/java/jcode/
│   ├── JCodeRepl.java            # 入口
│   ├── JCodeConfig.java          # 配置加载
│   ├── AnsiColors.java           # 终端着色
│   ├── agent/                    # AI 对话与工具调用
│   ├── command/                  # 斜杠命令实现
│   ├── filesystem/               # 文件系统适配 / 路径规范化
│   ├── session/                  # 会话状态与持久化
│   ├── shell/                    # REPL 主循环、命令分发、补全
│   └── ui/                       # CLI 渲染
├── src/main/resources/
│   └── application.properties    # 默认配置模板
└── .jcode/workspace/             # 运行时工作区（自动创建）

常见问题

启动报 `Invalid signature file digest for Manifest main attributes`

shaded fat-jar 中包含了被签名过的依赖（如 jna），Shade 重新打包后签名失效。本项目 pom.xml 已在 maven-shade-plugin 中配置 META-INF/*.SF|*.DSA|*.RSA 过滤；如果你 fork 后自己改了 shade 配置导致复发，请确保 filter 段保留。

Windows 下 shell 工具报 `sh.exe not found`

AgentScope 的 shell 工具依赖 POSIX sh。安装 Git for Windows，然后运行 jcode.bat（它会自动把 Git 自带的 sh.exe 加入 PATH）。或手动：

$env:PATH = "C:\Program Files\Git\bin;$env:PATH"
java -jar target\jcode-0.1.0-SNAPSHOT.jar

模型一直返回 401 / 网络错误

jcode> /doctor

会打印当前的端点、模型、工作区、文件系统类型，帮助快速定位是 key、URL 还是网络问题。

想用第三方 OpenAI 协议端点（DeepSeek / LongCat / 通义千问等）

只需配置 openai.base.url 和 openai.model 即可，例如：

openai.api.key=ak_xxxx
openai.base.url=https://api.longcat.chat/openai
openai.model=LongCat-2.0-Preview

开发

运行测试

./mvnw test# macOS / Linux
.\mvnw.cmd test# Windows

加一个新斜杠命令

在 src/main/java/jcode/command/ 下新建 XxxCommand.java，实现 CommandHandler 接口
在 JCodeRepl 启动时通过 CommandRegistry.register(...) 注册
/help 会自动列出新命令

构建可执行 fat-jar

./mvnw clean package -DskipTests
# 产物: target/jcode-0.1.0-SNAPSHOT.jar

License

MIT

目录

特性