hermes-task-framework 1.0.0__py3-none-any.whl

task-framework/skills/task-framework/docs/TASKS.md

@@ -0,0 +1,3 @@
+| # | Task | Description | Created | Status | Pending | Done |
+|---|------|-------------|---------|--------|:-------:|:----:|
+| 1 | task-framework-skill | 创建 task-framework skill（方法+容器+工具三层） | 2026-06-03 | active | 0 | 3 |

task-framework/skills/task-framework/docs/architecture.dot

@@ -0,0 +1,65 @@
+digraph task_framework {
+  rankdir=TB;
+  bgcolor="#1a1a2e";
+  fontcolor="#e0e0e0";
+  fontname="Consolas";
+  nodesep=0.5;
+  ranksep=0.8;
+
+  node [shape=box style="filled,rounded" fontname="Consolas" fontsize=11];
+
+  subgraph cluster_0 {
+    label="方法论 (Methodology)";
+    style=filled;
+    fillcolor="#16213e";
+    fontcolor="#e0e0e0";
+    color="#0f3460";
+
+    decompose [label="任务分解\ndecompose()" fillcolor="#0f3460" fontcolor="#e0e0e0"];
+    catalog [label="操作目录\noperations/" fillcolor="#0f3460" fontcolor="#e0e0e0"];
+    composites [label="组合模式\ncomposites/" fillcolor="#0f3460" fontcolor="#e0e0e0"];
+    strategies [label="执行策略\nA/B/C/D" fillcolor="#0f3460" fontcolor="#e0e0e0"];
+
+    decompose -> catalog [color="#00a8ff" style=dashed];
+    decompose -> composites [color="#00a8ff" style=dashed];
+    decompose -> strategies [color="#00a8ff" style=dashed];
+  }
+
+  subgraph cluster_1 {
+    label="容器 (Container)";
+    style=filled;
+    fillcolor="#1b2a3a";
+    fontcolor="#e0e0e0";
+    color="#0f3460";
+
+    taskdir [label="tasks/<ts>.<name>/" fillcolor="#1a3a5c" fontcolor="#e0e0e0"];
+    taskmd [label="TASK.md\n(checklist + BREAK)" fillcolor="#1a3a5c" fontcolor="#e0e0e0"];
+    readme [label="README.md\n(goal + summary)" fillcolor="#1a3a5c" fontcolor="#e0e0e0"];
+    logs [label="logs/\n(output + error)" fillcolor="#1a3a5c" fontcolor="#e0e0e0"];
+    docs [label="docs/\n(research findings)" fillcolor="#1a3a5c" fontcolor="#e0e0e0"];
+    inbox [label="inbox/ + declined/\n(proposal lifecycle)" fillcolor="#1a3a5c" fontcolor="#e0e0e0"];
+
+    taskdir -> taskmd [color="#00a8ff"];
+    taskdir -> readme [color="#00a8ff"];
+    taskdir -> logs [color="#00a8ff"];
+    taskdir -> docs [color="#00a8ff"];
+  }
+
+  subgraph cluster_2 {
+    label="工具 (Tooling)";
+    style=filled;
+    fillcolor="#1e2a3a";
+    fontcolor="#e0e0e0";
+    color="#0f3460";
+
+    runner [label="task-runner.sh\n(日志封装)" fillcolor="#2a4a7c" fontcolor="#e0e0e0"];
+    pdfconv [label="convert_md_to_pdf.py\n(文档生成)" fillcolor="#2a4a7c" fontcolor="#e0e0e0"];
+    taskmd_tpl [label="templates/TASK.md\n(模板)" fillcolor="#2a4a7c" fontcolor="#e0e0e0"];
+  }
+
+  # Cross-layer connections
+  strategies -> taskdir [label="创建" color="#e0a800" style=dashed];
+  catalog -> taskmd [label="填入 checklist" color="#e0a800" style=dashed];
+  taskmd -> runner [label="执行" color="#e0a800" style=dashed];
+  docs -> pdfconv [label="导出 PDF" color="#e0a800" style=dashed];
+}

task-framework/skills/task-framework/docs/architecture.svg

@@ -0,0 +1,188 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.43.0 (0)
+ -->
+<!-- Title: task_framework Pages: 1 -->
+<svg width="700pt" height="527pt"
+ viewBox="0.00 0.00 700.00 527.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 523)">
+<title>task_framework</title>
+<polygon fill="#1a1a2e" stroke="transparent" points="-4,4 -4,-523 696,-523 696,4 -4,4"/>
+<g id="clust1" class="cluster">
+<title>cluster_0</title>
+<polygon fill="#16213e" stroke="#0f3460" points="314,-341 314,-511 649,-511 649,-341 314,-341"/>
+<text text-anchor="middle" x="481.5" y="-495.8" font-family="Consolas" font-size="14.00" fill="#e0e0e0">方法论 (Methodology)</text>
+</g>
+<g id="clust2" class="cluster">
+<title>cluster_1</title>
+<polygon fill="#1b2a3a" stroke="#0f3460" points="11,-127 11,-297 676,-297 676,-127 11,-127"/>
+<text text-anchor="middle" x="343.5" y="-281.8" font-family="Consolas" font-size="14.00" fill="#e0e0e0">容器 (Container)</text>
+</g>
+<g id="clust3" class="cluster">
+<title>cluster_2</title>
+<polygon fill="#1e2a3a" stroke="#0f3460" points="8,-8 8,-83 491,-83 491,-8 8,-8"/>
+<text text-anchor="middle" x="249.5" y="-67.8" font-family="Consolas" font-size="14.00" fill="#e0e0e0">工具 (Tooling)</text>
+</g>
+<!-- decompose -->
+<g id="node1" class="node">
+<title>decompose</title>
+<path fill="#0f3460" stroke="black" d="M501.5,-480C501.5,-480 434.5,-480 434.5,-480 428.5,-480 422.5,-474 422.5,-468 422.5,-468 422.5,-456 422.5,-456 422.5,-450 428.5,-444 434.5,-444 434.5,-444 501.5,-444 501.5,-444 507.5,-444 513.5,-450 513.5,-456 513.5,-456 513.5,-468 513.5,-468 513.5,-474 507.5,-480 501.5,-480"/>
+<text text-anchor="middle" x="468" y="-465.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">任务分解</text>
+<text text-anchor="middle" x="468" y="-453.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">decompose()</text>
+</g>
+<!-- catalog -->
+<g id="node2" class="node">
+<title>catalog</title>
+<path fill="#0f3460" stroke="black" d="M628.5,-385C628.5,-385 561.5,-385 561.5,-385 555.5,-385 549.5,-379 549.5,-373 549.5,-373 549.5,-361 549.5,-361 549.5,-355 555.5,-349 561.5,-349 561.5,-349 628.5,-349 628.5,-349 634.5,-349 640.5,-355 640.5,-361 640.5,-361 640.5,-373 640.5,-373 640.5,-379 634.5,-385 628.5,-385"/>
+<text text-anchor="middle" x="595" y="-370.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">操作目录</text>
+<text text-anchor="middle" x="595" y="-358.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">operations/</text>
+</g>
+<!-- decompose&#45;&gt;catalog -->
+<g id="edge1" class="edge">
+<title>decompose&#45;&gt;catalog</title>
+<path fill="none" stroke="#00a8ff" stroke-dasharray="5,2" d="M491.29,-443.94C511.49,-429.16 540.89,-407.62 563.24,-391.26"/>
+<polygon fill="#00a8ff" stroke="#00a8ff" points="565.42,-394 571.42,-385.26 561.29,-388.35 565.42,-394"/>
+</g>
+<!-- composites -->
+<g id="node3" class="node">
+<title>composites</title>
+<path fill="#0f3460" stroke="black" d="M501.5,-385C501.5,-385 434.5,-385 434.5,-385 428.5,-385 422.5,-379 422.5,-373 422.5,-373 422.5,-361 422.5,-361 422.5,-355 428.5,-349 434.5,-349 434.5,-349 501.5,-349 501.5,-349 507.5,-349 513.5,-355 513.5,-361 513.5,-361 513.5,-373 513.5,-373 513.5,-379 507.5,-385 501.5,-385"/>
+<text text-anchor="middle" x="468" y="-370.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">组合模式</text>
+<text text-anchor="middle" x="468" y="-358.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">composites/</text>
+</g>
+<!-- decompose&#45;&gt;composites -->
+<g id="edge2" class="edge">
+<title>decompose&#45;&gt;composites</title>
+<path fill="none" stroke="#00a8ff" stroke-dasharray="5,2" d="M468,-443.94C468,-430.39 468,-411.18 468,-395.47"/>
+<polygon fill="#00a8ff" stroke="#00a8ff" points="471.5,-395.26 468,-385.26 464.5,-395.26 471.5,-395.26"/>
+</g>
+<!-- strategies -->
+<g id="node4" class="node">
+<title>strategies</title>
+<path fill="#0f3460" stroke="black" d="M374,-385C374,-385 334,-385 334,-385 328,-385 322,-379 322,-373 322,-373 322,-361 322,-361 322,-355 328,-349 334,-349 334,-349 374,-349 374,-349 380,-349 386,-355 386,-361 386,-361 386,-373 386,-373 386,-379 380,-385 374,-385"/>
+<text text-anchor="middle" x="354" y="-370.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">执行策略</text>
+<text text-anchor="middle" x="354" y="-358.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">A/B/C/D</text>
+</g>
+<!-- decompose&#45;&gt;strategies -->
+<g id="edge3" class="edge">
+<title>decompose&#45;&gt;strategies</title>
+<path fill="none" stroke="#00a8ff" stroke-dasharray="5,2" d="M447.09,-443.94C429.13,-429.29 403.03,-408 383.04,-391.69"/>
+<polygon fill="#00a8ff" stroke="#00a8ff" points="385.12,-388.87 375.16,-385.26 380.7,-394.3 385.12,-388.87"/>
+</g>
+<!-- taskmd -->
+<g id="node6" class="node">
+<title>taskmd</title>
+<path fill="#1a3a5c" stroke="black" d="M655.5,-171C655.5,-171 534.5,-171 534.5,-171 528.5,-171 522.5,-165 522.5,-159 522.5,-159 522.5,-147 522.5,-147 522.5,-141 528.5,-135 534.5,-135 534.5,-135 655.5,-135 655.5,-135 661.5,-135 667.5,-141 667.5,-147 667.5,-147 667.5,-159 667.5,-159 667.5,-165 661.5,-171 655.5,-171"/>
+<text text-anchor="middle" x="595" y="-156.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">TASK.md</text>
+<text text-anchor="middle" x="595" y="-144.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">(checklist + BREAK)</text>
+</g>
+<!-- catalog&#45;&gt;taskmd -->
+<g id="edge9" class="edge">
+<title>catalog&#45;&gt;taskmd</title>
+<path fill="none" stroke="#e0a800" stroke-dasharray="5,2" d="M595,-348.65C595,-311.83 595,-225.64 595,-181.34"/>
+<polygon fill="#e0a800" stroke="#e0a800" points="598.5,-181.29 595,-171.29 591.5,-181.29 598.5,-181.29"/>
+<text text-anchor="middle" x="643.5" y="-244.3" font-family="Times,serif" font-size="14.00">填入 checklist</text>
+</g>
+<!-- taskdir -->
+<g id="node5" class="node">
+<title>taskdir</title>
+<path fill="#1a3a5c" stroke="black" d="M411,-266C411,-266 297,-266 297,-266 291,-266 285,-260 285,-254 285,-254 285,-242 285,-242 285,-236 291,-230 297,-230 297,-230 411,-230 411,-230 417,-230 423,-236 423,-242 423,-242 423,-254 423,-254 423,-260 417,-266 411,-266"/>
+<text text-anchor="middle" x="354" y="-245.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">tasks/&lt;ts&gt;.&lt;name&gt;/</text>
+</g>
+<!-- strategies&#45;&gt;taskdir -->
+<g id="edge8" class="edge">
+<title>strategies&#45;&gt;taskdir</title>
+<path fill="none" stroke="#e0a800" stroke-dasharray="5,2" d="M354,-348.99C354,-329.92 354,-298.75 354,-276.28"/>
+<polygon fill="#e0a800" stroke="#e0a800" points="357.5,-276.03 354,-266.03 350.5,-276.03 357.5,-276.03"/>
+<text text-anchor="middle" x="368.5" y="-308.8" font-family="Times,serif" font-size="14.00">创建</text>
+</g>
+<!-- taskdir&#45;&gt;taskmd -->
+<g id="edge4" class="edge">
+<title>taskdir&#45;&gt;taskmd</title>
+<path fill="none" stroke="#00a8ff" d="M398.2,-229.94C438.5,-214.39 498.15,-191.38 541.2,-174.76"/>
+<polygon fill="#00a8ff" stroke="#00a8ff" points="542.6,-177.97 550.67,-171.11 540.08,-171.44 542.6,-177.97"/>
+</g>
+<!-- readme -->
+<g id="node7" class="node">
+<title>readme</title>
+<path fill="#1a3a5c" stroke="black" d="M474.5,-171C474.5,-171 373.5,-171 373.5,-171 367.5,-171 361.5,-165 361.5,-159 361.5,-159 361.5,-147 361.5,-147 361.5,-141 367.5,-135 373.5,-135 373.5,-135 474.5,-135 474.5,-135 480.5,-135 486.5,-141 486.5,-147 486.5,-147 486.5,-159 486.5,-159 486.5,-165 480.5,-171 474.5,-171"/>
+<text text-anchor="middle" x="424" y="-156.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">README.md</text>
+<text text-anchor="middle" x="424" y="-144.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">(goal + summary)</text>
+</g>
+<!-- taskdir&#45;&gt;readme -->
+<g id="edge5" class="edge">
+<title>taskdir&#45;&gt;readme</title>
+<path fill="none" stroke="#00a8ff" d="M366.84,-229.94C377.43,-215.87 392.62,-195.69 404.68,-179.67"/>
+<polygon fill="#00a8ff" stroke="#00a8ff" points="407.79,-181.36 411.01,-171.26 402.2,-177.15 407.79,-181.36"/>
+</g>
+<!-- logs -->
+<g id="node8" class="node">
+<title>logs</title>
+<path fill="#1a3a5c" stroke="black" d="M132.5,-171C132.5,-171 31.5,-171 31.5,-171 25.5,-171 19.5,-165 19.5,-159 19.5,-159 19.5,-147 19.5,-147 19.5,-141 25.5,-135 31.5,-135 31.5,-135 132.5,-135 132.5,-135 138.5,-135 144.5,-141 144.5,-147 144.5,-147 144.5,-159 144.5,-159 144.5,-165 138.5,-171 132.5,-171"/>
+<text text-anchor="middle" x="82" y="-156.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">logs/</text>
+<text text-anchor="middle" x="82" y="-144.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">(output + error)</text>
+</g>
+<!-- taskdir&#45;&gt;logs -->
+<g id="edge6" class="edge">
+<title>taskdir&#45;&gt;logs</title>
+<path fill="none" stroke="#00a8ff" d="M304.11,-229.94C258.24,-214.26 190.18,-190.99 141.5,-174.34"/>
+<polygon fill="#00a8ff" stroke="#00a8ff" points="142.63,-171.03 132.03,-171.11 140.36,-177.65 142.63,-171.03"/>
+</g>
+<!-- docs -->
+<g id="node9" class="node">
+<title>docs</title>
+<path fill="#1a3a5c" stroke="black" d="M313.5,-171C313.5,-171 192.5,-171 192.5,-171 186.5,-171 180.5,-165 180.5,-159 180.5,-159 180.5,-147 180.5,-147 180.5,-141 186.5,-135 192.5,-135 192.5,-135 313.5,-135 313.5,-135 319.5,-135 325.5,-141 325.5,-147 325.5,-147 325.5,-159 325.5,-159 325.5,-165 319.5,-171 313.5,-171"/>
+<text text-anchor="middle" x="253" y="-156.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">docs/</text>
+<text text-anchor="middle" x="253" y="-144.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">(research findings)</text>
+</g>
+<!-- taskdir&#45;&gt;docs -->
+<g id="edge7" class="edge">
+<title>taskdir&#45;&gt;docs</title>
+<path fill="none" stroke="#00a8ff" d="M335.48,-229.94C319.77,-215.48 297.06,-194.57 279.44,-178.35"/>
+<polygon fill="#00a8ff" stroke="#00a8ff" points="281.48,-175.46 271.75,-171.26 276.74,-180.61 281.48,-175.46"/>
+</g>
+<!-- runner -->
+<g id="node11" class="node">
+<title>runner</title>
+<path fill="#2a4a7c" stroke="black" d="M471.5,-52C471.5,-52 384.5,-52 384.5,-52 378.5,-52 372.5,-46 372.5,-40 372.5,-40 372.5,-28 372.5,-28 372.5,-22 378.5,-16 384.5,-16 384.5,-16 471.5,-16 471.5,-16 477.5,-16 483.5,-22 483.5,-28 483.5,-28 483.5,-40 483.5,-40 483.5,-46 477.5,-52 471.5,-52"/>
+<text text-anchor="middle" x="428" y="-37.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">task&#45;runner.sh</text>
+<text text-anchor="middle" x="428" y="-25.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">(日志封装)</text>
+</g>
+<!-- taskmd&#45;&gt;runner -->
+<g id="edge10" class="edge">
+<title>taskmd&#45;&gt;runner</title>
+<path fill="none" stroke="#e0a800" stroke-dasharray="5,2" d="M570.72,-134.99C541.65,-114.62 492.87,-80.44 460.55,-57.81"/>
+<polygon fill="#e0a800" stroke="#e0a800" points="462.51,-54.9 452.31,-52.03 458.49,-60.64 462.51,-54.9"/>
+<text text-anchor="middle" x="540.5" y="-94.8" font-family="Times,serif" font-size="14.00">执行</text>
+</g>
+<!-- pdfconv -->
+<g id="node12" class="node">
+<title>pdfconv</title>
+<path fill="#2a4a7c" stroke="black" d="M324,-52C324,-52 196,-52 196,-52 190,-52 184,-46 184,-40 184,-40 184,-28 184,-28 184,-22 190,-16 196,-16 196,-16 324,-16 324,-16 330,-16 336,-22 336,-28 336,-28 336,-40 336,-40 336,-46 330,-52 324,-52"/>
+<text text-anchor="middle" x="260" y="-37.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">convert_md_to_pdf.py</text>
+<text text-anchor="middle" x="260" y="-25.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">(文档生成)</text>
+</g>
+<!-- docs&#45;&gt;pdfconv -->
+<g id="edge11" class="edge">
+<title>docs&#45;&gt;pdfconv</title>
+<path fill="none" stroke="#e0a800" stroke-dasharray="5,2" d="M254.02,-134.99C255.16,-115.92 257.02,-84.75 258.37,-62.28"/>
+<polygon fill="#e0a800" stroke="#e0a800" points="261.88,-62.22 258.98,-52.03 254.89,-61.81 261.88,-62.22"/>
+<text text-anchor="middle" x="288" y="-94.8" font-family="Times,serif" font-size="14.00">导出 PDF</text>
+</g>
+<!-- inbox -->
+<g id="node10" class="node">
+<title>inbox</title>
+<path fill="#1a3a5c" stroke="black" d="M198,-266C198,-266 70,-266 70,-266 64,-266 58,-260 58,-254 58,-254 58,-242 58,-242 58,-236 64,-230 70,-230 70,-230 198,-230 198,-230 204,-230 210,-236 210,-242 210,-242 210,-254 210,-254 210,-260 204,-266 198,-266"/>
+<text text-anchor="middle" x="134" y="-251.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">inbox/ + declined/</text>
+<text text-anchor="middle" x="134" y="-239.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">(proposal lifecycle)</text>
+</g>
+<!-- taskmd_tpl -->
+<g id="node13" class="node">
+<title>taskmd_tpl</title>
+<path fill="#2a4a7c" stroke="black" d="M135.5,-52C135.5,-52 28.5,-52 28.5,-52 22.5,-52 16.5,-46 16.5,-40 16.5,-40 16.5,-28 16.5,-28 16.5,-22 22.5,-16 28.5,-16 28.5,-16 135.5,-16 135.5,-16 141.5,-16 147.5,-22 147.5,-28 147.5,-28 147.5,-40 147.5,-40 147.5,-46 141.5,-52 135.5,-52"/>
+<text text-anchor="middle" x="82" y="-37.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">templates/TASK.md</text>
+<text text-anchor="middle" x="82" y="-25.2" font-family="Consolas" font-size="11.00" fill="#e0e0e0">(模板)</text>
+</g>
+</g>
+</svg>

task-framework/skills/task-framework/docs/product-requirements.md

@@ -0,0 +1,65 @@
+# Task Framework — 产品需求文档
+
+> **版本:** v1.0
+> **状态:** 已投入使用
+> **最后修改:** 2026-06-03 21:50
+
+## 一、概述
+
+Task Framework 是 Hermes Personal Suite 的核心技能之一，提供从任务创建、执行到归档的完整工作流。它覆盖三层能力：
+
+- **方法论** — 如何把一句话需求拆成可执行的操作
+- **容器** — 如何在文件系统中有序组织任务产物
+- **工具** — 如何复用执行脚本和模板
+
+## 二、能力范围
+
+### 2.1 任务生命周期管理
+
+| 阶段 | 能力 | 入口 |
+|------|------|------|
+| 提议 | 收件箱接收任务 idea | `tasks/inbox/` |
+| 创建 | 自动生成时间戳目录、README、TASK.md | `task_create` |
+| 执行 | 支持 4 种执行策略 | Inline / Script / Subagent / Cron |
+| 跟踪 | CHECKLIST 逐项推进，BREAK 暂停点 | TASK.md |
+| 暂停/恢复 | 跨会话持续跟踪 | Status 标记 |
+| 完成/取消 | 归档或删除 | `task_setstatus` |
+
+### 2.2 操作分解
+
+将复杂任务拆解为标准操作：
+
+- `info-search` — 多源信息搜索
+- `code-write` — 代码实现
+- `paper-reproduce` — 论文复现
+- `file-concat` / `file-convert` — 文件加工
+- `document-write` — 文档编写
+- `code-review` — 代码审查
+- `data-analysis` — 数据分析
+- `infra-setup` — 基础设施
+
+### 2.3 组合模式
+
+预定义的常见工作流序列：
+
+- `software-dev` — 调研→设计→编码→审查
+- `research` — 搜索→分析→报告
+- `code-review-session` — 审查→记录→更新
+
+## 三、用户故事
+
+| ID | 用户故事 |
+|----|----------|
+| US-01 | 作为用户，我希望一句话告诉助手我要做什么，助手自动拆成可执行的 checklist |
+| US-02 | 作为用户，我希望任务在执行中途可以暂停，我确认后再继续 |
+| US-03 | 作为用户，我希望每次执行的输出自动保存，方便追溯 |
+| US-04 | 作为用户，我希望临时想到的任务可以先放到收件箱，稍后再决定是否做 |
+| US-05 | 作为用户，我希望不同类型的任务（调研、编码、文档）有不同的 checklist 模板 |
+
+## 四、与 Hermes 生态的关系
+
+| 组件 | 关系 |
+|------|------|
+| `quality-gate` skill | 任务修改后自动触发质量门禁 |
+| `GIT.md` rule | git 操作前置同步（Pre-Change Sync）和后置清理（Post-Change Workflow） |
+| `dump-to-stage` skill | 任务的记忆备份不冲突 — task-framework 管任务内容，dump-to-stage 管系统状态 |

task-framework/skills/task-framework/references/auto-runner.md

@@ -0,0 +1,32 @@
+# Auto-Runner (run.py) Pattern
+
+## When to Use
+
+Multi-phase tasks with a checklist in TASK.md. Create a single `run.py` at the task root that dispatches to individual phase scripts.
+
+## Structure
+
+```python
+./run.py                    — auto: find first unchecked item & execute
+./run.py phase<N>           — run specific phase
+./run.py list               — show checklist status
+```
+
+## Auto Mode Logic
+
+1. Read TASK.md checklist, find first `[ ]` item
+2. If it's a **BREAK**, mark it `[x]` and continue to next item
+3. Execute phases until next `[ ] BREAK` or end of list
+4. Mark each completed phase as `[x]`
+
+## Phase Runners
+
+Each phase runner calls an individual script (e.g. `scripts/gen_tts.py`, `scripts/record_timeline.py`, `scripts/composite.py`).
+
+## Unimplemented Phases
+
+Phases without an implementation should return `True` (skip, don't fail) so the auto-runner can progress past them to the next BREAK.
+
+## Venv
+
+Use `~/.venvs/playwright/bin/python` if available (has playwright, edge-tts, matplotlib, Pillow).

task-framework/skills/task-framework/references/composites/code-review-session.md

@@ -0,0 +1,30 @@
+# Composite: Code Review Session
+
+For a batch review of changes — diff analysis, quality gate, security scan, and report generation.
+
+## Sequence
+
+```
+1. 加载 TASK.md / 确认审查范围
+2. code-review      → 逐个文件审阅（diff, security, quality gate）
+3. document-write   → 写 review/SUMMARY.md（S-XXX 建议表）
+4. 更新 TASK.md 状态
+5. (optional) quality-gate → 跑完整质量门禁
+```
+
+## Checklist Template
+
+```
+- [ ] Phase 1 — Understand what changed (git diff, scope)
+- [ ] Phase 2 — Review each file (logic, security, style)
+- [ ] Phase 3 — Run quality gate
+- [ ] Phase 4 — Write review/SUMMARY.md with S-XXX items
+- [ ] BREAK: 审查结果是否接受？
+- [ ] Phase 5 — Fix critical issues / mark non-blockers
+```
+
+## Pitfalls
+
+- **Scope confusion** — confirm which changes are being reviewed before starting. A session with mixed concerns produces unusable review output
+- **S-XXX numbering** — each issue gets a unique S-XXX ID. New session → continue from last S-XXX, don't restart at S-001
+- **Don't skip quality gate** — review without quality gate misses automated issues (lint, type errors, test failures)

task-framework/skills/task-framework/references/composites/research.md

@@ -0,0 +1,45 @@
+# Composite: Research Task
+
+For open-ended investigation — competitor analysis, policy study, tech feasibility exploration.
+
+## Sequence
+
+```
+1. info-search    → 多源搜索（竞品、论文、政策、产品）
+2. data-analysis  → 整理发现、归类、对比
+3. document-write → 写出调研报告
+4. (optional) paper-reproduce → 如有论文需要复现
+```
+
+## Directory Structure
+
+```
+tasks/<ts>.<name>/
+├── README.md                      ← 调研总结（最初空，随进度更新）
+├── TASK.md                        ← 分解后的操作 checklist
+├── docs/
+│   ├── competitor-<company>.md    ← 每家公司一份
+│   ├── paper-<short-title>.md     ← 每篇论文一份
+│   ├── policy-<region>.md         ← 每个政策/报告一份
+│   └── architecture-proposal.md   ← 方案建议
+└── logs/
+    └── ...
+```
+
+## Checklist Template
+
+```
+- [ ] Phase 1 — Define scope & targets
+- [ ] Phase 2 — Collect sources (info-search)
+- [ ] Phase 3 — Organize & analyze findings
+- [ ] Phase 4 — Write summary report
+- [ ] BREAK: 调研结果是否足够？
+- [ ] Phase 5 — (optional) Architecture proposal / recommendation
+```
+
+## Pitfalls
+
+- **Scope creep** — agree on search scope before starting, or research goes infinite
+- **Source freshness** — note retrieval date on each doc; stale info = worse than no info
+- **Organize as you go** — don't wait until the end to write docs/ files. Write one file per source immediately after collecting it
+- **Summary table in README** — after collecting all docs, update README.md with a table linking each doc

task-framework/skills/task-framework/references/composites/software-dev.md

@@ -0,0 +1,41 @@
+# Composite: Software Development
+
+Standard round-trip for implementing a feature from scratch.
+
+## Sequence
+
+```
+1. info-search     → 调研现有方案、技术选型、竞品参考
+2. document-write  → 写四份文档（产品需求 / 产品设计 / 技术需求 / 技术设计）
+3. code-write      → 实现（建议 TDD：先写测试再写代码）
+4. code-review     → 自审查提交前的完整改动
+5. project-tasks   → 更新 TASK.md，标记完成
+```
+
+> **Note on docs:** The user prefers a four-doc split for feature work: 产品需求 (PRD), 产品设计 (product design), 技术需求 (TRD), 技术设计 (technical design). See `references/operations/document-write.md` for details. For small/straightforward features, a PRD+TRD pair may suffice — use judgment.
+
+## Loop Patterns
+
+The sequence isn't always linear. Common loops:
+
+- **PRD iteration**: 2 ↔ 用户 — 需求讨论 → 改 PRD → 再讨论
+- **Dev iteration**: 3 ↔ 4 — review 发现问题 → 修复 → 重新 review
+- **Architecture re-evaluation**: 3 → 1 — 实现中发现更好的方案 → 重新调研
+
+## Checklist Template
+
+```
+- [ ] Phase 1 — Research & design (info-search + document-write)
+- [ ] BREAK: 方案确认后再实现
+- [ ] Phase 2 — Implementation (code-write with TDD)
+- [ ] Phase 3 — Review & fix (code-review)
+- [ ] BREAK: 审查结果是否接受？
+- [ ] Phase 4 — Finalize & update task status
+```
+
+## Pitfalls
+
+- **Starting coding without design** — always do info-search + document-write first. Writing code without a plan is the #1 cause of rework.
+- **Forgetting BREAK points** — PRD review and code review both need a checkpoint. Add BREAK between phases.
+- **Single big commit** — commit per operation, not one giant commit at the end. Each commit should be a coherent unit.
+- **Skipping tests** — code-write without tests means code-review has no safety net. Always include tests.

task-framework/skills/task-framework/references/document-analysis-workflow.md

@@ -0,0 +1,95 @@
+# Document Analysis Workflow (PPT / PDF)
+
+When a project task involves analyzing a document (PPTX, PDF, DOCX), follow this pattern to extract content and produce structured docs.
+
+## Prerequisites
+
+Create a project venv if one doesn't exist:
+
+```bash
+cd <project-root>
+uv venv
+source .venv/bin/activate
+uv pip install python-pptx  # for PPTX files
+# or for PDF: uv pip install pymupdf  (marker-pdf for complex PDFs)
+```
+
+## Step 1 — Write an extraction script
+
+Do NOT use inline heredocs for Python scripts — shell quoting issues (nested quotes, `\n`, f-strings) are guaranteed to fail. Write a `.py` file under the task's `scripts/` dir instead.
+
+Example (`scripts/extract_ppt.py`):
+
+```python
+#!/usr/bin/env python3
+"""Extract all text and structure from a PPT."""
+
+from pptx import Presentation
+import os
+
+# Resolve the PPT path relative to the script
+pptx_path = os.path.join(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+    "S-filename.pptx"
+)
+
+prs = Presentation(pptx_path)
+print(f"Total slides: {len(prs.slides)}")
+
+for i, slide in enumerate(prs.slides, 1):
+    print(f"\n{'='*80}")
+    print(f"SLIDE {i}")
+    print(f"{'='*80}")
+
+    for shape in slide.shapes:
+        text = ""
+        has_image = False
+
+        if shape.has_text_frame:
+            for para in shape.text_frame.paragraphs:
+                t = para.text.strip()
+                if t:
+                    text += t + "\n"
+
+        if shape.shape_type == 13:  # Picture
+            has_image = True
+
+        if text.strip() or has_image:
+            tag = " [IMAGE]" if has_image else ""
+            print(f"\n  [{shape.name}]{tag}")
+            if text.strip():
+                for line in text.strip().split("\n"):
+                    print(f"    {line}")
+```
+
+## Step 2 — Save raw output to logs/
+
+```bash
+cd <project-root>
+source .venv/bin/activate
+ts=$(date '+%Y%m%d-%H%M%S')
+python3 tasks/*.<task-name>/scripts/extract_ppt.py \
+  > "tasks/*.<task-name>/logs/output.${ts}.log" 2>&1
+```
+
+## Step 3 — Analyze and write structured docs to docs/
+
+Organize findings into focused markdown files under `docs/`. Each file covers one domain:
+
+| File | Content |
+|------|---------|
+| `docs/01-project-background.md` | Background, policy, market analysis |
+| `docs/02-project-plan.md` | Architecture, technical solution, product design |
+| `docs/03-cost-and-roadmap.md` | Budget, timeline, investment analysis |
+| `docs/04-cooperation-resources.md` | Partners, team, training resources |
+| `docs/05-benefits-and-outlook.md` | Economic/social benefits, forecasts |
+| `docs/06-product-requirements-summary.md` | PRD-style consolidated summary |
+
+Number prefix (`01-`, `02-`...) ensures chronological ordering in `ls` and file explorers. Use meaningful topic names, not `slide-notes.md`.
+
+## Pitfalls
+
+- **Heredoc quoting fails** — Python f-strings with `\n`, nested quotes, and shell variable expansion in heredoc bodies all break. Always write extraction scripts to a `.py` file.
+- **python-pptx cannot extract embedded images' text content** — charts in image-only slides yield `[IMAGE]` with no text. Note these in docs as "diagram — see PPT directly."
+- **Chinese text truncation** — `sed -n '3p'` on README.md with Chinese characters may truncate mid-character if `head -c` cuts at the wrong byte boundary. Use `head -c 60 | head -n 1` to avoid splitting multi-byte chars.
+- **Blank lines after `## Status`** — TASK.md format has `## Status` → blank line → status value. `grep -A1` picks up the blank line; use `grep -A2` + `tail -1` to get the actual status. Both code snippets and pitfall text must use `-A2`.

task-framework/skills/task-framework/references/file-safety-lesson.md

@@ -0,0 +1,38 @@
+# File Safety Lesson — 50MB PPT Loss (2026-06-02)
+
+## What happened
+
+A 50MB PPT file (`灵泽——心脑血管主动健康示范（5.18）.pptx`) was lost during `task_inbox_accept`. The `mv` command appeared to succeed (no error output, `ls -la` immediately after showed the file at the destination), but the file was later found to be gone — neither at source nor destination.
+
+## Root cause
+
+`mv` with Chinese filenames across a shell heredoc boundary can silently fail due to encoding/path resolution issues. **No error message was produced** — the `mv` appeared successful but the file never actually arrived.
+
+## The fix
+
+Never use `mv` for file moves. Always use a two-step approach:
+
+1. **Step 1 — Create hard link (or copy)**
+   - Same filesystem: `ln <src> <dst>` (instant, no space cost)
+   - Cross-filesystem or symlink: `cp <src> <dst>` (slower but safe)
+
+2. **Step 2 — Verify then delete**
+   ```
+   ls -la <dst>/ && rm -rf <src>
+   ```
+   The `&&` ensures the delete only runs if verification succeeds.
+
+## Verification checklist after ANY file move
+
+```bash
+# 1. Confirm destination exists
+ls -la <dst>/        # must show the file
+# 2. Check file size matches
+ls -l <dst>/<file>   # compare with expected size
+# 3. Only then remove source
+rm -rf <src>
+```
+
+## Why this matters for Hermes agents
+
+Terminal commands may produce false positives — an `mv` that prints no error can still fail silently. The agent's shell session, encoding context, and CWD may differ from what the command expects. Two-step ln/cp+rm with explicit ls verification eliminates this class of bug.