From 73cca6e6eaff01f80614ea601c3e77f4ed6109a0 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 27 Aug 2026 11:20:27 +0800 Subject: [PATCH] =?UTF-8?q?docs(gitea):=20README=20=E8=88=87=20AGENTS=20?= =?UTF-8?q?=E8=A3=9C=E4=B8=8A=E7=9B=AF=20PR=20=E8=88=87=20PR=20=E6=A0=A1?= =?UTF-8?q?=E6=BA=96=E7=9A=84=E7=94=A8=E6=B3=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：README 的指令清單補上 `pr-get`、`pr-edit` 與 `pr-watch.sh` 三項與各自的退出碼，環境變數表補 `JSC_HOME` 與 `JSC_PR_WATCH_INTERVAL`；AGENTS.md 新增一條規則，盯 PR 等合併一律用 `tools/pr-watch.sh`，不要自己寫輪詢迴圈。 Why：新指令沒寫進 README，呼叫端就只能翻腳本原始碼。`pr-watch.sh` 的退出碼 `10` 更要講清楚：它不是錯誤，是「有新留言，換你處理」的交棒訊號，看成錯誤就會把留言吞掉。 How：README 依既有版面把三項排進指令區塊，另補一段說明退出碼 `10` 的設計意圖。AGENTS.md 把新規則插進第 5 條，原第 5 條順延為第 6 條。 Who：讀 `jsc-gitea` 說明的人，以及依 AGENTS.md 行事的代理。 --- AGENTS.md | 3 ++- README.md | 12 ++++++++++++ 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 7538fce..829108d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,8 @@ 2. 技能位於 `skills/{name}/SKILL.md`；處理任務前先比對需求與各技能的 `description`，相符就載入並依其步驟執行。 3. 技能準則的唯一來源：`plugins/meta` 存取庫的 `references/guidelines.md`。 4. 所有 hook 只放在 `jsc-hooks`；gitea 操作一律經由 `jsc-gitea` 的 `tools/gitea.sh`；問使用者一律依 `jsc-ask:ask` 的決策樹規則。 -5. 主 agent 不需要處理細節的流程，一律建立 sub agent 處理。 +5. 盯 PR 等合併用 `tools/pr-watch.sh`，不要自己寫輪詢迴圈。它回 10 就代表有新留言，把留言接回決策樹處理完，再重新盯一次。 +6. 主 agent 不需要處理細節的流程，一律建立 sub agent 處理。 ## 呼叫慣例 diff --git a/README.md b/README.md index 8e68ee6..9ad8065 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,10 @@ 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-get <owner>/<repo> <pr-index> # 印出 PR 的標題、base 分支與描述，供呼叫端比對有沒有差 + # 前三行固定 title、base、body 三個標記，第 4 行起是描述原文 +gitea.sh pr-edit <owner>/<repo> <pr-index> <title> <body-file> + # 更新 PR 的標題與描述；描述從檔案讀，裝得下多行 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 會阻擋合併 @@ -45,8 +49,14 @@ 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 規則 +pr-watch.sh <owner>/<repo> <pr-index> [state-file] + # 盯著一支 PR，直到它合併或關閉，不自動逾時退場 + # 退出碼 0 = 已合併或關閉、10 = 有新留言要接手、2 = 參數錯誤、3 = 查不到該 PR + # 已回報過的留言記在狀態檔，預設 $JSC_HOME/pr-watch/{owner}-{repo}-{index}.seen ``` +`pr-watch.sh` 的退出碼 10 是設計重點：腳本只負責偵測，決策交回呼叫端。收到 10 就把印出來的留言丟進決策樹，處理完再重新盯一次。 + 議題與 HTML 產出： ``` @@ -123,6 +133,8 @@ Gitea wiki 頁讀寫的統一入口：依頁面類型（QUESTION / PLAN / ANALYZ | `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 | 退回 `JSC_WIKI_REPO`，不做跨類型代用 | | `JSC_WIKI_REPO` | 共用預設的 wiki `{owner}/{repo}` | 詢問使用者 | +| `JSC_HOME` | `pr-watch.sh` 狀態檔的根目錄 | 預設 `~/.jsc` | +| `JSC_PR_WATCH_INTERVAL` | `pr-watch.sh` 的輪詢間隔秒數（正整數） | 預設 60 | ## Hash 規則