q-ring

q-ring

通过 MCP 为 AI 编码 Agent 提供 OS 密钥链密钥。

告别将 API 密钥粘贴到纯文本 .env 文件中，或费力应付笨重的密钥管理器。q-ring 会将凭据安全地保存在 OS 原生保险库（macOS Keychain、Linux Secret Service、Windows Credential Vault）中，并以量子物理学机制为其赋能。

📖 查看官方文档，了解完整的 CLI 参考、MCP 提示词指南和架构详情。

为什么选择 q-ring？

• 叠加态： 将一个密钥存储为多种状态（dev/staging/prod），并根据上下文确定其状态。
• 量子纠缠： 跨项目关联密钥，轮换一个密钥即可自动更新所有关联密钥。
• 量子隧穿： 创建临时的内存密钥，并在设定时间或读取次数后自动销毁。
• 量子隐形传态： 安全打包并共享 AES-256-GCM 加密的密钥包。
• 无缝 AI 集成： 内置 46 个 MCP 工具，可在 Cursor、Kiro 和 Claude Code 中原生使用。

🚀 安装

q-ring 专为全局安装而设计，让你可以在终端的任何位置使用。选择你喜欢的包管理器：

# pnpm (recommended)
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 对外提供服务——适用于托管式 MCP 部署（例如 Glama），或完全避免在主机上运行服务：

git clone https://github.com/I4cTime/q-ring.git
cd q-ring
docker build -t qring-mcp .
docker run --rm -p 8080:8080 qring-mcp

注意：容器内没有 OS 密钥链（GNOME Keyring / macOS Keychain），因此此方式适用于 MCP 协议接口、临时使用和 CI 实验，不适合持久化的本地密钥存储。日常使用时，请通过上述任一包管理器原生安装 CLI。

⚡ 快速入门

# 1️⃣ Store a secret (prompts securely if value is omitted)
qring set OPENAI_API_KEY sk-...

# 2️⃣ Retrieve it anytime
qring get OPENAI_API_KEY

# 3️⃣ List all keys (values are never shown)
qring list

# 4️⃣ Generate a cryptographic secret and save it
qring generate --format api-key --prefix "sk-" --save MY_KEY

# 5️⃣ Run a full health scan
qring health

# Something not working? Diagnose the install (keyring, audit, MCP wiring)
qring doctor

# Tab completion for your shell
qring completion zsh > ~/.zsh/completions/_qring   # also: bash, fish

量子特性

叠加态 — 一把密钥，多种环境

单个密钥可以同时保存开发、预发布和生产环境的不同值。系统会根据当前上下文解析出正确的值。

# Set environment-specific values
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

# Value resolves based on context
QRING_ENV=prod qring get API_KEY   # → sk-prod-789
QRING_ENV=dev  qring get API_KEY   # → sk-dev-123

# Inspect the quantum state
qring inspect API_KEY

环境晋升 — 先比较，再晋升

密钥具有各环境状态后，晋升就无需再复制粘贴：逐个比较两个环境中的密钥（仅比较状态，绝不比较值），然后将一个状态中的值复制到另一个状态。diff 在存在差异时以状态码 1 退出，因此也可用作 CI 门禁；除非你明确允许，否则 promote 会拒绝覆盖目标环境中的不同值。

# What differs between staging and prod? (same / different / missing on one side)
qring diff staging prod

# Make prod match staging for one key (asks before overwriting a different value)
qring promote DATABASE_URL --from staging --to prod

# Non-interactive, e.g. in a release script
qring promote DATABASE_URL --from staging --to prod --force --json

MCP Agent 也可使用相同的两项操作：diff_environments 和 promote_secret。

波函数坍缩 — 智能环境检测

q-ring 无需显式标记即可自动检测环境。解析顺序如下：

1. --env 标记
2. QRING_ENV 环境变量
3. NODE_ENV 环境变量
4. Git 分支启发式规则（main/master → 生产环境，develop → 开发环境）
5. .q-ring.json 项目配置
6. 密钥的默认环境

# See what environment q-ring detects
qring env

# Project config (.q-ring.json)
echo '{"env": "staging", "branchMap": {"release/*": "staging"}}' > .q-ring.json

量子衰变 — 带 TTL 的密钥

密钥可以设置存活时间。过期密钥会被禁止读取。陈旧密钥（已使用其存活时间的 75% 或以上）会触发警告。

# Set a secret that expires in 1 hour
qring set SESSION_TOKEN "tok-..." --ttl 3600

# Set with explicit expiry
qring set CERT_KEY "..." --expires "2026-06-01T00:00:00Z"

# Health check shows decay status
qring health

观察者效应 — 全面审计

每次读取、写入和删除密钥都会记录在具有防篡改哈希链的日志中。系统会跟踪访问模式以检测异常。

# View audit log
qring audit
qring audit --key OPENAI_KEY --limit 50

# Detect anomalies (burst access, unusual hours, chain tampering)
qring audit --anomalies

# Verify audit chain integrity
qring audit:verify

# Export audit log
qring audit:export --format json --since 2026-03-01
qring audit:export --format csv --output audit-report.csv

量子噪声 — 密钥生成

生成常见格式的强加密密钥。

qring generate                          # API key (default)
qring generate --format password -l 32  # Strong password
qring generate --format uuid            # UUID v4
qring generate --format token           # Base64url token
qring generate --format hex -l 64       # 64-byte hex
qring generate --format api-key --prefix "sk-live-" --save STRIPE_KEY

量子纠缠 — 关联密钥

在多个项目之间关联密钥。轮换某个密钥时，所有纠缠副本都会自动更新。

# Entangle two secrets
qring entangle API_KEY API_KEY_BACKUP

# Now updating API_KEY also updates API_KEY_BACKUP
qring set API_KEY "new-value"

# Unlink entangled secrets
qring disentangle API_KEY API_KEY_BACKUP

量子隧穿 — 临时密钥

创建仅存在于内存中的密钥。它们不会接触磁盘。可选设置 TTL 和最大读取次数，达到条件后自动销毁。

# Create an ephemeral secret (returns tunnel ID)
qring tunnel create "temporary-token-xyz" --ttl 300 --max-reads 1

# Read it (self-destructs after this read)
qring tunnel read tun_abc123

# List active tunnels
qring tunnel list

量子隐形传态 — 加密共享

将密钥打包到 AES-256-GCM 加密包中，以便在不同机器之间安全传输。锁定加密包有两种方式：

• 密码短语（v1）：使用 PBKDF2-HMAC-SHA512 派生密钥（210 000 次迭代）；每个加密包都会记录迭代次数，因此旧加密包仍可解包。
• 接收者（v2，0.18）：每位队友只需运行一次 qring teleport keygen，并分享其接收者字符串（qring1…，即 X25519 公钥；私钥保存在其操作系统密钥环中）。pack --to 会将新的内容密钥加密给每位接收者——使用临时 X25519 协商生成 HKDF-SHA256 密钥，全程采用 AES-256-GCM，仅使用 node:crypto——因此加密包之外不会传输任何秘密，也无需私下传递密码短语。

# Passphrase bundle (prompts)
qring teleport pack --keys "API_KEY,DB_PASS" > bundle.txt
cat bundle.txt | qring teleport unpack

# Recipient bundle: teammates publish their recipient once…
qring teleport keygen            # → qring1a3F…  (share this; keep the keyring)
qring teleport identity          # print it again later

# …then you address the pack to them (repeatable or comma-separated)
qring teleport pack --keys "API_KEY,DB_PASS" --to qring1a3F… --to qring1Zz9… > bundle.txt

# They unpack with the identity in their keyring — no passphrase
cat bundle.txt | qring teleport unpack

# Preview: who it's addressed to, whether that's you, and what's inside
qring teleport unpack <bundle> --dry-run

导入 — 批量导入密钥

将密钥从 .env 文件直接导入 q-ring。支持标准 dotenv 语法，包括注释、带引号的值和转义序列。CLI 接受文件路径或原始内容；import_dotenv MCP 工具只接受原始内容（不会读取磁盘上的文件），因此 Agent 无法诱使它读取任意本地文件。

# Import all secrets from a .env file
qring import .env

# Import to project scope, skipping existing keys
qring import .env --project --skip-existing

# Preview what would be imported
qring import .env --dry-run

选择性导出

使用密钥名称或标签筛选器，仅导出所需密钥。

# Export specific keys
qring export --keys "API_KEY,DB_PASS,REDIS_URL"

# Export by tag
qring export --tags "backend"

# Combine with format
qring export --keys "API_KEY,DB_PASS" --format json

密钥搜索与筛选

按标签、过期状态或密钥模式筛选 qring list 的输出。

# Filter by tag
qring list --tag backend

# Show only expired secrets
qring list --expired

# Show only stale secrets (75%+ decay)
qring list --stale

# Glob pattern on key name
qring list --filter "API_*"

# Script-friendly existence check (exit 0 if present, 1 if not; decay-aware)
qring has OPENAI_API_KEY --quiet && echo "configured"

项目密钥清单

在 .q-ring.json 中声明所需密钥，并通过一条命令验证项目是否已准备就绪。

# Validate project secrets against the manifest
qring check

# See which secrets are present, missing, expired, or stale
qring check --project-path /path/to/project

环境文件同步

根据项目清单生成 .env 文件，并从 q-ring 中解析每个密钥，同时根据环境解析其叠加状态。

# Generate to stdout
qring env:generate

# Write to a file
qring env:generate --output .env

# Force a specific environment
qring env:generate --env staging --output .env.staging

密钥引用与最小权限运行

qring:// 引用是指向密钥的可提交指针——它应放入 .env 文件中，替代密钥值。qring run 会在启动时解析引用和清单密钥，只注入项目声明的内容（不同于会注入整个作用域的 exec）。输出会自动脱敏。

# .env — safe to commit: these are references, not values
DATABASE_URL=qring://project/DATABASE_URL
OPENAI_API_KEY=qring://global/OPENAI_API_KEY
STRIPE_KEY=qring:///STRIPE_KEY            # auto scope: project, then global
SESSION_TTL=3600                          # plain values pass through

# Run with declared secrets injected (manifest + .env refs)
qring run -- pnpm dev

# Preview what would be injected, without running
qring run --dry-run -- pnpm dev

# Pin an environment, use a specific env file, or skip the manifest
qring run --env prod --env-file .env.prod --no-manifest -- ./deploy.sh

密钥名位于路径中，而不是主机名中（使用 qring://project/KEY，而不是 qring://KEY）——URL 主机名不区分大小写，而环境变量名区分大小写。格式错误的引用会明确报错，不会将字面的 qring://… 字符串泄漏给子进程。也可以将引用固定到某个环境：qring://project/DATABASE_URL?env=prod。

编辑器配置

只需一条命令，即可将 q-ring MCP 服务接入编辑器的 MCP 配置。合并操作不会造成破坏——其他服务会保留，只有使用 --force 才会替换现有的 q-ring 配置项。

qring setup cursor          # .cursor/mcp.json (project) or --global for ~/.cursor
qring setup kiro            # .kiro/settings/mcp.json, with read-only autoApprove list
qring setup claude          # .mcp.json (project scope)

# Preview without writing
qring setup cursor --dry-run

推送到部署平台

通过各个平台自己的已认证 CLI（gh / vercel / wrangler / flyctl / railway / netlify），将清单密钥推送到 GitHub Actions、Vercel、Cloudflare Workers、fly.io、Railway 或 Netlify——q-ring 从不持有平台令牌，密钥值通过 stdin 传输（对于仅支持导入的 Netlify CLI，则使用一个会立即删除的 0600 临时文件），绝不会通过 argv 传输。每次推送都会记录在审计链中。

# Push the .q-ring.json manifest keys to GitHub Actions secrets
qring push github --repo you/your-app

# Push to Vercel environments
qring push vercel --vercel-env production,preview

# Push to Cloudflare Workers secrets
qring push cloudflare

# fly.io (flyctl secrets import over stdin — note flyctl deploys per import), Railway, Netlify
qring push fly --app my-app
qring push railway --service api --railway-env production
qring push netlify --site 1234-abcd

# Explicit keys, preview first
qring push github --keys DATABASE_URL,API_KEY --dry-run

也可以一并植入金丝雀：qring canary plant KEY --format aws --push github 会在本地植入蜜罐令牌，并将其写入平台，但不会读取该令牌（参见 Canary 蜜罐令牌）。

密钥有效性验证

测试密钥对目标服务是否有效。q-ring 会根据密钥前缀自动检测提供商（sk- → OpenAI，ghp_ → GitHub 等），也可指定提供商名称。

# Validate a single secret
qring validate OPENAI_API_KEY

# Force a specific provider
qring validate SOME_KEY --provider stripe

# Validate all secrets with detectable providers
qring validate --all

# Only validate manifest-declared secrets
qring validate --all --manifest

# List available providers
qring validate --list-providers

内置提供商： OpenAI、Anthropic、OpenRouter、Google AI（Gemini）、Groq、Hugging Face、ElevenLabs*、Vercel*、Stripe、GitHub、AWS（格式检查）、Generic HTTP。密钥只会通过请求头发送，绝不会放入 URL。（*没有安全的公开前缀——请使用 --provider 或清单中的 provider 字段明确指定。）

输出：

  ✓ OPENAI_API_KEY   valid    (openai, 342ms)
  ✗ STRIPE_KEY       invalid  (stripe, 128ms) — API key has been revoked
  ⚠ AWS_ACCESS_KEY   error    (aws, 10002ms) — network timeout
  ○ DATABASE_URL     unknown  — no provider detected

钩子——密钥变更时触发的回调

注册 Webhook、Shell 命令或进程信号，在创建、更新或删除密钥时触发。支持密钥匹配、glob 模式、标签筛选和作用域限制。

# Run a shell command when a secret changes
qring hook add --key DB_PASS --exec "docker restart app"

# POST to a webhook on any write/delete
qring hook add --key API_KEY --url "https://hooks.example.com/rotate"

# Trigger on all secrets tagged "backend"
qring hook add --tag backend --exec "pm2 restart all"

# Signal a process when DB secrets change
qring hook add --key-pattern "DB_*" --signal-target "node"

# List all hooks
qring hook list

# Remove a hook
qring hook remove <id>

# Enable/disable
qring hook enable <id>
qring hook disable <id>

# Dry-run test a hook
qring hook test <id>

钩子采用即发即弃方式：钩子失败绝不会阻止密钥操作。钩子注册表存储于 ~/.config/q-ring/hooks.json。

SSRF 防护： 默认会阻止目标为私有/回环 IP 地址范围的 HTTP 钩子 URL（127.0.0.0/8、10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、169.254.0.0/16、::1、fc00::/7）。DNS 会在连接前检查，且在连接时重新验证，因此主机名无法先通过检查，再于套接字打开前重新绑定到私有地址。要允许钩子访问本地服务（例如在开发期间），请设置环境变量 Q_RING_ALLOW_PRIVATE_HOOKS=1。

可配置轮换

为每个密钥设置轮换格式，让 Agent 使用正确的值格式自动轮换；还可以设置轮换间隔，以便 q-ring 在凭据过期前提醒你。每个密钥都会记录其值上次更改的时间（rotatedAt）；设置 --rotate-every 后，在间隔的最后 20%（或最后 7 天，以较短者为准）内会标记为即将到期，超过该时限则标记为已逾期。这些状态会显示在 qring inspect、qring rotate:due、仪表板的“即将轮换”卡片以及 inspect_secret 工具中。

# Store a secret with rotation format metadata
qring set STRIPE_KEY "sk-..." --rotation-format api-key --rotation-prefix "sk-"

# Store a password with password rotation format
qring set DB_PASS "..." --rotation-format password

# Remind me every 90 days
qring set STRIPE_KEY "sk-..." --rotate-every 90

# What needs rotating? (most overdue first; --all lists every scheduled secret)
qring rotate:due
qring rotate:due --json

安全执行与自动脱敏

在安全注入密钥到环境变量的同时运行命令。所有已知密钥值都会从 stdout 和 stderr 中自动脱敏，防止泄漏到终端日志或 Agent 对话记录中。执行配置文件可限制允许运行的命令。

# Execute a deployment script with secrets injected
qring exec -- npm run deploy

# Inject only specific tags
qring exec --tags backend -- node server.js

# Run with a restricted profile (blocks network tools and interpreters/shells, 30s timeout)
qring exec --profile restricted -- npm test

代码库密钥扫描器

正在迁移旧代码库？使用正则表达式启发式规则和 Shannon 熵分析，快速扫描目录中的硬编码凭据。

# Scan current directory
qring scan .

输出：

  ✗ src/db/connection.js:12
    Key:     DB_PASSWORD
    Entropy: 4.23
    Context: const DB_PASSWORD = "..."

复合 / 模板化密钥

存储复杂的连接字符串，并动态解析其他密钥。如果 DB_PASS 轮换，DB_URL 会自动保持正确，无需手动更新。

qring set DB_USER "admin"
qring set DB_PASS "supersecret"
qring set DB_URL "postgres://{{DB_USER}}:{{DB_PASS}}@localhost/mydb"

# Resolves embedded templates automatically
qring get DB_URL 
# Output: postgres://admin:supersecret@localhost/mydb

用户审批（零信任 Agent）

保护敏感的生产密钥，未经用户明确批准，MCP 服务不得自主读取。每个审批令牌都会经过 HMAC 验证，并限定作用范围、注明原因且设有有效期限。此门禁也适用于批量读取：通过 MCP 执行 export_secrets 和 teleport_pack 时，会跳过缺少有效授权的受审批保护密钥。

# Mark a secret as requiring approval
qring set PROD_DB_URL "..." --requires-approval

# Temporarily grant MCP access for 1 hour with a reason
qring approve PROD_DB_URL --for 3600 --reason "deploying v2.0"

# List all approvals with verification status
qring approvals

# Revoke an approval
qring approve PROD_DB_URL --revoke

当 Agent 因受审批保护的密钥而受阻时，q-ring 会发出桌面通知（Linux 上使用 notify-send，macOS 上使用 osascript），通知中会注明密钥和准确的 qring approve 命令。通知按密钥限流，可通过 QRING_NOTIFY=off 禁用。

Canary 蜜标

植入看起来与读取起来都和真实凭据完全相同的假凭据。任何触及蜜标的对象——遭入侵的 MCP 服务、过度好奇的 Agent，或遍历密钥环以窃取数据的工具——都会收到假值，且不会察觉异常；与此同时，q-ring 会触发桌面警报，并在防篡改审计链中写入 canary 事件。

# Plant a canary shaped like a real AWS access key
qring canary plant AWS_SECRET_ACCESS_KEY --format aws

# Other shapes: aws-secret, github, github-pat, openai, openai-project,
# anthropic, stripe, gitlab, slack, google, npm, generic
qring canary plant GHP_BACKUP_TOKEN --format github-pat

# See what's been tripped
qring canary list
qring audit --action canary

这些值是符合服务提供商真实令牌格式的 CSPRNG 随机噪声（aws 蜜标符合 AKIA[A-Z0-9]{16}，anthropic 蜜标符合真实的 sk-ant-api03-…AA 格式），看起来足以乱真，但永远无法通过验证。警报按密钥限流，每 30 秒最多触发一次；审计记录会记录每次读取。

及时收到警报。 只有在电脑旁时，桌面通知才有用。注册 Webhook 渠道，每次触发也会通知这些渠道：

qring canary alert add --discord https://discord.com/api/webhooks/…
qring canary alert add --slack   https://hooks.slack.com/services/…
qring canary alert add --ntfy    https://ntfy.sh/my-canaries
qring canary alert add --url     https://example.com/canary   # generic JSON POST
qring canary alert list
qring canary alert test          # send a clearly-labelled drill

渠道配置存放在 ~/.config/q-ring/canary-alerts.json（模式为 0600）。通知采用即发即弃的方式，像钩子一样防范 SSRF，并与桌面警报共用限流机制；通知绝不包含假值，只包含密钥、作用范围、来源，以及触发访问的 Agent 标签。

在 CI 中植入触发器。 一步完成蜜标植入并将其推送到部署平台，让泄露的 GitHub Actions / Vercel / Cloudflare 环境携带诱饵：

qring canary plant AWS_SECRET_ACCESS_KEY --format aws-secret --push github --repo you/your-app

坦诚说明：q-ring 只能看到经过 q-ring 的读取。在平台端直接使用泄露值时，q-ring 无法观察到；如有需要，请同时启用服务提供商自己的警报功能。

蜜标经过精心设计，能够隐蔽运行：它们不带任何标识性描述（你可以使用 --description 添加不起眼的掩护说明），标记永远不会出现在 MCP 工具响应中，触发记录也只能在操作员的终端中查看——Agent 无法通过 MCP 审计工具看到这些记录。批量 export 和 delete 与读取一样会触发蜜标，因此遍历密钥环或移除触发器都会拉响警报。不再需要某个蜜标？运行 qring canary disarm <key>，即可将其恢复为普通密钥（对蜜标执行 qring set 前会先发出警告——覆盖操作会刻意保留蜜标标记，防止 Agent 将其洗掉）。

MCP Airlock

通过 q-ring 在第三方 MCP 服务前运行。Airlock 位于 Agent 主机和封装的服务之间，以剥离后的环境启动该服务（不继承 API 密钥；使用 --inherit-env 可选择恢复继承），在审计链中将所有经过它的工具调用、资源读取和提示词获取记录为 wrap 事件（按会话分组，并标注调用客户端的身份），在每个结果到达转录记录前清除已知的机密值，并执行项目的 policy.wrap 规则。工具和提示词参数不会被记录——它们可能包含机密。

{
  "mcpServers": {
    "some-server": {
      "command": "qring",
      "args": ["mcp", "wrap", "--", "npx", "-y", "some-mcp-server"]
    }
  }
}

工具、资源和提示词都会原样通过（包括分页、进度通知、取消、订阅以及 list_changed / updated 通知）；Airlock 声明的能力与封装服务完全一致。长时间运行的工具由主机自身的超时机制管理，Airlock 设有较宽松的超时上限，可通过 QRING_WRAP_TIMEOUT_MS 配置。

# Wrap a remote Streamable HTTP server; the Bearer token comes from q-ring (audited read)
qring mcp wrap --url https://mcp.example.com/mcp --auth-secret EXAMPLE_MCP_TOKEN

# Keep results verbatim (default: known secret values are replaced with [QRING:REDACTED])
qring mcp wrap --no-redact -- npx -y some-mcp-server

封装策略。 在 .q-ring.json 中管理封装的服务——使用相同的文件和失败关闭引擎：

{
  "policy": {
    "wrap": {
      "allowTools": ["github_*", "search"],
      "denyTools": ["github_delete_*"],
      "approveTools": ["github_merge_pr"],
      "rateLimit": { "maxCalls": 60, "perSeconds": 60 },
      "toolRateLimits": { "search": { "maxCalls": 5, "perSeconds": 10 } },
      "redactResults": true
    }
  }
}

被拒绝的工具会从 tools/list 中隐藏，调用时也会被拒绝，并生成 policy_deny 审计事件；在你授予 approveTools 中的工具之前，它们的调用会被拒绝：

qring mcp approve github_merge_pr --for 900 --reason "release 1.4"
qring mcp approvals
qring mcp approve github_merge_pr --revoke

请明确 Airlock 的作用：剥离环境、为每次通过留下可防篡改的记录、在工具边界执行策略，以及尽力清除环中已知的机密值。它不是沙箱——封装的进程仍以你的用户身份运行，拥有正常的文件系统、网络和操作系统密钥链访问权限，且工具描述不会经过检查。有关实际边界的说明，请参阅 docs/threat-model.md。

即时（JIT）配置

无需存储静态凭据，而是将 q-ring 配置为在请求时动态生成短期令牌（例如 AWS STS、通用 HTTP 端点）。

# Store the STS role configuration
qring set AWS_TEMP_KEYS '{"roleArn":"arn:aws:iam::123:role/AgentRole", "durationSeconds":3600}' --jit-provider aws-sts

# Resolving the secret automatically assumes the role and caches the temporary token
qring get AWS_TEMP_KEYS

面向 AI Agent 的项目上下文

安全且经过脱敏的项目机密、配置和状态概览。专为放入 AI Agent 的系统提示词而设计，不会暴露机密值。

# Human-readable summary
qring context

# JSON output (for MCP / programmatic use)
qring context --json

机密感知代码检查器

扫描指定文件中的硬编码机密，并可选择自动修复。使用 --fix 时，检测到的机密会替换为 process.env.KEY 引用，并存储在 q-ring 中。

# Lint files for hardcoded secrets
qring lint src/config.ts src/db.ts

# Auto-fix: replace hardcoded values and store in q-ring
qring lint src/config.ts --fix

# Scan entire directory with auto-fix
qring scan . --fix

Agent 记忆

加密的持久化键值存储，可在多个 AI Agent 会话之间保留。适合记住轮换历史、项目决策或上下文。

# Store a memory
qring remember last_rotation "Rotated STRIPE_KEY on 2026-03-21"

# Retrieve it
qring recall last_rotation

# List all memories
qring recall

# Forget
qring forget last_rotation

提交前机密扫描

安装 git 提交前钩子，自动阻止包含硬编码机密的提交。

# Install the hook
qring hook:install

# Uninstall
qring hook:uninstall

机密分析

分析使用模式，并获取机密优化建议。

qring analyze

输出包括访问次数最多的机密、未使用或已过期的机密、范围优化建议以及轮换建议。

服务设置向导

通过一条命令快速设置新的服务集成，包括机密、清单条目和钩子。

# Create secrets for a new Stripe integration
qring wizard stripe --keys STRIPE_KEY,STRIPE_SECRET --provider stripe --tags payment

# With a hook to restart the app on change
qring wizard myservice --hook-exec "pm2 restart app"

治理策略

在 .q-ring.json 中定义项目级治理规则，以控制哪些 MCP 工具可以使用、哪些密钥可以访问、哪些命令可以执行，以及被包装的 MCP 服务在安全隔离区内可以执行哪些操作。策略在 MCP 服务、密钥环和安全隔离区级别强制执行。

通过 MCP 启动时，策略根据服务启动所在的目录解析，而不是根据调用方传入的 projectPath 解析，因此 Agent 无法通过指向没有策略的目录来绕过限制。请从项目根目录（.q-ring.json 所在目录）启动 MCP 服务。对 .q-ring.json 的修改会自动生效（文件更改时策略缓存会失效），因此无需重启服务。

策略文件会经过架构验证，并且默认拒绝：无效的 policy 对象（例如将 denytools 拼错）会引发 PolicyConfigError，而不是被静默忽略，因此格式错误的规则绝不会扩大访问权限。

# View the active policy
qring policy

# JSON output
qring policy --json

.q-ring.json 中的策略示例：

{
  "policy": {
    "mcp": {
      "denyTools": ["delete_secret"],
      "deniedKeys": ["PROD_DB_PASSWORD"],
      "deniedTags": ["production"]
    },
    "exec": {
      "denyCommands": ["curl", "wget", "ssh"],
      "maxRuntimeSeconds": 30
    },
    "secrets": {
      "requireApprovalForTags": ["production"],
      "maxTtlSeconds": 86400
    },
    "wrap": {
      "denyTools": ["*_delete_*"],
      "approveTools": ["deploy_*"],
      "rateLimit": { "maxCalls": 60, "perSeconds": 60 }
    }
  }
}

执行配置

使用具名配置限制命令执行，这些配置可控制允许执行的命令、网络访问、超时时间和环境变量清理。

# Run with the "restricted" profile (blocks network tools and interpreters/shells; 30s timeout)
qring exec --profile restricted -- npm test

# Run with the "ci" profile (5min timeout, allows network)
qring exec --profile ci -- npm run deploy

# Default: unrestricted
qring exec -- echo "hello"

内置配置： unrestricted、restricted（禁止网络工具以及解释器／Shell——python -c、node -e、bash 等都无法外泄注入的机密；限制时间为 30s）、ci（限制时间为 5min，阻止破坏性命令）。

防篡改审计

每条审计事件都包含前一条事件的 SHA-256 哈希，从而形成一条可检测篡改的链。自 v0.14 起，链还会使用存储在 OS 密钥环中的密钥 HMAC 进行锚定，因此 qring audit:verify 可以检测截断和整文件重写，而不只是原地修改。验证完整性并以多种格式导出日志。MCP 会话中的事件还会附上连接客户端自行报告的身份信息（clientInfo 中的 name@version），该信息会显示在 qring audit 输出中，也可通过 qring audit --agent <label> 筛选。这只是用于标记“哪个 Agent 执行了此操作”的审计标签，绝不是授权边界，因为客户端可以自行选择报告的内容。

# Verify the entire audit chain
qring audit:verify

# Export as JSON
qring audit:export --format json --since 2026-03-01

# Export as CSV
qring audit:export --format csv --output audit-report.csv

Agent 会话时间线

每个 MCP 会话都会附上客户端身份信息（clientInfo 中的 name@version），每个安全隔离区会话都会附上关联 ID。audit:sessions 会将平铺的审计记录重新整理为每个 Agent 进程对应的一条时间线，因此，只需一条命令就能查看“Cursor 在该会话中做了什么”，而无需使用 grep。

# One block per session: agent, source, window, event + denial counts, keys touched
qring audit:sessions

# Narrow to one client, widen the window, print every event line
qring audit:sessions --agent "[email protected]" --since 7d --verbose

# Machine-readable
qring audit:sessions --json

安全隔离区会话（qring mcp wrap）会以 airlock: <wrapped command> 的形式显示，并按顺序列出每次代理调用。状态面板（qring status）会在可展开的 Agent 会话（24h） 卡片中呈现相同数据。

Agent 也可以查看自己的历史记录，不过是通过 MCP 资源而非工具：qring://sessions 会列出会话摘要，qring://sessions/{id} 会返回一条时间线（仅包含密钥名称和操作，绝不包含值）。Agent 侧有两项保障：在汇总任何内容之前会剔除金丝雀触发记录，因此无法通过会话视图发现蜜罐令牌；在 .q-ring.json 策略中禁止 audit_log 工具，也会同时隐藏这些资源——一个开关即可控制 Agent 的审计可见性。

加密文件后端（无头环境／CI）

完全没有 OS 密钥环的主机（无头 Linux、容器、CI）可以选择使用加密文件存储。所有内容——机密、审计锚点、Agent 记忆密钥——都会经由该存储处理。

export QRING_BACKEND=file
export QRING_FILE_PASSPHRASE="a strong passphrase"   # required — no passphrase, no access
qring set CI_TOKEN

该存储采用 AES-256-GCM，位于 ~/.config/q-ring/file-backend.enc（模式 0600，可通过 QRING_FILE_BACKEND_PATH 覆盖路径），并使用基于密码短语的 PBKDF2 派生密钥。该功能仅在显式启用时使用：缺少 OS 密钥环时绝不会静默回退到此存储；没有密码短语时，所有操作都会默认拒绝——q-ring 绝不会使用可从机器信息推导出的密钥进行加密。

团队与组织作用域

在 global 和 project 作用域之外，增加 team 和 org 作用域，以便在群组间共享机密。解析顺序：project → team → org → global（优先采用最具体的作用域）。

# Store a secret in team scope
qring set SHARED_API_KEY "sk-..." --team my-team

# Store in org scope
qring set ORG_LICENSE "lic-..." --org acme-corp

# Resolution cascades: project > team > org > global
qring get API_KEY --team my-team --org acme-corp

发行方原生轮换

尝试使用提供方原生方式轮换密钥（适用于支持此功能的提供方），否则回退到本地生成。

# Rotate via the detected provider
qring rotate STRIPE_KEY

# Force a specific provider
qring rotate API_KEY --provider openai

CI 密钥验证

以适用于 CI 的模式，批量验证所有密钥与其提供方的连接。返回结构化的通过/失败报告，失败时退出码为 1。

# Validate all secrets (CI mode)
qring ci:validate

# JSON output for pipeline parsing
qring ci:validate --json

Agent 模式 — 自主监控

在后台运行的守护进程，可持续监控密钥健康状况、检测异常，并可选择自动轮换过期密钥。

# Start the agent
qring agent --interval 60 --verbose

# With auto-rotation of expired secrets
qring agent --auto-rotate

# Single scan (for CI/cron)
qring agent --once

量子状态仪表板 — 实时监控

在浏览器中启动实时仪表板，将整个量子子系统浓缩为一页，一目了然。这是一个在本地提供服务的独立 HTML 页面——无需云端、无需配置，完全离线——使用 Preact + htm 应用构建（运行时已打包并内联）。它每 5 秒通过 Server-Sent Events 推送更新，并就地更新 DOM，因此数据刷新时不会重新播放入场动画，而且搜索输入、光标和滚动位置都能在每次更新时保留。

你将获得：

• KPI 栏 — 密钥总数、检测到的环境、受保护数量、待处理审批、钩子、过去 24 小时的读取次数，以及实时异常数量。
• 健康状况摘要 — 健康 / 陈旧 / 过期 / 未设置衰减的密钥环形图，以及按范围划分的数量（全局 / 项目 / 团队 / 组织）。
• 环境 — 波函数坍缩详情：检测到的环境、来源、分支，以及任何项目上下文。
• 清单 — .q-ring.json 摘要，显示已声明 / 必需 / 缺失 / 过期 / 陈旧的密钥。
• 策略 — MCP、exec 和密钥策略一览（允许 / 拒绝的工具、拒绝的密钥 / 标签、允许 / 拒绝的命令，以及审批和轮换要求）。
• 密钥表格 — 可搜索、可排序的所有密钥视图（密钥、范围、环境、类型、衰减、标签、上次读取时间），并提供 expired、stale 和 protected 快捷筛选标签。按 / 可聚焦搜索框。
• 量子卡片 — 衰减计时器、叠加态、纠缠对和活跃的量子隧道。
• 审批与钩子 — 有效（以及遭篡改的）审批授权实时列表，以及每个已注册钩子及其匹配摘要。
• Agent 会话（24 小时） — 每个 MCP 客户端或隔离舱会话各显示一行：Agent 标签、来源、时间窗口、事件和拒绝次数、近期事件。
• Agent 记忆 — 持久化在 ~/.config/q-ring/agent-memory.enc 中的加密记忆密钥数量。
• 异常警报 — 突发读取、非工作时间访问、遭篡改的审计链以及其他可疑模式。
• 审计日志（24 小时） — 可筛选的信息流，提供操作标签（read/write/delete/export）、来源标签（cli/mcp/hook/agent）和自由文本筛选。

顶部栏控件可让你暂停 SSE 更新（便于阅读审计信息流）、按需刷新，或跳转到原始 JSON 快照 /api/status。键盘快捷键：/ 聚焦密钥搜索 · P 暂停 · R 刷新。

仪表板仅绑定到 127.0.0.1，且绝不会暴露密钥值，但会显示密钥名称、审计日志和审批授权——因此，每个路由都受随机生成的单次启动令牌保护。qring status 会打印（并打开）包含 ?token=… 的完整 URL；未携带令牌的请求会收到 403。停止服务器即可使令牌失效。

# Open the dashboard (auto-launches your browser at http://127.0.0.1:9876/?token=…)
qring status

# Specify a custom port
qring status --port 4200

# Don't auto-open the browser (copy the printed tokenized URL yourself)
qring status --no-open

MCP 服务

q-ring 内置完整的 MCP 服务，包含 46 个用于 AI Agent 集成的工具。

核心工具

工具	描述
get_secret	读取密钥值（会折叠叠加态，并审计读取操作）
list_secrets	列出作用域内的键和元数据（绝不公开值）；可按标签、到期时间和 glob 筛选
set_secret	创建或覆盖单个密钥，可选设置 TTL、按环境划分状态、标签和轮换格式
promote_secret	将一个密钥的值从一个环境状态复制到另一个环境状态（相同时不执行任何操作；可用 force 覆盖不同的目标值）
diff_environments	逐键比较两个环境——相同／不同／仅在 A 中／仅在 B 中／已折叠；只显示状态，绝不显示值
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	确定当前上下文中应由哪个环境 slug 驱动叠加态折叠
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 Agent 工具

工具	描述
get_project_context	获取单个脱敏快照，包含机密、环境、清单、钩子和近期审计活动
agent_remember	将非机密备注持久保存到加密的 Agent 记忆中，供不同会话使用
agent_recall	读取记忆值；如果未提供键，则列出所有已存储的键
agent_forget	永久删除 Agent 记忆中的键
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 策略对工具、键或 exec 操作进行试运行，不实际执行操作
get_policy_summary	概述策略规则数量以及审批和轮换要求
rotate_secret	请求上游提供方签发新凭据，并将其存回密钥环
ci_validate_secrets	批量验证范围内所有可访问的机密，并返回结构化的通过/失败报告

Cursor / Kiro 配置

将配置添加到 .cursor/mcp.json 或 .kiro/settings/mcp.json（也可以运行 qring setup cursor / qring setup kiro 让其写入）：

如果已全局安装 q-ring（例如 pnpm add -g @i4ctime/q-ring）：

{
  "mcpServers": {
    "q-ring": {
      "command": "qring-mcp"
    }
  }
}

如果使用本地克隆：

{
  "mcpServers": {
    "q-ring": {
      "command": "node",
      "args": ["/path/to/q-ring/dist/mcp.js"]
    }
  }
}

Claude Code 配置

将配置添加到项目根目录中的 .mcp.json，或运行 qring setup claude，或运行 claude mcp add q-ring -- qring-mcp（使用 claude_desktop_config.json 的是应用 Claude Desktop，而非 Claude Code）：

全局安装：

{
  "mcpServers": {
    "q-ring": {
      "command": "qring-mcp"
    }
  }
}

本地克隆：

{
  "mcpServers": {
    "q-ring": {
      "command": "node",
      "args": ["/path/to/q-ring/dist/mcp.js"]
    }
  }
}

VS Code 配置

VS Code 原生支持 MCP——将配置添加到 .vscode/mcp.json（注意使用 servers 键，而非 mcpServers）：

{
  "servers": {
    "q-ring": {
      "command": "qring-mcp"
    }
  }
}

qring setup 暂时不会写入此文件——VS Code 目前只能通过配置接入（没有官方插件包）。

编辑器插件

q-ring 仓库提供三个官方编辑器套件——每个套件都会为宿主编辑器添加规则/引导配置、Agent、命令、技能、钩子和 MCP 连接器。

插件	编辑器	亮点
cursor-plugin/	Cursor	3 条规则、5 项技能、2 个 Agent、8 条斜杠命令、3 个钩子、MCP 自动连接
kiro-plugin/	Kiro	官方 Power 布局：POWER.md、根目录中的 mcp.json、steering/、hooks/；也可使用 plugin:sync:kiro 扁平化
claude-code-plugin/	Claude Code	CLAUDE.md 记忆、项目 .mcp.json、2 个子 Agent、8 条斜杠命令、6 项技能、3 个钩子脚本

Cursor 插件

q-ring Cursor 插件通过规则、技能、Agent、命令、钩子和内置 MCP 连接器，将量子机密管理直接集成到 IDE 中。

组件	功能
3 条规则	始终生效的指导：绝不将机密硬编码，所有操作均使用 q-ring，并对 .env 文件发出警告
5 项技能	根据上下文自动触发：机密管理、扫描、轮换、项目接入、携带机密执行
2 个 Agent	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——可使用全部 46 个工具

可从 Cursor 市场安装，或参阅 cursor-plugin/README.md 进行手动设置。

Kiro 插件（Power）

kiro-plugin/ 目录是一个 Kiro Power，符合 创建 Power 的要求：POWER.md（元数据、接入指南、steering 映射）、根目录下的 mcp.json（MCP 服务必须与 Power 中引用的服务名称一致），以及用于工作流的 steering/。在 Kiro → Powers → Add power from Local Path 中选择 kiro-plugin 进行安装，或者在 GitHub 上发布该文件夹，然后使用 Add power from GitHub。

始终生效的 steering 会禁止硬编码机密，并将所有操作交由 q-ring 处理；manual steering 文件则作为 Agent 人设（#qring-secret-ops、#qring-security-auditor）、技能包和斜杠命令（#qring-cmd-scan-secrets 等）使用。可选钩子位于 hooks/ 中，可复制到 .kiro/hooks/。

# Alternative: flatten into ~/.kiro (settings + steering + hooks)
pnpm run plugin:sync:kiro

# Or scope to a single project
pnpm run plugin:sync:kiro -- /path/to/your/project/.kiro

完整说明请参阅 kiro-plugin/README.md。

Claude Code 插件

对于 Claude Code，q-ring 提供 CLAUDE.md 记忆文件、项目范围的 .mcp.json、两个子 Agent（secret-ops、security-auditor）、八条斜杠命令（/qring-scan-secrets、/qring-health-check、……）、六项技能和三个钩子（编辑后 Lint 提醒、Bash 执行前的 .env 防护、会话启动时的上下文预备）。

# Install into the current project ($PWD)
pnpm run plugin:sync:claude

# Install agents/commands/skills/hooks at user scope (~/.claude)
pnpm run plugin:sync:claude -- --user

# Or target a specific project
pnpm run plugin:sync:claude -- /path/to/your/project

已有的 CLAUDE.md、.mcp.json 或 .claude/settings.json 文件绝不会被静默覆盖——脚本会在这些文件旁创建 <filename>.qring-template，供你手动合并。传入 --force 可覆盖文件。

完整说明请参阅 claude-code-plugin/README.md。

架构

qring CLI ─────┐
               ├──▶ Core Engine ──▶ @napi-rs/keyring ──▶ OS Keyring
MCP Server ────┘       │
                       ├── Envelope (quantum metadata)
                       ├── Scope Resolver (global / project / team / org)
                       ├── Collapse (env detection + branchMap globs)
                       ├── Observer (tamper-evident audit chain)
                       ├── Policy (governance-as-code engine)
                       ├── Noise (secret generation)
                       ├── Entanglement (cross-secret linking)
                       ├── Validate (provider-based liveness + rotation)
                       ├── Hooks (shell/HTTP/signal callbacks)
                       ├── Import (.env file ingestion)
                       ├── Exec (profile-restricted injection + redaction)
                       ├── Scan (codebase entropy heuristics)
                       ├── Provision (JIT ephemeral credentials)
                       ├── Approval (HMAC-verified zero-trust tokens)
                       ├── Context (safe redacted project view)
                       ├── Linter (secret-aware code scanning)
                       ├── Memory (encrypted agent persistence)
                       ├── Tunnel (ephemeral in-memory)
                       ├── Teleport (encrypted sharing)
                       ├── Agent (autonomous monitor + rotation)
                       └── Dashboard (live status via SSE)

项目配置（.q-ring.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 key", "format": "api-key", "prefix": "sk-", "provider": "openai" },
    "DATABASE_URL": { "required": true, "description": "Postgres connection string", "validationUrl": "https://api.example.com/health" },
    "SENTRY_DSN": { "required": false, "description": "Sentry error tracking" }
  },
  "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 工具访问、密钥访问限制、exec 允许列表和机密生命周期要求

📚 文档

• 快速入门：Claude Code · Cursor · Kiro
• 故障排查 — 密钥环后端、MCP 连接、审批关卡、策略固定
• CLI ↔ MCP 对照 — 每条命令对应的 MCP 工具
• 发布 — 由标签驱动的发布流程

贡献

完整指南（开发环境、约定、需要保持同步的文件）请参阅 CONTRIBUTING.md。简要说明：

• 创建 PR 前，请运行 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。
  • Claude Code： pnpm run plugin:sync:claude 会将 claude-code-plugin/ 复制到当前目录（也可传入项目路径；添加 --user 可安装到 ~/.claude/）。
• 另请参阅 docs/cli-mcp-parity.md。

🔒 安全

• 本地优先。 核心存储位于你的操作系统密钥链中——没有 q-ring 云服务，也无需账户。MCP 接口、审计日志和 Agent 记忆都保存在你的计算机上（审计和记忆文件仅允许所有者访问，权限为 0600）。
• 已编写威胁模型。 q-ring 保护什么、不保护什么，以及剩余风险所在之处——包括对 Agent 数据外泄问题的坦诚回答——请参阅 docs/threat-model.md。
• 经过对抗性审查加固。 v0.14.0 发布了内部对抗性审计的结果——策略绕过、审批范围和执行配置文件方面的问题均已修复，且每项修复都附有回归测试。详情请参阅 CHANGELOG 的 Security 部分（自 0.12.0 起采用的惯例：先修复，再在此处披露）。
• 报告漏洞。 请使用 GitHub 私密漏洞报告——支持的版本表和响应承诺（48 小时内确认收到，7 天内评估）请参阅 SECURITY.md。

📜 许可证

AGPL-3.0 - 可免费使用、修改和分享。任何衍生作品或托管服务都必须以相同许可证发布其源代码。