mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-14 02:42:04 +08:00
169f218f7a
- Improved the reading of the discovery index by adding a fallback mechanism to scan directories for discovery folders if the index.json is invalid or missing. - Added sorting of discoveries by creation time in descending order. - Enhanced the `appendToIssuesJsonl` function to include deduplication logic for issues based on ID and source finding ID. - Updated the discovery route handler to reflect the number of issues added and skipped during export. - Introduced UI elements for selecting and deselecting findings in the dashboard. - Added CSS styles for exported findings and action buttons. - Implemented search functionality for filtering findings based on title, file, and description. - Added internationalization support for new UI elements. - Created scripts for automated API extraction from various project types, including FastAPI and TypeScript. - Documented the API extraction process and library bundling instructions.
162 lines
4.2 KiB
Markdown
162 lines
4.2 KiB
Markdown
# Phase 2.5: API Extraction
|
||
|
||
在项目探索后、并行分析前，自动提取 API 文档。
|
||
|
||
## 核心原则
|
||
|
||
**使用成熟工具提取，确保输出格式与 wiki 模板兼容。**
|
||
|
||
## 执行流程
|
||
|
||
```javascript
|
||
const config = JSON.parse(Read(`${workDir}/manual-config.json`));
|
||
|
||
// 检查项目路径配置
|
||
const apiSources = config.api_sources || detectApiSources(config.project_path);
|
||
|
||
// 执行 API 提取
|
||
Bash({
|
||
command: `python .claude/skills/software-manual/scripts/extract_apis.py -o "${workDir}" -p ${apiSources.join(' ')}`
|
||
});
|
||
|
||
// 验证输出
|
||
const apiDocsDir = `${workDir}/api-docs`;
|
||
const extractedFiles = Glob(`${apiDocsDir}/**/*.{json,md}`);
|
||
console.log(`Extracted ${extractedFiles.length} API documentation files`);
|
||
```
|
||
|
||
## 支持的项目类型
|
||
|
||
| 类型 | 检测方式 | 提取工具 | 输出格式 |
|
||
|------|----------|----------|----------|
|
||
| FastAPI | `app/main.py` + FastAPI import | OpenAPI JSON | `openapi.json` + `API_SUMMARY.md` |
|
||
| Next.js | `package.json` + next | TypeDoc | `*.md` (Markdown) |
|
||
| Python Module | `__init__.py` + setup.py/pyproject.toml | pdoc | `*.md` (Markdown) |
|
||
| Express | `package.json` + express | swagger-jsdoc | `openapi.json` |
|
||
| NestJS | `package.json` + @nestjs | @nestjs/swagger | `openapi.json` |
|
||
|
||
## 输出格式规范
|
||
|
||
### Markdown 兼容性要求
|
||
|
||
确保输出 Markdown 与 wiki CSS 样式兼容：
|
||
|
||
```markdown
|
||
# API Reference → <h1> (wiki-base.css)
|
||
|
||
## Endpoints → <h2>
|
||
|
||
| Method | Path | Summary | → <table> 蓝色表头
|
||
|--------|------|---------|
|
||
| `GET` | `/api/...` | ... | → <code> 红色高亮
|
||
|
||
### GET /api/users → <h3>
|
||
|
||
\`\`\`json → <pre><code> 深色背景
|
||
{
|
||
"id": 1,
|
||
"name": "example"
|
||
}
|
||
\`\`\`
|
||
|
||
- Parameter: `id` (required) → <ul><li> + <code>
|
||
```
|
||
|
||
### 格式验证检查
|
||
|
||
```javascript
|
||
function validateApiDocsFormat(apiDocsDir) {
|
||
const issues = [];
|
||
const mdFiles = Glob(`${apiDocsDir}/**/*.md`);
|
||
|
||
for (const file of mdFiles) {
|
||
const content = Read(file);
|
||
|
||
// 检查表格格式
|
||
if (content.includes('|') && !content.match(/\|.*\|.*\|/)) {
|
||
issues.push(`${file}: 表格格式不完整`);
|
||
}
|
||
|
||
// 检查代码块语言标注
|
||
const codeBlocks = content.match(/```(\w*)\n/g) || [];
|
||
const unlabeled = codeBlocks.filter(b => b === '```\n');
|
||
if (unlabeled.length > 0) {
|
||
issues.push(`${file}: ${unlabeled.length} 个代码块缺少语言标注`);
|
||
}
|
||
|
||
// 检查标题层级
|
||
if (!content.match(/^# /m)) {
|
||
issues.push(`${file}: 缺少一级标题`);
|
||
}
|
||
}
|
||
|
||
return issues;
|
||
}
|
||
```
|
||
|
||
## 项目配置示例
|
||
|
||
在 `manual-config.json` 中配置 API 源：
|
||
|
||
```json
|
||
{
|
||
"software": {
|
||
"name": "Hydro Generator Workbench",
|
||
"type": "web"
|
||
},
|
||
"api_sources": {
|
||
"backend": {
|
||
"path": "D:/dongdiankaifa9/backend",
|
||
"type": "fastapi",
|
||
"entry": "app.main:app"
|
||
},
|
||
"frontend": {
|
||
"path": "D:/dongdiankaifa9/frontend",
|
||
"type": "typescript",
|
||
"entries": ["lib", "hooks", "components"]
|
||
},
|
||
"hydro_generator_module": {
|
||
"path": "D:/dongdiankaifa9/hydro_generator_module",
|
||
"type": "python"
|
||
},
|
||
"multiphysics_network": {
|
||
"path": "D:/dongdiankaifa9/multiphysics_network",
|
||
"type": "python"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 输出结构
|
||
|
||
```
|
||
{workDir}/api-docs/
|
||
├── backend/
|
||
│ ├── openapi.json # OpenAPI 3.0 规范
|
||
│ └── API_SUMMARY.md # Markdown 摘要（wiki 兼容）
|
||
├── frontend/
|
||
│ ├── modules.md # TypeDoc 模块文档
|
||
│ ├── classes/ # 类文档
|
||
│ └── functions/ # 函数文档
|
||
├── hydro_generator/
|
||
│ ├── assembler.md # pdoc 模块文档
|
||
│ ├── blueprint.md
|
||
│ └── builders/
|
||
└── multiphysics/
|
||
├── analysis_domain.md
|
||
├── builders.md
|
||
└── compilers.md
|
||
```
|
||
|
||
## 质量门禁
|
||
|
||
- [ ] 所有配置的 API 源已提取
|
||
- [ ] Markdown 格式与 wiki CSS 兼容
|
||
- [ ] 表格正确渲染（蓝色表头）
|
||
- [ ] 代码块有语言标注
|
||
- [ ] 无空文件或错误文件
|
||
|
||
## 下一阶段
|
||
|
||
→ [Phase 3: Parallel Analysis](03-parallel-analysis.md)
|