LeeGuanWei-a/dsh-arch-advisor

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

本插件封装开源知识库 awesome-architecture，
故工具以 arch_ 命名、文中多处保留该知识库原名。

English · 中文

一句话说明

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

安装后，你在对话里聊系统设计、业务建模、写开发文档时，模型会自动调用本插件提供的
7 个 arch_ 工具——实时查阅开源知识库
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 → 按版本快照规范建档，后续改动留历史

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

安装

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

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

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

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。不联网时目录/学习路径仍可用（内置），但读正文会提示网络不可达。
问：和上游知识库 study8677/awesome-architecture 是什么关系？
答：本插件是知识库的“对话化封装”，不包含其内容、不改写其内容。两者都是 MIT，用本插件即自动使用最新上游内容。

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

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

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

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

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

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

开发

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

Credits / 致谢

本插件的知识内容全部来自开源项目
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 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:

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 (MIT).
感谢作者和所有贡献者。原始内容请参见上游仓库。