# NudgeDoc

**Agent 生成的 Markdown → 飞书云文档 + 私聊卡片。**  
文档你不主动看？让 Bot 来 nudge 你。

## 功能（V1）

- 任意 Markdown → 飞书 Docx
- 默认给 `FEISHU_TARGET_OPEN_ID` 发私聊卡片（标题 + 摘要 + 打开链接）
- **MCP Server**（Cursor 主路径）+ **CLI**（Claude Code / 脚本备用）

## 快速开始

```bash
cd ~/Developer/person/nudge-doc
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

cp .env.example .env
# 填入新建飞书应用的 FEISHU_APP_ID / SECRET / TARGET_OPEN_ID
```

### CLI

```bash
nudgedoc push --title "本周学习路线" --file plan.md

# 或 stdin
echo "# Hello" | nudgedoc push --title "Test"

# 只建 Doc，不发卡片
nudgedoc push --title "Test" --file plan.md --no-card
```

### Cursor MCP

`~/.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "nudgedoc": {
      "command": "/Users/pingzi/Developer/person/nudge-doc/.venv/bin/python",
      "args": ["-m", "nudgedoc", "mcp"],
      "env": {
        "FEISHU_APP_ID": "cli_xxx",
        "FEISHU_APP_SECRET": "xxx",
        "FEISHU_TARGET_OPEN_ID": "ou_xxx"
      }
    }
  }
}
```

对话中说：**「把这份学习计划推到飞书」** → Agent 调用 `push_markdown`。

## 飞书新应用权限（V1 最小集）

在 [飞书开放平台](https://open.feishu.cn/) 创建**独立应用**（不要与 Agent-Pilot 共用）：

| 权限 | 用途 |
|------|------|
| `im:message:send_as_bot` | 发私聊卡片 |
| `docx:document` | 创建 / 编辑文档 |
| `cardkit:card:write` | 交互卡片（可选，当前用 interactive 消息） |

**V1 不需要**事件订阅长连接（只主动 OpenAPI 推送）。

获取 `open_id`：把 Bot 加到测试范围 → 私聊 Bot 发消息 → 开放平台「测试企业与人员」查看，或从 Bot 日志读取。

## 架构

```
Cursor Agent ──MCP──► nudgedoc.push_markdown
Claude CLI   ──Shell► nudgedoc push
                          │
                          ├─► Feishu Docx API
                          └─► IM card → your open_id
```

## V2 Roadmap（占位）

- [ ] 读取 Agent / Cursor 对话历史
- [ ] 自动总结周计划并推送
- [ ] 本地 `push_history.jsonl` 或 sqlite

见 `nudgedoc/memory/`。

## License

MIT