majiayu000 zhimeng's 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 |
接收飞书消息事件 | - |
API 详细说明
1. 问答接口 (POST /ask)
请求体:
{
"question": "用户问题",
"top_k": 5,
"include_sources": true,
"filter_folder": null,
"user_id": "用户唯一标识"
}
响应体:
{
"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)
响应体:
{
"status": "healthy",
"vectorstore_loaded": true,
"document_count": 1316
}
3. 重建索引 (POST /index)
请求体:
{
"paths": ["Journal", "Projects"],
"force": false
}
响应体:
{
"status": "success",
"chunks_indexed": 1500
}
标准操作流程 (SOP)
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: 启动/停止服务
启动服务:
cd /Users/qitmac001395/workspace/QAL/ideas/apps/zhimeng-agent
poetry run uvicorn src.main:app --host 0.0.0.0 --port 8001 --reload
启动飞书长连接 (本地开发，无需公网IP):
cd /Users/qitmac001395/workspace/QAL/ideas/apps/zhimeng-agent
poetry run python src/feishu_ws.py
后台启动:
# 主服务
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
日报同步工作流:
- 本技能读取 Obsidian 日报
- 格式化内容
- 调用
feishu-messaging技能发送消息
集成 obsidian-organize
知识库维护工作流:
- 使用
obsidian-organize整理文档结构 - 触发本技能的
/index重建索引 - 验证检索质量
常见问题
Q: 服务无法启动？
检查:
- Python 环境:
poetry install - 端口占用:
lsof -i :8001 - 环境变量:
config/.env是否存在
Q: 检索结果不准确？
尝试:
- 重建索引:
POST /index {"force": true} - 增加 top_k 值
- 使用 filter_folder 限定范围
Q: 飞书长连接断开？
检查:
- 网络连接
- App 凭证是否过期
- 查看日志:
tail -f feishu_ws.log
配置文件
config/.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 的对话历史 # 对话记忆更新
注意事项
- API 密钥安全:
.env文件不要提交到 Git - 成本控制: 每次问答约消耗 Claude API $0.01-0.05
- 索引时间: 完整重建约需 2-5 分钟 (取决于文档数量)
- 对话记忆: 基于 user_id 隔离，无 user_id 时不保留历史
- 飞书长连接: 需要 App 开启"机器人消息长连接"能力