wiki-fmt 1.0.0

一个 Confluence 文档自动排版工具，支持 LLM 智能排版优化

Wiki Format Tool

一个的 Confluence 页面格式化和处理 CLI 工具，支持通过 LLM 自动优化文档排版和内容组织。

功能特性

• 🔄 获取页面内容：从 Confluence 页面 URL 获取内容并转换为 Markdown
• 📝 智能格式化：使用 LLM (OpenAI/Azure OpenAI) 自动优化页面排版和内容结构
• 📤 内容上传：将本地 Markdown 或文本文件上传到 Confluence 页面
• 🔍 连接测试：测试 Confluence API 连接和权限
• 🌐 多平台支持：支持 Confluence Cloud 和 Server/Data Center
• 🛡️ 安全认证：支持多种身份验证方式

安装

通过 pip 安装（推荐）

pip install wiki-fmt

从源码安装

git clone <repository-url>
cd wiki_fmt
pip install -e .

配置

环境变量配置

工具需要配置以下环境变量来连接 Confluence 和 LLM 服务：

Confluence 配置

对于 Confluence Cloud：

export CONFLUENCE_BASE_URL="https://your-domain.atlassian.net"
export CONFLUENCE_USERNAME="[e-mail]"
export CONFLUENCE_API_TOKEN="your-api-token"

对于 Confluence Server/Data Center：

export CONFLUENCE_BASE_URL="https://your-confluence.example.com"
export CONFLUENCE_API_TOKEN="your-personal-access-token"
# 注意：Server/Data Center 不需要设置 CONFLUENCE_USERNAME

OpenAI 配置（任选其一）

使用 OpenAI：

export OPENAI_API_KEY="your-openai-api-key"
export OPENAI_MODEL="gpt-4"  # 可选，默认为 gpt-3.5-turbo
export OPENAI_BASE_URL=

使用 Azure OpenAI：

export AZURE_OPENAI_API_KEY="your-azure-openai-key"
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
export AZURE_OPENAI_API_VERSION="2024-02-15-preview"  # 可选
export AZURE_OPENAI_DEPLOYMENT_NAME="your-deployment-name"

获取 API Token

Confluence Cloud API Token

1. 访问 Atlassian API Tokens
2. 点击 "Create API token"
3. 输入标签名称（如 "wiki-fmt"）
4. 复制生成的 token

Confluence Server/Data Center Personal Access Token

1. 登录到你的 Confluence 实例
2. 进入 Settings → Personal Access Tokens
3. 点击 "Create token"
4. 输入 token 名称并设置权限
5. 复制生成的 token

OpenAI API Key

1. 访问 OpenAI API Keys
2. 点击 "Create new secret key"
3. 复制生成的 API key

使用方法

基本命令

# 测试连接
wiki-fmt test

# 获取页面内容并转换为 Markdown
wiki-fmt get <page-url>

# 格式化页面（仅优化排版，不修改内容）
wiki-fmt format <page-url> [--dry-run]

# 重新组织页面内容和排版
wiki-fmt format <page-url> --reorganize [--dry-run]

# 上传本地文件到页面
wiki-fmt upload <file-path> <page-url> [--format markdown|text] [--dry-run]

详细使用示例

1. 测试连接

wiki-fmt test

输出示例：

✅ Confluence API 连接成功
🔗 连接到: https://your-domain.atlassian.net
👤 认证方式: 用户名/API Token
📁 可访问的空间 (前3个):
   - PROJ → 项目文档
   - TEAM → 团队知识库
   - DEV → 开发文档
✅ 连接测试完成

2. 获取页面内容

wiki-fmt get "https://your-domain.atlassian.net/wiki/spaces/PROJ/pages/123456/Page+Title"

这将：

• 获取页面的 HTML 内容
• 转换为 Markdown 格式
• 保存到本地文件 Page_Title.md

3. 格式化页面（仅排版优化）

# 预览模式（不实际更新）
wiki-fmt format "https://your-domain.atlassian.net/wiki/spaces/PROJ/pages/123456/Page+Title" --dry-run

# 实际更新页面
wiki-fmt format "https://your-domain.atlassian.net/wiki/spaces/PROJ/pages/123456/Page+Title"

仅排版模式会：

• 保持原有内容完全不变
• 优化标题层级结构
• 改善段落和列表格式
• 添加适当的强调标记
• 优化代码块和表格格式

4. 重新组织页面内容

# 预览模式
wiki-fmt format "https://your-domain.atlassian.net/wiki/spaces/PROJ/pages/123456/Page+Title" --reorganize --dry-run

# 实际更新
wiki-fmt format "https://your-domain.atlassian.net/wiki/spaces/PROJ/pages/123456/Page+Title" --reorganize

重新组织模式会：

• 分析内容逻辑，重新组织结构
• 优化文字表达，提高可读性
• 完善标题层级和段落结构
• 保持技术细节和关键信息准确性

5. 上传本地文件

# 上传 Markdown 文件
wiki-fmt upload "./my-document.md" "https://your-domain.atlassian.net/wiki/spaces/PROJ/pages/123456/Page+Title" --format markdown

# 上传纯文本文件
wiki-fmt upload "./notes.txt" "https://your-domain.atlassian.net/wiki/spaces/PROJ/pages/123456/Page+Title" --format text

# 预览模式（不实际上传）
wiki-fmt upload "./my-document.md" "https://your-domain.atlassian.net/wiki/spaces/PROJ/pages/123456/Page+Title" --dry-run

命令行选项说明

全局选项

• --help: 显示帮助信息
• --version: 显示版本信息

format 命令选项

• --reorganize: 启用内容重新组织模式（默认为仅排版模式）
• --dry-run: 预览模式，显示处理结果但不实际更新页面

upload 命令选项

• --format {markdown,text}: 指定文件格式（默认：markdown）
• --dry-run: 预览模式，显示上传内容但不实际更新页面

最佳实践

1. 使用建议

• 首次使用：建议先运行 wiki-fmt test 确保连接正常
• 格式化操作：首次使用时建议先用 --dry-run 参数预览效果
• 批量操作：处理重要页面时建议先备份原始内容
• 权限检查：确保使用的账户对目标页面有编辑权限

2. 安全注意事项

• 环境变量：不要在代码或配置文件中硬编码 API Token
• 权限最小化：使用具有最小必要权限的账户
• 测试环境：建议先在测试环境中验证功能

3. 性能优化

• Token 权限：确保 API Token 有足够权限访问目标空间
• 网络连接：确保网络连接稳定，特别是处理大页面时
• LLM 配额：注意 OpenAI API 的使用配额和限制

4. 故障排除

常见错误

连接失败：

❌ Confluence API 连接失败: 401 Unauthorized

• 检查 CONFLUENCE_BASE_URL 是否正确
• 检查 API Token 是否有效
• 确认用户名和密码配置正确

页面不存在：

❌ 无法获取页面内容

• 确认页面 URL 正确
• 检查页面访问权限
• 确认页面未被删除

LLM 服务错误：

❌ LLM 格式化失败: Invalid API key

• 检查 OpenAI API Key 是否正确
• 确认 API Key 有足够配额
• 检查网络连接到 OpenAI 服务

调试模式

设置环境变量启用详细日志：

export LOG_LEVEL=DEBUG
wiki-fmt test

开发

项目结构

wiki_fmt/
├── __init__.py
├── cli.py          # 命令行接口
└── formatter.py    # 核心功能实现

本地开发

# 克隆项目
git clone <repository-url>
cd wiki_fmt

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install -e .

# 运行测试
wiki-fmt test

版本历史

• v1.0.0: 初始版本
  • 支持页面内容获取和转换
  • 支持 LLM 格式化
  • 支持本地文件上传
  • 支持 Confluence Cloud 和 Server

许可证

[许可证信息]

贡献

欢迎提交 Issue 和 Pull Request！

支持

如果遇到问题或有功能建议，请：

1. 查看本文档的故障排除部分
2. 在项目仓库中提交 Issue
3. 联系项目维护者