[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-s-kostyaev--ellama":3,"tool-s-kostyaev--ellama":61},[4,17,27,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":16},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",160015,2,"2026-04-18T11:30:52",[13,14,15],"开发框架","Agent","语言模型","ready",{"id":18,"name":19,"github_repo":20,"description_zh":21,"stars":22,"difficulty_score":23,"last_commit_at":24,"category_tags":25,"status":16},8272,"opencode","anomalyco\u002Fopencode","OpenCode 是一款开源的 AI 编程助手（Coding Agent），旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件，而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码，还是排查难以定位的 Bug，OpenCode 都能通过自然语言交互高效完成，显著减少开发者在重复性劳动和上下文切换上的时间消耗。\n\n这款工具专为软件开发者、工程师及技术研究人员设计，特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构，这意味着用户可以审查代码逻辑、自定义行为策略，甚至私有化部署以保障数据安全，彻底打破了传统闭源 AI 助手的“黑盒”限制。\n\n在技术体验上，OpenCode 提供了灵活的终端界面（Terminal UI）和正在测试中的桌面应用程序，支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具，安装便捷，并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客，还是渴望提升产出的独立开发者，OpenCode 都提供了一个透明、可信",144296,1,"2026-04-16T14:50:03",[14,26],"插件",{"id":28,"name":29,"github_repo":30,"description_zh":31,"stars":32,"difficulty_score":10,"last_commit_at":33,"category_tags":34,"status":16},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[26,14,35,13],"图像",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":10,"last_commit_at":42,"category_tags":43,"status":16},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[26,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":50,"last_commit_at":51,"category_tags":52,"status":16},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,3,"2026-04-06T11:19:32",[15,35,14,13],{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":10,"last_commit_at":59,"category_tags":60,"status":16},8553,"spec-kit","github\u002Fspec-kit","Spec Kit 是一款专为提升软件开发效率而设计的开源工具包，旨在帮助团队快速落地“规格驱动开发”（Spec-Driven Development）模式。传统开发中，需求文档往往与代码实现脱节，导致沟通成本高且结果不可控；而 Spec Kit 通过将规格说明书转化为可执行的指令，让 AI 直接依据明确的业务场景生成高质量代码，从而减少从零开始的随意编码，确保产出结果的可预测性。\n\n该工具特别适合希望利用 AI 辅助编程的开发者、技术负责人及初创团队。无论是启动全新项目还是在现有工程中引入规范化流程，用户只需通过简单的命令行操作，即可初始化项目并集成主流的 AI 编程助手。其核心技术亮点在于“规格即代码”的理念，支持社区扩展与预设模板，允许用户根据特定技术栈定制开发流程。此外，Spec Kit 强调官方维护的安全性，提供稳定的版本管理，帮助开发者在享受 AI 红利的同时，依然牢牢掌握架构设计的主动权，真正实现从“凭感觉写代码”到“按规格建系统”的转变。",88749,"2026-04-17T09:48:14",[15,35,14,13],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":75,"owner_location":76,"owner_email":75,"owner_twitter":75,"owner_website":75,"owner_url":77,"languages":78,"stars":91,"forks":92,"last_commit_at":93,"license":94,"difficulty_score":50,"env_os":95,"env_gpu":96,"env_ram":97,"env_deps":98,"category_tags":105,"github_topics":75,"view_count":10,"oss_zip_url":75,"oss_zip_packed_at":75,"status":16,"created_at":106,"updated_at":107,"faqs":108,"releases":143},9098,"s-kostyaev\u002Fellama","ellama","Ellama is a tool for interacting with large language models from Emacs.","Ellama 是一款专为 Emacs 编辑器打造的大语言模型交互工具，旨在让用户无需离开熟悉的编辑环境，即可直接与 AI 进行对话和协作。它有效解决了开发者在编码、写作或查阅文档时需频繁切换窗口的痛点，将翻译、代码审查、文本摘要、语法润色等常用 AI 功能无缝集成到工作流中。\n\n这款工具特别适合重度依赖 Emacs 的开发者、技术作家及研究人员使用。无论是需要快速重构代码的程序员，还是希望提升写作效率的内容创作者，都能通过 Ellama 获得流畅的辅助体验。其核心亮点在于原生支持流式输出，确保回复实时呈现；同时具备高度可配置性，默认兼容 Ollama 本地模型，也支持 OpenAI 等多种后端，允许用户为聊天、编程或总结等不同任务指定专属模型。此外，Ellama 还能在界面头部动态显示上下文与会话信息，帮助用户更好地管理对话状态。作为一个由社区驱动的开源项目，Ellama 以轻量、灵活的方式，让强大的大模型能力真正融入日常编辑操作之中。","[[http:\u002F\u002Fwww.gnu.org\u002Flicenses\u002Fgpl-3.0.txt][file:https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-GPL_3-green.svg]]\n[[https:\u002F\u002Fmelpa.org\u002F#\u002Fellama][file:https:\u002F\u002Fmelpa.org\u002Fpackages\u002Fellama-badge.svg]]\n[[https:\u002F\u002Fstable.melpa.org\u002F#\u002Fellama][file:https:\u002F\u002Fstable.melpa.org\u002Fpackages\u002Fellama-badge.svg]]\n[[https:\u002F\u002Felpa.gnu.org\u002Fpackages\u002Fellama.html][file:https:\u002F\u002Felpa.gnu.org\u002Fpackages\u002Fellama.svg]]\n\nEllama is a tool for interacting with large language models from Emacs. It\nallows you to ask questions and receive responses from the LLMs. Ellama can\nperform various tasks such as translation, code review, summarization, enhancing\ngrammar\u002Fspelling or wording and more through the Emacs interface. Ellama\nnatively supports streaming output, making it effortless to use with your\npreferred text editor.\n\nThe name \"ellama\" is derived from \"Emacs Large LAnguage Model\nAssistant\". Previous sentence was written by Ellama itself.\n[[file:imgs\u002Freasoning-models.gif]]\n\n* Installation\n\nJust ~M-x~ ~package-install~ @@html:\u003Ckbd>@@Enter@@html:\u003C\u002Fkbd>@@ ~ellama~\n@@html:\u003Ckbd>@@Enter@@html:\u003C\u002Fkbd>@@. By default it uses\n[[https:\u002F\u002Fgithub.com\u002Fjmorganca\u002Follama][ollama]] provider. If you are OK with it,\nyou need to install [[https:\u002F\u002Fgithub.com\u002Fjmorganca\u002Follama][ollama]] and pull\n[[https:\u002F\u002Follama.com\u002Fmodels][any ollama model]] like this:\n\n#+BEGIN_SRC shell\n ollama pull qwen2.5:3b\n#+END_SRC\n\nYou can use ~ellama~ with other models or another LLM provider. Without any\nconfiguration, the first available ollama model will be used. You can customize\nellama configuration like this:\n\n#+BEGIN_SRC emacs-lisp\n (use-package ellama\n :ensure t\n :bind (\"C-c e\" . ellama)\n ;; send last message in chat buffer with C-c C-c\n :hook (org-ctrl-c-ctrl-c-hook . ellama-chat-send-last-message)\n :init (setopt ellama-auto-scroll t)\n :config\n ;; show ellama context in header line in all buffers\n (ellama-context-header-line-global-mode +1)\n ;; show ellama session id in header line in all buffers\n (ellama-session-header-line-global-mode +1))\n#+END_SRC\n\nMore sophisticated configuration example:\n\n#+BEGIN_SRC emacs-lisp\n (use-package ellama\n :ensure t\n :bind (\"C-c e\" . ellama)\n ;; send last message in chat buffer with C-c C-c\n :hook (org-ctrl-c-ctrl-c-hook . ellama-chat-send-last-message)\n :init\n ;; setup key bindings\n ;; (setopt ellama-keymap-prefix \"C-c e\")\n ;; language you want ellama to translate to\n (setopt ellama-language \"German\")\n ;; could be llm-openai for example\n (require 'llm-ollama)\n (setopt ellama-provider\n \t (make-llm-ollama\n \t ;; this model should be pulled to use it\n \t ;; value should be the same as you print in terminal during pull\n \t :chat-model \"llama3:8b-instruct-q8_0\"\n \t :embedding-model \"nomic-embed-text\"\n \t :default-chat-non-standard-params '((\"num_ctx\" . 8192))))\n (setopt ellama-summarization-provider\n \t (make-llm-ollama\n \t :chat-model \"qwen2.5:3b\"\n \t :embedding-model \"nomic-embed-text\"\n \t :default-chat-non-standard-params '((\"num_ctx\" . 32768))))\n (setopt ellama-coding-provider\n \t (make-llm-ollama\n \t :chat-model \"qwen2.5-coder:3b\"\n \t :embedding-model \"nomic-embed-text\"\n \t :default-chat-non-standard-params '((\"num_ctx\" . 32768))))\n ;; Predefined llm providers for interactive switching.\n ;; You shouldn't add ollama providers here - it can be selected interactively\n ;; without it. It is just example.\n (setopt ellama-providers\n \t '((\"zephyr\" . (make-llm-ollama\n \t\t\t :chat-model \"zephyr:7b-beta-q6_K\"\n \t\t\t :embedding-model \"zephyr:7b-beta-q6_K\"))\n \t (\"mistral\" . (make-llm-ollama\n \t\t\t :chat-model \"mistral:7b-instruct-v0.2-q6_K\"\n \t\t\t :embedding-model \"mistral:7b-instruct-v0.2-q6_K\"))\n \t (\"mixtral\" . (make-llm-ollama\n \t\t\t :chat-model \"mixtral:8x7b-instruct-v0.1-q3_K_M-4k\"\n \t\t\t :embedding-model \"mixtral:8x7b-instruct-v0.1-q3_K_M-4k\"))))\n ;; Naming new sessions with llm\n (setopt ellama-naming-provider\n \t (make-llm-ollama\n \t :chat-model \"llama3:8b-instruct-q8_0\"\n \t :embedding-model \"nomic-embed-text\"\n \t :default-chat-non-standard-params '((\"stop\" . (\"\\n\")))))\n (setopt ellama-naming-scheme 'ellama-generate-name-by-llm)\n ;; Translation llm provider\n (setopt ellama-translation-provider\n \t (make-llm-ollama\n \t :chat-model \"qwen2.5:3b\"\n \t :embedding-model \"nomic-embed-text\"\n \t :default-chat-non-standard-params\n \t '((\"num_ctx\" . 32768))))\n (setopt ellama-extraction-provider (make-llm-ollama\n \t\t\t\t :chat-model \"qwen2.5-coder:7b-instruct-q8_0\"\n \t\t\t\t :embedding-model \"nomic-embed-text\"\n \t\t\t\t :default-chat-non-standard-params\n \t\t\t\t '((\"num_ctx\" . 32768))))\n ;; customize display buffer behaviour\n ;; see ~(info \"(elisp) Buffer Display Action Functions\")~\n (setopt ellama-chat-display-action-function #'display-buffer-full-frame)\n (setopt ellama-instant-display-action-function #'display-buffer-at-bottom)\n :config\n ;; show ellama context in header line in all buffers\n (ellama-context-header-line-global-mode +1)\n ;; show ellama session id in header line in all buffers\n (ellama-session-header-line-global-mode +1)\n ;; handle scrolling events\n (advice-add 'pixel-scroll-precision :before #'ellama-disable-scroll)\n (advice-add 'end-of-buffer :after #'ellama-enable-scroll))\n#+END_SRC\n\n* Commands\n\n- ~ellama~: This is the entry point for Ellama. It displays the main transient\n menu, allowing you to access all other Ellama commands from here.\n- ~ellama-chat~: Ask Ellama about something by entering a prompt in an\n interactive buffer and continue conversation. If called with universal\n argument (~C-u~) will start new session with llm model interactive selection.\n- ~ellama-write~: This command allows you to generate text using an LLM. When\n called interactively, it prompts for an instruction that is then used to\n generate text based on the context. If a region is active, the selected text\n is added to ephemeral context before generating the response.\n- ~ellama-chat-send-last-message~: Send last user message extracted from current\n ellama chat buffer.\n- ~ellama-ask-about~: Ask Ellama about a selected region or the current\n buffer. Automatically adds selected region or current buffer to ephemeral\n context for one request.\n- ~ellama-ask-selection~: Send selected region or current buffer to ellama chat.\n- ~ellama-ask-line~: Send current line to ellama chat.\n- ~ellama-complete~: Complete text in current buffer with ellama.\n- ~ellama-translate~: Ask Ellama to translate a selected region or word at the\n point.\n- ~ellama-translate-buffer~: Translate current buffer.\n- ~ellama-define-word~: Find the definition of the current word using Ellama.\n- ~ellama-summarize~: Summarize a selected region or the current buffer using\n Ellama.\n- ~ellama-summarize-killring~: Summarize text from the kill ring.\n- ~ellama-code-review~: Review code in a selected region or the current buffer\n using Ellama. Automatically adds selected region or current buffer to\n ephemeral context for one request.\n- ~ellama-change~: Change text in a selected region or the current buffer\n according to a provided change.\n- ~ellama-make-list~: Create a markdown list from the active region or the\n current buffer using Ellama.\n- ~ellama-make-table~: Create a markdown table from the active region or the\n current buffer using Ellama.\n- ~ellama-summarize-webpage~: Summarize a webpage fetched from a URL using\n Ellama.\n- ~ellama-provider-select~: Select ellama provider.\n- ~ellama-code-complete~: Complete selected code or code in the current buffer\n according to a provided change using Ellama.\n- ~ellama-code-add~: Generate and insert new code based on description. This\n function prompts the user to describe the code they want to generate. If a\n region is active, it includes the selected text in ephemeral context for code\n generation.\n- ~ellama-code-edit~: Change selected code or code in the current buffer\n according to a provided change using Ellama.\n- ~ellama-code-improve~: Change selected code or code in the current buffer\n according to a provided change using Ellama.\n- ~ellama-generate-commit-message~: Generate commit message based on diff.\n- ~ellama-proofread~: Proofread selected text.\n- ~ellama-improve-wording~: Enhance the wording in the currently selected region\n or buffer using Ellama.\n- ~ellama-improve-grammar~: Enhance the grammar and spelling in the currently\n selected region or buffer using Ellama.\n- ~ellama-improve-conciseness~: Make the text of the currently selected region\n or buffer concise and simple using Ellama.\n- ~ellama-make-format~: Render the currently selected text or the text in the\n current buffer as a specified format using Ellama.\n- ~ellama-load-session~: Load ellama session from file.\n- ~ellama-session-delete~: Delete ellama session.\n- ~ellama-session-switch~: Change current active session.\n- ~ellama-session-kill~: Select and kill one of active sessions.\n- ~ellama-session-rename~: Rename current ellama session.\n- ~ellama-context-add-file~: Add file to context.\n- ~ellama-context-add-directory~: Add all files in directory to the context.\n- ~ellama-context-add-buffer~: Add buffer to context.\n- ~ellama-context-add-selection~: Add selected region to context.\n- ~ellama-context-add-info-node~: Add info node to context.\n- ~ellama-context-reset~: Clear global context.\n- ~ellama-context-manage~: Manage the global context. Inside context management\n buffer you can see ellama context elements. Available actions with key\n bindings:\n - ~n~: Move to the next line.\n - ~p~: Move to the previous line.\n - ~q~: Quit the window.\n - ~g~: Update context management buffer.\n - ~a~: Open the transient context menu for adding new elements.\n - ~d~: Remove the context element at the current point.\n - ~RET~: Preview the context element at the current point.\n- ~ellama-context-preview-element-at-point~: Preview ellama context element at\n point. Works inside ellama context management buffer.\n- ~ellama-context-remove-element-at-point~: Remove ellama context element at\n point from global context. Works inside ellama context management buffer.\n- ~ellama-chat-translation-enable~: Enable chat translation.\n- ~ellama-chat-translation-disable~: Disable chat translation.\n- ~ellama-solve-reasoning-problem~: Solve reasoning problem with Abstraction of\n Thought technique. It uses a chain of multiple messages to an LLM and helps it\n to provide much better answers on reasoning problems. Even small LLMs like\n phi3-mini provide much better results on reasoning tasks using AoT.\n- ~ellama-solve-domain-specific-problem~: Solve domain specific problem with\n simple chain. It makes LLMs act like a professional and adds a planning step.\n- ~ellama-community-prompts-select-blueprint~: Select a prompt from the\n community prompt collection. The user is prompted to choose a role, and then a\n corresponding prompt is inserted into a blueprint buffer.\n- ~ellama-blueprint-fill-variables~: Prompt user for values of variables found\n in current blueprint buffer and update them.\n- ~ellama-tools-enable-by-name~: Enable a specific tool by its name. Use this\n command to activate individual tools. Requires the tool name as input.\n- ~ellama-tools-enable-all~: Enable all available tools at once. Use this\n command to activate every tool in the system for comprehensive functionality\n without manual selection.\n- ~ellama-tools-disable-by-name~: Disable a specific tool by its name. Use this\n command to deactivate individual tools when their functionality is no longer\n needed.\n- ~ellama-tools-disable-all~: Disable all enabled tools simultaneously. Use this\n command to reset the system to a minimal state, ensuring no tools are active.\n\n* Keymap\n\nIt's better to use a transient menu (~M-x ellama~) instead of a keymap. It\noffers a better user experience.\n\nIn any buffer where there is active ellama streaming, you can press ~C-g~ and it\nwill cancel current stream.\n\nHere is a table of keybindings and their associated functions in Ellama, using\nthe ~ellama-keymap-prefix~ prefix (not set by default):\n\n| Keymap | Function | Description |\n|--------+---------------------------------+------------------------------|\n| \"w\" | ellama-write | Write |\n| \"c c\" | ellama-code-complete | Code complete |\n| \"c a\" | ellama-code-add | Code add |\n| \"c e\" | ellama-code-edit | Code edit |\n| \"c i\" | ellama-code-improve | Code improve |\n| \"c r\" | ellama-code-review | Code review |\n| \"c m\" | ellama-generate-commit-message | Generate commit message |\n| \"s s\" | ellama-summarize | Summarize |\n| \"s w\" | ellama-summarize-webpage | Summarize webpage |\n| \"s c\" | ellama-summarize-killring | Summarize killring |\n| \"s l\" | ellama-load-session | Session Load |\n| \"s r\" | ellama-session-rename | Session rename |\n| \"s d\" | ellama-session-delete | Session delete |\n| \"s a\" | ellama-session-switch | Session activate |\n| \"P\" | ellama-proofread | Proofread |\n| \"i w\" | ellama-improve-wording | Improve wording |\n| \"i g\" | ellama-improve-grammar | Improve grammar and spelling |\n| \"i c\" | ellama-improve-conciseness | Improve conciseness |\n| \"m l\" | ellama-make-list | Make list |\n| \"m t\" | ellama-make-table | Make table |\n| \"m f\" | ellama-make-format | Make format |\n| \"a a\" | ellama-ask-about | Ask about |\n| \"a i\" | ellama-chat | Chat (ask interactively) |\n| \"a l\" | ellama-ask-line | Ask current line |\n| \"a s\" | ellama-ask-selection | Ask selection |\n| \"t t\" | ellama-translate | Text translate |\n| \"t b\" | ellama-translate-buffer | Translate buffer |\n| \"t e\" | ellama-chat-translation-enable | Translation enable |\n| \"t d\" | ellama-chat-translation-disable | Translation disable |\n| \"t c\" | ellama-complete | Text complete |\n| \"d w\" | ellama-define-word | Define word |\n| \"x b\" | ellama-context-add-buffer | Context add buffer |\n| \"x f\" | ellama-context-add-file | Context add file |\n| \"x d\" | ellama-context-add-directory | Context add directory |\n| \"x s\" | ellama-context-add-selection | Context add selection |\n| \"x i\" | ellama-context-add-info-node | Context add info node |\n| \"x r\" | ellama-context-reset | Context reset |\n| \"p s\" | ellama-provider-select | Provider select |\n\n* Configuration\n\nThe following variables can be customized for the Ellama client:\n\n- ~ellama-enable-keymap~: Enable the Ellama keymap.\n- ~ellama-keymap-prefix~: The keymap prefix for Ellama.\n- ~ellama-user-nick~: The user nick in logs.\n- ~ellama-assistant-nick~: The assistant nick in logs.\n- ~ellama-language~: The language for Ollama translation. Default\nlanguage is english.\n- ~ellama-provider~: llm provider for ellama.\nThere are many supported providers: ~ollama~, ~open ai~, ~vertex~,\n~GPT4All~. For more information see\n[[https:\u002F\u002Felpa.gnu.org\u002Fpackages\u002Fllm.html][llm documentation]].\n- ~ellama-providers~: association list of model llm providers with name as key.\n- ~ellama-spinner-enabled~: Enable spinner during text generation.\n- ~ellama-spinner-type~: Spinner type for ellama. Default type is\n ~progress-bar~.\n- ~ellama-auto-scroll~: If enabled ellama buffer will scroll automatically\n during generation. Disabled by default.\n- ~ellama-fill-paragraphs~: Option to customize ellama paragraphs filling\n behaviour.\n- ~ellama-response-process-method~: Configure how LLM responses are processed.\n Options include streaming for real-time output, async for asynchronous\n processing, or skipping every N messages to reduce resource usage.\n- ~ellama-name-prompt-words-count~: Count of words in prompt to generate name.\n- Prompt templates for every command.\n- ~ellama-chat-done-callback~: Callback that will be called on ellama\nchat response generation done. It should be a function with single argument\ngenerated text string.\n- ~ellama-nick-prefix-depth~: User and assistant nick prefix depth. Default\n value is 2.\n- ~ellama-sessions-directory~: Directory for saved ellama sessions.\n- ~ellama-major-mode~: Major mode for ellama commands. Org mode by default.\n- ~ellama-session-auto-save~: Automatically save ellama sessions if set. Enabled\n by default.\n- ~ellama-naming-scheme~: How to name new sessions.\n- ~ellama-naming-provider~: LLM provider for generating session names by LLM. If\n not set ~ellama-provider~ will be used.\n- ~ellama-chat-translation-enabled~: Enable chat translations if set.\n- ~ellama-translation-provider~: LLM translation provider. ~ellama-provider~\n will be used if not set.\n- ~ellama-coding-provider~: LLM coding tasks provider. ~ellama-provider~ will\n be used if not set.\n- ~ellama-summarization-provider~: LLM summarization provider.\n ~ellama-provider~ will be used if not set.\n- ~ellama-show-quotes~: Show quotes content in chat buffer. Disabled by default.\n- ~ellama-chat-display-action-function~: Display action function for\n ~ellama-chat~.\n- ~ellama-instant-display-action-function~: Display action function for\n ~ellama-instant~.\n- ~ellama-translate-italic~: Translate italic during markdown to org\n transformations. Enabled by default.\n- ~ellama-extraction-provider~: LLM provider for data extraction.\n- ~ellama-text-display-limit~: Limit for text display in context elements.\n- ~ellama-context-poshandler~: Position handler for displaying context buffer.\n ~posframe-poshandler-frame-top-center~ will be used if not set.\n- ~ellama-context-border-width~: Border width for the context buffer.\n- ~ellama-session-remove-reasoning~: Remove internal reasoning from the session\n after ellama provide an answer. This can improve long-term communication with\n reasoning models. Enabled by default.\n- ~ellama-session-hide-org-quotes~: Hide org quotes in the Ellama session\n buffer. From now on, think tags will be replaced with quote blocks. If this\n flag is enabled, reasoning steps will be collapsed after generation and upon\n session loading. Enabled by default.\n- ~ellama-output-remove-reasoning~: Eliminate internal reasoning from ellama\n output to enhance the versatility of reasoning models across diverse\n applications.\n- ~ellama-context-posframe-enabled~: Enable showing posframe with ellama\n context.\n- ~ellama-context-manage-display-action-function~: Display action function for\n ~ellama-context-manage~. Default value ~display-buffer-same-window~.\n- ~ellama-context-preview-element-display-action-function~: Display action\n function for ~ellama-context-preview-element~.\n- ~ellama-context-line-always-visible~: Make context header or mode line always\n visible, even with empty context.\n- ~ellama-community-prompts-url~: The URL of the community prompts collection.\n- ~ellama-community-prompts-file~: Path to the CSV file containing community\n prompts. This file is expected to be located inside an ~ellama~ subdirectory\n within your ~user-emacs-directory~.\n- ~ellama-show-reasoning~: Show reasoning in separate buffer if enabled. Enabled\n by default.\n- ~ellama-reasoning-display-action-function~: Display action function for\n reasoning.\n- ~ellama-session-line-template~: Template for formatting the current session\n line.\n- ~ellama-debug~: Enable debug. When enabled, generated text is now logged to a\n ~*ellama-debug*~ buffer with a separator for easier tracking of debug\n information. The debug output includes the raw text being processed and is\n appended to the end of the debug buffer each time.\n- ~ellama-tools-allow-all~: Allow ~ellama~ using all the tools without user\n confirmation. Dangerous. Use at your own risk.\n- ~ellama-tools-allowed~: List of allowed ~ellama~ tools. Tools from this list\n will work without user confirmation.\n- ~ellama-tools-argument-max-length~: Max length of function argument in the\n confirmation prompt. Default value 50.\n- ~ellama-tools-use-srt~: Run shell-based tools (~shell_command~, ~grep~ and\n ~grep_in_file~) via the external ~srt~ sandbox runtime. Disabled by default.\n If enabled, non-shell file tools also perform local filesystem checks derived\n from the same ~srt~ settings file to keep behavior aligned. The local checks\n currently enforce the filesystem subset ~denyRead~, ~allowWrite~ and\n ~denyWrite~ for tools such as ~read_file~, ~write_file~, ~edit_file~,\n ~directory_tree~, ~move_file~, ~count_lines~ and ~lines_range~. If enabled\n and ~srt~ is not installed, or the relevant ~srt~ settings file is missing or\n malformed, the tool call signals a user error (fail closed).\n- ~ellama-tools-srt-program~: Sandbox runtime executable name\u002Fpath used when\n ~ellama-tools-use-srt~ is enabled. Default value is ~\"srt\"~.\n- ~ellama-tools-srt-args~: Extra arguments passed to ~srt~ before the wrapped\n command (for example ~--settings \u002Fpath\u002Fto\u002Fsettings.json~). The same arguments\n are also used to resolve the settings file path for local non-shell filesystem\n checks (default =~\u002F.srt-settings.json= if no ~--settings~\u002F~-s~ is provided).\n- ~ellama-blueprint-global-dir~: Global directory for storing blueprint files.\n- ~ellama-blueprint-local-dir~: Local directory name for project-specific\n blueprints.\n- ~ellama-blueprint-file-extensions~: File extensions recognized as blueprint\n files.\n- ~ellama-blueprint-variable-regexp~: Regular expression to match blueprint\n variables like ~{var_name}~.\n- ~ellama-skills-global-path~: Path to the global directory containing Agent\n Skills.\n- ~ellama-skills-local-path~: Project-relative path for local Agent Skills.\n Default value is ~\"skills\"~.\n- ~ellama-tools-subagent-default-max-steps~: Default maximum number of\n auto-continue steps for a sub-agent. Default value is 30.\n- ~ellama-tools-subagent-roles~: Subagent roles with provider, system prompt and\n allowed tools. Configuration of subagents for the ~task~ tool.\n\n** DLP for Tool Input\u002FOutput\n\nEllama includes an optional DLP (Data Loss Prevention) layer for tool calls. It\ncan scan:\n\n- tool input (arguments sent from the model to tools)\n- tool output (strings returned from tools back to the model)\n\nThe DLP layer supports regex-based rules and exact secret detection derived from\nenvironment variables (including common encoded variants such as\nbase64\u002Fbase64url and hex). It also includes an optional LLM-based semantic\ncheck as a block-only backstop for payloads that look unsafe but do not match a\ndeterministic rule.\n\nRecommended initial rollout:\n\n- enable DLP\n- keep mode in ~monitor~\n- review incidents before switching selected paths to ~enforce~\n- if enabling the LLM detector, start with a small tool allowlist\n\nExample minimal setup:\n\n#+BEGIN_SRC emacs-lisp\n (setopt ellama-tools-dlp-enabled t)\n (setopt ellama-tools-dlp-mode 'monitor)\n (setopt ellama-tools-dlp-log-targets '(memory))\n#+END_SRC\n\nKey settings:\n\n- ~ellama-tools-dlp-enabled~: Enable DLP scanning for tool input\u002Foutput.\n- ~ellama-tools-dlp-mode~: Rollout mode. Use ~monitor~ for detect+log only, or\n ~enforce~ to apply actions.\n- ~ellama-tools-dlp-regex-rules~: Regex detector rules (IDs, patterns,\n direction\u002Ftool\u002Farg scoping, enable\u002Fdisable, case folding).\n- ~ellama-tools-dlp-scan-env-exact-secrets~: Enable exact-secret detection from\n environment variables (enabled by default).\n- ~ellama-tools-dlp-llm-check-enabled~: Enable the optional isolated LLM safety\n classifier (disabled by default).\n- ~ellama-tools-dlp-llm-provider~: Provider used for the isolated LLM safety\n check. When nil, it falls back to the extraction provider, then the default\n provider.\n- ~ellama-tools-dlp-llm-directions~: Directions where the LLM detector may run\n (~input~, ~output~, or both).\n- ~ellama-tools-dlp-llm-max-scan-size~: Maximum bytes eligible for the LLM\n detector. Payloads above this limit are skipped for the LLM pass.\n- ~ellama-tools-dlp-llm-tool-allowlist~: Optional list of tool names allowed to\n use the LLM detector. Nil means all tools are eligible.\n- ~ellama-tools-dlp-llm-run-policy~: Run the LLM detector only when\n deterministic findings are empty (~clean-only~) or on every non-blocked scan\n (~always-unless-blocked~).\n- ~ellama-tools-dlp-max-scan-size~: Maximum bytes scanned per input\u002Foutput\n payload (default 5 MB; larger payloads are truncated for scanning).\n- ~ellama-tools-dlp-input-default-action~: Default action for input findings in\n ~enforce~ mode (~allow~, ~warn~, ~block~).\n- ~ellama-tools-dlp-output-default-action~: Default action for output findings\n in ~enforce~ mode (~allow~, ~warn~, ~block~, ~redact~).\n- ~ellama-tools-dlp-output-warn-behavior~: Handling for output ~warn~ verdicts\n (~allow~, ~confirm~, or ~block~).\n- ~ellama-tools-dlp-policy-overrides~: Per-tool\u002Fper-arg overrides and\n exceptions. For structured input args, nested string values are scanned with\n path-like arg names (for example ~payload.items[0].token~). Override ~:arg~\n matches exact names and nested path prefixes (for example ~\"payload\"~ matches\n ~payload.items[0].token~).\n- ~ellama-tools-dlp-log-targets~: Incident log targets (~memory~, ~message~,\n ~file~).\n- ~ellama-tools-dlp-audit-log-file~: JSONL path used when ~file~ sink is\n enabled.\n- ~ellama-tools-dlp-incident-log-max~: Maximum in-memory incidents retained.\n- ~ellama-tools-dlp-input-fail-open~ \u002F ~ellama-tools-dlp-output-fail-open~:\n Behavior when DLP itself errors internally.\n- ~ellama-tools-irreversible-enabled~: Enable irreversible-action handling.\n- ~ellama-tools-irreversible-default-action~: Default irreversible action\n (~warn~ or ~block~, with monitor downgrade to ~warn-strong~).\n- ~ellama-tools-irreversible-unknown-tool-action~: Default action for unknown\n MCP tools (~warn~ or ~allow~).\n- ~ellama-tools-irreversible-require-typed-confirm~: Require typed phrase for\n irreversible warnings.\n- ~ellama-tools-irreversible-project-overrides-enabled~: Enable project-local\n irreversible override policy.\n- ~ellama-tools-irreversible-project-overrides-file~: Project policy file name.\n- ~ellama-tools-irreversible-project-trust-store-file~: User trust store for\n repository approval records (repo root + remote + policy hash).\n- ~ellama-tools-irreversible-scoped-bypass-default-ttl~: Default TTL (seconds)\n for session bypass entries.\n- ~ellama-tools-output-line-budget-enabled~: Enable per-tool output line-budget\n truncation before returning text to the model (enabled by default).\n- ~ellama-tools-output-line-budget-max-lines~: Max lines per tool output\n (default ~200~).\n- ~ellama-tools-output-line-budget-max-line-length~: Max characters per line\n before a single line is truncated (default ~4000~).\n- ~ellama-tools-output-line-budget-save-overflow-file~: Save full overflowing\n output to a temp file when the output source file is unknown (default ~t~).\n\nEnforcement behavior (v1):\n\n- input ~block~ prevents tool execution\n- input ~warn~ asks for explicit confirmation before execution\n- output ~block~ returns a safe denial string\n- output ~redact~ replaces detected fragments with placeholders\n- output ~warn~ follows ~ellama-tools-dlp-output-warn-behavior~ (~confirm~ by\n default)\n\nLLM safety check behavior (v1):\n\n- the LLM detector runs only when ~ellama-tools-dlp-llm-check-enabled~ is\n non-nil\n- the checker uses an isolated structured-output request with no tools\n- in ~monitor~, unsafe LLM verdicts are logged but do not change the result\n- in ~enforce~, an unsafe LLM verdict may force ~block~\n- LLM findings never trigger ~warn~ or ~redact~ and do not affect redaction\n\nIrreversible action safety (v1):\n\n- irreversible warnings use ~warn-strong~ with typed confirmation phrase ~I\n UNDERSTAND THIS CANNOT BE UNDONE~\n- in ~enforce~, high-confidence irreversible findings hard ~block~\n- in ~monitor~, high-confidence irreversible findings still require typed\n confirmation and do not hard block\n- unknown MCP tool identities default to ~warn~ (configurable via\n ~ellama-tools-irreversible-unknown-tool-action~)\n- policy precedence for irreversible decisions: ~high-confidence enforce block~\n > ~session bypass~ > ~project override~ > global irreversible default\n- project overrides are ignored until the repository policy is explicitly\n trusted; trust is bound to repo root, remote URL, and policy hash\n- audit sink write failure for irreversible decisions is fail-closed; in\n interactive sessions a separate explicit confirmation can override once\n\nSession bypass helper:\n\n#+BEGIN_SRC emacs-lisp\n ;; Allow irreversible actions for one tool identity in this session.\n (ellama-tools-dlp-add-session-bypass \"mcp-db\u002Fquery\" 3600 \"migration window\")\n#+END_SRC\n\nAutonomous agent configuration:\n\nAutonomous agents need a low-friction policy. Prompting on every ordinary tool\ncall trains users to approve blindly, which is worse than a smaller set of\nhigh-signal prompts. The recommended shape is:\n\n- clean read\u002Fwrite operations inside the approved workspace run automatically\n- secret leaks and prompt-injection-like output are redacted or blocked\n- ambiguous dangerous actions require typed user confirmation or fail closed\n- high-confidence destructive actions are blocked, not prompted\n- unknown MCP tools warn until they are classified\n\n~ellama-tools-allow-all~ only bypasses the normal confirmation wrapper. It does\nnot bypass DLP, irreversible-action checks, output scanning, or ~srt~ filesystem\nchecks because DLP wraps the confirmation layer. This makes ~allow-all~\nsuitable only when DLP enforcement is enabled and tool filesystem access is\nconstrained.\n\nRecommended baseline for autonomous coding:\n\n#+BEGIN_SRC emacs-lisp\n (with-eval-after-load 'ellama-tools\n ;; Let clean calls run without repetitive prompts.\n (setopt ellama-tools-allow-all t)\n\n ;; Required safety layer.\n (setopt ellama-tools-dlp-enabled t)\n (setopt ellama-tools-dlp-mode 'enforce)\n\n ;; Prefer fail-closed behavior for autonomous operation.\n (setopt ellama-tools-dlp-input-fail-open nil)\n (setopt ellama-tools-dlp-output-fail-open nil)\n\n ;; Keep secret and output protections active.\n (setopt ellama-tools-dlp-scan-env-exact-secrets t)\n (setopt ellama-tools-dlp-input-default-action 'warn)\n (setopt ellama-tools-dlp-output-default-action 'redact)\n\n ;; Irreversible actions require stronger intent.\n (setopt ellama-tools-irreversible-enabled t)\n (setopt ellama-tools-irreversible-default-action 'warn)\n (setopt ellama-tools-irreversible-require-typed-confirm t)\n\n ;; Keep telemetry durable enough to tune.\n (setopt ellama-tools-dlp-log-targets '(memory file))\n\n ;; Strongly recommended when `ellama-tools-allow-all' is enabled.\n (setopt ellama-tools-use-srt t)\n (setopt ellama-tools-srt-args\n '(\"--settings\" \"~\u002F.config\u002Fellama\u002Fsrt-autonomous.json\")))\n#+END_SRC\n\nUse an ~srt~ policy that allows writes only inside the current project and a\nscratch area. Add explicit read\u002Fwrite denials for secrets, credentials, audit\nlogs, and system paths. See the project sandbox example in the SRT Filesystem\nPolicy for Tools section.\n\nThere are two reasonable policies for dangerous cases. User-handled dangerous\ncases ask only for DLP warnings and irreversible actions:\n\n#+BEGIN_SRC emacs-lisp\n (setopt ellama-tools-dlp-input-default-action 'warn)\n (setopt ellama-tools-dlp-output-warn-behavior 'confirm)\n (setopt ellama-tools-irreversible-default-action 'warn)\n (setopt ellama-tools-irreversible-require-typed-confirm t)\n#+END_SRC\n\nMedium-risk irreversible actions require the typed confirmation phrase ~I\nUNDERSTAND THIS CANNOT BE UNDONE~. High-confidence destructive actions are\nstill blocked in ~enforce~ mode before session or project overrides apply.\n\nSecure fallback is better for unattended agents:\n\n#+BEGIN_SRC emacs-lisp\n (setopt ellama-tools-dlp-input-default-action 'block)\n (setopt ellama-tools-dlp-output-warn-behavior 'block)\n (setopt ellama-tools-irreversible-default-action 'block)\n (setopt ellama-tools-irreversible-require-typed-confirm t)\n#+END_SRC\n\nWith secure fallback, the agent receives a denial string and must find a safer\npath. This avoids turning user confirmation into a routine approval habit.\n\nReduce prompt fatigue by tightening tool roles instead of weakening safety.\nAvoid ~:tools :all~ for autonomous subagents. Prefer separate roles such as:\n\n- read-only explorer without ~shell_command~\n- coder with file tools and sandboxed ~shell_command~\n- bash role only when a task explicitly needs shell access\n- no ~ask_user~ tool unless user interruption is intentional\n\nFor MCP tools, keep ~ellama-tools-irreversible-unknown-tool-action~ as ~warn~\ninitially. After observing common safe tools, classify trusted tool identities\nwith ~ellama-tools-irreversible-tool-risk-overrides~ or trusted project\noverrides. Use ~ellama-tools-dlp-add-session-bypass~ only for narrow tool\nidentities and short TTLs; do not disable DLP globally to reduce prompts.\n\nIf ~srt~ is not available, do not use global ~ellama-tools-allow-all~ for\nautonomous coding. Use a small ~ellama-tools-allowed~ list of safe read-only\ntools instead, and keep mutating tools behind confirmation or DLP fallback.\n\nTool output truncation behavior:\n\n- line budget is applied per tool output payload\n- if a payload exceeds the line budget, the model receives a truncation notice\n plus the truncated snippet\n- if lines exceed ~ellama-tools-output-line-budget-max-line-length~, those lines\n are shortened and marked with ~...[line truncated]~\n- when source is known (for example ~read_file~, ~lines_range~, ~grep_in_file~),\n the notice includes source path and suggests using ~lines_range~ and\n ~grep_in_file~\u002F~grep~\n- when source is unknown (for example generic tool output), full output is saved\n to a temp file (if enabled) and the filename is included in the notice\n\nExample regex rules:\n\n#+BEGIN_SRC emacs-lisp\n (setopt ellama-tools-dlp-regex-rules\n '((:id \"openai-key\"\n :pattern \"sk-[[:alnum:]-]+\"\n :directions (input output))\n (:id \"pem-header\"\n :pattern \"-----BEGIN [A-Z ]+-----\"\n :directions (output)\n :enabled t)))\n#+END_SRC\n\nExample scoped override (ignore noisy shell command input):\n\n#+BEGIN_SRC emacs-lisp\n (setopt ellama-tools-dlp-policy-overrides\n '((:tool \"shell_command\"\n :direction input\n :arg \"cmd\"\n :except t)))\n#+END_SRC\n\nExample override for structured input payloads (top-level arg prefix match):\n\n#+BEGIN_SRC emacs-lisp\n (setopt ellama-tools-dlp-policy-overrides\n '((:tool \"write_file\"\n :direction input\n :arg \"content\"\n :action warn)))\n#+END_SRC\n\nTuning helpers:\n\n- ~M-x ellama-tools-dlp-reset-runtime-state~\n- ~M-x ellama-tools-dlp-show-incident-stats~\n- ~(ellama-tools-dlp-recent-incidents)~\n- ~(ellama-tools-dlp-incident-stats)~\n- ~(ellama-tools-dlp-incident-stats-report)~\n\nIncident stats include rollups by risk class, rule ID, tool identity, and\ndecision type (including ~bypass~).\n\nFor a longer rollout\u002Ftuning walkthrough and more override examples, see\n~docs\u002Fdlp_rollout_guide.md~.\n\nTroubleshooting:\n\n- repeated irreversible warnings: classify trusted MCP tools with\n ~ellama-tools-irreversible-tool-risk-overrides~ or use a short-lived session\n bypass for one tool identity\n- bypass expiry: session bypasses expire by TTL and are removed automatically;\n re-add with ~ellama-tools-dlp-add-session-bypass~ when needed\n- false positives: inspect incidents via ~ellama-tools-dlp-recent-incidents~ and\n tune regex rules \u002F overrides before moving more paths to enforce\n\n** SRT Filesystem Policy for Tools\n\nWhen ~ellama-tools-use-srt~ is non-nil, the ~srt~ settings file is the source of\ntruth for tool filesystem policy:\n\n- shell-based tools (~shell_command~, ~grep~, ~grep_in_file~) are enforced by\n the external ~srt~ runtime\n- non-shell file tools (~read_file~, ~write_file~, ~append_file~,\n ~prepend_file~, ~edit_file~, ~directory_tree~, ~move_file~, ~count_lines~,\n ~lines_range~) apply local checks derived from the same ~srt~ settings file\n\nSupported local filesystem subset (current):\n\n- ~filesystem.denyRead~\n- ~filesystem.allowWrite~\n- ~filesystem.denyWrite~ (takes precedence over ~allowWrite~)\n\nFor irreversible audit hardening, keep ~ellama-tools-dlp-audit-log-file~ outside\n~allowWrite~ and add explicit ~denyRead~\u002F~denyWrite~ entries for the audit\ndirectory.\n\nLocal checks intentionally ignore unrelated ~srt~ keys (for example\n~network.*~). If the ~filesystem~ section is missing, local checks use the same\ndefaults as ~srt~ for filesystem access: reads are allowed by default and writes\nare denied unless allowed by ~allowWrite~.\n\nPath matching notes for local checks:\n\n- relative paths in ~srt~ rules are resolved against Emacs ~default-directory~\n- ~~ expands to the current user home directory\n- literal paths, directory-prefix rules, and glob patterns are supported\n- malformed\u002Funsupported patterns signal a ~user-error~ (fail closed)\n\nThe local checks fail closed when ~ellama-tools-use-srt~ is enabled and:\n\n- ~srt~ is not installed\n- the resolved settings file is missing\n- the settings file is malformed JSON\n- relevant ~filesystem~ keys have an invalid shape\n\nExample ~srt~ config for a project sandbox:\n\n#+BEGIN_SRC json\n{\n \"network\": {\n \"allowedDomains\": [\n \"github.com\",\n \"*.github.com\",\n \"api.github.com\",\n \"*.npmjs.org\"\n ],\n \"deniedDomains\": [],\n \"allowUnixSockets\": [],\n \"allowLocalBinding\": false\n },\n \"filesystem\": {\n \"denyRead\": [\n \"~\u002F.srt-settings.json\",\n \"~\u002F.ssh\",\n \"~\u002F.aws\",\n \"~\u002F.gnupg\u002F\",\n \"~\u002F.config\u002Fgcloud\u002F\",\n \"~\u002F.azure\u002F\",\n \"~\u002F.kube\u002F\",\n \"~\u002F.docker\u002F\",\n \"~\u002F.netrc\",\n \"~\u002F.npmrc\",\n \"~\u002F.pypirc\",\n \"~\u002F.git-credentials\",\n \"~\u002F.emacs.d\u002Fellama-dlp-audit.jsonl\",\n \".env\",\n \".env.*\",\n \".env*.local\",\n \"*.env\",\n \"*-credentials.json\",\n \"*serviceAccount*.json\",\n \"*service-account*.json\",\n \"kubeconfig\",\n \"*-secret.yaml\",\n \"secrets.yaml\",\n \"*.pem\",\n \"*.key\",\n \"*.p12\",\n \"*.pfx\",\n \"*.tfstate\",\n \"*.tfstate.backup\",\n \".terraform\u002F\",\n \".vercel\u002F\",\n \".netlify\u002F\",\n \".supabase\u002F\",\n \"dump.sql\",\n \"backup.sql\",\n \"*.dump\"\n ],\n \"allowWrite\": [\n \".\",\n \"src\u002F\",\n \"test\u002F\",\n \"docs\u002F\",\n \"\u002Ftmp\u002Fellama-agent\"\n ],\n \"denyWrite\": [\n \"~\u002F.srt-settings.json\",\n \"~\u002F.ssh\",\n \"~\u002F.aws\",\n \"~\u002F.gnupg\u002F\",\n \"~\u002F.config\u002Fgcloud\u002F\",\n \"~\u002F.azure\u002F\",\n \"~\u002F.kube\u002F\",\n \"~\u002F.docker\u002F\",\n \"~\u002F.netrc\",\n \"~\u002F.npmrc\",\n \"~\u002F.pypirc\",\n \"~\u002F.git-credentials\",\n \"~\u002F.emacs.d\u002Fellama-dlp-audit.jsonl\",\n \".env\",\n \".env.*\",\n \".env*.local\",\n \"*.env\",\n \"*-credentials.json\",\n \"*serviceAccount*.json\",\n \"*service-account*.json\",\n \"kubeconfig\",\n \"*-secret.yaml\",\n \"secrets.yaml\",\n \"*.pem\",\n \"*.key\",\n \"*.p12\",\n \"*.pfx\",\n \"*.tfstate\",\n \"*.tfstate.backup\",\n \".terraform\u002F\",\n \".vercel\u002F\",\n \".netlify\u002F\",\n \".supabase\u002F\",\n \"dump.sql\",\n \"backup.sql\",\n \"*.dump\",\n \"\u002Fetc\u002F\",\n \"\u002Fusr\u002F\",\n \"\u002Fbin\u002F\",\n \"\u002Fsbin\u002F\",\n \"\u002Fboot\u002F\",\n \"\u002Froot\u002F\",\n \"~\u002F.bash_history\",\n \"~\u002F.zsh_history\",\n \"~\u002F.node_repl_history\",\n \"~\u002F.bashrc\",\n \"~\u002F.zshrc\",\n \"~\u002F.profile\",\n \"~\u002F.bash_profile\"\n ]\n },\n \"ignoreViolations\": {\n \"npm\": [\n \"\u002Fprivate\u002Ftmp\"\n ]\n },\n \"enableWeakerNestedSandbox\": false,\n \"enableWeakerNetworkIsolation\": false\n}\n#+END_SRC\n\nKeep ~allowUnixSockets~ empty unless the agent explicitly needs a local socket.\nFor example, adding ~\u002Fvar\u002Frun\u002Fdocker.sock~ gives the sandbox broad Docker\ncontrol and should be treated as a privileged capability.\n\nExample Emacs configuration:\n\n#+BEGIN_SRC emacs-lisp\n (setopt ellama-tools-use-srt t)\n (setopt ellama-tools-srt-args\n '(\"--settings\" \"\u002Fpath\u002Fto\u002F.srt-settings.json\"))\n#+END_SRC\n\nParity tests (real ~srt~ runtime vs local ~ellama~ checks):\n\n- ~make test-srt-integration~: Run host parity tests (requires ~srt~ installed)\n- ~make test-srt-integration-linux~: Run parity tests in Docker on Linux\n semantics. Requires Docker and runs a privileged container (~--privileged~).\n\n* Context Management\n\nEllama allows you to provide context to the Large Language Model (LLM) to\nimprove the relevance and quality of responses. Context serves as background\ninformation, data, or instructions that guide the LLM's understanding of your\nprompt. Without context, the LLM relies solely on its pre-existing knowledge,\nwhich may not always be appropriate.\n\nA “global context” is maintained, which is a collection of text blocks\naccessible to the LLM when responding to prompts. This global context is\nprepended to your prompt before transmission to the LLM. Additionally, Ellama\nsupports an \"ephemeral context,\" which is temporary and only available for a\nsingle request.\n\nSome commands add context automatically as ephemeral context:\n~ellama-ask-about~, ~ellama-code-review~, ~ellama-write~, and ~ellama-code-add~.\n\n** Transient Menus for Context Management\n\nEllama provides a transient menu accessible through the main menu, offering a\nstreamlined way to manage context elements. This menu is accessed via the\n“System” branch of the main transient menu, and then selecting \"Context\nCommands.\"\n\nThe Context Commands transient menu is structured as follows:\n\nContext Commands:\n\n- Options: Provides options for managing ephemeral context.\n - “-e” \"Use Ephemeral Context\" ~--ephemeral~\n- Add: Provides options for adding content to the global or ephemeral context.\n - “b” \"Add Buffer\" ~ellama-transient-add-buffer~\n - “d” \"Add Directory\" ~ellama-transient-add-directory~\n - “f” \"Add File\" ~ellama-transient-add-file~\n - “s” \"Add Selection\" ~ellama-transient-add-selection~\n - “i” \"Add Info Node\" ~ellama-transient-add-info-node~\n- Manage: Provides options for managing the global context.\n - “m” \"Manage context\" ~ellama-context-manage~ - Opens the context\n management buffer.\n - “D” \"Delete element\" ~ellama-context-element-remove-by-name~ - Deletes an\n element by name.\n - “r” \"Context reset\" ~ellama-context-reset~ - Clears the entire global\n context.\n- Quit: (“q” \"Quit\" ~transient-quit-one~) - Closes the context commands\n transient menu.\n\n** Managing the Context\n\n~ellama-context-manage~ opens a dedicated buffer, the context management buffer,\nwhere you can view, modify, and organize the global context. Within this buffer:\n\n+ ~n~: Move to the next context element.\n+ ~p~: Move to the previous context element.\n+ ~q~: Quit the context management buffer.\n+ ~g~: Refresh the contents of the context management buffer.\n+ ~a~: Add a new context element (similar to ~ellama-context-add-selection~).\n+ ~RET~: Preview the content of the context element at the current point.\n\n** Considerations\n\nLarge Language Models possess limited context window sizes, restricting the\ntotal amount of text they can process. Be mindful of the size of your context to\navoid truncation or performance degradation. Irrelevant context can dilute the\ninformation and hinder the LLM’s focus. Ensure context remains up-to-date for\naccurate information. Experimentation with different approaches to context\nmanagement can optimize performance for specific use cases.\n\n* Minor modes\n\nThe Ellama package for Emacs offers a suite of minor modes designed to enhance\nthe user experience by providing context-specific information directly within\nthe editor's interface. These minor modes focus on updating both the header line\nand mode line with relevant details, making it easier to manage and navigate\nmultiple sessions and buffers.\n\nKey features include:\n\n- Context Header Line Modes: ~ellama-context-header-line-mode~ and its global\n counterpart, ~ellama-context-header-line-global-mode~, update the header line\n to display what elements are added to the global Ellama context. This is\n particularly useful for keeping track of what information is currently in\n context.\n- Context Mode Line Modes: Similarly, ~ellama-context-mode-line-mode~ and\n ~ellama-context-mode-line-global-mode~ provide information about the current\n global context directly within the mode line, ensuring that users always have\n relevant information at a glance.\n- Session Header Line Mode: ~ellama-session-header-line-mode~ and its global\n version display the current Ellama session ID in the header line, helping\n users manage multiple sessions efficiently.\n- Session Mode Line Mode: ~ellama-session-mode-line-mode~ and its global\n counterpart offer an additional way to track session IDs by displaying them in\n the mode line.\n\nThese minor modes are easily toggled on or off using specific commands,\nproviding flexibility for users who may want to enable these features globally\nacross all buffers or selectively within individual buffers.\n\n** ellama-context-header-line-mode\n\nDescription: Toggle the Ellama Context header line mode. This minor mode updates\nthe header line to display context-specific information.\n\nUsage: To enable or disable ~ellama-context-header-line-mode~, use the command:\n\n M-x ellama-context-header-line-mode\n\nWhen enabled, this mode adds a hook to ~window-state-change-hook~ to update the\nheader line whenever the window state changes. It also calls\n~ellama-context-update-header-line~ to initialize the header line with\ncontext-specific information.\n\nWhen disabled, it removes the evaluation of ~(:eval (ellama-context-line))~ from\n~header-line-format~.\n\n** ellama-context-header-line-global-mode\n\nDescription: Globalized version of ~ellama-context-header-line-mode~. This mode\nensures that ~ellama-context-header-line-mode~ is enabled in all buffers.\n\nUsage: To enable or disable ~ellama-context-header-line-global-mode~, use the\ncommand:\n\n M-x ellama-context-header-line-global-mode\n\nThis globalized minor mode provides a convenient way to ensure that\ncontext-specific header line information is always available, regardless of the\nbuffer being edited.\n\n** ellama-context-mode-line-mode\n\nDescription: Toggle the Ellama Context mode line mode. This minor mode updates\nthe mode line to display context-specific information.\n\nUsage: To enable or disable ~ellama-context-mode-line-mode~, use the command:\n\n M-x ellama-context-mode-line-mode\n\nWhen enabled, this mode adds a hook to ~window-state-change-hook~ to update the\nmode line whenever the window state changes. It also calls\n~ellama-context-update-mode-line~ to initialize the mode line with\ncontext-specific information.\n\nWhen disabled, it removes the evaluation of ~(:eval (ellama-context-line))~ from\n~mode-line-format~.\n\n** ellama-context-mode-line-global-mode\n\nDescription: Globalized version of ~ellama-context-mode-line-mode~. This mode\nensures that ~ellama-context-mode-line-mode~ is enabled in all buffers.\n\nUsage: To enable or disable ~ellama-context-mode-line-global-mode~, use the\ncommand:\n\n M-x ellama-context-mode-line-global-mode\n\nThis globalized minor mode provides a convenient way to ensure that\ncontext-specific mode line information is always available, regardless of the\nbuffer being edited.\n\n** Ellama Session Header Line Mode\n\nThe ~ellama-session-header-line-mode~ is a minor mode that allows you to display\nthe current Ellama session ID in the header line of your Emacs buffers. This\nfeature helps keep track of which session you are working with, especially\nuseful when managing multiple sessions.\n\n*** Enabling and Disabling\n\nTo enable this mode, use the following command:\n#+BEGIN_SRC emacs-lisp\nM-x ellama-session-header-line-mode\n#+END_SRC\n\nThis will toggle the display of the session ID in the header line. You can also\nenable or disable it globally across all buffers using:\n#+BEGIN_SRC emacs-lisp\nM-x ellama-session-header-line-global-mode\n#+END_SRC\n\n*** Customization\n\nThe session ID is displayed with a customizable face called ~ellama-face~. You\ncan customize this face to change its appearance.\n\n** Ellama Session Mode Line Mode\n\nThe ~ellama-session-mode-line-mode~ is a minor mode that allows you to display\nthe current Ellama session ID in the mode line of your Emacs buffers. This\nfeature provides an additional way to keep track of which session you are\nworking with, especially useful when managing multiple sessions.\n\n*** Enabling and Disabling\n\nTo enable this mode, use the following command:\n#+BEGIN_SRC emacs-lisp\nM-x ellama-session-mode-line-mode\n#+END_SRC\n\nThis will toggle the display of the session ID in the mode line. You can also\nenable or disable it globally across all buffers using:\n#+BEGIN_SRC emacs-lisp\nM-x ellama-session-mode-line-global-mode\n#+END_SRC\n\n*** Customization\n\nThe session ID is displayed with a customizable face called ~ellama-face~. You\ncan customize this face to change its appearance.\n\n* Using Blueprints\n\nBlueprints in Ellama refer to predefined templates or structures that facilitate\nthe creation and management of chat sessions. These blueprints are designed to\nstreamline the process of generating consistent and high-quality outputs by\nproviding a structured framework for interactions.\n\n** Key Components of Ellama Blueprints\n\n1. Act: This is the primary identifier for a blueprint, representing the\naction or purpose of the blueprint.\n2. Prompt: The content that will be used to initiate the chat session. This\ncan include instructions, context, or any other relevant information needed to\nguide the conversation.\n3. For Developers: A flag indicating whether the blueprint is intended for\ndevelopers.\n\n** Creating and Managing Blueprints\n\nEllama provides several functions to create, select, and manage blueprints:\n\n- ~ellama-blueprint-create~: This function allows users to create a new\n blueprint from the current buffer. It prompts for a name and whether the\n blueprint is for developers, then saves the content of the current buffer as\n the prompt.\n\n- ~ellama-blueprint-new~: This function creates a new buffer for a blueprint,\n optionally inserting the content of the current region if active.\n\n- ~ellama-blueprint-select~: This function allows users to select a prompt from\n the collection of blueprints. It filters prompts based on whether they are for\n developers and their source (user-defined, community, or all).\n\n** Blueprints files\n\nYou can also store blueprints as plain text files. You can store it globally\ninside ~ellama-blueprint-global-dir~ or locally in the project local directory\n~ellama-blueprint-local-dir~ with ~ellama-blueprint-file-extensions~.\n\n** Variable Management\n\nBlueprints can include variables that need to be filled before running the chat\nsession. Ellama provides command to fill these variables:\n\n- ~ellama-blueprint-fill-variables~: Prompts the user to enter values for\n variables found in the current buffer and fills them.\n\n** Keymap and Mode\n\nEllama provides a local keymap ~ellama-blueprint-mode-map~ for managing\nblueprints within buffers. The mode includes key bindings for sending the buffer\nto a new chat session, killing the current buffer, creating a new blueprint, and\nfilling variables.\n\nThe ~ellama-blueprint-mode~ is a derived mode from ~text-mode~, providing syntax\nhighlighting for variables in curly braces and setting up the local keymap.\n\nWhen in ~ellama-blueprint-mode~, the following keybindings are available:\n\n- ~C-c C-c~: Send current buffer to a new chat session and kill the current\n buffer.\n- ~C-c C-k~: Kill the current buffer.\n- ~C-c c~: Create a blueprint from the current buffer.\n- ~C-c v~: Fill variables in the current blueprint.\n\n** Transient Menus\n\nEllama includes transient menus for easy access to blueprint commands. The\n~ellama-transient-blueprint-menu~ provides options for chatting with a selected\nblueprint, creating a new blueprint, and quitting the menu.\n\nThe ~ellama-transient-main-menu~ integrates the blueprint menu into the main\nmenu, providing a comprehensive interface for all Ellama commands.\n\n** Running Blueprints programmatically\n\nThe ~ellama-blueprint-run~ function initiates a chat session using a specified\nblueprint. It pre-fills variables based on the provided arguments.\n\n#+BEGIN_SRC emacs-lisp\n (defun my-chat-with-morpheus ()\n \"Start chat with Morpheus.\"\n (interactive)\n (ellama-blueprint-run \"Character\" '(:character \"Morpheus\" :series \"Matrix\")))\n\n (global-set-key (kbd \"C-c e M\") #'my-chat-with-morpheus)\n#+END_SRC\n\n* MCP Integration\n\nYou can also use MCP (Model Context Protocol) tools with ~ellama~. You need\nEmacs 30 or higher version. Install ~mcp.el~ -\nhttps:\u002F\u002Fgithub.com\u002Flizqwerscott\u002Fmcp.el. For example to add web search capability\nto ~ellama~ you can add duckduckgo mcp server\n(https:\u002F\u002Fgithub.com\u002Fnickclyde\u002Fduckduckgo-mcp-server):\n\n#+begin_src emacs-lisp\n(use-package mcp\n :ensure t\n :demand t\n :custom\n (mcp-hub-servers\n `((\"ddg\" . (:command \"uvx\"\n\t\t\t:args\n\t\t\t(\"duckduckgo-mcp-server\")))))\n :config\n (require 'mcp-hub)\n (mcp-hub-start-all-server\n (lambda ()\n (let ((tools (mcp-hub-get-all-tool :asyncp t :categoryp t)))\n (mapcar #'(lambda (tool)\n\t\t (apply #'ellama-tools-define-tool\n\t\t\t (list tool)))\n\t tools)))))\n#+end_src\n\nWhen ~:categoryp t~ is used, ellama derives stable MCP tool identity as\n~\u003Ccategory>\u002F\u003Ctool-name>~ (for example ~mcp-ddg\u002Fsearch~). Irreversible policy,\naudit, and overrides are keyed by this identity.\n\n* Agent Skills\n\nEllama supports *Agent Skills*, a lightweight format for extending AI\ncapabilities. Skills are loaded into context only when needed (Progressive\nDisclosure).\n\n** Directory Structure\n\nEllama looks for skills in two locations:\n1. *Global*: =~\u002F.emacs.d\u002Fellama\u002Fskills\u002F= (Customizable via\n~ellama-skills-global-path~)\n2. *Project-Local*: ~skills\u002F~ inside your project root (Customizable via\n~ellama-skills-local-path~)\n\nA skill is a directory containing a ~SKILL.md~ file. This file includes metadata\n(~name~ and ~description~, at minimum) and instructions that tell an agent how\nto perform a specific task. Skills can also bundle scripts, templates, and\nreference materials.\n\n#+begin_src\nmy-project\u002F\n└──skills\u002F\n └── pdf-processing\u002F\n ├── SKILL.md # Required: instructions + metadata\n ├── scripts\u002F # Optional: executable code\n ├── references\u002F # Optional: documentation\n └── assets\u002F # Optional: templates, resources\n#+end_src\n\n** Creating a Skill\n\nSKILL.md must contain YAML frontmatter:\n\n#+begin_src markdown\n---\nname: pdf-processing\ndescription: Extract text from PDFs and summarize them.\n---\n\n# PDF Processing Instructions\nTo extract text from a PDF...\n#+end_src\n\n** How it works\n\n*Auto-Discovery*: Ellama scans skill directories automatically whenever a chat\n starts. *Context*: Skill metadata (name, description, location) is injected\n into the system prompt. *Activation*: The LLM uses the read_file tool to load\n the SKILL.md content when needed.\n\n* Acknowledgments\n\nThanks [[https:\u002F\u002Fgithub.com\u002Fjmorganca][Jeffrey Morgan]] for excellent project\n[[https:\u002F\u002Fgithub.com\u002Fjmorganca\u002Follama][ollama]]. This project cannot exist\nwithout it.\n\nThanks [[https:\u002F\u002Fgithub.com\u002Fzweifisch][zweifisch]] - I got some ideas from\n[[https:\u002F\u002Fgithub.com\u002Fzweifisch\u002Follama][ollama.el]] what ollama client in Emacs\ncan do.\n\nThanks [[https:\u002F\u002Fgithub.com\u002FDavid-Kunz][Dr. David A. Kunz]] - I got more ideas\nfrom [[https:\u002F\u002Fgithub.com\u002FDavid-Kunz\u002Fgen.nvim][gen.nvim]].\n\nThanks [[https:\u002F\u002Fgithub.com\u002Fahyatt][Andrew Hyatt]] for ~llm~ library. Without it\nonly ~ollama~ would be supported.\n\n* Contributions\n\nTo contribute, submit a pull request or report a bug. This library is part of\nGNU ELPA; major contributions must be from someone with FSF\npapers. Alternatively, you can write a module and share it on a different\narchive like MELPA.\n\n* GNU Free Documentation License\n:PROPERTIES:\n:APPENDIX: t\n:END:\n\n#+texinfo: @include doclicense.texi\n\n#+begin_export html\n\u003Cpre>\n\n GNU Free Documentation License\n Version 1.3, 3 November 2008\n\n\n Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.\n \u003Chttps:\u002F\u002Ffsf.org\u002F>\n Everyone is permitted to copy and distribute verbatim copies\n of this license document, but changing it is not allowed.\n\n0. PREAMBLE\n\nThe purpose of this License is to make a manual, textbook, or other\nfunctional and useful document \"free\" in the sense of freedom: to\nassure everyone the effective freedom to copy and redistribute it,\nwith or without modifying it, either commercially or noncommercially.\nSecondarily, this License preserves for the author and publisher a way\nto get credit for their work, while not being considered responsible\nfor modifications made by others.\n\nThis License is a kind of \"copyleft\", which means that derivative\nworks of the document must themselves be free in the same sense. It\ncomplements the GNU General Public License, which is a copyleft\nlicense designed for free software.\n\nWe have designed this License in order to use it for manuals for free\nsoftware, because free software needs free documentation: a free\nprogram should come with manuals providing the same freedoms that the\nsoftware does. But this License is not limited to software manuals;\nit can be used for any textual work, regardless of subject matter or\nwhether it is published as a printed book. We recommend this License\nprincipally for works whose purpose is instruction or reference.\n\n\n1. APPLICABILITY AND DEFINITIONS\n\nThis License applies to any manual or other work, in any medium, that\ncontains a notice placed by the copyright holder saying it can be\ndistributed under the terms of this License. Such a notice grants a\nworld-wide, royalty-free license, unlimited in duration, to use that\nwork under the conditions stated herein. The \"Document\", below,\nrefers to any such manual or work. Any member of the public is a\nlicensee, and is addressed as \"you\". You accept the license if you\ncopy, modify or distribute the work in a way requiring permission\nunder copyright law.\n\nA \"Modified Version\" of the Document means any work containing the\nDocument or a portion of it, either copied verbatim, or with\nmodifications and\u002For translated into another language.\n\nA \"Secondary Section\" is a named appendix or a front-matter section of\nthe Document that deals exclusively with the relationship of the\npublishers or authors of the Document to the Document's overall\nsubject (or to related matters) and contains nothing that could fall\ndirectly within that overall subject. (Thus, if the Document is in\npart a textbook of mathematics, a Secondary Section may not explain\nany mathematics.) The relationship could be a matter of historical\nconnection with the subject or with related matters, or of legal,\ncommercial, philosophical, ethical or political position regarding\nthem.\n\nThe \"Invariant Sections\" are certain Secondary Sections whose titles\nare designated, as being those of Invariant Sections, in the notice\nthat says that the Document is released under this License. If a\nsection does not fit the above definition of Secondary then it is not\nallowed to be designated as Invariant. The Document may contain zero\nInvariant Sections. If the Document does not identify any Invariant\nSections then there are none.\n\nThe \"Cover Texts\" are certain short passages of text that are listed,\nas Front-Cover Texts or Back-Cover Texts, in the notice that says that\nthe Document is released under this License. A Front-Cover Text may\nbe at most 5 words, and a Back-Cover Text may be at most 25 words.\n\nA \"Transparent\" copy of the Document means a machine-readable copy,\nrepresented in a format whose specification is available to the\ngeneral public, that is suitable for revising the document\nstraightforwardly with generic text editors or (for images composed of\npixels) generic paint programs or (for drawings) some widely available\ndrawing editor, and that is suitable for input to text formatters or\nfor automatic translation to a variety of formats suitable for input\nto text formatters. A copy made in an otherwise Transparent file\nformat whose markup, or absence of markup, has been arranged to thwart\nor discourage subsequent modification by readers is not Transparent.\nAn image format is not Transparent if used for any substantial amount\nof text. A copy that is not \"Transparent\" is called \"Opaque\".\n\nExamples of suitable formats for Transparent copies include plain\nASCII without markup, Texinfo input format, LaTeX input format, SGML\nor XML using a publicly available DTD, and standard-conforming simple\nHTML, PostScript or PDF designed for human modification. Examples of\ntransparent image formats include PNG, XCF and JPG. Opaque formats\ninclude proprietary formats that can be read and edited only by\nproprietary word processors, SGML or XML for which the DTD and\u002For\nprocessing tools are not generally available, and the\nmachine-generated HTML, PostScript or PDF produced by some word\nprocessors for output purposes only.\n\nThe \"Title Page\" means, for a printed book, the title page itself,\nplus such following pages as are needed to hold, legibly, the material\nthis License requires to appear in the title page. For works in\nformats which do not have any title page as such, \"Title Page\" means\nthe text near the most prominent appearance of the work's title,\npreceding the beginning of the body of the text.\n\nThe \"publisher\" means any person or entity that distributes copies of\nthe Document to the public.\n\nA section \"Entitled XYZ\" means a named subunit of the Document whose\ntitle either is precisely XYZ or contains XYZ in parentheses following\ntext that translates XYZ in another language. (Here XYZ stands for a\nspecific section name mentioned below, such as \"Acknowledgements\",\n\"Dedications\", \"Endorsements\", or \"History\".) To \"Preserve the Title\"\nof such a section when you modify the Document means that it remains a\nsection \"Entitled XYZ\" according to this definition.\n\nThe Document may include Warranty Disclaimers next to the notice which\nstates that this License applies to the Document. These Warranty\nDisclaimers are considered to be included by reference in this\nLicense, but only as regards disclaiming warranties: any other\nimplication that these Warranty Disclaimers may have is void and has\nno effect on the meaning of this License.\n\n2. VERBATIM COPYING\n\nYou may copy and distribute the Document in any medium, either\ncommercially or noncommercially, provided that this License, the\ncopyright notices, and the license notice saying this License applies\nto the Document are reproduced in all copies, and that you add no\nother conditions whatsoever to those of this License. You may not use\ntechnical measures to obstruct or control the reading or further\ncopying of the copies you make or distribute. However, you may accept\ncompensation in exchange for copies. If you distribute a large enough\nnumber of copies you must also follow the conditions in section 3.\n\nYou may also lend copies, under the same conditions stated above, and\nyou may publicly display copies.\n\n\n3. COPYING IN QUANTITY\n\nIf you publish printed copies (or copies in media that commonly have\nprinted covers) of the Document, numbering more than 100, and the\nDocument's license notice requires Cover Texts, you must enclose the\ncopies in covers that carry, clearly and legibly, all these Cover\nTexts: Front-Cover Texts on the front cover, and Back-Cover Texts on\nthe back cover. Both covers must also clearly and legibly identify\nyou as the publisher of these copies. The front cover must present\nthe full title with all words of the title equally prominent and\nvisible. You may add other material on the covers in addition.\nCopying with changes limited to the covers, as long as they preserve\nthe title of the Document and satisfy these conditions, can be treated\nas verbatim copying in other respects.\n\nIf the required texts for either cover are too voluminous to fit\nlegibly, you should put the first ones listed (as many as fit\nreasonably) on the actual cover, and continue the rest onto adjacent\npages.\n\nIf you publish or distribute Opaque copies of the Document numbering\nmore than 100, you must either include a machine-readable Transparent\ncopy along with each Opaque copy, or state in or with each Opaque copy\na computer-network location from which the general network-using\npublic has access to download using public-standard network protocols\na complete Transparent copy of the Document, free of added material.\nIf you use the latter option, you must take reasonably prudent steps,\nwhen you begin distribution of Opaque copies in quantity, to ensure\nthat this Transparent copy will remain thus accessible at the stated\nlocation until at least one year after the last time you distribute an\nOpaque copy (directly or through your agents or retailers) of that\nedition to the public.\n\nIt is requested, but not required, that you contact the authors of the\nDocument well before redistributing any large number of copies, to\ngive them a chance to provide you with an updated version of the\nDocument.\n\n\n4. MODIFICATIONS\n\nYou may copy and distribute a Modified Version of the Document under\nthe conditions of sections 2 and 3 above, provided that you release\nthe Modified Version under precisely this License, with the Modified\nVersion filling the role of the Document, thus licensing distribution\nand modification of the Modified Version to whoever possesses a copy\nof it. In addition, you must do these things in the Modified Version:\n\nA. Use in the Title Page (and on the covers, if any) a title distinct\n from that of the Document, and from those of previous versions\n (which should, if there were any, be listed in the History section\n of the Document). You may use the same title as a previous version\n if the original publisher of that version gives permission.\nB. List on the Title Page, as authors, one or more persons or entities\n responsible for authorship of the modifications in the Modified\n Version, together with at least five of the principal authors of the\n Document (all of its principal authors, if it has fewer than five),\n unless they release you from this requirement.\nC. State on the Title page the name of the publisher of the\n Modified Version, as the publisher.\nD. Preserve all the copyright notices of the Document.\nE. Add an appropriate copyright notice for your modifications\n adjacent to the other copyright notices.\nF. Include, immediately after the copyright notices, a license notice\n giving the public permission to use the Modified Version under the\n terms of this License, in the form shown in the Addendum below.\nG. Preserve in that license notice the full lists of Invariant Sections\n and required Cover Texts given in the Document's license notice.\nH. Include an unaltered copy of this License.\nI. Preserve the section Entitled \"History\", Preserve its Title, and add\n to it an item stating at least the title, year, new authors, and\n publisher of the Modified Version as given on the Title Page. If\n there is no section Entitled \"History\" in the Document, create one\n stating the title, year, authors, and publisher of the Document as\n given on its Title Page, then add an item describing the Modified\n Version as stated in the previous sentence.\nJ. Preserve the network location, if any, given in the Document for\n public access to a Transparent copy of the Document, and likewise\n the network locations given in the Document for previous versions\n it was based on. These may be placed in the \"History\" section.\n You may omit a network location for a work that was published at\n least four years before the Document itself, or if the original\n publisher of the version it refers to gives permission.\nK. For any section Entitled \"Acknowledgements\" or \"Dedications\",\n Preserve the Title of the section, and preserve in the section all\n the substance and tone of each of the contributor acknowledgements\n and\u002For dedications given therein.\nL. Preserve all the Invariant Sections of the Document,\n unaltered in their text and in their titles. Section numbers\n or the equivalent are not considered part of the section titles.\nM. Delete any section Entitled \"Endorsements\". Such a section\n may not be included in the Modified Version.\nN. Do not retitle any existing section to be Entitled \"Endorsements\"\n or to conflict in title with any Invariant Section.\nO. Preserve any Warranty Disclaimers.\n\nIf the Modified Version includes new front-matter sections or\nappendices that qualify as Secondary Sections and contain no material\ncopied from the Document, you may at your option designate some or all\nof these sections as invariant. To do this, add their titles to the\nlist of Invariant Sections in the Modified Version's license notice.\nThese titles must be distinct from any other section titles.\n\nYou may add a section Entitled \"Endorsements\", provided it contains\nnothing but endorsements of your Modified Version by various\nparties--for example, statements of peer review or that the text has\nbeen approved by an organization as the authoritative definition of a\nstandard.\n\nYou may add a passage of up to five words as a Front-Cover Text, and a\npassage of up to 25 words as a Back-Cover Text, to the end of the list\nof Cover Texts in the Modified Version. Only one passage of\nFront-Cover Text and one of Back-Cover Text may be added by (or\nthrough arrangements made by) any one entity. If the Document already\nincludes a cover text for the same cover, previously added by you or\nby arrangement made by the same entity you are acting on behalf of,\nyou may not add another; but you may replace the old one, on explicit\npermission from the previous publisher that added the old one.\n\nThe author(s) and publisher(s) of the Document do not by this License\ngive permission to use their names for publicity for or to assert or\nimply endorsement of any Modified Version.\n\n\n5. COMBINING DOCUMENTS\n\nYou may combine the Document with other documents released under this\nLicense, under the terms defined in section 4 above for modified\nversions, provided that you include in the combination all of the\nInvariant Sections of all of the original documents, unmodified, and\nlist them all as Invariant Sections of your combined work in its\nlicense notice, and that you preserve all their Warranty Disclaimers.\n\nThe combined work need only contain one copy of this License, and\nmultiple identical Invariant Sections may be replaced with a single\ncopy. If there are multiple Invariant Sections with the same name but\ndifferent contents, make the title of each such section unique by\nadding at the end of it, in parentheses, the name of the original\nauthor or publisher of that section if known, or else a unique number.\nMake the same adjustment to the section titles in the list of\nInvariant Sections in the license notice of the combined work.\n\nIn the combination, you must combine any sections Entitled \"History\"\nin the various original documents, forming one section Entitled\n\"History\"; likewise combine any sections Entitled \"Acknowledgements\",\nand any sections Entitled \"Dedications\". You must delete all sections\nEntitled \"Endorsements\".\n\n\n6. COLLECTIONS OF DOCUMENTS\n\nYou may make a collection consisting of the Document and other\ndocuments released under this License, and replace the individual\ncopies of this License in the various documents with a single copy\nthat is included in the collection, provided that you follow the rules\nof this License for verbatim copying of each of the documents in all\nother respects.\n\nYou may extract a single document from such a collection, and\ndistribute it individually under this License, provided you insert a\ncopy of this License into the extracted document, and follow this\nLicense in all other respects regarding verbatim copying of that\ndocument.\n\n\n7. AGGREGATION WITH INDEPENDENT WORKS\n\nA compilation of the Document or its derivatives with other separate\nand independent documents or works, in or on a volume of a storage or\ndistribution medium, is called an \"aggregate\" if the copyright\nresulting from the compilation is not used to limit the legal rights\nof the compilation's users beyond what the individual works permit.\nWhen the Document is included in an aggregate, this License does not\napply to the other works in the aggregate which are not themselves\nderivative works of the Document.\n\nIf the Cover Text requirement of section 3 is applicable to these\ncopies of the Document, then if the Document is less than one half of\nthe entire aggregate, the Document's Cover Texts may be placed on\ncovers that bracket the Document within the aggregate, or the\nelectronic equivalent of covers if the Document is in electronic form.\nOtherwise they must appear on printed covers that bracket the whole\naggregate.\n\n\n8. TRANSLATION\n\nTranslation is considered a kind of modification, so you may\ndistribute translations of the Document under the terms of section 4.\nReplacing Invariant Sections with translations requires special\npermission from their copyright holders, but you may include\ntranslations of some or all Invariant Sections in addition to the\noriginal versions of these Invariant Sections. You may include a\ntranslation of this License, and all the license notices in the\nDocument, and any Warranty Disclaimers, provided that you also include\nthe original English version of this License and the original versions\nof those notices and disclaimers. In case of a disagreement between\nthe translation and the original version of this License or a notice\nor disclaimer, the original version will prevail.\n\nIf a section in the Document is Entitled \"Acknowledgements\",\n\"Dedications\", or \"History\", the requirement (section 4) to Preserve\nits Title (section 1) will typically require changing the actual\ntitle.\n\n\n9. TERMINATION\n\nYou may not copy, modify, sublicense, or distribute the Document\nexcept as expressly provided under this License. Any attempt\notherwise to copy, modify, sublicense, or distribute it is void, and\nwill automatically terminate your rights under this License.\n\nHowever, if you cease all violation of this License, then your license\nfrom a particular copyright holder is reinstated (a) provisionally,\nunless and until the copyright holder explicitly and finally\nterminates your license, and (b) permanently, if the copyright holder\nfails to notify you of the violation by some reasonable means prior to\n60 days after the cessation.\n\nMoreover, your license from a particular copyright holder is\nreinstated permanently if the copyright holder notifies you of the\nviolation by some reasonable means, this is the first time you have\nreceived notice of violation of this License (for any work) from that\ncopyright holder, and you cure the violation prior to 30 days after\nyour receipt of the notice.\n\nTermination of your rights under this section does not terminate the\nlicenses of parties who have received copies or rights from you under\nthis License. If your rights have been terminated and not permanently\nreinstated, receipt of a copy of some or all of the same material does\nnot give you any rights to use it.\n\n\n10. FUTURE REVISIONS OF THIS LICENSE\n\nThe Free Software Foundation may publish new, revised versions of the\nGNU Free Documentation License from time to time. Such new versions\nwill be similar in spirit to the present version, but may differ in\ndetail to address new problems or concerns. See\nhttps:\u002F\u002Fwww.gnu.org\u002Flicenses\u002F.\n\nEach version of the License is given a distinguishing version number.\nIf the Document specifies that a particular numbered version of this\nLicense \"or any later version\" applies to it, you have the option of\nfollowing the terms and conditions either of that specified version or\nof any later version that has been published (not as a draft) by the\nFree Software Foundation. If the Document does not specify a version\nnumber of this License, you may choose any version ever published (not\nas a draft) by the Free Software Foundation. If the Document\nspecifies that a proxy can decide which future versions of this\nLicense can be used, that proxy's public statement of acceptance of a\nversion permanently authorizes you to choose that version for the\nDocument.\n\n11. RELICENSING\n\n\"Massive Multiauthor Collaboration Site\" (or \"MMC Site\") means any\nWorld Wide Web server that publishes copyrightable works and also\nprovides prominent facilities for anybody to edit those works. A\npublic wiki that anybody can edit is an example of such a server. A\n\"Massive Multiauthor Collaboration\" (or \"MMC\") contained in the site\nmeans any set of copyrightable works thus published on the MMC site.\n\n\"CC-BY-SA\" means the Creative Commons Attribution-Share Alike 3.0\nlicense published by Creative Commons Corporation, a not-for-profit\ncorporation with a principal place of business in San Francisco,\nCalifornia, as well as future copyleft versions of that license\npublished by that same organization.\n\n\"Incorporate\" means to publish or republish a Document, in whole or in\npart, as part of another Document.\n\nAn MMC is \"eligible for relicensing\" if it is licensed under this\nLicense, and if all works that were first published under this License\nsomewhere other than this MMC, and subsequently incorporated in whole or\nin part into the MMC, (1) had no cover texts or invariant sections, and\n(2) were thus incorporated prior to November 1, 2008.\n\nThe operator of an MMC Site may republish an MMC contained in the site\nunder CC-BY-SA on the same site at any time before August 1, 2009,\nprovided the MMC is eligible for relicensing.\n\n\nADDENDUM: How to use this License for your documents\n\nTo use this License in a document you have written, include a copy of\nthe License in the document and put the following copyright and\nlicense notices just after the title page:\n\n Copyright (c) YEAR YOUR NAME.\n Permission is granted to copy, distribute and\u002For modify this document\n under the terms of the GNU Free Documentation License, Version 1.3\n or any later version published by the Free Software Foundation;\n with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.\n A copy of the license is included in the section entitled \"GNU\n Free Documentation License\".\n\nIf you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,\nreplace the \"with...Texts.\" line with this:\n\n with the Invariant Sections being LIST THEIR TITLES, with the\n Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.\n\nIf you have Invariant Sections without Cover Texts, or some other\ncombination of the three, merge those two alternatives to suit the\nsituation.\n\nIf your document contains nontrivial examples of program code, we\nrecommend releasing these examples in parallel under your choice of\nfree software license, such as the GNU General Public License,\nto permit their use in free software.\n\u003C\u002Fpre>\n#+end_export\n","[[http:\u002F\u002Fwww.gnu.org\u002Flicenses\u002Fgpl-3.0.txt][文件:https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-GPL_3-green.svg]]\n[[https:\u002F\u002Fmelpa.org\u002F#\u002Fellama][文件:https:\u002F\u002Fmelpa.org\u002Fpackages\u002Fellama-badge.svg]]\n[[https:\u002F\u002Fstable.melpa.org\u002F#\u002Fellama][文件:https:\u002F\u002Fstable.melpa.org\u002Fpackages\u002Fellama-badge.svg]]\n[[https:\u002F\u002Felpa.gnu.org\u002Fpackages\u002Fellama.html][文件:https:\u002F\u002Felpa.gnu.org\u002Fpackages\u002Fellama.svg]]\n\nEllama 是一个用于从 Emacs 中与大型语言模型交互的工具。它允许你向 LLM 提出问题并接收回复。通过 Emacs 界面，Ellama 可以执行多种任务，例如翻译、代码审查、摘要生成、改进语法\u002F拼写或措辞等。Ellama 原生支持流式输出，因此可以轻松地与你喜欢的文本编辑器一起使用。\n\n“ellama”这个名字来源于“Emacs Large Language Model Assistant”。前一句话正是由 Ellama 自己撰写的。\n[[文件:imgs\u002Freasoning-models.gif]]\n\n* 安装\n\n只需输入 ~M-x~ ~package-install~ @@html:\u003Ckbd>@@Enter@@html:\u003C\u002Fkbd>@@ ~ellama~\n@@html:\u003Ckbd>@@Enter@@html:\u003C\u002Fkbd>@@。默认情况下，它使用 [[https:\u002F\u002Fgithub.com\u002Fjmorganca\u002Follama][ollama]] 提供商。如果你对此没有异议，你需要安装 [[https:\u002F\u002Fgithub.com\u002Fjmorganca\u002Follama][ollama]] 并拉取 [[https:\u002F\u002Follama.com\u002Fmodels][任何 ollama 模型]]，如下所示：\n\n#+BEGIN_SRC shell\n ollama pull qwen2.5:3b\n#+END_SRC\n\n你可以将 ~ellama~ 与其他模型或另一个 LLM 提供商一起使用。如果没有进行任何配置，系统会自动使用第一个可用的 ollama 模型。你可以按照以下方式自定义 Ellama 的配置：\n\n#+BEGIN_SRC emacs-lisp\n (use-package ellama\n :ensure t\n :bind (\"C-c e\" . ellama)\n ;; 在聊天缓冲区中用 C-c C-c 发送最后一条消息\n :hook (org-ctrl-c-ctrl-c-hook . ellama-chat-send-last-message)\n :init (setopt ellama-auto-scroll t)\n :config\n ;; 在所有缓冲区的标题栏中显示 Ellama 上下文\n (ellama-context-header-line-global-mode +1)\n ;; 在所有缓冲区的标题栏中显示 Ellama 会话 ID\n (ellama-session-header-line-global-mode +1))\n#+END_SRC\n\n更复杂的配置示例：\n\n#+BEGIN_SRC emacs-lisp\n (use-package ellama\n :ensure t\n :bind (\"C-c e\" . ellama)\n ;; 在聊天缓冲区中用 C-c C-c 发送最后一条消息\n :hook (org-ctrl-c-ctrl-c-hook . ellama-chat-send-last-message)\n :init\n ;; 设置键绑定\n ;; (setopt ellama-keymap-prefix \"C-c e\")\n ;; 你希望 Ellama 翻译成的语言\n (setopt ellama-language \"German\")\n ;; 例如可以是 llm-openai\n (require 'llm-ollama)\n (setopt ellama-provider\n \t (make-llm-ollama\n \t ;; 使用此模型前需先拉取\n \t ;; 值应与你在终端拉取时打印的值一致\n \t :chat-model \"llama3:8b-instruct-q8_0\"\n \t :embedding-model \"nomic-embed-text\"\n \t :default-chat-non-standard-params '((\"num_ctx\" . 8192))))\n (setopt ellama-summarization-provider\n \t (make-llm-ollama\n \t :chat-model \"qwen2.5:3b\"\n \t :embedding-model \"nomic-embed-text\"\n \t :default-chat-non-standard-params '((\"num_ctx\" . 32768))))\n (setopt ellama-coding-provider\n \t (make-llm-ollama\n \t :chat-model \"qwen2.5-coder:3b\"\n \t :embedding-model \"nomic-embed-text\"\n \t :default-chat-non-standard-params '((\"num_ctx\" . 32768))))\n ;; 预定义的 LLM 提供商，用于交互式切换。\n ;; 不应在此处添加 ollama 提供商——它们可以在不添加的情况下直接交互选择。此处仅为示例。\n (setopt ellama-providers\n \t '((\"zephyr\" . (make-llm-ollama\n \t\t\t :chat-model \"zephyr:7b-beta-q6_K\"\n \t\t\t :embedding-model \"zephyr:7b-beta-q6_K\"))\n \t (\"mistral\" . (make-llm-ollama\n \t\t\t :chat-model \"mistral:7b-instruct-v0.2-q6_K\"\n \t\t\t :embedding-model \"mistral:7b-instruct-v0.2-q6_K\"))\n \t (\"mixtral\" . (make-llm-ollama\n \t\t\t :chat-model \"mixtral:8x7b-instruct-v0.1-q3_K_M-4k\"\n \t\t\t :embedding-model \"mixtral:8x7b-instruct-v0.1-q3_K_M-4k\"))))\n ;; 使用 LLM 命名新会话\n (setopt ellama-naming-provider\n \t (make-llm-ollama\n \t :chat-model \"llama3:8b-instruct-q8_0\"\n \t :embedding-model \"nomic-embed-text\"\n \t :default-chat-non-standard-params '((\"stop\" . (\"\\n\")))))\n (setopt ellama-naming-scheme 'ellama-generate-name-by-llm)\n ;; 翻译 LLM 提供商\n (setopt ellama-translation-provider\n \t (make-llm-ollama\n \t :chat-model \"qwen2.5:3b\"\n \t :embedding-model \"nomic-embed-text\"\n \t :default-chat-non-standard-params\n \t '((\"num_ctx\" . 32768))))\n (setopt ellama-extraction-provider (make-llm-ollama\n \t\t\t\t :chat-model \"qwen2.5-coder:7b-instruct-q8_0\"\n \t\t\t\t :embedding-model \"nomic-embed-text\"\n \t\t\t\t :default-chat-non-standard-params\n \t\t\t\t '((\"num_ctx\" . 32768))))\n ;; 自定义显示缓冲区的行为\n ;; 参见 ~(info \"(elisp) Buffer Display Action Functions\")~\n (setopt ellama-chat-display-action-function #'display-buffer-full-frame)\n (setopt ellama-instant-display-action-function #'display-buffer-at-bottom)\n :config\n ;; 在所有缓冲区的标题栏中显示 Ellama 上下文\n (ellama-context-header-line-global-mode +1)\n ;; 在所有缓冲区的标题栏中显示 Ellama 会话 ID\n (ellama-session-header-line-global-mode +1)\n ;; 处理滚动事件\n (advice-add 'pixel-scroll-precision :before #'ellama-disable-scroll)\n (advice-add 'end-of-buffer :after #'ellama-enable-scroll))\n#+END_SRC\n\n* 命令\n\n- ~ellama~: 这是 Ellama 的入口点。它会显示主临时菜单，允许你从这里访问所有其他 Ellama 命令。\n- ~ellama-chat~: 通过在交互式缓冲区中输入提示来向 Ellama 提问，并继续对话。如果使用通用参数调用（~C-u~），将启动一个新的会话，并提供 LLM 模型的交互式选择。\n- ~ellama-write~: 此命令允许你使用 LLM 生成文本。交互式调用时，它会提示你输入一条指令，然后根据上下文生成文本。如果当前有区域被选中，则会在生成响应之前将选中文本添加到临时上下文中。\n- ~ellama-chat-send-last-message~: 发送当前 Ellama 聊天缓冲区中提取的最后一条用户消息。\n- ~ellama-ask-about~: 向 Ellama 提问关于选定区域或当前缓冲区的内容。会自动将选定区域或当前缓冲区添加到临时上下文中，用于一次请求。\n- ~ellama-ask-selection~: 将选定区域或当前缓冲区发送到 Ellama 聊天中。\n- ~ellama-ask-line~: 将当前行发送到 Ellama 聊天中。\n- ~ellama-complete~: 使用 Ellama 完成当前缓冲区中的文本。\n- ~ellama-translate~: 请求 Ellama 翻译选中的区域或光标处的单词。\n- ~ellama-translate-buffer~: 翻译当前缓冲区。\n- ~ellama-define-word~: 使用 Ellama 查找当前单词的定义。\n- ~ellama-summarize~: 使用 Ellama 总结选定区域或当前缓冲区的内容。\n- ~ellama-summarize-killring~: 总结剪贴板中的文本。\n- ~ellama-code-review~: 使用 Ellama 审查选定区域或当前缓冲区中的代码。会自动将选定区域或当前缓冲区添加到临时上下文中，用于一次请求。\n- ~ellama-change~: 根据提供的修改内容更改选定区域或当前缓冲区中的文本。\n- ~ellama-make-list~: 使用 Ellama 从当前区域或缓冲区创建 Markdown 列表。\n- ~ellama-make-table~: 使用 Ellama 从当前区域或缓冲区创建 Markdown 表格。\n- ~ellama-summarize-webpage~: 使用 Ellama 总结从 URL 获取的网页内容。\n- ~ellama-provider-select~: 选择 Ellama 提供者。\n- ~ellama-code-complete~: 使用 Ellama 根据提供的修改内容完成选定代码或当前缓冲区中的代码。\n- ~ellama-code-add~: 根据描述生成并插入新代码。此功能会提示用户描述他们想要生成的代码。如果当前有区域被选中，则会将选中文本包含在用于代码生成的临时上下文中。\n- ~ellama-code-edit~: 使用 Ellama 根据提供的修改内容更改选定代码或当前缓冲区中的代码。\n- ~ellama-code-improve~: 使用 Ellama 根据提供的修改内容改进选定代码或当前缓冲区中的代码。\n- ~ellama-generate-commit-message~: 根据差异生成提交信息。\n- ~ellama-proofread~: 校对选定文本。\n- ~ellama-improve-wording~: 使用 Ellama 改进当前选定区域或缓冲区中的措辞。\n- ~ellama-improve-grammar~: 使用 Ellama 改善当前选定区域或缓冲区中的语法和拼写。\n- ~ellama-improve-conciseness~: 使用 Ellama 使当前选定区域或缓冲区中的文本更加简洁明了。\n- ~ellama-make-format~: 使用 Ellama 将当前选定文本或缓冲区中的文本渲染为指定格式。\n- ~ellama-load-session~: 从文件加载 Ellama 会话。\n- ~ellama-session-delete~: 删除 Ellama 会话。\n- ~ellama-session-switch~: 切换当前活动会话。\n- ~ellama-session-kill~: 选择并终止一个活动会话。\n- ~ellama-session-rename~: 重命名当前 Ellama 会话。\n- ~ellama-context-add-file~: 将文件添加到上下文中。\n- ~ellama-context-add-directory~: 将目录中的所有文件添加到上下文中。\n- ~ellama-context-add-buffer~: 将缓冲区添加到上下文中。\n- ~ellama-context-add-selection~: 将选定区域添加到上下文中。\n- ~ellama-context-add-info-node~: 将 Info 节点添加到上下文中。\n- ~ellama-context-reset~: 清除全局上下文。\n- ~ellama-context-manage~: 管理全局上下文。在上下文管理缓冲区中，你可以查看 Ellama 上下文元素。可用的操作及快捷键绑定如下：\n - ~n~: 移动到下一行。\n - ~p~: 移动到上一行。\n - ~q~: 关闭窗口。\n - ~g~: 更新上下文管理缓冲区。\n - ~a~: 打开临时上下文菜单以添加新元素。\n - ~d~: 移除当前点的上下文元素。\n - ~RET~: 预览当前点的上下文元素。\n- ~ellama-context-preview-element-at-point~: 预览当前点的 Ellama 上下文元素。仅在 Ellama 上下文管理缓冲区中有效。\n- ~ellama-context-remove-element-at-point~: 从全局上下文中移除当前点的 Ellama 上下文元素。仅在 Ellama 上下文管理缓冲区中有效。\n- ~ellama-chat-translation-enable~: 启用聊天翻译。\n- ~ellama-chat-translation-disable~: 禁用聊天翻译。\n- ~ellama-solve-reasoning-problem~: 使用“思维抽象”技术解决推理问题。该方法通过向 LLM 发送一系列消息，帮助其更好地回答推理问题。即使是 phi3-mini 等小型 LLM，在使用 AoT 技术后，也能在推理任务上取得更好的效果。\n- ~ellama-solve-domain-specific-problem~: 使用简单链式方法解决特定领域的问题。这种方法让 LLM 表现得像专业人士一样，并增加了一个规划步骤。\n- ~ellama-community-prompts-select-blueprint~: 从社区提示集中选择一个提示。系统会提示用户选择一个角色，然后将相应的提示插入蓝图缓冲区。\n- ~ellama-blueprint-fill-variables~: 提示用户填写当前蓝图缓冲区中变量的值，并更新这些变量。\n- ~ellama-tools-enable-by-name~: 通过名称启用特定工具。使用此命令可以激活单个工具，需要输入工具名称。\n- ~ellama-tools-enable-all~: 一次性启用所有可用工具。使用此命令可以激活系统中的每一个工具，实现全面的功能，而无需手动选择。\n- ~ellama-tools-disable-by-name~: 通过名称禁用特定工具。当某个工具的功能不再需要时，可以使用此命令将其停用。\n- ~ellama-tools-disable-all~: 同时禁用所有已启用的工具。使用此命令可以将系统重置为最小状态，确保没有任何工具处于活动状态。\n\n* 键位映射\n\n建议使用临时菜单（~M-x ellama~）而不是键位映射，这样用户体验更好。\n\n在任何正在进行 Ellama 流式传输的缓冲区中，按下 ~C-g~ 即可取消当前流。\n\n以下是 Ellama 中使用 ~ellama-keymap-prefix~ 前缀（默认未设置）的键位绑定及其对应功能的表格：\n\n| 键位 | 功能 | 描述 |\n|--------+---------------------------------+------------------------------|\n| \"w\" | ellama-write | 写作 |\n| \"c c\" | ellama-code-complete | 代码补全 |\n| \"c a\" | ellama-code-add | 添加代码 |\n| \"c e\" | ellama-code-edit | 编辑代码 |\n| \"c i\" | ellama-code-improve | 改进代码 |\n| \"c r\" | ellama-code-review | 代码评审 |\n| \"c m\" | ellama-generate-commit-message | 生成提交信息 |\n| \"s s\" | ellama-summarize | 概括 |\n| \"s w\" | ellama-summarize-webpage | 概括网页 |\n| \"s c\" | ellama-summarize-killring | 概括剪贴板内容 |\n| \"s l\" | ellama-load-session | 加载会话 |\n| \"s r\" | ellama-session-rename | 重命名会话 |\n| \"s d\" | ellama-session-delete | 删除会话 |\n| \"s a\" | ellama-session-switch | 切换会话激活状态 |\n| \"P\" | ellama-proofread | 校对 |\n| \"i w\" | ellama-improve-wording | 改善措辞 |\n| \"i g\" | ellama-improve-grammar | 改善语法和拼写 |\n| \"i c\" | ellama-improve-conciseness | 提高简洁性 |\n| \"m l\" | ellama-make-list | 制作列表 |\n| \"m t\" | ellama-make-table | 制作表格 |\n| \"m f\" | ellama-make-format | 制作格式 |\n| \"a a\" | ellama-ask-about | 询问 |\n| \"a i\" | ellama-chat | 聊天（交互式提问） |\n| \"a l\" | ellama-ask-line | 询问当前行 |\n| \"a s\" | ellama-ask-selection | 询问选区 |\n| \"t t\" | ellama-translate | 文本翻译 |\n| \"t b\" | ellama-translate-buffer | 翻译缓冲区 |\n| \"t e\" | ellama-chat-translation-enable | 启用翻译功能 |\n| \"t d\" | ellama-chat-translation-disable | 禁用翻译功能 |\n| \"t c\" | ellama-complete | 文本补全 |\n| \"d w\" | ellama-define-word | 查词典 |\n| \"x b\" | ellama-context-add-buffer | 添加缓冲区上下文 |\n| \"x f\" | ellama-context-add-file | 添加文件上下文 |\n| \"x d\" | ellama-context-add-directory | 添加目录上下文 |\n| \"x s\" | ellama-context-add-selection | 添加选区上下文 |\n| \"x i\" | ellama-context-add-info-node | 添加 Info 节点上下文 |\n| \"x r\" | ellama-context-reset | 重置上下文 |\n| \"p s\" | ellama-provider-select | 选择服务提供商 |\n\n* 配置\n\n以下变量可以针对 Ellama 客户端进行自定义：\n\n- ~ellama-enable-keymap~: 启用 Ellama 键位映射。\n- ~ellama-keymap-prefix~: Ellama 的键位前缀。\n- ~ellama-user-nick~: 日志中的用户昵称。\n- ~ellama-assistant-nick~: 日志中的助手昵称。\n- ~ellama-language~: Ollama 翻译使用的语言。默认语言为英语。\n- ~ellama-provider~: Ellama 使用的 LLM 提供商。支持的提供商众多，包括 ~ollama~、~open ai~、~vertex~ 和 ~GPT4All~。更多信息请参阅 [[https:\u002F\u002Felpa.gnu.org\u002Fpackages\u002Fllm.html][llm 文档]]。\n- ~ellama-providers~: 模型与 LLM 提供商的关联列表，以名称为键。\n- ~ellama-spinner-enabled~: 在文本生成过程中启用加载动画。\n- ~ellama-spinner-type~: Ellama 的加载动画类型。默认类型为 ~progress-bar~。\n- ~ellama-auto-scroll~: 如果启用，Ellama 缓冲区将在生成过程中自动滚动。默认关闭。\n- ~ellama-fill-paragraphs~: 自定义 Ellama 段落填充行为的选项。\n- ~ellama-response-process-method~: 配置 LLM 响应的处理方式。选项包括流式传输以实现实时输出、异步处理，或每隔 N 条消息跳过一次以减少资源消耗。\n- ~ellama-name-prompt-words-count~: 用于生成名称的提示词数量。\n- 每个命令的提示模板。\n- ~ellama-chat-done-callback~: Ellama 聊天响应生成完成后调用的回调函数。它应该是一个接受单个参数（生成的文本字符串）的函数。\n- ~ellama-nick-prefix-depth~: 用户和助手昵称前缀的深度。默认值为 2。\n- ~ellama-sessions-directory~: 保存 Ellama 会话的目录。\n- ~ellama-major-mode~: Ellama 命令的主要模式。默认为 Org 模式。\n- ~ellama-session-auto-save~: 如果设置，则自动保存 Ellama 会话。默认开启。\n- ~ellama-naming-scheme~: 新会话的命名方式。\n- ~ellama-naming-provider~: 用于由 LLM 生成会话名称的 LLM 提供商。如果未设置，则使用 ~ellama-provider~。\n- ~ellama-chat-translation-enabled~: 如果设置，则启用聊天翻译。\n- ~ellama-translation-provider~: LLM 翻译提供商。如果未设置，则使用 ~ellama-provider~。\n- ~ellama-coding-provider~: LLM 编程任务提供商。如果未设置，则使用 ~ellama-provider~。\n- ~ellama-summarization-provider~: LLM 总结提供商。如果未设置，则使用 ~ellama-provider~。\n- ~ellama-show-quotes~: 在聊天缓冲区中显示引用内容。默认关闭。\n- ~ellama-chat-display-action-function~: ~ellama-chat~ 的显示操作函数。\n- ~ellama-instant-display-action-function~: ~ellama-instant~ 的显示操作函数。\n- ~ellama-translate-italic~: 在 Markdown 到 Org 的转换过程中翻译斜体文本。默认开启。\n- ~ellama-extraction-provider~: 用于数据提取的 LLM 提供商。\n- ~ellama-text-display-limit~: 上下文元素中文本显示的限制。\n- ~ellama-context-poshandler~: 上下文缓冲区显示的位置处理器。如果未设置，则使用 ~posframe-poshandler-frame-top-center~。\n- ~ellama-context-border-width~: 上下文缓冲区的边框宽度。\n- ~ellama-session-remove-reasoning~: 在 Ellama 提供答案后，移除会话中的内部推理。这可以改善与推理模型的长期沟通。默认开启。\n- ~ellama-session-hide-org-quotes~: 在 Ellama 会话缓冲区中隐藏 Org 引用。从现在起，思考标签将被引用块取代。如果启用此标志，推理步骤将在生成后以及会话加载时折叠起来。默认开启。\n- ~ellama-output-remove-reasoning~: 从 Ellama 输出中消除内部推理，以增强推理模型在各种应用中的通用性。\n- ~ellama-context-posframe-enabled~: 启用显示带有 Ellama 上下文的 posframe。\n- ~ellama-context-manage-display-action-function~: ~ellama-context-manage~ 的显示操作函数。默认值为 ~display-buffer-same-window~。\n- ~ellama-context-preview-element-display-action-function~: ~ellama-context-preview-element~ 的显示操作函数。\n- ~ellama-context-line-always-visible~: 使上下文头或模式行始终可见，即使上下文为空。\n- ~ellama-community-prompts-url~: 社区提示集合的 URL。\n- ~ellama-community-prompts-file~: 包含社区提示的 CSV 文件路径。该文件应位于您的 ~user-emacs-directory~ 中的 ~ellama~ 子目录内。\n- ~ellama-show-reasoning~: 如果启用，则在单独的缓冲区中显示推理过程。默认开启。\n- ~ellama-reasoning-display-action-function~: 推理过程的显示操作函数。\n- ~ellama-session-line-template~: 当前会话行的格式化模板。\n- ~ellama-debug~: 启用调试模式。启用后，生成的文本将被记录到 ~*ellama-debug*~ 缓冲区，并使用分隔符以便于跟踪调试信息。调试输出包括正在处理的原始文本，并且每次都会追加到调试缓冲区的末尾。\n- ~ellama-tools-allow-all~: 允许 ~ellama~ 在无需用户确认的情况下使用所有工具。此举存在风险，请自行承担后果。\n- ~ellama-tools-allowed~: 允许使用的 ~ellama~ 工具列表。此列表中的工具无需用户确认即可运行。\n- ~ellama-tools-argument-max-length~: 确认提示中函数参数的最大长度。默认值为 50。\n- ~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~ 设置文件缺失或格式错误，则工具调用将触发用户错误（故障安全机制）。\n- ~ellama-tools-srt-program~: 当 ~ellama-tools-use-srt~ 启用时使用的沙盒运行程序名称\u002F路径。默认值为 ~\"srt\"~。\n- ~ellama-tools-srt-args~: 在包装命令之前传递给 ~srt~ 的额外参数（例如 ~--settings \u002Fpath\u002Fto\u002Fsettings.json~）。这些参数也用于解析本地非 Shell 文件系统检查的设置文件路径（默认为 =~\u002F.srt-settings.json=，若未提供 ~--settings~\u002F~-s~ 则使用）。\n- ~ellama-blueprint-global-dir~: 存储蓝图文件的全局目录。\n- ~ellama-blueprint-local-dir~: 项目特定蓝图的本地目录名。\n- ~ellama-blueprint-file-extensions~: 被识别为蓝图文件的文件扩展名。\n- ~ellama-blueprint-variable-regexp~: 用于匹配蓝图变量（如 ~{var_name}~）的正则表达式。\n- ~ellama-skills-global-path~: 包含 Agent Skills 的全局目录路径。\n- ~ellama-skills-local-path~: 项目相关的本地 Agent Skills 路径。默认值为 ~\"skills\"~。\n- ~ellama-tools-subagent-default-max-steps~: 子代理自动继续步骤的默认最大数量。默认值为 30。\n- ~ellama-tools-subagent-roles~: 子代理的角色，包括提供商、系统提示和允许使用的工具。这是为 ~task~ 工具配置子代理的方式。\n\n** 工具输入\u002F输出的 DLP\n\nEllama 包含一个可选的工具调用数据丢失防护（DLP）层。它可以扫描：\n\n- 工具输入（从模型发送到工具的参数）\n- 工具输出（从工具返回给模型的字符串）\n\nDLP 层支持基于正则表达式的规则，以及从环境变量中提取的精确秘密检测（包括常见的编码变体，如 base64\u002Fbase64url 和 hex）。它还包含一个可选的基于 LLM 的语义检查，作为仅针对块级别的一种后备机制，用于处理那些看起来不安全但不符合确定性规则的有效载荷。\n\n推荐的初始部署方案：\n\n- 启用 DLP\n- 将模式设置为 ~monitor~\n- 在将选定路径切换到 ~enforce~ 之前，先审查事件\n- 如果启用 LLM 检测器，应从一个小的工具白名单开始\n\n最小化示例配置：\n\n#+BEGIN_SRC emacs-lisp\n (setopt ellama-tools-dlp-enabled t)\n (setopt ellama-tools-dlp-mode 'monitor)\n (setopt ellama-tools-dlp-log-targets '(memory))\n#+END_SRC\n\n关键设置：\n\n- ~ellama-tools-dlp-enabled~：启用对工具输入\u002F输出的 DLP 扫描。\n- ~ellama-tools-dlp-mode~：部署模式。使用 ~monitor~ 只进行检测和日志记录，或使用 ~enforce~ 来执行操作。\n- ~ellama-tools-dlp-regex-rules~：正则表达式检测规则（ID、模式、方向\u002F工具\u002F参数范围、启用\u002F禁用、大小写折叠）。\n- ~ellama-tools-dlp-scan-env-exact-secrets~：从环境变量中启用精确秘密检测（默认启用）。\n- ~ellama-tools-dlp-llm-check-enabled~：启用可选的隔离 LLM 安全分类器（默认禁用）。\n- ~ellama-tools-dlp-llm-provider~：用于隔离 LLM 安全检查的服务提供商。当为 nil 时，会回退到提取服务提供商，然后是默认提供商。\n- ~ellama-tools-dlp-llm-directions~：LLM 检测器可能运行的方向（~input~、~output~，或两者）。\n- ~ellama-tools-dlp-llm-max-scan-size~：LLM 检测器可以处理的最大字节数。超过此限制的有效载荷将跳过 LLM 检查。\n- ~ellama-tools-dlp-llm-tool-allowlist~：允许使用 LLM 检测器的工具名称列表。如果为 nil，则所有工具都符合条件。\n- ~ellama-tools-dlp-llm-run-policy~：仅在确定性检测结果为空时运行 LLM 检测器（~clean-only~），或在每次未被阻止的扫描中都运行（~always-unless-blocked~）。\n- ~ellama-tools-dlp-max-scan-size~：每次输入\u002F输出有效载荷扫描的最大字节数（默认 5 MB；较大的有效载荷会被截断以供扫描）。\n- ~ellama-tools-dlp-input-default-action~：在 ~enforce~ 模式下，输入检测结果的默认动作（~allow~、~warn~、~block~）。\n- ~ellama-tools-dlp-output-default-action~：在 ~enforce~ 模式下，输出检测结果的默认动作（~allow~、~warn~、~block~、~redact~）。\n- ~ellama-tools-dlp-output-warn-behavior~：输出 ~warn~ 判决的处理方式（~allow~、~confirm~ 或 ~block~）。\n- ~ellama-tools-dlp-policy-overrides~：按工具\u002F按参数的覆盖和例外情况。对于结构化的输入参数，嵌套的字符串值会使用类似路径的参数名进行扫描（例如 ~payload.items[0].token~）。覆盖 ~:arg~ 会匹配精确名称和嵌套路径前缀（例如 ~\"payload\"~ 会匹配 ~payload.items[0].token~）。\n- ~ellama-tools-dlp-log-targets~：事件日志目标（~memory~、~message~、~file~）。\n- ~ellama-tools-dlp-audit-log-file~：当启用 ~file~ 接收器时使用的 JSONL 路径。\n- ~ellama-tools-dlp-incident-log-max~：保留的最大内存事件数量。\n- ~ellama-tools-dlp-input-fail-open~ \u002F ~ellama-tools-dlp-output-fail-open~：当 DLP 自身发生内部错误时的行为。\n- ~ellama-tools-irreversible-enabled~：启用不可逆操作处理。\n- ~ellama-tools-irreversible-default-action~：默认的不可逆操作（~warn~ 或 ~block~，同时将监控模式降级为 ~warn-strong~）。\n- ~ellama-tools-irreversible-unknown-tool-action~：未知 MCP 工具的默认动作（~warn~ 或 ~allow~）。\n- ~ellama-tools-irreversible-require-typed-confirm~：要求输入特定短语才能解除不可逆警告。\n- ~ellama-tools-irreversible-project-overrides-enabled~：启用项目本地的不可逆覆盖政策。\n- ~ellama-tools-irreversible-project-overrides-file~：项目政策文件名。\n- ~ellama-tools-irreversible-project-trust-store-file~：用于存储仓库批准记录的用户信任库（仓库根目录 + 远程地址 + 政策哈希）。\n- ~ellama-tools-irreversible-scoped-bypass-default-ttl~：会话绕过条目的默认 TTL（秒）。\n- ~ellama-tools-output-line-budget-enabled~：在将文本返回给模型之前，启用按工具的输出行预算截断（默认启用）。\n- ~ellama-tools-output-line-budget-max-lines~：每个工具输出的最大行数（默认 ~200~）。\n- ~ellama-tools-output-line-budget-max-line-length~：在单行被截断之前，每行的最大字符数（默认 ~4000~）。\n- ~ellama-tools-output-line-budget-save-overflow-file~：当输出源文件未知时，将完整的溢出输出保存到临时文件中（默认 ~t~）。\n\n强制执行行为（v1）：\n\n- 输入 ~block~ 会阻止工具执行\n- 输入 ~warn~ 会在执行前要求明确确认\n- 输出 ~block~ 会返回一条安全的拒绝字符串\n- 输出 ~redact~ 会用占位符替换检测到的片段\n- 输出 ~warn~ 遵循 ~ellama-tools-dlp-output-warn-behavior~（默认为 ~confirm~）\n\nLLM 安全检查行为（v1）：\n\n- LLM 检测器仅在 ~ellama-tools-dlp-llm-check-enabled~ 不为 nil 时运行\n- 检查器使用一个隔离的结构化输出请求，且不涉及任何工具\n- 在 ~monitor~ 模式下，不安全的 LLM 判决会被记录，但不会改变结果\n- 在 ~enforce~ 模式下，不安全的 LLM 判决可能会导致 ~block~\n- LLM 检测结果绝不会触发 ~warn~ 或 ~redact~，也不会影响内容的编辑。\n\n不可逆行动安全（v1）：\n\n- 不可逆警告使用 ~warn-strong~，并要求输入确认短语 ~我明白这无法撤销~\n- 在 ~enforce~ 模式下，高置信度的不可逆检测结果会直接 ~block~\n- 在 ~monitor~ 模式下，高置信度的不可逆检测结果仍然需要输入确认，且不会直接 ~block~\n- 未知 MCP 工具的身份默认为 ~warn~（可通过 ~ellama-tools-irreversible-unknown-tool-action~ 进行配置）\n- 不可逆决策的优先顺序：~高置信度强制阻断~ > ~会话绕过~ > ~项目覆盖~ > 全局不可逆默认\n- 项目覆盖在仓库政策被明确信任之前会被忽略；信任与仓库根目录、远程 URL 和政策哈希绑定在一起\n- 不可逆决策的审计日志写入失败时会采取闭锁措施；在交互式会话中，可以通过一次额外的明确确认来覆盖这一决定。\n\n会话绕过助手：\n\n#+BEGIN_SRC emacs-lisp\n ;; 允许在此会话中对一个工具身份执行不可逆操作。\n (ellama-tools-dlp-add-session-bypass \"mcp-db\u002Fquery\" 3600 \"migration window\")\n#+END_SRC\n\n自主代理配置：\n\n自主代理需要一种低摩擦的策略。在每次普通的工具调用时都提示用户确认，反而会让用户养成盲目批准的习惯，这比采用少量高信号的提示要糟糕得多。推荐的配置如下：\n\n- 在批准的工作空间内，干净的读写操作会自动执行\n- 秘密泄露和类似提示注入的输出会被屏蔽或阻止\n- 模糊不清的危险操作需要用户键入确认，否则将采取失败封闭机制\n- 高置信度的破坏性操作会被直接阻止，不会弹出确认提示\n- 未知的MCP工具会发出警告，直到它们被分类\n\n~ellama-tools-allow-all~仅绕过正常的确认包装层。它并不会绕过DLP、不可逆操作检查、输出扫描或~srt~文件系统检查，因为DLP已经包裹了确认层。这使得~allow-all~仅在启用DLP强制执行且工具文件系统访问受限时才适用。\n\n自主编码的推荐基线：\n\n#+BEGIN_SRC emacs-lisp\n (with-eval-after-load 'ellama-tools\n ;; 让干净的调用无需重复提示即可运行。\n (setopt ellama-tools-allow-all t)\n\n ;; 必要的安全层。\n (setopt ellama-tools-dlp-enabled t)\n (setopt ellama-tools-dlp-mode 'enforce)\n\n ;; 偏好失败封闭行为以进行自主操作。\n (setopt ellama-tools-dlp-input-fail-open nil)\n (setopt ellama-tools-dlp-output-fail-open nil)\n\n ;; 保持秘密和输出保护措施处于激活状态。\n (setopt ellama-tools-dlp-scan-env-exact-secrets t)\n (setopt ellama-tools-dlp-input-default-action 'warn)\n (setopt ellama-tools-dlp-output-default-action 'redact)\n\n ;; 不可逆操作需要更强的意图确认。\n (setopt ellama-tools-irreversible-enabled t)\n (setopt ellama-tools-irreversible-default-action 'warn)\n (setopt ellama-tools-irreversible-require-typed-confirm t)\n\n ;; 保持遥测数据足够持久以便调整。\n (setopt ellama-tools-dlp-log-targets '(memory file))\n\n ;; 强烈建议在启用`ellama-tools-allow-all'时使用。\n (setopt ellama-tools-use-srt t)\n (setopt ellama-tools-srt-args\n '(\"--settings\" \"~\u002F.config\u002Fellama\u002Fsrt-autonomous.json\")))\n#+END_SRC\n\n使用一个只允许在当前项目和临时区域中写入的~srt~策略。为秘密、凭证、审计日志和系统路径添加明确的读写拒绝规则。请参阅SRT文件系统策略工具部分中的项目沙箱示例。\n\n对于危险情况，有两种合理的策略。由用户处理的危险情况仅要求DLP警告和不可逆操作确认：\n\n#+BEGIN_SRC emacs-lisp\n (setopt ellama-tools-dlp-input-default-action 'warn)\n (setopt ellama-tools-dlp-output-warn-behavior 'confirm)\n (setopt ellama-tools-irreversible-default-action 'warn)\n (setopt ellama-tools-irreversible-require-typed-confirm t)\n#+END_SRC\n\n中等风险的不可逆操作需要输入确认短语“我理解这无法撤销”。高置信度的破坏性操作在~enforce~模式下仍会被阻止，即使有会话或项目的覆盖设置也无法改变这一结果。\n\n安全回退机制更适合无人值守的代理：\n\n#+BEGIN_SRC emacs-lisp\n (setopt ellama-tools-dlp-input-default-action 'block)\n (setopt ellama-tools-dlp-output-warn-behavior 'block)\n (setopt ellama-tools-irreversible-default-action 'block)\n (setopt ellama-tools-irreversible-require-typed-confirm t)\n#+END_SRC\n\n采用安全回退机制时，代理会收到拒绝信息，并需寻找更安全的路径。这样可以避免将用户确认变成例行公事式的批准习惯。\n\n通过收紧工具角色而非削弱安全性来减少提示疲劳。避免为自主子代理使用~:tools :all~。优先选择以下独立角色：\n\n- 只读探索者，不含~shell_command~\n- 具有文件工具和沙盒化~shell_command~的编码员\n- 仅当任务明确需要Shell访问时才使用Bash角色\n- 除非有意中断用户，否则不使用~ask_user~工具\n\n对于MCP工具，初始将~ellama-tools-irreversible-unknown-tool-action~设置为~warn~。观察常见安全工具后，可通过~ellama-tools-irreversible-tool-risk-overrides~或受信任的项目覆盖来分类可信工具身份。仅对特定工具身份和较短的TTL使用~ellama-tools-dlp-add-session-bypass~；切勿为减少提示而全局禁用DLP。\n\n如果~srt~不可用，则不要为自主编码使用全局的~ellama-tools-allow-all~。应改用一个包含少量安全只读工具的~ellama-tools-allowed~列表，并将可能产生变化的工具置于确认或DLP回退机制之下。\n\n工具输出截断行为：\n\n- 每个工具的输出负载都会应用行预算\n- 如果负载超过行预算，模型会收到截断通知以及被截断的部分内容\n- 如果行数超过~ellama-tools-output-line-budget-max-line-length~，这些行会被缩短，并标注为~...[行被截断]~\n- 当来源已知时（例如~read_file~、~lines_range~、~grep_in_file~），通知会包含源路径，并建议使用~lines_range~和~grep_in_file~\u002F~grep~\n- 当来源未知时（例如通用工具输出），完整输出会被保存到临时文件中（如果启用），并在通知中注明文件名。\n\n正则表达式规则示例：\n\n#+BEGIN_SRC emacs-lisp\n (setopt ellama-tools-dlp-regex-rules\n '((:id \"openai-key\"\n :pattern \"sk-[[:alnum:]-]+\"\n :directions (input output))\n (:id \"pem-header\"\n :pattern \"-----BEGIN [A-Z ]+-----\"\n :directions (output)\n :enabled t)))\n#+END_SRC\n\n范围覆盖示例（忽略嘈杂的Shell命令输入）：\n\n#+BEGIN_SRC emacs-lisp\n (setopt ellama-tools-dlp-policy-overrides\n '((:tool \"shell_command\"\n :direction input\n :arg \"cmd\"\n :except t)))\n#+END_SRC\n\n结构化输入负载的覆盖示例（顶级参数前缀匹配）：\n\n#+BEGIN_SRC emacs-lisp\n (setopt ellama-tools-dlp-policy-overrides\n '((:tool \"write_file\"\n :direction input\n :arg \"content\"\n :action warn)))\n#+END_SRC\n\n调优辅助工具：\n\n- ~M-x ellama-tools-dlp-reset-runtime-state~\n- ~M-x ellama-tools-dlp-show-incident-stats~\n- ~(ellama-tools-dlp-recent-incidents)~\n- ~(ellama-tools-dlp-incident-stats)~\n- ~(ellama-tools-dlp-incident-stats-report)~\n\n事件统计包括按风险等级、规则ID、工具身份和决策类型（包括~bypass~）的汇总。\n\n有关更详细的部署\u002F调优指南及更多覆盖示例，请参阅~docs\u002Fdlp_rollout_guide.md~。\n\n故障排除：\n\n- 反复出现不可逆操作警告：使用~ellama-tools-irreversible-tool-risk-overrides~对可信MCP工具进行分类，或为单一工具身份使用短期会话绕过\n- 绕过到期：会话绕过按TTL到期并自动移除；必要时可使用~ellama-tools-dlp-add-session-bypass~重新添加\n- 误报：通过~ellama-tools-dlp-recent-incidents~检查事件，并在将更多路径转为强制执行之前调整正则规则或覆盖设置\n\n** SRT文件系统工具策略\n\n当~ellama-tools-use-srt~为非空时，~srt~设置文件是工具文件系统策略的真实依据：\n\n- 基于 shell 的工具（~shell_command~、~grep~、~grep_in_file~）由外部的 ~srt~ 运行时强制执行。\n- 非 shell 文件工具（~read_file~、~write_file~、~append_file~、~prepend_file~、~edit_file~、~directory_tree~、~move_file~、~count_lines~、~lines_range~）应用源自同一 ~srt~ 设置文件的本地检查。\n\n当前支持的本地文件系统子集：\n\n- ~filesystem.denyRead~\n- ~filesystem.allowWrite~\n- ~filesystem.denyWrite~（优先于 ~allowWrite~）\n\n对于不可逆的审计加固，应将 ~ellama-tools-dlp-audit-log-file~ 置于 ~allowWrite~ 之外，并为审计目录添加明确的 ~denyRead~\u002F~denyWrite~ 条目。\n\n本地检查会故意忽略无关的 ~srt~ 键（例如 ~network.*~）。如果 ~filesystem~ 部分缺失，本地检查将使用与 ~srt~ 相同的文件系统访问默认值：默认允许读取，而写入则被拒绝，除非被 ~allowWrite~ 允许。\n\n本地检查的路径匹配说明：\n\n- ~srt~ 规则中的相对路径会相对于 Emacs 的 ~default-directory~ 解析。\n- ~~ 会扩展为当前用户的主目录。\n- 支持字面路径、目录前缀规则和 glob 模式。\n- 格式错误或不支持的模式会触发 ~user-error~（失败即关闭）。\n\n当 ~ellama-tools-use-srt~ 启用时，以下情况会导致本地检查失败并关闭：\n\n- ~srt~ 未安装。\n- 解析后的设置文件不存在。\n- 设置文件是格式错误的 JSON。\n- 相关的 ~filesystem~ 键的形状无效。\n\n项目沙箱的 ~srt~ 配置示例：\n\n#+BEGIN_SRC json\n{\n \"network\": {\n \"allowedDomains\": [\n \"github.com\",\n \"*.github.com\",\n \"api.github.com\",\n \"*.npmjs.org\"\n ],\n \"deniedDomains\": [],\n \"allowUnixSockets\": [],\n \"allowLocalBinding\": false\n },\n \"filesystem\": {\n \"denyRead\": [\n \"~\u002F.srt-settings.json\",\n \"~\u002F.ssh\",\n \"~\u002F.aws\",\n \"~\u002F.gnupg\u002F\",\n \"~\u002F.config\u002Fgcloud\u002F\",\n \"~\u002F.azure\u002F\",\n \"~\u002F.kube\u002F\",\n \"~\u002F.docker\u002F\",\n \"~\u002F.netrc\",\n \"~\u002F.npmrc\",\n \"~\u002F.pypirc\",\n \"~\u002F.git-credentials\",\n \"~\u002F.emacs.d\u002Fellama-dlp-audit.jsonl\",\n \".env\",\n \".env.*\",\n \".env*.local\",\n \"*.env\",\n \"*-credentials.json\",\n \"*serviceAccount*.json\",\n \"*service-account*.json\",\n \"kubeconfig\",\n \"*-secret.yaml\",\n \"secrets.yaml\",\n \"*.pem\",\n \"*.key\",\n \"*.p12\",\n \"*.pfx\",\n \"*.tfstate\",\n \"*.tfstate.backup\",\n \".terraform\u002F\",\n \".vercel\u002F\",\n \".netlify\u002F\",\n \".supabase\u002F\",\n \"dump.sql\",\n \"backup.sql\",\n \"*.dump\"\n ],\n \"allowWrite\": [\n \".\",\n \"src\u002F\",\n \"test\u002F\",\n \"docs\u002F\",\n \"\u002Ftmp\u002Fellama-agent\"\n ],\n \"denyWrite\": [\n \"~\u002F.srt-settings.json\",\n \"~\u002F.ssh\",\n \"~\u002F.aws\",\n \"~\u002F.gnupg\u002F\",\n \"~\u002F.config\u002Fgcloud\u002F\",\n \"~\u002F.azure\u002F\",\n \"~\u002F.kube\u002F\",\n \"~\u002F.docker\u002F\",\n \"~\u002F.netrc\",\n \"~\u002F.npmrc\",\n \"~\u002F.pypirc\",\n \"~\u002F.git-credentials\",\n \"~\u002F.emacs.d\u002Fellama-dlp-audit.jsonl\",\n \".env\",\n \".env.*\",\n \".env*.local\",\n \"*.env\",\n \"*-credentials.json\",\n \"*serviceAccount*.json\",\n \"*service-account*.json\",\n \"kubeconfig\",\n \"*-secret.yaml\",\n \"secrets.yaml\",\n \"*.pem\",\n \"*.key\",\n \"*.p12\",\n \"*.pfx\",\n \"*.tfstate\",\n \"*.tfstate.backup\",\n \".terraform\u002F\",\n \".vercel\u002F\",\n \".netlify\u002F\",\n \".supabase\u002F\",\n \"dump.sql\",\n \"backup.sql\",\n \"*.dump\",\n \"\u002Fetc\u002F\",\n \"\u002Fusr\u002F\",\n \"\u002Fbin\u002F\",\n \"\u002Fsbin\u002F\",\n \"\u002Fboot\u002F\",\n \"\u002Froot\u002F\",\n \"~\u002F.bash_history\",\n \"~\u002F.zsh_history\",\n \"~\u002F.node_repl_history\",\n \"~\u002F.bashrc\",\n \"~\u002F.zshrc\",\n \"~\u002F.profile\",\n \"~\u002F.bash_profile\"\n ]\n },\n \"ignoreViolations\": {\n \"npm\": [\n \"\u002Fprivate\u002Ftmp\"\n ]\n },\n \"enableWeakerNestedSandbox\": false,\n \"enableWeakerNetworkIsolation\": false\n}\n#+END_SRC\n\n除非代理程序明确需要本地套接字，否则请保持 ~allowUnixSockets~ 为空。例如，添加 ~\u002Fvar\u002Frun\u002Fdocker.sock~ 将赋予沙箱广泛的 Docker 控制权限，因此应被视为特权能力。\n\nEmacs 配置示例：\n\n#+BEGIN_SRC emacs-lisp\n (setopt ellama-tools-use-srt t)\n (setopt ellama-tools-srt-args\n '(\"--settings\" \"\u002Fpath\u002Fto\u002F.srt-settings.json\"))\n#+END_SRC\n\n一致性测试（实际 ~srt~ 运行时 vs 本地 ~ellama~ 检查）：\n\n- ~make test-srt-integration~：运行主机一致性测试（需要安装 ~srt~）。\n- ~make test-srt-integration-linux~：在 Linux 语义下通过 Docker 运行一致性测试。需要 Docker，并且会运行一个特权容器（~--privileged~）。\n\n* 上下文管理\n\nEllama 允许您向大型语言模型（LLM）提供上下文，以提高响应的相关性和质量。上下文充当背景信息、数据或指令，引导 LLM 理解您的提示。如果没有上下文，LLM 将完全依赖其预先存在的知识，而这可能并不总是合适的。\n\nEllama 维护着一个“全局上下文”，它是由文本块组成的集合，在 LLM 回应提示时可供其访问。这个全局上下文会在发送给 LLM 之前附加到您的提示中。此外，Ellama 还支持“临时上下文”，它是暂时性的，仅适用于单次请求。\n\n一些命令会自动将内容作为临时上下文添加：~ellama-ask-about~、~ellama-code-review~、~ellama-write~ 和 ~ellama-code-add~。\n\n** 上下文管理的瞬态菜单\n\nEllama 提供了一个可通过主菜单访问的瞬态菜单，用于更便捷地管理上下文元素。该菜单可通过主瞬态菜单的“系统”分支进入，然后选择“上下文命令”。\n\n上下文命令瞬态菜单的结构如下：\n\n上下文命令：\n\n- 选项：提供管理临时上下文的选项。\n - “-e” “使用临时上下文” ~--ephemeral~\n- 添加：提供将内容添加到全局或临时上下文的选项。\n - “b” “添加缓冲区” ~ellama-transient-add-buffer~\n - “d” “添加目录” ~ellama-transient-add-directory~\n - “f” “添加文件” ~ellama-transient-add-file~\n - “s” “添加选区” ~ellama-transient-add-selection~\n - “i” “添加信息节点” ~ellama-transient-add-info-node~\n- 管理：提供管理全局上下文的选项。\n - “m” “管理上下文” ~ellama-context-manage~ — 打开上下文管理缓冲区。\n - “D” “删除元素” ~ellama-context-element-remove-by-name~ — 按名称删除元素。\n - “r” “上下文重置” ~ellama-context-reset~ — 清除整个全局上下文。\n- 退出：（“q” “退出” ~transient-quit-one~）— 关闭上下文命令瞬态菜单。\n\n** 管理上下文\n\n~ellama-context-manage~ 会打开一个专用的缓冲区——上下文管理缓冲区——您可以在其中查看、修改和组织全局上下文。在此缓冲区内：\n\n+ ~n~: 移动到下一个上下文元素。\n+ ~p~: 移动到上一个上下文元素。\n+ ~q~: 退出上下文管理缓冲区。\n+ ~g~: 刷新上下文管理缓冲区的内容。\n+ ~a~: 添加一个新的上下文元素（类似于 ~ellama-context-add-selection~）。\n+ ~RET~: 预览当前点处的上下文元素内容。\n\n** 注意事项\n\n大型语言模型具有有限的上下文窗口大小，限制了它们可以处理的文本总量。请注意上下文的大小，以避免截断或性能下降。不相关的上下文会稀释信息，妨碍语言模型的关注度。确保上下文保持最新，以便获得准确的信息。通过尝试不同的上下文管理方法，可以针对特定用例优化性能。\n\n* 小模式\n\nEmacs 的 Ellama 包提供了一系列小模式，旨在通过在编辑器界面中直接提供上下文相关信息来增强用户体验。这些小模式专注于更新标题行和模式行中的相关细节，从而更轻松地管理和导航多个会话和缓冲区。\n\n主要功能包括：\n\n- 上下文标题行模式：~ellama-context-header-line-mode~ 及其全局版本 ~ellama-context-header-line-global-mode~ 会更新标题行，以显示添加到全局 Ellama 上下文中的元素。这对于跟踪当前上下文中包含哪些信息非常有用。\n- 上下文模式行模式：同样地，~ellama-context-mode-line-mode~ 和 ~ellama-context-mode-line-global-mode~ 直接在模式行中提供有关当前全局上下文的信息，确保用户始终一目了然地掌握相关信息。\n- 会话标题行模式：~ellama-session-header-line-mode~ 及其全局版本会在标题行中显示当前的 Ellama 会话 ID，帮助用户高效管理多个会话。\n- 会话模式行模式：~ellama-session-mode-line-mode~ 及其全局版本则通过在模式行中显示会话 ID，提供了另一种跟踪会话 ID 的方式。\n\n这些小模式可以通过特定命令轻松开启或关闭，为希望在所有缓冲区中全局启用这些功能，或仅在个别缓冲区中选择性启用的用户提供灵活性。\n\n** ellama-context-header-line-mode\n\n描述：切换 Ellama 上下文标题行模式。该小模式会更新标题行以显示上下文相关信息。\n\n使用方法：要启用或禁用 ~ellama-context-header-line-mode~，请使用以下命令：\n\n M-x ellama-context-header-line-mode\n\n启用后，此模式会向 ~window-state-change-hook~ 添加钩子，以便在窗口状态发生变化时更新标题行。它还会调用 ~ellama-context-update-header-line~ 来初始化标题行，显示上下文相关信息。\n\n禁用时，它会从 ~header-line-format~ 中移除 ~(:eval (ellama-context-line))~ 的评估。\n\n** ellama-context-header-line-global-mode\n\n描述：~ellama-context-header-line-mode~ 的全局化版本。此模式确保在所有缓冲区中启用 ~ellama-context-header-line-mode~。\n\n使用方法：要启用或禁用 ~ellama-context-header-line-global-mode~，请使用以下命令：\n\n M-x ellama-context-header-line-global-mode\n\n这个全局化的小模式提供了一种便捷的方式，无论正在编辑哪个缓冲区，都能确保始终显示上下文相关的标题行信息。\n\n** ellama-context-mode-line-mode\n\n描述：切换 Ellama 上下文模式行模式。该小模式会更新模式行以显示上下文相关信息。\n\n使用方法：要启用或禁用 ~ellama-context-mode-line-mode~，请使用以下命令：\n\n M-x ellama-context-mode-line-mode\n\n启用后，此模式会向 ~window-state-change-hook~ 添加钩子，以便在窗口状态发生变化时更新模式行。它还会调用 ~ellama-context-update-mode-line~ 来初始化模式行，显示上下文相关信息。\n\n禁用时，它会从 ~mode-line-format~ 中移除 ~(:eval (ellama-context-line))~ 的评估。\n\n** ellama-context-mode-line-global-mode\n\n描述：~ellama-context-mode-line-mode~ 的全局化版本。此模式确保在所有缓冲区中启用 ~ellama-context-mode-line-mode~。\n\n使用方法：要启用或禁用 ~ellama-context-mode-line-global-mode~，请使用以下命令：\n\n M-x ellama-context-mode-line-global-mode\n\n这个全局化的小模式提供了一种便捷的方法，无论编辑哪个缓冲区，都能确保始终显示上下文相关的模式行信息。\n\n** Ellama 会话标题行模式\n\n~ellama-session-header-line-mode~ 是一种小模式，允许您在 Emacs 缓冲区的标题行中显示当前的 Ellama 会话 ID。此功能有助于跟踪您正在使用的会话，尤其是在管理多个会话时非常有用。\n\n*** 启用和禁用\n\n要启用此模式，请使用以下命令：\n#+BEGIN_SRC emacs-lisp\nM-x ellama-session-header-line-mode\n#+END_SRC\n\n这将切换标题行中会话 ID 的显示。您也可以通过以下命令在全球范围内所有缓冲区中启用或禁用它：\n#+BEGIN_SRC emacs-lisp\nM-x ellama-session-header-line-global-mode\n#+END_SRC\n\n*** 自定义\n\n会话 ID 使用名为 ~ellama-face~ 的可自定义面显示。您可以自定义此面以更改其外观。\n\n** Ellama 会话模式行模式\n\n~ellama-session-mode-line-mode~ 是一种小模式，允许您在 Emacs 缓冲区的模式行中显示当前的 Ellama 会话 ID。此功能提供了另一种跟踪您正在使用的会话的方式，尤其在管理多个会话时非常有用。\n\n*** 启用和禁用\n\n要启用此模式，请使用以下命令：\n#+BEGIN_SRC emacs-lisp\nM-x ellama-session-mode-line-mode\n#+END_SRC\n\n这将切换模式行中会话 ID 的显示。您也可以通过以下命令在全球范围内所有缓冲区中启用或禁用它：\n#+BEGIN_SRC emacs-lisp\nM-x ellama-session-mode-line-global-mode\n#+END_SRC\n\n*** 自定义\n\n会话 ID 使用名为 ~ellama-face~ 的可自定义面显示。您可以自定义此面以更改其外观。\n\n* 使用蓝图\n\nEllama 中的蓝图是指预定义的模板或结构，用于促进聊天会话的创建和管理。这些蓝图旨在通过提供交互的结构化框架，简化生成一致且高质量输出的过程。\n\n** Ellama 蓝图的关键组成部分\n\n1. 行动：这是蓝图的主要标识符，代表蓝图的动作或目的。\n2. 提示：用于启动聊天会话的内容。这可以包括指令、上下文或其他任何引导对话所需的相关信息。\n3. 适用于开发者：一个标志，指示该蓝图是否面向开发者。\n\n** 创建和管理蓝图\n\nEllama 提供了多个功能来创建、选择和管理蓝图：\n\n- ~ellama-blueprint-create~：此函数允许用户从当前缓冲区创建一个新的蓝图。它会提示输入名称以及该蓝图是否面向开发者，然后将当前缓冲区的内容保存为提示。\n \n- ~ellama-blueprint-new~：此函数会创建一个新的蓝图缓冲区，如果当前区域被选中，则可以选择插入该区域的内容。\n \n- ~ellama-blueprint-select~：此函数允许用户从蓝图集合中选择一个提示。它会根据提示是否面向开发者及其来源（用户自定义、社区或全部）进行过滤。\n\n** 蓝图文件\n\n你也可以将蓝图存储为纯文本文件。可以在全局范围内存储在 ~ellama-blueprint-global-dir~ 目录下，或者在项目本地目录 ~ellama-blueprint-local-dir~ 中，使用 ~ellama-blueprint-file-extensions~ 扩展名。\n\n** 变量管理\n\n蓝图可以包含在运行聊天会话之前需要填充的变量。Ellama 提供了填充这些变量的命令：\n\n- ~ellama-blueprint-fill-variables~：提示用户输入当前缓冲区中找到的变量值，并进行填充。\n\n** 键位映射和模式\n\nEllama 为缓冲区内管理蓝图提供了一个局部键位映射 ~ellama-blueprint-mode-map~。该模式包括将缓冲区发送到新的聊天会话、杀死当前缓冲区、创建新蓝图以及填充变量等按键绑定。\n\n~ellama-blueprint-mode~ 是基于 ~text-mode~ 的派生模式，它为花括号中的变量提供语法高亮，并设置局部键位映射。\n\n当处于 ~ellama-blueprint-mode~ 时，以下键位绑定可用：\n\n- ~C-c C-c~：将当前缓冲区发送到新的聊天会话并杀死当前缓冲区。\n- ~C-c C-k~：杀死当前缓冲区。\n- ~C-c c~：从当前缓冲区创建一个蓝图。\n- ~C-c v~：填充当前蓝图中的变量。\n\n** 临时菜单\n\nEllama 包含临时菜单，方便访问蓝图相关命令。~ellama-transient-blueprint-menu~ 提供了与选定蓝图聊天、创建新蓝图以及退出菜单的选项。\n\n~ellama-transient-main-menu~ 将蓝图菜单集成到主菜单中，为所有 Ellama 命令提供了一个全面的界面。\n\n** 以编程方式运行蓝图\n\n~ellama-blueprint-run~ 函数使用指定的蓝图启动聊天会话。它会根据提供的参数预先填充变量。\n\n#+BEGIN_SRC emacs-lisp\n (defun my-chat-with-morpheus ()\n \"开始与墨菲斯聊天。\"\n (interactive)\n (ellama-blueprint-run \"Character\" '(:character \"Morpheus\" :series \"Matrix\")))\n\n (global-set-key (kbd \"C-c e M\") #'my-chat-with-morpheus)\n#+END_SRC\n\n* MCP 集成\n\n你也可以将 MCP（模型上下文协议）工具与 ~ellama~ 一起使用。你需要 Emacs 30 或更高版本。安装 ~mcp.el~ - https:\u002F\u002Fgithub.com\u002Flizqwerscott\u002Fmcp.el。例如，要为 ~ellama~ 添加网页搜索功能，你可以添加 duckduckgo mcp 服务器（https:\u002F\u002Fgithub.com\u002Fnickclyde\u002Fduckduckgo-mcp-server）：\n\n#+begin_src emacs-lisp\n(use-package mcp\n :ensure t\n :demand t\n :custom\n (mcp-hub-servers\n `((\"ddg\" . (:command \"uvx\"\n\t\t\t:args\n\t\t\t(\"duckduckgo-mcp-server\")))))\n :config\n (require 'mcp-hub)\n (mcp-hub-start-all-server\n (lambda ()\n (let ((tools (mcp-hub-get-all-tool :asyncp t :categoryp t)))\n (mapcar #'(lambda (tool)\n\t\t (apply #'ellama-tools-define-tool\n\t\t\t (list tool)))\n\t tools)))))\n#+end_src\n\n当使用 ~:categoryp t~ 时，ellama 会推导出稳定的 MCP 工具身份，格式为 ~\u003Ccategory>\u002F\u003Ctool-name>~（例如 ~mcp-ddg\u002Fsearch~）。不可逆的策略、审计和覆盖操作都以此身份为关键。\n\n* 代理技能\n\nEllama 支持 *代理技能*，这是一种轻量级的扩展 AI 功能的格式。技能仅在需要时加载到上下文中（渐进式披露）。\n\n** 目录结构\n\nEllama 会在两个位置查找技能：\n1. 全局：=~\u002F.emacs.d\u002Fellama\u002Fskills\u002F=（可通过 ~ellama-skills-global-path~ 自定义）\n2. 项目本地：你的项目根目录下的 ~skills\u002F~ 目录（可通过 ~ellama-skills-local-path~ 自定义）\n\n一个技能是一个包含 ~SKILL.md~ 文件的目录。该文件至少包含元数据（~name~ 和 ~description~）以及指示代理如何执行特定任务的说明。技能还可以捆绑脚本、模板和参考资料。\n\n#+begin_src\nmy-project\u002F\n└──skills\u002F\n └── pdf-processing\u002F\n ├── SKILL.md # 必需：说明 + 元数据\n ├── scripts\u002F # 可选：可执行代码\n ├── references\u002F # 可选：文档\n └── assets\u002F # 可选：模板、资源\n#+end_src\n\n** 创建技能\n\nSKILL.md 必须包含 YAML 前言：\n\n#+begin_src markdown\n---\nname: pdf-processing\ndescription: 从 PDF 中提取文本并进行总结。\n---\n\n\n\n# PDF 处理说明\n要从 PDF 中提取文本...\n#+end_src\n\n** 工作原理\n\n*自动发现*：每当开始聊天时，Ellama 会自动扫描技能目录。*上下文*：技能的元数据（名称、描述、位置）会被注入到系统提示中。*激活*：LLM 会在需要时使用 read_file 工具加载 SKILL.md 的内容。\n\n* 致谢\n\n感谢 [[https:\u002F\u002Fgithub.com\u002Fjmorganca][Jeffrey Morgan]] 的优秀项目 [[https:\u002F\u002Fgithub.com\u002Fjmorganca\u002Follama][ollama]]。没有这个项目，本项目将无法存在。\n\n感谢 [[https:\u002F\u002Fgithub.com\u002Fzweifisch][zweifisch]] - 我从 [[https:\u002F\u002Fgithub.com\u002Fzweifisch\u002Follama][ollama.el]] 中获得了一些关于 Emacs 中 ollama 客户端能做什么的想法。\n\n感谢 [[https:\u002F\u002Fgithub.com\u002FDavid-Kunz][Dr. David A. Kunz]] - 我从 [[https:\u002F\u002Fgithub.com\u002FDavid-Kunz\u002Fgen.nvim][gen.nvim]] 中获得了更多灵感。\n\n感谢 [[https:\u002F\u002Fgithub.com\u002Fahyatt][Andrew Hyatt]] 提供的 ~llm~ 库。如果没有它，就只能支持 ~ollama~ 了。\n\n* 贡献\n\n如需贡献，请提交拉取请求或报告错误。本库是 GNU ELPA 的一部分；重大贡献必须由持有 FSF 论文的人士提出。或者，你也可以编写模块并在其他仓库如 MELPA 上分享。\n\n* GNU 自由文档许可证\n:PROPERTIES:\n:APPENDIX: t\n:END:\n\n#+texinfo: @include doclicense.texi\n\n#+begin_export html\n\u003Cpre>\n\n GNU 自由文档许可证\n 第 1.3 版，2008 年 11 月 3 日\n\n\n 版权所有 © 2000, 2001, 2002, 2007, 2008 自由软件基金会，美国\n \u003Chttps:\u002F\u002Ffsf.org\u002F>\n 每个人都有权复制和分发本许可证文件的完整副本，但不得对其进行修改。\n\n0. 序言\n\n本许可证的目的在于使手册、教科书或其他具有功能性和实用性的文档在自由的意义上成为“自由”文档：确保每个人都有权以复制和再分发该文档的实际自由，无论是否对其进行修改，也无论出于商业或非商业目的。其次，本许可证还为作者和出版者提供了一种方式，使其能够因其工作而获得应有的认可，同时不对其它人所做的修改承担责任。\n\n本许可证属于一种“ copyleft ”许可证，这意味着该文档的衍生作品本身也必须以相同的方式保持自由。它与 GNU 通用公共许可证相辅相成，后者是专为自由软件设计的 copyleft 许可证。\n\n我们设计本许可证的初衷是为了将其用于自由软件的手册，因为自由软件需要自由的文档：一个自由的程序应当附带提供与该软件同等自由的手册。然而，本许可证并不局限于软件手册；它可以用于任何文字作品，不论其主题为何，也不论其是以印刷书籍形式出版还是以其他形式发布。我们主要建议将本许可证应用于以教学或参考为目的的作品。\n\n\n1. 适用范围与定义\n\n本许可证适用于任何媒介上的手册或其他作品，只要其中包含由版权所有者放置的声明，表明该作品可根据本许可证的条款进行分发。此类声明授予一项全球性的、免版税的、无限期的许可，允许根据本许可证中规定的条件使用该作品。“文档”指代上述任何手册或作品。任何公众成员均为被许可人，并在本许可证中被称为“您”。如果您以需要依据版权法获得许可的方式复制、修改或分发该作品，则视为您已接受本许可证。\n\n“修改版本”是指包含文档或其部分内容的作品，无论是完全照搬原文，还是经过修改和\u002F或翻译成另一种语言。\n\n“次要部分”是指文档中专门讨论文档的出版者或作者与其整体主题（或相关事项）之间关系的附录或前言部分，且不包含任何可以直接归入该整体主题的内容。（例如，如果文档部分是数学教材，则次要部分不得解释任何数学内容。）这种关系可以是与主题或相关事项的历史渊源，也可以是在法律、商业、哲学、伦理或政治等方面的相关立场。\n\n“不变部分”是指在声明文档依据本许可证发布时，被指定为不变部分的某些次要部分。如果某一部分不符合上述关于次要部分的定义，则不得被指定为不变部分。文档可以不包含任何不变部分。如果文档未明确指出任何不变部分，则视为不存在不变部分。\n\n“封面文字”是指在声明文档依据本许可证发布时，被列为前封面文字或后封面文字的若干简短文本段落。前封面文字不得超过5个词，后封面文字不得超过25个词。\n\n“透明”副本是指以机器可读格式呈现的文档副本，其格式规范向公众公开，适合使用通用文本编辑器直接编辑文档，或（对于由像素组成的图像）使用通用绘图程序进行编辑，或（对于绘图）使用广泛可用的绘图编辑软件进行编辑；并且适合输入到文本排版程序中，或自动转换为多种可用于文本排版程序的格式。如果副本采用看似透明的文件格式，但其标记语言或缺乏标记语言的设计旨在阻止或抑制读者后续修改，则该副本不被视为“透明”。若图像格式被用于表示大量文本，则该图像格式也不属于“透明”格式。非“透明”的副本被称为“不透明”副本。\n\n适合用作“透明”副本的格式包括：无标记的纯 ASCII 文本、Texinfo 输入格式、LaTeX 输入格式、使用公开可用 DTD 的 SGML 或 XML，以及符合标准的简单 HTML、PostScript 或 PDF，这些格式专为人工修改而设计。透明图像格式的例子包括 PNG、XCF 和 JPG。不透明格式则包括只能由专有文字处理软件读取和编辑的专有格式，以及 DTD 和\u002F或处理工具并不普遍可用的 SGML 或 XML，还有某些文字处理软件仅用于输出而生成的机器自动生成的 HTML、PostScript 或 PDF。\n\n“扉页”对于印刷书籍而言，是指书的扉页本身，加上为清晰地载明本许可证要求出现在扉页上的信息所需的后续页面。对于没有传统意义上的扉页的作品，“扉页”是指靠近作品标题最显著位置的文本，位于正文开始之前。\n\n“出版者”是指向公众分发文档副本的任何个人或实体。\n\n“标题为 XYZ 的部分”是指文档中名称为 XYZ 的子单元，或者其标题中包含 XYZ，且在括号内注明了 XYZ 在另一种语言中的译文。（此处 XYZ 代表下文中提到的具体部分名称，如“致谢”、“献词”、“推荐语”或“历史”等。）在修改文档时“保留该部分的标题”，是指按照本定义，该部分仍应被视为“标题为 XYZ 的部分”。\n\n文档可以在声明本许可证适用于该文档的公告旁包含免责声明。这些免责声明被视为通过引用纳入本许可证，但仅限于免除担保责任的部分；除此之外，这些免责声明可能具有的任何其他含义均无效，且对本许可证的含义不产生影响。\n\n2. 原样复制\n\n您可以在任何媒介上复制并分发文档，无论是商业性还是非商业性，前提是所有副本中都必须完整地复制本许可证、版权声明以及声明本许可证适用于该文档的许可公告，并且您不得对该许可证所规定的条件附加任何其他限制。您不得使用技术手段来阻碍或控制他人阅读或进一步复制您制作或分发的副本。不过，您可以接受针对副本的报酬。如果您分发的副本数量足够多，则还必须遵守第3节的规定。\n\n您还可以在上述相同条件下出借副本，并可公开展示副本。\n\n\n3. 大量复制\n\n如果您出版文档的印刷副本（或通常带有印刷封面的介质副本），数量超过100份，并且文档的许可声明要求包含封皮文字，您必须用封面将这些副本封装起来，封面上应清晰可辨地印上所有这些封皮文字：前封皮文字印在封面上，后封皮文字印在封底上。两面封皮还必须清楚且易于辨认地表明您是这些副本的出版者。前封皮必须完整呈现文档标题，且标题中的每个词都应同样突出、醒目。您还可以在封面上添加其他内容。只要封面所做的修改仅限于封面本身，同时保留文档标题并满足上述条件，这些修改在其他方面即可被视为原文复制。\n\n如果任一封面所需的文本内容过多而无法清晰地容纳，您应当将列出的前若干条（在合理范围内尽可能多的条目）印在实际封面上，其余内容则延续至相邻页面。\n\n如果您出版或分发超过100份文档的不透明副本，您必须在每一份不透明副本中附带一份机器可读的透明副本，或者在每份不透明副本中注明一个计算机网络地址，使广大网络用户能够通过公共标准网络协议免费下载一份不含附加内容的完整透明副本。如果您选择后一种方式，则在开始大量分发不透明副本时，您必须采取合理谨慎的措施，以确保该透明副本在所注明的地址上持续可用，直至自您最后一次直接或通过代理人、零售商向公众分发该版本的不透明副本之日起至少一年之后。\n\n建议您在重新分发大量副本之前，尽早与文档作者取得联系，以便他们有机会为您提供文档的更新版本；但这并非强制性要求。\n\n4. 修改\n\n您可以在遵守上述第2节和第3节规定的前提下，复制并分发文档的修改版本，但前提是您必须以本许可证的完全相同条款发布修改版本，并使该修改版本取代原文档的地位，从而授权任何持有该修改版本副本的人对其进行分发和修改。此外，您还必须在修改版本中做到以下几点：\n\nA. 在扉页（以及如有封面的话，在封面上）使用一个不同于原文档及先前各版本标题的标题（先前各版本的标题若存在，应在文档的历史部分列出）。若您获得该版本原出版者的许可，可以使用与先前版本相同的标题。\nB. 在扉页上列出对修改版本负有责任的一位或多位个人或实体作为作者，并至少包括原文档的五位主要作者（若主要作者不足五位，则全部列出），除非这些作者免除您的此项义务。\nC. 在扉页上注明修改版本的出版者名称，作为出版者。\nD. 保留原文档的所有版权声明。\nE. 在现有版权声明旁添加一条适当的版权声明，说明您对文档所做的修改。\nF. 紧接版权声明之后，加入一份许可声明，以本许可证的条款允许公众使用修改版本，其格式见下文附录。\nG. 在该许可声明中保留原文档许可声明中所列的不可变章节和必需封皮文字的完整清单。\nH. 随附本许可证的未作修改的副本。\nI. 保留名为“历史”的章节及其标题，并在其中增加一项内容，至少注明修改版本的标题、年份、新作者和出版者，这些信息均取自扉页。如果原文档中没有名为“历史”的章节，则需创建一个，注明文档的标题、年份、作者和出版者，这些信息同样取自扉页，然后再添加一项描述修改版本的内容，如前一句所述。\nJ. 保留原文档中为公众访问文档透明副本而提供的网络地址，以及文档中为其所依据的先前版本提供的网络地址。这些地址可以置于“历史”章节中。对于在其发布日期早于原文档至少四年的工作，或者如果其所指版本的原出版者给予许可，则您可以省略相应的网络地址。\nK. 对于任何名为“致谢”或“献词”的章节，保留其标题，并保持该章节中所有贡献者致谢和\u002F或献词的内容与语气不变。\nL. 保留原文档的所有不可变章节，其内容和标题均不得更改。章节编号或类似标识不视为章节标题的一部分。\nM. 删除任何名为“推荐”的章节。此类章节不得出现在修改版本中。\nN. 不得将任何现有章节重新命名为“推荐”，也不得使其标题与任何不可变章节产生冲突。\nO. 保留所有免责声明。\n\n如果修改版本包含新的前置章节或附录，且这些章节符合次要章节的定义、不含从原文档复制的内容，您可以自行决定将其全部或部分指定为不可变章节。为此，您需要将这些章节的标题添加到修改版本许可声明中的不可变章节列表中。这些标题必须与其他章节标题有所区别。\n\n您也可以添加一个名为“推荐”的章节，但该章节只能包含各方对您的修改版本的推荐——例如同行评审意见，或某组织认可该文本为某一标准的权威定义等。\n\n您可以在修改版本封皮文字列表的末尾添加一段不超过5个字的前封皮文字，以及一段不超过25个字的后封皮文字。任何单一实体（或通过其安排）仅能添加一段前封皮文字和一段后封皮文字。如果原文档已经包含针对同一封皮的封皮文字，且该文字此前由您本人或您所代表的同一实体安排添加，则您不得再添加新的封皮文字；但在获得先前添加该文字的出版者的明确许可后，您可以替换原有文字。\n\n根据本许可证，文档的作者和出版者并未授予您使用其姓名进行宣传，或声称、暗示其对任何修改版本予以认可的权利。\n\n5. 文档合并\n\n您可以根据上述第4节中关于修改版本的规定，将本文档与其他依据本许可证发布的文档合并，但须在合并后的作品中包含所有原始文档中未作修改的不可变章节，并在其许可声明中将其全部列为合并作品的不可变章节，同时保留所有免责声明。\n\n合并后的作品只需包含一份本许可证副本，多个内容相同的不可变章节可以替换为单个副本。如果存在多个名称相同但内容不同的不可变章节，应通过在章节标题末尾加括号注明该章节的原作者或出版者（如已知）或一个唯一编号的方式使每个此类章节的标题具有唯一性。同样，还应对合并作品许可声明中不可变章节列表内的章节标题作出相应调整。\n\n在合并过程中，您必须将各原始文档中标题为“历史”的章节合并成一个统一的“历史”章节；同样地，也将所有标题为“致谢”和“献词”的章节分别合并。您还必须删除所有标题为“ endorsements”的章节。\n\n\n6. 文档汇编\n\n您可以制作一个由本文档及其他依据本许可证发布的文档组成的汇编，并用汇编中包含的一份本许可证副本替换各个文档中的单独副本，但前提是您在其他方面仍需遵守本许可证关于逐字复制各文档的规定。\n\n您也可以从此类汇编中提取单个文档，并依据本许可证单独分发该文档，但须在提取出的文档中插入一份本许可证副本，并在该文档的逐字复制方面完全遵循本许可证的其他规定。\n\n\n7. 与独立作品的聚合\n\n将本文档或其衍生作品与其他独立的文档或作品在存储或分发介质上组合成一个整体，称为“聚合体”，如果该组合所产生的著作权不用于限制聚合体使用者的合法权利，使其超出各个独立作品本身所允许的范围，则此组合被视为聚合体。当本文档被纳入聚合体时，本许可证并不适用于聚合体中那些并非本文档衍生作品的其他作品。\n\n如果第3节关于封面文字的要求适用于这些文档副本，且本文档在聚合体中所占比例不足一半，则本文档的封面文字可以放置在包围文档的封面页上，或者在文档为电子形式时，放置于等效的电子封面之上。否则，封面文字必须出现在覆盖整个聚合体的印刷封面页上。\n\n\n8. 翻译\n\n翻译被视为一种修改形式，因此您可以在第4节规定的条件下分发本文档的译本。用译本替换不可变章节需要获得其版权所有者的特别许可，但您可以在这些不可变章节的原文之外，一并包含其部分或全部译本。您还可以包含本许可证及其在文档中出现的所有许可声明和免责声明的译本，但前提是必须同时附上本许可证的英文原文以及那些声明和免责声明的原文。若译本与本许可证、任何声明或免责声明的原文之间存在分歧，则以原文为准。\n\n如果文档中的某一章节标题为“致谢”、“献词”或“历史”，则第4节中关于保持其标题不变的要求通常会要求更改实际标题。\n\n\n9. 终止\n\n除本许可证明确授权的情形外，您不得复制、修改、再许可或分发本文档。任何其他方式的复制、修改、再许可或分发行为均属无效，并将自动终止您依据本许可证享有的权利。\n\n然而，如果您停止一切违反本许可证的行为，则您从特定版权所有者处获得的许可将被恢复：（a）暂时恢复，除非且直至该版权所有者明确且最终终止您的许可；（b）永久恢复，如果该版权所有者未能在您停止违规行为后的60天内以合理方式通知您有关违规行为。\n\n此外，若您从某版权所有者处收到关于违反本许可证的通知，而这是您首次收到来自该版权所有者关于违反本许可证的通知（无论针对何种作品），并且您在收到通知后的30天内纠正了违规行为，则您从此版权所有者处获得的许可将被永久恢复。\n\n本节规定的权利终止并不影响已从您处依据本许可证获得副本或相关权利的各方的许可。如果您的权利已被终止且未获永久恢复，则即使您再次获得相同材料的部分或全部副本，亦无权使用这些材料。\n\n\n10. 本许可证的未来修订\n\n自由软件基金会可能会不时发布GNU自由文档许可证的新修订版本。这些新版本的精神将与当前版本相似，但在细节上可能有所不同，以应对新的问题或关切。详情请参阅https:\u002F\u002Fwww.gnu.org\u002Flicenses\u002F。\n\n许可证的每一个版本都有其独特的版本号。如果文档明确规定“本许可证的某一指定版本或任何后续版本”适用于该文档，则您可以选择遵循该指定版本或自由软件基金会已正式发布（而非草稿）的任何后续版本的条款和条件。如果文档未指定本许可证的具体版本号，则您可以选择自由软件基金会以往正式发布过的任一版本（而非草稿）。如果文档规定由代理人决定可采用的未来版本，则该代理就某一版本公开发表的接受声明将永久授权您为该文档选用该版本。\n\n\n11. 重新许可\n\n“大规模多作者协作站点”（或“MMC站点”）是指任何发布受版权保护作品并同时提供显著编辑功能的万维网服务器。任何人都可编辑的公共维基就是此类服务器的一个例子。“大规模多作者协作”（或“MMC”）指在MMC站点上发布的任何一组受版权保护的作品。\n\n“CC-BY-SA”是指知识共享组织发布的一份知识共享署名-相同方式共享3.0协议，该组织是一家非营利性机构，主要营业地点位于美国加利福尼亚州旧金山；同时也包括由同一组织发布的该协议未来的著佐权版本。\n\n“纳入”是指将一份文档的全部或部分作为另一份文档的一部分进行出版或再出版。\n\n如果一个MMC依据本许可证授权，并且所有最初在该MMC之外的其他地方依据本许可证首次发表、随后被全部或部分纳入该MMC的作品，同时满足以下两个条件：(1) 这些作品没有任何封面文字或不可变章节；(2) 它们是在2008年11月1日之前被纳入的，则该MMC即为“符合重新许可条件”。\n\n在2009年8月1日之前，MMC站点的运营者可以在同一站点上以CC-BY-SA协议重新发布该站点中包含的MMC，前提是该MMC符合重新许可条件。\n\n\n附录：如何将本许可证用于您的文档\n\n要在您撰写的文档中使用本许可证，请在文档中附上一份许可证副本，并在扉页之后立即添加如下版权和许可声明：\n\n 版权所有 © 年份 您的名字。\n 根据自由软件基金会发布的GNU自由文档许可证第1.3版或任何后续版本的条款，特此授予复制、分发和\u002F或修改本文件的权限；\n 本许可证无不可变章节、无前封面文字、无后封面文字。\n 许可证全文载于名为“GNU自由文档许可证”的章节中。\n\n如果您有不可变章节、前封面文字和后封面文字，请将“……文字。”一行替换为：\n\n 其不可变章节为 列出其标题，前封面文字为 列出，后封面文字为 列出。\n\n如果您只有不可变章节而没有封面文字，或者三者之间存在其他组合，请根据实际情况合并上述两种表述。\n\n如果您的文档包含非 trivial 的程序代码示例，我们建议您同时依照您选择的自由软件许可证（例如GNU通用公共许可证）发布这些示例，以便它们能够在自由软件中被使用。\n\u003C\u002Fpre>\n#+end_export","# Ellama 快速上手指南\n\nEllama 是一款运行在 Emacs 编辑器中的大型语言模型（LLM）交互工具。它支持流式输出，可轻松实现翻译、代码审查、文本摘要、语法修正等功能。默认后端为 Ollama。\n\n## 环境准备\n\n在开始之前，请确保满足以下要求：\n\n1. **操作系统**：Linux, macOS 或 Windows (WSL)。\n2. **Emacs**：建议版本 28.0 或更高，以支持最新的包管理和显示功能。\n3. **Ollama**（默认依赖）：\n * Ellama 默认使用 [Ollama](https:\u002F\u002Fgithub.com\u002Fjmorganca\u002Follama) 作为 LLM 提供者。\n * **安装 Ollama**：访问官网下载对应系统的安装包，或在终端执行：\n ```bash\n curl -fsSL https:\u002F\u002Follama.com\u002Finstall.sh | sh\n ```\n *(国内用户若下载缓慢，可尝试配置代理或使用国内镜像源)*\n * **拉取模型**：安装完成后，需至少拉取一个模型才能使用。例如拉取轻量级的 Qwen2.5 模型：\n ```bash\n ollama pull qwen2.5:3b\n ```\n\n## 安装步骤\n\n### 1. 通过 MELPA 安装 Ellama\n\n启动 Emacs，执行以下命令安装 `ellama` 包：\n\n1. 按下 `M-x` (Alt + x)。\n2. 输入 `package-install` 并回车。\n3. 输入 `ellama` 并回车。\n\n*(如果未配置 MELPA 源，请先在 `init.el` 中添加 MELPA 仓库地址)*\n\n### 2. 基础配置\n\n将以下代码添加到你的 Emacs 配置文件（`~\u002F.emacs.d\u002Finit.el` 或 `~\u002F.config\u002Femacs\u002Finit.el`）中，以启用基本功能和快捷键：\n\n```elisp\n(use-package ellama\n :ensure t\n :bind (\"C-c e\" . ellama) ;; 设置主快捷键为 C-c e\n ;; 可选：在 Org 模式下使用 C-c C-c 发送最后一条消息\n :hook (org-ctrl-c-ctrl-c-hook . ellama-chat-send-last-message)\n :init\n (setopt ellama-auto-scroll t) ;; 启用自动滚动\n :config\n ;; 在头部行显示上下文和会话 ID\n (ellama-context-header-line-global-mode +1)\n (ellama-session-header-line-global-mode +1))\n```\n\n重新加载配置文件或重启 Emacs 使配置生效。\n\n## 基本使用\n\n### 1. 启动交互菜单\n\n按下快捷键 `C-c e` (或执行 `M-x ellama`)，将弹出 transient 主菜单。这是所有功能的入口。\n\n### 2. 发起对话 (Chat)\n\n* **命令**：`ellama-chat`\n* **操作**：\n 1. 在主菜单中选择 `Chat` 或直接执行 `M-x ellama-chat`。\n 2. 在弹出的缓冲区中输入你的问题。\n 3. Ellama 将调用本地 Ollama 模型并流式返回答案。\n* **新建会话**：使用前缀参数 `C-u M-x ellama-chat` 可以交互式地选择新的模型并开始新会话。\n\n### 3. 常用场景示例\n\n你可以选中一段文本（Region），然后通过 `C-c e` 菜单快速执行以下操作：\n\n* **翻译**：选中文本 -> `C-c e` -> `Translate` (默认翻译为目标语言，可在配置中设置 `ellama-language`)。\n* **代码审查**：选中代码 -> `C-c e` -> `Code review`。\n* **解释内容**：选中内容 -> `C-c e` -> `Ask about`。\n* **润色文本**：选中文本 -> `C-c e` -> `Improve wording` 或 `Improve grammar`。\n\n### 4. 高级配置（可选）\n\n如果需要指定特定模型（如区分聊天模型和代码模型），可在配置文件中添加如下设置：\n\n```elisp\n(require 'llm-ollama)\n(setopt ellama-provider\n (make-llm-ollama\n :chat-model \"llama3:8b-instruct-q8_0\"\n :embedding-model \"nomic-embed-text\"))\n;; 为代码任务指定专用模型\n(setopt ellama-coding-provider\n (make-llm-ollama\n :chat-model \"qwen2.5-coder:3b\"))\n```\n\n配置完成后，Ellama 会根据任务类型自动调用相应的模型。","一位资深 Emacs 用户正在处理一个遗留项目的重构任务，需要频繁阅读复杂的旧代码、编写技术文档并修复语法错误。\n\n### 没有 ellama 时\n- **上下文切换频繁**：为了询问代码逻辑或请求重构建议，必须离开编辑器切换到浏览器或独立聊天窗口，打断心流。\n- **操作繁琐低效**：每次都需要手动复制代码片段、粘贴到外部工具、等待回复后再复制回缓冲区，极易出错且耗时。\n- **缺乏流式体验**：无法在生成过程中实时预览长段落的翻译或总结结果，只能被动等待完整响应。\n- **配置割裂**：针对代码审查、文档润色等不同任务，难以在编辑器内快速切换专用的大模型参数或类型。\n\n### 使用 ellama 后\n- **原地智能交互**：直接在 Emacs 缓冲区通过快捷键唤起 ellama，无需切换窗口即可对选中代码进行解释或重构。\n- **工作流无缝集成**：利用原生支持的流式输出，实时查看代码审查意见或文章润色结果，边生成边调整，效率显著提升。\n- **任务场景化定制**：通过预设配置，一键调用专为编码优化的 `qwen2.5-coder` 模型进行代码审查，或切换至通用模型进行德语文档翻译。\n- **会话状态可视**：头部状态栏实时显示当前会话 ID 和上下文信息，确保在多文件编辑时不会混淆不同任务的对话历史。\n\nellama 将大语言模型深度融入 Emacs 编辑环境，让开发者在不中断思维的前提下，享受如虎添翼的智能辅助体验。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fs-kostyaev_ellama_6c25fcf4.png","s-kostyaev","Sergey Kostyaev","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fs-kostyaev_f2d15082.png",null,"Berlin, Germany ","https:\u002F\u002Fgithub.com\u002Fs-kostyaev",[79,83,87],{"name":80,"color":81,"percentage":82},"Emacs Lisp","#c065db",99.2,{"name":84,"color":85,"percentage":86},"Makefile","#427819",0.7,{"name":88,"color":89,"percentage":90},"Dockerfile","#384d54",0.1,928,61,"2026-04-14T00:15:36","GPL-3.0","Linux, macOS, Windows","未说明（取决于后端 Ollama 及所选模型，Ellama 本身作为 Emacs 插件无直接 GPU 需求）","未说明（取决于后端 Ollama 及所选模型）",{"notes":99,"python":100,"dependencies":101},"Ellama 是一个 Emacs 插件，本身不直接运行模型，而是作为客户端连接到本地或远程的 Ollama 服务。因此，实际的硬件需求（GPU、内存等）完全取决于用户通过 Ollama 加载的具体大语言模型（如 llama3, qwen2.5 等）。用户需先独立安装并运行 Ollama 服务，并在其中拉取所需的模型文件。","未说明",[102,103,104],"Emacs","Ollama","llm-ollama",[15,26],"2026-03-27T02:49:30.150509","2026-04-18T22:37:30.156586",[109,114,119,124,129,134,138],{"id":110,"question_zh":111,"answer_zh":112,"source_url":113},40888,"如何恢复或重新加载之前的会话（Session）？","可以使用 `ellama-load-session` 命令来恢复之前的会话。会话文件本质上是普通的 Org 文件，存储在配置的目录中。此外，你可以同时拥有多个活动会话，通过按 `C-u` 前缀再执行 `ellama-chat` (即 `C-u ellama-chat`) 来启动一个新的会话。","https:\u002F\u002Fgithub.com\u002Fs-kostyaev\u002Fellama\u002Fissues\u002F18",{"id":115,"question_zh":116,"answer_zh":117,"source_url":118},40889,"在模型生成回复时按下 `C-g` 会导致整个会话缓冲区被杀死，如何解决？","这是一个已知行为。如果将 `ellama-session-auto-save` 设置为非 nil 值，按下 `C-g` 中止请求时会弹出缓冲区保存确认提示，从而防止缓冲区被直接杀死。另外，有用户发现如果在配置中将 `ellama--current-session-id` 和 `ellama-session-auto-save` 显式设置为 nil 也可能影响此行为。理想情况下，`C-g` 应仅中止最近的请求而保留会话缓冲区。","https:\u002F\u002Fgithub.com\u002Fs-kostyaev\u002Fellama\u002Fissues\u002F197",{"id":120,"question_zh":121,"answer_zh":122,"source_url":123},40890,"`ellama-complete` 命令粘贴了模型的思考过程而不是直接完成文本，怎么办？","这通常是由于提示词（prompt）设置或过滤逻辑导致的。维护者曾尝试通过改进过滤 lambda 函数（filter lambda）来解决此问题，并建议用户尝试最新的提交版本。如果问题依旧，可能需要检查模型输出的解析逻辑或等待维护者对提示词模板的进一步优化。","https:\u002F\u002Fgithub.com\u002Fs-kostyaev\u002Fellama\u002Fissues\u002F258",{"id":125,"question_zh":126,"answer_zh":127,"source_url":128},40891,"如何在项目中管理和复用自定义的提示词（Prompts）？","推荐的工作流是将提示词作为项目的一部分存储在特定文件夹（如 `docs` 文件夹）中。使用时，先将包含提示词的文件（例如 `docs\u002Finstructions.org`）添加到上下文中，然后添加相关的代码或文档，最后调用现有的 Ellama 命令（如 `ellama-code-add`）来发送指令。虽然目前不直接集成外部提示词库，但这种基于文件的上下文管理方式非常灵活。","https:\u002F\u002Fgithub.com\u002Fs-kostyaev\u002Fellama\u002Fissues\u002F98",{"id":130,"question_zh":131,"answer_zh":132,"source_url":133},40892,"为什么 `ellama-code-add` 似乎忽略了已添加的上下文缓冲区？","这可能是因为当前模式未正确显示或关联会话及文件列表。维护者计划创建一个新的次要模式（minor mode），在该模式的模式行（mode line）中显示当前会话，并在头行（header line）中同时显示会话名称和文件列表，以解决上下文不明确的问题。用户可以关注相关修复进度或在新的模式下测试。","https:\u002F\u002Fgithub.com\u002Fs-kostyaev\u002Fellama\u002Fissues\u002F292",{"id":135,"question_zh":136,"answer_zh":137,"source_url":113},40893,"Doom Emacs 用户遇到会话目录冲突或 `C-u` 快捷键无效的问题如何解决？","对于 Doom Emacs 用户：1. 如果会话目录与 Doom 的缓存目录冲突，可以在配置中将 `ellama-sessions-directory` 修改为其他路径（例如 `~\u002F.emacs.d\u002F.ellama-sessions`）。2. Doom Emacs 使用 `SPC u` 作为通用前缀键来替代 Emacs 标准的 `C-u`，因此在执行需要前缀的命令时请尝试使用 `SPC u`。",{"id":139,"question_zh":140,"answer_zh":141,"source_url":142},40894,"瞬态菜单（Transient Menu）太高且布局不合理，能否调整？","维护者已意识到瞬态菜单存在过高、分类不清晰以及状态显示不透明的问题。针对会话管理，已经实现了类似 `ellama-session-kill` 的功能来更好地管理缓冲区。关于菜单布局和工作流的改进（如更宽更短的菜单、更清晰的模型切换和会话创建流程）正在讨论和规划中，旨在让用户更清楚地知道当前使用的会话和模型状态。","https:\u002F\u002Fgithub.com\u002Fs-kostyaev\u002Fellama\u002Fissues\u002F236",[]]