smartcode-x

AI 代码智能体 CLI，支持工具调用（读写文件、Shell、MCP、Web 等），架构对齐 Claude Code。命令行入口：smartcode-x。

支持 macOS / Linux / Windows（Windows 使用 PowerShell 或 CMD，需 Node.js 18+）。

配置来源：仅 settings.json 分层 + settings.json 内 env 块 + 可选的 Shell 环境变量 / CLI 参数。不会自动读取项目根目录的 .env 文件（与 npm install -g 安装后的行为一致）。

安装

# macOS / Linux / Windows（PowerShell 相同）
npm install -g smartcode-x
smartcode-x --version

安装后验证：smartcode-x --version 应只输出版本号（如 smartcode-x 0.1.2），不应有多余日志。

仓库内开发：

cd smart-code
npm install
npm run cli          # 或 npm link 后全局 smartcode-x

更多安装方式（离线包、内网 registry）：docs/install.md

维护者：发布到 npm

npm 包名：smartcode-x（公开包，用户安装：npm install -g smartcode-x）。完整说明见 docs/publish-npm.md。

一次性：登录 npm

npm login          # 浏览器或 OTP 完成认证
npm whoami         # 确认当前账号

若账号启用了 2FA，发布时需输入 OTP。

每次发版（推荐流程）

在 smart-code/ 目录执行：

cd smart-code

# 1. 测试 + 构建（发布前必跑）
npm run test:ci

# 2. 升版本（三选一；会改 package.json / package-lock.json，并在 git 仓库内自动 commit + tag）
npm version patch    # 0.1.2 → 0.1.3  修 bug
npm version minor    # 0.1.2 → 0.2.0  新功能
npm version major    # 0.1.2 → 1.0.0  破坏性变更

# 不想自动 git commit/tag 时，用手动改 version：
# 编辑 package.json 的 "version"，再执行下面步骤

# 3. 预览将要上传的文件（应主要是 dist/、bin/、README、LICENSE）
npm pack --dry-run

# 4. 本地试装（可选）
npm pack
npm install -g ./smartcode-x-0.1.2.tgz
smartcode-x --version

# 5. 发布（prepublishOnly 会自动 npm run build）
npm publish

# 6. 推送 git（若用了 npm version）
git push && git push --tags

# 7. 验证线上包
npm view smartcode-x version
npm install -g smartcode-x@latest
smartcode-x --version

常用命令速查

| 命令 | 作用 | |------|------| | npm run build | 编译 TypeScript → dist/ | | npm run test:ci | 构建 + 跑全量测试 | | npm pack --dry-run | 预览发布 tarball 内容 | | npm publish | 上传到 npmjs.com | | npm deprecate [email protected] "请升级" | 标记旧版本（慎用） | | npm unpublish [email protected] | 撤回指定版本（72 小时内且几乎无下载；慎用） |

发布前检查

| 项 | 说明 | |----|------| | 包内容 | package.json 的 files 仅含 dist、bin；不会带上 .env、settings.json、源码 src/ | | 构建 | prepublishOnly 已配置为发布前自动 npm run build | | Node | 要求 >= 18（engines 字段） | | 全局命令 | 发布后用户得到 smartcode-x 与别名 smart-code |

常见问题

E403 Forbidden — 当前 npm 账号无 smartcode-x 发布权限，需包 owner 在 npm 网站添加协作者。

E402 / 需付费 — scope 包（@xxx/pkg）首次须 npm publish --access public；smartcode-x 无 scope，直接 npm publish 即可。

用户装完 smartcode-x: command not found — 全局 bin 不在 PATH，见 docs/install.md。

快速开始（推荐：自动引导）

无需手动复制 JSON。安装后直接启动：

smartcode-x

若本机尚未配置 API Key，会自动进入交互式模型配置引导：选择 Anthropic 或 OpenAI 标准入口，填写模型名 / API 地址 / Key，并生成 settings.json 后进入对话。

也可随时重新配置：

smartcode-x setup
# 别名：smartcode-x init

启动后输入自然语言即可；输入 / 回车打开命令菜单，/help 查看全部斜杠命令。

Windows 一键流程（PowerShell）

npm install -g smartcode-x
smartcode-x --version
smartcode-x                    # 首次会自动进入配置引导
cd D:\path\to\your-project
smartcode-x

配置会写入：%USERPROFILE%\.smartcode-x\settings.json（例如 C:\Users\你\.smartcode-x\settings.json）。

macOS / Linux 一键流程

npm install -g smartcode-x
smartcode-x --version
smartcode-x                    # 首次会自动进入配置引导
cd /path/to/your-project
smartcode-x

配置会写入：~/.smartcode-x/settings.json。

手动编辑配置（可选）

若不想用引导，可复制模板后自行编辑：

# macOS / Linux
mkdir -p ~/.smartcode-x
cp .smartcode-x/settings.example.json ~/.smartcode-x/settings.json

# Windows PowerShell
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.smartcode-x"
Copy-Item .smartcode-x\settings.example.json "$env:USERPROFILE\.smartcode-x\settings.json"
notepad "$env:USERPROFILE\.smartcode-x\settings.json"

模板文件：.smartcode-x/settings.example.json

首次使用：模型配置引导

smartcode-x 在交互式终端下启动时，若检测不到 API Key，会启动配置向导（与 smartcode-x setup 相同逻辑）。

何时触发

| 场景 | 是否弹出引导 | |------|----------------| | 首次 smartcode-x（无 API Key） | ✅ 自动弹出 | | smartcode-x setup / smartcode-x init | ✅ 强制进入 | | 已配置 settings.json 或环境变量中有 Key | ❌ 直接进入 REPL | | --api-key 启动参数 | ❌ 跳过（使用参数中的 Key） | | --non-interactive、serve、管道/CI | ❌ 不弹出；缺 Key 则报错退出 | | 设 SMARTCODE_X_SKIP_SETUP=1 | ❌ 跳过引导 |

引导流程

1. 读取已有配置模板（若存在）：~/.smartcode-x/settings.json，或同目录下其他 settings*.json（如 settings333.json）、项目 .smartcode-x/settings.json、settings.example.json —— 默认模型名与网关地址从这里预填，不再写死
2. 选择 API 标准入口（二选一）：Anthropic 或 OpenAI
3. 输入模型名称（已预填，回车可保留）
4. 输入 API Base URL（已预填，官方 API 可留空）
5. 输入 API Key（掩码输入，不回显）
6. 确认保存 → 写入用户全局 settings.json → 自动继续启动

支持的标准入口

引导只提供两种通用协议形态；火山方舟、DeepSeek、Ollama 等请在引导完成后手动编辑 settings.json，见下方「配置总览」案例。

| 入口 | 协议 | 适用场景 | 向导会询问 | 写入的主要 env 字段 | |------|------|----------|------------|------------------------| | Anthropic | Messages API | 官方 Claude、Kimi 等 Anthropic 兼容网关 | 模型名、Base URL（可选）、API Key | ANTHROPIC_AUTH_TOKEN、ANTHROPIC_BASE_URL、SMARTCODE_X_API_PROVIDER=anthropic | | OpenAI | Chat Completions API | 官方 OpenAI、各类 OpenAI 兼容端点 | 模型名、Base URL（可选）、API Key | OPENAI_API_KEY、OPENAI_BASE_URL、SMARTCODE_X_API_PROVIDER=openai |

配置文件写到哪里

引导默认写入用户全局配置（所有项目共用），与 Claude Code 的 ~/.claude/settings.json 一致：

| 平台 | 路径 | |------|------| | macOS / Linux | ~/.smartcode-x/settings.json | | Windows | %USERPROFILE%\.smartcode-x\settings.json |

• 若文件已存在，会询问是否合并更新（新 env 覆盖同名字段，其余保留）
• Unix 系统上该文件会尝试设为 600 权限
• 勿将含密钥的 settings 提交到 git

引导生成的配置示例

Anthropic（兼容网关 / Kimi）

{
  "modelType": "anthropic",
  "model": "kimi-k2.6",
  "permissionMode": "auto",
  "maxTokens": 8192,
  "storageDir": ".smartcode-x/sessions",
  "session": { "autoSave": true, "maxMessages": 1000 },
  "permissions": { "defaultMode": "acceptEdits" },
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-api-key",
    "ANTHROPIC_BASE_URL": "https://your-gateway.example.com/",
    "ANTHROPIC_MODEL": "kimi-k2.6",
    "MODEL": "kimi-k2.6",
    "SMARTCODE_X_API_PROVIDER": "anthropic",
    "API_TIMEOUT_MS": "3000000"
  }
}

OpenAI

{
  "modelType": "openai",
  "model": "gpt-4o",
  "permissionMode": "auto",
  "maxTokens": 8192,
  "storageDir": ".smartcode-x/sessions",
  "session": { "autoSave": true, "maxMessages": 1000 },
  "permissions": { "defaultMode": "acceptEdits" },
  "env": {
    "OPENAI_API_KEY": "your-api-key",
    "OPENAI_BASE_URL": "https://api.openai.com/v1",
    "MODEL": "gpt-4o",
    "SMARTCODE_X_API_PROVIDER": "openai",
    "API_TIMEOUT_MS": "3000000"
  }
}

引导后如何改模型 / 换 Key

smartcode-x setup              # 重新走一遍向导

或在 REPL 内：

/model kimi-k2.6               # 临时切换模型（当前会话）

长期修改请编辑用户级 settings.json，或增加项目级 .smartcode-x/settings.json 覆盖默认模型（见下方「配置总览」）。

CI / 脚本中跳过引导

# 方式 1：环境变量
export ANTHROPIC_API_KEY="sk-..."
export MODEL="kimi-k2.6"
smartcode-x --non-interactive --input "hello"

# 方式 2：CLI 参数
smartcode-x --api-key "$KEY" --model kimi-k2.6 --non-interactive --input "hello"

# 方式 3：跳过引导检查（仍需自行提供 Key）
SMARTCODE_X_SKIP_SETUP=1 smartcode-x

Windows 使用说明

smartcode-x 基于 Node.js，配置加载使用 os.homedir() 与 path.join()，在 Windows 上与 macOS 同一套合并逻辑，settings.json 格式完全相同，无需单独 Windows 版配置。

路径对照

| 用途 | macOS / Linux | Windows | |------|---------------|---------| | 用户全局配置 | ~/.smartcode-x/settings.json | %USERPROFILE%\.smartcode-x\settings.json | | 项目配置 | <项目>/.smartcode-x/settings.json | <项目>\.smartcode-x\settings.json | | 本机覆盖 | <项目>/.smartcode-x/settings.local.json | <项目>\.smartcode-x\settings.local.json | | 会话存储 | <cwd>/.smartcode-x/sessions/ | <cwd>\.smartcode-x\sessions\ | | 遗留 TOML | ~/.sc-next/config.toml | %USERPROFILE%\.sc-next\config.toml |

PowerShell 中 ~ 有时可用，但推荐写 $env:USERPROFILE，避免不同终端行为不一致。

配置如何被读取（与 Mac 相同）

合并优先级（后者覆盖前者）：

内置默认值
  → %USERPROFILE%\.smartcode-x\settings.json     （用户全局）
  → .\smart-code.config.json                     （遗留项目 JSON）
  → .\.smartcode-x\settings.json                 （项目）
  → .\.smartcode-x\settings.local.json           （本机覆盖）
  → 遗留 TOML、SMARTCODE_X_* 环境变量、CLI 参数

示例：在 D:\research\smartcode-x 启动时：

1. 先读 C:\Users\<你>\.smartcode-x\settings.json（若存在，含引导写入的配置）
2. 再读 D:\research\smartcode-x\.smartcode-x\settings.json（若存在）
3. 再读 settings.local.json（若存在）

settings.json 里的 env 块会在加载配置时注入 process.env；不会覆盖 Shell 里已 export / $env: 的同名变量。

注意：CLI 不会读取 <cwd>/.env。仓库里的 .env 仅供本地脚本/示例使用，已加入 .gitignore，不会随 npm 包发布（package.json 的 files 仅含 dist 与 bin）。

Windows 功能支持情况

| 功能 | Windows | 说明 | |------|---------|------| | npm install -g | ✅ | npm 生成 smartcode-x.cmd | | 首次配置引导 setup | ✅ | PowerShell / CMD（需 TTY） | | REPL 对话、斜杠命令 | ✅ | Node readline | | 读/写/编辑文件、Glob、Grep | ✅ | Node fs，路径自动适配 | | settings.json 分层加载 | ✅ | 与 Mac 相同 | | API 调用（Kimi / 火山等） | ✅ | HTTPS | | Shell / Bash 工具 | ✅ | 使用 cmd.exe（%ComSpec%），支持 npm.cmd 等 | | Shell 沙箱 | ❌ | 仅 Linux/macOS；Windows 无沙箱直接执行 | | install.sh | ❌ | 请用 npm install -g |

Windows 常见问题

smartcode-x 不是内部或外部命令

全局 npm 目录未加入 PATH：

npm config get prefix
# 一般为 C:\Users\<你>\AppData\Roaming\npm

把该目录加入系统「环境变量 → Path」，重新打开 PowerShell。

--version 出现 ◇ injected env ...

dotenv v17 的提示，不是安装失败；0.1.2+ 已静默。旧版临时处理：

$env:DOTENV_CONFIG_QUIET = "true"

PowerShell 执行策略

一般不需要改 ExecutionPolicy。若公司策略拦截全局脚本：

npx smartcode-x

引导不出现

确认在交互式终端运行（非管道重定向）；已配 Key 时不会重复引导，用 smartcode-x setup 可强制重配。

只有项目级 settings.json、没有用户级配置

可以，在该项目目录下启动即可；换目录不会自动带上。多项目共用 API Key 时，用引导或 setup 写到 %USERPROFILE%\.smartcode-x\ 更方便。

配置总览

smartcode-x 的配置方式与 Claude Code 的 settings.json 分层 一致：用户全局 → 项目共享 → 本机覆盖 → 环境变量 → 命令行参数。后者覆盖前者。

配置文件在哪里

| 层级 | macOS / Linux | Windows | 用途 | 是否提交 git | |------|---------------|---------|------|----------------| | 用户 | ~/.smartcode-x/settings.json | %USERPROFILE%\.smartcode-x\settings.json | 全机默认：API、模型、权限模式 | 否（本机私密） | | 项目 | <项目>/.smartcode-x/settings.json | <项目>\.smartcode-x\settings.json | 团队共享：项目默认模型、权限、MCP 等 | 可提交 | | 本地 | <项目>/.smartcode-x/settings.local.json | <项目>\.smartcode-x\settings.local.json | 本机覆盖项目配置（个人密钥、调试） | 应加入 .gitignore | | 遗留 JSON | <项目>/smart-code.config.json | 同左 | 旧版项目配置，仍可读 | 视情况 | | 遗留 TOML | ~/.sc-next/config.toml、sc-next.config.toml | %USERPROFILE%\.sc-next\... | 旧版 TOML，仍可读 | 视情况 |

示例模板：仓库内 .smartcode-x/settings.example.json

不读取 .env：smartcode-x CLI 启动时不会加载项目根目录的 .env。npm 安装的用户也不会自带 .env；请用 smartcode-x setup 或编辑 settings.json。

合并优先级（从低到高）

数值越大，越晚合并，最终生效：

内置默认值
  ↓
~/.smartcode-x/settings.json          ← 用户全局
  ↓
./smart-code.config.json              ← 遗留项目 JSON
  ↓
./.smartcode-x/settings.json          ← 项目
  ↓
./.smartcode-x/settings.local.json    ← 项目本地（优先级高于项目 settings）
  ↓
遗留 TOML（~/.sc-next、./sc-next.config.toml）
  ↓
环境变量 SMARTCODE_X_* / SMART_CODE_* / SC_NEXT_*
  ↓
命令行参数（--model、--api-key、--cwd、--permission-mode 等）  ← 最高

记忆口诀：本地 settings.local > 项目 settings > 用户 ~/.smartcode-x > 默认值；临时用 CLI 参数最省事。

Settings 配置案例

下面按使用场景给出可直接复制改写的 settings.json。仓库模板： .smartcode-x/settings.example.json

案例 1：用户全局 settings.json（推荐放 API Key）

全机默认，所有项目共用；不要提交 git。也可用 smartcode-x setup 自动生成，无需手抄。

macOS / Linux 路径：~/.smartcode-x/settings.json
Windows 路径：%USERPROFILE%\.smartcode-x\settings.json

{
  "modelType": "anthropic",
  "model": "kimi-k2.6",
  "permissionMode": "auto",
  "maxTokens": 8192,
  "storageDir": ".smartcode-x/sessions",
  "session": {
    "autoSave": true,
    "maxMessages": 1000
  },
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-api-key",
    "ANTHROPIC_BASE_URL": "https://new-api.jointpilot.com/",
    "ANTHROPIC_MODEL": "kimi-k2.6",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "kimi-k2.6",
    "MODEL": "kimi-k2.6",
    "SMARTCODE_X_API_PROVIDER": "anthropic",
    "API_TIMEOUT_MS": "3000000"
  },
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

一键初始化：

# macOS / Linux
mkdir -p ~/.smartcode-x
cp path/to/smartcode-x/.smartcode-x/settings.example.json ~/.smartcode-x/settings.json
# 编辑 env 里的密钥与 BASE_URL

# Windows PowerShell
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.smartcode-x"
Copy-Item path\to\smartcode-x\.smartcode-x\settings.example.json "$env:USERPROFILE\.smartcode-x\settings.json"
notepad "$env:USERPROFILE\.smartcode-x\settings.json"

案例 2：项目级 .smartcode-x/settings.json（团队共享，可提交）

只约定项目默认行为，不含个人密钥；API Key 仍放用户级或 settings.local.json。

{
  "model": "glm-4.7",
  "permissionMode": "plan",
  "maxTokens": 8192,
  "storageDir": ".smartcode-x/sessions",
  "session": {
    "autoSave": true,
    "maxMessages": 500
  },
  "permissions": {
    "defaultMode": "plan"
  }
}

进入该项目目录启动 smartcode-x 后，会在此配置之上再叠加上面的用户全局配置；同名字段以项目为准（例如项目的 permissionMode: plan 覆盖用户的 auto）。

案例 3：本机覆盖 .smartcode-x/settings.local.json（个人密钥 / 调试）

优先级高于项目 settings.json，适合「项目配置进 git，但密钥只在本机」。

{
  "permissionMode": "bypass",
  "env": {
    "VOLCES_API_KEY": "your-volces-key-only-on-this-machine"
  }
}

.gitignore 建议加入：

.smartcode-x/settings.local.json

案例 4：三层叠加时谁生效（举例）

假设同时存在：

| 文件 | model | permissionMode | |------|---------|------------------| | ~/.smartcode-x/settings.json | kimi-k2.6 | auto | | ./.smartcode-x/settings.json | glm-4.7 | plan | | ./.smartcode-x/settings.local.json | （未写） | bypass |

最终：model = glm-4.7（项目覆盖用户），permissionMode = bypass（本地覆盖项目）。

若再执行 smartcode-x --model deepseek-chat，则 model = deepseek-chat（CLI 最高）。

案例 5：火山方舟 GLM

~/.smartcode-x/settings.json：

{
  "model": "glm-4.7",
  "permissionMode": "auto",
  "env": {
    "VOLCES_API_KEY": "your-volces-api-key",
    "SMARTCODE_X_API_PROVIDER": "volces"
  }
}

或仅在 settings.json 的 env 块中配置（推荐）：

{
  "model": "glm-4.7",
  "permissionMode": "auto",
  "env": {
    "VOLCES_API_KEY": "your-volces-api-key",
    "SMARTCODE_X_API_PROVIDER": "volces"
  }
}

案例 6：DeepSeek（Anthropic 兼容端点）

{
  "model": "deepseek-chat",
  "permissionMode": "auto",
  "env": {
    "DEEPSEEK_API_KEY": "sk-...",
    "ANTHROPIC_API_KEY": "sk-...",
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "SMARTCODE_X_API_PROVIDER": "anthropic",
    "MODEL": "deepseek-chat"
  }
}

案例 7：本地 Ollama

{
  "model": "llama3.2",
  "permissionMode": "bypass",
  "env": {
    "SMARTCODE_X_API_PROVIDER": "ollama",
    "OLLAMA_HOST": "http://127.0.0.1:11434",
    "OLLAMA_API_KEY": "ollama"
  }
}

案例 8：非交互脚本 / CI（权限全开）

不依赖 settings 文件，启动参数即可：

smartcode-x --non-interactive \
  --permission-mode bypass \
  --cwd ./my-app \
  --input "运行 pnpm test 并只汇报失败用例"

或在用户 settings 里长期开启：

{
  "permissionMode": "bypass",
  "permissions": {
    "defaultMode": "bypassPermissions"
  }
}

案例 9：远程 serve 模式

用户级或 shell 环境：

{
  "env": {
    "SMARTCODE_X_SERVER_TOKEN": "your-random-token",
    "SMARTCODE_X_SERVER_SESSION_BACKEND": "file"
  }
}

smartcode-x serve --port 8787 --host 127.0.0.1

与本仓库当前配置对照

本仓库内有一份实际在用的配置：.smartcode-x/settings.json（已在 .gitignore，勿提交密钥）。与 README 案例 1 对比如下：

| 项 | 本仓库 .smartcode-x/settings.json | README 案例 1（用户全局） | 说明 | |----|-------------------------------------|---------------------------|------| | 文件位置 | smart-code/.smartcode-x/（项目级） | ~/.smartcode-x/（用户级） | 在 smart-code 目录启动时生效；换别的项目目录不会自动带上 | | permissionMode | bypass | auto | 你这边工具不弹确认，适合本地开发；案例 1 更保守 | | permissions.defaultMode | bypassPermissions | acceptEdits | 与上面一致，最终都映射为 bypass | | env 密钥字段 | 同时写了 ANTHROPIC_AUTH_TOKEN 与 ANTHROPIC_API_KEY | 通常只写其一 | 重复但无害；加载时任一即可 | | env 模型别名 | 写了 HAIKU/SONNET/OPUS/SMALL_FAST/SUBAGENT 等 | 案例 1 只列 SONNET | 兼容 Claude Code 子模型变量；网关统一走 kimi-k2.6 时可保留 | | API_TIMEOUT_MS | 3000000 | 案例 1 有 | 请求超时（毫秒），长任务用 | | 其余 | model、maxTokens、session、storageDir 等与案例 1 一致 | — | 无冲突 |

结论：字段名与 README 描述无出入；主要区别是 权限更开放（bypass）、配置放在项目目录而非用户主目录、env 里多写了若干 Claude Code 兼容变量。若希望所有项目共用同一套 API，建议把 env 密钥迁到 ~/.smartcode-x/settings.json，项目里只留 model / permissionMode 等非敏感项。

字段说明（settings.json 顶层）

| 字段 | 类型 | 作用 | 备注 | |------|------|------|------| | model | string | 默认对话模型名 | 启动横幅、/model 显示；优先级高于 env.MODEL | | modelType | string | API 提供商类型 | 映射为内部 provider.default，如 anthropic、volces | | provider | string | 同 modelType | 二选一即可 | | defaultModel | string | 同 model | Claude Code 别名 | | permissionMode | string | 工具权限模式 | default / auto / plan / bypass | | permission_mode | string | 同 permissionMode | 蛇形写法 | | maxTokens | number | 单次 API 回复 token 上限 | 映射为 max_tokens，默认 4096 | | max_tokens | number | 同 maxTokens | 蛇形写法 | | storageDir | string | 会话持久化目录 | 相对当前 cwd，默认 .smartcode-x/sessions | | storage_dir | string | 同 storageDir | 蛇形写法 | | apiKey | string | API 密钥（顶层） | 也可放在 env 块；映射为 provider.api_key | | api_key | string | 同 apiKey | 蛇形写法 | | baseURL / base_url / baseUrl | string | API 基址 | 也可放在 env.ANTHROPIC_BASE_URL 等 | | session | object | 会话行为 | 见下表 | | permissions | object | Claude Code 风格权限 | 见下表 | | env | object | 注入 process.env | 见下表；不覆盖 shell 已有变量 | | mcpServers / mcp_servers | object | MCP 服务器定义 | 与 /mcp registry 配合 | | hooks | object | 钩子命令 | pre_tool_use / post_tool_use 等 |

session 对象

| 字段 | 类型 | 作用 | 默认 | |------|------|------|------| | autoSave / auto_save | boolean | 退出 REPL（/exit、/clear）时是否自动写入项目记忆 | true | | maxMessages / max_messages | number | 单会话消息条数上限（触发压缩前） | 1000 |

permissions 对象

| 字段 | 类型 | 作用 | 映射结果 | |------|------|------|----------| | defaultMode | string | Claude Code 权限别名 | 含 bypass → bypass；含 accept → auto；plan → plan；否则 default |

与顶层 permissionMode 重复配置时：后加载的层覆盖先加载的；同一文件内若两者都有，loader 会读 permissionMode 或 permissions.defaultMode（见 mapSettingsJsonToLoaderConfig）。

env 块常用变量

写入 process.env，并参与推导 provider / model（若顶层未写）。

| 变量 | 作用 | |------|------| | SMARTCODE_X_API_PROVIDER | 强制提供商：anthropic、volces、ollama 等 | | ANTHROPIC_API_KEY | Anthropic 或兼容网关 API Key | | ANTHROPIC_AUTH_TOKEN | 与 ANTHROPIC_API_KEY 等价（Claude Code 习惯） | | ANTHROPIC_BASE_URL | 兼容网关地址（如 Kimi、DeepSeek 的 Anthropic 端点） | | ANTHROPIC_MODEL | 未写顶层 model 时作为模型名 | | ANTHROPIC_DEFAULT_SONNET_MODEL | 同上后备（Sonnet 别名） | | ANTHROPIC_DEFAULT_HAIKU_MODEL | 子任务/快速模型别名（部分 SDK 会读） | | ANTHROPIC_DEFAULT_OPUS_MODEL | Opus 别名 | | ANTHROPIC_SMALL_FAST_MODEL | 小模型别名 | | CLAUDE_CODE_SUBAGENT_MODEL | 子智能体默认模型 | | MODEL | 通用模型名；顶层无 model 时生效 | | API_TIMEOUT_MS | HTTP 请求超时（毫秒） | | VOLCES_API_KEY | 火山方舟密钥 | | DEEPSEEK_API_KEY | DeepSeek 密钥 | | OPENAI_API_KEY | OpenAI 密钥 | | API_BASE_URL | 通用 API 基址后备 | | OLLAMA_HOST / OLLAMA_API_KEY | 本地 Ollama |

顶层 SMARTCODE_X_* 环境变量（不进 settings 文件也可）

| 变量 | 作用 | |------|------| | SMARTCODE_X_MODEL | 覆盖模型 | | SMARTCODE_X_API_PROVIDER | 覆盖提供商 | | SMARTCODE_X_SERVER_TOKEN | serve HTTP/WS 鉴权 | | SMARTCODE_X_SERVER_SESSION_BACKEND | 会话存储：memory / file / redis | | SMARTCODE_X_NO_LOGO | 1 关闭启动 Logo |

仍兼容 SMART_CODE_*、SC_NEXT_* 前缀。

permissionMode 与 permissions.defaultMode 二选一即可；带 bypass 的会映射为 bypass（工具无需确认，适合脚本）。

配置来源说明（CLI 不读 .env）

| 来源 | 是否默认加载 | 说明 | |------|----------------|------| | ~/.smartcode-x/settings.json | ✅ | 用户全局，推荐（smartcode-x setup 写入） | | .smartcode-x/settings.json / settings.local.json | ✅ | 项目 / 本机覆盖 | | settings.json 里的 env 块 | ✅ | 加载时注入 process.env（不覆盖 Shell 已有变量） | | Shell export / $env:XXX | ✅ | 需自行在终端设置 | | CLI 参数 --model、--api-key 等 | ✅ | 优先级最高 | | 项目根目录 .env | ❌ | CLI 不读取；npm 包也不包含此文件 | | 仓库内 smart-code.config.json | ✅（遗留） | 仅部分字段，不含 API Key |

本地开发与 npm install -g 行为一致：请把 API Key、模型、Base URL 写在 settings.json（或走首次引导），不要依赖仓库里的 .env。

env 块与 Shell 环境变量的关系

| 来源 | 行为 | |------|------| | settings.json 里的 env | 加载配置时注入；仅当 process.env 中尚无该 key 时写入 | | Shell 已 export / $env: 的变量 | 优先级高于 settings 的 env 块 |

推荐做法：

• API Key 放在 ~/.smartcode-x/settings.json 的 env（或 settings.local.json），不要提交 git
• 项目差异（如团队统一模型）放在 .smartcode-x/settings.json 并提交
• 个人覆盖 放在 .smartcode-x/settings.local.json

环境变量（结构化覆盖）

除 settings.json 的 env 外，可直接设置（优先级高于 settings 文件，低于 CLI 参数）：

| 变量 | 作用 | |------|------| | SMARTCODE_X_MODEL | 模型名 | | SMARTCODE_X_API_PROVIDER | 提供商（anthropic、ollama 等） | | SMARTCODE_X_SERVER_TOKEN | serve 模式鉴权 | | SMARTCODE_X_NO_LOGO | 1 关闭启动 Logo |

仍兼容前缀：SMART_CODE_*、SC_NEXT_*。

常见第三方 Key（也可写在 env 块）：ANTHROPIC_API_KEY、VOLCES_API_KEY、DEEPSEEK_API_KEY、OPENAI_API_KEY、OLLAMA_API_KEY 等。

模型名最终从哪来

REPL / CLI 解析顺序：

--model 参数  →  settings 顶层 model  →  settings.env 里的 MODEL / ANTHROPIC_MODEL  →  默认 claude-sonnet-4-6

因此：若 settings.json 里写了 "model": "kimi-k2.6" 或在 env 里写了 "MODEL": "kimi-k2.6"，启动横幅会显示该模型，除非传 --model。

工作目录 cwd

• 默认：启动 smartcode-x 时所在的目录
• 工具读写文件、加载 .smartcode-x/settings.json、MCP registry、项目记忆等，都相对该 cwd
• 切换：REPL 内 /cwd D:\path\to\project 或 /cwd /path/to/project，或启动时 smartcode-x --cwd <路径>

给某个仓库干活时，先 cd 到该仓库再启动，或用 --cwd，避免读到错误的项目配置。

命令行参数（最高优先级）

smartcode-x \
  --cwd ./my-app \
  --model glm-4.7 \
  --api-key "$VOLCES_API_KEY" \
  --base-url https://ark.cn-beijing.volces.com/v1 \
  --permission-mode auto \
  --session <session-id> \
  --verbose

# 非交互单次提问（脚本/CI）
smartcode-x --non-interactive --permission-mode bypass --input "运行 pnpm test"

与 Claude Code 的对应

| Claude Code | smartcode-x | |-------------|-------------| | claude | smartcode-x（别名 smart-code） | | ~/.claude/settings.json | ~/.smartcode-x/settings.json | | .claude/settings.json | .smartcode-x/settings.json | | .claude/settings.local.json | .smartcode-x/settings.local.json |

详细字段说明：docs/configuration.md

功能概览

• 工具：读/写/编辑文件、Glob、Grep、Bash、Todo、Web 搜索/抓取、MCP 等
• 多模型：Anthropic、OpenAI、火山方舟、DeepSeek、Gemini、智谱、xAI、Ollama 等
• 权限：default / auto / plan / bypass；REPL /permissions 管理规则
• 会话：/session、/clear；可选持久化到 storageDir
• 进行中状态：REPL 执行任务时显示动态指示行（读秒、token 估算、thought for、工具子任务 ■/□），对齐 Claude Code
• MCP：/mcp registry …、smartcode-x mcp add …
• Skills：/skills list|enable（SKILL.md 注入，非斜杠插件）
• 远程：smartcode-x serve 提供 HTTP/WebSocket 控制面

模型与 API 示例

| 提供商 | 模型示例 | 配置要点 | |--------|----------|----------| | 火山方舟 | glm-4.7 | VOLCES_API_KEY，可选 baseURL | | Anthropic / 兼容网关 | claude-sonnet-4-6、kimi-k2.6 | ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL | | DeepSeek | deepseek-chat | DEEPSEEK_API_KEY | | OpenAI | gpt-4o | OPENAI_API_KEY | | Ollama 本地 | llama3.2 等 | SMARTCODE_X_API_PROVIDER=ollama，OLLAMA_HOST |

常用 REPL 命令

| 命令 | 说明 | |------|------| | / + Enter | 命令选择菜单 | | /help | 全部斜杠命令 | | /model [name] | 查看或切换模型 | | /mode [default\|auto\|plan\|bypass] | 权限模式 | | /cwd [path] | 工作目录 | | /clear | 清空当前会话 | | /session new | 新会话 | | /mcp registry list | MCP 服务器列表 | | /permissions list | 权限规则 |

程序化调用（SDK）

import { createAgent } from 'smartcode-x'

const agent = createAgent({
  model: 'glm-4.7',
  apiKey: process.env.VOLCES_API_KEY,
  baseURL: 'https://ark.cn-beijing.volces.com/v1',
})

for await (const event of agent.query('Hello')) {
  if (event.type === 'text') console.log(event.text)
}

示例代码：examples/

文档索引

| 文档 | 内容 | |------|------| | 本文 README | 安装、首次模型引导、Windows 适配、配置案例与字段说明 | | docs/configuration.md | 配置详解 | | docs/install.md | 安装与发布 | | docs/publish-npm.md | 维护者发 npm | | docs/chrome-computer-mcp.md | Chrome / Computer Use MCP | | docs/api-reference.md | API 参考 |

License

MIT