# https://github.com/zcag/tela 项目说明书

生成时间：2026-07-05 12:37:53 UTC

## 目录

- [概述与系统架构](#page-1)
- [核心功能、编辑器与协作](#page-2)
- [AI 与 Agent 集成（Atlas / MCP / RAG）](#page-3)
- [部署、运维与扩展](#page-4)

<a id='page-1'></a>

## 概述与系统架构

### 相关页面

相关主题：[核心功能、编辑器与协作](#page-2), [AI 与 Agent 集成（Atlas / MCP / RAG）](#page-3), [部署、运维与扩展](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/zcag/tela/blob/main/README.md)
- [docs/architecture.md](https://github.com/zcag/tela/blob/main/docs/architecture.md)
- [docs/decisions.md](https://github.com/zcag/tela/blob/main/docs/decisions.md)
- [backend/cmd/tela/main.go](https://github.com/zcag/tela/blob/main/backend/cmd/tela/main.go)
- [backend/go.mod](https://github.com/zcag/tela/blob/main/backend/go.mod)
- [frontend/package.json](https://github.com/zcag/tela/blob/main/frontend/package.json)
- [frontend/astro.config.mjs](https://github.com/zcag/tela/blob/main/frontend/astro.config.mjs)
- [landing/package.json](https://github.com/zcag/tela/blob/main/landing/package.json)
- [docker-compose.yml](https://github.com/zcag/tela/blob/main/docker-compose.yml)
</details>

# 概述与系统架构

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. 系统数据流概览

```mermaid
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]()。

---

<a id='page-2'></a>

## 核心功能、编辑器与协作

### 相关页面

相关主题：[概述与系统架构](#page-1), [AI 与 Agent 集成（Atlas / MCP / RAG）](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [backend/internal/api/pages.go](https://github.com/zcag/tela/blob/main/backend/internal/api/pages.go)
- [backend/internal/api/spaces.go](https://github.com/zcag/tela/blob/main/backend/internal/api/spaces.go)
- [backend/internal/api/dav.go](https://github.com/zcag/tela/blob/main/backend/internal/api/dav.go)
- [backend/internal/api/pages_ws.go](https://github.com/zcag/tela/blob/main/backend/internal/api/pages_ws.go)
- [backend/internal/api/mcp_sheet_edit.go](https://github.com/zcag/tela/blob/main/backend/internal/api/mcp_sheet_edit.go)
- [backend/internal/api/mcp_sheet_authoring.go](https://github.com/zcag/tela/blob/main/backend/internal/api/mcp_sheet_authoring.go)
</details>

# 核心功能、编辑器与协作

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]()

## 相关社区议题

- **issue #9（Agent activity audit trail）**：希望在现有 MCP 通道基础上增加"谁通过 MCP 读了/写了什么"的活动日志，呼应 `pages_ws.go` 与 MCP 模块共同构成的协作面，是当前最受关注的协作可观测性议题。
- **v0.8.0 release notes**：明确了 Sheets 的能力边界与 MCP 入口拆分，并确认 `get_page format=values` 与 `edit_sheet` 是 AI Agent 与 Sheet 交互的官方入口。

---

<a id='page-3'></a>

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

### 相关页面

相关主题：[概述与系统架构](#page-1), [部署、运维与扩展](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [backend/internal/atlas/engine/engine.go](https://github.com/zcag/tela/blob/main/backend/internal/atlas/engine/engine.go)
- [backend/internal/atlas/engine/stage_outline.go](https://github.com/zcag/tela/blob/main/backend/internal/atlas/engine/stage_outline.go)
- [backend/internal/atlas/engine/stage_draft.go](https://github.com/zcag/tela/blob/main/backend/internal/atlas/engine/stage_draft.go)
- [backend/internal/atlas/engine/stage_publish.go](https://github.com/zcag/tela/blob/main/backend/internal/atlas/engine/stage_publish.go)
- [backend/internal/atlas/core/model.go](https://github.com/zcag/tela/blob/main/backend/internal/atlas/core/model.go)
- [backend/internal/atlas/llm/client.go](https://github.com/zcag/tela/blob/main/backend/internal/atlas/llm/client.go)
</details>

# AI 与 Agent 集成（Atlas / MCP / 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 共用，避免阶段间序列化误差。

```mermaid
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](https://github.com/zcag/tela/issues/9)、v0.8.0 release notes 中 MCP 工具说明。

## RAG：检索增强的上下文

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

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

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

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

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

---

<a id='page-4'></a>

## 部署、运维与扩展

### 相关页面

相关主题：[概述与系统架构](#page-1), [AI 与 Agent 集成（Atlas / MCP / RAG）](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [deploy/docker-compose.yml](https://github.com/zcag/tela/blob/main/deploy/docker-compose.yml)
- [deploy/docker-compose.split.yml](https://github.com/zcag/tela/blob/main/deploy/docker-compose.split.yml)
- [deploy/docker-compose.registry.yml](https://github.com/zcag/tela/blob/main/deploy/docker-compose.registry.yml)
- [deploy/docker-compose.ai.yml](https://github.com/zcag/tela/blob/main/deploy/docker-compose.ai.yml)
- [deploy/.env.example](https://github.com/zcag/tela/blob/main/deploy/.env.example)
- [deploy/proxy/Caddyfile](https://github.com/zcag/tela/blob/main/deploy/proxy/Caddyfile)
</details>

# 部署、运维与扩展

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` 后按需调整即可启动部署。

```bash
# 常见使用流程
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 解耦

```mermaid
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]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: zcag/tela; human_manual_source: deepwiki_human_wiki -->