sophhub 0.2.4 → 0.4.0

package/skills/notes-hub-assistant/src/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: notes-hub-assistant
+description: 统一处理飞书、Notion、wolai 三类笔记工作流。支持创建、读取、更新、删除、搜索、评论与附件写入；根据用户输入自动路由到对应平台并执行平台专属约束。触发场景包括“写入笔记”“同步到某笔记平台”“查找历史笔记”“按链接读取笔记”“把会议纪要整理到笔记”等。wolai 路线使用官方 OpenAPI。
+version: 1.0.0
+metadata:
+  openclaw:
+    requires:
+      bins: ["python3", "node", "npx", "mcporter"]
+---
+
+# Notes Hub Assistant
+
+统一入口，整合以下 3 个平台能力：
+
+- Feishu Notes（含 Minutes -> Note）
+- Notion（vibe-notionbot）
+- wolai（OpenAPI）
+
+> **暂时下线**：印象笔记（Evernote）相关路由与 OpenClaw 工具链已暂时关闭；不要调用 `evernote.*`、不要提示 `openclaw evernote login`、不要将用户意图路由到印象笔记。若用户明确要求印象笔记，说明当前已暂停支持并建议在飞书 / Notion / wolai 中选其一。
+
+目标：用户只描述“要做什么”，你负责“选平台 + 执行 + 返回结果”。
+
+## 1. 路由优先级
+
+按以下顺序判断目标平台：
+
+1. **用户明确点名平台**（如“写到 Notion”）-> 直接路由
+2. **输入包含特征链接/标识** -> 自动路由
+   - `*.feishu.cn/minutes/` -> Feishu Minutes -> Note
+   - `feishu.cn/docx/` 或飞书 doc token -> Feishu Notes
+   - `notion.so` 链接或 Notion page/database id -> Notion
+   - `wolai.com` 页面链接或存在 `WOLAI_APP_TOKEN` / (`WOLAI_APP_ID` + `WOLAI_APP_SECRET`) 场景 -> wolai
+3. **未指定平台** -> 仅追问一次：`你希望写入飞书、Notion，还是 wolai？`
+
+不要在平台已明确时重复追问。
+
+## 2. 统一能力模型
+
+所有请求先映射到统一动作，再执行平台命令：
+
+- `create`：新建笔记/页面
+- `read`：读取笔记内容
+- `update`：追加、覆盖、章节替换
+- `delete/archive`：删除或归档
+- `search`：关键词搜索
+- `comment`：评论
+- `media`：上传图片/文件
+
+返回时统一口径：
+
+- 成功：说明平台、对象 ID/链接、关键变更内容
+- 失败：简要返回错误原因 + 下一步建议
+
+### OpenClaw「在线笔记」面板
+
+内置面板将用户意图与正文合并为同一字段：YAML 中 `payload.content` 即「操作与内容」全文；`target.raw` 可能由高级选项单独填写，也可能由前端从正文中抽取第一条可识别的文档链接或 ID。解析时请结合 `action`、`target.raw` 与 `payload.content` 整体理解用户意图。
+
+## 2.1 工具安装与执行硬规则（必须遵守）
+
+- 严禁输出或建议任何 `npm install`（包括 `npm install -g`）。
+- 涉及 CLI 依赖时，统一使用 `npx -y` 的一次性执行方式。
+- 优先调用本 skill 的 Python wrapper（例如 `run_note_crud.py`、`run_notionbot.py`、`run_wolai_note_crud.py`），由 wrapper 内部处理 `npx -y` 细节。
+- 仅当用户环境缺少 `npx` 时，才提示安装 Node.js；不要提示安装具体 npm 包。
+- 当用户要求“安装某 CLI”时，改为给出 `npx -y -p <package> <bin> ...` 的执行方案，而非本地全局安装。
+
+## 3. 平台执行层
+
+### A. Feishu Notes（主文档流）
+
+优先使用本 skill 内置封装脚本：
+
+```bash
+python3 {baseDir}/scripts/run_note_crud.py --op <create|read|update|delete|search> ...
+```
+
+```bash
+python3 {baseDir}/scripts/run_note_crud.py --op <media-insert|comment|section-update> ...
+```
+
+动作映射：
+
+- 新建：`--op create --title --markdown`
+- 读取：`--op read --doc`
+- 追加/覆盖：`--op update --doc --mode <append|overwrite|replace> --markdown`
+- 删除：`--op delete --doc`
+- 搜索：`--op search --query`
+- 图片/附件：`--op media-insert --doc --file --media-type`
+- 评论：`--op comment --doc --comment`
+- 章节编辑：`--op section-update --doc --section-title --section-mode --markdown`
+
+强约束：
+
+- 用户给的是飞书 Minutes 链接时，不要走普通 read/update 流，改走下方 Minutes 专用流。
+- 不先用网页抓取去读 Minutes 链接；先执行封装脚本。
+- 不要建议 `npm install -g @larksuite/cli` 或其他 npm 安装命令；若需直连 CLI，必须使用 `npx -y -p @larksuite/cli lark-cli ...`。
+- 飞书默认身份为 `bot`（云端优先）。除非用户明确要求并已完成本地 OAuth 登录，否则不要切回 `user`。
+
+#### 云端部署授权规范（Feishu）
+
+- 运行身份：默认 `bot`，不要依赖 `user` 扫码授权。
+- 凭证策略：使用可持久化的 `LARKSUITE_CLI_CONFIG_DIR`，避免容器重启后 token 丢失。
+- 执行策略：所有 CLI 调用必须可追溯到 `npx -y` 路径，禁止 `npm install`。
+- 故障处理：若报 token 缺失，优先检查配置目录挂载/注入是否成功，而不是提示用户在容器内扫码。
+- 仅在用户明确要求本地交互授权时，才给出：
+  `npx -y -p @larksuite/cli lark-cli config init --new`
+
+### B. Feishu Minutes -> Note（次能力）
+
+仅当输入是飞书妙记链接或 `minute_token` 时触发：
+
+```bash
+python3 {baseDir}/scripts/run_meeting_minutes.py "<minutes_url_or_token>"
+```
+
+结果处理：
+
+- `status=succeeded`：返回 `feishu_doc_url`
+- `status=partial`：说明“已提取但建文档失败”
+- `status=failed`：简要返回 `error_message`
+
+### C. Notion（vibe-notionbot）
+
+默认命令入口（本 skill 内置 wrapper）：
+
+```bash
+python3 {baseDir}/scripts/run_notionbot.py ...
+```
+
+认证前置：
+
+```bash
+python3 {baseDir}/scripts/run_notionbot.py auth status
+```
+
+核心动作：
+
+- 新建页面：`page create --parent <id> --title "<title>" [--markdown|--markdown-file]`
+- 读取页面：`page get <page_id>`
+- 更新页面属性/内容：`page update <page_id> ...`
+- 归档：`page archive <page_id>`
+- 搜索：`search "<query>"`
+- 评论：`comment create ...`
+- 批量：`batch --file ./operations.json '[]'`
+
+Notion 写入硬规则（必须执行）：
+
+- 任何“新增笔记 / 替换正文 / 追加完整笔记块”都先规范化为固定结构：
+  - `元数据`、`摘要`、`事实`、`洞察`、`决策`、`行动`、`问题`、`参考`
+- 缺失项统一用：`未知` / `无` / `待定`
+- 禁止把原始聊天碎片直接写入 Notion
+
+### D. wolai（OpenAPI）
+
+默认命令入口（本 skill 内置 wrapper）：
+
+```bash
+python3 {baseDir}/scripts/run_wolai_note_crud.py --op <create|read|read-children|update|delete|search> ...
+```
+
+认证前置（满足任一项即可）：
+
+- 方案 A：配置 `WOLAI_APP_TOKEN`
+- 方案 B：配置 `WOLAI_APP_ID` + `WOLAI_APP_SECRET`（脚本会自动调用 `POST /token` 获取 token）
+
+核心动作映射：
+
+- 新建块：`--op create --parent-id <id> --content "<text>"`
+- 读取块：`--op read --id <id>`
+- 读取子块：`--op read-children --id <id> [--cursor ... --limit ...]`
+- 更新块：`--op update --id <id> --content "<text>"`（优先 PATCH，失败回退 PUT）
+- 删除块：`--op delete --id <id>`
+- 轻量搜索：`--op search --parent-id <id> --query "<keyword>"`（在子块范围内过滤）
+
+执行约束：
+
+- 统一使用 `https://openapi.wolai.com/v1` 作为默认 base URL（可被 `WOLAI_OPENAPI_BASE_URL` 覆盖）
+- 用户明确要求 wolai 时，优先 wolai，不降级到其他平台
+- 返回原始错误信息中的 `message/error_code/status_code`，并补充下一步建议
+
+<!--
+### E. Evernote（OpenClaw）— 暂时屏蔽
+
+恢复时取消注释并同步 frontmatter/路由/第4节/示例/输出模板。
+
+优先使用 evernote 工具族：
+
+- `evernote.auth_status`
+- `evernote.list_notebooks`
+- `evernote.create_note`
+- `evernote.get_note`
+
+流程规则：
+
+1. 先 `auth_status`
+2. 未连接时提示 `openclaw evernote login`
+3. 缺少必要参数才追问，且每次只问最少字段
+4. 未指定笔记本时，默认写入后端默认笔记本
+-->
+
+## 4. 跨平台默认策略
+
+- 除非用户要求“同时写入多个平台”，否则只写一个目标平台。
+- 如果用户要求“同步到多个平台”，执行顺序：Feishu -> Notion -> wolai，并逐项汇报结果。
+- 任一平台失败，不阻塞其他平台继续执行；最后汇总成功/失败列表。
+- 不暴露 token、cookie、敏感 ID；输出中自动脱敏。
+
+## 5. 最小追问规则
+
+只在以下信息缺失时追问：
+
+- 目标平台不明确
+- 目标对象不明确（页面 ID / 文档链接）
+- 写入方式不明确（追加还是覆盖）
+
+其余信息优先用上下文推断，不要反复确认。
+
+## 6. 示例路由
+
+- “把这段会议纪要存到飞书” -> Feishu `create` 或 `update`
+- “读取这个链接并整理成飞书文档：`https://my.feishu.cn/minutes/...`” -> Minutes 专用流
+- “把这段内容按结构化笔记写入 Notion 数据库” -> Notion `page create --database`
+- “帮我搜索 wolai 里关于 OKR 的页面” -> wolai `search`
+
+## 7. 输出模板
+
+执行结束后使用统一格式回复：
+
+- 平台：`<feishu|notion|wolai>`
+- 动作：`<create|read|update|delete|search|comment|media>`
+- 结果：`成功/失败`
+- 对象：`<链接或ID>`
+- 摘要：`一句话说明关键结果`
+- 失败时补充：`建议下一步`

package/skills/notes-hub-assistant/src/scripts/_resolve_lark_cli.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+"""Resolve how to invoke Lark CLI.
+
+Cloud environments often have no admin permissions, so we prefer running the
+official CLI via `npx -y -p @larksuite/cli lark-cli ...`.
+
+This module returns a *command prefix* (list of argv items), not a path.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import List, Optional, Sequence
+
+
+def resolve_lark_cli_prefix(_base_dir: Path) -> list[str]:
+    """Return argv prefix to execute lark-cli.
+
+    Preferred:
+      npx -y -p @larksuite/cli lark-cli
+
+    Fallback (if npx missing):
+      lark-cli (on PATH)
+    """
+    npx = shutil.which("npx")
+    if npx:
+        return [npx, "-y", "-p", "@larksuite/cli", "lark-cli"]
+
+    lark_cli = shutil.which("lark-cli")
+    if lark_cli:
+        return [lark_cli]
+
+    raise FileNotFoundError(
+        "missing Lark CLI runner: npx or lark-cli not found on PATH. "
+        "expected to run via: npx -y -p @larksuite/cli lark-cli ..."
+    )
+
+
+def as_prefix(cli_bin: str, cli_prefix: Optional[Sequence[str]]) -> List[str]:
+    """Back-compat helper for orchestrators.
+
+    - If --lark-cli-prefix is provided, use it.
+    - Else, use --lark-cli-bin as a single executable path.
+    """
+    if cli_prefix:
+        return list(cli_prefix)
+    return [cli_bin]