@llangtop/pwiki-webpage

pwiki-webpage 是浏览器页面适配器，和 Pwiki/api 分离：

Pwiki/core       领域能力和索引
Pwiki/api        Node HTTP API 服务
Pwiki/webpage    浏览器页面、页面状态和 HTTP client

页面层只能通过 /api/v1 访问知识库。它不应把 @llangtop/pwiki-core 打进浏览器 bundle，也不应启动 CLI 或 MCP 子进程。

作为 Node 项目依赖安装：

npm install @llangtop/pwiki-webpage @llangtop/pwiki-api @llangtop/pwiki-core

发布包只包含构建后的 dist 和本说明文件；构建流程会复制页面 HTML/CSS、WebApp manifest、Service Worker 和安装图标到 dist。 安装后可直接使用包声明的页面服务命令：

npm install -g @llangtop/pwiki-webpage
pwiki-webpage --base-path /absolute/path/to/wiki-home --allow-source-management

如果使用当前 monorepo 的本地工作区，可以使用根工作区声明的快捷命令；参数会继续传给 页面服务：

npm run webpage
npm run webpage -- --base-path /absolute/path/to/wiki-home --allow-source-management

也可以通过下面的 npm run start -w 启动。

当前页面服务由两个显式边界组成：

• PwikiApiClient：浏览器安全的 HTTP client；
• createPwikiWebpageServer() / startPwikiWebpage()：静态页面服务，可在显式启动 时把 API handler 挂载到同一进程。

执行 npm start -w @llangtop/pwiki-webpage 时才会监听端口，默认是 127.0.0.1:4317；它不会因为导入页面 client、构建或打开包而静默启动 API。

浏览器 client 统一封装：

• status / sources；
• source-relative 文件浏览；
• keyword / semantic / hybrid 搜索；
• 二次精排状态读取和开关；
• 条目读取；
• 创建、修改、重命名、移动和删除请求。

页面当前已提供：

• source 列表和 source 内可展开的 Markdown 文件树；
• keyword / semantic / hybrid 搜索结果；
• 搜索历史：离开搜索页后保留当前查询和结果，刷新后恢复最近 8 条历史；
• 安全转义的 Markdown 阅读器，以及共享草稿的预览式编辑和源码模式；
• 创建、覆盖保存、重命名、移动、删除、刷新、加载和卸载 source；
• 右侧 Markdown 大纲和文件属性操作区；
• 顶部窗口管理：已打开/未打开页面、窗口压缩/堆叠和独立的新建工作区；
• 新工作区中的最近关闭 Markdown 列表，点击即可恢复，最多保留 8 条浏览器本地记录；
• 夜幕紫、纸张米白、海湾蓝、松林绿、玫瑰粉、琥珀橙，以及 VSCode 现代/经典黑白、高对比度、OLED 优化、现代黑色等配色；
• 文件栏和大纲栏可拖动调整宽度，文件树支持横向滚动，大纲标题最多显示三行并自动省略；
• 两侧栏收起后对应网格列为零，不会继续占用 Markdown 展示区或制造中间空白；
• 页面提供 WebApp manifest、同源 Service Worker 和 Chrome 安装提示，允许在 localhost 或 HTTPS 上安装为独立 WebApp。

页面保存、移动、重命名和删除后会重新读取条目、文件树和状态；API 响应保留 BM25/向量维护的状态边界。编辑器的阅读、预览式编辑和源码模式共享同一份未保存草稿， 切换模式不会丢失内容；保存后 core 仍按文件更新 BM25，并按 embedding 内容 hash 复用未变化的 AST chunk。Markdown 渲染只允许受限的安全链接，不把原始 HTML 直接插入页面。

搜索历史和最近关闭文件只写入浏览器 localStorage，不写入知识库文件；重新打开条目 时仍通过 /api/v1/entry 读取最新内容。关闭窗口记录的是 Markdown 窗口，删除文件不会 被错误地加入最近关闭列表。

页面的视觉方向参考 Obsidian 的公开插件/主题生态，而不是其未公开的桌面核心： 文件树 + 搜索 + 阅读/编辑的三栏工作区、CSS 变量主题和显式用户操作。详情见 Pwiki/api/README.md 的借鉴边界。

npm run build -w @llangtop/pwiki-webpage
npm run start -w @llangtop/pwiki-webpage

默认监听 127.0.0.1:4317。页面服务同时挂载 /api/v1，也可以显式指定知识库目录 和数据源管理权限：

npm run start -w @llangtop/pwiki-webpage -- \
  --host 127.0.0.1 --port 4317 --base-path /absolute/path/to/wiki-home \
  --allow-source-management

独立 API 服务的路由表和启动边界见 ../api/README.md。