pythia-setup

设置

开始时宣布：“正在使用 pythia-setup 配置数据库访问。”

**阶段：**执行 — 一次性搭建环境；之后的所有操作均按「学习 → 询问 → 执行」进行

请按以下顺序设置：先配置连接（其他一切都需要它），再配置最小权限用户（唯一无法绕过的保护），最后配置 SQLcl MCP（可选，仅用于读取）。

1. 连接

在项目根目录创建 .pythia/connections.json — pythia install 会生成该文件框架（通过 pip 安装时：pip install pythia-plsql），也可以从 克隆的仓库中复制 examples/connections.example.json。填写文件内容。pythia 应用以下规则：

• 只有一个条目：直接使用。多个条目：项目根目录下方的路径段决定选用哪个条目（root/DEV/... → DEV），否则使用顶层 "default": "<name>" 指定的条目。若存在歧义则报错，绝不猜测。
• --conn NAME 和 PYTHIA_CONNECTION 的优先级最高；PYTHIA_USER/PYTHIA_PASSWORD/PYTHIA_DSN 变量可绕过该文件。
• 该文件包含凭据：安装程序会将其写入 .gitignore（请提交该行）— 请保持此设置，并勿将其放入聊天内容或截图。若 Git 跟踪了该文件，pythia doctor 会失败。

运行 pythia check 进行验证：它会显示当前连接身份和对象数量。若失败，会指出连接名称以及需要检查的内容。

2. Agent 的数据库用户 — 真正的保护

策略文件是应用侧的防护措施；**Oracle 授权是 Agent 唯一无法绕过的保护层。**Oracle 没有简洁的逐对象授权方式来实现“可以在该架构中编辑 PL/SQL” — 编译到其他架构需要 CREATE ANY PROCEDURE，而该权限涵盖实例上的所有架构。

完整配置包含三个账户 — 管理员（仅用于管理）、所有者（架构所有者，绝不能是 DBA：代理会话会继承所有者持有的全部权限）、Agent（仅用于登录）— 详见 GUIDE 第 3 节和 examples/agent-user-setup.example.sql。其核心是代理身份验证：仅用于登录的用户通过架构所有者进行连接。Agent 永远不会获知所有者密码；撤销只需一条语句；审计记录会显示实际连接者；影响范围仅限一个开发架构。

在项目目录中运行一次 pythia agent-user --save。它会输出三条代理 SQL 语句，并生成密码，同时将匹配的凭据保存为连接 <conn>_agent（新的默认连接；所有者条目保持不变）。每次运行都会重新生成密码，因此绝不能先预览、之后再保存 — SQL 和已保存的配置必须来自同一次运行。将 SQL 原样转交开发人员，由 DBA 执行，然后运行 pythia check 进行验证。--json 会以机器可读格式输出相同结果。手动替代方案： examples/agent-user-setup.example.sql，请相应调整名称。

请遵循 Oracle 关于大模型访问的官方指导：授予最低限度的权限，绝不要让大模型连接生产数据库，并定期审计其活动。

若会话持有 %ANY% 权限或直接以架构所有者身份运行，pythia check 会用一行警告提示。目标状态是：没有警告。

3. SQLcl MCP 服务（可选，仅用于读取）

如果已安装 SQLcl 25.2+，Agent 可通过 Oracle 官方 MCP 服务读取数据：命令为 sql -mcp。客户端配置示例：

{"mcpServers": {"sqlcl": {"command": "sql", "args": ["-mcp"]}}}

• 保持默认限制级别（-R 4，限制最严格）：它会阻止主机命令和 @ 脚本。请注意，它不会阻止 run-sql 中的 DML/DDL — 因此写入操作绝不通过 MCP 执行：只有 pythia apply 具备快照、预览、验证和日志记录功能。
• 内置审计功能值得告知 DBA：每次交互都会记录到 DBTOOLS$MCP_LOG；V$SESSION.MODULE 会显示 MCP 客户端，V$SESSION.ACTION 会显示大模型名称；生成的 SQL 会包含 /* LLM in use */ 注释。

4. .pythia/ 中有什么，以及由什么创建

只有 connections.json 是由 install 写入的。其余文件会在你需要时创建，因此空的 .pythia/ 也能正常工作——在你需要它们之前，这里没有任何缺失。

文件	创建者	用途
connections.json	pythia install	连接信息。包含密码——绝不要打开它；pythia connections 会列出名称、用户、架构和目标，不含机密信息。安装时会将其添加到 .gitignore。
journal/	首次写入或创建快照时	每个捕获的版本，以及每条记录对应的可运行回滚操作。
conventions.json	pythia conventions --init	每种对象类型的命名模式。每次应用预览都会在新名称偏离模式时发出警告。
conventions.md	pythia conventions --init	用文字描述的团队规范。pythia-write 写入任何内容前都会先读取此文件，且其优先级高于此工具包附带的通用模式。
policy.json	pythia policy set <group> <value>	固定写入策略。文件不存在时会使用内置默认值，而默认值本身已是安全的。
settings.json	你手动创建	可选开关，例如 {"auto_snapshot": false}。

**记录团队规范是价值最高的可选步骤。**运行 pythia conventions --init，然后用实际模式替换占位模式——pythia similar <A_TYPICAL_NAME> 会展示架构已有的做法，比凭空设计一套规范更好。将违反后果明确的规则写入 conventions.md，并说明违反规则的代价；明确指出后果的规则更容易得到遵守。将这两个文件提交到项目仓库，让整个团队和每个 Agent 会话都遵循同一套规范。

5. 审批、钩子和环境 — pythia doctor

pythia install 会配置 Claude Code 钩子，在 .mcp.json 中注册 pythia_approve MCP 审批器（除 dontAsk 外，它会在每种权限模式下弹出提示的审批入口），并配置 Codex 对应项。重启后：

• pythia doctor — 检查每个钩子是否已配置且能够启动 pythia（无法导入 pythia 的钩子会默认放行：防护将关闭）；检查审批入口是否已注册；检查曾导致 AskUserQuestion 返回空结果的设置（允许规则、某个技能的 allowed-tools 中列出该工具、设置中的 PreToolUse 钩子捕获该工具，或已启用的插件）——目前会发出 warn 警告，因为当前的 Claude Code 无论如何都会要求显示对话框；还会检查 dontAsk，此项会导致 fail：两个聊天入口都会关闭。每条 fail 都表示防护或审批无法正常工作；请连同提示的文件一起转达。当前会话的 approval door 行会按此处可用的顺序列出审批入口。
• pythia doctor --db — 版本、字符集、PL/Scope 和编译器警告覆盖情况、INVALID 对象、utPLSQL。
• 在 connections.json 中将类似生产环境的连接标记为 "protected": true（或 "env": "prod"）：autopilot 随后会直接拒绝这些连接。

reference/environment.md 提供了稳健开发环境的完整检查清单：本地 Oracle Free 容器、AL32UTF8、编译器设置、共享架构卫生、utPLSQL，以及适合代码审查和自主工作的客户端权限模式。

完成标准

• pythia check 能够连接、显示正确的架构，且没有权限警告。
• pythia doctor 没有 fail 行。
• pythia policy 会打印写入策略和回滚表。
• 凭据文件未被跟踪（git status 中不会显示该文件）。