dsh-agent-instructions

dsh-agent-instructions

给 dsh 原生的 AGENTS.md 加一个图形编辑面板，并把官方的指令加载语义如实反映到界面上。

人格、称呼、语气这些内容就写在 AGENTS.md 里，由你自己撰写 —— 插件不管内容语义。

# 桌面端安装：在应用的「插件」页添加本插件（GitHub 地址或本地路径），
# 或直接改 desktop profile 的 package.json（link: 依赖 + bundles 条目）。
# 重启应用后生效

装好后在 侧边栏 → Agent 指令（MCP 之下）打开。

想改代码：git clone 后在桌面端「插件」页以本地路径安装，改完刷新页面即可（client 侧热生效；host 侧改动需重启应用）。

• ✅ 侧边栏一级入口：官方 sidebar.panellist + main 槽位注册（排在 MCP 之下），与「插件 / 自动化任务」同机制
• ✅ 读 / 改 / 存 任意一层：<DSH_HOME>/AGENTS.md 与工作区链上每一层的 4 个候选名
• ✅ 指令预算可视化：复刻官方发现链，算真实的字节占用与超预算裁剪
• ✅ 列表即编辑器：按读取顺序列出每一层，点哪一行就在下面编辑那一份（每个标作用范围 + 字节 + 状态点：生效 / 已暂停 / 太长会被丢掉 / 太长会被截断 / 不会被读取 / 内容重复）
• ✅ 三种生效范围：工作区 + 全局 / 仅工作区 / 仅全局 —— 暂停即改名（加 .disabled），内容一字节不丢，随时恢复
• ✅ 每一层都能单独暂停/启用（全局层与项目层走同一套机制，不再有"只有全局能暂停"的特例）
• ✅ 手写 React bundle（React.createElement，不用 JSX）+ 官方 ui-primitives 控件，无构建步骤、无第三方依赖
• ✅ 样式全部读取 dsh 的 --dsw-* 设计 token，自动跟随明暗主题与字号
• ✅ 界面语言跟随 dsh：中英双语，语言取自 dsh 自己的语言设置 —— 在 dsh 里切成英文，本插件跟着变，无需单独设
• ❌ 不修改任何 dsh 源码，只做适配
• ❌ 不注入系统提示词、不写入第二份身份文件、不改动 dsh 原生行为

---

想改代码 / 了解内部实现？见 CONTRIBUTING.md。

入口

唯一入口：侧边栏 → Agent 指令（与官方「插件 / 自动化任务」同一套一级面板机制，排在 MCP 之下）。

旧版的右下角浮动按钮已移除；v0.4.18 起设置页入口（settings.section）也按主人裁决移除， 面板代码里不再保留设置页 / 回退行 / 模态外壳的任何残留。

访问范围（这个插件碰什么、不碰什么）

收录指南要求 README 讲清"插件访问什么"，这里如实列出。host 侧只 import 了 node:crypto / node:fs / node:fs/promises / node:os / node:path —— 没有任何网络模块。

安装 / 卸载

# 安装：在桌面端应用的「插件」页添加本仓库（本地路径或 GitHub 地址）；
# 或在 desktop profile 的 package.json 里加 link: 依赖 + bundles 条目，然后重启应用。
# 重启生效（host 侧代码在应用启动时装载）

# 卸载：先在「插件」页移除（或删掉 desktop profile 的 package.json 里的
# 依赖与 bundles 条目），再删链接与源码 —— 顺序不要反，否则会在 profile 里留下断链

pnpm remove 不会清理 node_modules/dsh-agent-instructions 符号链接（link 安装的通病），需手动删除该链接。 link 安装时依赖必须装在插件源码目录（Node 从源码 realpath 解析）。

---

两级 AGENTS.md（官方机制）

• 顺序：从宽泛到具体（全局 → 项目根 → … → 会话工作目录）
• 预算：合计上限由 preset 声明（官方默认 65536 字节）；超出时宽泛的先被省略
• 项目根靠 .git 识别；AGENTS.local.md / CLAUDE.local.md 是本地叠加层
• ⚠️ 本地叠加层只在项目 scope 存在，全局 scope 没有（官方 agent-instructions/README.zh.md 原文： "项目 scope 默认加载 … overlay，但用户全局 $DSH_HOME scope 没有本地 overlay"）。代码上 files.ts:285 的全局发现用的是写死的 USER_GLOBAL_FILE = 'AGENTS.md'（render.ts:98）， 完全不遍历候选列表 —— 所以连 localInstructionFileCandidates 配置项也覆盖不到它。 ⇒ 想让规则对所有工作区生效，只能写进 ~/.dsh/AGENTS.md 本身（那是唯一文件，不是叠加层）
• 补充实测：若会话 cwd 恰为 $DSH_HOME，则 ~/.dsh/AGENTS.local.md 会被读到 —— 但它的层身份 仍是 project（被"项目目录"逻辑捡到的），不是全局层。换句话说：文件能读到 ≠ 全局层支持它
• 生效时机：官方挂的是 ctx.on('agent/pre-step', …) 钩子 —— 每一步请求前都会重新合成， 并按内容摘要（baseline.changes）检测变化后增量替换 ⇒ 改名/改内容不需要重启，对之后的请求即时生效， 同一会话内也会刷新（与 preset 层不同）
• $DSH_HOME 解析（复刻官方优先级）：显式配置 → $DSH_HOME 环境变量 → ~/.dsh；纯空白视为未设置

---

已知取舍

1. 已接入官方 slot 体系（侧边栏一级面板 sidebar.panellist + main）。这不需要构建链：官方客户端产物的依赖形式 就是普通 require——require("react") / require("react-dom/client") / require("@deepseek-ai/dsh-client-ui-primitives")，实测无需在 package.json 里声明即可解析（走共享静态表）， 组件用 React.createElement 写、不用 JSX。官方注册形式（行与页面成对，id/key 同值）：

   ctx.slots.inject('sidebar.panellist', () => ctx.slots.register({
     name: 'sidebar.panellist', id: PANEL_ID, order: 22, label: () => <文案 thunk>,
   }, IconComponent))
   ctx.slots.inject('main', () => ctx.slots.register({
     name: 'main', key: PANEL_ID,
   }, PageComponent))
   

   ⚠️ ctx.slots.register(options, component) 只有两个参数（社区某插件传的第三个 true 是多余实参，别照抄）； slot 名未被父节点声明时会 throw ⇒ 注册必须包 try/catch 并重试（slots.inject 会随父声明自动执行， 重试只兜「已声明但抛错」这一种情况）。 ⚠️ 注意两处同名但语义不同的 inject：bundle 里的 exports.inject 是 cordis 服务注入表 （要用 ctx.slots 就得写 ['slots']）；package.json 的 dsh.client.inject 才是模块/包级别声明。

2. 不做格式化 / 预览 —— 有意为之：AGENTS.md 是纯文本契约，插件不该重新排版它。

3. 预算为近似值 —— 只算文件字节，不含官方渲染边框（见上文口径说明）。

4. 暂停靠改名，会在磁盘上留痕 —— .disabled 是真实的文件名变更。若该目录是 git 仓库，git status 会显示一行改名； 不 git add 就只停在工作区，不进索引、不进历史（所以"误提交"不是会自动发生的风险，而是需要你主动做的动作）。 这是"不改官方源码、不写配置"的必然代价，换来的是随时可逆、内容零损失。

5. 未处理工作区目录不存在 —— 保存到不存在的目录会返回 404。

---