用途
GRACE 4 CLI 用于操作 GRACE 4 项目，围绕 .grace 文件提供 lint 检查、状态查询、模块导航、验证导航以及文件级语义标记等能力。它面向需要以命令行方式对 GRACE 治理文档进行校验和导航的场景。
主要能力
- lint 检查：对 .grace 进行校验，并可通过 --run-commands 执行声明的 MustPassCommand。
- 状态查询：提供 grace status 等生命周期命令。
- 模块导航与验证导航：支持在 GRACE 结构中定位模块与验证信息。
- 文件级语义标记：支持文件局部的语义标记。
- 命令运行契约：--run-commands 对每个声明的 MustPassCommand 值每次 lint 执行一次，快速失败，默认每条命令超时 600 秒，可用 --command-timeout SECONDS 覆盖，设为 0 则禁用超时。
- 输出分离：计划、进度和逐条命令结果行输出到 stderr；lint 报告和 JSON 输出到 stdout，因此管道 stdout 是安全的。
- 输出模式：代理和管道默认获得紧凑输出；交互式终端看到实时流式命令输出。可用 --verbose（实时）或 --quiet（紧凑）强制模式，二者互斥；--format json 始终为紧凑格式。
- 运行日志：每次运行的完整合并输出保存在 ~/.cache/grace/run-commands/<project>/runs/<run>/（遵循 XDG_CACHE_HOME），并带有机器可读的 meta.json；失败命令会打印有界输出尾部以及绝对日志路径。
- meta.json 内容：记录该次运行所针对的 VCS 身份（head、branch、dirty，在 git 仓库外均为 null）以及写入进程 pid；在运行开始时以 status running 写入，完成时重写；若某条 running 记录的进程已不存在，则在后续运行中被重新归类为 killed。
- 日志修剪：每个变更的最新通过运行会被无限期保留，因此已归档变更引用的证据仍留在磁盘上；保留计数仅适用于非通过运行——失败、超时、中断、被同一变更的更新通过运行取代、未绑定到变更或缺少可读 meta.json 的运行。计数默认为 10，可通过 .grace-lint.json 中的 runLogRetention 项目级设置，也可通过 --keepRuns N 按运行覆盖。--keepRuns 0 完全不保留非通过运行，这会在当前运行失败时立即删除它，并使其打印的日志路径悬空。
- 中断处理：被中断的运行（SIGINT/SIGTERM）会杀死整个命令进程组，在 meta.json 中记录 interrupted 状态，并以 130 退出。
使用方式
通过命令行调用 GRACE 4 CLI 的相应子命令进行 lint、status、导航等操作。使用 --run-commands 时，需在配置中声明 MustPassCommand 条目。运行日志位于 ~/.cache/grace/run-commands/ 下，可通过 .grace-lint.json 的 runLogRetention 或 --keepRuns 控制保留数量。
适用场景
适用于需要对 GRACE 4 项目进行命令行治理、校验和导航的开发与维护场景，尤其是希望在 CI 或脚本中安全使用 stdout 管道、并保留可追溯运行证据的工作流。
限制与边界
- 生命周期命令契约：current 评估的是活跃的已批准基线，不是终态证据。MustPassCommand 条目应保持为叶子项目检查；不要在 plan 断言中嵌套 grace lint、grace status 或另一个 GRACE 生命周期命令。选定的 target/final lint 需在外部运行。
- 失败契约：lint、status 和导航命令在返回记录前会先校验。JSON 参数/运行时失败会在 stdout 输出单个 { "schemaVersion": "1.0.0", "ok": false, "error": { ... } } 对象。文本失败为一行简洁可操作的信息，带非零退出码，无堆栈跟踪。
- 运行时契约：TypeScript/JavaScript 分析已内置。Python 和 Dart 受治理文件需要其运行时在 PATH 中；缺少运行时会以可操作的 analysis.runtime-missing 诊断失败关闭，而不是静默丢弃一致性检查。
- 迁移边界：GRACE 4 命令不会双重校验旧版 GRACE 3 文档，需使用 grace-migrate。
暂未提供
官方文档、安装命令、具体子命令语法、配置字段完整列表、平台支持范围、收费与价格信息暂未提供。