@coderpp/yunxiao-cli 0.1.10 → 0.1.11

package/README.md

@@ -169,7 +169,7 @@ mr release <repositoryName> <sourceBranch> <targetBranch>
 例如，把 `release` 合并到 `master`：
 
 ```bash
-node dist/src/index.js mr release syjc-web release master --yes
+node dist/src/index.js mr release example-web release master --yes
 ```
 
 这个命令会先按仓库名称查询代码库 ID，再用当前 token 对应的用户作为评审人创建合并请求，随后评审通过并合并。合并时固定保留源分支，不会删除源分支。
@@ -177,7 +177,7 @@ node dist/src/index.js mr release syjc-web release master --yes
 如果只想创建合并请求，不自动评审和合并，使用 `--create-only`：
 
 ```bash
-node dist/src/index.js mr release syjc-web release master --yes --create-only
+node dist/src/index.js mr release example-web release master --yes --create-only
 ```
 
 `--create-only` 仍会在云效创建合并请求，所以仍然需要 `--yes`。
@@ -186,13 +186,7 @@ node dist/src/index.js mr release syjc-web release master --yes --create-only
 
 发布版本时，如果云效返回“源分支相对目标分支没有改动，不能新建代码评审”，可视为该仓库无改动并跳过。
 
-发布所有版本时，推荐顺序为：
-
-1. 商混版：`master` -> `gx-concrete/dev`
-2. 蜀道版：`master` -> `sdjt/dev`
-3. 标准版：`master` -> `release`
-
-标准版应最后发布。
+目标分支和多个版本的发布顺序由使用方按自己的项目约定指定。
 
 查询变更文件树：
 
@@ -437,3 +431,25 @@ node dist/src/index.js workitem comment <workitemId> --content "处理完成，
 - `pipeline retry-job`
 - `workitem update`
 - `workitem comment`
+
+## 根据链接读取完整工作项及下载文件
+
+```bash
+npx --yes --package @coderpp/yunxiao-cli yunxiao workitem content "<云效工作项链接>" --dir ./content
+npx --yes --package @coderpp/yunxiao-cli yunxiao workitem content "<云效工作项链接>" --dir ./content --download-attachments
+
+# 单独下载正文及评论图片，或普通附件
+npx --yes --package @coderpp/yunxiao-cli yunxiao workitem images <workitemId> --dir ./images
+npx --yes --package @coderpp/yunxiao-cli yunxiao workitem attachments <workitemId> --dir ./attachments
+```
+
+`content`、`images`、`attachments` 始终输出 JSON。沿用现有 Token、组织、中心版/Region 版配置，
+`content` 校验链接项目位于 `YUNXIAO_PROJECT_IDS` 或 `--project-ids` 配置的范围内。
+`content` 保留全部详情字段和评论原文，`descriptionHtml`、评论 `contentHtml` 的图片引用替换为本地绝对路径；
+`images` 返回 `fileId`、`path`、`source`，支持 HTML、富文本 JSON、Markdown，跨来源重复图片只下载一次。
+普通附件默认仅返回元信息；开启 `--download-attachments` 后返回附件 `path`。
+不返回附件临时签名 URL，下载时不向存储站点传递 Token。
+图片位于 `images/`、普通附件位于 `attachments/`，默认根目录为 `workitem-<ID>-content`。
+已有文件不覆盖，重复读取请选择新目录；失败返回非零退出码，清理未完成文件并保留已完成文件。
+仅支持带 `fileIdentifier` 的云效图片（PNG/JPEG/GIF/WebP/BMP/ICO）；外部图片和 data URL 会报错。
+需要工作项、评论、附件只读权限。完整内容不递归包含关联工作项或历史动态。

package/dist/src/cli.js

@@ -1,7 +1,8 @@
+import { readWorkitemContent, downloadWorkitemImages, downloadWorkitemAttachments, parseWorkitemUrl } from "./workitem-content.js";
 import { YunxiaoClient } from "./client.js";
 const mergeTypes = new Set(["ff-only", "no-fast-forward", "squash", "rebase"]);
 const outputFormats = new Set(["table", "json"]);
-const booleanFlags = new Set(["all-pages", "create-only", "help", "json", "remove-source-branch", "yes"]);
+const booleanFlags = new Set(["download-attachments", "all-pages", "create-only", "help", "json", "remove-source-branch", "yes"]);
 const workitemStateNames = new Map([
     ["todo", ["TODO", "待处理", "待办"]],
     ["opened", ["TODO", "待处理", "待办"]],
@@ -26,7 +27,7 @@ export async function runCli(args = process.argv.slice(2), env = process.env, io
         const outputFormat = outputFormatFromFlags(parsed.flags);
         const client = createClient(parsed.flags, env, io.fetcher);
         const result = await runCommand(scope, command, parsed, client, env);
-        printResult(result, outputFormat, stdout);
+        printResult(result, scope === "workitem" && ["content", "images", "attachments"].includes(command) ? "json" : outputFormat, stdout);
         return 0;
     }
     catch (error) {
@@ -177,6 +178,24 @@ async function runWorkitemCommand(command, parsed, client, env) {
             const currentUser = await client.getCurrentUser();
             return searchWorkitems(client, { ...parsed.flags, "assigned-to": currentUser.id }, env);
         }
+        case "content": {
+            const link = requiredPositional(workitemId, "workitemUrl");
+            const { projectId, workitemId: id } = parseWorkitemUrl(link);
+            if (!workitemProjectIds(parsed.flags, env).includes(projectId))
+                throw new Error("Link project is outside the configured project scope.");
+            return readWorkitemContent(client, link, {
+                dir: optionalString(parsed.flags.dir) ?? `workitem-${id}-content`,
+                downloadAttachments: hasFlag(parsed.flags, "download-attachments")
+            });
+        }
+        case "images":
+            return downloadWorkitemImages(client, requiredPositional(workitemId, "workitemId"), {
+                dir: optionalString(parsed.flags.dir) ?? `workitem-${workitemId}-images`
+            });
+        case "attachments":
+            return downloadWorkitemAttachments(client, requiredPositional(workitemId, "workitemId"), {
+                dir: optionalString(parsed.flags.dir) ?? `workitem-${workitemId}-attachments`
+            });
         case "get":
             return client.getWorkitem(requiredPositional(workitemId, "workitemId"));
         case "update":
@@ -712,6 +731,9 @@ Usage:
   yunxiao workitem list --project-ids p1,p2 [--assigned-to userId] [--created-by userId] [--state todo|doing|done] [--from "2026-04-01 00:00:00"] [--to "2026-04-30 23:59:59"]
   yunxiao workitem mine --project-ids p1,p2 [--state todo|doing|done] [--output table|json]
   yunxiao workitem get <workitemId> [--output table|json]
+  yunxiao workitem content <workitemUrl> [--dir directory] [--download-attachments]
+  yunxiao workitem images <workitemId> [--dir directory]
+  yunxiao workitem attachments <workitemId> [--dir directory]
   yunxiao workitem update <workitemId> --yes [--assigned-to userId] [--participants user1,user2] [--due-date "2026-05-01 18:00:00"] [--field key=value]
   yunxiao workitem activities <workitemId> [--output table|json]
   yunxiao workitem comments <workitemId> [--output table|json]

package/dist/src/client.d.ts

@@ -189,6 +189,8 @@ export declare class YunxiaoClient {
     getMember(memberId: string): Promise<unknown>;
     searchWorkitems(options: SearchWorkitemsOptions): Promise<unknown>;
     getWorkitem(workitemId: string): Promise<unknown>;
+    getWorkitemFile(workitemId: string, fileId: string): Promise<unknown>;
+    listWorkitemAttachments(workitemId: string): Promise<unknown>;
     updateWorkitem(workitemId: string, options: UpdateWorkitemOptions): Promise<unknown>;
     listWorkitemActivities(workitemId: string): Promise<unknown>;
     listWorkitemComments(workitemId: string): Promise<unknown>;

package/dist/src/client.js

@@ -85,6 +85,12 @@ export class YunxiaoClient {
     getWorkitem(workitemId) {
         return this.request("GET", `${this.projexPath("/workitems")}/${encodePathSegment(workitemId)}`);
     }
+    getWorkitemFile(workitemId, fileId) {
+        return this.request("GET", `${this.projexPath("/workitems")}/${encodePathSegment(workitemId)}/files/${encodePathSegment(fileId)}`);
+    }
+    listWorkitemAttachments(workitemId) {
+        return this.request("GET", `${this.projexPath("/workitems")}/${encodePathSegment(workitemId)}/attachments`);
+    }
     updateWorkitem(workitemId, options) {
         return this.request("PUT", `${this.projexPath("/workitems")}/${encodePathSegment(workitemId)}`, undefined, options);
     }

package/dist/src/workitem-content.d.ts

@@ -0,0 +1,27 @@
+import { YunxiaoClient, type Fetcher } from "./client.js";
+type RecordData = Record<string, unknown>;
+type Image = {
+    fileId: string;
+    path: string;
+    source: string;
+};
+export type ContentOptions = {
+    dir: string;
+    downloadAttachments?: boolean;
+    fetcher?: Fetcher;
+};
+export declare function parseWorkitemUrl(link: string): {
+    projectId: string;
+    workitemId: string;
+};
+export declare function downloadWorkitemAttachments(client: YunxiaoClient, id: string, options: ContentOptions): Promise<RecordData[]>;
+export declare function readWorkitemContent(client: YunxiaoClient, link: string, options: ContentOptions): Promise<{
+    url: string;
+    workitem: RecordData;
+    descriptionHtml: string;
+    comments: RecordData[];
+    images: Image[];
+    attachments: RecordData[];
+}>;
+export declare function downloadWorkitemImages(client: YunxiaoClient, id: string, options: ContentOptions): Promise<Image[]>;
+export {};

package/dist/src/workitem-content.js

@@ -0,0 +1,180 @@
+import { mkdir, open, rm } from "node:fs/promises";
+import path from "node:path";
+import { parseFragment, serialize } from "parse5";
+import MarkdownIt from "markdown-it";
+export function parseWorkitemUrl(link) {
+    const u = new URL(link);
+    const parts = u.pathname.replace(/\/$/, "").split("/");
+    if (u.protocol !== "https:" || u.host !== "devops.aliyun.com" || u.username || u.password ||
+        parts.length !== 6 || parts[1] !== "projex" || parts[2] !== "project" || !parts[3] || !parts[4] || !parts[5]) {
+        throw new Error("Expected a Yunxiao workitem URL: https://devops.aliyun.com/projex/project/<projectId>/<type>/<workitemId>");
+    }
+    return { projectId: parts[3], workitemId: parts[5] };
+}
+function record(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Unexpected workitem API response.");
+    return value;
+}
+function records(value) {
+    if (!Array.isArray(value))
+        throw new Error("Expected an API array.");
+    return value.map(record);
+}
+function str(value) { return typeof value === "string" ? value : ""; }
+function markup(content, format) {
+    const text = str(content);
+    if (format === "MARKDOWN")
+        return new MarkdownIt({ html: true }).render(text);
+    if (text.trimStart().startsWith("{")) {
+        const rich = record(JSON.parse(text));
+        if (typeof rich.htmlValue !== "string")
+            throw new Error("Rich text is missing htmlValue.");
+        return rich.htmlValue;
+    }
+    return text;
+}
+function imageExtension(head) {
+    if (head.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+        return ".png";
+    if (head[0] === 255 && head[1] === 216 && head[2] === 255)
+        return ".jpg";
+    if (/^GIF8[79]a/.test(head.toString("ascii", 0, 6)))
+        return ".gif";
+    if (head.toString("ascii", 0, 4) === "RIFF" && head.toString("ascii", 8, 12) === "WEBP")
+        return ".webp";
+    if (head.toString("ascii", 0, 2) === "BM")
+        return ".bmp";
+    if (head.subarray(0, 4).equals(Buffer.from([0, 0, 1, 0])))
+        return ".ico";
+    throw new Error("Download is not a supported image (PNG/JPEG/GIF/WebP/BMP/ICO).");
+}
+async function download(url, target, image, fetcher) {
+    let response;
+    try {
+        response = await fetcher(url, { signal: AbortSignal.timeout(120000) });
+    }
+    catch {
+        throw new Error("File download failed (network error or timeout).");
+    }
+    if (!response.ok || !response.body) {
+        await response.body?.cancel();
+        throw new Error(`File download failed: HTTP ${response.status}.`);
+    }
+    const reader = response.body.getReader();
+    let file;
+    let destination = target;
+    let complete = false;
+    try {
+        const chunks = [];
+        let size = 0;
+        while (size < 16) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            chunks.push(Buffer.from(chunk.value));
+            size += chunk.value.length;
+        }
+        const head = Buffer.concat(chunks);
+        if (image)
+            destination += imageExtension(head);
+        await mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
+        file = await open(destination, "wx", 0o600);
+        await file.writeFile(head);
+        for (;;) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            await file.writeFile(chunk.value);
+        }
+        await file.close();
+        complete = true;
+        return destination;
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            throw new Error(`File already exists; choose a new directory: ${destination}`);
+        // Do not leak signed storage URLs from fetch errors.
+        throw new Error(`Unable to save file ${destination}: download or filesystem error.`);
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+        if (file && !complete) {
+            await file.close();
+            await rm(destination, { force: true });
+        }
+    }
+}
+async function localize(client, id, content, format, source, dir, cache, images, fetcher) {
+    const tree = parseFragment(markup(content, format));
+    async function visit(node) {
+        if ("tagName" in node && node.tagName === "img") {
+            const src = node.attrs.find(a => a.name === "src");
+            const fileId = src && new URL(src.value, "https://devops.aliyun.com").searchParams.get("fileIdentifier");
+            if (!src || !fileId)
+                throw new Error(`${source}: only Yunxiao images with fileIdentifier are supported.`);
+            let local = cache.get(fileId);
+            if (!local) {
+                const file = record(await client.getWorkitemFile(id, fileId));
+                if (!str(file.url))
+                    throw new Error(`Missing download URL for image ${fileId}.`);
+                local = await download(str(file.url), path.resolve(dir, String(cache.size + 1).padStart(2, "0")), true, fetcher);
+                cache.set(fileId, local);
+            }
+            src.value = local;
+            if (!images.some(i => i.fileId === fileId && i.source === source))
+                images.push({ fileId, path: local, source });
+        }
+        if ("childNodes" in node)
+            for (const child of node.childNodes)
+                await visit(child);
+    }
+    await visit(tree);
+    return serialize(tree);
+}
+async function attachments(client, id, options) {
+    const files = records(await client.listWorkitemAttachments(id));
+    for (const [index, file] of files.entries()) {
+        const url = str(file.url);
+        delete file.url;
+        if (!options.downloadAttachments)
+            continue;
+        if (!url)
+            throw new Error(`Missing download URL for attachment ${index + 1}.`);
+        let name = path.posix.basename(str(file.fileName).replaceAll("\\", "/"));
+        if (!name || name === "." || name === "..")
+            name = "attachment";
+        file.path = await download(url, path.resolve(options.dir, `${String(index + 1).padStart(2, "0")}-${name}`), false, options.fetcher ?? fetch);
+    }
+    return files;
+}
+export async function downloadWorkitemAttachments(client, id, options) {
+    return attachments(client, id, { ...options, downloadAttachments: true });
+}
+export async function readWorkitemContent(client, link, options) {
+    const { projectId, workitemId: id } = parseWorkitemUrl(link);
+    const workitem = record(await client.getWorkitem(id));
+    if (workitem.id !== id || record(workitem.space).id !== projectId)
+        throw new Error("Workitem/project does not match the link.");
+    const comments = records(await client.listWorkitemComments(id));
+    const images = [];
+    const cache = new Map();
+    const dir = path.join(options.dir, "images");
+    const fetcher = options.fetcher ?? fetch;
+    const descriptionHtml = await localize(client, id, workitem.description, workitem.formatType, "description", dir, cache, images, fetcher);
+    for (const c of comments)
+        c.contentHtml = await localize(client, id, c.content, c.contentFormat, `comment:${c.id}`, dir, cache, images, fetcher);
+    return { url: link, workitem, descriptionHtml, comments, images,
+        attachments: await attachments(client, id, { ...options, dir: path.join(options.dir, "attachments") }) };
+}
+export async function downloadWorkitemImages(client, id, options) {
+    const workitem = record(await client.getWorkitem(id));
+    const comments = records(await client.listWorkitemComments(id));
+    const images = [];
+    const cache = new Map();
+    const fetcher = options.fetcher ?? fetch;
+    await localize(client, id, workitem.description, workitem.formatType, "description", options.dir, cache, images, fetcher);
+    for (const c of comments)
+        await localize(client, id, c.content, c.contentFormat, `comment:${c.id}`, options.dir, cache, images, fetcher);
+    return images;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coderpp/yunxiao-cli",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "A CLI for Yunxiao merge request, pipeline retry, project member, and workitem workflows.",
   "type": "module",
   "repository": {
@@ -29,6 +29,7 @@
     "access": "public"
   },
   "devDependencies": {
+    "@types/markdown-it": "^14.2.0",
     "@types/node": "^20.12.12",
     "typescript": "^5.4.5"
   },
@@ -38,5 +39,9 @@
   "files": [
     "dist/src",
     "README.md"
-  ]
+  ],
+  "dependencies": {
+    "markdown-it": "^14.3.3",
+    "parse5": "^7.3.0"
+  }
 }