Skip to content

dongshuyan/compass-skills / skills/task-forest

task-forest

Verified

Maintains a repo-local task forest or task DAG for the current workspace. Use when the user asks to initialize or update a task forest, close a session, summarize evolving project work, align a request with a global goal, track progress/history/deviations/todos, save or apply a task proposal, or export the client-readable task-forest HTML. Do not use for executing the tracked tasks themselves or for generic HTML work.

references/integration-contract.md

View on GitHub
# task-forest 集成契约

## 目录

- 固定导出文件
- gap-router 读取方式
- local-agent-control-room 读取方式
- 写入边界
- 全局 SQLite 边界

## 固定导出文件

每次 `export` 后生成:

```text
.agent-workbench/task-forest/exports/task-forest.graph.json
.agent-workbench/task-forest/exports/task-forest.todos.json
.agent-workbench/task-forest/exports/task-forest.timeline.json
.agent-workbench/task-forest/exports/task-forest.html
```

消费者应读取 `exports/`,不要读取 `graph/nodes.json` 和 `graph/edges.json`,更不要直接写它们。

## gap-router 读取方式

`gap-router` 的任务池来源应优先使用 `task-forest.todos.json`。推荐候选条件:

- `status` 属于 `proposed`、`ready`、`in_progress`、`review_needed`;
- `ready == true`;
- 排除 `done`、`deprecated`、`archived`;
- 排除 `blocked_by` 非空的任务,除非用户明确想处理阻塞。

可用字段:

```text
id
title
purpose
kind
status
progress
priority
difficulty
remaining_minutes_min
remaining_minutes_max
ready
blocked_by
next_action
confidence
context_tags
desired_outcomes
success_metrics
alignment
```

推荐逻辑可以结合 gap-router 自己的等待时间、切入成本、切回成本和精力参数。若需要记录用户执行结果,gap-router 应写入 task-forest proposal,而不是直接改 task-forest 图。

推荐给用户时,优先使用 `purpose` 和 `alignment.why_this_task` 解释“为什么这件事符合当前 global 目的”;如果这些字段为空,应降低推荐置信度或提示需要先做目标对齐。

如果需要更快获得候选队列,也可以读取 `task-forest.graph.json` 中的派生字段:

```text
status_queues.actionable_todos
status_queues.ready
status_queues.review_needed
status_queues.evergreen_open_goals
```

其中 `evergreen_open_goals` 代表长期持续目标,不能简单按剩余分钟推荐给用户;应只作为当前上下文和目的解释来源。真正适合碎片时间推荐的是 `actionable_todos` 和 `ready` 中具备估时、低切换成本、低阻塞风险的节点。

## local-agent-control-room 读取方式

`local-agent-control-room` 应读取 `task-forest.graph.json`,把 agent/session 状态叠加到任务节点上:

```text
session_id -> source_sessions 或 proposal.session_id
waiting_human -> question / review_needed
risk finding -> risk / deviation proposal
completed session -> review_needed 或 done proposal
```

控制室可以展示:

- 哪个 session 正在处理哪个任务节点;
- 哪些节点完成但待 review;
- 哪些节点被风险事件影响;
- 哪些任务等待用户回答;
- 哪些任务长时间无进展。

新版 `task-forest.graph.json` 提供了便于控制室展示的派生字段:

```text
status_queues.blocked
status_queues.review_needed
status_queues.open
edge_index.<node_id>.incoming
edge_index.<node_id>.outgoing
edge_index.<node_id>.blocking_edges
edge_index.<node_id>.cross_edges
edge_type_counts
tree_edges
cross_edges
```

控制室应使用这些字段定位“谁卡住、谁待复核、谁有跨任务依赖”。展示层可以默认使用 `child_of` 作为层级树,把 `depends_on`、`contributes_to`、`clarifies` 等边作为可点击关系边展示,避免把 DAG 误读成纯树。

如果控制室复用 `task-forest.html` 的交互经验,应遵守 `html-visualization-contract.md` 的用户语义:`child_of` 面向用户显示为“子任务”,搜索、筛选、展开和历史播放都只是浏览器视图状态,不能写回 task-forest graph。

控制室不应直接修改 task-forest 的正式状态。它可以生成 proposal:

```text
.agent-workbench/task-forest/proposals/<proposal_id>.json
```

然后由 `$task-forest` 读取、解释、请求用户确认并应用。

## 写入边界

唯一允许正式写入 task-forest 的程序是:

```bash
scripts/task_forest.py
```

其他插件只允许:

- 读取 `exports/`;
- 写入未确认 proposal;
- 写入外部观察日志,再由 task-forest 转成 proposal。

HTML 中的按钮、搜索、筛选、展开、详情和历史播放都属于浏览器本地视图状态。其他插件不应把这些 UI 状态当成任务状态,也不应从 HTML 反向解析任务事实;需要完整任务数据时读取 JSON export。

## 全局 SQLite 边界

全局 SQLite 可以保留轻量 registry:

```text
workspace_path
task_forest_path
exports_dir
graph_export_path
todos_export_path
timeline_export_path
html_export_path
last_seen_at
last_export_at
last_export_hash
node_count
edge_count
ready_count
review_needed_count
blocked_count
evergreen_count
status
last_error
```

推荐表名:

```text
aw_task_forests
aw_task_forest_runs
```

全局 registry 默认关闭。只有用户明确同意跨 workspace 发现,并设置 `TASK_FOREST_ENABLE_GLOBAL_REGISTRY=1` 后,`task_forest.py` 才会在 `init`、`export`、`validate`、`proposal-save`、`proposal-apply` 后尽力更新该 registry。数据库路径由 `AGENT_WORKBENCH_DB` 指定;未指定时使用 `~/.agent-workbench/agent-workbench.sqlite3`。`TASK_FOREST_DISABLE_GLOBAL_REGISTRY=1` 可强制关闭已有的全局启用配置。

`gap-router` 和 `local-agent-control-room` 也只能在用户同意这一集成后刷新 registry,以便下一次发现该 workspace。

不要把节点、边、事件、快照、HTML、proposal 内容或完整对话摘要保存到全局 SQLite。完整数据必须留在 repo-local task-forest 目录。全局 registry 只是发现入口和健康状态摘要,不是任务事实源。
add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks.Stars: 115kUpdated Claude CodeCodexVerifiedInstall