Detective Kusto

一个KQL代理，在编写查询之前会先读取你的实际架构。

让任何模型编写KQL，它都会给你一个看起来正确的查询。然后你将其粘贴到真实的工作空间中，它就会失败，因为UserPrincipleName不是列，signinlogs不是表，并且它过滤的字段在你的租户中是空的。你手动修复它，对工具的信任度降低了一些，最终你不再使用它。

D-Kusto解决了根本原因。它在本地维护你实际拥有的表的目录，一个你记录实际搜索内容的文件，以及一个在你看到查询之前就检查其中每个名称是否在目录中的验证器。

它不绑定于某个特定的助手。它使用MCP协议，因此可以在GitHub Copilot、Claude Code、Cursor、Continue和Zed中工作。如果你的助手完全不支持MCP，它会将相同的规则编译成你的助手会读取的指令文件。

为什么特别强调接地

这是微软自己的发现，并非我们的主张。在NL2KQL论文（arXiv 2404.02933 —— Security Copilot查询助手背后的研究）中，查询是通过在400个问题的基准测试中实际执行来评分的：

他们的消融实验隔离了各个要素：移除架构会使准确率从0.635降至0.431，再移除工作示例则降至0.232。架构接地和工作示例是贡献最大的两个因素，这也是本仓库的核心构建基础。

Related MCP server: mcp-kql-server

你会得到什么

.dkusto/
  config.yaml          your databases, query style rules, redaction policy
  EXPERTISE.md         what YOU look for: thresholds, false-positive traps, query shape
  CONTEXT.md           what the data IS: naming conventions, connector gaps, join traps
  catalog/<db>/tables/ one JSON file per table - the schema, the ground truth
  corpus/*.kql         worked examples with front-matter, adapted rather than reinvented
  memory/              learned corrections. Private, gitignored, never shared by default

该文件夹中的所有内容都属于你。没有任何内容随包一起提供。

快速开始

pip install git+https://github.com/KC-Explore/d-kusto
cd your-project
dkusto init --demo     # a working 6-table synthetic workspace to poke at
dkusto tables
dkusto validate --query 'SigninLogs | where TimeGenerated > ago(1d) | project UserPrincipleName'

最后那个命令告诉你UserPrincipleName不存在，建议使用UserPrincipalName，并且无需接触集群或凭据即可完成。

然后将其指向你自己的架构：

dkusto init                              # a blank workspace
dkusto import my-schema.json             # see docs/schema-format.md for the shapes accepted
$EDITOR .dkusto/EXPERTISE.md             # this is the part that makes it good

d-kusto尚未在PyPI上发布；在此之前请从git安装。

将其接入你的助手

同一台服务器，五个客户端。选择你的。

GitHub Copilot (VS Code) — .vscode/mcp.json

{ "servers": { "dkusto": { "command": "dkusto", "args": ["mcp"] } } }

Claude Code — .mcp.json

{ "mcpServers": { "dkusto": { "command": "dkusto", "args": ["mcp"] } } }

Cursor — ~/.cursor/mcp.json，形状与Claude Code相同。

Continue / Zed — 注册一个运行dkusto mcp的stdio服务器。

服务器通过从其工作目录向上查找来找到你的工作空间。大多数客户端在项目文件夹中启动它，因此这通常能正常工作。如果你的客户端没有这样做，请明确指定——要么在服务器的env中设置DKUSTO_WORKSPACE，要么传递路径，注意这是一个全局标志，因此必须放在子命令之前：

{ "command": "dkusto", "args": ["--workspace", "/path/to/project", "mcp"] }

将其指向包含.dkusto/的目录，或直接指向.dkusto/本身；两者都有效。如果路径不是工作空间，服务器将退出并报错，而不是启动并报告你没有表。

不支持MCP？ 运行dkusto instructions。它将协议以及工作空间的实时摘要编译到AGENTS.md、.github/copilot-instructions.md、CLAUDE.md和.cursor/rules/dkusto.mdc中，并告诉模型直接读取目录文件。我们每个文件中的区域都有分隔，因此不会覆盖你已经保存在那里的笔记。如果没有任何更改，重新运行将是无操作。

七个工具

search_schema返回片段是经过深思熟虑的。将包含300个表的目录粘贴到提示中既昂贵，又不如提供一组有针对性的表那样能产生更好的答案。

验证器能捕获什么，不能捕获什么

它能捕获实际会咬人的失败模式：

• 不存在的表和列，并提供"你是不是想找"的建议

• 存在于不同表上的列，并告诉你具体是哪个表

• 在管道中早期有效，但在你引用之前已被project、project-away或summarize丢弃的列

• 大小写错误——Kusto实体名称是大小写敏感的，因此signinlogs在运行时失败，即使它读起来没问题

• 不是运算符的运算符，悬空的管道

• 控制命令（.drop、.set-or-replace、.ingest）——直接拒绝

它还会发出警告（不会导致失败），关于缺少时间过滤器、没有显式kind=的join，以及没有行数限制的查询。

坦率地说明其局限性：

• 它是一个感知架构的检查器，而不是一个完整的解析器。微软真正的KQL语法存在于一个.NET库中；用Python重新实现它将是一场必输的竞赛。将其替换到同一接口后面，对于任何想要完整保真度的人来说，都在路线图上。

• 它不进行表达式类型检查。

• 它无法知道evaluate插件或存储函数返回什么。

• 当遇到无法建模的内容时，它会停止断言：列跟踪变为开放状态，后续发现从错误降级为警告。这是一个经过深思熟虑的选择。一个会"狼来了"的验证器会被关闭，然后它就什么都捕获不到了。少报是更安全的失败方向。

v1不执行查询。 其中没有任何集群连接或凭据处理。它读取本地文件并返回查询文本。

学习循环

当你编辑代理给你的查询时，将编辑内容反馈回来：

dkusto learn --original before.kql --corrected after.kql --intent "new-country sign-ins"

它会比较两者，对更改进行分类——列交换、大小写修复、时间窗口扩大、添加去重——并编写一条持久的语句，按涉及的表进行索引。下次dkusto_context会呈现相关的经验教训。几周后，代理将不再犯你特定的错误，而不仅仅是泛泛的错误。

隐私，因为这很重要。 存储位于.dkusto/memory/中，dkusto init会使该目录自我忽略——它会在其中写入一个包含*的.gitignore文件，因此无论你自己的忽略规则如何，git都不会拾取它。它保护你，而不是告诉你自我保护。所有内容在写入之前都会经过脱敏处理：UPN、IP地址、主机名、GUID、哈希值和令牌会变成占位符。只有一个共享路径dkusto export-pack，它永远不会自动执行，并且除非你要求，否则会排除查询文本。在将其发送到任何地方之前，请先阅读该文件。

EXPERTISE.md 是大家容易忽略的部分

架构告诉代理什么是可能的。EXPERTISE.md告诉它什么是有用的：低于十次失败的突发是过期的缓存凭据而不是攻击，你的服务帐户主导登录量并破坏任何基线，首次出现的问题需要基线窗口和leftanti连接而不是单个where。

一个没有专业知识文件的接地代理会编写能解析的查询。有了它，它会编写值得运行的查询。dkusto init会给你一个结构化的模板；花十五分钟填写它是使用此工具能做的最具杠杆效应的事情。

自带架构

范围是任何Kusto：Azure Data Explorer、Fabric Eventhouse、Log Analytics、Microsoft Sentinel、Defender XDR高级狩猎。没有内置的供应商目录，也没有关于你的表名称的任何假设。

dkusto import接受几种格式，包括.show database schema as json输出、getschema行以及扁平的表到列映射。docs/schema-format.md 为每种格式提供了一个工作示例和生成它的命令。

一个需要提前说明的警告：样本值是真实数据。在它们接近任何提交之前，请先进行清理。

与微软的Sentinel MCP服务器一起使用

它们相辅相成而非相互竞争。微软的服务器具有实时数据访问和实体丰富功能；D-Kusto拥有你的自定义表、你编写的专业知识、离线验证和私有学习循环，无需数据湖接入和按查询计费。注册两者，使用一个进行编写和验证，使用另一个进行执行。docs/sentinel-mcp.md 提供了详细信息，并引用了来源，任何我们无法验证的内容都明确标记为如此。

命令参考

路线图

实时只读架构自省、从执行结果中学习、架构漂移检测，以及一个带有适用于OpenAI兼容端点、Anthropic和Gemini的适配器的CLI ask。docs/roadmap.md 明确说明了当前存在什么以及不存在什么。

贡献

验证器的运算符和函数注册表是src/dkusto/validator/operators.py中的纯数据。如果它标记了有效的内容，修复通常是在那里添加一个名称——一个真正的一行拉取请求。请在tests/test_validator.py中包含一个失败案例；黄金集将对有效查询的误报视为最严重的错误类型。

许可证和商标

MIT。请参阅 LICENSE。

Kusto、Azure Data Explorer、Microsoft Sentinel、Microsoft Defender和GitHub Copilot是微软公司的商标。这是一个独立的、无关联的工具，用于读取你提供的架构文件。不暗示任何认可。