Knowledge Reorg

Knowledge Reorg

知识库位于 archive/knowledge/，按领域组织目录。本技能提供领域级结构操作与健康检查。

知识库结构

archive/knowledge/
├── dual-arm/          ← 双臂系统
├── weld-template/     ← 焊接模板
├── weld-seam/         ← 焊缝规划
├── coarse-positioning/ ← 粗定位
├── scanning/          ← 精定位与扫描
├── capacity/          ← 产能统计
├── weld-tracking/     ← 焊接跟踪
├── coordinate/        ← 坐标与矩阵
├── workflow/          ← 状态机与工作流
├── frontend/          ← 前端界面
├── device-robot/      ← 设备与机器人
└── tools/             ← 工具与其他

知识文件格式

每个 .md 文件必须包含 YAML frontmatter：

---
name: kebab-case-slug
description: 一句话摘要
metadata:
  type: knowledge
---

# 标题

## 交叉引用
- 相关概念见 [[other-file-name]]

命令语法

/knowledge-reorg                                    ← 无参数：执行 inspect
/knowledge-reorg inspect                            ← 健康检查
/knowledge-reorg merge  into    ← 合并两个领域
/knowledge-reorg split  → ,   ← 拆分领域（agent 驱动）
/knowledge-reorg move  to             ← 跨领域移动文件
/knowledge-reorg consolidate                ← 合并碎片文件（agent 驱动）

领域名对应 archive/knowledge/ 下的目录名（如 dual-arm、weld-seam）。文件名不含扩展名（如 strategy、arc-timing）。

---

inspect — 健康检查

扫描所有领域文件夹，逐项报告以下指标：

| 检查项 | 条件 | 级别 | 建议 | |--------|------|------|------| | 领域膨胀 | 文件数 > 10 | ⚠️ 警告 | 建议拆分为子领域 | | 孤立领域 | 文件数 = 1 | ⚠️ 警告 | 建议合并到语义最接近的领域 | | 交叉引用断链 | [[name]] 指向不存在的文件 | 🔴 错误 | 报告断链位置与目标名 | | 缺少 frontmatter | 文件不以 --- 开头或缺少 name/description/metadata.type | 🔴 错误 | 报告缺失字段 | | 重复 name | 两个文件的 frontmatter name 相同 | 🔴 错误 | 报告冲突文件 |

输出格式

以表格形式呈现每个领域的检查结果：

领域                文件数  警告  错误  详情
dual-arm               5     0     0
weld-seam              5     0     1   断链: [[nonexistent]] (planning.md L42)
weld-tracking          1     1     0   建议: 合并到相邻领域
workflow               7     0     0

对每个问题附上具体位置（文件名 + 行号），便于定位修复。

执行步骤

1. 列出 archive/knowledge/ 下所有子目录
2. 遍历每个目录内的 .md 文件
3. 解析 frontmatter，检查格式完整性
4. 提取所有 [[...]] 交叉引用，验证目标文件是否存在
5. 汇总为报告，按领域分组展示

---

merge — 合并两个领域

将 ` 的全部文件移入 `，更新所有交叉引用和索引。

语法

/knowledge-reorg merge weld-tracking into coordinate

执行步骤

1. 验证：确认 archive/knowledge// 和 archive/knowledge// 均存在
2. 移动文件：将 / 下所有 .md 文件移到 /
3. 更新交叉引用：搜索 archive/ 下所有 .md 文件，将引用路径从旧领域更新为新领域

• 在 INDEX.md 中更新路径：knowledge// → knowledge//
• 在其他知识文件中更新 [[name]] 引用（如果 name 不变则无需更新）

1. 清理：删除空的 / 目录
2. 同步索引：重写 archive/INDEX.md 的 Knowledge 段落，反映新路径

冲突处理

如果 ` 中已存在同名 .md` 文件，停止并报告冲突，让用户决定如何处理（跳过/重命名/合并内容）。

---

split — 拆分领域（agent 驱动）

将一个领域拆分为两个或多个子领域。agent 根据文件内容的语义相关性判定每个文件的归属。

语法

/knowledge-reorg split workflow → fsm, production

执行步骤

1. 验证：确认源领域存在，目标领域不存在（避免覆盖）
2. 读取文件：读取源领域下所有 .md 文件的完整内容
3. Agent 判定归属（spawn agent 执行）：

• 分析每个文件的 description、标题和核心内容
• 根据用户指定的分类依据（命令参数）或语义相似度，为每个文件分配到目标子领域
• 输出一份归属表供用户确认：

`` 文件名 → 目标领域 理由 state-machine.md → fsm 状态机核心定义 persistence.md → fsm 崩溃恢复属于状态机范畴 production.md → production 生产渲染逻辑 cache.md → production 缓存与生产数据绑定 ``

1. 用户确认：展示归属表，等待用户确认或调整
2. 执行移动：按归属表移动文件到对应子目录
3. 更新交叉引用：同 merge 步骤 3
4. 创建目录：创建新的子领域目录（如果尚不存在）
5. 删除源目录：仅当源目录为空时删除
6. 同步索引：重写 archive/INDEX.md

---

move — 跨领域移动文件

将单个文件从一个领域移到另一个领域。

语法

/knowledge-reorg move cache to scanning

执行步骤

1. 定位文件：在 archive/knowledge/ 下搜索 ` 对应的 .md 文件（按 frontmatter name` 匹配）
2. 验证目标：确认目标领域目录存在
3. 检查冲突：目标目录下是否已存在同名文件
4. 移动文件
5. 更新交叉引用：更新 INDEX.md 中的路径
6. 同步索引

---

consolidate — 合并碎片（agent 驱动）

当一个领域内文件过于碎片化（内容少、主题重叠）时，由 agent 判断哪些文件应该合并。

语法

/knowledge-reorg consolidate device-robot

执行步骤

1. 读取领域：读取目标领域下所有 .md 文件的完整内容
2. Agent 分析（spawn agent 执行）：

• 评估每个文件的长度和内容密度
• 识别主题重叠的文件组
• 提出合并方案：

``` 建议合并：

• robot-ops.md + fanuc.md → robot-ops.md

理由: fanuc 是 robot-ops 的具体实现子集，合并后更连贯 保留不动：

• config.md（独立主题，内容充分）
• calculator.md（独立主题，内容充分）

```

• 为每个合并组生成合并后的完整内容草稿

1. 用户确认：展示合并方案和草稿，等待用户确认
2. 执行合并：用合并后的内容替换目标文件，删除被合并的源文件
3. 更新交叉引用：被删除文件的 [[name]] 引用改为指向合并后的文件
4. 同步索引

---

索引同步规则

所有结构操作完成后，必须执行以下同步步骤：

1. 更新 archive/INDEX.md

• 重新扫描 archive/knowledge/ 下所有目录和文件
• 重写 Knowledge 段落（保持 Records、ADR 等其他段落不变）
• 格式与现有 INDEX.md 一致：

```markdown ### / — （N 文件）

• [name](knowledge/domain/name.md) — description

```

• 按领域拼音字母排序

2. 更新文件内交叉引用

• 搜索所有 archive/knowledge/ 下的 .md 文件
• 找到所有 [[name]] 格式的引用
• 如果引用的目标文件已被移动/重命名/删除：
• 移动/重命名：更新 [[name]] 为新的 name（如果 name 变了）
• 删除（被合并）：更新 [[name]] 为合并后文件的 name
• 目标不存在：标记为断链并在输出中警告

3. 不破坏的内容

• archive/records/ 下的记录文件 — 不触碰
• archive/adr/ 下的架构决策 — 不触碰
• 文件内部的标题、正文内容 — 只在 consolidate 操作时由 agent 修改

---

通用约束

• 先确认后执行：所有写操作（merge/split/move/consolidate）在展示计划后等待用户确认，除非用户使用 --force 标记
• 原子性：如果一个操作的中间步骤失败，报告已完成的步骤和失败点，由用户决定回滚或继续
• 备份意识：操作前提醒用户 archive/ 已在 git 版本控制下，如需回退可用 git checkout
• 不创建新知识：本技能只做结构重组，不生成新的知识内容（consolidate 的合并除外，但也是聚合现有内容）

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: grasscaograss
• Source: grasscaograss/AwesomeWeldoneSkills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.