From 7af6dda9cca9c74034cc95c5edd744eeec1a5afd Mon Sep 17 00:00:00 2001
From: claude-code-best <claude-code-best@proton.me>
Date: Thu, 9 Jul 2026 10:36:33 +0800
Subject: [PATCH 1/2] =?UTF-8?q?feat:=20artifact=20=E5=B7=A5=E5=85=B7?=
 =?UTF-8?q?=E6=94=AF=E6=8C=81=20Markdown=20=E4=B8=8A=E4=BC=A0=E3=80=81?=
 =?UTF-8?q?=E4=BB=A3=E7=A0=81=E9=AB=98=E4=BA=AE=E4=B8=8E=20mermaid?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

按扩展名分发：.md/.markdown 用 marked 转 HTML 后上传，.html/.htm 直传，
其他返回错误。转换产物通过 unpkg CDN 引入 highlight.js (github 主题) 和
mermaid v11，初始化脚本先把 language-mermaid 块提升为 <div class="mermaid">
避免被 highlight.js 当 JS 误染，再初始化 mermaid，最后 hljs.highlightAll()。
后端 Worker 不变，仍只接 text/html，转换在前端工具内完成。

Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win>
---
 bun.lock                                      |   1 +
 packages/builtin-tools/package.json           |   3 +-
 .../src/tools/ArtifactTool/ArtifactTool.ts    |  28 ++-
 .../__tests__/ArtifactTool.test.ts            |  52 +++++
 .../ArtifactTool/__tests__/markdown.test.ts   |  88 +++++++++
 .../ArtifactTool/examples/full-feature.md     | 178 ++++++++++++++++++
 .../src/tools/ArtifactTool/markdown.ts        |  98 ++++++++++
 .../src/tools/ArtifactTool/prompt.ts          |  10 +-
 src/skills/bundled/useArtifacts.ts            |  35 +++-
 9 files changed, 479 insertions(+), 14 deletions(-)
 create mode 100644 packages/builtin-tools/src/tools/ArtifactTool/__tests__/markdown.test.ts
 create mode 100644 packages/builtin-tools/src/tools/ArtifactTool/examples/full-feature.md
 create mode 100644 packages/builtin-tools/src/tools/ArtifactTool/markdown.ts

diff --git a/bun.lock b/bun.lock
index bd57bddb1d..0f238022a5 100644
--- a/bun.lock
+++ b/bun.lock
@@ -237,6 +237,7 @@
       "version": "1.0.0",
       "dependencies": {
         "@claude-code-best/agent-tools": "workspace:*",
+        "marked": "^17.0.6",
       },
     },
     "packages/cloud-artifacts": {
diff --git a/packages/builtin-tools/package.json b/packages/builtin-tools/package.json
index 88dac6d49a..dec40e5330 100644
--- a/packages/builtin-tools/package.json
+++ b/packages/builtin-tools/package.json
@@ -11,6 +11,7 @@
     "./utils": "./src/utils.ts"
   },
   "dependencies": {
-    "@claude-code-best/agent-tools": "workspace:*"
+    "@claude-code-best/agent-tools": "workspace:*",
+    "marked": "^17.0.6"
   }
 }
diff --git a/packages/builtin-tools/src/tools/ArtifactTool/ArtifactTool.ts b/packages/builtin-tools/src/tools/ArtifactTool/ArtifactTool.ts
index f3c2604598..3114287b54 100644
--- a/packages/builtin-tools/src/tools/ArtifactTool/ArtifactTool.ts
+++ b/packages/builtin-tools/src/tools/ArtifactTool/ArtifactTool.ts
@@ -10,13 +10,16 @@ import {
 } from './prompt.js'
 import { getArtifactsToken, getUploadUrl } from './config.js'
 import { uploadArtifact } from './client.js'
+import { markdownToHtml } from './markdown.js'
 import { renderToolResultMessage } from './UI.js'
 
 const inputSchema = lazySchema(() =>
   z.strictObject({
     file_path: z
       .string()
-      .describe('Absolute path to a local HTML file to upload.'),
+      .describe(
+        'Absolute path to a local HTML (.html/.htm) or Markdown (.md/.markdown) file to upload. Markdown is converted to styled HTML before upload.',
+      ),
     hash: z
       .string()
       .regex(/^[A-Za-z0-9_-]{1,128}$/, 'must match ^[A-Za-z0-9_-]{1,128}$')
@@ -47,7 +50,7 @@ export type ArtifactOutput = z.infer<OutputSchema>
 export const ArtifactTool = buildTool({
   name: ARTIFACT_TOOL_NAME,
   searchHint:
-    'upload html artifact share url cloud publish progress report public link',
+    'upload html markdown artifact share url cloud publish progress report public link',
   maxResultSizeChars: 2_000,
   shouldDefer: true,
   strict: true,
@@ -146,9 +149,9 @@ export const ArtifactTool = buildTool({
       }
     }
 
-    let html: string
+    let rawContent: string
     try {
-      html = await readFile(file_path, 'utf8')
+      rawContent = await readFile(file_path, 'utf8')
     } catch {
       return {
         data: {
@@ -160,6 +163,23 @@ export const ArtifactTool = buildTool({
       }
     }
 
+    const lowerPath = file_path.toLowerCase()
+    let html: string
+    if (lowerPath.endsWith('.html') || lowerPath.endsWith('.htm')) {
+      html = rawContent
+    } else if (lowerPath.endsWith('.md') || lowerPath.endsWith('.markdown')) {
+      html = markdownToHtml(rawContent, file_path)
+    } else {
+      return {
+        data: {
+          id: '',
+          url: '',
+          expiresAt: '',
+          error: `Unsupported file extension. Accepted: .html, .htm, .md, .markdown — got: ${file_path}`,
+        },
+      }
+    }
+
     try {
       const result = await uploadArtifact({
         html,
diff --git a/packages/builtin-tools/src/tools/ArtifactTool/__tests__/ArtifactTool.test.ts b/packages/builtin-tools/src/tools/ArtifactTool/__tests__/ArtifactTool.test.ts
index d8d00f7309..28020740f2 100644
--- a/packages/builtin-tools/src/tools/ArtifactTool/__tests__/ArtifactTool.test.ts
+++ b/packages/builtin-tools/src/tools/ArtifactTool/__tests__/ArtifactTool.test.ts
@@ -6,6 +6,8 @@ import { ArtifactTool } from '../ArtifactTool.js'
 
 const TEST_DIR = join(tmpdir(), 'artifact-tool-test')
 const TEST_FILE = join(TEST_DIR, 'report.html')
+const MD_FILE = join(TEST_DIR, 'report.md')
+const TXT_FILE = join(TEST_DIR, 'notes.txt')
 const MISSING_FILE = join(TEST_DIR, 'does-not-exist.html')
 const DIR_AS_FILE = TEST_DIR
 
@@ -26,6 +28,12 @@ describe('ArtifactTool.call', () => {
   beforeEach(() => {
     mkdirSync(TEST_DIR, { recursive: true })
     writeFileSync(TEST_FILE, '<h1>test report</h1>', 'utf8')
+    writeFileSync(
+      MD_FILE,
+      '# MD Report\n\n| a | b |\n| - | - |\n| 1 | 2 |\n',
+      'utf8',
+    )
+    writeFileSync(TXT_FILE, 'plain text content', 'utf8')
     process.env.CLAUDE_ARTIFACTS_TOKEN = 'test-token'
     process.env.CLAUDE_ARTIFACTS_URL = 'https://example.test'
   })
@@ -109,4 +117,48 @@ describe('ArtifactTool.call', () => {
       'payload_too_large',
     )
   })
+
+  test('converts .md file to styled HTML before upload', async () => {
+    const fetchMock = mockFetchSuccess({
+      id: 'md-id',
+      url: 'https://example.test/7d/md-id.html',
+      expiresAt: '2026-06-27T10:00:00.000Z',
+    })
+    globalThis.fetch = fetchMock
+
+    const result = await ArtifactTool.call({ file_path: MD_FILE, ttl: 7 })
+
+    expect(result.data).toMatchObject({ id: 'md-id' })
+    expect((result.data as { error?: string }).error).toBeUndefined()
+
+    const calls = (
+      fetchMock as unknown as {
+        mock: { calls: [string | URL | Request, RequestInit | undefined][] }
+      }
+    ).mock.calls
+    expect(calls.length).toBe(1)
+    const body = String(calls[0][1]?.body)
+    expect(body.startsWith('<!DOCTYPE html>')).toBe(true)
+    expect(body).toContain('<h1>MD Report</h1>')
+    expect(body).toContain('<table>')
+    expect(body).toContain('<title>MD Report</title>')
+    // Content-Type header must remain text/html — the Worker only accepts HTML.
+    expect(calls[0][1]?.headers).toMatchObject({ 'Content-Type': 'text/html' })
+  })
+
+  test('rejects unsupported extension without calling fetch', async () => {
+    let fetchCalled = false
+    globalThis.fetch = mock(() => {
+      fetchCalled = true
+      return Promise.resolve(new Response('{}'))
+    }) as unknown as typeof fetch
+
+    const result = await ArtifactTool.call({ file_path: TXT_FILE, ttl: 7 })
+
+    expect(fetchCalled).toBe(false)
+    expect((result.data as { error?: string }).error).toContain(
+      'Unsupported file extension',
+    )
+    expect((result.data as { error?: string }).error).toContain('.md')
+  })
 })
diff --git a/packages/builtin-tools/src/tools/ArtifactTool/__tests__/markdown.test.ts b/packages/builtin-tools/src/tools/ArtifactTool/__tests__/markdown.test.ts
new file mode 100644
index 0000000000..c07d79fdf3
--- /dev/null
+++ b/packages/builtin-tools/src/tools/ArtifactTool/__tests__/markdown.test.ts
@@ -0,0 +1,88 @@
+import { describe, expect, test } from 'bun:test'
+import { markdownToHtml } from '../markdown.js'
+
+describe('markdownToHtml', () => {
+  test('wraps body in a full HTML document', () => {
+    const out = markdownToHtml('# Hello')
+    expect(out.startsWith('<!DOCTYPE html>')).toBe(true)
+    expect(out).toContain('<html')
+    expect(out).toContain('</html>')
+    expect(out).toContain('<style>')
+  })
+
+  test('extracts H1 as <title>', () => {
+    const out = markdownToHtml('# Hello World\n\nbody')
+    expect(out).toContain('<title>Hello World</title>')
+    expect(out).toContain('<h1>Hello World</h1>')
+  })
+
+  test('renders GFM tables', () => {
+    const md = ['| A | B |', '| - | - |', '| 1 | 2 |'].join('\n')
+    const out = markdownToHtml(md)
+    expect(out).toContain('<table>')
+    expect(out).toContain('<th>A</th>')
+    expect(out).toContain('<td>1</td>')
+  })
+
+  test('preserves fenced code language class', () => {
+    const md = '```ts\nconst x = 1\n```'
+    const out = markdownToHtml(md)
+    expect(out).toContain('class="language-ts"')
+    expect(out).toContain('<pre>')
+  })
+
+  test('passes through inline raw HTML', () => {
+    const out = markdownToHtml('<strong>raw</strong>')
+    expect(out).toContain('<strong>raw</strong>')
+  })
+
+  test('renders blockquotes', () => {
+    const out = markdownToHtml('> quoted')
+    expect(out).toContain('<blockquote>')
+  })
+
+  test('falls back to basename when no H1 present', () => {
+    const out = markdownToHtml('just body text', '/tmp/My Report.md')
+    expect(out).toContain('<title>My Report</title>')
+  })
+
+  test('falls back to default when no H1 and no filename', () => {
+    const out = markdownToHtml('just body text')
+    expect(out).toContain('<title>Artifact</title>')
+  })
+
+  test('strips .markdown suffix in fallback title', () => {
+    const out = markdownToHtml('body', '/x/foo.markdown')
+    expect(out).toContain('<title>foo</title>')
+  })
+
+  test('escapes HTML in title to prevent injection', () => {
+    const out = markdownToHtml('# Title <script>alert(1)</script>')
+    // Title tag must not contain a literal <script>
+    const titleMatch = out.match(/<title>([\s\S]*?)<\/title>/)
+    expect(titleMatch).not.toBeNull()
+    expect(titleMatch![1]).not.toContain('<script>')
+    expect(titleMatch![1]).toContain('&lt;script&gt;')
+  })
+
+  test('embeds highlight.js and mermaid via unpkg CDN', () => {
+    const out = markdownToHtml('body')
+    expect(out).toContain(
+      'https://unpkg.com/@highlightjs/cdn-assets@11.10.0/highlight.min.js',
+    )
+    expect(out).toContain(
+      'https://unpkg.com/@highlightjs/cdn-assets@11.10.0/styles/github.min.css',
+    )
+    expect(out).toContain('https://unpkg.com/mermaid@11/dist/mermaid.min.js')
+    // Init script must run after both libraries load.
+    expect(out).toContain('hljs.highlightAll()')
+    expect(out).toContain('mermaid.initialize(')
+    expect(out).toContain('language-mermaid')
+    const mermaidIdx = out.indexOf('mermaid@11/dist/mermaid.min.js')
+    const hljsIdx = out.indexOf('highlight.min.js')
+    const initIdx = out.indexOf('hljs.highlightAll')
+    expect(mermaidIdx).toBeGreaterThan(0)
+    expect(hljsIdx).toBeGreaterThan(mermaidIdx)
+    expect(initIdx).toBeGreaterThan(hljsIdx)
+  })
+})
diff --git a/packages/builtin-tools/src/tools/ArtifactTool/examples/full-feature.md b/packages/builtin-tools/src/tools/ArtifactTool/examples/full-feature.md
new file mode 100644
index 0000000000..162aa95bb8
--- /dev/null
+++ b/packages/builtin-tools/src/tools/ArtifactTool/examples/full-feature.md
@@ -0,0 +1,178 @@
+# 全功能 Markdown 测试
+
+这份文档用于人工验证 `artifact` 工具对 `.md` 文件的上传、转换、代码高亮与 Mermaid 渲染是否正常。**直接把它传给 `artifact` 工具**（`file_path` 指向本文件），浏览器打开返回的 URL 即可对照下面的章节逐一确认。
+
+## 行内格式
+
+正文段落里包含 **粗体**、*斜体*、~~删除线~~、`行内代码`、以及组合 **粗体 + _斜体_ + `code`**。还有 [一个链接](https://example.com) 指向 example.com。
+
+支持中英文混排：Claude Orange `#D77757` 是 Anthropic 的主色。Emoji：🚀 ✅ 🎯。
+
+## 标题层级
+
+以下是 H2，再往下还有 H3 / H4 / H5 / H6：
+
+### H3 — 第三层
+#### H4 — 第四层
+##### H5 — 第五层
+###### H6 — 第六层
+
+## 列表
+
+无序列表：
+
+- 第一项
+- 第二项
+  - 嵌套项 A
+  - 嵌套项 B
+    - 更深一层
+- 第三项
+
+有序列表：
+
+1. 第一步
+2. 第二步
+   1. 子步骤 2.1
+   2. 子步骤 2.2
+3. 第三步
+
+任务列表（GFM）：
+
+- [x] 已完成项
+- [ ] 未完成项
+- [ ] 另一个未完成项
+
+## 表格
+
+左对齐 / 居中 / 右对齐混合：
+
+| 名称       | 类型     | 数量 | 备注           |
+| ---------- | :------: | ---: | -------------- |
+| Claude     | 模型     |    1 | 推荐           |
+| Opus 4.7   | 模型     |    2 | 最强           |
+| Haiku 4.5  | 模型     |    3 | 最快           |
+
+## 围栏代码块（语法高亮）
+
+TypeScript：
+
+```ts
+interface User {
+  id: string
+  name: string
+  role: 'admin' | 'guest'
+}
+
+export async function fetchUser(id: string): Promise<User> {
+  const res = await fetch(`/api/users/${id}`)
+  if (!res.ok) throw new Error(`status ${res.status}`)
+  return (await res.json()) as User
+}
+```
+
+Python：
+
+```python
+from dataclasses import dataclass
+from typing import Iterable
+
+@dataclass
+class Point:
+    x: float
+    y: float
+
+def centroid(points: Iterable[Point]) -> Point:
+    pts = list(points)
+    n = len(pts)
+    return Point(sum(p.x for p in pts) / n, sum(p.y for p in pts) / n)
+```
+
+Bash：
+
+```bash
+# Install dependencies and run tests
+bun install
+bun run precheck
+```
+
+JSON：
+
+```json
+{
+  "name": "claude-code-best",
+  "version": "2.2.1",
+  "runtime": "bun",
+  "features": ["buddy", "bridge_mode", "ultrathink"]
+}
+```
+
+## Mermaid 图表
+
+流程图：
+
+```mermaid
+flowchart TD
+    A[用户输入] --> B{是否需要计划?}
+    B -- 是 --> C[进入 Plan 模式]
+    B -- 否 --> D[直接执行]
+    C --> E[用户审批]
+    E --> D
+    D --> F[调用工具]
+    F --> G[返回结果]
+```
+
+时序图：
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant C as CLI
+    participant A as API
+    U->>C: 发送消息
+    C->>A: 流式请求
+    A-->>C: 工具调用 delta
+    C->>U: 渲染权限提示
+    U->>C: 批准
+    C->>A: 继续流
+    A-->>C: 最终消息
+    C-->>U: 显示结果
+```
+
+甘特图：
+
+```mermaid
+gantt
+    title 发布计划
+    dateFormat  YYYY-MM-DD
+    section 工程
+    代码冻结     :done,    eng1, 2026-07-01, 7d
+    人工测试     :active,  eng2, after eng1, 5d
+    section 市场
+    文案撰写     :         mk1, 2026-07-03, 4d
+    正式发布     :         mk2, after eng2, 1d
+```
+
+## 引用
+
+> 这是一段引用文本。
+> 第二行继续。
+
+> 嵌套引用：
+>
+> > 这是更深层级。
+>
+> 回到外层。
+
+## 水平线
+
+---
+
+水平线之上。
+
+## 行内 HTML
+
+直接写的 HTML 会被透传：<kbd>Ctrl</kbd> + <kbd>C</kbd>，<span style="color: #D77757">Claude Orange 文字</span>。
+
+## 结论
+
+如果上面所有章节都正常显示，说明 artifact 工具的 Markdown 转换、代码高亮（highlight.js）、Mermaid 渲染均已就绪。
diff --git a/packages/builtin-tools/src/tools/ArtifactTool/markdown.ts b/packages/builtin-tools/src/tools/ArtifactTool/markdown.ts
new file mode 100644
index 0000000000..cbeb392d46
--- /dev/null
+++ b/packages/builtin-tools/src/tools/ArtifactTool/markdown.ts
@@ -0,0 +1,98 @@
+import { basename } from 'path'
+import { marked, type Tokens } from 'marked'
+
+/**
+ * Convert a Markdown string into a complete HTML document with a neutral,
+ * minimal stylesheet (one Claude-Orange accent). Used by the artifact tool
+ * to accept .md files alongside .html.
+ */
+export function markdownToHtml(md: string, filename?: string): string {
+  const body = marked.parse(md, {
+    async: false,
+    gfm: true,
+    breaks: false,
+  }) as string
+  const title = extractTitle(md) ?? fallbackTitle(filename)
+  return wrapDocument(body, title)
+}
+
+function extractTitle(md: string): string | undefined {
+  for (const token of marked.lexer(md)) {
+    if (token.type === 'heading' && (token as Tokens.Heading).depth === 1) {
+      return (token as Tokens.Heading).text
+    }
+  }
+  return undefined
+}
+
+function fallbackTitle(filename?: string): string {
+  if (!filename) return 'Artifact'
+  return basename(filename).replace(/\.(md|markdown)$/i, '') || 'Artifact'
+}
+
+function wrapDocument(body: string, title: string): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<link rel="stylesheet" href="https://unpkg.com/@highlightjs/cdn-assets@11.10.0/styles/github.min.css">
+<style>
+:root { --accent: #D77757; }
+body { font: 14px/1.5 -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; max-width: 800px; margin: 2rem auto; padding: 0 1rem; color: #1a1a1a; }
+h1 { border-bottom: 2px solid var(--accent); padding-bottom: .3rem; }
+h2 { margin-top: 1.5em; }
+img { max-width: 100%; }
+pre { background: #f6f6f6; padding: .75rem 1rem; border-radius: 4px; overflow-x: auto; }
+code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+pre code { background: none; padding: 0; }
+.hljs { background: transparent; padding: 0; }
+table { border-collapse: collapse; width: 100%; margin: 1em 0; }
+th, td { border: 1px solid #ddd; padding: 6px 10px; text-align: left; }
+th { background: #f6f6f6; }
+blockquote { border-left: 3px solid var(--accent); margin: 0; padding: .25rem 1rem; color: #555; }
+a { color: var(--accent); }
+.mermaid { text-align: center; margin: 1em 0; }
+</style>
+</head>
+<body>
+${body}
+<script src="https://unpkg.com/mermaid@11/dist/mermaid.min.js"></script>
+<script src="https://unpkg.com/@highlightjs/cdn-assets@11.10.0/highlight.min.js"></script>
+<script>
+(function () {
+  // Hoist mermaid fence blocks out of <pre><code> before hljs touches them,
+  // otherwise highlight.js would mangle the diagram source as if it were JS.
+  document.querySelectorAll('pre code.language-mermaid').forEach(function (code) {
+    var pre = code.parentElement;
+    var div = document.createElement('div');
+    div.className = 'mermaid';
+    div.textContent = code.textContent;
+    pre.replaceWith(div);
+  });
+  if (window.mermaid) {
+    window.mermaid.initialize({ startOnLoad: false, theme: 'default', securityLevel: 'loose' });
+    window.mermaid.run();
+  }
+  if (window.hljs) {
+    window.hljs.highlightAll();
+  }
+})();
+</script>
+</body>
+</html>`
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(
+    /[&<>"]/g,
+    c =>
+      ({
+        '&': '&amp;',
+        '<': '&lt;',
+        '>': '&gt;',
+        '"': '&quot;',
+      })[c] as string,
+  )
+}
diff --git a/packages/builtin-tools/src/tools/ArtifactTool/prompt.ts b/packages/builtin-tools/src/tools/ArtifactTool/prompt.ts
index ab0ebe5f13..b65e003c43 100644
--- a/packages/builtin-tools/src/tools/ArtifactTool/prompt.ts
+++ b/packages/builtin-tools/src/tools/ArtifactTool/prompt.ts
@@ -1,14 +1,14 @@
 export const ARTIFACT_TOOL_NAME = 'artifact'
 
 export async function describeArtifactTool(): Promise<string> {
-  return 'Upload an HTML file to the cloud-artifacts hosting service and get back a public URL. Pass `hash` to overwrite a previously-uploaded artifact (keeps URL stable).'
+  return 'Upload an HTML or Markdown file to the cloud-artifacts hosting service and get back a public URL. Markdown files are converted to styled HTML before upload. Pass `hash` to overwrite a previously-uploaded artifact (keeps URL stable).'
 }
 
 export async function getArtifactToolPrompt(): Promise<string> {
-  return `Upload an HTML file to a public hosting service and return a shareable URL plus an internal \`id\` (the "hash").
+  return `Upload an HTML or Markdown file to a public hosting service and return a shareable URL plus an internal \`id\` (the "hash").
 
 ## Inputs
-- \`file_path\` (required): absolute path to a local HTML file.
+- \`file_path\` (required): absolute path to a local HTML (\`.html\`/\`.htm\`) or Markdown (\`.md\`/\`.markdown\`) file. Markdown is converted to a styled HTML document before upload — just author plain Markdown (headings, lists, GFM tables, fenced code blocks, blockquotes) and the tool wraps it in a page with a neutral stylesheet.
 - \`hash\` (optional): if provided, overwrites the artifact with the same hash (URL stays the same). If omitted, a new random id is generated.
 - \`ttl\` (optional, default \`7\`): artifact lifetime in days. Must be \`7\` or \`30\`.
 
@@ -16,10 +16,10 @@ export async function getArtifactToolPrompt(): Promise<string> {
 \`{ id, url, expiresAt }\` — \`id\` is the hash (save it for future overwrite calls), \`url\` is publicly accessible.
 
 ## Workflow
-1. Use the Write tool to create a local HTML file.
+1. Use the Write tool to create a local \`.html\` or \`.md\` file.
 2. Call this tool with its \`file_path\`.
 3. If iterating on the same artifact, pass back the \`id\` returned from the first call as \`hash\` so the URL stays stable.
 
 ## Errors
-The tool surfaces backend error codes verbatim (e.g. \`payload_too_large\`, \`unauthorized\`). If the file does not exist or is not a regular file, the tool returns an \`error\` field without making an HTTP request.`
+The tool surfaces backend error codes verbatim (e.g. \`payload_too_large\`, \`unauthorized\`). If the file does not exist, is not a regular file, or has an unsupported extension, the tool returns an \`error\` field without making an HTTP request. Accepted extensions: \`.html\`, \`.htm\`, \`.md\`, \`.markdown\`.`
 }
diff --git a/src/skills/bundled/useArtifacts.ts b/src/skills/bundled/useArtifacts.ts
index 4fb819fb2d..021ed8b38b 100644
--- a/src/skills/bundled/useArtifacts.ts
+++ b/src/skills/bundled/useArtifacts.ts
@@ -36,20 +36,25 @@ Artifacts are public HTML pages you upload to a hosting service. They have stabl
 
 **First upload (creates a new artifact):**
 \`\`\`
-1. Use the Write tool to write HTML to a local file (location is your choice).
+1. Use the Write tool to write HTML (.html) or Markdown (.md) to a local file (location is your choice).
 2. SearchExtraTools({ query: "select:artifact" })   // loads the tool schema
-3. ExecuteExtraTool({ tool_name: "artifact", params: { file_path: "<absolute-path>.html" } })
+3. ExecuteExtraTool({ tool_name: "artifact", params: { file_path: "<absolute-path>.html|.md" } })
 4. Save the returned \`id\` from the tool result — this is the hash.
 \`\`\`
 
 **Subsequent updates (overwrites in place, URL stays stable):**
 \`\`\`
-1. Update the local HTML file.
-2. ExecuteExtraTool({ tool_name: "artifact", params: { file_path: "<absolute-path>.html", hash: "<id-from-first-call>" } })
+1. Update the local file.
+2. ExecuteExtraTool({ tool_name: "artifact", params: { file_path: "<absolute-path>.html|.md", hash: "<id-from-first-call>" } })
 \`\`\`
 
 The URL returned on every call is the same when you pass the same \`hash\`. The user can open it at any time to see the latest version.
 
+## Choosing HTML vs Markdown
+
+- **Markdown (.md)** — preferred for text-heavy reports, design docs, research notes. The tool converts it to a styled HTML page (GFM tables, fenced code blocks, blockquotes, headings). You write content, not chrome.
+- **HTML (.html)** — preferred when you need bespoke layout, custom CSS, embedded SVG, or interactive \`<script>\`. The hosting service serves the HTML verbatim.
+
 ## Minimal HTML skeleton
 
 \`\`\`html
@@ -72,6 +77,28 @@ The URL returned on every call is the same when you pass the same \`hash\`. The
 </html>
 \`\`\`
 
+## Minimal Markdown skeleton
+
+\`\`\`md
+# Artifact Title
+
+## Section
+
+Body paragraph with **bold**, *italic*, and \`inline code\`.
+
+- Bullet item
+- Bullet item
+
+| Column A | Column B |
+| -------- | -------- |
+| cell     | cell     |
+
+\`\`\`ts
+// fenced code block — language hint is preserved
+const x = 1
+\`\`\`
+\`\`\`
+
 The hosting service serves the HTML verbatim (including any \`<script>\` you include), so you can use vanilla JS/SVG/CSS as needed. Do not embed secrets.
 
 ## Notes

From 3edb13413b7570647cafdd96217171fae3561c3f Mon Sep 17 00:00:00 2001
From: claude-code-best <claude-code-best@proton.me>
Date: Thu, 9 Jul 2026 11:45:36 +0800
Subject: [PATCH 2/2] =?UTF-8?q?refactor:=20=E7=A7=BB=E9=99=A4=20attributio?=
 =?UTF-8?q?n=20header=20=E4=B8=AD=E7=9A=84=20per-message=20fingerprint=20?=
 =?UTF-8?q?=E4=BB=A5=E6=8F=90=E5=8D=87=E7=BC=93=E5=AD=98=E7=A8=B3=E5=AE=9A?=
 =?UTF-8?q?=E6=80=A7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

getAttributionHeader() 不再接收 fingerprint 参数，cc_version 仅用
MACRO.VERSION。原来 cc_version=2.1.888.abc 中 abc 是 per-message 的
fingerprint，每次请求都变，即使 header 标记为 cacheScope:null 也不利于
未来的缓存优化。

- system.ts: 移除 fingerprint 参数，cc_version 仅用 MACRO.VERSION
- claude.ts: 移除 computeFingerprintFromMessages import 及调用
- sideQuery.ts: 移除 fingerprint 计算、extractFirstUserMessageText 及
  computeFingerprint import

Co-Authored-By: deepseek-v4-pro <deepseek-ai@claude-code-best.win>
---
 src/constants/system.ts    | 12 ++++--------
 src/services/api/claude.ts |  8 +-------
 src/utils/sideQuery.ts     | 23 +----------------------
 3 files changed, 6 insertions(+), 37 deletions(-)

diff --git a/src/constants/system.ts b/src/constants/system.ts
index 0cd2e7652d..a2d7ca1d77 100644
--- a/src/constants/system.ts
+++ b/src/constants/system.ts
@@ -58,7 +58,7 @@ function isAttributionHeaderEnabled(): boolean {
 
 /**
  * Get attribution header for API requests.
- * Returns a header string with cc_version (including fingerprint) and cc_entrypoint.
+ * Returns a header string with cc_version and cc_entrypoint.
  * Enabled by default, can be disabled via env var or GrowthBook killswitch.
  *
  * When NATIVE_CLIENT_ATTESTATION is enabled, includes a `cch=00000` placeholder.
@@ -70,22 +70,18 @@ function isAttributionHeaderEnabled(): boolean {
  * We use a placeholder (instead of injecting from Zig) because same-length
  * replacement avoids Content-Length changes and buffer reallocation.
  */
-export function getAttributionHeader(fingerprint: string): string {
+export function getAttributionHeader(): string {
   if (!isAttributionHeaderEnabled()) {
     return ''
   }
 
-  const version = `${MACRO.VERSION}.${fingerprint}`
+  const version = MACRO.VERSION
   const entrypoint = process.env.CLAUDE_CODE_ENTRYPOINT ?? 'unknown'
 
   // cch=00000 placeholder is overwritten by Bun's HTTP stack with attestation token
   const cch = feature('NATIVE_CLIENT_ATTESTATION') ? ' cch=00000;' : ''
   // cc_workload: turn-scoped hint so the API can route e.g. cron-initiated
-  // requests to a lower QoS pool. Absent = interactive default. Safe re:
-  // fingerprint (computed from msg chars + version only, line 78 above) and
-  // cch attestation (placeholder overwritten in serialized body bytes after
-  // this string is built). Server _parse_cc_header tolerates unknown extra
-  // fields so old API deploys silently ignore this.
+  // requests to a lower QoS pool. Absent = interactive default.
   const workload = getWorkload()
   const workloadPair = workload ? ` cc_workload=${workload};` : ''
   const header = `x-anthropic-billing-header: cc_version=${version}; cc_entrypoint=${entrypoint};${cch}${workloadPair}`
diff --git a/src/services/api/claude.ts b/src/services/api/claude.ts
index 91db156e6d..5c75e22221 100644
--- a/src/services/api/claude.ts
+++ b/src/services/api/claude.ts
@@ -72,7 +72,6 @@ import {
 import { resolveAppliedEffort } from '../../utils/effort.js'
 import { isEnvTruthy } from '../../utils/envUtils.js'
 import { errorMessage } from '../../utils/errors.js'
-import { computeFingerprintFromMessages } from '../../utils/fingerprint.js'
 import { captureAPIRequest, logError } from '../../utils/log.js'
 import {
   createAssistantAPIErrorMessage,
@@ -1386,11 +1385,6 @@ async function* queryModel(
     postNormalizedMessageCount: messagesForAPI.length,
   })
 
-  // Compute fingerprint from first user message for attribution.
-  // Must run BEFORE injecting synthetic messages (e.g. deferred tool names)
-  // so the fingerprint reflects the actual user input.
-  const fingerprint = computeFingerprintFromMessages(messagesForAPI)
-
   // When the delta attachment is enabled, deferred tools are announced
   // via persisted deferred_tools_delta attachments instead of this
   // ephemeral prepend (which busts cache whenever the pool changes).
@@ -1438,7 +1432,7 @@ async function* queryModel(
   // filter(Boolean) works by converting each element to a boolean - empty strings become false and are filtered out.
   systemPrompt = asSystemPrompt(
     [
-      getAttributionHeader(fingerprint),
+      getAttributionHeader(),
       getCLISyspromptPrefix({
         isNonInteractive: options.isNonInteractiveSession,
         hasAppendSystemPrompt: options.hasAppendSystemPrompt,
diff --git a/src/utils/sideQuery.ts b/src/utils/sideQuery.ts
index 6424d54565..3d6d645dcf 100644
--- a/src/utils/sideQuery.ts
+++ b/src/utils/sideQuery.ts
@@ -30,7 +30,6 @@ import {
 import { getModelBetas, modelSupportsStructuredOutputs } from './betas.js'
 import { logForDebugging } from './debug.js'
 import { errorMessage } from './errors.js'
-import { computeFingerprint } from './fingerprint.js'
 import { getAPIProvider } from './model/providers.js'
 import { normalizeModelStringForAPI } from './model/model.js'
 import { getOpenAIClient } from '../services/api/openai/client.js'
@@ -97,21 +96,6 @@ export type SideQueryOptions = {
   optional?: boolean
 }
 
-/**
- * Extract text from first user message for fingerprint computation.
- */
-function extractFirstUserMessageText(messages: MessageParam[]): string {
-  const firstUserMessage = messages.find(m => m.role === 'user')
-  if (!firstUserMessage) return ''
-
-  const content = firstUserMessage.content
-  if (typeof content === 'string') return content
-
-  // Array of content blocks - find first text block
-  const textBlock = content.find(block => block.type === 'text')
-  return textBlock?.type === 'text' ? textBlock.text : ''
-}
-
 /**
  * Extract system prompt text from the `system` option.
  */
@@ -219,12 +203,7 @@ export async function sideQuery(opts: SideQueryOptions): Promise<BetaMessage> {
     betas.push(STRUCTURED_OUTPUTS_BETA_HEADER)
   }
 
-  // Extract first user message text for fingerprint
-  const messageText = extractFirstUserMessageText(messages)
-
-  // Compute fingerprint for OAuth attribution
-  const fingerprint = computeFingerprint(messageText, MACRO.VERSION)
-  const attributionHeader = getAttributionHeader(fingerprint)
+  const attributionHeader = getAttributionHeader()
 
   // Build system as array to keep attribution header in its own block
   // (prevents server-side parsing from including system content in cc_entrypoint)