@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 —— 一个 5 步管线，在每次 LLM 调用前自动聚合精准上下文：

UserQuery → QueryParser → 真正异步并行查询(Code Graph + Memory + Orchestration) → 去重合并 → 智能压缩 → ContextPack

关键特性：

• 真正的异步并行 — 使用 execSafeAsync + Promise.allSettled，非假并行
• 智能 Token 预算 — 动态重分配空源预算，bugWarnings 封顶保护，跨源文件去重
• 阶段感知记忆检索 — 按 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 目录

双模式运行

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 (批处理)

# 指定编排引擎
codeagent chat --orchestration gsd          # GSD-Lite
codeagent chat --orchestration superpowers  # Superpowers

# 预算控制
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>             # 删除会话

配置

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

codeagent config set provider api                # 默认使用 API provider
codeagent config set orchestration 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    │
       │  (5-step pipeline) │
       └──┬────┬────┬──────┘
          │    │    │
    ┌─────┘    │    └─────┐
    ▼          ▼          ▼
┌────────┐ ┌───────┐ ┌──────────┐
│ Code   │ │Memory │ │  Orch    │
│ Graph  │ │Engine │ │ Adapter  │
│ (Rust) │ │(Node) │ │GSD|Super │
└────────┘ └───────┘ └──────────┘

项目结构

src/
├── broker/                 # Context Broker 核心
│   ├── broker.ts           # buildContextPack() — 5 步管线主入口
│   ├── query-parser.ts     # 意图检测 + 实体提取 (EN/ZH 双语)
│   ├── context-pack.ts     # ContextPack 类型 + Zod schema
│   └── compressor.ts       # Token 预算压缩 (优先级排序)
│
├── adapters/               # 外部系统适配器
│   ├── code-graph.ts       # Code Graph MCP CLI 适配
│   ├── memory.ts           # claude-mem-lite CLI 适配
│   └── orchestration/
│       ├── interface.ts    # OrchestrationAdapter 统一接口
│       ├── gsd.ts          # GSD-Lite (读 .gsd/state.json)
│       └── superpowers.ts  # Superpowers (无状态, 技能发现)
│
├── 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
│   └── 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 估算 + 截断

编程接口

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 (可选) — 代码搜索。未安装时 Broker 跳过代码上下文。
• claude-mem-lite (可选) — 记忆系统。未安装时 Broker 跳过记忆上下文。
• ANTHROPIC_API_KEY — 使用 --provider api 时需要。

开发

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

数据存储

数据	位置
会话数据库	~/.local/share/codeagent/codeagent.db
全局配置	~/.config/codeagent/config.json
项目 hooks	.claude/settings.json

License

MIT