Windows Remote Executor v3.5 核心接口

服务地址: http://<host>:8765

核心端点

配置管理

GET  /config              # 获取配置（log_dir, log_retention_days, upload_dir）
POST /config              # 更新配置 {log_dir, log_retention_days}
POST /config/cleanup-now  # 手动清理旧日志

任务执行（异步）

POST /run
Content-Type: application/json

{"script_path": "D:\\script.py", "args": [], "cwd": "...", "python_path": "D:\\venv\\Scripts\\python.exe"}

返回: {"task_id": "xxx", "status": "started", "log_file": "..."}

python_path 可选，不传默认用系统 PATH 的 python。

同步执行（短任务）

POST /run-sync
Content-Type: application/json

{"script_path": "D:\\script.py", "args": [], "cwd": "...", "timeout": 30, "python_path": null}

返回: {"stdout": "...", "stderr": "...", "returncode": 0}

任务管理

GET    /status/{task_id}      # 任务状态
GET    /log/{task_id}?max_lines=200  # 任务日志
POST   /stop/{task_id}        # 停止任务
GET    /tasks                 # 列出所有任务
POST   /tasks/clear-finished  # 清理已完成任务

PowerShell（异步）

POST /powershell
Content-Type: application/json

{"command": "Get-Process | Select-Object -First 5", "timeout": 60}

返回: {"task_id": "xxx", "status": "started", "log_file": "..."}

PowerShell（同步）

POST /powershell-sync
Content-Type: application/json

{"command": "...", "timeout": 60}

返回: {"stdout": "...", "stderr": "...", "returncode": 0}

文件上传/下载

POST /upload                # multipart: file + target_path
POST /batch/upload          # multipart: files[] + target_dir
POST /download              # {path} JSON body，支持大文件和中文路径
POST /list                  # {path, pattern}

审计日志

GET /audit?limit=100

服务管理

控制 executor 自身的 Windows 服务。

POST /service/restart       # 重启服务（延迟2秒执行）
POST /service/stop          # 停止服务（延迟2秒执行）
GET  /service/autostart     # 获取开机自启状态
POST /service/autostart?enable=true   # 开启开机自启
POST /service/autostart?enable=false  # 关闭开机自启
GET  /service/info          # 服务信息（版本、PID、任务数）
GET  /health                # 健康检查

重启服务:

curl -s -X POST http://<host>:8765/service/restart

返回: {"message": "Service SkyWindowsRemoteExecutor restart scheduled"}

注意：重启是异步的，HTTP 响应返回后 2 秒才执行，期间服务暂时不可用。

停止服务:

curl -s -X POST http://<host>:8765/service/stop

返回: {"message": "Service SkyWindowsRemoteExecutor stop scheduled"}

停止后需通过 net start <服务名> 或本机启动服务才能恢复。

开机自启:

# 查看
curl -s http://<host>:8765/service/autostart
# → {"enabled": true, "start_type": "Automatic", "service_name": "SkyWindowsRemoteExecutor"}

# 开启
curl -s -X POST "http://<host>:8765/service/autostart?enable=true"

# 关闭
curl -s -X POST "http://<host>:8765/service/autostart?enable=false"

服务信息:

curl -s http://<host>:8765/service/info
# → {"version": "3.5", "pid": 1234, "total_tasks": 5, "running_tasks": 2, ...}

curl -s http://<host>:8765/health
# → {"status": "ok", "service": "Sky Windows Remote Executor v3.5", "tasks": 5}

动态加载其他功能层

当用户提到以下关键词时，加载对应 skill：

加载方式: skill_view(name="remote-executor-file")

References

• references/windows-python-encoding.md — Windows Python UTF-8 编码问题修复指南
• references/layered-skill-architecture.md — 分层 Skill 按需加载架构设计
• references/v33-endpoints.md — v3.5 完整端点列表
• references/test-all-endpoints.sh — 全端点测试脚本
• references/test-all-endpoints.sh — 全端点测试脚本

Token 开销

Pitfalls

1. PowerShell 命令中的引号转义: JSON 中传递 PowerShell 命令时，Windows 路径的反斜杠需要双写（D:\\\\file.txt），引号需要正确转义。
2. 异步任务日志延迟: /run 和 /powershell 是异步的，创建后需要等待几秒再查 /log，否则可能返回空。
3. 文件读取大小限制: /file/read 文本限制 100KB，二进制限制 1MB，超大文件会被截断（truncated: true）。
4. 服务状态为数字: /service/list 返回的 status 是数字枚举（1=Stopped, 4=Running），不是字符串。
5. 事件日志时间格式: PowerShell ConvertTo-Json 默认输出 /Date(timestamp)/ 格式，不是 ISO 8601。
6. 批量上传空文件: /batch/upload 用 -F "files=@/dev/null" 测试时会上传空文件，生产环境使用真实文件。
7. 审计日志中文显示: v3.5 代码中部分审计字符串有编码问题（显示为乱码如 鎵цPS鍛戒护），但不影响功能。