# DSH 架构与开发文档

本目录保存 DSH 数据源平台的长期架构约束、开发准则、AI 上下文规则、数据源特殊说明以及阶段性实施计划。

文档分为三类。

使用插件先读[中文首页](../README.zh.md)或[English README](../README.md)。Kafka 的完整命令、认证、结果上限和写入约束见[中文使用指南](datasource/kafka.md)／[English guide](datasource/kafka.en.md)。

## 1. 长期稳定文档

### data-source-onboarding.md

新增数据源的可执行接入指南：当前类型、静态注册、模块接口、调用链、模拟源验收和发布隔离。新增源时先读此文，再按需读架构及专属文档。

### data-source-architecture.md

定义系统是什么、公共底座负责什么、数据源负责什么，以及长期不可破坏的架构边界。

涉及以下任务时必须阅读：

- 新增数据源
- 修改公共底座
- 修改 Workspace
- 修改执行主流程
- 修改 AI/人工协作
- 修改 History / Knowledge
- 大规模跨模块重构
- 判断某能力应该公共还是数据源专属

### development-guidelines.md

定义代码质量和长期维护规则。

重点约束：

- 重复代码
- 重复流程
- 重复 UI / 样式 / 交互
- 重复状态
- 第二套系统
- 过度设计
- God File / God Service
- sourceType 分支泛滥
- 调用链复杂化
- 死代码
- 兼容代码堆积
- AI 阅读成本

### ai-context-guide.md

定义 Cursor / AI 在不同任务下应该读取哪些资料，避免所有任务都加载全部架构文档。

目标是：

“需要多少上下文，就读取多少上下文。”

## 2. 数据源文档

目录：

docs/datasource/

只记录某一种数据源真正特殊的行为和约束。

不要在这里重复公共 Workspace、AI、History、Knowledge 等公共体系。

## 3. 实施计划

目录：

docs/plans/

计划文档用于某一次具体重构或开发。

计划可以很详细，包括：

- 文件
- 方法
- 调用链
- 阶段
- 测试
- 验收
- 停止条件

但计划不是永久架构真理。

如果真实代码与旧计划发生明显变化，应重新验证，而不是机械执行旧计划。

长期边界优先参考 architecture 和 guidelines，具体施工参考当前 plan，最终事实以当前代码和实际验证结果为准。

阶段验收按日期记录：[执行边界修复（2026-10-05）](plans/execution-boundary-implementation.md)、[Kafka 排障扩展（2026-10-04～05）](plans/kafka-repair-implementation.md)、[剩余闭环与适配层收敛（2026-10-03）](plans/remaining-closure-implementation.md)。各记录只证明当时的版本与覆盖范围；后续源码、安装环境和真实模型须核对对应报告。

## 当前代码评审

- [提交前代码评审与验证（2026-10-09）](code-review-2026-10-09.md)：本轮发现、修复、801 项测试及浏览器／打包验证边界。