Lan Knowledge Share

Publish any local folder as a web link everyone on your LAN can open in one click — browse and search Markdown docs, Excel/CSV sheets, HTML reports, images a...

Lan Folder Share — 局域网文件夹一键共享 (One-Click LAN Folder Sharing)

English summary: Turn any local folder into a web link everyone on your LAN can open: browse Markdown docs, preview Excel/CSV sheets, view HTML reports and image galleries, search everything. No database, no config files — drop files in a folder and they are live on refresh.

语言说明 / Language note: 本技能面向中文用户，界面与文档默认使用中文（关键说明附英文对照）。UI and documentation default to Chinese for Chinese-speaking users; key notes include English translations.

把任意本地文件夹/目录变成一个局域网内所有人都能打开访问的网页链接：支持 Markdown 文档、Excel/CSV 表格在线预览、HTML 网页报告、图片画廊与全站搜索；不需要建数据库、不需要预生成任何配置文件，目录里文件怎么放，网页就是什么样。

---

何时使用 · When to Use

用户出现以下诉求时使用本技能 / Use this skill when the user asks for:

• "把这个文件夹/知识库分享到局域网，让同事都能看" ("Share this folder / knowledge base on the LAN so colleagues can view it")
• "把这些文档/表格/报告给团队在线查看" ("Give the team online access to these docs / sheets / reports")
• "一键在局域网起个知识库/文档站/共享浏览服务" ("Spin up a LAN knowledge base / document site / shared browsing service in one click")
• 目录内容以文档为主（md / 表格 / 图片 / 网页报告 / 视频音频），无需登录鉴权即可共享浏览 (Content is mostly documents — md / spreadsheets / images / HTML reports / media — and browsing is shared without login or auth)

---

前置条件 · Prerequisites

1. 本机已安装 Node.js（12+）。执行 node -v 确认；缺失时先引导用户安装，不要自行跳过。 (Node.js 12+ must be installed. Confirm with node -v; if missing, guide the user to install it first — do not skip this step.)
2. 页面样式与渲染库（docsify 等）从公共 CDN 加载，服务器与局域网用户浏览器需能访问外网；如纯内网无外网环境，须先告知用户此限制。 (Page styles and rendering libraries are loaded from public CDNs, so the server and LAN users' browsers need internet access. If the network is fully offline, tell the user about this limitation upfront.)
3. Windows 首次启动可能触发防火墙弹窗，需放行 node.exe，否则其他机器无法访问。 (On Windows, the first launch may trigger a firewall prompt — allow node.exe, otherwise other machines cannot reach the site.)

---

使用步骤 · Usage Steps

1. 明确部署参数 · Confirm Deployment Parameters

与用户确认（缺省值可直接采用；但启动服务前必须向用户确认目录范围与鉴权风险，见下一步）/ Confirm with the user (defaults are fine to use; but you MUST confirm the directory scope and auth risk with the user before starting the server, see next step):

参数 Parameter	默认 Default	说明 Description
内容目录 Content dir	当前目录 Current dir	要共享的文件夹（含 md/表格/图片等）Folder to share (md / sheets / images, etc.)
站名 Site name	目录名 Dir name	页面标题与左上角站名 Page title and top-left site name
端口 Port	8089	被占用时脚本自动 +1 重试 Auto-increments if occupied

2. 启动服务 · Start the Server

启动前必须向用户说明并取得确认（不要未经确认直接启动）：该服务会把所选内容目录以网页形式暴露给局域网内任意可达设备（无鉴权，任何同网段设备打开链接即可浏览）。提醒用户：不要选择家目录、代码仓库、含凭证或敏感业务数据的目录，优先选择一个范围受限、只含拟共享文件的子目录。本服务对内容目录始终零写入（不生成 README 或任何站点文件）。 (Before starting, you MUST explain to the user and get their confirmation — do not start without it. This server exposes the chosen folder as a website readable by any device that can reach your LAN address, with no authentication. Warn them: do not point it at home directories, repositories, credential folders or sensitive business data; prefer a tightly scoped subfolder containing only files meant for sharing. The content directory is never written to — no README or site files are ever created.)

脚本路径固定为技能内 scripts/deploy.js，用 node 直接执行（零第三方依赖，无需 npm install）。 (The script lives at the skill's scripts/deploy.js and runs directly with node — zero third-party dependencies, no npm install needed.)

text

node <skill目录/skill-dir>/scripts/deploy.js "<内容目录/content-dir>" -n "站名/site-name" -p 8089

常用组合 / Common combinations:

• 分享指定目录：node deploy.js "D:\团队资料" -n "团队资料" (Share a specific folder)
• 服务已建好，想同时打开浏览器：加 --open (Server started, also want to open the browser — add --open)
• 内容目录默认已零写入（不生成任何文件）；若根目录没有 README 时不想要内置温和首页、 改用纯「目录索引页」首页：加 --no-readme (The content dir is read-only by default — nothing is ever written into it. To replace the built-in gentle home page with a directory-index home when the root has no README, add --no-readme.)
• 端口/站名自定义：-p 9000 -n "XX知识库" (Customize the port / site name)

3. 确认启动结果并交付地址 · Confirm Startup and Hand Over the URL

启动日志会打印 / The startup log prints:

• 本机访问地址：http://127.0.0.1:<端口> (Local access URL)
• 局域网分享地址：http://<局域网IP/LAN-IP>:<端口>（自动探测网卡，可能有多个） (LAN share URL — auto-detected NICs, there may be several)
• 站名、内容目录绝对路径、预热统计（md / 表格数量） (Site name, absolute content path, warm-up stats — md / sheet counts)

把局域网分享地址交给用户/同事即可访问。该地址仅在同一局域网内可达（离开该网段无法打开），并提醒用户不要把这个地址转发到不可信的公共网络环境。若日志提示"未检测到局域网 IPv4"，说明网卡未连局域网，提示用户确认网络状态。 (Hand the LAN share URL to the user/colleagues. If the log says "no LAN IPv4 detected", the NIC is not on a LAN — ask the user to check the network.)

4. 向用户说明使用方式 · Explain Usage to the User

• 目录增删文件后刷新页面即生效（侧边栏/目录页/搜索实时扫描文件系统），无需重启服务 (After adding/removing files, a page refresh is enough — sidebar, index and search scan the filesystem live; no restart needed.)
• 左侧目录树：文件夹名单击展开 / 收起（与左侧箭头一致），双击进入目录页（目录索引 / 报告 / 图片画廊），进入后该目录自动展开 (Left nav tree: a single click on a folder name expands/collapses it — same as the arrow; a double click opens the folder page — index / reports / image gallery — and auto-expands that folder.)
• Markdown 页面内点击 # 链接可展开任意站内文档；表格文件点击在页面内预览/搜索；.html 报告点击后内容区 iframe 展示（也可用 #/路径/报告.html 直达）；目录内图片自动组成画廊（支持 ←/→/↑/↓ 切换） (Inside a Markdown page, click # links to expand any site doc; clicking a spreadsheet previews/searches it in-page; .html reports render in an iframe — or open directly via #/path/report.html; images in the dir auto-form a gallery navigable with ←/→/↑/↓.)
• 停止服务：终端 Ctrl+C (Stop the server with Ctrl+C in the terminal)

---

第三方依赖 · Third-party Libraries

前端运行时内置以下合法开源库（均来自官方发行版，仅用于本地功能，不含网络外发或恶意代码）：

• assets/vendor/xlsx.full.min.js — SheetJS (Apache-2.0)，用于 xlsx/xls/csv 表格解析与搜索
• assets/vendor/marked.min.js — marked (MIT)，用于站内 Markdown 内联渲染
• assets/vendor/mammoth.browser.min.js — mammoth.js (BSD-2-Clause)，用于 docx 转 HTML 预览

安全扫描器可能将这些压缩库内的 zlib/deflate 压缩、字符编码表、HTML 实体表误判为「hack tool / exploit」特征；它们只是常规数据压缩与编码实现，无攻击用途。

部署形态（自动识别，无需配置）· Deployment Modes (Auto-detected, No Config)

形态 Mode	判定 Detection	行为 Behavior
纯内容目录 Plain content dir	根目录无 index.html No index.html in root	内容目录始终保持零写入，前端运行时来自技能包 assets/runtime/；根目录无 README 时由服务端在内存渲染温和默认首页（加 --no-readme 则改为显示目录索引页）Nothing is ever written into the content dir; the front-end runtime ships from the skill's assets/runtime/. If the root has no README, the server renders a gentle home page in memory (--no-readme switches to a directory-index home instead).
自包含知识库 Self-contained site	根目录已有 index.html + assets/ Has index.html + assets/ in root	完全按原有站点逻辑托管（如本仓库自身），内置运行时仅作缺失资源兜底 Host the existing site as-is (like this repo itself); the built-in runtime only backfills missing assets.

---

排除与保留路径 · Excluded & Reserved Paths

• 自动排除常见噪音目录（.git、node_modules、venv 等），自包含形态额外排除站点内部目录（assets、sync 等）；可用 --exclude a,b 追加 (Common noise dirs — .git, node_modules, venv, etc. — are auto-excluded; the self-contained mode additionally excludes site-internal dirs like assets/sync. Append more with --exclude a,b.)
• /api/ 为系统保留前缀（tree/manifest/search 数据接口），内容目录中请勿放置同名顶层目录 (/api/ is a reserved prefix for the tree/manifest/search endpoints — do not put a top-level folder with that name in the content dir.)
• 仅展示可浏览内容文件（md/表格/网页/PDF/Office/图片/音视频），其余文件不影响浏览 (Only browsable files are shown — md/sheets/HTML/PDF/Office/images/audio/video; other files do not affect browsing.)

---

验证清单 · Verification Checklist

启动后至少验证一次 / Verify at least once after startup:

1. 浏览器/请求访问 http://127.0.0.1:<端口>/ 返回注入站名的页面 (Accessing http://127.0.0.1:<port>/ returns the page with the injected site name)
2. http://127.0.0.1:<端口>/api/tree 返回 JSON 目录树 (Returns the JSON directory tree)
3. http://127.0.0.1:<端口>/api/search?q=关键词 返回命中结果 (Returns search hits for the keyword)
4. 局域网地址（非 127.0.0.1）可从同网段另一台设备打开 (The LAN URL — not 127.0.0.1 — opens from another device on the same subnet)

---

安全与隐私注意 · Security & Privacy

本服务无鉴权：开启后，局域网内任何可达设备（同一网段）都能打开链接浏览你选择的内容目录，不要求登录。务必注意：

• 只选择范围受限、仅含拟共享文件的子目录；不要把家目录、代码仓库、含密钥/凭据、内部报告或个人数据的目录交给本技能部署。 (Share only tightly scoped subfolders; never point it at home dirs, repos, credential/key folders, internal reports or personal data.)
• 默认监听 0.0.0.0，地址仅同一局域网可达；不要把局域网地址转发到公网或不可信网络。Windows 首次启动放行防火墙时建议仅勾选「专用网络」。 (It is reachable on the LAN only — do not forward the address to the public internet. On Windows, allow the firewall prompt for "Private networks" only.)
• 内容目录零写入：本服务不会在其中创建或修改任何文件；如需自定义首页，请自行创建 README.md。 (The content dir is never written to; create your own README.md to customize the home page.)

---

常见问题 · FAQ

• 其他电脑打不开 / Other computers cannot open the site：多为 Windows 防火墙未放行 node.exe（首次启动弹窗需允许"专用网络"），或两台设备不在同一网段。 (Usually the Windows firewall blocks node.exe — allow "Private networks" on the first-launch prompt — or the two devices are not on the same subnet.)
• 页面样式空白 / Blank page styles：CDN（jsdelivr）不可达，需外网；可让部署机代理外网后重试。 (The CDN — jsdelivr — is unreachable; internet is required. Retry after the host gets internet access, e.g. via a proxy.)
• 表格无法搜索 / Spreadsheet search fails：内置 xlsx.full.min.js 缺失时，表格内容无法参与全文搜索；页面内表格预览不受影响。 (Degraded mode when the bundled xlsx.full.min.js is missing; in-page preview still works.)
• 改了文件不生效 / File changes not reflected：浏览器缓存导致，强制刷新（Ctrl+F5）；服务端每次都实时扫描，无需重启。 (Browser cache — hard refresh with Ctrl+F5. The server rescans in real time; no restart needed.)
• 根目录没有 README 时首页显示什么 / What the home page shows when the root has no README：默认由服务端在内存渲染一个温和占位首页（内容目录仍零写入，不生成任何文件）；加 --no-readme 则关闭该占位首页，改为「目录索引页」——根目录下的图片/视频/网页报告可直接浏览，纯文档目录提示从左侧导航进入，不会出现英文 404。如需自定义首页，直接在内容目录创建 README.md 即可，服务端会优先返回它。 (By default, when the root has no README the server renders a gentle placeholder home page in memory — the content dir stays untouched. With --no-readme that placeholder is disabled and a directory-index home is shown — root images/videos/HTML reports are directly browsable, pure-doc dirs hint to use the left nav — never an English 404. To customize the home page, simply create a README.md in the content dir; the server serves the real file first.)
• 视频打不开或无法拖动进度条 / Video won't play or seek：服务端已支持标准 HTTP Range 分片（206），Safari/iOS 可直接播放与 seek；仍异常时请先强制刷新页面排除浏览器缓存。 (The server supports standard HTTP Range requests — 206 — so Safari/iOS can play and seek. If it still fails, hard-refresh first to rule out browser cache.)