| 项 | 值 |
|---|---|
| 规范编号 | SPEC-012 |
| 标题 | 面向人的输出的形态:两条流、两种介质、行的种类、颜色 |
| 状态 | 评审中 v1.0 |
| 版本 | 1.0 |
| 最后修改 | 2026-10-26 |
| 对应实现 | mcpp >= 2026.10.26.1 |
| 相关设计文档 | .agents/docs/2026-09-29-build-progress-display-design.md、.agents/docs/2026-09-30-build-output-refinement-design.md、.agents/docs/2026-10-26-control-contract-runtime-and-ide-ecosystem-design.md §5.7、§5.9 |
| 使用文档 | 50 — 机器可读输出 §3 |
用语按 RFC 2119:必须 / 禁止为强制,应当为建议,可以为可选。
本规范约束面向人的输出的形态:哪一条流、什么介质、哪几种行、何时有颜色。它不约束 逐字内容;面向人的输出没有兼容承诺,程序读取的是 docs/50 的信封与记录。agent 与 CI 读到的是管道中的输出, 因此管道中的形态与终端中的形态同等重要。
标准输出携带命令的结果(程序的输出、文档、列表、mcpp test 的报告);标准错误携带
叙述(状态行、进度、warning:、error:、note:、tip:、编译器诊断)。划分规则与
例外见 docs/50 §3。--quiet 去掉叙述,保留警告、错误与诊断。
- 终端介质:标准错误是能移动光标的终端时,构建在输出下方保留一行状态行,只有这一行 被原地重绘;已经写出的行禁止被改写、重新着色或移动。
- 日志介质:管道、文件、
TERM=dumb、不支持虚拟终端序列的控制台。禁止写出任何 光标移动或回车重绘序列;行在内容确定后写出一次。构建静默 60 s 后追加一行心跳 (Building <完成>/<总数> · <时钟>),之后每 60 s 至多一行。
| 种类 | 形式 | 用途 |
|---|---|---|
| 状态行 | 右对齐到第 12 列的一个词,后接主体: Compiling app v0.1.0 (.) |
命令正在做或已经做完的事 |
| 消息行 | error: …、warning: …、note: …、tip: … |
mcpp 自己的判断 |
| 续行 | 缩进到消息正文的列 | 消息的细节、列表 |
| 补救行 | help: … |
读者下一步可以执行的命令或要改的键 |
| 诊断 | 编译器、链接器的原文 | 内容本身 |
- 状态行的词:进行中的工作用现在分词(
Resolving、Compiling、Running、Waiting、Packing、Installing),完成的工作用过去分词(Finished、Packed、Installed), 报告的事实用名词标签(Home、Default)。构建的主线固定为Resolving→Compiling→Finished,run另有Running。 - 一条错误存在可执行的下一步时,必须以一行
help:给出;下一步是一条命令时,写出 完整的命令。外部工具(xlings)给出的补救按原样转述。 - 带位置的消息必须以
<path>:<line>:<col>:或<path>:开头,与编译器诊断同形, 编辑器与终端可以直接跳转;信封中的诊断由此得到path与range(docs/50 §2)。 - 编译器诊断必须原样完整输出,mcpp 禁止截断或改写;mcpp 自己的列表应当
有上限,并说明省略了多少(
… and N more)。
优先级从高到低:
MCPP_NO_COLOR=1或非空的NO_COLOR:关闭。CLICOLOR_FORCE非空且不为0,或FORCE_COLOR非空且不为0、false:开启, 管道同样开启。状态行仍只在终端介质中绘制。- 否则:终端开启,管道关闭。
颜色只修饰状态行的词、消息行的前缀与强调,禁止承载其他地方没有的信息。
| 版本 | 日期 | 变更 |
|---|---|---|
| 1.0 | 2026-10-26 | 首版:两条流、两种介质、行的种类(help: 统一补救行)、颜色的优先级 |