# @danxbot/docs 中文文档

规范地址：https://npmcn.com/package/%40danxbot/docs/

版本：0\.1\.72
npm 元数据更新时间：2026-11-06T00:36:03.483Z
中文译文更新时间：2026-11-11T11:14:35.406Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40danxbot/docs
原文对照：https://npmcn.com/package/%40danxbot/docs/?lang=original
项目主页：https://github.com/newms87/danxbot#readme
源码仓库：https://github.com/newms87/danxbot

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

- 包体积（解压后）：2.6 MB，136 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-09-30T05:35:10.546Z
- 最新版本发布：2026-11-06T00:36:03.293Z
- 近 30 天下载量：7676（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：55（近 12 个月 55 个）

## 中文简介

Repo-agnostic docs 包 (DX-3336/DX-3337):一种已打入,已版本的节点文件格式,一个从docs根来构建内相图的加载器,以及一个已失败的粗体 `check` CLI(英语:CLI).

## 安装

```sh
npm install @danxbot/docs
```

也可以使用：`pnpm add @danxbot/docs`、`yarn add @danxbot/docs`、`bun add @danxbot/docs`

## README

# @ danxbot/ docs

用于PLN-12文档系统的可知性文件包。 没有 此软件包是 danxbot (R-1) 的特异性: 任何 repo 都可以采用并存储其 文档作为输入的节点文件,每个节点一个文件.

## 医生是做什么的(schema v3)

医生解释一个系统做什么和为什么,用字来说,一个非工程师可以 随从:它的部位,人们所询问的事物 发生,他们背后的规则和决定, 如何管理事物的地方. 然后他们指向工程师 _地点_ 看着 他们从不绘制个人地图 分类、API路线、计划或代码合同——将文件与 代码,保证漂移,并重复代码已经说过的话(PLN-12 R-11).

**节点是个实质性话题 有人会抬头看** 系统,一个主要的 部分,或该部分的正部分(一个app,一个组件,一个域想) ——有全页(PLN-12 R-13). 规则、决定、警告、顺序 步骤或一组状态从来不是自己的节点: _节_ 页 次 属于它。 只有一个句子的节点是子弹 或在其母页内的一个部分,而不是它自己的节点—— `check` 在一个系统/地区/托皮克身体上执行一个50字的楼层 正好是一个文件 树又不能悄悄地装满这些薄而单发的结点.

## 节点文件格式

一个带 YAML 前题的节点文件被标记为下:

```markdown
---
id: area.issues
type: Area
title: Issue cards
summary: Issue cards track work as it moves from an idea to finished and merged.
schema_version: 3
part_of: system.danxbot
look_in: [src/issues]
color: iris
rules:
  - Status is always derived from lifecycle timestamps, never written directly.
---

Issue cards are the unit of work danxbot hands to its agents...
```

需要的字段 : `id` (稳定,kebab/dot形式,例如:. `area.issues` 或者说 `topic.ready-at`, (中文(简体) ), `type`, (中文(简体) ), `title`, (中文(简体) ), `summary` (标题: `SUMMARY_MAX_LENGTH`, 200个字符), `schema_version` (必须是准确的) `SCHEMA_VERSION_MAX`,当前3),以及 `part_of` (单亲节点 id - 每个类型都要求 `System`,以及 **禁用内容** 打开 `System`,则 树一根.

### 节点类型

每种类型都有一个普通语言标签和一个一行解释,导出为 `NODE_TYPE_INFO` 所以每个视图都显示这些词 而不是一个赤裸的名称.

| 类型 | 显示为 | 答复 |
| --- | --- | --- |
| `System` | 系统 | 这个系统是什么,它是为了谁,它为他们做什么 |
| `Area` | 系统的一部分 | 该系统的主要部分,以及它的责任 |
| `Topic` | 专题 | 人们所问领域的真正部分——应用、组件或域概念——充分解释 |
| `Guide` | 怎么样 | 关于任务的分步指示 |
| `Path` | 学习路径 | 一种读取器的读取顺序 |

`Concept`, (中文(简体) ), `Flow`, (中文(简体) ), `Lifecycle` 财务报告和审定财务报表 `Decision` 为: **作为节点类型而去** 看到了吗 下"页"为其内容所活之处.

### `part_of` ——一个通航关系

`part_of` 是决定树上每个视图的唯一关系。 这个 是一个单个需要的scalar(从不列出),所以“确切的说,是父母一方” _形状_ 而非必须计算的规则:一个道克根有一个 `System` (根,无 `part_of`),其他每个节点都有一个 `part_of` 父,没有周期。 哪种类型可以是固定的 (单位:千美元)`PART_OF_TARGET_TYPES`:

| 一个.. | 也许 `part_of` 一个.. |
| --- | --- |
| `Area` | `System` 仅限 |
| `Topic` | a 一个 `Area`,或另一个 `Topic` |
| `Guide` | (单位:千美元) `System`,一个 `Area`,或一个 `Topic` |
| `Path` | `System` 仅限 |

A 类 `Path` 永远不是任何人的 `part_of` 亲子关系.

### `see_also` - 一个交叉链接

`see_also` 是一个其他节点 ID 的简单列表, 作为内线“ 另参见 ” 提供 页面上的文本链接——从不设环形节点,从不打出关系。 这个 替换 v2's `uses`, (中文(简体) ), `leads-to`, (中文(简体) ), `explained-by` 财务报告和审定财务报表 `step-of`。 。 。 .

### 页 次

一个页面的结构化内容是数据,而不是免费的标记下,所以应用程序可以 使每个部分具有正确的组件(序列图、状态) (图.) 以下每一节都是可选的,以及(除 `Path`, (中文(简体) ), 其唯一内容是 `steps[]`任何一项 `System`编号 :`Area`编号 :`Topic`编号 :`Guide` 可携带其中任何:

| 外地 | 形状 | 显示为 |
| --- | --- | --- |
| `why_it_matters` | 普通字符串 | 简短点名 |
| `how_it_works` | `{actor, action, target?, notes?}[]` | 序列图 |
| `states` | `{subject, states: {id, label?}[], transitions: {from, to, trigger?, guard?}[]}` | 状态图——每个 `transitions[].from`编号 :`.to` 必须命名已声明的 `states[].id` |
| `rules` | 非空字符串列表 | 规则列表 |
| `decisions` | `{choice, why, rejected?, trade_off?}[]` | 一个"为什么它是这样建造的"列表 |
| `watch_out_for` | 非空字符串列表 | 备注列表 |

### 可选字段

`see_also[]` (节点标识), `look_in[]` (发动机指向 **区域级别**(单位:千美元) 目录、软件包或服务名称——例如源文件 `src/orders/service.ts`,或诸如 `src/orders.ts#placeOrder`将被拒绝, `provenance` (单位:千美元)`{plans?, cards?, commits?}`, (中文(简体) ), `audience[]` (单位:千美元)`developer` | `operator` | `integrator` | `agent`, (中文(简体) ), `icon` (单位:千美元) `@danxbot/ui` 图标名称, `color` (输入键) `@danxbot/ui`是因为 调色板 - `PALETTE_KEYS`数字 : `iris`, (中文(简体) ), `aqua`, (中文(简体) ), `mint`, (中文(简体) ), `amber`, (中文(简体) ), `rose`, (中文(简体) ), `azure`, (中文(简体) ), `slate`) (中文(简体) ).

特定类型结构字段 : `System` 节点可以声明 `value_props[]` (单位:千美元)`{icon, title, summary, color?}`() 其本身的销售点,与 其区域; `Path` 需要节点 `steps[]` (单位:千美元)`{node, note?}`, (中文(简体) ), `node` 引用另一个节点 `id`),并没有任何页面部分。 每个 其他类型只包含上面的常见字段外加页块表.

完整的计划在代码中定义一次,在 `src/schema.ts` 这是 验证器、装载器和任何后期消费者的单一真相来源 (搜索,docs应用).

### 只读一个计划版本

旧版本没有读者,也没有自动迁移。 文件 谁 `schema_version` 并不是目前被拒绝的 `check` 带有这样一条消息的 v2 文件(与 `Concept`, (中文(简体) ), `Flow`, (中文(简体) ), `Lifecycle` 或者说 `Decision` 节点,或 `relations[]` 列表)和一个 v1 文件(与 `Component`, (中文(简体) ), `Contract`, (中文(简体) ), `Invariant` 或者说 `Domain` 节点, 代码 `anchors` 或者说 `verified_at`(中文(简体) ) 两者都必须被重写为v3节点(CLAUDE.md Core Principle 1)——响亮地失败, 没有遗产阅读器,没有版本条件逻辑).

## 安装

```bash
npm install @danxbot/docs
```

## 使用量

```ts
import { loadDocsGraph, loadDocsRoot, runChecks } from "@danxbot/docs";

// Fail-loud: throws DocsValidationError if anything is wrong.
const graph = loadDocsGraph("./docs");

// Or collect every problem yourself (this is what the CLI does):
const loadResult = loadDocsRoot("./docs");
const problems = runChecks(loadResult);
```

```bash
npx tsx src/cli.ts check ./docs                        # dev
danxbot-docs check ./docs                               # after `npm run build`
danxbot-docs search ./docs "how does X work" [--limit N]  # compact YAML, for agents
danxbot-docs tree ./docs [--root <id>] [--depth N]      # compact YAML of the part-of hierarchy, for agents
danxbot-docs show ./docs <id>                           # one node's full content, for agents
danxbot-docs serve ./docs [--port N]                    # the docs app, live (default port 4300)
danxbot-docs build ./docs ./out                         # the docs app, as a static site
danxbot-docs demo [--port N]                            # serves the bundled example project — see below
danxbot-docs promotion-guide                            # the generic "draft a changeset from a plan" protocol, for agents
```

## 代理商:树-搜索-显示(DX-3581,PLN-12架构§6)

代理人的简短指示指船舶 [`AGENTS.md`](https://npmcn.com/package/%40danxbot/docs/AGENTS.md);本节为更长的解释.

代理在文档根上增加上下文 分三步走,从不读取 文件 :

1.  **`tree`** 到东方. `danxbot-docs tree ./docs` 打印整个 `part_of` 深度2的层次(系统及其区域和专题) 压缩 YAML : `id`, (中文(简体) ), `type`, (中文(简体) ), `title`, (中文(简体) ), `summary`, (中文(简体) ), `file` 和一个真实的 `children` 每个节点计数——足以看到系统的形状和 选择分支, 不读取任何页体 . `--root <id>` 缩入 1个分支(从该节点中深入计算); `--depth N` 宽或窄 走多远? 一个未知 `--root` 无法大声命名 最近的真实身份.
2.  **`search`** 寻找. `danxbot-docs search ./docs "<query>"` (见上文) 将节点(BM25在标题、摘要和正文上排出,并倒出句号, 单词产生,一个词的奖金 一页实际上说,一个小 助推图近距离),每匹配返回一行: `id`, (中文(简体) ), `type`, (中文(简体) ), `title`, (中文(简体) ), `summary`,页面的 `file`,其大小在 `bytes` 财务报告和审定财务报表 `lines`, (中文(简体) ), 财务报告和审定财务报表 `look_in` 当页面宣布代码指针(DX-5582)时。 没有尸体和 没有祖先或相关列表:大小表示是否读取整个文件 或以切片为单位。 同样的答案来自MCP的平台 `docs_search` 对于本次检出, 其它文件根或团队 repo 托管 医生。 6个默认匹配; `--limit N` 为了更多.
3.  **`show <id>`** 读取. `danxbot-docs show ./docs <id>` 打印一个 节点是完整的:它的前题, 决定, 如何 工作, 状态, watch out for,...) 及其标记 身体,加上其祖先的连锁和直系子女——两者都缩减为: `id` + 键 `summary` 只是,从来没有扩大。 读取保留为颗粒 : `show` 所以下一步总是另一个 明确 `tree`编号 :`search`编号 :`show` 电话,不是不断增长的垃圾场 一个 未知的 id 失败, 将命名最近的真 id .

仅当 `show`是因为 `look_in` 指针对 看那里——文件本身从不命名类,路线或符号 (R-11),所以在页面内容本身内部没有可挖掘的.

## 代理人:将计划推广到文件(DX-3674)

与上文读出的一个单独的通用协议:如何转出一个 完成计划后 整个计划,阅读登陆承诺,决定创建/更新/出现/ 根据当前图表替换,并用 `check` 在此之前 承诺 它的船作为 [`PROMOTION.md`](https://npmcn.com/package/%40danxbot/docs/PROMOTION.md); 代理读取 与 `danxbot-docs promotion-guide` 而不是需要知道 内部 `node_modules` 这个包裹已经拆了 这个软件包是 复古的,不知道什么计划 或在哪里推 结果 —— 发送到此向导中指向一个代理人, 以提供该结果.

## 演示(DX-3369)

包裹上载了一个现实的例子Docs项目—— **环点**虚构的 售卖活动票的服务 `examples/ringlet/`,与 中性测试固定装置。 它写在schema v3的颗粒: 少数 实质性领域,每个领域都有几个专题,加上指南和学习道路—— 从来没有一个细节点只保留一句话。 它没有列出阶级,路线或 计划;每个区域都把工程师指向何处取景.

一个命令为它服务:

```bash
npm run demo               # dev, via tsx — reads examples/ringlet live
node dist/cli.js demo      # after `npm run build` — same, from the built CLI
```

都一样 `danxbot-docs demo [--port N]` 罩下( 默认端口) 4300个,与 `serve`)——薄薄的包裹围绕 `serve` 指向捆绑的 `examples/ringlet` 目录, 从软件包自己的安装中解析 位置而不是当前工作目录,所以它从 安装或检查软件包的任何地方.

## 文档应用`serve` 编号 : `build`(中文(简体) )

`serve` 财务报告和审定财务报表 `build` 两者都需要程序自己的资产 预建一次通过 `npm run build:app` (或 `npm run build`,它同时进行CLI和应用程序)—— 他们读 `dist/app` 而不是在苍蝇上编集任何东西. `serve` 是一个 简单 `node:http` 静态文件服务器:没有数据库,没有框架. 重读 并重建每个请求的嵌入式数据 `/`, (中文(简体) ), 因此,编辑一个节点文件会在下一个浏览器重新加载时出现,没有重启. `build` 写入一个完全静态的站点: 已建资产加一个 `index.html` 里面嵌入了docs root 的数据,可以部署到任何静态 主持人。 两者都拒绝(未响出,R-3)为无效的docs root服务/建造—— 完全一样的验证 `check` 运行.

应用程序本身:一个只关注儿童的网页(网页) `part_of` 儿童粉丝 环绕它; 交叉链接是内在的“ 另见” 文本链接, 绝不是环 节点),每个节点一页(先是零文本摘要,再是其页面部分 与匹配组件一起被制取,“在哪里查看”指针和 和搜索结果作为小可点击的图表(同 引擎 `search` (a) 使用。 真正的铬在整个——导航, `part-of` 面包屑,a 命令- palette 搜索、外观控制(主题/文本大小/相通/ —— 完全从 `@danxbot/ui`,对 电话宽度。 来源 `src/app/` (反应应用)和 `src/server/` (单位:千美元) CLI 服务/建设层;见 `src/app-data.ts` 一项合同 他们之间.

## 检查规则

`check` 退出非零并列出每个问题, 每行一个, 文件 它被发现于:

-   `schema_violation` ——计划错误:缺失/无效前题,一个字段 一个已删除的节点类型, a `part_of` 失踪在一个 非系统节点或存在于系统,a `look_in` 命名源文件 或符号
-   `unsupported_schema_version` a 包括: `schema_version` 除当前 1(从未自动迁移——CLAUDE.md核心原则1)
-   `unreadable_file` a 包括: `.md` 文件或根下的一个目录不能 被读取(连接符号,权限错误);它被报告,并且 其余树还负荷(DX-5597)
-   `duplicate_id` 一样 `id` 由多个文件声明
-   `dangling_relation` a 包括: `part_of` 或者说 `see_also` 指向未知的编号
-   `part_of_cycle` a 包括: `part_of` 周期
-   `part_of_target_type` a 包括: `part_of` 树形状的父类型 不允许(见 `part_of` (上表)
-   `multiple_systems` ——在多克根中有一个以上的系统
-   `summary_too_long` a 包括: `summary` 超过200个字符的上限
-   `path_unknown_node` — 一个路径步骤, 命名一个未知的节点 ID
-   `unknown_icon_name` - 一个 `icon` (节点级别或 `value_props` 条目) 这不是真的 `@danxbot/ui` 图标名称
-   `unknown_color` a 包括: `color` (节点级别或 `value_props` 条目) 这不是一个 `PALETTE_KEYS` 调色板密钥
-   `thin_page` - 50字层下的系统/地区/托皮克体是真实的 页面需要 (R- 13); 指南和路径豁免
-   `how_it_works_code_symbol` a 包括: `how_it_works` 写入为 代码(`name::method`, (中文(简体) ), `name()`, (中文(简体) ), `name->method`,或源文件或 file-and-symbol 形状),而不是系统中的角色(R-11);活字段 永远不扫描, 空课名留给 `PROMOTION.md`是因为 观众测试

## 测试

`tests/fixtures/valid/` 是一个小型中性示例项目(每个节点类型, 每一页, `look_in`, (中文(简体) ), `color`, (中文(简体) ), `icon` 财务报告和审定财务报表 `value_props` 每个 (至少行使一次) `check` 干净的. `tests/fixtures/invalid/` 上面每个检查规则都有一个固定目录,每个都证明这个规则 火,加上: `v1-node` 财务报告和审定财务报表 `v2-node` (两个退休计划版本都被拒绝) 同样的方式, `removed-type` (a v3 文件,使用已删除的 v3 类型), `multiple-problems-one-file` (两项规则同时在同一档案上开火),和 `look-in-file-symbol` (计划一级) `look_in` 形状拒绝). `examples/ ringlet/` (见上文"Demo")是一个单独的,大得多的项目,意在 人类浏览,而不是作为最低限度的测试固定装置,它也包含在它的范围内 自己的测试说它通过了 `check` 零问题,以及 `tree-show-ringlet.test.ts`,练习 `tree` 财务报告和审定财务报表 `show` 反对 (card AC"测试覆盖了Ringlet上的两个命令").

## 常见问题

### @danxbot/docs 是什么？

Repo-agnostic docs 包 \(DX-3336/DX-3337\):一种已打入,已版本的节点文件格式,一个从docs根来构建内相图的加载器,以及一个已失败的粗体 check CLI\(英语:CLI\)\.

### 如何安装 @danxbot/docs？

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

### @danxbot/docs 支持 TypeScript 吗？

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

### @danxbot/docs 支持 ESM 还是 CommonJS？

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

### @danxbot/docs 需要什么版本的 Node\.js？

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

### @danxbot/docs 可以商用吗？

@danxbot/docs 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @danxbot/docs 的下载量有多少？

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

### @danxbot/docs 还在维护吗？

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