星月
85e58ae239
- Move all Hermes skills from skills/ to hermes/ - Add cursor/ for Cursor rules (.mdc) - Add code-review.mdc (Gitea PR review with tea CLI) - Update sync.sh to use new hermes/ path - Update README with new structure
144 lines
3.3 KiB
Markdown
144 lines
3.3 KiB
Markdown
---
|
|
name: wiki-writing
|
|
description: 在 Gitea wiki 中编写和维护文档。规范格式、操作流程、排版约定。
|
|
version: 1.0.0
|
|
author: 星月
|
|
metadata:
|
|
hermes:
|
|
tags: [wiki, documentation, gitea, writing]
|
|
---
|
|
|
|
# Wiki 编写规范
|
|
|
|
在 Gitea 仓库的 wiki 中编写和维护文档。
|
|
|
|
## Wiki 仓库操作
|
|
|
|
Gitea wiki 本质是一个独立的 git 仓库，地址为 `<repo>.wiki.git`。
|
|
|
|
### Clone
|
|
|
|
```bash
|
|
git clone https://git.shazhou.work/<owner>/<repo>.wiki.git /tmp/<repo>-wiki
|
|
```
|
|
|
|
### 编辑流程
|
|
|
|
```bash
|
|
cd /tmp/<repo>-wiki
|
|
|
|
# 编辑或新建 .md 文件
|
|
# 文件名即 wiki 页面名（用 kebab-case，如 cursor-agent-setup.md）
|
|
|
|
git add -A
|
|
git commit -m "docs: 简要说明改了什么"
|
|
git push
|
|
```
|
|
|
|
### 页面命名
|
|
|
|
- 文件名用 **kebab-case**：`cursor-agent-setup.md`，不要用空格或中文文件名
|
|
- `Home.md` 是 wiki 首页，必须存在
|
|
- 文件名会直接显示为 wiki 侧边栏的页面标题
|
|
|
|
## 排版约定
|
|
|
|
### 语言与标点
|
|
|
|
- **中文文档用中文标点**：`，。：；！？（）【】「」`
|
|
- **英文/代码文档用英文标点**
|
|
- 不要在中文文档中混用半角标点（Gitea 的 "ambiguous Unicode" 警告可忽略，那是给代码文件设计的）
|
|
|
|
### 中英文混排
|
|
|
|
- 中文与英文/数字之间加一个空格：`使用 Cursor Agent 做编码任务`
|
|
- 中文与代码块之间加空格：`用 `tea` 命令读取`
|
|
- 专有名词保持原文：Gitea、Cursor、Hermes，不要翻译
|
|
|
|
### 文档结构
|
|
|
|
```markdown
|
|
# 标题
|
|
|
|
> 作者：xxx | 日期
|
|
|
|
## 背景
|
|
（为什么需要这个）
|
|
|
|
## 前置条件
|
|
（需要什么）
|
|
|
|
## 步骤
|
|
### 1. 第一步
|
|
### 2. 第二步
|
|
|
|
## 注意事项
|
|
（坑和经验）
|
|
```
|
|
|
|
### 代码块
|
|
|
|
- 始终指定语言标记：` ```bash `、` ```python `、` ```markdown `
|
|
- 命令用 `bash`，配置文件用对应格式
|
|
- 代码块内的注释用英文（避免终端编码问题）
|
|
|
|
### 元信息
|
|
|
|
每篇文档开头加作者和日期：
|
|
|
|
```markdown
|
|
> 作者：星月 | 2026-04-22
|
|
```
|
|
|
|
## 内容原则
|
|
|
|
1. **面向 agent 伙伴** — 假设读者是新加入的 Hermes agent，从零开始
|
|
2. **可执行** — 每个步骤给出可直接复制运行的命令
|
|
3. **说明 why** — 不只是 how，还要解释为什么这样做
|
|
4. **记录坑** — 踩过的坑写进"注意事项"，帮后来者避雷
|
|
|
|
## 常见操作
|
|
|
|
### 新建 wiki 页面
|
|
|
|
```bash
|
|
cd /tmp/<repo>-wiki
|
|
cat > new-page.md << 'EOF'
|
|
# 页面标题
|
|
|
|
> 作者：你的名字 | 日期
|
|
|
|
内容...
|
|
EOF
|
|
|
|
git add new-page.md
|
|
git commit -m "docs: add new-page"
|
|
git push
|
|
```
|
|
|
|
### 更新现有页面
|
|
|
|
```bash
|
|
cd /tmp/<repo>-wiki
|
|
git pull # 先拉最新
|
|
# 编辑文件...
|
|
git add -A
|
|
git commit -m "docs: 说明改了什么"
|
|
git push
|
|
```
|
|
|
|
### 查看 wiki 地址
|
|
|
|
页面在浏览器中的 URL 为：
|
|
```
|
|
https://git.shazhou.work/<owner>/<repo>/wiki/<page-name>
|
|
```
|
|
其中 `<page-name>` 对应文件名去掉 `.md` 后缀。
|
|
|
|
## Pitfalls
|
|
|
|
1. **wiki 仓库和代码仓库是分开的** — 它们有独立的 git 历史，push wiki 不会触发代码仓库的 CI
|
|
2. **Gitea 的 Unicode 警告是误报** — 中文文档里的中文标点会触发 "ambiguous Unicode characters" 警告，忽略即可
|
|
3. **文件名避免特殊字符** — 用 kebab-case，不要用空格、中文、或 URL 不友好的字符
|
|
4. **先 pull 再改** — wiki 可能被多人编辑，避免冲突
|