Effect 中文文档

Effect 中文社区

站点：https://effect-ts.cn —— Effect（TypeScript 的 effect system）官方文档全量中文翻译 （v4 + v3 共 234 页，每页标注上游基线）+ 可溯源的问答（每条引用可点回原文，无依据即拒答）

• 报错百科（真实报错的检索索引）+ 26 个用 Effect 写的开源 AI 项目推荐。

给 AI / Agent 的入口：/llms.txt · /llms-full.txt · /docs/<slug>.md · /cite/<digest>.json（引用核验记录） · MCP server（仓库内 pnpm mcp）。

[CI] [上游同步] [License: MIT]

中文世界 Effect 的第一入口：官方文档的高质量中文译站 + 内容社区 + 由 Effect 与 DDD 自建的开源标本。

• 产品与技术规划见 PLAN.md；译者规范见 docs/translation-guide.md； 上线步骤见 docs/deployment.md。
• 站点当前状态：已具备公开发布条件 —— v3 + v4 全量 234 篇中文译文（v4 110 · v3 124，覆盖率 100%）， 每篇 frontmatter 记录译者 / 审校 / 上游基线；搜索、RSS、llms.txt 全部为构建期产物，不依赖后端。
• 审校口径：当前 234 篇的 reviewers 一律为 ecn-review，含义是机器可复核 （代码块与上游逐字节一致、结构对齐、术语 0 命中、锚点可达），非人类精读，尚无人类精读署名； 展示口径见 apps/site/src/data/provenance.ts，维护者精读抽查后请追加自己的名字。

快速开始

pnpm install
# 一条命令跑起前后端（Astro 前台 :4321 + Effect API :8787）pnpm dev
# 可选：接入模型（不配也能完整运行 —— extractive 模式：检索合成 + 引用 + 拒答，零成本）cp .env.example .env                      # 填 DEEPSEEK_API_KEY=sk-...（或 LLM_BASE_URL + LLM_API_KEY）pnpm --filter @ecn/api llm:check          # 一条命令验证模型真的接上了（打印提供方/模型/超时）# 查找顺序：apps/api/.env.local → apps/api/.env → 仓库根 .env.local → 仓库根 .env# `pnpm dev` 会 watch 这几个文件：改完 Key 自动重启，不用手动重启
# 可选：本地 Postgres（默认 InMemory 模式不需要它）—— 在 .env 里设置 DATABASE_URL 后：pnpm db:up                                # docker 起 Postgres；或用本机 postgres 亦可

• 前台：http://localhost:4321（/api/* 已由 dev 代理到后端）
• 后端：http://localhost:8787
  • GET /api/health 健康检查
  • GET /api/questions 问题列表 / POST /api/questions 提问 / GET /api/questions/:id 详情
  • GET /openapi.json 自动生成的 OpenAPI（来自 @effect/schema 契约）

常用命令

pnpm typecheck            # 全仓类型检查（含 astro check）pnpm test                 # 各包测试（api: domain/application；content: 内容门禁）pnpm build                # contracts 编译 + api typecheck + astro 构建pnpm content:check        # 内容门禁：frontmatter / 路径镜像 / 术语 / 元数据残留（PR 必过）pnpm cite:check           # 引用协议门禁：摘要 / 内容指纹 / 构建产物一致（保证引用可解引用）pnpm proposals:check      # Agent 提案队列校验：治理不变量 + 复用内容门禁pnpm content:status       # 译文同步状态扫描pnpm corpus:build         # 生成 AI 知识层语料（内容改动后必跑；CI 有新鲜度门禁）pnpm mcp                  # 启动 MCP Server（stdio），把中文知识接进编码 Agentpnpm report:weekly        # 周报：AI 用量 / 可验证答率 / 缓存命中 / Agent 侧下载量（见 docs/metrics.md）pnpm traffic              # 访问报表（宿主 Caddy 日志；`pnpm traffic:prod` 从生产拉取）pnpm --filter @ecn/api llm:check   # 用真实模型跑一次问答+报错诊断（验证 DeepSeek/OpenAI 兼容配置）# 上游相关（需先 clone 官方内容仓库；路径用绝对路径）pnpm --filter @ecn/content exec tsx src/cli.ts snapshot --dir <上游docs> -o snap.jsonpnpm --filter @ecn/content exec tsx src/cli.ts diff --snapshot /abs/snap.json --docs /abs/apps/site/src/content/docspnpm --filter @ecn/content exec tsx src/cli.ts nav --dir <上游docs> -o apps/site/src/data/docs-nav.json

站点具备什么

目录速览

apps/site     Astro 前台（内容集合/MDX，React islands，SEO 优先；AskPanel 问这一页）apps/api      Effect 后端（@effect/platform HTTP，DDD 洋葱分层；含 Knowledge/Assistant 上下文）apps/mcp      中文知识层的 MCP Server（stdio，离线自包含）packages/knowledge  检索与答案合成（BM25F-lite、中文分词、话题归属、引用不变量）packages/contracts  前后端共享 Effect Schema DTO + 错误码（Schema-first）packages/content    内容管线 CLI（门禁校验 / 上游快照与 stale 比对 / 导航生成）infra/        docker-compose（本地 Postgres）docs/         译者指南、部署指南、术语黑名单PLAN.md       产品与技术规划（含 DDD 设计与路线图）

技术栈与为什么

后端 DDD 要点（详见 PLAN §5）：

• 限界上下文：Identity / Publishing / QnA / Curation / Notification（Moderation 先内嵌）
• 每个上下文是垂直切片：domain / application / infrastructure / interfaces
• 端口（仓储/ID/事件）定义在 domain，适配在 infrastructure，用 Layer 一键替换
• 领域错误用 Data.TaggedError，wire 错误用 @effect/schema 的 Schema.TaggedError（在 interfaces 层完成映射）

Layer 可移植性的活例子：同一个 QuestionRepository 端口，bootstrap/main.ts 按 DATABASE_URL 是否存在，在 InMemory 仓储与 Postgres 仓储之间切换 —— 这就是依赖倒置 + DI 容器。 测试里也用 Layer 注入确定性 ID 与内存仓储。

CI 与上游同步（“同步即信誉”自动化）

• .github/workflows/ci.yml：内容门禁 → typecheck → test → build。
• .github/workflows/upstream-sync.yml：每日定时（可手动触发）克隆官方内容仓库 Effect-TS/website 的 apps/web/src/content/docs（官方文档真正的源 —— Effect-TS/effect 仓库里并没有 docs/）→ 生成上游快照 → 比对译文落后 → 检查导航漂移 → 自动开/更新 upstream-sync 标签的 issue。

本地可复用同一套能力：packages/content 的 snapshot / diff / nav / check 子命令。

公开发布清单

• 内容：v3 + v4 全量 234 篇中文译文（v4 110 · v3 124，100%），全部 status: published 并记录译者 / 审校 / 上游基线（@bf46254）；审校为 ecn-review（机器可复核，见上「审校口径」）
• 可追溯同步：基线标注 + 每日比对 + 落后告警
• 阅读闭环：镜像侧边栏、TOC、上下页、版本切换、未翻译占位页（无死链）
• 体验：站内搜索（⌘K）、RSS、llms.txt、robots、sitemap、404、canonical/OG
• 质量门禁：内容门禁（CI）+ 全仓 typecheck/test/build
• 信任与协作：LICENSE、行为准则、Issue/PR 模板、术语表、非官方声明
• 部署：静态托管步骤 + API 容器化（docs/deployment.md）
• 待办：<Tabs> 交互切换；人类精读审校署名；社区功能（Phase 2）

里程碑

• Phase 0 · 地基：monorepo、Astro 壳、Effect/DDD 后端骨架、契约、CI
• Phase 1 · 内容为主：镜像官方结构的译站、内容管线、门禁与自动化、首屏阅读体验
• Phase 1.5 · 内容扩充：v3 + v4 全量 234/234 页（v4 110 · v3 124），覆盖率 100%
• Phase 2 · 社区功能：身份认证、问答/评论、审核、通知
• Phase 3 · 增长：案例库、活动日历、全文检索（分词）、自托管 Playground

指向

• 官方站点：https://effect.website/ · 官方内容仓库：https://github.com/Effect-TS/website
• 译者指南：docs/translation-guide.md · 部署指南：docs/deployment.md
• AI-Native 产品设计（Agent 时代的知识层）：docs/ai-native.md
• Agent 接入指南（MCP / HTTP / 静态 .md / 引用核验）：docs/agent-integration.md
• MCP 分发（各目录的实际机制、MCPB 打包、待人工步骤）：docs/mcp-distribution.md
• 给 Agent 的安装说明（Cline 一类工具会找这个文件）：llms-install.md
• 度量与周报（收什么 / 落哪 / 怎么看）：docs/metrics.md
• 生态观测台（Effect × AI Agent 调查：口径、数据集、报告）：docs/observatory/methodology.md · 线上 https://effect-ts.cn/observatory/
• 给编码 Agent 的仓库契约：AGENTS.md（架构不变量 / 必跑门禁 / 不许做的事）
• Agent 提案队列（机器写、人审）：.proposals/README.md
• 行为准则：CODE_OF_CONDUCT.md · 许可：LICENSE（内容与商标说明见 NOTICE.md）