可审计执行运行时 firestige/crystra-execution

Crystra — Execution System

把每一次 Agent 对话变成一条可审计、可恢复、版本绑定的交付。

Execution System 是 crystra 的 Execution System —— 与宿主无关的小型执行边界：它解析并校验一个确定的 Workflow Package，把绑定信息写入不可变的 Delivery Manifest，在 Runner 隔离的执行上下文中协调整个交付；进程崩溃后可从最后一个持久化边界恢复；执行过程通过 OTLP 发出有界观测——观测从不控制执行。

交付形态

Execution System 是宿主无关的产品，不是某个插件。DSH 只是入口之一：

| 形态 | 包 | 适用 |
| 嵌入库 | crystra-execution | 宿主无关嵌入 —— 导入 ExecutionApplicationFactory，用 create(configFile, dependencies) 引导 |
| DSH 插件入口 | dsh-crystra | DeepSeek Harness 用户 —— 在对话与侧边栏中运行工作流 |
| CLI | execution-config（随 crystra-execution）| 配置 init / copy / validate / dump-effective |

DSH 插件是首个产品入口；每个被接纳的 Workflow Action 都在 Runner 所有、隔离的 DSH 执行上下文（DSH-E）中运行，绝不在 Intake 上下文（DSH-I）中。

为什么需要它

| 裸 Agent 对话的问题 | 实际会发生什么 | Execution System 如何解决 |
| 执行是黑盒 | 模型做了什么、用了哪个版本的工作流定义，事后无法核对 | 每次交付绑定一个确定版本 + SHA-256，写入不可变 Manifest |
| 中断即丢失 | 进程退出/重启后，长任务状态无处可寻 | Manifest/当前槽位持久化，/crystra recover 从最后持久化边界恢复 |
| 版本漂移 | 同一请求在不同时刻可能执行不同定义 | 确定的 name@version selector、不可变 GitHub 资产与已校验的 exact-content READY cache |
| 观测与执行耦合 | 遥测故障可能拖垮执行 | 单向、best-effort OTLP；Evidence 或遥测不可用时 Execution 继续运行 |

工作原理

三个 Module 承担上述职责：

- Delivery Binding 解析一个确定的、本地 READY 的 Workflow Package（selector → 校验 → 本地 MISSING/STAGING/READY 存储），并构造 Manifest 内容。
- Runtime Interaction 拥有规范工作区排他性、当前 Delivery 槽位、Manifest 持久化、Runtime 调用、恢复与最终处理。
- Delivery Observation 将出站有界事实映射到单向、尽力而为的 OTLP profile，但不控制执行。

默认 Source 是配置指定的 firestige/crystra-workflow-package GitHub Release。implementation-workflow@0.3.0 与 system-design-workflow@0.3.0 会经过下载、校验并发布到本地 READY store；它们不会嵌进任何 Execution artifact。

架构图

安装

唯一公开 DSH 插件为 dsh-crystra，由 firestige/crystra-dsh 持有并注册。插件以普通依赖引用本核心的精确 GitHub Release tarball。安装与配置以该仓库说明为准，不再分发独立 Execution 插件或安装器。

Crystra 候选仍在准备中，尚无可安装的 Crystra 发布。packages/dsh-intake 是待归并到统一插件的私有回归夹具。

命令

/crystra list # 隐私安全的 Delivery 与工作区状态 /crystra create <name@version> /crystra recover [delivery-id] /crystra status [delivery-id] /crystra action finish /crystra abandon <delivery-id>

显式第一方 skill /workflow-execution 通过 DSH-I 专用工具 workflow_execution_intake 恰好执行一次闭环操作。

兼容性

| 维度 | 要求 |
| Node.js | >=24.12.0 <25 |
| DeepSeek Harness | 0.1.5-rc.2（@deepseek-ai/dsh）|
| Workflow Package 契约 | agentops.workflow-dsl@2.0.0 |
| 观测契约 | agentops.observation@1.0.0 |
| 检查点存储 | better-sqlite3（原生构建，经 allowBuilds 批准）|

已知限制与待办

- 开发者预览 —— 0.1.x 面向个人与小团队的可信本地环境；后续仍可能发生破坏兼容性的变化。
- Session/Delivery 排他绑定 —— DSH Intake 只传递 private、typed、invocation-only 的精确注册会话工作区证明；Execution 推导并持久化 canonical Git worktree，Manifest/current-slot 继续作为 Delivery/worktree 的持久权威。Session、Delivery 与被占用 worktree 均不得隐式切换、共享、抢占或超时释放。
- 观测默认关闭 —— 将 observation.enabled 设为 true 并提供 loopback OTLP base endpoint 即可启用 non-controlling exporter。
- 仅 DSH 交互面 —— 发行版以自带 web profile 为交互组装；自定义 profile 只含 dsh-base，不是交互式 Intake 面。

面向维护者

- 发布 qualification —— 见发布流程。本仓只验证宿主无关 core；DSH bundle 与 clean-profile qualification 由 firestige/crystra-dsh 负责。
- 本地发布前 E2E —— 指南；最终 DSH quickstart；配置参考；DSH Intake package reference。

直接嵌入

宿主无关嵌入从 package root 导入 ExecutionApplicationFactory、DefaultExecutionApplicationFactory、ExecutionRequest、TaskPrompt 与 configuration types。调用 default factory 的 create(configFile, dependencies) 是唯一 production bootstrap path。Exact DSH runtime 是 optional peer：package-root import/type consumer 无需安装它；执行当前 dsh Provider 时，embedding profile 必须提供 @deepseek-ai/dsh@0.1.5-rc.2。Release 包含 config/schema/execution.config.schema.json、versioned defaults/examples、compiled TypeScript declarations，以及 execution-config init|copy|validate|dump-effective。

多 Provider 2.0

execution.config@2.0.0 是正式的多 Provider production path，不含 installation-wide Provider 或 model default。除非 embedding 显式传入 registry，DefaultExecutionApplicationFactory 会注册精确锁定的 DSH、Copilot SDK 与 Codex CLI Provider factory。每个 Agent-action Role 必须在 <canonical-worktree>/.crystra/role-provider-bindings.json 中显式绑定 exact Provider identity/version 与 Provider-owned model coordinate。Admission 校验 Workflow required capabilities，把 factory descriptor digest 冻结进 execution.delivery-manifest@2.0.0，且从不做 priority selection 或 fallback。Recovery 只接受同一 descriptor，并且只为 persisted Delivery 实际使用的 Provider 启动 realm。Machine schema 见 config/schema/execution.config.v2.schema.json。

默认 Copilot factory 注册 provider.copilot@1.0.78，通过精确锁定的 SDK 复用本机登录；默认 Codex factory 注册 provider.codex@0.144.5，复用 Codex CLI 的本机登录状态。两条路径都不会向 embedding host 索取 token material。每个 Delivery realm 只接纳已为 Role 冻结的 model coordinate；runtime、登录、model、恢复或 binding 发生漂移时一律 fail closed。

私有本地包与 RC

自行修改的 Workflow 无须先公开发布。将编译好的包目录（含 definition/package.json 及其声明的资源）打包并登记到本地目录：

workflow-local-source pack /绝对路径/my-workflow /绝对路径/private-workflows/source.json

源码构建后可使用 node dist/configuration/local-source-cli.js pack ...。命令输出精确 selector 和应写入 Execution 安装配置的 workflowSource：

{
"kind": "adapter",
"adapterKey": "workflow.local.v1",
"adapterConfigFile": "/绝对路径/private-workflows/source.json" }

本地源仅接受 my-workflow@1.2.3-rc.1 等精确版本；裸名称、latest、版本范围均不能选取本地包。默认公共 GitHub 源拒绝预发布版本，包括显式指定的 RC；本地源不会回退到网络源。

目录记录包名、精确版本、相对归档路径和 SHA-256；Execution 校验归档并继续执行同样的 schema、快照与资源内容校验。本地缓存独立，缓存命中也不能绕过当前本地源校验。修改 Workflow 后，重新生成有效摘要和快照并使用新的精确版本（如 1.2.3-rc.2）；相同坐标覆盖不同内容会被拒绝。已 admission 的 Delivery 恢复仍使用原冻结绑定。

获取源码

本仓库通常作为 crystra 的 submodule 使用：

git clone --recurse-submodules https://github.com/firestige/crystra.git

单独克隆：

git clone https://github.com/firestige/crystra-execution.git

文档

- Execution System 设计
- 概念架构
- Workflow 组合模型
- Execution–Evidence Interaction Contract
- 规划中的第一方 LangGraph Runtime Profile

License

Apache-2.0

DSH Agent Provider

rc.2 的迁移与验收范围见运行时迁移说明。

默认 production registry 新增 provider.dsh@0.1.5-rc.2（dsh-headless），支持 structured completion 和 Action interaction。它在独立的 Delivery realm 中运行锁定版本的 DSH headless runtime，不附着到已有 DSH UI 会话，也不加载宿主的环境插件。使用时需安装可选 peer @deepseek-ai/dsh@0.1.5-rc.2；其他 Provider 不会因此启动或加载 DSH。

在 .crystra/role-provider-bindings.json 中显式绑定对应 Role（将 role.reviewer 替换为 Workflow 的实际 Role）：

{
"schemaVersion": "execution.repository-role-provider-bindings@1.0.0",
"bindings": {
"role.reviewer": {
"agentProvider": { "identity": "provider.dsh", "version": "0.1.5-rc.2" },
"model": { "provider": "deepseek", "model": "deepseek-chat" }
}
}
}

凭证由 Provider 内部读取：优先使用进程环境中的 DEEPSEEK_API_KEY，其次读取 $DSH_HOME/.credentials.yaml 中的同名引用（默认 ~/.dsh/.credentials.yaml，DSH version: 1 / refs 格式）。凭证缺失时，会话打开失败。密钥不写入 Role binding、Manifest 或恢复记录；旧版严格指定文件的适配器维持原有行为。

开发锁文件同时将 DSH 组件依赖固定到 rc.2，避免上游 CLI 的版本范围自动引入后续 RC。适配器使用公开的 Session.ownEvents() 接口。已存在的 Delivery 保留原 provider 描述符，不能自动换成新版恢复；这类 Delivery 应使用原版本运行时，或更新绑定后准入新的 Delivery。

DEEPSEEK_BASE_URL 可指向本机或代理的 OpenAI 兼容 DeepSeek 接口，默认 https://api.deepseek.com。本机接口必须支持 DSH 的 DeepSeek chat/tool-call 协议和所绑定的模型。model-provider coordinate 支持 deepseek 和 deepseek-official。规划时通过同一服务的 GET /models 查询真实模型 ID，返回 deepseek 模型坐标。空目录保持为空；缺少凭证、请求失败、无效响应或超时会报告 unavailable，不填入默认模型。发现请求有大小和时间限制，不创建 Delivery、Session 或状态目录；modelQueryTimeoutMs 默认 10 秒，生产组合使用 startupTimeoutMs。不会自动导入 DSH profile patch 配置或 .env 文件。

Embedding 可从 crystra-execution 导入并注册 createDshAgentProviderFactory({ stateDirectory, credentialPath, credentialRef, baseURL, turnTimeoutMs })，仅 stateDirectory 必填。这些参数控制连接与认证，不提供模型 fallback。默认 production factory 使用 executionTimeoutMs 作为回合超时。

会话按 Delivery、Manifest 与 canonical worktree 隔离持久化；恢复要求 opaque identity 及 session/Role/model/连接绑定一致。取消、超时和接口错误会返回明确的失败状态，超时会话不能再次执行。Delivery realm 释放时会清理其会话和 runtime。

管控平面的 Provider 模型目录

await composition.control.planningCapabilities() 是 Execution 的只读规划接口。每次查询由已注册 Provider 获取本机登录账号的原生模型目录，不创建 Session 或 Delivery，也不读取其他会话。providers[].modelCatalog 返回 state（available、unavailable 或 unsupported）及 models: [{provider, model}]，其中两字段可直接用于 Plan 的 roleBindings 模型配置。Provider 身份和精确版本仍来自同一条 Provider 描述；外部 Chat 的模型选择不决定 Role 绑定。

Crystra 在每次管控对话及自动续轮前等待并刷新此接口。查询失败时只返回明确的不可用状态，不填默认模型、不要求用户查询源码或手填 ID。目录表示当前可选能力；正式 Plan 确认与 Delivery 入场仍执行原有绑定校验。