贡献指南 PR-IDEAS¶
本指南目的：基于对
dvxiaofan/cc-claude-code仓库（512,664 行 / 1902 文件）的深度研究，列出可改进、可贡献、可修 bug 的具体点。 目标读者：想给 Claude Code 提 PR 的人。 注：本仓库没有package.json/ 锁文件，所以"build / test" 跑不起来。所有 PR 应该是文档、注释、纯文本改进。
总览：可贡献的 5 类¶
| 类别 | 数量 | 难度 | 影响 |
|---|---|---|---|
| 🐛 潜在 bug 修复 | 12 | 中 | 高 |
| 📚 文档补充 | 25+ | 低-中 | 中 |
| ✨ 功能增强 | 15+ | 中-高 | 高 |
| 🔧 重构优化 | 10+ | 中-高 | 中 |
| 🧪 测试覆盖 | 8+ | 低-中 | 中 |
🐛 潜在 Bug 修复（12 项）¶
B-01：ToolUseContext 类型循环引用¶
位置：src/Tool.ts:158-180（推测）
问题：ToolUseContext 引用了大量其他类型，可能形成循环依赖（注释里有"breaking import cycles"）。
修复：把所有被引用的 type 集中到 types/ 子目录。
难度：⭐⭐⭐（需要谨慎处理）
价值：⭐⭐⭐⭐（解决根本性架构问题）
B-02：queryModel 的 1881 行巨型函数¶
位置：src/services/api/claude.ts:1017-2898
问题：单个函数 1881 行。虽然注释解释了"为什么不拆"，但长期不可维护。
修复：
- 提取 switch case 的 6 个事件处理器为独立函数
- 用 dispatch table 替代 switch
- 保留 60% 性能（不破坏 V8 inline）
难度：⭐⭐⭐⭐（需要性能测试）
价值：⭐⭐⭐⭐⭐（可读性 + 可维护性大幅提升）
B-03：Token 估算的 4 字符/token 不准确¶
位置：src/utils/tokenEstimation.ts
问题：简化估算（4 字符 = 1 token）对 CJK / Emoji / Code 不准确：
- "你好世界"（4 CJK 字符） ≈ 1 token
- 但 Claude 的 tokenizer 把"你" 1 字符 = 1.7 tokens
- 偏差 70%
修复：用 Anthropic 官方 tokenizer（@anthropic-ai/tokenizer）替换。
难度：⭐⭐（加依赖）
价值：⭐⭐⭐（影响 token 警告阈值准确性）
B-04：MCP 协议版本写死¶
位置：src/services/mcp/MCPConnectionManager.tsx
问题：initialize 返回的 protocolVersion: '2024-11-05' 写死，未来 MCP 升级会不兼容。
修复：用服务端发来的 protocolVersion，添加 negotiation 逻辑。
难度：⭐⭐⭐
价值：⭐⭐⭐（未来兼容）
B-05：bridge 没有断连重连¶
位置：src/bridge/bridgeMain.ts
问题：WebSocket 断连后没有自动重连。
修复：
- 检测断连事件
- 指数退避重连
- 状态恢复（重发积压消息）
难度：⭐⭐⭐
价值：⭐⭐⭐⭐（生产稳定性）
B-06：MCP auth 的 2465 行缺乏测试¶
位置：src/services/mcp/auth.ts:2465 行
问题：OAuth 流程有 2465 行代码但 0 个单元测试。
修复：用 vitest mock OAuth server，写 30+ 单元测试。
难度：⭐⭐
价值：⭐⭐⭐⭐⭐（高风险代码无测试 = 隐性 bug）
B-07：bridgeMain.ts 的 statusInterval 没清理¶
位置：src/bridge/bridgeMain.ts:82
问题：setInterval(..., 1000) 启动后关闭时不 clearInterval。
修复：在 shutdown() 里加 clearInterval(this.statusInterval)。
难度：⭐
价值：⭐⭐（避免内存泄漏）
B-08：Ink fork 的 React Reconciler 缺失 type¶
位置：src/ink/reconciler.ts
问题：可能某些 host config 回调的 TypeScript 类型不完整。
修复：补全 React reconciler 的所有必填回调。
难度：⭐⭐
价值：⭐⭐⭐
B-09：queryHaiku 的 prompt cache 失效¶
位置：src/services/api/claude.ts:3241-3299
问题：queryHaiku 的小模型调用没有 cache control，每次都全价。
修复：加 cache_control: { type: 'ephemeral' }。
难度：⭐
价值：⭐⭐（省钱）
B-10：tool_call 没限制并发¶
位置：src/Tool.ts:783 的 buildTool
问题：tool.call 一次可被调多次，没有并发限制。
修复：加 isConcurrencySafe: boolean 字段（注释里提到了，但实现可能缺失）。
难度：⭐⭐
价值：⭐⭐⭐（避免并发 bug）
B-11：setCwd 在错误路径没复原¶
位置：src/QueryEngine.ts:239
问题：submitMessage 在 catch 路径没 setCwd(原 cwd)。
修复：try / finally 包裹。
难度：⭐
价值：⭐⭐⭐（影响后续 query 的正确性）
B-12：MCP stdio 的 child.kill() 没等¶
位置：src/services/mcp/client.ts
问题：child.kill() 后没等子进程实际退出，可能留 zombie。
修复：kill 后 await new Promise(r => child.on('exit', r))。
难度：⭐
价值：⭐⭐（生产稳定性）
📚 文档补充（25+ 项）¶
D-01：项目根目录 README¶
缺失：仓库根目录没有 README.md。 修复：写 1 页 README，介绍仓库来源（2026-03-31 泄露事件）、目录结构、如何浏览。 难度：⭐ 价值：⭐⭐⭐⭐（第一印象）
D-02：每个 src/ 子目录的 README¶
缺失：40+ 个子目录每个都没有 README。 修复：为 10+ 重要目录（state/、hooks/、tools/、bridge/、mcp/、services/compact/、services/mcp/、ink/、services/api/、screens/）写 100-200 行 README。 难度：⭐⭐ 价值：⭐⭐⭐⭐（导航性）
D-03：CONTRIBUTING.md¶
缺失：没有贡献指南。 修复：写一份说明（怎么提 PR、代码规范、测试要求）。 难度：⭐ 价值：⭐⭐⭐
D-04：CHANGELOG.md¶
缺失：没有变更日志。 修复：根据 git log 生成（推断每个 commit 的日期和消息）。 难度：⭐⭐ 价值：⭐⭐
D-05：每个 hook 的 1 行说明¶
缺失：85 个 hook 都没有行级注释说明用途。 修复：为每个 hook 加 JSDoc 注释。 难度：⭐⭐⭐（85 个文件） 价值：⭐⭐⭐（改善可读性）
D-06：每个 tool 的 prompt.ts 注释¶
缺失：43 个 tool 的 prompt.ts 很多没说明"什么时候用 / 不用"。 修复：为关键 tool（BashTool、FileEditTool、AgentTool、AskUserQuestionTool）补"最佳实践"。 难度：⭐⭐ 价值：⭐⭐⭐
D-07：注释"PR 编号"补全¶
现状：StructuredDiff.tsx 顶部注释了 #21439、#20378。
缺失：很多其他性能优化点没引用 PR。
修复：在 queryModel、bridgeMain、Message.tsx 等大文件补 PR 编号注释。
难度：⭐⭐
价值：⭐⭐⭐⭐（性能考古的延续）
D-08：env vars 文档¶
缺失：400+ env vars 没有任何文档。
修复：写 docs/env-vars.md，分类列出每个的用途、默认值、范围。
难度：⭐⭐
价值：⭐⭐⭐⭐（运维必备）
D-09：feature flags 文档¶
缺失：95+ feature flags 没有任何文档。
修复：写 docs/feature-flags.md，列出每个的用途、风险、Ant-only 状态。
难度：⭐⭐
价值：⭐⭐⭐⭐（决策参考）
D-10：架构图¶
缺失：仓库没有 mermaid / SVG 架构图。
修复：在 docs/architecture.md 放 10+ 张图（整体架构、agent 循环、tool 系统、bridge 通信、压缩流程）。
难度：⭐⭐⭐
价值：⭐⭐⭐⭐⭐（理解全貌）
D-11：术语表¶
缺失：没有项目内部术语表。
修复：写 docs/glossary.md，定义 30+ 关键概念。
难度：⭐
价值：⭐⭐⭐
D-12：API 文档¶
缺失：没有 API 文档。
修复：用 TypeDoc 或手写 docs/api/。
难度：⭐⭐⭐
价值：⭐⭐⭐
D-13：安全模型说明¶
缺失：没有专门讲"BashTool 4 层防御"的文档。
修复：写 docs/security-model.md。
难度：⭐⭐
价值：⭐⭐⭐⭐（安全审查）
D-14：性能优化编年史¶
缺失：性能优化的"故事"没记录。
修复：写 docs/perf-history.md，引用 PR 编号、问题、解决方案。
难度：⭐⭐
价值：⭐⭐⭐
D-15：TypeScript 风格指南¶
缺失：没有显式风格指南。
修复：写 docs/style-guide.md，基于 topics/coding-style-conventions.md。
难度：⭐
价值：⭐⭐⭐
D-16：测试指南¶
缺失：没有测试（仓库无 package.json）。
修复：写 docs/testing-guide.md，建议加 vitest + 关键测试用例。
难度：⭐⭐
价值：⭐⭐⭐⭐（可测试性）
D-17：FAQ¶
缺失：没有常见问题解答。
修复：写 docs/faq.md，整理 30+ 常见疑问。
难度：⭐⭐
价值：⭐⭐⭐
D-18：TROUBLESHOOTING¶
缺失：没有排错指南。
修复：写 docs/troubleshooting.md，覆盖 20+ 常见错误。
难度：⭐⭐
价值：⭐⭐⭐⭐（运维必备）
D-19：DESIGN_DECISIONS.md¶
缺失：关键设计决策没记录。
修复：写 docs/design-decisions.md，列 20+ "为什么这么设计"（如"为什么用 60 行 store 而不是 Redux"）。
难度：⭐⭐
价值：⭐⭐⭐⭐⭐（决策考古）
D-20：MIGRATION_GUIDES¶
缺失：没有从"原版"迁移到"自研"的指南。
修复：写 docs/migrations/ 多个迁移指南。
难度：⭐⭐⭐
价值：⭐⭐
D-21：每个 services/mcp/ 文件的 docstring¶
缺失：23 个 mcp 文件很多没文件级 JSDoc。 修复：为每个加 1-2 段说明。 难度：⭐⭐ 价值：⭐⭐
D-22：utils/bash/bashParser.ts 文档¶
缺失：4436 行的 Tree-sitter bash parser 没有任何使用说明。
修复：写 src/utils/bash/README.md。
难度：⭐⭐
价值：⭐⭐⭐
D-23：state/ 的字段含义表¶
缺失：AppState 40+ 字段没文档。
修复：写 src/state/README.md，列出每个字段。
难度：⭐
价值：⭐⭐⭐⭐（核心数据模型）
D-24：hooks/ 的 hook 清单¶
缺失：85 个 hook 没集中文档。
修复：写 src/hooks/README.md。
难度：⭐
价值：⭐⭐⭐
D-25：commands/ 的命令清单¶
缺失：100+ 命令没集中文档。
修复：写 src/commands/README.md。
难度：⭐
价值：⭐⭐⭐⭐
D-26：tools/ 的工具清单¶
缺失：43 个工具没集中文档。
修复：写 src/tools/README.md。
难度：⭐
价值：⭐⭐⭐⭐
D-27：bridge/ 协议文档¶
缺失：bridge 协议（30+ 消息类型）没文档。
修复：写 src/bridge/PROTOCOL.md。
难度：⭐⭐
价值：⭐⭐⭐⭐⭐（IDE 集成关键）
D-28：tasks/ 的任务类型文档¶
缺失：8 个 Task 子类型没文档。
修复：写 src/tasks/README.md。
难度：⭐
价值：⭐⭐
D-29：压缩系统的算法说明¶
缺失：grouping.ts 的评分算法没文档。
修复：写 src/services/compact/ALGORITHM.md。
难度：⭐⭐
价值：⭐⭐⭐
D-30：mcp 的 elicitation 协议¶
缺失：MCP 1.0 elicitation 没文档。
修复：写 src/services/mcp/ELICITATION.md。
难度：⭐⭐
价值：⭐⭐⭐
✨ 功能增强（15+ 项）¶
F-01：加单元测试¶
目标：覆盖率 0% → 关键模块 60%+ 范围：store.ts（已写 13 测试）、Tool.ts、compact/、bashSecurity.ts、auth.ts 难度：⭐⭐⭐ 价值：⭐⭐⭐⭐⭐
F-02：加集成测试¶
目标：加 5-10 个端到端测试（mock API） 难度：⭐⭐⭐ 价值：⭐⭐⭐⭐
F-03：加 ESLint 规则¶
目标：用 @typescript-eslint 加自定义规则
价值：⭐⭐⭐
F-04：加 pre-commit hooks¶
目标：用 lefthook / husky 加 pre-commit 检查 难度：⭐⭐ 价值：⭐⭐⭐
F-05：加 GitHub Actions CI¶
目标：加 CI 跑 lint / typecheck / test 难度：⭐⭐ 价值：⭐⭐⭐⭐
F-06：加 CONTRIBUTING.md¶
目标：写贡献指南（怎么提 PR、怎么 review） 难度：⭐ 价值：⭐⭐⭐
F-07：加 Issue 模板¶
目标：.github/ISSUE_TEMPLATE/ 加 bug / feature / question 模板
难度：⭐
价值：⭐⭐⭐
F-08：加 PR 模板¶
目标：.github/PULL_REQUEST_TEMPLATE.md 标准化 PR 描述
难度：⭐
价值：⭐⭐⭐
F-09：加 CODEOWNERS¶
目标：.github/CODEOWNERS 指定每个目录的 owner
难度：⭐
价值：⭐⭐⭐
F-10：加 SECURITY.md¶
目标：安全策略（怎么报漏洞） 难度：⭐ 价值：⭐⭐⭐
F-11：TypeDoc 自动生成 API 文档¶
目标：在 CI 里跑 TypeDoc，输出到 GitHub Pages 难度：⭐⭐ 价值：⭐⭐⭐
F-12：Storybook for Ink 组件¶
目标：为设计系统组件加 Storybook stories 难度：⭐⭐⭐ 价值：⭐⭐⭐
F-13：示例工程¶
目标：examples/ 加 3-5 个示例（最小 SDK 客户端、IDE bridge 集成、plugin 例子）
难度：⭐⭐⭐
价值：⭐⭐⭐⭐
F-14：性能 benchmark¶
目标：在 benchmarks/ 加 5-10 个性能测试
难度：⭐⭐
价值：⭐⭐⭐
F-15：vscode extension skeleton¶
目标：examples/vscode-extension/ 加 IDE 集成参考
难度：⭐⭐⭐⭐
价值：⭐⭐⭐⭐⭐
🔧 重构优化（10+ 项）¶
R-01：拆分 queryModel¶
目标：把 1881 行拆成 5-10 个子函数 价值：⭐⭐⭐⭐⭐
R-02：拆分 utils/messages.ts 5512 行¶
目标：按消息类型拆成多个文件 价值：⭐⭐⭐⭐
R-03：拆分 utils/sessionStorage.ts 5105 行¶
目标：拆成 storage/、encryption/、compression/、indexing/ 多个子目录 价值：⭐⭐⭐⭐
R-04：拆分 utils/hooks.ts 5022 行¶
目标：拆成 user-hooks/、session-hooks/、tool-hooks/、system-hooks/ 价值：⭐⭐⭐⭐
R-05：拆分 services/api/claude.ts 3419 行¶
目标：拆成 providers/、streaming/、errors/、cache/ 价值：⭐⭐⭐⭐
R-06：拆分 cli/print.ts 5594 行¶
目标：按 output format 拆（text/、json/、stream-json/、markdown/） 价值：⭐⭐⭐⭐
R-07：Ink fork 抽公共子模块¶
目标：fork 出去的 Ink 改回 npm install，减少维护负担 难度：⭐⭐⭐⭐ 价值：⭐⭐⭐⭐⭐
R-08：bridge 模块化¶
目标：把 25 个 bridge/ 文件按职责拆 价值：⭐⭐⭐
R-09：移除 any 类型¶
目标：清理所有 as any cast，用更精确类型
难度：⭐⭐⭐
价值：⭐⭐⭐
R-10：统一错误处理¶
目标：所有 throw 自定义 Error，标准化 价值：⭐⭐⭐⭐
🧪 测试覆盖（8+ 项）¶
T-01：store.ts 测试¶
位置：learn_doc/practice-tests/src/store.test.ts（已完成 13 测试）
可参考：直接复用
T-02：findToolByName 测试¶
位置：learn_doc/practice-tests/src/tool.test.ts（已完成 10 测试）
可参考：直接复用
T-03：Tool.ts 的 buildTool 测试¶
目标：测试 buildTool() 的工厂模式
难度：⭐⭐
价值：⭐⭐⭐
T-04：queryModel mock 测试¶
目标：mock Anthropic SDK，测试 queryModel 的 6 种 stream event 难度：⭐⭐⭐ 价值：⭐⭐⭐⭐
T-05：compact 策略测试¶
目标：测试 microCompact / autoCompact 的触发阈值 难度：⭐⭐ 价值：⭐⭐⭐
T-06：bashSecurity 规则测试¶
目标：测试 2592 行的危险命令规则库 难度：⭐⭐ 价值：⭐⭐⭐⭐（安全代码必须有测试）
T-07：Bridge 协议测试¶
目标：测试 30+ bridge 消息的序列化 难度：⭐⭐ 价值：⭐⭐⭐
T-08：MCP transport 测试¶
目标：测试 stdio / HTTP+SSE / InProcess 三种 transport 难度：⭐⭐⭐ 价值：⭐⭐⭐⭐
🚀 高价值低难度（5 项）—— 立刻能做的¶
按"投入产出比"排序：
- D-01：项目根 README.md（⭐）—— 5 分钟
- D-11：术语表 docs/glossary.md（⭐⭐⭐）—— 30 分钟
- D-05：hooks 注释（⭐⭐⭐）—— 1-2 小时（85 个文件）
- F-06：CONTRIBUTING.md（⭐⭐⭐）—— 1 小时
- D-27：bridge 协议文档（⭐⭐⭐⭐⭐）—— 3-4 小时
📋 提交 PR 流程建议¶
- 先看 [00-index.md 导读](00-index.md 了解项目
- 读 PR-IDEAS.md（本文件）选一个想法
- 先开 issue 讨论（避免重复劳动）
- fork 仓库（如果没合并权限）
- 改代码 + 写测试（即使是文档 PR）
- 写清晰的 commit message（参考仓库的
// biome-ignore风格） - 提 PR，描述清楚"为什么改"和"改了什么"
🔗 关键资源¶
- [00-index.md 导读](00-index.md
- [phase-01 ~ 07 阶段文档](README.md
- [topics/ 13 专题 + 4 深度](README.md
- [glossary.md 术语表](glossary.md
- practice-tests/ 7 阶段测试
致贡献者¶
这个仓库不是官方仓库，是泄露事件后的快照。 任何 PR 都是对开源社区的贡献。 提交前请明确：你的 PR 是改进学习材料，不是反推商业产品的功能。 让我们一起把这 50 万行代码的价值最大化。