Skip to content

feature-exploration-plan.md

Latest commit

 

History

History
457 lines (360 loc) · 16.2 KB

feature-exploration-plan.md

File metadata and controls

457 lines (360 loc) · 16.2 KB

Feature 探索计划书

生成日期：2026-04-02 代码库中已识别 89 个 feature flag，本文档按实现完整度和探索价值分级，制定探索优先级和路线图。

已完成：BUDDY（✅ 2026-04-02）、TRANSCRIPT_CLASSIFIER / Auto Mode（✅ 2026-04-02）

一、总览

按实现状态分类

状态 数量 说明
已实现/可用 11 代码完整，开启 feature 后可运行（可能需要 OAuth 等外部依赖）
部分实现 8 核心逻辑存在但关键模块为 stub，需要补全
纯 Stub 15 所有函数/工具返回空值，需要从零实现
N/A 55+ 内部基础设施、低引用量辅助功能，或反编译丢失过多

启用方式

所有 feature 通过环境变量启用：

# 单个 feature
FEATURE_BUDDY=1 bun run dev

# 多个 feature 组合
FEATURE_KAIROS=1 FEATURE_PROACTIVE=1 FEATURE_FORK_SUBAGENT=1 bun run dev

二、Tier 1 — 已实现/可用（优先探索）

2.1 KAIROS（常驻助手模式）⭐ 最高优先级

  • 引用数：154（全库最大）
  • 功能：将 CLI 变为常驻后台助手，支持：
    • 持久化 bridge 会话（跨重启复用 session）
    • 后台执行任务（用户离开终端时继续工作）
    • 推送通知到移动端（任务完成/需要输入时）
    • 每日记忆日志 + /dream 知识蒸馏
    • 外部频道消息接入（Slack/Discord/Telegram）
  • 子 Feature：
子 Feature 引用 功能
KAIROS_BRIEF 39 Brief 工具（SendUserMessage），结构化消息输出
KAIROS_CHANNELS 19 外部频道消息接入
KAIROS_PUSH_NOTIFICATION 4 移动端推送通知
KAIROS_GITHUB_WEBHOOKS 3 GitHub PR webhook 订阅
KAIROS_DREAM 1 夜间记忆蒸馏
  • 关键文件：src/assistant/、src/tools/BriefTool/、src/services/mcp/channelNotification.ts、src/memdir/memdir.ts
  • 外部依赖：Anthropic OAuth（claude.ai 订阅）、GrowthBook 特性门控
  • 探索命令：FEATURE_KAIROS=1 FEATURE_KAIROS_BRIEF=1 FEATURE_PROACTIVE=1 bun run dev

探索步骤：

  1. 开启 feature，观察启动行为变化
  2. 测试 /assistant、/brief 命令
  3. 验证 BriefTool 输出模式
  4. 尝试频道消息接入
  5. 测试 /dream 记忆蒸馏

2.2 TRANSCRIPT_CLASSIFIER（Auto Mode 分类器） ✅ 已完成

  • 引用数：108
  • 功能：使用 LLM 对用户意图进行分类，实现 auto mode（自动决定工具权限）
  • 状态：✅ prompt 模板已重建，功能完整可用（2026-04-02 完成）

2.3 VOICE_MODE（语音输入）

  • 引用数：46
  • 功能：按键说话（Push-to-Talk），音频流式传输到 Anthropic STT 端点（Nova 3），实时转录显示
  • 当前状态：完整实现，包括录音、WebSocket 流、转录插入
  • 关键文件：src/voice/voiceModeEnabled.ts、src/hooks/useVoice.ts、src/services/voiceStreamSTT.ts
  • 外部依赖：Anthropic OAuth（非 API key）、macOS 原生音频或 SoX
  • 探索命令：FEATURE_VOICE_MODE=1 bun run dev
  • 默认快捷键：长按空格键录音

探索步骤：

  1. 确认 OAuth token 可用
  2. 测试按住空格录音 → 释放后转录
  3. 验证实时中间转录显示
  4. 测试 /voice 命令切换

2.4 TEAMMEM（团队共享记忆）

  • 引用数：51
  • 功能：基于 GitHub 仓库的团队共享记忆系统，memory/team/ 目录双向同步到 Anthropic 服务器
  • 当前状态：完整实现，包括增量同步、冲突解决、密钥扫描、路径穿越防护
  • 关键文件：src/services/teamMemorySync/（index、watcher、secretScanner）、src/memdir/teamMemPaths.ts
  • 外部依赖：Anthropic OAuth + GitHub remote（getGithubRepo()）
  • 探索命令：FEATURE_TEAMMEM=1 bun run dev

探索步骤：

  1. 确认项目有 GitHub remote
  2. 开启后观察 memory/team/ 目录创建
  3. 测试团队记忆写入和同步
  4. 验证密钥扫描防护

2.5 COORDINATOR_MODE（多 Agent 编排）

  • 引用数：32
  • 功能：CLI 变为编排者，通过 AgentTool 派发任务给多个 worker 并行执行
  • 当前状态：核心逻辑实现，worker agent 模块为 stub
  • 关键文件：src/coordinator/coordinatorMode.ts（系统 prompt 完整）、src/coordinator/workerAgent.ts（stub）
  • 限制：编排者只能使用 AgentTool/TaskStop/SendMessage，不能直接操作文件
  • 探索命令：FEATURE_COORDINATOR_MODE=1 CLAUDE_CODE_COORDINATOR_MODE=1 bun run dev

探索步骤：

  1. 补全 workerAgent.ts stub
  2. 测试多 worker 并行任务派发
  3. 验证 worker 结果汇总

2.6 BRIDGE_MODE（远程控制）

  • 引用数：28
  • 功能：本地 CLI 注册为 bridge 环境，可从 claude.ai 或其他控制面远程驱动
  • 当前状态：v1（env-based）和 v2（env-less）实现均存在
  • 关键文件：src/bridge/bridgeEnabled.ts、src/bridge/replBridge.ts（v1）、src/bridge/remoteBridgeCore.ts（v2）
  • 外部依赖：claude.ai OAuth、GrowthBook 门控 tengu_ccr_bridge
  • 探索命令：FEATURE_BRIDGE_MODE=1 bun run dev

2.7 FORK_SUBAGENT（上下文继承子 Agent）

  • 引用数：4
  • 功能：AgentTool 生成 fork 子 agent，继承父级完整对话上下文，优化 prompt cache
  • 当前状态：完整实现（forkSubagent.ts），支持 worktree 隔离通知、递归防护
  • 关键文件：src/tools/AgentTool/forkSubagent.ts
  • 探索命令：FEATURE_FORK_SUBAGENT=1 bun run dev

2.8 TOKEN_BUDGET（Token 预算控制）

  • 引用数：9
  • 功能：解析用户指定的 token 预算（如 "spend 2M tokens"），自动持续工作直到达到目标
  • 当前状态：解析器完整实现，支持简写和详细语法；QueryEngine 中的周转逻辑已连接
  • 关键文件：src/utils/tokenBudget.ts、src/QueryEngine.ts
  • 探索命令：FEATURE_TOKEN_BUDGET=1 bun run dev

2.9 MCP_SKILLS（MCP 技能发现）

  • 引用数：9
  • 功能：将 MCP 服务器提供的 prompt 类型命令筛选为可调用技能
  • 当前状态：功能性实现（config 门控筛选器）
  • 关键文件：src/commands.ts（getMcpSkillCommands()）
  • 探索命令：FEATURE_MCP_SKILLS=1 bun run dev

2.10 TREE_SITTER_BASH（Bash AST 解析）

  • 引用数：3
  • 功能：纯 TypeScript bash 命令 AST 解析器，用于 fail-closed 权限匹配
  • 当前状态：完整实现（bashParser.ts ~2000行 + ast.ts ~400行）
  • 关键文件：src/utils/vendor/tree-sitter-bash/
  • 探索命令：FEATURE_TREE_SITTER_BASH=1 bun run dev

2.11 BUDDY（虚拟伙伴） ✅ 已完成

  • 引用数：16
  • 功能：/buddy 命令，支持 hatch/rehatch/pet/mute/unmute
  • 状态：✅ 已合入，功能完整可用（2026-04-02 完成）

三、Tier 2 — 部分实现（需要补全）

3.1 PROACTIVE（主动模式）

  • 引用数：37
  • 功能：Tick 驱动的自主代理，定时唤醒执行工作，配合 SleepTool 控制节奏
  • 当前状态：核心模块 src/proactive/index.ts 全部 stub（activate/deactivate/pause 返回 false 或空操作）
  • 依赖：与 KAIROS 强绑定（所有检查都是 feature('PROACTIVE') || feature('KAIROS')）
  • 补全工作量：中等 — 需要实现 tick 生成、SleepTool 集成、暂停/恢复逻辑

3.2 BASH_CLASSIFIER（Bash 命令分类器）

  • 引用数：45
  • 功能：LLM 驱动的 bash 命令意图分类（允许/拒绝/询问）
  • 当前状态：bashClassifier.ts 全部 stub（matches: false）
  • 补全工作量：大 — 需要 LLM 调用实现、prompt 设计

3.3 ULTRAPLAN（增强规划）

  • 引用数：10
  • 功能：关键字触发增强计划模式，输入 "ultraplan" 自动转为 plan
  • 当前状态：关键字检测完整实现，/ultraplan 命令为 stub
  • 补全工作量：小 — 只需实现命令处理逻辑

3.4 EXPERIMENTAL_SKILL_SEARCH（技能语义搜索）

  • 引用数：21
  • 功能：DiscoverSkills 工具，根据当前任务语义搜索可用技能
  • 当前状态：布线完整，核心搜索逻辑 stub
  • 补全工作量：中等 — 需要实现搜索引擎和索引

3.5 CONTEXT_COLLAPSE（上下文折叠）

  • 引用数：20
  • 功能：CtxInspectTool 让模型内省上下文窗口大小，优化压缩决策
  • 当前状态：工具 stub，HISTORY_SNIP 子功能也 stub
  • 补全工作量：中等

3.6 WORKFLOW_SCRIPTS（工作流自动化）

  • 引用数：10
  • 功能：基于文件的自动化工作流 + /workflows 命令
  • 当前状态：WorkflowTool、命令、加载器全部 stub
  • 补全工作量：大 — 需要从零设计工作流 DSL

3.7 WEB_BROWSER_TOOL（浏览器工具）

  • 引用数：4
  • 功能：模型可调用浏览器工具导航和交互网页
  • 当前状态：工具注册存在，实现 stub
  • 补全工作量：大

3.8 DAEMON（后台守护进程）

  • 引用数：3
  • 功能：后台守护进程 + 远程控制服务器
  • 当前状态：只有条件导入布线，无实现
  • 补全工作量：极大

四、Tier 3 — 纯 Stub / N/A（低优先级）

Feature 引用 状态 说明
CHICAGO_MCP 16 N/A Anthropic 内部 MCP 基础设施
UDS_INBOX 17 Stub Unix 域套接字对等消息
MONITOR_TOOL 13 Stub 文件/进程监控工具
BG_SESSIONS 11 Stub 后台会话管理
SHOT_STATS 10 无实现 逐 prompt 统计
EXTRACT_MEMORIES 7 无实现 自动记忆提取
TEMPLATES 6 Stub 项目/提示模板
LODESTONE 6 N/A 内部基础设施
STREAMLINED_OUTPUT 1 — 精简输出模式
HOOK_PROMPTS 1 — Hook 提示词
CCR_AUTO_CONNECT 3 — CCR 自动连接
CCR_MIRROR 4 — CCR 镜像模式
CCR_REMOTE_SETUP 1 — CCR 远程设置
NATIVE_CLIPBOARD_IMAGE 2 — 原生剪贴板图片
CONNECTOR_TEXT 7 — 连接器文本

以及其余 40+ 个低引用量 feature。

五、探索路线图

Phase 1：快速验证（无外部依赖）

目标：确认代码可以正常运行，体验基本功能

优先级 Feature 命令 预期效果
1 BUDDY FEATURE_BUDDY=1 bun run dev /buddy hatch 生成伙伴
2 FORK_SUBAGENT FEATURE_FORK_SUBAGENT=1 bun run dev Agent 可生成上下文继承的子任务
3 TOKEN_BUDGET FEATURE_TOKEN_BUDGET=1 bun run dev 输入 "spend 500k tokens" 测试自动持续
4 TREE_SITTER_BASH FEATURE_TREE_SITTER_BASH=1 bun run dev 更精确的 bash 权限匹配
5 MCP_SKILLS FEATURE_MCP_SKILLS=1 bun run dev MCP 服务器 prompt 提升为技能

Phase 2：核心功能探索（需要 OAuth）

目标：体验 KAIROS 全套能力

优先级 Feature 命令 预期效果
1 TRANSCRIPT_CLASSIFIER FEATURE_TRANSCRIPT_CLASSIFIER=1 bun run dev Auto mode 自动激活
2 KAIROS 全套 FEATURE_KAIROS=1 FEATURE_KAIROS_BRIEF=1 FEATURE_KAIROS_CHANNELS=1 FEATURE_PROACTIVE=1 bun run dev 常驻助手 + Brief 输出 + 频道消息
3 VOICE_MODE FEATURE_VOICE_MODE=1 bun run dev 按空格说话
4 TEAMMEM FEATURE_TEAMMEM=1 bun run dev 团队记忆同步
5 COORDINATOR_MODE FEATURE_COORDINATOR_MODE=1 CLAUDE_CODE_COORDINATOR_MODE=1 bun run dev 多 agent 编排

Phase 3：Stub 补全开发

目标：将高价值 stub 实现为可用功能

优先级 Feature 补全难度 价值
1 PROACTIVE 中 自主工作能力
2 ULTRAPLAN 小 增强规划
3 CONTEXT_COLLAPSE 中 长对话优化
4 EXPERIMENTAL_SKILL_SEARCH 中 技能发现
5 BASH_CLASSIFIER 大 安全增强

六、推荐组合方案

"全功能助手"组合

FEATURE_KAIROS=1 \
FEATURE_KAIROS_BRIEF=1 \
FEATURE_KAIROS_CHANNELS=1 \
FEATURE_KAIROS_PUSH_NOTIFICATION=1 \
FEATURE_PROACTIVE=1 \
FEATURE_FORK_SUBAGENT=1 \
FEATURE_TOKEN_BUDGET=1 \
FEATURE_TRANSCRIPT_CLASSIFIER=1 \
FEATURE_BUDDY=1 \
bun run dev

"多 Agent 协作"组合

FEATURE_COORDINATOR_MODE=1 \
FEATURE_FORK_SUBAGENT=1 \
FEATURE_BRIDGE_MODE=1 \
FEATURE_BG_SESSIONS=1 \
CLAUDE_CODE_COORDINATOR_MODE=1 \
bun run dev

"开发者增强"组合

FEATURE_TRANSCRIPT_CLASSIFIER=1 \
FEATURE_TREE_SITTER_BASH=1 \
FEATURE_TOKEN_BUDGET=1 \
FEATURE_MCP_SKILLS=1 \
FEATURE_CONTEXT_COLLAPSE=1 \
bun run dev

七、风险与注意事项

  1. OAuth 依赖：KAIROS、VOICE_MODE、TEAMMEM、BRIDGE_MODE 需要 Anthropic OAuth 认证（claude.ai 订阅），API key 用户无法使用
  2. GrowthBook 门控：部分功能（VOICE_MODE 的 tengu_cobalt_frost、TEAMMEM 的 tengu_herring_clock）即使 feature flag 开启，还需要服务端 GrowthBook 开关
  3. 反编译不完整：所有"已实现"功能均为反编译产物，可能存在运行时错误，需要逐个验证
  4. Proactive stub：KAIROS 的自主工作能力依赖 PROACTIVE，但 PROACTIVE 核心是 stub，需先补全
  5. tsc 错误：代码库有 ~1341 个 TypeScript 编译错误（来自反编译），不影响 Bun 运行时但在 IDE 中会有大量红线

附录：Feature Flag 完整列表

共 89 个 feature flag（按引用数降序）：

Feature 引用 Tier
KAIROS 154 1
TRANSCRIPT_CLASSIFIER 108 1
TEAMMEM 51 1
VOICE_MODE 46 1
BASH_CLASSIFIER 45 2
KAIROS_BRIEF 39 1
PROACTIVE 37 2
COORDINATOR_MODE 32 1
BRIDGE_MODE 28 1
EXPERIMENTAL_SKILL_SEARCH 21 2
CONTEXT_COLLAPSE 20 2
KAIROS_CHANNELS 19 1
UDS_INBOX 17 3
CHICAGO_MCP 16 3
BUDDY 16 1
HISTORY_SNIP 15 2
MONITOR_TOOL 13 3
COMMIT_ATTRIBUTION 12 —
CACHED_MICROCOMPACT 12 —
BG_SESSIONS 11 3
WORKFLOW_SCRIPTS 10 2
ULTRAPLAN 10 2
SHOT_STATS 10 3
TOKEN_BUDGET 9 1
PROMPT_CACHE_BREAK_DETECTION 9 —
MCP_SKILLS 9 1
EXTRACT_MEMORIES 7 3
CONNECTOR_TEXT 7 —
TEMPLATES 6 3
LODESTONE 6 3
TREE_SITTER_BASH_SHADOW 5 —
QUICK_SEARCH 5 —
MESSAGE_ACTIONS 5 —
DOWNLOAD_USER_SETTINGS 5 —
DIRECT_CONNECT 5 —
WEB_BROWSER_TOOL 4 2
VERIFICATION_AGENT 4 —
TERMINAL_PANEL 4 —
SSH_REMOTE 4 —
REVIEW_ARTIFACT 4 —
REACTIVE_COMPACT 4 —
KAIROS_PUSH_NOTIFICATION 4 1
HISTORY_PICKER 4 —
FORK_SUBAGENT 4 1
CCR_MIRROR 4 —
TREE_SITTER_BASH 3 1
MEMORY_SHAPE_TELEMETRY 3 —
MCP_RICH_OUTPUT 3 —
KAIROS_GITHUB_WEBHOOKS 3 1
FILE_PERSISTENCE 3 —
DAEMON 3 2
CCR_AUTO_CONNECT 3 —
UPLOAD_USER_SETTINGS 2 —
POWERSHELL_AUTO_MODE 2 —
OVERFLOW_TEST_TOOL 2 —
NEW_INIT 2 —
NATIVE_CLIPBOARD_IMAGE 2 —
HARD_FAIL 2 —
ENHANCED_TELEMETRY_BETA 2 —
COWORKER_TYPE_TELEMETRY 2 —
BREAK_CACHE_COMMAND 2 —
AWAY_SUMMARY 2 —
AUTO_THEME 2 —
ALLOW_TEST_VERSIONS 2 —
AGENT_TRIGGERS_REMOTE 2 —
AGENT_MEMORY_SNAPSHOT 2 —
UNATTENDED_RETRY 1 —
ULTRATHINK 1 —
TORCH 1 —
STREAMLINED_OUTPUT 1 —
SLOW_OPERATION_LOGGING 1 —
SKILL_IMPROVEMENT 1 —
SELF_HOSTED_RUNNER 1 —
RUN_SKILL_GENERATOR 1 —
PERFETTO_TRACING 1 —
NATIVE_CLIENT_ATTESTATION 1 —
KAIROS_DREAM 1 1
IS_LIBC_MUSL 1 —
IS_LIBC_GLIBC 1 —
HOOK_PROMPTS 1 —
DUMP_SYSTEM_PROMPT 1 —
COMPACTION_REMINDERS 1 —
CCR_REMOTE_SETUP 1 —
BYOC_ENVIRONMENT_RUNNER 1 —
BUILTIN_EXPLORE_PLAN_AGENTS 1 —
BUILDING_CLAUDE_APPS 1 —
ANTI_DISTILLATION_CC 1 —
AGENT_TRIGGERS 1 —
ABLATION_BASELINE 1 —