@jack200714/mafw 4.5.1

package/README.md

@@ -0,0 +1,199 @@
+<div align="center">
+
+<img src="packages/desktop/icons/master/app-icon-1024.png" width="120" alt="MAFW — Mafu">
+
+# MAFW
+
+**Memory-Augmented Framework for Work**
+
+会话结束、上下文压缩、模型更替之后——记忆依然存续的 AI Agent 工作平台
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/@jack200714/mafw.svg)](https://www.npmjs.com/package/@jack200714/mafw)
+[![CI](https://github.com/Jackli-2022/mafw/actions/workflows/ci.yml/badge.svg)](https://github.com/Jackli-2022/mafw/actions/workflows/ci.yml)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-blue)](https://github.com/Jackli-2022/mafw)
+
+</div>
+
+---
+
+## 这是什么
+
+MAFW 是一个以**谐波记忆（Harmonic Memory）**为核心的 AI Agent 工作平台。
+它不再只是某个编辑器的插件，而是由四个部分组成的完整系统：
+
+| 组件 | 形态 | 作用 |
+|---|---|---|
+| **Gateway** | 常驻进程（HTTP API :3000 + 事件流） | 记忆存取、Goal 编排、自动化引擎、全部业务中枢 |
+| **Desktop** | Electron 应用 | 对话、Goal 管理、记忆看板、审批与自动化配置的完整 GUI |
+| **TUI** | `mafw tui` 命令 | 终端全功能界面：Chat / Goals / Memory / Triage（markdown 渲染、鼠标点选） |
+| **CLI** | `mafw` 命令 | Gateway 的启动、守护、诊断与运维 |
+| **opencode 插件** | 可选接入 | 在 opencode 内获得记忆注入与 `mafw_*` 工具（其一入口，非必需） |
+
+核心命题：**让 Agent 跨会话、跨上下文压缩、跨模型更替地记住你的偏好、决策与踩过的坑。**
+
+## 核心特性
+
+### 🧠 谐波记忆
+
+- **统一 HarmonicUnit 模型**：episodic / semantic / procedural / global 四类，层级只是标签，检索无视类型
+- **OKF 存储**（Open Knowledge Format）：每条记忆一个 Markdown 文件（frontmatter + 正文），人可直接阅读编辑；索引是纯可推导产物，丢了可重建
+- **BM25 检索**：`primary_abstraction` + `cue_anchors` 上的倒排检索 × 能量 × 显著度，1000 条记忆 ~2-3ms
+- **能量系统**：检索/反馈加成、按天衰减（显著度越高衰减越慢），重要的事自然浮起，琐碎的事自然沉底
+- **MinHash 合并**：跨层相似记忆自动 soft-supersede 合并，历史版本可追溯
+- **Pinned 披露层 + Sticky 便签板**：身份画像每轮必见，"记下来"类提醒限时必达
+- **主动记忆引导**（OptMem 式）：Agent 自主决定何时写入、何时检索，而非被动灌注
+- **环境探测式维护**：记忆 curator 写入前用只读工具验证候选记忆（propose–probe–commit），
+  每周自动重验高价值记忆、被环境证伪的走 supersedes 链更新——能量衰减管"淡忘"，探测验证管"内容有效性"
+
+### 🤖 Goal 编排
+
+- **Manager Agent**：拆解目标 → plan / execute / review 循环，里程碑自动推送；创建即计划评审门（review-then-run）
+- **回合预算**：goal 可设 `maxTurns` / `maxCostUsd`，超限自动硬停（BudgetGuard）
+- **每轮目标快照**注入，compaction 免疫；`/btw` 支线问答不污染主线
+- **演化观测**（RSI Phase 1）：goal 结果、会话映射、失败签名全量落库，为策略演化铺路
+
+### 🖥️ Desktop 应用
+
+Rail 侧边栏 + TabStrip 布局：`chat / goals / memory / approvals / triage / automation / notes` 全功能 GUI，
+右 Dock 内置上下文用量、分模型成本统计与配额窗口，15s 轮询实时刷新。
+
+v1.20 交互面：**steering**（忙碌回合排队续发）、会话分支（fork / revert / unrevert）、全局命令面板（Ctrl+P）、
+每会话审批模式（manual / auto + 预算上限）、系统托盘与 OS 通知、会话导出 Markdown、@file 文件提及、
+transcript 搜索（Ctrl+F）；UI 工具卡插件系统支持 `.js` 文件自定义工具执行卡（v2：依赖声明 + 流式渲染）。
+
+### 🎬 媒体理解
+
+图片 / 视频 / 音频经 A2A 协议接入 Media Agent，主模型原生多模态分析（非文本描述转述），
+每模态可独立配置引擎与模型，支持插件扩展。
+
+### 🐍 持久 Python 内核
+
+会话级 Jupyter kernel（ZeroMQ wire 协议），变量与导入跨工具调用保持，matplotlib 出图直接回传。
+
+### ⚙️ 自动化引擎
+
+Cron 规则驱动：记忆衰减、回合聚合压缩（每小时）、反思管线、stale 记忆重验（每周）；triage 队列让关键决定仍由你确认。
+
+### 🔌 Runtime 能力契约
+
+Gateway 与 Agent runtime 之间是能力自声明契约（Tier 0-2）：内置 opencode runtime、pi runtime 插件、
+external 托管模式可热切换，无需重启。契约能力面覆盖会话分支（fork / revert）、回合预算、
+结果信封（usage / finish）、三值审批回复（once / always / reject）、原生 question 通道等。
+
+## 基准
+
+LongMemEval-S（session 粒度，谐波记忆管线）：
+
+| 指标 | 早期 | 当前 |
+|---|---|---|
+| L1 检索 Recall@10 | 47.4% | **94.9%** |
+| L1 Recall@1 | 5.8% | **58.6%** |
+| L2 端到端 QA 准确率 | 16.7% | **66.7%** |
+
+评测代码：`evaluation/longmemeval/`（数据隔离，不污染真实记忆库）。
+
+## 架构
+
+```
+ Desktop (Electron)      CLI (mafw)      opencode 插件
+        │                     │                │
+        └───────────── HTTP :3000 / SSE ───────┘
+                          │
+                   ┌──────┴───────┐
+                   │    Gateway   │
+                   └──────┬───────┘
+        ┌──────────┬──────┴──────┬───────────┐
+   谐波记忆系统   Goal 编排引擎   自动化引擎   媒体/内核/用量
+   OKF + 索引    manager/plan/  cron 规则    A2A · Jupyter
+   能量·合并     execute/review 衰减·压缩    provider 插件
+```
+
+数据根目录 `~/.mafw/`：记忆 OKF 文件、统一数据库、日志、配置覆盖。
+
+## 快速开始
+
+### 1. 启动 Gateway
+
+```bash
+npm install -g @jack200714/mafw
+
+mafw start          # 前台启动
+mafw daemon         # 后台守护
+mafw status         # 查看状态
+mafw tui            # 终端界面（Chat / Goals / Memory / Triage）
+mafw dashboard      # 打开 Web Dashboard
+```
+
+### 2. 桌面应用
+
+安装包内置 Gateway，开箱即用（无需先装 npm 包）。下载：
+[GitHub Releases 最新版](https://github.com/Jackli-2022/mafw/releases/latest)
+
+| 平台 | 安装包 |
+|---|---|
+| Windows | `mafw-desktop-win-x64.exe`（nsis，未签名） |
+| Linux | `AppImage`（需 `chmod +x`）/ `.deb` / `.rpm` |
+
+或从源码构建：
+
+```bash
+git clone https://github.com/Jackli-2022/mafw
+cd mafw && npm install          # npm workspaces
+cd packages/desktop
+npx electron-vite build
+```
+
+### 3. opencode 接入（可选）
+
+```json
+{
+  "plugin": ["@jack200714/mafw"],
+  "mcp": { "mafw": { "type": "remote", "url": "http://127.0.0.1:3000/mcp", "enabled": true } }
+}
+```
+
+插件激活时自动补写缺失的 MCP 接线并备份原配置（fail-open）。
+
+## 仓库结构
+
+```
+packages/desktop/        Electron 桌面应用（main / preload / renderer）
+packages/tui/            终端界面（pi-tui）
+gateway/                 Gateway 核心（HTTP API、记忆、编排、自动化、媒体、内核）
+src/                     opencode 插件（hooks / tools / MCP 自接线）
+.github/workflows/       CI：双 OS 验证；tag v* 自动出桌面安装包（draft release）
+evaluation/longmemeval/  LongMemEval 记忆基准
+docs/                    设计文档与实施计划
+```
+
+## 文档
+
+| 文档 | 位置 |
+|---|---|
+| 架构总览（AGENTS.md） | `AGENTS.md` |
+| Gateway 架构 | `docs/architecture/gateway.md` |
+| Plugin 架构 | `docs/architecture/plugin.md` |
+| 谐波记忆 v6.3 | `docs/superpowers/specs/2026-07-02-v6.3-harmonic-memory-m1-m3.md` |
+| OKF 存储迁移 v6.8 | `docs/superpowers/specs/2026-07-16-okf-migration-design.md` |
+| Desktop 图标（茉芙/Mafu） | `docs/superpowers/specs/2026-09-10-desktop-icon-design.md` |
+| 记忆基准 | `evaluation/README.md` |
+
+## 声明
+
+MAFW Desktop 应用图标「茉芙 / Mafu」由 AI 辅助生成（智谱 CogView-4）并经人工后处理。
+
+## 参考与致谢
+
+MAFW 的设计站在这些项目与研究的肩膀上：
+
+| 参考 | 与 MAFW 的关系 |
+|---|---|
+| [opencode](https://github.com/sst/opencode) | 插件宿主平台；Desktop 端（`packages/desktop`）源自其桌面架构并深度改造（MAFW Rail/Tabs/Config、gateway sidecar 等） |
+| [Memora](https://arxiv.org/abs/2602.03315)（Microsoft M365 Research, ICML 2026） | 谐波记忆系统的架构参照：`primary_abstraction` / `cue_anchors` / `memory_value` 三元数据模型与其同构；embedding 相似度合并 + LLM UPDATE/CREATE 裁判（ConsolidationService）采用其方案；其 LongMemEval-S 87.4% SOTA 是本项目记忆管线设计的方向验证 |
+| [Grounding Agent Memory](https://arxiv.org/abs/2609.11060)（Microsoft, 2026） | 环境探测式记忆维护（Environment-Probing Curation）的方案来源：post-task curator 以最小权限只读工具在写入前验证候选记忆（propose–probe–commit）、定期重验并刷新 stale 条目；其 CLBench/APEX 实验证明该机制同时提升正确率并降低 task-agent 成本 |
+| OKF（Open Knowledge Format） | 记忆存储层：Markdown + frontmatter、每记忆一文件，索引视为纯可推导产物；设计见 `docs/superpowers/specs/2026-07-16-okf-migration-design.md` |
+
+## 许可
+
+MIT

package/bin/mafw.js

@@ -0,0 +1,436 @@
+#!/usr/bin/env node
+
+const { spawn, execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const http = require('http');
+const os = require('os');
+
+const pkg = require('../package.json');
+const CONFIG_DIR = path.join(os.homedir(), '.config', 'mafw');
+const PID_FILE = path.join(CONFIG_DIR, 'gateway.pid');
+const LOG_DIR = path.join(os.homedir(), '.mafw', 'logs');
+const LOG_FILE = path.join(LOG_DIR, 'mafw.log');
+const GATEWAY_SCRIPT = path.resolve(__dirname, '..', 'gateway', 'dist', 'index.js');
+const GATEWAY_PORT = process.env.MAFW_GATEWAY_PORT || process.env.MAFW_SERVER_API_PORT || '3000';
+const GATEWAY_URL = process.env.MAFW_GATEWAY_URL || `http://localhost:${GATEWAY_PORT}`;
+
+const USAGE = `
+MAFW CLI v${pkg.version}
+
+Usage: mafw <command> [options]
+
+Process Commands:
+  start              Start Gateway in foreground
+  daemon             Start Gateway in background (detached)
+  stop               Stop running Gateway
+  status             Show Gateway status (PID / health)
+  restart            Restart Gateway
+  logs               Show recent logs (last 50 lines)
+
+API Commands:
+  health             Gateway health check (GET /health)
+  stats              Gateway statistics (GET /api/stats)
+  restart-agent      Restart the agent serve process (POST /api/runtime/restart-agent)
+  projects           List registered projects (GET /api/projects)
+  goals              List active goals (GET /api/goals)
+  register <dir>     Register a project (POST /register)
+  sessions           List sessions (GET /api/sessions)
+  control <action> <goalId>  Control goal (pause|abort|force-phase)
+  memory-search <query>      Memory context injection (GET /api/memory/merged-search)
+  automations        List automation rules (GET /api/automations)
+  approvals          List pending approvals (GET /api/approvals)
+  triage             List triage items (GET /api/triage)
+
+Service Commands:
+  service-register   Register as OS-level auto-start service
+  service-unregister Unregister OS-level service
+
+Utility Commands:
+  config             Show gateway config
+  dashboard          Open Dashboard in browser
+  tui                Open terminal UI (chat + goals/memory/triage)
+  uninstall          Uninstall instructions
+  version            Show version
+`;
+
+const COMMANDS = [
+  'start', 'daemon', 'stop', 'status', 'restart', 'logs',
+    'health', 'stats', 'projects', 'goals', 'register',
+    'sessions', 'control', 'memory-search',
+    'automations', 'approvals', 'triage', 'restart-agent',
+  'service-register', 'service-unregister',
+  'config', 'dashboard', 'uninstall', 'version', 'update', 'tui',
+];
+
+function httpRequest(method, urlPath, body) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(urlPath, GATEWAY_URL);
+    const opts = {
+      hostname: url.hostname,
+      port: url.port,
+      path: url.pathname + url.search,
+      method,
+      headers: { 'Content-Type': 'application/json' },
+      timeout: 10000,
+    };
+    const req = http.request(opts, (res) => {
+      let data = '';
+      res.on('data', (chunk) => data += chunk);
+      res.on('end', () => {
+        try {
+          resolve({ status: res.statusCode, body: JSON.parse(data) });
+        } catch {
+          resolve({ status: res.statusCode, body: data });
+        }
+      });
+    });
+    req.on('error', (err) => reject(err));
+    req.on('timeout', () => { req.destroy(); reject(new Error('Request timeout')); });
+    if (body) req.write(JSON.stringify(body));
+    req.end();
+  });
+}
+
+function ensureDirs() {
+  if (!fs.existsSync(CONFIG_DIR)) fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  if (!fs.existsSync(LOG_DIR)) fs.mkdirSync(LOG_DIR, { recursive: true });
+}
+
+function readPid() {
+  if (!fs.existsSync(PID_FILE)) return null;
+  return fs.readFileSync(PID_FILE, 'utf-8').trim();
+}
+
+function isRunning(pid) {
+  try { process.kill(Number(pid), 0); return true; }
+  catch { return false; }
+}
+
+function writePid(pid) { fs.writeFileSync(PID_FILE, String(pid)); }
+function removePid() { try { fs.unlinkSync(PID_FILE); } catch {} }
+
+function startGateway(background) {
+  ensureDirs();
+  const existingPid = readPid();
+  if (existingPid && isRunning(existingPid)) {
+    console.log(`Gateway already running (PID: ${existingPid})`);
+    return;
+  }
+  if (existingPid) removePid();
+
+  if (!fs.existsSync(GATEWAY_SCRIPT)) {
+    console.error(`Gateway script not found: ${GATEWAY_SCRIPT}`);
+    console.error('Run: cd gateway && npm run build');
+    process.exit(1);
+  }
+
+  const child = spawn(process.execPath, [GATEWAY_SCRIPT], {
+    stdio: background ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+    detached: background,
+    windowsHide: true,
+  });
+
+  writePid(child.pid);
+
+  if (background) {
+    // Diagnostics: capture stderr to a file (a detached gateway that crashes
+    // silently otherwise leaves no trace). stdout is discarded; the gateway's
+    // own file logging covers normal logs.
+    // NOTE: use a raw fd + writeSync — a fs.WriteStream here never ends, which
+    // keeps the parent's event loop alive so `mafw daemon` hangs (and any
+    // tree-kill then takes the detached gateway down with it).
+    const errLog = path.join(LOG_DIR, 'gateway-stderr.log');
+    try { if (!fs.existsSync(LOG_DIR)) fs.mkdirSync(LOG_DIR, { recursive: true }); } catch {}
+    const errFd = fs.openSync(errLog, 'a');
+    if (child.stderr) {
+      child.stderr.on('data', (chunk) => { try { fs.writeSync(errFd, chunk); } catch {} });
+    }
+    if (child.stdout) child.stdout.destroy();
+    child.unref();
+    console.log(`Gateway started in background (PID: ${child.pid})`);
+    console.log(`Logs: ${LOG_FILE}`);
+  } else {
+    console.log(`Gateway starting (PID: ${child.pid})`);
+    child.on('exit', (code) => { removePid(); process.exit(code); });
+  }
+}
+
+function stopGateway() {
+  const pid = readPid();
+  if (!pid) { console.log('Gateway not running'); return; }
+  if (!isRunning(pid)) {
+    console.log('Gateway not running (stale PID)');
+    removePid();
+    return;
+  }
+  try {
+    process.kill(Number(pid), 'SIGTERM');
+    console.log(`Gateway stopped (PID: ${pid})`);
+  } catch (err) {
+    console.error(`Failed to stop: ${err.message}`);
+  }
+  removePid();
+}
+
+function showStatus() {
+  const pid = readPid();
+  if (!pid || !isRunning(pid)) {
+    console.log('Gateway: STOPPED');
+    if (pid) removePid();
+    return;
+  }
+  console.log(`Gateway: RUNNING (PID: ${pid})`);
+  console.log(`URL: ${GATEWAY_URL}`);
+  console.log(`Logs: ${LOG_FILE}`);
+}
+
+function showLogs() {
+  if (!fs.existsSync(LOG_FILE)) {
+    console.log('No logs yet');
+    return;
+  }
+  const lines = fs.readFileSync(LOG_FILE, 'utf-8').split(/\r?\n/);
+  const tail = lines.length > 50 ? lines.slice(-50) : lines;
+  console.log(tail.join('\n'));
+}
+
+async function callApi(name, method, urlPath, body) {
+  try {
+    const res = await httpRequest(method || 'GET', urlPath, body);
+    if (res.status >= 400) {
+      console.error(`Error ${res.status}: ${typeof res.body === 'string' ? res.body : JSON.stringify(res.body)}`);
+      return;
+    }
+    console.log(JSON.stringify(res.body, null, 2));
+  } catch (err) {
+    console.error(`API call failed: ${err.message}`);
+    console.error(`Is the gateway running? Try: mafw start`);
+  }
+}
+
+function registerService() {
+  ensureDirs();
+  const script = path.resolve(GATEWAY_SCRIPT);
+  const platform = process.platform;
+  if (platform === 'win32') {
+    const taskName = 'MAFW-Gateway';
+    const cmd = `schtasks /create /tn "${taskName}" /tr "node \\"${script}\\"" /sc onlogon /rl highest /f`;
+    try { execSync(cmd, { stdio: 'inherit' }); console.log(`Scheduled task "${taskName}" registered`); }
+    catch (err) { console.error(`Failed: ${err.message}`); process.exit(1); }
+  } else if (platform === 'darwin') {
+    const agentDir = path.join(os.homedir(), 'Library', 'LaunchAgents');
+    const plistPath = path.join(agentDir, 'com.mafw.gateway.plist');
+    if (!fs.existsSync(agentDir)) fs.mkdirSync(agentDir, { recursive: true });
+    const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.mafw.gateway</string>
+  <key>ProgramArguments</key>
+  <array><string>/usr/local/bin/node</string><string>${script}</string></array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${LOG_FILE}</string>
+  <key>StandardErrorPath</key><string>${LOG_FILE}</string>
+</dict>
+</plist>`;
+    fs.writeFileSync(plistPath, plist, 'utf-8');
+    try { execSync(`launchctl load "${plistPath}"`, { stdio: 'inherit' }); console.log(`LaunchAgent registered: ${plistPath}`); }
+    catch (err) { console.error(`Failed: ${err.message}`); }
+  } else {
+    const unitDir = path.join(os.homedir(), '.config', 'systemd', 'user');
+    const unitPath = path.join(unitDir, 'mafw-gateway.service');
+    if (!fs.existsSync(unitDir)) fs.mkdirSync(unitDir, { recursive: true });
+    const unit = `[Unit]
+Description=MAFW Gateway
+After=network.target
+[Service]
+ExecStart=/usr/bin/node ${script}
+Restart=on-failure
+RestartSec=5
+StandardOutput=append:${LOG_FILE}
+StandardError=append:${LOG_FILE}
+[Install]
+WantedBy=default.target`;
+    fs.writeFileSync(unitPath, unit, 'utf-8');
+    try {
+      execSync('systemctl --user daemon-reload', { stdio: 'inherit' });
+      execSync('systemctl --user enable mafw-gateway.service', { stdio: 'inherit' });
+      console.log(`systemd service registered: ${unitPath}`);
+    } catch (err) { console.error(`Failed: ${err.message}`); }
+  }
+}
+
+function unregisterService() {
+  const platform = process.platform;
+  if (platform === 'win32') {
+    try { execSync('schtasks /delete /tn "MAFW-Gateway" /f', { stdio: 'inherit' }); console.log('Scheduled task unregistered'); }
+    catch (err) { console.error(`Failed: ${err.message}`); }
+  } else if (platform === 'darwin') {
+    const plistPath = path.join(os.homedir(), 'Library', 'LaunchAgents', 'com.mafw.gateway.plist');
+    if (fs.existsSync(plistPath)) {
+      try { execSync(`launchctl unload "${plistPath}"`, { stdio: 'inherit' }); fs.unlinkSync(plistPath); console.log('LaunchAgent unregistered'); }
+      catch (err) { console.error(`Failed: ${err.message}`); }
+    } else { console.log('No LaunchAgent found'); }
+  } else {
+    try {
+      execSync('systemctl --user disable mafw-gateway.service', { stdio: 'inherit' });
+      const unitPath = path.join(os.homedir(), '.config', 'systemd', 'user', 'mafw-gateway.service');
+      if (fs.existsSync(unitPath)) fs.unlinkSync(unitPath);
+      console.log('systemd service unregistered');
+    } catch (err) { console.error(`Failed: ${err.message}`); }
+  }
+}
+
+function openDashboard() {
+  const url = `http://localhost:${Number(GATEWAY_PORT)}/`;
+  console.log(`Opening Dashboard: ${url}`);
+  try {
+    if (process.platform === 'win32') execSync(`start "" "${url}"`, { stdio: 'ignore' });
+    else if (process.platform === 'darwin') execSync(`open "${url}"`, { stdio: 'ignore' });
+    else execSync(`xdg-open "${url}"`, { stdio: 'ignore' });
+  } catch { console.log(`Open in browser: ${url}`); }
+}
+
+function showConfig() {
+  const configFile = path.join(CONFIG_DIR, 'config.json');
+  if (fs.existsSync(configFile)) {
+    console.log(fs.readFileSync(configFile, 'utf-8'));
+  } else {
+    console.log('{}');
+    console.log(`(Create ${configFile} to set persistent config)`);
+  }
+}
+
+function showUninstall() {
+  console.log(`
+MAFW Uninstall
+
+1. Remove plugin from opencode.json:
+   - Edit ~/.config/opencode/config.json
+   - Remove "@jack200714/mafw" from plugins array
+
+2. Delete plugin data:
+   rm -rf ~/.config/mafw
+   rm -rf ~/.mafw
+
+3. Uninstall npm package:
+   npm uninstall -g @jack200714/mafw
+
+4. Stop Gateway:
+   mafw stop
+  `);
+}
+
+async function main() {
+  const cmd = process.argv[2];
+  if (!cmd || cmd === '--help' || cmd === '-h') { console.log(USAGE); return; }
+
+  if (!COMMANDS.includes(cmd)) {
+    console.error(`Unknown command: ${cmd}`);
+    console.log(USAGE);
+    process.exit(1);
+  }
+
+  switch (cmd) {
+    case 'start': startGateway(false); break;
+    case 'daemon': startGateway(true); break;
+    case 'stop': stopGateway(); break;
+    case 'status': showStatus(); break;
+    case 'restart':
+      stopGateway();
+      startGateway(true);
+      break;
+    case 'logs': showLogs(); break;
+
+    case 'health': await callApi('health', 'GET', '/health'); break;
+    case 'restart-agent': await callApi('restart-agent', 'POST', '/api/runtime/restart-agent'); break;
+    case 'stats': await callApi('stats', 'GET', '/api/stats'); break;
+    case 'projects': await callApi('projects', 'GET', '/api/projects'); break;
+    case 'goals': await callApi('goals', 'GET', '/api/goals'); break;
+    case 'sessions': await callApi('sessions', 'GET', '/api/sessions'); break;
+    case 'automations': await callApi('automations', 'GET', '/api/automations'); break;
+    case 'approvals': await callApi('approvals', 'GET', '/api/approvals'); break;
+    case 'triage': await callApi('triage', 'GET', '/api/triage'); break;
+
+    case 'register': {
+      const dir = process.argv[3];
+      if (!dir) { console.error('Usage: mafw register <projectDir>'); process.exit(1); }
+      await callApi('register', 'POST', '/register', { projectDir: path.resolve(dir), mafwDir: path.join(path.resolve(dir), '.mafw') });
+      break;
+    }
+    case 'control': {
+      const action = process.argv[3];
+      const goalId = process.argv[4];
+      if (!action || !goalId) { console.error('Usage: mafw control <pause|abort|force-phase> <goalId>'); process.exit(1); }
+      await callApi('control', 'POST', '/control', { action: action.toUpperCase(), goalId });
+      break;
+    }
+    case 'memory-search': {
+      const query = process.argv.slice(3).join(' ');
+      if (!query) { console.error('Usage: mafw memory-search <query>'); process.exit(1); }
+      await callApi('memory-search', 'GET', `/api/memory/merged-search?query=${encodeURIComponent(query)}`);
+      break;
+    }
+
+    case 'service-register': registerService(); break;
+    case 'service-unregister': unregisterService(); break;
+    case 'config': showConfig(); break;
+    case 'dashboard': openDashboard(); break;
+    case 'uninstall': showUninstall(); break;
+    case 'version': console.log(`v${pkg.version}`); break;
+    case 'update': requestUpdate(); break;
+    case 'tui': launchTui(); break;
+  }
+}
+
+// `mafw update`: write the self-update token (atomic tmp+rename). The running
+// gateway watches ~/.mafw/pending-restart.json, rebuilds itself and hands off
+// to a takeover process; it then notifies the caller session.
+function requestUpdate() {
+  const pid = readPid();
+  if (!pid || !isRunning(pid)) {
+    console.error('Gateway is not running. Start it first: mafw start / mafw daemon');
+    process.exit(1);
+  }
+  ensureDirs();
+  const token = {
+    target: 'gateway',
+    action: 'update',
+    reason: 'mafw update (CLI)',
+    requestedAt: new Date().toISOString(),
+    delayMs: 3000,
+  };
+  const tmp = path.join(CONFIG_DIR, 'pending-restart.json.tmp');
+  const dst = path.join(os.homedir(), '.mafw', 'pending-restart.json');
+  try {
+    fs.mkdirSync(path.dirname(dst), { recursive: true });
+    fs.writeFileSync(tmp, JSON.stringify(token, null, 2), 'utf-8');
+    fs.renameSync(tmp, dst);
+    console.log('Update requested: gateway will rebuild and restart itself (~3s).');
+  } catch (err) {
+    console.error(`Failed to write update token: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// `mafw tui`: launch the terminal UI (packages/tui). stdio inherit so the TUI
+// owns the console; windowsHide:false because a TUI needs a visible console
+// (unlike gateway sidecar spawns, which must set it true).
+function launchTui() {
+  const tuiScript = path.resolve(__dirname, '..', 'packages', 'tui', 'dist', 'cli.js');
+  if (!fs.existsSync(tuiScript)) {
+    console.error('TUI not built. Run: npm run build');
+    process.exit(1);
+  }
+  const child = spawn(process.execPath, [tuiScript, ...process.argv.slice(3)], {
+    stdio: 'inherit',
+    windowsHide: false,
+  });
+  child.on('exit', (code) => process.exit(code ?? 0));
+}
+
+main().catch(err => { console.error(err.message); process.exit(1); });
+

package/dist/hooks/bash-python-guide.d.ts

@@ -0,0 +1,4 @@
+export declare function pythonGuideHook(input: any, output: any): any;
+/** 测试辅助：重置会话去重。 */
+export declare function _resetPythonGuideState(): void;
+//# sourceMappingURL=bash-python-guide.d.ts.map

package/dist/hooks/bash-python-guide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bash-python-guide.d.ts","sourceRoot":"","sources":["../../src/hooks/bash-python-guide.ts"],"names":[],"mappings":"AAmCA,wBAAgB,eAAe,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAG,GAAG,CA6B5D;AAED,mBAAmB;AACnB,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}