# https://github.com/andrii-su/datoon 项目说明书

生成时间：2026-07-07 23:36:00 UTC

## 目录

- [项目概述、安装与快速入门](#page-1)
- [核心转换流程与决策门控机制](#page-2)
- [多格式读取器、归一化与错误处理](#page-3)
- [插件生态、技能与社区运维要点](#page-4)

<a id='page-1'></a>

## 项目概述、安装与快速入门

### 相关页面

相关主题：[核心转换流程与决策门控机制](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/andrii-su/datoon/blob/main/README.md)
- [INSTALL.md](https://github.com/andrii-su/datoon/blob/main/INSTALL.md)
- [pyproject.toml](https://github.com/andrii-su/datoon/blob/main/pyproject.toml)
- [src/datoon/__init__.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/__init__.py)
- [src/datoon/cli.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/cli.py)
- [src/datoon/models.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/models.py)
- [src/datoon/converter.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/converter.py)
- [src/datoon/readers/__init__.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/readers/__init__.py)
</details>

# 项目概述、安装与快速入门

## 1. 项目概述

datoon 是一个面向 LLM 数据工作负载的命令行工具，主要解决将多源异构数据快速转换为大模型可用训练/推理格式的问题。仓库以 Python 包形式发布，源码位于 `src/datoon/`，并通过 `pyproject.toml` 进行构建与依赖管理 资料来源：[pyproject.toml:1-40]()。

工具的核心职责可以概括为三点：

- **多格式读取**：内置 CSV、JSONL、YAML、XML、Excel、Parquet、Avro、ORC 与 Apple Numbers 等多种格式读取器，统一暴露为 `readers` 子包入口 资料来源：[src/datoon/readers/__init__.py:1-40]()。
- **格式转换与 Token 估算**：通过 `converter` 模块将读取到的数据规整为 LLM 友好格式，并使用 `tiktoken` 进行 token 数量估算 资料来源：[src/datoon/converter.py:1-60]()。
- **MCP 集成**：自 v1.7.0 起，datoon 可作为 MCP（Model Context Protocol）服务器对外暴露，并已在 Registry、Smithery、Glama 等市场登记 资料来源：[README.md:1-80]()。

数据模型与对外暴露的公共符号集中在 `src/datoon/__init__.py` 与 `src/datoon/models.py` 中，方便被其它 Python 项目以库的形式直接调用 资料来源：[src/datoon/__init__.py:1-30]()。

## 2. 安装

datoon 通过 `pyproject.toml` 声明项目元数据与依赖，使用标准的 `pip` 或兼容工具即可完成安装 资料来源：[pyproject.toml:1-80]()。

```bash
# 从 GitHub 直接安装最新发布版本
pip install datoon

# 或安装指定版本（当前最新为 v1.9.1）
pip install datoon==1.9.1

# 从源码安装（推荐用于开发）
git clone https://github.com/andrii-su/datoon.git
cd datoon
pip install -e .
```

由于工具依赖 `tiktoken`、`pyyaml`、`pandas`、`openpyxl`、`pyarrow`、`fastavro`、`pyorc` 等可选库，部分格式（如 Avro、ORC、Numbers）需要相应的系统级依赖；具体可选依赖组在 `pyproject.toml` 中按 `extras` 提供 资料来源：[pyproject.toml:40-120]()。安装完成后可通过 `datoon --version` 验证版本，`datoon --help` 查看可用子命令 资料来源：[src/datoon/cli.py:1-40]()。

## 3. 快速入门

CLI 由 `src/datoon/cli.py` 中的入口函数组织，遵循子命令 + 选项的常见模式 资料来源：[src/datoon/cli.py:1-60]()。

### 3.1 读取与转换

下面给出几个常见用法，假设当前目录存在 `data.jsonl`、`data.csv` 等文件：

```bash
# 将 JSONL 数据转为统一的 LLM 格式并输出到 stdout
datoon convert data.jsonl --format jsonl

# 指定输出文件
datoon convert data.jsonl -o output.jsonl

# 多格式输入：读取 Excel 工作表
datoon convert report.xlsx --sheet Sheet1 -o output.jsonl

# 读取 Apple Numbers 表格
datoon convert report.numbers --table Sheet1 -o output.jsonl
```

`--sheet` 与 `--table` 参数在 v1.8.0 中加入，用于在处理 Excel 与 Numbers 输入时选择具体工作表/表格 资料来源：[README.md:40-120]()。

### 3.2 Token 数量估算

自 v1.9.0 起，token 编码默认改为 `o200k_base`，并可通过参数自定义，更贴合 GPT-4o/Claude 等当代模型的分词方式 资料来源：[src/datoon/converter.py:60-120]()。

```bash
# 使用默认编码估算 token 数
datoon tokens data.jsonl

# 指定编码
datoon tokens data.jsonl --encoding o200k_base
```

## 4. 核心能力概览

下表汇总了 datoon 当前主要能力及其首次引入的版本，便于读者快速定位能力边界。

| 能力 | 关键来源 | 引入版本 |
|---|---|---|
| 多格式读取器（CSV/JSONL/YAML/XML/Excel/Parquet/Avro/ORC/Numbers） | `src/datoon/readers/__init__.py` | v1.6.0 |
| MCP 服务器握手并报告版本 | `src/datoon/mcp` | v1.7.1 |
| 在 MCP 市场（Registry、Smithery、Glama）登记 | `README.md` | v1.7.0 |
| `--sheet` / `--table` 选项 | `src/datoon/cli.py` | v1.8.0 |
| 可配置 token 编码，默认 `o200k_base` | `src/datoon/converter.py` | v1.9.0 |

读者在使用过程中如需进一步排错，可参考已有的社区讨论，例如读取器错误类型不一致（#41）、YAML 列表项校验（#43）、`cli.py` 中 `Sequence` 导入位置（#44）等，这些讨论反映了当前边界与待改进点 资料来源：[src/datoon/readers/yaml.py:1-40]()。

至此，读者已了解 datoon 的定位、安装方式以及最常用的命令。后续可按需深入到各读取器、转换器或 MCP 集成的具体实现细节。

---

<a id='page-2'></a>

## 核心转换流程与决策门控机制

### 相关页面

相关主题：[项目概述、安装与快速入门](#page-1), [多格式读取器、归一化与错误处理](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/datoon/converter.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/converter.py)
- [src/datoon/analyzer.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/analyzer.py)
- [src/datoon/models.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/models.py)
- [src/datoon/errors.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/errors.py)
- [src/datoon/cli.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/cli.py)
- [src/datoon/mcp_server.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/mcp_server.py)
- [src/datoon/readers/__init__.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/readers/__init__.py)
- [src/datoon/readers/jsonl.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/readers/jsonl.py)
- [src/datoon/readers/yaml.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/readers/yaml.py)
- [src/datoon/readers/xml.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/readers/xml.py)
</details>

# 核心转换流程与决策门控机制

## 1. 管线总览与模块协作

`datoon` 的核心目标是把来自多种结构化来源（CSV、JSONL、YAML、XML、Excel、Parquet、Avro、ORC、Numbers）的数据，规范化为可直接送入 LLM 工作流的统一表示，并在此过程中提供可控、可审计的决策门控（gating）。整体管线由读取层、转换层、分析层与外部接口层构成，CLI 与 MCP 服务器分别承载命令行与模型上下文协议两种调用入口。

```mermaid
flowchart LR
    A[输入文件] --> B[readers/* 读取与规范化]
    B --> C[converter.py 转换]
    C --> D[analyzer.py 分析]
    D --> E{出口}
    E -->|CLI| F[cli.py]
    E -->|MCP| G[mcp_server.py]
```

读取层通过派发器按扩展名选择具体 reader；转换层负责统一结构与 token 估算；分析层提供指标；CLI 与 MCP 服务器负责把结果暴露给最终用户。资料来源：[src/datoon/readers/__init__.py:1-120]() [src/datoon/cli.py:1-200]() [src/datoon/mcp_server.py:1-200]()

## 2. 多格式读取与规范化门控

读取层在 v1.6.0 起支持九种格式，由 `readers/__init__.py` 中的派发器按文件类型分发。各类 reader 暴露统一的 `read` 契约，但内部各自维护解析与规范化策略，因此读层构成了第一道"决策门控"。

**安全性门控**：`readers/xml.py` 显式拒绝 DTD/DOCTYPE 声明以阻断 XML 实体扩展（XXE/Billion Laughs）类 DoS。资料来源：[src/datoon/readers/xml.py:1-80]()

**语义保留门控**：v1.7.2 修复了标量与行强制转换过程中破坏语义值的问题，转换器须在类型推断时保留字符串/数字/布尔/日期等语义，而不是一律转字符串。资料来源：[src/datoon/converter.py:1-150]() [src/datoon/models.py:1-100]()

**结构归一门控**：`readers/yaml.py::_normalize` 将 YAML 的 dict/list 形态归一为记录列表，但当前实现对 list 元素是否全部为对象不做校验，存在把标量混入而触发下游错误的隐患（参见社区议题 #43）。同时该函数对非预期形态直接抛出 `ValueError`。资料来源：[src/datoon/readers/yaml.py:1-60]() [src/datoon/errors.py:1-50]()

## 3. Token 估算与编码决策门控

转换层的关键决策之一是为 token 估算选择 tiktoken 编码。自 v1.9.0 起，加载逻辑由 `_load_token_encoder` 实现，编码可由配置指定，默认值已切换到 `o200k_base`（GPT-4o / o-series 风格），以贴合目标模型的真实分词方式；早期默认 `cl100k_base`（GPT-3.5/4 时代）已被替代，社区议题 #42 仍在讨论为 Claude 等非 tiktoken 模型提供更精确的估算通道。资料来源：[src/datoon/converter.py:1-200]() [src/datoon/analyzer.py:1-120]()

## 4. 错误分类与传播门控

转换过程中错误的分类是调用方决定是否重试、跳过还是中止的关键依据。当前 reader 的错误类型并不统一：

| Reader / 模块 | 抛出类型 |
| --- | --- |
| `readers/jsonl.py` | `DatoonError` |
| `readers/xml.py` / `readers/yaml.py` | `ValueError` |
| `readers/__init__.py` 派发器 | `ValueError` |

CLI 顶层目前以 `(OSError, ValueError, DatoonError)` 元组方式宽口径捕获，正是上述不统一分类的折中；社区议题 #41 提议收敛到统一的 `DatoonError` 体系，使上层可以基于异常类型做更精细的策略路由。资料来源：[src/datoon/readers/__init__.py:1-120]() [src/datoon/errors.py:1-60]() [src/datoon/cli.py:1-200]()

另一道隐式门控在 converter 内部：v1.7.3 修复了 `NaN` / `Infinity` 等非有限 JSON 常量被原样透传的问题，转换器在写回前必须拒绝这些值，防止下游 JSON 解析器（标准 JSON 不支持这些常量）出现非确定性失败。资料来源：[src/datoon/converter.py:1-200]()

## 5. 入口与协议层

CLI 通过 `--sheet` / `--table`（v1.8.0）显式选择 Excel/Numbers 文件中的具体工作表，扩展了读取层的二维结构门控；MCP 服务器则在 `initialize` 握手阶段上报当前 `datoon` 版本（v1.7.1），并自 v1.7.0 起在 Registry、Smithery、Glama 等市场上可被发现，使模型客户端可以按版本与能力协商调用入口。资料来源：[src/datoon/cli.py:1-200]() [src/datoon/mcp_server.py:1-200]()

综上，datoon 的"核心转换流程与决策门控机制"是一组围绕**读取安全、语义保真、编码一致、错误可路由**展开的多层闸门，每一层都对应一条可被配置或代码审查独立验证的契约。

---

<a id='page-3'></a>

## 多格式读取器、归一化与错误处理

### 相关页面

相关主题：[核心转换流程与决策门控机制](#page-2), [插件生态、技能与社区运维要点](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/datoon/readers/__init__.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/readers/__init__.py)
- [src/datoon/readers/csv.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/readers/csv.py)
- [src/datoon/readers/jsonl.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/readers/jsonl.py)
- [src/datoon/readers/yaml.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/readers/yaml.py)
- [src/datoon/readers/xml.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/readers/xml.py)
- [src/datoon/readers/excel.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/readers/excel.py)
- [src/datoon/cli.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/cli.py)
- [src/datoon/errors.py](https://github.com/andrii-su/datoon/blob/main/src/datoon/errors.py)
</details>

# 多格式读取器、归一化与错误处理

## 概述

datoon 的 `readers` 子包为 LLM 数据准备场景提供了一套统一的多格式输入适配层。它在 v1.6.0 中以「add multi-format readers」特性引入，覆盖 CSV、JSONL、YAML、XML、Excel、Parquet、Avro、ORC 与 Numbers 等格式 资料来源：[releases/v1.6.0](https://github.com/andrii-su/datoon/releases/tag/v1.6.0)。所有读取器对外暴露同一接口契约，内部各自完成「解析 → 类型推断 → 行级归一化」的流水线，最终向调用方返回 `list[dict]` 形式的记录集合，供 converter / metrics 等下游组件消费。

整套子系统的设计目标是：

- **接口一致**：以 `read(path, **opts)` 形式分派，便于上层 CLI 与 MCP 工具复用。
- **数据归一**：将不同结构（list、dict-of-list、单标量）的源文件归一为可被下游 `TokenEstimator` 处理的行式记录。
- **防御式解析**：对 XML 等高风险格式阻断 DTD / DOCTYPE，防止实体扩展型 DoS 资料来源：[releases/v1.7.4](https://github.com/andrii-su/datoon/releases/tag/v1.7.4)。

## 读取器分派与公共契约

`readers/__init__.py` 是入口分派层，它集中维护「扩展名 → 读取器模块」的映射关系并暴露统一的 `read()`。CLI 层只依赖这一个入口，因此新增格式只需在此处注册。CLI 端针对 I/O 类故障通常会捕获一个较宽的异常元组，例如 `(OSError, ValueError, DatoonError)` 资料来源：[src/datoon/cli.py]()，这意味着读取器抛出的异常类型需要在该元组覆盖范围内。

各格式读取器的职责可概括为：

| 格式 | 主要解析库 | 行为要点 |
|------|-----------|---------|
| CSV | 内置 csv | 标题行映射为字典键 |
| JSONL | json | 逐行解析、非空行校验 |
| YAML | PyYAML | 支持 list 与 dict 两种顶层结构 |
| XML | xml.etree | 拒绝 DTD/DOCTYPE，遍历子节点为记录 |
| Excel | openpyxl | 支持 `--sheet` / `--table` 选择 资料来源：[releases/v1.8.0](https://github.com/andrii-su/datoon/releases/tag/v1.8.0) |

资料来源：[src/datoon/readers/__init__.py]() [src/datoon/readers/csv.py]() [src/datoon/readers/excel.py]()。

## 归一化策略与已知缺陷

归一化是把「源文件中形态各异的结构」折叠成统一行记录的关键步骤，不同格式的实现差异较大。

### JSONL：行级强校验

JSONL 读取器逐行解析并对空行、类型不符的情况报错，错误已统一到项目级异常 `DatoonError`，便于调用方精确捕获 资料来源：[src/datoon/readers/jsonl.py]()。

### YAML：列表项未校验

`yaml.py::_normalize` 在 `isinstance(data, list)` 分支直接返回，对列表项是否为对象 (`dict`) 没有进行检查；当顶层 list 中混入标量时，下游 schema 推断会出现偏差。这是社区提出的待修缺陷 资料来源：[issue #43](https://github.com/andrii-su/datoon/issues/43)。建议在 `_normalize` 中追加 `all(isinstance(item, dict) for item in data)` 的守卫，并在失败时抛出 `DatoonError` 以与 JSONL 行为对齐。

### CSV / Excel：标量值语义保留

数值、空串与日期类标量在 coercion 阶段会被特别保留其语义类型，避免被统一转成字符串丢失精度 资料来源：[releases/v1.7.2](https://github.com/andrii-su/datoon/releases/tag/v1.7.2)。Excel 读取器需要 `--sheet` / `--table` 显式选择工作表或具名表，避免在含多表的工作簿上默认选取首张表造成误读 资料来源：[releases/v1.8.0](https://github.com/andrii-su/datoon/releases/tag/v1.8.0)。

### XML：结构性防御

XML 读取器在解析前置拒绝含有 `<!DOCTYPE>` 或 `<!ENTITY>` 声明的输入，阻断 billion-laughs / XXE 类攻击；该行为随 v1.7.4 一并发布 资料来源：[src/datoon/readers/xml.py]() [releases/v1.7.4](https://github.com/andrii-su/datoon/releases/tag/v1.7.4)。

## 错误处理与一致性

当前错误类型在各读取器之间并不统一：

| 读取器 | 抛出类型 | 备注 |
|--------|---------|------|
| `readers/jsonl.py` | `DatoonError` | 与项目异常体系一致 |
| `readers/xml.py` | `ValueError` | 内置值错误 |
| `readers/yaml.py` | `ValueError` | 仅列表项校验缺失 |
| `readers/__init__.py` | `ValueError` | 分派层兜底 |

资料来源：[issue #41](https://github.com/andrii-su/datoon/issues/41) [src/datoon/errors.py]()。

这种不一致导致 CLI 不得不通过元组异常宽匹配进行兜底。社区建议的统一方向是：让所有读取器在「输入语义不正确」时统一抛出 `DatoonError`，而把底层解析库自身抛出的 `ValueError`、`json.JSONDecodeError` 等作为 `__cause__` 链保留，便于调试与日志聚合。

```mermaid
flowchart LR
    A[CLI / MCP 调用] --> B[readers/__init__.py<br/>分派]
    B --> C1[csv.py]
    B --> C2[jsonl.py]
    B --> C3[yaml.py]
    B --> C4[xml.py]
    B --> C5[excel.py]
    C1 & C2 & C3 & C4 & C5 --> D[_normalize<br/>归一化]
    D --> E[list[dict]<br/>统一记录]
    C3 -.未校验 list 项.-> F[issue #43]
    C2 -.DatoonError.-> G[issue #41<br/>错误统一]
    C4 -.拒 DTD.-> H[v1.7.4]
```

资料来源：[src/datoon/readers/__init__.py]() [src/datoon/readers/csv.py]() [src/datoon/readers/jsonl.py]() [src/datoon/readers/yaml.py]() [src/datoon/readers/xml.py]() [src/datoon/readers/excel.py]()。

## 相关社区讨论与延伸阅读

- **#41**：错误类型统一提案，建议将 `ValueError` 收敛到 `DatoonError` 以减小异常匹配面 资料来源：[issue #41](https://github.com/andrii-su/datoon/issues/41)。
- **#43**：YAML 列表项类型校验缺失，提议增加 `_normalize` 的对象守卫 资料来源：[issue #43](https://github.com/andrii-su/datoon/issues/43)。
- **#44**：`cli.py` 中 `from typing import Sequence` 属于已弃用别名，应迁回 `collections.abc` 资料来源：[issue #44](https://github.com/andrii-su/datoon/issues/44) [src/datoon/cli.py]()。
- **v1.7.4 / v1.8.0**：分别带来 XML DTD 防护与 Excel 工作表/具名表选择能力，是当前读取器安全与可用性的关键里程碑 资料来源：[releases/v1.7.4](https://github.com/andrii-su/datoon/releases/tag/v1.7.4) [releases/v1.8.0](https://github.com/andrii-su/datoon/releases/tag/v1.8.0)。

---

<a id='page-4'></a>

## 插件生态、技能与社区运维要点

### 相关页面

相关主题：[核心转换流程与决策门控机制](#page-2), [多格式读取器、归一化与错误处理](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [.claude-plugin/marketplace.json](https://github.com/andrii-su/datoon/blob/main/.claude-plugin/marketplace.json)
- [.claude-plugin/plugin.json](https://github.com/andrii-su/datoon/blob/main/.claude-plugin/plugin.json)
- [.agents/plugins/marketplace.json](https://github.com/andrii-su/datoon/blob/main/.agents/plugins/marketplace.json)
- [plugins/datoon/.codex-plugin/plugin.json](https://github.com/andrii-su/datoon/blob/main/plugins/datoon/.codex-plugin/plugin.json)
- [plugins/datoon/skills/datoon/SKILL.md](https://github.com/andrii-su/datoon/blob/main/plugins/datoon/skills/datoon/SKILL.md)
- [skills/datoon/SKILL.md](https://github.com/andrii-su/datoon/blob/main/skills/datoon/SKILL.md)
</details>

# 插件生态、技能与社区运维要点

## 概述与生态定位

datoon 在仓库内构建了一套面向 AI 助手客户端的插件与技能生态,服务于"将结构化数据(CSV/JSONL/YAML/XML/Excel/Parquet/Avro/ORC/Numbers 等)转为 LLM 可消费格式"这一核心目标。生态层覆盖三类分发场景:Claude 客户端读取 `.claude-plugin/` 清单,Codex 客户端读取 `plugins/datoon/.codex-plugin/`,通用 Agent 客户端读取 `.agents/plugins/marketplace.json`。技能(Skills)层则通过 `plugins/datoon/skills/datoon/SKILL.md` 与顶层 `skills/datoon/SKILL.md` 两份等价副本,在不同客户端之间复用同一套提示词范式,使任意数据源输入都能被自动路由到 datoon 的转换管线。

资料来源:[plugins/datoon/skills/datoon/SKILL.md:1-30]()

## 插件清单与多渠道分发

仓库采用"一份插件逻辑、多份清单暴露"的布局,通过三套独立清单将 datoon 推送给对应生态:

| 渠道 | 清单文件 | 目标客户端 |
|------|----------|------------|
| Claude | `.claude-plugin/plugin.json` / `marketplace.json` | Claude 系列、Claude Code |
| Codex | `plugins/datoon/.codex-plugin/plugin.json` | Codex CLI 及其衍生 |
| Agents | `.agents/plugins/marketplace.json` | 通用 Agent/MCP 平台 |

资料来源:[.claude-plugin/marketplace.json:1-25]()、资料来源:[plugins/datoon/.codex-plugin/plugin.json:1-20]()

v1.5.0 提交 (`176b900`) 针对该分发链路做了加固,确保发布到 PyPI 与同步到各清单之间的版本号、入口命令、能力声明保持一致;v1.6.0 (提交 `ca8de4e`) 引入多格式读取器之后,任何订阅了 datoon 技能的客户端都能在不升级客户端的前提下立即支持新格式。

资料来源:[.claude-plugin/plugin.json:1-40]()、资料来源:[.agents/plugins/marketplace.json:1-30]()

## 技能复用与调用契约

技能文件遵循统一范式:首段声明触发条件(任意结构化数据需要送入 LLM 时调用 datoon CLI 或 MCP 服务器),随后给出参数化示例(读取路径、目标格式、分隔符、token 预算)与输出排版规范。两份 SKILL.md 属于有意冗余——分别面向"按顶层 skills 目录发现"的客户端与"按插件内 skills 目录发现"的客户端,因此使用 Codex 插件路径或顶层 skills 路径的客户都能命中同一份提示词契约。

资料来源:[skills/datoon/SKILL.md:1-50]()

社区在 #44 中指出 `cli.py` 仍从 `typing` 引入 `Sequence`(属于 ruff UP035),虽然不影响技能对外契约,但任何对 CLI 行为或参数的微调都必须同步回到技能文件,否则下游客户端会按旧示例调用,产生静默偏离。该问题在技能层表现为"参数示例必须与当前 CLI 字面对齐",因此维护节奏应与 CLI 改动保持同步。

资料来源:[plugins/datoon/skills/datoon/SKILL.md:30-60]()

## 社区运维要点与发布节奏

v1.7.0 起 datoon 进入 MCP 生态市场分发阶段,已登记的市场包括 Registry、Smithery 与 Glama,使任意启用 MCP 的助手都能在握手阶段发现 datoon 服务器。v1.7.1 进一步要求 `initialize` 握手显式回传版本号,客户端据此做能力协商。

资料来源:[.claude-plugin/marketplace.json:10-30]()

运维侧的核心责任集中在三点:

1. **版本同步**:每次 release 之后,三份清单(`.claude-plugin/`、`plugins/datoon/.codex-plugin/`、`.agents/plugins/marketplace.json`)中的版本字段必须随之回写,否则下游市场会出现"插件已升级但入口仍是旧版本"的错位。
2. **错误分类收敛**:#41 指出 reader 之间异常类型不一致(`jsonl` 抛 `DatoonError`,`xml`/`yaml` 抛 `ValueError`,分发器抛 `ValueError`),上层(包括 MCP 服务器与技能调用方)只能靠捕获宽泛元组来兜底。统一为 `DatoonError` 之前需先梳理异常层级,避免破坏既有契约。
3. **不可信输入防护**:#43 反映 YAML `_normalize` 未校验列表项,#38 通过拒绝 DTD/DOCTYPE 缓解 XML 实体扩展 DoS,#37 拒绝非有限 JSON 常量——这三类加固共同表明,经技能触发进入 datoon 的输入默认按"不可信"处理,运维需关注新格式 reader 是否同样遵循该原则。

资料来源:[.claude-plugin/plugin.json:30-60]()

结合 v1.9.x 补丁节奏——`#46` 将 token 编码默认改为 `o200k_base` 并设为可配置(直接响应 #42)、`#47` 调整 README 表格以兼容 mdformat——社区运维可借助上述清单做变更影响面分类:清单内变更需要重新打包并触发市场审核,转换器内部变更只需随 PyPI 发布即可。

资料来源:[.agents/plugins/marketplace.json:15-40]()

---

**维护提示**

- 升级前先跑 `pytest` 与基准测试,确认 CLI 参数未变之后再回写三份清单。
- 任何 reader 新增格式,都需要在两份 SKILL.md 中补充触发示例,保持调用契约一致。
- MCP 市场(RG/SM/GL)的 `initialize` 版本号必须随 release 一并刷新,避免能力协商退回旧实现。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：andrii-su/datoon

摘要：发现 25 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

## 1. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/andrii-su/datoon | host_targets=mcp_host, claude_code, claude

## 2. 配置坑 · 失败模式：configuration: Token estimate uses cl100k_base, not the tokenizer of target models

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Token estimate uses cl100k_base, not the tokenizer of target models
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Token estimate uses cl100k_base, not the tokenizer of target models
- 证据：failure_mode_cluster:github_issue | https://github.com/andrii-su/datoon/issues/42 | Token estimate uses cl100k_base, not the tokenizer of target models

## 3. 配置坑 · 失败模式：configuration: v1.9.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.9.0
- 对用户的影响：Upgrade or migration may change expected behavior: v1.9.0
- 证据：failure_mode_cluster:github_release | https://github.com/andrii-su/datoon/releases/tag/v1.9.0 | v1.9.0

## 4. 配置坑 · 来源证据：Unify reader error taxonomy (ValueError vs DatoonError)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Unify reader error taxonomy (ValueError vs DatoonError)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/andrii-su/datoon/issues/41 | 来源类型 github_issue 暴露的待验证使用条件。

## 5. 配置坑 · 来源证据：YAML reader does not validate that list items are objects

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：YAML reader does not validate that list items are objects
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/andrii-su/datoon/issues/43 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 6. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/andrii-su/datoon | README/documentation is current enough for a first validation pass.

## 7. 维护坑 · 失败模式：migration: cli.py imports Sequence from typing (deprecated alias)

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: cli.py imports Sequence from typing (deprecated alias)
- 对用户的影响：Developers may hit a documented source-backed failure mode: cli.py imports Sequence from typing (deprecated alias)
- 证据：failure_mode_cluster:github_issue | https://github.com/andrii-su/datoon/issues/44 | cli.py imports Sequence from typing (deprecated alias)

## 8. 维护坑 · 来源证据：cli.py imports Sequence from typing (deprecated alias)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：cli.py imports Sequence from typing (deprecated alias)
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/andrii-su/datoon/issues/44 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 9. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/andrii-su/datoon | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/andrii-su/datoon | no_demo; severity=medium

## 11. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/andrii-su/datoon | no_demo; severity=medium

## 12. 安全/权限坑 · 来源证据：Token estimate uses cl100k_base, not the tokenizer of target models

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Token estimate uses cl100k_base, not the tokenizer of target models
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/andrii-su/datoon/issues/42 | 来源类型 github_issue 暴露的待验证使用条件。

## 13. 能力坑 · 失败模式：capability: YAML reader does not validate that list items are objects

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: YAML reader does not validate that list items are objects
- 对用户的影响：Developers may hit a documented source-backed failure mode: YAML reader does not validate that list items are objects
- 证据：failure_mode_cluster:github_issue | https://github.com/andrii-su/datoon/issues/43 | YAML reader does not validate that list items are objects

## 14. 能力坑 · 失败模式：conceptual: Unify reader error taxonomy (ValueError vs DatoonError)

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this conceptual risk before relying on the project: Unify reader error taxonomy (ValueError vs DatoonError)
- 对用户的影响：Developers may hit a documented source-backed failure mode: Unify reader error taxonomy (ValueError vs DatoonError)
- 证据：failure_mode_cluster:github_issue | https://github.com/andrii-su/datoon/issues/41 | Unify reader error taxonomy (ValueError vs DatoonError)

## 15. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/andrii-su/datoon | issue_or_pr_quality=unknown

## 16. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/andrii-su/datoon | release_recency=unknown

## 17. 维护坑 · 失败模式：maintenance: v1.5.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.5.0
- 对用户的影响：Upgrade or migration may change expected behavior: v1.5.0
- 证据：failure_mode_cluster:github_release | https://github.com/andrii-su/datoon/releases/tag/v1.5.0 | v1.5.0

## 18. 维护坑 · 失败模式：maintenance: v1.6.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.6.0
- 对用户的影响：Upgrade or migration may change expected behavior: v1.6.0
- 证据：failure_mode_cluster:github_release | https://github.com/andrii-su/datoon/releases/tag/v1.6.0 | v1.6.0

## 19. 维护坑 · 失败模式：maintenance: v1.7.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.7.0
- 对用户的影响：Upgrade or migration may change expected behavior: v1.7.0
- 证据：failure_mode_cluster:github_release | https://github.com/andrii-su/datoon/releases/tag/v1.7.0 | v1.7.0

## 20. 维护坑 · 失败模式：maintenance: v1.7.1

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.7.1
- 对用户的影响：Upgrade or migration may change expected behavior: v1.7.1
- 证据：failure_mode_cluster:github_release | https://github.com/andrii-su/datoon/releases/tag/v1.7.1 | v1.7.1

## 21. 维护坑 · 失败模式：maintenance: v1.7.2

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.7.2
- 对用户的影响：Upgrade or migration may change expected behavior: v1.7.2
- 证据：failure_mode_cluster:github_release | https://github.com/andrii-su/datoon/releases/tag/v1.7.2 | v1.7.2

## 22. 维护坑 · 失败模式：maintenance: v1.7.3

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.7.3
- 对用户的影响：Upgrade or migration may change expected behavior: v1.7.3
- 证据：failure_mode_cluster:github_release | https://github.com/andrii-su/datoon/releases/tag/v1.7.3 | v1.7.3

## 23. 维护坑 · 失败模式：maintenance: v1.7.4

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.7.4
- 对用户的影响：Upgrade or migration may change expected behavior: v1.7.4
- 证据：failure_mode_cluster:github_release | https://github.com/andrii-su/datoon/releases/tag/v1.7.4 | v1.7.4

## 24. 维护坑 · 失败模式：maintenance: v1.8.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.8.0
- 对用户的影响：Upgrade or migration may change expected behavior: v1.8.0
- 证据：failure_mode_cluster:github_release | https://github.com/andrii-su/datoon/releases/tag/v1.8.0 | v1.8.0

## 25. 维护坑 · 失败模式：maintenance: v1.9.1

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.9.1
- 对用户的影响：Upgrade or migration may change expected behavior: v1.9.1
- 证据：failure_mode_cluster:github_release | https://github.com/andrii-su/datoon/releases/tag/v1.9.1 | v1.9.1

<!-- canonical_name: andrii-su/datoon; human_manual_source: deepwiki_human_wiki -->