skaiea13-ai/contextloop

# ContextLoop **一个由 DataHub 驱动的 schema 变更事件代理，能够追踪影响范围、分配基于事实的操作，并将已批准的操作记忆写回 context graph。** ContextLoop 是为 [Build with DataHub: The Agent Hackathon](https://datahub.devpost.com/) 中的 **Agents That Do Real Work** 挑战赛而构建的。它将提议的列变更转化为一个可审计的五阶段循环： 1. 通过 DataHub 搜索验证选定资产，然后读取实时的 schema、所有权、文档和治理信号。 2. 查询最多三跳的列级下游血缘，构建有界影响投影，并使用 DataHub Agent Context Kit 检索先前相关的事件记忆。 3. 使用 ChatGPT 认证的 Codex runtime 对严重程度和有界风险因素进行分类。 4. 确定性地渲染证据，并将操作仅分配给 DataHub 中存在的所有者。 5. 在明确的人工批准后，保存一份事件记忆文档，并将其与有界影响集中的每个资产以及检索到的每份过往事件文档相关联。 不接收也不需要 OpenAI API 密钥。模型执行使用用户现有的 **Codex ChatGPT OAuth** 会话，并且后端会从每个模型子进程中移除 `OPENAI_API_KEY`。这避免了计费的 OpenAI API 费用；正常的 ChatGPT 套餐限制仍然适用。 ## 为什么它很重要 schema 变更在源头看起来可能毫无危害，但会在几跳之外的下游静默破坏语义模型、仪表板、指标和副本。仅仅依靠目录搜索无法弥合这一差距。ContextLoop 将 DataHub 的实时 context graph 与“操作与记忆”循环相结合，以便下一位工程师或 agent 能够继承证据、决策、所有者和回滚计划。 ## 演示中哪些是真实的 - DataHub OSS v1.6.0 在 Docker 中本地运行。 - 官方的 `showcase-ecommerce` 数据包提供了 schema、所有者、文档和血缘。 - `datahub-agent-context` 执行 `search`、`list_schema_fields`、`get_lineage`、`get_entities`、`search_documents`、`grep_documents` 和 `save_document` 操作。 - `analytics.order_details` 上选定的 `discount_amount` 列目前解析为跨 Looker、Power BI 和 Snowflake 的 10 个下游资产。 - 后端最多评估返回的前 10 个资产。画布渲染了以源为中心的星型投影（最多包含六个资产）以及溢出计数；它不会重构 DataHub 的多跳边缘拓扑。 - 模型调用仅在 `codex login status` 确认 `Logged in using ChatGPT` 后通过 `codex exec` 运行。 - 在用户点击 **Approve & write back to DataHub** 之前，回写操作将被阻止。 - 生成的 DataHub 文档与源资产、该有界影响集中的每个资产以及检索到的先前 ContextLoop 事件记忆相关联。 经过验证的 OAuth 运行中捕获的输出可在 [`examples/impact-analysis.json`](examples/impact-analysis.json) 中找到，确切的 DataHub 文档正文可在 [`examples/incident-memory.md`](examples/incident-memory.md) 中找到。 ## 架构 ``` flowchart LR U["Data engineer"] --> UI["React incident console"] UI --> API["FastAPI orchestrator"] API --> ACK["DataHub Agent Context Kit"] ACK --> DH["DataHub OSS context graph"] API --> CX["Codex CLI via ChatGPT OAuth"] DH --> ACK --> API CX --> API --> UI UI -->|"Explicit approval"| API API -->|"save_document"| ACK --> DH ``` 模型永远不会接收凭据或原始数据仓库数据。它接收的是 DataHub 元数据的紧凑、经过电子邮箱清洗的投影：请求的变更、精确的 schema 匹配、下游资产名称和平台、目录所有者显示名称、安全的治理信号，以及来自先前相关 ContextLoop 文档的有界摘录。目录文本被视为不受信任的数据，绝不作为指令。Codex 只能返回严重程度和有界的 risk-factor 枚举列表；服务器从已验证的 DataHub context 中推导所有包含实体的描述、计数、证据和所有者分配。 ## 前置条件 - macOS 或 Linux - Docker Desktop、Colima 或其他兼容 Docker 的 runtime，且至少有 8 GB 可用内存 - Python 3.11 和 [uv](https://docs.astral.sh/uv/) - Node.js 22+ - [DataHub CLI](https://docs.datahub.com/docs/quickstart/) - 使用 ChatGPT OAuth 登录的 [Codex CLI](https://developers.openai.com/codex/cli/) 在设置之前验证 OAuth： ``` codex login status ``` 输出必须包含 `Logged in using ChatGPT`。 ## 快速开始 ``` git clone https://github.com/skaiea13-ai/contextloop.git cd contextloop ./scripts/bootstrap.sh ./scripts/dev.sh ``` 打开 [http://127.0.0.1:5173](http://127.0.0.1:5173)。 引导脚本将： - 验证 ChatGPT OAuth 会话； - 在需要时启动 DataHub OSS Quickstart； - 使用 Quickstart 记录的本地凭据配置本地 DataHub CLI； - 加载官方的 `showcase-ecommerce` 数据包； - 安装锁定的 Python 和 Node 依赖项。 它不会创建、请求或存储 OpenAI API 密钥。 ### 免费评审模式 评委可以在没有 Codex 帐户或进行任何模型调用的情况下，演练真实的 DataHub 读取、血缘、接口、审批门禁和 `save_document` 回写操作： ``` CONTEXTLOOP_FAKE_CODEX=1 ./scripts/bootstrap.sh CONTEXTLOOP_FAKE_CODEX=1 ./scripts/dev.sh ``` 此模式带有明显的 **Fixture · no model call** 标签。它仅将推理响应替换为确定性的 fixture；DataHub 访问和回写保持真实状态。提交的演示视频和发布证据使用真实的 ChatGPT OAuth 路径。 ## 演示流程 1. 保留预先选定的 `analytics.order_details` 资产。 2. 选择 **Drop column**，输入 `discount_amount`，并保留 `PROD`。 3. 点击 **Run impact loop**。 4. 检查基于 DataHub 的影响投影、治理证据、先前记忆计数、业务影响和绑定所有者的操作。 5. 确认第五阶段显示 **Approval required**，并且 DataHub 尚未被修改。 6. 点击 **Approve & write back to DataHub**。 7. 跟随成功链接，并在 DataHub 中检查新的 Analysis 文档。 ## 仅限 OAuth 的模型边界 该实现特意不包含 API 提供商适配器。[`backend/contextloop/codex_auth.py`](backend/contextloop/codex_auth.py) 通过以下方式强制执行此边界： - 要求 `codex login status` 报告 ChatGPT OAuth； - 从子进程环境中移除 `OPENAI_API_KEY`； - 调用 `codex exec --ephemeral --ignore-user-config --ignore-rules --sandbox read-only`； - 使用严格的 JSON Schema 将响应限制为严重程度和有界的 risk-factor 枚举； - 拒绝意外的自由文本字段以及检索到的 context 不支持的风险因素； - 确定性地从 DataHub 推导所有计数和证据； - 在服务器端生成包含实体的操作文本，并仅分配给检索到的所有者，或者在不存在时分配明确的 `Unassigned` 状态。 确定性 fixture 仅通过 `CONTEXTLOOP_FAKE_CODEX=1` 启用，用于免费评审访问、单元测试和浏览器回归测试。它不进行模型调用，也不是产品的默认设置。 ## 验证 运行静态和自动化检查： ``` ./scripts/verify.sh ``` 运行发布门禁，其中包括实时的 OAuth 分析、显式的 DataHub 回写和精确的 SDK 重新查询验证： ``` ./scripts/verify_live.sh ``` 发布验证还包括在 1600×1000 和 390×844 分辨率下的浏览器 QA。 ## 仓库映射 ``` backend/contextloop/ FastAPI, Agent Context Kit, OAuth runner backend/tests/ OAuth-boundary and deterministic tests frontend/src/ React incident command center design/ Accepted visual concept docs/ Architecture and Devpost-ready materials examples/ Verified sample outputs scripts/ Bootstrap, development, and verification commands THIRD_PARTY_NOTICES.md Direct dependency and sample-data notices ``` ## 安全与隐私 - 切勿将 Codex、ChatGPT、DataHub 或 Devpost 凭据粘贴到此仓库中。 - 本地 DataHub token 保留在仓库之外的 DataHub CLI 用户配置中。 - Agent 接收来自公共样本包的元数据，而不是业务记录。 - 所有者电子邮件地址和不安全的结构化属性值被排除在模型 context 之外。 - 目录描述和先前的文档摘录被视为不受信任的数据。 - `codex exec` 是只读且临时的。 - 目录变更与模型推理分离，并且需要显式的 UI 操作。 ## 运行时模式 完整的模型支持体验是一个桌面本地演示，因为 OAuth 凭据是与用户绑定的。它使用操作员的 ChatGPT 认证的 Codex CLI 和本地 DataHub 实例。免费评审模式不需要 Codex 帐户，也不进行模型调用，同时保留了工作流程中真实的 DataHub 部分。无论哪种模式都不使用共享的 API 密钥或按量计费的 OpenAI API 后端。 ## 提交材料 - [Devpost 描述](docs/DEVPOST_DESCRIPTION.md) - [三分钟演示脚本](docs/DEMO_SCRIPT.md) - [官方需求清单](docs/SUBMISSION_CHECKLIST.md) - [官方需求矩阵](docs/REQUIREMENTS_MATRIX.md) - [发布验证证据](docs/RELEASE_EVIDENCE.md) - [架构与威胁边界](docs/ARCHITECTURE.md) - [设计规范](docs/DESIGN_SPEC.md) - [已有工作与 AI 披露](docs/DISCLOSURES.md) - [最终 Devpost 字段包](docs/FINAL_SUBMISSION.md) - [第三方声明](THIRD_PARTY_NOTICES.md) ## 许可证 Apache License 2.0。参见 [`LICENSE`](LICENSE)。

标签：DataHub, LLM Agent, MITM代理, 变更管理, 数据治理, 数据血缘, 请求拦截, 逆向工具