codingsamss/orbit-os

OrbitOS 共享配置，供 orbit-* 系列 skill 自动引用；也可在知识库相关操作中直接调用以获取 Vault 上下文。

Vault 结构

库路径: 由环境变量 $OBSIDIAN_VAULT_ROOT 指定（本地配置注入；典型形如 $HOME/Library/Mobile Documents/iCloud~md~obsidian/Documents/<你的 Vault 名>）

| 目录 | 用途 | |------|------| | 01_日记 | 每日日志（按月归档：YYYY-MM/YYYY-MM-DD.md） | | 02_项目 | 活跃项目（扁平结构，按名称组织） | | 03_研究 | 永久参考资料 | | 04_知识沉淀 | 原子概念笔记 | | 05_资讯 | 策展内容（Newsletters/、产品发布/） | | 06_计划 | 执行计划（完成后归档） | | 07_资产 | 工具资产与可复用配置沉淀 | | 08_交接台 | 多机器、多 agent 的任务 handoff 与接力索引 |

Agent 交接台规范

08_交接台 只保存可读的 Markdown 交接信息、索引和外部资产链接；大型产物、视频、压缩包、下载物、中间处理文件统一放到 iCloud Drive 顶级目录 AgentArtifacts/，不要放进 Obsidian Vault。

推荐结构:

08_交接台/
  00_Index.md
  01_Inbox/
  02_Active/
    project/
    research/
    knowledge/
    ops/
    media/
  03_Blocked/
    project/
    research/
    knowledge/
    ops/
    media/
  04_Archive/
    YYYY-MM/
  90_Templates/
    task.md
    handoff.md
    assets.md

外部资产结构与任务 task_id 对齐:

iCloud Drive/AgentArtifacts/
  00_Inbox/
  01_Active/
    project/
    research/
    knowledge/
    ops/
    media/
  02_Archive/

任务目录规则:

• task_id 使用 <YYYY-MM-DD>-<english-slug>，例如 2026-06-29-openmontage-douyin-tutorial
• 每个正式任务必须有父目录: 08_交接台/<lifecycle>/<category>/<task_id>/
• 分类固定为 project、research、knowledge、ops、media
• 00_Task.md 是当前真相，记录目标、状态、下一步、owner machine、最新 handoff 和外部资产根
• 01_Assets.md 只记录 AgentArtifacts/<lifecycle>/<category>/<task_id>/ 下的大文件索引，不内嵌大文件
• 单次交接文件命名为 <YYYY-MM-DD-HHMM>__<topic-slug>.md（topic-slug 为本次交接重点的英文短 slug），例如 2026-06-29-1451__douyin-tutorial-research.md；机器与 agent 写进 frontmatter 的 machine / agent，不放进文件名
• handoff 文件按 append-only 处理；要更新当前状态时改 00_Task.md，不要回写旧 handoff
• 生命周期为 01_Inbox -> 02_Active -> 03_Blocked -> 04_Archive/YYYY-MM
• 外部写入 08_交接台 内 .md 后必须执行 touch "<file>"

结构与元数据规范

• 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)，建议补一行图注
• 仅当用户明确要求“只保留外链”时，才允许不落地图片

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

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

完成条件（DoD）

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

最小流程

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

缺图模板

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

内容呈现规范

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

文档开头

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

标题层级

• H2 带编号: ## 1. 标题名
• 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 归纳出一句主线描述。

### {repo}（N commits）

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

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

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

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

最小模板:

---
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（若命中，先定位再清理）