转写说明
本文基于已校验的公开原文进行结构化转写与事实梳理,非原文转载。 转写保留可核验的技术事实,并将工程建议与来源观点明确分开。
- 原作者: 浪遏
- 原始来源: https://juejin.cn/post/7706807603482361907
- 原文发布时间: Wed, 11 Nov 2026 15:54:49 GMT
核心结论
juejin-cli 是连接本地 Markdown 与掘金发布流程的命令行工具,目标不是单次封装接口,而是让作者与 AI Agent 共享一套可发现、可预检、可衔接且可恢复的写作工作流。
其可靠性主要来自四点:命令定义可生成结构化 schema;JSON 输出具有稳定的成功与失败语义;发布配置能够随 Markdown 复用;写操作发生超时或响应异常时不自动重放,并通过 operation ID、阶段及资源 ID 留下恢复线索。工具明确区分“接口成功”“草稿保存”“提交被平台接受”和“文章公开可见”,避免把不同状态混为发布成功。
能力机制
命令树由 Commander 定义,并从同一来源生成 schema,减少命令参数与独立说明不同步的问题。--json 模式成功时向 stdout 输出单个 JSON 文档,失败时向 stderr 输出错误文档并返回非零退出码。调用方可以直接取得 draft_id,继续执行更新或发布,而不必从自然语言输出中提取状态。
代码按职责拆分:命令注册位于 src/cli/commands/,依赖由 context.ts 组装,平台请求与类型集中在 src/platform/juejin/;Markdown 解析和图片处理位于 src/content/;草稿、专栏与发布等写入流程由 WritingService 编排,负责加锁、读取合并及操作回执。命令行入口与 SDK 共用底层能力。
文章可通过 frontmatter 携带标题、摘要、分类和标签。标签 ID 使用字符串,避免 JavaScript 大整数精度问题。本地图片会先检查文件存在性和受支持格式,上传后再替换正文引用,原始 Markdown 不被修改。
快速开始
已发布的 npm 包名为 @ganzhibin/juejin-cli。来源未给出可直接引用的安装命令,因此不补写安装参数。
可先查看发布命令结构,并使用预检模式检查文章:
| |
frontmatter 可采用以下字段结构:
| |
创建草稿后,可查询操作回执:
| |
已有草稿 ID 时应沿用该资源,并执行 draft update,而不是重新创建草稿。来源未提供完整参数形式,因此不补写文件、ID 等参数示例。
适用边界
配置保存在本地,只表示文章、图片路径和发布参数可由作者在本地目录或 Git 仓库中管理,不能据此推断网络请求、平台处理或推理数据一定不离开本机。
写请求超时不代表平台没有保存资源。juejin-cli 不会在请求异常后自动重放创建或发布操作,因为自动重试可能生成重复草稿或重复提交。恢复前需要核对远端状态和回执。发布结果中的 submitted 仅表示平台接受提交,不代表审核完成或已经公开索引。
目录级批量发布入口已完成本地验收,但来源说明它将随 0.2.0 发布,0.1.0 不包含该命令。搜索接口的条数限制行为、审核状态查询和测试内容清理也仍需完善,不能把架构规划视为全部功能已经实现。
核验清单
来源可确认的事实包括:
schema与命令定义共用来源,JSON 模式使用 stdout、stderr 和退出码区分结果。- 草稿、专栏及发布流程具有操作 ID、阶段和已知资源 ID 等回执信息。
- 图片上传前执行存在性与格式检查,正文替换后保留原始 Markdown。
- 精确匹配标签后会立即结束搜索;使用已确认的标签 ID 可以减少重复搜索。
- 自动化测试曾覆盖登录、查询、图片上传、草稿创建与更新、文章提交、专栏创建与更新。
工程上建议在批量写入前完成整目录预检;遇到结果未知的条目时停止自动执行并核对远端状态;已完成条目直接跳过;更新时复用已有草稿 ID;验收时分别记录接口成功、草稿成功、提交成功和公开可见状态,并保留失败输入、请求耗时与具体原因。
来源与核验
- 原始文章
- 页面事实以原始来源及其引用的官方资料为准;版本、星标和模型能力会随时间变化。
- AI Stack 不公开抓取到的全文快照,只发布独立转写与来源入口。