@liangjie559567/ultrapower 5.5.39 → 5.5.41

package/.claude-plugin/marketplace.json

@@ -8,11 +8,11 @@
     {
       "name": "ultrapower",
       "description": "Disciplined multi-agent orchestration: workflow enforcement + parallel execution",
-      "version": "5.5.39",
+      "version": "5.5.41",
       "source": {
         "source": "npm",
         "package": "@liangjie559567/ultrapower",
-        "version": "5.5.39"
+        "version": "5.5.41"
       },
       "author": {
         "name": "liangjie559567"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ultrapower",
   "description": "Disciplined multi-agent orchestration: workflow enforcement + parallel execution",
-  "version": "5.5.39",
+  "version": "5.5.41",
   "author": {
     "name": "liangjie559567"
   },
@@ -19,11 +19,5 @@
     "claudecode",
     "anthropic",
     "llm"
-  ],
-  "statusline": {
-    "command": "node",
-    "args": [
-      "dist/hud/index.js"
-    ]
-  }
+  ]
 }

package/docs/CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- OMC:START -->
-<!-- OMC:VERSION:5.5.33 -->
+<!-- OMC:VERSION:5.5.40 -->
 # ultrapower - Multi-Agent Orchestration 智能多 Agent 编排
 
 你正在使用 ultrapower（OMC），这是 Claude Code 的多 agent 编排层。

package/docs/INSTALL.md

@@ -1,6 +1,6 @@
 # ultrapower 安装部署详细教程
 
-ultrapower v5.5.33 完整安装指南，覆盖从零开始到完全配置的所有步骤。
+ultrapower v5.5.40 完整安装指南，覆盖从零开始到完全配置的所有步骤。
 
 ---
 
@@ -88,7 +88,7 @@ git --version
 
 **预期输出：**
 ```
-✓ Installing ultrapower v5.5.33...
+✓ Installing ultrapower v5.5.40...
 ✓ Hooks registered: 39
 ✓ Agents loaded: 49
 ✓ Skills available: 71

package/docs/REFERENCE.md

@@ -1,4 +1,4 @@
-<!-- ultrapower v5.5.33 | updated: 2026-03-02 -->
+<!-- ultrapower v5.5.40 | updated: 2026-03-02 -->
 
 # ultrapower Reference — v5.5.33
 

package/docs/RELEASE.md

@@ -0,0 +1,49 @@
+# 发布流程
+
+## 自动化发布（推荐）
+
+### 1. 创建 changeset
+
+```bash
+npm run changeset
+```
+
+回答问题：
+- 选择变更类型（patch/minor/major）
+- 输入变更描述
+
+### 2. 提交 changeset
+
+```bash
+git add .changeset
+git commit -m "chore: add changeset for feature X"
+git push origin dev
+```
+
+### 3. 合并到 main
+
+创建 PR 从 dev 到 main，合并后 GitHub Actions 自动：
+- 运行测试
+- 更新版本号
+- 生成 CHANGELOG
+- 发布到 npm
+- 创建 GitHub Release
+
+## 手动发布
+
+```bash
+npm run changeset        # 创建 changeset
+npm run version          # 更新版本
+npm run release          # 发布到 npm
+```
+
+## GitHub Secrets 配置
+
+在仓库设置中添加：
+- `NPM_TOKEN`: 从 npmjs.com 获取访问令牌
+
+## 版本规范
+
+- **patch** (5.5.39 → 5.5.40): Bug 修复
+- **minor** (5.5.39 → 5.6.0): 新功能
+- **major** (5.5.39 → 6.0.0): 破坏性变更

package/docs/RELEASE_GUIDE.md

@@ -0,0 +1,218 @@
+# ultrapower 插件发布完整指南
+
+## 📋 目录
+
+1. [快速发布流程](#快速发布流程)
+2. [发布架构](#发布架构)
+3. [详细步骤](#详细步骤)
+4. [高级配置](#高级配置)
+5. [故障排查](#故障排查)
+
+---
+
+## 快速发布流程
+
+```bash
+# 1. 更新版本
+node scripts/bump-version.mjs 5.5.41
+
+# 2. 提交到 dev
+git add .
+git commit -m "chore: bump version to 5.5.41"
+git push origin dev
+
+# 3. 合并到 main（触发自动发布）
+git checkout main
+git merge dev
+git push origin main
+```
+
+GitHub Actions 自动执行：构建 → 测试 → NPM 发布 → GitHub Release → 插件市场同步
+
+---
+
+## 发布架构
+
+```
+版本更新 → 构建验证 → NPM 发布 → GitHub Release → 插件市场同步
+   ↓           ↓           ↓            ↓              ↓
+bump-version  tsc+test   npm publish  gh release    git push dev
+```
+
+### 5 步流水线
+
+1. **Preflight** - 版本同步校验（5 个配置文件）
+2. **Validate** - TypeScript + 构建 + 测试
+3. **Publish** - NPM 发布（带 provenance）
+4. **Release** - GitHub Release 创建
+5. **Sync** - Marketplace 同步到 dev 分支
+
+---
+
+## 详细步骤
+
+### Step 1: 版本号更新
+
+**自动同步 5 个文件：**
+- `package.json`
+- `.claude-plugin/plugin.json`
+- `.cursor-plugin/plugin.json`
+- `.claude-plugin/marketplace.json`
+- `marketplace.json`
+
+```bash
+node scripts/bump-version.mjs 5.5.41
+```
+
+**验证版本一致性：**
+```bash
+node scripts/bump-version.mjs
+# 输出: ✓ All in sync
+```
+
+### Step 2: 本地验证
+
+```bash
+# TypeScript 类型检查
+tsc --noEmit
+
+# 完整构建
+npm run build
+
+# 运行测试
+npm test
+
+# 预览打包内容
+npm pack --dry-run
+```
+
+### Step 3: 提交变更
+
+```bash
+git add .
+git commit -m "chore: bump version to 5.5.41"
+git push origin dev
+```
+
+### Step 4: 触发发布
+
+```bash
+# 合并到 main 触发 GitHub Actions
+git checkout main
+git merge dev
+git push origin main
+```
+
+### Step 5: 验证发布
+
+```bash
+# 检查 NPM
+npm view @liangjie559567/ultrapower@5.5.41
+
+# 检查 GitHub Release
+gh release view v5.5.41
+
+# 检查 provenance
+npm audit signatures
+```
+
+---
+
+## 高级配置
+
+### NPM Provenance（供应链安全）
+
+**已启用：** 发布时自动添加 `--provenance` 标志
+
+**验证：**
+```bash
+npm audit signatures
+```
+
+**查看 provenance：**
+访问 https://www.npmjs.com/package/@liangjie559567/ultrapower
+查看验证徽章
+
+### GitHub Actions 缓存
+
+**已启用：** 依赖缓存加速 CI/CD
+
+**缓存策略：**
+- 路径：`~/.npm`
+- 键：`${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}`
+- 节省时间：30-60 秒
+
+### Changesets 集成
+
+**当前配置：** 使用 Changesets action 自动化版本管理
+
+**工作流：**
+1. 推送到 main → Changesets 检测变更
+2. 有 changeset → 创建版本 PR
+3. 合并 PR → 自动发布
+
+---
+
+## 故障排查
+
+### 常见问题
+
+**Q: 版本不一致错误**
+```bash
+# 重新同步版本
+node scripts/bump-version.mjs 5.5.41
+```
+
+**Q: 循环依赖错误**
+```bash
+# 检查 package.json dependencies
+# 确保不包含 @liangjie559567/ultrapower
+```
+
+**Q: NPM 发布失败**
+```bash
+# 检查 NPM_TOKEN
+echo $NPM_TOKEN
+
+# 手动发布
+npm publish --access public --provenance
+```
+
+**Q: GitHub Release 失败**
+```bash
+# 手动创建
+gh release create v5.5.41 --generate-notes
+```
+
+### 发布失败恢复
+
+详见 [RELEASE_RECOVERY.md](./RELEASE_RECOVERY.md)
+
+---
+
+## 安全最佳实践
+
+✅ **已实施：**
+- NPM provenance 声明
+- GitHub Actions 权限最小化
+- 短期证书（非长期密钥）
+- 依赖缓存（加速 + 安全）
+
+✅ **版本控制：**
+- 严格 semver 格式验证
+- 5 文件版本同步
+- 循环依赖检测
+
+✅ **发布验证：**
+- 构建前类型检查
+- 测试门禁
+- 打包内容预览
+
+---
+
+## 参考资料
+
+- [NPM Package Provenance](https://github.blog/2023-04-19-introducing-npm-package-provenance)
+- [GitHub Actions Caching](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows)
+- [Changesets Documentation](https://github.com/changesets/changesets)
+- [发布失败恢复指南](./RELEASE_RECOVERY.md)

package/docs/RELEASE_RECOVERY.md

@@ -0,0 +1,84 @@
+# 发布失败恢复指南
+
+## 快速诊断
+
+发布流程的 5 个步骤：
+1. **Preflight** - 版本同步校验
+2. **Validate** - 构建 + 测试
+3. **Publish** - NPM 发布
+4. **Release** - GitHub Release
+5. **Sync** - Marketplace 同步
+
+## 恢复策略
+
+### 场景 1: NPM 发布成功，但后续步骤失败
+
+**症状：** 包已在 npmjs.com 上，但没有 GitHub Release
+
+**恢复步骤：**
+```bash
+# 方案 A: 手动创建 GitHub Release
+gh release create v5.5.40 --generate-notes
+
+# 方案 B: 标记为弃用并重新发布（< 72小时）
+npm deprecate @liangjie559567/ultrapower@5.5.40 "Incomplete release, use 5.5.41"
+node scripts/bump-version.mjs 5.5.41
+npm run build
+npm publish --provenance
+gh release create v5.5.41 --generate-notes
+```
+
+### 场景 2: 发布后发现严重 Bug
+
+**72 小时内且无依赖：**
+```bash
+npm unpublish @liangjie559567/ultrapower@5.5.40
+```
+
+**任何时候（推荐）：**
+```bash
+npm deprecate @liangjie559567/ultrapower@5.5.40 "Critical bug, use 5.5.41"
+node scripts/bump-version.mjs 5.5.41
+npm run build
+npm test
+npm publish --provenance
+```
+
+### 场景 3: 从特定步骤恢复
+
+```bash
+# 从 publish 步骤开始
+node scripts/release-local.mjs --start-from=publish
+
+# 从 release 步骤开始
+node scripts/release-local.mjs --start-from=release
+
+# 从 sync 步骤开始
+node scripts/release-local.mjs --start-from=sync
+```
+
+## 预防措施
+
+### 发布前检查清单
+
+- [ ] 所有测试通过 (`npm test`)
+- [ ] 版本号已更新且一致 (`node scripts/bump-version.mjs`)
+- [ ] 无循环依赖
+- [ ] Git 工作区干净
+- [ ] 本地验证打包内容 (`npm pack --dry-run`)
+
+### Dry-run 测试
+
+```bash
+# 完整 dry-run（不实际执行）
+npm run release:dry-run
+
+# 或
+node scripts/release-local.mjs --dry-run
+```
+
+## 紧急联系
+
+- NPM 包页面: https://www.npmjs.com/package/@liangjie559567/ultrapower
+- GitHub Releases: https://github.com/liangjie559567/ultrapower/releases
+- 问题报告: https://github.com/liangjie559567/ultrapower/issues

package/docs/standards/README.md

@@ -5,7 +5,7 @@
 > **最后更新**: 2026-03-02
 > **真理之源**: `docs/standards/audit-report.md`
 
-ultrapower v5.5.33 具备 49 个 agents、70 个 skills、35 个 hooks 的完整体系。本规范体系从现有代码反向提取，覆盖运行时防护、Hook 执行顺序、状态机、Agent 生命周期、用户使用指南和贡献规范，使 ultrapower 从"能用"升级为"可靠、易用、可扩展"。
+ultrapower v5.5.40 具备 49 个 agents、70 个 skills、35 个 hooks 的完整体系。本规范体系从现有代码反向提取，覆盖运行时防护、Hook 执行顺序、状态机、Agent 生命周期、用户使用指南和贡献规范，使 ultrapower 从"能用"升级为"可靠、易用、可扩展"。
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liangjie559567/ultrapower",
-  "version": "5.5.39",
+  "version": "5.5.41",
   "description": "Disciplined multi-agent orchestration: workflow enforcement + parallel execution",
   "type": "module",
   "main": "dist/index.js",
@@ -57,7 +57,7 @@
     "sync-metadata:verify": "tsx scripts/sync-metadata.ts --verify",
     "sync-metadata:dry-run": "tsx scripts/sync-metadata.ts --dry-run",
     "prepare": "npm run build",
-    "prepublishOnly": "npm run build && npm run compose-docs",
+    "prepublishOnly": "npm run build && npm run compose-docs && npm run sync:marketplace",
     "postinstall": "node scripts/plugin-setup.mjs",
     "release:local": "node scripts/release-local.mjs",
     "release:dry-run": "node scripts/release-local.mjs --dry-run",
@@ -65,10 +65,15 @@
     "validate:versions": "node scripts/validate-versions.mjs",
     "sync:version": "node scripts/sync-version.mjs",
     "sync:version:dry": "node scripts/sync-version.mjs --dry-run",
+    "sync:marketplace": "node scripts/sync-marketplace.mjs",
+    "changeset": "changeset",
+    "version": "changeset version && npm run sync:version && npm run sync:marketplace",
+    "release": "npm run build && npm test && changeset publish",
     "validate:counts": "node scripts/validate-counts.mjs",
     "validate:counts:fix": "node scripts/validate-counts.mjs --fix",
     "check:links": "node scripts/check-links.mjs",
-    "check:links:fix": "node scripts/check-links.mjs --fix"
+    "check:links:fix": "node scripts/check-links.mjs --fix",
+    "validate:plugins": "node scripts/validate-plugin-configs.mjs"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.1.0",
@@ -87,6 +92,7 @@
     "zod": "^3.23.8"
   },
   "devDependencies": {
+    "@changesets/cli": "^2.30.0",
     "@eslint/js": "^9.39.2",
     "@types/node": "^22.19.7",
     "@types/ws": "^8.18.1",

package/scripts/release-steps.mjs

@@ -29,7 +29,7 @@ export async function preflight(opts = {}) {
 export async function validateBuild(opts = {}) {
   const { skipTests = false, dryRun = false } = opts;
   try {
-    run('tsc --noEmit', dryRun);
+    run('npx tsc --noEmit', dryRun);
     run('npm run build', dryRun);
     if (!skipTests) run('npm run test:run', dryRun);
     return { success: true, output: 'Build validation passed' };
@@ -39,10 +39,11 @@ export async function validateBuild(opts = {}) {
 }
 
 export async function publishNpm(opts = {}) {
-  const { dryRun = false, tag = 'latest' } = opts;
+  const { dryRun = false, tag = 'latest', provenance = true } = opts;
   const version = getVersion();
   try {
-    run(`npm publish --access public --tag ${tag}`, dryRun);
+    const provenanceFlag = provenance && process.env.GITHUB_ACTIONS ? '--provenance' : '';
+    run(`npm publish --access public --tag ${tag} ${provenanceFlag}`.trim(), dryRun);
     return { success: true, version };
   } catch (err) {
     return { success: false, version, output: err.message };
@@ -78,6 +79,17 @@ export async function syncMarketplace(opts = {}) {
     if (p.source?.version !== version) { p.source.version = version; changed = true; }
   }
 
+  if (!changed) {
+    console.log('syncMarketplace: versions already in sync');
+    return { success: true };
+  }
+
+  if (dryRun) {
+    console.log('[dry-run] Would update marketplace.json and plugin.json');
+    console.log('[dry-run] Would commit and push to dev');
+    return { success: true };
+  }
+
   // Sync plugin.json
   const pluginPath = resolve('.claude-plugin/plugin.json');
   const plugin = JSON.parse(readFileSync(pluginPath, 'utf-8'));
@@ -93,9 +105,9 @@ export async function syncMarketplace(opts = {}) {
 
   writeFileSync(marketplacePath, JSON.stringify(market, null, 2) + '\n');
   writeFileSync(pluginPath, JSON.stringify(plugin, null, 2) + '\n');
-  run(`git add .claude-plugin/marketplace.json .claude-plugin/plugin.json`, dryRun);
 
   try {
+    run(`git add .claude-plugin/marketplace.json .claude-plugin/plugin.json`, dryRun);
     run(`git commit -m "chore: sync marketplace.json to v${version}"`, dryRun);
     run(`git push origin HEAD:dev`, dryRun);
     console.log(`syncMarketplace: updated to v${version} and pushed to dev`);
@@ -143,7 +155,12 @@ if (cliStep && ['preflight', 'validate', 'publish', 'release', 'sync'].includes(
   const dryRun = process.argv.includes('--dry-run');
   const version = process.env.GITHUB_REF_NAME?.replace(/^v/, '') || undefined;
   const stepMap = { preflight, validate: validateBuild, publish: publishNpm, release: createGithubRelease, sync: syncMarketplace };
-  stepMap[cliStep]({ dryRun, version }).then(r => {
-    if (!r.success) { console.error(`Step ${cliStep} failed: ${r.output ?? ''}`); process.exit(1); }
-  });
+  stepMap[cliStep]({ dryRun, version })
+    .then(r => {
+      if (!r.success) { console.error(`Step ${cliStep} failed: ${r.output ?? ''}`); process.exit(1); }
+    })
+    .catch(err => {
+      console.error(`Step ${cliStep} threw exception: ${err.message}`);
+      process.exit(1);
+    });
 }

package/scripts/sync-marketplace.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from 'fs';
+
+const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
+const marketplace = JSON.parse(readFileSync('.claude-plugin/marketplace.json', 'utf8'));
+const plugin = JSON.parse(readFileSync('.claude-plugin/plugin.json', 'utf8'));
+
+// 同步版本号
+marketplace.plugins[0].version = pkg.version;
+plugin.version = pkg.version;
+
+writeFileSync('.claude-plugin/marketplace.json', JSON.stringify(marketplace, null, 2) + '\n');
+writeFileSync('.claude-plugin/plugin.json', JSON.stringify(plugin, null, 2) + '\n');
+
+console.log(`✅ Marketplace & plugin version synced to ${pkg.version}`);

package/scripts/validate-plugin-configs.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Validate plugin.json files for completeness and consistency
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+
+const REQUIRED_FIELDS = ['name', 'version', 'statusline'];
+const PLUGIN_FILES = [
+  '.claude-plugin/plugin.json',
+  '.cursor-plugin/plugin.json'
+];
+
+let hasErrors = false;
+
+// Read package.json version
+const pkg = JSON.parse(readFileSync('package.json', 'utf-8'));
+const expectedVersion = pkg.version;
+
+console.log(`Validating plugin configs against version ${expectedVersion}\n`);
+
+for (const file of PLUGIN_FILES) {
+  try {
+    const config = JSON.parse(readFileSync(resolve(file), 'utf-8'));
+
+    // Check required fields
+    for (const field of REQUIRED_FIELDS) {
+      if (!config[field]) {
+        console.error(`❌ ${file}: Missing required field "${field}"`);
+        hasErrors = true;
+      }
+    }
+
+    // Check version consistency
+    if (config.version !== expectedVersion) {
+      console.error(`❌ ${file}: Version mismatch (${config.version} !== ${expectedVersion})`);
+      hasErrors = true;
+    }
+
+    // Check statusline config
+    if (config.statusline && (!config.statusline.command || !config.statusline.args)) {
+      console.error(`❌ ${file}: Invalid statusline config`);
+      hasErrors = true;
+    }
+
+    if (!hasErrors) {
+      console.log(`✓ ${file}`);
+    }
+  } catch (err) {
+    console.error(`❌ ${file}: ${err.message}`);
+    hasErrors = true;
+  }
+}
+
+if (hasErrors) {
+  console.error('\n❌ Plugin config validation failed');
+  process.exit(1);
+} else {
+  console.log('\n✅ All plugin configs valid');
+}