[[http://www.gnu.org/licenses/gpl-3.0.txt][文件:https://img.shields.io/badge/license-GPL_3-green.svg]] [[https://melpa.org/#/ellama][文件:https://melpa.org/packages/ellama-badge.svg]] [[https://stable.melpa.org/#/ellama][文件:https://stable.melpa.org/packages/ellama-badge.svg]] [[https://elpa.gnu.org/packages/ellama.html][文件:https://elpa.gnu.org/packages/ellama.svg]]

Ellama 是一个用于从 Emacs 中与大型语言模型交互的工具。它允许你向 LLM 提出问题并接收回复。通过 Emacs 界面，Ellama 可以执行多种任务，例如翻译、代码审查、摘要生成、改进语法/拼写或措辞等。Ellama 原生支持流式输出，因此可以轻松地与你喜欢的文本编辑器一起使用。

“ellama”这个名字来源于“Emacs Large Language Model Assistant”。前一句话正是由 Ellama 自己撰写的。 [[文件:imgs/reasoning-models.gif]]

• 安装

只需输入 M-x package-install @@html:@@Enter@@html:@@ ellama @@html:@@Enter@@html:@@。默认情况下，它使用 [[https://github.com/jmorganca/ollama][ollama]] 提供商。如果你对此没有异议，你需要安装 [[https://github.com/jmorganca/ollama][ollama]] 并拉取 [[https://ollama.com/models][任何 ollama 模型]]，如下所示：

#+BEGIN_SRC shell ollama pull qwen2.5:3b #+END_SRC

你可以将 ellama 与其他模型或另一个 LLM 提供商一起使用。如果没有进行任何配置，系统会自动使用第一个可用的 ollama 模型。你可以按照以下方式自定义 Ellama 的配置：

#+BEGIN_SRC emacs-lisp (use-package ellama :ensure t :bind ("C-c e" . ellama) ;; 在聊天缓冲区中用 C-c C-c 发送最后一条消息 :hook (org-ctrl-c-ctrl-c-hook . ellama-chat-send-last-message) :init (setopt ellama-auto-scroll t) :config ;; 在所有缓冲区的标题栏中显示 Ellama 上下文 (ellama-context-header-line-global-mode +1) ;; 在所有缓冲区的标题栏中显示 Ellama 会话 ID (ellama-session-header-line-global-mode +1)) #+END_SRC

更复杂的配置示例：

#+BEGIN_SRC emacs-lisp (use-package ellama :ensure t :bind ("C-c e" . ellama) ;; 在聊天缓冲区中用 C-c C-c 发送最后一条消息 :hook (org-ctrl-c-ctrl-c-hook . ellama-chat-send-last-message) :init ;; 设置键绑定 ;; (setopt ellama-keymap-prefix "C-c e") ;; 你希望 Ellama 翻译成的语言 (setopt ellama-language "German") ;; 例如可以是 llm-openai (require 'llm-ollama) (setopt ellama-provider (make-llm-ollama ;; 使用此模型前需先拉取 ;; 值应与你在终端拉取时打印的值一致 :chat-model "llama3:8b-instruct-q8_0" :embedding-model "nomic-embed-text" :default-chat-non-standard-params '(("num_ctx" . 8192)))) (setopt ellama-summarization-provider (make-llm-ollama :chat-model "qwen2.5:3b" :embedding-model "nomic-embed-text" :default-chat-non-standard-params '(("num_ctx" . 32768)))) (setopt ellama-coding-provider (make-llm-ollama :chat-model "qwen2.5-coder:3b" :embedding-model "nomic-embed-text" :default-chat-non-standard-params '(("num_ctx" . 32768)))) ;; 预定义的 LLM 提供商，用于交互式切换。 ;; 不应在此处添加 ollama 提供商——它们可以在不添加的情况下直接交互选择。此处仅为示例。 (setopt ellama-providers '(("zephyr" . (make-llm-ollama :chat-model "zephyr:7b-beta-q6_K" :embedding-model "zephyr:7b-beta-q6_K")) ("mistral" . (make-llm-ollama :chat-model "mistral:7b-instruct-v0.2-q6_K" :embedding-model "mistral:7b-instruct-v0.2-q6_K")) ("mixtral" . (make-llm-ollama :chat-model "mixtral:8x7b-instruct-v0.1-q3_K_M-4k" :embedding-model "mixtral:8x7b-instruct-v0.1-q3_K_M-4k")))) ;; 使用 LLM 命名新会话 (setopt ellama-naming-provider (make-llm-ollama :chat-model "llama3:8b-instruct-q8_0" :embedding-model "nomic-embed-text" :default-chat-non-standard-params '(("stop" . ("\n"))))) (setopt ellama-naming-scheme 'ellama-generate-name-by-llm) ;; 翻译 LLM 提供商 (setopt ellama-translation-provider (make-llm-ollama :chat-model "qwen2.5:3b" :embedding-model "nomic-embed-text" :default-chat-non-standard-params '(("num_ctx" . 32768)))) (setopt ellama-extraction-provider (make-llm-ollama :chat-model "qwen2.5-coder:7b-instruct-q8_0" :embedding-model "nomic-embed-text" :default-chat-non-standard-params '(("num_ctx" . 32768)))) ;; 自定义显示缓冲区的行为 ;; 参见 (info "(elisp) Buffer Display Action Functions") (setopt ellama-chat-display-action-function #'display-buffer-full-frame) (setopt ellama-instant-display-action-function #'display-buffer-at-bottom) :config ;; 在所有缓冲区的标题栏中显示 Ellama 上下文 (ellama-context-header-line-global-mode +1) ;; 在所有缓冲区的标题栏中显示 Ellama 会话 ID (ellama-session-header-line-global-mode +1) ;; 处理滚动事件 (advice-add 'pixel-scroll-precision :before #'ellama-disable-scroll) (advice-add 'end-of-buffer :after #'ellama-enable-scroll)) #+END_SRC

• 命令

• ellama: 这是 Ellama 的入口点。它会显示主临时菜单，允许你从这里访问所有其他 Ellama 命令。
• ellama-chat: 通过在交互式缓冲区中输入提示来向 Ellama 提问，并继续对话。如果使用通用参数调用（C-u），将启动一个新的会话，并提供 LLM 模型的交互式选择。
• ellama-write: 此命令允许你使用 LLM 生成文本。交互式调用时，它会提示你输入一条指令，然后根据上下文生成文本。如果当前有区域被选中，则会在生成响应之前将选中文本添加到临时上下文中。
• ellama-chat-send-last-message: 发送当前 Ellama 聊天缓冲区中提取的最后一条用户消息。
• ellama-ask-about: 向 Ellama 提问关于选定区域或当前缓冲区的内容。会自动将选定区域或当前缓冲区添加到临时上下文中，用于一次请求。
• ellama-ask-selection: 将选定区域或当前缓冲区发送到 Ellama 聊天中。
• ellama-ask-line: 将当前行发送到 Ellama 聊天中。
• ellama-complete: 使用 Ellama 完成当前缓冲区中的文本。
• ellama-translate: 请求 Ellama 翻译选中的区域或光标处的单词。
• ellama-translate-buffer: 翻译当前缓冲区。
• ellama-define-word: 使用 Ellama 查找当前单词的定义。
• ellama-summarize: 使用 Ellama 总结选定区域或当前缓冲区的内容。
• ellama-summarize-killring: 总结剪贴板中的文本。
• ellama-code-review: 使用 Ellama 审查选定区域或当前缓冲区中的代码。会自动将选定区域或当前缓冲区添加到临时上下文中，用于一次请求。
• ellama-change: 根据提供的修改内容更改选定区域或当前缓冲区中的文本。
• ellama-make-list: 使用 Ellama 从当前区域或缓冲区创建 Markdown 列表。
• ellama-make-table: 使用 Ellama 从当前区域或缓冲区创建 Markdown 表格。
• ellama-summarize-webpage: 使用 Ellama 总结从 URL 获取的网页内容。
• ellama-provider-select: 选择 Ellama 提供者。
• ellama-code-complete: 使用 Ellama 根据提供的修改内容完成选定代码或当前缓冲区中的代码。
• ellama-code-add: 根据描述生成并插入新代码。此功能会提示用户描述他们想要生成的代码。如果当前有区域被选中，则会将选中文本包含在用于代码生成的临时上下文中。
• ellama-code-edit: 使用 Ellama 根据提供的修改内容更改选定代码或当前缓冲区中的代码。
• ellama-code-improve: 使用 Ellama 根据提供的修改内容改进选定代码或当前缓冲区中的代码。
• ellama-generate-commit-message: 根据差异生成提交信息。
• ellama-proofread: 校对选定文本。
• ellama-improve-wording: 使用 Ellama 改进当前选定区域或缓冲区中的措辞。
• ellama-improve-grammar: 使用 Ellama 改善当前选定区域或缓冲区中的语法和拼写。
• ellama-improve-conciseness: 使用 Ellama 使当前选定区域或缓冲区中的文本更加简洁明了。
• ellama-make-format: 使用 Ellama 将当前选定文本或缓冲区中的文本渲染为指定格式。
• ellama-load-session: 从文件加载 Ellama 会话。
• ellama-session-delete: 删除 Ellama 会话。
• ellama-session-switch: 切换当前活动会话。
• ellama-session-kill: 选择并终止一个活动会话。
• ellama-session-rename: 重命名当前 Ellama 会话。
• ellama-context-add-file: 将文件添加到上下文中。
• ellama-context-add-directory: 将目录中的所有文件添加到上下文中。
• ellama-context-add-buffer: 将缓冲区添加到上下文中。
• ellama-context-add-selection: 将选定区域添加到上下文中。
• ellama-context-add-info-node: 将 Info 节点添加到上下文中。
• ellama-context-reset: 清除全局上下文。
• ellama-context-manage: 管理全局上下文。在上下文管理缓冲区中，你可以查看 Ellama 上下文元素。可用的操作及快捷键绑定如下：
  • n: 移动到下一行。
  • p: 移动到上一行。
  • q: 关闭窗口。
  • g: 更新上下文管理缓冲区。
  • a: 打开临时上下文菜单以添加新元素。
  • d: 移除当前点的上下文元素。
  • RET: 预览当前点的上下文元素。
• ellama-context-preview-element-at-point: 预览当前点的 Ellama 上下文元素。仅在 Ellama 上下文管理缓冲区中有效。
• ellama-context-remove-element-at-point: 从全局上下文中移除当前点的 Ellama 上下文元素。仅在 Ellama 上下文管理缓冲区中有效。
• ellama-chat-translation-enable: 启用聊天翻译。
• ellama-chat-translation-disable: 禁用聊天翻译。
• ellama-solve-reasoning-problem: 使用“思维抽象”技术解决推理问题。该方法通过向 LLM 发送一系列消息，帮助其更好地回答推理问题。即使是 phi3-mini 等小型 LLM，在使用 AoT 技术后，也能在推理任务上取得更好的效果。
• ellama-solve-domain-specific-problem: 使用简单链式方法解决特定领域的问题。这种方法让 LLM 表现得像专业人士一样，并增加了一个规划步骤。
• ellama-community-prompts-select-blueprint: 从社区提示集中选择一个提示。系统会提示用户选择一个角色，然后将相应的提示插入蓝图缓冲区。
• ellama-blueprint-fill-variables: 提示用户填写当前蓝图缓冲区中变量的值，并更新这些变量。
• ellama-tools-enable-by-name: 通过名称启用特定工具。使用此命令可以激活单个工具，需要输入工具名称。
• ellama-tools-enable-all: 一次性启用所有可用工具。使用此命令可以激活系统中的每一个工具，实现全面的功能，而无需手动选择。
• ellama-tools-disable-by-name: 通过名称禁用特定工具。当某个工具的功能不再需要时，可以使用此命令将其停用。
• ellama-tools-disable-all: 同时禁用所有已启用的工具。使用此命令可以将系统重置为最小状态，确保没有任何工具处于活动状态。

• 键位映射

建议使用临时菜单（M-x ellama）而不是键位映射，这样用户体验更好。

在任何正在进行 Ellama 流式传输的缓冲区中，按下 C-g 即可取消当前流。

以下是 Ellama 中使用 ellama-keymap-prefix 前缀（默认未设置）的键位绑定及其对应功能的表格：

| 键位 | 功能 | 描述 | |--------+---------------------------------+------------------------------| | "w" | ellama-write | 写作 | | "c c" | ellama-code-complete | 代码补全 | | "c a" | ellama-code-add | 添加代码 | | "c e" | ellama-code-edit | 编辑代码 | | "c i" | ellama-code-improve | 改进代码 | | "c r" | ellama-code-review | 代码评审 | | "c m" | ellama-generate-commit-message | 生成提交信息 | | "s s" | ellama-summarize | 概括 | | "s w" | ellama-summarize-webpage | 概括网页 | | "s c" | ellama-summarize-killring | 概括剪贴板内容 | | "s l" | ellama-load-session | 加载会话 | | "s r" | ellama-session-rename | 重命名会话 | | "s d" | ellama-session-delete | 删除会话 | | "s a" | ellama-session-switch | 切换会话激活状态 | | "P" | ellama-proofread | 校对 | | "i w" | ellama-improve-wording | 改善措辞 | | "i g" | ellama-improve-grammar | 改善语法和拼写 | | "i c" | ellama-improve-conciseness | 提高简洁性 | | "m l" | ellama-make-list | 制作列表 | | "m t" | ellama-make-table | 制作表格 | | "m f" | ellama-make-format | 制作格式 | | "a a" | ellama-ask-about | 询问 | | "a i" | ellama-chat | 聊天（交互式提问） | | "a l" | ellama-ask-line | 询问当前行 | | "a s" | ellama-ask-selection | 询问选区 | | "t t" | ellama-translate | 文本翻译 | | "t b" | ellama-translate-buffer | 翻译缓冲区 | | "t e" | ellama-chat-translation-enable | 启用翻译功能 | | "t d" | ellama-chat-translation-disable | 禁用翻译功能 | | "t c" | ellama-complete | 文本补全 | | "d w" | ellama-define-word | 查词典 | | "x b" | ellama-context-add-buffer | 添加缓冲区上下文 | | "x f" | ellama-context-add-file | 添加文件上下文 | | "x d" | ellama-context-add-directory | 添加目录上下文 | | "x s" | ellama-context-add-selection | 添加选区上下文 | | "x i" | ellama-context-add-info-node | 添加 Info 节点上下文 | | "x r" | ellama-context-reset | 重置上下文 | | "p s" | ellama-provider-select | 选择服务提供商 |

• 配置

以下变量可以针对 Ellama 客户端进行自定义：

• ellama-enable-keymap: 启用 Ellama 键位映射。
• ellama-keymap-prefix: Ellama 的键位前缀。
• ellama-user-nick: 日志中的用户昵称。
• ellama-assistant-nick: 日志中的助手昵称。
• ellama-language: Ollama 翻译使用的语言。默认语言为英语。
• ellama-provider: Ellama 使用的 LLM 提供商。支持的提供商众多，包括 ollama、open ai、vertex 和 GPT4All。更多信息请参阅 [[https://elpa.gnu.org/packages/llm.html][llm 文档]]。
• ellama-providers: 模型与 LLM 提供商的关联列表，以名称为键。
• ellama-spinner-enabled: 在文本生成过程中启用加载动画。
• ellama-spinner-type: Ellama 的加载动画类型。默认类型为 progress-bar。
• ellama-auto-scroll: 如果启用，Ellama 缓冲区将在生成过程中自动滚动。默认关闭。
• ellama-fill-paragraphs: 自定义 Ellama 段落填充行为的选项。
• ellama-response-process-method: 配置 LLM 响应的处理方式。选项包括流式传输以实现实时输出、异步处理，或每隔 N 条消息跳过一次以减少资源消耗。
• ellama-name-prompt-words-count: 用于生成名称的提示词数量。
• 每个命令的提示模板。
• ellama-chat-done-callback: Ellama 聊天响应生成完成后调用的回调函数。它应该是一个接受单个参数（生成的文本字符串）的函数。
• ellama-nick-prefix-depth: 用户和助手昵称前缀的深度。默认值为 2。
• ellama-sessions-directory: 保存 Ellama 会话的目录。
• ellama-major-mode: Ellama 命令的主要模式。默认为 Org 模式。
• ellama-session-auto-save: 如果设置，则自动保存 Ellama 会话。默认开启。
• ellama-naming-scheme: 新会话的命名方式。
• ellama-naming-provider: 用于由 LLM 生成会话名称的 LLM 提供商。如果未设置，则使用 ellama-provider。
• ellama-chat-translation-enabled: 如果设置，则启用聊天翻译。
• ellama-translation-provider: LLM 翻译提供商。如果未设置，则使用 ellama-provider。
• ellama-coding-provider: LLM 编程任务提供商。如果未设置，则使用 ellama-provider。
• ellama-summarization-provider: LLM 总结提供商。如果未设置，则使用 ellama-provider。
• ellama-show-quotes: 在聊天缓冲区中显示引用内容。默认关闭。
• ellama-chat-display-action-function: ellama-chat 的显示操作函数。
• ellama-instant-display-action-function: ellama-instant 的显示操作函数。
• ellama-translate-italic: 在 Markdown 到 Org 的转换过程中翻译斜体文本。默认开启。
• ellama-extraction-provider: 用于数据提取的 LLM 提供商。
• ellama-text-display-limit: 上下文元素中文本显示的限制。
• ellama-context-poshandler: 上下文缓冲区显示的位置处理器。如果未设置，则使用 posframe-poshandler-frame-top-center。
• ellama-context-border-width: 上下文缓冲区的边框宽度。
• ellama-session-remove-reasoning: 在 Ellama 提供答案后，移除会话中的内部推理。这可以改善与推理模型的长期沟通。默认开启。
• ellama-session-hide-org-quotes: 在 Ellama 会话缓冲区中隐藏 Org 引用。从现在起，思考标签将被引用块取代。如果启用此标志，推理步骤将在生成后以及会话加载时折叠起来。默认开启。
• ellama-output-remove-reasoning: 从 Ellama 输出中消除内部推理，以增强推理模型在各种应用中的通用性。
• ellama-context-posframe-enabled: 启用显示带有 Ellama 上下文的 posframe。
• ellama-context-manage-display-action-function: ellama-context-manage 的显示操作函数。默认值为 display-buffer-same-window。
• ellama-context-preview-element-display-action-function: ellama-context-preview-element 的显示操作函数。
• ellama-context-line-always-visible: 使上下文头或模式行始终可见，即使上下文为空。
• ellama-community-prompts-url: 社区提示集合的 URL。
• ellama-community-prompts-file: 包含社区提示的 CSV 文件路径。该文件应位于您的 user-emacs-directory 中的 ellama 子目录内。
• ellama-show-reasoning: 如果启用，则在单独的缓冲区中显示推理过程。默认开启。
• ellama-reasoning-display-action-function: 推理过程的显示操作函数。
• ellama-session-line-template: 当前会话行的格式化模板。
• ellama-debug: 启用调试模式。启用后，生成的文本将被记录到 ellama-debug 缓冲区，并使用分隔符以便于跟踪调试信息。调试输出包括正在处理的原始文本，并且每次都会追加到调试缓冲区的末尾。
• ellama-tools-allow-all: 允许 ellama 在无需用户确认的情况下使用所有工具。此举存在风险，请自行承担后果。
• ellama-tools-allowed: 允许使用的 ellama 工具列表。此列表中的工具无需用户确认即可运行。
• ellama-tools-argument-max-length: 确认提示中函数参数的最大长度。默认值为 50。
• ellama-tools-use-srt: 通过外部 srt 沙盒运行环境执行基于 Shell 的工具（shell_command、grep 和 grep_in_file）。默认关闭。如果启用，非 Shell 文件工具也会根据相同的 srt 设置文件进行本地文件系统检查，以保持行为一致。目前，本地检查强制执行文件系统子集 denyRead、allowWrite 和 denyWrite，适用于 read_file、write_file、edit_file、directory_tree、move_file、count_lines 和 lines_range 等工具。如果启用但未安装 srt，或相关 srt 设置文件缺失或格式错误，则工具调用将触发用户错误（故障安全机制）。
• ellama-tools-srt-program: 当 ellama-tools-use-srt 启用时使用的沙盒运行程序名称/路径。默认值为 "srt"。
• ellama-tools-srt-args: 在包装命令之前传递给 srt 的额外参数（例如 --settings /path/to/settings.json）。这些参数也用于解析本地非 Shell 文件系统检查的设置文件路径（默认为 =/.srt-settings.json=，若未提供 --settings/-s~ 则使用）。
• ellama-blueprint-global-dir: 存储蓝图文件的全局目录。
• ellama-blueprint-local-dir: 项目特定蓝图的本地目录名。
• ellama-blueprint-file-extensions: 被识别为蓝图文件的文件扩展名。
• ellama-blueprint-variable-regexp: 用于匹配蓝图变量（如 {var_name}）的正则表达式。
• ellama-skills-global-path: 包含 Agent Skills 的全局目录路径。
• ellama-skills-local-path: 项目相关的本地 Agent Skills 路径。默认值为 "skills"。
• ellama-tools-subagent-default-max-steps: 子代理自动继续步骤的默认最大数量。默认值为 30。
• ellama-tools-subagent-roles: 子代理的角色，包括提供商、系统提示和允许使用的工具。这是为 task 工具配置子代理的方式。

** 工具输入/输出的 DLP

Ellama 包含一个可选的工具调用数据丢失防护（DLP）层。它可以扫描：

• 工具输入（从模型发送到工具的参数）
• 工具输出（从工具返回给模型的字符串）

DLP 层支持基于正则表达式的规则，以及从环境变量中提取的精确秘密检测（包括常见的编码变体，如 base64/base64url 和 hex）。它还包含一个可选的基于 LLM 的语义检查，作为仅针对块级别的一种后备机制，用于处理那些看起来不安全但不符合确定性规则的有效载荷。

推荐的初始部署方案：

• 启用 DLP
• 将模式设置为 monitor
• 在将选定路径切换到 enforce 之前，先审查事件
• 如果启用 LLM 检测器，应从一个小的工具白名单开始

最小化示例配置：

#+BEGIN_SRC emacs-lisp (setopt ellama-tools-dlp-enabled t) (setopt ellama-tools-dlp-mode 'monitor) (setopt ellama-tools-dlp-log-targets '(memory)) #+END_SRC

关键设置：

• ellama-tools-dlp-enabled：启用对工具输入/输出的 DLP 扫描。
• ellama-tools-dlp-mode：部署模式。使用 monitor 只进行检测和日志记录，或使用 enforce 来执行操作。
• ellama-tools-dlp-regex-rules：正则表达式检测规则（ID、模式、方向/工具/参数范围、启用/禁用、大小写折叠）。
• ellama-tools-dlp-scan-env-exact-secrets：从环境变量中启用精确秘密检测（默认启用）。
• ellama-tools-dlp-llm-check-enabled：启用可选的隔离 LLM 安全分类器（默认禁用）。
• ellama-tools-dlp-llm-provider：用于隔离 LLM 安全检查的服务提供商。当为 nil 时，会回退到提取服务提供商，然后是默认提供商。
• ellama-tools-dlp-llm-directions：LLM 检测器可能运行的方向（input、output，或两者）。
• ellama-tools-dlp-llm-max-scan-size：LLM 检测器可以处理的最大字节数。超过此限制的有效载荷将跳过 LLM 检查。
• ellama-tools-dlp-llm-tool-allowlist：允许使用 LLM 检测器的工具名称列表。如果为 nil，则所有工具都符合条件。
• ellama-tools-dlp-llm-run-policy：仅在确定性检测结果为空时运行 LLM 检测器（clean-only），或在每次未被阻止的扫描中都运行（always-unless-blocked）。
• ellama-tools-dlp-max-scan-size：每次输入/输出有效载荷扫描的最大字节数（默认 5 MB；较大的有效载荷会被截断以供扫描）。
• ellama-tools-dlp-input-default-action：在 enforce 模式下，输入检测结果的默认动作（allow、warn、block）。
• ellama-tools-dlp-output-default-action：在 enforce 模式下，输出检测结果的默认动作（allow、warn、block、redact）。
• ellama-tools-dlp-output-warn-behavior：输出 warn 判决的处理方式（allow、confirm 或 block）。
• ellama-tools-dlp-policy-overrides：按工具/按参数的覆盖和例外情况。对于结构化的输入参数，嵌套的字符串值会使用类似路径的参数名进行扫描（例如 payload.items[0].token）。覆盖 :arg 会匹配精确名称和嵌套路径前缀（例如 "payload" 会匹配 payload.items[0].token）。
• ellama-tools-dlp-log-targets：事件日志目标（memory、message、file）。
• ellama-tools-dlp-audit-log-file：当启用 file 接收器时使用的 JSONL 路径。
• ellama-tools-dlp-incident-log-max：保留的最大内存事件数量。
• ellama-tools-dlp-input-fail-open / ellama-tools-dlp-output-fail-open：当 DLP 自身发生内部错误时的行为。
• ellama-tools-irreversible-enabled：启用不可逆操作处理。
• ellama-tools-irreversible-default-action：默认的不可逆操作（warn 或 block，同时将监控模式降级为 warn-strong）。
• ellama-tools-irreversible-unknown-tool-action：未知 MCP 工具的默认动作（warn 或 allow）。
• ellama-tools-irreversible-require-typed-confirm：要求输入特定短语才能解除不可逆警告。
• ellama-tools-irreversible-project-overrides-enabled：启用项目本地的不可逆覆盖政策。
• ellama-tools-irreversible-project-overrides-file：项目政策文件名。
• ellama-tools-irreversible-project-trust-store-file：用于存储仓库批准记录的用户信任库（仓库根目录 + 远程地址 + 政策哈希）。
• ellama-tools-irreversible-scoped-bypass-default-ttl：会话绕过条目的默认 TTL（秒）。
• ellama-tools-output-line-budget-enabled：在将文本返回给模型之前，启用按工具的输出行预算截断（默认启用）。
• ellama-tools-output-line-budget-max-lines：每个工具输出的最大行数（默认 200）。
• ellama-tools-output-line-budget-max-line-length：在单行被截断之前，每行的最大字符数（默认 4000）。
• ellama-tools-output-line-budget-save-overflow-file：当输出源文件未知时，将完整的溢出输出保存到临时文件中（默认 t）。

强制执行行为（v1）：

• 输入 block 会阻止工具执行
• 输入 warn 会在执行前要求明确确认
• 输出 block 会返回一条安全的拒绝字符串
• 输出 redact 会用占位符替换检测到的片段
• 输出 warn 遵循 ellama-tools-dlp-output-warn-behavior（默认为 confirm）

LLM 安全检查行为（v1）：

• LLM 检测器仅在 ellama-tools-dlp-llm-check-enabled 不为 nil 时运行
• 检查器使用一个隔离的结构化输出请求，且不涉及任何工具
• 在 monitor 模式下，不安全的 LLM 判决会被记录，但不会改变结果
• 在 enforce 模式下，不安全的 LLM 判决可能会导致 block
• LLM 检测结果绝不会触发 warn 或 redact，也不会影响内容的编辑。

不可逆行动安全（v1）：

• 不可逆警告使用 warn-strong，并要求输入确认短语 我明白这无法撤销
• 在 enforce 模式下，高置信度的不可逆检测结果会直接 block
• 在 monitor 模式下，高置信度的不可逆检测结果仍然需要输入确认，且不会直接 block
• 未知 MCP 工具的身份默认为 warn（可通过 ellama-tools-irreversible-unknown-tool-action 进行配置）
• 不可逆决策的优先顺序：高置信度强制阻断 > 会话绕过 > 项目覆盖 > 全局不可逆默认
• 项目覆盖在仓库政策被明确信任之前会被忽略；信任与仓库根目录、远程 URL 和政策哈希绑定在一起
• 不可逆决策的审计日志写入失败时会采取闭锁措施；在交互式会话中，可以通过一次额外的明确确认来覆盖这一决定。

会话绕过助手：

#+BEGIN_SRC emacs-lisp ;; 允许在此会话中对一个工具身份执行不可逆操作。 (ellama-tools-dlp-add-session-bypass "mcp-db/query" 3600 "migration window") #+END_SRC

自主代理配置：

自主代理需要一种低摩擦的策略。在每次普通的工具调用时都提示用户确认，反而会让用户养成盲目批准的习惯，这比采用少量高信号的提示要糟糕得多。推荐的配置如下：

• 在批准的工作空间内，干净的读写操作会自动执行
• 秘密泄露和类似提示注入的输出会被屏蔽或阻止
• 模糊不清的危险操作需要用户键入确认，否则将采取失败封闭机制
• 高置信度的破坏性操作会被直接阻止，不会弹出确认提示
• 未知的MCP工具会发出警告，直到它们被分类

ellama-tools-allow-all仅绕过正常的确认包装层。它并不会绕过DLP、不可逆操作检查、输出扫描或srt文件系统检查，因为DLP已经包裹了确认层。这使得allow-all仅在启用DLP强制执行且工具文件系统访问受限时才适用。

自主编码的推荐基线：

#+BEGIN_SRC emacs-lisp (with-eval-after-load 'ellama-tools ;; 让干净的调用无需重复提示即可运行。 (setopt ellama-tools-allow-all t)

;; 必要的安全层。
(setopt ellama-tools-dlp-enabled t)
(setopt ellama-tools-dlp-mode 'enforce)

;; 偏好失败封闭行为以进行自主操作。
(setopt ellama-tools-dlp-input-fail-open nil)
(setopt ellama-tools-dlp-output-fail-open nil)

;; 保持秘密和输出保护措施处于激活状态。
(setopt ellama-tools-dlp-scan-env-exact-secrets t)
(setopt ellama-tools-dlp-input-default-action 'warn)
(setopt ellama-tools-dlp-output-default-action 'redact)

;; 不可逆操作需要更强的意图确认。
(setopt ellama-tools-irreversible-enabled t)
(setopt ellama-tools-irreversible-default-action 'warn)
(setopt ellama-tools-irreversible-require-typed-confirm t)

;; 保持遥测数据足够持久以便调整。
(setopt ellama-tools-dlp-log-targets '(memory file))

;; 强烈建议在启用`ellama-tools-allow-all'时使用。
(setopt ellama-tools-use-srt t)
(setopt ellama-tools-srt-args
        '("--settings" "~/.config/ellama/srt-autonomous.json")))

#+END_SRC

使用一个只允许在当前项目和临时区域中写入的srt策略。为秘密、凭证、审计日志和系统路径添加明确的读写拒绝规则。请参阅SRT文件系统策略工具部分中的项目沙箱示例。

对于危险情况，有两种合理的策略。由用户处理的危险情况仅要求DLP警告和不可逆操作确认：

#+BEGIN_SRC emacs-lisp (setopt ellama-tools-dlp-input-default-action 'warn) (setopt ellama-tools-dlp-output-warn-behavior 'confirm) (setopt ellama-tools-irreversible-default-action 'warn) (setopt ellama-tools-irreversible-require-typed-confirm t) #+END_SRC

中等风险的不可逆操作需要输入确认短语“我理解这无法撤销”。高置信度的破坏性操作在enforce模式下仍会被阻止，即使有会话或项目的覆盖设置也无法改变这一结果。

安全回退机制更适合无人值守的代理：

#+BEGIN_SRC emacs-lisp (setopt ellama-tools-dlp-input-default-action 'block) (setopt ellama-tools-dlp-output-warn-behavior 'block) (setopt ellama-tools-irreversible-default-action 'block) (setopt ellama-tools-irreversible-require-typed-confirm t) #+END_SRC

采用安全回退机制时，代理会收到拒绝信息，并需寻找更安全的路径。这样可以避免将用户确认变成例行公事式的批准习惯。

通过收紧工具角色而非削弱安全性来减少提示疲劳。避免为自主子代理使用~:tools :all~。优先选择以下独立角色：

• 只读探索者，不含shell_command
• 具有文件工具和沙盒化shell_command的编码员
• 仅当任务明确需要Shell访问时才使用Bash角色
• 除非有意中断用户，否则不使用ask_user工具

对于MCP工具，初始将ellama-tools-irreversible-unknown-tool-action设置为warn。观察常见安全工具后，可通过ellama-tools-irreversible-tool-risk-overrides或受信任的项目覆盖来分类可信工具身份。仅对特定工具身份和较短的TTL使用ellama-tools-dlp-add-session-bypass；切勿为减少提示而全局禁用DLP。

如果srt不可用，则不要为自主编码使用全局的ellama-tools-allow-all。应改用一个包含少量安全只读工具的ellama-tools-allowed列表，并将可能产生变化的工具置于确认或DLP回退机制之下。

工具输出截断行为：

• 每个工具的输出负载都会应用行预算
• 如果负载超过行预算，模型会收到截断通知以及被截断的部分内容
• 如果行数超过ellama-tools-output-line-budget-max-line-length，这些行会被缩短，并标注为~...[行被截断]~
• 当来源已知时（例如read_file、lines_range、grep_in_file），通知会包含源路径，并建议使用lines_range和grep_in_file/grep
• 当来源未知时（例如通用工具输出），完整输出会被保存到临时文件中（如果启用），并在通知中注明文件名。

正则表达式规则示例：

#+BEGIN_SRC emacs-lisp (setopt ellama-tools-dlp-regex-rules '((:id "openai-key" :pattern "sk-[[:alnum:]-]+" :directions (input output)) (:id "pem-header" :pattern "-----BEGIN [A-Z ]+-----" :directions (output) :enabled t))) #+END_SRC

范围覆盖示例（忽略嘈杂的Shell命令输入）：

#+BEGIN_SRC emacs-lisp (setopt ellama-tools-dlp-policy-overrides '((:tool "shell_command" :direction input :arg "cmd" :except t))) #+END_SRC

结构化输入负载的覆盖示例（顶级参数前缀匹配）：

#+BEGIN_SRC emacs-lisp (setopt ellama-tools-dlp-policy-overrides '((:tool "write_file" :direction input :arg "content" :action warn))) #+END_SRC

调优辅助工具：

• M-x ellama-tools-dlp-reset-runtime-state
• M-x ellama-tools-dlp-show-incident-stats
• (ellama-tools-dlp-recent-incidents)
• (ellama-tools-dlp-incident-stats)
• (ellama-tools-dlp-incident-stats-report)

事件统计包括按风险等级、规则ID、工具身份和决策类型（包括bypass）的汇总。

有关更详细的部署/调优指南及更多覆盖示例，请参阅docs/dlp_rollout_guide.md。

故障排除：

• 反复出现不可逆操作警告：使用ellama-tools-irreversible-tool-risk-overrides对可信MCP工具进行分类，或为单一工具身份使用短期会话绕过
• 绕过到期：会话绕过按TTL到期并自动移除；必要时可使用ellama-tools-dlp-add-session-bypass重新添加
• 误报：通过ellama-tools-dlp-recent-incidents检查事件，并在将更多路径转为强制执行之前调整正则规则或覆盖设置

** SRT文件系统工具策略

当ellama-tools-use-srt为非空时，srt设置文件是工具文件系统策略的真实依据：

• 基于 shell 的工具（shell_command、grep、grep_in_file）由外部的 srt 运行时强制执行。
• 非 shell 文件工具（read_file、write_file、append_file、prepend_file、edit_file、directory_tree、move_file、count_lines、lines_range）应用源自同一 srt 设置文件的本地检查。

当前支持的本地文件系统子集：

• filesystem.denyRead
• filesystem.allowWrite
• filesystem.denyWrite（优先于 allowWrite）

对于不可逆的审计加固，应将 ellama-tools-dlp-audit-log-file 置于 allowWrite 之外，并为审计目录添加明确的 denyRead/denyWrite 条目。

本地检查会故意忽略无关的 srt 键（例如 network.*）。如果 filesystem 部分缺失，本地检查将使用与 srt 相同的文件系统访问默认值：默认允许读取，而写入则被拒绝，除非被 allowWrite 允许。

本地检查的路径匹配说明：

• srt 规则中的相对路径会相对于 Emacs 的 default-directory 解析。
• ~~ 会扩展为当前用户的主目录。
• 支持字面路径、目录前缀规则和 glob 模式。
• 格式错误或不支持的模式会触发 user-error（失败即关闭）。

当 ellama-tools-use-srt 启用时，以下情况会导致本地检查失败并关闭：

• srt 未安装。
• 解析后的设置文件不存在。
• 设置文件是格式错误的 JSON。
• 相关的 filesystem 键的形状无效。

项目沙箱的 srt 配置示例：

#+BEGIN_SRC json { "network": { "allowedDomains": [ "github.com", ".github.com", "api.github.com", ".npmjs.org" ], "deniedDomains": [], "allowUnixSockets": [], "allowLocalBinding": false }, "filesystem": { "denyRead": [ "/.srt-settings.json", "/.ssh", "/.aws", "/.gnupg/", "/.config/gcloud/", "/.azure/", "/.kube/", "/.docker/", "/.netrc", "/.npmrc", "/.pypirc", "/.git-credentials", "/.emacs.d/ellama-dlp-audit.jsonl", ".env", ".env.", ".env.local", ".env", "-credentials.json", "serviceAccount.json", "service-account.json", "kubeconfig", "-secret.yaml", "secrets.yaml", ".pem", ".key", ".p12", ".pfx", ".tfstate", ".tfstate.backup", ".terraform/", ".vercel/", ".netlify/", ".supabase/", "dump.sql", "backup.sql", ".dump" ], "allowWrite": [ ".", "src/", "test/", "docs/", "/tmp/ellama-agent" ], "denyWrite": [ "/.srt-settings.json", "/.ssh", "/.aws", "/.gnupg/", "/.config/gcloud/", "/.azure/", "/.kube/", "/.docker/", "/.netrc", "/.npmrc", "/.pypirc", "/.git-credentials", "/.emacs.d/ellama-dlp-audit.jsonl", ".env", ".env.", ".env.local", ".env", "-credentials.json", "serviceAccount.json", "service-account.json", "kubeconfig", "-secret.yaml", "secrets.yaml", ".pem", ".key", ".p12", ".pfx", ".tfstate", ".tfstate.backup", ".terraform/", ".vercel/", ".netlify/", ".supabase/", "dump.sql", "backup.sql", ".dump", "/etc/", "/usr/", "/bin/", "/sbin/", "/boot/", "/root/", "/.bash_history", "/.zsh_history", "/.node_repl_history", "/.bashrc", "/.zshrc", "/.profile", "~/.bash_profile" ] }, "ignoreViolations": { "npm": [ "/private/tmp" ] }, "enableWeakerNestedSandbox": false, "enableWeakerNetworkIsolation": false } #+END_SRC

除非代理程序明确需要本地套接字，否则请保持 allowUnixSockets 为空。例如，添加 /var/run/docker.sock 将赋予沙箱广泛的 Docker 控制权限，因此应被视为特权能力。

Emacs 配置示例：

#+BEGIN_SRC emacs-lisp (setopt ellama-tools-use-srt t) (setopt ellama-tools-srt-args '("--settings" "/path/to/.srt-settings.json")) #+END_SRC

一致性测试（实际 srt 运行时 vs 本地 ellama 检查）：

• make test-srt-integration：运行主机一致性测试（需要安装 srt）。
• make test-srt-integration-linux：在 Linux 语义下通过 Docker 运行一致性测试。需要 Docker，并且会运行一个特权容器（--privileged）。

• 上下文管理

Ellama 允许您向大型语言模型（LLM）提供上下文，以提高响应的相关性和质量。上下文充当背景信息、数据或指令，引导 LLM 理解您的提示。如果没有上下文，LLM 将完全依赖其预先存在的知识，而这可能并不总是合适的。

Ellama 维护着一个“全局上下文”，它是由文本块组成的集合，在 LLM 回应提示时可供其访问。这个全局上下文会在发送给 LLM 之前附加到您的提示中。此外，Ellama 还支持“临时上下文”，它是暂时性的，仅适用于单次请求。

一些命令会自动将内容作为临时上下文添加：ellama-ask-about、ellama-code-review、ellama-write 和 ellama-code-add。

** 上下文管理的瞬态菜单

Ellama 提供了一个可通过主菜单访问的瞬态菜单，用于更便捷地管理上下文元素。该菜单可通过主瞬态菜单的“系统”分支进入，然后选择“上下文命令”。

上下文命令瞬态菜单的结构如下：

上下文命令：

• 选项：提供管理临时上下文的选项。
  • “-e” “使用临时上下文” --ephemeral
• 添加：提供将内容添加到全局或临时上下文的选项。
  • “b” “添加缓冲区” ellama-transient-add-buffer
  • “d” “添加目录” ellama-transient-add-directory
  • “f” “添加文件” ellama-transient-add-file
  • “s” “添加选区” ellama-transient-add-selection
  • “i” “添加信息节点” ellama-transient-add-info-node
• 管理：提供管理全局上下文的选项。
  • “m” “管理上下文” ellama-context-manage — 打开上下文管理缓冲区。
  • “D” “删除元素” ellama-context-element-remove-by-name — 按名称删除元素。
  • “r” “上下文重置” ellama-context-reset — 清除整个全局上下文。
• 退出：（“q” “退出” transient-quit-one）— 关闭上下文命令瞬态菜单。

** 管理上下文

ellama-context-manage 会打开一个专用的缓冲区——上下文管理缓冲区——您可以在其中查看、修改和组织全局上下文。在此缓冲区内：

• n: 移动到下一个上下文元素。
• p: 移动到上一个上下文元素。
• q: 退出上下文管理缓冲区。
• g: 刷新上下文管理缓冲区的内容。
• a: 添加一个新的上下文元素（类似于 ellama-context-add-selection）。
• RET: 预览当前点处的上下文元素内容。

** 注意事项

大型语言模型具有有限的上下文窗口大小，限制了它们可以处理的文本总量。请注意上下文的大小，以避免截断或性能下降。不相关的上下文会稀释信息，妨碍语言模型的关注度。确保上下文保持最新，以便获得准确的信息。通过尝试不同的上下文管理方法，可以针对特定用例优化性能。

• 小模式

Emacs 的 Ellama 包提供了一系列小模式，旨在通过在编辑器界面中直接提供上下文相关信息来增强用户体验。这些小模式专注于更新标题行和模式行中的相关细节，从而更轻松地管理和导航多个会话和缓冲区。

主要功能包括：

• 上下文标题行模式：ellama-context-header-line-mode 及其全局版本 ellama-context-header-line-global-mode 会更新标题行，以显示添加到全局 Ellama 上下文中的元素。这对于跟踪当前上下文中包含哪些信息非常有用。
• 上下文模式行模式：同样地，ellama-context-mode-line-mode 和 ellama-context-mode-line-global-mode 直接在模式行中提供有关当前全局上下文的信息，确保用户始终一目了然地掌握相关信息。
• 会话标题行模式：ellama-session-header-line-mode 及其全局版本会在标题行中显示当前的 Ellama 会话 ID，帮助用户高效管理多个会话。
• 会话模式行模式：ellama-session-mode-line-mode 及其全局版本则通过在模式行中显示会话 ID，提供了另一种跟踪会话 ID 的方式。

这些小模式可以通过特定命令轻松开启或关闭，为希望在所有缓冲区中全局启用这些功能，或仅在个别缓冲区中选择性启用的用户提供灵活性。

** ellama-context-header-line-mode

描述：切换 Ellama 上下文标题行模式。该小模式会更新标题行以显示上下文相关信息。

使用方法：要启用或禁用 ellama-context-header-line-mode，请使用以下命令：

M-x ellama-context-header-line-mode

启用后，此模式会向 window-state-change-hook 添加钩子，以便在窗口状态发生变化时更新标题行。它还会调用 ellama-context-update-header-line 来初始化标题行，显示上下文相关信息。

禁用时，它会从 header-line-format 中移除 (:eval (ellama-context-line)) 的评估。

** ellama-context-header-line-global-mode

描述：ellama-context-header-line-mode 的全局化版本。此模式确保在所有缓冲区中启用 ellama-context-header-line-mode。

使用方法：要启用或禁用 ellama-context-header-line-global-mode，请使用以下命令：

M-x ellama-context-header-line-global-mode

这个全局化的小模式提供了一种便捷的方式，无论正在编辑哪个缓冲区，都能确保始终显示上下文相关的标题行信息。

** ellama-context-mode-line-mode

描述：切换 Ellama 上下文模式行模式。该小模式会更新模式行以显示上下文相关信息。

使用方法：要启用或禁用 ellama-context-mode-line-mode，请使用以下命令：

M-x ellama-context-mode-line-mode

启用后，此模式会向 window-state-change-hook 添加钩子，以便在窗口状态发生变化时更新模式行。它还会调用 ellama-context-update-mode-line 来初始化模式行，显示上下文相关信息。

禁用时，它会从 mode-line-format 中移除 (:eval (ellama-context-line)) 的评估。

** ellama-context-mode-line-global-mode

描述：ellama-context-mode-line-mode 的全局化版本。此模式确保在所有缓冲区中启用 ellama-context-mode-line-mode。

使用方法：要启用或禁用 ellama-context-mode-line-global-mode，请使用以下命令：

M-x ellama-context-mode-line-global-mode

这个全局化的小模式提供了一种便捷的方法，无论编辑哪个缓冲区，都能确保始终显示上下文相关的模式行信息。

** Ellama 会话标题行模式

ellama-session-header-line-mode 是一种小模式，允许您在 Emacs 缓冲区的标题行中显示当前的 Ellama 会话 ID。此功能有助于跟踪您正在使用的会话，尤其是在管理多个会话时非常有用。

*** 启用和禁用

要启用此模式，请使用以下命令： #+BEGIN_SRC emacs-lisp M-x ellama-session-header-line-mode #+END_SRC

这将切换标题行中会话 ID 的显示。您也可以通过以下命令在全球范围内所有缓冲区中启用或禁用它： #+BEGIN_SRC emacs-lisp M-x ellama-session-header-line-global-mode #+END_SRC

*** 自定义

会话 ID 使用名为 ellama-face 的可自定义面显示。您可以自定义此面以更改其外观。

** Ellama 会话模式行模式

ellama-session-mode-line-mode 是一种小模式，允许您在 Emacs 缓冲区的模式行中显示当前的 Ellama 会话 ID。此功能提供了另一种跟踪您正在使用的会话的方式，尤其在管理多个会话时非常有用。

*** 启用和禁用

要启用此模式，请使用以下命令： #+BEGIN_SRC emacs-lisp M-x ellama-session-mode-line-mode #+END_SRC

这将切换模式行中会话 ID 的显示。您也可以通过以下命令在全球范围内所有缓冲区中启用或禁用它： #+BEGIN_SRC emacs-lisp M-x ellama-session-mode-line-global-mode #+END_SRC

*** 自定义

会话 ID 使用名为 ellama-face 的可自定义面显示。您可以自定义此面以更改其外观。

• 使用蓝图

Ellama 中的蓝图是指预定义的模板或结构，用于促进聊天会话的创建和管理。这些蓝图旨在通过提供交互的结构化框架，简化生成一致且高质量输出的过程。

** Ellama 蓝图的关键组成部分

1. 行动：这是蓝图的主要标识符，代表蓝图的动作或目的。
2. 提示：用于启动聊天会话的内容。这可以包括指令、上下文或其他任何引导对话所需的相关信息。
3. 适用于开发者：一个标志，指示该蓝图是否面向开发者。

** 创建和管理蓝图

Ellama 提供了多个功能来创建、选择和管理蓝图：

• ellama-blueprint-create：此函数允许用户从当前缓冲区创建一个新的蓝图。它会提示输入名称以及该蓝图是否面向开发者，然后将当前缓冲区的内容保存为提示。

• ellama-blueprint-new：此函数会创建一个新的蓝图缓冲区，如果当前区域被选中，则可以选择插入该区域的内容。

• ellama-blueprint-select：此函数允许用户从蓝图集合中选择一个提示。它会根据提示是否面向开发者及其来源（用户自定义、社区或全部）进行过滤。

** 蓝图文件

你也可以将蓝图存储为纯文本文件。可以在全局范围内存储在 ellama-blueprint-global-dir 目录下，或者在项目本地目录 ellama-blueprint-local-dir 中，使用 ellama-blueprint-file-extensions 扩展名。

** 变量管理

蓝图可以包含在运行聊天会话之前需要填充的变量。Ellama 提供了填充这些变量的命令：

• ellama-blueprint-fill-variables：提示用户输入当前缓冲区中找到的变量值，并进行填充。

** 键位映射和模式

Ellama 为缓冲区内管理蓝图提供了一个局部键位映射 ellama-blueprint-mode-map。该模式包括将缓冲区发送到新的聊天会话、杀死当前缓冲区、创建新蓝图以及填充变量等按键绑定。

ellama-blueprint-mode 是基于 text-mode 的派生模式，它为花括号中的变量提供语法高亮，并设置局部键位映射。

当处于 ellama-blueprint-mode 时，以下键位绑定可用：

• C-c C-c：将当前缓冲区发送到新的聊天会话并杀死当前缓冲区。
• C-c C-k：杀死当前缓冲区。
• C-c c：从当前缓冲区创建一个蓝图。
• C-c v：填充当前蓝图中的变量。

** 临时菜单

Ellama 包含临时菜单，方便访问蓝图相关命令。ellama-transient-blueprint-menu 提供了与选定蓝图聊天、创建新蓝图以及退出菜单的选项。

ellama-transient-main-menu 将蓝图菜单集成到主菜单中，为所有 Ellama 命令提供了一个全面的界面。

** 以编程方式运行蓝图

ellama-blueprint-run 函数使用指定的蓝图启动聊天会话。它会根据提供的参数预先填充变量。

#+BEGIN_SRC emacs-lisp (defun my-chat-with-morpheus () "开始与墨菲斯聊天。" (interactive) (ellama-blueprint-run "Character" '(:character "Morpheus" :series "Matrix")))

(global-set-key (kbd "C-c e M") #'my-chat-with-morpheus) #+END_SRC

• MCP 集成

你也可以将 MCP（模型上下文协议）工具与 ellama 一起使用。你需要 Emacs 30 或更高版本。安装 mcp.el - https://github.com/lizqwerscott/mcp.el。例如，要为 ellama 添加网页搜索功能，你可以添加 duckduckgo mcp 服务器（https://github.com/nickclyde/duckduckgo-mcp-server）：

#+begin_src emacs-lisp (use-package mcp :ensure t :demand t :custom (mcp-hub-servers `(("ddg" . (:command "uvx" :args ("duckduckgo-mcp-server"))))) :config (require 'mcp-hub) (mcp-hub-start-all-server (lambda () (let ((tools (mcp-hub-get-all-tool :asyncp t :categoryp t))) (mapcar #'(lambda (tool) (apply #'ellama-tools-define-tool (list tool))) tools))))) #+end_src

当使用 :categoryp t 时，ellama 会推导出稳定的 MCP 工具身份，格式为 /（例如 mcp-ddg/search）。不可逆的策略、审计和覆盖操作都以此身份为关键。

• 代理技能

Ellama 支持 代理技能，这是一种轻量级的扩展 AI 功能的格式。技能仅在需要时加载到上下文中（渐进式披露）。

** 目录结构

Ellama 会在两个位置查找技能：

1. 全局：=~/.emacs.d/ellama/skills/=（可通过 ellama-skills-global-path 自定义）
2. 项目本地：你的项目根目录下的 skills/ 目录（可通过 ellama-skills-local-path 自定义）

一个技能是一个包含 SKILL.md 文件的目录。该文件至少包含元数据（name 和 description）以及指示代理如何执行特定任务的说明。技能还可以捆绑脚本、模板和参考资料。

#+begin_src my-project/ └──skills/ └── pdf-processing/ ├── SKILL.md # 必需：说明 + 元数据 ├── scripts/ # 可选：可执行代码 ├── references/ # 可选：文档 └── assets/ # 可选：模板、资源 #+end_src

** 创建技能

SKILL.md 必须包含 YAML 前言：

#+begin_src markdown

---

name: pdf-processing description: 从 PDF 中提取文本并进行总结。

PDF 处理说明

要从 PDF 中提取文本... #+end_src

** 工作原理

自动发现：每当开始聊天时，Ellama 会自动扫描技能目录。上下文：技能的元数据（名称、描述、位置）会被注入到系统提示中。激活：LLM 会在需要时使用 read_file 工具加载 SKILL.md 的内容。

• 致谢

感谢 [[https://github.com/jmorganca][Jeffrey Morgan]] 的优秀项目 [[https://github.com/jmorganca/ollama][ollama]]。没有这个项目，本项目将无法存在。

感谢 [[https://github.com/zweifisch][zweifisch]] - 我从 [[https://github.com/zweifisch/ollama][ollama.el]] 中获得了一些关于 Emacs 中 ollama 客户端能做什么的想法。

感谢 [[https://github.com/David-Kunz][Dr. David A. Kunz]] - 我从 [[https://github.com/David-Kunz/gen.nvim][gen.nvim]] 中获得了更多灵感。

感谢 [[https://github.com/ahyatt][Andrew Hyatt]] 提供的 llm 库。如果没有它，就只能支持 ollama 了。

• 贡献

如需贡献，请提交拉取请求或报告错误。本库是 GNU ELPA 的一部分；重大贡献必须由持有 FSF 论文的人士提出。或者，你也可以编写模块并在其他仓库如 MELPA 上分享。

• GNU 自由文档许可证 :PROPERTIES: :APPENDIX: t :END:

#+texinfo: @include doclicense.texi

#+begin_export html

                GNU 自由文档许可证
                 第 1.3 版，2008 年 11 月 3 日


 版权所有 © 2000, 2001, 2002, 2007, 2008 自由软件基金会，美国
     
 每个人都有权复制和分发本许可证文件的完整副本，但不得对其进行修改。

0. 序言

本许可证的目的在于使手册、教科书或其他具有功能性和实用性的文档在自由的意义上成为“自由”文档：确保每个人都有权以复制和再分发该文档的实际自由，无论是否对其进行修改，也无论出于商业或非商业目的。其次，本许可证还为作者和出版者提供了一种方式，使其能够因其工作而获得应有的认可，同时不对其它人所做的修改承担责任。

本许可证属于一种“ copyleft ”许可证，这意味着该文档的衍生作品本身也必须以相同的方式保持自由。它与 GNU 通用公共许可证相辅相成，后者是专为自由软件设计的 copyleft 许可证。

我们设计本许可证的初衷是为了将其用于自由软件的手册，因为自由软件需要自由的文档：一个自由的程序应当附带提供与该软件同等自由的手册。然而，本许可证并不局限于软件手册；它可以用于任何文字作品，不论其主题为何，也不论其是以印刷书籍形式出版还是以其他形式发布。我们主要建议将本许可证应用于以教学或参考为目的的作品。


1. 适用范围与定义

本许可证适用于任何媒介上的手册或其他作品，只要其中包含由版权所有者放置的声明，表明该作品可根据本许可证的条款进行分发。此类声明授予一项全球性的、免版税的、无限期的许可，允许根据本许可证中规定的条件使用该作品。“文档”指代上述任何手册或作品。任何公众成员均为被许可人，并在本许可证中被称为“您”。如果您以需要依据版权法获得许可的方式复制、修改或分发该作品，则视为您已接受本许可证。

“修改版本”是指包含文档或其部分内容的作品，无论是完全照搬原文，还是经过修改和/或翻译成另一种语言。

“次要部分”是指文档中专门讨论文档的出版者或作者与其整体主题（或相关事项）之间关系的附录或前言部分，且不包含任何可以直接归入该整体主题的内容。（例如，如果文档部分是数学教材，则次要部分不得解释任何数学内容。）这种关系可以是与主题或相关事项的历史渊源，也可以是在法律、商业、哲学、伦理或政治等方面的相关立场。

“不变部分”是指在声明文档依据本许可证发布时，被指定为不变部分的某些次要部分。如果某一部分不符合上述关于次要部分的定义，则不得被指定为不变部分。文档可以不包含任何不变部分。如果文档未明确指出任何不变部分，则视为不存在不变部分。

“封面文字”是指在声明文档依据本许可证发布时，被列为前封面文字或后封面文字的若干简短文本段落。前封面文字不得超过5个词，后封面文字不得超过25个词。

“透明”副本是指以机器可读格式呈现的文档副本，其格式规范向公众公开，适合使用通用文本编辑器直接编辑文档，或（对于由像素组成的图像）使用通用绘图程序进行编辑，或（对于绘图）使用广泛可用的绘图编辑软件进行编辑；并且适合输入到文本排版程序中，或自动转换为多种可用于文本排版程序的格式。如果副本采用看似透明的文件格式，但其标记语言或缺乏标记语言的设计旨在阻止或抑制读者后续修改，则该副本不被视为“透明”。若图像格式被用于表示大量文本，则该图像格式也不属于“透明”格式。非“透明”的副本被称为“不透明”副本。

适合用作“透明”副本的格式包括：无标记的纯 ASCII 文本、Texinfo 输入格式、LaTeX 输入格式、使用公开可用 DTD 的 SGML 或 XML，以及符合标准的简单 HTML、PostScript 或 PDF，这些格式专为人工修改而设计。透明图像格式的例子包括 PNG、XCF 和 JPG。不透明格式则包括只能由专有文字处理软件读取和编辑的专有格式，以及 DTD 和/或处理工具并不普遍可用的 SGML 或 XML，还有某些文字处理软件仅用于输出而生成的机器自动生成的 HTML、PostScript 或 PDF。

“扉页”对于印刷书籍而言，是指书的扉页本身，加上为清晰地载明本许可证要求出现在扉页上的信息所需的后续页面。对于没有传统意义上的扉页的作品，“扉页”是指靠近作品标题最显著位置的文本，位于正文开始之前。

“出版者”是指向公众分发文档副本的任何个人或实体。

“标题为 XYZ 的部分”是指文档中名称为 XYZ 的子单元，或者其标题中包含 XYZ，且在括号内注明了 XYZ 在另一种语言中的译文。（此处 XYZ 代表下文中提到的具体部分名称，如“致谢”、“献词”、“推荐语”或“历史”等。）在修改文档时“保留该部分的标题”，是指按照本定义，该部分仍应被视为“标题为 XYZ 的部分”。

文档可以在声明本许可证适用于该文档的公告旁包含免责声明。这些免责声明被视为通过引用纳入本许可证，但仅限于免除担保责任的部分；除此之外，这些免责声明可能具有的任何其他含义均无效，且对本许可证的含义不产生影响。

2. 原样复制

您可以在任何媒介上复制并分发文档，无论是商业性还是非商业性，前提是所有副本中都必须完整地复制本许可证、版权声明以及声明本许可证适用于该文档的许可公告，并且您不得对该许可证所规定的条件附加任何其他限制。您不得使用技术手段来阻碍或控制他人阅读或进一步复制您制作或分发的副本。不过，您可以接受针对副本的报酬。如果您分发的副本数量足够多，则还必须遵守第3节的规定。

您还可以在上述相同条件下出借副本，并可公开展示副本。


3. 大量复制

如果您出版文档的印刷副本（或通常带有印刷封面的介质副本），数量超过100份，并且文档的许可声明要求包含封皮文字，您必须用封面将这些副本封装起来，封面上应清晰可辨地印上所有这些封皮文字：前封皮文字印在封面上，后封皮文字印在封底上。两面封皮还必须清楚且易于辨认地表明您是这些副本的出版者。前封皮必须完整呈现文档标题，且标题中的每个词都应同样突出、醒目。您还可以在封面上添加其他内容。只要封面所做的修改仅限于封面本身，同时保留文档标题并满足上述条件，这些修改在其他方面即可被视为原文复制。

如果任一封面所需的文本内容过多而无法清晰地容纳，您应当将列出的前若干条（在合理范围内尽可能多的条目）印在实际封面上，其余内容则延续至相邻页面。

如果您出版或分发超过100份文档的不透明副本，您必须在每一份不透明副本中附带一份机器可读的透明副本，或者在每份不透明副本中注明一个计算机网络地址，使广大网络用户能够通过公共标准网络协议免费下载一份不含附加内容的完整透明副本。如果您选择后一种方式，则在开始大量分发不透明副本时，您必须采取合理谨慎的措施，以确保该透明副本在所注明的地址上持续可用，直至自您最后一次直接或通过代理人、零售商向公众分发该版本的不透明副本之日起至少一年之后。

建议您在重新分发大量副本之前，尽早与文档作者取得联系，以便他们有机会为您提供文档的更新版本；但这并非强制性要求。

4. 修改

您可以在遵守上述第2节和第3节规定的前提下，复制并分发文档的修改版本，但前提是您必须以本许可证的完全相同条款发布修改版本，并使该修改版本取代原文档的地位，从而授权任何持有该修改版本副本的人对其进行分发和修改。此外，您还必须在修改版本中做到以下几点：

A. 在扉页（以及如有封面的话，在封面上）使用一个不同于原文档及先前各版本标题的标题（先前各版本的标题若存在，应在文档的历史部分列出）。若您获得该版本原出版者的许可，可以使用与先前版本相同的标题。
B. 在扉页上列出对修改版本负有责任的一位或多位个人或实体作为作者，并至少包括原文档的五位主要作者（若主要作者不足五位，则全部列出），除非这些作者免除您的此项义务。
C. 在扉页上注明修改版本的出版者名称，作为出版者。
D. 保留原文档的所有版权声明。
E. 在现有版权声明旁添加一条适当的版权声明，说明您对文档所做的修改。
F. 紧接版权声明之后，加入一份许可声明，以本许可证的条款允许公众使用修改版本，其格式见下文附录。
G. 在该许可声明中保留原文档许可声明中所列的不可变章节和必需封皮文字的完整清单。
H. 随附本许可证的未作修改的副本。
I. 保留名为“历史”的章节及其标题，并在其中增加一项内容，至少注明修改版本的标题、年份、新作者和出版者，这些信息均取自扉页。如果原文档中没有名为“历史”的章节，则需创建一个，注明文档的标题、年份、作者和出版者，这些信息同样取自扉页，然后再添加一项描述修改版本的内容，如前一句所述。
J. 保留原文档中为公众访问文档透明副本而提供的网络地址，以及文档中为其所依据的先前版本提供的网络地址。这些地址可以置于“历史”章节中。对于在其发布日期早于原文档至少四年的工作，或者如果其所指版本的原出版者给予许可，则您可以省略相应的网络地址。
K. 对于任何名为“致谢”或“献词”的章节，保留其标题，并保持该章节中所有贡献者致谢和/或献词的内容与语气不变。
L. 保留原文档的所有不可变章节，其内容和标题均不得更改。章节编号或类似标识不视为章节标题的一部分。
M. 删除任何名为“推荐”的章节。此类章节不得出现在修改版本中。
N. 不得将任何现有章节重新命名为“推荐”，也不得使其标题与任何不可变章节产生冲突。
O. 保留所有免责声明。

如果修改版本包含新的前置章节或附录，且这些章节符合次要章节的定义、不含从原文档复制的内容，您可以自行决定将其全部或部分指定为不可变章节。为此，您需要将这些章节的标题添加到修改版本许可声明中的不可变章节列表中。这些标题必须与其他章节标题有所区别。

您也可以添加一个名为“推荐”的章节，但该章节只能包含各方对您的修改版本的推荐——例如同行评审意见，或某组织认可该文本为某一标准的权威定义等。

您可以在修改版本封皮文字列表的末尾添加一段不超过5个字的前封皮文字，以及一段不超过25个字的后封皮文字。任何单一实体（或通过其安排）仅能添加一段前封皮文字和一段后封皮文字。如果原文档已经包含针对同一封皮的封皮文字，且该文字此前由您本人或您所代表的同一实体安排添加，则您不得再添加新的封皮文字；但在获得先前添加该文字的出版者的明确许可后，您可以替换原有文字。

根据本许可证，文档的作者和出版者并未授予您使用其姓名进行宣传，或声称、暗示其对任何修改版本予以认可的权利。

5. 文档合并

您可以根据上述第4节中关于修改版本的规定，将本文档与其他依据本许可证发布的文档合并，但须在合并后的作品中包含所有原始文档中未作修改的不可变章节，并在其许可声明中将其全部列为合并作品的不可变章节，同时保留所有免责声明。

合并后的作品只需包含一份本许可证副本，多个内容相同的不可变章节可以替换为单个副本。如果存在多个名称相同但内容不同的不可变章节，应通过在章节标题末尾加括号注明该章节的原作者或出版者（如已知）或一个唯一编号的方式使每个此类章节的标题具有唯一性。同样，还应对合并作品许可声明中不可变章节列表内的章节标题作出相应调整。

在合并过程中，您必须将各原始文档中标题为“历史”的章节合并成一个统一的“历史”章节；同样地，也将所有标题为“致谢”和“献词”的章节分别合并。您还必须删除所有标题为“ endorsements”的章节。


6. 文档汇编

您可以制作一个由本文档及其他依据本许可证发布的文档组成的汇编，并用汇编中包含的一份本许可证副本替换各个文档中的单独副本，但前提是您在其他方面仍需遵守本许可证关于逐字复制各文档的规定。

您也可以从此类汇编中提取单个文档，并依据本许可证单独分发该文档，但须在提取出的文档中插入一份本许可证副本，并在该文档的逐字复制方面完全遵循本许可证的其他规定。


7. 与独立作品的聚合

将本文档或其衍生作品与其他独立的文档或作品在存储或分发介质上组合成一个整体，称为“聚合体”，如果该组合所产生的著作权不用于限制聚合体使用者的合法权利，使其超出各个独立作品本身所允许的范围，则此组合被视为聚合体。当本文档被纳入聚合体时，本许可证并不适用于聚合体中那些并非本文档衍生作品的其他作品。

如果第3节关于封面文字的要求适用于这些文档副本，且本文档在聚合体中所占比例不足一半，则本文档的封面文字可以放置在包围文档的封面页上，或者在文档为电子形式时，放置于等效的电子封面之上。否则，封面文字必须出现在覆盖整个聚合体的印刷封面页上。


8. 翻译

翻译被视为一种修改形式，因此您可以在第4节规定的条件下分发本文档的译本。用译本替换不可变章节需要获得其版权所有者的特别许可，但您可以在这些不可变章节的原文之外，一并包含其部分或全部译本。您还可以包含本许可证及其在文档中出现的所有许可声明和免责声明的译本，但前提是必须同时附上本许可证的英文原文以及那些声明和免责声明的原文。若译本与本许可证、任何声明或免责声明的原文之间存在分歧，则以原文为准。

如果文档中的某一章节标题为“致谢”、“献词”或“历史”，则第4节中关于保持其标题不变的要求通常会要求更改实际标题。


9. 终止

除本许可证明确授权的情形外，您不得复制、修改、再许可或分发本文档。任何其他方式的复制、修改、再许可或分发行为均属无效，并将自动终止您依据本许可证享有的权利。

然而，如果您停止一切违反本许可证的行为，则您从特定版权所有者处获得的许可将被恢复：（a）暂时恢复，除非且直至该版权所有者明确且最终终止您的许可；（b）永久恢复，如果该版权所有者未能在您停止违规行为后的60天内以合理方式通知您有关违规行为。

此外，若您从某版权所有者处收到关于违反本许可证的通知，而这是您首次收到来自该版权所有者关于违反本许可证的通知（无论针对何种作品），并且您在收到通知后的30天内纠正了违规行为，则您从此版权所有者处获得的许可将被永久恢复。

本节规定的权利终止并不影响已从您处依据本许可证获得副本或相关权利的各方的许可。如果您的权利已被终止且未获永久恢复，则即使您再次获得相同材料的部分或全部副本，亦无权使用这些材料。


10. 本许可证的未来修订

自由软件基金会可能会不时发布GNU自由文档许可证的新修订版本。这些新版本的精神将与当前版本相似，但在细节上可能有所不同，以应对新的问题或关切。详情请参阅https://www.gnu.org/licenses/。

许可证的每一个版本都有其独特的版本号。如果文档明确规定“本许可证的某一指定版本或任何后续版本”适用于该文档，则您可以选择遵循该指定版本或自由软件基金会已正式发布（而非草稿）的任何后续版本的条款和条件。如果文档未指定本许可证的具体版本号，则您可以选择自由软件基金会以往正式发布过的任一版本（而非草稿）。如果文档规定由代理人决定可采用的未来版本，则该代理就某一版本公开发表的接受声明将永久授权您为该文档选用该版本。


11. 重新许可

“大规模多作者协作站点”（或“MMC站点”）是指任何发布受版权保护作品并同时提供显著编辑功能的万维网服务器。任何人都可编辑的公共维基就是此类服务器的一个例子。“大规模多作者协作”（或“MMC”）指在MMC站点上发布的任何一组受版权保护的作品。

“CC-BY-SA”是指知识共享组织发布的一份知识共享署名-相同方式共享3.0协议，该组织是一家非营利性机构，主要营业地点位于美国加利福尼亚州旧金山；同时也包括由同一组织发布的该协议未来的著佐权版本。

“纳入”是指将一份文档的全部或部分作为另一份文档的一部分进行出版或再出版。

如果一个MMC依据本许可证授权，并且所有最初在该MMC之外的其他地方依据本许可证首次发表、随后被全部或部分纳入该MMC的作品，同时满足以下两个条件：(1) 这些作品没有任何封面文字或不可变章节；(2) 它们是在2008年11月1日之前被纳入的，则该MMC即为“符合重新许可条件”。

在2009年8月1日之前，MMC站点的运营者可以在同一站点上以CC-BY-SA协议重新发布该站点中包含的MMC，前提是该MMC符合重新许可条件。


附录：如何将本许可证用于您的文档

要在您撰写的文档中使用本许可证，请在文档中附上一份许可证副本，并在扉页之后立即添加如下版权和许可声明：

    版权所有 ©  年份  您的名字。
    根据自由软件基金会发布的GNU自由文档许可证第1.3版或任何后续版本的条款，特此授予复制、分发和/或修改本文件的权限；
    本许可证无不可变章节、无前封面文字、无后封面文字。
    许可证全文载于名为“GNU自由文档许可证”的章节中。

如果您有不可变章节、前封面文字和后封面文字，请将“……文字。”一行替换为：

    其不可变章节为 列出其标题，前封面文字为 列出，后封面文字为 列出。

如果您只有不可变章节而没有封面文字，或者三者之间存在其他组合，请根据实际情况合并上述两种表述。

如果您的文档包含非 trivial 的程序代码示例，我们建议您同时依照您选择的自由软件许可证（例如GNU通用公共许可证）发布这些示例，以便它们能够在自由软件中被使用。

#+end_export

Ellama 快速上手指南

Ellama 是一款运行在 Emacs 编辑器中的大型语言模型（LLM）交互工具。它支持流式输出，可轻松实现翻译、代码审查、文本摘要、语法修正等功能。默认后端为 Ollama。

环境准备

在开始之前，请确保满足以下要求：

1. 操作系统：Linux, macOS 或 Windows (WSL)。
2. Emacs：建议版本 28.0 或更高，以支持最新的包管理和显示功能。
3. Ollama（默认依赖）：
   • Ellama 默认使用 Ollama 作为 LLM 提供者。
   • 安装 Ollama：访问官网下载对应系统的安装包，或在终端执行：

     curl -fsSL https://ollama.com/install.sh | sh
     

     (国内用户若下载缓慢，可尝试配置代理或使用国内镜像源)
   • 拉取模型：安装完成后，需至少拉取一个模型才能使用。例如拉取轻量级的 Qwen2.5 模型：

     ollama pull qwen2.5:3b
     

安装步骤

1. 通过 MELPA 安装 Ellama

启动 Emacs，执行以下命令安装 ellama 包：

1. 按下 M-x (Alt + x)。
2. 输入 package-install 并回车。
3. 输入 ellama 并回车。

(如果未配置 MELPA 源，请先在 init.el 中添加 MELPA 仓库地址)

2. 基础配置

将以下代码添加到你的 Emacs 配置文件（~/.emacs.d/init.el 或 ~/.config/emacs/init.el）中，以启用基本功能和快捷键：

(use-package ellama
  :ensure t
  :bind ("C-c e" . ellama) ;; 设置主快捷键为 C-c e
  ;; 可选：在 Org 模式下使用 C-c C-c 发送最后一条消息
  :hook (org-ctrl-c-ctrl-c-hook . ellama-chat-send-last-message)
  :init
  (setopt ellama-auto-scroll t) ;; 启用自动滚动
  :config
  ;; 在头部行显示上下文和会话 ID
  (ellama-context-header-line-global-mode +1)
  (ellama-session-header-line-global-mode +1))

重新加载配置文件或重启 Emacs 使配置生效。

基本使用

1. 启动交互菜单

按下快捷键 C-c e (或执行 M-x ellama)，将弹出 transient 主菜单。这是所有功能的入口。

2. 发起对话 (Chat)

• 命令：ellama-chat
• 操作：
  1. 在主菜单中选择 Chat 或直接执行 M-x ellama-chat。
  2. 在弹出的缓冲区中输入你的问题。
  3. Ellama 将调用本地 Ollama 模型并流式返回答案。
• 新建会话：使用前缀参数 C-u M-x ellama-chat 可以交互式地选择新的模型并开始新会话。

3. 常用场景示例

你可以选中一段文本（Region），然后通过 C-c e 菜单快速执行以下操作：

• 翻译：选中文本 -> C-c e -> Translate (默认翻译为目标语言，可在配置中设置 ellama-language)。
• 代码审查：选中代码 -> C-c e -> Code review。
• 解释内容：选中内容 -> C-c e -> Ask about。
• 润色文本：选中文本 -> C-c e -> Improve wording 或 Improve grammar。

4. 高级配置（可选）

如果需要指定特定模型（如区分聊天模型和代码模型），可在配置文件中添加如下设置：

(require 'llm-ollama)
(setopt ellama-provider
      (make-llm-ollama
       :chat-model "llama3:8b-instruct-q8_0"
       :embedding-model "nomic-embed-text"))
;; 为代码任务指定专用模型
(setopt ellama-coding-provider
      (make-llm-ollama
       :chat-model "qwen2.5-coder:3b"))

配置完成后，Ellama 会根据任务类型自动调用相应的模型。