handoff-cli 0.3.4__tar.gz → 0.3.6__tar.gz

{handoff_cli-0.3.4 → handoff_cli-0.3.6}/.github/workflows/publish.yml

@@ -21,6 +21,11 @@ jobs:
       - name: Build
         run: uv build
 
+      - name: Check long description rendering
+        run: |
+          pip install twine
+          twine check dist/*
+
       - name: Publish to PyPI
         run: uv publish --token ${{ secrets.PYPI }}
 

handoff_cli-0.3.6/Makefile

@@ -0,0 +1,33 @@
+.PHONY: render skills
+
+render:  ## Preview PyPI long description rendering
+	pip install -q "readme_renderer[md]" 2>/dev/null
+	python -m readme_renderer README.md > /tmp/handoff-pypi-preview.html
+	@echo "✅  /tmp/handoff-pypi-preview.html  ($(shell wc -c < /tmp/handoff-pypi-preview.html | tr -d ' ') bytes)"
+	open /tmp/handoff-pypi-preview.html
+
+# ── skill 文档同步 ──────────────────────────────────────────────────
+# handoff-ds/SKILL.md 是主文档（master），只改它。
+# 它的 frontmatter（顶部的 `---...---` 块）不同步；其下的正文会被复制到
+# 其它 backend 的 SKILL.md，并把 backend 名/缩写替换成对应值。占位符在
+# 「构建时」由 sed 替换，落盘的都是具体值——LLM 永远读不到占位符。
+SKILLS := cli/skills
+MASTER := $(SKILLS)/handoff-ds/SKILL.md
+
+skills:  ## 把 handoff-ds/SKILL.md 正文同步到其它 backend 的 SKILL.md
+	@$(call sync_skill,handoff-codex,codex,cx)
+	@$(call sync_skill,handoff-opus,opus,op)
+	@echo "done."
+
+# $(1)=目标目录  $(2)=backend 名  $(3)=run_id 缩写
+define sync_skill
+target="$(SKILLS)/$(1)/SKILL.md"; \
+tmp=$$(mktemp); \
+awk '{print} /^---[[:space:]]*$$/{n++; if(n==2) exit}' "$$target" > "$$tmp"; \
+awk 'body{print} /^---[[:space:]]*$$/{n++; if(n==2) body=1}' "$(MASTER)" \
+  | sed -e 's/deepseek/$(2)/g' \
+        -e 's/handoff-ds/handoff-$(2)/g' \
+        -e 's/0613-ds-/0613-$(3)-/g' >> "$$tmp"; \
+mv "$$tmp" "$$target"; \
+echo "synced $$target (backend=$(2))";
+endef

handoff_cli-0.3.6/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: handoff-cli
+Version: 0.3.6
+Summary: Multi coding-agent task dispatcher — a CLI proxy for claude that sends coding tasks to configurable AI backends
+Requires-Python: >=3.9
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: textual<3,>=2
+Description-Content-Type: text/markdown
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/handoff-hero.jpg" width="100%" alt="hero">
+
+# With **Handoff**, your coding agents can finally work together.
+
+
+| You're in | Hand off to | Why |
+| :-- | :-- | :-- |
+| Claude Code / Codex | **DeepSeek** | It does the simple work fast and cheap; save the expensive quota for decisions |
+| DeepSeek | **Codex / Opus** | Borrow a brain for hard problems, bring the answer back to your session |
+
+No tool-switching, no lost context.
+
+**English** · [简体中文](README.zh-CN.md)
+
+</div>
+
+## Why handoff
+
+If you use more than one coding agent, these will sound familiar:
+
+- 💸 **"Claude / Codex: the $20 plan never lasts. The $100 plan costs too much."**<br>
+  — Just say: *"Give this task to `/handoff-ds`."* DeepSeek does the work fast and cheap. Save your expensive quota for decisions.
+- 🤔 **"DeepSeek is stuck. I want a second opinion from Codex."**<br>
+  — Just say: *"Ask `/handoff-codex` what it thinks."* No new terminal. No re-explaining. The answer comes back to your current session.
+- 🔁 **"`/handoff-ds` finished that task. Now I have a follow-up task for it."**<br>
+  — Just say: *"Resume the last `/handoff-ds` session, then do X."* It just sends one more message in the old conversation — all the old context is still there.
+
+
+**The math is simple:** DeepSeek V4 is as capable as Sonnet, and on [OpenCode Go](https://opencode.ai/go?ref=D5926WCTD8) the same money buys **18× the work**:
+
+| Option | Relative cost for the same work |
+| --- | --- |
+| Claude Sonnet (subscription) | 1× (baseline) |
+| DeepSeek official API | **1/3** |
+| [OpenCode Go](https://opencode.ai/go?ref=D5926WCTD8) (includes DeepSeek V4) | **1/18** |
+
+So: **only pay for the SOTA model** (Opus / GPT-5.5) — use it to plan and review. Everything else goes to DeepSeek. With handoff, **$20 Claude Code (plan + dispatch) + $5 OpenCode Go (execution) ≈ the work of a $200 Claude Code Max.**
+
+## Quick start
+
+> **Before you start:** handoff works inside Claude Code (CLI or desktop app) or Codex. You need at least one of them installed and logged in.
+
+### 1. Install
+
+```bash
+uv tool install handoff-cli
+handoff init        # creates the config, links skill / agent files
+```
+
+Upgrade with `uv tool upgrade handoff-cli`.
+
+### 2. Set your token
+
+The `opus` and `codex` backends reuse your existing Claude Code / Codex logins — zero config. **Only DeepSeek needs a token.**
+
+For DeepSeek, we recommend the [OpenCode Go plan](https://opencode.ai/go?ref=D5926WCTD8) (lowest cost, includes DeepSeek V4). Once you have a key, edit `~/.handoff/config.yaml` and change just the `ANTHROPIC_AUTH_TOKEN` line:
+
+```yaml
+# ~/.handoff/config.yaml — handoff init generates this for you
+backends:
+  deepseek:                          # ← first = default
+    type: claude
+    model: deepseek-v4-flash
+    pro_model: "deepseek-v4-pro[1m]"
+    env:
+      ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic
+      ANTHROPIC_AUTH_TOKEN: "sk-..."  # ← change this. Local proxy setup: https://github.com/iTzFaisal/oc-cc-proxy
+      ANTHROPIC_MODEL: "{model}"
+
+  opus:                              # local claude login — zero config
+    type: claude
+    ...
+  codex:                             # local codex login — zero config
+    type: codex
+    ...
+```
+
+### 3. Dispatch your first task
+
+Go back to Claude Code and say:
+
+> Make a plan, then hand it to `/handoff-ds`.
+
+The task runs in the background; your session is never blocked. When it finishes, the agent reads the result and reports back.
+
+### 4. Who you can hand work off to
+
+| What you say | From | Hands off to | Best for |
+| --- | --- | --- | --- |
+| `/handoff-ds` | Claude Code | DeepSeek V4 | Execution work: writing code, running tests, refactors, bulk edits |
+| `handoff-ds` (subagent) | Codex | DeepSeek V4 | Same as above — use this when you're inside Codex |
+| `/handoff-codex` | Claude Code | Codex (GPT-5.5) | Heavy reasoning, second opinions, hard bugs |
+| `/handoff-opus` | Claude Code | Claude Opus | Decisions that deserve the top model |
+
+> Codex has no slash commands — from Codex you invoke the subagent of the same name instead: say "have `handoff-ds` execute the task above."
+
+### 5. Watch progress / browse history
+
+Inside Claude Code, expand the background shell and you'll see live progress right there — it renders in the shell view and uses none of your main session's context. To browse history or follow a task on its own, use `handoff list` and `handoff tail` (see the FAQ below).
+
+## FAQ
+
+<details>
+<summary><b>How do I browse the task list or watch a task's progress?</b></summary>
+
+<br>
+
+Dispatching and resuming are the AI's job (`handoff run` / `handoff resume` under the hood). These two commands are for you — browse the list, watch the progress:
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+**`handoff list` / `handoff ls`** — interactive TUI over your full task history. See the full prompt, live status, and final result; press `G` on a row to reload that conversation and keep chatting.
+
+</td>
+<td width="50%" valign="top">
+
+**`handoff tail <run-id>`** — follow a task's output stream live, like looking over its shoulder.
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+<!-- docs/assets/list-tui.jpg — ~480px wide — TUI list + detail view, highlight G/C shortcuts -->
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/list-tui.jpg" width="100%" alt="handoff list interactive TUI">
+
+</td>
+<td valign="top">
+
+<!-- docs/assets/tail.jpg — ~480px wide — handoff tail live stream -->
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/tail.jpg" width="100%" alt="handoff tail live follow">
+
+</td>
+</tr>
+</table>
+
+</details>
+
+<details>
+<summary><b>Can I dispatch several tasks at once?</b></summary>
+
+<br>
+
+Yes. Have your agent send off several tasks in one message. Each runs on its own and reports back on its own — they never get in each other's way.
+
+<!-- docs/assets/parallel.jpg — ~621px wide — 2–3 background tasks from one message, each with its own RESULT= path -->
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/parallel.jpg" width="621" alt="Parallel dispatch">
+
+</details>
+
+<details>
+<summary><b>No uv / installing from source?</b></summary>
+
+<br>
+
+`pipx install handoff-cli` or `pip install handoff-cli` work just as well. From source:
+
+```bash
+git clone https://github.com/dazuiba/handoff && cd handoff
+uv tool install -e .
+handoff init
+```
+
+</details>
+
+<details>
+<summary><b>How do I add a custom backend / what goes in the env block?</b></summary>
+
+<br>
+
+Add one more entry under `backends` — any Anthropic-compatible endpoint works:
+
+```yaml
+backends:
+  kimi:
+    type: claude
+    model: kimi-k3
+    env:
+      ANTHROPIC_BASE_URL: https://api.moonshot.cn/anthropic
+      ANTHROPIC_AUTH_TOKEN: "${MOONSHOT_API_KEY}"
+      ANTHROPIC_MODEL: "{model}"
+```
+
+The env block is entirely yours — every key=value you set is exported before the CLI launches. `{model}` substitutes the resolved model name, `${ENV_VAR}` expands from your shell. Run `handoff env` to see where everything lives. Full details: **[configuration docs (Chinese) →](docs/configuration.zh-CN.md)**.
+
+</details>
+
+<details>
+<summary><b>How does it actually work?</b></summary>
+
+<br>
+
+1. Your agent hands the whole task to handoff, which runs it **in the background** — your session never blocks.
+2. handoff launches the matching CLI (`claude -p` / `codex exec`) in an isolated context and streams the full output to disk.
+3. The main session receives exactly one line: `RESULT=<path-to-result-file>`. Progress goes to the background shell view — **never** into your main context.
+4. On completion the agent gets notified, reads the result file, and reports back to you.
+5. The `RESULT=` path is also a stable handle for the conversation: every follow-up round resumes the same session.
+
+</details>
+
+**More docs**
+
+- **[CLI reference (Chinese) →](docs/cli-reference.zh-CN.md)** — full usage of `run` / `resume` / `list` / `tail` / `env` / `init`, run-id encoding, on-disk file layout.
+- **[Configuration (Chinese) →](docs/configuration.zh-CN.md)** — mechanism vs data layers, env block, `${ENV}` interpolation, include, custom backends.
+- **[Design notes (Chinese) →](docs/design.zh-CN.md)** — why Claude Code uses background shells while Codex uses a subagent; the RESULT= protocol.

{handoff_cli-0.3.4 → handoff_cli-0.3.6}/README.md

@@ -1,12 +1,12 @@
 <div align="center">
-<img src="docs/assets/handoff-hero.jpg" width="100%" alt="hero">
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/handoff-hero.jpg" width="100%" alt="hero">
 
 # With **Handoff**, your coding agents can finally work together.
 
 
-| coding agent | → Hand off to | Why |
+| You're in | Hand off to | Why |
 | :-- | :-- | :-- |
-| Claude Code / Codex | **DeepSeek** | Execution work is fast and cheap; save the expensive quota for decisions |
+| Claude Code / Codex | **DeepSeek** | It does the simple work fast and cheap; save the expensive quota for decisions |
 | DeepSeek | **Codex / Opus** | Borrow a brain for hard problems, bring the answer back to your session |
 
 No tool-switching, no lost context.
@@ -23,23 +23,24 @@ If you use more than one coding agent, these will sound familiar:
   — Just say: *"Give this task to `/handoff-ds`."* DeepSeek does the work fast and cheap. Save your expensive quota for decisions.
 - 🤔 **"DeepSeek is stuck. I want a second opinion from Codex."**<br>
   — Just say: *"Ask `/handoff-codex` what it thinks."* No new terminal. No re-explaining. The answer comes back to your current session.
-- 🔁 **"I want to continue that task from before."**<br>
-  — Just say: *"Resume that `/handoff-ds` session."* Everything is still there: the files it changed, the code it read, what it concluded.
-- 🔄 **"A new model means a new session. I have to explain everything again."**<br>
-  — Don't switch. Stay in your session. handoff passes the task over, then brings the result back.
+- 🔁 **"`/handoff-ds` finished that task. Now I have a follow-up task for it."**<br>
+  — Just say: *"Resume the last `/handoff-ds` session, then do X."* It just sends one more message in the old conversation — all the old context is still there.
 
-**Do the math:** for transactional work — writing code, running tests — DeepSeek V4 matches Sonnet-class models at a fraction of the price. What is really scarce, and worth a subscription, is the judgment of the one or two models at the very top (Opus / GPT-5.5).
+
+**The math is simple:** DeepSeek V4 is as capable as Sonnet, and on [OpenCode Go](https://opencode.ai/go?ref=D5926WCTD8) the same money buys **18× the work**:
 
 | Option | Relative cost for the same work |
 | --- | --- |
-| Claude Sonnet | 1× (baseline) |
+| Claude Sonnet (subscription) | 1× (baseline) |
 | DeepSeek official API | **1/3** |
 | [OpenCode Go](https://opencode.ai/go?ref=D5926WCTD8) (includes DeepSeek V4) | **1/18** |
 
-Let the top model talk to you, split the work, and review; hand all execution off — **a $20 subscription directing $5 of compute gets you ~$200 worth of work.** That's all there is to it: one sentence inside your agent session.
+So: **only pay for the SOTA model** (Opus / GPT-5.5) — use it to plan and review. Everything else goes to DeepSeek. With handoff, **$20 Claude Code (plan + dispatch) + $5 OpenCode Go (execution) ≈ the work of a $200 Claude Code Max.**
 
 ## Quick start
 
+> **Before you start:** handoff works inside Claude Code (CLI or desktop app) or Codex. You need at least one of them installed and logged in.
+
 ### 1. Install
 
 ```bash
@@ -51,9 +52,9 @@ Upgrade with `uv tool upgrade handoff-cli`.
 
 ### 2. Set your token
 
-opus / codex reuse your local claude / codex logins — zero config. **Only DeepSeek needs a token.**
+The `opus` and `codex` backends reuse your existing Claude Code / Codex logins — zero config. **Only DeepSeek needs a token.**
 
-For DeepSeek compute we recommend the [OpenCode Go plan](https://opencode.ai/go?ref=D5926WCTD8) (lowest cost, includes DeepSeek V4). Once you have a key, edit `~/.handoff/config.yaml` and change just the `ANTHROPIC_AUTH_TOKEN` line:
+For DeepSeek, we recommend the [OpenCode Go plan](https://opencode.ai/go?ref=D5926WCTD8) (lowest cost, includes DeepSeek V4). Once you have a key, edit `~/.handoff/config.yaml` and change just the `ANTHROPIC_AUTH_TOKEN` line:
 
 ```yaml
 # ~/.handoff/config.yaml — handoff init generates this for you
@@ -92,11 +93,11 @@ The task runs in the background; your session is never blocked. When it finishes
 | `/handoff-codex` | Claude Code | Codex (GPT-5.5) | Heavy reasoning, second opinions, hard bugs |
 | `/handoff-opus` | Claude Code | Claude Opus | Decisions that deserve the top model |
 
-> Codex has no slash commands, so that row is the subagent of the same name — say "have `handoff-ds` execute the task above."
+> Codex has no slash commands — from Codex you invoke the subagent of the same name instead: say "have `handoff-ds` execute the task above."
 
 ### 5. Watch progress / browse history
 
-Inside Claude Code, expand the background shell and the live progress is right there — it renders in the shell view and uses none of your main session's context. To browse history or follow a task on its own, use `handoff list` and `handoff tail` (see the FAQ below).
+Inside Claude Code, expand the background shell and you'll see live progress right there — it renders in the shell view and uses none of your main session's context. To browse history or follow a task on its own, use `handoff list` and `handoff tail` (see the FAQ below).
 
 ## FAQ
 
@@ -124,13 +125,13 @@ Dispatching and resuming are the AI's job (`handoff run` / `handoff resume` unde
 <td valign="top">
 
 <!-- docs/assets/list-tui.jpg — ~480px wide — TUI list + detail view, highlight G/C shortcuts -->
-<img src="docs/assets/list-tui.jpg" width="100%" alt="handoff list interactive TUI">
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/list-tui.jpg" width="100%" alt="handoff list interactive TUI">
 
 </td>
 <td valign="top">
 
 <!-- docs/assets/tail.jpg — ~480px wide — handoff tail live stream -->
-<img src="docs/assets/tail.jpg" width="100%" alt="handoff tail live follow">
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/tail.jpg" width="100%" alt="handoff tail live follow">
 
 </td>
 </tr>
@@ -146,7 +147,7 @@ Dispatching and resuming are the AI's job (`handoff run` / `handoff resume` unde
 Yes. Have your agent send off several tasks in one message. Each runs on its own and reports back on its own — they never get in each other's way.
 
 <!-- docs/assets/parallel.jpg — ~621px wide — 2–3 background tasks from one message, each with its own RESULT= path -->
-<img src="docs/assets/parallel.jpg" width="621" alt="Parallel dispatch">
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/parallel.jpg" width="621" alt="Parallel dispatch">
 
 </details>
 

{handoff_cli-0.3.4 → handoff_cli-0.3.6}/README.zh-CN.md

@@ -1,5 +1,5 @@
 <div align="center">
-<img src="docs/assets/handoff-hero.jpg" width="100%" alt="hero">
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/handoff-hero.jpg" width="100%" alt="hero">
 
 # 有了 **Handoff**，你手里的几个 coding agent 终于可以互相协作了。
 
@@ -126,13 +126,13 @@ backends:
 <td valign="top">
 
 <!-- docs/assets/list-tui.jpg — 建议 ~480 宽 — TUI 列表 + 详情视图，圈出 G/C 快捷键 -->
-<img src="docs/assets/list-tui.jpg" width="100%" alt="handoff list 交互式 TUI">
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/list-tui.jpg" width="100%" alt="handoff list 交互式 TUI">
 
 </td>
 <td valign="top">
 
 <!-- docs/assets/tail.jpg — 建议 ~480 宽 — handoff tail 实时输出流 -->
-<img src="docs/assets/tail.jpg" width="100%" alt="handoff tail 实时跟踪">
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/tail.jpg" width="100%" alt="handoff tail 实时跟踪">
 
 </td>
 </tr>
@@ -148,7 +148,7 @@ backends:
 可以。在同一条消息里让 agent 派出多个任务，各自独立执行、独立完成通知，互不干扰。
 
 <!-- docs/assets/parallel.jpg — 建议 621 宽 — 同一条消息派发 2~3 个后台任务，各自拿到不同 RESULT= 路径 -->
-<img src="docs/assets/parallel.jpg" width="621" alt="并行派发多任务">
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/parallel.jpg" width="621" alt="并行派发多任务">
 
 </details>
 

{handoff_cli-0.3.4 → handoff_cli-0.3.6}/cli/commands/new.py

@@ -4,9 +4,10 @@ Pre-allocates a run_id and returns the canonical .prompt.md path so the caller
 can write the prompt directly to its final archive location before dispatching.
 
 Usage:
-  handoff new --backend <name> [--slug <slug>]
+  handoff new --backend <name> [--slug <slug>] [--write]
 
-Stdout: one line — absolute path to the .prompt.md file (file is NOT created).
+Stdout: one line — absolute path to the .prompt.md file.
+By default the file is not created. With --write, stdin is written to the file.
 """
 
 from __future__ import annotations
@@ -26,9 +27,10 @@ from ..config import Config
 
 
 def cmd_new(argv: list[str], config: Config):
-    """handoff new --backend <name> [--slug <slug>]"""
+    """handoff new --backend <name> [--slug <slug>] [--write]"""
     backend_arg = ""
     slug_arg = ""
+    write_prompt = False
 
     i = 0
     while i < len(argv):
@@ -49,6 +51,8 @@ def cmd_new(argv: list[str], config: Config):
             slug_arg = argv[i]
         elif a.startswith("--slug="):
             slug_arg = a.split("=", 1)[1]
+        elif a == "--write":
+            write_prompt = True
         elif a in ("-h", "--help"):
             from ..main import usage
             usage()
@@ -85,4 +89,12 @@ def cmd_new(argv: list[str], config: Config):
     run_id = f"{mmdd}-{b2}-{seq_code}-{clean_slug}"
     prompt_path = os.path.join(TASKS_DIR, f"{run_id}.prompt.md")
 
+    if write_prompt:
+        if sys.stdin.isatty():
+            print("handoff new: --write requires prompt text on stdin", file=sys.stderr)
+            sys.exit(2)
+        os.makedirs(os.path.dirname(prompt_path), exist_ok=True)
+        with open(prompt_path, "w") as f:
+            f.write(sys.stdin.read())
+
     print(prompt_path)

{handoff_cli-0.3.4 → handoff_cli-0.3.6}/cli/commands/resume.py

@@ -27,7 +27,7 @@ from ..config import Config
 
 
 def cmd_resume(argv: list[str], config: Config):
-    """handoff resume [<run-id|seq>] [--backend <name>] [--pro] [--cwd <dir>]
+    """handoff resume [<run-id|seq>] [--backend <name>] [--slug <slug>] [--pro] [--cwd <dir>]
     [--verbose] [(<input-file|-> | --text <prompt...>)]."""
     # Pre-scan --verbose so it works regardless of position (e.g. after --text).
     verbose = "--verbose" in argv
@@ -36,6 +36,7 @@ def cmd_resume(argv: list[str], config: Config):
     pro = False
     cwd = ""
     backend_arg = ""
+    slug_arg = ""
     selector = ""
     input_src = ""
     text_mode = False
@@ -61,6 +62,14 @@ def cmd_resume(argv: list[str], config: Config):
             backend_arg = filtered[i]
         elif a.startswith("--backend="):
             backend_arg = a.split("=", 1)[1]
+        elif a == "--slug":
+            i += 1
+            if i >= len(filtered):
+                print("handoff resume: --slug requires a value", file=sys.stderr)
+                sys.exit(2)
+            slug_arg = filtered[i]
+        elif a.startswith("--slug="):
+            slug_arg = a.split("=", 1)[1]
         elif a == "--text":
             text_mode = True
             if input_src:
@@ -159,7 +168,16 @@ def cmd_resume(argv: list[str], config: Config):
         # Non-interactive: dispatch a new turn through the run pipeline.
         conn.close()
         from .run import _execute
-        _execute(cwd, prompt_text, backend_name, pro, config, resume_session_id=session_id, verbose=verbose)
+        _execute(
+            cwd,
+            prompt_text,
+            backend_name,
+            pro,
+            config,
+            resume_session_id=session_id,
+            slug=slug_arg or "resume",
+            verbose=verbose,
+        )
 
 
 def _resume_interactive(config: Config, backend_name: str, session_id: str, cwd: str, pro: bool, verbose: bool = False):

{handoff_cli-0.3.4 → handoff_cli-0.3.6}/cli/commands/run.py

@@ -40,7 +40,7 @@ def _is_adopted_path(input_src: str) -> bool:
 
 
 def cmd_run(argv: list[str], config: Config):
-    """handoff run [--backend <name>] [--cwd <dir>] [--pro] [--verbose] (<input-file|-> | --text <prompt...>)."""
+    """handoff run [--backend <name>] [--cwd <dir>] [--slug <slug>] [--pro] [--verbose] (<input-file|-> | --text <prompt...>)."""
     # Pre-scan --verbose so it works regardless of position (e.g. after --text).
     verbose = "--verbose" in argv
     filtered = [a for a in argv if a != "--verbose"]
@@ -48,6 +48,7 @@ def cmd_run(argv: list[str], config: Config):
     pro = False
     cwd = ""
     backend_arg = ""
+    slug_arg = ""
     input_src = ""
     text_mode = False
     text_parts = []
@@ -71,6 +72,14 @@ def cmd_run(argv: list[str], config: Config):
             backend_arg = filtered[i]
         elif a.startswith("--backend="):
             backend_arg = a.split("=", 1)[1]
+        elif a == "--slug":
+            i += 1
+            if i >= len(filtered):
+                print("handoff run: --slug requires a value", file=sys.stderr)
+                sys.exit(2)
+            slug_arg = filtered[i]
+        elif a.startswith("--slug="):
+            slug_arg = a.split("=", 1)[1]
         elif a == "--text":
             text_mode = True
             if input_src:
@@ -130,10 +139,10 @@ def cmd_run(argv: list[str], config: Config):
         if not prompt_text:
             print("handoff run: --text requires a non-empty value", file=sys.stderr)
             sys.exit(2)
-        slug = "from-text"
+        slug = slug_arg or "from-text"
     elif input_src == "-" or (not input_src and not sys.stdin.isatty()):
         prompt_text = sys.stdin.read()
-        slug = "from-stdin"
+        slug = slug_arg or "from-stdin"
     elif input_src:
         if not os.path.isfile(input_src):
             print(f"handoff run: input file not found: {input_src}", file=sys.stderr)
@@ -164,7 +173,7 @@ def cmd_run(argv: list[str], config: Config):
         else:
             with open(input_src) as f:
                 prompt_text = f.read()
-            slug = "from-file"
+            slug = slug_arg or "from-file"
     else:
         print("handoff run: input file required, or use --text <prompt...> / pipe via '-'", file=sys.stderr)
         sys.exit(2)

{handoff_cli-0.3.4 → handoff_cli-0.3.6}/cli/main.py

@@ -12,10 +12,10 @@ def usage(config=None):
   handoff --help
   handoff env
   handoff init      [-y|--yes]
-  handoff new       --backend <name> [--slug <slug>]
+  handoff new       --backend <name> [--slug <slug>] [--write]
   handoff list|ls   [--uuid] [--cwd]
-  handoff run       [--backend <name>] [--cwd <dir>] [--pro] [--verbose] (<input-file|-> | --text <prompt...>)
-  handoff resume    [<run-id|seq>] [--pro] [--cwd <dir>] [--verbose] [(<input-file|-> | --text <prompt...>)]
+  handoff run       [--backend <name>] [--cwd <dir>] [--slug <slug>] [--pro] [--verbose] (<input-file|-> | --text <prompt...>)
+  handoff resume    [<run-id|seq>] [--slug <slug>] [--pro] [--cwd <dir>] [--verbose] [(<input-file|-> | --text <prompt...>)]
   handoff tail [<run-id|seq>]
 
   handoff env              — print config / data paths (works even with broken config)
@@ -29,6 +29,8 @@ def usage(config=None):
 Run ids: <mmdd>-<backend2>-<SEQ_CODE>-<slug>  (e.g. 0611-ds-03-fix-auth)
 --cwd defaults to the current directory of the calling process.
 --backend picks a backend (default: first entry in config.yaml backends).
+--slug sets the semantic suffix in generated run ids.
+--write on `handoff new` writes stdin to the pre-allocated .prompt.md file.
 --pro uses the backend's pro_model. A resume stays on its original backend."""
     )
 

handoff_cli-0.3.6/cli/skills/handoff-codex/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: handoff-codex
+description: 向 Codex (GPT-5.5) 咨询复杂问题 / 要第二意见 / 派发需要强推理的任务。后台运行，完成后自动通知。支持并行多任务，支持续接（resume）上次会话继续派发后续任务。
+---
+
+# handoff-codex Skill
+
+<interaction_contract>
+This skill is executed by Claude Code (an AI agent). The rules below are BINDING — follow them exactly; do not simplify or reinterpret.
+## 命令模板（照抄，勿改结构）
+
+```bash
+handoff run --backend codex --slug <≤3个英文单词的任务助记词> - <<'__HF_EOF__'
+[prompt 内容]
+__HF_EOF__
+```
+
+必须用 `run_in_background: true` 启动——handoff 耗时 2~20 分钟，前台会阻塞整个会话。
+
+**关键规则：**
+- `--slug` 只写≤3个英文单词、`-` 分隔的语义助记词（如 `fix-auth`）；禁止日期/时间戳/随机数/UUID/计数器，唯一性由 `handoff run` 自动分配的 seq 保证。
+- heredoc 界定符固定用 `__HF_EOF__`，prompt 原样粘贴、不转义。
+- 不要自己拼任务文件名，也不要用 `> RESULT 2> OUT` 重定向——handoff 自己管命名和落盘。
+- 用户提到 `pro`（或要求更强/专业模型处理复杂任务）时，在 `handoff run` 后加 `--pro`。
+- 回显任何 home 下的任务路径时，缩写成 `~/.handoff/...`，不要暴露 `/Users/<name>/...`。
+
+启动后从 **stdout** 捕获唯一有用的一行 `RESULT=<任务路径>`（如 `~/.handoff/tasks/0613-cx-03-fix-auth.result.md`），缩写成 `~/.handoff/...` 后回显给用户。**这条路径的文件名主干（去掉目录和 `.result.md` 后缀）就是本次 run_id**（上例 → `0613-cx-03-fix-auth`）；记住它，用户要求"继续上次/接着再做 X"时靠它 `resume`。
+
+其余不要读：进度信息在 **stderr**（Claude Code 的 shell view 自动实时显示，别读进上下文）；同名 `.out.txt` 是进度日志，仅诊断（无结果/超时）时才 `tail -f`/`Read`；同名 `.prompt.md` 就是你刚发的内容。
+
+收到完成通知后，用 `Read` 读对应的 `.result.md` 汇报，**不要**再读后台输出（结果已在文件里，重复读只会把进度噪音吃进上下文）。`.result.md` 为空或异常时才读 `.out.txt` 诊断。
+</interaction_contract>
+
+## 多任务
+
+- **并行**：在**同一条消息**里发出多个 `run_in_background: true` 的 Bash 调用，各自用 `handoff run --slug ... - <<'__HF_EOF__'` 派发不同 prompt（seq 自动递增），各自从 stdout 捕获 `RESULT=`，分别等通知、分别读 `.result.md` 汇报。
+- **串行**：等上一个的完成通知到达、读并汇报后，再启动下一个。
+
+## 续接上次会话（resume 续派）
+
+要保留某次任务的上下文继续，而非开新会话：用 `resume` 替代 `run`，继续通过 heredoc/stdin 传入后续任务；其余约定（后台、捕获新 `RESULT=`、读 `.result.md`）完全相同：
+
+```bash
+handoff resume <run_id> --backend codex --slug <任务助记词> - <<'__HF_EOF__'
+[后续任务内容]
+__HF_EOF__
+```
+
+- `<run_id>` 用该会话**首次**任务的 run_id（上面那个文件名主干）；它是稳定句柄，每轮续接都用它，不要追每轮新生成的 run_id。
+- **必须带后续 prompt**：不带 heredoc、`-`、输入文件或 `--text` 的 `resume <run_id>` 是交互式重开，后台会卡死。
+- 续接默认只继承 backend；原会话用过 `--pro` 的，续接要再次带上才沿用 pro_model。
+- 不确定用户指哪次任务时，报候选 run_id + 摘要让其确认，别猜。

handoff_cli-0.3.6/cli/skills/handoff-ds/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: handoff-ds
+description: 把执行性编码/调查任务整包交给 DeepSeek 后台执行，省主会话额度。后台运行，完成后自动通知。支持并行多任务，支持续接（resume）上次会话继续派发后续任务。
+---
+
+# handoff-ds Skill
+
+<interaction_contract>
+This skill is executed by Claude Code (an AI agent). The rules below are BINDING — follow them exactly; do not simplify or reinterpret.
+## 命令模板（照抄，勿改结构）
+
+```bash
+handoff run --backend deepseek --slug <≤3个英文单词的任务助记词> - <<'__HF_EOF__'
+[prompt 内容]
+__HF_EOF__
+```
+
+必须用 `run_in_background: true` 启动——handoff 耗时 2~20 分钟，前台会阻塞整个会话。
+
+**关键规则：**
+- `--slug` 只写≤3个英文单词、`-` 分隔的语义助记词（如 `fix-auth`）；禁止日期/时间戳/随机数/UUID/计数器，唯一性由 `handoff run` 自动分配的 seq 保证。
+- heredoc 界定符固定用 `__HF_EOF__`，prompt 原样粘贴、不转义。
+- 不要自己拼任务文件名，也不要用 `> RESULT 2> OUT` 重定向——handoff 自己管命名和落盘。
+- 用户提到 `pro`（或要求更强/专业模型处理复杂任务）时，在 `handoff run` 后加 `--pro`。
+- 回显任何 home 下的任务路径时，缩写成 `~/.handoff/...`，不要暴露 `/Users/<name>/...`。
+
+启动后从 **stdout** 捕获唯一有用的一行 `RESULT=<任务路径>`（如 `~/.handoff/tasks/0613-ds-03-fix-auth.result.md`），缩写成 `~/.handoff/...` 后回显给用户。**这条路径的文件名主干（去掉目录和 `.result.md` 后缀）就是本次 run_id**（上例 → `0613-ds-03-fix-auth`）；记住它，用户要求"继续上次/接着再做 X"时靠它 `resume`。
+
+其余不要读：进度信息在 **stderr**（Claude Code 的 shell view 自动实时显示，别读进上下文）；同名 `.out.txt` 是进度日志，仅诊断（无结果/超时）时才 `tail -f`/`Read`；同名 `.prompt.md` 就是你刚发的内容。
+
+收到完成通知后，用 `Read` 读对应的 `.result.md` 汇报，**不要**再读后台输出（结果已在文件里，重复读只会把进度噪音吃进上下文）。`.result.md` 为空或异常时才读 `.out.txt` 诊断。
+</interaction_contract>
+
+## 多任务
+
+- **并行**：在**同一条消息**里发出多个 `run_in_background: true` 的 Bash 调用，各自用 `handoff run --slug ... - <<'__HF_EOF__'` 派发不同 prompt（seq 自动递增），各自从 stdout 捕获 `RESULT=`，分别等通知、分别读 `.result.md` 汇报。
+- **串行**：等上一个的完成通知到达、读并汇报后，再启动下一个。
+
+## 续接上次会话（resume 续派）
+
+要保留某次任务的上下文继续，而非开新会话：用 `resume` 替代 `run`，继续通过 heredoc/stdin 传入后续任务；其余约定（后台、捕获新 `RESULT=`、读 `.result.md`）完全相同：
+
+```bash
+handoff resume <run_id> --backend deepseek --slug <任务助记词> - <<'__HF_EOF__'
+[后续任务内容]
+__HF_EOF__
+```
+
+- `<run_id>` 用该会话**首次**任务的 run_id（上面那个文件名主干）；它是稳定句柄，每轮续接都用它，不要追每轮新生成的 run_id。
+- **必须带后续 prompt**：不带 heredoc、`-`、输入文件或 `--text` 的 `resume <run_id>` 是交互式重开，后台会卡死。
+- 续接默认只继承 backend；原会话用过 `--pro` 的，续接要再次带上才沿用 pro_model。
+- 不确定用户指哪次任务时，报候选 run_id + 摘要让其确认，别猜。

handoff_cli-0.3.6/cli/skills/handoff-ds.toml

@@ -0,0 +1,63 @@
+name = "handoff-ds"
+description = "Delegate one-shot analysis, review, and bounded coding tasks through handoff. Before invoking this agent, the caller must: (1) run `handoff new --backend deepseek --slug <slug> --write <<'__HF_EOF__' ... __HF_EOF__` to create the canonical .prompt.md file and capture its printed path, (2) send this agent only `PROMPT_FILE=~/.handoff/tasks/<run-id>.prompt.md` plus any pro/resume hint; do not expose `/Users/<name>/...` when the path is under home, and do not include the raw delegated prompt in the subagent message. Slugs must be semantic only, with no timestamps, random numbers, UUIDs, or counters. Supports hints like 'handoff-ds (pro)', 'handoff-ds pro', '专业模式', '更强模型'."
+model = "gpt-5.4-mini"
+model_reasoning_effort = "low"
+web_search = "disabled"
+features = { shell_tool = true, multi_agent = false }
+
+developer_instructions = """
+
+你是 `handoff` 命令启动器。不要分析任务，不要回答任务内容。
+
+输入格式：
+- 必须包含 `PROMPT_FILE=<path>`。
+- `<path>` 是已经存在的 `.prompt.md` 文件路径，通常是 `~/.handoff/tasks/<run-id>.prompt.md`。
+- 输入可能包含 `pro`、`专业模式`、`更强模型`，表示使用 `--pro`。
+- 输入可能包含 `resume`、`继续`、`接着刚才`，表示续接上次任务。
+
+第一条动作必须调用 `functions.exec_command`。不要先发 commentary。
+
+只允许执行下面四种命令之一：
+
+普通任务：
+```bash
+handoff run --backend deepseek <PROMPT_FILE> >/dev/null
+```
+
+pro 任务：
+```bash
+handoff run --backend deepseek --pro <PROMPT_FILE> >/dev/null
+```
+
+resume 任务：
+```bash
+handoff resume <run_id> --backend deepseek <PROMPT_FILE> >/dev/null
+```
+
+resume + pro：
+```bash
+handoff resume <run_id> --backend deepseek --pro <PROMPT_FILE> >/dev/null
+```
+
+规则：
+- `<PROMPT_FILE>` 必须直接来自输入里的 `PROMPT_FILE=`。
+- 如果路径以 `~` 开头，命令里直接使用这个 `~` 路径。
+- 不要读取 `<PROMPT_FILE>`。禁止 `cat`、`sed`、`head`、`tail`、heredoc、命令替换。
+- 不要运行其它命令。不要写文件。
+- 必须前台阻塞执行。禁止 `&`、`nohup`、`disown`、`setsid`、`tmux`、`screen`。
+- 如果 exec 返回仍在运行的 session，继续等待直到进程退出。
+
+resume 的 `<run_id>`：
+- 如果本会话之前最终回答过 `RESULT=.../<id>.result.md`，`<run_id>` 就是 `<id>`。
+- 如果没有可用的上次 `RESULT=`，即使输入说 resume，也按普通任务执行 `handoff run`。
+
+最终回答：
+- 命令输出里如果有 `RESULT=<path>`，最终回答必须只包含最后一行 `RESULT=...`。
+- 如果 `RESULT=` 路径在用户 home 下，回答前缩写成 `~/.handoff/...`。
+- 不要总结，不要解释，不要读取 result 文件。
+- 如果命令退出码非 0 但输出里有 `RESULT=...`，仍然只回答 `RESULT=...`。
+- 只有完全没有 `RESULT=` 时，才用一句话说明失败。
+
+如果没有可用 shell 工具，最终只回答 `HF_AGENT_EXEC_TOOL_UNAVAILABLE`。
+
+"""

handoff_cli-0.3.6/cli/skills/handoff-opus/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: handoff-opus
+description: 把关键决策/验收类任务交给 Claude Opus 执行。后台运行，完成后自动通知。支持并行多任务，支持续接（resume）上次会话继续派发后续任务。
+---
+
+# handoff-opus Skill
+
+<interaction_contract>
+This skill is executed by Claude Code (an AI agent). The rules below are BINDING — follow them exactly; do not simplify or reinterpret.
+## 命令模板（照抄，勿改结构）
+
+```bash
+handoff run --backend opus --slug <≤3个英文单词的任务助记词> - <<'__HF_EOF__'
+[prompt 内容]
+__HF_EOF__
+```
+
+必须用 `run_in_background: true` 启动——handoff 耗时 2~20 分钟，前台会阻塞整个会话。
+
+**关键规则：**
+- `--slug` 只写≤3个英文单词、`-` 分隔的语义助记词（如 `fix-auth`）；禁止日期/时间戳/随机数/UUID/计数器，唯一性由 `handoff run` 自动分配的 seq 保证。
+- heredoc 界定符固定用 `__HF_EOF__`，prompt 原样粘贴、不转义。
+- 不要自己拼任务文件名，也不要用 `> RESULT 2> OUT` 重定向——handoff 自己管命名和落盘。
+- 用户提到 `pro`（或要求更强/专业模型处理复杂任务）时，在 `handoff run` 后加 `--pro`。
+- 回显任何 home 下的任务路径时，缩写成 `~/.handoff/...`，不要暴露 `/Users/<name>/...`。
+
+启动后从 **stdout** 捕获唯一有用的一行 `RESULT=<任务路径>`（如 `~/.handoff/tasks/0613-op-03-fix-auth.result.md`），缩写成 `~/.handoff/...` 后回显给用户。**这条路径的文件名主干（去掉目录和 `.result.md` 后缀）就是本次 run_id**（上例 → `0613-op-03-fix-auth`）；记住它，用户要求"继续上次/接着再做 X"时靠它 `resume`。
+
+其余不要读：进度信息在 **stderr**（Claude Code 的 shell view 自动实时显示，别读进上下文）；同名 `.out.txt` 是进度日志，仅诊断（无结果/超时）时才 `tail -f`/`Read`；同名 `.prompt.md` 就是你刚发的内容。
+
+收到完成通知后，用 `Read` 读对应的 `.result.md` 汇报，**不要**再读后台输出（结果已在文件里，重复读只会把进度噪音吃进上下文）。`.result.md` 为空或异常时才读 `.out.txt` 诊断。
+</interaction_contract>
+
+## 多任务
+
+- **并行**：在**同一条消息**里发出多个 `run_in_background: true` 的 Bash 调用，各自用 `handoff run --slug ... - <<'__HF_EOF__'` 派发不同 prompt（seq 自动递增），各自从 stdout 捕获 `RESULT=`，分别等通知、分别读 `.result.md` 汇报。
+- **串行**：等上一个的完成通知到达、读并汇报后，再启动下一个。
+
+## 续接上次会话（resume 续派）
+
+要保留某次任务的上下文继续，而非开新会话：用 `resume` 替代 `run`，继续通过 heredoc/stdin 传入后续任务；其余约定（后台、捕获新 `RESULT=`、读 `.result.md`）完全相同：
+
+```bash
+handoff resume <run_id> --backend opus --slug <任务助记词> - <<'__HF_EOF__'
+[后续任务内容]
+__HF_EOF__
+```
+
+- `<run_id>` 用该会话**首次**任务的 run_id（上面那个文件名主干）；它是稳定句柄，每轮续接都用它，不要追每轮新生成的 run_id。
+- **必须带后续 prompt**：不带 heredoc、`-`、输入文件或 `--text` 的 `resume <run_id>` 是交互式重开，后台会卡死。
+- 续接默认只继承 backend；原会话用过 `--pro` 的，续接要再次带上才沿用 pro_model。
+- 不确定用户指哪次任务时，报候选 run_id + 摘要让其确认，别猜。

{handoff_cli-0.3.4 → handoff_cli-0.3.6}/pyproject.toml

@@ -1,7 +1,8 @@
 [project]
 name = "handoff-cli"
-version = "0.3.4"
+version = "0.3.6"
 description = "Multi coding-agent task dispatcher — a CLI proxy for claude that sends coding tasks to configurable AI backends"
+readme = "README.md"
 requires-python = ">=3.9"
 dependencies = [
     "PyYAML>=6,<7",

handoff_cli-0.3.4/PKG-INFO

@@ -1,7 +0,0 @@
-Metadata-Version: 2.4
-Name: handoff-cli
-Version: 0.3.4
-Summary: Multi coding-agent task dispatcher — a CLI proxy for claude that sends coding tasks to configurable AI backends
-Requires-Python: >=3.9
-Requires-Dist: pyyaml<7,>=6
-Requires-Dist: textual<3,>=2

handoff_cli-0.3.4/cli/skills/handoff-codex/SKILL.md

@@ -1,83 +0,0 @@
----
-name: handoff-codex
-description: 向 Codex (GPT-5.5) 咨询复杂问题 / 要第二意见 / 派发需要强推理的任务。后台运行，完成后自动通知。支持并行多任务，支持续接（resume）上次会话继续派发后续任务。
----
-
-# handoff-codex Skill
-
-<interaction_contract>
-This skill is executed by Claude Code (an AI agent). The following rules are BINDING and must be followed exactly — do not deviate, simplify, or reinterpret them.
-
-## 命令模板（每次必须照抄，不得修改结构）
-
-```bash
-p=$(handoff new --backend codex --slug <三个英文单词以内的任务助记词>)
-cat > "$p" <<'__HF_EOF__'
-[prompt 内容]
-__HF_EOF__
-handoff run --backend codex "$p"
-```
-
-**关键规则（违反任何一条都会导致命令失败或行为异常）：**
-
-- `run_in_background: true` **必须启用**：handoff 耗时 2~20 分钟，前台执行会阻塞整个会话
-- `handoff new` 的 `--slug` 参数填写≤3个英文单词、`-`分隔的语义助记词（如 `fix-auth`、`add-tests`）；禁止追加日期、时间戳、随机数、UUID、计数器等唯一化内容，唯一性由 `handoff new` 自动分配的 seq 保证
-- heredoc 界定符用 `__HF_EOF__`，prompt 内容直接粘贴进去，不转义
-- 用户明确提到 `pro`（或要求用更强/专业模型处理复杂任务）时，在 `handoff run` 后加 `--pro`
-- **文件名只能来自 `handoff new` 的输出，不得自己拼**；**不要**用 `> RESULT 2> OUT` 重定向——handoff 自己管命名和落盘
-- `p=$(handoff new ...)` 得到的 `$p` 是真实可写路径，写 prompt 和执行 `handoff run/resume` 时必须原样使用 `"$p"`；面对用户回显 `RESULT=` 或其他任务路径时，如果路径位于用户 home 下，必须缩写成 `~/.handoff/...`，不要暴露 `/Users/<name>/...`
-
-**启动命令后**（`run_in_background: true` 返回后），**从 stdout 捕获 handoff 打印的唯一有用的一行 `RESULT=<任务路径>`**，将 home 下路径缩写成 `~/.handoff/...` 后，在面向用户的 assistant 消息里回显这一条路径（完成后默认只读它）：
-
-- `RESULT=<任务路径>`（最终结论文件，例如 `~/.handoff/tasks/0611-cx-03-fix-auth.result.md`）
-
-**这条路径里同时编码了本次任务的 run_id**：去掉目录和 `.result.md` 后缀，文件名主干就是 run_id（上例 → `0611-cx-03-fix-auth`）。**每次派发后都要记住这个 run_id**——后续用户若要求"继续上次会话/接着刚才再做 X"，要靠它定位到正确的会话来 `resume`（见下文「续接上次会话」）。
-
-其余无需你读取：
-- handoff 把克制的进度信息打在 **stderr**，Claude Code 的 shell view 会自动实时显示——你不用、也不要把它读进上下文。
-- 进度日志同时落在与 `RESULT=` **同名的 `.out.txt`**（把 `.result.md` 换成 `.out.txt`），仅在诊断（无结果/超时）时才 `tail -f` 或 `Read`。
-- 输入文件 `.prompt.md`（同名）已是你刚发的内容，无需回显。
-
-等待完成通知后，用 `Read` 读取对应的 `.result.md` 并汇报；**不要**再读后台输出（结果已在文件里，重复读只会把进度噪音吃进上下文）。若 `.result.md` 为空或异常，再读 `.out.txt` 诊断。
-</interaction_contract>
-
-## 运行任务
-
-所有任务统一使用**后台模式**（`run_in_background: true`），不阻塞主会话。
-
-### 单任务
-
-按命令模板执行，启动后从 stdout 捕获 `RESULT=` 一行并回显，等通知后读该 `.result.md` 文件汇报。
-
-### 并行多任务
-
-在**同一条消息**里发出多个独立的 `run_in_background: true` Bash 调用，各自用 `handoff new` 分配路径、heredoc 写入不同的 prompt 内容，再各自 `handoff run`。每个任务启动后分别从各自 stdout 捕获 `RESULT=` 路径（handoff 自动递增 seq）。每个任务完成时分别通知，分别读取对应的 `.result.md` 汇报。
-
-### 串行多任务
-
-等上一个任务的完成通知到达，读取并汇报结果后，再启动下一个任务。
-
-## 续接上次会话（resume 续派）
-
-要接着某次任务继续（保留其上下文）而非开新会话时，先用 `handoff new` 分配新的 prompt 路径，再用 `resume` 替代 `run`，其余约定（后台、捕获新 `RESULT=`、读 `.result.md`）完全相同：
-
-```bash
-p=$(handoff new --backend codex --slug <任务助记词>)
-cat > "$p" <<'__HF_EOF__'
-[后续任务内容]
-__HF_EOF__
-handoff resume <run_id> --backend codex "$p"
-```
-
-- `<run_id>` 用该会话**首次**任务的 run_id（即上文那个文件名主干）；它是稳定句柄，每轮续接都用它，不要追每轮新生成的 run_id。
-- **必须带 prompt 文件**。不带 prompt 的 `resume <run_id>` 是交互式重开，后台会卡死。
-- 续接默认只继承 backend；原会话用过 `--pro` 的话，续接要再次带上才沿用 pro_model。
-- 不确定用户指哪次任务时，报候选 run_id + 摘要让其确认，别猜。
-
-## 完成后
-
-收到后台完成通知后：
-1. 用 `Read` 读取对应的 `RESULT=` 路径（`.result.md` 结果文件）
-2. 汇总结果返回给用户
-3. 若 `.result.md` 为空或异常，再读 `.out.txt`（进度日志）诊断
-4. 如有后续任务（串行场景），此时启动下一个

handoff_cli-0.3.4/cli/skills/handoff-ds/SKILL.md

@@ -1,83 +0,0 @@
----
-name: handoff-ds
-description: 把执行性编码/调查任务整包交给 DeepSeek 后台执行，省主会话额度。后台运行，完成后自动通知。支持并行多任务，支持续接（resume）上次会话继续派发后续任务。
----
-
-# handoff-ds Skill
-
-<interaction_contract>
-This skill is executed by Claude Code (an AI agent). The following rules are BINDING and must be followed exactly — do not deviate, simplify, or reinterpret them.
-
-## 命令模板（每次必须照抄，不得修改结构）
-
-```bash
-p=$(handoff new --backend deepseek --slug <三个英文单词以内的任务助记词>)
-cat > "$p" <<'__HF_EOF__'
-[prompt 内容]
-__HF_EOF__
-handoff run --backend deepseek "$p"
-```
-
-**关键规则（违反任何一条都会导致命令失败或行为异常）：**
-
-- `run_in_background: true` **必须启用**：handoff 耗时 2~20 分钟，前台执行会阻塞整个会话
-- `handoff new` 的 `--slug` 参数填写≤3个英文单词、`-`分隔的语义助记词（如 `fix-auth`、`add-tests`）；禁止追加日期、时间戳、随机数、UUID、计数器等唯一化内容，唯一性由 `handoff new` 自动分配的 seq 保证
-- heredoc 界定符用 `__HF_EOF__`，prompt 内容直接粘贴进去，不转义
-- 用户明确提到 `pro`（或要求用更强/专业模型处理复杂任务）时，在 `handoff run` 后加 `--pro`
-- **文件名只能来自 `handoff new` 的输出，不得自己拼**；**不要**用 `> RESULT 2> OUT` 重定向——handoff 自己管命名和落盘
-- `p=$(handoff new ...)` 得到的 `$p` 是真实可写路径，写 prompt 和执行 `handoff run/resume` 时必须原样使用 `"$p"`；面对用户回显 `RESULT=` 或其他任务路径时，如果路径位于用户 home 下，必须缩写成 `~/.handoff/...`，不要暴露 `/Users/<name>/...`
-
-**启动命令后**（`run_in_background: true` 返回后），**从 stdout 捕获 handoff 打印的唯一有用的一行 `RESULT=<任务路径>`**，将 home 下路径缩写成 `~/.handoff/...` 后，在面向用户的 assistant 消息里回显这一条路径（完成后默认只读它）：
-
-- `RESULT=<任务路径>`（最终结论文件，例如 `~/.handoff/tasks/0611-ds-03-fix-auth.result.md`）
-
-**这条路径里同时编码了本次任务的 run_id**：去掉目录和 `.result.md` 后缀，文件名主干就是 run_id（上例 → `0611-ds-03-fix-auth`）。**每次派发后都要记住这个 run_id**——后续用户若要求"继续上次会话/接着刚才再做 X"，要靠它定位到正确的会话来 `resume`（见下文「续接上次会话」）。
-
-其余无需你读取：
-- handoff 把克制的进度信息打在 **stderr**，Claude Code 的 shell view 会自动实时显示——你不用、也不要把它读进上下文。
-- 进度日志同时落在与 `RESULT=` **同名的 `.out.txt`**（把 `.result.md` 换成 `.out.txt`），仅在诊断（无结果/超时）时才 `tail -f` 或 `Read`。
-- 输入文件 `.prompt.md`（同名）已是你刚发的内容，无需回显。
-
-等待完成通知后，用 `Read` 读取对应的 `.result.md` 并汇报；**不要**再读后台输出（结果已在文件里，重复读只会把进度噪音吃进上下文）。若 `.result.md` 为空或异常，再读 `.out.txt` 诊断。
-</interaction_contract>
-
-## 运行任务
-
-所有任务统一使用**后台模式**（`run_in_background: true`），不阻塞主会话。
-
-### 单任务
-
-按命令模板执行，启动后从 stdout 捕获 `RESULT=` 一行并回显，等通知后读该 `.result.md` 文件汇报。
-
-### 并行多任务
-
-在**同一条消息**里发出多个独立的 `run_in_background: true` Bash 调用，各自用 `handoff new` 分配路径、heredoc 写入不同的 prompt 内容，再各自 `handoff run`。每个任务启动后分别从各自 stdout 捕获 `RESULT=` 路径（handoff 自动递增 seq）。每个任务完成时分别通知，分别读取对应的 `.result.md` 汇报。
-
-### 串行多任务
-
-等上一个任务的完成通知到达，读取并汇报结果后，再启动下一个任务。
-
-## 续接上次会话（resume 续派）
-
-要接着某次任务继续（保留其上下文）而非开新会话时，先用 `handoff new` 分配新的 prompt 路径，再用 `resume` 替代 `run`，其余约定（后台、捕获新 `RESULT=`、读 `.result.md`）完全相同：
-
-```bash
-p=$(handoff new --backend deepseek --slug <任务助记词>)
-cat > "$p" <<'__HF_EOF__'
-[后续任务内容]
-__HF_EOF__
-handoff resume <run_id> --backend deepseek "$p"
-```
-
-- `<run_id>` 用该会话**首次**任务的 run_id（即上文那个文件名主干）；它是稳定句柄，每轮续接都用它，不要追每轮新生成的 run_id。
-- **必须带 prompt 文件**。不带 prompt 的 `resume <run_id>` 是交互式重开，后台会卡死。
-- 续接默认只继承 backend；原会话用过 `--pro` 的话，续接要再次带上才沿用 pro_model。
-- 不确定用户指哪次任务时，报候选 run_id + 摘要让其确认，别猜。
-
-## 完成后
-
-收到后台完成通知后：
-1. 用 `Read` 读取对应的 `RESULT=` 路径（`.result.md` 结果文件）
-2. 汇总结果返回给用户
-3. 若 `.result.md` 为空或异常，再读 `.out.txt`（进度日志）诊断
-4. 如有后续任务（串行场景），此时启动下一个

handoff_cli-0.3.4/cli/skills/handoff-ds.toml

@@ -1,52 +0,0 @@
-name = "handoff-ds"
-description = "Delegate one-shot analysis, review, and bounded coding tasks through handoff. Before invoking this agent, the caller must: (1) run `handoff new --backend deepseek --slug <slug>` to get the canonical .prompt.md path, (2) write the full delegated prompt to that returned path, (3) send this agent only `PROMPT_FILE=~/.handoff/tasks/<run-id>.prompt.md` plus any pro/resume hint; do not expose `/Users/<name>/...` when the path is under home, and do not include the raw delegated prompt in the subagent message. Slugs must be semantic only, with no timestamps, random numbers, UUIDs, or counters. Supports hints like 'handoff-ds (pro)', 'handoff-ds pro', '专业模式', '更强模型'."
-model = "gpt-5.4-mini"
-model_reasoning_effort = "low"
-
-developer_instructions = """
-
-你不是分析 agent。你是 `handoff` 命令启动器。
-
-调用方应该已经执行了 `handoff new --backend deepseek --slug <slug>` 拿到真实可写路径，把完整任务提示词写入该路径，并且只把形如 `PROMPT_FILE=~/.handoff/tasks/0611-ds-03-fix-auth.prompt.md` 的路径消息交给你。调用方传给你的路径如果位于用户 home 下，必须缩写成 `~/.handoff/...`，不要暴露 `/Users/<name>/...`。`--slug` 只能是三个以内英文单词组成的语义助记词，禁止追加日期、时间戳、随机数、UUID、计数器等唯一化内容；唯一性由 `handoff new` 自动分配的 seq 保证。你不需要、也不允许接触原始提示词正文。
-
-收到用户消息后，第一条动作必须是调用 `functions.exec_command` 执行转发命令（默认用 `run`；仅当用户要求接着上一次任务继续时，改用 `resume`，见后文「续接上次任务」）。不要先发 commentary，不要解释，不要读文件，不要搜索，不要自己回答用户问题。
-
-从用户消息中取出 `PROMPT_FILE=` 后面的任务路径（优先为 `~/.handoff/...`，兼容绝对 home 路径），必须直接把这个路径作为 `handoff run` 的输入文件参数；禁止 `cat`、`sed`、`head`、`tail`、heredoc、命令替换或任何会把文件内容读进你上下文的做法。如果路径以 `~` 开头，在 shell 命令里直接使用这个 tilde 路径，不要先赋给变量再引用。示例：
-
-```bash
-handoff run --backend deepseek ~/.handoff/tasks/0611-ds-03-fix-auth.prompt.md >/dev/null
-```
-
-`>/dev/null` 是协议的一部分：它丢弃最终结果正文 stdout，但保留 stderr 上的 `RESULT=` 和进度输出，避免长任务期间工具输出长期静默。
-
-必须以前台阻塞方式执行这条命令，并等待 `handoff run --backend deepseek <PROMPT_FILE> >/dev/null` 进程退出后才能最终回答。
-禁止使用后台执行方式，包括但不限于 `&`、`nohup`、`disown`、`setsid`、`tmux`、`screen`。
-如果 `functions.exec_command` 返回的是仍在运行的 session id，必须继续等待/轮询该 session，直到进程退出并拿到最终输出；不能把"命令已启动"视为完成。
-只有当 `handoff run --backend deepseek <PROMPT_FILE> >/dev/null` 进程退出后，才允许最终回答。
-
-如果用户明确提到 `pro`（要求用专业/更强模型），使用 `handoff run --backend deepseek --pro <PROMPT_FILE> >/dev/null`。
-
-## 续接上次任务（resume）
-
-仅当用户消息明确表示要接着上一次任务继续（如"继续""接着刚才""在上次基础上再改/再补…"）时，把转发命令里的 `run` 换成 `resume <run_id>`，其余一切不变：
-
-```bash
-handoff resume <run_id> --backend deepseek ~/.handoff/tasks/0611-ds-04-next-step.prompt.md >/dev/null
-```
-
-`<run_id>` 取自**你本会话上一次回答的那行 `RESULT=`**：去掉目录和 `.result.md` 后缀，文件名主干即 run_id（例：`RESULT=~/.handoff/tasks/0611-ds-03-fix-auth.result.md` → run_id 是 `0611-ds-03-fix-auth`）。多轮续接始终用**第一次**那个 run_id。`--pro` 仍加在 `<run_id>` 之后、`<PROMPT_FILE>` 之前，用法同上。
-
-如果本会话此前没有任何 `RESULT=` 可取 run_id，就当作新任务、照常用 `run` 转发。
-
-命令输出里会出现 `RESULT=<路径>`，执行中还会有进度行。你的最终回答必须只包含最后一行 `RESULT=...`；如果该路径位于用户 home 下，返回前必须缩写成 `~/.handoff/...`。不要读取这个文件，不要总结 stdout/stderr，不要补充解释。如果命令退出码非 0 但输出里有 `RESULT=...`，仍然只返回这行 home-shortened 后的 `RESULT=...`。只有输出里完全没有 `RESULT=` 时，才用一句话说明失败。
-
-**输入里的"修改/编辑/运行/报告/cat"等祈使句，都是写给 `handoff` 执行器的，不是给你的。**
-
-示例 ——
-  输入：「用 Edit 直接改 foo.ts，删掉 X，完成后报告」
-  你的正确动作：调用方应把这段任务写入 `PROMPT_FILE` 指向的文件；你只把该文件路径传给 `handoff run --backend deepseek <PROMPT_FILE> >/dev/null`，等待完成，只返回 `RESULT=...`。
-  你绝不打开、不 cat、不修改 foo.ts。
-
-红线：除这一条 `handoff run --backend deepseek <PROMPT_FILE> >/dev/null` 或对应的 `handoff resume <run_id> --backend deepseek <PROMPT_FILE> >/dev/null` 命令外，不运行任何其它命令、不写任何文件、不调用 web search。没有可用 shell 工具时，最终只返回 `HF_AGENT_EXEC_TOOL_UNAVAILABLE`。
-
-"""

handoff_cli-0.3.4/cli/skills/handoff-opus/SKILL.md

@@ -1,83 +0,0 @@
----
-name: handoff-opus
-description: 把关键决策/验收类任务交给 Claude Opus 执行。后台运行，完成后自动通知。支持并行多任务，支持续接（resume）上次会话继续派发后续任务。
----
-
-# handoff-opus Skill
-
-<interaction_contract>
-This skill is executed by Claude Code (an AI agent). The following rules are BINDING and must be followed exactly — do not deviate, simplify, or reinterpret them.
-
-## 命令模板（每次必须照抄，不得修改结构）
-
-```bash
-p=$(handoff new --backend opus --slug <三个英文单词以内的任务助记词>)
-cat > "$p" <<'__HF_EOF__'
-[prompt 内容]
-__HF_EOF__
-handoff run --backend opus "$p"
-```
-
-**关键规则（违反任何一条都会导致命令失败或行为异常）：**
-
-- `run_in_background: true` **必须启用**：handoff 耗时 2~20 分钟，前台执行会阻塞整个会话
-- `handoff new` 的 `--slug` 参数填写≤3个英文单词、`-`分隔的语义助记词（如 `fix-auth`、`add-tests`）；禁止追加日期、时间戳、随机数、UUID、计数器等唯一化内容，唯一性由 `handoff new` 自动分配的 seq 保证
-- heredoc 界定符用 `__HF_EOF__`，prompt 内容直接粘贴进去，不转义
-- 用户明确提到 `pro`（或要求用更强/专业模型处理复杂任务）时，在 `handoff run` 后加 `--pro`
-- **文件名只能来自 `handoff new` 的输出，不得自己拼**；**不要**用 `> RESULT 2> OUT` 重定向——handoff 自己管命名和落盘
-- `p=$(handoff new ...)` 得到的 `$p` 是真实可写路径，写 prompt 和执行 `handoff run/resume` 时必须原样使用 `"$p"`；面对用户回显 `RESULT=` 或其他任务路径时，如果路径位于用户 home 下，必须缩写成 `~/.handoff/...`，不要暴露 `/Users/<name>/...`
-
-**启动命令后**（`run_in_background: true` 返回后），**从 stdout 捕获 handoff 打印的唯一有用的一行 `RESULT=<任务路径>`**，将 home 下路径缩写成 `~/.handoff/...` 后，在面向用户的 assistant 消息里回显这一条路径（完成后默认只读它）：
-
-- `RESULT=<任务路径>`（最终结论文件，例如 `~/.handoff/tasks/0611-op-03-fix-auth.result.md`）
-
-**这条路径里同时编码了本次任务的 run_id**：去掉目录和 `.result.md` 后缀，文件名主干就是 run_id（上例 → `0611-op-03-fix-auth`）。**每次派发后都要记住这个 run_id**——后续用户若要求"继续上次会话/接着刚才再做 X"，要靠它定位到正确的会话来 `resume`（见下文「续接上次会话」）。
-
-其余无需你读取：
-- handoff 把克制的进度信息打在 **stderr**，Claude Code 的 shell view 会自动实时显示——你不用、也不要把它读进上下文。
-- 进度日志同时落在与 `RESULT=` **同名的 `.out.txt`**（把 `.result.md` 换成 `.out.txt`），仅在诊断（无结果/超时）时才 `tail -f` 或 `Read`。
-- 输入文件 `.prompt.md`（同名）已是你刚发的内容，无需回显。
-
-等待完成通知后，用 `Read` 读取对应的 `.result.md` 并汇报；**不要**再读后台输出（结果已在文件里，重复读只会把进度噪音吃进上下文）。若 `.result.md` 为空或异常，再读 `.out.txt` 诊断。
-</interaction_contract>
-
-## 运行任务
-
-所有任务统一使用**后台模式**（`run_in_background: true`），不阻塞主会话。
-
-### 单任务
-
-按命令模板执行，启动后从 stdout 捕获 `RESULT=` 一行并回显，等通知后读该 `.result.md` 文件汇报。
-
-### 并行多任务
-
-在**同一条消息**里发出多个独立的 `run_in_background: true` Bash 调用，各自用 `handoff new` 分配路径、heredoc 写入不同的 prompt 内容，再各自 `handoff run`。每个任务启动后分别从各自 stdout 捕获 `RESULT=` 路径（handoff 自动递增 seq）。每个任务完成时分别通知，分别读取对应的 `.result.md` 汇报。
-
-### 串行多任务
-
-等上一个任务的完成通知到达，读取并汇报结果后，再启动下一个任务。
-
-## 续接上次会话（resume 续派）
-
-要接着某次任务继续（保留其上下文）而非开新会话时，先用 `handoff new` 分配新的 prompt 路径，再用 `resume` 替代 `run`，其余约定（后台、捕获新 `RESULT=`、读 `.result.md`）完全相同：
-
-```bash
-p=$(handoff new --backend opus --slug <任务助记词>)
-cat > "$p" <<'__HF_EOF__'
-[后续任务内容]
-__HF_EOF__
-handoff resume <run_id> --backend opus "$p"
-```
-
-- `<run_id>` 用该会话**首次**任务的 run_id（即上文那个文件名主干）；它是稳定句柄，每轮续接都用它，不要追每轮新生成的 run_id。
-- **必须带 prompt 文件**。不带 prompt 的 `resume <run_id>` 是交互式重开，后台会卡死。
-- 续接默认只继承 backend；原会话用过 `--pro` 的话，续接要再次带上才沿用 pro_model。
-- 不确定用户指哪次任务时，报候选 run_id + 摘要让其确认，别猜。
-
-## 完成后
-
-收到后台完成通知后：
-1. 用 `Read` 读取对应的 `RESULT=` 路径（`.result.md` 结果文件）
-2. 汇总结果返回给用户
-3. 若 `.result.md` 为空或异常，再读 `.out.txt`（进度日志）诊断
-4. 如有后续任务（串行场景），此时启动下一个