codefree/ — code-free 工具

English | 中文

@historuians/dsh-codefree 注册一个面向模型的 codefree 工具，把实现委派给 codefree-o CLI（opencode 分叉）。harness agent 先规划——通常用它的 fs/bash 工具写一个方案文件（markdown/JSON）——然后带着方案调用 codefree。工具在会话工作区运行 codefree-o run 并回传报告，让 agent 基于编成结果继续，而不是重新实现。

为什么单独做一个工具而不是用 bash

一条 bash 调用也能跑 codefree-o run，但 harness 得从原始文本里重建期望的模型可见契约。这个工具声明了该契约：经过校验的 parameters、规范输出 schema、终端渲染意图、针对长实现的后台任务支持，以及确定性的 --dir/--model/--agent 映射。它还塑造子进程环境，让 codefree-o 自己的 home 保持可写。

使用

一个组合加载该插件，并在非沙箱运行时配合非受限的 shell/subprocess provider：

- id: codefree
  plugin: '@historuians/dsh-codefree'

工具名为 codefree。模型先写方案，再调用它：

task: "implement per PLAN.md"
plan_file: "PLAN.md"
dir: "<session workspace>"

一键安装

@historuians/dsh-codefree 是一个 Profile Bundle（声明了 dsh.bundle.patch），一条命令装进目标 dsh profile，并在宿主层注册 codefree 工具：

dsh plugin --profile web add @historuians/dsh-codefree   # 一键安装插件
dsh web                                                  # 启动 GUI

想拿到完整「DeepSeek 规划 → codefree 编码」体验（codegen 二进制 + 编排 preset + 严格技能 + 参考脚本），再跑包自带的 codegen-setup 脚本（暴露为 dsh-codegen-setup bin，也可 node <pkg>/bin/codegen-setup.mjs）：

npm i -g @srdcloud/codefree-o          # codegen 二进制（或脚本会自动装）
dsh-codegen-setup                      # bundle 安装 + preset + 技能 + 默认
dsh web                                # 启动 GUI

codegen-setup 会：

1. 确保 @srdcloud/codefree-o 全局已装（npm i -g），已有则跳过。
2. 把 @historuians/dsh-codefree Bundle 装进 $DSH_PROFILE（默认 web）profile。
3. 把 codegen-orchestrator preset 拷到 $DSH_HOME/.agent-presets。
4. 把 codegen-slice 技能拷到 $DSH_AGENTS_HOME/skills（默认 ~/.agents/skills）。
5. 把参考 workflow 编排脚本拷到 $DSH_HOME/codegen。
6. 在 $DSH_HOME/settings.yaml 写入 agent-presets.default: codegen-orchestrator。
7. 打印启动命令和一个演示提示。

然后新建会话（web host 默认用 codegen-orchestrator），让 DeepSeek 规划、切片、经 workflow 扇出到 codefree、审查、合并即可。Bundle 提供 codefree 工具（全局），preset 提供编排人设，技能提供严格契约。

配置

| 键 | 类型 | 默认值 | 用途 | |---|---|---|---| | command | string | 'codefree-o' | 驱动 codefree-o 的可执行文件。npm 全局安装（npm install -g @srdcloud/codefree-o）会从 PATH 与 npm 全局 bin 自动发现；设成绝对路径可指定某个二进制。解析不到时工具会报错并要求给出路径。 | | homeDir | string | 未设置 | 把 USERPROFILE/HOME 固定到该目录（须已装有 .codefree-o home）。仅在受限沙箱下需要。 | | autoApprove | boolean | true | 传 --auto，让非交互权限提示不挂起。 | | enableRunInBackground | boolean | true | 在工具上暴露 run_in_background。 | | defaultTimeoutMs | number | 未设置 | 模型未提供时的每次调用超时。 |

工具契约

• parameters：task（必填）、plan_file、dir、model、agent、timeout_ms，以及（启用时）run_in_background。
• execute 通过 ctx.subprocess 以 argv 数组（绝不经过 shell 解释）发起 codefree-o run <task> [-f <plan_file>] --dir <cwd> [--model ..] [--agent ..] [--auto] --format default。每次调用的超时和调用方的 abort 信号都到达 spawn spec，因此超时与取消一样触发同一种树作用域终止升级。
• output.schema 是一个判别联合：foreground 运行（exitCode、signal、timedOut、stdout、stderr）或 background 任务 id。非零退出以标记报告，而不是工具错误；只有 spawn 级失败与 abort 才表现为 isError。

Model Experience

请求上下文与条件

模型看到什么

工具由 toolDescription 描述，并出现在模型的工具列表里。除工具专属引导区段外，它不给系统提示词贡献字面散文。

引导区段的逐字文本

Check the codefree result before moving on; it may have modified the workspace. Investigate any [exit code: N] marker.

Token 影响

固定 —— codefree 工具 schema 与一个引导区段。plan_file 内容作为 codefree-o 附件传入，不拷贝进模型请求。

KV Cache 影响

追加式 —— 引导区段与工具 schema 前缀稳定；重复调用不重写更早的请求 token。

构建

包可以独立构建：tsconfig.json 是自包含的（不继承 deepseek-harness monorepo 的基础配置）， npm install 之后：

• npm test — 针对已发布的 @deepseek-ai/* 依赖跑 vitest 单元测试 + 真实挂载 boot 测试
• npm run typecheck — 对 src/ 跑 tsc --noEmit
• npm run build — 从 src/ 重新生成 lib/types/*

运行时产物（lib/index.js）是已提交的预构建文件，npm run build 不会重新生成它；改动 src/ 后请保持它同步。

已知限制与被推迟的工作

• codefree-o 必须已安装并已认证 —— 工具假定 codefree-o 在 PATH 上，且它自己的 ~/.codefree-o home 已含配置/认证。缺少可执行文件会让调用失败；没有插件内的供给或凭据引导。
• 设计上不设限 —— codegen 需要写代码库并跑 git/构建/测试工具，因此不支持沙箱执行；部署方必须让该工具在非受限执行器下运行（或设置 homeDir 与宽松沙箱策略）。
• 后台 readOutput 仅在完成后输出 —— 后台任务在结算后一次性流出整份报告（工具在关闭后读取已收集输出），不是增量行；长期增量的 UI 被推迟。
• 输出是人工文本 —— --format default 返回 codefree-o 的报告文本；结构化 diff 投影需要把 codefree-o 的 --format json 事件流解析成 DiffResultView，这一点被推迟。