@monoedge/jdu-cli

jdu 把本地 Markdown（含图片、嵌套 md）发布到简牍服务。

快速开始

npm i -g @monoedge/jdu-cli
jdu login                   # 首次连接官方站点 https://jiandu.zausau.com，打开浏览器用 Capsule 授权；--server <url> 指定站点
jdu push notes/hello.md --visibility public
jdu read <id|url> [--version <seq>] [--out <file.md>]
jdu official add <docId>   # 管理员：上架到官方知识库

成功时 stdout 只有文档 URL。需要 Node.js ≥ 22。

登录只走 Capsule 浏览器授权：jdu login 打开 <server>/p/cli/authorize，确认后 CLI 用 PKCE 换回 CLI token。SSH 远端等无图形环境自动切到手动模式（也可加 --no-browser）：终端打印授权地址，在任意设备打开并确认后把页面上的 code 粘回终端。CI 等无法交互的机器先在已登录的机器上签一枚，再交给它：

jdu token create --label ci        # 浏览器里确认一次，stdout 只有 token
jdu login --token <token>          # 或不落盘，逐条命令用 JIANDU_TOKEN=<token>

签出去的 token 用 jdu token list / jdu token rm <id> 管理。

适用范围

• 支持：连接简牍官方服务（Cloudflare 托管、Capsule 登录），发布文档与 widget，管理标签、评论、团队、分享与读者池
• 不支持：本包不含 server，也不提供部署命令；旧版登录方式（password / token / forward-auth / Cloudflare Access / OIDC）留在本机的凭据不再可用，相关命令会提示重新 jdu login
• 版本核对：写操作前先读一次站点的 /healthz，服务端与本 CLI 版本不匹配时在发出任何写请求前失败，并提示升级 jdu

写简牍 Markdown 的 agent 可安装 jiandu-markdown-guide skill：复制整个目录到 agent 的 skills 搜索路径。skill 会按当前 jdu -h 与实例的 widget 元数据写稿。

可选写作优化

jdu writing guide 离线返回中文方法论，由当前 agent 结合用户的原文、读者、用途和偏好优化文章。不调用 LLM、不要求 LLM key、不读取或修改原文、不写用户配置或全局规则。

jdu writing guide --widgets --site <alias> 只读目标实例的 /api/syntax、widget 注册表和解析结果，返回当前可用组件的用途、场景、真实 schema 与通过 schema 的样本 fence。默认按当前身份解析个人组件；--doc <id> 同时启用查询，并按可读文章的作者解析组件。未声明的兼容能力与未运行的渲染保持未核对。查询失败时仍返回方法论，组件清单标为未验证，退回普通 Markdown。

--json 返回 methodology 与 instance 两个独立部分；目录状态为 not-requested、verified 或 unavailable。verified 只指查询与版本对齐，renderVerified 始终为 false。不会自动登录或刷新凭据；站点未明确、授权过期或接口不可用时通过降级说明处理。fence 可带 scope，不能附加 @version；版本由目标实例解析。

skill 仅提示这个可选入口。明确要求优化时无需重复询问；只要求写稿时在有帮助的场景征询，拒绝或尚未同意时保持原有写法。不会自动注入方法论、插入 widget、改全局写作习惯或获准发布。方法论内联于 CLI 单文件产物，不依赖 skill 安装路径。完整文章前后示例见仓库 examples/writing-guide。

配置在 ~/.config/jiandu/，可被 JIANDU_SERVER / JIANDU_TOKEN 覆盖。

文档列表

jdu list 自动读取所有页；--all 包含归档文档，--json 输出一个 JSON 文档数组（空列表为 []）。JSON 中的 visibility 保留原始 private / public。

jdu list 表格会显示团队名称、稳定 ID 和有效指定读者数量，例如 private (team: Design [team-id], +2 readers)；JSON 保留 team（团队 ID，无团队为 null）和 readers（无有效读者为 []），新增 teamName（当前可访问团队的名称，无团队或无法解析时为 null）。名称从所选站点的可访问团队列表读取，每次运行重新解析；同名团队通过 ID 区分。无法解析时表格显示 team: unknown [team-id]（随 CLI 语言翻译），查询失败的提示写入 stderr。没有团队的文档不会被推断为团队文档。

jdu team list 列出所选站点当前用户可访问团队的名称和 ID，--json 输出一个团队数组（空列表为 []），两种输出均自动读取所有页。普通用户只能列出自己所属的团队，实例管理员沿用现有权限查看全部团队；单篇文档的指定读者身份不授予所在团队的访问权。

jdu read <id|url> 把文档的 resolved Markdown 原文写到 stdout；--out <file> 改为写入文件，--version <seq> 精确读取指定版本，默认读取最新版。URL 可使用 /d/<id>、/d/<id>.md 或带历史序号的 /d/<id>/v/<seq> 文档路径。绝对 URL 必须对应本机已配置的 Jiandu 站点；可用 --site <alias> 指明站点，但 URL origin 与所选站点不符时会在请求前报错，不会向任意 origin 发送已配置凭据。该命令只返回 Markdown 正文，不递归下载附件。

过期或撤销授权不计入读者。public 表示任何人可读，附加授权仍会显示；ARCHIVED 单独表示归档状态。团队查询复用现有 /api/teams。