kiro-gateway-cli 1.6.0 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +57 -7
  2. package/README_EN.md +72 -17
  3. package/dist/kiro-gateway.js +111 -89
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -32,12 +32,20 @@ node bin/kiro-gateway.js serve --port 9000
32
32
  node bin/kiro-gateway.js --host 127.0.0.1 --port 9000
33
33
 
34
34
  # 后台运行（守护进程）——立即返回
35
+ kiro-gateway start
36
+ kiro-gateway start --port 9000
35
37
  kiro-gateway serve --background
36
38
  kiro-gateway serve -b --port 9000
37
39
 
40
+ # 查看后台服务器运行状态（未运行时退出码为 1）
41
+ kiro-gateway status
42
+
38
43
  # 停止后台服务器（需在同一个目录下运行）
39
44
  kiro-gateway stop
40
45
 
46
+ # 升级到最新发布版本（底层执行 npm i -g kiro-gateway-cli）
47
+ kiro-gateway update
48
+
41
49
  # 全局安装（添加 kiro-gateway 命令）
42
50
  npm link
43
51
  kiro-gateway serve --port 9000
@@ -75,28 +83,70 @@ kiro-gateway serve \
75
83
 
76
84
  ### 后台运行
77
85
 
78
- `serve --background`（或 `-b`）会把服务器作为分离的守护进程启动，然后立即返回。父进程会等待服务器健康检查通过（/health 端点）并打印结果。
86
+ 三个子命令管理后台服务器：`start`（启动）、`status`（查看状态）、`stop`（停止）。
87
+ `serve --background`（或 `-b`）与 `start` 等价，会把服务器作为分离的守护进程启动，然后立即返回。父进程会等待服务器健康检查通过（/health 端点）并打印结果。
79
88
 
80
89
  ```bash
81
- kiro-gateway serve --background --port 9000
90
+ kiro-gateway start --port 9000
82
91
  # Starting server in the background (pid 12345)...
83
92
  # Server is running in the background: http://127.0.0.1:9000/health
93
+ # Check it with: kiro-gateway status
84
94
  # Stop it with: kiro-gateway stop
85
95
 
96
+ kiro-gateway status
97
+ # Kiro Gateway is running in the background (pid 12345).
98
+ # Health: http://127.0.0.1:9000/health (healthy)
99
+ # PID file: .kiro-gateway.pid
100
+ # Log file: kiro-gateway.log
101
+ # Stop it with: kiro-gateway stop
102
+
86
103
  kiro-gateway stop
87
104
  # Background server stopped (pid 12345).
88
105
  ```
89
106
 
90
- 守护进程状态文件（相对于工作目录，所以 `stop` 必须在启动 `serve --background` 的同一个目录下运行）：
107
+ `status` 的退出码：后台服务器在运行时为 `0`，未运行（无 pid 文件、进程已死或 pid 文件损坏）时为 `1`，方便脚本判断。健康检查使用当前配置的 `--host` / `--port`，所以如果后台服务器是用其他端口启动的，请用同样的 `--port` 运行 `status`，否则只会显示进程存活但 health 不响应。
108
+
109
+ 守护进程状态文件（相对于工作目录，所以 `status` / `stop` 必须在启动后台服务器的同一个目录下运行）：
91
110
 
92
111
  - `.kiro-gateway.pid` - 后台服务器的 PID（可用 `KIRO_PID_FILE` 覆盖）
93
112
  - `kiro-gateway.log` - 守护进程输出日志（可用 `KIRO_LOG_FILE` 覆盖）
94
113
 
95
114
  启动前 CLI 会检查目标端口是否空闲，如果已有其他服务在监听，会报错并给出可操作的提示。如果后台服务器在启动过程中退出（凭据错误、端口冲突等），CLI 会报告失败并显示日志末尾几行。
96
115
 
97
- ### Windows 平台说明
116
+ ### 升级版本
117
+
118
+ `update` 会先查询 npm registry 上的最新版本，然后执行全局安装：
119
+
120
+ ```bash
121
+ kiro-gateway update
122
+ # Updating kiro-gateway v1.7.0 -> v1.8.0...
123
+ # Updated kiro-gateway to v1.8.0.
124
+
125
+ # 已是最新版本时不会重复安装
126
+ kiro-gateway update
127
+ # kiro-gateway is already up to date (v1.8.0).
128
+ ```
129
+
130
+ 实际执行的命令是 `npm install -g kiro-gateway-cli@latest`。如果查询 registry 失败（离线、代理等），会直接安装最新版本，效果等同于手动执行该命令。
131
+
132
+ ### 跨平台说明（macOS / Windows / Linux）
133
+
134
+ 三平台都支持后台运行，行为差异如下：
135
+
136
+ | 项目 | macOS / Linux | Windows |
137
+ | --- | --- | --- |
138
+ | 启动方式 | 分离的守护进程，父进程退出后继续运行 | 同上，额外使用 `windowsHide` 隐藏控制台窗口 |
139
+ | 日志 | 子进程自己打开日志文件并接管 stdout/stderr | 同上（Win32 不能通过 `stdio` 继承任意文件描述符） |
140
+ | `stop` 语义 | 先发 `SIGTERM` 让服务器优雅关闭，8 秒未退出则 `SIGKILL` | 直接终止进程（Windows 没有 POSIX 信号，不会执行优雅退出处理器） |
141
+ | pid 文件清理 | 子进程优雅退出或 `stop` 时删除，删除失败会重试 | `stop` 父进程删除；遇到杀软/索引器占用会重试最多 6 次 |
142
+ | 权限不足 | 提示可能需要 `sudo` | 提示从同样权限（管理员）的命令行执行 |
143
+
144
+ 注意点：
98
145
 
99
- 后台运行在 Windows 上同样可用：子进程以无控制台窗口（`windowsHide`）方式启动，并自行把输出重定向到日志文件（Win32 不能通过 `stdio` 继承任意文件描述符）。一个注意点：Windows 没有 POSIX 信号，所以 `kiro-gateway stop` 会直接终止后台进程，而不会触发它的优雅退出处理器。pid 文件仍由 `stop` 清理，且每次 `start`/`stop` 都会校验 pid 文件对应的进程状态，非优雅终止也是安全的。
146
+ - `status` / `stop` 依据工作目录下的 pid 文件，必须在启动后台服务器的同一个目录运行。
147
+ - 无论哪个平台，`start` / `stop` / `status` 都会校验 pid 文件对应的进程是否存活，残留的 pid 文件会被自动清理，非优雅终止也是安全的。
148
+ - IPv4 与 IPv6 都支持：`--host ::1` 时展示和探测的地址会自动加方括号（`http://[::1]:8000/health`），`--host ::` 会探测 `::1`。
149
+ - 启动失败时（端口占用、地址不可用、凭据错误），父进程会打印日志尾部并清理 pid 文件，不会留下“幽灵”状态。
100
150
 
101
151
  ## 配置
102
152
 
@@ -114,8 +164,8 @@ kiro-gateway stop
114
164
  | `SERVER_HOST` / `SERVER_PORT` | 服务器监听地址 |
115
165
  | `VPN_PROXY_URL` | 受限网络下的代理：HTTP/HTTPS 或 SOCKS（`socks5://`、代理侧 DNS 用 `socks5h://`、`socks4a://`） |
116
166
  | `LOG_LEVEL` | `DEBUG`、`INFO`、`WARNING`、`ERROR`（默认：`INFO`） |
117
- | `KIRO_PID_FILE` | `--background` 模式的 PID 文件（默认：`.kiro-gateway.pid`） |
118
- | `KIRO_LOG_FILE` | `--background` 模式的日志文件（默认：`kiro-gateway.log`） |
167
+ | `KIRO_PID_FILE` | 后台模式的 PID 文件（默认：`.kiro-gateway.pid`） |
168
+ | `KIRO_LOG_FILE` | 后台模式的日志文件（默认：`kiro-gateway.log`） |
119
169
  | `ACCOUNT_SYSTEM` | 启用多账号故障切换（`true`/`false`） |
120
170
  | `FAKE_REASONING` | 通过标签注入实现扩展思考（默认：**关闭**）。Kiro 服务端会拦截思维链提取：模型一旦开始输出 `<thinking>` 块，该轮就以 `CONTENT_FILTERED` / `REASONING_EXTRACTION` 被终止，答案丢失。设为 `1` 可自行承担风险开启 |
121
171
  | `FIRST_TOKEN_TIMEOUT` | 重试前等待首个 token 的时间（默认：15 秒） |
package/README_EN.md CHANGED
@@ -34,12 +34,20 @@ node bin/kiro-gateway.js serve --port 9000
34
34
  node bin/kiro-gateway.js --host 127.0.0.1 --port 9000
35
35
 
36
36
  # Run in the background (daemon) - returns immediately
37
+ kiro-gateway start
38
+ kiro-gateway start --port 9000
37
39
  kiro-gateway serve --background
38
40
  kiro-gateway serve -b --port 9000
39
41
 
42
+ # Show the background server status (exit code 1 when not running)
43
+ kiro-gateway status
44
+
40
45
  # Stop the background server (run from the same directory)
41
46
  kiro-gateway stop
42
47
 
48
+ # Upgrade to the latest published version (runs npm i -g kiro-gateway-cli)
49
+ kiro-gateway update
50
+
43
51
  # Global install (adds the `kiro-gateway` command)
44
52
  npm link
45
53
  kiro-gateway serve --port 9000
@@ -79,22 +87,37 @@ starts the server the same way.
79
87
 
80
88
  ### Running in the background
81
89
 
82
- `serve --background` (or `-b`) starts the server as a detached daemon and
83
- returns immediately. The parent waits for the server to become healthy
84
- (health endpoint) and prints the result.
90
+ Three subcommands manage the background server: `start`, `status` and `stop`.
91
+ `serve --background` (or `-b`) is equivalent to `start`: it starts the server
92
+ as a detached daemon and returns immediately. The parent waits for the server
93
+ to become healthy (health endpoint) and prints the result.
85
94
 
86
95
  ```bash
87
- kiro-gateway serve --background --port 9000
96
+ kiro-gateway start --port 9000
88
97
  # Starting server in the background (pid 12345)...
89
98
  # Server is running in the background: http://127.0.0.1:9000/health
99
+ # Check it with: kiro-gateway status
90
100
  # Stop it with: kiro-gateway stop
91
101
 
102
+ kiro-gateway status
103
+ # Kiro Gateway is running in the background (pid 12345).
104
+ # Health: http://127.0.0.1:9000/health (healthy)
105
+ # PID file: .kiro-gateway.pid
106
+ # Log file: kiro-gateway.log
107
+ # Stop it with: kiro-gateway stop
108
+
92
109
  kiro-gateway stop
93
110
  # Background server stopped (pid 12345).
94
111
  ```
95
112
 
96
- Daemon state files (relative to the working directory, so `stop` must be run
97
- from the same directory as `serve --background`):
113
+ `status` exits with `0` while the background server is running and with `1`
114
+ when it is not (missing pid file, dead process, corrupted pid file), which
115
+ makes it usable in scripts. The health probe uses the configured
116
+ `--host` / `--port`, so pass the same `--port` the server was started with;
117
+ otherwise the process is reported as alive but the health check fails.
118
+
119
+ Daemon state files (relative to the working directory, so `status` and `stop`
120
+ must be run from the same directory as the start command):
98
121
 
99
122
  - `.kiro-gateway.pid` - PID of the background server (override: `KIRO_PID_FILE`)
100
123
  - `kiro-gateway.log` - daemon output (override: `KIRO_LOG_FILE`)
@@ -104,16 +127,48 @@ an actionable message when another service is already listening there. If the
104
127
  background server exits during startup (bad credentials, port conflict), the
105
128
  CLI reports the failure and shows the last log lines.
106
129
 
107
- ### Platform notes (Windows)
130
+ ### Upgrading
131
+
132
+ `update` checks the npm registry for the latest version and then performs a
133
+ global install:
134
+
135
+ ```bash
136
+ kiro-gateway update
137
+ # Updating kiro-gateway v1.7.0 -> v1.8.0...
138
+ # Updated kiro-gateway to v1.8.0.
108
139
 
109
- The daemon works on Windows too: the child is spawned without a console
110
- window (`windowsHide`) and redirects its output to the log file itself
111
- (Win32 cannot inherit arbitrary file descriptors via `stdio`). One caveat:
112
- Windows has no POSIX signals, so `kiro-gateway stop` terminates the
113
- background process directly instead of triggering its graceful shutdown
114
- handler. The pid file is still cleaned up by `stop`, and ungraceful
115
- termination is safe because the pid file is validated against the process
116
- state on every `start`/`stop`.
140
+ # Nothing is installed when already up to date
141
+ kiro-gateway update
142
+ # kiro-gateway is already up to date (v1.8.0).
143
+ ```
144
+
145
+ The command runs `npm install -g kiro-gateway-cli@latest`. If the registry
146
+ lookup fails (offline, proxy, ...), it installs the latest version anyway,
147
+ which is the same as running that command manually.
148
+
149
+ ### Platform notes (macOS / Windows / Linux)
150
+
151
+ The background mode works on all three platforms. Differences:
152
+
153
+ | Aspect | macOS / Linux | Windows |
154
+ | --- | --- | --- |
155
+ | Start | Detached daemon that survives the parent exit | Same, plus `windowsHide` so no console window flashes up |
156
+ | Logging | The child opens the log file itself and takes over stdout/stderr | Same (Win32 cannot inherit arbitrary file descriptors via `stdio`) |
157
+ | `stop` | `SIGTERM` first so the server shuts down gracefully; `SIGKILL` after 8s | Terminates the process directly (no POSIX signals, so shutdown handlers never run) |
158
+ | pid file cleanup | Removed by the child on graceful exit or by `stop`, with retries | Removed by `stop`; retried up to 6 times when antivirus/indexers hold the file |
159
+ | Permission error | Suggests `sudo` | Suggests running from an elevated prompt |
160
+
161
+ Caveats:
162
+
163
+ - `status` and `stop` rely on the pid file in the working directory, so run them
164
+ from the same directory the server was started in.
165
+ - On every platform `start`/`stop`/`status` validate the pid file against the
166
+ live process; stale pid files are removed automatically, so ungraceful
167
+ termination is safe.
168
+ - IPv4 and IPv6 both work: `--host ::1` is printed and probed with brackets
169
+ (`http://[::1]:8000/health`), and `--host ::` probes `::1`.
170
+ - When startup fails (port taken, address unavailable, bad credentials) the
171
+ parent prints the log tail and removes the pid file, leaving no ghost state.
117
172
 
118
173
  ## Configuration
119
174
 
@@ -132,8 +187,8 @@ environment variables:
132
187
  | `SERVER_HOST` / `SERVER_PORT` | Server binding |
133
188
  | `VPN_PROXY_URL` | Proxy for restricted networks: HTTP/HTTPS or SOCKS (`socks5://`, `socks5h://` for proxy-side DNS, `socks4a://`) |
134
189
  | `LOG_LEVEL` | `DEBUG`, `INFO`, `WARNING`, `ERROR` (default: `INFO`) |
135
- | `KIRO_PID_FILE` | PID file for `--background` mode (default: `.kiro-gateway.pid`) |
136
- | `KIRO_LOG_FILE` | Log file for `--background` mode (default: `kiro-gateway.log`) |
190
+ | `KIRO_PID_FILE` | PID file for background mode (default: `.kiro-gateway.pid`) |
191
+ | `KIRO_LOG_FILE` | Log file for background mode (default: `kiro-gateway.log`) |
137
192
  | `ACCOUNT_SYSTEM` | Enable multi-account failover (`true`/`false`) |
138
193
  | `FAKE_REASONING` | Extended thinking via tag injection (default: **disabled**). Kiro blocks reasoning extraction server-side: once the model opens a `<thinking>` block the turn comes back as `CONTENT_FILTERED` / `REASONING_EXTRACTION` and the answer is lost. Set to `1` to opt in at your own risk |
139
194
  | `FIRST_TOKEN_TIMEOUT` | First-token wait before retry (default: 15s) |