软件中心 v1.2.0

这是继 v1.0.0 后的正式发布，包含 v1.1.0 阶段新增的可选 Halo MCP Server 集成，以及自动化操作的重试、并发编辑和操作前检查改进。现提供 43 个基础工具 + 2 个默认关闭的敏感工具，覆盖软件、版本、下载源、分类、标签和专题；未安装 MCP Server 时插件仍可独立运行。相对于 v1.1.0 阶段新增 9 个查询工具，已有工具名称和必填参数保持兼容。

三项改进

1. 创建请求持久化，重复调用不会重复创建

六类创建工具均接受可选 requestId（UUID）。同一资源类型下，相同 ID 和相同输入只尝试创建一次；换用不同输入会返回 IDEMPOTENCY_CONFLICT。

创建回执保存在 Halo 数据库中，跨插件重载及 Halo 进程重启保留。
同一请求并发到达时，只有取得写入资格的调用创建资源，其他调用返回原回执或 OPERATION_IN_PROGRESS。
资源已保存但回执未完成时，可以通过资源上的请求标记恢复回执。
资源后来被修改或删除，重放旧请求只返回原创建结果，不覆盖或重建。
新增 get_create_operation，查询 pending/writing/succeeded/failed/unknown 状态。

回执只保存输入摘要、目标名称和操作状态，不保存输入正文或敏感值。当前不自动清理回执；管理员清理记录或回退数据库会改变防重复保障。无法确认结果的请求保留 unknown，不自动重建。

2. 统计刷新不再必然阻止普通编辑

普通读取增加 editRevision。普通更新及发布时，除 expectedVersion 外传入 expectedEditRevision，即可在业务内容未变的情况下接受统计或元数据造成的版本变化。

实际落库仍发生版本冲突时，最多重新读取并重试两次。每次重试重新检查业务内容和引用，不覆盖其他人的业务修改。

只传 expectedVersion 时继续严格校验。敏感配置更新和删除仍使用严格版本，不能使用该宽容机制。敏感值不参与普通业务摘要；普通更新保留最新敏感配置。editRevision 表示当前内容，不是修改历史序号。

3. 发布前看准备情况，删除前看影响

新增 check_app_publication、check_topic_publication 及六类 check_*_deletion。

allowed 表示当前领域规则是否允许操作；ready 还要求没有准备度警告。
软件发布检查已发布版本、该版本启用的下载源、目标配置及必要 Secret 是否存在；不输出 Secret 名称或值。
专题发布检查条目中的软件是否可见。
删除检查返回引用数量、最多 20 个名称样本，以及引用是否阻止删除；同时提示保留的专题或关联软件引用。
每组下载源或专题条目最多深入检查 200 条，超限会明确提示检查不完整。

预检查是当前快照，不锁定资源，也不改变原有发布规则。它不验证远程文件能否下载或登录、验证码流程能否成功；实际执行仍重新校验。

升级与使用

在 Halo Console 上传 plugin-software-1.2.0.jar。
等待插件恢复 STARTED，客户端重新获取工具目录。
在 MCP 服务中为已有密钥勾选需要的新增查询工具；新增工具不会自动授权。
自动化创建始终携带稳定的 requestId，重试复用同一 ID 和输入；编辑读取最新详情并携带 expectedEditRevision。

新增参数均为可选。旧客户端继续可用，但不会自动获得创建去重或容忍统计变更的能力。重放创建返回的是原回执，后续编辑前需要重新读取资源。

从 v1.0.0 升级前，需先将 Halo 升级至 2.26.0 或更高版本（v1.0.0 的最低要求为 2.25.0）。源码构建使用 Java 21。当前编译使用 MCP API 1.3.0，保留 1.0.0 调用契约，可选插件依赖仍为 MCP Server >=1.0.0 & <2.0.0；不嵌入 MCP API/SDK。基础工具不依赖 AI Foundation；AI Foundation 编译 API 为 1.1.1，可选依赖范围保持 >=1.0.0-SNAPSHOT & <2.0.0。

新增内部 Extension operations.software.jiewen.run/v1alpha1/SoftwareCreateOperation 及两项引用索引，既有六类业务 GVK、Console API 和业务数据结构保持兼容。内部请求记录未向普通软件角色或匿名用户开放原始资源权限。

完整参数、工具目录和失败处理见 MCP 接入文档。1.1.0 设计背景见原实现方案。

构建与发布维护

更新 Gradle、Halo UI 和其他兼容依赖；Console 保持 IIFE 输出及现有 JS/CSS 加载方式。
对齐 Node.js 24、TypeScript 5.9 和 Halo 2.26 要求的 Vue Router 5.1，避免依赖升级破坏构建兼容性。
GitHub Release 发布后自动构建安装包并推送至 Halo 应用市场应用 app-todmqfve；本次不自动同步 README。
暂停三个生态的常规 Dependabot 版本更新 PR，改为按需手动维护；仓库安全更新设置保持原样。

验证记录

验证日期：2026-10-16。使用独立 Halo 2.26.0 容器、文件型 H2 数据库、官方 MCP Server 1.0.0，通过 /mcp Streamable HTTP 联调。

检查	结果
完整 Gradle 构建	通过，生成 1.2.0 安装包
Java 单元与契约测试	193 项通过，无失败或跳过（含提交前审查新增的 4 项）
前端测试	14 个文件、55 项通过
前端类型检查与 lint	通过
真实 MCP 联调	全部 45 个工具调用成功，61 项检查通过
JAR 内容	含 Console JS/CSS、新服务及内部模型；无 MCP API/SDK 类

真实联调覆盖六类创建/查询/编辑/删除、同一请求重放和不同输入拒绝、四个并发请求只创建一条资源、保存资源后恢复回执、插件重载和整站进程重启后的去重、删除资源后不再重建、不确定结果不重建、业务版本与统计版本冲突、发布准备及引用影响、敏感配置脱敏、密钥白名单、匿名访问拒绝，以及 MCP 停用和恢复。

单元测试另覆盖回执存储失败、取消与超时恢复、业务并发竞争、有限重试、敏感字段不进入摘要、检查数量上限及全部工具输出 Schema。联调修复了 Halo 将存储重名异常转换为 HTTP 400 异常的兼容问题：重试先读取并核验已存在请求，不依赖异常消息文字。

提交前对抗审查修复了两项边界问题：引用校验不再接受已标记删除但尚未清理的软件、分类或 Secret 等资源；专题发布预检查遇到旧数据中的空条目时返回隐藏条目警告，避免 Reactor 拒绝空元素而中断检查。4 项回归用例先复现失败，修复后通过；上述真实 MCP 联调记录来自修补前，本轮修补通过完整本地构建和回归验证，未重复执行整套真实 MCP 联调。

依赖更新后，Gradle 9.8.1 完整构建、193 项 Java 测试、55 项前端测试、lint 和类型检查再次通过。保持新 API 编译结果不变，仅将测试运行时替换为 AI Foundation API 1.0.1 / MCP API 1.0.0 后，193 项 Java 测试再次通过；安装包保留 Console JS/CSS，不包含可选插件 API 或 MCP SDK。此阶段未重复执行真实 Halo 安装、升级、编辑器 UI 和 MCP 联调。

本次未进行 PostgreSQL/MySQL 联调、生产数据压力测试、全部 MCP 1.x 版本测试或特定 AI 客户端的界面验收。跨资源工作流、批量导入和 AI 异步作业仍不在本版本范围内。

正式版本号为 1.2.0，Git 标签为 v1.2.0，安装包为 plugin-software-1.2.0.jar。发布安装包不会自动升级已安装插件的站点；站点升级需在 Halo Console 中执行。

Generated from v1.2.0

软件中心 v1.0.0

这是 Software Manager for Halo 的首个稳定版本，为 Halo 提供独立、主题中立的软件内容管理、公开查询和安全下载能力。主题可以通过 Finder、Theme Router 或版本化 REST API 接入，插件本身不依赖任何特定主题。

版本亮点

完整的软件领域模型：支持软件、版本、下载源、分类、标签和专题的创建与管理，并覆盖发布状态、排序、统计、SEO 及关联内容。
Console 管理界面：提供软件编辑器，以及分类、标签、专题、版本和下载源管理；下载源支持类型、优先级、健康状态和门禁配置。
主题中立的公开集成：提供 softwareFinder、公共主题路由和 v1alpha1 REST API，公开 VO 与 Console/原始 Extension 分离，方便不同主题或客户端消费。
安全下载授权：下载详情不直接暴露最终 URL、storageKey、提取码或密码等敏感字段；通过短期 download-grants 授权获取下载信息，并支持 Cloudflare Turnstile 验证。
权限与安全边界：新增软件查看、软件管理和敏感下载配置等角色模板；下载目标执行 HTTP(S)/站内路径校验，验证码异常、Secret 缺失或目标不安全时按 fail-closed 处理，敏感响应使用 no-store。
评论与可选 AI：将 SoftwareApp 注册为 Halo 评论资源；可选接入 AI Foundation，为软件摘要、详情和 SEO 提供 Console 编辑建议，不影响核心软件管理功能。
开发者契约与工程化：提供主题 API、REST API 和 OpenAPI 文档，并配套 Java、Vue、公共 VO、Router、RBAC、下载安全和 AI 能力契约测试。

兼容性

Halo >= 2.25.0
Java 21（仅从源码构建插件时需要）
AI Foundation >= 1.0.0-SNAPSHOT 且 < 2.0.0（可选，仅用于 AI 编辑辅助）

安装

从 GitHub Releases 下载 software 插件 JAR。
在 Halo Console 的“插件”页面上传并启用。
在“软件”菜单中配置选项、分类、标签、专题、软件、版本和下载源。
如使用验证码下载，在 Halo 中创建保存 Turnstile Secret Key 的 Secret，再完成插件“下载安全”设置。
使用主题或其他客户端时，仅调用公开 Finder/Router/REST API，不要读取原始 Extension 或 Console API 中的敏感字段。

升级注意

主题接入应使用 GET /download-options 和 POST /download-grants 获取下载授权，不应继续依赖详情接口中的最终下载 URL。
公开详情中的下载源 URL 为空是预期行为；提取码、密码和存储键只在完成授权后返回，并且只应保存在当前下载流程的内存中。
v1alpha1 公共契约、getHome()/SoftwareHomeVo 和主题 Router 均属于跨项目接口，升级主题或自定义客户端时请同步查看主题 API 文档与 REST API 文档。
AI Foundation 缺失、禁用或未配置模型时，软件管理、公开 API、Finder 和主题路由仍应正常工作。

已知边界

插件只负责软件数据、查询、授权和权限；网格/列表布局、颜色、动画等展示逻辑由主题负责。
应用市场发布当前未启用，本版本通过 GitHub Release 分发。

许可证

GPL-3.0

菜单

软件中心