From b7947528d296608f48c2799cef6b535f5bd5c665 Mon Sep 17 00:00:00 2001
From: ai_xiaopei <xiaopei@aisim.cn>
Date: Sun, 26 Jul 2026 11:08:50 +0800
Subject: [PATCH] fix: 使用 Makefile 编译确保 FTS5 支持
---
bin/kb-cli | 0
docs/superpowers/specs/2026-07-26-kb-cli-draft-integration-design.md | 414 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 414 insertions(+), 0 deletions(-)
diff --git a/bin/kb-cli b/bin/kb-cli
index 27137eb..2578a39 100755
--- a/bin/kb-cli
+++ b/bin/kb-cli
Binary files differ
diff --git a/docs/superpowers/specs/2026-07-26-kb-cli-draft-integration-design.md b/docs/superpowers/specs/2026-07-26-kb-cli-draft-integration-design.md
new file mode 100644
index 0000000..024a706
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-26-kb-cli-draft-integration-design.md
@@ -0,0 +1,414 @@
+# kb-cli 草稿录入集成设计文档
+
+**日期**: 2026-07-26
+**状态**: 设计中
+**版本**: v0.4.0
+
+## 背景
+
+当前知识库草稿录入依赖 Python 脚本 `draft-intake.py`，需要 Hermes Agent 手动调用。本次设计将草稿录入功能集成到 kb-cli，实现：
+1. AI 生成草稿标题和正文
+2. kb-cli 自动提取 tags（调用本地 LLM）
+3. kb-cli 自动搜索相关文档并生成合并指示
+4. 通过知识图谱创建 wikilinks
+
+## 目标
+
+- **简化流程**: 一条命令完成草稿创建 + tags 提取 + 合并指示生成
+- **智能标签**: 使用本地 LLM 提取问题匹配型 tags + 扩展词
+- **自动关联**: 基于 tags 搜索知识库，生成合并指示和 wikilinks
+- **批量重建**: 支持为现有文档批量重建 tags
+
+## 核心流程
+
+```
+草稿内容 → LLM 生成 tags → kb-cli search(tags) → 搜索到 top3 文档 → LLM 生成合并指示
+```
+
+### 详细步骤
+
+1. **LLM 提取 tags + related_docs**
+ - 输入：草稿内容
+ - 输出：5-10 个 tags + 0-5 个相关文档标题
+ - tags 类型：核心问题标签 + 扩展词 + 平台/设备标签
+
+2. **kb-cli search(tags)**
+ - 使用 tags 作为关键词搜索知识库
+ - 返回 top3 相关文档
+
+3. **LLM 生成合并指示**
+ - 输入：草稿内容 + top3 文档
+ - 输出：merge.md（包含合并建议 + 理由）
+
+4. **创建 wikilinks**
+ - 通过 graph 匹配 related_docs 对应的节点
+ - 创建 wikilink edges
+
+5. **写入文件**
+ - draft.md：包含 frontmatter（tags）+ 正文
+ - merge.md：合并指示
+
+## 命令设计
+
+### 1. draft create
+
+创建草稿，自动生成 tags 和合并指示。
+
+```bash
+kb-cli draft create --type 售后 --title "标题" --content-file /path/to/content.md
+```
+
+**参数**:
+- `--type`: 草稿类型（售后/产品/运营/行业/TAPD）
+- `--title`: 草稿标题
+- `--content-file`: 草稿正文文件路径
+- `--source`: 来源标识（可选）
+- `--force`: 强制创建，跳过重复检查
+
+**流程**:
+1. 读取 content-file 内容
+2. 调用 LLM 提取 tags + related_docs
+3. 使用 tags 搜索知识库，获取 top3 文档
+4. 调用 LLM 生成合并指示（基于 top3 文档）
+5. 检查待审阅区是否已存在相同标题的草稿
+6. 创建目录结构：`待审阅/{类型}/NNN-YYYYMMDD-标题/`
+7. 写入 draft.md（包含 frontmatter + 正文）
+8. 写入 merge.md（合并指示）
+9. 通过 graph 匹配 related_docs，创建 wikilink edges
+
+### 2. tags rebuild
+
+批量重建现有文档的 tags。
+
+```bash
+kb-cli tags rebuild [--vault=<路径>] [--dry-run] [--limit=100]
+```
+
+**参数**:
+- `--vault`: 知识库路径（默认 ~/aisim/note/001/笔记001）
+- `--dry-run`: 仅预览，不实际写入
+- `--limit`: 限制处理文档数量（默认 100）
+
+**流程**:
+1. 扫描知识库所有 .md 文件
+2. 对每个文件：
+ - 读取内容
+ - 调用 LLM 提取 tags
+ - 更新 frontmatter 中的 tags 字段
+ - 重建索引（更新 nodes 表的 tags 字段）
+3. 输出统计：处理文件数、更新 tags 数
+
+## LLM 配置
+
+复用 `generate-merge-hint.py` 的配置：
+- **API**: `http://192.168.3.246:1127/v1/chat/completions`
+- **Model**: `qwen3.6-35b-a3b`
+- **参数**: temperature=0.3, max_tokens=2000, enable_thinking=False
+
+### Prompt 设计
+
+#### 提取 tags + related_docs
+
+```
+分析以下知识库草稿，提取：
+1. tags（5-10个）：
+ - 核心问题标签（如"充不进气"、"档案下载失败"）
+ - 扩展词（不同人可能的描述，如"充气慢"、"进气不足"）
+ - 平台/设备标签（如"电子秤平台"、"智能枪"）
+2. related_docs（0-5个）：相关文档标题（用于创建链接）
+
+输出 JSON：
+{
+ "tags": ["充不进气", "充气慢", "进气不足", "智能枪", "电子秤平台"],
+ "related_docs": ["智能枪通气杆卡住漏气", "角阀充装功率不足"]
+}
+
+草稿内容：
+{content}
+```
+
+#### 生成合并指示
+
+```
+你是一个知识库管理助手。请判断以下草稿与哪些知识库文档相关。
+
+## 草稿内容
+{draft_content}
+
+## 候选文档（Top 3）
+1. 标题: {title1}, 路径: {path1}, 相关度: {score1}
+2. 标题: {title2}, 路径: {path2}, 相关度: {score2}
+3. 标题: {title3}, 路径: {path3}, 相关度: {score3}
+
+## 任务
+请分析草稿与每个候选文档的相关性，输出 JSON 格式：
+
+{
+ "recommendation": {
+ "action": "merge|new|split",
+ "target": "目标路径（如果 action=merge）",
+ "reason": "判断理由",
+ "confidence": "high|medium|low"
+ },
+ "analysis": [
+ {
+ "path": "文档路径",
+ "relevance": "high|medium|low",
+ "reason": "相关性说明"
+ }
+ ]
+}
+
+判断标准：
+- action=merge: 草稿内容与某个候选文档高度相关，应该合并
+- action=new: 草稿内容是全新的，应该新建文档
+- action=split: 草稿内容包含多个独立主题，应该拆分
+- confidence=high: 判断很确定
+- confidence=medium: 判断比较确定
+- confidence=low: 判断不太确定
+
+只输出 JSON，不要其他内容。
+```
+
+## 文件结构
+
+```
+待审阅/
+├── 售后提取/
+│ ├── 001-20260726-充不进气问题/
+│ │ ├── draft.md # 草稿内容（包含 tags）
+│ │ └── merge.md # 合并指示
+│ └── 002-20260726-档案下载失败/
+│ ├── draft.md
+│ └── merge.md
+├── 产品提取/
+├── 运营提取/
+├── TAPD提取/
+└── counter.json # 编号计数器
+```
+
+### draft.md 格式
+
+```markdown
+---
+title: "充不进气问题"
+type: "售后"
+status: 待确认
+draft: true
+source: "售后诊断"
+tags: [充不进气, 充气慢, 进气不足, 智能枪, 电子秤平台]
+created: 2026-07-26 10:30:00
+---
+
+## 问题描述
+
+客户反馈充装时充不进气，或充气速度很慢...
+
+## 排查过程
+
+1. 检查智能枪是否正常连接
+2. 检查角阀是否打开
+...
+
+## 解决方案
+
+1. 更换智能枪通气杆
+2. 清理角阀滤网
+...
+```
+
+### merge.md 格式
+
+```markdown
+---
+draft_id: 001-20260726-充不进气问题
+generated_at: 2026-07-26 10:35:00
+confidence: high
+---
+
+## 合并指示
+
+**操作类型**: merge
+**目标**: FAQ/充装类/001-智能枪通气杆卡住漏气.md
+**理由**: 草稿描述的"充不进气"问题与现有 FAQ 001 高度相关，都是智能枪通气杆问题导致的充气异常
+
+## 依据
+
+### 搜索到的相关文档（Top 3）
+
+1. **智能枪通气杆卡住漏气** (相似度: 0.92)
+ - 路径: `FAQ/充装类/001-智能枪通气杆卡住漏气.md`
+ - 摘要: 智能枪通气杆卡住导致漏气，影响充装...
+
+2. **角阀充装功率不足** (相似度: 0.78)
+ - 路径: `FAQ/充装类/017-角阀充装功率不足.md`
+ - 摘要: 角阀供电不足导致充装功率低...
+
+3. **充不进气与老瓶芯片问题** (相似度: 0.75)
+ - 路径: `FAQ/充装类/013-充不进气与老瓶芯片问题.md`
+ - 摘要: 老瓶芯片兼容性问题导致充不进气...
+
+## LLM 判断
+
+- **FAQ/充装类/001-智能枪通气杆卡住漏气.md**: high - 草稿描述的充气慢、充不进气现象与 FAQ 001 的通气杆卡住问题高度一致
+- **FAQ/充装类/017-角阀充装功率不足.md**: medium - 功率不足也会导致充气慢，但根因不同
+- **FAQ/充装类/013-充不进气与老瓶芯片问题.md**: medium - 都是充不进气问题，但老瓶芯片是识别问题，不是充气问题
+```
+
+## 技术实现
+
+### 依赖
+
+- `github.com/mattn/go-sqlite3` (需要 CGO + FTS5 标签)
+- 本地 LLM API（OpenAI 兼容格式）
+
+### 模块设计
+
+#### 1. internal/llm/client.go
+
+LLM 客户端，封装 API 调用。
+
+```go
+type Client struct {
+ apiBase string
+ apiKey string
+ model string
+}
+
+func NewClient(apiBase, apiKey, model string) *Client
+
+func (c *Client) ExtractTags(content string) (*ExtractResult, error)
+func (c *Client) GenerateMergeHint(draftContent string, candidates []SearchResult) (*MergeHint, error)
+```
+
+#### 2. internal/draft/intake.go
+
+草稿录入逻辑。
+
+```go
+type DraftIntake struct {
+ vaultPath string
+ llmClient *llm.Client
+ store *index.Store
+}
+
+func NewDraftIntake(vaultPath string, llmClient *llm.Client, store *index.Store) *DraftIntake
+
+func (d *DraftIntake) CreateDraft(draftType, title, content, source string, force bool) error
+func (d *DraftIntake) RebuildTags(limit int, dryRun bool) error
+```
+
+#### 3. cmd/draft.go
+
+CLI 命令定义。
+
+```go
+var draftCmd = &cobra.Command{
+ Use: "draft",
+ Short: "草稿管理",
+}
+
+var draftCreateCmd = &cobra.Command{
+ Use: "create",
+ Short: "创建草稿",
+ RunE: runDraftCreate,
+}
+
+var tagsRebuildCmd = &cobra.Command{
+ Use: "rebuild",
+ Short: "重建 tags",
+ RunE: runTagsRebuild,
+}
+```
+
+## 待解决问题
+
+### 1. FTS5 模块缺失
+
+**问题**: go-sqlite3 编译时未启用 FTS5，导致 `kb-cli search` 报错 `no such module: fts5`
+
+**解决方案**: 编译时添加 CGO 标签
+```bash
+go build -tags fts5 -o ~/go/bin/kb-cli
+```
+
+**验证**:
+```bash
+kb-cli search 充装
+```
+
+### 2. LLM API 配置
+
+**问题**: 需要硬编码 API 地址和密钥，还是从配置文件读取？
+
+**方案**: 从环境变量读取，支持回退到默认值
+```go
+apiBase := os.Getenv("KB_LLM_API_BASE")
+if apiBase == "" {
+ apiBase = "http://192.168.3.246:1127/v1"
+}
+```
+
+## 实现计划
+
+### Phase 1: 修复 FTS5 问题
+1. 重新编译 kb-cli，添加 `-tags fts5`
+2. 验证 `kb-cli search` 正常工作
+
+### Phase 2: 实现 LLM 客户端
+1. 创建 `internal/llm/client.go`
+2. 实现 `ExtractTags` 和 `GenerateMergeHint` 方法
+3. 编写单元测试
+
+### Phase 3: 实现 draft create 命令
+1. 创建 `internal/draft/intake.go`
+2. 实现草稿创建逻辑
+3. 创建 `cmd/draft.go`，定义 CLI 命令
+4. 集成测试
+
+### Phase 4: 实现 tags rebuild 命令
+1. 实现批量重建 tags 逻辑
+2. 添加 `--dry-run` 支持
+3. 集成测试
+
+### Phase 5: 文档与发布
+1. 更新 README.md
+2. 更新技能文档
+3. 发布 v0.4.0
+
+## 风险与缓解
+
+### 风险 1: LLM 输出不稳定
+
+**缓解**:
+- 使用 temperature=0.3 降低随机性
+- 添加 JSON 解析容错（尝试提取 ```json 代码块）
+- 失败时回退到简单模式（只生成 tags，不生成 related_docs）
+
+### 风险 2: tags 质量不高
+
+**缓解**:
+- Prompt 明确要求三类 tags（核心问题 + 扩展词 + 平台/设备）
+- 提供示例，引导 LLM 输出高质量 tags
+- 后续可通过 `tags rebuild` 批量优化
+
+### 风险 3: 合并指示不准确
+
+**缓解**:
+- 提供 top3 候选文档，让 LLM 有足够信息判断
+- 要求 LLM 输出 confidence 字段，低置信度时提示人工审核
+- 保留 merge.md 文件，方便人工修正
+
+## 成功标准
+
+- `kb-cli draft create` 能成功创建草稿，包含 tags 和合并指示
+- `kb-cli tags rebuild` 能批量重建现有文档的 tags
+- tags 质量满足搜索需求（能匹配用户描述的问题）
+- 合并指示准确率达到 80% 以上（high + medium confidence）
+
+## 后续优化
+
+1. **智能分类**: 根据内容自动判断草稿类型（售后/产品/运营）
+2. **增量更新**: 只重建 tags 变化的文档，减少 LLM 调用
+3. **批量模式**: 支持从文件批量导入草稿（如 CSV、JSON）
+4. **Web UI**: 提供 Web 界面管理草稿和审阅流程
--
Gitblit v1.9.1