# @agent-teams/docs-protocol 中文文档

规范地址：https://npmcn.com/package/%40agent-teams/docs-protocol/

版本：0\.6\.6
npm 元数据更新时间：2026-10-25T11:32:26.703Z
中文译文更新时间：2026-11-05T22:41:06.808Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agent-teams/docs-protocol
原文对照：https://npmcn.com/package/%40agent-teams/docs-protocol/?lang=original
项目主页：https://github.com/agent-teams-ai/engineering-foundation#readme
源码仓库：https://github.com/agent-teams-ai/engineering-foundation

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：844 kB，357 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^24\.18\.0 \|\| ^26\.0\.0
- 运行依赖：6 个
- 首次发布：2026-08-15T17:14:28.995Z
- 最新版本发布：2026-10-25T11:32:26.270Z
- 近 30 天下载量：11170（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：32（近 12 个月 32 个）

## 中文简介

任意寄存器的决定性文档作者和代理文本协议 .

## 安装

```sh
npm install @agent-teams/docs-protocol
```

也可以使用：`pnpm add @agent-teams/docs-protocol`、`yarn add @agent-teams/docs-protocol`、`bun add @agent-teams/docs-protocol`

## README

# `@agent-teams/docs-protocol`

用于人类的确定性、存储-内存文献库和CLI 和编码代理。 它让Markdown/YAML作为权威,提供安全 仅创建作者、 咨询模糊搜索, 范围 `llms.txt` 上下文和a 不需要代理团队管理的寄存器的便携式设置.

包是直接依赖之上的便携式应用层 `@agent-teams/document-authoring` 财务报告和审定财务报表 `@agent-teams/repository-mutation`编辑 可选只读 MCP 传输单独发布为 `@agent-teams/docs-protocol-mcp`。 。 。 .

## 边界

-   文件作者拥有作者合同,目录,计划,收据, 定型编译,被保护物化,严格侧车合并.
-   存储器突变拥有操作屏障,日记持续, file system突变安全, 和精确构建的恢复机制.
-   Docs协议拥有便携式应用程序和命令语义,共享的元数据词汇, 关系查询、代理路由和收养检查.
-   消费者拥有它只的数据配置图,元数据计划,所有者,模板, 明确可达性,以及不透明的语义验证器ID.

配置文件不能包含命令、钩子、召回、动态导入、远程 参考文献、环境插值或可执行消费者代码。 语义 校验器ID 由 `docs:info` 财务报告和审定财务报表 `docs:check`; 此软件包永远不会 执行它们.

## 便携式快速启动

使用 [警犬社区工作流程](https://github.com/agent-teams-ai/engineering-foundation/blob/main/docs/reference/open-source-docs-protocol.md#install-one-exact-version) 证明并安装精确的 文物合格坐标。 这是唯一的权威 用于版本,注册针,包管理支持,以及可选的MCP配对.

手提靴子适用,恢复最初只使用POSIX. 视窗是 具备只读CLI和MCP使用授权的能力 POSIX 主机, 已承诺, 然后被克隆; 本地 Windows 靴子陷阱突变不是 但有一个支持性索赔.

不写入预览设置 :

```bash
docs-protocol init --project-id example/widgets \
  --owner documentation/team --dry-run --json
```

审查返回的文件并摘要,然后重复相同的权威输入:

```bash
docs-protocol init --project-id example/widgets \
  --owner documentation/team --apply \
  --expect sha256:PLAN_DIGEST_FROM_PREVIEW --json
```

Bootstrap 创建惰性本地配置文件、 元数据计划、 拥有者、 Diataxis 模板和索引、文档技能和一个标记的路由 `AGENTS.md`。它不编辑显示、锁定文件、工作流程或已有的软件包 仅创建目标。 已更改的相片需要新的预览 .

生成的 `docs.config.yaml` 自动发现。 预览决定 :

```bash
docs-protocol new --type adr --id ADR-0001 --title "Portable documentation" \
  --owner documentation/team --summary "Adopt portable documentation." \
  --dry-run --json
```

审查其汇编的字节,然后应用 **新文档** 预览摘要 :

```bash
docs-protocol new --type adr --id ADR-0001 --title "Portable documentation" \
  --owner documentation/team --summary "Adopt portable documentation." \
  --apply --expect sha256:NEW_PLAN_DIGEST_FROM_PREVIEW --json
```

添加返回的内容 `markdownLink` 返回时 `indexPath`,然后核实:

```bash
docs-protocol find "portable documentation" --fuzzy --json
docs-protocol context "portable documentation" --fuzzy --max-documents 12 --json
docs-protocol check --json
```

模糊的排名和上下文是一次性建议;身份,元数据,路径, 校对:Soup 公共节点 API在没有终端的情况下曝光相同的操作.

见 [社区工作流程](https://github.com/agent-teams-ai/engineering-foundation/blob/main/docs/reference/open-source-docs-protocol.md) 完全安全契约.

## 可移植命令

在一个准确的版本安装此工具包 `devDependencies`,从不 生产 `dependencies`。便携配置文件是 `docs.config.yaml`; 覆盖 它明确与 `--profile` 并使用 `--consumer`。 。 。 .

`new` 需要准确的其中之一 `--dry-run` 或者说 `--apply`预览从不保留 身份或写作。 对经审查的应用程序,通过其 `planDigest` 作为 `--expect` (节点: `DocsNewRequest.expectedPlanDigest`) (中文(简体) ). 不正确的摘要返回 `invalid-input` (Exit 2); 不同编译的 Plan 返回 `authority-stale` (出处1). 两者 没有突变效应. `--expect` 仅使用 `--apply`明确 直接 `--apply` 无 `--expect` 汇编并应用现有权威; 它并不要求批准早先的预览。 仍然匹配摘要 需要当前的概况政策、权威、锚地和交易检查.

只应用创建计划中的文档并报告准确性 索引路径和Markdown链接;它从来不编辑索引. 每个作者请求选择文档作者的关闭 `create-missing-real-directories` 政策。 产生的 Plan v2 只能创建 其经核实的缺失母链和记录目录证据以进行回收.

```bash
agent-teams-docs find --type adr --owner architecture/tooling --related ADR-0004
agent-teams-docs new --type adr --id ADR-0083 --title "Tenant isolation" \
  --owner architecture/tooling --summary "Defines tenant isolation." \
  --blocked-by ADR-0082 --metadata evidence='["test:tenant-isolation"]' --dry-run
```

所有过滤器都与AND结合. 结果使用二进制 ID/ path 命令和 0 比赛是成功的. `related`, (中文(简体) ), `blocked_by`,以及 `code_anchors` 是马厩 v1 词汇. 重复 `--code-anchor` 一个严格的JSON值。 重复 `--metadata key=<strict JSON>` 用于补充消费者 -- -- 省略 -- -- 验证数据.

## 配置路径

可移植配置 v4 路径到文档授权配置 v3. 现有便携式 profile v3仍可读取其历史语义. 仅授权文件加载线性前题和任何已声明的元数据 侧车,执行严格的路径到全元数据合并,验证最终 ,并披露一个有界限的惰性元数据投影。 Docs 协议永远不会 复制文档 .

引用的文档授权配置文件是可编写的唯一权威 类型、身份、位置、标题、所有者、所需元数据以及明确 可达性. `not-required` (a) 需要人可读的理由 无效。 Docs协议简介只包含路由,协议身份, 代理 Skill 路由, 不透明的语义验证器 ID, 以及 v4 所需的仅数据 `relations.blockers` 政策。 内容 `types` 财务报告和审定财务报表 `statuses` 入院障碍目标; `subjectIncompatibleStatuses` 禁止封锁那些主题的状态。 启动器 v4 数据允许推荐的 ADR/ Diataxis 阻塞器; 消费者自行选择 词汇. [配置 v4 迁移](https://npmcn.com/package/%40agent-teams/docs-protocol/docs/profile-v4.md) 记录有线身份, 被冻结 v3 兼容性,可移植路径规则,迁移和回滚.

元数据 JSON Schema `format` 是注释: 文档作者用途 `validateFormats: false`它不主张URI、日期或其他格式的有效性. 在需要有效性时使用得到支持的明确计划限制. 这个 [仅限数据特性示例](https://npmcn.com/package/%40agent-teams/docs-protocol/docs/feature-module-example.md) 显示 使用现有源政策计划,消费者拥有的DDD/Clean边界.

便携式 JSON 计划导出于 `@agent-teams/docs-protocol/schemas/*`。 。 。 . 机器输出使用一个JSON信封,带有协议ID/版本并稳定退出 代码 : `0` 成功吗, `1` 违反/冲突/出售/恢复, `2` 无效输入, `3` 执行失败,以及 `130` 取消 . 人类 `--help`,子命令 `--help`,以及 `--version` 使用 stdout 并退出 0. 与 `--json`,帮助/版本返回 stdout 上一个有计划有效的引用错误, 2号出口和空出;他们的人类文本没有JSON成功合同. 通用 v1/v2 命令保留其现有的信封形状 。 可移植 `init`边框 `context`,并选择模糊 `find` 使用添加剂v3信封; 默认精确 `find` 仍为v2. 消费者必须发送 `schemaVersion` 财务报告和审定财务报表 对照匹配的导出计划验证 . 回收与持续交易和准确安装的文件有关 作者构建, 因此它不会在之前分析可变作者配置 复会. 包含历史线名 `foundation` 保持不变 合同身份不变.

## 消费者资格

`@agent-teams/docs-protocol/qualification` 出口 `runDocsProtocolQualification`消费者提供一种故意一次性的 固定和一个写作方案。 跑步者复制 固定在自己的 临时目录,然后证明信息,确定性查找,预览/应用等同, 明确可达性、检查、医生和复原结束。 它拒绝固定 并联,验证源树没有改变,只删除 它创建的临时目录 .

管理下的组群资格是有意的,不在本包中。 代理团队用户 安装 `@agent-teams/docs-protocol-agent-teams` 并使用其独特的 `agent-teams-docs-managed` 可执行文件; 便携式核心既不发现也不 导入适配器.

## 常见问题

### @agent-teams/docs-protocol 是什么？

任意寄存器的决定性文档作者和代理文本协议 \.

### 如何安装 @agent-teams/docs-protocol？

在项目目录运行 npm install @agent-teams/docs-protocol，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 docs-protocol、agent-teams-docs，可以用 npx docs-protocol 直接运行。

### @agent-teams/docs-protocol 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @agent-teams/docs-protocol 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @agent-teams/docs-protocol 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^24\.18\.0 \|\| ^26\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @agent-teams/docs-protocol 可以商用吗？

@agent-teams/docs-protocol 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @agent-teams/docs-protocol 的下载量有多少？

根据 npm 官方下载统计，@agent-teams/docs-protocol 在 2026/10/05 – 2026/11/03 这 30 天内被下载 11,170 次，日均约 372 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agent-teams/docs-protocol 还在维护吗？

最新版本 0\.6\.6 发布于 2026/10/25（13 天前）；至今共发布 32 个版本，其中过去 12 个月发布了 32 个；首次发布于 2026/08/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。