跳到主要内容

探索框架

· 阅读需 12 分钟
José Villaseñor Montfort
Strange Days Tech

到 2026 年 4 月，框架已经有了约 50 个治理之下的 Markdown 文件，它们已经变得不透明。straymark explore —— 一个把整个仓库渲染成可导航界面的 TUI —— 在它意外暴露 Post 8 异常值的三周前诞生。新工具会在无意之间制造出可见性。

1. 两周后揭露异常值的工具​

本博客 Post 8 记录了一个具体事件：发现了框架中唯一一个正典语言为西班牙语的文件。操作者并非通过系统性检查找到它；而是在审计准备过程中运行了 straymark explore --lang es，在视觉上注意到有一个模板相对其他文件是反向书写的。那篇文章中有这样一句话：

"框架的一个新界面（TUI）将所有文件同时呈现，不一致之处变得显而易见——就像整理书架时，突然发现有一本书脊背朝外。"

本文介绍的就是这个工具。straymark explore 这个 TUI 几乎在它所揭露的发现之前三周就已诞生——于 2026 年 4 月 25 日随 cli-3.4.0 发布——并在此后四个版本中逐步完善，所有版本均在 48 小时内完成。这不是一篇关于代码的文章。它是关于一件具体工具的文章，印证了博客此前已命名的一个论点：新工具会在无意之间制造出可见性。

2. 为什么在 Markdown 框架里构建 TUI​

到 2026 年 4 月下旬，框架已经拥有约五十个受治理的 Markdown 文件——PRINCIPLES.md、AGENT-RULES.md、DOCUMENTATION-POLICY.md、QUICK-REFERENCE.md、SPECKIT-CHARTER-BRIDGE.md，加上 dist/.straymark/templates/ 中的模板、审计提示，以及每个文件的三语版本（i18n/es/、i18n/zh-CN/）。它们都在磁盘上，都可以用 find 和 cat 浏览，完全可访问。

但同时，也完全不可见。对于第一次克隆框架的使用者，第一个问题不是"规则 N 在哪里？"，而是"这里有什么？"。递归 ls 无法回答这个问题——它只会让人不知所措。grep 需要知道要搜索什么。编辑器一次只打开一个文件。框架已经达到了这样的规模：它自身的表面已经变得不透明。

straymark explore 正是为了解决这个问题而诞生的：一个可导航界面，能在三秒内回答"这里有什么？"。它不是 IDE，不是 Read-the-Docs 式系统，也不是静态网站。它是一个 TUI——终端用户界面——运行在使用者的仓库上，对框架的正典文件建立索引，按类别分组展示，并在终端内使用带颜色的 Markdown 查看器让你阅读文件。

构建 TUI 而非 Web 应用的决定，与博客此前论述的两点相符。第一，Post 4 的原则 #10——"StrayMark 不是 LLM 网关"——可以推广为"StrayMark 不是任何已经做了某件事的东西"。我们不与 MkDocs 或 Material for MkDocs 竞争。第二，同一 Post 4 中的 A1 决策：纯编排。TUI 不需要服务器，不需要构建步骤，不需要网络连接：它运行在框架已经存在的使用者仓库上。这是能解决问题的最朴素的一块拼图。

3. cli-3.4.0 落地的内容​

4 月 25 日的 PR #57，以 cli-3.4.0 合并，做了三件具体的事：

  • 引入了 straymark explore 命令。当终端宽度达到 100 列或以上时，采用双面板布局：左侧导航（30%），右侧文档（70%）。较窄的终端折叠为单面板。底部状态栏显示相关快捷键。
  • 将框架的正典文件索引为可导航的层级结构：治理文档（AGENT-RULES.md、DOCUMENTATION-POLICY.md 等）、模板（dist/.straymark/templates/）、审计提示，以及使用者目录（docs/charters/、.straymark/07-ai-audit/ 等）。每个节点可用 Enter 展开。
  • 接入了 i18n 解析器。--lang <code> 选项允许运行 straymark explore --lang es，并在翻译存在时获取西班牙语的所有治理文档。若无翻译，则静默回退到正典英文。提交的字面描述：

"通过 explore TUI 贯通 language 配置和新的 --lang 标志，当翻译存在时从 i18n/<lang>/ 提供框架治理文档，否则静默回退到英文。"

i18n 解析器部分比 TUI 本身更重要。在 cli-3.4.0 之前，辅助函数 resolve_localized_path 仅由 straymark new 使用（用于解析应以何种语言将模板注入使用者）。PR #57 将其提取到 cli/src/utils.rs:146 作为共享辅助函数，使得**i18n/<lang>/ 覆盖层解析方式的单一定义**同时支撑 new 命令和 explore 命令。对使用者而言，行为保持可预期：如果你将某个模板翻译到 i18n/es/，TUI 展示它的方式与生成时使用它的方式一致。没有意外。

Markdown 渲染使用 pulldown-cmark 作为解析器，ratatui 组件负责绘制。语法着色、带边框的代码块、圆角边框的表格、按层级缩进的标题。不炫目，但可读性好。

4. 三十六小时内的四次精炼​

4 月 25 日至 27 日之间发生的事，正是 Post 9 几个月后命名为流程属性的东西：当提案写得清晰，实现就是执行。四个 PR，在 36 小时内完成，将 TUI 从"能用"带到"做完"：

PR标签时间新增内容
#60cli-3.5.04 月 25 日 22:36实时语言切换器。 L 键在不退出 TUI 的情况下循环切换显示语言：en → es → zh-CN → en。索引就地重建。
#61cli-3.5.0（同一版本）4 月 25 日 23:41OS 语言区域自动检测。 若使用者没有 config.yml，TUI 读取 $LC_ALL / $LANG 并将 POSIX 区域（如 es_MX.UTF-8 → es）映射到最近支持的语言。
#62cli-3.5.14 月 26 日 00:07元数据面板已翻译。 25 个新的 i18n 条目用于标签和标题，加入了视觉填充以保持跨语言对齐。
#63cli-3.5.24 月 26 日 00:13快捷键清理。 移除了未记录的 vim 别名 l 和 h（小写 l 与 L 语言切换器冲突）。保留已记录的 j/k/g/G/n/N。

这段弧线的速度重复了同一模式。Post 6 中记录的 fw-4.11.0 的五个 PR（品牌更名为 StrayMark）在四十三分钟内完成。Post 4 中记录的三个审计周期版本在一天内完成。TUI 的曲线类似：设计在 PR #57 中已确定，而精炼则是在操作者开始频繁使用该命令并注意到摩擦点时出现的。

值得记录的轶事是 cli-3.5.2：它移除的 l 和 h 键是 vim 别名——操作者在编辑器中靠肌肉记忆使用它们。但当大写 L 语言切换器几小时前落地时，小写 l 和大写 L 共享同一物理键，视觉上的过渡令人困惑。修复方法是移除未记录的别名：完整字母拼写（j/k/g/G）保留；复制功能的缩写消失。这是一个小的 UX 细节，说明 TUI 决策是针对真实使用调整的，而非 UX 理论。

5. TUI 两周后揭露的内容​

此处，文章从另一端接续了 Post 8 的线索。cli-3.4.0 给框架增加的不仅仅是一个导航命令；它是一个同时可视化的界面。也就是说：在 TUI 出现之前，框架的文件存在，但只能逐一阅读。有了 TUI 之后，它们可以被一次性看到，分组、标记，以相同的呈现模式。

这改变了操作者能注意到的事情。

5 月 12 日，cli-3.4.0 合并两周半后，操作者在外部审计周期前运行了 straymark explore --lang es。他们打开了"审计提示"组，发现了一件存在已久的事：根目录下的 audit-prompt.md 是用西班牙语写的，而其他所有正典框架文件都以英文作为根目录版本，以 i18n/es/ 覆盖层作为西班牙语版本。一个文件，相对于约定是反向的。

这个细节不是通过系统性审查发现的。它是通过视觉对比发现的。这正是 Post 8 第 3 节编纂为论点的内容：

"新工具制造可见性。"

TUI 没有造成这个异常值——它自第一次将 Sentinel 技能 plan-audit 移植到正典框架的提交以来就存在（Post 3 对此有记录）。TUI 也没有寻找异常值；它不是一个不一致性检测工具。它所做的只是把每个文件放在同一屏幕上，以相同的呈现模式，让人眼注意到从一开始就存在的东西。值得记录的结论是结构性的：任何超过五十个正典文件的框架都需要一个同时可视化的界面，不是因为这个界面本身在教学上重要，而是因为没有它，仓库的某些规律性就变得无法观察。

6. 值得记录的细小技术决策​

三个值得记录的 TUI 设计细节，均与博客已命名的框架原则相符：

特性标志 tui。 CLI 的 Cargo.toml 将 TUI 声明为可选依赖（ratatui + crossterm + pulldown-cmark 置于默认启用的 tui 标志之后）。只需要 init、update、validate 的使用者可以通过 cargo build --no-default-features 构建不含 TUI 的二进制文件。这关闭了一个在框架中反复出现的子架构决策：默认给使用者提供价值，但当 TUI 对其流程毫无意义时，让他们可以选择更轻量的二进制文件。

文档懒加载。 DocIndex 维护一个 HashMap<PathBuf, Document>，它在每个节点被打开时才填充，而非在启动时。对于拥有一百个治理文件的仓库，这意味着 straymark explore 在 200ms 内启动，只在操作者按下 Enter 时才读取磁盘。这个决策在技术上微不足道；真正不微不足道的是它是有意识做出的。TUI 不与 IDE 竞争；它与 cat 竞争。它必须感觉同样即时。

超链接的历史栈。 当一个框架文档提及另一个（例如 AGENT-RULES.md §3 引用 DOCUMENTATION-POLICY.md §6），TUI 允许你通过点击跳转到被引用的文档，并用 Esc 返回。内部有一个导航栈，可以恢复之前文档的滚动位置。这一功能将阅读框架从"我打开一个文件，关闭它，再打开另一个"变成了"我在文档之间跟随一场对话而不失去线索"。框架今天所拥有的交叉引用数量——原则、智能体规则、模式、模板之间——使这种导航在结构上重要，而不只是装饰性的。

7. 结语​

从这个过程中，我得出了四个结论：

  1. 超过一定规模的框架需要一个同时可视化的界面。 这不是人体工学问题；这是仓库某些规律性得以被观察的条件。Post 8 记录了后果；本文记录了工具。

  2. TUI 不会造成发现；它使发现成为可能。 审计提示异常值自上一年 5 月就已存在。4 月唯一改变的是，一个屏幕出现了，在那里它可以与同类文件一起被看到。工具对内容没有意见；它改变的是人眼能注意到规律性的条件。

  3. 当设计清晰时，实现是小时，而非冲刺。 三十六小时内的五个 PR——语言感知、实时切换器、OS 检测、面板 i18n、快捷键清理——之所以可能，是因为设计在 PR #57 中已关闭。这与 Post 4、6 和 9 是同一模式。

  4. 最有趣的技术决策可以是一个编译时标志。 tui 特性标志明确声明 TUI 是可选的，框架在没有它的情况下仍然可以工作，使用者可以自行决定。这种架构上的谦逊，是一个假设使用者工作方式的 CLI 与一个在能发挥作用的地方提供自身的 CLI 之间的区别。

本文使本博客覆盖了第一批留为明确技术债的 H-14 里程碑。PLAN-INVESTIGACION.md §1.43-55 中记录的其余候选里程碑——AGENTS.md 通用注入、完整 EN/ES/zh-CN i18n 覆盖、straymark validate 作为正式层、CLA 助手——仍可作为未来批次的主题。没有承诺的节奏，但已记录在案。

锚点：PR #57 — cli-3.4.0（语言感知 explore，2026 年 4 月 25 日）。PR #60 · #61 · #62 · #63 — 精炼版本 cli-3.5.0 至 cli-3.5.2（2026 年 4 月 25-26 日）。代码：cli/src/tui/（15 个文件）。使用者文档：docs/adopters/CLI-REFERENCE.md §straymark explore。

本文档在生成式 AI 工具（Claude 4.7）的协助下撰写；内容的全部责任由人类作者承担。