sift-light 1.0.0

package/README.md

@@ -0,0 +1,177 @@
+# sift-light
+
+English · [简体中文](README.zh-CN.md)
+
+**sift-light — Evidence-first search for AI agents.**
+
+**A general-purpose local search plugin that helps agents find files, documents, notes, logs and other text material.**
+
+Think of a patient librarian: describe what you need, and it helps locate the shelf, open the relevant page and follow the next lead. A small search brings the passages straight to you. A broad search starts with a map so you can decide where to look first.
+
+## How it helps
+
+### Find a passage without opening every folder
+
+Looking for an error message, a sentence or a name is like giving a librarian a keyword. When there are only a few matches, the plugin returns their text and locations directly, saving repeated file opening and scrolling.
+
+### Start with a map when the collection is large
+
+“Which documents mention refunds?” can produce a lot of material. The plugin first presents matching files and snippets, like marking promising stops on a map. The agent can choose what to open before filling the conversation with entire documents.
+
+### Keep your bookmark for the next question
+
+“Continue from where we stopped” can follow the existing result to its next page. The agent can also open the surrounding text of a match, like returning to a bookmarked passage to read what came before and after it.
+
+### Recover when the remembered wording is not exact
+
+Use `mode: "hybrid"` with one natural-language `query` when a sentence may have been remembered with different wording. Hybrid always runs an exact literal search and the installed local Concept model under one owned request. Exact evidence appears first; semantic candidates are clearly labeled, ranked only by similarity and removed when they overlap an exact match. The initial page shares counts, coverage, source references, one inspection cursor and a compact preview instead of concatenating two complete responses. `conceptLimit` changes only the non-overlapping semantic supplement (default 3, maximum 20); it never displaces literal evidence. The returned matches request opens the same snapshot's complete exact-first pagination without rerunning either search.
+
+Concept ranking covers every UTF-8 passage admitted by the request's documented source budget; it no longer samples a fixed prefix of the scope. Concept and hybrid searches automatically admit up to 2,000 files and process them sequentially in bounded 200-file batches, then merge every batch into one global ranking and one coverage result. Batches share the request's 32 MiB read budget, so raising the file ceiling does not multiply the content budget. Users do not need to plan or continue batches themselves. `maxFilesToParse` remains an optional advanced hard ceiling when a smaller scope is intentional. Passages that exceed the model token window are ranked through overlapping token-safe windows, so later text is not silently discarded. Offline embeddings are cached by content, model revision and chunking revision in a bounded 512 MiB local cache. Repeated content is reused, changed content misses naturally, and cache write or cleanup failures remain visible in the result.
+
+Slow Concept and hybrid requests return within the default five-second wait window with `status: "waiting"` or `"running"`, an `operationId`, progress and an exact `nextRequest` such as `{ "mode": "await", "operationId": "..." }`. Copy that request unchanged: it resumes the same computation and never restarts the query or downgrades to a literal-only result. A final result remains available for stable re-fetch for 10 minutes, with up to 32 terminal results retained per service session, and `mode: "cancel"` stops the owned work and waits for cleanup. Each service session admits at most eight pending operations; an operation has one total deadline controlled by `SIFT_LIGHT_CONCEPT_TIMEOUT_MS` (integer milliseconds from 1000 through 3600000; default 600000) and a 120-second idle continuation lease. A real model, source or resource failure is returned as a failure with its diagnostic. Source generation is re-enumerated and re-verified before publication, so changes refresh the operation and mixed versions are never marked complete. Admission planning counts (`filesEnumerated`, `filesAdmitted`, `filesSkippedEmpty`, `filesUnavailable`, `passagesQueued`, `batchesPlanned`, `batchesCompleted`) stay visible. Empty files are a normal skip and do not mark the result partial.
+
+### Give several search conditions together
+
+“Find files mentioning both the customer and a refund” works like selecting documents with two labels. “Any of these words will do” works like handing over a shortlist. Multiple conditions can be expressed together to reduce repeated searches.
+
+### Choose the drawer you want searched
+
+Ask the agent to restrict a search to one folder when that is the scope you need. If you remember only part of a filename, start by finding the file and then inspect its contents—like narrowing a cabinet down to a shelf and then a document.
+
+Multi-word `files` queries require each word literally in the path; a single abbreviation still supports fuzzy matching. Use `hybrid` or `concept` for business intent. Ordinary content searches retain their default zero-result expansion; use `scope: "strict"` to stay within an explicit path. Expansion is announced before returned evidence.
+
+### Know what has been shown
+
+Long results arrive in pages with a way to continue. When the original material changes, the plugin asks for a fresh check. Like a careful research assistant, it distinguishes the passages already shown from the pages still to come.
+
+A complete snapshot describes match retention, not complete source text. Truncated matching-line excerpts show their limit and an executable `inspectRequest`, which remains usable after the final match page. Follow pagination cursors instead of repeating the query with a different limit.
+In Pi and OMP, the passive session status includes the loaded package version, counts returned new queries, distinguishes complete, partial and unfinished results, and reports non-cancelled failed calls. Cursor and operation continuations do not inflate the new-query count.
+
+Ordinary searches keep repository ignore rules, but now report policy-filtered filesystem coverage instead of calling an absence exhaustive when ignored files exist. Use `mode: "audit"` with named literal `patterns` for one bounded receipt covering declared scope, enumerated/searched/skipped files, ignored-file policy, per-pattern `present`/`absent_with_complete_coverage`/`unknown` findings, and start/end source stability. Set `ignorePolicy: "include"` when an audit must include ignored configuration and generated files; `.git` internals and protected paths remain excluded.
+
+### Discover language capabilities before loading a provider
+
+Use `mode: "capabilities"` with the project root for a compact, names-only inventory. JavaScript, TypeScript and TSX support AST structure, roles, outline, static imports and related-test candidates. Go supports AST structure and roles. Python supports bounded indentation-based outline. Swift and other languages remain available to ordinary content search, filename discovery and source inspection. Capability inventory does not start parsers or the Concept model.
+
+Language-service navigation is out of scope. Asking for `definitions`, `references`, `implementations`, `callers`, `callees`, `dependencies`, `dependents`, `trace` or `impact` fails explicitly, because a text search dressed up as precise navigation would be a worse answer than a clear refusal. No language server runs while you work.
+
+### Check saved source evidence
+
+Use `mode: "validate"` with a saved ordinary-search or analysis `cursor`, optionally selecting a `matchIndex`. Validation compares retained sources with the current worktree or their pinned Git objects, reports `current`, `stale` or `unknown`, and preserves incomplete search coverage. Structured metadata is under `details.validation` and `details.analysis.validation`; the removed graph fields and trace cursors are no longer supported. Validation checks sources on demand and does not run background watchers. It checks saved evidence, not whether new matching files have appeared since the search.
+
+### Narrow by file age or inspect code structure
+
+Worktree searches can use `modifiedAfter` and `modifiedBefore` as Unix millisecond bounds. The lower bound is inclusive and the upper bound is exclusive, so a time window can be expressed without changing the search pattern. The same filter applies to content and filename searches; unavailable file metadata is reported as incomplete evidence rather than silently treated as a match.
+
+Use `mode: "outline"` with a concrete JS/TS/TSX or Python file to see bounded symbol ranges. JS/TS/TSX use ast-grep; Python uses indentation-based class, function and method evidence. These ranges do not prove compiler bindings, runtime calls or test coverage. `mode: "tests"` provides JS/TS/TSX related-test candidates; unsupported language operations fail explicitly. Use ordinary search and `inspect` for Swift source.
+
+The readable result keeps the main evidence compact. Per-item ranges, counts, coverage and continuation requests remain in structured `details`, so a client can use the structured fields without requiring a second search.
+
+## Common uses
+
+Tell your agent what you need, for example:
+
+- “Which documents mention the refund deadline?”
+- “Find this error in the logs and show the surrounding messages.”
+- “Find files containing both the customer name and the order number.”
+- “List matches for any of these keywords.”
+- “I remember part of the meeting-notes filename. Help me find it.”
+- “Search only this folder; do not expand the scope.”
+- “Show me which files contain relevant text, then open two of them.”
+- “Continue from the previous page and show the remaining passages.”
+- “Search files modified since this Unix millisecond timestamp.”
+- “I may remember this sentence incorrectly; search exact and semantic evidence together.”
+- “Show the Python classes and functions in this file, then inspect the method that matters.”
+- “Find this function name in source, inspect the relevant occurrences, then validate the saved evidence after I edit the file.”
+
+The plugin provides file locations and actual text so the agent can answer from the material and you can check the original yourself.
+
+## Install
+
+MCP needs Node.js 22.19+. Pi needs Pi 0.84.3+ with Node.js 22.19+ or Bun 1.4+. The search engine ships with the package for each supported platform, so no system search tool, shell function or `PATH` setup is required, and a search never downloads anything. Install with optional dependencies enabled.
+
+When upgrading from a release published under an earlier package identity, remove that earlier plugin and MCP registration before installing sift-light. This avoids loading two search tools or enforcement hooks in the same host.
+
+To use your own ripgrep, set `SIFT_LIGHT_RG_PATH` to the absolute path of the executable in the MCP server or Pi process environment, then restart the host. It applies to content, filename and Git-source searches. Paths containing spaces work; aliases, shell functions, relative paths and `~` are not expanded. An unusable value fails explicitly instead of silently choosing another executable. If the bundled engine is missing, reinstall with optional dependencies enabled or point this setting at your own binary.
+
+### Pi
+
+```bash
+pi install npm:sift-light
+```
+
+Restart Pi after installing or updating. Pi uses this plugin for conventional searches by default; reads, edits, tests, builds and scripts remain available. `enforceSearch` accepts `"hard"` (the default), `"prefer"` (keep the dedicated tool and guidance without denying alternative searches), or `"off"`. Boolean values and unknown configuration fields are rejected. Configure it in `~/.pi/agent/sift-light.json`, then restart. Set `"locale": "zh-CN"` there for the Chinese interface.
+
+### OMP (Oh My Pi)
+
+```bash
+omp install npm:sift-light@latest
+```
+
+Restart OMP after installing or updating. The package declares its native OMP extension and registers `sift-light`. In the default hard mode it removes OMP's built-in `grep` and `glob` entries from the active tool set and blocks direct search commands while leaving reads, edits, tests, builds and other development tools available. Prefer mode keeps both the dedicated and alternative tools active, adds model guidance, and does not deny shell searches. OMP's active profile is respected; the default configuration file is `~/.omp/agent/sift-light.json`, and a named profile uses `~/.omp/profiles/<profile>/agent/sift-light.json`. Set `enforceSearch` to `"hard"` (default), `"prefer"`, or `"off"` in the active file, then restart OMP. Only these current string values are accepted; boolean values and unknown configuration fields are rejected. Set `"locale": "zh-CN"` to use the Chinese interface.
+
+### Optional semantic judge
+
+Hybrid search remains local-only by default. An optional semantic judge can classify retained concept candidates and improve ordering, but it never replaces local matching, source inspection, pagination, or verification.
+
+The feature is enabled only when `semanticJudge.enabled` is explicitly set to `true`. Merely defining the environment variable does not activate network access. Keep the credential in the process environment; do not put the credential value in this file:
+
+```json
+{
+  "locale": "en",
+  "enforceSearch": "hard",
+  "semanticJudge": {
+    "enabled": false,
+    "provider": "jev",
+    "apiKeyEnv": "TYPESAFE_API_KEY",
+    "model": "jev-latest",
+    "timeoutMs": 120000,
+    "maxCandidates": 20,
+    "maxRetries": 2
+  }
+}
+```
+
+When enabled, the configured endpoint receives only the query and bounded candidate excerpts. Up to eight candidates and 64 KiB are sent per request. Independent batches run under the existing 20-candidate ceiling; an HTTP 413 response splits only that batch. If one batch fails, its candidates keep their local order while successful batches still contribute classifications, and the result reports partial coverage with judged/unjudged candidate and batch counts. A missing key still fails configuration explicitly, local candidates are never removed by a provider failure, and semantic classification is not runtime proof.
+
+### Claude Code or Codex: MCP connection
+
+```bash
+claude mcp add sift-light -- npx -y --package sift-light@latest sift-light-mcp --stdio
+```
+
+```bash
+codex mcp add sift-light -- npx -y --package sift-light@latest sift-light-mcp --stdio
+```
+
+`@latest` follows the newest published version when MCP starts. Restart the host to load updates. The server searches the active project; `SIFT_LIGHT_MCP_CWD` can select a different root. An MCP-only connection adds the tool without disabling other search tools.
+
+Pi and OMP load their host-scoped configuration by default. Set `SIFT_LIGHT_CONFIG` in the actual host process environment when all hosts should share one explicit file; it overrides the host-scoped path for Pi and OMP as well as MCP. Claude Code, Codex and Kimi all start the same standalone MCP server, so add this variable to each host's MCP `env` map rather than relying only on a shell startup file:
+
+```text
+SIFT_LIGHT_CONFIG=/absolute/path/to/sift-light.json
+```
+
+Keep `TYPESAFE_API_KEY` in the MCP process environment or its secret manager; never put the credential value in the configuration file or a checked-in host manifest. The standalone MCP server keeps semantic judging disabled when this path is absent, and fails at startup when an explicit path is missing or an enabled configuration has no key. It never silently claims that Jev ran. Startup diagnostics are written to stderr, and hybrid results expose `semanticJudge.status`; `judgedCandidates > 0` proves that at least one remote batch completed, `complete` means every considered candidate was judged, and `partial` keeps the remaining candidates locally ordered and explicitly unjudged.
+
+MCP returns readable text plus structured evidence by default. If a host serializes both forms into the model context, set `SIFT_LIGHT_MCP_OUTPUT_MODE=model` in that MCP server's environment and restart it. Model mode omits `structuredContent` and its advertised output schema, advertises concise workflow guidance, and selects the smaller of the standard page and a compact view of the same retained analysis snapshot. Repeated paths and inspect requests are shared, hybrid does not concatenate separate literal and Concept bodies, and outline excerpts are deferred to version-checked inspection. Counts, coverage, partial status, reasons and continuation requests remain visible. Use `text` to omit structured output while preserving the complete standard text and full usage guidance, or retain the default `structured` mode for programmatic consumers and clients that expose only structured results. Any other value fails at startup. The bundled Claude Code, Codex and Kimi native plugins select `model`; direct MCP connections retain the structured default unless configured explicitly.
+
+`paths` selects exact retained files from an existing cursor; a new search accepts one `path`. Split unrelated roots into separate requests rather than replacing them with a broader common parent. Markdown inspection uses a bounded line window and does not require Universal Ctags; missing structure providers remain visible when they affect code structure inspection.
+
+### Native plugins
+
+For conventional search enforcement in other hosts:
+
+- **Claude Code:** `/plugin marketplace add lightsifter/sift-light`, then `/plugin install sift-light@sift-light`.
+- **Codex:** `codex plugin marketplace add lightsifter/sift-light`, then `codex plugin add sift-light@sift-light`; review and trust the hook in `/hooks`.
+- **Kimi Code:** `/plugins install /absolute/path/plugins/sift-light` using the plugin directory from this repository or installed package, then confirm trust and run `/reload`.
+
+Kimi Code's web mode can start plugin MCP servers from its installation directory. If relative MCP searches resolve to the wrong project, keep the native plugin for search enforcement and add a project-local `.kimi-code/mcp.json` entry with the same `sift-light` server and an explicit absolute `cwd` for that project.
+
+Restart after installation. Native hooks use hard enforcement by default. To keep the native plugin, MCP tool and model guidance without denying conventional searches, start the host with `SIFT_LIGHT_ENFORCE_SEARCH=prefer`; use `off` to disable only hook enforcement. Accepted values are `hard`, `prefer`, and `off`; an unsupported value fails closed instead of silently allowing a search. The setting is inherited from the host process, so a project cannot lower a user's policy merely by committing a repository configuration file. You can still disable the complete integration through Claude Code `/plugin`, Codex `/hooks`, or Kimi `/plugins disable sift-light` followed by `/reload`.
+
+In hard mode, a direct search such as `grep warning report.txt` is denied. A trailing filter such as `cat report.txt | grep warning` remains available because it filters output from a non-search producer; `find src | grep test` and `rg warning src | grep result` remain denied because their pipelines already contain a direct search producer. If one subcommand in a compound shell call is denied, the host executes none of that call. The denial identifies the detected search and tells the agent to retry non-search operations separately.
+
+Local searches stay on your machine. Only grant access to files your agent is allowed to read. HTTP deployments need an authenticated gateway before public exposure; see [Security](SECURITY.md).
+
+[Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [AGPL-3.0-only license](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,177 @@
+# sift-light
+
+简体中文 · [English](README.md)
+
+**sift-light — Evidence-first search for AI agents.**
+
+**一个通用的本地搜索插件，让 Agent 更方便地查找文件、文档、笔记、日志和各类文本资料。**
+
+它像一位耐心的图书管理员：你说想找什么，它帮你找到书架、翻到相关页面，再陪你沿着线索继续看。资料少时，直接把内容递给你；资料多时，先铺开一张地图，让你知道从哪里看起。
+
+## 它能帮上什么忙
+
+### 找一句话，不用翻完整个资料柜
+
+想找一条报错、一段说明或某个名字，就像告诉管理员一本书里的关键词。命中不多时，插件直接给出原文和所在位置，省去逐个文件打开、来回翻找的过程。
+
+### 资料很多，先给你地图
+
+问“哪些资料提到退款”，可能一下找到很多内容。它会先整理相关文件和片段，像在地图上标出有线索的地点；Agent 可以先判断哪些值得看，再打开其中的原文，而不是一开始就面对满桌散页。
+
+### 追问的时候，书签还在
+
+你说“接着刚才的结果看”，它能沿着上次的位置继续翻页。也可以从某一条命中打开附近原文，像把书签夹在那一页，随时回来补看前因后果。
+
+### 记得不完全准确，也能一次找回
+
+当一句话可能记错了措辞时，可以用一个自然语言 `query` 调用 `mode: "hybrid"`。Hybrid 会在同一个受控请求中始终执行精确字面搜索和已安装的本地 Concept 模型：精确证据固定排在前面，语义候选明确标注且只表示相似度，与精确命中范围重叠的候选会被去重。初始页面共享计数、覆盖状态、来源引用和一个检查游标，以紧凑预览代替拼接两份完整响应。`conceptLimit` 只调整不重叠的语义补充数量（默认 3，最大 20），不会挤占字面证据；返回的 matches 请求从同一个快照开始完整的精确优先分页，不会重新执行任一搜索。
+
+Concept 排名会覆盖请求所声明源码预算内接纳的全部 UTF-8 段落，不再固定抽取范围开头的一小部分。Concept 和 hybrid 默认会自动接纳最多 2,000 个文件，在内部按每批 200 个文件顺序处理，再合并成一次全局排名和一份覆盖结果。所有批次共享同一个请求的 32 MiB 读取预算，扩大文件上限不会把内容预算成倍放大。用户不需要自己计算或续接批次；只有确实想主动缩小范围时，才需要把 `maxFilesToParse` 作为可选的高级硬上限。超过模型 token 窗口的段落会拆成带重叠、且保证不截断的窗口参与排名，后半段内容不会被静默丢弃。离线 embedding 按内容、模型版本和分段版本缓存在本地，缓存上限为 512 MiB；重复内容直接复用，内容变化自然失效，缓存写入或清理失败会在结果中明确显示。
+
+Concept 或 hybrid 较慢时，会在默认五秒等待窗口内返回 `status: "waiting"` 或 `"running"`、`operationId`、进度和精确的 `nextRequest`，例如 `{ "mode": "await", "operationId": "..." }`。请原样复制这个请求：它会续接同一个计算，不会重启查询，也不会降级成只有字面的结果。最终结果可稳定复取十分钟；每个服务会话最多保留 32 个终态结果。`mode: "cancel"` 会停止自有任务并等待清理完成。每个服务会话最多同时接纳八个 pending operation；单个 operation 使用 `SIFT_LIGHT_CONCEPT_TIMEOUT_MS` 指定一个总执行时限（整数毫秒，1000–3600000，默认 600000），另有 120 秒无人续接租期。真实模型、来源或资源故障会以明确失败返回。发布结果前会重新枚举并校验同一来源 generation；源文件变化会刷新 operation，混合版本不会被标成 complete。接纳计划计数（`filesEnumerated`、`filesAdmitted`、`filesSkippedEmpty`、`filesUnavailable`、`passagesQueued`、`batchesPlanned`、`batchesCompleted`）会在结果里明确显示。空文件属于正常跳过，不会把结果标成 partial。
+
+### 几个条件，可以一起交代
+
+“找同时提到客户和退款的文件”，就像请管理员挑出同时贴着两张标签的资料；“这几个词任意一个出现都算”，则像列出一张候选清单。可以一次表达多个查找条件，减少反复搜索。
+
+### 指定一个抽屉，就在里面找
+
+需要只查某个文件夹时，可以明确告诉 Agent 限定范围。只记得文件名的一部分，也可以先找文件，再看内容。像先确定资料柜的哪一层，再逐步缩小到要找的那一份。
+
+`files` 多词查询要求每个词都在路径中按字面出现；单个缩写仍支持模糊匹配。业务意图使用 `hybrid` 或 `concept`。普通内容搜索保留零匹配后扩大范围的既有默认；需要限定目录时传 `scope: "strict"`。范围扩大的提示会先于证据显示。
+
+### 看到了多少，说得清楚
+
+一页装不下的内容会分批展示，并提供继续查看的入口。原文发生变化时，也会提醒重新确认。像一位认真整理资料的助手，会把“已经看到的”和“还需要往后翻的”交代清楚。
+
+完整快照表示匹配保留完整，不代表源码正文没有截断。长行摘录会明确标记限制，并给出最后一页之后仍可执行的 `inspectRequest`。需要更多结果时沿游标继续，不要仅为翻页而修改 limit 重搜。
+Pi 和 OMP 的被动 session 状态会显示当前加载的包版本，统计已返回的新查询，区分完整、部分和未完成结果，并报告未取消的失败调用。cursor 与 operation 续接不会重复计入新查询。
+
+普通搜索继续遵循仓库 ignore 规则，但只要存在被忽略文件，就会明确说明文件系统覆盖受策略过滤，不再把“接纳文件里没找到”说成“整个目录绝对不存在”。需要发布前收口时，可以用 `mode: "audit"` 配合带名字的字面量 `patterns`，一次拿到声明范围、枚举/搜索/跳过文件、ignore 策略、每个模式的 `present`、`absent_with_complete_coverage` 或 `unknown` 结论，以及搜索前后的来源稳定性。审计必须包含被忽略的配置或生成文件时，设置 `ignorePolicy: "include"`；`.git` 内部和受保护路径仍然不会开放。
+
+### 先发现语言能力，再按需加载提供方
+
+使用 `mode: "capabilities"` 和项目根目录，可以获取紧凑的文件语言清单。JavaScript、TypeScript 和 TSX 支持 AST 结构、角色、outline、静态 imports 和关联测试候选；Go 支持 AST 结构和角色；Python 支持基于缩进的有界 outline。Swift 和其他语言仍可使用普通内容搜索、文件发现和源码 inspect。能力清单不会启动 parser 或 Concept 模型。
+
+语言服务导航不在范围内。请求 `definitions`、`references`、`implementations`、`callers`、`callees`、`dependencies`、`dependents`、`trace` 或 `impact` 都会明确报错——用文本搜索伪装精确导航，比直接说清楚更糟。使用期间不会启动任何语言服务。
+
+### 校验已保存的源码证据
+
+使用 `mode: "validate"` 加普通搜索或 analysis 的 `cursor`，可以按需传入 `matchIndex` 选择单项证据。校验将已保留源码与当前工作区或固定 Git 对象比较，报告 `current`、`stale` 或 `unknown`，并保留原搜索的不完整覆盖状态。结构化信息位于 `details.validation` 和 `details.analysis.validation`；旧关系图字段和 trace cursor 不再支持。校验按需读取源码，不启动后台监听；它验证已保存证据，不证明搜索后没有新增匹配文件。
+
+### 按文件时间缩小范围，也可以看代码结构
+
+工作区搜索支持用 Unix 毫秒时间戳传入 `modifiedAfter` 和 `modifiedBefore`。下界包含、上界不包含，因此可以准确表示一个时间窗口，不必改动搜索关键词。内容搜索和文件名搜索使用同一过滤条件；无法核验文件元数据时会明确报告证据不完整，不会静默当作命中。
+
+对具体的 JS/TS/TSX 或 Python 文件使用 `mode: "outline"`，可以查看有界符号范围。JS/TS/TSX 使用 ast-grep，Python 使用基于缩进的类、函数和方法范围；它们不证明编译器绑定、运行时调用或测试覆盖。`mode: "tests"` 提供 JS/TS/TSX 关联测试候选，不支持的语言操作会明确报错。Swift 源码可使用普通搜索和 `inspect`。
+
+可读正文会保持精简；每项证据的范围、计数、覆盖状态和继续请求仍保留在结构化 `details` 中，客户端无需为了拿到这些字段再次搜索。
+
+## 常见用法
+
+直接向 Agent 表达需求即可，例如：
+
+- “帮我找一下，哪些文档提到了退款期限？”
+- “这条报错在哪些日志里出现过？把附近的内容也给我看看。”
+- “找同时包含客户名称和订单编号的文件。”
+- “这几个关键词，任意一个出现都列出来。”
+- “我只记得文件名里有会议记录，帮我找找。”
+- “这次只查这个资料文件夹，不要扩大范围。”
+- “先告诉我相关内容分布在哪些文件，再打开其中两份。”
+- “接着刚才的位置继续看，把没展示完的部分找出来。”
+- “按这个 Unix 毫秒时间戳之后修改过的文件搜索。”
+- “这句话我可能记得不准确，把精确和语义证据一起找出来。”
+- “列出这个 Python 文件里的类和函数，再打开需要看的方法。”
+- “搜索这个函数名并查看相关源码；我修改文件后，再校验已保存的证据。”
+
+插件提供文件位置和实际文本，帮助 Agent 根据原文回答，也方便你回到资料中核对。
+
+## 安装
+
+MCP 需要 Node.js 22.19+。Pi 需要 Pi 0.84.3+，以及 Node.js 22.19+ 或 Bun 1.4+。搜索引擎随包提供对应平台的版本，无需系统搜索工具、Shell 函数或额外设置 `PATH`，搜索过程也不会下载任何东西。安装时请保留可选依赖。
+
+如果你从更早的包身份升级，请先移除此前安装的插件和 MCP 注册，再安装 sift-light，避免同一宿主同时加载两套搜索工具或拦截钩子。
+
+如需使用自己的 ripgrep，在 MCP 服务或 Pi 进程的环境变量中设置 `SIFT_LIGHT_RG_PATH` 为可执行文件的绝对路径，然后重启宿主。该设置统一作用于内容、文件名和 Git 源文件搜索。路径中的空格可用；不支持别名、Shell 函数、相对路径或 `~` 展开。配置无效时明确报错，不会另选程序。随包引擎缺失时，请保留可选依赖重新安装，或把该项指向自己的二进制。
+
+### Pi
+
+```bash
+pi install npm:sift-light
+```
+
+安装或更新后重启 Pi。Pi 默认让常规搜索使用本插件，读取、编辑、测试、构建和脚本仍可使用。`enforceSearch` 支持 `"hard"`（默认严格拦截）、`"prefer"`（保留专用工具和模型指引，但不拒绝其他搜索）和 `"off"`；布尔值及未知配置字段会直接报错。请在 `~/.pi/agent/sift-light.json` 中配置后重启；设置 `"locale": "zh-CN"` 可启用中文界面。
+
+### OMP（Oh My Pi）
+
+```bash
+omp install npm:sift-light@latest
+```
+
+安装或更新后重启 OMP。安装包声明了 OMP 原生扩展并注册 `sift-light`。默认 hard 模式会从活动工具集中移除 OMP 内置的 `grep` 和 `glob`，并在执行前阻止直接搜索命令，同时保留读取、编辑、测试、构建和其他开发工具。prefer 模式会同时保留专用工具与其他搜索工具，加入模型指引，但不拒绝 shell 搜索。OMP 当前 profile 会被正确识别：默认配置文件是 `~/.omp/agent/sift-light.json`，命名 profile 使用 `~/.omp/profiles/<profile>/agent/sift-light.json`。在当前文件中将 `enforceSearch` 设置为 `"hard"`（默认）、`"prefer"` 或 `"off"` 后重启 OMP；布尔值及未知配置字段会直接报错。设置 `"locale": "zh-CN"` 可启用中文界面。
+
+### 可选语义判断
+
+Hybrid 搜索默认只使用本地能力。可选的语义判断器可以对保留的概念候选进行分类并改善排序，但不会替代本地匹配、源码检查、分页或验证。
+
+只有在配置中明确设置 `semanticJudge.enabled` 为 `true` 时才会启用。仅定义环境变量不会激活网络请求。凭据应保留在进程环境变量中，不要把凭据值写进配置文件：
+
+```json
+{
+  "locale": "zh-CN",
+  "enforceSearch": "hard",
+  "semanticJudge": {
+    "enabled": false,
+    "provider": "jev",
+    "apiKeyEnv": "TYPESAFE_API_KEY",
+    "model": "jev-latest",
+    "timeoutMs": 120000,
+    "maxCandidates": 20,
+    "maxRetries": 2
+  }
+}
+```
+
+启用后，配置的端点只会收到查询和有界的候选摘录。每个请求最多包含八个候选和 64 KiB；独立批次仍受现有最多二十个候选的总上限约束，HTTP 413 只会拆分对应批次。某个批次失败时，其中的候选保持本地顺序，成功批次仍可提供分类；结果会明确标记为部分覆盖，并报告已判断/未判断候选及批次计数。缺少密钥仍会明确报配置错误，提供方失败绝不会删除本地候选，语义分类也不等同于运行时证明。
+
+### Claude Code 或 Codex：连接 MCP
+
+```bash
+claude mcp add sift-light -- npx -y --package sift-light@latest sift-light-mcp --stdio
+```
+
+```bash
+codex mcp add sift-light -- npx -y --package sift-light@latest sift-light-mcp --stdio
+```
+
+`@latest` 会在 MCP 启动时跟随最新发布版本，更新后重启宿主即可加载。服务器默认搜索当前项目，可用 `SIFT_LIGHT_MCP_CWD` 指定其他根目录。仅连接 MCP 会添加工具，不会禁用其他搜索工具。
+
+Pi 和 OMP 默认读取各自宿主的配置文件。如果希望所有宿主共用一份明确配置，可以在实际宿主进程环境中设置 `SIFT_LIGHT_CONFIG`；它会同时覆盖 Pi、OMP 和 MCP 的宿主默认路径。Claude Code、Codex 和 Kimi 都是启动同一个独立 MCP 服务，因此要把这个变量放进各自 MCP 条目的 `env` 中，不能只依赖 Shell 启动文件：
+
+```text
+SIFT_LIGHT_CONFIG=/absolute/path/to/sift-light.json
+```
+
+`TYPESAFE_API_KEY` 应保存在 MCP 进程环境或宿主的密钥管理中；不要把凭据值写进配置文件或提交到版本库的宿主清单。没有这个路径时，独立 MCP 会明确保持语义判断 disabled；路径被显式设置但文件不存在，或配置已启用但缺少 key 时，会在启动阶段失败，不会静默声称 Jev 已运行。启动诊断写入 stderr，hybrid 结果会暴露 `semanticJudge.status`；`judgedCandidates > 0` 证明至少一个远程批次已完成，`complete` 表示所有纳入判断的候选都已判断，`partial` 则会保留其余候选的本地顺序并明确标记为未判断。
+
+MCP 默认同时返回可读文本和结构化证据。如果宿主会把两种形式一起序列化进模型上下文，请在该 MCP 服务的环境中设置 `SIFT_LIGHT_MCP_OUTPUT_MODE=model`，然后重启。模型模式不返回 `structuredContent`，也不声明结构化输出 schema；它会提供精简的工作流说明，并在标准页和同一个已保留分析快照的紧凑视图中选择较小者。紧凑视图共享重复路径和 inspect 请求，hybrid 不会拼接两份独立的 literal 与 Concept 正文，并把 outline 签名延后到版本校验过的源码检查。计数、覆盖范围、部分状态、原因和续读请求仍然可见。`text` 模式只省略结构化输出，逐字保留标准文本和完整兼容说明；程序消费者或只展示结构化结果的客户端应继续使用默认的 `structured` 模式。其他取值会在启动时明确失败。捆绑的 Claude Code、Codex 和 Kimi 原生插件会选择 `model`；直接 MCP 连接仍保留兼容默认值，除非显式配置。
+
+`paths` 只用于从已有 cursor 中精确选择已保留文件；新搜索只接受一个 `path`。多个互不相干的根目录应拆成独立请求，不要自动改成范围更大的共同父目录。Markdown 检查直接使用有界行窗口，不依赖 Universal Ctags；代码结构检查真的受到 provider 缺失影响时仍会明确报告。
+
+### 原生插件
+
+如果希望在其他宿主中也强制常规搜索使用本插件：
+
+- **Claude Code：** 先运行 `/plugin marketplace add lightsifter/sift-light`，再运行 `/plugin install sift-light@sift-light`。
+- **Codex：** 先运行 `codex plugin marketplace add lightsifter/sift-light`，再运行 `codex plugin add sift-light@sift-light`，通过 `/hooks` 查看并信任钩子。
+- **Kimi Code：** 使用本仓库或安装包中的插件目录，运行 `/plugins install /absolute/path/plugins/sift-light`，确认信任后执行 `/reload`。
+
+Kimi Code 的 web 模式可能从安装目录启动插件 MCP 服务。如果相对路径搜索解析到了错误项目，请继续使用原生插件强制搜索，并在项目内的 `.kimi-code/mcp.json` 中配置同名 `sift-light` 服务，显式填写该项目的绝对 `cwd`。
+
+安装后重启。原生钩子默认使用严格模式。如需保留原生插件、MCP 工具和模型指引，但不硬性拒绝其他搜索，请使用 `SIFT_LIGHT_ENFORCE_SEARCH=prefer` 启动宿主；设置为 `off` 只关闭钩子强制策略。可用值为 `hard`、`prefer` 和 `off`，非法值会安全拒绝并明确报错，不会静默放行。该设置由宿主进程继承，因此项目不能仅靠提交仓库配置文件降低用户的全局策略。仍可通过 Claude Code `/plugin`、Codex `/hooks`，或 Kimi `/plugins disable sift-light` 后执行 `/reload` 来关闭整个集成。
+
+严格模式下，`grep warning report.txt` 这类直接搜索会被拒绝；`cat report.txt | grep warning` 仍可用，因为它只是过滤一个非搜索命令的输出。`find src | grep test` 和 `rg warning src | grep result` 仍会被拒绝，因为管道中已经包含直接搜索来源。复合 shell 调用中只要一个子命令被拒绝，宿主就不会执行其中任何操作；拒绝信息会指出检测到的搜索，并要求 Agent 单独重试非搜索操作。
+
+本地搜索在你的机器上进行。请只允许 Agent 读取已获授权的文件。HTTP 服务对外开放前需要认证网关，详见[安全说明](SECURITY.md)。
+
+[更新记录](CHANGELOG.md) · [参与贡献](CONTRIBUTING.md) · [AGPL-3.0-only 许可证](LICENSE)

package/SECURITY.md

@@ -0,0 +1,25 @@
+# Security Policy
+
+## Reporting vulnerabilities
+
+Use this repository's GitHub private vulnerability reporting. Include the affected version, impact and reproduction steps with non-sensitive examples. Do not publish credentials, private source or exploit details in an issue.
+
+Security fixes target the latest released version. An acknowledgement is normally provided within seven days; remediation depends on severity and reproducibility.
+
+## Access and privacy
+
+The tool runs with the permissions of its host process. It is read-only, but it is not a filesystem sandbox. Explicit absolute paths and `..` can access other readable locations. `.git` internals and known external credential and special-system paths are blocked; these checks cannot identify every renamed, copied or custom-location secret. Hidden files inside the project remain searchable.
+
+`redact: true` optionally masks common credential values in returned output. It does not change which files are searched and cannot guarantee removal of every sensitive value. Only connect the tool to repositories and paths that the agent is authorized to read.
+
+Local searches have no telemetry and do not upload source or queries. Package installation can access npm. Explicit installation of the optional concept model downloads public assets; concept searches then run offline. Concept mode stores content-addressed embeddings, never source text or paths, beneath the configured local model root. The cache identity includes the pinned model and chunking revision, is bounded to 512 MiB, and can be deleted without losing source data or search correctness. Remote HTTP connections transmit requests and results to the configured server.
+
+## HTTP deployments
+
+The HTTP server has no built-in authentication. Keep the default loopback binding or place it behind an authenticated gateway. Browser clients require an explicitly allowed origin; CORS is not authentication. Restrict the server account's filesystem permissions to the data intended for its clients.
+
+## Search enforcement
+
+Version 1.2.0 enables conventional search enforcement by default in Pi. Claude Code, Codex and Kimi Code require the native plugin; MCP alone cannot disable other tools. Codex also requires the user to trust its hook.
+
+Enforcement depends on an enabled, trusted, runnable host hook. Disabled hooks, process failures and host error handling can prevent interception. Custom programs can still search. The policy preserves ordinary reads, edits, directory browsing, tests, builds and scripts, and does not change the model, memory or existing host permissions. See the [README](README.md) for disabling it.

package/package.json

@@ -0,0 +1,142 @@
+{
+  "name": "sift-light",
+  "version": "1.0.0",
+  "description": "Context-efficient local search for files, documents, notes and logs across Pi, OMP and MCP clients",
+  "keywords": [
+    "ai-agent",
+    "claude-code",
+    "code-navigation",
+    "codex",
+    "context-engineering",
+    "grep",
+    "mcp",
+    "oh-my-pi",
+    "omp",
+    "pi",
+    "pi-extension",
+    "pi-package",
+    "ripgrep",
+    "search",
+    "source-inspection"
+  ],
+  "homepage": "https://github.com/lightsifter/sift-light#readme",
+  "bugs": {
+    "url": "https://github.com/lightsifter/sift-light/issues"
+  },
+  "license": "AGPL-3.0-only",
+  "author": "baoer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lightsifter/sift-light.git"
+  },
+  "bin": {
+    "sift-light-mcp": "src/mcp-server.mjs",
+    "sift-light-model": "src/concept-worker.mjs"
+  },
+  "files": [
+    "src/**/*.ts",
+    "src/syntax-worker.mjs",
+    "src/mcp-server.mjs",
+    "src/syntax-worker.toml",
+    "README.md",
+    "README.zh-CN.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "src/concept-worker.mjs",
+    "plugins/sift-light/**"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build:worker": "bun run scripts/build-syntax-worker.ts",
+    "check:worker": "bun run doc/testing/scripts/check-syntax-worker.ts",
+    "build:mcp": "bun run scripts/build-mcp-server.ts",
+    "check:mcp": "bun run doc/testing/scripts/check-mcp-server.ts",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "lint": "oxlint --type-aware --deny-warnings --report-unused-disable-directives src scripts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test ./doc/testing/test",
+    "test:node": "bun run doc/testing/scripts/node-smoke.ts",
+    "benchmark": "bun run doc/testing/scripts/benchmark.ts",
+    "check": "bun run format:check && bun run lint && bun run typecheck && bun run build",
+    "pack:check": "bun pm pack --dry-run && bun run scripts/check-npm-publish.ts",
+    "setup:concept": "bun run src/concept-worker.mjs --install-model",
+    "build:concept-worker": "bun run scripts/build-concept-worker.ts",
+    "check:concept-worker": "bun run doc/testing/scripts/check-concept-worker.ts",
+    "test:concept": "bun run doc/testing/scripts/test-concept.ts",
+    "evaluate:investigations": "bun run doc/testing/scripts/investigation-eval.ts",
+    "build:search-plugin": "bun run scripts/build-search-plugin.ts",
+    "check:search-plugin": "bun run doc/testing/scripts/check-search-plugin.ts",
+    "test:mcp-hosts": "bun run doc/testing/scripts/mcp-host-verification.ts",
+    "build": "bun run build:worker && bun run build:concept-worker && bun run build:search-plugin && bun run build:mcp",
+    "format:local:check": "bun run doc/testing/scripts/format-local.ts --check",
+    "lint:local": "oxlint --no-ignore --type-aware --tsconfig doc/testing/tsconfig.json --deny-warnings --report-unused-disable-directives src scripts doc/testing/test doc/testing/scripts",
+    "typecheck:local": "tsc --noEmit --project doc/testing/tsconfig.json",
+    "check:local": "bun run format:check && bun run format:local:check && bun run check:search-plugin && bun run check:concept-worker && bun run check:worker && bun run check:mcp && bun run lint:local && bun run typecheck:local && bun run test && bun run test:node && bun run benchmark"
+  },
+  "dependencies": {
+    "@ast-grep/lang-go": "0.0.6",
+    "@ast-grep/napi": "0.45.2",
+    "@huggingface/transformers": "3.8.1",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@vscode/ripgrep": "1.18.0",
+    "typebox": "1.3.19",
+    "web-tree-sitter": "0.25.10",
+    "zod": "4.5.4"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.84.3",
+    "@earendil-works/pi-coding-agent": "0.84.3",
+    "@earendil-works/pi-tui": "0.84.3",
+    "@types/bun": "^1.4.0",
+    "oxfmt": "^0.65.0",
+    "oxlint": "^1.80.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "tree-sitter-bash": "0.25.1",
+    "tree-sitter-powershell": "0.26.4",
+    "typescript": "7.0.2"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "bun": ">=1.4.0",
+    "node": ">=22.19.0"
+  },
+  "packageManager": "bun@1.4.2",
+  "knip": {
+    "entry": [
+      "src/mcp-server.ts"
+    ]
+  },
+  "omp": {
+    "extensions": [
+      "./plugins/sift-light/omp-extension.mjs"
+    ]
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}

package/plugins/sift-light/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "sift-light",
+  "version": "1.0.0",
+  "description": "Require sift-light for conventional local searches while keeping development tools available.",
+  "author": {
+    "name": "baoer"
+  },
+  "homepage": "https://github.com/lightsifter/sift-light#readme",
+  "license": "AGPL-3.0-only"
+}

package/plugins/sift-light/.codex-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "sift-light",
+  "version": "1.0.0",
+  "description": "Require sift-light for conventional local searches while keeping development tools available.",
+  "author": {
+    "name": "baoer"
+  },
+  "homepage": "https://github.com/lightsifter/sift-light#readme",
+  "license": "AGPL-3.0-only",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "sift-light",
+    "shortDescription": "Enforced local code search",
+    "longDescription": "Require sift-light for conventional local searches while keeping development tools available.",
+    "defaultPrompt": "Search this project's code using sift-light.",
+    "developerName": "baoer",
+    "category": "Productivity",
+    "capabilities": []
+  }
+}

package/plugins/sift-light/.mcp.json

@@ -0,0 +1,24 @@
+{
+  "mcpServers": {
+    "sift-light": {
+      "command": "npx",
+      "args": [
+        "--yes",
+        "--package",
+        "sift-light-runtime@npm:sift-light@1.0.0",
+        "sift-light-mcp",
+        "--stdio"
+      ],
+      "env": {
+        "npm_config_ignore_scripts": "true",
+        "ONNXRUNTIME_NODE_INSTALL_CUDA": "skip",
+        "SIFT_LIGHT_MCP_OUTPUT_MODE": "model"
+      },
+      "env_vars": [
+        "SIFT_LIGHT_CONFIG",
+        "TYPESAFE_API_KEY",
+        "SIFT_LIGHT_JEV_API_KEY"
+      ]
+    }
+  }
+}