yxstack-skill/commands/learn.md

# /learn - 知识库学习与检索

## 命令定位
摄入外部业务材料（报告、调研、数据、文档等），解析并汇总为结构化知识库，
供所有 YxStack 指令在执行时自动加载参考。

## 子命令

| 子命令 | 用途 |
|--------|------|
| `/learn <路径>` | 摄入指定文件/目录，解析并更新知识库 |
| `/learn update` | 增量更新，检测新增或修改的材料 |
| `/learn show` | 查看当前知识库摘要（模块、材料数、最近更新） |
| `/learn prune` | 修剪过期或矛盾的知识条目 |

---

## /learn <路径> — 摄入外部材料

### Step 1: 扫描材料

扫描目标路径，识别所有可处理文件：

**支持格式**：
- 文档：`.md`, `.txt`, `.pdf`, `.docx`
- 表格：`.xlsx`, `.csv`
- 演示：`.pptx`
- 网页：`.html`, 直接输入 URL
- 图片：`.png`, `.jpg`（OCR 文字提取）
- 结构化数据：`.json`

**跳过规则**：`.yxstack/`, `node_modules/`, `.git/`, `.DS_Store`
**目录处理**：递归扫描，按修改时间排序

### Step 2: 逐份解析

对每个文件，使用 Read 工具读取内容，AI 模型提取结构化信息：

**信息提取维度**：
| 维度 | 提取内容 |
|------|----------|
| 行业数据 | 市场规模、增长率、政策环境、技术趋势（数字+来源页） |
| 竞品信息 | 名称、定位、核心优势、主要劣势、价格带、目标用户 |
| 用户信息 | 画像描述、痛点清单、采购/使用决策链、付费意愿 |
| 约束条件 | 预算范围、时间节点、合规/监管要求、资源限制 |
| 假设与观点 | 非事实性判断、预测性结论 → 务必标注为"假设"，归入待验证 |

### Step 3: 知识汇总

- **按模块归类**：行业背景 / 市场数据 / 竞品全景 / 目标用户 / 关键约束 / 待验证假设
- **去重合并**：相同信息点合并为一条，标注多来源
- **冲突处理**：矛盾信息点保留双方观点，归入「知识冲突」区域
- **溯源标注**：每条关键信息标注来源材料 + 页码/段落

### Step 4: 写入知识库

将汇总结果写入 `.yxstack/learn/knowledge.md`：

**新增模式**（knowledge.md 不存在）：创建新文件，写入全部模块
**增量模式**（knowledge.md 已存在）：合并新材料信息，更新对应模块，追加材料溯源

**knowledge.md 格式**：
```markdown
---
title: "项目知识库"
project: "{项目名称}"
last_updated: "{YYYY-MM-DD}"
materials_processed: {N}
---

# 项目知识库

> 最近更新：{YYYY-MM-DD}
> 已处理材料：{N} 份（详见 [材料溯源](#材料溯源)）

## 行业背景
- 关键事实1 [来源：材料A]
- 关键事实2 [来源：材料B]

## 市场数据
| 指标 | 数值 | 来源 |
|------|------|------|
| 市场规模 | XXX | 材料A (p.12) |

## 竞品全景
| 竞品 | 定位 | 核心优势 | 主要劣势 | 价格带 | 来源 |
|------|------|----------|----------|--------|------|

## 目标用户
- 核心用户画像：[来源]
- 痛点清单（按严重程度）：
  1. 痛点1 [来源]
  2. 痛点2 [来源]
- 付费意愿与能力：[来源]

## 关键约束
- 预算约束：
- 时间约束：
- 合规/监管约束：
- 资源约束：

## 待验证假设
| 假设 | 验证路径 | 来源 |
|------|----------|------|
| XXX  | 如何验证 | 材料C |

## 知识冲突
| 主题 | 观点A | 来源A | 观点B | 来源B |
|------|-------|-------|-------|-------|

## 材料溯源
| 材料 | 类型 | 处理时间 | 关键信息贡献 |
|------|------|----------|-------------|
```

### Step 5: 更新元数据

更新 `.yxstack/learn/_learn_meta.json`：
```json
{
  "project": "{项目名称}",
  "last_updated": "{ISO时间戳}",
  "materials_processed": N,
  "materials": [
    {
      "name": "材料名称",
      "path": "原始路径",
      "type": "pdf",
      "processed_at": "ISO时间戳",
      "sha256": "可选：文件哈希"
    }
  ]
}
```

---

## /learn update — 增量更新

重新扫描已记录的材料目录，检测：
- 新增文件 → 解析并追加到 knowledge.md
- 修改过的文件 → 标记对应模块为「待更新」，重新解析
- 删除的文件 → 保留历史知识，标记来源材料已不可用

---

## /learn show — 查看摘要

读取 `.yxstack/learn/knowledge.md`，简洁展示：
- 知识库覆盖的模块列表
- 已处理材料数量
- 最近更新时间
- 待验证假设数量
- 知识冲突数量

---

## /learn prune — 修剪知识库

对标 gstack 的 `/learn prune` 机制：

1. **过期检测**：检查每条信息的来源材料是否仍可访问
2. **矛盾检测**：检查同一主题下是否存在相互矛盾的结论
3. **置信度评估**：标注每条知识的可靠性（从来源材料质量推断）
4. **用户确认**：对标记条目逐条询问：
   - 删除（知识已过时）
   - 保留（仍有效）
   - 降级（标注为「待验证」）
5. 修剪后更新 knowledge.md

判断标准：「下次执行分析时，这条知识还有参考价值吗？」

---

## 存档规则

/learn 本身不产生报告文件（不同于其他 YxStack 指令），而是直接维护 `.yxstack/learn/knowledge.md`。

执行 `/learn` 后，追加事件日志：
```json
{"skill":"learn","event":"completed","ts":"当前时间","summary":"摄入 N 份材料，知识库已更新","decision":"新增/更新模块列表"}
```

---

## 与其他指令的关系

| 指令 | 如何引用知识库 |
|------|---------------|
| /pfit | 参考目标用户（痛点清单）、待验证假设 |
| /pos | 参考竞品全景、行业背景、市场数据 |
| /uj | 参考目标用户（画像+决策链）、痛点清单 |
| /prd | 参考全部模块 |
| /money | 参考市场数据、竞品全景（价格带）、关键约束（预算） |
| /gtm | 参考目标用户（画像+决策链）、行业背景 |
| /metric | 参考市场数据（行业基准）、关键约束 |
| /comp | 参考竞品全景、市场数据 |

---

## 常见误区
- 把个人观点当事实写入知识库（应标注为假设）
- 材料之间的信息不核实矛盾直接合并（应标注冲突）
- 知识库只建不维护（应定期 prune）
- 把单个来源的结论当作确定事实（应标注置信度）