任务：知识库喂入层（kb-feeding，方向 2）

设计依据：所有者 10-24 定稿（修订 2，评审目录 kb-design-1024.md）与进度页决定 62。树苗（docs/hub-r4-tasks/kb-seedling.md，方向 1）之外的一切资料——用例、缺陷、需求/规格、构建、自由文本——都由 Circle 喂给树：Circle 实际用到什么，Hub 就按来源的 schema 把什么填进去；Circle 只补程序填不了的语义，带逐字引文；Hub 只核验、登记、写账，不问人、不调模型、不裁决矛盾。本页把 knowledge-structure@1 的结构逐项写死；实现拆分待本页审定后另列。

喂入层的位置与形状（照定稿）

挂在树苗旁，不进根摘要：喂入对象是独立内容寻址对象，只带指向树苗（和节点路径）的引用。
进入时机 = Circle 用到：运行里经 Hub 连接器读到，或上传为输入；Hub 之外读到的只有上传才算用到。不再整批生产。
运行中不问人：待办只登记在控制台；唯一的问人在 start_run（包要求版本而没给、结构也定不出时拒绝并列候选）。
冲突：结构问题按产品包声明的权威源判；语义矛盾两边都留、建 contradicts，不裁决。
伪造：一切陈述的根据必须是 Hub 自己经连接器读到并保存的原文，引文逐字核对，不存在整条拒收；闭集、命令、路径解析不出即拒；管理员撤回记录是唯一的事后纠正。

0. 总则（不许的东西）

不许关键词、词表、同义词、前缀表或自由文本正则决定身份、绑定或关联；一切匹配是结构化值的完全相等（命令串↔命令树路径按 CommandIdentity，编号↔声明语法，版本↔目录语法）。例子全部合成：平台 zx-u、版本线 10.8 起、地址只用 192.0.2.0/24。

1. 五类对象的身份、出处与字段

身份一律是内容摘要（K01 同款规范化：排序紧凑 UTF-8、身份字段不含时间戳）；文档号/节点号是出处，不是身份。10 份字节相同的脑图 = 一个对象、多条来源、多条绑定。

1.1 用例（fed-case@1）

身份：规范化的用例子树摘要。复用 cases.ts 的投影：kityminder@1 子树 → {autoid, priority, 资源, 步骤文本, 期望文本} 规范形（cases.ts caseStatement 的输入形状），摘要 = canonical JSON 的 SHA-256。autoid 缺失时身份只按内容（autoid 是字段，不是键）。
出处字段：source = { system: 'agile', document: <文档号>, element: <节点号>, revision: <平台修订>, bytes: <原件对象摘要> }；一份文档多来源就多条 source，身份不变。
程序读到即填的字段（全部来自 famx 包结构化解析，逐字段）：
- autoid、priority、resources ← 敏捷平台 meta + 脑图 JSON 节点 data（cases.ts elementDocument / 脑图解析）。
- steps[].text、expects[].text ← cases.ts.caseBody 共用读取两种布局：步骤子分支＋期望叶子，或用例节点正文分行＋期望叶子。编号、[check]、空白和原措辞保留，不另写喂入专用提取规则。
- commands ← cases-commands.ts.stepCommands 共用完整命令行和类型核验，按锁定树苗的命令目录生成 CommandIdentity。解析不出的步骤不猜、不擦除编号或标记，计入 unparsed_steps；上级标签、标题布局的纯标题和期望中的命令不补成操作命令。
- document_lines ← 敏捷目录版本层（documents.ts documentLines）。
Circle 可经回注提出的字段（每个都带逐字引文 quote = {source 对象摘要 + 选择器}）：classification（闭集：功能/反向/升级/…）、manual_link（用例↔手册章节提议，见关联规则）、relations（same_subject / contradicts / covers）、applicability（逐字段，FAMX_COMPONENTS 等闭集）、correction（对步骤/期望原文的更正建议，不改原件）。
关联规则：用例↔命令：steps 里的命令串与树苗 /commands/<词…> 路径完全相等（CommandIdentity 相等）→ 程序建（结构），核验只查锁定根里路径仍可解析。用例↔手册章节：只经核验的提议——Circle 提 manual_link，Hub 核引文在手册原件逐字存在、章节路径在锁定树苗 /manual/* 下可解析；核不过整条拒。程序不建章节关联。

1.2 缺陷（fed-defect@1）

身份：PLM 导出的规范化记录摘要（定稿：编号是出处不是身份；同编号内容变了 = 新身份、旧主张失效）。
出处：source = { system: 'plm', ticket: <编号>, revision: <导出批次>, bytes }。
程序填：id（编号）、status、affected_lines、resolved_lines、fix_builds ← PLM 结构化字段（fixed-bugs.ts 同款投影）；affected_lines 为空 → 版本”未声明”。
Circle 回注（带引文）：classification、same_subject/contradicts/covers 关系、applicability、对描述的更正建议。

1.3 需求/规格（fed-spec@1）

身份：规格文档规范化摘要（specifications.ts 的文档形状）。
出处：source = { system: 'plm-requirements' | 'manual-store', ticket | path, bytes }。
程序填：id、title、linked_builds ← PLM 构建的需求字段；文档目录行（documents.ts）。
Circle 回注（带引文）：章节↔命令提议、章节↔用例提议、applicability、更正。

1.4 构建（fed-build@1）

身份：构建站写法的完整构建名本身 + 家族/线/平台解析（naming.ts parseBuildName 的规范输出）。
出处：source = { system: 'build-site', page: <页名>, bytes }。
程序填：name、family、line、platform、built_at、released_at、tree（命令树对象摘要）、fixed_bugs（修复清单，fixed-bugs.ts）——全部来自 sync.ts 已有投影；点名构建（FAMX_PINNED_BUILDS）进喂入层照常。
Circle 回注（带引文）：applicability、构建↔缺陷 covers 提议。运行目标不产生任何绑定，只产生使用记录。

1.5 自由文本（fed-note@1）

身份：上传原件的内容摘要（工单、纪要，任何自由文本）。
出处：source = { system: 'upload', bytes }；上传原件来源类型是”声明”，只对上传者和管理员可见（B02 R[3]），不作团队知识的根据。
程序填：只有采集事实（谁、哪次运行、时刻）；不解析内容、不抽关键词。
Circle 回注（带引文）：classification（闭集 = 对象种类加工单、纪要，其余记未分类——决定 62 集成者七项）、逐字引文的段落声明、关系提议。

2. 版本绑定（version-binding@1）

一条绑定是一条主张（B01 形状）：

字段	取值
`object`	喂入对象摘要
`product`	产品线
`line`	版本线（按产品包声明的目录/名称语法解析；C07 R[9]：10.8 = 10.8.0）
`basis`	`source_structure`（来源结构）或 `declared`（人的声明）；组成依据词表加”来源结构”一档（决定 62）
`grounds`	source_structure：目录标签原文片段 + 解析语法名；declared：声明人 + 运行号（case-location 的 line 参数、回注的版本声明）
`state`	`bound` / `undeclared` / `conflict`；conflict 带 `candidates: line[]`（目录里两个版本层时两个都留）

出处只有两种：来源结构（敏捷目录版本层、PLM 影响/解决版本、构建站修复清单、手册库目录名、构建名语法——全部程序按声明语法解析，等级”观察上的规则”）和人的声明（等级”声明”）；模型读内容推断版本禁止。结构与声明冲突（目录说 10.8，某人声明 10.9）：两者都留，等级决定显示顺序，不覆盖。
继承：绑定只记直接那条；视图按产品包声明的规则展开（现规则：不晚于目标线、不早于 min_line 的用例都算，沿用 min_line），展开项标”继承自 10.8（产品包规则）”；没有声明规则的不继承。
定不出版本 → 对象进产品线不分版本范围，state = undeclared，标”版本未声明”，照常参与一切、单列计数、不进版本差；控制台每份文档一条待办（重复不再发、不推送），目录改好后下一次读到自动绑定。同一身份多版本目录 → 多条绑定，不复制。
start_run 的问人保留一处：包声明”必须有版本”而 start_run 没给、结构也定不出 → 拒绝并列候选（C07 R[3]）。

3. 使用记录、序号冻结、撤回（usage@1 / feeding-offset@1 / retraction@1）

usage@1：{object, run, line(运行目标), at}——Hub 观察到就记（事实）；不算版本绑定。凡经 Hub 读的都在（必须回）：运行里读过的对象全部出现在本次运行的喂入清单里，不是可选。
feeding-offset@1：运行开始时冻结喂入层序号（只追加日志的位置），与锁根一起记进运行；重跑按同一序号复现。回归范围、巡检、查缺、看板、追溯一律读”锁定树苗 + 冻结序号之前的喂入层”。
retraction@1：{objects[] | runs[] | entries[], by: 管理员, at, reason 一行}——追加式，被撤回条目有效条件记失效，不删、留痕；吊销令牌账号的回注进撤回待办。唯一的事后纠正，不做事前审批。

4. 视图怎么读喂入层

对象清单走视图（index / facets），get_nodes 在关联节点旁附带对象引用（像现在的 contributions）；不新增读取机制。
回归范围 / 巡检 / 查缺 / 看板 / 追溯：锁定树苗 + 冻结序号之前的喂入层；”版本未声明”单列计数、不进版本差；矛盾（contradicts）数单列；冲突（conflict）照常参与并单列。
未声明版本的对象命令照锁定版本的命令树核（封闭世界），不因未声明降级核验。

5. 读到即喂（触发点与复用）

程序投影由这些现有读取触发（复用 famx 包既有函数，不写新的解析）：

触发点	投影
start_run 绑定的期望来源读取（检查声明 `reads`，6a36255）	用例（cases.ts / cases-commands.ts / locate.ts）、缺陷（fixed-bugs.ts）按读到即填
get_nodes 按引用读原件	同上 + documents.ts（目录行 → 绑定候选）
upload_file	自由文本（fed-note@1，声明级可见性）
同步里的构建清单（含 FAMX_PINNED_BUILDS 点名构建）	fed-build@1（sync.ts 已有投影，转喂入层）

Hub 之外读到的（模型在 Circle 里自己看的）不触发；只有上传才算用到。

6. 过渡（决定 62：旧每构建根不动）

旧每构建根保留不动、不再新增用例索引；视图对旧根照旧。
新树苗路径上，视图先读喂入层；喂入层里这个版本没有任何用例时，照实报“这个版本的用例还没有被用到过”，给出口（用到即进来：下次运行读到即入层），不报错、不回退去整批生产。
knowledge-structure@1 的 schema 草案进 contracts/model.json 的路径：与 seedling@1 并列，五类对象 + version-binding + usage/feeding-offset/retraction 三记录 + 视图闭集；生成走 gen:contracts。实现前不改 contracts，本页即草案。

顺序

本页审定（所有者过目）。
contracts：knowledge-structure@1 schema + 词表”来源结构”档（gen:contracts 重生成）。
Hub：喂入层存储与读到即喂投影、核验管线、冻结序号、视图改造。
包：knowledge-contribution 承接回注；famx 包函数转喂入投影（声明已去，函数在）。
客户端：Circle 提议格式与”必须回”清单。

Hub 接线与读取边界

写入由 Knowledge.feeding 提供：observeSource、upload、prepare / appendPrepared、retract；模型提议复用回注槽的可选 feeding 字段，不新增模型调用。admit 先核验整份数组，再在同一事务追加。
五类对象、绑定、使用与撤回均放在 claim@1 的 statement.data.feeding，保留 B01 根据、依据等级、实际操作者和原始来源记录身份。规范内容另存对象库。冻结序号取记录库追加顺序（允许空洞），与根一起写入运行、上下文和结果锁；序号不写进规范对象，不进根摘要。
视图读取走 FeedingReader.cut(product, offset, principal)，原件权限逐条核对；null 只表示无运行的当前视图。旧运行缺冻结序号时给缺失事实和另开运行的出口，不回填零或最新序号。旧每构建根仍走旧视图。
产品包声明 feeding.project、normalize_line、verify_command、classifications 回调；Hub 不解析产品正文。工作流可以声明 feeding.require_version、分类闭集及 declared_line_parameter。运行目标只记使用；只有最后这个显式参数才记人的版本绑定。
JSON / KityMinder 解析器未提供可证明的原始字节范围，因此喂入引文另支持 {reference: src 引用（含解析器与选择器）, text: 逐字片段}。已有可证明字节跨度的引文格式继续支持；不猜跨度，不做文字折叠。
实际读取清单通过工具结果的 feeding_objects 返回，原件喂入缺上下文或格式失败通过 feeding_pending 给缺失事实和下一步。原件保留原权限。管理员调用 retract 追加撤回；对象、运行、条目分别核对存在性，原始记录不删不改。账号停用或存在已吊销令牌的回注只登记核对待办，不自动裁决。

读触发投影的有界执行

每份原件整体交产品包投影，最多两次整文档调用（识别后带冻结命令树重投影）；版本线按文档去重后，用现有沙箱批调用在一个进程内核对所有候选，不按用例、步骤或树苗逐个起进程。
纯投影按原件摘要、产品包摘要、原始外部身份、元数据摘要、冻结根与组成寻址缓存；并发同件合并，重读和重启复用已完成的整文档投影。权限、当次出处、版本绑定与使用记录仍分别核验登记，缓存不扩大权限，也不把不同元数据或不同组成混在一起。
start_run 输入、期望来源、检查读取及原件 get_nodes 的读触发最多等 250 毫秒；未完成即回“投影进行中”，feeding_pending 带缺失事实与下一步，feeding_objects 先列实际读取的原件摘要。后台最多 2 件、排队最多 32 件；超出明确回尚未开始，不能静默丢弃。单次沙箱最多 5 秒，不重试墙钟超时；每份文档最多 1000 条对象，超限整份拒收。
任务状态以追加记录保留。重启后缺完成回执就报未知，重读按原采集引用续做；不伪造完成，不推进运行冻结序号。元数据按连接器声明的 JSON 解析，不因其中有 root 字段就识别成脑图。

原件采集身份与多来源

新运行的来源绑定分别冻结 artifact（本次返回的原件记录）、read_manifest（读取动作）与 meta_artifact（同次元数据原件记录）。读取字节和后续检查优先沿这份绑定走；来源的内容摘要仍是对象身份，不替代采集记录身份。
生成件的业务出处取核验过的本次读取清单：清单必须确实列出该原件记录及其字节摘要，且当前读者有权读取。连接器按原件记录索引读取清单，不按全库的相同摘要反查、挑前一条或最新一条。脑图读取依赖目录树等多个外部对象，不能因此判“多个来源冲突”。
同内容可来自 agile:case、agile:mindmap 等不同读取动作：规范用例对象摘要相等，出处观察分别追加并绑定各自读取动作；不同规范内容即使文档号、节点号相同也生成新身份，旧主张按来源修订的有效条件失效，历史原件和引文不改写。
旧生成件若只记录摘要、缺读取动作身份，记来源未声明并给重新读取的出口，不猜补一条历史出处，也不以“来源不唯一”阻断原始输入读取。

resource 的用例级结构提示

fed-case@1.resource_declaration 记录模板表身份、声明状态、原始解析值的 raw_json、已声明测试类型和结构违规。闭集外字面或字段形状错误只使该用例的标签字段记 undeclared，接受标签列表留空，附一条 advisory 违规及允许精确字面的修正清单；该用例和其余用例照常入层。原始值仍参与规范内容摘要，不会把两个不同的未声明值压成同一身份。有效标签按完全相等登记，接受列表去除完全相等的重复值；原始顺序和重复值保留在 raw_json 与身份输入中。历史对象没有这个可选字段时不回填、不改原件。

失败重试与读取上下文

持久投影和完成回执只复用成功结果，均绑定实际产品包摘要；进行中任务也按包摘要区分，并冻结所用包。升包后同一原件重新投影，旧包晚到的失败或结果不覆盖新包的待办、对象及当前进度，历史记录保留。

输入原件、目录元数据、锁定命令树的读取失败统一登记本次待办，说明阶段、摘要、采集记录和读取档位；不沿用旧的函数错误。树苗命令树只从已授权根的锁定组成取对应采集记录，通过实际启用的管理员核验身份解析；服务没有预设同步管理员时不再借普通运行者去读管理侧原件，也不向运行者授予原始命令树访问权。生成件已有运行读取授权时，喂入只复用运行冻结的那条采集记录；相同字节的未绑定副本、不可读元数据及保留中的来源仍不能替代或越权读取。