Synthia Doc Plugin


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

✨ 特性

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

📦 安装

``bash


使用 pnpm

pnpm add -D synthia-doc

使用 npm

npm install -D synthia-doc

使用 yarn

yarn 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 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 配置
`

🎯 最佳实践

$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