Strata Coder

An MCP implementation worker for local OpenAI-compatible coding models.

主模型负责规划、选择是否委派、审查和集成补丁；Strata Coder 让本地模型在项目副本中完成具体实现、运行检查并返回结果。支持接入具备 MCP stdio 客户端能力的编程工具和自建 Harness。

本项目独立维护，不隶属于同名推理服务；只依赖兼容的 /chat/completions 接口和工具调用能力。

给 AI 助手：安装与集成

用户要求你安装本项目时，请先阅读 AI 安装指南，再执行安装。不要只给用户一段配置就声称完成。

1. 识别用户的操作系统、Node/Git、目标客户端及其版本，读取现有配置；缺少模型地址、模型 ID、项目目录或检查命令时先收集信息，不照搬占位符。

2. 查询 npm 上实际存在的版本并固定版本；尚未发布时使用本仓库源码。模型服务器地址是模型 API，不是 MCP URL。

3. 配置文件保存在安装目录之外；配置真实检查，密钥使用环境变量。工作目录由宿主在运行时提供，不需要写入配置。

4. 将 MCP stdio 启动命令合并到目标客户端配置：Codex 使用 mcp_servers；OpenCode 2.x 使用 mcp.servers；旧版格式另行识别。备份并保留已有模型、provider、MCP 和项目规则。

5. 合并 委派规则，保留用户按任务选择主模型/本地模型的能力；发现已有相同服务时更新已有项，避免重复注册。

6. 验证配置可解析、MCP 握手成功、五个工具可见，调用 get_capabilities 确认实际加载的配置。真实推理只在用户授权范围内的临时项目验证。

7. 汇报安装版本、修改过的配置文件、已验证项、待完成项与卸载方法；登录、权限或重启被阻塞时明确说明，不宣称成功。

可以把下面的话交给自己的 AI 助手：

请阅读 https://github.com/huyinghuan/strata-coder 的 README、docs/AI-INSTALL.md 和 prompts/planner.md，
将 Strata Coder 安装并集成到我的编程客户端。先识别客户端版本并保留现有配置，
确认模型地址、模型 ID、项目范围和检查命令，再验证 MCP 工具可用。

Related MCP server: local-mcp

安装

需要 Node.js 22+、Git，以及支持 tools / tool_calls 的模型端点。开发及真实推理测试在 macOS 上完成；CI 配置了 macOS/Linux 与 Node 22/24 的测试矩阵，Windows 尚未验证。

在项目目录运行一次初始化，即可完成模型连接、项目检查、协作规则与 OpenCode 接入：

npx -y strata-coder@0.2.0 init

init 会在项目内写入 .strata-coder/config.json（模型连接与检查；工作目录由宿主在运行时提供，不写入配置）、把 .strata-coder/ 加入项目 .gitignore、生成 .opencode/strata-coder.md 协作规则并在 AGENTS.md 插入受管引用；检测到 OpenCode 2.x 时写入项目级 MCP 配置（保留注释、主模型与其他 MCP），最后用 MCP 握手自检生成的配置。非交互环境必须提供 --baseUrl 和 --model，可用 --check-command 指定检查命令；init --help 查看全部参数。重复运行保留已有预算、状态路径和检查；显式 --check-command 优先于自动检测，并保留其他检查。协作规则只维护受管内容，不覆盖用户修改。通过 npx 初始化时，会将当次包保存到被忽略的 .strata-coder/runtime/ 并安装运行依赖，服务及检查均引用该稳定副本；清理 npx 缓存不影响使用，此步骤需要可用的 npm registry/cache。

OpenCode 的全局 MCP 注册一次即可复用到所有项目：新项目打开 OpenCode 后，服务会自动获得该项目目录，无需再填工作目录白名单，也无需为继承目录而运行 init。init 只用于写入该项目的模型/检查配置；自动识别测试命令是独立功能，尚未实现，未配置检查的项目仍无法提交编码任务。

也可以手动启动已安装的版本：

npx -y strata-coder@0.2.0 --config /absolute/path/strata-coder.config.json
npm install -g strata-coder@0.2.0
strata-coder --config /absolute/path/strata-coder.config.json

服务通过 stdio 通信，由客户端管理进程；直接在终端启动会等待 MCP 消息。strata-coder 只是 MCP 启动入口，不提供独立的编码任务 CLI。

不传 --config 时，先找当前目录的 .strata-coder/config.json，再找入口旁的 strata-coder.config.json / local-coder.config.json；都没有时明确报错并提示先运行 strata-coder init。示例配置不会被自动当作可运行配置。--baseUrl、--model、--apiKeyEnv 在读取文件后覆盖同名配置字段：

strata-coder --baseUrl http://127.0.0.1:8080/v1
strata-coder --baseUrl http://127.0.0.1:8080/v1 --model other-model --apiKeyEnv OTHER_KEY

源码安装（也适用于尚未发布 npm 的版本）：

git clone https://github.com/huyinghuan/strata-coder.git
cd strata-coder
npm ci --ignore-scripts
cp strata-coder.config.example.json strata-coder.config.json
# 编辑配置，填写实际模型、项目路径和检查命令
node src/mcp.js --config "$PWD/strata-coder.config.json"

在目标项目中也可以直接用源码运行初始化：node /absolute/path/strata-coder/src/mcp.js init。

配置

strata-coder init 生成项目级配置 <project>/.strata-coder/config.json（模型连接、检查与预算）；它不包含工作目录白名单。状态在 <project>/.strata-coder/state，整个 .strata-coder/ 由 init 加入项目 .gitignore。也可以继续使用全局或自定义配置文件；示例配置仅是模板，不会被自动加载。

手动配置文件存放在 npm 安装目录之外，升级包不会覆盖它。所有相对路径以配置文件所在目录为基准；推荐绝对路径。

{
  "baseUrl": "http://127.0.0.1:8080/v1",
  "model": "your-model-id",
  "stateDir": "/absolute/path/to/strata-coder-state",
  "checks": {
    "unit": {
      "command": ["node", "--test", "test/unit.test.js"],
      "timeoutSeconds": 60
    }
  },
  "defaultChecks": ["unit"],
  "requireChecks": true,
  "reasoningEffort": "low",
  "maxOutputTokens": 13000,
  "requestTimeoutSeconds": 360,
  "maxRepairAttempts": 2,
  "temperature": 0
}

将示例检查替换为项目真实命令。命令在工作副本执行，不经过 shell。node_modules、虚拟环境和 Git 忽略文件不复制；strata-coder init 为 npm 项目生成的 strata_unit 检查使用随包分发的 src/npm-check.js：副本必须存在锁文件；首次检查、安装失败后重试或依赖清单变化时执行 npm ci --ignore-scripts，仅复用与当前清单匹配的成功安装，随后运行测试命令；缺少锁文件或安装失败会给出准确提示，不修改原项目。默认未选择检查就拒绝任务；仅在需要未验证草稿时显式设置 requireChecks: false。

• reasoningEffort 支持 low、medium、high、none 或 null；null 省略该参数，适用于不支持它的服务。具体模型是否支持其他档位由服务决定。

• maxContextChars 默认 120,000，限制消息历史的 JSON 字符数，不是 tokens；不代表模型上下文容量，也不是精确 tokenizer 计数。扩大预算前需为工具定义、模板和输出预留空间。

• maxOutputTokens 是每次响应上限，maxTurns 默认 20，maxTaskSeconds 默认 900 秒。请按模型实际限制配置。

• maxRepairAttempts 从检查失败后的首次实际修改开始计数；耗尽时交回主模型。

• 多个客户端共用同一绝对 stateDir 可共享任务记录、提交去重和项目占用状态。

• 同一 OS 用户、相同规范化模型 URL 的请求通过共享端点锁串行执行。不同 URL 别名、不同机器或外部调用不受该锁控制。

• 模型需要鉴权时，在 MCP 进程环境中设置 LOCAL_CODER_API_KEY，或用 apiKeyEnv 指定另一个变量名。示例配置把 apiKeyEnv 置空，默认不发送 Authorization 头。

--config 优先于 STRATA_CODER_CONFIG，后者优先于兼容保留的 LOCAL_CODER_CONFIG；都没有时先查找当前目录的 .strata-coder/config.json，再按 strata-coder.config.json → local-coder.config.json 的顺序在启动入口旁查找，最后明确报错并提示运行 strata-coder init；示例配置不会被自动加载。--baseUrl、--model、--apiKeyEnv 在读取文件后、校验前覆盖对应字段，未提供的字段保持文件值。旧配置文件名、.local-coder-state 状态目录和锁目录仍兼容，无需迁移已有任务。

工作目录（运行时）

服务启动时由宿主提供目录范围，配置文件中没有工作目录白名单：

• 客户端支持 MCP roots 时，优先使用 roots/list 返回的本机目录；file:// URI（含百分号编码、中文、空格）会规范化为真实路径，非本地 URI、文件和不存在的路径会被拒绝。

• 客户端不支持 roots 或明确返回空 roots 时，使用宿主启动 MCP 进程时的工作目录；npm 包安装目录、npx 缓存、状态目录、配置文件目录和用户主目录不会被当作项目目录。

• roots 请求失败时明确报错，不会退回可能更宽的范围。

• submit_task 的 workspace 可省略：只有一个根目录时自动使用；多个根目录时返回候选并要求显式选择；显式传入只能选择某个根目录或其子项目（子目录），范围外的目录会被拒绝，不能借此扩大宿主提供的范围。

• get_capabilities 的 workspace 返回 roots、source（mcp_roots 或 cwd）、default 与解析错误；多根目录时 default 为 null。

• 已提交任务固定使用提交时的绝对目录；roots 更新只影响后续提交，旧任务超出新范围后查询、读取工件和取消会被拒绝，任务本身不受影响。

• 同一宿主同时打开多个项目时，每个连接（每个 MCP 进程）使用各自的目录范围，不共享可变状态。

目录范围只约束本地 Worker 的读写和检查位置，不是操作系统沙箱；检查命令仍以宿主用户权限运行。

接入 MCP 客户端

strata-coder init 已自动完成 OpenCode 2.x 的项目级接入，并向其他客户端打印通用 stdio 配置。手动接入时，以下适用于使用 mcpServers 结构的客户端，其他客户端将同一命令映射到其 MCP stdio 设置中：

{
  "mcpServers": {
    "strata_coder": {
      "command": "npx",
      "args": ["-y", "strata-coder@0.2.0", "--config", "/absolute/path/strata-coder.config.json"]
    }
  }
}

桌面客户端若找不到 npx，使用它的绝对路径，或者使用绝对 Node 路径加 src/mcp.js。不要用带启动横幅的 npm start 作为 MCP 通信入口。

源码安装可生成本机路径的配置参考：

npm run host-config -- /absolute/path/strata-coder.config.json

生成器只打印通用配置和已有客户端适配示例，不修改任何客户端配置。客户端各版本配置格式可能不同，应以实际版本为准。

把 prompts/planner.md 合并到主模型指令中，告诉它何时委派、如何等待和审查。不要覆盖已有项目规则。strata-coder init 会改为生成 .opencode/strata-coder.md 并在项目 AGENTS.md 中插入受管引用。用户可以说“这个任务用主模型，不调用本地模型”或“这个任务交给本地模型”。如果要接手正在执行的任务，先取消该任务并确认终态。

停用某个项目：删除 .opencode/strata-coder.md、AGENTS.md 中 strata-coder:start 与 strata-coder:end 之间的引用，以及项目 OpenCode 配置里的 strata_coder 服务；再按需删除 .strata-coder/。第一版不提供 uninstall 命令。

工作流与工具

1. get_capabilities：确认模型、宿主提供的 workspace 目录与来源、检查名称和预算。

2. submit_task：提交一个边界明确的实现或修复任务，立即返回任务 ID。

3. get_task：优先使用 wait_seconds: 20，查看进度与终态。

4. read_artifact：按需分页读取补丁、检查或事件。

5. cancel_task：请求取消，再查询确认停止。

任务参数见 examples/task.json。allowed_paths 为相对文件/目录前缀，不支持 glob。相同项目、相同 request_id 和相同参数的重试会返回同一任务；不要通过换 ID 无限重试失败任务。

终态包括 ready_for_review、needs_primary、failed、cancelled、interrupted。ready_for_review 仅表示完成了配置检查，仍需审查业务正确性。needs_primary 返回失败原因和部分补丁，供主模型接手或重新拆分任务。

修改发生在项目副本，原项目不会自动改变。审查完整补丁后，在原项目执行：

git apply --check /absolute/path/to/changes.patch
git apply /absolute/path/to/changes.patch

应用后再次运行项目检查。后台 Worker 在 MCP 断线后继续执行；禁用 MCP 不会取消任务。取消请求也不保证模型服务立即停止 GPU 计算。只有任务结束后才应清理对应状态目录。

验证与开发

npm test
npm run test:package

自动化测试使用模拟模型，覆盖 MCP 连接、真实 Worker、去重、取消、检查、失败交接和端点串行。打包测试会安装真实 tarball 并验证其启动入口和 MCP 握手，需要访问 npm registry，不调用本地模型。

可选真实推理测试：

npm run smoke -- /absolute/path/strata-coder.config.json
npm run regression -- /absolute/path/strata-coder.config.json /absolute/path/local-model-eval

回归脚本依赖外部评估数据及 macOS sandbox-exec，不包含在 npm 包内。真实任务记录、评估报告、本机配置和凭据不会随源码或 npm 包发布。

权限边界

工作副本隔离代码变更，不是操作系统沙箱。文件工具限制目录、修改范围和符号链接；配置的检查仍以宿主用户身份运行项目代码。仅对受信任项目配置检查，需要执行不可信仓库时，将整个 Worker 放入容器或 OS 沙箱。

默认排除 .git、依赖目录、.env*、.pem、.key、.aws、.ssh 等，但不是完整的敏感数据扫描。源码会按需发送到配置的模型端点；主模型读取的摘要、补丁和日志进入主模型上下文。token 统计仅属于本地服务，不代表主模型节省量。

发布与许可

仓库维护和 GitHub Actions → 公共 npm 的步骤见 docs/PUBLISHING.md。使用 MIT 许可证，见 LICENSE。