BigPizzaV3/CodexPlusPlus · error

历史消息接口返回格式无效

Error message

历史消息接口返回格式无效

What it means

readNativeHistory pages through a thread's items via the native `thread/items/list` RPC. After the call returns, it requires `page.data` to be an array; if the response is null, missing `data`, or `data` is not an array, it throws this error to fail fast on a malformed/unrecognized wire contract instead of producing silently corrupted history.

Solutions

  1. Update the plugin to a version matching the installed Codex Desktop build (the history wire contract is version-pinned).
  2. Log the raw `page` object at the throw site to inspect the actual response shape and confirm which field replaced `data`.
  3. If the response shape changed, adapt native-history.mjs to read the new field (e.g. `page.items`) or normalize it into `data`.
  4. Retry after fully reloading/restarting the Codex Desktop app to rule out a transient truncated response.

Example fix

// before
if(!Array.isArray(page?.data))throw Error('历史消息接口返回格式无效');
// after
const rows=page?.data??page?.items;
if(!Array.isArray(rows))throw Error('历史消息接口返回格式无效');
Defensive patterns

Strategy: try-catch

Validate before calling

if(!resp||!Array.isArray(resp.data))return [];

Type guard

function isValidPage(p){return p!=null&&Array.isArray(p.data);}

Try / catch

try{page=await send('thread/items/list',{threadId,turnId,cursor,limit,sortDirection:'asc'});}catch(e){console.warn('items/list response shape:',page);return cachedMessages;}

Prevention

When it happens

Trigger: The `send('thread/items/list', {threadId, turnId, cursor, limit, sortDirection:'asc'})` call resolves with an object whose `.data` is absent or not an Array — e.g. the native Desktop API returns `{items:[...]}` or `{error:...}` instead of `{data:[...]}` after a Codex Desktop update changed the response shape, or a failed/incomplete response object is passed through without rejecting.

Common situations: Codex Desktop upgraded to a build whose thread/items/list payload no longer uses `data`; a relay/proxy in front of the API returns an error JSON body that still resolves; the plugin's wire-contract comments (verified against a specific installed Desktop version) no longer match the installed version.

Related errors

AI-assisted analysis of BigPizzaV3/CodexPlusPlus@b1ed92e5e4 (2026-09-19). Data as JSON: /api/errors/3177e450d4d87e4a. Report an issue: GitHub.

Appendix: source

Thrown at tools/conversation-canvas/native-history.mjs:45

    signal?.throwIfAborted();onProgress(`正在读取历史 ${index+1}/${turns.length}…`);
    const key=`${threadId}:${turn.id}`,cached=await cache.get(key);
    let parsed;
    if(cached&&turn.status==='completed')parsed=cached;
    else{
      const partial=turn.status==='completed'?await cache.get(`${key}:partial`):null;
      parsed=partial?.messages?.slice()||[];let itemCursor=partial?.cursor??null,limit=32;const cursors=new Set();
      do{
        signal?.throwIfAborted();
        if(cursors.has(itemCursor))throw Error('历史消息分页游标重复');
        let page;
        for(;;){
          try{page=await send('thread/items/list',{threadId,turnId:turn.id,cursor:itemCursor,limit,sortDirection:'asc'});break;}
          catch(error){
            if(limit>1&&/decoded message length too large/i.test(error.message)){limit=Math.max(1,Math.floor(limit/2));continue;}
            throw error;
          }
        }
        if(!Array.isArray(page?.data))throw Error('历史消息接口返回格式无效');
        cursors.add(itemCursor);
        for(const row of page.data){
          if(row.turnId!=null&&row.turnId!==turn.id)throw Error('历史消息所属轮次不匹配');
          const item=row.item??row;
          if(!['userMessage','agentMessage'].includes(item.type))continue;
          if(typeof item.id!=='string')throw Error('历史消息缺少稳定 ID');
          const role=item.type==='userMessage'?'user':'assistant';
          const content=role==='user'?(item.content??[]):[{text:item.text??''}];
          const message=parseMessage({type:'response_item',payload:{type:'message',id:item.id,role,phase:role==='assistant'?(item.phase??'final_answer'):'',content}},item.id);
          if(message)parsed.push({...message,turnId:turn.id,turnStatus:turn.status});
        }
        itemCursor=page.nextCursor??null;
        onProgress(`正在读取历史 ${index+1}/${turns.length} · 已读 ${parsed.length} 条消息…`);
        if(turn.status==='completed'&&itemCursor!==null)await cache.set(`${key}:partial`,{messages:parsed,cursor:itemCursor});
      }while(itemCursor!==null);
      if(turn.status==='completed'){await cache.set(key,parsed);await cache.delete(`${key}:partial`);}
    }
    // Older completed-turn caches contain text and IDs but no turn metadata.

View on GitHub (pinned to b1ed92e5e4)