zhimeng's Agent 操作技能
概述
zhimeng's Agent 是基于 Obsidian 知识库的 RAG 智能问答助手，由 Claude Opus 4.5 驱动。支持知识库问答、日报同步、飞书消息推送等功能。
服务信息
项目 值
项目路径 /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 详细说明
- 问答接口 (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 (可选): 用户标识，用于对话记忆
- 健康检查 (GET /health )
响应体:
{ "status": "healthy", "vectorstore_loaded": true, "document_count": 1316 }
- 重建索引 (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 开启"机器人消息长连接"能力