命令与 Action 工作流

使用隐藏且不带 tools 的 compaction agent 生成续接摘要。成功后，后续 turn 会复用 该摘要而不是更早的模型上下文；当前 agent-shell buffer 中的可见 transcript 仍然 保留。Compaction 失败时不会改变之前的上下文。

这是仅供聊天调用的 Action：在 agent-shell 中输入 /authority~。 它不会出现在 ~M-x magent-action 中。

返回当前 session agent 的有效 catalog view。每一行显示 permission key、最终 decision、tool 是否暴露、rule 或 session override 来源、resource sub-rules、 approval policy，以及执行发生在 host、child Emacs 还是 live Emacs。

检查相关 buffer、region、文件、diff、错误或项目上下文，解释入口点、数据流、状态 变化和职责边界。它用于理解现有行为，不会进行编辑。

/explain 为什么这个 callback 可能完成两次

重建问题表现，定位最小且可信的根因，进行聚焦修改，在可行时补充 regression test，并运行本应捕获该问题的验证。

/fix 复现并修复失败的 ledger replay test

检查仓库文档、manifest、测试和工作流，然后创建或刷新项目根目录的 ~AGENTS.md~。已有的有效说明应被保留，并避免无关改动。

/init 加入 live Emacs 验证流程

以 senior code reviewer 的视角检查当前仓库状态和 diff，优先发现 correctness bug、regression、不安全的边界情况和缺失测试，并按严重程度输出 findings。除非 用户明确要求，否则不会修改文件。

/review 重点检查 cancellation 和 stale callbacks

从项目中找到相关测试命令，先运行最小但有意义的测试，只在必要时扩大范围。 结果会记录通过、失败和跳过的检查，以及剩余风险。

/test 运行当前分支改动文件相关的聚焦测试

agent-shell 会展示已注册 slash command，并运行选中的 /name 输入。内置单 turn prompt Action 是 magent-action-builtins.el 中的数据项；第三方包使用 相同的公开 Action API：

(require 'magent-action)

(defun my-magent-review-buffer-p (buffer)
  "当 BUFFER 含有可 review 的 diff 时返回非 nil。"
  (with-current-buffer buffer
    (derived-mode-p 'diff-mode)))

(magent-define-workflow my-magent-review (invocation)
  "Review INVOCATION 对应的 staged changes。"
  (let ((changed-files
         (magent-workflow-process
             "List staged files"
             '("git" "diff" "--cached" "--name-only"))))
    (magent-workflow-answer
        "Review staged changes"
        (format
         "Review the staged changes in these files:\n%s"
         changed-files)
      :buffers
      '(agent-shell-mode
        (magit-status-mode :required-p nil)
        ("^\\*Warnings\\*" :regexp t
         :required-p nil :project-only-p nil)
        (my-magent-review-buffer-p :predicate t :required-p nil))
      :skills '("code-review")
      :agent 'build
      :append-argument-p t
      :tools '(read_file grep bash read_tool_output))))

(magent-action-register
 "my-review"
 :description "运行包自定义的 review workflow。"
 :title "包自定义 review"
 :exposure '(slash)
 :session-policy 'current
 :workflow #'my-magent-review
 :source-layer 'project
 :source-scope "/path/to/project"
 :requires 'diff-mode)

每个 registration 必须提供且只提供一个 :workflow function，并显式指定 :session-policy~。Workflow 是由 ~magent-define-workflow 定义的 Elisp generator。分支、循环、局部状态、校验以及对 Emacs 的普通调用都直接使用 Elisp； 只有真正需要等待异步结果的地方才使用由 Magent 管理的 Step。

:exposure 声明支持的调用入口：~’(slash)~（默认）、~’(interactive)~，或 '(slash interactive)~。~M-x magent-action 只列出包含 interactive 的 Action； :session-policy 独立决定使用哪个 session。

:modes 可选地限制交互调用所在的原始 buffer：

:modes '(major magit-mode)
:modes '(minor git-commit-mode)
:modes '(or (major org-mode)
            (and (major prog-mode) (minor eglot-managed-mode)))

major 包含派生 mode；~minor~ 检查原始 buffer 中的 mode 变量。~and~ 要求全部 匹配，~or~ 要求任一匹配。不支持空表达式或任意 Lisp；不写 :modes 就不限制。 Slash 调用不检查 mode。先解析项目作用域和同名覆盖，再过滤候选；项目版本不匹配时 不会回退到全局版本。专用交互命令同样在创建 Action/session 前检查 mode。 光标是否在 diff 上等具体条件仍由 Workflow 检查。

:requires 接收一个 Emacs feature symbol 或 feature symbol list。Magent 在 Invocation preflight 中逐个调用 require~。缺少 feature 时 Action 仍可被发现，但 会在创建 isolated session 之前失败。这个选项不会安装 package、检查 executable， 也不会要求调用者位于 project workspace。已经移除的 ~:requires-project 不再有 Action 对应项。

(NAME, SOURCE-LAYER, canonical SOURCE-SCOPE) 这个三元组对应唯一的 registry slot。再次注册同一 slot 会替换旧定义，并使旧 registration token 失效；撤销新 registration 不会恢复同一 slot 的旧定义。不同 layer 和不同 project scope 仍然 彼此独立，并继续参与正常的优先级解析。

:buffers 使用类似 popwin 的有序 pattern list：

• buffer object 精确选择该 live buffer。
• string 精确选择同名 buffer。
• symbol 选择 major-mode 与它完全相同的全部 buffer。
• (REGEXP :regexp t ...) 选择名称匹配 REGEXP 的全部 buffer。
• lambda 或 closure 会按 (PREDICATE BUFFER) 调用。
• (FUNCTION-SYMBOL :predicate t ...) 显式指定一个 buffer predicate。

裸 pattern 默认必需，因此 '(magent-buffer magit-buffer) 表示两个 required major-mode selector。展开项支持 :required-p~、:regexp~、~:predicate~ 和 :project-only-p~。Required pattern 无匹配时会在提交前终止 Action；optional pattern 会记录日志后跳过。Mode、regexp 和 predicate selector 会按 ~buffer-list 顺序选择 全部 live buffer，并在 session 有项目时默认只匹配该项目；精确 buffer 和精确名称 默认不做项目过滤。两类默认值都可用 :project-only-p 显式覆盖。最终结果保持配置 顺序，并按 buffer identity 去重。

Magent 在 runtime submission 前立即为所有匹配 buffer 建立快照。Active region 优先；否则捕获当前 accessible range，因此会尊重 narrowing。快照去除 text properties，并作为 structured user resource 保存 buffer name、mode、file、modified state、point、selected/retained bounds、narrowing state 和 content。不可变快照随 user turn 持久化并用于后续 ledger replay；之后修改 live buffer 不会改写历史。

magent-action-buffer-context-max-chars 默认把所有 buffer content 的总量限制为 24000 characters；较早的 :buffers 项优先。超过剩余预算的快照会保留以 point 为 中心的窗口，并加入模型可见的截断标记。预算只计算捕获的 buffer content，不计算 resource metadata header。

模型可见 user content 的顺序是：展开后的 Action prompt、Action buffer snapshots、frontend attachments。Agent Step 的 append-argument-p 默认为 nil； 设为非 nil 时会把 slash command 后的文本追加成 Additional instruction block。 Workflow 已经读取 magent-action-invocation-argument 时应保持 nil。项目 scope、 frontend facts 和附件路径仍属于 Action Invocation，并自动继承。

Request context 是 runtime metadata，不是额外的模型输入。已识别字段可以影响项目 instructions 查找、capability resolution 或 runtime routing，但该 plist 不会原样发送 给模型。Agent 和 Answer Step 可以设置 step-local :request-context 与模型可见的 :resource-blocks~。Canonical Action metadata 由 Magent 管理；其他需要让模型看到 的指令和数据应放入 prompt、:buffers~ 或附件 resource。

由 Magent 管理的 Step forms 包括：

• magent-workflow-agent-turn 执行中间 model turn，默认返回文本。它支持 :agent~、 ~:skills~、:buffers~、~:append-argument-p~、~:tools~、~:effort~、~:thinking~、 :request-context~、:resource-blocks~ 和 ~:result~。
• magent-workflow-answer 支持相同的 model 选项，但它是 terminal Step：流式输出 最终回答并结束 Invocation，之后的 forms 不会继续执行。

:tools 是该 Step 暴露给 provider 的 exact allowlist，不只是 preflight requirement；未知或不可用的名字会在提交前失败。 :effort 支持 auto~、~minimal~、~low~、~medium~、~high 和 xhigh~； ~:thinking 支持 auto~、~enabled 和 disabled~。这些值会随该 Step 的 request 一起冻结。显式 ~disabled 会抑制 ~:effort~；若所选 reasoning provider 没有可靠的 disable 映射，则在 dispatch 前直接失败。

• magent-workflow-process 只运行由非空 string 组成的 argv list。它会捕获调用点 的 directory 和 process environment，并支持 :directory~、:environment~ override alist、~:timeout~、~:check~、~:result~、~:record-command~ 与 :record-output~。默认结果是完整 stdout；:result ’full~ 返回包含 stderr、 exit status、duration 和 timeout state 的 magent-action-process-result~。 Process Step 是 local-only：捕获到或显式传入 remote directory 时，会在创建 process 前失败。Action 若有意在 project host 执行，应使用暴露 ~bash tool 的 agent Step。
• magent-workflow-callback 用来适配已有的异步 Elisp API。Start function 接收 DONE~，必须用 ~completed~、~failed 或 cancelled 调用 (DONE STATUS VALUE) 一次，并可返回一个无参数 cancel function。

magent-action-process-timeout 是 process 的默认 deadline（300 秒）。 magent-action-step-output-max-chars 限制持久化到 activity ledger 的 process 与格式化 callback output（默认 24000 characters）；返回给 Workflow Elisp 的值 不会被截断。

Workflow 正常走到结尾时只能返回用户可见 string 或 nil。Process、agent 和 callback Step 失败时会在 generator 内抛出对应的 typed magent-action-*-error~，因此可用普通 ~condition-case 恢复。取消是 terminal 状态，不会恢复 Workflow。 magent-action-progress 仍可发送仅通知用途的进度；每个 Step 的开始和结束会自动 写入 activity ledger。

Agent 和 Answer Step 使用 runtime FIFO。Process 和 callback Step 仍由 Invocation 拥有并可取消，但不占用全局 agent execution slot，因此不同 Invocation 的外部等待 可以重叠。项目本地 Markdown 不会获得受信任 Workflow 的执行权限。

ACP 会把当前 runtime session 精确 scope 内可见的每个 instruction skill 发布成 $name~，agent-shell 将其显示为 ~/$name~。提交 ~/$name 可选说明 时，原始文本仍 作为普通 user turn 保存，同时该 skill 会被显式选择到本次 turn；它不会创建 Action Invocation。Tool-type skill 不会投影。~/skills~ 使用相同的 scope-aware descriptor 在本地列出 instruction skills，不联系 provider。Skill 永远不会投影进 Action registry。

Project Action definition 会按 canonical project scope 保留。~magent-action-get~、 magent-action-list 和 magent-action-parse 接受可选 scope；ACP 在发布菜单和 分派命令时都会传入对应 runtime session 的 scope。Skill descriptor catalog 遵循 相同规则，并保留 inactive project snapshot。因此多个项目 session 可以同时使用 同名 Action 或 skill 覆盖，而不会把一个项目的条目泄漏到另一个项目的菜单。

Magent 按文件名顺序扫描项目 .magent/actions/*.el~，仅加载顶层、非隐藏的源码文件。 文件使用普通 Elisp 定义 Workflow 并调用 ~magent-action-register~；加载器自动提供 ~:source-layer 'project 和规范化项目 scope，通过注册 API 指定其他层或项目会报错。

;;; .magent/actions/check.el -*- lexical-binding: t; -*-
(magent-define-workflow my-project-check (_invocation)
  (magent-workflow-process "Run project checks" '("make" "check")))

(magent-action-register
 "project-check"
 :description "运行当前项目的检查。"
 :exposure '(slash interactive)
 :session-policy 'isolated
 :workflow #'my-project-check)

打开 M-x magent-action 时只发现已批准的文件，不弹授权提示。 选择 manage: reload-project 批准并加载新增或修改的文件，再次打开菜单即可选择 其中的 Action。信任记录覆盖完整文件名和内容集合， 保存在本机 magent-action-project-trust-file 中；文件新增、删除或内容变化后需要 重新确认。执行的是确认过的内存快照。这些文件拥有完整的 live Emacs 执行能力； 信任机制不是沙箱，也不追踪文件间接加载的其他代码。顶层应只做定义和注册，任意 Elisp 副作用无法在加载失败后回滚。

后台和聊天发现不会弹出确认或执行未经批准的文件。可在项目 buffer 中使用 M-x magent-action-trust-project 为聊天批准文件，或重新确认此前拒绝的内容。 magent-action-reload-project 手动重新执行已批准文件； magent-action-forget-project-trust 撤销信任并删除当前文件注册。常规发现和调用时 检查内容变化，无需文件监听。删除全部文件会清除对应注册；加载报错时指出文件名， 不发布半套项目 Action，也不影响其他项目。已经启动的调用继续使用捕获的 Workflow。

M-x magent-action-run-doctor 通过可信的只读 probes 收集有边界的证据，递归脱敏后 发送一次不包含 model tools 的请求。使用前缀参数 C-u M-x magent-action-run-doctor 可以先检查适用的 probe selection。Probe API 和 安全边界见 DOCTOR.zh.org。