206 lines
7.4 KiB
Markdown
206 lines
7.4 KiB
Markdown
# 存储规格
|
||
|
||
## Wiki 根目录
|
||
|
||
所有 wiki 存储在工作目录下的 `.wiki/` 目录中：
|
||
|
||
```
|
||
{项目根目录}/
|
||
└── .wiki/
|
||
├── enterprise-annuity/ # 一个研究主题一个目录
|
||
├── charlie-munger/
|
||
└── public-fund/
|
||
```
|
||
|
||
**位置选择逻辑**（按优先级）：
|
||
1. 如果当前目录有 `.wiki/` → 使用它
|
||
2. 如果当前目录有 `.claude/` → 在同级创建 `.wiki/`
|
||
3. 如果当前目录是 git repo 根 → 在根目录创建 `.wiki/`
|
||
4. 否则 → 在当前目录创建 `.wiki/`
|
||
|
||
**与 .gitignore 的关系**：建议将 `.wiki/` 加入 `.gitignore`（wiki 是个人知识库，不应随项目代码提交）。如果用户希望版本管理 wiki，可以在 `.wiki/` 内单独 `git init`。
|
||
|
||
### Obsidian 兼容
|
||
|
||
`.wiki/` 目录可直接作为 Obsidian vault 打开（`Open folder as vault`）：
|
||
|
||
- `[[slug]]` / `[[slug|display]]` → Obsidian Graph View 自动渲染拓扑
|
||
- YAML frontmatter → Obsidian Properties 面板，可按 confidence、type 等字段过滤
|
||
- `sources/`、`entities/`、`concepts/` 目录 → Obsidian 文件夹视图
|
||
|
||
**首次创建 `.wiki/` 时**，Agent 应初始化 `.obsidian/` 配置目录，启用图谱着色：
|
||
|
||
```
|
||
.wiki/.obsidian/
|
||
├── graph.json # 图谱配色方案（按 path 和 tag 分组着色）
|
||
├── app.json # {}
|
||
├── appearance.json # {}
|
||
└── core-plugins.json # 启用 graph、backlink、properties、tag-pane
|
||
```
|
||
|
||
`graph.json` 预设 5 个颜色分组：
|
||
|
||
| 分组规则 | 颜色 | 说明 |
|
||
|---------|------|------|
|
||
| `path:sources/` | 蓝灰 | 源文件 |
|
||
| `path:entities/` | 青绿 | 实体 |
|
||
| `path:concepts/` | 翠绿 | 概念 |
|
||
| `path:analyses/` | 紫色 | 分析 |
|
||
| `[confidence:contested]` | 红色 | 有争议的节点（Obsidian Properties 语法匹配 frontmatter） |
|
||
|
||
同时设置：
|
||
- `showTags: false`（不在图谱中显示 tag 节点——着色靠 `path:` 和 Properties 查询，tag 仅用于搜索过滤）
|
||
- `showArrow: true`（显示关系方向）
|
||
- `textFadeMultiplier: -1.5`（默认显示节点标签）
|
||
- `search: "-path:index -path:log"`（排除 index 和 log 元文件）
|
||
|
||
如果需要排除 `_report.html` 等生成文件，在 Obsidian Settings → Files & Links → Excluded files 中添加 `_*`。
|
||
|
||
### 可视化报告
|
||
|
||
运行 `python schema.py --report .wiki/{主题}/` 生成 `_report.html`，浏览器打开即可查看：
|
||
|
||
- 统计面板：页面数、类型分布、contested 数
|
||
- 交互式关系图：vis-network.js 渲染，可拖拽、缩放
|
||
- 数据表：所有结构化数据点（value + unit + period + confidence）
|
||
- Freshness：按更新日期排序
|
||
- Coverage Gaps：孤页、缺失页面
|
||
|
||
## 单个 Wiki 的目录结构
|
||
|
||
```
|
||
.wiki/{主题名}/
|
||
├── data.db # 结构化数据（SQLite，store.py 管理）
|
||
├── meta.yaml # Wiki 元数据（本体类型、创建时间、描述）
|
||
├── index.md # 页面目录（Agent 自动维护）
|
||
├── log.md # 操作日志（append-only）
|
||
├── _report.html # 可视化报告（schema.py --report 生成）
|
||
├── sources/ # 源文件摘要页（不可变）
|
||
│ ├── 2026-04-06-policy-doc.md
|
||
│ └── 2026-04-03-annual-report.md
|
||
├── entities/ # 实体页（叙事分析）
|
||
│ ├── alpha-corp.md
|
||
│ └── regulatory-agency.md
|
||
├── concepts/ # 概念页
|
||
│ ├── fiduciary-responsibility.md
|
||
│ └── portable-annuity.md
|
||
└── analyses/ # 分析归档页（query 产出）
|
||
└── market-comparison.md
|
||
```
|
||
|
||
### 数据分层原则
|
||
|
||
| 层 | 载体 | 存什么 | 为什么 |
|
||
|----|------|--------|--------|
|
||
| **叙事层** | Markdown 页面 | 分析、上下文、wikilink | 人类阅读、Obsidian 浏览 |
|
||
| **数据层** | data.db (SQLite) | 数值、时序、关系、history | 聚合查询、跨页面对比、时间线 |
|
||
| **元数据层** | YAML frontmatter | title, type, created, updated, sources, confidence | 页面身份标识 |
|
||
|
||
**Frontmatter 不再存储 `data` 和 `history` 字段。** 所有结构化数据写入 `data.db`。
|
||
Frontmatter 只保留：`title`, `type`, `created`, `updated`, `sources`, `confidence`。
|
||
`relations` 在 frontmatter 中保留（Obsidian wikilink 渲染需要），同时写入 `data.db`（查询需要）。
|
||
|
||
### data.db 初始化
|
||
|
||
Wiki 创建时，Agent 运行 `python store.py init .wiki/{主题}/` 初始化数据库。
|
||
表结构见 `store.py`，包含：`pages`, `data_points`, `history`, `relations`。
|
||
|
||
## meta.yaml
|
||
|
||
每个 wiki 的元信息，创建时写入，后续 lint 时更新统计：
|
||
|
||
```yaml
|
||
name: my-research-topic
|
||
ontology_type: domain # domain | cognitive | general
|
||
description: 研究主题描述
|
||
seed: fibo-pensions # 可选，引用 seeds/ 下的种子文件名
|
||
created: 2026-04-06
|
||
last_ingest: 2026-04-06
|
||
stats:
|
||
sources: 3
|
||
entities: 8
|
||
concepts: 5
|
||
analyses: 1
|
||
total_pages: 17
|
||
contested_count: 1
|
||
```
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| name | 是 | wiki 目录名 |
|
||
| ontology_type | 是 | domain / cognitive / general |
|
||
| description | 是 | 一句话描述研究主题 |
|
||
| seed | 否 | 种子配置名，对应 `seeds/{name}.md`。不设则无种子，wiki 自由生长 |
|
||
| created | 是 | 创建日期 |
|
||
| last_ingest | 是 | 最近 ingest 日期（Agent 更新） |
|
||
| stats | 是 | 页面统计（Agent / lint 更新） |
|
||
|
||
## 初始化模板
|
||
|
||
### 新建 Wiki 时创建的 index.md
|
||
|
||
```markdown
|
||
# {主题名} Wiki Index
|
||
|
||
> 0 pages | Created: {日期} | Type: {ontology_type}
|
||
|
||
## Sources (0)
|
||
|
||
## Entities (0)
|
||
|
||
## Concepts (0)
|
||
|
||
## Analyses (0)
|
||
```
|
||
|
||
### 新建 Wiki 时创建的 log.md
|
||
|
||
```markdown
|
||
# {主题名} Wiki Log
|
||
|
||
## {日期} — init
|
||
- Created wiki: {主题名}
|
||
- Ontology type: {ontology_type}
|
||
- Description: {描述}
|
||
```
|
||
|
||
## 文件大小预期
|
||
|
||
| Wiki 规模 | 源文件数 | 总页面数 | 磁盘占用 | 适用检索方式 |
|
||
|-----------|---------|---------|---------|------------|
|
||
| 小 | 1-10 | 5-30 | < 1 MB | grep + 读 index |
|
||
| 中 | 10-50 | 30-150 | 1-10 MB | grep + 读 index |
|
||
| 大 | 50-200 | 150-500 | 10-50 MB | 需要升级到索引检索（超出 Skill 范围） |
|
||
|
||
**默认模式上限：~500 页。** 超过后启用 SQLite FTS5 索引（零依赖，Python 自带），支持 BM25 排序和反向链接查询。详见 `scaling.md`。
|
||
|
||
> 再往上（需要向量检索 / 多用户协作），迁移到外部平台。
|
||
|
||
## 跨 Wiki 操作
|
||
|
||
`query` 默认在单个 wiki 内搜索。如果用户问的问题跨越多个 wiki：
|
||
|
||
```
|
||
用户：Munger 的投资框架和企业年金领域有什么交叉？
|
||
|
||
Agent：
|
||
1. 读 .wiki/ 下的目录列表，识别相关 wiki
|
||
2. 分别读 charlie-munger/index.md 和 enterprise-annuity/index.md
|
||
3. 在两个 wiki 中搜索相关页面
|
||
4. 综合回答，标注来源属于哪个 wiki
|
||
```
|
||
|
||
## 源文件处理
|
||
|
||
不同格式的源文件，ingest 时的处理方式：
|
||
|
||
| 格式 | 处理方式 | 说明 |
|
||
|------|---------|------|
|
||
| 文本 / Markdown | 直接读取 | 最理想的输入格式 |
|
||
| PDF | 读取文本内容（Agent 能力范围内） | 复杂排版可能丢失结构 |
|
||
| Excel / CSV | 读取数据，提取关键指标 | 数值数据写入实体页的"关键数据"段落 |
|
||
| 用户口述 / 对话文本 | 作为文本 ingest | 标注来源为"口述"，confidence 默认 medium |
|
||
| URL / 网页 | 用 WebFetch 获取内容后 ingest | 标注来源 URL |
|
||
|
||
**Agent 不存储源文件原件**——只存储 source 摘要页。原件由用户自行管理。
|