@ danxbot/ docs
用于PLN-12文档系统的可知性文件包。 没有 此软件包是 danxbot (R-1) 的特异性: 任何 repo 都可以采用并存储其 文档作为输入的节点文件,每个节点一个文件.
医生是做什么的(schema v3)
医生解释一个系统做什么和为什么,用字来说,一个非工程师可以 随从:它的部位,人们所询问的事物 发生,他们背后的规则和决定, 如何管理事物的地方. 然后他们指向工程师 地点 看着 他们从不绘制个人地图 分类、API路线、计划或代码合同——将文件与 代码,保证漂移,并重复代码已经说过的话(PLN-12 R-11).
节点是个实质性话题 有人会抬头看 系统,一个主要的
部分,或该部分的正部分(一个app,一个组件,一个域想)
——有全页(PLN-12 R-13). 规则、决定、警告、顺序
步骤或一组状态从来不是自己的节点: 节 页 次
属于它。 只有一个句子的节点是子弹
或在其母页内的一个部分,而不是它自己的节点—— check
在一个系统/地区/托皮克身体上执行一个50字的楼层 正好是一个文件
树又不能悄悄地装满这些薄而单发的结点.
节点文件格式
一个带 YAML 前题的节点文件被标记为下:
---
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)——响亮地失败,
没有遗产阅读器,没有版本条件逻辑).
安装
npm install @danxbot/docs
使用量
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);
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;本节为更长的解释.
代理在文档根上增加上下文 分三步走,从不读取 文件 :
tree到东方.danxbot-docs tree ./docs打印整个part_of深度2的层次(系统及其区域和专题) 压缩 YAML :id, (中文(简体) ),type, (中文(简体) ),title, (中文(简体) ),summary, (中文(简体) ),file和一个真实的children每个节点计数——足以看到系统的形状和 选择分支, 不读取任何页体 .--root <id>缩入 1个分支(从该节点中深入计算);--depth N宽或窄 走多远? 一个未知--root无法大声命名 最近的真实身份.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为了更多.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; 代理读取
与 danxbot-docs promotion-guide 而不是需要知道 内部
node_modules 这个包裹已经拆了 这个软件包是
复古的,不知道什么计划 或在哪里推
结果 —— 发送到此向导中指向一个代理人, 以提供该结果.
演示(DX-3369)
包裹上载了一个现实的例子Docs项目—— 环点虚构的
售卖活动票的服务 examples/ringlet/,与
中性测试固定装置。 它写在schema v3的颗粒: 少数
实质性领域,每个领域都有几个专题,加上指南和学习道路——
从来没有一个细节点只保留一句话。 它没有列出阶级,路线或
计划;每个区域都把工程师指向何处取景.
一个命令为它服务:
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——计划错误:缺失/无效前题,一个字段 一个已删除的节点类型, apart_of失踪在一个 非系统节点或存在于系统,alook_in命名源文件 或符号unsupported_schema_versiona 包括:schema_version除当前 1(从未自动迁移——CLAUDE.md核心原则1)unreadable_filea 包括:.md文件或根下的一个目录不能 被读取(连接符号,权限错误);它被报告,并且 其余树还负荷(DX-5597)duplicate_id一样id由多个文件声明dangling_relationa 包括:part_of或者说see_also指向未知的编号part_of_cyclea 包括:part_of周期part_of_target_typea 包括:part_of树形状的父类型 不允许(见part_of(上表)multiple_systems——在多克根中有一个以上的系统summary_too_longa 包括:summary超过200个字符的上限path_unknown_node— 一个路径步骤, 命名一个未知的节点 IDunknown_icon_name- 一个icon(节点级别或value_props条目) 这不是真的@danxbot/ui图标名称unknown_colora 包括:color(节点级别或value_props条目) 这不是一个PALETTE_KEYS调色板密钥thin_page- 50字层下的系统/地区/托皮克体是真实的 页面需要 (R- 13); 指南和路径豁免how_it_works_code_symbola 包括: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上的两个命令").