Agent Demo — Development skill for Claude Code

agent-demo

Java 编写的 Claude Code 风格 Agent CLI。第一阶段独立调 LLM API（DeepSeek），后续可扩展多 Provider。

---

1. 项目定位

在终端里与 LLM 协作：流式对话、调用本地工具（读文件、执行命令）、多步自主完成任务、会话持久化到本地。

维度	设计取向
集成方式	独立调 LLM API（不依赖 dsh / Claude Code 进程）
目标用户	习惯终端、追求可控与可观测的开发者
模型支持	多 Provider 抽象层，v0.1 首实现 DeepSeek（OpenAI 兼容协议）
能力范围	Claude Code 核心能力集：流式对话、工具调用、权限确认、会话持久化、Memory

与 Claude Code 的关系：本项目独立实现，借鉴其成熟的工程模式（Tool 协议对象、append-only JSONL 会话、compact 熔断、`MEMORY.md` 索引）。**不依赖 Claude Code 运行时**，不调用其 API。

---

2. 核心特性（v0.1）

• ✅ REPL 交互：连续多轮对话、流式输出（边生成边打印）
• ✅ 工具调用：ReadFile / WriteFile / EditFile / Ls / Shell，自动执行并回流结果
• ✅ 权限确认：写文件与命令执行需要用户交互确认（默认 allow-read, ask-write）
• ✅ 会话持久化：JSONL append-only 格式保存到 ~/.agent-demo/sessions/（v0.1 仅保存，v0.2 支持 resume）
• ✅ Slash 命令：/help /clear /quit /history /resume（/model v0.2）
• ✅ Memory 记忆：长期记忆写入 ~/.agent-demo/memory/，下次会话按相关度自动召回
• ✅ 上下文压缩：128K 上限前自动触发 compact，失败熔断防止死循环
• ✅ 错误重试：网络 / 5xx / 429 自动重试；401 立即停止，REPL 打印友好提示（key 未设 / 失效 / 网络 / 限流）后继续等待输入而非退出进程
• ✅ Ctrl+C 中断：第一次优雅取消当前生成、第二次（500ms 内）强制退出
• ✅ 跨平台：Windows / Linux / macOS；中文编码三重防御（GBK↔UTF-8 回退）
• ✅ 成本可见：每轮 token 累计，/history 显示估算费用，达到阈值告警 / 停止

---

3. 技术栈

类别	选型	版本	理由
JDK	OpenJDK	17	与 rocketmq-demo 保持一致
框架	Spring Boot	3.2.x	同上
HTTP	Spring WebFlux WebClient	6.1.x	原生支持 SSE 流式响应
CLI	picocli	4.7.x	注解式，子命令 / 选项齐全
JSON	Jackson	2.15.x	Spring Boot 默认
终端	JLine3	3.25.x	raw mode、历史、自动补全
构建	Maven	3.9.x	与现有项目一致

**不引入 Lombok、spring-boot-starter-web、数据库**——CLI 不需要 servlet 容器，v0.1 JSON 文件存会话足够。

---

4. 快速开始

4.1 构建

mvn clean package -DskipTests

产物：`target/agent-cli.jar`（fat jar，约 15 MB，可直接执行）。

4.2 初始化配置

java -jar target/agent-cli.jar init

在 `~/.agent-demo/config.yaml` 生成默认配置：

provider:
  type: deepseek
  apiKey: REPLACE_ME       # 改为你的 DeepSeek API key
  baseUrl: https://api.de