@yeaft/webchat-agent 0.1.78 → 0.1.80

package/conversation.js

@@ -3,6 +3,8 @@ import { loadSessionHistory } from './history.js';
 import { startClaudeQuery } from './claude.js';
 import { crewSessions, loadCrewIndex } from './crew.js';
 import { rolePlaySessions, saveRolePlayIndex, removeRolePlaySession, loadRolePlayIndex, validateRolePlayConfig, initRolePlayRouteState, loadCrewContext, refreshCrewContext, initCrewContextMtimes } from './roleplay.js';
+import { initRolePlayDir, writeSessionClaudeMd, generateSessionName, getDefaultRoles, getSessionDir } from './roleplay-dir.js';
+import { addRolePlaySession, findRolePlaySessionByConversationId, setActiveRolePlaySession } from './roleplay-session.js';
 
 // Restore persisted roleplay sessions on module load (agent startup)
 loadRolePlayIndex();
@@ -149,16 +151,71 @@ export async function createConversation(msg) {
     }
   }
 
-  console.log(`Creating conversation: ${conversationId} in ${effectiveWorkDir} (lazy start)`);
+  // ★ RolePlay: initialize .roleplay/ directory, generate session, set cwd
+  let rpSessionName = null;
+  let rpSessionWorkDir = effectiveWorkDir; // default: project root
+  if (rolePlayConfig) {
+    try {
+      const language = rolePlayConfig.language || 'zh-CN';
+
+      // 1. Ensure .roleplay/ directory structure exists
+      await initRolePlayDir(effectiveWorkDir, language);
+
+      // 2. Generate unique session name
+      rpSessionName = generateSessionName(
+        effectiveWorkDir,
+        rolePlayConfig.teamType,
+        msg.rolePlayConfig?.sessionName || null
+      );
+
+      // 3. Write session CLAUDE.md (role list, ROUTE protocol, workflow)
+      await writeSessionClaudeMd(effectiveWorkDir, rpSessionName, {
+        teamType: rolePlayConfig.teamType,
+        language,
+        roles: rolePlayConfig.roles,
+      });
+
+      // 4. Set cwd to session directory so Claude Code auto-reads its CLAUDE.md
+      rpSessionWorkDir = getSessionDir(effectiveWorkDir, rpSessionName);
+
+      // 5. Build roles snapshot for session.json
+      const rolesSnapshot = (rolePlayConfig.roles && rolePlayConfig.roles.length > 0)
+        ? rolePlayConfig.roles.map(r => ({
+            name: r.name,
+            displayName: r.displayName || r.name,
+            icon: r.icon || '',
+          }))
+        : getDefaultRoles(rolePlayConfig.teamType, language);
+
+      // 6. Persist to .roleplay/session.json
+      await addRolePlaySession(effectiveWorkDir, {
+        name: rpSessionName,
+        teamType: rolePlayConfig.teamType,
+        language,
+        projectDir: effectiveWorkDir,
+        conversationId,
+        roles: rolesSnapshot,
+        createdAt: Date.now(),
+      });
+
+      console.log(`  RolePlay: initialized .roleplay/${rpSessionName}, cwd=${rpSessionWorkDir}`);
+    } catch (e) {
+      console.error('[createConversation] Failed to init .roleplay/ dir:', e);
+      // Non-fatal: fall back to project root as cwd
+      rpSessionWorkDir = effectiveWorkDir;
+    }
+  }
+
+  console.log(`Creating conversation: ${conversationId} in ${rpSessionWorkDir} (lazy start)`);
   if (username) console.log(`  User: ${username} (${userId})`);
-  if (rolePlayConfig) console.log(`  RolePlay: teamType=${rolePlayConfig.teamType}, roles=${rolePlayConfig.roles?.length}`);
+  if (rolePlayConfig) console.log(`  RolePlay: teamType=${rolePlayConfig.teamType}, roles=${rolePlayConfig.roles?.length}, session=${rpSessionName}`);
 
   // 只创建 conversation 状态，不启动 Claude 进程
   // Claude 进程会在用户发送第一条消息时启动 (见 handleUserInput)
   ctx.conversations.set(conversationId, {
     query: null,
     inputStream: null,
-    workDir: effectiveWorkDir,
+    workDir: rpSessionWorkDir,
     claudeSessionId: null,
     createdAt: Date.now(),
     abortController: null,
@@ -169,6 +226,9 @@ export async function createConversation(msg) {
     username,
     disallowedTools: disallowedTools || null,  // null = 使用全局默认
     rolePlayConfig: rolePlayConfig || null,
+    // Track the original project dir and session name for .roleplay/ operations
+    _rpProjectDir: rolePlayConfig ? effectiveWorkDir : null,
+    _rpSessionName: rpSessionName,
     usage: {
       inputTokens: 0,
       outputTokens: 0,
@@ -198,7 +258,7 @@ export async function createConversation(msg) {
   ctx.sendToServer({
     type: 'conversation_created',
     conversationId,
-    workDir: effectiveWorkDir,
+    workDir: rpSessionWorkDir,
     userId,
     username,
     disallowedTools: disallowedTools || null,
@@ -260,6 +320,21 @@ export async function resumeConversation(msg) {
     ? { roles: rolePlayEntry.roles, teamType: rolePlayEntry.teamType, language: rolePlayEntry.language }
     : null;
 
+  // ★ RolePlay resume: look up session in .roleplay/session.json to restore cwd
+  let rpResumeWorkDir = effectiveWorkDir;
+  if (rolePlayConfig && rolePlayEntry) {
+    const rpProjectDir = rolePlayEntry.projectDir || effectiveWorkDir;
+    const rpDiskSession = findRolePlaySessionByConversationId(rpProjectDir, conversationId);
+    if (rpDiskSession && rpDiskSession.name) {
+      rpResumeWorkDir = getSessionDir(rpProjectDir, rpDiskSession.name);
+      // Re-activate the session
+      setActiveRolePlaySession(rpProjectDir, rpDiskSession.name).catch(e => {
+        console.warn('[Resume] Failed to update activeSession:', e.message);
+      });
+      console.log(`[Resume] RolePlay: restored session cwd=${rpResumeWorkDir}`);
+    }
+  }
+
   // ★ RolePlay resume: refresh .crew context to get latest kanban/features
   if (rolePlayConfig && rolePlayEntry) {
     const crewContext = loadCrewContext(effectiveWorkDir);
@@ -274,7 +349,7 @@ export async function resumeConversation(msg) {
   ctx.conversations.set(conversationId, {
     query: null,
     inputStream: null,
-    workDir: effectiveWorkDir,
+    workDir: rpResumeWorkDir,
     claudeSessionId: claudeSessionId,  // 保存要恢复的 session ID
     createdAt: Date.now(),
     abortController: null,

package/crew/session.js

@@ -6,7 +6,7 @@ import { join, isAbsolute } from 'path';
 import ctx from '../context.js';
 import { getMessages } from '../crew-i18n.js';
 import { initWorktrees } from './worktree.js';
-import { initSharedDir, writeRoleClaudeMd, updateSharedClaudeMd } from './shared-dir.js';
+import { initSharedDir, writeRoleClaudeMd, updateSharedClaudeMd, backupMemoryContent } from './shared-dir.js';
 import {
   loadCrewIndex, upsertCrewIndex, removeFromCrewIndex,
   loadSessionMeta, saveSessionMeta, loadSessionMessages, getMaxShardIndex
@@ -366,6 +366,9 @@ export async function handleDeleteCrewDir(msg) {
   if (!isValidProjectDir(projectDir)) return;
   const crewDir = join(projectDir, '.crew');
   try {
+    // 提取并备份记忆内容（删除前）
+    await backupMemoryContent(crewDir);
+
     // 删除 Crew 模板定义
     await fs.rm(join(crewDir, 'CLAUDE.md'), { force: true }).catch(() => {});
     await fs.rm(join(crewDir, 'roles'), { recursive: true, force: true }).catch(() => {});

package/crew/shared-dir.js

@@ -4,13 +4,98 @@
  */
 import { promises as fs } from 'fs';
 import { join } from 'path';
-import { getMessages } from '../crew-i18n.js';
+import { getMessages, getAllMemoryTitles } from '../crew-i18n.js';
 
 /** Format role label: "icon displayName" or just "displayName" if no icon */
 function roleLabel(r) {
   return r.icon ? `${r.icon} ${r.displayName}` : r.displayName;
 }
 
+const MEMORY_BACKUP_FILE = '.memory-backup.json';
+
+/**
+ * Extract user-written content after a memory section title.
+ * Searches for any known locale's title (e.g. "# 共享记忆" or "# Shared Memory"),
+ * returns the trimmed content after the title line until EOF or next top-level heading.
+ * Returns null if section not found or content is only the default placeholder.
+ */
+function extractMemorySection(fileContent, titles, defaults) {
+  for (const title of titles) {
+    const idx = fileContent.indexOf(title);
+    if (idx === -1) continue;
+    // Content starts after the title line
+    const afterTitle = fileContent.slice(idx + title.length);
+    // Find next top-level heading (# at start of line) — that's where memory ends
+    const nextHeading = afterTitle.search(/\n#\s/);
+    const raw = nextHeading === -1 ? afterTitle : afterTitle.slice(0, nextHeading);
+    const trimmed = raw.trim();
+    // Skip if empty or is just the default placeholder
+    if (!trimmed) return null;
+    for (const d of defaults) {
+      if (trimmed === d.trim()) return null;
+    }
+    return trimmed;
+  }
+  return null;
+}
+
+/**
+ * Backup memory content from .crew/CLAUDE.md and .crew/roles/*/CLAUDE.md
+ * before deletion. Writes .crew/.memory-backup.json.
+ */
+export async function backupMemoryContent(crewDir) {
+  const { sharedTitles, sharedDefaults, personalTitles, personalDefaults } = getAllMemoryTitles();
+  const backup = { shared: null, roles: {} };
+
+  // Extract shared memory from .crew/CLAUDE.md
+  try {
+    const sharedContent = await fs.readFile(join(crewDir, 'CLAUDE.md'), 'utf-8');
+    backup.shared = extractMemorySection(sharedContent, sharedTitles, sharedDefaults);
+  } catch { /* CLAUDE.md doesn't exist — skip */ }
+
+  // Extract personal memory from each role's CLAUDE.md
+  try {
+    const rolesDir = join(crewDir, 'roles');
+    const roleDirs = await fs.readdir(rolesDir);
+    for (const roleName of roleDirs) {
+      try {
+        const roleClaudeMd = await fs.readFile(join(rolesDir, roleName, 'CLAUDE.md'), 'utf-8');
+        const memory = extractMemorySection(roleClaudeMd, personalTitles, personalDefaults);
+        if (memory) {
+          backup.roles[roleName] = memory;
+        }
+      } catch { /* Role dir or file missing — skip */ }
+    }
+  } catch { /* roles/ doesn't exist — skip */ }
+
+  // Only write backup if there's something to preserve
+  if (backup.shared || Object.keys(backup.roles).length > 0) {
+    await fs.writeFile(join(crewDir, MEMORY_BACKUP_FILE), JSON.stringify(backup, null, 2));
+    console.log(`[Crew] Memory backup saved: shared=${!!backup.shared}, roles=${Object.keys(backup.roles).join(',') || 'none'}`);
+  }
+}
+
+/**
+ * Load memory backup from .crew/.memory-backup.json, returns null if not found.
+ */
+async function loadMemoryBackup(sharedDir) {
+  try {
+    const data = await fs.readFile(join(sharedDir, MEMORY_BACKUP_FILE), 'utf-8');
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Delete memory backup file after successful restore.
+ */
+async function cleanupMemoryBackup(sharedDir) {
+  try {
+    await fs.rm(join(sharedDir, MEMORY_BACKUP_FILE), { force: true });
+  } catch { /* ignore */ }
+}
+
 /**
  * 初始化共享目录
  */
@@ -27,6 +112,9 @@ export async function initSharedDir(sharedDir, roles, projectDir, language = 'zh
 
   // 生成 .crew/CLAUDE.md（共享级）
   await writeSharedClaudeMd(sharedDir, roles, projectDir, language);
+
+  // 清理记忆备份文件（已在 write 阶段恢复）
+  await cleanupMemoryBackup(sharedDir);
 }
 
 /**
@@ -52,6 +140,10 @@ export async function initRoleDir(sharedDir, role, language = 'zh-CN', allRoles
 export async function writeSharedClaudeMd(sharedDir, roles, projectDir, language = 'zh-CN') {
   const m = getMessages(language);
 
+  // Check for memory backup to restore
+  const backup = await loadMemoryBackup(sharedDir);
+  const sharedMemoryContent = (backup && backup.shared) ? backup.shared : m.sharedMemoryDefault;
+
   const claudeMd = `${m.projectGoal}
 
 ${m.projectCodePath}
@@ -73,7 +165,7 @@ ${m.worktreeRulesContent}
 ${m.featureRecordShared}
 
 ${m.sharedMemoryTitle}
-${m.sharedMemoryDefault}
+${sharedMemoryContent}
 `;
 
   await fs.writeFile(join(sharedDir, 'CLAUDE.md'), claudeMd);
@@ -129,6 +221,12 @@ export async function writeRoleClaudeMd(sharedDir, role, language = 'zh-CN', all
   const roleDir = join(sharedDir, 'roles', role.name);
   const m = getMessages(language);
 
+  // Check for memory backup to restore
+  const backup = await loadMemoryBackup(sharedDir);
+  const personalMemoryContent = (backup && backup.roles && backup.roles[role.name])
+    ? backup.roles[role.name]
+    : m.personalMemoryDefault;
+
   // Resolve generic ROUTE targets to actual instance names
   const resolvedClaudeMd = resolveRouteTargets(role.claudeMd || role.description, role, allRoles);
 
@@ -147,7 +245,7 @@ ${m.codeWorkDirNote}
 
   claudeMd += `
 ${m.personalMemory}
-${m.personalMemoryDefault}
+${personalMemoryContent}
 `;
 
   await fs.writeFile(join(roleDir, 'CLAUDE.md'), claudeMd);

package/crew-i18n.js

@@ -498,3 +498,23 @@ Roles don't need to manually create or update these files.`,
 export function getMessages(language) {
   return messages[language] || messages['zh-CN'];
 }
+
+/**
+ * Get all memory-related titles and defaults across all locales.
+ * Used to detect and extract user-written memory content regardless of language.
+ * @returns {{ sharedTitles: string[], sharedDefaults: string[], personalTitles: string[], personalDefaults: string[] }}
+ */
+export function getAllMemoryTitles() {
+  const sharedTitles = [];
+  const sharedDefaults = [];
+  const personalTitles = [];
+  const personalDefaults = [];
+  for (const lang of Object.keys(messages)) {
+    const m = messages[lang];
+    if (m.sharedMemoryTitle) sharedTitles.push(m.sharedMemoryTitle);
+    if (m.sharedMemoryDefault) sharedDefaults.push(m.sharedMemoryDefault);
+    if (m.personalMemory) personalTitles.push(m.personalMemory);
+    if (m.personalMemoryDefault) personalDefaults.push(m.personalMemoryDefault);
+  }
+  return { sharedTitles, sharedDefaults, personalTitles, personalDefaults };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.78",
+  "version": "0.1.80",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/roleplay-dir.js

@@ -0,0 +1,301 @@
+/**
+ * RolePlay — .roleplay/ directory and CLAUDE.md management.
+ *
+ * Analogous to agent/crew/shared-dir.js but for the single-process
+ * RolePlay collaboration mode.
+ *
+ * Directory structure:
+ *   .roleplay/
+ *   ├── CLAUDE.md              (shared instructions, inherited by all sessions)
+ *   ├── session.json           (session index)
+ *   ├── roles/                 (one subdirectory per session)
+ *   │   └── {session-name}/
+ *   │       └── CLAUDE.md      (Claude Code cwd points here)
+ *   └── context/
+ *       ├── kanban.md
+ *       └── features/
+ */
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import { existsSync, readdirSync } from 'fs';
+import { getRolePlayMessages } from './roleplay-i18n.js';
+
+// ─── Team type → default role set mapping ───────────────────────────
+// Each entry is a list of role names (keys into roleTemplates in i18n).
+const TEAM_ROLES = {
+  dev:     ['pm', 'dev', 'reviewer', 'tester'],
+  writing: ['planner', 'writer', 'editor'],
+  trading: ['strategist', 'analyst', 'macro', 'risk', 'trader'],
+  video:   ['director', 'scriptwriter', 'storyboard'],
+  custom:  ['pm', 'dev', 'reviewer', 'tester'], // default same as dev
+};
+
+// ─── Session name constraints ───────────────────────────────────────
+const SESSION_NAME_RE = /^[a-z0-9-]+$/;
+const MAX_SESSION_NAME_LEN = 64;
+
+/**
+ * Generate a session directory name.
+ *
+ * Format: `{teamType}-{customName|"team"}-{YYYYMMDD}[-{seq}]`
+ *
+ * If a session with the same name already exists under .roleplay/roles/,
+ * a sequence number is appended (e.g. `-2`, `-3`).
+ *
+ * @param {string} projectDir - absolute path to project root
+ * @param {string} teamType - dev | writing | trading | video | custom
+ * @param {string} [customName] - user-provided name (optional)
+ * @returns {string} unique session name
+ */
+export function generateSessionName(projectDir, teamType, customName) {
+  const now = new Date();
+  const datePart = [
+    now.getFullYear(),
+    String(now.getMonth() + 1).padStart(2, '0'),
+    String(now.getDate()).padStart(2, '0'),
+  ].join('');
+
+  const namePart = sanitizeNamePart(customName) || 'team';
+  const base = `${teamType}-${namePart}-${datePart}`;
+
+  // Check for duplicates under .roleplay/roles/
+  const rolesDir = join(projectDir, '.roleplay', 'roles');
+  const existing = new Set();
+  if (existsSync(rolesDir)) {
+    try {
+      for (const d of readdirSync(rolesDir, { withFileTypes: true })) {
+        if (d.isDirectory()) existing.add(d.name);
+      }
+    } catch {
+      // permission error — treat as empty
+    }
+  }
+
+  if (!existing.has(base)) return base;
+
+  // Append sequence number
+  for (let seq = 2; seq <= 999; seq++) {
+    const candidate = `${base}-${seq}`;
+    if (!existing.has(candidate)) return candidate;
+  }
+
+  // Extremely unlikely: fall back to timestamp suffix
+  return `${base}-${Date.now()}`;
+}
+
+/**
+ * Sanitize user-provided name part:
+ *  - lowercase
+ *  - replace non-alphanumeric with hyphens
+ *  - collapse consecutive hyphens
+ *  - trim leading/trailing hyphens
+ *  - enforce max length
+ *
+ * Returns empty string if input is empty/invalid.
+ */
+function sanitizeNamePart(raw) {
+  if (!raw || typeof raw !== 'string') return '';
+  let s = raw.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+  if (s.length > 30) s = s.substring(0, 30).replace(/-$/, '');
+  return SESSION_NAME_RE.test(s) ? s : '';
+}
+
+// ─── Directory initialization ───────────────────────────────────────
+
+/**
+ * Ensure .roleplay/ directory structure exists.
+ * Creates the top-level dirs if absent, writes shared CLAUDE.md
+ * only on first creation (preserves user edits after that).
+ *
+ * @param {string} projectDir - absolute path to project root
+ * @param {string} [language='zh-CN']
+ */
+export async function initRolePlayDir(projectDir, language = 'zh-CN') {
+  const rpDir = join(projectDir, '.roleplay');
+
+  await fs.mkdir(rpDir, { recursive: true });
+  await fs.mkdir(join(rpDir, 'roles'), { recursive: true });
+  await fs.mkdir(join(rpDir, 'context'), { recursive: true });
+  await fs.mkdir(join(rpDir, 'context', 'features'), { recursive: true });
+
+  // Write shared CLAUDE.md only if it doesn't exist
+  const sharedMdPath = join(rpDir, 'CLAUDE.md');
+  try {
+    await fs.access(sharedMdPath);
+    // Already exists — don't overwrite (user may have edited it)
+  } catch {
+    await writeRolePlaySharedClaudeMd(projectDir, language);
+  }
+}
+
+/**
+ * Write (or overwrite) .roleplay/CLAUDE.md — the shared-level instructions
+ * inherited by all sessions via Claude Code's CLAUDE.md lookup chain.
+ *
+ * @param {string} projectDir
+ * @param {string} [language='zh-CN']
+ */
+export async function writeRolePlaySharedClaudeMd(projectDir, language = 'zh-CN') {
+  const m = getRolePlayMessages(language);
+  const rpDir = join(projectDir, '.roleplay');
+
+  const content = `${m.sharedTitle}
+
+${m.projectPath}
+${projectDir}
+${m.useAbsolutePath}
+
+${m.workMode}
+${m.workModeContent}
+
+${m.workConventions}
+${m.workConventionsContent}
+
+${m.crewRelation}
+${m.crewRelationContent}
+
+${m.sharedMemory}
+${m.sharedMemoryDefault}
+`;
+
+  await fs.writeFile(join(rpDir, 'CLAUDE.md'), content);
+}
+
+// ─── Session CLAUDE.md generation ───────────────────────────────────
+
+/**
+ * Write .roleplay/roles/{sessionName}/CLAUDE.md — session-level config.
+ *
+ * This file is the core configuration that Claude Code reads automatically
+ * (cwd is set to this directory). It contains:
+ *  - Session metadata (name, teamType, language)
+ *  - Full role list with descriptions (generated from teamType or custom roles)
+ *  - ROUTE protocol reference
+ *  - Workflow for this team type
+ *  - Project path reference
+ *  - Session memory section
+ *
+ * @param {string} projectDir - project root
+ * @param {string} sessionName - session directory name
+ * @param {object} config - { teamType, language, roles?, projectDir? }
+ *   - config.roles: optional custom role array from RolePlay config.
+ *     If provided and non-empty, these are used instead of default team roles.
+ *     Each role: { name, displayName, icon?, description?, claudeMd? }
+ */
+export async function writeSessionClaudeMd(projectDir, sessionName, config) {
+  const { teamType = 'dev', language = 'zh-CN', roles: customRoles } = config;
+  const m = getRolePlayMessages(language);
+
+  const sessionDir = join(projectDir, '.roleplay', 'roles', sessionName);
+  await fs.mkdir(sessionDir, { recursive: true });
+
+  // Build role list section
+  const roleSection = buildRoleSection(teamType, language, customRoles);
+
+  // Build workflow section
+  const workflow = (teamType === 'dev')
+    ? m.devWorkflow
+    : m.genericWorkflow;
+
+  const content = `${m.sessionTitle(sessionName)}
+
+${m.teamTypeLabel}
+${teamType}
+
+${m.languageLabel}
+${language}
+
+${m.roleListTitle}
+
+${roleSection}
+
+${m.routeProtocol}
+
+${m.workflowTitle}
+
+${workflow}
+
+${m.projectPathTitle}
+${projectDir}
+${m.useAbsolutePath}
+
+${m.sessionMemory}
+${m.sessionMemoryDefault}
+`;
+
+  await fs.writeFile(join(sessionDir, 'CLAUDE.md'), content);
+}
+
+/**
+ * Build the role list section for a session CLAUDE.md.
+ *
+ * Strategy:
+ *  1. If custom roles are provided (from RolePlay config), use them directly.
+ *     For each custom role, look up a matching roleTemplate for extra detail,
+ *     but prefer the custom role's claudeMd/description if provided.
+ *  2. Otherwise, use the default role set for the teamType from TEAM_ROLES.
+ */
+function buildRoleSection(teamType, language, customRoles) {
+  const m = getRolePlayMessages(language);
+  const templates = m.roleTemplates;
+
+  if (customRoles && customRoles.length > 0) {
+    return customRoles.map(r => {
+      const tmpl = templates[r.name];
+      // Prefer custom claudeMd, then custom description, then template
+      const body = r.claudeMd || r.description || (tmpl ? tmpl.content : '');
+      const heading = tmpl
+        ? tmpl.heading
+        : `## ${r.icon || ''} ${r.displayName || r.name} (${r.name})`.replace(/\s{2,}/g, ' ');
+      return `${heading}\n${body}`;
+    }).join('\n\n');
+  }
+
+  // Default: use TEAM_ROLES mapping
+  const roleNames = TEAM_ROLES[teamType] || TEAM_ROLES.dev;
+  return roleNames.map(name => {
+    const tmpl = templates[name];
+    if (!tmpl) return `## ${name}\n(No template available)`;
+    return `${tmpl.heading}\n${tmpl.content}`;
+  }).join('\n\n');
+}
+
+/**
+ * Get the default role list for a team type.
+ * Used by session creation to populate session.json roles snapshot.
+ *
+ * @param {string} teamType
+ * @param {string} language
+ * @returns {Array<{name: string, displayName: string, icon: string}>}
+ */
+export function getDefaultRoles(teamType, language = 'zh-CN') {
+  const m = getRolePlayMessages(language);
+  const templates = m.roleTemplates;
+  const roleNames = TEAM_ROLES[teamType] || TEAM_ROLES.dev;
+
+  return roleNames.map(name => {
+    const tmpl = templates[name];
+    if (!tmpl) return { name, displayName: name, icon: '' };
+
+    // Extract icon and displayName from heading: "## 📋 PM-乔布斯 (pm)"
+    const headingMatch = tmpl.heading.match(/^##\s*(\S+)\s+(.+?)\s*\((\w+)\)\s*$/);
+    if (headingMatch) {
+      return {
+        name: headingMatch[3],
+        displayName: headingMatch[2],
+        icon: headingMatch[1],
+      };
+    }
+    return { name, displayName: name, icon: '' };
+  });
+}
+
+/**
+ * Get the session directory path.
+ * @param {string} projectDir
+ * @param {string} sessionName
+ * @returns {string} absolute path to .roleplay/roles/{sessionName}/
+ */
+export function getSessionDir(projectDir, sessionName) {
+  return join(projectDir, '.roleplay', 'roles', sessionName);
+}

package/roleplay-i18n.js

@@ -0,0 +1,445 @@
+/**
+ * RolePlay i18n — localized template strings for .roleplay/ directory files.
+ *
+ * Separated from crew-i18n.js because RolePlay CLAUDE.md templates have
+ * different structure (single-process, no worktree rules, session-scoped).
+ *
+ * Supported languages: 'zh-CN' (default), 'en'
+ */
+
+const messages = {
+  'zh-CN': {
+    // ── .roleplay/CLAUDE.md (shared level) ──
+    sharedTitle: '# RolePlay 共享指令',
+    projectPath: '# 项目路径',
+    useAbsolutePath: '所有代码操作请使用此绝对路径。',
+    workMode: '# 工作模式',
+    workModeContent: `RolePlay 是单进程多角色协作模式。一个 Claude 实例依次扮演不同角色，通过 ROUTE 协议切换。
+与 Crew（多进程、每角色独立 Claude 实例）的区别：
+- 所有角色共享同一个上下文窗口
+- 角色切换是即时的（无需跨进程通信）
+- 适合轻量级协作和快速迭代`,
+    workConventions: '# 工作约定',
+    workConventionsContent: `- 文档产出写入 .roleplay/context/ 目录
+- 代码修改使用项目路径的绝对路径
+- 每个角色专注自己的职责，不越界`,
+    crewRelation: '# 与 .crew 的关系',
+    crewRelationContent: `- .roleplay/context/ 可以读取 .crew/context/ 的内容
+- .crew 的共享记忆和看板对 RolePlay 可见
+- RolePlay 不修改 .crew/ 的任何内容（只读）`,
+    sharedMemory: '# 共享记忆',
+    sharedMemoryDefault: '_所有 session 共同维护，记录项目级的共识和决策。_',
+
+    // ── .roleplay/roles/{session}/CLAUDE.md (session level) ──
+    sessionTitle: (name) => `# RolePlay Session: ${name}`,
+    teamTypeLabel: '# 团队类型',
+    languageLabel: '# 语言',
+    roleListTitle: '# 角色列表',
+
+    // Role templates per teamType
+    roleTemplates: {
+      pm: {
+        heading: '## 📋 PM-乔布斯 (pm)',
+        content: `你是 PM-乔布斯。你的职责：
+- 分析用户需求，理解意图
+- 将需求拆分为可执行的开发任务
+- 定义验收标准
+- 最终验收开发成果
+
+风格：简洁、注重用户价值、善于抓住本质。`,
+      },
+      dev: {
+        heading: '## 💻 开发者-托瓦兹 (dev)',
+        content: `你是开发者-托瓦兹。你的职责：
+- 设计技术方案和架构
+- 使用工具（Read, Edit, Write, Bash）实现代码
+- 确保代码质量和可维护性
+- 修复 reviewer 和 tester 提出的问题
+
+风格：追求代码简洁优雅，重视性能和可维护性。不写废话，直接动手。`,
+      },
+      reviewer: {
+        heading: '## 🔍 审查者-马丁 (reviewer)',
+        content: `你是审查者-马丁。你的职责：
+- 仔细审查开发者的代码变更
+- 检查：代码风格、命名规范、架构合理性、边界情况、安全漏洞
+- 如果有问题，明确指出并说明修改建议
+- 确认通过后明确说"LGTM"
+
+风格：严格但友善，注重最佳实践，善于发现潜在问题。`,
+      },
+      tester: {
+        heading: '## 🧪 测试者-贝克 (tester)',
+        content: `你是测试者-贝克。你的职责：
+- 使用 Bash 工具运行测试
+- 验证功能是否按预期工作
+- 检查边界情况和异常处理
+- 如果有 bug，明确描述复现步骤
+
+风格：测试驱动思维，善于发现边界情况，追求可靠性。`,
+      },
+      designer: {
+        heading: '## 🎨 设计师-拉姆斯 (designer)',
+        content: `你是设计师-拉姆斯。你的职责：
+- 设计用户交互流程和页面布局
+- 确保视觉一致性和用户体验
+- 输出设计方案给开发者实现
+
+风格：Less but better，追求极致简洁。`,
+      },
+      // Writing team
+      planner: {
+        heading: '## 📋 策划-曹雪芹 (planner)',
+        content: `你是策划-曹雪芹。你的职责：
+- 制定整体创作方向和大纲
+- 审核内容质量和一致性
+- 做出关键创作决策
+
+风格：注重故事内核，善于把控整体节奏。`,
+      },
+      writer: {
+        heading: '## ✍️ 执笔师-鲁迅 (writer)',
+        content: `你是执笔师-鲁迅。你的职责：
+- 根据大纲撰写具体内容
+- 把控文字质量和风格一致性
+- 按照设计师的节奏方案写作
+
+风格：文字犀利，善于用细节打动人。`,
+      },
+      editor: {
+        heading: '## 📝 审稿师 (editor)',
+        content: `你是审稿师。你的职责：
+- 审核文字质量、逻辑一致性
+- 检查错别字、语法、标点
+- 确认内容符合整体方向
+
+风格：严谨细致，注重可读性。`,
+      },
+      // Trading team
+      strategist: {
+        heading: '## 📋 策略师 (strategist)',
+        content: `你是策略师。你的职责：
+- 综合技术分析和宏观研究做出交易决策
+- 管理整体仓位和风险敞口
+- 协调团队分析方向
+
+风格：冷静理性，注重概率思维。`,
+      },
+      analyst: {
+        heading: '## 📊 技术分析师 (analyst)',
+        content: `你是技术分析师。你的职责：
+- 分析价格走势和技术指标
+- 识别关键支撑/阻力位
+- 提供入场/出场信号
+
+风格：数据驱动，图表说话。`,
+      },
+      macro: {
+        heading: '## 🌐 宏观研究员 (macro)',
+        content: `你是宏观研究员。你的职责：
+- 分析宏观经济数据和政策
+- 评估市场情绪和资金流向
+- 提供宏观背景判断
+
+风格：视野开阔，善于关联不同市场。`,
+      },
+      risk: {
+        heading: '## 🛡️ 风控 (risk)',
+        content: `你是风控。你的职责：
+- 审查交易方案的风险
+- 设定止损和仓位限制
+- 监控已有持仓风险
+
+风格：保守谨慎，底线思维。`,
+      },
+      trader: {
+        heading: '## 💰 交易员 (trader)',
+        content: `你是交易员。你的职责：
+- 执行策略师的交易决策
+- 选择最优执行时机和方式
+- 报告执行结果
+
+风格：执行力强，反应迅速。`,
+      },
+      // Video team
+      director: {
+        heading: '## 🎬 导演 (director)',
+        content: `你是导演。你的职责：
+- 把控整体视觉叙事方向
+- 审核脚本和分镜
+- 做出最终创意决策
+
+风格：注重视觉叙事，善于把控节奏。`,
+      },
+      scriptwriter: {
+        heading: '## ✏️ 编剧 (scriptwriter)',
+        content: `你是编剧。你的职责：
+- 撰写视频脚本和旁白
+- 构建叙事结构
+- 设计情节转折
+
+风格：善于讲故事，注重情感共鸣。`,
+      },
+      storyboard: {
+        heading: '## 🖼️ 分镜师 (storyboard)',
+        content: `你是分镜师。你的职责：
+- 将脚本转化为视觉分镜
+- 设计镜头语言和转场
+- 确保视觉连贯性
+
+风格：视觉思维，善于用画面讲故事。`,
+      },
+    },
+
+    routeProtocol: `# ROUTE 协议
+
+当一个角色完成工作需要交给另一个角色时，使用 ROUTE 块：
+
+---ROUTE---
+to: {目标角色name}
+summary: {交接内容摘要}
+task: {任务ID}（可选）
+taskTitle: {任务标题}（可选）
+---END_ROUTE---
+
+规则：
+- \`to\` 必须是有效的角色 name，或 \`human\` 表示需要用户输入
+- 一次可以输出多个 ROUTE 块
+- ROUTE 块必须在角色输出的末尾
+- 切换后必须完全以该角色的视角和人格思考和行动`,
+
+    workflowTitle: '# 工作流程',
+    devWorkflow: `1. **PM** 分析需求，拆分任务，确定验收标准
+2. **开发者** 实现代码（使用工具读写文件）
+3. **审查者** Code Review（不通过 → 返回开发者修复）
+4. **测试者** 运行测试 & 验证（有 bug → 返回开发者修复）
+5. **PM** 验收总结`,
+    genericWorkflow: '按角色顺序依次完成任务。',
+
+    projectPathTitle: '# 项目路径',
+
+    sessionMemory: '# Session 记忆',
+    sessionMemoryDefault: '_本 session 的工作记录、决策和待办事项。_',
+  },
+
+  'en': {
+    // ── .roleplay/CLAUDE.md (shared level) ──
+    sharedTitle: '# RolePlay Shared Instructions',
+    projectPath: '# Project Path',
+    useAbsolutePath: 'Use this absolute path for all code operations.',
+    workMode: '# Work Mode',
+    workModeContent: `RolePlay is a single-process multi-role collaboration mode. One Claude instance plays different roles in sequence, switching via the ROUTE protocol.
+Differences from Crew (multi-process, each role has its own Claude instance):
+- All roles share the same context window
+- Role switching is instant (no cross-process communication)
+- Suitable for lightweight collaboration and rapid iteration`,
+    workConventions: '# Work Conventions',
+    workConventionsContent: `- Write documentation output to .roleplay/context/ directory
+- Use absolute project path for code changes
+- Each role focuses on its own responsibilities`,
+    crewRelation: '# Relationship with .crew',
+    crewRelationContent: `- .roleplay/context/ can read .crew/context/ content
+- .crew shared memory and kanban are visible to RolePlay
+- RolePlay does not modify anything in .crew/ (read-only)`,
+    sharedMemory: '# Shared Memory',
+    sharedMemoryDefault: '_Maintained by all sessions, recording project-level consensus and decisions._',
+
+    // ── .roleplay/roles/{session}/CLAUDE.md (session level) ──
+    sessionTitle: (name) => `# RolePlay Session: ${name}`,
+    teamTypeLabel: '# Team Type',
+    languageLabel: '# Language',
+    roleListTitle: '# Role List',
+
+    roleTemplates: {
+      pm: {
+        heading: '## 📋 PM-Jobs (pm)',
+        content: `You are PM-Jobs. Your responsibilities:
+- Analyze user requirements and understand intent
+- Break down requirements into executable tasks
+- Define acceptance criteria
+- Final acceptance of deliverables
+
+Style: Concise, user-value focused, excellent at grasping the essence.`,
+      },
+      dev: {
+        heading: '## 💻 Dev-Torvalds (dev)',
+        content: `You are Dev-Torvalds. Your responsibilities:
+- Design technical solutions and architecture
+- Use tools (Read, Edit, Write, Bash) to implement code
+- Ensure code quality and maintainability
+- Fix issues raised by reviewer and tester
+
+Style: Pursue clean, elegant code. Value performance and maintainability. No fluff, just code.`,
+      },
+      reviewer: {
+        heading: '## 🔍 Reviewer-Martin (reviewer)',
+        content: `You are Reviewer-Martin. Your responsibilities:
+- Carefully review code changes from the developer
+- Check: code style, naming conventions, architecture, edge cases, security
+- If issues found, clearly point them out with fix suggestions
+- When approved, explicitly say "LGTM"
+
+Style: Strict but kind, focused on best practices, good at spotting potential issues.`,
+      },
+      tester: {
+        heading: '## 🧪 Tester-Beck (tester)',
+        content: `You are Tester-Beck. Your responsibilities:
+- Use Bash tool to run tests
+- Verify functionality works as expected
+- Check edge cases and error handling
+- If bugs found, clearly describe reproduction steps
+
+Style: Test-driven thinking, good at finding edge cases, pursuing reliability.`,
+      },
+      designer: {
+        heading: '## 🎨 Designer-Rams (designer)',
+        content: `You are Designer-Rams. Your responsibilities:
+- Design user interaction flows and page layouts
+- Ensure visual consistency and user experience
+- Deliver design specs for developer implementation
+
+Style: Less but better, pursuing ultimate simplicity.`,
+      },
+      planner: {
+        heading: '## 📋 Planner (planner)',
+        content: `You are the Planner. Your responsibilities:
+- Set overall creative direction and outline
+- Review content quality and consistency
+- Make key creative decisions
+
+Style: Focus on story core, good at pacing control.`,
+      },
+      writer: {
+        heading: '## ✍️ Writer (writer)',
+        content: `You are the Writer. Your responsibilities:
+- Write specific content based on the outline
+- Maintain writing quality and style consistency
+- Follow the designer's pacing plan
+
+Style: Sharp writing, good at using details to move people.`,
+      },
+      editor: {
+        heading: '## 📝 Editor (editor)',
+        content: `You are the Editor. Your responsibilities:
+- Review writing quality, logical consistency
+- Check typos, grammar, punctuation
+- Confirm content aligns with overall direction
+
+Style: Rigorous and detailed, focused on readability.`,
+      },
+      strategist: {
+        heading: '## 📋 Strategist (strategist)',
+        content: `You are the Strategist. Your responsibilities:
+- Synthesize technical analysis and macro research for trading decisions
+- Manage overall positions and risk exposure
+- Coordinate team analysis direction
+
+Style: Calm and rational, probability-focused thinking.`,
+      },
+      analyst: {
+        heading: '## 📊 Technical Analyst (analyst)',
+        content: `You are the Technical Analyst. Your responsibilities:
+- Analyze price trends and technical indicators
+- Identify key support/resistance levels
+- Provide entry/exit signals
+
+Style: Data-driven, charts speak.`,
+      },
+      macro: {
+        heading: '## 🌐 Macro Researcher (macro)',
+        content: `You are the Macro Researcher. Your responsibilities:
+- Analyze macroeconomic data and policies
+- Assess market sentiment and fund flows
+- Provide macro context judgment
+
+Style: Broad perspective, good at connecting different markets.`,
+      },
+      risk: {
+        heading: '## 🛡️ Risk Manager (risk)',
+        content: `You are the Risk Manager. Your responsibilities:
+- Review trading plan risks
+- Set stop-loss and position limits
+- Monitor existing position risk
+
+Style: Conservative, bottom-line thinking.`,
+      },
+      trader: {
+        heading: '## 💰 Trader (trader)',
+        content: `You are the Trader. Your responsibilities:
+- Execute strategist's trading decisions
+- Choose optimal execution timing and method
+- Report execution results
+
+Style: Strong execution, quick reactions.`,
+      },
+      director: {
+        heading: '## 🎬 Director (director)',
+        content: `You are the Director. Your responsibilities:
+- Control overall visual narrative direction
+- Review scripts and storyboards
+- Make final creative decisions
+
+Style: Visual storytelling, good at pacing control.`,
+      },
+      scriptwriter: {
+        heading: '## ✏️ Scriptwriter (scriptwriter)',
+        content: `You are the Scriptwriter. Your responsibilities:
+- Write video scripts and narration
+- Build narrative structure
+- Design plot twists
+
+Style: Good storytelling, focused on emotional resonance.`,
+      },
+      storyboard: {
+        heading: '## 🖼️ Storyboard Artist (storyboard)',
+        content: `You are the Storyboard Artist. Your responsibilities:
+- Convert scripts into visual storyboards
+- Design camera language and transitions
+- Ensure visual continuity
+
+Style: Visual thinking, good at telling stories with images.`,
+      },
+    },
+
+    routeProtocol: `# ROUTE Protocol
+
+When a role finishes work and needs to hand off to another role, use a ROUTE block:
+
+---ROUTE---
+to: {target_role_name}
+summary: {handoff content summary}
+task: {task ID} (optional)
+taskTitle: {task title} (optional)
+---END_ROUTE---
+
+Rules:
+- \`to\` must be a valid role name, or \`human\` for user input
+- Multiple ROUTE blocks can be output at once
+- ROUTE blocks must be at the end of role output
+- After switching, fully think and act from that role's perspective`,
+
+    workflowTitle: '# Workflow',
+    devWorkflow: `1. **PM** analyzes requirements, breaks down tasks, defines acceptance criteria
+2. **Dev** implements code (using tools to read/write files)
+3. **Reviewer** code review (if fails → back to Dev)
+4. **Tester** runs tests & verifies (if bugs → back to Dev)
+5. **PM** acceptance & summary`,
+    genericWorkflow: 'Complete tasks by following the role sequence.',
+
+    projectPathTitle: '# Project Path',
+
+    sessionMemory: '# Session Memory',
+    sessionMemoryDefault: '_Work records, decisions, and to-do items for this session._',
+  }
+};
+
+/**
+ * Get RolePlay i18n messages for the given language.
+ * Falls back to 'zh-CN' for unknown languages.
+ *
+ * @param {string} language
+ * @returns {object}
+ */
+export function getRolePlayMessages(language) {
+  return messages[language] || messages['zh-CN'];
+}

package/roleplay-session.js

@@ -0,0 +1,184 @@
+/**
+ * RolePlay Session — session index management for .roleplay/session.json.
+ *
+ * Analogous to agent/crew/session.js but much simpler:
+ * - No multi-process concerns (single process)
+ * - No worktree management
+ * - Atomic write for crash safety
+ *
+ * session.json schema:
+ * {
+ *   sessions: [{ name, teamType, language, projectDir, conversationId,
+ *                roles, createdAt, updatedAt, status }],
+ *   activeSession: string | null
+ * }
+ */
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import { existsSync, readFileSync, writeFileSync, renameSync } from 'fs';
+
+const SESSION_FILE = 'session.json';
+
+// ─── Read / Write ───────────────────────────────────────────────────
+
+/**
+ * Load .roleplay/session.json.
+ * Returns { sessions: [], activeSession: null } if file doesn't exist or is corrupt.
+ *
+ * @param {string} projectDir
+ * @returns {{ sessions: Array, activeSession: string|null }}
+ */
+export function loadRolePlaySessionIndex(projectDir) {
+  const filePath = join(projectDir, '.roleplay', SESSION_FILE);
+  if (!existsSync(filePath)) {
+    return { sessions: [], activeSession: null };
+  }
+  try {
+    const raw = readFileSync(filePath, 'utf-8');
+    const data = JSON.parse(raw);
+    return {
+      sessions: Array.isArray(data.sessions) ? data.sessions : [],
+      activeSession: data.activeSession || null,
+    };
+  } catch (e) {
+    console.warn('[RolePlaySession] Failed to load session.json:', e.message);
+    return { sessions: [], activeSession: null };
+  }
+}
+
+/**
+ * Save .roleplay/session.json atomically (write tmp → rename).
+ *
+ * @param {string} projectDir
+ * @param {{ sessions: Array, activeSession: string|null }} data
+ */
+export async function saveRolePlaySessionIndex(projectDir, data) {
+  const rpDir = join(projectDir, '.roleplay');
+  const filePath = join(rpDir, SESSION_FILE);
+  const tmpPath = `${filePath}.tmp.${Date.now()}`;
+
+  const content = JSON.stringify(data, null, 2);
+  try {
+    await fs.mkdir(rpDir, { recursive: true });
+    await fs.writeFile(tmpPath, content);
+    await fs.rename(tmpPath, filePath);
+  } catch (e) {
+    console.error('[RolePlaySession] Failed to save session.json:', e.message);
+    // Clean up tmp file if rename failed
+    try { await fs.unlink(tmpPath); } catch {}
+    throw e;
+  }
+}
+
+// ─── Session CRUD ───────────────────────────────────────────────────
+
+/**
+ * Add a new session entry to .roleplay/session.json.
+ * Sets it as the activeSession.
+ *
+ * @param {string} projectDir
+ * @param {object} session - session entry to add:
+ *   { name, teamType, language, projectDir, conversationId, roles, createdAt }
+ * @returns {object} the session entry with updatedAt/status fields added
+ */
+export async function addRolePlaySession(projectDir, session) {
+  const index = loadRolePlaySessionIndex(projectDir);
+
+  // Check for duplicate session name
+  const existing = index.sessions.find(s => s.name === session.name);
+  if (existing) {
+    // Update existing entry instead of creating duplicate
+    Object.assign(existing, {
+      ...session,
+      updatedAt: Date.now(),
+      status: 'active',
+    });
+    index.activeSession = session.name;
+    await saveRolePlaySessionIndex(projectDir, index);
+    return existing;
+  }
+
+  const entry = {
+    ...session,
+    updatedAt: Date.now(),
+    status: 'active',
+  };
+
+  index.sessions.push(entry);
+  index.activeSession = session.name;
+  await saveRolePlaySessionIndex(projectDir, index);
+  return entry;
+}
+
+/**
+ * Remove (archive) a session from .roleplay/session.json.
+ * The session entry is marked as 'archived', not deleted,
+ * so the context/ directory content remains valid.
+ *
+ * Optionally removes the session's roles/ directory.
+ *
+ * @param {string} projectDir
+ * @param {string} sessionName
+ * @param {object} [options]
+ * @param {boolean} [options.removeDir=true] - remove .roleplay/roles/{sessionName}/
+ */
+export async function removeRolePlaySession(projectDir, sessionName, options = {}) {
+  const { removeDir = true } = options;
+  const index = loadRolePlaySessionIndex(projectDir);
+
+  const session = index.sessions.find(s => s.name === sessionName);
+  if (session) {
+    session.status = 'archived';
+    session.updatedAt = Date.now();
+  }
+
+  // Clear activeSession if it was the removed one
+  if (index.activeSession === sessionName) {
+    // Pick next active session (most recently updated non-archived)
+    const active = index.sessions
+      .filter(s => s.status === 'active')
+      .sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
+    index.activeSession = active[0]?.name || null;
+  }
+
+  await saveRolePlaySessionIndex(projectDir, index);
+
+  // Remove the session directory (but keep context/)
+  if (removeDir) {
+    const sessionDir = join(projectDir, '.roleplay', 'roles', sessionName);
+    try {
+      await fs.rm(sessionDir, { recursive: true, force: true });
+    } catch {
+      // Not critical — may not exist
+    }
+  }
+}
+
+/**
+ * Find a session entry by conversationId.
+ *
+ * @param {string} projectDir
+ * @param {string} conversationId
+ * @returns {object|null} session entry or null
+ */
+export function findRolePlaySessionByConversationId(projectDir, conversationId) {
+  if (!conversationId) return null;
+  const index = loadRolePlaySessionIndex(projectDir);
+  return index.sessions.find(s => s.conversationId === conversationId) || null;
+}
+
+/**
+ * Update the activeSession pointer and updatedAt timestamp.
+ *
+ * @param {string} projectDir
+ * @param {string} sessionName
+ */
+export async function setActiveRolePlaySession(projectDir, sessionName) {
+  const index = loadRolePlaySessionIndex(projectDir);
+  const session = index.sessions.find(s => s.name === sessionName);
+  if (session) {
+    session.updatedAt = Date.now();
+    index.activeSession = sessionName;
+    await saveRolePlaySessionIndex(projectDir, index);
+  }
+}