git-learn/openspec/changes/knowledge-index-panel/design.md

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