在 Mac 上本地跑 openJiuwen：从 GitHub 被墙到前端依赖地狱

花了一个下午把华为系的开源 Agent 平台 openJiuwen 在本地 Mac 上跑起来了。整个过程中踩了七八个坑，从 GitHub 连不上、pnpm 依赖开盲盒到 lucide-react 删图标不通知——写下来给打算自己部署的人当攻略。

1. 为什么要折腾 openJiuwen

openJiuwen 是华为系的开源 Agent 智能体开发平台，代码版权归属 Huawei Technologies 主体，Apache 2.0 协议开源。与华为云 AgentArts（智果）同源度超过 90%。

它的核心卖点放在国内 Agent 赛道里挺能打：JiuwenSwarm 蜂群多 Agent 协同、80+ 预制插件、14 个渠道接入（含微信实验级）、MCP 服务端支持、工作流引擎基于字节跳动 FlowGram。

关键是它开源。这意味着你可以本地部署、二次开发、甚至自定义渠道接自己的场景。对于做 Agent 开发平台选型调研的人来说，这是一个值得花时间摸透的项目。

2. 第一步就跪了：GitHub 直接连不上

国内访问 GitHub 的通病——release 包几百 MB 的 arm64 tar 包根本下不来。gh CLI 也被重置，git clone 也走不通。

解法：切到 AtomGit 镜像：

几秒钟就拉下来了。国内搞开源项目，AtomGit/coding.net 这些镜像站是保命技能。

3. 后端依赖倒是顺利

项目结构是 Python FastAPI 后端 + React Vite 前端。后端用 uv 装依赖，一路绿灯：

cd agent-studio-src/backend
uv venv .venv
uv pip install -e .
cp ../.env.example .env
# 改配置：DB_TYPE=sqlite（省得装 MySQL）

启动后端：

cd ..
.venv/bin/python -m uvicorn \
  openjiuwen_studio.main:app \
  --host 0.0.0.0 --port 8000

Return 200，SQLite 自动初始化。后端顺利得让我放松了警惕——然后前端教我做人了。

4. 前端依赖地狱

项目前端是 React + Vite + TypeScript + MUI 全家桶，依赖 1800+ 个包，用 pnpm 管理。pnpm install 过了，但 vite dev server 启动后报了一系列错，每个都像开盲盒。

4.1 @assistant-ui 版本矩阵大战

ERROR: No matching export in "@assistant-ui/store" for import "tapClientResource"

@assistant-ui/store 从 0.2.20 开始才加了 tapClientResource、tapAssistantClientRef 等别名导出。项目 package.json 锁的 @assistant-ui/react@0.12.20 依赖 store ^0.2.9，npm 自动解析到了 0.2.17，不包含这些别名。

解法：手动升级 store 到 0.2.20。

pnpm add @assistant-ui/store@0.2.20

4.2 @flowgram.ai 的 tsconfig 引用崩塌

workspace 包 packages/workflow-canvas/tsconfig.json 的 extends 指向 @flowgram.ai/ts-config。pnpm 的严格模式不把 dev 依赖装到工作区根目录。

解法：修改 tsconfig 移除 extends 行——它的配置内容都已经 inline 在 compilerOptions 里了。

4.3 lucide-react 图标追杀战

Importing binding name 'Ellipsis' is not found.
Importing binding name 'LoaderCircle' is not found.

lucide-react 在 0.505.0 版本中把一些旧图标从 barrel export 里删了，按名字 import 直接报错。

解法：把 Ellipsis 换成 MoreHorizontal。LoaderCircle 需要清除 Vite 依赖缓存后重新预打包才生效。

rm -rf frontend/node_modules/.vite
# 然后重启 vite

4.4 unified 的 CJS/ESM 暗坑

TypeError: unified is not a function

来源代码里写的是 import { unified } from 'unified'。但 unified 是 CommonJS 模块，Vite 的 CJS 转换后只有 default export 没有 named export。

解法：改 4 个文件的 import：

- import { unified } from 'unified'
+ import unified from 'unified'

类似的还有缺失的 rehype-raw、remark-gfm、mermaid、@radix-ui/react-icons 等——每个都是项目 package.json 没把 transitive dependency 写全。

5. 跑起来的样子

前后端都起来之后

页面渲染正常，登录功能可用。后端日志显示 SQLite 表自动创建，API 路由全部注册。唯一的提示是 DeepSearch 组件需要额外配置——不影响主功能使用。

6. 几个真实吐槽

1. pnpm 严格模式的双刃剑 — 好处是磁盘空间省了，坏处是 workspace package 的 dev 依赖全都要手动装到根目录
2. 前端依赖版本太激进 — lucide-react 0.505、@assistant-ui 0.12.x 都在快速迭代中，barrel export 说删就删不通知
3. Docker 被墙的连锁影响 — openJiuwen 主要走 Docker 部署，但 Docker Hub 在国内不可达。如果不自己配镜像加速，arm64 tar 包跑不起来
4. 文档不全 — 快速开始文档只说"参考安装指导"，详细的部署步骤藏在 Docker 场景下，本地开发的手册要翻源码猜

7. 适合谁 / 不适合谁

适合：

• 做 Agent 平台选型调研的团队（可以先本地跑通再决定）
• 想二次开发或贡献 openJiuwen 的开发者
• 对 JiuwenSwarm 多 Agent 协同感兴趣的人

不适合：

• 想要开箱即用 Agent 的人（直接去华为云用 AgentArts SaaS 就好）
• 前端依赖版本洁癖患者（这项目会让你血压升高）