synthia-doc

v0.0.2

Published

a month ago

Synthia Engine Doc Plugin - 提供文档生成功能的 Synthia 插件

0High
0Medium
0Low

brandnewvoice

synthia plugin documentation generator markdown

Synthia Doc Plugin

Synthia Doc Plugin 是 Synthia Engine 的文档管理插件，提供文档生成、知识图谱构建和智能搜索功能。支持多种文档格式，包括 Markdown、MDX、RST 等。

✨ 特性

📚 多格式支持: 支持 Markdown、MDX、RST、TXT、JSON 等格式
🧠 知识图谱: 构建项目文档的知识图谱，支持语义搜索
🔍 智能搜索: 基于语义的文档搜索功能
🖥️ 预览服务: 内置文档预览服务器
📊 统计分析: 详细的文档统计和分析
🔄 自动更新: 监听文件变化自动更新索引
🎯 灵活配置: 丰富的配置选项支持

📦 安装

# 使用 pnpm
pnpm add -D synthia-doc

# 使用 npm
npm install -D synthia-doc

# 使用 yarn
yarn add -D synthia-doc

🚀 快速开始

1. 在 Synthia 配置中启用插件

// synthia.config.ts
import { defineConfig } from 'synthia-cli';
import { docPlugin } from 'synthia-doc';

export default defineConfig({
  plugins: [
    {
      name: 'doc',
      plugin: docPlugin({
        knowledgeGraph: {
          enabled: true,
          storage: {
            type: 'file',
            path: '.synthia-knowledge',
          },
        },
        preview: {
          enabled: true,
          port: 3001,
        },
      }),
    },
  ],
});

2. 生成知识图谱

# 生成文档知识图谱索引
synthia doc --generate

# 启动文档预览服务
synthia doc --serve

# 搜索文档内容
synthia doc --search "API 文档"

# 查看统计信息
synthia doc --stats

📋 命令选项

| 选项 | 类型 | 描述 | 默认值 | | ------------ | ------- | ---------------------------------- | -------------- | | --generate | boolean | 生成知识图谱索引 | false | | --serve | boolean | 启动文档预览服务 | false | | --search | string | 搜索文档内容 | - | | --stats | boolean | 显示图谱统计信息 | false | | --watch | boolean | 监听文件变化自动更新 | false | | --output | string | 指定输出目录 | .synthia-doc | | --format | string | 指定输出格式 (html|pdf|markdown) | html |

⚙️ 配置选项

DocPluginOptions

interface DocPluginOptions {
  enabled?: boolean; // 是否启用插件
  type?: 'local' | 'cloud' | 'hybrid'; // 存储类型
  directory?: string; // 文档目录
  ttl?: number; // 缓存过期时间
  maxSize?: string; // 最大缓存大小
  compression?: boolean; // 是否压缩
  strategy?: 'lru' | 'fifo' | 'lfu'; // 缓存策略

  // 知识图谱配置
  knowledgeGraph?: {
    enabled?: boolean;
    storage?: {
      type?: 'file' | 'memory';
      path?: string;
      compression?: boolean;
    };
    search?: {
      defaultType?: 'semantic' | 'hybrid' | 'keyword';
      maxResults?: number;
      minRelevanceScore?: number;
      enableCache?: boolean;
      cacheSize?: number;
    };
    indexing?: {
      autoIndex?: boolean;
      indexInterval?: number;
      incrementalIndex?: boolean;
    };
    embedding?: {
      enabled?: boolean;
      dimensions?: number;
      model?: string;
    };
  };

  // 文档预览服务配置
  preview?: {
    enabled?: boolean;
    port?: number;
    host?: string;
    open?: boolean;
    theme?: 'default' | 'dark' | 'light';
  };
}

📚 支持的文档格式

Markdown (.md)

# API 文档

## 用户管理

### 创建用户

```typescript
interface CreateUserRequest {
  name: string;
  email: string;
}
```

更新用户

更新用户信息的接口说明...


### MDX (.mdx)

```mdx
import { CodeBlock } from './components/CodeBlock';

# 组件文档

<CodeBlock language="typescript">
interface Props {
  title: string;
  children: React.ReactNode;
}
</CodeBlock>

RST (.rst)

API 文档
========

用户管理
--------

创建用户
~~~~~~~~

.. code-block:: typescript

   interface CreateUserRequest {
     name: string;
     email: string;
   }

JSON (.json)

{
  "title": "API 规范",
  "version": "1.0.0",
  "endpoints": [
    {
      "path": "/api/users",
      "method": "POST",
      "description": "创建用户"
    }
  ]
}

🔍 搜索功能

语义搜索

# 语义搜索 - 理解查询意图
synthia doc --search "如何创建用户"

# 关键词搜索 - 精确匹配
synthia doc --search "CreateUserRequest"

# 混合搜索 - 结合语义和关键词
synthia doc --search "用户管理 API"

搜索结果

搜索结果包含：

📄 文档标题和路径
📝 内容摘要
🎯 相关性评分
🔗 相关链接

🖥️ 预览服务

启动预览服务

# 启动预览服务
synthia doc --serve

# 指定端口
synthia doc --serve --port 8080

# 自动打开浏览器
synthia doc --serve --open

预览功能

🌐 Web 界面浏览文档
🔍 实时搜索功能
📱 响应式设计
🎨 主题切换支持
📊 文档统计展示

📊 统计分析

查看统计信息

# 查看知识图谱统计
synthia doc --stats

统计内容

📈 节点总数和边总数
📁 文档类型分布
🕒 最后更新时间
📊 索引质量指标

🔧 高级用法

自定义文档扫描

// synthia.config.ts
export default defineConfig({
  plugins: [
    {
      name: 'doc',
      plugin: docPlugin({
        knowledgeGraph: {
          indexing: {
            autoIndex: true,
            indexInterval: 30000, // 30秒
            incrementalIndex: true,
          },
        },
      }),
    },
  ],
});

监听模式

# 监听文件变化
synthia doc --watch

# 监听特定目录
synthia doc --watch --pattern "docs/**/*.md"

输出格式

# HTML 格式输出
synthia doc --generate --format html

# PDF 格式输出
synthia doc --generate --format pdf

# Markdown 格式输出
synthia doc --generate --format markdown

📁 项目结构

your-project/
├── docs/
│   ├── api/
│   │   ├── users.md
│   │   └── products.md
│   ├── guides/
│   │   ├── getting-started.md
│   │   └── advanced-usage.md
│   └── components/
│       ├── Button.mdx
│       └── Modal.mdx
├── .synthia-knowledge/    # 知识图谱存储
├── .synthia-doc/         # 生成的文档
└── synthia.config.ts     # Synthia 配置

🎯 最佳实践

1. 文档组织

docs/
├── README.md              # 项目概述
├── getting-started/       # 入门指南
│   ├── installation.md
│   ├── quick-start.md
│   └── examples.md
├── api/                   # API 文档
│   ├── authentication.md
│   ├── users.md
│   └── products.md
├── guides/                # 使用指南
│   ├── configuration.md
│   ├── deployment.md
│   └── troubleshooting.md
└── components/            # 组件文档
    ├── Button.mdx
    ├── Modal.mdx
    └── Form.mdx

2. 文档元数据

---
title: '用户管理 API'
description: '用户相关的 API 接口文档'
tags: ['api', 'users', 'authentication']
lastUpdated: '2024-01-15'
---

# 用户管理 API

用户管理相关的 API 接口说明...

3. 搜索优化

# 使用描述性的标题

## 创建新用户账户

# 添加关键词标签

<!-- tags: user, create, account, registration -->

# 使用结构化的内容

### 请求参数

### 响应格式

### 错误处理

🔌 集成示例

与 VitePress 集成

// synthia.config.ts
export default defineConfig({
  plugins: [
    {
      name: 'doc',
      plugin: docPlugin({
        preview: {
          enabled: false, // 禁用内置预览
        },
        knowledgeGraph: {
          enabled: true,
        },
      }),
    },
  ],
});

与 GitBook 集成

# 生成 GitBook 格式
synthia doc --generate --format gitbook

# 输出到 GitBook 目录
synthia doc --generate --output ./gitbook

🐛 故障排除

常见问题

Q: 知识图谱生成失败

# 检查文档文件是否存在
ls -la docs/

# 检查权限
chmod -R 755 docs/

# 重新生成
synthia doc --generate --force

Q: 搜索无结果

# 确保已生成知识图谱
synthia doc --generate

# 检查搜索关键词
synthia doc --search "API"

Q: 预览服务启动失败

# 检查端口是否被占用
lsof -i :3001

# 使用其他端口
synthia doc --serve --port 3002

调试模式

# 启用详细日志
synthia doc --generate --verbose

# 查看知识图谱状态
synthia doc --stats --verbose

🔧 自定义配置

知识图谱配置

// synthia.config.ts
export default defineConfig({
  plugins: [
    {
      name: 'doc',
      plugin: docPlugin({
        knowledgeGraph: {
          storage: {
            type: 'file',
            path: '.custom-knowledge',
            compression: true,
          },
          search: {
            defaultType: 'semantic',
            maxResults: 20,
            minRelevanceScore: 0.5,
            enableCache: true,
            cacheSize: 2000,
          },
          embedding: {
            enabled: true,
            dimensions: 1024,
            model: 'text-embedding-ada-002',
          },
        },
      }),
    },
  ],
});

预览服务配置

// synthia.config.ts
export default defineConfig({
  plugins: [
    {
      name: 'doc',
      plugin: docPlugin({
        preview: {
          enabled: true,
          port: 8080,
          host: '0.0.0.0',
          open: true,
          theme: 'dark',
        },
      }),
    },
  ],
});

🤝 贡献

欢迎贡献代码！请查看贡献指南了解详细信息。

开发环境设置

# 克隆仓库
git clone https://github.com/your-org/synthia-engine.git

# 安装依赖
pnpm install

# 运行测试
pnpm test

# 构建插件
pnpm build

📄 许可证

MIT License - 查看 LICENSE 文件了解详细信息。

🔗 相关链接

📞 支持

如果您遇到问题或有任何疑问，请：

查看 FAQ
搜索 Issues
创建新的 Issue
加入我们的 Discord 社区