{"_id":"@buckeyestudio/toh-file-reference","name":"@buckeyestudio/toh-file-reference","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","description":"File-reference discovery contract and shared @file grammar","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"},"type":"module","main":"lib/index.js","types":"lib/types/index.d.ts","exports":{".":{"types":"./lib/types/index.d.ts","default":"./lib/index.js"},"./grammar":{"types":"./lib/types/grammar.d.ts","default":"./lib/types/grammar.js"},"./invariant":{"types":"./lib/types/invariant.d.ts","default":"./lib/invariant.js"},"./types":{"types":"./lib/types/types.d.ts","default":"./lib/types/types.js"},"./typert":{"types":"./lib/typert.host.d.ts","default":"./lib/typert.host.js"},"./remote":{"types":"./lib/typert.remote-client.d.ts","default":"./lib/typert.remote-client.js"},"./src/*":"./src/*","./package.json":"./package.json"},"license":"MIT","author":{"name":"buckeyestudio"},"peerDependencies":{"@buckeyestudio/toh-agent":"^0.1.1-rc.2","@buckeyestudio/toh-invariants":"^0.1.1-rc.2","@buckeyestudio/toh-typert-protocol":"^0.1.1-rc.2","@buckeyestudio/cordis":"^4.0.1"},"devDependencies":{"@buckeyestudio/toh-agent":"^0.1.1-rc.2","@buckeyestudio/toh-invariants":"^0.1.1-rc.2","@buckeyestudio/toh-typert-protocol":"^0.1.1-rc.2","@buckeyestudio/cordis":"^4.0.1"},"dependencies":{"zod":"^4.4.3"},"_id":"@buckeyestudio/toh-file-reference@0.1.1-rc.2","bugs":{"url":"https://github.com/dustinwloring1988/theopen-harness/issues"},"homepage":"https://github.com/dustinwloring1988/theopen-harness#readme","_integrity":"sha512-neFLGDDDn9crgRLzLGRGvcaYU1IoBoCDuYJGOUtyt+XgQEe6waBIeZ/g6A5XktzFb53o0iTDk1QPXpPy/NL4/w==","_resolved":"/home/runner/work/theopen-harness/theopen-harness/dist/npm/buckeyestudio-toh-file-reference-0.1.1-rc.2.tgz","_from":"file:/home/runner/work/theopen-harness/theopen-harness/dist/npm/buckeyestudio-toh-file-reference-0.1.1-rc.2.tgz","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-neFLGDDDn9crgRLzLGRGvcaYU1IoBoCDuYJGOUtyt+XgQEe6waBIeZ/g6A5XktzFb53o0iTDk1QPXpPy/NL4/w==","shasum":"6c809ecc11faf367d5a0fc49baafa59f2883dc34","tarball":"https://registry.npmjs.org/@buckeyestudio/toh-file-reference/-/toh-file-reference-0.1.1-rc.2.tgz","fileCount":19,"unpackedSize":56369,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDVkYxVzO9SDvwXzJL1CxVE7oeWV5hCt/Cy3NQ9bwoF1wIgRlqeim/mL5tm7Xk9WFG0WRQ0trWwRXd65lqZzYbXyrQ="}]},"_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_0.1.1-rc.2_1787489038690_0.6344173708891627"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-23T12:43:58.481Z","0.1.1-rc.2":"2026-08-23T12:43:58.838Z","modified":"2026-08-23T12:43:59.019Z"},"maintainers":[{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"}],"description":"File-reference discovery contract and shared @file grammar","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"},"author":{"name":"buckeyestudio"},"bugs":{"url":"https://github.com/dustinwloring1988/theopen-harness/issues"},"license":"MIT","readme":"# `@buckeyestudio/toh-file-reference`\n\n[English](README.md) | 中文\n\n文件引用发现 seam，以及供宿主驱动的用户界面共享、可在浏览器中安全使用的 `@file` 语法。`ctx.fileReferences.list(agent, query, signal)` 为指定 agent（智能体）返回仅含路径的文件或目录候选；具体提供方负责命名空间访问、排序、缓存和失效处理。同一契约以一元 `fileReferences/list` Remote 方法对外可调（`@Remote` 标注在 Service Definition 上，经保留的末位 signal 参数取消），浏览器消费方直接调用 `ctx.remote.fileReferences.list`，无需 API Proxy 路由。\n\n`activeAtToken()` 只在输入开头或空白后识别 `@path` 或尚未闭合的 `@\"path with spaces` token，因此类似电子邮件的文本不会打开补全。`formatFileMention()` 会生成与提示词匹配的写法，为目录候选追加 `/`，保留显式打开的引号，并拒绝编辑器语法无法安全表示的控制字符或内嵌引号。\n\n选择候选项不会读取或附加文件内容。导出的 `FILE_REFERENCE_PROMPT` 是稳定指引；当指定 agent 可以调用 `read` 时，提供方可以安装该指引。\n\n## 模型体验\n\n间接影响模型体验：`@buckeyestudio/toh-file-reference-local` 会按条件贡献本包的稳定文件引用指引。\n\n#### KV 缓存影响\n\n接口和语法本身不会增加请求 token；缓存行为取决于提供方拥有的提示词段。\n\n## 已知限制与暂缓事项\n\n- **路径候选仅供参考**：该 seam 不保证后续面向模型的文件系统工具能够访问同一命名空间；部署时必须让提供方与实际生效的 `read` 实现对齐。\n- **没有文件内容引用对象**：所选文件仍是普通提示词文本，其内容必须经过模型显式调用工具后才对模型可见。\n","readmeFilename":"README.zh.md","_rev":"1-d0b68dd2a96c1ce00eb6720d8a67e9d0"}