# Cicy-code – a local-first multi-agent coding workspace via npx

> Source: <https://github.com/cicy-ai/cicy-code>
> Published: 2026-07-18 05:50:59+00:00

`cicy-code`

是一个本地优先的多 agent 开发工作区:tmux worker + WebTTY 终端 + React 工作区 + AI 网关 + skill 市场,收在同一个仓库里,通过 npm(`npx cicy-code`

)分发单二进制。

```
npx cicy-code
```

首次运行会拉取匹配当前平台的单二进制(~30 MB),然后在本机起服务 —— 浏览器打开 [http://127.0.0.1:8008](http://127.0.0.1:8008) 即可进入工作区。从零到指挥一支 agent 团队,大约 5 分钟。

- 🚀
[快速开始](https://docs.cicy-ai.com/guide/getting-started)— 5 分钟从安装到第一支 agent 团队 - 📥
[下载与安装](https://docs.cicy-ai.com/guide/download)— 各平台安装包与 Docker 方式 - 🌐
[cicy-ai.com](https://cicy-ai.com)— 官网与云端版

```
cicy-code/
├── app/          React + Vite 前端(入口 app/src/App.tsx,主界面 Workspace.tsx)
├── api/          Go 后端 + 终端层
│   ├── mgr/      主程序与业务路由(main.go 注册路由与启动)
│   ├── server/   WebTTY HTTP/WebSocket 服务
│   ├── webtty/   WebTTY 协议
│   ├── js/       浏览器端终端资产源码(改后需 `cd api && make asset`)
│   ├── skillcmd/ `cicy-code skill <…>` 子命令(安装/卸载/列表)
│   └── resources/ 后端静态资源
├── npm/          npm 发布包与启动器(bin/cicy-code.js + publish-all.sh + install.sh)
├── scripts/      构建/发版/测试脚本(build-image.sh / fresh-instance.sh / sync-version.py)
├── workers/      Cloudflare Workers(见下「Cloudflare Workers」)
├── build.sh      标准构建入口(唯一正确的构建/测试方式)
├── dev.py        本地开发入口
├── versions.json base 镜像 / app 资产 / ttyd 版本
└── Makefile      常用别名
```

主入口:

- 本地开发
`python3 dev.py`

- 构建/测试
`./build.sh`

- 后端
`api/mgr/main.go`

,前端`app/src/App.tsx`

,主工作区`app/src/components/Workspace.tsx`

- 版本号源头
`npm/package.json`

- cicy 状态根
`~/cicy-ai`

**必须走 ./build.sh,不要直接 go build / go test。**

`build.sh`

会在编译前准备内嵌资源;裸 `go build ./mgr/`

会跳过这些步骤、和真实流水线不等价,还会在仓库根丢一个 `./mgr`

产物。`./build.sh`

依次:

- 同步版本号
- 复制
`api/resources`

→`api/mgr/resources`

- 复制
`.tmux.conf`

、`.cicy_tmux.conf`

→`api/mgr/`

- 构建
`app/dist`

(除非`SKIP_NPM=1`

) - 刷新 ttyd 内嵌资产(除非
`SKIP_TTYD_ASSET=1`

) - 复制
`app/dist`

→`api/mgr/ui`

(前端嵌进二进制) - 编译
`api/mgr`

→`api/cicy-code`

```
./build.sh build [os arch]     # 当前/指定平台构建
./build.sh all                 # 全平台
./build.sh test-go             # Go 测试(稳定入口)
./build.sh test-go ./mgr/...   # 单包测试
./build.sh docker <tag>        # runtime 镜像
./build.sh docker-base <tag>   # base 镜像
cd ~/projects/cicy-code
python3 dev.py                 # 构建 + 后台起 api/cicy-code --dev --public,tail 日志
```

默认端口:API `8008`

、Vite `8022`

。前端源码改动:`dev.py`

默认 `SKIP_NPM=1`

复用 `app/dist`

,要生效先 `cd app && npm run build`

,再 `python3 dev.py`

。

前后端分开调试:

```
cd app && npm ci && npm run dev          # 前端 HMR(:8022)
cd api && go run ./mgr/ --dev --public   # 后端把非 API 请求反代到 :8022
```

（`--dev`

仅用于本地起服务;正式产物仍必须走 `./build.sh`

。）

版本号统一由 `scripts/sync-version.py`

写入这几处:`npm/package.json`

、`app/package.json`

、`app/package-lock.json`

、`app/src/config.ts`

、`api/mgr/main.go`

、`.cicy_tmux.conf`

。

**正式发版(走 CI):**

```
python3 scripts/sync-version.py --set 2.3.NN   # 1) bump 所有版本文件
cd app && npm run build                        # 2) 前端 build(把 config.version 烘进 dist)
cd .. && git add <你的文件> && git commit ...   # 3) 提交(共享 checkout:只 add 自己的文件)
git push origin main
git tag v2.3.NN && git push origin v2.3.NN      # 4) 打 tag → 触发 .github/workflows/release.yml
```

CI 从 **tag** 构建各平台二进制、发布 npm 五连包。

**只更新本地 Mac 桌面(不发 npm,更快):** 桌面跑 `~/.local/bin/cicy-code`

(symlink → 版本化二进制)。流程见项目内约定(每次必 bump 版本 → `./build.sh build darwin amd64`

→ 拷成版本化名 → 原子换 symlink → 同步 `~/.local/bin/.cicy-localbin.json`

)。

前端改动务必在 bump 之后

`npm run build`

,否则`SKIP_NPM=1`

会复用旧 dist,`membership-version`

显示的还是旧号。

主包 `cicy-code`

只是个 launcher(几 KB),二进制按平台拆成子包,npm 按 `os`

/`cpu`

**只装匹配当前机器的那个**:

```
cicy-code                  launcher(bin/cicy-code.js → require.resolve 平台子包并 exec)
├─ cicy-code-darwin-arm64
├─ cicy-code-darwin-x64
├─ cicy-code-linux-x64
└─ cicy-code-linux-arm64
```

安装:

```
npm install -g cicy-code        # 海外
npm install -g cicy-code --registry=https://registry.npmmirror.com   # 国内(缓存二进制,不走 GitHub)
npx cicy-code                   # 临时跑一次
```

`npm/publish-all.sh <npm-version> [gh-tag]`

从对应 GitHub release 资产打包发布 4 个平台子包 + 主包(子包先发、主包后发,保证 optionalDependencies 可解析)。CI 已自动化这条链。

**后端 api/mgr** —

`main.go`

注册全部路由与启动。关键文件:`setup.go`

:环境检查、内置 worker、开机 seed(dotfiles / memory 模板 / 内置 skill)`tmux.go`

:pane 生命周期、tmux send、agent 启动脚本(boot.sh)、fork`chatbus.go`

:聊天 WebSocket、poll、client 广播`agent_memory_template.go`

:agent 记忆模板组装(见下)`newtab.go`

:`/newtab`

单源浏览器起始页(chrome + electron tab 共用)`skills.go`

/`skill_market*.go`

:skill 市场 API(`/api/skill-market/*`

)`ai_gateway_*.go`

/`providers*.go`

:各 provider 适配与 AI 网关`runtime.go`

/`machines.go`

:managed runtime、机器表`ui.go`

:内嵌 UI 或 Vite 反代;`paths.go`

:状态根与路径常量

**终端层** — `api/server`

(HTTP/WS)、`api/webtty`

(协议)、`api/js`

(浏览器端资产,改后 `make asset`

)。

**前端 app** —

`App.tsx`

路由;`Workspace.tsx`

主工作区(agent stack / 团队面板 / skill 市场 / Todo / WS 状态);`services/api.ts`

统一 API 客户端;`config.ts`

版本号与 API base。**Cloudflare Workers workers/**(独立

`wrangler deploy`

,与主程序解耦):`oauth-flow`

→`oauth-flow.cicy-ai.com`

:Google OAuth 授权码**无状态中继**(只暂存 code,TTL 10min、一次性;永不接触 client_secret / token)`skills-registry`

→`skills.cicy-ai.com`

:**public skill 注册表 API**(`/v1/skills*`

、`/v1/admin/publish`

),`skill install`

打的就是它

- 装/卸/列表:
`cicy-code skill install|remove|installed <name>`

(`api/skillcmd/`

) - public 注册表:
`workers/skills-registry`

(`skills.cicy-ai.com`

),public skill 源码在独立仓库`cicy-skills`

,tag 触发`/v1/admin/publish`

- 规范:三类 skill(public / private / team)的落盘位置与发布约定见
`cicy-skill-spec`

- 前端市场入口
`/api/skill-market/*`

,红点提示 public skill 有更新

cicy 状态根 `~/cicy-ai`

:

`~/cicy-ai/global.json`

:全局配置 + api_token`~/cicy-ai/db/`

:敏感配置(`email.json`

、`cf.json`

、`frps.toml`

、`mihomo.yaml`

等,chmod 600)`~/cicy-ai/memory/`

:记忆模板(`global.md`

、`projects/`

、`agents/`

)`~/cicy-ai/workers/`

:各 agent workspace`~/cicy-ai/skills/`

:已装 skill(public 扁平 /`private/`

/`team/<team>/`

)`~/cicy-ai/assets/`

:上传资源目录

Apache-2.0