tutorial

运行时配置（步骤 0 — 任何处理开始前）

读取以下文件，以配置特定领域的行为：

1. ops/derivation-manifest.md — 词汇映射、平台提示

   • 使用 vocabulary.notes 作为笔记文件夹名称
   • 使用 vocabulary.note / vocabulary.note_plural 指代笔记类型
   • 使用 vocabulary.reduce 作为提取动词
   • 使用 vocabulary.reflect 作为查找关联的动词
   • 使用 vocabulary.topic_map 指代 MOC
   • 使用 vocabulary.inbox 作为收件箱文件夹名称

2. ops/config.yaml — 处理深度、领域上下文

如果这些文件不存在，则使用通用默认值。

立即执行

目标：$ARGUMENTS

• 如果存在 ops/tutorial-state.yaml 且 current_step <= 5：从保存的步骤继续
• 如果目标为 "reset"：删除 ops/tutorial-state.yaml 并重新开始
• 如果不存在状态文件：开始新教程并选择轨道

现在开始。 下方内容定义了流程。

---

检测是否继续

读取 ops/tutorial-state.yaml。如果文件存在且教程尚未完成，则显示：

--=={ ars contexta : tutorial }==--

  Welcome back.
  Track: [track]     [step-progress] Step [N] of 5
  Resuming where you left off...

跳转到已保存的 current_step。不要再次询问轨道。如果 current_step > 5，则教程已完成——询问是否重置。

进度指示器格式：

• 步骤 1/5：[=> ]
• 步骤 2/5：[==> ]
• 步骤 3/5：[===> ]
• 步骤 4/5：[====> ]
• 步骤 5/5：[=====>]

选择轨道（仅限新教程）

显示标题，然后使用 AskUserQuestion：

--=={ ars contexta : tutorial }==--

Which track fits your work best?

  (a) Researcher -- academic papers, domain
      research, literature processing

  (b) Manager -- meeting notes, strategy docs,
      decision tracking

  (c) Personal -- daily observations, goal
      setting, reflective journaling

等待回复。将 a/b/c 分别映射为 researcher/manager/personal。

将初始状态写入 ops/tutorial-state.yaml：

track: [researcher|manager|personal]
current_step: 1
completed_steps: []
started: [ISO 8601 UTC]
last_activity: [ISO 8601 UTC]

---

步骤执行模式

每个步骤都遵循 WHY / DO / SEE。每个步骤开始前显示进度条。每个步骤结束后，更新 ops/tutorial-state.yaml（追加到 completed_steps，递增 current_step，更新 last_activity）。

轨道适配参考

每个步骤都会根据所选轨道调整措辞和示例。结构保持一致，内容则有所不同。

步骤	研究者	管理者	个人
捕获	论文中的论点	会议中的决策	一天中的感悟
发现	论文之间的关联	决策与利益相关方的关联	观察与目标之间的模式
处理	提取论文内容	挖掘会议笔记	凝练日记内容
维护	过时的论点、失效的引文	孤立的决策	缺乏关联的反思
反思	研究图谱的扩展	机构记忆	自我认知模式

---

步骤 1：捕捉 — 创建你的第一条 {vocabulary.note}

WHY：

--=={ ars contexta : tutorial }==--
  [=>    ] Step 1 of 5 -- Capture

  Everything starts with a thought worth keeping.

根据路径调整理念：

路径	WHY 表述
researcher	“研究始于你注意到某件值得记住的事。论文中的一个论点、不同研究中的一种模式，或一个尚未有人提出的问题。系统会将这些内容捕捉为散文句式标题——每个标题都是一个命题，与其他笔记链接时读起来依然自然。”
manager	“良好的决策始于记录观察。会议中出现的一种模式、利益相关者的担忧，或一个战略洞见。系统会将这些内容转化为相互关联的笔记，每个标题都是一个完整的想法——不是‘Q3 planning’这样的标签，而是‘Q3 的推进速度取决于减少上下文切换’这样的论点。”
personal	“成长始于留意。散步时的一个领悟、一周中的一种模式，或一个关于什么才重要的问题。系统会将这些内容捕捉为散文句式笔记——每个标题都是你真心相信的想法，例如‘晨间习惯之所以有效，是因为它能减少决策疲劳’。”

DO：

使用 AskUserQuestion，并根据路径调整提示词：

路径	提示词
researcher	“分享一个来自你研究的论点、观察或问题。用一句话写出你真心想记住并继续探索的内容。”
manager	“分享一个来自你工作的决策、模式或洞见。用一句话写出值得在会议和项目中持续跟踪的内容。”
personal	“分享一个想法、观察或领悟。用一句话写出你真心想记住的内容。”

将输入转换为一条真实的 {vocabulary.note}：

1. 将输入转换为散文式标题文件名（小写、安全字符、完整句子）
2. 创建 YAML frontmatter：

   ---
   description: [adds context beyond the title — scope, mechanism, or implication]
   topics: ["[[index]]"]
   created: [today's date]
   ---
   

3. 用 2-3 个句子展开这个想法
4. 添加 Topics 页脚，链接到中心 {vocabulary.topic_map}
5. 将文件写入 {vocabulary.notes}/

SEE：

  Note created:
    {vocabulary.notes}/[filename].md

  Title: [the prose title]
  Description: [the description]
  Topics: [[index]]

  Notice how the title works as prose:
    "Since [[your note title]], the question
     becomes..."

  That is what makes notes linkable. The title
  IS the thought, expressed as a sentence.

更新状态，然后继续步骤 2。

---

步骤 2：发现 — 找到关联

原因：

--=={ ars contexta : tutorial }==--
  [==>   ] Step 2 of 5 -- Discover

  A note alone is a file. Notes that connect
  become a knowledge graph.

根据不同方向调整：

方向	原因说明
researcher	“当观点彼此关联时，研究成果会不断累积。关于方法论的发现可能会拓展关于工具的发现。一项研究中的模式可能与另一项研究中的模式相矛盾。洞见就蕴藏在这些关联中——不在单篇论文里，而在思想之间的关系中。”
manager	“当决策彼此关联时，组织知识会不断累积。招聘决策与能力方面的顾虑有关。战略调整会影响多个项目。这些关联揭示了个别选择背后的系统。”
personal	“当观察彼此关联时，自我认知会不断累积。关于晨间习惯的洞见可能与精力模式有关。对关系的观察可能会拓展对沟通的认识。这些关联揭示了你真正相信什么。”

操作：

使用 AskUserQuestion，并采用适合该方向的提示词：

方向	提示词
researcher	“分享第二条研究见解——最好能与第一条笔记关联，但任何真实的观点都可以。”
manager	“分享另一条工作观察——最好与第一条有关，但任何真实的见解都可以。”
personal	“分享另一个想法——最好能与第一个关联，但任何真实的观察都可以。”

创建第二条 {vocabulary.note}。然后搜索与第一条 {vocabulary.note} 的关联：

1. 阅读两条 {vocabulary.note_plural}
2. 应用表述测试：你能否完成“[[note A]] 与 [[note B]] 相关，因为 [具体原因]”？
3. 如果确实存在关联：
   • 在一条或两条 {vocabulary.note_plural} 中添加行内 wiki 链接
   • 添加带有上下文短语的 relevant_notes 条目
4. 如果不存在真实关联：
   • 说明牵强地建立关联不如没有关联
   • “这些笔记目前尚无关联，这没关系。图谱会随着时间不断扩展。”

效果：

如果存在关联：

  Note created and connected:
    {vocabulary.notes}/[filename].md

  Connection:
    [[note A]] connects to [[note B]]
    because [your articulated reason]

  This is what /reflect does at scale --
  finding genuine connections across your
  entire graph.

如果不存在关联：

  Note created:
    {vocabulary.notes}/[filename].md

  No genuine connection to your first note.
  That is fine -- forced connections pollute
  the graph. Real connections emerge as your
  graph grows.

更新状态，然后继续步骤 3。

---

步骤 3：处理 — 提取结构化知识

原因：

--=={ ars contexta : tutorial }==--
  [===>  ] Step 3 of 5 -- Process

  Raw material becomes structured knowledge
  through extraction. You mine for atomic
  insights, not summaries.

根据不同方向调整：

方向	原因说明
researcher	“一篇论文包含数十条观点，但只有其中一部分对你的研究有价值。提取意味着找出值得保留的命题——具体观点、方法选择、令人意外的发现——并将每一条都转化为独立笔记。这就是 /{reduce} 的实际应用。”
manager	“会议记录和战略文档中藏着许多洞见。提取意味着找出决策、假设、风险因素，并为每一项单独创建笔记，以便追踪和建立关联。这就是 /{reduce} 的实际应用。”
personal	“日记条目和每日笔记中包含尚未处理的观察。提取意味着找出洞见、模式和真实的感悟，并将每一项凝练成一条笔记，让它与其他内容共同累积。这就是 /{reduce} 的实际应用。”

操作：

使用 AskUserQuestion，并采用适合该方向的提示词：

方向	提示词
researcher	“粘贴一小段原始材料——论文笔记、文章摘录或研究观察。两到五个句子就足够了。”
manager	“粘贴一小段原始材料——会议记录、战略摘录或项目观察。两到五个句子就足够了。”
personal	“粘贴一小段原始材料——日记条目、对话记录或日常观察。两到五个句子就足够了。”

提取 1–2 条原子级见解：

1. 找出值得保留的命题（不是摘要，也不是事务安排）
2. 应用筛选原则：跳过纯对话内容、临时事务安排和模糊观察
3. 检查是否与现有教程 {vocabulary.note_plural} 存在关联
4. 按照正确的架构创建 {vocabulary.note}
5. 存在真实关联时添加链接

效果：

  Extracted [N] insight(s) from your material:

  1. [title of extracted note]
     [connection status: linked to [[note]] | standalone]

  Raw material -> atomic {vocabulary.note_plural} -> connected graph.
  This is what /{reduce} does. It finds the
  propositions worth keeping and turns each into
  a composable {vocabulary.note}.

如果没有值得提取的内容：

  No atomic insights found in this material.
  That happens — not everything contains
  extractable propositions. The selectivity
  gate is working: better to skip than to
  create low-value {vocabulary.note_plural}.

更新状态，然后继续步骤 4。

---

步骤 4：维护 — 检查知识库健康状况

原因：

--=={ ars contexta : tutorial }==--
  [====> ] Step 4 of 5 -- Maintain

  A knowledge system that is not maintained
  decays. Health checks catch problems before
  they compound.

根据轨道调整：

轨道	原因说明
researcher	“当引用失效、论点过时、笔记失去关联时，研究图谱就会衰退。健康检查能在孤立论点、缺少描述和链接失效损害研究完整性之前发现这些问题。”
manager	“当决策变得孤立、链接失效、笔记失去上下文时，组织知识就会衰退。健康检查能在这些问题损害机构记忆之前发现它们。”
personal	“当反思彼此脱节、描述含糊、模式被忽略时，个人知识就会衰退。健康检查能在洞见丢失之前发现这些问题。”

执行：

不要使用 AskUserQuestion。对教程中的 {vocabulary.note_plural} 运行自动迷你健康检查：

1. 描述检查： 每个 {vocabulary.note} 都有描述字段吗？描述是否提供了标题之外的信息？
2. 链接检查： 所有维基链接都能指向现有文件吗？
3. {vocabulary.topic_map} 检查： 每个 {vocabulary.note} 都出现在至少一个 {vocabulary.topic_map} 的 Topics 页脚中吗？
4. 孤立检查： 是否有任何 {vocabulary.note} 没有入链？
5. 连接密度： 每个 {vocabulary.note} 平均有多少个维基链接？

对每项检查，报告 PASS 或 WARN，并说明具体情况。

示例：

  Health check on your [N] tutorial {vocabulary.note_plural}:

  | Check              | Status | Detail              |
  |--------------------|--------|---------------------|
  | Descriptions       | PASS   | All notes described |
  | Links              | PASS   | No broken links     |
  | {vocabulary.topic_map} membership | WARN   | [note] not in MOC   |
  | Orphan risk        | PASS   | All notes connected |
  | Connection density | PASS   | Avg [N] links/note  |

  This is what /health does at scale. It catches
  problems automatically so the graph stays
  healthy as it grows.

如果发现警告，自动修复（添加缺失的 {vocabulary.topic_map} 链接、改进描述），并说明修复了什么。

更新状态，然后继续步骤 5。

---

步骤 5：反思 — 回顾已构建的内容

原因：

--=={ ars contexta : tutorial }==--
  [=====>] Step 5 of 5 -- Reflect

  Step back and see the system you started
  building. A few notes are a beginning.
  The question is what comes next.

根据轨道调整：

轨道	原因说明
researcher	“你已经拥有了研究图谱的雏形。每篇处理过的论文、每个提取出的论点、每条发现的关联，都会让图谱更有价值。复合效应意味着第 100 条笔记比第 1 条更有价值，因为它有 99 种潜在关联。”
manager	“你已经拥有了组织记忆的雏形。每场处理过的会议、每项跟踪的决策、每条发现的关联，都会让系统更有价值。机构知识不再只存在于人们的脑海中，而是开始存在于图谱里。”
personal	“你已经拥有了自我认知系统的雏形。每条记录下来的观察、每个命名的模式、每条发现的关联，都会让系统更有价值。你开始通过累积的证据认识自己，而不只是凭借今天的感受。”

执行：

显示知识库状态摘要：

  What you built:

  {vocabulary.note_plural}: [N]
  Connections: [M] wiki links
  {vocabulary.topic_map_plural}: linked to [[index]]

  Your graph so far:
    [[note 1]] ----> [[note 2]]
         \               |
          '-> [[note 3]] -'

（用简单的 ASCII 图展示教程中的 {vocabulary.note_plural} 之间的实际关联。）

然后展示对方法的理解：

Your system also knows about itself:
  ops/methodology/   Your system's self-knowledge
  /ask [question]    Ask the research behind your
                     system's design

Try: /ask "why does my system use [relevant feature]?"

然后使用 AskUserQuestion：

“接下来你想做什么？你可以：

(a) 记录更多想法（直接告诉我） (b) 处理原始材料（/{reduce} [粘贴内容或文件]） (c) 探索你的系统（/next） (d) 进一步了解某个特定命令（/help [command]）”

这是交接到实际使用环节。不要处理对方的回复，只需确认其选择并指出正确的操作方向。

示例：

--=={ ars contexta : tutorial }==--

  [======] Complete

  You built a working knowledge graph in five
  steps. Every {vocabulary.note} you add from here
  compounds the value of what already exists.

  Quick reference:
    /ask [question]     Query your graph
    /learn [topic]      Research and grow
    /{reduce} [source]  Extract insights
    /{reflect}          Find connections
    /health             Check system health
    /next               What to do next
    /help               Full command guide

---

完成

步骤 5 之后，写入最终状态：

track: [track]
current_step: 6
completed_steps: [1, 2, 3, 4, 5]
started: [original timestamp]
last_activity: [now]
completed: [now]

状态持久化

每一步完成后，都要写入 ops/tutorial-state.yaml。这是不可妥协的要求——教程必须能在不同会话之间恢复。

格式：

track: [researcher|manager|personal]
current_step: [1-6, where 6 = complete]
completed_steps: [array of completed step numbers]
started: [ISO 8601 UTC]
last_activity: [ISO 8601 UTC]
completed: [ISO 8601 UTC, only when done]

会话启动集成： 如果状态存在且尚未完成，会话启动钩子应显示：“你有一个未完成的教程（第 N 步，共 5 步）。使用 /tutorial 继续。”

质量原则

在实践中学习。 每一步都会在知识库中创建实际内容，而非假设性示例。教程中创建的 {vocabulary.note_plural} 都是真实的 {vocabulary.note_plural}，会一直保留，并随着后续内容不断累积。

先讲原因，再讲方法。 每一步都会先解释这件事为何重要，再请用户采取行动。理解动机可以避免教程沦为待办清单。

真实，不强求。 如果用户的输入没有产生有意义的关联，就如实说明。不要为了让教程看起来成功而捏造关联。诚实说明何时存在关联、何时不存在，有助于传授正确的思维模型。

适配不同路径，而非受路径限制。 路径会改变示例和措辞，而不会改变结构。研究人员和个人用户都会经历相同的五个步骤，只是引导方式不同。

循序渐进。 第 1 步非常简单（分享一个想法）。第 5 步则需要理解系统。每一步都建立在上一步的基础上。任何一步都不要求用户掌握教程尚未提供的知识。

边缘情况

用户在第 3 步未粘贴任何内容： 提供一段适合其路径的预先编写的示例段落。「这里有一个示例，你可以用它来了解提取的工作方式：」

用户想跳过某一步： 允许跳过。更新状态，将该步骤标记为已跳过（而非已完成）。教程不应让用户觉得必须闯关。

用户在完成教程后再次运行 /tutorial： 显示完成状态并提供重置选项。「你的教程已完成。运行 /tutorial reset 即可重新开始。」

用户的输入过短（只有一个词）： 温和地请用户补充完整。「你能把它扩展成一个完整的句子吗？系统处理完整想法的效果最好。例如，不要只写『会议』，可以写『如果不跟踪行动事项，每周会议就会失去价值』。」