📦 @goodandready/dsh-agent-orchestrator

---

⚡ 概述与解决的核心痛点

在执行复杂的多阶段工程任务时，单一智能体架构往往面临认知过载：在单一上下文请求中混合了系统架构、界面布局、前端交互、服务端逻辑、单元测试与文档编写，极易导致接口幻觉、功能退化与不必要的 Token 浪费。

此外，各子智能体的独立执行通常会中断大语言模型的 KV 缓存复用，失去前缀提示词缓存（Prompt Caching）的优势，产生严重的首次响应延迟 (TTFT) 与高昂的推理成本。

@goodandready/dsh-agent-orchestrator 为 DeepSeek Harness 提供完整的自主多智能体编排方案：

1. 智能分流与任务分解：深度解析来自聊天或看板卡片的目标，拆解并分发给 12 个专属智能体角色。
2. 有向无环图 (DAG) 引擎：基于依赖拓扑结构并行调度无阻塞子任务，严格保障阻断检查点。
3. KV 缓存 / Prompt Caching 优化器：确保同模型智能体之间保持字节级的前缀一致性，释放 80–90% 的缓存命中率并实现极速首字输出。
4. 严格的权责分离：服务端后端、UI 界面设计与客户端前端实现各自保持独立的角色与执行阶段，杜绝单一智能体跨界混写。
5. 双场景原生集成：支持在 DSH 聊天中通过 /orchestrate 斜杠命令直接调用（带顶部吸顶里程碑卡片），亦可无缝接入 @goodandready/dsh-kanban 看板。

---

🏗️ 系统架构图

graph TD
    Trigger["输入任务<br/>(聊天中 /orchestrate 或看板卡片)"] --> Main["主调度器 (分流与规划)"]
    
    subgraph Engine ["DAG 调度引擎与提示词缓存优化"]
        L1["第 1 层：规范化基础锚点 (>1024 Token)"]
        L2["第 2 层：共享任务上下文锚点"]
        L3["第 3 层：阶段累计产物 (仅追加模式)"]
        L4["第 4 层：角色专属后缀指令"]
    end

    Main --> Engine

    subgraph AgentPool ["配置化智能体角色池 (完全内聚于插件设置)"]
        R1["需求分析师"]
        R2["系统架构师"]
        R3["UI/UX 设计师"]
        R4["后端工程师"]
        R5["前端工程师"]
        R6["QA 自动化工程师"]
        R7["技术文档专家"]
    end

    Engine --> AgentPool
    AgentPool --> Delivery["编排交付<br/>(顶部状态卡片与看板状态同步)"]

---

👥 12 大内置专属智能体角色矩阵

所有智能体预设均完全内聚于插件设置面板中（无需依赖本地额外配置文件）：

角色 ID	角色名称	核心专业领域	严格职责边界
spec	需求分析师	功能规范、验收准则 (DoD)、数据结构定义	严禁编写业务实现代码或样式
architecture	系统架构师	架构设计、DESIGN.md、ADR 决策、模块契约	严禁编写生产代码或执行部署
ui_design	UI/UX 设计师	界面布局、主题变量 (--dsw-alias-*)、插槽设计	严禁编写服务端 Cordis 服务逻辑
frontend	前端工程师	React 组件、客户端 Hooks、DOM 交互与事件	严禁修改后端路由或数据库存储
backend	后端工程师	Cordis 服务、WebServer 路由、状态与持久化	严禁编写客户端 React JSX 或前端 CSS
fullstack	全栈集成师	端到端契约对接、全链路串联打通	严格遵守模块化边界规范
qa_tests	QA 自动化工程师	原生单元测试 (node:test)、边界用例覆盖	仅限无外网依赖的纯净验证
bugfix	缺陷修复专家	根因精准定位、最小爆炸半径修复	严禁重构无关代码
docs	技术文档专家	英中俄三语文档编撰 (en/ru/zh)、发行注记	严禁覆盖或删除旧版有效文档
refactoring	重构精简专家	复杂度裁剪 (YAGNI)、代码瘦身与体积压缩	必须严格保持向前兼容
research	前沿探索工程师	技术选型评估、多方案 Spike 对比验证	输出分析报告，严禁直接合并 Spike 代码
devops	运维与工具工程师	包清单规范化、打包构建校验、systemd 守护	严禁泄露内部网络凭证与私钥

---

🔄 复杂度编排场景

1. Hotfix / 紧急缺陷 (1 阶段)：即时消除单一 Bug 或调整单项配置参数。
2. Simple / 简易任务 (2 阶段)：方案讨论与规范 $ ightarrow$ 靶向执行交付。
3. Medium / 中型需求 (3–4 阶段)：需求分析 $ ightarrow$ 界面设计 $ ightarrow$ 前端编码 $ ightarrow$ QA 自动化测试。
4. Complex / 复杂项目 (5–6 阶段)：需求分析 $ ightarrow$ 系统架构 $ ightarrow$ 界面设计 $ ightarrow$ 全栈实现 $ ightarrow$ QA 验收 $ ightarrow$ 三语文档。
5. Enterprise / 深度研发 (7 阶段)：技术评估 Spike $ ightarrow$ 需求分析 $ ightarrow$ 系统架构 $ ightarrow$ 后端与 UI 并行开发 $ ightarrow$ 前端集成 $ ightarrow$ 全面 QA $ ightarrow$ 文档网关验收。
6. 自定义 DAG 场景：在插件设置面板自由增删阶段、配置依赖关系与阻断检查点。

---

⚡ 提示词缓存 (Prompt Caching) 底层原理

主流大语言模型严格从第一个 Token 开始构建并复用 KV 缓存。如果在 Prompt 开头混入不确定性的时间戳或随机 ID，缓存命中率将骤降至 0%。

dsh-agent-orchestrator 强制采用 4 层规范化布局：

1. 第 1 层：静态基础锚点 (>1024 Token)：所有智能体共享的字节级完全一致的规则与工具说明。
2. 第 2 层：共享任务上下文锚点：用户核心目标与目标仓库的稳定描述。
3. 第 3 层：阶段累计产物 (仅追加模式)：前序阶段产物按确定性顺序追加，完全保留前置 KV 缓存。
4. 第 4 层：角色专属后缀指令：智能体角色人设、技能指导与当前子任务专属指令置于最末端。

此架构能够使共享同一模型的子智能体达到 80–95% 的缓存命中率，极大降低首字生成延迟并将 Token 消耗降低约 90%。

---

💻 使用指南

1. 在 DSH 聊天中通过斜杠命令触发

/orchestrate 为财务管理插件设计并开发设置卡片

显式指定复杂度预设：

/orchestrate complex 构建多租户身份认证提供商服务
/orchestrate hotfix 修复 store.js 中的空指针异常

简明别名：

/orc 重构状态管理模块

2. 在 @goodandready/dsh-kanban 看板中协作

• 打开看板上的任意任务卡片。
• 点击 [Собрать пайплайн / 装配工作流]。
• 选择复杂度预设或采用自动分流。
• 任务卡片实时展示各阶段进度，任务完成自动推进至 Review 状态。

---

🧪 自动化测试与打包验证

执行原生测试套件（121 个用例全部通过，零外部网络依赖）：

node --test test/*.test.mjs

验证 npm 打包体积合规性（严格低于 256 KiB 上限）：

npm pack --dry-run --json

---

🖼️ 视觉设计验收效果

v0.1.6 生产环境验收效果 — 设置面板暗色与亮色主题对照：

---

📄 开源协议

MIT © GooDAnDReaDY