用途:introspect 属于 Tier-1 实时只读内省,用于获取文件无法提供的运行时真相,例如真实索引使用情况、缺少索引的外键连接、表与行大小、RLS 状态、扩展、引擎版本以及 autovacuum/wraparound 状态。它是访问这些信息的唯一路径,且按约定只读。
连接方式:优先使用 DB MCP 服务器,权限边界更清晰,只调用名称匹配 query / read / list / describe / schema 的只读类工具;通用可写查询工具会经过同一只读校验器,并由 mcp__.* 上的 PreToolUse 钩子兜底。先列出可用工具,绝不调用会变更数据的工具。否则从环境变量 $DATABASE_URL 读取最小权限只读连接串,绝不回显,也不写入发现结果;redactSecrets() 会清除进入发现、报告或日志的任何凭据。两者都不可用时,对每个依赖检查输出 status: needs_api,并说明原因和所需的最小授权,绝不静默通过,也绝不编造行数、大小或执行计划。
只读契约(任何查询前强制执行):SET default_transaction_read_only = on; 设置有限的 statement_timeout(如 SET statement_timeout = '15s';);仅允许 SELECT / EXPLAIN(除计划外无 ANALYZE 写入副作用)/ 目录读取,其余一律拒绝。
读取的目录(不含行数据):Postgres 读取 version()、information_schema、pg_catalog、pg_class、pg_index、pg_indexes、pg_constraint、pg_policies、pg_extension;Tier-2 增加 pg_stat_user_indexes / pg_stat_user_tables、pg_stat_statements、age(datfrozenxid)。MySQL/MariaDB 读取 information_schema(TABLES、STATISTICS、KEY_COLUMN_USAGE)与 SHOW ENGINE INNODB STATUS(只读)。Mongo 使用 db.stats()、$indexStats、$collStats(Tier-2)。Cassandra 使用 system_schema、nodetool tablehistograms(Tier-2)。
对发现的影响:有实时证据的检查升级为 confidence: established,并可据此封顶评分(例如确认 int4/serial 主键接近耗尽、TXID wraparound 迫近、被依赖表上 RLS 关闭)。没有实时访问时,这些检查保持方向性结论或变为 needs_api,绝不单凭静态信号封顶。所有发现仍符合 schema/finding.schema.json;verification.reproduce 引用 $DATABASE_URL,绝不使用字面凭据。
输出:返回调用审计器所需的目录事实(索引清单、RLS 状态、版本、大小),并明确说明哪些检查仍为 needs_api 及原因。以用户语言(EN/ES)回复。限制:仅只读,不修改数据;需要 MCP 只读工具或 $DATABASE_URL;缺失时只能报告 needs_api。