Soia Cwork Feishu Doc Git Sync

soia-cwork-feishu-doc-git-sync

把飞书知识库的内容镜像到一个本地 Markdown 知识库。默认方向是 Feishu → local/Git/Obsidian/VitePress；本技能不默认向飞书写入，双向同步必须先建立文档归属、冲突策略和写权限。

客户可读说明

这个技能可以做什么

客户如何使用

1. 确认 soia-cwork-feishu-cli 已完成飞书应用凭证登录，并且机器人可以读取目标知识空间。
2. 在本机私有配置中填写知识空间 ID、输出目录和来源 URL 模板；不要把 App Secret、token 或企业私有路径提交到公开技能仓库。
3. 首次使用先执行 dry-run，核对空间、节点数量和目标目录。
4. 先用单节点隔离试点核对表格、资源和样式快照；--pilot-node-token 只写明确选择的节点到单独试点目录，不会给空目录补齐其他节点占位文件。
5. 执行镜像同步。默认只写本地文件和同步元数据，不修改飞书内容，也不删除本地历史文件。
6. 如需排除完整目录树，在私有配置设置 sync.exclude_subtrees.enabled: true，并在 roots 中优先填写稳定 node_token；首次清理既有 Markdown、完整导出和已下载附件时显式运行一次 --rebuild-tree，本地补录目录永不受影响。
7. 同步写入后会自动校验 manifest、文件存在性、frontmatter、失败占位、侧边栏覆盖范围、排除子树残留、资源引用、未归档的嵌入式 Sheet、未归档的 Sheet 内嵌 Base、all_docx 模式下尚未完成 XML 语义扫描的历史文档，以及 all_nodes 模式下仍未生成真实表格的独立 Sheet；发现 failed/stale 或语义缺口时返回非零结果，不能把空白占位或局部内容当作完整成功。
8. 如需检查表格导出，先做 drive +inspect/帮助/schema 探查；能力探查不等于授权导出。
9. 只有客户明确确认导出范围、格式、文件数和本地目录后，才调用 drive +export 或 drive +export-download。
10. 如需镜像 Sheet，先在私有配置明确范围：全部独立 Sheet 使用 sync.sheets.enabled: true 与 all_nodes: true 自动发现每个网格子表，或在 selections 中逐项指定 node_token、稳定 sheet_id 和有界 A1 range；两种方式都必须设置行列、单元格和返回字符上限。响应达到 max_chars 时必须按 actual_range 下一行续读，不能把截断当成整表失败。混合工作簿还需显式设置 include_bitable_tabs: true 与记录上限，随后把 Base 子表路由到多维表格读取。文档内嵌 Sheet 启用 sync.embedded_sheets.enabled 后，还须选择 all_docx: true 或 node_tokens。按需开启 sync.sheets.preserve 保存公式、样式、批注、布局和图表等元数据。未启用时必须显示并校验语义缺口，不得静默删除 <sheet> 或把独立 Sheet 占位当成完整归档。
11. 如需镜像多维表格，逐项指定 sync.bitables.selections 的 node_token、table_id 和 max_records，再开启 sync.bitables.enabled 或传入 --sync-bitables；附件二进制还需要单独开启 download_attachments，仪表盘/报表元数据需要 include_dashboards。
12. 只有用户明确确认来源、格式、文件数、输出目录和 Git 策略后，才能执行完整初始化：Sheet 设置 sync.sheets.workbook_exports.enabled=true 与 all_nodes=true，Base 设置 sync.bitables.base_exports.enabled=true 与 all_nodes=true，Wiki 文件设置 sync.files.downloads.enabled=true 与 all_nodes=true。每项必须配置 batch_size，重复执行至 deferred 为零。
13. 如需离线资源、文档间本地跳转、子页面导航或变更台账，先在私有配置中逐项启用 download_assets、localize_internal_links、render_sub_page_navigation、change_ledger；它们默认关闭以兼容已有镜像。
14. 批量初始化前先以一份代表性范围试点，确认资源数量、失败类别和本地渲染；同步完成后再运行 Git diff、站点构建和必要的人工抽查。

推荐命令：

python3 scripts/sync_feishu_wiki.py --config <private-config.yml> --dry-run
# 试点只写所选节点到独立目录；仍会核验它是否属于当前知识库
python3 scripts/sync_feishu_wiki.py --config <private-config.yml> --output-dir <pilot-output-dir> \
  --pilot-node-token <node_token> --incremental
python3 scripts/sync_feishu_wiki.py --config <private-config.yml> --incremental
# 没有事件订阅时，按 wiki +node-get 的远端更新时间判断正文是否变化
python3 scripts/sync_feishu_wiki.py --config <private-config.yml> --incremental --probe-remote-metadata
# 复用已完整正文，优先补独立 Sheet stub、未扫描的内嵌 Sheet 文档，再退避重试失败项
python3 scripts/sync_feishu_wiki.py --config <private-config.yml> --retry-failed
# 事件适配器已经拿到变动 ID 时，只拉对应节点；可重复传入多个 ID
python3 scripts/sync_feishu_wiki.py --config <private-config.yml> --incremental \
  --changed-node-token <node_token> --changed-obj-token <obj_token>
# 只修复指定节点的本地格式，复用 manifest 中的其他文档，不重试历史失败项
python3 scripts/sync_feishu_wiki.py --config <private-config.yml> --incremental \
  --rebuild-tree --rebuild-tree-only --only-node-token <node_token> --skip-assets
# 官方 webhook/长连接适配器写入 JSON/NDJSON 后，按事件目标增量拉取
python3 scripts/sync_feishu_wiki.py --config <private-config.yml> --incremental \
  --event-file <events.ndjson>
# 仅在确认历史生成目录曾经扁平化时执行一次结构迁移
python3 scripts/sync_feishu_wiki.py --config <private-config.yml> --retry-failed --rebuild-tree
# 大型知识库遇到限流时分批补偿；重复执行直到 --validate-only 通过
python3 scripts/sync_feishu_wiki.py --config <private-config.yml> \
  --retry-failed --retry-batch-size 100 --skip-assets
# 如果只需要修复本地目录层级、暂时不请求飞书
python3 scripts/sync_feishu_wiki.py --config <private-config.yml> --rebuild-tree --rebuild-tree-only
# 从飞书刷新最新目录层级和兄弟节点顺序，但复用现有本地正文
python3 scripts/sync_feishu_wiki.py --config <private-config.yml> --incremental \
  --rebuild-tree --refresh-tree-only
# 应用私有配置中的整棵子树排除，并清理该子树既有 Markdown、完整导出和已下载附件
python3 scripts/sync_feishu_wiki.py --config <private-config.yml> --incremental \
  --rebuild-tree --refresh-tree-only --skip-assets
# 下载图片到本地镜像并把正文中的远程 URL 改成相对路径
python3 scripts/sync_feishu_wiki.py --config <private-config.yml> --incremental \
  --download-assets
# 将私有配置中明确选择的 Sheet 范围渲染为 Markdown 表格
python3 scripts/sync_feishu_wiki.py --config <private-config.yml> --incremental \
  --sync-sheets
# 将已授权文档中的嵌入式 Sheet 追加为有界 Markdown 表格快照
python3 scripts/sync_feishu_wiki.py --config <private-config.yml> --incremental \
  --sync-embedded-sheets
# 将私有配置中明确选择的多维表格镜像为 Markdown 与 JSON 快照
python3 scripts/sync_feishu_wiki.py --config <private-config.yml> --incremental \
  --sync-bitables
# 完整初始化仍使用同一同步命令；私有配置中 workbook_exports/base_exports/files.downloads
# 的 enabled 与 all_nodes 必须都为 true，并按 batch_size 分批重复执行
python3 scripts/sync_feishu_wiki.py --config <private-config.yml> --incremental \
  --sync-sheets --sync-bitables
# 只校验最近一次同步生成的本地镜像，不访问飞书
python3 scripts/sync_feishu_wiki.py --config <private-config.yml> --validate-only

依赖与安装

装整个域（Claude Code 与 Codex 共用同一份域插件）：

claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-cwork-office@soia

只装这一个技能：

npx skills add soia-team/soia-open-cwork-office-skills -g -a '*' -s soia-cwork-feishu-doc-git-sync -y

WorkBuddy 的装载单位是角色化专家而不是插件，npx skills add -a '*' 覆盖不到它，需要单独安装，见 docs/install/workbuddy.md。

三种工作模式

• mirror：默认模式。知识库是来源，本地生成的 10_knowledge-base/ 不应手工编辑。
• local：只维护本地 20_本地补录/，不会被镜像同步覆盖，也不会自动上传飞书。
• managed：未来用于明确指定的双向托管文档。必须逐文档确认写入权限、冲突规则和发布动作；当前脚本只提供只读镜像基础，不把它伪装成已经完成的双向同步。

ID 增量同步与事件推送

• node_token 是同步主键，obj_token 是正文读取和事件映射的对象键；标题变化、移动和重名都不应改变这两个 ID。
• sync.exclude_subtrees 必须在私有配置中显式启用；优先按稳定 node_token 排除，exact_title 会排除所有精确同名根节点。同步器只在根节点的父级列表中识别它，不再枚举后代，并从正文、Sheet、Base、图片、附件、重试、活跃 manifest 和侧边栏中同时排除整棵子树。
• 已生成的排除子树内容不会被普通增量同步静默删除；用户明确要求清理后运行 --rebuild-tree，同步器把已知成员记录为 excluded 而不是误报为远端删除，并清理、校验对应 Markdown、目录、_exports/ 完整导出和 _assets/ 已下载附件均不残留；20_本地补录/ 永不删除。
• --only-node-token 是单文档修复开关；与 --rebuild-tree-only 一起使用时只从已有 manifest 定位节点，不重新遍历飞书树，也不会因为其他节点历史失败而重试它们。
• 首次同步建立完整基线，记录 obj_edit_time/remote_updated_at 和 docs +fetch 返回的 revision_id。
• 后续 --incremental 仍会先按 parent_node_token 重建树，但只读取新增、失败、事件命中或远端编辑时间变化的文档正文；未变化节点复用本地 Markdown。
• 兄弟节点顺序直接保留 wiki +node-list 返回的飞书顺序，不按标题重新排序；因此 VitePress/Obsidian 目录应与飞书知识库的手工排序一致。
• 没有事件目标时，默认用 wiki +node-get 做元数据探测；这会产生较多轻量元数据请求，但避免重复下载正文。大型空间可改用官方事件订阅并传 --event-file。
• 事件只提供“哪个对象可能变了”的提示，不能替代 Wiki 树对账；创建、删除、标题变化和未识别事件仍需重新对账节点树。
• 官方事件订阅、权限和 drive.file.* 覆盖边界见 references/events.yml。当前 lark-cli event list 未暴露云文档 drive.file.* 事件，因此本脚本不声称已经在 CLI 内常驻监听；外部长连接/webhook 适配器可以把 JSON/NDJSON 交给 --event-file。

依赖与安装

安装本技能及其同仓依赖：

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-cwork-office@soia

只要这一个技能时，可用 npx 路线。注意技能会落进共享真源 ~/.agents/skills；若同时装了插件，同一技能会出现两份索引且各自漂移，建议二选一：

npx skills add soia-team/soia-open-cwork-office-skills -g -a '*' -s soia-cwork-feishu-doc-git-sync -y

私有配置默认位置：

~/.config/soia-skills/soia-cwork-feishu-doc-git-sync/config.yml

也可以使用 SOIA_CWORK_FEISHU_DOC_GIT_SYNC_CONFIG_FILE 指定配置文件。参考 assets/config.example.yml。

最小配置示例：

version: 1
provider:
  cli: lark-cli
  profile: <configured-cli-profile>
  brand: feishu
  identity: bot
space:
  id: <wiki-space-id>
  source_url_template: https://<tenant>.feishu.cn/wiki/{node_token}
paths:
  output_dir: <git-repository>/docs/feishu-knowledge
  generated_dir: 10_<knowledge-base-name>
sync:
  mode: mirror
  prune: false

权限建议：首轮只申请知识库、文档与 Sheet 只读权限。图片和附件下载是可选增强，涉及云盘/导出权限时单独申请；双向写入权限永不作为默认权限。

同步规则

• 只使用 --as bot 的应用身份读取，默认不需要用户身份 token。
• 通过 node token 遍历知识空间，使用文档 token 读取 docx 内容。
• paths.generated_dir 必须使用目标知识库的真实名称或稳定英文名称；例如 10_后端技术支持库，不要再嵌套一个泛化的 feishu-knowledge 目录。
• 如果已有输出目录中只有一个 10_* 生成目录而配置未填写 paths.generated_dir，技能会复用它；如果发现多个候选目录，会停止并要求先明确配置，避免自动制造重复目录。
• 每个生成 Markdown 写入来源 URL、space ID、node token、object token、父节点和内容 hash。
• 使用 sync-state.json 保留 node token 到本地路径的映射；标题变化时尽量保持稳定路径，树位置由最新 parent_node_token 重新计算。
• manifest.json 和 sync-state.json 记录 obj_edit_time、remote_updated_at、revision_id，用于增量选择和审计。
• 本地单个路径组件最多 48 个字符；超长标题会保留完整标题在 frontmatter/侧边栏，并在文件夹或文件名中追加 node ID 短后缀，避免 Obsidian、macOS 和 VitePress/Rollup 路径过长。
• 同步器会把飞书导出的自定义 figure/source/grid/callout、媒体 token 和 XML 片段转换为可被 Markdown/VitePress 解析的形式；这只改变本地渲染，不写回飞书。
• 飞书文档引用会按 node_token 优先、obj_token 兜底解析为可点击的飞书 Wiki 链接；用户引用会保留为 @显示名。静态 Markdown 不复制飞书的悬浮卡片和成员头像交互，但不再错误降级为代码样式。
• 有子节点的飞书节点必须生成一个同名目录，并把正文放在目录内的同名 index Markdown：父目录/节点名/节点名.md；叶子节点才直接生成 节点名.md。不要生成同级的“同名文件 + 同名文件夹”。
• 如果飞书本身存在同名叶子与可展开节点、父子同名或同级重复可展开节点，目录/文件会追加稳定的 node ID 短后缀；这是为了避免本地文件系统发生同级冲突，manifest 仍以 node_token 区分真实节点。
• --retry-failed 会复用已有完整正文，并把失败节点、独立 Sheet stub、未完成 XML 语义扫描的历史文档加入补偿队列；适合遇到飞书接口限流或启用新的 Sheet 策略后继续补齐。
• 历史镜像中如果保留“当前同步器只读取文档正文”一类旧占位，即使飞书节点后来从 Sheet 变成 Docx、manifest 状态仍是 ok，验收也会判定失败，并在 --retry-failed 队列中最高优先级重拉；不能把类型漂移后的旧占位当成成功正文。
• --retry-batch-size N 仅与 --retry-failed 配合使用，每次最多补偿 N 个失败或语义缺口节点；大型空间应重复执行，并以 --validate-only 的 failed_records=0、unmirrored_sheet_nodes=0、unscanned_embedded_sheet_documents=0 为结束条件。
• --retry-failed 使用上一次 manifest 作为节点清单，不再先对全量文档做元数据探测；启用 Sheet 全量策略时，它会优先补独立 Sheet stub 与缺少语义扫描标记的历史 Docx，再重试普通失败项，并继续受全局节流保护。大型空间配合 --retry-batch-size 重复执行，直到 unmirrored_sheet_nodes 与 unscanned_embedded_sheet_documents 都为 0。
• 同一输出目录同时只允许一个同步进程；如果上一轮仍在退出或用户重复启动，后续进程会停止并报告，不会并发覆盖 manifest。
• 全局请求节流和指数退避会跨同步 worker 生效；sync.min_request_interval_seconds 默认 0.5 秒，避免大知识库并发触发 99991400 限流。
• 正文读取失败但本地已有旧正文时，节点会标记为 stale 并保留旧正文；下一次增量同步会继续重试，校验不会将其视为成功。
• 每次非 dry-run 同步结束都会运行本地验收；--validate-only 可单独复核最近一次结果。验收失败时退出码为 2，并在 manifest 的 validation 节点保留机器可读摘要。
• prune: false 时不删除已消失节点对应的本地文件；节点会在 manifest 中标记为 deleted，避免一次权限或网络异常造成数据丢失。
• 20_本地补录/ 与 90_同步元数据/ 不会被知识库同步覆盖。
• --rebuild-tree 只处理 paths.generated_dir 内由同步器生成的旧扁平文件与已排除节点的已知资源，不触碰 20_本地补录/。
• --rebuild-tree-only 仅复用已有 manifest 和生成文件做目录迁移，不发起飞书正文请求；如果同时启用资源本地化，仍可能只为刷新过期媒体 URL 读取含资源的文档。
• --refresh-tree-only 会重新读取飞书节点树和兄弟顺序，按最新 parent_node_token 重建本地目录和侧边栏，但复用已有本地正文；启用资源本地化时，会额外刷新仍含未本地化资源的文档；必须与 --rebuild-tree 一起使用。
• manifest.json/sync-state.json 的 tree_order: feishu_node_list 表示目录顺序来源于飞书节点列表，不是标题排序。
• 图片默认保留远程 URL；设置 sync.download_assets: true 或传入 --download-assets 后，技能会把正文中的远程图片及 <source token="..."> 媒体块下载到 paths.generated_dir/_assets/，并把 Markdown/HTML 引用改写为相对路径。已下载的飞书附件卡片必须进一步改写为标准 Markdown 本地链接；若该链接被单独的 <p> 包裹，必须同时移除该 HTML 容器，确保 Obsidian 和 VitePress 都能点击打开。未下载的卡片仍保留原远程引用并报告失败。
• 下载资源时，优先按飞书媒体 token 去重；同一附件或图片即使带有不同的短期签名 URL，也只保留一份本地资源。无 token 的资源仍按 URL 内容寻址。
• sync.localize_internal_links: true 时，已同步的 Wiki/文档引用会改为相对本地 Markdown 链接；sync.render_sub_page_navigation: true 时，飞书导出的 <sub-page-list> 会改为本地 Markdown 子页面导航。两项均默认关闭，不影响已有外链行为。
• sync.change_ledger: true 时，会在同步元数据下按运行生成新增、修改、移动和远端删除的变更台账；修改项只保留受 change_ledger_max_diff_lines 限制的 diff，不复制文档全文，也不改变生成镜像或本地补录目录。
• sheet 默认只生成元数据 stub。经用户明确授权全库有界快照后，设置 sync.sheets.enabled: true 与 all_nodes: true，同步器会用 sheets +workbook-info 自动发现每个独立 Sheet 的网格子表，再按 max_rows、max_columns、max_cells、max_chars 上限调用 sheets +csv-get；响应截断时按 actual_range 分行续读。也可继续用 selections 精确声明单个范围。混合工作簿中的 Base 子表只有在 include_bitable_tabs: true 时才按 max_bitable_records 有界读取，否则节点失败，不能静默跳过；若 Base 权限不足，已读出的普通 Sheet 仍落盘，但节点保持 failed 并写入明确缺口标记。all_nodes 验收会拒绝任何 metadata_stub、缺少真实表格标记的 Sheet 节点或未归档的 Base 子表。完整契约见 references/sheet-mirroring.yml。
• 飞书 Markdown 可能只返回 <sheet> 引用而不返回任何单元格。同步器不得删除该引用后仍报告完整成功：未授权下钻时保留可见缺口并使验收失败；仅当 sync.embedded_sheets.enabled 且明确选择 all_docx: true 或 node_tokens 时，才读取文档 XML 并在配置上限内生成“嵌入式表格”快照。首次启用会补扫旧文档；快照不会伪装成交互式原表。完整范围契约见 references/sheet-mirroring.yml。
• sync.sheets.preserve.enabled: true 会在同一选定范围另存单元格值、公式、样式、批注，以及工作表布局、图表和浮动图片元数据的 JSON 快照；可额外开启透视、筛选、条件格式和迷你图元数据。它不把图表或图片伪装成原生 Markdown。完整工作簿需在用户明确批准后同时设置 sync.sheets.workbook_exports.enabled: true 和 all_nodes: true，同步器会用 drive +export 分批生成 .xlsx 并在 Sheet 索引中链接。
• 异步 Sheet 导出未在首轮轮询完成时，会把导出任务票据保存在生成目录的私有快照中；后续批次只轮询同一任务，并在就绪后使用 drive +export-download 下载，不会反复创建相同工作簿导出任务。manifest.stats.sheet_workbooks_pending 表示仍在飞书端处理的数量。
• 图片/附件本地化是显式 opt-in 的本地数据下载；不能因为用户只要求“检查图片”就下载全部素材。持久化配置中的 sync.download_assets: true 只能视为用户此前对该资源范围的明确授权，不得扩展为表格或多维表格导出授权。若先执行 Sheet/Base/文件的结构初始化并使用 --skip-assets 避免输出锁冲突，必须在初始化结束后单独执行资源本地化批次；--skip-assets 不会把图片或附件标记为已下载。
• bitable 与未授权的 sheet 默认只生成元数据 stub，不读取表内数据；已启用 sync.sheets.all_nodes 的独立 Sheet 不允许继续保留 stub。设置 sync.bitables.enabled: true 后，必须逐项声明 node_token、table_id 与 max_records；同步器以 base +field-list、base +record-list 和可选的 base +view-list/base +dashboard-list/base +dashboard-block-list 生成 Markdown 与 JSON 快照。sync.bitables.download_attachments: true 是独立的二进制下载授权，使用 base +record-download-attachment 并只处理已选表的已读记录附件。完整 Base 导出仍须在用户明确批准后同时设置 sync.bitables.base_exports.enabled: true 和 all_nodes: true，同步器用 drive +export 分批生成 .base。
• Wiki file 节点默认只生成元数据 stub；用户明确确认完整初始化后，同时设置 sync.files.downloads.enabled: true 与 all_nodes: true，同步器才会分批调用 drive +download。文件以原始二进制保存，不会执行、挂载、解压或解析 ZIP、DMG、EXE 等格式。
• 飞书图片 URL 可能很快过期。启用本地化并使用 --refresh-asset-urls 时，会先刷新关联文档的 URL 再下载，不会无条件重拉所有正文；下载后统一写为转义 alt 的本地 HTML <img>，并按文件二进制识别 PNG/JPEG/GIF/WebP/SVG、修正错误缓存后缀。
• 事件目标、--changed-*-token、--only-node-token 或隔离试点只处理本轮重读文档的资源，不会把整库历史资源重新加入下载队列；完整资源回填则不传目标并按 asset_batch_size 分批执行。
• 图片下载使用 URL 内容寻址文件名，重复同步会复用已有资源；Markdown 的普通 URL 与 (<https://…>) 尖括号 URL 都会进入同一下载队列。可通过 asset_workers、asset_timeout_seconds、asset_download_attempts、max_asset_bytes 限制并发、超时、媒体重试和单文件大小；单资源默认上限为 50 MiB，可在私有配置中按已确认的下载范围调低或调高。携带飞书媒体 token 的附件遇到短暂或未归类 CLI 失败时会在上限内重试；明确的权限不足、资源不存在或 asset_too_large 不会盲目重试。大型存量镜像可设置正整数 asset_batch_size：每次只请求该数量的尚未落盘资源，已下载资源仍会被本地化改写；asset_refreshed_batch_size 可限制同一批已刷新文档的新链接下载量。重复执行并以 --validate-only 确认完成。manifest 会报告本轮 assets_deferred。下载失败只保留原 URL，并在 manifest 的 assets_failed 计数中报告，不把鉴权 URL 写入日志或清单。
• <source token="..."> 或无 URL 的 <img token="..."> 会调用官方 docs +media-download；远程 URL 不可直接读取时，需要按权限清单补充 docs:document.media:download 或 drive:file:download，并在私有配置中启用本地资源下载。没有下载权限时不得猜测本地资源已经完整。

安全规则

• 不在公开 skill、Obsidian vault、Markdown、Git 提交、终端输出或最终回复中写入 App Secret、access token、cookie。
• 终端日志、进度回执和最终回复不得输出本地绝对路径、具体本地文件名、操作系统用户名、用户名、密码、App Secret、access token 或私有下载 URL；统一使用脱敏占位符，只报告状态、数量和错误类别。详见 references/output-redaction.yml。
• 不默认调用飞书创建、更新、删除接口。
• drive +export、drive +export-download、docs +media-download 和附件下载均属于数据导出/下载动作；用户说“看下能否导出”时只做 inspect、help、schema 或 dry-run，不得直接创建本地文件。
• Sheet 与 Base 值镜像都属于敏感数据落盘：只有用户明确确认需要将选定范围/表同步到本地工作区，并在私有配置中写入有界 sync.sheets.selections 或受限 sync.bitables.selections 后才可启用；该确认不授权任何工作簿导出、未选附件下载或自动 Git 提交。
• 真实导出前必须明确回执来源、类型、格式、预计文件数、输出目录和 Git 追踪策略；“检查能力”不等于“授权导出”。
• 导出文件默认放在临时目录或用户明确指定的目录；只有经用户明确确认的完整镜像初始化才能写入生成目录下的 _exports/ 或 _assets/，并且不得自动提交 Git、自动推送远程或写回飞书。
• bot 无权访问的个人云盘或私有资源必须报告为不可见，不得切换 user OAuth 代为读取。
• 不默认覆盖本地补录、删除历史文件或推送远程 Git；这些属于需要明确确认的写入/发布动作。
• 执行前检查目标仓库、当前分支和远程地址；发现与预期不符时停止并报告。

私密信息与中间数据

• 把排除节点 ID、知识空间 ID、凭据别名和本地输出位置只写入技能私有配置，不提交公共仓库。
• 把 active/excluded 节点清单、同步状态、侧边栏和变更台账保存在用户指定镜像的同步元数据目录；排除记录只用于证明未抓取范围，不包含正文。
• 把临时下载和接口中间结果交给系统临时目录；只把用户授权的 Markdown、表格快照和资源文件写入交付目录。

日志与完成回执

终端和最终回复至少报告：

• started：空间、身份、配置来源和目标目录（不打印秘密）。
• processed：节点、文档、跳过和失败数量。
• created/updated：生成或更新的 Markdown、manifest、sidebar 数量。
• skipped/failed：失败节点、原因和是否可重试。
• verification：Git diff、VitePress build、抽样文档和源链接检查结果。
• next_step：是否需要补权限、确认 Git push 或规划双向同步。
• 文件变化只报告数量和类别，不列本地路径或文件名；身份只报告 bot identity / user identity 等非敏感状态。

Resources

• 权限与权限申请分层：references/permissions.yml
• 飞书 CLI 命令与权限申请流程：同仓库 soia-cwork-feishu-cli/references/cli-workflows.md 和 soia-cwork-feishu-cli/references/permissions.md。
• 事件订阅与增量目标：references/events.yml
• 同步策略：references/sync-policy.yml
• 文档格式转换：references/block-mapping.yml
• Sheet 范围镜像：references/sheet-mirroring.yml
• 富资源镜像能力与边界：references/rich-resource-mirroring.yml
• 表格/多维表格导出安全策略：references/export-policy.yml
• 日志与回复脱敏策略：references/output-redaction.yml
• Git 与 VitePress 接入：references/git-vitepress.yml
• 私有配置模板：assets/config.example.yml

Validation

python3 scripts/sync_feishu_wiki.py --help
python3 scripts/sync_feishu_wiki.py --config <private-config.yml> --dry-run
python3 scripts/sync_feishu_wiki.py --config <private-config.yml> --validate-only
git diff --check

Forward test

Before a real sync, run a dry-run or a small authorized representative scope and verify the tree, stable node-ID mapping, ordering, incremental selection, asset references, and failure receipt. After every write, require the built-in validation gate to pass; a zero exit code alone is not evidence that the mirror is complete.