B Code

一个从零构建的编码 Agent CLI —— 你自己的 Claude Code。

在终端里用自然语言下达任务：读代码、改文件、跑命令、写计划，全程可见工具调用与权限审批。

npm i -g @bysking/b-code    # 全局安装
# 或
npx -y @bysking/b-code      # 免安装直接使用

安装

# 从 npm 全局安装（推荐）
npm i -g @bysking/b-code

# 或从本仓库安装（需要先构建，见「开发」）
npm run build && npm i -g .

安装后得到 bcode 命令。开发模式直接运行：

npm run dev            # 相当于 tsx src/index.ts

快速开始

One-shot（执行一条指令后退出）：

bcode "Read the README and summarize what this project does"

REPL（交互式多轮对话，每轮自动保存）：

bcode

命令行参数

参数	说明
bcode "指令"	One-shot：执行单条指令后保存退出（可含权限确认）
bcode	REPL：交互式多轮对话
bcode --resume	REPL 并恢复上次会话
bcode --session <id>	恢复指定会话（配合--resume）
bcode --plan "指令"	Plan 模式：写 / 编辑 / shell 全部拦截，只读规划
bcode --yolo "指令"	Bypass 模式：跳过 confirm（危险命令 deny 仍拦得住）
bcode --auto "指令"	Auto 模式：用分类器代替确认框
bcode --goal <条件> "指令"	Auto 追目标：无人值守循环，直到条件达成
bcode --loop <秒> "指令"	定时重投：每隔 N 秒重复执行指令（Ctrl-C 停止）

退出时会打印恢复命令，例如：

想恢复本次会话，执行:
  bcode --resume --session <id>

交互界面（TTY）

TTY 下使用 Ink 渲染：思考过程、工具调用块、Markdown 回复、权限确认、斜杠菜单均为声明式 UI。

斜杠命令（输入 / 可唤起补全菜单）：

命令	说明
/clear	清空当前对话历史（并重置"本轮自动审批"标记）
/plan	切换 Plan（只读）模式
/yolo	切换 Bypass 模式
/auto	切换 Auto 模式（分类器管控写/shell）
/default	切换回默认模式
/skills	列出可用技能
/mcp	列出已配置的 MCP server
/remember <事实>	保存一条长期记忆
exit / quit	退出

快捷键：

• Esc：软中断当前对话（可继续输入新指令）

非 TTY（管道 / CI / 脚本）下自动退化为 readline 交互，语义保持一致；权限确认只消费 y/n 行。

权限与模式

四种模式：default / plan / bypass / auto。

权限判定三态：allow（放行）/ deny（拦截）/ confirm（询问），遵循三个原则：

1. deny 优先 —— 危险命令在任何模式（含 --yolo）下都拦得住；
2. fail-closed —— 未声明模式的工具默认 confirm，不默认放行；
3. plan 只读由权限层强制 —— 不靠提示词"求"模型别动。

以下危险命令直接 deny（连 --yolo 也绕不过）：

rm -rf / git push / git reset --hard / sudo / mkfs
> /dev/ 设备写入 / dd / kill / reboot / shutdown

技能（Skills）

把常用提示词包装成 /name 参数 命令。技能支持两种形态，技能名 = 文件名 / 目录名：

平铺文件 {name}.md —— 单文件即技能：

---
name: commit
description: 用规范格式提交代码
user-invocable: true
---

按以下规范提交：$ARGUMENTS

技能目录 {name}/SKILL.md —— 对齐 Claude 生态，目录名即技能名，描述与正文读目录下的 SKILL.md（或小写 skill.md），目录里的其他文件（reference、模板等）作为技能资源：

.claude/skills/
├── commit.md                      # 平铺形态
└── changelog-generator/
    ├── SKILL.md                   # 目录形态：描述 + 正文
    └── templates/                 # 技能资源，不参与解析

两种形态的差异：

	平铺文件	技能目录
技能名	文件名（去 .md）	目录名
user-invocable	需显式写 true	默认可调用，写 false 关闭
同名冲突	同目录内平铺优先	—

正文里的 $ARGUMENTS 会被替换为调用时传入的参数。技能调用优先于普通对话： /commit 修复登录 bug → 命中 commit 技能并替换参数。

frontmatter 的 description 支持块标量多行写法（>- 折叠成一行、| 保留换行），与 Claude 生态 SKILL.md 兼容。

搜索链（越靠前优先级越高，同名技能前者生效）：

1. {cwd}/.claude/skills —— 项目级
2. $B_CODE_SKILLS_DIR —— 显式覆盖（CI / 多环境）
3. $B_CODE_HOME/skills —— 用户级，随数据根迁移
4. ~/.claude/skills —— 兼容既有 Claude 生态的兜底

记忆（Memory）

跨会话长期记忆。模型通过 save_memory 工具主动沉淀（经用户确认后落盘），也可以在 REPL 里用 /remember 手动保存。

• 存储：{B_CODE_HOME}/projects/{sha256(cwd)前16位}/memory/*.md
• 召回：关键词重叠打分，纯确定性、不调模型；top3 注入 system prompt 末尾
• 隔离：同一目录的工作区各自独立记忆

MCP

启动时自动挂载配置的 MCP 服务器（失败仅记日志，不阻塞）。

配置搜索链（env 最高优先，同名 server 后者胜）：

1. $B_CODE_MCP_CONFIG —— 显式覆盖
2. {cwd}/.claude/mcp.json —— 项目级
3. {B_CODE_HOME}/mcp.json —— 用户级

{
  "mcpServers": {
    "demo": {
      "mode": "read",
      "command": "node",
      "args": ["/path/to/server.cjs"]
    }
  }
}

mode: "read" 声明该 server 所有工具按只读放行（免确认）；缺省 fail-closed → 需要确认。

配置

settings.json

配置文件位于 {B_CODE_HOME}/settings.json（B_CODE_CONFIG 可覆盖路径），复制 settings.example.json 后按需填写。

合并原则：真实环境变量优先，配置只是缺省值 —— 已 export 的键不会被覆盖。

字段	说明
provider	"anthropic" 或 "openai"（缺省按 endpoint 智能判断）
apiKey	对应 provider 的密钥
baseUrl	对应 provider 的端点（支持 OpenAI 兼容端点）
model	覆盖默认模型名（等价B_CODE_MODEL）
env	{ KEY: value } 注入环境变量

环境变量

变量	说明
B_CODE_HOME	数据根目录（必须绝对路径；缺省~/.b-code）
B_CODE_CONFIG	配置文件路径覆盖
B_CODE_MODEL	模型名覆盖
B_CODE_MAX_TOKENS	单次输出上限 token（缺省 4096）
B_CODE_THINKING	正整数时开启 extended thinking（预算 token）
B_CODE_HTTP_TIMEOUT	OpenAI 兼容后端流式空闲超时 ms（缺省 120000）
B_CODE_SHELL_TIMEOUT	run_shell 命令超时 ms（缺省 30000）
B_CODE_SKILLS_DIR	技能目录覆盖
B_CODE_MCP_CONFIG	MCP 配置文件覆盖
B_CODE_LOG_LEVEL	日志级别：debug / info / warn / error
B_CODE_LOG_FILE	true 时输出日志到文件
ANTHROPIC_API_KEY / OPENAI_API_KEY	对应 provider 的密钥
ANTHROPIC_BASE_URL / OPENAI_BASE_URL	对应 provider 的端点

数据目录

启动时自动创建（对齐 Claude Code 的约定目录）：

{B_CODE_HOME}/
├── sessions/     # 会话持久化
├── logs/         # 调试日志
├── projects/     # 跨项目记忆（按项目哈希隔离）
├── skills/       # 用户级技能
├── plans/        # Plan 文件
├── session.json  # 最近一次会话
└── mcp.json      # 用户级 MCP 配置

开发

npm install        # 安装依赖
npm run dev        # 开发运行（tsx 直跑 TS 源码）
npm run typecheck  # 类型检查
npm test           # 单元测试
npm run build      # esbuild 打包 → dist/cli.mjs（单文件，含全部依赖）
node dist/cli.mjs  # 验证产物

发布前 prepublishOnly 会自动执行 npm run build && npm test。

License

MIT