ws-update

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Wiki Update

Wiki 更新

Extract durable knowledge from the current source — a project, the conversation, a research session — and place it in the user's wiki. Merge before creating, respect the wiki's conventions, and keep every file inside its size cap.

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

The wiki model

Wiki 模型

A wiki is a folder whose

index.md

carries a

## Spaces

heading.

## Spaces

is the navigation contract: every space directly inside is listed there as

- [label](path/index.md) — description

, and tools traverse only what it lists. Spaces nest recursively; each space is itself a wiki one level down. Plain folders (no

index.md

) just group files. The markdown dialect is Obsidian — wikilinks, frontmatter, callouts, embeds; the companion

obsidian-markdown

and

obsidian-bases

skills cover the syntax.

Wiki 是一个文件夹，其

index.md

中带有

## Spaces

标题。

## Spaces

是导航契约：每个直接位于其中的 space 都要在该处列为

- [label](path/index.md) — description

，工具也只遍历其中列出的内容。Space 可以递归嵌套；每个 space 本身都是下一层级的 Wiki。普通文件夹（没有

index.md

）只用于归组文件。Markdown 方言为 Obsidian——支持 wikilinks、frontmatter、callouts 和 embeds；配套的

obsidian-markdown

和

obsidian-bases

skills 会介绍这些语法。

Resolving the wiki

解析 Wiki

Resolution order: an explicit path from the user → the nearest CWD-ancestor folder that is a wiki, or carries a

.wiki-spaces/

folder that is one (a folder's own space) → the

wiki

key in

~/.config/wiki-spaces/config

. The user's words override the mechanics: "my wiki" means the configured one even when CWD sits inside another wiki (a company repo, say). When a CWD wiki and a different configured wiki both exist, announce which root you resolved; ask once if intent is ambiguous. Never silently operate on the wrong wiki.

解析顺序：用户提供的显式路径 → 最近的 CWD 祖先文件夹，且该文件夹本身是 Wiki，或包含一个作为该文件夹自身 space 的

.wiki-spaces/

文件夹 →

~/.config/wiki-spaces/config

中的

wiki

键。用户的措辞优先于上述机制：即使用户位于另一个 Wiki（例如公司 repo）中，“my wiki”仍然表示已配置的 Wiki。当 CWD Wiki 与另一个已配置的 Wiki 同时存在时，应声明解析到的根目录；如果意图不明确，只询问一次。绝不能默默操作错误的 Wiki。

The bundled script

内置 script

scripts/ws.py

sits next to this SKILL.md — stdlib python3 (3.9+), zero dependencies, read-only. It parses the contract, never the content: structure — traversal, scope, caps, drift — is the script's side; reading and judging meaning is yours. Invoke it by absolute path (your working directory is usually elsewhere):

```
python3 <skill-dir>/scripts/ws.py list --wiki <root>
```
— spaces reachable via the
```
## Spaces
```
contract, each with its entry description (
```
--external
```
to cross mounts).
```
… files --wiki <root>
```
— markdown files reachable via the contract.
```
… grep <pattern> [-i] [-F] --wiki <root>
```
— regex line search over those files,
```
-F
```
for a literal string (a name carrying metacharacters sweeps exact); prints
```
rel:line: text
```
, exits 1 on no match. The sweep primitive: a link worklist, a tag inventory, an escaping-reference check are each a pattern plus your judgment on the hits.
```
… check-size <target> [--stdin] --wiki <root>
```
— cap verdict for a file; pipe planned content with
```
--stdin
```
to check before writing.
```
… audit --wiki <root>
```
— contract drift, entries crossing a space boundary, over-cap or unreadable files, unhealthy mounts. Findings name their repair where one is safe to name (a
```
missing entry
```
prints the exact line to add); apply repairs as ordinary edits and re-run the audit to verify — the script never writes.

Trust the script's output over re-deriving structure by hand. Stdout is data; stderr carries the resolved root (

audit

prints it as its stdout header instead) and

note:

advisories naming whatever a walk skipped, the enclosing wiki when the root is nested inside one, and the configured wiki when the root is another — relay them when they could change the answer.

scripts/ws.py

位于本 SKILL.md 旁边——使用 stdlib python3（3.9+），零依赖，只读。它只解析契约，绝不解析内容：结构——遍历、作用域、大小上限和漂移——由 script 负责；阅读内容并判断其含义则由你负责。必须使用绝对路径调用它（你的工作目录通常在其他位置）：

```
python3 <skill-dir>/scripts/ws.py list --wiki <root>
```
——列出通过
```
## Spaces
```
契约可达的 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>
```
——检查契约漂移、跨越 space 边界的条目、超限或无法读取的文件，以及不健康的挂载点。发现项会在能够安全指出修复方式时说明修复方法（例如
```
missing entry
```
会打印需要添加的准确行）；将修复作为普通编辑应用，然后重新运行 audit 进行验证——script 绝不写入内容。

应信任 script 的输出，而不是手动重新推导结构。Stdout 是数据；stderr 携带解析后的根目录（audit 则将其作为 stdout 标头打印），以及

note:

提示，说明 walk 跳过了什么、嵌套在另一个 Wiki 内时的外层 Wiki，以及根目录为另一个 Wiki 时的已配置 Wiki；在这些信息可能改变答案时应转达。

Trust scope and size discipline

信任范围与大小约束

Owned vs external is relative to the resolved root: anything under a folder named

shared/

(at any depth), a git submodule, or a symlink into either is external; a symlink to a folder outside the tree answers to where it sits, like a clone. Reads cross owned spaces by default and enter external ones only when the user explicitly asks. Writes stay inside the targeted space; any other space — owned or external — is written only on explicit instruction.

Caps are UTF-8 bytes including frontmatter, keyed by basename:

index.md

5000,

log.md

and

hot.md

100000, any other

*.md

15000.

Caps belong to the user: a wiki that wants different ones sets them in
```
_meta/limits.md
```
, and
```
check-size
```
reads them.
Check caps with
```
check-size
```
: pipe the planned content via
```
--stdin
```
before every write, new page or edit — a write that shrinks an over-cap file reports
```
ok
```
, progress, so repairs converge; a file checked on disk answers to the cap alone.
An overflow is a signal about shape, not just size: distill the page, reshape the space, or promote a page that has grown into one — never truncate, never raise the cap.
The exception is
```
log.md
```
: an over-cap log rolls — move it whole to
```
_archives/log-<YYYYMMDD>.md
```
and start a fresh one — so the history archives, never shrinks.

Conventions are opt-in per wiki. Read the markers present at the scope root (the space the user targeted, else the resolved root) —

log.md

_meta/taxonomy.md

_meta/limits.md

_meta/ignore.md

, frontmatter on pages,

_template.md

hot.md

.git

— and degrade gracefully when one is absent. If

log.md

exists, append one line per operation:

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

所有权与外部性相对于解析后的根目录判断：位于名为

shared/

的文件夹下（任意深度）、属于 git submodule，或是指向这两类位置的 symlink，均属于外部；指向树外文件夹的 symlink 归属其实际所在位置，就像 clone 一样。默认情况下可以跨自有 spaces 读取；只有用户明确要求时才能进入外部 spaces。写入仅限目标 space；无论其他 space 是自有还是外部，只有得到明确指示才可写入。

大小上限按 UTF-8 bytes 计算并包含 frontmatter，以 basename 区分：

index.md

为 5000，

log.md

和

hot.md

为 100000，其他所有

*.md

为 15000。

这些上限属于用户；如果 Wiki 需要不同的上限，应在
```
_meta/limits.md
```
中设置，
```
check-size
```
会读取这些值。
使用
```
check-size
```
检查上限：每次写入——无论是新页面还是编辑——之前，都应通过
```
--stdin
```
传入计划写入的内容；如果某次写入使一个原本超限的文件缩小，则会报告
```
ok
```
和进展，使修复逐步收敛；对于磁盘上的文件，检查结果只取决于上限。
溢出来源是内容形态的信号，而不只是大小问题：提炼页面、重新组织 space，或将已经成长为大主题的页面提升为独立页面——绝不截断，绝不提高上限。
```
log.md
```
是例外：日志超限时需要滚动——将整个旧文件移至
```
_archives/log-<YYYYMMDD>.md
```
，然后创建一个新的日志——这样历史记录会被归档，而不会缩减。

约定按 Wiki 选择启用。读取 scope 根目录（用户目标 space 的根目录，否则为解析后的根目录）中存在的标记——

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

Initialization

初始化

When nothing resolves — no explicit path, no CWD-ancestor wiki, no valid config — set one up inline: follow references/init.md, then resume the request. A broken configured path (missing on disk, no

index.md

, not absolute) is a hard stop, not a setup trigger — surface it and let the user decide. A folder's own space — asked for ("set up a wiki for this project"), or offered once when a sync targets a folder that has none — follows references/own-space.md, whether or not a wiki already resolves.

当完全没有解析到目标时——没有显式路径、没有 CWD 祖先 Wiki，也没有有效配置——就地建立一个：遵循 references/init.md，然后继续执行请求。已配置路径损坏（磁盘上不存在、没有

index.md

、不是绝对路径）属于硬性停止条件，而不是触发初始化的理由；应报告问题，让用户决定。文件夹自身的 space——无论是用户明确要求（“set up a wiki for this project”），还是在同步目标文件夹没有 space 时提供一次——都应遵循 references/own-space.md，无论当前是否已解析到一个 Wiki。

Procedure

操作流程

Resolve the wiki (core block) and announce the root when it came from CWD or could be ambiguous.
Detect conventions at the scope root (core block). Presence markers (
```
log.md
```
, taxonomy,
```
hot.md
```
) never inherit from a parent;
```
_meta/limits.md
```
,
```
_meta/ignore.md
```
, and
```
_template.md
```
follow their nearest-ancestor rule. Skip every step whose marker is absent.

Detect the mode from the user's intent — CWD only disambiguates which project, never the mode:

Mode	Trigger	Input
Direct add	"add this to the wiki", "save this recipe" — a concrete artifact in hand	the handed content
Project sync	"sync this project", explicit project naming	project files, git log
Conversation capture	"save this", "capture this" — the session itself, no single artifact	the current conversation
Research capture	"store this research"	findings from the session

Extract knowledge. Direct add: take the content as handed — your job is placement and dedup, not re-synthesis. Project sync: decisions and rationale, patterns, tool/API wiring, trade-offs, results — from the files and recent git history. Conversation: durable conclusions and decisions, written as facts ("X works by…"), never chat summary. Research: what took effort and would be expensive to re-derive.
Filter and deduplicate. Knowledge-capture wikis get the noise filter: answerable from the code or a quick search? skip; needed in 3 months? keep. Content-store wikis (recipes, journals, runbooks) skip the filter — every entry is intentional. Enumerate existing pages via
```
files
```
and rank by filename/path/frontmatter overlap: when a near-match exists, merge into it instead of creating a sibling.
Place.
```
list
```
prints each space with its entry description — the placement hints; check top-level plain folders too. Match semantically: knowledge about a source belongs with that source's space when one exists — its own
```
.wiki-spaces/
```
, or its space in the wiki; knowledge reusable beyond it belongs with its topic. Standing in a folder's own space, that topic's home is the configured wiki the script notes — a second root: name the page and its place there, and on a yes take that root through steps 2 and 5 before writing. Several equally plausible candidates, or none → ask. Flat wiki → write at the root. Names follow the wiki's own pattern — match what existing pages do; where no pattern exists, default to lowercase, hyphenated, ≤50 chars.
Check the cap on every write. Pipe planned content before writing:
sh
```
python3 <skill-dir>/scripts/ws.py check-size <target> --stdin --wiki <root> <<'EOF'
<planned content>
EOF
```
An edit pipes its planned content the same way (a shrink of an over-cap page reports
```
ok
```
); the audit backstops what slips through. On
```
over
```
— never truncate, never ignore, never raise the cap. Re-read the page and its space's index, diagnose why it overflowed, then act:
- Bloat — padding, near-duplicates, prose pasted in raw, entries you wouldn't re-create today → distill: merge, tighten, drop. The cap exists to force this judgment.
- Growth — genuinely distinct topics sharing one file → reshape the space to what it would look like had it been designed for today's content: self-standing sibling pages under a hub, a promotion, or a regrouped layout (Space operations links both procedures). Both can apply — distill first, then reshape what remains. Update every index you touch. Filenames like
```
topic-2.md
```
  or
```
topic-more.md
```
  mean a file was split without rethinking the space — never ship them. An over-cap
```
index.md
```
  is navigation debt: push detail into child pages, one line per entry.
Write. New pages: nearest ancestor
```
_template.md
```
if present, else the wiki's page shape (frontmatter only where the wiki already uses it). Mark non-source claims
```
%%inferred%%
```
, conflicting sources
```
%%ambiguous%%
```
. Add up to 2 wikilinks on first natural mentions. Updates: merge, preserve manual content, bump
```
updated:
```
if frontmatter is in use, never overwrite unrelated sections. On a project sync, record the repo path (
```
~
```
-contracted) on the project's hub page —
```
repo:
```
/
```
sources:
```
frontmatter where in use, else one plain line — so a later session maps the checkout to its page. More than ~10 pages changing → show the plan and ask first.
Keep the contract. Created a new space, removed one, or moved pages? Update
```
## Spaces
```
per Space operations below.
```
## Items
```
sections are optional human curation — maintain one where the index already has it. Then check the shape you're leaving: entry descriptions still true, no name that only makes sense historically — small fixes now; bigger reshapes become the close-out's
```
ws-tend
```
suggestion.
Close out. Run
```
audit
```
. Apply the safe structural repairs yourself, re-auditing between rounds until gone:

- Add the exact entry line a
```
missing entry
```
  finding prints, then trail it with a
```
— description
```
  — the placement hint every later operation reads.
- Insert the
```
## Spaces
```
  heading a registered bare child lacks — only where the finding's hint asks for the insert; a near-miss hint asks for a rename, which stays reported as author intent.
- Remove an entry the audit says crosses another space's boundary — that space owns the deeper listing; register it there instead when it is missing.

An undeclared bare index is a promotion decision — surface it, act only on the user's call. Other findings are reported, not auto-repaired; outside this sync's write scope, suggest a
```
ws-tend
```
pass — suggestion only, never run it yourself. Log an
```
UPDATE
```
line per the core block and confirm in one block:
```
Updated wiki (<root>)
```
with created paths, updated paths, mode, and audit outcome.

解析 Wiki（核心块），当根目录来自 CWD 或可能存在歧义时，声明该根目录。
检测 scope 根目录的约定（核心块）。存在性标记（
```
log.md
```
、taxonomy、
```
hot.md
```
）绝不从父级继承；
```
_meta/limits.md
```
、
```
_meta/ignore.md
```
和
```
_template.md
```
遵循最近的祖先规则。缺少相应标记时，跳过每一步。

根据用户意图检测模式——CWD 只用于消除哪个项目的歧义，绝不决定模式：

模式	触发条件	输入
直接添加（Direct add）	“add this to the wiki”、“save this recipe”——手中已有具体内容	交给你的内容
项目同步（Project sync）	“sync this project”、明确指定项目名称	项目文件、git log
对话捕获（Conversation capture）	“save this”、“capture this”——会话本身，没有单一内容	当前对话
研究捕获（Research capture）	“store this research”	会话中的发现

提取知识。 直接添加：按交付的内容原样采用——你的职责是放置和去重，而不是重新综合。项目同步：从文件和最近的 git 历史中提取决策及理由、模式、工具/API 接线、权衡和结果。对话：把长期结论和决策写成事实（“X 的工作方式是……”），而不是聊天摘要。研究：提取那些耗费精力、若重新推导则成本高昂的信息。
过滤并去重。 知识捕获型 Wiki 使用噪声过滤器：能否从代码或快速搜索中得到答案？是则跳过；三个月后仍会需要吗？会则保留。内容存储型 Wiki（食谱、日志、runbook）不使用该过滤器——每个条目都是有意添加的。通过
```
files
```
枚举现有页面，并按文件名、路径或 frontmatter 的重合程度排序：存在近似匹配时，合并到该页面，而不是创建同级页面。
放置。
```
list
```
会打印每个 space 及其条目描述——这些描述就是放置提示；也要检查顶层普通文件夹。按语义匹配：关于某个来源的知识，如果该来源拥有 space（自己的
```
.wiki-spaces/
```
，或 Wiki 中对应的 space），就应放在该 space；可跨来源复用的知识则放在其主题 space。当位于某个文件夹自身的 space 中时，该主题的归属地是 script 提示的已配置 Wiki——这是第二个根目录：先命名页面并确定其位置，得到用户肯定后，在写入前对该根目录执行步骤 2 和步骤 5。若有多个同样合理的候选，或没有候选，则询问。扁平 Wiki → 写在根目录。名称遵循 Wiki 自身的模式——与现有页面保持一致；若不存在模式，默认使用小写、连字符分隔且不超过 50 个字符的名称。
每次写入都检查大小上限。 写入前传入计划内容：
sh
```
python3 <skill-dir>/scripts/ws.py check-size <target> --stdin --wiki <root> <<'EOF'
<planned content>
EOF
```
编辑同样传入计划内容（缩写过限页面时会报告
```
ok
```
）；audit 可作为兜底，检查遗漏的问题。出现
```
over
```
时——绝不截断、绝不忽略、绝不提高上限。重新读取页面及其 space 的 index，诊断溢出原因，然后采取行动：
- 膨胀——填充内容、近似重复、原文直接粘贴的冗长段落，以及今天不会重新创建的条目 → 提炼：合并、压缩、删除。大小上限的存在正是为了促成这种判断。
- 增长——真正不同的主题共用一个文件 → 按照今天的内容本应被设计出的样子重新组织 space：在 hub 下建立可独立成篇的同级页面、进行提升，或重新分组布局（空间操作包含这两种流程）。两者可能同时适用——先提炼，再重新组织剩余内容。更新所有涉及的 index。类似
```
topic-2.md
```
  或
```
topic-more.md
```
  的文件名说明文件被拆分时没有重新思考 space——绝不能交付这种结果。超限的
```
index.md
```
  属于导航债务：把细节下放到子页面，每个条目只保留一行。
写入。 新页面：使用最近祖先的
```
_template.md
```
（如果存在），否则遵循 Wiki 的页面形态（仅在 Wiki 已使用 frontmatter 时才添加 frontmatter）。用
```
%%inferred%%
```
标记非来源声明，用
```
%%ambiguous%%
```
标记相互冲突的来源。首次自然提及某主题时，最多添加 2 个 wikilink。更新：进行合并，保留人工编写的内容；如果正在使用 frontmatter，则更新
```
updated:
```
；绝不覆盖无关章节。项目同步时，在项目的 hub 页面记录 repo 路径（使用
```
~
```
收缩形式）——在已使用 frontmatter 时写入
```
repo:
```
/
```
sources:
```
，否则写成一整行——以便后续会话能把该 checkout 映射到对应页面。变更超过约 10 个页面 → 先展示计划并询问。
维护契约。 新建、删除或移动了 space？按下方空间操作更新
```
## Spaces
```
。
```
## Items
```
区块是可选的人工整理——如果 index 中已有，则应维护。然后检查最终留下的结构：条目描述仍然准确，没有只在历史上才说得通的名字——现在修复小问题；更大的重组则作为收尾阶段的
```
ws-tend
```
建议。
收尾。 运行
```
audit
```
。自行应用安全的结构修复，并在每一轮修复后重新运行 audit，直到问题消失：

- 添加
```
missing entry
```
  发现所打印的准确条目行，然后追加
```
— description
```
  ——这是后续每次操作都会读取的放置提示。
- 为已注册但缺少标题的裸子目录插入
```
## Spaces
```
  标题——仅当发现的提示明确要求插入时；近似匹配提示要求重命名，而重命名属于作者意图，因此继续报告。
- 删除 audit 判定跨越另一个 space 边界的条目——该 space 拥有更深层的列表；若该条目尚未注册，则改为在那里注册。

未声明的裸 index 属于页面提升决策——应告知用户，仅根据用户的决定执行。其他发现只报告，不自动修复；对于超出本次同步写入范围的问题，建议执行
```
ws-tend
```
pass——仅提出建议，绝不自行运行。按照核心块记录一行
```
UPDATE
```
，并用一个区块确认：
```
Updated wiki (<root>)
```
，其中包含已创建路径、已更新路径、模式和 audit 结果。

Space operations

空间操作

Create a space (a folder needing first-class navigation):

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

## Spaces

—

- [<name>/](<name>/index.md) — description

, href percent-encoded where the name demands it; the description is the placement hint later operations read. The audit's

missing entry

finding prints the exact line if in doubt.

Remove a page: sweep for what points at it first —

grep -F '<stem>' --wiki <root>

(every link form carries the stem; judge each hit, code examples aside) — rewrite or drop the real links, prefer a move to

_archives/

over deletion, then

audit

Remove a space: confirm with the user (prefer

_archives/

over deletion), delete the folder, remove its entry from the parent's

## Spaces

, then

audit

to verify nothing dangles.

Mount someone else's space: references/mount.md. Share a space of yours: references/share.md.

Promote a page into a space — routine once a page's shape asks for it; inventory its links, snapshot, move, rewrite, verify: references/promote.md. Rename, move, merge, or demote a space on the same skeleton: references/restructure.md.

创建 space（需要一等导航的文件夹）：

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

在最近的祖先 space 的

## Spaces

中注册它——

- [<name>/](<name>/index.md) — description

，当名称需要时对 href 进行百分号编码；描述是后续操作会读取的放置提示。如果不确定，audit 的

missing entry

发现会打印准确行。

删除页面：先扫描指向它的内容——

grep -F '<stem>' --wiki <root>

（每种链接形式都带有 stem；逐个判断命中结果，代码示例除外）——重写或删除实际链接；优先移至

_archives/

而不是删除，然后运行

audit

。

删除 space：先与用户确认（优先使用

_archives/

而不是删除），删除文件夹，从父级

## Spaces

中移除其条目，然后运行

audit

，验证没有悬空引用。

挂载他人的 space：references/mount.md。共享自己的 space：references/share.md。

将页面提升为 space——当页面形态提出这种需要时，常规执行：盘点链接、创建快照、移动、重写、验证：references/promote.md。重命名、移动、合并或降级 space也采用相同的骨架：references/restructure.md。