agami-core

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="plugins/agami/shared/agami-logo-dark.svg"> <img src="plugins/agami/shared/agami-logo-light.svg" alt="agami" width="240"> </picture> </p> <p align="center"><strong>人工智能与您的数据之间的信任层。本地运行。私有。属于您。</strong></p> <p align="center">_{<strong>agami-core</strong> — <a href="https://agami.ai">Agami</a> 的公平代码核心。}</p> <p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-fair--code-blue.svg" alt="许可证：fair-code"></a> <img src="https://img.shields.io/badge/version-0.3.3-blue" alt="版本"> <img src="https://img.shields.io/badge/status-pre--public-orange" alt="状态"> <a href="#快速开始-5分钟内"><img src="https://img.shields.io/badge/试用示例-无需数据库-brightgreen" alt="试用示例"></a> </p> <!-- HERO VISUAL: drop docs/assets/demo.gif (a ~10s sample-flow capture) and uncomment the line below. See docs/assets/README.md for what to capture. A visual is the highest-leverage addition here. --> <!-- <p align="center"><img src="docs/assets/demo.gif" alt="agami: a governed answer with its provenance receipt" width="760"></p> --> 将人工智能代理指向数据库，它会通过**猜测**来回答 - 猜测连接，猜测“收入”的含义，猜测它有权读取哪些行。**agami-core**是代理和您的数据之间的受控层：它将您的模式转换为语义模型，其中每个连接都是外键派生或人为批准的，每个指标都由名称和角色**签署**，每个答案都附有**收据** - 准确的SQL，它引用的模型版本，以及谁为每个定义提供了担保。规则存在于模型中，**而不是提示**中。而且所有这些都在您的机器上运行 - 凭证，模式和结果永远不会离开它。 ## 您获得什么 - ✅ **受控的答案，而不是猜测** - 每个连接都是外键派生或人为批准的；每个指标在运行时信任之前都由名称 + 角色签署。 - 🧾 **每个答案的收据** - 字面上的SQL，触摸的表，使用的关系和引用的模型版本。可复制，可审计。 - 🔒 **本地且私有** - 在Claude Code中通过Bash/Read/Write运行。凭证，模式和结果永远不会触摸我们运行的服务器。 - 🧩 **便携的语义模型** - 普通的，git原生的YAML您拥有（主题区域，表，实体，指标，关系）。没有锁定。 - 🗄️ **与您的数据库配合使用** - Postgres · Supabase · Redshift · MySQL · Snowflake · BigQuery · SQL Server · Oracle · Databricks · Trino · DuckDB · SQLite。 - 🛠️ **零基础设施** - 没有后端，没有代理。如果您有DB CLI，那么您拥有的一切；一个可选的本地MCP服务器允许Claude Desktop使用相同的模型。 ## 快速开始（5分钟内） ### 最快的方式 - 内置示例（无需数据库，无需凭证） agami附带**Acme Store**，一个小型本地SQLite数据集（商务 + 订阅）和一个现成的，已签署的语义模型。您在1分钟内获得一个受控的答案 - 附带完整的收据，而且没有任何东西离开您的机器。 ```bash # 1. 安装插件（请参阅下面的每台主机步骤）。 # 2. 试用示例 - 无需连接： /agami-connect sample # 或者直接说"I don't have a database" / "try the sample" # 3. 提出问题 - 查看强制执行的治理： 谁是按总支出计算的前5位客户？ # 4. 现在观察模型的构建 - 查看强制执行的治理： /agami-connect reintrospect ``` **步骤 3** 故意跨越一个 **扇形陷阱** （orders → line items → payments），一个朴素的代理会无声地进行双重计算。agami的预飞行检查会捕获它并返回正确的结果 *以及连接收据* - 信任层，在您的第一个查询中强制执行。 **步骤4是真正的重点。** 自然语言查询无处不在; 稀有的是 *信任从哪里来*。`reintrospect` 从实时模式中重新派生示例 - 反射 → 推断 + 置信度评分每个连接 → 门控指标签署 → 重新验证示例 - 因此您观察到受控模型成形，而不是仅仅消耗它。 要从头开始构建（完整的LLM丰富，描述等），请运行 `/agami-connect sample` 并选择 **“从头开始构建模型，以便我可以查看它的工作原理”**。无论哪种方式，都需要几分钟 - 这是演示 **收据** 您在步骤3中看到的内容是如何获得的。完整流程： [docs/usage.md](docs/usage.md)。 ### 真实数据库 当您准备好连接自己的数据库时： ```bash # 1. 运行connect - 选择您的DB类型，编写凭证模板（仅第一次运行） /agami-connect # 2. 填写模板，然后保存 + 锁定它 # （agami仅运行只读查询，因此如果可以，请使用只读DB用户） # 请agami获取“只读授权”以获取确切的GRANT SQL $EDITOR <artifacts_dir>/local/credentials.example mv <artifacts_dir>/local/credentials.example <artifacts_dir>/local/credentials chmod 600 <artifacts_dir>/local/credentials # 3. 重新运行connect以进行反射：构建语义模型 + 种子示例 /agami-connect # 4. 提出问题 我们上个月发货了多少订单？ ``` `/agami-connect` 是一个一站式服务：它拾取缺失的凭证，反射实时数据库到语义模型（表，列，PK粒度，FK关系，敏感列标志），分层LLM丰富，生成EXPLAIN验证的种子示例。验证门控； `git init` + 快照。 还有 `/agami-connect sample` 用于无DB示例。 完整流程： [docs/usage.md](docs/usage.md)。凭证按方言分类： [docs/credentials.md](docs/credentials.md)。 ## 安装 > **平台说明。** 在 **macOS和Linux**上验证。 在 **Windows**上，技能需要 **[Git for Windows](https://git-scm.com/downloads/win)** （Claude Code使用Git Bash作为其Bash工具）; Windows尚未完全验证到端点。 可选的本地MCP服务器是纯stdlib Python，并且是跨平台的。 相同的插件适用于Claude Code CLI，VS Code和Cursor。 **Claude Code CLI** - 在Claude Code中： ``` /plugin marketplace add AgamiAI/agami-core /plugin install agami-core@agami ``` 通过 `/plugin list` 验证 - 您应该看到 `agami-core@agami v0.3.3`。 **VS Code / Cursor** - 安装 **Claude Code** 扩展，输入 `/plugin` 打开 **Manage Plugins**，添加 `AgamiAI/agami-core` 市场，然后从插件选项卡安装 `agami-core`。 每台主机的演练： [docs/install/](docs/install/). ## 信任层 大多数AI数据代理悄悄选择一个连接，悄悄选择“收入”的定义，然后悄悄返回一个数字。agami使每个决定都可审计： - **每个条目的置信度和审查状态。** 每个连接，指标和实体都有一个平面信任块（`confidence`，`review_state`和批准身份） - 没有供应商大块，没有需要调整的分数。 DB声明的外键和结构列名称自动批准; 所有推断的内容保持 `unreviewed` 并在“审查”选项卡中显示。 - **指标必须签署（规则1）。** 指标需要批准者电子邮件，角色和非空 `calculation` 才能被运行时视为真实 - 一个坏指标会使所有使用它的报告偏斜。 连接和实体是惰性的（规则2）：在审查之前可以使用，收据上标记为未确认，直到确认。 - **每个答案都附带收据** - 字面上的SQL，表 + 行数，使用关系（带有置信度/状态），指标定义，作者 + 日期，数据新鲜度和模型快照哈希。如果使用任何未审查的条目，则会出现警告横幅。 没有内容被无声信任。 - **快照固定 + git原生。** 模型位于 `~/agami-artifacts/<profile>/` 下的YAML，首次反射时 `git init`。 每个答案记录模型快照哈希，以便旧答案完全重现，模式漂移将受影响的条目翻转为 `stale` 而不是无声更改数字。 完整的机制 - 信任块，规则1/规则2，审查队列，收据，示例验证： **[docs/trust-layer.md](docs/trust-layer.md)**。 ## 技能（斜杠命令） 自然语言短语会自动路由到每个技能 - “打开审查仪表盘” / “将此保存为更正” / “反射我的模式”全部有效，无需输入斜杠命令。 | 命令 | 它执行的操作 | |---|---| | `/agami-connect` | 一站式设置 + 反射：检测/收集凭证，反射实时DB到语义模型（表，列，PK粒度，FK关系，敏感列标志），分层LLM丰富，生成EXPLAIN验证的种子示例。 验证门控； `git init` + 快照。 还有 `/agami-connect sample` 用于无DB示例。 | | `/agami-query` | 回答自然语言问题：选择示例 + 关系，生成并运行SQL，格式化结果 + 图表，并显示出处收据。 标记它依赖的任何未审查的条目。 （通常您不输入这个 - 普通语言路由到这里。） | | `/agami-model` | 一个仪表盘，用于 **浏览，管理和签署** 模型：每个表/字段/指标/实体/连接，每个表的Exclude/Include，编辑，新指标。 **审查** 选项卡是信任层签署队列。 在队列上打开它 `/agami-model review`。 | | `/agami-save-correction` | 记录更正并将其路由到正确的位置（SQL示例，列元数据，显示首选项，业务概念或新指标），显示其分类，然后写入。 属性显示在它影响的未来答案中。 | | `/agami-reconcile` | 将其指向遗留仪表盘的CSV；它生成每个问题，通过agami运行它，并显示带有公差的并排差异。 验证您已经信任的模型。 | | `/agami-serve` | 从 **Claude Desktop** 应用程序使用agami：连接可选的本地MCP服务器（与托管连接器相同的工具，由您的本地模型 + 执行 - stdio，只读，无网络）。 参见 [docs/mcp-server.md](docs/mcp-server.md)。 | ## 隐私 agami完全在本地运行 - 凭证（`chmod 600`），语义模型，图表，导出和仪表盘都位于 `~/agami-artifacts/` 下，并且技能永远不会读取这些路径之外的文件（除了您的DB工具的身份验证配置，在连接时设置并获得您的许可）。 详情： [docs/privacy.md](docs/privacy.md)。 ## 公平代码与托管 agami是 **公平代码** （源代码可用）。 在您自己的机器上运行 - 反射，便携式语义模型，NL→SQL + 本地执行，信任层，更正和本地MCP服务器 - **免费为您的团队自托管**。 将数据或MCP暴露给您的组织外部人员是付费线路 - 团队云（多租户模型注册表，共享治理上下文，始终在线评估）。 边界，以清晰的语言陈述： [docs/open-vs-hosted.md](docs/open-vs-hosted.md)。 ## 自托管团队服务器 除了本地单人设置外，agami还附带一个 **HTTP MCP服务器**，以便团队可以指向一个共享的，受控模型。 它是云中立的（一个VM + Postgres，或一个无状态平台，如Cloud Run + 管理的Postgres），完全由环境变量配置，并且 **默认情况下LLM免费 + 无出口**。 完整的设置 - `pip install "agami-core[server]"`安装，env-var合同和可选的Google / Microsoft（OIDC）登录 - 在 **[docs/self-hosting.md](docs/self-hosting.md)**中。 对于一键部署包，请使用 `/agami-deploy`技能。 ## 文档 - [快速开始和用法](docs/usage.md) - 首次运行演练 + 常见工作流程 - [凭证](docs/credentials.md) - 每个方言，每个连接方法选择器 - [信任层](docs/trust-layer.md) - 置信度，签署，收据，快照 - [格式规范](docs/format-spec.md) - 语义模型布局 + 工作示例 - [MCP服务器](docs/mcp-server.md) - 从Claude Desktop使用agami - [自托管团队服务器](docs/self-hosting.md) - HTTP服务器，env-var合同，OIDC - [故障排除和卸载](docs/troubleshooting.md) - [公平代码与托管](docs/open-vs-hosted.md) · [隐私](docs/privacy.md) ## 贡献 问题和PR欢迎在 [github.com/AgamiAI/agami-core](https://github.com/AgamiAI/agami-core)上提出。 参见 [CONTRIBUTING.md](CONTRIBUTING.md)以获取测试命令和 **版本提升 纪律** - 每个用户可见的更改都需要 `.claude-plugin/marketplace.json`（两次）和 `plugins/agami/.claude-plugin/plugin.json`中的版本提升，否则现有安装将停留在缓存的旧版本。 值得注意的更改： [CHANGELOG.md](CHANGELOG.md)。 在推送之前，请使用 **`uv run dev.py check`** （ruff + 测试套件 + gitleaks - 与每个PR运行的CI相同的门控）本地运行检查。 一次性设置和完整命令列表在 [CONTRIBUTING.md](CONTRIBUTING.md)中； 编码和客户安全约定在 [CLAUDE.md](CLAUDE.md)中。 CI门控每个PR。 **如果agami对您有用，存储库上的⭐️可以帮助其他人找到它。** ## 许可证 **公平代码** （源代码可用） - Agami功能使用许可证。 参见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。 免费与付费（内部使用与外部暴露）的区别： [LICENSING.md](LICENSING.md)。 由 [Agami AI](https://agami.ai) 构建。