Community寫作與編輯github.com

YujunZhou/tellonce

用於 Claude Code 的會話內合規強制技能(論文 Sec 6 內部測試)。具有每個用戶自適應閾值,並經過混沌測試的安裝/診斷/卸載功能。

tellonce 是什麼?

Tellonce 是一個專門為 Claude Code 設計的合規強制技能,用於在會話中自動檢測、記錄和強制執行用戶偏好。它採用多層架構,包括規則注入、適用性閘門和合規追蹤器,所有這些都透過自動鉤子運行,無需明確呼叫。預設情況下,技能處於「觀察模式」,僅掃描偏好並記錄,不會封鎖會話或呼叫外部 LLM,從而保護用戶隱私。若要啟用硬性封鎖或 AI 審判模式,使用者需明確設定環境變數 `PT_ENFORCE=1` 或 `PT_SHADOW=1`。該技能的核心是「鐵律」,要求每個回應都必須包含偏好掃描,並透過「閘門函數」確保記錄觀察結果。其設計重點在於避免誤報(假陽性),並透過漸進式規則索引(預設使用 `progressive` 後端,最多 50 條規則)和基於原則的語義檢測,幫助開發者追蹤複雜的跨會話偏好,而非依賴於模式匹配。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add YujunZhou/tellonce

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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,否則就代表未涵蓋
「不可重複使用 / 一次性指示」那麼請在回應中說明 — 讓使用者糾正你
「我確信這不是訊號」確信 ≠ 證據。寧可過度偵測,也不要漏掉

基於原則的偵測(始終優先)

以下模式是範例種子,並非詳盡的清單。 使用者表達方式多變;字面上的模式匹配會錯過大多數訊號。請先語義性地套用原則,然後使用模式作為線索。

偵測原則(每次輪詢按此順序套用)

  1. 任何表達使用者希望事情如何完成的子句 → 偏好

    • 包括第一人稱價值陳述(「我喜歡 / 我希望 / 我認為 X 很好」)、規範性陳述(「X 應該 / 必須 / 最好 Y」)、比較性偏好(「X 比 Y 好」)
    • 無論其表達形式是指令、理由、抱怨還是題外話
  2. 任何表達沮喪或糾正您行為的子句 → 摩擦或陷阱

    • 沮喪標記:重複(「又來了」 / 「還是」)、惱怒(「為什麼它還是…」)、反問(「我不是已經說過…」)、諷刺(「算了」)
    • 即使被緩和語氣(「其實」 / 「沒關係」 / 「算了」),這些緩和詞通常掩蓋了真正的訊號
  3. 訊息中的任何理由/正當化子句 → 獨立掃描

    • 使用者結構 [指令] + [理由] — 理由通常說明了他們為什麼有這個偏好,而這正是偏好的內容
    • 標記:因為 / 主要 / 我想要 / 我希望 / 因此 / 所以 / 以便
  4. 任何關於您行為的後設問題 → 摩擦(您做了某件他們希望重新考慮的事)

    • 「這是 X 嗎?」 / 「你對 Y 有什麼看法?」 / 「你為什麼這樣做?」 / 「這是 Z 嗎?」 — 使用者是在質疑你的選擇,而不是在徵求意見
  5. 對不尋常方法的默認接受,或對你的建議進行乾淨的轉向 → 已驗證的偏好

    • 沒有反對意見本身就代表訊號。特別是當你做出了一個他們本可以糾正的判斷時。

成本不對稱性(預設)

  • 誤報成本(將非訊號標記為訊號):使用者說「不,這是一次性的」 → 你學到了東西。損失約 1 輪。
  • 漏報成本:使用者在多輪中被困擾,同樣的錯誤一次又一次地在會話中重複,最終的修正需要很高的成本。
  • → 預設:偵測,低信心時詢問,中等以上信心時儲存。

不要停留在模式上

如果訊息不符合任何列出的模式,但任何一個原則被觸發 → 仍然是訊號。模式是錨點;原則是規則。


隱含訊號偵測

以下是上述原則的具體例子 — 種子模式庫,並非完整集合。 先從語義上掃描(參見原則),然後將這些作為線索:

使用者說表面含義實際訊號線索
「你不應該檢查其他地方嗎?」提問摩擦:你本來就應該做這件事在你犯錯之後
「又來了…」 / 「還是…」 / 「為什麼還是…」沮喪陷阱:同樣的錯誤重複發生第二次以上發生
「我不是已經告訴過你了嗎?」反問摩擦:規則存在但未被遵守參考記憶體
「是」 + 修正部分同意偏好:強化現有規則微妙的重新導向
默認接受不尋常的方法無反對意見偏好:已驗證的判斷沒有修正
「因為…我希望…」請求的理由偏好:「因為」子句陳述了規則本身合理化子句通常包含偏好,而不只是上下文
「驗證它,因為我希望…」任務指令偏好:偏好的回答方式(實證 > 理論)「因為」子句揭示了工作風格偏好,與任務本身分開

…

[為翻譯而截斷]

相關技能