12 KiB

Raw Blame History

wiki +update

前置条件： 先阅读 ../../gitlink-shared/SKILL.md 了解认证、全局参数和安全规则。 ⚠️ 写入操作 — 执行前必须确认用户意图。

更新现有 Wiki 页面。支持三种模式：覆盖、追加、重命名。

命令

覆盖模式（完全替换内容）

# 覆盖整个页面内容
gitlink-cli wiki +update --title "Home" --cover "# New Content\n\nThis replaces everything."

# 从文件覆盖
gitlink-cli wiki +update --title "API Reference" --file new-api.md

追加模式（在现有内容后追加）

# 追加内容到现有页面
gitlink-cli wiki +update --title "Home" --add "\n\n## New Section\n\nAdditional content."

# 从文件追加
gitlink-cli wiki +update --title "Guide" --add "" --file appendix.md

重命名模式（更改页面标题）

# 重命名页面（保留原内容）
gitlink-cli wiki +update --page "Old-Title" --title "New-Title"

# 重命名并更新内容
gitlink-cli wiki +update --page "Old-Title" --title "New-Title" --cover "Updated content"

参数

参数	Short	必填	说明
`--title`	`-t`	是	目标页面标题（更新后的标题，用于重命名）
`--page`	`-p`	否	当前页面标题（用于查找和重命名，默认同 `--title`）
`--cover`	`-c`	否*	覆盖整个页面内容（纯文本）
`--add`	`-a`	否*	追加内容到现有页面（纯文本）
`--file`	`-f`	否	从文件读取内容（配合 `--cover` 或 `--add` 使用）
`--message`	`-m`	否	提交消息（可选）
`--owner`		否	仓库所有者（自动从 git remote 解析）
`--repo`		否	仓库名称（自动从 git remote 解析）
`--format`		否	输出格式: `json`/`table`/`yaml`
`--debug`		否	开启调试输出

--cover 或 --add 必须指定其中一个，或都不指定（仅重命名）

返回字段

Table 格式

列名	说明
`title`	更新后的页面标题
`message`	操作结果消息

JSON 格式

{
  "ok": true,
  "data": {
    "title": "Updated Title",
    "message": "Wiki page updated successfully"
  }
}

三种更新模式

1. 覆盖模式 (`--cover`)

完全替换页面内容：

gitlink-cli wiki +update --title "Home" --cover "# New Home Page

This completely replaces the old content."

工作流程：

用户提供新内容
CLI 直接用新内容替换整个页面
旧内容完全丢失

使用场景：

完全重写页面
修正错误内容
大规模内容更新

2. 追加模式 (`--add`)

在现有内容基础上追加：

gitlink-cli wiki +update --title "Home" --add "\n\n## Changelog

### v1.0.0 (2026-06-01)
- Initial release"

工作流程：

CLI 获取当前页面内容
将新内容追加到现有内容后
提交更新后的完整内容

使用场景：

添加新章节
追加更新日志
补充补充说明

3. 重命名模式 (`--page` + `--title`)

更改页面标题：

# 仅重命名（保留原内容）
gitlink-cli wiki +update --page "Old-Title" --title "New-Title"

# 重命名并更新内容
gitlink-cli wiki +update --page "Old-Title" --title "New-Title" --cover "Updated"

工作流程：

--page 指定当前页面标题（用于查找）
--title 指定新标题
如果指定 --cover 或 --add，同时更新内容

使用场景：

修正页面标题拼写
调整命名规范
页面重组

Workflow

覆盖模式

Confirm the new content with the user.
Warning that this will replace all existing content.
Execute gitlink-cli wiki +update --title "<title>" --cover "<new content>".
Report the update result.

追加模式

Confirm the content to append.
Execute gitlink-cli wiki +update --title "<title>" --add "<content>".
Report the update result.

重命名模式

Confirm the old title (--page) and new title (--title).
Execute gitlink-cli wiki +update --page "<old>" --title "<new>".
Report the rename result.

[!CAUTION] 覆盖模式 会完全替换页面内容，无法撤销！建议先使用 wiki +view 查看当前内容，必要时手动备份。

API

PUT https://gateway.gitlink.org.cn/api/wiki/open/updateWiki
Body: {
  "owner": "...",
  "repo": "...",
  "projectId": 123,
  "pageName": "<current-title>",
  "title": "<new-title>",
  "content_base64": "<base64-encoded-content>",
  "message": "<optional-message>"
}

工作流程：

CLI 获取 project_id
如果是追加模式，先获取当前页面内容
将内容 Base64 编码
调用 Gateway API 更新页面
返回更新结果

使用场景

场景 1: 修正文档错误

# 查看当前内容
gitlink-cli wiki +view --title "API Reference"

# 修正错误
gitlink-cli wiki +update --title "API Reference" \
  --file corrected-api.md

场景 2: 添加更新日志

# 追加更新日志到首页
gitlink-cli wiki +update --title "Home" --add '
## Changelog

### v2.0.0 (2026-06-01)
- Added new feature X
- Fixed bug Y
- Improved performance Z'

场景 3: 重命名页面

# 将 "api" 重命名为 "API Reference"
gitlink-cli wiki +update --page "api" --title "API Reference"

# 重命名并更新内容
gitlink-cli wiki +update --page "old-guide" --title "User-Guide" \
  --cover "# User Guide\n\nUpdated content"

场景 4: 批量更新多个页面

#!/bin/bash
# 批量更新所有页面的页脚

declare -A pages=(
  ["Home"]="home.md"
  ["API-Reference"]="api.md"
  ["Guide"]="guide.md"
)

for title in "${!pages[@]}"; do
  file="${pages[$title]}"

  # 读取文件内容作为覆盖内容
  echo "Updating: $title from $file"
  gitlink-cli wiki +update --title "$title" --file "$file"
done

场景 5: 增量更新文档

#!/bin/bash
# 为所有页面添加"最后更新"时间戳

for title in $(gitlink-cli wiki +list --format json | jq -r ".data[].title"); do
    current_date=$(date "+%Y-%m-%d")

    gitlink-cli wiki +update --title "$title" \
      --add "\n\n---\n\n*Last updated: $current_date*"
done

模式选择指南

何时使用覆盖模式？

✅ 使用覆盖模式：

完全重写页面内容
修正严重错误
大规模内容更新
从文件导入新版本

❌ 避免使用覆盖模式：

只需添加小段内容
需要保留部分现有内容
不确定要修改的具体内容

何时使用追加模式？

✅ 使用追加模式：

添加新章节
追加更新日志
补充补充说明
保持历史内容

❌ 避免使用追加模式：

需要修正现有内容
页面内容过长
需要结构性修改

何时使用重命名模式？

✅ 使用重命名模式：

修正拼写错误
统一命名规范
页面重组
调整文档结构

常见问题

Q: 覆盖模式能否撤销？

A: 不能。覆盖模式会完全替换内容，无法自动撤销。

建议：

先使用 wiki +view 查看当前内容
必要时手动备份：gitlink-cli wiki +view --title "Page" > backup.md
再执行覆盖更新

Q: 追加模式的内容位置？

A: 追加的内容会添加到现有内容的末尾。

如果需要精确控制位置：

先查看当前内容
手动编辑（合并旧内容 + 新内容）
使用覆盖模式更新

Q: 重命名后旧标题还能访问吗？

A: 不能。重命名后：

旧标题页面不存在
使用旧标题访问会返回 404
需要更新所有指向旧页面的链接

Q: 如何同时修改标题和内容？

A: 使用 --page + --title + --cover：

gitlink-cli wiki +update \
  --page "Old-Title" \
  --title "New-Title" \
  --cover "New content"

Q: 更新失败提示 "page not found"？

A: 可能原因：

--title 指定的页面不存在
如果使用 --page，当前页面不存在
owner/repo 指定错误

解决方法：

# 先列出所有页面
gitlink-cli wiki +list

# 确认页面标题正确（区分大小写）
gitlink-cli wiki +update --title "Correct-Title" --cover "..."

Q: 追加模式获取旧内容失败？

A: 可能原因：

页面不存在
网络问题
权限不足

解决方法：

# 检查页面是否存在
gitlink-cli wiki +view --title "Page-Name"

# 如果页面不存在，先创建
gitlink-cli wiki +create --title "Page-Name" --content "..."

错误处理

错误	原因	解决方案
`required flag --title is missing`	未指定目标标题	添加 `--title "Page Title"`
`--cover or --file is required`	未提供更新内容	添加 `--cover "..."` 或 `--file file.md`
`failed to fetch current page content`	追加模式下页面不存在	先创建页面或检查标题
`page not found`	指定页面不存在	使用 `wiki +list` 查看可用页面
`401 Unauthorized`	未登录或 Token 过期	运行 `gitlink-cli auth login`
`403 Forbidden`	无权限更新 Wiki	检查是否有项目写入权限

最佳实践

1. 更新前备份

# 更新前先备份当前内容
gitlink-cli wiki +view --title "Important Page" --format json | \
  jq -r ".data.content_decoded" > backup.md

# 然后执行更新
gitlink-cli wiki +update --title "Important Page" --file new-content.md

2. 验证更新结果

# 更新后查看新内容
gitlink-cli wiki +view --title "Page" --format json | \
  jq -r ".data.content_decoded"

3. 使用文件进行复杂更新

# 1. 导出当前内容
gitlink-cli wiki +view --title "Page" --format json | \
  jq -r ".data.content_decoded" > temp.md

# 2. 手动编辑 temp.md

# 3. 更新回 Wiki
gitlink-cli wiki +update --title "Page" --file temp.md

# 4. 清理
rm temp.md

4. 批量重命名规范

#!/bin/bash
# 统一命名规范：将空格替换为连字符

for title in $(gitlink-cli wiki +list --format json | jq -r ".data[].title"); do
    # 如果标题包含空格
    if [[ "$title" =~ " " ]]; then
        # 生成新标题（空格替换为连字符）
        new_title=$(echo "$title" | sed 's/ /-/g')

        echo "Renaming: '$title' -> '$new_title'"
        gitlink-cli wiki +update --page "$title" --title "$new_title"
    fi
done

5. 增量更新工作流

#!/bin/bash
# 安全的追加模式工作流

title="Home"
new_content="## New Section\n\nNew content here."

# 1. 先检查页面是否存在
if gitlink-cli wiki +view --title "$title" >/dev/null 2>&1; then
    # 2. 追加内容
    gitlink-cli wiki +update --title "$title" --add "\n\n$new_content"
    echo "Content appended to $title"
else
    # 3. 页面不存在，创建新页面
    gitlink-cli wiki +create --title "$title" --content "$new_content"
    echo "New page $title created"
fi

完整示例

示例：重构项目文档

#!/bin/bash
# 文档重构工作流

# 1. 备份所有页面
mkdir -p wiki-backup
for title in $(gitlink-cli wiki +list --format json | jq -r ".data[].title"); do
    filename=$(echo "$title" | sed 's/[^a-zA-Z0-9_-]/_/g').md
    gitlink-cli wiki +view --title "$title" --format json | \
      jq -r ".data.content_decoded" > "wiki-backup/$filename"
    echo "Backed up: $title -> $filename"
done

# 2. 重命名页面（统一命名规范）
gitlink-cli wiki +update --page "api" --title "API-Reference"
gitlink-cli wiki +update --page "user guide" --title "User-Guide"

# 3. 更新首页内容
gitlink-cli wiki +update --title "Home" --file new-home.md

# 4. 为所有页面添加页脚
for title in $(gitlink-cli wiki +list --format json | jq -r ".data[].title"); do
    gitlink-cli wiki +update --title "$title" \
      --add "\n\n---\n\n*Updated: $(date '+%Y-%m-%d')*"
done

echo "Wiki restructuring completed!"

References

gitlink-wiki
wiki +create — 创建 Wiki 页面
wiki +view — 查看 Wiki 页面
wiki +delete — 删除 Wiki 页面
gitlink-shared

12 KiB Raw Blame History Unescape Escape

wiki +update

命令

覆盖模式（完全替换内容）

追加模式（在现有内容后追加）

重命名模式（更改页面标题）

参数

返回字段

Table 格式

JSON 格式

三种更新模式

1. 覆盖模式 (--cover)

2. 追加模式 (--add)

3. 重命名模式 (--page + --title)

Workflow

覆盖模式

追加模式

重命名模式

API

使用场景

场景 1: 修正文档错误

场景 2: 添加更新日志

场景 3: 重命名页面

场景 4: 批量更新多个页面

场景 5: 增量更新文档

模式选择指南

何时使用覆盖模式？

何时使用追加模式？

何时使用重命名模式？

常见问题

Q: 覆盖模式能否撤销？

Q: 追加模式的内容位置？

Q: 重命名后旧标题还能访问吗？

Q: 如何同时修改标题和内容？

Q: 更新失败提示 "page not found"？

Q: 追加模式获取旧内容失败？

错误处理

最佳实践

1. 更新前备份

2. 验证更新结果

3. 使用文件进行复杂更新

4. 批量重命名规范

5. 增量更新工作流

完整示例

示例：重构项目文档

References

12 KiB

Raw Blame History

1. 覆盖模式 (`--cover`)

2. 追加模式 (`--add`)

3. 重命名模式 (`--page` + `--title`)