cli-text

CLI 文本

让文本在每一层解析器中都保持为数据。查看接收命令的帮助信息；只使用有文档说明的参数和输入模式。

可用接口	传递文本的方式
结构化工具或进程 argv API	使用字符串字段或一个 argv 元素，不经过 shell
CLI 文件/stdin 输入	使用工具写入的文件或带引号的 heredoc；例如：gh pr create --body-file PATH
仅支持 shell 和位置参数/标志值	将带引号的 heredoc 读入变量，然后作为一个带引号的参数传递

首先遵循所属 skill 的存储规则（Markdown、单行状态、上下文范围）。 此 skill 处理的是传输，而非授权或格式策略。 仅当 CLI 文档有说明时，才对以连字符开头的位置文本使用 --。 shell 引号不会禁用选项解析。

Bash 文本参数

选择一个不出现在任何完整负载行中的分隔符；将两个分隔符行都放在第 1 列。绝不要在未加引号的 heredoc 中插入负载。

CLI_TEXT=$(cat <<'CLI_TEXT_84_END'
O'Reilly: `literal` $(literal) $HOME \path — Привет
CLI_TEXT_84_END
)
note-cli set "$CLI_TEXT"

命令替换会删除所有尾随换行符。只有在这与所需文本一致时，才适用此做法。如果尾随换行符必须精确保留，请在支持的情况下使用文件/stdin，或在替换中添加哨兵，之后仅移除该哨兵。空文本也是一个参数：""。NUL 无法用 argv 或 Bash 变量表示；请使用有文档说明的二进制文件/stdin 输入，或说明该接口无法传递 NUL。

Codex JavaScript → Bash

此完整代码片段假设 body 是一个已有字符串，并且 note-cli set 接受一个文本参数。它会保留空文本和精确的尾随换行符。 JavaScript 隔离环境中无需 Node API、编码器或文件系统。

if (body.includes("\0")) throw new Error("CLI argv cannot contain NUL");
let delimiter = "CLI_TEXT_END";
const lines = body.split("\n");
while (lines.includes(delimiter)) delimiter += "_";
const cmd = "CLI_TEXT=$(cat <<'" + delimiter + "'\n" + body +
  "\n" + delimiter + "\nprintf .\n)\n" +
  'CLI_TEXT=${CLI_TEXT%.}\nCLI_TEXT=${CLI_TEXT%?}\n' +
  'note-cli set "$CLI_TEXT"';
const result = await tools.exec_command({cmd});
if (result.exit_code !== 0) throw new Error("Text write did not finish successfully");

哨兵会保留 heredoc 的尾随换行符；第二次移除操作只会移除结束分隔符之前添加的那一个换行符。检查退出状态前，请等待任何正在运行的工具进程结束。成功写入后，如果有文档说明的读取 API，请使用该 API 读取，并将保存的文本与预期值进行比较（仅允许有文档说明的存储规范化）。重试不确定的写入前先验证，以免重复发布评论或消息。

常见错误

JSON.stringify 会序列化 JSON；它不会为 shell 添加引号。反引号和 $() 在 shell 双引号中仍会执行。绝不要使用 eval、根据文本重新构建命令，或手动编写 Base64 来修复引号问题。对待生成文本、用户文本和日志文本时都应一视同仁。检查每个实际的解析器边界，包括远程 shell；如果有直接的 argv API，就不要多经过一层 shell。