fix(role): sub agent 等非對話情境跳過單一載入鎖

單一載入鎖的目的是避免「使用者同時與兩個相同人格對話」,但實作把所有 SessionStart
一視同仁,導致一個本該成立的情境失效:使用者正在別的視窗跟某角色聊天時,
另一個角色就不能派該角色當 sub agent 幫忙 —— 實測確認會被自己的鎖擋下。

- role_lib.sh 新增 role_skip_instance_lock(),由 ROLE_SKIP_INSTANCE_LOCK 控制
- role_instance_acquire 在該情境放行且**不寫鎖**,不會搶走互動式對話持有的名額
- role skill 補說明:sub agent 情境應設 ROLE_SKIP_INSTANCE_LOCK=1,並說明理由

驗證:模擬「使用者視窗持有鎖 → sub agent 要求載入」,未設定時被擋、
設定後正常載入角色人格且鎖仍由使用者視窗持有。

版號 0.0.4 → 0.0.5(依 master 現行版本 0.0.4 計算,非累加)

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jeffery
2026-07-29 10:52:41 +08:00
co-authored by Claude Opus 5
parent b36fb12416
commit fa62d1fce2
5 changed files with 22 additions and 4 deletions
+5 -1
View File
@@ -119,6 +119,7 @@ ROLE_DIR="<skill base directory>/../../scripts/role" # 其他助理
| `ROLE_BRIEF_LIMIT` | | 所有檢查腳本輸出合計的字元上限 | `2000` |
| `ROLE_SINGLE_INSTANCE` | | 單一載入實例限制:同一角色同時只被一個工作階段載入。設 `0` 可停用 | `1` |
| `ROLE_INSTANCE_IDLE_MINUTES` | | 前一個工作階段的 transcript 閒置多久後自動釋放角色鎖 | `30` |
| `ROLE_SKIP_INSTANCE_LOCK` | | 設 `1` 時跳過單一載入鎖且**不寫鎖**,供 sub agent 等非對話情境使用 | `0` |
| `ROLE_SCOPE` | | 冒號分隔的路徑前綴,僅這些路徑下的 session 載入/記錄 | 全部 session |
| `ROLE_ERRLOG` | | 錯誤訊息額外寫入的檔案路徑 | 只走 stderr |
@@ -296,12 +297,15 @@ Stop hook 只做「編碼前處理」,輸出粗分類、summary、tags、prior
| 持有者的 transcript 已刪除 | 自動接手 |
| 持有者閒置超過 `ROLE_INSTANCE_IDLE_MINUTES` | 自動接手 |
| hook 未提供 transcript 路徑 | **一律放行且不寫鎖** |
| `ROLE_SKIP_INSTANCE_LOCK=1` | **一律放行且不寫鎖**(sub agent 等非對話情境) |
判斷依據是**持有者 transcript 檔的 mtime**,而非 pid —— SessionStart hook 無法可靠取得 CLI 主行程 pid,也沒有保證會觸發的 SessionEnd hook 可用來釋放鎖;活躍的工作階段會持續寫入 transcript,因此「多久沒被寫入」最貼近真實狀態且不需要清理程序。
**設計原則是寧可誤放行也不要誤鎖** —— 誤鎖會讓使用者叫不出角色,比偶爾重複載入嚴重得多。因此無法識別工作階段時一律放行。
> sub agent 是否受此限制,取決於該 harness 是否為 sub agent 觸發 `SessionStart` 並提供獨立的 transcript 路徑;若未觸發 hook,則不受限制
**sub agent 不該受此限制**:鎖的目的是避免「使用者同時與兩個相同人格對話」,而被其他角色派去做事的 sub agent 並不是在跟使用者對話。若不放行,會讓「使用者正在別的視窗跟某角色聊天時,另一個角色就不能請他幫忙」這種本該成立的情境失效。因此 sub agent 情境請設 `ROLE_SKIP_INSTANCE_LOCK=1`:它會放行且**不寫鎖**,不會搶走互動式對話持有的名額
> 若該 harness 未為 sub agent 觸發 `SessionStart`,sub agent 本來就不受限制,設不設定都不影響。
### `--forget-preview`