neodrop-cli 1.2.0 → 2.0.1

package/lib/api.mjs

@@ -1,22 +1,25 @@
-// tRPC 11 HTTP 调用最小封装（适配 backend 配置的 superjson transformer）。
+// Minimal tRPC 11 HTTP client (matches the backend's superjson transformer).
 //
-// URL 形态：
+// URL shapes:
 //   - query:    GET  /trpc/<proc>?input=<urlencoded {json:<input>}>
 //   - mutation: POST /trpc/<proc>  body = {json:<input>}
 //
-// 响应形态（superjson）：
-//   - 成功：{ result: { data: { json: <T>, meta?: {...} } } }
-//   - 失败：{ error: { json: { message, code, data: {...} } } }
+// Response shapes (superjson):
+//   - success: { result: { data: { json: <T>, meta?: {...} } } }
+//   - failure: { error: { json: { message, code, data: {...} } } }
 //
-// 入参 / 出参的 superjson `meta` 字段用于 Date 等非 JSON 类型还原，CLI 用不上
-// （凭证 expiresAt 直接用 ISO 字符串），这里只取 `json` 字段。
+// The superjson `meta` field on inputs/outputs restores non-JSON types such as
+// Date, which the CLI doesn't need (credential expiresAt is a plain ISO string),
+// so we only read the `json` field here.
 //
-// 零运行时依赖：用 Node 原生 fetch（Node 18+），不引第三方 HTTP 库。
+// Zero runtime dependencies: uses Node's native fetch (Node 18+), no third-party
+// HTTP library.
 
 export class ApiError extends Error {
-  // tRPC 业务错误（HTTP >= 400 或 body.error 非空）。
-  // code 来自 tRPC 的错误码（'UNAUTHORIZED' / 'NOT_FOUND' / 'BAD_REQUEST' 等），
-  // CLI 上层可据此分流（如 401 提示重 login）。
+  // tRPC business error (HTTP >= 400 or a non-empty body.error).
+  // code comes from tRPC's error codes ('UNAUTHORIZED' / 'NOT_FOUND' /
+  // 'BAD_REQUEST', etc.), so the CLI can branch on it (e.g. prompt to re-login
+  // on 401).
   constructor(message, code = "", httpStatus = 0) {
     super(code ? `[${code}] ${message}` : message);
     this.name = "ApiError";
@@ -28,14 +31,15 @@ export class ApiError extends Error {
 function buildUrl(apiOrigin, proc, inputValue) {
   const base = `${apiOrigin.replace(/\/+$/, "")}/trpc/${proc}`;
   if (inputValue === undefined) return base;
-  // superjson 入参 wrapper：{ json: <value> }
+  // superjson input wrapper: { json: <value> }
   const qs = new URLSearchParams({ input: JSON.stringify({ json: inputValue }) });
   return `${base}?${qs.toString()}`;
 }
 
-// Cloudflare WAF 看到默认 UA 会按 bot 拒（HTTP 403 + error code 1010）。给一个
-// 老实的客户端身份——告诉 CF/origin「这是 neodrop-cli」，便于排查与白名单。
-// 改 UA 不是为了伪装，是为了通过基础的 client fingerprint check。
+// Cloudflare WAF rejects the default UA as a bot (HTTP 403 + error code 1010).
+// Present an honest client identity — telling CF/origin "this is neodrop-cli"
+// makes debugging and allowlisting easier. Setting the UA is not about
+// disguise, it's about passing the basic client fingerprint check.
 const USER_AGENT = "neodrop-cli/1.0 (+https://github.com/NeoDropAI/neodrop-skills)";
 
 async function doRequest({ method, url, token, body }) {
@@ -46,11 +50,13 @@ async function doRequest({ method, url, token, body }) {
   };
   if (token) headers.authorization = `Bearer ${token}`;
 
-  // 一次 transparent retry——线上 Cloudflare/upstream 偶发 TLS-layer 抖动
-  // （"EOF occurred in violation of protocol" 等）。mutation 也加 retry：tRPC
-  // mutation 在网络抖动 + 业务层未提交时是幂等可重的（最多多签发一个 PAT/订阅，
-  // 可接受代价）。注意 fetch 对 4xx/5xx 不抛错——那由 handleResponse 处理，
-  // 这里只 retry 真正的网络层异常。
+  // One transparent retry — production Cloudflare/upstream occasionally has
+  // TLS-layer hiccups ("EOF occurred in violation of protocol", etc.). Retry is
+  // applied to mutations too: a tRPC mutation is idempotent-enough to retry when
+  // the network flaked before the business layer committed (worst case, one
+  // extra PAT/subscription is issued — an acceptable cost). Note that fetch does
+  // not throw on 4xx/5xx — that's handled by handleResponse; here we only retry
+  // true network-layer failures.
   let lastErr;
   for (let i = 0; i < 2; i++) {
     try {
@@ -59,11 +65,12 @@ async function doRequest({ method, url, token, body }) {
       lastErr = err;
     }
   }
-  // Node fetch 把真正的原因藏在 err.cause（如 ECONNREFUSED / ENOTFOUND /
-  // self-signed certificate）；err.message 通常只是笼统的 "fetch failed"。
+  // Node fetch hides the real reason in err.cause (e.g. ECONNREFUSED /
+  // ENOTFOUND / self-signed certificate); err.message is usually just the
+  // generic "fetch failed".
   const cause = lastErr?.cause;
   const detail = cause?.code || cause?.message || lastErr?.message || String(lastErr);
-  throw new Error(`连接失败：${detail}`);
+  throw new Error(`Connection failed: ${detail}`);
 }
 
 async function handleResponse(res) {
@@ -73,7 +80,7 @@ async function handleResponse(res) {
     try {
       body = JSON.parse(text);
     } catch {
-      throw new Error(`非 JSON 响应（HTTP ${res.status}）：${text.slice(0, 200)}`);
+      throw new Error(`Non-JSON response (HTTP ${res.status}): ${text.slice(0, 200)}`);
     }
   }
 
@@ -85,7 +92,7 @@ async function handleResponse(res) {
     throw new ApiError(msg, code, res.status);
   }
 
-  // superjson 响应剥层
+  // Unwrap the superjson response
   return body.result.data.json;
 }
 
@@ -96,8 +103,8 @@ export async function trpcQuery(opts, proc, inputValue) {
 }
 
 export async function trpcMutation(opts, proc, inputValue) {
-  const url = buildUrl(opts.apiOrigin, proc); // mutation 不走 query input
-  // mutation 永远发 JSON body：input 为 undefined 时发 {"json": null}
+  const url = buildUrl(opts.apiOrigin, proc); // mutations don't use query input
+  // A mutation always sends a JSON body: {"json": null} when input is undefined
   const body = JSON.stringify({ json: inputValue === undefined ? null : inputValue });
   const res = await doRequest({ method: "POST", url, token: opts.token, body });
   return handleResponse(res);

package/lib/chat.mjs

@@ -1,17 +1,23 @@
-// chat 能力：发一条消息给 Neodrop 的对话 agent，等回复生成完，拿完整回复。
+// chat capability: send one message to Neodrop's conversational agent, wait for
+// the reply to finish generating, and return the complete reply.
 //
-// 链路（全部走用户 PAT，Bearer 鉴权）：
-//   1. 建 / 复用会话：session.create（全局助手）或
-//      session.getOrCreateChannelAssistant（--channel 频道助手）——tRPC mutation
-//   2. 发送：POST /api/chat（非 tRPC 的 Hono 端点，后端 2026-07 起支持 PAT Bearer）。
-//      响应是 SSE 流；回复由后端 BullMQ worker 生成、与本连接生命周期解耦，
-//      CLI 不解析流内容，只把「流读到 EOF」当作大概率完成的信号。
-//   3. 收敛：轮询 session.getActiveChatTurn 直到 null（turn 已 terminal——
-//      SSE 中途断线也靠这层兜住），再 session.getMessages 取本次 user 消息
-//      之后新增的消息作为回复。最终一致以 getMessages 为准，不信任流。
+// Flow (everything uses the user's PAT with Bearer auth):
+//   1. Create / reuse a session: session.create (global assistant) or
+//      session.getOrCreateChannelAssistant (--channel assistant) — tRPC mutation.
+//   2. Send: POST /api/chat (a non-tRPC Hono endpoint; the backend has supported
+//      PAT Bearer since 2026-07). The response is an SSE stream; the reply is
+//      generated by a backend BullMQ worker decoupled from this connection's
+//      lifecycle, so the CLI does not parse the stream contents and only treats
+//      "the stream reached EOF" as a likely-done signal.
+//   3. Settle: poll session.getActiveChatTurn until null (the turn has reached a
+//      terminal state — this layer also covers a mid-stream SSE disconnect),
+//      then session.getMessages to take the messages added after this user
+//      message as the reply. Final consistency relies on getMessages, not the
+//      stream.
 //
-// 为什么不解析 SSE：UIMessage chunk 协议类型多且随主仓演进，CLI 的消费者是
-// AI agent，要的是「一次拿到完整回复的 JSON」，不是逐 token 渲染。
+// Why we don't parse the SSE: the UIMessage chunk protocol has many types and
+// evolves with the main repo, and the CLI's consumer is an AI agent that wants
+// "the complete reply as JSON in one shot", not token-by-token rendering.
 
 import { randomUUID } from "node:crypto";
 import { trpcMutation, trpcQuery } from "./api.mjs";
@@ -23,8 +29,9 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-// POST /api/chat 发送消息。成功返回 Response（SSE 已开始）；HTTP >= 400 时
-// 解析 JSON error 抛出（402 余额不足 / 401 未登录 / 400 消息非法等）。
+// POST /api/chat to send a message. On success returns the Response (the SSE
+// stream has started); on HTTP >= 400 it parses the JSON error and throws
+// (402 insufficient balance / 401 not logged in / 400 invalid message, etc.).
 async function postChatMessage({ apiOrigin, token, sessionId, text, locale, signal }) {
   const url = `${apiOrigin.replace(/\/+$/, "")}/api/chat`;
   const body = {
@@ -51,29 +58,31 @@ async function postChatMessage({ apiOrigin, token, sessionId, text, locale, sign
     try {
       payload = await res.json();
     } catch {
-      // 非 JSON 错误体，用 HTTP 状态兜底
+      // Non-JSON error body; fall back to the HTTP status
     }
     const msg = (payload && (payload.error || payload.message)) || `HTTP ${res.status}`;
     const code = (payload && payload.code) || "";
-    throw new Error(code ? `[${code}] ${msg}` : `发送失败：${msg}`);
+    throw new Error(code ? `[${code}] ${msg}` : `Send failed: ${msg}`);
   }
   return { response: res, userMessageId: body.message.id };
 }
 
-// 读 SSE 流到 EOF（内容丢弃）。断线 / 超时都不算失败——后端 worker 与连接
-// 解耦，最终状态交给 getActiveChatTurn 轮询收敛。
+// Read the SSE stream to EOF (contents discarded). A disconnect / timeout is not
+// a failure — the backend worker is decoupled from the connection, and the final
+// state is settled by polling getActiveChatTurn.
 async function drainStream(response) {
   try {
     if (!response.body) return;
     for await (const _chunk of response.body) {
-      // 只等 EOF，不解析
+      // Just wait for EOF, don't parse
     }
   } catch {
-    note("⚠ SSE 连接中断，转轮询等待回复…");
+    note("⚠ SSE connection dropped, falling back to polling for the reply…");
   }
 }
 
-// 轮询直到 session 没有 live 的 chat turn（回复已生成完 / 失败 / 取消）。
+// Poll until the session has no live chat turn (the reply has finished /
+// failed / been cancelled).
 async function pollUntilTurnSettled({ apiOrigin, token, sessionId, deadline, intervalMs }) {
   for (;;) {
     const turn = await trpcQuery({ apiOrigin, token }, "session.getActiveChatTurn", {
@@ -82,7 +91,7 @@ async function pollUntilTurnSettled({ apiOrigin, token, sessionId, deadline, int
     if (!turn) return;
     if (Date.now() > deadline) {
       throw new Error(
-        `等待回复超时（turn=${turn.id} 仍在 ${turn.status}）。稍后可用 chat history --session ${sessionId} 查看结果。`,
+        `Timed out waiting for the reply (turn=${turn.id} still ${turn.status}). You can check the result later with chat history --session ${sessionId}.`,
       );
     }
     await sleep(intervalMs);
@@ -97,12 +106,50 @@ function extractText(parts) {
     .join("");
 }
 
+// Noise the raw message payload carries but a CLI consumer never needs: multi-KB
+// provider signatures, provider metadata, and per-call execution plumbing.
+const NOISE_KEYS = new Set([
+  "providerMetadata",
+  "callProviderMetadata",
+  "resultProviderMetadata",
+  "signature",
+  "startedAt",
+  "finishedAt",
+  "durationMs",
+  "stepNumber",
+  "toolCallId",
+]);
+
+function stripNoise(value) {
+  if (Array.isArray(value)) return value.map(stripNoise);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (NOISE_KEYS.has(k)) continue;
+      out[k] = stripNoise(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+// Slim a message for output: drop chain-of-thought `reasoning` parts (internal
+// thinking, not the answer) and strip the noise keys above from what remains.
+export function slimMessage(m) {
+  const cleaned = stripNoise(m);
+  if (Array.isArray(cleaned.parts)) {
+    cleaned.parts = cleaned.parts.filter((p) => p && p.type !== "reasoning");
+  }
+  return cleaned;
+}
+
 /**
- * 发送一条消息并等待完整回复。
+ * Send one message and wait for the complete reply.
  *
  * @returns {Promise<{sessionId: string, reply: {text: string, parts: unknown[]} | null, newMessages: unknown[]}>}
- *   reply 是本次新增消息里最后一条 assistant 消息（text = 其 text parts 拼接）；
- *   turn 失败等场景下可能没有 assistant 回复，reply 为 null，调用方看 newMessages 自行判断。
+ *   reply is the last assistant message among the newly added messages (text =
+ *   its text parts joined); in cases such as a failed turn there may be no
+ *   assistant reply, so reply is null and the caller decides based on newMessages.
  */
 export async function sendAndAwaitReply({
   apiOrigin,
@@ -116,8 +163,17 @@ export async function sendAndAwaitReply({
   const deadline = Date.now() + timeoutMs;
   const abort = AbortSignal.timeout(timeoutMs);
 
-  note(`→ 发送到 session ${sessionId} …`);
-  const { response, userMessageId } = await postChatMessage({
+  // Snapshot existing message ids before sending: the backend assigns the user
+  // message its own id (it does not echo the message.id we sent), so we can't use
+  // the client id as an anchor — we diff against "messages that appeared after
+  // sending".
+  const before = await trpcQuery({ apiOrigin, token }, "session.getMessages", {
+    sessionId,
+  });
+  const beforeIds = new Set(before.map((m) => m.id));
+
+  note(`→ Sending to session ${sessionId} …`);
+  const { response } = await postChatMessage({
     apiOrigin,
     token,
     sessionId,
@@ -126,7 +182,7 @@ export async function sendAndAwaitReply({
     signal: abort,
   });
 
-  note("… 回复生成中");
+  note("… generating reply");
   await drainStream(response);
   await pollUntilTurnSettled({
     apiOrigin,
@@ -139,23 +195,25 @@ export async function sendAndAwaitReply({
   const messages = await trpcQuery({ apiOrigin, token }, "session.getMessages", {
     sessionId,
   });
-  // 本次 user 消息之后新增的所有消息 = 这轮回复（含 tool / data 卡片等中间产物）
-  const anchor = messages.findIndex((m) => m.id === userMessageId);
-  const newMessages = anchor >= 0 ? messages.slice(anchor + 1) : [];
-  const lastAssistant = [...newMessages]
-    .reverse()
-    .find((m) => m.role === "assistant");
+  // All messages added this round (the diff); dropping the user message we just
+  // sent leaves this round's reply (assistant text + intermediate artifacts such
+  // as tool / data cards).
+  const fresh = messages.filter((m) => !beforeIds.has(m.id));
+  const lastUserIdx = fresh.map((m) => m.role).lastIndexOf("user");
+  const turn = lastUserIdx >= 0 ? fresh.slice(lastUserIdx + 1) : fresh;
+  const lastAssistant = [...turn].reverse().find((m) => m.role === "assistant");
 
   return {
     sessionId,
-    reply: lastAssistant
-      ? { text: extractText(lastAssistant.parts), parts: lastAssistant.parts }
-      : null,
-    newMessages,
+    // reply.text is the assistant's final text — empty when it only asked a
+    // clarifying question via a tool (read newMessages then). The structured
+    // content lives in newMessages, so reply carries just the text (no dup).
+    reply: lastAssistant ? { text: extractText(lastAssistant.parts) } : null,
+    newMessages: turn.map(slimMessage),
   };
 }
 
-/** 建新会话（全局助手），或按 --channel 拿该频道的助手会话。 */
+/** Create a new session (global assistant), or get the channel's assistant session per --channel. */
 export async function resolveChatSession({ apiOrigin, token, channelId }) {
   if (channelId) {
     const session = await trpcMutation(

package/lib/credentials.mjs

@@ -1,14 +1,16 @@
-// 本地凭证（~/.neodrop/credentials.json，chmod 0600）。
+// Local credentials (~/.neodrop/credentials.json, chmod 0600).
 //
-// 只支持单一 active token——切换 server / 换号都走 logout → login。
+// Only a single active token is supported — switching server / account goes
+// through logout → login.
 //
-// 凭证 schema：
-//   webOrigin  string  产品域（neodrop.ai；本地 dev 4001）
-//   apiOrigin  string  API 域（api.neodrop.ai；本地 dev 3001）—— 与 web 拆开是因为部署不同域
-//   token      string  PAT 明文，仅本机；权限 0600
-//   tokenId    string  用于 logout / 远程撤销
-//   name       string  在 /settings/cli-tokens 上展示的客户端名
-//   expiresAt  string  ISO 8601，默认 90 天
+// Credential schema:
+//   webOrigin  string  product origin (neodrop.ai; local dev 4001)
+//   apiOrigin  string  API origin (api.neodrop.ai; local dev 3001) — split from
+//                      web because they deploy on different domains
+//   token      string  PAT in plaintext, local machine only; mode 0600
+//   tokenId    string  used for logout / remote revocation
+//   name       string  client name shown on /settings/cli-tokens
+//   expiresAt  string  ISO 8601, defaults to 90 days
 //   createdAt  string  ISO 8601
 
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
@@ -27,12 +29,14 @@ export function readCredentials() {
   try {
     return JSON.parse(readFileSync(FILE_PATH, "utf-8"));
   } catch (err) {
-    throw new Error(`无法解析 ${FILE_PATH}：${err.message}`);
+    throw new Error(`Failed to parse ${FILE_PATH}: ${err.message}`);
   }
 }
 
-// 原子写：写临时文件 → chmod 0600 → rename。chmod 在 rename 之前完成，确保最终
-// 文件出现的瞬间权限就是 0600，不存在其他进程能读到 world-readable 的窗口。
+// Atomic write: write temp file → chmod 0600 → rename. The chmod completes
+// before the rename, guaranteeing the final file has 0600 permissions the moment
+// it appears — there is no window where another process could read it as
+// world-readable.
 export function writeCredentials(creds) {
   mkdirSync(FILE_DIR, { recursive: true });
   const tmp = `${FILE_PATH}.tmp`;
@@ -52,7 +56,7 @@ export function clearCredentials() {
 export function requireCredentials() {
   const creds = readCredentials();
   if (creds === null) {
-    throw new Error("未登录。先运行：npx neodrop-cli login");
+    throw new Error("Not logged in. Run: npx neodrop-cli login");
   }
   return creds;
 }

package/lib/install-skill.mjs

@@ -1,12 +1,15 @@
-// 把 SKILL.md + references/ 拷进 agent 的 skill 目录，让 `npx neodrop-cli` 一条命令
-// 既装好 CLI 又装好 skill 描述。
+// Copy SKILL.md + references/ into the agent's skill directory so that a single
+// `npx neodrop-cli` command installs both the CLI and the skill description.
 //
-// npm/npx 只分发「可执行文件」；而 Claude Code 等 agent 的 skill 是 SKILL.md +
-// references/ 这组文件落进 agent 的 skill 目录后才会被路由。两条分发渠道本来是
-// 分开的，这个命令把它们合并成一步。
+// npm/npx only distributes "executables"; an agent skill for Claude Code and the
+// like is the SKILL.md + references/ file set, which is only routed once it lands
+// in the agent's skill directory. The two distribution channels are normally
+// separate, and this command merges them into one step.
 //
-// 默认目标 ~/.claude/skills/neodrop-cli/（Claude Code 约定）；--dest 可改到别的
-// agent 的 skill 目录。目录名固定 neodrop-cli，与 SKILL.md frontmatter 的 name 一致。
+// The default target is ~/.claude/skills/neodrop-cli/ (the Claude Code
+// convention); --dest can point at another agent's skill directory. The
+// directory name is fixed to neodrop-cli, matching the name in SKILL.md's
+// frontmatter.
 
 import { cpSync, existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
@@ -18,14 +21,14 @@ export function defaultSkillDest() {
 }
 
 export function installSkill({ dest } = {}) {
-  // 包根目录 = 本文件所在 lib/ 的上一层（bin/ 与 lib/ 与 SKILL.md 同级）
+  // Package root = the parent of this file's lib/ dir (bin/, lib/, and SKILL.md are siblings)
   const here = dirname(fileURLToPath(import.meta.url)); // .../lib
   const pkgRoot = dirname(here);
   const target = dest || defaultSkillDest();
 
   const skillSrc = join(pkgRoot, "SKILL.md");
   if (!existsSync(skillSrc)) {
-    throw new Error(`找不到 SKILL.md（期望在 ${skillSrc}）；npm 包可能未按 files 白名单打进 SKILL.md`);
+    throw new Error(`SKILL.md not found (expected at ${skillSrc}); the npm package may not have included SKILL.md in its files allowlist`);
   }
 
   mkdirSync(target, { recursive: true });

package/lib/origins.mjs

@@ -1,10 +1,13 @@
-// Neodrop 部署的 web origin（产品域）与 api origin（backend 域）解耦。
+// Neodrop deploys the web origin (product domain) and api origin (backend
+// domain) decoupled.
 //
-// 线上：web = https://neodrop.ai，api = https://api.neodrop.ai
-// 本地 dev：web = http://localhost:4001，api = http://localhost:3001
+// Production: web = https://neodrop.ai, api = https://api.neodrop.ai
+// Local dev:  web = http://localhost:4001, api = http://localhost:3001
 //
-// CLI 让用户显式传 --api；不传时按 web origin 启发式推断。self-host 用户默认
-// 假设 backend 反代到 web 同域 /trpc/*，需要时用 --api 覆盖。
+// The CLI lets the user pass --api explicitly; when omitted it is inferred
+// heuristically from the web origin. For self-hosted users the default assumes
+// the backend is reverse-proxied on the same domain as web at /trpc/*, which can
+// be overridden with --api when needed.
 
 export function inferApiOrigin(webOrigin) {
   let parsed;
@@ -17,16 +20,17 @@ export function inferApiOrigin(webOrigin) {
   const port = parsed.port;
   const scheme = parsed.protocol.replace(/:$/, "");
 
-  // 线上 neodrop.ai → api.neodrop.ai
+  // Production neodrop.ai → api.neodrop.ai
   if (host === "neodrop.ai") {
     return `${scheme}://api.neodrop.ai`;
   }
 
-  // 本地 dev：localhost:4001 / 127.0.0.1:4001 → 同 host 3001
+  // Local dev: localhost:4001 / 127.0.0.1:4001 → same host on 3001
   if ((host === "localhost" || host === "127.0.0.1") && port === "4001") {
     return `${scheme}://${host}:3001`;
   }
 
-  // 其他（self-host 反代等）：默认与 web 同域，假设 /trpc/* 反代到 backend。
+  // Otherwise (self-host reverse proxy, etc.): default to the same domain as
+  // web, assuming /trpc/* is proxied to the backend.
   return webOrigin.replace(/\/+$/, "");
 }

package/lib/output.mjs

@@ -1,7 +1,7 @@
-// 统一输出：stdout = JSON（AI 直接 JSON.parse），stderr = 日志/提示。
+// Unified output: stdout = JSON (an AI can JSON.parse directly), stderr = logs/notices.
 //
-// 默认单行 JSON；--pretty 切 2 空格缩进 JSON——两者都是合法 JSON，AI 不需要
-// flag 切换也能解析。
+// Single-line JSON by default; --pretty switches to 2-space indented JSON — both
+// are valid JSON, so an AI can parse either without needing the flag.
 
 let pretty = false;
 

package/lib/web-urls.mjs

@@ -1,17 +1,23 @@
-// Neodrop 前端 URL 拼装：用户拿到 id 后能直接得到一条可点击的网页链接。
+// Neodrop frontend URL assembly: once a user has an id, they get a clickable web
+// link directly.
 //
-// 为什么放 skill 而不是后端 response：URL 路径（`/post/<id>` / `/channel/<id>` /
-// `/user/<id>`）是前端的渲染契约，不是数据契约——`grain.id` 是稳定的数据；前端
-// 明天可以把路由改成 `/post/<id>` 而无需后端发新版 API。把路由塞进 response 会让
-// backend 反向依赖前端渲染。这里给 CLI 内部用，作为 stderr 上的人类可读提示。
+// Why this lives in the skill rather than the backend response: URL paths
+// (`/post/<id>` / `/channel/<id>` / `/user/<id>`) are a frontend rendering
+// contract, not a data contract — `grain.id` is stable data; the frontend could
+// change the route to `/post/<id>` tomorrow without the backend shipping a new
+// API version. Baking routes into the response would make the backend depend
+// backwards on frontend rendering. This is for CLI internal use, as a
+// human-readable hint on stderr.
 //
-// 路径权威源 = `apps/web/src/app/[locale]/<route>/[id]/page.tsx`：
+// Path source of truth = `apps/web/src/app/[locale]/<route>/[id]/page.tsx`:
 //   post / grain  → `/post/<id>`
 //   channel       → `/channel/<id>`
 //   user          → `/user/<id>`
 //
-// 注意：CLI 不挂 locale 前缀（neodrop.ai 的 localePrefix='as-needed'，默认 locale
-// `en` 落到无前缀路径；其它 locale 由前端按用户偏好做客户端 redirect）。
+// Note: the CLI attaches no locale prefix (neodrop.ai uses
+// localePrefix='as-needed', so the default locale `en` maps to the prefix-less
+// path; other locales are handled by a client-side redirect based on user
+// preference).
 
 function strip(origin) {
   return origin.replace(/\/+$/, "");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neodrop-cli",
-  "version": "1.2.0",
+  "version": "2.0.1",
   "description": "Neodrop (neodrop.ai) CLI — let your AI agent (Claude Code / Cursor / Codex) browse channels, read posts, manage subscriptions, create channels and chat with Neodrop's AI assistants as you. stdout is always valid JSON. npx neodrop-cli login and go.",
   "type": "module",
   "bin": {

package/references/commands.md

@@ -27,12 +27,38 @@
 | `neodrop channels by-category <category> --sort latest --limit 20` | Channels in a category. |
 | `neodrop channels search "<query>" --locale en --limit 10` | Full-text search over the public pool. |
 
-**Create & subscribe**
+**Create (async — runs the creation agent)**
+
+`channels create` starts the **same creation-agent pipeline as the web wizard**: it immediately creates the channel in `DRAFT`, then an agent researches the topic, generates the runnable configuration (requirement / sources / schedule) and activates the channel. This usually takes **a few minutes** and consumes credits.
+
+| Command | What it does |
+|---|---|
+| `neodrop channels create --name "<name>" --prompt "<brief>" --locale en` | Start creation; returns the `agentTask` right away (`task.id` + `task.channelId`). |
+| `neodrop channels create --name "<name>" --prompt "<brief>" --wait` | Block until the task reaches a terminal status (polls every 15s, 20min cap). |
+| `neodrop channels create-status <taskId>` | Poll an in-flight creation task. |
+
+| Flag | Purpose |
+|---|---|
+| `--name` (required) | Channel name shown to users. |
+| `--prompt` | Free-form creation instructions for the agent — topic, audience, style, cadence. Strongly recommended; without it the agent only has the name to go on. |
+| `--description` | One-line channel intro (shown on the channel page; not the agent instructions). |
+| `--carrier Article\|ImagePost\|Podcast\|Music\|Video` | Content modality; omit to let the platform default (Article). |
+| `--json '{...}' \| --stdin` | Advanced — raw `agentTask.create` input (`channelName` / `channelDescription` / `description` (= prompt) / `locale` / `contentCarrier`). |
+
+- Task `status`: `PENDING` / `RUNNING` → in progress; `COMPLETED` → done; `FAILED` → failed (exit 1 with `--wait`); `PAUSED` → out of credits, auto-resumes after topping up.
+- New channels default to **PUBLIC** visibility; flip it later on the web manage page.
+- A bare `channel.create` (shell only, stays `DRAFT` forever, no runnable config) is intentionally **not** a sugar command; if you really need it: `api channel.create --json '{"name":"X"}' --mutation`.
+
+**Run (produce one issue now)**
+
+| Command | What it does |
+|---|---|
+| `neodrop channels run <channelId>` | `channel.triggerRun` — manual production run. Requires a runnable config (creation finished; a `DRAFT` with config is auto-activated). Fails with a clear error while creation is still in progress. |
+
+**Subscribe**
 
 | Command | What it does |
 |---|---|
-| `neodrop channels create --name "<name>" --description "<desc>" --locale en` | Create a channel from flags. |
-| `neodrop channels create --json '{"name":"X","locale":"en","type":"PRIVATE"}'` | Create a channel from a full JSON payload. |
 | `neodrop channels subscribe <channelId>` | Subscribe to a channel. |
 | `neodrop channels unsubscribe <channelId>` | Unsubscribe from a channel. |
 
@@ -89,6 +115,7 @@ For tRPC procedures with no sugar command, fall back to `api`:
 
 - **Defaults to a GET query** — every write MUST add `--mutation` explicitly.
 - To find a procedure's full name, check the main repo's `packages/backend/src/api/trpc/routers.ts`, or probe `curl /api/trpc/<router>.<procedure>?input=...` against a dev backend.
+- **Field contracts are strict where it matters**: `channel.update` accepts exactly `{id, name?, description?, avatar?}` and `channel.create` exactly `{name, description?, type?, locale?}` — unknown keys are rejected with `BAD_REQUEST` (they are **not** a way to write channel configuration; the runnable config is owned by the creation agent, see [channels → Create](#channels)). Other procedures may still silently strip unknown keys (standard zod behavior), so don't infer "accepted" from a success response — verify the response body.
 
 ## Global flags
 

package/references/troubleshooting.md

@@ -25,7 +25,9 @@ When the CLI errors, **first read the error code in brackets on stderr**, then m
 | Symptom | Meaning | Fix |
 |---|---|---|
 | `[NOT_FOUND]` | id / slug doesn't exist | List with `channels list` / `posts list` first to verify the id |
-| `[BAD_REQUEST]` | Input schema is wrong (most common with `--json`) | Read the stderr detail; cross-check `neodrop <cmd> --help`; for complex input, get it working with a sugar command first, then drop to `--json` |
+| `[BAD_REQUEST]` | Input schema is wrong (most common with `--json`), including unknown keys on `channel.create` / `channel.update` — those two reject unrecognized fields instead of stripping them | Read the stderr detail; cross-check `neodrop <cmd> --help` and the field contracts in [commands.md#api](commands.md#api); for complex input, get it working with a sugar command first, then drop to `--json` |
+| `[FORBIDDEN]` mentioning credits on `channels create` | Channel creation costs credits and the account balance is insufficient | Ask the user to top up / check in on the web app, then retry |
+| Error saying the channel is still a draft with no runnable config on `channels run` | The channel is a bare `DRAFT` shell — creation never ran or is still in progress | If a creation task exists: poll `channels create-status <taskId>` until `COMPLETED`, then rerun. If the channel was created as a bare shell (old CLI ≤1.x or raw `api channel.create`): create it properly with `channels create --name ... --prompt ...` — a shell can't be activated in place |
 | `[INTERNAL_SERVER_ERROR]` | The backend crashed | Retry once; if it persists, open an issue with the full stderr |
 
 ## Environment