234 lines
12 KiB
Markdown
234 lines
12 KiB
Markdown
---
|
||
title: "WikiLLM 知识库规范"
|
||
last_updated: 2026-08-07
|
||
type: schema
|
||
---
|
||
|
||
# WikiLLM 知识库规范
|
||
|
||
本文件是当前仓库 Wiki 的实际维护规范。它优先适配本仓库已有的 `wiki/INDEX.md`、`wiki/Glossary.md`、`wiki/sources.md`、`wiki/compile-results.tsv` 和 `wiki/compile.log`，不假设存在通用 Wiki 项目的 `index.md` 或其他目录名称。
|
||
|
||
## 1. 分层结构
|
||
|
||
```text
|
||
raw/ # 原始来源和不可变摘编，原则上只读
|
||
├── 期货/ # 期货研究资料
|
||
│ ├── 00-整体相关/
|
||
│ ├── 01-基本分析逻辑/
|
||
│ ├── 10-品种相关/
|
||
│ ├── 20-品种新闻/
|
||
│ ├── 90-待核验/
|
||
│ └── _meta/
|
||
├── 股票/ # 股票投资资料
|
||
├── 估值/ # 企业财务与估值资料
|
||
├── 宏观/ # 宏观经济与房地产等宏观领域资料
|
||
├── 量化/ # 量化交易框架与方法（abuquant 等；源码本体可能不入库，以摘编+哈希清单为证据）
|
||
├── 书籍/ # 经典投资书籍中文摘编（主题子目录 00-价值投资~07-规则与教材；批次状态见 raw/_meta/书籍入库批次清单.tsv）
|
||
├── 技术/ # 软件工具类知识（mihomo 代理内核、PaddleOCR OCR 工具链等）
|
||
├── images/ # 图片类原始资料
|
||
├── llm_wiki/ # 上游 llm-wiki 参考仓库（.git.bak 保留，源码不入库）
|
||
└── _meta/ # 来源清单、迁移记录、哈希等
|
||
|
||
wiki/ # 编译后的可检索知识
|
||
├── concepts/ # 稳定概念、机制和理论
|
||
├── practices/ # 研究、维护和交易实践
|
||
├── queries/ # 有长期复用价值的问答归档
|
||
├── assets/ # Wiki 页面使用的本地图片
|
||
├── _meta/ # 本规范及维护元数据
|
||
├── INDEX.md # 唯一总入口和阅读地图
|
||
├── Glossary.md # 术语定义和页面入口
|
||
├── sources.md # 来源导航与来源分组
|
||
├── compile-results.tsv # 原始来源到 Wiki 页面的编译状态
|
||
└── compile.log # 按时间追加的编译和维护记录
|
||
```
|
||
|
||
`raw/` 保存证据，`wiki/` 保存综合知识。Wiki 页面可以改写和精炼，raw 文件除非用户明确编辑或删除，不应被自动重写、移动或删除。
|
||
|
||
## 2. 页面类型
|
||
|
||
| 类型 | 目录/用途 | 应回答的问题 | 不应承担的内容 |
|
||
|---|---|---|---|
|
||
| `overview` | 总览页 | 这个主题是什么，页面如何分工 | 逐个来源的全部案例细节 |
|
||
| `concept` | `wiki/concepts/` | 一个稳定概念或机制如何运作 | 日常报告模板、单次新闻 |
|
||
| `practice` | `wiki/practices/` | 如何研究、维护或执行 | 把作者观点写成已验证事实 |
|
||
| `case-study` | `wiki/practices/` 或专题页 | 某篇论文、公司或团队实际做了什么 | 把单一案例推广成普遍规律 |
|
||
| `source-derivative` | `raw/` | 原始材料的可检索摘编是什么 | 未经核验的推测和营销结论 |
|
||
| `query` | `wiki/queries/` | 一个具有长期复用价值的问题如何回答 | 一次性查值或临时聊天内容 |
|
||
| `summary` | 入口和资料目录 | 一组资料如何组织、证据边界是什么 | 代替主题页面承载所有正文 |
|
||
|
||
新增页面前先搜索已有页面。出现以下任一情况才新建页面：主题具有独立检索价值、来源中有稳定机制、页面能被至少一个入口链接，或用户明确要求保留为独立研究产物。
|
||
|
||
## 3. Frontmatter
|
||
|
||
普通 Wiki 页面至少包含：
|
||
|
||
```yaml
|
||
---
|
||
title: "页面标题"
|
||
type: concept | practice | case-study | query | summary | overview
|
||
last_updated: YYYY-MM-DD
|
||
tags:
|
||
- "领域"
|
||
confidence: high | medium | low
|
||
contested: true
|
||
raw_sources:
|
||
- path: "raw/相对仓库根目录的来源路径"
|
||
hash: "sha256:..."
|
||
---
|
||
```
|
||
|
||
字段规则：
|
||
|
||
- `title`：与页面主题一致，避免只使用来源标题。
|
||
- `type`：按页面职责填写；历史页面不要伪装成当前实践。
|
||
- `last_updated`：正文或证据边界变化时更新。
|
||
- `tags`：使用已有领域词，避免为单个来源创建临时标签。
|
||
- `confidence`：表示当前页面主张的证据强度，不表示投资收益概率。
|
||
- `contested: true`：存在来源冲突、历史规则、作者预测、第三方主张或尚未解决的证据问题时使用。
|
||
- `raw_sources`：必须指向仓库内实际存在的 raw 文件；外部 URL 放在 `source` 或正文来源说明中，不替代仓库内证据。
|
||
|
||
对于历史交易所规则、作者观点、研报预测、供应商统计和来源方营销主张，应同时写明版本/日期和复核要求。
|
||
|
||
## 4. 页面写作
|
||
|
||
每个概念或实践页优先采用以下顺序：
|
||
|
||
1. 页面定位与职责边界
|
||
2. 定义或研究目标
|
||
3. 核心机制/流程/指标
|
||
4. 证据和不确定性
|
||
5. 失效条件、风险或待核验问题
|
||
6. 相关页面
|
||
|
||
不同页面的职责应分开：
|
||
|
||
- 总览页讲共同框架。
|
||
- 概念页讲一个机制。
|
||
- 实践页讲可执行流程和检查项。
|
||
- 案例页讲某个来源实际声称或实施的内容。
|
||
- raw 摘编保留细节、章节范围和证据限制。
|
||
|
||
不要为了减少行数机械删除公式、单位、统计范围、历史版本、失败模式或原始证据边界。
|
||
|
||
## 5. 期货资料规范
|
||
|
||
期货来源按以下层级组织：
|
||
|
||
- `00-整体相关/`：跨品种制度、宏观、市场结构、资金和风险。
|
||
- `01-基本分析逻辑/`：供需、成本、库存、利润、基差、曲线和研究流程。
|
||
- `10-品种相关/`：一个品种的产业链、合约、交割和数据字典。
|
||
- `20-品种新闻/`：一事一文的事件记录，不直接覆盖长期概念页。
|
||
- `90-待核验/`：来源不完整、预测、网页剪藏和未经确认的观点。
|
||
|
||
所有合约单位、保证金、涨跌停、限仓、仓单有效期、交割地点、厂库名录和套保额度都必须标注规则版本，并在当前交易前重新核验。
|
||
|
||
常用指标必须同时记录统计对象、地区、质量、含税状态、单位、频率和时间口径。例如：
|
||
|
||
```text
|
||
基差 = 现货价格 - 对应期货价格
|
||
库存可用天数 = 与库存范围匹配的库存量 / 对应日均出货量
|
||
```
|
||
|
||
这些是研究计算口径；若原始材料没有给出公式，不得声称它是原文公式。
|
||
|
||
## 6. 来源和状态
|
||
|
||
`wiki/compile-results.tsv` 是机器可读的来源状态表，字段固定为：
|
||
|
||
```text
|
||
raw_path hash last_modified wiki_paths compile_time status
|
||
```
|
||
|
||
维护规则：
|
||
|
||
- 同一个 `raw_path` 只保留一行。
|
||
- `wiki_paths` 列出该来源影响的全部 Wiki 页面。
|
||
- 二进制来源使用文件字节 SHA-256。
|
||
- raw Markdown 摘编若按正文哈希登记，必须在维护记录中明确哈希范围；不要用通用整文件哈希覆盖既有约定。
|
||
- 用户主动删除 raw 文件并要求同步时，删除对应派生 Wiki 页、导航、来源状态和仅由该页支撑的术语；保留编译日志中的删除记录。
|
||
- 用户主动修改的 raw 文件先报告漂移，不自动重写哈希。
|
||
|
||
## 7. 导航和链接
|
||
|
||
- 知识域组织：Wiki 以**投资**为主域（期货 / 股票 / 宏观与房地产 / 量化交易 / 经典投资书籍），**LLM Agent 与 Harness 工程**和**软件工具**为方法论与工具域；`INDEX.md` 反映该归属，期货研究是投资域下「期货」板块的组成部分，不与其他投资板块平级并列。
|
||
- 时序内容约定：月度/季度市场回顾等日期型页面按历史层维护（frontmatter 标注 `status: historical` 或保留原 `confidence` 并注明时点），由更高频综述（季度/年度）页面引用，不无限累积平行回顾页；新回顾页只链接近期回顾，旧回顾由综述页承接。
|
||
- `wiki/INDEX.md` 是唯一总入口，负责阅读顺序和首选页面，不必重复列出所有来源。
|
||
- `wiki/sources.md` 负责来源导航和来源分组。
|
||
- `wiki/Glossary.md` 负责术语定义；同一术语只保留一个统一定义，多个来源语境用“补充说明”表达。
|
||
- 新页面至少连接到一个入口和一个相关页面；有意义时补充返回链接。
|
||
- `[[wikilink]]` 目标必须解析到 `wiki/` 下的 Markdown 页面。
|
||
- 图片使用相对当前页面的路径，审计时按文件系统真实路径解析。
|
||
|
||
## 8. 每次维护后的检查
|
||
|
||
在声称整理完成前运行：
|
||
|
||
```powershell
|
||
pwsh -File .\tools\wiki-audit.ps1
|
||
```
|
||
|
||
必须确认：
|
||
|
||
- frontmatter 完整；
|
||
- Wiki 内部链接无断链；
|
||
- 图片路径存在；
|
||
- INDEX 覆盖全部内容页；
|
||
- `raw_sources` 路径存在；
|
||
- `compile-results.tsv` 可解析、无重复来源行和占位哈希；
|
||
- 用户主动删除的来源没有活动派生引用；
|
||
- `git diff --check` 通过。
|
||
|
||
超长页面检查默认以 200 行为阈值；经人工确认确实需要保留完整结构的页面，可通过 `tools/wiki-audit.ps1` 的 `$LongPageAllowlist` 白名单豁免。当前白名单包含：`Glossary.md`、`INDEX.md`（唯一总入口与阅读地图，需完整列出全部内容页，2026-08-07 加入）、`concepts/Harness-Engineering-Complete-Guide.md`、`concepts/Meta-Harness.md`、`practices/OpenAI-Codex-Harness-Engineering.md` 和 `queries/What-is-Harness-Engineering-in-Simple-Terms.md`。白名单只抑制超长页面警告，不豁免 frontmatter、链接、图片、来源路径或编译状态检查。
|
||
|
||
审计发现的问题分为：
|
||
|
||
- **ERROR**：链接断裂、TSV 无法解析、frontmatter 缺失、页面未索引。
|
||
- **WARNING**：raw 缺失、哈希漂移、低置信度、争议页面、超长页面。
|
||
- **INFO**：页面数量、链接数量、来源数量等统计。
|
||
|
||
## 9. 可重复的自我反思流程
|
||
|
||
自我反思分为确定性检查和人工内容判断两层，不允许让脚本直接重写知识正文：
|
||
|
||
1. **生成体检**：运行 `pwsh -File .\tools\wiki-audit.ps1`，先处理 ERROR，再记录 WARNING。
|
||
2. **生成反思报告**：运行 `pwsh -File .\tools\wiki-reflect.ps1`，覆盖生成 `wiki/_meta/wiki-review.md`。
|
||
3. **逐项决策**：对报告中的每一项选择 `保留`、`降级`、`补证据`、`合并`、`拆分` 或 `删除`，并说明理由；低置信度和争议页面默认不自动删除。
|
||
4. **最小修改**：只修改已选页面，保留公式、单位、机制、失败模式和证据边界；用户删除 raw 时才执行同步删除级联。
|
||
5. **复核记录**：重新运行两个脚本，把实际变更、未处理事项和来源边界追加到 `wiki/compile.log`。
|
||
|
||
反思报告是可再生的工作队列，不是长期知识页面。它不进入 `INDEX.md`，不参与 Wiki 页面数量和孤岛统计；若需要保留历史判断，应写入 `compile.log` 或单独的审阅记录，而不是手工修改生成报告。
|
||
|
||
推荐命令：
|
||
|
||
```powershell
|
||
pwsh -File .\tools\wiki-audit.ps1
|
||
pwsh -File .\tools\wiki-reflect.ps1
|
||
```
|
||
|
||
严格门禁可使用 `-FailOnWarning` 或 `-FailOnFindings`，但超长页面、历史规则和低置信度页面首先是人工审阅任务，不等于自动错误。
|
||
|
||
## 10. 远程同步与推送流程
|
||
|
||
本仓库的唯一远程是自建 Gitea：`gitea` → `http://10.4.167.10:63000/jzy/my_wiki.git`（账户 `jzy`，分支 `main`）。搭建时参考的 GitHub 上游 `origin` 已移除，不得再依赖外部仓库。
|
||
|
||
每次维护完成后的标准推送：
|
||
|
||
```powershell
|
||
pwsh -File .\tools\wiki-push.ps1 -Audit -Message "描述本次变更"
|
||
```
|
||
|
||
`tools/wiki-push.ps1` 固化流程：
|
||
|
||
1. `-Audit` 时先运行 `wiki-audit.ps1`，存在 ERROR 即中止（`-FailOnWarning` 可升级为严格门禁）；
|
||
2. `git add -A` 并提交（`-Message` 缺省时自动生成 `maintain | 日期 Wiki 增量更新`）；
|
||
3. `git push gitea main`，失败时提示检查网络与凭据。
|
||
|
||
凭据说明：access token 明文保存在 `.git/config` 的远程 URL 中，仅限内网使用；如 token 泄露或服务器可被他人访问，应在 Gitea「设置 → 应用」轮换 token，或改用 SSH 密钥方式。`git` 凭据不得写入仓库内任何文件（`.env`、脚本、日志均禁止）。
|
||
|
||
版本控制约定：
|
||
|
||
- `.obsidian/workspace.json` 等 Obsidian 运行时状态已被 `.gitignore` 排除并停止跟踪，不进入提交；
|
||
- `raw/llm_wiki/.git.bak` 是上游子仓库元数据备份，被 `.gitignore` 排除；恢复上游更新时改名为 `.git` 使用；
|
||
- `__pycache__/` 与 `*.pyc` 等编译缓存不进入提交；
|
||
- 每次推送前应确认 `git status` 中无意外文件，推送后在 Gitea 页面核对提交记录。
|