DeepSeek Harness TUI

键盘优先的终端 profile，独立位于本仓库 packages/dsh-tui，不修改 opensource/deepseek-harness 或 opensource/cordis。用户文档见 docs/tui-user-guide.md，验证记录见 docs/phase-0-compatibility-matrix.md。

边界

• src/harness-adapter.ts 是唯一允许接触上游的模块：它优先 import 已安装的 @deepseek-ai/dsh-* 包，开发环境回退到固定的源码 checkout，并把 Agent、 SessionEvent、approval waterfall、commands、questions 与 tool presentation 归一为 TUI 自有 contract。
• 其余模块（projection、store、卡片、布局、shutdown、诊断）不引用上游类型； 非 .tsx 模块也不引用 React/Ink。tests/isolation.spec.ts 扫描全部源码强制这两条。
• cordis.patch.yml 是外置 bundle overlay，并显式补齐 read-only permission preset；Agent loop、工具、策略、sandbox 与持久化仍归 Harness 所有。
• upstream-compat.json 固定已验证 commit 与工具链；上游更新先跑 npm run check:release，失败时保留旧基线。

模块

模块	职责
startup.ts	argv 解析与校验（进入 raw mode 前失败）
plugin.ts	组合、生命周期、受控关闭、诊断日志
harness-adapter.ts	唯一上游耦合点，含 session 列表与运行请求
agent-controller.ts	上游中立的 handle 所有权与操作
conversation-projection.ts	seq gate + 幂等折叠（id 索引，无线性扫描）
transcript-view.ts / tool-card.ts / diff-view.ts	卡片与折叠策略
terminal-text.ts / terminal-capabilities.ts / terminal-layout.ts	终端安全、能力探测与行预算
activity.ts	状态行投影（权限、todo、token、子 Agent）
session-selector.ts	恢复候选与选择解析
shutdown.ts / diagnostic-log.ts	有界关闭与脱敏诊断
app.tsx / render-boundary.tsx	Ink 渲染与区域级错误边界

开发命令

pnpm install
pnpm run check:release       # 完整发布门禁（下列全部）
pnpm run check:release -- --fast

pnpm run check:upstream      # 上游 tuple 与服务契约
pnpm build                   # 严格 TypeScript
pnpm test                    # 单元 / 投影 / 边界 / 故障注入
pnpm run check:profile       # 真实 Harness profile 组合
pnpm run check:interactive   # 80x24 审批 / 160x50 resize / 80x12 提问 / Unicode 粘贴
pnpm run check:resume        # 新建 -> 退出 -> --resume latest -> 续跑
pnpm run check:bench         # 性能预算
pnpm run check:packed        # 打包产物离树安装
pnpm run check:soak:quick    # 10 秒耐久；pnpm run check:soak 为 30 分钟
pnpm run check:node22        # Node 22 运行时矩阵
pnpm run check:real              # 真实 DeepSeek API 一次性任务（密钥取自环境或 .env）
pnpm run check:real:interactive  # 真实模型 + 真实工具 + follow-up + /quit
pnpm run check:real:approval     # read-only 预设下的真实升权与审批决策
pnpm run build:lib           # 生成发布用 lib/

pnpm run check:cli           # dshcodecli 启动器（help / 非 TTY / 非法预设 / installed 接线）

dshcodecli "检查当前改动并运行测试"
dshcodecli -i --alternate-screen "修复登录竞态"
dshcodecli --resume latest
dshcodecli --resume-select
dshcodecli --permission read-only "review current changes"

交互模式中，/model 打开模型选择器，/model PROVIDER/MODEL[:EFFORT] 从下一轮切换 当前 Session，/model save PROVIDER/MODEL[:EFFORT] 额外保存未来 Session 默认值。/status、 /context、/doctor 和 /config 提供只读运行信息；/commands 打开 Ctrl+P 命令面板； /clear、/exit 分别是 /new、/quit 的安全别名。

dshcodecli（bin/dshcodecli.mjs，pnpm link --global 后任意目录可用）是唯一入口， pnpm tui 与 scripts/run-tui.sh 已经变成它的薄别名。命令在本仓库内解析到时走 dev 模式： 以 --conditions=development 让 profile 解析 src/*.ts；装到别处则找已安装的 dsh 并解析编译后的 lib/*.js。两种模式都以你敲命令时所在的目录为工作区。

当前限制

• Ctrl+X 以 detached 进程打开编辑器，适合 GUI/远程编辑器；需要接管 TTY 的终端 编辑器不在 P0 范围。
• SSH/tmux 已探测并降级，但人工环境矩阵尚未执行；Linux/macOS 的 PTY 套件未在本 环境运行。
• 鼠标只接管滚轮（应用内翻页），接管期间原生拖选需按住 Shift，/mouse 可交还终端； 图像协议、PTY 面板、右侧 activity 面板与会话全文搜索仍未做（P1）。
• 内置 profile 注册需上游 PROFILE_TEMPLATES 配合；本仓库按 ADR 0001 只用外置 bundle。