CoreMind 面向没有智能体开发经验的新手和普通工程师，通过统一 Runtime 提供受控 Harness/Loop、CLI/TUI、TypeScript SDK、Python SDK，以及随功能同步交付的 SOP、Skill、双语指南和离线示例。

当前稳定版为已发布的 0.3.0，完整继承 rc.2 的 Harness、Context/Artifact、Coding Kernel、受控扩展、实验与四入口快照。可从 GitHub Release、npm 与 PyPI 获取。

0.3.0 已从同一提交完成 Windows/Linux 自动矩阵、双平台真实伪终端（Windows ConPTY / Linux PTY）、真实 Provider 复验、最终文档审计和维护者发布授权。Tag、8 个 npm 包、PyPI wheel、独立源码 ZIP、Manifest 和哈希清单均绑定该发布；双语文档站的发布状态与 0.3.0 一致。

5 个黄金示例 · SOP/Skill 索引 · 版本迁移指南 · 已知限制 · 公开路线图 · 安全策略 · 社区行为准则

当前仓库具备什么能力

当前稳定版 0.3.0 坚持 CLI/TUI、TypeScript SDK、Python SDK 和源码共用同一个 Runtime、协议与结果语义；下表按当前仓库源码与已发布产物描述。

当前不包含完整 Web 开发环境、官方托管 API、官方 Docker 镜像、纯 Python Runtime 和 macOS 正式支持。详见公开路线图。

后续版本计划

0.3.x 将以真实缺陷、社区反馈和发布证据为依据持续迭代。CoreMind 仍不会替用户决定业务目标、审批责任或智能体架构，也不计划提供官方 Docker 镜像或把框架变成托管 SaaS。

0.3.0-rc.2 完成 Batch 0～6 并通过公开发布物 Dogfooding；0.3.0 稳定版没有新增产品行为，只同步版本、发布元数据和必要文档。alibaba-model-studio/qwen-plus 已在发布 Runtime 上完成七项真实复验；P01～P20、8 个 npm tarball、Python wheel、独立源码 ZIP、21 个模块和全部受审计 Markdown 文件已在同一发布提交通过统一门禁。

CoreMind 解决什么问题

CoreMind 让没有 Agent 开发经验的工程师先走一条标准路径：

1. 用 coremind create 新建项目或接入已有工程。
2. 用 Config v2 明确 Agent、工具、预算、权限和质量档。
3. 用 run 或 chat 开发，并查看审批、Trace、预算和 checkpoint。
4. 用 check 做静态质量门禁，用 eval 做业务场景评测。
5. 按项目生成的需求、架构、SOP、测试指南、验收清单和 Skill 继续迭代。

框架不会替用户决定业务目标、数据字段、审批责任或 Agent 架构。用户负责业务与最终验收；CoreMind 负责机制保护、质量证据和开发指导。

三种使用方式

正式目标平台仍是 Windows 与 Linux；macOS 暂列为后续支持。Web 完整开发环境进入三期，当前不提供官方 Docker 镜像或托管 API 平台。

快速开始

需要 Node.js ≥ 22.19。0.3.0 已在 npm Registry 公开，可执行下面的稳定版安装命令。

npm install -g [email protected]
coremind providers
coremind create my-agent --template translator --language typescript --provider alibaba-model-studio
cd my-agent
copy .env.example .env
coremind check coremind.yaml
coremind run coremind.yaml --prompt "翻译：你好，世界"
coremind eval coremind.yaml

Linux 将 copy 换成 cp。交互终端会询问 Provider；脚本或 CI 必须显式传入 --provider，可用 coremind providers 查看清单。空目录会要求选择 TypeScript、JavaScript 或 Python；已有工程能唯一识别语言时自动判断，混合工程不会猜测。

生成的项目不仅有 coremind.yaml，还包括代码/测试骨架、evals/scenarios.yaml、中英文需求与架构、开发 SOP、测试指南、验收清单、项目 Skill、决策记录和 checkpoint 目录。已有文件不会被覆盖。

Config v2 最小安全配置

schemaVersion: 2
name: support-agent

provider:
  id: deepseek
  apiKeyEnv: DEEPSEEK_API_KEY

agents:
  main:
    systemPrompt: |
      只根据已确认的业务规则和工具结果回答；信息不足时明确说明。

runtime:
  maxTurns: 12
  maxSteps: 20
  maxToolCalls: 10
  maxToolFailures: 2
  maxRetries: 2
  runTimeoutMs: 120000

permissions:
  mode: ask
  workspaceOnly: true
  network: ask

quality:
  profile: standard
  minScenarioPassRate: 1
  allowOverride: true

权限模式：

• ask：需要批准的工具逐项询问。
• assisted：工作区内低风险文件操作自动批准，高风险操作询问。
• full：不逐项询问，但显式 deny、审计、Trace 和 checkpoint 仍然生效；路径感知文件工具继续执行工作区策略。

Linux 上的内置 bash 在 OS 级沙箱中运行，当前固定断网、只允许写工作区，并在沙箱不可用时关闭执行而不回退宿主 shell。Windows 一期没有 OS 级 shell 沙箱；宿主 Shell 只有在 full、workspaceOnly: false、network: allow 同时选择时开放，其他组合安全拒绝。Git Bash 发现只提供命令兼容性，不提供隔离。CoreMind 不会把 checkpoint 描述成任意副作用的完整恢复。

Linux 沙箱依赖仍处于上游研究预览阶段，当前作为纵深防御能力使用；安全结论以完整权限策略、恢复机制和自动化测试证据为准。

CLI/TUI

coremind create <name>       新建项目或接入已有工程
coremind run <file>          无头运行；支持 --print、--json-events、--session、--resume
coremind chat <file>         多轮 TUI/readline；审批、预算、错误与 checkpoint
coremind check [file]        配置、安全、项目材料和质量档门禁
coremind eval [file]         重复运行 evals/scenarios.yaml
coremind doctor [file]       Node、配置与 Provider 环境自检
coremind templates           查看模板（兼容 list-templates）

run/chat/eval 可用 --permission ask|assisted|full 临时选择批准强度，但不会关闭安全边界和审计。TUI 支持 /status、/checkpoints、/diff <id>、/restore <id>、/abort 和 /exit。

coremind run 的退出码可直接用于 PowerShell、CI 和其他自动化：0 成功、1 失败、2 等待人工处理、3 预算耗尽、124 超时、130 中止。使用 --json-events 时，stdout 只输出 JSONL，最后一行固定为 type: "run_result" 的完整终态；诊断信息写入 stderr。--print 与 --json-events 不能同时使用，避免机器输出混入普通文本。

TypeScript SDK

import {
  CoreMindRuntime,
  defineTool,
  loadConfigFile,
  parseAndValidate,
} from "coremind-ai";

const config = parseAndValidate(await loadConfigFile("coremind.yaml")).config;
const lookupOrder = defineTool<{ orderId: string }>({
  name: "lookup_order",
  description: "查询订单",
  parameters: {
    type: "object",
    properties: { orderId: { type: "string" } },
    required: ["orderId"],
  },
  effect: { operations: ["read"], reversible: true },
  execute: async ({ orderId }) => ({ orderId, status: "paid" }),
});

const runtime = await CoreMindRuntime.create({
  config,
  configDir: process.cwd(),
  initialPrompt: "查询 A-100",
  toolDefinitions: [lookupOrder],
  approveTool: async () => "allow",
});
const result = await runtime.run();
console.log(result.outcome, result.metrics, result.transcript);

Python SDK

Python SDK 启动一个常驻 Node worker，通过 CoreMind Protocol v1 使用相同的 Runtime 和结果语义；它不是第二套 Python Agent Loop。

from coremind import CoreMindClient

client = CoreMindClient("coremind.yaml", approval_handler=lambda request: "allow")

@client.tool(
    description="查询订单",
    effect={"operations": ["read"], "reversible": True},
)
def lookup_order(order_id: str) -> dict[str, str]:
    return {"id": order_id, "status": "paid"}

with client:
    result = client.run("查询 A-100")
print(result["outcome"], result["transcript"])

完整说明见 Python SDK 模块。

Harness 与质量证据

• 统一 RunOutcome / RunMetrics / EvaluationReport / ReleaseReadiness；成功、失败、暂停、中止、超时和预算耗尽都通过返回值表达，失败不能伪装为成功。
• turn、step、工具调用/失败、重试、token、费用、步骤与总运行超时预算。
• ask/assisted/full 三档权限，deny、路径和网络策略优先。
• ask 模式下人工拒绝任一工具审批后，被拒绝项和本批次尚未审批的后续工具都会被阻断；本批结果归并后返回 paused，不会继续请求模型或重复弹出审批。顺序工作流中的拒绝步骤不会保存输出，后续步骤不会启动。
• edit/write 前 checkpoint，运行后 diff 与显式恢复；恢复前检查工具完成后的文件指纹，检测到人工或并发修改时拒绝覆盖。
• 自定义工具必须声明 effect.operations 与 effect.reversible；权限层递归检查嵌套路径和 URL，未知副作用在受约束模式下安全拒绝。
• Windows 宿主 Shell 只有在 full、关闭工作区限制、允许网络同时选择时开放，其他组合安全拒绝；Git Bash 不等于隔离；Linux Shell 继续使用操作系统级隔离。
• 带 runId、eventId、sequence、timestamp 的 Trace 与 append-only RunState。
• 意外中断后可从完整 step_output 边界继续；已结束运行、配置/输入不匹配或未完成步骤含非重放安全工具时明确拒绝恢复。
• 每个工具调用写入幂等关联标识；业务工具仍需自行用该标识实现收据或去重，CoreMind 不承诺“恰好一次”。
• Provider 调用前的确定性 Context 保护和多轮 Session 恢复。
• RunResult.snapshot 统一四个入口的 operation、outcome、指标、评测、Trace、Checkpoint、Artifact、扩展收据和恢复判断。
• 生命周期扩展仅开放 before-model、before-tool、after-tool、run-finished 四个事件；能力与信任显式声明，默认不加载未知本地扩展。
• 轻量 experiment → arm → run → trace 记录版本、输入指纹、环境、随机种子、运行结果和 grader，不建立第二套评测终态。
• development、standard、strict 三档质量门禁；安全错误不可覆盖，其他覆盖必须记录原因并追加到 .coremind/quality-overrides.jsonl。

Provider 策略

CoreMind 提供锁定的 40 个可配置 Provider 入口，也支持自定义 OpenAI-compatible 端点。可配置不等于 CoreMind Certified；当前认证必须在同一版本完成流式、工具调用、结构化结果、多轮、abort、错误映射和长上下文七项真实测试。旧证据继续保留用于追溯，但不能替代当前候选复验。alibaba-model-studio/qwen-plus 已基于 0.3.0 候选完成七项真实复验，因此当前矩阵为 1 个已认证、39 个待认证。

默认无遥测。任何业务数据外传都必须由用户明确授权，密钥应使用 apiKeyEnv，不应写入 YAML。

查看自动生成的供应商矩阵和认证 SOP。

学习与验证材料

• 21 个能力模块：每个模块均有实现路径、测试、双语 README/SOP/指南、Skill、示例和 module.yaml。
• 5 个黄金示例：订单助手、合同审核、Python 数据分析、受控调查与验证修复 Loop，均可用本地 mock Provider 离线运行。
• 2 个编码智能体真实缺陷仓库：TypeScript 与 Python 均验证复现、最小修复、目标/回归测试、只读 Git 证据和脏工作区保护。
• 配置指南、Skill 指南、质量指南、CLI 指南。

源码开发

npm ci
npm run build
npm run check
npm run test:stability
npm run test:coverage
npm run test:coding-evals
npm run build:python-worker
npm run release:check-npm
npm run release:test-npm
npm run release:test-source
python -X utf8 -m build --wheel python
npm run release:check-wheel

npm run check:modules 会检查 21 个模块与 5 个黄金示例的双语配对、Skill frontmatter、源码/测试路径、Markdown 链接、Config v2 和版本记录。CI 同时面向 Windows 与 Linux，连续三次执行 Node 测试，并验证覆盖率不下降、Python SDK、真实 Worker 一致性、黄金示例、编码缺陷评测、npm tarball 和 wheel 干净安装。P20 由目标平台真实伪终端自动验收；若自动脚本与人工可见界面出现差异，再补充人工复核记录。

开源协议

MIT · 参与贡献 · 安全策略 · 社区行为准则 · 上游组件声明见 THIRD_PARTY_NOTICES.md