From 9da6b248b53771133ff4aabd03b7ff57bef7af3c Mon Sep 17 00:00:00 2001
From: Origami404 <Origami404@foxmail.com>
Date: Wed, 8 Apr 2026 22:39:18 +0800
Subject: [PATCH] docs: refine CLI design with render-md subcommand

---
 .../2026-04-08-gitea-pr-review-design.md      | 58 ++++++++++++++-----
 1 file changed, 43 insertions(+), 15 deletions(-)

diff --git a/docs/superpowers/specs/2026-04-08-gitea-pr-review-design.md b/docs/superpowers/specs/2026-04-08-gitea-pr-review-design.md
index 36e562e..a413a1f 100644
--- a/docs/superpowers/specs/2026-04-08-gitea-pr-review-design.md
+++ b/docs/superpowers/specs/2026-04-08-gitea-pr-review-design.md
@@ -28,6 +28,7 @@
 2. 生成 Markdown 输出，结构遵循 `README.md` 约定。
 3. 生成 JSON 输出，字段可追溯到源 API 实体。
 4. 处理评论正文为 Markdown 的情况，避免破坏外层文档结构。
+5. 提供 `json -> markdown` 子命令，从 JSON 文件渲染出与主流程一致的 Markdown 文档。
 
 ### 2.2 Out of Scope
 
@@ -66,7 +67,7 @@
 
 1. `cli`
    - 解析参数与环境变量。
-   - 决定输出格式与输出路径。
+   - 处理子命令分发与输出目标（默认 stdout）。
 2. `gitea_client`
    - 仅负责 API 调用与分页。
    - 返回原始 DTO（与 API 字段接近）。
@@ -77,6 +78,8 @@
    - 将 `PrReviewDocument` 渲染为 Markdown。
 5. `render_json`
    - 将 `PrReviewDocument` 序列化为稳定 JSON。
+6. `input_json`
+   - 从 JSON 文件反序列化为 `PrReviewDocument`。
 
 ### 4.2 核心数据模型（内部）
 
@@ -126,6 +129,13 @@ CommentThread
    - Markdown: 面向阅读。
    - JSON: 面向程序消费。
 
+### 5.1 子命令数据流
+
+1. `fetch` 子命令（主流程）:
+   - `fetch -> normalize -> render(markdown|json) -> stdout/--out`
+2. `render-md` 子命令:
+   - `read json file -> deserialize(PrReviewDocument) -> render(markdown) -> stdout/--out`
+
 ## 6. Markdown 输出规范
 
 目标: 对齐 `README.md` 给出的基础结构，保证评论内容完整。
@@ -135,16 +145,18 @@ CommentThread
 ````md
 # <repo> `#<pr-index>` <pr-title>
 
-<基本信息区>
+<pr 描述>
 
-## Commits
+## Metadata
+
+### Commits
 - <sha-short> <title> (<author>, <date>)
 ...
 
-## Diff Stat
-- files changed: <n>
-- additions: <n>
-- deletions: <n>
+### Diff Stat
+total: <files_changed> files, +<additions>, -<deletions>
+- <file-path>: +<additions>, -<deletions>
+...
 
 ## Review 1 (<review-state>)
 > <reviewer>
@@ -246,7 +258,14 @@ CommentThread
 
 ## 8. CLI 与配置
 
-### 8.1 输入
+### 8.1 子命令
+
+1. `fetch <pr_index>`
+   - 从 Gitea 拉取并输出文档。
+2. `render-md --in <json_path>`
+   - 从 JSON 输入渲染 Markdown。
+
+### 8.2 输入配置（`fetch`）
 
 1. 必填:
    - `pr_index`（位置参数）
@@ -255,11 +274,15 @@ CommentThread
    - `GITEA_PR_CLI_URL`
    - `GITEA_PR_CLI_REPO`
 
-### 8.2 输出参数（新增）
+### 8.3 输出参数
 
-1. `--format markdown|json|both`（默认 `markdown`）
-2. `--out <path>`（单输出文件）
-3. `--out-dir <dir>`（`both` 时用于分文件输出）
+1. `--format markdown|json`（默认 `markdown`，仅 `fetch` 支持）
+2. `--out <path>`（可选；未提供时默认输出到 stdout）
+
+约束:
+
+1. 移除 `both` 选项。
+2. 移除 `--out-dir` 参数。
 
 ## 9. 错误处理策略
 
@@ -269,6 +292,9 @@ CommentThread
    - 评论缺父节点: 降级为孤立线程并 warning。
    - 分支或 commit 字段缺失: 输出 `null` 并 warning。
 4. 渲染错误: 指出是 Markdown 还是 JSON 渲染失败。
+5. `render-md` 输入错误:
+   - JSON 文件不存在/不可读时，返回非 0 并指明路径。
+   - JSON schema 不匹配时，定位字段并返回非 0。
 
 ## 10. 测试策略
 
@@ -276,6 +302,7 @@ CommentThread
    - 线程聚合（正常链路、孤立回复、乱序输入）。
    - Markdown fence 选择逻辑（三反引号冲突场景）。
    - JSON 序列化稳定性（字段与顺序）。
+   - `render-md` 反序列化与渲染一致性。
 2. 快照测试
    - 固定输入 DTO -> Markdown 输出快照。
 3. 集成测试
@@ -286,7 +313,7 @@ CommentThread
 1. M1: 完成 `gitea_client` + DTO。
 2. M2: 完成 `normalize` 与线程规则。
 3. M3: 完成 Markdown 渲染并对齐 README 结构。
-4. M4: 完成 JSON 输出。
+4. M4: 完成 JSON 输出与 `render-md` 子命令。
 5. M5: 补齐测试与错误处理。
 
 ## 12. 验收标准
@@ -298,5 +325,6 @@ CommentThread
    - diff stat
    - review/comment/reply 完整正文
 2. 能输出 JSON 且字段完整、顺序稳定。
-3. 评论正文含 Markdown/代码块时，Markdown 总文档结构不被破坏。
-4. 关键异常路径有清晰错误信息并返回非 0。
+3. `render-md --in <json_path>` 能从 JSON 成功产出 Markdown，且结构与 `fetch --format markdown` 一致。
+4. 评论正文含 Markdown/代码块时，Markdown 总文档结构不被破坏。
+5. 关键异常路径有清晰错误信息并返回非 0。