.claude-plugin/plugin.json

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

.codex-plugin/plugin.json

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

README.md

@@ -25,12 +25,15 @@ gitea.sh owners                                  # 列出可讀取的 owner
 gitea.sh repos <owner>                           # 列出 owner 的 repo 全名
 gitea.sh default-branch <owner>/<repo>
 gitea.sh clone-url <owner>/<repo>
-gitea.sh wiki-repo <TYPE>                        # 解析頁面類型的 wiki 位置（見環境變數）
+gitea.sh hash-id <text>                          # 產生 8 碼大寫 SHA-1；首碼 0-9/A/B/C 時改成 Hxxxxxxx
+gitea.sh wiki-repo <TYPE>                        # 解析頁面類型的 wiki 位置（TYPE = QUESTION / PLAN / ANALYZE / MAINTAIN / REPO / LOG / ERROR）
 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 pr-create <owner>/<repo> <head> <base> <title> <body-file>
 gitea.sh api <METHOD> <path> [json-file]
+hash-id <text>                                   # 與 gitea.sh hash-id 相同
+check-wiki-rules.sh                              # 驗證 wiki repo 解析與 hash fallback 規則
 ```
 
 ## Skills 目錄
@@ -41,7 +44,7 @@ gitea.sh api <METHOD> <path> [json-file]
 
 ### `wiki`
 
-Gitea wiki 頁讀寫的統一入口：依頁面類型（QUESTION / PLAN / ANALYZE / MAINTAIN / REPO / LOG）解析 wiki 所在的 `{owner}/{repo}`，未設定環境變數時以決策樹詢問。頁面內容以圖表優先（mermaid 圖、markdown 表格），純文字為最後手段。
+Gitea wiki 頁讀寫的統一入口：依頁面類型（QUESTION / PLAN / ANALYZE / MAINTAIN / REPO / LOG / ERROR）解析 wiki 所在的 `{owner}/{repo}`，先讀對應的 `JSC_WIKI_REPO_{TYPE}`，再退回 `JSC_WIKI_REPO`，不同類型不可互相代用。頁面內容以圖表優先（mermaid 圖、markdown 表格），純文字為最後手段。
 
 ### `repo-sync`
 
@@ -55,9 +58,13 @@ Gitea wiki 頁讀寫的統一入口：依頁面類型（QUESTION / PLAN / ANALYZ
 | --- | --- | --- |
 | `GITEA_HOST` | Gitea 站台（可省略 scheme，預設 https） | 詢問使用者 |
 | `GITEA_TOKEN` | Gitea API token；缺少或遇 401/403 時自動退回 tea CLI 登入 token | 詢問使用者 |
-| `JSC_WIKI_REPO_{TYPE}` | 各類型 wiki 頁的 `{owner}/{repo}`；TYPE = QUESTION / PLAN / ANALYZE / MAINTAIN / REPO / LOG | 退回 `JSC_WIKI_REPO` |
+| `JSC_WIKI_REPO_{TYPE}` | 各類型 wiki 頁的 `{owner}/{repo}`；TYPE = QUESTION / PLAN / ANALYZE / MAINTAIN / REPO / LOG / ERROR | 退回 `JSC_WIKI_REPO`，不做跨類型代用 |
 | `JSC_WIKI_REPO` | 共用預設的 wiki `{owner}/{repo}` | 詢問使用者 |
 
+## Hash 規則
+
+`{HASH}` 由 `tools/hash-id` 產生。先算 `SHA-1` 前 8 碼並轉大寫。若首碼是數字或 `A`、`B`、`C`，就改成 `H` 加上原本的前 7 碼，維持 8 碼長度。
+
 ## 相關 domain
 
 - [`jsc-ask`](https://gitea.jsc.idv.tw/plugins/ask)：wiki 位置未設定時的決策樹詢問

plugin.json

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

skills/wiki/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wiki
-description: Read or write a Gitea wiki page through tools/gitea.sh with GITEA_TOKEN. Resolve the wiki repo per page type (QUESTION/PLAN/ANALYZE/MAINTAIN/REPO/LOG) via gitea.sh wiki-repo, falling back to JSC_WIKI_REPO or a decision-tree question. Page content is chart-first - prefer mermaid diagrams and markdown tables over plain prose. Used by jsc-ask, jsc-sdlc, and jsc-log for all wiki pages; not for repo code files.
+description: Read or write a Gitea wiki page through tools/gitea.sh and tools/hash-id. Resolve the wiki repo per page type with JSC_WIKI_REPO_{TYPE} first, then JSC_WIKI_REPO, and ask only when neither is set. Page content is chart-first - prefer mermaid diagrams and markdown tables over plain prose. Used by jsc-ask, jsc-sdlc, and jsc-log for wiki pages, including ERROR pages, not for repo code files.
 ---
 
 # wiki — read and write Gitea wiki pages
@@ -9,10 +9,11 @@ Every wiki operation in the jsc skill set goes through this skill. One entry poi
 
 ## Resolve the wiki location
 
-Different page types can live in different `{owner}/{repo}` repos, classified by page-name prefix: `QUESTION`, `PLAN`, `ANALYZE`, `MAINTAIN`, `REPO`, `LOG`.
+Different page types can live in different `{owner}/{repo}` repos, classified by page-name prefix: `QUESTION`, `PLAN`, `ANALYZE`, `MAINTAIN`, `REPO`, `LOG`, `ERROR`.
 
-1. Run `tools/gitea.sh wiki-repo {TYPE}` (TYPE = the page-name prefix). Resolution order: `JSC_WIKI_REPO_{TYPE}` > `JSC_WIKI_REPO`. When either is set, use it and skip the question.
+1. Before asking the user, inspect the current shell environment for the needed repo variables and Gitea connection variables: `JSC_WIKI_REPO_{TYPE}`, `JSC_WIKI_REPO`, `GITEA_HOST`, and `GITEA_TOKEN`. Use inherited shell values first; only ask when the needed repo cannot be resolved after that check.
-2. On exit 3 (neither is set), ask the user for that page type's `{owner}/{repo}` per the `jsc-ask:ask` rules, and suggest setting `JSC_WIKI_REPO_{TYPE}` (can differ per type) or `JSC_WIKI_REPO` (shared default).
+2. Run `tools/gitea.sh wiki-repo {TYPE}` (TYPE = the page-name prefix). Allowed types are `QUESTION`, `PLAN`, `ANALYZE`, `MAINTAIN`, `REPO`, `LOG`, and `ERROR`. Resolution order is `JSC_WIKI_REPO_{TYPE}` first, then `JSC_WIKI_REPO`. Never borrow another type's repo.
+3. On exit 3 (neither is set after env inspection), ask the user for that page type's `{owner}/{repo}` per the `jsc-ask:ask` rules, and suggest setting `JSC_WIKI_REPO_{TYPE}` (can differ per type) or `JSC_WIKI_REPO` (shared default).
 
 ## Operations
 
@@ -25,7 +26,8 @@ Different page types can live in different `{owner}/{repo}` repos, classified by
 ## Rules
 
 1. Page names must follow the wiki naming table in the skill guidelines (see `jsc-meta/references/guidelines.md`).
-2. To update a contents page (`*_CONTENTS`): `wiki-get` it first, apply the template to append or modify, then `wiki-put` the whole page back. Never overwrite entries owned by others.
+2. Use `tools/hash-id` for `{HASH}` values. It returns the first 8 uppercase SHA-1 hex chars, or `H` plus the first 7 chars when the raw hash starts with `0-9`, `A`, `B`, or `C`.
-3. Write all wiki content in UTF-8 Traditional Chinese, per the STE100 output rule.
+3. To update a contents page (`*_CONTENTS`): `wiki-get` it first, apply the template to append or modify, then `wiki-put` the whole page back. Never overwrite entries owned by others.
-4. Prefer visual forms for page content: use mermaid diagrams (flowchart, sequence, gantt, pie) and markdown tables wherever the information allows. Plain running text is the last resort, kept short.
+4. Write all wiki content in UTF-8 Traditional Chinese, per the STE100 output rule.
-5. Authentication fallback is built into `tools/gitea.sh`: on a missing GITEA_TOKEN or a 401/403 response it retries with the tea CLI login token automatically, so only report an auth failure when both paths fail.
+5. Prefer visual forms for page content: use mermaid diagrams (flowchart, sequence, gantt, pie) and markdown tables wherever the information allows. Plain running text is the last resort, kept short.
+6. Authentication fallback is built into `tools/gitea.sh`: on a missing GITEA_TOKEN or a 401/403 response it retries with the tea CLI login token automatically, so only report an auth failure when both paths fail.

tools/check-wiki-rules.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env sh
+# check-wiki-rules — 驗證 wiki repo 解析與 hash-id 規則。
+set -eu
+
+dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+gitea="$dir/gitea.sh"
+hash_id="$dir/hash-id"
+
+fail() {
+  printf '%s\n' "$1" >&2
+  exit 1
+}
+
+expect_eq() {
+  got=$1
+  want=$2
+  label=$3
+  [ "$got" = "$want" ] || fail "$label: want=$want got=$got"
+}
+
+check_repo() {
+  type=$1
+  label=$2
+  want=$3
+  shift 3
+  got=$(env -i PATH="${PATH:-/usr/bin:/bin}" "$@" "$gitea" wiki-repo "$type")
+  expect_eq "$got" "$want" "$label"
+}
+
+check_hash() {
+  input=$1
+  want=$2
+  got=$("$hash_id" "$input")
+  expect_eq "$got" "$want" "hash-id $input"
+}
+
+check_repo REPO 'REPO specific wins' 'records/REPO' \
+  JSC_WIKI_REPO_REPO='records/REPO' \
+  JSC_WIKI_REPO_ANALYZE='knowledges/ANALYZE' \
+  JSC_WIKI_REPO='shared/wiki'
+
+check_repo REPO 'REPO falls back to shared only' 'shared/wiki' \
+  JSC_WIKI_REPO_ANALYZE='knowledges/ANALYZE' \
+  JSC_WIKI_REPO='shared/wiki'
+
+check_repo ANALYZE 'ANALYZE specific wins' 'knowledges/ANALYZE' \
+  JSC_WIKI_REPO_REPO='records/REPO' \
+  JSC_WIKI_REPO_ANALYZE='knowledges/ANALYZE' \
+  JSC_WIKI_REPO='shared/wiki'
+
+check_repo ANALYZE 'ANALYZE falls back to shared only' 'shared/wiki' \
+  JSC_WIKI_REPO_REPO='records/REPO' \
+  JSC_WIKI_REPO='shared/wiki'
+
+check_repo ERROR 'ERROR uses its own repo' 'errors/wiki' \
+  JSC_WIKI_REPO_ERROR='errors/wiki' \
+  JSC_WIKI_REPO='shared/wiki'
+
+check_hash 'case-2' 'H5172CB7'
+check_hash 'case-11' 'HA9A6662'
+check_hash 'case-1' 'HB6EC7FD'
+check_hash 'case-12' 'HCCA8D42'
+
+printf '%s\n' 'OK'

tools/gitea.sh

@@ -5,9 +5,10 @@
 #   gitea.sh repos <owner>                           # 列出 owner 底下可讀取的 repo（全名）
 #   gitea.sh default-branch <owner>/<repo>           # 印出預設分支
 #   gitea.sh clone-url <owner>/<repo>                # 印出 clone URL
+#   gitea.sh hash-id <text>                          # 產生 8 碼大寫 SHA-1 hash；首碼為 0-9/A/B/C 時改成 Hxxxxxxx
 #   gitea.sh wiki-repo <TYPE>                        # 解析頁面類型的 wiki 位置：
-#       TYPE = QUESTION|PLAN|ANALYZE|MAINTAIN|REPO|LOG（即頁名前綴）
+#       TYPE = QUESTION|PLAN|ANALYZE|MAINTAIN|REPO|LOG|ERROR（即頁名前綴）
-#       依序取 JSC_WIKI_REPO_{TYPE} > JSC_WIKI_REPO；都未設定 exit 3（呼叫端須詢問使用者）
+#       依序取 JSC_WIKI_REPO_{TYPE} > JSC_WIKI_REPO；不得跨類型代用；都未設定 exit 3
 #   gitea.sh wiki-list <owner>/<repo>                # 列出 wiki 頁名
 #   gitea.sh wiki-get <owner>/<repo> <page>          # 印出 wiki 頁 markdown；不存在時 exit 4
 #   gitea.sh wiki-put <owner>/<repo> <page> <file>   # 建立或更新 wiki 頁（內容取自檔案）
@@ -21,6 +22,30 @@
 #   （~/.config/tea/config.yml，優先取 default: true 的登入）；兩者皆無才失敗。
 set -eu
 
+script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+
+resolve_wiki_repo() { # TYPE -> JSC_WIKI_REPO_{TYPE} -> JSC_WIKI_REPO
+  type=$(printf '%s' "${1:?TYPE required}" | tr a-z A-Z)
+  case "$type" in
+    QUESTION|PLAN|ANALYZE|MAINTAIN|REPO|LOG|ERROR) ;;
+    *) echo "unknown wiki type: $type" >&2; exit 2 ;;
+  esac
+  eval "v=\${JSC_WIKI_REPO_${type}:-}"
+  [ -n "$v" ] || v="${JSC_WIKI_REPO:-}"
+  if [ -n "$v" ]; then printf '%s\n' "$v"; else
+    echo "no wiki repo configured for $type (set JSC_WIKI_REPO_$type or JSC_WIKI_REPO)" >&2; exit 3
+  fi
+}
+
+cmd="${1:?usage: gitea.sh <command> ...}"; shift
+case "$cmd" in
+  hash-id)
+    exec "$script_dir/hash-id" "$@" ;;
+  wiki-repo)
+    resolve_wiki_repo "${1-}"
+    exit 0 ;;
+esac
+
 tea_token() { # 取 tea CLI 設定檔的 token（優先 default: true 的登入，否則第一個）
   cfg="${HOME}/.config/tea/config.yml"
   [ -f "$cfg" ] || return 1
@@ -78,7 +103,6 @@ for i in items:
 ' "$1"
 }
 
-cmd="${1:?usage: gitea.sh <command> ...}"; shift
 case "$cmd" in
   owners)
     { req GET "/user" | json_field login
@@ -101,13 +125,6 @@ case "$cmd" in
   clone-url)
     or="${1:?owner/repo required}"
     req GET "/repos/$or" | json_field clone_url ;;
-  wiki-repo)
-    type=$(printf '%s' "${1:?TYPE required}" | tr a-z A-Z)
-    eval "v=\${JSC_WIKI_REPO_$type:-}"
-    [ -n "$v" ] || v="${JSC_WIKI_REPO:-}"
-    if [ -n "$v" ]; then printf '%s\n' "$v"; else
-      echo "no wiki repo configured for $type (set JSC_WIKI_REPO_$type or JSC_WIKI_REPO)" >&2; exit 3
-    fi ;;
   wiki-list)
     or="${1:?owner/repo required}"
     req GET "/repos/$or/wiki/pages?limit=200" | json_field title ;;

tools/hash-id

@@ -0,0 +1,34 @@
+#!/usr/bin/env sh
+# hash-id — 產生 8 碼大寫 SHA-1 hash。
+# 用法:
+#   hash-id <text>
+#   printf '%s' <text> | hash-id
+# 規則:
+#   先取 SHA-1 前 8 碼大寫。
+#   若首碼為 0-9、A、B、C，改成 H 加上原 SHA-1 前 7 碼。
+set -eu
+
+input=''
+if [ "$#" -gt 0 ]; then
+  input=$*
+elif [ -t 0 ]; then
+  input=''
+else
+  input=$(cat)
+fi
+
+if command -v sha1sum >/dev/null 2>&1; then
+  raw=$(printf '%s' "$input" | sha1sum | awk '{print $1}')
+elif command -v shasum >/dev/null 2>&1; then
+  raw=$(printf '%s' "$input" | shasum -a 1 | awk '{print $1}')
+else
+  echo 'no SHA-1 helper found' >&2
+  exit 1
+fi
+
+hash=$(printf '%s' "$raw" | cut -c1-8 | tr a-f A-F)
+case "$hash" in
+  [0-9ABC]*) hash="H$(printf '%s' "$hash" | cut -c1-7)" ;;
+esac
+
+printf '%s\n' "$hash"