@sdsrs/codeagent

上下文感知的编程 Agent —— 将代码搜索、记忆系统、编排引擎整合为统一的 Context Broker，支持独立 CLI 和 Claude Code 增强两种运行模式。

安装

# 全局安装
npm install -g @sdsrs/codeagent

# 直接运行
npx @sdsrs/codeagent --help

# 安装后可用两个命令
codeagent chat
devx chat

核心概念

CodeAgent 的核心是 Context Broker —— 一个 6 路并行管线，在每次 LLM 调用前自动聚合精准上下文：

UserQuery → QueryParser → 6路异步并行查询(Code + Memory + Orch + ChangedFiles + Git + LibDocs) → 去重合并 → 智能压缩 → ContextPack

关键特性：

• 6 路异步并行 — 使用 execSafeAsync + Promise.allSettled，任何源失败不阻塞
• 智能 Token 预算 — 默认 code:700 memory:600 orch:300 meta:200 docs:200，意图自适应 + 空源动态重分配
• 跨源评分排序 — bugWarning(+3)、filePath(+3)、gitDiff(+2)、symbol match(+2)、impact(+1) 多维评分，高信号文件优先
• 内容分级注入 — HOT(评分≥6): 全文 snippet / WARM(3-5): 代码文件 8 行签名、配置文件 5 行 / COLD(<3): 仅路径
• 轮次注入衰减 — 通过 TurnHistory 跟踪已注入文件路径，最近注入的文件得分衰减（age=1: ×0.3, age=2: ×0.6），避免重复注入
• 查询级缓存 — 相似查询（Jaccard > 0.7 且意图相同）30s 内复用上轮 ContextPack，跳过完整管线
• CJK 双语增强 — 7 种意图 × 加权 regex + bigram 短语匹配 + CJK 滑动窗口关键词提取，中英文查询同等质量
• Tree-sitter Repo Map 降级 — code-graph-mcp 不可用时自动用 tree-sitter 提取代码结构（TS/JS/Python/Go），含 import graph PageRank 排序
• 库文档实时注入 — 检测查询中的库名 + package.json 依赖交叉匹配，通过 context7 CLI 并行注入最新 API 文档
• 上下文质量度量 — 自动持久化到 JSONL，codeagent metrics 查看历史分析（源命中率/延迟/token 利用率）
• 阶段感知记忆检索 — 按 implement/debug/brainstorm 等阶段过滤记忆类型
• 配置文件生效 — config set 的值自动成为 CLI 默认值
• 语言标签注入 — 代码片段自动识别语言并添加 fenced code block 标签，提升 Claude 解析效率

它消费 3 个已有系统但不合并代码，通过 CLI 调用保持松耦合：

| 系统 | 语言 | 职责 | 调用方式 | |------|------|------|---------| | Code Graph MCP | Rust | AST 解析、混合搜索、调用图、影响分析 | CLI (code-graph-mcp) | | claude-mem-lite | Node.js | 类型化记忆、FTS5+向量召回 | CLI (claude-mem-lite) | | GSD-Lite / Superpowers | Node.js | 编排状态机、阶段管理 | 读 state.json / 读 skills 目录 | | Context7 | Node.js | 库文档实时检索 | CLI (context7) |

双模式运行

Mode A: 独立 CLI (codeagent chat)

完全掌控消息流的交互式 Agent，基于 Claude Agent SDK。

# 新会话
codeagent chat

# 续接会话
codeagent chat --resume <sessionId>

# 指定 provider
codeagent chat --provider sdk     # Agent SDK (默认，完整工具能力)
codeagent chat --provider api     # Anthropic API (轻量，无工具执行)
codeagent chat --provider cli     # claude -p (批处理)

# 指定编排引擎（默认 auto — 自动检测并组合可用引擎）
codeagent chat --orchestration auto         # 自动检测 (默认)
codeagent chat --orchestration superpowers  # 仅 Superpowers
codeagent chat --orchestration gsd          # 仅 GSD-Lite
codeagent chat --orchestration none         # 禁用编排

# 预算控制
codeagent chat --max-budget 2.0

会话内命令：

| 命令 | 功能 | |------|------| | /help | 显示所有命令 | | /quit | 结束会话 | | /status | 查看会话信息 | | /stage | 查看当前阶段 | | /cost | 查看累计费用 | | /context | 查看上次注入的上下文 | | /brainstorm | 切换到 brainstorm 阶段 | | /plan | 切换到 plan 阶段 | | /implement | 切换到 implement 阶段 | | /review | 切换到 review 阶段 | | /debug | 切换到 debug 阶段 |

Mode B: Claude Code 增强 (hooks)

通过 hooks 在 Claude Code 内自动注入上下文，零学习成本。

# 安装 hooks 到当前项目
npm run install-hooks

# 安装 hooks 到全局
npm run install-hooks:global

| Hook | 触发时机 | 行为 | |------|---------|------| | UserPromptSubmit | 每次用户输入 | Context Broker 生成 ContextPack → 注入到 prompt | | SessionStart | 会话开始 | 注入项目概要 + 活跃编排状态 | | PostCompact | 上下文压缩后 | 重注入编排状态 + bug 警告，防止压缩丢失 | | Stop | 会话结束 | 从对话中提取关键发现 → 写入记忆 |

其他命令

代码搜索

codeagent search "payment processing"              # 语义搜索
codeagent search "RefundService" --type impact      # 影响分析
codeagent search "processPayment" --type callgraph  # 调用图
codeagent search "src/payment/" --type overview     # 模块概览

记忆管理

codeagent memory "authentication"                                    # 搜索记忆
codeagent memory --save "金额用 cents" --type decision --body "避免浮点精度问题"  # 保存记忆

会话管理

codeagent session list                    # 列出会话
codeagent session show <id>               # 查看详情
codeagent session delete <id>             # 删除会话

上下文度量

codeagent metrics                    # 显示最近 50 次调用的性能分析
codeagent metrics --limit 100        # 分析最近 100 次

输出内容：源命中率 + 平均延迟、意图分布、Token 利用率百分位、管线延迟百分位。 数据自动持久化到 ~/.local/share/codeagent/metrics.jsonl（500KB 自动轮转）。

配置

配置值自动成为 CLI 命令的默认值（命令行参数仍然优先）：

codeagent config set provider api                # 默认使用 API provider
codeagent config set orchestration auto          # 自动检测编排 (默认)
codeagent config set orchestration superpowers   # 强制 Superpowers
codeagent config set model claude-opus-4-6       # 设置模型
codeagent config set maxBudgetUsd 5.0            # 设置预算上限
codeagent config get                             # 查看所有配置
codeagent config path                            # 查看配置文件路径

架构

┌──────────────────────────────┐
│         用户入口 (双模式)       │
│                              │
│  Mode A           Mode B     │
│  ┌──────────┐  ┌──────────┐ │
│  │ devx CLI  │  │Claude Code│ │
│  │ (TUI)     │  │  hooks    │ │
│  │ Agent SDK │  │ + skills  │ │
│  └─────┬─────┘  └─────┬────┘ │
└────────┼───────────────┼──────┘
         └───────┬───────┘
                 ▼
       ┌─────────────────────────┐
       │    Context Broker        │
       │  (6-source pipeline)     │
       └──┬────┬────┬────┬───┬──┘
          │    │    │    │   │
    ┌─────┘    │    │    │   └──────┐
    ▼          ▼    ▼    ▼          ▼
┌────────┐ ┌─────┐ ┌──────┐ ┌────┐ ┌──────┐
│Code    │ │Mem  │ │Orch  │ │Git │ │Lib   │
│Graph / │ │     │ │      │ │Diff│ │Docs  │
│RepoMap │ │     │ │      │ │    │ │      │
│(Rust/  │ │(Node│ │GSD|  │ │    │ │(ctx7)│
│TS)     │ │)    │ │Super │ │    │ │      │
└────────┘ └─────┘ └──────┘ └────┘ └──────┘

项目结构

src/
├── broker/                 # Context Broker 核心
│   ├── broker.ts           # buildContextPack() — 6 路管线主入口 + metrics + Jaccard 缓存
│   ├── query-parser.ts     # 意图检测 + 实体提取 (EN/ZH 双语, bigram, CJK 分词)
│   ├── context-pack.ts     # ContextPack 类型 + Zod schema + metrics types + adaptBudget
│   ├── compressor.ts       # Token 预算压缩 (跨源评分 + HOT/WARM/COLD 分级 + 注入衰减)
│   └── turn-history.ts     # 轮次注入跟踪 (session_events 读写 + context_reset 边界)
│
├── adapters/               # 外部系统适配器
│   ├── code-graph.ts       # Code Graph MCP CLI 适配 (含 repo-map 降级 + 内容片段注入)
│   ├── repo-map.ts         # Tree-sitter repo map + import graph PageRank (TS/JS/Python/Go)
│   ├── lib-docs.ts         # Context7 库文档注入 (package.json 交叉匹配)
│   ├── memory.ts           # claude-mem-lite CLI 适配 (ID/title 去重)
│   ├── git.ts              # Git diff 适配 (changed files + function context + branch)
│   └── orchestration/
│       ├── interface.ts    # OrchestrationAdapter 统一接口
│       ├── factory.ts      # createOrchAdapter() 工厂 + auto-detect
│       ├── composite.ts    # CompositeOrchAdapter (多源合并)
│       ├── gsd.ts          # GSD-Lite (读 .gsd/state.json)
│       ├── superpowers.ts  # Superpowers (技能发现 + spec/plan 读取)
│       └── null.ts         # NullOrchAdapter (无编排降级)
│
├── providers/              # LLM Provider 抽象层
│   ├── interface.ts        # AgentProvider 接口 + TurnEvent 类型
│   ├── claude-sdk.ts       # Agent SDK V1 query() + resume
│   ├── claude-cli.ts       # claude -p 批处理
│   └── anthropic-api.ts    # 直接 API 调用 (流式)
│
├── session/                # 会话管理
│   ├── schema.ts           # SQLite schema + 迁移
│   └── manager.ts          # SessionManager CRUD + 事件记录 + 惰性单例
│
├── cli/                    # 命令行界面
│   ├── index.ts            # Commander.js 主入口
│   ├── commands/           # chat, search, memory, session, config, metrics
│   └── tui/renderer.ts     # ANSI TUI: spinner, stage, markdown
│
├── hooks/                  # Claude Code 生命周期 hooks
│   ├── user-prompt.ts      # UserPromptSubmit → Broker → 注入
│   ├── session-start.ts    # SessionStart → 项目概要
│   ├── post-compact.ts     # PostCompact → 恢复编排状态 + bug 警告
│   └── stop.ts             # Stop → 记忆写入
│
├── skills/                 # Claude Code Skills
│   ├── brainstorm.md       # 强制 brainstorm 模式
│   └── review.md           # bug memory 感知的代码审查
│
├── scripts/
│   └── install-hooks.ts    # 一键注册 hooks 到 settings.json
│
└── utils/
    ├── exec.ts             # 带超时的安全命令执行 (sync + async, 无 shell)
    ├── tokens.ts           # Token 估算 (CJK/非CJK 分离) + 截断
    ├── deadline.ts         # withDeadline() — Hook 外层超时保护
    ├── debug.ts            # debugLog/debugTiming (CODEAGENT_DEBUG=1)
    └── metrics-log.ts      # Metrics JSONL 持久化 + 轮转

编程接口

CodeAgent 同时导出 npm 模块，可在自己的代码中使用：

import { ContextBroker, formatContextPack } from '@sdsrs/codeagent';
import { hasContent } from '@sdsrs/codeagent/context-pack';
import { SessionManager } from '@sdsrs/codeagent/session';

// 构建上下文
const broker = new ContextBroker(process.cwd());
const pack = await broker.buildContextPack({
  repoRoot: process.cwd(),
  userQuery: 'how does the payment module work?',
  stage: 'brainstorm',
});

if (hasContent(pack)) {
  console.log(formatContextPack(pack));
}

环境要求

• Node.js >= 20
• code-graph-mcp (可选) — 代码搜索。未安装时自动降级到 tree-sitter repo map。
• claude-mem-lite (可选) — 记忆系统。未安装时 Broker 跳过记忆上下文。
• context7 (可选) — 库文档注入。未安装时跳过文档上下文。安装：npm install -g @upstash/context7
• ANTHROPIC_API_KEY — 使用 --provider api 时需要。

开发

git clone https://github.com/sdsrss/codeagent.git
cd codeagent
npm install
npm run build
npm test                    # 477 tests (unit + integration)
npm run dev                 # watch mode

数据存储

| 数据 | 位置 | |------|------| | 会话数据库 | ~/.local/share/codeagent/codeagent.db | | 度量日志 | ~/.local/share/codeagent/metrics.jsonl | | 全局配置 | ~/.config/codeagent/config.json | | 项目 hooks | .claude/settings.json |

License

MIT