数据文件夹与文件格式

数据文件夹（Vault，在 Markdown 工具中常这样称呼）是 TandemLoop 存储你全部数据的文件夹。它只包含普通的文本文件——带 YAML 头部的 Markdown——位于你在设置时选择的位置：本地或 iCloud 云盘中。因此，其他工具、AI 智能体，当然还有你自己，都可以用任意文本编辑器读取它。

文件夹结构

{数据文件夹}/
  AGENTS.md                  ← 给 AI 智能体的说明
  _inbox/                    ← 快速录入的任务（GTD 收件箱）
  bereiche/                  ← 你的领域（每个领域一个子文件夹）
    {领域}/
      area_{slug}.md         ← 领域元数据
      _projects/             ← 该领域的项目
      _singles/              ← 直接位于领域中的独立任务
      _folders/              ← 可选的文件夹
        {文件夹}/
          fld_{slug}.md      ← 文件夹元数据
          _projects/
          _singles/
  _config/                   ← 配置（标签、属性、主题、显示、语言）
    tags.yaml
    attributes/              ← 自定属性（每个属性一个文件）
      {键名}.yaml
    themes/                  ← 主题（每个主题一个文件）
      {键名}.yaml
    agent.yaml               ← AI 智能体的最近一次运行（由智能体写入）
    language.yaml            ← 数据文件夹的语言
  _views/                    ← 已存储的视图（也可在子文件夹中）
    vw_{slug}.yaml
  _proposals/                ← AI 的提案
    prop_{slug}.md
  _archive/                  ← 已归档的条目（请勿手动编辑）
  _conflicts/                ← 备份的 iCloud 冲突副本
  _system/                   ← 架构和自动生成的参考文档

以 _ 开头的目录是系统文件夹，由 App 管理。

条目 ID 与文件名前缀

每个条目都在其 Frontmatter 的 id 字段中带有一个基于 UUID 的稳定 ID。文件名与 ID 无关，使用易读的 slug。只有视图、视图文件夹（vf_…）和提案的 ID 中包含 slug。较早的文件可能仍使用 slug 形式的 ID（例如 area_arbeit）。

数据约定

文件格式遵循三条原则：

宽容读取：即使缺少字段、包含未知的状态值，或文件来自旧版本，App 也能读取。这样，手动编辑过的条目或由 AI 智能体创建的条目就不会导致整个 App 无法使用。

稳定写入：更新文件时，App 会保留现有字段的顺序和已有信息。外部编辑器添加的未知字段也会保留。后来新增的字段（例如提醒 remind_at）会被 App 追加到 Frontmatter 末尾；空字段写作 null，只有 remind_at 和 repeat: 等少数字段在未设置时完全不出现。

机器可读：由于这些都是纯文本 Markdown 文件，AI 智能体和其他工具可以直接读取数据文件夹。它们可以直接进行哪些更改，详见与 AI 智能体协作一章。

自定属性

自定属性（在设置的属性中）可以为任务、项目和里程碑添加额外字段。每个属性都是 _config/attributes/ 中的一个小 YAML 文件——文件名就是属性的键名：

key: kunde
name: 客户
type: select
applies_to:
  - task
  - project
options:
  - ACME
  - Contoso
description: 这项工作是为哪位客户完成的。

属性值写在相应文件 Frontmatter 的 attributes: 下：

attributes:
  kunde: ACME
  budget: 12000
  abnahme: '2026-11-30'

• 类型：text、number（数字）、date（'YYYY-MM-DD'）、boolean（是/否）、select（选项之一）、url（链接）。
• 键名只能由小写字母、数字和下划线组成，且不得与 status 或 due_date 等内置字段相同。键名之后无法更改。
• 空字段不会被存储。删除属性不会移除已有的值——这些值仍保留在文件中，并在检查器中显示为只读行。
• 在视图中，属性以 attributes.键名 字段的形式提供，可用于过滤、排序和分组。

重复任务

重复规则写在任务 Frontmatter 的 repeat: 下，例如每周一：

repeat:
  unit: week
  days: [mon]

unit 可以是 day、weekday、week、month 或 year；此外还可选 every（间隔）、day 或 nth + weekday（按月规则）、from: completion（从完成时算起），以及作为结束条件的 until 或 count。series、occurrence 和 next 这几个键由 App 自行维护。面向智能体的完整参考位于 _system/docs/data-model.md。

主题

每个主题都是 _config/themes/ 下的一个 YAML 文件——不含扩展名的文件名就是它的键名（nordlicht.yaml → nordlicht）。主题只列出与默认值不同的颜色：

name: 北极光
description: 清冷的青绿色，搭配深色背景。
appearance: system        # system、light 或 dark
font_design: rounded      # default、rounded、serif 或 monospaced
colors:
  primary:
    light: "#0F766E"
    dark: "#2DD4BF"
  danger: "#E5484D"       # 一个值同时用于浅色和深色

颜色以带引号的十六进制值表示，含不透明度时写作 #RRGGBBAA。有哪些颜色键、哪些由其他颜色推导，以及默认值是什么，都写在 _system/docs/themes.md 中——这份参考由 TandemLoop 自行维护，以便 AI 智能体设计出合适的主题。当前启用哪个主题由每台设备各自存储；主题文件本身随数据文件夹同步。

关系块

除收件箱中的任务外，每个任务、项目、里程碑和文件夹文件都会在正文末尾包含一小段机器可读的内容，以相对 Markdown 链接的形式存储上级关系，下面是项目“Website-Relaunch”中一个任务的示例：

<!-- tandemloop:relations:start -->
[Bereich: Arbeit](../../../area_arbeit.md) · [Projekt: Website Relaunch](../prj_website-relaunch.md)
<!-- tandemloop:relations:end -->

这个块由 App 自动保持最新，无需手动编辑；AI 智能体在新文件中省略它，在移动文件时将其删除。即使没有 App 的内存索引，工具和智能体也能借助它看清层级归属。

数据文件夹的语言

TandemLoop 自己写入文件的少量文本——关系块中的字段名（Bereich: / Area: …）、任务记录中的标题（## Du — 21.3.2026 / ## You — 2026-03-21）、提案的各部分（## Diskussion / ## Discussion）以及给 AI 智能体的说明（AGENTS.md、_system/docs/）——都遵循数据文件夹的语言。它记录在 _config/language.yaml 中：

language: en

新建的数据文件夹为英语；没有这个文件的数据文件夹（来自旧版本）保持德语。数据文件夹的语言与设备语言无关——因此所有设备写入的文件都相同。读取时，TandemLoop 能识别两种写法。

多台设备：通过 iCloud 云盘同步

TandemLoop 没有自有服务器，也不会主动向网络传输任何数据。由于数据文件夹是一个普通文件夹，只要把它放在 iCloud 云盘中，就能在多台设备上使用。iCloud 会在 Mac、iPad 和 iPhone 之间保持文件最新；TandemLoop 在每台设备上读取同一个文件夹，并在需要时从 iCloud 载入缺少的文件。