Workspace

September 6, 2026 · View on GitHub

唯一事实来源是 docs/plan.md。本文定义磁盘布局。

Project 布局

每个 Project（DSH workspace 根目录）一个 workspace/ 交付树。本地 Docker 下按 Worker 白名单顶层目录逐目录 bind（.git/ 与 .dsh-pentester/ 物理上不在容器内）；远程 Docker 下是共享 named volume 的本地镜像，阶段边界才做 full sync。详见下文「规则」。

<project>/
└── workspace/                       # 交付树 = 容器 /workspace（仅当前 Target）
    ├── .dsh-pentester/              # Workspace 级注册表
    │   └── targets.json             # Target registry（schemaVersion 1）
    └── targets/
        └── <target-id>/             # 每个 Target 独立子树
            ├── .git/                # 宿主侧 git 仓库（全跟踪；不随 volume 同步）
            ├── .dsh-pentester/      # 宿主控制态（Worker 不可修改）
            │   ├── run.json         # 唯一机器状态：target/scope/RoE/language/stageAdvancePolicy(automatic|manual|custom+instruction；缺省 automatic)/status(active|stopped|completed)/currentStage/stageStatuses/delegations + id(UUID)/instanceId(7 hex)/revision(单调递增 mutation fence)/preEngagementCallId/restartedFrom（schemaVersion 3）
            │   ├── workspace.json   # 工作区元数据（id/target/language/created/gitBranch）
            │   └── events.jsonl     # append-only 事件日志
            ├── .gitignore           # tmp/ cache/ *.log
            ├── target/              # target.json scope.md roe.md inputs/
            ├── stages/
            │   ├── 01-pre-engagement/
            │   │   ├── summary.md   # 宿主在 advance 时写
            │   │   └── delegations/
            │   │       └── D-001/
            │   │           ├── input/           # task_prompt 快照（不可变）
            │   │           ├── work/            # 默认执行 cwd（过程文件）
            │   │           ├── artifacts/       # 给后续 Worker 的正式产出
            │   │           ├── evidence/        # 支撑结论的证明材料
            │   │           └── result.md        # 当前正式可交付结果（Worker 写/更新）
            │   ├── 02-intelligence-gathering/ …
            │   └── 07-reporting/ …
            ├── findings/            # 提升后的 findings.md / threat-model.md
            ├── report/              # report.md（最终交付）
            └── traffic/             # 流量记录（pcap/mitm；git 全跟踪）

规则：

Target 隔离：每个 Target 拥有独立的 .git/、.dsh-pentester/、run.json、文件系统树。Worker 只看到当前 Target 的 /workspace，看不到兄弟 Target。
Workspace 级：workspace/.dsh-pentester/targets.json 是唯一的跨 Target 共享文件，只记录 Target 注册信息（id、rootSessionId、dirName）。
每 Delegation 一个独立目录，ID 在 branch timeline 内跨 Stage 全局递增。
result.md 是 Delegation 的当前正式可交付结果：Worker 写/更新。
target/inputs/pre-engagement.md 记录七题确认的审计摘要（Target / Scope / RoE / Language / Stage Advance Policy —— policy 由 proof 派生，模型参数不可绕过）。
Trace 的 Agent 下方 Deliverable 节点读取各 delegation 的 result.md / evidence/ / artifacts/ 元数据（count + sample names，不读正文）与 canonical findings/、assets/（按 sourceDelegationId 聚合）； work/ scratch 不进入 Trace。
Worker 默认 cwd = 自己的 work/；只写自己的 delegation 目录，可读整个 /workspace/。
容器 /workspace：远程 Docker = 该 Target 的 named volume；本地 Docker = 按 Worker 白名单顶层目录（target/ assets/ findings/ stages/ report/ traffic/）逐目录 bind —— .git/ 与 .dsh-pentester/ 物理上不在容器内（不可读、不可写）。
同步（仅远程模式）：push 与 pull 都是 mirror 语义，且都排除 .git/ 与 .dsh-pentester/（集中 PathPolicy：pull 在任何写盘之前拒绝控制态条目，绝不被容器侧归档覆盖宿主 run.json）。pull 对普通文件做 temp+rename 原子发布；transport 全程不跟随 symlink；受资源上限约束（条目数 / 单文件 / 总量 / 路径长度）。
Git：每个 Target 独立 .git/。阶段完成时宿主做约定式 commit + tag。 rollback 只影响当前 Target，兄弟 Target 不受影响。
审计依赖 DSH session log、events.jsonl 与磁盘交付物。

不需要：STATUS.md、INDEX.*、manifest.json、logs/、Deliverable Registry、全局 assets.json。

Pentester Home 布局

插件自身的配置与运行时数据在 Pentester Home（DSH_PENTESTER_HOME > $DSH_HOME/dsh-pentester > ~/.dsh/dsh-pentester），与任何 project 交付树分离，不 mount 进容器：

~/.dsh/dsh-pentester/
├── settings.json            # Settings V4（dockerHost / stageAgents / stageAgentsDefaultsVersion / mcpServers）
├── agents/                  # Custom Agent Profiles（热更新）
├── skills/                  # Custom Skills —— 自己加 skill 就放这里
│   └── <name>.skill/
│       └── SKILL.md         # frontmatter name+description，正文即指令
├── agent-overrides/         # Builtin Agent 用户 Overlay（<id>.yml）
├── skill-packs/
│   └── 1.0.1/               # 已安装的 Builtin Skill Pack（Settings 初始化）
│       ├── .installation.json
│       └── skills/ …        # builtin 961 skills（只读）
└── runtime/
    └── skill-snapshots/     # 每 Delegation 的 frozen grant 快照（Host-only）
        └── <target>/<run>/<stage>-<D-xxx>/
            ├── manifest.json        # frozen grant（native provider 的 grant 来源）
            └── <name>.skill/ …      # bundle 副本（skill tool on-demand 读取）

加自定义 skill:在 skills/ 下建 <name>.skill/SKILL.md 即可（详见 skill-runtime-v4.md §4.1）。目录热更新，无需重启。

多 Target 语义

Project
  └── Shared Workspace
        ├── Target A
        │     ├── Root Session A
        │     └── PentestRun A
        ├── Target B
        │     ├── Root Session B
        │     └── PentestRun B
        └── Target C ...

同一 Target 再次发起 → 询问 [Continue] [Restart]
Continue：打开原有 Root Session，不创建新 Run
Restart：清除该 Target 旧数据，创建新 Run，当前 Session 成为新 controller
不同 Target：必须新建 Pentester Root Session