From 1aad1afb3b972e463266ba2c37996eb30a677f2e Mon Sep 17 00:00:00 2001
From: Origami404 <Origami404@foxmail.com>
Date: Wed, 8 Apr 2026 22:59:07 +0800
Subject: [PATCH] docs: update usage and clean clippy warnings

---
 README.md              | 58 ++++++++++++++++++++++++++++++++----------
 src/normalize.rs       |  2 +-
 src/render/markdown.rs |  6 ++---
 3 files changed, 48 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 2706de8..e18fb5b 100644
--- a/README.md
+++ b/README.md
@@ -1,31 +1,61 @@
-这是一个读取 gitea PR, 将其内容 (主要是评阅意见) 整理为 LLM 友好的 markdown 文件的项目.
+这是一个读取 Gitea PR，并将其内容整理为 LLM 友好的文档的项目。
 
-使用:
+主要输出两种格式：
+
+1. `markdown`：直接面向 LLM 的可读文档，重点保留 review/comment/reply 内容。
+2. `json`：结构化输出，便于二次处理。
+
+使用：
 
 ```bash
 GITEA_PR_CLI_API_TOKEN=...
 GITEA_PR_CLI_URL=https://gitea.com
-# 或用参数指定 --repo 在最开头
 GITEA_PR_CLI_REPO=Origami404/aaa
-gitea-pr-review <pr-index>
+
+# 默认输出 markdown 到 stdout
+gitea-pr-review fetch <pr-index>
+
+# 输出 json 到 stdout
+gitea-pr-review fetch <pr-index> --format json
+
+# 输出到文件
+gitea-pr-review fetch <pr-index> --format json --out pr.json
+gitea-pr-review fetch <pr-index> --out pr.md
+
+# 从已有 json 重新生成 markdown
+gitea-pr-review render-md --in pr.json
+gitea-pr-review render-md --in pr.json --out pr.md
 ```
 
-返回:
+返回的 markdown 结构大致如下：
 
 `````md
 # <repo> `#<pr-index>` <pr-title>
 
-<各种基本信息, LLM 决定展示形式>
+## Metadata
 
-## Reivew 1 (<review 结果>)
-> <发起人>
+### Commits
+- <sha-short> <title> (<author>, <date>)
+
+### Diff Stat
+- files changed: <n>
+- additions: <n>
+- deletions: <n>
+- <file-path>: +<additions>, -<deletions>
+
+## Review 1 (<review-state>)
+> <reviewer>
 
 ### Comment 1.1
-<文件名>:<行号>
-<用户>: 说了 xxx
-... (后续用户回复)
-
-### Comment 1.2
-...
+<file>:<line>
+<user>:
+```md
+<原始评论正文>
+```
 
+### Reply 1.1.1
+<user>:
+```md
+<原始回复正文>
+```
 `````
diff --git a/src/normalize.rs b/src/normalize.rs
index f6802fd..57d0e28 100644
--- a/src/normalize.rs
+++ b/src/normalize.rs
@@ -58,7 +58,7 @@ fn normalize_threads(comments: Vec<ReviewCommentDto>) -> Vec<CommentThread> {
     grouped
         .into_iter()
         .map(|(thread_id, mut group)| {
-            group.sort_by(|a, b| comment_sort_key(a).cmp(&comment_sort_key(b)));
+            group.sort_by_key(comment_sort_key);
 
             let root = group.remove(0);
             let file_path = root
diff --git a/src/render/markdown.rs b/src/render/markdown.rs
index 8a6a4ba..a118026 100644
--- a/src/render/markdown.rs
+++ b/src/render/markdown.rs
@@ -64,7 +64,7 @@ pub fn render_markdown(doc: &PrReviewDocument) -> String {
         "- merged at: {}\n",
         doc.meta.merged_at.as_deref().unwrap_or("null")
     ));
-    out.push_str("\n");
+    out.push('\n');
 
     out.push_str("## Commits\n\n");
     for commit in &doc.commits {
@@ -73,7 +73,7 @@ pub fn render_markdown(doc: &PrReviewDocument) -> String {
             commit.short_sha, commit.title, commit.author, commit.date
         ));
     }
-    out.push_str("\n");
+    out.push('\n');
 
     out.push_str("## Diff Stat\n\n");
     out.push_str(&format!(
@@ -86,7 +86,7 @@ pub fn render_markdown(doc: &PrReviewDocument) -> String {
             file.path, file.additions, file.deletions
         ));
     }
-    out.push_str("\n");
+    out.push('\n');
 
     for (review_index, review) in doc.reviews.iter().enumerate() {
         out.push_str(&format!(