tela 项目说明书 - Doramagic.ai

Doramagic 项目包 · 项目说明书

tela 项目

开源、可自托管的 Markdown 团队 wiki，内置 MCP 服务器，让 AI 代理像正式成员一样读写和检索你的文档。支持实时多人协作及语义与全文搜索，基于 Go + PostgreSQL + React/Milkdown 构建。

概述与系统架构

Tela 是一个面向团队与 AI Agent 协同的知识库系统，提供结构化文档（Wiki）、协同表格（Sheets）以及通过 MCP（Model Context Protocol）暴露给 AI 客户端的读写能力。项目以 Go 编写的后端服务作为单一事实源，前端采用 Astro 提供静态壳层与局部交互，营销落地页则作为独立的 Astro 构建产物独立部署，三者在仓库内通过目录...

章节 相关页面

继续阅读本节完整说明和来源证据。

1. 项目定位与核心能力

Tela 的核心定位是"把 Wiki 当作 AI Agent 可作为一等公民访问的工作空间"。除常见的人员协作能力外，系统额外提供两类差异化能力：

Sheets 协作文档：在 v0.8.0 引入，基于 Defter 网格实现的表格编辑器与阅读器，支持 CRDT 感知的撤销、CSV/XLSX 导入导出以及静态值冻结资料来源：README.md:1-40。
MCP Server for Agents：将 Wiki/Sheet 的读取、写入、搜索操作暴露为 MCP 工具，使外部 AI Agent 能够以结构化 ops 的方式参与协同资料来源：docs/architecture.md:12-58。

社区当前关注的缺口是"Agent 活动审计"——目前尚无可观察的 Agent 读写时间线（详见 issue #9），这是后续路线图中的重点方向。

2. 仓库分层与构建单元

仓库采用"多应用单一仓库（monorepo of apps）"的组织方式，每个顶层目录对应一个独立的构建与部署单元：

目录	技术栈	角色	部署目标
`backend/`	Go（module 形式）	业务 API、MCP Server、文件存储抽象	服务端进程
`frontend/`	Astro + TS	Wiki/Sheet 应用运行时	应用子域
`landing/`	Astro（独立构建）	营销品牌站，OKLCH 设计 token	域 apex

三者在 CI 中分别构建、独立部署：backend 暴露 HTTP/JSON 与 MCP 端口，frontend 通过 SSG/SSR 渲染页面并反向调用后端，landing 不耦合业务代码，仅承担品牌与 SEO 资料来源：docs/decisions.md:5-30 资料来源：README.md:42-78。

3. 后端入口与依赖基线

后端以单一 main 包形式启动，主函数位于 backend/cmd/tela/main.go，负责装配路由、MCP 端点以及存储层适配器资料来源：backend/cmd/tela/main.go:1-60。Go 模块依赖通过 backend/go.mod 锁定，运行时使用标准库的 HTTP 服务以及一个第三方 MCP 库用于将工具注册暴露给 LLM 客户端资料来源：backend/go.mod:1-25。

后端内部大致划分为：

HTTP API 层：提供 Wiki 页面与 Sheet 单元格的读写、版本管理接口。
MCP 工具层：将 API 层的能力镜像为 MCP tools，例如 edit_sheet（结构化操作）与 get_page format=values（读取计算值）资料来源：README.md:30-58。
存储抽象层：默认面向本地文件系统，预留接口以便替换为外部 KV/对象存储。

4. 前端应用与 Astro 配置

frontend/ 基于 Astro，使用其混合渲染能力：长内容页面在构建时静态化以利于 SEO，编辑、预览与协同会话则以按需 hydration 形式提供交互资料来源：frontend/astro.config.mjs:1-40。前端通过 fetch 与后端 API 对接，Sheets 视图内嵌协同光标与单元格 presence，进一步依赖 CRDT 客户端维持本地撤销栈资料来源：frontend/package.json:1-30。

应用运行时新增的"阅读模式"（issue #3）计划在 Astro 端以路由级 reader 组件实现，包含滚动监听目录、阅读进度条、阅读时长估算与字号/字体偏好等纯前端行为，不涉及后端协议变更。

5. 系统数据流概览

flowchart LR
    User[人员客户端] -->|HTTPS| FE[frontend Astro App]
    Agent[AI Agent / MCP Client] -->|MCP over stdio/HTTP| BE[backend Go Service]
    FE -->|JSON API| BE
    BE -->|read/write| Store[(本地文件系统 / 可插拔存储)]
    Landing[landing Astro Site] -.品牌与 SEO.-> User

资料来源：docs/architecture.md:60-96 资料来源：docker-compose.yml:1-30。

6. 部署拓扑

开发与生产均通过 docker-compose.yml 编排，典型拓扑包含：backend、frontend、landing 三个独立容器，由前置反向代理根据域名/路径分流——/ 落在 landing，/app/* 与 /mcp 分别落在 frontend 与 backend 资料来源：docker-compose.yml:1-45。

7. 待补齐的能力

当前架构已为后续演进留出边界：Agent 活动审计（issue #9）需要在 MCP 工具层加入结构化日志并暴露查询接口；阅读模式（issue #3）属于前端增强，不影响后端契约；SEO 完整性（issue #2）落地于 landing/ 元数据与 robots.txt/sitemap.xml/llms.txt，并对应用域施加 noindex 资料来源：docs/decisions.md:32-58。

资料来源：docs/architecture.md:60-96 资料来源：docker-compose.yml:1-30。

核心功能、编辑器与协作

Tela 是一个面向团队与 AI 代理（Agent）的协作式 wiki 平台。其核心能力围绕三类资源展开：空间（Spaces）、页面（Pages）、表格（Sheets），并通过 WebSocket 提供实时协作、通过 MCP 让 AI Agent 以一等公民身份读写内容。本页梳理后端 API 层如何把这些能力组合成统一的编辑与协作面。

章节 相关页面

继续阅读本节完整说明和来源证据。

一、核心数据模型与 API 边界

Tela 的后端按资源类型拆分 API 模块，每个文件对应一类职责：

pages.go：页面（Page）的 CRUD、版本与读取接口
spaces.go：空间（Space）的隔离、列表与成员关系
dav.go：暴露 WebDAV 端点，使外部工具可以像操作文件系统一样挂载 wiki
pages_ws.go：提供基于 WebSocket 的实时通道，支持多端同步与在线状态

资料来源：backend/internal/api/pages.go、backend/internal/api/spaces.go、backend/internal/api/dav.go、backend/internal/api/pages_ws.go

WebDAV 的存在意味着 Tela 不是封闭的 silo：传统桌面工具、备份脚本、CI 流程都可以直接消费 wiki 内容；这也是 v0.8.0 中强化 Sheet 导入导出能力所依赖的基础设施前提。

二、Sheets：可协作的网格文档

v0.8.0 引入了 Sheets 作为新的一类文档类型，区别于传统的 Markdown Page：拥有全屏的网格编辑器与只读视图，支持单元格的实时在线状态（live cell presence），使用 CRDT 感知的撤销栈以避免多人编辑时撤销互相破坏，并提供 CSV/XLSX 导入导出、冻结值（freeze-values）以及面向 Agent 作者的结构 lint 网关。

能力	Page（Markdown）	Sheet（Grid）
主编辑器	Markdown	网格编辑器
协作同步	WebSocket	WebSocket + 单元格 presence
撤销语义	文档级	CRDT-aware
导入导出	仅 Markdown	CSV / XLSX
MCP 入口	通用页面读写	专门的 `edit_sheet`
结构校验	无	structural lint gate

Sheets 的 MCP 入口被进一步拆成两个文件：mcp_sheet_edit.go 暴露结构化编辑操作（edit_sheet），mcp_sheet_authoring.go 处理 Agent 创建、初始化与 lint 网关，确保 Agent 写入的表格结构合法。

资料来源：backend/internal/api/mcp_sheet_edit.go、backend/internal/api/mcp_sheet_authoring.go

三、实时协作与 WebSocket 通道

pages_ws.go 是 Tela 协作能力的中枢。它负责接受客户端的 WebSocket 升级请求并鉴权，将编辑事件广播到同一空间内的其他在线客户端；在 Sheets 场景下额外广播单元格级 presence 信号，并与版本控制系统协作以确保冲突编辑可收敛。

由于 Sheets 与 Pages 共用同一套通道，Agent 通过 MCP 写入的变更也会以"一等队友"的形式实时推送给人类协作者。社区在 issue #9 中提出的 Agent activity audit trail 诉求，正是希望补齐这套协作通道的可观测性短板——目前 MCP 调用本身可追溯，但页面级活动流尚未聚合。

资料来源：backend/internal/api/pages_ws.go、backend/internal/api/mcp_sheet_edit.go

四、MCP：AI Agent 的一等公民接口

Tela 区别于传统 wiki 的最大差异化在于 MCP（Model Context Protocol）服务器。它允许 Agent 通过 get_page 读取页面（支持 format=values 等结构化输出，用于读取 Sheet 的计算结果），通过 edit_sheet 进行结构化表格编辑，并通过 search 等通用工具发现内容。

通过把 Sheets 的编辑拆为"结构化操作"而非"自由文本"，Tela 让 Agent 写入的内容天然适合被 lint 与回滚——mcp_sheet_authoring.go 中的 structural lint gate 即承担这一守门人角色。这意味着无论是人类还是 Agent，最终都走同一套 pages_ws.go 协作通道，编辑器层面的协作模型保持一致。

资料来源：backend/internal/api/mcp_sheet_edit.go、backend/internal/api/mcp_sheet_authoring.go、backend/internal/api/pages_ws.go

AI 与 Agent 集成（Atlas / MCP / RAG）

Tela 通过三层互补的能力把 AI 与 Agent 引入到协作 wiki 中：Atlas 是后端的生成式引擎（outline → draft → publish 三阶段流水线），负责把自然语言需求落地成可发布的页面；MCP 是面向 AI Agent 的标准协议服务器，让 Agent 像队友一样读写 wiki 与 Sheets；RAG 是连接两者的检索通道，使上述生成与操作...

章节 相关页面

继续阅读本节完整说明和来源证据。

概述

Tela 通过三层互补的能力把 AI 与 Agent 引入到协作 wiki 中：Atlas 是后端的生成式引擎（outline → draft → publish 三阶段流水线），负责把自然语言需求落地成可发布的页面；MCP 是面向 AI Agent 的标准协议服务器，让 Agent 像队友一样读写 wiki 与 Sheets；RAG 是连接两者的检索通道，使上述生成与操作都基于现有页面与向量索引的上下文。三者共同构成"人对人 + Agent 对人 / Agent 对 Agent" 的协作底座。

资料来源：backend/internal/atlas/engine/engine.go:1-1

Atlas：分阶段生成流水线

Atlas 引擎由总入口 engine.go 编排，将一次"页面生成"任务拆分成可独立执行、可恢复的阶段（stages）：

阶段	文件	职责
outline	`stage_outline.go`	从用户提示中抽取大纲（标题、子章节、关键点），作为后续阶段的骨架
draft	`stage_draft.go`	基于大纲与已有 wiki 上下文撰写完整 Markdown/Defter 内容
publish	`stage_publish.go`	执行结构性 lint、写入存储并广播到前端，必要时回滚

这种"小步、可检视"的流水线设计让 Agent 与人类都能在中途介入——比如在 draft 之后、 publish 之前进行人工审阅或修订，而无需重跑整个生成。

资料来源：backend/internal/atlas/engine/engine.go:1-1、backend/internal/atlas/engine/stage_outline.go:1-1、backend/internal/atlas/engine/stage_draft.go:1-1、backend/internal/atlas/engine/stage_publish.go:1-1

LLM 客户端与提示/上下文模型

backend/internal/atlas/llm/client.go 抽象出对模型提供方的调用（鉴权、流式、重试、token 计数），让 Atlas 不绑定具体厂商；而 core/model.go 定义统一的提示词、上下文片段与中间结构（如大纲节点、章节占位）的数据模型，供三个 stage 与 LLM client 共用，避免阶段间序列化误差。

flowchart LR
  A[用户/Agent 提示] --> B[engine.go]
  B -->|outline| S1[stage_outline.go]
  S1 -->|大纲| S2[stage_draft.go]
  S2 -->|草稿| S3[stage_publish.go]
  S3 -->|写入| Store[(Wiki 存储)]
  C[llm/client.go] -.提供模型.-> S1
  C -.提供模型.-> S2
  M[core/model.go] -.共享数据结构.-> S1
  M -.共享数据结构.-> S2
  M -.共享数据结构.-> S3

资料来源：backend/internal/atlas/llm/client.go:1-1、backend/internal/atlas/core/model.go:1-1

MCP：把 AI Agent 当一等公民

MCP（Model Context Protocol）服务器把 Tela 的核心读写动作暴露为标准工具，使外部 Agent（Claude、Cursor 等）能够直接参与编辑：

读：get_page 支持 format=values 等形式读取 Sheets 的"计算后值"，而非底层标记，让 Agent 拿到业务语义。
写：edit_sheet 暴露结构化操作（设值、清空、合并、冻结），并配合 publish 阶段的结构性 lint 校验，保证 Agent 不会写入破碎的网格。
检索：通过 RAG 通道进行语义搜索，把相关页面喂给 Agent 作为上下文。

社区讨论中提出的"Agent Activity Log"（issue #9）正是在这条通道上加挂审计层：记录哪个 Agent（由 MCP client id 标识）在何时读了哪些页面、改了哪些单元，从而为"Agent 作为一等队友"补足可观测性。

资料来源：参考 issue #9、v0.8.0 release notes 中 MCP 工具说明。

RAG：检索增强的上下文

RAG 在 Atlas 与 MCP 之间共享同一检索层：

索引：wiki 页面与 Sheets 在保存时（经 stage_publish.go）被切片、嵌入并写入向量存储。
召回：当 LLM 调用（llm/client.go）或 Agent MCP 请求触发时，按"页面/Sheet + 关键字"双路召回 top-k。
注入：召回片段经 core/model.go 的统一结构注入到 outline/draft 的提示词中，确保生成内容引用的是仓库内真实存在的资料。
v0.8.0 之后，新增的 Sheets 也走同一 RAG 通道，因此 Agent 既能读 wiki，也能读表格语义。

端到端示例（Agent 写一篇页面）

Agent 通过 MCP 调用 get_page / search 收集上下文（命中 RAG）。
调用内部 Atlas 入口（或直接提供结构化大纲）触发 stage_outline.go。
LLM（llm/client.go）结合 RAG 召回片段产出草稿 → stage_draft.go。
stage_publish.go 执行 lint 与持久化，广播到所有客户端。
Agent 的每次调用被记录，为未来的 Activity Log 提供数据源。

这种"读用 MCP、写用 Atlas、守门用 lint"的组合，让 Tela 在人类与 Agent 协作时既开放又能保证内容质量。

资料来源：backend/internal/atlas/engine/engine.go:1-1

部署、运维与扩展

tela 提供了多套面向不同部署形态的 Docker Compose 编排，使项目既能以单体方式快速启动，也能在前后端分离、内网镜像仓库、AI 增强等场景下横向扩展。deploy/ 目录是整套运维配置的入口，所有部署变体共享同一份 .env 变量定义，但通过不同的 compose 文件启用不同子集，从而覆盖从本地试验到生产级别的多种需求。

章节 相关页面

继续阅读本节完整说明和来源证据。

一、部署拓扑总览

仓库在 deploy/ 下提供了四种 compose 编排，分别对应不同的扩展粒度：

编排文件	主要场景	核心特性
`docker-compose.yml`	单机一体部署	同时拉起 backend、frontend、postgres、proxy，最小化配置
`docker-compose.split.yml`	前后端分离	拆分 backend/frontend 子域，便于独立扩缩容
`docker-compose.registry.yml`	内网镜像仓库	在私有 registry 上分发镜像，适合受限网络环境
`docker-compose.ai.yml`	AI 能力增强	引入 MCP/AI 相关服务，扩展 agent 协作能力

这套分层结构使运维人员能够以同一份环境变量文件作为"事实之源"，再根据不同环境叠加 compose override，从而降低配置漂移风险。资料来源：deploy/docker-compose.yml:1-40 deploy/docker-compose.split.yml:1-40 deploy/docker-compose.registry.yml:1-40 deploy/docker-compose.ai.yml:1-40

二、配置与变量管理

所有 compose 编排都通过 .env 文件注入运行时配置。deploy/.env.example 提供了完整的变量清单与默认值，覆盖数据库连接、TLS 域名、镜像标签、AI 服务开关等关键开关。运维人员复制该文件为 .env 后按需调整即可启动部署。

# 常见使用流程
cp deploy/.env.example deploy/.env
docker compose -f deploy/docker-compose.yml up -d

docker-compose.yml 在最顶层声明了 backend、frontend、postgres 等基础服务，并通过 env_file 统一引用 .env，确保数据库 URL、secret、端口等敏感信息不会硬编码进镜像。资料来源：deploy/.env.example:1-60 deploy/docker-compose.yml:1-60

三、反向代理与域名路由

deploy/proxy/Caddyfile 是对外暴露 HTTP/HTTPS 流量的核心组件。Caddy 自动申请并续期证书，运维无需手动管理证书生命周期。配置中以子域形式区分不同 compose 编排的入口：

单体部署：app.example.com 同时承担前端与 API
拆分部署：app.example.com（前端）与 api.example.com（后端）独立
apex 域名（landing）：通过单独的 landing 入口与 app 解耦

flowchart LR
  Client[浏览器 / MCP 客户端] --> Caddy[Caddy 反向代理]
  Caddy -->|app 子域| Frontend[Frontend 容器]
  Caddy -->|api 子域| Backend[Backend 容器]
  Backend --> DB[(PostgreSQL)]
  Backend -.可选.-> AI[AI / MCP 服务]

资料来源：deploy/proxy/Caddyfile:1-80 deploy/docker-compose.split.yml:1-40

四、扩展模式与运维建议

镜像仓库分发：当生产环境无法直接拉取公网镜像时，使用 docker-compose.registry.yml 指向内网 registry（如 registry.internal/tela/backend:<tag>），并结合 CI 在内部重新 tag。
AI 能力按需启用：docker-compose.ai.yml 引入 MCP server 与 agent 协作组件，对应社区 Issue #9 提出的 Agent 活动审计需求；启用前需确保 .env 中相关 AI 开关与凭证已就绪。
滚动升级：因 backend 与 frontend 已解耦为独立服务，可以分别替换镜像 tag 实现零停机发布；建议在 CI 中先部署 backend，等待健康检查通过后再切流量至前端。
数据持久化：postgres 数据卷显式声明在 compose 文件中，运维需定期执行 pg_dump 备份，并将卷挂载到主机或对象存储。
可观测性：当前编排内置了基础日志输出，建议在生产环境接入集中式日志与指标采集，可通过在 compose 中添加 sidecar 实现。

社区当前最关注的扩展点是 Agent 活动审计轨迹（Issue #9），未来可能在 docker-compose.ai.yml 之上叠加独立的 activity log 服务，与 MCP server 解耦以便按需启用。

资料来源：deploy/docker-compose.ai.yml:1-40 deploy/docker-compose.registry.yml:1-40 deploy/docker-compose.yml:1-60 deploy/.env.example:1-60 deploy/proxy/Caddyfile:1-80

资料来源：deploy/proxy/Caddyfile:1-80 deploy/docker-compose.split.yml:1-40

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 失败模式：security_permissions: Feature: Agent activity audit trail — who read/wrote what via MCP

Developers may expose sensitive permissions or credentials: Feature: Agent activity audit trail — who read/wrote what via MCP

medium 失败模式：installation: v0.8.0

Upgrade or migration may change expected behavior: v0.8.0

medium 来源证据：SEO completeness pass — landing meta/OG/schema + robots/sitemap/llms + app noindex

可能增加新用户试用和生产接入成本。

medium 可能修改宿主 AI 配置

安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。

Pitfall Log / 踩坑日志

项目：zcag/tela

摘要：发现 16 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 失败模式：security_permissions: Feature: Agent activity audit trail — who read/wrote what via MCP。

1. 安全/权限坑 · 失败模式：security_permissions: Feature: Agent activity audit trail — who read/wrote what via MCP

严重度：high
证据强度：source_linked
发现：Developers should check this security_permissions risk before relying on the project: Feature: Agent activity audit trail — who read/wrote what via MCP
对用户的影响：Developers may expose sensitive permissions or credentials: Feature: Agent activity audit trail — who read/wrote what via MCP
证据：failure_mode_cluster:github_issue | https://github.com/zcag/tela/issues/9 | Feature: Agent activity audit trail — who read/wrote what via MCP, failure_mode_cluster:github_issue | https://github.com/zcag/tela/issues/9 | Feature: Agent activity audit trail — who read/wrote what via MCP

2. 安装坑 · 失败模式：installation: v0.8.0

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v0.8.0
对用户的影响：Upgrade or migration may change expected behavior: v0.8.0
证据：failure_mode_cluster:github_release | https://github.com/zcag/tela/releases/tag/v0.8.0 | v0.8.0

3. 安装坑 · 来源证据：SEO completeness pass — landing meta/OG/schema + robots/sitemap/llms + app noindex

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：SEO completeness pass — landing meta/OG/schema + robots/sitemap/llms + app noindex
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/zcag/tela/issues/2 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

4. 配置坑 · 可能修改宿主 AI 配置

严重度：medium
证据强度：source_linked
发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
证据：capability.host_targets | https://github.com/zcag/tela | host_targets=mcp_host, claude, cursor

5. 配置坑 · 失败模式：configuration: Reading mode — chrome-free, typographically elevated page reader

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: Reading mode — chrome-free, typographically elevated page reader
对用户的影响：Developers may misconfigure credentials, environment, or host setup: Reading mode — chrome-free, typographically elevated page reader
证据：failure_mode_cluster:github_issue | https://github.com/zcag/tela/issues/3 | Reading mode — chrome-free, typographically elevated page reader, failure_mode_cluster:github_issue | https://github.com/zcag/tela/issues/3 | Reading mode — chrome-free, typographically elevated page reader

6. 能力坑 · 能力判断依赖假设

严重度：medium
证据强度：source_linked
发现：README/documentation is current enough for a first validation pass.
对用户的影响：假设不成立时，用户拿不到承诺的能力。
证据：capability.assumptions | https://github.com/zcag/tela | README/documentation is current enough for a first validation pass.

7. 维护坑 · 维护活跃度未知

严重度：medium
证据强度：source_linked
发现：未记录 last_activity_observed。
对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
证据：evidence.maintainer_signals | https://github.com/zcag/tela | last_activity_observed missing

严重度：medium
证据强度：source_linked
发现：no_demo
证据：downstream_validation.risk_items | https://github.com/zcag/tela | no_demo; severity=medium

9. 安全/权限坑 · 存在评分风险

严重度：medium
证据强度：source_linked
发现：no_demo
对用户的影响：风险会影响是否适合普通用户安装。
证据：risks.scoring_risks | https://github.com/zcag/tela | no_demo; severity=medium

10. 安全/权限坑 · 来源证据：Feature: Agent activity audit trail — who read/wrote what via MCP

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature: Agent activity audit trail — who read/wrote what via MCP
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/zcag/tela/issues/9 | 来源类型 github_issue 暴露的待验证使用条件。

11. 安全/权限坑 · 来源证据：Marketing landing page (standalone Astro) + apex deploy routing

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Marketing landing page (standalone Astro) + apex deploy routing
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/zcag/tela/issues/1 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

12. 安全/权限坑 · 来源证据：Reading mode — chrome-free, typographically elevated page reader

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Reading mode — chrome-free, typographically elevated page reader
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/zcag/tela/issues/3 | 来源类型 github_issue 暴露的待验证使用条件。

13. 能力坑 · 失败模式：capability: SEO completeness pass — landing meta/OG/schema + robots/sitemap/llms + app noindex

严重度：low
证据强度：source_linked
发现：Developers should check this capability risk before relying on the project: SEO completeness pass — landing meta/OG/schema + robots/sitemap/llms + app noindex
对用户的影响：Developers may hit a documented source-backed failure mode: SEO completeness pass — landing meta/OG/schema + robots/sitemap/llms + app noindex
证据：failure_mode_cluster:github_issue | https://github.com/zcag/tela/issues/2 | SEO completeness pass — landing meta/OG/schema + robots/sitemap/llms + app noindex, failure_mode_cluster:github_issue | https://github.com/zcag/tela/issues/2 | SEO completeness pass — landing meta/OG/schema + robots/sitemap/llms + app noindex

14. 能力坑 · 失败模式：conceptual: Marketing landing page (standalone Astro) + apex deploy routing

严重度：low
证据强度：source_linked
发现：Developers should check this conceptual risk before relying on the project: Marketing landing page (standalone Astro) + apex deploy routing
对用户的影响：Developers may hit a documented source-backed failure mode: Marketing landing page (standalone Astro) + apex deploy routing
证据：failure_mode_cluster:github_issue | https://github.com/zcag/tela/issues/1 | Marketing landing page (standalone Astro) + apex deploy routing, failure_mode_cluster:github_issue | https://github.com/zcag/tela/issues/1 | Marketing landing page (standalone Astro) + apex deploy routing

15. 维护坑 · issue/PR 响应质量未知

严重度：low
证据强度：source_linked
发现：issue_or_pr_quality=unknown。
对用户的影响：用户无法判断遇到问题后是否有人维护。
证据：evidence.maintainer_signals | https://github.com/zcag/tela | issue_or_pr_quality=unknown

16. 维护坑 · 发布节奏不明确

严重度：low
证据强度：source_linked
发现：release_recency=unknown。
对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
证据：evidence.maintainer_signals | https://github.com/zcag/tela | release_recency=unknown

来源：Doramagic 发现、验证与编译记录

tela 项目

概述与系统架构

1. 项目定位与核心能力

2. 仓库分层与构建单元

3. 后端入口与依赖基线

4. 前端应用与 Astro 配置

5. 系统数据流概览

6. 部署拓扑

7. 待补齐的能力

核心功能、编辑器与协作

一、核心数据模型与 API 边界

二、Sheets：可协作的网格文档

三、实时协作与 WebSocket 通道

四、MCP：AI Agent 的一等公民接口

相关社区议题

AI 与 Agent 集成（Atlas / MCP / RAG）

概述

Atlas：分阶段生成流水线

LLM 客户端与提示/上下文模型

MCP：把 AI Agent 当一等公民

RAG：检索增强的上下文

端到端示例（Agent 写一篇页面）

部署、运维与扩展

一、部署拓扑总览

二、配置与变量管理

三、反向代理与域名路由

四、扩展模式与运维建议

失败模式与踩坑日记

Pitfall Log / 踩坑日志

1. 安全/权限坑 · 失败模式：security_permissions: Feature: Agent activity audit trail — who read/wrote what via MCP

2. 安装坑 · 失败模式：installation: v0.8.0

3. 安装坑 · 来源证据：SEO completeness pass — landing meta/OG/schema + robots/sitemap/llms + app noindex

4. 配置坑 · 可能修改宿主 AI 配置

5. 配置坑 · 失败模式：configuration: Reading mode — chrome-free, typographically elevated page reader

6. 能力坑 · 能力判断依赖假设

7. 维护坑 · 维护活跃度未知

9. 安全/权限坑 · 存在评分风险

10. 安全/权限坑 · 来源证据：Feature: Agent activity audit trail — who read/wrote what via MCP

11. 安全/权限坑 · 来源证据：Marketing landing page (standalone Astro) + apex deploy routing

12. 安全/权限坑 · 来源证据：Reading mode — chrome-free, typographically elevated page reader

13. 能力坑 · 失败模式：capability: SEO completeness pass — landing meta/OG/schema + robots/sitemap/llms + app noindex

14. 能力坑 · 失败模式：conceptual: Marketing landing page (standalone Astro) + apex deploy routing

15. 维护坑 · issue/PR 响应质量未知

16. 维护坑 · 发布节奏不明确