q-ring

="center"> <img src="https://unpkg.com/@i4ctime/q-ring@latest/assets/social-card-optimized.jpg" alt="q-ring logo" width="100%" /> </div> # q-ring **首款专为 AI 编程代理设计的量子启发式钥匙环。** [](https://www.npmjs.com/package/@i4ctime/q-ring) [](https://qring.i4c.studio/docs) [](https://glama.ai/mcp/servers/I4cTime/quantum_ring) [](https://github.com/I4cTime/quantum_ring/blob/main/LICENSE) <a href="https://glama.ai/mcp/servers/I4cTime/quantum_ring"> <img src="https://glama.ai/mservers/I4cTime/quantum_ring/card.svg" alt="quantum_ring MCP width="400" /> </a> 停止将 API 密钥粘贴到纯文本 `.env` 文件中，或与笨重的秘密管理器搏斗。 **q-ring** 将您的凭证安全地在操作系统的原生保险箱（macOS 钥匙串，Linux 秘密服务，Windows 凭证保险箱）中，并通过量子物理机制增强它们。 > 📖 **[查看官方文档](https://qring.i4c.studio/docs)** 以获取完整的 CLI 参考、MCP 提示手册和架构详细信息。 ### 为什么选择 q-ring？ - **叠加态：** 存储一个具有多个状态的密钥（开发/预发布/生产），这些状态根据上下文折叠。 - **纠缠：** 跨项目链接密钥，这样旋转一个密钥会自动更新所有密钥。 - **隧道效应：** 创建短暂的内存中的秘密，它们在设定的时间或读取次数后自我销毁。 - **传送：** 安全地打包和分享使用 AES-256-GCM 加密的秘密包。 - **与 AI 无缝集成：** 44 个内置 MCP 工具，可在 **Cursor**、**Kiro** 和 **Claude Code** 中原生使用。 ## 🚀 安装 q-ring 设计为全局安装，以便在终端的任何地方都可用。请选择您喜欢的包管理器： ```bash # pnpm（推荐） pnpm add -g @i4ctime/q-ring # npm npm install -g @i4ctime/q-ring # yarn yarn global add @i4ctime/q-ring # Homebrew（macOS / Linux） brew install i4ctime/tap/qring ``` ### Docker（MCP 服务器） 存储库提供了一个 `Dockerfile`，它构建 MCP 服务器并通过 [`mcp-proxy`](https://github.com/punkpeye/mcp-proxy) 暴露它 - 可用于托管 MCP 部署（例如 Glama）或将服务器完全保持在主机之外： ```bash git clone https://github.com/I4cTime/quantum_ring.git cd quantum_ring docker build -t qring-mcp . docker run --rm -p 8080:8080 qring-mcp ``` > 注意：容器内没有操作系统密钥链（GNOME 密钥环 / macOS 密钥链），因此此路径适用于 MCP 协议表面、临时使用和 CI 实验 - 而不是用于持久的本地秘密存储。对于日常使用，请通过上述包管理器之一原生安装 CLI。 ## ⚡ 快速入门 ```bash # 1️⃣ 存储秘密（如果省略值，则安全提示） qring set OPENAI_API_KEY sk-... # 2️⃣ 随时检索它 qring get OPENAI_API_KEY # 3️⃣ 列出所有密钥（永远不会显示值） qring list # 4️⃣ 生成加密秘密并保存它 qring generate --format api-key --prefix "sk-" --save MY_KEY # 5️⃣ 运行完整健康扫描 qring health # 有问题吗？诊断安装（密钥环，审计，MCP 连线） qring doctor # 为您的 shell 启用 tab 补全 qring completion zsh > ~/.zsh/completions/_qring # 另有：bash，fish ``` ## 量子特性 ### 态 - 一个密钥，多环境 单个秘密可以同时保存开发、预发布和生产的不同值。正确的值根据当前上下文解析。 ```bash # 设置环境特定值 qring set API_KEY "sk-dev-123" --env dev qring set API_KEY "sk-stg-456" --env staging qring set API_KEY "sk-prod-789" --env prod # 值根据上下文解析 QRING_ENV=prod qring get API_KEY # → sk-prod-789 QRING_ENV=dev qring get API_KEY # → sk-dev-123 # 检查量子态 qring inspect API_KEY ``` ### 波函数坍缩 - 智能环境检测 q-ring 在没有显式标志的情况下自动检测环境。解析顺序： 1. `--env` 标志 2. `QRING_ENV` 环境变量 3. `NODE_ENV` 环境变量 4. Git 分支启发式（`main`/`master` → 生产，`develop` → 开发） 5. `.q-ring.json` 项目配置 6. 秘密的默认环境 ```bash # 查看 q-ring 检测到的环境 qring env # 项目配置（.q-ring.json） echo '{"env": "staging", "branchMap": {"release/*": "staging"}}' > .q-ring.json ``` ### 量子衰减 - 具有 TTL 的秘密 秘密可以有生存时间。过期的秘密被阻止读取。过期秘密（寿命的 75% 以上）触发警告。 ```bash # 设置 1 小时后过期的秘密 qring set SESSION_TOKEN "tok-..." --ttl 3600 # 设置显式过期时间 qring set CERT_KEY "..." --expires "2026-06-01T00:00:00Z" # 健康检查显示衰减状态 qring health ``` ### 观察者效应 - 审计一切 每次读取、写入和删除秘密都会记录，并带有篡改证据的哈希链。访问模式被跟踪以检测异常。 ```bash # 查看审计日志 qring audit qring audit --key OPENAI_KEY --limit 50 # 检测异常（突发访问，不寻常时间，链篡改） qring audit --anomalies # 验证审计链完整性 qring audit:verify # 导出审计日志 qring audit:export --format json --since 2026-03-01 qring audit:export csv --output audit-report.csv ``` ### - 秘密生成 生成常见格式的强加密秘密。 ```bash qring generate # API 密钥（默认） qring generate --format password -l 32 # 强密码 qring generate --format uuid # UUID v4 qring generate --format token # Base64url 令牌 qring generate --format hex -l 64 64 字节十六进制 qring generate --format api-key --prefix "sk-live-" --save STRIPE_KEY ``` ### 纠缠 - 链接秘密跨项目的秘密。当您旋转一个时，所有纠缠的副本都会自动更新。 ```bash # 纠缠两个秘密 qring entangle API_KEY API_KEY_BACKUP # 现在更新 API_KEY 也会更新 API_KEY_BACKUP qring set API_KEY "new-value" # 解开纠缠的秘密 qring disentangle API_KEY API_KEY_BACKUP ``` ### 隧道效应 - 短暂的秘密 创建仅在内存中存在的秘密。它们永远不会接触磁盘。可选的 TTL 和最大读取自我销毁。 ```bash # 创建短暂秘密（返回隧道 ID） qring tunnel create "temporary-token-xyz" --ttl 300 --max-reads 1 # 读取它（读取后自我销毁） qring tunnel read tun_abc123 # 列出活动隧道 qring tunnel list ``` ### 传送 - 加密共享 将秘密打包成 AES-256-GCM 加密包，以便在机器之间安全传输。密钥由您的口令短语派生，使用 PBKDF2-HMAC-SHA512（210,000 次迭代）；每个包都记录其迭代计数，因此旧版本生成的包仍然可以解包。 ```bash # 打包秘密输入口令短语） qring teleport pack --keys "API_KEY,DB_PASS" > bundle.txt # 在另一台：解包（提示输入口令短语） cat bundle.txt | qring teleport unpack # 预览而不导入 qring teleport unpack <bundle> --dry-run ``` ### 导入 - 批量秘密摄入 直接从 `.env` 文件将秘密导入 q-ring。支持标准 dotenv 语法，包括注释、引用的值和转义序列。CLI 接受文件路径或原始内容；`import_dotenv` MCP 工具仅接受原始内容（它从不读取磁盘文件），因此代理无法强制它读取任意本地文件。 ```bash # 从 .env 文件导入所有秘密 qring import .env # 导入到项目范围，跳过现有密钥 qring import .env --project --skip-existing # 预览将要导入的内容 qring import .env --dry-run ``` ### 选择性导出 仅导出您需要的秘密，使用密钥名称或标签过滤器。 ```bash # 导出特定密钥 qring export --keys "API_KEY,DB_PASS,REDIS_URL" # 按标签qring export --backend" # 结合格式 qring export --keys "API_KEY_PASS" --format``` ### 秘密搜索和过滤 按过期状态或密钥模式过滤 `qring list` 输出。 ```bash # 按标签过滤 qring list --tag backend # 仅显示已过期秘密 qring list --expired # 仅显示过期秘密（寿命的 75% 以上） qring list --stale # 密钥名称上的 glob qring list --filter "API_*" # 友好性检查（存在时退出 0，不存在时退出 1；衰减感知） qring has OPENAI_API_KEY --quiet && echo "configured" ``` ### 项目秘密清单 在 `.q-ring.json`所需的秘密，并使用单个命令验证情况。 ```# 验证项目秘密与清单 qring check # 查看哪些秘密缺失、过期或陈旧 qring check --project-path /path/to/project ``` ### 环境文件同步 从项目清单中生成 `.env` 文件，根据环境感知叠加态解析每个密钥。 ```bash # 输出到 stdout qring env # qring env --output .env # 强制特定qring env:env staging --output .env.staging ``` ### 秘密有效性验证 测试秘密是否确实对目标服务有效。q-ring 从密钥前缀（`sk-` → OpenAI，`ghp_` → GitHub 等）自动检测提供者或接受显式提供者名称。 ```bash # 验证单个秘密 qring validate OPENAI_API_KEY # 强制特定提供者 qring validate SOME_KEY --provider stripe # 验证所有具有可检测秘密 q --all #验证清单中秘密 qring validate --all --manifest 出可用提供qring validate --viders ``` 提供者：** OpenAI、Stripe、GitHub、AWS（格式检查）、Generic HTTP。 输出： ``` ✓ OPENAI_API_KEY 有效 （openai，342ms） ✗ STRIPE_KEY 无效 （stripe，128ms）— API 密钥已被撤销 ⚠ AWS_ACCESS_KEY 错误 （aws，10002ms）— 网络超时 ○ DATABASE_URL 未知 — 未检测到提供者 ``` ### 钩子 - 秘密更改回调 注册在秘密创建、更新或删除时触发的 webhook、shell 命令或进程信号。支持密钥匹配、glob 模式、标签过滤和范围约束。 ```bash # 在更改秘密时运行 shell 命令 qring hook add --key DB_PASS --exec "docker restart app" # 在任何写入/删除操作上发送 POST 到 webhook qring hook add --key API_KEY --url "https://hooks.example.com/rotate" # 触发所有标记为“backend”的秘密 qring hook add --tag backend --exec "pm2 restart all" # 在 DB 秘密更改时向进程发送信号 qring hook add --key-pattern "DB_*" --signal-target "node" # 列出所有钩子 qring hook list # 删除钩子 qring hook remove <id> # 启用/禁用 qring hook enable <id> qring hook disable <id> # 干燥运行测试钩子 qring hook test <id> ``` 钩子是即发即忘的：失败的钩子永远不会阻塞秘密操作。钩子注册表存储在 `~/.config/q-ring/hooks.json`。 **SSRF 保护：** 默认阻止针对私有/环回 IP 范围（`127.0.0.0/8`、`10.0.0/8`、`172.16.0.0/12`、`192.168.0.0/16`、`169.254.0.0/16`、`::1`00::/7`） 的 HTTP webhook URL。DNS 在连接前和连接时都会被检查，因此主机名无法通过在套接字打开之前重新绑定到私有地址。要允许针对钩子（例如在开发过程中），请设置环境变量 `Q_RING_ALLOW_PRIVATE_HOOKS=1`。 ### 可配置轮换 秘密设置轮换格式，以便代理自动轮换正确的值形状。 ```# 存储具有轮换格式元数据的秘密 qring set STRIPE_KEY "sk --rotation-format api-key --rotation-prefix "" # 存储具有密码轮换格式的密码 qring set DB_PASS "..." --rotation-format password ``` ### 安全执行和自动编辑 运行带有安全注入到环境中的秘密的命令。所有已知的秘密值都会自动从 stdout 和 stderr 中编辑，以防止泄漏到终端日志或代理记录中。执行配置文件限制可以运行哪些命令。 ```bash # 执行带有注入秘密的部署脚本 qring exec -- npm run deploy # 仅注入特定标签 qring exec --tags backend -- node server.js # 使用受限配置文件运行（阻止 curl/wget/ssh，30 秒超时） qring exec --profile restricted -- npm test ``` ### 代码库秘密扫描器 迁移旧代码库？使用正则表达式启发式和香农熵分析快速扫描目录中的硬编码凭证。 ```bash # 扫描当前目录 qring scan . ``` 输出： ``` ✗ src/db/connection.js:12 密钥： DB_PASSWORD 熵：4.23 上下文：const DB_PASSWORD = "..." ``` ### 复合/模板秘密 存储动态解析其他秘密的复杂连接字符串。如果 `DB_PASS` 轮换，`DB_URL` 会自动正确而无需手动更新。 ```bash qring set DB_USER "admin" qring set DB_PASS "supersecret" qring set DB_URL "postgres://{{DB_USER}}:{{DB_PASS}}@localhost/mydb" # 自动解析嵌入式模板ring get DB_URL # 输出：postgres://admin:supersecret@localhost/mydb ``` ### 用户审批（零信任代理） 通过显式用户审批，保护秘密不被 MCP读取。每个审批令牌都经过 HMAC 验证、范围限定、理由验证和时限。权限适用于批量读取export_secrets` 和 `teleport_pack` 通过 MCP 跳的密钥，而这些密钥缺乏有效的授权bash # 标记秘密需要审批 set PROD_DB_URL "..." --requires-approval # 临时授予 MCP 访问 1 小时并有理由 qring approve PROD_DB_URL --for 3600 --reason "deploying v2.0 列出所有审批状态 qring approvals #审批 qring approve PROD --revoke ``` ### 即时（JIT）供应 不要存储静态凭证，配置 `q-ring` 在需要时动态生成短期令牌（例如 AWS STS，通用 HTTP 端点）。 ```bash # 存储 STS 角色配置 qring set AWS_TEMP_KEYS '{"roleArn":"arn:aws:iam::123:Role", "durationSeconds0}' --jit-provider aws-st# 解析秘密会自动承担角色并令牌 qring get AWS ``` ### AI 代理的项目上下文 密、安全性和状态编辑后的概述。设计用于在不暴露机密值的情况下将其馈 AI 代理的系统提示中。 ```bash # 人类可读 qring context # JSON 输出（用于 MCP / 程序使用） context --json ``` ### 机 Linter 扫描特定文件中的硬编码机密，带有可选的自动修复功能。当使用 `--fix` 时，机密将替换为 `.KEY` 引用并存储在 中。 ```bash # 检查文件中的硬编码机密 qring/config.ts src/db.ts # 自动修复：替换硬编码值并存储在 q-ring 中 qring lint src/config.ts --fix # 扫描整个目录并自动修复 qring scan . --fix ``` ### 代理内存 加密的持久化键值存储，在 AI 代理会话之间存活。用于记住轮换历史、项目决策或上下文。 ```bash # 存储内存 qring remember last_rotation "Rotated ST_KEY on 2026-21" # 检索它 recall last_rotation # 列出所有记忆 qring recall # 忘记 qring forget last_rotation ``` ### 预提交机密扫描 安装 git 预提交钩子，自动阻止包含硬编码机密的提交。 ```bash # 安装钩子 qring hook:install # 卸载 qring hook:uninstall ``` ### 机密分析 分析使用模式并为您的机密获取优化建议。 ```bash qring analyze ``` 输出包括访问最多的机密、未使用的/陈旧的机密、作用域优化建议和轮换建议。 ### 服务设置向导 使用单个命令快速设置新的服务集成，包括机密、清单条目和钩子。 ```bash # 为新的 Stripe 集成创建机密 qring wizard stripe --keys STRIPE_KEY,STRIPE_SECRET --provider stripe --tags payment # 带有更改钩子的向导 qring wizard myservice --hook-exec "pm2 restart app" ``` ### 治理策略 在 `.q-ring.json` 中定义项目规则，以控制允许使用哪些 MCP 工具、哪些密钥可访问以及可以执行哪些命令。在 MCP 服务器和密钥环级别强制执行策略。 在 MCP 上，策略从服务器启动的目录中解析 - 而不是调用者传递的 `projectPath` - 因此代理无法通过策略的目录来规避 MCP 服务器从项目根目录启动（`.q-ring.json` 位于此处）。对 `.q-ring.json` 的生效（策略缓存会在文件失效），因此您无需重启服务器bash # 查看活动策略 qring policy # JSON 输出 qring policy --json ``` 示例策略在 `.q-ring.json` 中： ```json { "policy": { "mcp": { "denyTools": ["delete_secret"], "deniedKeys": ["PROD_DB_PASSWORD"], "deniedTags": ["production"] }, " { "denyCommands": ["curl", "wget", "ssh"], maxRuntimeSeconds": 30 }, "secrets": { "requireApprovalForTags": ["production"], "maxTtlSeconds": 86400 } } } ``` ### 执行配置文件 使用命名配置文件限制命令执行，控制允许的命令、网络访问、超时和环境清理。 ```bash # 列出配置文件 qring exec:profiles # 创建配置文件 qring exec:profile add restricted --allow-commands "npm run deploy" --deny-network-access ``` # 以“restricted”配置文件运行（阻止curl、wget、ssh；超时30秒） qring exec --profile restricted -- npm test # 以“ci”配置文件运行（超时5分钟，允许网络访问） qring exec --profile ci -- npm run deploy # 默认：无限制 qring exec -- echo "hello" **内置配置文件：** `unrestricted`, `restricted` （无网络工具，30秒限制），`ci` （5分钟限制，阻止破坏性命令）。 ### 防篡改审计 每个审计事件都包含前一个事件的SHA-256哈希值，创建一个防篡改链。验证完整性并以多种格式导出日志。 ```bash # 验证整个审计链 qring audit:verify # 以JSON格式导出 qring audit:export --format json --since 2026-03-01 # 以CSV格式导出 qring audit:export --format csv --output audit-report.csv ``` ### 团队和组织范围 扩展`global`和`project`范围至`team`和`org`范围，实现跨组共享密钥。解析顺序：项目 → 团队 → 组织 → 全局（最具体者优先）。 ```bash # 在团队范围内存储密钥 qring set SHARED_API_KEY "sk-..." --team my-team # 存储在组织范围内 qring set ORG_LICENSE "lic-..." --org acme-corp # 解析级联：项目 > 团队 > 组织 > 全局 qring get API_KEY --team my-team --org acme-corp ``` ### 策略原生轮换 尝试提供者原生的密钥轮换（适用于支持的提供者），或回退到本地生成。 ```bash # 通过检测的提供者轮换 qring rotate STRIPE_KEY # 强制指定提供者 qring rotate API_KEY --provider openai ``` ### CI密钥验证 在CI友好模式下批量验证所有密钥的提供者。返回结构化的通过/失败报告，失败时退出代码为1。 ```bash # 验证所有密钥（CI模式） qring ci:validate # JSON输出用于管道解析 qring ci:validate --json ``` ### 代理模式 — 自主监控 一个后台守护进程，持续监控密钥健康状况，检测异常，并可选地自动轮换过期的密钥。 ```bash # 启动代理 qring agent --interval 60 --verbose # 带有过期密钥自动轮换 qring agent --auto-rotate # 单次扫描（用于CI/cron） qring agent --once ``` ### 量子状态仪表盘 — 实时监控 在浏览器中启动一个实时仪表盘，将整个量子子系统变成一个可一览的页面。它是一个自包含的HTML页面，在本地提供服务 — 无需云，无需配置，完全离线 — 构建为Preact + htm应用程序（运行时捆绑和内联）。它通过服务器发送事件每5秒流式传输更新，并在本地差异化DOM，以便数据刷新而不会重新运行进入动画，并且您的搜索输入、插入符号和滚动位置在刻度之间保持不变。 您将获得： - **KPI条** — 总密钥、检测到的环境、保护计数、活动审批、钩子、24小时读取和实时异常计数。 - **健康摘要** — 健康/陈旧/过期/无衰减密钥的甜甜圈图表，以及每个范围的计数（全局/项目/团队/组织）。 - **环境** — 波函数崩溃详细信息：检测到的环境、源、分支和任何项目上下文。 - **清单** — `.q-ring.json`摘要，包含声明/必需/丢失/过期/陈旧密钥。 - **策略** — 一览MCP、exec和密钥策略（允许/拒绝工具，拒绝密钥/标签，允许/拒绝命令，审批和轮换要求）。 - **密钥表** — 可搜索、可排序的每个密钥视图（密钥、范围、环境、类型、衰减、标签、最后读取），带有`过期`、`陈旧`和`保护`筛选的快速芯片。按 `/`聚焦搜索框。 - **量子卡** — 衰减计时器、叠加状态、纠缠对和活动量子隧道。 - **审批和钩子** — 有效（和篡改）的审批授予和每个注册钩子的匹配摘要。 - **代理内存** — 在`~/.config/q-ring/agent-memory.enc`处持久化的加密内存密钥计数。 - **异常警报** — 突发读取、非工作时间访问、篡改审计链和其他可疑模式。 - **审计日志（24小时）** — 可筛选的提要，带有操作芯片（`读取`/`写入`/`删除`/`导出`）、源芯片（`cli`/`mcp`/`hook`/`agent`）和纯文本筛选器。 顶栏控件允许您 **暂停** SSE更新（在读取审计源时很有用），**刷新** 按需，或跳转到 `/api/status` 处的原始JSON快照。键盘快捷键： `/` 聚焦密钥搜索 · `P` 暂停 · `R` 刷新。 仪表盘仅绑定到 `127.0.0.1` 并 **从不** 公开密钥值，但它会显示密钥名称、审计日志和审批授予 — 因此每个路由都由一个随机、每次启动的令牌控制。 `qring status` 打印（并打开）完整的URL，包括 `?token=…` ；没有令牌的请求会得到 `403` 。停止服务器以使令牌失效。 ```bash # 打开仪表盘（自动启动浏览器到 http://127.0.0.1:9876/?token=…） qring status # 指定自定义端口 qring status --port 4200 # 不自动打开浏览器（自行复制打印的令牌化URL） qring status --no-open ``` ## MCP服务器 q-ring包含一个完整的MCP服务器，带有44种工具用于AI代理集成。 ### 核心工具 | 工具 | 描述 | |------|-------------| | `get_secret` | 读取密钥值（崩溃叠加，审计读取） | | `list_secrets` | 在范围内列出密钥 + 元数据（值从不暴露）；按标签、到期时间、通配符筛选 | | `set_secret` | 创建或覆盖单个密钥，可选TTL、每环境状态、标签、轮换格式 | | `delete_secret` | 永久删除密钥值（无法从q-ring撤销） | | `has_secret` | 尊重衰减的布尔存在检查（无审计读取） | | `export_secrets` | 渲染多个密钥为`.env`或JSON，用于一次性导出（跳过审批保护的密钥，无授予） | | `import_dotenv` | 解析`.env`文本并批量存储每个键值对（仅接受原始内容，不读取文件） | | `check_project` | 将`.q-ring.json`清单与密钥环进行比较，检查缺失/过期/陈旧密钥 | | `env_generate` | 从项目清单中渲染完整的`.env`正文，并对空白位置发出警告 | ### 量子工具 | 工具 | 描述 | |------|-------------| | `inspect_secret` | 显示一个密钥的元数据（状态、衰减、纠缠、访问计数），不显示值 | | `detect_environment` | 解析当前上下文应驱动叠加崩溃的环境斜线 | | `generate_secret` | 生成一个选定格式的CSPRNG支持的值，并可选地存储它 | | `entangle_secrets` | 链接两个密钥，以便未来的写入/轮换传播相同的值 | | `disentangle_secrets` | 打破两个密钥之间的同步链接（不删除值） | ### 隧道工具 | 工具 | 描述 | |------|-------------| | `tunnel_create` | 将值存储在进程内存中并返回不透明的ID（从不触摸磁盘） | | `tunnel_read` | 通过ID获取隧道值 — 可能在读取时自毁 | | `tunnel_list` | 枚举活动隧道，剩余读取预算和TTL（仅限ID） | | `tunnel_destroy` | 立即从内存中删除隧道，在TTL/读取完成之前 | ### 传送工具 | 工具 | 描述 | |------|-------------| | `teleport_pack` | 将选定的密钥加密到一个受密码保护的AES-256-GCM包中 | | `teleport_unpack` | 解密传送包并导入每个密钥（可选干运行） | ### 验证工具 | 工具 | 描述 | |------|-------------| | `validate_secret` | 访问上游服务（OpenAI/Stripe/GitHub/AWS/HTTP）以确认单个密钥仍然有效 | | `list_providers` | 列出内置验证提供者和它们的自动检测前缀 | ### 钩子工具 | 工具 | 描述 | |------|-------------| | `register_hook` | 注册一个shell/HTTP/信号副作用，在写入/删除/轮换时触发 | | `list_hooks` | 显示每个注册钩子的匹配条件、类型和启用标志 | | `remove_hook` | 通过ID分离单个钩子而不触摸任何密钥 | ### 执行和扫描工具 | 工具 | 描述 | |------|-------------| | `exec_with_secrets` | 运行一个子命令，将密钥注入为环境变量，并且任何泄漏的值都会从输出中删除 | | `scan_codebase_for_secrets` | 遍历目录树并通过正则表达式 + 熵启发式标记硬编码密钥 | | `lint_files` | 检查特定文件列表的硬编码密钥，可选自动修复到 `process.env.KEY` | ### AI代理工具 | 工具 | 描述 | |------|-------------| | `get_project_context` | 机密、环境、清单、钩子和最近审计活动的单个红色快照 | | `agent_remember` | 在加密代理内存中持久化一个非密钥注释，跨会话 | | `agent_recall` | 读取内存值，或在未提供密钥时列出每个存储的密钥 | | `agent_forget` | 从代理内存中永久删除一个密钥 | | `analyze_secrets` | 用例配置文件：最常访问的、陈旧的、从未访问的、无轮换候选 | ### 观察者和健康工具 | 工具 | 描述 | |------|-------------| | `audit_log` | 查询由密钥、操作和限制筛选的防篡改审计日志 | | `detect_anomalies` | 从审计历史中显示突发读取和非工作时间发现 | | `verify_audit_chain` | 重新计算审计哈希链并报告如果篡改则报告第一个断点 | | `export_audit` | 以jsonl、json或csv导出审计事件用于存档/SIEM | | `health_check` | 只读范围扫描：衰减/陈旧/过期计数加当前异常 | | `status_dashboard` | 启动一个本地SSE仪表盘，带有实时KPI、密钥、钩子和审计源（返回一个令牌门控的`127.0.0.1` URL） | | `agent_scan` | 多项目健康通行，带有可选的`autoRotate`用于过期密钥 | ### 治理和策略工具 | 工具 | 描述 | |------|-------------| | `check_policy` | 在执行之前使用`.q-ring.json`策略进行工具/密钥/执行操作的干运行 | | `get_policy_summary` | 策略规则计数和审批/轮换要求的概要 | | `rotate_secret` | 请求上游提供者发布新的凭证并将其存储回密钥环 | | `ci_validate_secrets` | 批量验证范围内每个可访问的密钥并返回结构化的通过/失败报告 | ### 游标 / Kiro 配置 添加到 `.cursor/mcp.json` 或 `.kiro/mcp.json`： **如果q-ring已全局安装** （例如 `pnpm add -g @i4ctime/q-ring`）： ```json { "mcpServers": { "q-ring": { "command": "qring-mcp" } } } ``` **如果使用本地克隆：** ```json { "mcpServers": { "q-ring": { "command": "node", "args": ["/path/to/quantum_ring/dist/mcp.js"] } } } ``` ### Claude Code 配置 添加到 `~/.claude/claude_desktop_config.json`： **全局安装：** ```json { "mcpServers": { "q-ring": { "command": "qring-mcp" } } } ``` **本地克隆：** ```json { "mcpServers": { "q-ring": { "command": "node", "args": ["/path/to/quantum_ring/dist/mcp.js"] } } } ``` ## 编辑器插件 q-ring存储库提供了三个一流的编辑器包 — 每个包都为其主机编辑器添加了规则/引导、代理、命令、技能、钩子和MCP连接器。 | 插件 | 编辑器 | 亮点 | |--------|--------|-----------| | [`cursor-plugin/`](cursor-plugin/README.md) | [Cursor](https://cursor.com) | 3个规则，5个技能，2个代理，8个斜杠命令，3个钩子，MCP自动连接 | | [`kiro-plugin/`](kiro-plugin/README.md) | [Kiro](https://kiro.dev) | 官方 [Power](https://kiro.dev/docs/powers/create/) 布局： `POWER.md`，根 `mcp.json`， `steering/`， `hooks/`；或使用 `plugin:sync:kiro` 扁平化 | | [`claude-code-plugin/`](claude-code-plugin/README.md) | [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) | `CLAUDE.md` 内存，项目范围 `.mcp.json`，2个子代理，8个斜杠命令，5个技能，3个钩子脚本 | ### 游标插件 **q-ring 游标插件** 将量子密钥管理直接带入您的IDE，包含规则、技能、代理、命令、钩子和内置MCP连接器。 | 组件 | 功能 | |-----------|-------------| | **3个规则** | 始终开启的指导：绝不硬编码密钥，使用q-ring进行所有操作，警告`.env`文件 | | **5个技能** | 上下文自动触发：密钥管理、扫描、轮换、项目开通、exec-with-secrets | | **2个代理** | `security-auditor`（主动监控）和 `secret-ops`（日常助手） | | **8个命令** | `/qring:scan-secrets`、`/qring:health-check`、`/qring:rotate-expired`、`/qring:setup-project`、`/qring:teleport-secrets`、`/qring:dashboard`、`/qring:exec-safe`、`/qring:analyze` | | **3个钩子` | `afterFileEdit`（lint扫描）、`sessionStart`（项目上下文）、`beforeShellExecution`（`.env`守护） | | **MCP连接器** | 通过stdio自动连接到 `qring-mcp` — 所有44个工具可用 | 从Cursor市场安装或参见 [`cursor-plugin/README.md`](cursor-plugin/README.md) 进行手动设置。 ### Kiro插件（Power） [`kiro-plugin/`](kiro-plugin/) 目录是Kiro **Power** 按照 [Create powers](https://kiro.dev/docs/powers/create/)：`POWER.md`（元数据、上线、引导图），根 [`mcp.json`](kiro-plugin/mcp.json) （MCP服务器必须与引用的服务器名称匹配），以及 [`steering/`](kiro-plugin/steering/) 用于工作流。 从Kiro → **Powers** → **Add power from Local Path** 并选择 `kiro-plugin`，或在GitHub上发布文件夹并使用 **Add power from GitHub**。 始终开启的引导阻止硬编码密钥并将所有内容路由到q-ring；`manual`引导文件充当代理角色（#qring-secret-ops，#qring-security-auditor），技能包和斜杠命令（#qring-cmd-scan-secrets等）。可选钩子位于 `hooks/` 以复制到 `.kiro/hooks/`。 ```bash # 替代方案：扁平化到 ~/.kiro （设置 + 引导 + 钩子） pnpm run plugin:sync:kiro # 或作用于单个项目 pnpm run plugin:sync:kiro -- /path/to/your/project/.kiro ``` 参见 [`kiro-plugin/README.md`](kiro-plugin/README.md) 了解完整分解。 ### Claude Code 插件 对于 [Claude Code](https://docs.claude.com/en/docs/claude-code/overview)，q-ring 提供了 `CLAUDE.md` 内存文件、项目范围 `.mcp.json`、两个 [subagents](https://docs.claude.com/en/docs/claude-code/sub-agents)（`secret-ops`、`security-auditor`）、八个 [slash commands](https://docs.claude.com/en/docs/claude-code/slash-commands)（`/qring-scan-secrets`、`/qring-health-check`、…）、五个 [skills](https://docs.claude.com/en/docs/claude-code/skills）和三个 [hooks](https://docs.claude.com/en/docs/claude-code/hooks)（编辑后提醒、预Bash `.env` 守护、会话启动上下文提示）。 ```bash # 安装到当前项目（$PWD） pnpm run plugin:sync:claude # 安装代理/命令/技能/钩子到用户范围（~/.claude） pnpm run plugin:sync:claude -- --user # 或目标到特定项目 pnpm run plugin:sync:claude -- /path/to/your/project` ``` ## 项目配置（`.q-ring.json`） 可选的逐项目配置： ```json { "env": "dev", "defaultEnv": "dev", "branchMap": { "main": "prod", "develop": "dev", "staging": "staging", "release/*": "staging", "feature/*": "dev" }, "secrets": { "OPENAI_API_KEY": { "required": true, "description": "OpenAI API 密钥", "format": "api-key", "prefix": "sk-", "provider": "openai" }, "DATABASE_URL": { "required": true, "description": "Postgres 连接字符串", "validationUrl": "https://api.example.com/health" }, "SENTRY_DSN": { "required": false, "description": "Sentry 错误跟踪" } }, "policy": { "mcp": { "denyTools": ["delete_secret"], "deniedKeys": ["PROD_DB_PASSWORD"], "deniedTags": ["production"] }, "exec": { "denyCommands": ["curl", "wget"], "maxRuntimeSeconds": 60 } } } ``` - **`branchMap`** 支持带有 `*` 通配符的 glob 模式（例如，`release/*` 匹配 `release/v1.0`） - **`secrets`** 声明项目所需的密钥 — 使用 `qring check` 验证，使用 `qring env:generate` 生成 `.env` 文件 - **`provider`** 将存活验证提供程序与密钥关联（例如，`"openai"`、`"stripe"`、`"github"`）— 使用 `qring validate` 测试 - **`validationUrl`** 配置通用 HTTP 提供程序的自定义验证端点 - **`policy`** 定义 MCP 工具门控、密钥访问限制、执行允许列表和密钥生命周期要求的治理规则 ## 📚 文档 - [快速入门：Claude Code](docs/quickstart-claude-code.md) · [Cursor](docs/quickstart-cursor.md) · [Kiro](docs/quickstart-kiro.md) - [故障排除](docs/troubleshooting.md) — 密钥环后端、MCP 连接、批准门、策略固定 - [CLI ↔ MCP 对应关系](docs/cli-mcp-parity.md) — 每个命令都映射到其 MCP 工具 - [发布](docs/releasing.md) — 基于标签的发布流程 ## 贡献 参见 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取完整指南（开发环境、约定、需要同步的文件）。简要版本： - 在打开拉取请求之前，请运行 **`pnpm run lint`**、**`pnpm run typecheck`** 和 **`pnpm run test:ci`**。 - 测试或沙盒可以 将审计日志指向其他位置，使用 **`QRING_AUDIT_DIR`**（如果缺少目录，则会创建该目录）；默认为 `~/.config/q-ring/audit.jsonl`。 - 可选的本地预提交：**`qring hook:install`**（当 `qring` 在您的 `PATH` 上时，使用此软件包的 `precommit` 钩子）。 - 修改编辑器插件之一后： - **Cursor:** `pnpm run plugin:sync` 将 `cursor-plugin/` 复制到 `~/.cursor/plugins/local/my-plugin`（或传递自定义路径）。 - **Kiro:** `pnpm run plugin:sync:kiro` 将 `kiro-plugin/mcp.json` 复制到 `~/.kiro/settings/mcp.json`，以及 `steering/` 和 `hooks/`（或传递项目 `.kiro` 路径）。建议在 Powers 面板中添加 `kiro-plugin/` 作为 [Power](https://kiro.dev/docs/powers/create/)。 - **Claude Code:** `pnpm run plugin:sync:claude` 将 `claude-code-plugin/` 复制到当前目录（或传递项目路径；添加 `--user` 以安装在 `~/.claude/`）。 - 另请参见 [docs/cli-mcp-parity.md](docs/cli-mcp-parity.md)。 ## 📜 许可证 [AGPL-3.0](LICENSE) - 免费使用、修改和分享。任何衍生作品或托管服务必须在其源代码下使用相同的许可证发布。