# dsh-pathfinder · 动手改界面之前必读 > 这份文件装的是**法**。它不装现状、不装取值：取值住在 `src/client/styles/tokens.css`，改一个值是设计动作， > 不违反这里任何一条。 > > **加任何内容需要 user explicit approval；上限 100 行，要加一条先腾出一条。** > 「这一轮改了什么、为什么」写进 commit body；正在琢磨、还没定的写进 `.tmp/`（gitignored）。 ## 这个仓在做什么 把 `agent-pathfinder` 的管线搬进 DSH，做成一个用户看得见的工作面板。 面板是**记录的一张脸**：它印的字段都是工具里真有的，版面从记录里长出来。一个没有单位的数字， 读者读不出它是什么——宁可不印。 ## 最重的两条 - **不叙述界面。** 控件自己说状态，读数自己带单位；一句「这里显示…」都不写。控件需要一句解释 时，把它做清楚——这比在它旁边添一行小字管用。 - **没有的东西不画。** 记录里没有的数不印；一个都没有的那一栏不留空标题、不写「暂无」、不留带 内边距的空盒子。 ## 一、词表与判据 词表以工具仓的 `docs/vocabulary.md` 为准，本仓只引用、不另写一份，也不许各写一套读法。 - 节点的状态只有三个：`completed` / `shelved` / `todo`。 - `shelved` 是**出局等人**：没交付的判决落到图上就是它，谁都不许开工，要人 `pf dag revive` 放回去。面板上读作**等待处理**。 - **人闸**是「这一格什么时候要一个人」，一个词 + 那一刻，判据全在记录里，面板不新增数据： `shelved` 读作**等待处理**（判决那一步的 `ended_at`）；`mode=manual` 且还没交付读作**手动 节点**（它那一步的 `started_at`）；`mode=checkpoint` 交付了、且**这次交付还没被批过**（批的 时刻不早于交付时刻才算数），读作**检查点**（那一刻＝交付那一刻）。停不停仍然只看这一格自己的 `mode`（`checkpoint` 停在收尾那一拍，`manual` 的人闸在格子的对话里）；工具里没有「我停了，在 等人」这个旗标，但「人批过没有」如今在记录里有了落点：`approved_at`。 - 「谁在做它」不在状态里，记在线路的 `holding` 里，读的时候算出来：`running`（进行中）。 - `ready`（可开工）三条判据缺一不可：自己是 `todo`、每个依赖都 `completed`、**且没有任何线 握着它**。少了第一条，出局等人的节点会装成可开工；少了第三条，别人手里正做的会装成可开工。 - 线路的 `path` 只记**走过的**步。「这条线还剩多少步」在工具里不存在——盘上没有这个数。 ## 二、共同地面 - 值只取自 DSH 自己的令牌，不自造颜色；**承担意义的记号有五个**（已交付 / 进行中 / 未开始 / 等待 处理 / 失败），只花四个值，要添一个先撤一个。 - 共同构件住在 `src/client/styles/tokens.css`：两个面板说同一个词，就得说在同一个对象上。取值住 那里，本文件不抄；边距、行高、节奏这些数字住各页的页根（`.pf-page`），也不抄。 - 字体三个角色都取自 DSH：牌位那一档才用 Montserrat，正文走系统无衬线，一切数字走等宽并带 `tabular-nums`。字号只用 DSH 的档，不自造一档。 - 读的人是在别的活之间瞄一眼：**时间一律静态**，正文不出滚动条，**任何 `vh` / `vw` 都不许用** （无头截图会在拍照前撑大视口，跟视口挂钩的尺寸会在快门中间重排）。 - **对比度的判据落在读者身上**：要逐个分辨的记号过了线才画；一整行按质量读的密排刻度可以更暗。 两档的具体数写在 `src/client/styles/tokens.css` 里，改档不改这条。 ## 三、文案纪律 - **同一件事不说两遍。** 位置已经说过的不再抄一遍（所在的那一列不必在每张卡上各报一次）。 - **机器读数不进阅读流**（进度、内部评分、判定等级）。要留就降成 chip 或悬停。 - **不出现 session id。** 那串东西对读的人没有意义。 - **依赖只写两种词**：`可开工` / `前置节点 N 个`，且只写给还没开动的活——落定的不欠谁，进行中的已经 过了这个问题。 - **等待处理只在出问题的时候存在。** 有，它排在其他进行中的节点前头，读者先遇到它。 - **读者看见的词从对照表里取。** 词表管「这个词是什么意思」（以工具仓为准，见上），对照表管「这个词在 哪种语言里怎么写」：中英各一本、键集一样，少一枚键编译就报错，添一种语言就是添一本。模型只说读数 是什么（`shelved`、`checkpoint`、还欠三个前置），不说它怎么读——那是 client 的事。 ## 四、每一格 - **一根组织轴 + 一个签名件。** 一格只回答一个问句，签名件是它被记住的那件东西；共同的部分 （牌位、工作区、读数行）在每一格里长得一样。 - **折叠不动版面。** 它收掉的是内容，这一页的布局留在原地。 - 组合件（宽度把手、标签、行内动作、下拉）**照 DSH 自己那一份抄**，字号、字重、留白逐条对齐； 只有 DSH 没有的东西才自己长。 ## 五、代码、注释与文档 - 代码和注释**不写 md 路径、不写 §节号、不写行号**；判据的指针由 md 这一侧单向持有。 - 机制不显然的地方，把「为什么长成这样」写在它旁边——读完旁边那段代码就能看出这句话为真， 才算写对了。 - 注释只留「读完旁边代码看不出」的那一句；文件级的设计说明归路牌，不归代码。 - **读数不落纸**：条数、字节、哈希、耗时、pid 这类数字写下来就会烂——要核就现跑那条命令。 - **路牌一行一条**：本级每个子文件夹、每份散装文件各一行，深处的事归深处的路牌。