{"_id":"@buckeyestudio/toh-file-reference-local","name":"@buckeyestudio/toh-file-reference-local","dist-tags":{"next":"0.1.1-rc.2","latest":"0.1.1-rc.2"},"versions":{"0.1.1-rc.2":{"name":"@buckeyestudio/toh-file-reference-local","description":"Local-filesystem ctx.fileReferences provider with bounded fuzzy indexes","version":"0.1.1-rc.2","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/dustinwloring1988/theopen-harness.git","directory":"packages/context/file-reference-local"},"type":"module","main":"lib/index.js","types":"lib/types/index.d.ts","exports":{".":{"types":"./lib/types/index.d.ts","default":"./lib/index.js"},"./search":{"types":"./lib/types/search.d.ts","default":"./lib/types/search.js"},"./invariant":{"types":"./lib/types/invariant.d.ts","default":"./lib/invariant.js"},"./src/*":"./src/*","./package.json":"./package.json"},"license":"MIT","author":{"name":"buckeyestudio"},"dependencies":{"@buckeyestudio/schemastery":"^3.18.1"},"peerDependencies":{"@buckeyestudio/toh-file-reference":"^0.1.1-rc.2","@buckeyestudio/toh-agent":"^0.1.1-rc.2","@buckeyestudio/toh-invariants":"^0.1.1-rc.2","@buckeyestudio/toh-system-prompt":"^0.1.1-rc.2","@buckeyestudio/cordis":"^4.0.1","@buckeyestudio/toh-tools":"^0.1.1-rc.2"},"devDependencies":{"@buckeyestudio/toh-agent":"^0.1.1-rc.2","@buckeyestudio/toh-file-reference":"^0.1.1-rc.2","@buckeyestudio/toh-invariants":"^0.1.1-rc.2","@buckeyestudio/toh-tools":"^0.1.1-rc.2","@buckeyestudio/toh-system-prompt":"^0.1.1-rc.2","@buckeyestudio/cordis":"^4.0.1"},"_id":"@buckeyestudio/toh-file-reference-local@0.1.1-rc.2","bugs":{"url":"https://github.com/dustinwloring1988/theopen-harness/issues"},"homepage":"https://github.com/dustinwloring1988/theopen-harness#readme","_integrity":"sha512-6bnJnhMCSnsp9AUwMyfhYlWU2ZtwS6zEAFX1sm13K2TLiDw9c2FEsBG39654Ni5ER43uCCD71qBI7jleiQzANw==","_resolved":"/home/runner/work/theopen-harness/theopen-harness/dist/npm/buckeyestudio-toh-file-reference-local-0.1.1-rc.2.tgz","_from":"file:/home/runner/work/theopen-harness/theopen-harness/dist/npm/buckeyestudio-toh-file-reference-local-0.1.1-rc.2.tgz","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-6bnJnhMCSnsp9AUwMyfhYlWU2ZtwS6zEAFX1sm13K2TLiDw9c2FEsBG39654Ni5ER43uCCD71qBI7jleiQzANw==","shasum":"a718edb33eb396a594a9545de3d632b462c0c684","tarball":"https://registry.npmjs.org/@buckeyestudio/toh-file-reference-local/-/toh-file-reference-local-0.1.1-rc.2.tgz","fileCount":13,"unpackedSize":45014,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCndqaNpwY7RuJTK/ikMxk8iRbOT4Anxl4bdFEzuzf5SgIhAO05Tk16/vrAJY2WCOpRjS/R+FjmLuoy4iwXQxihZlI2"}]},"_npmUser":{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"},"directories":{},"maintainers":[{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/toh-file-reference-local_0.1.1-rc.2_1787489684959_0.5293486898947553"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-23T12:54:44.826Z","0.1.1-rc.2":"2026-08-23T12:54:45.076Z","modified":"2026-08-23T12:54:45.327Z"},"maintainers":[{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"}],"description":"Local-filesystem ctx.fileReferences provider with bounded fuzzy indexes","homepage":"https://github.com/dustinwloring1988/theopen-harness#readme","repository":{"type":"git","url":"git+https://github.com/dustinwloring1988/theopen-harness.git","directory":"packages/context/file-reference-local"},"author":{"name":"buckeyestudio"},"bugs":{"url":"https://github.com/dustinwloring1988/theopen-harness/issues"},"license":"MIT","readme":"# `@buckeyestudio/toh-file-reference-local`\n\n[English](README.md) | 中文\n\n`ctx.fileReferences` 的本地文件系统实现。它为每个 agent（智能体）维护一个有界的 `WorkspaceFileSearch`，以该会话的 `cwd` 为根目录；缺少该值时回退到宿主进程的 cwd。查询包含 `/` 时，索引会对直接列出的目录项排序；否则会对有界递归索引进行模糊排序。索引永远不会跟随目录符号链接。\n\n工具结果事件会使指定 agent 的可复用索引失效，使后续补全能够反映工作区中可能发生的变更。agent 的 dispose（资源释放）会释放该索引及其作用域内的提示词贡献；插件 dispose 会等待所有提示词 fiber，并释放全部缓存的搜索器。\n\n## 配置\n\n| 配置键 | 默认值 | 契约 |\n|---|---:|---|\n| `maxResults` | `20` | 单次查询返回的候选项最大数量。 |\n| `maxEntries` | `10000` | 每个 agent 工作区建立索引的文件和目录最大数量。 |\n| `excludedDirectories` | `[\".git\", \"node_modules\"]` | 遍历和候选项中排除的目录基名。 |\n\n所有数值都必须是正的安全整数。排除名称必须是非空基名，且不能包含 `/` 或 `\\`。\n\n## 模型体验\n\n### `read` 可用时的文件引用指引\n\n#### 模型看到什么\n\n当指定 agent 有实际生效的 `read` 工具时，提供方会贡献以下稳定的系统提示词段：\n\n##### 文件引用指令\n\n```markdown\nPaths prefixed with @ are files explicitly referenced by the user. Use the read tool when their contents are needed; do not claim to have inspected a file before reading it.\n```\n\n#### Token 影响\n\n该影响有条件且固定：只要 `read` 对指定 agent 可见，这一句就会存在；候选查询本身不增加 token，所选路径只会贡献普通用户消息中的对应字符。\n\n#### KV 缓存影响\n\n该稳定句子会加入系统提示词前缀。挂载或移除此提供方，或者改变 `read` 是否可见，都会改变该前缀；查询、候选项和索引失效不会改变前缀。\n\n## 已知限制与暂缓事项\n\n- **宿主本地命名空间**：提供方扫描 Harness 宿主的文件系统，因此远程或虚拟 `read` 实现需要使用命名空间与该工具一致的提供方。\n- **有界的提示性索引**：超大型工作区可能省略 `maxEntries` 之后的路径；被排除或无法读取的目录不会出现。\n- **没有忽略文件语义**：`.gitignore` 和其他项目忽略文件不会影响发现；系统只排除已配置的目录基名。\n","readmeFilename":"README.zh.md","_rev":"1-d46003bbcd67c8905473ebec2fae5be5"}