design-cli-output使用 chalk 颜色、Unicode 图形符号、多个详细级别（human、verbose、quiet、JSON） 和一致的语调规则为 CLI 工具设计终端输出。涵盖配色板选择、状态指示器设计、 reporter 函数架构、ceremony/叙事输出变体，以及跨终端兼容性。当构建新的 CLI reporter 模块、向现有工具添加温暖叙事输出、跨多个命令标准化输出， 或设计与人类可读文本并行的机器可读 JSON 时使用。
Independent GitHub snapshot · Automated classification · Original documentation governs
为命令行工具设计一致的、多级别的终端输出。
使用 chalk 创建命名的配色板对象。
加载 chalk 时带上无颜色后备。 后备必须替代配色板所使用的每一种调用形态，而这不止于原样传回字符串：
// A factory returns a *function*; a direct style returns a string. Enumerate
// this list against the installed chalk, not from memory — chalk 6 added the
// three underline* variants, and a list that omits them is wrong for those names.
const FACTORIES = new Set(['ansi256', 'bgAnsi256', 'bgHex', 'bgRgb', 'hex',
'rgb', 'underlineAnsi256', 'underlineHex', 'underlineRgb']);
function makeChalkStub() {
return new Proxy((text) => text, {
get(target, prop) {
if (prop === 'then') return undefined; // must not be a thenable
if (prop === 'level') return 0; // no color support, truthfully
if (typeof prop === 'symbol') return Reflect.get(target, prop);
return FACTORIES.has(prop) ? () => makeChalkStub() : makeChalkStub();
},
});
}
let chalk;
try { chalk = (await import('chalk')).default; }
catch { chalk = makeChalkStub(); }
四条不变量，更简短的 stub 每一条都会弄错：
(text) => text，不是 {}。链式调用（chalk.bold.cyan('x')）要求每一跳既可索引又可调用。new Proxy({}, { get: () => (s) => s }) 满足直接样式却破坏工厂函数：此时 chalk.hex('#FF6B35') 是字符串 '#FF6B35'，调用它会抛出 TypeError: ... is not a function。配色板在模块加载时构建，因此这种后备会在 import 时就让工具崩掉 —— 而这恰恰是本应降级为纯文本的场景。then 必须是 undefined。 若 stub 对每个属性都返回一个函数，await chalk 会永久挂起：运行时会调用 .then，然后等待一个无人触发的回调。Node 会报告 Detected unsettled top-level await 并以 13 退出。level 必须是数字。 能力开关读取 chalk.level >= 1；返回真值的 stub 会打开这些开关，而其背后并无颜色支持。用这次 import 之后存活下来的那个对象来构建配色板。
标准配色板（事务性输出）：
// Status colors
const ok = chalk.green; // success
const fail = chalk.red; // errors
const warn = chalk.yellow; // warnings
const info = chalk.cyan; // identifiers, names
const dim = chalk.dim; // secondary info, paths
const bold = chalk.bold; // headers
温暖配色板（ceremony/叙事输出）：
const C = {
flame: chalk.hex('#FF6B35'), // active elements, fire
amber: chalk.hex('#FFB347'), // arriving items, warm highlights
spark: chalk.hex('#FFF4E0'), // individual items (sparks/skills)
ember: chalk.hex('#8B4513'), // cold/dormant states
warm: chalk.hex('#D4A574'), // neutral warm text
dim: chalk.dim, // background, secondary
fail: chalk.red, // errors stay red (honest)
};
配色板设计规则：
chalk.hex('#FF6B35')）预期结果： 一个带有命名条目的配色板对象，以及一个已被实际执行过、而非仅仅写出来的后备。
失败处理： 直接演练后备路径；配色板不是发现它已损坏的合适位置。在 stub 处于作用域内时：
console.assert(chalk.dim('x') === 'x'); // direct style
console.assert(chalk.hex('#fff')('x') === 'x'); // factory — the usual defect
console.assert(chalk.bold.cyan('x') === 'x'); // chain
console.assert(chalk.level === 0); // capability gate stays shut
await chalk; // must not hang
NO_COLOR=1 覆盖不到这一点。它演练的是一个可用的 chalk 选择不输出转义码；而后备演练的是一个 import 失败的 chalk。两条路径不共享任何代码。带注释的生产级 stub、该缺陷的复现，以及上述检查的可运行版本，请参阅扩展示例。
为状态通信选择 Unicode 图形符号或 ASCII 字符：
ASCII（最大兼容性）：
+ created/installed (green)
- removed/deleted (red)
= skipped/unchanged (dim)
! error/warning (red)
Unicode（更丰富，需要 UTF-8 终端）：
✦ item/skill/practice (spark)
◉ active/burning state
◎ cooling/embers state
○ cold/dormant state
◌ available/not installed
✗ failed item
✓ success (use sparingly — not all terminals render it well)
选择标准：
--ascii 标志或 NO_COLOR 检测同时提供两者预期结果： 一组无需仅依赖颜色就能一目了然传达状态的图形符号。
失败处理： 若图形符号在测试中渲染为 ? 或方框，替换为 ASCII 等价物。+/-/=/! 集到处都能用。
每个命令应支持四个输出级别：
| 级别 | 标志 | 受众 | 内容 |
|---|---|---|---|
| 默认 | （无） | 终端前的人 | 格式化、有颜色、信息丰富 |
| 详细 | --verbose 或 --ceremonial | 想要细节的人 | 逐项分解、到达序列 |
| 安静 | --quiet | 脚本、CI | 最少行数、状态图标、无装饰 |
| JSON | --json | 机器消费者 | 结构化、可解析、完整 |
实现模式：
function output(data, options) {
if (options.json) {
console.log(JSON.stringify(data, null, 2));
return;
}
if (options.quiet) {
for (const item of data.items) {
const icon = item.ok ? '+' : '!';
console.log(`${icon} ${item.id}`);
}
return;
}
// Default (or verbose) human output
printFormatted(data, { verbose: options.verbose });
}
JSON 输出规则：
预期结果： 四个清晰的输出级别，跨命令行为一致。
失败处理： 若 verbose 模式过于嘈杂，使其需主动选择（--ceremonial）而非分级的详细级别。
定义所有输出函数遵循的语调和风格。这可以防止跨命令不一致。
示例语调规则（来自 campfire reporter）：
标准（非 ceremony）输出的语调规则：
预期结果： 一组书面的 3-7 条语调规则，输出函数必须遵守。
失败处理： 若规则感觉武断，测试它们：在使用与不使用每条规则的情况下编写相同输出。若移除规则不改变输出质量，规则不需要。
将输出组织到 reporter 模块中，每个函数职责清晰：
// reporter.js — standard output
export function printResults(results) { ... }
export function printItemTable(items) { ... }
export function printDetections(detections) { ... }
export function printAudit(auditResults) { ... }
export function printDryRun() { ... }
export function warn(msg) { ... }
export function error(msg) { ... }
export { chalk };
每个函数遵循相同结构：
对于 ceremony 输出，创建单独模块：
// campfire-reporter.js — warm narrative output
export function printArrival({ teamId, agents, results, ceremonial }) { ... }
export function printScatter({ teamId, agents, results }) { ... }
export function printTend(fires) { ... }
export function printCampfireList({ teams, state, reg }) { ... }
export function printFireSummary({ team, fireData, reg }) { ... }
export function printJson(data) { ... }
预期结果： 可独立使用的 reporter 函数 —— 每个处理自己的格式化，不依赖调用者状态。
失败处理： 若函数超过约 50 行，提取辅助函数。reporter 函数应能独立审查。
验证输出在不同上下文中正确渲染：
# With colors (interactive terminal)
node cli/index.js list --domains
# Without colors (piped)
node cli/index.js list --domains | cat
# With NO_COLOR environment variable
NO_COLOR=1 node cli/index.js list --domains
# JSON mode (parseable)
node cli/index.js campfire --json | jq .
# In CI (typically no TTY)
CI=true node cli/index.js audit
# The no-color fallback. A failed import cannot be provoked with an env var, so
# assert on the stub itself in the suite rather than reaching it through the CLI.
# Pass a glob, not a directory: `node --test <dir>` stopped expanding at Node 22.
node --test 'cli/test/*.test.js'
检查：
jq . 验证）预期结果： 输出在所有六种上下文中都正确。
失败处理： 若 ANSI 码泄漏，确保 chalk 尊重 NO_COLOR。若 Unicode 损坏，提供 ASCII 后备模式。注意：绿色的测试套件对颜色本身两个方向都什么也说明不了 —— 测试运行器会把 stdout 接入管道，这会让 chalk.level 变成 0，于是有颜色和无颜色的输出逐字节相同，即便颜色彻底坏掉断言依然通过。要证明颜色可用，需要 FORCE_COLOR=3 并对转义序列做断言。
level === 0、await 全部检查通过jq 解析new Proxy({}, { get: () => (s) => s }) 读起来很完整，也确实覆盖了 chalk.dim 和 chalk.red，但此后每个工厂函数都返回一个字符串，而调用者紧接着就要去调用它。由于配色板在模块加载时构建，TypeError 会落在 import 时 —— 后备恰恰在它唯一存在意义的那个场景里败得最惨。第 1 步列出了 stub 必须满足的四条不变量。--json 模式下，仅输出有效 JSON。一行散漫的文本（如 "DRY RUN"）会破坏 JSON 解析器。若命令必须显示两者，清晰分离或在 JSON 模式下抑制人类文本。Math.max(...items.map(i => i.id.length)) 动态计算填充。+、OK、ERR）。--quiet 模式下，它增加噪声。将 ceremony 输出放在显式标志后。scaffold-cli-command —— 使用此输出的命令test-cli-application —— 测试输出与预期匹配build-cli-plugin —— 插件通过此输出系统报告结果