@yeaft/webchat-agent 0.1.79 → 0.1.81

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/routing.js

@@ -161,7 +161,7 @@ export async function dispatchToRole(session, roleName, content, fromSource, tas
   if (effectiveTaskId && typeof content === 'string') {
     const taskContent = await readTaskFile(session, effectiveTaskId);
     if (taskContent) {
-      content = `${content}\n\n---\n<task-context file="context/features/${effectiveTaskId}.md">\n${taskContent}\n</task-context>`;
+      content = `${content}\n\n---\n<task-context file=".crew/context/features/${effectiveTaskId}.md">\n${taskContent}\n</task-context>`;
     }
   }
 
@@ -169,7 +169,7 @@ export async function dispatchToRole(session, roleName, content, fromSource, tas
   if (typeof content === 'string') {
     const kanbanContent = await readKanban(session);
     if (kanbanContent) {
-      content = `${content}\n\n---\n<kanban file="context/kanban.md">\n${kanbanContent}\n</kanban>`;
+      content = `${content}\n\n---\n<kanban file=".crew/context/kanban.md">\n${kanbanContent}\n</kanban>`;
     }
   }
 

package/crew/task-files.js

@@ -106,7 +106,7 @@ export function parseCompletedTasks(text) {
 }
 
 /**
- * 更新 feature 索引文件 context/features/index.md
+ * 更新 feature 索引文件 .crew/context/features/index.md
  */
 export async function updateFeatureIndex(session) {
   const featuresDir = join(session.sharedDir, 'context', 'features');
@@ -148,7 +148,7 @@ export async function updateFeatureIndex(session) {
 }
 
 /**
- * 追加完成汇总到 context/changelog.md
+ * 追加完成汇总到 .crew/context/changelog.md
  */
 export async function appendChangelog(session, taskId, taskTitle) {
   const contextDir = join(session.sharedDir, 'context');
@@ -218,7 +218,7 @@ export async function saveRoleWorkSummary(session, roleName, accumulatedText) {
 let _kanbanWriteLock = Promise.resolve();
 
 /**
- * 更新工作看板 context/kanban.md
+ * 更新工作看板 .crew/context/kanban.md
  *
  * @param {object} session
  * @param {object} [opts]

package/crew-i18n.js

@@ -87,15 +87,15 @@ ${isDevTeam ? '3' : '2'}. **任务完成** - 所有任务已完成，给出完
 ---END_TASKS---`,
 
     featureRecordTitle: '# Feature 工作记录',
-    featureRecordContent: `系统会自动管理 \`context/features/{task-id}.md\` 工作记录文件：
+    featureRecordContent: `系统会自动管理 \`.crew/context/features/{task-id}.md\` 工作记录文件：
 - PM 分配任务时自动创建文件（包含 task-id、标题、需求描述）
 - 每次 ROUTE 传递时自动追加工作记录（角色名、时间、summary）
 - 你收到的消息中会包含 <task-context> 标签，里面是该任务的完整工作记录
 
 系统还维护以下文件（自动更新，无需手动管理）：
-- \`context/features/index.md\`：所有 feature 的索引（进行中/已完成分类），快速查看项目状态
-- \`context/changelog.md\`：已完成任务的变更记录，每个任务完成时自动追加摘要
-- \`context/kanban.md\`：工作看板，记录每个 feature 的负责人、当前状态和最新进展
+- \`.crew/context/features/index.md\`：所有 feature 的索引（进行中/已完成分类），快速查看项目状态
+- \`.crew/context/changelog.md\`：已完成任务的变更记录，每个任务完成时自动追加摘要
+- \`.crew/context/kanban.md\`：工作看板，记录每个 feature 的负责人、当前状态和最新进展
 你收到的消息中还会包含 <kanban> 标签，里面是工作看板的实时快照。
 你不需要手动创建或更新这些文件，专注于你的本职工作即可。`,
 
@@ -172,8 +172,8 @@ UI/交互方案不确定时找设计师确认。需求不明确时找决策者 "
     teamMembersTitle: '# 团队成员',
     noMembers: '_暂无成员_',
     workConventions: '# 工作约定',
-    workConventionsContent: `- 文档产出写入 context/ 目录
-- 重要决策记录在 context/decisions.md
+    workConventionsContent: `- 文档产出写入 .crew/context/ 目录
+- 重要决策记录在 .crew/context/decisions.md
 - 代码修改使用项目代码路径的绝对路径`,
     stuckRules: '# 卡住上报规则',
     stuckRulesContent: `当你遇到以下情况时，不要自己空转或反复重试，立即 ROUTE 给 PM（pm）请求协调：
@@ -192,11 +192,11 @@ UI/交互方案不确定时找设计师确认。需求不明确时找决策者 "
 - PM 不做 cherry-pick，只负责打 tag
 - 每次新任务/新 feature 必须基于最新的 main 分支创建新的 worktree，确保在最新代码上开发`,
     featureRecordShared: `# Feature 工作记录
-系统自动管理 \`context/features/{task-id}.md\` 工作记录文件：
+系统自动管理 \`.crew/context/features/{task-id}.md\` 工作记录文件：
 - PM 通过 ROUTE 分配任务（带 task + taskTitle 字段）时自动创建
 - 每次角色 ROUTE 传递时自动追加工作记录
 - 角色收到消息时自动注入对应 task 文件内容作为上下文
-- \`context/kanban.md\`：工作看板，记录所有任务的负责人、状态和最新进展
+- \`.crew/context/kanban.md\`：工作看板，记录所有任务的负责人、状态和最新进展
 角色不需要手动创建或更新这些文件。`,
     sharedMemoryTitle: '# 共享记忆',
     sharedMemoryDefault: '_团队共同维护，记录重要的共识、决策和信息。_',
@@ -329,15 +329,15 @@ Important: Do not loop endlessly between roles. When work is substantively compl
 ---END_TASKS---`,
 
     featureRecordTitle: '# Feature Work Records',
-    featureRecordContent: `The system automatically manages \`context/features/{task-id}.md\` work record files:
+    featureRecordContent: `The system automatically manages \`.crew/context/features/{task-id}.md\` work record files:
 - Automatically created when PM assigns tasks (includes task-id, title, requirement description)
 - Work records are appended automatically on each ROUTE handoff (role name, time, summary)
 - Your received messages will include <task-context> tags containing the complete work record for that task
 
 The system also maintains these files (auto-updated, no manual management needed):
-- \`context/features/index.md\`: Index of all features (categorized as in-progress/completed) for quick project status overview
-- \`context/changelog.md\`: Change log of completed tasks, with summary appended when each task completes
-- \`context/kanban.md\`: Work kanban board recording each feature's assignee, current status, and latest progress
+- \`.crew/context/features/index.md\`: Index of all features (categorized as in-progress/completed) for quick project status overview
+- \`.crew/context/changelog.md\`: Change log of completed tasks, with summary appended when each task completes
+- \`.crew/context/kanban.md\`: Work kanban board recording each feature's assignee, current status, and latest progress
 Your received messages will also include <kanban> tags with a real-time snapshot of the work kanban.
 You don't need to manually create or update these files — focus on your core work.`,
 
@@ -414,8 +414,8 @@ After development is complete, send two ROUTE blocks simultaneously to ${revName
     teamMembersTitle: '# Team Members',
     noMembers: '_No members yet_',
     workConventions: '# Work Conventions',
-    workConventionsContent: `- Write documentation output to context/ directory
-- Record important decisions in context/decisions.md
+    workConventionsContent: `- Write documentation output to .crew/context/ directory
+- Record important decisions in .crew/context/decisions.md
 - Use the project code path (absolute path) for code changes`,
     stuckRules: '# Escalation Rules',
     stuckRulesContent: `When you encounter the following situations, do not spin or retry repeatedly — immediately ROUTE to PM (pm) for coordination:
@@ -434,11 +434,11 @@ When escalating, explain: what task you're working on, where you're stuck, and w
 - PM doesn't cherry-pick, only manages tags
 - Each new task/feature must create a new worktree based on the latest main branch to ensure development on latest code`,
     featureRecordShared: `# Feature Work Records
-The system automatically manages \`context/features/{task-id}.md\` work record files:
+The system automatically manages \`.crew/context/features/{task-id}.md\` work record files:
 - Automatically created when PM assigns tasks via ROUTE (with task + taskTitle fields)
 - Work records are appended on each role ROUTE handoff
 - Task file content is auto-injected as context when a role receives a message
-- \`context/kanban.md\`: Work kanban board recording all tasks' assignees, statuses, and latest progress
+- \`.crew/context/kanban.md\`: Work kanban board recording all tasks' assignees, statuses, and latest progress
 Roles don't need to manually create or update these files.`,
     sharedMemoryTitle: '# Shared Memory',
     sharedMemoryDefault: '_Team-maintained shared knowledge, decisions, and information._',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.79",
+  "version": "0.1.81",
   "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);
+  }
+}