Skip to content

Latest commit

 

History

History
55 lines (44 loc) · 8.47 KB

File metadata and controls

55 lines (44 loc) · 8.47 KB

CONTEXT

本仓领域词汇表。只放词与定义,不放实现细节。

graphwatch

  • 注册表(registry):被监听目录的清单,add/remove 读写,daemon 热加载。
  • 补课(catchup):daemon 启动或热加载新目录时,发现图谱落后于源码就入队重建的行为。只在挂载那一刻发生一次,之后靠监听。
  • 新鲜度(freshness):单目录图谱是否落后于源码的状态。四态:新鲜 / 未构建 / 过期 / 更新中。daemon 在跑且源码有变更 = 更新中;没跑才是过期。
  • 监听与重建分离:watchdog 线程只负责发现变更(轻),重建走全局队列由 worker 执行(重)。同一目录的变更在队列里去重合并。
  • 重建并发(rebuild concurrency):同时执行重建的目录数,最小 1,默认 1(串行)。
  • 服务管理(service management):把 daemon 注册成用户级系统服务的动作集合——install / uninstall / start / stop / restart / registered / state。与 daemon 内部逻辑互不感知。
  • 平台 adapter:服务管理在某平台的具体实现(macOS launchd / Linux systemd --user / Windows schtasks)。平台差异只存在于 adapter 内部。

browse(浏览器控制)

  • context(上下文):一个可被指令作用的浏览上下文,即一个标签页或其中一个 frame。id 约定:顶层标签页是 "<tabId>",子 frame 是 "<tabId>.<frameId>"。选哪个 context 的优先级恒为 --context <id> > --match-url '<glob>'(命中多个就报错要求收窄)> 当前活动标签页。
  • element(元素):context 里的一个 DOM 节点,指令的作用对象。永远由 locator 现场解析得到,不在进程间传递句柄。
  • locator(定位器):一条描述「找哪个元素」的字符串,四种 scheme 前缀分派——css= / text=(text*= 为包含匹配)/ xpath= / js=,不写前缀默认 css=。js= 在 MAIN world 求值,是唯一能穿透 shadow DOM 的方式,也因此算高危动作。默认自动等待最多 5 秒直到元素出现且可交互。
  • daemon(常驻中转):本机一个 Unix socket 服务端,站在 CLI 与浏览器之间。存在的理由:浏览器只会 fork native host,而用户敲命令的 CLI 是另一个进程,两者天生连不上。只做传输与路由,不懂指令语义。
  • native host(本机宿主):浏览器按 native messaging 协议 fork 起来的那个进程,实为 browse --native-host。一头是浏览器给的 stdin/stdout 管道,一头是 daemon 的 socket,只搬运不解释。
  • command(指令):一条 WebDriver BiDi 形状的请求信封 {id, method, params},method 写成 <module>.<action>(私有能力带 lg: 前缀,如 lg:history.search)。回包只有 Success / Error 两种,错误码用 BiDi 标准枚举或带冒号的扩展码。
  • 策略目标(policy target):一条指令真正作用到的页面地址,由 context / match-url / 当前标签页解析而来。dispatch 在执行前解析一次,拒绝名单、功能开关、确认、执行、审计共用同一份;读不到地址即拒绝(fail closed)。没有页面目标的全局动作(如 history.search)没有策略目标。
  • 归属(ownership):一个页面「是不是 browse 自己的」的状态。硬规则:页面方法只许落在自己的页面上,无开关。判定永远懒做——命令到达时查该标签页当前在不 在自己的组里,不监听任何事件。
  • 专属组(dedicated group):browse 在普通 Chrome 窗口里维护的 browse/<用途> 组,自己开的页面全部进入对应组。组名表达项目或任务用途(例如 browse/a.com、browse/research);组的存在本身就是归属标记和视觉隔离;用完用 browse group dissolve <用途> 回收。
  • 组成员身份真源(group membership as the source of truth):在专属组里 = 自己的页面,是唯一判据。用户把标签拖进组即接管、拖出即放走;拖动就是授权/撤权的手。
  • 收编(adopt):把 browse 没开过的已有页面变为自己的动作(lg:tabs.adopt)。matchUrl 在全浏览器里找,收编即加入指定的 browse/<用途> 组(默认 browse/default),并过确认策略。
  • 登记表(ownership registry):自己开过/收编过的页面的 origin+path 清单(LRU 上限 50,存 chrome.storage.local)。唯一用途:浏览器重启后按 URL 把现存标签页认领回组。
  • 页面缓存(page cache):text/html 正文读取结果在扩展端的留存(每页最近 5 份、全局 100 份,导航/关页即失效)。读命令永远现读;缓存只由 browse page cache [index] 显式取回,0 = 最新。
  • 认领(reclaim):重启后第一条命令触发 ensureOwn 重建组时,顺手把登记表匹配的现存标签页收回组的动作。没有启动事件,纯懒触发。
  • 停止(stopped):连接生命周期的单一状态,表达「用户不要自动重连」。持久化,跨 Service Worker 重启保持;用户 connect 或浏览器完整启动才解除。

viewer(本地文件展示)

  • 纯文本页(plain-text page):浏览器没有当成网页渲染、只是把文件原文倒出来的那一类页面。判定三件事同时成立:document.contentType 是纯文本类、body 下恰好一个 <pre>、document.title 为空。不限 file://,任何来源都算。
  • 美化(prettify):把一张纯文本页换成按文件类型渲染过的样子——markdown 渲染、代码高亮、json/yaml 折叠树、csv 表格、log 分列上色。反面是原始(raw),即那张纯文本页本来的样子。两者随时可切,切换状态不跨页记忆。
  • 接管(takeover):viewer 决定对某一页做美化。三档:白名单内的文件类型直接接管;明确是网页的不碰;剩下拿不准的不接管,只浮一个「美化一下」按钮交给人点。
  • 方言(dialect):markdown 的一种扩展写法。本仓认七种:GFM、front-matter、Obsidian 双括号链接、脚注、::: 提示框、Pandoc、MDX。MDX 只做降级渲染——它要编译成 JavaScript 再执行,而扩展禁止执行运行时生成的代码。
  • 降级渲染(degraded render):某种语法做不到完整效果时,仍按普通 markdown 渲染正文,在做不到的那个位置留一个写明原因的占位块。信息不丢,是「这里本来有东西」的痕迹。
  • 下载(download):浏览器判定某文件类型不可内联,转而存盘。存盘的页面根本不存在,viewer 无从接管。默认不管已被下载的类型;**强制拦截(force intercept)**是一个用户自己开的开关,开了就在导航发生前把这类文件改跳到 viewer 自己的页面。
  • file 权限开关:chrome://extensions 里那个「允许访问文件网址」。扩展声明 host_permissions 不够,必须用户手动打开,运行时可用 chrome.extension.isAllowedFileSchemeAccess() 读到真实状态。
  • 拦截协议(intercept):强制拦截的 URL 约定——dNR 规则生成与 file= 参数编解码两端,同一个 module 拥有;协议两端不许各自手写编解码。

日志

  • 结构化日志(structured log):每条记录都带固定字段,可被机器直接筛选和采集;本仓使用 JSONL 表示,每行一条 JSON。
  • 统一日志文件(unified log file):全仓 Python 共用的那一个日志文件;靠记录里的来源字段区分是哪个工具写的,而不是每个工具各开一个文件。
  • 日志轮转(log rotation):日志文件达到大小边界后,当前文件改名为带序号的备份,继续写入新文件;备份数量有限,最旧备份会被删除。
  • 日志上下文(log context):帮助定位事件的路径、域名、命令和错误信息;不包含密码、cookie 或表单内容。
  • 临时日志位置(temporary log location):操作系统提供的临时目录;适合近期排障,不保证跨重启保留。
  • 私有日志权限(private log permissions):日志目录只允许当前用户访问,日志文件和轮转备份只允许当前用户读写。

git 工作流

  • 分支会话(branch session):切到目标分支(不存在则建跟踪分支)并在退出时按路径决定是否回原分支的保证。错误路径默认回滚,成功路径默认留在目标分支。回滚幂等:已在原分支则跳过。