@waoooo/claude-skills 1.0.0

package/skills/capability-docs-generate/assets/templates/capability.mdx

@@ -0,0 +1,271 @@
+---
+title: '概览'
+description: 'L2 [能力名称] - 简短描述'
+---
+
+## 概述
+
+[能力名称] 是 Waoooo 平台的**统一 [服务类型] 服务**，负责对接多个 [外部服务类型]，提供统一的 [功能] 接口。
+
+**核心功能**：
+- [核心功能 1]
+- [核心功能 2]
+- [核心功能 3]
+- [核心功能 4]
+
+**能力定位**：
+- 属于 **L2 连接能力层**
+- 只负责 [核心职责]，不负责业务逻辑
+- 触发后续流程（通知 [相关服务]）
+
+---
+
+## 核心职责
+
+### ✅ 负责什么
+
+- **[职责 1]**：[详细说明]
+- **[职责 2]**：[详细说明]
+- **[职责 3]**：[详细说明]
+
+### ❌ 不负责什么
+
+- **[非职责 1]**：[说明为什么不负责]
+- **[非职责 2]**：[说明为什么不负责]
+- **[非职责 3]**：[说明为什么不负责]
+
+---
+
+## 整体架构
+
+### 系统架构图
+
+```mermaid
+flowchart TB
+    subgraph Client["客户端"]
+        Web[Web 应用]
+        Extension[浏览器插件]
+    end
+
+    subgraph L1API["L1 API Client"]
+        APIClient[API Client<br/>HTTP 请求封装]
+    end
+
+    subgraph L2["L2 连接能力层"]
+        Gateway[[能力名称]<br/>统一服务]
+    end
+
+    subgraph L1["L1 基础能力层"]
+        Service1[相关服务 1]
+        Service2[相关服务 2]
+    end
+
+    subgraph Providers["外部服务提供商"]
+        Provider1[供应商 1]
+        Provider2[供应商 2]
+        Provider3[供应商 3]
+    end
+
+    Web --> APIClient
+    Extension --> APIClient
+    APIClient --> Gateway
+
+    Gateway --> Service1
+    Gateway --> Service2
+
+    Gateway --> Provider1
+    Gateway --> Provider2
+    Gateway --> Provider3
+
+    Provider1 -.Webhook.-> Gateway
+    Provider2 -.Webhook.-> Gateway
+    Provider3 -.Webhook.-> Gateway
+
+    style Gateway fill:#e1f5ff
+    style Service1 fill:#fff3cd
+    style Service2 fill:#fff3cd
+    style APIClient fill:#fff3cd
+```
+
+**架构说明**：
+- **客户端**：Web 应用和浏览器插件发起请求
+- **API Client (L1)**：前端统一 HTTP 请求封装，自动注入认证 Token
+- **[能力名称] (L2)**：统一的 [服务类型] 服务，对接多个外部供应商
+- **L1 能力层**：[相关服务列表]
+- **外部供应商**：[供应商列表]
+
+<Note>
+**API Client 说明**：
+- 所有前端到后端的 API 请求都通过 **L1 API Client** 统一处理
+- API Client 自动注入认证 Token、处理请求/响应拦截、统一错误处理
+- L1-L2 层之间的交互也是通过 API 调用实现
+</Note>
+
+---
+
+## 当前实现状态
+
+### ✅ 已实现（[主要供应商]）
+
+**后端功能**：
+- ✅ [供应商] 集成
+- ✅ [核心功能 1]
+- ✅ [核心功能 2]
+- ✅ Webhook 处理和签名验证
+- ✅ 错误处理和重试机制
+
+**前端功能**：
+- ✅ [前端功能 1]
+- ✅ [前端功能 2]
+- ✅ [前端功能 3]
+
+**代码位置**：
+- 后端：`waoooo-service/app/[module]/`
+- 前端：`waoooo-web/packages/@waoooo/[package]/`
+
+### ⚠️ 架构问题
+
+<Warning>
+**当前架构存在的问题**：
+
+**问题描述**：
+- [问题 1]
+- [问题 2]
+- [问题 3]
+
+**影响**：
+- [影响说明 1]
+- [影响说明 2]
+
+**解决方案**：
+- ✅ **[方案 1]**：[说明]
+- ⚠️ **[方案 2]**：[说明]
+</Warning>
+
+### 🔄 计划支持
+
+<Note>
+**未来规划**：
+
+- **[功能 1]**：[说明]
+- **[功能 2]**：[说明]
+- **[功能 3]**：[说明]
+
+**架构要求**：
+- 统一的接口设计
+- 可切换的服务提供商
+- 向后兼容
+</Note>
+
+---
+
+## 快速开始
+
+### 后端调用示例
+
+```python
+# 示例代码
+from app.[module] import [ServiceClass]
+
+# 创建实例
+service = [ServiceClass]()
+
+# 调用方法
+result = await service.[method_name](
+    param1="value1",
+    param2="value2"
+)
+```
+
+### 前端调用示例
+
+```typescript
+// 示例代码
+import { use[Hook] } from '@waoooo/[package]';
+
+function Component() {
+  const { [method], loading, error } = use[Hook]();
+
+  const handleAction = async () => {
+    const result = await [method]({
+      param1: 'value1',
+      param2: 'value2'
+    });
+  };
+
+  return (
+    // JSX
+  );
+}
+```
+
+---
+
+## 深入了解
+
+<CardGroup cols={2}>
+  <Card title="核心概念" icon="lightbulb" href="/capabilities/l2-integration/[capability-name]/concepts">
+    了解核心概念和设计思想
+  </Card>
+
+  <Card title="[功能模块 1]" icon="gear" href="/capabilities/l2-integration/[capability-name]/[module-1]">
+    [功能模块 1 说明]
+  </Card>
+
+  <Card title="[功能模块 2]" icon="route" href="/capabilities/l2-integration/[capability-name]/[module-2]">
+    [功能模块 2 说明]
+  </Card>
+
+  <Card title="[供应商 1]" icon="credit-card" href="/capabilities/l2-integration/[capability-name]/[provider-1]">
+    [供应商 1] 集成文档
+  </Card>
+
+  <Card title="[供应商 2]" icon="credit-card" href="/capabilities/l2-integration/[capability-name]/[provider-2]">
+    [供应商 2] 集成文档
+  </Card>
+
+  <Card title="[供应商 3]" icon="credit-card" href="/capabilities/l2-integration/[capability-name]/[provider-3]">
+    [供应商 3] 集成文档
+  </Card>
+</CardGroup>
+
+---
+
+## API 参考
+
+<CardGroup cols={2}>
+  <Card title="[API 端点 1]" icon="code" href="/api-reference/rest-api/endpoints/[endpoint-1]">
+    [API 端点 1 说明]
+  </Card>
+
+  <Card title="[API 端点 2]" icon="code" href="/api-reference/rest-api/endpoints/[endpoint-2]">
+    [API 端点 2 说明]
+  </Card>
+
+  <Card title="Webhook" icon="webhook" href="/api-reference/rest-api/endpoints/[webhook]">
+    Webhook 回调处理
+  </Card>
+</CardGroup>
+
+---
+
+## 项目规划
+
+<CardGroup cols={2}>
+  <Card title="详细规划" icon="map" href="/planning/[capability-name]">
+    查看详细规划文档
+  </Card>
+
+  <Card title="TODO 任务" icon="list-check" href="/planning/todo/[capability-name]">
+    查看待办任务清单
+  </Card>
+
+  <Card title="ROADMAP" icon="road" href="/planning/ROADMAP">
+    查看项目路线图
+  </Card>
+</CardGroup>
+
+---
+
+**最后更新**：2026-02-06
+**维护者**：Waoooo Development Team

package/skills/capability-docs-generate/scripts/generate-capability-docs.ts

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+/**
+ * Generate Capability Documentation from OpenSpec and Code
+ * 
+ * This script generates capability documentation by:
+ * 1. Reading OpenSpec proposal and design
+ * 2. Analyzing code structure and implementation
+ * 3. Filling the capability.mdx template with extracted data
+ * 4. Outputting to waoooo-docs/developer-docs/capabilities/<layer>/<capability>.mdx
+ * 5. Updating mint.json navigation
+ * 
+ * Usage:
+ *   npx tsx generate-capability-docs.ts \
+ *     --openspec <openspec-path> \
+ *     --capability <capability-id> \
+ *     --layer <l1-foundation|l2-integration|l3-business> \
+ *     --code <code-path>
+ * 
+ * Example:
+ *   npx tsx generate-capability-docs.ts \
+ *     --openspec openspec/changes/001-payment-gateway/ \
+ *     --capability payment-gateway \
+ *     --layer l2-integration \
+ *     --code ../../waoooo-service/app/payment/
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface CapabilityData {
+  name: string;
+  layer: string;
+  description: string;
+  coreFeatures: string[];
+  responsibilities: {
+    what: string[];
+    whatNot: string[];
+  };
+  architecture: {
+    diagram: string;
+    description: string;
+  };
+  implementation: {
+    status: string;
+    backend: string[];
+    frontend: string[];
+    codePaths: {
+      backend: string;
+      frontend: string;
+    };
+  };
+  issues: {
+    problems: string[];
+    impacts: string[];
+    solutions: string[];
+  };
+  futureSupport: string[];
+  quickStart: {
+    backend: string;
+    frontend: string;
+  };
+  apiEndpoints: string[];
+  relatedCapabilities: string[];
+}
+
+// ============================================================================
+// CLI Arguments Parsing
+// ============================================================================
+
+function parseArgs(): {
+  openspecPath: string;
+  capabilityId: string;
+  layer: string;
+  codePath: string;
+} {
+  const args = process.argv.slice(2);
+  const result: any = {};
+
+  for (let i = 0; i < args.length; i += 2) {
+    const key = args[i].replace('--', '');
+    const value = args[i + 1];
+    result[key] = value;
+  }
+
+  if (!result.openspec || !result.capability || !result.layer) {
+    console.error('❌ Missing required arguments');
+    console.error('Usage: generate-capability-docs.ts --openspec <path> --capability <id> --layer <layer> [--code <path>]');
+    process.exit(1);
+  }
+
+  return {
+    openspecPath: result.openspec,
+    capabilityId: result.capability,
+    layer: result.layer,
+    codePath: result.code || '',
+  };
+}
+
+// ============================================================================
+// OpenSpec Parsing
+// ============================================================================
+
+function readOpenSpec(openspecPath: string): { proposal: string; design: string } {
+  const proposalPath = path.join(openspecPath, 'proposal.md');
+  const designPath = path.join(openspecPath, 'design.md');
+
+  if (!fs.existsSync(proposalPath)) {
+    throw new Error(`Proposal not found: ${proposalPath}`);
+  }
+
+  const proposal = fs.readFileSync(proposalPath, 'utf-8');
+  const design = fs.existsSync(designPath) ? fs.readFileSync(designPath, 'utf-8') : '';
+
+  return { proposal, design };
+}
+
+function extractFromOpenSpec(proposal: string, design: string): Partial<CapabilityData> {
+  // Extract title (first # heading)
+  const titleMatch = proposal.match(/^#\s+(.+)$/m);
+  const name = titleMatch ? titleMatch[1] : 'Unknown Capability';
+
+  // Extract description (first paragraph after title)
+  const descMatch = proposal.match(/^#\s+.+\n\n(.+?)(?:\n\n|$)/m);
+  const description = descMatch ? descMatch[1] : '';
+
+  // Extract core features (look for bullet points under "功能" or "Features")
+  const featuresMatch = proposal.match(/##\s+(?:功能|Features|核心功能)[\s\S]*?\n((?:[-*]\s+.+\n?)+)/i);
+  const coreFeatures = featuresMatch
+    ? featuresMatch[1].split('\n').filter(line => line.trim()).map(line => line.replace(/^[-*]\s+/, '').trim())
+    : [];
+
+  // Extract responsibilities from design
+  const responsibilitiesMatch = design.match(/##\s+(?:职责|Responsibilities)[\s\S]*?\n((?:[-*]\s+.+\n?)+)/i);
+  const responsibilities = responsibilitiesMatch
+    ? responsibilitiesMatch[1].split('\n').filter(line => line.trim()).map(line => line.replace(/^[-*]\s+/, '').trim())
+    : [];
+
+  return {
+    name,
+    description,
+    coreFeatures,
+    responsibilities: {
+      what: responsibilities.filter(r => !r.includes('不负责') && !r.includes('not responsible')),
+      whatNot: responsibilities.filter(r => r.includes('不负责') || r.includes('not responsible')),
+    },
+  };
+}
+
+// ============================================================================
+// Code Analysis
+// ============================================================================
+
+function analyzeCode(codePath: string): Partial<CapabilityData> {
+  if (!codePath || !fs.existsSync(codePath)) {
+    return {
+      implementation: {
+        status: 'Not Implemented',
+        backend: [],
+        frontend: [],
+        codePaths: { backend: '', frontend: '' },
+      },
+    };
+  }
+
+  // Simple file listing (can be enhanced with AST parsing)
+  const files = fs.readdirSync(codePath, { recursive: true }) as string[];
+  const pyFiles = files.filter(f => f.endsWith('.py'));
+  const tsFiles = files.filter(f => f.endsWith('.ts') || f.endsWith('.tsx'));
+
+  return {
+    implementation: {
+      status: 'Implemented',
+      backend: pyFiles.slice(0, 5), // Top 5 files
+      frontend: tsFiles.slice(0, 5),
+      codePaths: {
+        backend: codePath.includes('service') ? codePath : '',
+        frontend: codePath.includes('web') ? codePath : '',
+      },
+    },
+  };
+}
+
+// ============================================================================
+// Template Filling
+// ============================================================================
+
+function fillTemplate(data: CapabilityData): string {
+  const templatePath = path.join(__dirname, '../assets/templates/capability.mdx');
+  let template = fs.readFileSync(templatePath, 'utf-8');
+
+  // Replace placeholders
+  template = template.replace(/\[能力名称\]/g, data.name);
+  template = template.replace(/\[服务类型\]/g, data.layer);
+  template = template.replace(/\[简短描述\]/g, data.description);
+
+  // Replace core features
+  const featuresText = data.coreFeatures.map(f => `- ${f}`).join('\n');
+  template = template.replace(/- \[核心功能 1\][\s\S]*?- \[核心功能 4\]/m, featuresText);
+
+  // Replace responsibilities
+  const whatText = data.responsibilities.what.map(r => `- **${r}**`).join('\n');
+  const whatNotText = data.responsibilities.whatNot.map(r => `- **${r}**`).join('\n');
+  template = template.replace(/- \*\*\[职责 1\]\*\*[\s\S]*?- \*\*\[职责 3\]\*\*/m, whatText);
+  template = template.replace(/- \*\*\[非职责 1\]\*\*[\s\S]*?- \*\*\[非职责 3\]\*\*/m, whatNotText);
+
+  // Replace implementation status
+  const backendFiles = data.implementation.backend.map(f => `  - ✅ ${f}`).join('\n');
+  const frontendFiles = data.implementation.frontend.map(f => `  - ✅ ${f}`).join('\n');
+  template = template.replace(/- ✅ \[供应商\] 集成[\s\S]*?- ✅ 错误处理和重试机制/m, backendFiles);
+  template = template.replace(/- ✅ \[前端功能 1\][\s\S]*?- ✅ \[前端功能 3\]/m, frontendFiles);
+
+  // Replace code paths
+  template = template.replace(/waoooo-service\/app\/\[module\]\//g, data.implementation.codePaths.backend);
+  template = template.replace(/waoooo-web\/packages\/@waoooo\/\[package\]\//g, data.implementation.codePaths.frontend);
+
+  // Replace last updated date
+  const today = new Date().toISOString().split('T')[0];
+  template = template.replace(/\*\*最后更新\*\*：\d{4}-\d{2}-\d{2}/, `**最后更新**：${today}`);
+
+  return template;
+}
+
+// ============================================================================
+// Update mint.json (using universal utility)
+// ============================================================================
+
+function updateMintJson(capabilityId: string, layer: string, docsPath: string) {
+  const projectRoot = path.resolve(__dirname, '../../../../../');
+  
+  // Map layer to group name
+  const layerNames: Record<string, string> = {
+    'l1-foundation': 'L1 基础能力层',
+    'l2-integration': 'L2 连接能力层',
+    'l3-business': 'L3 业务能力层',
+  };
+
+  // Calculate relative path
+  const relativePath = path.relative(
+    path.join(projectRoot, 'waoooo-docs'),
+    docsPath
+  ).replace(/\.mdx$/, '');
+
+  // Call universal update-mint-nav utility
+  const updateScript = path.join(__dirname, '../../../../src/scripts/update-mint-nav.ts');
+  const { execSync } = require('child_process');
+
+  try {
+    execSync(
+      `npx tsx "${updateScript}" --section "Capabilities" --group "${layerNames[layer]}" --page "${relativePath}"`,
+      { stdio: 'inherit' }
+    );
+  } catch (error) {
+    console.warn('⚠️  Failed to update mint.json');
+  }
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  console.log('🚀 Generating Capability Documentation...\n');
+
+  const { openspecPath, capabilityId, layer, codePath } = parseArgs();
+
+  console.log('📥 Input:');
+  console.log(`  - OpenSpec: ${openspecPath}`);
+  console.log(`  - Capability: ${capabilityId}`);
+  console.log(`  - Layer: ${layer}`);
+  console.log(`  - Code: ${codePath || '(not provided)'}\n`);
+
+  // Step 1: Read OpenSpec
+  console.log('📖 Step 1/5: Reading OpenSpec...');
+  const { proposal, design } = readOpenSpec(openspecPath);
+  const openspecData = extractFromOpenSpec(proposal, design);
+  console.log('✅ OpenSpec parsed\n');
+
+  // Step 2: Analyze code
+  console.log('🔍 Step 2/5: Analyzing code...');
+  const codeData = analyzeCode(codePath);
+  console.log('✅ Code analyzed\n');
+
+  // Step 3: Merge data
+  console.log('🔗 Step 3/5: Merging data...');
+  const capabilityData: CapabilityData = {
+    name: openspecData.name || capabilityId,
+    layer,
+    description: openspecData.description || '',
+    coreFeatures: openspecData.coreFeatures || [],
+    responsibilities: openspecData.responsibilities || { what: [], whatNot: [] },
+    architecture: {
+      diagram: '(Auto-generated diagram placeholder)',
+      description: '(Auto-generated description)',
+    },
+    implementation: codeData.implementation || {
+      status: 'Not Implemented',
+      backend: [],
+      frontend: [],
+      codePaths: { backend: '', frontend: '' },
+    },
+    issues: {
+      problems: [],
+      impacts: [],
+      solutions: [],
+    },
+    futureSupport: [],
+    quickStart: {
+      backend: '(Auto-generated example)',
+      frontend: '(Auto-generated example)',
+    },
+    apiEndpoints: [],
+    relatedCapabilities: [],
+  };
+  console.log('✅ Data merged\n');
+
+  // Step 4: Fill template and write output
+  console.log('📝 Step 4/5: Generating documentation...');
+  const output = fillTemplate(capabilityData);
+
+  // Determine output path
+  const projectRoot = path.resolve(__dirname, '../../../../../');
+  const docsPath = path.join(projectRoot, 'waoooo-docs/developer-docs/capabilities', layer, `${capabilityId}.mdx`);
+
+  // Ensure directory exists
+  fs.mkdirSync(path.dirname(docsPath), { recursive: true });
+
+  // Write file
+  fs.writeFileSync(docsPath, output, 'utf-8');
+  console.log('✅ Documentation generated\n');
+
+  // Step 5: Update mint.json
+  console.log('🔧 Step 5/5: Updating mint.json...');
+  updateMintJson(capabilityId, layer, docsPath);
+  console.log('');
+
+  console.log('📂 Output:');
+  console.log(`  ${docsPath}\n`);
+
+  console.log('🎉 Done!');
+  console.log('\n💡 Next steps:');
+  console.log('  1. Review the generated documentation');
+  console.log('  2. Fill in missing sections (architecture diagram, issues, etc.)');
+  console.log('  3. Add code examples and API references');
+  console.log('  4. Commit the changes');
+}
+
+main().catch(error => {
+  console.error('❌ Error:', error.message);
+  process.exit(1);
+});