From 99d64383039798fcd8e4ad4685da5b9a0e652a40 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Mon, 2 Mar 2026 19:38:30 +0800 Subject: [PATCH] feat: add documentation for Checkbox, Input, and Select components; enhance Queue and Terminal features - Introduced Checkbox component documentation in Chinese, covering usage, properties, and examples. - Added Input component documentation in Chinese, detailing its attributes and various states. - Created Select component documentation in Chinese, including subcomponents and usage examples. - Developed Queue management documentation, outlining its core functionalities and component structure. - Added Terminal dashboard documentation, describing its layout, core features, and usage examples. - Documented team workflows, detailing various team skills and their applications in project management. --- ccw/src/tools/codex-lens.ts | 70 +++- .../codex-lens-bootstrap-pip-missing.test.js | 120 +++++++ codex-lens/pyproject.toml | 6 +- codex-lens/src/codex_lens.egg-info/PKG-INFO | 6 +- .../src/codex_lens.egg-info/requires.txt | 6 +- docs/.vitepress/config.ts | 123 +++++-- .../theme/components/DemoContainer.vue | 4 +- .../theme/components/LanguageSwitcher.vue | 17 +- docs/.vitepress/theme/layouts/Layout.vue | 2 +- docs/.vitepress/theme/styles/demo.css | 2 +- docs/.vitepress/theme/styles/mobile.css | 46 +-- docs/guide/installation.md | 90 ++++- docs/skills/naming-conventions.md | 307 ++++++++++++++++++ docs/zh-CN/features/dashboard.md | 242 -------------- docs/zh-CN/index.md | 53 --- docs/{zh-CN => zh}/components/index.md | 0 docs/{zh-CN => zh}/components/ui/badge.md | 0 docs/{zh-CN => zh}/components/ui/button.md | 0 docs/{zh-CN => zh}/components/ui/card.md | 0 docs/{zh-CN => zh}/components/ui/checkbox.md | 0 docs/{zh-CN => zh}/components/ui/input.md | 0 docs/{zh-CN => zh}/components/ui/select.md | 0 docs/{zh-CN => zh}/features/queue.md | 0 docs/{zh-CN => zh}/features/terminal.md | 0 docs/zh/guide/installation.md | 104 +++++- docs/zh/workflows/teams.md | 197 +++++++++++ 26 files changed, 1017 insertions(+), 378 deletions(-) create mode 100644 ccw/tests/codex-lens-bootstrap-pip-missing.test.js create mode 100644 docs/skills/naming-conventions.md delete mode 100644 docs/zh-CN/features/dashboard.md delete mode 100644 docs/zh-CN/index.md rename docs/{zh-CN => zh}/components/index.md (100%) rename docs/{zh-CN => zh}/components/ui/badge.md (100%) rename docs/{zh-CN => zh}/components/ui/button.md (100%) rename docs/{zh-CN => zh}/components/ui/card.md (100%) rename docs/{zh-CN => zh}/components/ui/checkbox.md (100%) rename docs/{zh-CN => zh}/components/ui/input.md (100%) rename docs/{zh-CN => zh}/components/ui/select.md (100%) rename docs/{zh-CN => zh}/features/queue.md (100%) rename docs/{zh-CN => zh}/features/terminal.md (100%) create mode 100644 docs/zh/workflows/teams.md diff --git a/ccw/src/tools/codex-lens.ts b/ccw/src/tools/codex-lens.ts index 278dfdfe..1149e0fc 100644 --- a/ccw/src/tools/codex-lens.ts +++ b/ccw/src/tools/codex-lens.ts @@ -516,6 +516,36 @@ async function ensureLiteLLMEmbedderReady(): Promise { // Fallback: Use pip for installation const pipPath = getCodexLensPip(); + // UV-created venvs may not ship with pip.exe. Ensure pip exists before using pip fallback. + if (!existsSync(pipPath)) { + const venvPython = getCodexLensPython(); + console.warn(`[CodexLens] pip not found at: ${pipPath}. Attempting to bootstrap pip with ensurepip...`); + try { + execSync(`\"${venvPython}\" -m ensurepip --upgrade`, { + stdio: 'inherit', + timeout: EXEC_TIMEOUTS.PACKAGE_INSTALL, + }); + } catch (err) { + console.warn(`[CodexLens] ensurepip failed: ${(err as Error).message}`); + } + } + + if (!existsSync(pipPath)) { + return { + success: false, + error: `pip not found at ${pipPath}. Delete ${getCodexLensVenvDir()} and retry, or reinstall using UV.`, + diagnostics: { + packagePath: localPath || undefined, + venvPath: getCodexLensVenvDir(), + installer: 'pip', + editable, + searchedPaths: !localPath ? discovery.searchedPaths : undefined, + }, + warnings: warnings.length > 0 ? warnings : undefined, + }; + } + + try { if (localPath) { const pipFlag = editable ? '-e' : ''; @@ -1011,7 +1041,45 @@ async function bootstrapVenv(): Promise { // Install codex-lens try { console.log('[CodexLens] Installing codex-lens package...'); - const pipPath = getCodexLensPip(); + const pipPath = getCodexLensPip(); + + // UV-created venvs may not ship with pip.exe. Ensure pip exists before using pip fallback. + if (!existsSync(pipPath)) { + const venvPython = getCodexLensPython(); + console.warn(`[CodexLens] pip not found at: ${pipPath}. Attempting to bootstrap pip with ensurepip...`); + try { + execSync(`\"${venvPython}\" -m ensurepip --upgrade`, { + stdio: 'inherit', + timeout: EXEC_TIMEOUTS.PACKAGE_INSTALL, + }); + } catch (err) { + console.warn(`[CodexLens] ensurepip failed: ${(err as Error).message}`); + } + } + + // If pip is still missing, recreate the venv using system Python (guarantees pip). + if (!existsSync(pipPath)) { + console.warn('[CodexLens] pip still missing after ensurepip; recreating venv with system Python...'); + try { + rmSync(venvDir, { recursive: true, force: true }); + const pythonCmd = getSystemPython(); + execSync(`${pythonCmd} -m venv \"${venvDir}\"`, { stdio: 'inherit', timeout: EXEC_TIMEOUTS.PROCESS_SPAWN }); + } catch (err) { + return { + success: false, + error: `Failed to recreate venv for pip fallback: ${(err as Error).message}`, + warnings: warnings.length > 0 ? warnings : undefined, + }; + } + + if (!existsSync(pipPath)) { + return { + success: false, + error: `pip not found at ${pipPath} after venv recreation. Ensure your Python installation includes ensurepip/pip.`, + warnings: warnings.length > 0 ? warnings : undefined, + }; + } + } // Try local path using unified discovery const discovery = findCodexLensPath(); diff --git a/ccw/tests/codex-lens-bootstrap-pip-missing.test.js b/ccw/tests/codex-lens-bootstrap-pip-missing.test.js new file mode 100644 index 00000000..c847698d --- /dev/null +++ b/ccw/tests/codex-lens-bootstrap-pip-missing.test.js @@ -0,0 +1,120 @@ +/** + * Regression test: CodexLens bootstrap should recover when UV bootstrap fails + * and the existing venv is missing pip (common with UV-created venvs). + * + * We simulate "UV available but broken" by pointing CCW_UV_PATH to the current Node + * executable. `node --version` exits 0 so isUvAvailable() returns true, but any + * `node pip install ...` calls fail, forcing bootstrapVenv() to fall back to pip. + * + * Before running bootstrapVenv(), we pre-create the venv and delete its pip entrypoint + * to mimic a venv that has Python but no pip executable. bootstrapVenv() should + * re-bootstrap pip (ensurepip) or recreate the venv, then succeed. + */ + +import { describe, it } from 'node:test'; +import assert from 'node:assert/strict'; +import { spawn } from 'node:child_process'; +import { mkdtempSync, rmSync } from 'node:fs'; +import { dirname, join } from 'node:path'; +import { tmpdir } from 'node:os'; +import { fileURLToPath } from 'node:url'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +// repo root: /ccw/tests -> +const REPO_ROOT = join(__dirname, '..', '..'); + +function runNodeEvalModule(script, env) { + return new Promise((resolve, reject) => { + const child = spawn(process.execPath, ['--input-type=module', '-e', script], { + cwd: REPO_ROOT, + env, + stdio: ['ignore', 'pipe', 'pipe'], + windowsHide: true, + }); + + let stdout = ''; + let stderr = ''; + + child.stdout.on('data', (d) => { stdout += d.toString(); }); + child.stderr.on('data', (d) => { stderr += d.toString(); }); + + child.on('error', (err) => reject(err)); + child.on('close', (code) => resolve({ code, stdout, stderr })); + }); +} + +describe('CodexLens bootstrap pip repair', () => { + it('repairs missing pip in existing venv during pip fallback', { timeout: 10 * 60 * 1000 }, async () => { + const dataDir = mkdtempSync(join(tmpdir(), 'codexlens-bootstrap-pip-missing-')); + + try { + const script = ` +import { execSync } from 'node:child_process'; +import { existsSync, rmSync, mkdirSync } from 'node:fs'; +import { join } from 'node:path'; + +import { getSystemPython } from './ccw/dist/utils/python-utils.js'; +import { bootstrapVenv } from './ccw/dist/tools/codex-lens.js'; + +const dataDir = process.env.CODEXLENS_DATA_DIR; +if (!dataDir) throw new Error('Missing CODEXLENS_DATA_DIR'); + +mkdirSync(dataDir, { recursive: true }); +const venvDir = join(dataDir, 'venv'); + +// Create a venv up-front so UV bootstrap will skip venv creation and fail on install. +const pythonCmd = getSystemPython(); +execSync(pythonCmd + ' -m venv "' + venvDir + '"', { stdio: 'inherit' }); + +// Simulate a "pip-less" venv by deleting the pip entrypoint. +const pipPath = process.platform === 'win32' + ? join(venvDir, 'Scripts', 'pip.exe') + : join(venvDir, 'bin', 'pip'); +if (existsSync(pipPath)) { + rmSync(pipPath, { force: true }); +} + +const result = await bootstrapVenv(); +const pipRestored = existsSync(pipPath); + +console.log('@@RESULT@@' + JSON.stringify({ result, pipRestored })); +`.trim(); + + const env = { + ...process.env, + // Isolate test venv + dependencies from user/global CodexLens state. + CODEXLENS_DATA_DIR: dataDir, + // Make isUvAvailable() return true, but installFromProject() fail. + CCW_UV_PATH: process.execPath, + }; + + const { code, stdout, stderr } = await runNodeEvalModule(script, env); + assert.equal(code, 0, `bootstrapVenv child process failed:\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`); + + const marker = '@@RESULT@@'; + const idx = stdout.lastIndexOf(marker); + assert.ok(idx !== -1, `Missing result marker in stdout:\n${stdout}`); + + const jsonText = stdout.slice(idx + marker.length).trim(); + const parsed = JSON.parse(jsonText); + + assert.equal(parsed?.result?.success, true, `Expected success=true, got:\n${jsonText}`); + assert.equal(parsed?.pipRestored, true, `Expected pipRestored=true, got:\n${jsonText}`); + + // Best-effort: confirm we exercised the missing-pip repair path. + assert.ok( + String(stderr).includes('pip not found at:') || String(stdout).includes('pip not found at:'), + `Expected missing-pip warning in output. STDERR:\n${stderr}\nSTDOUT:\n${stdout}` + ); + } finally { + try { + rmSync(dataDir, { recursive: true, force: true }); + } catch { + // Best effort cleanup; leave artifacts only if Windows locks prevent removal. + } + } + }); +}); + diff --git a/codex-lens/pyproject.toml b/codex-lens/pyproject.toml index b4ab1123..f6e6ecaf 100644 --- a/codex-lens/pyproject.toml +++ b/codex-lens/pyproject.toml @@ -30,7 +30,7 @@ dependencies = [ [project.optional-dependencies] # Semantic search using fastembed (ONNX-based, lightweight ~200MB) semantic = [ - "numpy~=1.24.0", + "numpy~=1.26.0", "fastembed~=0.2.0", "hnswlib~=0.8.0", ] @@ -38,7 +38,7 @@ semantic = [ # GPU acceleration for semantic search (NVIDIA CUDA) # Install with: pip install codexlens[semantic-gpu] semantic-gpu = [ - "numpy~=1.24.0", + "numpy~=1.26.0", "fastembed~=0.2.0", "hnswlib~=0.8.0", "onnxruntime-gpu~=1.15.0", # CUDA support @@ -47,7 +47,7 @@ semantic-gpu = [ # GPU acceleration for Windows (DirectML - supports NVIDIA/AMD/Intel) # Install with: pip install codexlens[semantic-directml] semantic-directml = [ - "numpy~=1.24.0", + "numpy~=1.26.0", "fastembed~=0.2.0", "hnswlib~=0.8.0", "onnxruntime-directml~=1.15.0", # DirectML support diff --git a/codex-lens/src/codex_lens.egg-info/PKG-INFO b/codex-lens/src/codex_lens.egg-info/PKG-INFO index 1cffe19e..d778d604 100644 --- a/codex-lens/src/codex_lens.egg-info/PKG-INFO +++ b/codex-lens/src/codex_lens.egg-info/PKG-INFO @@ -19,16 +19,16 @@ Requires-Dist: pathspec~=0.11.0 Requires-Dist: watchdog~=3.0.0 Requires-Dist: ast-grep-py~=0.40.0 Provides-Extra: semantic -Requires-Dist: numpy~=1.24.0; extra == "semantic" +Requires-Dist: numpy~=1.26.0; extra == "semantic" Requires-Dist: fastembed~=0.2.0; extra == "semantic" Requires-Dist: hnswlib~=0.8.0; extra == "semantic" Provides-Extra: semantic-gpu -Requires-Dist: numpy~=1.24.0; extra == "semantic-gpu" +Requires-Dist: numpy~=1.26.0; extra == "semantic-gpu" Requires-Dist: fastembed~=0.2.0; extra == "semantic-gpu" Requires-Dist: hnswlib~=0.8.0; extra == "semantic-gpu" Requires-Dist: onnxruntime-gpu~=1.15.0; extra == "semantic-gpu" Provides-Extra: semantic-directml -Requires-Dist: numpy~=1.24.0; extra == "semantic-directml" +Requires-Dist: numpy~=1.26.0; extra == "semantic-directml" Requires-Dist: fastembed~=0.2.0; extra == "semantic-directml" Requires-Dist: hnswlib~=0.8.0; extra == "semantic-directml" Requires-Dist: onnxruntime-directml~=1.15.0; extra == "semantic-directml" diff --git a/codex-lens/src/codex_lens.egg-info/requires.txt b/codex-lens/src/codex_lens.egg-info/requires.txt index a4f28711..6fd9a96c 100644 --- a/codex-lens/src/codex_lens.egg-info/requires.txt +++ b/codex-lens/src/codex_lens.egg-info/requires.txt @@ -42,18 +42,18 @@ onnxruntime~=1.15.0 transformers~=4.36.0 [semantic] -numpy~=1.24.0 +numpy~=1.26.0 fastembed~=0.2.0 hnswlib~=0.8.0 [semantic-directml] -numpy~=1.24.0 +numpy~=1.26.0 fastembed~=0.2.0 hnswlib~=0.8.0 onnxruntime-directml~=1.15.0 [semantic-gpu] -numpy~=1.24.0 +numpy~=1.26.0 fastembed~=0.2.0 hnswlib~=0.8.0 onnxruntime-gpu~=1.15.0 diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 3c6b21d7..867925c0 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -102,6 +102,15 @@ export default withMermaid(defineConfig({ { text: 'First Workflow', link: '/guide/first-workflow' }, { text: 'CLI Tools', link: '/guide/cli-tools' } ] + }, + { + text: '📝 CLAUDE.md & MCP', + collapsible: true, + items: [ + { text: 'CLAUDE.md Guide', link: '/guide/claude-md' }, + { text: 'CCW MCP Tools', link: '/guide/ccwmcp' }, + { text: 'MCP Setup', link: '/guide/mcp-setup' } + ] } ], '/commands/': [ @@ -128,6 +137,13 @@ export default withMermaid(defineConfig({ { text: 'Prep', link: '/commands/codex/prep' }, { text: 'Review', link: '/commands/codex/review' } ] + }, + { + text: '🔧 CLI Reference', + collapsible: true, + items: [ + { text: 'CLI Commands', link: '/cli/commands' } + ] } ], '/skills/': [ @@ -175,6 +191,34 @@ export default withMermaid(defineConfig({ { text: 'Core Skills', link: '/skills/core-skills' }, { text: 'Reference', link: '/skills/reference' } ] + }, + { + text: '📋 Skill Specifications', + collapsible: true, + items: [ + { text: 'Document Standards', link: '/skills/specs/document-standards' }, + { text: 'Issue Classification', link: '/skills/specs/issue-classification' }, + { text: 'Quality Gates', link: '/skills/specs/quality-gates' }, + { text: 'Quality Standards', link: '/skills/specs/quality-standards' }, + { text: 'Reference Docs Spec', link: '/skills/specs/reference-docs-spec' }, + { text: 'Review Dimensions', link: '/skills/specs/review-dimensions' } + ] + }, + { + text: '📄 Skill Templates', + collapsible: true, + items: [ + { text: 'Architecture Doc', link: '/skills/templates/architecture-doc' }, + { text: 'Autonomous Action', link: '/skills/templates/autonomous-action' }, + { text: 'Autonomous Orchestrator', link: '/skills/templates/autonomous-orchestrator' }, + { text: 'Epics Template', link: '/skills/templates/epics-template' }, + { text: 'Issue Template', link: '/skills/templates/issue-template' }, + { text: 'Product Brief', link: '/skills/templates/product-brief' }, + { text: 'Requirements PRD', link: '/skills/templates/requirements-prd' }, + { text: 'Review Report', link: '/skills/templates/review-report' }, + { text: 'Sequential Phase', link: '/skills/templates/sequential-phase' }, + { text: 'Skill Markdown', link: '/skills/templates/skill-md' } + ] } ], '/features/': [ @@ -194,7 +238,35 @@ export default withMermaid(defineConfig({ collapsible: true, items: [ { text: 'API Settings', link: '/features/api-settings' }, - { text: 'System Settings', link: '/features/system-settings' } + { text: 'System Settings', link: '/features/system-settings' }, + { text: 'Settings', link: '/features/settings' } + ] + }, + { + text: '🔍 Discovery & Explorer', + collapsible: true, + items: [ + { text: 'Discovery', link: '/features/discovery' }, + { text: 'Explorer', link: '/features/explorer' }, + { text: 'Extensions', link: '/features/extensions' } + ] + }, + { + text: '📋 Issues & Tasks', + collapsible: true, + items: [ + { text: 'Issue Hub', link: '/features/issue-hub' }, + { text: 'Orchestrator', link: '/features/orchestrator' }, + { text: 'Queue', link: '/features/queue' }, + { text: 'Sessions', link: '/features/sessions' }, + { text: 'Tasks History', link: '/features/tasks-history' } + ] + }, + { + text: '🖥️ Terminal', + collapsible: true, + items: [ + { text: 'Terminal Dashboard', link: '/features/terminal' } ] } ], @@ -228,7 +300,8 @@ export default withMermaid(defineConfig({ collapsible: true, items: [ { text: 'Commands & Skills', link: '/reference/commands-skills' }, - { text: 'Claude Code Hooks', link: '/reference/claude-code-hooks-guide' } + { text: 'Claude Code Hooks', link: '/reference/claude-code-hooks-guide' }, + { text: 'Hook Templates Analysis', link: '/reference/hook-templates-analysis' } ] } ], @@ -350,6 +423,7 @@ 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: { @@ -458,6 +532,8 @@ export default withMermaid(defineConfig({ { text: 'Memory 记忆系统', link: '/zh/features/memory' }, { text: 'CLI 调用', link: '/zh/features/cli' }, { text: 'Dashboard 面板', link: '/zh/features/dashboard' }, + { text: 'Terminal 终端仪表板', link: '/zh/features/terminal' }, + { text: 'Queue 队列管理', link: '/zh/features/queue' }, { text: 'CodexLens', link: '/zh/features/codexlens' } ] }, @@ -470,6 +546,21 @@ export default withMermaid(defineConfig({ ] } ], + '/zh/components/': [ + { + text: 'UI 组件', + collapsible: true, + items: [ + { text: '概述', link: '/zh/components/index' }, + { text: 'Button 按钮', link: '/zh/components/ui/button' }, + { text: 'Card 卡片', link: '/zh/components/ui/card' }, + { text: 'Input 输入框', link: '/zh/components/ui/input' }, + { text: 'Select 选择器', link: '/zh/components/ui/select' }, + { text: 'Checkbox 复选框', link: '/zh/components/ui/checkbox' }, + { text: 'Badge 徽章', link: '/zh/components/ui/badge' } + ] + } + ], '/zh/workflows/': [ { text: '🔄 工作流系统', @@ -495,33 +586,5 @@ export default withMermaid(defineConfig({ } } }, - 'zh-CN': { - label: '简体中文', - lang: 'zh-CN', - title: 'Claude Code Workflow 文档', - description: 'Claude Code Workspace - 高级 AI 驱动开发环境', - themeConfig: { - outline: { - level: [2, 3], - label: '本页目录' - }, - nav: [ - { text: '功能', link: '/zh-CN/features/dashboard' } - ], - sidebar: { - '/zh-CN/features/': [ - { - text: '⚙️ 核心功能', - collapsible: false, - items: [ - { text: 'Dashboard 面板', link: '/zh-CN/features/dashboard' }, - { text: 'Terminal 终端监控', link: '/zh-CN/features/terminal' }, - { text: 'Queue 队列管理', link: '/zh-CN/features/queue' } - ] - } - ] - } - } - } } })) diff --git a/docs/.vitepress/theme/components/DemoContainer.vue b/docs/.vitepress/theme/components/DemoContainer.vue index 31d1aa6e..9283e887 100644 --- a/docs/.vitepress/theme/components/DemoContainer.vue +++ b/docs/.vitepress/theme/components/DemoContainer.vue @@ -80,7 +80,7 @@ onMounted(async () => { } } else { // Dynamically import demo component from file - const demoModule = await import(`../demos/${props.name}.tsx`) + const demoModule = await import(`../../demos/${props.name}.tsx`) const DemoComponent = demoModule.default || demoModule[props.name] if (!DemoComponent) { @@ -94,7 +94,7 @@ onMounted(async () => { // Extract source code try { - const rawModule = await import(`../demos/${props.name}.tsx?raw`) + const rawModule = await import(`../../demos/${props.name}.tsx?raw`) sourceCode.value = rawModule.default || rawModule } catch { sourceCode.value = '// Source code not available' diff --git a/docs/.vitepress/theme/components/LanguageSwitcher.vue b/docs/.vitepress/theme/components/LanguageSwitcher.vue index f1515e95..d0af0b00 100644 --- a/docs/.vitepress/theme/components/LanguageSwitcher.vue +++ b/docs/.vitepress/theme/components/LanguageSwitcher.vue @@ -27,13 +27,20 @@ const currentLocale = computed(() => { // Get alternate language link for current page const getAltLink = (localeCode: string) => { - if (localeCode === 'root') localeCode = '' + // Get current path and strip any existing locale prefix + let currentPath = page.value.relativePath - // Get current page path without locale prefix - const currentPath = page.value.relativePath - const altPath = localeCode ? `/${localeCode}/${currentPath}` : `/${currentPath}` + // Strip locale prefixes (zh/, zh-CN/) from path + currentPath = currentPath.replace(/^(zh-CN|zh)\//, '') - return altPath + // Remove .md extension for clean URL (VitePress uses .html) + currentPath = currentPath.replace(/\.md$/, '') + + // Construct target path with locale prefix + if (localeCode === 'root' || localeCode === '') { + return `/${currentPath}` + } + return `/${localeCode}/${currentPath}` } const switchLanguage = (localeCode: string) => { diff --git a/docs/.vitepress/theme/layouts/Layout.vue b/docs/.vitepress/theme/layouts/Layout.vue index 7259987e..33986413 100644 --- a/docs/.vitepress/theme/layouts/Layout.vue +++ b/docs/.vitepress/theme/layouts/Layout.vue @@ -196,7 +196,7 @@ onBeforeUnmount(() => { /* Container queries in mobile.css provide additional responsiveness */ /* Mobile-specific styles */ -@media (max-width: var(--bp-sm)) { +@media (max-width: 767px) { .hero-extensions { margin-top: 1rem; padding: 0 12px; diff --git a/docs/.vitepress/theme/styles/demo.css b/docs/.vitepress/theme/styles/demo.css index 7938e5de..205538ed 100644 --- a/docs/.vitepress/theme/styles/demo.css +++ b/docs/.vitepress/theme/styles/demo.css @@ -35,7 +35,7 @@ } /* Responsive design */ -@media (max-width: var(--bp-sm)) { +@media (max-width: 767px) { .demo-header { flex-direction: column; align-items: flex-start; diff --git a/docs/.vitepress/theme/styles/mobile.css b/docs/.vitepress/theme/styles/mobile.css index e64bbfd6..a8e8b669 100644 --- a/docs/.vitepress/theme/styles/mobile.css +++ b/docs/.vitepress/theme/styles/mobile.css @@ -1,8 +1,10 @@ /** * Mobile-Responsive Styles * Breakpoints: < 480px (xs), < 768px (sm/mobile), 768px-1024px (md/tablet), > 1024px (lg/desktop) - * Uses CSS custom properties from variables.css: --bp-xs, --bp-sm, --bp-md, --bp-lg * WCAG 2.1 AA compliant + * + * NOTE: Media/container queries MUST use literal pixel values (CSS spec limitation) + * --bp-xs: 480px, --bp-sm: 768px, --bp-md: 1024px, --bp-lg: 1440px */ /* ============================================ @@ -19,7 +21,7 @@ max-width: 320px; } - @media (min-width: var(--bp-sm)) { + @media (min-width: 768px) { .VPSidebar { width: var(--vp-sidebar-width, 272px); max-width: none; @@ -31,13 +33,13 @@ padding: 16px; } - @media (min-width: var(--bp-sm)) { + @media (min-width: 768px) { .VPContent { padding: 24px; } } - @media (min-width: var(--bp-md)) { + @media (min-width: 1024px) { .VPContent { padding: 32px 48px; } @@ -48,14 +50,14 @@ display: none; } - @media (min-width: var(--bp-sm)) { + @media (min-width: 768px) { .VPDocOutline { display: block; width: 200px; } } - @media (min-width: var(--bp-md)) { + @media (min-width: 1024px) { .VPDocOutline { width: 256px; } @@ -65,7 +67,7 @@ /* Container Query Rules (modern browsers) */ @supports (container-type: inline-size) { /* Sidebar Container Queries */ - @container sidebar (max-width: var(--bp-xs)) { + @container sidebar (max-width: 480px) { .VPSidebar .group { padding: 12px 16px; } @@ -75,7 +77,7 @@ } } - @container sidebar (min-width: var(--bp-xs)) and (max-width: var(--bp-sm)) { + @container sidebar (min-width: 480px) and (max-width: 768px) { .VPSidebar .group { padding: 16px 20px; } @@ -85,7 +87,7 @@ } } - @container sidebar (min-width: var(--bp-sm)) { + @container sidebar (min-width: 768px) { .VPSidebar .group { padding: 16px 24px; } @@ -221,25 +223,25 @@ } /* Generic Container-Responsive Utility Class */ -@container (max-width: var(--bp-xs)) { +@container (max-width: 480px) { .container-responsive { padding: 0 var(--spacing-fluid-xs); } } -@container (min-width: var(--bp-xs)) and (max-width: var(--bp-sm)) { +@container (min-width: 480px) and (max-width: 768px) { .container-responsive { padding: 0 var(--spacing-fluid-sm); } } -@container (min-width: var(--bp-sm)) and (max-width: var(--bp-md)) { +@container (min-width: 768px) and (max-width: 1024px) { .container-responsive { padding: 0 var(--spacing-fluid-md); } } -@container (min-width: var(--bp-md)) { +@container (min-width: 1024px) { .container-responsive { padding: 0 var(--spacing-fluid-lg); } @@ -250,7 +252,7 @@ * ============================================ */ /* Base Mobile Styles (320px+) */ -@media (max-width: var(--bp-sm)) { +@media (max-width: 767px) { /* Typography */ :root { --vp-font-size-base: 14px; @@ -598,7 +600,7 @@ /* ============================================ * Tablet Styles (768px - 1024px) * ============================================ */ -@media (min-width: var(--bp-sm)) and (max-width: var(--bp-md)) { +@media (min-width: 768px) and (max-width: 1023px) { :root { --vp-content-width: 760px; --vp-sidebar-width: 240px; @@ -639,7 +641,7 @@ /* ============================================ * Desktop Styles (1024px+) * ============================================ */ -@media (min-width: var(--bp-md)) { +@media (min-width: 1024px) { :root { --vp-layout-max-width: 1600px; --vp-content-width: 960px; @@ -692,7 +694,7 @@ /* ============================================ * Large Desktop (1440px+) * ============================================ */ -@media (min-width: var(--bp-lg)) { +@media (min-width: 1440px) { :root { --vp-content-width: 1040px; --vp-sidebar-width: 280px; @@ -749,7 +751,7 @@ /* ============================================ * ProfessionalHome Component - Mobile Optimizations * ============================================ */ -@media (max-width: var(--bp-sm)) { +@media (max-width: 767px) { /* Root level overflow prevention */ html, body { max-width: 100vw; @@ -921,7 +923,7 @@ } /* ProfessionalHome - Tablet Optimizations */ -@media (min-width: var(--bp-sm)) and (max-width: var(--bp-md)) { +@media (min-width: 768px) and (max-width: 1023px) { .pro-home .hero-section { padding: 3rem 0 2.5rem; } @@ -941,7 +943,7 @@ } /* ProfessionalHome - Small Mobile (< 480px) */ -@media (max-width: var(--bp-xs)) { +@media (max-width: 479px) { .pro-home .hero-badge { font-size: 0.7rem; padding: 0.2rem 0.5rem; @@ -965,7 +967,7 @@ /* ============================================ * Dark Mode Specific * ============================================ */ -@media (max-width: var(--bp-sm)) { +@media (max-width: 767px) { .dark { --vp-c-bg: #0f172a; --vp-c-text-1: #f1f5f9; @@ -975,7 +977,7 @@ /* ============================================ * Print Styles for Mobile * ============================================ */ -@media print and (max-width: var(--bp-sm)) { +@media print and (max-width: 767px) { .VPContent { font-size: 10pt; } diff --git a/docs/guide/installation.md b/docs/guide/installation.md index 55b77e9e..3ea43a80 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -178,26 +178,100 @@ cp -r agents/* ~/.claude/agents/ ## Uninstallation +CCW provides a smart uninstall command that automatically handles installation manifests, orphan file cleanup, and global file protection. + +### Using CCW Uninstall Command (Recommended) + ```bash -# Remove CCW commands -rm ~/.claude/commands/ccw.md -rm ~/.claude/commands/ccw-coordinator.md +ccw uninstall +``` + +Uninstallation flow: + +1. **Scan Installation Manifests** - Automatically detects all installed CCW instances (Global and Path modes) +2. **Interactive Selection** - Displays installation list for you to choose which to uninstall +3. **Smart Protection** - When uninstalling Path mode, if a Global installation exists, global files (workflows, scripts, templates) are automatically preserved +4. **Orphan File Cleanup** - Automatically cleans up skills and commands files no longer referenced by any installation +5. **Empty Directory Cleanup** - Removes empty directories left behind +6. **Git Bash Fix Removal** - On Windows, after the last installation is removed, asks whether to remove the Git Bash multi-line prompt fix + +### Uninstall Output Example + +``` + Found installations: + + 1. Global + Path: /Users/username/my-project + Date: 2026/3/2 + Version: 7.0.5 + Files: 156 | Dirs: 23 + +────────────────────────────────────── +? Select installation to uninstall: Global - /Users/username/my-project +? Are you sure you want to uninstall Global installation? Yes + +✔ Removing files... +✔ Uninstall complete! + +╔══════════════════════════════════════╗ +║ Uninstall Summary ║ +╠══════════════════════════════════════╣ +║ ✓ Successfully Uninstalled ║ +║ ║ +║ Files removed: 156 ║ +║ Directories removed: 23 ║ +║ Orphan files cleaned: 3 ║ +║ ║ +║ Manifest removed ║ +╚══════════════════════════════════════╝ +``` + +### Manual Uninstallation + +If you need to manually remove CCW files (not recommended): + +```bash +# CCW installed directories (safe to remove) +rm -rf ~/.claude/commands/ccw.md +rm -rf ~/.claude/commands/ccw-coordinator.md rm -rf ~/.claude/commands/workflow rm -rf ~/.claude/commands/issue rm -rf ~/.claude/commands/cli rm -rf ~/.claude/commands/memory - -# Remove CCW skills and agents +rm -rf ~/.claude/commands/idaw rm -rf ~/.claude/skills/workflow-* rm -rf ~/.claude/skills/team-* +rm -rf ~/.claude/skills/review-* rm -rf ~/.claude/agents/team-worker.md rm -rf ~/.claude/agents/cli-*-agent.md +rm -rf ~/.claude/workflows +rm -rf ~/.claude/scripts +rm -rf ~/.claude/templates +rm -rf ~/.claude/manifests +rm -rf ~/.claude/version.json -# Remove configuration (optional) -rm -rf ~/.claude/cli-tools.json -rm -rf .workflow/ +# Codex related directories +rm -rf ~/.codex/prompts +rm -rf ~/.codex/skills +rm -rf ~/.codex/agents + +# Other CLI directories +rm -rf ~/.gemini +rm -rf ~/.qwen + +# CCW core directory +rm -rf ~/.ccw ``` +::: danger Danger +**Do NOT** run `rm -rf ~/.claude` - this will delete your Claude Code personal configurations: +- `~/.claude/settings.json` - Your Claude Code settings +- `~/.claude/settings.local.json` - Local override settings +- MCP server configurations, etc. + +Always use `ccw uninstall` for controlled uninstallation. +::: + ## Troubleshooting ### Command Not Found diff --git a/docs/skills/naming-conventions.md b/docs/skills/naming-conventions.md new file mode 100644 index 00000000..3316ae38 --- /dev/null +++ b/docs/skills/naming-conventions.md @@ -0,0 +1,307 @@ +# Naming Conventions + +CCW uses consistent naming conventions across skills, commands, files, and configurations. Following these conventions ensures your custom skills integrate seamlessly with the built-in ecosystem. + +## Overview + +Consistent naming conventions help with: +- **Discoverability**: Skills and commands are easy to find and understand +- **Integration**: Custom skills work well with built-in ones +- **Maintenance**: Clear naming reduces cognitive load when debugging +- **Documentation**: Self-documenting code and configuration + +## Skill Naming + +### Built-in Skill Pattern + +Built-in CCW skills follow these patterns: + +| Pattern | Examples | Usage | +|---------|----------|-------| +| `team-*` | `team-lifecycle-v4`, `team-brainstorm` | Multi-agent team skills | +| `workflow-*` | `workflow-plan`, `workflow-execute` | Planning and execution workflows | +| `*-cycle` | `review-cycle`, `refactor-cycle` | Iterative process skills | +| `memory-*` | `memory-capture`, `memory-manage` | Memory-related operations | + +### Custom Skill Naming + +When creating custom skills, use these guidelines: + +```yaml +# Good: Clear, descriptive, follows convention +name: generate-react-component +name: api-scaffolding +name: test-coverage-analyzer + +# Avoid: Too generic or unclear +name: helper +name: stuff +name: my-skill-v2 +``` + +### Naming Principles + +1. **Use kebab-case**: All skill names use lowercase with hyphens + ```yaml + name: team-lifecycle-v4 # Good + name: teamLifecycleV4 # Bad + ``` + +2. **Start with action or category**: Indicate what the skill does + ```yaml + name: generate-component # Action-based + name: test-coverage # Category-based + ``` + +3. **Use version suffixes for iterations**: Not "v2" but purpose + ```yaml + name: team-lifecycle-v5 # Version iteration + name: workflow-lite # Lightweight variant + ``` + +## Command Naming + +### CLI Command Pattern + +Commands follow a `category:action:variant` pattern: + +```bash +# Format +ccw :: + +# Examples +ccw workflow:plan:verify +ccw workflow:replan +ccw memory:capture:session +ccw team:lifecycle +``` + +### Command Aliases + +Short aliases for common commands: + +| Full Command | Short Alias | +|--------------|-------------| +| `workflow:multi-cli-plan` | `workflow:multi-cli-plan` | +| `team:lifecycle-v4` | `team lifecycle` | +| `brainstorm:auto` | `brainstorm` | + +## File Naming + +### Skill Files + +``` +~/.claude/skills/my-skill/ +├── SKILL.md # Skill definition (required, uppercase) +├── index.ts # Skill logic (optional) +├── phases/ # Phase files (optional) +│ ├── phase-1.md # Numbered phases +│ └── phase-2.md +└── examples/ # Usage examples + └── basic-usage.md +``` + +### Documentation Files + +Documentation follows clear hierarchical patterns: + +``` +docs/ +├── skills/ +│ ├── index.md # Skills overview +│ ├── core-skills.md # Built-in skills reference +│ ├── naming-conventions.md # This file +│ └── custom.md # Custom skill development +├── workflows/ +│ ├── index.md +│ ├── teams.md # Team workflows +│ └── best-practices.md +└── zh/ # Chinese translations + └── skills/ + └── index.md +``` + +### Markdown File Conventions + +| Pattern | Example | Usage | +|---------|---------|-------| +| `index.md` | `skills/index.md` | Section overview | +| `kebab-case.md` | `naming-conventions.md` | Topic pages | +| `UPPERCASE.md` | `SKILL.md`, `README.md` | Special/config files | + +## Configuration Keys + +### Skill Frontmatter + +```yaml +--- +name: workflow-plan # kebab-case +description: 4-phase planning # Sentence case +version: 1.0.0 # Semantic versioning +triggers: # Array format + - workflow-plan + - workflow:replan +category: planning # Lowercase +tags: # Array of keywords + - planning + - verification +--- +``` + +### CLI Tool Configuration + +```json +{ + "tools": { + "gemini": { + "enabled": true, // camelCase for JSON + "primaryModel": "gemini-2.5-flash", + "tags": ["analysis", "Debug"] + } + } +} +``` + +## Variable Naming in Code + +### TypeScript/JavaScript + +```typescript +// Files and directories +import { SkillContext } from './types' + +// Variables and functions +const skillName = "my-skill" +function executeSkill() {} + +// Classes and interfaces +class SkillExecutor {} +interface SkillOptions {} + +// Constants +const MAX_RETRIES = 3 +const DEFAULT_TIMEOUT = 5000 +``` + +### Configuration Keys + +```yaml +# Use kebab-case for YAML configuration keys +skill-name: my-skill +max-retries: 3 +default-timeout: 5000 + +# JSON uses camelCase +{ + "skillName": "my-skill", + "maxRetries": 3, + "defaultTimeout": 5000 +} +``` + +## Trigger Keywords + +### Skill Triggers + +Triggers define how skills are invoked: + +| Skill | Triggers (English) | Triggers (Chinese) | +|-------|-------------------|-------------------| +| brainstorm | `brainstorm`, `brainstorming` | `头脑风暴` | +| team-planex | `team planex`, `wave pipeline` | `波浪流水线` | +| review-code | `review code`, `code review` | `代码审查` | +| memory-manage | `memory manage`, `update memory` | `更新记忆` | + +### Trigger Guidelines + +1. **Use natural language**: Triggers should be conversational +2. **Support multiple languages**: English and Chinese for built-in skills +3. **Include variants**: Add common synonyms and abbreviations +4. **Be specific**: Avoid overly generic triggers that conflict + +## Session Naming + +### Workflow Sessions + +Sessions use timestamp-based naming: + +``` +.workflow/.team/ +├── TLS-my-project-2026-03-02/ # Team:Project:Date +├── WS-feature-dev-2026-03-02/ # Workflow:Feature:Date +└── review-session-2026-03-02/ # Descriptor:Date +``` + +### Session ID Format + +``` +-- + +Types: +- TLS = Team Lifecycle Session +- WS = Workflow Session +- RS = Review Session +``` + +## Examples + +### Example 1: Good Skill Naming + +```yaml +--- +name: api-scaffolding +description: Generate REST API boilerplate with routes, controllers, and tests +version: 1.0.0 +triggers: + - generate api + - api scaffold + - create api +category: development +tags: [api, rest, scaffolding, generator] +--- +``` + +### Example 2: Good File Organization + +``` +~/.claude/skills/api-scaffolding/ +├── SKILL.md +├── index.ts +├── templates/ +│ ├── controller.ts.template +│ ├── route.ts.template +│ └── test.spec.ts.template +└── examples/ + ├── basic-api.md + └── authenticated-api.md +``` + +### Example 3: Good Command Naming + +```bash +# Clear and hierarchical +ccw api:scaffold:rest +ccw api:scaffold:graphql +ccw api:test:coverage + +# Aliases for convenience +ccw api:scaffold # Defaults to REST +ccw api:test # Defaults to coverage +``` + +## Migration Checklist + +When renaming skills or commands: + +- [ ] Update `SKILL.md` frontmatter +- [ ] Update all trigger references +- [ ] Update documentation links +- [ ] Add migration note in old skill description +- [ ] Update session naming if applicable +- [ ] Test all command invocations + +::: info See Also +- [Custom Skill Development](./custom.md) - Creating your own skills +- [Core Skills Reference](./core-skills.md) - All built-in skills +- [Skills Library](./index.md) - Skill overview and categories +::: diff --git a/docs/zh-CN/features/dashboard.md b/docs/zh-CN/features/dashboard.md deleted file mode 100644 index b94ce628..00000000 --- a/docs/zh-CN/features/dashboard.md +++ /dev/null @@ -1,242 +0,0 @@ -# 仪表板 - -## 一句话概述 -**仪表板通过直观的基于小部件的界面，提供项目工作流状态、统计信息和最近活动的概览。** - ---- - -## 解决的痛点 - -| 痛点 | 当前状态 | 仪表板解决方案 | -|------|----------|----------------| -| **项目可见性不足** | 无法查看整体项目健康状况 | 带有技术栈和开发索引的项目信息横幅 | -| **指标分散** | 统计信息分布在多个位置 | 集中式统计数据，带有迷你趋势图 | -| **工作流状态未知** | 难以跟踪会话进度 | 带有状态细分的饼图 | -| **最近工作丢失** | 无法快速访问活动会话 | 带有任务详情的会话轮播 | -| **索引状态不明确** | 不知道代码是否已索引 | 实时索引状态指示器 | - ---- - -## 概述 - -**位置**: `ccw/frontend/src/pages/HomePage.tsx` - -**用途**: 仪表板主页，提供项目概览、统计信息、工作流状态和最近活动监控。 - -**访问**: 导航 → 仪表板（默认首页，路径为 `/`） - -**布局**: -``` -+--------------------------------------------------------------------------+ -| 仪表板头部（标题 + 刷新） | -+--------------------------------------------------------------------------+ -| WorkflowTaskWidget（组合卡片） | -| +--------------------------------------------------------------------+ | -| | 项目信息横幅（可展开） | | -| | - 项目名称、描述、技术栈徽章 | | -| | - 快速统计（功能、bug修复、增强） | | -| | - 索引状态指示器 | | -| +----------------------------------+---------------------------------+ | -| | 统计部分 | 工作流状态 | 任务详情（轮播） | | -| | - 6 个迷你卡片 | - 饼图 | - 会话导航 | | -| | - 迷你趋势图 | - 图例 | - 任务列表（2 列） | | -| +----------------+-----------------+-------------------------------+ | -+--------------------------------------------------------------------------+ -| RecentSessionsWidget | -| +--------------------------------------------------------------------+ | -| | 标签页：所有任务 | 工作流 | 轻量任务 | | -| | +---------------+---------------+-------------------------------+ | | -| | | 带有状态、进度、标签、时间的任务卡片 | | | -| | +---------------------------------------------------------------+ | | -+--------------------------------------------------------------------------+ -``` - ---- - -## 实时演示 - -:::demo DashboardOverview #DashboardOverview.tsx ::: - ---- - -## 核心功能 - -| 功能 | 描述 | -|------|------| -| **项目信息横幅** | 可展开的横幅，显示项目名称、描述、技术栈（语言、框架、架构）、开发索引（功能/bug修复/增强）和实时索引状态 | -| **统计部分** | 6 个迷你统计卡片（活动会话、总任务、已完成任务、待处理任务、失败任务、今日活动），带有 7 天迷你趋势图 | -| **工作流状态饼图** | 环形图显示会话状态细分（已完成、进行中、计划中、已暂停、已归档），附带百分比 | -| **会话轮播** | 自动轮播（5秒间隔）的会话卡片，带有任务列表、进度条和手动导航箭头 | -| **最近会话小部件** | 所有任务类型的标签页视图，带有筛选、状态徽章和进度指示器 | -| **实时更新** | 统计数据每 60 秒自动刷新，索引状态每 30 秒刷新 | - ---- - -## 组件层次结构 - -``` -HomePage -├── DashboardHeader -│ ├── 标题 -│ └── 刷新操作按钮 -├── WorkflowTaskWidget -│ ├── ProjectInfoBanner（可展开） -│ │ ├── 项目名称和描述 -│ │ ├── 技术栈徽章 -│ │ ├── 快速统计卡片 -│ │ ├── 索引状态指示器 -│ │ ├── 架构部分 -│ │ ├── 关键组件 -│ │ └── 设计模式 -│ ├── 统计部分 -│ │ └── MiniStatCard（6 个卡片，带迷你趋势图） -│ ├── WorkflowStatusChart -│ │ └── 饼图与图例 -│ └── SessionCarousel -│ ├── 导航箭头 -│ └── 会话卡片（任务列表） -└── RecentSessionsWidget - ├── 标签导航（全部 | 工作流 | 轻量任务） - ├── 任务网格 - │ └── TaskItemCard - └── 加载/空状态 -``` - ---- - -## Props API - -### HomePage 组件 - -| Prop | 类型 | 默认值 | 描述 | -|------|------|--------|------| -| - | - | - | 此页面组件不接受任何 props（数据通过 hooks 获取） | - -### WorkflowTaskWidget - -| Prop | 类型 | 默认值 | 描述 | -|------|------|--------|------| -| `className` | `string` | `undefined` | 用于样式的额外 CSS 类 | - -### RecentSessionsWidget - -| Prop | 类型 | 默认值 | 描述 | -|------|------|--------|------| -| `className` | `string` | `undefined` | 用于样式的额外 CSS 类 | -| `maxItems` | `number` | `6` | 要显示的最大项目数量 | - ---- - -## 使用示例 - -### 基础仪表板 - -```tsx -import { HomePage } from '@/pages/HomePage' - -// 仪表板在根路由 (/) 自动渲染 -// 不需要 props - 数据通过 hooks 获取 -``` - -### 嵌入 WorkflowTaskWidget - -```tsx -import { WorkflowTaskWidget } from '@/components/dashboard/widgets/WorkflowTaskWidget' - -function CustomDashboard() { - return ( -
- -
- ) -} -``` - -### 自定义最近会话小部件 - -```tsx -import { RecentSessionsWidget } from '@/components/dashboard/widgets/RecentSessionsWidget' - -function ActivityFeed() { - return ( -
- -
- ) -} -``` - ---- - -## 状态管理 - -### 本地状态 - -| 状态 | 类型 | 描述 | -|------|------|------| -| `hasError` | `boolean` | 关键错误的错误跟踪 | -| `projectExpanded` | `boolean` | 项目信息横幅展开状态 | -| `currentSessionIndex` | `number` | 轮播中活动会话的索引 | -| `activeTab` | `'all' \| 'workflow' \| 'lite'` | 最近会话小部件筛选标签页 | - -### Store 选择器（Zustand） - -| Store | 选择器 | 用途 | -|-------|--------|------| -| `appStore` | `selectIsImmersiveMode` | 检查沉浸模式是否激活 | - -### 自定义 Hooks（数据获取） - -| Hook | 描述 | 重新获取间隔 | -|------|-------------|--------------| -| `useWorkflowStatusCounts` | 会话状态分布数据 | - | -| `useDashboardStats` | 带迷你趋势图的统计数据 | 60 秒 | -| `useProjectOverview` | 项目信息和技术栈 | - | -| `useIndexStatus` | 实时索引状态 | 30 秒 | -| `useSessions` | 活动会话数据 | - | -| `useLiteTasks` | 最近小部件的轻量任务数据 | - | - ---- - -## 交互演示 - -### 统计卡片演示 - -:::demo MiniStatCards #MiniStatCards.tsx ::: - -### 项目信息横幅演示 - -:::demo ProjectInfoBanner #ProjectInfoBanner.tsx ::: - -### 会话轮播演示 - -:::demo SessionCarousel #SessionCarousel.tsx ::: - ---- - -## 可访问性 - -- **键盘导航**： - - Tab - 在交互元素之间导航 - - Enter/Space - 激活按钮和卡片 - - 方向键 - 导航轮播会话 - -- **ARIA 属性**： - - 导航按钮上的 `aria-label` - - 可展开部分的 `aria-expanded` - - 实时更新的 `aria-live` 区域 - -- **屏幕阅读器支持**： - - 所有图表都有文字描述 - - 状态指示器包含文字标签 - - 导航被正确宣布 - ---- - -## 相关链接 - -- [会话](/features/sessions) - 查看和管理所有会话 -- [终端仪表板](/features/terminal) - 终端优先监控界面 -- [队列](/features/queue) - 问题执行队列管理 -- [内存](/features/memory) - 持久化内存管理 -- [设置](/features/settings) - 全局应用设置 diff --git a/docs/zh-CN/index.md b/docs/zh-CN/index.md deleted file mode 100644 index af6acdfc..00000000 --- a/docs/zh-CN/index.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -layout: home -title: Claude Code Workflow -titleTemplate: Claude Code Workflow 文档 - -hero: - name: Claude Code Workflow - text: 高级 AI 驱动开发环境 - tagline: 提升您的编码工作流程，实现智能化开发 - image: - src: /logo.svg - alt: Claude Code Workflow - actions: - - theme: brand - text: 快速开始 - link: /zh-CN/guide/ch01-what-is-claude-dms3 - - theme: alt - text: 查看功能 - link: /zh-CN/features/spec - -features: - - title: 🤖 智能编排 - details: Claude AI 驱动的任务编排，自动拆解复杂项目为可执行的步骤。 - - title: ⚡ 内置技能 - details: 27+ 个内置技能，涵盖代码审查、测试、重构等常见开发场景。 - - title: 🔄 工作流系统 - details: 四级工作流体系，从基础任务到复杂代理团队，灵活适应各种需求。 - - title: 💾 持久化记忆 - details: 跨会话的知识积累和上下文管理，让 AI 学习您的编码偏好。 - - title: 🎨 可视化界面 - details: 丰富的 Web 界面，包括仪表板、终端监控、问题追踪等实用工具。 - - title: 🔌 MCP 集成 - details: 支持 Model Context Protocol，轻松扩展 AI 能力和工具集。 ---- - -## 什么是 Claude Code Workflow？ - -Claude Code Workflow (CCW) 是一个基于 Claude AI 的智能开发环境，通过工作流编排、代理协作和持久化记忆，帮助开发者更高效地完成编码任务。 - -### 核心特性 - -- **智能任务拆解**: 将复杂需求自动分解为可执行的子任务 -- **代理协作系统**: 多个专业代理协同工作，覆盖代码、测试、文档等各个环节 -- **上下文记忆**: 跨会话保持项目知识和编码决策 -- **实时监控**: 终端流监控、问题追踪等可视化工具 -- **CLI 工具集成**: 灵活的命令行工具，支持多种 AI 模型 - -## 快速链接 - -- [安装指南](/zh-CN/guide/installation) -- [第一个工作流](/zh-CN/guide/first-workflow) -- [核心功能](/zh-CN/features/spec) -- [组件文档](/zh-CN/components/) diff --git a/docs/zh-CN/components/index.md b/docs/zh/components/index.md similarity index 100% rename from docs/zh-CN/components/index.md rename to docs/zh/components/index.md diff --git a/docs/zh-CN/components/ui/badge.md b/docs/zh/components/ui/badge.md similarity index 100% rename from docs/zh-CN/components/ui/badge.md rename to docs/zh/components/ui/badge.md diff --git a/docs/zh-CN/components/ui/button.md b/docs/zh/components/ui/button.md similarity index 100% rename from docs/zh-CN/components/ui/button.md rename to docs/zh/components/ui/button.md diff --git a/docs/zh-CN/components/ui/card.md b/docs/zh/components/ui/card.md similarity index 100% rename from docs/zh-CN/components/ui/card.md rename to docs/zh/components/ui/card.md diff --git a/docs/zh-CN/components/ui/checkbox.md b/docs/zh/components/ui/checkbox.md similarity index 100% rename from docs/zh-CN/components/ui/checkbox.md rename to docs/zh/components/ui/checkbox.md diff --git a/docs/zh-CN/components/ui/input.md b/docs/zh/components/ui/input.md similarity index 100% rename from docs/zh-CN/components/ui/input.md rename to docs/zh/components/ui/input.md diff --git a/docs/zh-CN/components/ui/select.md b/docs/zh/components/ui/select.md similarity index 100% rename from docs/zh-CN/components/ui/select.md rename to docs/zh/components/ui/select.md diff --git a/docs/zh-CN/features/queue.md b/docs/zh/features/queue.md similarity index 100% rename from docs/zh-CN/features/queue.md rename to docs/zh/features/queue.md diff --git a/docs/zh-CN/features/terminal.md b/docs/zh/features/terminal.md similarity index 100% rename from docs/zh-CN/features/terminal.md rename to docs/zh/features/terminal.md diff --git a/docs/zh/guide/installation.md b/docs/zh/guide/installation.md index c7791806..7b6f4399 100644 --- a/docs/zh/guide/installation.md +++ b/docs/zh/guide/installation.md @@ -106,13 +106,109 @@ npm install -g claude-code-workflow@latest ## 卸载 -```bash -npm uninstall -g claude-code-workflow +CCW 提供了智能卸载命令，会自动处理安装清单、孤立文件清理和全局文件保护。 -# 删除配置（可选） -rm -rf ~/.claude +### 使用 CCW 卸载命令（推荐） + +```bash +ccw uninstall ``` +卸载流程： + +1. **扫描安装清单** - 自动检测所有已安装的 CCW 实例（Global 和 Path 模式） +2. **交互选择** - 显示安装列表，让您选择要卸载的实例 +3. **智能保护** - 卸载 Path 模式时，如果存在 Global 安装，会自动保护全局文件（workflows、scripts、templates） +4. **孤立文件清理** - 自动清理不再被任何安装引用的 skills 和 commands 文件 +5. **空目录清理** - 移除安装留下的空目录 +6. **Git Bash 修复移除** - Windows 上最后一个安装卸载后，询问是否移除 Git Bash 多行提示修复 + +### 卸载输出示例 + +``` + Found installations: + + 1. Global + Path: /Users/username/my-project + Date: 2026/3/2 + Version: 7.0.5 + Files: 156 | Dirs: 23 + +────────────────────────────────────── +? Select installation to uninstall: Global - /Users/username/my-project +? Are you sure you want to uninstall Global installation? Yes + +✔ Removing files... +✔ Uninstall complete! + +╔══════════════════════════════════════╗ +║ Uninstall Summary ║ +╠══════════════════════════════════════╣ +║ ✓ Successfully Uninstalled ║ +║ ║ +║ Files removed: 156 ║ +║ Directories removed: 23 ║ +║ Orphan files cleaned: 3 ║ +║ ║ +║ Manifest removed ║ +╚══════════════════════════════════════╝ +``` + +### 手动卸载 npm 包 + +如果需要完全移除 CCW npm 包： + +```bash +# 卸载全局 npm 包 +npm uninstall -g claude-code-workflow +``` + +### 手动删除 CCW 文件（不推荐） + +如果必须手动删除，以下是 CCW 安装的具体路径： + +```bash +# CCW 安装的目录（可安全删除） +rm -rf ~/.claude/commands/ccw.md +rm -rf ~/.claude/commands/ccw-coordinator.md +rm -rf ~/.claude/commands/workflow +rm -rf ~/.claude/commands/issue +rm -rf ~/.claude/commands/cli +rm -rf ~/.claude/commands/memory +rm -rf ~/.claude/commands/idaw +rm -rf ~/.claude/skills/workflow-* +rm -rf ~/.claude/skills/team-* +rm -rf ~/.claude/skills/review-* +rm -rf ~/.claude/agents/team-worker.md +rm -rf ~/.claude/agents/cli-*-agent.md +rm -rf ~/.claude/workflows +rm -rf ~/.claude/scripts +rm -rf ~/.claude/templates +rm -rf ~/.claude/manifests +rm -rf ~/.claude/version.json + +# Codex 相关目录 +rm -rf ~/.codex/prompts +rm -rf ~/.codex/skills +rm -rf ~/.codex/agents + +# 其他 CLI 目录 +rm -rf ~/.gemini +rm -rf ~/.qwen + +# CCW 核心目录 +rm -rf ~/.ccw +``` + +::: danger 危险 +**不要**执行 `rm -rf ~/.claude`，这会删除您的 Claude Code 个人配置： +- `~/.claude/settings.json` - 您的 Claude Code 设置 +- `~/.claude/settings.local.json` - 本地覆盖设置 +- MCP 服务器配置等 + +建议始终使用 `ccw uninstall` 进行受控卸载。 +::: + ## 故障排除 ### 权限问题 diff --git a/docs/zh/workflows/teams.md b/docs/zh/workflows/teams.md new file mode 100644 index 00000000..4669ad91 --- /dev/null +++ b/docs/zh/workflows/teams.md @@ -0,0 +1,197 @@ +# 团队工作流 + +CCW 提供多个支持多角色协调复杂任务的团队协作技能。 + +## 团队技能概览 + +| 技能 | 角色 | 流水线 | 用例 | +|-------|-------|----------|----------| +| **team-planex** | 3 (planner + executor) | 波浪流水线（边规划边执行） | 规划和执行并行 | +| **team-iterdev** | 5 (generator → critic → integrator → validator) | 生成器-评论者循环 | 带反馈循环的迭代开发 | +| **team-lifecycle-v4** | 8 (spec → architect → impl → test) | 5 阶段生命周期 | 完整规范 → 实现 → 测试工作流 | +| **team-lifecycle-v5** | 可变 (team-worker) | 内置阶段 | 最新 team-worker 架构 | +| **team-issue** | 6 (explorer → planner → implementer → reviewer → integrator) | 5 阶段问题解决 | 多角色问题求解 | +| **team-testing** | 5 (strategist → generator → executor → analyst) | 4 阶段测试 | 综合测试覆盖 | +| **team-quality-assurance** | 6 (scout → strategist → generator → executor → analyst) | 5 阶段 QA | 质量保障闭环 | +| **team-brainstorm** | 5 (coordinator → ideator → challenger → synthesizer → evaluator) | 5 阶段头脑风暴 | 多视角创意生成 | +| **team-uidesign** | 4 (designer → developer → reviewer) | CP-9 双轨 | UI 设计和实现并行 | +| **team-frontend** | 6 (frontend-lead → ui-developer → ux-engineer → component-dev → qa) | 设计集成 | 带 UI/UX 集成的前端开发 | +| **team-review** | 4 (scanner → reviewer → fixer) | 4 阶段代码审查 | 代码扫描和自动修复 | +| **team-roadmap-dev** | 4 (planner → executor → verifier) | 分阶段执行 | 路线图驱动开发 | +| **team-tech-debt** | 6 (scanner → assessor → planner → executor → validator) | 5 阶段清理 | 技术债务识别和解决 | +| **team-ultra-analyze** | 5 (explorer → analyst → discussant → synthesizer) | 4 阶段分析 | 深度协作代码库分析 | +| **team-coordinate** | 可变 | 通用协调 | 通用团队协调（旧版） | +| **team-coordinate-v2** | 可变 (team-worker) | team-worker 架构 | 现代 team-worker 协调 | +| **team-executor** | 可变 | 轻量级执行 | 基于会话的执行 | +| **team-executor-v2** | 可变 (team-worker) | team-worker 执行 | 现代 team-worker 执行 | + +## 使用方法 + +### 通过 /ccw 编排器 + +```bash +# 基于意图自动路由 +/ccw "team planex: 用户认证系统" +/ccw "全生命周期: 通知服务开发" +/ccw "QA 团队: 质量保障支付流程" + +# 基于团队的工作流 +/ccw "team brainstorm: 新功能想法" +/ccw "team issue: 修复登录超时" +/ccw "team testing: 测试覆盖率提升" +``` + +### 直接调用技能 + +```javascript +// 编程调用 +Skill(skill="team-lifecycle-v5", args="Build user authentication system") +Skill(skill="team-planex", args="Implement OAuth2 with concurrent planning") +Skill(skill="team-quality-assurance", args="Quality audit of payment system") + +// 带模式选择 +Skill(skill="workflow-plan", args="--mode replan") +``` + +### 通过 Task 工具（用于代理调用） + +```javascript +// 生成团队工作器代理 +Task({ + subagent_type: "team-worker", + description: "Spawn executor worker", + team_name: "my-team", + name: "executor", + run_in_background: true, + prompt: `## Role Assignment +role: executor +session: D:/project/.workflow/.team/my-session +session_id: my-session +team_name: my-team +requirement: Implement user authentication +inner_loop: true` +}) +``` + +## 检测关键词 + +| 技能 | 关键词（英文） | 关键词（中文） | +|-------|-------------------|----------------| +| **team-planex** | team planex, plan execute, wave pipeline | 团队规划执行, 波浪流水线 | +| **team-iterdev** | team iterdev, iterative development | 迭代开发团队 | +| **team-lifecycle** | team lifecycle, full lifecycle, spec impl test | 全生命周期, 规范实现测试 | +| **team-issue** | team issue, resolve issue, issue team | 团队 issue, issue 解决团队 | +| **team-testing** | team test, comprehensive test, test coverage | 测试团队, 全面测试 | +| **team-quality-assurance** | team qa, qa team, quality assurance | QA 团队, 质量保障团队 | +| **team-brainstorm** | team brainstorm, collaborative brainstorming | 团队头脑风暴, 协作头脑风暴 | +| **team-uidesign** | team ui design, ui design team, dual track | UI 设计团队, 双轨设计 | +| **team-frontend** | team frontend, frontend team | 前端开发团队 | +| **team-review** | team review, code review team | 代码审查团队 | +| **team-roadmap-dev** | team roadmap, roadmap driven | 路线图驱动开发 | +| **team-tech-debt** | tech debt cleanup, technical debt | 技术债务清理, 清理技术债 | +| **team-ultra-analyze** | team analyze, deep analysis, collaborative analysis | 深度协作分析 | + +## 团队技能架构 + +### 版本演进 + +| 版本 | 架构 | 状态 | +|---------|-------------|--------| +| **v5** | team-worker（动态角色） | **最新** | +| v4 | 5 阶段生命周期，内联讨论 | 稳定 | +| v3 | 3 阶段生命周期 | 旧版 | +| v2 | 通用协调 | 已弃用 | + +### v5 Team Worker 架构 + +最新架构使用 `team-worker` 代理，基于阶段前缀进行动态角色分配： + +| 阶段 | 前缀 | 角色 | +|-------|--------|------| +| 分析 | ANALYSIS | doc-analyst | +| 草稿 | DRAFT | doc-writer | +| 规划 | PLAN | planner | +| 实现 | IMPL | executor (code-developer, tdd-developer 等) | +| 测试 | TEST | tester (test-fix-agent 等) | +| 审查 | REVIEW | reviewer | + +### 角色类型 + +| 类型 | 前缀 | 描述 | +|------|--------|-------------| +| **编排器** | COORD | 管理工作流，协调代理 | +| **负责人** | SPEC, IMPL, TEST | 领导阶段，委派给工作器 | +| **工作器** | 可变 | 执行特定任务 | + +## 工作流模式 + +### 波浪流水线 (team-planex) + +```text +Wave 1: Plan ──────────────────────────────────┐ + ↓ │ +Wave 2: Exec ←────────────────────────────────┘ + ↓ +Wave 3: Plan → Exec → Plan → Exec → ... +``` + +规划和执行并发 - 执行者在第 N 波工作时，规划者正在规划第 N+1 波。 + +### 生成器-评论者循环 (team-iterdev) + +```text +Generator → Output → Critic → Feedback → Generator + ↓ + Integrator → Validator +``` + +通过反馈循环进行迭代改进。 + +### CP-9 双轨 (team-uidesign) + +```text +Design Track: Designer → Tokens → Style + ↓ +Implementation Track: Developer → Components + ↓ + Reviewer → Verify +``` + +设计和实现并行的双轨进行。 + +### 5 阶段生命周期 (team-lifecycle-v4) + +```text +1. Spec Planning (coordinator + spec-lead) +2. Architecture Design (architect) +3. Implementation Planning (impl-lead + dev team) +4. Test Planning (test-lead + qa-analyst) +5. Execution & Verification (all roles) +``` + +线性推进所有生命周期阶段。 + +## 何时使用各团队技能 + +| 场景 | 推荐技能 | +|----------|-------------------| +| 需要并行规划和执行 | **team-planex** | +| 带多次迭代的复杂功能 | **team-iterdev** | +| 完整规范 → 实现 → 测试工作流 | **team-lifecycle-v5** | +| 问题解决 | **team-issue** | +| 综合测试 | **team-testing** | +| 质量审计 | **team-quality-assurance** | +| 新功能创意 | **team-brainstorm** | +| UI 设计 + 实现 | **team-uidesign** | +| 前端特定开发 | **team-frontend** | +| 代码质量审查 | **team-review** | +| 带路线图的大型项目 | **team-roadmap-dev** | +| 技术债务清理 | **team-tech-debt** | +| 深度代码库分析 | **team-ultra-analyze** | + +::: info 另请参阅 +- [技能参考](../skills/reference.md) - 所有技能文档 +- [CLI 命令](../cli/commands.md) - 命令参考 +- [代理](../agents/index.md) - 代理文档 +- [4 级工作流](./4-level.md) - 工作流系统概览 +:::