dossier

Dossier — 面向模型驱动编排的签名版、版本化 Agent Skills

面向模型驱动编排的签名版、版本化 Agent Skills 开放标准：模型读取技能并决定步骤，Dossier 则让这些技能可以安全地分享和重复使用。技能可托管在任何地方——GitHub 仓库、你自己的服务器或 Dossier 注册表——每个人安装的都是同一版本，还可以验证作者身份以及内容是否遭到篡改。 网站

快速了解 Dossier 是带有版本和签名的 Agent Skill（一个 .ds.md 文件）。 在不同机器和团队成员之间复制技能文件是可行的，直到没人知道当前运行的是哪个版本，或是谁修改了它。Dossier 为每项技能指定固定版本并添加 Ed25519 签名，让每个人安装的内容保持一致，并可以验证作者身份及内容是否遭到篡改。 与 npm 包类似，Dossier 无论托管在哪里都能使用：格式本身包含版本和签名，因此从 GitHub 获取的技能和从注册表安装的技能都能通过相同的验证。签名能证明完整性和来源，但无法防止提示词注入，也不能保证技能运行起来是安全的。

  ┌──────────────────────────────────────────────────────────────────────┐
  │                                                                      │
  │    Write a skill (.ds.md)   Verify integrity       AI executes       │
  │    in Markdown, then sign   with checksums &       the workflow      │
  │                             signatures             intelligently     │
  │                                                                      │
  │    ┌──────────┐    sign     ┌──────────┐   run     ┌──────────┐     │
  │    │  Author  │ ─────────> │  Verify  │ ────────> │ AI Agent │     │
  │    └──────────┘            └──────────┘            └──────────┘     │
  │         │                       │                       │            │
  │     .ds.md file            checksum +              validated         │
  │     with JSON              signature               results with     │
  │     frontmatter            verification            evidence         │
  │                                                                      │
  └──────────────────────────────────────────────────────────────────────┘

刚来？ → 5 分钟快速入门 | 正在使用 Claude Code？ → 60 秒了解 MCP | 想现在试试？ → 30 秒开始使用

概览

flowchart LR
    A["📝 Create\n.ds.md file"] --> B["🔏 Sign\nchecksum +\nsignature"]
    B --> C["✅ Verify\nintegrity &\nauthenticity"]
    C --> D["🤖 Execute\nAI runs the\nworkflow"]
    D --> E["📋 Validate\nsuccess criteria\n& evidence"]

    style A fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
    style B fill:#fce4ec,stroke:#c62828,color:#b71c1c
    style C fill:#fff3e0,stroke:#ef6c00,color:#e65100
    style D fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    style E fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c

是什么：任何 AI Agent 都能运行的技能（.ds.md 文件）——已签名、已版本化，可跨工具移植 为什么：普通技能只存在于某个工具中，任何人都能篡改；Dossier 则让同一技能可验证并固定版本 完整性：内置校验和、加密签名和 CLI 验证工具 兼容：Claude、ChatGPT、Cursor 以及任何大模型——不受供应商锁定 兼容 Agent Skills / SKILL.md：Dossier 是构建于 Agent Skills 之上的一层，而非竞争格式。它添加签名和版本管理，并通过 ai-dossier install-skill 和 ai-dossier skill-export 导入和导出技能。

状态：协议 v1.0（稳定规范）| CLI v0.14.0 | 15+ 个示例技能 | 持续开发中

文件约定：Dossier 使用 .ds.md（不可变指令）和 .dsw.md（可变工作文件）。已签名的 Dossier 在 Agent Skills 布局中使用标准的 --- YAML frontmatter，因此每个 Dossier 也是有效的技能；手动编写的 Dossier 可以使用易读的 ---dossier JSON 布局，再由 ai-dossier sign 转换。了解详情

工作原理：模型驱动的编排

在模型驱动的编排中，由模型决定步骤、工具调用、重试，以及何时完成工作。手写的 DAG 不会这样做。Dossier 让这种方式可以安全地共享和重复使用。每项技能都经过签名并固定版本。多步骤运行由确定性调度器负责，而该调度器绝不会调用大模型。

模型驱动的方法由 AWS Strands Agents 推广。Dossier 在此基础上增加了签名、版本管理和确定性外壳。

Dossier 将此称为混合模型驱动的编排：每项技能内部由模型驱动，外部则由确定性机制负责。请阅读模型驱动的编排中的完整说明。

开始使用

1. 运行一个 dossier — 无需安装

选择你已有的任意 LLM，然后粘贴以下内容：

Analyze my project using the dossier at:
https://raw.githubusercontent.com/imboard-ai/ai-dossier/main/examples/guides/context-engineering-best-practices.ds.md

就是这样。LLM 会读取 dossier 并遵循其中的指令，无需任何工具。

想先验证它吗？

npx @ai-dossier/cli verify https://raw.githubusercontent.com/imboard-ai/ai-dossier/main/examples/guides/context-engineering-best-practices.ds.md

2. 将 MCP 服务添加到 Claude Code

只需一条命令，就能让 Claude Code 原生支持 dossier——发现、验证和执行 dossier，无需复制粘贴 URL：

claude mcp add dossier --scope user -- npx @ai-dossier/mcp-server

然后询问 Claude："列出可用的 dossier" 或 "运行 scaffold-typescript-project dossier"。

/plugin marketplace add imboard-ai/ai-dossier
/plugin install dossier-mcp-server@ai-dossier

{
  "mcpServers": {
    "dossier": {
      "command": "npx",
      "args": ["-y", "@ai-dossier/mcp-server"]
    }
  }
}

3. 创建自己的 dossier

在项目中初始化 dossier（设置 ~/.dossier/、钩子和 MCP 配置）：

npx @ai-dossier/cli init

然后创建一个 dossier：

npx @ai-dossier/cli create my-workflow

此命令会生成一个可供编辑的 .ds.md 文件。dossier 只是顶部带有元数据块的 Markdown，你可以用 JSON 格式编写：

---dossier
{
  "title": "My Workflow",
  "version": "1.0.0",
  "protocol_version": "1.0",
  "status": "draft",
  "objective": "Describe what this automates",
  "risk_level": "low"
}
---

# My Workflow

## Actions
1. Step one — what to do
2. Step two — what to verify

## Validation
- Expected outcome was achieved

签名时，ai-dossier sign 会将标头重写为标准的 --- YAML，并采用 Agent Skills 布局（顶部为 name 和 description，其他字段则放在 metadata 下，作为 dossier.* 字符串），并添加涵盖该文件的签名。签名后的文件可通过 skills-ref validate 验证，并可原样安装到 Claude Code。完整演示请参阅符合规范结构的 Dossier。

完整规范请参阅编写指南，或浏览 Dossier 注册表查看真实示例。

为什么使用 Dossier？

“这不就是一种技能吗？” 没错，dossier 就是 一种技能。不同之处在于，普通技能（例如 Claude Code 的 SKILL.md）缺少以下所有功能：

触发技能连接了两者：一个精简的 SKILL.md，用于调用经过版本控制并已签名的 dossier（ai-dossier run <registry-path>）——既保留自然语言触发方式，又获得签名、版本控制和注册表分发功能。

“那 AGENTS.md 文件呢？” 用途不同：AGENTS.md 用于说明你的项目；dossier 用于自动化工作流。两者相辅相成。

架构

graph TB
    subgraph Packages["@ai-dossier packages"]
        Core["@ai-dossier/core\nParsing, verification,\nlinting, risk assessment"]
        CLI["@ai-dossier/cli\nCommand-line tool\nverify, sign, search, run"]
        MCP["@ai-dossier/mcp-server\nMCP integration for\nClaude Code & others"]
        Registry["@ai-dossier/registry\nVercel serverless API\nDiscover & publish"]
    end

    subgraph Inputs["Dossier Files"]
        DS[".ds.md\nImmutable instructions\nfrontmatter + Markdown"]
        DSW[".dsw.md\nMutable working files\nExecution state"]
    end

    subgraph Consumers["AI Agents"]
        Claude["Claude Code"]
        ChatGPT["ChatGPT"]
        Cursor["Cursor"]
        Other["Any LLM"]
    end

    DS --> Core
    DSW --> Core
    Core --> CLI
    Core --> MCP
    CLI --> Registry
    MCP --> Claude
    MCP --> ChatGPT
    MCP --> Cursor
    MCP --> Other
    CLI -->|"verify & run"| Consumers

    style Core fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
    style CLI fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    style MCP fill:#fff3e0,stroke:#ef6c00,color:#e65100
    style Registry fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
    style DS fill:#fff9c4,stroke:#f9a825,color:#f57f17
    style DSW fill:#fff9c4,stroke:#f9a825,color:#f57f17

验证流程

每个 dossier 在执行前都会经过多阶段安全流程：

flowchart TD
    Start(["dossier verify file.ds.md"]) --> Parse["Parse frontmatter\n+ Markdown body"]
    Parse --> Checksum{"Checksum\nverification"}

    Checksum -->|"SHA-256 match"| SigCheck{"Signature\nverification"}
    Checksum -->|"mismatch"| Block["BLOCK execution\nContent tampered"]

    SigCheck -->|"valid + trusted"| Risk["Risk assessment"]
    SigCheck -->|"valid + untrusted"| Risk
    SigCheck -->|"unsigned"| Risk
    SigCheck -->|"invalid"| Block

    Risk -->|"low"| Safe["SAFE to execute"]
    Risk -->|"medium/high"| Caution["PROCEED with caution"]
    Risk -->|"critical + unsigned"| Block

    style Start fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
    style Safe fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    style Caution fill:#fff3e0,stroke:#ef6c00,color:#e65100
    style Block fill:#ffebee,stroke:#c62828,color:#b71c1c
    style Checksum fill:#f5f5f5,stroke:#616161,color:#212121
    style SigCheck fill:#f5f5f5,stroke:#616161,color:#212121
    style Risk fill:#f5f5f5,stroke:#616161,color:#212121

完整系统架构请参阅 ARCHITECTURE.md。

示例

浏览 Dossier 注册表，查看完整集合，涵盖 DevOps、数据库、数据科学、安全等领域。

# Search from the CLI
npx @ai-dossier/cli search deploy

安全与验证

flowchart LR
    Author["Author"] -->|"signs"| Dossier[".ds.md"]
    Dossier -->|"distributed via"| Registry["Registry / URL"]
    Registry -->|"fetched by"| CLI["CLI / MCP"]
    CLI -->|"verifies"| Checks["Checksum\n+ Signature\n+ Risk Level"]
    Checks -->|"safe"| Execute["Execute"]
    Checks -->|"blocked"| Reject["Reject"]

    style Author fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
    style Dossier fill:#fff9c4,stroke:#f9a825,color:#f57f17
    style Checks fill:#fff3e0,stroke:#ef6c00,color:#e65100
    style Execute fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    style Reject fill:#ffebee,stroke:#c62828,color:#b71c1c

• 使用 CLI 工具（ai-dossier verify）在执行前验证校验和 / 签名
• 优先使用 MCP 模式进行沙箱化、权限受控的操作
• 外部引用声明：会获取或链接到外部 URL 的 dossier 必须在 external_references 中声明这些 URL 及其信任级别。代码检查器会标记未声明的 URL；MCP 服务的 read_dossier 工具会针对正文中发现的任何未声明外部 URL 返回 security_notices。这有助于降低未经审查的外部内容带来的传递信任风险。
• 当前保障措施和限制请参阅 SECURITY_STATUS.md

注册表与多注册表支持

CLI 支持多个注册表，便于团队和组织发现、发布和共享 dossier。

flowchart LR
    CLI["dossier CLI"] -->|"parallel query"| R1["Public Registry\ndossier-registry.vercel.app"]
    CLI -->|"parallel query"| R2["Internal Registry\ndossier.company.com"]
    CLI -->|"parallel query"| R3["Mirror Registry\nmirror.example.com"]

    R1 -->|"results"| Merge["Merge results\n(partial failure OK)"]
    R2 -->|"results"| Merge
    R3 -->|"error"| Merge

    Merge --> User["User sees\ncombined results"]

    style CLI fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
    style Merge fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    style R3 fill:#ffebee,stroke:#c62828,color:#b71c1c

• 多注册表：配置多个注册表（公共、内部、镜像），并行查询
• 强制使用 HTTPS：所有注册表 URL 都必须使用 HTTPS，以保护传输中的凭据
• 注册表级凭据：每个注册表的身份验证相互隔离——某个令牌遭到泄露，不会导致其他注册表被访问
• 项目级配置：在项目中添加 .dossierrc.json，设置团队共享的注册表配置

# Add a private registry
dossier config --add-registry internal --url https://dossier.company.com

# List configured registries
dossier config --list-registries

完整的注册表管理选项请参阅 CLI 文档。

采用者指南

• 独立开发者：将 .ds.md 粘贴到你的 LLM 中，通过 MCP 或 CLI 运行
• 开源项目维护者：添加 /dossiers，并加入一项 CI 检查，在 README 上运行 Reality Check
• 平台团队：从 init -> deploy -> rollback dossier 入手；接入密钥和扫描器

详细指南请参阅 docs/guides/adopter-playbooks.md

文档

理念

“技能告诉 Agent 要做什么；Dossier 让你能够信任它。”

Dossier 在 Agent 技能的基础上，补足了复制文件所缺少的内容：可固定的版本、可验证的签名（让你知道它由谁编写且未被修改），以及用于安装它的注册表。验证可以证明完整性和来源；但它无法防止提示词注入，也不能保证技能运行安全。

Dossier 标准提供：

• 信任：执行前验证加密签名和校验和
• 版本管理：可固定并按需升级的语义化版本
• 分发：让技能易于发现和安装的注册表
• 可移植性：适用于任何项目、任何工作流、任何大模型，不受供应商锁定
• 适应性：Agent 能理解上下文并调整行为

Dossier：面向模型驱动编排的签名版、版本化 Agent 技能 值得信任的技能。

常见问题

什么是模型驱动编排？

这是一种由模型决定步骤、工具调用、重试以及何时完成工作的编排方式，而非采用手工编码的 DAG 或状态机。AWS Strands Agents 推广了这一术语。Dossier 在模型周围增加了签名版、固定版本的技能和确定性调度器。请参阅工作原理。

如何为 Agent 技能签名？

签名版 Agent 技能始于一个 .ds.md 文件。使用 CLI 为其签名，即可添加校验和及 Ed25519 签名；之后任何人都可以在运行前验证它。请参阅5 分钟快速开始和创建你自己的 Dossier。

Dossier 与 SKILL.md 有何不同？

Dossier 是叠加在其上的一层，而非替代品。SKILL.md 是一个 Agent Skills 文件；Dossier 则是一种额外包含固定版本、签名和注册表分发的技能。ai-dossier install-skill 和 ai-dossier skill-export 可在两者之间转换技能。请参阅为什么使用 Dossier？。

验证能保证技能安全运行吗？

不能。验证可以证明完整性（技能未被修改）和来源（由谁签名）。它无法防止提示词注入，也不能保证技能运行安全。运行技能前，请先阅读并信任其作者。请参阅安全与验证。

许可证

本项目采用 GNU Affero General Public License v3.0 (AGPL-3.0) 许可。您可以自由使用、复制、修改和分发本项目，但任何修改后的版本或使用本软件的网络服务，也必须根据相同的许可证公开其源代码。

参考资料

完整的学术参考文献和行业研究列表，以及为档案方法提供支持的资料，请参阅 REFERENCES.md。