AI 提示词 / 需求规格¶

# 需求规格：三级向下钻取文件浏览器（单文件 HTML）

做一个「向下探索 / 逐级钻取」的文件-目录浏览器，纯前端、单文件、零依赖，
把一份目录树按 **3 个层级** 横向展开，用户可以左右探索、逐级下钻、随时回退。

## 一、目标

做一个「向下探索 / 逐级钻取」的文件-目录浏览器，纯前端、单文件、零依赖，
把一份目录树按 **3 个层级** 横向展开，用户可以左右探索、逐级下钻、随时回退。

## 二、技术约束

- 单个 `.html` 文件，使用原生 HTML + CSS + JS，不允许任何外部依赖 / CDN / 框架。
- 目录树数据以 JS 对象字面量（`const TREE`）内联在文件里，不发起网络请求。
- 双击打开即可运行（file:// 直接可用），无构建步骤。

## 三、数据结构

每个节点统一结构：

```js
{
  name: "名字",          // 展示名
  type: "dir|py|sh|js|md|cfg",  // dir 为目录，其余为文件类型
  desc: "一句话说明",     // 详情面板里的描述
  children: [ ...节点 ]   // 仅目录有；文件无此字段
}
```

- 根节点代表仓库本身（name = 仓库名）。
- 约定：`type === "dir"` 才可继续下钻，文件是叶子节点。

## 四、布局与交互要求

### 1. 顶部 Header

- 标题 + 一句副标题（说明总文件数 / 顶层模块数）。
- 面包屑：从根目录开始，用 `/` 分隔当前完整路径；**每一段可点击**，点击后回退到该层级（实现“向左探索”）。

### 2. 主体：横向列式钻取（board）

- 每列代表一个层级：
    - 第 1 列固定为「① 顶层模块」；
    - 第 2 列 = 第 1 列选中目录的 children，标签「② 二级内容」；
    - 第 3 列 = 第 2 列选中目录的 children，标签「③ 三级内容」。
- 列与列之间用箭头符号（如 `›`）指示下钻方向。
- 列头显示层级名 + 该层子项数量。
- 列内可滚动（纵向设最大高度），超出横向时整块可横向滚动。
- **点击目录**：在当前列右侧展开下一列（向下钻取）。
- **再次点击已选中的目录**：收起该层及之后所有列（向左回退）。
- **点击文件**：不展开新列，只在底部详情面板展示。
- 选中项要有高亮样式（背景色 + 左侧色条）。

### 3. 详情面板（detail）

- 展示当前选中节点的：
    - 图标 + 名称；
    - 完整路径；
    - 元信息 chips：类型、路径、直接子项数 / 子孙总数（目录）或功能归类（文件）；
    - 描述文本（取节点的 `desc`）。
- 目录额外统计“子孙总数”，文件按扩展名给出功能分类标签。

### 4. 图例（legend）

- 用色块 + 文字标注每种类型的颜色含义（目录 / Python / Shell / JS / Markdown / 配置）。
- 附一句使用提示。

## 五、视觉要求

- 深色主题（GitHub dark 风格）：
    - 背景 `#0e1117`，面板 `#161b22`，分隔线 `#2a3242`。
    - 主文字 `#e6edf3`，次要文字 `#8b98a9`，强调色蓝 `#4ea1ff` + 绿 `#38d39f`。
- 按文件类型区分颜色与图标：
    - dir 橙黄 / py 蓝 / sh 绿 / js 黄 / md 紫 / cfg 灰。
- 圆角面板、hover 高亮、过渡动画（~0.12s）、等宽字体用于路径。
- Header 吸顶（sticky）。

## 六、健壮性 / 边界

- 目录为空时列内显示占位文案（如“该目录暂无内容”）。
- 钻取层数要有安全上限（例如 4~5 层），防止数据异常时无限展开。
- 初始化时默认展开首个目录链，直接呈现一个三级视图（开箱即有内容）。
- 若首层第一个子项不是目录，则自动退回到只展开可用层数，不报错。

## 七、验收标准

1. 双击文件即能打开，控制台无报错。
2. 点目录能在右侧逐级展开到第 3 层；点面包屑能逐级回退。
3. 点文件能在详情区看到路径与描述，且不产生新列。
4. HTML 标签配平，配色/图例与文件类型一致。
5. 数据树的“最大深度 ≥ 3”，保证三级视图成立。

---

## 八、换数据（复用方式）

把 `TREE` 对象替换成目标目录树即可（保持 `name/type/desc/children` 结构），
其余 HTML/CSS/JS 逻辑无需改动。若新仓库层级更深，可放宽第六节的层数上限。

## 文档维护规则

1. 本文1-80行禁止修改
2. 80行后的内容与实际不符时，更新本文以反映实际
4. 本文超过500行必须主动压缩至500行以内
5. 一旦读到本文，请记住需要遵守本文的要求

## 核心原则

1. 先理解再动手：通读任务+关联代码 → 追踪端到端数据流 → 理解问题全貌
2. 最小必要实现，不写非必要代码
3. 干活前阅读 记得遵守 每次任务必须先询问模式 的要求

## 决策阶梯

写任何代码前，从第一级开始，停在第一个满足条件的台阶：

1. 需要存在吗？ → 否：跳过
2. 代码库已有？ → 复用，不重写
3. 标准库能做？ → 用它
4. 平台原生特性覆盖？ → 用它
5. 已安装依赖能解决？ → 用它
6. 一行代码能搞定？ → 就一行
7. 走到这里：写最少能工作的代码

阶梯覆盖设计、编码、评审三阶段。选方案前必须读完任务和涉及代码，追踪完整执行路径。方案上可以懒，阅读上不可以懒。

## 设计

少写代码的方式是更早说不。

- **质疑需求**：阶梯第一级在设计阶段最有力。"需要这功能吗？"——已有方案能覆盖，新功能整个跳过。
- **用问题回应**：复杂需求先给最简方案，反问"X 做了；Y 已覆盖。真的要完整 X？要就说。"不等答案，给默认。
- **不建"将来可能用"的架构**：无第二个实现 → 不建接口；无第二个产品 → 不建工厂；未变过的值 → 不加配置。
- **数据结构选对，代码自然短**：DB 约束替代应用层校验；jsonb 替代一对多关联表；窗口函数替代应用层聚合——DB 能做的，代码不重复。
- **仅一处调用的抽象是冗余，删除。**

## 编码

- 不引入无明确需求的抽象。
- 不引入新依赖，除非现有方案无法满足。
- 不要无调用方的样板代码。
- 删优于加。简单优于聪明。文件越少越好。
- 最短能工作的 diff 即赢家——前提是已理解问题。在最错处做最小改动不是懒，是第二个 bug。
- 两个标准库方案等长时，选正确处理边界条件的。懒 = 少写代码，≠ 用更脆弱的算法。
- 修 bug = 治根本，不治症状。检查所有调用方，在共享函数修一次——一处 guard 比每处各加 diff 更短。只修点名路径让其他调用方继续破损。
- 非平凡逻辑必须附带一个可运行检查：最小能证明逻辑出错的断言或小测试。不要测试框架、不要 fixtures。一行平凡代码不需要。
- 刻意简化标记：省略边界条件（全局锁、O(n²)、朴素启发式）时，用 `ponytail:` 注释标注上限和升级路径。

## 评审

评审只盯一个问题：**哪些代码可以不写。**

- 范围：只查过度工程和复杂度。正确性 bug、安全漏洞、性能交常规评审。
- 输出：每行一个发现，格式：**位置 → 标签 → 砍什么 → 替代方案**。
- 无可砍时说：**`Lean already. Ship.`**

五个标签，按可砍代码量从大到小：

| 标签 | 命中场景 | 替代方案 |
|------|---------|---------|
| `delete:` | 死代码、未用灵活性、投机功能 | 无 |
| `stdlib:` | 手写代码替代了标准库已有功能 | 标准库函数名 |
| `native:` | 库或代码做了平台原生的事 | 平台特性名 |
| `yagni:` | 单一实现抽象、无人设配置、单调用方层 | 内联，等第二个出现 |
| `shrink:` | 同逻辑可更短 | 给出更短写法 |
评审终点不是"代码好"，是"diff 变短了"。

## 安全红线

以下永不在砍代码讨论范围，设计/编码/评审三阶段均不可触碰：

| 红线 | 说明 |
|------|------|
| 信任边界输入验证 | 路径穿越、SQL 注入、XSS——永为必经检查点 |
| 防数据丢失的错误处理 | 涉及数据写入/删除时，错误处理不可省略 |
| 安全性 | 身份验证、授权、加密——不可妥协 |
| 可访问性 | 原生元素自带无障碍，自定义组件需额外保障 |
| 真实硬件校准 | 平台非理想环境：时钟漂移、传感器误差等 |