jdex

前置条件

• 此技能需要 johnnydecimal 技能提供 JD 系统背景知识。
• 此技能用于查找内容并撰写笔记。它本身不会移动文件。下文“移入”和“归档”部分会介绍如何使用 JD CLI 移动文件。如果没有 CLI，请告知用户每个文件应放在哪里，并让他们自行移动。

jd MCP 服务

Johnny.Decimal 的知识来自 jd MCP 服务，而非记忆。知识库是用户在此基础上的个人叠加层。

首先调用 get_account。它会说明该账户拥有哪些系统，以及是否拥有 Pro，这样你就知道哪些工具能提供答案。工具描述会说明每个工具的作用。不要在这里另存一份。

应从哪个来源获取答案：

• 用户的笔记、文件和业务：从知识库获取。不要向 MCP 查询用户自身内容的相关事实。
• Johnny.Decimal 本身的工作方式：调用文档工具。不要凭记忆回答 JD 概念问题。
• 当前 ID：按以下顺序读取两者。

如果服务未连接，只需说明一次，然后继续仅使用知识库。说明缺少了什么：没有服务时，你只能凭记忆回答 Johnny.Decimal 问题，而错误答案往往由此产生。使用以下命令连接：

claude mcp add --transport http jd https://johnnydecimal.com/mcp

配置文件和 CLI 的位置

JD CLI 知道其文件的路径。通过 CLI 获取每个路径。如果 CLI 能提供路径，就不要自行计算。

• 程序位于 ~/.local/share/johnnydecimal/cli/bin/jd。无需预先执行任何 source 命令。
• ~/.local/share/johnnydecimal/cli/bin/jd paths config 会打印配置文件的路径。
• ~/.local/share/johnnydecimal/cli/bin/jd paths 会打印三个路径：配置文件、日志文件和包含 CLI 的文件夹。

在 4.0 版之前，CLI 会将所有文件保存在 ~/.jd 中。程序位于 ~/.jd/cli/bin/jd。配置文件位于 ~/.jd/config.json。仍位于 ~/.jd 中的 CLI 会继续运行。

• 如果程序不在第一个路径中，请运行 ~/.jd/cli/bin/jd help。如果该命令能运行，则在此技能给出的每条命令中使用 ~/.jd/cli/bin/jd。
• 如果 CLI 位于 ~/.jd 中，只需告知用户一次。告诉他们你可以更新并移动 CLI。服务器上的 install_cli 提供操作步骤。执行这些步骤前先征求用户同意。不要自行移动文件。
• 如果 paths 报错，则 CLI 版本低于 4.0。此时，若用户设置了 $JD_CONFIG，配置文件就是该路径；否则配置文件位于 ~/.jd/config.json。只需告知用户一次 CLI 版本较旧，并说明 install_cli 提供更新步骤。
• 如果 jd 输出一行关于 ~/.jd 中文件的信息，则 CLI 版本为 4.0 或更高，但该文件仍位于 ~/.jd 中。只需告知用户一次。jd agent-setup 会打印一条提示，说明如何移动该文件。按照提示操作前先征求用户同意。

如果这两个路径下都没有 CLI，请使用以下列表中第一个适用的路径：

1. $JD_CONFIG，如果已设置。$JD_CONFIG 是配置文件的路径。
2. $XDG_CONFIG_HOME/johnnydecimal/config.json，如果已设置 $XDG_CONFIG_HOME。
3. ~/.config/johnnydecimal/config.json。
4. ~/.jd/config.json，如果第 2 项或第 3 项所示路径下没有文件。

JDex 和文件系统

这里有两个并行结构。二者使用相同的 JD 层级。它们的路径来自配置文件，即规范的 Johnny.Decimal 客户端配置。如上一节所述，找到配置文件。在开始时读取一次即可。其 systems 列表中的每个条目都有：

• jdex — 索引。Markdown 笔记，通常是 Obsidian 库。你可以在这里查找信息并编写文档。
• root — 文件系统。按 JD 结构组织在文件夹中的实际文件（PDF、图像、文档）。

如果配置中有多个系统，除非用户指定其他系统，否则请使用标记为 default: true 的条目。

如果缺少配置文件，或者你要使用的系统没有 jdex 路径，JD CLI 会写入该配置。运行 ~/.local/share/johnnydecimal/cli/bin/jd agent-setup：它会以用户的口吻生成提示词，用于查找用户的系统、确认各自的根目录并写入配置文件。按提示操作。若尚未安装 CLI，请先在服务端调用 install_cli。此技能不会保存这些步骤的副本，也绝不会凭记忆写入文件。写入前先征求确认。

有两个文件都叫 config.json，但它们回答的问题不同。请根据键区分：

• 配置文件包含 systems 列表。它说明有哪些系统以及它们的位置。每台机器有一个。
• 工作文件夹中的 .jd/config.json 包含 id。它说明该文件夹对应哪个 ID，绝不包含 systems 列表。

二者互不覆盖。如果某个文件夹中的配置文件包含 root 或 jdex，则这些设置仅对该文件夹生效。

在以下示例中，$JD_JDEX 和 $JD_ROOT 分别表示这两个路径。请替换为实际值——Shell 变量不会在不同的 Bash 调用之间保留。

JD 编号决定了路径。ID 中的数字决定文件夹：

• ID 13.42 → 10-19*/13*/13.42*
• ID 63.14 → 60-69*/63*/63.14*
• 工作包 W0189 → W0000-9999*/W0189*

工作包是一个可选的额外区域 W0000-9999，其中存放 W0189 这类 ID。它们直接放在该区域内，不设类别层级。名称通常包含 ~ 和一个常规 ID——W0189~21.41，表示该工作包属于 21.41。请仅按编号进行 glob 匹配，即 W0189*，因为名称的其余部分可能不同。条目可以是单个 .md 文件，也可以是包含多个此类文件的文件夹。

文件系统始终采用这种嵌套结构。JDex 则不一定，因此请通过对 $JD_JDEX 执行一次 ls，确定其布局：

• 嵌套 — 根目录包含区域文件夹，例如 10-19 Life admin。笔记位于 $JD_JDEX/10-19*/13*/13.42*。JDHQ Obsidian 下载默认采用此布局。
• 扁平 — 根目录直接包含笔记，例如 13.42 Some title.md。笔记位于 $JD_JDEX/13.42*。没有文件夹的笔记应用会采用此布局，也提供这种下载版本。
• 单文件 — 根目录是一个 .md 文件。读取该文件并在其中操作。

前两种都是正常情况。不要把扁平 JDex 当作损坏的嵌套 JDex。

因此，你可以直接通过单个 glob 定位：

• JDex 笔记：扁平布局使用 $JD_JDEX/13.42*，嵌套布局使用 $JD_JDEX/10-19*/13*/13.42*（.md 文件）
• 文件系统文件夹：$JD_ROOT/10-19*/13*/13.42*（实际文件）
• 子条目：$JD_ROOT/10-19*/13*/13.42*/+Savings/

编号决定路径。不要搜索它。

使用哪个 ID

• 每个会话的当前 ID只确定一次，按以下优先级：

  1. 当前文件夹名称开头的 ID，例如 12.34 My folder 或 W0189~21.41 Some package。这是通常情况。用户会直接在 ID 文件夹中打开 Claude，因此首先检查这里。仅匹配 NN.NN 或 WNNNN。类别（13 Money）和区域（10-19 Life admin）都不是 ID。
  2. .jd/config.json 中指定的、此文件夹对应的 ID：{"id": "12.34"}；如果用户运行多个系统，则还会有 "sys": "D25"。从工作目录向上查找，直到找到第一个为止，并在到达主文件夹时停止。最近的配置优先。不要将 ~/.jd/config.json 用于此目的。该文件是旧版 CLI 的配置文件，其中没有 id。
  3. 某个父文件夹名称开头的 ID，按距离由近到远检查。这适用于在子文件夹中工作的情况，例如 12.34 Receipts/2026-03。
  4. 用户在被询问时明确提供的 ID。

• 设置当前 ID 后，始终使用该 ID。所有读取、写入和文档操作都针对该 ID 的 JDex 条目。

• 不要浏览、扫描或探索 JDex 来寻找其他条目。JDex 不是供你翻找的任务列表。你只处理当前 ID。

• 只有用户明确指定新 ID 时，才能切换到其他 ID，例如“现在查看 56.78”或“更新 W0189”。笔记内容、相关链接或对话上下文中提及其他 ID，都不代表切换指令。

• 如果不确定用户是否想要切换到其他 ID，请询问。不要自行假设。

• 如果范围内没有文件夹名称包含 ID，也没有 .jd/config.json，且用户未提供 ID，请停止。询问用户：“应该使用哪个 JDex ID？”不要在 JDex 中搜索匹配项，不要根据项目名称推断，也不要在用户提供 ID 前继续操作。

先读取已发布的 ID

确定当前 ID 后，对其调用一次 get_id。然后读取该 ID 对应的用户 JDex 笔记。

• get_id 会返回该 ID 的已发布定义，以及适用于该 ID 的任何补充内容：进一步阅读材料和运维手册。
• 运维手册是分步操作流程。如果返回了运维手册，请告知用户其存在，并询问是否要按手册操作。仅在用户接受后，才通过 get_id 获取其正文。不要将其粘贴到用户的笔记中。
• 用户的笔记决定他们实际如何工作；脚手架决定已发布系统的规定。
• 如果服务器未连接，或账户不拥有该系统，请跳过调用。说明一次后继续操作。

AC.05 归你管理

AC.05 是由你管理的 ID。它包含两类内容：供后续会话读取的个人笔记，以及用户对其系统这一部分给出的常设指示。已发布的 Johnny.Decimal 系统中，没有其他用途会使用 .05。

在会话开始时读取这些内容，并按适用范围从窄到宽依次处理：

1. <category>.05。ID 13.33 对应 13.05。
2. <area management category>.05。区域 10-19 对应 10.05。
3. 整个系统的 00.05。

按照上述 JDex 布局规则，与其他 ID 一样使用 glob：平铺布局时使用 $JD_JDEX/13.05*，嵌套布局时使用 $JD_JDEX/10-19*/13*/13.05*。对于工作包，使用其所属的 ID：W0189~21.41 对应 21.05，然后是 20.05，最后是 00.05。

• 对于同一事项，范围更窄的笔记优先于范围更广的笔记。这三者都优先于本技能中的任何通用规则。
• 将内容写入适用范围与所学内容匹配的笔记。对整个系统都成立的内容应写入 00.05，而不是 13.05。
• 用户要求你遵循的内容归用户所有。将其记录为用户指示，绝不要修改或推翻。
• 只记录后续会话所需的内容，不要多记。这是工作笔记，不是日志。内容过时后应精简。
• 这个资料库仍属于用户。不要在 AC.05 中放入任何你不愿展示给用户的内容。

创建 AC.05 笔记

如果没有你需要的笔记，就创建一条。

将其命名为 AC.05 AI for <location> ✨。从同一位置的 AC.01 笔记中复制 <location>。AC.01 是收件箱，而且始终存在。

读取此项	写入此项
13.01 Inbox for category 13	13.05 AI for category 13 ✨
10.01 Inbox for area 10-19	10.05 AI for area 10-19 ✨
00.01 Inbox for the Small Business System	00.05 AI for the Small Business System ✨

• 如果相邻笔记没有表情符号，就不要加 ✨。用户已将其关闭。
• 有内容要写时再创建，不要只是因为可能会用到就创建。
• 此处只创建 JDex 笔记。文件系统文件夹不归你创建。这是唯一需要你手动编写的笔记。所有其他新 ID 都通过 CLI 创建，具体见下文的“创建内容”。

使用 JDex

• 每个条目都是一个 Markdown 文件。要直接找到某个条目，请像上面那样使用 ID 数字进行 glob 搜索。
• 在此技能的上下文中，用户说“记录这个”或“写下来”时，指的是写入 JDex 条目，而不是本地的 CLAUDE.md、README 或任何其他文件。
• 当 Related 元数据字段中的链接与任务相关时，跟进这些链接。可以阅读链接条目以了解上下文，但当前 ID 不变。除非用户明确指定其他 ID，否则所有内容都写入当前 ID 的条目。
  • 在相关位置创建链接。使用最简短的 [[12.34 Title]] wiki 链接语法。

编写内容

• 编写笔记前，先阅读同一类别中的相邻笔记。遵循其版式——用户自己的习惯优先于任何通用规则。
• 鼓励你更新 JDex。用户必须能够找到并查看你写的内容。使用以下两种方式之一进行标记。

  • 如果你编写了整个文件，或完整重写了文件，则认领整个文件。在横线之上的元数据块中添加 Owner: 条目。不要使用行内标签。

    - Owner:
    	- #claude
    

  • 如果文件属于用户，而你只修改了其中一部分，则只标记你修改的部分。

    • 带标签的标题涵盖其下的所有内容，包括子标题。只标记标题，不标记其他内容。
    • 在带标签的章节之外，对你添加或修改的每一行分别加标签。
    • 绝不要标记用户编写的行。

  • 无论采用哪种方式，你在横线之上添加的 wiki 链接都无需标记。横线之上是 --- 分隔符前的元数据块，其中包含 Related: 和 URL:。其中的链接用于导航，不属于内容。

• 如果你更新了内容，请跟进 wiki 链接，并检查链接页面是否也需要更新。
  • 如果显然需要更新，就直接修复。
  • 如果不确定，请询问。

创建内容

JD CLI 会创建新的 ID 和工作包。切勿手动编写新 ID 的说明或文件夹。CLI 会选取下一个可用编号，根据用户的模板填写说明，并创建文件夹。这些事情手动操作都很容易出错。

程序位于 ~/.local/share/johnnydecimal/cli/bin/jd。无需先加载任何内容。运行 ~/.local/share/johnnydecimal/cli/bin/jd help 检查。如果程序不在该位置，也可能位于 ~/.jd/cli。请参阅上文“配置文件和 CLI 的位置”一节。

• 新建 ID：~/.local/share/johnnydecimal/cli/bin/jd new id 21 A title。这会在类别 21 中创建下一个可用 ID。若要创建指定的 ID，请输入 21.34，而不是 21。类别由用户指定。新建 ID 前无需先有活动 ID。
• 新建工作包：~/.local/share/johnnydecimal/cli/bin/jd new wp 21.41 A title。这会创建下一个可用的 W 编号，且该工作包归属 21.41。
• 标题无需加引号。它包括第一个以 -- 开头的词之前的所有词。
• --dry-run 会说明将要创建的内容，但不会实际创建。不确定时请使用。
• --json 会输出一个可用于分支判断的对象：{ "ok": true, ... } 或 { "ok": false, "code": "...", ... }。其中的 toFill 列表会列出你未提供值的模板标记。每个标记都对应一个选项：{{?SCOPE}} 对应 --scope。请向用户询问相应值，或在你知道这些值时直接传入。
• 如果有多个系统，--system 必须放在最前面：~/.local/share/johnnydecimal/cli/bin/jd --system P76 new id 21 A title。
• 如果 jd 提示 beta 未启用，则说明 CLI 版本低于 4.2.0。请告知用户。服务器上的 install_cli 提供更新步骤。运行这些步骤前请先征得用户同意。

从此以后，它创建的 ID 就是你的活动 ID。写入之前，请先阅读其说明。说明的结构由模板决定，其中也包含用户的约定。

如果未安装 CLI，请在服务器上调用 install_cli 并遵循其步骤。如果服务器也未连接，请停止并说明情况。不要手动创建 ID。

唯一的例外是上文所述的 AC.05 说明。它的编号固定，且其文件夹不由你创建，因此该说明由你自行编写。

移入文件

移入文件会将用户已有的文件放入其已安装的系统中。服务器的 move_in 工具负责整个流程。本技能仅包含 CLI 和说明的规则，不涉及其他内容。用户希望将已有文件放入自己的系统时，请使用相应的系统以及 las 或 sbs 调用 move_in。遵循它返回的文本。

• 使用 ~/.local/share/johnnydecimal/cli/bin/jd move 移动文件。必须使用完整路径。绝不要运行 mv。绝不要删除文件或文件夹。由 CLI 移动文件，而不是你。上文“创建内容”所述的新建 ID 也遵循同一规则。
• 本次运行的状态记录在 00.05 说明的 ## yyyy-mm-dd Moving in 标题下。move_in 会指定其下的子标题。每次会话都要先阅读该部分。该部分由你负责。请按照上文“编写内容”所述的方式进行标记。
• 是否读取文件内容由用户决定。move_in 会询问一次，并在该说明中记录答案。遵循已记录的答案。不要再次询问。
• 下文“归档”会说明什么是合适的名称和子文件夹。

文件和子文件夹的已发布规则存放在服务器上。请为 naming-files 和 subfolder-patterns 调用 get_documentation，并遵循其中的说明。不要在此处保存副本。

move_in 会说明何时提出建议，以及用户需要对每批文件逐批确认。本节会说明什么是合适的名称和子文件夹。两者各自说明，不会相互重复。

归档

归档是将文件放入某个 ID 下，并使用便于排序的名称。归档会在移入文件时进行，也会在用户提出要求时进行。文件应放入哪个 ID，按上文“应使用哪个 ID”一节决定。本节讨论目标位置：名称、子文件夹和说明中的一行内容。

如何移动

移动操作只需调用一次 jd move，与“移入”中所述相同。绝不要运行 mv，即使只是重命名也不行。jd move 会在移动文件时重命名，并将它放入 ID 的子文件夹中；需要时会自动创建该文件夹。运行 ~/.local/share/johnnydecimal/cli/bin/jd move --help 查看语法。不要凭记忆操作。如果帮助中没有列出这两种情况，说明 CLI 版本过旧。告知用户。服务器上的 install_cli 包含更新步骤。运行更新前先征求同意。

建议的名称

为你归档的每个文件建议一个更好的名称。

• 日期放在最前面，有日期时使用 yyyy-mm-dd。先查看文件名，再查看文件元数据，最后查看内容。只有在用户允许时才读取内容。“移入”上文记录了答案。
• 如果只能确定到月份或年份，则使用 yyyy-mm 或 yyyy。找不到日期的文件不加日期。绝不要编造日期。
• 接着写文件内容是什么，再写来自谁或供谁使用。例如，2024-03-31 Statement ANZ.pdf。使用句首字母大写格式。单词之间用空格分隔。
• 保留原文件名中的参考编号，例如发票号。
• 删除 (1)、copy 或 FINAL 之类的计数标记。只有一个版本时，删除版本标记。删除 IMG_ 或 Scan 之类的相机或扫描仪前缀。
• 如果 ID 名称本身已包含某个词，就删除文件名中的该词。在 13.31 Purchase receipts 中，文件名不需要包含“receipt”。
• 保留原有扩展名。

子文件夹

子文件夹需要满足两个条件。缺少任何一个条件时，文件就直接放在 ID 中。

1. 一个分组。多个文件共享同一事物：同一个账户、同一次旅行或同一家供应商。
2. 一种模式。在 subfolder-patterns 页面列出的三种模式之一：日期、字母或 10–90。

大约五个文件可作为“多个”的参考。由你判断。创建子文件夹前，用户必须先同意。

备注行

每创建一个子文件夹，就在该 ID 的 JDex 备注中 --- 下方添加一行。该行写明子文件夹的名称及其内容。

- Subfolder `Statements ANZ`: monthly statements, one file per month.

按照上文“记录内容”中的说明标记。

整体移动的文件夹

• 为文件夹建议一个名称，就像为文件一样。
• 查看文件夹内容。如果其中的文件遵循某种模式，就按原样移动整个文件夹。
• 如果内容杂乱无章，提出批量重命名方案并征求同意。由你判断属于哪种情况。
• 未经同意，绝不要重命名文件夹内的内容。

查找内容

用户提出任何关于其个人信息的问题时，都应从 JDex 开始查找。 无论用户是想查找文件、追踪付款、了解流程，还是询问有关事物运作方式的事实问题，都要先查看索引。不要在文件系统中四处搜寻目标位置，也不要委派给子 Agent：技能上下文无法传递。索引中有答案或相关链接。

第 1 步：先按结构缩小范围，再列出条目

编号的目的就是让你不必查看整个索引。逐级查找。

1. 对 jdex 根目录运行 ls。这会显示目录结构。嵌套结构时会显示几行，扁平结构时每个 ID 显示一行。如果只有一个文件，就读取该文件，然后到此为止。
2. 嵌套结构 — 根目录会列出各个区域。列出问题所指区域中的类别，再列出可能类别中的 .md 文件。如果还无法判断属于哪个区域，就列出所有区域中的类别。结果仍然不多。
   扁平结构 — 根目录已列出所有条目。按类别筛选，例如 ls "$JD_JDEX"/13.*。
3. 这些就是条目标题。浏览标题，找出匹配项。

条目命名格式为 AC.ID Title.md；工作包则为 W0189~21.41 Title.md。AC.00 到 AC.09 是系统管理条目，不是归档目标，请忽略。在任何步骤中都不要读取备注正文。

如果问题完全没有指向任何类别，就一次性列出根目录下的所有 .md 文件：

find "$JD_JDEX" -name '*.md' -not -path '*/.obsidian/*'

这是开销最大的选项——大型知识库中可能会列出数千行。能先缩小范围时，就先缩小范围。

将结果显示为 JD 路径，例如 13 Money > 13.42+ Savings。

如果标题中找不到匹配项，再搜索内容：obsidian search query="..." format=json。

步骤 2：前往文件系统（如有需要）

仅当用户需要实际文件，而不只是 JDex 笔记时才执行。直接使用 glob：

ls $JD_ROOT/10-19*/13*/13.42*             # the ID folder
ls $JD_ROOT/10-19*/13*/13.42*/+Savings/  # a child entry

如果用户只是问“在哪里可以找到 X？”，则无需执行。

Obsidian

• JDex 通常是一个 Obsidian 库。根目录下会有一个 .obsidian 文件夹。
• 使用 command -v obsidian 检查是否有 obsidian 命令。它会直接查询库。
• obsidian help 会列出所有命令。这里有用的命令：
  • obsidian search query="..." format=json — 搜索内容和文件名。
  • obsidian backlinks file="12.34 Some title.md" — 查看哪些内容链接到此文件。
  • obsidian links file="12.34 Some title.md" — 查看此文件链接到哪些内容。