---
name: torch-save
description: "手动保存一条知识到团队知识仓库。当你完成了一个任务想沉淀经验、有飞书文档里的知识想录入、或对话萃取提示按了Y时使用。支持文字描述、飞书文档链接，Claude 自动规范化格式。触发词：保存知识、记录经验、存一下、save knowledge、torch-save。"
disable-model-invocation: true
argument-hint: [知识描述 或 飞书文档链接]
allowed-tools: Bash(git *) Bash(lark-cli *) Read Write Glob
---

# /torch-save — 保存知识到团队仓库

将一条知识规范化后保存到团队知识仓库。

## 前置确认

1. 确认知识仓库路径（按优先级依次查找：当前项目 CLAUDE.md / AGENTS.md / .cursor/rules/torch.md 中的 `团队知识库` 段落 → 询问用户）
2. 验证知识仓库路径存在且包含 `knowledge-catalog.md`
3. 同步知识仓库：`git -C {知识仓库路径} pull --rebase --quiet`
   - **pull 失败**：不阻断保存，提示「知识库同步失败，使用本地版本」继续执行

## 判断输入类型

用户通过 $ARGUMENTS 提供输入，判断属于哪种类型：

### 类型 A：飞书文档链接

识别特征：包含 `feishu.cn/docx/` 或 `feishu.cn/wiki/` 或 `larksuite.com`

处理流程：
1. 从 URL 中提取文档 ID（路径最后一段）
2. 检测 lark-cli 是否可用：
   ```bash
   lark-cli --version 2>/dev/null
   ```
3. **如果可用**：读取文档内容
   ```bash
   lark-cli docs read {doc_id}
   ```
4. **如果不可用**：输出引导信息
   ```
   ⚠️ 检测到未安装 lark-cli，无法自动读取飞书文档。你可以：
   1. 安装 lark-cli（推荐）：pip install lark-feishu-cli
   2. 手动复制文档内容粘贴给我
   3. 提供文档导出的 Markdown 文件路径
   ```
   等待用户提供内容后继续。

### 类型 B：文字描述

识别特征：不是 URL，是自然语言描述

直接使用用户提供的文字作为原始素材。

### 类型 C：无参数（对话萃取后触发）

如果 $ARGUMENTS 为空，回顾当前对话上下文，从中提取可沉淀的知识。

## 规范化流程

### Step 1: 分析内容

从原始素材中提取：
- **类型判断**：这是 model/decision/guideline/pitfall/process 中的哪种？
- **标题**：一句话概括
- **核心内容**：结构化整理
- **标签**：3-5 个关键词 tags
- **来源项目**：从当前目录或 git remote 获取

### Step 2: 生成条目草稿

```yaml
---
id: {待分配}
type: {判断的类型}
maturity: draft
tags: [{提取的标签}]
created: {当前日期}
last_referenced: null
reference_count: 0
contributors: [{git config user.name}]
source_project: {项目名}
evidence:
  - project: {项目名}
    date: {当前日期}
    description: "{来源说明}"
---

# {标题}

{根据类型组织的结构化内容}
```

### Step 3: 展示草稿并确认

```
💾 知识条目草稿：

类型: {type}
标题: {title}
标签: {tags}
存储位置: tech-wiki/{type}s/

---
{完整条目预览}
---

确认保存？[Y/修改/N]
- Y: 直接保存
- 修改: 告诉我要改什么
- N: 取消
```

### Step 4: 分配 ID 并写入

用户确认后：

1. **检查仓库结构完整性**：
   目标目录不存在时自动创建（如 `tech-wiki/pitfalls/` 目录缺失则创建），
   `catalog.md`、`knowledge-catalog.md`、`log.md` 缺失时按模板创建。
2. 读取目标目录下已有条目，找到最大序号，分配下一个 ID
   - 技术知识：`TK-{子类缩写}-{序号}`（如 TK-PIT-002）
   - 业务知识：`BK-{领域缩写}-{子类缩写}-{序号}`
   - 子类缩写：MOD / DEC / GL / PIT / PROC
   - 目录为空时从 001 开始
   - **示例条目**（ID=000 或备注含 📎 示例）不计入序号，从 001 开始分配
3. 写入条目文件到知识仓库对应目录
4. 更新对应 `catalog.md`（在相应 type 分组下追加一行）——不存在则创建
5. 更新 `knowledge-catalog.md` 中的统计数据——不存在则创建
6. 在 `log.md` 末尾追加：
   ```
   ## [{日期}] save | [{用户名}] | {来源描述} | +1 {type} | #{hash}
   - 新增 {ID}: {标题} (draft)
   ```
7. 提交并推送：
   ```bash
   cd {知识仓库路径}
   git add .
   git commit -m "save: 新增 {ID} {标题}"
   git push
   ```
   - **push 失败处理**：如果 push 失败（网络问题/无 remote），提示用户「本地 commit 已完成，请稍后手动 `git push`」，不要因为 push 失败而回滚 commit

## 异常处理

| 场景 | 处理 |
|------|------|
| 知识仓库路径不存在 | 提示用户确认路径，或询问是否创建 |
| `knowledge-catalog.md` 不存在 | 提示"该路径下未找到 catalog 文件，请确认是否为正确的知识仓库" |
| ID 序号冲突（并发写入） | 重新扫描目录取最大值 +1 |
| `git push` 失败 | 提示用户手动 push，本地 commit 已保存不会丢失 |
| 飞书文档内容为空/无权限 | 提示"无法读取文档内容"，建议用户手动粘贴 |
| 条目文件写入失败（权限） | 报错并提示检查目录权限 |

## 注意事项

- 所有新保存的条目 maturity 固定为 `draft`
- 如果用户输入内容太少（< 20 字且不是 URL），追问补充细节
- 如果无法明确判断 type，向用户展示选项让其选择
- 优先生成高质量条目，宁可多问一句也不要生成低质量内容
- **空知识库**：如果知识库仅有示例条目（ID=000），正常保存，不做特殊阻断
- **示例条目**（ID=000 或备注含 📎 示例）不计入统计数字，更新 knowledge-catalog.md 时必须排除