grasscaograss Archive Import — 文档导入
Quick start
/archive-import docs/specs/ → records ← spec 文档 → records
/archive-import .zread/wiki/ → knowledge ← wiki 输出 → 知识库
第一个参数：源文档路径（文件或目录）。第二个参数：目标模式（records 或 knowledge）。
两种模式
| 目标 | 处理方式 | 适用场景 |
|---|---|---|
| → records | 格式转换：添加 TL;DR，套用模板，保留内容 | Spec 文档、会议记录、外部报告、一次性文档 |
| → knowledge | 深度整理：重叠分析、领域分组、并行 agent 读写、合并/拆分 | 技术参考资料、wiki 导出、可复用领域知识 |
Records 模式
处理每份文档
- 读取源文档
- 提取：标题、日期（来自文件名或内容）、要点
- 生成 TL;DR 行和关键词标签
- 套用标准 record 模板（参见
/archive-session的模板） - 写入
archive/records/YYYY-MM-DD-<slug>.md
更新 INDEX.md
在 archive/INDEX.md 的 ## Records 下添加每条导入记录，附关键词标签。每行不超过 150 字符。
Knowledge 模式
Knowledge 模式采用三步工作流：分析设计 → 并行写入 → 验证更新。 核心区别在于使用 TaskCreate 为每个领域启动独立 Agent 并行执行，而非串行处理。
领域文件夹参考
archive/knowledge/
├── dual-arm/ ← 双臂系统
├── weld-template/ ← 焊接模板
├── weld-seam/ ← 焊缝规划
├── coarse-positioning/ ← 粗定位
├── scanning/ ← 精定位与扫描
├── capacity/ ← 产能统计
├── weld-tracking/ ← 焊接跟踪
├── coordinate/ ← 坐标与矩阵
├── workflow/ ← 状态机与工作流
├── frontend/ ← 前端界面
├── device-robot/ ← 设备与机器人
├── tools/ ← 工具与其他
第一步：分析源文档，设计领域结构
- 读取所有源文档 — 用 Glob 找到所有文件，逐个 Read
- 提取关键概念、事实、规则、模式 — 从每份文档中抽取出独立的知识单元
- 与现有知识对比重叠 — Read
archive/knowledge/下所有现有文件，标记：- new：全新知识，无重叠
- merge：与现有文件有重叠，需要合并
- skip：已被现有文件完全覆盖
- 按领域分组 — 将知识单元归入上述领域文件夹，确定每个文件的：
- 源文件归属（哪些源文档的内容合并到此文件）
- 与现有知识文件的合并关系
- 向用户展示结构方案 — 输出分组表，等待用户确认：
| 领域文件夹 | 新文件 | 合并到已有文件 | 跳过 |
|-----------|--------|--------------|------|
| dual-arm/ | arc-safety.md | pipeline.md (追加§3) | — |
| scanning/ | laser-calib.md | — | vision.md 已覆盖 |
用户确认后进入第二步。
第二步：创建目录，并行启动 Agent
创建目标文件夹（如尚未存在）
为每个领域文件夹启动一个独立 Agent（通过 TaskCreate），每个 agent 接收以下信息：
- 领域名称和文件夹路径（如
archive/knowledge/dual-arm/） - 要读取的源文件列表（绝对路径）
- 已有知识文件的迁移需求（如需合并，列出目标文件和合并策略）
- 知识文件格式规范（见下方）
- 合并/拆分指导原则
Agent 的职责：
- 读取该领域下所有源文档
- 按主题合并/拆分为 1-N 个知识文件
- 每个文件严格使用标准知识文件格式
- 用 Write 工具写入目标文件夹
- 领域名称和文件夹路径（如
所有 agent 并行执行 — 不等待前一个完成再启动下一个
Agent 提示词模板
为每个 agent 提供的完整指令结构：
你是知识库整理 agent。请完成以下任务：
## 领域
- 名称：<领域名称>
- 目标路径：<绝对路径，如 C:\...\archive\knowledge\dual-arm\>
## 源文件
请读取以下文件并提取知识：
- <文件1绝对路径>
- <文件2绝对路径>
## 迁移需求
- <文件名> 需合并到已有 <existing-file.md> 的 <章节>
- <文件名> 是全新知识，创建新文件
## 知识文件格式
严格使用以下格式（含 frontmatter）：
---
name: kebab-case-slug
description: 一句话摘要
metadata:
type: knowledge
---
# 标题
`关键词1` `关键词2` — 一句话总结
## 背景 / 问题
<为什么需要这个知识，解决什么问题>
## 核心设计
<架构、数据结构、关键算法、核心接口>
## 关键规则
<约束、不变量、边界条件、注意事项>
## 交叉引用
- 相关知识文件路径
- 相关 record 路径
- 相关源码路径
## 合并/拆分原则
- 一份源文档可拆分为多个知识文件（按主题）
- 多份源文档可合并为一个知识文件（按主题聚合）
- 优先按主题内聚，而非按来源文件
- 每个文件聚焦一个主题，避免超过 300 行
- 合并已有文件时保留原有结构，在末尾追加新章节或在对应章节补充内容
第三步：验证和更新索引
- 确认所有文件已生成 — Glob 检查目标文件夹，对比第一步的计划
- 更新
archive/INDEX.md的## Knowledge段 — 按领域分组列出所有知识文件，格式：### <领域>/ — <中文名>（N 文件） - [slug](knowledge/<领域>/slug.md) — 一句话摘要 - 清理迁移的旧文件 — 如果源文档是从项目内其他位置导入的，询问用户是否删除原文件
- 检查新术语 — 扫描新生成的知识文件，提取可能需要加入
archive/CONTEXT.md的术语：- 列出候选术语和定义
- 请用户确认
- 按 archive/CONTEXT.md 现有格式写入（术语名、定义、
_Avoid_提示）
知识文件格式（规范）
---
name: kebab-case-slug
description: 一句话摘要
metadata:
type: knowledge
---
# 标题
`关键词1` `关键词2` — 一句话总结
## 背景 / 问题
## 核心设计
## 关键规则
## 交叉引用
格式要点：
- frontmatter 必须包含
name、description、metadata.type: knowledge - 标题后紧跟关键词标签行（反引号包裹）和一句话总结
- 四个标准章节：背景/问题、核心设计、关键规则、交叉引用
- 交叉引用列出相关的知识文件、record 和源码路径
- 文件名使用 kebab-case，与 frontmatter
name一致