nodal-context

# 节点上下文 > 开源的、**基于面试**的分析代理上下文层 - 以及一个与格式无关的工具，衡量您的上下文是否真正使代理更准确。 📖 **文档:** [docs.nodaldata.io](https://docs.nodaldata.io) · 🌐 **网站:** [nodaldata.io](https://nodaldata.io) --- ## 这是什么 将人工智能代理（Claude、Codex、Gemini 或其他）指向数据仓库，让它编写 SQL 查询，感觉像是自助式分析，直到您发现答案是自信地错误的。解决方法不是更好的模型，而是**上下文**：您的术语含义、哪个表是规范的、标准过滤器是什么、以及哪里有陷阱。 `nodal-context` 是三件事，按团队采用的顺序排列： 1. **构建它 - 上下文格式 + 面试技能。** *免费、开源（Apache-2.0）。* 该技能与您的分析师一起构建上下文，一次一个领域，并将其写入团队审查的 Git 仓库。两个深度，一个流程：完整的 多阶段面试，或 **30 分钟快速通道**，确认一个领域的五个最高杠杆答案并草拟其余部分。您可以自由使用、fork 和修改，无需与我们联系。 2. **共享它 - 托管的 MCP 端点。** *自助服务、低成本：订阅并在几分钟内启动。* 将您的分析上下文 - 和可选的 dbt 仓库 - 连接到整个团队共享的 MCP 端点：任何代理都可以从仓库中获取受管辖的答案。将拉取请求合并， 每个消费者都会更新 - 无需重新分发文件。Nodal 管理员还允许**非技术用户编辑上下文** 和向仓库提出拉取请求，以便团队可以量化和质性地评估建议的更改。自托管只读服务器始终免费；托管端点添加身份验证、用法日志和管理员编辑流程。如需，我们还可以在您的云环境中构建 MCP 服务器。 3. **保持正确 - 学习循环。** *企业：[联系我们](mailto:info@nodaldata.io)。* 这是构建学习循环的地方。**可观察性：** 您的业务团队、营销团队和分析师实际提出的数据问题是什么？**覆盖率评估：** 复杂的评估带有覆盖率指标，突出显示问题何时提出时上下文覆盖率最小，以便您随着时间的推移以安全的方式演化上下文。**回归测试：** 确保昨天正确回答的问题今天仍然正确，因为您添加和更改上下文，同时业务发展。还有 **dbt 仓库同步** （上游模型更改会为分析师重新起草受影响的定义）。种子格式和一次性本地运行器始终开放且免费。 ## 为什么是基于面试的，而不是自动构建的 明显的方法 - 以及大多数工具的做法 - 是摄取您的仓库、dbt、BI 层和查询历史并**自动生成**上下文。我们故意不这样做，因为已经衡量的团队发现它不适用于作为事实来源： - Anthropic 的数据团队报告说，从原始表和查询日志自动生成指标定义“编码了我们试图消除的模糊性”，并且在评估中**净负面** 与较小的人工策划层相比。 - 他们还给了代理 grep 访问数千个先前的查询，准确率提升 **不足 1 个百分点** - 信息存在，代理看到了它，但仍然没有解决问题的正确实体。 - [Anthropic 参考资料](https://claude.com/blog/how-anthropic-enables-self-service-data-analytics-with-claude) - 其他数据代理发现类似的结论： [Meta](https://medium.com/@AnalyticsAtMeta/inside-metas-home-grown-ai-analytics-agent-4ea6779acfb3) 和 [Ramp](https://engineering.ramp.com/post/meet-ramp-research) 他们的结论是：**用模型生成文档，但让人类拥有定义。** 这正是面试所做的。我们确实自动提取模式和 dbt 作为**纠正草稿** （以便分析师不必从头开始），但我们信任分析师的确认，而不是提取。 奖励是，分析师在面试中做的每一个消歧义（“活跃客户端意味着 X，而不是 Y”）同时是一个上下文条目 **和一个标记的评估对**。构建上下文的过程就是收集基本事实的过程。 ## 两个深度：完整的面试或 30 分钟快速通道 技能型提取器（例如 Anthropic 的 `data-context-extractor` for Claude desktop）设定了一个公平的市场预期：分析师应该在大约半小时内获得有用的上下文。面试满足了这个预算，同时仍然提供治理。当您说 **“快速通道”** （或“我只有 30 分钟”）时，同一个面试在五个问题的预算下运行在一个领域 - 规范表的粒度、一个模糊的实体、2-3 个指标、标准卫生过滤器和一个静默故障 - 验证几个答案实时针对您的仓库，并将其他未询问的问题留作审查状态为草稿的存根。 与快速技能构建器的区别在于您保留的内容：每个确认的答案仍然 **由人拥有** ，仍然发出 **评估种子** ，并且领域被 **深度标记** （“五个问题深度，N 个草稿开放”），因此速度从不冒充覆盖范围。完整的面试是相同的流程，但没有预算限制 - 而快速通道的待办事项清单（代理在上下文仍然出错的问题）告诉您哪些领域值得进一步审查。已经使用快速提取器构建了数据技能？该工具包会按原样对其进行评分（ `--adapter skill` ），而快速通道是铸造种子最便宜的方式，这些种子会对它进行评分。 ## 格式可读且开源（Markdown + YAML） 此仓库定义了一个上下文格式（ACF - 见 [`SPEC.md`](./SPEC.md)）。但您 **无需使用它** 即可使用测量缝隙。工具包（ [`eval_harness/INTERFACE.md`](./eval_harness/INTERFACE.md)）读取 ACF、Kaelio `ktx` YAML、dbt 模型/文档、原始 Markdown 或代理数据分析技能（例如，由 Anthropic 的 `data-context-extractor` 生成 - 文件夹或打包的 zip），对其进行标准化，并以相同的方式衡量增量。带来您已经拥有的任何上下文。 ## 快速开始 在面试之前，请设置它所依赖的两项。两者都不需要完美，但两者都能使面试 **更快、更准确**：代理验证定义是否与实时数据一致，并读取您现有的转换，而不是猜测。 **1. 通过 MCP 连接仓库（必需）。** 面试会根据实时仓库验证答案，生成的仓库的 `data-question` 技能会查询它 - 两者都需要 **只读** 仓库访问权限。选择您的仓库的 MCP 服务器并将其添加到您的代理： | 仓库 | MCP 服务器 | |---|---| | Snowflake | [Snowflake MCP](https://github.com/Snowflake-Labs/mcp) | | BigQuery | [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) （谷歌）| | Redshift | [AWS Labs MCP 服务器](https://github.com/awslabs/mcp) （Redshift）| | Databricks | [Databricks MCP](https://github.com/databricks/databricks-mcp) | | 其他/一般 | [Model Context Protocol 服务器](https://github.com/modelcontextprotocol/servers) | 使用 **只读角色/凭证** - 面试和数据问题技能永远只会 `SELECT`。请参阅您代理的 MCP 文档（例如 Claude Code：`claude mcp add`），了解如何将其连接起来。 **2. 克隆您的 dbt 仓库（推荐）。** 如果您使用 dbt，请将您的 dbt 项目克隆到一个相邻目录，并在两个仓库可见的情况下启动面试。面试会读取您的 `models/`、`schema.yml` 和指标定义作为**纠正草稿** - 以便分析师纠正实际定义，而不是从头开始描述，并且生成的 `lineage:` 指针引用实际的 dbt 模型。 ```bash # 1. 获取工具。面试技能从存储库根目录读取 SPEC.md、template/、schemas/ 和 scripts/， # 所以克隆整个存储库（不仅仅是技能文件夹）。 git clone https://github.com/nodal-data/nodal-context.git cd nodal-context # 2. 在存储库中打开您的客户端代理（Claude Code / Codex / Cursor）并说： # “构建我的分析上下文。” → 上下文面试技能接管。 # 时间不多？说“快速通道” - 五个核心问题，实时检查， # 其余部分为后续会话草拟。 # （技能在存储库中通过 .claude/skills/ 可发现。） # 它写入一个可审查的 ../analytics-context/ 存储库作为此克隆的** sibling ** # （git 初始化；工具存储库保持只读），并在结束时提供将其推送到 GitHub 的选项。 # 注意：我通过询问“select datetime from each warehouse”检查数据库连接以确保它已登录 # 3. 在第一个域之后，查看增量： # “在 session-financials 上运行评估增量。” # 4. 日常使用上下文：cd 进入生成的存储库并向 Claude Code 提问一个 # 真实的问题 - 在该存储库的 README.md 中查看（Claude Code 基础案例 + Codex）。 ``` 生成的 `../analytics-context/` 是您的交付成果 - 它自己的 Git 仓库。克隆的 `nodal-context/` 工具仓库保持只读；您可以保留它以便稍后为更多领域运行面试，或者在上下文仓库推送后删除它。 ## 存储库布局 ``` nodal-context/ ├── SPEC.md # 分析上下文格式（ACF）- 标准 ├── skills/context-interview/ # 面试技能（免费部分） │ ├── SKILL.md │ └── references/ # 面试状态机 + 骨架 + 收集 ├── schemas/ # 使 YAML 校验的 JSON 模式 ├── template/ # 面试填写的空脚手架 ├── examples/example-healthcare-company/ # ACF 格式的示例 ├── eval_harness/ # 开源评估运行器 + 其接口（INTERFACE.md，README.md） └── .github/workflows/ # 验证上下文，检测漂移，在 PR 上运行评估增量 ``` ## 在团队中共享（MCP） 这是产品 #2 - 自助服务。上下文仓库只是 Markdown + YAML，因此单个分析师可以将自己的代理指向文件并免费获得受管辖的答案：克隆它，在本地读取它，就完成了。这适用于单个人在一台机器上。 要在 **整个团队** 面前提供相同的上下文 - 非技术业务用户在自己的代理中提出问题并获得分析师会给出的答案 - 通过 **MCP** 连接。可选的第二个连接器公开您的 **dbt/仓库 lineage** ，以便代理可以检查 **如何** 计算指标，而不仅仅是其含义。 三种提供方式： - **在 Nodal 上启动（托管）** - 自助服务路径：订阅，粘贴只读 GitHub 令牌到管理员，共享端点。三步，几分钟，低成本。**无需数据库连接** - Nodal 提供上下文仓库，而不是您的数据。 - **构建您自己的** - 在原始仓库上自行托管小型只读 MCP 服务器。始终免费，无锁定。 - **在您的云/VPC 中运行** - 用于数据驻留或安全要求；**联系销售**。 身份验证、用法日志和管理员编辑流程（非技术用户通过 PR 提出上下文更改）是托管产品 - 适用于团队规模分发的便利功能，而不是格式锁定：文件保持开放，自托管始终免费。生成的存储库附带一个 `SHARING.md`，其中包含工具界面和 3 步托管设置。 **您更喜欢 Claude-desktop 和 skill.md 吗？** 编译存储库为可分发的技能快照： ```bash python3 scripts/compile_skill.py path/to/analytics-context --zip ``` 这会发出一个 `<company>-data-analyst/` 技能（SKILL.md + references/），管理员可以将其上传到 claude.ai / Claude desktop - 组织配置的技能会集中更新。输出是 **已标记的快照** （`compiled from repo@sha`），而不是第二个事实来源：每当合并后重新生成它。与评估工具的 `skill` 适配器往返通过相同的域名，因此相同的种子会评估仓库和编译的技能。MCP 仍然是实时、始终当前的路径；技能是到达的缓存。 ## 与 dbt 仓库保持同步 上下文在 dbt 模型在其下更改时就会过时 - 列名更改、指标重新定义、表删除 - 而过时的上下文比没有上下文更糟糕，因为代理信任它。免费的 CI 合同会捕获这一点：捆绑的 `context-drift` 工作流程在每个 PR 上标记上游 dbt 模型依赖的更改，以便人类重新确认定义。 Nodal 提供 **托管版本的循环**：连接您的 dbt 仓库，变更会在其中传播到业务上下文中 - 受影响的定义会从新的 dbt 源重新起草，并路由给分析师确认（仍然基于面试构建：人类拥有每个定义，同步只是保持草稿更新）。这基于 ACF 已经为每个领域保留的 `lineage:` 指针。这是 **企业级** （产品 #3）的一部分，可以在您的云/VPC 或我们的云/VPC 中部署 - [联系我们](mailto:info@nodaldata.io)。 ## 免费/付费线路，明确说明 | 功能 | 哪里 | 费用 | |---|---|---| | 上下文格式（ACF） | `SPEC.md`、`schemas/` | 免费，Apache-2.0 | | 面试技能（完整或快速通道） | `skills/context-interview/` | 免费 | | 评估种子收集（面试 → 标记对） | 技能 | 免费 | | 一次性评估增量（开/关，本地运行） | 工具包，自行运行 | 免费 | | 用于 Claude desktop 的编译技能快照 | `scripts/compile_skill.py` | 免费 | | 原始上下文文件的自托管代理 | 您的代理 | 免费 | | **团队共享的 MCP 端点（受管辖的答案，身份验证，日志记录，非技术编辑通过 PR）** | Nodal（托管） | **付费 - 自助服务** | | **dbt 仓库同步（dbt 更改重新起草到上下文中，分析师确认）** | Nodal（托管） | **付费 - 企业** | | **学习循环：可观察性，覆盖率评估，回归测试，漂移检测** | Nodal（托管） | **付费 - 企业** | **托管的 MCP 端点是自助服务的入口**：订阅，连接仓库，共享端点 - 几分钟，无需销售电话。**学习循环（可观察性，覆盖率评估，回归测试）和 dbt 仓库同步是企业级** - 它们是数据团队保持上下文正确的方式，并且在自助服务分析扩展时了解谁在问什么；要演示，需求或定价，**请联系我们** 在 info@nodaldata.io。了解更多信息，请访问 [nodaldata.io](https://nodaldata.io) 或 [docs.nodaldata.io](https://docs.nodaldata.io)。 ## 许可证 Apache-2.0（参见 `LICENSE`）。格式和面试属于您所有。