@amaster.ai/cli 1.1.30 → 1.1.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -54,6 +54,26 @@ amaster addon upgrade crm-pages
54
54
  amaster addon list
55
55
  ```
56
56
 
57
+ Addon 可把市场展示主图和截图放在源码包内,例如:
58
+
59
+ ```text
60
+ marketplace/cover.png
61
+ marketplace/screenshots/preview.png
62
+ ```
63
+
64
+ 并在 `addon.json` 中声明:
65
+
66
+ ```json
67
+ {
68
+ "display": {
69
+ "image": "marketplace/cover.png",
70
+ "screenshots": ["marketplace/screenshots/preview.png"]
71
+ }
72
+ }
73
+ ```
74
+
75
+ 这些文件只用于发布到 Addon Marketplace,不会被 `addon install` 安装到应用工程。
76
+
57
77
  `addon search` 在未显式传 `--application-type` 时,会从当前目录向上查找最近的 `package.json`,读取同级 `app.settings.yml` 的 `type`,并自动按 `web` 或 `mini` 过滤。
58
78
 
59
79
  常用参数:
@@ -119,10 +139,17 @@ Addon 可在 `addon.json` 中声明安装后的运行配置要求:
119
139
 
120
140
  `install.requirements` 会写入 `meta.json`,并在安装/升级结果中返回 `requirements` 和 `missingRequirements`。`secrets` 只保存键名和说明,不保存密钥值。
121
141
 
122
- 页面注册方式:
142
+ 页面接入方式:
143
+
144
+ - CLI 只复制页面文件并写入 `src/addons/{addonName}/meta.json`
145
+ - CLI 不自动修改 `src/routes.tsx` 或 `src/app.config.ts`
146
+ - 安装/升级结果会返回 `llmGuidance`,由大模型按当前应用结构接入 web routes、mini pages 和 tabBar
147
+
148
+ 显式接入指导:
123
149
 
124
- - `web`:生成 `src/amaster/registry/addon-routes.generated.ts`,并 patch `src/routes.tsx`
125
- - `mini`:生成 `src/amaster/registry/addon-pages.generated.ts`,并 patch `src/app.config.ts`
150
+ - Addon 包根目录可以放 `SKILL.md`
151
+ - `SKILL.md` 不会安装到应用工程,只会在安装/升级结果的 `llmGuidance.skill` 中返回给大模型
152
+ - 如果 Addon 本身就是一个 skill 资源,应在 `addon.json.members` 中显式声明 `type: "skill"`;普通 Addon 的根 `SKILL.md` 只作为模型指导
126
153
 
127
154
  升级策略:
128
155
 
@@ -158,7 +185,7 @@ Addon 可在 `addon.json` 中声明安装后的运行配置要求:
158
185
  }
159
186
  ```
160
187
 
161
- MCP 接入时可按 `conflicts[].path` 读取应用里的当前文件,并按 `memberName` / `sourcePath` 获取 Addon 原始内容,再交给 AI 合并后重试安装或升级。
188
+ MCP 接入时可按 `conflicts[].path` 读取应用里的当前文件,并按 `memberName` / `sourcePath` 获取 Addon 原始内容,再交给 AI 或人工合并处理。
162
189
 
163
190
  ## 模板检查
164
191
 
package/dist/cli.cjs CHANGED
@@ -564,6 +564,7 @@ async function loadAddonManifestFromDirectory(directory) {
564
564
  const manifestText = await promises$1.readFile(manifestPath, "utf8");
565
565
  const manifest = JSON.parse(manifestText);
566
566
  validateAddonManifest(manifest);
567
+ await assertDisplayAssetPathsExist(directory, manifest);
567
568
  return manifest;
568
569
  }
569
570
  function validateAddonManifest(manifest) {
@@ -582,9 +583,40 @@ function validateAddonManifest(manifest) {
582
583
  if (!Array.isArray(manifest.members)) {
583
584
  throw new Error("addon.json missing members");
584
585
  }
586
+ validateDisplayAssets(manifest);
585
587
  validateInstallRequirements(manifest);
586
588
  validateInstallNpm(manifest);
587
589
  }
590
+ function validateDisplayAssets(manifest) {
591
+ const image = manifest.display.image;
592
+ if (image !== void 0) {
593
+ if (typeof image !== "string") {
594
+ throw new Error("addon.json display.image must be a string");
595
+ }
596
+ normalizeRelativePath(image, "display.image");
597
+ }
598
+ const screenshots = manifest.display.screenshots;
599
+ if (screenshots !== void 0) {
600
+ if (!Array.isArray(screenshots)) {
601
+ throw new Error("addon.json display.screenshots must be an array");
602
+ }
603
+ screenshots.forEach((item, index) => {
604
+ if (typeof item !== "string") {
605
+ throw new Error(`addon.json display.screenshots[${index}] must be a string`);
606
+ }
607
+ normalizeRelativePath(item, `display.screenshots[${index}]`);
608
+ });
609
+ }
610
+ }
611
+ async function assertDisplayAssetPathsExist(directory, manifest) {
612
+ const paths = [
613
+ ...manifest.display.image ? [manifest.display.image] : [],
614
+ ...manifest.display.screenshots ?? []
615
+ ];
616
+ for (const assetPath of paths) {
617
+ await assertPathExists(directory, normalizeRelativePath(assetPath, "display asset path"));
618
+ }
619
+ }
588
620
  function validateInstallRequirements(manifest) {
589
621
  const requirements = manifest.install?.requirements;
590
622
  if (!requirements) {
@@ -651,21 +683,21 @@ function validateInstallNpm(manifest) {
651
683
  function resolveMemberSourcePath(member) {
652
684
  const sourcePath = member.source?.path;
653
685
  if (typeof sourcePath === "string" && sourcePath.trim()) {
654
- return normalizeRelativePath(sourcePath);
686
+ return normalizeRelativePath(sourcePath, "member source path");
655
687
  }
656
688
  const fallbackKeys = ["entry", "path", "contentPath"];
657
689
  for (const key of fallbackKeys) {
658
690
  const value = member[key];
659
691
  if (typeof value === "string" && value.trim()) {
660
- return normalizeRelativePath(value);
692
+ return normalizeRelativePath(value, "member source path");
661
693
  }
662
694
  }
663
695
  return null;
664
696
  }
665
- function normalizeRelativePath(value) {
697
+ function normalizeRelativePath(value, fieldName = "path") {
666
698
  const normalized = value.replace(/^\.?\//, "").replace(/\\/g, "/");
667
699
  if (!normalized || normalized.startsWith("../") || normalized.includes("/../")) {
668
- throw new Error(`Invalid member source path: ${value}`);
700
+ throw new Error(`Invalid addon.json ${fieldName}: ${value}`);
669
701
  }
670
702
  return normalized;
671
703
  }
@@ -781,13 +813,6 @@ function ensurePathInsideTarget(targetDir, relativePath) {
781
813
  }
782
814
  return absolute;
783
815
  }
784
- function removeFileExtension(input) {
785
- const extension = path.extname(input);
786
- return extension ? input.slice(0, -extension.length) : input;
787
- }
788
- function toPascalCase(input) {
789
- return input.split(/[^a-zA-Z0-9]+/).filter(Boolean).map((part) => part[0].toUpperCase() + part.slice(1)).join("");
790
- }
791
816
  function parseScalarValue(rawValue, expectedType, enumValues) {
792
817
  const primaryType = Array.isArray(expectedType) ? expectedType[0] : expectedType;
793
818
  if (enumValues?.length) {
@@ -879,6 +904,83 @@ function buildMissingRequirements(requirements) {
879
904
  secrets: requirements.secrets?.filter((item) => item.required !== false).map((item) => ({ ...item }))
880
905
  };
881
906
  }
907
+ function hasInstallRequirements(requirements) {
908
+ return Boolean(requirements.envs?.length || requirements.secrets?.length);
909
+ }
910
+ function hasNpmDependencies(npm) {
911
+ return Boolean(Object.keys(npm.dependencies ?? {}).length);
912
+ }
913
+ function buildAddonLlmGuidance(input) {
914
+ const pageMembers = input.meta.members.filter((member) => member.type === "page");
915
+ const componentMembers = input.meta.members.filter((member) => member.type === "component");
916
+ const settingsMembers = input.meta.members.filter((member) => member.type === "settings");
917
+ const webRoutes = input.meta.members.filter((member) => member.type === "page" && member.page?.web).map((member) => ({
918
+ route: member.page.web.route,
919
+ entry: member.page.web.entry.startsWith("src/") ? member.page.web.entry : `src/${member.page.web.entry}`,
920
+ title: member.page.web.title,
921
+ visible: member.page.web.visible,
922
+ suggestedFile: "src/routes.tsx"
923
+ }));
924
+ const miniPages = input.meta.members.filter((member) => member.type === "page" && member.page?.mini).map((member) => ({
925
+ pagePath: member.page.mini.pagePath,
926
+ suggestedFile: "src/app.config.ts",
927
+ tabBar: member.page.mini.tabBar
928
+ }));
929
+ const components = componentMembers.map((member) => ({
930
+ name: member.name,
931
+ importFrom: member.targetPaths[0] || "",
932
+ targetPaths: member.targetPaths
933
+ }));
934
+ const settings = settingsMembers.map((member) => ({
935
+ targetPath: member.settings?.targetPath || member.targetPaths[0] || "",
936
+ paths: member.settings?.paths.map((item) => item.path) || []
937
+ }));
938
+ const instructions = [
939
+ `Addon ${input.meta.name}@${input.meta.version} has been ${input.operation === "install" ? "installed" : "upgraded"} into the application files.`,
940
+ "Do not run the install command again to apply integration steps; edit the application source files directly."
941
+ ];
942
+ if (pageMembers.length > 0) {
943
+ instructions.push("Wire the installed page members into the application's existing routing/configuration style.");
944
+ }
945
+ if (componentMembers.length > 0) {
946
+ instructions.push("Use installed component members from their target paths where the application needs them.");
947
+ }
948
+ if (hasInstallRequirements(input.requirements)) {
949
+ instructions.push("Configure the declared env/secret requirements before running or deploying the application.");
950
+ }
951
+ if (hasNpmDependencies(input.npm)) {
952
+ instructions.push("NPM dependencies have been written to package.json; avoid adding duplicate dependency entries.");
953
+ }
954
+ return {
955
+ summary: input.meta.manifest.description || input.meta.manifest.title || `Installed addon ${input.meta.name}@${input.meta.version}.`,
956
+ instructions,
957
+ skill: input.skillContent ? { path: "SKILL.md", content: input.skillContent } : void 0,
958
+ webRoutes: webRoutes.length ? webRoutes : void 0,
959
+ miniPages: miniPages.length ? miniPages : void 0,
960
+ components: components.length ? components : void 0,
961
+ settings: settings.length ? settings : void 0,
962
+ requirements: hasInstallRequirements(input.requirements) ? input.requirements : void 0,
963
+ npm: hasNpmDependencies(input.npm) ? input.npm : void 0
964
+ };
965
+ }
966
+ async function readAddonSkillGuidance(extractedDir, manifest) {
967
+ const hasSkillMemberAtRoot = manifest.members.some((member) => {
968
+ if (member.type !== "skill") {
969
+ return false;
970
+ }
971
+ const sourcePath = resolveMemberSourcePath(member);
972
+ return sourcePath === "SKILL.md";
973
+ });
974
+ if (hasSkillMemberAtRoot) {
975
+ return void 0;
976
+ }
977
+ const skillPath = path.join(extractedDir, "SKILL.md");
978
+ if (!fs.existsSync(skillPath)) {
979
+ return void 0;
980
+ }
981
+ const content = (await promises$1.readFile(skillPath, "utf8")).trim();
982
+ return content || void 0;
983
+ }
882
984
  function getAddonMetaPath(targetDir, addonName) {
883
985
  return path.join(targetDir, "src", "addons", addonName, "meta.json");
884
986
  }
@@ -1637,119 +1739,6 @@ async function validateUpgradeConflicts(targetDir, plan, existingMetas, previous
1637
1739
  });
1638
1740
  }
1639
1741
  }
1640
- async function ensureWebRoutesPatched(targetDir) {
1641
- const routesFile = path.join(targetDir, "src", "routes.tsx");
1642
- const original = await promises$1.readFile(routesFile, "utf8");
1643
- let next = original;
1644
- if (!next.includes("./amaster/registry/addon-routes.generated")) {
1645
- next = next.replace(
1646
- 'import type { ComponentType } from "react";',
1647
- 'import type { ComponentType } from "react";\nimport { addonRoutes } from "./amaster/registry/addon-routes.generated";'
1648
- );
1649
- }
1650
- if (!next.includes("...addonRoutes")) {
1651
- const routeArrayPattern = /const routes:\s*RouteConfig\[\]\s*=\s*\[([\s\S]*?)\];/;
1652
- const match = next.match(routeArrayPattern);
1653
- if (!match) {
1654
- throw new Error("Unable to patch src/routes.tsx for addon route registration");
1655
- }
1656
- const inner = match[1]?.trim() ?? "";
1657
- const replacement = inner ? `const routes: RouteConfig[] = [
1658
- ...addonRoutes,
1659
- ${match[1]}
1660
- ];` : "const routes: RouteConfig[] = [\n ...addonRoutes,\n];";
1661
- next = next.replace(routeArrayPattern, replacement);
1662
- }
1663
- if (next !== original) {
1664
- await promises$1.writeFile(routesFile, next);
1665
- }
1666
- }
1667
- async function ensureMiniAppConfigPatched(targetDir, needsTabBarItems) {
1668
- const configFile = path.join(targetDir, "src", "app.config.ts");
1669
- const original = await promises$1.readFile(configFile, "utf8");
1670
- let next = original;
1671
- if (!next.includes("./amaster/registry/addon-pages.generated")) {
1672
- next = `import { addonPages, addonTabBarItems } from "./amaster/registry/addon-pages.generated";
1673
- ${next}`;
1674
- }
1675
- if (!next.includes("...addonPages")) {
1676
- next = next.replace(/const pages\s*=\s*\[([\s\S]*?)\]/, (_full, inner) => {
1677
- const trimmed = inner.trim();
1678
- if (!trimmed) {
1679
- return "const pages = [...addonPages]";
1680
- }
1681
- return `const pages = [${inner}, ...addonPages]`;
1682
- });
1683
- }
1684
- if (needsTabBarItems && !next.includes("...addonTabBarItems")) {
1685
- const listPattern = /list:\s*\[([\s\S]*?)\]/;
1686
- const match = next.match(listPattern);
1687
- if (!match) {
1688
- throw new Error("Unable to patch src/app.config.ts for addon tabBar registration");
1689
- }
1690
- next = next.replace(listPattern, (_full, inner) => `list: [${inner}, ...addonTabBarItems]`);
1691
- }
1692
- if (next !== original) {
1693
- await promises$1.writeFile(configFile, next);
1694
- }
1695
- }
1696
- async function rebuildRegistryFiles(targetDir, applicationType, metas) {
1697
- const registryDir = path.join(targetDir, "src", "amaster", "registry");
1698
- await promises$1.mkdir(registryDir, { recursive: true });
1699
- if (applicationType === "web") {
1700
- const pageMembers2 = metas.flatMap(
1701
- (meta) => meta.members.filter((member) => member.type === "page" && member.page?.web).map((member) => ({ addonName: meta.name, member }))
1702
- ).sort((left, right) => `${left.addonName}:${left.member.name}`.localeCompare(`${right.addonName}:${right.member.name}`));
1703
- const imports = pageMembers2.map(({ addonName, member }) => {
1704
- const identifier = toPascalCase(`${addonName}-${member.name}-page`);
1705
- const entry = member.page.web.entry;
1706
- return {
1707
- identifier,
1708
- importPath: `../../${removeFileExtension(entry).replace(/\\/g, "/")}`,
1709
- route: member.page.web.route,
1710
- visible: member.page.web.visible,
1711
- name: member.name
1712
- };
1713
- });
1714
- const fileContent2 = [
1715
- 'import type { ComponentType } from "react";',
1716
- ...imports.map((item) => `import ${item.identifier} from "${item.importPath}";`),
1717
- "",
1718
- "type AddonRouteConfig = {",
1719
- " name: string;",
1720
- " path: string;",
1721
- " Component: ComponentType<Record<string, unknown>>;",
1722
- " visible?: boolean;",
1723
- "};",
1724
- "",
1725
- "export const addonRoutes: AddonRouteConfig[] = [",
1726
- ...imports.map(
1727
- (item) => ` { name: ${JSON.stringify(item.name)}, path: ${JSON.stringify(item.route)}, Component: ${item.identifier},${item.visible === void 0 ? "" : ` visible: ${item.visible},`} },`
1728
- ),
1729
- "];",
1730
- ""
1731
- ].join("\n");
1732
- await promises$1.writeFile(path.join(registryDir, "addon-routes.generated.ts"), fileContent2);
1733
- await ensureWebRoutesPatched(targetDir);
1734
- return;
1735
- }
1736
- const pageMembers = metas.flatMap(
1737
- (meta) => meta.members.filter((member) => member.type === "page" && member.page?.mini).map((member) => member.page.mini)
1738
- ).sort((left, right) => left.pagePath.localeCompare(right.pagePath));
1739
- const addonPages = pageMembers.map((page) => page.pagePath);
1740
- const addonTabBarItems = pageMembers.filter((page) => page.tabBar).map((page) => ({
1741
- pagePath: page.pagePath,
1742
- ...page.tabBar
1743
- }));
1744
- const fileContent = [
1745
- `export const addonPages = ${JSON.stringify(addonPages, null, 2)};`,
1746
- "",
1747
- `export const addonTabBarItems = ${JSON.stringify(addonTabBarItems, null, 2)};`,
1748
- ""
1749
- ].join("\n");
1750
- await promises$1.writeFile(path.join(registryDir, "addon-pages.generated.ts"), fileContent);
1751
- await ensureMiniAppConfigPatched(targetDir, addonTabBarItems.length > 0);
1752
- }
1753
1742
  async function materializeAddon(options) {
1754
1743
  const targetDir = path.resolve(options.targetDir);
1755
1744
  const existingMetas = await listInstalledAddons(targetDir);
@@ -1793,19 +1782,26 @@ async function materializeAddon(options) {
1793
1782
  });
1794
1783
  await ensureParentDirectory(plan.metaPath);
1795
1784
  await promises$1.writeFile(plan.metaPath, JSON.stringify(meta, null, 2));
1796
- const nextMetas = existingMetas.filter((item) => item.name !== meta.name).concat(meta);
1797
- await rebuildRegistryFiles(targetDir, plan.applicationType, nextMetas.filter((item) => item.applicationType === plan.applicationType));
1798
1785
  if (options.installPackageDependencies && packageJsonFiles.length) {
1799
1786
  await installPackageDependencies(targetDir);
1800
1787
  }
1801
1788
  const requirements = resolveInstallRequirements(plan.manifest);
1789
+ const skillContent = await readAddonSkillGuidance(options.extractedDir, plan.manifest);
1790
+ const llmGuidance = buildAddonLlmGuidance({
1791
+ operation: options.mode,
1792
+ meta,
1793
+ requirements,
1794
+ npm,
1795
+ skillContent
1796
+ });
1802
1797
  return {
1803
1798
  meta,
1804
1799
  writtenFiles: installedFiles.map((file) => file.path).concat(packageJsonFiles, restoredSettingsFiles, settingsResult.writtenFiles),
1805
1800
  removedFiles,
1806
1801
  requirements,
1807
1802
  missingRequirements: buildMissingRequirements(requirements),
1808
- npm
1803
+ npm,
1804
+ llmGuidance
1809
1805
  };
1810
1806
  }
1811
1807
  async function installAddonFromExtractedDirectory(options) {
@@ -3439,6 +3435,47 @@ function formatLoginIdentity(user) {
3439
3435
  function resolveAddonTargetDir(target) {
3440
3436
  return target ? target : resolveNearestPackageRoot();
3441
3437
  }
3438
+ function renderAddonInstallResult(result, operation, options) {
3439
+ const output = {
3440
+ success: true,
3441
+ operation,
3442
+ addon: {
3443
+ name: result.meta.name,
3444
+ version: result.meta.version,
3445
+ applicationType: result.meta.applicationType
3446
+ },
3447
+ files: {
3448
+ written: result.writtenFiles,
3449
+ removed: result.removedFiles
3450
+ },
3451
+ npm: Object.keys(result.npm.dependencies ?? {}).length ? result.npm : void 0,
3452
+ missingRequirements: result.missingRequirements.envs?.length || result.missingRequirements.secrets?.length ? result.missingRequirements : void 0,
3453
+ llmGuidance: result.llmGuidance
3454
+ };
3455
+ if (options.json) {
3456
+ renderOutput(output, options);
3457
+ return;
3458
+ }
3459
+ const lines = [
3460
+ `Addon ${operation === "install" ? "installed" : "upgraded"}: ${result.meta.name}@${result.meta.version}`,
3461
+ `Application type: ${result.meta.applicationType}`,
3462
+ `Written files: ${result.writtenFiles.length}`
3463
+ ];
3464
+ if (result.removedFiles.length) {
3465
+ lines.push(`Removed files: ${result.removedFiles.length}`);
3466
+ }
3467
+ if (result.llmGuidance.webRoutes?.length) {
3468
+ lines.push("Next: wire web routes from llmGuidance.webRoutes.");
3469
+ }
3470
+ if (result.llmGuidance.miniPages?.length) {
3471
+ lines.push("Next: wire mini pages from llmGuidance.miniPages.");
3472
+ }
3473
+ if (output.missingRequirements) {
3474
+ lines.push("Next: configure missing env/secrets from llmGuidance.requirements.");
3475
+ }
3476
+ lines.push("Use --json for LLM-readable integration guidance.");
3477
+ renderOutput(lines.join("\n"), options);
3478
+ }
3442
3479
  function requireStack(value) {
3443
3480
  if (value === "react-vite" || value === "taro") {
3444
3481
  return value;
@@ -3601,7 +3638,7 @@ addJsonOption(addOrganizationOption(addRegistryOption(addon.command("install <sp
3601
3638
  organizationCode: options.organizationCode,
3602
3639
  installParameters: parseKeyValuePairs(options.set)
3603
3640
  });
3604
- renderOutput(result, options);
3641
+ renderAddonInstallResult(result, "install", options);
3605
3642
  });
3606
3643
  addJsonOption(addOrganizationOption(addRegistryOption(addon.command("upgrade <specifier>").description("Upgrade an installed addon")))).option("--target <path>", "Application root directory, defaults to nearest package.json directory").addOption(new commander.Option("--application-type <type>", "Application type").choices(["web", "mini"])).option("--set <key=value>", "Install parameter", (value, previous = []) => previous.concat(value), []).action(async (specifier, options) => {
3607
3644
  const registry = resolveRegistryFromOptions(options);
@@ -3613,7 +3650,7 @@ addJsonOption(addOrganizationOption(addRegistryOption(addon.command("upgrade <sp
3613
3650
  organizationCode: options.organizationCode,
3614
3651
  installParameters: parseKeyValuePairs(options.set)
3615
3652
  });
3616
- renderOutput(result, options);
3653
+ renderAddonInstallResult(result, "upgrade", options);
3617
3654
  });
3618
3655
  addJsonOption(addon.command("list").description("List installed addons in an application")).option("--target <path>", "Application root directory, defaults to nearest package.json directory").action(async (options) => {
3619
3656
  const installed = await listInstalledAddons(resolveAddonTargetDir(options.target));