docs: organize product documentation by domain

Replace the flat features directory with document-type and functional-domain navigation, update repository-wide links, and add a top-level documentation index. Define Task, Conversation, Job, Subjob, Run, Scheduled Task, Goal Task, and Task Center in one canonical document set. Keep Smart Heartbeat ownership separate and leave future partitioned memory explicitly undesigned.
2026-08-19 07:52:43 +08:00
parent 3935f50017
commit ccaab25d11
28 changed files with 1980 additions and 590 deletions
@@ -0,0 +1,16 @@
+# Task 与 Job 文档集
+
+本目录定义 GoodBuddy 的工作对象、内部执行单元和调度关系。
+
+## 权威文档
+
+1. [Task 与 Job 统一领域模型](./task-and-job-model.md)：术语、身份和对象关系。
+2. [Task Center PRD](./task-center-prd.md)：Task 的应用级索引。
+3. [Scheduled Task PRD](./scheduled-task-prd.md)：时间或事件触发的 Task。
+4. [Goal Task PRD](./goal-task-prd.md)：围绕可验证结果有界推进的 Task。
+5. [Job 与 Subjob PRD](./job-and-subjob-prd.md)：Task 内部串行、并行和委派执行。
+
+## 阅读顺序
+
+先阅读统一领域模型。其他三份文档不得重新定义 Task、Conversation、Job、Run 或 Subagent。
+若实现与文档出现冲突，应先修正统一模型，再同步功能 PRD。
@@ -0,0 +1,53 @@
+# Goal Task PRD
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中，未来能力 |
+| 版本 | 0.1 |
+| 日期 | 2026-08-19 |
+| 依赖 | [Task 与 Job 统一领域模型](./task-and-job-model.md) |
+
+## 1. 产品定义
+
+Goal Task 是围绕可验证结果持续推进的 Task。它仍然只有一个 Task Conversation；每轮观察、
+计划、行动和评估由 Job/Run 表达，不创建一串顶层 Task。
+
+## 2. 必要配置
+
+- 目标描述。
+- 至少一个成功标准。
+- 约束和停止条件。
+- 最大轮数、截止时间或预算。
+- 每轮评估方式。
+- 无进展处理。
+- Project、Runtime、知识、记忆、目录、工具和审批范围。
+
+## 3. 有界循环
+
+```text
+Observe Job
+  → Planning Job
+  → Permission and budget check
+  → Action Job / parallel Jobs
+  → Evaluation Job
+  → Complete, pause, revise or continue
+```
+
+循环内的所有 Job 共享 Task Conversation。只有协调器把有意义的阶段进展写入消息时间线，
+避免每个内部步骤产生一条顶层任务或杂乱消息。
+
+## 4. 完成和无进展
+
+- 模型声明不能单独证明目标完成。
+- 成功标准必须可计算或可人工审查。
+- 连续两轮没有指标改善、重复下一步、连续失败、权限不可用或预算不足时暂停。
+- 修改范围、预算、Runtime、工作模式或权限必须用户确认。
+
+## 5. 验收原则
+
+- [ ] Goal Task 只有一个 Task Conversation。
+- [ ] 循环步骤以 Job 表达，不创建顶层子 Task。
+- [ ] 没有成功标准和停止条件时不能启用。
+- [ ] 无进展和预算耗尽不会伪装为成功。
@@ -0,0 +1,98 @@
+# Job 与 Subjob PRD
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中，未来能力 |
+| 版本 | 0.1 |
+| 日期 | 2026-08-19 |
+| 依赖 | [Task 与 Job 统一领域模型](./task-and-job-model.md) |
+
+## 1. 目标
+
+在不创建额外顶层 Task 或 Conversation 的前提下，让一个 Task 能够分解、串行、并行和委派
+多个执行单元，并将进展和结果有序汇入 Task 的同一 Conversation。
+
+## 2. Job 类型
+
+首期只使用有限类型：
+
+- `step`：Task 内一个明确步骤。
+- `scheduled_occurrence`：Scheduled Task 的一次到期执行。
+- `delegated`：交给 Subagent 或远程执行器。
+- `parallel_branch`：并行方案或分工。
+- `aggregation`：汇总多个前置 Job。
+
+类型描述执行方式，不创造新的产品对象层级。
+
+## 3. 并行模型
+
+```text
+Task Conversation
+  └─ Coordinating Job
+       ├─ Parallel Job A
+       ├─ Parallel Job B
+       ├─ Parallel Job C
+       └─ Aggregation Job
+```
+
+- 并行 Job 使用同一个 `taskId` 和 `conversationId`。
+- 每个 Job 有独立输入快照、状态、Run、预算和输出缓冲。
+- 并行 Job 不直接同时追加助手消息。
+- Aggregation Job 或 Task 协调器按确定顺序生成一条进展或结果消息。
+- 用户可以查看每个 Job 的详细活动，但主 Conversation 保持可读。
+
+## 4. Subjob
+
+Job 可以创建有界 Subjob：
+
+- 默认最大深度 2。
+- 默认最大并发 3。
+- 默认最大子项数、模型调用、Token、耗时和输出大小由父 Job 预算限制。
+- 子级只能使用父级已授权能力的子集。
+- 父级取消、失败或超时后，活动子级必须取消。
+
+## 5. Subagent
+
+Subagent 是 Job 的执行者：
+
+- 专家选择和路由记录在 Job 上。
+- Subagent 的原始流式输出进入有界 Job 缓冲和活动记录。
+- 完成、失败和部分输出都返回父 Job。
+- Subagent 不获得独立 Task Center 条目或 Conversation。
+
+## 6. 状态与恢复
+
+Job 状态至少包括：
+
+```text
+queued → running → waiting_approval → completed
+                 ↘ failed | cancelled | interrupted | budget_exceeded
+```
+
+- 重试创建新 Run，不覆盖失败 Run。
+- 应用退出将活动 Job 标记为 `interrupted`。
+- 有外部副作用且结果未知的 Job 不自动重试。
+- 聚合 Job 必须明确处理部分成功、全部失败和取消。
+
+## 7. 界面
+
+Task Conversation 显示：
+
+- 当前总体进展。
+- 并行 Job 数量和聚合状态。
+- 需要审批或用户输入的 Job。
+- 完成后的统一结果。
+
+详细活动视图显示 Job 树、执行者、Runtime、耗时、预算、Run、错误和成果。Task Center 只显示
+Task 聚合状态，不展开 Job 树。
+
+## 8. 验收标准
+
+- [ ] 并行 Job 共享所属 Task 的 Conversation。
+- [ ] Job 不创建顶层 Task。
+- [ ] 并行输出不会无序污染消息时间线。
+- [ ] Subjob 深度、并发、预算和输出有界。
+- [ ] Subagent 失败能够返回部分输出和明确状态。
+- [ ] 父级取消传播到所有活动子级。
@@ -0,0 +1,226 @@
+# Scheduled Task PRD
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 当前基础能力已存在，扩展调度设计中 |
+| 版本 | 0.4 |
+| 日期 | 2026-08-19 |
+| 依赖 | [Task 与 Job 统一领域模型](./task-and-job-model.md) |
+| 相关架构 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md) |
+
+## 1. 产品定义
+
+Scheduled Task 是带时间或事件触发器的 Task。它不是 Schedule 定义与临时 Task 的松散组合，
+也不创建第二条 Conversation。
+
+创建 Scheduled Task 时：
+
+1. 创建一个 Task。
+2. 为该 Task 创建唯一 Conversation。
+3. 保存 Schedule/Trigger Binding。
+4. 每次触发在同一 Task 内创建新的 Job 和 Run。
+5. 将面向用户的进展和结果持续写回同一 Task Conversation。
+
+因此，一个每日任务在 Task Center 中始终是一条 Task，而不是每天新增一条 Task。
+
+## 2. 当前能力
+
+GoodBuddy 当前支持单次、每日和每周触发固定 Ask 提示，并持久化计划、Task、运行状态和成果。
+近期改进不得破坏现有数据、错过执行结算、暂停、立即运行和应用退出行为。
+
+## 3. 目标
+
+- 支持单次、每日、每周、每月、工作日和受限 Cron。
+- 支持 Task 完成、失败、Conversation 完成等内部事件触发。
+- 允许自然语言生成结构化草稿，但必须由用户检查后启用。
+- 提供时区、错过执行、幂等、租约、重试、恢复、取消、预算和审计。
+- 让所有重复触发复用同一 Task Conversation。
+- 为一次触发建立清晰 Job/Run，而不是创建新的顶层 Task。
+
+## 4. 非目标
+
+- 不提供任意脚本和循环的通用 DAG 编辑器。
+- 不允许模型生成并直接执行任意 Shell、SQL 或无限频率 Cron。
+- 不承诺应用退出后继续运行。
+- 不允许计划静默扩大权限、目录、知识或记忆范围。
+- 不把 Smart Heartbeat 变成 Scheduled Task。
+- 不把每次触发或重试显示为新的 Task。
+
+## 5. 创建与配置
+
+用户可以输入自然语言意图：
+
+```text
+每周五下午 5 点总结本项目本周完成和失败的工作，
+列出下周三个优先事项，不要修改文件。
+```
+
+模型只生成草稿：
+
+- 名称和说明。
+- 时间或事件触发器。
+- 工作模式和 Runtime 建议。
+- Project、知识、记忆、目录和工具范围。
+- 输入、输出和通知。
+- 预算、并发和错过执行策略。
+
+用户确认后，系统一次性创建 Task、Conversation 和 Schedule Binding。编辑计划只影响后续
+Job；已启动 Run 使用冻结快照。
+
+## 6. 触发器
+
+### 6.1 时间触发
+
+```ts
+type TimeTrigger =
+  | { type: 'once'; at: string; timezone: string }
+  | { type: 'daily'; localTime: string; timezone: string }
+  | {
+      type: 'weekly'
+      weekdays: number[]
+      localTime: string
+      timezone: string
+    }
+  | {
+      type: 'monthly'
+      day: number | 'last'
+      localTime: string
+      timezone: string
+    }
+  | {
+      type: 'cron'
+      expression: string
+      timezone: string
+    }
+```
+
+受限 Cron 使用五字段，不支持秒、年份、宏、`L`、`W`、`#` 或供应商扩展。Main 负责解析，
+默认最小间隔为 15 分钟，并展示未来五次触发时间。
+
+### 6.2 事件触发
+
+后续支持：
+
+- `conversation.completed`
+- `task.completed`
+- `task.failed`
+- `artifact.created`
+- `knowledge.sync.completed`
+- `magic_note.updated`
+
+事件触发配置来源范围、确定性过滤、去重窗口、冷却时间和并发上限。基础匹配不调用模型。
+
+### 6.3 手动触发
+
+“立即运行”在当前 Task 内创建独立 Job 和 Run，不改变下一次计划时间，不创建新 Task。
+重复点击使用调用级幂等键去重。
+
+## 7. 一次触发的对象关系
+
+```text
+Scheduled Task
+  ├─ Conversation（持续复用）
+  ├─ Schedule Binding
+  └─ Job: scheduled_occurrence
+       └─ Run
+```
+
+- `scheduledFor` 和计划版本形成幂等键。
+- 同一 Scheduled Task 默认最多一个活动 occurrence Job。
+- 若允许并行 occurrence，它们仍属于同一 Task Conversation，并由协调器有序汇总。
+- 重试产生新 Run，不产生新 Task 或新 Job。
+
+## 8. 错过执行
+
+| 策略 | 行为 |
+| --- | --- |
+| `skip` | 记录跳过，不补跑 |
+| `run_once` | 无论错过多少次，只在当前 Task 内补一个 Job |
+| `catch_up_bounded` | 在数量和时间窗口上限内创建多个有界 Job |
+
+默认补跑最多 3 次、最多回溯 7 天。补跑同样受 Task 的并发、权限和预算控制。
+
+## 9. 时区和夏令时
+
+- 保存 IANA 时区，不保存固定 UTC 偏移。
+- 春季不存在的本地时间在当日第一个有效分钟触发。
+- 秋季重复时间只触发一次。
+- 系统时区变化不自动修改计划时区。
+- UI 显示计划时区、本机时区差异和未来触发时间。
+
+## 10. Ask、Execute 与审批
+
+第一阶段保持 Ask：
+
+- Runtime 边界只读。
+- 不写文件、不执行命令、不发送消息、不修改远程数据。
+- 输出写回 Task Conversation；独立交付物才进入成果。
+
+Execute 按顺序开放：
+
+1. 有人值守，沿用逐工具审批。
+2. 预批准低风险工具和参数范围。
+3. 经过专项验证的内置无人值守模板。
+
+高风险、越界或未预授权动作进入 `waiting_approval`，不能因定时触发而绕过策略。
+
+## 11. 预算与背压
+
+每个 Scheduled Task 配置：
+
+- 最大 Job 耗时。
+- 最大模型、Token 和工具调用。
+- 最大成果大小。
+- 最大活动 Job 数。
+- 后台优先级。
+
+前台请求优先。后台达到上限时延后并记录 `deferred`，不能挤占用户正在等待的请求，也不能
+在恢复空闲时一次释放全部积压。
+
+## 12. 重试、恢复和取消
+
+- 瞬时、无副作用失败可以有界重试。
+- 配置、权限和范围错误不重试。
+- 外部副作用结果未知时进入 `outcome_unknown`，不自动重试。
+- 应用退出将活动 Job/Run 标记为 `interrupted`。
+- 暂停计划只阻止新 Job，不假装取消已发生的外部操作。
+- 取消 Task 必须传播到活动 Job、Subjob 和 Runtime。
+
+## 13. 界面
+
+Task Center 显示 Scheduled Task 的范围、状态、最近进展、需要关注和下次触发时间。点击条目
+打开同一 Task Conversation。
+
+Task 内可查看：
+
+- 计划和触发器。
+- 下次执行和未来预览。
+- 每次 occurrence Job。
+- Run、审批、活动和成果。
+
+不新增平行 Automation Center。
+
+## 14. 兼容迁移
+
+现有 Schedule、Schedule Run、Task 和 Conversation 数据渐进关联：
+
+- 保留现有计划 ID、启停状态、下次时间和历史。
+- 为每个现有计划建立或绑定一个持续 Task Conversation。
+- 历史每次执行映射为该 Task 下的 occurrence Job/Run。
+- 迁移不得复制消息、成果或顶层 Task。
+
+## 15. 验收标准
+
+- [ ] 创建 Scheduled Task 只创建一个 Task 和一个 Conversation。
+- [ ] 重复触发始终复用该 Task Conversation。
+- [ ] 每次触发创建 Job/Run，不创建新的顶层 Task。
+- [ ] 支持单次、每日、每周、每月、工作日和受限 Cron。
+- [ ] UI 显示计划时区和未来五次触发时间。
+- [ ] 夏令时不会造成漂移或双跑。
+- [ ] 错过执行按配置跳过、补一次或有界补跑。
+- [ ] 手动运行不改变下次计划时间。
+- [ ] Ask 在 Runtime 边界拒绝写操作和外部副作用。
+- [ ] 应用重启不自动重放结果未知的副作用。
+- [ ] Task Center 不因重复触发新增条目。
@@ -0,0 +1,151 @@
+# Task 与 Job 统一领域模型
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 产品边界已确认，部分能力待实施 |
+| 版本 | 0.1 |
+| 日期 | 2026-08-19 |
+| 适用产品 | GoodBuddy 桌面端 |
+| 文档角色 | Task、Conversation、Job、Run 与 Subagent 的权威定义 |
+
+## 1. 核心定义
+
+### 1.1 Task
+
+Task 是用户明确创建或由已启用计划创建的工作单位，也是 Task Center 的顶层对象。
+
+- 创建 Task 就创建一条新的 Conversation。
+- Task 的内容载体是这条 Conversation，不再维护第二份任务正文或消息时间线。
+- 打开 Task 就打开其 Conversation。
+- Task 的目标、状态、范围、计划、Job、审批、活动和成果都围绕同一 Conversation 组织。
+- 一个 Task 在生命周期内保持同一个 `taskId` 和 `conversationId` 绑定。
+
+普通 Conversation 不自动成为 Task。用户只是聊天时，不应因为存在模型调用或工具步骤就
+产生顶层 Task。
+
+### 1.2 Conversation
+
+Conversation 是 Task 的交互和内容载体：
+
+- 保存用户消息、助手消息和面向用户的进展。
+- 承载同一 Task 内多个 Job 的可理解汇总。
+- 不让并行 Job 直接无序写入同一消息流；由 Task 协调器合并进展和结果。
+- 删除、归档和切换范围时遵循 Task 的生命周期规则。
+
+### 1.3 Job
+
+Job 是 Task 内部的执行单位，不是新的顶层 Task：
+
+- 一次计划触发、一个执行步骤、一项专家委派或一组并行工作都可以是 Job。
+- 一个 Task 可以串行或并行运行多个 Job。
+- 所有 Job 仍属于同一个 Task 和同一条 Conversation。
+- Job 可以有自己的状态、预算、Runtime、执行者、输入快照和成果引用。
+- Job 不进入 Task Center；它显示在 Task 的时间线、活动或 Runtime 视图中。
+
+### 1.4 Subjob
+
+Subjob 是 Job 的子执行单元。它用于分解和并发，不创建新的 Task 或 Conversation。
+
+- 父 Job 负责合并 Subjob 结果。
+- 取消父 Job 必须传播到仍活动的 Subjob。
+- Subjob 不能扩大父 Job 的项目、目录、工具、知识、记忆或审批范围。
+- 深度、数量、并发、时间、Token 和输出大小必须有界。
+
+### 1.5 Run
+
+Run 是 Task 或 Job 的一次执行尝试和审计记录，不是用户工作对象：
+
+- 重试、恢复或手动重新运行可以产生新的 Run。
+- Run 冻结当次配置、范围、预算和 Runtime。
+- Run 进入活动记录和审计，不进入 Task Center。
+- `completed` 只表示该次执行按协议结束，不必然表示 Task 目标达成。
+
+### 1.6 Subagent
+
+Subagent 是执行 Job 或 Subjob 的受限执行者，不是对象层级：
+
+- 专家、Agent Runtime 或其他执行器可以承担 Job。
+- Subagent 不自动拥有独立 Task 或 Conversation。
+- Subagent 输出先回到所属 Job，再由 Task 协调器写入同一 Conversation。
+
+## 2. 对象关系
+
+```text
+Task 1 ── 1 Conversation
+  │
+  ├─ Schedule / Trigger Binding（可选）
+  ├─ Job 1
+  │   ├─ Run 1..N
+  │   └─ Subjob 0..N
+  ├─ Job 2（可与 Job 1 并行）
+  └─ Artifact / Approval / Activity / Notification
+```
+
+不允许：
+
+```text
+Task → 第二条 Conversation
+Job → 新建顶层 Task
+Subagent → 自动新建 Conversation
+Run → 出现在 Task Center
+```
+
+## 3. Scheduled Task
+
+Scheduled Task 仍然是 Task，而不是独立的自动化对象：
+
+1. 用户创建 Scheduled Task。
+2. 系统创建一个 Task 和一个 Conversation，并保存 Schedule/Trigger Binding。
+3. 到期时在该 Task 内创建新的 Job 和 Run。
+4. 每次触发的进展和结果汇入同一个 Task Conversation。
+5. 编辑计划影响后续 Job，不修改已经启动的 Run。
+
+同一 Scheduled Task 默认串行触发。需要并行时，应显式允许多个 Job 并发，并继续使用同一
+Conversation，而不是复制 Task。
+
+## 4. 状态分层
+
+| 层级 | 典型状态 | 用户在哪里看到 |
+| --- | --- | --- |
+| Task | queued、running、waiting_approval、paused、completed、failed、cancelled、interrupted | Task Center、Task Conversation |
+| Job | queued、running、waiting、completed、failed、cancelled | Task 时间线、活动、Runtime |
+| Run | claimed、running、completed、failed、cancelled、interrupted、budget_exceeded | 活动与审计 |
+
+Task 状态由当前目标和所属 Job 聚合得出，但不能用“任一 Job 完成”直接推断 Task 完成。
+
+## 5. 兼容映射
+
+当前代码和旧文档中的对象按以下方式收敛：
+
+| 旧概念 | 目标概念 |
+| --- | --- |
+| 自动任务 | Scheduled Task、Event Task 或 Goal Task |
+| 自动会话 | 删除该独立概念，使用 Task Conversation |
+| 子任务、Child Task | Job 或 Subjob |
+| 专家子任务 | 由专家 Subagent 执行的 Job/Subjob |
+| 多任务并行 | 一个 Task 内多个并行 Job；确实独立的用户目标才创建多个 Task |
+| Schedule Run | Scheduled Task 内的 Job Run |
+| Automation Run | Task 或 Job 的 Run |
+
+数据库字段可以在兼容期保留旧名称，但新产品文案、PRD 和新增契约必须使用本模型。
+
+## 6. 安全和数据要求
+
+- Main 验证 Task、Conversation、Job、Run 和 Project 的归属链。
+- Renderer 不能把任意 Job 绑定到其他 Task 或 Conversation。
+- Job/Subjob 继承父级能力上限，只能缩小，不能扩大。
+- 并行输出先有界持久化，再按确定顺序汇总到 Conversation。
+- 取消、超时、审批和应用退出必须沿 Task → Job → Subjob → Runtime 传播。
+- 用户删除 Task 时，先处理活动 Job，再按数据保留规则清理关联对象。
+
+## 7. 验收原则
+
+- [ ] 创建 Task 时只创建一条对应 Conversation。
+- [ ] Scheduled Task 的重复触发复用同一 Task Conversation。
+- [ ] 一个 Task 可以在同一 Conversation 下运行多个并行 Job。
+- [ ] Job、Subjob、Run 和 Subagent 不进入 Task Center。
+- [ ] 并行 Job 不直接无序写入 Conversation。
+- [ ] 取消和权限范围能够沿层级正确传播。
+- [ ] 新文档不再把 Job/Subjob 定义为新的顶层 Task。
@@ -0,0 +1,59 @@
+# Task Center PRD
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-08-19 |
+| 依赖 | [Task 与 Job 统一领域模型](./task-and-job-model.md) |
+| 界面归属 | [通用助手工作栏与执行空间](../assistant-experience/assistant-workbar-and-execution-spaces-prd.md) |
+
+## 1. 产品定义
+
+Task Center 是所有 Task 的应用级单例索引。它不是第二份任务数据，也不是 Automation
+Center。点击条目直接打开 Task 自身的 Conversation。
+
+## 2. 收录边界
+
+收录：
+
+- 用户明确创建的 Task。
+- Scheduled Task、Event Task 和 Goal Task。
+- 未来由用户确认创建的其他顶层 Task。
+
+不收录：
+
+- 普通 Conversation。
+- Job、Subjob、Run、工具步骤或 Subagent。
+- Smart Heartbeat 配置、报告和建议。
+- 仅用于审计的活动记录。
+
+## 3. 列表信息
+
+每条 Task 至少显示：
+
+- 名称和 Global / Project 范围。
+- Task 类型和触发来源。
+- 当前聚合状态。
+- 最近一次面向用户的进展。
+- 最近活动时间。
+- 等待审批、失败或需要关注数量。
+- 下次计划时间（如适用）。
+
+## 4. 交互
+
+- 点击条目打开 Task Conversation。
+- 支持按需要关注、进行中、已暂停、已结束筛选。
+- 支持暂停、恢复、取消和打开详情，但不在窄栏复制完整 Job 时间线。
+- 后台变化更新状态和徽标，不自动抢占当前页面。
+- Task 的计划、Job、Run、审批和成果在 Task 自身或对应活动视图管理。
+
+## 5. 验收标准
+
+- [ ] Task Center 只展示 Task。
+- [ ] 点击 Task 不会跳转到另一条内容相同的附属 Conversation。
+- [ ] Job/Subjob/Run 不会重复成为顶层条目。
+- [ ] Scheduled Task 显示下次时间，但每次触发不新增 Task 条目。
+- [ ] Smart Heartbeat 不进入 Task Center。