🪨 Dundun Agent

Solid as a rock, sharp as a blade.

TypeScript 实现的本地 AI Agent 运行时。提供终端 TUI、Fastify WebSocket 服务端、多模型 Provider、工具调用、权限管理、上下文压缩、会话持久化、记忆系统、Skill 插件与 MCP 扩展能力。

功能矩阵

| 模块 | 能力 | |------|------| | Terminal CLI | 全功能 TUI：Markdown 渲染、流式输出、/ 命令菜单、trace 详情页、交互式权限/澄清面板 | | Server | Fastify + WebSocket：/health 健康检查、/ws 双向消息协议（16 种消息类型） | | Providers | OpenAI / Anthropic / Minimax / Google Gemini / OpenAI-compatible（DeepSeek、Qwen、GLM 等） | | Agents | general · build · plan · explore，统一异步生成器运行时 | | Tools | 12 类内置工具（见下表），可扩展 MCP 工具 | | Memory | 三层记忆：SQLite 语义记忆 + Markdown file-backed + Skill 索引，反思侧车自动蒸馏 | | Context Compression | 工具输出裁剪 → 弱摘要 → 强摘要，基于 token 估算自动触发 | | Permission | glob 规则引擎，Allow / Deny / Ask + 规则持久化 | | Persistence | 兼容 Python 版布局：session / memory / plugin / log | | Plugins | 插件市场 + 本地/全局安装，支持 Git 源与本地路径 | | MCP | 完整 MCP 客户端，stdio + Streamable HTTP 双传输 |

内置工具一览

| 工具 | 说明 | |------|------| | read | 读取文件（文本/图片/PDF/Jupyter），支持行范围 | | write | 写入文件，自动创建目录 | | edit | 精确字符串替换（支持 replace_all） | | glob | 文件名 glob 匹配搜索 | | grep | 正则表达式代码搜索 | | bash | Shell 命令执行（带超时、风险等级、workspace 边界） | | todowrite / todoread | 任务列表管理 | | clarify | 歧义澄清，向用户提问 | | skill | 加载内置 Skill 到对话 | | websearch | 网页搜索 | | webfetch | 获取网页内容（size/type/redirect 限制） | | codesearch | Exa Code API 代码搜索 | | task | 启动子 Agent（explore / plan / general / build） | | mcp | MCP 工具代理调用 | | lsp | LSP documentSymbol / workspaceSymbol | | maps_* | 高德地图系列（地理编码/路径规划/周边搜索/天气/IP定位） | | resolve-library-id / query-docs | Context7 文档查询 |

快速开始

环境要求

• Node.js ≥ 24
• npm

git clone <repo>
cd dundun_agent
npm install

运行模式

# 一体化模式（服务端 + Terminal CLI 同时启动）
npm run dev

# 仅服务端
npm run dev -- --server-only --host 127.0.0.1 --port 8367

# 仅客户端（连接已有服务端）
npm run dev -- --server 127.0.0.1:8367

全局安装

npm run build
npm link                    # 注册为全局命令 dundun
dundun --help               # 验证

CLI 参数

dundun [options]

Options:
  -s, --server <server>       服务端地址，如 localhost:8367
      --server-only           只启动服务端（不启动客户端）
  -c, --client <client>       客户端类型：cli | terminal | rocketchat | feishu | web
      --trace-port <port>     Terminal CLI trace 详情页端口（默认 8377）
      --web-port <port>       Web dev server 端口（默认 8110）
      --web-host <host>       Web dev server host（默认 127.0.0.1）
  -p, --port <port>           服务端端口（默认 8367）
      --host <host>           服务端绑定地址（默认 0.0.0.0）
  -d, --debug                 调试模式
      --auto                  启动后直接进入自动权限模式
  -a, --agent <agent>         外部 Agent 定义（可多次指定）
      --mcp <mcp>             外部 MCP 服务器配置（JSON 字符串或文件路径）

配置

运行时配置读取 ~/.dundun/config.json，模型选择写入 ~/.dundun/setting.json。

api_key 支持 ${ENV_NAME} 环境变量展开。

{
  "provider": {
    "default": "minimax/MiniMax-M2.7",
    "minimax": {
      "type": "minimax",
      "api_key": "${MINIMAX_API_KEY}",
      "base_url": "https://api.minimax.io/v1",
      "models": ["MiniMax-M2.7", "MiniMax-M2.7-highspeed"],
      "context_window": 204800
    },
    "openai": {
      "type": "openai",
      "api_key": "${OPENAI_API_KEY}",
      "models": ["gpt-5.4"]
    },
    "anthropic": {
      "type": "anthropic",
      "api_key": "${ANTHROPIC_API_KEY}",
      "models": ["claude-opus-4-6", "claude-sonnet-4-6"]
    },
    "google": {
      "type": "google",
      "api_key": "${GOOGLE_API_KEY}",
      "models": ["gemini-3.1-pro-preview"]
    }
  }
}

支持模型速查

| Provider | 代表模型 | Context Window | |----------|---------|----------------| | OpenAI | gpt-5.4, gpt-5.3, gpt-5.2-codex | ~400K | | Anthropic | claude-opus-4-6, claude-sonnet-4-6 | 200K | | Minimax | MiniMax-M2.7, MiniMax-M2.7-highspeed | 204.8K | | Google | gemini-3.1-pro-preview, gemini-3-flash-preview | ~1M | | GLM | glm-5.1, glm-5, glm-4.7, glm-4.6 | 200K | | Qwen | qwen3.6-plus, qwen3.6-flash, qwen3-coder-plus | 256K~1M | | DeepSeek | deepseek-v4-flash, deepseek-v4-pro | 1M |

架构

                    ┌──────────────────────────────┐
                    │        Terminal TUI           │
                    │   (interactions/ rendering)   │
                    └──────────────┬───────────────┘
                                   │ WebSocket (msg types)
                    ┌──────────────▼───────────────┐
                    │      Fastify Server           │
                    │   session mgr · msg router    │
                    └──────────────┬───────────────┘
                                   │
        ┌──────────────┬───────────┼───────────┬──────────────┐
        ▼              ▼           ▼           ▼              ▼
   ┌─────────┐  ┌──────────┐ ┌────────┐ ┌─────────┐  ┌──────────┐
   │Provider │  │  Agent   │ │Context │ │  Tools  │  │  Memory  │
   │ layer   │  │ runtime  │ │compress│ │registry │  │  system  │
   └─────────┘  └──────────┘ └────────┘ └─────────┘  └──────────┘
        │              │                         │
   ┌────┴────┐   ┌────┴────┐              ┌────┴────┐
   │OpenAI   │   │general  │              │MCP      │
   │Anthropic│   │build    │              │LSP      │
   │Minimax  │   │plan     │              │Skill    │
   │Google   │   │explore  │              │Plugin   │
   │Compat.. │   └─────────┘              └─────────┘
   └─────────┘

目录结构

src/
├── cli/                    CLI 入口：参数解析、端口发现、启动编排
├── server/                 Fastify/WebSocket 服务端
│   ├── app.ts              服务创建、/health + /ws 路由
│   ├── session.ts          Session 模型与模型工厂
│   ├── session-manager.ts  Session 生命周期
│   ├── websocket-handler.ts WebSocket 消息路由器（16 种消息类型）
│   └── constants.ts        消息/事件枚举、Agent 类型常量
├── providers/              模型 Provider 抽象层
│   ├── base.ts             核心类型（Message, ToolCall, BaseModelClient）
│   ├── factory.ts          客户端工厂 + 模型发现
│   ├── models.ts           模型注册表 + Provider 推断
│   ├── openai-client.ts    OpenAI / OpenAI-compatible
│   ├── anthropic-client.ts Anthropic
│   └── minimax-client.ts   Minimax
├── agents/                 Agent 运行时
│   ├── base-agent.ts       run() 异步生成器：工具循环、权限、doom loop
│   └── index.ts            内置 Agent 类型注册
├── context/                上下文管理
│   ├── base-context.ts     CompressionResult 接口
│   ├── compression.ts      摘要压缩逻辑
│   └── default-context.ts  默认上下文实现
├── tools/                  工具系统
│   ├── registry.ts         工具注册与查找
│   ├── base.ts             工具输出/错误类型
│   ├── filesystem.ts       read/write/edit/glob/grep
│   ├── system.ts           bash
│   ├── todo.ts             todowrite/todoread
│   ├── clarify.ts          澄清
│   ├── skill.ts            Skill 加载
│   ├── web.ts              websearch/webfetch
│   ├── task.ts             Task 子 Agent
│   ├── mcp.ts              MCP 工具代理
│   ├── lsp.ts              LSP 符号查询
│   └── truncation.ts       工具输出裁剪
├── core/                   核心模块
│   ├── config.ts           配置加载
│   ├── logger.ts           日志
│   ├── paths.ts            数据目录布局
│   ├── permission.ts       权限引擎（glob 规则）
│   ├── permission-config.ts 权限配置
│   ├── plugin-config.ts    插件安装路径
│   ├── plugin-importer.ts  插件导入器
│   ├── plugin-marketplace.ts 插件市场
│   ├── session-store.ts    会话持久化
│   ├── interaction.ts      交互类型枚举
│   └── memory/             记忆子系统
│       ├── file-memory.ts / markdown-file.ts  File-backed 记忆
│       ├── sqlite-store.ts  SQLite 语义记忆
│       ├── service.ts      记忆服务（检索/注入/蒸馏）
│       ├── skill-index.ts  Skill 索引
│       ├── policy.ts       记忆策略
│       └── models.ts       记忆数据模型
└── integrations/           客户端集成
    └── terminal-cli/       Terminal TUI（状态机、渲染、trace）

数据目录

默认路径 ~/.dundun/：

~/.dundun/
├── config.json              Provider 与运行时配置
├── setting.json             默认模型、推理强度等用户设置
├── user.md                  User file-backed memory
├── tools.json               MCP 服务器连接状态
├── projects/<id>/
│   ├── sessions/            会话元数据与上下文
│   └── memory.md            Project file-backed memory
├── sqlite/                  SQLite 语义记忆 & 事件日志
├── logs/                    运行日志
└── plugins/                 本地插件安装目录

MCP 配置

在 ~/.dundun/tools.json 中配置外部 MCP 服务器：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "type": "stdio"
    },
    "exa": {
      "url": "https://api.exa.ai/mcp",
      "headers": { "Authorization": "Bearer ${EXA_API_KEY}" },
      "type": "streamableHttp"
    }
  }
}

插件

# 从插件市场安装
# （通过 Agent 对话自然触发，或直接修改 ~/.dundun/plugins/）

# 插件源支持
# - Git 仓库
# - 本地路径
# - NPM 包

脚本速查

| 命令 | 说明 | |------|------| | npm run dev | 一体化开发模式 | | npm run build | tsup 构建 → dist/ | | npm run typecheck | TypeScript 类型检查 | | npm test | Vitest 运行全部测试 | | npm link | 全局注册 dundun 命令 |

License

Apache 2.0

--- ADDITIONAL TERMS ---- For commercial use of this software (including but not limited to integration into SaaS platforms or resale as part of a product), a separate commercial license is required. Please contact [Your Email/Company] for licensing options.