openJiuwen 实训营 Day 1 · WorkSwarm 入门教程
从零完成 WorkSwarm 的安装、初始化、启动、模型配置，到跑通第一次真实对话。
本文所有命令与截图均在 Windows 11 + PowerShell 环境实测通过。
目录
- [0. Day 1 任务与本文范围](#0. Day 1 任务与本文范围)
- [1. WorkSwarm 是什么](#1. WorkSwarm 是什么)
- [2. 环境准备](#2. 环境准备)
- [3. 安装 WorkSwarm](#3. 安装 WorkSwarm)
- [4. 初始化工作区](#4. 初始化工作区)
- [5. 启动服务与验证](#5. 启动服务与验证)
- [6. 工作区目录结构](#6. 工作区目录结构)
- [7. 模型配置（核心）](#7. 模型配置（核心）)
- [8. 模型连通性测试](#8. 模型连通性测试)
- [9. 第一次对话](#9. 第一次对话)
- [10. 排障手册](#10. 排障手册)
- [11. 打卡提交](#11. 打卡提交)
- 附录：一页速查
0. Day 1 任务与本文范围
| 项目 | 内容 |
|---|---|
| 主题 | WorkSwarm 入门：安装配置与 AtomGit 基础操作 |
| 基础任务 | 完成 WorkSwarm 的安装和基础配置，成功启动后提交运行界面截图 |
| 进阶任务 | 完成至少一个模型的连通性测试，并使用 WorkSwarm 完成一次简单对话 |
| 本文覆盖 | 基础 + 进阶，全部步骤均实测执行并附真实截图 |
说明：实训营文档版本为
jiuwenswarm-v0.2.2，本文实测安装到的是 PyPI 上的最新版本 0.2.3，两者操作一致。
1. WorkSwarm 是什么
WorkSwarm 是基于 openJiuwen 框架构建的智能多 Agent 协作平台。启动后从左侧导航栏即可直观看到它的能力版图：
智能体 会话 团队 心跳 定时任务 技能 频道 Harness
设置：配置信息 / 浏览器服务 / 更新三种执行模式
| 模式 | 说明 | 适用场景 |
|---|---|---|
| Swarm（集群） | 多 Agent 并行协作 | 复杂任务拆解、并行调研 |
| Plan（规划） | 先规划再执行 | 目标明确、步骤可拆分 |
| Performance（性能） | 追求执行效率 | 简单直接的单步任务 |
核心能力模块
| 模块 | 作用 |
|---|---|
| Skill | 技能系统，可扩展 Agent 能力（初始化时自带 skill-creator、swarmskill-creator） |
| Heartbeat | 心跳巡检，周期性主动检查与提醒 |
| Cron | 定时任务调度 |
| Team | 多智能体团队协作 |
| Memory | 记忆系统，跨会话保留上下文 |
| Channel | 多渠道接入（Web / 飞书 / Telegram 等） |
| Harness | 执行框架与运行时编排 |
2. 环境准备
2.1 版本要求
| 依赖项 | 版本要求 | 说明 |
|---|---|---|
| 操作系统 | Windows 10/11、macOS 10.15+、Linux | 主流系统均支持 |
| Python | ≥3.11 且 ❤️.14（推荐 3.11） | 超出范围会被直接拒绝启动 |
| Node.js | ≥ 18.x | 用于前端界面 |
| Git | 最新版 | 源码安装时必需 |
2.2 环境检查
powershell
python --version
# Python 3.12.7
node --version
# v24.15.0
git --version
# git version 2.53.0.windows.2⚠️ Python 版本是最常见的坑 。必须是
>=3.11且<3.14，Python 3.14 及以上会在启动时报Python version not supported。
3. 安装 WorkSwarm
官方提供四种安装方式，按需选择：
| 方式 | 适用人群 |
|---|---|
| 方式一：桌面安装包（dmg / exe） | 想开箱即用、不想自己配 Python/Node 环境 |
| 方式二：pip 安装（本文采用） | 已有 Python 环境，最通用 |
| 方式三：源码安装（uv） | 需要改源码、跟 develop 分支 |
| 方式四：源码安装（conda） | 习惯 conda 管理环境 |
3.1 创建并激活虚拟环境（推荐）
powershell
cd e:\openjiuwen
python -m venv jiuwenswarm-env
.\jiuwenswarm-env\Scripts\activate使用虚拟环境可以避免污染全局 Python，也方便后续卸载（直接删目录即可）。
3.2 pip 安装
powershell
# 默认源
pip install jiuwenswarm
# 国内镜像（推荐，速度快很多）
pip install jiuwenswarm -i https://pypi.tuna.tsinghua.edu.cn/simple
# 或阿里源
pip install jiuwenswarm -i https://mirrors.aliyun.com/pypi/simple/安装体积较大（wheel 约 20 MB，连带依赖约数百 MB），请耐心等待。
3.3 验证安装
powershell
pip show jiuwenswarmName: jiuwenswarm
Version: 0.2.3
Summary: JiuwenSwarm4. 初始化工作区
首次启动前必须执行初始化，它会生成配置目录与默认文件。
powershell
jiuwenswarm-init实测输出（节选）：
[jiuwenswarm-init] Initializing default workspace
[jiuwenswarm-init] Workspace: C:\Users\HP\.jiuwenswarm
[jiuwenswarm-init] 增量初始化：只添加缺失文件，保留已有文件 / Incremental init: only adds missing files, preserves existing
[jiuwenswarm-init] Non-interactive mode: using default language 'zh'
已安装默认技能: skill-creator
已安装默认技能: swarmskill-creator
已更新状态文件: C:\Users\HP\.jiuwenswarm\agent\workspace\skills\skills_state.json
[jiuwenswarm-init] 初始化完成，文件变更如下 / Init complete, file changes:
新增文件 / New files: 53
+ C:\Users\HP\.jiuwenswarm\agent\workspace\AGENT.md
+ C:\Users\HP\.jiuwenswarm\agent\workspace\HEARTBEAT.md
+ C:\Users\HP\.jiuwenswarm\agent\workspace\IDENTITY.md
+ C:\Users\HP\.jiuwenswarm\agent\workspace\SOUL.md
+ C:\Users\HP\.jiuwenswarm\agent\workspace\USER.md
+ C:\Users\HP\.jiuwenswarm\agent\workspace\memory\MEMORY.md
+ C:\Users\HP\.jiuwenswarm\agent\workspace\skills\skill-creator\SKILL.md
...
[jiuwenswarm-init] initialized: C:\Users\HP\.jiuwenswarm💡 关键特性 ：
jiuwenswarm-init是增量初始化，只补齐缺失文件、不会覆盖你已有的自定义配置。所以升级版本后可以放心重复执行，不必担心配置被冲掉。
5. 启动服务与验证（基础任务）
powershell
jiuwenswarm-start启动后会拉起两个核心进程：
python -m jiuwenswarm.gateway.app_gateway # 网关，对外提供 Web 服务
python -m jiuwenswarm.server.app_agentserver # Agent 服务端5.1 验证端口
powershell
Get-NetTCPConnection -State Listen | Where-Object { $_.LocalPort -eq 5173 }LocalPort OwningProcess
--------- -------------
5173 434885.2 打开 Web 界面
浏览器访问 http://localhost:5173
左下角显示 版本 0.2.3，主界面正常渲染 ------ 基础任务完成。
5.3 进入配置页
点击左侧「配置信息」，可以看到：
页面顶部提示：共 17 个配置组 / 45 项参数，分四个标签页：
- 模型配置
- Agent 配置
- 安全配置
- 其他配置
⚠️ 重要提醒 ：文档开头就强调「安装完成并不代表直接可用，需要先完成模型配置」。此时界面右下角模型名仍是占位符
your-model-name，说明还没有可用的模型，继续下一步。
6. 工作区目录结构
初始化后所有数据都在 ~/.jiuwenswarm/（Windows 即 C:\Users\<用户名>\.jiuwenswarm\）：
~/.jiuwenswarm/
├── config/
│ ├── config.yaml # 主配置：模型、Agent、Harness、日志等（45 项参数）
│ ├── .env # 环境变量：模型密钥、第三方 API Key
│ └── builtin_rules.yaml # 内置规则
├── agent/
│ ├── workspace/ # Agent 工作区
│ │ ├── AGENT.md # Agent 人设定义
│ │ ├── IDENTITY.md # 身份信息
│ │ ├── USER.md # 用户画像
│ │ ├── SOUL.md # 性格/价值观
│ │ ├── HEARTBEAT.md # 心跳任务清单
│ │ ├── memory/MEMORY.md # 长期记忆
│ │ └── skills/ # 技能库
│ │ ├── skill-creator/
│ │ └── swarmskill-creator/
│ └── .logs/ # 运行日志
├── channels/ # 渠道（Web 前端 dist 等）
├── logs/ # 启动日志
└── .updates/ # 自动更新📌 Day 4 会深入
AGENT.md/IDENTITY.md/USER.md，这里先知道它们在哪。
7. 模型配置（核心）
这是 Day 1 最重要的部分，也是最容易踩坑的地方。
7.1 模型配置有两个来源
WorkSwarm 里"模型"出现在两个地方，它们不是同一份配置：
| 位置 | 配置来源 | 界面表现 |
|---|---|---|
| 配置页「默认模型（主对话）」 | config/config.yaml → models.defaults[0] |
配置页的模型卡片 |
| 对话页右下角模型选择器 | config/config.yaml → react.model_name，实际取 config/.env 的 MODEL_NAME |
聊天输入框旁边的模型名 |
对应配置片段：
yaml
# config.yaml ------ 配置页的模型卡片
models:
defaults:
- model_client_config:
api_base: https://api.deepseek.com
api_key: sk-******************** # 实际使用时填自己的 Key
model_name: deepseek-v4-flash
client_provider: OpenAI
timeout: 1800
verify_ssl: false
model_config_obj:
temperature: 0.95
is_default: true
yaml
# config.yaml ------ 对话页使用的模型名
react:
agent_name: main_agent
model_name: ${MODEL_NAME:-deepseek-chat} # ← 从 .env 读取
skill_mode: all
ini
# config/.env ------ 首次安装的默认占位值（需要替换）
API_BASE="https://example.com/compatible-mode/v1"
API_KEY="sk-xxxxxxxxx"
MODEL_NAME="your-model-name"
MODEL_PROVIDER=OpenAI🔥 这就是那个坑 ：即使配置页的模型卡片填好了，如果
.env里MODEL_NAME还是your-model-name，对话页依然会用这个假名字去请求，导致对话直接失败。两边都要配，且要一致。
7.2 方式一：Web 界面配置（推荐）
在「配置信息 → 模型配置 → 默认模型（主对话）」中填写：
| 字段 | 必填 | 说明 |
|---|---|---|
model_name |
✅ | 模型名称，如 deepseek-v4-flash、qwen-plus、gpt-4o |
alias |
❌ | 显示别名，如「主对话默认」 |
api_base |
✅ | 接口地址，需兼容 OpenAI 格式 |
api_key |
✅ | 密钥（本地模型随便填，如 sk-1234） |
model_provider |
✅ | 下拉选择：OpenAI / OpenRouter / DashScope / SiliconFlow / Inference / Affinity / DeepSeek |
reasoning_level |
❌ | 推理强度：使用默认值 / off / low / medium / high |
填好后记得：先修改 .env 的四个变量，再点「保存」。保存后后端会自动重启以加载最新配置。
7.3 方式二：直接改文件（适合批量/自动化）
编辑 ~/.jiuwenswarm/config/.env：
ini
API_BASE="https://api.deepseek.com"
API_KEY="sk-你的密钥"
MODEL_NAME="deepseek-v4-flash"
MODEL_PROVIDER=OpenAI如需改模型卡片本身，编辑 config/config.yaml 的 models.defaults[0]。
改完后必须重启服务：
powershell
# 停止现有进程
Get-CimInstance Win32_Process -Filter "Name='python.exe'" |
Where-Object { $_.CommandLine -match 'jiuwenswarm' } |
ForEach-Object { Stop-Process -Id $_.ProcessId -Force }
# 重新启动
jiuwenswarm-start7.4 配置生效验证
重启后打开对话页，右下角应该从 your-model-name 变成你配置的真实模型名：
8. 模型连通性测试（进阶任务）
在「配置信息 → 模型配置」中，展开模型卡片后点击 「测试」 按钮。
- ✅ 绿色对勾 = 连通成功，模型可用
- ❌ 红色叉号 = 连通失败，检查
api_base/api_key/ 网络
8.1 命令行独立验证（排障用）
如果界面测试一直失败，可以用 curl / PowerShell 绕过 WorkSwarm 直接打模型接口，快速定位是「模型问题」还是「配置问题」：
powershell
$base = "https://api.deepseek.com"
$key = "sk-你的密钥"
$model = "deepseek-v4-flash"
$body = @{
model = $model
messages = @(@{ role = 'user'; content = 'hi' })
max_tokens = 16
stream = $false
} | ConvertTo-Json -Depth 5
Invoke-RestMethod -Uri "$base/chat/completions" -Method Post `
-Headers @{ 'Authorization' = "Bearer $key"; 'Content-Type' = 'application/json' } `
-Body $body实测返回：
Hello! How接口通了，说明模型侧没问题，剩下的就是 WorkSwarm 的配置对齐问题。
9. 第一次对话（进阶任务）
回到「对话」页，在输入框发送一条消息：
你好，请用一句话自我介绍，并列出你最擅长的3个能力。按 Enter 发送（Shift+Enter 换行）。
实测回复：
你好！我是 JiuwenSwarm 创建的私人智能体，一个有温度的数字助手，会像靠谱的伙伴一样主动帮你解决问题。
我最擅长的3个能力：
- 信息搜集与整理 ------ 快速搜索、抓取网页、分析文档，把零散信息提炼成清晰结论
- 文件处理与自动化 ------ 读写编辑各类文件、执行代码与脚本、批量处理数据，帮你省下重复劳动
- 任务规划与执行 ------ 把复杂需求拆解成可执行的步骤，用待办清单全程跟踪，直到交付完整结果
有什么需要我帮忙的，尽管说～
关键信息解读
| 指标 | 数值 | 含义 |
|---|---|---|
27,728 in / 166 out / 27,894 total |
Token 消耗 | 输入含系统提示词（27.7K），实际回复 166 tokens |
上下文窗口 27.7K/1000.0K (2.8%) |
上下文占用 | 当前模型上下文上限 1000K，Day 11 会讲压缩 |
内存占用 409.2 MB |
运行时内存 | 正常范围 |
💡 首次提问消耗了 27.7K 输入 tokens，是因为 WorkSwarm 会注入 Agent 人设、技能清单、工具定义等系统提示词。这是 Agent 框架与裸调 LLM 的显著区别。
进阶任务完成 ✅
10. 排障手册
Q1: 启动时报 Python version not supported
Python 版本需 >=3.11 且 <3.14。用 python --version 确认。
Q2: 启动时报 Node.js not found
安装 Node.js 18.x 或更高版本。
Q3: Web 页面打不开（localhost:5173 无响应）
按顺序排查：
powershell
# 1. 端口是否在监听
Get-NetTCPConnection -State Listen | Where-Object { $_.LocalPort -eq 5173 }
# 2. 进程是否还活着
Get-CimInstance Win32_Process -Filter "Name='python.exe'" |
Select-Object ProcessId, CommandLine
# 3. 看日志
Get-Content "$env:USERPROFILE\.jiuwenswarm\logs\*" -Tail 50Q4: 有多个 JiuwenSwarm 实例导致端口冲突
如果机器上装过桌面版 + pip 版，可能同时存在两套进程抢 5173：
powershell
Get-CimInstance Win32_Process -Filter "Name='python.exe'" |
Where-Object { $_.CommandLine -match 'jiuwenswarm' } |
Select-Object ProcessId, CommandLine输出类似：
42768 E:\openjiuwen\jiuwenswarm-env\Scripts\python.exe -m jiuwenswarm.server.app_agentserver
39732 C:\Users\HP\...\python.exe -m jiuwenswarm.server.app_agentserver
6824 E:\openjiuwen\jiuwenswarm-env\Scripts\python.exe -m jiuwenswarm.gateway.app_gateway
31720 C:\Users\HP\...\python.exe -m jiuwenswarm.gateway.app_gateway保留一套、杀掉其余，再重启即可。
Q5: 源码安装时报 dist directory not found
源码（editable install）不会自带前端构建产物，需要手动构建：
powershell
cd jiuwenswarm\channels\web\frontend
npm install
npm run build
xcopy /E /I dist %USERPROFILE%\.jiuwenswarm\channels\web\frontend\distQ6: 模型配好了但对话报错
回到 [7.1 节](#7.1 节)：确认 .env 的 MODEL_NAME 已改成真实模型名，而不只是改了界面上的模型卡片。改完记得重启。
Q7: 如何查看 / 卸载版本
powershell
pip show jiuwenswarm # 查看
pip uninstall jiuwenswarm # 卸载11. 打卡提交
发布到 GitCode openJiuwen 组织讨论区，讨论类型选 「实训营」 ，Label 选 「openJiuwen实训营」。
markdown
标题：【openJiuwen实训营】- Day 1 - WorkSwarm入门
📅 日期：2026-09-03
📖 学习内容：WorkSwarm 入门，完成安装部署、初始化工作区、模型配置，
跑通连通性测试与第一次对话。
✅ 完成任务：基础 + 进阶
📸 截图/代码：
[环境检查]
python --version # Python 3.12.7
node --version # v24.15.0
git --version # git version 2.53.0.windows.2
[安装与初始化]
python -m venv jiuwenswarm-env
.\jiuwenswarm-env\Scripts\activate
pip install jiuwenswarm -i https://pypi.tuna.tsinghua.edu.cn/simple
jiuwenswarm-init # 生成 53 个文件，工作区 C:\Users\HP\.jiuwenswarm
jiuwenswarm-start # http://localhost:5173
[模型配置] config/.env
API_BASE="https://api.deepseek.com"
API_KEY="sk-****"
MODEL_NAME="deepseek-v4-flash"
MODEL_PROVIDER=OpenAI
[截图]
1. 启动界面 --- day1-01-startup.png
2. 配置信息页 --- day1-02-config.png
3. 连通性测试✓ --- day1-03-model-test.png
4. 第一次对话 --- day1-04-chat.png
💡 心得笔记：
1. 最大的坑：模型配置有「两个来源」------配置页的 models.defaults 和
.env 的 MODEL_NAME，两边都要改且保持一致，否则对话页仍会用占位符
your-model-name 去请求，直接失败。
2. jiuwenswarm-init 是增量初始化，只补缺失文件、不覆盖已有配置，
升级后重复执行很安全。
3. 首次对话消耗 27,728 输入 tokens，因为框架注入了 Agent 人设、
技能清单和工具定义 ------ 这体现了 Agent 框架与裸调 LLM 的本质区别。
4. 排障思路：Web 打不开先查 5173 端口 → 再查进程 → 最后查
~/.jiuwenswarm/logs/；模型不通就用 curl 直连接口，先确定
是模型问题还是配置问题。附录：一页速查
powershell
# ===== 环境 =====
python --version # 需 >=3.11 且 <3.14
node --version # 需 >=18
git --version
# ===== 安装 =====
python -m venv jiuwenswarm-env
.\jiuwenswarm-env\Scripts\activate
pip install jiuwenswarm -i https://pypi.tuna.tsinghua.edu.cn/simple
# ===== 初始化（仅首次，可重复执行）=====
jiuwenswarm-init
# ===== 启动 / 重启 =====
jiuwenswarm-start
# 访问 http://localhost:5173
# ===== 停止 =====
Get-CimInstance Win32_Process -Filter "Name='python.exe'" |
Where-Object { $_.CommandLine -match 'jiuwenswarm' } |
ForEach-Object { Stop-Process -Id $_.ProcessId -Force }
# ===== 关键路径 =====
~/.jiuwenswarm/config/config.yaml # 主配置（45 项参数）
~/.jiuwenswarm/config/.env # 模型密钥（MODEL_NAME 别忘改！）
~/.jiuwenswarm/agent/workspace/ # Agent 工作区（AGENT.md 等）
~/.jiuwenswarm/logs/ # 排障日志
# ===== 版本 =====
pip show jiuwenswarm参考链接