@xihe-lab/tapd-core 2.0.0-rc.1 → 2.0.0-rc.3

package/dist/richtext/pipeline.js

@@ -0,0 +1,199 @@
+// TAPD 2.0 rc.2 P3 接线（需求 1139814312001001548）—— 富文本保真转换主管道。
+//
+// B 侧语义库（core/richtext，纯函数）在转换器「token / 规则级」接入（B 的接线警告）：
+//   - md→html（markdown-it core 规则，token 级）：
+//       * `attach:` 链接（link_open..link_close 纯文本运行）→ 整段替换为 R6 data 五件套锚点
+//         （html_inline token；html:false 只影响解析不影响程序化 token 的渲染）；
+//       * `@昵称` / `@@` 语义只在 inline children 的 **text token** 内替换（mention/escape 各自成 token）；
+//       * code_inline / fence / html_* / image（含 alt）/ 链接内部（含 URL）一律跳过；
+//         裸 URL（https://.../@name）内的 @ 由「连续非空白段含 ://」护栏跳过。
+//       * 禁止对整段输入直接调 fragment 级函数上线（会误伤代码段与 URL）——本模块即正确接线层。
+//   - html→md（turndown 规则级）：
+//       * at-who <b> → `@昵称`（永不降级 **粗体**，R7）；附件锚点 <a> → `[📎 name](attach:ws/id)`；
+//         识别失败（href 缺失等）保留原节点 HTML，绝不猜测改写。
+//       * 保真规则先于 GFM 注册（FSD §8）：turndown addRule 为 unshift 语义（后注册者先匹配），
+//         故在 use(gfm) 之后再 addRule 即获得最高匹配优先级，并有规则优先级测试固化。
+//       * 文本节点字面 @ 保护走 turndown 实例 escape 钩子（escapeAtLiteralsForMd；
+//         CODE 内文本 isCode 天然绕过 escape，代码段 @ 不被加倍）。
+//
+// 单一实例共享给 md_to_html/html_to_md 工具（tools/utility.ts）与写管道
+// （registry/richtext.ts 的 transformWriteArgs/transformReadData）——FSD §3.7：
+// 所有富文本写工具与 pm 层场景共用同一条管道，免费获得 @/附件/图片能力。
+import MarkdownIt from 'markdown-it';
+import TurndownService from 'turndown';
+import { gfm } from 'turndown-plugin-gfm';
+import { attachmentAnchorHtml, attachmentAnchorNodeToMd, atWhoNodeToMd, escapeAtLiteralsForMd, findMentions, isAttachmentAnchorNode, isAtWhoNode, renderMentionHtml, } from './index.js';
+// ---------------------------------------------------------------------------
+// md → html（markdown-it，token 级）
+// ---------------------------------------------------------------------------
+/** `attach:<ws>/<id>`（与 richtext md 扩展语法的 ws/id 文法一致：排除空白、()、/）。 */
+const ATTACH_HREF_RE = /^attach:([^()\s/]+)\/([^()\s/]+)$/i;
+/**
+ * 裸 URL 防误伤：mention 候选往前回溯同一连续非空白段，段内含 `://` 视为 URL 的一部分
+ * （如 `https://e.com/@zhang`）。md 链接语法 `[t](url)` 的 URL 在 token attrs 里天然不进本层。
+ */
+function insideBareUrl(content, atIndex) {
+    let start = atIndex;
+    while (start > 0 && !/\s/.test(content[start - 1]))
+        start -= 1;
+    return content.slice(start, atIndex).includes('://');
+}
+/**
+ * 把一个 text token 的内容按 @ 语义拆分为 [text | html_inline] 串
+ * （镜像 richtext scanAtTokens 规则：@@ 优先、findMentions 已内建左边界判定）。
+ * 无任何语义变化时返回 null（调用方保留原 token，避免无谓重排）。
+ */
+function splitTextTokenAtSemantics(TokenCtor, token) {
+    const content = token.content;
+    const mentions = findMentions(content);
+    if (mentions.length === 0 && !content.includes('@@'))
+        return null;
+    const mentionByStart = new Map(mentions.map(m => [m.start, m]));
+    const out = [];
+    let plain = '';
+    const flush = () => {
+        if (plain === '')
+            return;
+        const text = new TokenCtor('text', '', 0);
+        text.content = plain;
+        out.push(text);
+        plain = '';
+    };
+    let i = 0;
+    let changed = false;
+    while (i < content.length) {
+        if (content[i] === '@') {
+            if (content[i + 1] === '@') {
+                plain += '@'; // md 转义 @@ → 字面 @
+                changed = true;
+                i += 2;
+                continue;
+            }
+            const mention = mentionByStart.get(i);
+            if (mention && !insideBareUrl(content, i)) {
+                flush();
+                const html = new TokenCtor('html_inline', '', 0);
+                html.content = renderMentionHtml(mention.name);
+                out.push(html);
+                changed = true;
+                i = mention.end;
+                continue;
+            }
+        }
+        plain += content[i];
+        i += 1;
+    }
+    flush();
+    if (!changed || (out.length === 1 && out[0].type === 'text' && out[0].content === content))
+        return null;
+    return out;
+}
+/** inline children 内的 `attach:` 链接 → R6 锚点（整段替换为单个 html_inline token）。 */
+function convertAttachmentLinks(TokenCtor, tokens) {
+    for (let i = 0; i < tokens.length; i++) {
+        const open = tokens[i];
+        if (open.type !== 'link_open')
+            continue;
+        const href = String(open.attrGet('href') ?? '');
+        const refMatch = ATTACH_HREF_RE.exec(href.trim());
+        if (!refMatch)
+            continue;
+        // link_open..link_close 之间必须是纯文本运行（含嵌套/换行则保守跳过，保留原链接）
+        let text = '';
+        let closeIdx = -1;
+        for (let j = i + 1; j < tokens.length; j++) {
+            const t = tokens[j];
+            if (t.type === 'link_close') {
+                closeIdx = j;
+                break;
+            }
+            if (t.type !== 'text')
+                break;
+            text += t.content;
+        }
+        if (closeIdx < 0)
+            continue;
+        const name = text.replace(/^\s*📎\s*/, '');
+        if (name === '')
+            continue;
+        let anchor;
+        try {
+            anchor = attachmentAnchorHtml({ workspaceId: refMatch[1], id: refMatch[2], name });
+        }
+        catch {
+            continue; // ws/id 含空白或非法字符 → 原样保留（绝不猜测改写）
+        }
+        const htmlToken = new TokenCtor('html_inline', '', 0);
+        htmlToken.content = anchor;
+        tokens.splice(i, closeIdx - i + 1, htmlToken);
+    }
+}
+/** inline children 内 text token 的 @ 语义替换（链接内部跳过；code/html/image token 天然跳过）。 */
+function convertMentions(TokenCtor, tokens) {
+    let linkDepth = 0;
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token.type === 'link_open') {
+            linkDepth += 1;
+            continue;
+        }
+        if (token.type === 'link_close') {
+            linkDepth = Math.max(0, linkDepth - 1);
+            continue;
+        }
+        if (linkDepth > 0)
+            continue; // 链接文本内 @ 不转换（URL 已天然不在 text token）
+        if (token.type !== 'text')
+            continue;
+        const replacement = splitTextTokenAtSemantics(TokenCtor, token);
+        if (replacement) {
+            tokens.splice(i, 1, ...replacement);
+            i += replacement.length - 1;
+        }
+    }
+}
+function tapdRichtextCoreRule(state) {
+    const TokenCtor = state.Token;
+    for (const token of state.tokens) {
+        // fence/code_block/html_block 等 block token 内容不经过 inline 层，天然跳过
+        if (token.type !== 'inline' || !token.children)
+            continue;
+        convertAttachmentLinks(TokenCtor, token.children);
+        convertMentions(TokenCtor, token.children);
+    }
+}
+const markdownIt = new MarkdownIt({ html: false, breaks: true });
+// push 到 core 链尾（text_join 之后）：不再有规则会合并/重排我们的 token 切分
+markdownIt.core.ruler.push('tapd_richtext_semantics', tapdRichtextCoreRule);
+/** md → TAPD 富文本 html（@昵称/@@转义/attach: 附件引用/图片与普通 md 全兼容）。 */
+export function mdToHtml(md) {
+    return markdownIt.render(md);
+}
+// ---------------------------------------------------------------------------
+// html → md（turndown，规则级）
+// ---------------------------------------------------------------------------
+const turndown = new TurndownService({ headingStyle: 'atx', codeBlockStyle: 'fenced' });
+turndown.use(gfm);
+// 保真规则先于 GFM/内建规则匹配：addRule 是 unshift 语义（后注册者先匹配），
+// 在 use(gfm) 之后注册即拿到最高优先级（FSD §8，规则优先级由测试固化）。
+turndown.addRule('tapdAtWho', {
+    filter: node => isAtWhoNode(node),
+    replacement: (_content, node) => atWhoNodeToMd(node),
+});
+turndown.addRule('tapdAttachmentAnchor', {
+    filter: node => isAttachmentAnchorNode(node),
+    replacement: (_content, node) => {
+        const md = attachmentAnchorNodeToMd(node);
+        // 识别条件不满足（缺 href 等）→ 保留原节点 HTML，绝不猜测改写
+        return md ?? node.outerHTML ?? '';
+    },
+});
+// 文本节点字面 @ 保护（round-trip 稳定：命中 mention 规则的 @名字 加倍为 @@名字）。
+// CODE 内文本 isCode 天然绕过 escape 钩子（turndown process 分支），代码段 @ 不被加倍。
+const baseEscape = TurndownService.prototype.escape.bind(TurndownService.prototype);
+turndown.escape = (text) => baseEscape(escapeAtLiteralsForMd(text));
+/** TAPD 富文本 html → md（at-who → @昵称、附件锚点 → attach: 引用、/tfl/ 图片走 GFM 内建规则）。 */
+export function htmlToMd(html) {
+    return turndown.turndown(html);
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/richtext/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../../src/richtext/pipeline.ts"],"names":[],"mappings":"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"}

package/dist/richtext/round-trip.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=round-trip.test.d.ts.map

package/dist/richtext/round-trip.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"round-trip.test.d.ts","sourceRoot":"","sources":["../../src/richtext/round-trip.test.ts"],"names":[],"mappings":""}

package/dist/richtext/round-trip.test.js

@@ -0,0 +1,105 @@
+// round-trip 契约测试：六类样本（@/附件/链接/图片/混合/纯文本）md→html→md 与原文等价（空白规约内）。
+// 只覆盖纯函数语义层（本目录 fragment 函数），不经过工具/注册表转换主链路（接线归 Wave 2）。
+import assert from 'node:assert/strict';
+import { htmlToMdFragment, mdToHtmlFragment } from './index.js';
+const WS = '39814312';
+const AT = (name) => `<b class="at-who" contenteditable="false" data-userid="${name}" data-type="user">@${name}</b>`;
+const ANCHOR = (id, name, fileType) => `<a data-is-tapd-attachment="true" data-can-preview="true" data-file-type="${fileType}" ` +
+    `data-name="${name}" target="_blank" rel="noopener" ` +
+    `href="/${WS}/attachments/preview_attachments/${id}/story_description_attachment">${name}</a>`;
+// 空白规约：允许转换层的空白差异（本层本不应产生，防御性归一）
+const normalize = (value) => value.replace(/\s+/g, ' ').trim();
+const SAMPLES = [
+    {
+        name: '样本1 @（中英文昵称、CJK 标点边界）',
+        md: '请 @徐昭 今天内确认，备份联系 @bob_dev。',
+        html: `请 ${AT('徐昭')} 今天内确认，备份联系 ${AT('bob_dev')}。`,
+    },
+    {
+        name: '样本2 附件（pdf/text/other 映射）',
+        md: `评审材料 [📎 接口设计.pdf](attach:${WS}/1139814312001000001)，日志 [📎 app.log](attach:${WS}/1139814312001000002)`,
+        html: `评审材料 ${ANCHOR('1139814312001000001', '接口设计.pdf', 'pdf')}，日志 ${ANCHOR('1139814312001000002', 'app.log', 'other')}`,
+    },
+    {
+        name: '样本3 链接（语义层零干预透传，基础转换器职责）',
+        md: `需求详情见 [TAPD 1139814312001001548](https://www.tapd.cn/${WS}/prong/stories/view/1139814312001001548)`,
+        html: `需求详情见 [TAPD 1139814312001001548](https://www.tapd.cn/${WS}/prong/stories/view/1139814312001001548)`,
+    },
+    {
+        name: '样本4 图片（/tfl/ 远端路径，语义层零干预透传）',
+        md: '效果图 ![登录页](/tfl/captures/2026/09/login.png)',
+        html: '效果图 ![登录页](/tfl/captures/2026/09/login.png)',
+    },
+    {
+        name: '样本5 混合（@ + @@转义 + 附件@名 + 图片 + 链接 + 粗体）',
+        md: [
+            '# rc.2 评审',
+            '',
+            '负责人 @徐昭，抄送 @@everyone（字面量）。',
+            `材料 [📎 报表@v2.txt](attach:${WS}/1139814312001000003)，截图 ![首页](/tfl/a.png)。`,
+            `线索 [需求](https://www.tapd.cn/${WS}/prong/stories/view/1139814312001001548) 与 **加粗**。`,
+        ].join('\n'),
+        html: [
+            '# rc.2 评审',
+            '',
+            `负责人 ${AT('徐昭')}，抄送 @everyone（字面量）。`,
+            `材料 ${ANCHOR('1139814312001000003', '报表@v2.txt', 'text')}，截图 ![首页](/tfl/a.png)。`,
+            `线索 [需求](https://www.tapd.cn/${WS}/prong/stories/view/1139814312001001548) 与 **加粗**。`,
+        ].join('\n'),
+    },
+    {
+        name: '样本6 纯文本（邮箱/工单号/孤立 @ 不误伤，@@转义不触发 mention，FSD §8）',
+        md: '版本 v1.2 已发布。联系邮箱 user@example.com；工单号 T-100@QA 由 support@test 处理；单独的 @ 保持原样，转义 @@support 也不触发 mention。',
+        html: '版本 v1.2 已发布。联系邮箱 user@example.com；工单号 T-100@QA 由 support@test 处理；单独的 @ 保持原样，转义 @support 也不触发 mention。',
+    },
+];
+const checks = [
+    ...SAMPLES.map((sample) => [
+        `md→html: ${sample.name}`,
+        () => {
+            assert.equal(normalize(mdToHtmlFragment(sample.md)), normalize(sample.html));
+        },
+    ]),
+    ...SAMPLES.map((sample) => [
+        `html→md: ${sample.name}`,
+        () => {
+            assert.equal(normalize(htmlToMdFragment(sample.html)), normalize(sample.md));
+        },
+    ]),
+    ...SAMPLES.map((sample) => [
+        `round-trip: ${sample.name}`,
+        () => {
+            assert.equal(normalize(htmlToMdFragment(mdToHtmlFragment(sample.md))), normalize(sample.md));
+            // 二次往返幂等（转换稳定点）
+            const once = htmlToMdFragment(mdToHtmlFragment(sample.md));
+            assert.equal(normalize(htmlToMdFragment(mdToHtmlFragment(once))), normalize(once));
+        },
+    ]),
+    ['R7 回归: @昵称 产出 at-who 标记而非降级形态', () => {
+            const html = mdToHtmlFragment('呼叫 @徐昭');
+            assert.ok(html.includes('<b class="at-who" contenteditable="false" data-userid="徐昭" data-type="user">@徐昭</b>'));
+            const md = htmlToMdFragment('<p><b class="at-who" contenteditable="false" data-userid="徐昭" data-type="user">@徐昭</b></p>');
+            assert.equal(md, '<p>@徐昭</p>');
+            assert.ok(!md.includes('**'));
+        }],
+];
+let failed = 0;
+for (const [name, check] of checks) {
+    try {
+        check();
+        console.log(`PASS ${name}`);
+    }
+    catch (error) {
+        failed += 1;
+        console.error(`FAIL ${name}`);
+        console.error(`  ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+if (failed > 0) {
+    console.error(`\n${failed}/${checks.length} failed`);
+    process.exitCode = 1;
+}
+else {
+    console.log(`\n${checks.length}/${checks.length} passed`);
+}
+//# sourceMappingURL=round-trip.test.js.map

package/dist/richtext/round-trip.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"round-trip.test.js","sourceRoot":"","sources":["../../src/richtext/round-trip.test.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,yDAAyD;AACzD,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEhE,MAAM,EAAE,GAAG,UAAU,CAAC;AAEtB,MAAM,EAAE,GAAG,CAAC,IAAY,EAAE,EAAE,CAC1B,0DAA0D,IAAI,uBAAuB,IAAI,MAAM,CAAC;AAClG,MAAM,MAAM,GAAG,CAAC,EAAU,EAAE,IAAY,EAAE,QAAgB,EAAE,EAAE,CAC5D,6EAA6E,QAAQ,IAAI;IACzF,cAAc,IAAI,mCAAmC;IACrD,UAAU,EAAE,oCAAoC,EAAE,kCAAkC,IAAI,MAAM,CAAC;AAEjG,iCAAiC;AACjC,MAAM,SAAS,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AAQvE,MAAM,OAAO,GAAa;IACxB;QACE,IAAI,EAAE,uBAAuB;QAC7B,EAAE,EAAE,4BAA4B;QAChC,IAAI,EAAE,KAAK,EAAE,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC,SAAS,CAAC,GAAG;KACnD;IACD;QACE,IAAI,EAAE,2BAA2B;QACjC,EAAE,EAAE,6BAA6B,EAAE,gDAAgD,EAAE,uBAAuB;QAC5G,IAAI,EAAE,QAAQ,MAAM,CAAC,qBAAqB,EAAE,UAAU,EAAE,KAAK,CAAC,OAAO,MAAM,CAAC,qBAAqB,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE;KACzH;IACD;QACE,IAAI,EAAE,0BAA0B;QAChC,EAAE,EAAE,wDAAwD,EAAE,0CAA0C;QACxG,IAAI,EAAE,wDAAwD,EAAE,0CAA0C;KAC3G;IACD;QACE,IAAI,EAAE,6BAA6B;QACnC,EAAE,EAAE,6CAA6C;QACjD,IAAI,EAAE,6CAA6C;KACpD;IACD;QACE,IAAI,EAAE,wCAAwC;QAC9C,EAAE,EAAE;YACF,WAAW;YACX,EAAE;YACF,6BAA6B;YAC7B,4BAA4B,EAAE,6CAA6C;YAC3E,+BAA+B,EAAE,oDAAoD;SACtF,CAAC,IAAI,CAAC,IAAI,CAAC;QACZ,IAAI,EAAE;YACJ,WAAW;YACX,EAAE;YACF,OAAO,EAAE,CAAC,IAAI,CAAC,qBAAqB;YACpC,MAAM,MAAM,CAAC,qBAAqB,EAAE,WAAW,EAAE,MAAM,CAAC,wBAAwB;YAChF,+BAA+B,EAAE,oDAAoD;SACtF,CAAC,IAAI,CAAC,IAAI,CAAC;KACb;IACD;QACE,IAAI,EAAE,iDAAiD;QACvD,EAAE,EAAE,wGAAwG;QAC5G,IAAI,EAAE,uGAAuG;KAC9G;CACF,CAAC;AAEF,MAAM,MAAM,GAA2B;IACrC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;QACzB,YAAY,MAAM,CAAC,IAAI,EAAE;QACzB,GAAG,EAAE;YACH,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QAC/E,CAAC;KACsB,CAAC;IAC1B,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;QACzB,YAAY,MAAM,CAAC,IAAI,EAAE;QACzB,GAAG,EAAE;YACH,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,gBAAgB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;QAC/E,CAAC;KACsB,CAAC;IAC1B,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;QACzB,eAAe,MAAM,CAAC,IAAI,EAAE;QAC5B,GAAG,EAAE;YACH,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,gBAAgB,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;YAC7F,gBAAgB;YAChB,MAAM,IAAI,GAAG,gBAAgB,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;YAC3D,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,gBAAgB,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;QACrF,CAAC;KACsB,CAAC;IAC1B,CAAC,+BAA+B,EAAE,GAAG,EAAE;YACrC,MAAM,IAAI,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;YACxC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,qFAAqF,CAAC,CAAC,CAAC;YAChH,MAAM,EAAE,GAAG,gBAAgB,CAAC,4FAA4F,CAAC,CAAC;YAC1H,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC;YAC/B,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;QAChC,CAAC,CAAC;CACH,CAAC;AAEF,IAAI,MAAM,GAAG,CAAC,CAAC;AACf,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;IACnC,IAAI,CAAC;QACH,KAAK,EAAE,CAAC;QACR,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,CAAC,CAAC;QACZ,OAAO,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;QAC9B,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC/E,CAAC;AACH,CAAC;AAED,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;IACf,OAAO,CAAC,KAAK,CAAC,KAAK,MAAM,IAAI,MAAM,CAAC,MAAM,SAAS,CAAC,CAAC;IACrD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC;KAAM,CAAC;IACN,OAAO,CAAC,GAAG,CAAC,KAAK,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,SAAS,CAAC,CAAC;AAC5D,CAAC"}

package/dist/sdk-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sdk-routes.d.ts","sourceRoot":"","sources":["../src/sdk-routes.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,GAAG,KAAK,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAgLxD,CAAC"}
+{"version":3,"file":"sdk-routes.d.ts","sourceRoot":"","sources":["../src/sdk-routes.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,GAAG,KAAK,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAqLxD,CAAC"}

package/dist/sdk-routes.js

@@ -8,6 +8,10 @@ export const SDK_ROUTES = {
     // attachments
     'GET /attachments': 'getAttachments',
     'GET /attachments/down': 'downloadAttachment',
+    'POST /open_app_obj_attachment': 'addOpenAppObjAttachment',
+    // files (upload channel — multipart via TapdClient.postFile)
+    'POST /files/upload_attachment': 'uploadAttachment',
+    'POST /files/upload_image': 'uploadImage',
     // board-cards
     'GET /board_cards': 'getBoardCards',
     // board-columns

package/dist/sdk-routes.js.map

@@ -1 +1 @@
-{"version":3,"file":"sdk-routes.js","sourceRoot":"","sources":["../src/sdk-routes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sdk-routes.js","sourceRoot":"","sources":["../src/sdk-routes.ts"],"names":[],"mappings":"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"}

package/dist/tapd-client.d.ts

@@ -1,3 +1,30 @@
+/**
+ * TAPD API Client
+ *
+ * Supports dual authentication modes:
+ * - Basic Auth: using api_user + api_password
+ * - OAuth/Bearer Token: using access_token
+ *
+ * Routes requests through @opentapd/tapd-node-sdk when the method+path is
+ * listed in SDK_ROUTES, otherwise falls back to the custom fetch client.
+ * - GET SDK failures fall back to fetch (read-only, idempotent)
+ * - POST SDK failures throw directly (never fallback, avoid duplicate writes)
+ * - Set TAPD_SDK_DISABLED=1 to bypass the SDK entirely (rollback switch)
+ *
+ * GET 通道前置只读数据 TTL 缓存（cache/read-cache.ts）：仅 allowlist 内低频端点
+ * （workitem_types / workflow / 成员 / 自定义字段配置 / settings 系 / 分类 / 角色）
+ * 参与缓存（TTL + LRU + in-flight 去重 + 深拷贝返回），其余请求一律直连。
+ * TAPD_CACHE=off 关闭；TAPD_CACHE_DEBUG=1 打命中日志；失效用 invalidateCache()。
+ */
+import { ReadStream } from 'node:fs';
+/**
+ * A param value accepted by the multipart upload channel (TapdClient.postFile).
+ * The file itself MUST be an fs.ReadStream (i.e. fs.createReadStream):
+ * the SDK only switches to multipart/form-data for ReadStream/FILE values
+ * (node-sdk/src/sdk.js:159) — Buffers / Readable.from() silently degrade to
+ * plain form fields.
+ */
+export type FileUploadParam = string | number | boolean | undefined | ReadStream;
 export declare class TapdClient {
     private authHeader;
     private baseUrl;
@@ -8,6 +35,15 @@ export declare class TapdClient {
     private sdk?;
     private readonly sdkEnabled;
     private readonly verbose;
+    /**
+     * GET 重试指数退避基数（毫秒）：延迟 = base * 2^attempt（1s, 2s, 4s）。
+     * 公开静态以便测试注入小值加速、运维按需调参；429 携带 Retry-After 时优先采用其值（上限 30s）。
+     */
+    static retryBackoffBaseMs: number;
+    private static readonly MAX_RETRIES;
+    private static readonly RETRYABLE_STATUS;
+    /** Retry-After 退避上限：避免服务端给出超长等待时占死工具超时预算（原始值仍透出在错误详情）。 */
+    private static readonly RETRY_AFTER_CAP_MS;
     private constructor();
     /**
      * Create client from OAuth access token
@@ -74,11 +110,29 @@ export declare class TapdClient {
      */
     private getSdk;
     /**
-     * Route a request through the SDK when the method+path is mapped,
-     * otherwise (and on read-only SDK failure) through the fetch client.
+     * 请求入口：GET 先过只读缓存门面（allowlist 内端点命中即返，未命中并发去重），
+     * 再走 SDK/fetch 网络通道；POST 与 multipart 不参与缓存，直连网络通道。
+     * 返回值形态与直连完全一致（命中为深拷贝，防消费方 mutate 污染缓存）。
      */
     private route;
+    /**
+     * Network channel: route a request through the SDK when the method+path is
+     * mapped, otherwise (and on read-only SDK failure) through the fetch client.
+     */
+    private routeNetwork;
+    /**
+     * Make HTTP request to TAPD API with retry support
+     *
+     * Retry policy:
+     * - Retry on 429/500/502/503 status codes and network-level failures
+     * - Max 3 retries with exponential backoff (1s, 2s, 4s); 429 的 Retry-After 优先（上限 30s）
+     * - POST requests do NOT retry (avoid duplicate creation)
+     * - 非 2xx 的确定性错误（400/401/403/404...）立即抛出，不做无谓重试
+     * - 所有错误统一抛 TapdError（结构化详情见 errors/index.ts）
+     */
     request<T>(method: 'GET' | 'POST', path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    /** 单次重试等待：429 的 Retry-After 优先（封顶 30s），否则指数退避 base * 2^attempt。 */
+    private retryDelayMs;
     /**
      * GET request to TAPD API
      */
@@ -87,6 +141,29 @@ export declare class TapdClient {
      * POST request to TAPD API
      */
     post<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    /**
+     * POST a multipart (file upload) request — the streaming channel for upload
+     * endpoints (`/files/upload_attachment`, `/files/upload_image`, ...).
+     *
+     * Keeps registry.exec the single execution path (FSD §2 ruling: streaming
+     * calls never bypass TapdClient, so audit / timeout / read-only gating and
+     * auth stay unified).
+     *
+     * Routing mirrors route() POST semantics:
+     * - When `POST <path>` is mapped in SDK_ROUTES and the SDK is enabled, the
+     *   request goes through the SDK, which builds multipart/form-data when any
+     *   param value is an fs.ReadStream (node-sdk/src/sdk.js:159).
+     * - POST failures throw directly (never fall back / retry — a flaky network
+     *   must not duplicate an upload).
+     * - Without an SDK route (or with TAPD_SDK_DISABLED=1 rollback switch on),
+     *   falls back to a fetch-based multipart upload (Node 20+ global FormData).
+     */
+    postFile<T>(path: string, params: Record<string, FileUploadParam>): Promise<T>;
+    /**
+     * fetch-based multipart fallback (no SDK route / SDK disabled). Node 20+
+     * global fetch serializes FormData bodies (boundary included) automatically.
+     */
+    private postMultipartViaFetch;
 }
 /**
  * TAPD API response structure

package/dist/tapd-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tapd-client.d.ts","sourceRoot":"","sources":["../src/tapd-client.ts"],"names":[],"mappings":"AAgBA,qBAAa,UAAU;IACrB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAoB;IACpC,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,WAAW,CAAC,CAAS;IAC7B,OAAO,CAAC,WAAW,CAAC,CAAS;IAC7B,OAAO,CAAC,GAAG,CAAC,CAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyC;IACpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;IAEhE,OAAO;IAgBP;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU;IAIzE;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU;IAWxF;;;OAGG;IACH,MAAM,CAAC,OAAO,IAAI,UAAU;IAmB5B;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,MAAM,GAAG,SAAS;IAIxC;;OAEG;IACH,MAAM,CAAC,qBAAqB,IAAI,MAAM,GAAG,SAAS;IAKlD;;OAEG;IACH,MAAM,CAAC,6BAA6B,IAAI,MAAM,GAAG,SAAS;IAI1D;;OAEG;IACH,MAAM,CAAC,4BAA4B,IAAI,MAAM,GAAG,SAAS;IAIzD;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,UAAO,GAAG,MAAM;IAc1F;;;;;;;KAOC;IACD;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IAe3B,OAAO,CAAC,MAAM;IAQd;;;;OAIG;IACH,OAAO,CAAC,MAAM;IAOd;;;OAGG;YACW,KAAK;IAyBb,OAAO,CAAC,CAAC,EACb,MAAM,EAAE,KAAK,GAAG,MAAM,EACtB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,GAC7D,OAAO,CAAC,CAAC,CAAC;IAwEb;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAI1F;;OAEG;IACG,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAGxG;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,CAAC,CAAC;IACR,IAAI,EAAE,MAAM,CAAC;CACd"}
+{"version":3,"file":"tapd-client.d.ts","sourceRoot":"","sources":["../src/tapd-client.ts"],"names":[],"mappings":"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"}