hack/tools/scripts/llm-key-hunter/results/_cache/content/abc-lee_niu-agent.json

{"repo": "abc-lee/niu-agent", "files": {"docs/manual-user-guide.md": {"a2dc05c539255f7025314ccba1494145cb29dfa3": {"t": 1785746455.7276278, "n": 20765, "h": "355d398e8162501c", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nRust 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"\",\n    \"litellm_kwargs\": {}\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"none\",\n    \"litellm_kwargs\": {}\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点基础地址（不含路径后缀，LiteLLM 会自动追加：openai 类型追加 `/chat/completions`，anthropic 类型追加 `/v1/messages`） |\n| `model` | 模型名称 |\n| `type` | 系统内部参数，用于区分 API 格式转换和认证方式：`openai`（OpenAI 兼容格式）或 `anthropic`（Anthropic 原生格式）。**不是** LiteLLM 的 custom_llm_provider |\n| `provider` | LiteLLM 路由参数，映射为 `custom_llm_provider`。常见值：`\"\"`（空，默认由 type 决定）、`\"volcengine\"`（火山引擎）。填写后模型名无需加厂商前缀 |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"`。**注意**：该参数的实际效果与模型基础能力强相关，不同模型的最优值差异很大，需实测确定（详见下方\"reasoning_effort 配置与测试指南\"） |\n| `litellm_kwargs` | 厂商特有参数，JSON 对象格式，原样透传给 LiteLLM。用于传递各厂商 SDK 要求的额外参数（如火山引擎的 `thinking`、`allowed_openai_params` 等）。代码不做任何厂商判断，只负责透传 |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**火山方舟(Ark)端点配置说明**\n\n火山方舟提供两种计费端点，模型池相同，但功能权限有差异：\n\n| 端点 | 地址 | 计费 | response_format | 适用场景 |\n|------|------|------|-----------------|----------|\n| 标准端点 | `https://ark.cn-beijing.volces.com/api/v3` | 按量计费 | 支持 | 主 Agent、LightRAG |\n| Coding Plan | `https://ark.cn-beijing.volces.com/api/coding/v3` | 包月计费 | **不支持**（网关 400 拒绝） | 主 Agent |\n\n**格式化输出（response_format）能力自动探测**\n\n设置窗口\"测试连接并保存\"按钮在测试通过后，会自动追加一次格式化输出能力探测，按 3 档递进调用真实 LLM，找出当前配置支持的最强档位：\n\n| 档位 | response_format.type | 约束 | 典型支持厂商 |\n|------|---------------------|------|--------------|\n| Tier 1（最强） | `json_schema` strict | 输出严格匹配 schema | OpenAI 真正支持 |\n| Tier 2（中等） | `json_object` | 输出合法 JSON，不约束字段 | OpenAI、DeepSeek |\n| Tier 3（最弱） | 无 response_format | prompt + `json_repair` 客户端容错 | 所有厂商兜底 |\n\n**探测流程**：从 Tier 1 开始测，失败则降级测 Tier 2，再失败则定为 Tier 3。每档失败条件：\n- `model_rejected`：LiteLLM 抛 `BadRequestError`/`UnsupportedParamsError`（模型/网关 4xx 拒绝，如豆包 Coding Plan）\n- `gateway_blocked`：网关返回 200 但响应非合法 JSON（网关接受参数但模型输出漂移，如 GLM xopglm5）\n\n探测采用三次采样 + 冲突式设计：\n- 三次采样全过才升档，任何一次失败立即降级——防 flaky 网关（豆包 Coding\n  Plan 2026-07-21 实测：同一请求 5 次采样 2 次执行、3 次静默忽略）碰巧\n  命中执行窗口期误判支持\n- 冲突式设计：schema 强制要求 `{\"verdict\": \"SCHEMA_ENFORCED\"}`，prompt\n  却要求模型写普通英文句子且禁止输出 JSON——只有 schema 战胜 prompt\n  （输出被强制为 schema JSON）才判定真支持，模型跟随 prompt 输出普通\n  文本即判定网关静默忽略\n- 限流单独处理：RateLimitError 不计失败，sleep 后重试本次采样（指数\n  退避 5s→10s→20s→40s→80s，最多 5 次），直到返回非限流结果才判定\n\n**写入配置**：\n- `lightrag_llm.litellm_kwargs.response_format_mode`：`\"json_schema\"` / `\"json_object\"` / `\"prompt_only\"`\n- `lightrag_llm.litellm_kwargs.allowed_openai_params`：前两档 `[\"response_format\"]`，prompt_only 档 `[]`（双写兼容旧逻辑）\n\n**典型场景**（2026-07-19 实测）：\n- 豆包 Coding Plan 端点（`/api/coding/v3`，model=`ark-code-latest`）：\n  网关行为非确定性（flaky），同一请求多次采样结果不稳定（有时执行\n  json_schema strict、有时静默忽略），三次采样必然 ≥1 次静默忽略 →\n  探测结果稳定 `prompt_only`\n- GLM 端点（`maas-coding-api.cn-huabei-1.xf-yun.com/v2`，model=`xopglm5`）：网关接受但模型输出漂移，探测结果 `prompt_only`\n- OpenAI 官方：探测结果 `json_schema`\n\n**升级后自动探测**：旧版本用户配置无 `response_format_mode` 字段。程序启动后若检测到该字段缺失，后台自动触发一次探测写入配置，不阻塞启动。\n\n**手动覆盖**：关闭程序后手动编辑 `config/user-config.json` 的 `lightrag_llm.litellm_kwargs.response_format_mode`。下次设置窗口测试保存会覆盖手动值。\n\n**注意**：\n- 探测调用会消耗约 100-200 token（最坏情况测到 Tier 2）。仅\"测试连接并保存\"按钮触发，不引入后台定时探测（升级后首次启动除外）。\n- 探测独立于启动时的 LLM 连通性测试（`/api/test-llm`），不影响启动速度。\n\n> **重要**：LightRAG 的 keyword_extraction 依赖 `response_format`，必须使用标准端点。如果误用 Coding Plan 端点，本次升级后的\"格式化输出能力自动探测\"会识别为 `prompt_only` 档位并写入配置，运行时 LightRAG 直接走 prompt-only 路径（不再每次发无效请求触发 400 后 fallback）。详见上方\"格式化输出（response_format）能力自动探测\"小节。\n\n**火山方舟深度思考模型 + 工具调用配置**（重要）：\n\n火山方舟的 `doubao-seed` 系列模型（包括 `ark-code-latest`）默认启用深度思考模式。当 `litellm_kwargs` 中未显式传递 `thinking` 参数时，API 没有结构化工具调用保障——模型偶发将 tool_call 放入 `reasoning_content` 的 `<seed:tool_call>` XML 格式，而非标准的 `tool_calls` 字段，导致工具调用丢失。\n\n**主 Agent 必须配置**：\n```json\n\"llm\": {\n  ...\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n| `thinking` 值 | 效果 | 适用场景 |\n|---------------|------|----------|\n| `{\"type\": \"enabled\"}` | 显式启用深度思考，API 网关保障 tool_call 走标准通道 | **主 Agent（必须）** |\n| `{\"type\": \"disabled\"}` | 禁用深度思考 | LightRAG 入库（需配合 `response_format`） |\n| `{\"type\": \"auto\"}` | 模型自行决定 | 不推荐（行为不确定） |\n| 不传 | 模型默认启用思考，但无 tool_call 保障 | **危险：工具调用可能丢失** |\n\n> **注意**：`thinking` 参数通过 `litellm_kwargs` 原样透传给 LiteLLM，再由 VolcEngine 适配器转为 API 请求的 `extra_body.thinking` 字段。代码不做任何厂商判断，所有厂商特有参数都走这个透传通道。\n\n**模型名格式差异**：\n\n两种端点的模型池相同，但模型名格式不同：\n\n| 端点 | 模型名格式 | 示例 |\n|------|-----------|------|\n| 标准端点 | 带日期后缀的全名 | `doubao-seed-2-0-pro-260215` |\n| Coding Plan | 简短别名 | `doubao-seed-2.0-pro` |\n\n> **注意**：在标准端点上使用 Coding Plan 的简短别名会返回 404；反之，在 Coding Plan 端点上两种格式都能用。\n\n**LiteLLM 路由配置**：\n\n使用 LiteLLM 调用火山方舟模型时，必须通过 `provider: \"volcengine\"` 走 VolcEngine 适配器路由。这是 LiteLLM 的标准机制：\n\n| 配置方式 | 路由 | 结果 |\n|----------|------|------|\n| `provider: \"volcengine\"` + `model: \"doubao-seed-2.0-pro\"` | VolcEngine 适配器 | 正确：`thinking` 参数自动处理，厂商特有参数通过 `litellm_kwargs` 透传 |\n| `model: \"volcengine/doubao-seed-2.0-pro\"`（无 provider） | VolcEngine 适配器 | 也可：LiteLLM 通过前缀推断路由，但不如 `provider` 显式 |\n| `model: \"doubao-seed-2.0-pro\"`（无 provider 无前缀） | OpenAI 适配器 | **错误**：`thinking` 等火山特有参数无法传递 |\n\n> **注意**：`type: \"openai\"` 是系统内部参数（区分 Anthropic/OpenAI 格式转换），不是 LiteLLM 的 `custom_llm_provider`。两者独立：`type` 控制格式，`provider` 控制路由。\n\n**可用模型**：doubao-seed-2.0-code、doubao-seed-2.0-pro、doubao-seed-2.0-lite、minimax-m2.7、minimax-m3、glm-5.1、kimi-k2.6、deepseek-v4-pro、deepseek-v4-flash、ark-code-latest\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-seed-2.0-pro`（Coding Plan 别名）或 `doubao-seed-2-0-pro-260215`（标准端点全名） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `provider` | LiteLLM 路由参数，同 `llm` 段说明。火山引擎填 `\"volcengine\"` | `\"\"` 或 `\"volcengine\"` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n| `temperature` | LLM 采样温度。0.0 完全确定性，1.0 高随机度。为空时由系统兜底 0.2 | `0.2`（实体/关系抽取建议低温度避免 JSON 漂移） |\n| `litellm_kwargs` | 厂商特有参数，同 `llm` 段说明。火山引擎知识图谱需传 `thinking` 和 `allowed_openai_params` | `{}` 或见配置示例 |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n> **温度值说明**：LightRAG 调 LLM 时如果不配 `temperature` 字段，系统兜底默认 `0.2`。这是为实体抽取、关系抽取等结构化任务优化的低温度值，避免高随机度导致 JSON 格式漂移、实体名不一致。如果需要更稳定的输出可设 `0.0`，需要更多创造性可设 `0.5~0.7`，但不建议超过 `1.0`。主 Agent / 子 Agent 的温度值在提示词文档里独立配置（主 Agent 0.6、子 Agent 多数 0.2），与此处的 `lightrag_llm.temperature` 完全独立，互不影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用 | 建议初始使用时，根据模型情况自己测试后确定 |\n| `low` | 浅层推理 | 模型推理速度极慢时，可选用 |\n| `medium` | 中等推理 | 非入库的图谱查询任务；部分模型入库也可用 |\n| `high` | 深度推理 | 建议用于入库（推理预算耗尽，输出质量高） |\n| `xhigh` | 最深推理 | 不建议用于入库 |\n\n**reasoning_effort 配置与测试指南**：\n\n`reasoning_effort` 的最优值与模型基础能力强相关，不存在通用最优值。实测数据（ark-code-latest 模型入库 SYSTEM_MANUAL.md）：\n\n| 配置 | 实体类型准确率 | 空响应率 | 补充提取有效性 | 综合评分 |\n|------|--------------|---------|--------------|---------|\n| `none` | 67% | 60% | 无 | 5.5/10 |\n| `low` | 95% | 40% | 有效 | **7.5/10** |\n| `medium` | 14% | 40% | 部分 | 6.0/10 |\n| `high` | 分裂 | 40% | 无 | 4.0/10 |\n\n关键发现：\n1. **推理越深不一定越好**：推理token被模型内部消耗，不转化为输出质量。过度推理反而导致实体类型误分类（如子Agent被归为organization而非technology）\n2. **补充提取受影响**：高推理级别下模型过度自信，判断\"无需补充\"，导致遗漏无法弥补\n3. **不同模型差异很大**：能力强的模型（如 Claude、GPT-4o）在 `none` 或 `low` 即可高质量提取；能力有限的模型可能需要 `high`，但也可能适得其反\n\n**换模型后必须实测**：更改模型或 reasoning_effort 后，用同一文档入库并检查日志验证效果。\n\n**入库质量检查方法**：\n1. 入库后检查日志目录 `logs/raw_http/YYYYMMDD/`，读取 `*_response.json` 文件\n2. 检查空响应：响应体仅含 `<|COMPLETE|>` 或 content 为空，说明该轮提取失败\n3. 检查实体类型：子Agent应为 technology 而非 person/organization；MCP服务器应为 technology 而非 organization\n4. 检查违规节点：不应出现与 niu 根节点重名的实体\n5. 检查补充提取：`*_response.json` 中补充提取应有实质内容（非仅 `<|COMPLETE|>`）\n6. 如发现问题，调整 reasoning_effort 重新入库测试\n\n**配置示例**：\n\n主 Agent 用火山方舟 Coding Plan（完整配置）：\n```json\n\"llm\": {\n  \"presetId\": \"ark-code-latest\",\n  \"apiKey\": \"你的API Key\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/coding/v3\",\n  \"model\": \"ark-code-latest\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"\",\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3\",\n  \"model\": \"doubao-seed-2-0-pro-260215\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"disabled\"},\n    \"allowed_openai_params\": [\"response_format\"]\n  }\n}\n```\n\n> **注意**：LightRAG 必须使用标准端点（apiBase 含 /api/v3），不能用 Coding Plan 端点（/api/coding/v3），因为 Coding Plan 网关 400 拒绝 response_format。设置窗口\"测试连接并保存\"会自动探测并写入 `response_format_mode=prompt_only`（豆包 Coding Plan 场景）。model 必须用标准端点的全名格式（带日期后缀）。\n> **LiteLLM 路由**：`provider: \"volcengine\"` 让 LiteLLM 走 VolcEngine 适配器。`litellm_kwargs` 中的 `thinking: {\"type\": \"disabled\"}` 关闭思考链（火山要求使用 response_format 时必须关闭），`allowed_openai_params: [\"response_format\"]` 让 VolcEngine 适配器透传 response_format 参数。\n\n场景二：主 Agent 和 LightRAG 用同一模型，独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n场景三：能力强的模型，禁用思考链即可（如 Claude、GPT-4o）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"none\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 上下文配置\n\n**配置文件**：`config/user-config.json` 中的 `context` 段\n\n```json\n{\n  \"context\": {\n    \"contextWindowSize\": 200000,\n    \"warningThreshold\": 0.8,\n    \"targetThreshold\": 0.5,\n    \"sleepTriggerMinutes\": 5\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 默认值 | 范围 |\n|------|------|--------|------|\n| `contextWindowSize` | 模型上下文窗口大小（tokens） | 200000 | 32000 ~ 2000000 |\n| `warningThreshold` | 溢出警告阈值，上下文使用率超过此值触发压缩 | 0.8 | 0.0 ~ 1.0 |\n| `targetThreshold` | 强制压缩目标，压缩后上下文使用率降至此值 | 0.5 | 0.0 ~ 1.0 |\n| `sleepTriggerMinutes` | 空闲多久后触发睡眠整理（分钟） | 5 | > 0 |\n\n**常见模型的 contextWindowSize**：\n\n| 模型 | 上下文窗口 | 配置值 |\n|------|-----------|--------|\n| GPT-4o-mini | 128K | 128000 |\n| GPT-4o | 128K | 128000 |\n| Claude 3.5 Sonnet | 200K | 200000 |\n| DeepSeek V3 (deepseek-chat) | 64K | 64000 |\n| DeepSeek R1 (deepseek-reasoner) | 128K | 128000 |\n| Qwen2.5-Turbo | 1M | 1000000 |\n| 本地 Ollama 模型 | 取决于模型 | 按实际配置 |\n\n> **注意**：`contextWindowSize` 与模型强相关，切换模型后需同步更新此值。设置窗口主界面可直接配置此值，高级选项中可配置溢出阈值等参数。\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出，`contextWindowSize` 在主界面，阈值参数点\"高级选项\"展开）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.4 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.5 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.5 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Excel | .xlsx | 支持 |\n| PowerPoint | .pptx | 支持 |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| HTML | .html | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.6 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 10 条（1 条工作便签 + 9 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（知识图谱 LightRAG）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索 + 知识图谱关联，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.7 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下一轮对话起不再出现首次使用提示（memory.json 每轮重读，写入后立即生效）\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.8 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n### 1.9 日志配置\n\n**配置文件**：`~/.niu/config/user-config.json`（首次启动从 bundle 内 `config/user-config.json` 模板复制）\n\n**配置字段**：\n\n````json\n{\n  \"logging\": {\n    \"enabled\": false,\n    \"level\": \"INFO\"\n  }\n}\n````\n\n| 字段 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `enabled` | bool | `false` | 日志总开关。`false` 时所有日志输出关闭（见下表），`true` 时按 `level` 输出 |\n| `level` | string | `\"INFO\"` | 日志级别：`DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL` |\n\n**关闭日志时（`enabled=false`，缺省）受控的日志源**：\n\n| 日志源 | 文件路径 | 控制方式 |\n|--------|----------|----------|\n| Python loguru sink | stderr | `logger.disable(\"\")` 全局禁用 |\n| Python stdlib logging | stderr | `logging.disable(CRITICAL)` 禁用 10+ 处散落 logger |\n| uvicorn 访问日志 | stderr | `log_level=\"critical\"` + `access_log=False` |\n| raw_http transport 层日志 | `~/.niu/logs/raw_http/YYYYMMDD/NNNNNN.json` | `install_http_logger()` 不 patch HTTP client + 幂等守卫 |\n| raw_http 应用层日志 | `~/.niu/logs/raw_http/YYYYMMDD/NNNNNN_request.json` + `_response.json` | `_write_raw_log()` 静默跳过 |\n| LLM interaction 可读日志 | `~/.niu/logs/llm_interaction_YYYYMMDD.log` | `_write_interaction_log()` 静默跳过 |\n| 飞书 adapter stderr | `~/.niu/logs/im_adapter_stderr.log` | `subprocess.DEVNULL` 代替文件重定向 |\n| /http-log/ HTTP 日志查看服务 | http://localhost:9876/http-log/ | router 不挂载（返回 404） |\n| Rust tracing | stderr | `tracing_subscriber` 不 init（tracing 调用静默丢弃） |\n\n**不受日志开关控制的诊断日志**（关键诊断必须保留）：\n\n| 日志源 | 文件路径 | 用途 |\n|--------|----------|------|\n| launcher 致命错误 | `~/.niu/logs/launcher_error.log` | 启动失败诊断（API 未运行、Electron 启动失败等），用 `time` crate 格式化时间戳 |\n| gateway 致命错误 | `~/.niu/logs/gateway_error.log` | 飞书 adapter 启动失败诊断（app_id 配错、端口占用、credentials 缺失） |\n\n\n**日志目录**：\n\n所有运行时日志统一写入 `~/.niu/logs/`（macOS/Linux）或 `%USERPROFILE%\\.niu\\logs\\`（Windows），不在 bundle 内（macOS Gatekeeper 禁止运行时改 bundle 内文件）。\n\n**Windows 控制台窗口**：\n\nWindows release build 下，niu.exe 编译为 GUI 子系统（`#![cfg_attr(all(target_os=\"windows\", not(debug_assertions)), windows_subsystem=\"windows\")]`），双击不弹 cmd 窗口。debug build 保留 console 方便调试。\n\n**macOS 控制台窗口**：\n\nmacOS 下构造 `niu.app` bundle（`Info.plist` 含 `LSUIElement=true`），Finder 双击不弹 Terminal。命令行 `./niu` 裸二进制仍保留供开发调试。\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "3c2d22d097211a546b706acfbb6e44fe76c79210": {"t": 1785764504.7128422, "n": 20765, "h": "355d398e8162501c", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nRust 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"\",\n    \"litellm_kwargs\": {}\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"none\",\n    \"litellm_kwargs\": {}\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点基础地址（不含路径后缀，LiteLLM 会自动追加：openai 类型追加 `/chat/completions`，anthropic 类型追加 `/v1/messages`） |\n| `model` | 模型名称 |\n| `type` | 系统内部参数，用于区分 API 格式转换和认证方式：`openai`（OpenAI 兼容格式）或 `anthropic`（Anthropic 原生格式）。**不是** LiteLLM 的 custom_llm_provider |\n| `provider` | LiteLLM 路由参数，映射为 `custom_llm_provider`。常见值：`\"\"`（空，默认由 type 决定）、`\"volcengine\"`（火山引擎）。填写后模型名无需加厂商前缀 |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"`。**注意**：该参数的实际效果与模型基础能力强相关，不同模型的最优值差异很大，需实测确定（详见下方\"reasoning_effort 配置与测试指南\"） |\n| `litellm_kwargs` | 厂商特有参数，JSON 对象格式，原样透传给 LiteLLM。用于传递各厂商 SDK 要求的额外参数（如火山引擎的 `thinking`、`allowed_openai_params` 等）。代码不做任何厂商判断，只负责透传 |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**火山方舟(Ark)端点配置说明**\n\n火山方舟提供两种计费端点，模型池相同，但功能权限有差异：\n\n| 端点 | 地址 | 计费 | response_format | 适用场景 |\n|------|------|------|-----------------|----------|\n| 标准端点 | `https://ark.cn-beijing.volces.com/api/v3` | 按量计费 | 支持 | 主 Agent、LightRAG |\n| Coding Plan | `https://ark.cn-beijing.volces.com/api/coding/v3` | 包月计费 | **不支持**（网关 400 拒绝） | 主 Agent |\n\n**格式化输出（response_format）能力自动探测**\n\n设置窗口\"测试连接并保存\"按钮在测试通过后，会自动追加一次格式化输出能力探测，按 3 档递进调用真实 LLM，找出当前配置支持的最强档位：\n\n| 档位 | response_format.type | 约束 | 典型支持厂商 |\n|------|---------------------|------|--------------|\n| Tier 1（最强） | `json_schema` strict | 输出严格匹配 schema | OpenAI 真正支持 |\n| Tier 2（中等） | `json_object` | 输出合法 JSON，不约束字段 | OpenAI、DeepSeek |\n| Tier 3（最弱） | 无 response_format | prompt + `json_repair` 客户端容错 | 所有厂商兜底 |\n\n**探测流程**：从 Tier 1 开始测，失败则降级测 Tier 2，再失败则定为 Tier 3。每档失败条件：\n- `model_rejected`：LiteLLM 抛 `BadRequestError`/`UnsupportedParamsError`（模型/网关 4xx 拒绝，如豆包 Coding Plan）\n- `gateway_blocked`：网关返回 200 但响应非合法 JSON（网关接受参数但模型输出漂移，如 GLM xopglm5）\n\n探测采用三次采样 + 冲突式设计：\n- 三次采样全过才升档，任何一次失败立即降级——防 flaky 网关（豆包 Coding\n  Plan 2026-07-21 实测：同一请求 5 次采样 2 次执行、3 次静默忽略）碰巧\n  命中执行窗口期误判支持\n- 冲突式设计：schema 强制要求 `{\"verdict\": \"SCHEMA_ENFORCED\"}`，prompt\n  却要求模型写普通英文句子且禁止输出 JSON——只有 schema 战胜 prompt\n  （输出被强制为 schema JSON）才判定真支持，模型跟随 prompt 输出普通\n  文本即判定网关静默忽略\n- 限流单独处理：RateLimitError 不计失败，sleep 后重试本次采样（指数\n  退避 5s→10s→20s→40s→80s，最多 5 次），直到返回非限流结果才判定\n\n**写入配置**：\n- `lightrag_llm.litellm_kwargs.response_format_mode`：`\"json_schema\"` / `\"json_object\"` / `\"prompt_only\"`\n- `lightrag_llm.litellm_kwargs.allowed_openai_params`：前两档 `[\"response_format\"]`，prompt_only 档 `[]`（双写兼容旧逻辑）\n\n**典型场景**（2026-07-19 实测）：\n- 豆包 Coding Plan 端点（`/api/coding/v3`，model=`ark-code-latest`）：\n  网关行为非确定性（flaky），同一请求多次采样结果不稳定（有时执行\n  json_schema strict、有时静默忽略），三次采样必然 ≥1 次静默忽略 →\n  探测结果稳定 `prompt_only`\n- GLM 端点（`maas-coding-api.cn-huabei-1.xf-yun.com/v2`，model=`xopglm5`）：网关接受但模型输出漂移，探测结果 `prompt_only`\n- OpenAI 官方：探测结果 `json_schema`\n\n**升级后自动探测**：旧版本用户配置无 `response_format_mode` 字段。程序启动后若检测到该字段缺失，后台自动触发一次探测写入配置，不阻塞启动。\n\n**手动覆盖**：关闭程序后手动编辑 `config/user-config.json` 的 `lightrag_llm.litellm_kwargs.response_format_mode`。下次设置窗口测试保存会覆盖手动值。\n\n**注意**：\n- 探测调用会消耗约 100-200 token（最坏情况测到 Tier 2）。仅\"测试连接并保存\"按钮触发，不引入后台定时探测（升级后首次启动除外）。\n- 探测独立于启动时的 LLM 连通性测试（`/api/test-llm`），不影响启动速度。\n\n> **重要**：LightRAG 的 keyword_extraction 依赖 `response_format`，必须使用标准端点。如果误用 Coding Plan 端点，本次升级后的\"格式化输出能力自动探测\"会识别为 `prompt_only` 档位并写入配置，运行时 LightRAG 直接走 prompt-only 路径（不再每次发无效请求触发 400 后 fallback）。详见上方\"格式化输出（response_format）能力自动探测\"小节。\n\n**火山方舟深度思考模型 + 工具调用配置**（重要）：\n\n火山方舟的 `doubao-seed` 系列模型（包括 `ark-code-latest`）默认启用深度思考模式。当 `litellm_kwargs` 中未显式传递 `thinking` 参数时，API 没有结构化工具调用保障——模型偶发将 tool_call 放入 `reasoning_content` 的 `<seed:tool_call>` XML 格式，而非标准的 `tool_calls` 字段，导致工具调用丢失。\n\n**主 Agent 必须配置**：\n```json\n\"llm\": {\n  ...\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n| `thinking` 值 | 效果 | 适用场景 |\n|---------------|------|----------|\n| `{\"type\": \"enabled\"}` | 显式启用深度思考，API 网关保障 tool_call 走标准通道 | **主 Agent（必须）** |\n| `{\"type\": \"disabled\"}` | 禁用深度思考 | LightRAG 入库（需配合 `response_format`） |\n| `{\"type\": \"auto\"}` | 模型自行决定 | 不推荐（行为不确定） |\n| 不传 | 模型默认启用思考，但无 tool_call 保障 | **危险：工具调用可能丢失** |\n\n> **注意**：`thinking` 参数通过 `litellm_kwargs` 原样透传给 LiteLLM，再由 VolcEngine 适配器转为 API 请求的 `extra_body.thinking` 字段。代码不做任何厂商判断，所有厂商特有参数都走这个透传通道。\n\n**模型名格式差异**：\n\n两种端点的模型池相同，但模型名格式不同：\n\n| 端点 | 模型名格式 | 示例 |\n|------|-----------|------|\n| 标准端点 | 带日期后缀的全名 | `doubao-seed-2-0-pro-260215` |\n| Coding Plan | 简短别名 | `doubao-seed-2.0-pro` |\n\n> **注意**：在标准端点上使用 Coding Plan 的简短别名会返回 404；反之，在 Coding Plan 端点上两种格式都能用。\n\n**LiteLLM 路由配置**：\n\n使用 LiteLLM 调用火山方舟模型时，必须通过 `provider: \"volcengine\"` 走 VolcEngine 适配器路由。这是 LiteLLM 的标准机制：\n\n| 配置方式 | 路由 | 结果 |\n|----------|------|------|\n| `provider: \"volcengine\"` + `model: \"doubao-seed-2.0-pro\"` | VolcEngine 适配器 | 正确：`thinking` 参数自动处理，厂商特有参数通过 `litellm_kwargs` 透传 |\n| `model: \"volcengine/doubao-seed-2.0-pro\"`（无 provider） | VolcEngine 适配器 | 也可：LiteLLM 通过前缀推断路由，但不如 `provider` 显式 |\n| `model: \"doubao-seed-2.0-pro\"`（无 provider 无前缀） | OpenAI 适配器 | **错误**：`thinking` 等火山特有参数无法传递 |\n\n> **注意**：`type: \"openai\"` 是系统内部参数（区分 Anthropic/OpenAI 格式转换），不是 LiteLLM 的 `custom_llm_provider`。两者独立：`type` 控制格式，`provider` 控制路由。\n\n**可用模型**：doubao-seed-2.0-code、doubao-seed-2.0-pro、doubao-seed-2.0-lite、minimax-m2.7、minimax-m3、glm-5.1、kimi-k2.6、deepseek-v4-pro、deepseek-v4-flash、ark-code-latest\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-seed-2.0-pro`（Coding Plan 别名）或 `doubao-seed-2-0-pro-260215`（标准端点全名） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `provider` | LiteLLM 路由参数，同 `llm` 段说明。火山引擎填 `\"volcengine\"` | `\"\"` 或 `\"volcengine\"` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n| `temperature` | LLM 采样温度。0.0 完全确定性，1.0 高随机度。为空时由系统兜底 0.2 | `0.2`（实体/关系抽取建议低温度避免 JSON 漂移） |\n| `litellm_kwargs` | 厂商特有参数，同 `llm` 段说明。火山引擎知识图谱需传 `thinking` 和 `allowed_openai_params` | `{}` 或见配置示例 |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n> **温度值说明**：LightRAG 调 LLM 时如果不配 `temperature` 字段，系统兜底默认 `0.2`。这是为实体抽取、关系抽取等结构化任务优化的低温度值，避免高随机度导致 JSON 格式漂移、实体名不一致。如果需要更稳定的输出可设 `0.0`，需要更多创造性可设 `0.5~0.7`，但不建议超过 `1.0`。主 Agent / 子 Agent 的温度值在提示词文档里独立配置（主 Agent 0.6、子 Agent 多数 0.2），与此处的 `lightrag_llm.temperature` 完全独立，互不影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用 | 建议初始使用时，根据模型情况自己测试后确定 |\n| `low` | 浅层推理 | 模型推理速度极慢时，可选用 |\n| `medium` | 中等推理 | 非入库的图谱查询任务；部分模型入库也可用 |\n| `high` | 深度推理 | 建议用于入库（推理预算耗尽，输出质量高） |\n| `xhigh` | 最深推理 | 不建议用于入库 |\n\n**reasoning_effort 配置与测试指南**：\n\n`reasoning_effort` 的最优值与模型基础能力强相关，不存在通用最优值。实测数据（ark-code-latest 模型入库 SYSTEM_MANUAL.md）：\n\n| 配置 | 实体类型准确率 | 空响应率 | 补充提取有效性 | 综合评分 |\n|------|--------------|---------|--------------|---------|\n| `none` | 67% | 60% | 无 | 5.5/10 |\n| `low` | 95% | 40% | 有效 | **7.5/10** |\n| `medium` | 14% | 40% | 部分 | 6.0/10 |\n| `high` | 分裂 | 40% | 无 | 4.0/10 |\n\n关键发现：\n1. **推理越深不一定越好**：推理token被模型内部消耗，不转化为输出质量。过度推理反而导致实体类型误分类（如子Agent被归为organization而非technology）\n2. **补充提取受影响**：高推理级别下模型过度自信，判断\"无需补充\"，导致遗漏无法弥补\n3. **不同模型差异很大**：能力强的模型（如 Claude、GPT-4o）在 `none` 或 `low` 即可高质量提取；能力有限的模型可能需要 `high`，但也可能适得其反\n\n**换模型后必须实测**：更改模型或 reasoning_effort 后，用同一文档入库并检查日志验证效果。\n\n**入库质量检查方法**：\n1. 入库后检查日志目录 `logs/raw_http/YYYYMMDD/`，读取 `*_response.json` 文件\n2. 检查空响应：响应体仅含 `<|COMPLETE|>` 或 content 为空，说明该轮提取失败\n3. 检查实体类型：子Agent应为 technology 而非 person/organization；MCP服务器应为 technology 而非 organization\n4. 检查违规节点：不应出现与 niu 根节点重名的实体\n5. 检查补充提取：`*_response.json` 中补充提取应有实质内容（非仅 `<|COMPLETE|>`）\n6. 如发现问题，调整 reasoning_effort 重新入库测试\n\n**配置示例**：\n\n主 Agent 用火山方舟 Coding Plan（完整配置）：\n```json\n\"llm\": {\n  \"presetId\": \"ark-code-latest\",\n  \"apiKey\": \"你的API Key\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/coding/v3\",\n  \"model\": \"ark-code-latest\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"\",\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3\",\n  \"model\": \"doubao-seed-2-0-pro-260215\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"disabled\"},\n    \"allowed_openai_params\": [\"response_format\"]\n  }\n}\n```\n\n> **注意**：LightRAG 必须使用标准端点（apiBase 含 /api/v3），不能用 Coding Plan 端点（/api/coding/v3），因为 Coding Plan 网关 400 拒绝 response_format。设置窗口\"测试连接并保存\"会自动探测并写入 `response_format_mode=prompt_only`（豆包 Coding Plan 场景）。model 必须用标准端点的全名格式（带日期后缀）。\n> **LiteLLM 路由**：`provider: \"volcengine\"` 让 LiteLLM 走 VolcEngine 适配器。`litellm_kwargs` 中的 `thinking: {\"type\": \"disabled\"}` 关闭思考链（火山要求使用 response_format 时必须关闭），`allowed_openai_params: [\"response_format\"]` 让 VolcEngine 适配器透传 response_format 参数。\n\n场景二：主 Agent 和 LightRAG 用同一模型，独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n场景三：能力强的模型，禁用思考链即可（如 Claude、GPT-4o）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"none\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 上下文配置\n\n**配置文件**：`config/user-config.json` 中的 `context` 段\n\n```json\n{\n  \"context\": {\n    \"contextWindowSize\": 200000,\n    \"warningThreshold\": 0.8,\n    \"targetThreshold\": 0.5,\n    \"sleepTriggerMinutes\": 5\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 默认值 | 范围 |\n|------|------|--------|------|\n| `contextWindowSize` | 模型上下文窗口大小（tokens） | 200000 | 32000 ~ 2000000 |\n| `warningThreshold` | 溢出警告阈值，上下文使用率超过此值触发压缩 | 0.8 | 0.0 ~ 1.0 |\n| `targetThreshold` | 强制压缩目标，压缩后上下文使用率降至此值 | 0.5 | 0.0 ~ 1.0 |\n| `sleepTriggerMinutes` | 空闲多久后触发睡眠整理（分钟） | 5 | > 0 |\n\n**常见模型的 contextWindowSize**：\n\n| 模型 | 上下文窗口 | 配置值 |\n|------|-----------|--------|\n| GPT-4o-mini | 128K | 128000 |\n| GPT-4o | 128K | 128000 |\n| Claude 3.5 Sonnet | 200K | 200000 |\n| DeepSeek V3 (deepseek-chat) | 64K | 64000 |\n| DeepSeek R1 (deepseek-reasoner) | 128K | 128000 |\n| Qwen2.5-Turbo | 1M | 1000000 |\n| 本地 Ollama 模型 | 取决于模型 | 按实际配置 |\n\n> **注意**：`contextWindowSize` 与模型强相关，切换模型后需同步更新此值。设置窗口主界面可直接配置此值，高级选项中可配置溢出阈值等参数。\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出，`contextWindowSize` 在主界面，阈值参数点\"高级选项\"展开）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.4 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.5 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.5 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Excel | .xlsx | 支持 |\n| PowerPoint | .pptx | 支持 |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| HTML | .html | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.6 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 10 条（1 条工作便签 + 9 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（知识图谱 LightRAG）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索 + 知识图谱关联，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.7 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下一轮对话起不再出现首次使用提示（memory.json 每轮重读，写入后立即生效）\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.8 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n### 1.9 日志配置\n\n**配置文件**：`~/.niu/config/user-config.json`（首次启动从 bundle 内 `config/user-config.json` 模板复制）\n\n**配置字段**：\n\n````json\n{\n  \"logging\": {\n    \"enabled\": false,\n    \"level\": \"INFO\"\n  }\n}\n````\n\n| 字段 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `enabled` | bool | `false` | 日志总开关。`false` 时所有日志输出关闭（见下表），`true` 时按 `level` 输出 |\n| `level` | string | `\"INFO\"` | 日志级别：`DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL` |\n\n**关闭日志时（`enabled=false`，缺省）受控的日志源**：\n\n| 日志源 | 文件路径 | 控制方式 |\n|--------|----------|----------|\n| Python loguru sink | stderr | `logger.disable(\"\")` 全局禁用 |\n| Python stdlib logging | stderr | `logging.disable(CRITICAL)` 禁用 10+ 处散落 logger |\n| uvicorn 访问日志 | stderr | `log_level=\"critical\"` + `access_log=False` |\n| raw_http transport 层日志 | `~/.niu/logs/raw_http/YYYYMMDD/NNNNNN.json` | `install_http_logger()` 不 patch HTTP client + 幂等守卫 |\n| raw_http 应用层日志 | `~/.niu/logs/raw_http/YYYYMMDD/NNNNNN_request.json` + `_response.json` | `_write_raw_log()` 静默跳过 |\n| LLM interaction 可读日志 | `~/.niu/logs/llm_interaction_YYYYMMDD.log` | `_write_interaction_log()` 静默跳过 |\n| 飞书 adapter stderr | `~/.niu/logs/im_adapter_stderr.log` | `subprocess.DEVNULL` 代替文件重定向 |\n| /http-log/ HTTP 日志查看服务 | http://localhost:9876/http-log/ | router 不挂载（返回 404） |\n| Rust tracing | stderr | `tracing_subscriber` 不 init（tracing 调用静默丢弃） |\n\n**不受日志开关控制的诊断日志**（关键诊断必须保留）：\n\n| 日志源 | 文件路径 | 用途 |\n|--------|----------|------|\n| launcher 致命错误 | `~/.niu/logs/launcher_error.log` | 启动失败诊断（API 未运行、Electron 启动失败等），用 `time` crate 格式化时间戳 |\n| gateway 致命错误 | `~/.niu/logs/gateway_error.log` | 飞书 adapter 启动失败诊断（app_id 配错、端口占用、credentials 缺失） |\n\n\n**日志目录**：\n\n所有运行时日志统一写入 `~/.niu/logs/`（macOS/Linux）或 `%USERPROFILE%\\.niu\\logs\\`（Windows），不在 bundle 内（macOS Gatekeeper 禁止运行时改 bundle 内文件）。\n\n**Windows 控制台窗口**：\n\nWindows release build 下，niu.exe 编译为 GUI 子系统（`#![cfg_attr(all(target_os=\"windows\", not(debug_assertions)), windows_subsystem=\"windows\")]`），双击不弹 cmd 窗口。debug build 保留 console 方便调试。\n\n**macOS 控制台窗口**：\n\nmacOS 下构造 `niu.app` bundle（`Info.plist` 含 `LSUIElement=true`），Finder 双击不弹 Terminal。命令行 `./niu` 裸二进制仍保留供开发调试。\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "0c589e072c87b5e29d39eb0f2ee587690e763f97": {"t": 1785764506.380731, "n": 20737, "h": "1c59e763d41bd81a", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nRust 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"\",\n    \"litellm_kwargs\": {}\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"none\",\n    \"litellm_kwargs\": {}\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点基础地址（不含路径后缀，LiteLLM 会自动追加：openai 类型追加 `/chat/completions`，anthropic 类型追加 `/v1/messages`） |\n| `model` | 模型名称 |\n| `type` | 系统内部参数，用于区分 API 格式转换和认证方式：`openai`（OpenAI 兼容格式）或 `anthropic`（Anthropic 原生格式）。**不是** LiteLLM 的 custom_llm_provider |\n| `provider` | LiteLLM 路由参数，映射为 `custom_llm_provider`。常见值：`\"\"`（空，默认由 type 决定）、`\"volcengine\"`（火山引擎）。填写后模型名无需加厂商前缀 |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"`。**注意**：该参数的实际效果与模型基础能力强相关，不同模型的最优值差异很大，需实测确定（详见下方\"reasoning_effort 配置与测试指南\"） |\n| `litellm_kwargs` | 厂商特有参数，JSON 对象格式，原样透传给 LiteLLM。用于传递各厂商 SDK 要求的额外参数（如火山引擎的 `thinking`、`allowed_openai_params` 等）。代码不做任何厂商判断，只负责透传 |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**火山方舟(Ark)端点配置说明**\n\n火山方舟提供两种计费端点，模型池相同，但功能权限有差异：\n\n| 端点 | 地址 | 计费 | response_format | 适用场景 |\n|------|------|------|-----------------|----------|\n| 标准端点 | `https://ark.cn-beijing.volces.com/api/v3` | 按量计费 | 支持 | 主 Agent、LightRAG |\n| Coding Plan | `https://ark.cn-beijing.volces.com/api/coding/v3` | 包月计费 | **不支持**（网关 400 拒绝） | 主 Agent |\n\n**格式化输出（response_format）能力自动探测**\n\n设置窗口\"测试连接并保存\"按钮在测试通过后，会自动追加一次格式化输出能力探测，按 3 档递进调用真实 LLM，找出当前配置支持的最强档位：\n\n| 档位 | response_format.type | 约束 | 典型支持厂商 |\n|------|---------------------|------|--------------|\n| Tier 1（最强） | `json_schema` strict | 输出严格匹配 schema | OpenAI 真正支持 |\n| Tier 2（中等） | `json_object` | 输出合法 JSON，不约束字段 | OpenAI、DeepSeek |\n| Tier 3（最弱） | 无 response_format | prompt + `json_repair` 客户端容错 | 所有厂商兜底 |\n\n**探测流程**：从 Tier 1 开始测，失败则降级测 Tier 2，再失败则定为 Tier 3。每档失败条件：\n- `model_rejected`：LiteLLM 抛 `BadRequestError`/`UnsupportedParamsError`（模型/网关 4xx 拒绝，如豆包 Coding Plan）\n- `gateway_blocked`：网关返回 200 但响应非合法 JSON（网关接受参数但模型输出漂移，如 GLM xopglm5）\n\n探测采用三次采样 + 冲突式设计：\n- 三次采样全过才升档，任何一次失败立即降级——防 flaky 网关（豆包 Coding\n  Plan 2026-07-21 实测：同一请求 5 次采样 2 次执行、3 次静默忽略）碰巧\n  命中执行窗口期误判支持\n- 冲突式设计：schema 强制要求 `{\"verdict\": \"SCHEMA_ENFORCED\"}`，prompt\n  却要求模型写普通英文句子且禁止输出 JSON——只有 schema 战胜 prompt\n  （输出被强制为 schema JSON）才判定真支持，模型跟随 prompt 输出普通\n  文本即判定网关静默忽略\n- 限流单独处理：RateLimitError 不计失败，sleep 后重试本次采样（指数\n  退避 5s→10s→20s→40s→80s，最多 5 次），直到返回非限流结果才判定\n\n**写入配置**：\n- `lightrag_llm.litellm_kwargs.response_format_mode`：`\"json_schema\"` / `\"json_object\"` / `\"prompt_only\"`\n- `lightrag_llm.litellm_kwargs.allowed_openai_params`：前两档 `[\"response_format\"]`，prompt_only 档 `[]`（双写兼容旧逻辑）\n\n**典型场景**（2026-07-19 实测）：\n- 豆包 Coding Plan 端点（`/api/coding/v3`，model=`ark-code-latest`）：\n  网关行为非确定性（flaky），同一请求多次采样结果不稳定（有时执行\n  json_schema strict、有时静默忽略），三次采样必然 ≥1 次静默忽略 →\n  探测结果稳定 `prompt_only`\n- GLM 端点（`maas-coding-api.cn-huabei-1.xf-yun.com/v2`，model=`xopglm5`）：网关接受但模型输出漂移，探测结果 `prompt_only`\n- OpenAI 官方：探测结果 `json_schema`\n\n**升级后自动探测**：旧版本用户配置无 `response_format_mode` 字段。程序启动后若检测到该字段缺失，后台自动触发一次探测写入配置，不阻塞启动。\n\n**手动覆盖**：关闭程序后手动编辑 `config/user-config.json` 的 `lightrag_llm.litellm_kwargs.response_format_mode`。下次设置窗口测试保存会覆盖手动值。\n\n**注意**：\n- 探测调用会消耗约 100-200 token（最坏情况测到 Tier 2）。仅\"测试连接并保存\"按钮触发，不引入后台定时探测（升级后首次启动除外）。\n- 探测独立于启动时的 LLM 连通性测试（`/api/test-llm`），不影响启动速度。\n\n> **重要**：LightRAG 的 keyword_extraction 依赖 `response_format`，必须使用标准端点。如果误用 Coding Plan 端点，本次升级后的\"格式化输出能力自动探测\"会识别为 `prompt_only` 档位并写入配置，运行时 LightRAG 直接走 prompt-only 路径（不再每次发无效请求触发 400 后 fallback）。详见上方\"格式化输出（response_format）能力自动探测\"小节。\n\n**火山方舟深度思考模型 + 工具调用配置**（重要）：\n\n火山方舟的 `doubao-seed` 系列模型（包括 `ark-code-latest`）默认启用深度思考模式。当 `litellm_kwargs` 中未显式传递 `thinking` 参数时，API 没有结构化工具调用保障——模型偶发将 tool_call 放入 `reasoning_content` 的 `<seed:tool_call>` XML 格式，而非标准的 `tool_calls` 字段，导致工具调用丢失。\n\n**主 Agent 必须配置**：\n```json\n\"llm\": {\n  ...\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n| `thinking` 值 | 效果 | 适用场景 |\n|---------------|------|----------|\n| `{\"type\": \"enabled\"}` | 显式启用深度思考，API 网关保障 tool_call 走标准通道 | **主 Agent（必须）** |\n| `{\"type\": \"disabled\"}` | 禁用深度思考 | LightRAG 入库（需配合 `response_format`） |\n| `{\"type\": \"auto\"}` | 模型自行决定 | 不推荐（行为不确定） |\n| 不传 | 模型默认启用思考，但无 tool_call 保障 | **危险：工具调用可能丢失** |\n\n> **注意**：`thinking` 参数通过 `litellm_kwargs` 原样透传给 LiteLLM，再由 VolcEngine 适配器转为 API 请求的 `extra_body.thinking` 字段。代码不做任何厂商判断，所有厂商特有参数都走这个透传通道。\n\n**模型名格式差异**：\n\n两种端点的模型池相同，但模型名格式不同：\n\n| 端点 | 模型名格式 | 示例 |\n|------|-----------|------|\n| 标准端点 | 带日期后缀的全名 | `doubao-seed-2-0-pro-260215` |\n| Coding Plan | 简短别名 | `doubao-seed-2.0-pro` |\n\n> **注意**：在标准端点上使用 Coding Plan 的简短别名会返回 404；反之，在 Coding Plan 端点上两种格式都能用。\n\n**LiteLLM 路由配置**：\n\n使用 LiteLLM 调用火山方舟模型时，必须通过 `provider: \"volcengine\"` 走 VolcEngine 适配器路由。这是 LiteLLM 的标准机制：\n\n| 配置方式 | 路由 | 结果 |\n|----------|------|------|\n| `provider: \"volcengine\"` + `model: \"doubao-seed-2.0-pro\"` | VolcEngine 适配器 | 正确：`thinking` 参数自动处理，厂商特有参数通过 `litellm_kwargs` 透传 |\n| `model: \"volcengine/doubao-seed-2.0-pro\"`（无 provider） | VolcEngine 适配器 | 也可：LiteLLM 通过前缀推断路由，但不如 `provider` 显式 |\n| `model: \"doubao-seed-2.0-pro\"`（无 provider 无前缀） | OpenAI 适配器 | **错误**：`thinking` 等火山特有参数无法传递 |\n\n> **注意**：`type: \"openai\"` 是系统内部参数（区分 Anthropic/OpenAI 格式转换），不是 LiteLLM 的 `custom_llm_provider`。两者独立：`type` 控制格式，`provider` 控制路由。\n\n**可用模型**：doubao-seed-2.0-code、doubao-seed-2.0-pro、doubao-seed-2.0-lite、minimax-m2.7、minimax-m3、glm-5.1、kimi-k2.6、deepseek-v4-pro、deepseek-v4-flash、ark-code-latest\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-seed-2.0-pro`（Coding Plan 别名）或 `doubao-seed-2-0-pro-260215`（标准端点全名） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `provider` | LiteLLM 路由参数，同 `llm` 段说明。火山引擎填 `\"volcengine\"` | `\"\"` 或 `\"volcengine\"` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n| `temperature` | LLM 采样温度。0.0 完全确定性，1.0 高随机度。为空时由系统兜底 0.2 | `0.2`（实体/关系抽取建议低温度避免 JSON 漂移） |\n| `litellm_kwargs` | 厂商特有参数，同 `llm` 段说明。火山引擎知识图谱需传 `thinking` 和 `allowed_openai_params` | `{}` 或见配置示例 |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n> **温度值说明**：LightRAG 调 LLM 时如果不配 `temperature` 字段，系统兜底默认 `0.2`。这是为实体抽取、关系抽取等结构化任务优化的低温度值，避免高随机度导致 JSON 格式漂移、实体名不一致。如果需要更稳定的输出可设 `0.0`，需要更多创造性可设 `0.5~0.7`，但不建议超过 `1.0`。主 Agent / 子 Agent 的温度值在提示词文档里独立配置（主 Agent 0.6、子 Agent 多数 0.2），与此处的 `lightrag_llm.temperature` 完全独立，互不影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用 | 建议初始使用时，根据模型情况自己测试后确定 |\n| `low` | 浅层推理 | 模型推理速度极慢时，可选用 |\n| `medium` | 中等推理 | 非入库的图谱查询任务；部分模型入库也可用 |\n| `high` | 深度推理 | 建议用于入库（推理预算耗尽，输出质量高） |\n| `xhigh` | 最深推理 | 不建议用于入库 |\n\n**reasoning_effort 配置与测试指南**：\n\n`reasoning_effort` 的最优值与模型基础能力强相关，不存在通用最优值。实测数据（ark-code-latest 模型入库 SYSTEM_MANUAL.md）：\n\n| 配置 | 实体类型准确率 | 空响应率 | 补充提取有效性 | 综合评分 |\n|------|--------------|---------|--------------|---------|\n| `none` | 67% | 60% | 无 | 5.5/10 |\n| `low` | 95% | 40% | 有效 | **7.5/10** |\n| `medium` | 14% | 40% | 部分 | 6.0/10 |\n| `high` | 分裂 | 40% | 无 | 4.0/10 |\n\n关键发现：\n1. **推理越深不一定越好**：推理token被模型内部消耗，不转化为输出质量。过度推理反而导致实体类型误分类（如子Agent被归为organization而非technology）\n2. **补充提取受影响**：高推理级别下模型过度自信，判断\"无需补充\"，导致遗漏无法弥补\n3. **不同模型差异很大**：能力强的模型（如 Claude、GPT-4o）在 `none` 或 `low` 即可高质量提取；能力有限的模型可能需要 `high`，但也可能适得其反\n\n**换模型后必须实测**：更改模型或 reasoning_effort 后，用同一文档入库并检查日志验证效果。\n\n**入库质量检查方法**：\n1. 入库后检查日志目录 `logs/raw_http/YYYYMMDD/`，读取 `*_response.json` 文件\n2. 检查空响应：响应体仅含 `<|COMPLETE|>` 或 content 为空，说明该轮提取失败\n3. 检查实体类型：子Agent应为 technology 而非 person/organization；MCP服务器应为 technology 而非 organization\n4. 检查违规节点：不应出现与 niu 根节点重名的实体\n5. 检查补充提取：`*_response.json` 中补充提取应有实质内容（非仅 `<|COMPLETE|>`）\n6. 如发现问题，调整 reasoning_effort 重新入库测试\n\n**配置示例**：\n\n主 Agent 用火山方舟 Coding Plan（完整配置）：\n```json\n\"llm\": {\n  \"presetId\": \"ark-code-latest\",\n  \"apiKey\": \"你的API Key\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/coding/v3\",\n  \"model\": \"ark-code-latest\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"\",\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3\",\n  \"model\": \"doubao-seed-2-0-pro-260215\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"disabled\"},\n    \"allowed_openai_params\": [\"response_format\"]\n  }\n}\n```\n\n> **注意**：LightRAG 必须使用标准端点（apiBase 含 /api/v3），不能用 Coding Plan 端点（/api/coding/v3），因为 Coding Plan 网关 400 拒绝 response_format。设置窗口\"测试连接并保存\"会自动探测并写入 `response_format_mode=prompt_only`（豆包 Coding Plan 场景）。model 必须用标准端点的全名格式（带日期后缀）。\n> **LiteLLM 路由**：`provider: \"volcengine\"` 让 LiteLLM 走 VolcEngine 适配器。`litellm_kwargs` 中的 `thinking: {\"type\": \"disabled\"}` 关闭思考链（火山要求使用 response_format 时必须关闭），`allowed_openai_params: [\"response_format\"]` 让 VolcEngine 适配器透传 response_format 参数。\n\n场景二：主 Agent 和 LightRAG 用同一模型，独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n场景三：能力强的模型，禁用思考链即可（如 Claude、GPT-4o）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"none\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 上下文配置\n\n**配置文件**：`config/user-config.json` 中的 `context` 段\n\n```json\n{\n  \"context\": {\n    \"contextWindowSize\": 200000,\n    \"warningThreshold\": 0.8,\n    \"targetThreshold\": 0.5,\n    \"sleepTriggerMinutes\": 5\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 默认值 | 范围 |\n|------|------|--------|------|\n| `contextWindowSize` | 模型上下文窗口大小（tokens） | 200000 | 32000 ~ 2000000 |\n| `warningThreshold` | 溢出警告阈值，上下文使用率超过此值触发压缩 | 0.8 | 0.0 ~ 1.0 |\n| `targetThreshold` | 强制压缩目标，压缩后上下文使用率降至此值 | 0.5 | 0.0 ~ 1.0 |\n| `sleepTriggerMinutes` | 空闲多久后触发睡眠整理（分钟） | 5 | > 0 |\n\n**常见模型的 contextWindowSize**：\n\n| 模型 | 上下文窗口 | 配置值 |\n|------|-----------|--------|\n| GPT-4o-mini | 128K | 128000 |\n| GPT-4o | 128K | 128000 |\n| Claude 3.5 Sonnet | 200K | 200000 |\n| DeepSeek V3 (deepseek-chat) | 64K | 64000 |\n| DeepSeek R1 (deepseek-reasoner) | 128K | 128000 |\n| Qwen2.5-Turbo | 1M | 1000000 |\n| 本地 Ollama 模型 | 取决于模型 | 按实际配置 |\n\n> **注意**：`contextWindowSize` 与模型强相关，切换模型后需同步更新此值。设置窗口主界面可直接配置此值，高级选项中可配置溢出阈值等参数。\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出，`contextWindowSize` 在主界面，阈值参数点\"高级选项\"展开）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.4 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.5 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.5 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Excel | .xlsx | 支持 |\n| PowerPoint | .pptx | 支持 |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| HTML | .html | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.6 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 10 条（1 条工作便签 + 9 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（知识图谱 LightRAG）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索 + 知识图谱关联，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.7 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.8 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n### 1.9 日志配置\n\n**配置文件**：`~/.niu/config/user-config.json`（首次启动从 bundle 内 `config/user-config.json` 模板复制）\n\n**配置字段**：\n\n````json\n{\n  \"logging\": {\n    \"enabled\": false,\n    \"level\": \"INFO\"\n  }\n}\n````\n\n| 字段 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `enabled` | bool | `false` | 日志总开关。`false` 时所有日志输出关闭（见下表），`true` 时按 `level` 输出 |\n| `level` | string | `\"INFO\"` | 日志级别：`DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL` |\n\n**关闭日志时（`enabled=false`，缺省）受控的日志源**：\n\n| 日志源 | 文件路径 | 控制方式 |\n|--------|----------|----------|\n| Python loguru sink | stderr | `logger.disable(\"\")` 全局禁用 |\n| Python stdlib logging | stderr | `logging.disable(CRITICAL)` 禁用 10+ 处散落 logger |\n| uvicorn 访问日志 | stderr | `log_level=\"critical\"` + `access_log=False` |\n| raw_http transport 层日志 | `~/.niu/logs/raw_http/YYYYMMDD/NNNNNN.json` | `install_http_logger()` 不 patch HTTP client + 幂等守卫 |\n| raw_http 应用层日志 | `~/.niu/logs/raw_http/YYYYMMDD/NNNNNN_request.json` + `_response.json` | `_write_raw_log()` 静默跳过 |\n| LLM interaction 可读日志 | `~/.niu/logs/llm_interaction_YYYYMMDD.log` | `_write_interaction_log()` 静默跳过 |\n| 飞书 adapter stderr | `~/.niu/logs/im_adapter_stderr.log` | `subprocess.DEVNULL` 代替文件重定向 |\n| /http-log/ HTTP 日志查看服务 | http://localhost:9876/http-log/ | router 不挂载（返回 404） |\n| Rust tracing | stderr | `tracing_subscriber` 不 init（tracing 调用静默丢弃） |\n\n**不受日志开关控制的诊断日志**（关键诊断必须保留）：\n\n| 日志源 | 文件路径 | 用途 |\n|--------|----------|------|\n| launcher 致命错误 | `~/.niu/logs/launcher_error.log` | 启动失败诊断（API 未运行、Electron 启动失败等），用 `time` crate 格式化时间戳 |\n| gateway 致命错误 | `~/.niu/logs/gateway_error.log` | 飞书 adapter 启动失败诊断（app_id 配错、端口占用、credentials 缺失） |\n\n\n**日志目录**：\n\n所有运行时日志统一写入 `~/.niu/logs/`（macOS/Linux）或 `%USERPROFILE%\\.niu\\logs\\`（Windows），不在 bundle 内（macOS Gatekeeper 禁止运行时改 bundle 内文件）。\n\n**Windows 控制台窗口**：\n\nWindows release build 下，niu.exe 编译为 GUI 子系统（`#![cfg_attr(all(target_os=\"windows\", not(debug_assertions)), windows_subsystem=\"windows\")]`），双击不弹 cmd 窗口。debug build 保留 console 方便调试。\n\n**macOS 控制台窗口**：\n\nmacOS 下构造 `niu.app` bundle（`Info.plist` 含 `LSUIElement=true`），Finder 双击不弹 Terminal。命令行 `./niu` 裸二进制仍保留供开发调试。\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "9bf4e27563c7819adcccc34fea0510dac117867f": {"t": 1785764508.0803375, "n": 20861, "h": "a81368232acda57c", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nRust 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"\",\n    \"litellm_kwargs\": {}\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"none\",\n    \"litellm_kwargs\": {}\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点基础地址（不含路径后缀，LiteLLM 会自动追加：openai 类型追加 `/chat/completions`，anthropic 类型追加 `/v1/messages`） |\n| `model` | 模型名称 |\n| `type` | 系统内部参数，用于区分 API 格式转换和认证方式：`openai`（OpenAI 兼容格式）或 `anthropic`（Anthropic 原生格式）。**不是** LiteLLM 的 custom_llm_provider |\n| `provider` | LiteLLM 路由参数，映射为 `custom_llm_provider`。常见值：`\"\"`（空，默认由 type 决定）、`\"volcengine\"`（火山引擎）。填写后模型名无需加厂商前缀 |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"`。**注意**：该参数的实际效果与模型基础能力强相关，不同模型的最优值差异很大，需实测确定（详见下方\"reasoning_effort 配置与测试指南\"） |\n| `litellm_kwargs` | 厂商特有参数，JSON 对象格式，原样透传给 LiteLLM。用于传递各厂商 SDK 要求的额外参数（如火山引擎的 `thinking`、`allowed_openai_params` 等）。代码不做任何厂商判断，只负责透传 |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**火山方舟(Ark)端点配置说明**\n\n火山方舟提供两种计费端点，模型池相同，但功能权限有差异：\n\n| 端点 | 地址 | 计费 | response_format | 适用场景 |\n|------|------|------|-----------------|----------|\n| 标准端点 | `https://ark.cn-beijing.volces.com/api/v3` | 按量计费 | 支持 | 主 Agent、LightRAG |\n| Coding Plan | `https://ark.cn-beijing.volces.com/api/coding/v3` | 包月计费 | **不支持**（网关 400 拒绝） | 主 Agent |\n\n**格式化输出（response_format）能力自动探测**\n\n设置窗口\"测试连接并保存\"按钮在测试通过后，会自动追加一次格式化输出能力探测，按 3 档递进调用真实 LLM，找出当前配置支持的最强档位：\n\n| 档位 | response_format.type | 约束 | 典型支持厂商 |\n|------|---------------------|------|--------------|\n| Tier 1（最强） | `json_schema` strict | 输出严格匹配 schema | OpenAI 真正支持 |\n| Tier 2（中等） | `json_object` | 输出合法 JSON，不约束字段 | OpenAI、DeepSeek |\n| Tier 3（最弱） | 无 response_format | prompt + `json_repair` 客户端容错 | 所有厂商兜底 |\n\n**探测流程**：从 Tier 1 开始测，失败则降级测 Tier 2，再失败则定为 Tier 3。每档失败条件：\n- `model_rejected`：LiteLLM 抛 `BadRequestError`/`UnsupportedParamsError`（模型/网关 4xx 拒绝，如豆包 Coding Plan）\n- `gateway_blocked`：网关返回 200 但响应非合法 JSON（网关接受参数但模型输出漂移，如 GLM xopglm5）\n\n探测采用三次采样 + 冲突式设计：\n- 三次采样全过才升档，任何一次失败立即降级——防 flaky 网关（豆包 Coding\n  Plan 2026-07-21 实测：同一请求 5 次采样 2 次执行、3 次静默忽略）碰巧\n  命中执行窗口期误判支持\n- 冲突式设计：schema 强制要求 `{\"verdict\": \"SCHEMA_ENFORCED\"}`，prompt\n  却要求模型写普通英文句子且禁止输出 JSON——只有 schema 战胜 prompt\n  （输出被强制为 schema JSON）才判定真支持，模型跟随 prompt 输出普通\n  文本即判定网关静默忽略\n- 限流单独处理：RateLimitError 不计失败，sleep 后重试本次采样（指数\n  退避 5s→10s→20s→40s→80s，最多 5 次），直到返回非限流结果才判定\n\n**写入配置**：\n- `lightrag_llm.litellm_kwargs.response_format_mode`：`\"json_schema\"` / `\"json_object\"` / `\"prompt_only\"`\n- `lightrag_llm.litellm_kwargs.allowed_openai_params`：前两档 `[\"response_format\"]`，prompt_only 档 `[]`（双写兼容旧逻辑）\n\n**典型场景**（2026-07-19 实测）：\n- 豆包 Coding Plan 端点（`/api/coding/v3`，model=`ark-code-latest`）：\n  网关行为非确定性（flaky），同一请求多次采样结果不稳定（有时执行\n  json_schema strict、有时静默忽略），三次采样必然 ≥1 次静默忽略 →\n  探测结果稳定 `prompt_only`\n- GLM 端点（`maas-coding-api.cn-huabei-1.xf-yun.com/v2`，model=`xopglm5`）：网关接受但模型输出漂移，探测结果 `prompt_only`\n- OpenAI 官方：探测结果 `json_schema`\n\n**升级后自动探测**：旧版本用户配置无 `response_format_mode` 字段。程序启动后若检测到该字段缺失，后台自动触发一次探测写入配置，不阻塞启动。\n\n**手动覆盖**：关闭程序后手动编辑 `config/user-config.json` 的 `lightrag_llm.litellm_kwargs.response_format_mode`。下次设置窗口测试保存会覆盖手动值。\n\n**注意**：\n- 探测调用会消耗约 100-200 token（最坏情况测到 Tier 2）。仅\"测试连接并保存\"按钮触发，不引入后台定时探测（升级后首次启动除外）。\n- 探测独立于启动时的 LLM 连通性测试（`/api/test-llm`），不影响启动速度。\n\n> **重要**：LightRAG 的 keyword_extraction 依赖 `response_format`，必须使用标准端点。如果误用 Coding Plan 端点，本次升级后的\"格式化输出能力自动探测\"会识别为 `prompt_only` 档位并写入配置，运行时 LightRAG 直接走 prompt-only 路径（不再每次发无效请求触发 400 后 fallback）。详见上方\"格式化输出（response_format）能力自动探测\"小节。\n\n**火山方舟深度思考模型 + 工具调用配置**（重要）：\n\n火山方舟的 `doubao-seed` 系列模型（包括 `ark-code-latest`）默认启用深度思考模式。当 `litellm_kwargs` 中未显式传递 `thinking` 参数时，API 没有结构化工具调用保障——模型偶发将 tool_call 放入 `reasoning_content` 的 `<seed:tool_call>` XML 格式，而非标准的 `tool_calls` 字段，导致工具调用丢失。\n\n**主 Agent 必须配置**：\n```json\n\"llm\": {\n  ...\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n| `thinking` 值 | 效果 | 适用场景 |\n|---------------|------|----------|\n| `{\"type\": \"enabled\"}` | 显式启用深度思考，API 网关保障 tool_call 走标准通道 | **主 Agent（必须）** |\n| `{\"type\": \"disabled\"}` | 禁用深度思考 | LightRAG 入库（需配合 `response_format`） |\n| `{\"type\": \"auto\"}` | 模型自行决定 | 不推荐（行为不确定） |\n| 不传 | 模型默认启用思考，但无 tool_call 保障 | **危险：工具调用可能丢失** |\n\n> **注意**：`thinking` 参数通过 `litellm_kwargs` 原样透传给 LiteLLM，再由 VolcEngine 适配器转为 API 请求的 `extra_body.thinking` 字段。代码不做任何厂商判断，所有厂商特有参数都走这个透传通道。\n\n**模型名格式差异**：\n\n两种端点的模型池相同，但模型名格式不同：\n\n| 端点 | 模型名格式 | 示例 |\n|------|-----------|------|\n| 标准端点 | 带日期后缀的全名 | `doubao-seed-2-0-pro-260215` |\n| Coding Plan | 简短别名 | `doubao-seed-2.0-pro` |\n\n> **注意**：在标准端点上使用 Coding Plan 的简短别名会返回 404；反之，在 Coding Plan 端点上两种格式都能用。\n\n**LiteLLM 路由配置**：\n\n使用 LiteLLM 调用火山方舟模型时，必须通过 `provider: \"volcengine\"` 走 VolcEngine 适配器路由。这是 LiteLLM 的标准机制：\n\n| 配置方式 | 路由 | 结果 |\n|----------|------|------|\n| `provider: \"volcengine\"` + `model: \"doubao-seed-2.0-pro\"` | VolcEngine 适配器 | 正确：`thinking` 参数自动处理，厂商特有参数通过 `litellm_kwargs` 透传 |\n| `model: \"volcengine/doubao-seed-2.0-pro\"`（无 provider） | VolcEngine 适配器 | 也可：LiteLLM 通过前缀推断路由，但不如 `provider` 显式 |\n| `model: \"doubao-seed-2.0-pro\"`（无 provider 无前缀） | OpenAI 适配器 | **错误**：`thinking` 等火山特有参数无法传递 |\n\n> **注意**：`type: \"openai\"` 是系统内部参数（区分 Anthropic/OpenAI 格式转换），不是 LiteLLM 的 `custom_llm_provider`。两者独立：`type` 控制格式，`provider` 控制路由。\n\n**可用模型**：doubao-seed-2.0-code、doubao-seed-2.0-pro、doubao-seed-2.0-lite、minimax-m2.7、minimax-m3、glm-5.1、kimi-k2.6、deepseek-v4-pro、deepseek-v4-flash、ark-code-latest\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-seed-2.0-pro`（Coding Plan 别名）或 `doubao-seed-2-0-pro-260215`（标准端点全名） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `provider` | LiteLLM 路由参数，同 `llm` 段说明。火山引擎填 `\"volcengine\"` | `\"\"` 或 `\"volcengine\"` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n| `temperature` | LLM 采样温度。0.0 完全确定性，1.0 高随机度。为空时由系统兜底 0.2 | `0.2`（实体/关系抽取建议低温度避免 JSON 漂移） |\n| `litellm_kwargs` | 厂商特有参数，同 `llm` 段说明。火山引擎知识图谱需传 `thinking` 和 `allowed_openai_params` | `{}` 或见配置示例 |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n> **温度值说明**：LightRAG 调 LLM 时如果不配 `temperature` 字段，系统兜底默认 `0.2`。这是为实体抽取、关系抽取等结构化任务优化的低温度值，避免高随机度导致 JSON 格式漂移、实体名不一致。如果需要更稳定的输出可设 `0.0`，需要更多创造性可设 `0.5~0.7`，但不建议超过 `1.0`。主 Agent / 子 Agent 的温度值在提示词文档里独立配置（主 Agent 0.6、子 Agent 多数 0.2），与此处的 `lightrag_llm.temperature` 完全独立，互不影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用 | 建议初始使用时，根据模型情况自己测试后确定 |\n| `low` | 浅层推理 | 模型推理速度极慢时，可选用 |\n| `medium` | 中等推理 | 非入库的图谱查询任务；部分模型入库也可用 |\n| `high` | 深度推理 | 建议用于入库（推理预算耗尽，输出质量高） |\n| `xhigh` | 最深推理 | 不建议用于入库 |\n\n**reasoning_effort 配置与测试指南**：\n\n`reasoning_effort` 的最优值与模型基础能力强相关，不存在通用最优值。实测数据（ark-code-latest 模型入库 SYSTEM_MANUAL.md）：\n\n| 配置 | 实体类型准确率 | 空响应率 | 补充提取有效性 | 综合评分 |\n|------|--------------|---------|--------------|---------|\n| `none` | 67% | 60% | 无 | 5.5/10 |\n| `low` | 95% | 40% | 有效 | **7.5/10** |\n| `medium` | 14% | 40% | 部分 | 6.0/10 |\n| `high` | 分裂 | 40% | 无 | 4.0/10 |\n\n关键发现：\n1. **推理越深不一定越好**：推理token被模型内部消耗，不转化为输出质量。过度推理反而导致实体类型误分类（如子Agent被归为organization而非technology）\n2. **补充提取受影响**：高推理级别下模型过度自信，判断\"无需补充\"，导致遗漏无法弥补\n3. **不同模型差异很大**：能力强的模型（如 Claude、GPT-4o）在 `none` 或 `low` 即可高质量提取；能力有限的模型可能需要 `high`，但也可能适得其反\n\n**换模型后必须实测**：更改模型或 reasoning_effort 后，用同一文档入库并检查日志验证效果。\n\n**入库质量检查方法**：\n1. 入库后检查日志目录 `logs/raw_http/YYYYMMDD/`，读取 `*_response.json` 文件\n2. 检查空响应：响应体仅含 `<|COMPLETE|>` 或 content 为空，说明该轮提取失败\n3. 检查实体类型：子Agent应为 technology 而非 person/organization；MCP服务器应为 technology 而非 organization\n4. 检查违规节点：不应出现与 niu 根节点重名的实体\n5. 检查补充提取：`*_response.json` 中补充提取应有实质内容（非仅 `<|COMPLETE|>`）\n6. 如发现问题，调整 reasoning_effort 重新入库测试\n\n**配置示例**：\n\n主 Agent 用火山方舟 Coding Plan（完整配置）：\n```json\n\"llm\": {\n  \"presetId\": \"ark-code-latest\",\n  \"apiKey\": \"你的API Key\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/coding/v3\",\n  \"model\": \"ark-code-latest\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"\",\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3\",\n  \"model\": \"doubao-seed-2-0-pro-260215\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"disabled\"},\n    \"allowed_openai_params\": [\"response_format\"]\n  }\n}\n```\n\n> **注意**：LightRAG 必须使用标准端点（apiBase 含 /api/v3），不能用 Coding Plan 端点（/api/coding/v3），因为 Coding Plan 网关 400 拒绝 response_format。设置窗口\"测试连接并保存\"会自动探测并写入 `response_format_mode=prompt_only`（豆包 Coding Plan 场景）。model 必须用标准端点的全名格式（带日期后缀）。\n> **LiteLLM 路由**：`provider: \"volcengine\"` 让 LiteLLM 走 VolcEngine 适配器。`litellm_kwargs` 中的 `thinking: {\"type\": \"disabled\"}` 关闭思考链（火山要求使用 response_format 时必须关闭），`allowed_openai_params: [\"response_format\"]` 让 VolcEngine 适配器透传 response_format 参数。\n\n场景二：主 Agent 和 LightRAG 用同一模型，独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n场景三：能力强的模型，禁用思考链即可（如 Claude、GPT-4o）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"none\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 上下文配置\n\n**配置文件**：`config/user-config.json` 中的 `context` 段\n\n```json\n{\n  \"context\": {\n    \"contextWindowSize\": 200000,\n    \"warningThreshold\": 0.8,\n    \"targetThreshold\": 0.5,\n    \"sleepTriggerMinutes\": 5\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 默认值 | 范围 |\n|------|------|--------|------|\n| `contextWindowSize` | 模型上下文窗口大小（tokens） | 200000 | 32000 ~ 2000000 |\n| `warningThreshold` | 溢出警告阈值，上下文使用率超过此值触发压缩 | 0.8 | 0.0 ~ 1.0 |\n| `targetThreshold` | 强制压缩目标，压缩后上下文使用率降至此值 | 0.5 | 0.0 ~ 1.0 |\n| `sleepTriggerMinutes` | 空闲多久后触发睡眠整理（分钟） | 5 | > 0 |\n\n**常见模型的 contextWindowSize**：\n\n| 模型 | 上下文窗口 | 配置值 |\n|------|-----------|--------|\n| GPT-4o-mini | 128K | 128000 |\n| GPT-4o | 128K | 128000 |\n| Claude 3.5 Sonnet | 200K | 200000 |\n| DeepSeek V3 (deepseek-chat) | 64K | 64000 |\n| DeepSeek R1 (deepseek-reasoner) | 128K | 128000 |\n| Qwen2.5-Turbo | 1M | 1000000 |\n| 本地 Ollama 模型 | 取决于模型 | 按实际配置 |\n\n> **注意**：`contextWindowSize` 与模型强相关，切换模型后需同步更新此值。设置窗口主界面可直接配置此值，高级选项中可配置溢出阈值等参数。\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出，`contextWindowSize` 在主界面，阈值参数点\"高级选项\"展开）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.4 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.5 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.5 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Excel | .xlsx | 支持 |\n| PowerPoint | .pptx | 支持 |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| HTML | .html | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.6 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 10 条（1 条工作便签 + 9 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（知识图谱 LightRAG）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索 + 知识图谱关联，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.7 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.8 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n### 1.9 日志配置\n\n**配置文件**：`~/.niu/config/user-config.json`（首次启动从 bundle 内 `config/user-config.json` 模板复制）\n\n**配置字段**：\n\n````json\n{\n  \"logging\": {\n    \"enabled\": false,\n    \"level\": \"INFO\"\n  }\n}\n````\n\n| 字段 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `enabled` | bool | `false` | 日志总开关。`false` 时所有日志输出关闭（见下表），`true` 时按 `level` 输出 |\n| `level` | string | `\"INFO\"` | 日志级别：`DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL` |\n\n**关闭日志时（`enabled=false`，缺省）受控的日志源**：\n\n| 日志源 | 文件路径 | 控制方式 |\n|--------|----------|----------|\n| Python loguru sink | stderr | `logger.disable(\"\")` 全局禁用 |\n| Python stdlib logging | stderr | `logging.disable(CRITICAL)` 禁用 10+ 处散落 logger |\n| uvicorn 访问日志 | stderr | `log_level=\"critical\"` + `access_log=False` |\n| raw_http transport 层日志 | `~/.niu/logs/raw_http/YYYYMMDD/NNNNNN.json` | `install_http_logger()` 不 patch HTTP client + 幂等守卫 |\n| raw_http 应用层日志 | `~/.niu/logs/raw_http/YYYYMMDD/NNNNNN_request.json` + `_response.json` | `_write_raw_log()` 静默跳过 |\n| LLM interaction 可读日志 | `~/.niu/logs/llm_interaction_YYYYMMDD.log` | `_write_interaction_log()` 静默跳过 |\n| 飞书 adapter stderr | `~/.niu/logs/im_adapter_stderr.log` | `subprocess.DEVNULL` 代替文件重定向 |\n| /http-log/ HTTP 日志查看服务 | http://localhost:9876/http-log/ | router 不挂载（返回 404） |\n| Rust tracing | stderr | `tracing_subscriber` 不 init（tracing 调用静默丢弃） |\n\n**不受日志开关控制的诊断日志**（关键诊断必须保留）：\n\n| 日志源 | 文件路径 | 用途 |\n|--------|----------|------|\n| launcher 致命错误 | `~/.niu/logs/launcher_error.log` | 启动失败诊断（API 未运行、Electron 启动失败等），用 `time` crate 格式化时间戳 |\n| gateway 致命错误 | `~/.niu/logs/gateway_error.log` | 飞书 adapter 启动失败诊断（app_id 配错、端口占用、credentials 缺失） |\n\n**开启日志**（调试时用）：\n\n把 `~/.niu/config/user-config.json` 的 `logging.enabled` 改为 `true`，重启程序。所有受控日志源会按 `level` 字段输出到对应文件或 stderr。\n\n**日志目录**：\n\n所有运行时日志统一写入 `~/.niu/logs/`（macOS/Linux）或 `%USERPROFILE%\\.niu\\logs\\`（Windows），不在 bundle 内（macOS Gatekeeper 禁止运行时改 bundle 内文件）。\n\n**Windows 控制台窗口**：\n\nWindows release build 下，niu.exe 编译为 GUI 子系统（`#![cfg_attr(all(target_os=\"windows\", not(debug_assertions)), windows_subsystem=\"windows\")]`），双击不弹 cmd 窗口。debug build 保留 console 方便调试。\n\n**macOS 控制台窗口**：\n\nmacOS 下构造 `niu.app` bundle（`Info.plist` 含 `LSUIElement=true`），Finder 双击不弹 Terminal。命令行 `./niu` 裸二进制仍保留供开发调试。\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "53ae46b68da8947f3510b5ed5f9173a5f46e8319": {"t": 1785764509.5914686, "n": 18653, "h": "6c431f4dca83ff26", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nRust 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"\",\n    \"litellm_kwargs\": {}\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"none\",\n    \"litellm_kwargs\": {}\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点基础地址（不含路径后缀，LiteLLM 会自动追加：openai 类型追加 `/chat/completions`，anthropic 类型追加 `/v1/messages`） |\n| `model` | 模型名称 |\n| `type` | 系统内部参数，用于区分 API 格式转换和认证方式：`openai`（OpenAI 兼容格式）或 `anthropic`（Anthropic 原生格式）。**不是** LiteLLM 的 custom_llm_provider |\n| `provider` | LiteLLM 路由参数，映射为 `custom_llm_provider`。常见值：`\"\"`（空，默认由 type 决定）、`\"volcengine\"`（火山引擎）。填写后模型名无需加厂商前缀 |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"`。**注意**：该参数的实际效果与模型基础能力强相关，不同模型的最优值差异很大，需实测确定（详见下方\"reasoning_effort 配置与测试指南\"） |\n| `litellm_kwargs` | 厂商特有参数，JSON 对象格式，原样透传给 LiteLLM。用于传递各厂商 SDK 要求的额外参数（如火山引擎的 `thinking`、`allowed_openai_params` 等）。代码不做任何厂商判断，只负责透传 |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**火山方舟(Ark)端点配置说明**\n\n火山方舟提供两种计费端点，模型池相同，但功能权限有差异：\n\n| 端点 | 地址 | 计费 | response_format | 适用场景 |\n|------|------|------|-----------------|----------|\n| 标准端点 | `https://ark.cn-beijing.volces.com/api/v3` | 按量计费 | 支持 | 主 Agent、LightRAG |\n| Coding Plan | `https://ark.cn-beijing.volces.com/api/coding/v3` | 包月计费 | **不支持**（网关 400 拒绝） | 主 Agent |\n\n**格式化输出（response_format）能力自动探测**\n\n设置窗口\"测试连接并保存\"按钮在测试通过后，会自动追加一次格式化输出能力探测，按 3 档递进调用真实 LLM，找出当前配置支持的最强档位：\n\n| 档位 | response_format.type | 约束 | 典型支持厂商 |\n|------|---------------------|------|--------------|\n| Tier 1（最强） | `json_schema` strict | 输出严格匹配 schema | OpenAI 真正支持 |\n| Tier 2（中等） | `json_object` | 输出合法 JSON，不约束字段 | OpenAI、DeepSeek |\n| Tier 3（最弱） | 无 response_format | prompt + `json_repair` 客户端容错 | 所有厂商兜底 |\n\n**探测流程**：从 Tier 1 开始测，失败则降级测 Tier 2，再失败则定为 Tier 3。每档失败条件：\n- `model_rejected`：LiteLLM 抛 `BadRequestError`/`UnsupportedParamsError`（模型/网关 4xx 拒绝，如豆包 Coding Plan）\n- `gateway_blocked`：网关返回 200 但响应非合法 JSON（网关接受参数但模型输出漂移，如 GLM xopglm5）\n\n探测采用三次采样 + 冲突式设计：\n- 三次采样全过才升档，任何一次失败立即降级——防 flaky 网关（豆包 Coding\n  Plan 2026-07-21 实测：同一请求 5 次采样 2 次执行、3 次静默忽略）碰巧\n  命中执行窗口期误判支持\n- 冲突式设计：schema 强制要求 `{\"verdict\": \"SCHEMA_ENFORCED\"}`，prompt\n  却要求模型写普通英文句子且禁止输出 JSON——只有 schema 战胜 prompt\n  （输出被强制为 schema JSON）才判定真支持，模型跟随 prompt 输出普通\n  文本即判定网关静默忽略\n- 限流单独处理：RateLimitError 不计失败，sleep 后重试本次采样（指数\n  退避 5s→10s→20s→40s→80s，最多 5 次），直到返回非限流结果才判定\n\n**写入配置**：\n- `lightrag_llm.litellm_kwargs.response_format_mode`：`\"json_schema\"` / `\"json_object\"` / `\"prompt_only\"`\n- `lightrag_llm.litellm_kwargs.allowed_openai_params`：前两档 `[\"response_format\"]`，prompt_only 档 `[]`（双写兼容旧逻辑）\n\n**典型场景**（2026-07-19 实测）：\n- 豆包 Coding Plan 端点（`/api/coding/v3`，model=`ark-code-latest`）：\n  网关行为非确定性（flaky），同一请求多次采样结果不稳定（有时执行\n  json_schema strict、有时静默忽略），三次采样必然 ≥1 次静默忽略 →\n  探测结果稳定 `prompt_only`\n- GLM 端点（`maas-coding-api.cn-huabei-1.xf-yun.com/v2`，model=`xopglm5`）：网关接受但模型输出漂移，探测结果 `prompt_only`\n- OpenAI 官方：探测结果 `json_schema`\n\n**升级后自动探测**：旧版本用户配置无 `response_format_mode` 字段。程序启动后若检测到该字段缺失，后台自动触发一次探测写入配置，不阻塞启动。\n\n**手动覆盖**：关闭程序后手动编辑 `config/user-config.json` 的 `lightrag_llm.litellm_kwargs.response_format_mode`。下次设置窗口测试保存会覆盖手动值。\n\n**注意**：\n- 探测调用会消耗约 100-200 token（最坏情况测到 Tier 2）。仅\"测试连接并保存\"按钮触发，不引入后台定时探测（升级后首次启动除外）。\n- 探测独立于启动时的 LLM 连通性测试（`/api/test-llm`），不影响启动速度。\n\n> **重要**：LightRAG 的 keyword_extraction 依赖 `response_format`，必须使用标准端点。如果误用 Coding Plan 端点，本次升级后的\"格式化输出能力自动探测\"会识别为 `prompt_only` 档位并写入配置，运行时 LightRAG 直接走 prompt-only 路径（不再每次发无效请求触发 400 后 fallback）。详见上方\"格式化输出（response_format）能力自动探测\"小节。\n\n**火山方舟深度思考模型 + 工具调用配置**（重要）：\n\n火山方舟的 `doubao-seed` 系列模型（包括 `ark-code-latest`）默认启用深度思考模式。当 `litellm_kwargs` 中未显式传递 `thinking` 参数时，API 没有结构化工具调用保障——模型偶发将 tool_call 放入 `reasoning_content` 的 `<seed:tool_call>` XML 格式，而非标准的 `tool_calls` 字段，导致工具调用丢失。\n\n**主 Agent 必须配置**：\n```json\n\"llm\": {\n  ...\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n| `thinking` 值 | 效果 | 适用场景 |\n|---------------|------|----------|\n| `{\"type\": \"enabled\"}` | 显式启用深度思考，API 网关保障 tool_call 走标准通道 | **主 Agent（必须）** |\n| `{\"type\": \"disabled\"}` | 禁用深度思考 | LightRAG 入库（需配合 `response_format`） |\n| `{\"type\": \"auto\"}` | 模型自行决定 | 不推荐（行为不确定） |\n| 不传 | 模型默认启用思考，但无 tool_call 保障 | **危险：工具调用可能丢失** |\n\n> **注意**：`thinking` 参数通过 `litellm_kwargs` 原样透传给 LiteLLM，再由 VolcEngine 适配器转为 API 请求的 `extra_body.thinking` 字段。代码不做任何厂商判断，所有厂商特有参数都走这个透传通道。\n\n**模型名格式差异**：\n\n两种端点的模型池相同，但模型名格式不同：\n\n| 端点 | 模型名格式 | 示例 |\n|------|-----------|------|\n| 标准端点 | 带日期后缀的全名 | `doubao-seed-2-0-pro-260215` |\n| Coding Plan | 简短别名 | `doubao-seed-2.0-pro` |\n\n> **注意**：在标准端点上使用 Coding Plan 的简短别名会返回 404；反之，在 Coding Plan 端点上两种格式都能用。\n\n**LiteLLM 路由配置**：\n\n使用 LiteLLM 调用火山方舟模型时，必须通过 `provider: \"volcengine\"` 走 VolcEngine 适配器路由。这是 LiteLLM 的标准机制：\n\n| 配置方式 | 路由 | 结果 |\n|----------|------|------|\n| `provider: \"volcengine\"` + `model: \"doubao-seed-2.0-pro\"` | VolcEngine 适配器 | 正确：`thinking` 参数自动处理，厂商特有参数通过 `litellm_kwargs` 透传 |\n| `model: \"volcengine/doubao-seed-2.0-pro\"`（无 provider） | VolcEngine 适配器 | 也可：LiteLLM 通过前缀推断路由，但不如 `provider` 显式 |\n| `model: \"doubao-seed-2.0-pro\"`（无 provider 无前缀） | OpenAI 适配器 | **错误**：`thinking` 等火山特有参数无法传递 |\n\n> **注意**：`type: \"openai\"` 是系统内部参数（区分 Anthropic/OpenAI 格式转换），不是 LiteLLM 的 `custom_llm_provider`。两者独立：`type` 控制格式，`provider` 控制路由。\n\n**可用模型**：doubao-seed-2.0-code、doubao-seed-2.0-pro、doubao-seed-2.0-lite、minimax-m2.7、minimax-m3、glm-5.1、kimi-k2.6、deepseek-v4-pro、deepseek-v4-flash、ark-code-latest\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-seed-2.0-pro`（Coding Plan 别名）或 `doubao-seed-2-0-pro-260215`（标准端点全名） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `provider` | LiteLLM 路由参数，同 `llm` 段说明。火山引擎填 `\"volcengine\"` | `\"\"` 或 `\"volcengine\"` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n| `temperature` | LLM 采样温度。0.0 完全确定性，1.0 高随机度。为空时由系统兜底 0.2 | `0.2`（实体/关系抽取建议低温度避免 JSON 漂移） |\n| `litellm_kwargs` | 厂商特有参数，同 `llm` 段说明。火山引擎知识图谱需传 `thinking` 和 `allowed_openai_params` | `{}` 或见配置示例 |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n> **温度值说明**：LightRAG 调 LLM 时如果不配 `temperature` 字段，系统兜底默认 `0.2`。这是为实体抽取、关系抽取等结构化任务优化的低温度值，避免高随机度导致 JSON 格式漂移、实体名不一致。如果需要更稳定的输出可设 `0.0`，需要更多创造性可设 `0.5~0.7`，但不建议超过 `1.0`。主 Agent / 子 Agent 的温度值在提示词文档里独立配置（主 Agent 0.6、子 Agent 多数 0.2），与此处的 `lightrag_llm.temperature` 完全独立，互不影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用 | 建议初始使用时，根据模型情况自己测试后确定 |\n| `low` | 浅层推理 | 模型推理速度极慢时，可选用 |\n| `medium` | 中等推理 | 非入库的图谱查询任务；部分模型入库也可用 |\n| `high` | 深度推理 | 建议用于入库（推理预算耗尽，输出质量高） |\n| `xhigh` | 最深推理 | 不建议用于入库 |\n\n**reasoning_effort 配置与测试指南**：\n\n`reasoning_effort` 的最优值与模型基础能力强相关，不存在通用最优值。实测数据（ark-code-latest 模型入库 SYSTEM_MANUAL.md）：\n\n| 配置 | 实体类型准确率 | 空响应率 | 补充提取有效性 | 综合评分 |\n|------|--------------|---------|--------------|---------|\n| `none` | 67% | 60% | 无 | 5.5/10 |\n| `low` | 95% | 40% | 有效 | **7.5/10** |\n| `medium` | 14% | 40% | 部分 | 6.0/10 |\n| `high` | 分裂 | 40% | 无 | 4.0/10 |\n\n关键发现：\n1. **推理越深不一定越好**：推理token被模型内部消耗，不转化为输出质量。过度推理反而导致实体类型误分类（如子Agent被归为organization而非technology）\n2. **补充提取受影响**：高推理级别下模型过度自信，判断\"无需补充\"，导致遗漏无法弥补\n3. **不同模型差异很大**：能力强的模型（如 Claude、GPT-4o）在 `none` 或 `low` 即可高质量提取；能力有限的模型可能需要 `high`，但也可能适得其反\n\n**换模型后必须实测**：更改模型或 reasoning_effort 后，用同一文档入库并检查日志验证效果。\n\n**入库质量检查方法**：\n1. 入库后检查日志目录 `logs/raw_http/YYYYMMDD/`，读取 `*_response.json` 文件\n2. 检查空响应：响应体仅含 `<|COMPLETE|>` 或 content 为空，说明该轮提取失败\n3. 检查实体类型：子Agent应为 technology 而非 person/organization；MCP服务器应为 technology 而非 organization\n4. 检查违规节点：不应出现与 niu 根节点重名的实体\n5. 检查补充提取：`*_response.json` 中补充提取应有实质内容（非仅 `<|COMPLETE|>`）\n6. 如发现问题，调整 reasoning_effort 重新入库测试\n\n**配置示例**：\n\n主 Agent 用火山方舟 Coding Plan（完整配置）：\n```json\n\"llm\": {\n  \"presetId\": \"ark-code-latest\",\n  \"apiKey\": \"你的API Key\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/coding/v3\",\n  \"model\": \"ark-code-latest\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"\",\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3\",\n  \"model\": \"doubao-seed-2-0-pro-260215\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"disabled\"},\n    \"allowed_openai_params\": [\"response_format\"]\n  }\n}\n```\n\n> **注意**：LightRAG 必须使用标准端点（apiBase 含 /api/v3），不能用 Coding Plan 端点（/api/coding/v3），因为 Coding Plan 网关 400 拒绝 response_format。设置窗口\"测试连接并保存\"会自动探测并写入 `response_format_mode=prompt_only`（豆包 Coding Plan 场景）。model 必须用标准端点的全名格式（带日期后缀）。\n> **LiteLLM 路由**：`provider: \"volcengine\"` 让 LiteLLM 走 VolcEngine 适配器。`litellm_kwargs` 中的 `thinking: {\"type\": \"disabled\"}` 关闭思考链（火山要求使用 response_format 时必须关闭），`allowed_openai_params: [\"response_format\"]` 让 VolcEngine 适配器透传 response_format 参数。\n\n场景二：主 Agent 和 LightRAG 用同一模型，独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n场景三：能力强的模型，禁用思考链即可（如 Claude、GPT-4o）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"none\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 上下文配置\n\n**配置文件**：`config/user-config.json` 中的 `context` 段\n\n```json\n{\n  \"context\": {\n    \"contextWindowSize\": 200000,\n    \"warningThreshold\": 0.8,\n    \"targetThreshold\": 0.5,\n    \"sleepTriggerMinutes\": 5\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 默认值 | 范围 |\n|------|------|--------|------|\n| `contextWindowSize` | 模型上下文窗口大小（tokens） | 200000 | 32000 ~ 2000000 |\n| `warningThreshold` | 溢出警告阈值，上下文使用率超过此值触发压缩 | 0.8 | 0.0 ~ 1.0 |\n| `targetThreshold` | 强制压缩目标，压缩后上下文使用率降至此值 | 0.5 | 0.0 ~ 1.0 |\n| `sleepTriggerMinutes` | 空闲多久后触发睡眠整理（分钟） | 5 | > 0 |\n\n**常见模型的 contextWindowSize**：\n\n| 模型 | 上下文窗口 | 配置值 |\n|------|-----------|--------|\n| GPT-4o-mini | 128K | 128000 |\n| GPT-4o | 128K | 128000 |\n| Claude 3.5 Sonnet | 200K | 200000 |\n| DeepSeek V3 (deepseek-chat) | 64K | 64000 |\n| DeepSeek R1 (deepseek-reasoner) | 128K | 128000 |\n| Qwen2.5-Turbo | 1M | 1000000 |\n| 本地 Ollama 模型 | 取决于模型 | 按实际配置 |\n\n> **注意**：`contextWindowSize` 与模型强相关，切换模型后需同步更新此值。设置窗口主界面可直接配置此值，高级选项中可配置溢出阈值等参数。\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出，`contextWindowSize` 在主界面，阈值参数点\"高级选项\"展开）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.4 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.5 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.5 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Excel | .xlsx | 支持 |\n| PowerPoint | .pptx | 支持 |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| HTML | .html | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.6 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 10 条（1 条工作便签 + 9 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（知识图谱 LightRAG）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索 + 知识图谱关联，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.7 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.8 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "686a92a54beb447f7a992a2784ddc53df1abb0e2": {"t": 1785764510.90733, "n": 18665, "h": "3e815ea2bb8aba34", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nRust 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"\",\n    \"litellm_kwargs\": {}\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"none\",\n    \"litellm_kwargs\": {}\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点基础地址（不含路径后缀，LiteLLM 会自动追加：openai 类型追加 `/chat/completions`，anthropic 类型追加 `/v1/messages`） |\n| `model` | 模型名称 |\n| `type` | 系统内部参数，用于区分 API 格式转换和认证方式：`openai`（OpenAI 兼容格式）或 `anthropic`（Anthropic 原生格式）。**不是** LiteLLM 的 custom_llm_provider |\n| `provider` | LiteLLM 路由参数，映射为 `custom_llm_provider`。常见值：`\"\"`（空，默认由 type 决定）、`\"volcengine\"`（火山引擎）。填写后模型名无需加厂商前缀 |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"`。**注意**：该参数的实际效果与模型基础能力强相关，不同模型的最优值差异很大，需实测确定（详见下方\"reasoning_effort 配置与测试指南\"） |\n| `litellm_kwargs` | 厂商特有参数，JSON 对象格式，原样透传给 LiteLLM。用于传递各厂商 SDK 要求的额外参数（如火山引擎的 `thinking`、`allowed_openai_params` 等）。代码不做任何厂商判断，只负责透传 |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**火山方舟(Ark)端点配置说明**\n\n火山方舟提供两种计费端点，模型池相同，但功能权限有差异：\n\n| 端点 | 地址 | 计费 | response_format | 适用场景 |\n|------|------|------|-----------------|----------|\n| 标准端点 | `https://ark.cn-beijing.volces.com/api/v3` | 按量计费 | 支持 | 主 Agent、LightRAG |\n| Coding Plan | `https://ark.cn-beijing.volces.com/api/coding/v3` | 包月计费 | **不支持**（网关 400 拒绝） | 主 Agent |\n\n**格式化输出（response_format）能力自动探测**\n\n设置窗口\"测试连接并保存\"按钮在测试通过后，会自动追加一次格式化输出能力探测，按 3 档递进调用真实 LLM，找出当前配置支持的最强档位：\n\n| 档位 | response_format.type | 约束 | 典型支持厂商 |\n|------|---------------------|------|--------------|\n| Tier 1（最强） | `json_schema` strict | 输出严格匹配 schema | OpenAI 真正支持 |\n| Tier 2（中等） | `json_object` | 输出合法 JSON，不约束字段 | OpenAI、DeepSeek |\n| Tier 3（最弱） | 无 response_format | prompt + `json_repair` 客户端容错 | 所有厂商兜底 |\n\n**探测流程**：从 Tier 1 开始测，失败则降级测 Tier 2，再失败则定为 Tier 3。每档失败条件：\n- `model_rejected`：LiteLLM 抛 `BadRequestError`/`UnsupportedParamsError`（模型/网关 4xx 拒绝，如豆包 Coding Plan）\n- `gateway_blocked`：网关返回 200 但响应非合法 JSON（网关接受参数但模型输出漂移，如 GLM xopglm5）\n\n探测采用三次采样 + 冲突式设计：\n- 三次采样全过才升档，任何一次失败立即降级——防 flaky 网关（豆包 Coding\n  Plan 2026-07-21 实测：同一请求 5 次采样 2 次执行、3 次静默忽略）碰巧\n  命中执行窗口期误判支持\n- 冲突式设计：schema 强制要求 `{\"verdict\": \"SCHEMA_ENFORCED\"}`，prompt\n  却要求模型写普通英文句子且禁止输出 JSON——只有 schema 战胜 prompt\n  （输出被强制为 schema JSON）才判定真支持，模型跟随 prompt 输出普通\n  文本即判定网关静默忽略\n- 限流单独处理：RateLimitError 不计失败，sleep 后重试本次采样（指数\n  退避 5s→10s→20s→40s→80s，最多 5 次），直到返回非限流结果才判定\n\n**写入配置**：\n- `lightrag_llm.litellm_kwargs.response_format_mode`：`\"json_schema\"` / `\"json_object\"` / `\"prompt_only\"`\n- `lightrag_llm.litellm_kwargs.allowed_openai_params`：前两档 `[\"response_format\"]`，prompt_only 档 `[]`（双写兼容旧逻辑）\n\n**典型场景**（2026-07-19 实测）：\n- 豆包 Coding Plan 端点（`/api/coding/v3`，model=`ark-code-latest`）：\n  网关行为非确定性（flaky），同一请求多次采样结果不稳定（有时执行\n  json_schema strict、有时静默忽略），三次采样必然 ≥1 次静默忽略 →\n  探测结果稳定 `prompt_only`\n- GLM 端点（`maas-coding-api.cn-huabei-1.xf-yun.com/v2`，model=`xopglm5`）：网关接受但模型输出漂移，探测结果 `prompt_only`\n- OpenAI 官方：探测结果 `json_schema`\n\n**升级后自动探测**：旧版本用户配置无 `response_format_mode` 字段。程序启动后若检测到该字段缺失，后台自动触发一次探测写入配置，不阻塞启动。\n\n**手动覆盖**：关闭程序后手动编辑 `config/user-config.json` 的 `lightrag_llm.litellm_kwargs.response_format_mode`。下次设置窗口测试保存会覆盖手动值。\n\n**注意**：\n- 探测调用会消耗约 100-200 token（最坏情况测到 Tier 2）。仅\"测试连接并保存\"按钮触发，不引入后台定时探测（升级后首次启动除外）。\n- 探测独立于启动时的 LLM 连通性测试（`/api/test-llm`），不影响启动速度。\n\n> **重要**：LightRAG 的 keyword_extraction 依赖 `response_format`，必须使用标准端点。如果误用 Coding Plan 端点，本次升级后的\"格式化输出能力自动探测\"会识别为 `prompt_only` 档位并写入配置，运行时 LightRAG 直接走 prompt-only 路径（不再每次发无效请求触发 400 后 fallback）。详见上方\"格式化输出（response_format）能力自动探测\"小节。\n\n**火山方舟深度思考模型 + 工具调用配置**（重要）：\n\n火山方舟的 `doubao-seed` 系列模型（包括 `ark-code-latest`）默认启用深度思考模式。当 `litellm_kwargs` 中未显式传递 `thinking` 参数时，API 没有结构化工具调用保障——模型偶发将 tool_call 放入 `reasoning_content` 的 `<seed:tool_call>` XML 格式，而非标准的 `tool_calls` 字段，导致工具调用丢失。\n\n**主 Agent 必须配置**：\n```json\n\"llm\": {\n  ...\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n| `thinking` 值 | 效果 | 适用场景 |\n|---------------|------|----------|\n| `{\"type\": \"enabled\"}` | 显式启用深度思考，API 网关保障 tool_call 走标准通道 | **主 Agent（必须）** |\n| `{\"type\": \"disabled\"}` | 禁用深度思考 | LightRAG 入库（需配合 `response_format`） |\n| `{\"type\": \"auto\"}` | 模型自行决定 | 不推荐（行为不确定） |\n| 不传 | 模型默认启用思考，但无 tool_call 保障 | **危险：工具调用可能丢失** |\n\n> **注意**：`thinking` 参数通过 `litellm_kwargs` 原样透传给 LiteLLM，再由 VolcEngine 适配器转为 API 请求的 `extra_body.thinking` 字段。代码不做任何厂商判断，所有厂商特有参数都走这个透传通道。\n\n**模型名格式差异**：\n\n两种端点的模型池相同，但模型名格式不同：\n\n| 端点 | 模型名格式 | 示例 |\n|------|-----------|------|\n| 标准端点 | 带日期后缀的全名 | `doubao-seed-2-0-pro-260215` |\n| Coding Plan | 简短别名 | `doubao-seed-2.0-pro` |\n\n> **注意**：在标准端点上使用 Coding Plan 的简短别名会返回 404；反之，在 Coding Plan 端点上两种格式都能用。\n\n**LiteLLM 路由配置**：\n\n使用 LiteLLM 调用火山方舟模型时，必须通过 `provider: \"volcengine\"` 走 VolcEngine 适配器路由。这是 LiteLLM 的标准机制：\n\n| 配置方式 | 路由 | 结果 |\n|----------|------|------|\n| `provider: \"volcengine\"` + `model: \"doubao-seed-2.0-pro\"` | VolcEngine 适配器 | 正确：`thinking` 参数自动处理，厂商特有参数通过 `litellm_kwargs` 透传 |\n| `model: \"volcengine/doubao-seed-2.0-pro\"`（无 provider） | VolcEngine 适配器 | 也可：LiteLLM 通过前缀推断路由，但不如 `provider` 显式 |\n| `model: \"doubao-seed-2.0-pro\"`（无 provider 无前缀） | OpenAI 适配器 | **错误**：`thinking` 等火山特有参数无法传递 |\n\n> **注意**：`type: \"openai\"` 是系统内部参数（区分 Anthropic/OpenAI 格式转换），不是 LiteLLM 的 `custom_llm_provider`。两者独立：`type` 控制格式，`provider` 控制路由。\n\n**可用模型**：doubao-seed-2.0-code、doubao-seed-2.0-pro、doubao-seed-2.0-lite、minimax-m2.7、minimax-m3、glm-5.1、kimi-k2.6、deepseek-v4-pro、deepseek-v4-flash、ark-code-latest\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-seed-2.0-pro`（Coding Plan 别名）或 `doubao-seed-2-0-pro-260215`（标准端点全名） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `provider` | LiteLLM 路由参数，同 `llm` 段说明。火山引擎填 `\"volcengine\"` | `\"\"` 或 `\"volcengine\"` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n| `temperature` | LLM 采样温度。0.0 完全确定性，1.0 高随机度。为空时由系统兜底 0.2 | `0.2`（实体/关系抽取建议低温度避免 JSON 漂移） |\n| `litellm_kwargs` | 厂商特有参数，同 `llm` 段说明。火山引擎知识图谱需传 `thinking` 和 `allowed_openai_params` | `{}` 或见配置示例 |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n> **温度值说明**：LightRAG 调 LLM 时如果不配 `temperature` 字段，系统兜底默认 `0.2`。这是为实体抽取、关系抽取等结构化任务优化的低温度值，避免高随机度导致 JSON 格式漂移、实体名不一致。如果需要更稳定的输出可设 `0.0`，需要更多创造性可设 `0.5~0.7`，但不建议超过 `1.0`。主 Agent / 子 Agent 的温度值在提示词文档里独立配置（主 Agent 0.6、子 Agent 多数 0.2），与此处的 `lightrag_llm.temperature` 完全独立，互不影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用思考链 | 能力强的模型（自带足够推理能力） |\n| `low` | 浅层推理 | **多数模型入库时的最优值**（实测推荐） |\n| `medium` | 中等推理 | 非入库的图谱查询任务；部分模型入库也可用 |\n| `high` | 深度推理 | 不建议用于入库（推理预算耗尽，输出质量反而下降） |\n| `xhigh` | 最深推理 | 不建议用于入库 |\n\n**reasoning_effort 配置与测试指南**：\n\n`reasoning_effort` 的最优值与模型基础能力强相关，不存在通用最优值。实测数据（ark-code-latest 模型入库 SYSTEM_MANUAL.md）：\n\n| 配置 | 实体类型准确率 | 空响应率 | 补充提取有效性 | 综合评分 |\n|------|--------------|---------|--------------|---------|\n| `none` | 67% | 60% | 无 | 5.5/10 |\n| `low` | 95% | 40% | 有效 | **7.5/10** |\n| `medium` | 14% | 40% | 部分 | 6.0/10 |\n| `high` | 分裂 | 40% | 无 | 4.0/10 |\n\n关键发现：\n1. **推理越深不一定越好**：推理token被模型内部消耗，不转化为输出质量。过度推理反而导致实体类型误分类（如子Agent被归为organization而非technology）\n2. **补充提取受影响**：高推理级别下模型过度自信，判断\"无需补充\"，导致遗漏无法弥补\n3. **不同模型差异很大**：能力强的模型（如 Claude、GPT-4o）在 `none` 或 `low` 即可高质量提取；能力有限的模型可能需要 `medium`，但也可能适得其反\n\n**换模型后必须实测**：更改模型或 reasoning_effort 后，用同一文档入库并检查日志验证效果。\n\n**入库质量检查方法**：\n1. 入库后检查日志目录 `logs/raw_http/YYYYMMDD/`，读取 `*_response.json` 文件\n2. 检查空响应：响应体仅含 `<|COMPLETE|>` 或 content 为空，说明该轮提取失败\n3. 检查实体类型：子Agent应为 technology 而非 person/organization；MCP服务器应为 technology 而非 organization\n4. 检查违规节点：不应出现与 niu 根节点重名的实体\n5. 检查补充提取：`*_response.json` 中补充提取应有实质内容（非仅 `<|COMPLETE|>`）\n6. 如发现问题，调整 reasoning_effort 重新入库测试\n\n**配置示例**：\n\n主 Agent 用火山方舟 Coding Plan（完整配置）：\n```json\n\"llm\": {\n  \"presetId\": \"ark-code-latest\",\n  \"apiKey\": \"你的API Key\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/coding/v3\",\n  \"model\": \"ark-code-latest\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"\",\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3\",\n  \"model\": \"doubao-seed-2-0-pro-260215\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"disabled\"},\n    \"allowed_openai_params\": [\"response_format\"]\n  }\n}\n```\n\n> **注意**：LightRAG 必须使用标准端点（apiBase 含 /api/v3），不能用 Coding Plan 端点（/api/coding/v3），因为 Coding Plan 网关 400 拒绝 response_format。设置窗口\"测试连接并保存\"会自动探测并写入 `response_format_mode=prompt_only`（豆包 Coding Plan 场景）。model 必须用标准端点的全名格式（带日期后缀）。\n> **LiteLLM 路由**：`provider: \"volcengine\"` 让 LiteLLM 走 VolcEngine 适配器。`litellm_kwargs` 中的 `thinking: {\"type\": \"disabled\"}` 关闭思考链（火山要求使用 response_format 时必须关闭），`allowed_openai_params: [\"response_format\"]` 让 VolcEngine 适配器透传 response_format 参数。\n\n场景二：主 Agent 和 LightRAG 用同一模型，独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n场景三：能力强的模型，禁用思考链即可（如 Claude、GPT-4o）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"none\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 上下文配置\n\n**配置文件**：`config/user-config.json` 中的 `context` 段\n\n```json\n{\n  \"context\": {\n    \"contextWindowSize\": 200000,\n    \"warningThreshold\": 0.8,\n    \"targetThreshold\": 0.5,\n    \"sleepTriggerMinutes\": 5\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 默认值 | 范围 |\n|------|------|--------|------|\n| `contextWindowSize` | 模型上下文窗口大小（tokens） | 200000 | 32000 ~ 2000000 |\n| `warningThreshold` | 溢出警告阈值，上下文使用率超过此值触发压缩 | 0.8 | 0.0 ~ 1.0 |\n| `targetThreshold` | 强制压缩目标，压缩后上下文使用率降至此值 | 0.5 | 0.0 ~ 1.0 |\n| `sleepTriggerMinutes` | 空闲多久后触发睡眠整理（分钟） | 5 | > 0 |\n\n**常见模型的 contextWindowSize**：\n\n| 模型 | 上下文窗口 | 配置值 |\n|------|-----------|--------|\n| GPT-4o-mini | 128K | 128000 |\n| GPT-4o | 128K | 128000 |\n| Claude 3.5 Sonnet | 200K | 200000 |\n| DeepSeek V3 (deepseek-chat) | 64K | 64000 |\n| DeepSeek R1 (deepseek-reasoner) | 128K | 128000 |\n| Qwen2.5-Turbo | 1M | 1000000 |\n| 本地 Ollama 模型 | 取决于模型 | 按实际配置 |\n\n> **注意**：`contextWindowSize` 与模型强相关，切换模型后需同步更新此值。设置窗口主界面可直接配置此值，高级选项中可配置溢出阈值等参数。\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出，`contextWindowSize` 在主界面，阈值参数点\"高级选项\"展开）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.4 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.5 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.5 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Excel | .xlsx | 支持 |\n| PowerPoint | .pptx | 支持 |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| HTML | .html | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.6 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 10 条（1 条工作便签 + 9 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（知识图谱 LightRAG）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索 + 知识图谱关联，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.7 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.8 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "70af9b8003fe7d3cbd072cff5992cc33cd85b7de": {"t": 1785764512.4207609, "n": 18218, "h": "6ab14eb1c42d9797", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nRust 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"\",\n    \"litellm_kwargs\": {}\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"none\",\n    \"litellm_kwargs\": {}\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点基础地址（不含路径后缀，LiteLLM 会自动追加：openai 类型追加 `/chat/completions`，anthropic 类型追加 `/v1/messages`） |\n| `model` | 模型名称 |\n| `type` | 系统内部参数，用于区分 API 格式转换和认证方式：`openai`（OpenAI 兼容格式）或 `anthropic`（Anthropic 原生格式）。**不是** LiteLLM 的 custom_llm_provider |\n| `provider` | LiteLLM 路由参数，映射为 `custom_llm_provider`。常见值：`\"\"`（空，默认由 type 决定）、`\"volcengine\"`（火山引擎）。填写后模型名无需加厂商前缀 |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"`。**注意**：该参数的实际效果与模型基础能力强相关，不同模型的最优值差异很大，需实测确定（详见下方\"reasoning_effort 配置与测试指南\"） |\n| `litellm_kwargs` | 厂商特有参数，JSON 对象格式，原样透传给 LiteLLM。用于传递各厂商 SDK 要求的额外参数（如火山引擎的 `thinking`、`allowed_openai_params` 等）。代码不做任何厂商判断，只负责透传 |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**火山方舟(Ark)端点配置说明**\n\n火山方舟提供两种计费端点，模型池相同，但功能权限有差异：\n\n| 端点 | 地址 | 计费 | response_format | 适用场景 |\n|------|------|------|-----------------|----------|\n| 标准端点 | `https://ark.cn-beijing.volces.com/api/v3` | 按量计费 | 支持 | 主 Agent、LightRAG |\n| Coding Plan | `https://ark.cn-beijing.volces.com/api/coding/v3` | 包月计费 | **不支持**（网关 400 拒绝） | 主 Agent |\n\n**格式化输出（response_format）能力自动探测**\n\n设置窗口\"测试连接并保存\"按钮在测试通过后，会自动追加一次格式化输出能力探测，按 3 档递进调用真实 LLM，找出当前配置支持的最强档位：\n\n| 档位 | response_format.type | 约束 | 典型支持厂商 |\n|------|---------------------|------|--------------|\n| Tier 1（最强） | `json_schema` strict | 输出严格匹配 schema | OpenAI 真正支持 |\n| Tier 2（中等） | `json_object` | 输出合法 JSON，不约束字段 | OpenAI、DeepSeek |\n| Tier 3（最弱） | 无 response_format | prompt + `json_repair` 客户端容错 | 所有厂商兜底 |\n\n**探测流程**：从 Tier 1 开始测，失败则降级测 Tier 2，再失败则定为 Tier 3。每档失败条件：\n- `model_rejected`：LiteLLM 抛 `BadRequestError`/`UnsupportedParamsError`（模型/网关 4xx 拒绝，如豆包 Coding Plan）\n- `gateway_blocked`：网关返回 200 但响应非合法 JSON（网关接受参数但模型输出漂移，如 GLM xopglm5）\n\n**写入配置**：\n- `lightrag_llm.litellm_kwargs.response_format_mode`：`\"json_schema\"` / `\"json_object\"` / `\"prompt_only\"`\n- `lightrag_llm.litellm_kwargs.allowed_openai_params`：前两档 `[\"response_format\"]`，prompt_only 档 `[]`（双写兼容旧逻辑）\n\n**典型场景**（2026-07-19 实测）：\n- 豆包 Coding Plan 端点（`/api/coding/v3`，model=`ark-code-latest`）：网关 400 拒绝 response_format，探测结果 `prompt_only`\n- GLM 端点（`maas-coding-api.cn-huabei-1.xf-yun.com/v2`，model=`xopglm5`）：网关接受但模型输出漂移，探测结果 `prompt_only`\n- OpenAI 官方：探测结果 `json_schema`\n\n**升级后自动探测**：旧版本用户配置无 `response_format_mode` 字段。程序启动后若检测到该字段缺失，后台自动触发一次探测写入配置，不阻塞启动。\n\n**手动覆盖**：关闭程序后手动编辑 `config/user-config.json` 的 `lightrag_llm.litellm_kwargs.response_format_mode`。下次设置窗口测试保存会覆盖手动值。\n\n**注意**：\n- 探测调用会消耗约 100-200 token（最坏情况测到 Tier 2）。仅\"测试连接并保存\"按钮触发，不引入后台定时探测（升级后首次启动除外）。\n- 探测独立于启动时的 LLM 连通性测试（`/api/test-llm`），不影响启动速度。\n\n> **重要**：LightRAG 的 keyword_extraction 依赖 `response_format`，必须使用标准端点。如果误用 Coding Plan 端点，本次升级后的\"格式化输出能力自动探测\"会识别为 `prompt_only` 档位并写入配置，运行时 LightRAG 直接走 prompt-only 路径（不再每次发无效请求触发 400 后 fallback）。详见上方\"格式化输出（response_format）能力自动探测\"小节。\n\n**火山方舟深度思考模型 + 工具调用配置**（重要）：\n\n火山方舟的 `doubao-seed` 系列模型（包括 `ark-code-latest`）默认启用深度思考模式。当 `litellm_kwargs` 中未显式传递 `thinking` 参数时，API 没有结构化工具调用保障——模型偶发将 tool_call 放入 `reasoning_content` 的 `<seed:tool_call>` XML 格式，而非标准的 `tool_calls` 字段，导致工具调用丢失。\n\n**主 Agent 必须配置**：\n```json\n\"llm\": {\n  ...\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n| `thinking` 值 | 效果 | 适用场景 |\n|---------------|------|----------|\n| `{\"type\": \"enabled\"}` | 显式启用深度思考，API 网关保障 tool_call 走标准通道 | **主 Agent（必须）** |\n| `{\"type\": \"disabled\"}` | 禁用深度思考 | LightRAG 入库（需配合 `response_format`） |\n| `{\"type\": \"auto\"}` | 模型自行决定 | 不推荐（行为不确定） |\n| 不传 | 模型默认启用思考，但无 tool_call 保障 | **危险：工具调用可能丢失** |\n\n> **注意**：`thinking` 参数通过 `litellm_kwargs` 原样透传给 LiteLLM，再由 VolcEngine 适配器转为 API 请求的 `extra_body.thinking` 字段。代码不做任何厂商判断，所有厂商特有参数都走这个透传通道。\n\n**模型名格式差异**：\n\n两种端点的模型池相同，但模型名格式不同：\n\n| 端点 | 模型名格式 | 示例 |\n|------|-----------|------|\n| 标准端点 | 带日期后缀的全名 | `doubao-seed-2-0-pro-260215` |\n| Coding Plan | 简短别名 | `doubao-seed-2.0-pro` |\n\n> **注意**：在标准端点上使用 Coding Plan 的简短别名会返回 404；反之，在 Coding Plan 端点上两种格式都能用。\n\n**LiteLLM 路由配置**：\n\n使用 LiteLLM 调用火山方舟模型时，必须通过 `provider: \"volcengine\"` 走 VolcEngine 适配器路由。这是 LiteLLM 的标准机制：\n\n| 配置方式 | 路由 | 结果 |\n|----------|------|------|\n| `provider: \"volcengine\"` + `model: \"doubao-seed-2.0-pro\"` | VolcEngine 适配器 | 正确：`thinking` 参数自动处理，厂商特有参数通过 `litellm_kwargs` 透传 |\n| `model: \"volcengine/doubao-seed-2.0-pro\"`（无 provider） | VolcEngine 适配器 | 也可：LiteLLM 通过前缀推断路由，但不如 `provider` 显式 |\n| `model: \"doubao-seed-2.0-pro\"`（无 provider 无前缀） | OpenAI 适配器 | **错误**：`thinking` 等火山特有参数无法传递 |\n\n> **注意**：`type: \"openai\"` 是系统内部参数（区分 Anthropic/OpenAI 格式转换），不是 LiteLLM 的 `custom_llm_provider`。两者独立：`type` 控制格式，`provider` 控制路由。\n\n**可用模型**：doubao-seed-2.0-code、doubao-seed-2.0-pro、doubao-seed-2.0-lite、minimax-m2.7、minimax-m3、glm-5.1、kimi-k2.6、deepseek-v4-pro、deepseek-v4-flash、ark-code-latest\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-seed-2.0-pro`（Coding Plan 别名）或 `doubao-seed-2-0-pro-260215`（标准端点全名） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `provider` | LiteLLM 路由参数，同 `llm` 段说明。火山引擎填 `\"volcengine\"` | `\"\"` 或 `\"volcengine\"` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n| `temperature` | LLM 采样温度。0.0 完全确定性，1.0 高随机度。为空时由系统兜底 0.2 | `0.2`（实体/关系抽取建议低温度避免 JSON 漂移） |\n| `litellm_kwargs` | 厂商特有参数，同 `llm` 段说明。火山引擎知识图谱需传 `thinking` 和 `allowed_openai_params` | `{}` 或见配置示例 |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n> **温度值说明**：LightRAG 调 LLM 时如果不配 `temperature` 字段，系统兜底默认 `0.2`。这是为实体抽取、关系抽取等结构化任务优化的低温度值，避免高随机度导致 JSON 格式漂移、实体名不一致。如果需要更稳定的输出可设 `0.0`，需要更多创造性可设 `0.5~0.7`，但不建议超过 `1.0`。主 Agent / 子 Agent 的温度值在提示词文档里独立配置（主 Agent 0.6、子 Agent 多数 0.2），与此处的 `lightrag_llm.temperature` 完全独立，互不影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用思考链 | 能力强的模型（自带足够推理能力） |\n| `low` | 浅层推理 | **多数模型入库时的最优值**（实测推荐） |\n| `medium` | 中等推理 | 非入库的图谱查询任务；部分模型入库也可用 |\n| `high` | 深度推理 | 不建议用于入库（推理预算耗尽，输出质量反而下降） |\n| `xhigh` | 最深推理 | 不建议用于入库 |\n\n**reasoning_effort 配置与测试指南**：\n\n`reasoning_effort` 的最优值与模型基础能力强相关，不存在通用最优值。实测数据（ark-code-latest 模型入库 SYSTEM_MANUAL.md）：\n\n| 配置 | 实体类型准确率 | 空响应率 | 补充提取有效性 | 综合评分 |\n|------|--------------|---------|--------------|---------|\n| `none` | 67% | 60% | 无 | 5.5/10 |\n| `low` | 95% | 40% | 有效 | **7.5/10** |\n| `medium` | 14% | 40% | 部分 | 6.0/10 |\n| `high` | 分裂 | 40% | 无 | 4.0/10 |\n\n关键发现：\n1. **推理越深不一定越好**：推理token被模型内部消耗，不转化为输出质量。过度推理反而导致实体类型误分类（如子Agent被归为organization而非technology）\n2. **补充提取受影响**：高推理级别下模型过度自信，判断\"无需补充\"，导致遗漏无法弥补\n3. **不同模型差异很大**：能力强的模型（如 Claude、GPT-4o）在 `none` 或 `low` 即可高质量提取；能力有限的模型可能需要 `medium`，但也可能适得其反\n\n**换模型后必须实测**：更改模型或 reasoning_effort 后，用同一文档入库并检查日志验证效果。\n\n**入库质量检查方法**：\n1. 入库后检查日志目录 `logs/raw_http/YYYYMMDD/`，读取 `*_response.json` 文件\n2. 检查空响应：响应体仅含 `<|COMPLETE|>` 或 content 为空，说明该轮提取失败\n3. 检查实体类型：子Agent应为 technology 而非 person/organization；MCP服务器应为 technology 而非 organization\n4. 检查违规节点：不应出现与 niu 根节点重名的实体\n5. 检查补充提取：`*_response.json` 中补充提取应有实质内容（非仅 `<|COMPLETE|>`）\n6. 如发现问题，调整 reasoning_effort 重新入库测试\n\n**配置示例**：\n\n主 Agent 用火山方舟 Coding Plan（完整配置）：\n```json\n\"llm\": {\n  \"presetId\": \"ark-code-latest\",\n  \"apiKey\": \"你的API Key\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/coding/v3\",\n  \"model\": \"ark-code-latest\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"\",\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3\",\n  \"model\": \"doubao-seed-2-0-pro-260215\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"disabled\"},\n    \"allowed_openai_params\": [\"response_format\"]\n  }\n}\n```\n\n> **注意**：LightRAG 必须使用标准端点（apiBase 含 /api/v3），不能用 Coding Plan 端点（/api/coding/v3），因为 Coding Plan 网关 400 拒绝 response_format。设置窗口\"测试连接并保存\"会自动探测并写入 `response_format_mode=prompt_only`（豆包 Coding Plan 场景）。model 必须用标准端点的全名格式（带日期后缀）。\n> **LiteLLM 路由**：`provider: \"volcengine\"` 让 LiteLLM 走 VolcEngine 适配器。`litellm_kwargs` 中的 `thinking: {\"type\": \"disabled\"}` 关闭思考链（火山要求使用 response_format 时必须关闭），`allowed_openai_params: [\"response_format\"]` 让 VolcEngine 适配器透传 response_format 参数。\n\n场景二：主 Agent 和 LightRAG 用同一模型，独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n场景三：能力强的模型，禁用思考链即可（如 Claude、GPT-4o）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"none\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 上下文配置\n\n**配置文件**：`config/user-config.json` 中的 `context` 段\n\n```json\n{\n  \"context\": {\n    \"contextWindowSize\": 200000,\n    \"warningThreshold\": 0.8,\n    \"targetThreshold\": 0.5,\n    \"sleepTriggerMinutes\": 5\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 默认值 | 范围 |\n|------|------|--------|------|\n| `contextWindowSize` | 模型上下文窗口大小（tokens） | 200000 | 32000 ~ 2000000 |\n| `warningThreshold` | 溢出警告阈值，上下文使用率超过此值触发压缩 | 0.8 | 0.0 ~ 1.0 |\n| `targetThreshold` | 强制压缩目标，压缩后上下文使用率降至此值 | 0.5 | 0.0 ~ 1.0 |\n| `sleepTriggerMinutes` | 空闲多久后触发睡眠整理（分钟） | 5 | > 0 |\n\n**常见模型的 contextWindowSize**：\n\n| 模型 | 上下文窗口 | 配置值 |\n|------|-----------|--------|\n| GPT-4o-mini | 128K | 128000 |\n| GPT-4o | 128K | 128000 |\n| Claude 3.5 Sonnet | 200K | 200000 |\n| DeepSeek V3 (deepseek-chat) | 64K | 64000 |\n| DeepSeek R1 (deepseek-reasoner) | 128K | 128000 |\n| Qwen2.5-Turbo | 1M | 1000000 |\n| 本地 Ollama 模型 | 取决于模型 | 按实际配置 |\n\n> **注意**：`contextWindowSize` 与模型强相关，切换模型后需同步更新此值。设置窗口主界面可直接配置此值，高级选项中可配置溢出阈值等参数。\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出，`contextWindowSize` 在主界面，阈值参数点\"高级选项\"展开）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.4 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.5 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.5 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Excel | .xlsx | 支持 |\n| PowerPoint | .pptx | 支持 |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| HTML | .html | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.6 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 10 条（1 条工作便签 + 9 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（知识图谱 LightRAG）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索 + 知识图谱关联，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.7 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.8 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "b9feb11264ad30ebd6da61e7de248ddeaa41a787": {"t": 1785764513.776408, "n": 18469, "h": "4a1485424de59d8d", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nRust 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"\",\n    \"litellm_kwargs\": {}\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"none\",\n    \"litellm_kwargs\": {}\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点基础地址（不含路径后缀，LiteLLM 会自动追加：openai 类型追加 `/chat/completions`，anthropic 类型追加 `/v1/messages`） |\n| `model` | 模型名称 |\n| `type` | 系统内部参数，用于区分 API 格式转换和认证方式：`openai`（OpenAI 兼容格式）或 `anthropic`（Anthropic 原生格式）。**不是** LiteLLM 的 custom_llm_provider |\n| `provider` | LiteLLM 路由参数，映射为 `custom_llm_provider`。常见值：`\"\"`（空，默认由 type 决定）、`\"volcengine\"`（火山引擎）。填写后模型名无需加厂商前缀 |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"`。**注意**：该参数的实际效果与模型基础能力强相关，不同模型的最优值差异很大，需实测确定（详见下方\"reasoning_effort 配置与测试指南\"） |\n| `litellm_kwargs` | 厂商特有参数，JSON 对象格式，原样透传给 LiteLLM。用于传递各厂商 SDK 要求的额外参数（如火山引擎的 `thinking`、`allowed_openai_params` 等）。代码不做任何厂商判断，只负责透传 |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**火山方舟(Ark)端点配置说明**\n\n火山方舟提供两种计费端点，模型池相同，但功能权限有差异：\n\n| 端点 | 地址 | 计费 | response_format | 适用场景 |\n|------|------|------|-----------------|----------|\n| 标准端点 | `https://ark.cn-beijing.volces.com/api/v3` | 按量计费 | 支持 | 主 Agent、LightRAG |\n| Coding Plan | `https://ark.cn-beijing.volces.com/api/coding/v3` | 包月计费 | **不支持**（网关接受参数但不执行，2026-07-21 实测） | 主 Agent |\n\n**格式化输出（response_format）能力自动探测**\n\n设置窗口\"测试连接并保存\"按钮在测试通过后，会自动追加一次格式化输出能力探测，按 3 档递进调用真实 LLM，找出当前配置支持的最强档位：\n\n| 档位 | response_format.type | 约束 | 典型支持厂商 |\n|------|---------------------|------|--------------|\n| Tier 1（最强） | `json_schema` strict | 输出严格匹配 schema | OpenAI 真正支持 |\n| Tier 2（中等） | `json_object` | 输出合法 JSON，不约束字段 | OpenAI、DeepSeek |\n| Tier 3（最弱） | 无 response_format | prompt + `json_repair` 客户端容错 | 所有厂商兜底 |\n\n**探测流程**：从 Tier 1 开始测，失败则降级测 Tier 2，再失败则定为 Tier 3。每档失败条件：\n- `model_rejected`：LiteLLM 抛 `BadRequestError`/`UnsupportedParamsError`（模型/网关 4xx 拒绝，如豆包 Coding Plan）\n- `gateway_blocked`：网关返回 200 但响应非合法 JSON（网关接受参数但模型输出漂移，如 GLM xopglm5）\n\n探测采用冲突式设计：schema 强制要求 `{\"verdict\": \"SCHEMA_ENFORCED\"}`，prompt 却要求模型写普通英文句子且禁止输出 JSON——只有 schema 战胜 prompt（输出被强制为 schema JSON）才判定真支持，模型跟随 prompt 输出普通文本即判定网关静默忽略。该设计防\"网关静默接受但不执行\"导致的假阳性（2026-07-21 豆包实测行为）。\n\n**写入配置**：\n- `lightrag_llm.litellm_kwargs.response_format_mode`：`\"json_schema\"` / `\"json_object\"` / `\"prompt_only\"`\n- `lightrag_llm.litellm_kwargs.allowed_openai_params`：前两档 `[\"response_format\"]`，prompt_only 档 `[]`（双写兼容旧逻辑）\n\n**典型场景**（2026-07-19 实测）：\n- 豆包 Coding Plan 端点（`/api/coding/v3`，model=`ark-code-latest`）：07-19 网关 400 拒绝 response_format；07-21 起网关改为静默接受但不执行（冲突测试实锤 schema 被无视），探测结果 `prompt_only`\n- GLM 端点（`maas-coding-api.cn-huabei-1.xf-yun.com/v2`，model=`xopglm5`）：网关接受但模型输出漂移，探测结果 `prompt_only`\n- OpenAI 官方：探测结果 `json_schema`\n\n**升级后自动探测**：旧版本用户配置无 `response_format_mode` 字段。程序启动后若检测到该字段缺失，后台自动触发一次探测写入配置，不阻塞启动。\n\n**手动覆盖**：关闭程序后手动编辑 `config/user-config.json` 的 `lightrag_llm.litellm_kwargs.response_format_mode`。下次设置窗口测试保存会覆盖手动值。\n\n**注意**：\n- 探测调用会消耗约 100-200 token（最坏情况测到 Tier 2）。仅\"测试连接并保存\"按钮触发，不引入后台定时探测（升级后首次启动除外）。\n- 探测独立于启动时的 LLM 连通性测试（`/api/test-llm`），不影响启动速度。\n\n> **重要**：LightRAG 的 keyword_extraction 依赖 `response_format`，必须使用标准端点。如果误用 Coding Plan 端点，本次升级后的\"格式化输出能力自动探测\"会识别为 `prompt_only` 档位并写入配置，运行时 LightRAG 直接走 prompt-only 路径（不再每次发无效请求试探网关）。详见上方\"格式化输出（response_format）能力自动探测\"小节。\n\n**火山方舟深度思考模型 + 工具调用配置**（重要）：\n\n火山方舟的 `doubao-seed` 系列模型（包括 `ark-code-latest`）默认启用深度思考模式。当 `litellm_kwargs` 中未显式传递 `thinking` 参数时，API 没有结构化工具调用保障——模型偶发将 tool_call 放入 `reasoning_content` 的 `<seed:tool_call>` XML 格式，而非标准的 `tool_calls` 字段，导致工具调用丢失。\n\n**主 Agent 必须配置**：\n```json\n\"llm\": {\n  ...\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n| `thinking` 值 | 效果 | 适用场景 |\n|---------------|------|----------|\n| `{\"type\": \"enabled\"}` | 显式启用深度思考，API 网关保障 tool_call 走标准通道 | **主 Agent（必须）** |\n| `{\"type\": \"disabled\"}` | 禁用深度思考 | LightRAG 入库（需配合 `response_format`） |\n| `{\"type\": \"auto\"}` | 模型自行决定 | 不推荐（行为不确定） |\n| 不传 | 模型默认启用思考，但无 tool_call 保障 | **危险：工具调用可能丢失** |\n\n> **注意**：`thinking` 参数通过 `litellm_kwargs` 原样透传给 LiteLLM，再由 VolcEngine 适配器转为 API 请求的 `extra_body.thinking` 字段。代码不做任何厂商判断，所有厂商特有参数都走这个透传通道。\n\n**模型名格式差异**：\n\n两种端点的模型池相同，但模型名格式不同：\n\n| 端点 | 模型名格式 | 示例 |\n|------|-----------|------|\n| 标准端点 | 带日期后缀的全名 | `doubao-seed-2-0-pro-260215` |\n| Coding Plan | 简短别名 | `doubao-seed-2.0-pro` |\n\n> **注意**：在标准端点上使用 Coding Plan 的简短别名会返回 404；反之，在 Coding Plan 端点上两种格式都能用。\n\n**LiteLLM 路由配置**：\n\n使用 LiteLLM 调用火山方舟模型时，必须通过 `provider: \"volcengine\"` 走 VolcEngine 适配器路由。这是 LiteLLM 的标准机制：\n\n| 配置方式 | 路由 | 结果 |\n|----------|------|------|\n| `provider: \"volcengine\"` + `model: \"doubao-seed-2.0-pro\"` | VolcEngine 适配器 | 正确：`thinking` 参数自动处理，厂商特有参数通过 `litellm_kwargs` 透传 |\n| `model: \"volcengine/doubao-seed-2.0-pro\"`（无 provider） | VolcEngine 适配器 | 也可：LiteLLM 通过前缀推断路由，但不如 `provider` 显式 |\n| `model: \"doubao-seed-2.0-pro\"`（无 provider 无前缀） | OpenAI 适配器 | **错误**：`thinking` 等火山特有参数无法传递 |\n\n> **注意**：`type: \"openai\"` 是系统内部参数（区分 Anthropic/OpenAI 格式转换），不是 LiteLLM 的 `custom_llm_provider`。两者独立：`type` 控制格式，`provider` 控制路由。\n\n**可用模型**：doubao-seed-2.0-code、doubao-seed-2.0-pro、doubao-seed-2.0-lite、minimax-m2.7、minimax-m3、glm-5.1、kimi-k2.6、deepseek-v4-pro、deepseek-v4-flash、ark-code-latest\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-seed-2.0-pro`（Coding Plan 别名）或 `doubao-seed-2-0-pro-260215`（标准端点全名） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `provider` | LiteLLM 路由参数，同 `llm` 段说明。火山引擎填 `\"volcengine\"` | `\"\"` 或 `\"volcengine\"` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n| `temperature` | LLM 采样温度。0.0 完全确定性，1.0 高随机度。为空时由系统兜底 0.2 | `0.2`（实体/关系抽取建议低温度避免 JSON 漂移） |\n| `litellm_kwargs` | 厂商特有参数，同 `llm` 段说明。火山引擎知识图谱需传 `thinking` 和 `allowed_openai_params` | `{}` 或见配置示例 |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n> **温度值说明**：LightRAG 调 LLM 时如果不配 `temperature` 字段，系统兜底默认 `0.2`。这是为实体抽取、关系抽取等结构化任务优化的低温度值，避免高随机度导致 JSON 格式漂移、实体名不一致。如果需要更稳定的输出可设 `0.0`，需要更多创造性可设 `0.5~0.7`，但不建议超过 `1.0`。主 Agent / 子 Agent 的温度值在提示词文档里独立配置（主 Agent 0.6、子 Agent 多数 0.2），与此处的 `lightrag_llm.temperature` 完全独立，互不影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用思考链 | 能力强的模型（自带足够推理能力） |\n| `low` | 浅层推理 | **多数模型入库时的最优值**（实测推荐） |\n| `medium` | 中等推理 | 非入库的图谱查询任务；部分模型入库也可用 |\n| `high` | 深度推理 | 不建议用于入库（推理预算耗尽，输出质量反而下降） |\n| `xhigh` | 最深推理 | 不建议用于入库 |\n\n**reasoning_effort 配置与测试指南**：\n\n`reasoning_effort` 的最优值与模型基础能力强相关，不存在通用最优值。实测数据（ark-code-latest 模型入库 SYSTEM_MANUAL.md）：\n\n| 配置 | 实体类型准确率 | 空响应率 | 补充提取有效性 | 综合评分 |\n|------|--------------|---------|--------------|---------|\n| `none` | 67% | 60% | 无 | 5.5/10 |\n| `low` | 95% | 40% | 有效 | **7.5/10** |\n| `medium` | 14% | 40% | 部分 | 6.0/10 |\n| `high` | 分裂 | 40% | 无 | 4.0/10 |\n\n关键发现：\n1. **推理越深不一定越好**：推理token被模型内部消耗，不转化为输出质量。过度推理反而导致实体类型误分类（如子Agent被归为organization而非technology）\n2. **补充提取受影响**：高推理级别下模型过度自信，判断\"无需补充\"，导致遗漏无法弥补\n3. **不同模型差异很大**：能力强的模型（如 Claude、GPT-4o）在 `none` 或 `low` 即可高质量提取；能力有限的模型可能需要 `medium`，但也可能适得其反\n\n**换模型后必须实测**：更改模型或 reasoning_effort 后，用同一文档入库并检查日志验证效果。\n\n**入库质量检查方法**：\n1. 入库后检查日志目录 `logs/raw_http/YYYYMMDD/`，读取 `*_response.json` 文件\n2. 检查空响应：响应体仅含 `<|COMPLETE|>` 或 content 为空，说明该轮提取失败\n3. 检查实体类型：子Agent应为 technology 而非 person/organization；MCP服务器应为 technology 而非 organization\n4. 检查违规节点：不应出现与 niu 根节点重名的实体\n5. 检查补充提取：`*_response.json` 中补充提取应有实质内容（非仅 `<|COMPLETE|>`）\n6. 如发现问题，调整 reasoning_effort 重新入库测试\n\n**配置示例**：\n\n主 Agent 用火山方舟 Coding Plan（完整配置）：\n```json\n\"llm\": {\n  \"presetId\": \"ark-code-latest\",\n  \"apiKey\": \"你的API Key\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/coding/v3\",\n  \"model\": \"ark-code-latest\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"\",\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3\",\n  \"model\": \"doubao-seed-2-0-pro-260215\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"disabled\"},\n    \"allowed_openai_params\": [\"response_format\"]\n  }\n}\n```\n\n> **注意**：LightRAG 必须使用标准端点（apiBase 含 /api/v3），不能用 Coding Plan 端点（/api/coding/v3），因为 Coding Plan 网关 400 拒绝 response_format。设置窗口\"测试连接并保存\"会自动探测并写入 `response_format_mode=prompt_only`（豆包 Coding Plan 场景）。model 必须用标准端点的全名格式（带日期后缀）。\n> **LiteLLM 路由**：`provider: \"volcengine\"` 让 LiteLLM 走 VolcEngine 适配器。`litellm_kwargs` 中的 `thinking: {\"type\": \"disabled\"}` 关闭思考链（火山要求使用 response_format 时必须关闭），`allowed_openai_params: [\"response_format\"]` 让 VolcEngine 适配器透传 response_format 参数。\n\n场景二：主 Agent 和 LightRAG 用同一模型，独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n场景三：能力强的模型，禁用思考链即可（如 Claude、GPT-4o）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"none\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 上下文配置\n\n**配置文件**：`config/user-config.json` 中的 `context` 段\n\n```json\n{\n  \"context\": {\n    \"contextWindowSize\": 200000,\n    \"warningThreshold\": 0.8,\n    \"targetThreshold\": 0.5,\n    \"sleepTriggerMinutes\": 5\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 默认值 | 范围 |\n|------|------|--------|------|\n| `contextWindowSize` | 模型上下文窗口大小（tokens） | 200000 | 32000 ~ 2000000 |\n| `warningThreshold` | 溢出警告阈值，上下文使用率超过此值触发压缩 | 0.8 | 0.0 ~ 1.0 |\n| `targetThreshold` | 强制压缩目标，压缩后上下文使用率降至此值 | 0.5 | 0.0 ~ 1.0 |\n| `sleepTriggerMinutes` | 空闲多久后触发睡眠整理（分钟） | 5 | > 0 |\n\n**常见模型的 contextWindowSize**：\n\n| 模型 | 上下文窗口 | 配置值 |\n|------|-----------|--------|\n| GPT-4o-mini | 128K | 128000 |\n| GPT-4o | 128K | 128000 |\n| Claude 3.5 Sonnet | 200K | 200000 |\n| DeepSeek V3 (deepseek-chat) | 64K | 64000 |\n| DeepSeek R1 (deepseek-reasoner) | 128K | 128000 |\n| Qwen2.5-Turbo | 1M | 1000000 |\n| 本地 Ollama 模型 | 取决于模型 | 按实际配置 |\n\n> **注意**：`contextWindowSize` 与模型强相关，切换模型后需同步更新此值。设置窗口主界面可直接配置此值，高级选项中可配置溢出阈值等参数。\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出，`contextWindowSize` 在主界面，阈值参数点\"高级选项\"展开）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.4 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.5 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.5 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Excel | .xlsx | 支持 |\n| PowerPoint | .pptx | 支持 |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| HTML | .html | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.6 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 10 条（1 条工作便签 + 9 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（知识图谱 LightRAG）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索 + 知识图谱关联，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.7 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.8 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "5270ffad9b0b3b15990523e8f7dfaaceb1602a61": {"t": 1785764515.4012291, "n": 18218, "h": "6ab14eb1c42d9797", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nRust 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"\",\n    \"litellm_kwargs\": {}\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"none\",\n    \"litellm_kwargs\": {}\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点基础地址（不含路径后缀，LiteLLM 会自动追加：openai 类型追加 `/chat/completions`，anthropic 类型追加 `/v1/messages`） |\n| `model` | 模型名称 |\n| `type` | 系统内部参数，用于区分 API 格式转换和认证方式：`openai`（OpenAI 兼容格式）或 `anthropic`（Anthropic 原生格式）。**不是** LiteLLM 的 custom_llm_provider |\n| `provider` | LiteLLM 路由参数，映射为 `custom_llm_provider`。常见值：`\"\"`（空，默认由 type 决定）、`\"volcengine\"`（火山引擎）。填写后模型名无需加厂商前缀 |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"`。**注意**：该参数的实际效果与模型基础能力强相关，不同模型的最优值差异很大，需实测确定（详见下方\"reasoning_effort 配置与测试指南\"） |\n| `litellm_kwargs` | 厂商特有参数，JSON 对象格式，原样透传给 LiteLLM。用于传递各厂商 SDK 要求的额外参数（如火山引擎的 `thinking`、`allowed_openai_params` 等）。代码不做任何厂商判断，只负责透传 |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**火山方舟(Ark)端点配置说明**\n\n火山方舟提供两种计费端点，模型池相同，但功能权限有差异：\n\n| 端点 | 地址 | 计费 | response_format | 适用场景 |\n|------|------|------|-----------------|----------|\n| 标准端点 | `https://ark.cn-beijing.volces.com/api/v3` | 按量计费 | 支持 | 主 Agent、LightRAG |\n| Coding Plan | `https://ark.cn-beijing.volces.com/api/coding/v3` | 包月计费 | **不支持**（网关 400 拒绝） | 主 Agent |\n\n**格式化输出（response_format）能力自动探测**\n\n设置窗口\"测试连接并保存\"按钮在测试通过后，会自动追加一次格式化输出能力探测，按 3 档递进调用真实 LLM，找出当前配置支持的最强档位：\n\n| 档位 | response_format.type | 约束 | 典型支持厂商 |\n|------|---------------------|------|--------------|\n| Tier 1（最强） | `json_schema` strict | 输出严格匹配 schema | OpenAI 真正支持 |\n| Tier 2（中等） | `json_object` | 输出合法 JSON，不约束字段 | OpenAI、DeepSeek |\n| Tier 3（最弱） | 无 response_format | prompt + `json_repair` 客户端容错 | 所有厂商兜底 |\n\n**探测流程**：从 Tier 1 开始测，失败则降级测 Tier 2，再失败则定为 Tier 3。每档失败条件：\n- `model_rejected`：LiteLLM 抛 `BadRequestError`/`UnsupportedParamsError`（模型/网关 4xx 拒绝，如豆包 Coding Plan）\n- `gateway_blocked`：网关返回 200 但响应非合法 JSON（网关接受参数但模型输出漂移，如 GLM xopglm5）\n\n**写入配置**：\n- `lightrag_llm.litellm_kwargs.response_format_mode`：`\"json_schema\"` / `\"json_object\"` / `\"prompt_only\"`\n- `lightrag_llm.litellm_kwargs.allowed_openai_params`：前两档 `[\"response_format\"]`，prompt_only 档 `[]`（双写兼容旧逻辑）\n\n**典型场景**（2026-07-19 实测）：\n- 豆包 Coding Plan 端点（`/api/coding/v3`，model=`ark-code-latest`）：网关 400 拒绝 response_format，探测结果 `prompt_only`\n- GLM 端点（`maas-coding-api.cn-huabei-1.xf-yun.com/v2`，model=`xopglm5`）：网关接受但模型输出漂移，探测结果 `prompt_only`\n- OpenAI 官方：探测结果 `json_schema`\n\n**升级后自动探测**：旧版本用户配置无 `response_format_mode` 字段。程序启动后若检测到该字段缺失，后台自动触发一次探测写入配置，不阻塞启动。\n\n**手动覆盖**：关闭程序后手动编辑 `config/user-config.json` 的 `lightrag_llm.litellm_kwargs.response_format_mode`。下次设置窗口测试保存会覆盖手动值。\n\n**注意**：\n- 探测调用会消耗约 100-200 token（最坏情况测到 Tier 2）。仅\"测试连接并保存\"按钮触发，不引入后台定时探测（升级后首次启动除外）。\n- 探测独立于启动时的 LLM 连通性测试（`/api/test-llm`），不影响启动速度。\n\n> **重要**：LightRAG 的 keyword_extraction 依赖 `response_format`，必须使用标准端点。如果误用 Coding Plan 端点，本次升级后的\"格式化输出能力自动探测\"会识别为 `prompt_only` 档位并写入配置，运行时 LightRAG 直接走 prompt-only 路径（不再每次发无效请求触发 400 后 fallback）。详见上方\"格式化输出（response_format）能力自动探测\"小节。\n\n**火山方舟深度思考模型 + 工具调用配置**（重要）：\n\n火山方舟的 `doubao-seed` 系列模型（包括 `ark-code-latest`）默认启用深度思考模式。当 `litellm_kwargs` 中未显式传递 `thinking` 参数时，API 没有结构化工具调用保障——模型偶发将 tool_call 放入 `reasoning_content` 的 `<seed:tool_call>` XML 格式，而非标准的 `tool_calls` 字段，导致工具调用丢失。\n\n**主 Agent 必须配置**：\n```json\n\"llm\": {\n  ...\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n| `thinking` 值 | 效果 | 适用场景 |\n|---------------|------|----------|\n| `{\"type\": \"enabled\"}` | 显式启用深度思考，API 网关保障 tool_call 走标准通道 | **主 Agent（必须）** |\n| `{\"type\": \"disabled\"}` | 禁用深度思考 | LightRAG 入库（需配合 `response_format`） |\n| `{\"type\": \"auto\"}` | 模型自行决定 | 不推荐（行为不确定） |\n| 不传 | 模型默认启用思考，但无 tool_call 保障 | **危险：工具调用可能丢失** |\n\n> **注意**：`thinking` 参数通过 `litellm_kwargs` 原样透传给 LiteLLM，再由 VolcEngine 适配器转为 API 请求的 `extra_body.thinking` 字段。代码不做任何厂商判断，所有厂商特有参数都走这个透传通道。\n\n**模型名格式差异**：\n\n两种端点的模型池相同，但模型名格式不同：\n\n| 端点 | 模型名格式 | 示例 |\n|------|-----------|------|\n| 标准端点 | 带日期后缀的全名 | `doubao-seed-2-0-pro-260215` |\n| Coding Plan | 简短别名 | `doubao-seed-2.0-pro` |\n\n> **注意**：在标准端点上使用 Coding Plan 的简短别名会返回 404；反之，在 Coding Plan 端点上两种格式都能用。\n\n**LiteLLM 路由配置**：\n\n使用 LiteLLM 调用火山方舟模型时，必须通过 `provider: \"volcengine\"` 走 VolcEngine 适配器路由。这是 LiteLLM 的标准机制：\n\n| 配置方式 | 路由 | 结果 |\n|----------|------|------|\n| `provider: \"volcengine\"` + `model: \"doubao-seed-2.0-pro\"` | VolcEngine 适配器 | 正确：`thinking` 参数自动处理，厂商特有参数通过 `litellm_kwargs` 透传 |\n| `model: \"volcengine/doubao-seed-2.0-pro\"`（无 provider） | VolcEngine 适配器 | 也可：LiteLLM 通过前缀推断路由，但不如 `provider` 显式 |\n| `model: \"doubao-seed-2.0-pro\"`（无 provider 无前缀） | OpenAI 适配器 | **错误**：`thinking` 等火山特有参数无法传递 |\n\n> **注意**：`type: \"openai\"` 是系统内部参数（区分 Anthropic/OpenAI 格式转换），不是 LiteLLM 的 `custom_llm_provider`。两者独立：`type` 控制格式，`provider` 控制路由。\n\n**可用模型**：doubao-seed-2.0-code、doubao-seed-2.0-pro、doubao-seed-2.0-lite、minimax-m2.7、minimax-m3、glm-5.1、kimi-k2.6、deepseek-v4-pro、deepseek-v4-flash、ark-code-latest\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-seed-2.0-pro`（Coding Plan 别名）或 `doubao-seed-2-0-pro-260215`（标准端点全名） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `provider` | LiteLLM 路由参数，同 `llm` 段说明。火山引擎填 `\"volcengine\"` | `\"\"` 或 `\"volcengine\"` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n| `temperature` | LLM 采样温度。0.0 完全确定性，1.0 高随机度。为空时由系统兜底 0.2 | `0.2`（实体/关系抽取建议低温度避免 JSON 漂移） |\n| `litellm_kwargs` | 厂商特有参数，同 `llm` 段说明。火山引擎知识图谱需传 `thinking` 和 `allowed_openai_params` | `{}` 或见配置示例 |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n> **温度值说明**：LightRAG 调 LLM 时如果不配 `temperature` 字段，系统兜底默认 `0.2`。这是为实体抽取、关系抽取等结构化任务优化的低温度值，避免高随机度导致 JSON 格式漂移、实体名不一致。如果需要更稳定的输出可设 `0.0`，需要更多创造性可设 `0.5~0.7`，但不建议超过 `1.0`。主 Agent / 子 Agent 的温度值在提示词文档里独立配置（主 Agent 0.6、子 Agent 多数 0.2），与此处的 `lightrag_llm.temperature` 完全独立，互不影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用思考链 | 能力强的模型（自带足够推理能力） |\n| `low` | 浅层推理 | **多数模型入库时的最优值**（实测推荐） |\n| `medium` | 中等推理 | 非入库的图谱查询任务；部分模型入库也可用 |\n| `high` | 深度推理 | 不建议用于入库（推理预算耗尽，输出质量反而下降） |\n| `xhigh` | 最深推理 | 不建议用于入库 |\n\n**reasoning_effort 配置与测试指南**：\n\n`reasoning_effort` 的最优值与模型基础能力强相关，不存在通用最优值。实测数据（ark-code-latest 模型入库 SYSTEM_MANUAL.md）：\n\n| 配置 | 实体类型准确率 | 空响应率 | 补充提取有效性 | 综合评分 |\n|------|--------------|---------|--------------|---------|\n| `none` | 67% | 60% | 无 | 5.5/10 |\n| `low` | 95% | 40% | 有效 | **7.5/10** |\n| `medium` | 14% | 40% | 部分 | 6.0/10 |\n| `high` | 分裂 | 40% | 无 | 4.0/10 |\n\n关键发现：\n1. **推理越深不一定越好**：推理token被模型内部消耗，不转化为输出质量。过度推理反而导致实体类型误分类（如子Agent被归为organization而非technology）\n2. **补充提取受影响**：高推理级别下模型过度自信，判断\"无需补充\"，导致遗漏无法弥补\n3. **不同模型差异很大**：能力强的模型（如 Claude、GPT-4o）在 `none` 或 `low` 即可高质量提取；能力有限的模型可能需要 `medium`，但也可能适得其反\n\n**换模型后必须实测**：更改模型或 reasoning_effort 后，用同一文档入库并检查日志验证效果。\n\n**入库质量检查方法**：\n1. 入库后检查日志目录 `logs/raw_http/YYYYMMDD/`，读取 `*_response.json` 文件\n2. 检查空响应：响应体仅含 `<|COMPLETE|>` 或 content 为空，说明该轮提取失败\n3. 检查实体类型：子Agent应为 technology 而非 person/organization；MCP服务器应为 technology 而非 organization\n4. 检查违规节点：不应出现与 niu 根节点重名的实体\n5. 检查补充提取：`*_response.json` 中补充提取应有实质内容（非仅 `<|COMPLETE|>`）\n6. 如发现问题，调整 reasoning_effort 重新入库测试\n\n**配置示例**：\n\n主 Agent 用火山方舟 Coding Plan（完整配置）：\n```json\n\"llm\": {\n  \"presetId\": \"ark-code-latest\",\n  \"apiKey\": \"你的API Key\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/coding/v3\",\n  \"model\": \"ark-code-latest\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"\",\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3\",\n  \"model\": \"doubao-seed-2-0-pro-260215\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"disabled\"},\n    \"allowed_openai_params\": [\"response_format\"]\n  }\n}\n```\n\n> **注意**：LightRAG 必须使用标准端点（apiBase 含 /api/v3），不能用 Coding Plan 端点（/api/coding/v3），因为 Coding Plan 网关 400 拒绝 response_format。设置窗口\"测试连接并保存\"会自动探测并写入 `response_format_mode=prompt_only`（豆包 Coding Plan 场景）。model 必须用标准端点的全名格式（带日期后缀）。\n> **LiteLLM 路由**：`provider: \"volcengine\"` 让 LiteLLM 走 VolcEngine 适配器。`litellm_kwargs` 中的 `thinking: {\"type\": \"disabled\"}` 关闭思考链（火山要求使用 response_format 时必须关闭），`allowed_openai_params: [\"response_format\"]` 让 VolcEngine 适配器透传 response_format 参数。\n\n场景二：主 Agent 和 LightRAG 用同一模型，独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n场景三：能力强的模型，禁用思考链即可（如 Claude、GPT-4o）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"none\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 上下文配置\n\n**配置文件**：`config/user-config.json` 中的 `context` 段\n\n```json\n{\n  \"context\": {\n    \"contextWindowSize\": 200000,\n    \"warningThreshold\": 0.8,\n    \"targetThreshold\": 0.5,\n    \"sleepTriggerMinutes\": 5\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 默认值 | 范围 |\n|------|------|--------|------|\n| `contextWindowSize` | 模型上下文窗口大小（tokens） | 200000 | 32000 ~ 2000000 |\n| `warningThreshold` | 溢出警告阈值，上下文使用率超过此值触发压缩 | 0.8 | 0.0 ~ 1.0 |\n| `targetThreshold` | 强制压缩目标，压缩后上下文使用率降至此值 | 0.5 | 0.0 ~ 1.0 |\n| `sleepTriggerMinutes` | 空闲多久后触发睡眠整理（分钟） | 5 | > 0 |\n\n**常见模型的 contextWindowSize**：\n\n| 模型 | 上下文窗口 | 配置值 |\n|------|-----------|--------|\n| GPT-4o-mini | 128K | 128000 |\n| GPT-4o | 128K | 128000 |\n| Claude 3.5 Sonnet | 200K | 200000 |\n| DeepSeek V3 (deepseek-chat) | 64K | 64000 |\n| DeepSeek R1 (deepseek-reasoner) | 128K | 128000 |\n| Qwen2.5-Turbo | 1M | 1000000 |\n| 本地 Ollama 模型 | 取决于模型 | 按实际配置 |\n\n> **注意**：`contextWindowSize` 与模型强相关，切换模型后需同步更新此值。设置窗口主界面可直接配置此值，高级选项中可配置溢出阈值等参数。\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出，`contextWindowSize` 在主界面，阈值参数点\"高级选项\"展开）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.4 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.5 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.5 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Excel | .xlsx | 支持 |\n| PowerPoint | .pptx | 支持 |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| HTML | .html | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.6 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 10 条（1 条工作便签 + 9 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（知识图谱 LightRAG）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索 + 知识图谱关联，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.7 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.8 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "15e59bcb3cdba2527d2c57c81b72251a3fceaa38": {"t": 1785764516.7174795, "n": 16567, "h": "d7afd0469fe6f171", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nRust 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"\",\n    \"litellm_kwargs\": {}\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"none\",\n    \"litellm_kwargs\": {}\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点基础地址（不含路径后缀，LiteLLM 会自动追加：openai 类型追加 `/chat/completions`，anthropic 类型追加 `/v1/messages`） |\n| `model` | 模型名称 |\n| `type` | 系统内部参数，用于区分 API 格式转换和认证方式：`openai`（OpenAI 兼容格式）或 `anthropic`（Anthropic 原生格式）。**不是** LiteLLM 的 custom_llm_provider |\n| `provider` | LiteLLM 路由参数，映射为 `custom_llm_provider`。常见值：`\"\"`（空，默认由 type 决定）、`\"volcengine\"`（火山引擎）。填写后模型名无需加厂商前缀 |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"`。**注意**：该参数的实际效果与模型基础能力强相关，不同模型的最优值差异很大，需实测确定（详见下方\"reasoning_effort 配置与测试指南\"） |\n| `litellm_kwargs` | 厂商特有参数，JSON 对象格式，原样透传给 LiteLLM。用于传递各厂商 SDK 要求的额外参数（如火山引擎的 `thinking`、`allowed_openai_params` 等）。代码不做任何厂商判断，只负责透传 |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**火山方舟(Ark)端点配置说明**\n\n火山方舟提供两种计费端点，模型池相同，但功能权限有差异：\n\n| 端点 | 地址 | 计费 | response_format | 适用场景 |\n|------|------|------|-----------------|----------|\n| 标准端点 | `https://ark.cn-beijing.volces.com/api/v3` | 按量计费 | 支持 | 主 Agent、LightRAG |\n| Coding Plan | `https://ark.cn-beijing.volces.com/api/coding/v3` | 包月计费 | **不支持**（网关拦截） | 主 Agent |\n\n> **重要**：LightRAG 的 keyword_extraction 依赖 `response_format`，必须使用标准端点。如果误用 Coding Plan 端点，系统会自动 fallback 到纯 prompt JSON 返回（功能正常但多一次无效请求）。\n\n**火山方舟深度思考模型 + 工具调用配置**（重要）：\n\n火山方舟的 `doubao-seed` 系列模型（包括 `ark-code-latest`）默认启用深度思考模式。当 `litellm_kwargs` 中未显式传递 `thinking` 参数时，API 没有结构化工具调用保障——模型偶发将 tool_call 放入 `reasoning_content` 的 `<seed:tool_call>` XML 格式，而非标准的 `tool_calls` 字段，导致工具调用丢失。\n\n**主 Agent 必须配置**：\n```json\n\"llm\": {\n  ...\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n| `thinking` 值 | 效果 | 适用场景 |\n|---------------|------|----------|\n| `{\"type\": \"enabled\"}` | 显式启用深度思考，API 网关保障 tool_call 走标准通道 | **主 Agent（必须）** |\n| `{\"type\": \"disabled\"}` | 禁用深度思考 | LightRAG 入库（需配合 `response_format`） |\n| `{\"type\": \"auto\"}` | 模型自行决定 | 不推荐（行为不确定） |\n| 不传 | 模型默认启用思考，但无 tool_call 保障 | **危险：工具调用可能丢失** |\n\n> **注意**：`thinking` 参数通过 `litellm_kwargs` 原样透传给 LiteLLM，再由 VolcEngine 适配器转为 API 请求的 `extra_body.thinking` 字段。代码不做任何厂商判断，所有厂商特有参数都走这个透传通道。\n\n**模型名格式差异**：\n\n两种端点的模型池相同，但模型名格式不同：\n\n| 端点 | 模型名格式 | 示例 |\n|------|-----------|------|\n| 标准端点 | 带日期后缀的全名 | `doubao-seed-2-0-pro-260215` |\n| Coding Plan | 简短别名 | `doubao-seed-2.0-pro` |\n\n> **注意**：在标准端点上使用 Coding Plan 的简短别名会返回 404；反之，在 Coding Plan 端点上两种格式都能用。\n\n**LiteLLM 路由配置**：\n\n使用 LiteLLM 调用火山方舟模型时，必须通过 `provider: \"volcengine\"` 走 VolcEngine 适配器路由。这是 LiteLLM 的标准机制：\n\n| 配置方式 | 路由 | 结果 |\n|----------|------|------|\n| `provider: \"volcengine\"` + `model: \"doubao-seed-2.0-pro\"` | VolcEngine 适配器 | 正确：`thinking` 参数自动处理，厂商特有参数通过 `litellm_kwargs` 透传 |\n| `model: \"volcengine/doubao-seed-2.0-pro\"`（无 provider） | VolcEngine 适配器 | 也可：LiteLLM 通过前缀推断路由，但不如 `provider` 显式 |\n| `model: \"doubao-seed-2.0-pro\"`（无 provider 无前缀） | OpenAI 适配器 | **错误**：`thinking` 等火山特有参数无法传递 |\n\n> **注意**：`type: \"openai\"` 是系统内部参数（区分 Anthropic/OpenAI 格式转换），不是 LiteLLM 的 `custom_llm_provider`。两者独立：`type` 控制格式，`provider` 控制路由。\n\n**可用模型**：doubao-seed-2.0-code、doubao-seed-2.0-pro、doubao-seed-2.0-lite、minimax-m2.7、minimax-m3、glm-5.1、kimi-k2.6、deepseek-v4-pro、deepseek-v4-flash、ark-code-latest\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-seed-2.0-pro`（Coding Plan 别名）或 `doubao-seed-2-0-pro-260215`（标准端点全名） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `provider` | LiteLLM 路由参数，同 `llm` 段说明。火山引擎填 `\"volcengine\"` | `\"\"` 或 `\"volcengine\"` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n| `temperature` | LLM 采样温度。0.0 完全确定性，1.0 高随机度。为空时由系统兜底 0.2 | `0.2`（实体/关系抽取建议低温度避免 JSON 漂移） |\n| `litellm_kwargs` | 厂商特有参数，同 `llm` 段说明。火山引擎知识图谱需传 `thinking` 和 `allowed_openai_params` | `{}` 或见配置示例 |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n> **温度值说明**：LightRAG 调 LLM 时如果不配 `temperature` 字段，系统兜底默认 `0.2`。这是为实体抽取、关系抽取等结构化任务优化的低温度值，避免高随机度导致 JSON 格式漂移、实体名不一致。如果需要更稳定的输出可设 `0.0`，需要更多创造性可设 `0.5~0.7`，但不建议超过 `1.0`。主 Agent / 子 Agent 的温度值在提示词文档里独立配置（主 Agent 0.6、子 Agent 多数 0.2），与此处的 `lightrag_llm.temperature` 完全独立，互不影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用思考链 | 能力强的模型（自带足够推理能力） |\n| `low` | 浅层推理 | **多数模型入库时的最优值**（实测推荐） |\n| `medium` | 中等推理 | 非入库的图谱查询任务；部分模型入库也可用 |\n| `high` | 深度推理 | 不建议用于入库（推理预算耗尽，输出质量反而下降） |\n| `xhigh` | 最深推理 | 不建议用于入库 |\n\n**reasoning_effort 配置与测试指南**：\n\n`reasoning_effort` 的最优值与模型基础能力强相关，不存在通用最优值。实测数据（ark-code-latest 模型入库 SYSTEM_MANUAL.md）：\n\n| 配置 | 实体类型准确率 | 空响应率 | 补充提取有效性 | 综合评分 |\n|------|--------------|---------|--------------|---------|\n| `none` | 67% | 60% | 无 | 5.5/10 |\n| `low` | 95% | 40% | 有效 | **7.5/10** |\n| `medium` | 14% | 40% | 部分 | 6.0/10 |\n| `high` | 分裂 | 40% | 无 | 4.0/10 |\n\n关键发现：\n1. **推理越深不一定越好**：推理token被模型内部消耗，不转化为输出质量。过度推理反而导致实体类型误分类（如子Agent被归为organization而非technology）\n2. **补充提取受影响**：高推理级别下模型过度自信，判断\"无需补充\"，导致遗漏无法弥补\n3. **不同模型差异很大**：能力强的模型（如 Claude、GPT-4o）在 `none` 或 `low` 即可高质量提取；能力有限的模型可能需要 `medium`，但也可能适得其反\n\n**换模型后必须实测**：更改模型或 reasoning_effort 后，用同一文档入库并检查日志验证效果。\n\n**入库质量检查方法**：\n1. 入库后检查日志目录 `logs/raw_http/YYYYMMDD/`，读取 `*_response.json` 文件\n2. 检查空响应：响应体仅含 `<|COMPLETE|>` 或 content 为空，说明该轮提取失败\n3. 检查实体类型：子Agent应为 technology 而非 person/organization；MCP服务器应为 technology 而非 organization\n4. 检查违规节点：不应出现与 niu 根节点重名的实体\n5. 检查补充提取：`*_response.json` 中补充提取应有实质内容（非仅 `<|COMPLETE|>`）\n6. 如发现问题，调整 reasoning_effort 重新入库测试\n\n**配置示例**：\n\n主 Agent 用火山方舟 Coding Plan（完整配置）：\n```json\n\"llm\": {\n  \"presetId\": \"ark-code-latest\",\n  \"apiKey\": \"你的API Key\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/coding/v3\",\n  \"model\": \"ark-code-latest\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"\",\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3\",\n  \"model\": \"doubao-seed-2-0-pro-260215\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"disabled\"},\n    \"allowed_openai_params\": [\"response_format\"]\n  }\n}\n```\n\n> **注意**：LightRAG 必须使用标准端点（apiBase 含 /api/v3），不能用 Coding Plan 端点（/api/coding/v3），因为 Coding Plan 网关拦截 response_format。model 必须用标准端点的全名格式（带日期后缀）。\n> **LiteLLM 路由**：`provider: \"volcengine\"` 让 LiteLLM 走 VolcEngine 适配器。`litellm_kwargs` 中的 `thinking: {\"type\": \"disabled\"}` 关闭思考链（火山要求使用 response_format 时必须关闭），`allowed_openai_params: [\"response_format\"]` 让 VolcEngine 适配器透传 response_format 参数。\n\n场景二：主 Agent 和 LightRAG 用同一模型，独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n场景三：能力强的模型，禁用思考链即可（如 Claude、GPT-4o）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"none\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 上下文配置\n\n**配置文件**：`config/user-config.json` 中的 `context` 段\n\n```json\n{\n  \"context\": {\n    \"contextWindowSize\": 200000,\n    \"warningThreshold\": 0.8,\n    \"targetThreshold\": 0.5,\n    \"sleepTriggerMinutes\": 5\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 默认值 | 范围 |\n|------|------|--------|------|\n| `contextWindowSize` | 模型上下文窗口大小（tokens） | 200000 | 32000 ~ 2000000 |\n| `warningThreshold` | 溢出警告阈值，上下文使用率超过此值触发压缩 | 0.8 | 0.0 ~ 1.0 |\n| `targetThreshold` | 强制压缩目标，压缩后上下文使用率降至此值 | 0.5 | 0.0 ~ 1.0 |\n| `sleepTriggerMinutes` | 空闲多久后触发睡眠整理（分钟） | 5 | > 0 |\n\n**常见模型的 contextWindowSize**：\n\n| 模型 | 上下文窗口 | 配置值 |\n|------|-----------|--------|\n| GPT-4o-mini | 128K | 128000 |\n| GPT-4o | 128K | 128000 |\n| Claude 3.5 Sonnet | 200K | 200000 |\n| DeepSeek V3 (deepseek-chat) | 64K | 64000 |\n| DeepSeek R1 (deepseek-reasoner) | 128K | 128000 |\n| Qwen2.5-Turbo | 1M | 1000000 |\n| 本地 Ollama 模型 | 取决于模型 | 按实际配置 |\n\n> **注意**：`contextWindowSize` 与模型强相关，切换模型后需同步更新此值。设置窗口主界面可直接配置此值，高级选项中可配置溢出阈值等参数。\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出，`contextWindowSize` 在主界面，阈值参数点\"高级选项\"展开）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.4 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.5 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.5 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Excel | .xlsx | 支持 |\n| PowerPoint | .pptx | 支持 |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| HTML | .html | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.6 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 10 条（1 条工作便签 + 9 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（知识图谱 LightRAG）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索 + 知识图谱关联，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.7 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.8 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "2da8ce0fa34484dee04bdc7ca5af89ef96f96585": {"t": 1785764518.2973518, "n": 16135, "h": "73fcae0e7d1cdee8", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nRust 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"\",\n    \"litellm_kwargs\": {}\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"none\",\n    \"litellm_kwargs\": {}\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点基础地址（不含路径后缀，LiteLLM 会自动追加：openai 类型追加 `/chat/completions`，anthropic 类型追加 `/v1/messages`） |\n| `model` | 模型名称 |\n| `type` | 系统内部参数，用于区分 API 格式转换和认证方式：`openai`（OpenAI 兼容格式）或 `anthropic`（Anthropic 原生格式）。**不是** LiteLLM 的 custom_llm_provider |\n| `provider` | LiteLLM 路由参数，映射为 `custom_llm_provider`。常见值：`\"\"`（空，默认由 type 决定）、`\"volcengine\"`（火山引擎）。填写后模型名无需加厂商前缀 |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"`。**注意**：该参数的实际效果与模型基础能力强相关，不同模型的最优值差异很大，需实测确定（详见下方\"reasoning_effort 配置与测试指南\"） |\n| `litellm_kwargs` | 厂商特有参数，JSON 对象格式，原样透传给 LiteLLM。用于传递各厂商 SDK 要求的额外参数（如火山引擎的 `thinking`、`allowed_openai_params` 等）。代码不做任何厂商判断，只负责透传 |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**火山方舟(Ark)端点配置说明**\n\n火山方舟提供两种计费端点，模型池相同，但功能权限有差异：\n\n| 端点 | 地址 | 计费 | response_format | 适用场景 |\n|------|------|------|-----------------|----------|\n| 标准端点 | `https://ark.cn-beijing.volces.com/api/v3` | 按量计费 | 支持 | 主 Agent、LightRAG |\n| Coding Plan | `https://ark.cn-beijing.volces.com/api/coding/v3` | 包月计费 | **不支持**（网关拦截） | 主 Agent |\n\n> **重要**：LightRAG 的 keyword_extraction 依赖 `response_format`，必须使用标准端点。如果误用 Coding Plan 端点，系统会自动 fallback 到纯 prompt JSON 返回（功能正常但多一次无效请求）。\n\n**火山方舟深度思考模型 + 工具调用配置**（重要）：\n\n火山方舟的 `doubao-seed` 系列模型（包括 `ark-code-latest`）默认启用深度思考模式。当 `litellm_kwargs` 中未显式传递 `thinking` 参数时，API 没有结构化工具调用保障——模型偶发将 tool_call 放入 `reasoning_content` 的 `<seed:tool_call>` XML 格式，而非标准的 `tool_calls` 字段，导致工具调用丢失。\n\n**主 Agent 必须配置**：\n```json\n\"llm\": {\n  ...\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n| `thinking` 值 | 效果 | 适用场景 |\n|---------------|------|----------|\n| `{\"type\": \"enabled\"}` | 显式启用深度思考，API 网关保障 tool_call 走标准通道 | **主 Agent（必须）** |\n| `{\"type\": \"disabled\"}` | 禁用深度思考 | LightRAG 入库（需配合 `response_format`） |\n| `{\"type\": \"auto\"}` | 模型自行决定 | 不推荐（行为不确定） |\n| 不传 | 模型默认启用思考，但无 tool_call 保障 | **危险：工具调用可能丢失** |\n\n> **注意**：`thinking` 参数通过 `litellm_kwargs` 原样透传给 LiteLLM，再由 VolcEngine 适配器转为 API 请求的 `extra_body.thinking` 字段。代码不做任何厂商判断，所有厂商特有参数都走这个透传通道。\n\n**模型名格式差异**：\n\n两种端点的模型池相同，但模型名格式不同：\n\n| 端点 | 模型名格式 | 示例 |\n|------|-----------|------|\n| 标准端点 | 带日期后缀的全名 | `doubao-seed-2-0-pro-260215` |\n| Coding Plan | 简短别名 | `doubao-seed-2.0-pro` |\n\n> **注意**：在标准端点上使用 Coding Plan 的简短别名会返回 404；反之，在 Coding Plan 端点上两种格式都能用。\n\n**LiteLLM 路由配置**：\n\n使用 LiteLLM 调用火山方舟模型时，必须通过 `provider: \"volcengine\"` 走 VolcEngine 适配器路由。这是 LiteLLM 的标准机制：\n\n| 配置方式 | 路由 | 结果 |\n|----------|------|------|\n| `provider: \"volcengine\"` + `model: \"doubao-seed-2.0-pro\"` | VolcEngine 适配器 | 正确：`thinking` 参数自动处理，厂商特有参数通过 `litellm_kwargs` 透传 |\n| `model: \"volcengine/doubao-seed-2.0-pro\"`（无 provider） | VolcEngine 适配器 | 也可：LiteLLM 通过前缀推断路由，但不如 `provider` 显式 |\n| `model: \"doubao-seed-2.0-pro\"`（无 provider 无前缀） | OpenAI 适配器 | **错误**：`thinking` 等火山特有参数无法传递 |\n\n> **注意**：`type: \"openai\"` 是系统内部参数（区分 Anthropic/OpenAI 格式转换），不是 LiteLLM 的 `custom_llm_provider`。两者独立：`type` 控制格式，`provider` 控制路由。\n\n**可用模型**：doubao-seed-2.0-code、doubao-seed-2.0-pro、doubao-seed-2.0-lite、minimax-m2.7、minimax-m3、glm-5.1、kimi-k2.6、deepseek-v4-pro、deepseek-v4-flash、ark-code-latest\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-seed-2.0-pro`（Coding Plan 别名）或 `doubao-seed-2-0-pro-260215`（标准端点全名） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `provider` | LiteLLM 路由参数，同 `llm` 段说明。火山引擎填 `\"volcengine\"` | `\"\"` 或 `\"volcengine\"` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n| `litellm_kwargs` | 厂商特有参数，同 `llm` 段说明。火山引擎知识图谱需传 `thinking` 和 `allowed_openai_params` | `{}` 或见配置示例 |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用思考链 | 能力强的模型（自带足够推理能力） |\n| `low` | 浅层推理 | **多数模型入库时的最优值**（实测推荐） |\n| `medium` | 中等推理 | 非入库的图谱查询任务；部分模型入库也可用 |\n| `high` | 深度推理 | 不建议用于入库（推理预算耗尽，输出质量反而下降） |\n| `xhigh` | 最深推理 | 不建议用于入库 |\n\n**reasoning_effort 配置与测试指南**：\n\n`reasoning_effort` 的最优值与模型基础能力强相关，不存在通用最优值。实测数据（ark-code-latest 模型入库 SYSTEM_MANUAL.md）：\n\n| 配置 | 实体类型准确率 | 空响应率 | 补充提取有效性 | 综合评分 |\n|------|--------------|---------|--------------|---------|\n| `none` | 67% | 60% | 无 | 5.5/10 |\n| `low` | 95% | 40% | 有效 | **7.5/10** |\n| `medium` | 14% | 40% | 部分 | 6.0/10 |\n| `high` | 分裂 | 40% | 无 | 4.0/10 |\n\n关键发现：\n1. **推理越深不一定越好**：推理token被模型内部消耗，不转化为输出质量。过度推理反而导致实体类型误分类（如子Agent被归为organization而非technology）\n2. **补充提取受影响**：高推理级别下模型过度自信，判断\"无需补充\"，导致遗漏无法弥补\n3. **不同模型差异很大**：能力强的模型（如 Claude、GPT-4o）在 `none` 或 `low` 即可高质量提取；能力有限的模型可能需要 `medium`，但也可能适得其反\n\n**换模型后必须实测**：更改模型或 reasoning_effort 后，用同一文档入库并检查日志验证效果。\n\n**入库质量检查方法**：\n1. 入库后检查日志目录 `logs/raw_http/YYYYMMDD/`，读取 `*_response.json` 文件\n2. 检查空响应：响应体仅含 `<|COMPLETE|>` 或 content 为空，说明该轮提取失败\n3. 检查实体类型：子Agent应为 technology 而非 person/organization；MCP服务器应为 technology 而非 organization\n4. 检查违规节点：不应出现与 niu 根节点重名的实体\n5. 检查补充提取：`*_response.json` 中补充提取应有实质内容（非仅 `<|COMPLETE|>`）\n6. 如发现问题，调整 reasoning_effort 重新入库测试\n\n**配置示例**：\n\n主 Agent 用火山方舟 Coding Plan（完整配置）：\n```json\n\"llm\": {\n  \"presetId\": \"ark-code-latest\",\n  \"apiKey\": \"你的API Key\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/coding/v3\",\n  \"model\": \"ark-code-latest\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"\",\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3\",\n  \"model\": \"doubao-seed-2-0-pro-260215\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"low\",\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"disabled\"},\n    \"allowed_openai_params\": [\"response_format\"]\n  }\n}\n```\n\n> **注意**：LightRAG 必须使用标准端点（apiBase 含 /api/v3），不能用 Coding Plan 端点（/api/coding/v3），因为 Coding Plan 网关拦截 response_format。model 必须用标准端点的全名格式（带日期后缀）。\n> **LiteLLM 路由**：`provider: \"volcengine\"` 让 LiteLLM 走 VolcEngine 适配器。`litellm_kwargs` 中的 `thinking: {\"type\": \"disabled\"}` 关闭思考链（火山要求使用 response_format 时必须关闭），`allowed_openai_params: [\"response_format\"]` 让 VolcEngine 适配器透传 response_format 参数。\n\n场景二：主 Agent 和 LightRAG 用同一模型，独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"low\",\n  \"litellm_kwargs\": {}\n}\n```\n\n场景三：能力强的模型，禁用思考链即可（如 Claude、GPT-4o）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"none\",\n  \"litellm_kwargs\": {}\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 上下文配置\n\n**配置文件**：`config/user-config.json` 中的 `context` 段\n\n```json\n{\n  \"context\": {\n    \"contextWindowSize\": 200000,\n    \"warningThreshold\": 0.8,\n    \"targetThreshold\": 0.5,\n    \"sleepTriggerMinutes\": 5\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 默认值 | 范围 |\n|------|------|--------|------|\n| `contextWindowSize` | 模型上下文窗口大小（tokens） | 200000 | 32000 ~ 2000000 |\n| `warningThreshold` | 溢出警告阈值，上下文使用率超过此值触发压缩 | 0.8 | 0.0 ~ 1.0 |\n| `targetThreshold` | 强制压缩目标，压缩后上下文使用率降至此值 | 0.5 | 0.0 ~ 1.0 |\n| `sleepTriggerMinutes` | 空闲多久后触发睡眠整理（分钟） | 5 | > 0 |\n\n**常见模型的 contextWindowSize**：\n\n| 模型 | 上下文窗口 | 配置值 |\n|------|-----------|--------|\n| GPT-4o-mini | 128K | 128000 |\n| GPT-4o | 128K | 128000 |\n| Claude 3.5 Sonnet | 200K | 200000 |\n| DeepSeek V3 (deepseek-chat) | 64K | 64000 |\n| DeepSeek R1 (deepseek-reasoner) | 128K | 128000 |\n| Qwen2.5-Turbo | 1M | 1000000 |\n| 本地 Ollama 模型 | 取决于模型 | 按实际配置 |\n\n> **注意**：`contextWindowSize` 与模型强相关，切换模型后需同步更新此值。设置窗口主界面可直接配置此值，高级选项中可配置溢出阈值等参数。\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出，`contextWindowSize` 在主界面，阈值参数点\"高级选项\"展开）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.4 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.5 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.5 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Excel | .xlsx | 支持 |\n| PowerPoint | .pptx | 支持 |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| HTML | .html | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.6 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 10 条（1 条工作便签 + 9 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（知识图谱 LightRAG）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索 + 知识图谱关联，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.7 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.8 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "c6e5dcd294bf0bbd80ff9bb910a8bbf26193af40": {"t": 1785764519.8353612, "n": 16130, "h": "142e442558c40c8d", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nRust 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"\",\n    \"litellm_kwargs\": {}\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"none\",\n    \"litellm_kwargs\": {}\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点基础地址（不含路径后缀，LiteLLM 会自动追加：openai 类型追加 `/chat/completions`，anthropic 类型追加 `/v1/messages`） |\n| `model` | 模型名称 |\n| `type` | 系统内部参数，用于区分 API 格式转换和认证方式：`openai`（OpenAI 兼容格式）或 `anthropic`（Anthropic 原生格式）。**不是** LiteLLM 的 custom_llm_provider |\n| `provider` | LiteLLM 路由参数，映射为 `custom_llm_provider`。常见值：`\"\"`（空，默认由 type 决定）、`\"volcengine\"`（火山引擎）。填写后模型名无需加厂商前缀 |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"`。**注意**：该参数的实际效果与模型基础能力强相关，不同模型的最优值差异很大，需实测确定（详见下方\"reasoning_effort 配置与测试指南\"） |\n| `litellm_kwargs` | 厂商特有参数，JSON 对象格式，原样透传给 LiteLLM。用于传递各厂商 SDK 要求的额外参数（如火山引擎的 `thinking`、`allowed_openai_params` 等）。代码不做任何厂商判断，只负责透传 |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**火山方舟(Ark)端点配置说明**\n\n火山方舟提供两种计费端点，模型池相同，但功能权限有差异：\n\n| 端点 | 地址 | 计费 | response_format | 适用场景 |\n|------|------|------|-----------------|----------|\n| 标准端点 | `https://ark.cn-beijing.volces.com/api/v3` | 按量计费 | 支持 | 主 Agent、LightRAG |\n| Coding Plan | `https://ark.cn-beijing.volces.com/api/coding/v3` | 包月计费 | **不支持**（网关拦截） | 主 Agent |\n\n> **重要**：LightRAG 的 keyword_extraction 依赖 `response_format`，必须使用标准端点。如果误用 Coding Plan 端点，系统会自动 fallback 到纯 prompt JSON 返回（功能正常但多一次无效请求）。\n\n**火山方舟深度思考模型 + 工具调用配置**（重要）：\n\n火山方舟的 `doubao-seed` 系列模型（包括 `ark-code-latest`）默认启用深度思考模式。当 `litellm_kwargs` 中未显式传递 `thinking` 参数时，API 没有结构化工具调用保障——模型偶发将 tool_call 放入 `reasoning_content` 的 `<seed:tool_call>` XML 格式，而非标准的 `tool_calls` 字段，导致工具调用丢失。\n\n**主 Agent 必须配置**：\n```json\n\"llm\": {\n  ...\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n| `thinking` 值 | 效果 | 适用场景 |\n|---------------|------|----------|\n| `{\"type\": \"enabled\"}` | 显式启用深度思考，API 网关保障 tool_call 走标准通道 | **主 Agent（必须）** |\n| `{\"type\": \"disabled\"}` | 禁用深度思考 | LightRAG 入库（需配合 `response_format`） |\n| `{\"type\": \"auto\"}` | 模型自行决定 | 不推荐（行为不确定） |\n| 不传 | 模型默认启用思考，但无 tool_call 保障 | **危险：工具调用可能丢失** |\n\n> **注意**：`thinking` 参数通过 `litellm_kwargs` 原样透传给 LiteLLM，再由 VolcEngine 适配器转为 API 请求的 `extra_body.thinking` 字段。代码不做任何厂商判断，所有厂商特有参数都走这个透传通道。\n\n**模型名格式差异**：\n\n两种端点的模型池相同，但模型名格式不同：\n\n| 端点 | 模型名格式 | 示例 |\n|------|-----------|------|\n| 标准端点 | 带日期后缀的全名 | `doubao-seed-2-0-pro-260215` |\n| Coding Plan | 简短别名 | `doubao-seed-2.0-pro` |\n\n> **注意**：在标准端点上使用 Coding Plan 的简短别名会返回 404；反之，在 Coding Plan 端点上两种格式都能用。\n\n**LiteLLM 路由配置**：\n\n使用 LiteLLM 调用火山方舟模型时，必须通过 `provider: \"volcengine\"` 走 VolcEngine 适配器路由。这是 LiteLLM 的标准机制：\n\n| 配置方式 | 路由 | 结果 |\n|----------|------|------|\n| `provider: \"volcengine\"` + `model: \"doubao-seed-2.0-pro\"` | VolcEngine 适配器 | 正确：`thinking` 参数自动处理，厂商特有参数通过 `litellm_kwargs` 透传 |\n| `model: \"volcengine/doubao-seed-2.0-pro\"`（无 provider） | VolcEngine 适配器 | 也可：LiteLLM 通过前缀推断路由，但不如 `provider` 显式 |\n| `model: \"doubao-seed-2.0-pro\"`（无 provider 无前缀） | OpenAI 适配器 | **错误**：`thinking` 等火山特有参数无法传递 |\n\n> **注意**：`type: \"openai\"` 是系统内部参数（区分 Anthropic/OpenAI 格式转换），不是 LiteLLM 的 `custom_llm_provider`。两者独立：`type` 控制格式，`provider` 控制路由。\n\n**可用模型**：doubao-seed-2.0-code、doubao-seed-2.0-pro、doubao-seed-2.0-lite、minimax-m2.7、minimax-m3、glm-5.1、kimi-k2.6、deepseek-v4-pro、deepseek-v4-flash、ark-code-latest\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-seed-2.0-pro`（Coding Plan 别名）或 `doubao-seed-2-0-pro-260215`（标准端点全名） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `provider` | LiteLLM 路由参数，同 `llm` 段说明。火山引擎填 `\"volcengine\"` | `\"\"` 或 `\"volcengine\"` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n| `litellm_kwargs` | 厂商特有参数，同 `llm` 段说明。火山引擎知识图谱需传 `thinking` 和 `allowed_openai_params` | `{}` 或见配置示例 |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用思考链 | 能力强的模型（自带足够推理能力） |\n| `low` | 浅层推理 | **多数模型入库时的最优值**（实测推荐） |\n| `medium` | 中等推理 | 非入库的图谱查询任务；部分模型入库也可用 |\n| `high` | 深度推理 | 不建议用于入库（推理预算耗尽，输出质量反而下降） |\n| `xhigh` | 最深推理 | 不建议用于入库 |\n\n**reasoning_effort 配置与测试指南**：\n\n`reasoning_effort` 的最优值与模型基础能力强相关，不存在通用最优值。实测数据（ark-code-latest 模型入库 SYSTEM_MANUAL.md）：\n\n| 配置 | 实体类型准确率 | 空响应率 | 补充提取有效性 | 综合评分 |\n|------|--------------|---------|--------------|---------|\n| `none` | 67% | 60% | 无 | 5.5/10 |\n| `low` | 95% | 40% | 有效 | **7.5/10** |\n| `medium` | 14% | 40% | 部分 | 6.0/10 |\n| `high` | 分裂 | 40% | 无 | 4.0/10 |\n\n关键发现：\n1. **推理越深不一定越好**：推理token被模型内部消耗，不转化为输出质量。过度推理反而导致实体类型误分类（如子Agent被归为organization而非technology）\n2. **补充提取受影响**：高推理级别下模型过度自信，判断\"无需补充\"，导致遗漏无法弥补\n3. **不同模型差异很大**：能力强的模型（如 Claude、GPT-4o）在 `none` 或 `low` 即可高质量提取；能力有限的模型可能需要 `medium`，但也可能适得其反\n\n**换模型后必须实测**：更改模型或 reasoning_effort 后，用同一文档入库并检查日志验证效果。\n\n**入库质量检查方法**：\n1. 入库后检查日志目录 `logs/raw_http/YYYYMMDD/`，读取 `*_response.json` 文件\n2. 检查空响应：响应体仅含 `<|COMPLETE|>` 或 content 为空，说明该轮提取失败\n3. 检查实体类型：子Agent应为 technology 而非 person/organization；MCP服务器应为 technology 而非 organization\n4. 检查违规节点：不应出现与 niu 根节点重名的实体\n5. 检查补充提取：`*_response.json` 中补充提取应有实质内容（非仅 `<|COMPLETE|>`）\n6. 如发现问题，调整 reasoning_effort 重新入库测试\n\n**配置示例**：\n\n主 Agent 用火山方舟 Coding Plan（完整配置）：\n```json\n\"llm\": {\n  \"presetId\": \"ark-code-latest\",\n  \"apiKey\": \"你的API Key\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/coding/v3\",\n  \"model\": \"ark-code-latest\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"\",\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3\",\n  \"model\": \"doubao-seed-2-0-pro-260215\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"low\",\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"disabled\"},\n    \"allowed_openai_params\": [\"response_format\"]\n  }\n}\n```\n\n> **注意**：LightRAG 必须使用标准端点（apiBase 含 /api/v3），不能用 Coding Plan 端点（/api/coding/v3），因为 Coding Plan 网关拦截 response_format。model 必须用标准端点的全名格式（带日期后缀）。\n> **LiteLLM 路由**：`provider: \"volcengine\"` 让 LiteLLM 走 VolcEngine 适配器。`litellm_kwargs` 中的 `thinking: {\"type\": \"disabled\"}` 关闭思考链（火山要求使用 response_format 时必须关闭），`allowed_openai_params: [\"response_format\"]` 让 VolcEngine 适配器透传 response_format 参数。\n\n场景二：主 Agent 和 LightRAG 用同一模型，独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"low\",\n  \"litellm_kwargs\": {}\n}\n```\n\n场景三：能力强的模型，禁用思考链即可（如 Claude、GPT-4o）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"none\",\n  \"litellm_kwargs\": {}\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 上下文配置\n\n**配置文件**：`config/user-config.json` 中的 `context` 段\n\n```json\n{\n  \"context\": {\n    \"contextWindowSize\": 200000,\n    \"warningThreshold\": 0.8,\n    \"targetThreshold\": 0.5,\n    \"sleepTriggerMinutes\": 5\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 默认值 | 范围 |\n|------|------|--------|------|\n| `contextWindowSize` | 模型上下文窗口大小（tokens） | 200000 | 32000 ~ 2000000 |\n| `warningThreshold` | 溢出警告阈值，上下文使用率超过此值触发压缩 | 0.8 | 0.0 ~ 1.0 |\n| `targetThreshold` | 强制压缩目标，压缩后上下文使用率降至此值 | 0.5 | 0.0 ~ 1.0 |\n| `sleepTriggerMinutes` | 空闲多久后触发睡眠整理（分钟） | 5 | > 0 |\n\n**常见模型的 contextWindowSize**：\n\n| 模型 | 上下文窗口 | 配置值 |\n|------|-----------|--------|\n| GPT-4o-mini | 128K | 128000 |\n| GPT-4o | 128K | 128000 |\n| Claude 3.5 Sonnet | 200K | 200000 |\n| DeepSeek V3 (deepseek-chat) | 64K | 64000 |\n| DeepSeek R1 (deepseek-reasoner) | 128K | 128000 |\n| Qwen2.5-Turbo | 1M | 1000000 |\n| 本地 Ollama 模型 | 取决于模型 | 按实际配置 |\n\n> **注意**：`contextWindowSize` 与模型强相关，切换模型后需同步更新此值。设置窗口主界面可直接配置此值，高级选项中可配置溢出阈值等参数。\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出，`contextWindowSize` 在主界面，阈值参数点\"高级选项\"展开）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.4 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.5 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.5 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Excel | .xlsx | 支持 |\n| PowerPoint | .pptx | 支持 |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| HTML | .html | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.6 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 10 条（1 条工作便签 + 9 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（向量库，L0/L1/L2 三层存储）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.7 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.8 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "7b8a8ff12f491eb0312a4f386ba5d3f4b6ed4aad": {"t": 1785764521.1334558, "n": 16292, "h": "4e86974e5262078e", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nGo 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"\",\n    \"litellm_kwargs\": {}\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"none\",\n    \"litellm_kwargs\": {}\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点基础地址（不含路径后缀，LiteLLM 会自动追加：openai 类型追加 `/chat/completions`，anthropic 类型追加 `/v1/messages`） |\n| `model` | 模型名称 |\n| `type` | 系统内部参数，用于区分 API 格式转换和认证方式：`openai`（OpenAI 兼容格式）或 `anthropic`（Anthropic 原生格式）。**不是** LiteLLM 的 custom_llm_provider |\n| `provider` | LiteLLM 路由参数，映射为 `custom_llm_provider`。常见值：`\"\"`（空，默认由 type 决定）、`\"volcengine\"`（火山引擎）。填写后模型名无需加厂商前缀 |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"`。**注意**：该参数的实际效果与模型基础能力强相关，不同模型的最优值差异很大，需实测确定（详见下方\"reasoning_effort 配置与测试指南\"） |\n| `litellm_kwargs` | 厂商特有参数，JSON 对象格式，原样透传给 LiteLLM。用于传递各厂商 SDK 要求的额外参数（如火山引擎的 `thinking`、`allowed_openai_params` 等）。代码不做任何厂商判断，只负责透传 |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**火山方舟(Ark)端点配置说明**\n\n火山方舟提供两种计费端点，模型池相同，但功能权限有差异：\n\n| 端点 | 地址 | 计费 | response_format | 适用场景 |\n|------|------|------|-----------------|----------|\n| 标准端点 | `https://ark.cn-beijing.volces.com/api/v3` | 按量计费 | 支持 | 主 Agent、LightRAG |\n| Coding Plan | `https://ark.cn-beijing.volces.com/api/coding/v3` | 包月计费 | **不支持**（网关拦截） | 主 Agent |\n\n> **重要**：LightRAG 的 keyword_extraction 依赖 `response_format`，必须使用标准端点。如果误用 Coding Plan 端点，系统会自动 fallback 到纯 prompt JSON 返回（功能正常但多一次无效请求）。\n\n**火山方舟深度思考模型 + 工具调用配置**（重要）：\n\n火山方舟的 `doubao-seed` 系列模型（包括 `ark-code-latest`）默认启用深度思考模式。当 `litellm_kwargs` 中未显式传递 `thinking` 参数时，API 没有结构化工具调用保障——模型偶发将 tool_call 放入 `reasoning_content` 的 `<seed:tool_call>` XML 格式，而非标准的 `tool_calls` 字段，导致工具调用丢失。\n\n**主 Agent 必须配置**：\n```json\n\"llm\": {\n  ...\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n| `thinking` 值 | 效果 | 适用场景 |\n|---------------|------|----------|\n| `{\"type\": \"enabled\"}` | 显式启用深度思考，API 网关保障 tool_call 走标准通道 | **主 Agent（必须）** |\n| `{\"type\": \"disabled\"}` | 禁用深度思考 | LightRAG 入库（需配合 `response_format`） |\n| `{\"type\": \"auto\"}` | 模型自行决定 | 不推荐（行为不确定） |\n| 不传 | 模型默认启用思考，但无 tool_call 保障 | **危险：工具调用可能丢失** |\n\n> **注意**：`thinking` 参数通过 `litellm_kwargs` 原样透传给 LiteLLM，再由 VolcEngine 适配器转为 API 请求的 `extra_body.thinking` 字段。代码不做任何厂商判断，所有厂商特有参数都走这个透传通道。\n\n**模型名格式差异**：\n\n两种端点的模型池相同，但模型名格式不同：\n\n| 端点 | 模型名格式 | 示例 |\n|------|-----------|------|\n| 标准端点 | 带日期后缀的全名 | `doubao-seed-2-0-pro-260215` |\n| Coding Plan | 简短别名 | `doubao-seed-2.0-pro` |\n\n> **注意**：在标准端点上使用 Coding Plan 的简短别名会返回 404；反之，在 Coding Plan 端点上两种格式都能用。\n\n**LiteLLM 路由配置**：\n\n使用 LiteLLM 调用火山方舟模型时，必须通过 `provider: \"volcengine\"` 走 VolcEngine 适配器路由。这是 LiteLLM 的标准机制：\n\n| 配置方式 | 路由 | 结果 |\n|----------|------|------|\n| `provider: \"volcengine\"` + `model: \"doubao-seed-2.0-pro\"` | VolcEngine 适配器 | 正确：`thinking` 参数自动处理，厂商特有参数通过 `litellm_kwargs` 透传 |\n| `model: \"volcengine/doubao-seed-2.0-pro\"`（无 provider） | VolcEngine 适配器 | 也可：LiteLLM 通过前缀推断路由，但不如 `provider` 显式 |\n| `model: \"doubao-seed-2.0-pro\"`（无 provider 无前缀） | OpenAI 适配器 | **错误**：`thinking` 等火山特有参数无法传递 |\n\n> **注意**：`type: \"openai\"` 是系统内部参数（区分 Anthropic/OpenAI 格式转换），不是 LiteLLM 的 `custom_llm_provider`。两者独立：`type` 控制格式，`provider` 控制路由。\n\n**可用模型**：doubao-seed-2.0-code、doubao-seed-2.0-pro、doubao-seed-2.0-lite、minimax-m2.7、minimax-m3、glm-5.1、kimi-k2.6、deepseek-v4-pro、deepseek-v4-flash、ark-code-latest\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-seed-2.0-pro`（Coding Plan 别名）或 `doubao-seed-2-0-pro-260215`（标准端点全名） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `provider` | LiteLLM 路由参数，同 `llm` 段说明。火山引擎填 `\"volcengine\"` | `\"\"` 或 `\"volcengine\"` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n| `litellm_kwargs` | 厂商特有参数，同 `llm` 段说明。火山引擎知识图谱需传 `thinking` 和 `allowed_openai_params` | `{}` 或见配置示例 |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用思考链 | 能力强的模型（自带足够推理能力） |\n| `low` | 浅层推理 | **多数模型入库时的最优值**（实测推荐） |\n| `medium` | 中等推理 | 非入库的图谱查询任务；部分模型入库也可用 |\n| `high` | 深度推理 | 不建议用于入库（推理预算耗尽，输出质量反而下降） |\n| `xhigh` | 最深推理 | 不建议用于入库 |\n\n**reasoning_effort 配置与测试指南**：\n\n`reasoning_effort` 的最优值与模型基础能力强相关，不存在通用最优值。实测数据（ark-code-latest 模型入库 SYSTEM_MANUAL.md）：\n\n| 配置 | 实体类型准确率 | 空响应率 | 补充提取有效性 | 综合评分 |\n|------|--------------|---------|--------------|---------|\n| `none` | 67% | 60% | 无 | 5.5/10 |\n| `low` | 95% | 40% | 有效 | **7.5/10** |\n| `medium` | 14% | 40% | 部分 | 6.0/10 |\n| `high` | 分裂 | 40% | 无 | 4.0/10 |\n\n关键发现：\n1. **推理越深不一定越好**：推理token被模型内部消耗，不转化为输出质量。过度推理反而导致实体类型误分类（如子Agent被归为organization而非technology）\n2. **补充提取受影响**：高推理级别下模型过度自信，判断\"无需补充\"，导致遗漏无法弥补\n3. **不同模型差异很大**：能力强的模型（如 Claude、GPT-4o）在 `none` 或 `low` 即可高质量提取；能力有限的模型可能需要 `medium`，但也可能适得其反\n\n**换模型后必须实测**：更改模型或 reasoning_effort 后，用同一文档入库并检查日志验证效果。\n\n**入库质量检查方法**：\n1. 入库后检查日志目录 `logs/raw_http/YYYYMMDD/`，读取 `*_response.json` 文件\n2. 检查空响应：响应体仅含 `<|COMPLETE|>` 或 content 为空，说明该轮提取失败\n3. 检查实体类型：子Agent应为 technology 而非 person/organization；MCP服务器应为 technology 而非 organization\n4. 检查违规节点：不应出现与 niu 根节点重名的实体\n5. 检查补充提取：`*_response.json` 中补充提取应有实质内容（非仅 `<|COMPLETE|>`）\n6. 如发现问题，调整 reasoning_effort 重新入库测试\n\n**配置示例**：\n\n主 Agent 用火山方舟 Coding Plan（完整配置）：\n```json\n\"llm\": {\n  \"presetId\": \"ark-code-latest\",\n  \"apiKey\": \"你的API Key\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/coding/v3\",\n  \"model\": \"ark-code-latest\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"\",\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3\",\n  \"model\": \"doubao-seed-2-0-pro-260215\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"low\",\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"disabled\"},\n    \"allowed_openai_params\": [\"response_format\"]\n  }\n}\n```\n\n> **注意**：LightRAG 必须使用标准端点（apiBase 含 /api/v3），不能用 Coding Plan 端点（/api/coding/v3），因为 Coding Plan 网关拦截 response_format。model 必须用标准端点的全名格式（带日期后缀）。\n> **LiteLLM 路由**：`provider: \"volcengine\"` 让 LiteLLM 走 VolcEngine 适配器。`litellm_kwargs` 中的 `thinking: {\"type\": \"disabled\"}` 关闭思考链（火山要求使用 response_format 时必须关闭），`allowed_openai_params: [\"response_format\"]` 让 VolcEngine 适配器透传 response_format 参数。\n\n场景二：主 Agent 和 LightRAG 用同一模型，独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"low\",\n  \"litellm_kwargs\": {}\n}\n```\n\n场景三：能力强的模型，禁用思考链即可（如 Claude、GPT-4o）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"none\",\n  \"litellm_kwargs\": {}\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 上下文配置\n\n**配置文件**：`config/user-config.json` 中的 `context` 段\n\n```json\n{\n  \"context\": {\n    \"contextWindowSize\": 200000,\n    \"warningThreshold\": 0.8,\n    \"targetThreshold\": 0.5,\n    \"sleepTriggerMinutes\": 5\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 默认值 | 范围 |\n|------|------|--------|------|\n| `contextWindowSize` | 模型上下文窗口大小（tokens） | 200000 | 32000 ~ 2000000 |\n| `warningThreshold` | 溢出警告阈值，上下文使用率超过此值触发压缩 | 0.8 | 0.0 ~ 1.0 |\n| `targetThreshold` | 强制压缩目标，压缩后上下文使用率降至此值 | 0.5 | 0.0 ~ 1.0 |\n| `sleepTriggerMinutes` | 空闲多久后触发睡眠整理（分钟） | 5 | > 0 |\n\n**常见模型的 contextWindowSize**：\n\n| 模型 | 上下文窗口 | 配置值 |\n|------|-----------|--------|\n| GPT-4o-mini | 128K | 128000 |\n| GPT-4o | 128K | 128000 |\n| Claude 3.5 Sonnet | 200K | 200000 |\n| DeepSeek V3 (deepseek-chat) | 64K | 64000 |\n| DeepSeek R1 (deepseek-reasoner) | 128K | 128000 |\n| Qwen2.5-Turbo | 1M | 1000000 |\n| 本地 Ollama 模型 | 取决于模型 | 按实际配置 |\n\n> **注意**：`contextWindowSize` 与模型强相关，切换模型后需同步更新此值。设置窗口主界面可直接配置此值，高级选项中可配置溢出阈值等参数。\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出，`contextWindowSize` 在主界面，阈值参数点\"高级选项\"展开）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.4 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.5 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.5 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Word（旧版） | .doc | **不支持** |\n| Excel | .xlsx | 支持 |\n| Excel（旧版） | .xls | **不支持** |\n| PowerPoint | .pptx | 支持 |\n| PowerPoint（旧版） | .ppt | **不支持** |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| CSV | .csv | 支持 |\n| JSON | .json | 支持 |\n| 日志 | .log | 支持 |\n| HTML | .html / .htm | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.6 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 5 条（1 条工作便签 + 4 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（向量库，L0/L1/L2 三层存储）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.7 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.8 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "36de3d18aa8d6210493c878561706234eb11aebb": {"t": 1785764523.5087342, "n": 15137, "h": "1effa9f065a03f4b", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nGo 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"\",\n    \"litellm_kwargs\": {}\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"none\",\n    \"litellm_kwargs\": {}\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点基础地址（不含路径后缀，LiteLLM 会自动追加：openai 类型追加 `/chat/completions`，anthropic 类型追加 `/v1/messages`） |\n| `model` | 模型名称 |\n| `type` | 系统内部参数，用于区分 API 格式转换和认证方式：`openai`（OpenAI 兼容格式）或 `anthropic`（Anthropic 原生格式）。**不是** LiteLLM 的 custom_llm_provider |\n| `provider` | LiteLLM 路由参数，映射为 `custom_llm_provider`。常见值：`\"\"`（空，默认由 type 决定）、`\"volcengine\"`（火山引擎）。填写后模型名无需加厂商前缀 |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"`。**注意**：该参数的实际效果与模型基础能力强相关，不同模型的最优值差异很大，需实测确定（详见下方\"reasoning_effort 配置与测试指南\"） |\n| `litellm_kwargs` | 厂商特有参数，JSON 对象格式，原样透传给 LiteLLM。用于传递各厂商 SDK 要求的额外参数（如火山引擎的 `thinking`、`allowed_openai_params` 等）。代码不做任何厂商判断，只负责透传 |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**火山方舟(Ark)端点配置说明**\n\n火山方舟提供两种计费端点，模型池相同，但功能权限有差异：\n\n| 端点 | 地址 | 计费 | response_format | 适用场景 |\n|------|------|------|-----------------|----------|\n| 标准端点 | `https://ark.cn-beijing.volces.com/api/v3` | 按量计费 | 支持 | 主 Agent、LightRAG |\n| Coding Plan | `https://ark.cn-beijing.volces.com/api/coding/v3` | 包月计费 | **不支持**（网关拦截） | 主 Agent |\n\n> **重要**：LightRAG 的 keyword_extraction 依赖 `response_format`，必须使用标准端点。如果误用 Coding Plan 端点，系统会自动 fallback 到纯 prompt JSON 返回（功能正常但多一次无效请求）。\n\n**模型名格式差异**：\n\n两种端点的模型池相同，但模型名格式不同：\n\n| 端点 | 模型名格式 | 示例 |\n|------|-----------|------|\n| 标准端点 | 带日期后缀的全名 | `doubao-seed-2-0-pro-260215` |\n| Coding Plan | 简短别名 | `doubao-seed-2.0-pro` |\n\n> **注意**：在标准端点上使用 Coding Plan 的简短别名会返回 404；反之，在 Coding Plan 端点上两种格式都能用。\n\n**LiteLLM 路由配置**：\n\n使用 LiteLLM 调用火山方舟模型时，必须通过 `provider: \"volcengine\"` 走 VolcEngine 适配器路由。这是 LiteLLM 的标准机制：\n\n| 配置方式 | 路由 | 结果 |\n|----------|------|------|\n| `provider: \"volcengine\"` + `model: \"doubao-seed-2.0-pro\"` | VolcEngine 适配器 | 正确：`thinking` 参数自动处理，厂商特有参数通过 `litellm_kwargs` 透传 |\n| `model: \"volcengine/doubao-seed-2.0-pro\"`（无 provider） | VolcEngine 适配器 | 也可：LiteLLM 通过前缀推断路由，但不如 `provider` 显式 |\n| `model: \"doubao-seed-2.0-pro\"`（无 provider 无前缀） | OpenAI 适配器 | **错误**：`thinking` 等火山特有参数无法传递 |\n\n> **注意**：`type: \"openai\"` 是系统内部参数（区分 Anthropic/OpenAI 格式转换），不是 LiteLLM 的 `custom_llm_provider`。两者独立：`type` 控制格式，`provider` 控制路由。\n\n**可用模型**：doubao-seed-2.0-code、doubao-seed-2.0-pro、doubao-seed-2.0-lite、minimax-m2.7、minimax-m3、glm-5.1、kimi-k2.6、deepseek-v4-pro、deepseek-v4-flash、ark-code-latest\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-seed-2.0-pro`（Coding Plan 别名）或 `doubao-seed-2-0-pro-260215`（标准端点全名） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `provider` | LiteLLM 路由参数，同 `llm` 段说明。火山引擎填 `\"volcengine\"` | `\"\"` 或 `\"volcengine\"` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n| `litellm_kwargs` | 厂商特有参数，同 `llm` 段说明。火山引擎知识图谱需传 `thinking` 和 `allowed_openai_params` | `{}` 或见配置示例 |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用思考链 | 能力强的模型（自带足够推理能力） |\n| `low` | 浅层推理 | **多数模型入库时的最优值**（实测推荐） |\n| `medium` | 中等推理 | 非入库的图谱查询任务；部分模型入库也可用 |\n| `high` | 深度推理 | 不建议用于入库（推理预算耗尽，输出质量反而下降） |\n| `xhigh` | 最深推理 | 不建议用于入库 |\n\n**reasoning_effort 配置与测试指南**：\n\n`reasoning_effort` 的最优值与模型基础能力强相关，不存在通用最优值。实测数据（ark-code-latest 模型入库 SYSTEM_MANUAL.md）：\n\n| 配置 | 实体类型准确率 | 空响应率 | 补充提取有效性 | 综合评分 |\n|------|--------------|---------|--------------|---------|\n| `none` | 67% | 60% | 无 | 5.5/10 |\n| `low` | 95% | 40% | 有效 | **7.5/10** |\n| `medium` | 14% | 40% | 部分 | 6.0/10 |\n| `high` | 分裂 | 40% | 无 | 4.0/10 |\n\n关键发现：\n1. **推理越深不一定越好**：推理token被模型内部消耗，不转化为输出质量。过度推理反而导致实体类型误分类（如子Agent被归为organization而非technology）\n2. **补充提取受影响**：高推理级别下模型过度自信，判断\"无需补充\"，导致遗漏无法弥补\n3. **不同模型差异很大**：能力强的模型（如 Claude、GPT-4o）在 `none` 或 `low` 即可高质量提取；能力有限的模型可能需要 `medium`，但也可能适得其反\n\n**换模型后必须实测**：更改模型或 reasoning_effort 后，用同一文档入库并检查日志验证效果。\n\n**入库质量检查方法**：\n1. 入库后检查日志目录 `logs/raw_http/YYYYMMDD/`，读取 `*_response.json` 文件\n2. 检查空响应：响应体仅含 `<|COMPLETE|>` 或 content 为空，说明该轮提取失败\n3. 检查实体类型：子Agent应为 technology 而非 person/organization；MCP服务器应为 technology 而非 organization\n4. 检查违规节点：不应出现与 niu 根节点重名的实体\n5. 检查补充提取：`*_response.json` 中补充提取应有实质内容（非仅 `<|COMPLETE|>`）\n6. 如发现问题，调整 reasoning_effort 重新入库测试\n\n**配置示例**：\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3\",\n  \"model\": \"doubao-seed-2-0-pro-260215\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"low\",\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"disabled\"},\n    \"allowed_openai_params\": [\"response_format\"]\n  }\n}\n```\n\n> **注意**：LightRAG 必须使用标准端点（apiBase 含 /api/v3），不能用 Coding Plan 端点（/api/coding/v3），因为 Coding Plan 网关拦截 response_format。model 必须用标准端点的全名格式（带日期后缀）。\n> **LiteLLM 路由**：`provider: \"volcengine\"` 让 LiteLLM 走 VolcEngine 适配器。`litellm_kwargs` 中的 `thinking: {\"type\": \"disabled\"}` 关闭思考链（火山要求使用 response_format 时必须关闭），`allowed_openai_params: [\"response_format\"]` 让 VolcEngine 适配器透传 response_format 参数。\n\n场景二：主 Agent 和 LightRAG 用同一模型，独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"low\",\n  \"litellm_kwargs\": {}\n}\n```\n\n场景三：能力强的模型，禁用思考链即可（如 Claude、GPT-4o）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"none\",\n  \"litellm_kwargs\": {}\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 上下文配置\n\n**配置文件**：`config/user-config.json` 中的 `context` 段\n\n```json\n{\n  \"context\": {\n    \"contextWindowSize\": 200000,\n    \"warningThreshold\": 0.8,\n    \"targetThreshold\": 0.5,\n    \"sleepTriggerMinutes\": 5\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 默认值 | 范围 |\n|------|------|--------|------|\n| `contextWindowSize` | 模型上下文窗口大小（tokens） | 200000 | 32000 ~ 2000000 |\n| `warningThreshold` | 溢出警告阈值，上下文使用率超过此值触发压缩 | 0.8 | 0.0 ~ 1.0 |\n| `targetThreshold` | 强制压缩目标，压缩后上下文使用率降至此值 | 0.5 | 0.0 ~ 1.0 |\n| `sleepTriggerMinutes` | 空闲多久后触发睡眠整理（分钟） | 5 | > 0 |\n\n**常见模型的 contextWindowSize**：\n\n| 模型 | 上下文窗口 | 配置值 |\n|------|-----------|--------|\n| GPT-4o-mini | 128K | 128000 |\n| GPT-4o | 128K | 128000 |\n| Claude 3.5 Sonnet | 200K | 200000 |\n| DeepSeek V3 (deepseek-chat) | 64K | 64000 |\n| DeepSeek R1 (deepseek-reasoner) | 128K | 128000 |\n| Qwen2.5-Turbo | 1M | 1000000 |\n| 本地 Ollama 模型 | 取决于模型 | 按实际配置 |\n\n> **注意**：`contextWindowSize` 与模型强相关，切换模型后需同步更新此值。设置窗口主界面可直接配置此值，高级选项中可配置溢出阈值等参数。\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出，`contextWindowSize` 在主界面，阈值参数点\"高级选项\"展开）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.4 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.5 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.5 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Word（旧版） | .doc | **不支持** |\n| Excel | .xlsx | 支持 |\n| Excel（旧版） | .xls | **不支持** |\n| PowerPoint | .pptx | 支持 |\n| PowerPoint（旧版） | .ppt | **不支持** |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| CSV | .csv | 支持 |\n| JSON | .json | 支持 |\n| 日志 | .log | 支持 |\n| HTML | .html / .htm | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.6 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 5 条（1 条工作便签 + 4 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（向量库，L0/L1/L2 三层存储）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.7 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.8 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "0b6fb31f047f5fc1fb6ab63e21795d65d20d4252": {"t": 1785764524.8661885, "n": 14219, "h": "3ad2e55454473b72", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nGo 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"reasoning_effort\": \"\"\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"reasoning_effort\": \"none\"\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点基础地址（不含路径后缀，LiteLLM 会自动追加：openai 类型追加 `/chat/completions`，anthropic 类型追加 `/v1/messages`） |\n| `model` | 模型名称 |\n| `type` | 系统内部参数，用于区分 API 格式转换和认证方式：`openai`（OpenAI 兼容格式）或 `anthropic`（Anthropic 原生格式）。该值映射为 LiteLLM 的 custom_llm_provider，不是直接传给 SDK 的类型 |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"`。**注意**：该参数的实际效果与模型基础能力强相关，不同模型的最优值差异很大，需实测确定（详见下方\"reasoning_effort 配置与测试指南\"） |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**火山方舟(Ark)端点配置说明**\n\n火山方舟提供两种计费端点，模型池相同，但功能权限有差异：\n\n| 端点 | 地址 | 计费 | response_format | 适用场景 |\n|------|------|------|-----------------|----------|\n| 标准端点 | `https://ark.cn-beijing.volces.com/api/v3` | 按量计费 | 支持 | 主 Agent、LightRAG |\n| Coding Plan | `https://ark.cn-beijing.volces.com/api/coding/v3` | 包月计费 | **不支持**（网关拦截） | 主 Agent |\n\n> **重要**：LightRAG 的 keyword_extraction 依赖 `response_format`，必须使用标准端点。如果误用 Coding Plan 端点，系统会自动 fallback 到纯 prompt JSON 返回（功能正常但多一次无效请求）。\n\n**模型名格式差异**：\n\n两种端点的模型池相同，但模型名格式不同：\n\n| 端点 | 模型名格式 | 示例 |\n|------|-----------|------|\n| 标准端点 | 带日期后缀的全名 | `doubao-seed-2-0-pro-260215` |\n| Coding Plan | 简短别名 | `doubao-seed-2.0-pro` |\n\n> **注意**：在标准端点上使用 Coding Plan 的简短别名会返回 404；反之，在 Coding Plan 端点上两种格式都能用。\n\n**LiteLLM 路由要求**：\n\n使用 LiteLLM 调用火山方舟模型时，模型名必须加 `volcengine/` 前缀，确保走 VolcEngine 适配器路由：\n\n| 写法 | 路由 | 结果 |\n|------|------|------|\n| `volcengine/doubao-seed-2.0-pro` | VolcEngine 适配器 | 正确：`thinking` 参数自动处理，`response_format` 需配合 `allowed_openai_params` 透传 |\n| `doubao-seed-2.0-pro`（无前缀） | OpenAI 适配器 | **错误**：`thinking` 参数无法传递，`response_format` 虽能透传但缺少 `thinking:disabled` 会导致思考链冲突 |\n\n> **注意**：当前系统配置中 `type: \"openai\"` 是系统内部参数（区分 Anthropic/OpenAI 格式转换），不是 LiteLLM 的 `custom_llm_provider`。系统代码会根据 `apiBase` 是否包含 `volces.com` 自动将 `custom_llm_provider` 设为 `volcengine`，并添加 `volcengine/` 前缀。用户无需在 `model` 字段中手动添加前缀。\n\n**可用模型**：doubao-seed-2.0-code、doubao-seed-2.0-pro、doubao-seed-2.0-lite、minimax-m2.7、minimax-m3、glm-5.1、kimi-k2.6、deepseek-v4-pro、deepseek-v4-flash、ark-code-latest\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-seed-2.0-pro`（Coding Plan 别名）或 `doubao-seed-2-0-pro-260215`（标准端点全名） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用思考链 | 能力强的模型（自带足够推理能力） |\n| `low` | 浅层推理 | **多数模型入库时的最优值**（实测推荐） |\n| `medium` | 中等推理 | 非入库的图谱查询任务；部分模型入库也可用 |\n| `high` | 深度推理 | 不建议用于入库（推理预算耗尽，输出质量反而下降） |\n| `xhigh` | 最深推理 | 不建议用于入库 |\n\n**reasoning_effort 配置与测试指南**：\n\n`reasoning_effort` 的最优值与模型基础能力强相关，不存在通用最优值。实测数据（ark-code-latest 模型入库 SYSTEM_MANUAL.md）：\n\n| 配置 | 实体类型准确率 | 空响应率 | 补充提取有效性 | 综合评分 |\n|------|--------------|---------|--------------|---------|\n| `none` | 67% | 60% | 无 | 5.5/10 |\n| `low` | 95% | 40% | 有效 | **7.5/10** |\n| `medium` | 14% | 40% | 部分 | 6.0/10 |\n| `high` | 分裂 | 40% | 无 | 4.0/10 |\n\n关键发现：\n1. **推理越深不一定越好**：推理token被模型内部消耗，不转化为输出质量。过度推理反而导致实体类型误分类（如子Agent被归为organization而非technology）\n2. **补充提取受影响**：高推理级别下模型过度自信，判断\"无需补充\"，导致遗漏无法弥补\n3. **不同模型差异很大**：能力强的模型（如 Claude、GPT-4o）在 `none` 或 `low` 即可高质量提取；能力有限的模型可能需要 `medium`，但也可能适得其反\n\n**换模型后必须实测**：更改模型或 reasoning_effort 后，用同一文档入库并检查日志验证效果。\n\n**入库质量检查方法**：\n1. 入库后检查日志目录 `logs/raw_http/YYYYMMDD/`，读取 `*_response.json` 文件\n2. 检查空响应：响应体仅含 `<|COMPLETE|>` 或 content 为空，说明该轮提取失败\n3. 检查实体类型：子Agent应为 technology 而非 person/organization；MCP服务器应为 technology 而非 organization\n4. 检查违规节点：不应出现与 niu 根节点重名的实体\n5. 检查补充提取：`*_response.json` 中补充提取应有实质内容（非仅 `<|COMPLETE|>`）\n6. 如发现问题，调整 reasoning_effort 重新入库测试\n\n**配置示例**：\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3\",\n  \"model\": \"doubao-seed-2-0-pro-260215\",\n  \"type\": \"openai\",\n  \"reasoning_effort\": \"low\"\n}\n```\n\n> **注意**：LightRAG 必须使用标准端点（apiBase 含 /api/v3），不能用 Coding Plan 端点（/api/coding/v3），因为 Coding Plan 网关拦截 response_format。model 必须用标准端点的全名格式（带日期后缀）。\n> **LiteLLM 路由**：系统会根据 apiBase 自动识别火山方舟端点并走 VolcEngine 路由（模型名自动加 volcengine/ 前缀），无需手动配置。\n\n场景二：主 Agent 和 LightRAG 用同一模型，独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"reasoning_effort\": \"low\"\n}\n```\n\n场景三：能力强的模型，禁用思考链即可（如 Claude、GPT-4o）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"reasoning_effort\": \"none\"\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 上下文配置\n\n**配置文件**：`config/user-config.json` 中的 `context` 段\n\n```json\n{\n  \"context\": {\n    \"contextWindowSize\": 200000,\n    \"warningThreshold\": 0.8,\n    \"targetThreshold\": 0.5,\n    \"sleepTriggerMinutes\": 5\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 默认值 | 范围 |\n|------|------|--------|------|\n| `contextWindowSize` | 模型上下文窗口大小（tokens） | 200000 | 32000 ~ 2000000 |\n| `warningThreshold` | 溢出警告阈值，上下文使用率超过此值触发压缩 | 0.8 | 0.0 ~ 1.0 |\n| `targetThreshold` | 强制压缩目标，压缩后上下文使用率降至此值 | 0.5 | 0.0 ~ 1.0 |\n| `sleepTriggerMinutes` | 空闲多久后触发睡眠整理（分钟） | 5 | > 0 |\n\n**常见模型的 contextWindowSize**：\n\n| 模型 | 上下文窗口 | 配置值 |\n|------|-----------|--------|\n| GPT-4o-mini | 128K | 128000 |\n| GPT-4o | 128K | 128000 |\n| Claude 3.5 Sonnet | 200K | 200000 |\n| DeepSeek V3 (deepseek-chat) | 64K | 64000 |\n| DeepSeek R1 (deepseek-reasoner) | 128K | 128000 |\n| Qwen2.5-Turbo | 1M | 1000000 |\n| 本地 Ollama 模型 | 取决于模型 | 按实际配置 |\n\n> **注意**：`contextWindowSize` 与模型强相关，切换模型后需同步更新此值。设置窗口主界面可直接配置此值，高级选项中可配置溢出阈值等参数。\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出，`contextWindowSize` 在主界面，阈值参数点\"高级选项\"展开）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.4 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.5 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.5 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Word（旧版） | .doc | **不支持** |\n| Excel | .xlsx | 支持 |\n| Excel（旧版） | .xls | **不支持** |\n| PowerPoint | .pptx | 支持 |\n| PowerPoint（旧版） | .ppt | **不支持** |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| CSV | .csv | 支持 |\n| JSON | .json | 支持 |\n| 日志 | .log | 支持 |\n| HTML | .html / .htm | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.6 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 5 条（1 条工作便签 + 4 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（向量库，L0/L1/L2 三层存储）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.7 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.8 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "a421fd40847303488c4cfcb81782fa6f0cb7595f": {"t": 1785764526.1492348, "n": 12350, "h": "3f59d5b3eba8e475", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nGo 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1/chat/completions\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"reasoning_effort\": \"\"\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"reasoning_effort\": \"none\"\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点地址（openai 类型含 `/chat/completions` 后缀；anthropic 类型含 `/v1/messages` 后缀） |\n| `model` | 模型名称 |\n| `type` | 类型：`openai`（兼容 OpenAI API）或 `anthropic` |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"`。**注意**：该参数的实际效果与模型基础能力强相关，不同模型的最优值差异很大，需实测确定（详见下方\"reasoning_effort 配置与测试指南\"） |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-pro-32k`（不带思考链） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用思考链 | 能力强的模型（自带足够推理能力） |\n| `low` | 浅层推理 | **多数模型入库时的最优值**（实测推荐） |\n| `medium` | 中等推理 | 非入库的图谱查询任务；部分模型入库也可用 |\n| `high` | 深度推理 | 不建议用于入库（推理预算耗尽，输出质量反而下降） |\n| `xhigh` | 最深推理 | 不建议用于入库 |\n\n**reasoning_effort 配置与测试指南**：\n\n`reasoning_effort` 的最优值与模型基础能力强相关，不存在通用最优值。实测数据（ark-code-latest 模型入库 SYSTEM_MANUAL.md）：\n\n| 配置 | 实体类型准确率 | 空响应率 | 补充提取有效性 | 综合评分 |\n|------|--------------|---------|--------------|---------|\n| `none` | 67% | 60% | 无 | 5.5/10 |\n| `low` | 95% | 40% | 有效 | **7.5/10** |\n| `medium` | 14% | 40% | 部分 | 6.0/10 |\n| `high` | 分裂 | 40% | 无 | 4.0/10 |\n\n关键发现：\n1. **推理越深不一定越好**：推理token被模型内部消耗，不转化为输出质量。过度推理反而导致实体类型误分类（如子Agent被归为organization而非technology）\n2. **补充提取受影响**：高推理级别下模型过度自信，判断\"无需补充\"，导致遗漏无法弥补\n3. **不同模型差异很大**：能力强的模型（如 Claude、GPT-4o）在 `none` 或 `low` 即可高质量提取；能力有限的模型可能需要 `medium`，但也可能适得其反\n\n**换模型后必须实测**：更改模型或 reasoning_effort 后，用同一文档入库并检查日志验证效果。\n\n**入库质量检查方法**：\n1. 入库后检查日志目录 `logs/raw_http/YYYYMMDD/`，读取 `*_response.json` 文件\n2. 检查空响应：响应体仅含 `<|COMPLETE|>` 或 content 为空，说明该轮提取失败\n3. 检查实体类型：子Agent应为 technology 而非 person/organization；MCP服务器应为 technology 而非 organization\n4. 检查违规节点：不应出现与 niu 根节点重名的实体\n5. 检查补充提取：`*_response.json` 中补充提取应有实质内容（非仅 `<|COMPLETE|>`）\n6. 如发现问题，调整 reasoning_effort 重新入库测试\n\n**配置示例**：\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3/chat/completions\",\n  \"model\": \"doubao-pro-32k\",\n  \"type\": \"openai\",\n  \"reasoning_effort\": \"low\"\n}\n```\n\n场景二：主 Agent 和 LightRAG 用同一模型，独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"reasoning_effort\": \"low\"\n}\n```\n\n场景三：能力强的模型，禁用思考链即可（如 Claude、GPT-4o）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"reasoning_effort\": \"none\"\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 上下文配置\n\n**配置文件**：`config/user-config.json` 中的 `context` 段\n\n```json\n{\n  \"context\": {\n    \"contextWindowSize\": 200000,\n    \"warningThreshold\": 0.8,\n    \"targetThreshold\": 0.5,\n    \"sleepTriggerMinutes\": 5\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 默认值 | 范围 |\n|------|------|--------|------|\n| `contextWindowSize` | 模型上下文窗口大小（tokens） | 200000 | 32000 ~ 2000000 |\n| `warningThreshold` | 溢出警告阈值，上下文使用率超过此值触发压缩 | 0.8 | 0.0 ~ 1.0 |\n| `targetThreshold` | 强制压缩目标，压缩后上下文使用率降至此值 | 0.5 | 0.0 ~ 1.0 |\n| `sleepTriggerMinutes` | 空闲多久后触发睡眠整理（分钟） | 5 | > 0 |\n\n**常见模型的 contextWindowSize**：\n\n| 模型 | 上下文窗口 | 配置值 |\n|------|-----------|--------|\n| GPT-4o-mini | 128K | 128000 |\n| GPT-4o | 128K | 128000 |\n| Claude 3.5 Sonnet | 200K | 200000 |\n| DeepSeek V3 (deepseek-chat) | 64K | 64000 |\n| DeepSeek R1 (deepseek-reasoner) | 128K | 128000 |\n| Qwen2.5-Turbo | 1M | 1000000 |\n| 本地 Ollama 模型 | 取决于模型 | 按实际配置 |\n\n> **注意**：`contextWindowSize` 与模型强相关，切换模型后需同步更新此值。设置窗口主界面可直接配置此值，高级选项中可配置溢出阈值等参数。\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出，`contextWindowSize` 在主界面，阈值参数点\"高级选项\"展开）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.4 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.5 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.5 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Word（旧版） | .doc | **不支持** |\n| Excel | .xlsx | 支持 |\n| Excel（旧版） | .xls | **不支持** |\n| PowerPoint | .pptx | 支持 |\n| PowerPoint（旧版） | .ppt | **不支持** |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| CSV | .csv | 支持 |\n| JSON | .json | 支持 |\n| 日志 | .log | 支持 |\n| HTML | .html / .htm | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.6 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 5 条（1 条工作便签 + 4 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（向量库，L0/L1/L2 三层存储）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.7 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.8 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "0e8febe8f0618779bb42cecf1cf777fa5afffe03": {"t": 1785764527.568135, "n": 12308, "h": "3067e4e5639c5003", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nGo 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1/chat/completions\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"reasoning_effort\": \"\"\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"reasoning_effort\": \"none\"\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点地址（openai 类型含 `/chat/completions` 后缀；anthropic 类型含 `/v1/messages` 后缀） |\n| `model` | 模型名称 |\n| `type` | 类型：`openai`（兼容 OpenAI API）或 `anthropic` |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"`。**注意**：该参数的实际效果与模型基础能力强相关，不同模型的最优值差异很大，需实测确定（详见下方\"reasoning_effort 配置与测试指南\"） |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-pro-32k`（不带思考链） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用思考链 | 能力强的模型（自带足够推理能力） |\n| `low` | 浅层推理 | **多数模型入库时的最优值**（实测推荐） |\n| `medium` | 中等推理 | 非入库的图谱查询任务；部分模型入库也可用 |\n| `high` | 深度推理 | 不建议用于入库（推理预算耗尽，输出质量反而下降） |\n| `xhigh` | 最深推理 | 不建议用于入库 |\n\n**reasoning_effort 配置与测试指南**：\n\n`reasoning_effort` 的最优值与模型基础能力强相关，不存在通用最优值。实测数据（ark-code-latest 模型入库 SYSTEM_MANUAL.md）：\n\n| 配置 | 实体类型准确率 | 空响应率 | 补充提取有效性 | 综合评分 |\n|------|--------------|---------|--------------|---------|\n| `none` | 67% | 60% | 无 | 5.5/10 |\n| `low` | 95% | 40% | 有效 | **7.5/10** |\n| `medium` | 14% | 40% | 部分 | 6.0/10 |\n| `high` | 分裂 | 40% | 无 | 4.0/10 |\n\n关键发现：\n1. **推理越深不一定越好**：推理token被模型内部消耗，不转化为输出质量。过度推理反而导致实体类型误分类（如子Agent被归为organization而非technology）\n2. **补充提取受影响**：高推理级别下模型过度自信，判断\"无需补充\"，导致遗漏无法弥补\n3. **不同模型差异很大**：能力强的模型（如 Claude、GPT-4o）在 `none` 或 `low` 即可高质量提取；能力有限的模型可能需要 `medium`，但也可能适得其反\n\n**换模型后必须实测**：更改模型或 reasoning_effort 后，用同一文档入库并检查日志验证效果。\n\n**入库质量检查方法**：\n1. 入库后检查日志目录 `logs/raw_http/YYYYMMDD/`，读取 `*_response.json` 文件\n2. 检查空响应：响应体仅含 `<|COMPLETE|>` 或 content 为空，说明该轮提取失败\n3. 检查实体类型：子Agent应为 technology 而非 person/organization；MCP服务器应为 technology 而非 organization\n4. 检查违规节点：不应出现与 niu 根节点重名的实体\n5. 检查补充提取：`*_response.json` 中补充提取应有实质内容（非仅 `<|COMPLETE|>`）\n6. 如发现问题，调整 reasoning_effort 重新入库测试\n\n**配置示例**：\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3/chat/completions\",\n  \"model\": \"doubao-pro-32k\",\n  \"type\": \"openai\",\n  \"reasoning_effort\": \"low\"\n}\n```\n\n场景二：主 Agent 和 LightRAG 用同一模型，独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"reasoning_effort\": \"low\"\n}\n```\n\n场景三：能力强的模型，禁用思考链即可（如 Claude、GPT-4o）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"reasoning_effort\": \"none\"\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 上下文配置\n\n**配置文件**：`config/user-config.json` 中的 `context` 段\n\n```json\n{\n  \"context\": {\n    \"contextWindowSize\": 200000,\n    \"warningThreshold\": 0.8,\n    \"targetThreshold\": 0.5,\n    \"sleepTriggerMinutes\": 5\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 默认值 | 范围 |\n|------|------|--------|------|\n| `contextWindowSize` | 模型上下文窗口大小（tokens） | 200000 | 32000 ~ 2000000 |\n| `warningThreshold` | 溢出警告阈值，上下文使用率超过此值触发压缩 | 0.8 | 0.0 ~ 1.0 |\n| `targetThreshold` | 强制压缩目标，压缩后上下文使用率降至此值 | 0.5 | 0.0 ~ 1.0 |\n| `sleepTriggerMinutes` | 空闲多久后触发睡眠整理（分钟） | 5 | > 0 |\n\n**常见模型的 contextWindowSize**：\n\n| 模型 | 上下文窗口 | 配置值 |\n|------|-----------|--------|\n| GPT-4o-mini | 128K | 128000 |\n| GPT-4o | 128K | 128000 |\n| Claude 3.5 Sonnet | 200K | 200000 |\n| DeepSeek V3 (deepseek-chat) | 64K | 64000 |\n| DeepSeek R1 (deepseek-reasoner) | 128K | 128000 |\n| Qwen2.5-Turbo | 1M | 1000000 |\n| 本地 Ollama 模型 | 取决于模型 | 按实际配置 |\n\n> **注意**：`contextWindowSize` 与模型强相关，切换模型后需同步更新此值。设置窗口的\"高级选项\"中可直接配置。\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出，点\"高级选项\"展开）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.4 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.5 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.5 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Word（旧版） | .doc | **不支持** |\n| Excel | .xlsx | 支持 |\n| Excel（旧版） | .xls | **不支持** |\n| PowerPoint | .pptx | 支持 |\n| PowerPoint（旧版） | .ppt | **不支持** |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| CSV | .csv | 支持 |\n| JSON | .json | 支持 |\n| 日志 | .log | 支持 |\n| HTML | .html / .htm | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.6 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 5 条（1 条工作便签 + 4 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（向量库，L0/L1/L2 三层存储）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.7 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.8 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "d5ab1965b490347684d6fd2ba180ae8e2a9b2734": {"t": 1785764528.788075, "n": 11252, "h": "fa665f04b7a5387f", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nGo 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1/chat/completions\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"reasoning_effort\": \"\"\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"reasoning_effort\": \"none\"\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点地址（openai 类型含 `/chat/completions` 后缀；anthropic 类型含 `/v1/messages` 后缀） |\n| `model` | 模型名称 |\n| `type` | 类型：`openai`（兼容 OpenAI API）或 `anthropic` |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"`。**注意**：该参数的实际效果与模型基础能力强相关，不同模型的最优值差异很大，需实测确定（详见下方\"reasoning_effort 配置与测试指南\"） |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-pro-32k`（不带思考链） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用思考链 | 能力强的模型（自带足够推理能力） |\n| `low` | 浅层推理 | **多数模型入库时的最优值**（实测推荐） |\n| `medium` | 中等推理 | 非入库的图谱查询任务；部分模型入库也可用 |\n| `high` | 深度推理 | 不建议用于入库（推理预算耗尽，输出质量反而下降） |\n| `xhigh` | 最深推理 | 不建议用于入库 |\n\n**reasoning_effort 配置与测试指南**：\n\n`reasoning_effort` 的最优值与模型基础能力强相关，不存在通用最优值。实测数据（ark-code-latest 模型入库 SYSTEM_MANUAL.md）：\n\n| 配置 | 实体类型准确率 | 空响应率 | 补充提取有效性 | 综合评分 |\n|------|--------------|---------|--------------|---------|\n| `none` | 67% | 60% | 无 | 5.5/10 |\n| `low` | 95% | 40% | 有效 | **7.5/10** |\n| `medium` | 14% | 40% | 部分 | 6.0/10 |\n| `high` | 分裂 | 40% | 无 | 4.0/10 |\n\n关键发现：\n1. **推理越深不一定越好**：推理token被模型内部消耗，不转化为输出质量。过度推理反而导致实体类型误分类（如子Agent被归为organization而非technology）\n2. **补充提取受影响**：高推理级别下模型过度自信，判断\"无需补充\"，导致遗漏无法弥补\n3. **不同模型差异很大**：能力强的模型（如 Claude、GPT-4o）在 `none` 或 `low` 即可高质量提取；能力有限的模型可能需要 `medium`，但也可能适得其反\n\n**换模型后必须实测**：更改模型或 reasoning_effort 后，用同一文档入库并检查日志验证效果。\n\n**入库质量检查方法**：\n1. 入库后检查日志目录 `logs/raw_http/YYYYMMDD/`，读取 `*_response.json` 文件\n2. 检查空响应：响应体仅含 `<|COMPLETE|>` 或 content 为空，说明该轮提取失败\n3. 检查实体类型：子Agent应为 technology 而非 person/organization；MCP服务器应为 technology 而非 organization\n4. 检查违规节点：不应出现与 niu 根节点重名的实体\n5. 检查补充提取：`*_response.json` 中补充提取应有实质内容（非仅 `<|COMPLETE|>`）\n6. 如发现问题，调整 reasoning_effort 重新入库测试\n\n**配置示例**：\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3/chat/completions\",\n  \"model\": \"doubao-pro-32k\",\n  \"type\": \"openai\",\n  \"reasoning_effort\": \"low\"\n}\n```\n\n场景二：主 Agent 和 LightRAG 用同一模型，独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"reasoning_effort\": \"low\"\n}\n```\n\n场景三：能力强的模型，禁用思考链即可（如 Claude、GPT-4o）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"reasoning_effort\": \"none\"\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.4 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.4 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Word（旧版） | .doc | **不支持** |\n| Excel | .xlsx | 支持 |\n| Excel（旧版） | .xls | **不支持** |\n| PowerPoint | .pptx | 支持 |\n| PowerPoint（旧版） | .ppt | **不支持** |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| CSV | .csv | 支持 |\n| JSON | .json | 支持 |\n| 日志 | .log | 支持 |\n| HTML | .html / .htm | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.5 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 5 条（1 条工作便签 + 4 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（向量库，L0/L1/L2 三层存储）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.6 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.7 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "9c33c02025775ddfc8542ff324ee3899ea958464": {"t": 1785764530.1276164, "n": 10107, "h": "6046735acfdf698e", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nGo 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1/chat/completions\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"reasoning_effort\": \"\"\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"reasoning_effort\": \"none\"\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点地址（openai 类型含 `/chat/completions` 后缀；anthropic 类型含 `/v1/messages` 后缀） |\n| `model` | 模型名称 |\n| `type` | 类型：`openai`（兼容 OpenAI API）或 `anthropic` |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"` |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-pro-32k`（不带思考链） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用思考链 | **入库时建议使用**（默认值，零配置生效） |\n| `low` | 浅层推理 | 需要少量推理的入库任务 |\n| `medium` | 中等推理 | 非入库的图谱查询任务 |\n| `high` | 深度推理 | 不建议用于 LightRAG 入库 |\n\n**配置示例**：\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3/chat/completions\",\n  \"model\": \"doubao-pro-32k\",\n  \"type\": \"openai\",\n  \"reasoning_effort\": \"none\"\n}\n```\n\n场景二：主 Agent 和 LightRAG 用同一模型，但独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"reasoning_effort\": \"none\"\n}\n```\n\n场景三：允许 LightRAG 浅层推理（高级用法）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"reasoning_effort\": \"low\"\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.4 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.4 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Word（旧版） | .doc | **不支持** |\n| Excel | .xlsx | 支持 |\n| Excel（旧版） | .xls | **不支持** |\n| PowerPoint | .pptx | 支持 |\n| PowerPoint（旧版） | .ppt | **不支持** |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| CSV | .csv | 支持 |\n| JSON | .json | 支持 |\n| 日志 | .log | 支持 |\n| HTML | .html / .htm | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.5 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 5 条（1 条工作便签 + 4 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（向量库，L0/L1/L2 三层存储）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.6 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.7 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "54971c2665e7de5d094acca8fcd2b2f3eaeba10e": {"t": 1785764531.5577323, "n": 9948, "h": "81886ab116822cd0", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nGo 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1/chat/completions\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\"\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"reasoning_effort\": \"none\"\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点地址（openai 类型含 `/chat/completions` 后缀；anthropic 类型含 `/v1/messages` 后缀） |\n| `model` | 模型名称 |\n| `type` | 类型：`openai`（兼容 OpenAI API）或 `anthropic` |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-pro-32k`（不带思考链） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用思考链 | **入库时建议使用**（默认值，零配置生效） |\n| `low` | 浅层推理 | 需要少量推理的入库任务 |\n| `medium` | 中等推理 | 非入库的图谱查询任务 |\n| `high` | 深度推理 | 不建议用于 LightRAG 入库 |\n\n**配置示例**：\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3/chat/completions\",\n  \"model\": \"doubao-pro-32k\",\n  \"type\": \"openai\",\n  \"reasoning_effort\": \"none\"\n}\n```\n\n场景二：主 Agent 和 LightRAG 用同一模型，但独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"reasoning_effort\": \"none\"\n}\n```\n\n场景三：允许 LightRAG 浅层推理（高级用法）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"reasoning_effort\": \"low\"\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.4 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.4 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Word（旧版） | .doc | **不支持** |\n| Excel | .xlsx | 支持 |\n| Excel（旧版） | .xls | **不支持** |\n| PowerPoint | .pptx | 支持 |\n| PowerPoint（旧版） | .ppt | **不支持** |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| CSV | .csv | 支持 |\n| JSON | .json | 支持 |\n| 日志 | .log | 支持 |\n| HTML | .html / .htm | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.5 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 5 条（1 条工作便签 + 4 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（向量库，L0/L1/L2 三层存储）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.6 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.7 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "643bb4ffcd3dc40a63e6eabe9139ead804fb00cf": {"t": 1785764532.9104934, "n": 7845, "h": "db86a68616d310b0", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nGo 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1/chat/completions\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\"\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点地址（openai 类型含 `/chat/completions` 后缀；anthropic 类型含 `/v1/messages` 后缀） |\n| `model` | 模型名称 |\n| `type` | 类型：`openai`（兼容 OpenAI API）或 `anthropic` |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.3 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.4 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n### 1.4 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Word（旧版） | .doc | **不支持** |\n| Excel | .xlsx | 支持 |\n| Excel（旧版） | .xls | **不支持** |\n| PowerPoint | .pptx | 支持 |\n| PowerPoint（旧版） | .ppt | **不支持** |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| CSV | .csv | 支持 |\n| JSON | .json | 支持 |\n| 日志 | .log | 支持 |\n| HTML | .html / .htm | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.5 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 5 条（1 条工作便签 + 4 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（向量库，L0/L1/L2 三层存储）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.6 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.7 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "f8b838f8f2ed20466dee4229ae5452dc1f72f9f5": {"t": 1785764534.2494917, "n": 7707, "h": "30cc01f7b904870b", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nGo 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1/chat/completions\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\"\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点地址（openai 类型含 `/chat/completions` 后缀；anthropic 类型含 `/v1/messages` 后缀） |\n| `model` | 模型名称 |\n| `type` | 类型：`openai`（兼容 OpenAI API）或 `anthropic` |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.3 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.4 支持的文件格式\"。\n\n### 1.4 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Word（旧版） | .doc | **不支持** |\n| Excel | .xlsx | 支持 |\n| Excel（旧版） | .xls | **不支持** |\n| PowerPoint | .pptx | 支持 |\n| PowerPoint（旧版） | .ppt | **不支持** |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| CSV | .csv | 支持 |\n| JSON | .json | 支持 |\n| 日志 | .log | 支持 |\n| HTML | .html / .htm | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.5 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 5 条（1 条工作便签 + 4 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（向量库，L0/L1/L2 三层存储）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.6 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.7 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "7afcb78168df931c30b3a560af010402013704a2": {"t": 1785764535.693151, "n": 7466, "h": "018ff1043a2d1f7d", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1/chat/completions\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\"\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点地址（openai 类型含 `/chat/completions` 后缀；anthropic 类型含 `/v1/messages` 后缀） |\n| `model` | 模型名称 |\n| `type` | 类型：`openai`（兼容 OpenAI API）或 `anthropic` |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.3 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（15 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.4 支持的文件格式\"。\n\n### 1.4 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Word（旧版） | .doc | **不支持** |\n| Excel | .xlsx | 支持 |\n| Excel（旧版） | .xls | **不支持** |\n| PowerPoint | .pptx | 支持 |\n| PowerPoint（旧版） | .ppt | **不支持** |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| CSV | .csv | 支持 |\n| JSON | .json | 支持 |\n| 日志 | .log | 支持 |\n| HTML | .html / .htm | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.5 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 5 条（1 条工作便签 + 4 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（向量库，L0/L1/L2 三层存储）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.6 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.7 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "722c6c428eddfe8b38a1717bffc0b8ddc48c6af8": {"t": 1785764537.1544843, "n": 7040, "h": "202f99cc946e3bc3", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1/chat/completions\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\"\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点地址（openai 类型含 `/chat/completions` 后缀；anthropic 类型含 `/v1/messages` 后缀） |\n| `model` | 模型名称 |\n| `type` | 类型：`openai`（兼容 OpenAI API）或 `anthropic` |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.3 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（15 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.4 支持的文件格式\"。\n\n### 1.4 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Word（旧版） | .doc | **不支持** |\n| Excel | .xlsx | 支持 |\n| Excel（旧版） | .xls | **不支持** |\n| PowerPoint | .pptx | 支持 |\n| PowerPoint（旧版） | .ppt | **不支持** |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| CSV | .csv | 支持 |\n| JSON | .json | 支持 |\n| 日志 | .log | 支持 |\n| HTML | .html / .htm | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.5 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 5 条（1 条工作便签 + 4 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**2. 语义记忆（向量库，L0/L1/L2 三层存储）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.6 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.7 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "100bf39146cb67721acbe4a48448fefca79522f2": {"t": 1785764538.4069068, "n": 5834, "h": "72d0b411b704531a", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1/chat/completions\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\"\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点地址（openai 类型含 `/chat/completions` 后缀；anthropic 类型含 `/v1/messages` 后缀） |\n| `model` | 模型名称 |\n| `type` | 类型：`openai`（兼容 OpenAI API）或 `anthropic` |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.3 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（15 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n### 1.4 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 5 条（1 条工作便签 + 4 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**2. 语义记忆（向量库，L0/L1/L2 三层存储）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.5 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 完成后，下次对话不再出现首次使用提示\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.6 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "6d16889a13baaf398cfaedfadfcc5b88a3f4376a": {"t": 1786067775.953015, "n": 20765, "h": "355d398e8162501c", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nRust 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"\",\n    \"litellm_kwargs\": {}\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"none\",\n    \"litellm_kwargs\": {}\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点基础地址（不含路径后缀，LiteLLM 会自动追加：openai 类型追加 `/chat/completions`，anthropic 类型追加 `/v1/messages`） |\n| `model` | 模型名称 |\n| `type` | 系统内部参数，用于区分 API 格式转换和认证方式：`openai`（OpenAI 兼容格式）或 `anthropic`（Anthropic 原生格式）。**不是** LiteLLM 的 custom_llm_provider |\n| `provider` | LiteLLM 路由参数，映射为 `custom_llm_provider`。常见值：`\"\"`（空，默认由 type 决定）、`\"volcengine\"`（火山引擎）。填写后模型名无需加厂商前缀 |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"`。**注意**：该参数的实际效果与模型基础能力强相关，不同模型的最优值差异很大，需实测确定（详见下方\"reasoning_effort 配置与测试指南\"） |\n| `litellm_kwargs` | 厂商特有参数，JSON 对象格式，原样透传给 LiteLLM。用于传递各厂商 SDK 要求的额外参数（如火山引擎的 `thinking`、`allowed_openai_params` 等）。代码不做任何厂商判断，只负责透传 |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**火山方舟(Ark)端点配置说明**\n\n火山方舟提供两种计费端点，模型池相同，但功能权限有差异：\n\n| 端点 | 地址 | 计费 | response_format | 适用场景 |\n|------|------|------|-----------------|----------|\n| 标准端点 | `https://ark.cn-beijing.volces.com/api/v3` | 按量计费 | 支持 | 主 Agent、LightRAG |\n| Coding Plan | `https://ark.cn-beijing.volces.com/api/coding/v3` | 包月计费 | **不支持**（网关 400 拒绝） | 主 Agent |\n\n**格式化输出（response_format）能力自动探测**\n\n设置窗口\"测试连接并保存\"按钮在测试通过后，会自动追加一次格式化输出能力探测，按 3 档递进调用真实 LLM，找出当前配置支持的最强档位：\n\n| 档位 | response_format.type | 约束 | 典型支持厂商 |\n|------|---------------------|------|--------------|\n| Tier 1（最强） | `json_schema` strict | 输出严格匹配 schema | OpenAI 真正支持 |\n| Tier 2（中等） | `json_object` | 输出合法 JSON，不约束字段 | OpenAI、DeepSeek |\n| Tier 3（最弱） | 无 response_format | prompt + `json_repair` 客户端容错 | 所有厂商兜底 |\n\n**探测流程**：从 Tier 1 开始测，失败则降级测 Tier 2，再失败则定为 Tier 3。每档失败条件：\n- `model_rejected`：LiteLLM 抛 `BadRequestError`/`UnsupportedParamsError`（模型/网关 4xx 拒绝，如豆包 Coding Plan）\n- `gateway_blocked`：网关返回 200 但响应非合法 JSON（网关接受参数但模型输出漂移，如 GLM xopglm5）\n\n探测采用三次采样 + 冲突式设计：\n- 三次采样全过才升档，任何一次失败立即降级——防 flaky 网关（豆包 Coding\n  Plan 2026-07-21 实测：同一请求 5 次采样 2 次执行、3 次静默忽略）碰巧\n  命中执行窗口期误判支持\n- 冲突式设计：schema 强制要求 `{\"verdict\": \"SCHEMA_ENFORCED\"}`，prompt\n  却要求模型写普通英文句子且禁止输出 JSON——只有 schema 战胜 prompt\n  （输出被强制为 schema JSON）才判定真支持，模型跟随 prompt 输出普通\n  文本即判定网关静默忽略\n- 限流单独处理：RateLimitError 不计失败，sleep 后重试本次采样（指数\n  退避 5s→10s→20s→40s→80s，最多 5 次），直到返回非限流结果才判定\n\n**写入配置**：\n- `lightrag_llm.litellm_kwargs.response_format_mode`：`\"json_schema\"` / `\"json_object\"` / `\"prompt_only\"`\n- `lightrag_llm.litellm_kwargs.allowed_openai_params`：前两档 `[\"response_format\"]`，prompt_only 档 `[]`（双写兼容旧逻辑）\n\n**典型场景**（2026-07-19 实测）：\n- 豆包 Coding Plan 端点（`/api/coding/v3`，model=`ark-code-latest`）：\n  网关行为非确定性（flaky），同一请求多次采样结果不稳定（有时执行\n  json_schema strict、有时静默忽略），三次采样必然 ≥1 次静默忽略 →\n  探测结果稳定 `prompt_only`\n- GLM 端点（`maas-coding-api.cn-huabei-1.xf-yun.com/v2`，model=`xopglm5`）：网关接受但模型输出漂移，探测结果 `prompt_only`\n- OpenAI 官方：探测结果 `json_schema`\n\n**升级后自动探测**：旧版本用户配置无 `response_format_mode` 字段。程序启动后若检测到该字段缺失，后台自动触发一次探测写入配置，不阻塞启动。\n\n**手动覆盖**：关闭程序后手动编辑 `config/user-config.json` 的 `lightrag_llm.litellm_kwargs.response_format_mode`。下次设置窗口测试保存会覆盖手动值。\n\n**注意**：\n- 探测调用会消耗约 100-200 token（最坏情况测到 Tier 2）。仅\"测试连接并保存\"按钮触发，不引入后台定时探测（升级后首次启动除外）。\n- 探测独立于启动时的 LLM 连通性测试（`/api/test-llm`），不影响启动速度。\n\n> **重要**：LightRAG 的 keyword_extraction 依赖 `response_format`，必须使用标准端点。如果误用 Coding Plan 端点，本次升级后的\"格式化输出能力自动探测\"会识别为 `prompt_only` 档位并写入配置，运行时 LightRAG 直接走 prompt-only 路径（不再每次发无效请求触发 400 后 fallback）。详见上方\"格式化输出（response_format）能力自动探测\"小节。\n\n**火山方舟深度思考模型 + 工具调用配置**（重要）：\n\n火山方舟的 `doubao-seed` 系列模型（包括 `ark-code-latest`）默认启用深度思考模式。当 `litellm_kwargs` 中未显式传递 `thinking` 参数时，API 没有结构化工具调用保障——模型偶发将 tool_call 放入 `reasoning_content` 的 `<seed:tool_call>` XML 格式，而非标准的 `tool_calls` 字段，导致工具调用丢失。\n\n**主 Agent 必须配置**：\n```json\n\"llm\": {\n  ...\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n| `thinking` 值 | 效果 | 适用场景 |\n|---------------|------|----------|\n| `{\"type\": \"enabled\"}` | 显式启用深度思考，API 网关保障 tool_call 走标准通道 | **主 Agent（必须）** |\n| `{\"type\": \"disabled\"}` | 禁用深度思考 | LightRAG 入库（需配合 `response_format`） |\n| `{\"type\": \"auto\"}` | 模型自行决定 | 不推荐（行为不确定） |\n| 不传 | 模型默认启用思考，但无 tool_call 保障 | **危险：工具调用可能丢失** |\n\n> **注意**：`thinking` 参数通过 `litellm_kwargs` 原样透传给 LiteLLM，再由 VolcEngine 适配器转为 API 请求的 `extra_body.thinking` 字段。代码不做任何厂商判断，所有厂商特有参数都走这个透传通道。\n\n**模型名格式差异**：\n\n两种端点的模型池相同，但模型名格式不同：\n\n| 端点 | 模型名格式 | 示例 |\n|------|-----------|------|\n| 标准端点 | 带日期后缀的全名 | `doubao-seed-2-0-pro-260215` |\n| Coding Plan | 简短别名 | `doubao-seed-2.0-pro` |\n\n> **注意**：在标准端点上使用 Coding Plan 的简短别名会返回 404；反之，在 Coding Plan 端点上两种格式都能用。\n\n**LiteLLM 路由配置**：\n\n使用 LiteLLM 调用火山方舟模型时，必须通过 `provider: \"volcengine\"` 走 VolcEngine 适配器路由。这是 LiteLLM 的标准机制：\n\n| 配置方式 | 路由 | 结果 |\n|----------|------|------|\n| `provider: \"volcengine\"` + `model: \"doubao-seed-2.0-pro\"` | VolcEngine 适配器 | 正确：`thinking` 参数自动处理，厂商特有参数通过 `litellm_kwargs` 透传 |\n| `model: \"volcengine/doubao-seed-2.0-pro\"`（无 provider） | VolcEngine 适配器 | 也可：LiteLLM 通过前缀推断路由，但不如 `provider` 显式 |\n| `model: \"doubao-seed-2.0-pro\"`（无 provider 无前缀） | OpenAI 适配器 | **错误**：`thinking` 等火山特有参数无法传递 |\n\n> **注意**：`type: \"openai\"` 是系统内部参数（区分 Anthropic/OpenAI 格式转换），不是 LiteLLM 的 `custom_llm_provider`。两者独立：`type` 控制格式，`provider` 控制路由。\n\n**可用模型**：doubao-seed-2.0-code、doubao-seed-2.0-pro、doubao-seed-2.0-lite、minimax-m2.7、minimax-m3、glm-5.1、kimi-k2.6、deepseek-v4-pro、deepseek-v4-flash、ark-code-latest\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-seed-2.0-pro`（Coding Plan 别名）或 `doubao-seed-2-0-pro-260215`（标准端点全名） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `provider` | LiteLLM 路由参数，同 `llm` 段说明。火山引擎填 `\"volcengine\"` | `\"\"` 或 `\"volcengine\"` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n| `temperature` | LLM 采样温度。0.0 完全确定性，1.0 高随机度。为空时由系统兜底 0.2 | `0.2`（实体/关系抽取建议低温度避免 JSON 漂移） |\n| `litellm_kwargs` | 厂商特有参数，同 `llm` 段说明。火山引擎知识图谱需传 `thinking` 和 `allowed_openai_params` | `{}` 或见配置示例 |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n> **温度值说明**：LightRAG 调 LLM 时如果不配 `temperature` 字段，系统兜底默认 `0.2`。这是为实体抽取、关系抽取等结构化任务优化的低温度值，避免高随机度导致 JSON 格式漂移、实体名不一致。如果需要更稳定的输出可设 `0.0`，需要更多创造性可设 `0.5~0.7`，但不建议超过 `1.0`。主 Agent / 子 Agent 的温度值在提示词文档里独立配置（主 Agent 0.6、子 Agent 多数 0.2），与此处的 `lightrag_llm.temperature` 完全独立，互不影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用 | 建议初始使用时，根据模型情况自己测试后确定 |\n| `low` | 浅层推理 | 模型推理速度极慢时，可选用 |\n| `medium` | 中等推理 | 非入库的图谱查询任务；部分模型入库也可用 |\n| `high` | 深度推理 | 建议用于入库（推理预算耗尽，输出质量高） |\n| `xhigh` | 最深推理 | 不建议用于入库 |\n\n**reasoning_effort 配置与测试指南**：\n\n`reasoning_effort` 的最优值与模型基础能力强相关，不存在通用最优值。实测数据（ark-code-latest 模型入库 SYSTEM_MANUAL.md）：\n\n| 配置 | 实体类型准确率 | 空响应率 | 补充提取有效性 | 综合评分 |\n|------|--------------|---------|--------------|---------|\n| `none` | 67% | 60% | 无 | 5.5/10 |\n| `low` | 95% | 40% | 有效 | **7.5/10** |\n| `medium` | 14% | 40% | 部分 | 6.0/10 |\n| `high` | 分裂 | 40% | 无 | 4.0/10 |\n\n关键发现：\n1. **推理越深不一定越好**：推理token被模型内部消耗，不转化为输出质量。过度推理反而导致实体类型误分类（如子Agent被归为organization而非technology）\n2. **补充提取受影响**：高推理级别下模型过度自信，判断\"无需补充\"，导致遗漏无法弥补\n3. **不同模型差异很大**：能力强的模型（如 Claude、GPT-4o）在 `none` 或 `low` 即可高质量提取；能力有限的模型可能需要 `high`，但也可能适得其反\n\n**换模型后必须实测**：更改模型或 reasoning_effort 后，用同一文档入库并检查日志验证效果。\n\n**入库质量检查方法**：\n1. 入库后检查日志目录 `logs/raw_http/YYYYMMDD/`，读取 `*_response.json` 文件\n2. 检查空响应：响应体仅含 `<|COMPLETE|>` 或 content 为空，说明该轮提取失败\n3. 检查实体类型：子Agent应为 technology 而非 person/organization；MCP服务器应为 technology 而非 organization\n4. 检查违规节点：不应出现与 niu 根节点重名的实体\n5. 检查补充提取：`*_response.json` 中补充提取应有实质内容（非仅 `<|COMPLETE|>`）\n6. 如发现问题，调整 reasoning_effort 重新入库测试\n\n**配置示例**：\n\n主 Agent 用火山方舟 Coding Plan（完整配置）：\n```json\n\"llm\": {\n  \"presetId\": \"ark-code-latest\",\n  \"apiKey\": \"你的API Key\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/coding/v3\",\n  \"model\": \"ark-code-latest\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"\",\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3\",\n  \"model\": \"doubao-seed-2-0-pro-260215\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"disabled\"},\n    \"allowed_openai_params\": [\"response_format\"]\n  }\n}\n```\n\n> **注意**：LightRAG 必须使用标准端点（apiBase 含 /api/v3），不能用 Coding Plan 端点（/api/coding/v3），因为 Coding Plan 网关 400 拒绝 response_format。设置窗口\"测试连接并保存\"会自动探测并写入 `response_format_mode=prompt_only`（豆包 Coding Plan 场景）。model 必须用标准端点的全名格式（带日期后缀）。\n> **LiteLLM 路由**：`provider: \"volcengine\"` 让 LiteLLM 走 VolcEngine 适配器。`litellm_kwargs` 中的 `thinking: {\"type\": \"disabled\"}` 关闭思考链（火山要求使用 response_format 时必须关闭），`allowed_openai_params: [\"response_format\"]` 让 VolcEngine 适配器透传 response_format 参数。\n\n场景二：主 Agent 和 LightRAG 用同一模型，独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n场景三：能力强的模型，禁用思考链即可（如 Claude、GPT-4o）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"none\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 上下文配置\n\n**配置文件**：`config/user-config.json` 中的 `context` 段\n\n```json\n{\n  \"context\": {\n    \"contextWindowSize\": 200000,\n    \"warningThreshold\": 0.8,\n    \"targetThreshold\": 0.5,\n    \"sleepTriggerMinutes\": 5\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 默认值 | 范围 |\n|------|------|--------|------|\n| `contextWindowSize` | 模型上下文窗口大小（tokens） | 200000 | 32000 ~ 2000000 |\n| `warningThreshold` | 溢出警告阈值，上下文使用率超过此值触发压缩 | 0.8 | 0.0 ~ 1.0 |\n| `targetThreshold` | 强制压缩目标，压缩后上下文使用率降至此值 | 0.5 | 0.0 ~ 1.0 |\n| `sleepTriggerMinutes` | 空闲多久后触发睡眠整理（分钟） | 5 | > 0 |\n\n**常见模型的 contextWindowSize**：\n\n| 模型 | 上下文窗口 | 配置值 |\n|------|-----------|--------|\n| GPT-4o-mini | 128K | 128000 |\n| GPT-4o | 128K | 128000 |\n| Claude 3.5 Sonnet | 200K | 200000 |\n| DeepSeek V3 (deepseek-chat) | 64K | 64000 |\n| DeepSeek R1 (deepseek-reasoner) | 128K | 128000 |\n| Qwen2.5-Turbo | 1M | 1000000 |\n| 本地 Ollama 模型 | 取决于模型 | 按实际配置 |\n\n> **注意**：`contextWindowSize` 与模型强相关，切换模型后需同步更新此值。设置窗口主界面可直接配置此值，高级选项中可配置溢出阈值等参数。\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出，`contextWindowSize` 在主界面，阈值参数点\"高级选项\"展开）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.4 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.5 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.5 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Excel | .xlsx | 支持 |\n| PowerPoint | .pptx | 支持 |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| HTML | .html | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.6 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 10 条（1 条工作便签 + 9 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（知识图谱 LightRAG）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索 + 知识图谱关联，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.7 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下一轮对话起不再出现首次使用提示（memory.json 每轮重读，写入后立即生效）\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.8 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n### 1.9 日志配置\n\n**配置文件**：`~/.niu/config/user-config.json`（首次启动从 bundle 内 `config/user-config.json` 模板复制）\n\n**配置字段**：\n\n````json\n{\n  \"logging\": {\n    \"enabled\": false,\n    \"level\": \"INFO\"\n  }\n}\n````\n\n| 字段 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `enabled` | bool | `false` | 日志总开关。`false` 时所有日志输出关闭（见下表），`true` 时按 `level` 输出 |\n| `level` | string | `\"INFO\"` | 日志级别：`DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL` |\n\n**关闭日志时（`enabled=false`，缺省）受控的日志源**：\n\n| 日志源 | 文件路径 | 控制方式 |\n|--------|----------|----------|\n| Python loguru sink | stderr | `logger.disable(\"\")` 全局禁用 |\n| Python stdlib logging | stderr | `logging.disable(CRITICAL)` 禁用 10+ 处散落 logger |\n| uvicorn 访问日志 | stderr | `log_level=\"critical\"` + `access_log=False` |\n| raw_http transport 层日志 | `~/.niu/logs/raw_http/YYYYMMDD/NNNNNN.json` | `install_http_logger()` 不 patch HTTP client + 幂等守卫 |\n| raw_http 应用层日志 | `~/.niu/logs/raw_http/YYYYMMDD/NNNNNN_request.json` + `_response.json` | `_write_raw_log()` 静默跳过 |\n| LLM interaction 可读日志 | `~/.niu/logs/llm_interaction_YYYYMMDD.log` | `_write_interaction_log()` 静默跳过 |\n| 飞书 adapter stderr | `~/.niu/logs/im_adapter_stderr.log` | `subprocess.DEVNULL` 代替文件重定向 |\n| /http-log/ HTTP 日志查看服务 | http://localhost:9876/http-log/ | router 不挂载（返回 404） |\n| Rust tracing | stderr | `tracing_subscriber` 不 init（tracing 调用静默丢弃） |\n\n**不受日志开关控制的诊断日志**（关键诊断必须保留）：\n\n| 日志源 | 文件路径 | 用途 |\n|--------|----------|------|\n| launcher 致命错误 | `~/.niu/logs/launcher_error.log` | 启动失败诊断（API 未运行、Electron 启动失败等），用 `time` crate 格式化时间戳 |\n| gateway 致命错误 | `~/.niu/logs/gateway_error.log` | 飞书 adapter 启动失败诊断（app_id 配错、端口占用、credentials 缺失） |\n\n\n**日志目录**：\n\n所有运行时日志统一写入 `~/.niu/logs/`（macOS/Linux）或 `%USERPROFILE%\\.niu\\logs\\`（Windows），不在 bundle 内（macOS Gatekeeper 禁止运行时改 bundle 内文件）。\n\n**Windows 控制台窗口**：\n\nWindows release build 下，niu.exe 编译为 GUI 子系统（`#![cfg_attr(all(target_os=\"windows\", not(debug_assertions)), windows_subsystem=\"windows\")]`），双击不弹 cmd 窗口。debug build 保留 console 方便调试。\n\n**macOS 控制台窗口**：\n\nmacOS 下构造 `niu.app` bundle（`Info.plist` 含 `LSUIElement=true`），Finder 双击不弹 Terminal。命令行 `./niu` 裸二进制仍保留供开发调试。\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}, "9ee7383bdce5aeb4e134c06e5ed706ee194e4af9": {"t": 1786068447.57199, "n": 20765, "h": "355d398e8162501c", "c": "# 用户操作手册\n\n> 本文档从 SYSTEM_MANUAL.md 拆分而来，包含用户指南的详细内容。\n> 如需系统概述和架构信息，请参阅 [SYSTEM_MANUAL.md](SYSTEM_MANUAL.md)。\n\n## 一、用户指南\n\n### 1.1 首次启动流程\n\n**初始化用户目录**\n\nRust 启动器首次运行时，会自动执行 `initNiuDir()`：\n1. 创建 `~/.niu/` 目录（如果不存在）\n2. 将 `memory/` 目录下的模板文件（`memory.json`、`preferences.json`）拷贝到 `~/.niu/`（仅当目标文件不存在时才拷贝，避免覆盖已有配置）\n\n**第一步：配置 LLM**\n\n首次启动时，如果未配置大模型，系统会自动弹出设置窗口让你输入 API Key。\n设置完成后点击\"测试连接并保存\"，窗口关闭，进入下一步。\n\n**第二步：设置工作目录**\n\n大模型配置成功后，主窗口会打开。\n如果是首次使用（memory.json 中 `firstRun` 为 `true`），大模型会主动询问你工作目录放在哪里。\n`workspace.path` 的默认值为占位文本\"请询问用户指定工作目录\"，Agent 检测到此占位文本时会主动询问用户设置真实工作目录。\n直接告诉大模型路径，例如：\"E:/我的知识库\"\n大模型会自动帮你完成初始化配置。\n\n**基本操作：**\n\n| 操作 | 方法 |\n|------|------|\n| **对话** | 直接输入文字 |\n| **入库文档** | 拖入 PDF/Word/PPT/Excel/MD/HTML 文件 |\n| **入库照片** | 拖入 JPG/PNG 照片 |\n| **搜索知识** | 问：\"搜索关于 XXX 的知识\" |\n| **创建提醒** | 说：\"明天早上 8 点提醒我开会\" |\n| **查看任务** | 问：\"查看所有定时任务\" |\n\n### 1.2 LLM 配置\n\n**配置文件**：`config/user-config.json`\n\n```json\n{\n  \"llm\": {\n    \"presetId\": \"openai\",\n    \"apiKey\": \"sk-xxx\",\n    \"apiBase\": \"https://api.openai.com/v1\",\n    \"model\": \"gpt-4o-mini\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"\",\n    \"litellm_kwargs\": {}\n  },\n  \"lightrag_llm\": {\n    \"presetId\": \"\",\n    \"apiKey\": \"\",\n    \"apiBase\": \"\",\n    \"model\": \"\",\n    \"type\": \"openai\",\n    \"provider\": \"\",\n    \"reasoning_effort\": \"none\",\n    \"litellm_kwargs\": {}\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 |\n|------|------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 |\n| `apiKey` | 你的 API Key |\n| `apiBase` | API 端点基础地址（不含路径后缀，LiteLLM 会自动追加：openai 类型追加 `/chat/completions`，anthropic 类型追加 `/v1/messages`） |\n| `model` | 模型名称 |\n| `type` | 系统内部参数，用于区分 API 格式转换和认证方式：`openai`（OpenAI 兼容格式）或 `anthropic`（Anthropic 原生格式）。**不是** LiteLLM 的 custom_llm_provider |\n| `provider` | LiteLLM 路由参数，映射为 `custom_llm_provider`。常见值：`\"\"`（空，默认由 type 决定）、`\"volcengine\"`（火山引擎）。填写后模型名无需加厂商前缀 |\n| `reasoning_effort` | 思考链深度：`\"\"`（空，由模型默认决定）、`\"none\"`（禁用）、`\"low\"`、`\"medium\"`、`\"high\"`、`\"xhigh\"`。主 Agent 默认空，LightRAG 默认 `\"none\"`。**注意**：该参数的实际效果与模型基础能力强相关，不同模型的最优值差异很大，需实测确定（详见下方\"reasoning_effort 配置与测试指南\"） |\n| `litellm_kwargs` | 厂商特有参数，JSON 对象格式，原样透传给 LiteLLM。用于传递各厂商 SDK 要求的额外参数（如火山引擎的 `thinking`、`allowed_openai_params` 等）。代码不做任何厂商判断，只负责透传 |\n\n**预设列表**：编辑 `config/llm-presets.json` 查看支持的预设。\n\n当前内置预设包括：\n\n| 预设 ID | 名称 | 类型 |\n|---------|------|------|\n| `openai` | OpenAI GPT-4o Mini | openai |\n| `openai-gpt4` | OpenAI GPT-4o | openai |\n| `anthropic` | Anthropic Claude 3.5 Sonnet | anthropic |\n| `anthropic-haiku` | Anthropic Claude 3.5 Haiku | anthropic |\n| `deepseek` | DeepSeek Chat | openai |\n| `deepseek-reasoner` | DeepSeek R1 | openai |\n| `qwen` | 通义千问 | openai |\n| `qianfan` | 百度千帆 | openai |\n| `doubao` | 豆包 | openai |\n| `moonshot` | Moonshot (Kimi) | openai |\n| `glm` | 智谱 GLM-4 Flash | openai |\n| `minimax` | MiniMax M2 | openai |\n| `minimax-anthropic` | MiniMax M2.7 (Anthropic API) | anthropic |\n| `minimax-anthropic-highspeed` | MiniMax M2.7 高速版 (Anthropic API) | anthropic |\n| `ollama` | Ollama 本地 | openai |\n| `custom` | 自定义 | openai |\n\n**火山方舟(Ark)端点配置说明**\n\n火山方舟提供两种计费端点，模型池相同，但功能权限有差异：\n\n| 端点 | 地址 | 计费 | response_format | 适用场景 |\n|------|------|------|-----------------|----------|\n| 标准端点 | `https://ark.cn-beijing.volces.com/api/v3` | 按量计费 | 支持 | 主 Agent、LightRAG |\n| Coding Plan | `https://ark.cn-beijing.volces.com/api/coding/v3` | 包月计费 | **不支持**（网关 400 拒绝） | 主 Agent |\n\n**格式化输出（response_format）能力自动探测**\n\n设置窗口\"测试连接并保存\"按钮在测试通过后，会自动追加一次格式化输出能力探测，按 3 档递进调用真实 LLM，找出当前配置支持的最强档位：\n\n| 档位 | response_format.type | 约束 | 典型支持厂商 |\n|------|---------------------|------|--------------|\n| Tier 1（最强） | `json_schema` strict | 输出严格匹配 schema | OpenAI 真正支持 |\n| Tier 2（中等） | `json_object` | 输出合法 JSON，不约束字段 | OpenAI、DeepSeek |\n| Tier 3（最弱） | 无 response_format | prompt + `json_repair` 客户端容错 | 所有厂商兜底 |\n\n**探测流程**：从 Tier 1 开始测，失败则降级测 Tier 2，再失败则定为 Tier 3。每档失败条件：\n- `model_rejected`：LiteLLM 抛 `BadRequestError`/`UnsupportedParamsError`（模型/网关 4xx 拒绝，如豆包 Coding Plan）\n- `gateway_blocked`：网关返回 200 但响应非合法 JSON（网关接受参数但模型输出漂移，如 GLM xopglm5）\n\n探测采用三次采样 + 冲突式设计：\n- 三次采样全过才升档，任何一次失败立即降级——防 flaky 网关（豆包 Coding\n  Plan 2026-07-21 实测：同一请求 5 次采样 2 次执行、3 次静默忽略）碰巧\n  命中执行窗口期误判支持\n- 冲突式设计：schema 强制要求 `{\"verdict\": \"SCHEMA_ENFORCED\"}`，prompt\n  却要求模型写普通英文句子且禁止输出 JSON——只有 schema 战胜 prompt\n  （输出被强制为 schema JSON）才判定真支持，模型跟随 prompt 输出普通\n  文本即判定网关静默忽略\n- 限流单独处理：RateLimitError 不计失败，sleep 后重试本次采样（指数\n  退避 5s→10s→20s→40s→80s，最多 5 次），直到返回非限流结果才判定\n\n**写入配置**：\n- `lightrag_llm.litellm_kwargs.response_format_mode`：`\"json_schema\"` / `\"json_object\"` / `\"prompt_only\"`\n- `lightrag_llm.litellm_kwargs.allowed_openai_params`：前两档 `[\"response_format\"]`，prompt_only 档 `[]`（双写兼容旧逻辑）\n\n**典型场景**（2026-07-19 实测）：\n- 豆包 Coding Plan 端点（`/api/coding/v3`，model=`ark-code-latest`）：\n  网关行为非确定性（flaky），同一请求多次采样结果不稳定（有时执行\n  json_schema strict、有时静默忽略），三次采样必然 ≥1 次静默忽略 →\n  探测结果稳定 `prompt_only`\n- GLM 端点（`maas-coding-api.cn-huabei-1.xf-yun.com/v2`，model=`xopglm5`）：网关接受但模型输出漂移，探测结果 `prompt_only`\n- OpenAI 官方：探测结果 `json_schema`\n\n**升级后自动探测**：旧版本用户配置无 `response_format_mode` 字段。程序启动后若检测到该字段缺失，后台自动触发一次探测写入配置，不阻塞启动。\n\n**手动覆盖**：关闭程序后手动编辑 `config/user-config.json` 的 `lightrag_llm.litellm_kwargs.response_format_mode`。下次设置窗口测试保存会覆盖手动值。\n\n**注意**：\n- 探测调用会消耗约 100-200 token（最坏情况测到 Tier 2）。仅\"测试连接并保存\"按钮触发，不引入后台定时探测（升级后首次启动除外）。\n- 探测独立于启动时的 LLM 连通性测试（`/api/test-llm`），不影响启动速度。\n\n> **重要**：LightRAG 的 keyword_extraction 依赖 `response_format`，必须使用标准端点。如果误用 Coding Plan 端点，本次升级后的\"格式化输出能力自动探测\"会识别为 `prompt_only` 档位并写入配置，运行时 LightRAG 直接走 prompt-only 路径（不再每次发无效请求触发 400 后 fallback）。详见上方\"格式化输出（response_format）能力自动探测\"小节。\n\n**火山方舟深度思考模型 + 工具调用配置**（重要）：\n\n火山方舟的 `doubao-seed` 系列模型（包括 `ark-code-latest`）默认启用深度思考模式。当 `litellm_kwargs` 中未显式传递 `thinking` 参数时，API 没有结构化工具调用保障——模型偶发将 tool_call 放入 `reasoning_content` 的 `<seed:tool_call>` XML 格式，而非标准的 `tool_calls` 字段，导致工具调用丢失。\n\n**主 Agent 必须配置**：\n```json\n\"llm\": {\n  ...\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n| `thinking` 值 | 效果 | 适用场景 |\n|---------------|------|----------|\n| `{\"type\": \"enabled\"}` | 显式启用深度思考，API 网关保障 tool_call 走标准通道 | **主 Agent（必须）** |\n| `{\"type\": \"disabled\"}` | 禁用深度思考 | LightRAG 入库（需配合 `response_format`） |\n| `{\"type\": \"auto\"}` | 模型自行决定 | 不推荐（行为不确定） |\n| 不传 | 模型默认启用思考，但无 tool_call 保障 | **危险：工具调用可能丢失** |\n\n> **注意**：`thinking` 参数通过 `litellm_kwargs` 原样透传给 LiteLLM，再由 VolcEngine 适配器转为 API 请求的 `extra_body.thinking` 字段。代码不做任何厂商判断，所有厂商特有参数都走这个透传通道。\n\n**模型名格式差异**：\n\n两种端点的模型池相同，但模型名格式不同：\n\n| 端点 | 模型名格式 | 示例 |\n|------|-----------|------|\n| 标准端点 | 带日期后缀的全名 | `doubao-seed-2-0-pro-260215` |\n| Coding Plan | 简短别名 | `doubao-seed-2.0-pro` |\n\n> **注意**：在标准端点上使用 Coding Plan 的简短别名会返回 404；反之，在 Coding Plan 端点上两种格式都能用。\n\n**LiteLLM 路由配置**：\n\n使用 LiteLLM 调用火山方舟模型时，必须通过 `provider: \"volcengine\"` 走 VolcEngine 适配器路由。这是 LiteLLM 的标准机制：\n\n| 配置方式 | 路由 | 结果 |\n|----------|------|------|\n| `provider: \"volcengine\"` + `model: \"doubao-seed-2.0-pro\"` | VolcEngine 适配器 | 正确：`thinking` 参数自动处理，厂商特有参数通过 `litellm_kwargs` 透传 |\n| `model: \"volcengine/doubao-seed-2.0-pro\"`（无 provider） | VolcEngine 适配器 | 也可：LiteLLM 通过前缀推断路由，但不如 `provider` 显式 |\n| `model: \"doubao-seed-2.0-pro\"`（无 provider 无前缀） | OpenAI 适配器 | **错误**：`thinking` 等火山特有参数无法传递 |\n\n> **注意**：`type: \"openai\"` 是系统内部参数（区分 Anthropic/OpenAI 格式转换），不是 LiteLLM 的 `custom_llm_provider`。两者独立：`type` 控制格式，`provider` 控制路由。\n\n**可用模型**：doubao-seed-2.0-code、doubao-seed-2.0-pro、doubao-seed-2.0-lite、minimax-m2.7、minimax-m3、glm-5.1、kimi-k2.6、deepseek-v4-pro、deepseek-v4-flash、ark-code-latest\n\n**LightRAG 知识图谱 LLM 配置**：`lightrag_llm` 段\n\nLightRAG 入库（实体提取、关系构建）使用与主 Agent 独立的 LLM 配置。`model` 和 `reasoning_effort` 是两个独立的配置维度，互不依赖。\n\n**`lightrag_llm` 字段说明**：\n\n| 字段 | 说明 | 建议值 |\n|------|------|--------|\n| `presetId` | 预设 ID，对应 llm-presets.json 中的预设 | `doubao`（豆包，轻量快速） |\n| `apiKey` | API Key。为空时自动继承 `llm` 段的 apiKey | 空（继承主配置） |\n| `apiBase` | API 端点地址。为空时自动继承 `llm` 段的 apiBase | 空（继承主配置） |\n| `model` | 模型名称。为空时使用主 Agent 同一模型 | `doubao-seed-2.0-pro`（Coding Plan 别名）或 `doubao-seed-2-0-pro-260215`（标准端点全名） |\n| `type` | 类型：`openai` 或 `anthropic` | `openai` |\n| `provider` | LiteLLM 路由参数，同 `llm` 段说明。火山引擎填 `\"volcengine\"` | `\"\"` 或 `\"volcengine\"` |\n| `reasoning_effort` | **思考链深度（核心配置）** | `\"none\"`（禁用，见下表） |\n| `temperature` | LLM 采样温度。0.0 完全确定性，1.0 高随机度。为空时由系统兜底 0.2 | `0.2`（实体/关系抽取建议低温度避免 JSON 漂移） |\n| `litellm_kwargs` | 厂商特有参数，同 `llm` 段说明。火山引擎知识图谱需传 `thinking` 和 `allowed_openai_params` | `{}` 或见配置示例 |\n\n> **重要**：LightRAG 官方建议入库时不要使用带思考链的模型。思考链会导致实体提取超时（单次调用可达 198 秒）。`reasoning_effort` 默认 `\"none\"` 确保即使主 Agent 使用思考链模型，入库也不受影响。\n\n> **温度值说明**：LightRAG 调 LLM 时如果不配 `temperature` 字段，系统兜底默认 `0.2`。这是为实体抽取、关系抽取等结构化任务优化的低温度值，避免高随机度导致 JSON 格式漂移、实体名不一致。如果需要更稳定的输出可设 `0.0`，需要更多创造性可设 `0.5~0.7`，但不建议超过 `1.0`。主 Agent / 子 Agent 的温度值在提示词文档里独立配置（主 Agent 0.6、子 Agent 多数 0.2），与此处的 `lightrag_llm.temperature` 完全独立，互不影响。\n\n**reasoning_effort 参数说明**：\n\n| 值 | 效果 | 建议场景 |\n|----|------|----------|\n| `none` | 完全禁用 | 建议初始使用时，根据模型情况自己测试后确定 |\n| `low` | 浅层推理 | 模型推理速度极慢时，可选用 |\n| `medium` | 中等推理 | 非入库的图谱查询任务；部分模型入库也可用 |\n| `high` | 深度推理 | 建议用于入库（推理预算耗尽，输出质量高） |\n| `xhigh` | 最深推理 | 不建议用于入库 |\n\n**reasoning_effort 配置与测试指南**：\n\n`reasoning_effort` 的最优值与模型基础能力强相关，不存在通用最优值。实测数据（ark-code-latest 模型入库 SYSTEM_MANUAL.md）：\n\n| 配置 | 实体类型准确率 | 空响应率 | 补充提取有效性 | 综合评分 |\n|------|--------------|---------|--------------|---------|\n| `none` | 67% | 60% | 无 | 5.5/10 |\n| `low` | 95% | 40% | 有效 | **7.5/10** |\n| `medium` | 14% | 40% | 部分 | 6.0/10 |\n| `high` | 分裂 | 40% | 无 | 4.0/10 |\n\n关键发现：\n1. **推理越深不一定越好**：推理token被模型内部消耗，不转化为输出质量。过度推理反而导致实体类型误分类（如子Agent被归为organization而非technology）\n2. **补充提取受影响**：高推理级别下模型过度自信，判断\"无需补充\"，导致遗漏无法弥补\n3. **不同模型差异很大**：能力强的模型（如 Claude、GPT-4o）在 `none` 或 `low` 即可高质量提取；能力有限的模型可能需要 `high`，但也可能适得其反\n\n**换模型后必须实测**：更改模型或 reasoning_effort 后，用同一文档入库并检查日志验证效果。\n\n**入库质量检查方法**：\n1. 入库后检查日志目录 `logs/raw_http/YYYYMMDD/`，读取 `*_response.json` 文件\n2. 检查空响应：响应体仅含 `<|COMPLETE|>` 或 content 为空，说明该轮提取失败\n3. 检查实体类型：子Agent应为 technology 而非 person/organization；MCP服务器应为 technology 而非 organization\n4. 检查违规节点：不应出现与 niu 根节点重名的实体\n5. 检查补充提取：`*_response.json` 中补充提取应有实质内容（非仅 `<|COMPLETE|>`）\n6. 如发现问题，调整 reasoning_effort 重新入库测试\n\n**配置示例**：\n\n主 Agent 用火山方舟 Coding Plan（完整配置）：\n```json\n\"llm\": {\n  \"presetId\": \"ark-code-latest\",\n  \"apiKey\": \"你的API Key\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/coding/v3\",\n  \"model\": \"ark-code-latest\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"\",\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"enabled\"}\n  }\n}\n```\n\n场景一：主 Agent 用思考链模型，LightRAG 用轻量模型（推荐）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"doubao\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"https://ark.cn-beijing.volces.com/api/v3\",\n  \"model\": \"doubao-seed-2-0-pro-260215\",\n  \"type\": \"openai\",\n  \"provider\": \"volcengine\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {\n    \"thinking\": {\"type\": \"disabled\"},\n    \"allowed_openai_params\": [\"response_format\"]\n  }\n}\n```\n\n> **注意**：LightRAG 必须使用标准端点（apiBase 含 /api/v3），不能用 Coding Plan 端点（/api/coding/v3），因为 Coding Plan 网关 400 拒绝 response_format。设置窗口\"测试连接并保存\"会自动探测并写入 `response_format_mode=prompt_only`（豆包 Coding Plan 场景）。model 必须用标准端点的全名格式（带日期后缀）。\n> **LiteLLM 路由**：`provider: \"volcengine\"` 让 LiteLLM 走 VolcEngine 适配器。`litellm_kwargs` 中的 `thinking: {\"type\": \"disabled\"}` 关闭思考链（火山要求使用 response_format 时必须关闭），`allowed_openai_params: [\"response_format\"]` 让 VolcEngine 适配器透传 response_format 参数。\n\n场景二：主 Agent 和 LightRAG 用同一模型，独立控制思考深度（零配置即生效）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"low\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n场景三：能力强的模型，禁用思考链即可（如 Claude、GPT-4o）：\n```json\n\"lightrag_llm\": {\n  \"presetId\": \"\",\n  \"apiKey\": \"\",\n  \"apiBase\": \"\",\n  \"model\": \"\",\n  \"type\": \"openai\",\n  \"provider\": \"\",\n  \"reasoning_effort\": \"none\",\n  \"temperature\": 0.2,\n  \"litellm_kwargs\": {}\n}\n```\n\n**通过 MCP 工具动态修改**（无需重启）：\n- 读取配置：调用 `get_lightrag_llm_config` 工具\n- 修改配置：调用 `set_lightrag_llm_config` 工具，参数与字段名对应\n- 清除模型（回退到主模型）：调用 `set_lightrag_llm_config(model=\"\")`\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n- **方式三**：通过 MCP 工具 `set_lightrag_llm_config` 动态修改（无需重启）\n\n### 1.3 上下文配置\n\n**配置文件**：`config/user-config.json` 中的 `context` 段\n\n```json\n{\n  \"context\": {\n    \"contextWindowSize\": 200000,\n    \"warningThreshold\": 0.8,\n    \"targetThreshold\": 0.5,\n    \"sleepTriggerMinutes\": 5\n  }\n}\n```\n\n**字段说明**：\n\n| 字段 | 说明 | 默认值 | 范围 |\n|------|------|--------|------|\n| `contextWindowSize` | 模型上下文窗口大小（tokens） | 200000 | 32000 ~ 2000000 |\n| `warningThreshold` | 溢出警告阈值，上下文使用率超过此值触发压缩 | 0.8 | 0.0 ~ 1.0 |\n| `targetThreshold` | 强制压缩目标，压缩后上下文使用率降至此值 | 0.5 | 0.0 ~ 1.0 |\n| `sleepTriggerMinutes` | 空闲多久后触发睡眠整理（分钟） | 5 | > 0 |\n\n**常见模型的 contextWindowSize**：\n\n| 模型 | 上下文窗口 | 配置值 |\n|------|-----------|--------|\n| GPT-4o-mini | 128K | 128000 |\n| GPT-4o | 128K | 128000 |\n| Claude 3.5 Sonnet | 200K | 200000 |\n| DeepSeek V3 (deepseek-chat) | 64K | 64000 |\n| DeepSeek R1 (deepseek-reasoner) | 128K | 128000 |\n| Qwen2.5-Turbo | 1M | 1000000 |\n| 本地 Ollama 模型 | 取决于模型 | 按实际配置 |\n\n> **注意**：`contextWindowSize` 与模型强相关，切换模型后需同步更新此值。设置窗口主界面可直接配置此值，高级选项中可配置溢出阈值等参数。\n\n**修改配置方式**：\n- **方式一（推荐）**：通过设置窗口修改（首次启动自动弹出，`contextWindowSize` 在主界面，阈值参数点\"高级选项\"展开）\n- **方式二**：关闭程序后，手动编辑 `config/user-config.json`\n\n### 1.4 知识图谱\n\n知识图谱基于 LightRAG 引擎，支持文档入库后的自动实体提取和关系构建。\n\n**查询方式**：\n- 直接向大模型提问（如：\"XXX 和 YYY 有什么关系？\"）\n- 通过知识图谱可视化界面浏览实体关系（`/api/kg/snapshot`、`/api/kg/explore`）\n\n**存储位置**：`~/.niu/lightrag_storage/`（LightRAG 固定存储路径，不随 workspace.path 变化）\n\n**架构说明**：知识图谱和向量检索已统一由 `lightrag-server` 提供（23 个工具），取代了旧版独立的 `vector-store` 和 `kg-server`。旧的 `kg-server`（KuzuDB）和 `vector-store` 已禁用（`preload: false`）。\n\n**注意**：文档入库时，LightRAG 自动完成实体提取、关系构建和向量索引，无需手动操作。\n\n**注意**：并非所有文档格式都支持知识图谱入库，详见下方\"1.5 支持的文件格式\"。\n\n**入库参数配置**：LightRAG 入库参数（并发数、分片大小、补充提取次数等）可在 `~/.niu/preferences.json` 的 `lightrag` 配置段调整，详见 [知识检索运维手册](manual-vector-store.md) 第 8.5 节。\n\n**入库模型与思考链配置**：LightRAG 入库使用的模型和思考链深度在 `config/user-config.json` 的 `lightrag_llm` 配置段设置，详见上方 1.2 节\"LightRAG 知识图谱 LLM 配置\"。默认禁用思考链（`reasoning_effort: \"none\"`），防止深度推理导致入库超时。\n\n### 1.5 支持的文件格式\n\nNiu 有两种入库能力，格式支持范围不同：\n\n**文件存储入库**：将文件复制到知识库目录，所有文档格式均支持。\n\n**知识图谱入库**：将文件内容写入 LightRAG 知识图谱，仅支持以下格式。\n\n#### 文件存储支持的格式\n\n| 格式 | 扩展名 | 知识图谱入库 |\n|------|--------|-------------|\n| PDF | .pdf | 支持 |\n| Word | .docx | 支持 |\n| Excel | .xlsx | 支持 |\n| PowerPoint | .pptx | 支持 |\n| 纯文本 | .txt | 支持 |\n| Markdown | .md | 支持 |\n| HTML | .html | 支持 |\n\n#### 不支持知识图谱入库的格式及原因\n\n| 扩展名 | 原因 |\n|--------|------|\n| .doc | 旧版二进制格式（OLE2），无法可靠提取纯文本 |\n| .xls | 旧版二进制格式（BIFF），无法可靠提取纯文本 |\n| .ppt | 旧版二进制格式，无法可靠提取纯文本 |\n| WPS 假 .docx | WPS 创建的 .docx 文件实际是 OLE2 格式（旧版 .doc），程序会自动检测并标记为不支持知识图谱入库 |\n\n> **建议**：如果 .doc/.xls/.ppt 文件需要入库知识图谱，请先用 Office 或 WPS 另存为 .docx/.xlsx/.pptx 格式。\n\n#### 照片入库支持的格式\n\n| 格式 | 扩展名 | 说明 |\n|------|--------|------|\n| JPEG | .jpg / .jpeg | 支持存储 + 人脸识别 |\n| PNG | .png | 支持存储 + 人脸识别 |\n| GIF | .gif | 支持存储 + 人脸识别 |\n| BMP | .bmp | 支持存储 + 人脸识别 |\n| WebP | .webp | 支持存储 + 人脸识别 |\n| HEIC | .heic / .heif | 支持存储 + 人脸识别 |\n\n> 照片格式仅支持存储和人脸识别，不支持知识图谱入库。\n\n详细格式说明和常见问题，请参阅 [文件格式支持手册](manual-file-formats.md)。\n\n### 1.6 记忆管理\n\n记忆系统分为两层：\n\n**1. 用户长期记忆（memory.json，驻留系统提示词）**\n- 存储路径：`~/.niu/memory.json` 的 `permanent` 数组\n- 工具：`user_memory_remember`、`user_memory_forget`、`user_memory_list`\n- 容量：最多 10 条（1 条工作便签 + 9 条长期记忆），每条不超过 200 token\n- 便签（type=task）：新任务自动覆盖旧便签\n- 特点：每轮对话自动注入系统提示词，大模型始终可见\n\n**用户信息配置（memory.json 的 user 字段）**：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `name` | 用户真实姓名 | 李磊 |\n| `nickname` | 用户称呼/昵称，主Agent用此称呼用户 | 老板 |\n| `occupation` | 用户职业，影响内容提取和日志编写的专业视角 | 软件工程师 |\n| `organization` | 用户工作单位，影响内容提取和日志编写的专业视角 | 某科技公司 |\n\n- 这些信息会自动注入到主Agent和子Agent的系统提示词中\n- 缺失时主Agent会主动询问用户并写入\n- 修改方式：告诉主Agent\"我的职业是XXX\"或\"我在XXX工作\"，主Agent会自动更新 memory.json\n\n**2. 语义记忆（知识图谱 LightRAG）**\n- 工具：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories`\n- 特点：基于语义相似度检索 + 知识图谱关联，支持大量信息\n- 用途：对话摘要、技术笔记、经验知识等\n\n**操作示例**：\n- 查看记忆：问 \"你记得我的什么信息？\"\n- 添加记忆：说 \"记住我的工作单位是 XXX\"\n- 删除记忆：说 \"忘记我的工作单位信息\"\n\n### 1.7 首次使用（firstRun）\n\n**触发条件**：`~/.niu/memory.json` 中 `firstRun` 为 `true`\n\n**大模型处理流程**：\n\n1. 在 system prompt 中看到\"## 首次使用\"段落\n2. 主动询问用户工作目录\n3. 用户回答路径（如：E:/我的知识库）\n4. 大模型用 bash 工具完成设置：\n   - 创建目录（如果不存在）\n   - 写入 `~/.niu/memory.json`：设置 `workspace.path`，将 `firstRun` 设为 `false`\n\n> 代码中实际将 `firstRun` 设为 `false`，而非删除该字段。\n\n5. 大模型询问用户基本信息（真实姓名、称呼、职业、工作单位），用户回答后写入 memory.json 的 user 字段\n\n6. 完成后，下一轮对话起不再出现首次使用提示（memory.json 每轮重读，写入后立即生效）\n\n**禁止事项**：\n- 不要询问用户 API Key（由设置窗口处理）\n- 只询问工作目录\n\n### 1.8 常见问题\n\n**Q: 数据存储在哪里？**\n```\nA: 数据分布在两个位置：\n\n~/.niu/ 目录：\n- 历史对话：~/.niu/messages.db\n- 用户记忆：~/.niu/memory.json\n- 知识图谱：~/.niu/lightrag_storage/\n- 定时任务：~/.niu/scheduled_tasks.db\n- 程序配置：config/ 目录\n\n工作区目录（由 workspace.path 决定）：\n- 定时任务：{workspace}/scheduled_tasks.db（优先路径）\n- 入库文档：{workspace}/documents/\n```\n\n**Q: 可以离线使用吗？**\n```\nA: 可以！所有功能都支持离线，除了：\n- 首次启动下载模型（需要网络）\n- 云端 LLM API（需要网络）\n\n本地 Ollama + 预下载模型 = 完全离线使用\n```\n\n**Q: 如何备份数据？**\n```\nA: 定期复制以下目录：\n- ~/.niu/        (记忆、对话记录、知识图谱、定时任务、配置)\n- {workspace}/documents/   (入库文档)\n\nworkspace 路径在 ~/.niu/memory.json 的 workspace.path 字段中。\n```\n\n**Q: 支持多用户吗？**\n```\nA: 当前版本为单用户设计，所有数据在本地。\n多用户支持计划在未来版本中实现。\n```\n\n**Q: GPU 加速有什么要求？**\n```\nA: NVIDIA GPU：\n- 显卡：GTX 1060 或更高\n- CUDA：安装 CUDA Toolkit 12.x\n- 安装：pip install onnxruntime-gpu\n\nWindows + 任意 GPU：\n- 安装：pip install onnxruntime-directml\n- 无需 CUDA\n```\n\n**Q: 如何卸载？**\n```\nA: 1. 关闭程序\n   2. 删除安装目录\n   3. 删除用户数据（可选）：\n      - C:\\Users\\用户名\\.niu\\\n```\n\n### 1.9 日志配置\n\n**配置文件**：`~/.niu/config/user-config.json`（首次启动从 bundle 内 `config/user-config.json` 模板复制）\n\n**配置字段**：\n\n````json\n{\n  \"logging\": {\n    \"enabled\": false,\n    \"level\": \"INFO\"\n  }\n}\n````\n\n| 字段 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `enabled` | bool | `false` | 日志总开关。`false` 时所有日志输出关闭（见下表），`true` 时按 `level` 输出 |\n| `level` | string | `\"INFO\"` | 日志级别：`DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL` |\n\n**关闭日志时（`enabled=false`，缺省）受控的日志源**：\n\n| 日志源 | 文件路径 | 控制方式 |\n|--------|----------|----------|\n| Python loguru sink | stderr | `logger.disable(\"\")` 全局禁用 |\n| Python stdlib logging | stderr | `logging.disable(CRITICAL)` 禁用 10+ 处散落 logger |\n| uvicorn 访问日志 | stderr | `log_level=\"critical\"` + `access_log=False` |\n| raw_http transport 层日志 | `~/.niu/logs/raw_http/YYYYMMDD/NNNNNN.json` | `install_http_logger()` 不 patch HTTP client + 幂等守卫 |\n| raw_http 应用层日志 | `~/.niu/logs/raw_http/YYYYMMDD/NNNNNN_request.json` + `_response.json` | `_write_raw_log()` 静默跳过 |\n| LLM interaction 可读日志 | `~/.niu/logs/llm_interaction_YYYYMMDD.log` | `_write_interaction_log()` 静默跳过 |\n| 飞书 adapter stderr | `~/.niu/logs/im_adapter_stderr.log` | `subprocess.DEVNULL` 代替文件重定向 |\n| /http-log/ HTTP 日志查看服务 | http://localhost:9876/http-log/ | router 不挂载（返回 404） |\n| Rust tracing | stderr | `tracing_subscriber` 不 init（tracing 调用静默丢弃） |\n\n**不受日志开关控制的诊断日志**（关键诊断必须保留）：\n\n| 日志源 | 文件路径 | 用途 |\n|--------|----------|------|\n| launcher 致命错误 | `~/.niu/logs/launcher_error.log` | 启动失败诊断（API 未运行、Electron 启动失败等），用 `time` crate 格式化时间戳 |\n| gateway 致命错误 | `~/.niu/logs/gateway_error.log` | 飞书 adapter 启动失败诊断（app_id 配错、端口占用、credentials 缺失） |\n\n\n**日志目录**：\n\n所有运行时日志统一写入 `~/.niu/logs/`（macOS/Linux）或 `%USERPROFILE%\\.niu\\logs\\`（Windows），不在 bundle 内（macOS Gatekeeper 禁止运行时改 bundle 内文件）。\n\n**Windows 控制台窗口**：\n\nWindows release build 下，niu.exe 编译为 GUI 子系统（`#![cfg_attr(all(target_os=\"windows\", not(debug_assertions)), windows_subsystem=\"windows\")]`），双击不弹 cmd 窗口。debug build 保留 console 方便调试。\n\n**macOS 控制台窗口**：\n\nmacOS 下构造 `niu.app` bundle（`Info.plist` 含 `LSUIElement=true`），Finder 双击不弹 Terminal。命令行 `./niu` 裸二进制仍保留供开发调试。\n\n---\n\n## 验证记录\n\n2026-04-30 验证并修正以下内容：\n\n| 位置 | 原文 | 修正后 |\n|------|------|--------|\n| 8.2 LLM 预设表 | `minimax` 对应模型名 \"MiniMax\" | 修正为 \"MiniMax M2\"（与 llm-presets.json 中 model 字段一致） |\n| 8.2 LLM 预设表 | `minimax-anthropic-highspeed` 描述 \"MiniMax M2.7 高速版\" | 修正为 \"MiniMax M2.7 高速版 (Anthropic API)\"（与实际 preset description 一致） |\n| 8.2 apiBase 说明 | \"含 `/chat/completions` 后缀\" | 补充说明：openai 类型含 `/chat/completions`，anthropic 类型含 `/v1/messages` |\n| 8.3 存储位置 | \"工作目录下的 LightRAG 数据文件（由 workspace.path 决定）\" | 修正为 `~/.niu/lightrag_storage/`（LightRAG 固定路径，不随 workspace 变化） |\n| 8.3 查询方式 | 仅提到\"可视化界面浏览\" | 补充具体 API 端点：`/api/kg/snapshot`、`/api/kg/explore` |\n| 8.3 架构说明 | 无 | 新增：说明 lightrag-server 已统一取代旧版 vector-store 和 kg-server |\n| 8.4 语义记忆工具 | 仅列出 `remember`、`recall` | 补充完整工具列表：`remember`、`recall`、`update_memory`、`get_memory_stats`、`cleanup_memories`、`link_memories` |\n| 8.4 用户记忆便签 | 无 | 补充：便签（type=task）新任务自动覆盖旧便签 |\n| 8.5 首次启动触发 | \"memory.json 中存在 `firstRun` 字段\" | 修正为 \"memory.json 中 `firstRun` 为 `true`\"（字段值判断而非字段存在判断） |\n| 8.5 首次启动步骤 | 包含手动执行 `init_vector_db.py` 步骤 | 移除：向量库初始化已集成到启动流程，无需手动执行 |\n| 8.6 数据存储 | 知识图谱路径 `{workspace}/lightrag/` | 修正为 `~/.niu/lightrag_storage/` |\n| 8.6 数据存储 | 定时任务路径仅 `{workspace}/scheduled_tasks.db` | 补充 fallback 路径 `~/.niu/scheduled_tasks.db`，说明优先使用 workspace 路径 |\n| 8.6 数据存储 | 历史对话路径 | 确认正确路径为 `~/.niu/messages.db`（单文件 SQLite，非目录） |\n| 8.6 数据存储 | 列出 `vectors.db` 和 `{workspace}/lightrag/` | 移除旧向量索引引用，改为 `~/.niu/lightrag_storage/` |\n| 8.6 备份 | 备份 `~/.niu/` + `{workspace}/` | 修正为 `~/.niu/` + `{workspace}/documents/`（LightRAG 数据已在 ~/.niu 下） |\n"}}}}