dsh-arch-advisor

Readme

# dsh-arch-advisor · DeepSeek Harness 架构顾问插件

> 本插件封装开源知识库 [awesome-architecture](https://github.com/study8677/awesome-architecture)，
> 故工具以 `arch_*` 命名、文中多处保留该知识库原名。

[English](#english) · 中文

## 一句话说明

**给你的 DeepSeek Harness 装上一位"读过架构书"的架构顾问。**

安装后，你在对话里聊系统设计、业务建模、写开发文档时，模型会自动调用本插件提供的
7 个 `arch_*` 工具——实时查阅开源知识库
[awesome-architecture](https://github.com/study8677/awesome-architecture)
（40 篇架构教程、31 个真实系统架构模板、6 个端到端案例），
并按成熟方法论一步步引导你，**而不是凭模型自己的记忆泛泛而谈**。

> 它和上游知识库的关系：知识库是"内容书"，本插件是把书放进对话的工具。
> 装之前，模型只能凭印象回答"这个系统大概怎么做"；装之后，它能引用书里的方法、模板与案例，
> 和你逐条讨论并产出可落盘的开发文档。

---

## 装前 vs 装后

| | 装之前 | 装之后 |
|---|---|---|
| 你问"我想做一个内部批量数据处理系统" | 模型凭经验给一段通用建议 | 模型先检索最贴近的架构模板/案例（arch_ask），再按阶段引导你澄清需求（arch_design） |
| 你问"支付系统该注意什么" | 零散列举 | 直接打开真实支付系统架构图，精读"关键决策与权衡/常见误区"（arch_read） |
| 你要求"生成需求文档/概要设计" | 模型自由发挥格式 | 按标准章节骨架产出，附完成标准清单（arch_docs），并按版本快照规范建档（arch_version） |
| 你要复习系统设计面试 | 想到哪问到哪 | 按学习路径检索高频考点（arch_roadmap + arch_search） |

---

## 安装后得到什么：7 个工具，分三组

### 📖 组一 · 查：把知识库当资料书翻
| 工具 | 用途 |
|---|---|
| `arch_roadmap` | 知识库总览与学习路径（教程六阶段/模板分类/案例） |
| `arch_search` | 目录关键词检索（中/英，匹配标题/主题/代表产品） |
| `arch_read` | 读某篇正文：先给目录+开头预览，可切中/英文、取全文 |

### 💬 组二 · 聊：把"想法"推进成"方案"
| 工具 | 用途 |
|---|---|
| `arch_ask` | 输入你的想法 → 自动映射到最相关的 教程+模板+案例，抓摘录给建议路线 |
| `arch_design` | 分步引导式设计：需求澄清 → 约束/质量属性 → 结构 → 关键决策 ADR → 演进路线 → 生产级审查，每步与你逐条讨论 |

### 📝 组三 · 写：把"方案"落成"开发文档"
| 工具 | 用途 |
|---|---|
| `arch_docs` | 开发文档规范：需求(prd)/概要(hld)/详细(lld)/数据库(dbd)/架构(arch) 的章节骨架 + 完成标准 checklist |
| `arch_version` | 开发文档版本管理规范（当前版 + archive 历史快照约定） |

---

## 典型使用流程（一次完整会话）

> **用户**：帮我设计一个内部批量数据处理系统，要导入校验、有业务流转，还要统计报表。
>
> **模型**（自动调工具，你在对话里看到的是结果）：
> 1. `arch_ask(question=…)` → 定位到「模块化单体」案例 + 相关教程
> 2. `arch_read(case:patchdesk-saas)` → 精读真实同类系统架构
> 3. `arch_design(clarify)` → 按清单与你逐条澄清（谁用/量级/顺序关系/一致性…）
> 4. `arch_design(decisions)` → 定关键取舍，形成 ADR
> 5. `arch_docs(prd)` → 按标准骨架产出需求文档，落盘到工作区
> 6. `arch_version` → 按版本快照规范建档，后续改动留历史

> 你不用记工具名——模型会根据你的话自动选择合适的工具调用。

---

## 安装

```sh
# GitHub 直装（当前分发方式）
dsh plugin --profile web add github:LeeGuanWei-a/dsh-arch-advisor

# 发布到 npm 后也可
dsh plugin --profile web add dsh-arch-advisor
```

重启（或 HMR 生效）后，在新会话/现有会话刷新即可使用。验证：

```sh
dsh plugin --profile web list        # 应看到 dsh-arch-advisor
# 然后随便开个会话问：你觉得一个电商秒杀系统要注意什么？
# 观察模型是否会调用 arch_search / arch_read
```

---

## 工作原理

- **Host 常驻插件**：通过 `cordis.patch.yml` 插入 profile 组合层，安装一次、重启后常驻（非会话级临时插件）。
- **内容运行时拉取**：读取知识库原文时先走 `raw.githubusercontent.com`，失败自动回退 GitHub Contents API；**永远拿到最新内容**，插件包本身零体积。
- **中文为主**：界面与摘录默认中文；教程 01-34 与全部模板/案例有英文版，`arch_read` 可 `lang: en` 切换。

---

## 常见问题

**Q：对 DeepSeek Harness 有最低版本要求吗？**
A：已在 **dsh 0.1.2-rc.1** 验证可用。本插件按 cordis 4 体系编写，peer 依赖 `@deepseek-ai/cordis ^4.0.1` 与 `@deepseek-ai/dsh-tools`，安装时 pnpm 会自动做 peer 校验——版本过旧的 host 会被直接拦截并提示，不会静默失败。建议使用能正常运行 dsh-market 的版本（约 ≥ 0.1.0-rc.6）；更早版本未验证，如遇问题请报 `dsh --version`。

**Q：必须联网吗？**
A：是。内容运行时从 GitHub 拉取，需要能访问 GitHub。不联网时目录/学习路径仍可用（内置），但读正文会提示网络不可达。

**Q：和上游知识库 [study8677/awesome-architecture](https://github.com/study8677/awesome-architecture) 是什么关系？**
A：本插件是知识库的"对话化封装"，不包含其内容、不改写其内容。两者都是 MIT，用本插件即自动使用最新上游内容。

**Q：模型会乱用这些工具吗？**
A：工具只在相关话题（系统设计/架构/开发文档）被调用；每个工具有明确触发场景描述。

**Q：适合谁？**
A：正在设计系统的人、写需求/设计文档的开发与产品、准备系统设计面试者、想让 AI 产出"有依据的方案"的任何人。

**Q：用本插件做出来的文档目录结构是固定的吗？会像某个示例项目那样吗？**
A：目录**组织方式**是固定的（这也是 `arch_version` 工具的规范），但文档**名字和内容**完全跟着你的项目走。规则只有两条：
- 项目根下建 `docs/`，第一层放**当前有效文档**（无后缀 = 最新版）；
- 每次定稿新版本，先冻结一份到 `docs/archive/<文档>-vX.md` 再改当前文件，历史版永久可查。

实际产出的样子（示例项目"金融数据加工系统"）：

```
<你的项目>/
└── docs/
    ├── <项目名>-架构方案.md          ← 当前版（无后缀，永远最新）
    ├── <项目名>-需求文档.md
    ├── <项目名>-概要设计.md
    ├── <项目名>-详细设计.md
    ├── <项目名>-数据库设计.md
    └── archive/                    ← 历史版本快照（每版独立文件，双击即看）
        ├── <项目名>-需求文档-v0.1.md
        ├── <项目名>-需求文档-v0.2.md
        └── …（其余文档各自的 -v0.1 基线）
```

把 `<你的项目>`/`<项目名>` 换成你实际的项目即可——文档内容由你的业务决定，
插件只保证"当前版 + 历史归档"这套不丢版本的结构。

---

## 开发

```sh
npm install
node --check lib/index.js        # 语法检查
# 无构建步骤（纯 ESM JS）
```

---

## Credits / 致谢

本插件的知识内容全部来自开源项目
[study8677/awesome-architecture](https://github.com/study8677/awesome-architecture)
——《Awesome Architecture · 架构图谱》：40 篇双语架构教程、31 个真实系统架构模板与 6 个端到端案例，
覆盖分布式系统、AI 原生系统、RAG、编码 Agent 与生产取舍。它「只讲判断、不讲语法」的理念，
正是本插件把架构顾问带进对话的基石。

感谢作者 **study8677** 与所有贡献者整理并开源这份高质量知识库（MIT 协议）。
如需查阅原始内容或贡献知识，请前往上游仓库。

---

## English

**An in-chat architecture consultant for DeepSeek Harness.**

Install once, and the model gains 7 `arch_*` tools that query the open-source
[awesome-architecture](https://github.com/study8677/awesome-architecture) knowledge base
(40 tutorials, 31 real-system templates, 6 end-to-end cases) in real time — so it can design,
discuss trade-offs, and produce engineering documents from a real methodology instead of memory.

Three capability groups:
- **Read** — `arch_roadmap` / `arch_search` / `arch_read`: browse, search, read the knowledge base (zh/en).
- **Discuss** — `arch_ask` (map your idea to docs) / `arch_design` (step-by-step guided design: clarify → constraints → structure → ADR → roadmap → review).
- **Write** — `arch_docs` (PRD/HLD/LLD/DBD/arch section skeletons + checklists) / `arch_version` (doc version-snapshot rules).

**Install**:

```sh
dsh plugin --profile web add github:LeeGuanWei-a/dsh-arch-advisor
```

**How it works**: a persistent host plugin (cordis.patch.yml), content fetched live from GitHub
(raw first, Contents API fallback) — always current, zero bundled content. Requires network access to GitHub.

**Minimum dsh version**: verified on **dsh 0.1.2-rc.1**. Built on the cordis 4 stack with peer deps
`@deepseek-ai/cordis ^4.0.1` and `@deepseek-ai/dsh-tools`; pnpm peer checks reject hosts that are too old.
As a rough reference, hosts that can run dsh-market (≈ ≥ 0.1.0-rc.6) should work. Older versions are unverified.

**Credits**: all knowledge content comes from
[study8677/awesome-architecture](https://github.com/study8677/awesome-architecture) (MIT).
Thanks to the author and all contributors. See the upstream repo for the original content.