Read Only Viewer zh CN

只读可视化界面

语言： English · 简体中文

lwc view 会启动一个本地浏览器界面，用于查看单个 live Wiki。它以前台方式运行，只监听 loopback，并且不会迁移、刷新、索引或修改项目。

Viewer 适合直观理解 Wiki；所有写入、恢复与正式验收仍应通过 CLI 完成。

启动 Viewer

lwc --scope project view
lwc --scope project view --port 4173 --no-open

默认端口为 0，由操作系统分配空闲端口。启动时会输出 JSON，其中包含 URL、绑定地址、read_only=true 以及是否成功打开浏览器。

未指定 --no-open 时，LWC 会调用当前平台的浏览器启动器。如果打开失败，手工访问输出的 URL 即可。回到启动终端按 Ctrl+C 可以停止服务。

Viewer 只读取 live Wiki，不支持 --scope all 或 changeset selector。

界面内容

区域	展示内容	边界
概览	数据库路径、revision、operation ID、Page 与 Source 数量	当前选中的 Wiki
页面	Page 列表与渲染后的 Markdown 正文	最多列出 1,000 个 Page
来源	Source ID、标题或 origin、字节数	最多列出 1,000 个 Source
知识图谱	规范 Wiki Page 之间的链接	最多 1,000 个节点、5,000 条边
代码图谱	项目 CodeGraph 数据库中的节点与边	lwc cg init 后可用；最多 1,000 个节点、5,000 条边
词网图	由查询限定的词—文档局部样本	每页 25 个文档、30 个词

知识图谱 页展示的是 Wiki Page link network，由规范页面及其 [[wikilinks]] 组成，并不是把 Grafeo/SurrealDB 外部文档图完整倒进浏览器。

代码图谱 页以 SQLite 只读模式读取现有项目 CodeGraph 数据库。Viewer 不会下载 CodeGraph、执行 cg init 或刷新索引；索引不存在时只给出如何在 Viewer 外初始化的提示。

词网图采用查询优先

词网图初始不加载任何数据。输入一到八个可检索词后，LWC 先取得有界候选文档页，再只计算样本中的词与归属关系。

浏览器每次请求 25 个文档和 30 个词，并提供上一页、下一页。API 会钳制更大的请求，同时返回截断诊断。这样可以避免把高密度 token 数据一次性做成全局大图。

分词方式、限制和解释规则见词图网。

交互图操作

知识图谱、代码图谱与词网图共用一套本地 3D 关系视图：

• 拖动旋转；
• 滚轮缩放；
• 标签始终跟随节点；
• 连接度更高的节点会获得更强视觉强调；
• 底部显示可见节点、边数量及是否受到边界截断。

可视化用于探索，不能替代图一致性校验。准确节点、路径、影响分析、Work 和 verify 仍应使用对应 CLI。

语言行为

Viewer 默认显示英文，可通过 中文 / EN 控件切换界面语言，选择结果保存在浏览器 local storage 中。

切换只影响界面文案。Page 正文、Source 标题、标识符、代码符号和图标签都不会被自动翻译。

只读契约

Viewer 的边界如下：

• 只绑定 127.0.0.1；
• 只开放 GET 与 HEAD 路由，写方法返回 HTTP 405；
• 以只读方式打开 Wiki 与 CodeGraph 数据库；
• 不会初始化或切换图引擎；
• 不会启动文档图构建或 CodeGraph 索引；
• 不会刷新历史 Source revision；
• JavaScript 与 CSS 内嵌发布，不依赖 CDN，运行时不需要 Node.js；
• 渲染 Markdown 前会清理内容，移除脚本、主动嵌入、图片、内联 style 属性和 style 元素；
• 返回严格 Content Security Policy 与 nosniff 响应头。

启动 Viewer 并读取所有 endpoint 都不应改变持久项目状态。SQLite 可能维护瞬时只读锁信息，但 Viewer 不执行规范或派生写入。

本地安全边界

Loopback 绑定可以阻止直接网络暴露，但不等于身份认证。同一主机、同一用户下的其他进程仍可能在 Viewer 运行期间访问这个随机本地端口。

• 不要把 URL 反向代理到公网；
• 不要在不可信的共享账号下运行 Viewer；
• 查看结束后及时停止；
• 把 Page 正文、Source origin、代码路径和图标签视为潜在敏感项目数据。

所有资源都由服务内嵌，响应也设置了 frame-ancestors 'none'；但浏览器扩展与本地恶意程序仍不在 LWC 的信任边界内。

API 范围

Viewer 使用以下本地只读 API：

GET /api/status
GET /api/pages?limit=1000&offset=0
GET /api/pages/{slug}
GET /api/sources?limit=1000&offset=0
GET /api/graphs/knowledge
GET /api/graphs/code
GET /api/graphs/words?query=...&limit=25&term_limit=30&offset=0

这些 endpoint 是内嵌 UI 的实现接口，不是带版本保证的远程集成 API。自动化应优先使用稳定的 lwc JSON CLI 或只读 MCP 工具。

常见问题

• view_bind_failed：使用端口 0，或选择其他空闲 loopback 端口。
• 浏览器没有打开：加 --no-open 重新运行，再访问输出的 URL。
• 代码图不可用：先运行 lwc --scope project cg status；确有需要并获得明确同意后，在 Viewer 外初始化。
• 词网图拒绝查询：提供一到八个可检索词。
• 图显示截断：改用 CLI 图探索或翻到下一页词图样本，不要无界扩大整个可视化。
• 数据看起来陈旧：停止 Viewer，通过对应 CLI 完成修复或刷新并验收，再启动新进程。

完成证据

一次 Viewer 查看满足以下条件才算完成：

• 启动结果包含 loopback URL 与 read_only=true；
• 已看到目标 Page、Source 或有界图样本；
• 不可用的图能力保持关闭，没有隐式初始化；
• 关于正确性的结论均使用 CLI 验证；
• Ctrl+C 停止前台服务并关闭端口；
• Viewer 请求没有改变持久 Wiki 与索引状态。