Merge pull request '發佈 jsc-gitea 0.0.8：新增 wiki-url 子指令與連結規範' (#14) from develop into master

Reviewed-on: #14
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-gitea",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "Gitea API 工具、Wiki 讀寫與存取庫批次同步",
   "skills": "./skills",
   "author": {

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-gitea",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "Gitea API 工具、Wiki 讀寫與存取庫批次同步",
   "skills": "./skills"
 }

README.md

@@ -32,6 +32,7 @@ gitea.sh wiki-repo <TYPE>                        # 解析頁面類型的 wiki
 gitea.sh wiki-list <owner>/<repo>
 gitea.sh wiki-get <owner>/<repo> <page>          # 不存在 exit 4
 gitea.sh wiki-put <owner>/<repo> <page> <file>   # 自動判斷新建或更新
+gitea.sh wiki-url <owner>/<repo> <page>          # 印出 wiki 頁絕對網址（取自 API 的 html_url）；跨存取庫連結用
 gitea.sh pr-create <owner>/<repo> <head> <base> <title> <body-file>
 gitea.sh api <METHOD> <path> [json-file]
 hash-id <text>                                   # 與 gitea.sh hash-id 相同

plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-gitea",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "Gitea API 工具、Wiki 讀寫與存取庫批次同步",
   "skills": "./skills/"
 }

skills/wiki/SKILL.md

@@ -22,6 +22,22 @@ Different page types can live in different `{owner}/{repo}` repos, classified by
 | list pages | `tools/gitea.sh wiki-list {owner}/{repo}` |
 | read page | `tools/gitea.sh wiki-get {owner}/{repo} {page}` (exit 4 when missing) |
 | write page | write the content to a temp file first, then `tools/gitea.sh wiki-put {owner}/{repo} {page} {file}` (creates or updates automatically) |
+| page URL | `tools/gitea.sh wiki-url {owner}/{repo} {page}` — the page's absolute URL, taken from the API's `html_url` (exit 4 when the page is missing) |
+
+## Linking between wiki pages
+
+Two rules, and getting either wrong produces a link that silently points at a page that does not exist.
+
+**Direction**: Gitea uses the GitHub/Gollum convention — `[[display text|page name]]`, **display text on the LEFT, page name on the RIGHT**. This is the opposite of MediaWiki. Gitea's own source says so (`modules/markup/html_link.go`): *"MediaWiki uses [[link|text]], while GitHub uses [[text|link]] … we prefer GitHub syntax"*. So `[[PLAN_H1234567|我的計畫]]` renders as the text `PLAN_H1234567` linking to a page named 我的計畫 — broken. Write `[[我的計畫|PLAN_H1234567]]`. When display text and page name are the same, use the no-pipe form `[[PLAN_H1234567]]`, which cannot be got wrong.
+
+**Scope**: `[[...]]` and relative markdown links both resolve **only inside the current wiki**. There is no cross-repo wiki-link syntax.
+
+| Link | Same wiki? | Use |
+| --- | --- | --- |
+| Same page type (e.g. `PLAN_CONTENTS` → `PLAN_{HASH}`) | Always — one type, one repo | `[[display\|page]]` or `[[page]]` |
+| Different page type (e.g. `LOG_{HASH}` → `PLAN_{HASH}`) | **Only when both types resolve to the same repo** | Absolute URL from `wiki-url`: `[display](https://…/wiki/PLAN_…)` |
+
+Because each type resolves its own `JSC_WIKI_REPO_{TYPE}`, a cross-type link **must** use the absolute URL — it stays correct whether or not the two types happen to share a repo, so never branch on that. Get the URL from `wiki-url`, never hand-assemble the path.
 
 ## Rules
 

tools/gitea.sh

@@ -138,6 +138,22 @@ import json,sys,base64
 d=json.load(sys.stdin)
 sys.stdout.write(base64.b64decode(d.get("content_base64","")).decode("utf-8"))
 ' ;;
+  wiki-url)
+    # 印出 wiki 頁的絕對網址，取自 API 回應的 html_url，不自行組路徑。
+    # 跨存取庫連結（例如 LOG 頁連到 PLAN 頁，而兩者的 JSC_WIKI_REPO_{TYPE} 不同）
+    # 只有絕對網址會通：[[頁名]] 與 markdown 相對連結都只在同一個 wiki 內解析。
+    or="${1:?owner/repo required}"; page="${2:?page required}"
+    if ! out=$(req GET "/repos/$or/wiki/page/$page" 2>/dev/null); then
+      echo "wiki page not found: $page" >&2; exit 4
+    fi
+    url=$(printf '%s' "$out" | python3 -c '
+import json,sys
+sys.stdout.write(json.load(sys.stdin).get("html_url") or "")
+')
+    if [ -z "$url" ]; then
+      echo "wiki page has no html_url: $page" >&2; exit 5
+    fi
+    printf '%s\n' "$url" ;;
   wiki-put)
     or="${1:?owner/repo required}"; page="${2:?page required}"; file="${3:?content file required}"
     tmp=$(mktemp)