xsql: Instructions file for Codex

AGENTS.md

本文件用于指导 AI agent / 自动化代码生成工具在 xsql 项目中进行一致、可维护、可扩展的开发。

1. 项目定位（必须理解）

• xsql：AI-first 的跨数据库 CLI 工具（Golang）。
• 核心目标：
  • 对 AI/agent 友好：稳定的机器可读输出、稳定错误码/退出码、可导出 tool spec。
  • 支持 MySQL/PostgreSQL，且 driver 架构可扩展。
  • 支持 Go 内实现 SSH proxy（driver 自定义 dial，必要时回退本地端口转发）。

任何改动都不得破坏既定的输出契约与错误码稳定性。

2. 文档是事实来源（Source of Truth）

实现前先阅读：

• docs/architecture.md
• docs/cli-spec.md
• docs/error-contract.md
• docs/config.md
• docs/env.md
• docs/db.md
• docs/ssh-proxy.md
• docs/ai.md
• docs/rfcs/ - RFC 文档目录

若实现与文档冲突：优先更新文档并说明原因，再实现。

强约束（Docs/RFC-first）：

• 以文档为准：实现必须与 docs/* 一致。
• 方案发生变化必须先改文档：任何会改变对外行为/契约/架构的变更，必须先通过文档（建议用 RFC）明确。
• 实现不得领先于文档：合并时必须保证"文档与实现一致"。
• RFC 维护位置：docs/rfcs/（见 docs/rfcs/README.md）。

3. 架构与目录约束（不要越界）

推荐结构（实现时请遵循）：

• cmd/xsql：CLI 入口（只做参数解析、调用 app、输出）
• internal/app：应用编排（核心入口，供 MCP/Web 等复用）
• internal/config：配置加载/合并/校验 + profile
• internal/secret：keyring/加密/明文兼容
• internal/db：driver registry + 执行引擎
• internal/mcp：MCP Server 实现
• internal/ssh：SSH proxy（driver dial/端口转发）+ ssh_config（可选）
• internal/output：json/yaml/table/csv + 流式写
• internal/errors：错误码/退出码/结构化错误
• internal/spec：tool spec 导出

强制规则：

• 核心逻辑不得依赖 CLI 框架类型（cobra 的 Command 等不应出现在 internal）。
• 输出/日志严格分流：stdout=数据，stderr=日志。

4. AI-first 输出与错误契约（强约束）

4.1 输出

• 成功：{"ok":true,...}
• 失败：{"ok":false,"error":{"code":"...","message":"...","details":{...}}}
• 非 TTY 默认 JSON；TTY 默认 table（详见 docs/cli-spec.md）。

4.2 错误码与退出码

• 必须集中在 internal/errors 维护（单一来源）。
• 退出码建议：0/2/3/4/5/10（详见 docs/cli-spec.md）。
• 新增错误码：
  1. 先在文档与代码的错误码表登记
  2. 保持向后兼容（只增不改、不复用旧含义）

5. 配置/ENV/CLI 合并规则（强约束）

• 优先级：CLI > ENV > Config。
• ENV 前缀：XSQL_。
• Secrets：默认使用 OS keyring；config 明文仅作为可选能力（详见 docs/config.md）。
• 不允许在日志/错误 details 中输出明文密码/私钥内容。

6. 数据库与只读策略（强约束）

• 目标数据库：MySQL + PostgreSQL。
• 可扩展性：通过 driver registry 扩展新 DB。
• 默认只读：防止误操作，默认启用双重只读保护（SQL 静态分析 + 数据库事务级只读）。
• CLI / MCP 写入双重授权：profile 必须配置 unsafe_allow_write: true，且当前 query 命令或 mcp server 必须同时携带 --unsafe-allow-write（或 XSQL_MCP_UNSAFE_ALLOW_WRITE=true）；任一条件缺失都保持只读。Web 始终强制只读。
• AI 调用标记：Codex 发起的 xsql CLI 调用必须携带 --attr source=codex-cli，建议同时追加 agent、env、team、task 等 attr；其他 AI 客户端应使用自己的稳定 source 值，且不得覆盖 source。
• 只读拦截必须返回明确错误码（退出码=4）。