Folio
团队 Wiki 存放在 Git 仓库里，浏览器中实时协作，AI 代理通过 MCP 读写同一批页面。
- Star 数
- ★ 74
- 最近更新
- 今天
- License
- MIT
- 主语言
- TypeScript
- FA 评分
- 61/100 · 存在缺口
30 秒速览
- 运行形态
- 可在哪里用
- 兼容但需适配ChatGPT · Codex · Claude Code · Claude.ai
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 产品团队的
docs/目录：把仓库的 docs 文件夹挂成空间，技术写作者在浏览器里改，开发者用 git pull 读到带作者名的普通提交。 - 不适合
- 需要拉取请求式评审后再合并的团队（Folio 直接推送到空间跟随的分支）
- 只想用托管 SaaS、不想维护 Docker、PostgreSQL 与 Redis 的团队
- 依赖 Vercel、Netlify 等无服务器平台部署的用户
- 源码审查
- 61/100 · 存在缺口
这个 Agent 能做什么，适合哪些场景？
Folio 是 Notion / Confluence 的开源自托管替代品，核心主张是“Git 仓库就是 Wiki”：每篇文档、数据表、白板、表单和上传文件都是空间仓库里的普通文件，数据库只保存索引、权限与实时编辑状态。它提供阅读、实时编辑、源码三种编辑模式，多人同时编辑文档、数据表和 Excalidraw 白板，并支持离线写作后自动回传。AI 能力分两层：侧边栏的 Folio AI 助手（Ask 只读 / Agent 可写）和一个暴露 41 个工具的 MCP 服务器，Claude Code、Cursor、claude.ai、ChatGPT 等客户端可用个人访问令牌或 OAuth 2.1 接入，权限不超过令牌所有者。部署方式是 docker compose up -d，启动后访问 http://localhost:4870 创建管理员账号；助手使用 Cursor 密钥，可自带或由空间/实例管理员提供，不配置密钥时其余功能照常工作。
Folio 扫描 Git 仓库中的 Markdown 文件并渲染为页面，把白板保存为可编辑的 Excalidraw SVG、数据表保存为单个 .table.md 文件、表单保存为 .form.md、Claude 工件保存为 <name>.artifact/ 目录。浏览器端通过实时协作同步编辑，编辑后约 90 秒静默或点击 Sync 时提交，提交作者为最后编辑者，提交信息为 folio:update。内置助手与外部代理共用同一套工具：MCP 端点 /mcp 提供列出/搜索空间、读写页面、建表单、编辑数据表列与视图、读取大纲/标签/属性/链接、查询链接图（get_graph）、发布工件（publish_artifact）等 41 个工具。空间内的 .agent 文件夹用普通页面定义该空间的助手指令；管理员还可在 /admin/assistant 查看答案评分、问卷与“未回答问题”列表。发布功能把空间变成只读网站，支持路径、子域名或自定义域名，按需开放搜索、下载与访客版 Ask AI。
- 产品团队的
docs/目录：把仓库的 docs 文件夹挂成空间，技术写作者在浏览器里改，开发者用 git pull 读到带作者名的普通提交。 - 需要自托管知识库的公司：一台 VPS 上 docker compose 启动，用访问矩阵按空间分配管理员、编辑、查看角色，并保留审计日志。
- 用 Claude Code 或 Cursor 做自动化的团队：通过 MCP 让代理读取发布流程、写发布说明、往路线图表格插一行。
- 需要对外文档站的团队：把某个空间发布为公共网站，开启搜索、Markdown/PDF/DOCX 下载和访客 Ask AI。
- 远程或出差场景：在无网络时继续编辑已打开的页面与白板，恢复连接后自动同步到同一地址。
- 从 Confluence 迁移：把 Confluence Cloud 或本地实例的页面树导入为 Markdown，白板转为 Excalidraw 画板。
如何安装或部署这个 Agent？
需要 Docker 与 Git，其他无需安装：
git clone https://github.com/evergreen-it-dev/folio.git
cd folio
docker compose up -d首次启动会构建应用，需要几分钟。随后打开 http://localhost:4870 创建第一个账号，该账号成为实例管理员。VPS 部署可用 deploy/vps 中的一键脚本，或在上面的 compose 文件上叠加 --profile https 启用自动 HTTPS；Coolify、Railway、Render、DigitalOcean、Dokploy、CapRover、Easypanel、Portainer、Fly.io 在 deploy/ 中有现成套件。
开发模式：
cp .env.dev.example .env
docker compose -f docker-compose.dev.yml up -d
npm install
npm run dev开发模式监听 http://localhost:4871，需要 Node.js 22.12 或更新版本（助手功能需要 22.13 或更新版本）。Vercel、Netlify 等无服务器平台不受支持。
如何使用这个 Agent？
创建账号后按欢迎向导建第一篇文档、白板或数据表，或连接已有 Git 仓库。代理接入 MCP 的最简方式：
claude mcp add folio --transport http https://wiki.example.com/mcp \
--header "Authorization: Bearer folio_pat_…"个人访问令牌只有 read 或 write 范围，权限不超过其所有者。claude.ai 或 ChatGPT 可把 https://wiki.example.com/mcp 加为自定义连接器，通过 OAuth 登录并授权 read 或 read+write。任何页面（可含子页面）都能以纯 Markdown 取回：
curl https://wiki.example.com/share/<token>.mdFolio AI 使用 Cursor 密钥，按“个人密钥 → 空间密钥 → 实例密钥 → 环境变量 CURSOR_API_KEY”的顺序取第一个存在的密钥；空间管理员在空间菜单的“Folio AI key”设置空间密钥，实例管理员可关闭个人密钥。不配置任何密钥时，除助手外的功能全部可用。
这个 Agent 有哪些优点和局限？
- 内容主权明确：页面、白板、数据表、表单都是 Git 仓库中的可读文件，停用 Folio 后仍可用任意编辑器打开。
- 代理接口完整：
/mcp提供 41 个工具，内置助手与外部代理共用同一实现，Ask 模式在服务端关闭写工具而非仅隐藏。 - 文档即代码体验成熟：可只挂载
docs/子目录、不写入 id，移动页面时在同一提交内重写进出的链接，冲突可按空间查看并回退到 Git 版本。 - 权限模型细致：空间角色、页面级权限、分享链接与令牌作用域分层，实例管理员默认看不到未加入的私有空间，所有授权变更进审计日志。
- 自托管成本可控：一条 docker compose 命令启动，无遥测；分析（PostHog）与错误上报（Sentry）均为可选且默认关闭。
- 模型供应商锁定在 Cursor 单一密钥体系，其他供应商“暂不支持”，没有密钥时助手完全不可用。
- Git 工作流没有拉取请求：空间跟随单一分支并直接推送，受保护分支会导致推送失败，需要自行用
docs分支过渡。 - 运行时依赖较重：需要 PostgreSQL、Redis 和持久化卷，且明确不支持 Vercel、Netlify 等无服务器平台。
- 存在文档化的能力边界：MDX 不是页面、数据表上限 20,000 行、链接图上限 10,000 页且公共站点无图、工件不能调用 Claude 或自有 API。
- 处于早期版本：0.1.0 发布于 2026 年 9 月 29 日，0.2.0 于 10 月 14 日，公开演示数据每 24 小时重置。
这个 Agent 与同类方案有什么区别？
README 明确对标 Confluence 与 Notion：Confluence 与 Notion 把内容存数据库、以 Git 作为导出，Folio 反过来以仓库为主存储；站点还提供与 Confluence、Notion 及自托管 Wiki 的对比页面。相对 GitBook 一类工具，Folio 强调无 IDE 的浏览器编辑加实时协作；相对 Obsidian，它能直接打开 .canvas 与 .base 并以团队权限管理。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Folio 当前 | 61 · 存在缺口 | 自托管服务免费 + 模型费 | ★ 74 | 今天 | TypeScript | ChatGPT · Codex · Claude Code · Claude.ai |
| NextClaw | 58 · 缺口较多 | 桌面应用免费 + 模型费 | ★ 262 | 今天 | TypeScript | Codex · Claude Code |
| Paca | 53 · 缺口较多 | 自托管服务免费 | ★ 2k | 今天 | Go | Codex · Claude Code |
| PocketPaw | 46 · 缺口较多 | 桌面应用免费 + 模型费 | ★ 893 | 1 个月前 | Python | Codex · OpenAI API · Claude API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
SECURITY.md 明确要求 MCP 令牌默认使用 read 作用域、页面内容不得当作指令，INSTALL.md 说明 GitHub OAuth 请求 repo 全量作用域但提供细粒度令牌替代，体现最小权限意识（2）。但缺少对 Agent 写操作的用户确认机制描述，仅靠权限边界，扣至 1。数据流透明性较好：明确说明 AI 助手依赖 Cursor 订阅并把页面发送到该服务、PostHog/Sentry 默认关闭且列出所发字段（2）。敏感数据处理有 FOLIO_SECRET 加密令牌、Sentry 掩码、演示环境警告（2）。依赖安全仅见 overrides 修补 nanoid/katex 等，无审计或锁文件证据，CI 用 --no-audit，扣至 1。外部效应方面 Agent 可写 Git、发布 artifact、公开站点，虽有沙箱与 CDN 白名单，但缺少对不可逆外部动作的确认，1。回滚有 Git 历史、备份分支、文件版本恢复（2）。来源归属：提交作者记录、MIT 版权，但发布者身份未验证、Agent 生成内容归属不清，1。
文档内部一致：README、INSTALL、LIMITATIONS 对 Git-first、90 秒提交、离线范围等描述互相吻合（2）。依赖可用性：Node>=22、Postgres/Redis 明确，镜像多架构发布，但未提供锁文件证据，2。失败信息：INSTALL 有排障章节、同步状态与冲突提示、Not saved 提示（2）。
受众与场景覆盖团队 wiki、docs-as-code、公开站点、Agent 集成，非常充分（3）。能力边界在 LIMITATIONS 中极为详尽（3）。触发精度：Agent 触发/调用条件、MCP 工具边界描述零散，缺少明确的触发规则说明，1。环境适配：支持 Docker、多种 PaaS，但明确不支持 serverless，需 Postgres/Redis，2。
信息架构清晰，README 分节详尽（3）。安装说明非常完整（3）。命名稳定性：版本 0.4.0 但无 CHANGELOG，命名/接口稳定性无承诺，1。示例与 FAQ：有视频、截图、场景，但无正式 FAQ，2。已知限制极详尽（3）。许可证 MIT 完整（3）。版本与变更日志缺失（1）。维护责任：发布者未验证，SECURITY 仅承诺最新版修复，1。
输出可用性：产物为页面/表格/白板/artifact，格式可读可导出（2）。边际价值：Git 原生 + Agent 一等公民确有差异化（2）。成本效益：需 Cursor 订阅、2GB 内存、Postgres/Redis，AI 依赖单一供应商，1。
声明可追溯性：README 声明多但多为自述，缺少指向代码/测试的具体引用（1）。交叉印证：文档间互相印证但无独立第三方证据（1）。事实与推断分离：LIMITATIONS 明确区分已实现与未实现，较好（2）。
- AI 助手依赖 Cursor 订阅并将页面内容发送至该服务，需评估数据出境与供应商锁定风险。
- GitHub OAuth 请求 repo 全量作用域，建议优先使用细粒度令牌。
- 发布者身份未经验证，维护责任与更新路径不明确，生产使用前应自行审计。
- 缺少锁文件与依赖审计证据，CI 使用 --no-audit，供应链风险需自行评估。
- Agent 写操作与公开站点发布缺少明确用户确认流程，需在部署时限制权限。
常见问题
不配置 AI 密钥还能用吗？
CURSOR_API_KEY 的顺序取用。代理会不会越权改到我看不到的页面？
read 令牌不能写，管理操作对令牌完全不可用。Folio AI 的 Ask 模式在服务端关闭写工具；链接图查询也按读者权限过滤，打不开的页面不会成为节点。可以直接接进现有产品的 docs 目录吗？
docs/ 为根路径时，Folio 只在索引中保存页面 id，仅在 docs/ 下增加一个隐藏文件 .<slug>.folio；若空间覆盖整个仓库则需要向每个页面写入 id 并在根目录加文件，除非管理员勾选“Light footprint”。此外 Folio 只跟随一个分支并直接推送。公共站点会把私有内容一起暴露吗？
.agent 文件夹与模板不会被发布；然而限制不会被子页面继承，发布前需要逐页确认并锁住不应公开的页面。发布决策（可见性、下载、Ask AI、索引）存在数据库中，站点样式则存放在仓库的 .folio/ 目录。