# encore - Doramagic AI Context Pack

> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。

## 充分原则

- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。
- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。

## 给宿主 AI 的使用方式

你正在读取 Doramagic 为 encore 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。

## Claim 消费规则

- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。
- **事实最低状态**：`supported`
- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。
- `weak`：只能作为低置信度线索，必须要求用户继续核实。
- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。
- `unverified`：不得作为事实使用，应明确说证据不足。
- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。

## 它最适合谁

- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86

## 它能做什么

- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`.devcontainer/scripts/install.sh`, `docs/go/ai-integration.md`, `docs/go/primitives/object-storage.md`, `docs/go/self-host/deploy-to-digital-ocean-wip.md` 等 Claim：`clm_0001` supported 0.86

## 怎么开始

- `curl -X PUT --data-binary @/home/me/dog-wizard.jpeg "https://storage.googleapis.com/profile-pictures/my-user-id/?x-goog-signature=b7a1<...>"` 证据：`docs/go/primitives/object-storage.md` Claim：`clm_0003` unverified 0.25
- `curl https://myapp.ondigitalocean.app/hello/world` 证据：`docs/go/self-host/deploy-to-digital-ocean-wip.md` Claim：`clm_0004` unverified 0.25
- `curl https://myapp.ondigitalocean.app/names/1` 证据：`docs/go/self-host/deploy-to-digital-ocean-wip.md` Claim：`clm_0005` unverified 0.25
- `curl -d '{` 证据：`docs/go/tutorials/incident-management-tool.md` Claim：`clm_0006` unverified 0.25, `clm_0012` unverified 0.25
- `curl -X PUT "http://localhost:4000/incidents/1/acknowledge"` 证据：`docs/go/tutorials/incident-management-tool.md` Claim：`clm_0007` unverified 0.25
- `npx add-skill encoredev/skills` 证据：`docs/go/ai-integration.md` Claim：`clm_0008` supported 0.86, `clm_0009` supported 0.86, `clm_0010` supported 0.86
- `npx add-skill encoredev/skills --list` 证据：`docs/go/ai-integration.md` Claim：`clm_0009` supported 0.86
- `npx add-skill encoredev/skills -a cursor -a claude-code` 证据：`docs/go/ai-integration.md` Claim：`clm_0010` supported 0.86
- `claude mcp add --transport stdio encore-local -- encore mcp run --app=your-app-id` 证据：`docs/go/ai-integration.md` Claim：`clm_0011` supported 0.86
- `curl -d "client_id=${OAUTH_CLIENT_ID}" -d "client_secret=${OAUTH_CLIENT_SECRET}" \` 证据：`docs/platform/integrations/oauth-clients.md` Claim：`clm_0012` unverified 0.25

## 继续前判断卡

- **当前建议**：先做角色匹配试用
- **为什么**：这个项目更像角色库，核心风险是选错角色或把角色文案当执行能力；先用 Prompt Preview 试角色匹配，再决定是否沙盒导入。

### 30 秒判断

- **现在怎么做**：先做角色匹配试用
- **最小安全下一步**：先用 Prompt Preview 试角色匹配；满意后再隔离导入
- **先别相信**：角色质量和任务匹配不能直接相信。
- **继续会触碰**：角色选择偏差、命令执行、本地环境或项目文件

### 现在可以相信

- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86
- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.devcontainer/scripts/install.sh`, `docs/go/ai-integration.md`, `docs/go/primitives/object-storage.md`, `docs/go/self-host/deploy-to-digital-ocean-wip.md` 等 Claim：`clm_0001` supported 0.86
- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`docs/go/ai-integration.md` Claim：`clm_0008` supported 0.86, `clm_0009` supported 0.86, `clm_0010` supported 0.86

### 现在还不能相信

- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。
- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。
- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。
- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。
- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。
- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。
- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。
- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。

### 继续会触碰什么

- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。
- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`.devcontainer/scripts/install.sh`, `docs/go/ai-integration.md`, `docs/go/primitives/object-storage.md`, `docs/go/self-host/deploy-to-digital-ocean-wip.md` 等
- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`.devcontainer/scripts/install.sh`, `docs/go/ai-integration.md`, `docs/go/primitives/object-storage.md`, `docs/go/self-host/deploy-to-digital-ocean-wip.md` 等
- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。

### 最小安全下一步

- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）
- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）
- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）

### 退出方式

- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。
- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。
- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。
- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。

## 哪些只能预览

- 解释项目适合谁和能做什么
- 基于项目文档演示典型对话流程
- 帮助用户判断是否值得安装或继续研究

## 哪些必须安装后验证

- 真实安装 Skill、插件或 CLI
- 执行脚本、修改本地文件或访问外部服务
- 验证真实输出质量、性能和兼容性

## 边界与风险判断卡

- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0025` inferred 0.45
- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`.devcontainer/scripts/install.sh`, `docs/go/ai-integration.md`, `docs/go/primitives/object-storage.md`, `docs/go/self-host/deploy-to-digital-ocean-wip.md` 等 Claim：`clm_0026` supported 0.86
- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。
- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。
- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。

## 开工前工作上下文

### 加载顺序

- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。
- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。
- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。
- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。
- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。

### 任务路由

- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`.devcontainer/scripts/install.sh`, `docs/go/ai-integration.md`, `docs/go/primitives/object-storage.md`, `docs/go/self-host/deploy-to-digital-ocean-wip.md` 等 Claim：`clm_0001` supported 0.86

### 上下文规模

- 文件总数：2017
- 重要文件覆盖：40/2017
- 证据索引条目：80
- 角色 / Skill 条目：69

### 证据不足时的处理

- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。
- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。
- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。
- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。

## Prompt Recipes

### 适配判断

- 目标：判断这个项目是否适合用户当前任务。
- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。

```text
请基于 encore 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。
```

### 安装前体验

- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。
- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。

```text
请把 encore 当作安装前体验资产，而不是已安装工具或真实运行环境。

请严格输出四段：
1. 先问我 3 个必要问题。
2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。
3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。
4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。

硬性边界：
- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。
- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。
- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。
- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。
- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。
- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。

```

### 角色 / Skill 选择

- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。
- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。

```text
请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。
```

### 风险预检

- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。
- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。

```text
请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。
```

### 宿主 AI 开工指令

- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。
- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。

```text
请基于 encore 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。
```

## 角色 / Skill 索引

- 共索引 69 个角色 / Skill / 项目文档条目。

- **What is Encore?**（project_doc）：Encore: Infrastructure orchestration from local to your cloud 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`
- **End to End Tests**（project_doc）：This folder contains end to end tests for Encore, which test everything in Encore as an end user would use it. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`e2e-tests/README.md`
- **Kubernetes Types**（project_doc）：This package contains types copied directly from the Kubernetes https://github.com/kubernetes/kubernetes project, this is to prevent the Encore CLI needing to have a dependency on the Kubernetes project for just these types. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`cli/cmd/encore/k8s/types/README.md`
- **Readme**（project_doc）：! Build Status https://travis-ci.org/gregjones/httpcache.svg?branch=master https://travis-ci.org/gregjones/httpcache ! GoDoc https://godoc.org/github.com/gregjones/httpcache?status.svg https://godoc.org/github.com/gregjones/httpcache 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`internal/httpcache/README.md`
- **pgproxy**（project_doc）：pgproxy is a flexible proxy for the Postgres wire protocol that allows for customizing authentication and backend selection by breaking apart the startup message flow between frontend and backend. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`pkg/pgproxy/README.md`
- **Encore Runtime**（project_doc）：This is the Encore runtime module that provides APIs and internal runtime components for running Encore applications. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`runtimes/go/README.md`
- **metrics**（project_doc）：This package allows an Encore app to export custom metrics to metric providers. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`runtimes/go/appruntime/infrasdk/metrics/README.md`
- **Encore JavaScript/TypeScript SDK**（project_doc）：This package contains the Encore JavaScript/TypeScript SDK, it is intended for you to use in your applications to develop against the Encore API. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`runtimes/js/encore.dev/README.md`
- **SemGrep Rules**（project_doc）：This directory contains a set of Semgrep rules we run against Encore's source code. You can find more information about the syntax of rules in the Semgrep documentation https://semgrep.dev/docs/writing-rules/overview/ . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tools/semgrep-rules/README.md`
- **Readme**（project_doc）：Encore Note We've copied in the rules from https://github.com/dgryski/semgrep-go on 2023-07-27 However delete some rules that we don't want to run in our codebase and updated some other rules. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tools/semgrep-rules/semgrep-go/README.md`
- **txtar**（project_doc）：! crates.io version 1 2 ! docs.rs docs 3 4 ! license 5 6 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tsparser/txtar/README.md`
- **tsparser-wasm**（project_doc）：WebAssembly build of the Encore TypeScript parser. Parses Encore.ts source files in the browser and returns application metadata APIs, services, infrastructure resources, etc. . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tsparser/wasm/README.md`
- **Install the Encore CLI**（project_doc）：If you are new to Encore, we recommend following the quick start guide /docs/go/quick-start . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/install.md`
- **Install the Encore CLI**（project_doc）：If you are new to Encore, we recommend following the quick start guide /docs/ts/quick-start . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/ts/install.md`
- **Integration Tests**（project_doc）：These are the integration tests from the original miniredis https://github.com/alicebob/miniredis Go implementation integration/ , adapted to compare miniredis-rs against miniredis-go at the RESP byte level. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`miniredis/tests/integration-go/README.md`
- **Update Golden Tests**（project_doc）：Instead of manually updating the golden tests, once you've verified the output of the tests is correct, then you can simply update all the expected output files files by running 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`pkg/clientgen/testdata/README.md`
- **Readme**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`pkg/vfs/testdata/filteredglob/foosystem/README.md`
- **Contributing to Encore**（project_doc）：We're so excited that you are interested in contributing to Encore! All contributions are welcome, and there are several valuable ways to contribute. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`
- **What AI Enables**（project_doc）：Encore is built for AI-assisted development. Encore-specific rules and MCP /docs/go/ai-integration mcp-server integration let AI understand your architecture and generate type-safe code that follows your patterns. Run encore run to start your app; Encore provisions local infrastructure automatically. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/ai-integration.md`
- **Running**（project_doc）：Flag Description Default --- --- --- -w, --watch Watch for changes and live-reload true --listen Address to listen on e.g. 0.0.0.0:4000 -p, --port Port to listen on 4000 --json Display logs in JSON format false -n, --namespace Namespace to use defaults to active namespace --color Whether to display colorized output auto-detected --redact Redact sensitive data in traces when running locally false -l, --level Minimum… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/cli/cli-reference.md`
- **Generating a Client**（project_doc）：Encore makes it simple to write scalable distributed backends by allowing you to make function calls that Encore translates into RPC calls. Encore also generates API clients with interfaces that look like the original Go functions, with the same parameters and response signature as the server. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/cli/client-generation.md`
- **Configuration files**（project_doc）：The Encore CLI has a number of configuration options to customize its behavior. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/cli/config-reference.md`
- **Usage**（project_doc）：Encore's CLI allows you to create and switch between multiple, independent infrastructure namespaces . Infrastructure namespaces are isolated from each other, and each namespace contains its own independent data. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/cli/infra-namespaces.md`
- **Example: Integrating with Cursor**（project_doc）：Encore provides an MCP server that implements the Model Context Protocol https://modelcontextprotocol.io/introduction , an open standard that enables large language models LLMs to access contextual information about your application. Think of MCP as a standardized interface—like a "USB-C port for AI applications"—that connects your Encore app's data and functionality to any LLM that supports the protocol. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/cli/mcp.md`
- **Why We Collect Data**（project_doc）：Telemetry helps us improve the Encore by collecting usage data. This data provides insights into how Encore is used, enabling us to make informed decisions to enhance performance, add new features, and fix bugs more efficiently. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/cli/telemetry.md`
- **Open Source Project**（project_doc）：We’re so excited that you are interested in contributing to Encore! All contributions are welcome, and there are several valuable ways to contribute. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/community/contribute.md`
- **Get involved**（project_doc）：Developers building with Encore are forward-thinkers, who are working on exciting and innovative applications. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/community/get-involved.md`
- **License**（project_doc）：We believe Open Source is key to a long-term sustainable and prosperous technology community. Encore builds on Open Source software, and is largely Open Source itself. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/community/open-source.md`
- **Code of Conduct**（project_doc）：Everyone is welcome in the Encore community, and it is of utmost importance to us that everyone is able to feel at home and contribute. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/community/principles.md`
- **Submit your contribution**（project_doc）：Templates /templates help and inspire developers to build applications using Encore. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/community/submit-template.md`
- **Standardization brings clarity**（project_doc）：Encore works by using static analysis to understand your application. This is a fancy term for parsing and analyzing the code you write and creating a graph of how your application works. This graph closely represents your own mental model of the system: boxes and arrows that represent systems and services that communicate with other systems, pass data and connect to infrastructure. We call it the Encore Application… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/concepts/application-model.md`
- **No DevOps experience required**（project_doc）：Using Encore.go to declare infrastructure in application code helps unlock several benefits: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/concepts/benefits.md`
- **Services**（project_doc）：Encore parses doc comments from your Go source code and surfaces them in the Service Catalog /docs/go/observability/service-catalog , generated API clients /docs/go/cli/client-generation , and OpenAPI specs. This means your documentation stays in your code and is always up to date. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/develop/api-docs.md`
- **The auth handler**（project_doc）：Almost every application needs to know who's calling it, whether the user represents a person in a consumer-facing app or an organization in a B2B app. Encore supports both use cases in a simple yet powerful way. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/develop/auth.md`
- **Using Config**（project_doc）：Configuration files let you define default behavior for your application, and override it for specific environments. This allows you to make changes without affecting deployments in other environments. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/develop/config.md`
- **Configuring CORS**（project_doc）：CORS is a web security concept that defines which website origins are allowed to access your API. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/develop/cors.md`
- **Daemon & Development Dashboard**（project_doc）：Encore works out of the box without configuration, but provides several environment variables for advanced use cases such as debugging, testing, or adapting Encore to specific workflow requirements. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/develop/env-vars.md`
- **Application Metadata**（project_doc）：While Encore tries to provide a cloud-agnostic environment, sometimes it's helpful to know more about the environment your application is running in. For this reason Encore provides an API for accessing metadata about the application application-metadata and the environment it's running in, as well as information about the current request current-request as part of the encore.dev package. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/develop/metadata.md`
- **Middleware functions**（project_doc）：Middleware is a way to write reusable code that runs before or after or both the handling of API requests, often across several or all API endpoints. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/develop/middleware.md`
- **Mocking Endpoints**（project_doc）：Encore comes with built-in support for mocking out APIs and services, which makes it easier to test your application in isolation. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/develop/mocking.md`
- **Validation**（project_doc）：When receiving incoming requests it's best practice to validate the payload to make sure it meets your expectations, contains all the necessary fields, and so on. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/develop/validation.md`
- **About the project**（project_doc）：Yes, check out the project on GitHub https://github.com/encoredev/encore . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/faq.md`
- **Setting up GORM**（project_doc）：Atlas https://atlasgo.io is a popular tool for managing database migrations. GORM https://gorm.io/ is a popular ORM for Go. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/how-to/atlas-gorm.md`
- **Communicate with Auth0**（project_doc）：In this guide you will learn how to set up an Encore auth handler /docs/go/develop/auth the-auth-handler that makes use of Auth0 https://auth0.com/ in order to add a seamless signup and login experience to your web app. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/how-to/auth0-auth.md`
- **How to break out a service from a monolith**（project_doc）：It's common to want to break out specific functionality into separate services. Perhaps you want to independently scale a specific service, or simply want to structure your codebase in smaller pieces. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/how-to/break-up-monolith.md`
- **Static linking**（project_doc）：Cgo is a feature of the Go compiler that enables Go programs to interface with libraries written in other languages using C bindings. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/how-to/cgo.md`
- **Set up the auth handler**（project_doc）：In this guide you will learn how to set up an Encore auth handler /docs/go/develop/auth the-auth-handler that makes use of Clerk https://clerk.com/ in order to add an integrated signup and login experience to your web app. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/how-to/clerk-auth.md`
- **Debug by starting the process in debug mode**（project_doc）：Encore makes it easy to debug your application using Delve https://github.com/go-delve/delve "Delve" . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/how-to/debug.md`
- **Mocking dependencies**（project_doc）：Dependency Injection is a fancy name for a simple concept: when you depend on some functionality, add that dependency as a field on your struct and refer to it that way instead of directly calling it. By doing so it becomes easier to test your services by swapping out certain dependencies for other implementations often with the use of interfaces . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/how-to/dependency-injection.md`
- **Installation**（project_doc）：The Encore Toolbar is a lightweight, drop-in script that adds a floating developer panel to your frontend application. It automatically intercepts all fetch and XMLHttpRequest calls, captures trace IDs from Encore's response headers, and lets you jump directly to the corresponding trace in the Development Dashboard /docs/go/observability/dev-dash or Encore Cloud https://app.encore.dev . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/how-to/encore-toolbar.md`
- **Add ent schemas to a service**（project_doc）：Encore has all the tools needed to support ORMs and migration frameworks out-of-the-box through named databases /docs/go/primitives/share-db-between-services and migration files /docs/go/primitives/databases defining-a-database-schema . Writing plain SQL might not work for your use case, or you may not want to use SQL in the first place. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/how-to/entgo-orm.md`
- **Set up auth handler**（project_doc）：Encore's authentication support /docs/go/develop/auth provides a simple yet powerful way of dealing with various authentication scenarios. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/how-to/firebase-auth.md`
- **Define a Connect service**（project_doc）：The Connect protocol https://connectrpc.com/ is an HTTP/2-based protocol for RPC communication. It's conceptually similar to gRPC, but with better support for using from browsers and JavaScript clients. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/how-to/grpc-connect.md`
- **Defining raw endpoints**（project_doc）：Encore makes it easy to define APIs and expose them, but it works best when you are in charge of the API schema. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/how-to/http-requests.md`
- **Logto settings**（project_doc）：Logto https://logto.io is a modern Auth0 alternative that helps you build the sign-in experience and user identity within minutes. It's particularly well-suited for protecting API services built with Encore. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/how-to/logto-auth.md`
- **Publishing messages to the outbox**（project_doc）：One of the hardest parts of building an event-driven application is ensuring consistency between services. A common pattern is for each service to have its own database and use Pub/Sub to notify other systems of business events. Inevitably this leads to inconsistencies since the Pub/Sub publishing is not transactional with the database writes. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/how-to/pubsub-outbox.md`
- **Set up Temporal clusters**（project_doc）：Temporal https://temporal.io is a workflow orchestration system for building highly reliable systems. Encore works great with Temporal, and this guide shows you how to integrate Temporal into your Encore application. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/how-to/temporal.md`
- **Accommodating for your unique requirements**（project_doc）：We realize most people read this page before even trying Encore, so we start with a perspective on how you might reason about adopting Encore. Read on to see what tools are available for migrating away. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/migration/migrate-away.md`
- **Dev Dash**（project_doc）：Encore provides an efficient local development workflow that automatically provisions local infrastructure /docs/platform/infrastructure/infra local-development and supports automated testing with dedicated test infrastructure. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/observability/dev-dash.md`
- **Birds-eye view**（project_doc）：Flow is a visual tool that gives you an always up-to-date view of your entire system, helping you reason about your microservices architecture and identify which services depend on each other and how they work together. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/observability/encore-flow.md`
- **Usage**（project_doc）：Encore offers built-in support for Structured Logging, which combines a free-form log message with structured and type-safe key-value pairs. This enables straightforward analysis of what your application is doing, in a way that is easy for a computer to parse, analyze, and index. This makes it simple to quickly filter and search through logs. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/observability/logging.md`
- **Defining custom metrics**（project_doc）：Encore provides built-in support for defining custom metrics in your Go applications. Once defined, metrics are automatically collected and displayed in the Encore Cloud Dashboard, and can be exported to third-party observability services. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/observability/metrics.md`
- **Service Catalog**（project_doc）：All developers agree API documentation is great to have, but the effort of maintaining it inevitably leads to docs becoming stale and out of date. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/observability/service-catalog.md`
- **Encore's tracing is more comprehensive and more performant than all other tools**（project_doc）：Distributed systems often have many moving parts, making it difficult to understand what your code is doing and finding the root-cause to bugs. That’s where Tracing comes in. If you haven’t seen it before, it may just about change your life. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/observability/tracing.md`
- **What you get with Encore.go**（project_doc）：Quick Start Guide Try building with Encore.go Get started 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/overview.md`
- **Current Request**（project_doc）：Calling an API endpoint looks like a regular function call with Encore.go. To call an endpoint you first import the other service as a Go package using import "encore.app/package-name" and then call the API endpoint like a regular function. Encore will automatically generate the necessary boilerplate at compile-time. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/primitives/api-calls.md`
- **The errs.Error type**（project_doc）：Encore supports returning structured error information from your APIs using the encore.dev/beta/errs https://pkg.go.dev/encore.dev/beta/errs package. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/primitives/api-errors.md`
- **Path parameters**（project_doc）：APIs in Encore are regular functions with request and response data types. These types are structs or pointers to structs with optional field tags, which Encore uses to encode API requests to HTTP messages. The same struct can be used for requests and responses, but the query tag is ignored when generating responses. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/primitives/api-schemas.md`
- **Monolith or Microservices**（project_doc）：Encore uses a monorepo design and it's best to use one Encore app for your entire backend application. This lets Encore build an application model that spans your entire app, necessary to get the most value out of many features like distributed tracing /docs/go/observability/tracing and Encore Flow /docs/go/observability/encore-flow . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/go/primitives/app-structure.md`

## 证据索引

- 共索引 80 条证据。

- **What is Encore?**（documentation）：Encore: Infrastructure orchestration from local to your cloud 证据：`README.md`
- **End to End Tests**（documentation）：This folder contains end to end tests for Encore, which test everything in Encore as an end user would use it. 证据：`e2e-tests/README.md`
- **Kubernetes Types**（documentation）：This package contains types copied directly from the Kubernetes https://github.com/kubernetes/kubernetes project, this is to prevent the Encore CLI needing to have a dependency on the Kubernetes project for just these types. 证据：`cli/cmd/encore/k8s/types/README.md`
- **Readme**（documentation）：! Build Status https://travis-ci.org/gregjones/httpcache.svg?branch=master https://travis-ci.org/gregjones/httpcache ! GoDoc https://godoc.org/github.com/gregjones/httpcache?status.svg https://godoc.org/github.com/gregjones/httpcache 证据：`internal/httpcache/README.md`
- **pgproxy**（documentation）：pgproxy is a flexible proxy for the Postgres wire protocol that allows for customizing authentication and backend selection by breaking apart the startup message flow between frontend and backend. 证据：`pkg/pgproxy/README.md`
- **Encore Runtime**（documentation）：This is the Encore runtime module that provides APIs and internal runtime components for running Encore applications. 证据：`runtimes/go/README.md`
- **metrics**（documentation）：This package allows an Encore app to export custom metrics to metric providers. 证据：`runtimes/go/appruntime/infrasdk/metrics/README.md`
- **Encore JavaScript/TypeScript SDK**（documentation）：This package contains the Encore JavaScript/TypeScript SDK, it is intended for you to use in your applications to develop against the Encore API. 证据：`runtimes/js/encore.dev/README.md`
- **SemGrep Rules**（documentation）：This directory contains a set of Semgrep rules we run against Encore's source code. You can find more information about the syntax of rules in the Semgrep documentation https://semgrep.dev/docs/writing-rules/overview/ . 证据：`tools/semgrep-rules/README.md`
- **Readme**（documentation）：Encore Note We've copied in the rules from https://github.com/dgryski/semgrep-go on 2023-07-27 However delete some rules that we don't want to run in our codebase and updated some other rules. 证据：`tools/semgrep-rules/semgrep-go/README.md`
- **txtar**（documentation）：! crates.io version 1 2 ! docs.rs docs 3 4 ! license 5 6 证据：`tsparser/txtar/README.md`
- **tsparser-wasm**（documentation）：WebAssembly build of the Encore TypeScript parser. Parses Encore.ts source files in the browser and returns application metadata APIs, services, infrastructure resources, etc. . 证据：`tsparser/wasm/README.md`
- **Package**（package_manifest）：{ "name": "encore.dev", "description": "Encore's JavaScript/TypeScript SDK", "version": "0.0.0-devel.202311141645", "license": "MPL-2.0", "bugs": { "url": "https://github.com/encoredev/encore/issues" }, "repository": { "type": "git", "url": "https://github.com/encoredev/encore", "directory": "runtimes/js/encore.dev" }, "scripts": { "build": "tsc -b", "lint": "eslint \" / .ts \"", "test": "bun test", "docs": "typedoc && node scripts/postprocess-docs.mjs" }, "type": "module", "sideEffects": false, "exports": { ".": { "types": "./mod.ts", "bun": "./mod.ts", "default": "./dist/mod.js" }, "./api": { "types": "./api/mod.ts", "bun": "./api/mod.ts", "default": "./dist/api/mod.js" }, "./auth": { "ty… 证据：`runtimes/js/encore.dev/package.json`
- **Install the Encore CLI**（documentation）：If you are new to Encore, we recommend following the quick start guide /docs/go/quick-start . 证据：`docs/go/install.md`
- **Install the Encore CLI**（documentation）：If you are new to Encore, we recommend following the quick start guide /docs/ts/quick-start . 证据：`docs/ts/install.md`
- **Integration Tests**（documentation）：These are the integration tests from the original miniredis https://github.com/alicebob/miniredis Go implementation integration/ , adapted to compare miniredis-rs against miniredis-go at the RESP byte level. 证据：`miniredis/tests/integration-go/README.md`
- **Update Golden Tests**（documentation）：Instead of manually updating the golden tests, once you've verified the output of the tests is correct, then you can simply update all the expected output files files by running 证据：`pkg/clientgen/testdata/README.md`
- **Readme**（documentation）：This is a example file 证据：`pkg/vfs/testdata/filteredglob/foosystem/README.md`
- **Package**（package_manifest）：{ "private": true, "type": "module", "scripts": { "test": "node --trace-warnings --experimental-specifier-resolution=node --loader ts-node/esm ./ts/main.ts", "test:js": "node --trace-warnings --experimental-specifier-resolution=node ./js/main.js", "lint": "tsc --noEmit && eslint \" / .{ts,js}\"" }, "devDependencies": { "@types/node": "^17.0.35", "@typescript-eslint/eslint-plugin": "^5.26.0", "@typescript-eslint/parser": "^5.26.0", "eslint": "^8.16.0", "ts-node": "^10.8.0", "typescript": "^4.6.4" }, "dependencies": { "isomorphic-fetch": "^3.0.0" } } 证据：`e2e-tests/testdata/echo_client/package.json`
- **Package**（package_manifest）：{ "name": "encore-ts-testapp", "private": true, "version": "0.0.1", "description": "Encore Typescript Test app", "license": "MPL-2.0", "type": "module", "scripts": { "test": "vitest" }, "devDependencies": { "@types/node": "^22.5.7", "typescript": "^5.4", "vitest": "^3.1.3" }, "dependencies": { "encore.dev": "file:/Users/andre/src/github.com/encoredev/encore/runtimes/js/encore.dev" }, "optionalDependencies": { "@rollup/rollup-linux-x64-gnu": "^4.13.0" } } 证据：`e2e-tests/testdata/tsapp/package.json`
- **Contributing to Encore**（documentation）：We're so excited that you are interested in contributing to Encore! All contributions are welcome, and there are several valuable ways to contribute. 证据：`CONTRIBUTING.md`
- **License**（source_file）：Mozilla Public License, version 2.0 证据：`LICENSE`
- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the "Software" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`pkg/editors/LICENSE`
- **License**（source_file）：Copyright c 2021 Engineering at Fullstory 证据：`pkg/emulators/storage/LICENSE`
- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the "Software" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`pkg/tarstream/LICENSE`
- **License**（source_file）：Copyright c 2019-2021 Tower Contributors 证据：`runtimes/core/src/api/cors/cors_headers_config/LICENSE`
- **License**（source_file）：Copyright c 2013-2021 Jack Christensen 证据：`runtimes/go/storage/sqldb/internal/stdlibdriver/LICENSE`
- **License**（source_file）：Mozilla Public License, version 2.0 证据：`runtimes/js/encore.dev/LICENSE`
- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the "Software" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`tools/semgrep-rules/semgrep-go/LICENSE`
- **What AI Enables**（documentation）：Encore is built for AI-assisted development. Encore-specific rules and MCP /docs/go/ai-integration mcp-server integration let AI understand your architecture and generate type-safe code that follows your patterns. Run encore run to start your app; Encore provisions local infrastructure automatically. 证据：`docs/go/ai-integration.md`
- **Running**（documentation）：Flag Description Default --- --- --- -w, --watch Watch for changes and live-reload true --listen Address to listen on e.g. 0.0.0.0:4000 -p, --port Port to listen on 4000 --json Display logs in JSON format false -n, --namespace Namespace to use defaults to active namespace --color Whether to display colorized output auto-detected --redact Redact sensitive data in traces when running locally false -l, --level Minimum log level to display trace\ debug\ info\ warn\ error --debug Compile for debugging enabled\ break --browser Open local dev dashboard in browser on startup auto\ never\ always auto 证据：`docs/go/cli/cli-reference.md`
- **Generating a Client**（documentation）：Encore makes it simple to write scalable distributed backends by allowing you to make function calls that Encore translates into RPC calls. Encore also generates API clients with interfaces that look like the original Go functions, with the same parameters and response signature as the server. 证据：`docs/go/cli/client-generation.md`
- **Configuration files**（documentation）：The Encore CLI has a number of configuration options to customize its behavior. 证据：`docs/go/cli/config-reference.md`
- **Usage**（documentation）：Encore's CLI allows you to create and switch between multiple, independent infrastructure namespaces . Infrastructure namespaces are isolated from each other, and each namespace contains its own independent data. 证据：`docs/go/cli/infra-namespaces.md`
- **Example: Integrating with Cursor**（documentation）：Encore provides an MCP server that implements the Model Context Protocol https://modelcontextprotocol.io/introduction , an open standard that enables large language models LLMs to access contextual information about your application. Think of MCP as a standardized interface—like a "USB-C port for AI applications"—that connects your Encore app's data and functionality to any LLM that supports the protocol. 证据：`docs/go/cli/mcp.md`
- **Why We Collect Data**（documentation）：Telemetry helps us improve the Encore by collecting usage data. This data provides insights into how Encore is used, enabling us to make informed decisions to enhance performance, add new features, and fix bugs more efficiently. 证据：`docs/go/cli/telemetry.md`
- **Open Source Project**（documentation）：We’re so excited that you are interested in contributing to Encore! All contributions are welcome, and there are several valuable ways to contribute. 证据：`docs/go/community/contribute.md`
- **Get involved**（documentation）：Developers building with Encore are forward-thinkers, who are working on exciting and innovative applications. 证据：`docs/go/community/get-involved.md`
- **License**（documentation）：We believe Open Source is key to a long-term sustainable and prosperous technology community. Encore builds on Open Source software, and is largely Open Source itself. 证据：`docs/go/community/open-source.md`
- **Code of Conduct**（documentation）：Everyone is welcome in the Encore community, and it is of utmost importance to us that everyone is able to feel at home and contribute. 证据：`docs/go/community/principles.md`
- **Submit your contribution**（documentation）：Templates /templates help and inspire developers to build applications using Encore. 证据：`docs/go/community/submit-template.md`
- **Standardization brings clarity**（documentation）：Encore works by using static analysis to understand your application. This is a fancy term for parsing and analyzing the code you write and creating a graph of how your application works. This graph closely represents your own mental model of the system: boxes and arrows that represent systems and services that communicate with other systems, pass data and connect to infrastructure. We call it the Encore Application Model. 证据：`docs/go/concepts/application-model.md`
- **No DevOps experience required**（documentation）：Using Encore.go to declare infrastructure in application code helps unlock several benefits: 证据：`docs/go/concepts/benefits.md`
- **Services**（documentation）：Encore parses doc comments from your Go source code and surfaces them in the Service Catalog /docs/go/observability/service-catalog , generated API clients /docs/go/cli/client-generation , and OpenAPI specs. This means your documentation stays in your code and is always up to date. 证据：`docs/go/develop/api-docs.md`
- **The auth handler**（documentation）：Almost every application needs to know who's calling it, whether the user represents a person in a consumer-facing app or an organization in a B2B app. Encore supports both use cases in a simple yet powerful way. 证据：`docs/go/develop/auth.md`
- **Using Config**（documentation）：Configuration files let you define default behavior for your application, and override it for specific environments. This allows you to make changes without affecting deployments in other environments. 证据：`docs/go/develop/config.md`
- **Configuring CORS**（documentation）：CORS is a web security concept that defines which website origins are allowed to access your API. 证据：`docs/go/develop/cors.md`
- **Daemon & Development Dashboard**（documentation）：Encore works out of the box without configuration, but provides several environment variables for advanced use cases such as debugging, testing, or adapting Encore to specific workflow requirements. 证据：`docs/go/develop/env-vars.md`
- **Application Metadata**（documentation）：While Encore tries to provide a cloud-agnostic environment, sometimes it's helpful to know more about the environment your application is running in. For this reason Encore provides an API for accessing metadata about the application application-metadata and the environment it's running in, as well as information about the current request current-request as part of the encore.dev package. 证据：`docs/go/develop/metadata.md`
- **Middleware functions**（documentation）：Middleware is a way to write reusable code that runs before or after or both the handling of API requests, often across several or all API endpoints. 证据：`docs/go/develop/middleware.md`
- **Mocking Endpoints**（documentation）：Encore comes with built-in support for mocking out APIs and services, which makes it easier to test your application in isolation. 证据：`docs/go/develop/mocking.md`
- **Validation**（documentation）：When receiving incoming requests it's best practice to validate the payload to make sure it meets your expectations, contains all the necessary fields, and so on. 证据：`docs/go/develop/validation.md`
- **About the project**（documentation）：Yes, check out the project on GitHub https://github.com/encoredev/encore . 证据：`docs/go/faq.md`
- **Setting up GORM**（documentation）：Atlas https://atlasgo.io is a popular tool for managing database migrations. GORM https://gorm.io/ is a popular ORM for Go. 证据：`docs/go/how-to/atlas-gorm.md`
- **Communicate with Auth0**（documentation）：In this guide you will learn how to set up an Encore auth handler /docs/go/develop/auth the-auth-handler that makes use of Auth0 https://auth0.com/ in order to add a seamless signup and login experience to your web app. 证据：`docs/go/how-to/auth0-auth.md`
- **How to break out a service from a monolith**（documentation）：It's common to want to break out specific functionality into separate services. Perhaps you want to independently scale a specific service, or simply want to structure your codebase in smaller pieces. 证据：`docs/go/how-to/break-up-monolith.md`
- **Static linking**（documentation）：Cgo is a feature of the Go compiler that enables Go programs to interface with libraries written in other languages using C bindings. 证据：`docs/go/how-to/cgo.md`
- **Set up the auth handler**（documentation）：In this guide you will learn how to set up an Encore auth handler /docs/go/develop/auth the-auth-handler that makes use of Clerk https://clerk.com/ in order to add an integrated signup and login experience to your web app. 证据：`docs/go/how-to/clerk-auth.md`
- **Debug by starting the process in debug mode**（documentation）：Encore makes it easy to debug your application using Delve https://github.com/go-delve/delve "Delve" . 证据：`docs/go/how-to/debug.md`
- **Mocking dependencies**（documentation）：Dependency Injection is a fancy name for a simple concept: when you depend on some functionality, add that dependency as a field on your struct and refer to it that way instead of directly calling it. By doing so it becomes easier to test your services by swapping out certain dependencies for other implementations often with the use of interfaces . 证据：`docs/go/how-to/dependency-injection.md`
- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。

## 宿主 AI 必须遵守的规则

- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `e2e-tests/README.md`, `cli/cmd/encore/k8s/types/README.md`
- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `e2e-tests/README.md`, `cli/cmd/encore/k8s/types/README.md`

## 用户开工前应该回答的问题

- 你准备在哪个宿主 AI 或本地环境中使用它？
- 你只是想先体验工作流，还是准备真实安装？
- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？

## 验收标准

- 所有能力声明都能回指到 evidence_refs 中的文件路径。
- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。
- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。

---

## Doramagic Context Augmentation

下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。

## Human Manual 骨架

使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。

宿主 AI 硬性规则：
- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。
- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。
- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。

- **项目概览**：importance `high`
  - source_paths: .devcontainer/Dockerfile, README.md, cli/cmd/encore/k8s/types/README.md, e2e-tests/README.md, e2e-tests/testdata/echo_client/package.json
- **Src 模块**：importance `high`
  - source_paths: runtimes/js/src/api.rs, runtimes/js/src/cache.rs, runtimes/js/src/cookies.rs, runtimes/js/src/error.rs, runtimes/js/src/gateway.rs
- **Src 模块**：importance `high`
  - source_paths: supervisor/src/bin/supervisor-encore.rs, supervisor/src/config.rs, supervisor/src/lib.rs, supervisor/src/proxy.rs, supervisor/src/supervisor.rs
- **Src 模块**：importance `high`
  - source_paths: tsparser/txtar/src/error.rs, tsparser/txtar/src/lib.rs

## Repo Inspection Evidence / 源码检查证据

- repo_clone_verified: true
- repo_inspection_verified: true
- repo_commit: `3b3cba5099ec9a05839ca3bb4bc1b27fdd27f45d`
- inspected_files: `README.md`, `docs/go/ai-integration.md`, `docs/go/cli/cli-reference.md`, `docs/go/cli/client-generation.md`, `docs/go/cli/config-reference.md`, `docs/go/cli/infra-namespaces.md`, `docs/go/cli/mcp.md`, `docs/go/cli/telemetry.md`, `docs/go/community/contribute.md`, `docs/go/community/get-involved.md`, `docs/go/community/open-source.md`, `docs/go/community/principles.md`, `docs/go/community/submit-template.md`, `docs/go/concepts/application-model.md`, `docs/go/concepts/benefits.md`, `docs/go/develop/api-docs.md`, `docs/go/develop/auth.md`, `docs/go/develop/config.md`, `docs/go/develop/cors.md`, `docs/go/develop/env-vars.md`

宿主 AI 硬性规则：
- 没有 repo_clone_verified=true 时，不得声称已经读过源码。
- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。
- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。

## Doramagic Pitfall Constraints / 踩坑约束

这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。

### Constraint 1: 来源证据：Encore.ts: api.raw delivers no client-disconnect signal — response 'close'/'error' never fire, streaming/SSE handlers c…

- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Encore.ts: api.raw delivers no client-disconnect signal — response 'close'/'error' never fire, streaming/SSE handlers can't abort abandoned work
- Why it matters: 可能增加新用户试用和生产接入成本。
- Evidence: community_evidence:github | https://github.com/encoredev/encore/issues/2515 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 2: 来源证据：Deploy branch selection UI shows deleted branches

- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Deploy branch selection UI shows deleted branches
- Why it matters: 可能增加新用户试用和生产接入成本。
- Evidence: community_evidence:github | https://github.com/encoredev/encore/issues/2495 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 3: 来源证据：Docs: self-host infra config `databases` map key and `name` descriptions are inverted vs runtime behavior

- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Docs: self-host infra config `databases` map key and `name` descriptions are inverted vs runtime behavior
- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Why it matters: 可能增加新用户试用和生产接入成本。
- Evidence: community_evidence:github | https://github.com/encoredev/encore/issues/2461 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 4: 能力判断依赖假设

- Trigger: README/documentation is current enough for a first validation pass.
- Host AI rule: 将假设转成下游验证清单。
- Why it matters: 假设不成立时，用户拿不到承诺的能力。
- Evidence: capability.assumptions | https://github.com/encoredev/encore | README/documentation is current enough for a first validation pass.
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 5: 维护活跃度未知

- Trigger: 未记录 last_activity_observed。
- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。
- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- Evidence: evidence.maintainer_signals | https://github.com/encoredev/encore | last_activity_observed missing
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

- Trigger: no_demo
- Evidence: downstream_validation.risk_items | https://github.com/encoredev/encore | no_demo; severity=medium
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 7: 存在评分风险

- Trigger: no_demo
- Why it matters: 风险会影响是否适合普通用户安装。
- Evidence: risks.scoring_risks | https://github.com/encoredev/encore | no_demo; severity=medium
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 8: 来源证据：`encore version` exits 1 when the update-check hangs

- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：`encore version` exits 1 when the update-check hangs
- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Why it matters: 可能影响授权、密钥配置或安全边界。
- Evidence: community_evidence:github | https://github.com/encoredev/encore/issues/2493 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 9: issue/PR 响应质量未知

- Trigger: issue_or_pr_quality=unknown。
- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。
- Why it matters: 用户无法判断遇到问题后是否有人维护。
- Evidence: evidence.maintainer_signals | https://github.com/encoredev/encore | issue_or_pr_quality=unknown
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 10: 发布节奏不明确

- Trigger: release_recency=unknown。
- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。
- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。
- Evidence: evidence.maintainer_signals | https://github.com/encoredev/encore | release_recency=unknown
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。