【免费下载链接】DeftSelf-hostable AGPL workspace where humans and AI agents share chat, tasks, knowledge, approvals, and MCP context.项目地址https://gitcode.com/gh_mirrors/deft9/Deft点击查看免费下载Deft 是一个可自托管self-hostable的开源工作区让人类与 AI Agent 在同一个空间里共享聊天、任务、知识、审批与 MCP 上下文。本文将从 monorepo 目录结构切入完整拆解它的技术栈前端用 Next.js 16 React 19API 层用 Hono 构建在 Node.js 之上数据层则由 PostgreSQL 16 pgvector Drizzle ORM 承担三者通过 pnpm workspaces 组织成一个高内聚的 monorepo。即使你只是新手也能看懂这套架构为什么这样设计。一、monorepo 总体结构一眼看懂目录地图Deft 用 pnpm-workspace.yaml 把整个仓库划分为两大区域apps/*可部署应用和packages/*共享库。这种应用与库分离的 monorepo 结构是理解整个项目的起点deft/ |-- apps/ | |-- web/ Next.js 16, React 19, Tailwind CSS, TipTap | -- api/ Hono, Socket.io, PostgreSQL job workers, agent and MCP runtime |-- packages/ | |-- db/ PostgreSQL, pgvector, Drizzle schema and migrations | |-- mcp/ Shared MCP protocol support | -- shared/ Shared types, schemas, and constants | -- app-kit/ 第三方 App 作者工具包SDK |-- docker-compose.yml -- pnpm-workspace.yaml 官方技术栈对照表可以直接查看 README.md它用一张表概括了每一层的选择。为什么选 pnpm workspaces单一依赖树pnpm-workspace.yaml里用overrides统一锁定hono、ws、socket.io-parser等关键版本避免子包版本漂移按需分发命令根 package.json 提供pnpm dev并行启动前后端、pnpm db:migrate、pnpm typecheck等一键脚本新手不用记每个子包的启动方式边界可测试仓库内置pnpm check:app-boundary边界检查脚本见 scripts/check-app-boundary.mjs在 CI 中强制各包不越权引用保证 monorepo 不会退化成大泥球。二、前端层Next.js 16 React 19 的 web 应用apps/web是用户直接看到的产品界面核心技术是Next.js 16App Router React 19 Tailwind CSS v4 TipTap 富文本编辑器。路由即功能模块Next.js 的app/目录直接映射产品功能浏览 apps/web/src/app/(app)//) 就能看到完整功能清单路由目录对应功能chat/多 Space 群聊人类与 Agent 同屏协作tasks/任务表格、看板、时间线多视图knowledge/知识 Wiki含图谱视图与语义问答calendar/、notes/、inbox/日历、笔记、收件箱approvals/Agent 操作的人工审批中心apps/、skills/、modules/App 市场、技能与模块管理这种目录 功能的组织方式让新手顺着文件夹就能理解产品全貌。组件层则集中在 apps/web/src/components/如space-chat.tsx聊天主界面、task-board.tsx看板、knowledge-panel.tsx等职责清晰、就近复用。前端配置里的工程细节apps/web/next.config.ts 值得新手一读它展示了生产级 Next.js 项目的三个典型实践安全响应头为全站配置 CSP、X-Frame-Options: DENY、HSTS并对 App 体验页单独下发更严格的策略环境注入手动加载仓库根.env让NEXT_PUBLIC_*变量在构建期正确内联到客户端 bundlecompose 文件中同样有对应args跨包编译transpilePackages: [deft/shared]让共享包直接以 TS 源码参与编译省去发布构建链。三、API 层Hono Socket.io 的轻量后端apps/api是整个系统的心脏与常见的Next.js 全栈不同Deft 把 API 拆成了独立的 Hono 服务默认监听 3001 端口。启动链路一目了然入口 apps/api/src/server.ts调用hono/node-server的serve()绑定端口启动后台 workers、job 调度器并挂载 Socket.io应用定义 apps/api/src/index.ts这里只组装不监听用 Hono 实例依次挂载 cors、logger、secureHeaders 中间件和近百个路由模块方便测试直接 import 而不占用端口——这是一个很值得学习的解耦手法路由按领域切分apps/api/src/routes/ 下有auth.ts、tasks.ts、agent.ts、knowledge.ts、mcp-server.ts、app-runs.ts等近百个文件一个文件对应一个资源域检索极快。中间件与后台任务中间件apps/api/src/middleware/auth.tsJWT 鉴权、rate-limit.ts限流、privacy-guard.ts隐私边界构成请求的第一道防线作业队列Deft 做了一个反直觉但非常务实的决策——不用 Redis直接用 PostgreSQL 的job_queue表做后台任务队列。决策记录见 docs/decisions/2026-08-17-postgres-job-queue.md自托管场景下少一个基础设施组件就少一份部署与运维成本应用状态和作业状态也同库管理。worker 实现位于 apps/api/src/workers/实时通信Socket.io 以进程内单实例模式运行负责聊天、审批等实时推送与 Next.js 前端通过socket.io-client对接。四、数据层PostgreSQL 16 pgvector Drizzlepackages/db是唯一持有数据库真相的包其他包都通过workspace:*引用它。pgvector让语义住进关系库Deft 的 wiki 页面和任务标题都带vector(1536)的 embedding 列schema 定义见 packages/db/src/schema.ts迁移 SQL 如 packages/db/drizzle/0033_tasks_embedding.sql用于知识检索和语义搜索启动时用 packages/db/scripts/ensure-pgvector.ts 幂等地CREATE EXTENSION IF NOT EXISTS vectordocker-compose.yml 直接选用pgvector/pgvector:pg16官方镜像并注释了原因普通postgres:16-alpine缺少 vector 扩展会导致db:push失败端口发布被刻意绑定到127.0.0.1注释中还记录了一次公网暴露事故教训——自托管项目把安全写进默认配置值得借鉴。Drizzle ORM类型安全的 schema 管理数据库连接封装在 packages/db/src/index.tspg.Pooldrizzle(pool, { schema })一行导出既带运行时实例又带完整 TypeScript 类型。schema 变更走drizzle-kit generate生成 SQL 迁移packages/db/drizzle/下已积累 80 个版本化迁移文件配套upgrades/目录支持从v0.2.0-preview.1基线起的版本化升级。五、共享包与部署monorepo 的粘合剂deft/sharedpackages/shared/src/前后端共用的 Zod schemas、能力声明、富文本常量是消灭前后端字段不一致问题的关键deft/mcppackages/mcp/src/MCP 协议客户端与传输安全策略让 Deft 既能被 Claude、ChatGPT 等外部 Agent 接入也能作为宿主管理 MCP 连接deft/app-kitpackages/app-kit/src/给第三方开发者写 Deft App 的 SDK包含资源同步、私域状态、HMAC 签名等 70 模块社区示例见 examples/connected-resource-campaigns-app/。部署侧docker-compose.yml 定义了deft前后端单容器、postgrespgvector 镜像两个核心服务外加init/upgrade/doctor/smoke等 tools profile 运维服务自托管新手可配合 docs/getting-started.md 与 docs/self-hosting.md 完成首次部署。六、架构速览一张表总结技术选型层技术选型仓库位置Web 前端Next.js 16 / React 19 / Tailwind v4 / TipTapapps/web/API 服务Hono Socket.io PostgreSQL job workersapps/api/数据层PostgreSQL 16 pgvector Drizzle ORMpackages/db/MCP 协议共享 MCP 客户端与传输安全packages/mcp/共享类型Zod schemas 与常量packages/shared/后台任务PostgreSQLjob_queue无 Redisdocs/decisions/2026-08-17-postgres-job-queue.md实时通信Socket.io 进程内单实例apps/api/src/socket.tsMonorepopnpm workspacespnpm-workspace.yaml七、写在最后这套架构给新手的 3 个启示按应用 / 库切分 monorepo再叠加边界检查脚本规模上去后依然好维护自托管优先意味着基础设施做减法——用 Postgres 同时承载业务数据、向量检索和任务队列部署拓扑因此简单到一个容器 一个数据库入口与定义分离server.ts只监听、index.ts只组装是提升可测试性的低成本手段几乎零成本就能照搬。Deft 目前处于 alpha 阶段AGPL-3.0 协议面向受控试点架构仍在快速演进。想动手体验的话可以从git clone https://gitcode.com/gh_mirrors/deft9/Deft克隆仓库然后阅读 docs/getting-started.md 搭建你的第一个工作区。赞分享【免费下载链接】DeftSelf-hostable AGPL workspace where humans and AI agents share chat, tasks, knowledge, approvals, and MCP context.项目地址https://gitcode.com/gh_mirrors/deft9/Deft点击查看免费下载相关推荐拆解Spell UI文档站架构Next.js 16 MDX Content Collections深度解析拆解Spell UI文档站架构Next.js 16 MDX Content Collections深度解析 本文拆解 Spell UI 一个可复制粘Swiparr项目架构深度解析Next.js 16 React 19 Drizzle源码结构全览Swiparr项目架构深度解析Next.js 16 React 19 Drizzle源码结构全览 Swiparr 是一款「电影界的 Tinder」——Local Studio 架构深度剖析Next.js 16 Electron 与 Bun/Hono 双栈如何协同Local Studio 架构深度剖析Next.js 16 Electron 与 Bun/Hono 双栈如何协同 Local Studio 是一个面向本地上一篇CnC_Remastered_Collection中的界面布局系统CONTROL.H与窗口管理下一篇DBeaver自定义函数文档模板创建标准化函数文档的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考