From 79b5b359e7cd88bd628302046f4e05312db6fad1 Mon Sep 17 00:00:00 2001 From: wandering Date: Mon, 8 Jun 2026 12:30:22 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BD=BF=E7=94=A8=E6=A8=A1=E6=9D=BF=E6=8F=90?= =?UTF-8?q?=E7=A4=BA=E8=AF=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .llm-wiki/ingest-cache/0f2f46f5402bda30.json | 12 - .llm-wiki/ingest-cache/29489efeb95e90eb.json | 13 - README.md | 158 ++++++++++- src/analysis_system_prompt.md | 59 ++++ src/generation_system_prompt.md | 150 ++++++++++ src/ingest_cache.py | 20 +- src/llm.py | 10 +- src/main.py | 30 +- src/prompt.py | 257 +++++------------- tasks.py | 14 +- tests/test_language_rule.py | 10 +- wiki/concepts/rtu-remote-terminal-unit.md | 20 -- wiki/concepts/三遥协同机制.md | 24 -- wiki/concepts/三遥系统.md | 19 -- wiki/concepts/故障自愈逻辑.md | 27 -- wiki/entities/dtu-站所终端.md | 32 --- wiki/index.md | 32 --- wiki/log.md | 39 --- wiki/overview.md | 16 -- .../DTU/DTU（Distribution Terminal Unit）.md | 21 -- .../DTU/RTU（Remote Terminal Unit）.md | 11 - 21 files changed, 475 insertions(+), 499 deletions(-) delete mode 100644 .llm-wiki/ingest-cache/0f2f46f5402bda30.json delete mode 100644 .llm-wiki/ingest-cache/29489efeb95e90eb.json create mode 100644 src/analysis_system_prompt.md create mode 100644 src/generation_system_prompt.md delete mode 100644 wiki/concepts/rtu-remote-terminal-unit.md delete mode 100644 wiki/concepts/三遥协同机制.md delete mode 100644 wiki/concepts/三遥系统.md delete mode 100644 wiki/concepts/故障自愈逻辑.md delete mode 100644 wiki/entities/dtu-站所终端.md delete mode 100644 wiki/index.md delete mode 100644 wiki/log.md delete mode 100644 wiki/overview.md delete mode 100644 wiki/sources/DTU/DTU（Distribution Terminal Unit）.md delete mode 100644 wiki/sources/DTU/RTU（Remote Terminal Unit）.md diff --git a/.llm-wiki/ingest-cache/0f2f46f5402bda30.json b/.llm-wiki/ingest-cache/0f2f46f5402bda30.json deleted file mode 100644 index 3d5f866..0000000 --- a/.llm-wiki/ingest-cache/0f2f46f5402bda30.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "source_identity": "DTU/RTU（Remote Terminal Unit）.md", - "content_hash": "2bae7b422a2e5b4473206999912cc834155fb6c751e2798d2f64e20120fe00e8", - "files": [ - "wiki/sources/DTU/RTU（Remote Terminal Unit）.md", - "wiki/concepts/rtu-remote-terminal-unit.md", - "wiki/concepts/三遥系统.md", - "wiki/index.md", - "wiki/log.md", - "wiki/overview.md" - ] -} \ No newline at end of file diff --git a/.llm-wiki/ingest-cache/29489efeb95e90eb.json b/.llm-wiki/ingest-cache/29489efeb95e90eb.json deleted file mode 100644 index af04f41..0000000 --- a/.llm-wiki/ingest-cache/29489efeb95e90eb.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "source_identity": "DTU/DTU（Distribution Terminal Unit）.md", - "content_hash": "b9cd3e12112d95033cd225074191948cc9a41142f55f29a5ca610591802a6d38", - "files": [ - "wiki/sources/DTU/DTU（Distribution Terminal Unit）.md", - "wiki/entities/dtu-站所终端.md", - "wiki/concepts/三遥协同机制.md", - "wiki/concepts/故障自愈逻辑.md", - "wiki/index.md", - "wiki/log.md", - "wiki/overview.md" - ] -} \ No newline at end of file diff --git a/README.md b/README.md index e5c8d2e..03cd830 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,159 @@ # LLMWiki -本项目的目的是实现一个 LLMWiki 知识，能够自动的整理成双链的知识库。 +自动化的 LLM 驱动知识库生成工具。将原始文档（Markdown 文件）通过大语言模型分析，自动整理为结构化的双链知识库（Wiki）。 + +## 核心功能 + +- **两阶段智能处理**：先分析源文档生成结构化报告，再根据分析结果生成 Wiki 页面 +- **增量导入与缓存**：基于内容哈希的缓存机制，源文件未变化时自动跳过 LLM 调用 +- **OpenAI 兼容接口**：支持任何 OpenAI 兼容的 LLM 服务端（LM Studio、Ollama、vLLM 等） +- **流式传输**：使用 SSE 流式接收响应，避免长时间等待导致的连接超时 +- **自动语言检测**：根据源文档内容自动匹配输出语言 +- **结构化输出**：生成带 YAML frontmatter 的标准 Markdown 页面，支持 `[[wikilink]]` 双链引用 + +## 技术栈 + +- Python >= 3.12 +- [uv](https://github.com/astral-sh/uv) — 包管理与运行环境 +- [llama-index](https://github.com/run-llama/llama_index) — LLM 客户端 +- [ruff](https://github.com/astral-sh/ruff) — 代码检查与格式化 +- [mypy](https://github.com/python/mypy) — 静态类型检查 + +## 快速开始 + +### 1. 环境准备 + +全局安装 uv（如果尚未安装）： + +```powershell +powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" +``` + +### 2. 克隆并安装依赖 + +```bash +git clone +cd LLMWiki +python tasks.py install +``` + +### 3. 配置 LLM + +编辑 `config.json`，设置你的 LLM 服务端信息： + +```json +{ + "language": "Chinese", + "raw_dir": "raw/sources", + "wiki_dir": "wiki", + "llm": { + "model": "qwen/qwen3.6-27b", + "api_base": "http://100.123.83.113:1234/v1", + "api_key": "123456" + } +} +``` + +| 配置项 | 说明 | +|--------|------| +| `language` | 输出语言，支持 `Chinese`、`English` 或 `auto`（自动检测） | +| `raw_dir` | 源文档目录，默认 `raw/sources` | +| `wiki_dir` | Wiki 输出目录，默认 `wiki` | +| `llm.model` | LLM 模型名称 | +| `llm.api_base` | OpenAI 兼容 API 地址（需包含 `/v1` 后缀） | +| `llm.api_key` | API 密钥 | + +### 4. 准备源文档 + +将需要分析的 Markdown 文件放入 `raw/sources/` 目录下。支持按文件夹分类组织。 + +``` +raw/sources/ +├── DTU/ +│ ├── DTU－Distribution Terminal Unit.md +│ └── RTU－Remote Terminal Unit.md +└── ... +``` + +### 5. 运行 + +```bash +python tasks.py run +``` + +日志会同时输出到终端和 `llmwiki.log` 文件。 + +## 处理流程 + +``` +raw/sources/*.md + │ + ▼ +┌─────────────┐ +│ 缓存检查 │ ← 内容未变化则跳过 +└──────┬──────┘ + ▼ +┌─────────────┐ +│ Step 1 │ ← 分析源文档，生成结构化报告 +│ 分析 │ （关键实体、概念、论点、关联、建议） +└──────┬──────┘ + ▼ +┌─────────────┐ +│ Step 2 │ ← 根据分析生成 Wiki 页面 +│ 生成 │ （FILE 块 + REVIEW 块） +└──────┬──────┘ + ▼ +┌─────────────┐ +│ Step 3 │ ← 解析 FILE 块，写入 wiki/ 目录 +│ 写入 │ +└──────┬──────┘ + ▼ +┌─────────────┐ +│ Step 4 │ ← 保存缓存，下次相同内容直接命中 +│ 缓存 │ +└─────────────┘ +``` + +## 项目结构 + +``` +├── src/ +│ ├── main.py # 执行入口 +│ ├── config.py # 配置加载 +│ ├── llm.py # LLM 客户端（分析 + 生成） +│ ├── prompt.py # 提示词构建 +│ ├── source.py # 源文件路径处理 +│ ├── ingest_cache.py # 导入缓存 +│ └── wiki_writer.py # Wiki 文件解析与写入 +├── tests/ # 测试用例 +├── raw/sources/ # 源文档目录 +├── wiki/ # 生成的 Wiki 知识库 +├── config.json # 配置文件 +├── tasks.py # 任务运行器 +└── pyproject.toml # 项目依赖与工具配置 +``` + +## 可用命令 + +| 命令 | 说明 | +|------|------| +| `python tasks.py install` | 安装依赖并配置 pre-commit | +| `python tasks.py run` | 执行主流程 | +| `python tasks.py check` | 运行代码检查（ruff + mypy + deptry） | +| `python tasks.py test` | 运行测试套件 | +| `python tasks.py clean` | 清理缓存目录 | + +## Wiki 页面类型 + +生成的 Wiki 页面支持以下类型： + +- **source** — 源文档摘要页面 +- **entity** — 关键实体（产品、芯片、算法等） +- **concept** — 关键概念（理论、方法、技术等） +- **query** — 查询页面 +- **synthesis** — 综合页面 +- **comparison** — 对比页面 + +## 许可证 + +MIT License \ No newline at end of file diff --git a/src/analysis_system_prompt.md b/src/analysis_system_prompt.md new file mode 100644 index 0000000..fb8b7b3 --- /dev/null +++ b/src/analysis_system_prompt.md @@ -0,0 +1,59 @@ +你是一位专业的嵌入式系统技术文档分析师，负责将各类嵌入式相关文档（技术手册、论文、项目笔记、调试记录、教程等）转化为结构化的知识库内容。你的核心目标是精准提取、系统分类、清晰关联所有有价值的技术信息，确保生成的内容能够直接用于构建和完善嵌入式系统 Wiki 知识库。不要输出思维链、隐藏推理或思考过程。在内部进行推理，只撰写简洁的最终分析。 + +{{LANG_RULE}} +**请严格按照以下结构进行分析，确保内容全面、逻辑清晰、重点突出：** +## 文档元信息 +- 文档类型：技术手册 / 学术论文 / 项目报告 / 调试记录 / 教程 / 规格书 / 代码注释等 +- 核心主题：用一句话概括文档的核心内容 +- 文档价值等级：核心（必须收录）/ 重要（建议收录）/ 一般（选择性收录）/ 边缘（无需收录） +- 是否可能已存在于 wiki 中（查阅 index.md 文件查看是否已存在） +## 关键实体提取 +列出文档中所有具有独立技术意义的实体，按以下分类整理： + +|实体类型|实体名称|在文档中的角色（核心 / 重要 / 边缘）|是否可能已存在于 Wiki 中|备注| +|---|---|---|---|---| +|芯片 / 器件|例如：STM32F407ZGT6、MAX7219、SN340FU02|||| +|硬件模块|例如：电源模块、串口通信模块、传感器模块|||| +|软件 / 固件|例如：FreeRTOS、U-Boot、STM32CubeMX|||| +|开发工具|例如：Keil MDK、Proteus、立创 EDA、ST-LINK|||| +|通信协议|例如：UART、SPI、I2C、TCP/IP、Modbus|||| +|算法 / 数据结构|例如：PID 控制、状态机、环形缓冲区|||| +|标准 / 规范|例如：GB/T 35732-2025、IEEE 802.3|||| +|其他|例如：特定数据集、测试设备|||| + +## 关键概念解析 +列出文档中涉及的核心理论、方法、技术和现象，每个概念包含： +- 概念名称 +- 简明定义：用 1-2 句话清晰解释概念的本质 +- 在文档中的重要性：为什么这个概念对理解文档内容至关重要 +- 是否可能已存在于 Wiki 中，如果不确定可以调用工具确认 +- 关联实体：该概念与哪些关键实体相关联 +## 核心技术方案 +- 整体架构：系统的硬件架构和软件架构（可使用文字描述或简单的层级结构） +- 工作原理：系统或模块的核心运行机制 +- 主要的工作流程、数据流向或控制流程 +- 核心实现：关键功能的具体实现方法或代码逻辑要点 +## 与现有 Wiki 的关联 +- 相关页面：列出所有与本文档内容相关的现有 Wiki 页面 +- 知识关系：本文档是强化（验证）、扩展（补充）还是挑战（修正）了现有知识 +## 矛盾与张力 +- 源文档中是否有任何内容与现有 wiki 内容冲突？ +- 是否存在内部矛盾或注意事项？ + +## 建议 +- 应该创建或更新哪些 wiki 页面？ +- 应该强调什么，弱化什么？ +- 是否有任何需要向用户指出的开放性问题？ +分析要全面但简洁，专注于真正重要的内容。 + +如果提供了文件夹上下文，请将其作为分类的提示——文件夹结构通常反映了用户的组织意图（例如，'papers/energy' 表示该文件是与能源相关的论文）。 + +{{#PURPOSE}} +## Wiki 目的（供参考） +{{PURPOSE}} +{{/PURPOSE}} + +{{#INDEX}} +## 当前 Wiki 索引（用于检查现有内容） +{{INDEX}} +{{/INDEX}} \ No newline at end of file diff --git a/src/generation_system_prompt.md b/src/generation_system_prompt.md new file mode 100644 index 0000000..e5405fa --- /dev/null +++ b/src/generation_system_prompt.md @@ -0,0 +1,150 @@ +你是一位 wiki 维护者。根据提供的分析结果，生成 wiki 文件。 +不要输出思维链、隐藏推理或解释性前言。在内部进行推理，只输出请求的 FILE/REVIEW 块。 + +{{LANG_RULE}} + +## 重要：源文件 +原始源文件是：**{{SOURCE_FILE_NAME}}** +从此源文件生成的所有 wiki 页面都必须在 frontmatter 的 `sources` 字段中包含此文件名。 + +{{#SCHEMA}} +## 项目 Schema 和路由规则（重要！！！） +{{SCHEMA}} + +使用此 schema 作为页面类型和目录的主要路由规则。 +如果它定义了自定义文件夹或区分（例如人物、技术、组织、方法或案例），请将页面写入这些 schema 定义的文件夹，而不是强制写入 wiki/实体/ 或 wiki/概念/。 +仅在 schema 未提供更具体目标时，才使用 wiki/实体/ 和 wiki/概念/。 +{{/SCHEMA}} + +## 需要生成的内容 + +1. 源摘要页面，路径为 **{{SUMMARY_PATH}}**（必须使用此确切路径） +2. 实体页面或 schema 定义的页面，用于分析中标识的关键命名对象。优先使用 schema 定义的目录；否则使用 wiki/实体/。 +3. 概念页面或 schema 定义的页面，用于关键想法、方法、技术和抽象。优先使用 schema 定义的目录；否则使用 wiki/概念/。 +4. 更新的 wiki/index.md — 在现有类别中添加新条目，保留所有现有条目 +5. wiki/log.md 的日志条目（仅追加新条目，格式：## [YYYY-MM-DD] ingest | 标题） +6. 更新的 wiki/overview.md — 整个 wiki 覆盖内容的高级摘要，更新以反映新导入的源。这应该是关于 wiki 中所有主题的综合 2-5 段概述，而不仅仅是新源。 + +## Frontmatter 规则（关键 — 解析器严格） + +每个页面以 YAML frontmatter 块开头。格式规则按重要性排序： + +1. 文件的第一行必须是恰好 `---`（三个连字符，不含其他内容）。 + 不要将文件包裹在 ```yaml ... ``` 代码块中。 + 不要以 `frontmatter:` 键或其他行作为前缀。 +2. 每行 frontmatter 是独立的 `key: value` 对。 +3. frontmatter 以另一行 `---` 结尾。 +4. 关闭 `---` 之后的下一行是页面正文的开始。 +5. 数组使用标准 YAML 内联形式 `[a, b, c]`（每项没有外部括号）。 + Wikilinks 仅属于正文 — 不要写 `related: [[a]], [[b]]`（无效 YAML）； + 写 `related: [a, b]` 使用裸 slug。 + +必需字段和类型： + • type — 已知类型之一（{{WIKI_TYPES}}），或项目 schema 明确定义的自定义类型 + • title — 字符串（尽量用中文，如果是必要的英文专业词汇可以用英文，如果包含冒号，请使用引号，例如 `title: "Foo: Bar"`） + • created — YYYY-MM-DD 格式的日期（不加引号） + • updated — 与 created 相同 + • tags — 裸字符串数组：`tags: [microbiology, ai]` + • related — 裸 wiki 页面 slug 数组：`related: [foo, bar-baz]`。不要包含 + `wiki/`、`.md` 或 `[[…]]` — 仅 slug。 + • sources — 源文件名数组；必须包含 "{{SOURCE_FILE_NAME}}"。 + +完整的可解析页面示例（两个 `---` 行之间的内容是 frontmatter；其后的标题和正文是页面正文）： + + --- + type: entity + title: 示例实体 + created: 2026-04-29 + updated: 2026-04-29 + tags: [示例, 演示] + related: [相关-slug-1, 相关-slug-2] + sources: ["{{SOURCE_FILE_NAME}}"] + --- + + # 示例实体 + + 正文内容写在这里。在正文中使用 [[wikilink]] 语法进行页面交叉引用。 + +其他规则： +- 在正文中使用 [[wikilink]] 语法进行页面交叉引用 +- 如果包含图片，使用相对于 wiki 根的路径，如 `media/source-slug/image.png`；绝不输出绝对文件系统路径。 +- 使用 kebab-case 文件名，尽量使用中文，如果是必要的英文专业词汇可以用英文 +- 遵循分析建议中关于强调内容的指导 +- 如果分析发现与现有页面的连接，添加交叉引用 + +## Review 块类型 + +在所有 FILE 块之后，可选地发出 REVIEW 块，用于需要人工判断的事项： + +- contradiction：分析发现与现有 wiki 内容存在冲突 +- duplicate：实体/概念可能在索引中以不同名称存在 +- missing-page：重要的概念被引用但没有专用页面 +- suggestion：关于进一步研究、相关源或值得探索的连接的思路 + +仅针对真正需要人工输入的事项创建 review。不要创建琐碎的 review。 + +## OPTIONS 允许值（仅限这些预定义标签）： + +- contradiction: OPTIONS: Create Page | Skip +- duplicate: OPTIONS: Create Page | Skip +- missing-page: OPTIONS: Create Page | Skip +- suggestion: OPTIONS: Create Page | Skip + +用户还有一个'深度研究'按钮（系统自动添加），可触发网络搜索。 +不要发明自定义选项标签。仅使用'Create Page'和'Skip'。 + +对于 suggestion 和 missing-page review，SEARCH 字段必须包含 2-3 个网络搜索查询 +（富含关键词、具体、适合搜索引擎 — 不是标题或句子）。示例： + SEARCH: automated technical debt detection AI generated code | software quality metrics LLM code generation | static analysis tools agentic software development + +{{#PURPOSE}} +## Wiki 目的 +{{PURPOSE}} +{{/PURPOSE}} + +{{#INDEX}} +## 当前 Wiki 索引（保留所有现有条目，添加新条目） +{{INDEX}} +{{/INDEX}} + +{{#OVERVIEW}} +## 当前概述（更新以反映新源） +{{OVERVIEW}} +{{/OVERVIEW}} + +## 输出格式（必须严格遵守 — 这是解析器读取响应的方式） + +你的整个响应仅由 FILE 块和可选的 REVIEW 块组成。不含其他内容。 + +FILE 块模板： +``` +---FILE: wiki/path/to/page.md--- +（完整的文件内容，包含 YAML frontmatter） +---END FILE--- +``` + +REVIEW 块模板（可选，在所有 FILE 块之后）： +``` +---REVIEW: type | Title--- +描述需要用户关注的内容。 +OPTIONS: Create Page | Skip +PAGES: wiki/page1.md, wiki/page2.md +SEARCH: query 1 | query 2 | query 3 +---END REVIEW--- +``` + +## 输出要求（严格 — 偏差将导致解析失败） + +1. 响应的第一个字符必须是 `-`（`---FILE:` 的开头）。 +2. 不要输出任何前言，如"以下是文件："、"根据分析..."或任何介绍性文字。 +3. 不要重复或重述分析 — 那是第一阶段的工作。你的工作是发出 FILE 块。 +4. 不要在 FILE/REVIEW 块之外输出 markdown 表格、项目符号列表或标题。 +5. 不要在最后一个 `---END FILE---` 或 `---END REVIEW---` 之后输出任何尾部评论。 +6. 块之间仅使用空行 — 不含字符。 +7. 每个 FILE 块的内容（标题、正文、描述）必须使用下面指定的强制输出语言。没有例外 — 即使是页面名称或章节标题。 + +如果以 `---FILE:` 以外的任何内容开头，整个响应将被丢弃。 + +--- + +{{LANG_RULE}} \ No newline at end of file diff --git a/src/ingest_cache.py b/src/ingest_cache.py index 81f1f3b..ef96d01 100644 --- a/src/ingest_cache.py +++ b/src/ingest_cache.py @@ -1,7 +1,7 @@ """导入缓存模块。 避免对相同源内容重复执行 LLM 分析。缓存键基于源标识符和源内容的哈希， -缓存值为已生成的 wiki 文件路径列表。 +缓存值为已生成的 wiki 文件路径列表和分析结果。 """ import hashlib @@ -36,9 +36,9 @@ def check_ingest_cache( project_path: str, source_identity: str, source_content: str, -) -> list[str] | None: +) -> tuple[list[str], str] | None: """ - 检查导入缓存，如果源内容未变化则返回之前生成的文件列表。 + 检查导入缓存，如果源内容未变化则返回之前生成的文件列表和分析结果。 参数 ---------- @@ -51,8 +51,8 @@ def check_ingest_cache( 返回 ------- - list[str] | None - 如果缓存命中，返回之前生成的文件路径列表； + tuple[list[str], str] | None + 如果缓存命中，返回 (文件路径列表, 分析结果)； 如果缓存未命中或缓存失效，返回 None。 """ cache_file = _cache_file(project_path, source_identity) @@ -107,12 +107,14 @@ def check_ingest_cache( pass return None + analysis = cache_data.get("analysis", "") + logger.info( "[cache] HIT for %s (%d cached files)", source_identity, len(file_list), ) - return file_list + return (file_list, analysis) def save_ingest_cache( @@ -120,9 +122,10 @@ def save_ingest_cache( source_identity: str, source_content: str, written_paths: list[str], + analysis: str = "", ) -> None: """ - 保存导入缓存，记录源内容和生成的文件列表。 + 保存导入缓存，记录源内容、分析结果和生成的文件列表。 参数 ---------- @@ -134,6 +137,8 @@ def save_ingest_cache( 源文件的内容（用于计算哈希）。 written_paths : list[str] 本次导入生成的文件路径列表。 + analysis : str + 第一步 LLM 分析结果（开发阶段缓存，避免重复分析）。 """ cache_dir = _cache_dir(project_path) cache_dir.mkdir(parents=True, exist_ok=True) @@ -144,6 +149,7 @@ def save_ingest_cache( "source_identity": source_identity, "content_hash": _content_hash(source_content), "files": written_paths, + "analysis": analysis, } try: diff --git a/src/llm.py b/src/llm.py index 0ecaa49..0a528c5 100644 --- a/src/llm.py +++ b/src/llm.py @@ -2,7 +2,11 @@ import logging -from prompt import build_analysis_system_prompt, build_generation_prompt, language_rule +from prompt import ( + _resolve_lang_rule, + build_analysis_system_prompt, + build_generation_prompt, +) logger = logging.getLogger(__name__) @@ -66,7 +70,7 @@ def query_analysis( source_content=source_content, configured_language=configured_language, ) - + logger.info("system_prompt: %s", system_prompt) messages = [ ChatMessage(role="system", content=system_prompt), ChatMessage( @@ -143,7 +147,7 @@ def query_generation( from config import get_llm_config - lang_rule = language_rule(source_content, configured_language) + lang_rule = _resolve_lang_rule(source_content, configured_language) system_prompt = build_generation_prompt( lang_rule=lang_rule, schema=schema, diff --git a/src/main.py b/src/main.py index 6aa0607..6e003a6 100644 --- a/src/main.py +++ b/src/main.py @@ -89,24 +89,25 @@ def main() -> None: try: # Step 0: 缓存检查 — 源内容未变化时跳过 LLM 调用 - cached_files = check_ingest_cache(project_path, source_identity, source_content) - if cached_files is not None: + cached = check_ingest_cache(project_path, source_identity, source_content) + if cached is not None: + cached_files, cached_analysis = cached logger.info( "缓存命中，跳过分析（%d 个已缓存文件）", len(cached_files), ) - continue - - # Step 1: 分析源文件 - analysis = query_analysis( - purpose=purpose, - index=index, - source_content=source_content, - source_identity=source_identity, - folder_context=folder_context, - ) - logger.info("分析完成，结果长度: %d 字符", len(analysis)) - logger.info("结果: %s", analysis) + analysis = cached_analysis + else: + # Step 1: 分析源文件 + analysis = query_analysis( + purpose=purpose, + index=index, + source_content=source_content, + source_identity=source_identity, + folder_context=folder_context, + ) + logger.info("分析完成，结果长度: %d 字符", len(analysis)) + logger.info("结果: %s", analysis) # Step 2: 生成 wiki 文件 wiki_files = query_generation( @@ -132,6 +133,7 @@ def main() -> None: source_identity, source_content, written_paths=written_paths, + analysis=analysis, ) except Exception as e: logger.error("分析失败: %s", e, exc_info=True) diff --git a/src/prompt.py b/src/prompt.py index dbb1dc7..5329eca 100644 --- a/src/prompt.py +++ b/src/prompt.py @@ -11,9 +11,20 @@ GENERATION_WIKI_TYPES = [ ] -def language_rule(source_content: str, configured_language: str | None = None) -> str: +def _load_template(template_name: str) -> str: + """根据文件名加载提示词模板。""" + from pathlib import Path + + template_path = Path(__file__).parent / template_name + return template_path.read_text(encoding="utf-8") + + +def _resolve_lang_rule( + source_content: str, + configured_language: str | None = None, +) -> str: """ - 生成语言规则提示。 + 解析语言规则字符串。 参数 ---------- @@ -21,7 +32,7 @@ def language_rule(source_content: str, configured_language: str | None = None) - 用于语言检测回退的源文档文本。 configured_language : str | None 明确配置的输出语言（如 "Chinese"、"English"、"auto"）。 - 传入 ``None`` 或 ``"auto"`` 以自动检测。 + 传入 ``None`` 时触发自动检测。 返回 ------- @@ -38,6 +49,29 @@ def language_rule(source_content: str, configured_language: str | None = None) - return "使用与源文档相同的语言输出分析报告。" +def _render_template(template: str, variables: dict[str, str]) -> str: + """ + 简易模板渲染：支持 {{VAR}} 替换和 {{#VAR}}...{{/VAR}} 条件块。 + """ + import re + + # 先处理条件块 {{#VAR}}...{{/VAR}} + for key, value in variables.items(): + open_tag = f"{{{{#{key}}}}}" + close_tag = f"{{{{/{key}}}}}" + pattern = re.escape(open_tag) + r"([\s\S]*?)" + re.escape(close_tag) + if value: + template = re.sub(pattern, r"\1", template) + else: + template = re.sub(pattern, "", template) + + # 再处理简单变量 {{VAR}} + for key, value in variables.items(): + template = template.replace(f"{{{{{key}}}}}", value) + + return template + + def build_analysis_system_prompt( purpose: str, index: str, @@ -68,54 +102,17 @@ def build_analysis_system_prompt( if configured_language is None: configured_language = get_language() - parts: list[str] = [ - "作为一位非常专业的嵌入式工程师，根据长久的工程师经验阅读源文档并产出一份结构化的分析报告。", - "不要输出思维链、隐藏推理或思考过程。在内部进行推理，只撰写简洁的最终分析。", - "", - language_rule(source_content, configured_language), - "", - "你的分析需要包含：", - "", - "## 关键实体", - "列出文档中提到的人物、组织、产品、数据集、工具、芯片、算法等。对于每一项：", - "- 名称和类型", - "- 在源文档中的角色（核心还是边缘）", - "- 是否可能已存在于 wiki 中（查阅索引）", - "", - "## 关键概念", - "列出理论、方法、技术、现象。对于每一项：", - "- 名称和简要定义", - "- 为什么在源文档中重要", - "- 是否可能已存在于 wiki 中", - "", - "## 主要论点与发现", - "- 核心主张或结果是什么？", - "- 有什么证据支持这些主张？", - "- 证据的强度如何？", - "", - "## 与现有 Wiki 的关联", - "- 源文档与哪些现有页面相关？", - "- 它是否强化、挑战或扩展了现有知识？", - "", - "## 矛盾与张力", - "- 源文档中是否有任何内容与现有 wiki 内容冲突？", - "- 是否存在内部矛盾或注意事项？", - "", - "## 建议", - "- 应该创建或更新哪些 wiki 页面？", - "- 应该强调什么，弱化什么？", - "- 是否有任何需要向用户指出的开放性问题？", - "", - "分析要全面但简洁，专注于真正重要的内容。", - "", - "如果提供了文件夹上下文，请将其作为分类的提示——文件夹结构通常反映了用户的组织意图（例如，'papers/energy' 表示该文件是与能源相关的论文）。", - "", - f"## Wiki 目的（供参考）\n{purpose}" if purpose else "", - (f"## 当前 Wiki 索引（用于检查现有内容）\n{index}" if index else ""), - ] - # 过滤空字符串并用换行符连接 - return "\n".join(part for part in parts if part) + template = _load_template("analysis_system_prompt.md") + + return _render_template( + template, + { + "LANG_RULE": _resolve_lang_rule(source_content, configured_language), + "PURPOSE": purpose, + "INDEX": index, + }, + ) def build_generation_prompt( @@ -162,150 +159,18 @@ def build_generation_prompt( wiki_types_str = " | ".join(GENERATION_WIKI_TYPES) - parts: list[str] = [ - "你是一位 wiki 维护者。根据提供的分析结果，生成 wiki 文件。", - "不要输出思维链、隐藏推理或解释性前言。在内部进行推理，只输出请求的 FILE/REVIEW 块。", - "", - lang_rule, - "", - "## 重要：源文件", - f"原始源文件是：**{source_file_name}**", - "从此源生成的所有 wiki 页面都必须在 frontmatter 的 `sources` 字段中包含此文件名。", - "", - schema - and [ - "## 项目 Schema 和路由规则（权威）", - schema, - "", - "使用此 schema 作为页面类型和目录的主要路由规则。", - "如果它定义了自定义文件夹或区分（例如人物、技术、组织、方法或案例），请将页面写入这些 schema 定义的文件夹，而不是强制写入 wiki/entities/ 或 wiki/concepts/。", - "仅在 schema 未提供更具体目标时，才使用 wiki/entities/ 和 wiki/concepts/。", - ], - "", - "## 需要生成的内容", - "", - f"1. 源摘要页面，路径为 **{summary_path}**（必须使用此确切路径）", - "2. 实体页面或 schema 定义的页面，用于分析中标识的关键命名对象。优先使用 schema 定义的目录；否则使用 wiki/entities/。", - "3. 概念页面或 schema 定义的页面，用于关键想法、方法、技术和抽象。优先使用 schema 定义的目录；否则使用 wiki/concepts/。", - "4. 更新的 wiki/index.md — 在现有类别中添加新条目，保留所有现有条目", - "5. wiki/log.md 的日志条目（仅追加新条目，格式：## [YYYY-MM-DD] ingest | 标题）", - "6. 更新的 wiki/overview.md — 整个 wiki 覆盖内容的高级摘要，更新以反映新导入的源。这应该是关于 wiki 中所有主题的综合 2-5 段概述，而不仅仅是新源。", - "", - "## Frontmatter 规则（关键 — 解析器严格）", - "", - "每个页面以 YAML frontmatter 块开头。格式规则按重要性排序：", - "", - "1. 文件的第一行必须是恰好 `---`（三个连字符，不含其他内容）。", - " 不要将文件包裹在 ```yaml ... ``` 代码块中。", - " 不要以 `frontmatter:` 键或其他行作为前缀。", - "2. 每行 frontmatter 是独立的 `key: value` 对。", - "3. frontmatter 以另一行 `---` 结尾。", - "4. 关闭 `---` 之后的下一行是页面正文的开始。", - "5. 数组使用标准 YAML 内联形式 `[a, b, c]`（每项没有外部括号）。", - " Wikilinks 仅属于正文 — 不要写 `related: [[a]], [[b]]`（无效 YAML）；", - " 写 `related: [a, b]` 使用裸 slug。", - "", - "必需字段和类型：", - f" • type — 已知类型之一（{wiki_types_str}），或项目 schema 明确定义的自定义类型", - ' • title — 字符串（尽量用中文，如果是必要的英文专业词汇可以用英文，如果包含冒号，请使用引号，例如 `title: "Foo: Bar"`）', - " • created — YYYY-MM-DD 格式的日期（不加引号）", - " • updated — 与 created 相同", - " • tags — 裸字符串数组：`tags: [microbiology, ai]`", - " • related — 裸 wiki 页面 slug 数组：`related: [foo, bar-baz]`。不要包含", - " `wiki/`、`.md` 或 `[[…]]` — 仅 slug。", - f' • sources — 源文件名数组；必须包含 "{source_file_name}"。', - "", - "完整的可解析页面示例（两个 `---` 行之间的内容是 frontmatter；其后的标题和正文是页面正文）：", - "", - " ---", - " type: entity", - " title: 示例实体", - " created: 2026-04-29", - " updated: 2026-04-29", - " tags: [示例, 演示]", - " related: [相关-slug-1, 相关-slug-2]", - f' sources: ["{source_file_name}"]', - " ---", - "", - " # 示例实体", - "", - " 正文内容写在这里。在正文中使用 [[wikilink]] 语法进行页面交叉引用。", - "", - "其他规则：", - "- 在正文中使用 [[wikilink]] 语法进行页面交叉引用", - "- 如果包含图片，使用相对于 wiki 根的路径，如 `media/source-slug/image.png`；绝不输出绝对文件系统路径。", - "- 使用 kebab-case 文件名，尽量使用中文，如果是必要的英文专业词汇可以用英文 ", - "- 遵循分析建议中关于强调内容的指导", - "- 如果分析发现与现有页面的连接，添加交叉引用", - "", - "## Review 块类型", - "", - "在所有 FILE 块之后，可选地发出 REVIEW 块，用于需要人工判断的事项：", - "", - "- contradiction：分析发现与现有 wiki 内容存在冲突", - "- duplicate：实体/概念可能在索引中以不同名称存在", - "- missing-page：重要的概念被引用但没有专用页面", - "- suggestion：关于进一步研究、相关源或值得探索的连接的思路", - "", - "仅针对真正需要人工输入的事项创建 review。不要创建琐碎的 review。", - "", - "## OPTIONS 允许值（仅限这些预定义标签）：", - "", - "- contradiction: OPTIONS: Create Page | Skip", - "- duplicate: OPTIONS: Create Page | Skip", - "- missing-page: OPTIONS: Create Page | Skip", - "- suggestion: OPTIONS: Create Page | Skip", - "", - "用户还有一个'深度研究'按钮（系统自动添加），可触发网络搜索。", - "不要发明自定义选项标签。仅使用'Create Page'和'Skip'。", - "", - "对于 suggestion 和 missing-page review，SEARCH 字段必须包含 2-3 个网络搜索查询", - "（富含关键词、具体、适合搜索引擎 — 不是标题或句子）。示例：", - " SEARCH: automated technical debt detection AI generated code | software quality metrics LLM code generation | static analysis tools agentic software development", - "", - f"## Wiki 目的\n{purpose}" if purpose else "", - f"## 当前 Wiki 索引（保留所有现有条目，添加新条目）\n{index}" if index else "", - f"## 当前概述（更新以反映新源）\n{overview}" if overview else "", - "", - # 输出格式必须是最后一部分——模型对最近的指令权重最高 - "## 输出格式（必须严格遵守 — 这是解析器读取响应的方式）", - "", - "你的整个响应仅由 FILE 块和可选的 REVIEW 块组成。不含其他内容。", - "", - "FILE 块模板：", - "```", - "---FILE: wiki/path/to/page.md---", - "（完整的文件内容，包含 YAML frontmatter）", - "---END FILE---", - "```", - "", - "REVIEW 块模板（可选，在所有 FILE 块之后）：", - "```", - "---REVIEW: type | Title---", - "描述需要用户关注的内容。", - "OPTIONS: Create Page | Skip", - "PAGES: wiki/page1.md, wiki/page2.md", - "SEARCH: query 1 | query 2 | query 3", - "---END REVIEW---", - "```", - "", - "## 输出要求（严格 — 偏差将导致解析失败）", - "", - "1. 响应的第一个字符必须是 `-`（`---FILE:` 的开头）。", - '2. 不要输出任何前言，如"以下是文件："、"根据分析..."或任何介绍性文字。', - "3. 不要重复或重述分析 — 那是第一阶段的工作。你的工作是发出 FILE 块。", - "4. 不要在 FILE/REVIEW 块之外输出 markdown 表格、项目符号列表或标题。", - "5. 不要在最后一个 `---END FILE---` 或 `---END REVIEW---` 之后输出任何尾部评论。", - "6. 块之间仅使用空行 — 不含字符。", - "7. 每个 FILE 块的内容（标题、正文、描述）必须使用下面指定的强制输出语言。没有例外 — 即使是页面名称或章节标题。", - "", - "如果以 `---FILE:` 以外的任何内容开头，整个响应将被丢弃。", - "", - # 在末尾重复语言指令，确保"最近指令"权重最高 - "---", - "", - lang_rule, - ] + template = _load_template("generation_system_prompt.md") - # 过滤空值并用换行符连接 - return "\n".join(part for part in parts if part is not None and part != "") + return _render_template( + template, + { + "LANG_RULE": lang_rule, + "SOURCE_FILE_NAME": source_file_name, + "SUMMARY_PATH": summary_path, + "WIKI_TYPES": wiki_types_str, + "SCHEMA": schema, + "PURPOSE": purpose, + "INDEX": index, + "OVERVIEW": overview, + }, + ) diff --git a/tasks.py b/tasks.py index d471d4f..4b4d8b2 100644 --- a/tasks.py +++ b/tasks.py @@ -19,19 +19,19 @@ def install() -> None: def check() -> None: - run("python -m uv lock --locked") - run("python -m uv run ruff check .") - run("python -m uv run ruff format --check .") - run("python -m uv run mypy src/main.py") - run("python -m uv run deptry .") + run("uv lock --locked") + run("uv run ruff check .") + run("uv run ruff format --check .") + run("uv run mypy src/") + run("uv run deptry .") def test() -> None: - run("python -m uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=term-missing") + run("uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=term-missing") def run_main() -> None: - run("python -m uv run python src/main.py") + run("uv run python src/main.py") def clean() -> None: diff --git a/tests/test_language_rule.py b/tests/test_language_rule.py index 9ffe087..623feb0 100644 --- a/tests/test_language_rule.py +++ b/tests/test_language_rule.py @@ -5,7 +5,7 @@ from pathlib import Path sys.path.insert(0, str(Path(__file__).parent.parent / "src")) -from prompt import language_rule +from prompt import _resolve_lang_rule class TestLanguageRule: @@ -13,20 +13,20 @@ class TestLanguageRule: def test_explicit_language(self) -> None: """测试显式指定语言时，提示中包含该语言名称。""" - result = language_rule("test content", "Chinese") + result = _resolve_lang_rule("test content", "Chinese") assert "Chinese" in result def test_auto_with_chinese_content(self) -> None: """测试中文内容自动检测。""" - result = language_rule("这是一段中文内容", None) + result = _resolve_lang_rule("这是一段中文内容", None) assert "简体中文" in result def test_auto_with_english_content(self) -> None: """测试英文内容自动检测。""" - result = language_rule("This is English content", None) + result = _resolve_lang_rule("This is English content", None) assert "源文档" in result def test_auto_detection_string(self) -> None: """测试传入 "auto" 字符串时触发自动检测。""" - result = language_rule("test", "auto") + result = _resolve_lang_rule("test", "auto") assert "源文档" in result diff --git a/wiki/concepts/rtu-remote-terminal-unit.md b/wiki/concepts/rtu-remote-terminal-unit.md deleted file mode 100644 index b99fb90..0000000 --- a/wiki/concepts/rtu-remote-terminal-unit.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -type: concept -title: "RTU（Remote Terminal Unit）" -created: 2024-05-20 -updated: 2024-05-20 -tags: [工业自动化, 边缘节点, SCADA, 测控设备] -related: [三遥系统, plc, scada-系统, dtu-配电终端] -sources: ["DTU/RTU（Remote Terminal Unit）.md"] ---- -# RTU（Remote Terminal Unit） -RTU（远端测控单元）是工业自动化与 SCADA 体系中的核心边缘节点设备，主要负责现场信号的采集、本地逻辑处理、协议转换以及上行通信。在“云-边-端”架构中，RTU 承担着将物理层数据转化为标准化工业协议的关键角色，广泛应用于石油、化工、智能制造及基础设施监控等领域。 - -## 核心能力与架构定位 -RTU 的设计初衷是适应恶劣的野外或工业环境，具备高环境适应性（宽温、高防护等级）、大容量数据存储与强大的远程通信能力。其业务功能高度依赖 [[三遥系统]] 标准，通过遥信（YX）监视设备状态，通过遥测（YC）采集过程参数，并通过遥控（YK）执行远程指令。 - -## 与 PLC 的选型边界 -在传统工业控制架构中，RTU 与 [[PLC]] 存在明确的功能划分：RTU 侧重于远程通信、数据汇聚与环境耐受性，适用于分散式部署；PLC 则侧重于本地高速逻辑运算与实时控制，适用于集中式产线。然而，随着边缘计算技术的发展，现代高端 PLC 已逐步集成以太网通信、OPC UA 协议与复杂算法，而 RTU 也向“智能边缘网关”演进，两者在算力与通信能力上的界限正逐渐模糊。实际选型需综合考量实时性要求、通信距离、环境防护等级及协议栈兼容性。 - -## 领域特化与演进 -通用 RTU 构成了工业测控的硬件底座。在电力配电自动化领域，基于 RTU 架构衍生出了专用的配电终端（DTU）、馈线终端（FTU）与配变终端（TTU），这些设备针对 IEC 60870-5-104/101、DL/T 634 等电力规约及电网拓扑进行了深度优化。未来 RTU 的发展将更侧重于多协议融合、安全机制（如 IEC 62443）集成以及云边协同能力。 \ No newline at end of file diff --git a/wiki/concepts/三遥协同机制.md b/wiki/concepts/三遥协同机制.md deleted file mode 100644 index dc6cb88..0000000 --- a/wiki/concepts/三遥协同机制.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -type: concept -title: "三遥协同机制" -created: 2024-05-20 -updated: 2024-05-20 -tags: [配电自动化, 控制理论, 终端通信, 实时控制] -related: [dtu-站所终端, 遥信, 遥测, 遥控, 配电主站, 故障自愈逻辑] -sources: ["DTU/DTU（Distribution Terminal Unit）.md"] ---- -# 三遥协同机制 - -**三遥协同机制**是配电自动化系统中终端与主站交互的基础控制范式，指通过遥信（YX）、遥测（YC）、遥控（YK）三种能力的闭环配合，实现电网状态的实时感知、逻辑校验与精准执行。该机制构成了 [[DTU（站所终端）]] 业务逻辑的核心骨架，直接决定故障响应时效与系统控制精度。 - -## 协同控制流 -三遥并非独立运行，而是遵循严格的时序与逻辑依赖： -1. **遥信触发（感知）**：终端采集开关位置变位、保护动作信号或告警状态，作为故障或异常事件的初始触发源。 -2. **遥测校验（确认）**：主站或终端本地逻辑调取电压、电流、功率等电气量数据，交叉验证遥信信号的真实性，排除误报或瞬时干扰。 -3. **遥控执行（动作）**：在逻辑校验通过后，系统下发分合闸或投切指令，终端驱动执行机构完成物理操作，实现控制闭环。 - -## 在站所终端中的落地 -在 [[DTU]] 的多回路站所场景中，三遥协同机制需处理更复杂的数据并发与逻辑冲突。DTU 通过内部实时操作系统（RTOS）调度，确保毫秒级遥信上报与遥控响应，同时支持主站集中控制与终端就地逻辑的无缝切换。该机制的有效运行依赖于高可靠通信链路（如光纤/5G/载波）与标准化协议栈（如 IEC 61850/60870-5-104）。 - -## 业务价值 -三遥协同是 [[故障自愈逻辑]] 得以实现的前提。通过“感知-校验-执行”的标准化流程，配电系统能够将传统的人工巡线抢修模式升级为自动化快速隔离与恢复，大幅降低停电范围与时长，提升配电网的韧性与智能化水平。 \ No newline at end of file diff --git a/wiki/concepts/三遥系统.md b/wiki/concepts/三遥系统.md deleted file mode 100644 index 0807bba..0000000 --- a/wiki/concepts/三遥系统.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -type: concept -title: "三遥系统" -created: 2024-05-20 -updated: 2024-05-20 -tags: [工业监控, 电力自动化, 数据采集, 远程控制] -related: [rtu-remote-terminal-unit, scada-系统] -sources: ["DTU/RTU（Remote Terminal Unit）.md"] ---- -# 三遥系统 -三遥系统是工业自动化与电力监控领域的标准交互模型，定义了远端测控设备（如 [[RTU]]）与上位监控系统（如 [[SCADA 系统]]）之间的核心数据流与控制指令。该系统通过三种基础能力实现了对工业过程与设备状态的全面感知与干预。 - -## 能力构成 -- **遥信（YX，Remote Signaling）**：负责采集工业设备的离散状态信号与故障报警。典型应用包括断路器分合闸状态、设备运行/停机指示、越限报警等。 -- **遥测（YC，Remote Telemetry）**：负责采集连续的模拟量过程参数。典型应用包括温度、压力、流量、电压、电流等物理量的实时监测与历史趋势记录。 -- **遥控（YK，Remote Control）**：负责将上位系统的控制指令下发至现场执行机构。典型应用包括设备启停控制、阀门开度调节、继电器投切等。 - -## 工程意义 -三遥能力是构建工业物联网（IIoT）与配电自动化系统的数据基石。在实际工程中，三遥数据的准确性、实时性与可靠性直接决定了监控系统的调度效率与安全水平。现代测控终端通常在三遥基础上扩展“遥调”（参数远程设定）与“遥视”（视频/图像监控），形成“五遥”体系，以应对更复杂的智能制造与智慧电网需求。 \ No newline at end of file diff --git a/wiki/concepts/故障自愈逻辑.md b/wiki/concepts/故障自愈逻辑.md deleted file mode 100644 index 5fb9a95..0000000 --- a/wiki/concepts/故障自愈逻辑.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -type: concept -title: "故障自愈逻辑" -created: 2024-05-20 -updated: 2024-05-20 -tags: [配网自动化, 供电可靠性, 故障处理, 智能电网] -related: [dtu-站所终端, 三遥协同机制, 配电主站, 馈线自动化] -sources: ["DTU/DTU（Distribution Terminal Unit）.md"] ---- -# 故障自愈逻辑 - -**故障自愈逻辑**是配电网自动化系统的核心业务流，指系统在发生故障时，无需人工干预即可自动完成故障定位、隔离及非故障区域供电恢复的闭环控制过程。该逻辑直接体现 [[DTU（站所终端）]] 在提升供电可靠性（SAIDI/SAIFI）中的工程价值，是现代智能配电网的标志性能力。 - -## 核心处理流程 -故障自愈通常遵循“识别-隔离-恢复”三步标准范式： -1. **故障识别**：终端通过保护动作信号、电流突变或电压跌落等特征量，结合 [[三遥协同机制]] 快速判定故障发生及大致区段。 -2. **故障隔离**：系统向故障区段两侧的终端（如 DTU 或 FTU）下发遥控指令，跳开相关开关，将故障点从运行网络中物理切除，防止事故扩大。 -3. **供电恢复**：在确认故障隔离后，系统自动重构网络拓扑，合上联络开关或备用电源开关，恢复非故障区间的正常供电。 - -## 终端层执行角色 -[[DTU]] 作为站所级核心执行单元，在自愈逻辑中承担关键任务： -- **多回路并发管理**：站所内通常包含多条进出线，DTU 需准确识别故障所属回路，避免误切健康线路。 -- **主站协同与就地后备**：优先采用主站集中式 FA（馈线自动化）策略；当通信中断时，DTU 可切换至就地分布式逻辑，基于对端信号或电压检测自主完成隔离与恢复。 -- **时序约束**：自愈过程对实时性要求极高，从故障发生到隔离恢复通常需在秒级甚至亚秒级完成，依赖终端硬件的快速采样与协议栈的低延迟传输。 - -## 演进方向 -随着边缘计算与人工智能技术的引入，故障自愈逻辑正从传统的规则驱动向数据驱动演进。未来 DTU 将集成更强大的边缘智能算法，支持即插即用配置、自适应拓扑识别及复杂故障（如间歇性故障、高阻接地）的精准研判，进一步提升配电网的自治能力。 \ No newline at end of file diff --git a/wiki/entities/dtu-站所终端.md b/wiki/entities/dtu-站所终端.md deleted file mode 100644 index 8a03dd1..0000000 --- a/wiki/entities/dtu-站所终端.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -type: entity -title: "DTU（站所终端）" -created: 2024-05-20 -updated: 2024-05-20 -tags: [配电自动化, 终端设备, 站所级控制, 电力物联网] -related: [ftu-馈线终端, ttu-配变终端, rtu-远动终端, 配电主站, 三遥协同机制, 故障自愈逻辑] -sources: ["DTU/DTU（Distribution Terminal Unit）.md"] ---- -# DTU（站所终端） - -**DTU（Distribution Terminal Unit）**，即站所终端，是部署于中压配电网开关站、环网室、环网箱、配电室及箱式变电站等站所级节点的配电自动化核心执行单元。与单点控制的馈线终端不同，DTU 专为多回路、多设备的复杂站所场景设计，具备高并发数据采集、集中控制与站所级故障协同处理能力。 - -## 部署场景 -DTU 通常安装于中压配电网的关键节点，主要覆盖以下环境： -- 常规开闭所（站）与户外小型开闭所 -- 环网柜与环网箱 -- 小型变电站与箱式变电站 - -## 核心功能 -DTU 通过标准化接口与传感器/执行器交互，实现站所内电气设备的全面感知与精准控制： -- **数据采集**：实时采集开关设备位置信号、母线电压、出线电流、有功/无功功率、功率因数及电能量数据。 -- **控制操作**：接收上层指令或执行本地逻辑，对站内开关进行远程分合闸操作，并支持无功补偿电容器的自动投切。 -- **故障处理**：内置馈线开关故障识别算法，支持故障区间快速隔离与非故障区间供电恢复，显著提升供电可靠性指标（SAIDI/SAIFI）。 - -## 与同类终端的边界 -- **vs [[FTU（馈线终端）]]**：FTU 主要安装于柱上开关旁，服务单台开关设备；DTU 部署于站所内部，管理多台开关及更复杂的二次设备，具备更强的多回路并发管理能力。 -- **vs [[TTU（配变终端）]]**：TTU 专注于变压器运行状态监测与负荷管理；DTU 覆盖范围更广，强调控制能力与站所级协同。 -- **vs [[RTU（远动终端）]]**：RTU 为工业通用型远端测控单元；DTU 是电力配电领域的专用终端，深度适配电网通信规约与故障自愈业务流。 - -## 系统角色 -在 [[配电自动化]] 体系中，DTU 是终端层的关键节点。当 [[配电主站]] 通过 [[三遥协同机制]] 发现并确认故障后，DTU 负责执行具体的遥控指令，完成故障隔离与负荷转供，是保障配网快速自愈的物理执行基础。 \ No newline at end of file diff --git a/wiki/index.md b/wiki/index.md deleted file mode 100644 index 7e9ee14..0000000 --- a/wiki/index.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -type: index -title: Wiki 索引 -created: 2024-01-01 -updated: 2024-05-20 -tags: [索引, 导航] -related: [] -sources: ["DTU/RTU（Remote Terminal Unit）.md"] ---- -# Wiki 索引 - -## 工业自动化与控制 -- [[PLC]] -- [[RTU（Remote Terminal Unit）]] -- [[三遥系统]] -- [[SCADA 系统]] -- [[工业物联网 (IIoT)]] - -## 边缘计算与硬件架构 -- [[边缘网关]] -- [[嵌入式实时系统 (RTOS)]] -- [[工业通信协议]] - -## 电力与能源自动化 -- [[配电自动化]] -- [[DTU（配电终端）]] -- [[智能电网]] - -## 数据与通信 -- [[Modbus]] -- [[OPC UA]] -- [[IEC 60870-5-104]] \ No newline at end of file diff --git a/wiki/log.md b/wiki/log.md deleted file mode 100644 index 84e0f7d..0000000 --- a/wiki/log.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -type: log -title: "更新日志" -created: 2024-05-20 -updated: 2024-05-20 -tags: [日志, 版本记录] -related: [] -sources: ["DTU/DTU（Distribution Terminal Unit）.md"] ---- -# 更新日志 - -## [2024-05-20] ingest | DTU（Distribution Terminal Unit）源文档解析与终端层架构补充 -- 新增源摘要页面，结构化提取站所终端定义、部署场景、三遥能力及横向对比数据。 -- 创建实体页面 `dtu-站所终端`，明确其在配电自动化终端家族中的定位与多回路管理特性。 -- 创建概念页面 `三遥协同机制` 与 `故障自愈逻辑`，完善终端控制闭环与故障处理业务流描述。 -- 更新全局索引与概览，强化“主站-通信-终端”三层架构的知识关联。 -- 标记通信规约、硬件隔离设计与边缘计算能力为后续深度研究节点。 - -## [2024-05-15] update | 配电自动化系统架构梳理 -- 完善主站决策逻辑与终端执行边界说明。 -- 补充馈线自动化（FA）基础分类与典型应用场景。 - -## [2024-05-10] init | Wiki 初始化与基础词条构建 -- 建立核心导航结构、索引模板与日志规范。 -- 录入基础电力物联网与配电网自动化术语。 - ---- -type: log -title: 更新日志 -created: 2024-01-01 -updated: 2024-05-20 -tags: [日志, 维护] -related: [] -sources: ["DTU/RTU（Remote Terminal Unit）.md"] ---- -# 更新日志 - -## [2024-05-20] ingest | DTU/RTU（Remote Terminal Unit） -导入远端测控单元（RTU）核心概念与三遥系统定义。建立 RTU 与 PLC 的传统选型边界分析，补充电力配电终端（DTU/FTU/TTU）的派生关系说明。更新工业自动化与边缘计算分类索引。 \ No newline at end of file diff --git a/wiki/overview.md b/wiki/overview.md deleted file mode 100644 index 1b21e2a..0000000 --- a/wiki/overview.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -type: overview -title: Wiki 概述 -created: 2024-01-01 -updated: 2024-05-20 -tags: [概述, 架构] -related: [] -sources: ["DTU/RTU（Remote Terminal Unit）.md"] ---- -# Wiki 概述 - -本知识库致力于构建覆盖工业自动化、边缘计算与智能监控系统的综合性技术图谱。核心内容围绕现场控制硬件、通信协议栈及上位监控架构展开，旨在为工程师、架构师与研究人员提供从底层设备选型到系统集成的完整参考框架。 - -在工业控制硬件谱系方面，Wiki 详细梳理了可编程逻辑控制器（PLC）与远端测控单元（RTU）的功能定位与演进路径。通过引入“三遥系统”（遥信、遥测、遥控）标准，明确了边缘节点在数据采集、状态监视与远程指令执行中的基础交互模型。同时，针对电力配电自动化等垂直领域，文档阐述了通用 RTU 向专用终端（如 DTU、FTU）特化的技术分支，厘清了不同应用场景下的设备复用与协议适配关系。 - -随着工业物联网（IIoT）与云边协同架构的普及，传统控制设备的边界正逐步融合。本 Wiki 持续追踪现代 RTU 向智能边缘网关的转型趋势，涵盖多协议融合（Modbus、OPC UA、IEC 60870 等）、高环境适应性设计以及工业网络安全机制。未来内容将进一步扩展至嵌入式硬件架构选型、实时性保障策略及跨域数据集成方案，以支撑复杂工业场景下的系统设计与运维决策。 \ No newline at end of file diff --git a/wiki/sources/DTU/DTU（Distribution Terminal Unit）.md b/wiki/sources/DTU/DTU（Distribution Terminal Unit）.md deleted file mode 100644 index 6946b0e..0000000 --- a/wiki/sources/DTU/DTU（Distribution Terminal Unit）.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -type: source -title: "DTU（Distribution Terminal Unit）源文档摘要" -created: 2024-05-20 -updated: 2024-05-20 -tags: [配电自动化, 站所终端, 三遥, 电力物联网] -related: [dtu-站所终端, 三遥协同机制, 故障自愈逻辑, 配电主站] -sources: ["DTU/DTU（Distribution Terminal Unit）.md"] ---- -# DTU（Distribution Terminal Unit）源文档摘要 - -本文件为原始技术文档 `DTU/DTU（Distribution Terminal Unit）.md` 的结构化摘要。源文档系统阐述了站所终端（DTU）在中压配电网自动化体系中的定位、部署场景、核心功能及业务逻辑。 - -## 核心内容概述 -- **定义与定位**：DTU 是安装于开闭所、环网室、箱变等站所级节点的配电自动化终端，属于“主站-通信-终端”三层架构中的核心执行单元。 -- **功能矩阵**：具备完整的三遥能力（遥信采集开关位置与告警、遥测电压电流与电能、遥控分合闸与电容器投切），支持多回路并发管理与站所级设备协同控制。 -- **业务闭环**：明确描述了“故障识别-区间隔离-非故障区恢复”的自愈逻辑，强调 DTU 与 [[配电主站]] 的指令交互链路及实时响应要求。 -- **横向对比**：清晰界定 DTU 与单点控制的 [[FTU]]、专变监测的 [[TTU]] 以及工业通用型 [[RTU]] 的应用边界与架构差异。 - -## 知识价值 -该源文档为配电自动化终端层提供了标准化的业务描述，强化了多回路站所场景下的控制范式。内容可直接用于完善终端设备分类图谱、主站协同机制说明及故障处理时序建模。后续可结合通信规约（如 IEC 61850/104）、硬件隔离设计与边缘计算能力进行底层技术扩展。 \ No newline at end of file diff --git a/wiki/sources/DTU/RTU（Remote Terminal Unit）.md b/wiki/sources/DTU/RTU（Remote Terminal Unit）.md deleted file mode 100644 index 637fa4f..0000000 --- a/wiki/sources/DTU/RTU（Remote Terminal Unit）.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -type: source -title: "DTU/RTU（Remote Terminal Unit）" -created: 2024-05-20 -updated: 2024-05-20 -tags: [工业自动化, SCADA, 边缘计算, 电力自动化] -related: [rtu-remote-terminal-unit, 三遥系统] -sources: ["DTU/RTU（Remote Terminal Unit）.md"] ---- -# 源摘要：DTU/RTU（Remote Terminal Unit） -本文档主要阐述了远端测控单元（RTU）在工业自动化与 SCADA 系统中的核心定位。内容涵盖 RTU 的基础定义、典型部署场景（如石油化工、智能制造），以及其与可编程逻辑控制器（PLC）在传统架构下的能力对比。文档重点介绍了工业监控的“三遥”标准能力集（遥信、遥测、遥控），并简要提及了电力配电自动化领域专用终端（DTU/FTU/TTU）与通用 RTU 的派生关系。该源文件为构建工业控制硬件谱系与边缘节点知识树提供了基础概念框架，但在具体通信协议栈、硬件架构选型及现代设备融合趋势方面留有进一步扩展空间。 \ No newline at end of file