# 贡献指南

[文档索引](README.md) · [English](contributing.en.md)

感谢你考虑为 dsh-TUI 做贡献！本文档是 `dsh-cc-tui` 的共享开发契约，适用于
在本仓库工作的所有人与编码 Agent。

## 如何贡献

- **报告 bug 或请求功能**：提交 issue，附上清晰的复现步骤与你使用的终端环境。
- **提交 PR**：base 指向 `main`。保持改动聚焦——一个 PR 只做一个逻辑改动，
  标题用中文或中英对照，描述写清动机、改动点与验证方式。
- **请求 review 前先跑验证矩阵**：CI 运行的就是下面这些命令。
- 新功能应附带或扩展一个聚焦的回归脚本。

## 范围（Scope）

`dsh-cc-tui` 是单包、纯 ESM 的 TypeScript 项目：为 DeepSeek Harness 提供
React 终端 UI 前门（通过 Cordis 挂载）。包内拥有 TUI、本地命令面、打包技能
以及移植的 Ink/Yoga 渲染器；Agent、会话、模型、工具、持久化与策略域由
DeepSeek Harness 拥有，TUI 只消费它们。

做大改动前，先读 `package.json`、相关 README 章节和你将要编辑的每个源文件。
优先复用仓库现有的服务边界与辅助函数，而不是引入平行的抽象。

## 仓库地图（Repository Map）

- `src/index.ts`：公共 Cordis 插件入口、配置 Schema，与对运行时插件的惰性移交。
- `src/plugin.ts`：TTY 校验、服务注册、Agent 创建/恢复、React 树挂载，以及
  终端/进程的收尾清理。
- `src/channel.ts`：事件到视图的投影 + 非 React 的动作面。把 DSH 会话事件
  翻译成 transcript 行，实现 submit、steer、rewind、resume、模型/preset 切换、
  本地报告及相关状态迁移。
- `src/screens/Chat.tsx`：顶层交互协调器。负责模态优先级、全局键盘、滚动/
  搜索/选区状态、slash 命令分发与聊天屏组装。
- `src/screens/StatusLine.tsx` 与 `src/screens/StatusMetrics.ts`：底部状态栏
  呈现与指标推导。
- `src/components/`：功能组件。`components/design-system/` 是主题感知原语；
  `components/messages/` 是 transcript 行；`components/questions/` 是
  `ask_user_question` 的 UI。
- `src/ui.ts`：本地渲染器、主题化 `Box`/`Text`、hooks 与公共 TUI 原语的
  首选门面。
- `src/ink/`：移植的低层 Ink 渲染器与终端实现。**敏感基础设施**：改动要聚焦，
  并附渲染器专用回归覆盖。
- `src/native-ts/yoga-layout/`：渲染器使用的移植布局引擎。
- `src/cc/`：为 Claude Code 风格 UI 适配的终端格式化与呈现辅助。
- `src/*Prefs.ts`、`src/customTheme.ts`、`src/sessionHistory.ts`：持久化的
  用户偏好与 `~/.dsh-cc` 下的本地会话元数据。
- `skills/*/SKILL.md`：随 npm 包分发的技能，由 `src/packaged-skills.ts` 注册。
- `cordis.patch.yml`：profile 安装时使用的包级 bundle 覆盖层。行的顺序、行 ID、
  被禁用的 host 行、insert/override 语义都很关键。
- `cordis.yml`：直接 Cordis/DSH 启动的完整裸组合示例。
- `scripts/`：无头回归、复现环境、探针与诊断。运行前先读脚本头部说明。
- `lib/types/`：`tsc` 的入库产物（JavaScript、声明与声明映射），由 `src/`
  生成并随 npm 分发。
- `lib/invariant.js`：`./invariant` 的独立打包运行时导出；普通 `pnpm build`
  不会重新生成它。
- `README.md` 与 `README_EN.md`：中英文用户文档。行为、配置、快捷键与限制
  必须两版同步。

## 运行时形态（Runtime Shape）

核心运行时链路：

```text
Cordis config
  -> src/index.ts
  -> src/plugin.ts
  -> DSH agent/session services
  -> src/channel.ts (session events -> Channel snapshot)
  -> src/screens/Chat.tsx
  -> src/components/*
  -> src/ui.ts
  -> src/ink/* + Yoga layout
  -> terminal ANSI output
```

职责归属在各层，不要越权：

- Agent/会话/工具事实来自 DSH 服务与持久化会话事件。
- 投影与 TUI 动作属于 `channel.ts`，不属于呈现组件。
- 交互模式与按键优先级属于 `Chat.tsx` 或当前聚焦的模态/输入组件。
- 可复用的视觉行为属于 `components/` 与主题感知原语。
- 终端协议、布局、命中测试、选区与帧差分行为属于 `ink/`。

不要仅仅为了让某个界面更好写，就在 TUI 里重新实现 DSH 域服务。通过 channel
或既有注册表缝隙去适配服务。

## 工具链（Toolchain）

- 支持 Node `^22.19 || >=24`；CI 用 Node 24。
- CI 与发布用 pnpm 11；开发也请用 pnpm。
- 干净检出安装：`pnpm install --frozen-lockfile`。
- `pnpm-lock.yaml` 是 CI 锁文件。`package-lock.json` 为 npm 用户跟踪但当前
  落后于包版本；不要把它当作依赖真源，也不要顺手改写。
- 有意改依赖时：更新 `pnpm-lock.yaml`，检查完整 lockfile diff，避免无关升级。
  只有任务明确包含 npm-install 兼容性时才动 `package-lock.json`。
- `@deepseek-ai/cordis` 与 `@deepseek-ai/dsh-invariants` 同时是 peer 与 dev
  依赖，便于本地类型检查；改版本时保持这两组声明兼容。
- 不要暴露、持久化或打印凭证。交互启动读取 `DEEPSEEK_API_KEY`；诊断可以
  报告是否已设置，但绝不能泄露完整值。

## 构建与生成产物（Build And Generated Files）

常规构建与类型检查关口：`pnpm build`（`tsc -p tsconfig.json`，把 `src/` 输出
到 `lib/types/`）。仓库提交这些产物，因为发布的包直接执行它们。

生成产物规则：

- 改 `src/`，**绝不直接改 `lib/types/`**。
- 任何源码改动后运行 `pnpm build`，并提交对应的 `lib/types/` JavaScript、
  `.d.ts` 与 `.d.ts.map` 变更。
- `tsc` 不清理 `outDir`。重命名或删除源模块后，检查 `lib/types/` 并只删除该
  模块的过期输出。
- 审查生成的 diff。意外变化通常意味着编译器/配置或依赖的意外漂移。
- 纯文档、纯 workflow、纯 YAML 改动不需要重建（除非同时改了 TypeScript 输入）。
- `lib/invariant.js` 不由 `pnpm build` 生成。若 `src/invariant.ts` 或
  `./invariant` 导出契约变化，显式保持打包文件与 `lib/types/invariant.d.ts`
  对齐，并验证包导出。

`scripts/build.sh` 是面向本地 DeepSeek Harness 源码检出的备用构建器（定位 DSH
检出并重连依赖），不是本独立仓库的默认构建命令。

## 验证（Verification）

仓库没有根级 `test` 或 `lint` 脚本；不要声称跑过它们。TypeScript 构建是通用
静态关口，随后是聚焦的可执行回归。

CI 在安装后运行：

```sh
pnpm build
node --import tsx/esm scripts/repro-askpanel.tsx
node --import tsx/esm scripts/verify-askpanel-layout.tsx
node --import tsx/esm scripts/repro-toolcards.tsx
```

改动共享渲染、`Chat`、提示/问卷布局、工具卡、主题原语或 Ink core 时，三个
CI 回归都要跑。窄改动还要跑最近的聚焦脚本：

| 改动区域 | 聚焦验证 |
| --- | --- |
| 通用无头屏幕组装 | `pnpm smoke` |
| Channel submit/steer/pending 行为 | `node scripts/verify-submit.mjs` |
| 提示队列行为 | `node scripts/verify-queue.mjs` |
| Goal/todo 投影与渲染 | `node scripts/verify-channel-goal-todo.mjs` + `node scripts/verify-goal-todo.mjs` |
| Compaction 与折叠 transcript 行 | `node scripts/verify-compact.mjs` |
| 主题加载与持久化 | `node --import tsx/esm scripts/verify-themes.mjs` |
| 滚动/粘底行为 | `node scripts/verify-scroll.mjs`、`node scripts/verify-resticky.mjs` 及对应 `repro-*` 环境 |
| 全屏复制即选区 | `node scripts/verify-copy-on-select.mjs` |

多数用普通 `node` 调用的脚本 import `lib/types/`——先跑 `pnpm build`。import
TypeScript 源的脚本在头部声明 `node --import tsx/esm <script>` 形式。不要凭
扩展名推断输入层：例如 `verify-themes.mjs` 其实通过 tsx import `src/`。

部分脚本是取证/交互工具而非有界测试：堆/泄漏脚本、PTY 探针、回放捕获、
性能探针与 `scripts/run.ts` 可能依赖特定 OS、终端、原生依赖、DSH 检出或长时
进程。读头部与前置条件，不要把 `scripts/` 当套件全跑。

终端可见改动：无头断言必要但不充分。环境可用时，在 inline 与 fullscreen 两种
模式、窄终端宽度下手动走一遍受影响流程：启动、resize、滚动、输入、取消与干净
退出。Windows ConPTY、tmux、OSC 剪贴板与同步输出有独立路径，改动它们时用对应
探针。

`pnpm tui` 调用 `scripts/run.ts`，它假定包位于 DeepSeek Harness monorepo
（`apps/cli` + `packages/*`）布局内，不是可移植的独立冒烟命令。端到端集成检查：
把插件装进 DSH profile，在真实 TTY 用所需凭证运行 `dsh --profile cc-tui`。

## TypeScript 与风格（TypeScript And Style）

- 包是 ESM。TypeScript 相对导入用 `.js` 后缀（如
  `import { Chat } from './screens/Chat.js'`）。保持此规则。
- 仓库自写 TypeScript 遵循现有风格：两空格缩进、单引号、无分号、多行结构
  尾逗号。移植的 Ink 文件可保留上游的 tab 或引号风格，不要批量格式化。
- 纯类型依赖优先 `import type`。
- 不要因为 `tsconfig.json` 放宽了 `noImplicitAny` 就引入 `any`。那些放宽是
  为了编译移植的 Ink core，不能成为新应用代码的质量基准。用 `unknown` 并收窄，
  或在外部缝隙定义小型结构化接口。
- 周边 API 用只读数据的地方保持只读。状态变更放在 channel/store 实现内，
  不要在组件里改值。
- 导出的 API 用简洁 JSDoc 说明契约与非显然的不变量，不要逐行解释机制。
- 避免一次性抽象与无关重构。只有一个调用点且不阐明真正不变量的琐碎辅助函数
  就地内联。
- 保护环境敏感 import 的初始化顺序。`FORCE_COLOR`、`NODE_ENV`、终端能力标志
  常在模块求值时读取；把 import 移到它们初始化之前会无类型错误地改变行为。

## 架构不变量（Architectural Invariants）

### Cordis 生命周期与配置

- 保持 `src/index.ts` 是小的公共插件契约、`src/plugin.ts` 是运行时实现。
  除非任务有意改插件加载契约，否则保留惰性移交。
- 资源通过 Cordis 注册，用 `ctx.effect` 或既有单一退出漏斗清理。渲染失败必须
  响亮且非零退出；正常退出必须在进程退出前恢复终端状态。
- `cordis.patch.yml` 叠加在 `dsh-base` 上。不要重复 base 已挂载的服务行。
  区分 ID 覆盖与 `insert`，一个服务依赖另一个时保持顺序。
- profile 覆盖会替换整个 `config` 块。文档展示覆盖时，包含替换后必须存活的
  每个键。
- 新增或重命名插件选项时，同步更新 `src/index.ts` 的 `Config` 接口与 Schema、
  运行时消费、`cordis.patch.yml` 与 `cordis.yml` 的相应行，以及双 README。

### 会话与通道状态

- 持久化的 DSH 会话事件日志是 transcript 真源。行从事件回放/投影而来；不要
  插入可能与持久化分歧的乐观助手/工具事实。
- 保留事件顺序、序列锚点与 call-ID 匹配。rewind、resume、折叠、工具结果关联
  与导出都依赖它们。
- 每个可观察的 channel 变更必须走恰当的同步或帧合并 emitter，让 `version`
  推进、订阅者被通知。
- 保持长会话内存有界。不要在没有实测替代方案时移除 transcript 折叠、回放
  合并、虚拟化或缓存上限。
- resume、rewind、模型切换、preset 切换等 Agent 变更必须一起重置所有会话级
  投影。审计行、goals、todos、标题、pending 消息、指标与已加载上下文的陈旧
  状态。
- 通过已挂载的 DSH 服务与注册表解析 agent/model/tool/preset 能力。不要猜测
  外部 API 形状；改集成时查看已安装包的类型。

### 交互与命令

- 按键优先级是行为，不是偶然的控制流。聚焦的问卷或模态先于全局处理器消费
  按键；鼠标文本选区先于 rewind/clear 消费 Escape；提示词只在无浮层时拥有
  文本编辑。
- 不要在单个组件里硬编码新快捷键就完事。同步更新相关帮助 UI 与双 README
  快捷键表，并为与既有模式的冲突新增或扩展回归。
- 本地 slash 命令在 `src/commands.ts` 声明、`Chat.tsx` 分发；注册表命令运行时
  合并。新增命令时同步更新声明、分发、帮助/文档与打包技能映射。
- 技能命令拼写不总等于目录拼写（如本地 `/pr_comments` 激活打包的
  `pr-comments` 技能）。保留显式映射与 host 命名约束。
- `ask_user_question` 必须经 `QuestionStore` 串行化；并发问题刻意 FIFO 呈现，
  结束后汇总。

### 终端渲染

- 优先用 `src/ui.ts` 导出的主题原语与 hooks。只有门面刻意不暴露的行为才深入
  `src/ink/`。
- 终端宽度是显示单元宽度，不是 JS 字符串长度。考虑 ANSI 转义、组合字符、
  emoji 与东亚宽字符；用仓库的宽度/切片/换行/ANSI 辅助函数。
- 保持帧输出缓冲、常规运行安静。TUI 活动期间不要加 `console.log` 或 stdout
  诊断。用 opt-in 的 stderr/调试路径（如 `CC_TUI_DEBUG`）或既有
  `DSH_CC_RENDER_LOG` 帧捕获。
- 在成功、错误、中断与收尾时都保持 raw 模式、光标、alt-screen、同步输出、
  鼠标、焦点与终端查询的清理。
- 避免渲染期无界集合或每 token/每帧分配。流式会话长命，本仓库对先前的 OOM
  与滚动性能失败有明确回归。
- 布局改动不得让 transcript 内容挤掉输入行与状态行。改动相关路径时演练
  resize 风暴、超长无断内容、流式行、上滚状态与粘底恢复。
- 平台检测保持窄。Windows Terminal/ConPTY、WSL、tmux、VS Code 与支持或不支持
  truecolor/DEC 2026 的终端走不同协议路径。

### 偏好、主题与文件

- 遵循既有可配置偏好优先级：显式部署配置或环境覆盖 > 持久化用户选择 >
  检测/默认值。改变该顺序要记录。
- 用户数据持久化在既有 `~/.dsh-cc` 位置下。校验并安全解析外部 JSON；损坏的
  可选状态应警告或回退，而不是让 TUI 崩溃。
- 把主题名与文件内容当不可信输入。保留路径包含检查与损坏主题文件的
  全有或全无校验。
- 主题新增必须完整覆盖 `Theme` 契约与每个内置色板。组件用语义主题键，不要用
  孤立的字面颜色。

## 跨文件修改清单（Cross-File Change Checklist）

| 改动 | 需要同步 |
| --- | --- |
| 插件配置或环境行为 | `src/index.ts`、运行时消费、`cordis.patch.yml`、`cordis.yml`、`README.md`、`README_EN.md` |
| Slash 命令或快捷键 | `src/commands.ts`、`src/screens/Chat.tsx`、帮助/输入组件、双 README、相关技能映射/测试 |
| 主题契约或持久化主题行为 | `src/theme.ts`、所有色板、主题 provider/picker、自定义主题解析器、主题验证、双 README |
| 会话/channel 行为 | `src/channel.ts`、受影响的 UI 投影、编译产物、聚焦 channel/回放回归 |
| 渲染器/布局行为 | `src/ink/` 或 Yoga 源、编译产物、CI 回归、聚焦滚动/resize/PTY 探针 |
| 打包技能 | `skills/<name>/SKILL.md`、`src/packaged-skills.ts` 假设、暴露为 slash 命令时的提示/映射 |
| 用户可见的文档化行为 | 中英文 README，外加适用的配置注释/帮助文本 |
| 包版本或依赖 | `package.json`、`pnpm-lock.yaml`、适用时的生成/发布产物；不要顺手搅动旧 npm 锁文件 |

## Git 与发布安全（Git And Release Safety）

- 工作树可能含有他人的改动。编辑前检查 `git status` 与相关 diff，保留无关
  改动，绝不丢弃不是你创建的工作。
- 不要运行破坏性清理命令（`git reset --hard`、`git checkout .`、
  `git clean -fd`）。不要用 `git stash` 隐藏他人会话的工作。
- 只暂存显式路径，绝不在共享工作树用 `git add .` 或 `git add -A`。
- 未经用户要求，不 commit、不打 tag、不 push、不发布、不建 Release。
- 发布由 tag 驱动：`.github/workflows/publish.yml` 要求 `v*` tag 与
  `package.json` 版本完全一致，随后构建、跑聚焦回归并发布 npm。版本变更与
  tag 是发布操作，不是日常清理。
- 移交代码改动前检查 `git diff --check`、源码 diff、生成 diff 与 `git status`，
  并如实报告跑了哪些验证、哪些平台/凭证相关的检查没跑。