24 KiB
24 KiB
Wiki 工作流示例
本文档提供了使用 gitlink-cli wiki 命令的完整工作流示例，涵盖从简单到复杂的各种场景。
目录
基础工作流
工作流 1: 创建单个 Wiki 页面
场景: 为项目创建首页
#!/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 文档体系
#!/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: 更新文档内容
场景: 文档需要定期更新以反映项目变化
#!/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: 追加更新日志
场景: 在文档末尾追加更新日志
#!/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
#!/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 文件
#!/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 页面命名规范
#!/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 自动维护项目文档
#!/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: 常见问题诊断
#!/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 — Wiki 功能总览
- wiki +list — 列出页面
- wiki +create — 创建页面
- wiki +update — 更新页面
- wiki +delete — 删除页面