plugins/gitea
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(gitea): 更正過期說明並補齊指令用法

Browse Source 
說明文件有兩處與現況不符。雜湊規則在這裡複述了一份，跟唯一來源各說各
話，讀的人會照著舊的做；技能組異動報告的雜湊來源早就改過，敘述卻留在
原地。現在改成指向唯一來源，並刪掉重複的那一份。

新增的指令、頁面類型與全腳本共用的結束碼也一併寫進說明。查不到就只能
翻程式，那正是說明文件該擋下來的成本。domain 簡介補上議題轉換與 HTML
匯出，與實際提供的技能一致。
This commit is contained in:
jiantw83
2026-08-31 11:12:20 +08:00
parent 2b759542a8
commit 8da586c481
2 changed files with 22 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+21 -5
View File
@@ -28,7 +28,7 @@ gitea.sh repos <owner> # 列出 owner 的 repo 全名
gitea.sh default-branch <owner>/<repo>
gitea.sh clone-url <owner>/<repo>
gitea.sh hash-id <text> # 產生 8 碼大寫 SHA-1；首碼 0-9/A/B/C 時改成 Hxxxxxxx
gitea.sh wiki-repo <TYPE> # 解析頁面類型的 wiki 位置（TYPE = QUESTION / PLAN / ANALYZE / DELIVER / MAINTAIN / REPO / LOG / LEARN / ERROR / CHECK / REPORT / SKILLSET）
gitea.sh wiki-repo <TYPE> # 解析頁面類型的 wiki 位置（TYPE = QUESTION / PLAN / ANALYZE / DELIVER / MAINTAIN / REPO / LOG / LEARN / ERROR / CHECK / REPORT / SKILLSET / TOOLING）
gitea.sh wiki-list <owner>/<repo>
gitea.sh wiki-get <owner>/<repo> <page> # 不存在 exit 4
gitea.sh wiki-put <owner>/<repo> <page> <file> # 自動判斷新建或更新；會先要求確認
@@ -37,6 +37,10 @@ gitea.sh pr-create <owner>/<repo> <head> <base> <title> <body-file> # 會先要
gitea.sh pr-status <owner>/<repo> <pr-index> # 印出 {state} {merged} {mergeable}
gitea.sh pr-get <owner>/<repo> <pr-index> # 印出 PR 的標題、base 分支與描述，供呼叫端比對有沒有差
# 前三行固定 title、base、body 三個標記，第 4 行起是描述原文
gitea.sh pr-of-branch <owner>/<repo> <branch> # 印出該分支目前開啟中的 PR（比對 head.ref）
# 第 1 行 number，接著 title、base、body 三個標記，第 5 行起是描述原文
# 結束碼 0=找到、2=用法錯誤、3=該分支沒有開啟中的 PR、4=API 失敗
# 「沒有 PR」用 3 不用 4：混用會把金鑰失效讀成沒開過 PR，接著開出重複的 PR
gitea.sh pr-edit <owner>/<repo> <pr-index> <title> <body-file> # 會先要求確認
# 更新 PR 的標題與描述；描述從檔案讀，裝得下多行
gitea.sh pr-comments <owner>/<repo> <pr-index> # 印出所有留言（issue 留言、審查評語、行內留言），第三欄帶 #id，依時間排序
@@ -47,6 +51,11 @@ gitea.sh pr-depend <owner>/<repo> <pr-index> <dep-owner>/<dep-repo> <dep-index>
gitea.sh repo-set <owner>/<repo> <description> [website] # 會先要求確認
gitea.sh markdown <file> # markdown 檔渲染成 HTML 片段（走 /markdown/raw）
gitea.sh api <METHOD> <path> [json-file]
# 全腳本共用結束碼: 0=成功、1=api 子命令請求失敗、2=用法錯誤
# 3=wiki-repo 沒設定或 pr-of-branch 查無 PR、4=找不到（404）與 PR 系列 API 失敗
# 5=wiki 頁沒有 html_url、7=金鑰失效或權限不足（401/403）、8=其他 API 失敗
# 7 與 8 一定要跟 4 分開：認證失敗若被讀成「頁面不存在」，
# 附加寫入就會變成整頁覆蓋，舊紀錄直接消失
hash-id <text> # 與 gitea.sh hash-id 相同
repo-sync.sh <owner>/<repo> [target-dir] # 同步單一存取庫；印出 cloned、updated、dirty {分支} 或 failed {原因}
# 基準分支的優先序只在這支腳本裡；dirty 會把解析好的分支帶出來當 PR 的 base
@@ -65,8 +74,14 @@ pr-watch.sh <owner>/<repo> <pr-index> [state-file]
gitea-link.sh parse <url> # 解析 wiki 或議題連結；不是這兩種就 exit 3（呼叫端據此中止）
issue.sh labels|label-ids|projects <owner>/<repo>
issue.sh title|body|labels-of <owner>/<repo> <index>
issue.sh show <owner>/<repo> <index> # 一次拿齊標題、標籤與正文，只打一次 API
# 四段固定格式：title、labels、body 標記，第 4 行起是正文
issue.sh create <owner>/<repo> <title> <body-file> [--labels <ids>] [--milestone <id>] # 會先要求確認
html-style.sh get|set|unset|list|layouts|styles # 種類對版型與風格的設定
html-style.sh key wiki <頁名> # 推導種類：取第一個底線前的字首
html-style.sh key issue <owner>/<repo> <編號> [--labels <名稱>[,<名稱>]]
# 推導種類：依序試每個標籤，第一個設定過的勝出，都沒有就回 ISSUE:DEFAULT
# 輸出一行「{種類}<TAB>{依據}」；結束碼 1=取不到標籤
html-render.sh --markdown <檔案> --title <標題> --out <輸出檔> [--layout] [--style] [--subtitle] [--source-url]
```
@@ -107,11 +122,11 @@ html-render.sh --markdown <檔案> --title <標題> --out <輸出檔> [--layout]
### `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 / CHECK / REPORT / SKILLSET / TOOLING）解析 wiki 所在的 `{owner}/{repo}`，先讀對應的 `JSC_WIKI_REPO_{TYPE}`，再退回 `JSC_WIKI_REPO`，不同類型不可互相代用。頁面內容以圖表優先（mermaid 圖、markdown 表格），純文字每節最多三句。
### `repo-sync`
存取庫批次同步：列出 owner → 使用者選擇 → 逐 repo（sub agent）呼叫 `tools/repo-sync.sh` clone 或更新；回報 `dirty {分支}` 的存取庫交給 `jsc-git:pr`，base 直接用腳本帶出來的那個分支；PR 依 `jsc-meta/references/pr-report.md` 集中成表。
存取庫批次同步：列出 owner → 使用者選擇 → 各存取庫併行（一個 repo 一個 sub agent）呼叫 `tools/repo-sync.sh` clone 或更新；回報 `dirty {分支}` 的存取庫交給 `jsc-git:pr`，base 直接用腳本帶出來的那個分支；PR 依 `jsc-meta/references/pr-report.md` 集中成表。
### `html-export`
@@ -134,14 +149,15 @@ 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 / DELIVER / MAINTAIN / REPO / LOG / LEARN / ERROR / CHECK / REPORT | 退回 `JSC_WIKI_REPO`，不做跨類型代用 |
| `JSC_WIKI_REPO_SKILLSET` | `SKILLSET_CONTENTS`、`SKILLSET_{HASH}`（技能組異動報告）的 `{owner}/{repo}`；雜湊來源為 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO`，不做跨類型代用 |
| `JSC_WIKI_REPO_SKILLSET` | `SKILLSET_CONTENTS`、`SKILLSET_{HASH}`（技能組異動報告）的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO`，不做跨類型代用 |
| `JSC_WIKI_REPO_TOOLING` | `TOOLING_CONTENTS`、`TOOLING_{HASH}`（技能盤點）的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO`，不做跨類型代用 |
| `JSC_WIKI_REPO` | 共用預設的 wiki `{owner}/{repo}` | 詢問使用者 |
| `JSC_HOME` | `pr-watch.sh` 狀態檔的根目錄 | 預設 `~/.jsc` |
| `JSC_PR_WATCH_INTERVAL` | `pr-watch.sh` 的輪詢間隔秒數（正整數） | 預設 60 |
## Hash 規則
`{HASH}` 由 `tools/hash-id` 產生。先算 `SHA-1` 前 8 碼並轉大寫。若首碼是數字或 `A`、`B`、`C`，就改成 `H` 加上原本的前 7 碼，維持 8 碼長度。
`{HASH}` 一律由 `tools/hash-id` 產生。長度、大小寫、`H` 前綴與各頁型的雜湊來源，唯一來源是 `jsc-meta` 的 [`references/guidelines.md`](https://gitea.jsc.idv.tw/plugins/meta/src/branch/master/references/guidelines.md)「Wiki 頁命名總表」，這裡不再複述一份。
## 相關 domain