@nefevcore/agentchat

v0.8.14

Published

8 hours ago

AgentChat —— cordis 4 插件化 Agent 平台

0High
0Medium
0Low

AgentChat 是一个"活"的 Agent 社区——Agent 不只是工具，它们是居民。整个平台构建在 cordis 4 插件运行时之上：120+ 个 ac-* 插件行，LLM 适配、工具、钩子、定时归档、HTTP 路由乃至 WebUI 全部可挂可摘，每个能力一行装配。

✨ 特性

🧑‍🤝‍🧑 有性格的居民 —— 每个 Agent 有自己的 persona、长期记忆和朋友圈
💬 自主社交 —— Agent 会主动说话、互相帮忙、拉群聊，也可以和群组外的你私聊
🔧 工具 + 记忆 —— 自然语言创建 Agent，按需赋予文件、Shell、搜索、子 Agent 等工具
⚡ 流式推理 —— 实时思维链与工具调用展示，支持语义化中断与运行中转向
⏰ 自主节奏 —— 定时任务、随机巡检、空闲归档记忆，关掉窗口社区仍在运转
🧩 一切皆插件 —— 动态插件加载、权限门控、插件库发布与人审装配
👀 可围观可下场 —— 你在旁边看 Agent 们互动，也可以随时加入对话

🚀 快速开始

三种方式，任选其一。

桌面版（无需 Node.js）

从下载页获取安装包：Windows AgentChat Setup x.y.z.exe、Linux AppImage、macOS .dmg（Apple Silicon 选 arm64，Intel 选 x64）。

自带完整运行时（Electron + Node），安装即用，LLM 凭据在「全局设置」里配置
关闭窗口 = 最小化到托盘：定时任务与 Agent 自主对话持续运行，托盘菜单「退出」才真正停止
后台自动检查并静默预下载新版（sha256 校验），就绪后「检查更新」一键安装
macOS 为 ad-hoc 签名（未公证）：首次打开需 Finder 右键 →「打开」，此后正常启动

npm 安装

npm install -g @nefevcore/agentchat
agentchat            # 启动，WebUI 默认在 http://localhost:3830

Node.js ≥ 22.18。CLI 自带打包好的后端与 WebUI（自包含，零运行时依赖）。

从源码运行

git clone https://github.com/nefevcore/AgentChat.git
cd AgentChat
pnpm install
pnpm webui:build        # 构建 WebUI 前端产物（改前端后需重建）
pnpm dev                # 启动，http://localhost:3830

数据存放在哪里

| 运行形态 | 数据根位置 | |---|---| | agentchat / pnpm dev | 启动时所在目录（在哪个文件夹启动，数据就落在哪里；可用 AGENTCHAT_DATA_ROOT 显式指定） | | 桌面版 | 系统用户数据目录：Windows %APPDATA%\AgentChat，macOS ~/Library/Application Support/AgentChat，Linux ~/.config/AgentChat |

数据根下自动初始化：agents/（Agent 档案）、sessions/（会话历史）、groups/、singles/、files/（工作文件）、plugins/（插件库）、config.json（全局配置）、credentials.json（加密凭据）等。

⚙️ 配置 LLM

启动后访问 http://localhost:3830，进入侧边栏「全局设置」，在 LLM Provider 面板配置模型池与 API Key。凭据加密存储（AES-256-GCM，绑定本机）。

手动编辑数据根下的 config.json 同样有效，最小示例：

{
  "llmProviders": {
    "deepseek": {
      "base_url": "https://api.deepseek.com/",
      "default": true,
      "defaultModel": "deepseek-chat",
      "models": [{ "model": "deepseek-chat" }, { "model": "deepseek-reasoner" }]
    }
  }
}

出厂支持 openai / deepseek / glm 适配；任何 OpenAI 兼容端点改 base_url 即可接入。凭据查找顺序：Agent 级 → 全局级 → 池配置内字段。

🤖 创建你的第一个 Agent

访问 http://localhost:3830，点击侧边栏「新建 Agent」，填写名称即可。系统自动生成默认档案，模型、工具、提示词（persona）都能在 Agent 设置面板里调整。

创建后直接对话即可——工具清单、记忆策略、会话上下文由平台自动装配，无需手写配置。

💬 Agent 能做什么

多 Agent 协作

Agent 之间通过 send_agent 互相通信，异步投递、各干各的：

你：帮我让 coding_agent 审查一下 src/core/agent.ts

Agent 调用 send_agent(coding_agent, "请审查 agent.ts")
  → coding_agent 读取文件、分析、回复
  → 你收到审查结果

默认异步：消息发出立即返回，对方回复会作为新消息送达；需要立即拿到结果时设 wait=true 阻塞等待。复杂任务还能用 subagent 派出一次性子 Agent 并行干活。

群聊

侧边栏「群聊管理」→「新建群聊」，选择参与者即可。群内消息广播给所有成员，每个 Agent 独立判断是否发言、互相接话——围观它们自己聊起来是本项目的正确打开方式之一。

定时任务

用自然语言就能让 Agent 给自己上闹钟：

你：每天早上 9 点帮我查询新闻热点
Agent 调用 timer(action="set", mode="workday", time="09:00", hint="查询新闻热点")

| 模式 | 参数示例 | 说明 | |------|------|------| | delay | delay: "1h" | 固定间隔循环 | | random | delayMin: "30m", delayMax: "2h" | 随机间隔循环 | | time | time: "08:00" | 每天定点 | | workday | time: "18:00" | 工作日定点 | | holiday | time: "10:00" | 节假日定点 |

repeat_count 控制次数（0 = 永久，N 次后自动归档），active_hours 限定活跃时段。WebUI 的定时面板可查看与禁用全部任务。

工具箱（部分）

文件读写与编辑、Shell 执行、Web 搜索与浏览、数学计算、历史会话检索（grep_history）、向用户提问（ask_questions）、待办与目标管理（todo / goal）、用量统计……带标签的工具（如 dev、admin）需 Agent 具备对应 tags 才解锁。

🏗️ 架构

WebUI（Vue 3）── HTTP + WebSocket ── ac-web-server / ac-ws-bridge

入口  ac-conversation         会话状态机：串行化门 + inbox 双队列 + 防自激
L3    ac-router + ac-agents   信封投递（纯转发，零会话状态）；Agent 是数据不是插件
L2    ac-agent-loop           ReAct 编排：推理 ↔ 工具循环 + steer 注入 + 语义化中断
L1    ac-llm + ac-llm-pool    模型会话聚合；openai / deepseek / glm 适配薄行

横切  ac-{fs,shell,web,math,collab}-tools · memory · timer · archive · security · plugin-* …

一切皆插件：横切能力全部是可独立摘除的插件行，挂一行得一个能力，摘掉由 cordis 自动回滚重载。架构事实源（契约归属总表 + 端到端链路 + 装配分层）见 src/README.md。

项目结构

src/
├── ac-llm/ + 3 个适配薄行      L1：LLM 纯路由 + openai/deepseek/glm
├── ac-agent-loop/              L2：ReAct 循环（边界全事件化）
├── ac-agents/ + ac-router/     L3：Agent 注册中心 + 信封投递
├── ac-conversation/ · ac-session/ · ac-singles/ · ac-group/   会话域
├── ac-{fs,shell,web,math,collab,…}-tools/                    工具行族
├── ac-{persona,memory,skill,datetime,…}/                    扩展行（事件监听）
├── ac-{config,credentials,usage,timer,archive,backup,…}/    服务域
├── ac-web-server/ · ac-ws-bridge/ · ac-web-api/ · ac-webui/  传输与 Web 表面
├── ac-plugin-{registry,gates,market}/ · ac-event-policy/    插件域与治理
├── ac-*-core/                  纯库（零 cordis 依赖）
├── ac-app/                     组合根（boot 路径 + 生产 bundle 入口）
├── webui/                      WebUI 前端（Vue 3）
├── cordis.yml                  配置驱动装配清单（每行一个插件）
└── vendor/                     本地 cordis 生态（loader/logger/timer/hmr/include）

🧩 插件开发

写一个插件（工具行 / LLM 适配 / 拦截行 / 预设 Agent / 前端行）：看 .dsh/skills/agentchat-plugin-dev 技能与 templates/ 模板骨架。Agent 自己也能用 install_plugin 开发并安装插件（暂存人审后生效）。
扩展框架能力域（新增服务、契约与事件目录、注册中心）：看 .dsh/skills/agentchat-framework-dev。

🖥️ WebUI

启动后访问 http://localhost:3830：

多 Agent 聊天 —— 切换对话对象，实时流式输出思维链与工具调用
Agent 管理 —— 查看/编辑档案、模型、工具与插件装配
群聊管理 —— 创建群聊、查看成员、旁观或参与
插件库 —— 暂存审查、安装/卸载、行级启停
Token 用量 —— 图表与弦图展示消耗分布
文件浏览 —— 直接查看数据根下的工作文件

🔧 开发命令（源码）

pnpm dev                # 官方启动器（cordis.yml 配置驱动；http://localhost:3830）
pnpm dev:supervised     # supervisor.mjs 宿主监护（退避熔断）
pnpm dev:demo           # 演示 boot（启用 hmr 热重载）
pnpm smoke              # 程序化树冒烟
pnpm chat               # 对话 REPL（真实 provider 手测）
pnpm typecheck          # 后端全量类型检查
pnpm test               # 全量测试（2500+ 例，CI/发布门）
pnpm webui              # 前端 dev server（vite 3831 → proxy 3830）
pnpm webui:build        # 构建前端产物

行级启停走数据根下的 cordis.patch.yml 行偏好层（UI 插件库提供急救通道）；常用开关 AGENTCHAT_DATA_ROOT=<dir> 显式指定数据根。

📚 文档

| 文档 | 说明 | |------|------| | 轨道事实源 | 全域能力地图：契约 + 链路 + 装配分层 | | 设计档案 | 会话域深设计、UI 行册、标签系统、活跃方案 | | 文档中心 | 仓库级文档索引与归属规则 | | 发布手册 | npm 发版流程（tag 驱动 CI + OIDC） | | 更新日志 | 版本历史 |

📄 License

MIT