@alipay/alipay-aipay 1.7.0 → 1.7.1

package/README.md

@@ -3,3 +3,33 @@
 支持 AI 按量付费、AI 网页应用收款、AI 移动应用收款的代码开发与产品开通。
 
 支付宝 AI 付站点：https://aipay.alipay.com/?from=alipay-aipay-skill
+
+## 安装渠道
+
+```bash
+# 正式版（默认）
+npx -y @alipay/alipay-aipay@latest install
+
+# 预发版
+npx -y @alipay/alipay-aipay@latest install --channel pre
+```
+
+两份 Skill 可并存：正式版安装到 Agent 的 `skills/alipay-aipay/`，预发版安装到 `skills/alipay-aipay-pre/`。预发版使用独立名称 `alipay-aipay-pre`，在对话中明确点名或选择预发版使用。`--target` 的 Agent 目标选择规则不变。
+
+```bash
+# 只更新或卸载预发版；省略 --channel pre 则只操作正式版
+npx -y @alipay/alipay-aipay@latest update --channel pre
+npx -y @alipay/alipay-aipay@latest uninstall --channel pre
+```
+
+安装记录、自更新和卸载按渠道隔离；`--target all` 也只操作所选渠道。两份 Skill 共用系统环境中的 alipay-cli 和 jq，卸载 Skill 不卸载这些工具。
+
+## 维护与发布
+
+- `skill/` 是正式版源目录，`skill-pre/` 是可独立修改的预发版源目录，构建不会互相覆盖。
+- `package.json.version` 是 npm 分发包版本；`alipayAipayChannels.stable/pre` 分别对应两份 Skill 的 `VERSION`。安装器保留所选 Skill 的版本，不用包版本覆盖。
+- 每次发布提升 npm 包版本；只修改预发内容时，只提升预发 Skill 版本和相应元数据。正式版自更新发现自身版本未变时不下载安装。
+- 两份常规 Skill 自更新器都查询 npm `latest`，只比较自己的渠道版本，并从查询所得精确 npm 包版本中安装对应目录。元数据缺失、非法或为测试版本时保留本地，不切换渠道。
+- 正式版版本从 `1.7.0` 按 `1.7.1`、`1.7.2` 递增；预发版从 `1.7.0-pre` 按 `1.7.1-pre`、`1.7.2-pre` 递增。npm 包版本自此次拆分起独立维护。
+- 旧版 updater 首次升级前仍按 npm 包版本触发一次正式版迁移。正式版 VERSION 可保持 `1.7.0`；旧更新器可能在文件已迁移后返回内部 `VERIFY_FAILED`，启动器会继续读取当前可用入口，不阻塞业务。后续使用新渠道规则。
+- 本次预发版先复制正式版业务能力，后续定制直接修改 `skill-pre/`。对客消息、业务契约和发布校验仍遵循 `AGENTS.md`。

package/dist/commands/install-current.js

@@ -1,7 +1,8 @@
 import fs from 'fs/promises';
+import { getChannelConfig, getSkillVersion, readInstalledChannel, readInstalledVersion, skillVersionKind } from '../utils/channels.js';
 import path from 'path';
 import process from 'process';
-import { getCommandContextForTargetDir, getPackageVersion, PACKAGE_ROOT, SKILL_NAME, } from '../utils/config.js';
+import { getCommandContextForTargetDir, PACKAGE_ROOT, } from '../utils/config.js';
 import { installSkillFilesAtPath, readVersionRecord, writeVersionRecordWithFallback, } from '../utils/file.js';
 export const SELF_UPDATE_TARGET_ENV = 'ALIPAY_AIPAY_SELF_UPDATE_TARGET';
 export const SELF_UPDATE_TRANSACTION_ENV = 'ALIPAY_AIPAY_SELF_UPDATE_TRANSACTION';
@@ -28,28 +29,35 @@ async function requireCurrentSkillRoot(skillDir) {
 /**
  * 仅供 Skill 自更新调用：精确覆盖当前目录，不扫描任何 Agent 安装目标。
  */
-async function installBoundCurrentSkill(target, transactionId) {
+async function installBoundCurrentSkill(target, transactionId, channel) {
     const skillDir = await requireCurrentSkillRoot(target);
+    if (readInstalledChannel(skillDir) !== channel)
+        throw new Error('自更新渠道与目标不一致');
+    if (skillVersionKind(readInstalledVersion(skillDir), channel) === 'beta')
+        throw new Error('beta 版本只允许手动 install 换版');
+    if (skillVersionKind(getSkillVersion(PACKAGE_ROOT, channel), channel) !== 'release')
+        throw new Error('自更新禁止安装 beta');
+    const SKILL_NAME = getChannelConfig(channel).skillName;
     const canonicalInstall = path.basename(skillDir) === SKILL_NAME;
     const context = canonicalInstall
-        ? getCommandContextForTargetDir(path.dirname(skillDir))
+        ? getCommandContextForTargetDir(path.dirname(skillDir), channel)
         : null;
     const previousRecord = context ? await readVersionRecord(context) : null;
-    await installSkillFilesAtPath(PACKAGE_ROOT, skillDir, { transactionId });
+    await installSkillFilesAtPath(PACKAGE_ROOT, skillDir, { transactionId, channel });
     if (context && previousRecord) {
         await writeVersionRecordWithFallback(context, {
             ...previousRecord,
-            version: getPackageVersion(),
+            version: getSkillVersion(PACKAGE_ROOT, channel),
             installedAt: new Date().toISOString(),
         });
     }
 }
-export async function installCurrentSkillCommand() {
+export async function installCurrentSkillCommand(channel = 'stable') {
     const target = process.env[SELF_UPDATE_TARGET_ENV] || '';
     const transactionId = process.env[SELF_UPDATE_TRANSACTION_ENV] || '';
     if (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(transactionId)) {
         throw new Error('缺少合法的自更新事务 ID');
     }
-    await installBoundCurrentSkill(target, transactionId);
+    await installBoundCurrentSkill(target, transactionId, channel);
 }
 //# sourceMappingURL=install-current.js.map

package/dist/commands/install.js

@@ -1,21 +1,22 @@
 import chalk from 'chalk';
+import { getChannelConfig, getSkillVersion } from '../utils/channels.js';
 import ora from 'ora';
 import { spawn } from 'child_process';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
-import { SKILLS, getPackageVersion, getCommandContext, getAllCommandContexts, detectCurrentAgentTarget, DEFAULT_TARGET, PACKAGE_ROOT, SKILL_NAME, TARGET_DIRS, } from '../utils/config.js';
+import { getCommandContext, getAllCommandContexts, detectCurrentAgentTarget, DEFAULT_TARGET, PACKAGE_ROOT, TARGET_DIRS, } from '../utils/config.js';
 import { ensureDir, installSkillFiles, readVersionRecord, writeVersionRecordWithFallback, } from '../utils/file.js';
 import { checkAlipayCli } from '../utils/alipay-cli.js';
 import { checkJq, isJqRequiredPlatform, resolveManagedJqAsset } from '../utils/jq.js';
-function resolveInstallPlan(cwd, target) {
+function resolveInstallPlan(cwd, target, channel) {
     if (target !== 'all') {
-        const context = getCommandContext(cwd, target);
+        const context = getCommandContext(cwd, target, channel);
         return { contexts: [context], primaryTargetDir: path.resolve(context.targetDir) };
     }
     const primaryTarget = detectCurrentAgentTarget() || DEFAULT_TARGET;
-    const primaryContext = getCommandContext(cwd, primaryTarget);
-    const contexts = getAllCommandContexts(cwd, primaryTarget);
+    const primaryContext = getCommandContext(cwd, primaryTarget, channel);
+    const contexts = getAllCommandContexts(cwd, primaryTarget, channel);
     const primaryTargetDir = path.resolve(primaryContext.targetDir);
     const ordered = [
         primaryContext,
@@ -24,19 +25,22 @@ function resolveInstallPlan(cwd, target) {
     return { contexts: ordered, primaryTargetDir };
 }
 export async function installCommand(cwd, options = {}) {
+    const channel = options.channel ?? 'stable';
+    const { skillName: SKILL_NAME, displayName } = getChannelConfig(channel);
+    const SKILLS = [{ name: SKILL_NAME, displayName }];
     const target = options.target ?? 'all';
     const skipTools = options.skipTools ?? false;
     const jqRequired = isJqRequiredPlatform();
     const jqPreparationSupported = resolveManagedJqAsset() !== null;
-    const installPlan = resolveInstallPlan(cwd, target);
+    const installPlan = resolveInstallPlan(cwd, target, channel);
     const { contexts, primaryTargetDir } = installPlan;
-    const version = getPackageVersion();
+    const version = getSkillVersion(PACKAGE_ROOT, channel);
     const targetDirLabels = contexts.map((ctx) => ctx.targetDirLabel);
     const targetSkillDirs = contexts.map((ctx) => path.join(ctx.targetDir, SKILL_NAME));
-    console.log(chalk.cyan.bold(`\n🚀 @alipay/alipay-aipay v${version}\n`));
+    console.log(chalk.cyan.bold(`\n🚀 @alipay/alipay-aipay ${channel} v${version}\n`));
     console.log(chalk.gray('优先安装 Skill 文件；alipay-cli 和用户级 jq 可在后台准备，不调用系统包管理器\n'));
     console.log(chalk.gray(`安装目标: ${targetSkillDirs.join(', ')}`));
-    console.log(chalk.gray(`${describeTargetSelection(os.homedir(), target, targetDirLabels, primaryTargetDir)}\n`));
+    console.log(chalk.gray(`${describeTargetSelection(os.homedir(), target, targetDirLabels, primaryTargetDir, SKILL_NAME)}\n`));
     // ========== 阶段 1: 环境检查 ==========
     let alipayCliOk = false;
     let jqOk = false;
@@ -112,12 +116,12 @@ export async function installCommand(cwd, options = {}) {
             try {
                 const existingRecord = await readVersionRecord(ctx);
                 if (existingRecord) {
-                    console.log(chalk.yellow(`检测到已有安装记录，直接覆盖更新: ${ctx.targetDirLabel}/alipay-aipay/`));
+                    console.log(chalk.yellow(`检测到已有安装记录，直接覆盖更新: ${ctx.targetDirLabel}/${SKILL_NAME}/`));
                     console.log(`  旧版本: ${existingRecord.version}  安装时间: ${existingRecord.installedAt}`);
                     console.log('');
                 }
                 await ensureDir(ctx.targetDir);
-                await installSkillFiles(PACKAGE_ROOT, ctx.targetDir);
+                await installSkillFiles(PACKAGE_ROOT, ctx.targetDir, channel);
                 const record = {
                     version,
                     installedAt: new Date().toISOString(),
@@ -149,7 +153,7 @@ export async function installCommand(cwd, options = {}) {
         if (legacyRecordLabels.length > 0) {
             console.log(chalk.yellow('⚠️  用户配置目录安装记录写入失败，已降级写入 Skill 目录内兼容记录。'));
             for (const targetDirLabel of legacyRecordLabels) {
-                console.log(chalk.gray(`   记录位置: ${targetDirLabel}/alipay-aipay/.alipay-aipay-version`));
+                console.log(chalk.gray(`   记录位置: ${targetDirLabel}/${SKILL_NAME}/.alipay-aipay-version`));
             }
             console.log('');
         }
@@ -161,19 +165,19 @@ export async function installCommand(cwd, options = {}) {
         process.exit(1);
     }
 }
-function describeTargetSelection(targetRoot, target, targetDirLabels, primaryTargetDir) {
+function describeTargetSelection(targetRoot, target, targetDirLabels, primaryTargetDir, skillName) {
     if (target === 'all') {
         const hasExistingAgentRoot = Object.keys(TARGET_DIRS)
             .map((targetName) => path.dirname(TARGET_DIRS[targetName]))
             .some((rootDir) => fs.existsSync(path.join(targetRoot, rootDir)));
         const primaryLabel = targetDirLabels.find((label) => path.resolve(path.isAbsolute(label) ? label : path.join(targetRoot, label)) === primaryTargetDir) || primaryTargetDir;
         if (!hasExistingAgentRoot && targetDirLabels.length === 1) {
-            return `目标选择: --target all；优先安装当前 Agent 目标 ${primaryLabel}/alipay-aipay/`;
+            return `目标选择: --target all；优先安装当前 Agent 目标 ${primaryLabel}/${skillName}/`;
         }
-        return `目标选择: --target all；当前 Agent 目标 ${primaryLabel}/alipay-aipay/ 优先且必须成功，其他已存在目标尽力安装`;
+        return `目标选择: --target all；当前 Agent 目标 ${primaryLabel}/${skillName}/ 优先且必须成功，其他已存在目标尽力安装`;
     }
     if (target === 'auto') {
-        return `目标选择: --target auto，按当前 Agent/已有安装目录解析为 ${targetDirLabels[0]}/alipay-aipay/`;
+        return `目标选择: --target auto，按当前 Agent/已有安装目录解析为 ${targetDirLabels[0]}/${skillName}/`;
     }
     return `目标选择: --target ${target}`;
 }

package/dist/commands/uninstall.js

@@ -1,21 +1,26 @@
 import inquirer from 'inquirer';
+import { getChannelConfig } from '../utils/channels.js';
 import chalk from 'chalk';
 import ora from 'ora';
 import fs from 'fs/promises';
-import { SKILLS, getCommandContext, getAllCommandContexts } from '../utils/config.js';
+import { getCommandContext, getAllCommandContexts } from '../utils/config.js';
 import { removeDir, readVersionRecord, resolveInstalledSkillPaths } from '../utils/file.js';
 export async function uninstallCommand(cwd, options = {}) {
+    const channel = options.channel ?? 'stable';
     const target = options.target ?? 'auto';
     if (target === 'all') {
-        for (const ctx of getAllCommandContexts(cwd)) {
+        for (const ctx of getAllCommandContexts(cwd, undefined, channel)) {
             await uninstallResolvedContext(ctx);
         }
         return;
     }
-    const ctx = getCommandContext(cwd, target);
+    const ctx = getCommandContext(cwd, target, channel);
     await uninstallResolvedContext(ctx);
 }
 async function uninstallResolvedContext(ctx) {
+    const channel = ctx.channel ?? 'stable';
+    const { skillName: SKILL_NAME, displayName } = getChannelConfig(channel);
+    const SKILLS = [{ name: SKILL_NAME, displayName }];
     // 检查是否有安装记录
     const record = await readVersionRecord(ctx);
     if (!record) {

package/dist/commands/update.js

@@ -1,52 +1,70 @@
 import inquirer from 'inquirer';
+import semver from 'semver';
+import { getChannelConfig, getSkillVersion, readInstalledVersion, skillVersionKind } from '../utils/channels.js';
 import chalk from 'chalk';
+import path from 'path';
 import ora from 'ora';
-import { SKILLS, getPackageVersion, getCommandContext, getAllCommandContexts, PACKAGE_ROOT, SKILL_NAME, } from '../utils/config.js';
-import { ensureDir, installSkillFiles, readVersionRecord, migrateVersionRecord, writeVersionRecordWithFallback, } from '../utils/file.js';
+import { getCommandContext, getAllCommandContexts, PACKAGE_ROOT, } from '../utils/config.js';
+import { ensureDir, installSkillFiles, readVersionRecord, migrateVersionRecord, writeVersionRecordWithFallback, resolveInstalledSkillPaths, } from '../utils/file.js';
 import { checkForUpdates } from '../utils/npm.js';
 import { checkAlipayCli } from '../utils/alipay-cli.js';
 import { checkJq, isJqRequiredPlatform } from '../utils/jq.js';
 export async function updateCommand(cwd, options = {}) {
+    const channel = options.channel ?? 'stable';
     const target = options.target ?? 'auto';
     if (target === 'all') {
-        for (const ctx of getAllCommandContexts(cwd)) {
+        for (const ctx of getAllCommandContexts(cwd, undefined, channel)) {
             await updateResolvedContext(ctx);
         }
         return;
     }
-    const ctx = getCommandContext(cwd, target);
+    const ctx = getCommandContext(cwd, target, channel);
     await updateResolvedContext(ctx);
 }
 async function updateResolvedContext(ctx) {
-    const currentPackageVersion = getPackageVersion();
+    const channel = ctx.channel ?? 'stable';
+    const { skillName: SKILL_NAME, displayName } = getChannelConfig(channel);
+    const SKILLS = [{ name: SKILL_NAME, displayName }];
+    const installCommandText = `npx -y @alipay/alipay-aipay@latest install${channel === 'pre' ? ' --channel pre' : ''}`;
+    const currentSkillVersion = getSkillVersion(PACKAGE_ROOT, channel);
     // 检查是否有安装记录
     const record = await readVersionRecord(ctx);
     if (!record) {
         console.log(chalk.yellow('\n未检测到已安装的支付宝 AI 付接入 Skill。'));
-        console.log(chalk.gray(`请先运行 \`npx -y @alipay/alipay-aipay@latest install\` 安装到 ${ctx.targetDir}/。\n`));
+        console.log(chalk.gray(`请先运行 \`${installCommandText}\` 安装到 ${ctx.targetDir}/。\n`));
+        return;
+    }
+    const installedVersion = readInstalledVersion(path.join(ctx.targetDir, SKILL_NAME)) ?? record.version;
+    if ([installedVersion, currentSkillVersion].some(version => skillVersionKind(version, channel) === 'beta')) {
+        console.log(chalk.gray('beta 测试版本保持固定；如需换版，请手动运行所选 npm 包的 install 命令。'));
         return;
     }
     console.log(chalk.cyan.bold('\n🔄 检查更新...\n'));
     // 检查 npm 最新版本
     const spinner = ora('正在检查 npm 最新版本...').start();
     try {
-        const versionInfo = await checkForUpdates();
+        resolveInstalledSkillPaths(ctx.targetDir, record.skills, [SKILL_NAME]);
+        const versionInfo = await checkForUpdates(channel);
         if (versionInfo.needsUpdate) {
-            spinner.warn(chalk.yellow('当前执行的 alipay-aipay 包不是 npm latest，未执行更新。\n'));
+            spinner.warn(chalk.yellow('当前执行包中的所选渠道版本较旧，未执行更新。\n'));
             console.log(`当前执行版本: ${versionInfo.current}`);
             console.log(`npm latest: ${versionInfo.latest}`);
             console.log(chalk.gray('请运行以下命令安装最新 Skill:'));
-            console.log(chalk.cyan('  npx -y @alipay/alipay-aipay@latest install\n'));
+            console.log(chalk.cyan(`  ${installCommandText}\n`));
+            return;
+        }
+        if (semver.valid(record.version) && semver.gt(record.version, currentSkillVersion)) {
+            spinner.succeed('本地渠道版本较新，保留当前安装。');
             return;
         }
-        if (record.version === currentPackageVersion) {
+        if (record.version === currentSkillVersion) {
             await migrateVersionRecord(ctx, record);
             spinner.succeed(chalk.green('Skill 文件已是当前执行包版本!\n'));
-            console.log(`当前版本: ${currentPackageVersion}`);
+            console.log(`当前版本: ${currentSkillVersion}`);
             console.log(`安装时间: ${record.installedAt}`);
         }
         else {
-            spinner.info(chalk.blue(`发现可安装版本: ${currentPackageVersion} (已安装: ${record.version})\n`));
+            spinner.info(chalk.blue(`发现可安装版本: ${currentSkillVersion} (已安装: ${record.version})\n`));
             // 显示更新信息
             console.log('将更新以下 Skill:\n');
             for (const skillName of record.skills) {
@@ -72,10 +90,10 @@ async function updateResolvedContext(ctx) {
             // 开始更新
             const updateSpinner = ora('正在更新 Skill 文件...').start();
             await ensureDir(ctx.targetDir);
-            await installSkillFiles(PACKAGE_ROOT, ctx.targetDir);
-            // 更新版本记录（用当前包的实际版本，而非 registry 上的最新版本）
+            await installSkillFiles(PACKAGE_ROOT, ctx.targetDir, channel);
+            // 更新版本记录：只记录当前包中所选 Skill 的版本。
             const newRecord = {
-                version: currentPackageVersion,
+                version: currentSkillVersion,
                 installedAt: new Date().toISOString(),
                 skills: SKILLS.map((s) => s.name),
                 alipayCliInstalled: record.alipayCliInstalled,
@@ -83,7 +101,7 @@ async function updateResolvedContext(ctx) {
             };
             await writeVersionRecordWithFallback(ctx, newRecord);
             updateSpinner.succeed(chalk.green('Skill 文件更新完成!\n'));
-            console.log(`版本: ${record.version} → ${currentPackageVersion}`);
+            console.log(`版本: ${record.version} → ${currentSkillVersion}`);
         }
         console.log('');
         // 重新检查环境工具

package/dist/index.js

@@ -1,4 +1,5 @@
 import { Command } from 'commander';
+import { parseChannel } from './utils/channels.js';
 import chalk from 'chalk';
 import { getPackageVersion } from './utils/config.js';
 import { installCommand } from './commands/install.js';
@@ -22,6 +23,7 @@ program
 // install 命令
 program
     .command('install')
+    .option('--channel <channel>', 'Skill 渠道: stable | pre', parseChannel, 'stable')
     .description('安装支付宝 AI 付接入 Skill（Skill 文件优先完成，工具准备不阻塞安装）')
     .option('--target <target>', '安装目标: all | agents | codex | claude | auto', 'all')
     .option('--with-jq', '兼容参数；macOS/Linux 缺少 jq 时默认已在 detached 后台准备')
@@ -29,24 +31,27 @@ program
     .action(async (options) => {
     await installCommand(process.cwd(), {
         target: parseTarget(options.target),
+        channel: options.channel,
         skipTools: Boolean(options.skipTools),
     });
 });
 // uninstall 命令
 program
     .command('uninstall')
+    .option('--channel <channel>', 'Skill 渠道: stable | pre', parseChannel, 'stable')
     .description('卸载已安装的支付宝 AI 付接入 Skill')
     .option('--target <target>', '卸载目标: all | agents | codex | claude | auto', 'auto')
     .action(async (options) => {
-    await uninstallCommand(process.cwd(), { target: parseTarget(options.target) });
+    await uninstallCommand(process.cwd(), { target: parseTarget(options.target), channel: options.channel });
 });
 // update 命令
 program
     .command('update')
+    .option('--channel <channel>', 'Skill 渠道: stable | pre', parseChannel, 'stable')
     .description('检查并更新支付宝 AI 付接入 Skill')
     .option('--target <target>', '更新目标: all | agents | codex | claude | auto', 'auto')
     .action(async (options) => {
-    await updateCommand(process.cwd(), { target: parseTarget(options.target) });
+    await updateCommand(process.cwd(), { target: parseTarget(options.target), channel: options.channel });
 });
 program
     .command('prepare-tools', { hidden: true })
@@ -57,9 +62,10 @@ program
 });
 program
     .command('install-current', { hidden: true })
+    .option('--channel <channel>', 'Skill 渠道', parseChannel, 'stable')
     .description('精确覆盖当前运行中的 Skill 目录')
-    .action(async () => {
-    await installCurrentSkillCommand();
+    .action(async (options) => {
+    await installCurrentSkillCommand(options.channel);
 });
 // 默认行为：无参数时直接执行安装流程
 if (process.argv.length === 2) {

package/dist/utils/channels.js

@@ -0,0 +1,67 @@
+import fs from 'fs';
+import path from 'path';
+import semver from 'semver';
+export const CHANNEL_FILE = 'references/normal/json/release-channel.json';
+export function parseChannel(value) {
+    if (value === 'stable' || value === 'pre')
+        return value;
+    throw new Error('无效的 --channel；可选值: stable | pre');
+}
+export function getChannelConfig(channel = 'stable') {
+    parseChannel(channel);
+    return channel === 'pre'
+        ? { channel, skillName: 'alipay-aipay-pre', sourceDir: 'skill-pre', displayName: '支付宝 AI 付接入 Skill 预发版' }
+        : { channel, skillName: 'alipay-aipay', sourceDir: 'skill', displayName: '支付宝 AI 付接入 Skill' };
+}
+export function readInstalledChannel(skillDir) {
+    const source = fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf8');
+    const declaredName = source.match(/^name:\s*(\S+)\s*$/m)?.[1];
+    const identity = declaredName === 'alipay-aipay-pre' ? 'pre' : 'stable';
+    try {
+        const file = path.join(skillDir, CHANNEL_FILE);
+        if (!fs.lstatSync(file).isFile())
+            throw new Error('渠道文件必须是普通文件');
+        const channel = parseChannel(JSON.parse(fs.readFileSync(file, 'utf8')).channel);
+        if (channel !== identity)
+            throw new Error('Skill 名称与渠道不一致');
+        return channel;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT' && identity === 'stable')
+            return 'stable';
+        throw error;
+    }
+}
+export function skillVersionKind(version, channel) {
+    if (typeof version !== 'string')
+        return null;
+    const parsed = semver.parse(version);
+    if (!parsed)
+        return null;
+    const suffix = parsed.prerelease.join('.');
+    if (suffix === (channel === 'pre' ? 'pre' : ''))
+        return 'release';
+    const pattern = channel === 'pre' ? /^pre-beta(?:\d+|\.\d+)?$/u : /^beta(?:\d+|\.\d+)?$/u;
+    return pattern.test(suffix) ? 'beta' : null;
+}
+export function readInstalledVersion(skillDir) {
+    try {
+        const file = path.join(skillDir, 'VERSION');
+        if (!fs.lstatSync(file).isFile())
+            return null;
+        return fs.readFileSync(file, 'utf8').trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function getSkillVersion(packageRoot, channel = 'stable') {
+    const config = getChannelConfig(channel);
+    const version = fs.readFileSync(path.join(packageRoot, config.sourceDir, 'VERSION'), 'utf8').trim();
+    const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+    if (!semver.valid(version) || !skillVersionKind(version, channel) || pkg.alipayAipayChannels?.[channel] !== version) {
+        throw new Error(`渠道 ${channel} 的 VERSION 与 npm 元数据不一致或非法`);
+    }
+    return version;
+}
+//# sourceMappingURL=channels.js.map

package/dist/utils/config.js

@@ -4,6 +4,7 @@ import { createHash } from 'crypto';
 import { fileURLToPath } from 'url';
 import fs from 'fs';
 import { execFileSync } from 'child_process';
+import { getChannelConfig } from './channels.js';
 // 获取当前包的根目录
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export const PACKAGE_ROOT = path.resolve(__dirname, '../../');
@@ -99,7 +100,8 @@ export function detectCurrentAgentTarget() {
 /**
  * 解析安装目标
  */
-export function resolveInstallTarget(cwd, target = 'auto') {
+export function resolveInstallTarget(cwd, target = 'auto', channel = 'stable') {
+    const SKILL_NAME = getChannelConfig(channel).skillName;
     if (target === 'agents' || target === 'claude') {
         return target;
     }
@@ -153,15 +155,17 @@ export function getExtraSkillDirs() {
         .map((item) => item.trim())
         .filter((item) => item.length > 0 && !item.includes('\0'));
 }
-function createCommandContext(cwd, targetDirLabel) {
+function createCommandContext(cwd, targetDirLabel, channel = 'stable') {
+    const SKILL_NAME = getChannelConfig(channel).skillName;
     const targetDir = path.isAbsolute(targetDirLabel)
         ? targetDirLabel
         : path.join(cwd, targetDirLabel);
     const skillDir = path.join(targetDir, SKILL_NAME);
     const resolvedTargetDir = path.resolve(targetDir);
-    const versionFileName = `${createHash('sha256').update(resolvedTargetDir).digest('hex')}.json`;
+    const versionFileName = `${createHash('sha256').update(channel === 'stable' ? resolvedTargetDir : `${resolvedTargetDir}\0${channel}`).digest('hex')}.json`;
     return {
         cwd,
+        channel,
         targetDir,
         versionFile: path.join(os.homedir(), '.config', 'alipay-aipay', 'install-records', versionFileName),
         legacyVersionFile: path.join(skillDir, VERSION_FILE),
@@ -171,12 +175,12 @@ function createCommandContext(cwd, targetDirLabel) {
 /**
  * 为已经解析出的 skills 父目录构造命令上下文。
  */
-export function getCommandContextForTargetDir(targetDir) {
+export function getCommandContextForTargetDir(targetDir, channel = 'stable') {
     if (!path.isAbsolute(targetDir) || targetDir.includes('\0')) {
         throw new Error('Skill 目标父目录必须是绝对路径');
     }
     const resolvedTargetDir = path.resolve(targetDir);
-    return createCommandContext(resolvedTargetDir, resolvedTargetDir);
+    return createCommandContext(resolvedTargetDir, resolvedTargetDir, channel);
 }
 function getExistingInstallTargetNames(cwd) {
     return getAllInstallTargetNames().filter((targetName) => fs.existsSync(path.join(cwd, TARGET_ROOT_DIRS[targetName])));
@@ -185,17 +189,17 @@ function getExistingInstallTargetNames(cwd) {
  * 获取批量安装目标上下文。普通命令扫描用户 Home 下已有的内置 Agent 目录；
  * 若没有任何已存在目录，则使用调用方指定的回退目标。环境变量可追加兼容 Skill 目录。
  */
-export function getAllCommandContexts(cwd, fallbackTarget = DEFAULT_TARGET) {
+export function getAllCommandContexts(cwd, fallbackTarget = DEFAULT_TARGET, channel = 'stable') {
     const extraSkillDirs = getExtraSkillDirs();
     const homeDir = os.homedir();
     const targetNames = getExistingInstallTargetNames(homeDir);
     if (targetNames.length === 0) {
         targetNames.push(fallbackTarget);
     }
-    const contexts = targetNames.map((targetName) => createCommandContext(homeDir, TARGET_DIRS[targetName]));
+    const contexts = targetNames.map((targetName) => createCommandContext(homeDir, TARGET_DIRS[targetName], channel));
     const seen = new Set(contexts.map((ctx) => path.resolve(ctx.targetDir)));
     for (const extraDir of extraSkillDirs) {
-        const ctx = createCommandContext(cwd, extraDir);
+        const ctx = createCommandContext(cwd, extraDir, channel);
         const resolved = path.resolve(ctx.targetDir);
         if (seen.has(resolved))
             continue;
@@ -207,11 +211,11 @@ export function getAllCommandContexts(cwd, fallbackTarget = DEFAULT_TARGET) {
 /**
  * 获取命令上下文
  */
-export function getCommandContext(_cwd, target = 'auto') {
+export function getCommandContext(_cwd, target = 'auto', channel = 'stable') {
     const homeDir = os.homedir();
-    const targetName = resolveInstallTarget(homeDir, target);
+    const targetName = resolveInstallTarget(homeDir, target, channel);
     const targetDirLabel = TARGET_DIRS[targetName];
-    return createCommandContext(homeDir, targetDirLabel);
+    return createCommandContext(homeDir, targetDirLabel, channel);
 }
 /**
  * 获取包版本

package/dist/utils/file.js

@@ -2,7 +2,7 @@ import fs from 'fs/promises';
 import path from 'path';
 import { randomUUID } from 'crypto';
 import { setTimeout as delay } from 'timers/promises';
-import { SKILL_NAME, SKILL_DIR } from './config.js';
+import { getChannelConfig, getSkillVersion, readInstalledChannel } from './channels.js';
 /**
  * 检查目录是否存在
  */
@@ -236,8 +236,8 @@ export async function writeVersionRecordWithFallback(ctx, record) {
  * 安装 Skill 文件到目标目录
  * 从包内 skill/ 目录复制 SKILL.md + references/ 到目标 skills 目录
  */
-export async function installSkillFiles(packageRoot, targetDir) {
-    return installSkillFilesAtPath(packageRoot, path.join(targetDir, SKILL_NAME));
+export async function installSkillFiles(packageRoot, targetDir, channel = 'stable') {
+    return installSkillFilesAtPath(packageRoot, path.join(targetDir, getChannelConfig(channel).skillName), { channel });
 }
 /**
  * 原子安装到已经确定的单个 Skill 目录。自更新使用事务 ID，便于超时恢复。
@@ -246,6 +246,8 @@ export async function installSkillFilesAtPath(packageRoot, skillTargetDir, optio
     if (!path.isAbsolute(skillTargetDir) || skillTargetDir.includes('\0')) {
         throw new Error('Skill 安装目录必须是绝对路径');
     }
+    const channel = options.channel ?? 'stable';
+    const { skillName: SKILL_NAME, sourceDir: SKILL_DIR } = getChannelConfig(channel);
     const transactionId = options.transactionId;
     if (transactionId && !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(transactionId)) {
         throw new Error('无效的 Skill 安装事务 ID');
@@ -253,7 +255,20 @@ export async function installSkillFilesAtPath(packageRoot, skillTargetDir, optio
     const resolvedSkillTargetDir = path.resolve(skillTargetDir);
     const targetDir = path.dirname(resolvedSkillTargetDir);
     const skillSourceDir = path.join(packageRoot, SKILL_DIR);
-    const packageJson = JSON.parse(await fs.readFile(path.join(packageRoot, 'package.json'), 'utf-8'));
+    const skillVersion = getSkillVersion(packageRoot, channel);
+    if (readInstalledChannel(skillSourceDir) !== channel)
+        throw new Error('安装源渠道不匹配');
+    for (const file of ['SKILL.md', 'VERSION', 'references/runtime-entry.md']) {
+        if (!(await fs.lstat(path.join(skillSourceDir, file))).isFile())
+            throw new Error('Skill 安装源不完整');
+    }
+    const oppositeName = getChannelConfig(channel === 'stable' ? 'pre' : 'stable').skillName;
+    if (path.basename(resolvedSkillTargetDir) === oppositeName)
+        throw new Error('禁止覆盖另一渠道目录');
+    if (await pathExists(path.join(resolvedSkillTargetDir, 'SKILL.md'))) {
+        if (readInstalledChannel(resolvedSkillTargetDir) !== channel)
+            throw new Error('禁止跨渠道覆盖 Skill');
+    }
     await ensureDir(targetDir);
     const stagingDir = transactionId
         ? path.join(targetDir, `.${SKILL_NAME}-install-${transactionId}`)
@@ -266,9 +281,7 @@ export async function installSkillFilesAtPath(packageRoot, skillTargetDir, optio
     try {
         await fs.copyFile(path.join(skillSourceDir, 'SKILL.md'), path.join(stagingDir, 'SKILL.md'));
         await copyDirWithPerms(path.join(skillSourceDir, 'references'), path.join(stagingDir, 'references'));
-        if (packageJson.version) {
-            await fs.writeFile(path.join(stagingDir, 'VERSION'), `${packageJson.version}\n`, 'utf-8');
-        }
+        await fs.copyFile(path.join(skillSourceDir, 'VERSION'), path.join(stagingDir, 'VERSION'));
         if (await pathExists(resolvedSkillTargetDir)) {
             try {
                 await fs.rename(resolvedSkillTargetDir, backupDir);
@@ -286,8 +299,8 @@ export async function installSkillFilesAtPath(packageRoot, skillTargetDir, optio
         catch (installError) {
             const installErrorCode = installError.code;
             const sameVersionInstalled = ['EEXIST', 'ENOTEMPTY', 'ENOENT'].includes(installErrorCode ?? '')
-                ? await waitForCompleteInstalledVersion(resolvedSkillTargetDir, packageJson.version)
-                : await hasCompleteInstalledVersion(resolvedSkillTargetDir, packageJson.version);
+                ? await waitForCompleteInstalledVersion(resolvedSkillTargetDir, skillVersion)
+                : await hasCompleteInstalledVersion(resolvedSkillTargetDir, skillVersion);
             if (sameVersionInstalled) {
                 if (previousInstallMoved) {
                     await removeDir(backupDir);
@@ -303,7 +316,7 @@ export async function installSkillFilesAtPath(packageRoot, skillTargetDir, optio
                 catch (restoreError) {
                     const restoreErrorCode = restoreError.code;
                     if (['EEXIST', 'ENOTEMPTY', 'ENOENT'].includes(restoreErrorCode ?? '') &&
-                        await waitForCompleteInstalledVersion(resolvedSkillTargetDir, packageJson.version)) {
+                        await waitForCompleteInstalledVersion(resolvedSkillTargetDir, skillVersion)) {
                         await removeDir(backupDir);
                         previousInstallMoved = false;
                         return;