docs(mdtodo): 收口 CLI 输出渐进披露

2026-07-12 02:28:45 +02:00
parent 756db2a9ea
commit db75577b8f
5 changed files with 48 additions and 8 deletions
@@ -3,18 +3,18 @@
 本文件长期跟踪 UniDesk 高频 CLI 的紧凑默认输出、语义化逐级披露、显式原始输出与错误可见性合同。单个命令、一次 dump 或一个 issue 作为 ITEM 纳入，不以临时故障扩散文件。


-## R1 [in_progress]
+## R1 [completed]

-解决 [UniDesk #1809](https://github.com/pikasTech/unidesk/issues/1809)：收敛 Gitea webhook status、trans --help 及未知/错误命令的高频 dump，建立 compact 默认输出、语义化 drill-down、显式 raw 和无 stack 错误合同；只改只读 CLI 可见性，不新增 mirror、sync、flush、trigger 或 apply。，完成任务后将详细报告写入[任务报告](./details/cli-output-progressive-disclosure/R1_Task_Report.md)。
+解决 [UniDesk #1809](https://github.com/pikasTech/unidesk/issues/1809)：收敛 Gitea webhook status、trans --help 及未知/错误命令的高频 dump，建立 compact 默认输出、语义化 drill-down、显式 raw 和无 stack 错误合同；只改只读 CLI 可见性，不新增 mirror、sync、flush、trigger 或 apply，完成任务后将详细报告写入[任务报告](./details/cli-output-progressive-disclosure/R1_Task_Report.md)。

-### R1.1 [in_progress]
+### R1.1 [completed]

-复现并冻结 [#1809](https://github.com/pikasTech/unidesk/issues/1809) 的输出合同：默认输出有界、repository key/deliveryId drill-down 语义化、--full 域聚合、--raw 显式；trans --help、未知子命令和可预测 option 错误不得回显内部 stack。，完成任务后将详细报告写入[任务报告](./details/cli-output-progressive-disclosure/R1.1_Task_Report.md)。
+复现并冻结 [#1809](https://github.com/pikasTech/unidesk/issues/1809) 的输出合同：默认输出有界、repository key/deliveryId drill-down 语义化、--full 域聚合、--raw 显式；trans --help、未知子命令和可预测 option 错误不得回显内部 stack，完成任务后将详细报告写入[任务报告](./details/cli-output-progressive-disclosure/R1.1_Task_Report.md)。

-### R1.2 [in_progress]
+### R1.2 [completed]

-实现共享 CLI 错误边界与 Gitea webhook 有界逐级披露，复用既有 formatter/命令路由；默认输出给出可执行的语义化 next，不依赖临时 dump，且不增加任何交付或 mirror 写入口。，完成任务后将详细报告写入[任务报告](./details/cli-output-progressive-disclosure/R1.2_Task_Report.md)。
+实现共享 CLI 错误边界与 Gitea webhook 有界逐级披露，复用既有 formatter/命令路由；默认输出给出可执行的语义化 next，不依赖临时 dump，且不增加任何交付或 mirror 写入口，完成任务后将详细报告写入[任务报告](./details/cli-output-progressive-disclosure/R1.2_Task_Report.md)。

-### R1.3
+### R1.3 [completed]

-覆盖 compact/full/raw、repository/deliveryId、错误参数和 trans --help 回归，完成静态验证、非草稿 PR、架构审查与自动交付后原入口验收。，完成任务后将详细报告写入[任务报告](./details/cli-output-progressive-disclosure/R1.3_Task_Report.md)。
+覆盖 compact/full/raw、repository/deliveryId、错误参数和 trans --help 回归，完成静态验证、非草稿 PR、架构审查与自动交付后原入口验收，完成任务后将详细报告写入[任务报告](./details/cli-output-progressive-disclosure/R1.3_Task_Report.md)。
@@ -0,0 +1,9 @@
+# R1.1 任务报告
+
+## 结论
+
+已冻结并验证 #1809 输出合同：默认 Gitea webhook status 为 20 行/2282B；repository/deliveryId 可逐级下钻；`--full` 为 243 行/8061B 的有界域聚合；`--raw` 仅在显式请求时进入受保护 dump。`trans --help` 为 10 行/569B，显式 top/scoped JSON 保留机器合同。
+
+## 错误边界
+
+未知命令、target、option 默认紧凑无 stack；`--json|--full|--raw|-o json` 返回 JSON/no-stack；`UNIDESK_CLI_DEBUG=1` 才披露输入错误 stack；内部异常继续保留 stack。
@@ -0,0 +1,9 @@
+# R1.2 任务报告
+
+## 实现
+
+PR #1815 引入共享 `CliInputError`、显式机器输出判定、紧凑 help renderer、Gitea target/option 输入边界和 webhook status progressive disclosure。`platform-infra-gitea.ts` 按配置、披露、渲染职责拆分，所有源码文件低于 2000 行。
+
+## 架构边界
+
+默认 help 仍只暴露只读 status/history；未新增 mirror、sync、flush、trigger、apply 或人工交付恢复入口。#1814 的 GitFetchCredential、SecretRef、fail-closed 合同保持完整。
@@ -0,0 +1,9 @@
+# R1.3 任务报告
+
+## 验证
+
+两轮独立 gate 最终无 blocker：45 pass、1 个既有 skip、0 fail；主代理定向回归 21 pass、0 fail；真实 PATH、default/full/raw、repository/deliveryId 与错误矩阵全部通过。
+
+## 交付
+
+PR #1815 merge commit 为 `756db2a9eadf2c9a2719469b178b73a200bf32f8`。自动 webhook delivery `ef58630c-7d87-11f1-81a5-c663caef385e` committed；PipelineRun `unidesk-host-nrvt5` Succeeded；GitOps/Argo `22fccab7e497` Synced/Healthy/exact；runtime 1/1。未执行任何手工 CI/CD、mirror、flush、sync、refresh 或 runtime patch。
@@ -0,0 +1,13 @@
+# R1 任务报告
+
+## 完成结果
+
+[UniDesk #1809](https://github.com/pikasTech/unidesk/issues/1809) 已由 PR #1815 完成并自动关闭。高频 help、输入错误和 Gitea webhook status 已从无界 JSON/dump 收敛为人工 compact 默认视图，并保留显式机器输出与语义化 drill-down。
+
+## 证据
+
+- merge：`756db2a9eadf2c9a2719469b178b73a200bf32f8`
+- 自动 PipelineRun：`unidesk-host-nrvt5`，Succeeded
+- GitOps/Argo：`22fccab7e497`，Synced/Healthy/exact
+- runtime：1/1，既有 digest 对齐
+- 最终 issue 评论：https://github.com/pikasTech/unidesk/issues/1809#issuecomment-4949316872