Reorganize workspace and archive skill artifacts

2026-05-20 11:39:30 +08:00
parent 0e0275d46a
commit f45122dafb
83 changed files with 9733 additions and 15 deletions
@@ -0,0 +1,58 @@
+## 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` |