nano-code-monitor

nano-code 的后台进程监控插件（v0.1.3）。提供三个工具：monitor（启动后台进程）、monitor_get（查询输出）、monitor_kill（终止进程），支持流式输出实时推送给 LLM。

Architecture

nano-code 核心 → monitor 工具调用 → MonitorManager.spawn() → child_process
                                     │
                                     ├── onLine    → StreamEventBuffer
                                     ├── onMatch   → StreamEventBuffer + setNotify
                                     ├── onExit    → StreamEventBuffer + setNotify
                                     └── onError   → StreamEventBuffer + setNotify
                                            │
                                            ▼
                                     onBeforeRequest 钩子
                                            │
                                            ▼
                                     LLM 请求消息（user message 注入）

三层独立职责：

1. src/manager.ts — MonitorManager：进程生命周期管理

   • child_process.spawn() 后台启动命令
   • 按行分割 stdout/stderr，累积到输出缓冲区
   • onLine/onMatch/onExit/onError 回调通知
   • stop/get/list/cleanup/killAll 管理接口

2. src/stream-events.ts — StreamEventBuffer：事件缓冲队列

   • enqueue() 将输出事件序列化为 JSON 字符串入队
   • drain() 取出所有待消费事件并清空队列

3. src/index.ts — monitorPlugin（NanoPlugin）：工具注册 + 生命周期钩子

   • getTools() 注册三个工具（monitor/monitor_get/monitor_kill）
   • execute() 分发工具调用到 MonitorManager
   • onBeforeRequest() 将 StreamEventBuffer 事件注入到 LLM 消息
   • onAgentExit() 清理子 agent 衍生的 monitor 进程
   • onDestroy() 全量 kill

Quick Start

构建

npm install
npm run build       # tsc 编译到 dist/

安装到 nano-code

从 npm 安装（推荐）：

nano-code plugin install @preprocess-cn/nano-code-monitor

本地安装：

nano-code plugin install /path/to/nano-code-monitor

安装后 .nano-code.yaml 自动生成配置：

plugins:
  monitor:
    type: npm
    spec: @preprocess-cn/nano-code-monitor
    enabled: true

验证安装

nano-code plugin list
# monitor  active  [npm]

Tools

| 工具 | 作用 | sideEffect | |------|------|-----------| | monitor | 在后台启动命令，返回 taskId | true | | monitor_get | 获取 monitor 的当前输出（支持正则过滤） | false | | monitor_kill | 终止运行中的 monitor 进程 | true |

monitor

{
  "command": "npm run build",
  "pattern": "error|Error",
  "description": "前端构建"
}

启动后立即返回 taskId，输出行以 monitor:line 流事件推送到 LLM。指定 pattern 时匹配到该正则的行会触发 monitor:match 事件和状态栏通知，进程继续运行，由 LLM 决定是否终止。

monitor_get

{
  "taskId": "m_a1b2c3d4",
  "filter": "error"
}

返回进程的完整状态和累积输出。可选 filter 正则过滤仅返回匹配行。

monitor_kill

{
  "taskId": "m_a1b2c3d4"
}

发送 SIGTERM 终止进程。已退出的进程返回当前状态信息。

Display 集成

通过 AgentReadyContext.display 窄接口（DisplayStatusBar & DisplayNotifier）集成：

• setStatusBar('Monitor', 'N') 显示活跃 monitor 数量，0 时自动隐藏
• setNotify('monitor', 'msg') pattern 匹配/非零退出时在状态栏右侧通知

生命周期

| 场景 | 行为 | |------|------| | 子 agent 退出 | onAgentExit → cleanup(agentName) 自动 kill 该 agent 的所有 monitor | | 主 agent 跨轮 | onAgentExit 不触发，monitor 跨轮存活 | | 进程退出 | updateStatusBar() 自动 -1，0 时隐藏 | | 插件销毁 | onDestroy → killAll() 兜底清理 |

Security

内嵌危险命令黑名单（与 nano-code command.ts 一致），阻塞以下操作：

• 毁灭性删除（rm -rf /）
• 磁盘物理破坏（dd、mkfs）
• 系统关机重启
• Fork 炸弹
• 反弹 Shell
• 用户篡改（passwd、userdel）

项目文件结构

├── src/
│   ├── index.ts          # NanoPlugin 主入口（工具 + 钩子）
│   ├── manager.ts        # MonitorManager 进程生命周期
│   ├── stream-events.ts  # StreamEventBuffer 事件缓冲
│   └── types.ts          # 类型定义 + 窄接口 + 黑名单
├── tests/
│   ├── manager.test.ts   # MonitorManager 15 用例
│   └── stream-events.test.ts  # StreamEventBuffer 4 用例
├── docs/
│   └── design.md         # 设计文档
├── .github/
│   └── workflows/
│       ├── ci.yml             # CI：多 Node 版本测试
│       └── publish.yml        # CD：tag 触发 npm 发布
├── .nano-code.yaml            # nano-code 插件配置
├── LICENSE                    # MIT
├── README.md
├── ROADMAP.md
├── package.json
└── tsconfig.json

开发

npm test        # 运行所有测试
npm run build   # 编译到 dist/

License

MIT