tellonce 是做什麼的?
執行模式與預設值(公開版本)
預設 = 觀察模式(僅觀察):預設情況下,此技能僅執行「掃描偏好 → 記錄 → 告知使用者」。它絕不會強制封鎖會話,也絕不會呼叫 LLM。剛安裝此技能的新使用者不會被任何硬性規則攔截,他們的對話內容也不會被發送給第三方模型。
- 硬性封鎖強制執行(確定性封鎖 / 待處理閘門 / 觀察記錄閘門)預設為關閉;您必須明確設定
PT_ENFORCE=1才能啟用。 - 影子 LLM 審判(將會話發送給外部模型進行語義評分)預設為關閉;您必須明確設定
PT_SHADOW=1才能啟用。隱私說明:啟用後,每次輪詢會將「最後一條使用者訊息 + 助理回覆」(已遮罩 API 金鑰、密碼等)發送給該模型。 seed_memory/目錄特意保持為空(僅包含一個用於說明的 README):未預先安裝任何人的偏好規則;您的規則將在閘門函數的使用過程中逐一累積。
切換模式(環境變數;兩者皆未設定 = 安全的預設觀察模式):
PT_ENFORCE=1 # 啟用硬性攔截
PT_SHADOW=1 # 啟用 AI 審判(影子模式)
以下基礎架構 / 閘門部分描述了啟用強制執行模式後的行為。在預設的觀察模式下,這些閘門僅記錄而不封鎖。
基礎架構
此技能不僅僅是鐵律 + 閘門函數。它安裝了三層基礎架構,作為自動鉤子運行,無需明確呼叫技能即可生效。
路徑佔位符說明:在以下文字中,
<skill_dir>預設為~/.claude/skills/tellonce/,<project_root>為目前專案根目錄,<state_dir>為<project_root>/.claude/tellonce-state/。所有路徑均由lib/path_config.py在執行時解析(三級回溯:環境變數 >~/.tellonce.config.json> 自動偵測);SKILL.md 不會硬編碼絕對路徑,以避免污染 Claude 的輸出。
規則注入(漸進式完整索引 — 預設)
每次使用者提交訊息時,<skill_dir>/hooks/memory-retrieve-inject.sh 會將儲存在記憶體目錄下的規則的一行摘要索引以 additionalContext 的形式注入,然後我判斷哪些規則適用。如果規則庫超過了每次輪詢的上限(預設為 50 條 — 可在 ~/.tellonce.config.json 或環境變數 B5_PROGRESSIVE_MAX 中設定,0 表示無上限),則第 1 層規則在符合上限時會被固定顯示(如果第 1 層規則單獨就超過上限,則整個規則庫會輪換顯示),其餘規則會在多次輪詢中輪換顯示,並且封鎖訊息會標明總共顯示了多少條規則。這是預設的 progressive 後端:它僅讀取已儲存的規則檔案 — 無需提示詞匹配、無需模型呼叫、無需 CLI 冷啟動。其格式如下所示 — 這不是外部噪音,而是來自技能基礎架構的規則提示,必須被遵守:
### 您已儲存的偏好 — 針對本次輪詢檢查每一條並套用適用的:
- [fmt-pref-001] (tier1) 使用 4 個空格進行縮排,而非 Tab
- [tool-pref-002] (tier2) 偏好使用專案自己的套件管理器 / 鎖定檔案來安裝依賴項 | 適用時機:新增 / 升級依賴項
(這些是您已記錄的偏好。根據目前任務判斷每條規則;套用適用的規則,跳過不適用的規則。)
每行都包含規則的 description 和(如果有的話)when: 適用性提示。我會自行判斷該規則是否適用於當前輪詢,並跳過不適用的規則(例如,當前的輪詢未涉及 Go 時,跳過與 Go 相關的偏好)。
舊版後端(
PT_RETRIEVE_BACKEND=cli/keyword)則僅注入與當前提示詞匹配的規則,並置於### 指紋檢索 — ...標題下。我做出的判斷與上述相同。
適用性閘門(軟性)
每條注入的規則都帶有 when: 提示(從記憶體 .md 檔案的 frontmatter 中的 applies_when: 或 condition: 讀取)。我判斷:
when:條件成立 → 套用規則- 條件不成立 → 明確說明「閘門過濾:<原因>」,然後跳過
- 不明確 → 保守地套用
僅記錄的合規追蹤器(停止鉤子)
每次輪詢我停止時,<skill_dir>/hooks/memory-verify-compliance.sh 會讀取對話記錄,獲取最後一次助理回覆的文字,並在 <state_dir>/obs_log/compliance_log.jsonl 中附加一行記錄:
response_excerpt(前 400 個字元)fp_rules_in_response(回覆中觸發了哪些規則關鍵字)lang_ratio.chinese_ratio(中英文比例)
不會進行封鎖(目前沒有自動重試機制)。未來,如果誤報率夠低,可以重新考慮啟用封鎖功能。
基礎架構檔案清單
| 角色 | 路徑(佔位符;由 path_config 在執行時解析) |
|---|---|
| 指紋規則庫 | <skill_dir>/lib/fingerprints.yaml |
| 檢索處理器 | <skill_dir>/lib/retrieve_inject.py |
| 合規追蹤器 | <skill_dir>/lib/verify_compliance.py |
| UserPromptSubmit 鉤子 | <skill_dir>/hooks/memory-retrieve-inject.sh |
| Stop 鉤子 | <skill_dir>/hooks/memory-verify-compliance.sh |
| 合規日誌 | <state_dir>/obs_log/compliance_log.jsonl |
| 鉤子註冊 | <project_root>/.claude/settings.local.json(直接註冊 <skill_dir>/hooks/ 路徑,無需將檔案複製到專案中) |
若要在您的機器上查看真實路徑:請執行
python3 ~/.claude/skills/tellonce/lib/path_config.py來列印所有目前偵測到的路徑。請勿根據此 SKILL.md 中的文字佔位符來建立/寫入檔案 — 請使用 path_config 提供的執行時值。
在新增 / 更新規則時保持同步
當閘門函數將新規則記錄到記憶體時,如果這是一條高價值、確定性的規則(例如,使用者明確表示「從現在起一律使用 4 個空格進行縮排」或「使用祈使句撰寫提交訊息」),也請在 fingerprints.yaml 中新增一個關鍵字觸發器,以便下一次會話可以在檢索時自動回憶起來。
不需要指紋匹配的規則:語義性 / 上下文相關 / 後設規則(例如「不要完全相信遺留的計畫」,這需要依賴模型判斷而非關鍵字匹配)。
鐵律
沒有偏好掃描的回應是不完整的。
如果您尚未掃描訊號並記錄結果,您的回應就不完整。這適用於每一條訊息,沒有例外。
違反此規則的字面意義就是違反其精神。
進度文件維護
在更新長生命週期的進度/狀態檔案(例如 PROGRESS.md)時,請將其保持在當前狀態 + 操作儀表板的形式,而不是會話記錄形式。
保留在當前檔案中:
- 未來工作所依賴的活躍狀態:當前結果、阻礙項、正在執行的程序、待處理的決策、活躍的基礎架構以及下一步行動。
- 仍屬於當前結構一部分的專案章節,除非使用者明確移除或歸檔它們。
- 當前的專案計畫和繼續所需的具体細節。
移至存檔檔案:
- 歷史會話記錄、過時的執行、被取代的計畫、被廢棄的路徑、舊的已回答問題以及除錯敘述。
- 劃掉或標記為「已由…取代」的條目;將當前文件重寫為當前事實,並將舊上下文保留在存檔中。
- 已暫停或超出範圍、不再需要立即繼續的分支。
請勿將臨時的專案特定排除事項、基準測試名稱或當前的實驗選擇編碼到持久的偏好文字中。這些應屬於專案進度文件本身。持久的規則是維護策略:當前檔案保持最新且可操作;舊的敘述移至存檔。
清理完成後,在提交前使用 grep 檢查進度檔案中是否包含過時的路徑名稱、舊的除錯術語和劃掉標記。
閘門函數
在認為回應完成之前:
1. 掃描:讀取使用者訊息 + 任務執行 — 是否有偏好/陷阱/摩擦訊號?
2. 記錄:寫入觀察日誌。如果 detected=true,則寫入/更新記憶體。
3. 確認:如果偵測到訊號,在回應結尾告知使用者。
跳過任何步驟 = 合規失敗。
閘門機制
僅啟用硬性檢查:觀察日誌檔案必須在停止時,於過時閾值內(預設 1800 秒,可透過環境變數 OBSERVATION_LOG_AGE_THRESHOLD_SEC 調整)被附加。這就是整個閘門。
軟性文字標記掃描已停用(因為我的回應文字措辭每次輪詢都有變化,導致了虛假封鎖)。結構化日誌條目本身就包含了掃描結果 — 這足以作為稽核線索。
每次輪詢的實用規則:
- 在停止前,在
observations.jsonl中附加一條條目。任何條目都可以,detected=true 或 detected=false 對閘門來說都無所謂。 - 繼續執行豐富的結構化條目(偵測欄位、root_cause 備註、confirmation_text) — 它們使本地記憶體/稽核軌跡更有用,即使閘門不檢查它們。將任何使用者訊息摘錄截斷至約 200 個字元,切勿將密碼/憑證複製到日誌中。
- 無需在回應文字中貼上 SCAN 標記。
為什麼這很重要:閘門僅在日誌確實未被寫入(真正的遺漏)時才封鎖,而不是因為回應文字不符合某個正則表達式 — 這避免了虛假封鎖。
紅旗 — 停下來
如果您發現自己有以下任何想法,請停下來並進行掃描:
- 「這只是狀態檢查 / 簡單問題」
- 「我可以在任務完成後再掃描」
- 「任務比掃描更緊急」
- 「我最近才掃描過,跳過這次」
- 「這裡顯然沒有什麼」
- 「我正在處理複雜的事情」
- 「這條訊息太短,不可能包含訊號」
- 「NOOP / UPDATE 不需要 confirmation_text」 → 錯誤;detected=true 的路徑需要確認(請參閱
## 確認策略)
合理化預防
| 不儲存的藉口 | 現實 |
|---|---|
| 「這是方法論決定,不是偏好」 | 方法論決定就是偏好 |
| 「它會寫在程式碼裡」 | 程式碼不是記憶體。下次會話不會讀取程式碼 |
| 「太明顯了,不需要儲存」 | 如果很明顯,為什麼你違反了它?儲存它 |
| 「現有記憶體已經涵蓋了」 | 請引用 atomic_id,否則就代表未涵蓋 |
| 「不可重複使用 / 一次性指示」 | 那麼請在回應中說明 — 讓使用者糾正你 |
| 「我確信這不是訊號」 | 確信 ≠ 證據。寧可過度偵測,也不要漏掉 |
基於原則的偵測(始終優先)
以下模式是範例種子,並非詳盡的清單。 使用者表達方式多變;字面上的模式匹配會錯過大多數訊號。請先語義性地套用原則,然後使用模式作為線索。
偵測原則(每次輪詢按此順序套用)
-
任何表達使用者希望事情如何完成的子句 → 偏好
- 包括第一人稱價值陳述(「我喜歡 / 我希望 / 我認為 X 很好」)、規範性陳述(「X 應該 / 必須 / 最好 Y」)、比較性偏好(「X 比 Y 好」)
- 無論其表達形式是指令、理由、抱怨還是題外話
-
任何表達沮喪或糾正您行為的子句 → 摩擦或陷阱
- 沮喪標記:重複(「又來了」 / 「還是」)、惱怒(「為什麼它還是…」)、反問(「我不是已經說過…」)、諷刺(「算了」)
- 即使被緩和語氣(「其實」 / 「沒關係」 / 「算了」),這些緩和詞通常掩蓋了真正的訊號
-
訊息中的任何理由/正當化子句 → 獨立掃描
- 使用者結構
[指令] + [理由]— 理由通常說明了他們為什麼有這個偏好,而這正是偏好的內容 - 標記:因為 / 主要 / 我想要 / 我希望 / 因此 / 所以 / 以便
- 使用者結構
-
任何關於您行為的後設問題 → 摩擦(您做了某件他們希望重新考慮的事)
- 「這是 X 嗎?」 / 「你對 Y 有什麼看法?」 / 「你為什麼這樣做?」 / 「這是 Z 嗎?」 — 使用者是在質疑你的選擇,而不是在徵求意見
-
對不尋常方法的默認接受,或對你的建議進行乾淨的轉向 → 已驗證的偏好
- 沒有反對意見本身就代表訊號。特別是當你做出了一個他們本可以糾正的判斷時。
成本不對稱性(預設)
- 誤報成本(將非訊號標記為訊號):使用者說「不,這是一次性的」 → 你學到了東西。損失約 1 輪。
- 漏報成本:使用者在多輪中被困擾,同樣的錯誤一次又一次地在會話中重複,最終的修正需要很高的成本。
- → 預設:偵測,低信心時詢問,中等以上信心時儲存。
不要停留在模式上
如果訊息不符合任何列出的模式,但任何一個原則被觸發 → 仍然是訊號。模式是錨點;原則是規則。
隱含訊號偵測
以下是上述原則的具體例子 — 種子模式庫,並非完整集合。 先從語義上掃描(參見原則),然後將這些作為線索:
| 使用者說 | 表面含義 | 實際訊號 | 線索 |
|---|---|---|---|
| 「你不應該檢查其他地方嗎?」 | 提問 | 摩擦:你本來就應該做這件事 | 在你犯錯之後 |
| 「又來了…」 / 「還是…」 / 「為什麼還是…」 | 沮喪 | 陷阱:同樣的錯誤重複發生 | 第二次以上發生 |
| 「我不是已經告訴過你了嗎?」 | 反問 | 摩擦:規則存在但未被遵守 | 參考記憶體 |
| 「是」 + 修正 | 部分同意 | 偏好:強化現有規則 | 微妙的重新導向 |
| 默認接受不尋常的方法 | 無反對意見 | 偏好:已驗證的判斷 | 沒有修正 |
| 「因為…我希望…」 | 請求的理由 | 偏好:「因為」子句陳述了規則本身 | 合理化子句通常包含偏好,而不只是上下文 |
| 「驗證它,因為我希望…」 | 任務指令 | 偏好:偏好的回答方式(實證 > 理論) | 「因為」子句揭示了工作風格偏好,與任務本身分開 |
…
[為翻譯而截斷]