第17章 版本演进：v0.1.3 到 v0.1.5 交付实录
看一个 Agent Harness 如何逐版从「能力可运行」走到「插件链路可信」
17.1 本章导读
前 16 章讲的是"系统长什么样、为什么这样设计"；本章换一个视角——看版本。deepseek-harness-java 在 2026 年 9 月连续交付了 v0.1.3、v0.1.4、v0.1.5 三个版本，每一版都对应第 12-13 章提到的"从 Demo 到产品"路线图上的一段。读这一章，你能看到一个真实开源项目如何排版本主线、如何控制变更范围、如何验证交付质量。
| 版本 | 主线 | 变更规模 | 对应章节 |
|---|---|---|---|
v0.1.3 | 统一配置模型、MCP & Skills 扩展、对话 UI 完善 | 84 个文件，+3698 / -596 行 | 第 9/10/16 章 |
v0.1.4 | 插件工程化：产物识别、配置持久化、状态对账、业务插件落地 | 35 个文件，+2528 / -235 行 | 第 9 章 |
v0.1.5 | 插件能力完善与安全加固：@提及、接口访问控制、注册校验、注入防护 | 10 个文件，+303 / -14 行 | 第 9 章 / 本章 |
v0.1.3 铺能力（3698 行新增），v0.1.4 做工程化（2528 行新增），v0.1.5 只做加固（303 行新增、10 个文件）。版本越到后期，变更面越收、每个改动越对准具体风险——这正是"从 Demo 走向产品"的节奏。
17.2 v0.1.5：@插件提及与访问控制
v0.1.5 没有新增插件机制的主干能力，而是把 v0.1.4 交付的插件链路从「可用」推进到「可信」。四个加固点分别落在四个层次：
17.2.1 对话侧：@插件提及
控制台输入框敲 @ 唤起插件候选列表（按插件 ID / 显示名模糊匹配，仅展示 ACTIVE 插件，最多 8 条），选中后回填 @<pluginId> 。AgentDispatchNode 识别提及后在消息末尾追加 [插件提及] 指令，要求模型优先在对应 plugin__<插件ID>__<工具名> 工具中选择。识别正则为 (?<=^|\s)@([A-Za-z0-9][A-Za-z0-9._-]*)，与 pluginId 字符集一致，邮件地址形态不会误判。
17.2.2 接口侧：PluginApiAuthFilter
| 场景 | 行为 |
|---|---|
| 只读请求 | GET / HEAD / OPTIONS 直接放行 |
| 本机调用 | 回环地址 127.0.0.1 / ::1 放行 |
| 远程命令调用 | 必须携带 X-Plugin-Api-Token，与 harness.plugins.api-token 配置一致 |
| 鉴权失败 | 401 + {"code":"A0300","info":"plugin API token required","data":null} |
设计取舍很明确：读接口开放便于控制台展示，安装/运行/启停/卸载等命令接口远程访问必须带 Token，避免主机暴露后插件被任意安装或停用。
17.2.3 注册侧：三重安全校验
| 加固点 | 机制 | 防什么 |
|---|---|---|
| pluginId 字符集 | [A-Za-z0-9][A-Za-z0-9._-]* 强制校验，非法 ID 安装期即拒绝 | 工具命名规则被破坏、安装目录路径穿越 |
| 工具注册幂等 | putIfAbsent 语义，重复注册释放新资源、返回已有工具名 | 插件重复 run 导致工具重复挂载、提示词重复写入 |
| 提示词清洗 | sanitizePromptText 清理换行与控制字符；提示词用注册后完整工具名 | 恶意描述通过换行注入系统提示词；模型按裸工具名调用失败 |
17.2.4 配套修正
| 修正 | 说明 |
|---|---|
| 目录识别修复 | AgentDispatchNode 命中目录关键词后先用 Files.isDirectory() 确认路径真实存在，避免把 SELECT/SHOW/DESC 等文本误当成目录路径改写用户消息 |
| 系统提示词修正 | 不再要求模型输出思考过程标签（原写法把 <think> 误写成 <thead>），明确只输出最终回答 |
| 安装脚本加固 | install-plugin.sh 对安装请求字段做 JSON 转义，支持含空格和特殊字符的路径与元数据 |
17.3 v0.1.5 验证与兼容
版本内新增三组定向测试，配合手工回归，保证加固不破坏既有行为：
| 测试 / 验证 | 覆盖点 |
|---|---|
buildsFsSearchInstructionForDirectoryQuestion | 目录改写仅对真实存在的目录生效（@TempDir 验证） |
appendsPluginMentionInstruction | @插件 提及正确转换为 [插件提及] 优先级指令 |
ignoresEmailLikeTextAsPluginMention | 邮件地址不会被误判为插件提及 |
| 手工回归 | 控制台 @ 补全交互、远程无 Token 返回 401、非法 pluginId 安装期拒绝、特殊字符路径正常安装 |
兼容性：插件 SDK 契约不变（插件仍只依赖 deepseek-harness-java-types），工具命名规则不变，既有合法 pluginId 全部满足新字符集要求，本机调用行为不变。升级注意：需要远程管理插件时必须先配置 harness.plugins.api-token 并在调用方携带请求头；历史数据中存在非法字符 pluginId 的，建议卸载后按新规则重装。
17.4 回看 v0.1.3 与 v0.1.4
17.4.1 v0.1.4：插件机制工程化
v0.1.4 把插件机制从「SPI 可注册」推进到「产物可识别、配置可持久化、运行状态可对账、业务能力可交付」：
| 亮点 | 说明 |
|---|---|
| 产物识别 | JAR 与 Maven 依赖两种产物自动解析为插件候选信息（POST /api/harness/plugins/analyze-jar），减少手工填写 |
| 配置持久化 | 插件键值配置从内存扩展到数据库，分层存储、重启恢复 |
| 状态可信 | 新增 plugin_status 工具，Agent 可查询登记与运行时状态，避免把 FAILED 插件说成可用 |
| 状态对账 | 启动时对比登记状态与运行时状态，自动修复偏差并拉起可恢复插件 |
| 开发体验 | DSH Java 插件开发 Skill + install-plugin.sh 一键安装脚本 |
| 业务插件 | mall-weekend-assistant 商城客服插件，打通商品、订单、物流工具链路 |
17.4.2 v0.1.3：扩展生态与统一配置
v0.1.3 的主线是把系统从「能力可运行」推进到「扩展可配置、运行可观测、体验更完整」：应用级与扩展配置收敛到 harness.yml（有效配置查询、启动校验、敏感信息脱敏）；MCP 支持 stdio、sse、streamable-http 三种接入；Skills 支持多目录发现与命名冲突仲裁；SSE 协议补齐推理、工具调用、工具结果与结束事件；会话列表支持分页、重命名、删除与恢复。
17.5 版本主线全景
v0.1.5 留下的已知限制，也正是下一版的候选清单：@插件 提及目前只是优先级引导（可升级为强制路由、锁定工具候选集）；API Token 为单值配置（可扩展为多 Token、按插件粒度授权与轮换）；插件命令接口缺操作审计日志；提示词清洗可沉淀为统一的 Sanitizer 覆盖插件提示词、事件文本等其他外部输入。
17.6 小结
本章要点：v0.1.3 铺扩展能力与统一配置，v0.1.4 把插件机制工程化（产物识别、配置持久化、状态对账、业务插件），v0.1.5 做安全加固（@提及、接口 Token、注册校验、提示词清洗）。三个版本的变更规模从 3698 行收敛到 303 行，是典型的「先铺能力、再工程化、后加固」节奏。
延伸阅读：完整的版本开发说明见仓库 docs/md/release-v0.1.3-development-notes.md、release-v0.1.4-development-notes.md 与 release-v0.1.5-development-notes.md；插件开发的完整工程指南见 docs/md/java-plugin-development.md。