From ade5e91ac1b96ab9199cdaa489f86f2609fc493f Mon Sep 17 00:00:00 2001 From: zhengwr Date: Wed, 17 Jun 2026 08:30:20 +0800 Subject: [PATCH] feat: add feature package export preview --- README.md | 2 + docs/AI_AGENT_Nocobase_ADOPTION_PLAN.md | 3 +- docs/AI_AGENT_Nocobase_SOURCE_REVIEW.md | 10 ++ docs/skills/eip4-release-manage.md | 18 +- .../java/com/eip4/platform/cli/Eip4Cli.java | 170 ++++++++++++++++-- .../com/eip4/platform/cli/Eip4CliTest.java | 71 ++++++++ 6 files changed, 251 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index e1345a3..76788d1 100644 --- a/README.md +++ b/README.md @@ -83,6 +83,8 @@ java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar env add --name loc java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar env status --base-url http://localhost:8084 java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai feature-package --task-id ait-xxx --change-set-id aics-xxx --output target/ai-runs/package.json java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release verify --package-file target/ai-runs/package.json +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release export --package-file target/ai-runs/package.json --output target/ai-runs/package.eip4pkg.json +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release import-preview --package-file target/ai-runs/package.eip4pkg.json ``` ## tools/ diff --git a/docs/AI_AGENT_Nocobase_ADOPTION_PLAN.md b/docs/AI_AGENT_Nocobase_ADOPTION_PLAN.md index 4718ba6..2f2ef4f 100644 --- a/docs/AI_AGENT_Nocobase_ADOPTION_PLAN.md +++ b/docs/AI_AGENT_Nocobase_ADOPTION_PLAN.md @@ -137,6 +137,7 @@ EIP4 当前已经有实体、页面 schema、服务流、菜单、smoke、部署 - 参考 NocoBase `env/status.ts` 和 `env-guard.ts`,`platform-cli` 新增本地 env registry/current env。 - 参考 NocoBase revision 创建前检查版本控制插件的思路,EIP4 后续 revision restore/diff 不能只依赖 JSON 快照,必须有发布系统能力检查。 - 新增 `eip4 release verify --package-file FILE`,先做离线发布前门禁,阻断未替换占位符和缺失本地 evidence 的功能包。 +- 新增 `eip4 release export/import-preview`,形成 `.eip4pkg.json` 文件格式和 checksum 门禁;导入预览不写环境、不启用功能。 - 详细源码对照见 `docs/AI_AGENT_Nocobase_SOURCE_REVIEW.md`。 ### P4:Typed Page Schema 和组件注册表 @@ -190,6 +191,6 @@ EIP4 应该借鉴的是边界和流程: | P0 | 完成 | `platform-ai` 主链路已提交 | | P1 | 第一版完成 | 已新增 `platform-cli` 和 Skills 规范骨架 | | P2 | 第一版完成 | 已新增功能包快照、里程碑 revision、CLI 命令和持久化表 | -| P3 | 进行中 | 已开始 env registry/current env/cross-env guard/release verify | +| P3 | 进行中 | 已完成 env registry/current env/cross-env guard/release verify/export/import-preview 第一版 | | P4 | 待开始 | 依赖页面 schema 现状清理 | | P5 | 待开始 | 依赖权限、审计、工具白名单成熟 | diff --git a/docs/AI_AGENT_Nocobase_SOURCE_REVIEW.md b/docs/AI_AGENT_Nocobase_SOURCE_REVIEW.md index bd3cf5c..f804c95 100644 --- a/docs/AI_AGENT_Nocobase_SOURCE_REVIEW.md +++ b/docs/AI_AGENT_Nocobase_SOURCE_REVIEW.md @@ -44,6 +44,8 @@ - AI 命令支持 `--env`。 - 显式选择非当前 env 时必须加 `--yes`,避免误操作共享环境。 - 新增 `eip4 release verify --package-file FILE`,离线检查功能包是否具备本地门禁 evidence、人审标记、SQL/rollback,并阻断 `${...}` 占位符。 +- 新增 `eip4 release export --package-file FILE --output FILE`,将功能包封装为 `.eip4pkg.json`,包含格式版本和 SHA-256 checksum。 +- 新增 `eip4 release import-preview --package-file FILE`,离线验证 `.eip4pkg.json` checksum 和发布门禁,不写任何环境。 ## 三、后续实现顺序 @@ -60,6 +62,8 @@ ### P3-2:FeaturePackage 导出/导入 +状态:第一版完成。 + 目标: - `.eip4pkg.json` 文件格式 @@ -67,6 +71,12 @@ - import preview - import 后不自动启用 +第一版已落地: + +- export: 普通 feature package JSON -> `.eip4pkg.json` 信封。 +- import-preview: 校验 format/version/checksum/payload 和 release gate。 +- import-preview 只读,不落库、不启用、不发布。 + ### P3-3:Revision diff/restore 目标: diff --git a/docs/skills/eip4-release-manage.md b/docs/skills/eip4-release-manage.md index c15a9a1..691190e 100644 --- a/docs/skills/eip4-release-manage.md +++ b/docs/skills/eip4-release-manage.md @@ -41,15 +41,26 @@ java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release verify \ --package-file target/ai-runs/feature-package.json ``` -5. 确认部署包包含: +5. 导出 `.eip4pkg.json` 并做导入预览: + +```bash +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release export \ + --package-file target/ai-runs/feature-package.json \ + --output target/ai-runs/feature-package.eip4pkg.json + +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release import-preview \ + --package-file target/ai-runs/feature-package.eip4pkg.json +``` + +6. 确认部署包包含: - manifest - SQL 草案 - rollback SQL - 本地 apply evidence - smoke evidence - repair evidence -6. 确认部署包需要人工审批。 -7. 如果包含 `${parentMenuId}` 等占位符,必须人工替换并复核;`release verify` 默认会阻断这类包。 +7. 确认部署包需要人工审批。 +8. 如果包含 `${parentMenuId}` 等占位符,必须人工替换并复核;`release verify` 默认会阻断这类包。 ## 线上 bug 修复路径 @@ -65,3 +76,4 @@ java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release verify \ - 不绕过部署包和人审。 - 不把 smoke 失败的变更包交给发布流程。 - 不发布 `release verify` 失败的功能包。 +- 不把 `import-preview` 当成导入或启用;它只是离线检查。 diff --git a/platform-cli/src/main/java/com/eip4/platform/cli/Eip4Cli.java b/platform-cli/src/main/java/com/eip4/platform/cli/Eip4Cli.java index 8664e0b..5d6ca42 100644 --- a/platform-cli/src/main/java/com/eip4/platform/cli/Eip4Cli.java +++ b/platform-cli/src/main/java/com/eip4/platform/cli/Eip4Cli.java @@ -6,7 +6,10 @@ import java.net.URI; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; +import java.security.MessageDigest; +import java.security.NoSuchAlgorithmException; import java.util.ArrayList; +import java.util.HexFormat; import java.util.LinkedHashMap; import java.util.List; import java.util.Locale; @@ -20,6 +23,9 @@ import com.fasterxml.jackson.databind.node.ObjectNode; public final class Eip4Cli { private static final String DEFAULT_BASE_URL = "http://localhost:8084"; + private static final String PACKAGE_FORMAT = "EIP4_FEATURE_PACKAGE"; + private static final int PACKAGE_FORMAT_VERSION = 1; + private static final String PACKAGE_CHECKSUM_ALGORITHM = "SHA-256"; private final ObjectMapper objectMapper; private final Eip4HttpClient httpClient; @@ -88,19 +94,118 @@ public final class Eip4Cli { return 0; } return switch (args[1]) { + case "export" -> runReleaseExport(args, out); + case "import-preview" -> runReleaseImportPreview(args, out, err); case "verify" -> runReleaseVerify(args, out, err); default -> fail(err, "Unknown release command: " + args[1]); }; } + private int runReleaseExport(String[] args, PrintStream out) throws IOException { + Options options = Options.parse(args, 2); + Path packageFile = Path.of(requiredPart(options.single("package-file"), "package-file")); + Path output = Path.of(requiredPart(options.single("output"), "output")); + JsonNode raw = objectMapper.readTree(Files.readString(packageFile, StandardCharsets.UTF_8)); + JsonNode payload = packagePayload(raw); + ObjectNode envelope = objectMapper.createObjectNode(); + envelope.put("format", PACKAGE_FORMAT); + envelope.put("formatVersion", PACKAGE_FORMAT_VERSION); + envelope.put("exportedAt", System.currentTimeMillis()); + envelope.put("checksumAlgorithm", PACKAGE_CHECKSUM_ALGORITHM); + envelope.set("payload", payload); + envelope.put("checksum", checksum(payload)); + if (output.getParent() != null) { + Files.createDirectories(output.getParent()); + } + Files.writeString(output, + objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(envelope) + System.lineSeparator(), + StandardCharsets.UTF_8); + out.println("Exported feature package: " + output.toAbsolutePath()); + out.println("packageId: " + packageId(payload, deploymentPackage(payload))); + out.println("checksum: " + envelope.path("checksum").asText()); + return 0; + } + + private int runReleaseImportPreview(String[] args, PrintStream out, PrintStream err) throws IOException { + Options options = Options.parse(args, 2); + Path packageFile = Path.of(requiredPart(options.single("package-file"), "package-file")); + JsonNode raw = objectMapper.readTree(Files.readString(packageFile, StandardCharsets.UTF_8)); + ReleaseValidation validation = validateReleasePackage(raw, true); + return printReleaseValidation(validation, options, out, err, "Import preview"); + } + private int runReleaseVerify(String[] args, PrintStream out, PrintStream err) throws IOException { Options options = Options.parse(args, 2); Path packageFile = Path.of(requiredPart(options.single("package-file"), "package-file")); JsonNode root = objectMapper.readTree(Files.readString(packageFile, StandardCharsets.UTF_8)); - JsonNode deploymentPackage = root.has("deploymentPackage") ? root.path("deploymentPackage") : root; + ReleaseValidation validation = validateReleasePackage(root, false); + return printReleaseValidation(validation, options, out, err, "Release package"); + } + + private ReleaseValidation validateReleasePackage(JsonNode root, boolean requireEnvelope) throws IOException { List blockers = new ArrayList<>(); List warnings = new ArrayList<>(); + validateEnvelope(root, blockers, requireEnvelope); + JsonNode payload = packagePayload(root); + JsonNode deploymentPackage = deploymentPackage(payload); + if (payload.isMissingNode() || payload.isNull() || !payload.isObject()) { + blockers.add("payload 必须是功能包 JSON object"); + } + validateDeploymentPackage(deploymentPackage, blockers, warnings); + + ObjectNode report = objectMapper.createObjectNode(); + report.put("status", blockers.isEmpty() ? "PASSED" : "FAILED"); + report.put("format", root.path("format").asText("")); + report.put("formatVersion", root.path("formatVersion").asInt(0)); + report.put("checksum", root.path("checksum").asText("")); + report.put("packageId", packageId(payload, deploymentPackage)); + report.put("taskId", text(deploymentPackage, "taskId")); + report.put("changeSetId", text(deploymentPackage, "changeSetId")); + ArrayNode blockerNodes = report.putArray("blockers"); + blockers.forEach(blockerNodes::add); + ArrayNode warningNodes = report.putArray("warnings"); + warnings.forEach(warningNodes::add); + return new ReleaseValidation(report, List.copyOf(blockers), List.copyOf(warnings)); + } + + private void validateEnvelope(JsonNode root, List blockers, boolean requireEnvelope) throws IOException { + if (!root.has("format")) { + if (requireEnvelope) { + blockers.add("导入预览要求 .eip4pkg.json 信封,缺少 format"); + } + return; + } + if (!PACKAGE_FORMAT.equals(root.path("format").asText())) { + blockers.add("format 必须是 " + PACKAGE_FORMAT); + } + if (root.path("formatVersion").asInt(0) != PACKAGE_FORMAT_VERSION) { + blockers.add("formatVersion 必须是 " + PACKAGE_FORMAT_VERSION); + } + if (!PACKAGE_CHECKSUM_ALGORITHM.equals(root.path("checksumAlgorithm").asText())) { + blockers.add("checksumAlgorithm 必须是 " + PACKAGE_CHECKSUM_ALGORITHM); + } + JsonNode payload = root.path("payload"); + if (!payload.isObject()) { + blockers.add("payload 必须是 JSON object"); + return; + } + String expected = root.path("checksum").asText(""); + if (expected.isBlank()) { + blockers.add("checksum 不能为空"); + return; + } + String actual = checksum(payload); + if (!expected.equals(actual)) { + blockers.add("checksum 不匹配,expected=" + expected + ", actual=" + actual); + } + } + + private void validateDeploymentPackage(JsonNode deploymentPackage, List blockers, + List warnings) { + if (!deploymentPackage.isObject()) { + blockers.add("deploymentPackage 必须是 JSON object"); + } if (!"READY_FOR_HUMAN_REVIEW".equals(text(deploymentPackage, "status"))) { blockers.add("deploymentPackage.status 必须是 READY_FOR_HUMAN_REVIEW"); } @@ -123,31 +228,41 @@ public final class Eip4Cli { blockers.add("sqlStatements 仍包含 ${...} 占位符,必须人工替换后再发布"); } deploymentPackage.path("warnings").forEach(warning -> warnings.add(warning.asText())); + } - ObjectNode report = objectMapper.createObjectNode(); - report.put("status", blockers.isEmpty() ? "PASSED" : "FAILED"); - report.put("packageId", packageId(root, deploymentPackage)); - report.put("taskId", text(deploymentPackage, "taskId")); - report.put("changeSetId", text(deploymentPackage, "changeSetId")); - ArrayNode blockerNodes = report.putArray("blockers"); - blockers.forEach(blockerNodes::add); - ArrayNode warningNodes = report.putArray("warnings"); - warnings.forEach(warningNodes::add); + private JsonNode packagePayload(JsonNode root) { + if (root != null && PACKAGE_FORMAT.equals(root.path("format").asText()) && root.has("payload")) { + return root.path("payload"); + } + return root; + } + private JsonNode deploymentPackage(JsonNode payload) { + if (payload != null && payload.has("deploymentPackage")) { + return payload.path("deploymentPackage"); + } + return payload; + } + + private int printReleaseValidation(ReleaseValidation validation, Options options, PrintStream out, + PrintStream err, String label) throws IOException { if (options.has("json-output")) { - out.println(objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(report)); - } else if (blockers.isEmpty()) { - out.println("Release package PASSED"); - out.println("packageId: " + packageId(root, deploymentPackage)); - if (!warnings.isEmpty()) { + out.println(objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(validation.report())); + } else if (validation.blockers().isEmpty()) { + out.println(label + " PASSED"); + out.println("packageId: " + validation.report().path("packageId").asText()); + if (!validation.report().path("checksum").asText("").isBlank()) { + out.println("checksum: " + validation.report().path("checksum").asText()); + } + if (!validation.warnings().isEmpty()) { out.println("warnings:"); - warnings.forEach(warning -> out.println("- " + warning)); + validation.warnings().forEach(warning -> out.println("- " + warning)); } } else { - err.println("Release package FAILED"); - blockers.forEach(blocker -> err.println("- " + blocker)); + err.println(label + " FAILED"); + validation.blockers().forEach(blocker -> err.println("- " + blocker)); } - return blockers.isEmpty() ? 0 : 2; + return validation.blockers().isEmpty() ? 0 : 2; } private int runEnvAdd(String[] args, PrintStream out) throws IOException { @@ -504,6 +619,16 @@ public final class Eip4Cli { return manifestId == null ? "" : manifestId; } + private String checksum(JsonNode payload) throws IOException { + try { + MessageDigest digest = MessageDigest.getInstance(PACKAGE_CHECKSUM_ALGORITHM); + byte[] hash = digest.digest(objectMapper.writeValueAsBytes(payload)); + return "sha256:" + HexFormat.of().formatHex(hash); + } catch (NoSuchAlgorithmException ex) { + throw new IllegalStateException("Missing checksum algorithm: " + PACKAGE_CHECKSUM_ALGORITHM, ex); + } + } + private int parseInt(String value, String name) { try { return Integer.parseInt(value); @@ -540,6 +665,8 @@ public final class Eip4Cli { eip4 env current eip4 env status [--env NAME|--base-url URL|--all] eip4 ai auto-develop --objective TEXT --feature-name NAME --table-name TABLE --entity-name NAME --template-id ID --menu-name NAME --field column:label:type[:length][:required] + eip4 release export --package-file FILE --output FILE + eip4 release import-preview --package-file FILE eip4 release verify --package-file FILE Environment: @@ -551,6 +678,8 @@ public final class Eip4Cli { private void printReleaseHelp(PrintStream out) { out.println(""" Usage: + eip4 release export --package-file FILE --output FILE + eip4 release import-preview --package-file FILE [--json-output] eip4 release verify --package-file FILE [--json-output] """); } @@ -603,6 +732,9 @@ public final class Eip4Cli { private record CliTarget(String envName, String baseUrl) { } + private record ReleaseValidation(ObjectNode report, List blockers, List warnings) { + } + private static final class Options { private final Map> values = new LinkedHashMap<>(); private static final List BOOLEAN_OPTIONS = List.of( diff --git a/platform-cli/src/test/java/com/eip4/platform/cli/Eip4CliTest.java b/platform-cli/src/test/java/com/eip4/platform/cli/Eip4CliTest.java index 920aee6..7d5482d 100644 --- a/platform-cli/src/test/java/com/eip4/platform/cli/Eip4CliTest.java +++ b/platform-cli/src/test/java/com/eip4/platform/cli/Eip4CliTest.java @@ -268,6 +268,77 @@ class Eip4CliTest { assertTrue(result.err().contains("占位符")); } + @Test + void releaseExportWritesChecksumEnvelopeAndImportPreviewPasses() throws Exception { + Path source = validPackageFile("package-source.json"); + Path exported = tempDir.resolve("customer-level.eip4pkg.json"); + + CliResult export = run(new CapturingClient(new Eip4HttpResponse(200, "{}")), + "release", "export", + "--package-file", source.toString(), + "--output", exported.toString()); + + assertEquals(0, export.code()); + JsonNode envelope = objectMapper.readTree(Files.readString(exported)); + assertEquals("EIP4_FEATURE_PACKAGE", envelope.path("format").asText()); + assertEquals(1, envelope.path("formatVersion").asInt()); + assertEquals("SHA-256", envelope.path("checksumAlgorithm").asText()); + assertTrue(envelope.path("checksum").asText().startsWith("sha256:")); + assertEquals("aipkg-1", envelope.path("payload").path("id").asText()); + + CliResult preview = run(new CapturingClient(new Eip4HttpResponse(200, "{}")), + "release", "import-preview", + "--package-file", exported.toString()); + + assertEquals(0, preview.code()); + assertTrue(preview.out().contains("Import preview PASSED")); + assertTrue(preview.out().contains("checksum: sha256:")); + } + + @Test + void releaseImportPreviewRejectsTamperedChecksum() throws Exception { + Path source = validPackageFile("package-source.json"); + Path exported = tempDir.resolve("customer-level.eip4pkg.json"); + run(new CapturingClient(new Eip4HttpResponse(200, "{}")), + "release", "export", + "--package-file", source.toString(), + "--output", exported.toString()); + String tampered = Files.readString(exported, StandardCharsets.UTF_8) + .replace("READY_FOR_HUMAN_REVIEW", "BLOCKED_PENDING_LOCAL_PASS"); + Files.writeString(exported, tampered, StandardCharsets.UTF_8); + + CliResult preview = run(new CapturingClient(new Eip4HttpResponse(200, "{}")), + "release", "import-preview", + "--package-file", exported.toString()); + + assertEquals(2, preview.code()); + assertTrue(preview.err().contains("Import preview FAILED")); + assertTrue(preview.err().contains("checksum 不匹配")); + } + + private Path validPackageFile(String name) throws Exception { + Path file = tempDir.resolve(name); + Files.writeString(file, """ + { + "id": "aipkg-1", + "deploymentPackage": { + "taskId": "ait-1", + "changeSetId": "aics-1", + "status": "READY_FOR_HUMAN_REVIEW", + "requiresHumanApproval": true, + "sqlStatements": ["insert into sys_page_schema values ('x')"], + "rollbackSqlStatements": ["delete from sys_page_schema where id = 'x'"], + "warnings": [], + "runEvidence": [ + {"runType": "LOCAL_APPLY", "status": "PASSED"}, + {"runType": "SMOKE", "status": "PASSED"} + ] + } + } + """, StandardCharsets.UTF_8); + return file; + } + private CliResult run(CapturingClient client, String... args) { return run(tempStore(), client, args); }