diff --git a/docs/product/code-search.zh.md b/docs/product/code-search.zh.md
new file mode 100644
index 000000000..701e3a005
--- /dev/null
+++ b/docs/product/code-search.zh.md
@@ -0,0 +1,342 @@
+# Code Search
+
+Code Search 是 XBuilder 的项目代码搜索能力。它面向 XBuilder 项目中的源码和选定项目元数据，提供可解释、可定位、可审计的文本搜索和结构化搜索能力。
+
+本文档定义 Code Search 的产品与系统边界。它描述目标状态和关键语义，不定义最终数据库 schema、完整 OpenAPI 契约或具体实现任务。
+
+## 背景与目标
+
+XBuilder 项目代码目前保存在项目文件集合中。`Project.files` 和 `ProjectRelease.files` 都是 `path -> universal URL` 形式的文件映射，文件内容可能以内联 `data:` URL 保存，也可能通过 `kodo://` 等对象存储地址引用。现有 `/projects` 的 `keyword` 参数只搜索项目展示名或名称模式，不搜索项目源码。
+
+XBuilder 需要一套通用的项目代码搜索能力，用于在用户项目中查找具体源码、结构化代码形态、可解析的匹配位置和可聚合的结果。第一个预期客户端是 XBuilder 管理台，但 Code Search 本身不是某个 admin 页面专用功能，也不应该被建模为某个框架的专用报告。
+
+目标包括：
+
+- 支持跨 XBuilder 项目源搜索源码和选定项目元数据
+- 支持代码导向的文本搜索，并返回具体匹配位置和片段
+- 支持语法级结构化搜索，并返回匹配范围、captures 和诊断信息
+- 将文本搜索、结构化搜索和未来的语义过滤分层建模
+- 明确 latest project content 和 release snapshot 的来源身份
+- 明确可搜索文件、文件角色、语言检测和排除策略
+- 通过索引提供稳定、可分页、可解释的搜索结果
+- 暴露索引覆盖、陈旧、失败和部分结果状态
+- 支持面向 admin 的首个使用界面，同时保持后端能力通用
+- 保护私有项目源码和派生索引中的用户内容
+- 为 `tree-sitter-xgo`、XGo 语义分析和后续代码迁移能力留下演进空间
+
+非目标包括：
+
+- 不定义 spx 专用 API 使用统计报告
+- 不把后端 API 做成 spx 或任意单个 XGo classfile framework 专用接口
+- 不把 Code Search 等同于社区项目搜索或 `/projects` keyword 搜索
+- 不提供自然语言、embedding 或 LLM 语义相似搜索作为权威匹配机制
+- 不要求第一阶段支持 resolved symbol 级精确匹配
+- 不要求第一阶段支持完整 ast-grep 或 Semgrep 兼容
+- 不把 lint、severity、message、fix、rule pack 或 codemod 作为第一阶段搜索契约
+- 不在默认结果中暴露完整源码、原始 file collection、universal URL 或 signed URL
+- 不让搜索引擎、对象存储或外部索引后端成为绕过后端授权的读取路径
+
+## 核心概念
+
+| 概念 | 含义 |
+| - | - |
+| Code Search | XBuilder 的项目代码搜索能力，覆盖文本搜索、语法级结构化搜索和未来的语义过滤 |
+| 项目源 project source | 可被搜索的项目代码来源，如 latest project content 或 release snapshot |
+| latest project content | `Project.files` 表示的当前项目文件集合，是可变来源 |
+| release snapshot | `ProjectRelease.files` 表示的项目发布快照，是发布时复制出的文件集合 |
+| source identity | 标识一次匹配来自哪个项目源、哪个文件、哪个内容版本和哪个索引版本的信息 |
+| file collection | `path -> universal URL` 形式的项目文件集合 |
+| searchable file | 被 Code Search 纳入索引和查询的文件 |
+| file role | 文件在 XBuilder 项目模型中的角色，如 spx project code、spx sprite code、project config、sprite config、asset metadata、generated internal metadata 或 binary asset |
+| text search | 面向源码文本的字面量、标识符、字符串、路径相关或正则搜索 |
+| structural matching | 基于语法树的结构化匹配，用代码形态或语法节点描述要查找的源代码结构 |
+| semantic filtering | 在文本搜索和结构化匹配候选结果上，使用 XGo 语义信息确认 resolved symbol、类型、接收者或 classfile 语义 |
+| capture | 结构化匹配中命名的子树或子片段，带有源代码范围和文本 |
+| coverage | 一次搜索实际覆盖了哪些项目源、哪些文件、哪些语言和哪些索引状态 |
+| search index | 从项目源派生出的可搜索状态，不是项目源码的权威存储 |
+| reindex | 因源内容变化、文件选择策略变化、解析器变化、matcher 变化或索引格式变化而重新生成派生索引 |
+
+## 能力边界
+
+Code Search 的后端能力应该保持通用。它接收来源范围、项目过滤、文件过滤、文本查询、结构化 matcher 和执行控制，返回匹配结果、诊断、覆盖信息和可选聚合摘要。具体客户端可以在此基础上组织出不同工作流，例如 admin 排查、项目迁移评估、框架兼容性审查或未来的代码迁移辅助。
+
+Code Search 不应把某个工作流固化为后端契约。即使第一批实际需求来自维护 spx 这类 XBuilder 支持的 XGo classfile framework，后端 API 也不应该出现只能表达某个 framework 报告的结构。framework 相关能力应作为文件角色、语言、结构化 matcher 或未来语义过滤的组合出现。
+
+Code Search 与社区项目搜索不同。社区项目搜索面向作品发现，查询对象是项目展示名、作者、可见性、排序和社区行为。Code Search 查询对象是项目源内的源码和选定项目元数据，结果需要具体文件、范围、snippet、captures、诊断和覆盖状态。
+
+Code Search 与 XGo 编译器、XGo LSP 和 Tree-sitter grammar 的边界也需要清晰。Code Search 负责编排索引、检索、匹配、授权、结果和可观测状态。XGo 编译器或语言服务负责语义事实。`tree-sitter-xgo` 如果存在，负责提供 XGo 源码的 concrete syntax tree 和 Tree-sitter 生态兼容层。
+
+## 系统边界
+
+Code Search 处在 XBuilder 项目模型、项目文件存储、后台索引、查询 API 和客户端体验之间。
+
+XBuilder 项目和发布仍然是源码来源的权威。`Project.files` 表示当前项目文件集合，`ProjectRelease.files` 表示发布快照文件集合。Code Search 索引只是这些来源的派生数据。
+
+Code Search API 是查询和管理派生索引的权威入口。它负责授权、来源范围、过滤、matcher 校验、结果形态、覆盖信息、审计边界和完整源码读取边界。外部索引后端、对象存储、解析器或 matcher 都不应该成为客户端直接依赖的公共契约。
+
+后台索引器负责从项目源读取 file collection，解析 universal URL，识别可搜索文件，提取可索引文本和必要元数据，运行语法解析或语义分析，并写入可搜索状态。索引器可以使用后台任务执行，但任务执行状态不应成为项目源是否可搜索的唯一权威。
+
+搜索索引负责加速检索，不负责最终授权判断。PostgreSQL、`pg_trgm`、Zoekt、Tantivy 或 OpenSearch 都可以作为实现候选，但 API 不应暴露具体索引引擎、引擎查询语言或引擎评分模型。
+
+XBuilder 管理台是第一客户端。它应该作为通用 Code Search 能力上的操作界面，而不是把后端能力变成 admin-only 或 spx-only。
+
+## 可搜索语料
+
+Code Search 的语料来自 XBuilder 项目源。项目源至少包括：
+
+- latest project content，来自 `Project.files`
+- release snapshot，来自 `ProjectRelease.files`
+
+latest project content 是可变来源，保存项目后可能变化。release snapshot 是发布时复制出的来源，应该按发布快照理解。相同项目、相同路径在 latest project content 和不同 release snapshot 中可能代表不同内容。
+
+一次查询必须显式声明或由 API 明确默认 source scope。结果也必须带回 source identity，不能只返回 owner、project 和 file path。否则调用方无法判断命中来自当前项目内容、某个发布快照，还是某个已经被后续保存覆盖的旧内容。
+
+文件内容解析必须通过 universal URL 处理。一个 `data:` URL 可能直接包含文本源码或 JSON 元数据，一个 `kodo://` URL 可能指向较大的文本文件或二进制资产。索引器不能把存储 scheme 当成语言检测或文件角色判断依据。
+
+对象存储只应该参与索引或重建索引时的内容读取。搜索请求如果已经有足够的索引文本、snippet 和结构化事实，不应该在热路径上反复读取对象存储。
+
+## 文件选择与语言检测
+
+Code Search 应索引用户相关的源码和选定项目元数据，而不是索引项目文件集合中的所有文件。
+
+当前 XBuilder spx 项目的主要代码文件是：
+
+- `main.spx`，表示 project 或 stage 级代码
+- `<sprite>.spx`，表示 sprite 级代码
+
+这些 `.spx` 文件应作为 XGo 语法处理。spx 是 XGo classfile framework，`main.spx` 是 project classfile，其他 sprite `.spx` 是 work classfile。这个角色影响文件元数据和未来语义分析，但不应该要求独立于 XGo 的另一套语法解析器。
+
+现有 Stage 加载逻辑还兼容 `index.spx`、`main.gmx` 和 `index.gmx` 等历史 stage code 路径。是否纳入第一阶段索引是文件选择策略问题。若纳入，应保留原始 file path，并将其识别为 stage code 兼容路径。
+
+已知 XBuilder JSON 文件应该按文件角色分类，而不是因为扩展名是 `.json` 就全部当成代码文件：
+
+- `assets/index.json` 表示项目级配置，如 stage config、zorder、camera、tilemap path 和 runtime settings
+- `assets/sprites/<name>/index.json` 表示 sprite 配置，如物理设置、碰撞形状、造型、动画和动画绑定
+- sound、tilemap 等资源 JSON 表示资源级元数据，如资源路径、声音元数据、tilemap layers 和 decorators
+
+这些 JSON 文件可以用于元数据提取、兼容性检查、迁移评估，以及可选的文本搜索或 JSON 结构化搜索。它们不应被当作 XGo 源码，也不应只按扩展名粗暴纳入。
+
+生成的内部文件默认不应纳入普通 Code Search，例如 `builder-ai-description.md` 和 `builder-ai-description.hash`。图片、音频、视频等二进制资产也不属于代码语料。
+
+索引器应保存明确的检测结果。检测结果至少应表达文件是否被纳入普通搜索、是否可文本搜索、是否可结构化搜索、检测语言、文件角色、使用的 parser 或 grammar，以及解析或检测诊断。
+
+语言检测和文件角色判断不属于 Tree-sitter grammar 的职责。`tree-sitter-xgo` 应只负责解析 XGo 源码语法。`main.spx` 是否是 project classfile、某个 `.spx` 是否是 sprite classfile、某个 JSON 是否应索引，都属于 XBuilder 项目模型和文件选择策略。
+
+## 搜索语义
+
+Code Search 的搜索语义分为三层：
+
+1. 文本搜索
+2. 语法级结构化搜索
+3. 未来的语义过滤
+
+文本搜索用于在源码文本和选定元数据文本中查找字面量、标识符、selector、package path、字符串字面量、注释或 JSON key。它应该是代码导向、确定性、可解释的搜索，不应使用 stemming、synonym expansion、embedding similarity 或自然语言改写。
+
+文本搜索中的多词行为必须显式。空白不应该悄悄改变为 phrase search、token search、AND、OR 或 fuzzy matching。第一阶段可以把查询作为一个 literal expression。后续如果支持 term query、phrase query、boolean query 或正则搜索，应作为明确模式。
+
+大小写、标识符边界和标点行为也必须显式。`github.com/goplus/spx/v2`、`broadcast`、`Sprite.step`、字符串字面量和 JSON key 这类代码文本不能依赖搜索引擎默认 analyzer 意外决定匹配语义。
+
+结构化搜索用于通过代码形态查找源代码结构。它应该匹配语法树中的 node 或 subtree，并返回源代码范围、captures、snippet 和诊断。第一阶段的结构化搜索应保持语法级，不应声称已经理解 resolved symbol、类型、隐式 receiver、framework package lookup 或 classfile lowering。
+
+面向人编写的结构化查询可以参考 ast-grep-like pattern。它比原始 Tree-sitter query 更接近代码写法，适合 admin 页面中的查询编辑。第一阶段不需要承诺完整 ast-grep 兼容，除非实现确实使用 ast-grep。一个明确记录的子集是可以接受的，前提是未支持能力必须被校验拒绝，而不是静默忽略。
+
+结构化查询的有用子集可以包含：
+
+- `pattern`，用于代码形态匹配
+- `context` 和 `selector`，用于需要解析上下文的片段
+- metavariables 和 captures
+- capture constraints，如 node kind、text regex 和 nested pattern
+- 位于 matcher 外部的 source scope、project filter、file filter、language 和 path 过滤
+
+Tree-sitter query 仍然是重要的低层参考。它可以描述 node kind、field、capture、anonymous node、wildcard 和 parser error node。它适合内部调试、高级能力或实现层，但作为 admin 首选查询格式会偏语法树细节。
+
+语义过滤是结构化候选之后的可选层。它用 XGo 语义信息确认某个 capture 是否解析到特定 package symbol、type、method、field、receiver 或 framework-provided member。语义过滤结果应暴露状态，如 syntax-only、semantic-confirmed、semantic-unavailable、semantic-failed 或 ambiguous。
+
+语义过滤不属于第一阶段语法级结构化搜索的必需条件。即使语义层暂不可用，Code Search 也应能返回 syntax-level 匹配，并清楚标识这些结果不是语义精确结果。
+
+## `tree-sitter-xgo` 与 XGo 语义
+
+如果第一阶段包含语法级结构化搜索，`tree-sitter-xgo` 值得作为 XGo 官方语法工件评估，而不是只作为 XBuilder 后端内部实现细节。
+
+Tree-sitter grammar 将语言的 concrete source syntax 暴露给多种工具。它可以支持语法树查询、语法高亮、locals、injections、tags、浏览器侧 Wasm 解析、Tree-sitter 编辑器生态和 ast-grep custom language。对于 Code Search，它可以提供稳定的语法树基础，也可以让 admin 页面获得更好的本地校验和预览体验。
+
+基于 XGo classfile 语法，一个 `tree-sitter-xgo` 应足够覆盖语法层。XGo classfile frameworks 共享同一类源代码形态。framework 差异来自文件分类、registry metadata、base class、work class、隐式 receiver 查找、生成方法和 project/work assembly。这些是语义和 lowering 问题，不应拆成每个 framework 一套 grammar。
+
+`tree-sitter-xgo` 应覆盖 XGo 和 classfile 的共享源码语法，包括普通 XGo 文件、XGo classfile、省略 package clause 的 classfile、classfile declaration 之前的 imports、top-level statements、field declarations、tags，以及 classfile-only static method declaration，如 `func .Name(...)`。
+
+`tree-sitter-xgo` 不应编码 framework-specific 或语义行为。例如它不应判断一个文件是 project classfile 还是 work classfile，不应判断某个 class extension 属于哪个 framework registration，不应判断 base class 或 work class，不应判断某个 identifier 是否通过隐式 receiver 或 framework package lookup 解析，也不应判断某个匹配是否解析到特定 package symbol。
+
+XGo 语义分析仍然是语义事实的来源。spx 项目的 `.spx` 文件不是孤立脚本。它们的含义依赖 classfile framework metadata、自动导入、生成成员、project/work 组合和 workspace 文件集合。Code Search 的 resolved symbol 分析应该使用与 XBuilder editor-side language service 一致的项目级上下文，而不是孤立解析某个 `.spx` 文件。
+
+## 查询模型与 API 边界
+
+Code Search 的 API 不应把文本搜索、结构化 matcher、路径过滤、项目过滤、来源范围和未来语义过滤压缩进一个自由字符串。请求结构应该把这些关注点分开，让校验、授权、索引、执行和 UI 反馈都可解释。
+
+请求模型应包含以下逻辑部分：
+
+- source scope，如 latest project content、release snapshot 或二者组合
+- project filters，如 owner、project identity、project type、visibility、project full name 或 release full name
+- file filters，如 path、language、file role、text-searchable status 或 structurally-searchable status
+- text query，用于 literal、identifier-oriented、phrase、boolean 或 regex 搜索
+- structural matcher，用于语法级结构化匹配
+- future semantic filters，用于 resolved symbol 或 XGo 语义过滤
+- execution controls，如 result limit、pagination、timeout、partial result policy 和 execution mode
+
+结构化 matcher 需要独立 validation 能力。调用方应该能在执行宽范围搜索之前校验 pattern、unsupported features、parser availability、language mismatch 和 file role mismatch。校验诊断应该足够让 admin 页面给出快速反馈。
+
+执行模式需要明确。简单文本搜索和窄范围结构化搜索可以同步返回分页结果。跨所有用户项目的宽范围结构化搜索可能需要超时、部分结果、异步执行或更严格的过滤要求。API 不应把未覆盖、超时或失败包装成普通空结果页。
+
+API 不应暴露底层引擎是否使用 PostgreSQL、Zoekt、Tantivy、OpenSearch、Tree-sitter query 或 ast-grep。公共契约应暴露 Code Search 概念，如 source identity、match range、captures、diagnostics、coverage、counts、grouping 和 freshness。
+
+## 结果模型
+
+Code Search 的核心结果应该是 match-oriented。一个 result item 表示某个项目源中某个文件里的一个具体匹配，而不是只表示一个项目或一个文件。
+
+一个匹配结果应包含：
+
+- source identity，包括 source kind、project identity 和 release identity
+- file path、file role、language 和 parser 或 matcher 信息
+- matched range，包括行列或可映射到源码的范围
+- snippet 和 matched text
+- captures，包括 capture name、range 和 text
+- match kind，如 text match 或 structural match
+- semantic status，如果语义过滤或语义标注参与执行
+- freshness 和 coverage 信息，如 indexed time、source hash、index format version、stale status、parse diagnostics 或 matcher diagnostics
+
+默认结果不应返回完整 source file、完整 file collection、universal URL 或 signed URL。完整源码读取应该是单独授权的操作，且需要清楚的审计边界。
+
+结果需要支持 grouping 和 counts，但 grouping 不应替代核心匹配结果。客户端可能按 project、owner、file、source kind、language、file role、match kind、parser status 或 semantic status 分组。后端可以返回通用 summaries，但不应把某个工作流的聚合方式固化成唯一结果。
+
+计数语义必须明确。match count、file count、source count、project count 和 owner count 不是同一个数字。一个项目可以有多个 source，一个 source 可以有多个文件，一个文件可以有多个匹配。release snapshot 是否纳入、是否与 latest project content 去重，也会改变 project count。
+
+分页结果中的 totals 必须说明含义。普通 XBuilder list API 的 `ByPage<T>` 使用 exact `total`，但 Code Search 对宽范围结构化查询、部分执行、超时或外部索引后端不一定总能提供完整精确 total。API 应区分 exact、approximate、unavailable 和 incomplete。
+
+没有匹配、没有覆盖、索引陈旧、索引失败、结构化 parser 不可用、文件被策略排除，是不同状态。结果和 summary 必须让调用方能区分这些状态。
+
+## 索引与维护
+
+Code Search 索引是派生数据。项目源码的 source of truth 仍然是 `Project.files` 和 `ProjectRelease.files`。
+
+搜索请求应该读取已索引的可搜索状态，而不是在请求路径上扫描所有 project files、解析所有 universal URL 或重建源码索引。项目保存、发布创建和普通用户编辑流程也不应等待解析、匹配或索引更新完成。
+
+索引状态应由 Code Search 域拥有。它需要记录哪个 source 被索引、哪个 file collection 或 file content 生成了索引、哪个索引逻辑版本生成了索引，以及当前状态是 current、stale、failed 还是 in progress。
+
+索引维护至少包含三类流程：
+
+1. 初始 backfill，用于既有 latest project sources 和选定 release sources
+2. 增量维护，用于 source content 变化、release 创建、删除、rename 或 visibility 变化
+3. 重建索引，用于 file selection policy、language detection、parser、matcher 或 index schema 变化
+
+内容变化需要重新索引。metadata-only 变化可能只需要更新 source identity、authorization metadata 或 visibility metadata。parser、matcher 或 file selection policy 变化即使没有源文件变化，也可能要求 reindex。
+
+索引必须是幂等且版本感知的。索引结果应绑定 source identity、source content hash 或 version，以及 index format version。如果更新的 source content 或更新的 index format 已经存在，旧任务结果不能覆盖当前可搜索状态。
+
+手动 reindex 应作为运维控制存在。它应该触发后台索引工作，而不是在请求内联执行。reindex 可以按单个 project source、owner、project scope、failed records、stale records 或旧 index format version 定位。
+
+搜索执行和 reindex 请求是不同操作。搜索请求询问当前可搜索状态中的匹配。reindex 请求要求后端刷新派生数据。搜索应在索引或重建进行中继续可用，并通过 coverage 信息说明哪些 source 当前未索引、陈旧、失败或仍在索引中。
+
+## 权限、隐私与审计
+
+全局项目代码搜索是对用户创建内容的特权读取路径。它不是普通项目元数据查询。
+
+XBuilder 当前项目访问模型包含 owner 和 visibility。公开项目可被非 owner 读取，私有项目通常要求 owner。release snapshot 没有独立 visibility，应跟随所属项目。admin 级 Code Search 如果纳入私有项目，就引入了跨用户读取源码的新路径。
+
+权限边界必须显式。能够访问 `/admin/*` 或管理 Account 资源，不应自动获得 Code Search 权限。Code Search 需要独立 capability，或明确映射到某个经过文档定义的 capability。
+
+搜索索引与源文件具有相同隐私等级。索引文本、snippet、captures、parse tree 和 extracted facts 都可能包含用户源码或项目元数据。如果使用外部搜索后端，该后端不能成为绕过后端授权和审计的第二读取路径。
+
+授权应在搜索执行和结果详情读取时执行，而不只是在建立索引时执行。索引中的 visibility 和 owner metadata 可以用于过滤，但最终权限判断仍应由后端负责。visibility 变化、项目删除和角色变化必须在索引清理完成前也能影响可见性。
+
+搜索结果默认不应暴露 raw file collection、universal URL、signed URL 或完整源码。`data:` URL 可以直接包含完整文本，`kodo://` URL 可以指向用户内容。默认结果应返回 source identity、file path、range、snippet、captures 和 diagnostics。
+
+Code Search 应写入 admin audit logs。审计记录应避免保存完整源码、完整 snippet、captures、signed URL 或用户内容。适合审计的字段包括 source scope、visibility scope、language、matcher mode、query hash、result count、是否包含 private project content、是否 partial、duration 和 actor。
+
+普通用户可见搜索和 privileged admin search 应区分。后端能力可以通用，但实际 searchable corpus 必须来自调用者的 authorization context。普通用户可能只能搜索自己的项目和公开项目，admin workflow 才能在具备 capability 和审计的前提下搜索更广范围。
+
+## Admin 体验
+
+第一个客户端可以是 XBuilder 管理台页面。该页面应是通用 Code Search 能力上的工具界面，不是 spx 专用报告页面。
+
+现有 `/admin/*` 页面是 capability-gated 的操作页面，通常包含 URL-backed filters、pagination、refresh、loading、error states、table/detail navigation 和权限提示。Code Search 管理台页面应沿用这种操作台形态，但查询界面会比普通资源列表更复杂。
+
+管理台需要组合结构化请求，而不是只提供一个搜索框。合理控件包括：
+
+- source scope 选择
+- owner、project、visibility 和 project type 过滤
+- file path、language、file role 和 searchable status 过滤
+- text query 输入和模式选择
+- structural matcher 编辑器
+- validation 按钮或自动校验反馈
+- result limit、timeout 和 partial result 设置
+- grouping 和 summary 展示
+
+轻量状态应该写入 URL，例如 filters、source scope、pagination 和 selected mode。长文本或多行结构化 pattern 不一定要完整塞进 query parameters。可复现性重要，但不应扭曲请求模型。
+
+结构化 matcher 需要先验证再执行宽范围查询。页面应展示 pattern diagnostics、unsupported features、parser availability 和 file-language mismatch。`tree-sitter-xgo` 或 matcher 不可用时，应作为 parser 或 matcher coverage 显示，而不是表现成没有结果。
+
+如果浏览器侧 Tree-sitter-compatible XGo grammar 可用，客户端可以提供本地解析、query validation 和 match preview。这只是编辑体验辅助。后端校验仍然是权威，因为真实搜索运行在后端索引、后端 parser version、matcher version、文件选择策略和授权上下文上。
+
+结果检查是管理台体验的核心。每个结果都应能作为一个 source file 中的一个 match 被查看，带有 project identity、source kind、file path、matched range、snippet、captures、freshness state 和 diagnostics。管理台可以按 project 或 file 分组展示，但后端核心结果不应只返回 project-level counts。
+
+导航必须 source-aware。latest project content 的命中可以链接到当前项目或编辑器上下文。release snapshot 的命中不能被呈现为来自可变的 latest project files。结果需要足够的 source identity，让客户端决定链接到项目页、编辑器、release history 或只读源码预览。
+
+## 生态参考
+
+Code Search 应贴近业内成熟代码搜索和结构化搜索约定，但不需要复制任何单一产品。
+
+GitHub Code Search 和 Sourcegraph Code Search 都将查询文本与 repo、language、path、symbol、content、visibility、count 或 timeout 等过滤条件区分开。这支持 Code Search 将 source scope、project filters、file filters、text query、structural matcher 和 execution controls 分开建模，而不是复制单字符串查询语言。
+
+GitHub 和 Sourcegraph 的文本搜索也说明，代码搜索应该保持解释性。正则、boolean 行为、path 过滤、language 过滤、大小写和结果限制都应明确，而不是依赖自然语言检索或 embedding similarity。
+
+ast-grep 和 Semgrep 是人类编写结构化查询的重要参考。二者都使用 code-like patterns 和 metavariables。Code Search 可以采用 ast-grep-like 子集作为结构化查询风格，但不应把 lint、severity、message、fix、taint 或 rule pack 引入第一阶段搜索契约。
+
+Sourcegraph Structural Search 是性能边界的提醒。跨全部项目的无文本锚点结构化查询应该被视为独立执行形态，需要 filters、limits、partial coverage、timeout 或 asynchronous execution。
+
+CodeQL 代表更重的语义分析模型。它依赖语言特定 database、AST、data flow、control flow、name binding 和 type information。Code Search 第一阶段不应直接走 CodeQL-like 路线，但可以保留未来 semantic facts 和 resolved symbol filtering 的接口空间。
+
+Zoekt、Tantivy、OpenSearch 和 PostgreSQL `pg_trgm` 是实现参考，而不是公共 API 参考。它们可以影响索引实现，但不应该决定 Code Search 的公共概念、结果模型或权限边界。
+
+## 后续演进方向
+
+第一阶段应同时包含文本搜索和语法级结构化搜索的最小可用能力。只有文本搜索会让许多代码形态问题难以表达，直接进入 resolved symbol 级语义搜索又会过早绑定 XGo 编译和 classfile 语义。
+
+语法级结构化搜索应优先围绕 XGo 语法和 `.spx` 文件落地。`tree-sitter-xgo` 如果成熟，可以作为长期语法树基础。如果它尚未成熟，后端实现可以采用更小的内部结构化 matcher 或其他可替换实现，但公共契约仍应保持语法级 matcher 的语义。
+
+语义过滤应作为后续层接入。它用于确认 resolved package、type、method、field、receiver、implicit receiver 或 framework-provided member。语义事实应来自 XGo 拥有的编译器、语言服务或语义分析组件，而不是 Tree-sitter grammar。
+
+索引后端应可替换。小规模或第一阶段可以由 PostgreSQL 管理 metadata、freshness、权限信息、索引状态和部分文本检索。随着数据量和查询复杂度增长，可以评估 Zoekt、Tantivy 或 OpenSearch。API 不应因后端替换而改变核心语义。
+
+未来可以在 Code Search 结果之上构建更高层工作流，例如迁移候选列表、批量 review queue、framework 兼容性审查或代码迁移辅助。自动改写或全局代码编辑属于后续能力，不属于第一阶段 Code Search 契约。
+
+## 待收敛事项
+
+以下事项需要在后续 OpenAPI、后端实现或阶段计划中收敛：
+
+- 第一阶段默认 source scope 是 latest project content、release snapshot 还是两者都支持
+- 第一阶段具体纳入哪些 JSON file roles
+- 历史 stage code 路径是否进入第一阶段索引
+- 文本搜索的第一批模式是 literal、identifier-oriented、phrase、boolean 还是 regex
+- 结构化 matcher 的第一批 ast-grep-like 子集范围
+- `tree-sitter-xgo` 的成熟度与后端结构化搜索时间线如何协调
+- 索引是否存储完整 searchable text、snippet cache、parse tree、extracted facts 或仅存引用
+- 初始实现使用 PostgreSQL `pg_trgm` 还是引入独立搜索索引
+- 宽范围结构化查询使用同步 partial result、异步执行，还是要求更强过滤条件
+- Code Search admin capability 的命名、授权映射和审计字段
+
+这些事项不改变本文档的核心边界。Code Search 应保持通用、分层、source-aware、match-oriented、可审计，并且不把某个 framework 或某个 admin 工作流编码进后端能力。
+
+## 参考资料
+
+- [goplus/builder#3331](https://github.com/goplus/builder/issues/3331)
+- [Tree-sitter](https://tree-sitter.github.io/tree-sitter/)
+- [Tree-sitter query syntax](https://tree-sitter.github.io/tree-sitter/using-parsers/queries/1-syntax.html)
+- [ast-grep pattern syntax](https://ast-grep.github.io/guide/pattern-syntax.html)
+- [Semgrep pattern syntax](https://docs.semgrep.dev/writing-rules/pattern-syntax)
+- [GitHub Code Search syntax](https://docs.github.com/en/search-github/github-code-search/understanding-github-code-search-syntax)
+- [Sourcegraph Code Search queries](https://sourcegraph.com/docs/code-search/queries)
+- [Sourcegraph Structural Search](https://sourcegraph.com/docs/code-search/types/structural)
+- [CodeQL overview](https://codeql.github.com/docs/codeql-overview/about-codeql/)
+- [PostgreSQL `pg_trgm`](https://www.postgresql.org/docs/current/pgtrgm.html)
+- [Zoekt](https://github.com/sourcegraph/zoekt)
+- [Tantivy](https://github.com/quickwit-oss/tantivy)
+- [OpenSearch full-text queries](https://docs.opensearch.org/latest/query-dsl/full-text/)