工程可用性评估与实操指南：现在能用吗？应该怎么用？

运行环境与账号硬性前置条件清单

工程成熟度与直接上生产的注意事项

方式 A：极具特色的“Agent 引导式安装（Agent-Assisted Setup）”

因为配置涉及多个 CLI 包装脚本、DSH Profile 隔离、Management API 调用以及策略初始化，作者将“注意力最小化”哲学直接用在了安装流程上——编写了一份专门给 Coding Agent 阅读的 SETUP.md。你只需在当前仓库目录下对你的 AI 编程助手（如 DSH、Claude Code 或 Antigravity）发送一句话：

你的 Coding Agent 会严格遵循 SETUP.md 的契约执行以下 5 步：

1. 静默环境探测（Probe）：自动在后台运行一行探测脚本检查 node, pnpm, git, tmux, python3, gh, dsh 版本及当前 GitHub 登录名，已满足的项绝不多问。
2. 单步极简提问（最多 9 题）：每次只问 1 个问题（每条消息控制在 300 词以内，并附带推荐默认值，你只需回复一个词即可确认），依次收集：监听源（仅 GitHub 还是含飞书）、目标仓库 owner/name、Agent 专用账号名、允许派单的白名单成员、本地基准克隆路径、Commit 署名作者、是否开启自动合并。
3. 生成完整计划并等待一次确认：在真正动手前，汇总展示所有将创建的脚本、配置与默认值。
4. 分离敏感操作与自动执行：绝不在聊天框索要密码或 Secret！需要人工扫码或输入 Token 的步骤会生成精确的终端命令让你在自己的终端执行；其余包装器创建、编译、服务启动与 HTTP API 配置保存全部由 Agent 自动完成。
5. 自检与移交：确认 scripts/dsh-superagent status 返回退出码 0，配置每小时自愈巡检任务，并输出面板 URL 与第一条测试指令。

方式 B：五步手工标准部署流程（深入理解底层配置）

如果你希望完全掌控每一个工程细节，可以按照 docs/006-deployment.md 执行以下五个标准步骤：

Step 1：创建隔离的 CLI 账号包装器（Account Wrappers）

为了保证 Agent 只使用它自己的专用凭证，而不触碰你个人的 ~/.config/gh，需在 ~/.local/bin/ 下创建独立的包装脚本：

# 1. 配置 Agent 专用 GitHub CLI 包装器 (gh-agent)
mkdir -p ~/.local/bin
cat > ~/.local/bin/gh-agent <<'EOF'
#!/bin/sh
GH_CONFIG_DIR="$HOME/.config/gh-agent" exec gh "$@"
EOF
chmod +x ~/.local/bin/gh-agent

# 使用 Agent 的专用 GitHub 账号登录并验证
gh-agent auth login
gh-agent api user --jq .login

# 2. (可选) 若启用飞书，配置纯 Bot 模式的 lark-bot 包装器
LARKSUITE_CLI_CONFIG_DIR="$HOME/.lark-cli-dsh-superagent" lark-cli config init --app-id <cli_xxx> --app-secret-stdin
LARKSUITE_CLI_CONFIG_DIR="$HOME/.lark-cli-dsh-superagent" lark-cli config strict-mode bot --global
cat > ~/.local/bin/lark-bot <<'EOF'
#!/bin/sh
export LARKSUITE_CLI_CONFIG_DIR="$HOME/.lark-cli-dsh-superagent"
exec lark-cli "$@"
EOF
chmod +x ~/.local/bin/lark-bot

Step 2：安装 DSH、编译仓库并创建独立的 superagent Profile

切记：必须将 dsh-superagent 安装在独立的 Profile（如 superagent）中，与你日常交互使用的默认 Profile 分开，因为该插件会改写进程级的 PATH（注入 worker-bin）与全局 Git 配置（注入 worker-gitconfig）：

# 1. 安装指定版本的 DeepSeek Harness
npm install -g @deepseek-ai/dsh@0.2.1-rc.3

# 2. 在当前仓库安装依赖并执行类型检查、测试与构建
pnpm install && pnpm build

# 3. 从 Web 模板初始化名为 superagent 的独立 Profile (仅首次安装执行!)
dsh superagent --from-default-profile web --dump-config > /dev/null

# 4. 将当前仓库作为插件链接到 superagent Profile
dsh plugin --profile superagent add "link:$PWD"

Step 3：编写机器级配置 cordis.patch.yml 并启动守护进程

参考 examples/profile.cordis.patch.yml，编辑 ~/.dsh/profiles/superagent/cordis.patch.yml：

- id: webserver
  config:
    host: 127.0.0.1
    port: 3082
- id: dsh-superagent
  config:
    stateDir: /Users/yourname/.dsh/state/superagent
# 若需启用飞书源，取消以下两行注释：
# - id: dsh-superagent-feishu
#   disabled: false

随后使用内置的生命周期脚本启动服务：

scripts/dsh-superagent start
scripts/dsh-superagent status

Step 4：通过 Web 面板或 Management HTTP API 完成四大模块初始化

打开浏览器访问 http://127.0.0.1:3082，点击左侧边栏的 Superagent 进入管理面板（或直接通过带有 x-orchestrator-request: 1 请求头的本地 API 配置）：

# 示例：通过 Management API 配置 GitHub Source、Policy 白名单与 Git Worktree Prepare 命令
api=http://127.0.0.1:3082/orchestrator/api

# 1. 设置 GitHub 监听仓库与专属 CLI
rev=$(curl -s -H 'x-orchestrator-request: 1' $api/settings | jq '.sources[] | select(.id == "github") | .revision')
curl -s -X PUT -H 'x-orchestrator-request: 1' -H 'content-type: application/json' $api/settings/source:github \
  -d "{\"value\": {\"enabled\": true, \"config\": {\"repository\": \"owner/repo\", \"cli\": \"$HOME/.local/bin/gh-agent\"}}, \"revision\": $rev}"

# 2. 配置 Executor 的 Git Worktree 自动准备命令 (每个工单自动拉取最新分支并切出独立工作树)
# Prepare 命令模板：
# git -C ~/src/repo fetch --no-tags "https://github.com/$DSH_SUPERAGENT_GITHUB_REPOSITORY.git" "${DSH_SUPERAGENT_GITHUB_PR_HEAD:-HEAD}:refs/dsh-superagent/$DSH_SUPERAGENT_TICKET" &&
# git -C ~/src/repo worktree add -b "agent/$DSH_SUPERAGENT_NAME" "$DSH_SUPERAGENT_DIR" "refs/dsh-superagent/$DSH_SUPERAGENT_TICKET"

Step 5：发起第一个任务验证闭环

使用白名单内的 GitHub 账号，在目标仓库新建一个 Issue 或在任意已有 Issue 下发表一条新评论（注意：直接编辑旧 Issue 的正文不会触发 GitHub 通知，必须发新评论）：

@<agent-github-login> 请帮我检查并修复某模块中的拼写错误，并提交 PR。

在 1 分钟（默认轮询间隔）内，Web 面板的 Overview 和 Execution 标签页就会出现新创建的 Ticket，Agent 会在原评论下回复一句简短的接单确认，随后在 ~/.dsh/state/superagent/work/<worktree-name> 中静默完成代码修改、测试验证并提交 PR。

推荐的三阶段安全投产路线图（Progressive Rollout）

遵循 docs/000-philosophy.md 中“Start narrow, tune for less noise”的操作员责任准则，严禁在第一天就向全员开放主动模式。推荐按以下三步演进：

服务控制脚本（scripts/dsh-superagent）与 4 类退出码契约

运维脚本 scripts/dsh-superagent 提供了严密的进程管理（支持 start, stop, restart, status），其退出码专为外部自动化巡检（Watchdog）设计：

得益于 src/sources/kind.ts 的 SourceKind 插件化协议与 docs/008-cookbook.md 的详尽规范，为系统新增一个事件源（例如名为 webhook 或 gitlab）无需修改 src/core 的任何一行代码，只需按以下 5 步实现一个独立模块：