From 3b5308ab30833a64ef9c6ea6e2f0c43622d096a2 Mon Sep 17 00:00:00 2001
From: x_zhuo <12474586+zx06@users.noreply.github.com>
Date: Tue, 10 Feb 2026 15:58:03 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=87=E6=A1=A3=E5=AE=A1=E6=9F=A5?=
 =?UTF-8?q?=E4=BF=AE=E6=AD=A3=20+=20README=20=E5=A2=9E=E5=8A=A0=20npm=20?=
 =?UTF-8?q?=E5=AE=89=E8=A3=85=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

修正问题:
1. README.md: 增加 npm install -g xsql-cli 安装方式
2. README.md: 修正 proxy 命令示例参数顺序，与 cli-spec 保持一致
3. README.md: spec 命令描述补充 --format yaml 支持说明
4. npm/xsql/README.md: 修正用法示例，使用 -p profile 而非不存在的 --dsn
5. docs/architecture.md: 补充遗漏的 /internal/proxy 目录
6. docs/dev.md: 补充 proxy/ 和 tests/e2e/ 目录
7. docs/testing.md: 更新 E2E 测试目录结构（补充 7 个测试文件）
8. internal/app/app.go: 移除 spec 中不存在的 --read-only flag
---
 README.md            | 9 ++++++---
 docs/architecture.md | 1 +
 docs/dev.md          | 2 ++
 docs/testing.md      | 9 +++++++--
 internal/app/app.go  | 1 -
 npm/xsql/README.md   | 2 +-
 6 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 0b2667a..f2e33a7 100644
--- a/README.md
+++ b/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`，并会在本地监听端口，将流量转发到目标数据库。
diff --git a/docs/architecture.md b/docs/architecture.md
index c1240d4..6d0460f 100644
--- a/docs/architecture.md
+++ b/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       # 错误码/退出码/可机读错误
diff --git a/docs/dev.md b/docs/dev.md
index b571f9e..4775e99 100644
--- a/docs/dev.md
+++ b/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/              # 文档
 ```
diff --git a/docs/testing.md b/docs/testing.md
index 4cc0a59..1d3bc45 100644
--- a/docs/testing.md
+++ b/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 代理成功测试
 ```
 
 ### 运行测试
diff --git a/internal/app/app.go b/internal/app/app.go
index 80a04a4..9b76941 100644
--- a/internal/app/app.go
+++ b/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)"},
diff --git a/npm/xsql/README.md b/npm/xsql/README.md
index 5862050..e21dbd9 100644
--- a/npm/xsql/README.md
+++ b/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
 ```