kb: 借鉴 Opus 设计 — INDEX.md 自动索引 + prefs/projects 目录 + decisions 开张

2026-08-08 21:06:27 +10:00 · 2026-08-01 23:45:49 +10:00
parent 97b4cfcdfc
commit 78f1548f7a
11 changed files with 228 additions and 0 deletions
@@ -23,7 +23,10 @@ kb/
 ├── raw/               # 源材料（按月分桶，不可变）
 │   ├── links/         #   从 Links App 自动同步的新闻
 │   └── YYYY-MM/       #   手动分享的文章、网页
+├── prefs/             # Agent 行为偏好（多工具共享，先 search 再写）
+├── projects/          # 进行中的项目（状态/目标/下一步，细节在 wiki）
 ├── wiki/              # 编译后的知识页
+│   ├── INDEX.md       #   自动生成索引（scripts/reindex.sh，勿手改）
 │   ├── investing/     #   投资相关
 │   ├── tech/          #   技术相关
 │   ├── life/          #   生活相关
@@ -86,6 +89,10 @@ rg 搜 wiki/ + raw/ → 结果标 [wiki] 或 [raw] → 合成回答
 - P1: 投资页 >60天未更新 → 建议修
 - P2: 孤儿页 → 提示

+### Reindex (索引 — 结构变更后)
+`scripts/reindex.sh` → 重新生成 `wiki/INDEX.md`（frontmatter title + 正文首行）。
+新页面、改名、删除后都要 reindex。INDEX.md 勿手改。
+
 ## Page Templates

 ### Stock Thesis
@@ -23,3 +23,9 @@

 ## [2026-07-14] sync | daily conversation scan — found 1 item
 - antirez 文章 "Control the ideas, not the code"：AI时代程序员角色从写代码转向控制设计思想
+
+## [2026-08-01] restructure | KB 借鉴 Opus 设计（decision: 2026-08-01-kb-evolution）
+- scripts/reindex.sh: 生成 wiki/INDEX.md（frontmatter title + 正文首行 hook，排除 README/_template）
+- 新增 prefs/（agent-language.md + _template.md）、projects/（README + _template.md）
+- wiki/decisions/ 开张: 2026-08-01-kb-evolution.md + _template.md
+- SCHEMA.md 目录结构 + Reindex 说明更新
@@ -0,0 +1,12 @@
+# Prefs — Agent 行为偏好
+
+> 大哥的偏好在这里落盘，**任何 Agent（小黑、Claude Code、Codex、Cursor…）读写前先 search**。
+> 借鉴 Claude Opus 的 kb 设计：偏好独立成目录，不混在技术知识里。
+
+## 规则
+
+- 每条偏好一个文件，英文 slug：`agent-language.md`
+- frontmatter：`title` / `updated` / `tags: [pref/xxx]`
+- 内容：明确的行为指令，越具体越好；能测、能守
+- 先 search 再写：已有条目就更新，不重复建
+- 与 Hermes memory 的关系：memory 是 Hermes 私有；这里的 prefs/ 是**所有工具共享**的
@@ -0,0 +1,11 @@
+---
+title: "Pref: [Name]"
+updated: YYYY-MM-DD
+tags: [pref/xxx]
+---
+
+# [Name]
+
+- [明确的行为指令 1]
+- [明确的行为指令 2]
+- [可验证的结果 / 触发场景]
@@ -0,0 +1,12 @@
+---
+title: "Agent 语言：始终中文"
+updated: 2026-08-01
+tags: [pref/communication]
+---
+
+# Agent 语言
+
+- 对大哥一律用**中文**回复；技术术语（K3s、API、Namespace、Debt Recycling 等）保留英文
+- 文件名、路径、tag 用英文 slug
+- 面向其他 Agent/工具的内部注释可用英文
+- 输出给大哥的交付物：图片/文件直接发，不加冗长过程叙述
@@ -0,0 +1,12 @@
+# Projects — 进行中的项目
+
+> 每项目一个文件：当前状态、目标、下一步。**知识细节放 wiki/ 对应页面**，
+> 这里只放"现在进行到哪"。借鉴 Claude Opus 的 kb 设计。
+
+## 规则
+
+- 一个进行中的项目一个文件，英文 slug：`ipad-panel.md`
+- 内容：Status / Goal / Next steps / 关联 wiki 页面
+- 先 search 再写：已有 wiki 页面承载知识时，项目卡只链接过去，**不重复内容**
+- 项目结束 → 标记 `status: done` 或移 `_archive/`，不在 wiki 铺页
+- 每周 review 时过一遍 projects/，清理僵尸项目
@@ -0,0 +1,15 @@
+---
+title: "Project: [Name]"
+status: active
+updated: YYYY-MM-DD
+tags: [tech/project]
+---
+
+# [Name]
+
+- Status: active | paused | done
+- Goal: [一句话目标]
+- Next steps:
+  - [ ] [第一步]
+  - [ ] [第二步]
+- Links: [[related-wiki-page]]
@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Reindex: regenerate wiki/INDEX.md from wiki/**/*.md frontmatter.
+# Usage: scripts/reindex.sh
+# 借鉴 Claude Opus 的 AGENTS.md 思路：一行一条目 [标题](相对路径) — hook，
+# agent 先 skim 再打开文件。INDEX.md 由本脚本生成，不要手改。
+set -euo pipefail
+
+KB_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+WIKI_DIR="$KB_ROOT/wiki"
+INDEX_FILE="$WIKI_DIR/INDEX.md"
+TMP_FILE="$WIKI_DIR/.INDEX.tmp"
+
+# 固定顺序的 section；不存在或没有 .md 的自动跳过
+SECTIONS="investing tech life decisions"
+
+{
+  echo "# Wiki Index"
+  echo
+  echo "> 自动生成（scripts/reindex.sh）— 不要手改。每行一个条目：[标题](相对路径) — 正文首行摘要"
+  echo
+  echo "用法：skim 找相关条目 → 打开对应文件看细节。新页面 reindex 后自动出现。"
+  echo
+
+  for section in $SECTIONS; do
+    dir="$WIKI_DIR/$section"
+    [ -d "$dir" ] || continue
+
+    # 先数文件，空 section 不输出标题
+    count=0
+    while IFS= read -r _; do
+      count=$((count + 1))
+    done < <(find "$dir" -maxdepth 1 -name '*.md' -type f ! -name '_template.md' ! -name 'README.md' | sort)
+    [ "$count" -gt 0 ] || continue
+
+    echo "## $section"
+    echo
+
+    while IFS= read -r f; do
+      rel="${f#"$WIKI_DIR"/}"
+
+      # frontmatter title（可带引号），缺省用文件名
+      title="$(awk -F': ' '/^title:/ { gsub(/^"/,"",$2); gsub(/"$/,"",$2); print $2; exit }' "$f")"
+      [ -n "$title" ] || title="$(basename "$f" .md | tr '-' ' ')"
+
+      # hook = 正文第一个非空行（跳过 frontmatter 与 # 标题行），去掉列表符号与 markdown 符号
+      hook="$(awk '
+        BEGIN { fm=0; done=0 }
+        /^---$/ { if (fm==0) { fm=1; next } else { fm=0; next } }
+        fm==1 || done==1 { next }
+        /^#/ { next }
+        NF>0 {
+          gsub(/^[[:space:]]*[-*+>]*[[:space:]]*/, "");
+          gsub(/\*\*/,""); gsub(/`/,"");
+          while (match($0, /!\[[^]]*\]\([^)]*\)/)) $0 = substr($0,1,RSTART-1) substr($0,RSTART+RLENGTH);
+          while (match($0, /\[[^]]*\]\([^)]*\)/)) {
+            link = substr($0, RSTART, RLENGTH);
+            sub(/\]\([^)]*\)/, "]", link);
+            gsub(/^\[|\]$/, "", link);
+            $0 = substr($0,1,RSTART-1) link substr($0,RSTART+RLENGTH);
+          }
+          print; done=1
+        }
+      ' "$f")"
+      [ -n "$hook" ] || hook="(无正文)"
+      if [ "${#hook}" -gt 80 ]; then
+        hook="${hook:0:77}…"
+      fi
+
+      printf -- "- [%s](%s) — %s\n" "$title" "$rel" "$hook"
+    done < <(find "$dir" -maxdepth 1 -name '*.md' -type f ! -name '_template.md' ! -name 'README.md' | sort)
+    echo
+  done
+} > "$TMP_FILE"
+
+mv "$TMP_FILE" "$INDEX_FILE"
+entries="$(grep -c '^- \[' "$INDEX_FILE" || true)"
+echo "Index regenerated: $INDEX_FILE ($entries entries)"
@@ -0,0 +1,41 @@
+# Wiki Index
+
+> 自动生成（scripts/reindex.sh）— 不要手改。每行一个条目：[标题](相对路径) — 正文首行摘要
+
+用法：skim 找相关条目 → 打开对应文件看细节。新页面 reindex 后自动出现。
+
+## investing
+
+- [NVIDIA Investment Thesis](investing/nvidia-thesis.md) — NVIDIA 是 AI 基础设施的核心供应商，CUDA 生态护城河极深。数据中心 GPU 需求由 LLM 训练 + 推理双轮驱动。
+
+## tech
+
+- [DeepSeek 梁文锋投资会议录：克制的哲学与 AGI 路径](tech/2026-07-23-deepseek-liangwenfeng-investor-meeting.md) — 来源：elsewhere 公众号报道的 DeepSeek 融资会议实录
+- [Application](tech/application.md) — ElasticSearch
+- [Apps](tech/apps.md) — (无正文)
+- [Database](tech/database.md) — Mysql
+- [Devops](tech/devops.md) — Jenkins
+- [Fintech](tech/fintech.md) — (无正文)
+- [Go](tech/go.md) — value: Variable must not be modified
+- [Iot](tech/iot.md) — MQTT is a Client Server publish/subscribe messaging transport protocol. It is…
+- [Java](tech/java.md) — Serial GC
+- [Javascript](tech/javascript.md) — Arrow function
+- [K3s Homelab](tech/k3s-homelab.md) — 主节点: 192.168.1.2 (单节点 K3s)
+- [Kotlin](tech/kotlin.md) — kotlin
+- [Microservice](tech/microservice.md) — benefits
+- [Ruby](tech/ruby.md) — (无正文)
+- [Software Design](tech/software-design.md) — when to refactor
+- [Team Work](tech/team-work.md) — Retrospective
+- [Testing](tech/testing.md) — unit test
+- [Uncategorised](tech/uncategorised.md) — UUID use current time and your computer MAC address to generate the id
+- [Web](tech/web.md) — 200 OK
+- [Web Scraping](tech/web-scraping.md) — content downloading, download images, contents and so on.
+
+## life
+
+- [钢琴学习项目](life/piano-projects.md) — 成人功利型 / 项目制学琴：先快速弹出一首可听的曲子获得正反馈，再反向补基础。
+
+## decisions
+
+- [KB 借鉴 Opus 设计：轻量索引 + prefs/projects + decisions 开张](decisions/2026-08-01-kb-evolution.md) — Date: 2026-08-01
+
@@ -0,0 +1,18 @@
+---
+title: "KB 借鉴 Opus 设计：轻量索引 + prefs/projects + decisions 开张"
+created: 2026-08-01
+updated: 2026-08-01
+tags: [tech/kb, tech/agent]
+---
+
+# KB 借鉴 Opus 设计：轻量索引 + prefs/projects + decisions 开张
+
+- Date: 2026-08-01
+- Context: Claude Opus 给大哥设计了多 Agent 共享 kb（facts/prefs/projects/refs/docs/journal + AGENTS.md 自动索引）。与本地 ~/Code/kb 逐条对比后评估取舍。
+- Options considered:
+  1. **整体迁移到 Opus 结构** — agent 直写无审查、one fact per file、AGENTS.md 做入口。缺点：丢掉 ingest 管道（raw 2900+ 文件）+ 人类筛选 gate，知识库会膨胀成垃圾场。
+  2. **保持现有架构，只借鉴 3 处** — 轻量索引、prefs/ + projects/ 目录、decisions 落盘。缺点：多 Agent 共享能力仍有限。
+  3. 不动 — 缺点：wiki 膨胀后 agent 发现性差，偏好只活在 Hermes memory 里。
+- Decision: 选项 2。新增 `scripts/reindex.sh` 生成 `wiki/INDEX.md`；建 `prefs/`、`projects/`；`decisions/` 开张。
+- Rationale: 现有 raw→wiki + 人类筛选是核心优势，不能丢；索引解决发现性问题；prefs/projects 让偏好与项目状态脱离 Hermes 私有 memory，多工具可读。**不照搬**：agent 直写、one-fact-per-file、CLAUDE.md symlink hack。
+- Outcome: 2026-08-01 实施完毕，INDEX.md 已生成。
@@ -0,0 +1,17 @@
+---
+title: "[Decision Title]"
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+tags: [tech/decision]
+---
+
+# [Decision Title]
+
+- Date: YYYY-MM-DD
+- Context: [什么情况，为什么需要决策]
+- Options considered:
+  1. [选项 A + 一句话优劣]
+  2. [选项 B + 一句话优劣]
+- Decision: [选了哪个 + 一句话]
+- Rationale: [为什么选它，放弃什么]
+- Outcome: [如果已知，事后验证结果]