Uh oh!
There was an error while loading. Please reload this page.
feat(search): 通用拼音搜索 — locale 开关 + 名称字段 __search 拼音伴随列(#2486, ADR-0097) - #3027
Merged
Conversation
…on column (#2486) Implements ADR-0097 (extends ADR-0061 Tier-1 $search, purely additive): - OS_SEARCH_PINYIN_ENABLED platform switch (resolveSearchPinyinEnabled in @objectstack/types): explicit env wins; when unset the CLI boot path derives the default from the stack's configured locales (any zh-* -> on) and stamps the decision back into the env so the per-engine SchemaRegistry and the plugin gate read the same answer. - Compile-time materialization: SchemaRegistry.registerObject provisions a hidden `__search` companion column (hidden/readonly/system/searchable:false, indexed) for the ADR-0079 display/name field, right after provisionPrimary. FLS-restricted (requiredPermissions), hidden, secret/virtual source fields never feed the companion (ADR-0061 D5, fail-closed). - New @objectstack/plugin-pinyin-search: global beforeInsert/beforeUpdate hooks fill the blob (full pinyin + initials, "zhangwei zw") via lazy-loaded pinyin-pro only when the source field is in the write; paged idempotent boot backfill on kernel:bootstrapped plus rebuildSearchCompanion reconcile entry for hook-bypassing writes. - Query-time: expandSearchToFilter ORs { __search: { $contains: term } } into each latin term's clause when the column exists; resolveSearchFields is unchanged and the companion is unreachable via $searchFields overrides. CJK terms skip the clause. Zero driver changes. Verified end-to-end on the showcase app (zh-CN locale auto-enables): $search=zhangwei / zw / 张 all recall 张伟; latin and CJK source-column search behavior unchanged. Tests: objectql 880 passed (29 new), types 14, cli 509, plugin-pinyin-search 14. Closes#2486 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RMugRriiNv3nsnmLczfhuY
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📓 Docs Drift CheckThis PR changes 4 package(s): 27 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
…version group Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RMugRriiNv3nsnmLczfhuY
os-zhuang
marked this pull request as ready for review
July 16, 2026 07:12
Uh oh!
There was an error while loading. Please reload this page.
os-zhuang added a commit
that referenced
this pull request
Jul 16, 2026
…strable out of the box (#3034) Follow-ups to the merged pinyin-search feature (ADR-0097, PR #3027): - environment-variables.mdx: new "Search" section documenting OS_SEARCH_PINYIN_ENABLED (locale-derived default, explicit override, what it gates). - queries.mdx: "Pinyin recall" subsection under Full-Text Search. - showcase seed: CJK-named account (华宁科技) and contacts (张伟/王芳/李雷) so the auto-enabled pinyin search is demonstrable out of the box. Verified on a fresh showcase boot: $search=zhangwei/zw/wf/huaning/hnkj all recall the seeded CJK records. Refs #2486 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RMugRriiNv3nsnmLczfhuY
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
实现 #2486:在 ADR-0061 现有
$search之上,为"输拼音"补一条名称字段伴随列,纯加性 — 其它搜索行为一律不动。方案记录为 ADR-0097。实现(按 issue 组件清单)
平台开关(locale 推导默认值)
@objectstack/types新增resolveSearchPinyinEnabled({ locales? }):显式OS_SEARCH_PINYIN_ENABLED永远优先;未设置时由配置 locale 推导(挂任意zh-*即默认开)。serve是唯一看得到 stacki18n配置的地方 — 在那里解析一次并把结果回写进环境变量,之后每个消费方(各 engine 的SchemaRegistry、插件门控)通过无参形式读到同一个答案。serve自动把pinyin-search能力加入requires并加载插件(与mcp的 default-on 模式同形态)。无字段级元数据,不存在 ADR-0049 的死标记。编译期物化(1 列 / 对象)
packages/objectql/src/search-companion.ts(新):provisionSearchCompanion在SchemaRegistry.registerObject里、provisionPrimary之后运行 — 只对 ADR-0079 解析出的 display/name 字段挂隐藏列__search(hidden/readonly/system/searchable:false/index:true),migration 走 driversyncSchema正常加列(ADR-0045 加性物化)。requiredPermissions(FLS)、hidden、secret/虚拟类型的源字段一律不进伴随列 — 在唯一的 eligibility gate 强制,不靠作者记得。plugin-pinyin-search(纯 hook,对齐 plugin-sharing primary-BU 投影先例)beforeInsert/beforeUpdatehook:只在源字段出现在本次写入时重算(无写放大);pinyin-pro懒加载(开关关/非中文部署零成本);全拼+首字母同列存储("张伟"→"zhangwei zw");改名为非中文时清空 blob(无 stale 召回)。kernel:bootstrapped分页幂等回填 +rebuildSearchCompanion对账/重建入口(绕过 hook 的 bulk import / 迁移直写)。查询期接入(纯加性)
expandSearchToFilter:对象存在__search列时,每个拉丁 term 额外 OR{ __search: { $contains: term } };中文 term 跳过(直打源列)。resolveSearchFields原样不动;$searchFieldsoverride 与 allowed 求交后天然够不到伴随列(已测)。$or+$contains所有驱动已支持,零驱动改动。通用化接缝
SEARCH_COMPANION_NORMALIZERS = ['pinyin']— 只实现 pinyin,简繁/全半角/重音折叠共用同一列与机制。验证
showcase 真机端到端(
pnpm dev --fresh,zh-CN locale 自动点亮,插件出现在加载列表):$search=zhangwei(全拼)$search=zw(首字母)$search=张(中文)$search=ada(拉丁原文)$searchFields=__search越权__search被 hidden 过滤,不出现 ✓说明:
__search会随单记录默认响应返回(null或拼音 blob)— 与现有 hidden 系统列(organization_id等)的平台行为完全一致,且值只派生自人人可读的名称字段,无新信息面。测试:objectql 880(新增 29:eligibility gate / provisioning / registry 集成 / 查询期 OR / override 不可达)、types 14、cli 509、plugin-pinyin-search 14(真实 pinyin-pro)全绿。开关默认关 → 全套既有测试即"纯加性"证明。
范围 / 非目标(同 issue)
相关性排序 / typo 容错 / 整词防噪属 Tier-2;不物化非名称字段、不引入 search blob、不改
searchableFields;不依赖数据库分词器,方言/引擎无关。多音字用 pinyin-pro 默认启发式(P2 字典覆盖留 issue 跟踪)。下游:objectstack-ai/objectui#2112 分层选人器 picker 仅发
$search,拼音透明点亮,无需 UI 改动。Closes#2486
🤖 Generated with Claude Code
https://claude.ai/code/session_01RMugRriiNv3nsnmLczfhuY
Generated by Claude Code