forked from Gitlink/gitlink-cli
960 lines
24 KiB
Markdown
960 lines
24 KiB
Markdown
# Wiki 工作流示例
|
||
|
||
本文档提供了使用 `gitlink-cli wiki` 命令的完整工作流示例,涵盖从简单到复杂的各种场景。
|
||
|
||
## 目录
|
||
|
||
- [基础工作流](#基础工作流)
|
||
- [项目文档初始化](#项目文档初始化)
|
||
- [文档维护工作流](#文档维护工作流)
|
||
- [批量操作](#批量操作)
|
||
- [AI Agent 集成](#ai-agent-集成)
|
||
- [故障排除](#故障排除)
|
||
|
||
---
|
||
|
||
## 基础工作流
|
||
|
||
### 工作流 1: 创建单个 Wiki 页面
|
||
|
||
**场景**: 为项目创建首页
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# 1. 创建首页
|
||
gitlink-cli wiki +create --title "Home" --content '# Project Home
|
||
|
||
## Overview
|
||
This project is a CLI tool for GitLink platform.
|
||
|
||
## Features
|
||
- Repository management
|
||
- Issue tracking
|
||
- Pull requests
|
||
|
||
## Documentation
|
||
- [Getting Started](Getting-Started)
|
||
- [API Reference](API-Reference)
|
||
- [Contributing](Contributing)
|
||
|
||
## Support
|
||
- [FAQ](FAQ)
|
||
- [Contact Us](Contact-Us)'
|
||
|
||
# 2. 验证创建结果
|
||
gitlink-cli wiki +view --title "Home"
|
||
|
||
# 3. 列出所有页面
|
||
gitlink-cli wiki +list
|
||
```
|
||
|
||
**预期结果**:
|
||
- 创建了标题为 "Home" 的 Wiki 页面
|
||
- 页面包含导航链接和项目概述
|
||
- 可通过 `wiki +list` 和 `wiki +view` 验证
|
||
|
||
---
|
||
|
||
## 项目文档初始化
|
||
|
||
### 工作流 2: 创建完整项目文档结构
|
||
|
||
**场景**: 为新项目创建完整的 Wiki 文档体系
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# init-project-wiki.sh
|
||
|
||
set -e # 遇到错误立即退出
|
||
|
||
echo "=== Initializing Project Wiki ==="
|
||
|
||
# 1. 创建首页
|
||
echo "Creating Home page..."
|
||
gitlink-cli wiki +create --title "Home" --content '# Project Documentation
|
||
|
||
Welcome to the project documentation!
|
||
|
||
## Quick Links
|
||
- 📚 [Getting Started](Getting-Started) - New user guide
|
||
- 📖 [API Reference](API-Reference) - API documentation
|
||
- 🤝 [Contributing](Contributing) - Contribution guide
|
||
- ❓ [FAQ](FAQ) - Frequently asked questions
|
||
|
||
## Overview
|
||
This project provides a comprehensive CLI tool for GitLink platform management.
|
||
|
||
## Status
|
||
- Version: 1.0.0
|
||
- License: MIT
|
||
- Support: See [Contact Us](Contact-Us)'
|
||
|
||
# 2. 创建入门指南
|
||
echo "Creating Getting Started guide..."
|
||
gitlink-cli wiki +create --title "Getting-Started" --content '# Getting Started
|
||
|
||
## Installation
|
||
|
||
### Prerequisites
|
||
- Node.js 14+
|
||
- GitLink account
|
||
|
||
### Install via npm
|
||
\`\`\`bash
|
||
npm install -g gitlink-cli
|
||
\`\`\`
|
||
|
||
### Install from source
|
||
\`\`\`bash
|
||
git clone https://www.gitlink.org.cn/Gitlink/gitlink-cli.git
|
||
cd gitlink-cli
|
||
make install
|
||
\`\`\`
|
||
|
||
## Configuration
|
||
|
||
### Initialize config
|
||
\`\`\`bash
|
||
gitlink-cli config init
|
||
\`\`\`
|
||
|
||
### Login
|
||
\`\`\`bash
|
||
gitlink-cli auth login
|
||
\`\`\`
|
||
|
||
## Verify Installation
|
||
\`\`\`bash
|
||
gitlink-cli --version
|
||
gitlink-cli user +me
|
||
\`\`\`'
|
||
|
||
# 3. 创建 API 文档
|
||
echo "Creating API Reference..."
|
||
gitlink-cli wiki +create --title "API-Reference" --content '# API Reference
|
||
|
||
## Repository Operations
|
||
|
||
### List repositories
|
||
\`\`\`bash
|
||
gitlink-cli repo +list
|
||
\`\`\`
|
||
|
||
### Create repository
|
||
\`\`\`bash
|
||
gitlink-cli repo +create -n my-project -d "Project description"
|
||
\`\`\`
|
||
|
||
## Issue Operations
|
||
|
||
### List issues
|
||
\`\`\`bash
|
||
gitlink-cli issue +list --owner user --repo project
|
||
\`\`\`
|
||
|
||
### Create issue
|
||
\`\`\`bash
|
||
gitlink-cli issue +create -t "Bug title" -b "Bug description"
|
||
\`\`\`
|
||
|
||
## Pull Request Operations
|
||
|
||
### List PRs
|
||
\`\`\`bash
|
||
gitlink-cli pr +list --owner user --repo project
|
||
\`\`\`
|
||
|
||
### Create PR
|
||
\`\`\`bash
|
||
gitlink-cli pr +create --head feature --base main -t "Feature title"
|
||
\`\`\`'
|
||
|
||
# 4. 创建贡献指南
|
||
echo "Creating Contributing guide..."
|
||
gitlink-cli wiki +create --title "Contributing" --content '# Contributing
|
||
|
||
Thank you for your interest in contributing!
|
||
|
||
## How to Contribute
|
||
|
||
### Report Bugs
|
||
Create an issue with the bug report template.
|
||
|
||
### Submit Changes
|
||
1. Fork the repository
|
||
2. Create a feature branch
|
||
3. Make your changes
|
||
4. Submit a pull request
|
||
|
||
## Development Workflow
|
||
|
||
### Setup Development Environment
|
||
\`\`\`bash
|
||
git clone https://www.gitlink.org.cn/YOUR_USERNAME/gitlink-cli.git
|
||
cd gitlink-cli
|
||
make install
|
||
\`\`\`
|
||
|
||
### Run Tests
|
||
\`\`\`bash
|
||
make test
|
||
\`\`\`
|
||
|
||
### Code Style
|
||
- Follow Go conventions
|
||
- Add tests for new features
|
||
- Update documentation
|
||
|
||
## Pull Request Guidelines
|
||
|
||
### PR Title Format
|
||
- \`feat: add new feature\`
|
||
- \`fix: fix bug description\`
|
||
- \`docs: update documentation\`
|
||
|
||
### PR Description
|
||
Include:
|
||
- Problem statement
|
||
- Solution approach
|
||
- Testing performed
|
||
- Related issues'
|
||
|
||
# 5. 创建 FAQ
|
||
echo "Creating FAQ..."
|
||
gitlink-cli wiki +create --title "FAQ" --content '# Frequently Asked Questions
|
||
|
||
## General Questions
|
||
|
||
### Q: What is gitlink-cli?
|
||
A: GitLink CLI is a command-line tool for managing GitLink platform resources.
|
||
|
||
### Q: How do I install gitlink-cli?
|
||
A: Run \`npm install -g gitlink-cli\` or build from source.
|
||
|
||
## Authentication
|
||
|
||
### Q: How do I authenticate?
|
||
A: Run \`gitlink-cli auth login\` and provide your credentials.
|
||
|
||
### Q: How long does the token last?
|
||
A: Tokens expire after 7 days. Re-authenticate when expired.
|
||
|
||
## Troubleshooting
|
||
|
||
### Q: Command not found
|
||
A: Ensure npm global bin is in your PATH: \`export PATH=\$PATH:\$(npm config get prefix)/bin\`
|
||
|
||
### Q: Permission denied
|
||
A: Run \`gitlink-cli auth login\` to re-authenticate.
|
||
|
||
## More Help
|
||
- See [Getting Started](Getting-Started)
|
||
- Check [API Reference](API-Reference)
|
||
- Contact: [Contact Us](Contact-Us)'
|
||
|
||
# 6. 创建联系我们页面
|
||
echo "Creating Contact Us page..."
|
||
gitlink-cli wiki +create --title "Contact-Us" --content '# Contact Us
|
||
|
||
## Get Help
|
||
|
||
### Documentation
|
||
- [Getting Started](Getting-Started)
|
||
- [API Reference](API-Reference)
|
||
- [FAQ](FAQ)
|
||
|
||
### Community
|
||
- Forum: [GitLink Forum](https://forum.gitlink.org.cn)
|
||
- Chat: [Gitter Channel](https://gitter.im/gitlink-cli)
|
||
|
||
### Report Issues
|
||
- Bug Reports: [Issue Tracker](https://www.gitlink.org.cn/Gitlink/gitlink-cli/issues)
|
||
- Feature Requests: [Issue Tracker](https://www.gitlink.org.cn/Gitlink/gitlink-cli/issues)
|
||
|
||
## Development Team
|
||
|
||
### Maintainers
|
||
- @maintainer1 - Project lead
|
||
- @maintainer2 - Core development
|
||
|
||
### Contributors
|
||
See [CONTRIBUTORS.md](https://www.gitlink.org.cn/Gitlink/gitlink-cli/blob/master/CONTRIBUTORS.md)
|
||
|
||
## License
|
||
This project is licensed under the MulanPSL-2.0 License.
|
||
|
||
## Acknowledgments
|
||
Thanks to all contributors who have helped improve this project!'
|
||
|
||
echo "=== Wiki Initialization Complete ==="
|
||
echo "Created 6 documentation pages:"
|
||
gitlink-cli wiki +list
|
||
```
|
||
|
||
**关键特性**:
|
||
- ✅ 创建了完整的文档结构
|
||
- ✅ 页面之间有交叉引用链接
|
||
- ✅ 包含代码示例和命令
|
||
- ✅ 覆盖了项目的所有主要方面
|
||
|
||
---
|
||
|
||
## 文档维护工作流
|
||
|
||
### 工作流 3: 更新文档内容
|
||
|
||
**场景**: 文档需要定期更新以反映项目变化
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# update-documentation.sh
|
||
|
||
page_title="API-Reference"
|
||
backup_file="wiki-backup-$(date '+%Y%m%d-%H%M%S').md"
|
||
|
||
echo "=== Safe Wiki Update Workflow ==="
|
||
|
||
# 1. 备份当前内容
|
||
echo "Step 1: Backing up current content..."
|
||
gitlink-cli wiki +view --title "$page_title" --format json | \
|
||
jq -r ".data.content_decoded" > "$backup_file"
|
||
echo "✓ Backup saved: $backup_file"
|
||
|
||
# 2. 显示当前内容预览
|
||
echo ""
|
||
echo "Step 2: Current content preview:"
|
||
head -n 10 "$backup_file"
|
||
echo "..."
|
||
|
||
# 3. 编辑内容(使用临时文件)
|
||
temp_file="temp-wiki-update.md"
|
||
cp "$backup_file" "$temp_file"
|
||
|
||
echo ""
|
||
echo "Step 3: Edit the content in: $temp_file"
|
||
echo "Press Enter when done editing..."
|
||
read
|
||
|
||
# 4. 确认更新
|
||
echo ""
|
||
echo "Step 4: Review changes:"
|
||
echo "--- Old content (first 5 lines) ---"
|
||
head -n 5 "$backup_file"
|
||
echo "--- New content (first 5 lines) ---"
|
||
head -n 5 "$temp_file"
|
||
echo "---"
|
||
|
||
read -p "Apply changes? (y/N) " -n 1 -r
|
||
echo
|
||
|
||
if [[ $REPLY =~ ^[Yy]$ ]]; then
|
||
# 5. 执行更新
|
||
echo "Step 5: Applying update..."
|
||
gitlink-cli wiki +update --title "$page_title" --file "$temp_file"
|
||
|
||
# 6. 验证结果
|
||
echo "Step 6: Verifying update..."
|
||
gitlink-cli wiki +view --title "$page_title" --format json | \
|
||
jq -r ".data.content_decoded" > "updated-content.md"
|
||
|
||
if diff -q "$temp_file" "updated-content.md" >/dev/null; then
|
||
echo "✓ Update successful!"
|
||
rm "$temp_file" "updated-content.md"
|
||
else
|
||
echo "✗ Update verification failed!"
|
||
echo "Backup available at: $backup_file"
|
||
fi
|
||
else
|
||
echo "✗ Update cancelled."
|
||
echo "Backup available at: $backup_file"
|
||
rm "$temp_file"
|
||
fi
|
||
```
|
||
|
||
---
|
||
|
||
### 工作流 4: 追加更新日志
|
||
|
||
**场景**: 在文档末尾追加更新日志
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# append-changelog.sh
|
||
|
||
page_title="Home"
|
||
changelog_content="
|
||
|
||
---
|
||
|
||
## Changelog
|
||
|
||
### v$(date '+%Y.%m.%d')
|
||
- Updated documentation structure
|
||
- Added new examples
|
||
- Fixed typos and errors
|
||
- Improved API references"
|
||
|
||
echo "=== Appending Changelog to $page_title ==="
|
||
|
||
# 1. 查看当前末尾内容
|
||
echo "Current page ending:"
|
||
gitlink-cli wiki +view --title "$page_title" --format json | \
|
||
jq -r ".data.content_decoded" | tail -n 5
|
||
|
||
# 2. 确认追加
|
||
echo ""
|
||
echo "Content to append:"
|
||
echo "$changelog_content"
|
||
|
||
read -p "Append changelog? (y/N) " -n 1 -r
|
||
echo
|
||
|
||
if [[ $REPLY =~ ^[Yy]$ ]]; then
|
||
# 3. 追加内容
|
||
gitlink-cli wiki +update --title "$page_title" --add "$changelog_content"
|
||
echo "✓ Changelog appended successfully!"
|
||
|
||
# 4. 验证
|
||
echo ""
|
||
echo "Updated page ending:"
|
||
gitlink-cli wiki +view --title "$page_title" --format json | \
|
||
jq -r ".data.content_decoded" | tail -n 10
|
||
else
|
||
echo "✗ Append cancelled."
|
||
fi
|
||
```
|
||
|
||
---
|
||
|
||
## 批量操作
|
||
|
||
### 工作流 5: 从本地目录批量导入 Wiki
|
||
|
||
**场景**: 将本地的 Markdown 文档批量导入到 Wiki
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# batch-import-wiki.sh
|
||
|
||
wiki_docs_dir="./wiki-docs"
|
||
backup_dir="wiki-import-backup-$(date '+%Y%m%d-%H%M%S')"
|
||
|
||
echo "=== Batch Wiki Import ==="
|
||
|
||
# 1. 检查目录
|
||
if [ ! -d "$wiki_docs_dir" ]; then
|
||
echo "Error: Directory '$wiki_docs_dir' not found."
|
||
echo "Please create it and add your Markdown files."
|
||
exit 1
|
||
fi
|
||
|
||
# 2. 创建备份目录
|
||
mkdir -p "$backup_dir"
|
||
|
||
# 3. 统计文件
|
||
md_files=("$wiki_docs_dir"/*.md)
|
||
total_files=${#md_files[@]}
|
||
|
||
echo "Found $total_files Markdown files in '$wiki_docs_dir'"
|
||
|
||
# 4. 遍历导入
|
||
success_count=0
|
||
skip_count=0
|
||
error_count=0
|
||
|
||
for mdfile in "${md_files[@]}"; do
|
||
# 从文件名提取标题(去掉 .md 后缀)
|
||
filename=$(basename "$mdfile")
|
||
title="${filename%.md}"
|
||
|
||
echo ""
|
||
echo "Processing: $filename"
|
||
|
||
# 检查页面是否已存在
|
||
if gitlink-cli wiki +view --title "$title" >/dev/null 2>&1; then
|
||
echo " ⚠️ Page '$title' already exists. Skipping."
|
||
((skip_count++))
|
||
|
||
# 备份现有页面
|
||
gitlink-cli wiki +view --title "$title" --format json | \
|
||
jq -r ".data.content_decoded" > "$backup_dir/$filename"
|
||
continue
|
||
fi
|
||
|
||
# 创建新页面
|
||
if gitlink-cli wiki +create --title "$title" --file "$mdfile" 2>/dev/null; then
|
||
echo " ✓ Created: $title"
|
||
((success_count++))
|
||
else
|
||
echo " ✗ Failed: $title"
|
||
((error_count++))
|
||
|
||
# 失败时备份文件
|
||
cp "$mdfile" "$backup_dir/"
|
||
fi
|
||
done
|
||
|
||
# 5. 显示统计
|
||
echo ""
|
||
echo "=== Import Summary ==="
|
||
echo "Total files: $total_files"
|
||
echo "✓ Created: $success_count"
|
||
echo "⚠️ Skipped: $skip_count (already exists)"
|
||
echo "✗ Failed: $error_count"
|
||
|
||
if [ $error_count -gt 0 ]; then
|
||
echo ""
|
||
echo "Failed files backed up to: $backup_dir"
|
||
fi
|
||
|
||
# 6. 列出当前所有页面
|
||
echo ""
|
||
echo "Current Wiki pages:"
|
||
gitlink-cli wiki +list
|
||
```
|
||
|
||
---
|
||
|
||
### 工作流 6: 批量导出 Wiki 为本地文件
|
||
|
||
**场景**: 将所有 Wiki 页面导出为本地 Markdown 文件
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# batch-export-wiki.sh
|
||
|
||
export_dir="wiki-export-$(date '+%Y%m%d-%H%M%S')"
|
||
|
||
echo "=== Batch Wiki Export ==="
|
||
|
||
# 1. 创建导出目录
|
||
mkdir -p "$export_dir"
|
||
echo "Export directory: $export_dir"
|
||
|
||
# 2. 获取所有页面标题
|
||
titles=$(gitlink-cli wiki +list --format json | jq -r '.data[].title')
|
||
total_titles=$(echo "$titles" | wc -l)
|
||
|
||
echo "Found $total_titles Wiki pages"
|
||
|
||
# 3. 遍历导出
|
||
success_count=0
|
||
error_count=0
|
||
|
||
for title in $titles; do
|
||
# 清理文件名(替换特殊字符)
|
||
filename=$(echo "$title" | sed 's/[^a-zA-Z0-9_-]/_/g').md
|
||
|
||
echo "Exporting: $title -> $filename"
|
||
|
||
# 导出页面内容
|
||
if gitlink-cli wiki +view --title "$title" --format json | \
|
||
jq -r '.data.content_decoded' > "$export_dir/$filename" 2>/dev/null; then
|
||
echo " ✓ Exported: $filename"
|
||
((success_count++))
|
||
else
|
||
echo " ✗ Failed: $title"
|
||
((error_count++))
|
||
fi
|
||
done
|
||
|
||
# 4. 显示统计
|
||
echo ""
|
||
echo "=== Export Summary ==="
|
||
echo "Total pages: $total_titles"
|
||
echo "✓ Exported: $success_count"
|
||
echo "✗ Failed: $error_count"
|
||
|
||
# 5. 创建索引文件
|
||
echo "# Wiki Export Index" > "$export_dir/README.md"
|
||
echo "" >> "$export_dir/README.md"
|
||
echo "Export Date: $(date)" >> "$export_dir/README.md"
|
||
echo "" >> "$export_dir/README.md"
|
||
echo "## Pages" >> "$export_dir/README.md"
|
||
echo "" >> "$export_dir/README.md"
|
||
|
||
for title in $titles; do
|
||
filename=$(echo "$title" | sed 's/[^a-zA-Z0-9_-]/_/g').md
|
||
echo "- [$title]($filename)" >> "$export_dir/README.md"
|
||
done
|
||
|
||
echo ""
|
||
echo "✓ Index created: $export_dir/README.md"
|
||
echo "Export completed: $export_dir"
|
||
```
|
||
|
||
---
|
||
|
||
### 工作流 7: 批量重命名页面
|
||
|
||
**场景**: 统一 Wiki 页面命名规范
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# batch-rename-wiki.sh
|
||
|
||
# 定义重命名规则(旧标题 -> 新标题)
|
||
declare -A rename_rules=(
|
||
["api"]="API-Reference"
|
||
["getting started"]="Getting-Started"
|
||
["user guide"]="User-Guide"
|
||
["faq"]="FAQ"
|
||
["home"]="Home"
|
||
)
|
||
|
||
echo "=== Batch Wiki Rename ==="
|
||
|
||
# 1. 显示重命名计划
|
||
echo "Planned renames:"
|
||
for old_title in "${!rename_rules[@]}"; do
|
||
new_title="${rename_rules[$old_title]}"
|
||
echo " '$old_title' -> '$new_title'"
|
||
done
|
||
|
||
# 2. 确认执行
|
||
read -p "Proceed with renaming? (yes/NO) " -r
|
||
echo
|
||
|
||
if [[ ! "$REPLY" == "yes" ]]; then
|
||
echo "✗ Renaming cancelled."
|
||
exit 0
|
||
fi
|
||
|
||
# 3. 执行重命名
|
||
success_count=0
|
||
skip_count=0
|
||
error_count=0
|
||
|
||
for old_title in "${!rename_rules[@]}"; do
|
||
new_title="${rename_rules[$old_title]}"
|
||
|
||
echo ""
|
||
echo "Renaming: '$old_title' -> '$new_title'"
|
||
|
||
# 检查旧页面是否存在
|
||
if ! gitlink-cli wiki +view --title "$old_title" >/dev/null 2>&1; then
|
||
echo " ⚠️ Old page '$old_title' not found. Skipping."
|
||
((skip_count++))
|
||
continue
|
||
fi
|
||
|
||
# 检查新页面是否已存在
|
||
if gitlink-cli wiki +view --title "$new_title" >/dev/null 2>&1; then
|
||
echo " ⚠️ Target page '$new_title' already exists. Skipping."
|
||
((skip_count++))
|
||
continue
|
||
fi
|
||
|
||
# 执行重命名
|
||
if gitlink-cli wiki +update --page "$old_title" --title "$new_title" 2>/dev/null; then
|
||
echo " ✓ Renamed successfully"
|
||
((success_count++))
|
||
else
|
||
echo " ✗ Rename failed"
|
||
((error_count++))
|
||
fi
|
||
done
|
||
|
||
# 4. 显示统计
|
||
echo ""
|
||
echo "=== Rename Summary ==="
|
||
echo "Total planned: ${#rename_rules[@]}"
|
||
echo "✓ Renamed: $success_count"
|
||
echo "⚠️ Skipped: $skip_count"
|
||
echo "✗ Failed: $error_count"
|
||
|
||
# 5. 列出当前所有页面
|
||
echo ""
|
||
echo "Current Wiki pages:"
|
||
gitlink-cli wiki +list
|
||
```
|
||
|
||
---
|
||
|
||
## AI Agent 集成
|
||
|
||
### 工作流 8: AI Agent 自动文档管理
|
||
|
||
**场景**: AI Agent 自动维护项目文档
|
||
|
||
```python
|
||
#!/usr/bin/env python3
|
||
# ai_wiki_manager.py - AI Agent Wiki 管理示例
|
||
|
||
import subprocess
|
||
import json
|
||
import os
|
||
from datetime import datetime
|
||
|
||
class WikiManager:
|
||
"""GitLink Wiki 管理器 - 为 AI Agent 设计"""
|
||
|
||
def __init__(self, owner, repo):
|
||
self.owner = owner
|
||
self.repo = repo
|
||
self.base_cmd = ["gitlink-cli", "--owner", owner, "--repo", repo]
|
||
|
||
def run_command(self, command):
|
||
"""执行 gitlink-cli 命令并返回结果"""
|
||
try:
|
||
full_cmd = self.base_cmd + command
|
||
result = subprocess.run(
|
||
full_cmd,
|
||
capture_output=True,
|
||
text=True,
|
||
check=True
|
||
)
|
||
return result.stdout
|
||
except subprocess.CalledProcessError as e:
|
||
print(f"Command failed: {' '.join(full_cmd)}")
|
||
print(f"Error: {e.stderr}")
|
||
return None
|
||
|
||
def list_pages(self):
|
||
"""列出所有 Wiki 页面"""
|
||
output = self.run_command(["wiki", "+list", "--format", "json"])
|
||
if output:
|
||
data = json.loads(output)
|
||
return data.get("data", [])
|
||
return []
|
||
|
||
def get_page_content(self, title):
|
||
"""获取指定页面的内容"""
|
||
output = self.run_command(
|
||
["wiki", "+view", "--title", title, "--format", "json"]
|
||
)
|
||
if output:
|
||
data = json.loads(output)
|
||
return data.get("data", {}).get("content_decoded", "")
|
||
return None
|
||
|
||
def create_page(self, title, content):
|
||
"""创建新页面"""
|
||
# 创建临时文件
|
||
temp_file = f"/tmp/wiki_{title}.md"
|
||
with open(temp_file, 'w') as f:
|
||
f.write(content)
|
||
|
||
# 从文件创建
|
||
result = self.run_command(
|
||
["wiki", "+create", "--title", title, "--file", temp_file]
|
||
)
|
||
|
||
# 清理临时文件
|
||
os.remove(temp_file)
|
||
return result is not None
|
||
|
||
def update_page(self, title, content, mode="cover"):
|
||
"""更新页面内容
|
||
|
||
Args:
|
||
title: 页面标题
|
||
content: 新内容
|
||
mode: 更新模式 ("cover" 或 "add")
|
||
"""
|
||
temp_file = f"/tmp/wiki_update_{title}.md"
|
||
with open(temp_file, 'w') as f:
|
||
f.write(content)
|
||
|
||
if mode == "cover":
|
||
result = self.run_command(
|
||
["wiki", "+update", "--title", title, "--file", temp_file]
|
||
)
|
||
else: # add mode
|
||
result = self.run_command(
|
||
["wiki", "+update", "--title", title, "--add", "",
|
||
"--file", temp_file]
|
||
)
|
||
|
||
os.remove(temp_file)
|
||
return result is not None
|
||
|
||
def delete_page(self, title):
|
||
"""删除页面"""
|
||
result = self.run_command(["wiki", "+delete", "--title", title])
|
||
return result is not None
|
||
|
||
def search_in_pages(self, keyword):
|
||
"""在所有页面中搜索关键词"""
|
||
pages = self.list_pages()
|
||
results = []
|
||
|
||
for page in pages:
|
||
title = page.get("title", "")
|
||
content = self.get_page_content(title)
|
||
|
||
if content and keyword.lower() in content.lower():
|
||
results.append({
|
||
"title": title,
|
||
"url": page.get("sub_url", ""),
|
||
"preview": self.get_preview(content, keyword)
|
||
})
|
||
|
||
return results
|
||
|
||
def get_preview(self, content, keyword, context=50):
|
||
"""获取关键词周围的预览文本"""
|
||
index = content.lower().find(keyword.lower())
|
||
if index == -1:
|
||
return ""
|
||
|
||
start = max(0, index - context)
|
||
end = min(len(content), index + len(keyword) + context)
|
||
return content[start:end]
|
||
|
||
|
||
# AI Agent 使用示例
|
||
def ai_agent_example():
|
||
"""AI Agent 自动维护文档的示例"""
|
||
|
||
# 初始化 Wiki 管理器
|
||
wiki = WikiManager("Gitlink", "forgeplus")
|
||
|
||
print("=== AI Agent Wiki Manager ===")
|
||
|
||
# 1. 检查文档完整性
|
||
print("\n1. Checking documentation completeness...")
|
||
required_pages = ["Home", "Getting-Started", "API-Reference", "FAQ"]
|
||
current_pages = [p.get("title") for p in wiki.list_pages()]
|
||
|
||
missing_pages = set(required_pages) - set(current_pages)
|
||
if missing_pages:
|
||
print(f" ⚠️ Missing pages: {missing_pages}")
|
||
# AI Agent 可以自动创建缺失的页面
|
||
else:
|
||
print(" ✓ All required pages exist")
|
||
|
||
# 2. 检查过时内容
|
||
print("\n2. Checking for outdated content...")
|
||
outdated_keywords = ["version 0.9", "deprecated", "coming soon"]
|
||
for keyword in outdated_keywords:
|
||
results = wiki.search_in_pages(keyword)
|
||
if results:
|
||
print(f" ⚠️ Found '{keyword}' in:")
|
||
for result in results:
|
||
print(f" - {result['title']}")
|
||
# AI Agent 可以标记这些页面需要更新
|
||
|
||
# 3. 自动更新版本信息
|
||
print("\n3. Auto-updating version information...")
|
||
home_content = wiki.get_page_content("Home")
|
||
if home_content and "Version: 1.0.0" in home_content:
|
||
new_version = "1.0.1"
|
||
updated_content = home_content.replace("1.0.0", new_version)
|
||
if wiki.update_page("Home", updated_content, "cover"):
|
||
print(f" ✓ Updated version to {new_version}")
|
||
|
||
# 4. 生成统计报告
|
||
print("\n4. Generating statistics...")
|
||
pages = wiki.list_pages()
|
||
total_pages = len(pages)
|
||
|
||
print(f" Total pages: {total_pages}")
|
||
print(f" Last updated: {datetime.now().strftime('%Y-%m-%d')}")
|
||
|
||
# 计算每个页面的字符数
|
||
for page in pages:
|
||
title = page['title']
|
||
content = wiki.get_page_content(title)
|
||
if content:
|
||
char_count = len(content)
|
||
print(f" - {title}: {char_count} characters")
|
||
|
||
|
||
if __name__ == "__main__":
|
||
ai_agent_example()
|
||
```
|
||
|
||
---
|
||
|
||
## 故障排除
|
||
|
||
### 工作流 9: 常见问题诊断
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# wiki-diagnose.sh - Wiki 问题诊断工具
|
||
|
||
echo "=== Wiki Diagnostic Tool ==="
|
||
|
||
# 1. 检查认证状态
|
||
echo "1. Checking authentication..."
|
||
if gitlink-cli auth status 2>/dev/null | grep -q "Logged in"; then
|
||
echo " ✓ Authentication OK"
|
||
else
|
||
echo " ✗ Authentication failed"
|
||
echo " Solution: Run 'gitlink-cli auth login'"
|
||
exit 1
|
||
fi
|
||
|
||
# 2. 检查网络连接
|
||
echo "2. Checking network connectivity..."
|
||
if curl -s -o /dev/null -w "%{http_code}" https://www.gitlink.org.cn | grep -q "200\|301\|302"; then
|
||
echo " ✓ Network connectivity OK"
|
||
else
|
||
echo " ✗ Network connectivity failed"
|
||
echo " Solution: Check your internet connection"
|
||
fi
|
||
|
||
# 3. 检查 Gateway API 可用性
|
||
echo "3. Checking Gateway API..."
|
||
if curl -s -o /dev/null -w "%{http_code}" https://gateway.gitlink.org.cn/api | grep -q "200\|301\|302"; then
|
||
echo " ✓ Gateway API available"
|
||
else
|
||
echo " ✗ Gateway API unavailable"
|
||
echo " Solution: Gateway API may be down, try again later"
|
||
fi
|
||
|
||
# 4. 检查项目权限
|
||
echo "4. Checking project permissions..."
|
||
if gitlink-cli repo +info >/dev/null 2>&1; then
|
||
echo " ✓ Project access OK"
|
||
else
|
||
echo " ✗ Project access failed"
|
||
echo " Solution: Check if --owner and --repo are correct"
|
||
fi
|
||
|
||
# 5. 测试 Wiki 功能
|
||
echo "5. Testing Wiki functionality..."
|
||
page_count=$(gitlink-cli wiki +list --format json 2>/dev/null | jq '.meta.total_count // 0')
|
||
if [ "$page_count" -ge 0 ]; then
|
||
echo " ✓ Wiki功能正常 (当前页面数: $page_count)"
|
||
else
|
||
echo " ✗ Wiki功能异常"
|
||
echo " Solution: Wiki may not be enabled for this project"
|
||
fi
|
||
|
||
# 6. 显示诊断总结
|
||
echo ""
|
||
echo "=== Diagnostic Summary ==="
|
||
echo "如果以上检查都通过,Wiki 功能应该可以正常使用。"
|
||
echo "如果仍有问题,请检查:"
|
||
echo " 1. 页面标题是否正确(区分大小写)"
|
||
echo " 2. 是否有足够的权限操作 Wiki"
|
||
echo " 3. 网络连接是否稳定"
|
||
echo " 4. GitLink 平台是否正常运行"
|
||
```
|
||
|
||
---
|
||
|
||
## 总结
|
||
|
||
本文档提供了从基础到高级的 Wiki 工作流示例,涵盖:
|
||
|
||
- ✅ **基础操作**: 创建、查看、更新、删除
|
||
- ✅ **项目初始化**: 完整的文档结构建立
|
||
- ✅ **文档维护**: 安全的更新和追加工作流
|
||
- ✅ **批量处理**: 导入、导出、重命名批量操作
|
||
- ✅ **AI 集成**: Python 实现的自动化管理
|
||
- ✅ **故障排除**: 诊断和问题解决
|
||
|
||
这些工作流可以直接使用或根据具体需求调整。
|
||
|
||
## 相关文档
|
||
|
||
- [gitlink-wiki](../SKILL.md) — Wiki 功能总览
|
||
- [wiki +list](../references/wiki-list.md) — 列出页面
|
||
- [wiki +create](../references/wiki-create.md) — 创建页面
|
||
- [wiki +update](../references/wiki-update.md) — 更新页面
|
||
- [wiki +delete](../references/wiki-delete.md) — 删除页面
|