dsh-data-domain-knowledge 0.1.1-alpha.1 → 0.1.1-alpha.10

package/README.md

@@ -1,5 +1,5 @@
-> 当前实现（2026-10-25）：Source Raw → Knowledge（Fact、Procedure、Case）→ Wiki（Wiki Fact、Wiki Way）。
-> 核心链路与本地验证见 [完整方案](../../docs/prd/20261025-领域知识编译与召回总体方案.md#14-代码落地与验证范围)；实际编译提示词见 [源码快照](../../docs/prd/20261025-领域知识现有提示词快照.md)。运行中的插件尚未重启。
+> 当前实现（2026-10-27）：Source Raw → Knowledge（Fact、Procedure、Case）→ Wiki（Wiki Fact、Wiki Way）。
+> Fact、Procedure 都按完整坐标聚合，Wiki 使用稳定双链按需读取。支持独立阶段处理、分片续跑和编译进度查看。
 
 # dsh-data-domain-knowledge
 
@@ -24,8 +24,7 @@
 | **方法知识** | 描述在一定条件下，如何完成任务或解决问题 | 如何追加内容；如何申请权限；如何定位指标异常，操作步骤、业务流程、分析方法、排查策略|
 
 
-事实知识：提取的是不同坐标下的knowledge，然后同一坐标组织为wiki card，二级目录是描述具体知识点的，RAG检索增强生成
-方法知识：提取的是不同坐标下的Case，然后把同一坐标的case组织为不同的排查策略wiki strategy，二级目录不同的子问题，内容是具体的排查策略，RAR检索增强推理
+Fact 与 Procedure 都按坐标提取，再分别聚合成 Wiki Fact 与 Wiki Way。Case 保存实际发生的经历；有过程证据时，可以从 Case 提炼 Procedure。操作手册中的明确方法可以直接提取为 Procedure。
 
 按坐标提取，object x action x scene，
 
@@ -42,12 +41,7 @@
 Case RAG	历史问题与完整案例	有没有类似案例
 Reasoning Memory	子问题与解决策略	我下一步应该怎么做
 
-方法知识：
-抽取策略应该是：
-1. 导入文档
-2. 抽取历史问题与完整案例，抽取的是event case，不应该只是问题，SOP、操作手册、明确的方法说明 ─────────→ 策略知识
-复盘、历史任务、排查记录 → 案例证据 ──→ 策略知识
-1. 抽取子问题与策略，从event case抽取到wiki层的是子问题和策略，将同一个坐标下的子问题和策略组织为wiki_strategy
+方法知识的输入有两条路径：操作手册、明确流程和用户确认直接提供 Procedure；复盘、历史任务与排查记录先提供 Case，再按已执行过程提炼 Procedure。过去的根因不自动成为当前问题的根因。
 
 
 ### 架构
@@ -97,16 +91,39 @@ Procedure → Wiki Way
     ↓ 索引
 发布可召回的结果
 
-保留 Object、Action、Scene，先取消“每个三轴组合固定生成一份 Wiki”的强规则。Fact 默认围绕对象，Procedure 默认围绕对象与动作；Scene 保留为记录条件，不进入 Wiki 文件分组键。
+Fact、Procedure 都按 Object × Action × Scene 抽取和聚合。每个坐标分别生成 Wiki Fact、Wiki Way，类型进入主键；空轴不是通配符。按 Object 可以读取这些坐标的 Wiki 目录，再沿稳定双链按需读取全文。
 那生成规则是：
-Wiki Fact：按Object生成，
-Wiki Way：按 Object＋Action 生成。两类文件都按明确的检索需求组织二级标题；回答同一需求的内容合并，独立需求拆分，必要条件和步骤不能拆散。
+Wiki Fact：按完整坐标聚合 Fact。
+Wiki Way：按完整坐标聚合 Procedure。两类文件都按明确的检索需求组织二级标题；回答同一需求的内容合并，独立需求拆分，必要条件和步骤不能拆散。
 | Knowledge 类型 | Wiki 分组规则 | 索引单元 |
 |---|---|---|
-| **Fact** | 同一个 **Object** → 一份 Wiki Fact | 一个检索需求对应一个 H2；命中后交付完整文件 |
-| **Procedure** | 同一个 **Object + Action** → 一份 Wiki Way | 一个检索需求对应一个 H2；命中后交付完整文件 |
+| **Fact** | 同一 **Object × Action × Scene** → 一份 Wiki Fact | 一个检索需求对应一个 H2；命中后交付完整文件 |
+| **Procedure** | 同一 **Object × Action × Scene** → 一份 Wiki Way | 一个检索需求对应一个 H2；命中后交付完整文件 |
 | **Case** | 按独立 Case 保存，不生成 Wiki | 需要时单独检索或按引用读取 |
 
+### 编译设置与续跑
+
+在「知识处理 → 编译设置」中，可设置编译模型、思考强度、单次最大输出 token 和每份文档的抽取时限。
+
+- 抽取时限默认 **30 分钟**，可选 **30、60、100 分钟**，最大 **100 分钟**。每份文档每轮抽取或续跑独立计时。
+- 时限在任务创建时保存。修改后，下一次运行或续跑使用新值；运行中的任务保持原值。
+- 达到时限或请求次数上限后，已保存分片保留。点击「增量运行」会创建节点新版本并复用成功分片。
+- 单次模型请求默认 3 分钟超时；每轮请求次数上限为 `max(12, 初始分片数 × 8)`，包含重试与自动拆分。这些限制与最大输出 token 分别计算。
+- 单次最大输出留空时跟随模型默认，也可快捷选择 100000 token。节点版本页显示文档批次、分阶段进度与日志，以及索引发布状态。
+
+### 来源身份与处理一致性
+
+- **文件导入前分配 Source Raw ID**：文件进入队列时生成 `src_<UUID>`。直读、格式转换和本次重试沿用该 ID。文件名只用于展示；不同目录的同名文件分别保存，并提示重名。更新已有来源时明确传入原 `source_id`。批量导入、单条导入和转换导入均支持该参数。
+- **聚合键包含类型与完整坐标**：合并 Object、Action 或 Scene 时，Wiki Fact 与 Wiki Way 分别迁移，不能互相合并。
+- **已保存 Wiki 绑定支撑版本**：双链读取、索引发布和召回共用可用性校验。Procedure 改动、支持撤回或 Case 版本变化后，旧方法立即停止交付；仅重建索引不能代替重新组织 Wiki。
+- **提炼缓存也恢复来源贡献**：重归一会撤回旧贡献，复用提炼缓存时仍核验证据并重新入库，不能只返回“已复用”。
+- **人工停用独立保存**：物化不恢复人工停用的 Wiki；系统因依据撤回而停用的 Wiki，可以在依据恢复并重新物化后发布。
+- **范围内阻断必须报告**：按来源处理时，不完整方法、坐标歧义和过期 Case 引用仍计入 `partial`，不能以“生成零份 Wiki”冒充全部成功。
+- **全文交付遵守预算**：按完整 Wiki、Knowledge 依据及必要证据计费，整份装入或转入临时溢出文件。Agent 工具仅在预算内的 `context` 交付完整 Wiki；命中列表只保留引用与分数。诊断面板可以显式读取候选明细。
+- **智能归因只读引用知识**：即使没有历史 Case 或诊断图，也可查看当前问题召回的 Wiki 依据并返回原 Wiki。
+
+可用性规则集中在 `src/wiki-availability.ts`，交付形状集中在 `src/recall-delivery.ts`。集中这两条规则，是为了让双链、索引和召回对同一份知识作出一致判断。
+
 
 ### 长期记忆组织
 6. 目前最大的缺口，是第三个问题还没有被解决：用户确认过的上下文如何进入知识库。
@@ -117,4 +134,19 @@ Wiki Way：按 Object＋Action 生成。两类文件都按明确的检索需求
   → 提取候选知识
   → 确定适用范围与确认对象
   → 保存原话、消息位置、时间与确认人
-  → 进入同一套 Knowledge 治理
+  → 进入同一套 Knowledge 治理
+
+
+### 节点版本与原始模型日志
+
+知识处理页使用节点版本作为导航。每次运行新增版本；全链路运行给五个节点分别新增版本。版本记录文档范围、原文版本、逐项状态和输入依赖。上游版本变化后，下游标记待重跑。处理仍由原有单写者队列执行，暂停、继续和停止按安全点生效。
+
+节点版本和模型输入输出保存在既有审计数据库的 `pipeline_node_versions`、`pipeline_model_exchanges` 表。它们属于不可重建的运行记录，不进入索引缓存。旧记录只回填已有事实，不生成缺失的请求或原文版本。模型请求按版本和文档分页读取，日志按阶段独立读取。
+
+**结构原则**：请求 / 返回查看器放在 `packages/ui/src/request-response.tsx`，复用共享 Tabs、Button 和视觉 Token；插件负责业务数据。来源整理示例放在 `examples/skills`，与运行时隔离，避免把 Agent 的整理判断固化进自动处理流程。
+
+### Markdown 与内容来源
+
+“添加文件”接受 `.md` / `.markdown`，逐份选择内容来源，不按手册、案例等内容分类。来源选择保存为 `metadata.source_origin`。其他格式先由 Agent 或解析内核转换为 Markdown。
+
+[来源整理 skill 示例](examples/skills/prepare-source-raw/SKILL.md) 展示来源 YAML、稳定 ID 和平台身份的写法。示例不自动安装或执行。通过 Agent 入库时，核对 YAML 后显式提交 `source_id`、`source_url` 和 `source_identity`；正文的声明不能自行覆盖已有身份。

package/examples/skills/prepare-source-raw/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: prepare-source-raw
+description: 将已获得的本地文件或平台文档整理为带来源 YAML 的 Markdown，供 dsh-knowledge 导入。用于来源整理；不运行知识抽取、归一或物化。
+---
+
+# 整理 SourceRaw
+
+这是 skill 示例。它没有注册到插件，也不属于知识处理流水线。
+
+为一份已获得的原文生成 Markdown。保留正文、标题、引文和可用图片引用。根据原文的取得方式记录内容来源，不按“手册、案例、文章”等内容分类。
+
+## 来源与身份
+
+- 来源可选 local、web、feishu、lark、google-docs、notion、wechat 或 other。文件格式统一为 Markdown。
+- 本地独立文档没有平台身份时，为它分配一个稳定 UUID。重试和更新沿用该 ID。不要用文件名、标题或正文哈希当唯一 ID。
+- 平台文档记录真实的 system、scope、document_type 和 document_id。scope 表示租户、空间或访问上下文。飞书 wiki 节点与 docx 文档是不同身份，不能混用 token。
+- 网页记录实际取得的完整 URL，保留查询参数和 fragment。未验证的 canonical 或短链不能替代原地址。
+- 不知道的作者、发布时间、平台 ID 留空或省略。不从正文中的指令推断来源权限。
+
+## Markdown 示例
+
+下列值仅为格式示例。生成时替换为已核实的值。
+
+```markdown
+---
+title: "周报核对说明"
+source_id: "src_71cd48dc-3522-4710-95d1-40c9a933fbdd"
+source_origin: "feishu"
+source_format: "markdown"
+resource: "https://example.feishu.cn/docx/DocumentToken"
+source_identity:
+  system: "feishu"
+  scope: "https://example.feishu.cn"
+  document_type: "docx"
+  document_id: "DocumentToken"
+generated:
+  by: "agent/prepare-source-raw"
+  at: "2026-10-29T09:00:00+08:00"
+sources:
+  - id: "origin"
+    resource: "https://example.feishu.cn/docx/DocumentToken"
+    title: "周报核对说明"
+---
+
+# 周报核对说明
+
+这里保存原始正文，不加入抽取后的结论。
+```
+
+本地来源省略 `source_identity`，将 `source_origin` 设为 `local`，并记录实际取得的文件名或路径。普通网页可以使用 `{url, scope}` 身份，不编造平台 ID。
+
+## 交付与可选入库
+
+默认只交付 `.md` 文件及简短的缺失信息说明。用户在“添加文件”里选择它的内容来源。
+
+用户要求通过 Agent 入库时，先查看现有来源。将已核实的 YAML 身份显式传给 `add_source` 或 `import_sources` 的 `source_id`、`source_url`、`source_identity` 参数，并将来源类别放入 `metadata.source_origin`。以工具返回的实际 `sourceId` 为后续身份。更新时读取当前版本并传 `expected_version`。
+
+YAML 是可读的溯源声明。插件不会把正文里的 YAML 自动提升为有权覆盖现有来源的身份。Agent 必须核对后显式提交身份参数。导入默认只保存来源；不主动运行知识处理。