Ryan-AI-Studios/Ledgerful

# Ledgerful Ledgerful 是一个本地优先的 Rust CLI，用于变更智能和 Gemini 辅助开发。它将仓库的编辑转换为确定性的影响数据包、风险摘要、热点排名、有针对性的验证计划以及有界的 Gemini 上下文。 该工具旨在保持本地化并解释其工作原理。它不会作为自主编程 agent 运行。 Ledgerful：现有的 `ledgerful` 命令、hooks 和 `.ledgerful/` 状态目录将保持不变，继续工作。新安装的版本也会提供 `ledgerful` 及其短别名 `ldg`。 ## 安装说明 **Windows** (PowerShell): ``` iwr https://raw.githubusercontent.com/Ryan-AI-Studios/Ledgerful/main/install/install.ps1 -UseB | iex ``` **macOS 和 Linux**: ``` curl -fsSL https://raw.githubusercontent.com/Ryan-AI-Studios/Ledgerful/main/install/install.sh | sh ``` *（Homebrew 和 Apt 包即将推出）。* 从检出的代码库手动安装： ``` cargo install --path . ``` LSP daemon 位于一个可选功能之后： ``` cargo install --path . --features daemon ``` 有关安装程序选项、发布资产和 agent 引导说明，请参阅 [docs/installation.md](docs/installation.md)。 ## 快速入门 ``` ledgerful init ledgerful doctor ledgerful index ledgerful scan ledgerful impact ledgerful verify ledgerful hotspots ledgerful ask "What should I verify next?" ``` ## 命令 - `init`：创建 `.ledgerful/`、启动配置、启动规则以及 `.gitignore` 配置。 - `doctor`：报告平台、shell、path 和工具的健康状况。 - `index`：解析源代码以构建结构、entrypoint、call-graph、data-model、可观测性和语义向量索引。支持 SCIP 摄取。 - `scan`：总结暂存和未暂存的 git 变更。 - `watch`：将文件系统事件防抖处理为持久化的批次。 - `impact`：生成 `latest-impact.json`，包含符号、imports、runtime 使用情况、复杂度、时间耦合、热点、CI 预测和联邦影响。 - `verify`：使用结构影响、时间耦合、CI 预测和 Bayesian 失败概率排序来构建并运行确定性的验证计划。包含 `--explain` 用于 LLM 失败原因分析。 - `ask`：将经过清理的影响上下文发送给 Gemini 或本地 LLM。支持自然语言 `--semantic` 代码库搜索。 - `search`：通过 Tantivy trigrams 和排名 BM25 代码库查询进行亚毫秒级的正则表达式搜索。 - `hotspots`：按时间变更频率乘以复杂度对文件进行排名。 - `mcp`：运行 Model Context Protocol stdio 服务器以进行 AI agent 集成。 - `viz`：导出交互式 HTML Knowledge Graph 可视化，展示代码库依赖关系和风险热力图。 - `federate`：导出公共接口、扫描同级仓库，并显示已知的联邦链接。 - `ledger`：事务性架构内存（start、commit、rollback、audit、search、adr）。 - `daemon`：可选的 LSP 服务器，提供 diagnostics、Hover、CodeLens、陈旧数据处理和生命周期管理。 - `reset`：删除派生的本地状态。默认保留 `ledger.db`；使用 `--include-ledger` 删除出处数据。 - `demo`：生成一个包含真实签名 ledger 条目和 SOC2 证据导出的合成 invoice-service 仓库。完全离线运行，耗时约 15-30 秒；默认运行后清理（使用 `--keep` 进行检查）。 - `export evidence`：从 CLI 导出 SOC2 证据压缩包（与仪表板按钮导出的产物相同）。`--profile soc2 --out [--force]`。 ## 常见工作流 使用 first-parent git 历史记录生成影响报告： ``` ledgerful impact ``` 对于包含大量合并的仓库，包含所有父节点遍历： ``` ledgerful impact --all-parents ``` 运行预测性验证： ``` ledgerful verify ``` 禁用预测并使用仅限规则的验证： ``` ledgerful verify --no-predict ``` 检查风险热点： ``` ledgerful hotspots --limit 20 --commits 500 --dir src --lang rs ledgerful hotspots --json ``` 使用 Gemini 叙事报告： ``` ledgerful ask --narrative ``` 在首次标记的发布和 npm 发布之后，通过 兼容 MCP 的编程 agent 使用 Ledgerful： ``` npx @ledgerful/mcp-server ``` npm 包装器会下载带有校验和的 GitHub 发布二进制文件，并启动 `ledgerful mcp`。设置 `LEDGERFUL_MCP_BIN_OVERRIDE` 为本地二进制文件，以便在 开发或 CI 冒烟测试时使用。 在同级仓库之间使用联邦智能： ``` ledgerful federate export ledgerful federate scan ledgerful federate status ledgerful impact ``` 通过事务性出处跟踪变更： ``` # 在编辑前启动 transaction ledgerful ledger start src/main.rs --category FEATURE --message "Add auth module" # 在编辑和验证之后 ledgerful ledger commit --tx-id --summary "Added auth" --reason "API needs authentication" # 快速单文件更改 ledgerful ledger atomic src/config.rs --category REFACTOR --summary "Extract config validation" --reason "SRP" # 针对 docs 更改的轻量级 note ledgerful ledger note docs/api.md "Update endpoint docs" # 检查状态并调和 drift ledgerful ledger status ledgerful ledger reconcile --all --reason "Intentional local changes" # 搜索和审计 ledgerful ledger search "auth logic" --category FEATURE --days 30 ledgerful ledger audit --include-unaudited ledgerful ledger adr --output-dir docs/adr ``` ``` cargo run --features daemon -- daemon ``` ## 配置 Ledgerful 将仓库本地状态存储在 `.ledgerful/` 中。 - `.ledgerful/config.toml`：runtime 配置、watch 防抖、Gemini 超时/上下文、时间遍历、热点默认值以及 ledger 设置（强制执行、自动核对、验证门控）。 - `.ledgerful/rules.toml`：策略规则、受保护路径和所需的验证命令。 示例位于 [docs/examples/config.toml](docs/examples/config.toml)、[docs/examples/rules.toml](docs/examples/rules.toml) 和 [docs/examples/LEDGERFUL.md](docs/examples/LEDGERFUL.md) 中。 ## 报告和状态 生成的状态可重新构建，并始终保留在 `.ledgerful/` 内部。 - `.ledgerful/reports/latest-scan.json` - `.ledgerful/reports/latest-impact.json` - `.ledgerful/reports/latest-verify.json` - `.ledgerful/reports/fallback-impact.json` - `.ledgerful/state/ledger.db` - `.ledgerful/state/schema.json` - `.ledgerful/state/current-batch.json` 影响数据包在 SQLite 持久化之前会进行脱敏处理。Gemini prompts 在执行子进程之前会进行清理和截断。 ## Gemini Ledgerful 通过 shell 调用 `gemini` CLI。在使用 `ledgerful ask` 之前，请确保它已添加到 `PATH` 中。 - `GEMINI_API_KEY` 可以从进程环境或仓库本地的 `.env` 文件中提供。`.env` 会被 git 忽略；请使用 `.env.example` 作为模板。 - 默认情况下，日常的 `analyze`、`suggest` 和叙事请求使用 `gemini-3.1-flash-lite`，以降低延迟和成本。 - 高风险数据包和 `review-patch` 请求使用 `gemini-3.1-pro`，以获得更深度的推理和代码审查。 - 仅当您希望每个 ask 模式都使用同一个明确指定的模型时，才在 `.ledgerful/config.toml` 中设置 `gemini.model`。 - `--mode analyze`：爆炸半径和风险推理 - `--mode suggest`：针对性的验证建议 - `--mode review-patch`：带有实时 diff 上下文的补丁审查 - `--narrative`：由单个结构化 prompt 生成的资深架构师风险叙述 如果 Gemini 在影响数据包可用后失败，Ledgerful 将写入回退影响产物，或报告其失败的原因。 ## Windows / WSL - Windows 11 + PowerShell 是主要环境。 - 混合的 Windows/WSL 文件系统设置可能会更慢，并可能产生不同的工具可用性。 - 请在运行 Ledgerful 的环境中保持安装 `git` 和 `gemini`。 ## 架构 有关模块边界和当前数据流，请参阅 [docs/architecture.md](docs/architecture.md)。 ## 贡献 - 问题和设置帮助：[GitHub Discussions](https://github.com/Ryan-AI-Studios/Ledgerful/discussions)。 - Bug 报告：[GitHub Issues](https://github.com/Ryan-AI-Studios/Ledgerful/issues)。 - 安全报告：请参阅 [SECURITY.md](SECURITY.md) — 不要为安全漏洞提交公开的 issue。 - 保持变更在阶段内有界且确定。 - 在推送之前运行 `cargo fmt --check`、`cargo clippy --all-targets --all-features -- -D warnings` 和 `cargo test --all-features -j 1 -- --test-threads=1`。 ## 许可证 Ledgerful 是在 [PolyForm Noncommercial License 1.0.0](LICENSE) 下提供的源码可用软件，并在 [COMMERCIAL-EXCEPTION.md](COMMERCIAL-EXCEPTION.md) 中为符合条件的小型实体提供了额外许可。 必需声明：版权所有 2026 Ledgerful, LLC；额外许可已在 COMMERCIAL-EXCEPTION.md 中说明。

标签：可视化界面, 通知系统