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

Synthia Doc Plugin 是 Synthia Engine 的文档管理插件,提供文档生成、知识图谱构建和智能搜索功能。支持多种文档格式,包括 Markdown、MDX、RST 等。
- 📚 多格式支持: 支持 Markdown、MDX、RST、TXT、JSON 等格式
- 🧠 知识图谱: 构建项目文档的知识图谱,支持语义搜索
- 🔍 智能搜索: 基于语义的文档搜索功能
- 🖥️ 预览服务: 内置文档预览服务器
- 📊 统计分析: 详细的文档统计和分析
- 🔄 自动更新: 监听文件变化自动更新索引
- 🎯 灵活配置: 丰富的配置选项支持
``bash使用 pnpm
pnpm add -D synthia-doc
🚀 快速开始
$3
`typescript
// 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,
},
}),
},
],
});
`$3
`bash
生成文档知识图谱索引
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 |⚙️ 配置选项
$3
`typescript
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';
};
}
`📚 支持的文档格式
$3
``markdown
API 文档
用户管理
$3
`typescript
interface CreateUserRequest {
name: string;
email: string;
}
`
``$3
更新用户信息的接口说明...
``$3
`mdx
import { CodeBlock } from './components/CodeBlock';组件文档
interface Props {
title: string;
children: React.ReactNode;
}
``$3
`rst
API 文档
========用户管理
--------
创建用户
~~~~~~~~
.. code-block:: typescript
interface CreateUserRequest {
name: string;
email: string;
}
`$3
`json
{
"title": "API 规范",
"version": "1.0.0",
"endpoints": [
{
"path": "/api/users",
"method": "POST",
"description": "创建用户"
}
]
}
`🔍 搜索功能
$3
`bash
语义搜索 - 理解查询意图
synthia doc --search "如何创建用户"关键词搜索 - 精确匹配
synthia doc --search "CreateUserRequest"混合搜索 - 结合语义和关键词
synthia doc --search "用户管理 API"
`$3
搜索结果包含:
- 📄 文档标题和路径
- 📝 内容摘要
- 🎯 相关性评分
- 🔗 相关链接
🖥️ 预览服务
$3
`bash
启动预览服务
synthia doc --serve指定端口
synthia doc --serve --port 8080自动打开浏览器
synthia doc --serve --open
`$3
- 🌐 Web 界面浏览文档
- 🔍 实时搜索功能
- 📱 响应式设计
- 🎨 主题切换支持
- 📊 文档统计展示
📊 统计分析
$3
`bash
查看知识图谱统计
synthia doc --stats
`$3
- 📈 节点总数和边总数
- 📁 文档类型分布
- 🕒 最后更新时间
- 📊 索引质量指标
🔧 高级用法
$3
`typescript
// synthia.config.ts
export default defineConfig({
plugins: [
{
name: 'doc',
plugin: docPlugin({
knowledgeGraph: {
indexing: {
autoIndex: true,
indexInterval: 30000, // 30秒
incrementalIndex: true,
},
},
}),
},
],
});
`$3
`bash
监听文件变化
synthia doc --watch监听特定目录
synthia doc --watch --pattern "docs/*/.md"
`$3
`bash
HTML 格式输出
synthia doc --generate --format htmlPDF 格式输出
synthia doc --generate --format pdfMarkdown 格式输出
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 配置
`🎯 最佳实践
$3
`
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
`$3
`markdown
---
title: '用户管理 API'
description: '用户相关的 API 接口文档'
tags: ['api', 'users', 'authentication']
lastUpdated: '2024-01-15'
---用户管理 API
用户管理相关的 API 接口说明...
`$3
`markdown
使用描述性的标题
创建新用户账户
添加关键词标签
使用结构化的内容
$3
$3
$3
`🔌 集成示例
$3
`typescript
// synthia.config.ts
export default defineConfig({
plugins: [
{
name: 'doc',
plugin: docPlugin({
preview: {
enabled: false, // 禁用内置预览
},
knowledgeGraph: {
enabled: true,
},
}),
},
],
});
`$3
`bash
生成 GitBook 格式
synthia doc --generate --format gitbook输出到 GitBook 目录
synthia doc --generate --output ./gitbook
`🐛 故障排除
$3
Q: 知识图谱生成失败
`bash
检查文档文件是否存在
ls -la docs/检查权限
chmod -R 755 docs/重新生成
synthia doc --generate --force
`Q: 搜索无结果
`bash
确保已生成知识图谱
synthia doc --generate检查搜索关键词
synthia doc --search "API"
`Q: 预览服务启动失败
`bash
检查端口是否被占用
lsof -i :3001使用其他端口
synthia doc --serve --port 3002
`$3
`bash
启用详细日志
synthia doc --generate --verbose查看知识图谱状态
synthia doc --stats --verbose
`🔧 自定义配置
$3
`typescript
// 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',
},
},
}),
},
],
});
`$3
`typescript
// 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',
},
}),
},
],
});
`🤝 贡献
欢迎贡献代码!请查看 贡献指南 了解详细信息。
$3
`bash
克隆仓库
git clone https://github.com/your-org/synthia-engine.git安装依赖
pnpm install运行测试
pnpm test构建插件
pnpm build
``MIT License - 查看 LICENSE 文件了解详细信息。
- Synthia Engine 主页
- 插件开发指南
- API 文档
- 更新日志
如果您遇到问题或有任何疑问,请:
1. 查看 FAQ
2. 搜索 Issues
3. 创建新的 Issue
4. 加入我们的 Discord 社区
---
Made with ❤️ by the Synthia Team