claude-code-workflow 6.3.10 → 6.3.12

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

@@ -0,0 +1,132 @@
+# 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

@@ -0,0 +1,259 @@
+# 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

@@ -0,0 +1,245 @@
+# 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
+```