dsh-conductor 0.3.0__tar.gz

dsh_conductor-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dsh_conductor-0.3.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE README.md pyproject.toml
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include skills *.md *.py
+global-exclude __pycache__ *.py[cod]

dsh_conductor-0.3.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: dsh-conductor
+Version: 0.3.0
+Summary: DSH-managed coding-agent delegation with independent verification
+Author-email: Yu <66neko@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/66neko/dsh-conductor
+Project-URL: Repository, https://github.com/66neko/dsh-conductor
+Project-URL: Issues, https://github.com/66neko/dsh-conductor/issues
+Keywords: dsh,deepseek,tmux,claude-code,codex,orchestration,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# dsh-conductor
+
+`dsh-conductor` 是一个零第三方依赖的 Python 3.13 SDK。它把一段自然语言 prompt 交给工作环境中的 DSH：DSH 负责拆解任务、根据 prompt 选择 Claude Code 或 Codex、通过 tmux 监督执行、独立验证产物，并返回结构化验收结果。
+
+DSH 由运行环境提供，本项目不会安装或调用模型 API。Claude Code 与 Codex 分别由 `tmux-claude-code` 和 `tmux-codex` 两个独立 skill 驱动。
+
+## SDK 使用
+
+```python
+from pathlib import Path
+
+from conductor import Conductor, ConductorConfig
+
+client = Conductor(
+    workspace=Path("/path/to/project"),
+    config=ConductorConfig(
+        # dsh_bin=None 时从 DSH_BIN 或 PATH 查找。
+        dsh_bin=None,
+        max_attempts=2,
+    ),
+)
+
+result = client.run(
+    """
+    请使用 Codex 完成以下任务：创建 hello.txt，内容为 Hello Conductor 加一个换行。
+
+    验收标准：hello.txt 必须存在，且 bytes 恰好等于 b'Hello Conductor\\n'。
+    """,
+    on_event=lambda event: print(event.format()),
+)
+
+print(result.accepted)
+print(result.plan.task_summary)
+print(result.verdict.summary)
+```
+
+`run()` 的第一个参数是唯一业务输入。prompt 中可以明确写“使用 Claude Code”或“使用 Codex”；没有明确指定时，DSH 根据任务与当前环境选择。调用方不再传 `agent`、`task` 或 `verify` 参数。
+
+`on_event` 会在运行中接收 `RunEvent`，事件来源包括 `dsh`、`claude`、`codex` 和 `conductor`。事件只用于显示进度，完成事实仍由 DSH 协议、worker receipt 和最终 verdict 文件决定。`TaskResult` 包含：
+
+- `plan`：DSH 生成的 agent、任务摘要、步骤和带 ID 的验收项；
+- `verdict`：DSH 独立检查后的 `accepted`/`rejected`、每项证据、产物和剩余问题；
+- `state_directory`：本轮 request、plan、task、receipt、verdict 与 `worker-screen.log`；
+- `dsh`：协议状态、耗时、事件数量和 DSH 最后文本。
+
+被 DSH 拒绝是正常业务结果，`result.accepted` 为 `False`；DSH 启动失败、协议失败或结果文件不合法时抛出 `ConductorError`。
+
+完整字段、嵌套对象、错误结果和实时事件格式见 [`docs/result-json.md`](docs/result-json.md)。可运行示例见 [`examples/quickstart.py`](examples/quickstart.py)。
+
+## CLI
+
+CLI 是 SDK 的薄封装，保留给脚本和人工调用：
+
+```bash
+python3.13 -m conductor install-skills --workspace /path/to/project
+python3.13 -m conductor doctor
+python3.13 -m conductor run \
+  --workspace /path/to/project \
+  --prompt '请使用 Claude Code 创建 hello.txt。验收标准：文件存在且内容为 Hello。'
+```
+
+`run` 的 stdout 始终只有一个 JSON 对象；实时事件由 CLI 写入 stderr，因此可以安全地重定向 stdout。每次运行启动 DSH 前，SDK 都会把包内两个 skill 直接覆盖到 `<workspace>/.dsh/skills/`，供 DSH 项目级发现；不会写入 `~/.dsh/skills`，任务结束后也不会删除。`install-skills --workspace` 可提前执行同样的复制操作。`show` 可读取最近一次运行的 request、用户 prompt、manager prompt、plan、verdict 和日志路径。
+
+`.dsh/skills/` 是 SDK 生成的运行目录，建议加入项目的 Git 忽略规则。
+
+## 日志与状态
+
+conductor 会同时轮询两个候选 tmux 会话；DSH 选择哪个 agent 后，只有实际存在的会话产生屏幕日志。默认每 5 秒采样一次，SDK 可通过 `ConductorConfig(worker_log_interval_seconds=...)` 调整，CLI 可通过 `--worker-log-interval-seconds` 调整。变化会通过 `RunEvent(source="claude"/"codex", kind="worker_output")` 回调，并追加到 `worker-screen.log`。屏幕文字不会被当作完成或验收信号。
+
+状态目录默认是 `$XDG_STATE_HOME/dsh-conductor`，未设置时为 `~/.local/state/dsh-conductor`：
+
+```text
+runs/<run-id>/
+├── request.json
+├── user-prompt.md
+├── manager-prompt.md
+├── plan.json
+├── verdict.json
+├── worker-screen.log
+└── attempts/
+    ├── claude/1/{task.md,receipt.json}
+    └── codex/1/{task.md,receipt.json}
+```
+
+每轮运行使用新的 run id 和 receipt token，避免读取旧结论。accepted verdict 必须同时满足 DSH `turn/end` + `session.status=idle`、所有验收项通过、产物路径安全且选定 agent 的最终 receipt 有效。
+
+## 开发验证
+
+```bash
+python3.13 -m compileall -q conductor skills tests
+python3.13 -m unittest discover -v
+python3.13 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/tmux-claude-code
+python3.13 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/tmux-codex
+```
+
+## 发布
+
+推送 GitHub Release 后，`.github/workflows/publish.yml` 会先在独立 job 中运行测试并构建
+发行包，再用 PyPI Trusted Publishing 上传已验证的 wheel 与 sdist。首次发布前，需要在
+PyPI 为 GitHub Actions 配置 Trusted Publisher，并在 GitHub 创建 `pypi` 环境。完整字段、
+版本标签规则和发布步骤见 [`docs/pypi-publishing.md`](docs/pypi-publishing.md)。

dsh_conductor-0.3.0/README.md

@@ -0,0 +1,101 @@
+# dsh-conductor
+
+`dsh-conductor` 是一个零第三方依赖的 Python 3.13 SDK。它把一段自然语言 prompt 交给工作环境中的 DSH：DSH 负责拆解任务、根据 prompt 选择 Claude Code 或 Codex、通过 tmux 监督执行、独立验证产物，并返回结构化验收结果。
+
+DSH 由运行环境提供，本项目不会安装或调用模型 API。Claude Code 与 Codex 分别由 `tmux-claude-code` 和 `tmux-codex` 两个独立 skill 驱动。
+
+## SDK 使用
+
+```python
+from pathlib import Path
+
+from conductor import Conductor, ConductorConfig
+
+client = Conductor(
+    workspace=Path("/path/to/project"),
+    config=ConductorConfig(
+        # dsh_bin=None 时从 DSH_BIN 或 PATH 查找。
+        dsh_bin=None,
+        max_attempts=2,
+    ),
+)
+
+result = client.run(
+    """
+    请使用 Codex 完成以下任务：创建 hello.txt，内容为 Hello Conductor 加一个换行。
+
+    验收标准：hello.txt 必须存在，且 bytes 恰好等于 b'Hello Conductor\\n'。
+    """,
+    on_event=lambda event: print(event.format()),
+)
+
+print(result.accepted)
+print(result.plan.task_summary)
+print(result.verdict.summary)
+```
+
+`run()` 的第一个参数是唯一业务输入。prompt 中可以明确写“使用 Claude Code”或“使用 Codex”；没有明确指定时，DSH 根据任务与当前环境选择。调用方不再传 `agent`、`task` 或 `verify` 参数。
+
+`on_event` 会在运行中接收 `RunEvent`，事件来源包括 `dsh`、`claude`、`codex` 和 `conductor`。事件只用于显示进度，完成事实仍由 DSH 协议、worker receipt 和最终 verdict 文件决定。`TaskResult` 包含：
+
+- `plan`：DSH 生成的 agent、任务摘要、步骤和带 ID 的验收项；
+- `verdict`：DSH 独立检查后的 `accepted`/`rejected`、每项证据、产物和剩余问题；
+- `state_directory`：本轮 request、plan、task、receipt、verdict 与 `worker-screen.log`；
+- `dsh`：协议状态、耗时、事件数量和 DSH 最后文本。
+
+被 DSH 拒绝是正常业务结果，`result.accepted` 为 `False`；DSH 启动失败、协议失败或结果文件不合法时抛出 `ConductorError`。
+
+完整字段、嵌套对象、错误结果和实时事件格式见 [`docs/result-json.md`](docs/result-json.md)。可运行示例见 [`examples/quickstart.py`](examples/quickstart.py)。
+
+## CLI
+
+CLI 是 SDK 的薄封装，保留给脚本和人工调用：
+
+```bash
+python3.13 -m conductor install-skills --workspace /path/to/project
+python3.13 -m conductor doctor
+python3.13 -m conductor run \
+  --workspace /path/to/project \
+  --prompt '请使用 Claude Code 创建 hello.txt。验收标准：文件存在且内容为 Hello。'
+```
+
+`run` 的 stdout 始终只有一个 JSON 对象；实时事件由 CLI 写入 stderr，因此可以安全地重定向 stdout。每次运行启动 DSH 前，SDK 都会把包内两个 skill 直接覆盖到 `<workspace>/.dsh/skills/`，供 DSH 项目级发现；不会写入 `~/.dsh/skills`，任务结束后也不会删除。`install-skills --workspace` 可提前执行同样的复制操作。`show` 可读取最近一次运行的 request、用户 prompt、manager prompt、plan、verdict 和日志路径。
+
+`.dsh/skills/` 是 SDK 生成的运行目录，建议加入项目的 Git 忽略规则。
+
+## 日志与状态
+
+conductor 会同时轮询两个候选 tmux 会话；DSH 选择哪个 agent 后，只有实际存在的会话产生屏幕日志。默认每 5 秒采样一次，SDK 可通过 `ConductorConfig(worker_log_interval_seconds=...)` 调整，CLI 可通过 `--worker-log-interval-seconds` 调整。变化会通过 `RunEvent(source="claude"/"codex", kind="worker_output")` 回调，并追加到 `worker-screen.log`。屏幕文字不会被当作完成或验收信号。
+
+状态目录默认是 `$XDG_STATE_HOME/dsh-conductor`，未设置时为 `~/.local/state/dsh-conductor`：
+
+```text
+runs/<run-id>/
+├── request.json
+├── user-prompt.md
+├── manager-prompt.md
+├── plan.json
+├── verdict.json
+├── worker-screen.log
+└── attempts/
+    ├── claude/1/{task.md,receipt.json}
+    └── codex/1/{task.md,receipt.json}
+```
+
+每轮运行使用新的 run id 和 receipt token，避免读取旧结论。accepted verdict 必须同时满足 DSH `turn/end` + `session.status=idle`、所有验收项通过、产物路径安全且选定 agent 的最终 receipt 有效。
+
+## 开发验证
+
+```bash
+python3.13 -m compileall -q conductor skills tests
+python3.13 -m unittest discover -v
+python3.13 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/tmux-claude-code
+python3.13 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/tmux-codex
+```
+
+## 发布
+
+推送 GitHub Release 后，`.github/workflows/publish.yml` 会先在独立 job 中运行测试并构建
+发行包，再用 PyPI Trusted Publishing 上传已验证的 wheel 与 sdist。首次发布前，需要在
+PyPI 为 GitHub Actions 配置 Trusted Publisher，并在 GitHub 创建 `pypi` 环境。完整字段、
+版本标签规则和发布步骤见 [`docs/pypi-publishing.md`](docs/pypi-publishing.md)。

dsh_conductor-0.3.0/conductor/__init__.py

@@ -0,0 +1,24 @@
+"""由 DSH 管理运行在 tmux 中的编码 agent。"""
+
+from .dsh import DshClient, DshConfig, DshError, RunResult
+from .models import AgentKind, ExecutionPlan, Verdict
+from .progress import RunEvent
+from .sdk import Conductor, ConductorConfig, ConductorError, TaskResult
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "AgentKind",
+    "Conductor",
+    "ConductorConfig",
+    "ConductorError",
+    "DshClient",
+    "DshConfig",
+    "DshError",
+    "RunResult",
+    "RunEvent",
+    "TaskResult",
+    "ExecutionPlan",
+    "Verdict",
+    "__version__",
+]

dsh_conductor-0.3.0/conductor/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

dsh_conductor-0.3.0/conductor/agents/__init__.py

@@ -0,0 +1 @@
+"""不同 agent 各自独立的 tmux 协议。"""

dsh_conductor-0.3.0/conductor/agents/base.py

@@ -0,0 +1,355 @@
+"""共享控制器机制；所有 TUI 差异由具体 adapter 负责。"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shlex
+import shutil
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Pattern, Sequence
+
+from ..models import RecordError, WorkerReceipt
+from ..state import atomic_write_json
+from ..tmux import TmuxError, TmuxSession
+
+
+class WorkerError(RuntimeError):
+    """worker 会话未能到达可验证的交接点。"""
+
+
+@dataclass(frozen=True, slots=True)
+class AgentAdapter:
+    kind: str
+    executable: str
+    arguments: tuple[str, ...]
+    cursor_glyphs: tuple[str, ...]
+    menu_hint: Pattern[str]
+    affirmative: Pattern[str]
+    ready: Pattern[str]
+    pending_submission: Pattern[str] | None = None
+
+    def resolve_command(self, explicit_binary: str | None = None) -> list[str]:
+        raw = explicit_binary or shutil.which(self.executable)
+        if not raw:
+            raise WorkerError(f"cannot find {self.executable} on PATH; pass --binary")
+        binary = Path(raw).expanduser().resolve()
+        if not binary.is_file():
+            raise WorkerError(f"agent executable does not exist: {binary}")
+        return [str(binary), *self.arguments]
+
+    def cursor_label(self, screen: str) -> str | None:
+        for line in screen.splitlines():
+            for glyph in self.cursor_glyphs:
+                if glyph in line:
+                    label = line.split(glyph, 1)[1].strip()
+                    return re.sub(r"^\d+[.)]\s*", "", label)
+        return None
+
+    def is_menu(self, screen: str) -> bool:
+        return bool(self.menu_hint.search(screen))
+
+    def is_ready(self, screen: str) -> bool:
+        return not self.is_menu(screen) and bool(self.ready.search(screen))
+
+    def has_pending_submission(self, screen: str) -> bool:
+        return self.pending_submission is not None and bool(self.pending_submission.search(screen))
+
+
+def _emit(value: object) -> None:
+    json.dump(value, sys.stdout, ensure_ascii=False)
+    sys.stdout.write("\n")
+    sys.stdout.flush()
+
+
+def _submission_prompt(*, task_file: Path, script: Path, receipt: Path, token: str) -> str:
+    # TUI 只接收短指令；任务正文留在文件中，避免长粘贴在交互式编辑器中被截断。
+    command = (
+        f"python3.13 {shlex.quote(str(script))} complete "
+        f"--receipt {shlex.quote(str(receipt))} --token {shlex.quote(token)} "
+        "--status ready_for_verification --summary '简短事实总结'"
+    )
+    blocked = command.replace("ready_for_verification", "blocked")
+    return f"""
+<dsh_conductor_handoff>
+请完整读取任务文件 `{task_file}`，自主完成其中的任务和自检。该文件不是验收结论。
+全部编辑与检查结束后，最后一个工具操作必须运行下列命令，并把 summary 占位文字改为简短事实总结：
+
+{command}
+
+如果外部阻塞导致无法完成，改用下列命令，并在 summary 中说明阻塞原因：
+
+{blocked}
+
+写入回执后不要继续工作。回执只表示可以交给 DSH 独立验收，不表示任务已经通过验收。
+</dsh_conductor_handoff>
+""".strip()
+
+
+def wait_until_ready(
+    session: TmuxSession,
+    adapter: AgentAdapter,
+    *,
+    timeout_seconds: float,
+    ready_settle_seconds: float = 2.0,
+) -> None:
+    deadline = time.monotonic() + timeout_seconds
+    menu_steps = 0
+    ready_since: float | None = None
+    while time.monotonic() < deadline:
+        screen = session.capture()
+        status = session.status()
+        if status.pane_dead:
+            raise WorkerError(f"{adapter.kind} exited during startup\n{screen[-2000:]}")
+        if adapter.is_menu(screen):
+            ready_since = None
+            label = adapter.cursor_label(screen)
+            if label and adapter.affirmative.search(label):
+                session.send_keys("Enter")
+                time.sleep(1.0)
+                menu_steps = 0
+                continue
+            if menu_steps >= 8:
+                raise WorkerError(f"cannot find an affirmative startup option\n{screen[-2000:]}")
+            menu_steps += 1
+            session.send_keys("Down")
+            # Claude Code 异步重绘菜单；过早读屏会看到旧光标并误判为没有移动。
+            time.sleep(0.75)
+            continue
+        if adapter.is_ready(screen):
+            # 启动界面可能先显示输入框，随后才弹出目录信任菜单；稳定后再粘贴任务。
+            if ready_since is None:
+                ready_since = time.monotonic()
+            elif time.monotonic() - ready_since >= ready_settle_seconds:
+                return
+        else:
+            ready_since = None
+        time.sleep(0.5)
+    raise WorkerError(f"{adapter.kind} did not become ready\n{session.capture()[-2000:]}")
+
+
+def wait_for_receipt(
+    session: TmuxSession,
+    *,
+    adapter: AgentAdapter,
+    receipt_file: Path,
+    token: str,
+    timeout_seconds: float,
+    submission: str,
+) -> tuple[WorkerReceipt, float]:
+    started = time.monotonic()
+    deadline = started + timeout_seconds
+    last_error: str | None = None
+    menu_steps = 0
+    resubmit_after_menu = False
+    last_submit = time.monotonic()
+    while time.monotonic() < deadline:
+        if receipt_file.exists():
+            try:
+                receipt = WorkerReceipt.load(receipt_file, expected_token=token)
+                return receipt, time.monotonic() - started
+            except RecordError as exc:
+                last_error = str(exc)
+        screen = session.capture()
+        if adapter.is_menu(screen):
+            label = adapter.cursor_label(screen)
+            if label and adapter.affirmative.search(label):
+                session.send_keys("Enter")
+                menu_steps = 0
+                resubmit_after_menu = True
+                time.sleep(1.0)
+                continue
+            if menu_steps >= 8:
+                raise WorkerError(f"cannot handle worker menu while waiting for receipt\n{screen[-2000:]}")
+            session.send_keys("Down")
+            menu_steps += 1
+            time.sleep(0.75)
+            continue
+        if resubmit_after_menu and adapter.is_ready(screen):
+            # 菜单可能截断首次粘贴；清空残留输入后完整重投，不能只补发 Enter。
+            session.send_keys("C-c")
+            time.sleep(0.25)
+            session.send_text(submission)
+            resubmit_after_menu = False
+            last_submit = time.monotonic()
+            time.sleep(0.5)
+            continue
+        if adapter.has_pending_submission(screen) and time.monotonic() - last_submit >= 2.0:
+            # Codex 可能在 Enter 到达后才完成 bracketed paste。仅当编辑器仍显示
+            # pending-paste 标记时节流重发，避免无依据地重复提交任务。
+            session.send_keys("Enter")
+            last_submit = time.monotonic()
+            time.sleep(0.5)
+            continue
+        if session.status().pane_dead:
+            raise WorkerError(f"worker process exited before writing its receipt\n{screen[-2000:]}")
+        time.sleep(0.5)
+    detail = f"; last receipt error: {last_error}" if last_error else ""
+    raise WorkerError(f"timed out waiting for worker receipt {receipt_file}{detail}")
+
+
+def submit(
+    *,
+    session: TmuxSession,
+    adapter: AgentAdapter,
+    task_file: Path,
+    receipt_file: Path,
+    token: str,
+    script: Path,
+    timeout_seconds: float,
+) -> dict[str, object]:
+    if receipt_file.exists():
+        raise WorkerError(f"refusing stale receipt path: {receipt_file}")
+    try:
+        task = task_file.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise WorkerError(f"cannot read task file {task_file}: {exc}") from exc
+    if not task.strip():
+        raise WorkerError(f"task file is empty: {task_file}")
+    receipt_file.parent.mkdir(parents=True, exist_ok=True)
+    prompt = _submission_prompt(
+        task_file=task_file.resolve(),
+        script=script,
+        receipt=receipt_file.resolve(),
+        token=token,
+    )
+    session.send_text(prompt)
+    # 长文本粘贴可能在首个 Enter 后才完成展开；菜单由后续分支处理，其余状态只补交一次。
+    time.sleep(2.0)
+    if not receipt_file.exists() and not adapter.is_menu(session.capture()):
+        session.send_keys("Enter")
+    receipt, elapsed = wait_for_receipt(
+        session,
+        adapter=adapter,
+        receipt_file=receipt_file,
+        token=token,
+        timeout_seconds=timeout_seconds,
+        submission=prompt,
+    )
+    return {
+        "schema_version": 1,
+        "session": session.name,
+        "agent": adapter.kind,
+        "status": receipt.status,
+        "summary": receipt.summary,
+        "receipt_file": str(receipt_file.resolve()),
+        "elapsed_seconds": round(elapsed, 3),
+        "attach_command": f"tmux attach -t {session.name}",
+    }
+
+
+def build_parser(adapter: AgentAdapter) -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=f"{adapter.kind}_session.py",
+        description=f"Control one {adapter.kind} interactive session through tmux.",
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    run = commands.add_parser("run", help="start a session, submit a task, and wait for its receipt")
+    run.add_argument("--workspace", type=Path, required=True)
+    run.add_argument("--session", required=True)
+    run.add_argument("--task-file", type=Path, required=True)
+    run.add_argument("--receipt", type=Path, required=True)
+    run.add_argument("--token", required=True)
+    run.add_argument("--binary")
+    run.add_argument("--startup-timeout-seconds", type=float, default=120.0)
+    run.add_argument("--timeout-seconds", type=float, default=1200.0)
+
+    send = commands.add_parser("send", help="submit a follow-up to the same session")
+    send.add_argument("--session", required=True)
+    send.add_argument("--task-file", type=Path, required=True)
+    send.add_argument("--receipt", type=Path, required=True)
+    send.add_argument("--token", required=True)
+    send.add_argument("--timeout-seconds", type=float, default=1200.0)
+
+    for name in ("status", "capture", "close"):
+        command = commands.add_parser(name)
+        command.add_argument("--session", required=True)
+    capture = commands.choices["capture"]
+    capture.add_argument("--history-lines", type=int, default=0)
+
+    complete = commands.add_parser("complete", help="atomically write a worker receipt")
+    complete.add_argument("--receipt", type=Path, required=True)
+    complete.add_argument("--token", required=True)
+    complete.add_argument(
+        "--status",
+        choices=("ready_for_verification", "blocked"),
+        required=True,
+    )
+    complete.add_argument("--summary", required=True)
+    return parser
+
+
+def main(adapter: AgentAdapter, argv: Sequence[str] | None = None) -> int:
+    parser = build_parser(adapter)
+    args = parser.parse_args(argv)
+    script = Path(sys.argv[0]).resolve()
+    try:
+        if args.command == "complete":
+            if args.receipt.exists():
+                raise WorkerError(f"receipt already exists: {args.receipt}")
+            atomic_write_json(
+                args.receipt.resolve(),
+                WorkerReceipt(args.token, args.status, args.summary).to_json(),
+            )
+            _emit({"schema_version": 1, "status": "receipt_written", "receipt": str(args.receipt)})
+            return 0
+        if args.command == "run":
+            session = TmuxSession.create(
+                name=args.session,
+                workspace=args.workspace,
+                agent=adapter.kind,
+                command=adapter.resolve_command(args.binary),
+            )
+            try:
+                wait_until_ready(session, adapter, timeout_seconds=args.startup_timeout_seconds)
+                _emit(
+                    submit(
+                        session=session,
+                        adapter=adapter,
+                        task_file=args.task_file,
+                        receipt_file=args.receipt,
+                        token=args.token,
+                        script=script,
+                        timeout_seconds=args.timeout_seconds,
+                    )
+                )
+                return 0
+            except Exception:
+                # 失败会话保留给 DSH 或调用方排查，不能在异常路径中销毁现场。
+                raise
+        session = TmuxSession.attach(name=args.session, expected_agent=adapter.kind)
+        if args.command == "send":
+            _emit(
+                submit(
+                    session=session,
+                    adapter=adapter,
+                    task_file=args.task_file,
+                    receipt_file=args.receipt,
+                    token=args.token,
+                    script=script,
+                    timeout_seconds=args.timeout_seconds,
+                )
+            )
+        elif args.command == "status":
+            _emit({"schema_version": 1, **session.status().to_json()})
+        elif args.command == "capture":
+            _emit(
+                {
+                    "schema_version": 1,
+                    **session.status().to_json(),
+                    "screen": session.capture(history_lines=args.history_lines),
+                }
+            )
+        elif args.command == "close":
+            session.close()
+            _emit({"schema_version": 1, "status": "closed", "session": args.session})
+        return 0
+    except (WorkerError, TmuxError, RecordError, OSError) as exc:
+        print(f"{adapter.kind}_session: {exc}", file=sys.stderr)
+        return 1

dsh_conductor-0.3.0/conductor/agents/claude.py

@@ -0,0 +1,23 @@
+"""Claude Code 的 tmux 启动与就绪协议。"""
+
+from __future__ import annotations
+
+import re
+
+from .base import AgentAdapter, main as adapter_main
+
+
+# 菜单与就绪表达式只描述 Claude Code，不能与 Codex 的界面规则混用。
+CLAUDE = AgentAdapter(
+    kind="claude",
+    executable="claude",
+    arguments=("--dangerously-skip-permissions",),
+    cursor_glyphs=("❯",),
+    menu_hint=re.compile(r"Enter to confirm|Esc to cancel|to navigate|to select", re.IGNORECASE),
+    affirmative=re.compile(r"^(yes|trust|accept|continue|allow|approve)\b", re.IGNORECASE),
+    ready=re.compile(r"❯|bypass permissions on", re.IGNORECASE),
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    return adapter_main(CLAUDE, argv)