来源：notes/projects/feishu_base_sync/03_个人助理飞书同步SOP.md

个人助理飞书多维表格同步 SOP

1. 目标

把 codex_personal_assistant 本地个人助理目录中的任务、每日记录、阅读书籍、Markdown 文档资产和知识索引同步到飞书多维表格，方便在飞书端查看、检索和继续维护。

本 SOP 基于 2026-06-04 的实际执行记录沉淀。

2. 工作目录

cd /home/admin/code/cc-connect-work-space/codex_personal_assistant

3. 前置条件

3.1 lark-cli 可用

command -v lark-cli
lark-cli --version

3.2 用户授权有效

lark-cli auth status

需要看到 user identity 为 ready，并且 scope 包含：

• base:app:create
• base:table:create
• base:field:create
• base:record:create
• base:record:update
• base:record:read
• wiki:node:create
• drive:file:upload

如果 user token 过期，重新发起授权：

lark-cli auth login --no-wait --json --domain base,wiki,docs,drive,markdown

把输出的 verification_url 发给用户授权。用户授权完成后执行：

lark-cli auth login --device-code '<device_code>'

4. 创建正式 Base

lark-cli base +base-create \
  --as user \
  --name 'Codex Personal Assistant' \
  --time-zone Asia/Shanghai \
  --format json

本次实际创建结果：

• Base 名称：Codex Personal Assistant
• Base URL：https://my.feishu.cn/base/
• Base Token：<base_token>

注意：飞书新建 Base 会自动带一个默认空表，名为 数据表。本次暂时保留。

5. 创建数据表

本次创建了 5 张表：

创建表命令示例：

lark-cli base +table-create \
  --as user \
  --base-token '<base_token>' \
  --name '每日记录' \
  --fields '[{"name":"日期","type":"text"},{"name":"标题","type":"text"}]' \
  --format json

6. 字段设计注意事项

6.1 普通文本字段

{"name":"标题","type":"text"}

6.2 单选字段

{"name":"状态","type":"select","multiple":false,"options":[{"name":"Todo"},{"name":"Done"}]}

6.3 数字字段

{"name":"耗时分钟","type":"number"}

6.4 可点击 URL 字段

这是本次踩坑点。

错误做法：

{"name":"飞书文档链接","type":"text"}

这样飞书端会显示纯文本链接，移动端不能直接点击打开。

正确做法：

{"name":"内容梳理可打开","type":"text","style":{"type":"url"}}

飞书 Base 的 URL 样式字段本质仍是 type=text，但必须设置：

"style": {"type": "url"}

写入记录时，值仍然是普通 URL 字符串：

{"内容梳理可打开":"https://my.feishu.cn/file/xxx"}

CLI 读回时会显示为 Markdown 链接格式，说明飞书端已经按 URL 字段处理。

7. 上传 Markdown 到飞书

本次使用 lark-cli markdown +create 上传书籍 Markdown：

lark-cli markdown +create \
  --as user \
  --file 'notes/books/为什么精英都是时间控/02_方法卡片.md' \
  --name '为什么精英都是时间控_02_方法卡片.md' \
  --format json

本次上传结果：

注意：不要用 company_analyze 的 create_doc_from_md.py 默认上传，除非显式设置：

FEISHU_SKIP_BITABLE=1

否则它会写入研报项目的旧多维表格。

8. 写入记录

使用 record-upsert：

lark-cli base +record-upsert \
  --as user \
  --base-token '<base_token>' \
  --table-id '<table_id>' \
  --json '{"标题":"早晨通勤开始","日期":"2026-06-04"}' \
  --format json

更新已有记录时传 --record-id：

lark-cli base +record-upsert \
  --as user \
  --base-token '<base_token>' \
  --table-id '<table_id>' \
  --record-id '<record_id>' \
  --json '{"最后同步时间":"2026-06-04 10:38:00"}' \
  --format json

本次写入记录数：

9. 本次数据来源

9.1 每日记录

来源：logs/daily_log.md

同步内容：

• 2026-06-03 返程通勤、家务记录。
• 2026-06-04 早晨打车通勤记录。

9.2 阅读书籍

来源：notes/books/为什么精英都是时间控/

同步内容：

• 书名：为什么精英都是时间控
• 作者：桦泽紫苑
• 状态：复盘中
• 主题：时间管理、精力管理、个人成长

9.3 文档资产

来源：notes/books/**/*.md

每个 Markdown 一条记录，包含：

• 标题
• 类型
• 所属主题
• 本地路径
• 飞书文档链接
• 摘要
• 标签
• 最后修改时间
• 最后同步时间

9.4 知识索引

来源：notes/knowledge_base.md

同步了 Projects 和 Reading Notes 中已有索引。

10. 验证方法

查看表列表：

lark-cli base +table-list \
  --as user \
  --base-token <base_token> \
  --format json

查看记录：

lark-cli base +record-list \
  --as user \
  --base-token <base_token> \
  --table-id tblqceBluld0ggkk \
  --format json

统计记录数：

lark-cli base +record-list \
  --as user \
  --base-token <base_token> \
  --table-id tblqceBluld0ggkk \
  --format json | jq '.data.data | length'

注意：record-list 返回结构是 .data.data，不是 .data.items。

11. 已发现问题与修正

11.1 链接字段显示为纯文本

问题：手机端看到的是纯文本 URL，不能直接打开。

原因：字段创建成了普通文本字段：

{"type":"text","style":{"type":"plain"}}

修正：创建 URL 样式字段：

{"type":"text","style":{"type":"url"}}

并删除旧纯文本字段。

11.2 bot profile 权限不足

company_analyze bot profile 可以创建 wiki bitable 节点，但缺少 Base 表/字段/记录权限。

正确方式：使用用户授权后的默认 profile，并显式 --as user。

11.3 默认空表残留

Base 创建后自动生成默认表 数据表：

• Table ID：tbl94z2vTjOylux4

目前保留，后续可以删除。

12. 后续改进

1. 把 .tmp/write_personal_assistant_records.py 整理成正式脚本：scripts/sync_to_feishu_base.py。
2. 增加本地配置文件，保存 Base Token、Table ID、字段名映射。
3. 实现按业务键 upsert，避免重复写入同一条 daily log 或文档资产。
4. 删除默认空表 数据表。
5. 后续任务文件有内容后，同步 tasks/todo.md、tasks/in_progress.md、tasks/done.md。

13. 正式同步脚本

已将手工同步流程整理为正式脚本：

python3 scripts/sync_to_feishu_base.py

配置文件：

config/feishu_base.json

Dry run：

python3 scripts/sync_to_feishu_base.py --dry-run

脚本同步逻辑：

• Markdown 仍是本地源数据。
• 脚本解析 Markdown 生成结构化 records。
• 使用 lark-cli base +record-list 读取已有记录。
• 使用业务键匹配已有记录，命中则 update，未命中则 create。
• 使用 lark-cli base +record-upsert 写入飞书。

当前业务键：

调试结果：

• python3 -m py_compile scripts/sync_to_feishu_base.py 通过。
• --dry-run 正常输出待写入记录。
• 真实同步成功。
• 第二次真实同步命中相同 record_id，未产生重复记录。

当前记录数：

14. 创建飞书 Docx 文档而不是 Markdown 文件

读书笔记类 Markdown 应创建为飞书 docx 文档，而不是上传为飞书 Drive Markdown 文件。

推荐命令：

lark-cli docs +create \
  --api-version v2 \
  --as user \
  --title '<文档标题>' \
  --content @'<本地 Markdown 路径>' \
  --format json

不要使用：

lark-cli markdown +create --file <md>

原因：

• markdown +create 创建的是飞书文件，链接形态是 /file/...。
• docs +create 创建的是飞书文档，链接形态是 /docx/...，更适合阅读和后续编辑。

也不要复用 company_analyze 的 create_doc_from_md.py，原因见根目录 AGENTS.md。

创建 docx 后，把返回的 data.document.url 写入 config/feishu_base.json 的 book_file_links，再运行：

python3 scripts/sync_to_feishu_base.py