glossary-management

术语表管理

自我演进的技能：此技能会在使用过程中不断改进。如果说明有误、参数发生偏移，或需要采用变通方案，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

概述

管理全局术语表（~/.claude/docs/GLOSSARY.md）及其 Vale 集成。术语表是所有项目术语的唯一事实来源（SSoT）。

何时使用此技能

适用于以下情况：

• 手动将术语表同步到 Vale 词汇文件
• 验证术语表的格式和结构
• 检查各项目中是否存在重复或冲突的术语
• 以编程方式添加新术语
• 排查 Vale 术语警告

快捷命令

# Manual sync to Vale
bun ~/.claude/tools/bin/glossary-sync.ts

# Check for duplicates/conflicts across projects (invokes terminology-sync hook)
bun ~/eon/cc-skills/plugins/itp-hooks/hooks/posttooluse-terminology-sync.ts <<< '{"tool_name":"Edit","tool_input":{"file_path":"/tmp/test-CLAUDE.md"}}'

架构

┌─────────────────────────────────────────────────────────────────┐
│                    GLOSSARY.md (SSoT)                           │
│                ~/.claude/docs/GLOSSARY.md                       │
└─────────────────────────┬───────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          │               │               │
          ▼               ▼               ▼
┌─────────────────┐ ┌───────────┐ ┌────────────────────┐
│ accept.txt      │ │ Term.yml  │ │ Project CLAUDE.md  │
│ (Vale vocab)    │ │ (subs)    │ │ (bidirectional)    │
└─────────────────┘ └───────────┘ └────────────────────┘

SCAN_PATHS 配置

术语同步钩子使用 SCAN_PATHS 查找项目的 CLAUDE.md 文件。此项通过 GLOSSARY.md 中的 HTML 注释进行配置：

格式规则：

• 必须是以 <!-- SCAN_PATHS: 开头的 HTML 注释
• 每个路径单独一行，并以 - 为前缀
• 支持 glob 模式（*、**）
• 路径相对于主目录（~）

默认路径（如果未指定）：

• ~/eon/*/CLAUDE.md - 顶层项目的 CLAUDE.md 文件
• ~/eon/*/*/CLAUDE.md - 包级别的 CLAUDE.md 文件

表格结构（5 列）

GLOSSARY.md 中的每个术语都采用以下 5 列格式：

列	必填	说明	示例
术语	是	加粗的术语名称（**Term**）	**Time-Weighted Sharpe**
缩写	是	缩写（如果没有则填 -）	TWSR
定义	是	清晰、简洁的定义	Sharpe ratio for range bars
单位/范围	是	测量单位或有效范围	ratio、[0, 1]、-
项目	是	以逗号分隔的项目名称	research-repo, trading-fitness

示例行：

| **Time-Weighted Sharpe** | TWSR | Sharpe ratio for variable-duration bars using time weights | annualized ratio | research-repo |

自动同步（钩子）

两个 PostToolUse 钩子负责自动同步：

钩子	触发条件	操作
posttooluse-glossary-sync	编辑 ~/.claude/docs/GLOSSARY.md	同步到 Vale 词汇表
posttooluse-terminology-sync	编辑项目的 CLAUDE.md	合并术语到 GLOSSARY.md，并检测冲突

手动操作

将术语表同步到 Vale

自动同步失败或需要强制刷新时：

bun ~/.claude/tools/bin/glossary-sync.ts

输出：

=== Glossary Bidirectional Sync ===
  Source: /Users/you/.claude/docs/GLOSSARY.md
  Found 25 acronyms, 24 substitutions
  Updated: .vale/styles/config/vocabularies/TradingFitness/accept.txt
  Total terms: 27
  Updated: .vale/styles/TradingFitness/Terminology.yml
  Substitution rules: 24
  Updated timestamp: 2026-01-22T00:00:00Z
=== Sync Complete ===

验证术语表格式

检查 GLOSSARY.md 是否符合正确的表格格式：

# Check required columns
grep -E '^\| \*\*[^|]+\*\* \|' ~/.claude/docs/GLOSSARY.md | head -5

# Verify table structure (should have | Term | Acronym | Definition | Unit/Range | Projects |)
head -25 ~/.claude/docs/GLOSSARY.md

预期格式：

| Term                     | Acronym | Definition                  | Unit/Range | Projects      |
| ------------------------ | ------- | --------------------------- | ---------- | ------------- |
| **Time-Weighted Sharpe** | TWSR    | Sharpe ratio for range bars | ratio      | research-repo |

检查重复项

扫描所有项目的 CLAUDE.md 文件，查找术语冲突：

# Full duplicate check (scans ~/eon/*/CLAUDE.md)
bun ~/eon/cc-skills/plugins/itp-hooks/hooks/posttooluse-terminology-sync.ts <<< '{"tool_name":"Edit","tool_input":{"file_path":"/tmp/test-CLAUDE.md"}}'

检测到的冲突类型：

• 定义冲突：同一术语有不同定义
• 缩写冲突：同一术语有不同缩写
• 缩写碰撞：同一缩写用于不同术语

添加新术语

向术语表添加新术语：

1. 直接编辑 GLOSSARY.md：

   | **New Term** | NT | Definition of the new term | - | project-name |
   

2. 通过 posttooluse-glossary-sync 钩子自动触发同步

3. 验证 Vale 是否能识别该术语：

   echo "The NT is important" | vale --config=~/.claude/.vale.ini
   

Vale 集成

生成的文件

文件	用途
~/.claude/.vale/styles/config/vocabularies/TradingFitness/accept.txt	接受的术语（不会被标记）
~/.claude/.vale/styles/TradingFitness/Terminology.yml	替换规则（建议使用规范形式）

运行 Vale

# Check a single file (run from file's directory for glob patterns to match)
cd ~/eon/trading-fitness && vale --config=~/.claude/.vale.ini CLAUDE.md

# Check all CLAUDE.md files
find ~/eon -name "CLAUDE.md" -exec sh -c 'cd "$(dirname "$1")" && vale --config=~/.claude/.vale.ini "$(basename "$1")"' _ {} \;

重要：.vale.ini 中的 Vale glob 模式（例如 [CLAUDE.md]）是相对于当前工作目录的。请始终在文件所在目录运行 Vale，或使用与 glob 模式匹配的绝对路径。

故障排除

术语未被识别

1. 检查同步时间戳：

   grep "Last Sync" ~/.claude/docs/GLOSSARY.md
   

2. 强制手动同步：

   bun ~/.claude/tools/bin/glossary-sync.ts
   

3. 验证 Vale 配置路径：

   cat ~/.claude/.vale.ini | grep StylesPath
   

钩子未触发

1. 检查钩子是否已注册：

   grep "glossary-sync" ~/.claude/settings.json
   

2. 确认钩子文件存在：

   ls -la ~/.claude/plugins/marketplaces/cc-skills/plugins/itp-hooks/hooks/posttooluse-glossary-sync.ts
   

Vale 输出显示“0 files”，但文件存在

当 Vale 的 glob 模式与文件路径不匹配时，就会发生这种情况。posttooluse-vale-claude-md.ts 钩子通过以下方式处理：

1. 从文件所在目录逐级向上查找 .vale.ini
2. 在运行 Vale 前切换到文件所在目录
3. 移除 ANSI 转义码，以便可靠地解析输出

如果手动运行 Vale，请确保当前位于文件所在目录：

# Wrong - may show "0 files"
vale --config=/path/to/.vale.ini /absolute/path/to/CLAUDE.md

# Correct - cd first
cd /absolute/path/to && vale --config=/path/to/.vale.ini CLAUDE.md

词汇表目录重复

如果发现 Vale 行为不一致：

# Check for duplicate vocab dirs (should only have config/vocabularies/)
ls -la ~/.claude/.vale/styles/

# Remove any stale Vocab/ directory
rm -rf ~/.claude/.vale/styles/Vocab/

参考资料

• Vale 文档
• GLOSSARY.md：~/.claude/docs/GLOSSARY.md（本地文件）
• itp-hooks CLAUDE.md

执行后复盘

此技能执行完成后，在结束前检查：

1. 命令是否成功？ — 如果没有，请修复导致失败的指令或错误表。
2. 参数或输出是否发生变化？ — 如果底层工具的接口发生变化，请更新用法示例和参数表，使其保持一致。
3. 是否需要变通处理？ — 如果你不得不临时调整（使用不同的标志、增加步骤），请更新此 SKILL.md，以便下次调用时无需重复采用相同的变通方法。

仅当问题确实存在且可复现时才进行更新，不要更新推测性问题。