diff --git a/README.md b/README.md index a85ce2e..b5251c7 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,13 @@ MiniMax、Kimi（Moonshot）和智谱 GLM 使用专用 API 端点 — 选择供 - **构建** — Vite（渲染进程）+ esbuild（主进程/预加载） - **语言** — TypeScript +## 上游功能追踪 + +本仓库追踪来自上游 [ErlichLiu/Proma](https://github.com/ErlichLiu/Proma) 的功能开发。查看 [上游功能文档](./docs/UPSTREAM_FEATURES.md) 了解详情。 + +当前追踪的功能： +- **可视化统计** — [Issue #13](https://github.com/ErlichLiu/Proma/issues/13) → [PR #30](https://github.com/ErlichLiu/Proma/pull/30)：Token 使用量统计和成本预估 + ## 致谢 Proma 的诞生离不开这些优秀的开源项目： diff --git a/docs/HOW_TO_LINK_ISSUE_PR.md b/docs/HOW_TO_LINK_ISSUE_PR.md new file mode 100644 index 0000000..5ad49b5 --- /dev/null +++ b/docs/HOW_TO_LINK_ISSUE_PR.md @@ -0,0 +1,155 @@ +# 如何在 GitHub Issue 中关联 Pull Request + +本指南教您如何在 GitHub Issue 中提及和关联您的 Pull Request。 + +## 场景说明 + +- **Issue #13**: [ErlichLiu/Proma#13](https://github.com/ErlichLiu/Proma/issues/13) - 功能请求：可视化统计 +- **PR #30**: [ErlichLiu/Proma#30](https://github.com/ErlichLiu/Proma/pull/30) - 您的实现方案 + +## 方法一：在 Issue 中添加评论（推荐） + +### 步骤： + +1. **打开 Issue #13** + - 访问：https://github.com/ErlichLiu/Proma/issues/13 + +2. **滚动到页面底部的评论框** + +3. **输入以下评论**（选择其中一种）： + + **简单版本：** + ```markdown + I've created PR #30 to implement this feature. + ``` + + **详细版本：** + ```markdown + I've implemented this feature in PR #30. + + The implementation includes: + - Token usage tracking for all conversations + - Cost estimation based on configurable pricing + - Visualization dashboard with charts and statistics + + Please review and provide feedback. Thanks! + ``` + + **中文版本：** + ```markdown + 我已经在 PR #30 中实现了这个功能。 + + 实现包括： + - 所有对话的 Token 使用量追踪 + - 基于可配置定价的成本预估 + - 带图表和统计的可视化仪表板 + + 请审查并提供反馈，谢谢！ + ``` + +4. **点击 "Comment" 按钮** + +### 效果： + +- ✅ 在 Issue #13 下会显示您的评论 +- ✅ GitHub 会自动将 `#30` 转换为 PR #30 的链接 +- ✅ 在 PR #30 的页面会显示被 Issue #13 提及 + +--- + +## 方法二：在 PR 描述中关联 Issue（自动关闭） + +如果您希望 **PR 合并时自动关闭 Issue**，需要在 PR #30 的描述中使用关键词。 + +### 步骤： + +1. **打开 PR #30** + - 访问：https://github.com/ErlichLiu/Proma/pull/30 + +2. **点击描述区域右上角的 "..." 按钮** + +3. **选择 "Edit"** + +4. **在描述开头或结尾添加以下任一行**： + + ```markdown + Closes #13 + ``` + + 或者： + ```markdown + Fixes #13 + ``` + + 或者： + ```markdown + Resolves #13 + ``` + +5. **点击 "Update comment" 保存** + +### 效果： + +- ✅ PR #30 会自动关联到 Issue #13 +- ✅ 当 PR #30 被合并时，Issue #13 会自动关闭 +- ✅ 在 Issue #13 页面会显示被 PR #30 引用 + +--- + +## 方法三：同时使用两种方法（最佳实践） + +**推荐做法：** + +1. **在 PR #30 描述中**添加： + ```markdown + Closes #13 + ``` + +2. **在 Issue #13 中**添加评论： + ```markdown + I've implemented this in PR #30. Please review! + ``` + +这样可以： +- ✅ 在 Issue 讨论区通知所有关注者 +- ✅ 建立自动关闭关联 +- ✅ 方便项目维护者追踪进度 + +--- + +## GitHub 关键词说明 + +GitHub 支持的自动关闭关键词（不区分大小写）： + +| 关键词 | 说明 | +|--------|------| +| `close`, `closes`, `closed` | 关闭 Issue | +| `fix`, `fixes`, `fixed` | 修复 Issue | +| `resolve`, `resolves`, `resolved` | 解决 Issue | + +**使用格式：** +- 同一仓库：`Closes #13` +- 跨仓库：`Closes ErlichLiu/Proma#13` + +--- + +## 快速操作链接 + +- 📝 [在 Issue #13 添加评论](https://github.com/ErlichLiu/Proma/issues/13#new_comment_field) +- ✏️ [编辑 PR #30 描述](https://github.com/ErlichLiu/Proma/pull/30) +- 📚 [GitHub 官方文档：链接 PR 和 Issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) + +--- + +## 注意事项 + +⚠️ **重要提示：** + +1. 确保您已登录 GitHub +2. 您需要有评论权限（通常任何人都可以评论公开仓库的 Issue） +3. 如果 Issue 或 PR 在私有仓库，您需要有访问权限 +4. 使用 `#数字` 格式时，确保您在正确的仓库中操作 + +--- + +_本指南创建于 2026-02-18_ diff --git a/docs/QUICK_REFERENCE.md b/docs/QUICK_REFERENCE.md new file mode 100644 index 0000000..ca55fb5 --- /dev/null +++ b/docs/QUICK_REFERENCE.md @@ -0,0 +1,47 @@ +# 快速操作：关联 Issue #13 和 PR #30 + +## 🎯 最简单的方法（推荐） + +### 在 Issue #13 中评论 + +1. 打开：https://github.com/ErlichLiu/Proma/issues/13 +2. 滚动到底部评论框 +3. 输入并发送： + +```markdown +我已经在 PR #30 中实现了这个功能，请审查！ +``` + +**就这么简单！** ✅ + +--- + +## 🔄 如果希望 PR 合并时自动关闭 Issue + +### 编辑 PR #30 描述 + +1. 打开：https://github.com/ErlichLiu/Proma/pull/30 +2. 点击描述右上角的 "..." → "Edit" +3. 在描述开头添加： + +```markdown +Closes #13 +``` + +4. 点击 "Update comment" + +**完成！** ✅ + +--- + +## 📖 详细教程 + +查看完整指南：[HOW_TO_LINK_ISSUE_PR.md](./HOW_TO_LINK_ISSUE_PR.md) + +--- + +## 💡 提示 + +- 使用 `#30` 会自动创建到 PR #30 的链接 +- 使用 `Closes #13` 会在 PR 合并时自动关闭 Issue +- 可以在评论、PR 描述、提交消息中使用这些引用 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..34d13e1 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,36 @@ +# 文档目录 + +本目录包含 Proma 项目的各类文档。 + +## 📚 文档列表 + +### 上游功能追踪 + +- **[UPSTREAM_FEATURES.md](./UPSTREAM_FEATURES.md)** - 追踪上游仓库 ErlichLiu/Proma 的功能开发 + - 当前追踪：可视化统计功能（Issue #13 → PR #30） + +### 操作指南 + +- **[HOW_TO_LINK_ISSUE_PR.md](./HOW_TO_LINK_ISSUE_PR.md)** - 完整教程：如何在 GitHub 中关联 Issue 和 Pull Request + - 方法一：在 Issue 中添加评论 + - 方法二：在 PR 描述中使用关键词 + - 方法三：最佳实践组合 + +- **[QUICK_REFERENCE.md](./QUICK_REFERENCE.md)** - 快速参考卡片 + - 最简单的关联方法 + - 自动关闭 Issue 的设置 + +## 🎯 快速开始 + +如果您想要： + +1. **了解上游正在开发什么功能** → 查看 [UPSTREAM_FEATURES.md](./UPSTREAM_FEATURES.md) +2. **学习如何关联 Issue 和 PR** → 查看 [QUICK_REFERENCE.md](./QUICK_REFERENCE.md)（最快）或 [HOW_TO_LINK_ISSUE_PR.md](./HOW_TO_LINK_ISSUE_PR.md)（详细） + +## 📝 贡献 + +欢迎提交 PR 补充和完善文档！ + +--- + +_最后更新: 2026-02-18_ diff --git a/docs/UPSTREAM_FEATURES.md b/docs/UPSTREAM_FEATURES.md new file mode 100644 index 0000000..ef159b2 --- /dev/null +++ b/docs/UPSTREAM_FEATURES.md @@ -0,0 +1,48 @@ +# 上游功能追踪：可视化统计 + +追踪上游仓库 [ErlichLiu/Proma](https://github.com/ErlichLiu/Proma) 中关于可视化统计功能的开发进展。 + +## Issue #13 → PR #30 关联 + +**功能请求**: [Issue #13 - Visualize usage statistics and recent conversation token consumption](https://github.com/ErlichLiu/Proma/issues/13) + +**实现方案**: [PR #30 - feat: 添加 Token 使用量统计功能](https://github.com/ErlichLiu/Proma/pull/30) + +## 功能范围 + +### 用户需求 (Issue #13) +- 总使用量统计（日/月维度） +- 近期对话的 Token 消耗明细 +- 可视化图表展示，便于监控和优化 + +### 实现内容 (PR #30) + +**数据层** +- `ChatMessage` 添加 `usage` 字段持久化 +- Provider 适配器解析 SSE 流中的 usage 事件 +- `usage-service` 提供统计聚合和成本预估 + +**界面层** +- UsageSettings 统计页面（科技蓝风格，支持暗/亮主题） +- 总览卡片：总 Token、对话数、预估成本 +- 趋势图：7/30/90 天视图 +- 饼图：模型使用量分布 +- 最近对话列表及详情 + +**供应商支持** +- Anthropic、OpenAI、Google 等主流 Provider +- 可配置价格表用于成本预估 + +## 如何关联 Issue 和 PR + +如果您想在 Issue #13 中提及 PR #30，请查看操作指南： +- 📖 [完整教程](./HOW_TO_LINK_ISSUE_PR.md) +- ⚡ [快速参考](./QUICK_REFERENCE.md) + +## 同步计划 + +待上游 PR #30 合并后，评估同步到本仓库的可行性。 + +--- + +_追踪建立: 2026-02-18_