Repository navigation
Releases
v0.12.0 — 枚举值表补逐值中文说明
枚举值表补逐值中文说明
枚举值表原来只有两列，取值是英文标识，读者得回上面的字段描述里翻一遍才知道哪个是哪个：
枚举值
| 字段 | 取值 |
| data.attacks[].kind | thunder_hit |
| data.attacks[].kind | thunder_block|
| data.attacks[].kind | steal |
现在读 spec 的 x-enumDescriptions 把表升成三列：
枚举值
| 字段 | 取值 | 说明 |
| data.attacks[].kind | thunder_hit | 建筑被雷击损毁 |
| data.attacks[].kind | thunder_block | 被御守挡下，建筑无损 |
| data.attacks[].kind | steal | 被偷金币 |
OpenAPI 没有标准字段描述单个枚举值，x-enumDescriptions 是社区通行的扩展键（{取值: 说明}），连字符写法 x-enum-descriptions 也认。
spec 侧怎么产出
zod 4 直接用 .meta()，chanfana 会原样透传（实测可用）：
kind: z
.enum(["thunder_hit", "thunder_block", "steal"])
.describe("对抗类型")
.meta({
"x-enumDescriptions": {
thunder_hit: "建筑被雷击损毁",
thunder_block: "被御守挡下，建筑无损",
steal: "被偷金币",
},
}),.describe() 和 .meta() 谁先谁后都不会互相覆盖。
边界
按「宁可不写，也不写错」处理：
- 只配了部分取值 → 缺的那格留空，不错位
- 整张表都没配 → 保持两列，不留空列
- 说明值不是非空字符串 → 忽略，免得把
[object Object]写进文档
更新
npm i -g https://github.com/leeguooooo/openapi-lark/releases/latest/download/openapi-lark.tgz升级后首次 sync 因版本号纳入 hash 会全量重推一次，带枚举表的接口文档会一并更新。
v0.11.0 — 枚举值表补全字段路径（data.cost.type 而不是 type）
枚举值表补全字段路径
枚举值表第一列原来只写字段的叶子名，不写它挂在哪一层：
枚举值
| Property | Value |
| type | dice |
| type | free |
一个响应里出现两个 type（比如 drop.type 和 cost.type）时，读者无从分辨这张表说的是哪一个 —— 而上面的响应 Schema 表给的是完整点路径，两边对不上。
现在第一列是完整路径，写法与响应 Schema 表一致（数组段带 []）：
枚举值
| 字段 | 取值 |
| data.cost.type | dice |
| data.attacks[].kind | steal |
| data.rewards_granted[].kind | money |
匹配是靠取值集合消歧的，不是靠出现顺序：从 dereference 过的 api 按 (叶子名, 取值集合) 建索引再回填。drop.type 没有 enum，所以 type + ["dice","free"] 只会命中 cost.type 一个候选。命中不唯一（同名同取值真的挂在两处）时原样保留 —— 宁可少写路径，也不写错路径。
响应侧枚举表表头汉化
widdershins 对请求参数的枚举表发 |Parameter|Value|，对 schema 字段发 |Property|Value|。此前只汉化了前者，schema 字段的枚举表一直漏着英文表头。现在两者都翻成 | 字段 | 取值 | / | 参数 | 取值 |。
更新
npm i -g https://github.com/leeguooooo/openapi-lark/releases/latest/download/openapi-lark.tgz升级后首次 sync 因版本号纳入 hash 会全量重推一次，带枚举表的接口文档会一并更新。
v0.10.3 — 修复 XML NUL 泄漏截断文档 + partial_success 误报成功（issue #3）
修复（issue #3）
- NUL 占位符泄漏：行内标记嵌套（如 bold 内含行内 code）时，markdown→XML 的内部占位符未被还原，裸 NUL 字节进入 XML，飞书 docx import 在 degrade_code=3001 处截断全文。占位符改为循环还原，彻底修复。
- partial_success 误报成功：
docs +update返回result=partial_success或非空warnings时不再显示 ✓，视为推送失败；endpoint 模式的 XML 推送失败会自动回退 markdown 重推，文档保持完整。 - 兜底：最终 XML 输出剥离所有 XML 非法控制字符（保留 Tab/CR/LF）。
更新
npm i -g https://github.com/leeguooooo/openapi-lark/releases/latest/download/openapi-lark.tgz升级后首次 sync 因版本号纳入 hash 会全量重推一次，正好把此前被截断的文档全部修复。
v0.10.2 — 修复全局安装（npm i -g github:… 报 spawn sh ENOENT）
修复
- 全局安装失败：
npm i -g github:leeguooooo/openapi-lark在 npm 10/11 上因 npm 自身 bug（全局装 git 依赖时传递依赖 postinstall 报spawn sh ENOENT）必然失败。安装/更新命令统一改为 Release tarball：
npm i -g https://github.com/leeguooooo/openapi-lark/releases/latest/download/openapi-lark.tgz- bin 可执行位：构建产物
dist/cli.js现在带 exec bit，修复 tarball 安装后openapi-lark命令permission denied。 npx -y -p github:leeguooooo/openapi-lark openapi-lark <cmd>（skill 使用的形式）不受影响，仍可用。- 每次 release 由 CI 自动构建并附加
openapi-lark.tgz。
含 v0.10.1 全部修复（跨用户重复建树修复 + 未共享状态警告）。
v0.10.1 — 跨用户重复建树修复 + 未共享状态警告
修复
- parentDocToken 跨用户重复建树：一个用户创建的文档树，另一个用户（或换机器 / 删了
.openapi-lark/）跑 sync 不再整棵重复创建——缓存 miss 时先按标题认领 parent 下已有子节点，找不到才创建。 - 未共享状态警告：换人 clone / 换机器首跑 sync 时输出警告，说明 hash 缓存不随 git 共享、本次会按标题认领线上文档并全量重推（属预期），并建议多人协作提交
.openapi-lark/或固定由 CI 执行 sync。
更新方式
npm i -g github:leeguooooo/openapi-lark升级后首次 sync 会因版本号纳入 hash 而全量重推一次，属预期。
v0.10.0 — 真彩色：post-push 块着色（必填→红）
真彩色 —— post-push 块着色 pass
Lark 文档的导入路径不携带颜色（markdown/XML import 会剥离），这是 v0.5.1 移除"死"颜色标记的原因。但颜色其实活在块级属性上，可在文档推送后通过 docx 块 API 设置。
v0.10 新增可复用的 post-push 块着色器（src/lark/block-style.ts）。每个本次实际推送成功的接口文档（cache-skip / dry-run 的不跑），推送后自动：
- 拉取文档 blocks（
GET .../documents/{id}/blocks --page-all）。 - 在 block 树上跑可插拔的 StyleRule[]，定位目标文本元素，收集
{block_id, content, text_element_style}编辑。 - 一次
PATCH .../documents/{id}/blocks/batch_update应用全部编辑。
best-effort：拉取或更新失败仅打印告警、绝不把同步结果翻成 failed（内容已落地，颜色是增强）。规则集可扩展（后续加 highlight / callout 着色等）。
规则 #1（本版）：必填正文单元格 → 红字
字段表（参数 / 响应 Schema / 请求体）的「必填」列，对正文行（按表结构跳过表头）值为「必填」的单元格设 text_color:1（红）。表头「必填」永不染色；可选单元格（—）不动。
渲染层配合：必填单元格从 v0.9 的 ✅ 改为字面**「必填」**，供着色器染红。
验证（实测 zugo presence-records）
推送后着色器报告 styled:4；回读 blocks 确认正文 roomNo / startTime / endTime（参数表）与 success（200 Schema 表）的必填单元格 text_color:1，四张表的表头「必填」均 text_color:None（未染色）。
调色板
text_color / background_color：1=红 2=橙 3=黄 4=绿 5=蓝 … 15≈灰。background_color（高亮）同理设置，已为后续 highlight 规则预留（styler 支持任意 text_element_style）。
消费方：npx github:leeguooooo/openapi-lark 拉 main。
v0.9.0 — 必填列 ✅ / — 标记
必填列醒目标记（替代不可行的红字）
Lark 文档导入会剥离 text-color（v0.5.1 已证实，也是当初移除状态码颜色的原因），所以「必填红字」做不到。改用导入可存活的 emoji：
所有字段表 —— 参数表 + 响应 Schema 表 + 请求体 schema 表 —— 的「必填」列单元格：
- 必填 →
✅ - 可选 →
—（em dash，比否/false更像"留白"）
兼容 widdershins 的 true/false 与已本地化的 是/否/required 等取值。仅改「必填」列单元格，列头文字与其他列保持不变；无该列的表（响应状态表、枚举值表）no-op。
实测 zugo presence-records 参数表：roomNo/startTime/endTime → ✅，可选项 → —；响应 Schema 与 POST 请求体表同样生效。
消费方：npx github:leeguooooo/openapi-lark 拉 main。
v0.8.0 — sync 进度可见 + description 正文回归修复
🐛 回归修复（v0.7 引入）：恢复 operation description 正文
v0.7 的鉴权 dedup「skip 到下一个 heading」会连带吞掉紧跟鉴权段后的 description 正文 —— 整段（项目符号列表 + 「为什么用游标」分页说明）在 Lark 文档里消失，callout 后直接跳到「参数」。
- 鉴权 dedup 改为只跳过鉴权段自身那一段正文（遇空行即停），description 正文恢复完整渲染（
<ul>项目 +<b>加粗 + 段落）。 - callout 的
⚠️ 注意行此前泄漏原始 markdown（- **数据源**：…）；现清洗 markdown，清洗后仍像 markup 则整行省略。callout 不再吞/重复整段 description。 - 移除 callout 下方冗余的裸
METHOD /path代码行（callout 首行已粗体展示）。
✨ sync 进度可见（UX）
长跑（~175 接口）此前规划期只零散打印、推送期无计数，读起来像卡死。新增（纯日志，不改渲染/推送语义）：
- 阶段标题：
📋 阶段 1/2 规划结构（对账已有 wiki 节点）/🚀 阶段 2/2 待推送：共 N 个接口（总数前置）。 - 规划期滚动计数：
规划中：已对账 k 个节点…（每 ~20 节点 / ~2s 节流）+ 结束规划完成：X 节点 / Y 标签 / Z 分组 / W 待清理 zombie。 - 每接口推送
[i/N] p%：[42/175] 24% ✓ <标题> — <METHOD path> … (2.5s)。 - 失败/告警仍在结尾汇总；dry-run 也走推送计数。
实测 zugo（161 接口）dry-run：阶段标题、滚动计数、[1/161] 1% → [161/161] 100% 全部正常。
消费方：npx github:leeguooooo/openapi-lark 拉 main。
v0.7.0 — 可读性优化（点路径 Schema / 请求体示例 / 鉴权 dedup）
可读性修复（endpoint 模式 XML 输出）
1. 响应 Schema 字段名 → 完整点路径
widdershins 的 »/»»/»»» 嵌套标记 geeky 难读，改为重建完整点路径：
data → data.activities[] → data.activities[].activityId → data.pagination.hasMore。
数组对象父级加 []，子字段读作 parent[].child。无歧义、可复制进代码、全 ASCII。
2. 移除「调用流程」mermaid 图
固定骨架，只是重述 鉴权/参数/响应/分页 已有信息 → 删除。
3. 鉴权 dedup
单一鉴权方案时 drop 独立「鉴权」段（顶部 callout 的 🔑 行已覆盖）；多方案（OR）才保留段（callout 一行装不下列表）。
4. 轻量分隔
各主区块（参数 / 响应 / 响应 Schema / 示例 / 调用前检查）间加 <hr/>。
5. 请求体渲染（POST/PUT/PATCH）
- 移除 widdershins 的原始
> Body parameterJSON-Schema dump（冗余噪音）。 - 新增 pretty-print 请求体示例 (JSON)
<pre lang=json caption=请求体示例>，从 requestBody schema 合成（example/default/enum/format/类型默认值），置于 curl 请求示例之前。GET/DELETE 跳过。
保留
顶部 📌 callout、pre caption、约束列、curl 请求示例、调用前检查 checkbox。无颜色、无 button（Lark 导入会剥离）。
注：本版含 v0.6 的「缓存纳入版本号」修复，普通 sync 会自动重推全部接口。
消费方：npx github:leeguooooo/openapi-lark 拉 main。
v0.6.0 — 分页调用流程图 + 调用前检查 + 缓存纳入版本
新增两块 DocxXML 富 block（endpoint 模式，均已 push-probe 确认能通过 Lark 导入）
🔀 调用流程 mermaid（条件）
仅当接口分页时，在 ## 调用流程 下输出 <whiteboard type="mermaid"> 的 graph TD。分页判定：cursor/nextCursor 参数或响应字段、hasMore/pagination 响应字段、或 limit+offset/page。非分页接口不输出（2 框流程是噪音）。
流程按真实操作生成：调用方 → 鉴权步骤（如「携带 X-Api-Key」）→ 必填参数（如「传 roomNo / startTime / endTime」）→ 可选过滤分支（如 activityType）→ 调用 → 读取 data 字段（如 activities + pagination）→ {hasMore = true?} →是→「用 nextCursor 请求下一页」循环 / →否→ 结束。
☑️ 调用前检查 checkbox（条件）
## 调用前检查 下输出 <checkbox>，仅列 spec 可推导项（已配置鉴权 / 必填参数已传 / 分页用 nextCursor），最多 4 条，少于 2 条整段跳过。不臆造通用项。
放置顺序：callout → 鉴权 → 参数 → 调用流程 → 响应 → 示例 → 调用前检查。
修复：sync 缓存纳入工具版本
跳过缓存的 hash 之前只基于源 markdown，渲染层单独升级时 hash 不变 → 报 unchanged 跳过推送，线上仍是旧版（v0.5.1 升级后实测 175 skipped / 0 pushed）。现 hash 前缀加 openapi-lark@<version>，每次工具升级普通 sync 自动重推全部接口，无需 --force。
说明
- 不输出
<button>（被 Lark 导入丢弃）与任何颜色属性（被剥离）。可正常落地：callout 结构+emoji、pre caption、whiteboard(mermaid)、checkbox。 - XML 生成/推送失败仍自动回退 markdown，绝不阻断 sync。
消费方：npx github:leeguooooo/openapi-lark 拉 main。