# 小秘书 MCP（secretary-mcp）

给主 Agent 减负的子 Agent 模式 MCP。只向主模型暴露三个高层工具：

| 工具 | 作用 | 子 Agent 内部可用能力 |
|---|---|---|
| `ask_memory` | 回忆此前记住的偏好/事实/笔记 | memory_search / memory_list / memory_read |
| `ask_web` | 联网查证一个问题，返回凝练结论+来源 | web_search / fetch_url（多轮搜索→精读→再搜） |
| `delegate` | 整体交办一件多步骤杂活 | 上述全部 + memory_write |

核心机制：主模型上下文只增加「一次工具调用 + 一条凝练结论」。子 Agent 的多轮
tool_call（搜索 → 打开网页 → 再搜 → 收敛）全部发生本进程内，原始网页大段文本、
搜索结果列表永远不会进主模型上下文。子 Agent 必须通过 `submit_answer` 提交结论，
并有轮次上限（默认 10 轮，超限强制收敛）。

## 配置（MCP 客户端接入）

```json
{
  "mcpServers": {
    "secretary": {
      "command": "node",
      "args": ["<本目录绝对路径>/dist/index.js"],
      "env": {
        "LLM_API_KEY": "你的 API Key",
        "LLM_BASE_URL": "https://open.bigmodel.cn/api/paas/v4",
        "LLM_MODEL": "glm-4.5-flash",
        "SECRETARY_MEMORY_DIR": "<本目录绝对路径>/memory",
        "TAVILY_API_KEY": "可选，推荐配置"
      }
    }
  }
}
```

### 环境变量

| 变量 | 必填 | 说明 |
|---|---|---|
| `LLM_API_KEY` | ✅ | 子 Agent 用的便宜模型 API Key |
| `LLM_BASE_URL` | | OpenAI 兼容端点，默认智谱 `https://open.bigmodel.cn/api/paas/v4`（DashScope/DeepSeek/OpenAI 均可） |
| `LLM_MODEL` | | 默认 `glm-4.5-flash` |
| `SECRETARY_MEMORY_DIR` | | 记忆库目录，默认 `./memory` |
| `TAVILY_API_KEY` | | 搜索供应商；不配则回退 DuckDuckGo HTML（无密钥但可能被限流） |
| `SUBAGENT_MAX_TURNS` | | 子 Agent 最大轮次，默认 10 |

## 构建

```bash
npm install
npm run build
```

## 设计说明

- **记忆库**：本地 markdown 文件（可手改），按段落切块 + 关键词词频打分检索，
  内置中文虚词停用词表，零向量库依赖。
- **搜索**：有 `TAVILY_API_KEY` 走 Tavily；否则解析 DuckDuckGo HTML 页（宽松解析，
  改版/限流会失败，生产建议配 Tavily）。
- **网页抓取**：剥掉 script/style 取正文，单页截断 9000 字符，防止子 Agent 上下文爆炸。
- **容错**：模型不调 `submit_answer` 而直接输出文本时视为最终答案；轮次用尽则强制
  无工具收敛一次；工具报错会作为消息回给子 Agent 让它自行调整。

## 已知取舍

- 记忆检索是词频匹配，不是语义检索——查询词需要和记忆原文有字面重叠。
- delegate 的子 Agent 有 memory_write 权限，可写任意 `.md` 文件（已做路径逃逸防护）。
- 主 Agent 应给 delegate 传自包含的任务描述，子 Agent 看不到主对话。