TagsPythonaiohttp开源项目AI工具前端工程工具分享ClaudeChatGPT专栏「工具开源」/「DocCenter」一、痛点AI 时代的文档散落病过去一年我每天被 AI 生成的 HTML 文件淹没。Claude artifacts 一天 20 个、ChatGPT canvas 一天 10 个、Cursor / CodeBuddy 生成的报告一天 5-8 个。它们散落在十几个文件夹里双击只能看改一个错字得翻出原始 prompt 重跑一遍找历史版本找不到。我试过几条路都不通方案不通在哪VSCode看 HTML 要预览插件编辑富文本得切到源码模式Notion不接受 HTML 上传复制粘贴丢失样式浏览器收藏夹不能编辑不能批注自建静态站太重每次都要 build deploy所以我写了DocCenter一个跑在localhost:9901的本地工作台专门治这个病。仓库地址https://github.com/louisecxqiu-glitch/html-doc-center二、技术选型为什么是单 Python 文件 vanilla JSDocCenter 整个后端是一个server.py零requirements.txt唯一外部依赖是aiohttp。前端是 vanilla JS没有构建步骤。这不是炫技是有意为之。三个关键决定2.1 选 aiohttp不选 FastAPI维度aiohttpFastAPI冷启动0.3s1.5spydantic 加载内存~30MB~80MB心智负担一个web.RouteTableDef完事还要懂 Pydantic models工作台不是产品是自己每天用的工具。冷启动快、内存小比规整 OpenAPI 文档重要 100 倍。我自己 Mac 上同时还跑着 dashboard9900、心跳4011、cockpit8088……每个都吃 80MB 我不答应。2.2 选 vanilla JS不选 React零构建 零心智负担。修一个 bug 不需要npm install→npm run build→ 刷新而是改 → CmdShiftR。唯一嵌入的依赖是marked.min.jsMarkdown 渲染MIT平铺在web/vendor/。整个web/目录 8 个文件就是全部前端代码。2.3 选 iframe不选 SPA 路由被编辑的 HTML 文件是完整页面——它有自己的 CSS 动画、JS 交互、外链字体。如果把它的 body 抠出来塞进 SPA那些上下文全丢了。iframe 让每篇文档保留完整运行时DocCenter 只在它的/body前注入一段saver-runtime.js提供编辑工具栏和自动保存能力。保持原文件运行时不被污染是 v1.0 就立的规矩。三、核心架构三段式┌─────────────────────────────────────────────────────────────┐ │ Browser at localhost:9901 │ │ │ │ ┌─────────────────┐ ┌──────────────────────────────────┐ │ │ │ web/app.js │ │ iframe │ │ │ │ (sidebar tree) │ │ ┌────────────────────────────┐ │ │ │ │ │←─→│ │ users HTML │ │ │ │ │ │ │ │ injected saver-runtime.js│ │ │ │ └─────────────────┘ │ └────────────────────────────┘ │ │ │ ↕ HTTP JSON └──────────────────────────────────┘ │ └─────────┼───────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ server.py (aiohttp, single file) │ │ ┌───────────┬──────────────┬──────────────────────────────┐│ │ │ Static │ Tree/Config │ HTML Read/Write ││ │ │ / │ /api/tree │ /api/file (inject saver) ││ │ │ /static/* │ /api/config │ /api/snapshot ││ │ │ /changelog│ │ /api/save (overwrite/new/ ││ │ │ │ │ discard) ││ │ └───────────┴──────────────┴──────────────────────────────┘│ └─────────────────────────────────────────────────────────────┘3.1 后端 server.py路径安全是唯一硬约束所有 I/O handler 都必须先过_resolve_safe()把传入路径 resolve 成绝对路径再校验它在某个scan_root之下否则返回 403。def_resolve_safe(raw:str,scan_roots:list[str])-Optional[Path]:The single gate for path traversal defense.try:targetPath(raw).expanduser().resolve()except(OSError,RuntimeError):returnNoneforrootinscan_roots:root_pathPath(root).expanduser().resolve()iftargetroot_pathorroot_pathintarget.parents:returntargetreturnNone# caller returns 403新增任何 I/O handler 都禁止绕过它——这是 v1.0 就定下的硬规矩到 v1.11.11 都没破例。scan_roots配置在~/.codebuddy/html-doc-center/config.json前端设置面板可增删。默认排除_auto-save / node_modules / .git / dist / build等。3.2 saver-runtime.js脏状态监听的三道护栏这是项目最难的一段。dirty 检测必须只在用户主动编辑时为 true不能被页面 JS 动画 / scroll / 高亮触发。// 护栏 1用户交互窗口constUSER_INTERACT_WINDOW_MS800;letlastInteract0;[keydown,mousedown,paste,cut,drop].forEach(evdocument.addEventListener(ev,(){lastInteractDate.now();},true));// 护栏 2MutationObserver 配置只看 childList characterDataconstmonewMutationObserver(mutations{if(Date.now()-lastInteractUSER_INTERACT_WINDOW_MS)return;if(mutations.some(mm.target.tagNameSCRIPT||m.target.tagNameSTYLE))return;setDirty(true);});// 护栏 3延迟 1 秒 observe避开页面初始化setTimeout((){mo.observe(document.body,{childList:true,characterData:true,subtree:true// 严禁 attributes: true会被动画/滚动高亮误报});},1000);这三道护栏是 v1.2.4 一次脏状态误报 bug 后立的至今没退化。修改这段代码前必读注释——容易被看似优化地打开attributes: true立刻退化。3.3 前端 app.js唯一的 UX 决策点是三选一对话框切换文件 / 关闭 / 刷新时若isDirtytrue弹出┌─────────────────────────────────────────┐ │ 你修改了文档 │ │ │ │ ✅ 覆盖源文件 │ │ 另存为审阅版 │ │ 丢弃修改 │ └─────────────────────────────────────────┘整个 UX 只有这一个决策点。v1.2.5 我尝试加过第四个 按钮“保存并继续编辑”实测后立刻撤了——决策点越多用户越累。少即是多不是口号是每次想加按钮时都得过的关。四、5 条反 Bug 铁律项目沉淀v1.0 → v1.11.11 连续 42 版迭代踩了一堆坑。其中 v1.11 系列连续 11 次 hotfix 把我教育到位逼出 5 条铁律全部写进ITERATION-SOP.md铁律 1真实浏览器演练 ——「curl 200」≠「用户视角能用」反面案例v1.11.10三 Tab 切换功能curl 返回 200lint 0 错误我宣称完成。用户实测切到「收藏」「最近」Tab 显示空白。根因CSS 的.active { display: block }干不过 inline 的styledisplay:noneHTML 里有历史残留。铁律commit 前必须在浏览器硬刷新CmdShiftR 用户视角点 3 个核心交互。验收报告不能只贴 curl 200要写我在浏览器点了 X 看到了 Y。铁律 2守卫表达式必须显式验证反面案例v1.11.11if (window.sidebarTabsCtl)永远 false因为sidebarTabsCtl是 IIFE 内的const从未挂到window上。// ❌ 永远进不来(function(){constsidebarTabsCtl{activate:...};})();if(window.sidebarTabsCtl){...}// false forever// ✅ 闭包内直接引用(function(){constsidebarTabsCtl{activate:...};functiononClick(){sidebarTabsCtlsidebarTabsCtl.activate(tree);}})();铁律写if (X)前确认 X 在该 scope 的真实可见性。铁律 3CSS 改 .active / display 前 grep inline style 残留铁律CSS 优先级 inline id class tag。改新 class 控制显示前先grep旧 HTML 是否有同名 inline style“display:none” 残留——它会压住 CSS。!important是最后一招。铁律 4DOM 切换后的依赖动作必须用 rAF反面案例v1.11.11点击收藏目录 →activate(tree)切 display → 立刻scrollToPath()算位置 → 在旧布局上算 → 视觉零反馈。// ❌ 在旧布局上算位置sidebarTabsCtl.activate(tree);scrollToPath(path);// getBoundingClientRect returns stale values// ✅ 等下一帧sidebarTabsCtl.activate(tree);requestAnimationFrame((){scrollToPath(path);});铁律 5自驱模式 ≠ 跳过用户视角用户说自驱不要打断指的是不要发决策卡片不是免除验收。每 2-3 个版本最少一次假装我是用户演练。CHANGELOG 用户故事段写得越漂亮越要在浏览器里真实验过——否则就是文档自我催眠。五、Quick Start v1.12 RoadmapQuick Start3 行gitclone https://github.com/louisecxqiu-glitch/html-doc-center.gitcdhtml-doc-center pip3installaiohttppython3 server.py# → 打开 http://localhost:9901macOS 开机自启cplaunchd.plist.example ~/Library/LaunchAgents/com.louis.html-doc-center.plist launchctl load ~/Library/LaunchAgents/com.louis.html-doc-center.plistv1.12 Roadmap计划中全文搜索FTS5 防抖HTML 块级编辑增强拖拽重排、批量样式多窗口同步一个文件多 tab 打开时的状态广播移动端触屏阅读模式侧栏抽屉化详见docs/superpowers/plans/2026-05-14-v1.12-roadmap.md。六、仓库与联系方式⭐GitHub: https://github.com/louisecxqiu-glitch/html-doc-center Issues / Discussions / PRs 都欢迎 —— 见 CONTRIBUTING.mdConnect 「一深思AI」—— 配套深度文章《养虾系列》AI Agent 实战方法论 CSDNblog.csdn.net/qcx23 X / Twitterlouisqiu285052如果这工具对你有用star 一下是对开源最好的支持。Issue / PR 都欢迎慢慢养。Built with ❤️ by Louis Qiu · MIT Licensed · 路易乔布斯 © 2026