企业官网建设流程全解析

JiuwenSwarm 二次开发指南：从源码搭建、调试到扩展自定义 Agent 的完整开发者路径

【免费下载链接】jiuwenswarmJiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.项目地址: https://gitcode.com/gh_mirrors/ji/jiuwenswarm

JiuwenSwarm 是基于 openJiuwen 构建的开源智能 AI Agent 项目，能把大语言模型的能力通过日常通讯软件直接送到你手上。想深入 JiuwenSwarm 二次开发？这篇完整开发者指南将带你走完三步核心路径：从源码快速搭建开发环境→一键调试并跑通测试→通过扩展机制自定义你的专属 Agent。无需大量编程基础，跟着步骤即可完成第一次修改与验证。

先看懂 JiuwenSwarm 源码架构

在动手前，花 5 分钟了解项目结构，能帮你快速定位"要改的地方在哪"。JiuwenSwarm 采用 Python 后端 + 前端界面的双栈架构：

项目结构详细解析见官方文档：docs/zh/developer_guide.md，智能体概念图解见：docs/zh/智能体.md。

智能体 = 角色设定 + 工具 + 技能 + 记忆 + 工作空间 + 配置。理解这个公式，你就理解了自定义 Agent 的本质——改变其中的任一项。

三步完成 JiuwenSwarm 源码搭建

环境要求一览

一键安装步骤

第 1 步：克隆源码

git clone https://gitcode.com/gh_mirrors/ji/jiuwenswarm cd jiuwenswarm

第 2 步：用 uv 创建虚拟环境并同步依赖

uv venv --python=3.11 source .venv/bin/activate # Windows 用 .venv\Scripts\activate uv sync

uv sync会根据 pyproject.toml 和uv.lock自动安装全部依赖（含 pytest 等开发依赖）。依赖声明统一在这里管理，添加新依赖用uv add <package>。

第 3 步：构建 Web 前端

cd jiuwenswarm/channels/web/frontend npm install npm run build

构建产物输出到frontend/dist，供后端静态服务。至此，开发环境就绪 ✅

快速启动：JiuwenSwarm 一键调试模式

改完代码怎么验证？官方提供了debug调试模式，把「重新构建 + 重装依赖 + 后台启动」串成一条命令：

uv run jiuwenswarm-start debug

它会自动依次执行：Web 前端npm install→npm run build→ 根目录uv sync→ 后台启动全部服务（AgentServer / Gateway / Web），日志重定向到logs/swarm-<时间戳>.log。

💡提速技巧：如果只改了 Python 代码，前端构建纯属浪费，加--skip-build复用已有产物：

uv run jiuwenswarm-start debug --skip-build

其他常用调试操作：

启动成功后，打开 Web 界面即可看到完整的工作页面——模式选择器、技能、频道、智能体管理一应俱全：

调试模式的实现源码在 jiuwenswarm/debug_launcher.py，命令入口定义见 pyproject.toml（jiuwenswarm-start/jiuwenswarm-stop/jiuwenswarm-init三个可执行入口）。

用测试用例验证你的修改

修改代码后务必跑测试。⚠️ 关键点：必须使用uv run pytest，直接运行pytest会因环境不对报ModuleNotFoundError。

# 运行全部单元测试 uv run pytest tests/unit_tests/ # 运行全部系统测试 uv run pytest tests/system_tests/ # 只跑指定测试文件（开发时最常用的姿势） uv run pytest tests/unit_tests/test_config.py

测试框架配置见 pytest.ini 与 tests/README.md。如果你要新增功能，建议同步在tests/unit_tests/下补充对应的测试文件——仓库的 贡献指南 对此有规范说明。

扩展机制：定制你自己的专属 Agent

这是 JiuwenSwarm 二次开发的灵魂。项目在 jiuwenswarm/extensions/ 内置了完整的插件式扩展框架，无需 fork 核心代码即可注入自定义能力。

扩展机制如何工作

扩展加载流程由三个模块协作完成：

• 发现：jiuwenswarm/extensions/loader.py 扫描扩展目录，寻找含extension.yaml清单的扩展包，并自动安装扩展声明的依赖；
• 注册：jiuwenswarm/extensions/registry.py 提供扩展点，目前已开放AgentServer 客户端、加解密工具、第三方 Agent（ThirdAgent）三类注册接口，还支持回调事件系统（register/trigger）挂载自定义钩子；
• 基类：jiuwenswarm/extensions/sdk/base.py 定义了BaseExtension，只需实现initialize()和shutdown()两个生命周期方法。

内置扩展 jiuwenswarm/extensions/agent_client/ 是最佳参考范例：一个extension.yaml描述元数据（id、版本、依赖、配置 schema），一个extension.py实现register_extensions(registry)函数完成注册——清单模板见 jiuwenswarm/extensions/agent_client/extension.yaml。

编写你的第一个扩展（概念流程）

1. 在扩展目录下新建extension.yaml，声明你的扩展 id、版本与dependencies；
2. 新建extension.py，写一个继承BaseExtension（或AgentServerClientExtension等专用基类）的类；
3. 在register_extensions(registry)中把实例注册进registry；
4. 通过配置项extensions.extension_dirs指定你的扩展目录，重启服务即生效。

想接入外部智能体，可参考第三方 Agent 扩展 SDK：jiuwenswarm/extensions/sdk/third_agent.py。

在 Web 端「智能体」页面可以查看任意 Agent 的工作区文件与记忆内容——你自定义的 Agent 同样会在这里呈现其工作空间。

打包分发：把你的改动交付出去

二次开发完成后，项目支持两种分发形式：

• wheel 包：在根目录执行bash scripts/build.sh，一键产出主包jiuwenswarm.whl和 TUI sidecar 包jiuwenswarm-tui.whl（构建配置分别位于 pyproject.toml 与 packages/jiuwenswarm-tui/pyproject.toml）；
• 桌面 EXE / DMG：基于 PyInstaller，Windows 用scripts\build-exe.bat，macOS 用bash scripts/build-macos.sh。

完整的打包细节（含 jiuwenbox 沙箱包单独构建）见 docs/zh/developer_guide.md 第 6 章与 docs/zh/打包exe指南.md。

常见问题排查

总结：你的 JiuwenSwarm 二次开发路线图

1. 搭环境：git clone→uv venv→uv sync→npm run build；
2. 跑起来：uv run jiuwenswarm-start debug一键调试，--skip-build提速；
3. 改代码：后端改 Python、前端改 Web、TUI 用 Bun 编译；
4. 验修改：uv run pytest跑单元测试与系统测试；
5. 做扩展：借助jiuwenswarm/extensions/扩展机制注册你的自定义 Agent；
6. 发出去：scripts/build.sh打 wheel 包或桌面安装包。

从读源码到交付定制 Agent，JiuwenSwarm 的每一步都有现成脚本和文档支撑。现在就可以打开终端，跑通你的第一条 debug 命令了 🚀

【免费下载链接】jiuwenswarmJiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.项目地址: https://gitcode.com/gh_mirrors/ji/jiuwenswarm