diff --git a/ccw/src/core/websocket.ts b/ccw/src/core/websocket.ts index 97917cde..4c28733b 100644 --- a/ccw/src/core/websocket.ts +++ b/ccw/src/core/websocket.ts @@ -67,13 +67,9 @@ const THROTTLE_CONFIG = new Map key !== 'LOOP_COMPLETED' as any) + ] as const ); -// Add LOOP_COMPLETED separately to avoid type issues -THROTTLE_CONFIG.set('LOOP_COMPLETED', { interval: 0, category: 'immediate' }); - /** Per-message-type throttle tracking */ const throttleState = new Map(); @@ -563,36 +559,6 @@ export function parseWebSocketFrame(buffer: Buffer): { opcode: number; payload: return { opcode, payload: payload.toString('utf8'), frameLength }; } -/** - * Create WebSocket frame - */ -export function createWebSocketFrame(data: unknown): Buffer { - const payload = Buffer.from(JSON.stringify(data), 'utf8'); - const length = payload.length; - - let frame; - if (length <= 125) { - frame = Buffer.alloc(2 + length); - frame[0] = 0x81; // Text frame, FIN - frame[1] = length; - payload.copy(frame, 2); - } else if (length <= 65535) { - frame = Buffer.alloc(4 + length); - frame[0] = 0x81; - frame[1] = 126; - frame.writeUInt16BE(length, 2); - payload.copy(frame, 4); - } else { - frame = Buffer.alloc(10 + length); - frame[0] = 0x81; - frame[1] = 127; - frame.writeBigUInt64BE(BigInt(length), 2); - payload.copy(frame, 10); - } - - return frame; -} - /** * Extract session ID from file path */ diff --git a/ccw/src/tools/cli-history-store.ts b/ccw/src/tools/cli-history-store.ts index ac062d9c..f1079c0c 100644 --- a/ccw/src/tools/cli-history-store.ts +++ b/ccw/src/tools/cli-history-store.ts @@ -267,53 +267,37 @@ export class CliHistoryStore { const hasProjectRoot = tableInfo.some(col => col.name === 'project_root'); const hasRelativePath = tableInfo.some(col => col.name === 'relative_path'); + // Silent migrations - only log warnings/errors if (!hasCategory) { - console.log('[CLI History] Migrating database: adding category column...'); - this.db.exec(` - ALTER TABLE conversations ADD COLUMN category TEXT DEFAULT 'user'; - `); - // Create index separately to handle potential errors + this.db.exec(`ALTER TABLE conversations ADD COLUMN category TEXT DEFAULT 'user';`); try { this.db.exec(`CREATE INDEX IF NOT EXISTS idx_conversations_category ON conversations(category);`); } catch (indexErr) { console.warn('[CLI History] Category index creation warning:', (indexErr as Error).message); } - console.log('[CLI History] Migration complete: category column added'); } if (!hasParentExecutionId) { - console.log('[CLI History] Migrating database: adding parent_execution_id column...'); - this.db.exec(` - ALTER TABLE conversations ADD COLUMN parent_execution_id TEXT; - `); + this.db.exec(`ALTER TABLE conversations ADD COLUMN parent_execution_id TEXT;`); try { this.db.exec(`CREATE INDEX IF NOT EXISTS idx_conversations_parent ON conversations(parent_execution_id);`); } catch (indexErr) { console.warn('[CLI History] Parent execution index creation warning:', (indexErr as Error).message); } - console.log('[CLI History] Migration complete: parent_execution_id column added'); } // Add hierarchical storage support columns if (!hasProjectRoot) { - console.log('[CLI History] Migrating database: adding project_root column for hierarchical storage...'); - this.db.exec(` - ALTER TABLE conversations ADD COLUMN project_root TEXT; - `); + this.db.exec(`ALTER TABLE conversations ADD COLUMN project_root TEXT;`); try { this.db.exec(`CREATE INDEX IF NOT EXISTS idx_conversations_project_root ON conversations(project_root);`); } catch (indexErr) { console.warn('[CLI History] Project root index creation warning:', (indexErr as Error).message); } - console.log('[CLI History] Migration complete: project_root column added'); } if (!hasRelativePath) { - console.log('[CLI History] Migrating database: adding relative_path column for hierarchical storage...'); - this.db.exec(` - ALTER TABLE conversations ADD COLUMN relative_path TEXT; - `); - console.log('[CLI History] Migration complete: relative_path column added'); + this.db.exec(`ALTER TABLE conversations ADD COLUMN relative_path TEXT;`); } // Add missing timestamp index for turns table (for time-based queries) @@ -324,9 +308,7 @@ export class CliHistoryStore { `).get(); if (!indexExists) { - console.log('[CLI History] Adding missing timestamp index to turns table...'); this.db.exec(`CREATE INDEX IF NOT EXISTS idx_turns_timestamp ON turns(timestamp DESC);`); - console.log('[CLI History] Migration complete: turns timestamp index added'); } } catch (indexErr) { console.warn('[CLI History] Turns timestamp index creation warning:', (indexErr as Error).message); @@ -353,15 +335,11 @@ export class CliHistoryStore { } } - // Batch migration - only output log if there are columns to migrate + // Batch migration - silent if (missingTurnsColumns.length > 0) { - console.log(`[CLI History] Migrating turns table: adding ${missingTurnsColumns.length} columns (${missingTurnsColumns.join(', ')})...`); - for (const col of missingTurnsColumns) { this.db.exec(`ALTER TABLE turns ADD COLUMN ${col} ${turnsColumnDefs[col]};`); } - - console.log('[CLI History] Migration complete: turns table updated'); } // Add transaction_id column to native_session_mapping table for concurrent session disambiguation @@ -369,16 +347,12 @@ export class CliHistoryStore { const hasTransactionId = mappingInfo.some(col => col.name === 'transaction_id'); if (!hasTransactionId) { - console.log('[CLI History] Migrating database: adding transaction_id column to native_session_mapping...'); - this.db.exec(` - ALTER TABLE native_session_mapping ADD COLUMN transaction_id TEXT; - `); + this.db.exec(`ALTER TABLE native_session_mapping ADD COLUMN transaction_id TEXT;`); try { this.db.exec(`CREATE INDEX IF NOT EXISTS idx_native_transaction_id ON native_session_mapping(transaction_id);`); } catch (indexErr) { console.warn('[CLI History] Transaction ID index creation warning:', (indexErr as Error).message); } - console.log('[CLI History] Migration complete: transaction_id column added'); } } catch (err) { console.error('[CLI History] Migration error:', (err as Error).message); diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 867925c0..b56bd27d 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -75,8 +75,7 @@ export default withMermaid(defineConfig({ { text: 'Guide', link: '/guide/ch01-what-is-claude-dms3' }, { text: 'Commands', link: '/commands/claude/' }, { text: 'Skills', link: '/skills/' }, - { text: 'Features', link: '/features/spec' }, - { text: 'Components', link: '/components/' } + { text: 'Features', link: '/features/spec' } ], // Sidebar - 优化导航结构，增加二级标题和归类 @@ -423,7 +422,6 @@ export default withMermaid(defineConfig({ { text: '命令', link: '/zh/commands/claude/' }, { text: '技能', link: '/zh/skills/claude-index' }, { text: '功能', link: '/zh/features/spec' }, - { text: '组件', link: '/zh/components/' }, { text: '参考', link: '/zh/reference/commands-skills' } ], sidebar: { diff --git a/docs/.vitepress/theme/styles/custom.css b/docs/.vitepress/theme/styles/custom.css index 0ff9fed4..05505b07 100644 --- a/docs/.vitepress/theme/styles/custom.css +++ b/docs/.vitepress/theme/styles/custom.css @@ -1,7 +1,7 @@ /** * VitePress Custom Styles * Overrides and extensions for default VitePress theme - * Design System: ui-ux-pro-max — dark-mode-first, developer-focused + * Design System: ui-ux-pro-max — flat design, developer-focused, documentation-optimized */ /* ============================================ @@ -33,10 +33,14 @@ --vp-custom-block-danger-border: #fecaca; --vp-custom-block-danger-text: #b91c1c; - /* Layout Width Adjustments */ + /* Layout Width - Wider content area */ --vp-layout-max-width: 1600px; - --vp-content-width: 1000px; - --vp-sidebar-width: 272px; + --vp-content-width: 920px; + --vp-sidebar-width: 280px; + --vp-toc-width: 200px; + + /* Prose width for optimal readability */ + --vp-prose-width: 820px; } .dark { @@ -55,12 +59,9 @@ /* ============================================ * Layout Container Adjustments + * Use CSS variables in :root to control layout widths + * Do not override VitePress layout calculations with !important * ============================================ */ -.VPDoc .content-container, -.VPDoc.has-aside .content-container { - max-width: 90% !important; - padding: 0 32px; -} /* Adjust sidebar and content layout */ /* NOTE: Removed duplicate padding-left - VitePress already handles sidebar layout */ @@ -77,6 +78,18 @@ padding: 4px 8px; } +/* ============================================ + * Navigation Bar Border + * ============================================ */ +.VPNav { + border-bottom: 1px solid var(--vp-c-divider); +} + +/* ============================================ + * Desktop Layout Adjustments + * Grid-based layout is defined in mobile.css @media (min-width: 1024px) + * ============================================ */ + /* ============================================ * Home Page Override * ============================================ */ @@ -97,6 +110,12 @@ max-width: 100vw; } +/* Home page navbar - reduce title left margin since no sidebar */ +.Layout:has(.pro-home) .VPNavBar .content-body, +.Layout:has(.pro-home) .VPNavBar .title { + padding-left: 0 !important; +} + /* Ensure VPFooter doesn't cause overflow */ .Layout:has(.pro-home) .VPFooter { max-width: 100vw; @@ -136,54 +155,111 @@ /* ============================================ * Documentation Content Typography + * Optimized for readability (65-75 chars per line) * ============================================ */ +.vp-doc { + font-family: var(--vp-font-family-base); + line-height: var(--vp-line-height-relaxed); + color: var(--vp-c-text-1); +} + +/* Heading hierarchy with clear visual distinction */ .vp-doc h1 { + font-family: var(--vp-font-family-heading); + font-size: var(--vp-font-size-4xl); font-weight: 800; - letter-spacing: -0.02em; - margin-bottom: 1.5rem; + letter-spacing: -0.025em; + line-height: var(--vp-line-height-tight); + margin-bottom: var(--vp-spacing-8); + color: var(--vp-c-text-1); } .vp-doc h2 { + font-family: var(--vp-font-family-heading); + font-size: var(--vp-font-size-2xl); font-weight: 700; - margin-top: 3rem; - padding-top: 2rem; letter-spacing: -0.01em; + line-height: var(--vp-line-height-tight); + margin-top: var(--vp-spacing-12); + padding-top: var(--vp-spacing-8); border-top: 1px solid var(--vp-c-divider); + color: var(--vp-c-text-1); } .vp-doc h2:first-of-type { - margin-top: 1.5rem; + margin-top: var(--vp-spacing-6); border-top: none; } .vp-doc h3 { + font-family: var(--vp-font-family-heading); + font-size: var(--vp-font-size-xl); font-weight: 600; - margin-top: 2.5rem; + line-height: var(--vp-line-height-snug); + margin-top: var(--vp-spacing-10); + color: var(--vp-c-text-1); } .vp-doc h4 { + font-family: var(--vp-font-family-heading); + font-size: var(--vp-font-size-lg); font-weight: 600; - margin-top: 2rem; + line-height: var(--vp-line-height-snug); + margin-top: var(--vp-spacing-8); + color: var(--vp-c-text-2); } +.vp-doc h5 { + font-size: var(--vp-font-size-base); + font-weight: 600; + line-height: var(--vp-line-height-snug); + margin-top: var(--vp-spacing-6); + color: var(--vp-c-text-2); +} + +.vp-doc h6 { + font-size: var(--vp-font-size-sm); + font-weight: 600; + line-height: var(--vp-line-height-snug); + margin-top: var(--vp-spacing-4); + color: var(--vp-c-text-3); + text-transform: uppercase; + letter-spacing: 0.05em; +} + +/* Body text with optimal line height */ .vp-doc p { - line-height: 1.8; - margin: 1.25rem 0; + font-size: var(--vp-font-size-base); + line-height: var(--vp-line-height-relaxed); + margin: var(--vp-spacing-5) 0; + max-width: var(--vp-prose-width); } +/* Lists with proper spacing */ .vp-doc ul, .vp-doc ol { - margin: 1.25rem 0; - padding-left: 1.5rem; + font-size: var(--vp-font-size-base); + line-height: var(--vp-line-height-relaxed); + margin: var(--vp-spacing-5) 0; + padding-left: var(--vp-spacing-6); + max-width: var(--vp-prose-width); } .vp-doc li { - line-height: 1.8; - margin: 0.5rem 0; + line-height: var(--vp-line-height-relaxed); + margin: var(--vp-spacing-2) 0; } .vp-doc li + li { - margin-top: 0.5rem; + margin-top: var(--vp-spacing-2); +} + +/* Nested lists */ +.vp-doc ul ul, +.vp-doc ol ol, +.vp-doc ul ol, +.vp-doc ol ul { + margin: var(--vp-spacing-2) 0; } /* Better spacing for code blocks in lists */ @@ -191,6 +267,31 @@ margin: 0 2px; } +/* Blockquotes */ +.vp-doc blockquote { + margin: var(--vp-spacing-6) 0; + padding: var(--vp-spacing-4) var(--vp-spacing-6); + border-left: 4px solid var(--vp-c-primary); + background: var(--vp-c-bg-soft); + border-radius: 0 var(--vp-radius-lg) var(--vp-radius-lg) 0; + color: var(--vp-c-text-2); + font-style: italic; +} + +.vp-doc blockquote p { + margin: var(--vp-spacing-2) 0; +} + +/* Strong and emphasis */ +.vp-doc strong { + font-weight: 600; + color: var(--vp-c-text-1); +} + +.vp-doc em { + font-style: italic; +} + /* ============================================ * Command Reference Specific Styles * ============================================ */ @@ -212,12 +313,15 @@ /* ============================================ * Custom Container Blocks + * Flat design with left accent border * ============================================ */ .custom-container { - margin: 20px 0; - padding: 16px 20px; - border-radius: 12px; + margin: var(--vp-spacing-6) 0; + padding: var(--vp-spacing-4) var(--vp-spacing-5); + border-radius: var(--vp-radius-xl); border-left: 4px solid; + background: var(--vp-c-bg-soft); + box-shadow: var(--vp-shadow-xs); } .custom-container.info { @@ -231,103 +335,285 @@ } .dark .custom-container.success { - background: rgba(16, 185, 129, 0.1); + background: rgba(16, 185, 129, 0.08); } .custom-container.tip { - border-radius: 12px; + border-radius: var(--vp-radius-xl); + background: rgba(59, 130, 246, 0.05); } .custom-container.warning { - border-radius: 12px; + border-radius: var(--vp-radius-xl); + background: rgba(245, 158, 11, 0.05); } .custom-container.danger { - border-radius: 12px; + border-radius: var(--vp-radius-xl); + background: rgba(239, 68, 68, 0.05); +} + +/* Custom container titles */ +.custom-container .custom-container-title { + font-family: var(--vp-font-family-heading); + font-weight: 600; + font-size: var(--vp-font-size-sm); + text-transform: uppercase; + letter-spacing: 0.05em; + margin-bottom: var(--vp-spacing-2); +} + +/* VitePress default custom blocks */ +.vp-doc .tip, +.vp-doc .warning, +.vp-doc .danger, +.vp-doc .info { + border-radius: var(--vp-radius-xl); + margin: var(--vp-spacing-6) 0; + padding: var(--vp-spacing-4) var(--vp-spacing-5); + box-shadow: var(--vp-shadow-xs); +} + +.vp-doc .tip { + background: rgba(59, 130, 246, 0.05); + border-color: var(--vp-c-primary); +} + +.vp-doc .warning { + background: rgba(245, 158, 11, 0.05); + border-color: var(--vp-c-accent); +} + +.vp-doc .danger { + background: rgba(239, 68, 68, 0.05); + border-color: #ef4444; +} + +.vp-doc .info { + background: var(--vp-c-bg-soft); + border-color: var(--vp-c-primary); } /* ============================================ * Code Block Improvements + * Clean, flat design with subtle borders * ============================================ */ .vp-code-group { - margin: 20px 0; - border-radius: 12px; + margin: var(--vp-spacing-6) 0; + border-radius: var(--vp-radius-xl); overflow: hidden; + border: 1px solid var(--vp-c-divider); + box-shadow: var(--vp-shadow-sm); } .vp-code-group .tabs { background: var(--vp-c-bg-soft); border-bottom: 1px solid var(--vp-c-divider); + padding: 0 var(--vp-spacing-2); } .vp-code-group div[class*='language-'] { margin: 0; border-radius: 0; + border: none; } div[class*='language-'] { - border-radius: 12px; - margin: 20px 0; + border-radius: var(--vp-radius-xl); + margin: var(--vp-spacing-6) 0; + border: 1px solid var(--vp-c-divider); + background: var(--vp-c-bg-soft) !important; + box-shadow: var(--vp-shadow-sm); } div[class*='language-'] pre { - line-height: 1.65; + line-height: var(--vp-line-height-relaxed); + padding: var(--vp-spacing-5) var(--vp-spacing-6); } -/* Inline code */ +div[class*='language-'] code { + font-family: var(--vp-font-family-mono); + font-size: var(--vp-font-size-sm); + font-weight: 400; + letter-spacing: -0.01em; +} + +/* Code block header with language label */ +div[class*='language-'] > span.lang { + font-size: var(--vp-font-size-xs); + font-weight: 500; + text-transform: uppercase; + letter-spacing: 0.05em; + color: var(--vp-c-text-3); + padding: var(--vp-spacing-2) var(--vp-spacing-4); + background: var(--vp-c-bg-soft); + border-radius: var(--vp-radius-md); +} + +/* Inline code - subtle styling */ .vp-doc :not(pre) > code { - border-radius: 6px; + font-family: var(--vp-font-family-mono); + border-radius: var(--vp-radius-md); padding: 2px 6px; font-size: 0.875em; font-weight: 500; + background: var(--vp-c-bg-soft); + border: 1px solid var(--vp-c-divider); + color: var(--vp-c-primary); +} + +/* Copy button styling */ +.vp-code-group .vp-copy, +div[class*='language-'] .vp-copy { + border-radius: var(--vp-radius-md); + transition: all var(--vp-transition-color); +} + +.vp-code-group .vp-copy:hover, +div[class*='language-'] .vp-copy:hover { + background: var(--vp-c-bg-mute); } /* ============================================ * Table Styling + * Clean, flat design with subtle borders * ============================================ */ -table { +.vp-doc table { border-collapse: collapse; width: 100%; - margin: 20px 0; - border-radius: 12px; - overflow: hidden; + margin: var(--vp-spacing-6) 0; } -table th, -table td { - padding: 12px 16px; +.vp-doc table th, +.vp-doc table td { + padding: var(--vp-spacing-3) var(--vp-spacing-4); border: 1px solid var(--vp-c-divider); text-align: left; + font-size: var(--vp-font-size-sm); + line-height: var(--vp-line-height-normal); } -table th { +.vp-doc table th { background: var(--vp-c-bg-soft); + font-family: var(--vp-font-family-heading); font-weight: 600; - font-size: 0.875rem; + font-size: var(--vp-font-size-xs); text-transform: uppercase; - letter-spacing: 0.03em; + letter-spacing: 0.05em; color: var(--vp-c-text-2); + border-bottom-width: 2px; } -table tr:hover { +.vp-doc table td { + color: var(--vp-c-text-1); + vertical-align: top; +} + +.vp-doc table tr:hover { background: var(--vp-c-bg-soft); } +.vp-doc table tr:hover td { + color: var(--vp-c-text-1); +} + +/* Responsive tables */ +@media (max-width: 767px) { + .vp-doc table { + display: block; + overflow-x: auto; + -webkit-overflow-scrolling: touch; + } + + .vp-doc table th, + .vp-doc table td { + padding: var(--vp-spacing-2) var(--vp-spacing-3); + font-size: var(--vp-font-size-xs); + white-space: nowrap; + } +} + /* ============================================ * Sidebar Polish + * Clean, organized navigation * ============================================ */ +.VPSidebar { + background: var(--vp-c-bg); + border-right: 1px solid var(--vp-c-divider); +} + .VPSidebar .group + .group { - margin-top: 0.5rem; - padding-top: 0.5rem; + margin-top: var(--vp-spacing-4); + padding-top: var(--vp-spacing-4); border-top: 1px solid var(--vp-c-divider); } +/* Sidebar item styling */ +.VPSidebar .VPSidebarItem .text { + font-size: var(--vp-font-size-sm); + line-height: var(--vp-line-height-normal); + transition: color var(--vp-transition-color); +} + +.VPSidebar .VPSidebarItem .link:hover .text { + color: var(--vp-c-primary); +} + +.VPSidebar .VPSidebarItem.is-active .link .text { + color: var(--vp-c-primary); + font-weight: 600; +} + +/* Sidebar group titles */ +.VPSidebar .VPSidebarGroup .title { + font-family: var(--vp-font-family-heading); + font-size: var(--vp-font-size-xs); + font-weight: 600; + text-transform: uppercase; + letter-spacing: 0.05em; + color: var(--vp-c-text-3); + padding: var(--vp-spacing-2) var(--vp-spacing-4); +} + +/* ============================================ + * Navigation Polish + * ============================================ */ +.VPNav { + background: var(--vp-c-bg); + border-bottom: 1px solid var(--vp-c-divider); + box-shadow: var(--vp-shadow-xs); +} + +.VPNavBar .title { + font-family: var(--vp-font-family-heading); + font-weight: 700; + font-size: var(--vp-font-size-lg); + color: var(--vp-c-text-1); +} + +.VPNavBarMenu .VPNavBarMenuLink { + font-family: var(--vp-font-family-heading); + font-weight: 500; + font-size: var(--vp-font-size-sm); + transition: color var(--vp-transition-color); +} + +.VPNavBarMenu .VPNavBarMenuLink:hover { + color: var(--vp-c-primary); +} + +.VPNavBarMenu .VPNavBarMenuLink.active { + color: var(--vp-c-primary); + font-weight: 600; +} + /* ============================================ * Scrollbar Styling + * Subtle, flat design * ============================================ */ ::-webkit-scrollbar { - width: 6px; - height: 6px; + width: 8px; + height: 8px; } ::-webkit-scrollbar-track { @@ -337,30 +623,148 @@ table tr:hover { ::-webkit-scrollbar-thumb { background: var(--vp-c-surface-2); border-radius: var(--vp-radius-full); + border: 2px solid transparent; + background-clip: padding-box; } ::-webkit-scrollbar-thumb:hover { background: var(--vp-c-surface-3); + border: 2px solid transparent; + background-clip: padding-box; +} + +/* Firefox scrollbar */ +* { + scrollbar-width: thin; + scrollbar-color: var(--vp-c-surface-2) transparent; +} + +/* ============================================ + * TOC (Table of Contents) Polish + * Sticky positioning handled by grid layout in mobile.css + * ============================================ */ +.VPDocOutline { + padding-left: 24px; +} + +.VPDocOutline .outline-link { + font-family: var(--vp-font-family-base); + font-size: var(--vp-font-size-sm); + line-height: var(--vp-line-height-normal); + padding: var(--vp-spacing-1) var(--vp-spacing-2); + color: var(--vp-c-text-3); + transition: color var(--vp-transition-color); + border-radius: var(--vp-radius-md); +} + +.VPDocOutline .outline-link:hover { + color: var(--vp-c-primary); + background: var(--vp-c-bg-soft); +} + +.VPDocOutline .outline-link.is-active { + color: var(--vp-c-primary); + font-weight: 500; + background: var(--vp-c-bg-soft); +} + +.VPDocOutline .outline-marker { + width: 2px; + background: var(--vp-c-primary); + border-radius: var(--vp-radius-full); } /* ============================================ * Link Improvements + * Clean, accessible link styling * ============================================ */ a { text-decoration: none; - transition: color 0.2s ease; + color: var(--vp-c-primary); + transition: color var(--vp-transition-color); + cursor: pointer; } a:hover { text-decoration: underline; + color: var(--vp-c-primary-600); +} + +a:visited { + color: var(--vp-c-primary-700); +} + +.dark a:visited { + color: var(--vp-c-primary-300); +} + +/* External link indicator */ +.vp-doc a[target="_blank"]::after { + content: " ↗"; + font-size: 0.75em; + opacity: 0.7; +} + +/* ============================================ + * Button Improvements + * ============================================ */ +.VPButton { + font-family: var(--vp-font-family-heading); + font-weight: 600; + font-size: var(--vp-font-size-sm); + padding: var(--vp-spacing-2-5) var(--vp-spacing-5); + border-radius: var(--vp-radius-lg); + transition: all var(--vp-transition-color); + cursor: pointer; +} + +.VPButton.brand { + background: var(--vp-c-primary); + color: white; + border: none; +} + +.VPButton.brand:hover { + background: var(--vp-c-primary-600); + transform: translateY(-1px); + box-shadow: var(--vp-shadow-md); +} + +.VPButton.alt { + background: var(--vp-c-bg-soft); + color: var(--vp-c-text-1); + border: 1px solid var(--vp-c-divider); +} + +.VPButton.alt:hover { + background: var(--vp-c-bg-mute); + border-color: var(--vp-c-primary); } /* ============================================ * Focus States — Accessibility + * Clear visible focus for keyboard navigation * ============================================ */ :focus-visible { outline: 2px solid var(--vp-c-primary); outline-offset: 2px; + border-radius: var(--vp-radius-md); +} + +/* Skip focus outline for mouse users */ +:focus:not(:focus-visible) { + outline: none; +} + +/* Better focus for interactive elements */ +a:focus-visible, +button:focus-visible, +input:focus-visible, +select:focus-visible, +textarea:focus-visible { + outline: 2px solid var(--vp-c-primary); + outline-offset: 2px; + box-shadow: 0 0 0 4px rgba(59, 130, 246, 0.15); } /* ============================================ diff --git a/docs/.vitepress/theme/styles/mobile.css b/docs/.vitepress/theme/styles/mobile.css index a8e8b669..f47ea299 100644 --- a/docs/.vitepress/theme/styles/mobile.css +++ b/docs/.vitepress/theme/styles/mobile.css @@ -1,5 +1,6 @@ /** * Mobile-Responsive Styles + * Design System: ui-ux-pro-max — flat design, mobile-first * Breakpoints: < 480px (xs), < 768px (sm/mobile), 768px-1024px (md/tablet), > 1024px (lg/desktop) * WCAG 2.1 AA compliant * @@ -253,15 +254,16 @@ /* Base Mobile Styles (320px+) */ @media (max-width: 767px) { - /* Typography */ + /* Typography - smaller base for mobile */ :root { --vp-font-size-base: 14px; --vp-content-width: 100%; + --vp-prose-width: 100%; } /* Container */ .container { - padding: 0 12px; + padding: 0 var(--vp-spacing-3); } /* Navigation - ensure hamburger menu is visible */ @@ -271,10 +273,15 @@ } .VPNavBar { - padding: 0 12px; + padding: 0; overflow: visible !important; } + /* VPNavBar content padding for alignment */ + .VPNavBar .content { + padding: 0 var(--vp-spacing-3); + } + /* Navigation bar content wrapper */ .VPNavBar .content { overflow: visible !important; @@ -297,8 +304,8 @@ /* Reduce nav-extensions gap on mobile */ .VPNavBar .nav-extensions { - gap: 0.25rem; - padding-left: 0.25rem; + gap: var(--vp-spacing-1); + padding-left: var(--vp-spacing-1); overflow: visible !important; } @@ -333,10 +340,10 @@ overflow-y: auto; background: var(--vp-c-bg); border: 1px solid var(--vp-c-divider); - border-radius: 8px; - box-shadow: 0 4px 20px rgba(0, 0, 0, 0.15); + border-radius: var(--vp-radius-lg); + box-shadow: var(--vp-shadow-lg); z-index: 100; - padding: 8px 0; + padding: var(--vp-spacing-2) 0; } /* Language switcher dropdown fix */ @@ -354,7 +361,7 @@ min-width: 200px !important; max-width: calc(100vw - 24px) !important; z-index: 1000 !important; - box-shadow: 0 8px 24px rgba(0, 0, 0, 0.2) !important; + box-shadow: var(--vp-shadow-xl) !important; } /* Sidebar - fix display issues */ @@ -365,12 +372,19 @@ top: 56px !important; height: calc(100vh - 56px) !important; max-height: calc(100vh - 56px) !important; - overflow: visible !important; + overflow-y: auto !important; + overflow-x: hidden !important; position: fixed !important; left: 0 !important; z-index: 40 !important; background: var(--vp-c-bg) !important; transition: transform 0.25s ease !important; + border-right: 1px solid var(--vp-c-divider); + } + + /* Add padding to sidebar nav to prevent scrollbar overlap with navbar */ + .VPSidebar .VPSidebarNav { + padding-top: var(--vp-spacing-4) !important; } /* Sidebar when open */ @@ -386,7 +400,7 @@ /* Sidebar nav container */ .VPSidebar .VPSidebarNav { - padding: 12px 0; + padding: var(--vp-spacing-3) 0; height: 100%; min-height: auto; overflow-y: auto; @@ -395,17 +409,17 @@ /* Sidebar groups */ .VPSidebar .VPSidebarGroup { - padding: 8px 16px; + padding: var(--vp-spacing-2) var(--vp-spacing-4); } /* Sidebar items */ .VPSidebar .VPSidebarItem { - padding: 6px 0; + padding: var(--vp-spacing-1-5) 0; } /* Ensure sidebar links are properly sized */ .VPSidebar .link { - padding: 8px 12px; + padding: var(--vp-spacing-2) var(--vp-spacing-3); display: block; } @@ -434,21 +448,21 @@ /* Make sure all sidebar content is visible */ .VPSidebar .group { margin: 0; - padding: 12px 16px; + padding: var(--vp-spacing-3) var(--vp-spacing-4); } .VPSidebar .title { - font-size: 14px; + font-size: var(--vp-font-size-sm); font-weight: 600; - padding: 4px 0; + padding: var(--vp-spacing-1) 0; color: var(--vp-c-text-1); } /* Sidebar text styling */ .VPSidebar .text { - font-size: 14px; - line-height: 1.5; - padding: 6px 12px; + font-size: var(--vp-font-size-sm); + line-height: var(--vp-line-height-normal); + padding: var(--vp-spacing-1-5) var(--vp-spacing-3); } /* Ensure nested items are visible */ @@ -467,12 +481,12 @@ /* Content - reduce padding for better space usage */ .VPContent { - padding: 12px; + padding: var(--vp-spacing-3); } /* Doc content adjustments - reduce padding */ .VPDoc .content-container { - padding: 0 12px; + padding: 0 var(--vp-spacing-3); } /* Hide outline on mobile */ @@ -482,27 +496,27 @@ /* Hero Section */ .VPHomeHero { - padding: 40px 12px; + padding: var(--vp-spacing-10) var(--vp-spacing-3); } .VPHomeHero h1 { - font-size: 28px; - line-height: 1.2; + font-size: var(--vp-font-size-2xl); + line-height: var(--vp-line-height-tight); } .VPHomeHero p { - font-size: 14px; + font-size: var(--vp-font-size-sm); } /* Code Blocks - reduce margins */ div[class*='language-'] { - margin: 12px -12px; + margin: var(--vp-spacing-3) calc(var(--vp-spacing-3) * -1); border-radius: 0; } div[class*='language-'] pre { - padding: 12px; - font-size: 12px; + padding: var(--vp-spacing-3); + font-size: var(--vp-font-size-xs); } /* Tables - make them scrollable */ @@ -514,23 +528,23 @@ } table { - font-size: 12px; + font-size: var(--vp-font-size-xs); } table th, table td { - padding: 8px 12px; + padding: var(--vp-spacing-2) var(--vp-spacing-3); } /* Buttons */ .VPButton { - padding: 8px 16px; - font-size: 14px; + padding: var(--vp-spacing-2) var(--vp-spacing-4); + font-size: var(--vp-font-size-sm); } /* Cards */ .VPFeature { - padding: 16px; + padding: var(--vp-spacing-4); } /* Touch-friendly tap targets (min 44x44px per WCAG) */ @@ -550,13 +564,13 @@ /* Theme Switcher */ .theme-switcher { - padding: 12px; + padding: var(--vp-spacing-3); } /* Breadcrumbs */ .breadcrumb { - padding: 8px 0; - font-size: 12px; + padding: var(--vp-spacing-2) 0; + font-size: var(--vp-font-size-xs); } /* Table of Contents - hidden on mobile */ @@ -566,34 +580,34 @@ /* Typography adjustments for mobile */ .vp-doc h1 { - font-size: 1.75rem; - margin-bottom: 1rem; + font-size: var(--vp-font-size-2xl); + margin-bottom: var(--vp-spacing-4); } .vp-doc h2 { - font-size: 1.375rem; - margin-top: 2rem; - padding-top: 1.5rem; + font-size: var(--vp-font-size-xl); + margin-top: var(--vp-spacing-8); + padding-top: var(--vp-spacing-6); } .vp-doc h3 { - font-size: 1.125rem; - margin-top: 1.5rem; + font-size: var(--vp-font-size-lg); + margin-top: var(--vp-spacing-6); } .vp-doc p { - line-height: 1.7; - margin: 1rem 0; + line-height: var(--vp-line-height-relaxed); + margin: var(--vp-spacing-4) 0; } .vp-doc ul, .vp-doc ol { - margin: 1rem 0; - padding-left: 1.25rem; + margin: var(--vp-spacing-4) 0; + padding-left: var(--vp-spacing-5); } .vp-doc li { - margin: 0.375rem 0; + margin: var(--vp-spacing-1-5) 0; } } @@ -602,39 +616,40 @@ * ============================================ */ @media (min-width: 768px) and (max-width: 1023px) { :root { - --vp-content-width: 760px; + --vp-content-width: 720px; --vp-sidebar-width: 240px; + --vp-prose-width: 640px; } .VPContent { - padding: 24px; + padding: var(--vp-spacing-6); } .VPDoc .content-container { - padding: 0 24px; - max-width: 90% !important; + padding: 0 var(--vp-spacing-6); + max-width: 98% !important; } .VPHomeHero { - padding: 60px 24px; + padding: var(--vp-spacing-16) var(--vp-spacing-6); } .VPHomeHero h1 { - font-size: 36px; + font-size: var(--vp-font-size-3xl); } div[class*='language-'] { - margin: 12px 0; + margin: var(--vp-spacing-3) 0; } /* Outline visible but narrower */ .VPDocOutline { width: 200px; - padding-left: 16px; + padding-left: var(--vp-spacing-4); } .VPDocOutline .outline-link { - font-size: 12px; + font-size: var(--vp-font-size-xs); } } @@ -643,52 +658,122 @@ * ============================================ */ @media (min-width: 1024px) { :root { - --vp-layout-max-width: 1600px; - --vp-content-width: 960px; - --vp-sidebar-width: 272px; + --vp-layout-max-width: 1440px; + --vp-content-width: 860px; + --vp-sidebar-width: 280px; + --vp-prose-width: 720px; + --vp-toc-width: 220px; } .VPContent { - padding: 32px 48px; - max-width: var(--vp-layout-max-width); + padding: var(--vp-spacing-8) var(--vp-spacing-12); + /* Remove max-width to allow full viewport width */ } - .VPDoc .content-container { - max-width: 90% !important; - padding: 0 40px; + /* Desktop sidebar - restore fixed positioning but with proper width */ + .VPSidebar { + position: fixed !important; + left: 0 !important; + top: var(--vp-nav-height, 56px) !important; + width: var(--vp-sidebar-width, 280px) !important; + height: calc(100vh - var(--vp-nav-height, 56px)) !important; + padding: 0 !important; + overflow-y: auto !important; + border-right: 1px solid var(--vp-c-divider) !important; + z-index: 10 !important; } - /* Outline - sticky on desktop with good width */ - .VPDocOutline { - position: sticky; - top: calc(var(--vp-nav-height) + 24px); - width: 256px; - padding-left: 24px; - max-height: calc(100vh - var(--vp-nav-height) - 48px); + /* Desktop sidebar - add padding to inner nav */ + .VPSidebar nav.nav { + padding: var(--vp-spacing-4) !important; + height: auto; + } + + /* Ensure content has proper margin-left to clear the sidebar */ + .VPContent.has-sidebar { + margin-left: var(--vp-sidebar-width, 280px) !important; + margin-right: calc(var(--vp-toc-width, 220px) + 48px) !important; + padding: var(--vp-spacing-8) var(--vp-spacing-12) !important; + } + + /* Adjust doc container - remove auto margin to prevent offset */ + .VPDoc.has-aside .content-container { + max-width: 100%; + padding: 0 var(--vp-spacing-10); + } + + /* Right TOC - fixed position with right margin */ + .VPDocAside { + position: fixed; + right: 24px; + top: calc(var(--vp-nav-height, 56px) + 16px); + width: var(--vp-toc-width, 220px); + height: auto; + max-height: calc(100vh - var(--vp-nav-height, 56px) - 64px); overflow-y: auto; } + .aside-container { + position: fixed; + right: 24px; + top: calc(var(--vp-nav-height, 56px) + 16px); + width: var(--vp-toc-width, 220px); + height: auto; + max-height: calc(100vh - var(--vp-nav-height, 56px) - 64px); + overflow-y: auto; + } + + .VPDocOutline { + position: relative; + height: auto; + max-height: 100%; + overflow-y: auto; + padding: var(--vp-spacing-4); + } + + /* Navbar title - anchor to left edge */ + .VPNavBarTitle { + position: relative !important; + margin-left: 0 !important; + padding-left: 0 !important; + } + + /* Ensure navbar content-body has proper left padding */ + .VPNavBar .content-body { + padding-left: var(--vp-spacing-4) !important; + } + + /* Fix title position */ + .VPNavBar .title { + padding-left: var(--vp-spacing-4) !important; + left: 0 !important; + } + + /* Home page navbar - reduce title left margin since no sidebar */ + .Layout:has(.pro-home) .VPNavBar .content-body, + .Layout:has(.pro-home) .VPNavBar .title { + padding-left: 0 !important; + } + + /* Home page - no sidebar margin */ + .Layout:has(.pro-home) .VPContent { + margin-left: 0 !important; + } + .VPDocOutline .outline-marker { display: block; } .VPDocOutline .outline-link { - font-size: 13px; - line-height: 1.6; - padding: 4px 12px; - transition: color 0.2s ease; + font-size: var(--vp-font-size-sm); + line-height: var(--vp-line-height-normal); + padding: var(--vp-spacing-1) var(--vp-spacing-3); + transition: color var(--vp-transition-color); } .VPDocOutline .outline-link:hover { color: var(--vp-c-primary); } - - /* Two-column layout for content + TOC */ - .content-with-toc { - display: grid; - grid-template-columns: 1fr 280px; - gap: 32px; - } } /* ============================================ @@ -696,17 +781,17 @@ * ============================================ */ @media (min-width: 1440px) { :root { - --vp-content-width: 1040px; - --vp-sidebar-width: 280px; + --vp-content-width: 920px; + --vp-sidebar-width: 300px; + --vp-prose-width: 760px; + --vp-toc-width: 260px; } - .VPDoc .content-container { - max-width: 90% !important; - padding: 0 48px; - } - - .VPDocOutline { - width: 280px; + .VPDoc.has-aside .content-container { + max-width: 100%; + padding: 0 var(--vp-spacing-12); + margin-left: 0; + margin-right: 0; } } diff --git a/docs/.vitepress/theme/styles/variables.css b/docs/.vitepress/theme/styles/variables.css index 1fe4c210..dd6e17a7 100644 --- a/docs/.vitepress/theme/styles/variables.css +++ b/docs/.vitepress/theme/styles/variables.css @@ -79,23 +79,58 @@ --vp-c-text-4: #9ca3af; --vp-c-text-code: #ef4444; - /* Typography */ - --vp-font-family-base: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif; - --vp-font-family-mono: 'Fira Code', 'Cascadia Code', 'JetBrains Mono', Consolas, 'Courier New', monospace; + /* Typography - Developer-focused font pairing */ + --vp-font-family-base: 'Inter', 'IBM Plex Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Helvetica Neue', sans-serif; + --vp-font-family-mono: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', Consolas, 'Courier New', monospace; + --vp-font-family-heading: 'Inter', 'IBM Plex Sans', -apple-system, BlinkMacSystemFont, sans-serif; - /* Font Sizes */ - --vp-font-size-base: 16px; - --vp-font-size-sm: 14px; - --vp-font-size-lg: 18px; - --vp-font-size-xl: 20px; + /* Font Sizes - Modular scale (1.25 ratio) */ + --vp-font-size-xs: 0.75rem; /* 12px */ + --vp-font-size-sm: 0.875rem; /* 14px */ + --vp-font-size-base: 1rem; /* 16px */ + --vp-font-size-lg: 1.125rem; /* 18px */ + --vp-font-size-xl: 1.25rem; /* 20px */ + --vp-font-size-2xl: 1.5rem; /* 24px */ + --vp-font-size-3xl: 1.875rem; /* 30px */ + --vp-font-size-4xl: 2.25rem; /* 36px */ - /* Spacing (Fixed) */ - --vp-spacing-xs: 0.25rem; /* 4px */ - --vp-spacing-sm: 0.5rem; /* 8px */ - --vp-spacing-md: 1rem; /* 16px */ - --vp-spacing-lg: 1.5rem; /* 24px */ - --vp-spacing-xl: 2rem; /* 32px */ - --vp-spacing-2xl: 3rem; /* 48px */ + /* Line Heights - Optimized for readability */ + --vp-line-height-tight: 1.25; + --vp-line-height-snug: 1.4; + --vp-line-height-normal: 1.6; + --vp-line-height-relaxed: 1.75; + --vp-line-height-loose: 2; + + /* Spacing (Fixed) - 8px base grid */ + --vp-spacing-0: 0; + --vp-spacing-px: 1px; + --vp-spacing-0-5: 0.125rem; /* 2px */ + --vp-spacing-1: 0.25rem; /* 4px */ + --vp-spacing-1-5: 0.375rem; /* 6px */ + --vp-spacing-2: 0.5rem; /* 8px */ + --vp-spacing-2-5: 0.625rem; /* 10px */ + --vp-spacing-3: 0.75rem; /* 12px */ + --vp-spacing-3-5: 0.875rem; /* 14px */ + --vp-spacing-4: 1rem; /* 16px */ + --vp-spacing-5: 1.25rem; /* 20px */ + --vp-spacing-6: 1.5rem; /* 24px */ + --vp-spacing-7: 1.75rem; /* 28px */ + --vp-spacing-8: 2rem; /* 32px */ + --vp-spacing-9: 2.25rem; /* 36px */ + --vp-spacing-10: 2.5rem; /* 40px */ + --vp-spacing-12: 3rem; /* 48px */ + --vp-spacing-14: 3.5rem; /* 56px */ + --vp-spacing-16: 4rem; /* 64px */ + --vp-spacing-20: 5rem; /* 80px */ + --vp-spacing-24: 6rem; /* 96px */ + + /* Legacy aliases for backward compatibility */ + --vp-spacing-xs: var(--vp-spacing-1); + --vp-spacing-sm: var(--vp-spacing-2); + --vp-spacing-md: var(--vp-spacing-4); + --vp-spacing-lg: var(--vp-spacing-6); + --vp-spacing-xl: var(--vp-spacing-8); + --vp-spacing-2xl: var(--vp-spacing-12); /* Fluid Spacing (Responsive with clamp()) * Scales smoothly between viewport widths @@ -116,18 +151,24 @@ --container-outline: outline; --container-nav: nav; - /* Border Radius */ + /* Border Radius - Subtle, flat design friendly */ + --vp-radius-none: 0; --vp-radius-sm: 0.25rem; /* 4px */ --vp-radius-md: 0.375rem; /* 6px */ --vp-radius-lg: 0.5rem; /* 8px */ --vp-radius-xl: 0.75rem; /* 12px */ + --vp-radius-2xl: 1rem; /* 16px */ + --vp-radius-3xl: 1.5rem; /* 24px */ --vp-radius-full: 9999px; - /* Shadows */ - --vp-shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05); - --vp-shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1); - --vp-shadow-lg: 0 10px 15px -3 rgb(0 0 0 / 0.1); - --vp-shadow-xl: 0 20px 25px -5 rgb(0 0 0 / 0.1); + /* Shadows - Subtle for flat design */ + --vp-shadow-xs: 0 1px 2px 0 rgb(0 0 0 / 0.03); + --vp-shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 0.05), 0 1px 2px -1px rgb(0 0 0 / 0.05); + --vp-shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.07), 0 2px 4px -2px rgb(0 0 0 / 0.05); + --vp-shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.08), 0 4px 6px -4px rgb(0 0 0 / 0.05); + --vp-shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.08), 0 8px 10px -6px rgb(0 0 0 / 0.05); + --vp-shadow-inner: inset 0 2px 4px 0 rgb(0 0 0 / 0.05); + --vp-shadow-none: 0 0 #0000; /* Transitions */ --vp-transition-color: 0.2s ease; diff --git a/docs/guide/ch05-advanced-tips.md b/docs/guide/ch05-advanced-tips.md index 538c1bed..f677dee8 100644 --- a/docs/guide/ch05-advanced-tips.md +++ b/docs/guide/ch05-advanced-tips.md @@ -2,255 +2,180 @@ ## One-Line Positioning -**Advanced Tips are the key to efficiency improvement** — Deep CLI toolchain usage, multi-model collaboration optimization, memory management best practices. +**Drive AI tool orchestration with natural language** — Semantic CLI invocation, multi-model collaboration, intelligent memory management. --- -## 5.1 CLI Toolchain Usage +## 5.1 Semantic Tool Orchestration -### 5.1.1 CLI Configuration +### 5.1.1 Core Concept -CLI tool configuration file: `~/.claude/cli-tools.json` +CCW's CLI tools are **AI-automated capability extensions**. Users simply describe needs in natural language, and AI automatically selects and invokes the appropriate tools. + +::: tip Key Understanding +- User says: "Use Gemini to analyze this code" +- AI automatically: Invokes Gemini CLI + applies analysis rules + returns results +- Users don't need to know `ccw cli` command details +::: + +### 5.1.2 Available Tools & Capabilities + +| Tool | Strengths | Typical Trigger Words | +| --- | --- | --- | +| **Gemini** | Deep analysis, architecture design, bug diagnosis | "use Gemini", "deep understanding" | +| **Qwen** | Code generation, feature implementation | "let Qwen implement", "code generation" | +| **Codex** | Code review, Git operations | "use Codex", "code review" | +| **OpenCode** | Open-source multi-model | "use OpenCode" | + +### 5.1.3 Semantic Trigger Examples + +Simply express naturally in conversation, AI will automatically invoke the corresponding tool: + +| Goal | User Semantic Description | AI Auto-Executes | +| :--- | :--- | :--- | +| **Security Assessment** | "Use Gemini to scan auth module for security vulnerabilities" | Gemini + Security analysis rule | +| **Code Implementation** | "Let Qwen implement a rate limiting middleware" | Qwen + Feature implementation rule | +| **Code Review** | "Use Codex to review this PR's changes" | Codex + Review rule | +| **Bug Diagnosis** | "Use Gemini to analyze the root cause of this memory leak" | Gemini + Diagnosis rule | + +### 5.1.4 Underlying Configuration (Optional) + +AI tool invocation configuration file at `~/.claude/cli-tools.json`: ```json { - "version": "3.3.0", "tools": { "gemini": { "enabled": true, "primaryModel": "gemini-2.5-flash", - "secondaryModel": "gemini-2.5-flash", - "tags": ["analysis", "Debug"], - "type": "builtin" + "tags": ["analysis", "Debug"] }, "qwen": { "enabled": true, "primaryModel": "coder-model", - "secondaryModel": "coder-model", - "tags": [], - "type": "builtin" - }, - "codex": { - "enabled": true, - "primaryModel": "gpt-5.2", - "secondaryModel": "gpt-5.2", - "tags": [], - "type": "builtin" + "tags": ["implementation"] } } } ``` -### 5.1.2 Tag Routing - -Automatically select models based on task type: - -| Tag | Applicable Model | Task Type | -| --- | --- | --- | -| **analysis** | Gemini | Code analysis, architecture design | -| **Debug** | Gemini | Root cause analysis, problem diagnosis | -| **implementation** | Qwen | Feature development, code generation | -| **review** | Codex | Code review, Git operations | - -### 5.1.3 CLI Command Templates - -#### Analysis Task - -```bash -ccw cli -p "PURPOSE: Identify security vulnerabilities -TASK: • Scan for SQL injection • Check XSS • Verify CSRF -MODE: analysis -CONTEXT: @src/auth/**/* -EXPECTED: Security report with severity grading and fix recommendations -CONSTRAINTS: Focus on auth module" --tool gemini --mode analysis --rule analysis-assess-security-risks -``` - -#### Implementation Task - -```bash -ccw cli -p "PURPOSE: Implement rate limiting -TASK: • Create middleware • Configure routes • Redis backend -MODE: write -CONTEXT: @src/middleware/**/* @src/config/**/* -EXPECTED: Production code + unit tests + integration tests -CONSTRAINTS: Follow existing middleware patterns" --tool qwen --mode write --rule development-implement-feature -``` - -### 5.1.4 Rule Templates - -| Rule | Purpose | -| --- | --- | -| **analysis-diagnose-bug-root-cause** | Bug root cause analysis | -| **analysis-analyze-code-patterns** | Code pattern analysis | -| **analysis-review-architecture** | Architecture review | -| **analysis-assess-security-risks** | Security assessment | -| **development-implement-feature** | Feature implementation | -| **development-refactor-codebase** | Code refactoring | -| **development-generate-tests** | Test generation | +::: info Note +Tags help AI automatically select the most suitable tool based on task type. Users typically don't need to modify this configuration. +::: --- ## 5.2 Multi-Model Collaboration -### 5.2.1 Model Selection Guide +### 5.2.1 Collaboration Patterns -| Task | Recommended Model | Reason | +Through semantic descriptions, multiple AI models can work together: + +| Pattern | Description Style | Use Case | | --- | --- | --- | -| **Code Analysis** | Gemini | Strong at deep code understanding and pattern recognition | +| **Collaborative** | "Let Gemini and Codex jointly analyze architecture issues" | Multi-perspective analysis of the same problem | +| **Pipeline** | "Gemini designs, Qwen implements, Codex reviews" | Stage-by-stage complex task completion | +| **Iterative** | "Use Gemini to diagnose, Codex to fix, iterate until tests pass" | Bug fix loop | +| **Parallel** | "Let Gemini and Qwen each provide optimization suggestions" | Compare different approaches | + +### 5.2.2 Semantic Examples + +**Collaborative Analysis** +``` +User: Let Gemini and Codex jointly analyze security and performance of src/auth module +AI: [Automatically invokes both models, synthesizes analysis results] +``` + +**Pipeline Development** +``` +User: I need to implement a WebSocket real-time notification feature. + Please have Gemini design the architecture, Qwen implement the code, and Codex review. +AI: [Sequentially invokes three models, completing design→implement→review flow] +``` + +**Iterative Fix** +``` +User: Tests failed. Use Gemini to diagnose the issue, have Qwen fix it, loop until tests pass. +AI: [Automatically iterates diagnose-fix loop until problem is resolved] +``` + +### 5.2.3 Model Selection Guide + +| Task Type | Recommended Model | Reason | +| --- | --- | --- | +| **Architecture Analysis** | Gemini | Strong at deep understanding and pattern recognition | | **Bug Diagnosis** | Gemini | Powerful root cause analysis capability | -| **Feature Development** | Qwen | High code generation efficiency | -| **Code Review** | Codex (GPT) | Good Git integration, standard review format | -| **Long Text** | Claude | Large context window | - -### 5.2.2 Collaboration Patterns - -#### Serial Collaboration - -```bash -# Step 1: Gemini analysis -ccw cli -p "Analyze code architecture" --tool gemini --mode analysis - -# Step 2: Qwen implementation -ccw cli -p "Implement feature based on analysis" --tool qwen --mode write - -# Step 3: Codex review -ccw cli -p "Review implementation code" --tool codex --mode review -``` - -#### Parallel Collaboration - -Use `--tool gemini` and `--tool qwen` to analyze the same problem simultaneously: - -```bash -# Terminal 1 -ccw cli -p "Analyze from performance perspective" --tool gemini --mode analysis & - -# Terminal 2 -ccw cli -p "Analyze from security perspective" --tool codex --mode analysis & -``` - -### 5.2.3 Session Resume - -Cross-model session resume: - -```bash -# First call -ccw cli -p "Analyze authentication module" --tool gemini --mode analysis - -# Resume session to continue -ccw cli -p "Based on previous analysis, design improvement plan" --tool qwen --mode write --resume -``` +| **Code Generation** | Qwen | High code generation efficiency | +| **Code Review** | Codex | Good Git integration, standard review format | +| **Long Text Processing** | Claude | Large context window | --- -## 5.3 Memory Management +## 5.3 Intelligent Memory Management -### 5.3.1 Memory Categories +### 5.3.1 Memory System Overview -| Category | Purpose | Example Content | +CCW's memory system is an **AI self-managed** knowledge base, including: + +| Category | Purpose | Example | | --- | --- | --- | -| **learnings** | Learning insights | New technology usage experience | -| **decisions** | Architecture decisions | Technology selection rationale | -| **conventions** | Coding standards | Naming conventions, patterns | -| **issues** | Known issues | Bugs, limitations, TODOs | +| **learnings** | Learning insights | New technology usage experience, best practices | +| **decisions** | Architecture decisions | Technology selection rationale, design tradeoffs | +| **conventions** | Coding standards | Naming conventions, code style | +| **issues** | Known issues | Bug records, limitations | -### 5.3.2 Memory Commands +### 5.3.2 Automatic Memory Usage -| Command | Function | Example | -| --- | --- | --- | -| **list** | List all memories | `ccw memory list` | -| **search** | Search memories | `ccw memory search "authentication"` | -| **export** | Export memory | `ccw memory export ` | -| **import** | Import memory | `ccw memory import "..."` | -| **embed** | Generate embeddings | `ccw memory embed ` | +AI automatically retrieves and applies relevant memories when executing tasks: -### 5.3.3 Memory Best Practices - -::: tip Tip -- **Regular cleanup**: Organize Memory weekly, delete outdated content -- **Structure**: Use standard format for easy search and reuse -- **Context**: Record decision background, not just conclusions -- **Linking**: Cross-reference related content -::: - -### 5.3.4 Memory Template - -```markdown -## Title -### Background -- **Problem**: ... -- **Impact**: ... - -### Decision -- **Solution**: ... -- **Rationale**: ... - -### Result -- **Effect**: ... -- **Lessons Learned**: ... - -### Related -- [Related Memory 1](memory-id-1) -- [Related Documentation](link) ``` +User: Help me implement the user authentication module +AI: [Automatically retrieves authentication-related decisions and conventions from memory] + Based on previous technical decisions, we use JWT + bcrypt approach... +``` + +### 5.3.3 How Users Guide Memory + +While AI manages memory automatically, users can actively reinforce: + +**Explicitly Request to Remember** +``` +User: Remember this naming convention: all API routes use kebab-case +AI: [Stores this convention in conventions memory] +``` + +**Request to Review Decisions** +``` +User: Why did we choose Redis for caching before? +AI: [Retrieves from decisions memory and responds] +``` + +**Correct Wrong Memory** +``` +User: The previous decision changed, we now use PostgreSQL instead of MongoDB +AI: [Updates related decision memory] +``` + +### 5.3.4 Memory File Locations + +- **Global Memory**: `~/.claude/projects/{project-name}/memory/` +- **Project Memory**: `.claude/memory/` or `MEMORY.md` --- -## 5.4 CodexLens Advanced Usage +## 5.4 Hook Automation -### 5.4.1 Hybrid Search +### 5.4.1 Hook Concept -Combine vector search and keyword search: - -```bash -# Pure vector search -ccw search --mode vector "user authentication" - -# Hybrid search (default) -ccw search --mode hybrid "user authentication" - -# Pure keyword search -ccw search --mode keyword "authenticate" -``` - -### 5.4.2 Call Chain Tracing - -Trace complete call chains of functions: - -```bash -# Trace up (who called me) -ccw search --trace-up "authenticateUser" - -# Trace down (who I called) -ccw search --trace-down "authenticateUser" - -# Full call chain -ccw search --trace-full "authenticateUser" -``` - -### 5.4.3 Semantic Search Techniques - -| Technique | Example | Effect | -| --- | --- | --- | -| **Functional description** | "handle user login" | Find login-related code | -| **Problem description** | "memory leak locations" | Find potential issues | -| **Pattern description** | "singleton implementation" | Find design patterns | -| **Technical description** | "using React Hooks" | Find related usage | - ---- - -## 5.5 Hook Auto-Injection - -### 5.5.1 Hook Types +Hooks are automated processes before and after AI executes tasks, users don't need to trigger manually: | Hook Type | Trigger Time | Purpose | | --- | --- | --- | -| **pre-command** | Before command execution | Inject specifications, load context | -| **post-command** | After command execution | Save Memory, update state | +| **pre-command** | Before AI thinking | Load project specs, retrieve memory | +| **post-command** | After AI completion | Save decisions, update index | | **pre-commit** | Before Git commit | Code review, standard checks | -| **file-change** | On file change | Auto-format, update index | -### 5.5.2 Hook Configuration +### 5.4.2 Configuration Example Configure in `.claude/hooks.json`: @@ -258,19 +183,14 @@ Configure in `.claude/hooks.json`: { "pre-command": [ { - "name": "inject-specs", - "description": "Inject project specifications", + "name": "load-project-specs", + "description": "Load project specifications", "command": "cat .workflow/specs/project-constraints.md" - }, - { - "name": "load-memory", - "description": "Load related Memory", - "command": "ccw memory search \"{query}\"" } ], "post-command": [ { - "name": "save-memory", + "name": "save-decisions", "description": "Save important decisions", "command": "ccw memory import \"{content}\"" } @@ -280,49 +200,54 @@ Configure in `.claude/hooks.json`: --- -## 5.6 Performance Optimization +## 5.5 ACE Semantic Search -### 5.6.1 Indexing Optimization +### 5.5.1 What is ACE -| Optimization | Description | +ACE (Augment Context Engine) is AI's **code perception capability**, enabling AI to understand the entire codebase semantically. + +### 5.5.2 How AI Uses ACE + +When users ask questions, AI automatically uses ACE to search for relevant code: + +``` +User: How is the authentication flow implemented? +AI: [Uses ACE semantic search for auth-related code] + Based on code analysis, the authentication flow is... +``` + +### 5.5.3 Configuration Reference + +| Configuration Method | Link | | --- | --- | -| **Incremental indexing** | Only index changed files | -| **Parallel indexing** | Multi-process parallel processing | -| **Caching strategy** | Vector embedding cache | - -### 5.6.2 Search Optimization - -| Optimization | Description | -| --- | --- | -| **Result caching** | Same query returns cached results | -| **Paginated loading** | Large result sets paginated | -| **Smart deduplication** | Auto-duplicate similar results | +| **Official Docs** | [Augment MCP Documentation](https://docs.augmentcode.com/context-services/mcp/overview) | +| **Proxy Tool** | [ace-tool (GitHub)](https://github.com/eastxiaodong/ace-tool) | --- -## 5.7 Quick Reference +## 5.6 Semantic Prompt Cheatsheet -### CLI Command Cheatsheet +### Common Semantic Patterns -| Command | Function | +| Goal | Semantic Description Example | | --- | --- | -| `ccw cli -p "..." --tool gemini --mode analysis` | Analysis task | -| `ccw cli -p "..." --tool qwen --mode write` | Implementation task | -| `ccw cli -p "..." --tool codex --mode review` | Review task | -| `ccw memory list` | List memories | -| `ccw memory search "..."` | Search memories | -| `ccw search "..."` | Semantic search | -| `ccw search --trace "..."` | Call chain tracing | +| **Analyze Code** | "Use Gemini to analyze the architecture design of src/auth" | +| **Security Audit** | "Use Gemini to scan for security vulnerabilities, focus on OWASP Top 10" | +| **Implement Feature** | "Let Qwen implement a cached user repository" | +| **Code Review** | "Use Codex to review recent changes" | +| **Bug Diagnosis** | "Use Gemini to analyze the root cause of this memory leak" | +| **Multi-Model Collaboration** | "Gemini designs, Qwen implements, Codex reviews" | +| **Remember Convention** | "Remember: all APIs use RESTful style" | +| **Review Decision** | "Why did we choose this tech stack before?" | -### Rule Template Cheatsheet +### Collaboration Pattern Cheatsheet -| Rule | Purpose | +| Pattern | Semantic Example | | --- | --- | -| `analysis-diagnose-bug-root-cause` | Bug analysis | -| `analysis-assess-security-risks` | Security assessment | -| `development-implement-feature` | Feature implementation | -| `development-refactor-codebase` | Code refactoring | -| `development-generate-tests` | Test generation | +| **Collaborative** | "Let Gemini and Codex jointly analyze..." | +| **Pipeline** | "Gemini designs, Qwen implements, Codex reviews" | +| **Iterative** | "Diagnose and fix until tests pass" | +| **Parallel** | "Let multiple models each provide suggestions" | --- diff --git a/docs/reference/commands-skills.md b/docs/reference/commands-skills.md index 7d0f9f5b..6997fa35 100644 --- a/docs/reference/commands-skills.md +++ b/docs/reference/commands-skills.md @@ -4,23 +4,6 @@ --- -## Table of Contents - -1. [Main Orchestrator Commands](#1-main-orchestrator-commands) -2. [Workflow Session Commands](#2-workflow-session-commands) -3. [Issue Workflow Commands](#3-issue-workflow-commands) -4. [IDAW Commands](#4-idaw-commands) -5. [With-File Workflows](#5-with-file-workflows) -6. [Cycle Workflows](#6-cycle-workflows) -7. [CLI Commands](#7-cli-commands) -8. [Memory Commands](#8-memory-commands) -9. [Team Skills](#9-team-skills) -10. [Workflow Skills](#10-workflow-skills) -11. [Utility Skills](#11-utility-skills) -12. [Codex Capabilities](#12-codex-capabilities) - ---- - ## Quick Reference Table ### Commands Quick Reference diff --git a/docs/skills/claude-collaboration.md b/docs/skills/claude-collaboration.md index a10b8298..2572070e 100644 --- a/docs/skills/claude-collaboration.md +++ b/docs/skills/claude-collaboration.md @@ -1,11 +1,6 @@ ---- -适用CLI: claude -分类: team ---- - # Claude Skills - Team Collaboration -## One-Liner +## One-Line Positioning **Team Collaboration Skills is a multi-role collaborative work orchestration system** — Through coordinator, worker roles, and message bus, it enables parallel processing and state synchronization for complex tasks. @@ -13,32 +8,83 @@ | Pain Point | Current State | Claude Code Workflow Solution | |------------|---------------|----------------------| -| **Single model limitation** | Can only call one AI model | Multi-role parallel collaboration, leveraging各自专长 | +| **Single model limitation** | Can only call one AI model | Multi-role parallel collaboration, leveraging respective strengths | | **Chaotic task orchestration** | Manual task dependency and state management | Automatic task discovery, dependency resolution, pipeline orchestration | | **Fragmented collaboration** | Team members work independently | Unified message bus, shared state, progress sync | | **Resource waste** | Repeated context loading | Wisdom accumulation, exploration cache, artifact reuse | -## Skills List +--- -| Skill | Function | Trigger | -|-------|----------|---------| -| `team-coordinate` | Universal team coordinator (dynamic role generation) | `/team-coordinate` | -| `team-lifecycle` | Full lifecycle team (spec→impl→test→review) | `/team-lifecycle` | -| `team-planex` | Plan-execute pipeline (plan while executing) | `/team-planex` | -| `team-review` | Code review team (scan→review→fix) | `/team-review` | -| `team-testing` | Testing team (strategy→generate→execute→analyze) | `/team-testing` | +## Skills Overview + +| Skill | Function | Use Case | +| --- | --- | --- | +| `team-coordinate-v2` | Universal team coordinator (dynamic role generation) | Any complex task | +| `team-lifecycle-v5` | Full lifecycle team (spec→impl→test) | Complete feature development | +| `team-planex` | Plan-execute pipeline | Issue batch processing | +| `team-review` | Code review team | Code review, vulnerability scanning | +| `team-testing` | Testing team | Test coverage, test case generation | +| `team-arch-opt` | Architecture optimization team | Refactoring, architecture analysis | +| `team-perf-opt` | Performance optimization team | Performance tuning, bottleneck analysis | +| `team-brainstorm` | Brainstorming team | Multi-angle analysis, idea generation | +| `team-frontend` | Frontend development team | UI development, design system | +| `team-uidesign` | UI design team | Design system, component specs | +| `team-issue` | Issue processing team | Issue analysis, implementation | +| `team-iterdev` | Iterative development team | Incremental delivery, agile development | +| `team-quality-assurance` | Quality assurance team | Quality scanning, defect management | +| `team-roadmap-dev` | Roadmap development team | Phased development, milestones | +| `team-tech-debt` | Tech debt team | Debt cleanup, code governance | +| `team-ultra-analyze` | Deep analysis team | Complex problem analysis, collaborative exploration | +| `team-executor-v2` | Lightweight executor | Session resume, pure execution | + +--- + +## Core Architecture + +All Team Skills share a unified **team-worker agent architecture**: + +``` +┌──────────────────────────────────────────────────────────┐ +│ Skill(skill="team-xxx", args="task description") │ +└────────────────────────┬─────────────────────────────────┘ + │ Role Router + ┌──── --role present? ────┐ + │ NO │ YES + ↓ ↓ + Orchestration Mode Role Dispatch + (auto → coordinator) (route to role.md) + │ + ┌─────────┴─────────┬───────────────┬──────────────┐ + ↓ ↓ ↓ ↓ +┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ +│ coord │ │worker 1│ │worker 2│ │worker N│ +│(orchestrate)│ │(execute)│ │(execute)│ │(execute)│ +└────────┘ └────────┘ └────────┘ └────────┘ + │ │ │ │ + └───────────────────┴───────────────┴──────────────┘ + │ + Message Bus (message bus) +``` + +**Core Components**: +- **Coordinator**: Built-in orchestrator for task analysis, dispatch, monitoring +- **Team-Worker Agent**: Unified agent, loads role-spec to execute role logic +- **Role Router**: `--role=xxx` parameter routes to role execution +- **Message Bus**: Inter-team member communication protocol +- **Shared Memory**: Cross-task knowledge accumulation (Wisdom) + +--- ## Skills Details -### team-coordinate +### team-coordinate-v2 **One-Liner**: Universal team coordinator — Dynamically generates roles and orchestrates execution based on task analysis **Trigger**: -``` -/team-coordinate -/team-coordinate --role=coordinator -/team-coordinate --role= --session= +```bash +team-coordinate +team-coordinate --role=coordinator ``` **Features**: @@ -47,17 +93,6 @@ - Fast-Advance mechanism skips coordinator to directly spawn successor tasks - Wisdom accumulates cross-task knowledge -**Role Registry**: -| Role | File | Task Prefix | Type | -|------|------|-------------|------| -| coordinator | roles/coordinator/role.md | (none) | orchestrator | -| (dynamic) | `/roles/.md` | (dynamic) | worker | - -**Pipeline**: -``` -Task Analysis → Generate Roles → Initialize Session → Create Task Chain → Spawn First Batch Workers → Loop Progress → Completion Report -``` - **Session Directory**: ``` .workflow/.team/TC--/ @@ -66,20 +101,18 @@ Task Analysis → Generate Roles → Initialize Session → Create Task Chain ├── roles/ # Dynamic role definitions ├── artifacts/ # All MD deliverables ├── wisdom/ # Cross-task knowledge -├── explorations/ # Shared exploration cache -├── discussions/ # Inline discussion records └── .msg/ # Team message bus logs ``` --- -### team-lifecycle +### team-lifecycle-v5 **One-Liner**: Full lifecycle team — Complete pipeline from specification to implementation to testing to review **Trigger**: -``` -/team-lifecycle +```bash +team-lifecycle ``` **Features**: @@ -97,164 +130,67 @@ Task Analysis → Generate Roles → Initialize Session → Create Task Chain | executor | role-specs/executor.md | IMPL-* | true | | tester | role-specs/tester.md | TEST-* | false | | reviewer | role-specs/reviewer.md | REVIEW-* | false | -| architect | role-specs/architect.md | ARCH-* | false | -| fe-developer | role-specs/fe-developer.md | DEV-FE-* | false | -| fe-qa | role-specs/fe-qa.md | QA-FE-* | false | **Pipeline Definitions**: ``` -Specification Pipeline (6 tasks): - RESEARCH-001 → DRAFT-001 → DRAFT-002 → DRAFT-003 → DRAFT-004 → QUALITY-001 - -Implementation Pipeline (4 tasks): - PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001 - -Full Lifecycle (10 tasks): - [Spec Pipeline] → PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001 - -Frontend Pipeline: - PLAN-001 → DEV-FE-001 → QA-FE-001 (GC loop, max 2 rounds) +Specification Pipeline: RESEARCH → DRAFT → QUALITY +Implementation Pipeline: PLAN → IMPL → TEST + REVIEW +Full Lifecycle: [Spec Pipeline] → [Impl Pipeline] ``` -**Quality Gate** (after QUALITY-001 completion): -``` -═════════════════════════════════════════ -SPEC PHASE COMPLETE -Quality Gate: (%) - -Dimension Scores: - Completeness: % - Consistency: % - Traceability: % - Depth: % - Coverage: % - -Available Actions: - resume -> Proceed to implementation - improve -> Auto-improve weakest dimension - improve -> Improve specific dimension - revise -> Revise specific document - recheck -> Re-run quality check - feedback -> Inject feedback, create revision -═════════════════════════════════════════ -``` - -**User Commands** (wake paused coordinator): -| Command | Action | -|---------|--------| -| `check` / `status` | Output execution status graph, no progress | -| `resume` / `continue` | Check worker status, advance next step | -| `revise [feedback]` | Create revision task + cascade downstream | -| `feedback ` | Analyze feedback impact, create targeted revision chain | -| `recheck` | Re-run QUALITY-001 quality check | -| `improve [dimension]` | Auto-improve weakest dimension in readiness-report | - --- ### team-planex -**One-Liner**: Plan-and-execute team — Planner and executor work in parallel through per-issue beat pipeline +**One-Liner**: Plan-and-execute team — Per-issue beat pipeline **Trigger**: -``` -/team-planex -/team-planex --role=planner -/team-planex --role=executor --input +```bash +team-planex +team-planex --role=planner +team-planex --role=executor --input ``` **Features**: - 2-member team (planner + executor), planner serves as lead role -- Per-issue beat: planner creates EXEC-* task immediately after completing each issue's solution +- Per-issue beat: planner creates EXEC-* task immediately after completing each issue - Solution written to intermediate artifact file, executor loads from file -- Supports multiple execution backends (agent/codex/gemini) -**Role Registry**: -| Role | File | Task Prefix | Type | -|------|------|-------------|------| -| planner | roles/planner.md | PLAN-* | pipeline (lead) | -| executor | roles/executor.md | EXEC-* | pipeline | - -**Input Types**: -| Input Type | Format | Example | -|------------|--------|---------| -| Issue IDs | Direct ID input | `--role=planner ISS-20260215-001 ISS-20260215-002` | -| Requirement text | `--text '...'` | `--role=planner --text 'Implement user authentication module'` | -| Plan file | `--plan path` | `--role=planner --plan plan/2026-02-15-auth.md` | - -**Wave Pipeline** (per-issue beat): +**Wave Pipeline**: ``` -Issue 1: planner plans solution → write artifact → conflict check → create EXEC-* → issue_ready - ↓ (executor starts immediately) -Issue 2: planner plans solution → write artifact → conflict check → create EXEC-* → issue_ready - ↓ (executor consumes in parallel) -Issue N: ... -Final: planner sends all_planned → executor completes remaining EXEC-* → finish +Issue 1: planner plans → write artifact → create EXEC-* → executor executes +Issue 2: planner plans → write artifact → create EXEC-* → executor parallel consume +Final: planner sends all_planned → executor completes remaining → finish ``` -**Execution Method Selection**: -| Executor | Backend | Use Case | -|----------|---------|----------| -| `agent` | code-developer subagent | Simple tasks, synchronous execution | -| `codex` | `ccw cli --tool codex --mode write` | Complex tasks, background execution | -| `gemini` | `ccw cli --tool gemini --mode write` | Analysis tasks, background execution | - -**User Commands**: -| Command | Action | -|---------|--------| -| `check` / `status` | Output execution status graph, no progress | -| `resume` / `continue` | Check worker status, advance next step | -| `add ` | Append new tasks to planner queue | - --- ### team-review -**One-Liner**: Code review team — Unified code scanning, vulnerability review, optimization suggestions, and auto-fix +**One-Liner**: Code review team — Unified code scanning, vulnerability review, auto-fix **Trigger**: +```bash +team-review +team-review --full # scan + review + fix +team-review --fix # fix only +team-review -q # quick scan only ``` -/team-review -/team-review --full # scan + review + fix -/team-review --fix # fix only -/team-review -q # quick scan only -``` - -**Features**: -- 4-role team (coordinator, scanner, reviewer, fixer) -- Multi-dimensional review: security, correctness, performance, maintainability -- Auto-fix loop (review → fix → verify) **Role Registry**: -| Role | File | Task Prefix | Type | -|------|------|-------------|------| -| coordinator | roles/coordinator/role.md | RC-* | orchestrator | -| scanner | roles/scanner/role.md | SCAN-* | read-only analysis | -| reviewer | roles/reviewer/role.md | REV-* | read-only analysis | -| fixer | roles/fixer/role.md | FIX-* | code generation | +| Role | Task Prefix | Type | +|------|-------------|------| +| coordinator | RC-* | orchestrator | +| scanner | SCAN-* | read-only analysis | +| reviewer | REV-* | read-only analysis | +| fixer | FIX-* | code generation | -**Pipeline** (CP-1 Linear): +**Pipeline**: ``` -coordinator dispatch - → SCAN-* (scanner: toolchain + LLM scan) - → REV-* (reviewer: deep analysis + report) - → [User confirmation] - → FIX-* (fixer: plan + execute + verify) +SCAN-* (scan) → REV-* (review) → [User confirmation] → FIX-* (fix) ``` -**Checkpoints**: -| Trigger | Location | Behavior | -|---------|----------|----------| -| Review→Fix transition | REV-* complete | Pause, show review report, wait for user `resume` to confirm fix | -| Quick mode (`-q`) | After SCAN-* | Pipeline ends after scan, no review/fix | -| Fix-only mode (`--fix`) | Entry | Skip scan/review, go directly to fixer | - -**Review Dimensions**: -| Dimension | Check Points | -|-----------|--------------| -| Security (sec) | Injection vulnerabilities, sensitive data leakage, permission control | -| Correctness (cor) | Boundary conditions, error handling, type safety | -| Performance (perf) | Algorithm complexity, I/O optimization, resource usage | -| Maintainability (maint) | Code structure, naming conventions, comment quality | +**Review Dimensions**: Security, Correctness, Performance, Maintainability --- @@ -263,75 +199,318 @@ coordinator dispatch **One-Liner**: Testing team — Progressive test coverage through Generator-Critic loop **Trigger**: +```bash +team-testing ``` -/team-testing -``` - -**Features**: -- 5-role team (coordinator, strategist, generator, executor, analyst) -- Three pipelines: Targeted, Standard, Comprehensive -- Generator-Critic loop automatically improves test coverage **Role Registry**: -| Role | File | Task Prefix | Type | -|------|------|-------------|------| -| coordinator | roles/coordinator.md | (none) | orchestrator | -| strategist | roles/strategist.md | STRATEGY-* | pipeline | -| generator | roles/generator.md | TESTGEN-* | pipeline | -| executor | roles/executor.md | TESTRUN-* | pipeline | -| analyst | roles/analyst.md | TESTANA-* | pipeline | +| Role | Task Prefix | Type | +|------|-------------|------| +| coordinator | (none) | orchestrator | +| strategist | STRATEGY-* | pipeline | +| generator | TESTGEN-* | pipeline | +| executor | TESTRUN-* | pipeline | +| analyst | TESTANA-* | pipeline | **Three Pipelines**: ``` -Targeted (small scope changes): - STRATEGY-001 → TESTGEN-001(L1 unit) → TESTRUN-001 - -Standard (progressive): - STRATEGY-001 → TESTGEN-001(L1) → TESTRUN-001(L1) → TESTGEN-002(L2) → TESTRUN-002(L2) → TESTANA-001 - -Comprehensive (full coverage): - STRATEGY-001 → [TESTGEN-001(L1) + TESTGEN-002(L2)](parallel) → [TESTRUN-001(L1) + TESTRUN-002(L2)](parallel) → TESTGEN-003(L3) → TESTRUN-003(L3) → TESTANA-001 +Targeted: STRATEGY → TESTGEN(L1) → TESTRUN +Standard: STRATEGY → TESTGEN(L1) → TESTRUN → TESTGEN(L2) → TESTRUN → TESTANA +Comprehensive: STRATEGY → [TESTGEN(L1+L2) parallel] → [TESTRUN parallel] → TESTGEN(L3) → TESTRUN → TESTANA ``` -**Generator-Critic Loop**: -``` -TESTGEN → TESTRUN → (if coverage < target) → TESTGEN-fix → TESTRUN-2 - (if coverage >= target) → next layer or TESTANA +**Test Layers**: L1: Unit (80%) → L2: Integration (60%) → L3: E2E (40%) + +--- + +### team-arch-opt + +**One-Liner**: Architecture optimization team — Analyze architecture issues, design refactoring strategies, implement improvements + +**Trigger**: +```bash +team-arch-opt ``` -**Test Layer Definitions**: -| Layer | Coverage Target | Example | -|-------|-----------------|---------| -| L1: Unit | 80% | Unit tests, function-level tests | -| L2: Integration | 60% | Integration tests, module interaction | -| L3: E2E | 40% | End-to-end tests, user scenarios | +**Role Registry**: +| Role | Task Prefix | Function | +|------|-------------|----------| +| coordinator | (none) | orchestrator | +| analyzer | ANALYZE-* | architecture analysis | +| designer | DESIGN-* | refactoring design | +| refactorer | REFACT-* | implement refactoring | +| validator | VALID-* | validate improvements | +| reviewer | REVIEW-* | code review | -**Shared Memory** (shared-memory.json): -| Role | Field | -|------|-------| -| strategist | `test_strategy` | -| generator | `generated_tests` | -| executor | `execution_results`, `defect_patterns` | -| analyst | `analysis_report`, `coverage_history` | +**Detection Scope**: Dependency cycles, coupling/cohesion, layering violations, God Classes, dead code + +--- + +### team-perf-opt + +**One-Liner**: Performance optimization team — Performance profiling, bottleneck identification, optimization implementation + +**Trigger**: +```bash +team-perf-opt +``` + +**Role Registry**: +| Role | Task Prefix | Function | +|------|-------------|----------| +| coordinator | (none) | orchestrator | +| profiler | PROFILE-* | performance profiling | +| strategist | STRAT-* | optimization strategy | +| optimizer | OPT-* | implement optimization | +| benchmarker | BENCH-* | benchmarking | +| reviewer | REVIEW-* | code review | + +--- + +### team-brainstorm + +**One-Liner**: Brainstorming team — Multi-angle creative analysis, Generator-Critic loop + +**Trigger**: +```bash +team-brainstorm +team-brainstorm --role=ideator +``` + +**Role Registry**: +| Role | Task Prefix | Function | +|------|-------------|----------| +| coordinator | (none) | orchestrator | +| ideator | IDEA-* | idea generation | +| challenger | CHALLENGE-* | critical questioning | +| synthesizer | SYNTH-* | synthesis integration | +| evaluator | EVAL-* | evaluation scoring | + +--- + +### team-frontend + +**One-Liner**: Frontend development team — Built-in ui-ux-pro-max design intelligence + +**Trigger**: +```bash +team-frontend +``` + +**Role Registry**: +| Role | Task Prefix | Function | +|------|-------------|----------| +| coordinator | (none) | orchestrator | +| analyst | ANALYZE-* | requirement analysis | +| architect | ARCH-* | architecture design | +| developer | DEV-* | frontend implementation | +| qa | QA-* | quality assurance | + +--- + +### team-uidesign + +**One-Liner**: UI design team — Design system analysis, token definition, component specs + +**Trigger**: +```bash +team-uidesign +``` + +**Role Registry**: +| Role | Task Prefix | Function | +|------|-------------|----------| +| coordinator | (none) | orchestrator | +| researcher | RESEARCH-* | design research | +| designer | DESIGN-* | design definition | +| reviewer | AUDIT-* | accessibility audit | +| implementer | BUILD-* | code implementation | + +--- + +### team-issue + +**One-Liner**: Issue processing team — Issue processing pipeline + +**Trigger**: +```bash +team-issue +``` + +**Role Registry**: +| Role | Task Prefix | Function | +|------|-------------|----------| +| coordinator | (none) | orchestrator | +| explorer | EXPLORE-* | code exploration | +| planner | PLAN-* | solution planning | +| implementer | IMPL-* | code implementation | +| reviewer | REVIEW-* | code review | +| integrator | INTEG-* | integration validation | + +--- + +### team-iterdev + +**One-Liner**: Iterative development team — Generator-Critic loop, incremental delivery + +**Trigger**: +```bash +team-iterdev +``` + +**Role Registry**: +| Role | Task Prefix | Function | +|------|-------------|----------| +| coordinator | (none) | orchestrator | +| architect | ARCH-* | architecture design | +| developer | DEV-* | feature development | +| tester | TEST-* | test validation | +| reviewer | REVIEW-* | code review | + +**Features**: Developer-Reviewer loop (max 3 rounds), Task Ledger real-time progress + +--- + +### team-quality-assurance + +**One-Liner**: Quality assurance team — Issue discovery + test validation closed loop + +**Trigger**: +```bash +team-quality-assurance +team-qa +``` + +**Role Registry**: +| Role | Task Prefix | Function | +|------|-------------|----------| +| coordinator | (none) | orchestrator | +| scout | SCOUT-* | issue discovery | +| strategist | QASTRAT-* | strategy formulation | +| generator | QAGEN-* | test generation | +| executor | QARUN-* | test execution | +| analyst | QAANA-* | result analysis | + +--- + +### team-roadmap-dev + +**One-Liner**: Roadmap development team — Phased development, milestone management + +**Trigger**: +```bash +team-roadmap-dev +``` + +**Role Registry**: +| Role | Task Prefix | Function | +|------|-------------|----------| +| coordinator | (none) | human interaction | +| planner | PLAN-* | phase planning | +| executor | EXEC-* | phase execution | +| verifier | VERIFY-* | phase validation | + +--- + +### team-tech-debt + +**One-Liner**: Tech debt team — Debt scanning, assessment, cleanup, validation + +**Trigger**: +```bash +team-tech-debt +``` + +**Role Registry**: +| Role | Task Prefix | Function | +|------|-------------|----------| +| coordinator | (none) | orchestrator | +| scanner | TDSCAN-* | debt scanning | +| assessor | TDEVAL-* | quantitative assessment | +| planner | TDPLAN-* | governance planning | +| executor | TDFIX-* | cleanup execution | +| validator | TDVAL-* | validation regression | + +--- + +### team-ultra-analyze + +**One-Liner**: Deep analysis team — Multi-role collaborative exploration, progressive understanding + +**Trigger**: +```bash +team-ultra-analyze +team-analyze +``` + +**Role Registry**: +| Role | Task Prefix | Function | +|------|-------------|----------| +| coordinator | (none) | orchestrator | +| explorer | EXPLORE-* | code exploration | +| analyst | ANALYZE-* | deep analysis | +| discussant | DISCUSS-* | discussion interaction | +| synthesizer | SYNTH-* | synthesis output | + +**Features**: Supports Quick/Standard/Deep three depth modes + +--- + +### team-executor-v2 + +**One-Liner**: Lightweight executor — Resume session, pure execution mode + +**Trigger**: +```bash +team-executor --session= +``` + +**Features**: +- No analysis, no role generation — only load and execute existing session +- Used to resume interrupted team-coordinate sessions + +--- + +## User Commands + +All Team Skills support unified user commands (wake paused coordinator): + +| Command | Action | +|---------|--------| +| `check` / `status` | Output execution status graph, no progress | +| `resume` / `continue` | Check worker status, advance next step | +| `revise ` | Create revision task + cascade downstream | +| `feedback ` | Analyze feedback impact, create targeted revision chain | + +--- + +## Best Practices + +1. **Choose the right team type**: + - General tasks → `team-coordinate-v2` + - Complete feature development → `team-lifecycle-v5` + - Issue batch processing → `team-planex` + - Code review → `team-review` + - Test coverage → `team-testing` + - Architecture optimization → `team-arch-opt` + - Performance tuning → `team-perf-opt` + - Brainstorming → `team-brainstorm` + - Frontend development → `team-frontend` + - UI design → `team-uidesign` + - Tech debt → `team-tech-debt` + - Deep analysis → `team-ultra-analyze` + +2. **Leverage inner-loop roles**: Set `inner_loop: true` to let single worker handle multiple same-prefix tasks + +3. **Wisdom accumulation**: All roles in team sessions accumulate knowledge to `wisdom/` directory + +4. **Fast-Advance**: Simple linear successor tasks automatically skip coordinator to spawn directly + +5. **Checkpoint recovery**: All team skills support session recovery via `--resume` or `resume` command + +--- ## Related Commands - [Claude Commands - Workflow](../commands/claude/workflow.md) - [Claude Commands - Session](../commands/claude/session.md) - -## Best Practices - -1. **Choose the right team type**: - - General tasks → `team-coordinate` - - Full feature development → `team-lifecycle` - - Issue batch processing → `team-planex` - - Code review → `team-review` - - Test coverage → `team-testing` - -2. **Leverage inner-loop roles**: For roles with multiple same-prefix serial tasks, set `inner_loop: true` to let a single worker handle all tasks, avoiding repeated spawn overhead - -3. **Wisdom accumulation**: All roles in team sessions accumulate knowledge to `wisdom/` directory, subsequent tasks can reuse these patterns, decisions, and conventions - -4. **Fast-Advance**: Simple linear successor tasks automatically skip coordinator to spawn directly, reducing coordination overhead - -5. **Checkpoint recovery**: All team skills support session recovery, continue interrupted sessions via `--resume` or user command `resume` diff --git a/docs/zh/features/cli.md b/docs/zh/features/cli.md index 86493611..f904951a 100644 --- a/docs/zh/features/cli.md +++ b/docs/zh/features/cli.md @@ -14,6 +14,58 @@ | **错误恢复缺失** | 工具失败只能手动重试 | 自动 fallback 到备用模型 | | **上下文管理弱** | 多轮对话上下文不连贯 | Native Resume 自动管理 | +--- + +## 语义化调用（推荐） + +::: tip 核心理念 +CLI 工具是 **AI 自动调用的能力扩展**。用户只需用自然语言描述需求，AI 会自动选择并调用合适的工具。 +::: + +### 语义触发示例 + +只需在对话中自然表达，AI 会自动调用对应工具： + +| 目标 | 用户语义描述 | AI 自动执行 | +| :--- | :--- | :--- | +| **代码分析** | "用 Gemini 分析 auth 模块的代码结构" | Gemini + 分析规则 | +| **安全审计** | "用 Gemini 扫描安全漏洞，重点关注 OWASP Top 10" | Gemini + 安全评估规则 | +| **代码实现** | "让 Qwen 实现一个带缓存的用户仓库" | Qwen + 功能实现规则 | +| **代码审查** | "用 Codex 审查这个 PR 的改动" | Codex + 审查规则 | +| **Bug 诊断** | "用 Gemini 分析这个内存泄漏的根因" | Gemini + 诊断规则 | + +### 多模型协作模式 + +通过语义描述，可以让多个 AI 模型协同工作： + +| 模式 | 描述方式 | 适用场景 | +| --- | --- | --- | +| **协作型** | "让 Gemini 和 Codex 共同分析架构问题" | 多角度分析同一问题 | +| **流水线型** | "Gemini 设计方案，Qwen 实现，Codex 审查" | 分阶段完成复杂任务 | +| **迭代型** | "用 Gemini 诊断问题，Codex 修复，迭代直到通过测试" | Bug 修复循环 | +| **并行型** | "让 Gemini 和 Qwen 分别给出优化建议" | 对比不同方案 | + +### 协作示例 + +**流水线开发** +``` +用户：我需要实现一个 WebSocket 实时通知功能。 + 请 Gemini 设计架构，Qwen 实现代码，最后用 Codex 审查。 +AI：[依次调用三个模型，完成设计→实现→审查流程] +``` + +**迭代修复** +``` +用户：测试失败了，用 Gemini 诊断原因，让 Qwen 修复，循环直到测试通过。 +AI：[自动迭代诊断-修复流程，直到问题解决] +``` + +--- + +## 底层命令参考 + +以下是 AI 自动调用时使用的底层命令，用户通常无需手动执行。 + ## 核心概念速览 | 概念 | 说明 | 示例 | diff --git a/docs/zh/guide/ch05-advanced-tips.md b/docs/zh/guide/ch05-advanced-tips.md index 4aeee0bf..0f9c64db 100644 --- a/docs/zh/guide/ch05-advanced-tips.md +++ b/docs/zh/guide/ch05-advanced-tips.md @@ -2,255 +2,180 @@ ## 一句话定位 -**高级技巧是提升效率的关键** — CLI 工具链深度使用、多模型协作优化、记忆管理最佳实践。 +**用自然语言驱动 AI 编排工具链** — 语义化 CLI 调用、多模型协作、智能记忆管理。 --- -## 5.1 CLI 工具链使用 +## 5.1 语义化工具调度 -### 5.1.1 CLI 配置 +### 5.1.1 核心理念 -CLI 工具配置文件：`~/.claude/cli-tools.json` +CCW 的 CLI 工具是 **AI 自动调用的能力扩展**，用户只需用自然语言描述需求，AI 会自动选择并调用合适的工具。 + +::: tip 关键理解 +- 用户说："用 Gemini 分析这段代码" +- AI 自动：调用 Gemini CLI + 应用分析规则 + 返回结果 +- 用户无需关心 `ccw cli` 命令细节 +::: + +### 5.1.2 可用工具与能力 + +| 工具 | 擅长领域 | 典型触发词 | +| --- | --- | --- | +| **Gemini** | 深度分析、架构设计、Bug 诊断 | "用 Gemini 分析"、"深度理解" | +| **Qwen** | 代码生成、功能实现 | "让 Qwen 实现"、"代码生成" | +| **Codex** | 代码审查、Git 操作 | "用 Codex 审查"、"代码评审" | +| **OpenCode** | 开源多模型 | "用 OpenCode" | + +### 5.1.3 语义触发示例 + +只需在对话中自然表达，AI 会自动调用对应工具： + +| 目标 | 用户语义描述 | AI 自动执行 | +| :--- | :--- | :--- | +| **安全评估** | "用 Gemini 扫描认证模块的安全漏洞" | Gemini + 安全分析规则 | +| **代码实现** | "让 Qwen 帮我实现一个速率限制中间件" | Qwen + 功能实现规则 | +| **代码审查** | "用 Codex 审查这个 PR 的改动" | Codex + 审查规则 | +| **Bug 诊断** | "用 Gemini 分析这个内存泄漏的根因" | Gemini + 诊断规则 | + +### 5.1.4 底层配置（可选了解） + +AI 调用工具的配置文件位于 `~/.claude/cli-tools.json`： ```json { - "version": "3.3.0", "tools": { "gemini": { "enabled": true, "primaryModel": "gemini-2.5-flash", - "secondaryModel": "gemini-2.5-flash", - "tags": ["分析", "Debug"], - "type": "builtin" + "tags": ["分析", "Debug"] }, "qwen": { "enabled": true, "primaryModel": "coder-model", - "secondaryModel": "coder-model", - "tags": [], - "type": "builtin" - }, - "codex": { - "enabled": true, - "primaryModel": "gpt-5.2", - "secondaryModel": "gpt-5.2", - "tags": [], - "type": "builtin" + "tags": ["实现"] } } } ``` -### 5.1.2 标签路由 - -根据任务类型自动选择模型： - -| 标签 | 适用模型 | 任务类型 | -| --- | --- | --- | -| **分析** | Gemini | 代码分析、架构设计 | -| **Debug** | Gemini | 根因分析、问题诊断 | -| **实现** | Qwen | 功能开发、代码生成 | -| **审查** | Codex | 代码审查、Git 操作 | - -### 5.1.3 CLI 命令模板 - -#### 分析任务 - -```bash -ccw cli -p "PURPOSE: 识别安全漏洞 -TASK: • 扫描 SQL 注入 • 检查 XSS • 验证 CSRF -MODE: analysis -CONTEXT: @src/auth/**/* -EXPECTED: 安全报告，含严重性分级和修复建议 -CONSTRAINTS: 聚焦认证模块" --tool gemini --mode analysis --rule analysis-assess-security-risks -``` - -#### 实现任务 - -```bash -ccw cli -p "PURPOSE: 实现速率限制 -TASK: • 创建中间件 • 配置路由 • Redis 后端 -MODE: write -CONTEXT: @src/middleware/**/* @src/config/**/* -EXPECTED: 生产代码 + 单元测试 + 集成测试 -CONSTRAINTS: 遵循现有中间件模式" --tool qwen --mode write --rule development-implement-feature -``` - -### 5.1.4 规则模板 - -| 规则 | 用途 | -| --- | --- | -| **analysis-diagnose-bug-root-cause** | Bug 根因分析 | -| **analysis-analyze-code-patterns** | 代码模式分析 | -| **analysis-review-architecture** | 架构审查 | -| **analysis-assess-security-risks** | 安全评估 | -| **development-implement-feature** | 功能实现 | -| **development-refactor-codebase** | 代码重构 | -| **development-generate-tests** | 测试生成 | +::: info 说明 +标签（tags）帮助 AI 根据任务类型自动选择最合适的工具。用户通常无需修改此配置。 +::: --- ## 5.2 多模型协作 -### 5.2.1 模型选择指南 +### 5.2.1 协作模式 -| 任务 | 推荐模型 | 理由 | +通过语义描述，可以让多个 AI 模型协同工作： + +| 模式 | 描述方式 | 适用场景 | | --- | --- | --- | -| **代码分析** | Gemini | 擅长深度代码理解和模式识别 | +| **协作型** | "让 Gemini 和 Codex 共同分析架构问题" | 多角度分析同一问题 | +| **流水线型** | "Gemini 设计方案，Qwen 实现，Codex 审查" | 分阶段完成复杂任务 | +| **迭代型** | "用 Gemini 诊断问题，Codex 修复，迭代直到通过测试" | Bug 修复循环 | +| **并行型** | "让 Gemini 和 Qwen 分别给出优化建议" | 对比不同方案 | + +### 5.2.2 语义示例 + +**协作分析** +``` +用户：让 Gemini 和 Codex 共同分析 src/auth 模块的安全性和性能问题 +AI：[自动调用两个模型，综合分析结果] +``` + +**流水线开发** +``` +用户：我需要实现一个 WebSocket 实时通知功能。 + 请 Gemini 设计架构，Qwen 实现代码，最后用 Codex 审查。 +AI：[依次调用三个模型，完成设计→实现→审查流程] +``` + +**迭代修复** +``` +用户：测试失败了，用 Gemini 诊断原因，让 Qwen 修复，循环直到测试通过。 +AI：[自动迭代诊断-修复流程，直到问题解决] +``` + +### 5.2.3 模型选择建议 + +| 任务类型 | 推荐模型 | 理由 | +| --- | --- | --- | +| **架构分析** | Gemini | 擅长深度理解和模式识别 | | **Bug 诊断** | Gemini | 强大的根因分析能力 | -| **功能开发** | Qwen | 代码生成效率高 | -| **代码审查** | Codex (GPT) | Git 集成好，审查格式标准 | -| **长文本** | Claude | 上下文窗口大 | - -### 5.2.2 协作模式 - -#### 串行协作 - -```bash -# 步骤 1: Gemini 分析 -ccw cli -p "分析代码架构" --tool gemini --mode analysis - -# 步骤 2: Qwen 实现 -ccw cli -p "基于分析结果实现功能" --tool qwen --mode write - -# 步骤 3: Codex 审查 -ccw cli -p "审查实现代码" --tool codex --mode review -``` - -#### 并行协作 - -使用 `--tool gemini` 和 `--tool qwen` 同时分析同一问题： - -```bash -# 终端 1 -ccw cli -p "从性能角度分析" --tool gemini --mode analysis & - -# 终端 2 -ccw cli -p "从安全角度分析" --tool codex --mode analysis & -``` - -### 5.2.3 会话恢复 - -跨模型会话恢复： - -```bash -# 第一次调用 -ccw cli -p "分析认证模块" --tool gemini --mode analysis - -# 恢复会话继续 -ccw cli -p "基于上次分析，设计改进方案" --tool qwen --mode write --resume -``` +| **代码生成** | Qwen | 代码生成效率高 | +| **代码审查** | Codex | Git 集成好，审查格式标准 | +| **长文本处理** | Claude | 上下文窗口大 | --- -## 5.3 Memory 管理 +## 5.3 智能记忆管理 -### 5.3.1 Memory 分类 +### 5.3.1 记忆系统概述 -| 分类 | 用途 | 示例内容 | +CCW 的记忆系统是 **AI 自主管理** 的知识库，包括： + +| 分类 | 用途 | 示例 | | --- | --- | --- | -| **learnings** | 学习心得 | 新技术使用经验 | -| **decisions** | 架构决策 | 技术选型理由 | -| **conventions** | 编码规范 | 命名约定、模式 | -| **issues** | 已知问题 | Bug、限制、TODO | +| **learnings** | 学习心得 | 新技术使用经验、最佳实践 | +| **decisions** | 架构决策 | 技术选型理由、设计权衡 | +| **conventions** | 编码规范 | 命名约定、代码风格 | +| **issues** | 已知问题 | Bug 记录、限制说明 | -### 5.3.2 Memory 命令 +### 5.3.2 记忆的自动使用 -| 命令 | 功能 | 示例 | -| --- | --- | --- | -| **list** | 列出所有记忆 | `ccw memory list` | -| **search** | 搜索记忆 | `ccw memory search "认证"` | -| **export** | 导出记忆 | `ccw memory export ` | -| **import** | 导入记忆 | `ccw memory import "..."` | -| **embed** | 生成嵌入 | `ccw memory embed ` | +AI 在执行任务时会自动检索和应用相关记忆： -### 5.3.3 Memory 最佳实践 - -::: tip 提示 -- **定期整理**: 每周整理一次 Memory，删除过时内容 -- **结构化**: 使用标准格式，便于搜索和复用 -- **上下文**: 记录决策背景，不只是结论 -- **链接**: 相关内容互相引用 -::: - -### 5.3.4 Memory 模板 - -```markdown -## 标题 -### 背景 -- **问题**: ... -- **影响**: ... - -### 决策 -- **方案**: ... -- **理由**: ... - -### 结果 -- **效果**: ... -- **经验**: ... - -### 相关 -- [相关记忆 1](memory-id-1) -- [相关文档](link) ``` +用户：帮我实现用户认证模块 +AI：[自动检索记忆中的认证相关 decisions 和 conventions] + 根据之前的技术决策，我们使用 JWT + bcrypt 方案... +``` + +### 5.3.3 用户如何引导记忆 + +虽然 AI 自动管理记忆，但用户可以主动强化： + +**明确要求记住** +``` +用户：记住这个命名规范：所有 API 路由使用 kebab-case +AI：[将此规范存入 conventions 记忆] +``` + +**要求回顾决策** +``` +用户：我们之前为什么选择 Redis 做缓存？ +AI：[检索 decisions 记忆并回答] +``` + +**纠正错误记忆** +``` +用户：之前的决定改了，我们现在用 PostgreSQL 代替 MongoDB +AI：[更新相关 decision 记忆] +``` + +### 5.3.4 记忆文件位置 + +- **全局记忆**: `~/.claude/projects/{project-name}/memory/` +- **项目记忆**: `.claude/memory/` 或 `MEMORY.md` --- -## 5.4 CodexLens 高级用法 +## 5.4 Hook 自动化 -### 5.4.1 混合搜索 +### 5.4.1 Hook 概念 -结合向量搜索和关键词搜索： - -```bash -# 纯向量搜索 -ccw search --mode vector "用户认证" - -# 混合搜索（默认） -ccw search --mode hybrid "用户认证" - -# 纯关键词搜索 -ccw search --mode keyword "authenticate" -``` - -### 5.4.2 调用链追踪 - -追踪函数的完整调用链： - -```bash -# 向上追踪（谁调用了我） -ccw search --trace-up "authenticateUser" - -# 向下追踪（我调用了谁） -ccw search --trace-down "authenticateUser" - -# 完整调用链 -ccw search --trace-full "authenticateUser" -``` - -### 5.4.3 语义搜索技巧 - -| 技巧 | 示例 | 效果 | -| --- | --- | --- | -| **功能描述** | "处理用户登录" | 找到登录相关代码 | -| **问题描述** | "内存泄漏的地方" | 找到潜在问题 | -| **模式描述** | "单例模式的实现" | 找到设计模式 | -| **技术描述** | "使用 React Hooks" | 找到相关用法 | - ---- - -## 5.5 Hook 自动注入 - -### 5.5.1 Hook 类型 +Hook 是 AI 执行任务前后的自动化流程，用户无需手动触发： | Hook 类型 | 触发时机 | 用途 | | --- | --- | --- | -| **pre-command** | 命令执行前 | 注入规范、加载上下文 | -| **post-command** | 命令执行后 | 保存 Memory、更新状态 | +| **pre-command** | AI 思考前 | 加载项目规范、检索记忆 | +| **post-command** | AI 完成后 | 保存决策、更新索引 | | **pre-commit** | Git 提交前 | 代码审查、规范检查 | -| **file-change** | 文件变更时 | 自动格式化、更新索引 | -### 5.5.2 Hook 配置 +### 5.4.2 配置示例 在 `.claude/hooks.json` 中配置： @@ -258,19 +183,14 @@ ccw search --trace-full "authenticateUser" { "pre-command": [ { - "name": "inject-specs", - "description": "注入项目规范", + "name": "load-project-specs", + "description": "加载项目规范", "command": "cat .workflow/specs/project-constraints.md" - }, - { - "name": "load-memory", - "description": "加载相关 Memory", - "command": "ccw memory search \"{query}\"" } ], "post-command": [ { - "name": "save-memory", + "name": "save-decisions", "description": "保存重要决策", "command": "ccw memory import \"{content}\"" } @@ -280,49 +200,54 @@ ccw search --trace-full "authenticateUser" --- -## 5.6 性能优化 +## 5.5 ACE 语义搜索 -### 5.6.1 索引优化 +### 5.5.1 什么是 ACE -| 优化项 | 说明 | +ACE (Augment Context Engine) 是 AI 的 **代码感知能力**，让 AI 能理解整个代码库的语义。 + +### 5.5.2 AI 如何使用 ACE + +当用户提问时，AI 会自动使用 ACE 搜索相关代码： + +``` +用户：认证流程是怎么实现的？ +AI：[通过 ACE 语义搜索 auth 相关代码] + 根据代码分析，认证流程是... +``` + +### 5.5.3 配置参考 + +| 配置方式 | 链接 | | --- | --- | -| **增量索引** | 只索引变更文件 | -| **并行索引** | 多进程并行处理 | -| **缓存策略** | 向量嵌入缓存 | - -### 5.6.2 搜索优化 - -| 优化项 | 说明 | -| --- | --- | -| **结果缓存** | 相同查询返回缓存 | -| **分页加载** | 大结果集分页返回 | -| **智能去重** | 相似结果自动去重 | +| **官方文档** | [Augment MCP Documentation](https://docs.augmentcode.com/context-services/mcp/overview) | +| **代理工具** | [ace-tool (GitHub)](https://github.com/eastxiaodong/ace-tool) | --- -## 5.7 快速参考 +## 5.6 语义提示速查 -### CLI 命令速查 +### 常用语义模式 -| 命令 | 功能 | +| 目标 | 语义描述示例 | | --- | --- | -| `ccw cli -p "..." --tool gemini --mode analysis` | 分析任务 | -| `ccw cli -p "..." --tool qwen --mode write` | 实现任务 | -| `ccw cli -p "..." --tool codex --mode review` | 审查任务 | -| `ccw memory list` | 列出记忆 | -| `ccw memory search "..."` | 搜索记忆 | -| `ccw search "..."` | 语义搜索 | -| `ccw search --trace "..."` | 调用链追踪 | +| **分析代码** | "用 Gemini 分析 src/auth 的架构设计" | +| **安全审计** | "用 Gemini 扫描安全漏洞，重点关注 OWASP Top 10" | +| **实现功能** | "让 Qwen 实现一个带缓存的用户仓库" | +| **代码审查** | "用 Codex 审查最近的改动" | +| **Bug 诊断** | "用 Gemini 分析这个内存泄漏的根因" | +| **多模型协作** | "Gemini 设计方案，Qwen 实现，Codex 审查" | +| **记住规范** | "记住：所有 API 使用 RESTful 风格" | +| **回顾决策** | "我们之前为什么选择这个技术栈？" | -### 规则模板速查 +### 协作模式速查 -| 规则 | 用途 | +| 模式 | 语义示例 | | --- | --- | -| `analysis-diagnose-bug-root-cause` | Bug 分析 | -| `analysis-assess-security-risks` | 安全评估 | -| `development-implement-feature` | 功能实现 | -| `development-refactor-codebase` | 代码重构 | -| `development-generate-tests` | 测试生成 | +| **协作** | "让 Gemini 和 Codex 共同分析..." | +| **流水线** | "Gemini 设计，Qwen 实现，Codex 审查" | +| **迭代** | "诊断并修复，直到测试通过" | +| **并行** | "让多个模型分别给出建议" | --- diff --git a/docs/zh/reference/commands-skills.md b/docs/zh/reference/commands-skills.md index 7d300436..28e8dc8a 100644 --- a/docs/zh/reference/commands-skills.md +++ b/docs/zh/reference/commands-skills.md @@ -4,23 +4,6 @@ --- -## 目录 - -1. [主编排器命令](#1-主编排器命令) -2. [工作流会话命令](#2-工作流会话命令) -3. [Issue 工作流命令](#3-issue-工作流命令) -4. [IDAW 命令](#4-idaw-命令) -5. [With-File 工作流](#5-with-file-工作流) -6. [循环工作流](#6-循环工作流) -7. [CLI 命令](#7-cli-命令) -8. [记忆命令](#8-记忆命令) -9. [团队技能](#9-团队技能) -10. [工作流技能](#10-工作流技能) -11. [实用技能](#11-实用技能) -12. [Codex 能力](#12-codex-能力) - ---- - ## 快速参考表 ### 命令快速参考 diff --git a/docs/zh/skills/claude-collaboration.md b/docs/zh/skills/claude-collaboration.md index b04ffeae..89d1e57a 100644 --- a/docs/zh/skills/claude-collaboration.md +++ b/docs/zh/skills/claude-collaboration.md @@ -13,27 +13,78 @@ | **协作流程割裂** | 团队成员各自为战 | 统一消息总线、共享状态、进度同步 | | **资源浪费** | 重复上下文加载 | Wisdom 累积、探索缓存、产物复用 | -## Skills 列表 +--- -| Skill | 功能 | 触发方式 | +## Skills 总览 + +| Skill | 功能 | 适用场景 | | --- | --- | --- | -| `team-coordinate` | 通用团队协调器（动态角色生成） | `/team-coordinate` | -| `team-lifecycle-v5` | 全生命周期团队（规范→实现→测试→审查） | `/team-lifecycle` | -| `team-planex` | 规划-执行流水线（边规划边执行） | `/team-planex` | -| `team-review` | 代码审查团队（扫描→审查→修复） | `/team-review` | -| `team-testing` | 测试团队（策略→生成→执行→分析） | `/team-testing` | +| `team-coordinate-v2` | 通用团队协调器（动态角色生成） | 任意复杂任务 | +| `team-lifecycle-v5` | 全生命周期团队（规范→实现→测试） | 完整功能开发 | +| `team-planex` | 规划-执行流水线 | Issue 批处理 | +| `team-review` | 代码审查团队 | 代码审查、漏洞扫描 | +| `team-testing` | 测试团队 | 测试覆盖、用例生成 | +| `team-arch-opt` | 架构优化团队 | 重构、架构分析 | +| `team-perf-opt` | 性能优化团队 | 性能调优、瓶颈分析 | +| `team-brainstorm` | 头脑风暴团队 | 多角度分析、创意生成 | +| `team-frontend` | 前端开发团队 | UI 开发、设计系统 | +| `team-uidesign` | UI 设计团队 | 设计系统、组件规范 | +| `team-issue` | Issue 处理团队 | Issue 分析、实现 | +| `team-iterdev` | 迭代开发团队 | 增量交付、敏捷开发 | +| `team-quality-assurance` | 质量保证团队 | 质量扫描、缺陷管理 | +| `team-roadmap-dev` | 路线图开发团队 | 分阶段开发、里程碑 | +| `team-tech-debt` | 技术债务团队 | 债务清理、代码治理 | +| `team-ultra-analyze` | 深度分析团队 | 复杂问题分析、协作探索 | +| `team-executor-v2` | 轻量执行器 | 会话恢复、纯执行 | + +--- + +## 核心架构 + +所有 Team Skills 共享统一的 **team-worker agent 架构**： + +``` +┌──────────────────────────────────────────────────────────┐ +│ Skill(skill="team-xxx", args="任务描述") │ +└────────────────────────┬─────────────────────────────────┘ + │ Role Router + ┌──── --role present? ────┐ + │ NO │ YES + ↓ ↓ + Orchestration Mode Role Dispatch + (auto → coordinator) (route to role.md) + │ + ┌─────────┴─────────┬───────────────┬──────────────┐ + ↓ ↓ ↓ ↓ +┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ +│ coord │ │worker 1│ │worker 2│ │worker N│ +│ (编排) │ │(执行) │ │(执行) │ │(执行) │ +└────────┘ └────────┘ └────────┘ └────────┘ + │ │ │ │ + └───────────────────┴───────────────┴──────────────┘ + │ + Message Bus (消息总线) +``` + +**核心组件**: +- **Coordinator**: 内置编排器，负责任务分析、派发、监控 +- **Team-Worker Agent**: 统一代理，加载 role-spec 执行角色逻辑 +- **Role Router**: `--role=xxx` 参数路由到角色执行 +- **Message Bus**: 团队成员间通信协议 +- **Shared Memory**: 跨任务知识累积 (Wisdom) + +--- ## Skills 详解 -### team-coordinate +### team-coordinate-v2 **一句话定位**: 通用团队协调器 — 根据任务分析动态生成角色并编排执行 **触发**: -``` -/team-coordinate -/team-coordinate --role=coordinator -/team-coordinate --role= --session= +```bash +team-coordinate +team-coordinate --role=coordinator ``` **功能**: @@ -42,17 +93,6 @@ - Fast-Advance 机制跳过协调器直接派生后继任务 - Wisdom 累积跨任务知识 -**角色注册表**: -| 角色 | 文件 | 任务前缀 | 类型 | -|------|------|----------|------| -| coordinator | roles/coordinator/role.md | (无) | 编排器 | -| (动态) | `/roles/.md` | (动态) | 工作者 | - -**流水线**: -``` -任务分析 → 生成角色 → 初始化会话 → 创建任务链 → 派生首批工作者 → 循环推进 → 完成报告 -``` - **会话目录**: ``` .workflow/.team/TC--/ @@ -61,8 +101,6 @@ ├── roles/ # 动态角色定义 ├── artifacts/ # 所有 MD 交付产物 ├── wisdom/ # 跨任务知识 -├── explorations/ # 共享探索缓存 -├── discussions/ # 内联讨论记录 └── .msg/ # 团队消息总线日志 ``` @@ -73,8 +111,8 @@ **一句话定位**: 全生命周期团队 — 从规范到实现到测试到审查的完整流水线 **触发**: -``` -/team-lifecycle +```bash +team-lifecycle ``` **功能**: @@ -92,164 +130,67 @@ | executor | role-specs/executor.md | IMPL-* | true | | tester | role-specs/tester.md | TEST-* | false | | reviewer | role-specs/reviewer.md | REVIEW-* | false | -| architect | role-specs/architect.md | ARCH-* | false | -| fe-developer | role-specs/fe-developer.md | DEV-FE-* | false | -| fe-qa | role-specs/fe-qa.md | QA-FE-* | false | **流水线定义**: ``` -规范流水线 (6 任务): - RESEARCH-001 → DRAFT-001 → DRAFT-002 → DRAFT-003 → DRAFT-004 → QUALITY-001 - -实现流水线 (4 任务): - PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001 - -全生命周期 (10 任务): - [规范流水线] → PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001 - -前端流水线: - PLAN-001 → DEV-FE-001 → QA-FE-001 (GC 循环，最多 2 轮) +规范流水线: RESEARCH → DRAFT → QUALITY +实现流水线: PLAN → IMPL → TEST + REVIEW +全生命周期: [规范流水线] → [实现流水线] ``` -**质量关卡** (QUALITY-001 完成后): -``` -═════════════════════════════════════════ -SPEC PHASE COMPLETE -Quality Gate: (%) - -Dimension Scores: - Completeness: % - Consistency: % - Traceability: % - Depth: % - Coverage: % - -Available Actions: - resume -> Proceed to implementation - improve -> Auto-improve weakest dimension - improve -> Improve specific dimension - revise -> Revise specific document - recheck -> Re-run quality check - feedback -> Inject feedback, create revision -═════════════════════════════════════════ -``` - -**用户命令** (唤醒暂停的协调器): -| 命令 | 动作 | -|------|------| -| `check` / `status` | 输出执行状态图，不推进 | -| `resume` / `continue` | 检查工作者状态，推进下一步 | -| `revise [feedback]` | 创建修订任务 + 级联下游 | -| `feedback ` | 分析反馈影响，创建定向修订链 | -| `recheck` | 重新运行 QUALITY-001 质量检查 | -| `improve [dimension]` | 自动改进 readiness-report 中最弱维度 | - --- ### team-planex -**一句话定位**: 边规划边执行团队 — 通过逐 Issue 节拍流水线实现 planner 和 executor 并行工作 +**一句话定位**: 边规划边执行团队 — 逐 Issue 节拍流水线 **触发**: -``` -/team-planex -/team-planex --role=planner -/team-planex --role=executor --input +```bash +team-planex +team-planex --role=planner +team-planex --role=executor --input ``` **功能**: - 2 成员团队（planner + executor），planner 担任 lead 角色 -- 逐 Issue 节拍：planner 每完成一个 issue 的 solution 后立即创建 EXEC-* 任务 +- 逐 Issue 节拍：planner 完成后立即创建 EXEC-* 任务 - Solution 写入中间产物文件，executor 从文件加载 -- 支持多种执行后端（agent/codex/gemini） -**角色注册表**: -| 角色 | 文件 | 任务前缀 | 类型 | -|------|------|----------|------| -| planner | roles/planner.md | PLAN-* | pipeline (lead) | -| executor | roles/executor.md | EXEC-* | pipeline | - -**输入类型**: -| 输入类型 | 格式 | 示例 | -|----------|------|------| -| Issue IDs | 直接传入 ID | `--role=planner ISS-20260215-001 ISS-20260215-002` | -| 需求文本 | `--text '...'` | `--role=planner --text '实现用户认证模块'` | -| Plan 文件 | `--plan path` | `--role=planner --plan plan/2026-02-15-auth.md` | - -**Wave Pipeline** (逐 Issue 节拍): +**Wave Pipeline**: ``` -Issue 1: planner 规划 solution → 写中间产物 → 冲突检查 → 创建 EXEC-* → issue_ready - ↓ (executor 立即开始) -Issue 2: planner 规划 solution → 写中间产物 → 冲突检查 → 创建 EXEC-* → issue_ready - ↓ (executor 并行消费) -Issue N: ... -Final: planner 发送 all_planned → executor 完成剩余 EXEC-* → 结束 +Issue 1: planner 规划 → 写产物 → 创建 EXEC-* → executor 执行 +Issue 2: planner 规划 → 写产物 → 创建 EXEC-* → executor 并行消费 +Final: planner 发送 all_planned → executor 完成剩余 → 结束 ``` -**执行方法选择**: -| 执行器 | 后端 | 适用场景 | -|--------|------|----------| -| `agent` | code-developer subagent | 简单任务、同步执行 | -| `codex` | `ccw cli --tool codex --mode write` | 复杂任务、后台执行 | -| `gemini` | `ccw cli --tool gemini --mode write` | 分析类任务、后台执行 | - -**用户命令**: -| 命令 | 动作 | -|------|------| -| `check` / `status` | 输出执行状态图，不推进 | -| `resume` / `continue` | 检查工作者状态，推进下一步 | -| `add ` | 追加新任务到 planner 队列 | - --- ### team-review -**一句话定位**: 代码审查团队 — 统一的代码扫描、漏洞审查、优化建议和自动修复 +**一句话定位**: 代码审查团队 — 统一的代码扫描、漏洞审查、自动修复 **触发**: +```bash +team-review +team-review --full # scan + review + fix +team-review --fix # fix only +team-review -q # quick scan only ``` -/team-review -/team-review --full # scan + review + fix -/team-review --fix # fix only -/team-review -q # quick scan only -``` - -**功能**: -- 4 角色团队（coordinator, scanner, reviewer, fixer） -- 多维度审查：安全性、正确性、性能、可维护性 -- 自动修复循环（审查 → 修复 → 验证） **角色注册表**: -| 角色 | 文件 | 任务前缀 | 类型 | -|------|------|----------|------| -| coordinator | roles/coordinator/role.md | RC-* | 编排器 | -| scanner | roles/scanner/role.md | SCAN-* | 只读分析 | -| reviewer | roles/reviewer/role.md | REV-* | 只读分析 | -| fixer | roles/fixer/role.md | FIX-* | 代码生成 | +| 角色 | 任务前缀 | 类型 | +|------|----------|------| +| coordinator | RC-* | 编排器 | +| scanner | SCAN-* | 只读分析 | +| reviewer | REV-* | 只读分析 | +| fixer | FIX-* | 代码生成 | -**流水线** (CP-1 Linear): +**流水线**: ``` -coordinator dispatch - → SCAN-* (scanner: 工具链 + LLM 扫描) - → REV-* (reviewer: 深度分析 + 报告) - → [用户确认] - → FIX-* (fixer: 规划 + 执行 + 验证) +SCAN-* (扫描) → REV-* (审查) → [用户确认] → FIX-* (修复) ``` -**检查点**: -| 触发 | 位置 | 行为 | -|------|------|------| -| Review→Fix 过渡 | REV-* 完成 | 暂停，展示审查报告，等待用户 `resume` 确认修复 | -| 快速模式 (`-q`) | SCAN-* 后 | 流水线在扫描后结束，无审查/修复 | -| 仅修复模式 (`--fix`) | 入口 | 跳过扫描/审查，直接进入 fixer | - -**审查维度**: -| 维度 | 检查点 | -|------|--------| -| 安全性 (sec) | 注入漏洞、敏感信息泄露、权限控制 | -| 正确性 (cor) | 边界条件、错误处理、类型安全 | -| 性能 (perf) | 算法复杂度、I/O 优化、资源使用 | -| 可维护性 (maint) | 代码结构、命名规范、注释质量 | +**审查维度**: 安全性、正确性、性能、可维护性 --- @@ -258,75 +199,318 @@ coordinator dispatch **一句话定位**: 测试团队 — 通过 Generator-Critic 循环实现渐进式测试覆盖 **触发**: +```bash +team-testing ``` -/team-testing -``` - -**功能**: -- 5 角色团队（coordinator, strategist, generator, executor, analyst） -- 三种流水线：Targeted、Standard、Comprehensive -- Generator-Critic 循环自动改进测试覆盖率 **角色注册表**: -| 角色 | 文件 | 任务前缀 | 类型 | -|------|------|----------|------| -| coordinator | roles/coordinator.md | (无) | 编排器 | -| strategist | roles/strategist.md | STRATEGY-* | pipeline | -| generator | roles/generator.md | TESTGEN-* | pipeline | -| executor | roles/executor.md | TESTRUN-* | pipeline | -| analyst | roles/analyst.md | TESTANA-* | pipeline | +| 角色 | 任务前缀 | 类型 | +|------|----------|------| +| coordinator | (无) | 编排器 | +| strategist | STRATEGY-* | pipeline | +| generator | TESTGEN-* | pipeline | +| executor | TESTRUN-* | pipeline | +| analyst | TESTANA-* | pipeline | **三种流水线**: ``` -Targeted (小范围变更): - STRATEGY-001 → TESTGEN-001(L1 unit) → TESTRUN-001 - -Standard (渐进式): - STRATEGY-001 → TESTGEN-001(L1) → TESTRUN-001(L1) → TESTGEN-002(L2) → TESTRUN-002(L2) → TESTANA-001 - -Comprehensive (完整覆盖): - STRATEGY-001 → [TESTGEN-001(L1) + TESTGEN-002(L2)](并行) → [TESTRUN-001(L1) + TESTRUN-002(L2)](并行) → TESTGEN-003(L3) → TESTRUN-003(L3) → TESTANA-001 +Targeted: STRATEGY → TESTGEN(L1) → TESTRUN +Standard: STRATEGY → TESTGEN(L1) → TESTRUN → TESTGEN(L2) → TESTRUN → TESTANA +Comprehensive: STRATEGY → [TESTGEN(L1+L2) 并行] → [TESTRUN 并行] → TESTGEN(L3) → TESTRUN → TESTANA ``` -**Generator-Critic 循环**: -``` -TESTGEN → TESTRUN → (如果覆盖率 < 目标) → TESTGEN-fix → TESTRUN-2 - (如果覆盖率 >= 目标) → 下一层或 TESTANA +**测试层**: L1: Unit (80%) → L2: Integration (60%) → L3: E2E (40%) + +--- + +### team-arch-opt + +**一句话定位**: 架构优化团队 — 分析架构问题、设计重构策略、实施改进 + +**触发**: +```bash +team-arch-opt ``` -**测试层定义**: -| 层级 | 覆盖目标 | 示例 | +**角色注册表**: +| 角色 | 任务前缀 | 功能 | |------|----------|------| -| L1: Unit | 80% | 单元测试、函数级测试 | -| L2: Integration | 60% | 集成测试、模块间交互 | -| L3: E2E | 40% | 端到端测试、用户场景 | +| coordinator | (无) | 编排器 | +| analyzer | ANALYZE-* | 架构分析 | +| designer | DESIGN-* | 重构设计 | +| refactorer | REFACT-* | 实施重构 | +| validator | VALID-* | 验证改进 | +| reviewer | REVIEW-* | 代码审查 | -**共享内存** (shared-memory.json): -| 角色 | 字段 | +**检测范围**: 依赖循环、耦合/内聚、分层违规、上帝类、死代码 + +--- + +### team-perf-opt + +**一句话定位**: 性能优化团队 — 性能分析、瓶颈识别、优化实施 + +**触发**: +```bash +team-perf-opt +``` + +**角色注册表**: +| 角色 | 任务前缀 | 功能 | +|------|----------|------| +| coordinator | (无) | 编排器 | +| profiler | PROFILE-* | 性能分析 | +| strategist | STRAT-* | 优化策略 | +| optimizer | OPT-* | 实施优化 | +| benchmarker | BENCH-* | 基准测试 | +| reviewer | REVIEW-* | 代码审查 | + +--- + +### team-brainstorm + +**一句话定位**: 头脑风暴团队 — 多角度创意分析、Generator-Critic 循环 + +**触发**: +```bash +team-brainstorm +team-brainstorm --role=ideator +``` + +**角色注册表**: +| 角色 | 任务前缀 | 功能 | +|------|----------|------| +| coordinator | (无) | 编排器 | +| ideator | IDEA-* | 创意生成 | +| challenger | CHALLENGE-* | 批判质疑 | +| synthesizer | SYNTH-* | 综合整合 | +| evaluator | EVAL-* | 评估评分 | + +--- + +### team-frontend + +**一句话定位**: 前端开发团队 — 内置 ui-ux-pro-max 设计智能 + +**触发**: +```bash +team-frontend +``` + +**角色注册表**: +| 角色 | 任务前缀 | 功能 | +|------|----------|------| +| coordinator | (无) | 编排器 | +| analyst | ANALYZE-* | 需求分析 | +| architect | ARCH-* | 架构设计 | +| developer | DEV-* | 前端实现 | +| qa | QA-* | 质量保证 | + +--- + +### team-uidesign + +**一句话定位**: UI 设计团队 — 设计系统分析、Token 定义、组件规范 + +**触发**: +```bash +team-uidesign +``` + +**角色注册表**: +| 角色 | 任务前缀 | 功能 | +|------|----------|------| +| coordinator | (无) | 编排器 | +| researcher | RESEARCH-* | 设计研究 | +| designer | DESIGN-* | 设计定义 | +| reviewer | AUDIT-* | 无障碍审计 | +| implementer | BUILD-* | 代码实现 | + +--- + +### team-issue + +**一句话定位**: Issue 处理团队 — Issue 处理流水线 + +**触发**: +```bash +team-issue +``` + +**角色注册表**: +| 角色 | 任务前缀 | 功能 | +|------|----------|------| +| coordinator | (无) | 编排器 | +| explorer | EXPLORE-* | 代码探索 | +| planner | PLAN-* | 方案规划 | +| implementer | IMPL-* | 代码实现 | +| reviewer | REVIEW-* | 代码审查 | +| integrator | INTEG-* | 集成验证 | + +--- + +### team-iterdev + +**一句话定位**: 迭代开发团队 — Generator-Critic 循环、增量交付 + +**触发**: +```bash +team-iterdev +``` + +**角色注册表**: +| 角色 | 任务前缀 | 功能 | +|------|----------|------| +| coordinator | (无) | 编排器 | +| architect | ARCH-* | 架构设计 | +| developer | DEV-* | 功能开发 | +| tester | TEST-* | 测试验证 | +| reviewer | REVIEW-* | 代码审查 | + +**特点**: Developer-Reviewer 循环（最多 3 轮），Task Ledger 实时进度 + +--- + +### team-quality-assurance + +**一句话定位**: 质量保证团队 — Issue 发现 + 测试验证闭环 + +**触发**: +```bash +team-quality-assurance +team-qa +``` + +**角色注册表**: +| 角色 | 任务前缀 | 功能 | +|------|----------|------| +| coordinator | (无) | 编排器 | +| scout | SCOUT-* | 问题发现 | +| strategist | QASTRAT-* | 策略制定 | +| generator | QAGEN-* | 测试生成 | +| executor | QARUN-* | 测试执行 | +| analyst | QAANA-* | 结果分析 | + +--- + +### team-roadmap-dev + +**一句话定位**: 路线图开发团队 — 分阶段开发、里程碑管理 + +**触发**: +```bash +team-roadmap-dev +``` + +**角色注册表**: +| 角色 | 任务前缀 | 功能 | +|------|----------|------| +| coordinator | (无) | 人机交互 | +| planner | PLAN-* | 阶段规划 | +| executor | EXEC-* | 阶段执行 | +| verifier | VERIFY-* | 阶段验证 | + +--- + +### team-tech-debt + +**一句话定位**: 技术债务团队 — 债务扫描、评估、清理、验证 + +**触发**: +```bash +team-tech-debt +``` + +**角色注册表**: +| 角色 | 任务前缀 | 功能 | +|------|----------|------| +| coordinator | (无) | 编排器 | +| scanner | TDSCAN-* | 债务扫描 | +| assessor | TDEVAL-* | 量化评估 | +| planner | TDPLAN-* | 治理规划 | +| executor | TDFIX-* | 清理执行 | +| validator | TDVAL-* | 验证回归 | + +--- + +### team-ultra-analyze + +**一句话定位**: 深度分析团队 — 多角色协作探索、渐进式理解 + +**触发**: +```bash +team-ultra-analyze +team-analyze +``` + +**角色注册表**: +| 角色 | 任务前缀 | 功能 | +|------|----------|------| +| coordinator | (无) | 编排器 | +| explorer | EXPLORE-* | 代码探索 | +| analyst | ANALYZE-* | 深度分析 | +| discussant | DISCUSS-* | 讨论交互 | +| synthesizer | SYNTH-* | 综合输出 | + +**特点**: 支持 Quick/Standard/Deep 三种深度模式 + +--- + +### team-executor-v2 + +**一句话定位**: 轻量执行器 — 恢复会话、纯执行模式 + +**触发**: +```bash +team-executor --session= +``` + +**功能**: +- 无分析、无角色生成 — 仅加载并执行现有会话 +- 用于恢复中断的 team-coordinate 会话 + +--- + +## 用户命令 + +所有 Team Skills 支持统一的用户命令（唤醒暂停的协调器）： + +| 命令 | 动作 | |------|------| -| strategist | `test_strategy` | -| generator | `generated_tests` | -| executor | `execution_results`, `defect_patterns` | -| analyst | `analysis_report`, `coverage_history` | +| `check` / `status` | 输出执行状态图，不推进 | +| `resume` / `continue` | 检查工作者状态，推进下一步 | +| `revise ` | 创建修订任务 + 级联下游 | +| `feedback ` | 分析反馈影响，创建定向修订链 | + +--- + +## 最佳实践 + +1. **选择合适的团队类型**: + - 通用任务 → `team-coordinate-v2` + - 完整功能开发 → `team-lifecycle-v5` + - Issue 批处理 → `team-planex` + - 代码审查 → `team-review` + - 测试覆盖 → `team-testing` + - 架构优化 → `team-arch-opt` + - 性能调优 → `team-perf-opt` + - 头脑风暴 → `team-brainstorm` + - 前端开发 → `team-frontend` + - UI 设计 → `team-uidesign` + - 技术债务 → `team-tech-debt` + - 深度分析 → `team-ultra-analyze` + +2. **利用内循环角色**: 设置 `inner_loop: true` 让单个工作者处理多个同前缀任务 + +3. **Wisdom 累积**: 团队会话中的所有角色都会累积知识到 `wisdom/` 目录 + +4. **Fast-Advance**: 简单线性后继任务会自动跳过协调器直接派生 + +5. **断点恢复**: 所有团队技能支持会话恢复，通过 `--resume` 或 `resume` 命令继续 + +--- ## 相关命令 - [Claude Commands - Workflow](../commands/claude/workflow.md) - [Claude Commands - Session](../commands/claude/session.md) - -## 最佳实践 - -1. **选择合适的团队类型**: - - 通用任务 → `team-coordinate` - - 完整功能开发 → `team-lifecycle` - - Issue 批处理 → `team-planex` - - 代码审查 → `team-review` - - 测试覆盖 → `team-testing` - -2. **利用内循环角色**: 对于有多个同前缀串行任务的角色，设置 `inner_loop: true` 让单个工作者处理全部任务，避免重复派生开销 - -3. **Wisdom 累积**: 团队会话中的所有角色都会累积知识到 `wisdom/` 目录，后续任务可复用这些模式、决策和约定 - -4. **Fast-Advance**: 简单线性后继任务会自动跳过协调器直接派生，减少协调开销 - -5. **断点恢复**: 所有团队技能支持会话恢复，通过 `--resume` 或用户命令 `resume` 继续中断的会话