canon

name	canon
description	三省引擎(CMG)典则线 (Canon) — 规则生产库。v2.7.2 默认固化阈值10→3。纯静态规则层，不执行拦截、不存记忆。
version	2.7.2
role	producer
stage	system_anchor
dependencies	[]
min_hermes_version	any
platforms	["linux","macos","windows"]
author	L1veSong
license	MIT
metadata	{"hermes":{"tags":["cmg","canon","rules","self-reflection"],"related_skills":["guard","mnemonic","canon-mnemonic-guard"]}}

Canon 典则线 v2.7.2 — 规则生产库

角色: producer (规则生产锚点) | 阶段: system_anchor (系统锚点层)

三省引擎(CMG)典则线。从 CMG v5.0.2 物理拆分独立。不执行拦截、不存记忆——只生产规则。

---

文件结构

~/.hermes/self-reflection/
├── errors.jsonl              # 原始错误记录 (永久追加)
├── patterns.json             # 匹配模式库 (去重压缩)
├── state.json                # 跨会话状态
├── rules/                    # Obsidian 结构化规则目录
│   ├── _index.md             # 自动索引 + wikilinks 表格
│   ├── ban/                  # 禁止项
│   ├── gap/                  # 缺失项
│   └── lazy/                 # 偷懒项
├── config.json               # 用户配置
└── checklists/               # 防偷懒清单

---

版本变更

版本	变更
v2.7.2	+默认固化阈值10→3
v2.7.1	+P2补全: 草稿快速通道(接收Mnemonic同会话推送) + 与Mnemonic v3.5.1联动
v2.7.0	+误报自动降级(连续否决≥3次→降soft) + 规则有效期(!remember --expires 7d)
v2.6.0	+规则分级(hard/soft/monitor) + 修正模板(correction_template) + 用户纠正级别调整 + level_history追踪
v2.5.1	+推荐列表自动扫描: config.json recommendations + !scan-recommendations + plugins 扫描源
v2.5.0	+C1 定时扫盘: 加载时检查距上次扫盘天数，超阈值自动触发
v2.4.1	护栏逻辑剥离至 guard-spec.md，CMG v5.1.0 四包制分装
v2.4.0	+规则效果评分 +角色声明制 +简化触发词 +导入导出
v2.3.1	+规则冲突检测与自动裁决
v2.3.0	+依赖解耦(RuleReader接口+7适配器) +可配置扫描源 +模式切换
v2.2.9	+首次真实扫盘提取+固化执行
v2.2.3	+角色声明制(废除数字优先级)
v2.2.0	+扫盘提取
v2.0.0	Obsidian 结构化 rules/ 目录

---

启动时

1. 加载配置

读取 ~/.hermes/self-reflection/config.json。如不存在，使用默认值（含 auto_scan_interval_days: 7）。

2. 加载规则库

优先加载 rules/ 目录（结构化规则），降级加载 rules.permanent.md（v1 兼容）。

3. 加载跨会话状态

读取 ~/.hermes/self-reflection/state.json，核心字段：

{
  "last_solidify_at": "ISO8601",
  "last_scan_at": "ISO8601",
  "errors_since_solidify": 5,
  "sessions_since_start": 12,
  "last_activation": "ISO8601"
}

last_scan_at 记录上次扫盘时间（v2.5.0 新增）。

4. 检查固化阈值

比较 errors_since_solidify 与 auto_solidify_threshold。

5. 定时扫盘检查（C1 · v2.5.0）

触发条件： 每次 Canon 加载时自动执行。

执行步骤：

1. 读取 state.json → 获取 last_scan_at
2. 计算距上次扫盘的天数
3. 读取 config.json → auto_scan_interval_days（默认 7）
4. 如果 距上次扫盘 ≥ auto_scan_interval_days → 触发扫盘
   - 执行「扫盘提取」章节的完整流程（扫描 SOUL.md / Obsidian / Memory / Skill）
   - 更新 state.json: last_scan_at = now()
   - 输出: "定时扫盘完成。距上次 {N} 天。发现 {M} 条准则 → 待用户确认导入。"
5. 如果未到阈值 → 跳过
   - 输出: "距上次扫盘 {N} 天（阈值 {D} 天），跳过定时扫盘。"

降级： state.json 缺失或 last_scan_at 不存在 → 视同上一次从未扫盘，首次加载时自动触发。

5.5 SOUL 激活检测 + 推荐扫描（v2.5.2）

触发条件： 每次 Canon 加载时自动执行（在 C1 扫盘之后）。

执行步骤：

1. 读取 SOUL.md → 搜索 [CMG v{x}.{y}.{z}] 标记
2. 检测结果：
   ✅ 标记存在 + 版本匹配 → 静默通过
   ⚠️ 标记存在 + 版本过旧 → 输出: "CMG 已升级到 v{x}，SOUL.md 激活标记仍为 v{old}。更新？[Y/N]"
   ❌ 标记不存在 → 输出: "SOUL.md 未找到激活标记，护栏未自动生效。重新写入？[Y/N]"
3. 如果 C1 扫盘触发（距上次扫盘超阈值）：
   - 扫盘流程自动包含推荐列表扫描
   - 检查 config.json → recommendations.items[] 逐项
   - 新检测到的已安装推荐 → 提示启用
4. 如果 C1 扫盘未触发（未到阈值）：
   - 跳过推荐扫描（避免每次对话都扫）
   - 用户可用 !scan-recommendations 手动触发

推荐扫描输出格式（扫盘时自动包含）：

📋 推荐列表（自动扫描）:
  ✅ 8 个已就绪
  ⚠️ 1 个待配置: plur（已安装但未启用 → 输入 !scan-recommendations 配置）
  ❌ 0 个未安装

激活标记丢失的恢复流程：

⚠️ SOUL.md 中未找到 CMG 激活标记。
   护栏规则当前未自动生效。

   原因可能：
   1. 你手动删除了 SOUL.md 中的 [CMG v...] 行
   2. SOUL.md 被其他工具覆盖
   3. 这是首次在新设备上使用 CMG

   是否重新写入激活标记？
     [Y] 恢复 — 重新写入 [CMG v5.5.2] 加载 canon-mnemonic-guard 护栏规则
     [N] 跳过 — 护栏保持停用，下次扫盘再提醒

   选择 [Y/n]:

注意： 激活标记丢失≠CMG 损坏。规则库、配置、推荐列表全部在 ~/.hermes/self-reflection/ 中完整保留。丢失的只是 SOUL.md 中的一行触发器。

首次安装： 安装时执行初始扫盘 → 写入 last_scan_at。后续按阈值周期触发。

6. 加载防偷懒清单

读取 checklists/ 下 config.json 中启用的 YAML 文件。

7. 输出激活状态

必须输出: "Canon v2.7.2 已激活。{N} 条规则（{ban}/{gap}/{lazy}）。距上次扫盘 {D} 天。定时扫盘: {on/off}（间隔 {X} 天）。"

---

用户指出错误时（「记住」触发）

任何表达「记录错误行为 + 希望未来避免」的语句触发。三步走：生成规则 → 写入 rules/ → 更新 patterns.json。

---

冲突检测

新规则写入前扫描同类型规则。跨类型检测（ban↔gap↔lazy）已启用。冲突时 clarify 四选一裁决。

---

规则分级 (v2.6.0)

v2.6.0 新增。所有规则必须标注级别，Guard 根据级别决定拦截策略。

三级定义

级别	拦截行为	重试策略	设置方式	适用场景
hard	立即拦截	自动重试直到修正	!remember --hard	数学错误、安全违规、API错用
soft	提醒后放行	提醒1次，不重试	!remember --soft（默认）	启发式建议、可协商规则
monitor	不拦截	纯计数+报告	!monitor	观察性规则、实验性规则

规则 frontmatter 新增字段

---
type: ban
id: rule_xxx
level: hard        # ← v2.6.0 新增：hard / soft / monitor
correction_template: "具体修正方向"  # ← v2.6.0 新增
---

修正模板 (correction_template)

每条 hard 规则必须配置。Guard 拦截后注入此模板到 RetryLoop，告诉 AI 怎么改。

格式要求：

• 一句话说明修正方向（不要太长，避免上下文膨胀）
• 给出具体操作指令（不是原则性描述）

示例：

# 好：具体可执行
correction_template: "所有 OCR 坐标必须除以 2。请将你输出的所有坐标数值全部除以 2 后再输出。"

# 好：给出替换方案
correction_template: "禁止 pyautogui.hotkey('cmd','v')。请替换为 osascript keystroke 'v' using command down。"

# 差：只说了违规没说怎么改
correction_template: "不要用 pyautogui hotkey。"

# 差：太长了
correction_template: "关于 pyautogui 的 hotkey 功能，在 macOS 环境下，由于系统权限和输入法限制，Cmd 修饰键有概率丢失..."

未配置的 hard 规则： Guard 使用通用回退——"你的回答违反了规则：{rule_name}。请遵守该规则重新生成。"

用户纠正时的级别调整

用户纠正某规则 → 该规则提升一级: monitor→soft, soft→hard
hard 不再升级（已是最高）
当前会话内强化、跨会话恢复原级（除非再次纠正）

级别迁移记录

规则 frontmatter 新增字段追踪级别变化：

level_history:
  - {from: soft, to: hard, reason: "用户纠正", date: "2026-05-23"}

!remember 增强

!remember "禁止xxx"              → 默认 soft
!remember --hard "禁止xxx"       → hard
!remember --soft "注意xxx"       → soft（冗余，但明确）
!monitor "观察xxx"               → monitor

---

规则效果评分 (v2.7.0 增强)

命中率/误报率/最后命中/创建日期四指标。误报率>30%标记待调整，180天未命中提示过期。

误报自动降级（v2.7.0）

v2.7.0 新增。 规则不再永久锁定在 high 级别。用户连续否决/忽略某规则达到阈值 → 自动降级。

降级规则：

hard 规则被用户连续否决（说「这不是错误」「放行」）≥ 3 次 → 自动降为 soft
soft 规则被用户连续否决 ≥ 5 次 → 自动降为 monitor
monitor 规则被用户连续否决 ≥ 10 次 → 标记「待移除」，下次扫盘提示删除

降级后观察期 7 天：期间无再次违规 → 维持新级别
观察期内再次违规 → 恢复原级别

降级日志： rules/ frontmatter 新增 downgrade_history 字段追踪降级事件。

规则有效期（v2.7.0）

v2.7.0 新增。 不是所有规则都永久生效。临时规则到期自动失效。

用法：

!remember --expires 7d "论文提交前检查格式"   → 7天后自动失效
!remember --expires 30d "项目A的特殊约束"     → 30天后
!remember --expires never "禁止虚构幻觉"      → 永久（默认）

到期行为： 规则到期后自动从 rules/ 移至 rules/.expired/ 归档目录。下次扫盘时提示：「{N} 条规则已过期，是否清理？」

frontmatter 新增字段：

expires_at: "2026-06-01T00:00:00Z"  # ISO8601，到期时间
expired_action: "archive"            # archive=归档 / delete=删除

---

动态固化阈值

adaptive 模式根据用户纠正频率动态调整（高频→5，正常→10，低频→20），可切换为 fixed。

---

规则导入/导出

!export → rules/ + state.json + patterns.json → ZIP。!import <path> → 逐条冲突检测 → 确认导入。

---

扫盘提取

扫描 SOUL.md / Obsidian 铁则库 / Memory / 其他 Skill 中的准则类内容。过滤规则：含「禁止/必须/规则/铁则/HARD-GATE」的准则类提取，纯偏好/闲聊/日志跳过。

定时扫盘（C1 · v2.5.0）

扫盘不再是一次性的。每次 Canon 加载时检查 last_scan_at，超过 auto_scan_interval_days（config.json 中 auto_scan_interval_days，默认 7 天）自动触发扫盘。新增规则源（如新安装的 Skill、Obsidian 新增的铁则）会自动纳入。

扫盘中自动执行推荐检测（v2.5.1 新增）： 扫盘流程自动包含推荐列表扫描——检查 config.json 的 recommendations.items[]，对每个推荐项验证是否已安装、是否已配置。未配置的已安装项 → 提示用户启用。

手动扫盘

用户说「扫盘」/「扫描规则」/「提取准则」→ 立即执行扫盘，不受阈值限制。执行后更新 last_scan_at。

推荐列表扫描（v2.5.1 新增）

触发词: !scan-recommendations 或「扫描推荐」/「检查推荐列表」

独立于规则扫盘。只扫描 config.json 的 recommendations.items[]，不扫规则源。

执行流程：

1. 读取 config.json → recommendations.items[]
2. 逐项检测安装状态:
   - type=skill: 检查 detection_path 文件是否存在
   - type=plugin: 检查 pip entry points (detection_group + detection_name)
   - type=mcp_server: 检查 detection_path 文件是否存在
3. 逐项检测配置状态:
   - skill: 检查 skill 是否在 Hermes 已安装列表中
   - plugin: 检查 config.yaml plugins.enabled 是否包含
   - mcp_server: 检查 ~/.hermes/config.yaml 是否有对应 provider
4. 分类输出:
   - ✅ 已安装+已配置: N 个（正常）
   - ⚠️ 已安装+未配置: N 个 → 逐一询问用户是否启用
   - ❌ 未安装: N 个
5. 用户确认启用 → 自动配置（skill: 无需操作已可用; plugin: 写入 config.yaml; mcp: 写入 custom scan source）
6. 更新 recommendations.items[].configured = true
7. 更新 recommendations.last_scan

自动询问格式：

⚠️ 发现已安装但未配置的推荐工具：

  1. verify-before-completion (护栏增强)
     → Guard 拦截「声称完成但未验证」后自动调用
     启用？ [Y] 是 [N] 跳过

  2. rtk-rewrite (成本优化)
     → 压缩终端输出 60-90% token
     启用？ [Y] 是 [N] 跳过

用户确认后自动写入对应配置，无需手动编辑 config.yaml。

---

固化引擎

errors.jsonl → 去重合并 → rules/ 目录独立 .md → _index.md 自动索引 → patterns.json 更新。

---

健康检查

启动时检测 rules/ state.json patterns.json intercept_log.jsonl mnemonic_state.json 五文件完整性。

---

config.json 参考

{
  "auto_solidify_threshold": 10,
  "solidify_threshold_mode": "adaptive",
  "auto_scan_interval_days": 7,
  "conflict_detection": {"cross_type": true},
  "scoring": {"false_positive_threshold": 0.3, "expiry_days": 180},
  "health_check": {"enabled": true},
  "scan_sources": {
    "builtin": {"soul": true, "memory": true, "skills": true},
    "obsidian": {"enabled": true, "vault_path": "~/obsidian", "rule_dirs": ["🔒 HERMES-全局铁则库"]},
    "custom": []
  }
}

---

常见坑点

坑点 1: frontmatter 覆盖率腐烂

规则库随使用自然增长，但 frontmatter（level + correction_template）不会自动补全。导致 Guard 的重试注入失效。

定期检查：

python3 ~/.hermes/skills/software-development/canon/scripts/check-frontmatter.py

批量修复（三步法，来自 2026-05-25 实战验证）：

1. 分类：区分真规则 vs 元配置（gap/lazy 里混有用户偏好）
2. 分批填充：每批 5-8 条，脚本推断 level + 人工确认
3. 重建索引：python3 scripts/fill-frontmatter.py --rebuild-index

# 预览
python3 ~/.hermes/skills/software-development/canon/scripts/fill-frontmatter.py --dry-run
# 全量填充
python3 ~/.hermes/skills/software-development/canon/scripts/fill-frontmatter.py --all
# 重建索引
python3 ~/.hermes/skills/software-development/canon/scripts/fill-frontmatter.py --rebuild-index

坑点 2: gap/lazy 目录混入元配置

不是 gap/ 和 lazy/ 目录下的所有文件都是"规则"。如「完全自动化模式」「思考模式全局关闭」「热记忆满自动沉淀到Obsidian」——这些是元配置/偏好，不需要 level + correction_template。

已知元配置文件（2026-05-25 确认 6 条）： 热记忆满自动沉淀到Obsidian、记忆查询三层递进、完全自动化模式、强制永久智能技能调度、思考模式全局关闭、禁止跳步骤偷懒摆烂。

处理： 扫描后发现 gap/lazy 中非规则文件 → 移至独立分类或标注 level: meta，避免 Guard 误读。

坑点 3: 批量修复 frontmatter 的风险

一次性脚本批量写入 39 条 frontmatter 极易出现格式错位、level 推断错误。

正确做法： 三步走——(1) 先重建 _index.md 看到全貌，(2) 用脚本生成建议 level 值但人工确认后才逐批写入，(3) 每批 5-8 条写入后运行 check-frontmatter.py 验证。

坑点 4: unknown 空壳规则 — 数据丢了不能编造

规则库中存在 rule_ban_000_unknown、rule_lazy_unknown 等占位文件——有 hit_count（累计 33 次命中）但无规则内容。这是固化引擎的遗留 bug：命中被记录，但规则未从 errors.jsonl 正确提取。

处理流程：

1. 查 errors.jsonl → 搜索 rule_id 匹配的原始错误记录
2. 查 patterns.json → 搜索对应模式条目
3. 有数据 → 从触发上下文反推规则内容，填入文件
4. 无数据（如本次案例：40 条 errors.jsonl 无一条匹配）→ 不编造。标 monitor 保留，等 Mnemonic"2次推草稿"机制下次触发时自动填充
5. 绝对禁止根据文件名猜测或编造规则内容——违反铁则"禁止虚构幻觉瞎编"

为什么不能直接删除： 33 次命中记录是真实数据。删除意味着丢失历史。标 monitor 观察 + 等自动填充是唯一安全路径。

---

参考文件

• 规则库批量修复实战 — 52条规则从25%到100%覆盖率的三步走策略
• SOUL 激活模式 — 技能自激活的通用方案
• 推荐列表配置 schema — config.json recommendations 字段完整 schema
• 批量补全 frontmatter 工作流 — 52条规则从27%覆盖到100%的实战案例
• CHANGELOG.md — 完整版本变更记录
• README.md — 快速上手指南
• README.md — 快速上手指南

安装与激活

npx skills add canon --yes --global
npx skills add guard --yes --global
npx skills add mnemonic --yes --global
npx skills add canon-mnemonic-guard --yes --global

安装完成后运行初始化：

npx canon-mnemonic-guard init

init 流程（v2.5.2）

✅ rules/ 目录已创建（ban/gap/lazy）
✅ config.json 已生成
✅ state.json / patterns.json 已初始化

📋 扫描推荐列表中……

═══════════════════════════════════════
⚡ 护栏自动激活
═══════════════════════════════════════

是否在 SOUL.md 中写入激活标记（一行），让护栏规则在每次对话中自动生效？

  [Y] 是 — 写入一行: [CMG v5.5.2] 加载 canon-mnemonic-guard 护栏规则
  [N] 否 — 跳过，用 !scan 手动触发

选择 [Y/n]: 

选 Y： 在 SOUL.md 末尾追加一行激活标记。Hermes 读取 SOUL.md 时看到这行 → 自动加载 CMG 技能 → Guard 护栏在每次对话中生效。

选 N： 规则仅在 rules/ 目录中。用户手动 /skill canon-mnemonic-guard 或 /skill guard 触发。

激活标记格式

[CMG v5.5.2] 加载 canon-mnemonic-guard 护栏规则

这是 SOUL.md 中普通的一行文本。你可以随时手动删除——删掉后护栏不再自动生效。下一次扫盘时会检测到缺失并提醒。

扫盘时自动检测激活标记（v2.5.2）

每次扫盘（C1 定时或 !scan 手动）都会检查 SOUL.md 中是否存在 [CMG v 开头的激活行：

检测结果	行为
✅ 标记存在且版本匹配	正常，静默通过
⚠️ 标记存在但版本过旧	提示升级：「CMG 已升级到 v{x}，SOUL.md 中激活标记仍为 v{old}。更新？[Y/N]」
❌ 标记不存在	提示缺失：「SOUL.md 中未找到 CMG 激活标记，护栏规则未自动生效。重新注入？[Y/N]」

用户选 Y → 自动更新/写入标记。选 N → 保持当前状态。

激活标记的兼容性

• 格式极简： 一行纯文本，任何文本编辑器可见可删
• 不干扰其他内容： 追加到 SOUL.md 末尾，不修改已有内容
• 版本可追踪： 标记含版本号，升级时检测更新
• 可撤销： 删除这行即可停用护栏，CMG 只在下一次扫盘时提醒一次
• 跨设备： 如果你的 SOUL.md 通过 Obsidian/Git 同步，激活标记随文件迁移