ws-update

Wiki 更新

从当前来源——项目、对话或研究环节——中提取可长期保留的知识，并将其放入用户的 wiki。创建之前先合并，遵循 wiki 的约定，并确保每个文件都不超过大小上限。

Wiki 模型

wiki 是一个文件夹，其 index.md 中包含 ## Spaces 标题。## Spaces 是导航契约：其中必须列出每个直接包含的空间，格式为 - [label](path/index.md) — description，工具只会遍历其中列出的空间。空间可以递归嵌套；每个空间本身都是下一层的 wiki。普通文件夹（没有 index.md）只用于归类文件。Markdown 方言为 Obsidian——包括 wikilinks、frontmatter、callouts 和 embeds；配套的 obsidian-markdown 和 obsidian-bases 技能涵盖相关语法。

确定 wiki 路径

解析顺序：用户明确指定的路径 → 最近的 CWD 祖先文件夹，只要它是 wiki，或包含作为 wiki 的 .wiki-spaces/ 文件夹（即该文件夹自己的空间）→ ~/.config/wiki-spaces/config 中的 wiki 键。用户的表述优先于这些规则：“我的 wiki”指配置的 wiki，即使 CWD 位于另一个 wiki 中（例如公司仓库）。如果 CWD 所在的 wiki 与另一个已配置的 wiki 同时存在，请说明解析出的根目录；意图不明确时，只询问一次。绝不要默默操作错误的 wiki。

附带脚本

scripts/ws.py 位于此 SKILL.md 旁边——使用标准库的 python3（3.9+），无依赖，只读。它解析契约，而不解析内容：结构——遍历、范围、大小上限、偏差——由脚本处理；阅读内容并判断含义由你处理。使用绝对路径调用它（你的工作目录通常在别处）：

• python3 <skill-dir>/scripts/ws.py list --wiki <root> — 列出通过 ## Spaces 契约可访问的空间及其入口描述（使用 --external 可跨越挂载点）。
• … files --wiki <root> — 列出通过契约可访问的 Markdown 文件。
• … grep <pattern> [-i] [-F] --wiki <root> — 在这些文件中按行进行正则搜索；-F 表示按字面字符串搜索（名称中带有元字符时可精确匹配）；输出 rel:line: text，无匹配时退出码为 1。扫描的基本操作：链接工作清单、标签清单、转义引用检查，都可以通过一个搜索模式加上你对命中结果的判断来完成。
• … check-size <target> [--stdin] --wiki <root> — 检查文件是否符合大小上限；写入前可通过管道传入计划内容并使用 --stdin 进行检查。
• … audit --wiki <root> — 检查契约偏差、越过空间边界的条目、超限或无法读取的文件，以及状态异常的挂载点。对于可以明确指出修复方式的问题，结果会说明修复方法（例如，missing entry 会打印需要添加的确切行）；将修复作为常规编辑应用，然后重新运行审计进行验证——脚本不会写入任何内容。

相信脚本的输出，不要手动重新推导结构。标准输出是数据；标准错误会提供解析出的根目录（audit 则在标准输出的开头打印根目录），以及说明遍历跳过内容的 note: 提示、根目录嵌套于其他 wiki 时的外层 wiki，以及根目录属于另一 wiki 时的已配置 wiki——当这些信息可能影响答案时，请转达给用户。

信任范围与大小限制

自有与外部的判定相对于解析后的根目录：任何位于名为 shared/ 的文件夹（任意深度）下的内容、Git 子模块，或指向其中任一位置的符号链接，都属于外部；指向树外文件夹的符号链接则按其所在位置处理，与克隆目录相同。默认情况下，读取会跨越自有空间，只有用户明确要求时才会进入外部空间。写入仅限目标空间；任何其他空间（无论自有还是外部）只有在明确指示时才会写入。

上限按包含 frontmatter 在内的 UTF-8 字节数计算，并按基本文件名确定：index.md 为 5000，log.md 和 hot.md 为 100000，其他任何 *.md 文件为 15000。

• 上限由用户决定：需要不同上限的 wiki 可在 _meta/limits.md 中设置，check-size 会读取这些设置。
• 每次写入（新建页面或编辑）之前，都要使用 check-size 检查上限：通过 --stdin 传入计划写入的内容；缩小超限文件的写入会报告 ok 和进度，从而逐步修复；检查磁盘上的文件时则只依据上限判断。
• 超限说明的是内容结构问题，不只是大小问题：提炼页面内容、调整空间结构，或将已发展为独立空间的页面提升为一个空间——绝不截断内容，也绝不提高上限。
• log.md 是例外：超限的日志会滚动归档——将整个文件移至 _archives/log-<YYYYMMDD>.md，并新建一个空文件——这样历史记录会归档，而不会被缩减。

各项约定均为 wiki 可选。读取空间根目录（用户指定的空间，否则为解析后的根目录）中存在的标记——log.md、_meta/taxonomy.md、_meta/limits.md、_meta/ignore.md、页面 frontmatter、_template.md、hot.md、.git——缺少任何一项时都应妥善处理。如果存在 log.md，则每次操作追加一行：

printf '%s %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '<OP> <details>' >> <scope-root>/log.md

初始化

如果无法解析出任何内容——没有显式路径、当前工作目录的祖先目录中没有 wiki，也没有有效配置——则直接在当前上下文中设置一个：按照 references/init.md 操作，然后继续处理请求。配置的路径无效（磁盘上不存在、没有 index.md，或不是绝对路径）时必须停止，不能因此触发设置流程——应告知用户并由用户决定。文件夹自己的空间——用户提出要求（“为此项目设置一个 wiki”），或同步目标文件夹没有 wiki 时提供一次设置选项——均按照 references/own-space.md 操作，无论是否已解析出 wiki。

流程

1. 解析 wiki（核心模块），如果根目录来自 CWD 或可能存在歧义，则说明根目录。

2. 检测范围根目录中的约定（核心模块）。存在性标记（log.md、分类体系、hot.md）不会从父级继承；_meta/limits.md、_meta/ignore.md 和 _template.md 遵循最近祖先规则。跳过所有缺少标记的步骤。

3. 根据用户意图检测模式——CWD 只用于消除项目选择歧义，绝不用于判断模式：

   模式	触发条件	输入
   直接添加	“将此添加到 wiki”“保存这份配方”——手头有具体内容	提供的内容
   项目同步	“同步这个项目”、明确指定项目名称	项目文件、git 日志
   对话记录	“保存这个”“记录这个”——记录会话本身，没有单一内容	当前对话
   研究记录	“保存这项研究”	会话中的发现

4. 提取知识。 直接添加：照原样采用提供的内容——你的任务是确定位置并去重，而不是重新综合。项目同步：从文件和近期 git 历史中提取决策及其理由、模式、工具/API 接线方式、权衡和结果。对话：记录持久结论和决策，写成事实（“X 的工作方式是……”），绝不写聊天摘要。研究：记录耗费精力且日后重新推导代价高昂的内容。

5. 筛选并去重。 知识采集型 wiki 使用噪声过滤规则：能从代码或快速搜索中找到答案？跳过；3 个月后还会需要？保留。内容存储型 wiki（配方、日志、运行手册）跳过筛选——每条内容都是有意收录的。通过 files 列出现有页面，并按文件名/路径/前置元数据的重合度排序：存在近似匹配时，合并到该页面，不要创建同级页面。

6. 确定位置。 list 会打印每个空间及其条目描述——这些是位置提示；也要检查顶层普通文件夹。按语义匹配：关于某个来源的知识应放在该来源所属的空间中（如果存在），即它自己的 .wiki-spaces/ 或 wiki 中对应的空间；可在该来源之外复用的知识应放在对应主题下。如果当前位于某个文件夹自己的空间中，该主题的主页位于脚本注明的配置 wiki 中——这是第二个根目录：说明页面名称及其在该处的位置；用户同意后，在写入前对该根目录执行步骤 2 和 5。有多个同样合理的候选位置，或没有候选位置 → 询问。扁平 wiki → 写入根目录。文件名遵循 wiki 自身的模式——匹配现有页面的做法；没有既定模式时，默认使用小写、连字符分隔且不超过 50 个字符的名称。

7. 每次写入前检查上限。 写入前将计划内容通过管道传入：

   python3 <skill-dir>/scripts/ws.py check-size <target> --stdin --wiki <root> <<'EOF'
   <planned content>
   EOF
   

   编辑也要以同样方式将计划内容通过管道传入（缩减超限页面后会报告 ok）；审计会兜底检查遗漏项。若结果为 over——绝不截断、忽略或提高上限。重新读取页面及其空间的索引，诊断超限原因，然后采取相应措施：

   • 臃肿——填充内容、近似重复项、原样粘贴的散文、如今你不会重新创建的条目 → 精炼：合并、压缩、删除。上限的目的就是促使你作出这一判断。
   • 增长——真正不同的主题挤在同一文件中 → 按照针对当前内容重新设计空间时应有的结构重整空间：在中心页下创建可独立使用的同级页面、提升页面层级，或重新分组布局（空间操作链接了这两种流程）。 两种情况都适用时，先精炼，再重整剩余内容。更新你改动过的所有索引。像 topic-2.md 或 topic-more.md 这样的文件名，意味着拆分文件时没有重新考虑空间结构——绝不能提交这样的结果。 超限的 index.md 表示导航负担：将详细内容移至子页面，每个条目占一行。

8. 写入。 新页面：如果存在最近祖先 _template.md，则使用它；否则遵循 wiki 的页面格式（仅当 wiki 已使用前置元数据时才添加前置元数据）。对非来源支持的说法标记 %%inferred%%，对相互冲突的来源标记 %%ambiguous%%。在首次自然提及时添加最多 2 个 wiki 链接。更新页面时：合并内容、保留手动添加的内容；如果使用前置元数据，则更新 updated:；绝不覆盖无关章节。项目同步时，在项目中心页记录仓库路径（将 ~ 收缩形式用于路径）——如果有使用 repo:/sources: 前置元数据字段则写入其中，否则添加一行普通文本——以便后续会话能将工作区对应到该页面。变更超过约 10 个页面 → 先展示计划并征求同意。

9. 遵守约定。 新建了空间、移除了空间或移动了页面？按照下文空间操作更新 ## Spaces。## Items 章节是可选的人工整理内容——如果索引中已有，则予以维护。然后检查最终结构：条目描述仍然准确，不存在仅在历史背景下才有意义的名称——小修立即处理；较大规模的重整则作为收尾时 ws-tend 的建议。

10. 收尾。 运行 audit。自行应用安全的结构修复，每轮修复后重新审计，直到问题全部消除：

    • 添加 missing entry 发现所打印的确切条目行，并在末尾加上 — description——这是后续每项操作都会读取的放置提示。
    • 仅在发现提示要求插入的位置，添加已注册的裸子级所缺少的 ## Spaces 标题；如果提示指出的是近似匹配，则要求重命名，这会继续作为作者意图报告。
    • 移除审计指出越过其他空间边界的条目——更深层的列表归该空间所有；如果该条目缺失，则在该空间中注册。

    未声明的裸索引属于晋升决策——将其列出，仅按用户要求操作。其他发现只需报告，不要自动修复；若超出本次同步的写入范围，建议执行 ws-tend 检查——仅作建议，绝不要自行运行。按照核心块记录每项操作的一行 UPDATE，并在一个代码块中确认：Updated wiki (<root>)，包含创建的路径、更新的路径、模式和审计结果。

空间操作

创建空间（需要一级导航的文件夹）：

mkdir -p <root>/<path> && printf '# <Title>\n\n## Spaces\n' > <root>/<path>/index.md

在最近的祖先空间的 ## Spaces 中注册该空间——- [<name>/](<name>/index.md) — description，名称需要时对 href 进行百分号编码；该描述是后续操作会读取的放置提示。如有疑问，审计中的 missing entry 发现会打印确切的行。

移除页面：先检查有哪些内容指向该页面——grep -F '<stem>' --wiki <root>（所有链接形式都包含该 stem；代码示例除外，请逐一判断每处命中）——重写或删除实际链接，优先移至 _archives/，而非删除，然后运行 audit。

移除空间：先与用户确认（优先移至 _archives/，而非删除），删除文件夹，从父级的 ## Spaces 中移除其条目，然后运行 audit，确认没有悬空引用。

挂载他人的空间：references/mount.md。分享自己的空间：references/share.md。

将页面提升为空间——页面结构需要时即可按常规流程处理；清点链接、创建快照、移动、重写并验证：references/promote.md。重命名、移动、合并或降级空间，遵循相同流程：references/restructure.md。