From 20c771df3434338fd863ab36245461034ea26ea6 Mon Sep 17 00:00:00 2001 From: styayur Date: Thu, 22 Oct 2026 12:58:44 +0800 Subject: [PATCH 1/2] Align English and Chinese README quick starts, MCP setup and maturity limits --- README.md | 185 +++++++++++++++++++++++------------------------- README.zh-CN.md | 139 +++++++++++++++++++++++------------- 2 files changed, 175 insertions(+), 149 deletions(-) diff --git a/README.md b/README.md index c76d3e8..075d8fa 100644 --- a/README.md +++ b/README.md @@ -1,137 +1,126 @@ # Local Context Engine -**Project stage:** Alpha. Implemented workflows have automated verification; independent installation, upgrade and sustained user validation have not been audited. +Offline Windows search and local stdio MCP for files, applications, processes, services and windows. -**Local-first context discovery engine for Windows.** Find files, applications, -processes, services and windows through one explainable local query. +[简体中文](README.zh-CN.md) · [Download v0.2.0](https://github.com/styayur/local-context-engine/releases/tag/v0.2.0) · [Documentation](docs/README.md) -[![CI](https://github.com/styayur/local-context-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/styayur/local-context-engine/actions/workflows/ci.yml) -[![License: MPL-2.0](https://img.shields.io/badge/license-MPL--2.0-blue)](LICENSE) +**Stage: Alpha.** Implemented workflows have regression coverage; independent installation, upgrade and sustained user validation remain outstanding. This guide describes current source. The latest published release is v0.2.0; the v1.0.0 notes are an unreleased candidate, not an available binary or compatibility guarantee. -[简体中文](README.zh-CN.md) · [Download v0.2.0](https://github.com/styayur/local-context-engine/releases/tag/v0.2.0) · [Documentation](docs/README.md) +Current Rust workspace, desktop package and installer configuration declare 0.2.0. Sharing a version number with the release does not mean every default-branch change is in its binaries. -Current published release: **v0.2.0**. The v1.0.0 notes are an **unreleased -candidate**, not an available binary or a new compatibility guarantee. +## Features -## Why Local Context Engine +- Search local filenames, paths and metadata with an explicit DSL or English/Chinese rule-based query compilation. No account, model service or network is needed for normal search. +- Query files/directories, apps, processes, services and windows through the same service. Inspect ranking explanations, provider health and index state. +- Use the CLI, desktop shell or local stdio MCP adapter. The optional elevated NTFS MFT/USN service is separate from the unprivileged scan backend. +- File-query accelerators narrow candidates before exact verification; broad queries can still scan. Deterministic ordering requires the same query, snapshot, settings and usage state. -A filename, an installed application and a running process can refer to the same -work. LCE puts those local sources behind one query interface, while keeping the -query, candidate selection and ranking inspectable. File search indexes names, -paths and metadata rather than file contents. Normal search needs no account, -model service or network connection. +```text +CLI / Desktop / MCP → SearchService → Providers + ├─ file: planner → accelerators → verification + └─ apps / processes / services / windows + → ranking and explanations +``` -## Features and maturity +The planner belongs to the file provider, not to every provider. See [Architecture](docs/ARCHITECTURE.md) and [Query Engine](docs/QUERY_ENGINE.md). The existing [benchmark report](docs/BENCHMARKS.md) records synthetic measurements and their limits; it is not a latency guarantee. -| Status | Capability | Boundary | -|---|---|---| -| Stable | Query DSL and English/Chinese rule-based query compilation | Explicit filters; no model-generated retrieval | -| Stable | Query Planner with extension, prefix and full-path trigram accelerators | Exact verification remains authoritative; broad queries can scan | -| Stable | File/directory, app, process, service and window providers | Availability and metadata depend on Windows permissions | -| Stable | CLI, local stdio MCP, ranking explanations and index health | Same query **and snapshot/settings/usage state** give deterministic ordering | -| Experimental | Optional privileged NTFS MFT/USN service and desktop acceptance across machines | Implemented and tested, but require deployment-specific validation; see security and roadmap | -| Future | Full-text, semantic retrieval and model-backed query compilation | Not installed, enabled or run by default; no current implementation promise | +## Installation / Quick Start -Stable means implemented workflows with regression coverage. It does not mean -all hardware, filesystems or desktop environments have been certified. +### Published Windows packages -## Architecture +Download the [Windows x64 portable ZIP](https://github.com/styayur/local-context-engine/releases/download/v0.2.0/local-context-engine-windows-x64-v0.2.0.zip) or [desktop installer](https://github.com/styayur/local-context-engine/releases/download/v0.2.0/local-context-engine-desktop-v0.2.0-setup.exe). Compare your file with [SHA256SUMS.txt](https://github.com/styayur/local-context-engine/releases/download/v0.2.0/SHA256SUMS.txt): -```text -User - ↓ -CLI / Desktop / MCP - ↓ -Search Core (via SearchService) - ↓ -Providers ── live Windows snapshots - ↓ file-provider branch -Query Planner → Accelerators → candidate verification - ↓ -Ranking + deterministic ordering + explanations +```powershell +Get-FileHash -Algorithm SHA256 ``` -The planner lives inside the file provider. Accelerators narrow candidates; -providers own operating-system access. The interfaces, data flow and failure -boundaries are described in [Architecture](docs/ARCHITECTURE.md). +Extract the portable archive. In PowerShell, open the directory containing `localsearch.exe` and run: -## Performance +Before the first file search, review [index scope](docs/INDEXING.md): an empty `indexedDrives` setting selects all fixed local volumes, up to the entry limit. Settings are in `%LOCALAPPDATA%\LocalContextEngine\settings.json`; set the intended drives there before collection. A `path:` filter restricts results, not collection. Preserve settings and optional `usage.json` when backing up personal preferences; the index is rebuildable local metadata. -A paired synthetic **one-million-record** probe measured the following on -Windows with Rust 1.98.1. These are local observations, not latency guarantees. - -| Measurement | Before planner optimization | After | -|---|---:|---:| -| Accelerator construction | 11.93 s | 8.91 s | -| Construction process peak working set | 1005.25 MB | 258.98 MB | -| `ext:pdf report`, mean / P95 | 89.36 / 99.74 ms | 20.95 / 23.14 ms | -| Common `report`, mean / P95 | 8.34 / 9.61 ms | 8.47 / 9.87 ms | -| Estimated retained accelerator bytes | 75.80 MB | 75.80 MB | +```powershell +.\localsearch.exe --help +.\localsearch.exe --providers +.\localsearch.exe --backend scan "type:file ext:pdf" +.\localsearch.exe --explain "ext:pdf report" +.\localsearch.exe "type:process python" +.\localsearch.exe --index-status +``` -The memory reduction concerns **peak construction working set**, not a reduction -in retained index size. All eight full ordered comparisons matched the linear -reference. See [Benchmarks](docs/BENCHMARKS.md) for every query, hardware provenance, -sample counts, candidate limits, raw results and limitations. +The scan backend does not require the optional privileged service. Search returns `0` for results, `1` for a valid query with no matches, and `2` for an operation that could not complete. Provider availability depends on Windows permissions; live results and relative-time filters change with the system. See the [DSL reference](docs/DSL.md) and [indexing guide](docs/INDEXING.md). -## Installation +For the desktop package, run the installer, then launch **Local Context Engine**. It requires WebView2 and acceptance on your actual Windows installation. Build success alone does not establish that its window renders and searches correctly. -Download the Windows x64 portable archive or desktop installer from -[v0.2.0](https://github.com/styayur/local-context-engine/releases/tag/v0.2.0). -Verify the download against `SHA256SUMS.txt`. Extract the portable archive and run -`localsearch.exe`; add its directory to `PATH` if you want the commands below. -The desktop requires WebView2. A successful build is not a substitute for a -working desktop smoke test on your Windows installation. +### Build current source -To build the CLI and MCP server from source: +Use Windows x64, a current stable Rust MSVC toolchain and Visual Studio C++ Build Tools. For the desktop, also use Node.js 22 (CI), npm and WebView2. ```powershell git clone https://github.com/styayur/local-context-engine.git cd local-context-engine -git checkout v0.2.0 cargo build --release --locked .\target\release\localsearch.exe --help ``` -Use a current stable Rust MSVC toolchain and Visual Studio C++ Build Tools on -Windows. [Development](docs/DEVELOPMENT.md) covers desktop prerequisites and CI. -An unprivileged directory scan is available without installing the optional -index service. Read the [MFT visibility boundary](docs/SECURITY.md#mft-and-permissions) -before choosing that service on a shared machine. +These commands build the current default branch, not the published v0.2.0 tag. Default Cargo members include the CLI and MCP server but exclude the desktop stack. Desktop packaging and output paths are documented in [Development](docs/DEVELOPMENT.md). + +To launch the desktop from source, run `npm ci` then `npm run tauri:dev` in `apps/desktop`; Tauri opens the native window and starts its development server. + +### Connect an MCP client + +After building, `target/release/localsearch-mcp.exe` serves MCP over local stdio. Replace the example path with its absolute path in your client's configuration: + +```json +{ + "mcpServers": { + "localsearch": { + "command": "C:\\tools\\lce\\localsearch-mcp.exe" + } + } +} +``` + +See [MCP tools and protocol examples](docs/MCP.md) for `search_system`, `compile_query` and other tools. Search itself is local; your MCP client or model may forward results to another service, under its own privacy settings. -## Usage +## Testing / CI / Platform Support + +[![CI](https://github.com/styayur/local-context-engine/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/styayur/local-context-engine/actions/workflows/ci.yml) + +From the repository root on Windows: ```powershell -localsearch --providers -localsearch --backend scan "type:file ext:pdf" -localsearch --explain "ext:pdf report" -localsearch "prefix:read" -localsearch "type:process python" -localsearch "type:service state:running" -localsearch --index-status +cargo fmt --all -- --check +cargo clippy --all-targets --all-features -- -D warnings +cargo test +cargo build --release --locked ``` -Search commands return `0` for results, `1` for a valid query with no matches, -and `2` for an operation that could not complete. Relative time filters and live -providers naturally change with the clock and system state. Use the -[Query Engine](docs/QUERY_ENGINE.md), [DSL reference](docs/DSL.md) and -[MCP guide](docs/MCP.md) for filtering, JSON output and local agent integration. +For desktop checks, run in `apps/desktop`: + +```sh +npm ci +npm run lint +npm run typecheck +npm run build +``` + +The [CI workflow](.github/workflows/ci.yml) runs Rust and desktop checks on Windows, including `cargo check -p local-context-engine-desktop` from the repository root. [CodeForge regression](.github/workflows/codeforge-regression.yml) is an external development gate, not a runtime or Rust crate dependency. See [documentation checks](docs/DOCUMENTATION_CHECKS.md) for Markdown and link validation. + +## Known Limitations + +- Windows is the supported runtime backend; Linux runtime support is not provided. Cargo declares Rust 1.82, but CI tests current stable rather than that minimum. +- File search indexes names, paths and metadata, not file contents. Full-text search, semantic retrieval and model-backed query compilation are future work, not current capabilities. +- The elevated MFT/USN service and desktop need validation across machines. Earlier blank-WebView behavior is not resolved by a successful build alone. Service ACLs, journal rollover, fallback and uninstall need deployment acceptance. +- Cached paths, metadata, settings and optional usage history are sensitive local data. The elevated service can reveal filenames that a normal directory walk cannot list; it does not grant file-content access. Read [Security](docs/SECURITY.md) before enabling it on a shared machine. + +## Roadmap -## Security and privacy +Before v1.0, align package versions, validate the Rust minimum, and complete fresh-install, desktop-rendering and service acceptance gates. Metadata completeness and application discovery can improve later; semantic/full-text extensions must be explicit opt-in. See [Roadmap](docs/ROADMAP.md) and [release preparation](docs/RELEASE_PREPARATION.md), which distinguish implemented workflows from experimental deployment paths and future work. -Search does not upload data or index file contents. Cached paths, metadata, -settings and optional usage history remain sensitive local data. Activating a -result opens it through Windows; process termination requires explicit -confirmation. The optional elevated service can reveal filenames that a normal -directory walk cannot list. It does not grant permission to read their contents. -See [Security](docs/SECURITY.md) and [vulnerability reporting](SECURITY.md). +## Contributing -## Development +Follow [CONTRIBUTING.md](CONTRIBUTING.md) and [Development](docs/DEVELOPMENT.md). Use [Issues](https://github.com/styayur/local-context-engine/issues) for reproducible bugs and [SECURITY.md](SECURITY.md) for vulnerabilities. Keep permission boundaries and English/Chinese capability statements aligned. -Read [Development](docs/DEVELOPMENT.md) and [Contributing](CONTRIBUTING.md) for -checks and extension points. [Roadmap](docs/ROADMAP.md) separates release gates -from future work; [Changelog](CHANGELOG.md) describes user-visible changes. +## License -Repository license: [MPL-2.0](LICENSE). See [license notes](THIRD_PARTY_LICENSES.md) -for the remaining desktop package metadata inconsistency before v1.0.0. -LCE runs independently and has no runtime or -Rust crate dependency on CodeForge Engine. +The repository [LICENSE](LICENSE) and Rust workspace declare **MPL-2.0**. Desktop package metadata still says MIT; [third-party license notes](THIRD_PARTY_LICENSES.md) record that unresolved inconsistency. This documentation change does not alter licenses or package manifests. Dependencies retain their own terms; release notice completeness remains a separate review item. diff --git a/README.zh-CN.md b/README.zh-CN.md index 996f808..2dab1ed 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,89 +1,126 @@ # Local Context Engine -**面向 Windows 的本地优先上下文发现引擎。** 用一套可解释查询查找文件、应用、进程、服务和窗口。 +用于文件、应用、进程、服务和窗口的 Windows 离线搜索与本地 stdio MCP 服务。 [English](README.md) · [下载 v0.2.0](https://github.com/styayur/local-context-engine/releases/tag/v0.2.0) · [文档目录](docs/README.md) -当前已发布版本为 **v0.2.0**。v1.0.0 仍是未发布候选说明，不代表已有对应安装包或新的兼容性承诺。 +**阶段：Alpha。** 已实现流程有回归覆盖；独立用户的安装、升级和持续使用验证仍待完成。本指南介绍当前源码。最新正式发布为 v0.2.0，v1.0.0 说明仍属未发布候选，不表示已有对应安装包或兼容性保证。 -## 解决什么问题 +当前 Rust workspace、桌面包和安装程序配置均声明 0.2.0。版本号与 Release 相同，不代表默认分支的所有改动已进入发布程序。 -同一项工作可能对应文件、应用和运行中的进程。LCE 将这些本地来源放进同一个查询入口，并展示候选选择与排序依据。文件索引保存名称、路径和元数据，不读取全文用于检索；日常搜索不需要账户、模型服务或网络。 +## 功能 -## 能力与成熟度 +- 通过显式 DSL 或中英文规则式查询编译搜索本地文件名、路径与元数据，日常搜索不需要账户、模型服务或网络。 +- 同一服务查询文件/目录、应用、进程、服务和窗口，并展示排序解释、Provider 健康状态和索引信息。 +- 提供 CLI、桌面外壳和本地 stdio MCP 适配器。可选的特权 NTFS MFT/USN 服务独立于非特权扫描后端。 +- 文件查询先通过加速索引缩小候选，再精确验证；宽泛查询仍可能扫描。确定性排序要求查询、快照、设置与使用记录一致。 -| 状态 | 能力 | 边界 | -|---|---|---| -| Stable | Query DSL、中英文规则式查询编译 | 检索不依赖模型 | -| Stable | Query Planner、扩展名/prefix/trigram 索引 | 候选仍需验证；宽泛条件可能扫描索引 | -| Stable | 文件、应用、进程、服务、窗口 Providers | 元数据受 Windows 权限与后端能力限制 | -| Stable | CLI、本地 stdio MCP、解释与健康状态 | 查询、快照、设置、使用记录相同才具有确定性排序 | -| Experimental | 可选的特权 MFT/USN 服务、跨环境桌面验收 | 已实现并有测试，部署环境仍需验证 | -| Future | 全文、语义检索、模型查询编译器 | 不属于默认能力，也不承诺交付时间 | +```text +CLI / Desktop / MCP → SearchService → Providers + ├─ 文件：Planner → 加速索引 → 验证 + └─ 应用 / 进程 / 服务 / 窗口 + → 排序与解释 +``` -Stable 表示已有实现和回归覆盖，不表示通过了所有硬件、文件系统或桌面环境的认证。 +Planner 属于文件 Provider，不是每个 Provider 的公共步骤。详见[架构](docs/ARCHITECTURE.md)和[查询引擎](docs/QUERY_ENGINE.md)。已有[性能报告](docs/BENCHMARKS.md)记录合成数据测量及其限制，不提供延迟保证。 -## 架构 +## 安装 / 快速开始 -```text -用户 → CLI / Desktop / MCP → Search Core → Providers - ↓ 文件分支 - Query Planner → Accelerators - ↓ - 候选验证 → 排序与解释 -``` +### 已发布 Windows 软件包 + +下载 [Windows x64 便携 ZIP](https://github.com/styayur/local-context-engine/releases/download/v0.2.0/local-context-engine-windows-x64-v0.2.0.zip)或[桌面安装程序](https://github.com/styayur/local-context-engine/releases/download/v0.2.0/local-context-engine-desktop-v0.2.0-setup.exe)，对照 [SHA256SUMS.txt](https://github.com/styayur/local-context-engine/releases/download/v0.2.0/SHA256SUMS.txt) 校验： -Planner 位于文件 Provider 内部；其他 Provider 读取各自的系统快照。详见[架构](docs/ARCHITECTURE.md)。 +```powershell +Get-FileHash -Algorithm SHA256 +``` -## 性能 +解压便携包，在 PowerShell 中进入包含 `localsearch.exe` 的目录，运行： -Windows、Rust 1.98.1、百万条合成数据的成对测试： +首次文件搜索前，请检查[索引范围](docs/INDEXING.md)：`indexedDrives` 为空时，会在条目上限内选择所有固定本地卷。设置位于 `%LOCALAPPDATA%\LocalContextEngine\settings.json`，应在采集前指定目标盘符。`path:` 仅筛选结果，不限制采集。备份个人偏好时保留设置和可选的 `usage.json`；索引是可重建的本地元数据。 -| 指标 | 优化前 | 优化后 | -|---|---:|---:| -| 加速索引构建 | 11.93 秒 | 8.91 秒 | -| 构建进程峰值工作集 | 1005.25 MB | 258.98 MB | -| `ext:pdf report` 平均 / P95 | 89.36 / 99.74 ms | 20.95 / 23.14 ms | -| 常见词 `report` 平均 / P95 | 8.34 / 9.61 ms | 8.47 / 9.87 ms | -| 估算保留加速索引 | 75.80 MB | 75.80 MB | +```powershell +.\localsearch.exe --help +.\localsearch.exe --providers +.\localsearch.exe --backend scan "type:file ext:pdf" +.\localsearch.exe --explain "ext:pdf report" +.\localsearch.exe "type:process python" +.\localsearch.exe --index-status +``` -内存收益是构建峰值下降，不能解读为保留索引变小。八组完整有序结果与线性参考一致。完整方法、环境信息缺口、样本数和非加速案例见[性能报告](docs/BENCHMARKS.md)。 +扫描后端不需要可选的特权服务。搜索有结果返回 `0`，合法查询无结果返回 `1`，操作无法完成返回 `2`。Provider 能力受 Windows 权限限制，实时结果和相对时间条件随系统变化。详见 [DSL 参考](docs/DSL.md)和[索引指南](docs/INDEXING.md)。 -## 安装 +使用桌面包时，运行安装程序，再启动 **Local Context Engine**。它需要 WebView2，并应在实际 Windows 环境验收；构建成功不能证明窗口正常渲染或搜索可用。 -从 [v0.2.0 Release](https://github.com/styayur/local-context-engine/releases/tag/v0.2.0) 下载 Windows x64 便携包或安装程序，对照 `SHA256SUMS.txt` 校验。解压后运行 `localsearch.exe`，可将目录加入 PATH。桌面需要 WebView2，应在实际机器上做启动与搜索验收。 +### 构建当前源码 -源码构建使用当前 stable Rust MSVC 与 Visual Studio C++ Build Tools： +使用 Windows x64、当前稳定版 Rust MSVC 工具链和 Visual Studio C++ Build Tools。桌面开发还需要 Node.js 22（CI 版本）、npm 和 WebView2。 ```powershell git clone https://github.com/styayur/local-context-engine.git cd local-context-engine -git checkout v0.2.0 cargo build --release --locked .\target\release\localsearch.exe --help ``` -无需安装特权服务即可使用普通用户目录扫描。共享机器启用 MFT 前，请先阅读[权限边界](docs/SECURITY.md#mft-and-permissions)。 +这些命令构建当前默认分支，不是已发布的 v0.2.0 Tag。默认 Cargo 成员包含 CLI 和 MCP 服务，不包含桌面依赖栈；桌面打包与输出路径见[开发说明](docs/DEVELOPMENT.md)。 + +从源码启动桌面：在 `apps/desktop` 先运行 `npm ci`，再运行 `npm run tauri:dev`；Tauri 会打开原生窗口并启动开发服务器。 + +### 连接 MCP 客户端 + +构建后，`target/release/localsearch-mcp.exe` 通过本地 stdio 提供 MCP。在客户端配置中，将示例路径替换为程序的绝对路径： + +```json +{ + "mcpServers": { + "localsearch": { + "command": "C:\\tools\\lce\\localsearch-mcp.exe" + } + } +} +``` + +`search_system`、`compile_query` 等工具见 [MCP 工具与协议示例](docs/MCP.md)。搜索本身在本地执行，但 MCP 客户端或模型可能按自身隐私设置将结果发往其他服务。 -## 使用 +## 测试 / CI / 平台支持 + +[![CI](https://github.com/styayur/local-context-engine/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/styayur/local-context-engine/actions/workflows/ci.yml) + +在 Windows 的仓库根目录运行： ```powershell -localsearch --providers -localsearch --backend scan "type:file ext:pdf" -localsearch --explain "ext:pdf report" -localsearch "prefix:read" -localsearch "type:process python" -localsearch --index-status +cargo fmt --all -- --check +cargo clippy --all-targets --all-features -- -D warnings +cargo test +cargo build --release --locked ``` -查询退出码：`0` 有结果，`1` 查询有效但无匹配，`2` 操作无法完成。相对时间、实时快照和使用记录变化会影响结果。详见[查询引擎](docs/QUERY_ENGINE.md)、[DSL](docs/DSL.md) 与 [MCP](docs/MCP.md)。 +桌面检查在 `apps/desktop` 运行： + +```sh +npm ci +npm run lint +npm run typecheck +npm run build +``` + +[CI 工作流](.github/workflows/ci.yml)在 Windows 上执行 Rust 与桌面检查，包括在仓库根目录执行 `cargo check -p local-context-engine-desktop`。[CodeForge regression](.github/workflows/codeforge-regression.yml)是外部开发门禁，不是运行时或 Rust crate 依赖。Markdown 与链接检查见[文档检查](docs/DOCUMENTATION_CHECKS.md)。 + +## 已知限制 + +- 运行时后端支持 Windows，不提供 Linux 运行时支持。Cargo 声明 Rust 1.82，但 CI 检查当前稳定版，未验证该最低版本。 +- 文件搜索索引名称、路径与元数据，不搜索文件全文。全文、语义检索和模型查询编译器属于未来工作，不是当前能力。 +- 特权 MFT/USN 服务与桌面需跨机器验收。此前出现的 WebView 空白不能仅凭构建成功视为已解决。服务 ACL、日志回卷、回退与卸载仍需部署验收。 +- 路径缓存、元数据、设置和可选使用记录是敏感本地数据。特权服务可能显示普通目录遍历无法列出的文件名，但不授予文件内容读取权限；在共享机器启用前阅读[安全说明](docs/SECURITY.md)。 + +## 路线图 -## 安全与隐私 +v1.0 前需统一软件包版本、验证 Rust 最低版本，并完成全新安装、桌面渲染与服务验收。之后可改善元数据完整性和应用发现；语义或全文扩展必须显式选择启用。[路线图](docs/ROADMAP.md)与[发布准备](docs/RELEASE_PREPARATION.md)区分已实现流程、实验性部署路径和未来工作。 -默认检索不上传数据、不索引全文。路径缓存、元数据和使用记录仍是敏感本地数据。打开结果由 Windows 处理；结束进程需要确认。可选特权服务可能暴露普通目录遍历无法列出的文件名，但不会授予内容读取权限。详见[安全模型](docs/SECURITY.md)与[漏洞报告](SECURITY.md)。 +## 贡献 -## 开发 +遵循 [CONTRIBUTING.md](CONTRIBUTING.md)和[开发说明](docs/DEVELOPMENT.md)。可复现问题提交 [Issue](https://github.com/styayur/local-context-engine/issues)，漏洞按 [SECURITY.md](SECURITY.md) 报告。维护权限边界与中英文能力说明的一致性。 -[开发指南](docs/DEVELOPMENT.md)说明构建和检查；[贡献指南](CONTRIBUTING.md)说明扩展原则；[路线](docs/ROADMAP.md)区分发布门槛与未来能力；[变更记录](CHANGELOG.md)面向用户描述变化。 +## 许可证 -仓库许可证为 [MPL-2.0](LICENSE)。桌面 package 元数据仍有待对齐的许可证差异，见[许可证说明](THIRD_PARTY_LICENSES.md)。本仓独立运行，不依赖 CodeForge Engine 的运行时或 Rust crate。 +仓库 [LICENSE](LICENSE) 与 Rust workspace 声明 **MPL-2.0**。桌面包元数据仍写为 MIT，[第三方许可说明](THIRD_PARTY_LICENSES.md)记录了这一待解决的不一致。本次文档变更不修改许可证或包清单。依赖保留各自条款，发布声明的完整性仍需单独审核。 From 2c9252366baeafdce7a6081c93c6dc6bd92914bf Mon Sep 17 00:00:00 2001 From: styayur Date: Thu, 22 Oct 2026 13:02:41 +0800 Subject: [PATCH 2/2] Clarify first-run index scope and settings creation --- README.md | 12 +++++++++--- README.zh-CN.md | 12 +++++++++--- 2 files changed, 18 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 075d8fa..4f39172 100644 --- a/README.md +++ b/README.md @@ -34,9 +34,15 @@ Download the [Windows x64 portable ZIP](https://github.com/styayur/local-context Get-FileHash -Algorithm SHA256 ``` -Extract the portable archive. In PowerShell, open the directory containing `localsearch.exe` and run: +Before the first file search, review [index scope](docs/INDEXING.md): an empty `indexedDrives` setting selects all fixed local volumes, up to the entry limit. A `path:` filter restricts results, not collection. With clients closed, edit `%LOCALAPPDATA%\LocalContextEngine\settings.json` to select drives. If it does not exist, create that directory and a UTF-8 JSON file; this example selects only C. For an existing file, change only `indexedDrives` and preserve other settings: + +```json +{"indexedDrives": ["C"]} +``` + +Use valid JSON; an unreadable or invalid settings file falls back to defaults. Restart clients, and rebuild an existing index after changing scope. Back up settings and optional `%LOCALAPPDATA%\LocalContextEngine\usage.json` to preserve preferences; the index is rebuildable local metadata. -Before the first file search, review [index scope](docs/INDEXING.md): an empty `indexedDrives` setting selects all fixed local volumes, up to the entry limit. Settings are in `%LOCALAPPDATA%\LocalContextEngine\settings.json`; set the intended drives there before collection. A `path:` filter restricts results, not collection. Preserve settings and optional `usage.json` when backing up personal preferences; the index is rebuildable local metadata. +Extract the portable archive. In PowerShell, open the directory containing `localsearch.exe` and run: ```powershell .\localsearch.exe --help @@ -115,7 +121,7 @@ The [CI workflow](.github/workflows/ci.yml) runs Rust and desktop checks on Wind ## Roadmap -Before v1.0, align package versions, validate the Rust minimum, and complete fresh-install, desktop-rendering and service acceptance gates. Metadata completeness and application discovery can improve later; semantic/full-text extensions must be explicit opt-in. See [Roadmap](docs/ROADMAP.md) and [release preparation](docs/RELEASE_PREPARATION.md), which distinguish implemented workflows from experimental deployment paths and future work. +Before publishing v1.0, update package versions together, validate the Rust minimum, and complete fresh-install, desktop-rendering and service acceptance gates. Metadata completeness and application discovery can improve later; semantic/full-text extensions must be explicit opt-in. See [Roadmap](docs/ROADMAP.md) and [release preparation](docs/RELEASE_PREPARATION.md), which distinguish implemented workflows from experimental deployment paths and future work. ## Contributing diff --git a/README.zh-CN.md b/README.zh-CN.md index 2dab1ed..5e504e2 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -34,9 +34,15 @@ Planner 属于文件 Provider，不是每个 Provider 的公共步骤。详见[ Get-FileHash -Algorithm SHA256 ``` -解压便携包，在 PowerShell 中进入包含 `localsearch.exe` 的目录，运行： +首次文件搜索前，请检查[索引范围](docs/INDEXING.md)：`indexedDrives` 为空时，会在条目上限内选择所有固定本地卷。`path:` 仅筛选结果，不限制采集。关闭客户端后，在 `%LOCALAPPDATA%\LocalContextEngine\settings.json` 选择盘符。如果文件不存在，创建该目录和 UTF-8 JSON 文件；下例仅选择 C 盘。已有文件只修改 `indexedDrives`，保留其他设置： + +```json +{"indexedDrives": ["C"]} +``` + +必须使用合法 JSON，文件不可读或格式错误时会回退到默认设置。修改范围后重启客户端；已有索引需重建。备份设置及可选的 `%LOCALAPPDATA%\LocalContextEngine\usage.json` 可保留偏好；索引是可重建的本地元数据。 -首次文件搜索前，请检查[索引范围](docs/INDEXING.md)：`indexedDrives` 为空时，会在条目上限内选择所有固定本地卷。设置位于 `%LOCALAPPDATA%\LocalContextEngine\settings.json`，应在采集前指定目标盘符。`path:` 仅筛选结果，不限制采集。备份个人偏好时保留设置和可选的 `usage.json`；索引是可重建的本地元数据。 +解压便携包，在 PowerShell 中进入包含 `localsearch.exe` 的目录，运行： ```powershell .\localsearch.exe --help @@ -115,7 +121,7 @@ npm run build ## 路线图 -v1.0 前需统一软件包版本、验证 Rust 最低版本，并完成全新安装、桌面渲染与服务验收。之后可改善元数据完整性和应用发现；语义或全文扩展必须显式选择启用。[路线图](docs/ROADMAP.md)与[发布准备](docs/RELEASE_PREPARATION.md)区分已实现流程、实验性部署路径和未来工作。 +发布 v1.0 前需一并更新各软件包版本、验证 Rust 最低版本，并完成全新安装、桌面渲染与服务验收。之后可改善元数据完整性和应用发现；语义或全文扩展必须显式选择启用。[路线图](docs/ROADMAP.md)与[发布准备](docs/RELEASE_PREPARATION.md)区分已实现流程、实验性部署路径和未来工作。 ## 贡献