# wiki +update

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

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

## 命令

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

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

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

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

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

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

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

```bash
# 重命名页面（保留原内容）
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 格式

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

## 三种更新模式

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

**完全替换页面内容**：

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

This completely replaces the old content."
```

**工作流程**：
1. 用户提供新内容
2. CLI 直接用新内容替换整个页面
3. 旧内容**完全丢失**

**使用场景**：
- 完全重写页面
- 修正错误内容
- 大规模内容更新

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

**在现有内容基础上追加**：

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

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

**工作流程**：
1. CLI 获取当前页面内容
2. 将新内容追加到现有内容后
3. 提交更新后的完整内容

**使用场景**：
- 添加新章节
- 追加更新日志
- 补充补充说明

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

**更改页面标题**：

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

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

**工作流程**：
1. `--page` 指定当前页面标题（用于查找）
2. `--title` 指定新标题
3. 如果指定 `--cover` 或 `--add`，同时更新内容

**使用场景**：
- 修正页面标题拼写
- 调整命名规范
- 页面重组

## Workflow

### 覆盖模式

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

### 追加模式

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

### 重命名模式

1. **Confirm** the old title (`--page`) and new title (`--title`).
2. **Execute** `gitlink-cli wiki +update --page "<old>" --title "<new>"`.
3. **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>"
}
```

**工作流程**：
1. CLI 获取 `project_id`
2. 如果是追加模式，先获取当前页面内容
3. 将内容 Base64 编码
4. 调用 Gateway API 更新页面
5. 返回更新结果

## 使用场景

### 场景 1: 修正文档错误

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

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

### 场景 2: 添加更新日志

```bash
# 追加更新日志到首页
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: 重命名页面

```bash
# 将 "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: 批量更新多个页面

```bash
#!/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: 增量更新文档

```bash
#!/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:** **不能**。覆盖模式会完全替换内容，无法自动撤销。

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

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

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

如果需要精确控制位置：
1. 先查看当前内容
2. 手动编辑（合并旧内容 + 新内容）
3. 使用覆盖模式更新

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

**A:** **不能**。重命名后：
- 旧标题页面不存在
- 使用旧标题访问会返回 404
- 需要更新所有指向旧页面的链接

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

**A:** 使用 `--page` + `--title` + `--cover`：
```bash
gitlink-cli wiki +update \
  --page "Old-Title" \
  --title "New-Title" \
  --cover "New content"
```

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

**A:** 可能原因：
1. `--title` 指定的页面不存在
2. 如果使用 `--page`，当前页面不存在
3. `owner/repo` 指定错误

**解决方法**：
```bash
# 先列出所有页面
gitlink-cli wiki +list

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

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

**A:** 可能原因：
1. 页面不存在
2. 网络问题
3. 权限不足

**解决方法**：
```bash
# 检查页面是否存在
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. 更新前备份

```bash
# 更新前先备份当前内容
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. 验证更新结果

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

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

```bash
# 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. 批量重命名规范

```bash
#!/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. 增量更新工作流

```bash
#!/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
```

## 完整示例

### 示例：重构项目文档

```bash
#!/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](../SKILL.md)
- [wiki +create](wiki-create.md) — 创建 Wiki 页面
- [wiki +view](wiki-view.md) — 查看 Wiki 页面
- [wiki +delete](wiki-delete.md) — 删除 Wiki 页面
- [gitlink-shared](../../gitlink-shared/SKILL.md)
