快速开始：DeepSeek Harness 运行时上手

本指南面向 Agent 运行时工程：启动 Cordis Host、编写 cordis.yml、验证预设与 Session、体验审批与 MCP。理论背景见入门导论；动手实验见七天子站。

一、环境准备

项目	要求	说明
Node.js	>= 18，推荐 20 LTS	`node -v` 验证
包管理	npm / pnpm / yarn	npx 路径需 npm
LLM API	OpenAI 兼容 Key	DeepSeek / OpenAI 等
磁盘	≥ 2GB 可用	Session Log 增长
内存	≥ 4GB 推荐	MCP 多进程时

export DEEPSEEK_API_KEY="sk-..."
export DSH_LOG_LEVEL="info"   # 排错时用 debug

默认 Web UI 地址：http://127.0.0.1:3080

1.1 网络与代理

企业环境若 npx 拉包失败，配置 HTTPS_PROXY 或使用内 npm mirror。LLM API 需 Host 出站访问；纯内网部署需自建模型 endpoint 并在 Profile 修改 model.baseURL。

二、安装路径对比

路径	命令	适用场景	缺点
npx 一键	`npx @deepseek-ai/dsh web`	首次体验、Demo	版本浮动
克隆源码	`git clone` + `pnpm install` + `pnpm dev`	插件/Bug 开发	需构建
Docker	官方镜像 + volume	生产预演、CI	需维护镜像

# 推荐首启命令
npx @deepseek-ai/dsh web

# 等价包名（视发布渠道）
# npx @deepseek-ai/deepseek-harness web

生产应用 pin digest 而非 @latest；开发可用 pnpm link 本地 cordis 插件。

2.1 决策矩阵

你的目标	选择
15 分钟体验	npx
写 Cordis 插件	clone 源码
K8s 部署 Rehearsal	Docker + PVC
无 Node 的服务器	Docker only

三、cordis.yml 精讲

项目根或 DSH_CONFIG_DIR 指向目录下的 cordis.yml 是 Effective Runtime 的声明式入口。

host:
  name: local-dev
  port: 3080
  bind: 127.0.0.1
bundle: standard
profile: local
profiles:
  local:
    model:
      provider: deepseek
      name: deepseek-chat
      apiKey: ${DEEPSEEK_API_KEY}
    session:
      store: ./.dsh/sessions
      maxTurns: 40
    sandbox:
      workspace: ./demo-ws
      denyPaths:
        - "**/.env"
        - "**/secrets/**"
    approval:
      mode: permissive
    context:
      compress: hybrid
patches: []

字段	配置层	含义
`bundle`	Bundle	预设能力包
`profile`	Profile	当前激活环境名
`profiles.*`	Profile	各环境参数块
`patches`	Patch	短期覆盖列表

Patch 示例——临时禁用 bash：

patches:
  - op: disable
    path: tools.bash
    reason: "demo 只读"
    expire: "2026-12-31"

3.1 合并语义

后应用的 Patch 覆盖先应用的 Profile 字段；patches 数组顺序 significant。环境变量 ${VAR} 在启动时展开，缺失时 fail-fast。

四、首启验证（七步）

node -v ≥ 18
export DEEPSEEK_API_KEY=...
创建 demo-ws/README.md 测试文件
写入第三节 cordis.yml
npx @deepseek-ai/dsh web
浏览器打开 http://127.0.0.1:3080，选 Standard
发送：「读取 README 第一行」→ 检查 .dsh/sessions/*/events.jsonl

健康检查：curl -sf http://127.0.0.1:3080/health 应返回 200。

五、预设切换实验

固定 Prompt：「列出当前目录文件并总结」，分别用 Standard / Code / Minimal 新建 Session 对比：

观测项	Standard	Code	Minimal
可用 tools	中	多含 bash	少
是否触发 approval	少见	bash 常见	罕见
token 消耗	中	高	低

Creator 预设

Creator 仅能在 隔离 VM 或容器 中实验。禁止对生产仓库或含真实 Key 的环境使用。

# 切换 bundle 只需改 cordis.yml 后重启 Host
# bundle: code

六、Session 观察

Session 目录：./.dsh/sessions/<sessionId>/events.jsonl

tail -f .dsh/sessions/*/events.jsonl | python3 -m json.tool

关键事件类型：user_message、assistant_message、tool_call、tool_result、approval_blocked、session_fork。

Resume/Fork/Replay 语义详见 intro 第八章。

七、审批初体验

将 bundle 改为 code，approval.mode 改为 strict，Prompt：「执行 rm -rf /tmp/test」

预期：UI 或 CLI 出现 approval 弹窗；jsonl 写入 approval_blocked 或用户确认后执行。

子站交互 lab：审批模拟器

八、MCP 初配

mcp:
  servers:
    filesystem:
      command: npx
      args:
        - "-y"
        - "@modelcontextprotocol/server-filesystem"
        - "./demo-ws"

重启 Host 后，Log 应出现 MCP connect 事件；UI tools 列表含 MCP 提供的 tools。MCP 工具与内置工具 同一审批链。

九、排错决策树

现象	可能原因	修复
EADDRINUSE	3080 占用	改端口
401 / 403	Key 错或过期	轮换 Key
白屏	前端未 build	用官方 npx 包
无 tool_call	model 不支持 tools	换 deepseek-chat 等
MCP spawn fail	command 路径错	本地先跑 MCP 命令

十、验收清单

npx @deepseek-ai/dsh web 成功监听 3080
理解 cordis.yml 三层字段
Standard 下完成带 tool 的对话
对比至少两种预设
找到并解读 events.jsonl
体验一次 approval 拦截
知悉 Creator 风险
（可选）MCP filesystem 连通

十一、下一步

开发指南：编写 Cordis 插件
从零到一：完整项目实战
最佳实践：生产部署
七天子站：Day 2+ 实验

十二、30 分钟首启完整剧本

mkdir -p ~/dsh-lab/demo-ws && cd ~/dsh-lab
echo "# Harness Lab" > demo-ws/README.md
echo 'console.log("ok")' > demo-ws/index.js
cat > cordis.yml << 'EOF'
host:
  name: lab
  port: 3080
bundle: standard
profile: local
profiles:
  local:
    model:
      provider: deepseek
      name: deepseek-chat
      apiKey: ${DEEPSEEK_API_KEY}
    session:
      store: ./.dsh/sessions
    sandbox:
      workspace: ./demo-ws
patches: []
EOF
export DEEPSEEK_API_KEY="sk-..."
npx @deepseek-ai/dsh web

另开终端：curl -sf http://127.0.0.1:3080/health && find .dsh -name '*.jsonl'

UI Prompt 序列：①「README 主题」②「index.js 做什么」③「创建 notes.txt 写入 hello」（观察是否触发 tool 与 approval）

十三、cordis.yml 扩展字段参考

字段路径	类型	默认值	说明
host.bind	string	127.0.0.1	0.0.0.0 允许 LAN
host.port	number	3080	多实例改 3081
session.maxTurns	number	无限制	防 agent loop
session.store	path	.dsh/sessions	生产用 PVC
sandbox.denyPaths	glob[]	[]	拒绝敏感路径
sandbox.denyNetwork	bool	false	内网 QA 可 true
approval.mode	enum	permissive	prod 用 strict
approval.rules	array	[]	tool 名 pattern
context.compress	enum	hybrid	none/sliding/summarize/hybrid
otel.enabled	bool	false	staging 建议 true
otel.endpoint	url	-	Jaeger/OTLP
mcp.servers	map		MCP Server 定义

十四、安装故障库（分场景五步法）

EADDRINUSE

lsof -i :3080 查占用进程
kill 或改 host.port
重启 npx
curl health
记录端口规范进团队 wiki

npx 首次极慢

检查 npm registry 与代理
预装 npm i -g @deepseek-ai/dsh pin 版本
或使用 Docker 镜像
CI 缓存 npm store
文档注明期望冷启动时间

401 Unauthorized

echo 环境变量是否为空（勿 commit Key）
验证 Key 在 provider 控制台有效
检查 model.provider 与 baseURL
用 curl 直接打 LLM API 对比
轮换 Key 后重启 Host

模型从不调用 tool

确认 bundle 非 empty
换支持 function calling 的 model.name
Prompt 明确「使用工具读取文件」
debug 日志看 tools schema 是否下发
对照 intro 工具管道

十五、预设对照实验记录表

实验 Prompt：「分析 demo-ws 目录并给出改进建议」

指标	Standard	Code	Minimal
首 token 延迟	记录	记录	记录
总 turn 数
tool_call 次数
approval 次数
估算 token

实验后回答：谁适合 prod 默认？谁适合 CI smoke？Creator 为何不能填表？

十六、Session Log 分析命令

SESSION=$(ls -t .dsh/sessions | head -1)
cat .dsh/sessions/$SESSION/events.jsonl | python3 -c "
import sys,json
for line in sys.stdin:
    e=json.loads(line)
    print(e.get('type'), e.get('name','')[:40])
"

筛选 tool：grep tool_call events.jsonl。筛选拦截：grep blocked。

Resume 测试：对话中 kill Host 进程 → 同 sessionId 重启 → UI 点 Resume → 上下文应连贯。

十七、审批规则配置工作坊

approval:
  mode: strict
  rules:
    - match: "bash"
      action: require_human
    - match: "rm*"
      action: deny
    - match: "read_file"
      action: allow

实验 Prompt：①「bash: ls」②「bash: rm x」③「读 README」。确认 jsonl 三类不同事件。

十八、MCP 连通剧本

安装 @modelcontextprotocol/server-filesystem
cordis.yml 添加 mcp.servers
重启 Host，日志搜 mcp
Prompt「用 MCP 列出 demo-ws 文件」
故意写错 command，观察 fail-fast 错误
修正后 tool 出现
确认 MCP tool 走 approval（若配置 strict）

十九、OpenTelemetry 本地验证

otel:
  enabled: true
  endpoint: http://localhost:4318

启动 Jaeger all-in-one，完成一轮对话，在 UI 查 trace：http → session.turn → llm → tool。

二十、沙箱边界测试（预期 deny）

Prompt	预期
读 /etc/passwd	deny 或 block
写 ../outside.txt	deny
curl 外网 URL	视 denyNetwork

记录 jsonl 中 sandbox 相关事件，附进安全评审文档。

二十一、Spawn 子 Agent 观察

Code 预设 Prompt：「Spawn 子 agent 专门分析 index.js，父 session 等待摘要」

观察：是否出现第二个 sessionId 目录；父 jsonl 是否有 spawn/wait 事件；子 Session tool 集是否更小。

二十二、CI Smoke 示例

# .github/workflows/dsh-smoke.yml 概念片段
- run: npx @deepseek-ai/dsh web &
- run: sleep 10 && curl -sf http://127.0.0.1:3080/health
- run: kill %1

生产 CI 应 pin 版本 + 最小 cordis.yml + Minimal bundle 降成本。

二十三、Docker Compose 与 Session 持久化

services:
  dsh:
    image: deepseek-harness:latest
    ports: ["3080:3080"]
    volumes:
      - ./cordis.yml:/config/cordis.yml
      - dsh-sessions:/data/sessions
    environment:
      - DSH_CONFIG_DIR=/config
volumes:
  dsh-sessions:

验证：重启容器后 Session 可 Resume。

二十四、Git 分支与 cordis 治理

main：prod Profile 模板，无 Key，无 creator 默认
develop：staging Profile
feature 分支：允许 patches 实验，merge 前清空或合并 patches

PR Review 检查清单：Key 泄露、workspace 过大、approval off、creator 默认值。

二十五、升级与回滚

pin npx @deepseek-ai/dsh@1.2.3
staging Replay 50 条 Session
升级 MINOR
若 regression：digest 回滚镜像
postmortem 补 Replay case

二十六、八小时实验日议程

时段	内容
上午	npx 首启、cordis 字段、Standard 对话
下午	Code+审批、Minimal 成本、Session 分析
傍晚	MCP、沙箱测试、验收清单
可选	Creator 隔离容器（非 prod 数据）

交付物：验收清单签字、jsonl 样例、预设对比表。

二十七、团队 Handoff 模板

Host URL 与 port
当前 bundle / profile
session.store 路径
Key 来源（Vault 路径，非值）
Creator 是否禁用（必须否）
on-call 排错树链接：本文第九章

二十八、与 intro 五核心对照实验

核心	实验
Plugin	换 bundle 观察 tool 集变化
inject	故意错误 token 插件（源码 dev）
Events	strict approval 看 wrap
Teardown	重启 Host 10 次查端口泄漏
Context	改 session.store 路径

每项记录观察结果，与 intro 第三章对照。

二十九、Staging 演练

复制 prod cordis 为 staging Profile
log level debug，otel 全采样
Replay 生产 anonymized Session 10 条
20 并发 smoke（locust 或简单 shell loop）
kill Host 测 Resume

三十、故障注入

注入	预期 Host 行为
kill -9 Host	Session 可 Resume
断网	LLM 报错 surfaced，不 silent hang
磁盘满	Session 写入失败有 log
慢 tool	timeout 后 tool_error 事件

三十一、WSL 与 SSH 隧道

WSL2 内绑定 host.bind: 0.0.0.0，Windows 浏览器访问 localhost:3080。

远程 Linux：ssh -L 3080:127.0.0.1:3080 user@server，本地浏览器访问。

勿将 0.0.0.0 暴露公网无认证。

三十二、Minimal 成本压测

同一 FAQ 分类 Prompt 跑 5 次：Standard vs Minimal。记录平均 token 与 P95 延迟。Minimal 应显著更低 turn/tool 数。

三十三、Creator 容器隔离

docker run --read-only --tmpfs /tmp -p 3080:3080   -e DEEPSEEK_API_KEY -v $(pwd)/cordis-creator.yml:/config/cordis.yml   deepseek-harness:latest

实验完销毁容器与 Session volume，不使用生产 Key。

三十四、扩展验收（进阶）

三十五、常见问题

Q：能否用 OpenAI Key？ A：可以，Profile 改 provider/baseURL/model。

Q：Session 存在哪？ A：profiles.*.session.store，Docker 需 volume。

Q：多用户？ A：单 Host 适合团队内网；多租户需 Profile 隔离与认证插件。

Q：与 OpenClaw 关系？ 见 FAQ。

附录 A：命令速查

npx @deepseek-ai/dsh web
export DSH_CONFIG_DIR=~/dsh-configs/staging
export DSH_LOG_LEVEL=debug
curl http://127.0.0.1:3080/health
git clone https://github.com/deepseek-ai/deepseek-harness

附录 B：环境变量

变量	作用
DEEPSEEK_API_KEY	模型 API
DSH_CONFIG_DIR	cordis.yml 目录
DSH_LOG_LEVEL	debug/info/warn
HTTPS_PROXY	企业代理

附录 C：Profile 四套模板片段

local：permissive approval，本地 session 路径。ci：Minimal，tmpfs。staging：strict，otel on。prod：strict，creator 禁，PVC session。

变更任何 Profile 后建议跑一条 Replay 或手动 smoke。

附录 D：结语

你已完成 DSH 运行时 Host + cordis + Session Log 三角验证。继续 development 写插件，或七天子站 Day 2 深入 Cordis Events。

Walkthrough 1：monorepo sandbox

在 monorepo 根目录设 sandbox.workspace 为 packages/app，Prompt 读兄弟包文件，验证 deny 无法读 packages 外路径。

Walkthrough 2：pnpm dev 源码

clone 后 pnpm dev 启动，对比 npx 行为差异，理解插件热重载与 Bundle 加载路径。

Walkthrough 3：DSH_CONFIG_DIR

准备两套配置目录 staging/prod，export DSH_CONFIG_DIR 切换，避免单文件来回改出错。

Walkthrough 4：PR Review

提交 cordis.yml PR 时 CI 扫描 Key 正则、creator bundle、patches 行数>5 警告。

Walkthrough 5：安全 Prompt

三连：读 .env、rm -rf、curl 内网 IP，确认 block 事件与 UI 提示。

Walkthrough 6：Resume kill

长对话中途 kill -9，重启后 Resume，turn 序号连续。

Walkthrough 7：Fork 双 patch

同问题 Fork 两分支，分别应用不同 patch，对比结果后删除实验 Session。

Walkthrough 8：双端口

3080 Standard 与 3081 Code 并行，理解 Host 进程隔离与 session.store 是否分开。

Walkthrough 9：Jaeger span

在 trace 中点击 dsh.tool.execute，对照 jsonl 同一 turn 的 tool_call 事件。

Walkthrough 10：jsonl jq

jq 'select(.type=="tool_call")' events.jsonl 统计工具调用频率。

三十六、headless API 与自动化集成

部分部署暴露 HTTP API 供 CI 调用（概念路径，以官方文档为准）：POST /api/sessions 创建 Session，POST /api/sessions/:id/messages 发送消息。自动化应：

使用 Minimal bundle 降本
设置 maxTurns 防止 runaway
轮询 jsonl 或 SSE 流获取 tool 事件
超时后 kill Session 并告警

勿在 CI 使用 Creator；Key 用 short-lived OIDC 注入。

三十七、Profile 四套完整 YAML 片段

local — 开发：approval.mode: permissive，session.store: ./.dsh/sessions，otel.enabled: false。

ci — 流水线：bundle: minimal，session.store: /tmp/dsh-ci，无 MCP，health-only smoke。

staging — 预发：与 prod 同 bundle，approval.mode: strict，otel.enabled: true，DSH_LOG_LEVEL: debug。

prod — 生产：bundle: standard 或 code，creator 不可用，session.store 指向 PVC/S3，approval.mode: strict，sandbox.denyNetwork: true（视业务）。

切换 Profile 用 profile: 字段 + 重启；或用 DSH_CONFIG_DIR 目录隔离。

三十八、观察清单与 on-call 包

每次发版后 8 条观察：

health 200
一条对话产生 tool_call
strict 下 bash 被拦
jsonl 持续增长
Resume 可用
换 bundle 新 Session 正常
OTel span 完整（若启用）
MCP connect 无 error log

on-call 包应含：当前 cordis Git 链接、Vault secret 路径、排错树、Jaeger dashboard URL、Creator 禁用截图、最近 Replay CI 链接。

三十九、npx 与 Docker 选型终局

维度	npx	Docker
冷启动	慢	中
版本 pin	@version	digest
Session	本地	volume
插件开发	不便	挂载源码
生产	不推荐	推荐

学习路径用 npx；staging/prod 用镜像 + K8s Deployment + PVC。

四十、从 0 到第一次 tool_call 心智模型

用户输入 → Client 序列化 → Host 写 Log → 组装 messages/tools → LLM 返回（可能纯文本或 tool_call）→ 若有 tool_call 则 wrap→sandbox→execute→tool_result→再调 LLM → assistant 文本 → Client 渲染。

若 LLM 只返回文本：检查 Prompt 是否明确要求工具、model 是否支持 FC、bundle 是否为空、debug 日志 tools 数组长度。

四十一、失败模式汇总与工程对策

阶段	失败模式	检测信号	对策
安装	registry 超时	npx hang	镜像/离线包
配置	yml 合并错	工具集不符预期	debug 打印 effective config
启动	插件环依赖	exit 1 cyclic	拆分 inject
对话	401	LLM 报错	轮换 Key
对话	无 tool	纯文本回复	换 model/bundle
工具	sandbox deny	tool_error	缩 workspace
工具	approval block	blocked 事件	用户确认或改规则
MCP	spawn fail	mcp_error log	修正 command
Session	磁盘满	write EIO	归档 jsonl
升级	Replay diff	CI red	pin 旧版或 fix

首启成功后，建议将 demo-ws 纳入 git 而 .dsh 加入 gitignore，Session 不应进版本库。

企业 proxy 下 npx 失败时，可在内网 Verdaccio 镜像 @deepseek-ai/dsh 包。

cordis.yml 中 apiKey 永远使用 ${ENV} 占位，pre-commit hook 扫描 sk- 前缀。

验收时截图 events.jsonl 一条 tool_call 与一条 assistant_message 作为培训材料。

预设切换实验务必新建 Session，避免旧 context 中 tool 权限记忆干扰对比。

WSL 用户若 3080 无法访问，检查 Windows 防火墙与 WSL 端口转发文档。

Docker 部署时 DSH_CONFIG_DIR 只读 mount，Session volume 单独读写。

Minimal 压测结果应写入团队 wiki，作为 FinOps 选 preset 依据。

MCP command 使用 npx -y 时 CI 需缓存 npm 以免每次 cold pull。

kill Host 测 Resume 前，先确认 session.store 非 tmpfs 否则数据丢失。

strict approval 下 UI 超时未确认应写入 approval_timeout 事件，便于分析 UX 摩擦。

staging Replay 样本须脱敏 PII，jsonl 中 email 替换为 hash。

双端口实验时两个 Host 的 session.store 必须不同目录，防止 SessionId 碰撞。

health curl 应进 K8s readinessProbe，liveness 用轻量 HTTP 即可。

完成验收后，在七天子站 Day1 checklist 打勾，保持与文档一致。

Apple Silicon Mac 使用 npx 与 x86 镜像无本质差异，Docker 选 arm64 digest。

Windows 原生 Node 路径注意 sandbox.workspace 用正斜杠或双反斜杠转义。

并发 Session 压测时观察 Host 内存与 MCP 子进程数，必要时 limit MCP 连接池。

tool 超时在 Profile 可配，避免 slow grep 大 repo 阻塞 Agent loop。

LLM streaming 开启时 UI 逐 token 显示，jsonl 仍按 turn 批量写入。

错误 message 应对用户友好，内部 stack 仅写 debug 日志，见 Host 错误 surfaced 规范。

从 intro 带过来的 Bundle 概念，在 getting-started 用改 bundle 字段验证即可，无需改代码。

patch expire 字段到期后 Host 应 warn 日志提醒合并，避免 silent 继续生效。

graduation 标准：能独立填验收清单、能读 jsonl、能配 strict approval 即毕业 getting-started。

团队协作时 cordis.yml 变更应 link 到 intro 对应章节，便于 reviewer 理解 Bundle/Profile 语义。

本地 demo-ws 可放故意错误代码供 Code 预设练习 fix，但勿含真实 secret。

进阶附录：把「能跑」变成「可交接」

A. 团队 onboarding 90 分钟剧本

分钟	动作	验收
0–15	安装 Node、配置 Key、npx/源码二选一启动	UI 打开，health 正常
15–30	Standard 对话 + 观察 Session 文件增长	能指出 USER/LLM/TOOL 事件
30–45	切换 Minimal 重跑同一任务	工具面变窄可感知
45–60	配置一条 deny/ask 规则并触发	审批 UI 或日志出现
60–75	故意写错模型 baseURL，走排错树	5 分钟内定位
75–90	导出 resolved config 与 Session 片段交 PR 描述	可被同事复现

B. WSL / 远程开发注意点

工作目录放在 Linux 文件系统侧，避免 /mnt/c 上大量文件监听导致 Effect 卡顿；
端口转发确认 3080（或实际端口）未被公司代理劫持；
若 API 需代理，把代理配置放进 Host 环境变量而非写进可提交的 cordis.yml。

C. 双环境端口约定

本地常用：开发 Host 3080、预发 3081。Client 若写死 origin 会导致「连错环境还在看旧 Session」。用环境变量注入 API base，并在 UI 页脚显示 profile@host 标识。

D. 首次配置密钥轮换演练

用临时 Key 跑通；
轮换为正式 Key；
重启 Host，确认无旧 Key 残留于进程环境与日志；
Session 中不应打印 Key。把「日志红队」列入验收。

E. headless / CI 最小调用

CI 中用 Minimal + 非交互审批策略（只允许只读）跑冒烟：启动 → 发固定 prompt → 断言 Session 含 DONE 且无 deny 误杀。Creator 永不进 CI 默认矩阵。

DSH_CONFIG_DIR（或等价）放 yml 与 Patch；Session / 缓存放数据目录并进备份策略。备份配置不备份未脱敏 Session，或对 Session 做字段级脱敏后再存对象存储。

G. 升级清单

升级 Bundle 前：读 changelog → 在 staging 跑 Replay 套件 → 对比 tool schema hash → 再滚动生产。若 Replay 大面积失败，优先怀疑工具描述或参数约束变更，而不是「模型变笨」。

H. 常见安装故障速查（扩展）

症状	排查命令/动作	修复方向
pnpm 锁冲突	删 store 元数据后重装	统一包管理器
原生依赖编译失败	查 Node ABI	换 LTS、装 build tools
UI 空白	浏览器控制台与 CSP	检查反向代理路径
工具全失败	sandbox workdir 权限	修正挂载与用户 uid

I. 验证「Patch 真的生效」

改完审批规则后，不要只看 yml：跑一条必触发规则的命令，并在 Session 搜审批事件。若事件不存在，说明运行时未加载该 Patch（路径错误、profile 名不匹配或缓存旧进程）。

J. 交接包内容

交给下一班 on-call 的最小包：resolved config 快照、当前 Bundle 版本、活跃 Profile 列表、最近 24h 审批拒绝 TopN、已知 MCP 依赖、回滚 tag。没有交接包的「已部署」等于不可运维。

附录 K：首周运维值班最小手册

把快速开始从「个人跑通」升级为「小组可值班」，需要一份任何人都能执行的手册。以下内容可直接贴进团队 wiki，并按你们的端口与目录改名。

K.1 值班接班检查（10 分钟）

打开 Host 健康页或 CLI health，确认进程存活；
查看最近 1 小时审批 ask/deny 比例，异常飙升先当事故信号；
确认 MCP 依赖列表中标记为 required 的进程均为 up；
抽查一条生产 Session：事件是否连续、有无重复 TOOL 风暴；
确认当前 Bundle 版本与变更日历一致。

K.2 用户报障话术到技术动作

用户说法	你要翻译成的技术问题	立刻做的事
Agent 不理我	是审批卡住还是模型超时	看 Session 最后事件类型
它乱删文件	是否绕过 ask/deny	拉审批日志与工具参数
今天突然变笨	Profile/Bundle 是否变更	对比 resolved config diff
以前的会话续不上	store 是否丢或路由到其它实例	查 session id 路由与后端

K.3 本地与预发的数据隔离

切勿用生产 Session 目录挂到笔记本电脑做「顺便调试」。正确做法是导出脱敏片段或使用 Replay 夹具。预发数据库/对象存储必须与生产分离，密钥也分离。

K.4 一键启动之外的长期跑法

个人学习用 npx 很好；团队长期环境应固定版本、写 systemd/compose、配置日志轮转与磁盘水位告警。Session 与模型缓存目录要进监控：「磁盘满」常表现为莫名其妙的工具失败。

K.5 与文档站的关系（避免学偏）

本站 docs/dsh 讲的是 Harness 运行时工程；dsh_frontend 七天子站是课表与实验室。部署文档站或子站的 Nginx/证书知识，不能替代你对 Cordis Teardown 与审批矩阵的理解。值班手册应链接到开发指南与最佳实践，而不是只链接服务器 runbook。

K.6 30 天能力目标（给新成员）

第 1 周：独立完成安装、预设切换、Session 阅读；
第 2 周：写出最小插件并证明可卸载；
第 3 周：配置审批矩阵并通过攻击性用例；
第 4 周：完成一次 Replay CI 与一次模拟 Incident。

达到后，再进入从零到一的 Day6–7 做多 Agent 与发布。

附录 L：配置实验记录卡（可打印）

每次改 cordis.yml 或 Patch，用同一张卡记录，避免「昨天能跑今天不能」无法回溯。

日期与操作者
目标 Profile 名称
变更意图（一句话）
diff 摘要（改了哪些键）
resolved config 是否已导出
验证步骤（对话原文 + 期望工具）
Session id
结果：通过 / 失败 / 部分通过
回滚方式（git revert / 换 tag / 重载旧 Patch）
是否需要同步文档与子站实验说明

连续两周坚持后，你的快速开始经验会沉淀为团队资产，而不是个人笔记本里的碎片命令。这也是从「学会启动」走向「可运营 Harness」的最小习惯。

一、环境准备​

1.1 网络与代理​

二、安装路径对比​

2.1 决策矩阵​

三、cordis.yml 精讲​

3.1 合并语义​

四、首启验证（七步）​

五、预设切换实验​

六、Session 观察​

七、审批初体验​

八、MCP 初配​

九、排错决策树​

十、验收清单​

十一、下一步​

十二、30 分钟首启完整剧本​

十三、cordis.yml 扩展字段参考​

十四、安装故障库（分场景五步法）​

EADDRINUSE​

npx 首次极慢​

401 Unauthorized​

模型从不调用 tool​

十五、预设对照实验记录表​

十六、Session Log 分析命令​

十七、审批规则配置工作坊​

十八、MCP 连通剧本​

十九、OpenTelemetry 本地验证​

二十、沙箱边界测试（预期 deny）​

二十一、Spawn 子 Agent 观察​

二十二、CI Smoke 示例​

二十三、Docker Compose 与 Session 持久化​

二十四、Git 分支与 cordis 治理​

二十五、升级与回滚​

二十六、八小时实验日议程​

二十七、团队 Handoff 模板​

二十八、与 intro 五核心对照实验​

二十九、Staging 演练​

三十、故障注入​

三十一、WSL 与 SSH 隧道​

三十二、Minimal 成本压测​

三十三、Creator 容器隔离​

三十四、扩展验收（进阶）​

三十五、常见问题​

附录 A：命令速查​

附录 B：环境变量​

附录 C：Profile 四套模板片段​

附录 D：结语​

Walkthrough 1：monorepo sandbox​

Walkthrough 2：pnpm dev 源码​

Walkthrough 3：DSH_CONFIG_DIR​

Walkthrough 4：PR Review​

Walkthrough 5：安全 Prompt​

Walkthrough 6：Resume kill​

Walkthrough 7：Fork 双 patch​

Walkthrough 8：双端口​

Walkthrough 9：Jaeger span​

Walkthrough 10：jsonl jq​

三十六、headless API 与自动化集成​

三十七、Profile 四套完整 YAML 片段​

三十八、观察清单与 on-call 包​

三十九、npx 与 Docker 选型终局​

四十、从 0 到第一次 tool_call 心智模型​

四十一、失败模式汇总与工程对策​

进阶附录：把「能跑」变成「可交接」​

A. 团队 onboarding 90 分钟剧本​

B. WSL / 远程开发注意点​

C. 双环境端口约定​

D. 首次配置密钥轮换演练​

E. headless / CI 最小调用​

F. 配置目录与状态目录分离​

G. 升级清单​

H. 常见安装故障速查（扩展）​

I. 验证「Patch 真的生效」​

J. 交接包内容​

附录 K：首周运维值班最小手册​

K.1 值班接班检查（10 分钟）​

K.2 用户报障话术到技术动作​

K.3 本地与预发的数据隔离​

K.4 一键启动之外的长期跑法​

K.5 与文档站的关系（避免学偏）​

K.6 30 天能力目标（给新成员）​