Sentinel DV

Sentinel DV

Sentinel DV v2.3.1 是一个只读的设计验证证据模型上下文协议服务。它会将导出的 SystemVerilog、UVM、cocotb、断言、覆盖率、回归和波形工件编入 DuckDB，并向 AI Agent 提供 28 个有界、由架构驱动的工具。

文档 | 快速入门 | 视频演示 | 所有工具 | Agent 技能

提供的功能

• **运行与测试智能：**发现、摘要、历史记录、拓扑、差异、回放命令生成和实时状态快照。
• **失败分析：**规范化类别、稳定签名、有界证据、断言失败和失败聚类。
• **覆盖率闭环：**功能、代码、翻转和 FSM 指标；趋势；缺口；空洞性；SVA 状态；以及协议感知的约束候选项。
• **波形上下文：**预计算的 *.wave.json 和有界 VCD 摘要。原生 FSDB/WLF 流式处理不在支持范围内。
• **Agent 工作流：**面向 Codex、Claude Code 和 GitHub Copilot 的回归问题分类、单项测试失败调试和覆盖率闭环技能。

Sentinel DV 不会执行仿真、修改 RTL 或测试平台文件，也不会无限制地流式传输原始工件。runs.submit 和 tests.replay 会返回供工程师审核的试运行命令。

快速入门

需要 Python 3.10 或更高版本。此示例会为已检入的演示语料库建立索引：

若要使用持久环境，请安装 sentinel-dv>=2.3.1。以下命令使用 uvx 运行同一版本，无需持久安装。

git clone https://github.com/kiranreddi/sentinel-dv.git
cd sentinel-dv
cp demo/config.example.yaml demo/config.yaml

uvx --from [email protected] \
  sentinel-dv-index --config "$PWD/demo/config.yaml" --index-all

连接一个 Agent：

Codex

codex mcp add sentinel-dv \
  --env SENTINEL_DV_CONFIG="$PWD/demo/config.yaml" \
  -- uvx --from [email protected] sentinel-dv-server

Claude Code

claude mcp add \
  --env SENTINEL_DV_CONFIG="$PWD/demo/config.yaml" \
  --transport stdio --scope local sentinel-dv \
  -- uvx --from [email protected] sentinel-dv-server

GitHub Copilot CLI

copilot mcp add sentinel-dv \
  --env SENTINEL_DV_CONFIG="$PWD/demo/config.yaml" \
  -- uvx --from [email protected] sentinel-dv-server

使用绝对路径设置 SENTINEL_DV_CONFIG。在客户端的 MCP 状态视图中确认连接，然后调用 runs.list。

请参阅Agent 设置，了解配置文件示例、项目范围、技能发现和故障排除。

生产环境配置

复制 config.example.yaml 并定义允许的工件根目录：

artifact_roots:
  - /absolute/path/to/regression/artifacts

index:
  type: duckdb
  path: ./sentinel_dv.db

adapters:
  uvm: true
  cocotb: true
  assertions: true
  coverage: true
  waveform_summary: true

security:
  max_response_bytes: 2097152
  max_page_size: 200
  max_evidence_refs: 10

redaction:
  enabled: true
  redact_emails: true
  redact_paths: true

启动服务前先构建索引：

sentinel-dv-index --config /absolute/path/to/config.yaml --index-all
sentinel-dv-server --config /absolute/path/to/config.yaml

YAML 中的相对路径以配置文件所在目录为基准解析。生产环境启动时绝不会静默回退到演示数据。

MCP 工具

28 个工具按工程用途分组：

类别	工具
运行	runs.list、runs.get、runs.summary、runs.diff、runs.cross_sim、runs.submit
测试	tests.list、tests.get、tests.history、tests.topology、tests.cluster、tests.replay
失败与断言	failures.list、assertions.list、assertions.get、assertions.failures、assertions.sva_status、assertions.vacuity
覆盖率	coverage.list、coverage.summary、coverage.gaps、coverage.trend、coverage.advisor
回归与仿真	regressions.summary、regression.health、sim.status
波形	wave.signals、wave.summary

每个已注册工具都带有只读 MCP 注释和带版本的输出架构。MCP 工具参考介绍了精确的输入和输出。

Agent 技能

规范技能位于 skills/ 下：

• sentinel-dv-regression-triage
• sentinel-dv-failure-debugging
• sentinel-dv-coverage-closure

确定性镜像可辅助项目发现：

宿主	路径
Codex	.agents/skills/
Claude Code	.claude/skills/
GitHub Copilot	.github/skills/

仓库还包含 Codex 和 Claude 插件清单。.mcp.json 定义了捆绑的 stdio 服务命令；请提供 SENTINEL_DV_CONFIG，或在服务工作目录中放置 config.yaml。

编辑规范技能后：

.venv/bin/python scripts/sync_agent_skills.py
.venv/bin/python scripts/sync_agent_skills.py --check

支持的工件来源

• UVM 日志和拓扑提示
• cocotb 和通用 JUnit XML
• 断言定义和故障 JSON
• SVA 运行状态 JSON
• 支持的 JSON、XML、文本和 HTML 覆盖率摘要
• *.wave.json 和 VCD
• 实时仿真状态 JSON
• 导出的 VCS、Xcelium、Questa 和 Verilator 结果

适配器输出会规范化为带版本的架构，因此客户端无需编写特定于供应商的解析逻辑。

安全模型

• 工具为只读，基于索引和已配置的工件根目录运行。
• 路径解析限制在允许的根目录内。
• 证据计数、摘录、页面、波形信号、覆盖点以及响应总大小均受到限制。
• 可配置的脱敏功能可保护常见机密、电子邮件地址、IP 地址和本地路径。
• 工具输出是确定性的；MCP 服务不会生成因果结论。

使用生产工件前，请阅读安全和生产部署。

验证

创建开发环境：

python3 -m venv .venv
.venv/bin/pip install -e ".[dev,docs]"

运行端点和工作流检查：

.venv/bin/python scripts/verify_all_mcp_tools.py
.venv/bin/python scripts/verify_skill_workflows.py

运行完整质量套件：

.venv/bin/pytest
.venv/bin/ruff check .
.venv/bin/black --check .
.venv/bin/mypy sentinel_dv
.venv/bin/mkdocs build --strict

全工具验证器会调用所有已注册的 MCP 端点。技能验证器会为 52 个已纳入版本控制的演示工件编制索引，并执行已发布的回归分诊、故障调试和覆盖率闭合流程。

项目布局

sentinel_dv/
  adapters/        artifact parsers
  indexing/        DuckDB indexing and queries
  normalization/   signatures, taxonomy, redaction, coverage guidance
  schemas/         versioned response contracts
  tools/core.py    tool implementations
  server.py        FastMCP registration and stdio entry point

skills/            canonical agent skills
demo/              license-free exported verification fixtures
docs/              MkDocs documentation
scripts/           verification, gallery, release, and skill-sync tooling
tests/             unit and integration coverage

贡献

请参阅 CONTRIBUTING.md。Sentinel DV 采用 Apache-2.0 许可证。