ysagc-agent 0.1.0 → 0.2.0

package/README.md

@@ -6,39 +6,30 @@
 - 通信：JSON-RPC 2.0 over WebSocket（控制通道）+ 二进制帧（终端通道）
 - 路径沙箱：只能操作 allowlist（用户显式添加的项目根目录）内路径
 - 终端：node-pty（Windows: PowerShell / macOS·Linux: 默认 shell），输入输出**不经过网站后端**
+- **免配对码**（v0.2.0）：浏览器打开网站「工作台」自动识别并连接本机代理，无需输入配对码、无需安装 exe
 
-## 安装（两种渠道任选）
+## 安装（npm 方式，全球通用）
 
-### ① 安装包（普通用户）
-
-到网站「工作台 → 下载」页，按你的系统下载安装包：
-
-| 平台 | 形态 |
-|---|---|
-| Windows 10/11 | `ysagc-agent.exe`（单文件，免装 Node） |
-| macOS 12+ | 单文件二进制（未签名，首次需右键「打开」） |
-| Linux (Ubuntu 20.04+/Debian 11+) | 单文件二进制（AppImage 敬请期待） |
-
-Windows 若被杀软拦截：选择「仍要运行」，或在 Windows 安全中心放行。
-
-### ② npm（开发者用户）
+要求 Node.js ≥ 20（Windows / macOS / Linux 均可）。
 
 ```bash
-# 免安装，直接跑
+# 方式一：免安装，直接跑（推荐，首次会下载依赖包）
 npx ysagc-agent
 
-# 或全局安装
+# 方式二：全局安装后运行
 npm i -g ysagc-agent
 ysagc-agent
 ```
 
-要求 Node.js ≥ 20。
+启动后终端会显示 `ysagc-agent 运行中: ws://127.0.0.1:37890`，保持该终端窗口开启即可（最小化没问题，不要关闭）。
 
 ## 使用流程
 
-1. 启动后终端会显示 **6 位配对码**（10 分钟有效）。
-2. 打开网站 → 设置 → 设备管理 → 输入配对码 → 配对成功。
-3. 在网站添加项目（本机文件夹 / 克隆仓库 / 从零创建），即可开始使用工作台。
+1. 打开终端执行 `npx ysagc-agent`（保持运行）。
+2. 打开网站「工作台」，点击「新增工作区」→ 选择本机文件夹。
+3. 在聊天中把话题「绑定工作区」后，AI 就能在对应文件夹里读文件、改代码、跑命令了。
+
+> 旧版（0.1.x）安装包渠道与配对码流程已不再需要；如需卸载：`npm rm -g ysagc-agent`。
 
 ## 配置（agent.json）
 
@@ -47,8 +38,9 @@ ysagc-agent
 ```jsonc
 {
   "port": 37890,               // 端口被占用自动 +1（最多 5 次）
-  "allowedRoots": [],          // 授权项目根目录（网站添加项目时自动写入）
-  "deviceTokenWhitelist": [],  // 已配对设备令牌（sha256）
+  "allowedRoots": [],          // 授权项目根目录（网站添加工作区时自动写入）
+  "deviceTokenWhitelist": [],  // 旧版配对令牌（sha256，兼容保留）
+  "originWhitelist": [],       // 允许直连的浏览器 Origin；留空=自动信任站点与 localhost
   "trashEnabled": true,        // 删除进回收站
   "trashRetentionDays": 7,
   "enableTerminal": true,      // 终端开关
@@ -64,13 +56,15 @@ ysagc-agent
 
 **Q：端口被占用怎么办？** 自动尝试 37891–37894；也可 `ysagc-agent --port <端口>` 指定。
 
-**Q：macOS 提示"无法打开"？** 未签名应用：右键（或 Control+点击）→ 打开；或 系统设置 → 隐私与安全性 → 仍要打开。
+**Q：网页提示"未检测到本机代理"？** 确认 Agent 已在终端运行（能看到 `运行中: ws://127.0.0.1:37890`）；首次 `npx` 会先下载依赖，稍等片刻。
 
-**Q：连不上网站？** 确认 Agent 正在运行、配对码未过期；网站「设备管理」页有一键自检。
+**Q：macOS 提示"无法打开"？** npm 方式无需处理；仅安装包渠道需要右键 → 打开。
 
 **Q：日志在哪？** `~/.ysagc-agent/logs/agent.log`。日志**永不记录**密钥文件内容与 Git 凭证。
 
-**Q：Agent 会读取我电脑上的所有文件吗？** 不会。Agent 只能访问你在网站显式添加的项目目录（allowlist），越界操作一律拒绝并记录审计；终端除外（终端等同于你的命令行，可操作整台电脑——首次使用会在网页端弹安全确认）。
+**Q：Agent 会读取我电脑上的所有文件吗？** 不会。Agent 只能访问你在网站显式添加的工作区目录（allowlist），越界操作一律拒绝并记录审计；终端除外（终端等同于你的命令行，可操作整台电脑——首次使用会在网页端弹安全确认）。
+
+**Q：其他网站能控制我的 Agent 吗？** 不能。Agent 只信任站点域名与 localhost 来源（Origin 白名单），其他网页发起的连接会被拒绝。
 
 ## 开发
 
@@ -81,7 +75,7 @@ npm run smoke        # 冒烟测试（WS 鉴权 / RPC / 终端全链路）
 node scripts/smoke.js <token> <port>   # 自定义参数
 ```
 
-打包（单文件）：
+打包（单文件，可选）：
 
 ```bash
 npx @yao-pkg/pkg . --target node22-win-x64 --output dist/ysagc-agent.exe
@@ -93,4 +87,4 @@ CI：`.gitlab-ci.yml`（build 产物 + tag 触发发布到 Package Registry / np
 
 ## 隐私
 
-Agent 与网站后端的交互仅限：配对码上报、版本握手、审计元数据。**项目文件内容、终端输入输出、Git 凭证一律不经过网站后端**。
+Agent 与网站后端的交互仅限：设备自动注册、版本握手、审计元数据。**项目文件内容、终端输入输出、Git 凭证一律不经过网站后端**。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ysagc-agent",
-  "version": "0.1.0",
-  "description": "代码工作台本机代理：替浏览器在本机执行文件/Git/终端操作（JSON-RPC over WebSocket，直连 127.0.0.1）",
+  "version": "0.2.0",
+  "description": "代码工作台本机代理：替浏览器在本机执行文件/Git/终端操作（JSON-RPC over WebSocket，直连 127.0.0.1，免配对码）",
   "main": "src/index.js",
   "bin": {
     "ysagc-agent": "src/index.js"

package/src/config.js

@@ -27,8 +27,13 @@ const DEFAULTS = {
   // 终端权限：ask（每次询问）/ allow（始终允许）/ deny（拒绝）
   terminalPermission: 'ask',
   // 协议版本（与后端握手比对）
-  protocolVersion: 1,
+  protocolVersion: 2,
   agentVersion: null,
+  // ---- 免配对码直连（v0.2.0 起）----
+  // 允许的浏览器 Origin 列表（精确匹配 origin，如 https://chat.ysagc.top）。
+  // 为空时自动信任：backendUrl 对应的 origin + http://localhost / http://127.0.0.1 及其任意端口。
+  // 该列表之外的 Origin 发起的 WebSocket / 本地 HTTP 请求将被拒绝（防恶意网页操控本机代理）。
+  originWhitelist: [],
 };
 
 function ensureDir() {

package/src/http-fs.js

@@ -13,6 +13,8 @@ const path = require('path');
 const crypto = require('crypto');
 const url = require('url');
 
+const { isOriginTrusted } = require('./origin');
+
 const MAX_UPLOAD_SIZE = 512 * 1024 * 1024; // 512MB
 const MAX_ZIP_FILES = 2000;
 
@@ -24,7 +26,12 @@ function createHttpFsHandlers(ctxRef) {
   const sandbox = () => ctxRef().sandbox;
   const cfg = () => ctxRef().config;
 
-  function checkToken(token) {
+  function checkToken(token, req) {
+    // 免配对码直连（v0.2.0）：Origin 受信任的浏览器请求直接放行
+    if (req) {
+      const origin = req.headers && req.headers.origin;
+      if (origin && isOriginTrusted(origin, cfg())) return true;
+    }
     if (!token) return false;
     return (cfg().deviceTokenWhitelist || []).includes(sha256(token));
   }
@@ -37,7 +44,7 @@ function createHttpFsHandlers(ctxRef) {
   /** 上传：分片追加到临时文件，最后一片 rename 落盘 */
   function handleUpload(req, res, query) {
     const token = query.token;
-    if (!checkToken(token)) return sendJson(res, 401, { code: 'E_AUTH_FAILED', msg: '未授权' });
+    if (!checkToken(token, req)) return sendJson(res, 401, { code: 'E_AUTH_FAILED', msg: '未授权' });
     const relPath = String(query.path || '');
     if (!relPath) return sendJson(res, 400, { code: 'E_VALIDATION', msg: '缺少 path' });
     let r;
@@ -89,7 +96,7 @@ function createHttpFsHandlers(ctxRef) {
   /** 单文件下载（流式） */
   function handleDownload(req, res, query) {
     const token = query.token;
-    if (!checkToken(token)) return sendJson(res, 401, { code: 'E_AUTH_FAILED', msg: '未授权' });
+    if (!checkToken(token, req)) return sendJson(res, 401, { code: 'E_AUTH_FAILED', msg: '未授权' });
     const relPath = String(query.path || '');
     let r;
     try {
@@ -111,7 +118,7 @@ function createHttpFsHandlers(ctxRef) {
   /** zip 打包下载（yazl 流式） */
   function handleZip(req, res, query) {
     const token = query.token;
-    if (!checkToken(token)) return sendJson(res, 401, { code: 'E_AUTH_FAILED', msg: '未授权' });
+    if (!checkToken(token, req)) return sendJson(res, 401, { code: 'E_AUTH_FAILED', msg: '未授权' });
     const paths = String(query.paths || '')
       .split(',')
       .map((p) => p.trim())

package/src/index.js

@@ -20,6 +20,7 @@ const fs = require('fs');
 const { loadConfig, saveConfig, CONFIG_DIR } = require('./config');
 const logger = require('./logger');
 const { register, handleRequest } = require('./rpc');
+const { isOriginTrusted } = require('./origin');
 const { registerSystemMethods } = require('./methods/system');
 const { createTerminalMethods } = require('./methods/terminal');
 const { createProjectMethods } = require('./methods/project');
@@ -27,9 +28,10 @@ const { createFsMethods } = require('./methods/fs');
 const { createSkillMethods } = require('./methods/skill');
 const { createGitMethods } = require('./methods/git');
 const { createScaffoldMethods } = require('./methods/scaffold');
+const { createDialogMethods } = require('./methods/dialog');
 const { createHttpFsHandlers } = require('./http-fs');
 const { Sandbox } = require('./sandbox');
-const { startPairing, stopPairing } = require('./pairing');
+const { startPairing, stopPairing, agentId } = require('./pairing');
 
 const DEFAULT_PORT = 37890;
 const MAX_PORT_TRIES = 5;
@@ -47,6 +49,26 @@ function getArg(name) {
   return i >= 0 ? argv[i + 1] : null;
 }
 
+const AGENT_VERSION = require('../package.json').version;
+if (argv.includes('--help') || argv.includes('-h')) {
+  console.log(`ysagc-agent v${AGENT_VERSION} — 代码工作台本机代理
+用法: npx ysagc-agent [选项]
+
+选项:
+  --port N          指定监听端口（默认 37890，被占用自动 +1）
+  --init-token <t>  把指定 token 加入白名单（兼容旧版配对，一般无需使用）
+  --help, -h        显示帮助
+  --version, -v     显示版本
+
+启动后无需配对码：浏览器打开网站「工作台」即可自动识别本机代理并连接。
+代理仅监听 127.0.0.1，替浏览器在本机执行文件 / Git / 终端操作。`);
+  process.exit(0);
+}
+if (argv.includes('--version') || argv.includes('-v')) {
+  console.log(AGENT_VERSION);
+  process.exit(0);
+}
+
 // ---------------- 配置 ----------------
 let config = loadConfig();
 logger.setLevel(config.logLevel);
@@ -80,6 +102,8 @@ const gitMethods = createGitMethods(() => configRef);
 gitMethods.register(register);
 const scaffoldMethods = createScaffoldMethods(() => configRef);
 scaffoldMethods.register(register);
+const dialogMethods = createDialogMethods();
+dialogMethods.register(register);
 
 // ---------------- WS 服务 ----------------
 const state = {
@@ -136,6 +160,8 @@ function setupConnection(ws, req) {
   ws.isAlive = true;
   ws.authed = false;
   ws.deviceId = null;
+  // 免配对码直连：Origin 可信的浏览器连接无需 deviceToken（v0.2.0）
+  ws.originTrusted = isOriginTrusted(req.headers.origin, configRef.config);
   ws.authTimer = setTimeout(() => {
     if (!ws.authed) closeWith(ws, 4401, 'auth timeout');
   }, AUTH_TIMEOUT_MS);
@@ -167,9 +193,10 @@ function setupConnection(ws, req) {
     // ---- 鉴权握手 ----
     if (msg && msg.type === 'auth') {
       if (ws.authed) return;
-      const ok = checkAuthToken(msg.token);
-      if (!ok) {
-        logger.warn(`[ws] 鉴权失败：token 不在白名单（remote=${req.socket.remoteAddress}）`);
+      const tokenOk = checkAuthToken(msg.token);
+      const autoOk = ws.originTrusted && (msg.mode === 'auto' || !msg.token);
+      if (!tokenOk && !autoOk) {
+        logger.warn(`[ws] 鉴权失败：token 不在白名单且 Origin 不受信任（origin=${req.headers.origin || 'none'} remote=${req.socket.remoteAddress}）`);
         closeWith(ws, 4401, 'unauthorized');
         return;
       }
@@ -275,20 +302,52 @@ function setupConnection(ws, req) {
 function tryListen(port, triesLeft) {
   const httpFs = createHttpFsHandlers(() => configRef);
   const server = http.createServer((req, res) => {
-    // 本地 HTTP：上传/下载/zip（T-M1-05）
     const parsed = url.parse(req.url, true);
     const p = parsed.pathname || '';
+    const origin = req.headers.origin || '';
+
+    // CORS 预检（浏览器跨源 fetch 到 http://127.0.0.1 需要）
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, {
+        'Access-Control-Allow-Origin': origin || '*',
+        'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+        'Access-Control-Allow-Headers': 'Content-Type, X-Offset, X-Total, Authorization',
+        'Access-Control-Max-Age': '86400',
+      });
+      res.end();
+      return;
+    }
+    const corsHeaders = (h) => {
+      h['Access-Control-Allow-Origin'] = origin || '*';
+      return h;
+    };
     try {
+      // 免配对码直连：浏览器探测本机 Agent 信息（v0.2.0）
+      if (req.method === 'GET' && p === '/api/bootstrap') {
+        res.writeHead(200, corsHeaders({ 'Content-Type': 'application/json' }));
+        res.end(JSON.stringify({
+          agentId: agentId(),
+          agentVersion: require('../package.json').version,
+          protocolVersion: configRef.config.protocolVersion || 2,
+          port: configRef.config.port,
+          platform: `${process.platform} ${process.arch}`,
+          nodeVersion: process.version,
+          hostname: require('os').hostname(),
+          paired: (configRef.config.deviceTokenWhitelist || []).length > 0,
+          allowAuto: true,
+        }));
+        return;
+      }
       if (req.method === 'POST' && p === '/api/fs/upload') return httpFs.handleUpload(req, res, parsed.query);
       if (req.method === 'GET' && p === '/api/fs/download') return httpFs.handleDownload(req, res, parsed.query);
       if (req.method === 'GET' && p === '/api/fs/zip') return httpFs.handleZip(req, res, parsed.query);
     } catch (e) {
       logger.error(`[http] 处理 ${p} 失败: ${e && e.message}`);
-      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.writeHead(500, corsHeaders({ 'Content-Type': 'application/json' }));
       res.end(JSON.stringify({ code: 'E_INTERNAL', msg: e && e.message }));
       return;
     }
-    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.writeHead(404, corsHeaders({ 'Content-Type': 'application/json' }));
     res.end(JSON.stringify({ error: 'not found' }));
   });
 
@@ -343,7 +402,9 @@ function tryListen(port, triesLeft) {
   return server;
 }
 
-console.log(`ysagc-agent v${require('../package.json').version} 启动中（配置目录: ${CONFIG_DIR}）`);
+console.log(`ysagc-agent v${AGENT_VERSION} 启动中（配置目录: ${CONFIG_DIR}，端口: ${config.port}）`);
+console.log(`免配对码直连已启用：打开网站「工作台」即可自动识别本机代理（agentId: ${agentId().slice(0, 8)}...）`);
+console.log('提示: 输入 --help 查看完整选项。');
 tryListen(config.port, MAX_PORT_TRIES);
 
 process.on('SIGINT', () => {

package/src/methods/dialog.js

@@ -0,0 +1,84 @@
+/**
+ * dialog.* RPC 方法：本机原生对话框（T-M3-xx）
+ * - dialog.pickFolder {} → { path }  打开系统文件夹选择器，返回绝对路径（取消返回 E_DIALOG_CANCELED）
+ * 实现：
+ *   Windows: PowerShell FolderBrowserDialog（Agent 运行在用户本机，可弹原生窗口）
+ *   macOS:   osascript choose folder
+ *   Linux:   zenity / kdialog（依次尝试）
+ * 用途：添加项目时"点击选择文件夹"替代手输绝对路径（需求 4.3.1 方式 A）
+ */
+'use strict';
+
+const { execFile } = require('child_process');
+const { RpcError } = require('../rpc');
+
+const DIALOG_TIMEOUT_MS = 5 * 60 * 1000; // 用户可能挑很久，5 分钟上限
+
+function run(cmd, args, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    execFile(
+      cmd,
+      args,
+      { timeout: timeoutMs || DIALOG_TIMEOUT_MS, windowsHide: true, maxBuffer: 4 * 1024 * 1024 },
+      (err, stdout) => {
+        if (err) return reject(err);
+        resolve(String(stdout || ''));
+      }
+    );
+  });
+}
+
+/** Windows：PowerShell FolderBrowserDialog */
+async function pickFolderWindows() {
+  const ps = [
+    'Add-Type -AssemblyName System.Windows.Forms',
+    "$f = New-Object System.Windows.Forms.FolderBrowserDialog",
+    "$f.Description = '选择要添加到工作台的项目文件夹'",
+    '$f.ShowNewFolderButton = $true',
+    "if ($f.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) { Write-Output $f.SelectedPath }",
+  ].join('; ');
+  const out = await run('powershell.exe', ['-NoProfile', '-NonInteractive', '-STA', '-Command', ps]);
+  const p = String(out || '').trim().split(/\r?\n/).filter(Boolean).pop() || '';
+  return p;
+}
+
+/** macOS：osascript choose folder */
+async function pickFolderMac() {
+  const out = await run('osascript', ['-e', 'POSIX path of (choose folder with prompt "选择要添加到工作台的项目文件夹")']);
+  return String(out || '').trim();
+}
+
+/** Linux：zenity → kdialog 依次尝试 */
+async function pickFolderLinux() {
+  for (const [cmd, args] of [
+    ['zenity', ['--file-selection', '--directory', '--title=选择要添加到工作台的项目文件夹']],
+    ['kdialog', ['--getexistingdirectory', '选择要添加到工作台的项目文件夹']],
+  ]) {
+    try {
+      const out = await run(cmd, args, 30000);
+      const p = String(out || '').trim();
+      if (p) return p;
+    } catch {
+      /* 尝试下一种 */
+    }
+  }
+  throw new RpcError('E_DIALOG_UNSUPPORTED', '当前系统未安装文件夹选择工具（zenity/kdialog），请手动输入路径');
+}
+
+function createDialogMethods() {
+  return {
+    register(reg) {
+      reg('dialog.pickFolder', async () => {
+        let p = '';
+        if (process.platform === 'win32') p = await pickFolderWindows();
+        else if (process.platform === 'darwin') p = await pickFolderMac();
+        else p = await pickFolderLinux();
+        p = String(p || '').trim();
+        if (!p) throw new RpcError('E_DIALOG_CANCELED', '已取消选择文件夹');
+        return { path: p.replace(/\\/g, '/') };
+      });
+    },
+  };
+}
+
+module.exports = { createDialogMethods };

package/src/origin.js

@@ -0,0 +1,38 @@
+/**
+ * Origin 信任判断（免配对码直连，v0.2.0）
+ * 浏览器 WebSocket / fetch 会带 Origin 头；恶意网页发起的请求 Origin 不在白名单时被拒绝。
+ * originWhitelist 为空时自动信任：backendUrl 的 origin + localhost/127.0.0.1 任意端口。
+ */
+'use strict';
+
+/**
+ * @param {string|null|undefined} origin 请求的 Origin 头
+ * @param {{backendUrl?: string, originWhitelist?: string[]}} config 当前配置
+ * @returns {boolean}
+ */
+function isOriginTrusted(origin, config) {
+  if (!origin || typeof origin !== 'string') return false;
+  let o;
+  try {
+    o = new URL(origin).origin;
+  } catch {
+    return false;
+  }
+  const whitelist = (config && config.originWhitelist) || [];
+  if (Array.isArray(whitelist) && whitelist.length > 0) {
+    return whitelist.some((w) => String(w).replace(/\/$/, '') === o);
+  }
+  // 默认策略：站点 origin + 本机开发源
+  const backend = String((config && config.backendUrl) || '').replace(/\/$/, '');
+  if (backend) {
+    try {
+      if (new URL(backend).origin === o) return true;
+    } catch {
+      /* ignore */
+    }
+  }
+  if (o.startsWith('http://localhost') || o.startsWith('http://127.0.0.1')) return true;
+  return false;
+}
+
+module.exports = { isOriginTrusted };

package/src/pairing.js

@@ -93,7 +93,18 @@ function postJson(url, body) {
 
 function rotateCode() {
   current = { code: generateCode(), agentId: agentId(), createdAt: Date.now() };
-  console.log(`\n🔑 配对码: ${current.code}（10 分钟内有效，请在网站“设备管理”输入）\n`);
+  const W = 46;
+  const bar = '═'.repeat(W);
+  const pad = (s) => `  ${String(s).padEnd(W - 2)}`;
+  console.log('');
+  console.log('  ' + bar);
+  console.log(pad('代码工作台 · 配对码'));
+  console.log('  ' + '─'.repeat(W));
+  console.log(pad(`🔑 配对码: ${current.code}`));
+  console.log(pad('有效期: 10 分钟 · 单次使用'));
+  console.log(pad('请在网站「设备管理」或「首次配置」中输入'));
+  console.log('  ' + bar);
+  console.log('');
   logger.info(`[pairing] 生成新配对码 ${current.code}`);
   report();
   return current;