English Version

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 -- <file>
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 入口行为。