mcpField
T
task-forest

task-forest

github.com/dongshuyanAgent 工作流762203 次安装1 周前更新
代码仓库

关于 task-forest

task-forest 是面向不同 Agent 的技能，用于维护工作区任务结构、提案、进度和历史。它导出独立的只读 HTML 视图，并要求正式修改任务图前先获确认。

主要功能

  1. 01管理任务图与进度
  2. 02通过提案修改任务图
  3. 03HTML 导出含历史回放
  4. 04跨平台 Python 脚本
  5. 05可选工作区发现注册表

适用场景

  1. 01跟踪已完成和进行中的任务及其必要上级
  2. 02审核任务图变更提案后再应用
  3. 03分享独立的任务进度与历史视图

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/dongshuyan/compass-skills --skill task-forest

安装后在 Claude Code 中输入/task-forest确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
assets/
task-forest-overview.html
references/
concurrency.md
goal-alignment.md
html-visualization-contract.md
integration-contract.md
node-types.md
schema.md
session-close-workflow.md
scripts/
task_forest_html.py
task_forest_ordering.py
task_forest.py
validate_task_forest_export.py

详细介绍

Task Forest

用途

维护当前工作区的任务结构、提案、历史记录和进度。生成一份独立的 HTML 交付物，让初次阅读者无需打开其他任务列表或内部文件即可理解内容。

任务内容、提案、报告和 HTML 均使用用户所用的语言；若语言未知，默认使用中文。

可移植性

此技能与 Agent 无关。将整个 task-forest 目录安装到主机支持的任意技能位置，然后从包含此 SKILL.md 的目录解析脚本、引用和资源。不要假设特定的 Agent 名称、技能根目录、主目录布局、Shell、路径分隔符或操作系统。

使用主机上可用的 Python 3 启动器（python3、python 或 py -3）。脚本使用 Python 标准库，并支持 macOS、Linux 和 Windows。若要在任务历史记录中标记调用方 Agent，请设置 COMPASS_AGENT_NAME 或 AGENT_NAME，或者传入 --actor；否则使用中性值 agent。

核心规则

  1. 只能通过 scripts/task_forest.py 读取和写入任务森林数据；绝不要手动编辑 .agent-workbench/task-forest/ 中的规范文件。
  2. 每个节点使用一个主要的 child_of 父节点；使用 contributes_to 表示次要归属，使用 depends_on 表示前置依赖。
  3. 将图结构变更保存为提案，并等待用户确认后再运行 proposal-apply --yes。
  4. 将低置信度推断保留在问题或提案中。将重要的执行偏差记录为偏离。
  5. 使用通俗易懂的语言编写对用户可见的任务标题和用途。读者无需了解 P04 等内部代码或阅读其他文件，就能理解任务交付的内容、任务存在的原因以及已完成的工作。
  6. 仅导出一个 HTML 界面：exports/task-forest.html。它展示 done、in_progress 任务及其必要的 child_of 祖先节点，并支持历史回放。不要在 HTML 中公开内部讨论、证据、队列、文件系统路径、会话或提案内容。
  7. HTML 交互必须为只读。正式变更始终通过提案工作流进行。
  8. 默认将任务数据和发现元数据保存在仓库本地。可选择启用跨工作区发现：只有在用户明确选择启用并设置 TASK_FOREST_ENABLE_GLOBAL_REGISTRY=1 后，才可启用。此操作会将轻量级工作区路径和健康摘要写入 AGENT_WORKBENCH_DB；若未设置该变量，则写入 ~/.agent-workbench/agent-workbench.sqlite3，且绝不会存储任务内容。

主要工作流

初始化、更新或结束会话时：

  1. 运行 init。
  2. 读取 list --json 和 todo --json。
  3. 确定本次会话服务的全局目标，以及必须保持可见的任务结构。
  4. 如果工作区有权威任务列表，则对每个 done 或 in_progress 任务保留其有意义的 目标 -> 阶段 -> 模块 -> 具体任务 层级和同级顺序。包含必要的祖先节点，省略完全未启动的分支，并将额外修复任务归入其所改进的功能下。绝不要将多个阶段合并为一个节点，也不要依赖边的创建顺序。如果某个同级任务需要 display_order，则为整个同级组设置唯一的数值；不完整、重复或无效的值必须导致验证失败。
  5. 让每个可见节点都能独立理解。使用清晰的标题和 summary 或 purpose；在有助于说明交付内容时，补充结果或验收标准。内部代码只能作为次要标签，不能用作任务名称。
  6. 展示并保存提案。未经确认不得应用。
  7. 获得确认后，运行 proposal-apply --yes、validate 和 export。
  8. 返回提案路径和唯一的 HTML 路径。

当用户意图或目标全局目标确实不明确时，使用 $task-clarifier。

命令

从此文件解析 <skill-dir>，并使用可用的 Python 3 可执行文件。示例使用 python3；必要时替换为宿主机上可用的启动器。

python3 <skill-dir>/scripts/task_forest.py init
python3 <skill-dir>/scripts/task_forest.py list --json
python3 <skill-dir>/scripts/task_forest.py todo --json
python3 <skill-dir>/scripts/task_forest.py proposal-save --proposal-file /path/to/proposal.json
python3 <skill-dir>/scripts/task_forest.py proposal-apply <proposal-id> --yes
python3 <skill-dir>/scripts/task_forest.py validate
python3 <skill-dir>/scripts/task_forest.py export

默认工作区为当前目录。仅在明确指定其他工作区时使用 --workspace。仅在调用方明确选择了非默认任务森林根目录时使用 --root。

全局注册表集成默认关闭。若宿主机全局设置了启用标志，TASK_FOREST_DISABLE_GLOBAL_REGISTRY=1 仍可作为显式覆盖项。

输出

面向用户的交付物如下：

proposals/<proposal_id>.json
exports/task-forest.html

导出器还会为 gap-router 和 local-agent-control-room 维护三个内部兼容性文件：

exports/task-forest.graph.json
exports/task-forest.todos.json
exports/task-forest.timeline.json

除非用户明确要求机器可读数据，否则不要将这些 JSON 文件作为交付物呈现。

参考资料与验证

  • 阅读 references/schema.md，了解节点字段、提案操作和规范不变量。
  • 仅在判断是否符合全局目标或比较候选计划时，阅读 references/goal-alignment.md。
  • 仅在节点分类不明确时，阅读 references/node-types.md。
  • 在解决过时提案或并发写入问题前，阅读 references/concurrency.md。
  • 在修改或验证 HTML 时，阅读 references/html-visualization-contract.md。
  • 仅在修改 JSON 或注册表兼容性时，阅读 references/integration-contract.md。

对于 HTML 或导出器的更改，请运行：

python3 <skill-dir>/scripts/validate_task_forest_export.py --skill-dir <skill-dir>

HTML 仍是派生的只读视图。规范任务数据和提案历史保留在仓库本地。

评论

支持 Markdown