转写说明

本文基于已校验的公开原文进行结构化转写与事实梳理,非原文转载。 转写保留可核验的技术事实,并将工程建议与来源观点明确分开。

核心结论

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。来源未给出可直接引用的安装命令,因此不补写安装参数。

可先查看发布命令结构,并使用预检模式检查文章:

1
2
juejin schema article publish --json
juejin draft create ./article.md --dry-run --json

frontmatter 可采用以下字段结构:

1
2
3
4
5
6
7
---
title: 我的 TypeScript 实践
brief: 此处填写五十到一百字的文章摘要,概括问题、方法和结果。
category: 开发工具
tags:
  - "6809640543006490638"
---

创建草稿后,可查询操作回执:

1
juejin history --json

已有草稿 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 不公开抓取到的全文快照,只发布独立转写与来源入口。

站内链接

相关文章