dominds 1.16.1 → 1.16.2

package/dist/docs/dominds-agent-collaboration.zh.md

@@ -0,0 +1,401 @@
+# Dominds 智能体协作机制
+
+本文档面向**不运行在 Dominds 内部**、但需要理解 Dominds 协作方式的智能体与人类设计者。
+
+目标不是介绍实现细节，也不是比较优劣，而是回答两个问题：
+
+1. Dominds 团队在运行时是如何协作、挂起、恢复、回贴和升级给人的。
+2. 当用户描述一个业务场景时，外部智能体应如何据此设计一支合适的 Dominds 团队。
+
+相关参考：
+
+- [对话系统实现](./dialog-system.zh.md)
+- [术语表](./dominds-terminology.md)
+- [记忆系统](./memory-system.zh.md)
+- [封装式差遣牒](./encapsulated-taskdoc.zh.md)
+- [Agent Priming（启动脚本）](./agent-priming.zh.md)
+- [团队管理工具集](./team_mgmt-toolset.zh.md)
+
+## 一句话理解
+
+Dominds 不是把“多个智能体”简单并排摆在一起，而是把**对话**作为协作单元，把**差遣牒**作为共享任务真源，把 `team.yaml` 作为组织结构定义，再用 **Tellask / TellaskBack / Q4H** 驱动跨角色协作。
+
+如果你是外部智能体，可以把 Dominds 理解为一种“有组织结构、共享公告板、显式挂起恢复机制”的多智能体工作系统。
+
+## 核心对象
+
+### 1. 团队成员不是“人格”，而是职责包
+
+Dominds 团队成员通常由以下几类信息组成：
+
+- **身份与职责**：这个成员负责什么，不负责什么。
+- **路由卡（`gofor` / `nogo`）**：告诉其他成员“什么时候应该找我”“什么事情不要找我”。
+- **能力边界**：模型、工具集、目录权限、是否能跑 shell、是否能改 `.minds/`、是否能维护团队记忆。
+- **长期心智**：`persona / knowledge / lessons`。
+
+对外部智能体来说，设计团队时不要先想“起几个炫酷角色名”，而要先想：每个成员是否对应了一个稳定职责包。
+
+### 2. 对话才是运行中的协作实体
+
+在 Dominds 里，团队成员是静态定义；真正运行起来的是**对话**：
+
+- **主线对话**：承载当前任务的共享差遣牒，负责整体推进。
+- **支线对话**：围绕某个分项任务临时展开的工作对话。
+- **诉请者对话 / 被诉请者对话**：一次协作调用中的 caller / callee 角色，不等于上下级。
+
+这意味着：同一个成员可以在不同时间参与多条对话；团队结构与运行中的对话流是两层东西。
+
+### 3. 差遣牒是共享任务真源
+
+每个对话树都有一份封装的任务包（`*.tsk/`），其中最核心的是三段：
+
+- `goals`：这次任务完成时必须为真的结果。
+- `constraints`：必须遵守的硬约束。
+- `progress`：当前状态、关键决策、下一步。
+
+对于外部智能体，这一点非常重要：**Dominds 的共享协作不是靠“大家都记住聊天历史”，而是靠差遣牒持续对齐。**
+
+进一步说：
+
+- 长期稳定的团队共识，放进 `team_memory` 或 `.minds/**`
+- 成员个人的长期索引和习惯，放进 `personal_memory`
+- 当前工作集细节，放进 reminder
+- 需要复用的开场历史，做成 priming script
+
+### 4. `gofor` 是路由卡，不是完整岗位说明书
+
+`gofor` 的作用是告诉其他成员或人类：
+
+- 什么时候应该把事情诉请给这个成员
+- 诉请后大概会得到什么帮助或产出
+
+它不应该替代完整的 `persona/knowledge/lessons`，也不应该塞满成员自己的全部操作细则。
+
+如果你是外部智能体，要为用户设计团队，`gofor` 最适合写成“何时找我 + 我返回什么”的路由卡，而不是长篇职责描述。
+
+## Dominds 的协作是怎样发生的
+
+下面用外部智能体容易复用的方式描述一次典型协作。
+
+### 1. 主线接单
+
+通常由 `default_responder` 先接到任务，开启主线对话。
+
+主线对话的第一职责不是立刻到处派工，而是先冻结任务真相：
+
+- 把目标写入差遣牒 `goals`
+- 把硬约束写入 `constraints`
+- 把当前判断与下一步写入 `progress`
+
+如果这一步没有做好，后续再多支线也会失焦。
+
+### 2. 主线决定哪些工作要拆出去
+
+主线对话根据任务类型，决定哪些内容要交给其他成员。
+
+常见拆分维度：
+
+- 业务判断
+- 方案设计
+- 编码实现
+- shell 执行
+- 测试验证
+- 文案 / i18n
+- 团队治理 / 配置变更
+
+这不是“平均分配工作量”，而是把**职责边界不同、上下文不同、工具权限不同**的工作拆开。
+
+### 3. 诉请产生支线协作
+
+Dominds 里主要有三种协作诉请：
+
+- **TellaskBack（回问诉请）**：支线需要澄清时，回问当前诉请者对话。
+- **Tellask Session（长线诉请）**：适合多轮迭代、上下文可续用的协作。
+- **Fresh Tellask（一次性诉请）**：一次性的、无需保留后续续话语义的协作。
+
+外部智能体做团队设计时，可以按下面的经验判断：
+
+- 要持续多轮 debug、持续走查、反复修改同一子问题，用 **长线诉请**
+- 只需要一次性取证、跑一次命令、给一份审阅结果，用 **一次性诉请**
+- 支线发现关键信息缺失，不能猜，就用 **回问诉请**
+
+### 4. 协作不是“发消息就结束”，而是挂起与恢复
+
+Dominds 的关键特征之一，是诉请后的运行态会显式管理：
+
+- 主线可因等待支线结果而挂起
+- 支线可因等待澄清而挂起
+- 对话恢复由后端协程统一驱动
+- 回贴会回到“当前诉请者对话”
+
+因此，从外部智能体的视角，Dominds 协作设计要考虑的不是“谁给谁发消息”，而是：
+
+- 谁拥有当前任务真相
+- 谁在等待谁
+- 谁有权继续推进
+- 谁的回复会被自动路由回哪条工作线
+
+### 5. 向人请示（Q4H）是正式阻塞点
+
+当没有足够依据继续推进，或需要人类决策时，Dominds 用 `askHuman(...)` 形成 **Q4H**。
+
+Q4H 不是“顺手问一句”，而是一个正式的待答问题：
+
+- 对话会因此挂起
+- 问题会被索引与展示
+- 人类回答后，对话再恢复
+
+外部智能体在设计团队时，应主动规划哪些点必须升级给人，而不是把人类只当成最后兜底。
+
+### 6. 支线负责产出结果，不负责偷偷改全局真相
+
+在 Dominds 的用户语境里，只有**主线对话主理人**拥有 `change_mind` 权限。
+
+这意味着：
+
+- 支线可以分析、实现、验证、回贴
+- 支线可以通过回问诉请要澄清
+- 但共享差遣牒的更新权应收敛在主线
+
+这是一条很重要的组织规则：**谁拥有共享任务真源的更新权，谁就承担整体推进责任。**
+
+对外部智能体来说，这意味着团队设计时要分清：
+
+- 谁是“局部执行 owner”
+- 谁是“全局任务 owner”
+
+它们可以是同一个成员，也可以不是。
+
+## 外部智能体应如何设计 Dominds 团队
+
+下面这部分可直接作为 ChatGPT Pro 一类外部智能体的设计方法。
+
+### 第一步：先抽象业务工作流，不要先抽象岗位名
+
+先把用户需求拆成 5 个问题：
+
+1. 这项业务最终要交付什么结果。
+2. 哪些判断需要长期连续的上下文。
+3. 哪些工作需要不同工具、不同权限或不同专业视角。
+4. 哪些节点必须由人确认。
+5. 哪些规则必须长期沉淀为团队共识，而不是只存在于一次对话里。
+
+然后再决定团队成员，而不是反过来。
+
+### 第二步：用“职责边界”来拆成员
+
+一个成员适合独立存在，通常意味着它至少满足以下一条：
+
+- 需要独立工具权限边界
+- 需要长期稳定的专业判断口径
+- 需要承担明确的交付物
+- 需要频繁被其他成员诉请
+- 需要作为治理或审批节点存在
+
+如果一个角色既没有独立权限，也没有稳定职责，也没有清晰产出，通常不值得单独设成成员。
+
+### 第三步：先定主线 owner，再定支线成员
+
+给用户设计团队时，先确定：
+
+- 谁作为 `default_responder`
+- 谁负责维护差遣牒
+- 谁负责汇总支线回贴并继续推进
+
+然后再配置其他成员，例如：
+
+- 实现型成员
+- 证据收集型成员
+- 审阅 / QA 成员
+- 业务 owner
+- 治理 / 团队配置成员
+- shell specialist
+
+如果主线 owner 不清楚，团队很容易退化成“很多专家都在说话，但没人真正推进”。
+
+### 第四步：按协作持续性选择诉请形态
+
+团队设计时，可以把成员之间的连接关系分成三类：
+
+- **长线协作链路**：例如“主线 PM ↔ 全栈开发”“主线 SRE ↔ 变更评审”
+- **一次性能力调用**：例如“主线 → shell 专员跑一次命令”
+- **高风险澄清链路**：例如“支线实现 → 主线 owner 回问约束”
+
+如果用户业务本身需要反复迭代同一问题，优先设计成长线诉请链路，并给出稳定的 `sessionSlug` 命名策略。
+
+### 第五步：把记忆和治理也当成职责设计的一部分
+
+外部智能体在设计团队时，不应只列“谁做开发、谁做测试”，还应明确：
+
+- 谁维护 `team_memory`
+- 谁能改 `.minds/**`
+- 谁维护 priming scripts
+- 谁需要个人记忆作为职责域索引
+- 哪些业务约束必须进入差遣牒而不是停留在聊天里
+
+这决定团队能否在长程协作中持续稳定运转。
+
+## 一套可复用的设计框架
+
+外部智能体可按以下顺序为用户产出 Dominds 团队方案。
+
+### 1. 业务摘要
+
+- 目标结果是什么
+- 当前阶段是什么
+- 主要风险是什么
+- 哪些节点需要人工拍板
+
+### 2. 主线设计
+
+- `default_responder` 选谁
+- 主线对话由谁维护差遣牒
+- 主线默认先做哪三件事
+
+### 3. 成员设计
+
+每个成员至少说明以下几点：
+
+- `memberId`
+- 角色名称
+- `gofor`
+- 主要交付物
+- 非职责范围
+- 需要的 toolsets / 权限边界
+- 是否需要被其他成员长期反复诉请
+
+### 4. 协作链路设计
+
+至少说明：
+
+- 哪些成员和主线是长线协作
+- 哪些成员只接受一次性诉请
+- 哪些成员可以发起回问诉请
+- 哪些节点需要 Q4H
+
+### 5. 共享状态设计
+
+明确以下内容写到哪里：
+
+- 任务目标和约束：差遣牒
+- 关键决策和当前状态：差遣牒 `progress`
+- 长期团队规范：`team_memory` / `.minds/**`
+- 成员个人索引：`personal_memory`
+- 短期工作集：reminder
+- 可复用开场上下文：priming
+
+## 面向外部智能体的产出模板
+
+外部智能体可直接按下面模板向用户提交方案。
+
+```markdown
+# Dominds 团队设计方案
+
+## 业务目标
+
+- ...
+
+## 主线设计
+
+- default_responder: ...
+- 主线 owner: ...
+- 主线职责:
+  - 冻结 goals / constraints / progress
+  - 决定派工
+  - 汇总支线结果
+  - 必要时发起 Q4H
+
+## 成员清单
+
+| memberId | 负责什么 | 何时诉请它（gofor） | 主要交付 | 不负责什么 | 工具/权限 |
+| -------- | -------- | ------------------- | -------- | ---------- | --------- |
+| ...      | ...      | ...                 | ...      | ...        | ...       |
+
+## 协作链路
+
+- 长线诉请:
+  - 主线 -> 成员A：sessionSlug=...
+  - 主线 -> 成员B：sessionSlug=...
+- 一次性诉请:
+  - 主线 -> 成员C：用于...
+- 回问诉请:
+  - 成员A 在以下场景必须回问主线：...
+
+## 人类介入点（Q4H）
+
+- ...
+
+## 共享状态规则
+
+- goals:
+- constraints:
+- progress:
+- team_memory:
+- personal_memory:
+- priming:
+
+## 风险与反模式检查
+
+- 是否存在无人维护差遣牒的情况
+- 是否把 `gofor` 写成了冗长岗位说明书
+- 是否把需要长期迭代的问题误设计成一次性诉请
+- 是否把应由人拍板的事项错误地下放给支线自主决定
+```
+
+## 典型场景下的设计提示
+
+### 1. 端到端产品/研发场景
+
+通常至少要区分：
+
+- 主线 owner
+- 实现 owner
+- UX / 交互评审
+- QA / 浏览器验证
+- shell specialist
+- i18n 或文案
+
+适合用长线诉请的链路通常是“主线 ↔ 实现 owner”“主线 ↔ UX”。
+
+### 2. SRE / 变更治理场景
+
+通常至少要区分：
+
+- 变更 owner
+- 证据采集 / shell 执行
+- 风险评审
+- 发布 / 回滚治理
+
+这类场景尤其要明确 Q4H 节点，因为人类审批、豁免和回滚授权往往不可省略。
+
+### 3. 内容/知识运营场景
+
+通常至少要区分：
+
+- 主线编辑 owner
+- 资料搜集 / 整理
+- 事实校对
+- 风格与术语统一
+
+这类场景更容易受益于 priming 和团队记忆，因为术语、风格和结构常需长期复用。
+
+## 常见误区
+
+- 把团队成员设计成“按职称堆人头”，而不是按职责边界拆分。
+- 没有明确主线 owner，导致谁都能提建议，但没人维护任务真相。
+- 让支线直接承担全局协调，却不给它差遣牒治理权。
+- 把所有协作都设计成长线诉请，导致上下文负担过重。
+- 把所有协作都设计成一次性诉请，导致持续工作线反复丢上下文。
+- 把 `gofor`、`persona`、`knowledge`、`lessons` 混成一坨。
+- 把关键约束留在聊天里，没有写进差遣牒或团队记忆。
+
+## 给更强外部智能体的最后建议
+
+当你根据用户描述去设计 Dominds 团队时，优先产出这四样：
+
+1. **主线 owner 与差遣牒治理规则**
+2. **成员职责边界与路由卡**
+3. **成员之间该用长线诉请还是一次性诉请**
+4. **哪些地方必须升级给人**
+
+如果这四样已经清楚，`team.yaml`、priming、memory 只是落地形式；如果这四样不清楚，堆再多成员和工具也不会形成稳定协作。

package/dist/llm/api-quirks.d.ts

@@ -1,3 +1,4 @@
+import type { DialogLlmRetryRecoveryAction } from '@longrun-ai/kernel/types/display-state';
 import type { LanguageCode } from '@longrun-ai/kernel/types/language';
 import type { ProviderConfig } from './client';
 import type { LlmRetryStrategy } from './gen';
@@ -9,11 +10,14 @@ export type LlmFailureSummary = {
     code?: string;
 };
 export type LlmQuirkFailureHandling = {
+    sourceQuirk?: string;
+} & ({
     kind: 'default';
 } | {
     kind: 'give_up';
     message?: string;
     summaryTextI18n?: Partial<Record<LanguageCode, string>>;
+    recoveryAction?: DialogLlmRetryRecoveryAction;
 } | {
     kind: 'retry_strategy';
     retryStrategy: LlmRetryStrategy;
@@ -22,14 +26,21 @@ export type LlmQuirkFailureHandling = {
     kind: 'single_retry';
     delayMs: number;
     message?: string;
+});
+export type LlmQuirkRecoveryUsage = {
+    action: DialogLlmRetryRecoveryAction;
+    sourceQuirk?: string;
 };
 export type LlmFailureQuirkHandlerSession = {
+    quirkName: string;
     onFailure: (args: {
         provider: string;
         providerConfig: ProviderConfig;
         failure: LlmFailureSummary;
         error: unknown;
     }) => LlmQuirkFailureHandling;
+    onRequestSucceeded?: () => void;
+    onRecoveryActionUsed?: (usage: LlmQuirkRecoveryUsage) => void;
 };
 export declare function normalizeProviderApiQuirks(providerConfig: ProviderConfig): Set<string>;
 export declare function createLlmFailureQuirkHandlerSession(providerConfig: ProviderConfig): LlmFailureQuirkHandlerSession | undefined;