dsh-ctxlift 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +26 -0
- package/CONTRIBUTING.md +34 -0
- package/LICENSE +21 -0
- package/README.md +103 -2
- package/README.zh-CN.md +104 -0
- package/cordis.patch.yml +4 -0
- package/lib/client.js +477 -0
- package/lib/config.d.ts +142 -0
- package/lib/config.d.ts.map +1 -0
- package/lib/config.js +113 -0
- package/lib/config.js.map +1 -0
- package/lib/engine/coordinator.d.ts +44 -0
- package/lib/engine/coordinator.d.ts.map +1 -0
- package/lib/engine/coordinator.js +103 -0
- package/lib/engine/coordinator.js.map +1 -0
- package/lib/engine/files.d.ts +35 -0
- package/lib/engine/files.d.ts.map +1 -0
- package/lib/engine/files.js +206 -0
- package/lib/engine/files.js.map +1 -0
- package/lib/engine/render.d.ts +46 -0
- package/lib/engine/render.d.ts.map +1 -0
- package/lib/engine/render.js +139 -0
- package/lib/engine/render.js.map +1 -0
- package/lib/index.d.ts +82 -0
- package/lib/index.d.ts.map +1 -0
- package/lib/index.js +53 -0
- package/lib/index.js.map +1 -0
- package/lib/remote.d.ts +49 -0
- package/lib/remote.d.ts.map +1 -0
- package/lib/remote.js +148 -0
- package/lib/remote.js.map +1 -0
- package/locale/en.json +35 -0
- package/locale/zh.json +35 -0
- package/package.json +86 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 的格式。
|
|
4
|
+
|
|
5
|
+
## [0.1.0] - 2026-10-27
|
|
6
|
+
|
|
7
|
+
首个发布版本。完成官方范式重构与隔离实例全量验收。
|
|
8
|
+
|
|
9
|
+
### 新增
|
|
10
|
+
|
|
11
|
+
- 四层独立截断策略:全局(`globalPolicy`)、项目根 `CLAUDE.md`(`projectClaudePolicy`)、项目根 `AGENTS.md`(`projectAgentsPolicy`)、子目录(`subdirectoriesPolicy`),每层支持 `unlimited` / `truncate` / `disabled`。
|
|
12
|
+
- 全局文件偏好:`auto` / `agents` / `claude` / `both`,打破官方硬编码 `USER_GLOBAL_FILE='AGENTS.md'` 的限制。
|
|
13
|
+
- 浏览器内在线编辑全局指令文件(`AGENTS.md` / `CLAUDE.md`),经 RPC 服务原子落盘。
|
|
14
|
+
- 按官方范式重构:`Config` Schema(schemastery,全字段 volatile、无默认值)、`InstructionsGuardService extends TypertRemoteService` + `@Remote`、`ctx.plugin` 挂载、`scripts/build-client.mjs` 生成 ModuleLoader 客户端产物、`configForms.whileServed + plugins.bundle.config` 配置面板。
|
|
15
|
+
- 配置写入统一为官方 `{op:'set'|'unset'}` 通道,宿主持久化回写 `cordis.patch.yml` 并带 revision 冲突保护。
|
|
16
|
+
|
|
17
|
+
### 修复
|
|
18
|
+
|
|
19
|
+
- 插件"装配但未激活"根因:缺失 `Config` Schema 导致 settings 命名空间缺失;客户端产物非 ModuleLoader 形态被 client-runner 跳过;错误使用 `typertRemote.register` 手写注册。
|
|
20
|
+
- `saveGlobalContent` 增加强校验:拒绝非字符串内容,杜绝空载荷覆写用户全局文件。
|
|
21
|
+
|
|
22
|
+
### 验证
|
|
23
|
+
|
|
24
|
+
- 13 项单测全绿;隔离环境全功能验收(E2E)10 项标准全过。
|
|
25
|
+
- 隔离实例真机验收:settings 命名空间出现 `dsh-ctxlift`、浏览器面板渲染、编辑器保存落盘字节校验、四层截断策略独立生效(17/17)、真实 agent 会话三态(truncate / disabled / unlimited)实测。
|
|
26
|
+
- 冷装 / 热装 / 热卸载验收通过。
|
package/CONTRIBUTING.md
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# 贡献指南
|
|
2
|
+
|
|
3
|
+
欢迎为 dsh-ctxlift 贡献代码、文档或问题反馈。以下约定能让你快速上手,也让我们保持一致的工程质量。
|
|
4
|
+
|
|
5
|
+
## 开发环境
|
|
6
|
+
|
|
7
|
+
- Node >= 20,pnpm >= 9
|
|
8
|
+
- 克隆后 `pnpm install`(会安装 dev 与 peer 依赖)
|
|
9
|
+
- `pnpm typecheck` / `pnpm build` / `pnpm test` 分别对应类型检查、构建(tsc + build-client)与单测
|
|
10
|
+
- 隔离环境全功能验收:`node test/e2e/isolated-real-acceptance.mjs`
|
|
11
|
+
|
|
12
|
+
## 提交规范
|
|
13
|
+
|
|
14
|
+
- 提交信息使用英文,遵循 Conventional Commits(`feat:` / `fix:` / `docs:` / `refactor:` / `chore:` 等),可带简短说明。
|
|
15
|
+
- 每个小改动独立提交,保持提交粒度小、可回溯。
|
|
16
|
+
|
|
17
|
+
## 代码约定
|
|
18
|
+
|
|
19
|
+
- 代码注释使用简体中文,文档不使用 emoji。
|
|
20
|
+
- 保持改动最小、职责单一;不添加未要求的功能或抽象。
|
|
21
|
+
- 修改引擎逻辑(`src/engine/`)时,请同步更新或补充 `test/` 下的对应单测。
|
|
22
|
+
- 关键契约(Config 缺失导致不激活、volatile 语义、RPC 端点自动发现、客户端 `$mount` 等)记录在项目记忆库 `CLAUDE.md`,改动涉及这些契约时请一并维护。
|
|
23
|
+
|
|
24
|
+
## 问题反馈
|
|
25
|
+
|
|
26
|
+
提交 Issue 时请说明:
|
|
27
|
+
|
|
28
|
+
- DSH 运行时版本(`dsh --version`)与 profile 形态(web / headless)
|
|
29
|
+
- 复现步骤与预期行为
|
|
30
|
+
- 相关配置与日志
|
|
31
|
+
|
|
32
|
+
## 发布流程
|
|
33
|
+
|
|
34
|
+
- 版本号遵循 SemVer。发布由 tag(`v*`)触发 `.github/workflows/publish.yml`,先确保版本号已在 `package.json` 中更新并写入 `CHANGELOG.md`。
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Wenaixi
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,104 @@
|
|
|
1
|
-
#
|
|
1
|
+
# dsh-ctxlift
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[English](./README.md) | [简体中文](./README.zh-CN.md)
|
|
4
|
+
|
|
5
|
+
[](./LICENSE)
|
|
6
|
+
[](https://github.com/deepseek-ai/deepseek-harness)
|
|
7
|
+
[](https://nodejs.org)
|
|
8
|
+
[](https://pnpm.io)
|
|
9
|
+
|
|
10
|
+
A DeepSeek Harness (DSH) plugin that gives you fine-grained control over workspace instruction injection: independent truncation policies for the global `AGENTS.md` / `CLAUDE.md`, project-root instruction files, and subdirectory instruction files — plus an in-browser editor for global instruction files.
|
|
11
|
+
|
|
12
|
+
## Why
|
|
13
|
+
|
|
14
|
+
The official `agent-instructions` plugin shares one global byte budget across all instruction files. When the budget is exceeded it drops files in order of specificity — the **global `AGENTS.md` is discarded first** — and only truncates what is left. There is no way to say "never truncate the global rules" or "cap only the project `CLAUDE.md`".
|
|
15
|
+
|
|
16
|
+
`dsh-ctxlift` replaces that one-size-fits-all behavior with four independent policy layers.
|
|
17
|
+
|
|
18
|
+
## Features
|
|
19
|
+
|
|
20
|
+
- Four independent policy layers, each with its own mode:
|
|
21
|
+
- `unlimited` — keep the whole file, never truncate
|
|
22
|
+
- `truncate` — keep the first N bytes (UTF-8 safe, no broken characters)
|
|
23
|
+
- `disabled` — do not inject this layer at all
|
|
24
|
+
- Global file preference: `auto` / `agents` / `claude` / `both` — breaks the official hardcoded `USER_GLOBAL_FILE='AGENTS.md'` limit and supports a global `CLAUDE.md` (or both files at once).
|
|
25
|
+
- In-browser editor for global instruction files (`AGENTS.md` / `CLAUDE.md`) with atomic writes through an RPC service.
|
|
26
|
+
- Onion-skin replacement of the official `agent-instructions` messages on every agent step, so your policies take effect in real sessions.
|
|
27
|
+
|
|
28
|
+
## Install
|
|
29
|
+
|
|
30
|
+
Requires the DSH runtime (`npm i -g @deepseek-ai/dsh`). Examples use the `web` profile; substitute your own profile name.
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
# Install (automatic HMR reload)
|
|
34
|
+
dsh plugin --profile web add dsh-ctxlift
|
|
35
|
+
|
|
36
|
+
# Remove
|
|
37
|
+
dsh plugin --profile web remove dsh-ctxlift
|
|
38
|
+
|
|
39
|
+
# Inspect composed patch tree
|
|
40
|
+
dsh --profile web --dump-config | grep -A2 ctxlift
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Configuration
|
|
44
|
+
|
|
45
|
+
Open the plugin card in the settings page (the `plugins.bundle.config` slot). The panel has two parts:
|
|
46
|
+
|
|
47
|
+
1. **Policy layers** — one row per layer:
|
|
48
|
+
|
|
49
|
+
| Layer | Default | Scope |
|
|
50
|
+
|---|---|---|
|
|
51
|
+
| Global (`globalPolicy`) | unlimited, 131072 bytes | `~/.dsh/AGENTS.md` / `CLAUDE.md`, every session |
|
|
52
|
+
| Project root CLAUDE.md (`projectClaudePolicy`) | truncate, 65536 bytes | `<project>/CLAUDE.md`, `CLAUDE.local.md` |
|
|
53
|
+
| Project root AGENTS.md (`projectAgentsPolicy`) | truncate, 65536 bytes | `<project>/AGENTS.md`, `AGENTS.local.md` |
|
|
54
|
+
| Subdirectories (`subdirectoriesPolicy`) | truncate, 32768 bytes | `CLAUDE.md` / `AGENTS.md` in nested subdirectories |
|
|
55
|
+
|
|
56
|
+
2. **Global file preference** — `auto` / `agents` / `claude` / `both`, plus an editor tab that reads and writes the active global file directly from the browser.
|
|
57
|
+
|
|
58
|
+
Configuration is persisted by the host through the official `ConfigForms` channel (`profiles/<name>/cordis.patch.yml`), with revision conflict protection. Global file content is the only plugin-side disk write and uses an atomic temp-file + rename.
|
|
59
|
+
|
|
60
|
+
## Architecture
|
|
61
|
+
|
|
62
|
+
```
|
|
63
|
+
src/
|
|
64
|
+
├── index.ts Host entry: exports { name, inject, Config, apply };
|
|
65
|
+
│ assembles the coordinator and mounts the RPC service via ctx.plugin
|
|
66
|
+
├── config.ts Config Schema (schemastery, all fields volatile, no defaults);
|
|
67
|
+
│ DEFAULT_CONFIG + resolveConfig for the engine
|
|
68
|
+
├── remote.ts InstructionsGuardService extends TypertRemoteService,
|
|
69
|
+
│ @Remote('getGlobalInfo'|'saveGlobalContent'|'switchGlobalFilename')
|
|
70
|
+
└── engine/ render.ts (UTF-8-safe truncation), files.ts (discovery),
|
|
71
|
+
coordinator.ts (agent/pre-step onion-skin replacement)
|
|
72
|
+
scripts/
|
|
73
|
+
└── build-client.mjs Generates lib/client.js as a window.__ModuleLoader__.load bundle
|
|
74
|
+
that $mounts the remote descriptors and registers the config panel
|
|
75
|
+
locale/ zh.json / en.json
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Key contracts (verified against DSH source):
|
|
79
|
+
|
|
80
|
+
- `Config = Schema.object({...})` — a missing Config means no settings namespace, and the plugin never activates.
|
|
81
|
+
- All fields are `.volatile()` without Schema defaults, so "unconfigured" is distinguishable from an explicit write.
|
|
82
|
+
- Host RPC endpoints are discovered automatically from the `TypertRemoteService` subclass mounted via `ctx.plugin(...)`.
|
|
83
|
+
- The client bundle must explicitly `ctx.remote.$mount(...)` its descriptors — the host only mounts the built-in official contributions.
|
|
84
|
+
- The client needs `inject: ['slots', 'locale', 'configForms', 'remote']`.
|
|
85
|
+
|
|
86
|
+
## Development
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
pnpm install # installs dev + peer dependencies
|
|
90
|
+
pnpm typecheck # tsc --noEmit
|
|
91
|
+
pnpm build # tsc into lib/, scripts/build-client.mjs generates lib/client.js
|
|
92
|
+
pnpm test # node --test test/*.test.mjs (13 unit tests)
|
|
93
|
+
node test/e2e/isolated-real-acceptance.mjs # isolated full-function acceptance
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Compatibility
|
|
97
|
+
|
|
98
|
+
- Node >= 20
|
|
99
|
+
- DSH runtime `>=0.2.0-rc.1 <=0.2.1`
|
|
100
|
+
- pnpm >= 9 (lockfile v9)
|
|
101
|
+
|
|
102
|
+
## License
|
|
103
|
+
|
|
104
|
+
MIT. Full text in [LICENSE](./LICENSE).
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# dsh-ctxlift
|
|
2
|
+
|
|
3
|
+
[English](./README.md) | [简体中文](./README.zh-CN.md)
|
|
4
|
+
|
|
5
|
+
[](./LICENSE)
|
|
6
|
+
[](https://github.com/deepseek-ai/deepseek-harness)
|
|
7
|
+
[](https://nodejs.org)
|
|
8
|
+
[](https://pnpm.io)
|
|
9
|
+
|
|
10
|
+
面向 DeepSeek Harness (DSH) 的工作区指令精细化截断插件:为全局 `AGENTS.md` / `CLAUDE.md`、项目根指令文件、子目录指令文件分别提供独立策略(不截断 / 按字节截断 / 完全禁用),并在浏览器内直接编辑全局指令文件。
|
|
11
|
+
|
|
12
|
+
## 为什么需要它
|
|
13
|
+
|
|
14
|
+
官方 `agent-instructions` 插件给所有指令文件共用一个全局字节预算。预算超限时按"从宽泛到具体"的顺序丢弃文件——**全局 `AGENTS.md` 最先被丢**——最后剩下的文件才做截断。你无法表达"全局守则永远不许截断"或"只限制项目 CLAUDE.md"这类需求。
|
|
15
|
+
|
|
16
|
+
`dsh-ctxlift` 用四个互相独立的策略层取代这种一刀切行为。
|
|
17
|
+
|
|
18
|
+
## 功能特性
|
|
19
|
+
|
|
20
|
+
- 四层独立策略,每层可选三种模式:
|
|
21
|
+
- `unlimited`:完整保留,永不截断
|
|
22
|
+
- `truncate`:保留开头 N 字节(UTF-8 边界安全,不产生乱码)
|
|
23
|
+
- `disabled`:整层不注入
|
|
24
|
+
- 全局文件偏好:`auto` / `agents` / `claude` / `both`——打破官方硬编码 `USER_GLOBAL_FILE='AGENTS.md'` 的限制,支持全局 `CLAUDE.md`(或两者同时注入)。
|
|
25
|
+
- 浏览器内在线编辑全局指令文件(`AGENTS.md` / `CLAUDE.md`),经 RPC 服务原子落盘。
|
|
26
|
+
- 每个 agent 步骤上以洋葱圈方式替换官方 `agent-instructions` 消息,策略在真实会话中生效。
|
|
27
|
+
|
|
28
|
+
## 安装
|
|
29
|
+
|
|
30
|
+
需要 DSH 运行时(`npm i -g @deepseek-ai/dsh`)。以下示例使用 `web` profile,请替换为你自己的 profile 名。
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
# 安装(自动 HMR 热重载)
|
|
34
|
+
dsh plugin --profile web add dsh-ctxlift
|
|
35
|
+
|
|
36
|
+
# 卸载
|
|
37
|
+
dsh plugin --profile web remove dsh-ctxlift
|
|
38
|
+
|
|
39
|
+
# 查看装配树
|
|
40
|
+
dsh --profile web --dump-config | grep -A2 ctxlift
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## 配置
|
|
44
|
+
|
|
45
|
+
在设置页的插件卡片(`plugins.bundle.config` 插槽)中配置。面板分两部分:
|
|
46
|
+
|
|
47
|
+
1. **策略层**——每层一行:
|
|
48
|
+
|
|
49
|
+
| 层 | 默认值 | 作用范围 |
|
|
50
|
+
|---|---|---|
|
|
51
|
+
| 全局指令(`globalPolicy`) | unlimited / 131072 字节 | `~/.dsh/AGENTS.md` / `CLAUDE.md`,所有会话 |
|
|
52
|
+
| 项目根 CLAUDE.md(`projectClaudePolicy`) | truncate / 65536 字节 | `<项目>/CLAUDE.md`、`CLAUDE.local.md` |
|
|
53
|
+
| 项目根 AGENTS.md(`projectAgentsPolicy`) | truncate / 65536 字节 | `<项目>/AGENTS.md`、`AGENTS.local.md` |
|
|
54
|
+
| 子目录指令(`subdirectoriesPolicy`) | truncate / 32768 字节 | 深层子目录中的 `CLAUDE.md` / `AGENTS.md` |
|
|
55
|
+
|
|
56
|
+
2. **全局文件偏好**——`auto` / `agents` / `claude` / `both`,外加一个编辑器页签,可直接在浏览器中读写当前全局文件。
|
|
57
|
+
|
|
58
|
+
配置由宿主通过官方 `ConfigForms` 通道持久化(`profiles/<name>/cordis.patch.yml`),带 revision 冲突保护。全局文件内容是插件侧唯一允许的磁盘写,采用临时文件 + rename 原子落盘。
|
|
59
|
+
|
|
60
|
+
## 架构
|
|
61
|
+
|
|
62
|
+
```
|
|
63
|
+
src/
|
|
64
|
+
├── index.ts Host 入口:导出 { name, inject, Config, apply };
|
|
65
|
+
│ 组装 coordinator 并通过 ctx.plugin 挂载 RPC 服务
|
|
66
|
+
├── config.ts Config Schema(schemastery,全字段 volatile、无默认值);
|
|
67
|
+
│ DEFAULT_CONFIG + resolveConfig(引擎归一)
|
|
68
|
+
├── remote.ts InstructionsGuardService extends TypertRemoteService,
|
|
69
|
+
│ @Remote('getGlobalInfo'|'saveGlobalContent'|'switchGlobalFilename')
|
|
70
|
+
└── engine/ render.ts(UTF-8 安全截断)、files.ts(文件发现)、
|
|
71
|
+
coordinator.ts(agent/pre-step 洋葱圈替换)
|
|
72
|
+
scripts/
|
|
73
|
+
└── build-client.mjs 生成 lib/client.js(window.__ModuleLoader__.load 形态),
|
|
74
|
+
$mount 远端描述符并注册配置面板
|
|
75
|
+
locale/ zh.json / en.json
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
关键契约(均经 DSH 真实源码核实):
|
|
79
|
+
|
|
80
|
+
- `Config = Schema.object({...})` —— 缺 Config 就没有 settings 命名空间,插件不会激活。
|
|
81
|
+
- 全字段 `.volatile()` 且不给 Schema 默认值,"未配置"与"显式写入"可区分。
|
|
82
|
+
- 宿主 RPC 端点由 `ctx.plugin(TypertRemoteService 子类)` 自动发现。
|
|
83
|
+
- 客户端 bundle 必须显式 `ctx.remote.$mount(...)` 自己的描述符——宿主只挂载内置官方贡献。
|
|
84
|
+
- 客户端需要 `inject: ['slots', 'locale', 'configForms', 'remote']`。
|
|
85
|
+
|
|
86
|
+
## 开发
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
pnpm install # 安装 dev + peer 依赖
|
|
90
|
+
pnpm typecheck # tsc --noEmit
|
|
91
|
+
pnpm build # tsc 输出 lib/,scripts/build-client.mjs 生成 lib/client.js
|
|
92
|
+
pnpm test # node --test test/*.test.mjs(13 项单测)
|
|
93
|
+
node test/e2e/isolated-real-acceptance.mjs # 隔离环境全功能验收
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## 兼容性
|
|
97
|
+
|
|
98
|
+
- Node >= 20
|
|
99
|
+
- DSH 运行时 `>=0.2.0-rc.1 <=0.2.1`
|
|
100
|
+
- pnpm >= 9(lockfile v9)
|
|
101
|
+
|
|
102
|
+
## 许可证
|
|
103
|
+
|
|
104
|
+
MIT,全文见 [LICENSE](./LICENSE)。
|
package/cordis.patch.yml
ADDED