dsh-ankh-guard

English | 中文

让 agent 自己改代码、自己重启，还不把服务搞挂。

agent 改完代码想重启的时候，这个插件会先问一句：这次改动，构建和测试都过了吗？过了才放行，没过就拦下来——免得改坏的代码把整个服务、连同正在进行的对话一起带走。

工作原理

核心就一条规则：先证明代码是好的，才允许重启。

构建和测试全绿后，插件记录一个凭证，绑定当时的 git commit，并带 10 分钟有效期（maxAgeMinutes）。要重启时检查三点：

1. 有没有凭证；
2. 凭证超没超过 maxAgeMinutes；
3. 当前 HEAD 和记录凭证时的 commit 一不一致——记录之后任何改动都会让凭证失效。

这条规则能拦住一整类事故：改坏了构建、漏注册配置、导错模块——这些全都会让构建/类型检查失败，于是没有凭证，重启在造成伤害之前就被拒绝。

重启本身交给 watchdog 托管：独立的监督进程，宿主死了自动拉起来，起不来就回滚到检查点，连续四次失败停在崩溃页等人工处理。checkpoint 在批次前把整个工作树提交为回滚点，reset 硬重置回该点，canary 在重启后复检。检查点与凭证存在状态文件里，重启后依然存活，所以 canary 可以在新实例起来之后运行。

安装与加载

本包是 dsh 插件：守护运行中的 dsh web 实例，防止坏掉的自我修改重启。不自带宿主，先装宿主再加载插件：

npm install @deepseek-ai/dsh            # the host (dsh web / dsh CLI)
npm install @khorsheed/dsh-ankh-guard   # this plugin

然后启动宿主：npx @deepseek-ai/dsh web。

从 npm 安装插件（peer 依赖自动装）：

npm install @khorsheed/dsh-ankh-guard

或源码安装——clone、构建、测试：

git clone https://github.com/Khorsheed/dsh-ankh-guard.git
cd dsh-ankh-guard && pnpm install && pnpm run build && pnpm test

在 cordis.yml 里加载：

plugins:
  - id: ankh-guard
    name: '@khorsheed/dsh-ankh-guard'

配置（全部可选）：stateDir（默认 $DSH_HOME/state，否则 /.dsh-guard-state）、repoDir（默认进程 cwd）、maxAgeMinutes（凭证新鲜窗口，默认 10）、reportRestartContext（followup 自主报告 / step 骑下一次回合 / off，默认 followup）、fallbackGraceMs（发起会话尚未恢复时等其他 agent 接管报告前等多久，默认 60000）。

运行时需要：node、bash、macOS/Linux 上的 lsof（发现监听者；--pid 可绕过）。消费者无需构建——发布的 lib/ 就是可运行产物。

命令行

主要接口是 CLI，实例宕机也能用。安装后用 dsh-ankh-guard bin（或 node lib/cli.js）。所有命令带 --state-dir "$DSH_HOME/state" --repo "$PWD"。

dsh-ankh-guard verify      # is it safe to restart right now
dsh-ankh-guard record build+test   # green build & tests → record the credential
dsh-ankh-guard checkpoint --message "what changed"   # checkpoint before editing
dsh-ankh-guard canary --port 3080   # confirm after restart
dsh-ankh-guard supervise --port 3080 --start "CMD"   # hand the port to a watchdog