writedock-mcp 0.4.2 → 0.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "writedock-mcp",
-  "version": "0.4.2",
+  "version": "0.4.6",
   "description": "WriteDock local MCP server for the browser extension",
   "type": "commonjs",
   "license": "GPL-3.0-only",
@@ -17,7 +17,8 @@
     "LICENSE-MULTIPOST",
     "NOTICE.md",
     "THIRD_PARTY_NOTICES.txt",
-    "source"
+    "source",
+    "extension"
   ],
   "keywords": [
     "mcp",

package/source/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writedock/mcp-server",
-  "version": "0.4.2",
+  "version": "0.4.6",
   "private": true,
   "type": "module",
   "description": "WriteDock local MCP server for the browser extension",

package/source/src/__tests__/bridge.test.ts

@@ -2,7 +2,9 @@ import { afterEach, describe, expect, it } from 'vitest'
 import { createServer } from 'node:net'
 import { once } from 'node:events'
 import { randomBytes } from 'node:crypto'
+import http from 'node:http'
 import { WebSocket } from 'ws'
+import { EXTENSION_ORIGIN } from '../extension-id'
 import { LocalBridge, proof, requestProof } from '../bridge'
 
 const token = 'test-pairing-key-that-is-long-enough'
@@ -31,6 +33,26 @@ async function pair(bridge: LocalBridge, key = token) {
 afterEach(async () => { clients.splice(0).forEach(ws => ws.terminate()); await Promise.all(brokers.splice(0).map(value => value.close())) })
 
 describe('authenticated local bridge', () => {
+  it('answers discovery and one-click connection only for the fixed extension origin', async () => {
+    const bridge = await broker()
+    const hello = (origin?: string) => new Promise<number>((resolve, reject) => { const req = http.get({ host: '127.0.0.1', port: bridge.port, path: '/hello', headers: origin ? { Origin: origin } : {} }, res => { res.resume(); resolve(res.statusCode!) }); req.on('error', reject) })
+    expect(await hello(EXTENSION_ORIGIN)).toBe(200)
+    expect(await hello()).toBe(200)
+    expect(await hello('https://example.com')).not.toBe(200)
+    expect(await hello('chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa')).not.toBe(200)
+    const open = (origin: string) => new Promise<{ code?: number; message?: Record<string, unknown> }>(resolve => {
+      const ws = new WebSocket(`ws://127.0.0.1:${bridge.port}/connect`, { origin })
+      ws.on('message', raw => resolve({ message: JSON.parse(raw.toString()) }))
+      ws.on('unexpected-response', (_req, res) => resolve({ code: res.statusCode }))
+      ws.on('error', () => {})
+    })
+    expect((await open('chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa')).code).toBe(403)
+    expect((await open('https://example.com')).code).toBe(403)
+    const connected = await open(EXTENSION_ORIGIN)
+    expect(connected.message).toMatchObject({ type: 'connect_result', port: bridge.port, protocol: 'writedock/1' })
+    expect(String(connected.message?.token)).toMatch(/^[a-f0-9]{64}$/)
+  })
+
   it('rejects unauthenticated HTTP calls and browser-origin requests', async () => {
     const bridge = await broker()
     const url = `http://127.0.0.1:${bridge.port}/status`

package/source/src/__tests__/extension-update.test.ts

@@ -0,0 +1,54 @@
+import { mkdir, mkdtemp, readFile, realpath, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { bundledExtension, findInstalledExtension, installExtensionFiles } from '../extension-update'
+
+const manifest = (version: string, extra: Record<string, unknown> = {}) => JSON.stringify({ name: '写作台 WriteDock', version, key: 'fixed-key', ...extra })
+
+describe('extension update', () => {
+  let work: string, source: string, target: string
+  beforeEach(async () => {
+    work = await mkdtemp(join(tmpdir(), 'writedock-ext-'))
+    source = join(work, 'bundle/extension'); target = join(work, 'installed')
+    await mkdir(source, { recursive: true })
+    await writeFile(join(source, 'manifest.json'), manifest('2.0.0'))
+    await writeFile(join(source, 'worker.js'), 'new')
+  })
+  afterEach(() => rm(work, { recursive: true, force: true }))
+
+  it('installs into an empty folder, then overwrites in place keeping files still in use', async () => {
+    expect(await installExtensionFiles(source, target)).toMatchObject({ version: '2.0.0' })
+    expect(await readFile(join(target, 'worker.js'), 'utf8')).toBe('new')
+    await writeFile(join(target, 'old-hashed.js'), 'still used until reload')
+    await writeFile(join(target, 'manifest.json'), manifest('1.0.0'))
+    await installExtensionFiles(source, target)
+    expect(JSON.parse(await readFile(join(target, 'manifest.json'), 'utf8')).version).toBe('2.0.0')
+    expect(await readFile(join(target, 'old-hashed.js'), 'utf8')).toBe('still used until reload')
+  })
+
+  it('refuses another extension or a different identity, and leaves the folder alone', async () => {
+    await mkdir(target)
+    await writeFile(join(target, 'manifest.json'), JSON.stringify({ name: 'Other', version: '1.0.0' }))
+    await expect(installExtensionFiles(source, target)).rejects.toThrow('不是 WriteDock')
+    expect(JSON.parse(await readFile(join(target, 'manifest.json'), 'utf8')).name).toBe('Other')
+    await writeFile(join(target, 'manifest.json'), manifest('1.0.0', { key: 'other-key' }))
+    await expect(installExtensionFiles(source, target)).rejects.toThrow('身份不同')
+    expect(JSON.parse(await readFile(join(target, 'manifest.json'), 'utf8')).version).toBe('1.0.0')
+  })
+
+  it('finds the loaded folder by extension ID and ignores others', async () => {
+    await installExtensionFiles(source, target)
+    const browser = join(work, 'browser')
+    await mkdir(join(browser, 'Default'), { recursive: true })
+    await writeFile(join(browser, 'Default/Preferences'), JSON.stringify({ extensions: { settings: { other: { path: join(work, 'nope') }, theid: { path: target } } } }))
+    expect(await findInstalledExtension([browser], 'theid')).toBe(await realpath(target))
+    expect(await findInstalledExtension([browser], 'missing')).toBeUndefined()
+    expect(await findInstalledExtension([join(work, 'no-browser')], 'theid')).toBeUndefined()
+  })
+
+  it('reads the bundled version, and reports none from a source checkout', () => {
+    expect(bundledExtension(join(work, 'bundle'))).toMatchObject({ version: '2.0.0' })
+    expect(bundledExtension(work)).toBeUndefined()
+  })
+})

package/source/src/__tests__/setup.test.ts

@@ -0,0 +1,50 @@
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { runSetup } from '../setup'
+
+describe('setup', () => {
+  let home: string
+  const log: string[] = []
+  beforeEach(async () => { home = await mkdtemp(join(tmpdir(), 'writedock-setup-')); log.length = 0 })
+  afterEach(() => rm(home, { recursive: true, force: true }))
+
+  it('adds WriteDock to Codex and keeps the rest of the file, with a backup', async () => {
+    await mkdir(join(home, '.codex'))
+    const original = 'model = "x"\n\n[mcp_servers.other]\ncommand = "other"\n'
+    await writeFile(join(home, '.codex/config.toml'), original)
+    expect(await runSetup(home, line => log.push(line))).toBe(1)
+    const result = await readFile(join(home, '.codex/config.toml'), 'utf8')
+    expect(result.startsWith(original.trimEnd())).toBe(true)
+    expect(result).toContain('[mcp_servers.writedock]')
+    expect(result).toContain('"writedock-mcp@latest"')
+    expect(await readFile(join(home, '.codex/config.toml.writedock-backup'), 'utf8')).toBe(original)
+  })
+
+  it('leaves an existing entry alone, including its custom port and token', async () => {
+    await mkdir(join(home, '.codex'))
+    const original = '[mcp_servers.writedock]\ncommand = "node"\n\n[mcp_servers.writedock.env]\nWRITEDOCK_PORT = "9700"\n'
+    await writeFile(join(home, '.codex/config.toml'), original)
+    await runSetup(home, line => log.push(line))
+    expect(await readFile(join(home, '.codex/config.toml'), 'utf8')).toBe(original)
+    expect(log.join()).toContain('未改动')
+  })
+
+  it('merges JSON clients, and reports a broken file without changing it', async () => {
+    await writeFile(join(home, '.claude.json'), JSON.stringify({ theme: 'dark', mcpServers: { other: { command: 'x' } } }))
+    await mkdir(join(home, '.cursor'))
+    await writeFile(join(home, '.cursor/mcp.json'), '{ broken')
+    await runSetup(home, line => log.push(line))
+    const claude = JSON.parse(await readFile(join(home, '.claude.json'), 'utf8'))
+    expect(claude.theme).toBe('dark')
+    expect(Object.keys(claude.mcpServers).sort()).toEqual(['other', 'writedock'])
+    expect(await readFile(join(home, '.cursor/mcp.json'), 'utf8')).toBe('{ broken')
+    expect(log.join()).toContain('配置失败')
+  })
+
+  it('touches nothing when no client exists, and prints the configuration', async () => {
+    expect(await runSetup(home, line => log.push(line))).toBe(0)
+    expect(log.join()).toContain('writedock-mcp@latest')
+  })
+})

package/source/src/bridge.ts

@@ -6,6 +6,8 @@ import { createCipheriv, createHash, createHmac, randomBytes, randomUUID, timing
 import { WebSocket, WebSocketServer } from 'ws'
 import { MediaStore, type MediaAsset } from './media'
 import { mcpReleaseInfo } from './release-info'
+import { EXTENSION_ORIGIN } from './extension-id'
+import { updateInstalledExtension } from './extension-update'
 
 const LIMIT = 32 * 1024 * 1024
 const messageOf = (error: unknown) => error instanceof Error ? error.message : String(error)
@@ -59,10 +61,10 @@ export class LocalBridge {
     server.on('upgrade', (req, socket, head) => {
       const origin = req.headers.origin
       const extensionOrigin = typeof origin === 'string' && /^chrome-extension:\/\/[a-p]{32}$/.test(origin)
-      if (!this.validHost(req.headers.host) || !['/extension', '/pair'].includes(req.url || '') || (origin && !extensionOrigin) || (req.url === '/pair' && !extensionOrigin)) {
+      if (!this.validHost(req.headers.host) || !['/extension', '/pair', '/connect'].includes(req.url || '') || (origin && !extensionOrigin) || (req.url === '/pair' && !extensionOrigin) || (req.url === '/connect' && origin !== EXTENSION_ORIGIN)) {
         socket.write('HTTP/1.1 403 Forbidden\r\n\r\n'); socket.destroy(); return
       }
-      sockets.handleUpgrade(req, socket, head, ws => { if (req.url === '/pair') this.acceptPairing(ws); else this.accept(ws) })
+      sockets.handleUpgrade(req, socket, head, ws => { if (req.url === '/pair') this.acceptPairing(ws); else if (req.url === '/connect') void this.acceptConnect(ws); else this.accept(ws) })
     })
     await new Promise<void>((resolve, reject) => {
       server.once('error', reject)
@@ -90,6 +92,28 @@ export class LocalBridge {
     return { pairing_code: code, expires_at: new Date(expiresAt).toISOString(), expires_in_seconds: 180, instructions: '将此一次性配对码粘贴到扩展的「MCP 连接 → 输入一次性配对码」。有效期 3 分钟，使用一次后失效。无需重新安装 MCP 或修改 agent 配置。确认用户要连接当前扩展后再生成。' }
   }
 
+  /** Replaces the extension credential and drops whatever was using the old one. */
+  private async replaceExtensionToken(reason: string) {
+    const token = randomBytes(32).toString('hex')
+    await this.options.credentials?.setExtensionToken(token)
+    this.extensionToken = token
+    const previousClient = this.client
+    this.client = undefined; this.extensionId = undefined
+    for (const value of this.pending.values()) { clearTimeout(value.timer); value.reject(new Error(reason)) }
+    this.pending.clear()
+    previousClient?.close(1000, 'Extension pairing replaced')
+    return token
+  }
+
+  /** One-click connection: only this extension's fixed origin can reach here, and the user has just clicked 连接. */
+  private async acceptConnect(ws: WebSocket) {
+    try {
+      const token = await this.replaceExtensionToken('扩展连接已更换；请查询原同步任务，不要自动重新提交。')
+      ws.send(JSON.stringify({ type: 'connect_result', token, port: this.port, protocol: 'writedock/1' }))
+      ws.close(1000)
+    } catch { ws.close(1011, 'Connect failed') }
+  }
+
   private acceptPairing(ws: WebSocket) {
     const pairing = this.pairing
     if (!pairing || Date.now() > pairing.expiresAt || pairing.attempts >= 8) { ws.close(1008, 'Pairing code expired'); return }
@@ -107,15 +131,8 @@ export class LocalBridge {
         const message = JSON.parse(body)
         if (this.pairing !== pairing || Date.now() > pairing.expiresAt || message.type !== 'pairing_hello' || typeof message.proof !== 'string' || !equal(message.proof, proof(pairing.code, 'pairing-extension', nonce))) throw new Error('Pairing failed')
         this.pairing = undefined // Consume before the first asynchronous operation.
-        const token = randomBytes(32).toString('hex')
-        await this.options.credentials?.setExtensionToken(token)
-        this.extensionToken = token
         // A deliberate new pairing retires the old extension credential, not the MCP identity.
-        const previousClient = this.client
-        this.client = undefined; this.extensionId = undefined
-        for (const value of this.pending.values()) { clearTimeout(value.timer); value.reject(new Error('扩展配对已更换；请查询原同步任务，不要自动重新提交。')) }
-        this.pending.clear()
-        previousClient?.close(1000, 'Extension pairing replaced')
+        const token = await this.replaceExtensionToken('扩展配对已更换；请查询原同步任务，不要自动重新提交。')
         const key = createHmac('sha256', pairing.code).update(`writedock-pairing-key:${nonce}`).digest()
         const iv = randomBytes(12)
         const cipher = createCipheriv('aes-256-gcm', key, iv)
@@ -150,6 +167,13 @@ export class LocalBridge {
           return
         }
         if (message.type === 'pong') return
+        if (message.type === 'update_extension') {
+          void updateInstalledExtension().then(
+            result => ws.send(JSON.stringify({ type: 'update_extension_result', ok: true, version: result.version })),
+            error => ws.send(JSON.stringify({ type: 'update_extension_result', ok: false, error: messageOf(error) })),
+          )
+          return
+        }
         const pending = this.pending.get(message.id)
         if (!pending) return
         this.pending.delete(message.id); clearTimeout(pending.timer)
@@ -179,6 +203,11 @@ export class LocalBridge {
       if (responseNonce) res.setHeader('X-Writedock-Proof', proof(this.options.token, `http-response:${digest(body)}`, responseNonce))
       res.writeHead(status); res.end(body)
     }
+    // Lets the extension find this service before it is connected. Reveals only that it exists and its version.
+    // Chrome omits Origin on GETs from an extension with host permission; web pages always send theirs.
+    if (req.url === '/hello' && req.method === 'GET' && this.validHost(req.headers.host) && (!req.headers.origin || req.headers.origin === EXTENSION_ORIGIN)) {
+      send(200, { service: 'writedock-mcp', protocol: 'writedock/1', version: mcpReleaseInfo().mcp_version }); return
+    }
     const assetPath = /^\/assets\/([a-f0-9-]{36})$/.exec(req.url || '')
     if (assetPath && this.validHost(req.headers.host) && (!req.headers.origin || /^chrome-extension:\/\/[a-p]{32}$/.test(req.headers.origin))) {
       await this.media.serve(req, res, assetPath[1]); return
@@ -270,7 +299,7 @@ export class LocalBridge {
   }
 
   private async requestConnected(method: string, params: Record<string, unknown>): Promise<unknown> {
-    if (this.client?.readyState !== WebSocket.OPEN) throw new Error('扩展未连接。请调用 begin_pairing，将一次性配对码粘贴到扩展的 MCP 连接页；无需重装 MCP。')
+    if (this.client?.readyState !== WebSocket.OPEN) throw new Error('扩展未连接。请让用户打开浏览器的 WriteDock 扩展，在「连接」页点“连接”。无需重装 MCP。')
     const id = randomUUID()
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {

package/source/src/extension-id.ts

@@ -0,0 +1,2 @@
+/** Derived from the public key in packages/extension/manifest.json, so the ID does not depend on the install folder. */
+export const EXTENSION_ORIGIN = 'chrome-extension://himncajjeipncfpoajkcmfieonfpjfhb'

package/source/src/extension-update.ts

@@ -0,0 +1,82 @@
+import { readFileSync } from 'node:fs'
+import { cp, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, writeFile } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
+import { isAbsolute, join } from 'node:path'
+import { EXTENSION_ORIGIN } from './extension-id'
+
+const EXTENSION_ID = EXTENSION_ORIGIN.replace('chrome-extension://', '')
+const readManifest = async (directory: string) => JSON.parse(await readFile(join(directory, 'manifest.json'), 'utf8')) as { name?: string; version?: string; key?: string }
+const isWriteDock = (manifest: { name?: string; manifest_version?: number }) => manifest.name === '写作台 WriteDock'
+
+/** The extension shipped inside this npm package. Absent when running from a source checkout. */
+export function bundledExtension(base = __dirname) {
+  try {
+    const directory = join(base, 'extension')
+    const manifest = JSON.parse(readFileSync(join(directory, 'manifest.json'), 'utf8')) as { version?: string }
+    return typeof manifest.version === 'string' ? { directory, version: manifest.version } : undefined
+  } catch { return undefined }
+}
+
+/** Where setup installs the extension: stable, and visible in the browser's folder picker, which hides ~/Library on macOS. */
+export const defaultExtensionDirectory = (home = homedir()) => join(home, 'WriteDock', 'extension')
+
+function browserRoots(user = homedir()) {
+  const names = process.platform === 'win32'
+    ? ['Google/Chrome/User Data', 'Microsoft/Edge/User Data', 'Chromium/User Data', 'BraveSoftware/Brave-Browser/User Data'].map(name => join(process.env.LOCALAPPDATA || join(user, 'AppData/Local'), name))
+    : process.platform === 'darwin'
+      ? ['Google/Chrome', 'Microsoft Edge', 'Chromium', 'BraveSoftware/Brave-Browser'].map(name => join(user, 'Library/Application Support', name))
+      : ['google-chrome', 'microsoft-edge', 'chromium', 'BraveSoftware/Brave-Browser'].map(name => join(process.env.XDG_CONFIG_HOME || join(user, '.config'), name))
+  return names
+}
+
+/** Finds the folder the browser actually loaded this extension from, by its fixed ID. */
+export async function findInstalledExtension(roots = browserRoots(), id = EXTENSION_ID) {
+  for (const root of roots) {
+    let profiles: { name: string; isDirectory: () => boolean }[]
+    try { profiles = await readdir(root, { withFileTypes: true }) } catch { continue }
+    for (const profile of profiles.filter(item => item.isDirectory() && /^(Default|Profile \d+)$/.test(item.name))) {
+      for (const filename of ['Secure Preferences', 'Preferences']) {
+        try {
+          const preferences = JSON.parse(await readFile(join(root, profile.name, filename), 'utf8'))
+          const path = preferences.extensions?.settings?.[id]?.path
+          if (typeof path === 'string' && isAbsolute(path) && isWriteDock(await readManifest(path))) return realpath(path)
+        } catch { /* Missing or unreadable profile. */ }
+      }
+    }
+  }
+  return undefined
+}
+
+/** Overwrites in place, manifest last, restoring the previous files if anything fails. */
+export async function installExtensionFiles(source: string, target: string) {
+  const next = await readManifest(source)
+  if (!isWriteDock(next)) throw new Error('内置扩展文件不正确')
+  let previous: Awaited<ReturnType<typeof readManifest>> | undefined
+  try { previous = await readManifest(target) } catch { /* A first install. */ }
+  if (previous) {
+    if (!isWriteDock(previous)) throw new Error('目标目录不是 WriteDock 扩展，未覆盖')
+    if (previous.key !== next.key) throw new Error('旧版扩展的身份不同，无法原位更新，请重新加载一次新版')
+  }
+  await mkdir(target, { recursive: true })
+  const backup = previous ? await mkdtemp(join(tmpdir(), 'writedock-extension-backup-')) : undefined
+  if (backup) await cp(target, backup, { recursive: true, force: true })
+  try {
+    await cp(source, target, { recursive: true, force: true, filter: path => path !== join(source, 'manifest.json') })
+    const staged = join(target, '.writedock-manifest-update.tmp')
+    await writeFile(staged, await readFile(join(source, 'manifest.json')))
+    await rename(staged, join(target, 'manifest.json'))
+  } catch (error) {
+    if (backup) await cp(backup, target, { recursive: true, force: true })
+    throw error
+  } finally { if (backup) await rm(backup, { recursive: true, force: true }).catch(() => {}) }
+  return { directory: target, version: next.version }
+}
+
+/** Handles the 更新 button in the extension. */
+export async function updateInstalledExtension() {
+  const bundle = bundledExtension()
+  if (!bundle) throw new Error('当前服务没有内置扩展，请重启 agent 后再试')
+  const target = await findInstalledExtension()
+  if (!target) throw new Error('没有找到已加载的扩展目录，请手动更新')
+  return installExtensionFiles(bundle.directory, target)
+}

package/source/src/index.ts

@@ -4,6 +4,7 @@ import { LocalBridge } from './bridge'
 import { createMcpServer } from './server'
 import { loadIdentity } from './identity'
 import mcpPackage from '../package.json'
+import { runSetup } from './setup'
 
 async function main() {
   const port = Number(process.env.WRITEDOCK_PORT || 9647)
@@ -22,6 +23,8 @@ async function main() {
 if (process.argv.slice(2).some(argument => argument === '--version' || argument === '-v')) {
   // Allow inspecting an npm archive without starting a bridge or reading pairing credentials.
   console.log(mcpPackage.version)
+} else if (process.argv[2] === 'setup') {
+  runSetup().catch(error => { console.error('[WriteDock MCP]', error instanceof Error ? error.message : String(error)); process.exit(1) })
 } else {
   main().catch(error => { console.error('[WriteDock MCP]', error instanceof Error ? error.message : String(error)); process.exit(1) })
 }

package/source/src/release-info.ts

@@ -1,5 +1,6 @@
 import mcpPackage from '../package.json'
 import distribution from '../distribution.json'
+import { bundledExtension } from './extension-update'
 
 const CHECK_INTERVAL = 6 * 60 * 60_000
 const RETRY_INTERVAL = 10 * 60_000
@@ -56,8 +57,10 @@ function refresh() {
 /** Check asynchronously; version lookup must never delay pairing, tool calls or publication. */
 export function mcpReleaseInfo() {
   refresh()
+  const bundle = bundledExtension()
   return {
     mcp_version: mcpPackage.version,
+    ...(bundle ? { extension_bundle_version: bundle.version } : {}),
     ...(latestVersion ? { latest_version: latestVersion } : {}),
     update_available: !!latestVersion && newerVersion(latestVersion, mcpPackage.version),
     ...(checkedAt ? { update_checked_at: checkedAt } : {}),

package/source/src/server.ts

@@ -30,7 +30,7 @@ const agentWorkflow = 'Agent 只通过 WriteDock MCP 投稿和查询回执，不
 
 export function createMcpServer(bridge: LocalBridge) {
   const server = new McpServer({ name: 'writedock', version: mcpPackage.version }, {
-    instructions: agentWorkflow + 'WriteDock 通过本机扩展执行投稿。先检查连接和平台登录。实际平台能力以 list_platforms 返回的 action、publishModes、tools、modeOptions、confirmation、capabilities、coverRequired 为准，扩展更新后优先按该元信息选择工具。知乎、百家号、微博长文章、B站专栏、小红书长文使用 publish_article，Agent 直接提供 Markdown/HTML 或文件路径即可发布，无需用户在扩展编辑。百家号必须提供 cover 封面；知乎另支持 <video src="本地MP4路径"></video> 文章内视频，独立封面暂未接入。prepare_article 仅供可选本机预览，不是发布的前置要求。小红书 ID 为 xiaohongshu，三种模式共用此平台：写长文用 publish_article，支持正文图片、原生自动排版后发布，标题最多 64 字、正文最多 10000 字，不接独立 cover 或文章内视频；普通图文用 publish_post(kind=image)，独立视频用 publish_post(kind=video)，未传 cover_path 时保留平台自动生成的第一帧封面。小红书最终均须匹配 POST /web_api/sns/v2/note 的 success=true、result=0 和笔记 ID 回执才确认 submitted。抖音平台 ID 为 douyin，图文和视频同样用 publish_post(kind=image|video)，可选 cover_path；图文话题最多 4 个、视频最多 5 个，当前只接即时发布。抖音 confirmation=native_page_message，以本次操作新增的原生成功提示确认 submitted，未核对最终 HTTP 业务回执；仅跳转作品管理时仍为 unknown，Agent 不自动重发。小红书、抖音、微博普通图文与独立视频使用 prepare_post / publish_post，微博平台 ID 仍为 weibo，不另建平台。微博图文标题放入正文首行，最多 18 张图片；独立视频标题最多 30 个汉字（60 个半角字符），weibo_video_creation 必填，须依据用户实际内容传 original、secondary 或 repost，不能默认原创。微博同一次只能选图文或视频，长文章继续用 publish_article。只有用户明确要求发布并指定平台时才调用发布工具。微信公众号、搜狐号目前用 sync_article 保存文章草稿。B站专栏 ID 为 bilibili，使用 publish_article 直接发布文字和正文图片，不接视频、音频、附加内容卡片或独立封面；通过新版原生编辑器上传并发布，code=-352 时停止自动提交并转人工验证。遇到 needs_user_action 或 requires_user_action 时，把 user_actions 中的原因和稿件链接告诉用户，优先让用户切换到扩展已打开的页面处理验证码、封面、内容声明、来源、原创协议或发布设置，并手动发布；不得自动解决验证码、重新提交或换 request_id。该状态只记录人工接管，不代表用户之后的操作结果已被确认。扩展更新复用已有 MCP；需要恢复连接时调用 begin_pairing，让用户在扩展输入配对码。提交返回任务 ID，随后用 get_sync_task 查询结果。保持同一操作的 request_id 不变。publicationState=unknown 或任务中断时，向用户给出链接让其自行核对平台，Agent 不打开网页，不要自动生成新 request_id 重发。直接发布成功表示平台已接受提交，是否公开展示以平台为准。',
+    instructions: agentWorkflow + 'WriteDock 通过本机扩展执行投稿。先检查连接和平台登录。实际平台能力以 list_platforms 返回的 action、publishModes、tools、modeOptions、confirmation、capabilities、coverRequired 为准，扩展更新后优先按该元信息选择工具。知乎、百家号、微博长文章、B站专栏、小红书长文使用 publish_article，Agent 直接提供 Markdown/HTML 或文件路径即可发布，无需用户在扩展编辑。百家号必须提供 cover 封面；知乎另支持 <video src="本地MP4路径"></video> 文章内视频，独立封面暂未接入。prepare_article 仅供可选本机预览，不是发布的前置要求。小红书 ID 为 xiaohongshu，三种模式共用此平台：写长文用 publish_article，支持正文图片、原生自动排版后发布，标题最多 64 字、正文最多 10000 字，不接独立 cover 或文章内视频；普通图文用 publish_post(kind=image)，独立视频用 publish_post(kind=video)，未传 cover_path 时保留平台自动生成的第一帧封面。小红书最终均须匹配 POST /web_api/sns/v2/note 的 success=true、result=0 和笔记 ID 回执才确认 submitted。抖音平台 ID 为 douyin，图文和视频同样用 publish_post(kind=image|video)，可选 cover_path；图文话题最多 4 个、视频最多 5 个，当前只接即时发布。抖音 confirmation=native_page_message，以本次操作新增的原生成功提示确认 submitted，未核对最终 HTTP 业务回执；仅跳转作品管理时仍为 unknown，Agent 不自动重发。小红书、抖音、微博普通图文与独立视频使用 prepare_post / publish_post，微博平台 ID 仍为 weibo，不另建平台。微博图文标题放入正文首行，最多 18 张图片；独立视频标题最多 30 个汉字（60 个半角字符），weibo_video_creation 必填，须依据用户实际内容传 original、secondary 或 repost，不能默认原创。微博同一次只能选图文或视频，长文章继续用 publish_article。只有用户明确要求发布并指定平台时才调用发布工具。微信公众号、搜狐号目前用 sync_article 保存文章草稿。B站专栏 ID 为 bilibili，使用 publish_article 直接发布文字和正文图片，不接视频、音频、附加内容卡片或独立封面；通过新版原生编辑器上传并发布，code=-352 时停止自动提交并转人工验证。遇到 needs_user_action 或 requires_user_action 时，把 user_actions 中的原因和稿件链接告诉用户，优先让用户切换到扩展已打开的页面处理验证码、封面、内容声明、来源、原创协议或发布设置，并手动发布；不得自动解决验证码、重新提交或换 request_id。该状态只记录人工接管，不代表用户之后的操作结果已被确认。扩展更新复用已有 MCP；未连接时，让用户打开 WriteDock 扩展的「连接」页点“连接”。提交返回任务 ID，随后用 get_sync_task 查询结果。保持同一操作的 request_id 不变。publicationState=unknown 或任务中断时，向用户给出链接让其自行核对平台，Agent 不打开网页，不要自动生成新 request_id 重发。直接发布成功表示平台已接受提交，是否公开展示以平台为准。',
   })
   const wrap = (operation: () => Promise<unknown>) => operation().then(result => ({
     content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
@@ -38,10 +38,10 @@ export function createMcpServer(bridge: LocalBridge) {
   const readOnly = { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
 
   server.registerTool('get_connection_status', {
-    description: '检查本机 MCP 与扩展的连接、运行版本和 npm 更新提示。update_available=true 时告知用户重新启动 WriteDock MCP，保留配置和配对；发布任务进行中不要自动重启。旧版服务可能不返回版本字段；latest_version 缺失或 update_checking=true 时，不得声称已是最新版。', inputSchema: {}, annotations: { ...readOnly, openWorldHint: true },
+    description: '检查本机 MCP 与扩展的连接、运行版本和 npm 更新提示。update_available=true 时告知用户重新启动 WriteDock MCP，保留配置；发布任务进行中不要自动重启。旧版服务可能不返回版本字段；latest_version 缺失或 update_checking=true 时，不得声称已是最新版。', inputSchema: {}, annotations: { ...readOnly, openWorldHint: true },
   }, () => wrap(() => bridge.status()))
   server.registerTool('begin_pairing', {
-    description: '首次连接或扩展卸载重装后，生成 3 分钟有效的一次性配对码。让用户粘贴到扩展的 MCP 连接页即可，复用已有 MCP 和 agent 配置。新配对会替换此前浏览器的连接授权，请在用户要求连接扩展时调用。',
+    description: '通常不需要：未连接时，让用户打开 WriteDock 扩展的「连接」页点“连接”即可。只有用户使用旧版扩展时才生成 3 分钟有效的一次性配对码。',
     inputSchema: {}, annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   }, () => wrap(() => bridge.beginPairing()))
   server.registerTool('list_platforms', {
@@ -80,6 +80,48 @@ export function createMcpServer(bridge: LocalBridge) {
     if (!args.draft_id && (!args.kind || !args.title)) throw new Error('请提供 draft_id，或完整的 kind、title 和素材路径')
     return bridge.request('publishPost', { requestId: args.request_id, platforms: args.platforms, ...(args.draft_id ? { draftId: args.draft_id } : { post: await preparePost({ ...args, kind: args.kind!, title: args.title! }, (path, kind) => bridge.registerMedia(path, kind)) }) })
   }))
+  const unifiedInput = {
+    platforms: z.array(z.string().min(1)).min(1).max(30).describe('用户指定的全部平台 ID。扩展按平台分流：知乎、百家号、B站发文章；抖音发图文/视频；微博、小红书有 post 时发图文/视频，否则发长文；公众号、搜狐号只存草稿。'),
+    article: z.object(source).optional().describe('文章内容，file_path/markdown/html 三选一。cover 仅百家号、微博长文使用，其他平台自动忽略并在 warnings 中提示；百家号缺 cover 时用正文第一张图。'),
+    post: z.object(postSource).optional().describe('图文或视频内容，用于小红书、抖音、微博。'),
+    modes: z.record(z.enum(['article', 'post'])).optional().describe('可选：为微博、小红书指定发文章还是图文/视频，如 {"weibo":"article"}。'),
+  }
+  const unifiedParams = async (args: { platforms: string[]; article?: Parameters<typeof prepareSource>[0]; post?: Parameters<typeof preparePost>[0]; modes?: Record<string, string> }) => {
+    if (!args.article && !args.post) throw new Error('请提供 article（文章）或 post（图文/视频）内容')
+    return {
+      platforms: args.platforms, ...(args.modes ? { modes: args.modes } : {}),
+      ...(args.article ? { article: await prepareSource(args.article, path => bridge.registerMedia(path, 'video')) } : {}),
+      ...(args.post ? { post: await preparePost(args.post, (path, kind) => bridge.registerMedia(path, kind)) } : {}),
+    }
+  }
+  server.registerTool('publish', {
+    description: agentWorkflow + '首选的发布工具：一次调用发布到用户指定的多个平台。只有用户明确要求发布并指定平台时才调用。按平台依次执行，某个平台未登录、不能接收内容或失败，只跳过该平台，其他平台继续。遇到验证码时平台进入 waiting_verification，立即把原因和链接告诉用户，由用户手动完成，继续查询即可，不要重发。任务结束后按 get_sync_task 的 summary 逐平台告诉用户：哪些成功，哪些未登录（not_logged_in）等。立即返回 task_id，再用 get_sync_task 查询；results 是逐平台结果，warnings 说明为平台做的调整。必须使用稳定 request_id，相同 ID 不会重复提交。部分平台失败时，只针对失败平台用新 request_id 重新提交，unknown 的平台不要重发。旧版扩展不支持时会报错，不会发布。',
+    inputSchema: { ...unifiedInput, request_id: requestId },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+  }, args => wrap(async () => bridge.request('publish', { requestId: args.request_id, ...await unifiedParams(args) })))
+  server.registerTool('rehearse_publish', {
+    description: '与 publish 参数相同的演练：逐平台打开原生页面，填好内容、上传素材，走到点击发布之前停下，不提交发布。无需 request_id，不影响之后的真实发布。图片可能已上传到平台，部分平台会留下中间草稿，公众号、搜狐号不参与。结果 publicationState=rehearsed 不代表已发布，不得告诉用户内容已发出，也不要自行接着发布。',
+    inputSchema: unifiedInput,
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  }, args => wrap(async () => bridge.request('rehearsePublish', await unifiedParams(args))))
+  const rehearsalNote = '演练：打开原生页面，填好内容、上传素材，走到点击发布之前停下，不提交发布。用于检查平台改版、账号权限和选择器，稿件留在已打开的标签页由用户关闭。图片可能已上传到平台，知乎、百家号、微博长文章会留下中间草稿；最终发布请求和平台回执只有真实发布才能核对。无需 request_id，也不影响之后的真实发布。结果 publicationState=rehearsed 不代表已发布，不得告诉用户内容已发出，也不要自行接着发布。失败时结果带 diagnostics（阶段、页面结构、请求记录）。'
+  server.registerTool('rehearse_article', {
+    description: rehearsalNote + '本工具用于 publish_article 的平台：知乎、百家号、微博长文章、B站专栏、小红书长文，参数规则相同。返回 task_id 后查询 get_sync_task。',
+    inputSchema: { ...source, platforms: z.array(z.string().min(1)).min(1).max(30), draft_id: z.string().optional() },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  }, args => wrap(async () => {
+    if (args.draft_id && Object.entries(args).some(([key, value]) => key in source && value !== undefined)) throw new Error('draft_id 与稿件内容不能同时提供')
+    return bridge.request('rehearseArticle', { platforms: args.platforms, ...(args.draft_id ? { draftId: args.draft_id } : { article: await prepareSource(args, path => bridge.registerMedia(path, 'video')) }) })
+  }))
+  server.registerTool('rehearse_post', {
+    description: rehearsalNote + '本工具用于 publish_post 的平台：小红书、抖音、微博普通图文和视频，参数规则相同。返回 task_id 后查询 get_sync_task。',
+    inputSchema: { ...postSource, kind: postSource.kind.optional(), title: postSource.title.optional(), draft_id: z.string().optional(), platforms: z.array(z.string().min(1)).min(1).max(30) },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  }, args => wrap(async () => {
+    if (args.draft_id && Object.entries(args).some(([key, value]) => key in postSource && value !== undefined)) throw new Error('draft_id 与投稿内容不能同时提供')
+    if (!args.draft_id && (!args.kind || !args.title)) throw new Error('请提供 draft_id，或完整的 kind、title 和素材路径')
+    return bridge.request('rehearsePost', { platforms: args.platforms, ...(args.draft_id ? { draftId: args.draft_id } : { post: await preparePost({ ...args, kind: args.kind!, title: args.title! }, (path, kind) => bridge.registerMedia(path, kind)) }) })
+  }))
   server.registerTool('sync_article', {
     description: '向 list_platforms 返回 action=draft 的用户指定平台保存文章草稿，当前包括微信公众号、搜狐号。知乎、百家号、微博长文章、B站专栏、小红书长文已改用 publish_article；本工具不会把旧草稿调用自动升级成公开发布。可用 prepare_article 返回的 draft_id，或直接传 file_path/markdown/html。必须给同一操作使用稳定 request_id；相同 ID 重放不会重复提交。立即返回 task_id，再用 get_sync_task 查询进度。',
     inputSchema: { ...source, request_id: requestId, platforms: z.array(z.string().min(1)).min(1).max(30), draft_id: z.string().optional() },

package/source/src/setup.ts

@@ -0,0 +1,88 @@
+import { spawn } from 'node:child_process'
+import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { bundledExtension, defaultExtensionDirectory, findInstalledExtension, installExtensionFiles } from './extension-update'
+
+const COMMAND = 'npx'
+const ARGS = ['-y', '--prefer-online', 'writedock-mcp@latest']
+
+async function readIfPresent(path: string) {
+  try { return await readFile(path, 'utf8') }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined; throw error }
+}
+
+async function save(path: string, content: string, previous: string | undefined) {
+  await mkdir(dirname(path), { recursive: true })
+  if (previous !== undefined) await copyFile(path, `${path}.writedock-backup`)
+  await writeFile(path, content)
+}
+
+/** Keeps the user's other settings; an existing WriteDock entry stays, because it may hold a custom port or data directory. */
+export async function configureCodex(path: string): Promise<'added' | 'present'> {
+  const previous = await readIfPresent(path)
+  if (previous !== undefined && /^\s*\[mcp_servers\.writedock\]/m.test(previous)) return 'present'
+  const entry = `[mcp_servers.writedock]\ncommand = "${COMMAND}"\nargs = ${JSON.stringify(ARGS)}\nstartup_timeout_sec = 120\n`
+  await save(path, previous ? `${previous.replace(/\s*$/, '')}\n\n${entry}` : entry, previous)
+  return 'added'
+}
+
+export async function configureJsonClient(path: string): Promise<'added' | 'present'> {
+  const previous = await readIfPresent(path)
+  const config = previous?.trim() ? JSON.parse(previous) as { mcpServers?: Record<string, unknown> } : {}
+  if (config.mcpServers?.writedock) return 'present'
+  config.mcpServers = { ...config.mcpServers, writedock: { command: COMMAND, args: ARGS } }
+  await save(path, `${JSON.stringify(config, null, 2)}\n`, previous)
+  return 'added'
+}
+
+const exists = async (path: string) => (await readIfPresent(path)) !== undefined
+
+/** Best effort: shows the folder so the user can pick it, or drag it onto the extensions page. */
+function revealFolder(path: string) {
+  const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'explorer' : 'xdg-open'
+  try { const child = spawn(command, [path], { detached: true, stdio: 'ignore' }); child.on('error', () => {}); child.unref() } catch { /* The path is printed as well. */ }
+}
+
+/** Only clients already on this computer are configured, so setup never creates settings for an app the user does not have. */
+export async function runSetup(home = homedir(), log: (line: string) => void = console.log) {
+  const clients: { name: string; path: string; detect: string; configure: (path: string) => Promise<'added' | 'present'> }[] = [
+    { name: 'Codex', path: join(home, '.codex/config.toml'), detect: join(home, '.codex/config.toml'), configure: configureCodex },
+    { name: 'Claude Code', path: join(home, '.claude.json'), detect: join(home, '.claude.json'), configure: configureJsonClient },
+    { name: 'Cursor', path: join(home, '.cursor/mcp.json'), detect: join(home, '.cursor/mcp.json'), configure: configureJsonClient },
+    { name: 'Claude Desktop', path: join(home, 'Library/Application Support/Claude/claude_desktop_config.json'), detect: join(home, 'Library/Application Support/Claude/claude_desktop_config.json'), configure: configureJsonClient },
+  ]
+  let found = 0
+  for (const client of clients) {
+    if (!await exists(client.detect)) continue
+    found++
+    try {
+      const state = await client.configure(client.path)
+      log(state === 'added' ? `✓ ${client.name}：已添加 WriteDock（原配置备份为 .writedock-backup）` : `✓ ${client.name}：已有 WriteDock 配置，未改动`)
+    } catch (error) { log(`✗ ${client.name}：配置失败（${error instanceof Error ? error.message : String(error)}），原文件未改动`) }
+  }
+  if (!found) {
+    log('没有找到已知的 agent 客户端。请在你的客户端里添加这个 MCP 服务：')
+    log(JSON.stringify({ mcpServers: { writedock: { command: COMMAND, args: ARGS } } }, null, 2))
+  }
+  // Keep whichever folder the browser already loads, so a repeat setup does not ask for another manual load.
+  const bundle = bundledExtension()
+  const loaded = bundle ? await findInstalledExtension().catch(() => undefined) : undefined
+  let extensionFolder: string | undefined
+  if (bundle) {
+    try { extensionFolder = (await installExtensionFiles(bundle.directory, loaded || defaultExtensionDirectory(home))).directory }
+    catch (error) { log(`✗ 扩展：安装失败（${error instanceof Error ? error.message : String(error)}）`) }
+  }
+  log('')
+  log('接下来：')
+  log('1. 重启你的 agent 客户端，让它加载 WriteDock。')
+  if (extensionFolder && !loaded) {
+    log('2. 在 Chrome 或 Edge 打开 chrome://extensions，打开右上角的“开发者模式”，点“加载已解压的扩展程序”，选择这个文件夹：')
+    log(`   ${extensionFolder}`)
+    revealFolder(extensionFolder)
+    log('3. 打开 WriteDock 扩展，点“连接”。')
+  } else if (extensionFolder) {
+    log(`2. 扩展已更新。在 chrome://extensions 点一次 WriteDock 的刷新图标，然后点“连接”。`)
+  } else log('2. 打开浏览器的 WriteDock 扩展，点“连接”。')
+  return found
+}