---

title: dsh-ace 使用手册 owner: dsh-ace 维护者 status: current last_reviewed: 2026-10-21

dsh-ace —— ACE 操作手册插件

结论：装上即得一套「可进化的操作手册」——agent 完成任务后自动复盘沉淀经验，下次任务前翻手册照做；手册是纯 Markdown，人随时可以翻看和直接编辑。

dsh-ace 把 ACE（Agentic Context Engineering, arXiv 2510.04618）的方法做成 DSH 原生插件：不训练模型、不改权重，纯靠提示词与一个 Markdown 文件（playbook）。核心循环：

1. 读：任务开始前，agent 用 ace_playbook 查手册里有没有命中经验；
2. 盘：完成一个有实质工作量的任务后，agent 调 ace_reflect，由 LLM 复盘轨迹、提炼候选经验（条件/做法/依据）；
3. 并：ace_curate 把候选经验增量并入手册——增/改/删单条，LLM 去重，绝不整本重写（防止旧经验细节被磨平）。

安装

结论：一条命令安装，无需 Python、无需构建、无第三方 npm 依赖。

在终端（DSH 可用环境中）执行：

dsh plugin add github:ADkun/dsh-ace

也可以写完整地址：dsh plugin add https://github.com/ADkun/dsh-ace.git

安装后重启会话即可生效（插件注册三个工具和一段系统提示）。卸载：dsh plugin remove dsh-ace。

首次使用

结论：什么都不用配置——第一次调用会自动创建本机共享手册** <DSH home>/ace/playbook.md（Windows 上通常是 C:\Users\<你>\.dsh\ace\playbook.md），所有工作区共用这一本。**

手册位置由 playbookPath 决定，三种形态：

填什么	落在哪	用途
留空（默认）	<DSH home>/ace/playbook.md	本机共享，跨工作区共用一本
相对路径，如 .ace/playbook.md	相对会话工作目录 join	该工作区私有，可随仓库进 git
绝对路径，可 ~ 开头	原样使用	点名某一份手册

同一时刻只有一本手册被读写（不做「共享 + 项目私有」两层合并读：两层编号会撞、容量会互相吃、刚写进去的条目下次未必读得到）。

1. 正常给 agent 派活；完成一个像样的任务后，agent 会（被系统提示提醒）调用 ace_reflect 复盘，再把有价值的候选经验用 ace_curate 并入手册；
2. 想人工沉淀经验，直接告诉 agent「把这条经验加进手册」，或自己编辑上面那本手册文件（条目格式见下）；
3. 下次遇到同类任务，agent 开始前会先查手册。

手册条目格式（人可直接编辑，机器序列化同款）：

### [ace-001] 编辑前先读目标文件
- 条件：要对既有文件做任何修改之前
- 做法：先用 read 完整读一遍，确认结构后再动手
- 依据：盲改导致过两次返工
- 元数据：created=2026-02-07 updated=2026-02-07 helpful=0 harmful=0

条目编号单调递增：删掉 ace-003 之后，下一个新增是 ace-004，不会重用那个号。手册文件顶部有一行 HTML 注释记着「历史最高编号」（<!-- ace:id-highwater: 3 -->），机器写、人可直接看也可删。唯一的例外：你同时删掉最高编号的条目和这行标记时，历史最大值就没法从文件本身恢复了，那个编号可能被复用一次（之后标记会被重写成当前最大编号，也就是刚被复用的那个号，因此只会复用这一次）。只删标记不删条目的话，下一个新增仍会大于手册里现存的最高编号；只删条目不删标记的话，编号照旧不复用。

配置

结论：全部字段有默认值，零配置可用；想覆盖复盘用哪个模型、改手册位置时才需要动。

改配置有两条路：

1. 设置页（推荐）：DSH 网页端 → 侧边栏底部 Settings → 导航里的「ACE 手册」。页面是固定暗色卡片、JetBrains Maple Mono 等宽字体，改动即保存（写入宿主配置，重启会话生效）；
   • 其中 复盘 provider / model 两个覆盖字段是可搜索的分组下拉（不再是自由文本）：点开即可搜索（对 name / id / description 做大小写不敏感子串匹配），↑/↓ 移动高亮、Enter 选中、Esc 或点面板外部关闭；model 下拉按 provider 分组，已选 provider 时只列该组；
   • 两行各自都能清空（面板底部「跟随会话模型（清空）」），清空即回到跟随会话模型；
   • provider 与 model 必须两项都填才生效：只填一项时页面会在 model 行下方给出橙色警告，resolveRoute 也会静默回落到会话模型；
   • 下拉的数据来自宿主的 GET /api/dsh-ace/catalog；宿主还没重启到带这个接口的版本时，下拉里只显示一行「模型目录读取失败」，其余字段照常可用；
2. 补丁层：直接在 profile 的 cordis.patch.yml 里 override dsh-ace 条目的 config 字段。

字段	类型 / 默认值	说明
playbookPath	string / 空	手册文件路径。留空 = 本机共享手册 <DSH home>/ace/playbook.md（跨工作区共用一本）；绝对路径（支持 ~ / ~/ / ~\ 前缀）原样使用；相对路径相对会话工作目录解析，即该工作区私有
autoReflect	boolean / true	是否在系统提示里提醒 agent 任务完成后主动复盘
reflectProvider	string / 空	复盘与策展 LLM 的 provider 覆盖（设置页为可搜索下拉，可清空）；留空跟随会话模型
reflectModel	string / 空	复盘与策展 LLM 的 model 覆盖（设置页为按 provider 分组的可搜索下拉，可清空）；留空跟随会话模型。必须与 reflectProvider 同时非空才生效
maxEntries	number / 100	手册最大条目数（可填 1–1000）；超出后 ace_curate 整批拒绝并提示先合并旧条目
autoRecap	boolean / true	自动归档经验：主代理回合真正结束（无在跑子代理）后，插件在 agent 空闲下来时后台跑复盘并写入手册，不依赖模型主动调用
autoRecapThreshold	number / 1	触发自动归档所需的最小 mutating 工具调用次数（write/edit/pwsh/bash/run_code/present）
autoRecapCooldownTurns	number / 2	两次自动归档之间的最小回合间隔，避免每轮都跑
autoReviewInbox	boolean / false	预留，当前不生效：自动复审「待合并」条目的开关。实际复审入口是设置页的「待合并复审」区块与对话里的 /ace review

自动归档与「待合并」复审

结论：经验采集在后台自动完成，人只需在设置页看一眼「待合并复审」区块、偶尔输入一次 /ace review。

主代理一个回合真的干完（没有任何在跑的子代理）且本回合有足够 mutating 工具调用时，插件会在后台跑 Reflector + Curator，把新经验以增量方式写入手册（条目带 auto 标记）。子代理的回合永不触发——只有主代理采集。

触发时机在「回合真正结束、agent 空闲下来」之后，不是在回合结束的那一刻：宿主只允许在 agent 空闲时跑这类后台维护任务（回合进行中强行跑会直接失败），所以回合结束时插件先把这次复盘记成待办，等 agent 报空闲才真正执行。如果空闲那一刻 agent 恰好又被新任务拉走，这次复盘会顺延到下一个空闲时刻再试（最多试 3 次）；连续冲突才放弃并提醒你一次。

Curator 判为「新条目但与某条旧条目相似度偏高」（BM25 自评分相对阈值 50%）时，这条对子会写进手册同目录的 merge-inbox（封顶 20 条，满员后自动归档暂停新增）。人的两条出口：

1. 设置页「待合并复审」区块：逐对显示两条条目的 id、标题与相似度；区块不可用时（宿主未重启）只显示一行提示，其余字段照常可用；
2. /ace review（/ace 的 review 参数）：把待并对子注入对话（超过 8 条只注入前 8 条），模型据此用 ace_playbook 按 id 读出两条全文，能合并就走 ace_curate 的 update + remove，不能合并就原样跳过。

另有 /ace 命令作为手动兜底：立即跑一次 Reflector + Curator，写入手册（撞上并发冲突时，被拦下的条目会明确回报给你），不等自动触发。如果这会儿 agent 正忙，它会回你一句「agent 正在忙，稍后重试」——稍后再发一次即可。

手册文件存在哪（默认本机共享）

结论：手册默认一本、放在 <DSH home>/ace/playbook.md，与工作区无关；填相对路径才变成该工作区私有。

<DSH home> 的解析链（与设置文件同范式，见下节）：profileContext.home → DSH_HOME → ~/.dsh。目录不存在会在第一次写手册时自动创建（共享层的 ace 子目录同理）。想给某个仓库一份私有手册，把它设成相对路径 .ace/playbook.md 即可。

手册文件本身是首次读取时即创建的：第一次调用 ace_playbook（或 ace_reflect）读到「文件不存在」就会建出一份带文档头的空手册，父目录也一并建好。这一步在写锁内完成（与其它写入同一把锁），因此不会和并发写入打架。

多实例同时写同一本手册

结论：同一本手册上的「读-改-写」是串行的；别人在你复盘期间改了手册，你会收到一条明确报错，而不是覆盖掉对方的写。

• 写入统一经 withExclusiveLock（同进程按路径串行 + 跨进程 <file>.lock 文件锁）。锁区间内只有纯计算——Curator 的 LLM 去重在锁外跑，不占用别人的锁。
• 跨进程锁不会抢活着的持锁者：持锁进程还在就等着，最多等 30 秒；超时报错失败，而不是抢过来把对方的写盖掉。只有持锁进程已经崩溃（被强杀）留下的锁才会被立刻回收。
• 如果复盘期间别人改了同一条目，冲突按条判定：只有真正冲突的那几条被拦下，同批其余安全改动照常落盘；被拦下的条目会明确回报给你（ace_curate 的 conflicts 字段、自动复盘与 /ace 默认复盘分支的一条提示；/ace review 只是把「待合并」条目注入对话，不写手册、不做冲突判定），说明「手册在复盘期间被别的进程改过，这几条没并入，重试即可」——不静默丢弃、不覆盖对方的写。

已知限制

结论：下面几条是当前设计的边界，不是待修的缺陷——写在这里免得被当成意外。

• 并发新增只拦「重复」，不拦「不同」。 两个实例同时往同一本手册加条目时，冲突检测也参与 add：只拦与「自快照以来新出现或被改名的条目」构成重复的那些（内容完全相同、标题相同、或 BM25 相似度超阈值），其余照常落盘。与快照里本就存在、且未被改名的条目重复不算冲突——那是 Curator 去重（LLM 判 new/update/drop）的职责，不在冲突层重复拦。近似重复那一层只比正文（条件/做法/依据，不含标题）、相似度用对称比率并封顶 100%，所以「同领域的不同经验」不会被误判成重复。
• 编号可能被复用一次。 条目编号单调递增，但人同时删掉最高编号的条目和文档头的高水位标记时，历史最大值无法从文件本身恢复，那个编号可能被复用一次（之后标记会被重写成当前最大编号，也就是刚被复用的那个号，因此只会复用这一次）。这是已知边界，不是并发写导致的。
• 旧工作区里的手册不会自动搬迁。 升级前放在 <workspace>/.ace/playbook.md 的手册原样保留、不会被搬到共享层，也不会被合并——共享层是另一本独立的手册。想继续用旧的，把 playbookPath 设成那个相对路径即可。
• 多实例共享一本手册时，后写者仍可能覆盖先写者。 锁只保证「读-改-写」区间不重叠（不并发写坏文件），不保证跨实例的语义不冲突；后者靠上面的逐条冲突检测挑出来、回报给你重试。

设置文件存在哪（跟随 profile）

结论：设置文件落在当前 profile 目录下——<profileDir>/dsh-ace.json，每个 profile 各自一份；首次升级会自动从旧的 $DSH_HOME/dsh-ace.json 复制过来。

设置页保存的值（不是插件行 Config）存在这个 JSON 文件里。解析链按优先级从高到低：

1. ctx.get('profileContext').dir —— 当前 profile 的目录（$DSH_HOME/profiles/<name>，官方惯例；API 出处 dsh-app-boot\lib\types\profile-context.d.ts:10-25）；
2. DSH_PROFILE_DIR 环境变量；
3. DSH_HOME 环境变量；
4. ~/.dsh。

前一级缺失或为空串才落到下一级。升级说明：旧版本把设置写在 $DSH_HOME/dsh-ace.json（所有 profile 共用一份）。新版本第一次启动时，若新位置还没有文件而旧文件存在，会把旧内容复制到新位置并记一条日志；旧文件原样保留，不会删除。新位置已有文件时绝不覆盖——你在新位置写过的设置才是权威。因此升级后各 profile 会先继承旧设置一次，之后各写各的。

工具一览

结论：三个模型可见工具，全部围绕手册一个文件，互不越界。

工具	作用	改手册？
ace_playbook	读手册（整本 / 按条目 id / 按短关键词过滤——query 传 1-3 个短关键词，命中任一片段即返回、按相关度（BM25）排序；matched=0 时改用整本读取）	否
ace_reflect	复盘任务轨迹，产出结构化候选经验	否（只产出候选）
ace_curate	候选经验增量并入（add/update/remove + LLM 去重 + 容量护栏）	是（仅增量）

深入阅读

• 架构与不变量：DESIGN.md
• 测试与验证：TESTING.md
• 面向 agent 的约定：AGENTS.md