@nanmicoder/dsh-agent-teams 0.1.2 → 0.1.4

package/README.md

@@ -1,93 +1,134 @@
-# @nanmicoder/dsh-agent-teams
+<p align="right">
+  <strong>English</strong> · <a href="./README_ZH.md">简体中文</a>
+</p>
 
-[![npm](https://img.shields.io/npm/v/@nanmicoder/dsh-agent-teams.svg)](https://www.npmjs.com/package/@nanmicoder/dsh-agent-teams)
-[![license](https://img.shields.io/npm/l/@nanmicoder/dsh-agent-teams.svg)](LICENSE)
+<p align="center">
+  <img src="./assets/readme/hero.svg" width="100%" alt="dsh-agent-teams turns one DeepSeek Harness session into a coordinated multi-agent team">
+</p>
 
-DeepSeek Harness 的 AgentTeams 插件：安装后，任何会话只需一句自然语言（例如"用 AgentTeams 调研一下 XX"），即可驱动一个**多智能体团队**协作完成目标，并在 Web GUI 右上角实时看到团队活动面板。
+<p align="center">
+  <a href="https://www.npmjs.com/package/@nanmicoder/dsh-agent-teams"><img src="https://img.shields.io/npm/v/@nanmicoder/dsh-agent-teams.svg" alt="npm version"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/@nanmicoder/dsh-agent-teams.svg" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/DeepSeek%20Harness-plugin-202724" alt="DeepSeek Harness plugin">
+</p>
 
-核心语义移植自 Claude Code 的 AgentTeams：**创建团队**（队长 = 当前会话 agent）→ **拉成员**（可续聊子代理）→ **拆任务并声明依赖** → **成员间直接收发消息**（邮箱直达 + 唤醒，无队长中转）。
+## One prompt. A working team.
 
-## 界面预览
+`dsh-agent-teams` turns the current DeepSeek Harness session into a captain that can assemble durable sub-agents, split a goal into dependency-aware tasks, and coordinate work through direct messages.
 
-![AgentTeams 活动面板](https://raw.githubusercontent.com/NanmiCoder/dsh-agent-teams/main/assets/ui.png)
+Ask in natural language. The plugin provides the team protocol, nine coordination tools, persistent state, and a live Web UI—without requiring a separate workflow engine.
 
-## 安装
+<p align="center">
+  <img src="./assets/ui.png" width="100%" alt="DeepSeek Harness conversation with the AgentTeams live activity panel, members, tasks, dependencies, and reports">
+</p>
 
-**前置要求**：已安装 [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness)（`dsh` 命令可用）；Node.js `^22.19` 或 `>=24`；pnpm 11。
+## Why AgentTeams?
 
-插件已发布到 npm（`@nanmicoder` scope），一条命令装好：
+| Capability | What it changes |
+| --- | --- |
+| **Captain-led delegation** | The current session creates the team, assigns roles, and consolidates the final result. |
+| **Durable members** | Members are continuable DSH sub-agents that can be woken for focused follow-up turns. |
+| **Dependency-aware tasks** | Tasks move through explicit states and cannot be claimed before their dependencies finish. |
+| **Direct messaging** | Members send durable mailbox messages directly to teammates or the captain—no relay required. |
+| **Live activity panel** | The Web UI shows roles, current work, unread messages, task dependencies, and archived team history. |
+
+## Install
+
+> [!NOTE]
+> Requires an existing [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) installation.
+
+### npm
 
 ```sh
 dsh plugin --profile web add @nanmicoder/dsh-agent-teams
 ```
 
-`dsh plugin` 会把插件加入 `web` profile，并根据包内的 `dsh.bundle` 声明自动启用它；工具、系统提示和 Web 客户端入口随该 profile 一起加载。
-
-> **重启生效**：安装完成后，重启正在运行的 DeepSeek Harness Web 服务并刷新页面。
+### Build from source
 
-装好后可以用 `dsh plugin --profile web list` 确认插件在列表里。升级用同一条 add 命令即可。
+```sh
+git clone https://github.com/NanmiCoder/dsh-agent-teams.git
+cd dsh-agent-teams
+pnpm install
+pnpm build
+dsh plugin --profile web add .
+```
 
-### 其他安装方式
+Run `pnpm build` again after changing the source. The local plugin install remains linked to this checkout.
 
-**指定版本**——`latest` 的解析可能受 registry 缓存影响（国内镜像源同步新版本通常有延迟），想钉死版本时：
+Validate the composed profile, restart DSH, and refresh the Web UI:
 
 ```sh
-dsh plugin --profile web add @nanmicoder/dsh-agent-teams@<version>
+dsh --profile web --dump-config
+dsh web
 ```
 
-版本号见 [npm 发布页](https://www.npmjs.com/package/@nanmicoder/dsh-agent-teams?activeTab=versions)。
+Then ask for a team directly:
 
-**还没装 DSH，或不想全局安装**——用 `npx` 直接跑，无需预装：
+> Use AgentTeams to review the commits after v0.5.3 from performance, security, and product perspectives. Return one consolidated report.
 
-```sh
-npx -p @deepseek-ai/dsh dsh plugin --profile web add @nanmicoder/dsh-agent-teams
-```
+## How it works
 
-**从 GitHub 安装**——想用尚未发布到 npm 的最新提交：
+1. The current session creates a team and becomes its captain.
+2. The captain adds role-specific members backed by continuable sub-agents.
+3. The goal becomes tasks with owners and explicit dependencies.
+4. Claimed tasks are dispatched through durable mailbox messages that wake each member.
+5. Members work, update task state, and report directly to the captain or one another.
+6. The captain presents the combined result, then archives the complete team record.
 
-```sh
-dsh plugin --profile web add github:NanmiCoder/dsh-agent-teams
-```
+Team state is stored under `<workspace>/.agent-teams/`; the Web panel reads that disk truth and combines it with live sub-agent activity.
 
-**从源码安装**——要改插件本身，或参与开发：
+Member creation is zero-interaction by default: the plugin snapshots the LLM provider, model, and reasoning effort actually used by the captain's current step, and restores that snapshot on later continuations. Only an explicit heterogeneous-team request (for example, “backend on provider A/model X, frontend on provider B/model Y”) supplies a member-specific `provider` + `model`; there is no per-member model or reasoning prompt.
 
-```sh
-git clone https://github.com/NanmiCoder/dsh-agent-teams.git
-cd dsh-agent-teams
-pnpm install
-pnpm build
-dsh plugin --profile web add "link:$(pwd)"
-```
+## Configuration
 
-`link:` 安装后，改完代码跑 `pnpm build` 即时生效，不必重装插件（客户端改动需刷新页面，host 侧改动需重启 dsh 服务）。提交前跑 `pnpm verify` 做离线校验。
+Defaults work without extra setup. A trusted profile can override member behavior:
 
-## 使用
+```yaml
+- id: agent-teams
+  config:
+    stateDir: .agent-teams
+    memberProvider: spawn
+    memberModel: deepseek-v4
+    memberMaxDepth: 1
+    maxMembers: 8
+```
 
-安装并重启后，直接对助手说：
+`memberProvider` is the sub-agent runtime backend (`spawn` / `fork`), not an LLM provider. Cross-LLM-provider routing uses the optional `provider` + `model` fields of `agent_teams_add_member`; `memberModel` is only a model default for all members.
 
-> 用 AgentTeams 帮我调研一下开源 RAG 框架的选型，输出对比报告
+## Boundaries
 
-插件内置提示段会指导模型按协议执行：建团队 → 按角色拉成员 → 拆任务声明依赖 → 领取并唤醒成员 → 轮询收集产出 → 汇报后删除（归档保留）。
+- One captain leads one active team at a time.
+- Members act only after they are woken; mail remains durable while a participant is idle.
+- State is file-backed and serialized within one DSH process; concurrent processes editing the same team are not coordinated.
+- The activity panel reports persisted state as-is. Models may occasionally finish work without performing the expected task-state update.
 
-## 开发 Skill
+See [docs/usage.md](./docs/usage.md) for the full tool reference, state model, Web UI behavior, configuration, and known limits.
 
-仓库按开放 Agent Skills 规范提供 [`dsh-plugin-development`](skills/dsh-plugin-development/SKILL.md)，可直接安装：
+## Plugin development Skill
+
+The repository also ships the open Agent Skills package [`dsh-plugin-development`](./skills/dsh-plugin-development/SKILL.md):
 
 ```sh
 npx skills add NanmiCoder/dsh-agent-teams --skill dsh-plugin-development
 ```
 
-`skills/dsh-plugin-development/` 是唯一权威源码；`.dsh/skills/` 保存供 DSH 在本仓库作为 cwd 时自动发现的跨平台镜像。修改 Skill 后运行 `pnpm sync:skill`，`pnpm verify` 会检查镜像没有漂移。
+## Documentation
+
+| Guide | Covers |
+| --- | --- |
+| [Usage](./docs/usage.md) | Architecture, UI behavior, tools, configuration, limits, and validation |
+| [Verification](./docs/verification-guide.md) | Offline, composition, real e2e, and GUI verification |
+| [Plugin development](./docs/developing-dsh-plugins.md) | Human-readable guide built from this plugin |
+| [README writing](./docs/readme-writing-guide.md) | Repository documentation conventions |
 
-## 文档
+## Development
 
-| 文档 | 内容 |
-|---|---|
-| [docs/usage.md](docs/usage.md) | 工作原理、Web UI 行为、工具一览、配置、已知限制、验证 |
-| [docs/verification-guide.md](docs/verification-guide.md) | 四层验证方法（离线 / 组合 / 真实 e2e / ego-browser GUI） |
-| [skills/dsh-plugin-development/SKILL.md](skills/dsh-plugin-development/SKILL.md) | 可通过 `npx skills` 安装的 DSH 插件开发 Skill |
-| [docs/developing-dsh-plugins.md](docs/developing-dsh-plugins.md) | 面向人类阅读的开发指南（本插件为样例） |
+```sh
+pnpm install
+pnpm build
+pnpm verify
+```
 
 ## License
 
-MIT
+[MIT](./LICENSE)

package/README_ZH.md

@@ -0,0 +1,134 @@
+<p align="right">
+  <a href="./README.md">English</a> · <strong>简体中文</strong>
+</p>
+
+<p align="center">
+  <img src="./assets/readme/hero.svg" width="100%" alt="dsh-agent-teams 把一个 DeepSeek Harness 会话变成可协作的多智能体团队">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@nanmicoder/dsh-agent-teams"><img src="https://img.shields.io/npm/v/@nanmicoder/dsh-agent-teams.svg" alt="npm 版本"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/@nanmicoder/dsh-agent-teams.svg" alt="MIT 许可证"></a>
+  <img src="https://img.shields.io/badge/DeepSeek%20Harness-plugin-202724" alt="DeepSeek Harness 插件">
+</p>
+
+## 一句话，拉起一支真正协作的团队
+
+`dsh-agent-teams` 让当前 DeepSeek Harness 会话成为队长：创建可续聊的子 Agent、把目标拆成有依赖的任务，并通过直达消息协调成员工作。
+
+你只需用自然语言提出目标。插件会提供团队协议、9 个协作工具、持久化状态和实时 Web UI，不需要额外的 Workflow 引擎。
+
+<p align="center">
+  <img src="./assets/ui.png" width="100%" alt="DeepSeek Harness 对话与 AgentTeams 实时活动面板，展示成员、任务依赖和回报">
+</p>
+
+## 为什么需要 AgentTeams？
+
+| 能力 | 带来的变化 |
+| --- | --- |
+| **队长式委派** | 当前会话负责建队、分配角色并汇总最终结果。 |
+| **可续聊成员** | 成员是可持续唤醒的 DSH 子 Agent，可以继续执行聚焦的后续轮次。 |
+| **带依赖的任务** | 任务有明确状态；依赖未完成时不能领取。 |
+| **成员直达消息** | 成员通过持久化邮箱直接联系队友或队长，不需要队长中转。 |
+| **实时活动面板** | Web UI 展示角色、当前工作、未读消息、任务依赖和归档历史。 |
+
+## 安装
+
+> [!NOTE]
+> 使用前请确保已安装 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)。
+
+### npm
+
+```sh
+dsh plugin --profile web add @nanmicoder/dsh-agent-teams
+```
+
+### 从源码构建
+
+```sh
+git clone https://github.com/NanmiCoder/dsh-agent-teams.git
+cd dsh-agent-teams
+pnpm install
+pnpm build
+dsh plugin --profile web add .
+```
+
+修改源码后请重新执行 `pnpm build`。本地安装会继续链接到当前源码目录。
+
+检查组合配置、重启 DSH，然后刷新 Web UI：
+
+```sh
+dsh --profile web --dump-config
+dsh web
+```
+
+接着直接用自然语言拉团队：
+
+> 使用 AgentTeams 审查 v0.5.3 之后的提交，分别从性能、安全和产品角度分工，最后输出一份汇总报告。
+
+## 工作方式
+
+1. 当前会话创建团队并成为队长。
+2. 队长按角色添加由可续聊子 Agent 驱动的成员。
+3. 目标被拆成有负责人和显式依赖的任务。
+4. 任务领取后，通过持久化邮箱投递并唤醒对应成员。
+5. 成员执行任务、更新状态，并直接向队长或其他成员汇报。
+6. 队长汇总结果，随后归档完整团队记录。
+
+团队状态保存在 `<workspace>/.agent-teams/`；Web 面板读取这份磁盘真相，并与实时子 Agent 活动合并展示。
+
+成员创建默认零交互：插件会快照队长**当前这一步**实际使用的 LLM provider、model 与思考强度，成员后续续跑仍使用这份快照。只有当用户明确提出异构分工（例如“后端用 provider A/model X，前端用 provider B/model Y”）时，队长才会把对应的 `provider` + `model` 传给该成员；不会逐个弹出模型或思考强度选择。
+
+## 配置
+
+默认配置可以直接使用。受信任的 Profile 可以覆盖成员行为：
+
+```yaml
+- id: agent-teams
+  config:
+    stateDir: .agent-teams
+    memberProvider: spawn
+    memberModel: deepseek-v4
+    memberMaxDepth: 1
+    maxMembers: 8
+```
+
+这里的 `memberProvider` 指子 Agent 的运行后端（`spawn` / `fork`），不是 LLM provider。跨 LLM provider 由 `agent_teams_add_member` 的可选 `provider` + `model` 参数表达；`memberModel` 只是所有成员的模型默认覆盖。
+
+## 使用边界
+
+- 一个队长同一时间只能带一个活动团队。
+- 成员被唤醒后才行动；参与者空闲时，消息会持久保存在邮箱中。
+- 状态使用文件持久化，并在单个 DSH 进程内串行操作；多个进程同时修改同一团队不保证一致。
+- 活动面板如实展示持久化状态；模型偶尔可能完成工作却没有按协议更新任务状态。
+
+完整工具列表、状态模型、Web UI 行为、配置与已知限制见 [docs/usage.md](./docs/usage.md)。
+
+## 插件开发 Skill
+
+仓库同时提供开放 Agent Skills 包 [`dsh-plugin-development`](./skills/dsh-plugin-development/SKILL.md)：
+
+```sh
+npx skills add NanmiCoder/dsh-agent-teams --skill dsh-plugin-development
+```
+
+## 文档
+
+| 指南 | 内容 |
+| --- | --- |
+| [使用指南](./docs/usage.md) | 架构、UI 行为、工具、配置、限制与验证 |
+| [验证指南](./docs/verification-guide.md) | 离线、组合、真实 e2e 与 GUI 验证 |
+| [插件开发](./docs/developing-dsh-plugins.md) | 基于本插件整理的人类可读开发指南 |
+| [README 写作](./docs/readme-writing-guide.md) | 仓库文档约定 |
+
+## 开发
+
+```sh
+pnpm install
+pnpm build
+pnpm verify
+```
+
+## 许可证
+
+[MIT](./LICENSE)

package/assets/readme/hero.svg

@@ -0,0 +1,73 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="360" viewBox="0 0 1200 360" role="img" aria-labelledby="title desc">
+  <title id="title">dsh-agent-teams</title>
+  <desc id="desc">A DeepSeek Harness plugin that turns one captain session into a coordinated team of durable members working through dependent tasks and direct messages.</desc>
+
+  <defs>
+    <marker id="arrow" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto" markerUnits="strokeWidth">
+      <path d="M0 0L8 4L0 8Z" fill="#4F8CFF"/>
+    </marker>
+  </defs>
+
+  <rect width="1200" height="360" rx="28" fill="#07111F"/>
+  <path d="M656 42V318" stroke="#20334C" stroke-width="1.5"/>
+
+  <g font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', sans-serif">
+    <text x="58" y="64" fill="#7F98BB" font-size="17" font-weight="650" letter-spacing="2.2">DEEPSEEK HARNESS · MULTI-AGENT ORCHESTRATION</text>
+    <text x="58" y="142" fill="#F4F8FF" font-size="58" font-weight="760" letter-spacing="-2.1">dsh-agent-teams</text>
+    <text x="58" y="197" fill="#C4D1E3" font-size="27" font-weight="520">One session becomes a coordinated team.</text>
+
+    <g font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="15">
+      <rect x="58" y="247" width="152" height="42" rx="21" fill="#102642" stroke="#315D91"/>
+      <circle cx="81" cy="268" r="6" fill="#4F8CFF"/>
+      <text x="98" y="274" fill="#BBD5FF" font-weight="700">CAPTAIN-LED</text>
+      <text x="232" y="274" fill="#7189AA">MEMBERS · TASKS · MESSAGES · ARCHIVE</text>
+    </g>
+
+    <g font-family="ui-monospace, SFMono-Regular, Menlo, monospace">
+      <text x="704" y="57" fill="#7F98BB" font-size="15" letter-spacing="1.7">LIVE TEAM GRAPH</text>
+
+      <path d="M790 130C844 130 850 86 912 86" fill="none" stroke="#4F8CFF" stroke-width="1.8"/>
+      <path d="M790 130H912" fill="none" stroke="#4F8CFF" stroke-width="1.8"/>
+      <path d="M790 130C844 130 850 174 912 174" fill="none" stroke="#4F8CFF" stroke-width="1.8"/>
+      <path d="M1040 86V174" fill="none" stroke="#35D5A4" stroke-width="1.4" stroke-dasharray="5 6"/>
+
+      <circle cx="755" cy="130" r="38" fill="#102642" stroke="#4F8CFF" stroke-width="2"/>
+      <circle cx="755" cy="130" r="25" fill="#4F8CFF"/>
+      <path d="M745 132L753 140L767 121" fill="none" stroke="#FFFFFF" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+      <text x="712" y="184" fill="#AFC4E0" font-size="14">CAPTAIN</text>
+
+      <g>
+        <rect x="912" y="61" width="222" height="50" rx="12" fill="#101F33" stroke="#2B4567"/>
+        <circle cx="936" cy="86" r="8" fill="#4F8CFF"/>
+        <text x="955" y="82" fill="#F4F8FF" font-size="15" font-weight="700">RESEARCHER</text>
+        <text x="955" y="101" fill="#7F98BB" font-size="12">collect evidence</text>
+      </g>
+      <g>
+        <rect x="912" y="117" width="222" height="50" rx="12" fill="#101F33" stroke="#2B4567"/>
+        <circle cx="936" cy="142" r="8" fill="#35D5A4"/>
+        <text x="955" y="138" fill="#F4F8FF" font-size="15" font-weight="700">ENGINEER</text>
+        <text x="955" y="157" fill="#7F98BB" font-size="12">build and verify</text>
+      </g>
+      <g>
+        <rect x="912" y="173" width="222" height="50" rx="12" fill="#101F33" stroke="#2B4567"/>
+        <circle cx="936" cy="198" r="8" fill="#F2BD62"/>
+        <text x="955" y="194" fill="#F4F8FF" font-size="15" font-weight="700">REVIEWER</text>
+        <text x="955" y="213" fill="#7F98BB" font-size="12">challenge result</text>
+      </g>
+
+      <rect x="700" y="250" width="124" height="54" rx="12" fill="#101F33" stroke="#2B4567"/>
+      <text x="719" y="272" fill="#7F98BB" font-size="12">TASK t1</text>
+      <text x="719" y="292" fill="#F4F8FF" font-size="14" font-weight="700">RESEARCH</text>
+      <path d="M824 277H850" stroke="#4F8CFF" stroke-width="1.8" marker-end="url(#arrow)"/>
+
+      <rect x="858" y="250" width="124" height="54" rx="12" fill="#101F33" stroke="#2B4567"/>
+      <text x="877" y="272" fill="#7F98BB" font-size="12">TASK t2</text>
+      <text x="877" y="292" fill="#F4F8FF" font-size="14" font-weight="700">IMPLEMENT</text>
+      <path d="M982 277H1008" stroke="#4F8CFF" stroke-width="1.8" marker-end="url(#arrow)"/>
+
+      <rect x="1016" y="250" width="118" height="54" rx="12" fill="#102A29" stroke="#2E7368"/>
+      <text x="1035" y="272" fill="#75B8AC" font-size="12">TASK t3</text>
+      <text x="1035" y="292" fill="#9AF0D9" font-size="14" font-weight="700">REVIEW</text>
+    </g>
+  </g>
+</svg>