59 lines
3.0 KiB
Markdown
59 lines
3.0 KiB
Markdown
## Context
|
||
|
||
github-learn 是个人知识学习仓库。`/knowledge-absorber` 技能学习后，知识条目以 `knowledge_YYYYMMDD_Title/` 命名，当前集中存放在 `knowledge/entries/`。每个条目包含同名 `.md` 源文件和 `.html` 渲染页。
|
||
|
||
**约束**：
|
||
- Windows 11，Git Bash 可用。
|
||
- `knowledge-index.html` 放在项目根目录，浏览器直接打开。
|
||
- 零外部依赖（无 npm、无 CDN、无服务器）。
|
||
- 生成脚本是索引页面真理源；不要只手改生成后的 HTML。
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
- 自动发现 `knowledge/entries/knowledge_YYYYMMDD_Title/` 文件夹。
|
||
- 从 `.md` 文件的 YAML frontmatter 解析元数据（title、author、tags、date）。
|
||
- 为每个条目生成可点击链接，跳转到对应条目的 `.html` 文件。
|
||
- 支持全文搜索、标签筛选、年份筛选和清空筛选。
|
||
- 保持单文件静态索引页面，不引入运行时服务。
|
||
|
||
**Non-Goals:**
|
||
- 不修改任何现有 knowledge 条目内容。
|
||
- 不做云端同步或数据库存储。
|
||
- 不实现编辑功能。
|
||
- 不支持分页（初期 < 50 条目）。
|
||
|
||
## Decisions
|
||
|
||
### D1: 目录收纳 — knowledge/entries 作为知识条目根
|
||
|
||
**选择**：知识条目从项目根目录迁移到 `knowledge/entries/`，保留原有 `knowledge_YYYYMMDD_Title/` 命名约定。
|
||
|
||
**理由**：根目录同时承载 OpenSpec、devflow、skills、验证沙箱和知识条目。把知识条目集中到 `knowledge/entries/` 能降低根目录噪音，同时不破坏目录名作为日期和 slug 真理源的 ADR。
|
||
|
||
### D2: 索引生成 — Bash 脚本预生成 ENTRIES
|
||
|
||
**选择**：`scripts/update-knowledge-index.sh` 扫描本地目录、解析 Markdown frontmatter 和正文，并把结果内联进 `knowledge-index.html` 的 `ENTRIES` 数组。
|
||
|
||
**理由**：浏览器无法可靠枚举本地目录；用脚本预生成数据避免本地 `fetch()` 和 CORS 问题，也保持最终页面零运行时依赖。
|
||
|
||
### D3: 向后兼容 — 找不到 knowledge/entries 时回退根目录
|
||
|
||
**选择**：脚本优先扫描 `knowledge/entries/knowledge_*/`；如果 `knowledge/entries/` 不存在，则回退扫描项目根目录的 `knowledge_*/`。
|
||
|
||
**理由**：兼容旧项目结构和迁移中状态。
|
||
|
||
### D4: 条目链接 — 存储相对路径
|
||
|
||
**选择**：生成时为每个条目写入相对项目根的 `path` 字段，前端用 `path/<dirname>.html` 构造链接。
|
||
|
||
**理由**：条目目录不再在根目录，仅靠 slug 无法定位文件；相对路径能支持后续进一步分组。
|
||
|
||
## Risks / Trade-offs
|
||
|
||
| Risk | Impact | Mitigation |
|
||
| --- | --- | --- |
|
||
| `/knowledge-absorber` 仍输出到根目录 | 新条目不会进入整理后的目录 | 脚本有根目录 fallback；后续应更新 knowledge-absorber 输出约定 |
|
||
| 移动目录后旧文档引用过期 | 历史文档路径不准确 | 保留历史语境；当前 glossary、OpenSpec 和 README 以新结构为准 |
|
||
| 只修改生成后的 HTML | 下次重建丢失功能 | 所有页面功能必须先改 `scripts/update-knowledge-index.sh` |
|