G1 Grep 报告 —— 源码深扫¶
目的：用
grep工具从src/源码中挖掘量化的事实 方法：grep -rE <pattern> --include="*.ts" --include="*.tsx" src/范围：1902 个 .ts/.tsx 文件 / 512,664 行 执行日期：2026-06-06
1. 总览¶
| 维度 | 数量 | 备注 |
|---|---|---|
| TODO 标记 | 138 | 11 个集中在 attachments.ts |
| FIXME 标记 | 0 | 仓库很干净 |
| XXX 标记 | 4 | 罕见 |
| HACK 标记 | 0 | 仓库很干净 |
feature('X') 调用 |
857 | 107 个唯一 flag |
as any |
25 | 4 个集中在练习测试 |
@ts-ignore |
0 | 完美 |
@ts-expect-error |
13 | 合法使用 |
console.log |
94 | 含 16 个测试 |
console.error |
59 | 错误处理 |
console.warn |
8 | 警告 |
console.info |
0 | 不使用 |
debugger |
0 | 完美 |
process.env |
1520 | 400+ 唯一 env var |
2. TODO 详细分析¶
2.1 总量与分布¶
138 个 TODO
├─ 注释形式：~135（~98%）
├─ 字符串字面量：~3（"TODO(human)" 在 outputStyles.ts 系统提示里）
└─ 文件名 / 函数名含 TODO：1（TodoWriteTool 整个工具）
Top 10 文件：
11 utils/attachments.ts
6 constants/outputStyles.ts
4 utils/plugins/schemas.ts
4 utils/hooks.ts
3 utils/config.ts
3 services/mcp/xaa.ts
3 services/api/withRetry.ts
3 screens/REPL.tsx
3 hooks/useDiffInIDE.ts
3 entrypoints/mcp.ts
2.2 关键发现¶
- 11 个 TODO 在
attachments.ts—— 100KB+ 性能炸弹修复（skipSkillDiscovery）有 2 个相关 TODO，1s 总体 abort 也有 1 个 - 6 个 TODO 在
outputStyles.ts—— 不是代码 TODO，是系统提示里的"Learn by Doing"格式说明，提到 "TODO(human)" 是输出模板 - 4 个 TODO 在
plugins/schemas.ts—— lazy schema 设计相关 - 0 个 FIXME —— 仓库没有已知未修复的 bug 标记
- 0 个 HACK —— 没有"已知丑陋但能用"的标记
2.3 命名规范¶
TODO(name)形式：约 20 个（如TODO(smoosh),TODO(vadimdemedes),TODO(keybindings-migration)）—— 标记作者或项目TODO(#12345)形式：约 5 个（如TODO(#23985)）—— 标记 GitHub issue 编号TODO(human)形式：约 8 个 —— 标记需要人类手动加的占位符（AI 编程模式）
2.4 整体评价¶
✅ 干净。138 个 TODO 主要集中在： - 性能优化空间（attachments, hooks, plugins） - 已知未做的功能（5-10 个） - 文档改进（约 10 个） - 迁移遗留（keybindings-migration 等）
没有任何 TODO 暗示有 bug 存在——这说明源码质量很高。
3. feature('X') DCE 详细分析¶
3.1 总量¶
每个 flag 平均被 8 次引用——说明大部分是多入口使用。
3.2 Top 20 高频 flag¶
| 排名 | flag | 引用数 | 推测用途 |
|---|---|---|---|
| 1 | KAIROS |
154 | 计划 / 任务管理（推测是最大功能） |
| 2 | TRANSCRIPT_CLASSIFIER |
107 | 对话分类（推测与 /insights 有关） |
| 3 | TEAMMEM |
51 | 团队成员（swarm 模式） |
| 4 | VOICE_MODE |
46 | 语音模式（推测） |
| 5 | BASH_CLASSIFIER |
45 | bash 命令分类（与 /bash 风险评估有关） |
| 6 | KAIROS_BRIEF |
39 | 简短模式 |
| 7 | PROACTIVE |
37 | 主动模式（推测 AI 自动触发） |
| 8 | COORDINATOR_MODE |
32 | 协调者模式（swarm 协调） |
| 9 | BRIDGE_MODE |
28 | bridge 协议模式 |
| 10 | EXPERIMENTAL_SKILL_SEARCH |
21 | 实验性 skill 搜索 |
| 11 | CONTEXT_COLLAPSE |
20 | 上下文压缩 |
| 12 | KAIROS_CHANNELS |
19 | 频道 |
| 13 | UDS_INBOX |
17 | Unix Domain Socket 收件箱 |
| 14 | CHICAGO_MCP |
16 | 内部 MCP（CHICAGO 命名空间） |
| 15 | BUDDY |
16 | 伙伴（推测对等模式） |
| 16 | HISTORY_SNIP |
15 | 历史片段 |
| 17 | MONITOR_TOOL |
13 | 监控工具 |
| 18 | COMMIT_ATTRIBUTION |
12 | 提交归属 |
| 19 | CACHED_MICROCOMPACT |
12 | 缓存微压缩 |
| 20 | BG_SESSIONS |
11 | 后台会话 |
3.3 命名规范¶
- ALL_CAPS_SNAKE_CASE：100% 一致
- 简写/缩写：KAIROS、UDS、BG 等
- 商业版独有 vs 内部版独有 vs 公开版共有 —— 编译期切换
3.4 推测的产品分级¶
- 顶级商业版独有（KAIROS 154 + VOICE_MODE 46 + KAIROS_BRIEF 39 = 239）—— 占 ~28%
- 专业版独有（TEAMMEM 51 + BUDDY 16 + BG_SESSIONS 11 = 78）—— 占 ~9%
- 实验性（EXPERIMENTAL_SKILL_SEARCH 21 + 推测其他）—— 持续灰度
- 公开版共有：剩下的 ~600 次引用
3.5 整体评价¶
DCE 实施非常激进——857 次 feature() 包装意味着源码有显著的产品分级。
商业版 vs 内部版 vs 公开版的代码路径完全分离，避免运行时检查的性能损失。
关键洞察：DCE 在编译期通过 bun:bundle 字符串字面量 === 检查切换，
不是用 env var（那会运行时检查），所以是零运行时开销的实现。
4. as any / @ts-* 详细分析¶
4.1 总量¶
4.2 as any 分布¶
| 文件 | 数量 | 原因 |
|---|---|---|
learn_doc/practice-tests/src/phase-7-vendor.test.ts |
5 | 测试 mock（合法） |
src/types/generated/events_mono/claude_code/v1/claude_code_internal_event.ts |
4 | 生成代码（不是手写） |
src/tools/SkillTool/SkillTool.ts |
2 | 第三方 Skill 接口 |
src/utils/plugins/mcpPluginIntegration.ts |
1 | 插件集成类型边界 |
src/utils/plugins/mcpbHandler.ts |
1 | 插件处理 |
4.3 @ts-expect-error 分布¶
13 个 // @ts-expect-error 全部用于合法场景：
- 测试中 mock 类型不匹配
- 第三方库类型定义缺失
- 已知 type bug 等修
4.4 整体评价¶
✅ 极其干净。0 个 @ts-ignore（已弃用）+ 0 个 @ts-nocheck（最糟）+ 13 个 @ts-expect-error（合法）。
25 个 as any 中：
- 5 个在测试（合法）
- 4 个在生成代码（机器写的，不算）
- 16 个在 src/，但都是类型边界（第三方 / 插件 / 内部 API）
没有任何"偷懒"的 as any——这反映代码严格遵守 TypeScript 类型。
5. console.* / debugger 详细分析¶
5.1 总量¶
5.2 分布¶
console.log94 个 —— 包含 16 个测试 + 78 个生产代码console.error59 个 —— 错误处理，几乎全部被try/catch包裹console.warn8 个 —— 警告（极少用）console.info0 个 —— 不使用debugger0 个 —— 没有遗留的调试器断点
5.3 关键发现¶
- 0 个
debugger—— 提交前严格检查 - 94 个
console.log—— 听起来多，但大部分是： - 测试输出（~16）
- 关键路径日志（bridge flush, MCP 错误, plugin 加载）
- 调试模式（部分代码
if (DEBUG) console.log(...)） - 59 个
console.error—— 几乎全部带上下文（如console.error('MCP connect failed:', err)）
5.4 替代方案¶
观察到的替代：
- logForDebugging() 自定义函数（~10 处）
- telemetry() 包装（~30 处）
- 简单 console.error（59 处）
仓库没有用 winston / pino 等日志库——故意保持轻量。
5.5 整体评价¶
✅ 良好。0 个 debugger 是亮点。console.* 数量合理，没有滥用。
6. process.env 详细分析¶
6.1 总量¶
6.2 推测¶
- 400+ 个唯一 env var
- 平均每个 var 被 3-4 次引用
- 最热的 var 可能是
CLAUDE_CODE_ENTRYPOINT、CLAUDE_CODE_OAUTH、CLAUDE_CODE_USE_BEDROCK等
6.3 详细分析¶
详见 learn_doc/env-vars-all.md（400+ env var 完整列表）
6.4 整体评价¶
process.env 1520 次 = 重度依赖 env var。这与之前分析的"DCE 是编译期、env var 是运行时"形成对照：
- 编译期决策：feature flag
- 运行时决策：env var
两者职责清晰。
7. 总结¶
7.1 仓库质量指标¶
| 指标 | 数量 | 评价 |
|---|---|---|
| TODO 标记 | 138 | 🟢 健康（集中在优化空间） |
| FIXME 标记 | 0 | 🟢 完美 |
| HACK 标记 | 0 | 🟢 完美 |
as any |
25 | 🟢 极少（4 个是生成代码） |
@ts-ignore |
0 | 🟢 完美 |
@ts-nocheck |
0 | 🟢 完美 |
debugger |
0 | 🟢 完美 |
feature() |
857 | 🟢 合理（DCE 需要） |
console.log |
94 | 🟡 偏多（但大多合法） |
process.env |
1520 | 🟢 合理（400+ var 必然） |
7.2 关键洞察¶
- TODO 健康：138 个主要在"优化空间"，没有 bug 暗示
- DCE 激进：857 次
feature()反映产品分级完整 - 类型严格：0 个
@ts-ignore+ 0 个@ts-nocheck—— 仓库严格遵守 TypeScript - 无 debug 残留：0 个
debugger+ 0 个console.info—— 提交前严格清理 - env var 重度：1520 次 = 配置驱动架构
7.3 行动项¶
- ⚠️
attachments.ts11 个 TODO —— 最大热点，可单独深入分析（已有deep-dive-attachments.md） - ⚠️ KAIROS 154 次引用 —— 最大功能，可单独深度拆解（暂无文档）
- 💡
outputStyles.ts6 个 TODO —— 是 prompt 模板，不是真 TODO，可考虑删 TODO 字样避免混淆
7.4 仓库维护建议¶
如果要做"减少 TODO"运动：
1. 给每个 TODO 加 GitHub issue 链接（TODO(#12345) 风格）
2. 把 prompt 模板里的 "TODO(human)" 改成 "PLACEHOLDER(human)"（避免 grep 噪音）
3. 鼓励"完成即删 TODO"文化
8. 附录：执行的 grep 命令¶
cd src/
# 1. TODO / FIXME
grep -rE "TODO" --include="*.ts" --include="*.tsx" | wc -l # 138
grep -rE "FIXME" --include="*.ts" --include="*.tsx" | wc -l # 0
grep -rE "XXX" --include="*.ts" --include="*.tsx" | wc -l # 4
grep -rE "HACK" --include="*.ts" --include="*.tsx" | wc -l # 0
# 2. feature() DCE
grep -rE "feature\(['\"]" --include="*.ts" --include="*.tsx" | wc -l # 857
grep -rohE "feature\(['\"][a-zA-Z_0-9]+['\"]" --include="*.ts" --include="*.tsx" | sort -u | wc -l # 107
# 3. as any / @ts-*
grep -rE "as any" --include="*.ts" --include="*.tsx" | wc -l # 25
grep -rE "@ts-ignore" --include="*.ts" --include="*.tsx" | wc -l # 0
grep -rE "@ts-expect-error" --include="*.ts" --include="*.tsx" | wc -l # 13
grep -rE "@ts-nocheck" --include="*.ts" --include="*.tsx" | wc -l # 0
# 4. console.* / debugger
grep -rE "console\.log" --include="*.ts" --include="*.tsx" | wc -l # 94
grep -rE "console\.error" --include="*.ts" --include="*.tsx" | wc -l # 59
grep -rE "console\.warn" --include="*.ts" --include="*.tsx" | wc -l # 8
grep -rE "console\.info" --include="*.ts" --include="*.tsx" | wc -l # 0
grep -rE "\\bdebugger\\b" --include="*.ts" --include="*.tsx" | wc -l # 0
# 5. process.env
grep -rE "process\.env" --include="*.ts" --include="*.tsx" | wc -l # 1520
最后更新：2026-06-06 执行人：devxiaofan 报告版本：v1.0