docs: 文档审查修正 + README 增加 npm 安装说明

README.md

@@ -33,6 +33,9 @@ brew install zx06/tap/xsql
 # Windows
 scoop bucket add zx06 https://github.com/zx06/scoop-bucket && scoop install xsql
 
+# npm / npx
+npm install -g xsql-cli
+
 # 或直接下载: https://github.com/zx06/xsql/releases
 ```
 
@@ -153,7 +156,7 @@ xsql query "<SQL>" -p <profile> -f json
 | `xsql profile list` | 列出所有 profile |
 | `xsql profile show <name>` | 查看 profile 详情（密码脱敏） |
 | `xsql mcp server` | 启动 MCP Server（AI 助手集成） |
-| `xsql spec` | 导出 AI Tool Spec |
+| `xsql spec` | 导出 AI Tool Spec（支持 `--format yaml`） |
 | `xsql version` | 显示版本信息 |
 
 ### 输出格式
@@ -198,10 +201,10 @@ profiles:
 
 ```bash
 # 启动端口转发（自动分配本地端口）
-xsql -p prod proxy
+xsql proxy -p prod
 
 # 指定本地端口
-xsql -p prod proxy --local-port 13306
+xsql proxy -p prod --local-port 13306
 ```
 
 > 该命令要求 profile 配置 `ssh_proxy`，并会在本地监听端口，将流量转发到目标数据库。

docs/architecture.md

@@ -15,6 +15,7 @@
 /internal/db/pg        # PostgreSQL 驱动实现
 /internal/mcp          # MCP Server 实现
 /internal/ssh          # SSH proxy（driver dial，必要时回退端口转发）+ ssh_config（可选）
+/internal/proxy        # 端口转发代理（ssh -L 语义）
 /internal/output       # json/yaml/table/csv + 流式输出
 /internal/spec         # tool spec 导出（JSON schema）
 /internal/errors       # 错误码/退出码/可机读错误

docs/dev.md

@@ -100,10 +100,12 @@ internal/
   log/             # slog 日志
   mcp/             # MCP Server 实现
   output/          # json/yaml/table/csv 输出
+  proxy/           # 端口转发代理
   secret/          # keyring + 明文策略
   spec/            # tool spec 导出
   ssh/             # SSH client + dial
 tests/
+  e2e/             # E2E 测试
   integration/     # 集成测试（需要数据库）
 docs/              # 文档
 ```

docs/testing.md

@@ -207,8 +207,13 @@ func TestMain(m *testing.M) {
 ### 目录结构
 ```
 tests/e2e/
-  ├── e2e_test.go      # 共享 helper 和基础测试
-  └── profile_test.go  # profile 命令测试
+  ├── e2e_test.go                # 共享 helper 和基础设施
+  ├── mcp_test.go                # MCP Server 测试
+  ├── output_test.go             # 输出格式测试
+  ├── profile_test.go            # profile 命令测试
+  ├── proxy_test.go              # proxy 命令测试
+  ├── readonly_test.go           # 只读策略测试
+  └── ssh_proxy_success_test.go  # SSH 代理成功测试
 ```
 
 ### 运行测试

internal/app/app.go

@@ -39,7 +39,6 @@ func (a App) BuildSpec() spec.Spec {
 				Name:        "query",
 				Description: "Execute a read-only SQL query",
 				Flags: append(globalFlags,
-					spec.FlagSpec{Name: "read-only", Default: "true", Description: "Enforce read-only mode"},
 					spec.FlagSpec{Name: "unsafe-allow-write", Default: "false", Description: "Bypass read-only check (dangerous)"},
 					spec.FlagSpec{Name: "allow-plaintext", Default: "false", Description: "Allow plaintext secrets in config"},
 					spec.FlagSpec{Name: "ssh-skip-known-hosts-check", Default: "false", Description: "Skip SSH known_hosts check (dangerous)"},

npm/xsql/README.md

@@ -11,7 +11,7 @@ npm install -g xsql-cli
 ## Usage
 
 ```bash
-xsql query --dsn "mysql://user:pass@host:3306/db" "SELECT 1"
+xsql query "SELECT 1" -p dev -f json
 xsql version
 ```