[muzimu217]

PR 1 of the split agreed in #502 — Index infrastructure only, nothing else. Based on the latest main, one clean branch.

What's in

• FTS5 store under <data>/index/index.db (trigram tokenizer, fixed budgets: 50k files / 1MB per file / 2GB total), deliberately separate from pi.sqlite; integrity or schema failure quarantines the old file and recreates an empty store
• Lifecycle RPCs index.status / index.rebuild / index.clear, workspace-root-scoped (INDEX_ROOT_OUTSIDE_WORKSPACE otherwise), metadata only — never file contents; rebuild/clear write an audit entry
• Index page in the existing Workspace settings group: one health card (status / file count / size / unreadable count / last update), rebuild & clear actions, a build-progress line while building, empty and error states
• One switch, indexGrepBoost, default off. Turned on, it indexes newly opened workspaces in the background (workspace.set stays fast; the health card polls while building). Turning it on arms the current workspace immediately
• Opening the store never blocks host startup — a failed open degrades to a disabled store and the RPCs report unavailable
• i18n ×8, spec updates (en/zh) and E2E coverage for exactly this surface

What's deliberately out (per the split in #502)

• Grep is untouched. tools/mod.rs has zero changes; tools execute exactly as before whether or not an index exists. The fast path + freshness changes are PR 2, to be reviewed on "does it ever change Grep's answer".
• No workspace-watch watcher, no mark_stale wiring, no stats surface. The three stats leftovers named in feat(settings): fold the workspace index into the Workspace group #502 (stats.rs, stats-real-rpc-reconcile.mjs, idx_turns_started) are not present — this branch never carried them.

The two blockers named in #502

• Conflicts against main (SettingsPage.tsx, 06-settings-ia.md): resolved by starting from the current main instead of stacking.
• workspace_set_auto_indexes… wall-clock polling: the background build's join handle is now registered on the app state (index_builds), and the test awaits that handle directly, then asserts the settled status. No wall-clock polling. (For what it's worth: the polling version was also hiding a real platform race — watcher events landing mid-build flip the root to stale, which the test then never sees become fresh. That race belongs to PR 2's surface; PR 1 has no watcher at all.)

Verification

• cargo test -p host-core --locked: 549 passed / 0 failed (incl. new RPC tests: switch defaults + type validation, auto-index gated on the switch via the awaited handle, rebuild/clear audit, store self-healing, budget, multi-root scoping)
• cargo fmt --check clean; cargo clippy -p host-core -- -D warnings clean for every file this PR touches
• desktop suite 2465 passed / 0 failed; i18n catalogs 25 passed (key sets equal ×8)
• pnpm docs:check: 487 pages en/zh paired; architecture budget passed
• E2E: pnpm test:e2e:index → PASS E2E-INDEX-status-rebuild-clear
  • E2E: NOT RUN (full desktop UI suites)
  • Reason: this PR's E2E surface is the RPC lifecycle, which is automated above; UI-side scenarios are documented in the e2e plan
  • Alternative validation: desktop unit tests assert the Index page wiring, switch gating and locale keys; E2E-INDEX-settings-health-card documented as pending UI automation
  • Remaining risk: none known beyond the documented UI-automation gap

Real-workspace measurement (details in the comments)

Driven the shipped binary (cc726590) over stdio RPC against a real checkout of this repository (64k files incl. node_modules; isolated PI_DESKTOP_DATA_DIR):

• workspace.set with the switch off: 0.6 ms, zero index rows — no cost while off
• switch on: 2.6 ms to return; background build lands fresh in 3.0 s — 1,644 source text files / 19.2 MB, 0 errors (node_modules, target/, build outputs correctly excluded)
• foreground index.rebuild: 5.7 s; steady-state index.status latency 0.5–0.7 ms
• index.db: 115.5 MB (~6× content: FTS5 trigram postings + stored bodies; within the 2 GB budget — a contentless-FTS follow-up can shrink this substantially)

Note on pre-existing main breakage (not from this PR)

Typecheck and clippy each currently fail on untouched files from today's main, reproducible on pristine upstream/main (7a59a25) with the same commands:

• pnpm --filter @pi-desktop/desktop typecheck → electron/main/user-login-path.ts(28,74): TS2345 (from 574c78a; the JS job on the fix(desktop): classify crash dumps and keep them in the data directory #689 merge commit already shows failure)
• cargo clippy -p host-core -- -D warnings → user_skills.rs(921): useless_format

I left both alone to keep this PR single-purpose — happy to send a one-line fix separately if useful.

Closes nothing; part of the #502 split (PR 2: Grep fast path + freshness, PR 3: stats RPCs).

[muzimu217]

为方便 review，补一份实测数据和一份diff 导航。数据全部来自本 PR 的交付二进制（cc726590）+ 一份本仓库的真实检出（含 node_modules 约 4.9 万文件、构建产物等共 6.4 万文件，隔离的 PI_DESKTOP_DATA_DIR，不触碰真实数据）。

实测（真实工作区，stdio RPC 直驱）

操作	结果
workspace.set（开关关，默认态）	0.6 ms 返回；index.status 为空——关时零索引开销
settings.set 打开开关	2.6 ms 返回，后台构建启动
后台构建 → fresh	3.0 s（轮询粒度 200ms）：1,644 个源码文本文件 / 19.2 MB 内容，0 错误；node_modules、target/、构建产物被 ignore 口径正确排除
index.rebuild 前台全量	5.7 s（同规模）
index.status 稳态延迟	0.5–0.7 ms（×5 采样）
index.clear	2.3 s，清后状态为空
index.db 体积	115.5 MB

两点如实说明：

• 体积比：19.2 MB 内容 → 115.5 MB 存储（约 6×）。这是 FTS5 trigram 倒排 + 正文全存的已知特征，在 2 GB 总预算内；后续把 FTS 换成 contentless 表（只留倒排、不存正文）可以显著压下来，属于独立的后续改动，不混进本 PR。
• 可见集口径：健康卡的「已索引文件」是 ingest 成功的文本文件数；可见但未 ingest 的行（二进制、超限）只参与完整性、不进显示，所以 1,644 会小于 find 出来的源码文件数。

diff 导航（44 文件）

核心逻辑集中在两个新文件，其余多为薄接线：

• 存储层（值得细读）：crates/host-core/src/index.rs（状态机、爬取、预算、quarantine 自愈、ensure 幂等）+ index/fts.rs（FTS5 DDL 与读写）
• RPC 层：rpc/mod.rs 的改动只有三块——3 个 index case、workspace.set/settings.set 的开关接线（含 join 句柄注册）、3 条测试；state.rs（store 持有 + 开库失败降级 + index_builds 句柄表）；main.rs 仅一行 mod index;
• 前端：IndexPage.tsx + MetricTile.tsx 为新增；SettingsPage.tsx/settings-search.ts/api.ts/session-ipc.ts 各约 10–20 行接线
• 契约：workspace-index.ts/protocol.ts/errors.ts/types/settings.ts
• 机械面：i18n ×8（键集全等）、docs en/zh、e2e-index.mjs

测试 ↔ 不变量

测试	守护
workspace_set_auto_indexes_only_while_the_switch_is_on	开关关绝不建索引；开后后台构建落 fresh（等 join 句柄，非墙钟轮询）
index_grep_boost_defaults_off_and_rejects_non_booleans	默认关；非布尔补丁被拒
index_rebuild_and_clear_are_audited	两个破坏性操作都写审计
index.rs 内嵌 9 条	路径规范化、预算落 skipped_over_limit、损坏库隔离重建、多 root 命名空间隔离、building 残留自愈、进度只在 building 期出现

对照 #502 裁决清单：FTS5 store ✓ / 三个 lifecycle RPC ✓ / Workspace 组 Index 页 ✓ / 单开关默认关 ✓ / 不接 Grep（tools/mod.rs 零改动）✓ / 开库失败不挡 Host ✓ / stats 三残留不存在 ✓ / 等句柄不碰墙钟 ✓。

---

更新 1 — 与最新 main 的兼容：main 前进到 aad46adb（含 #692/#695/#702/#703/#704）后本 PR 一度 CONFLICTING，已合并解决（三处：settings.css、e2e 汇总表、package.json——均为双方各自新增的样式段/行首条目，两边保留；顺带清掉了本 PR 自己一个无消费者的 CSS 类）。合并后门禁重跑：host 576/0、desktop 2474/0、typecheck 0 错（#692 修好了 user-login-path.ts 的 TS2345，基线比上一版更干净）、i18n 25、docs 490 页、架构预算、cargo fmt --check、E2E-INDEX-status-rebuild-clear 全部通过；PR 现为 MERGEABLE。

更新 2 — 多轮稳定性与查询测试（同一真实工作区，隔离 data dir，合并后二进制 0e7ce522）：

维度	结果
重建确定性	5 轮 index.rebuild，fresh 行逐字节一致（fresh / 1644 文件 / 19.2 MB / 0 错），单轮 5.4–6.1 s
查询稳定性	50 次 index.status：50 次返回 payload 完全相同；延迟 min/P50/P95/max = 0.39 / 0.48 / 0.59 / 0.68 ms
build→clear→build ×3	每轮 cleared=1、重建后 fileCount / indexedBytes 零漂移；clear 后 DB 文件不收缩（SQLite freelist 页复用语义），行数据无残留
构建期间并发查询	rebuild 进行中 20 次 index.status 全部即时应答、0 错误，可观察到 building 态，构建最终落 fresh——查询与构建互不阻塞

[muzimu217]

你好，我们注意到 09-26 生效的贡献范围调整（外部 PR 暂只收 fix/perf，CONTRIBUTING R6.1）。#697 是按您 09-20 在 #502 给出的拆分方案开出的 PR 1（Index 基础设施），分支一直在持续 rebase 最新 main（当前 head ebed5a4c，四项 checks 绿）。

窗口期内我们不想让它占用您的审阅精力，您方便时给一个处置意向即可：

• a) 窗口解除后纳入 review 队列（我们继续把分支保持可合状态）；
• b) 按新政策转成 feature issue、由您排期实现（fork 分支与实测数据可作为参考实现保留）；
• c) 依政策关闭（分支我们自行保留，完全理解）。

另想顺带确认：被拆分取代的 #502 是否可随本裁定一并关闭？其内容已由 #697（PR1）取代，其余部分本就留待后续窗口再议，挂着一个陈旧分支只会给 triage 添噪音。

无论哪种处置我们都配合，一条回复即可，不占您时间。谢谢！

[Tioit-Wang]

Thanks for this — and sorry for the wait, this one has been sitting for a while.

It looks like solid work, and it's close to something we can evaluate properly. The one thing we're missing is visual evidence: since this touches the UI, we can't judge the result from the diff alone.

Could you add two screenshots to the description?

• A full screenshot of the interface, showing the change in its real context — the workspace index settings page and its metric tiles.
• A close-up (cropped) screenshot of the exact spot that changed, so the new elements are clearly visible.

With those attached we can see the actual result and make a confident call on merging.

[muzimu217]

Visual evidence, as requested — and the branch is refreshed.

Screenshots

Rendered from the production SettingsPage / IndexPage components and the production CSS, not a mock. The harness bundles the real components with esbuild and runs them in an isolated Electron window, stubbing only the preload boundary (window.piDesktop.invoke), so the markup and styles below are what ships.

Full interface — the page in its real settings context:

Close-up — the metric tiles that changed:

Fixture values: status=fresh, 12,483 files, 464 MB, last update 12m ago, 1180×860 window, light theme, en locale.

The probe that produced them asserts the DOM rather than only capturing pixels:

pageFound: true, gridFound: true, heading: "Index health"
Status / Ready · Indexed files 12,483 · Indexed size 464 MB · Last updated 12m
gridRect: 817 × 228 px at (315, 167)

These two show the healthy state. The empty state, the failed state, and a live rebuild (progress bar polling once a second) are covered by index-settings.test.mjs, not by these shots — I can add a second pair for those if you want them.

Branch refreshed

The head had drifted 688 commits behind main and had gone CONFLICTING. I rebuilt it as one commit on current main (8a8d56413), keeping the content identical and resolving only the merge points:

• package.json — kept both test:e2e:index and main's newer test:e2e:jev / storage entries.
• packages/shared/src/types.ts — export both worktree.js and workspace-index.js.
• crates/host-core/src/rpc/mod.rs — kept main's response_for alongside this branch's checked_index_root, and merged both import lists.
• docs/spec/04-ux/06-settings-ia.md + zh-CN — took main's current wording (Cloud sync / Remote Hosts are Experimental in all builds) and added Index to the Workspace group.
• docs/spec/06-delivery/04-e2e-test-plan.md — kept the two new E2E-INDEX-* rows and main's E2E-263 row.

Diff is unchanged in substance: 46 files, +3294/−21.

Verification on the rebuilt head (cba17f973)

• cargo test -p host-core index — 27/27 pass (includes index_rebuild_and_clear_are_audited, workspace_set_auto_indexes_only_while_the_switch_is_on).
• cargo test -p host-core — 980 pass, 1 fail. The single failure is data_relocation::tests::relocated_project_memory_remains_readable_through_the_repository, and it fails identically on clean main (verified separately: 0 passed, 1 failed, 964 filtered out) — a pre-existing upstream failure, not caused by this branch.
• node --test test/index-settings.test.mjs test/settings-general.test.mjs — 26/26 pass.
• pnpm build:js — clean.

Happy to split anything you consider too large; the intent here is still the one-thing PR you asked for on #502.

[muzimu217]

One structural thing I should have raised earlier, stated plainly so it does not sit in limbo.

This PR is a feat, and CONTRIBUTING R6.1 (CONTRIBUTING.md:148-170) says external feature PRs are not a delivery path while the window is in force — "Features are planned and delivered by the maintainers here; an unsolicited feat pull request is not a delivery path during this window." So the honest status is: this branch can be technically perfect and still not mergeable under the current policy, and I would rather say that than keep refreshing it indefinitely.

Where it came from. #478 (the workspace-index half of the "Data & Statistics" request) was closed as NOT_PLANNED with the note that the index half is carried by #502 → #697. So this is not an unsolicited idea invented in a PR — it is the continuation of a request you already discussed and a design you already reviewed three times on #502 ("Index 放 Workspace、默认 opt-in、FTS 只缩候选、失败不挡 Host 启动" — all still true here).

What I am asking for is a decision, not a merge. Any of these closes the question, and I will follow it without argument:

1. Accept it as an exception to R6.1 — then I keep it green and it is yours to schedule whenever the batch allows.
2. Take it over as maintainer work — the branch is one squashed commit on current main; you can cherry-pick it or tell me to hand it to whoever owns the area.
3. Decline the feature — say so and I will close feat(host): workspace index infrastructure behind an opt-in switch #697 and feat(settings): fold the workspace index into the Workspace group #502 myself, and the code stays on my fork.

Current state, so the decision is cheap to make:

• Head b3e5b41d5, one commit on main (8a8d56413), MERGEABLE, 0 conflicts.
• Rust host-core format / lint / test — pass (I fixed the rustfmt break I introduced while resolving the rebuild).
• Docs checks, Head contains latest base — pass.
• Trusted extensions Electron E2E — red, but this is the repo-level fix(providers): handle optional client certificate requests #1724 breakage (ci.yml:163 runs the client-certificate probe without xvfb-run); it fails on main itself. Not attributable to this branch.
• cargo test -p host-core index — 27/27 pass. Full cargo test -p host-core — 980 pass, 1 fail, and that one (data_relocation::…relocated_project_memory_remains_readable_through_the_repository) fails identically on clean main.
• node --test test/index-settings.test.mjs test/settings-general.test.mjs — 26/26 pass.
• Screenshots for the UI review are in the comment above.

I have also added a small read-only reviewer tool at scripts/review-gate.mjs in my own workspace (not in this PR) that scores quality and mergeability separately — running it on my own PRs is what surfaced the R6.1 problem clearly enough to write this comment. No action needed on it from you.