声明式意图 → 确定性执行契约 → 智能体 / 执行框架

Decretum

Decretum 将结构化意图转化为面向智能体和执行框架的确定性执行契约。

Decretum 是一个领域中立的声明式执行编译器。它结合模式、配方、配置文件、提供者/集成注册表、发现、验证、策略和确定性解析，生成可移植的执行契约。

安全研究是 Decretum 的参考领域，而非其架构边界。同一编译器模型可以描述软件工程、基础设施自动化、数据工程、事件响应、科学实验以及其他可复现的技术工作。

架构

Decretum 不是运行时。它定义可以执行的内容并生成可移植的执行契约。它不执行工作、不管理智能体/研究人员交互、不收集证据、不维护发现，也不生成报告。

编译完成后，Decretum 即停止。契约被传递给外部执行框架或智能体运行时。

如果后续执行需要新能力或需求变更，请求会返回 Decretum 进行验证、解析和重新编译。

模型

Schema       = 存在什么 / 语义边界
Recipe       = 应该做什么
Profile      = 执行特征与偏好
Registry     = 可用实现
Resolver     = 确定性能力绑定
Compiler     = 可移植契约生成
Harness      = 实际执行与交互
Store        = 持久化执行/研究记忆

重要的分离关系是：

                    DECRETUM
          声明式执行编译器
                       |
       +---------------+---------------+
       |               |               |
    Schema           Recipe          Profile
   "什么"           "做什么"         "如何做"
       |               |               |
       +---------------+---------------+
                       |
                    Resolver
                       |
     能力 + 提供者 + 集成
       + 执行框架 + 就绪状态 + 策略
                       |
                       v
               执行契约
                       |
                       v
              外部执行框架/智能体
                       |
          +------------+------------+
          |            |            |
       执行         交互         持久化
          |            |            |
          +------------+------------+
                       |
                    Store

领域包

编译器核心是领域中立的。领域特定的语义存在于注册表和模式中，而非编译器分支中。

示例：

• 安全研究 — 恶意软件、网络、取证、检测与云调查
• 软件工程 — 源代码变更、依赖、测试、构建与容器
• 基础设施 — 虚拟机、容器、网络与部署需求
• 数据工程 — 数据集、转换、验证与产物
• 科学/技术实验 — 仪器、观测、分析与证据

领域包贡献能力、模式、配方、配置文件和提供者元数据。它不改变核心解析器/编译器语义。

为什么使用结构化契约而非宽泛的 Markdown 规范？

Markdown 非常适合解释说明。它不是确定性的执行接口。

Decretum 分离了：

人类意图
    |
    v
结构化模式 + 配方 + 配置文件
    |
    v
经过验证的解析
    |
    v
可移植执行契约
    |
    v
智能体 / 执行框架执行

这为智能体提供了机器可读的边界，同时将实现选择排除在配方之外。

示例：软件工程

软件任务可以使用同一编译器：

apiVersion: decretum.dev/v1
kind: ExecutionRecipe
domain: software_engineering
id: build-user-service
name: Build User Service
version: "1.0"
objective: Build and validate a Python service.

capabilities:
  - source.read
  - source.modify
  - dependency.install
  - test.execute
  - artifact.build
  - container.build

profiles:
  infrastructure: local-dev
  language: python
  testing: pytest
  container: docker
  agent: coding-agent

completion:
  required:
    - tests_pass
    - artifact_built
    - container_built

同一意图可以针对另一组偏好进行编译：

profiles:
  infrastructure: isolated-dev-vm
  testing: pytest
  container: podman
  agent: enterprise-coding-agent

配方描述意图。配置文件表达偏好。提供者注册表决定实际可用的内容。

安全研究参考示例

id: suspicious-network-investigation
name: Suspicious Network Investigation
version: "1.0"
role: threat_researcher
objective: Determine whether the sample creates unexpected network activity.

capabilities:
  - process.observe
  - network.capture
  - artifact.collect

infrastructure_profile: isolated-linux-vm
instrumentation_profile: linux-network-observation
harness_profile: interactive-research

配方不包含 Lima/Docker 生命周期、MCP 实现、智能体提示词或运行时特定代码。

端到端工作流

1. 定义结构化意图。
2. 引用规范能力。
3. 选择配置文件/偏好。
4. 验证配方。
5. 发现可用的执行面。
6. 解析能力 → 提供者 → 集成 → 执行框架。
7. 检查就绪状态与策略。
8. 编译执行契约。
9. 将契约交给外部执行框架。
10. 执行框架执行、交互并持久化其状态。
11. 如果需求变更，返回 Decretum 并编译新契约。

Decretum 不执行步骤 9–10。

能力演进

发现
   |
提议
   |
语义审查
   |
批准
   |
规范能力
   |
提供者实现

发现可以提议能力，但不能静默改变规范语义。

快速开始

git clone https://github.com/Opposum0112/Decretum.git
cd Decretum
uv sync
decretum capabilities discover
decretum validate recipes/<recipe>.yaml
decretum resolve recipes/<recipe>.yaml
decretum compile recipes/<recipe>.yaml

Decretum 的 validate/resolve/compile 路径中没有任何环节会执行工作。

解析链

能力
    |
提供者
    |
集成
    |
执行面
    |
执行框架兼容性
    |
主机/提供者就绪状态
    |
策略兼容性
    |
就绪 / 阻塞

架构边界

Decretum 刻意不成为：

• 智能体运行时
• 工作流引擎
• 虚拟机/容器运行时
• 证据数据库
• 发现引擎
• 报告生成器
• 长时间运行的研究进程
• Codex/Goose/OpenCode 的替代品

而是：

Decretum
  = 声明式意图 -> 确定性契约

执行框架 / 智能体
  = 交互式执行环境

Store
  = 持久化执行或研究记忆

有关详细边界，请参阅 ARCHITECTURE.md、docs/execution-contract.md 和 docs/domain-model.md。

文档与项目治理

• 简介 — 问题、定位与工作流
• 架构 — 系统边界与不变量
• 执行契约 — 互操作性规范
• 领域模型 — 核心概念与领域包
• 贡献指南 — 开发与扩展规则
• 安全 — 漏洞报告
• 变更日志 — 发布历史
• 许可证 — Apache 2.0

贡献指南

在拥有语义的层级进行贡献：

• 领域模式/能力 → 稳定含义
• 提供者 → 具体实现
• 集成 → 访问面
• 配置文件 → 可复用的偏好/约束
• 发现 → 可用性证据
• 解析器/编译器 → 通用绑定与契约生成
• 执行框架/运行时 → 执行与交互
• Store → 持久化证据、产物、发现或报告

添加提供者通常应只需注册表工作，而非编译器分支。

对于新能力，在请求规范批准之前，请解释其语义并说明其与现有能力的区别。

项目结构

Decretum/
├── schema/
│   ├── capability_registry.yaml
│   ├── provider_registry.yaml
│   ├── profile_registry.yaml
│   └── sec_research_metamodel.yaml   # reference security domain
├── recipes/
├── docs/
│   └── domain-model.md
├── sec_agent/
│   ├── capability_registry.py
│   ├── capability_discovery.py
│   ├── profile_registry.py
│   ├── resolver.py
│   ├── policy.py
│   ├── compiler.py
│   ├── harness.py
│   └── replay.py
└── tests/

架构不变量

1. Decretum 是编译器/解析器，不是运行时。
2. Decretum 在生成执行契约后即停止。
3. 执行契约是互操作性边界。
4. 执行框架/智能体拥有执行与交互。
5. 持久化存储位于 Decretum 之外。
6. 新能力需求返回 Decretum 进行解析和重新编译。
7. 规范能力语义与提供者和执行框架无关。
8. 添加提供者不得要求编译器分支。
9. 发现不能静默改变规范本体。
10. 领域特定行为属于领域包，而非核心编译器逻辑。
11. 重放/验证是只读的。
12. 对于相同输入和注册表状态，编译器必须保持确定性。

在 Decretum 中定义。在执行框架中执行。在 Store 中记忆。

致谢

Decretum 建立在开源社区以及声明式模式、互操作性工具和智能体系统更广泛生态的工作之上。

特别感谢 LinkML 社区及贡献者，其模式与建模生态为 Decretum 的结构化语义方法提供了参考。

感谢那些使实验和互操作性成为可能的开源工具、标准和项目背后的维护者、贡献者和社区。

AI 辅助开发与署名

Decretum 在透明的 AI 辅助下开发。Opposum0112 是人类项目所有者、架构师、维护者和发布权威。codex 作为 AI 工程贡献者，用于架构探索、实现、重构、调试、测试指导、文档和仓库维护。

AI 辅助不会将项目所有权或发布权威转移给 AI 系统。人工审查和验收仍是项目工作流的一部分。

有关署名政策和 GitHub 署名详情，请参阅 CONTRIBUTORS.md 和 AI_ASSISTANCE.md。

联系方式

如有一般项目问题或错误报告，可通过 [email protected] 联系维护者。请勿通过电子邮件发送密码、API 密钥、凭据、私人数据或未公开的安全漏洞；漏洞请使用安全报告流程。