zhimeng-agent

zhimeng's Agent 是基于 Obsidian 知识库的 RAG 智能问答助手，由 Claude Opus 4.5 驱动。支持知识库问答、日报同步、飞书消息推送等功能。

| 项目 | 值 |

|------|-----|

| 服务地址 | http://localhost:8001 |

| 项目路径 | /Users/qitmac001395/workspace/QAL/ideas/apps/zhimeng-agent |

| 知识库路径 | /Users/qitmac001395/Documents/Obsidian Vault |

| 向量数据库 | ChromaDB (data/chroma/) |

| LLM 模型 | anthropic/claude-sonnet-4-20250514 |

| 能力 | 端点 | 用途 | 示例触发词 |

|------|------|------|-----------|

| 知识问答 | POST /ask | 基于知识库的 RAG 问答 | "问知识库"、"查一下" |

| 健康检查 | GET /health | 检查服务状态和文档数量 | "检查Agent"、"服务状态" |

| 重建索引 | POST /index | 重新索引 Obsidian 文档 | "重建索引"、"更新知识库" |

| 飞书Webhook | POST /webhook/feishu | 接收飞书消息事件 | - |

1. 问答接口 (`POST /ask`)

请求体:

```json

{

"question": "用户问题",

"top_k": 5,

"include_sources": true,

"filter_folder": null,

"user_id": "用户唯一标识"

}

```

响应体:

```json

{

"answer": "回答内容",

"sources": [

{"file": "文件名.md", "folder": "文件夹", "relevance": 0.85}

],

"tokens_used": 1234

}

```

参数说明:

• question (必填): 用户问题
• top_k (可选, 默认5): 检索文档数量 (1-20)
• include_sources (可选, 默认true): 是否返回来源
• filter_folder (可选): 限定搜索的文件夹
• user_id (可选): 用户标识，用于对话记忆

2. 健康检查 (`GET /health`)

响应体:

```json

{

"status": "healthy",

"vectorstore_loaded": true,

"document_count": 1316

}

```

3. 重建索引 (`POST /index`)

请求体:

```json

{

"paths": ["Journal", "Projects"],

"force": false

}

```

响应体:

```json

{

"status": "success",

"chunks_indexed": 1500

}

```

SOP 1: 知识库问答

```

步骤1: 检查服务状态

curl http://localhost:8001/health

步骤2: 发送问题

curl -X POST http://localhost:8001/ask \

-H "Content-Type: application/json" \

-d '{"question": "你的问题", "top_k": 5}'

步骤3: 解析响应中的 answer 和 sources

```

SOP 2: 日报同步到飞书

```

步骤1: 读取今日日报

读取 ~/Documents/Obsidian Vault/Journal/YYYYMMDD.md

步骤2: 提取关键内容

- 完成的工作

- 代码变更统计

- AI 消耗统计

步骤3: 格式化为飞书消息

使用 feishu-messaging 技能发送

步骤4: 发送到目标用户

调用 mcp__feishu__im_v1_message_create

收件人: 王植萌 (open_id: ou_18b8063b232cbdec73ea1541dfb74890)

```

SOP 3: 重建知识库索引

```

步骤1: 停止正在进行的查询

步骤2: 调用索引接口

curl -X POST http://localhost:8001/index \

-H "Content-Type: application/json" \

-d '{"force": true}'

步骤3: 验证索引结果

curl http://localhost:8001/health

确认 document_count 已更新

```

SOP 4: 启动/停止服务

启动服务:

```bash

cd /Users/qitmac001395/workspace/QAL/ideas/apps/zhimeng-agent

poetry run uvicorn src.main:app --host 0.0.0.0 --port 8001 --reload

```

启动飞书长连接 (本地开发，无需公网IP):

```bash

cd /Users/qitmac001395/workspace/QAL/ideas/apps/zhimeng-agent

poetry run python src/feishu_ws.py

```

后台启动:

```bash

# 主服务

nohup poetry run uvicorn src.main:app --host 0.0.0.0 --port 8001 > /tmp/zhimeng-agent.log 2>&1 &

# 飞书长连接

nohup poetry run python src/feishu_ws.py > feishu_ws.log 2>&1 &

```

集成 feishu-messaging

日报同步工作流:

1. 本技能读取 Obsidian 日报
2. 格式化内容
3. 调用 feishu-messaging 技能发送消息

集成 obsidian-organize

知识库维护工作流:

1. 使用 obsidian-organize 整理文档结构
2. 触发本技能的 /index 重建索引
3. 验证检索质量

Q: 服务无法启动？

检查:

1. Python 环境: poetry install
2. 端口占用: lsof -i :8001
3. 环境变量: config/.env 是否存在

Q: 检索结果不准确？

尝试:

1. 重建索引: POST /index {"force": true}
2. 增加 top_k 值
3. 使用 filter_folder 限定范围

Q: 飞书长连接断开？

检查:

1. 网络连接
2. App 凭证是否过期
3. 查看日志: tail -f feishu_ws.log

config/.env

```env

# LLM 配置

LLM_PROVIDER=anthropic

LLM_MODEL=claude-sonnet-4-20250514

ANTHROPIC_API_KEY=sk-ant-xxx

# 飞书配置

FEISHU_APP_ID=cli_xxx

FEISHU_APP_SECRET=xxx

# 服务配置

HOST=0.0.0.0

PORT=8001

DEBUG=true

```

config/settings.py

主要配置项:

• obsidian_vault_path: 知识库路径
• chroma_persist_dir: 向量数据库持久化目录
• chunk_size: 文档分块大小 (默认1000)
• chunk_overlap: 分块重叠 (默认200)

日志位置

• 主服务: 标准输出 或 /tmp/zhimeng-agent.log
• 飞书长连接: feishu_ws.log

关键日志模式

```

INFO:src.retriever:检索到 X 个相关文档 # 检索成功

INFO:httpx:HTTP Request: POST https://api.anthropic.com/v1/messages # LLM 调用

INFO:src.smart_agent:已更新用户 xxx 的对话历史 # 对话记忆更新

```

1. API 密钥安全: .env 文件不要提交到 Git
2. 成本控制: 每次问答约消耗 Claude API $0.01-0.05
3. 索引时间: 完整重建约需 2-5 分钟 (取决于文档数量)
4. 对话记忆: 基于 user_id 隔离，无 user_id 时不保留历史
5. 飞书长连接: 需要 App 开启"机器人消息长连接"能力