claude-code-workflow 6.3.53 → 7.0.0

package/.claude/skills/software-manual/phases/05-html-assembly.md

@@ -1,132 +0,0 @@
-# Phase 5: HTML Assembly
-
-使用 `universal-executor` 子 Agent 生成最终 HTML，避免主 Agent 内存溢出。
-
-## 核心原则
-
-**主 Agent 负责编排，子 Agent 负责繁重计算。**
-
-## 执行流程
-
-```javascript
-const config = JSON.parse(Read(`${workDir}/manual-config.json`));
-
-// 委托给 universal-executor 执行 HTML 组装
-const result = Task({
-  subagent_type: 'universal-executor',
-  run_in_background: false,
-  prompt: buildAssemblyPrompt(config, workDir)
-});
-
-const buildResult = JSON.parse(result);
-```
-
-## Prompt 构建
-
-```javascript
-function buildAssemblyPrompt(config, workDir) {
-  return `
-[ROLE] HTML Assembler
-
-[TASK]
-生成 TiddlyWiki 风格的交互式 HTML 手册（使用成熟库，无外部 CDN 依赖）
-
-[INPUT]
-- 模板: .claude/skills/software-manual/templates/tiddlywiki-shell.html
-- CSS: .claude/skills/software-manual/templates/css/wiki-base.css, wiki-dark.css
-- 配置: ${workDir}/manual-config.json
-- 章节: ${workDir}/sections/section-*.md
-- Agent 结果: ${workDir}/agent-results.json (含 tag 信息)
-- 截图: ${workDir}/screenshots/
-
-[LIBRARIES TO EMBED]
-1. marked.js (v14+) - Markdown 转 HTML
-   - 从 https://unpkg.com/marked/marked.min.js 获取内容内嵌
-2. highlight.js (v11+) - 代码语法高亮
-   - 核心 + 常用语言包 (js, ts, python, bash, json, yaml, html, css)
-   - 使用 github-dark 主题
-
-[STEPS]
-1. 读取 HTML 模板和 CSS
-2. 内嵌 marked.js 和 highlight.js 代码
-3. 读取 agent-results.json 提取各章节 tag
-4. 动态生成 {{TAG_BUTTONS_HTML}} (基于实际使用的 tags)
-5. 逐个读取 section-*.md，使用 marked 转换为 HTML
-6. 为代码块添加 data-language 属性和语法高亮
-7. 处理 <!-- SCREENSHOT: id="..." --> 标记，嵌入 Base64 图片
-8. 生成目录、搜索索引
-9. 组装最终 HTML，写入 ${workDir}/${config.software.name}-使用手册.html
-
-[CONTENT FORMATTING]
-- 代码块: 深色背景 + 语言标签 + 语法高亮
-- 表格: 蓝色表头 + 边框 + 悬停效果
-- 内联代码: 红色高亮
-- 列表: 有序/无序样式增强
-- 左侧导航: 固定侧边栏 + TOC
-
-[RETURN JSON]
-{
-  "status": "completed",
-  "output_file": "${config.software.name}-使用手册.html",
-  "file_size": "<size>",
-  "sections_count": <n>,
-  "tags_generated": [],
-  "screenshots_embedded": <n>
-}
-`;
-}
-```
-
-## Agent 职责
-
-1. **读取模板** → HTML + CSS
-2. **转换章节** → Markdown → HTML tiddlers
-3. **嵌入截图** → Base64 编码
-4. **生成索引** → 搜索数据
-5. **组装输出** → 单文件 HTML
-
-## Markdown 转换规则
-
-Agent 内部实现：
-
-```
-# H1 → <h1>
-## H2 → <h2>
-### H3 → <h3>
-```code``` → <pre><code>
-**bold** → <strong>
-*italic* → <em>
-[text](url) → <a href>
-- item → <li>
-<!-- SCREENSHOT: id="xxx" --> → <figure><img src="data:..."></figure>
-```
-
-## Tiddler 结构
-
-```html
-<article class="tiddler" id="tiddler-{name}" data-tags="..." data-difficulty="...">
-  <header class="tiddler-header">
-    <h2><button class="collapse-toggle">▼</button> {title}</h2>
-    <div class="tiddler-meta">{badges}</div>
-  </header>
-  <div class="tiddler-content">{html}</div>
-</article>
-```
-
-## 输出
-
-- `{软件名}-使用手册.html` - 最终 HTML
-- `build-report.json` - 构建报告
-
-## 质量门禁
-
-- [ ] HTML 渲染正确
-- [ ] 搜索功能可用
-- [ ] 折叠/展开正常
-- [ ] 主题切换持久化
-- [ ] 截图显示正确
-- [ ] 文件大小 < 10MB
-
-## 下一阶段
-
-→ [Phase 6: Iterative Refinement](06-iterative-refinement.md)

package/.claude/skills/software-manual/phases/06-iterative-refinement.md

@@ -1,259 +0,0 @@
-# Phase 6: Iterative Refinement
-
-Preview, collect feedback, and iterate until quality meets standards.
-
-## Objective
-
-- Preview generated HTML in browser
-- Collect user feedback
-- Address issues iteratively
-- Finalize documentation
-
-## Execution Steps
-
-### Step 1: Preview HTML
-
-```javascript
-const buildReport = JSON.parse(Read(`${workDir}/build-report.json`));
-const outputFile = `${workDir}/${buildReport.output}`;
-
-// Open in default browser for preview
-Bash({ command: `start "${outputFile}"` });  // Windows
-// Bash({ command: `open "${outputFile}"` });  // macOS
-
-// Report to user
-console.log(`
-📖 Manual Preview
-
-File: ${buildReport.output}
-Size: ${buildReport.size_human}
-Sections: ${buildReport.sections}
-Screenshots: ${buildReport.screenshots}
-
-Please review the manual in your browser.
-`);
-```
-
-### Step 2: Collect Feedback
-
-```javascript
-const feedback = await AskUserQuestion({
-  questions: [
-    {
-      question: "How does the manual look overall?",
-      header: "Overall",
-      options: [
-        { label: "Looks great!", description: "Ready to finalize" },
-        { label: "Minor issues", description: "Small tweaks needed" },
-        { label: "Major issues", description: "Significant changes required" },
-        { label: "Missing content", description: "Need to add more sections" }
-      ],
-      multiSelect: false
-    },
-    {
-      question: "Which aspects need improvement? (Select all that apply)",
-      header: "Improvements",
-      options: [
-        { label: "Content accuracy", description: "Fix incorrect information" },
-        { label: "More examples", description: "Add more code examples" },
-        { label: "Better screenshots", description: "Retake or add screenshots" },
-        { label: "Styling/Layout", description: "Improve visual appearance" }
-      ],
-      multiSelect: true
-    }
-  ]
-});
-```
-
-### Step 3: Address Feedback
-
-Based on feedback, take appropriate action:
-
-#### Minor Issues
-
-```javascript
-if (feedback.overall === "Minor issues") {
-  // Prompt for specific changes
-  const details = await AskUserQuestion({
-    questions: [{
-      question: "What specific changes are needed?",
-      header: "Details",
-      options: [
-        { label: "Typo fixes", description: "Fix spelling/grammar" },
-        { label: "Reorder sections", description: "Change section order" },
-        { label: "Update content", description: "Modify existing text" },
-        { label: "Custom changes", description: "I'll describe the changes" }
-      ],
-      multiSelect: true
-    }]
-  });
-
-  // Apply changes based on user input
-  applyMinorChanges(details);
-}
-```
-
-#### Major Issues
-
-```javascript
-if (feedback.overall === "Major issues") {
-  // Return to relevant phase
-  console.log(`
-  Major issues require returning to an earlier phase:
-
-  - Content issues → Phase 3 (Parallel Analysis)
-  - Screenshot issues → Phase 4 (Screenshot Capture)
-  - Structure issues → Phase 2 (Project Exploration)
-
-  Which phase should we return to?
-  `);
-
-  const phase = await selectPhase();
-  return { action: 'restart', from_phase: phase };
-}
-```
-
-#### Missing Content
-
-```javascript
-if (feedback.overall === "Missing content") {
-  // Identify missing sections
-  const missing = await AskUserQuestion({
-    questions: [{
-      question: "What content is missing?",
-      header: "Missing",
-      options: [
-        { label: "API endpoints", description: "More API documentation" },
-        { label: "UI features", description: "Additional UI guides" },
-        { label: "Examples", description: "More code examples" },
-        { label: "Troubleshooting", description: "More FAQ items" }
-      ],
-      multiSelect: true
-    }]
-  });
-
-  // Run additional agent(s) for missing content
-  await runSupplementaryAgents(missing);
-}
-```
-
-### Step 4: Save Iteration
-
-```javascript
-// Save current version before changes
-const iterationNum = getNextIterationNumber(workDir);
-const iterationDir = `${workDir}/iterations`;
-
-// Copy current version
-Bash({ command: `copy "${outputFile}" "${iterationDir}\\v${iterationNum}.html"` });
-
-// Log iteration
-const iterationLog = {
-  version: iterationNum,
-  timestamp: new Date().toISOString(),
-  feedback: feedback,
-  changes: appliedChanges
-};
-
-Write(`${iterationDir}/iteration-${iterationNum}.json`, JSON.stringify(iterationLog, null, 2));
-```
-
-### Step 5: Regenerate if Needed
-
-```javascript
-if (changesApplied) {
-  // Re-run HTML assembly with updated sections
-  await runPhase('05-html-assembly');
-
-  // Open updated preview
-  Bash({ command: `start "${outputFile}"` });
-}
-```
-
-### Step 6: Finalize
-
-When user approves:
-
-```javascript
-if (feedback.overall === "Looks great!") {
-  // Final quality check
-  const finalReport = {
-    ...buildReport,
-    iterations: iterationNum,
-    finalized_at: new Date().toISOString(),
-    quality_score: calculateFinalQuality()
-  };
-
-  Write(`${workDir}/final-report.json`, JSON.stringify(finalReport, null, 2));
-
-  // Suggest final location
-  console.log(`
-  ✅ Manual Finalized!
-
-  Output: ${buildReport.output}
-  Size: ${buildReport.size_human}
-  Quality: ${finalReport.quality_score}%
-  Iterations: ${iterationNum}
-
-  Suggested actions:
-  1. Copy to project root: copy "${outputFile}" "docs/"
-  2. Add to version control
-  3. Publish to documentation site
-  `);
-
-  return { status: 'completed', output: outputFile };
-}
-```
-
-## Iteration History
-
-Each iteration is logged:
-
-```
-iterations/
-├── v1.html                    # First version
-├── iteration-1.json           # Feedback and changes
-├── v2.html                    # After first iteration
-├── iteration-2.json           # Feedback and changes
-└── ...
-```
-
-## Quality Metrics
-
-Track improvement across iterations:
-
-```javascript
-const qualityMetrics = {
-  content_completeness: 0,   // All sections present
-  screenshot_coverage: 0,     // Screenshots for all UI
-  example_diversity: 0,       // Different difficulty levels
-  search_accuracy: 0,         // Search returns relevant results
-  user_satisfaction: 0        // Based on feedback
-};
-```
-
-## Exit Conditions
-
-The refinement phase ends when:
-1. User explicitly approves ("Looks great!")
-2. Maximum iterations reached (configurable, default: 5)
-3. Quality score exceeds threshold (default: 90%)
-
-## Output
-
-- **Final HTML**: `{软件名}-使用手册.html`
-- **Final Report**: `final-report.json`
-- **Iteration History**: `iterations/`
-
-## Completion
-
-When finalized, the skill is complete. Final output location:
-
-```
-.workflow/.scratchpad/manual-{timestamp}/
-├── {软件名}-使用手册.html     ← Final deliverable
-├── final-report.json
-└── iterations/
-```
-
-Consider copying to a permanent location like `docs/` or project root.

package/.claude/skills/software-manual/scripts/api-extractor.md

@@ -1,245 +0,0 @@
-# API 文档提取脚本
-
-根据项目类型自动提取 API 文档，支持 FastAPI、Next.js、Python 模块。
-
-## 支持的技术栈
-
-| 类型 | 技术栈 | 工具 | 输出格式 |
-|------|--------|------|----------|
-| Backend | FastAPI | openapi-to-md | Markdown |
-| Frontend | Next.js/TypeScript | TypeDoc | Markdown |
-| Python Module | Python | pdoc | Markdown/HTML |
-
-## 使用方法
-
-### 1. FastAPI Backend (OpenAPI)
-
-```bash
-# 提取 OpenAPI JSON
-cd D:/dongdiankaifa9/backend
-python -c "
-from app.main import app
-import json
-print(json.dumps(app.openapi(), indent=2))
-" > api-docs/openapi.json
-
-# 转换为 Markdown (使用 widdershins)
-npx widdershins api-docs/openapi.json -o api-docs/API_REFERENCE.md --language_tabs 'python:Python' 'javascript:JavaScript' 'bash:cURL'
-```
-
-**备选方案 (无需启动服务)**:
-```python
-# scripts/extract_fastapi_openapi.py
-import sys
-sys.path.insert(0, 'D:/dongdiankaifa9/backend')
-
-from app.main import app
-import json
-
-openapi_schema = app.openapi()
-with open('api-docs/openapi.json', 'w', encoding='utf-8') as f:
-    json.dump(openapi_schema, f, indent=2, ensure_ascii=False)
-
-print(f"Extracted {len(openapi_schema.get('paths', {}))} endpoints")
-```
-
-### 2. Next.js Frontend (TypeDoc)
-
-```bash
-cd D:/dongdiankaifa9/frontend
-
-# 安装 TypeDoc
-npm install --save-dev typedoc typedoc-plugin-markdown
-
-# 生成文档
-npx typedoc --plugin typedoc-plugin-markdown \
-  --out api-docs \
-  --entryPoints "./lib" "./hooks" "./components" \
-  --entryPointStrategy expand \
-  --exclude "**/node_modules/**" \
-  --exclude "**/*.test.*" \
-  --readme none
-```
-
-**typedoc.json 配置**:
-```json
-{
-  "$schema": "https://typedoc.org/schema.json",
-  "entryPoints": ["./lib", "./hooks", "./components"],
-  "entryPointStrategy": "expand",
-  "out": "api-docs",
-  "plugin": ["typedoc-plugin-markdown"],
-  "exclude": ["**/node_modules/**", "**/*.test.*", "**/*.spec.*"],
-  "excludePrivate": true,
-  "excludeInternal": true,
-  "readme": "none",
-  "name": "Frontend API Reference"
-}
-```
-
-### 3. Python Module (pdoc)
-
-```bash
-# 安装 pdoc
-pip install pdoc
-
-# hydro_generator_module
-cd D:/dongdiankaifa9
-pdoc hydro_generator_module \
-  --output-dir api-docs/hydro_generator \
-  --format markdown \
-  --no-show-source
-
-# multiphysics_network
-pdoc multiphysics_network \
-  --output-dir api-docs/multiphysics \
-  --format markdown \
-  --no-show-source
-```
-
-**备选: Sphinx (更强大)**:
-```bash
-# 安装 Sphinx
-pip install sphinx sphinx-markdown-builder
-
-# 生成 API 文档
-sphinx-apidoc -o docs/source hydro_generator_module
-cd docs && make markdown
-```
-
-## 集成脚本
-
-```python
-#!/usr/bin/env python3
-# scripts/extract_all_apis.py
-
-import subprocess
-import sys
-from pathlib import Path
-
-PROJECTS = {
-    'backend': {
-        'path': 'D:/dongdiankaifa9/backend',
-        'type': 'fastapi',
-        'output': 'api-docs/backend'
-    },
-    'frontend': {
-        'path': 'D:/dongdiankaifa9/frontend',
-        'type': 'typescript',
-        'output': 'api-docs/frontend'
-    },
-    'hydro_generator_module': {
-        'path': 'D:/dongdiankaifa9/hydro_generator_module',
-        'type': 'python',
-        'output': 'api-docs/hydro_generator'
-    },
-    'multiphysics_network': {
-        'path': 'D:/dongdiankaifa9/multiphysics_network',
-        'type': 'python',
-        'output': 'api-docs/multiphysics'
-    }
-}
-
-def extract_fastapi(config):
-    """提取 FastAPI OpenAPI 文档"""
-    path = Path(config['path'])
-    sys.path.insert(0, str(path))
-    
-    try:
-        from app.main import app
-        import json
-        
-        output_dir = Path(config['output'])
-        output_dir.mkdir(parents=True, exist_ok=True)
-        
-        # 导出 OpenAPI JSON
-        with open(output_dir / 'openapi.json', 'w', encoding='utf-8') as f:
-            json.dump(app.openapi(), f, indent=2, ensure_ascii=False)
-        
-        print(f"✓ FastAPI: {len(app.openapi().get('paths', {}))} endpoints")
-        return True
-    except Exception as e:
-        print(f"✗ FastAPI error: {e}")
-        return False
-
-def extract_typescript(config):
-    """提取 TypeScript 文档"""
-    try:
-        subprocess.run([
-            'npx', 'typedoc',
-            '--plugin', 'typedoc-plugin-markdown',
-            '--out', config['output'],
-            '--entryPoints', './lib', './hooks',
-            '--entryPointStrategy', 'expand'
-        ], cwd=config['path'], check=True)
-        print(f"✓ TypeDoc: {config['path']}")
-        return True
-    except Exception as e:
-        print(f"✗ TypeDoc error: {e}")
-        return False
-
-def extract_python(config):
-    """提取 Python 模块文档"""
-    try:
-        module_name = Path(config['path']).name
-        subprocess.run([
-            'pdoc', module_name,
-            '--output-dir', config['output'],
-            '--format', 'markdown'
-        ], cwd=Path(config['path']).parent, check=True)
-        print(f"✓ pdoc: {module_name}")
-        return True
-    except Exception as e:
-        print(f"✗ pdoc error: {e}")
-        return False
-
-EXTRACTORS = {
-    'fastapi': extract_fastapi,
-    'typescript': extract_typescript,
-    'python': extract_python
-}
-
-if __name__ == '__main__':
-    for name, config in PROJECTS.items():
-        print(f"\n[{name}]")
-        extractor = EXTRACTORS.get(config['type'])
-        if extractor:
-            extractor(config)
-```
-
-## Phase 3 集成
-
-在 `api-reference` Agent 提示词中添加：
-
-```
-[PRE-EXTRACTION]
-运行 API 提取脚本获取结构化文档：
-- python scripts/extract_all_apis.py
-
-[INPUT FILES]
-- api-docs/backend/openapi.json (FastAPI endpoints)
-- api-docs/frontend/*.md (TypeDoc output)
-- api-docs/hydro_generator/*.md (pdoc output)
-- api-docs/multiphysics/*.md (pdoc output)
-```
-
-## 输出结构
-
-```
-api-docs/
-├── backend/
-│   ├── openapi.json          # Raw OpenAPI spec
-│   └── API_REFERENCE.md      # Converted Markdown
-├── frontend/
-│   ├── modules.md
-│   ├── functions.md
-│   └── classes/
-├── hydro_generator/
-│   ├── assembler.md
-│   ├── blueprint.md
-│   └── builders/
-└── multiphysics/
-    ├── analysis_domain.md
-    ├── builders.md
-    └── compilers.md
-```