---
name: orbit-os
version: "1.4.2"
updated: 2026-04-08
description: "知识库 OrbitOS Obsidian Vault 共享配置。Vault 结构、格式规则、排版规范。被 orbit-* 系列 skill 自动引用；也可在知识库相关操作中直接调用以获取上下文。"
---
OrbitOS 共享配置，供 orbit-* 系列 skill 自动引用；也可在知识库相关操作中直接调用以获取 Vault 上下文。

# Vault 结构

库路径: `"/Users/suqi3/Library/Mobile Documents/iCloud~md~obsidian/Documents/Sam's"`

| 目录 | 用途 |
|------|------|
| `01_日记` | 每日日志（按月归档：`YYYY-MM/YYYY-MM-DD.md`） |
| `02_项目` | 活跃项目（扁平结构，按名称组织） |
| `03_研究` | 永久参考资料 |
| `04_知识沉淀` | 原子概念笔记 |
| `05_资讯` | 策展内容（Newsletters/、产品发布/） |
| `06_计划` | 执行计划（完成后归档） |
| `07_资产` | 工具资产与可复用配置沉淀 |
| `08_llm-wiki` | LLM Wiki 结构化知识层（raw / entities / concepts / queries） |

# 结构与元数据规范

- Frontmatter 必须在文件第一行，`---` 开头和结尾
- 多值字段用数组: `tags: [tag1, tag2]`
- 不允许重复键
- `---` 结束后不留空行
- 使用 wikilinks `[[NoteName]]` 连接笔记
- 项目通过 frontmatter 的 `area` 字段关联领域，不用文件夹层级
- 相关链接放在正文底部 `## See Also`，不放 frontmatter
- 外部脚本写入 `.md` 后必须执行 `touch "<file>"`（路径必须加引号/转义）以触发 Obsidian 感知
- 禁止未加引号的 `touch <file>`：含空格文件名会被 shell 拆分，产生意外 0 字节文件

# 引用与路径规范

- 默认使用短引用：`文件名:行号`（例如 `TrainRequestBO.java:46`）
- 若存在同名文件冲突，再使用最短必要相对路径 + 行号
- 默认不输出绝对路径和 markdown 可点击绝对路径链接
- 仅当用户明确要求“可点击地址”时，才提供绝对路径链接
- 同一段落中引用风格保持一致，避免混用

# 媒体资产规范（推特文章，简版）

- 默认推特文章路径：`03_研究/推特文章/YYYY-MM/`
- 若用户明确指定“推特精选”栏目（精选沉淀），canonical 原文放：`04_知识沉淀/推特精选/<author>/文章名.md`
- 文件名使用中文短标题，不加日期前缀；日期写入 frontmatter 的 `date` 与 `updated`
- 有图时默认本地化到同级目录：`.../assets/<slug>/`
- 图片文件名使用顺序编号：`img-0.ext`、`img-1.ext`、`img-2.ext`（保留原扩展名）
- 文内图片使用相对路径：`![图 1｜说明](assets/<slug>/img-0.jpg)`，建议补一行图注
- 仅当用户明确要求“只保留外链”时，才允许不落地图片
- 与 LLM Wiki 联动时：`08_llm-wiki/raw/articles/*.md` 可作为 source bridge，链接到 canonical 原文（避免 sources 路径频繁变更）

# 媒体资产规范（链接完整保存，通用）

- 触发：用户提供链接并要求“完整保存/完整还原/原文转录/含图保存/1:1 保留”
- 范围：`03_研究/`、`04_知识沉淀/`、`05_资讯/`
- 落地：文档写入目标栏目；图片保存到同级 `assets/<slug>/`，命名 `img-0.ext`、`img-1.ext`（保留扩展名）
- 引用：正文只用相对路径；仅在用户明确要求时保留外链
- 统计口径：只算正文信息图，忽略 logo/头像/分享按钮等装饰图
- 优先级：推特文章仍优先使用“推特文章规范”

## 完成条件（DoD）

- 若源文正文有图，必须满足：`预期图片数 = 下载成功数 = 文内引用数`
- 任一不相等即未完成；缺图必须阻塞交付并附缺失清单

## 最小流程

1. 识别正文图片并记录预期数量
2. 下载到 `assets/<slug>/`，正文按原位插图（相对路径）
3. 做三数一致校验（预期=下载=引用）
4. 外部写入 `.md` 后执行 `touch "<file>"`（必须加引号）

## 缺图模板

```text
状态：未完成（缺图）
- img-<n> | <url> | <reason> | <attempts>
处理：阻塞交付，待补齐后再完成。
```

# 内容呈现规范

输出到 Obsidian 的文档必须遵循以下排版风格:

## 文档开头
- 第一个内容块用 `> [!info]` callout 概括核心目标或文档定位

## 标题层级
- H2 带编号: `## 1. 标题名 (English Name)`，中英文双语
- H3 用于子节，不带编号
- 章节之间用 `---` 分隔

## 强调与标记
- 关键术语首次出现时加粗
- 技术名词、代码符号用行内代码包裹
- 代码块必须标注语言

## Callout 使用
- `> [!info]` 用于关键洞察、原理解释
- `> [!warning]` 用于注意事项、风险提示
- 普通引用块 `>` 用于类比、比喻、形象说明

## 内容组织
- 复杂概念先给出简短直觉解释，再展开细节
- 对比说明用并列代码块或表格
- 每个主要章节结尾可加引导思考或小结

# 日记填充规则

写日记（`01_日记/YYYY-MM/YYYY-MM-DD.md`）时，`## 日志` 部分应自动从 GitHub 拉取当天跨仓库的 commit 记录。

- GitHub 用户名: `codingSamss`
- 数据源: `gh api` Events API + Commits API
- 不加 `author` 参数，避免邮箱不匹配

## 写入格式

按仓库分组，每个仓库一个 H3，附 commit 数量。每条 commit 用列表项，末尾括号标 short sha。同仓库多条 commit 归纳出一句主线描述。

```markdown
### {repo}（N commits）

主线：一句话概括本仓库今天的改动方向

- commit 描述（`sha`）
- commit 描述（`sha`）
```

# 项目笔记结构 (C.A.P.)

- **背景 (Context)**: 目标、背景、为什么重要
- **行动 (Actions)**: 阶段/里程碑与任务
- **进展 (Progress)**: 更新记录

最小模板:

```markdown
---
area:
tags: [project]
status: active
---
## Context
## Actions
## Progress
```

# 规范优先级

当子 skill（如 orbit-diary）定义的规则与本文件冲突时，子 skill 特例优先于 orbit-os 基线。

# 校验清单

写入 Vault 前必检:

- [ ] Frontmatter 在第一行，无重复键
- [ ] H2 带编号且中英双语
- [ ] 代码块标注语言
- [ ] `## See Also` 在正文底部
- [ ] 引用默认使用短格式（`文件名:行号`），避免长绝对路径
- [ ] 推特文章路径为 `03_研究/推特文章/YYYY-MM/中文短标题.md`
- [ ] 有图文内容时，图片已本地化到同月 `assets/<slug>/` 并使用相对路径引用
- [ ] 链接完整保存任务：已生成正文图片清单（仅正文信息图）
- [ ] 链接完整保存任务：已通过三数一致（预期=下载=引用）
- [ ] 链接完整保存任务：若缺图已标记“未完成”并附缺失清单
- [ ] 外部写入后执行 `touch`（路径带引号）
- [ ] 批量自动化后执行一次 0 字节巡检：`find <vault> -type f -name '*.md' -size 0`（若命中，先定位再清理）