飞书 → ima 单向增量同步

把用户明确授权的飞书知识库页面树或云盘文件夹，批量导入指定 ima 知识库。先预览、后写入；用本地状态账本避免重复上传，遇到同名、更新、源删除或写入结果不确定时暂停并要求人工确认。

本项目不是飞书、ima、腾讯或 OpenAI 官方产品。

先选适合你的版本

适合谁	版本	需要什么	怎么开始
没有程序员背景的 Win11 用户	Win11 免安装版 v0.2.0	Windows 11 x64、飞书与 ima 凭证；不需要另装 Python、Codex、DeepSeek 或豆包	直接下载 ZIP
已经使用 Codex 的用户	Codex Skill v0.1.0	macOS、Codex、Python 3.9 或更高版本	运行 python3 scripts/install_skill.py

Win11 小白版：4 步开始

1. 下载 飞书到ima同步-Win11免安装版-v0.2.0.zip。
2. 右键 ZIP，选择“全部解压”。不要直接在压缩包里运行。
3. 打开解压后的文件夹，双击 启动飞书到ima同步.cmd。
4. 在自动打开的本地页面中保存配置，依次运行“故障诊断”“只预览”；确认结果后，第一次只同步 5–10 篇。

发给朋友前，可以先把这份单文件说明书一起发过去：

• 飞书到ima同步-Win11朋友使用说明.html
• Win11 源码与内置页面

Win11 版把凭证保存在 Windows 凭据管理器中；普通配置、日志和同步状态不会写进程序 ZIP。

Codex Skill：安装与运行

在仓库目录运行：

python3 --version
python3 scripts/install_skill.py

重启 Codex 后，可以直接说：

使用飞书到 ima 同步 Skill，先预览，不要上传。

也可以用命令行完成首次配置：

python3 ~/.codex/skills/feishu-ima-sync/scripts/feishu_ima_sync.py configure
python3 ~/.codex/skills/feishu-ima-sync/scripts/feishu_ima_sync.py doctor
python3 ~/.codex/skills/feishu-ima-sync/scripts/feishu_ima_sync.py preview
python3 ~/.codex/skills/feishu-ima-sync/scripts/feishu_ima_sync.py sync --yes --limit 10

更详细的权限与排错步骤见：

• Codex Skill 使用说明
• 小白操作手册
• 给朋友看的说明
• PDF 说明书

能做什么

• 扫描飞书 Wiki 页面树、整个知识库或云盘文件夹。
• 导出飞书在线文档、Sheet、Bitable，并下载常见普通文件。
• 上传到指定 ima 知识库和文件夹。
• 用 SQLite 状态账本跳过已经成功同步且没有变化的资料。
• 在写入前执行 ima 同名检查。
• 对修改、源删除、弱修改时间和不确定写入结果采取暂停确认策略。
• 生成预览与同步报告，便于逐项核对。

安全默认值

• preview 不写入 ima；正式 sync 必须明确确认。
• 飞书仍是主版本，本工具不会修改或删除飞书原文件。
• 飞书源删除不会自动删除 ima 副本。
• ima 同名检查命中时停止上传。
• Win11 凭证存入 Windows 凭据管理器；macOS 凭证优先存入钥匙串。
• Win11 管理页面仅监听 127.0.0.1 随机端口，并使用随机会话令牌。
• ima 密钥只发往 ima.qq.com；COS 临时凭证只发往 *.myqcloud.com。
• 不要在 Issue、截图或日志中提交 App Secret、ima API Key 或访问令牌。

当前状态

发行版	当前版本	已验证	仍需注意
Codex Skill	0.1.0	核心自动化测试 27 项通过	需要自行准备飞书应用与 ima OpenAPI 凭证
Win11 免安装版	0.2.0-win11-portable	核心测试 35 项、GUI/安全/状态测试 11 项通过；ZIP 完整性、UTF-8 文件名及官方 Python 运行时已核对	目前仍是候选发布版，尚未在真实 Win11 机器完成首次端到端验收；建议先预览并只同步 5–10 篇

重要边界

这不是双向同步。当前 ima OpenAPI 没有 Replace/Delete，因此已上传资料的更新和删除需要人工确认。飞书若没有返回可靠修改时间，条目会进入人工抽检状态，不会被静默判定为未变化。

许可与第三方软件

应用自身代码目前未声明开源许可证。公开可查看和下载，不等于自动授予修改或再次分发权；如需二次发布或商业集成，请先取得项目所有者授权。

Win11 免安装版内含 Python Software Foundation 官方 Windows x64 嵌入式运行时。完整 Python 许可证随包保存在 runtime/LICENSE.txt，来源和版本见 第三方软件说明。