@lifenrir/dsh-external-task-context-patch 0.0.0-stage → 0.1.0

package/README-zh.md

@@ -0,0 +1,103 @@
+# dsh-external-task-context-patch
+
+DSH 官方发行版 `0.2.2-rc.1` 中的 `@deepseek-ai/dsh-subagent-claude-code` 不会写运行日志，而外部任务上下文插件依赖这些日志提供实时对话流与「统计」标签。本包在官方提供方源码上应用插件的运行日志补丁并重新构建，然后安装到现有的 DSH profile 中。
+
+未打补丁时，插件仍能展示委派提示词、运行上下文和返回结果，但 Claude Code 任务没有实时日志，也没有统计。
+
+## 支持的版本
+
+| 提供方版本 | deepseek-harness tag |
+| --- | --- |
+| `0.2.2-rc.1` | `dsh-v0.2.2-rc.1`（默认） |
+
+安装器按 `dsh-v<version>` 建立版本与 tag 的映射；若 profile 中已安装的提供方版本与 `--tag` 不一致，除非传入 `--force`，否则拒绝安装。
+
+## 使用
+
+```sh
+# 未发布到 npm 时，从插件根目录直接运行（推荐先 --dry-run）。
+node patch/install.mjs --profile desktop --dry-run
+node patch/install.mjs --profile desktop
+
+# 已发布后可用 npx。
+# Patch the only profile that has the provider installed.
+npx @lifenrir/dsh-external-task-context-patch
+
+# 指定 profile（可重复传入 --profile 处理多个）。
+npx @lifenrir/dsh-external-task-context-patch --profile desktop
+
+# 只下载和构建，不写入 profile；临时文件除外。
+npx @lifenrir/dsh-external-task-context-patch --profile desktop --dry-run
+
+# 恢复该 profile 最新的备份。
+npx @lifenrir/dsh-external-task-context-patch --profile desktop --restore
+
+# 使用本地 deepseek-harness 检出，不访问网络。
+npx @lifenrir/dsh-external-task-context-patch --profile desktop \
+  --source /path/to/deepseek-harness/packages/subagent/subagent-claude-code/src
+```
+
+其他选项：
+
+- `--dsh-home <path>`：DSH home。默认使用非空的 `$DSH_HOME`，否则 `~/.dsh`。
+- `--tag <git-tag>`：要下载的发行 tag，默认 `dsh-v0.2.2-rc.1`。
+- `--force`：在版本与 tag 不匹配，或同一 tag 已存在有效安装记录时仍继续安装，并打印醒目警告。
+- `--yes`：非交互地处理所有发现的 profile。不传时，发现结果必须恰好只有一个 profile。
+- `--source <dir>`：离线模式。目录中必须包含官方 `index.ts`、`run.ts`、`process.ts`。
+
+未指定 `--profile` 时，安装器查找
+`<dsh-home>/profiles/*/node_modules/@deepseek-ai/dsh-subagent-claude-code`。
+必须恰好匹配一个 profile；传入 `--yes` 时处理全部匹配项。
+
+每次运行都会打印 profile、提供方版本、tag、备份路径、日志目录
+（`<dsh-home>/logs/subagent-claude-code`）以及重启提醒。
+
+## 安装器改动的文件
+
+只替换提供方包中的一个文件：
+
+```
+<profile>/node_modules/@deepseek-ai/dsh-subagent-claude-code/lib/index.js
+```
+
+下载的官方 `process.ts` 保持不变；补丁版 `index.ts`、`run.ts`、`log.ts` 由 esbuild 与其一起打包（单个 ESM bundle、`packages: 'external'`、`platform: 'node'`、`target: 'node20'`）。补丁版 `log.ts` 内联解析 DSH home（`$DSH_HOME` 非空时优先，否则 `~/.dsh`），因此 bundle 不再依赖 `@deepseek-ai/dsh-home-paths`。
+
+安装器不修改 profile 的 `package.json`，不运行 `pnpm`，也不改动其他已安装文件。
+
+## 备份与恢复
+
+替换 `lib/index.js` 之前，原文件会被复制到：
+
+```
+<dsh-home>/backups/subagent-claude-code-patch/<UTC 时间戳>/<profile>/index.js
+<dsh-home>/backups/subagent-claude-code-patch/<UTC 时间戳>/<profile>/install.json
+```
+
+`install.json` 记录 `{ version, tag, installedAt, providerDir, backupFile }`。
+`--restore` 会把最新记录的备份复制回 `lib/index.js`，并写入 `restoredAt`；再次恢复是无操作。
+
+替换文件后，安装器会从提供方真实目录导入已安装的 bundle，检查
+`name === 'subagent-claude-code'` 且 `Config({}).persistNativeTranscript === true`。
+检查失败时会自动还原备份并以非零状态退出。
+
+## 重启
+
+DSH 在启动时加载提供方。安装或恢复后需要重启 DSH；在此之前旧模块仍然驻留。
+
+## 升级
+
+升级 DSH 或提供方会替换包内容，从而覆盖 `lib/index.js` 并移除补丁。升级后请按新版本和 tag 重新运行安装器。建议先使用 `--dry-run`；版本与 tag 不一致时必须加 `--force`。
+
+## 网络与代理
+
+源码从
+`https://raw.githubusercontent.com/deepseek-ai/deepseek-harness/<tag>/packages/subagent/subagent-claude-code/src/`
+下载，每个文件 30 秒超时。若 DSH 位于代理之后，请在运行安装器前设置
+`NODE_USE_ENV_PROXY=1` 与 `HTTPS_PROXY`（或 `HTTP_PROXY`），或使用
+`--source <dir>` 指向本地检出。
+
+## 测试
+
+```sh
+node --test tests/lib.test.mjs
+```

package/README.md

@@ -1,3 +1,125 @@
-# Temporary Holding Version
+# dsh-external-task-context-patch
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official DSH release `0.2.2-rc.1` ships `@deepseek-ai/dsh-subagent-claude-code`
+as a package whose provider does not write run logs. The External Task Context
+plugin needs those logs for its live conversation stream and its Statistics tab.
+This package rebuilds the official provider with the plugin's run-log patch and
+installs it into an existing DSH profile.
+
+Without the patch the plugin still shows the delegation prompt, the runtime
+context, and the returned outcome, but there is no live log and no statistics
+for Claude Code tasks.
+
+## Supported release
+
+| Provider version | deepseek-harness tag |
+| --- | --- |
+| `0.2.2-rc.1` | `dsh-v0.2.2-rc.1` (default) |
+
+The installer maps `version` to `dsh-v<version>` and refuses a profile whose
+installed provider version does not match `--tag` unless `--force` is passed.
+
+## Usage
+
+```sh
+# Before publishing to npm, run it from the plugin root (prefer --dry-run first).
+node patch/install.mjs --profile desktop --dry-run
+node patch/install.mjs --profile desktop
+
+# Once published, the npx shortcut works.
+# Patch the only profile that has the provider installed.
+npx @lifenrir/dsh-external-task-context-patch
+
+# Patch a named profile (repeat --profile for several).
+npx @lifenrir/dsh-external-task-context-patch --profile desktop
+
+# Show what would happen; downloads and builds, but writes only temp files.
+npx @lifenrir/dsh-external-task-context-patch --profile desktop --dry-run
+
+# Restore the newest backup for the profile.
+npx @lifenrir/dsh-external-task-context-patch --profile desktop --restore
+
+# Build from a local deepseek-harness checkout instead of GitHub.
+npx @lifenrir/dsh-external-task-context-patch --profile desktop \
+  --source /path/to/deepseek-harness/packages/subagent/subagent-claude-code/src
+```
+
+Other options:
+
+- `--dsh-home <path>`: DSH home. Defaults to a non-empty `$DSH_HOME`, then `~/.dsh`.
+- `--tag <git-tag>`: release tag to download. Defaults to `dsh-v0.2.2-rc.1`.
+- `--force`: install despite a provider-version/tag mismatch, or reinstall over an
+  existing active patch record for the same tag. A loud warning is printed.
+- `--yes`: process every discovered profile non-interactively. Without it,
+  discovery must find exactly one profile.
+- `--source <dir>`: offline mode. The directory must contain the official
+  `index.ts`, `run.ts`, and `process.ts`.
+
+When no `--profile` is given the installer looks for
+`<dsh-home>/profiles/*/node_modules/@deepseek-ai/dsh-subagent-claude-code`.
+Exactly one match is required unless `--yes` is passed, in which case all
+matches are patched.
+
+Each run prints the profile, the provider version, the tag, the backup path, the
+log directory (`<dsh-home>/logs/subagent-claude-code`), and a restart reminder.
+
+## What the installer changes
+
+It replaces exactly one file in the provider package:
+
+```
+<profile>/node_modules/@deepseek-ai/dsh-subagent-claude-code/lib/index.js
+```
+
+The downloaded official `process.ts` is kept; the patched `index.ts`, `run.ts`,
+and `log.ts` are bundled over it with esbuild (single ESM bundle,
+`packages: 'external'`, `platform: 'node'`, `target: 'node20'`). The patched
+`log.ts` resolves the DSH home inline (`$DSH_HOME` when non-empty, otherwise
+`~/.dsh`), so the bundle has no `@deepseek-ai/dsh-home-paths` dependency.
+
+The installer does not modify the profile's `package.json`, does not run `pnpm`,
+and does not touch any other installed file.
+
+## Backups and restore
+
+Before replacing `lib/index.js`, the original is copied to:
+
+```
+<dsh-home>/backups/subagent-claude-code-patch/<UTC timestamp>/<profile>/index.js
+<dsh-home>/backups/subagent-claude-code-patch/<UTC timestamp>/<profile>/install.json
+```
+
+`install.json` records `{ version, tag, installedAt, providerDir, backupFile }`.
+`--restore` copies the newest record's backup back over `lib/index.js` and marks
+the record with `restoredAt`; restoring again is a no-op.
+
+After replacing the file, the installer imports the installed bundle and checks
+that `name === 'subagent-claude-code'` and that
+`Config({}).persistNativeTranscript === true`. If that check fails, the backup is
+restored automatically and the command exits non-zero.
+
+## Restart
+
+DSH loads the provider at startup. Restart DSH after installing or restoring.
+Until then the old module stays loaded.
+
+## Upgrades
+
+A DSH or provider upgrade replaces the package contents, which overwrites
+`lib/index.js` and removes the patch. After any upgrade, re-run the installer
+for the new version and tag. Use `--dry-run` first; `--force` is required when
+the version and tag do not match.
+
+## Network and proxies
+
+Sources are downloaded from
+`https://raw.githubusercontent.com/deepseek-ai/deepseek-harness/<tag>/packages/subagent/subagent-claude-code/src/`
+with a 30-second timeout per file. If DSH runs behind a proxy, set
+`NODE_USE_ENV_PROXY=1` and `HTTPS_PROXY` (or `HTTP_PROXY`) before running the
+installer, or use `--source <dir>` with a local checkout.
+
+## Tests
+
+```sh
+node --test tests/lib.test.mjs
+```