SummerSec/semantic-linter

英文版本

Semantic-Linter

Semantic-Linter 是一个面向 LLM 指令文件的插件与 CLI，用来收窄语义边界过宽的表达。它主要用于 SKILL.md、AGENTS.md、CLAUDE.md、prompt 文档、command 文档等指令资产，帮助减少因为措辞过宽带来的幻觉和范围漂移。

当前架构

Semantic-Linter 现在使用分层设计，不再是旧的 pointer-only 方案：

- SessionStart 注入一条紧凑的 STL: 规则指针，指向当前生效的 semantic-rules.md
- SubagentStart 把同样的规则指针传播给子代理
- UserPromptSubmit 可以在提示词进入模型前提醒宽边界表达
- PreToolUse 会在 Write 和 Edit 修改指令文件前给出预警
- PostToolUse 会在写入后再次检查结果，并记录升级状态
- bin/scan.js 仍然保留为显式 CLI 扫描入口，可扫描单文件、目录或当前工作区

默认运行模式是 guarded：

- off：关闭 semantic-linter
- pointer：只保留轻量规则指针
- guarded：规则指针 + 写入期检查
- strict：规则指针 + 写入期检查 + prompt 扫描

规则来源策略

默认使用 project-first 规则解析策略：

1. 从当前编辑文件或工作区开始，向上查找最近的 semantic-rules.md
2. 如果项目内没有，则回退到插件自带的 semantic-rules.md

你也可以通过 .semantic-linter.json 强制使用 plugin-only。

安装

Claude Code

claude plugin marketplace add SummerSec/semantic-linter
claude plugin install semantic-linter@summersec-semantic-linter
/reload-plugins

Codex

codex plugin marketplace add SummerSec/semantic-linter
codex plugin add semantic-linter@semantic-linter

Codex 不直接消费 Claude 的 hook manifest。它的项目级接入方式是把受管规则块写入 AGENTS.md。

DeepSeek Harness

安装官方 DSH CLI，并把本仓库作为 bundle 加入需要使用的 profile：

npm install -g @deepseek-ai/dsh@0.1.0-rc.6
dsh plugin --profile headless add github:SummerSec/semantic-linter
dsh plugin --profile web add github:SummerSec/semantic-linter

本地开发时可以在仓库根目录执行：

dsh plugin --profile headless add .

如果 pnpm 返回 ERR_PNPM_ADDING_TO_ROOT，在命令末尾追加 --ignore-workspace-root-check 后重试。

这个 DSH bundle 会把仓库根目录 skills/ 下的四个 Skill 注册到 ctx.skills。DSH 还会读取工作区中的 AGENTS.md 或 CLAUDE.md；调用 rules-installer 后，项目可以通过受管规则块按需读取 semantic-rules.md。

DSH 不会直接执行本仓库的 Claude hook manifest。DSH 下提供的是 packaged Skill + 项目 instruction pointer；SessionStart、SubagentStart、UserPromptSubmit、PreToolUse、PostToolUse 和 /stl-mode 仍仅属于 Claude hook 路径。

项目初始化

如果你想把项目本地规则注入到当前仓库，可以运行：

node /absolute/path/to/semantic-linter/scripts/build-rules.js --existing "$(pwd)"

这会生成：

- semantic-rules.md
- AGENTS.md 和或 CLAUDE.md 中的受管规则区块

如果两个文件都不存在，脚本会根据宿主环境创建默认目标：

- Codex 或 auto：AGENTS.md
- Claude：CLAUDE.md

常用命令：

npm run build-rules
npm run build-rules:check
npm run build-lexicon
npm run build-lexicon:check
npm run scan --
npm test

配置

可选配置文件为 .semantic-linter.json。

支持的字段：

{
"ignoreTrapIds": ["T01"],
"ignorePathSubstrings": ["fixtures/generated/"],
"ignoreStructuralTypes": ["open_ended_verb"],
"defaultMode": "guarded",
"ruleSource": "project-first",
"enablePromptScan": false,
"maxFindingsPerHook": 3
}

说明：

- defaultMode 支持 off、pointer、guarded、strict
- ruleSource 支持 project-first 和 plugin-only
- enablePromptScan 会在 guarded 模式下启用 UserPromptSubmit
- strict 会始终开启 prompt 扫描

检测范围

Semantic-Linter 会按路径约定扫描指令类文件：

- 文件名：SKILL.md、AGENTS.md、CLAUDE.md
- 后缀：.prompt.md、_definitions.md、*_examples.md
- 目录：skills/、agents/、commands/、rules/、prompts/

开发说明

核心运行时文件：

- hooks/session-start.js
- hooks/subagent-start.js
- hooks/user-prompt-submit.js
- hooks/pre-tool-use.js
- hooks/post-tool-use.js
- hooks/config.js
- hooks/runtime.js
- hooks/rules-resolver.js

核心库文件：

- lib/content-scanner.js
- lib/structural-analyzer.js
- lib/report-formatter.js
- lib/state-manager.js
- lib/config-loader.js

测试

npm test

npm test 会依次运行：

- build-lexicon:check
- build-rules:check
- tests/test-scanner.js
- tests/test-new-features.js

测试覆盖扫描器行为、生成器幂等性、manifest 一致性，以及基于 stdin 的 hook 入口行为。