large-file-write-heredoc
Reliable fallback technique for writing large file contents when write_file and shell_agent both fail with 'unknown error' due to payload size limits — uses run_shell with a Python heredoc to bypass tool constraints.
- License 许可
- MIT
- 所属仓库
- HKUDS/AgentPilot
- 最近更新
- 2026-11-12
- Stars
- ★ 8.0k
- Forks
- 944
01 前言 Front Matter
- name
- large-file-write-heredoc
- description
- Reliable fallback technique for writing large file contents when write_file and shell_agent both fail with 'unknown error' due to payload size limits — uses run_shell with a Python heredoc to bypass tool constraints.
02 资源文件 1
- 其他.skill_id39 B
03 SKILL.md 正文
Large File Write Fallback
Problem
When writing large files (typically several KB or more), two common tools may
fail with unknown error due to internal payload size limits:
write_file— has a maximum content size it can handle in a single call.shell_agent— may also hit payload limits when the task description includes large inline content.
Solution
Use run_shell with a Python heredoc pattern. This streams the file
content through stdin directly into Python's open(), bypassing the payload
constraints of the other tools.
Template
python3 - << 'EOF'
content = """<FILE CONTENTS HERE>"""
with open("<TARGET PATH>", "w") as f:
f.write(content)
EOF
Pass this as the command parameter to run_shell.
Step-by-Step Instructions
-
Attempt the normal write using
write_filefirst. If it succeeds, you are done. -
If
write_filefails (especially withunknown erroror a timeout on large content), do NOT retry withshell_agentusing inline content — it will likely fail for the same reason. -
Use the
run_shellheredoc fallback:- Embed the full file content inside a Python triple-quoted string.
- Specify the target path inside the
open()call. - Pass the entire block as the
commandtorun_shell.
-
Escape carefully inside the heredoc:
- Backslashes that should be literal in the file must be doubled (
\\). - Triple-quotes inside the content must be escaped (
\"\"\"). - The heredoc delimiter
EOFmust not appear on a line by itself inside the content (rename it toPYEOForFILEEOFif needed).
- Backslashes that should be literal in the file must be doubled (
-
Verify the write by following up with a
run_shellcall such as:wc -l <TARGET PATH> && head -5 <TARGET PATH>
Full Example
Suppose you need to write a large TypeScript file to
src/components/Dashboard.ts:
python3 - << 'PYEOF'
content = """import { foo } from './foo';
export interface DashboardData {
title: string;
items: string[];
}
export function createDashboard(data: DashboardData): string {
return `<div>${data.title}</div>`;
}
"""
with open("src/components/Dashboard.ts", "w") as f:
f.write(content)
PYEOF
Pass the above (without the surrounding code fence) as the command
argument to run_shell.
When to Use This Pattern
| Situation | Recommended tool |
|---|---|
| Small file (< ~2 KB) | write_file |
| Medium file, no errors yet | write_file (try first) |
Large file or write_file failed |
run_shell + Python heredoc |
shell_agent also fails on large inline content |
run_shell + Python heredoc |
Notes
- This pattern works for any text-based file (TypeScript, Python, JSON, YAML, Markdown, etc.).
- For binary files, adapt the approach to use
base64decoding inside the Python script. - The heredoc delimiter (
EOF,PYEOF,FILEEOF) can be any string not present as a standalone line in your content — choose accordingly. - This technique is also useful when content contains characters that would
need heavy shell escaping in a plain
echoorprintfapproach.
04 同仓库更多 Skills
agentpilot
Set up AgentPilot and use its single entry to prepare missing inputs and run configured RSI experiments. Use when the user requests AgentPilot installation or work with AgentPilot.
remember
Review auto-memory entries and propose promotions to OPENSPACE.md, OPENSPACE.local.md, or retained auto-memory topics; detect duplicates, stale facts, conflicts, and ambiguous entries before making changes.
skill-discovery
Search reusable OpenSpace skills locally, and browse cloud packages step by step when a cloud skill may help. Reusing proven skills saves tokens, improves reliability, and extends your capabilities beyond built-in tools.
delegate-task
Delegate tasks to OpenSpace — a full-stack autonomous worker for coding, DevOps, web research, and desktop automation, backed by an extensive MCP tool and skill library. Skills auto-improve through use, reducing token consumption over time. A cloud community lets agents share and collectively evolve reusable skills.
write-special-chars-ts-check
Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) using a Python heredoc script, plus a reliable TypeScript type-checking step that filters output to only the newly-written files to avoid being misled by pre-existing errors.
write-special-chars-readback
Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) using a Python heredoc script, with mandatory post-write verification via read_file and cleanup of /tmp helper scripts.