rayprism 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# RayPrism
+
+> 面向 AI Agent 工作流的多分支框架模板——选择分支、一键实例化、AI 即刻开工。
+
+## 快速开始
+
+```bash
+# 方式一：npx（免安装，推荐尝鲜）
+npx rayprism init dev my-app
+
+# 方式二：全局安装（长期使用）
+npm install -g rayprism
+rayprism init dev my-app --git
+
+# 进入项目，开始工作
+cd ~/Projects/my-app
+```
+
+> 首次运行会自动从 GitHub 下载模板到 `~/.rayprism/framework/`，后续使用缓存。
+
+## 核心概念
+
+RayPrism 是**框架模板**，不是具体项目。
+
+- `branches/` 下的四个分支模板是**只读的类定义**
+- 通过 `rayprism init` 将模板**实例化**为独立的项目空间
+- 框架升级通过 `rayprism upgrade` 一键完成，不影响项目产出
+
+```
+RayPrism/（框架，只读）          实例化项目（可写）
+========================         ========================
+branches/                        my-app/
+├── pro/                         ├── framework/ → branches/dev/  🔗
+├── content/   rayprism init     ├── .agents/skills/  (合并视图)
+├── dev/       ──────────────→   ├── .claude/rules/   (合并视图)
+└── ops/                         ├── overrides/       (自定义扩展)
+                                 └── workspace/       (所有产出)
+```
+
+## 四个分支
+
+| 分支 | 适合场景 | 主力技能 |
+|------|---------|---------|
+| **pro** | 知识整理 / Obsidian 笔记 | obsidian-markdown, obsidian-bases, json-canvas |
+| **content** | 公众号 / 内容创作 | ray-content-wechat-generating, ray-multi-party-mode |
+| **dev** | 工程开发 / 代码 | ray-util-antigravity-bridging, vercel-react-best-practices |
+| **ops** | 系统运维 / 排障 | tavily-search, agent-browser |
+
+## 项目管理
+
+```bash
+rayprism list              # 查看可用分支
+rayprism projects          # 列出所有已创建项目
+rayprism status            # 查看当前项目信息（在项目目录内）
+rayprism upgrade           # 升级框架到最新版本
+rayprism unregister <name> # 从注册表移除项目
+```
+
+## 安装
+
+```bash
+# npx（免安装）
+npx rayprism <command>
+
+# 全局安装
+npm install -g rayprism
+rayprism <command>
+```
+
+## 框架结构
+
+```
+RayPrism/
+├── package.json           ← npm 包配置
+├── bin/rayprism.js        ← CLI 入口
+├── src/                   ← CLI 源码
+│
+├── README.md              ← 当前文件
+├── AGENTS.md              ← AI Agent 主规则
+├── CLAUDE.md              ← Claude Code 规则入口
+├── GEMINI.md              ← Gemini CLI 规则入口
+│
+├── setup/                 ← 旧版 bash 工具（保留兼容）
+│
+└── branches/              ← 四分支纯净模板（只读）
+    ├── pro/               ← 知识管理 / Obsidian
+    ├── content/           ← 内容创作流水线
+    ├── dev/               ← 工程开发
+    └── ops/               ← 系统运维
+```
+
+## 文档
+
+- [验证清单](setup/checklist.md) — 初始化后的检查项
+
+## License
+
+MIT

package/bin/rayprism.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+/**
+ * rayprism — Multi-branch AI Agent Framework CLI
+ *
+ * Usage:
+ *   rayprism init <branch> <name> [--path /dir] [--git]
+ *   rayprism list
+ *   rayprism projects
+ *   rayprism status
+ *   rayprism upgrade
+ *   rayprism unregister <name>
+ */
+
+import { init } from '../src/commands/init.js';
+import { list } from '../src/commands/list.js';
+import { projects } from '../src/commands/projects.js';
+import { status } from '../src/commands/status.js';
+import { upgrade } from '../src/commands/upgrade.js';
+import { unregister } from '../src/commands/unregister.js';
+import { log } from '../src/utils/logger.js';
+
+const HELP = `
+\x1b[1mrayprism — Multi-branch AI Agent Framework\x1b[0m
+
+命令：
+  rayprism init <branch> <name> [--path /dir] [--git]   初始化新项目
+  rayprism list                                          列出可用分支
+  rayprism projects                                      列出所有已注册项目
+  rayprism status                                        查看当前项目信息
+  rayprism upgrade                                       更新框架符号链接
+  rayprism unregister <name>                             从注册表移除项目
+
+分支: pro | content | dev | ops
+
+示例：
+  npx rayprism init dev my-app
+  npx rayprism init content my-blog --git
+  rayprism list
+  rayprism projects
+`;
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0] || 'help';
+
+  try {
+    switch (command) {
+      case 'init': {
+        const branch = args[1];
+        const name = args[2];
+        if (!branch || !name) {
+          log.err('用法: rayprism init <branch> <name> [--path /dir] [--git]');
+        }
+        const opts = parseInitOpts(args.slice(3));
+        await init(branch, name, opts);
+        break;
+      }
+      case 'list':
+        await list();
+        break;
+      case 'projects':
+        await projects();
+        break;
+      case 'status':
+        await status();
+        break;
+      case 'upgrade':
+        await upgrade();
+        break;
+      case 'unregister': {
+        const name = args[1];
+        if (!name) log.err('用法: rayprism unregister <name>');
+        await unregister(name);
+        break;
+      }
+      case 'help':
+      case '--help':
+      case '-h':
+        console.log(HELP);
+        break;
+      case '--version':
+      case '-v': {
+        const { readFileSync } = await import('node:fs');
+        const { fileURLToPath } = await import('node:url');
+        const { dirname, join } = await import('node:path');
+        const __dirname = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+        console.log(pkg.version);
+        break;
+      }
+      default:
+        log.err(`未知命令: '${command}'。运行 rayprism help 查看帮助`);
+    }
+  } catch (e) {
+    if (e.message?.startsWith('EXIT:')) {
+      process.exit(1);
+    }
+    console.error(e);
+    process.exit(1);
+  }
+}
+
+function parseInitOpts(args) {
+  const opts = { path: '', git: false };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--path' && args[i + 1]) {
+      opts.path = args[++i];
+    } else if (args[i] === '--git') {
+      opts.git = true;
+    }
+  }
+  return opts;
+}
+
+main();

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "rayprism",
+  "version": "0.1.0",
+  "description": "Multi-branch AI Agent framework — one command to scaffold your AI workspace",
+  "bin": {
+    "rayprism": "bin/rayprism.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "keywords": [
+    "ai",
+    "agent",
+    "framework",
+    "scaffold",
+    "cli",
+    "claude",
+    "cursor",
+    "gemini"
+  ],
+  "author": "961882",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/961882/RayPrism.git"
+  },
+  "homepage": "https://github.com/961882/RayPrism"
+}

package/src/commands/init.js

@@ -0,0 +1,362 @@
+/**
+ * rayprism init <branch> <name> [--path /dir] [--git]
+ *
+ * Full port of rp.sh cmd_init logic to Node.js.
+ */
+
+import {
+  existsSync, mkdirSync, symlinkSync, writeFileSync,
+  readFileSync, readdirSync, lstatSync, rmSync, readlinkSync, statSync,
+} from 'node:fs';
+import { join, basename, resolve } from 'node:path';
+import { execSync } from 'node:child_process';
+import { log, C } from '../utils/logger.js';
+import {
+  VALID_BRANCHES, BRANCH_META, BRANCHES_DIR, WORKSPACE_DIR_DESC,
+  DEFAULT_PROJECTS_DIR,
+} from '../utils/constants.js';
+import { ensureFramework, getTemplateVersion } from '../utils/template.js';
+import { registerProject } from '../utils/registry.js';
+
+// ─── Exported helper: link .agents/ .claude/ (merged mode) ──────────
+export function linkHiddenDirs(branch, branchDir, projectDir) {
+  // === .agents/skills/ merge ===
+  const branchSkills = join(branchDir, '.agents', 'skills');
+  if (existsSync(branchSkills)) {
+    const targetSkills = join(projectDir, '.agents', 'skills');
+    mkdirSync(targetSkills, { recursive: true });
+
+    // Remove old framework symlinks (preserve local dirs)
+    if (existsSync(targetSkills)) {
+      for (const item of readdirSync(targetSkills)) {
+        const p = join(targetSkills, item);
+        if (lstatSync(p).isSymbolicLink()) rmSync(p);
+      }
+    }
+
+    // Link framework skills
+    for (const skillName of readdirSync(branchSkills)) {
+      const skillDir = join(branchSkills, skillName);
+      if (!statSync(skillDir).isDirectory()) continue;
+
+      const overridePath = join(projectDir, 'overrides', 'skills', skillName);
+      if (existsSync(overridePath)) {
+        symlinkSync(resolve(overridePath), join(targetSkills, skillName));
+        log.info(`  skills/${skillName} → overrides/ (本地覆盖)`);
+      } else {
+        symlinkSync(resolve(skillDir), join(targetSkills, skillName));
+      }
+    }
+
+    // Link extra override skills
+    const overrideSkillsDir = join(projectDir, 'overrides', 'skills');
+    if (existsSync(overrideSkillsDir)) {
+      for (const skillName of readdirSync(overrideSkillsDir)) {
+        const target = join(targetSkills, skillName);
+        if (!existsSync(target)) {
+          symlinkSync(resolve(join(overrideSkillsDir, skillName)), target);
+        }
+      }
+    }
+
+    log.ok('链接 .agents/skills/（框架 + 覆盖合并）');
+  }
+
+  // === .claude/rules/ merge ===
+  const branchRules = join(branchDir, '.claude', 'rules');
+  if (existsSync(branchRules)) {
+    const targetRules = join(projectDir, '.claude', 'rules');
+    mkdirSync(targetRules, { recursive: true });
+
+    // Remove old framework symlinks
+    if (existsSync(targetRules)) {
+      for (const item of readdirSync(targetRules)) {
+        const p = join(targetRules, item);
+        if (lstatSync(p).isSymbolicLink()) rmSync(p);
+      }
+    }
+
+    // Link framework rules
+    for (const ruleName of readdirSync(branchRules)) {
+      const ruleFile = join(branchRules, ruleName);
+      if (!statSync(ruleFile).isFile()) continue;
+
+      const overridePath = join(projectDir, 'overrides', 'rules', ruleName);
+      if (existsSync(overridePath)) {
+        symlinkSync(resolve(overridePath), join(targetRules, ruleName));
+        log.info(`  rules/${ruleName} → overrides/ (本地覆盖)`);
+      } else {
+        symlinkSync(resolve(ruleFile), join(targetRules, ruleName));
+      }
+    }
+
+    // Link extra override rules
+    const overrideRulesDir = join(projectDir, 'overrides', 'rules');
+    if (existsSync(overrideRulesDir)) {
+      for (const ruleName of readdirSync(overrideRulesDir)) {
+        const target = join(targetRules, ruleName);
+        if (!existsSync(target)) {
+          symlinkSync(resolve(join(overrideRulesDir, ruleName)), target);
+        }
+      }
+    }
+
+    log.ok('链接 .claude/rules/（框架 + 覆盖合并）');
+  }
+}
+
+// ─── Generate AGENTS.md wrapper ─────────────────────────────────────
+function writeAgentsMd(branch, projectName, branchDir, projectDir) {
+  const dirs = BRANCH_META[branch].dirs.split(' ');
+  const dirsTree = dirs.map(d => `├── ${d}/`).join('\n');
+
+  let branchAgents = '';
+  const branchAgentsPath = join(branchDir, 'AGENTS.md');
+  if (existsSync(branchAgentsPath)) {
+    branchAgents = readFileSync(branchAgentsPath, 'utf8')
+      .split('\n')
+      .filter(l => !l.startsWith('# '))
+      .slice(0, 60)
+      .join('\n');
+  }
+
+  const content = `# ${projectName} · AGENTS.md
+
+> 本文件由 \`rayprism init\` 自动生成，适用于 Claude Code / Cursor / Gemini CLI 等 AI 工具。
+
+## ⚠️ 框架只读声明（最高优先级）
+
+\`framework/\` 目录是从 RayPrism \`${branch}\` 分支拉取的只读框架，  
+**禁止修改 \`framework/\` 下的任何文件**。框架升级请运行 \`rayprism upgrade\`。
+
+## 📂 产出目录约束
+
+所有 AI 产出、生成内容、中间文件，**必须写入 \`workspace/\` 目录**，  
+不得在项目根目录随意创建文件。
+
+\`\`\`
+workspace/
+${dirsTree}
+\`\`\`
+
+## 🔧 自定义扩展
+
+项目级规则放在 \`overrides/\` 目录：
+
+- \`overrides/rules/*.md\` — 追加行为约束（自动合并到 .claude/rules/）
+- \`overrides/skills/\` — 项目专属 Skills（自动合并到 .agents/skills/）
+- 同名文件/目录会覆盖框架版本（本地优先）
+
+## 📋 分支规则
+
+本项目使用 **${branch}** 分支规则，详见：
+
+\`\`\`
+framework/AGENTS.md
+\`\`\`
+
+${branchAgents}
+`;
+
+  writeFileSync(join(projectDir, 'AGENTS.md'), content);
+  log.ok('AGENTS.md 已生成（含只读声明 + 覆盖说明 + 框架规则）');
+}
+
+// ─── Main init command ──────────────────────────────────────────────
+export async function init(branch, projectName, opts = {}) {
+  // Validate branch
+  if (!VALID_BRANCHES.includes(branch)) {
+    log.err(`无效分支: '${branch}'。可用: ${VALID_BRANCHES.join(', ')}`);
+  }
+
+  // Ensure templates are downloaded
+  await ensureFramework();
+
+  const branchDir = join(BRANCHES_DIR, branch);
+  if (!existsSync(branchDir)) {
+    log.err(`分支目录不存在: ${branchDir}`);
+  }
+
+  // Determine project path
+  const projectPath = opts.path || join(DEFAULT_PROJECTS_DIR, projectName);
+
+  // Don't overwrite existing
+  if (existsSync(projectPath)) {
+    log.err(`目录已存在: ${projectPath}`);
+  }
+
+  const templateVer = getTemplateVersion(branch);
+
+  // Print banner
+  console.log('');
+  console.log(C.bold('🚀 RayPrism · 初始化新项目'));
+  console.log('══════════════════════════════════');
+  console.log(`  分支类型 : ${branch}  (${BRANCH_META[branch].desc})`);
+  console.log(`  项目名称 : ${projectName}`);
+  console.log(`  项目路径 : ${projectPath}`);
+  console.log(`  框架来源 : ${branchDir}`);
+  console.log(`  模板版本 : v${templateVer}`);
+  if (opts.git) console.log('  Git 初始 : ✅');
+  console.log('');
+
+  mkdirSync(projectPath, { recursive: true });
+
+  // ① framework/ symlink
+  symlinkSync(resolve(branchDir), join(projectPath, 'framework'));
+  log.ok(`framework/ → ${branchDir}`);
+
+  // ② overrides/ 目录
+  mkdirSync(join(projectPath, 'overrides', 'rules'), { recursive: true });
+  mkdirSync(join(projectPath, 'overrides', 'skills'), { recursive: true });
+  writeFileSync(join(projectPath, 'overrides', 'README.md'), OVERRIDES_README);
+  log.ok('overrides/ 目录结构已创建');
+
+  // ③ Link hidden dirs (merge mode)
+  linkHiddenDirs(branch, branchDir, projectPath);
+
+  // ④ Link CLAUDE.md / GEMINI.md
+  for (const f of ['CLAUDE.md', 'GEMINI.md']) {
+    if (existsSync(join(branchDir, f))) {
+      symlinkSync(join('framework', f), join(projectPath, f));
+      log.ok(`链接 ${f}`);
+    }
+  }
+
+  // ⑤ workspace/ directories
+  const dirs = BRANCH_META[branch].dirs.split(' ');
+  for (const d of dirs) {
+    mkdirSync(join(projectPath, 'workspace', d), { recursive: true });
+  }
+  log.ok('workspace/ 目录结构已创建');
+
+  // ⑥ workspace/README.md
+  const tableRows = dirs
+    .map(d => `| \`${d}/\` | ${WORKSPACE_DIR_DESC[d] || '—'} |`)
+    .join('\n');
+  const wsReadme = `# Workspace\n\n所有项目产出放在此目录，框架规则在 \`../framework/\`（只读）。\n\n| 目录 | 用途 |\n|------|------|\n${tableRows}\n`;
+  writeFileSync(join(projectPath, 'workspace', 'README.md'), wsReadme);
+  log.ok('workspace/README.md 已生成');
+
+  // ⑦ AGENTS.md
+  writeAgentsMd(branch, projectName, branchDir, projectPath);
+
+  // ⑧ .rayprism.json
+  const config = {
+    name: projectName,
+    branch,
+    source: branchDir,
+    rayprism_home: resolve(join(BRANCHES_DIR, '..')),
+    template_version: templateVer,
+    created: new Date().toISOString(),
+  };
+  writeFileSync(join(projectPath, '.rayprism.json'), JSON.stringify(config, null, 2));
+  log.ok(`.rayprism.json 元信息已写入（含模板版本 v${templateVer}）`);
+
+  // ⑨ .gitignore
+  writeFileSync(join(projectPath, '.gitignore'), GITIGNORE_CONTENT);
+  log.ok('.gitignore 已创建');
+
+  // ⑩ Register
+  registerProject({
+    name: projectName,
+    branch,
+    path: projectPath,
+    source: branchDir,
+    templateVersion: templateVer,
+  });
+  log.ok('已注册到全局注册表 (~/.rayprism/registry.json)');
+
+  // ⑪ Post-init hook
+  const hookPath = join(branchDir, 'post-init.sh');
+  if (existsSync(hookPath)) {
+    log.info(`执行 ${branch} post-init hook...`);
+    try {
+      execSync(`bash "${hookPath}"`, { cwd: projectPath, stdio: 'inherit' });
+      log.ok('post-init hook 执行完成');
+    } catch {
+      log.warn('post-init hook 执行失败，跳过');
+    }
+  }
+
+  // ⑫ Git init
+  if (opts.git) {
+    log.info('初始化 Git 仓库...');
+    execSync('git init -q', { cwd: projectPath, stdio: 'pipe' });
+    execSync('git add -A', { cwd: projectPath, stdio: 'pipe' });
+    execSync(`git commit -q -m "init: rayprism init ${branch} ${projectName} (v${templateVer})"`, {
+      cwd: projectPath, stdio: 'pipe',
+    });
+    log.ok('Git 仓库已初始化并完成首次提交');
+  }
+
+  // Done
+  console.log('');
+  console.log('══════════════════════════════════');
+  log.ok('项目初始化完成！');
+  console.log('');
+  console.log(`  ${C.bold('下一步：')}`);
+  console.log(`  cd ${projectPath}`);
+  console.log('  用 Cursor / VS Code 打开即可');
+  console.log('');
+  console.log(`  ${C.cyan('产出路径')}   → workspace/`);
+  console.log(`  ${C.yellow('框架路径')}   → framework/（只读，请勿修改）`);
+  console.log(`  ${C.green('自定义扩展')} → overrides/（添加项目专属规则/Skills）`);
+  console.log('');
+}
+
+// ─── Static content ─────────────────────────────────────────────────
+
+const OVERRIDES_README = `# overrides/ — 项目级自定义扩展
+
+此目录用于添加项目特有的规则和 Skills，不影响框架模板。
+
+## 使用方法
+
+### 追加行为规则
+
+在 \`rules/\` 下新建 \`.md\` 文件，会自动合并到 \`.claude/rules/\`：
+
+\`\`\`bash
+cat > overrides/rules/my-project-rule.md << 'EOF'
+---
+description: 项目专属规则
+---
+- 所有报告必须包含数据来源链接
+- 代码注释使用中文
+EOF
+\`\`\`
+
+### 追加项目 Skills
+
+在 \`skills/\` 下新建 skill 目录，会自动合并到 \`.agents/skills/\`：
+
+\`\`\`
+overrides/skills/
+└── my-custom-skill/
+    └── SKILL.md
+\`\`\`
+
+### 覆盖框架版本
+
+如果本地文件与框架同名，本地版本优先（覆盖框架）。
+
+### 生效方式
+
+运行 \`rayprism upgrade\` 会重新合并框架 + overrides，自动生效。
+`;
+
+const GITIGNORE_CONTENT = `# 环境与系统
+.env
+.DS_Store
+
+# 框架符号链接（不跟踪，由 rayprism upgrade 管理）
+framework
+.agents
+.claude
+CLAUDE.md
+GEMINI.md
+
+# 临时产出
+workspace/logs/
+workspace/incidents/
+`;

package/src/commands/list.js

@@ -0,0 +1,31 @@
+/**
+ * rayprism list — Show available branches
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { VALID_BRANCHES, BRANCH_META, BRANCHES_DIR } from '../utils/constants.js';
+import { ensureFramework, getTemplateVersion } from '../utils/template.js';
+import { C } from '../utils/logger.js';
+
+export async function list() {
+  await ensureFramework();
+
+  console.log('');
+  console.log(C.bold('📦 RayPrism 可用分支'));
+  console.log('══════════════════════════════════');
+
+  for (const b of VALID_BRANCHES) {
+    const branchDir = join(BRANCHES_DIR, b);
+    if (existsSync(branchDir)) {
+      const ver = getTemplateVersion(b);
+      console.log(`  ${C.green('●')} ${C.bold(b)} ${C.dim('v' + ver)}   ${BRANCH_META[b].desc}`);
+    } else {
+      console.log(`  ${C.yellow('○')} ${b}   (分支目录未找到)`);
+    }
+  }
+
+  console.log('');
+  console.log('用法: rayprism init <branch> <project-name> [--git]');
+  console.log('');
+}

package/src/commands/projects.js

@@ -0,0 +1,33 @@
+/**
+ * rayprism projects — List all registered projects
+ */
+
+import { existsSync } from 'node:fs';
+import { loadRegistry } from '../utils/registry.js';
+import { C } from '../utils/logger.js';
+
+export async function projects() {
+  const reg = loadRegistry();
+
+  if (reg.projects.length === 0) {
+    console.log('');
+    console.log(C.yellow('暂无已注册的项目'));
+    console.log('运行 rayprism init <branch> <name> 创建第一个项目');
+    console.log('');
+    return;
+  }
+
+  console.log('');
+  console.log(C.bold(`📋 RayPrism 已注册项目 (${reg.projects.length})`));
+  console.log('══════════════════════════════════════════════════════');
+
+  for (const p of reg.projects) {
+    const alive = existsSync(p.path) ? C.green('●') : C.red('○');
+    const ver = p.template_version || '?';
+    const name = p.name.padEnd(20);
+    const branch = p.branch.padEnd(8);
+    console.log(`  ${alive} ${name} ${branch} v${ver.padEnd(6)} ${p.path}`);
+  }
+
+  console.log('');
+}

package/src/commands/status.js

@@ -0,0 +1,71 @@
+/**
+ * rayprism status — Show current project info
+ */
+
+import { existsSync, readFileSync, lstatSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { log, C } from '../utils/logger.js';
+import { getTemplateVersion } from '../utils/template.js';
+
+export async function status() {
+  const configPath = join(process.cwd(), '.rayprism.json');
+  if (!existsSync(configPath)) {
+    log.err('当前目录不是 RayPrism 项目（缺少 .rayprism.json）');
+  }
+
+  const config = JSON.parse(readFileSync(configPath, 'utf8'));
+
+  console.log('');
+  console.log(C.bold('📋 RayPrism 项目信息'));
+  console.log('══════════════════════════════════');
+  console.log(`  项目名称 : ${config.name || '?'}`);
+  console.log(`  分支类型 : ${config.branch || '?'}`);
+  console.log(`  框架来源 : ${config.source || '?'}`);
+  console.log(`  模板版本 : ${config.template_version || '?'}`);
+  console.log(`  创建时间 : ${config.created || '?'}`);
+
+  // Version comparison
+  const currentVer = config.template_version || '?';
+  let latestVer = '?';
+  if (config.source && existsSync(join(config.source, 'VERSION'))) {
+    latestVer = readFileSync(join(config.source, 'VERSION'), 'utf8').trim();
+  }
+
+  console.log('');
+  if (currentVer === latestVer) {
+    console.log(C.green(`  模板版本 : v${currentVer} ✅ 已是最新`));
+  } else {
+    console.log(C.yellow(`  模板版本 : v${currentVer} → v${latestVer} (可运行 rayprism upgrade)`));
+  }
+
+  // Framework symlink
+  console.log('');
+  const fwPath = join(process.cwd(), 'framework');
+  if (existsSync(fwPath) && lstatSync(fwPath).isSymbolicLink()) {
+    const { readlinkSync } = await import('node:fs');
+    const target = readlinkSync(fwPath);
+    console.log(`  ${C.green('framework/')} → ${target}`);
+  } else {
+    console.log(`  ${C.yellow('framework/')} (非符号链接，升级无效)`);
+  }
+
+  // Overrides status
+  const overridesPath = join(process.cwd(), 'overrides');
+  if (existsSync(overridesPath)) {
+    const rulesDir = join(overridesPath, 'rules');
+    const skillsDir = join(overridesPath, 'skills');
+    let ruleCount = 0, skillCount = 0;
+    try {
+      ruleCount = readdirSync(rulesDir).filter(f => f.endsWith('.md')).length;
+    } catch {}
+    try {
+      skillCount = readdirSync(skillsDir).filter((_, i, arr) => {
+        // count directories only
+        return true;
+      }).length;
+    } catch {}
+    console.log(`  ${C.cyan('overrides/')}  规则: ${ruleCount}, Skills: ${skillCount}`);
+  }
+
+  console.log('');
+}

package/src/commands/unregister.js

@@ -0,0 +1,15 @@
+/**
+ * rayprism unregister <name> — Remove project from registry
+ */
+
+import { unregisterProject } from '../utils/registry.js';
+import { log } from '../utils/logger.js';
+
+export async function unregister(name) {
+  const removed = unregisterProject(name);
+  if (removed) {
+    log.ok(`已从注册表移除: ${name}`);
+  } else {
+    log.warn(`注册表中未找到: ${name}`);
+  }
+}

package/src/commands/upgrade.js

@@ -0,0 +1,59 @@
+/**
+ * rayprism upgrade — Update framework symlinks to latest
+ */
+
+import { existsSync, readFileSync, writeFileSync, rmSync, symlinkSync, readdirSync, lstatSync, readlinkSync, mkdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { log, C } from '../utils/logger.js';
+import { ensureFramework, getTemplateVersion } from '../utils/template.js';
+import { BRANCHES_DIR } from '../utils/constants.js';
+import { registerProject } from '../utils/registry.js';
+import { linkHiddenDirs } from './init.js';
+
+export async function upgrade() {
+  const configPath = join(process.cwd(), '.rayprism.json');
+  if (!existsSync(configPath)) {
+    log.err('当前目录不是 RayPrism 项目（缺少 .rayprism.json）');
+  }
+
+  // Force re-download templates
+  await ensureFramework({ force: true });
+
+  const config = JSON.parse(readFileSync(configPath, 'utf8'));
+  const branch = config.branch;
+  const branchDir = join(BRANCHES_DIR, branch);
+  const currentVer = config.template_version || '?';
+  const latestVer = getTemplateVersion(branch);
+
+  if (currentVer === latestVer) {
+    log.info(`模板已是最新版本: v${currentVer}`);
+  } else {
+    log.info(`版本变更: v${currentVer} → v${latestVer}`);
+  }
+
+  // Re-link framework/
+  log.info(`重新链接 framework → ${branchDir}`);
+  const fwPath = join(process.cwd(), 'framework');
+  if (existsSync(fwPath)) rmSync(fwPath, { force: true });
+  symlinkSync(branchDir, fwPath);
+
+  // Re-link hidden dirs
+  linkHiddenDirs(branch, branchDir, process.cwd());
+
+  // Update .rayprism.json
+  config.template_version = latestVer;
+  config.source = branchDir;
+  writeFileSync(configPath, JSON.stringify(config, null, 2));
+  log.ok(`模板版本已更新为 v${latestVer}`);
+
+  // Update registry
+  registerProject({
+    name: config.name,
+    branch,
+    path: process.cwd(),
+    source: branchDir,
+    templateVersion: latestVer,
+  });
+
+  log.ok('框架已更新至最新版本');
+}

package/src/utils/constants.js

@@ -0,0 +1,36 @@
+/**
+ * Branch metadata and path constants
+ */
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// ─── Paths ──────────────────────────────────────────────────────────
+export const RAYPRISM_CACHE = join(homedir(), '.rayprism');
+export const FRAMEWORK_DIR = join(RAYPRISM_CACHE, 'framework');
+export const BRANCHES_DIR = join(FRAMEWORK_DIR, 'branches');
+export const REGISTRY_FILE = join(RAYPRISM_CACHE, 'registry.json');
+export const DEFAULT_PROJECTS_DIR = join(homedir(), 'Projects');
+
+export const GITHUB_REPO = '961882/RayPrism';
+export const GITHUB_TARBALL = `https://github.com/${GITHUB_REPO}/archive/refs/heads/main.tar.gz`;
+
+// ─── Branch definitions ─────────────────────────────────────────────
+export const VALID_BRANCHES = ['pro', 'content', 'dev', 'ops'];
+
+export const BRANCH_META = {
+  pro:     { desc: '专业文档 / 策略规划 / 分析报告',   dirs: 'reports strategy analysis drafts references' },
+  content: { desc: '内容创作 / 公众号 / 社媒运营',     dirs: 'drafts published assets scheduled archive' },
+  dev:     { desc: '软件开发 / 代码 / 架构设计',       dirs: 'src docs tests artifacts experiments' },
+  ops:     { desc: '运维 / 自动化 / 系统管理',         dirs: 'scripts configs runbooks logs incidents' },
+};
+
+export const WORKSPACE_DIR_DESC = {
+  reports: '分析报告', strategy: '策略文档', analysis: '分析草稿',
+  drafts: '草稿、初稿', references: '参考资料', published: '已发布内容',
+  assets: '素材、图片', scheduled: '待发内容', archive: '历史归档',
+  src: '源代码', docs: '文档', tests: '测试',
+  artifacts: '构建产物', experiments: '实验代码',
+  scripts: '自动化脚本', configs: '配置文件', runbooks: '操作手册',
+  logs: '日志记录', incidents: '故障记录', output: '最终产出',
+};

package/src/utils/logger.js

@@ -0,0 +1,21 @@
+/**
+ * Colored terminal logger — zero dependencies
+ */
+
+const C = {
+  green:  s => `\x1b[32m${s}\x1b[0m`,
+  yellow: s => `\x1b[33m${s}\x1b[0m`,
+  cyan:   s => `\x1b[36m${s}\x1b[0m`,
+  red:    s => `\x1b[31m${s}\x1b[0m`,
+  bold:   s => `\x1b[1m${s}\x1b[0m`,
+  dim:    s => `\x1b[2m${s}\x1b[0m`,
+};
+
+export const log = {
+  ok:   msg => console.log(C.green(`✅ ${msg}`)),
+  info: msg => console.log(C.cyan(`ℹ️  ${msg}`)),
+  warn: msg => console.log(C.yellow(`⚠️  ${msg}`)),
+  err:  msg => { console.error(C.red(`❌ ${msg}`)); throw new Error('EXIT:' + msg); },
+};
+
+export { C };

package/src/utils/registry.js

@@ -0,0 +1,46 @@
+/**
+ * Project registry — ~/.rayprism/registry.json
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { REGISTRY_FILE, RAYPRISM_CACHE } from './constants.js';
+
+function ensure() {
+  mkdirSync(RAYPRISM_CACHE, { recursive: true });
+  if (!existsSync(REGISTRY_FILE)) {
+    writeFileSync(REGISTRY_FILE, JSON.stringify({ projects: [] }, null, 2));
+  }
+}
+
+export function loadRegistry() {
+  ensure();
+  return JSON.parse(readFileSync(REGISTRY_FILE, 'utf8'));
+}
+
+export function saveRegistry(reg) {
+  ensure();
+  writeFileSync(REGISTRY_FILE, JSON.stringify(reg, null, 2));
+}
+
+export function registerProject({ name, branch, path, source, templateVersion }) {
+  const reg = loadRegistry();
+  reg.projects = reg.projects.filter(p => p.name !== name);
+  reg.projects.push({
+    name,
+    branch,
+    path,
+    source,
+    template_version: templateVersion,
+    created: new Date().toISOString(),
+  });
+  saveRegistry(reg);
+}
+
+export function unregisterProject(name) {
+  const reg = loadRegistry();
+  const before = reg.projects.length;
+  reg.projects = reg.projects.filter(p => p.name !== name);
+  saveRegistry(reg);
+  return reg.projects.length < before;
+}

package/src/utils/template.js

@@ -0,0 +1,78 @@
+/**
+ * Template download & cache management
+ *
+ * Downloads the RayPrism repo tarball from GitHub and extracts it to
+ * ~/.rayprism/framework/. Supports forced refresh for upgrade.
+ */
+
+import { existsSync, mkdirSync, rmSync, createWriteStream, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { createGunzip } from 'node:zlib';
+import { execSync } from 'node:child_process';
+import { FRAMEWORK_DIR, BRANCHES_DIR, GITHUB_TARBALL, RAYPRISM_CACHE } from './constants.js';
+import { log } from './logger.js';
+
+/**
+ * Ensure framework templates are cached locally.
+ * @param {object} opts
+ * @param {boolean} opts.force - Force re-download even if cached
+ * @returns {string} Path to BRANCHES_DIR
+ */
+export async function ensureFramework({ force = false } = {}) {
+  if (!force && existsSync(BRANCHES_DIR)) {
+    return BRANCHES_DIR;
+  }
+
+  log.info('正在从 GitHub 下载 RayPrism 模板...');
+  mkdirSync(RAYPRISM_CACHE, { recursive: true });
+
+  const tarPath = join(RAYPRISM_CACHE, 'main.tar.gz');
+
+  // Download tarball
+  const res = await fetch(GITHUB_TARBALL, { redirect: 'follow' });
+  if (!res.ok) {
+    log.err(`下载失败: HTTP ${res.status} — ${GITHUB_TARBALL}`);
+  }
+
+  // Save to file
+  const fileStream = createWriteStream(tarPath);
+  await pipeline(res.body, fileStream);
+
+  // Remove old framework dir
+  if (existsSync(FRAMEWORK_DIR)) {
+    rmSync(FRAMEWORK_DIR, { recursive: true, force: true });
+  }
+
+  // Extract using system tar (works on macOS/Linux, simpler than node tar)
+  mkdirSync(FRAMEWORK_DIR, { recursive: true });
+  execSync(`tar -xzf "${tarPath}" --strip-components=1 -C "${FRAMEWORK_DIR}"`, {
+    stdio: 'pipe',
+  });
+
+  // Clean up tarball
+  rmSync(tarPath, { force: true });
+
+  // Write download timestamp
+  const metaPath = join(RAYPRISM_CACHE, 'meta.json');
+  const meta = {
+    downloaded_at: new Date().toISOString(),
+    source: GITHUB_TARBALL,
+  };
+  const { writeFileSync } = await import('node:fs');
+  writeFileSync(metaPath, JSON.stringify(meta, null, 2));
+
+  log.ok('模板下载完成 → ~/.rayprism/framework/');
+  return BRANCHES_DIR;
+}
+
+/**
+ * Get the template version for a branch.
+ */
+export function getTemplateVersion(branch) {
+  const versionFile = join(BRANCHES_DIR, branch, 'VERSION');
+  if (existsSync(versionFile)) {
+    return readFileSync(versionFile, 'utf8').trim();
+  }
+  return '0.0.0';
+}