larksync-feishu-local-cache

# LarkSync Feishu Local Cache Skill

参考：
- `OPENCLAW_AGENT_GUIDE.md`：面向 OpenClaw 代理的自动执行 runbook（首次授权分支、无人值守分支、失败分支）

## English Overview
- Purpose: sync Feishu documents to local markdown/files and let OpenClaw read local cache first.
- Value: fewer Feishu API calls, lower token consumption, and more stable retrieval latency.
- Default mode: `download_only` with low-frequency schedule (daily by default).
- Advanced mode: `bidirectional` and `upload_only` are supported when explicitly requested.

### Typical intents (EN)
- "Set up a daily 01:00 sync from this Feishu folder to local cache."
- "Check my current LarkSync auth and task status first."
- "Switch this task to bidirectional sync and explain the risk."

## 价值主张
- 让 OpenClaw 的高频文档问答“走本地、不走云端接口”。
- 把 API 调用从“每次问答触发”变成“低频定时同步触发”。
- 在不改用户飞书使用习惯的前提下，直接获得更稳、更省的文档检索链路。

## 适用目标
- 目标：减少 OpenClaw 直接调用飞书 API 的频率，优先读取本地 Markdown/附件。
- 默认策略：`download_only` + 每日低频同步（可自定义时间与周期）。
- 进阶策略：支持 `bidirectional`（双向）和 `upload_only`，但仅在用户明确要求时启用。
- Windows 侧建议直接使用 LarkSync 安装包版运行服务，不需要源码构建。

## 触发意图（示例）
- “把飞书生产测试文件夹每天 01:00 同步到本地，给我配置好。”
- “先检查 LarkSync 当前授权和同步任务状态。”
- “我想把这个目录切成双向同步，先评估风险再改。”

## 默认执行流程
1. 检查本地 LarkSync 服务与授权状态。
2. 配置低频下载策略（默认每天一次）。
3. 创建同步任务（默认 `download_only`）。
4. 按需触发一次立即同步，建立本地缓存基线。
5. 后续回答用户文档问题时，优先读取本地同步目录。

## 命令入口
使用以下脚本作为统一入口（返回 JSON，便于自动化编排）：

```bash
python integrations/openclaw/skills/larksync_feishu_local_cache/scripts/larksync_skill_helper.py check
python integrations/openclaw/skills/larksync_feishu_local_cache/scripts/larksync_skill_helper.py configure-download --download-value 1 --download-unit days --downl...

# LarkSync Feishu Local Cache Skill

把飞书文档“变成本地知识库”的 OpenClaw 集成技能。  
核心目标：让 OpenClaw **优先读本地同步副本**，而不是每次都打飞书 API，从源头降低 token 消耗与限流风险。

## English Overview
An OpenClaw integration that turns Feishu docs into a local knowledge cache.  
Core goal: make OpenClaw read local synced files first instead of calling Feishu API on every query.

- Lower cost: shift frequent Q&A reads from Feishu API to local filesystem.
- Better stability: local cache still works when cloud API is throttled.
- Faster retrieval: local-first access for daily queries.
- Safe by default: `download_only` mode, with optional advanced bidirectional mode.

## 为什么值得安装
- 省额度：把高频问答读取从飞书 API 转到本地文件系统。
- 更稳：飞书偶发限流/网络波动时，本地副本仍可读。
- 更快：日常检索直接命中本地目录，不必每次远程拉取。
- 可扩展：默认低风险 `download_only`，需要时可升级到双向同步。

## 一句话效果（Before / After）
- Before：问一个文档问题 -> 调一次飞书 API -> 累积额度消耗。
- After：每天低频同步一次 -> 多次问答都走本地读取 -> API 用量大幅下降。

## 适合谁
- 已经在飞书沉淀大量文档、同时用 OpenClaw 做日常知识检索的人。
- 想把飞书纳入 NAS/本地知识管理体系的人。
- 关注“可持续调用成本”的个人或团队。

## 默认推荐模式
- 同步模式：`download_only`
- 下载频率：每日 1 次（可配置时间）
- 读取策略：OpenClaw 优先本地目录检索与引用

## 目录结构
```text
integrations/openclaw/skills/larksync_feishu_local_cache/
  SKILL.md
  OPENCLAW_AGENT_GUIDE.md
  README.md
  scripts/
    larksync_skill_helper.py
```

## Agent Runbook
- OpenClaw 代理专用执行说明：[`OPENCLAW_AGENT_GUIDE.md`](./OPENCLAW_AGENT_GUIDE.md)

## 依赖前提
1. Windows 侧已安装并运行 LarkSync（安装包版即可，不需要拉源码构建；后端可访问 `http://localhost:8000`）。
2. 已在 LarkSync 中完成飞书 OAuth 授权。
3. 出于安全考虑，helper 默认只允许连接本机 `localhost/127.0.0.1/::1`。

## 30 秒快速上手
```bash
# 1) 环境检查
python integrations/openclaw/skills/larksync_feishu_local_cache/scripts/larksync_skill...