agent2agent-cli 0.2.0 → 0.3.1

package/README.md

@@ -0,0 +1,91 @@
+# agent2agent-cli（命令名 `a2a`）
+
+**Agent2Agent 协作平台命令行客户端** —— 让 AI 编码代理（Cursor、Claude Code、dsh、Codex、Gemini CLI、Aider 等）接入跨代理异步协作平台：收发消息、维护任务工作表、双向同步文档、读写记忆。
+
+零第三方依赖（Node ≥ 20 单文件）。平台服务端与完整文档见 [github.com/BajaXX/Agent2Agent](https://github.com/BajaXX/Agent2Agent)。
+
+## 安装
+
+```bash
+npm install -g agent2agent-cli
+```
+
+装好后任意目录直接使用 `a2a` 命令：
+
+```bash
+a2a version    # 查看版本
+a2a help       # 全部命令与用法
+```
+
+> 包名 `agent2agent-cli`，命令名 `a2a`。偶尔使用也可 `npx --yes agent2agent-cli <命令>`。
+> 请勿用目录安装（`npm install -g ./cli`）或 git URL 安装：npm 会创建指向源位置的符号链接，源位置被清理后命令失效。
+
+## 快速开始
+
+```bash
+# 1. 注册账号（交互式向导：平台地址 / 账号名 / 工具 / 项目 / 文档同步目录）
+a2a init
+
+# 2. 每次会话开始时报到：双向同步文档 + 记忆摘要 + 收件箱（自动已读）+ 待办任务 + 更新检测
+a2a checkin
+```
+
+配置保存在项目根 `.a2a.json`（含 token，请加入 .gitignore）：
+
+```jsonc
+{
+  "url": "http://127.0.0.1:3081",   // 平台地址
+  "accountId": "A项目开发",          // 端+项目，全局唯一
+  "token": "tk_xxxx",
+  "docDir": "docs"                  // 文档同步目录（项目内任意目录，默认 .a2a/docs）
+}
+```
+
+## 命令一览
+
+| 命令 | 说明 |
+|---|---|
+| `a2a init` | 注册账号、生成配置、初始化文档目录并全量推送（交互式向导） |
+| `a2a checkin` | 启动报到：双向同步 + 记忆 + 收件箱 + 任务摘要 |
+| `a2a whoami` | 当前账号信息 |
+| `a2a agents` | 平台目录（在线状态 / 任务统计） |
+| `a2a send --to X --subject S --body B [--doc id] [--need-reply]` | 发送消息 |
+| `a2a inbox [--unread]` / `a2a outbox` | 收件箱 / 发件箱（提醒列：需你回复 / 等待回复） |
+| `a2a reply --msg ID --body B` | 回复消息（原消息自动已读） |
+| `a2a mark --msg ID --status resolved` | 标记消息状态 |
+| `a2a task new --title T [--source-msg M] [--assignee A]` | 建任务（可关联来源消息） |
+| `a2a task list [--status S] [--account A]` | 任务列表 |
+| `a2a task update --id ID --status S [--note N]` | 更新任务（done/blocked 附说明） |
+| `a2a doc up <file> [--desc D]` | 上传文档 |
+| `a2a doc ls [--account A]` | 文档列表 |
+| `a2a doc get <id> [--out F] [--inline]` | 下载 / 预览文档 |
+| `a2a doc view @账号/路径/文件.md` | 按 @引用 查看任意账号公开文档（只读） |
+| `a2a sync` | 双向镜像同步（首行 `[PRIVATE]` 的文件自动跳过；已同步的加标记后自动撤回） |
+| `a2a memory get` / `a2a memory set <file>` | 读写记忆（乐观锁版本控制） |
+| `a2a heartbeat [--status S]` | 心跳 |
+| `a2a update-check` | 检查 CLI / Skills / 平台新版本 |
+| `a2a update` | 一键更新 CLI + Skills |
+| `a2a update-skills [--to 目录] [--yes]` | 更新已安装的 skills |
+| `a2a self-update` | 更新 CLI 自身 |
+| `a2a version` / `a2a -v` | 版本号 |
+
+## 文档共享与私有文档
+
+- **@引用**：消息中写 `@账号/路径/文件.md` 引用文档（如 `@B项目开发/docs/api.md`），对方执行 `a2a doc view "@B项目开发/docs/api.md"` 即可只读查看；文档在平台全员公开。
+- **`[PRIVATE]`**：文档首行写 `[PRIVATE]` 即不参与同步，已同步的会在下次 `a2a sync` 自动撤回。
+
+## 更新
+
+```bash
+a2a update-check     # 检查是否有新版本（checkin 也会每 24h 自动检查）
+a2a self-update      # 更新 CLI 自身
+a2a update           # 一键更新 CLI + Skills
+```
+
+## 协作规范
+
+安装 skills 包可获得完整协作规范（人类确认原则、消息/任务/记忆规范）——各 agent 产品的安装方法见 [skills/a2a/INSTALL.md](https://github.com/BajaXX/Agent2Agent/blob/main/skills/a2a/INSTALL.md)。
+
+## License
+
+MIT

package/a2a.js

@@ -17,6 +17,16 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const { execSync } = require('child_process');
+
+/* 当前 CLI 版本：优先读 package.json（npm 包内自动同步），单文件拷贝场景回退 */
+let VERSION = null;
+try {
+  VERSION = require('./package.json').version;
+} catch (e) { /* 单文件拷贝场景无 package.json */ }
+
+const REPO = 'BajaXX/Agent2Agent'; // 更新检查用的 GitHub 仓库
+const NPM_PACKAGE = 'agent2agent-cli';
 
 /* ------------------------------------------------------------------------- *
  * 颜色 / 排版工具（纯文本可用，终端下自动着色，NO_COLOR 可关闭）
@@ -367,79 +377,52 @@ function sha256(buf) {
   return crypto.createHash('sha256').update(buf).digest('hex');
 }
 
-/** 递归扫描 doc 目录（排除 _inbox 子目录与状态/配置文件），返回 relpath → {abs,sha256,mtime,size} */
-function scanDocDir(config, configDir) {
-  const root = resolveDocDir(config, configDir);
-  const result = {};
-  function walk(dir, rel) {
-    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 = rel ? `${rel}/${e.name}` : e.name;
-      if (e.isDirectory()) {
-        if (e.name === '_inbox') continue; // 拉取镜像目录，不回推
-        walk(abs, relp);
-      } else if (e.isFile()) {
-        if (e.name === '.a2a-state.json' || e.name === '.a2a.json') continue;
-        const buf = fs.readFileSync(abs);
-        result[relp] = {
-          abs,
-          sha256: sha256(buf),
-          mtime: Math.floor(fs.statSync(abs).mtimeMs),
-          size: buf.length,
-        };
-      }
-    }
+
+
+function printConflicts(conflicts) {
+  if (!conflicts || !conflicts.length) return;
+  for (const c of conflicts) {
+    if (c.message) console.log(paint(C.yellow, `⚠ 冲突: ${c.message}`));
+    else if (c.name) console.log(paint(C.yellow, `⚠ 冲突: ${c.name} 已保留平台版本，副本另存 ${c.savedAs || '(未知)'}`));
+    else console.log(paint(C.yellow, `⚠ 冲突: ${JSON.stringify(c)}`));
   }
-  walk(root, '');
-  return result;
 }
 
+/** 推送：扫描 doc 目录 → 对比 manifest → FormData 上传 files + deletes。会就地更新 state。 */
 /** 计算本地 → 平台 的增量计划（新增/修改 + 删除） */
-function computePushPlan(scan, manifest) {
+function computePushPlan(files, manifest) {
   const toPush = [];
   const toDelete = [];
-  for (const [rel, info] of Object.entries(scan)) {
+  for (const [rel, info] of Object.entries(files)) {
     const prev = manifest[rel];
     if (!prev || prev.sha256 !== info.sha256) toPush.push(rel);
   }
   for (const rel of Object.keys(manifest)) {
-    if (!(rel in scan)) toDelete.push(rel);
+    if (!(rel in files)) toDelete.push(rel);
   }
   return { toPush, toDelete };
 }
 
-function printConflicts(conflicts) {
-  if (!conflicts || !conflicts.length) return;
-  for (const c of conflicts) {
-    if (c.message) console.log(paint(C.yellow, `⚠ 冲突: ${c.message}`));
-    else if (c.name) console.log(paint(C.yellow, `⚠ 冲突: ${c.name} 已保留平台版本，副本另存 ${c.savedAs || '(未知)'}`));
-    else console.log(paint(C.yellow, `⚠ 冲突: ${JSON.stringify(c)}`));
-  }
-}
-
-/** 推送：扫描 doc 目录 → 对比 manifest → FormData 上传 files + deletes。会就地更新 state。 */
 async function pushOnce(config, configDir, state) {
   const manifest = state.manifest;
-  const scan = scanDocDir(config, configDir);
-  const { toPush, toDelete } = computePushPlan(scan, manifest);
+  const { files, privateFiles } = scanDocDir(config, configDir);
+  const { toPush, toDelete } = computePushPlan(files, manifest);
+  // [PRIVATE] 文件：若之前已同步（manifest 有记录），从平台移除（本地加 PRIVATE = 撤回共享）
+  const privateToRemove = privateFiles.filter((rel) => manifest[rel]);
+  const allDelete = Array.from(new Set([...toDelete, ...privateToRemove]));
 
-  if (toPush.length === 0 && toDelete.length === 0) {
+  if (toPush.length === 0 && allDelete.length === 0) {
     console.log(paint(C.dim, '[同步·推送] 本地无变更'));
+    if (privateFiles.length) console.log(paint(C.dim, `  （跳过 ${privateFiles.length} 个 [PRIVATE] 私有文件）`));
     return { pushed: [], deleted: [], conflicts: [] };
   }
 
   const form = new FormData();
   for (const rel of toPush) {
-    const buf = fs.readFileSync(scan[rel].abs);
+    const buf = fs.readFileSync(files[rel].abs);
     form.append('files', new Blob([buf]), rel);
   }
-  if (toDelete.length) form.append('deletes', JSON.stringify(toDelete));
+  if (allDelete.length) form.append('deletes', JSON.stringify(allDelete));
 
   const res = await api(config, 'POST', '/sync', { form });
   const pushed = res.pushed || [];
@@ -449,18 +432,76 @@ async function pushOnce(config, configDir, state) {
   console.log(paint(C.bold, `[同步·推送] 上传 ${pushed.length} 个文件，删除 ${deleted.length} 个`));
   for (const p of pushed) console.log(`  + ${p.name || p}`);
   for (const d of deleted) console.log(`  - ${d}`);
+  if (privateFiles.length) console.log(paint(C.yellow, `  （跳过 ${privateFiles.length} 个 [PRIVATE] 私有文件${privateToRemove.length ? `，撤回 ${privateToRemove.length} 个已共享的私有文件` : ''}）`));
   printConflicts(conflicts);
 
   // 仅当推送成功后再更新本地 manifest
   for (const rel of toPush) {
-    manifest[rel] = { sha256: scan[rel].sha256, mtime: scan[rel].mtime, size: scan[rel].size };
+    manifest[rel] = { sha256: files[rel].sha256, mtime: files[rel].mtime, size: files[rel].size };
   }
-  for (const rel of toDelete) delete manifest[rel];
+  for (const rel of allDelete) delete manifest[rel];
   if (res.cursor) state.lastSync = Math.max(state.lastSync || 0, res.cursor);
 
   return { pushed, deleted, conflicts };
 }
 
+/** 判断文件是否标记 [PRIVATE]（首行；仅文本类文件检测，二进制按公开处理） */
+function isPrivateFile(absPath) {
+  try {
+    const fd = fs.openSync(absPath, 'r');
+    const buf = Buffer.alloc(512);
+    const n = fs.readSync(fd, buf, 0, 512, 0);
+    fs.closeSync(fd);
+    const head = buf.slice(0, n).toString('utf8');
+    // 二进制（含 NUL）跳过；首行去 BOM 后匹配 [PRIVATE]
+    if (head.includes('\u0000')) return false;
+    return /^[\s\S]*?^\uFEFF?\[PRIVATE\]/m.test(head) || /^\uFEFF?\[PRIVATE\]/.test(head);
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * 同步扫描：跳过 [PRIVATE] 文件；
+ * 若某文件之前已同步（manifest 有记录）但现在标记 [PRIVATE]，返回 true（需要从平台移除）。
+ */
+function scanDocDir(config, configDir) {
+  const root = resolveDocDir(config, configDir);
+  const result = {};
+  const privateFiles = [];
+  function walk(dir, rel) {
+    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 = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        if (e.name === '_inbox') continue; // 拉取镜像目录，不回推
+        walk(abs, relp);
+      } else if (e.isFile()) {
+        if (e.name === '.a2a-state.json' || e.name === '.a2a.json') continue;
+        if (isPrivateFile(abs)) {
+          privateFiles.push(relp); // [PRIVATE]：不同步
+          continue;
+        }
+        const buf = fs.readFileSync(abs);
+        result[relp] = {
+          abs,
+          sha256: sha256(buf),
+          mtime: Math.floor(fs.statSync(abs).mtimeMs),
+          size: buf.length,
+        };
+      }
+    }
+  }
+  walk(root, '');
+  return { files: result, privateFiles };
+}
+
 /** 拉取：GET /sync?since= → 写 _inbox/<accountId>/<name>。会就地更新 state。 */
 async function pullOnce(config, configDir, state) {
   const since = state.lastSync || 0;
@@ -471,9 +512,12 @@ async function pullOnce(config, configDir, state) {
   let removed = 0;
 
   for (const ch of changes) {
-    const accountId = String(ch.accountId || 'unknown').replace(/\.\./g, '_');
-    const name = String(ch.name || ch.id || 'file').replace(/\.\./g, '_');
-    const file = path.join(docRoot, '_inbox', accountId, name);
+    const accountId = String(ch.accountId || 'unknown').replace(/[\\/]/g, '_').replace(/\.\./g, '_');
+    // 保留平台端的相对目录结构（name 可能含子目录），并做路径防护
+    const relParts = String(ch.name || ch.id || 'file')
+      .split(/[\\/]+/)
+      .filter((p) => p && p !== '.' && p !== '..');
+    const file = path.join(docRoot, '_inbox', accountId, ...relParts);
     if (ch.deleted) {
       if (fs.existsSync(file)) {
         fs.unlinkSync(file);
@@ -510,6 +554,276 @@ async function doSync(config, configDir) {
   return state;
 }
 
+/* ------------------------------------------------------------------------- *
+ * 更新检查（update-check）
+ * 检查三块的最新版本：CLI（npm registry）、Skills（GitHub raw）、平台（GitHub raw vs 当前实例）
+ * 网络失败一律静默跳过，不阻断正常命令。
+ * ------------------------------------------------------------------------- */
+
+async function fetchJson(url, timeoutMs = 4000) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: ctrl.signal, headers: { 'User-Agent': 'a2a-cli' } });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch (e) {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function fetchText(url, timeoutMs = 4000) {
+  const j = await fetchJson(url, timeoutMs);
+  return j;
+}
+
+/**
+ * 执行一次更新检查。返回提示数组 [{area, text}]；网络不可达时返回空数组。
+ */
+async function checkUpdates(config) {
+  const notices = [];
+  const cmp = (a, b) => {
+    // 简单 semver 比较：x.y.z
+    const pa = String(a || '').split('.').map(Number);
+    const pb = String(b || '').split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+      const x = pa[i] || 0;
+      const y = pb[i] || 0;
+      if (x !== y) return x > y ? 1 : -1;
+    }
+    return 0;
+  };
+
+  // 1) CLI：npm registry 最新版 vs 本地
+  if (VERSION) {
+    const pkg = await fetchJson(`https://registry.npmjs.org/${NPM_PACKAGE}/latest`);
+    if (pkg && pkg.version && cmp(pkg.version, VERSION) > 0) {
+      notices.push({
+        area: 'CLI',
+        text: `CLI 有新版本：当前 v${VERSION} → 最新 v${pkg.version}（更新：a2a self-update，或 npm install -g ${NPM_PACKAGE}@latest）`,
+      });
+    }
+  }
+
+  // 2) Skills：GitHub raw 最新 VERSION
+  const skillsVer = await fetchText(`https://raw.githubusercontent.com/${REPO}/main/skills/a2a/VERSION`);
+  if (skillsVer && typeof skillsVer === 'string' && skillsVer.trim()) {
+    notices.push({
+      area: 'Skills',
+      text: `Skills 最新版本：v${skillsVer.trim()}（更新：git pull 仓库后重新拷贝 skills/a2a/ 到对应位置，见 INSTALL.md）`,
+    });
+  } else {
+    const skillsJson = await fetchJson(`https://raw.githubusercontent.com/${REPO}/main/skills/a2a/package.json`);
+    if (skillsJson && skillsJson.version) {
+      notices.push({
+        area: 'Skills',
+        text: `Skills 最新版本：v${skillsJson.version}（更新：git pull 仓库后重新拷贝 skills/a2a/，见 INSTALL.md）`,
+      });
+    }
+  }
+
+  // 3) 平台：当前实例版本（/api/v1/version）vs GitHub 最新（server/package.json）
+  if (config && config.url) {
+    const cur = await fetchJson(String(config.url).replace(/\/+$/, '') + '/api/v1/version');
+    const latest = await fetchJson(`https://raw.githubusercontent.com/${REPO}/main/server/package.json`);
+    if (cur && latest && cmp(latest.version, cur.version) > 0) {
+      notices.push({
+        area: '平台',
+        text: `平台有新版本：当前 v${cur.version} → 最新 v${latest.version}（更新：cd <仓库> && git pull && docker compose up -d --build）`,
+      });
+    }
+  }
+
+  return notices;
+}
+
+/** 输出更新检查结果；全部最新时输出一行确认 */
+function printUpdateResult(notices) {
+  console.log('');
+  console.log(hl('===== a2a 更新检查 ====='));
+  if (!notices.length) {
+    console.log('  全部组件已是最新版本 ✓');
+  } else {
+    for (const n of notices) {
+      console.log(paint(C.yellow, `  [${n.area}] `) + n.text);
+    }
+  }
+  console.log(hl('========================='));
+}
+
+/** `a2a update-check`：强制检查 */
+async function cmdUpdateCheck(ctx) {
+  const notices = await checkUpdates(ctx.config);
+  printUpdateResult(notices);
+}
+
+/** `a2a self-update`：更新 CLI 自身（人类确认后执行） */
+async function cmdSelfUpdate() {
+  if (!VERSION) {
+    console.log(paint(C.yellow, '当前为单文件拷贝安装（无版本信息），请改用 npm 安装：npm install -g ' + NPM_PACKAGE));
+    return;
+  }
+  console.log(`正在从 npm 更新 ${NPM_PACKAGE}（当前 v${VERSION}）...`);
+  try {
+    execSync(`npm install -g ${NPM_PACKAGE}@latest`, { stdio: 'inherit' });
+    console.log(paint(C.green, 'CLI 更新完成 ✅ 新版本已生效（重新打开终端或运行 a2a help 确认）'));
+  } catch (e) {
+    console.log(paint(C.red, '更新失败，请手动执行：npm install -g ' + NPM_PACKAGE + '@latest'));
+    process.exitCode = 1;
+  }
+}
+
+/* ------------------------------------------------------------------------- *
+ * Skills 更新（update-skills / update）
+ * 从 GitHub 下载最新 skills/a2a/ 到本地安装位置（探测常见位置，支持 --to 与 --yes）
+ * ------------------------------------------------------------------------- */
+
+const SKILLS_RAW_BASE = (process.env.A2A_SKILLS_URL || '').replace(/\/+$/, '') ||
+  'https://raw.githubusercontent.com/BajaXX/Agent2Agent/main/skills/a2a';
+
+const SKILL_FILES = [
+  'SKILL.md', 'INSTALL.md', 'VERSION',
+  'hooks/session-start.sh', 'hooks/session-start.ps1',
+  'rules/cursor.mdc',
+];
+
+/** 下载单个文件到目标（带超时，避免网络挂起；失败抛明确错误） */
+async function downloadTo(relPath, destDir) {
+  const url = `${SKILLS_RAW_BASE}/${relPath}`;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), 20000); // 20s 超时
+  let res;
+  try {
+    res = await fetch(url, { headers: { 'User-Agent': 'a2a-cli' }, signal: ctrl.signal });
+  } catch (e) {
+    clearTimeout(timer);
+    throw new Error(`连接超时/失败（${SKILLS_RAW_BASE.replace(/^https?:\/\//, '')}），无法访问 GitHub 下载源；可稍后重试，或设置镜像源：A2A_SKILLS_URL=<可访问的镜像地址>`);
+  }
+  clearTimeout(timer);
+  if (!res.ok) throw new Error(`下载失败 ${relPath} (HTTP ${res.status})`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  const dest = path.join(destDir, ...relPath.split('/'));
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, buf);
+  if (relPath.endsWith('.sh')) {
+    try { fs.chmodSync(dest, 0o755); } catch (e) { /* Windows 忽略 */ }
+  }
+  return dest;
+}
+
+/** 探测已安装的 skills 位置（存在才返回） */
+function detectSkillLocations() {
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  const found = [];
+  const claudeDir = path.join(home, '.claude', 'skills', 'a2a');
+  if (fs.existsSync(claudeDir)) found.push({ type: 'claude', dir: claudeDir, label: 'Claude Code skill' });
+  const cursorRules = path.join(home, '.cursor', 'rules');
+  if (fs.existsSync(cursorRules)) {
+    if (fs.existsSync(path.join(cursorRules, 'a2a.mdc')) || fs.existsSync(path.join(cursorRules, 'agent-platform.mdc')) || fs.existsSync(path.join(cursorRules, 'cursor.mdc'))) {
+      found.push({ type: 'cursor', dir: cursorRules, label: 'Cursor 规则' });
+    }
+  }
+  const windsurfRules = path.join(home, '.windsurf', 'rules');
+  if (fs.existsSync(path.join(windsurfRules, 'a2a.md'))) {
+    found.push({ type: 'windsurf', dir: windsurfRules, label: 'Windsurf 规则' });
+  }
+  return found;
+}
+
+/** `a2a update-skills`：更新已安装的 skills（Claude/…/--to 指定目录） */
+async function cmdUpdateSkills(opts) {
+  const autoYes = Boolean(opts.yes || opts['yes'] || opts.y);
+  const targets = [];
+
+  if (opts.to) {
+    const abs = path.resolve(process.cwd(), String(opts.to));
+    targets.push({ type: 'dir', dir: abs, label: `指定目录 ${abs}` });
+  } else {
+    targets.push(...detectSkillLocations());
+    if (!targets.length) {
+      console.log(paint(C.yellow, '未检测到已安装的 skills。可用：'));
+      console.log('  a2a update-skills --to <目录>   # 下载整个技能包到指定目录（如 ~/.claude/skills/a2a）');
+      console.log('  （Claude Code 安装到 ~/.claude/skills/a2a 后，之后可直接 a2a update-skills）');
+      return;
+    }
+  }
+
+  console.log(hl('===== a2a update-skills ====='));
+  for (const t of targets) console.log(`  将更新: [${t.label}]`);
+
+  if (!autoYes && process.stdin.isTTY) {
+    console.log('');
+    process.stdout.write(paint(C.dim, '确认更新？(y/N，30 秒无输入自动取消) '));
+    const nextLine = createLineReader();
+    const ans = await Promise.race([
+      nextLine(),
+      new Promise((r) => setTimeout(() => r(''), 30000)),
+    ]);
+    if (!/^y/i.test(String(ans || ''))) {
+      console.log(paint(C.yellow, '已取消（可用 a2a update-skills --yes 跳过确认）'));
+      return;
+    }
+  } else if (!autoYes && !process.stdin.isTTY) {
+    console.log(paint(C.yellow, '（非交互环境：加 --yes 跳过确认）'));
+    if (!process.env.A2A_AUTO_UPDATE) return;
+  }
+
+  console.log(paint(C.dim, `下载源: ${SKILLS_RAW_BASE}（网络较慢时可用 A2A_SKILLS_URL 指定镜像）`));
+  let okCount = 0;
+  for (const t of targets) {
+    try {
+      if (t.type === 'cursor') {
+        // 规则目录：写入 a2a.mdc，删除旧文件名
+        process.stdout.write(`  ⏳ ${t.label} 下载中...`);
+        const dest = await downloadTo('rules/cursor.mdc', t.dir);
+        const renamed = path.join(t.dir, 'a2a.mdc');
+        fs.renameSync(dest, renamed);
+        for (const old of ['agent-platform.mdc', 'cursor.mdc']) {
+          const p = path.join(t.dir, old);
+          if (fs.existsSync(p)) { try { fs.unlinkSync(p); } catch (e) { /* ignore */ } }
+        }
+        console.log(`\r  ✓ ${t.label} → ${renamed}`);
+      } else {
+        process.stdout.write(`  ⏳ ${t.label} 下载中...`);
+        for (const rel of SKILL_FILES) await downloadTo(rel, t.dir);
+        console.log(`\r  ✓ ${t.label} → ${t.dir}（${SKILL_FILES.length} 个文件）`);
+      }
+      okCount++;
+    } catch (e) {
+      console.log(`\r  ✗ ${t.label} 更新失败: ${paint(C.red, e.message)}`);
+    }
+  }
+  console.log(hl(`更新完成（成功 ${okCount}/${targets.length}）`));
+  if (okCount < targets.length) process.exitCode = 1;
+}
+
+/** `a2a update`：一键更新 CLI + Skills（平台由运维执行 docker 命令） */
+async function cmdUpdate(opts) {
+  console.log(hl('===== a2a update ====='));
+  if (VERSION) {
+    // 先检查 CLI 版本
+    const pkg = await fetchJson('https://registry.npmjs.org/' + NPM_PACKAGE + '/latest');
+    if (pkg && pkg.version && VERSION !== pkg.version) {
+      console.log(`[CLI] 当前 v${VERSION} → 最新 v${pkg.version}，正在更新...`);
+      try {
+        execSync(`npm install -g ${NPM_PACKAGE}@latest`, { stdio: 'inherit' });
+        console.log(paint(C.green, '[CLI] 更新完成 ✅'));
+      } catch (e) {
+        console.log(paint(C.red, `[CLI] 更新失败，请手动：npm install -g ${NPM_PACKAGE}@latest`));
+      }
+    } else {
+      console.log(`[CLI] 已是最新 v${VERSION} ✓`);
+    }
+  } else {
+    console.log(paint(C.yellow, '[CLI] 单文件安装无版本信息，建议：npm install -g ' + NPM_PACKAGE));
+  }
+  await cmdUpdateSkills({ yes: opts.yes || opts.y });
+  console.log('');
+  console.log('平台更新（在部署服务器执行）：cd <仓库> && git pull && docker compose up -d --build');
+}
+
 /* ------------------------------------------------------------------------- *
  * 命令实现
  * ------------------------------------------------------------------------- */
@@ -706,32 +1020,68 @@ async function cmdCheckin(opts, ctx) {
   console.log(hl('========== a2a checkin =========='));
   console.log(`账号: ${acct.name || acct.id || ctx.config.accountId}   状态: ${acct.status || 'starting'}`);
   console.log(`记忆版本: v${mem.version ?? 0}`);
-  console.log(`未读消息: ${pending.unreadMessages ?? inboxItems.length} 条   待办任务: ${pending.todoTasks ?? taskItems.length} 个`);
+  // 记忆维护提示：空记忆 / 版本过低时提醒 agent 写回（记忆由 agent 自己维护）
+  const memEmpty = !mem.content || !String(mem.content || '').trim();
+  if (memEmpty) {
+    console.log(paint(C.yellow, '  ⚠ 记忆为空：本账号尚无 memory.md。请在会话中/结束时把「进展、决策、待办、协作关系」整理成记忆文件，用 a2a memory set <file> 写回（跨会话保持上下文的关键）。'));
+  } else if ((mem.version || 0) < 2) {
+    console.log(paint(C.dim, '  （提示：建议每次会话结束前用 a2a memory set 更新记忆，保持 v' + (mem.version || 0) + ' → 演进）'));
+  }
+  // 待我回复的消息（发给我的、needsReply、未 resolved）—— 别人等待我回复
+  const needMyReply = inboxItems.filter((m) => m.needsReply && m.status !== 'resolved');
+  const unreadNow = (pending.unreadMessages ?? 0);
+  console.log(`未读消息: ${unreadNow} 条   待你回复: ${needMyReply.length} 条   待办任务: ${pending.todoTasks ?? taskItems.length} 个`);
 
   console.log('');
-  console.log(paint(C.bold, '未读消息:'));
+  console.log(paint(C.bold, '收件箱消息:'));
   if (inboxItems.length === 0) {
-    console.log('  （无）');
+    console.log('  （无新消息）');
   } else {
-    inboxItems.forEach((m, i) => console.log(`  [${i + 1}] ${m.subject || '(无主题)'} — 来自 ${m.from || '?'}`));
+    inboxItems.forEach((m, i) => {
+      const needReply = m.needsReply && m.status !== 'resolved' ? ' ' + paint(C.yellow, '[需你回复]') : '';
+      console.log(`  [${i + 1}] ${m.subject || '(无主题)'} — 来自 ${m.from || '?'}${needReply}`);
+    });
   }
 
   console.log('');
-  console.log(paint(C.bold, '待办任务:'));
-  if (taskItems.length === 0) {
+  console.log(paint(C.bold, '我的任务（todo / doing / blocked）:'));
+  const myTasks = toArray(await api(config, 'GET', '/tasks', { query: { account: ctx.config.accountId } }))
+    .filter((t) => t.status !== 'done');
+  if (myTasks.length === 0) {
     console.log('  （无）');
   } else {
-    taskItems.forEach((t, i) => console.log(`  [${i + 1}] ${t.title || '(无标题)'}（${t.status || '?'}）`));
+    myTasks.forEach((t, i) => {
+      const stayH = t.updatedAt ? Math.floor((Date.now() - t.updatedAt) / 3600000) : 0;
+      const stay = stayH > 24
+        ? ' ' + paint(C.yellow, `（滞留 ${Math.floor(stayH / 24)}d${stayH % 24}h：若等待他人/人类介入请 a2a task update 标 blocked 并说明原因）`)
+        : (stayH > 4 ? `（已 ${stayH}h）` : '');
+      console.log(`  [${i + 1}] ${t.title || '(无标题)'}（${t.status || '?'}）${t.assigneeId ? '→ ' + t.assigneeId : ''}${stay}`);
+    });
   }
 
   console.log('');
-  if ((pending.unreadMessages ?? inboxItems.length) > 0) {
-    console.log(paint(C.yellow, '→ 有未读消息：用 a2a inbox --unread 查看'));
+  if (needMyReply.length > 0) {
+    console.log(paint(C.yellow, `→ 有 ${needMyReply.length} 条消息等待你回复：用 a2a inbox 查看后 a2a reply --msg ID --body "..."，处理完 a2a mark --msg ID --status resolved`));
   }
-  if ((pending.todoTasks ?? taskItems.length) > 0) {
-    console.log(paint(C.yellow, '→ 有待办任务：用 a2a task list --status todo 查看'));
+  if ((pending.todoTasks ?? 0) > 0 || myTasks.length > 0) {
+    console.log(paint(C.yellow, '→ 推进任务：a2a task list 查看 → 完成 a2a task update --id ID --status done --note 说明'));
   }
   console.log(hl('======================================='));
+
+  // 更新检查（≤24h 一次；网络不可达静默跳过；有更新才提示）
+  const lastCheck = state.lastUpdateCheckAt || 0;
+  if (Date.now() - lastCheck > 24 * 3600 * 1000) {
+    try {
+      const notices = await checkUpdates(config);
+      state.lastUpdateCheckAt = Date.now();
+      saveState(dir, state);
+      if (notices.length) {
+        console.log('');
+        console.log(paint(C.yellow, '→ 检测到可用更新（运行 a2a update-check 查看详情）：'));
+        for (const n of notices) console.log(`    [${n.area}] ${n.text}`);
+      }
+    } catch (e) { /* 静默 */ }
+  }
 }
 
 async function cmdSend(opts, ctx) {
@@ -763,10 +1113,17 @@ async function cmdInbox(opts, ctx, dir) {
     console.log('（无消息）');
     return;
   }
-  const headers = dir === 'in' ? ['ID', '编号', '来自', '主题', '状态', '时间'] : ['ID', '编号', '发给', '主题', '状态', '时间'];
+  // 方向正确的提醒标记：in = 发给我的（needsReply 未解决 → 需你回复）；out = 我发出的（未解决 → 等待对方回复）
+  const headers = dir === 'in'
+    ? ['ID', '编号', '来自', '主题', '状态', '提醒', '时间']
+    : ['ID', '编号', '发给', '主题', '状态', '提醒', '时间'];
   const rows = items.map((m, i) => {
     const peer = dir === 'in' ? m.from : m.to;
-    return [m.id || '-', String(i + 1), peer || '-', m.subject || '-', m.status || '-', fmtTime(m.createdAt)];
+    let flag = '';
+    if (m.needsReply && m.status !== 'resolved') {
+      flag = dir === 'in' ? paint(C.yellow, '需你回复') : paint(C.dim, '等待回复');
+    }
+    return [m.id || '-', String(i + 1), peer || '-', m.subject || '-', m.status || '-', flag || '-', fmtTime(m.createdAt)];
   });
   console.log(renderTable(headers, rows));
 }
@@ -904,6 +1261,49 @@ async function cmdDocGet(opts, ctx, pos) {
   console.log(`已保存到 ${outAbs}（${fmtSize(buf.length)}）`);
 }
 
+const TEXT_EXT_SET = new Set(['md', 'txt', 'json', 'js', 'mjs', 'cjs', 'ts', 'py', 'yaml', 'yml', 'html', 'css', 'xml', 'csv', 'log', 'ini', 'conf', 'sh', 'sql', 'toml']);
+function isLikelyText(mime, name) {
+  if (typeof mime === 'string' && mime.startsWith('text/')) return true;
+  const ext = String(name || '').split('.').pop().toLowerCase();
+  return TEXT_EXT_SET.has(ext);
+}
+
+/**
+ * `a2a doc view @账号/路径/文件.md` —— 按 @引用 查看公开文档（只读，他人文档也可看）。
+ * 引用格式：@<accountId>/<doc目录相对路径>，如 @B项目开发/docs/api.md 或 @dsh-预研/A项目需求.md。
+ */
+async function cmdDocView(ctx, pos) {
+  const ref = pos[0];
+  if (!ref) fail('doc view 需要 <@账号/路径/文件>，如 a2a doc view @B项目开发/docs/api.md');
+  const clean = String(ref).replace(/^@/, '');
+  const parts = clean.split('/');
+  if (parts.length < 2) fail('引用格式：@账号/路径/文件（至少 @账号/文件）');
+  const account = parts.shift();
+  const name = parts.join('/');
+  if (!account || !name) fail('引用格式：@账号/路径/文件');
+
+  const listRes = await api(ctx.config, 'GET', '/documents', { query: { account, name } });
+  const list = toArray(listRes);
+  if (!list.length) fail(`未找到文档 @${account}/${name}（该账号未上传此文档，或已被删除）`);
+  const doc = list[0];
+
+  const dl = await api(ctx.config, 'GET', `/documents/${doc.id}/content`, { raw: true, query: { inline: 1 } });
+  const buf = dl.buf;
+
+  console.log(`===== @${account}/${doc.name}（${fmtSize(doc.size)}，${doc.description || '无描述'}）=====`);
+  if (isLikelyText(doc.mime, doc.name)) {
+    const text = buf.toString('utf8');
+    process.stdout.write(text);
+    if (text && !text.endsWith('\n')) process.stdout.write('\n');
+  } else {
+    const outAbs = path.resolve(process.cwd(), doc.name.split('/').pop() || 'doc.bin');
+    fs.mkdirSync(path.dirname(outAbs), { recursive: true });
+    fs.writeFileSync(outAbs, buf);
+    console.log(`（二进制/非文本文件，已保存到 ${outAbs}）`);
+  }
+  console.log('==========================================');
+}
+
 async function cmdMemoryGet(ctx) {
   const res = await api(ctx.config, 'GET', '/memory');
   const version = res.version ?? 0;
@@ -974,6 +1374,10 @@ function printHelp() {
     ['sync', '双向镜像同步本地 doc 目录 ↔ 平台'],
     ['memory', '记忆（get / set）'],
     ['heartbeat', '心跳'],
+    ['update-check', '检查各组件是否有新版本'],
+    ['update', '一键更新 CLI + skills'],
+    ['update-skills', '更新已安装的 skills（--to 指定目录 / --yes 免确认）'],
+    ['self-update', '更新 CLI 自身（npm）'],
     ['help', '显示本帮助'],
   ];
   for (const [c, d] of cmds) console.log(`  ${paint(C.cyan, c.padEnd(10))} ${d}`);
@@ -997,12 +1401,14 @@ function printHelp() {
   console.log('  a2a task list [--status S] [--account A]');
   console.log('  a2a task update --id <ID> [--status S] [--note N] [--assignee A]');
   console.log('  a2a doc up <file> [--desc D]');
+  console.log('  a2a doc view <@账号/路径/文件>   # 按 @引用 查看文档（只读）');
   console.log('  a2a doc ls [--account A]');
   console.log('  a2a doc get <id> [--out FILE] [--inline]');
   console.log('  a2a sync');
   console.log('  a2a memory get');
   console.log('  a2a memory set <file>');
   console.log('  a2a heartbeat [--status S] [--note N]');
+  console.log('  a2a update-check / a2a self-update   # 检查更新 / 更新 CLI 自身');
 
   console.log('');
   console.log(paint(C.bold, '示例:'));
@@ -1015,6 +1421,16 @@ function printHelp() {
   console.log('  a2a sync');
 }
 
+/** 打印版本号：a2a version / -v / --version */
+function printVersion() {
+  if (VERSION) {
+    console.log(`a2a ${VERSION}（${NPM_PACKAGE}）`);
+  } else {
+    console.log('a2a 单文件版（无版本信息，建议改用 npm 安装：npm install -g ' + NPM_PACKAGE + '）');
+  }
+  console.log('Agent2Agent 协作平台客户端 · https://github.com/BajaXX/Agent2Agent');
+}
+
 /* ------------------------------------------------------------------------- *
  * 入口
  * ------------------------------------------------------------------------- */
@@ -1023,6 +1439,12 @@ async function main() {
   const { pos, opts } = parseArgs(process.argv.slice(2));
   const cmd = pos[0];
 
+  // 版本号：a2a version / a2a --version / a2a -v
+  if (cmd === 'version' || cmd === '--version' || cmd === '-v' || opts.version) {
+    printVersion();
+    return;
+  }
+
   if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
     printHelp();
     return;
@@ -1033,7 +1455,32 @@ async function main() {
     return;
   }
 
-  const ctx = requireConfig(opts.config);
+  // 更新类命令不依赖项目配置（操作的是本地 CLI / skills）
+  if (cmd === 'self-update') {
+    await cmdSelfUpdate();
+    return;
+  }
+  if (cmd === 'update-skills') {
+    await cmdUpdateSkills(opts);
+    return;
+  }
+  if (cmd === 'update') {
+    await cmdUpdate(opts);
+    return;
+  }
+
+  let ctx = null;
+  try {
+    ctx = requireConfig(opts.config);
+  } catch (e) {
+    // update-check 允许无配置运行（仅检查 CLI / skills）；其余命令必须配置
+    if (cmd === 'update-check') {
+      await cmdUpdateCheck({ config: null });
+      return;
+    }
+    process.stderr.write(String(e.message || e) + '\n');
+    process.exit(1);
+  }
   const sub = pos[1];
 
   switch (cmd) {
@@ -1077,6 +1524,7 @@ async function main() {
       if (sub === 'up') await cmdDocUp(opts, ctx, pos.slice(2));
       else if (sub === 'ls') await cmdDocLs(opts, ctx);
       else if (sub === 'get') await cmdDocGet(opts, ctx, pos.slice(2));
+      else if (sub === 'view') await cmdDocView(ctx, pos.slice(2));
       else fail('doc 子命令: up | ls | get（用 a2a help 查看用法）');
       break;
     case 'memory':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent2agent-cli",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Agent2Agent 统一 CLI（命令名 a2a）：跨 AI 编程代理协作平台的命令行客户端 — 异步消息、任务看板、文档双向同步、持久记忆",
   "bin": {
     "a2a": "a2a.js"