---
name: torch-import
description: "冷启动：从现有项目（代码+Git历史+文档）批量提取知识填充团队知识仓库。当团队有一个已存在的项目首次接入 Torch 知识体系时使用，一次性提取 ≥10 条结构化知识条目。"
disable-model-invocation: true
argument-hint: "[知识仓库路径（可选）]"
allowed-tools: Bash(git *) Read Write Grep Glob
---

# /torch-import — 冷启动知识导入

从当前项目中批量提取隐性知识，填充到团队知识仓库。

## 🛑 执行铁律

Step 3 是**强制中断点**——展示摘要后**必须结束本轮回复**，等用户下一轮明确回复 `Y` / `确认` / `写入` / `继续` 才可进入 Step 4。沉默 ≠ 同意，模糊 ≠ 确认。

✅ 生成条目 → 展示摘要 → **结束回复** → 用户回 Y → 写文件 → 提交

额外规则：
- 示例条目（带 📎 示例 标记或 `example: true`）不计入统计数字，更新 knowledge-catalog.md 时必须排除

## 前置确认

1. 确认知识仓库路径（按优先级依次查找：$ARGUMENTS 传入 → 当前项目 CLAUDE.md / AGENTS.md / .cursor/rules/torch.md 中的 `团队知识库` 段落 → 询问用户）
2. 如果路径为空，询问用户提供知识仓库路径
3. 验证知识仓库路径存在且包含 `knowledge-catalog.md`
4. 同步知识仓库：`git -C {知识仓库路径} pull --rebase --quiet`

## 执行流程

### Step 1: 扫描当前项目

并行扫描以下 5 个来源，收集原始素材：

#### 1.1 代码结构分析
- 识别技术栈（语言、框架、构建工具）
- 识别模块划分和核心目录结构
- 识别关键设计模式（如分层架构、事件驱动等）
- **产出类型**：model

#### 1.2 文档分析
- 读取 CLAUDE.md、README.md、docs/ 下的文档
- 提取项目约定、技术决策、架构说明
- **产出类型**：decision, guideline

#### 1.3 Git 热点分析
```bash
git log --name-only --diff-filter=M --since="6 months ago" -- . | head -200
```
- 用 `git log --name-only` 获取修改文件列表，在 AI 侧统计频次（跨平台兼容，避免 `sort | uniq -c`）
- 反复修改的文件 → 可能是踩坑点或复杂模块
- 分析这些热点文件的 commit message，提取问题模式
- **产出类型**：pitfall
- **fallback**：git log 为空（新仓库/无历史）→ 跳过

#### 1.4 Git Revert/Fix 分析
```bash
git log --oneline --all --grep="revert" --grep="rollback" --grep="hotfix" --grep="fix" --since="6 months ago" | head -20
```
- 回滚记录 → 决策失误或已知陷阱
- 分析 revert 的原因（读 commit message 和相关 diff）
- **产出类型**：pitfall, decision
- **fallback**：无 revert/fix 记录 → 跳过

#### 1.5 配置文件分析
- 扫描 application.yml、pom.xml、package.json 等配置文件
- 识别非显而易见的配置项（多环境、多数据源、特殊参数）
- **产出类型**：guideline

### Step 2: 生成知识条目

对每条提取的知识，生成标准格式条目：

```yaml
---
id: {自动分配，读取目标目录下最大序号+1}
type: {model|decision|guideline|pitfall|process}
maturity: draft
tags: [从内容中提取的关键词标签]
created: {当前日期 YYYY-MM-DD}
last_referenced: null
reference_count: 0
contributors: [当前用户名，从 git config user.name 获取]
source_project: {当前项目名，从目录名或 git remote 获取}
evidence:
  - project: {当前项目名}
    date: {当前日期}
    description: "{提取来源说明}"
---

# {标题}

## {根据类型组织内容}
...
```

**目标**：生成 ≥ 10 条知识条目。如果某个来源没有有价值的内容，跳过。

**不足 10 条时的处理**：宁缺毋滥——如果 5 个来源扫描后仅得到 N 条（N < 10），照常进入 Step 3 展示，在摘要中注明「仅提取到 N 条，该项目可沉淀的知识较少」。禁止为凑数生成低质量条目。

**各 type 内容结构模板**：

- **model**：`## 定义` → `## 结构/字段` → `## 关联关系`
- **decision**：`## 背景` → `## 方案对比`（表格） → `## 结论` → `## 后续影响`
- **guideline**：`## 规则` → `## 示例`（正例+反例） → `## 例外情况`
- **pitfall**：`## 现象` → `## 根因` → `## 解决方案` → `## 如何预防`
- **process**：`## 前置条件` → `## 步骤`（有序列表） → `## 注意事项`

### Step 3: 【强制中断点】展示摘要

仅在内存中生成条目（**禁止写入任何文件**），向用户展示：

```
🔥 Torch Import 预览（尚未写入）

从项目 {project_name} 中提取了 {N} 条知识：

| # | ID | 类型 | 标题 | 来源 |
|---|-----|------|------|------|
| 1 | TK-PIT-002 | pitfall | XXX | Git 热点 |
| 2 | TK-DEC-002 | decision | XXX | CLAUDE.md |
| ... |

⚠️ 以上条目尚未写入知识仓库，请确认：
- Y: 全部写入
- N: 取消
- 编辑: 逐条确认（可删除/修改）
```

输出上述内容后，**立即结束本轮回复**（见执行铁律）。

### Step 4: 写入知识仓库

**前置检查**：用户本轮消息必须包含 `Y` / `确认` / `写入` / `继续` 之一，否则拒绝执行并重新请求确认。

用户确认后：

1. **初始化仓库结构（如果是空仓库）**：
   检查知识仓库是否已有完整目录结构，缺失的目录和文件按 template/ 模板补全：
   - 缺 `knowledge-catalog.md` → 从模板创建
   - 缺 `tech-wiki/` 及子目录 → 创建 `tech-wiki/{models,decisions,guidelines,pitfalls,processes}/` 和 `catalog.md`
   - 缺 `biz-wiki/` → 创建基础结构
   - 缺 `log.md` → 从模板创建
   - 缺 `.knowledge-config.yaml` → 从模板创建（提示用户修改团队名和成员）
   - 已存在的目录和文件不动
2. 将条目文件写入知识仓库对应目录（按 type 分目录）
3. 更新 `tech-wiki/catalog.md`（或 `biz-wiki/{domain}/catalog.md`）——不存在则创建，已存在则追加
   - 在对应 type 的表格末尾追加一行：`| [ID](type_dir/ID.md) | 标题 | draft | tags | 0 | |`
   - 示例条目（ID=000 且备注含 📎 示例）不修改不删除
4. 更新 `knowledge-catalog.md` 中的统计数据——不存在则创建，已存在则更新
   - 修改「统计概览」表格中对应层级的条目数和 draft 计数（+N）
   - 更新「最近更新」为当前日期
   - 在「贡献统计」表格中追加/更新贡献者行
5. 在 `log.md` 末尾追加记录：
   ```
   ## [{日期}] ingest | [{用户名}] | {项目名}冷启动导入 | +N条 | #{session_hash前6位}
   - 新增 {ID}: {标题} (draft)
   ...
   ```
6. 执行 git 操作：
   ```bash
   cd {知识仓库路径}
   git add .
   git commit -m "ingest: 从 {项目名} 冷启动导入 {N} 条知识"
   git push
   ```
   - **push 失败处理**：如果 push 失败（网络问题/无 remote），提示用户「本地 commit 已完成，请稍后手动 `git push`」，不要因为 push 失败而回滚 commit

## 注意事项

- 所有生成条目 maturity 固定为 `draft`
- ID 分配规则：读取目标目录下已有条目的最大序号，+1 递增
- ID 前缀：技术知识用 `TK-{子类}-{序号}`，业务知识用 `BK-{领域}-{子类}-{序号}`
- 子类缩写：MOD(model) DEC(decision) GL(guideline) PIT(pitfall) PROC(process)
- 如果无法判断是技术知识还是业务知识，默认放 tech-wiki
- 宁可少提取高质量条目，不要凑数生成低质量内容