npm - ace-tool-windows - Versions diffs - 0.2.5 → 0.2.7 - Mend

ace-tool-windows 0.2.5 → 0.2.7

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 (3) hide show

package/README.md CHANGED Viewed

@@ -1,266 +1,249 @@
-# ace-tool-windows
-Rust + Win32 的 MCP Server（stdio），提供 `search_context` 与 `enhance_prompt`，用原生 Win32 GUI 替代浏览器交互。
-![alt text](image.png)
-> 原项目：https://github.com/eastxiaodong/ace-tool
-## 快速开始
-### 1) 安装
-```powershell
-npm i -g ace-tool-windows
-```
-### 2) 直接运行（本地验证）
-```powershell
-ace-tool-win --base-url <URL> --token <TOKEN> [--enable-log]
-```
-### 3) 配置为 MCP Server
-> 不同 MCP 客户端字段名可能是 `mcpServers` 或 `servers`，以客户端文档为准。
-**mcpServers 格式（常见）**
-```json
-{
-  "mcpServers": {
-    "ace-tool-windows": {
-      "command": "ace-tool-win",
-      "args": ["--base-url", "https://acemcp.heroman.wtf/relay/", "--token", "<TOKEN>"]
-    }
-  }
-}
-```
-**使用本地 exe 路径**
-```json
-{
-  "mcpServers": {
-    "ace-tool-windows": {
-      "command": "C:\\path\\to\\ace-tool-win.exe",
-      "args": ["--base-url", "<URL>", "--token", "<TOKEN>"]
-    }
-  }
-}
-```
-**servers 格式（兼容模式）**
-```json
-{
-  "servers": {
-    "ace-tool-windows": {
-      "command": "ace-tool-win",
-      "args": ["--base-url", "<URL>", "--token", "<TOKEN>"]
-    }
-  }
-}
-```
-### 常见客户端配置示例
-以下仅展示配置片段，具体放置位置以对应客户端文档为准。
-**Claude Code**
-```json
-{
-  "mcpServers": {
-    "ace-tool-windows": {
-      "command": "ace-tool-win",
-      "args": ["--base-url", "https://acemcp.heroman.wtf/relay/", "--token", "<TOKEN>"]
-    }
-  }
-}
-```
-**Codex CLI（codex）**
-```toml
-[mcpServers."ace-tool-windows"]
-command = "ace-tool-win"
-args = ["--base-url", "https://acemcp.heroman.wtf/relay/", "--token", "<TOKEN>"]
-```
-配置完成后，在 AI CLI 中输入 `xxxxx -enhancer` 即可触发 `enhance_prompt`（同样支持 `-enhancer`）。
-## 项目简介
-本仓库是 ace-tool 的 Rust + Win32 重写版本，目标与 Node 版本功能 1:1 对齐，同时保持 MCP stdio 兼容，供 Codex / MCP 客户端调用。
-## 功能特性
-- MCP JSON-RPC over stdio，支持工具列举与调用
-- `search_context`：索引 + 检索代码库上下文
-- `enhance_prompt`：调用远端增强服务，支持中文/英文自动判断
-- Win32 GUI 交互窗口，提供继续增强 / 使用原始 / 结束对话
-- 本地索引与日志输出（`.ace-tool/`）
-## 环境要求
-- Windows 10/11（Win32 GUI）
-- Rust 工具链（建议稳定版）
-- Node.js + npm（用于发布到 npm）
-## 配置说明
-### CLI 参数
-- `--base-url` 必填，服务地址；未写协议会自动补 `https://`
-- `--token` 必填，ACE 服务 Token（在 https://acemcp.heroman.wtf 获取）
-- `--enable-log` 可选，写入 `.ace-tool/ace-tool.log`
-### 环境变量（可选）
-- `ACE_TOOL_HEADLESS=1`：跳过 UI，直接返回增强结果
-- `ACE_TOOL_HEADLESS_ACTION=enhanced|end|timeout`：headless 模式返回策略，默认 enhanced
-- `ACE_TOOL_DEBUG=1`：输出 MCP 调试日志（stderr + 文件）
-- `ACE_TOOL_DEBUG_VERBOSE=1`：输出更详细的帧解析日志
-- `ACE_TOOL_DEBUG_FILE=<path>`：调试日志路径，默认 `%TEMP%\\ace-tool-mcp.log`
-### 超时规则（重要）
-- 本项目默认不提供自定义超时参数。
-- MCP 调用超时以客户端（Codex）配置为准，例如 `tool_timeout_sec` / `startup_timeout_sec`。
-- 如需调整，请在 Codex 客户端配置中修改，不建议在服务端再做一套超时逻辑。
-## MCP 工具说明
-### search_context
-- 传入项目根路径与检索 query
-- 自动进行索引（`.ace-tool/index.json`）
-- 调用 `/agents/codebase-retrieval` 返回 formatted_retrieval
-### enhance_prompt
-- 调用 `/prompt-enhancer`
-- 语言检测：中文输入 -> 中文输出；英文输入 -> 英文输出
-- 工具名映射：`codebase-retrieval` -> `search_context`
-- 8 分钟超时回退到原始 prompt
-- 默认弹 Win32 窗口，等待用户点击后返回
-- 如需无 UI，可设置 `ACE_TOOL_HEADLESS=1`
-## 从源码运行
-```powershell
-# 在仓库根目录
-cargo run -- --base-url <URL> --token <TOKEN> [--enable-log]
-```
-## npm 打包与发布
-构建 + 拷贝 exe：
-```powershell
-npm run build:bin
-```
-本地打包验证：
-```powershell
-npm run pack:local
-```
-发布到 npm（首次需登录）：
-```powershell
-npm publish --access public
-```
-## 项目结构
-```text
-ace-tool-windows/
-- Cargo.toml
-- package.json
-- README.md
-- src/
-  - main.rs
-  - mcp/
-  - index/
-  - enhancer/
-  - ui/
-  - utils/
-- tests/
-```
-## 对齐清单（Node 版本）
-### MCP 协议
-- [ ] 基于 stdio 的 JSON-RPC
-- [ ] ListTools 返回 search_context + enhance_prompt schema
-- [ ] CallTool 按名称分发并返回 content[].text
-- [ ] MCP logging 通道推送（level + data）
-### CLI / 配置
-- [ ] 必填参数：--base-url、--token
-- [ ] 可选参数：--enable-log
-- [ ] base_url 自动规范化（必须 https，去掉末尾 /）
-### 项目数据
-- [ ] 项目根目录创建 .ace-tool/
-- [ ] index.json 写入 .ace-tool/
-- [ ] --enable-log 时写入 ace-tool.log
-- [ ] .ace-tool 自动加入 .gitignore
-### search_context 工具
-- [ ] project_root_path / query 输入校验
-- [ ] 路径统一为正斜杠
-- [ ] 目录存在性与类型检查
-- [ ] 检索前自动索引
-- [ ] POST {baseUrl}/agents/codebase-retrieval
-- [ ] 返回 formatted_retrieval 或友好错误信息
-### 索引行为
-- [ ] 默认文本后缀与排除规则与 Node 一致
-- [ ] 读取编码兜底（utf-8、gbk、gb2312、latin1）
-- [ ] 二进制内容检测并跳过
-- [ ] 清洗控制字符
-- [ ] 按 maxLinesPerBlob 分片（默认 800）
-- [ ] Blob 名称 hash：SHA-256(path + content)
-- [ ] MAX_BLOB_SIZE：单 blob 500KB
-- [ ] MAX_BATCH_SIZE：单批 5MB
-- [ ] 基于 index.json 的增量索引
-- [ ] 按 blob 数量自适应上传策略（batch size + 并发）
-- [ ] 指数退避重试 + 友好错误映射
-### enhance_prompt 工具
-- [ ] POST {baseUrl}/prompt-enhancer（payload 含 nodes/chat_history/blobs）
-- [ ] 语言检测（中文输入 -> 中文输出；英文输入 -> 英文输出）
-- [ ] 工具名映射：codebase-retrieval -> search_context
-- [ ] 8 分钟超时并回退到原始 prompt
-### Win32 UI（替代浏览器 UI）
-- [ ] 四个动作：发送增强 / 使用原始 / 继续增强 / 结束对话
-- [ ] Session 状态：pending / completed / timeout
-- [ ] UI 与增强流程通过通道协作
-### 错误提示
-- [ ] Token 无效（401）/ 访问被拒绝（403）
-- [ ] SSL 错误 / 非 https / DNS / 超时 / 连接被拒绝
-- [ ] 路径不存在 / 非目录 / 空索引
-### 日志格式
-- [ ] MCP logging 推送（level + data）
-- [ ] 文件日志行格式："YYYY-MM-DD HH:MM:SS | LEVEL | message"
-- [ ] 新日志流写入 Session 分隔符
-## 测试
-```powershell
-cargo test
-```
-## License
+# ace-tool-windows
+Windows 平台的 ACE MCP Server（Rust + Win32，stdio 模式），提供 `search_context` 与 `enhance_prompt`。
+> 原项目：<https://github.com/eastxiaodong/ace-tool>
+## 1. 安装
+```powershell
+npm i -g ace-tool-windows
+```
+## 2. 获取 Token
+在 <https://acemcp.heroman.wtf> 生成并复制 `token`。
+建议：
+- 不要把 token 提交到 Git 仓库。
+- 优先通过环境变量或本地 MCP 配置注入。
+- 即便使用 `codex` provider，`search_context` 仍依赖远端服务，必须配置 token。
+## 3. 模式速览（先选一个）
+### 3.1 `remote` 模式
+- 适合：不依赖本机 `codex` CLI，开箱可用。
+- 依赖：远端 token/credits。
+- 启动示例：
+```powershell
+ace-tool-win --base-url https://acemcp.heroman.wtf/relay/ --token <YOUR_TOKEN> --provider remote
+```
+### 3.2 `codex` 模式
+- 适合：希望本地走 Codex 增强，避免远端增强额度影响。
+- 依赖：本机可执行 `codex` CLI（`codex --version` 可用）。
+- 启动示例：
+```powershell
+ace-tool-win --base-url https://acemcp.heroman.wtf/relay/ --token <YOUR_TOKEN> --provider codex --codex-cmd codex --codex-reasoning-effort low
+```
+关键说明：
+- `search_context` 始终走远端，所以即便是 `codex` 模式也必须有可用 token。
+- `codex_cmd` 推荐先用 `codex`（PATH 方案，跨设备更稳），确实找不到再写绝对路径。
+- 交互窗口支持自适应布局；Codex 首轮超时会自动重试一次 `reasoning_effort=none`。
+## 4. MCP 配置模板（按模式复制）
+### 4.1 `remote` 模式模板
+JSON（适用于支持 `mcpServers` 的客户端）：
+```json
+{
+  "mcpServers": {
+    "ace-tool-windows": {
+      "command": "ace-tool-win",
+      "args": [
+        "--base-url", "https://acemcp.heroman.wtf/relay/",
+        "--token", "<YOUR_TOKEN>",
+        "--provider", "remote"
+      ]
+    }
+  }
+}
+```
+TOML（Codex CLI）：
+```toml
+[mcpServers."ace-tool-windows"]
+command = "ace-tool-win"
+args = [
+  "--base-url", "https://acemcp.heroman.wtf/relay/",
+  "--token", "<YOUR_TOKEN>",
+  "--provider", "remote"
+]
+```
+### 4.2 `codex` 模式模板
+JSON（适用于支持 `mcpServers` 的客户端）：
+```json
+{
+  "mcpServers": {
+    "ace-tool-windows": {
+      "command": "ace-tool-win",
+      "args": [
+        "--base-url", "https://acemcp.heroman.wtf/relay/",
+        "--token", "<YOUR_TOKEN>",
+        "--provider", "codex",
+        "--codex-cmd", "codex",
+        "--codex-reasoning-effort", "low"
+      ]
+    }
+  }
+}
+```
+TOML（Codex CLI）：
+```toml
+[mcpServers."ace-tool-windows"]
+command = "ace-tool-win"
+args = [
+  "--base-url", "https://acemcp.heroman.wtf/relay/",
+  "--token", "<YOUR_TOKEN>",
+  "--provider", "codex",
+  "--codex-cmd", "codex",
+  "--codex-reasoning-effort", "low"
+]
+```
+## 5. Provider 行为（当前版本）
+- 启动时确定 provider：`--provider` / `ACE_TOOL_ENHANCE_PROVIDER`，默认 `remote`。
+- 请求参数里的 `provider` 仅作为提示，不用于切换模式。
+- 如果请求里的 `provider` 与启动 provider 不一致，会自动忽略，仍以启动 provider 为准。
+- 不会再自动从 `codex` 降级到 `remote`。
+## 6. 在 AI CLI 中触发增强
+配置好 MCP 后，输入包含 `-enhance` 或 `-enhancer` 的请求即可触发 `enhance_prompt`。
+示例：
+```text
+为当前项目的代码添加详细注释 -enhance
+```
+补充：
+- 用户输入里的触发后缀（`-enhance` / `-enhancer`）会在增强前自动剥离，不会进入最终增强文本。
+- 若本次调用的 `prompt` 仅包含触发后缀，服务端会自动回退到 `conversation_history` 提取可用提示，不再直接报错中断。
+- 工具入口统一为 `enhance_prompt`，避免同义工具名导致重复触发。
+- 服务端会对短时间内完全相同的增强请求做去重（约 180 秒），避免“窗口刚关又被同参再次拉起”。
+- 增强文本采用“语义自适应”排版：在不改变语义前提下提升细节和可读性，不强制固定模板。
+## 7. 环境变量（按模式）
+### 7.1 `remote` 模式
+```powershell
+$env:ACE_TOOL_ENHANCE_PROVIDER = "remote"
+```
+### 7.2 `codex` 模式
+```powershell
+$env:ACE_TOOL_ENHANCE_PROVIDER = "codex"
+$env:ACE_TOOL_CODEX_CMD = "codex"
+$env:ACE_TOOL_CODEX_REASONING_EFFORT = "low"
+```
+### 7.3 通用变量
+- `ACE_TOOL_ENHANCE_TIMEOUT_SEC=90`（范围 10-600；未显式配置时 `remote` 默认 90 秒，`codex` 默认 180 秒）
+- `ACE_TOOL_UI_TIMEOUT_SEC=480`（范围 30-3600）
+- `ACE_TOOL_HEADLESS=1`
+- `ACE_TOOL_HEADLESS_ACTION=enhanced|end|timeout`
+- `ACE_TOOL_DEBUG=1`
+- `ACE_TOOL_DEBUG_VERBOSE=1`
+- `ACE_TOOL_DEBUG_FILE=<path>`
+## 8. 超时规则
+- `--enhance-timeout-sec` / `ACE_TOOL_ENHANCE_TIMEOUT_SEC`：增强请求超时，范围 10-600 秒；未显式配置时 `remote` 默认 90 秒，`codex` 默认 180 秒。
+- `--ui-timeout-sec` / `ACE_TOOL_UI_TIMEOUT_SEC`：UI 会话超时（默认 480 秒，范围 30-3600）。
+- 超出范围的配置会回退到默认值。
+- 交互模式下 UI 超时会回退到原始 prompt；headless 模式不显示 UI，由 `ACE_TOOL_HEADLESS_ACTION` 决定动作。
+- `codex` provider 在首轮超时时会自动重试一次（`reasoning_effort=none`），用于降低“首次增强卡住”的概率。
+## 9. 故障排查
+### 9.1 MCP 启动超时 / 连接失败
+检查项：
+- 必须使用 stdio 模式。
+- `command` 路径可执行（绝对路径优先）。
+- `--base-url` 与 `--token` 是否正确。
+- 开启 `ACE_TOOL_DEBUG=1` 查看日志链路。
+### 9.2 窗口不弹出或卡住
+检查项：
+- 是否启用了 `ACE_TOOL_HEADLESS=1`。
+- Windows 权限或安全软件是否拦截窗口创建。
+- 调试日志中是否出现 `enhance_prompt: opening ui`。
+### 9.3 Token 认证失败
+典型返回：401 / 403。
+处理：
+- 到 <https://acemcp.heroman.wtf> 重新生成 token。
+- 更新 MCP 配置后重启客户端。
+### 9.4 中文显示异常 / 乱码
+当前版本已增加 UTF-8/BOM/GBK 等解码兜底。若仍异常：
+- 确认终端与编辑器编码为 UTF-8。
+- 打开 `ACE_TOOL_DEBUG=1`，附带日志定位具体节点。
+### 9.5 Codex provider 无法执行 / 退出码非 0
+检查项：
+- `--codex-cmd` 是否指向可执行文件，PATH 是否包含 `codex`。
+- 使用相同命令在终端直接执行一次，确认 CLI 可运行。
+- 开启 `ACE_TOOL_DEBUG=1` 查看退出码与错误类型（timeout/auth/network 等）。
+### 9.6 Codex 首次增强慢 / 高概率超时
+检查项：
+- 日志是否长时间停在 `mcp: mcp-router starting`（已默认禁用内部 mcp-router；若仍出现，确认当前进程已重启到新版本）。
+- 将 `--codex-reasoning-effort` 临时降到 `none` 或 `low` 观察改善幅度。
+- 适当提高 `--enhance-timeout-sec`（例如 240）验证是否为纯耗时问题。
+## 10. 从源码构建
+```powershell
+# release
+npm run release
+# 构建并拷贝 bin/ace-tool-win.exe
+npm run build:bin
+# 本地打包验证
+npm run pack:local
+```
+## 11. 发布到 npm
+```powershell
+npm publish --access public
+```
+> 若启用 npm 2FA，请使用支持 publish 的 token 或完成二次验证。
+## 12. 发布前检查清单
+- [ ] `npm run release` 无 error / warning
+- [ ] MCP 可启动并能成功 `tools/list`
+- [ ] `enhance_prompt` 在 `remote` 与 `codex` 均可回包
+- [ ] 中文增强回归通过（无 `???`）
+- [ ] README 中配置示例可在新机器复现
+## License
 Apache-2.0
-## 致谢
-- 原项目：ace-tool（https://github.com/eastxiaodong/ace-tool）

package/bin/ace-tool-win.exe CHANGED Viewed

Binary file

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "ace-tool-windows",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "ACE MCP server for Windows (Win32)",
   "bin": {
     "ace-tool-win": "bin/ace-tool-win.exe"
@@ -17,11 +17,12 @@
     "LICENSE"
   ],
   "license": "Apache-2.0",
-  "scripts": {
-    "release": "cargo build --release",
-    "build:bin": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/build-bin.ps1",
-    "pack:local": "npm run build:bin && npm pack"
-  },
+  "scripts": {
+    "release": "cargo build --release",
+    "check:release": "npm run release && cargo test --lib",
+    "build:bin": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/build-bin.ps1",
+    "pack:local": "npm run build:bin && npm pack"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/doudouHubs/ace-tool-windows.git"