🚀 第一篇：快速上手

第1章十分钟跑起来：构建、启动与第一次对话

先获得直觉，再深入原理——让系统在你眼前活起来

1.1 本章导读

上一章我们说了"Harness 是什么"，这一章就把它真正跑起来。你将完成：克隆代码 → 一次构建 → 选择一种方式启动 → 在浏览器里和 Agent 对话。本章不需要你理解任何内部原理，照着做即可。

1.2 环境检查

打开终端，确认以下命令都有输出：

java -version    # 需要 17 或更高
mvn -version     # 需要 3.9 或更高

如果用的是 Node 插件（第9章）或 MCP（第10章），还需要 node -v 18+。MySQL 和 Docker 都是可选的——本章默认用零依赖的 H2 模式。

1.3 克隆与构建

git clone https://gitcode.net/KnowledgePlanet/deepseek-harness-java.git
cd deepseek-harness-java

# 快速打包（跳过测试，约 1-2 分钟）
mvn clean package -DskipTests

构建成功后会生成一个可执行 JAR：

deepseek-harness-java-app/target/deepseek-harness-java-app-1.0.0-SNAPSHOT.jar

📦 幕后发生了什么

这是一个 7 模块的 Maven 聚合工程。app 模块依赖其余所有模块，Spring Boot Maven 插件把所有内容打成一个 fat jar——你拿到的这个 JAR 就是整个系统，包含 Web 控制台、Agent 引擎、插件加载器和内嵌 H2 支持。

1.4 启动：三种方式选一种

方式一：Standalone（推荐首次体验，零外部依赖）

使用内嵌 H2 文件数据库，不需要装 MySQL：

export DEEPSEEK_API_KEY='你的模型API Key'

java -jar deepseek-harness-java-app/target/deepseek-harness-java-app-1.0.0-SNAPSHOT.jar \
  --spring.profiles.active=standalone

看到 Started DeepSeekHarnessApplication in X seconds 即启动成功，H2 数据文件写入 ./data/deepseek-harness-java.mv.db。

方式二：MySQL（默认 profile，贴近生产）

export SPRING_DATASOURCE_URL='jdbc:mysql://127.0.0.1:3306/deepseek_harness_java?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true'
export SPRING_DATASOURCE_USERNAME='root'
export SPRING_DATASOURCE_PASSWORD='你的密码'
export DEEPSEEK_API_KEY='你的模型API Key'

java -jar deepseek-harness-java-app/target/deepseek-harness-java-app-1.0.0-SNAPSHOT.jar

首次启动会自动执行 schema.sql 创建 12 张表（幂等，可重复启动）。

方式三：Docker Compose（最省心）

export DEEPSEEK_API_KEY='你的模型API Key'
docker compose up --build -d

Compose 会暴露 8090:8090，使用 standalone profile，并把 ./data、./plugins、./workspaces 挂载出来。

⚠️ 关于 API Key

系统通过 harness.llm.deepseek.api-key 配置模型网关的 Key，默认从环境变量 DEEPSEEK_API_KEY 读取。任何 OpenAI 兼容网关（DeepSeek 官方、自建网关、OneAPI 等）都可以，配合 base-url 一起改。

1.5 打开 Web 控制台

浏览器访问 http://localhost:8090/，你会看到一个类似 AI 编程助手的界面。左侧是工作区与会话列表，中间是对话区，顶部可以切换模型。

控制台是纯原生 JavaScript 实现的（约 3300 行，无前端构建链），本地加载 marked（Markdown 解析）、DOMPurify（XSS 过滤）、highlight.js（代码高亮）三个库——即使在内网环境也能完整运行。

1.6 第一次对话

在控制台输入框里发一句"你好，介绍一下你自己"，稍等片刻就能看到流式输出的回复。如果你让它"列出当前目录的文件"，你会看到界面中出现一张工具卡片——那是 Agent 在调用 shell_execute 工具，这正是 Harness 的核心能力：模型不只是说话，还能动手。

也可以用 curl 直接调 API：

# 阻塞式对话
curl -X POST http://localhost:8090/api/agent/message \
  -H 'Content-Type: application/json' \
  -d '{"agentId": "local-agent", "message": "Hello!"}'

# SSE 流式对话（观察事件流）
curl -N -X POST http://localhost:8090/api/agent/stream \
  -H 'Content-Type: application/json' \
  -d '{"agentId": "local-agent", "message": "介绍这个项目的架构"}'

流式接口会返回一系列事件：meta（起始帧）→ chunk（文本增量）→ 可能有 step_break（工具调用边界）→ done（终态）。第7章会完整解析这个协议。

1.7 验证清单

☐ java -version 显示 17+，mvn -version 显示 3.9+
☐ mvn clean package -DskipTests 构建成功
☐ 启动日志出现 Started DeepSeekHarnessApplication
☐ 浏览器打开 http://localhost:8090/ 能看到控制台
☐ 发送一条消息能收到流式回复
☐（可选）让它列目录，能看到工具卡片出现

1.8 小结与下一章预告

本章要点：一个 fat jar 就是整个系统；standalone 模式用 H2 零依赖启动；控制台是原生 JS 无需构建；对话走 /api/agent/stream SSE 接口。

下一章：你已经见过它跑起来的样子了。现在我们退一步俯瞰——这个系统的 7 个 Maven 模块如何划分？为什么依赖方向必须是单向的？什么是六边形架构？第2章带你建立全局视图。

第1章 十分钟跑起来：构建、启动与第一次对话