npm package: @sdsrs/codeagent
Description: CodeAgent — Context Broker + CLI for intelligent coding assistance. Integrates code search, memory, and orchestration.
Author: sdsrs
Latest version: 0.9.1

# @sdsrs/codeagent

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

## 安装

```bash
# 全局安装
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](https://github.com/sdsrss/code-graph-mcp) | Rust | AST 解析、混合搜索、调用图、影响分析 | CLI (`code-graph-mcp`) |
| [claude-mem-lite](https://github.com/sdsrss/claude-mem-lite) | Node.js | 类型化记忆、FTS5+向量召回 | CLI (`claude-mem-lite`) |
| [GSD-Lite](https://github.com/sdsrss/gsd-lite) / Superpowers | Node.js | 编排状态机、阶段管理 | 读 state.json / 读 skills 目录 |
| [Context7](https://github.com/upstash/context7) | Node.js | 库文档实时检索 | CLI (`context7`) |

## 双模式运行

### Mode A: 独立 CLI (`codeagent chat`)

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

```bash
# 新会话
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 内自动注入上下文，零学习成本。

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

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

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

## 其他命令

### 代码搜索

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

### 记忆管理

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

### 会话管理

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

### 上下文度量

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

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

### 配置

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

```bash
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 模块，可在自己的代码中使用：

```typescript
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` 时需要。

## 开发

```bash
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