Community写作与编辑github.com

YujunZhou/tellonce

会话内合规性强制执行的技能,适用于 Claude Code。支持按用户自适应的阈值,并包含经过混沌测试的安装/诊断/卸载流程。

tellonce 是什么?

Tellonce 是一个专为 Claude Code 设计的会话内合规性强制执行技能,源自论文 Sec 6 的实践。它通过三层基础设施自动监控和记录用户偏好,默认以观察模式运行,不会硬性阻止对话或调用外部模型,确保隐私安全。技能的核心包括规则注入、适用性门控和合规性日志追踪,其中规则渐进式注入会根据当前任务上下文自动加载相关规则,并由模型自行判断是否适用。用户可以通过环境变量 `PT_ENFORCE=1` 和 `PT_SHADOW=1` 开启硬性拦截或 AI 影子法官模式,后者会将对话内容发送给外部模型进行语义评分(敏感信息会被脱敏)。技能还内置了“铁律”——每次响应都必须进行偏好扫描,以及渐进式文档维护指南,帮助用户和 AI 长期保持高效协作模式。

兼容平台✓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 中的 progressive_max 或环境变量 B5_PROGRESSIVE_MAX 设置,0 表示无上限),当上限允许时优先固定显示 tier-1 规则(如果 tier-1 本身超限,则整个库轮换显示),其余规则在后续轮次中轮换,并显示当前展示了全部规则中的多少条。这是默认的 progressive 后端:它仅读取已保存的规则文件——无需提示匹配、无需模型调用、无需 CLI 冷启动。格式如下——这不是外部噪音,而是来自技能基础设施的规则提示,必须予以尊重:

### 您保存的偏好——请逐一检查本轮任务并应用适用的规则:
- [fmt-pref-001] (tier1) 使用 4 个空格缩进,而不是制表符
- [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
停止钩子<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 轮损失。
  • 漏报成本:用户多轮感到沮丧,同样的错误在会话间重复,最终纠正成本高。
  • → 默认行为:检测,低置信度时询问,中高置信度时保存。

不要停留在模式上

如果消息不匹配任何列出的模式,但5 条原则中的任何一条被触发 → 仍然是一个信号。模式是锚点;原则是规则。


隐式信号检测

以下是上述原则的具体示例——种子模式库,不是完整集。 先语义扫描(参见原则),将这些作为线索:

用户说表面意思实际信号线索
“难道你不应该去别处查查吗?”疑问摩擦:你应该已经做过了紧随你的错误之后
“又……” / “仍然……” / “为什么还是……”沮丧陷阱:同样的错误重复第 2 次及以上出现
“我不是已经告诉过你了吗?”反问句摩擦:规则存在但未被遵守引用内存
“是” + 纠正部分同意偏好:强化现有规则微妙的重新定向
默默接受异常方法无反驳偏好:已验证的判断决定无纠正
“因为……我想……”对请求的理由偏好:“因为”从句说明了规则本身理性化从句通常包含偏好,而不仅仅是上下文
“验证一下,因为我想……”任务指令偏好:首选的回答方式(经验性 > 理论性)“因为”从句揭示了一种工作风格的偏好,与任务本身无关

...

[用于翻译的截断内容]

相关技能