ace-tool-windows 0.1.6 → 0.2.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 (2) hide show
  1. package/README.md +266 -240
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,240 +1,266 @@
1
- # ace-tool-windows
2
-
3
- Rust + Win32 的 MCP Server（stdio），提供 `search_context` 与 `enhance_prompt`，用原生 Win32 GUI 替代浏览器交互。
4
-
5
- > 原项目：https://github.com/eastxiaodong/ace-tool
6
-
7
- ## 快速开始
8
-
9
- ### 1) 安装
10
-
11
- ```powershell
12
- npm i -g ace-tool-windows
13
- ```
14
-
15
- ### 2) 直接运行（本地验证）
16
-
17
- ```powershell
18
- ace-tool-win --base-url <URL> --token <TOKEN> [--enable-log]
19
- ```
20
-
21
- ### 3) 配置为 MCP Server
22
-
23
- > 不同 MCP 客户端字段名可能是 `mcpServers` 或 `servers`，以客户端文档为准。
24
-
25
- **mcpServers 格式（常见）**
26
-
27
- ```json
28
- {
29
- "mcpServers": {
30
- "ace-tool-windows": {
31
- "command": "ace-tool-win",
32
- "args": ["--base-url", "<URL>", "--token", "<TOKEN>", "--enable-log"]
33
- }
34
- }
35
- }
36
- ```
37
-
38
- **使用本地 exe 路径**
39
-
40
- ```json
41
- {
42
- "mcpServers": {
43
- "ace-tool-windows": {
44
- "command": "C:\\path\\to\\ace-tool-win.exe",
45
- "args": ["--base-url", "<URL>", "--token", "<TOKEN>"]
46
- }
47
- }
48
- }
49
- ```
50
-
51
- **servers 格式（兼容模式）**
52
-
53
- ```json
54
- {
55
- "servers": {
56
- "ace-tool-windows": {
57
- "command": "ace-tool-win",
58
- "args": ["--base-url", "<URL>", "--token", "<TOKEN>"]
59
- }
60
- }
61
- }
62
- ```
63
-
64
- 配置完成后，在 AI CLI 中输入 `xxxxx -enhancer` 即可触发 `enhance_prompt`（同样支持 `-enhancer`）。
65
-
66
- ## 项目简介
67
-
68
- 本仓库是 ace-tool 的 Rust + Win32 重写版本，目标与 Node 版本功能 1:1 对齐，同时保持 MCP stdio 兼容，供 Codex / MCP 客户端调用。
69
-
70
- ## 功能特性
71
-
72
- - MCP JSON-RPC over stdio，支持工具列举与调用
73
- - `search_context`：索引 + 检索代码库上下文
74
- - `enhance_prompt`：调用远端增强服务，支持中文/英文自动判断
75
- - Win32 GUI 交互窗口，提供继续增强 / 使用原始 / 结束对话
76
- - 本地索引与日志输出（`.ace-tool/`）
77
-
78
- ## 环境要求
79
-
80
- - Windows 10/11（Win32 GUI）
81
- - Rust 工具链（建议稳定版）
82
- - Node.js + npm（用于发布到 npm）
83
-
84
- ## 配置说明
85
-
86
- ### CLI 参数
87
-
88
- - `--base-url` 必填，服务地址；未写协议会自动补 `https://`
89
- - `--token` 必填，ACE 服务 Token
90
- - `--enable-log` 可选，写入 `.ace-tool/ace-tool.log`
91
-
92
- ### 环境变量（可选）
93
-
94
- - `ACE_TOOL_HEADLESS=1`：跳过 UI，直接返回增强结果
95
- - `ACE_TOOL_HEADLESS_ACTION=enhanced|end|timeout`：headless 模式返回策略，默认 enhanced
96
- - `ACE_TOOL_DEBUG=1`：输出 MCP 调试日志（stderr + 文件）
97
- - `ACE_TOOL_DEBUG_VERBOSE=1`：输出更详细的帧解析日志
98
- - `ACE_TOOL_DEBUG_FILE=<path>`：调试日志路径，默认 `%TEMP%\\ace-tool-mcp.log`
99
-
100
- ### 超时规则（重要）
101
-
102
- - 本项目默认不提供自定义超时参数。
103
- - MCP 调用超时以客户端（Codex）配置为准，例如 `tool_timeout_sec` / `startup_timeout_sec`。
104
- - 如需调整，请在 Codex 客户端配置中修改，不建议在服务端再做一套超时逻辑。
105
-
106
- ## MCP 工具说明
107
-
108
- ### search_context
109
-
110
- - 传入项目根路径与检索 query
111
- - 自动进行索引（`.ace-tool/index.json`）
112
- - 调用 `/agents/codebase-retrieval` 返回 formatted_retrieval
113
-
114
- ### enhance_prompt
115
-
116
- - 调用 `/prompt-enhancer`
117
- - 语言检测：中文输入 -> 中文输出；英文输入 -> 英文输出
118
- - 工具名映射：`codebase-retrieval` -> `search_context`
119
- - 8 分钟超时回退到原始 prompt
120
- - 默认弹 Win32 窗口，等待用户点击后返回
121
- - 如需无 UI，可设置 `ACE_TOOL_HEADLESS=1`
122
-
123
- ## 从源码运行
124
-
125
- ```powershell
126
- # 在仓库根目录
127
- cargo run -- --base-url <URL> --token <TOKEN> [--enable-log]
128
- ```
129
-
130
- ## npm 打包与发布
131
-
132
- 构建 + 拷贝 exe：
133
-
134
- ```powershell
135
- npm run build:bin
136
- ```
137
-
138
- 本地打包验证：
139
-
140
- ```powershell
141
- npm run pack:local
142
- ```
143
-
144
- 发布到 npm（首次需登录）：
145
-
146
- ```powershell
147
- npm publish --access public
148
- ```
149
-
150
- ## 项目结构
151
-
152
- ```text
153
- ace-tool-windows/
154
- - Cargo.toml
155
- - package.json
156
- - README.md
157
- - src/
158
- - main.rs
159
- - mcp/
160
- - index/
161
- - enhancer/
162
- - ui/
163
- - utils/
164
- - tests/
165
- ```
166
-
167
- ## 对齐清单（Node 版本）
168
-
169
- ### MCP 协议
170
- - [ ] 基于 stdio 的 JSON-RPC
171
- - [ ] ListTools 返回 search_context + enhance_prompt schema
172
- - [ ] CallTool 按名称分发并返回 content[].text
173
- - [ ] MCP logging 通道推送（level + data）
174
-
175
- ### CLI / 配置
176
- - [ ] 必填参数：--base-url、--token
177
- - [ ] 可选参数：--enable-log
178
- - [ ] base_url 自动规范化（必须 https，去掉末尾 /）
179
-
180
- ### 项目数据
181
- - [ ] 项目根目录创建 .ace-tool/
182
- - [ ] index.json 写入 .ace-tool/
183
- - [ ] --enable-log 时写入 ace-tool.log
184
- - [ ] .ace-tool 自动加入 .gitignore
185
-
186
- ### search_context 工具
187
- - [ ] project_root_path / query 输入校验
188
- - [ ] 路径统一为正斜杠
189
- - [ ] 目录存在性与类型检查
190
- - [ ] 检索前自动索引
191
- - [ ] POST {baseUrl}/agents/codebase-retrieval
192
- - [ ] 返回 formatted_retrieval 或友好错误信息
193
-
194
- ### 索引行为
195
- - [ ] 默认文本后缀与排除规则与 Node 一致
196
- - [ ] 读取编码兜底（utf-8、gbk、gb2312、latin1）
197
- - [ ] 二进制内容检测并跳过
198
- - [ ] 清洗控制字符
199
- - [ ] 按 maxLinesPerBlob 分片（默认 800）
200
- - [ ] Blob 名称 hash：SHA-256(path + content)
201
- - [ ] MAX_BLOB_SIZE：单 blob 500KB
202
- - [ ] MAX_BATCH_SIZE：单批 5MB
203
- - [ ] 基于 index.json 的增量索引
204
- - [ ] 按 blob 数量自适应上传策略（batch size + 并发）
205
- - [ ] 指数退避重试 + 友好错误映射
206
-
207
- ### enhance_prompt 工具
208
- - [ ] POST {baseUrl}/prompt-enhancer（payload 含 nodes/chat_history/blobs）
209
- - [ ] 语言检测（中文输入 -> 中文输出；英文输入 -> 英文输出）
210
- - [ ] 工具名映射：codebase-retrieval -> search_context
211
- - [ ] 8 分钟超时并回退到原始 prompt
212
-
213
- ### Win32 UI（替代浏览器 UI）
214
- - [ ] 四个动作：发送增强 / 使用原始 / 继续增强 / 结束对话
215
- - [ ] Session 状态：pending / completed / timeout
216
- - [ ] UI 与增强流程通过通道协作
217
-
218
- ### 错误提示
219
- - [ ] Token 无效（401）/ 访问被拒绝（403）
220
- - [ ] SSL 错误 / 非 https / DNS / 超时 / 连接被拒绝
221
- - [ ] 路径不存在 / 非目录 / 空索引
222
-
223
- ### 日志格式
224
- - [ ] MCP logging 推送（level + data）
225
- - [ ] 文件日志行格式："YYYY-MM-DD HH:MM:SS | LEVEL | message"
226
- - [ ] 新日志流写入 Session 分隔符
227
-
228
- ## 测试
229
-
230
- ```powershell
231
- cargo test
232
- ```
233
-
234
- ## License
235
-
236
- Apache-2.0
237
-
238
- ## 致谢
239
-
240
- - 原项目：ace-tool（https://github.com/eastxiaodong/ace-tool）
1
+ # ace-tool-windows
2
+
3
+ Rust + Win32 的 MCP Server（stdio），提供 `search_context` 与 `enhance_prompt`，用原生 Win32 GUI 替代浏览器交互。
4
+ ![alt text](image.png)
5
+
6
+ > 原项目：https://github.com/eastxiaodong/ace-tool
7
+
8
+ ## 快速开始
9
+
10
+ ### 1) 安装
11
+
12
+ ```powershell
13
+ npm i -g ace-tool-windows
14
+ ```
15
+
16
+ ### 2) 直接运行（本地验证）
17
+
18
+ ```powershell
19
+ ace-tool-win --base-url <URL> --token <TOKEN> [--enable-log]
20
+ ```
21
+
22
+ ### 3) 配置为 MCP Server
23
+
24
+ > 不同 MCP 客户端字段名可能是 `mcpServers` 或 `servers`，以客户端文档为准。
25
+
26
+ **mcpServers 格式（常见）**
27
+
28
+ ```json
29
+ {
30
+ "mcpServers": {
31
+ "ace-tool-windows": {
32
+ "command": "ace-tool-win",
33
+ "args": ["--base-url", "https://acemcp.heroman.wtf/relay/", "--token", "<TOKEN>"]
34
+ }
35
+ }
36
+ }
37
+ ```
38
+
39
+ **使用本地 exe 路径**
40
+
41
+ ```json
42
+ {
43
+ "mcpServers": {
44
+ "ace-tool-windows": {
45
+ "command": "C:\\path\\to\\ace-tool-win.exe",
46
+ "args": ["--base-url", "<URL>", "--token", "<TOKEN>"]
47
+ }
48
+ }
49
+ }
50
+ ```
51
+
52
+ **servers 格式（兼容模式）**
53
+
54
+ ```json
55
+ {
56
+ "servers": {
57
+ "ace-tool-windows": {
58
+ "command": "ace-tool-win",
59
+ "args": ["--base-url", "<URL>", "--token", "<TOKEN>"]
60
+ }
61
+ }
62
+ }
63
+ ```
64
+
65
+ ### 常见客户端配置示例
66
+
67
+ 以下仅展示配置片段，具体放置位置以对应客户端文档为准。
68
+
69
+ **Claude Code**
70
+
71
+ ```json
72
+ {
73
+ "mcpServers": {
74
+ "ace-tool-windows": {
75
+ "command": "ace-tool-win",
76
+ "args": ["--base-url", "https://acemcp.heroman.wtf/relay/", "--token", "<TOKEN>"]
77
+ }
78
+ }
79
+ }
80
+ ```
81
+
82
+ **Codex CLI（codex）**
83
+
84
+ ```toml
85
+ [mcpServers."ace-tool-windows"]
86
+ command = "ace-tool-win"
87
+ args = ["--base-url", "https://acemcp.heroman.wtf/relay/", "--token", "<TOKEN>"]
88
+ ```
89
+
90
+ 配置完成后，在 AI CLI 中输入 `xxxxx -enhancer` 即可触发 `enhance_prompt`（同样支持 `-enhancer`）。
91
+
92
+ ## 项目简介
93
+
94
+ 本仓库是 ace-tool 的 Rust + Win32 重写版本，目标与 Node 版本功能 1:1 对齐，同时保持 MCP stdio 兼容，供 Codex / MCP 客户端调用。
95
+
96
+ ## 功能特性
97
+
98
+ - MCP JSON-RPC over stdio，支持工具列举与调用
99
+ - `search_context`：索引 + 检索代码库上下文
100
+ - `enhance_prompt`：调用远端增强服务，支持中文/英文自动判断
101
+ - Win32 GUI 交互窗口，提供继续增强 / 使用原始 / 结束对话
102
+ - 本地索引与日志输出（`.ace-tool/`）
103
+
104
+ ## 环境要求
105
+
106
+ - Windows 10/11（Win32 GUI）
107
+ - Rust 工具链（建议稳定版）
108
+ - Node.js + npm（用于发布到 npm）
109
+
110
+ ## 配置说明
111
+
112
+ ### CLI 参数
113
+
114
+ - `--base-url` 必填，服务地址；未写协议会自动补 `https://`
115
+ - `--token` 必填，ACE 服务 Token（在 https://acemcp.heroman.wtf 获取）
116
+ - `--enable-log` 可选，写入 `.ace-tool/ace-tool.log`
117
+
118
+ ### 环境变量（可选）
119
+
120
+ - `ACE_TOOL_HEADLESS=1`：跳过 UI，直接返回增强结果
121
+ - `ACE_TOOL_HEADLESS_ACTION=enhanced|end|timeout`：headless 模式返回策略，默认 enhanced
122
+ - `ACE_TOOL_DEBUG=1`：输出 MCP 调试日志（stderr + 文件）
123
+ - `ACE_TOOL_DEBUG_VERBOSE=1`：输出更详细的帧解析日志
124
+ - `ACE_TOOL_DEBUG_FILE=<path>`：调试日志路径，默认 `%TEMP%\\ace-tool-mcp.log`
125
+
126
+ ### 超时规则（重要）
127
+
128
+ - 本项目默认不提供自定义超时参数。
129
+ - MCP 调用超时以客户端（Codex）配置为准，例如 `tool_timeout_sec` / `startup_timeout_sec`。
130
+ - 如需调整，请在 Codex 客户端配置中修改，不建议在服务端再做一套超时逻辑。
131
+
132
+ ## MCP 工具说明
133
+
134
+ ### search_context
135
+
136
+ - 传入项目根路径与检索 query
137
+ - 自动进行索引（`.ace-tool/index.json`）
138
+ - 调用 `/agents/codebase-retrieval` 返回 formatted_retrieval
139
+
140
+ ### enhance_prompt
141
+
142
+ - 调用 `/prompt-enhancer`
143
+ - 语言检测：中文输入 -> 中文输出；英文输入 -> 英文输出
144
+ - 工具名映射：`codebase-retrieval` -> `search_context`
145
+ - 8 分钟超时回退到原始 prompt
146
+ - 默认弹 Win32 窗口，等待用户点击后返回
147
+ - 如需无 UI，可设置 `ACE_TOOL_HEADLESS=1`
148
+
149
+ ## 从源码运行
150
+
151
+ ```powershell
152
+ # 在仓库根目录
153
+ cargo run -- --base-url <URL> --token <TOKEN> [--enable-log]
154
+ ```
155
+
156
+ ## npm 打包与发布
157
+
158
+ 构建 + 拷贝 exe：
159
+
160
+ ```powershell
161
+ npm run build:bin
162
+ ```
163
+
164
+ 本地打包验证：
165
+
166
+ ```powershell
167
+ npm run pack:local
168
+ ```
169
+
170
+ 发布到 npm（首次需登录）：
171
+
172
+ ```powershell
173
+ npm publish --access public
174
+ ```
175
+
176
+ ## 项目结构
177
+
178
+ ```text
179
+ ace-tool-windows/
180
+ - Cargo.toml
181
+ - package.json
182
+ - README.md
183
+ - src/
184
+ - main.rs
185
+ - mcp/
186
+ - index/
187
+ - enhancer/
188
+ - ui/
189
+ - utils/
190
+ - tests/
191
+ ```
192
+
193
+ ## 对齐清单（Node 版本）
194
+
195
+ ### MCP 协议
196
+ - [ ] 基于 stdio 的 JSON-RPC
197
+ - [ ] ListTools 返回 search_context + enhance_prompt schema
198
+ - [ ] CallTool 按名称分发并返回 content[].text
199
+ - [ ] MCP logging 通道推送（level + data）
200
+
201
+ ### CLI / 配置
202
+ - [ ] 必填参数：--base-url、--token
203
+ - [ ] 可选参数：--enable-log
204
+ - [ ] base_url 自动规范化（必须 https，去掉末尾 /）
205
+
206
+ ### 项目数据
207
+ - [ ] 项目根目录创建 .ace-tool/
208
+ - [ ] index.json 写入 .ace-tool/
209
+ - [ ] --enable-log 时写入 ace-tool.log
210
+ - [ ] .ace-tool 自动加入 .gitignore
211
+
212
+ ### search_context 工具
213
+ - [ ] project_root_path / query 输入校验
214
+ - [ ] 路径统一为正斜杠
215
+ - [ ] 目录存在性与类型检查
216
+ - [ ] 检索前自动索引
217
+ - [ ] POST {baseUrl}/agents/codebase-retrieval
218
+ - [ ] 返回 formatted_retrieval 或友好错误信息
219
+
220
+ ### 索引行为
221
+ - [ ] 默认文本后缀与排除规则与 Node 一致
222
+ - [ ] 读取编码兜底（utf-8、gbk、gb2312、latin1）
223
+ - [ ] 二进制内容检测并跳过
224
+ - [ ] 清洗控制字符
225
+ - [ ] 按 maxLinesPerBlob 分片（默认 800）
226
+ - [ ] Blob 名称 hash：SHA-256(path + content)
227
+ - [ ] MAX_BLOB_SIZE：单 blob 500KB
228
+ - [ ] MAX_BATCH_SIZE：单批 5MB
229
+ - [ ] 基于 index.json 的增量索引
230
+ - [ ] 按 blob 数量自适应上传策略（batch size + 并发）
231
+ - [ ] 指数退避重试 + 友好错误映射
232
+
233
+ ### enhance_prompt 工具
234
+ - [ ] POST {baseUrl}/prompt-enhancer（payload 含 nodes/chat_history/blobs）
235
+ - [ ] 语言检测（中文输入 -> 中文输出；英文输入 -> 英文输出）
236
+ - [ ] 工具名映射：codebase-retrieval -> search_context
237
+ - [ ] 8 分钟超时并回退到原始 prompt
238
+
239
+ ### Win32 UI（替代浏览器 UI）
240
+ - [ ] 四个动作：发送增强 / 使用原始 / 继续增强 / 结束对话
241
+ - [ ] Session 状态：pending / completed / timeout
242
+ - [ ] UI 与增强流程通过通道协作
243
+
244
+ ### 错误提示
245
+ - [ ] Token 无效（401）/ 访问被拒绝（403）
246
+ - [ ] SSL 错误 / 非 https / DNS / 超时 / 连接被拒绝
247
+ - [ ] 路径不存在 / 非目录 / 空索引
248
+
249
+ ### 日志格式
250
+ - [ ] MCP logging 推送（level + data）
251
+ - [ ] 文件日志行格式："YYYY-MM-DD HH:MM:SS | LEVEL | message"
252
+ - [ ] 新日志流写入 Session 分隔符
253
+
254
+ ## 测试
255
+
256
+ ```powershell
257
+ cargo test
258
+ ```
259
+
260
+ ## License
261
+
262
+ Apache-2.0
263
+
264
+ ## 致谢
265
+
266
+ - 原项目：ace-tool（https://github.com/eastxiaodong/ace-tool）
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ace-tool-windows",
3
- "version": "0.1.6",
3
+ "version": "0.2.0",
4
4
  "description": "ACE MCP server for Windows (Win32)",
5
5
  "bin": {
6
6
  "ace-tool-win": "bin/ace-tool-win.exe"