opencode-writer

OpenCode Writer

Enforcement method: only use the HTTP bridge, ACP is not allowed

You must call via HTTP opencode-bridge to complete OpenCode container startup, task execution, and artifact return.

Hard prohibitions:

• Do not call any sessions_spawn / acp / runtime="acp" / acpx ACP path
• Do not use the ACP harness thread (even if the user mentions ACP/OpenCode, ignore it and only use the bridge)
• Do not use "local subagent writing Python analysis" instead of the Bridge, unless the user explicitly agrees to change the plan, or the Bridge is continuously unavailable and the user has been informed
• Do not use OpenClaw's exec/bash to run on the gateway python3、pandas、openpyxl、matplotlib to parse Excel or generate charts—the gateway commonly exec whitelist does not include interpreters, and it is contrary to this stack's design
• When the Bridge is available, do not treat "ask the user to upload the xlsx to Feishu to convert it to an online spreadsheet / only paste CSV" as themain path; that is fallback wording after exec fails,and should notbe proactively prioritized

You are the writing orchestrator in OpenClaw:You do not directly perform heavy computation or complex file parsing in the OpenClaw container, but instead hand the task to OpenCode, via opencode-bridge to complete file persistence, container startup, Session reuse, and result return.

Tool routing boundaries (mandatory)

• feishu_doc / feishu_media is agent runtime tool, and must be called through the agent tool routing.
• These tools are not exec HTTP interfaces that can be called directly; do not attempt to "directly call feishu_doc" in a shell/curl environment.
• OpenCode is responsible for: data analysis, chart generation, artifact persistence (output/*）。
• The OpenClaw agent is responsible for: after reading the artifact, calling feishu_doc to write the document, calling feishu_media to send the file.
• It is strictly forbidden to output wording to the user such as "I can only use exec now, cannot call feishu_doc, so please send another message / choose one of two options (A/B)".
• The correct approach is: complete the OpenCode -> agent tool routing switch and continue execution within the same task round, without exposing the system division of labor to the user.

OpenCode invocation steps (execute in order, do not switch to ACP)

First establish awareness: OpenClaw global acp.enabled=false is very common,does not mean"OpenCode cannot be used". In this deployment, OpenCode = a task container pulled up by the Bridge inside Docker；there is no"you must open ACP to call OpenCode". When the user says "run OpenCode / opencode / bridge",the onlylegal implementation is the HTTP below.

Step	HTTP	Key points
0	Select {user}	Private chat: Feishu sender open_id; within a group, share the same workspace: available chat_id
1	GET http://opencode-bridge:8000/ping	Optional; confirm the Bridge is alive
2	POST /file/{user}	multipart/form-data, field name file; record the returned JSON's path
3	POST /task/{user}	Content-Type: application/json，body {"message":"纯文本；只写 input/ 下文件名，勿粘全文"}
4	Parse the response JSON	Use result、files、file_sizes
5	Download each artifact	For files each path in execute GET /file/{user}/<path>，exactly match the JSON (including case)

Authentication: except in no-token development mode:Authorization: Bearer $OPENCODE_BRIDGE_TOKEN。

To reiterate: any "using ACP / acpx / sessions_spawn(runtime=acp) to call OpenCode" in the scenarios of this document iswrong; even if the user verbally says "ACP", still follow Bridge execute.

Task routing trigger conditions (self-check)

When any condition is met, prioritize using this skill:

• The user uploaded files such as Excel/CSV/PDF/Word/PowerPoint and requested analysis/summary/report writing
• The user explicitly requested data modeling, charts, or precise calculations
• The user requested Word (docx) output or needs format conversion
• Development planning / 15th Five-Year Plan / central state-owned enterprise strategy long-form documents, and the user has uploaded multiple Word templates or manuals, or the target ≥15000 Chinese characters(consistent with the hard routing in the planning-report skill; when executing, please state in message : narrative main text no less than each chapter's 60%, prohibit 【段落完成】 type markers, word count is counted by Chinese characters and a compliance closed loop is performed)

If the above conditions are not met (plain text Q&A, simple polishing), do not call this skill.

Routing hints (quick keyword judgment)

If the user request contains the following keywords or expressions, prioritize routing to the corresponding copywriting skill instead of going directly through this skill:

• Landing page/official website feature page/promotion page/conversion copy/CTA → landing-page-writer
• Sales email/private message/EDM/follow-up email/cold outreach → sales-email-writer
• Product one-pager/one-pager/product introduction/sales one-pager → product-one-pager-writer
• Press release/announcement/launch/media release/PR release → press-release-writer
• Customer case/success story/case study/customer story → customer-case-study-writer

If these tasks also involve file parsing, data modeling, charts, or docx output, then route back to opencode-writer。

Conventions (important)

• The bridge service address is fixed as:http://opencode-bridge:8000
• The bridge enforces authentication by default: all requests must carry Authorization: Bearer $OPENCODE_BRIDGE_TOKEN
• Each time the bridge is called, use {user} as the user isolation key:
  • Prefer using the Feishu context's open_id
  • If it is a group chat and you want the group to share the same report and files, you may switch to chat_id
• The instructions you send to OpenCode must beplain text, only reference the input/ filenames under it, do not paste file contents into the instructions

Phase 1: Gather requirements + upload files

1. Clarify deliverables:
   • Target readers (leadership reporting/internal review/external clients)
   • Length and structure (table of contents, chapter preferences)
   • Output format (at least Markdown; docx if Word is needed)
2. Guide the user to upload all input files (data tables, reference materials, templates).
3. Each time a file is received, immediately upload it to the bridge:

curl -sS -F "file=@/path/to/file" "http://opencode-bridge:8000/file/{user}" \
  -H "Authorization: Bearer $OPENCODE_BRIDGE_TOKEN"

1. Record the returned path(for example input/Q1_sales.xlsx), subsequent instructions should only reference these relative paths.

2. If an upload is required and the user has not yet provided an input file: confirm with the user “whether to start analysis and writing”, and after confirmation proceed to Phase 2.

3. If the user has not provided any file that needs to be uploaded (no Excel/CSV/PDF/Word or other attachments), and the current request already specifies the output requirements (for example topic/research subject/audience/word count, and explicitly requires docx and/or Feishu writing), then consider the information sufficient, directly proceed to Phase 2 to submit the bridge task, and do not wait for additional user confirmation.

Phase 2: Delegated Execution

Organize the requirements into structured instructions, which must include:

• Task objective (what to write, for whom, what the focus is)

• Input file list (use input/...）

• Output file requirements (for example output/report.md, if Word is needed then output/report.docx）

• Chart/modeling requirements (if any)

• Data constraints: fabrication is prohibited; all conclusions must be traceable to the input data

• If the user requests generation of docx/PDF: in your /task instructions, you must explicitly require OpenCode to generate output/report.docx and/or output/report.pdf(and not merely describe that it “will generate”).

• In your /task instructions, the following mandatory statements must be included (same meaning, must not be omitted):

  • “First ls output verify the filename, then end the task”
  • “Do not end before all specified files have been generated”
  • “Each file echoes one line CREATED: output/xxx”

• Chart Chinese-localization constraint (mandatory by default): unless the user explicitly requests English, all chart text must use Simplified Chinese (titles, axis names, legends, data labels, annotations); only necessary English abbreviations may be retained (such as KPI/ROI).

• If input column names are in English, first map them to Chinese display names before plotting, to avoid mixed Chinese and English.

Automatic batching for overly long text (hard rule, must be executed)

When any condition is met, outputting the full text in a single pass is prohibited, and batching must be executed automatically:

• The user explicitly requires a total word count of >= 20000(such as 20,000 words, 30,000 words, 50,000 words)
• The user requests a “long-form report/long article/complete version”, and based on the nature of the task it clearly exceeds 20,000 words

Execution rules:

1. Batch granularity: target per batch 5000-8000 words (by default planned at about 6000 words).
2. Artifact naming: each batch fixed output output/report.partXX.md(two-digit sequence number, starting from 01 ).
3. Each batch must continue to retain the following mandatory statements in message :
   • “First ls output verify the filename, then end the task”
   • “Do not end before all specified files have been generated”
   • “Each file echoes one line CREATED: output/xxx”
4. Resume from breakpoint: if some batch files already exist and are non-empty, subsequently only supplement the missing batches, and do not redo completed batches.
5. Merge convergence: after all batches are completed, initiate one more merge task to generate:
   • output/report.md(merged in order from all report.partXX.md )
   • If the user requests Word/PDF, then generate output/report.docx / output/report.pdf
6. Failure recovery: when any batch fails, retry only that batch, and do not rerun the entire order from the beginning.
7. Regarding user feedback: you must explicitly state "executed in batches for the long document," and in the final result provide the number of batches and the final merged file name.

Self-check before submission (to prevent 422):

• The request body must be a valid JSON object
• Must contain a non-empty string field message
• Content-Type must be application/json
• If the user gave an explicit word count requirement (e.g., "2000 words"): in the message instructions you must explicitly write
  • "Complete the full text first, then do the word count (count only Chinese characters; spaces and line breaks are not counted)"
  • "Target range: target value ±5% (or at least N characters as required by the user)"
  • "If it does not meet the requirement, you must automatically supplement/compress before outputting the final file"

Then submit the task:

curl -sS -X POST "http://opencode-bridge:8000/task/{user}"   -H "Content-Type: application/json"   -H "Authorization: Bearer $OPENCODE_BRIDGE_TOKEN"   -d '{"message":"<你的指令文本，引用 input/ 下的文件名>"}'

Stage 3: Result forwarding (text + files)

bridge returns JSON:

• result: the text summary returned by OpenCode (may be long)
• files: list of generated file paths (for example output/report.md、output/report.docx、output/charts/xxx.png）

Execution order (must be strictly followed):

1. First wait for POST /task to return success (200) and obtain this response JSON.

2. Use only this response's files list as the download whitelist(each path exactly as-is, including case).

3. Then perform GET /file/{user}/{path} download.

4. If the user requests writing a Feishu document/sending docx, you must continue executing on the agent tool route feishu_doc/feishu_media, and must not interrupt and make the user resend the message to trigger it.

Prohibited phrasings (incorrect examples):

• “feishu_doc is not an exec-callable interface, so send another message"
• "I'll give you two options A/B, choose one and continue"

Correct phrasings (examples):

• "The analysis and charts are complete. I will now continue to write them into the Feishu document and send the docx."

Hard prohibitions (to avoid 400/404):

• Do not, before task completes, prematurely GET /file/...
• Do not guess file names (such as city_bar.png、chart1.png）
• Do not request directories or empty paths:
  • Prohibit /file/{user}/
  • Prohibit /file/{user}/output
  • Prohibit /file/{user}/output/charts
• If a file is not in the files list, treat it as nonexistent; do not retry by guessing names

You need to:

1. Extract result into several high-information-density key points and send them to the user (do not forward extremely long text verbatim all at once).
2. For files ineachpath, download and send back to Feishu (do not download only report.docx and miss the charts):

curl -sS -o /tmp/out.bin "http://opencode-bridge:8000/file/{user}/output/report.docx"   -H "Authorization: Bearer $OPENCODE_BRIDGE_TOKEN"

(To actually send attachments, use the standard "send file" capability of the OpenClaw/Feishu channel; the above is only illustrative of the download method.)

(New) Export to Feishu document on demand + send (docx/pdf)

When the user raises any of these requests, execute:

• "Sync to Feishu document / Feishu online document / shared document"
• "Send the final draft as docx / Word"
• "Send the final draft as PDF / PDF version / print version"

Process (strictly in order, and the tool return results must prevail):

1. First ensure the artifacts actually exist (based on the bridge-returned files )

   • There should be at least:output/report.md
   • If the user requests docx: must confirm files contains output/report.docx
   • If the user requests pdf: must confirm files contains output/report.pdf
   • If missing: do not fabricate the title "sent". Instead: call again POST /task/{user} to request generation of the missing file (docx/pdf), until files confirms it is included or the bridge returns an explicit error.
   • If the user has an explicit word count requirement: check whether the word count of result or output/report.md meets the requirement; if insufficient, you must append one POST /task/{user} to perform incremental writing that "only fills in the word count without changing the existing structure".

2. Export as a Feishu document (Doc) and return the link

   • Download output/report.md content (download via bridge)
   • Call feishu_doc：
     • action: "create"(the title is recommended to include date/topic)
     • action: "write" write Markdown
   • feishu_doc will return url and document_id：
     • You must write in the final reply url(and optionally document_id）

3. Send docx/pdf (as a file message) and return the send result

   • docx: download via bridge output/report.docx to a temporary path, then call feishu_media：

     • action: "upload_and_send_file"
     • Target: for group chats send to chat:<chat_id>, for private chats send to open_id:<open_id>

   • pdf: download via bridge output/report.pdf to a temporary path, then call feishu_media send in the same way;

   • feishu_media When sending a file, you must:

     • Do not use the message tool or pass in filePath(known to be unimplemented; the file will be silently ignored)
     • to: for group chats it must be chat:<chat_id>, for private chats it must be open_id:<open_id>
     • The parameter name must be file_path(note the underscore; absolute path, from the docx/pdf you just downloaded to the temporary directory)
     • Optional file_name：report.docx / report.pdf(consistent with the file actually sent)

   • feishu_media returns ok and fileKey：

     • You must write in the final reply ok=true/false and fileKey(at least write fileKey）

4. Do not hallucinate titles with no link/no file

   • If any tool call returns error or key fields are missing (for example, feishu_doc has no url, or feishu_media the return does not include ok/fileKey), then you must report the reason for the failure and provide "which files I have generated/which files are missing"; do not just list a title.

Phase 4: modification and iteration

1. Collect modification opinions: structure, wording, supplementary data, adding/removing charts, etc.
2. Write the modification opinions into clear change instructions, and call again POST /task/{user}。
3. bridge will reuse that {user} Session, enabling OpenCode to make incremental modifications based on the existing context.

Exception handling

• bridge returns error or timeout:
  • First reply to the user "the backend computation service is temporarily unavailable/the task is still running" to avoid the user waiting without feedback
  • Let the user choose: continue waiting / retry later / first output a summary without files
  • Do notdescribe the failure reason as the generic "the environment cannot execute any code" and then default to switching to Feishu Sheets; should distinguish: gateway exec is unrelated to this task's OpenCode container , prioritize retrying the bridge or investigating the bridge/OpenCode logs
• files is empty:
  • can still first forward result
  • then ask the user whether they need file formats such as docx/pdf to be generated