Harden dev-flow: pre-authorization marker, alternatives log, check script
- Record rejected answers in decision.md at the moment they are rejected - Allow explicit pre-authorized Build via a pre-authorized marker line - Land scripts/check-dev-flow.sh and derive devflow/index.md from archives - Add dev-flow process artifacts (decisions, prd) for open changes
This commit is contained in:
zhuyongxin
@@ -0,0 +1,42 @@
|
||||
# Decision: 目录名作为日期和标题的真理源
|
||||
|
||||
<!-- migrated-from: devflow/projects/2026-05-18-knowledge-index-panel/adr/0001-directory-name-as-truth-source.md (2026-09-18, change: migrate-devflow-archives) -->
|
||||
|
||||
## Problem
|
||||
|
||||
知识吸收器输出目录遵循 `knowledge_YYYYMMDD_Title/` 命名约定。目录内的 `.md` 文件包含 YAML frontmatter,其中也有 `date`/`created` 和 `title` 字段,但实际使用中发现字段名不一致(`date` vs `created`)且格式有差异。
|
||||
|
||||
索引重建脚本需要确定日期和标题的权威来源——两个来源都存在且都可能被读到时,不指定权威就必然漂移。
|
||||
|
||||
## Decision
|
||||
|
||||
**日期和短标识符 (slug) 的真理源是目录名。显示标题、tags、author 的真理源是 YAML frontmatter。**
|
||||
|
||||
- 日期从目录名的 `YYYYMMDD` 部分提取
|
||||
- 短标识符从目录名的 `Slug` 部分提取(用于文件路径构建,不用于显示)
|
||||
- 显示标题从 YAML frontmatter 的 `title` 字段提取
|
||||
- `tags` 和 `author` 从 YAML frontmatter 提取
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- Q: YAML 字段全优先? A: 不——字段名不一致(date vs created),脚本要处理变体,漂移点更多。
|
||||
- Q: 目录名全优先? A: 不——标题中的语义信息在下划线转空格后丢失(如 `mattpocock_skills` → `mattpocock skills`,实际标题更长更精确)。
|
||||
|
||||
## Consequences
|
||||
|
||||
**买到了**:
|
||||
- 索引脚本不需要处理日期字段名变体(date vs created)
|
||||
- 目录名是可见的、可审计的——与 `ls` 输出完全一致
|
||||
- bash 用 glob 匹配 `knowledge_*` 目录,天然获取了日期和 slug
|
||||
- 显示标题从 YAML 取,支持完整的、精确的标题文本(含标点、中文)
|
||||
|
||||
**付出了**:
|
||||
- 索引脚本需要解析 YAML frontmatter(复杂度比仅取目录名高)
|
||||
- 如果目录被重命名,slug 会变化但显示标题不受影响(可接受的行为)
|
||||
- 知识吸收器 skill 必须严格遵守 `knowledge_YYYYMMDD_Slug` 命名约定
|
||||
|
||||
## Verification
|
||||
|
||||
**只读(可直接跑)**
|
||||
- `ls knowledge/entries/ | head -3` → 目录名均形如 `knowledge_YYYYMMDD_Slug`
|
||||
- `grep -n 'date' scripts/update-knowledge-index.sh | head -5` → 日期提取自目录名而非 YAML
|
||||
@@ -0,0 +1,57 @@
|
||||
# PRD: 知识库索引面板 (Knowledge Index Panel)
|
||||
|
||||
## Problem Statement
|
||||
|
||||
用户每次用 `/knowledge-absorber` 学习后，会在项目根目录生成 `knowledge_YYYYMMDD_Title/` 文件夹。目前有 2 个知识条目，预计每月增长 5-10 个。所有条目散落在根目录，没有跨条目的导航或搜索能力。想找之前学过的内容只能手动翻目录，搜索成本随条目数线性上升。
|
||||
|
||||
## Solution
|
||||
|
||||
在项目根目录生成一个 **纯静态的 `knowledge-index.html`**，浏览器直接打开即可使用。它能自动发现所有 knowledge 条目，提供标签关联和全文搜索。不需要任何服务器、数据库或外部依赖。
|
||||
|
||||
## User Stories
|
||||
|
||||
1. As a 学习者, I want to see all my knowledge entries on one page with dates, so that I can quickly find what I studied and when
|
||||
2. As a 学习者, I want to search across all knowledge entries by keyword, so that I can find "that thing about Redis" in 2 seconds instead of manually opening 10 folders
|
||||
3. As a 学习者, I want to click a tag like "Claude Code" and see all related entries, so that I can review interconnected topics
|
||||
4. As a 学习者, I want the index to auto-discover new knowledge entries, so that I don't need to manually update anything after running `/knowledge-absorber`
|
||||
5. As a 学习者, I want the page to work offline by just double-clicking the HTML file, so that I can use it without internet or any setup
|
||||
6. As a 学习者, I want to see which entries are related to each other via shared tags, so that I can discover connections between topics I've studied
|
||||
7. As a 学习者, I want the search to highlight matching text, so that I can see at a glance why an entry matched my query
|
||||
8. As a 学习者, I want to see a count of entries per tag, so that I know which topics I've studied most
|
||||
|
||||
## Implementation Decisions
|
||||
|
||||
- **Single HTML file**: All CSS and JS inlined in `knowledge-index.html`. No external files or CDN dependencies
|
||||
- **Manifest-based discovery**: A JavaScript array inside the HTML lists all known knowledge directory names. Browser security sandbox prevents dynamic directory listing via `fetch()`
|
||||
- **YAML frontmatter parsing**: Regex-based extraction from `.md` files. Simple key:value parsing only — no full YAML spec support
|
||||
- **Client-side search**: All `.md` content loaded into memory at page init. Real-time filtering with `String.includes()`, case-insensitive. `<mark>` tags for highlighting
|
||||
- **Tag system**: In-memory `Map<tag, entry[]>` built at load time. Click to filter, click again to deselect
|
||||
- **Related Content**: Computed from shared tags, displayed per-entry
|
||||
- **No pagination**: Designed for < 50 entries. Full list rendered at once
|
||||
- **UTF-8 encoding**: All files assumed UTF-8. `fetch()` handles encoding detection
|
||||
|
||||
## Testing Decisions
|
||||
|
||||
- **What makes a good test**: Test external behavior — "user types keyword → correct entries appear" — not internal state
|
||||
- **Test with real data**: Use existing 2 knowledge entries (`knowledge_20260417_Waza`, `knowledge_20260518_mattpocock_skills`) as test fixtures
|
||||
- **Edge cases to verify**:
|
||||
- Missing directory (manifest lists a name that doesn't exist) → skip gracefully
|
||||
- Malformed YAML → display directory name as fallback
|
||||
- Empty tags array → no tag badges rendered
|
||||
- No search results → show "没有找到相关条目" message
|
||||
- Browser CORS when opened via `file://` protocol → document the workaround
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Google Drive / cloud sync
|
||||
- Editing knowledge entries
|
||||
- Full YAML 1.2 spec compliance
|
||||
- Pagination or virtual scrolling
|
||||
- Fuse.js or other fuzzy search libraries (keep it zero-dependency)
|
||||
- Dark mode toggle (can add later, not in v1)
|
||||
|
||||
## Further Notes
|
||||
|
||||
- The manifest maintenance problem (adding new entries) can be solved in a future iteration by modifying the `/knowledge-absorber` skill to auto-append to the manifest array
|
||||
- The `file://` protocol CORS limitation on Chrome means users may need to serve via `python -m http.server` or similar for full functionality
|
||||
- Tag counts provide a natural "learning heatmap" — most-studied topics bubble to the top
|
||||
Reference in New Issue
Block a user