dsh-chat-import: Instructions file for Codex

AGENTS.md

dsh-chat-import 是 DeepSeek Harness（DSH）插件：把 32 种来源格式（含 DSH 自身的会话日志）的聊天记录导入为可继续的 DSH 会话，支持反向导出。

原则

• 本仓库只做插件，不修改 DSH 引擎、apiproxy 或官方 UI 包。
• 宿主侧零构建，纯 ESM，lib/ 就是发布产物。唯一的例外是浏览器侧的 bundle lib/client.js：它由 src/client/ 的分片组装而成，外加白名单内联的 lib/ 纯模块，组装器是 scripts/build-client.mjs。之所以要组装，是因为 DSH 客户端加载器没有相对 require，产物必须是一个单文件（见 docs/architecture.md D7）。
• 同口径逻辑只留一份，来源清单由一张表派生（docs/architecture.md D21）：写新代码之前先找共用件，不要复制相邻来源的实现。
• 根目录只放发布到 GitHub / npm 的文件；本地工程文件收进 dev/，不提交。
• 公开文档（README 双语、docs、CHANGELOG、ROADMAP）不出现 REQ、issue 号一类内部编号。
• 结构性改动之前先读 docs/architecture.md（架构决策与权衡），不要违背已记录的决策。确实需要推翻某条决策时，先在该文档里说明旧决策为什么不再成立。
• 冲突时按这个顺序取舍：用户当次的指令 > 仓库代码现状 > 本文件 > docs/。被当次指令推翻的约定要不要回填进文档，由用户决定，AI 不现场猜。

体量停止线（机械触发，不靠判断）

• lib/ 下任何手工维护的源文件超过 1000 行（convert / export 纯函数层放宽到 800 行）：停止往里加新功能，先写一份拆分提案等用户确认；提案批准之前，该文件只修 bug。拆分方向见 docs/architecture.md D6。lib/client.js 是生成产物，不受这条限制，同样的界线作用在 src/client/ 的各个分片上。
• 同一个来源的解析或发现逻辑出现第 3 处副本时，同样停下来提案，不写第 4 处。
• test/*.test.mjs 单个文件超过 1200 行：同第一条，先拆再往里加用例。test/_support/ 与 test/fixtures/ 不受这条限制。测试面另有一项机械检查（npm run check:tests）：每个来源格式至少有一个测试锚点。
• 这几条停止线给执行模型用，触发即停，不必先判断「是否值得」。

命令

npm test               # node --test 跑 test/*.test.mjs
npm run lint           # eslint
npm run coverage       # 覆盖率护栏：line >= 75%
npm run check:coverage # 覆盖率结构：逐文件下限 + 逐目录均值下限（只看全局数字会盖住单文件的空洞）
npm run check:linux    # 跨平台路径纪律静态检查
npm run check:leaks    # 敏感信息泄漏扫描
npm run check:links    # 文档相对链接检查
npm run check:tests    # 测试面纪律：每个来源有测试锚点 + 单测文件停止线
npm run release:notes -- --version x.y.z   # 校验并预览该版本的发布说明（release workflow 用的是同一份）
npm run build:client   # 由 src/client/ 的分片组装 lib/client.js（改过面板必须重跑）
npm run build          # 发布面自检：client bundle 是否最新、files 是否完整、入口可达的模块是否都在 files 里、语法、lockfile

仓库布局

• lib/index.mjs 是插件入口（package.json 的 main），只做组装。
• lib/convert/* 与 lib/export/* 是纯函数层，不读盘、不 import 宿主模块，有测试守护。共用件在 convert/util.mjs、convert/ir.mjs、convert/core.mjs 与 export/common.mjs。设计同源的来源共用一个转换引擎，各自只留差异描述（pi 与 omp 共用 convert/pi-family.mjs，见 D21）。convert/index.mjs 只转出经它导入的名字；export/index.mjs 是公开子路径 ./export.mjs。
• lib/sources/* 是按来源命名的 host 面适配器，与 lib/convert/<src>.mjs 一一对应；SQLite 读取统一经 sources/sqlite.mjs。
• 导入编排分布在几处：lib/import-core.mjs 是单会话源与多会话源共用的状态机，lib/import-state.mjs 管已知记录与「源未变」短路径，lib/import-batch.mjs 管文件收集与批量计数，lib/import-variants.mjs 管 chatgpt / grokbuild / hermes / kimi 等特殊形态；registry 在 lib/imports.mjs。
• lib/discovery.mjs 是门面，实现放在 lib/discovery/：registry.mjs 是来源描述符表，其余是按来源族划分的扫描器模块。
• lib/tools.mjs 是门面，负责注册与档位对账，工具定义都在 lib/tools/。import_chat 的分发器与来源表在 lib/toolkit.mjs。工具 schema 只放一次调用需要的东西，长文说明在 docs/IMPORT-GUIDE.md，由运行时 skill dsh-chat-import-usage 按需加载。
• lib/client.js 是浏览器面板的 bundle，属生成产物，不要手改。源在 src/client/，组装器是 scripts/build-client.mjs。
• bin/dsh-chat-import.mjs 是独立 CLI。
• docs/ 放面向最终用户的文档（含 ROADMAP、CONTRIBUTING）。test/ 放测试与合成 fixtures，假宿主这类测试共用件在 test/_support/，不要在测试文件里另写一份。
• dev/、node_modules/、.dsh-file-claim/ 不入库。