ysagc-agent 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# ysagc-agent
+
+代码工作台本机代理：替浏览器在本机执行**文件 / Git / 终端**操作。只处理工作台发来的指令，不偷传数据、不常驻收集信息。
+
+- 仅监听 `127.0.0.1`（浏览器可信源），HTTPS 页面不拦截
+- 通信：JSON-RPC 2.0 over WebSocket（控制通道）+ 二进制帧（终端通道）
+- 路径沙箱：只能操作 allowlist（用户显式添加的项目根目录）内路径
+- 终端：node-pty（Windows: PowerShell / macOS·Linux: 默认 shell），输入输出**不经过网站后端**
+
+## 安装（两种渠道任选）
+
+### ① 安装包（普通用户）
+
+到网站「工作台 → 下载」页，按你的系统下载安装包：
+
+| 平台 | 形态 |
+|---|---|
+| Windows 10/11 | `ysagc-agent.exe`（单文件，免装 Node） |
+| macOS 12+ | 单文件二进制（未签名，首次需右键「打开」） |
+| Linux (Ubuntu 20.04+/Debian 11+) | 单文件二进制（AppImage 敬请期待） |
+
+Windows 若被杀软拦截：选择「仍要运行」，或在 Windows 安全中心放行。
+
+### ② npm（开发者用户）
+
+```bash
+# 免安装，直接跑
+npx ysagc-agent
+
+# 或全局安装
+npm i -g ysagc-agent
+ysagc-agent
+```
+
+要求 Node.js ≥ 20。
+
+## 使用流程
+
+1. 启动后终端会显示 **6 位配对码**（10 分钟有效）。
+2. 打开网站 → 设置 → 设备管理 → 输入配对码 → 配对成功。
+3. 在网站添加项目（本机文件夹 / 克隆仓库 / 从零创建），即可开始使用工作台。
+
+## 配置（agent.json）
+
+位置：`~/.ysagc-agent/agent.json`（Windows 为 `C:\Users\<你>\.ysagc-agent`）。非法 JSON 会自动备份恢复。
+
+```jsonc
+{
+  "port": 37890,               // 端口被占用自动 +1（最多 5 次）
+  "allowedRoots": [],          // 授权项目根目录（网站添加项目时自动写入）
+  "deviceTokenWhitelist": [],  // 已配对设备令牌（sha256）
+  "trashEnabled": true,        // 删除进回收站
+  "trashRetentionDays": 7,
+  "enableTerminal": true,      // 终端开关
+  "terminalMaxSessions": 3,
+  "terminalIdleTimeoutMin": 30,
+  "terminalPermission": "ask", // ask=每次询问 / allow=始终允许 / deny=拒绝
+  "backendUrl": "https://chat.ysagc.top",
+  "logLevel": "info"
+}
+```
+
+## 常见问题
+
+**Q：端口被占用怎么办？** 自动尝试 37891–37894；也可 `ysagc-agent --port <端口>` 指定。
+
+**Q：macOS 提示"无法打开"？** 未签名应用：右键（或 Control+点击）→ 打开；或 系统设置 → 隐私与安全性 → 仍要打开。
+
+**Q：连不上网站？** 确认 Agent 正在运行、配对码未过期；网站「设备管理」页有一键自检。
+
+**Q：日志在哪？** `~/.ysagc-agent/logs/agent.log`。日志**永不记录**密钥文件内容与 Git 凭证。
+
+**Q：Agent 会读取我电脑上的所有文件吗？** 不会。Agent 只能访问你在网站显式添加的项目目录（allowlist），越界操作一律拒绝并记录审计；终端除外（终端等同于你的命令行，可操作整台电脑——首次使用会在网页端弹安全确认）。
+
+## 开发
+
+```bash
+npm ci
+npm start            # 启动
+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
+# 三平台（Linux 环境可交叉产出）：
+npx @yao-pkg/pkg . --target node22-win-x64,node22-macos-x64,node22-linux-x64 --output dist/ysagc-agent
+```
+
+CI：`.gitlab-ci.yml`（build 产物 + tag 触发发布到 Package Registry / npm）。
+
+## 隐私
+
+Agent 与网站后端的交互仅限：配对码上报、版本握手、审计元数据。**项目文件内容、终端输入输出、Git 凭证一律不经过网站后端**。

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "ysagc-agent",
+  "version": "0.1.0",
+  "description": "代码工作台本机代理：替浏览器在本机执行文件/Git/终端操作（JSON-RPC over WebSocket，直连 127.0.0.1）",
+  "main": "src/index.js",
+  "bin": {
+    "ysagc-agent": "src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "smoke": "node scripts/smoke.js"
+  },
+  "keywords": [
+    "workspace",
+    "agent",
+    "local-files",
+    "terminal"
+  ],
+  "license": "UNLICENSED",
+  "private": false,
+  "dependencies": {
+    "chokidar": "^4.0.3",
+    "iconv-lite": "^0.6.3",
+    "jschardet": "^3.1.4",
+    "node-pty": "^1.1.0",
+    "ws": "^8.18.0",
+    "yauzl": "^3.2.0",
+    "yazl": "^2.5.1"
+  }
+}

package/src/config.js

@@ -0,0 +1,89 @@
+/**
+ * ysagc-agent 配置加载（agent.json）
+ * 位置：~/.ysagc-agent/agent.json
+ * 非法 JSON 自动备份恢复（agent.json.bak-<时间戳>）
+ */
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const CONFIG_DIR = process.env.YSAGC_AGENT_HOME || path.join(os.homedir(), '.ysagc-agent');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'agent.json');
+
+const DEFAULTS = {
+  port: 37890,
+  allowedRoots: [],
+  deviceTokenWhitelist: [],
+  trashEnabled: true,
+  trashRetentionDays: 7,
+  autoApprovePaths: true,
+  enableTerminal: true,
+  terminalMaxSessions: 3,
+  terminalIdleTimeoutMin: 30,
+  backendUrl: 'https://chat.ysagc.top',
+  logLevel: 'info',
+  // 终端权限：ask（每次询问）/ allow（始终允许）/ deny（拒绝）
+  terminalPermission: 'ask',
+  // 协议版本（与后端握手比对）
+  protocolVersion: 1,
+  agentVersion: null,
+};
+
+function ensureDir() {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+}
+
+function backupCorruptConfig() {
+  if (!fs.existsSync(CONFIG_PATH)) return;
+  const bak = path.join(CONFIG_DIR, `agent.json.bak-${Date.now()}`);
+  try {
+    fs.copyFileSync(CONFIG_PATH, bak);
+    console.error(`[config] agent.json 解析失败，已备份到 ${bak}，恢复默认配置`);
+  } catch {
+    /* 备份失败不阻塞 */
+  }
+}
+
+function loadConfig() {
+  ensureDir();
+  let config = {};
+  if (fs.existsSync(CONFIG_PATH)) {
+    try {
+      const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === 'object') config = parsed;
+      else backupCorruptConfig();
+    } catch {
+      backupCorruptConfig();
+    }
+  }
+  const merged = { ...DEFAULTS, ...config };
+  // 写入规范化后的配置（含缺失字段默认值），后续更新配置也走 saveConfig
+  saveConfig(merged, { silent: true });
+  return merged;
+}
+
+function saveConfig(patch, opts = {}) {
+  ensureDir();
+  const current = loadConfigRaw();
+  const next = { ...DEFAULTS, ...current, ...patch };
+  const tmp = CONFIG_PATH + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(next, null, 2));
+  fs.renameSync(tmp, CONFIG_PATH); // 原子替换，防损坏
+  if (!opts.silent) console.log(`[config] 配置已保存: ${CONFIG_PATH}`);
+  return next;
+}
+
+function loadConfigRaw() {
+  try {
+    if (!fs.existsSync(CONFIG_PATH)) return {};
+    const parsed = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+module.exports = { CONFIG_DIR, CONFIG_PATH, DEFAULTS, loadConfig, saveConfig };

package/src/http-fs.js

@@ -0,0 +1,171 @@
+/**
+ * Agent 本地 HTTP：上传/下载（T-M1-05）
+ * - POST /api/fs/upload?token=&path=&overwrite=1   分片上传（X-Offset / X-Total 头）
+ * - GET  /api/fs/download?token=&path=            单文件下载（流式）
+ * - GET  /api/fs/zip?token=&paths=a,b,c           zip 打包下载（yazl 流式）
+ * - 鉴权：deviceToken sha256 与白名单比对；路径经沙箱校验（allowlist）
+ * - 分片：临时文件 append，达到 X-Total 后原子 rename；覆盖需 overwrite=1（前端先 409 确认）
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const url = require('url');
+
+const MAX_UPLOAD_SIZE = 512 * 1024 * 1024; // 512MB
+const MAX_ZIP_FILES = 2000;
+
+function sha256(s) {
+  return crypto.createHash('sha256').update(String(s)).digest('hex');
+}
+
+function createHttpFsHandlers(ctxRef) {
+  const sandbox = () => ctxRef().sandbox;
+  const cfg = () => ctxRef().config;
+
+  function checkToken(token) {
+    if (!token) return false;
+    return (cfg().deviceTokenWhitelist || []).includes(sha256(token));
+  }
+
+  function sendJson(res, status, obj) {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(obj));
+  }
+
+  /** 上传：分片追加到临时文件，最后一片 rename 落盘 */
+  function handleUpload(req, res, query) {
+    const token = query.token;
+    if (!checkToken(token)) 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;
+    try {
+      r = sandbox().resolve(relPath, '');
+    } catch (e) {
+      return sendJson(res, 403, { code: 'E_PATH_ESCAPE', msg: e.message || '路径越界' });
+    }
+    if (r.rel === '' || r.rel === '.') return sendJson(res, 400, { code: 'E_VALIDATION', msg: '不能上传到项目根' });
+
+    const offset = Math.max(0, Number(req.headers['x-offset']) || 0);
+    const total = Math.max(0, Number(req.headers['x-total']) || 0);
+    if (total > MAX_UPLOAD_SIZE) return sendJson(res, 413, { code: 'E_FILE_TOO_LARGE', msg: '文件超过 512MB 限制' });
+    const overwrite = String(query.overwrite || '') === '1';
+
+    // 目标已存在 → 409 需确认
+    if (offset === 0 && !overwrite && fs.existsSync(r.abs)) {
+      return sendJson(res, 409, { code: 'E_PATH_EXISTS', msg: '目标文件已存在，请确认覆盖', needConfirm: true });
+    }
+
+    const tmpPath = path.join(r.root, `.upload-tmp-${sha256(relPath).slice(0, 16)}`);
+    try {
+      // 首片：若需覆盖且临时文件残留则清理
+      if (offset === 0 && fs.existsSync(tmpPath)) fs.rmSync(tmpPath);
+      const fd = fs.openSync(tmpPath, offset === 0 ? 'w' : 'a');
+      const chunks = [];
+      req.on('data', (c) => chunks.push(c));
+      req.on('end', () => {
+        const buf = Buffer.concat(chunks);
+        fs.writeSync(fd, buf, 0, buf.length, offset);
+        fs.closeSync(fd);
+        const curSize = offset + buf.length;
+        if (total > 0 && curSize >= total) {
+          // 完成：原子 rename
+          fs.renameSync(tmpPath, r.abs);
+          return sendJson(res, 200, { code: 0, data: { ok: true, size: curSize, relPath: r.rel }, msg: 'success' });
+        }
+        return sendJson(res, 200, { code: 0, data: { ok: true, received: curSize, total }, msg: 'chunk' });
+      });
+      req.on('error', () => {
+        try { fs.closeSync(fd); } catch { /* ignore */ }
+        sendJson(res, 500, { code: 'E_INTERNAL', msg: '上传中断' });
+      });
+    } catch (e) {
+      return sendJson(res, 500, { code: 'E_INTERNAL', msg: e.message });
+    }
+  }
+
+  /** 单文件下载（流式） */
+  function handleDownload(req, res, query) {
+    const token = query.token;
+    if (!checkToken(token)) return sendJson(res, 401, { code: 'E_AUTH_FAILED', msg: '未授权' });
+    const relPath = String(query.path || '');
+    let r;
+    try {
+      r = sandbox().resolve(relPath, '');
+    } catch (e) {
+      return sendJson(res, 403, { code: 'E_PATH_ESCAPE', msg: e.message || '路径越界' });
+    }
+    if (!fs.existsSync(r.abs) || !fs.statSync(r.abs).isFile()) {
+      return sendJson(res, 404, { code: 'E_PATH_NOT_FOUND', msg: '文件不存在' });
+    }
+    res.writeHead(200, {
+      'Content-Type': 'application/octet-stream',
+      'Content-Disposition': `attachment; filename="${encodeURIComponent(path.basename(r.abs))}"`,
+      'Content-Length': fs.statSync(r.abs).size,
+    });
+    fs.createReadStream(r.abs).pipe(res);
+  }
+
+  /** zip 打包下载（yazl 流式） */
+  function handleZip(req, res, query) {
+    const token = query.token;
+    if (!checkToken(token)) return sendJson(res, 401, { code: 'E_AUTH_FAILED', msg: '未授权' });
+    const paths = String(query.paths || '')
+      .split(',')
+      .map((p) => p.trim())
+      .filter(Boolean);
+    if (paths.length === 0 || paths.length > MAX_ZIP_FILES) {
+      return sendJson(res, 400, { code: 'E_VALIDATION', msg: 'paths 数量需在 1-2000 之间' });
+    }
+    const yazl = require('yazl');
+    const zipfile = new yazl.ZipFile();
+    let added = 0;
+    for (const rel of paths) {
+      let r;
+      try {
+        r = sandbox().resolve(rel, '');
+      } catch {
+        return sendJson(res, 403, { code: 'E_PATH_ESCAPE', msg: '路径越界: ' + rel });
+      }
+      if (!fs.existsSync(r.abs)) continue;
+      const st = fs.statSync(r.abs);
+      if (st.isDirectory()) {
+        // 递归目录
+        const walk = (dir, relBase) => {
+          let entries;
+          try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+          } catch {
+            return;
+          }
+          for (const e of entries) {
+            const abs = path.join(dir, e.name);
+            const relP = relBase ? `${relBase}/${e.name}` : e.name;
+            if (e.isDirectory()) walk(abs, relP);
+            else if (e.isFile()) {
+              zipfile.addFile(abs, relP);
+              added++;
+            }
+          }
+        };
+        walk(r.abs, path.basename(r.abs));
+      } else if (st.isFile()) {
+        zipfile.addFile(r.abs, path.basename(r.abs));
+        added++;
+      }
+    }
+    if (added === 0) return sendJson(res, 404, { code: 'E_PATH_NOT_FOUND', msg: '没有可打包的文件' });
+    res.writeHead(200, {
+      'Content-Type': 'application/zip',
+      'Content-Disposition': `attachment; filename="workspace-${Date.now()}.zip"`,
+    });
+    zipfile.outputStream.pipe(res);
+    zipfile.end();
+  }
+
+  return { handleUpload, handleDownload, handleZip };
+}
+
+module.exports = { createHttpFsHandlers };