接入 React/Vite 前端

已签名的 Knowledge Base Starter 0.1.0 提供可编辑的 Rust、Bun 与 React 源码。先按签名源码内容采用流程 预览并复制精确归档。使用 @lenso/cli@0.17.4，其原生 CLI 0.6.4 从已发布的 Rust 源码 ab09878c1d07235812a193c97b081686ff0d0943 构建；另外准备 Rust/Cargo、Bun 和可丢弃的 PostgreSQL 数据库。 Provider 初始化与凭据仍需显式准备。采用精确模板版本时使用 --marketplace、 --content-id 和尚不存在的 --content-destination，首次保留 --content-preview。 CLI 会核验当前目录和归档，不需要手工信任文件；复制源码不会配置 Provider， 也不授予构建权限。

参考 App 需要构建能接入 Bun Excerpt Plugin 的 linked Web Host。 仅支持 Process 的预编译 Host 无法运行这个 Bun Plugin。签名源码模板本身不会提供或激活 Host。

本地 Web App 快速开始先验证一次问候。本篇继续展示 普通 React 页面如何通过生成的类型调用 App 明确公开的 API。对于已准备的 源码 App，Lenso 会启动 Vite；另行构建后，静态资源由 Lenso Host 提供。 身份认证与授权仍由后端 Plugin 持有。

1. 启动前确认输入

模板归档对应 Fixture 的 project/ 目录；复制后根目录包含 app/ 与 frontend/。 先读精确源码版本的 fixtures/vnext-knowledge-base-app/README.md， 了解 Provider 配置与独立 Fixture 验证器。

公开包输入包括 @lenso/web-client 0.1.0、 @lenso/knowledge-excerpt 0.1.2、 Auth API-token 0.1.2、 Jobs 0.1.8 与 Secrets Env 0.1.7。采用前核对每个精确归档和签名身份； Registry 中存在某个包，不代表该 Provider 已有当前有效的签名目录条目。

原前端锁文件 project/frontend/bun.lock 指向本地 vendor/lenso-web-client.tgz，其字节与公开 npm 归档不同。 对于复制后归 App 所有的项目，可选择公开版本并审查 Manifest 与锁文件变更：

cd frontend
bun add --exact @lenso/web-client@0.1.0 --ignore-scripts
bun install --frozen-lockfile --ignore-scripts
bun run generate && bun run typecheck

下方原 Fixture 验证路径仍使用匹配的本地 Tarball，以及显式源码或签名 .crate Provider 输入。 验证器会创建 Schema 并留供检查，结束后不会重置数据库。 这条交互式凭据 Handoff 需要 POSIX no-follow 文件 API，不支持 Windows。

干净的 Fixture Checkout 不能直接运行 lenso app dev：Provider Plugin、 Operator 初始化、凭据与数据库配置均未准备。Fixture README 说明源码候选模式 与签名包模式。采用包时使用当前签名记录和公开归档摘要；AGENT_INPUT.md 中的 历史测试签名候选属于另一组输入。

2. 选择原 Fixture 验证路径

审查候选源码并准备隔离的本地构建环境后，Fixture 验证器可以在临时 App 中准备 Provider、从指定 Tarball 构建 React 页面、签发短期测试凭据、构建 Host，并通过 真实 HTTP Listener 检查业务路径：

cd /path/to/lenso-examples/fixtures/vnext-knowledge-base-app
HANDOFF_DIR="$(mktemp -d)" # Checkout 外私有的 0700 目录。
LENSO_REFERENCE_DATABASE_URL='postgresql://.../disposable_db' \
  python3 verify.py \
  --cli /absolute/path/to/lenso \
  --web-client-package /absolute/path/to/lenso-web-client.tgz \
  --framework-source /absolute/path/to/lenso-rust-checkout \
  --tool-provider-source /absolute/path/to/lenso-capability-agent-tool-provider \
  --auth-source /absolute/path/to/lenso-auth-plugin/crates/lenso-auth-api-token-plugin \
  --jobs-source /absolute/path/to/lenso-jobs-plugin/crates/lenso-jobs-plugin \
  --secrets-source /absolute/path/to/lenso-secrets-plugin/crates/lenso-secrets-env-plugin \
  --browser-handoff "$HANDOFF_DIR/browser-handoff.json"
rmdir "$HANDOFF_DIR" # 仅在验证器退出且 Handoff 文件已删除后执行。

Provider 和 App 构建可能执行包内构建脚本；未经审查的输入只能放在断网、受资源 限制的沙箱中运行。验证器会在该私有目录下独占创建权限为 0600 的 Handoff 文件，并拒绝已存在的文件或符号链接。文件含有效测试 Token 和 URL。验证器等待期间 （最多十分钟），打开该 URL、输入 Token、点击 Load workspace、创建一条 笔记，并确认处理后的摘录显示。再为这条笔记上传一个小文件，确认保存状态。 完成后删除 Handoff 文件，让验证器继续执行重启检查。最后的 rmdir 只会在 验证器退出后删除已空的私有目录。超时或 Ctrl-C 时，验证器会尝试核对 inode 再清理；在 POSIX 主线程中还会临时处理 SIGTERM 以执行清理。这些都是 尽力而为：同 UID 写入者可能在核对与按名称删除之间替换文件；SIGKILL、 进程崩溃或断电也可能留下文件。保持 0700 目录私有。若有残留，先停止 验证器，并仅在确认路径仍指向原 Handoff、而非替代文件后手工删除。 不要复用、提交或分享 Token。

成功运行会验证构建后删除源码的候选 App。提供 --web-client-package 时， 验证器会先用给定 Tarball 构建 React 页面；否则仍使用仓库内静态页面。 两种路径都不证明包已发布、Site 已部署或生产环境已受支持。

3. 在已准备的 App 中编辑 React 页面

对于 Provider、Schema Operator、凭据、Excerpt Plugin 和数据库设置都已经准备好的 App， 先将精确 Tarball 放到 Fixture 锁定的本地依赖路径。从 Fixture 目录使用 匹配的 CLI 和原 Fixture 的精确本地 Tarball 执行：

LENSO_CLI=/absolute/path/to/lenso
mkdir -p project/frontend/vendor
cp /absolute/path/to/lenso-web-client.tgz project/frontend/vendor/lenso-web-client.tgz
(cd project/frontend && bun install --frozen-lockfile && bun run generate && bun run typecheck)
"$LENSO_CLI" app dev --root project

project/frontend/lenso.dev.toml 选择 bun run dev，页面位于 http://127.0.0.1:5173/。Engine 通过 LENSO_API_URL_FILE 提供当前 Host URL 文件 project/.lenso/dev-backend-url；Vite Middleware 对每个允许的公开 请求重新读取该文件，并提供 GET /__lenso/backend 就绪握手。文件缺失或 无效时返回 503；Host 成功重建并换端口后，无需重启 Vite。Proxy 只转发 Fixture 的公开 notes、settings、jobs 和 attachment 路径，不开放 Host 管理接口或内部 Capability。等待 app dev 报告就绪后再打开 Vite 页面。

修改 React 页面后，停止开发循环，重新构建 Plugin 持有的静态资源，再构建 新的 App 分发目录：

(cd project/frontend && bun run build)
"$LENSO_CLI" app build --root project --out dist-react-review
"$LENSO_CLI" app check --root dist-react-review
"$LENSO_CLI" app show --root dist-react-review/intent --json
"$LENSO_CLI" app start --from dist-react-review --check

bun run generate 将已选 openapi.json 投影成 src/generated/api.ts。 src/main.tsx 中的页面通过 Bearer Token 回调创建 createLensoWebClient<paths>，并发出有类型的 GET/POST/PUT 请求。 unwrap 将 API 失败转换为 LensoApiError；类型生成不会让服务端输入自动 可信，也不会授予内部 Capability 的访问权。后端对每次请求校验 Actor 与资源 权限。Provider 边界见 Auth Plugin。

project/frontend/vite.config.ts 将构建结果写入 project/app/notes-web/public/。Vite HMR 不会更新已经构建的 App。 验证器的私有浏览器 Handoff 另行检查删除源码后仍可运行的 Host，而不是 可编辑的开发页面。

每次使用新的输出目录；app build 不覆盖已有目录。app start --check 只检查就绪后退出，不执行浏览器请求。完成标准是：验证器的浏览器请求使用 已签发 Token 成功、笔记可读回、未授权用户不能读取，构建后的 App 通过 check 和 show。本 Site 页面说明了检查方式，并不声称已对你的 Checkout 执行浏览器或构建测试。

让 Agent 完成同一任务

使用已签名的知识库源码模板和隔离的可丢弃数据库。
先核对已发布的 CLI、精确 Provider 输入与 npm 归档。
若选择原 Fixture 流程，保留匹配的源码版本和本地 Tarball，不要把公开字节直接替换进旧锁文件。
用私有浏览器 Handoff 运行 Fixture 验证器；在真实浏览器完成 Token 验证、
创建与读回笔记、上传文件，并检查验证器的跨用户拒绝结果。对于另外准备好的 App，
运行冻结的前端安装、generate/typecheck 和 app dev；修改后重新构建静态资源，
再执行 app build/check/show/start --check。
报告精确 Revision、包摘要、命令、浏览器 URL、结果与
缺失输入。不要把候选证明写成已发布或已部署的证明。

Agent 与手工操作使用同一个 App 和验收边界。Provider 或 Tarball 缺失是候选 步骤被阻断，不是绕过 Plugin Root 或把私有 Capability 暴露给浏览器的理由。