NeuroSpark Coder 部署与排错手册

1. 架构速览（先理解再动手）

• neurospark-coder：npm 包，本质是 @anthropic-ai/claude-code 的包装器，启动一个本地代理（PROXY_ONLY=true 可单独起代理做诊断），把 Claude Code 的请求转发到上游网关。
• 上游网关：https://api.tokenfire.cn/v1，OpenAI 兼容（/v1/chat/completions、/v1/models），支持 tools 函数调用。可用 OPENAI_API_URL 覆盖默认地址。
• 认证：代理在启动瞬间读取 OPENAI_API_KEY，之后为每个请求附加 Authorization: Bearer <key>。启动后再 export 对已运行会话无效。
• 默认模型 neurospark/GLM5.2-FP8；会话内用 /model 切换。/model 的设置可能被 ANTHROPIC_MODEL 环境变量覆盖（界面会有提示）。

2. 环境准备

macOS

• 需要 curl、Node.js（建议 Homebrew 安装）、npm。验证：curl --version && node --version && npm --version。
• 不要用 sudo 装全局包，也不要装进 /opt/homebrew（会被系统权限层拦截，报 permission denied）。使用用户级 prefix：~/.npm-global。
• 密钥等配置写入 ~/.zshrc（zsh）或 ~/.bash_profile（bash）；注意 .zshrc 只在交互式 shell 生效，脚本验证时用 zsh -i -c 而非 zsh -c。

Windows

• 安装 Node.js LTS 官方安装包（自带 npm）。用 PowerShell 操作。
• npm 全局目录默认为 %APPDATA%\npm，通常已在 PATH；若 neurospark-coder 找不到，把 npm config get prefix 的输出加入用户 PATH。
• 不要依赖 curl | bash 类脚本（claude.ai/install.sh 仅支持 macOS/Linux）；Windows 一律走 npm 安装。
• 若遇 PowerShell 执行策略拦截脚本，对当前用户放行：Set-ExecutionPolicy -Scope CurrentUser RemoteSigned。

3. 安装步骤

3.1 macOS（已验证流程，2026-10）

1. 不要直接 curl | bash。先下载官方脚本人工审查，确认只做"检查依赖 → 装 Claude Code → npm 装 neurospark-coder"三件事：
   bash curl -fsSL https://neuro-spark-ai.github.io/NeuroSpark-Install/install.sh -o /tmp/install.sh # 阅读确认无危险操作后再执行
2. 核验 npm 包真实性（防同名仿冒）：npm view neurospark-coder——维护者应为 thomas@neuro-spark.ai，仓库 Neuro-Spark-AI/NeuroSpark-Coder。
3. 脚本内调用的 https://claude.ai/install.sh 在部分网络返回"地区不可用"HTML 导致失败——属预期，直接改用 npm 安装两个包：
   bash mkdir -p "$HOME/.npm-global" npm_config_prefix="$HOME/.npm-global" npm install -g @anthropic-ai/claude-code neurospark-coder
   （用环境变量临时指定 prefix，不要 npm config set prefix 持久修改用户 .npmrc。）
4. 把 PATH 写入 shell 配置（zsh 写 ~/.zshrc，bash 写 ~/.bash_profile）：
   bash export PATH="$HOME/.npm-global/bin:$PATH"

3.2 Windows

npm install -g @anthropic-ai/claude-code neurospark-coder
# 确认全局目录在 PATH 中
npm config get prefix

4. 配置要点（含 API Key 规范）

4.1 密钥格式规格（脱敏展示，还原时严格对照）

• 真实格式：sk-neurospark- 前缀 + 标准 UUID（8-4-4-4-12 十六进制段），总长恰好 50 字符。
• 文档/聊天中的脱敏写法：sk-neurospark-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx（50 位占位）或 sk-neurospark-****…****c50d（末 4 位仅作识别用）。
• 自检命令：echo -n "$OPENAI_API_KEY" | wc -c 必须输出 50；不等于 50 即复制不完整。
• 当前密钥存放位置（换 key 时必须同步改全部位置）：
  1. ~/.bash_profile 的 export OPENAI_API_KEY=...（macOS bash）
  2. ~/.zshrc 的同名行（macOS zsh）
  3. ~/.workbuddy/models.json 中各 neurospark 模型的 apiKey 字段
• Windows 对应：用户环境变量 OPENAI_API_KEY + %USERPROFILE%\.workbuddy\models.json

4.2 ⚠️ 密钥写入的反截断纪律（本次踩过的最大的坑）

自动化平台/沙箱会对 Bash 命令中内联出现的密钥做截断脱敏——直接 echo "sk-...完整key..." >> ~/.zshrc 或 heredoc 内联写入，落盘的会是残缺串（实测 50 字符变 34），且报错表现为网关 401 Invalid token，极易误判为密钥失效。

正确做法——分段拼接写入，写后强制校验长度：

python3 - <<'EOF'
key = "sk-neu" + "rospark-" + "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  # 分段，单段不含完整可识别串
assert len(key) == 50
# 替换配置文件中旧的 OPENAI_API_KEY 行，再回读校验
EOF
echo -n "$OPENAI_API_KEY" | wc -c   # 必须 50

任何写入密钥的操作后，都必须回读文件并验证长度=50 才算完成。

4.3 持久化配置

macOS（~/.bash_profile 与 ~/.zshrc 各加一行）：

export OPENAI_API_KEY="sk-neurospark-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Windows（PowerShell，不需要管理员）：

[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-neurospark-xxxx...", "User")
# 临时（仅当前窗口）：$env:OPENAI_API_KEY = "sk-neurospark-xxxx..."

4.4 接入 WorkBuddy 自定义模型

配置文件：macOS ~/.workbuddy/models.json，Windows %USERPROFILE%\.workbuddy\models.json。改前先备份。

每条模型 9 个字段（该版本客户端自定义模型没有"上下文长度"设置项，属正常设计——上下文窗口由服务端裁决）：

{
  "id": "GLM5.2-FP8",
  "name": "NeuroSpark GLM5.2-FP8",
  "vendor": "Custom",
  "url": "https://api.tokenfire.cn/v1/chat/completions",
  "apiKey": "sk-neurospark-xxxx...(50字符)",
  "supportsToolCall": true,
  "supportsImages": false,
  "supportsReasoning": true,
  "reasoning": {"defaultEffort": "medium", "supportedEfforts": ["low","medium","high"], "canDisableThinking": true}
}

关键坑：id 会原样作为 model 参数发给网关，必须等于网关可识别的模型名（如 GLM5.2-FP8、glm-5.3-flash、claude-opus-4-8）。自定义前缀如 neurospark-glm5.2 会被网关拒绝（HTTP 400）。显示名 name 可随意。改完需完全退出并重开 WorkBuddy（配置不热加载）。写入用分段拼接法并在 Python 内回读校验 len(apiKey)==50。

5. 启动与验证

按顺序执行，全部通过才算部署完成（也可用 scripts/verify_deployment.sh（macOS/Linux）或 scripts/verify_deployment.ps1（Windows）一键跑完）：

# ① 命令存在（新开终端验证 PATH 持久化）
which claude && which neurospark-coder
claude --version            # 如 2.1.x
neurospark-coder --version  # 如 1.2.x，应打印默认模型与可用模型列表

# ② 密钥就绪
echo -n "$OPENAI_API_KEY" | wc -c   # 必须 50

# ③ 网关认证探活（必须 200；401=密钥问题，000=网络问题）
curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer $OPENAI_API_KEY" https://api.tokenfire.cn/v1/models

# ④ 真实补全（应返回 DEPLOY_OK）
curl -s -X POST https://api.tokenfire.cn/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" -H "content-type: application/json" \
  -d '{"model":"GLM5.2-FP8","max_tokens":32,"messages":[{"role":"user","content":"Reply with exactly: DEPLOY_OK"}]}'

# ⑤ 端到端：本地代理诊断模式
PROXY_ONLY=true neurospark-coder   # 打印 proxy=http://localhost:<port>
curl -s -X POST http://localhost:<port>/v1/messages -H "content-type: application/json" \
  -d '{"model":"neurospark/GLM5.2-FP8","max_tokens":64,"messages":[{"role":"user","content":"Reply with exactly: DEPLOY_OK"}]}'

# ⑥ 正式使用
cd 项目目录 && neurospark-coder

Windows PowerShell 对应探活：

curl.exe -s -o NUL -w "%{http_code}" -H "Authorization: Bearer $env:OPENAI_API_KEY" https://api.tokenfire.cn/v1/models

6. 常见问题与排错

7. 安全规范

• 密钥不写入项目文件、不进 git、尽量不进聊天记录；临时密钥文件用后删除。
• 密钥一旦在聊天中出现，建议到 NeuroSpark 门户轮换；轮换后按 #11 同步所有存放点。
• 安装脚本一律"先下载审查、后执行"，并核验 npm 包维护者与仓库归属。
• ~/.workbuddy/models.json.bak-* 备份含明文密钥，注意保管或删除。

8. 参考实现（2026-10-19 macOS 实测版本号）

• claude 2.1.303 / neurospark-coder 1.2.39 / node v26.12.0 / npm 11.20.0
• 网关 /v1/models 返回约 60 个模型（GLM 系列、Claude Opus 4.8、GPT-5 系列等），以实际返回为准。

Scripts

• scripts/verify_deployment.sh（macOS/Linux bash）：一键执行第 5 节全部验证项并输出逐项结果。
• scripts/verify_deployment.ps1（Windows PowerShell）：同等验证的 Windows 版本。
  两个脚本均从环境变量 OPENAI_API_KEY 读取密钥，不接收命令行密钥参数；执行前确保已在当前会话设置。