From 3a2eb40bef84ef6bbc1f55f34a25a8ba575321b2 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Tue, 25 Aug 2026 14:58:54 +0800 Subject: [PATCH] =?UTF-8?q?docs(gitea):=20=E5=90=8C=E6=AD=A5=E6=96=87?= =?UTF-8?q?=E4=BB=B6=E8=88=87=E5=8F=83=E8=80=83=E8=B3=87=E6=96=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：更新 README、AGENTS.md、templates 與 references，讓文件敘述與實際行為一致。 Why：稽核發現多處文件與程式行為分歧，違反「每個意義只有單一真實來源」。 How：以實際程式行為為準改寫敘述，重複的規則收成單一來源並以一行指引指過去。 Who：jsc-meta:skill-check 例行稽核（2026-08-25）。 Co-Authored-By: Claude Opus 5 --- README.md | 15 ++++++++++++--- references/wiki-links.md | 24 ++++++++++++++++++++++++ 2 files changed, 36 insertions(+), 3 deletions(-) create mode 100644 references/wiki-links.md diff --git a/README.md b/README.md index a31ddba..4aba7df 100644 --- a/README.md +++ b/README.md @@ -35,12 +35,21 @@ gitea.sh wiki-put / # 自動判斷新建或更新 gitea.sh wiki-url / # 印出 wiki 頁絕對網址（取自 API 的 html_url）；跨存取庫連結用 gitea.sh pr-create / <body-file> gitea.sh pr-status <owner>/<repo> <pr-index> # 印出 {state} {merged} {mergeable} -gitea.sh pr-comments <owner>/<repo> <pr-index> # 所有留言（issue／審查／行內），依時間排序 +gitea.sh pr-comments <owner>/<repo> <pr-index> # 印出所有留言（issue 留言、審查評語、行內留言），依時間排序 +gitea.sh pr-depend <owner>/<repo> <pr-index> <dep-owner>/<dep-repo> <dep-index> + # 把 PR 掛上前置 PR 依賴；依賴未關閉前 Gitea 會阻擋合併 +gitea.sh repo-set <owner>/<repo> <description> [website] # 設定 repo 描述與網頁 gitea.sh api <METHOD> <path> [json-file] hash-id <text> # 與 gitea.sh hash-id 相同 +repo-sync.sh <owner>/<repo> [target-dir] # 同步單一存取庫；印出 cloned、updated、dirty {分支} 或 failed {原因} + # 基準分支的優先序只在這支腳本裡；dirty 會把解析好的分支帶出來當 PR 的 base check-wiki-rules.sh # 驗證 wiki repo 解析與 hash fallback 規則 ``` +## 參考資料 + +- `references/wiki-links.md`：寫 wiki 頁才需要的連結規則。同類型用 `[[顯示文字|頁名]]`（顯示文字在左），跨類型用 `wiki-url` 給的絕對網址。 + ## Skills 目錄 呼叫方式：Claude / Antigravity `/jsc-gitea:{name}`；Codex `${name}`；Copilot / Kiro 描述需求自動觸發。 @@ -49,11 +58,11 @@ check-wiki-rules.sh # 驗證 wiki repo 解析與 ha ### `wiki` -Gitea wiki 頁讀寫的統一入口：依頁面類型（QUESTION / PLAN / ANALYZE / DELIVER / MAINTAIN / REPO / LOG / LEARN / ERROR）解析 wiki 所在的 `{owner}/{repo}`，先讀對應的 `JSC_WIKI_REPO_{TYPE}`，再退回 `JSC_WIKI_REPO`，不同類型不可互相代用。頁面內容以圖表優先（mermaid 圖、markdown 表格），純文字為最後手段。 +Gitea wiki 頁讀寫的統一入口：依頁面類型（QUESTION / PLAN / ANALYZE / DELIVER / MAINTAIN / REPO / LOG / LEARN / ERROR）解析 wiki 所在的 `{owner}/{repo}`，先讀對應的 `JSC_WIKI_REPO_{TYPE}`，再退回 `JSC_WIKI_REPO`，不同類型不可互相代用。頁面內容以圖表優先（mermaid 圖、markdown 表格），純文字每節最多三句。 ### `repo-sync` -存取庫批次同步：列出 owner → 使用者選擇 → 逐 repo（sub agent）clone 或切 develop/master 更新；有變更就開分支 commit、push、PR。 +存取庫批次同步：列出 owner → 使用者選擇 → 逐 repo（sub agent）呼叫 `tools/repo-sync.sh` clone 或更新；回報 `dirty {分支}` 的存取庫交給 `jsc-git:pr`，base 直接用腳本帶出來的那個分支。 <!-- JSC-SKILLS:END --> diff --git a/references/wiki-links.md b/references/wiki-links.md new file mode 100644 index 0000000..4b9d57c --- /dev/null +++ b/references/wiki-links.md @@ -0,0 +1,24 @@ +# Wiki 頁之間的連結 + +寫 wiki 頁才需要這份規則。兩條規則任一條寫錯，連結會指向一個不存在的頁，畫面上看不出異常。 + +## 方向：顯示文字在左，頁名在右 + +Gitea 採 GitHub／Gollum 慣例：`[[顯示文字|頁名]]`。方向與 MediaWiki 相反。Gitea 原始碼（`modules/markup/html_link.go`）寫得很清楚： + +> MediaWiki uses [[link|text]], while GitHub uses [[text|link]] … we prefer GitHub syntax + +所以 `[[PLAN_H1234567|我的計畫]]` 會顯示成文字 `PLAN_H1234567`，連到一個叫「我的計畫」的頁——這是壞連結。要寫 `[[我的計畫|PLAN_H1234567]]`。 + +顯示文字與頁名相同時，用不帶豎線的 `[[PLAN_H1234567]]`，這種寫法不會寫錯。 + +## 範圍：`[[...]]` 只在同一個 wiki 內解析 + +`[[...]]` 與 markdown 相對連結都只在目前這個 wiki 內解析。跨存取庫沒有 wiki 連結語法。 + +| 連結 | 同一個 wiki？ | 寫法 | +| --- | --- | --- | +| 同頁面類型（例：`PLAN_CONTENTS` → `PLAN_{HASH}`） | 一定同一個：一個類型一個存取庫 | `[[顯示文字\|頁名]]` 或 `[[頁名]]` | +| 不同頁面類型（例：`LOG_{HASH}` → `PLAN_{HASH}`） | **只有兩個類型解析到同一個存取庫時才同一個** | `wiki-url` 給的絕對網址：`[顯示文字](https://…/wiki/PLAN_…)` | + +每個類型各自解析自己的 `JSC_WIKI_REPO_{TYPE}`，所以跨類型連結**一律**用絕對網址：兩個類型剛好同存取庫也照樣正確，不必分兩種寫法。網址一律取自 `tools/gitea.sh wiki-url`，不要自己組路徑。