@sdsrs/codeagent

@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)、gitDiff(+2)、symbol match(+2)、impact(+1) 多维评分，高信号文件优先
• 内容分级注入 — HOT(评分≥6): 全文 snippet / WARM(3-5): 5 行签名 / COLD(<3): 仅路径，同预算覆盖更多文件
• Tree-sitter Repo Map 降级 — code-graph-mcp 不可用时自动用 tree-sitter 提取代码结构，含 import graph PageRank 排序
• 库文档实时注入 — 检测查询中的库名，通过 context7 CLI 注入最新 API 文档
• 上下文质量度量 — 自动持久化到 JSONL，codeagent metrics 查看历史分析（源命中率/延迟/token 利用率）
• 阶段感知记忆检索 — 按 implement/debug/brainstorm 等阶段过滤记忆类型
• 配置文件生效 — config set 的值自动成为 CLI 默认值

它消费 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
│   ├── query-parser.ts     # 意图检测 + 实体提取 (EN/ZH 双语, 引号符号)
│   ├── context-pack.ts     # ContextPack 类型 + Zod schema + metrics types
│   └── compressor.ts       # Token 预算压缩 (跨源评分 + HOT/WARM/COLD 分级)
│
├── adapters/               # 外部系统适配器
│   ├── code-graph.ts       # Code Graph MCP CLI 适配 (含 repo-map 降级)
│   ├── repo-map.ts         # Tree-sitter repo map + import graph PageRank (降级路径)
│   ├── lib-docs.ts         # Context7 库文档注入
│   ├── memory.ts           # claude-mem-lite CLI 适配
│   └── 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             # 带超时的安全命令执行
    ├── tokens.ts           # Token 估算 + 截断
    └── 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                    # 420 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