prov_ledger

# 🧾 provLedger    **您的管道已退出 0，且每一步都正常 — provLedger 是检查**数据**是否真正兑现承诺的层级。** 它为数据科学家的编码代理提供了一个计划到验证更改的审计轨迹，并将您的数据模式视为合同而非假设。  *(更喜欢终端吗？相同的弧线作为 CLI 记录： [silent-class-drop.gif](docs/media/silent-class-drop.gif)。)* **它捕获的内容** — 今天，这个仓库中的代码验证了以下每个内容： - **无声删除或重新输入上游列。** 作业仍然退出 0；声明的意图与运行时实际检查标志 `column_dropped` / `dtype_changed` 在错误的数据到达之前。上面的 GIF 就是这样 — 使用 `make demo` 复制它（分段纯度 0.31 vs 0.91）。 - **数据泄露。** 在具有相同血统根的数据上拟合和评估的模型，如果没有正确的训练/测试分割，则由状态图的泄露门标记为错误。 - **退化输出。** 标签列折叠为单个值（`cardinality_collapse` — “模型预测所有零”类）或空值分数激增通过运行时分析 + 漂移检测捕获。 每个捕获和关于它的LLM决定都**记录** — 到一个决策账本中，该账本会模糊匹配到下一个计划中，这样相同的错误不会重复。 | Live task tracking (plan + steps + data panel) | Pipeline dataflow, understood from the code | |---|---| |  |  | --- ## 🕐 2分钟试用 从一个新的克隆，没有服务，没有外部数据： ```bash git clone https://github.com/yizhao95/prov_ledger.git cd prov_ledger make demo ``` 这会离线且确定性地运行整个弧线（种子 42）：v1 假成功 → **不匹配** → 记录的决定 → 计划通过骨干网修订 → v2 **已验证**。然后在只读仪表板中重放它： ```bash ORCH_DB=$PWD/examples/silent-class-drop/demo-orchestrator.db \ bash orchestrator-webapp/launch_dashboard.sh # → http://127.0.0.1:8765 ``` 在 [`examples/silent-class-drop/`](examples/silent-class-drop/) 中查看演示文案以及如何再生媒体。 --- ## 📜 您的数据模式是一份合同 这是差异化的想法。通用代理框架验证**代码**运行；provLedger 还验证**数据**是否符合计划所述： - 一步声明一个数据**意图**（必需列 + dtypes）。运行时**实际**从实际记录中剖析（`data_profile`），并检测与声明的意图之间的漂移 — 删除的列，dtype 翻转，空值激增，基数崩溃 — 机械地，而不是通过询问 LLM 来通知。 - 一个 DataFrame 生成函数的“签名”是其列集 + 每列 dtypes，作为 typed `data_var` 节点与 `produces`/`consumes` 边在代码/数据图中持有 - 所以 *“更改输出类型 → 谁会破坏？”* 是一个查找。 --- ## ★ 目标 一个数据科学家的代理，思考方式更像一个严谨的工程师，而不是粗心的编码员 — **而不失去数据科学的直觉。** > *"我的编码代理应该在每种情况下都拥有完整的推理链 — 从不重复过去的错误。* - **一半 1 — 完整的推理链在范围内。** 在编写代码之前，代理应该知道哪些模块/函数/变量/DataFrame 列更改了；主管道如何受到影响；添加、删除或修改了什么；以及上游和下游必须如何更改。 - **一半 2 — 永不重复错误（账本）。** 过去的决定和失败的 provenance 账本，通过模糊匹配在计划时搜索。它的第一个真正的工作是数据工程决策记忆 — 例如 *“这是时间序列分割，所以我们使用滚动窗口，而不是随机分割 — 随机分割会泄露时间信息。”* --- ## 1 · 两个支柱，一个数据库学科 ```mermaid flowchart LR subgraph A[Pillar A · Orchestrator] WP[writing-plans] --> EX[executing-plans] end subgraph B[Pillar B · Project State Graph] AN[analyzers] --> G[(state-graph.db)] G --> RV[update-project-state-graph<br/>contract gates] end DB[(orchestrator.db<br/>plans · steps · data_profile<br/>llm_decisions · ledger)] WP -- publish plan --> DB EX -- log + profile --> DB G -- impact / review --> WP RV -- close gate --> EX DASH[read-only dashboard] -.reads.-> DB ``` 两个独立的有用子系统共享**一个理念**和**一个 SQLite 存储**。 | | Pillar | Records | |---|---|---| | **A** | **Orchestrator** — 计划/步骤状态机 | WHAT WAS DONE | | **B** | **Project State Graph** — 构建者 + 审查者 | WHAT THE CODE & DATA ARE | | **→** | **Result** | Auditable chain + contract safety net — reasoning captured, breakage blocked | **支柱 A — Orchestrator.** SQLite 支持的计划/步骤状态机由两个铁律技能（`writing-plans`，`executing-plans`）驱动。LLM 编写计划并调用薄壳包装器；Python + SQL 主干验证每个转换，强制执行断路器，并捕获日志。相同的主干承载数据优先的运行时循环：`profiler`（运行时实际）→ `drift`（与声明的意图相比）→ `data_loop`（决策 → 通过主干修复 → 重新验证）。 **支柱 B — 项目状态图.** 一个两层的存储库映射：一个由分析器（Python via AST；JS / HTML / CSS 结构通过 tree-sitter）构建的深 SQLite 节点/边图，以及一个人类可读的 `ARCHITECTURE.md`。一个配套审查器（`update-project-state-graph`）在关闭时检查每个更改与图的冲突 — 代码合同 **和** 数据合同。 🔗 **它们如何连接：** 图在两个时刻被读取 — 一次在**计划时**（预测影响，包括上游数据假设）和一次在**审查时**（验证没有损坏）。相同的图，相同的预计算卡，两个时间戳。 --- ## 2 · 核心哲学 — 确定性骨干 × LLM 决策层 LLM 代理漂移：它们忘记记录输出，忘记标记步骤完成，猜测错误的下游更改会影响，以及 — 对于数据科学家来说尤其 — 无声地损坏模式或分割。解决方法是将**所有确定性**内容分离到 Python + SQL 主干中，只留下真正的决策交给 LLM。 | Layer | Owns | |---|---| | **LLM decides** | 下一步骤 · 哪些符号/列影响 · 如何编写代码 · 是否需要偏差 · 如何处理数据漂移 | | **Backbone records / enforces** | 状态转换 · 断路器 · 日志捕获 · AST 依赖边 · 代码和数据合同门 · 运行时数据分析 + 漂移检测 · 计划关闭 | **规则：** *骨干网强制执行的每个不变性都是 LLM 永远不会意外违反的。* LLM 可以创造；骨干网不能。 只有一个**写入路径**：人类向代理提供自然语言反馈，代理的更改通过 `writing-plans` → `executing-plans`，每次都带有相同的测试、断路器和合同门。没有任何内容 — 包括仪表板 — 直接写入数据库。 🔬 **这是为什么这是数据科学形状的版本：** 软件工程师的代理不能破坏调用图。数据科学家的代理不能破坏调用图 **和** 不能无声地损坏列模式、训练/测试分割或上游表假设。 --- ## 3 · 任务生命周期 一个影响注册项目的状态更改任务，端到端： | # | Phase | Owner | What happens | |---|---|---|---| | 1 | 意图分类 | Orchestrator | `STATE_ALTERING` 或 `STATELESS`？ Email/docs 跳过重路径。 | | 2 | 预飞行 + 计划 | `writing-plans` | 拉取影响以获取触及的符号/列 + 上游数据假设；模糊匹配账本以获取相关过去的决定；发布计划 + 步骤 + 审查步骤。 | | 3 | 执行 | `executing-plans` | 每个步骤都通过薄包装器运行；`run-step.sh` 原子捕获 stdout/stderr + 真实退出代码。 | | 4 | 公园 | Orchestrator | 所有步骤终端 → 计划在触及注册项目时停在 `NEEDS_REVIEW`。 | | 5 | 审查 | `update-project-state-graph` | 与图进行差异比较 → 代码和数据合同门。清理 → 刷新 + 重试 + 关闭。损坏 → 失败，报告，人类决定。 | --- ## 🧬 起源和归属 两个编排技能 — **`writing-plans`** 和 **`executing-plans`** — 源自 [Superpowers](https://github.com/obra/superpowers) 技能库，由 Jesse Vincent（obra）修改。原始的 Superpowers 技能建立了计划-执行纪律和“薄壳包装器 + 确定性骨干”哲学。该存储库在此基础上构建。 ### 这个项目在原始 Superpowers 技能的基础上添加了什么 - **SQLite 支持的编排器** (`orchestrator-backend/` — 计划/步骤状态机不再是临时 markdown；每个转换都经过验证并在具有迁移、断路器和不可变 `COMPLETED` 步骤的真实数据库中持久化。 - **强制日志捕获** — `run-step.sh` 原子记录 stdout/stderr 和**真实**退出代码（针对 `PIPESTATUS` 伪装加固）。 - **第二个支柱 — 项目状态图** (`project-state-graph` + `update-project-state-graph`) — 一个深层节点/边代码图和一个审查器，它对 **代码合同和数据合同** 进行门控。 - **数据作为一流公民建模** — 函数的输出是一个 typed `data_var`，具有 `produces` / `consumes` 边，将 *"更改输出类型 → 谁会破坏？”* 变成一个查找。 - **DataFrame 感知合同** — DataFrame 生成函数的“签名”是其列集 + 每列 dtypes；检测到删除/重命名/重新输入的列。 - **运行时数据分析 + 漂移检测** (`profiler` / `drift` / `data_loop`) — 声明的意图在运行时与剖析的实际检查；漂移驱动记录的决策循环（参见演示）。 - **图中的无声失败门** — 数据泄露检测（相同行血统拟合 + eval 无正确分割 → 错误）和无防护模型输入警告。 - **计划时影响预飞行** (`impact_preflight.py`) — 计划附带的正向影响分析（声明的目标，上游假设，能力边界）。 --- ## 4 · 优势 - **经过战斗测试的不变量** — 断路器，不可变的 `COMPLETED` 步骤和强制日志捕获，经受住真实事件的考验。被 15 多个团队的工程师内部使用。 - **数据作为一流公民** — typed `data_var` 节点具有 `produces`/`consumes` 边，运行时配置文件和漂移驱动的决策记录。 - **卡片，而不是遍历** — 每个可调用的 `consistency_card`s 纯粹从边计算，所以 LLM 进行一次检索而不是图遍历。 - **报告，不要自动修复** — 审查者确定性地检测到损坏但从不修复；人类决定。 - **通用属性图模式** — 添加新的节点/边词汇（SQL，API，ML，DE）无需迁移。 - **只读可观察性** — 仪表板以只读方式读取相同的数据库；编排器永远不依赖它。 --- ## 👥 适用人群 **适用于：** 运行对真实管道的编码代理的数据科学家和 ML 工程师，其中“脚本退出 0”并不意味着“数字正确”。 **不适用于：** 通用代理编排。如果您的代理永远不触及数据集、模式或训练/测试分割，更轻量的框架将更好地为您服务。 --- ## 📦 仓库布局 ``` prov_ledger/ ├── .claude-plugin/ # plugin.json + marketplace.json （一键安装） ├── hooks/ # SessionStart hook → 异步依赖引导 ├── commands/ # /provledger-dashboard 斜杠命令 ├── scripts/ # bootstrap.sh, pl-python, smoke_install.sh ├── requirements.txt # 统一依赖集 ├── Makefile # `make demo` — 无声分类器演练 ├── examples/ │ └── silent-class-drop/ # 离线，确定性演示（参见其 README） ├── orchestrator-backend/ # 支柱 A — SQLite 计划/步骤状态机（仅限标准库） │ ├── orchestrator/ # api.py, db.py, state_machine.py, circuit_breakers.py, │ │ # profiler.py, drift.py, data_loop.py, telemetry.py │ ├── migrations/ # 001..013 SQL 迁移 │ └── tests/ ├── orchestrator-webapp/ # Live 只读 provLedger 仪表板（FastAPI + HTMX） │ └── app/ # main.py, queries.py, templates/ ├── orchestrator-cli.py # CLI 入口点 ├── docs/ # 媒体 + 完整架构 / 参考 / 指南文档 └── skills/ ├── writing-plans/ # ← 源自 Superpowers ├── executing-plans/ # ← 源自 Superpowers ├── project-state-graph/ # 支柱 B — 深度代码/数据图构建器 ├── update-project-state-graph/# 支柱 B — 审查者 / 合同门控 ├── brainstorming/ # 支持过程技能（本地适配） ├── systematic-debugging/ ├── test-driven-development/ └── subagent-driven-development/ ``` > `superpowers` 插件是推荐的配套：byte-identical > `verification-before-completion` 技能不捆绑，并且由 > superpowers 提供时提供。 --- ## 📚 文档 本 README 是高级别的入口点。完整的存储库文档树在 `docs/` 下： | 区域 | 路径 | 涵盖 | |---|---|---| | **架构** | `docs/architecture/` | 两个支柱，骨干网 × LLM 层，数据流，仪表板，技能层 | | **参考** | `docs/reference/` | 数据模型（迁移 001–013），状态机，API，CLI，图模式，脚本 | | **指南** | `docs/guides/` | 安装，端到端任务生命周期，仪表板，账本 | | **开发** | `docs/development/` | 测试，验证流程，迁移，贡献 | 从 `docs/README.md` 开始。设计、审计和计划记录在 `docs/superpowers/` 下实时构建。 ## 🚀 安装 ### 推荐 — 作为 Claude Code 插件（一步安装） ```text /plugin marketplace add yizhao95/prov_ledger /plugin install provledger@provledger` ``` 依赖项在第一个会话时自行安装：后台 `SessionStart` 引导程序构建 **一个** venv 在 `~/skill-workspace/.venv`（覆盖 `PROVLEDGER_VENV`）并安装 `requirements.txt`。它是幂等的 — 暖会话是 no-op。启动审查仪表板随时使用 **`/provledger-dashboard`**。 > **配套（推荐）：** 安装 > [`superpowers`](https://github.com/obra/superpowers) 插件以获取完整的技能集。 > provLedger 仅包含其演化和新颖的技能 > (`writing-plans`，`executing-plans`, > `project-state-graph`， > `update-project-state-graph`，以及本地适配的 > `brainstorming`， > `systematic-debugging`， > `test-driven-development`， > `subagent-driven-development`)，并将 superpowers 视为**软依赖**： > 字节相同的`verification-before-completion`技能不捆绑， > 由 superpowers 提供。 ### 手动/开发安装 参见 **[INSTALL.md](INSTALL.md)** 获取完整指南。快速开始： ```bash # 1. 克隆 git clone git@github.com:yizhao95/prov_ledger.git cd prov_ledger # 2. 将依赖项引导到统一的 venv（幂等） bash scripts/bootstrap.sh PY=~/skill-workspace/.venv/bin/python # 3. 运行测试套件以确认健康安装（分别运行每个套件 — # 每个套件都有自己的 pyproject/pythonpath；一次合并调用会破坏） $PY -M pytest orchestrator-backend -q $PY -M pytest orchestrator-webapp -q $PY -M pytest skills/writing-plans/tests -q $PY -M pytest skills/executing-plans -q $PY -M pytest skills/project-state-graph/scripts/tests -q $PY -M pytest skills/update-project-state-graph/scripts/tests -q # 4. 启动仪表板 PROVLEDGER_WEBAPP_DIR=orchestrator-webapp bash orchestrator-webapp/launch_dashboard.sh # → 打开 http://127.0.0.1:8765 ``` 仪表板以**只读**方式读取编排器数据库。 使用 `ORCH_DB` 环境变量将其指向任何编排器数据库（默认为 `~/skill-workspace/orchestrator.db`）。 --- ## 🤝 贡献 问题和 PR 欢迎。良好的第一份贡献：运行 `make demo` 并报告任何不重现的内容；为 `orchestrator/drift.py` 添加漂移类型（带有测试）；使用 `skills/project-state-graph/` 中的分析器扩展演示文案；改进 dtype 覆盖率。 ## 📫 联系方式 维护者：**yzhao950213@gmail.com** ## 📄 许可 MIT — 参见 [LICENSE](LICENSE)。