dsh-sop-agent-teams

SOP 驱动的通用业务 Agent Team 插件，运行在 DeepSeek Harness（DSH）之上。

主 Agent / 子 Agent 的角色、模型、工具、数据契约全部可配置；
Agent 招聘模块：所有工作流的成员 Agent 统一收录在共享招聘池管理与修改（说明、技能、persona、模型、工具清单），实时显示被哪些工作流引用；任何工作流都可从池中录用成员；主 Agent 规划（sop_plan/sop_amend）与人工定义都会自动收录成员；
技能管理模块：团队共享技能库——安装/编辑/删除技能，启用后注册进 DSH 技能目录，队长与所有成员 Agent 都能通过 skill 工具调用；支持从 DSH 现有技能一键导入；招聘池成员配置技能时优先展示库中技能；
SOP 既可人预定义（sops/*.yaml），也可由主 Agent 主动规划（sop_plan）并运行中调整（sop_amend）；
配置好后按 SOP（节点编排 + 依赖 + 质量门 + 人工关卡 + 回退）自动跑任务：成员空闲时调度器自动领取就绪节点并唤醒；
每一步在可视化看板上可观测（运行看板、任务详情、审批中心、Agent招聘、工作流设置、定时任务、产出物）；审批中心可直接点击通过/驳回（无需在对话中操作）；定时任务可按 cron 自动运行指定 SOP；
工作流版本管理（同一工作流的升级版本合并展示、一键回退）、结构化表单编辑器（分区配置：成员/数据表/节点/关卡/回退/规划，无需手写 YAML）、删除工作流（有活动实例时保护性拒绝）；新增工作流可直接从招聘池勾选成员；
状态持久化到磁盘（真相源），支持冷恢复、归档复盘、全量审计事件。

设计来源：Claude Code Agent Teams（共享任务列表/依赖解锁/人工审批/角色模板），业务建模参考《风控业务 Agent Team》文档（7 角色闭环 + 统一工作台 + 双层状态机 + Context Bundle）。

快速开始

# 1. 构建（或从发布包安装）
pnpm install && pnpm build

# 2. 安装到 DSH profile（web 或 headless）
dsh plugin --profile web add .

# 3. 校验组合配置并启动
dsh --profile web --dump-config
dsh web

在会话中对主 Agent 说：

运行 risk-control-daily SOP，目标：降低支付盗刷漏召率，误杀率不超过 1%。

或者让主 Agent 现场规划：

治理支付盗刷漏报，先做一轮专项，上线必须有我确认。

主 Agent 会调用 sop_create_instance（已有 SOP）或 sop_plan（现场规划，默认进审批中心）启动流程。Web 界面右上角出现 SOP 工作台 浮层（运行看板 / 任务详情 / 审批中心 / Agent招聘 / 工作流设置 / 定时任务 / 产出物）。工作流支持版本管理与回退、结构化表单编辑、删除，人工新增的工作流默认标记为人工定义。

核心概念

概念	说明
SOP 定义	一组可配置的业务流程：agents（角色）+ tables（数据契约）+ steps（节点 DAG）+ manual_gates + rollbacks + planning + prompts
实例	一次业务运行（investigation/工单/专项），`instance_id` 串联所有数据；每个实例一个主 Agent（captain）
招聘池（Agent 招聘模块）	全局共享的成员 Agent 人才池：工作流成员自动收录、可统一管理修改、可被任意工作流录用；实时计算每个成员被哪些工作流引用
节点任务	双层状态机：实例阶段（running/waiting-human/monitoring/closed…）+ 任务状态（pending→claimed→in_progress→completed/failed/cancelled，带 attempt_id）
Context Bundle	任务只存引用；执行前按节点 inputs 组装上下文，四层拼装执行提示词（角色层 + 任务层 + 上下文层 + 协议层）
事件调度	成员 idle → 调度器原子领取就绪任务 → 唤醒成员；被动推送为主、主动 claim 为辅；冷重启自动恢复
质量门 / 人工关卡	声明式规则（`表.字段非空率 == 100%`）；人工关卡将节点置为 waiting-human，审批通过继续、驳回回退
动态规划	`sop_plan` 现场设计 SOP（受 planning 约束：scope/agent_source/max_steps/max_depth），变更进审批中心并可版本回滚

模型工具（`sop_*`）

工具	使用者	作用
`sop_create_instance`	主 Agent	按 SOP 定义创建运行实例
`sop_status`	全员	实例全景：节点/任务/成员/待审/进度
`sop_claim_task`	成员	显式领取任务（引擎原子校验）
`sop_update_task`	成员	携带 attempt_id 推进任务（completed/failed + 质量门）
`sop_assign`	主 Agent	指派/转派（撤销旧 attempt 重新排队）
`sop_message`	全员	成员间/向主 Agent 直达消息（邮箱持久化 + 唤醒，拒冒名）
`sop_approve`	主 Agent	决定人工关卡（grant/reject + 意见）
`sop_rollback`	主 Agent	回退到指定节点（下游子图整体重跑）
`sop_plan`	主 Agent	现场规划新 SOP（校验 + planning 约束 + 审批；成员自动收录进招聘池）
`sop_amend`	主 Agent	运行中调整 SOP（结构变更走审批；成员变更同步招聘池）
`sop_archive`	主 Agent	结束实例并归档（含复盘结论入共享记忆）
`sop_recruit_list`	主 Agent	招聘池全景：共享成员 Agent + 技能 + 被哪些工作流引用
`sop_recruit_add`	主 Agent	招聘新成员 Agent（说明 / 技能 / systemPrompt / 模型 / 工具）
`sop_recruit_update`	主 Agent	更新招聘池成员配置（局部字段）
`sop_recruit_remove`	主 Agent	删除招聘池成员（被工作流引用时拒绝并列出引用方）
`sop_recruit_hire`	主 Agent	从招聘池录用成员进任意工作流（按 ID 去重）
`sop_skill_list`	主 Agent	团队技能库全景（描述/启用状态/被哪些成员引用）
`sop_skill_install`	主 Agent	安装新技能（全字段，或 from_existing 从 DSH 目录导入）
`sop_skill_update`	主 Agent	编辑技能（局部字段；enabled=false 停用不注册）
`sop_skill_remove`	主 Agent	删除技能（成员标签引用仅提示不阻断）

示例 SOP

sops/risk-control-daily.yaml —— 风控每日漏召治理（7 角色闭环，参考《风控业务 Agent Team》文档建模）
sops/customer-complaint.yaml —— 客服工单处理（同一插件换配置即换业务）

开发

pnpm install
pnpm typecheck   # host + client 类型检查
pnpm test        # 核心逻辑单测（DSL/质量门/调度器/存储/提示词拼装/示例 SOP）
pnpm build       # tsc host + tsc client + tsdown 客户端打包
pnpm verify      # 以上全部

已知问题

当前 DSH 构建的 spawn continuable 成员激活失败：成员被创建、领取任务、收到唤醒消息，但执行轮次以 error 结束且无输出（GUI 与 headless 一致，已用最小 e2e 复现）。解法：profile 中配置 memberProvider: fork（fork 下成员独立执行完整链路已验证通过）：
```
# profile 的 cordis.patch.yml
- id: sop-agent-teams
  config:
    memberProvider: fork
```
成员模型路由：成员缺省继承队长路由；若 SOP 中给成员写死 model，该模型必须是环境已配置的路由（示例 SOP 不写死模型）。

发布

pnpm verify
pnpm publish                # npm 发布（package.json 已含 publishConfig）
# 或 GitHub 方式：git tag v0.1.0 && git push origin v0.1.0

用户安装（三种方式）

# 1) npm 包
dsh plugin --profile web add dsh-sop-agent-teams

# 2) GitHub 仓库（git 依赖，无需 npm 发布）
dsh plugin --profile web add git+https://github.com/KarmaX/dsh-sop-agent-teams.git

# 3) 本地目录（开发调试）
dsh plugin --profile web add /path/to/dsh-sop-agent-teams

安装后校验组合配置并启动：dsh --profile web --dump-config && dsh web；重启后浏览器右上角出现 Agent teams 工作台 即生效。

文档

docs/user-guide.md —— 使用指南（安装确认、三种用法、完整示例、看板操作、自定义 SOP、故障排查）
docs/dsl-reference.md —— SOP DSL 完整参考（agents/tables/steps/manualGates/rollbacks/planning/prompts/trigger）

许可证

MIT

dsh-sop-agent-teams

Installer

README