贡献 Magent

• Emacs 29.1+
• gptel 0.9.8+
• compat 30.1+
• yaml 1.0+
• acp 0.13.1+
• agent-shell 0.66.1+
• package-lint（仅开发时需要）
• ripgrep 或 Git，用于 grep tool 测试；优先使用 ripgrep

make compile    # Byte-compile all files
make lint       # 检查声明和 package metadata
make test-unit  # Run batch ERT unit tests
make test       # Run unit tests plus deterministic live smoke tests
make coverage   # Run ERT under built-in testcover
make clean      # 删除构建产物及 Harbor benchmark 容器/网络
make purge      # 进一步删除 benchmark Docker 镜像及 Harbor task cache

Makefile 会自动探测 ~/.emacs.d/elpa/ 下的 ELPA dependency directories。若要使用非标准 checkout，可显式传入 GPTEL_DIR 、 COMPAT_DIR 或 YAML_DIR 等变量。

• 内部函数和变量使用 magent-module--name ，双横线。
• 公共函数、命令和变量使用 magent-module-name ，单横线。
• Tool implementation 使用 magent-tools--<name> 作为内部函数， magent-tools--<name>-tool 作为 gptel-tool 变量。
• 可选 integration 放在独立模块中，不能把依赖泄漏进 core runtime。
• 不要在 Magent source files 中使用个人配置风格前缀，如 +module/name 。

所有 Elisp 文件必须包含：

;;; filename.el --- Brief description  -*- lexical-binding: t; -*-

每个 Elisp source file 也应保留 SPDX license identifier，方便 melpazoid/package-lint 检测。

• 公共函数需要 docstring。
• 用 ;;; 做 section headers。
• 用 ;; 做 inline comments。
• 用户可见变化更新 README.org 。
• User-visible changes 添加到 CHANGELOG.org 的 Unreleased section。
• 修改 public compatibility contract、package version 或 release artifact 前阅读 ~docs/RELEASING.zh.org~。
• 面向开发者的变化更新 AGENTS.md 或 docs/ 中对应文档。
• child-agent lifecycle 变化更新 docs/AGENT_JOBS.org 。
• plan-driven 工作中断前，更新相关 plan 或 task note。

• 用 cl-letf mock gptel-request 。
• 把 registries 绑定到 fresh state。
• 调用 magent-session-reset 清空 global state。
• 同时测试 success 和 error paths。

# Reload changed file
emacsclient --eval '(load "/path/to/file.el" nil t)'

# Clear the current runtime session
emacsclient --eval '(magent-runtime-session-clear (magent-runtime-session-current))'

# Test prompts:
# - Non-tool: "你好"
# - Tool-use: "帮我看下 emacs 里面有多少 buffer"
# - Multi-step: "帮我在 emacs 里面打开 magent 的 magit buffer"

对真实配置的 gptel provider 跑 live tests 前，先在 running Emacs 中开启 debug-on-error ：

emacsclient --eval '(setq debug-on-error t)'

运行期间和结束后检查 *Messages* 、 *Backtrace* 、 *magent-log* 或 *magent-live-test-log* ，以及 *gptel-log* 。不要把未检查的原始 *gptel-log* 贴进 issue 或 commit；其中可能包含 provider headers、request bodies 或 API key material。

GitHub Actions 运行：

• test.yml ：分别安装 Emacs 29.4 和 30.1、安装依赖、执行 byte-compile、声明/package lint、unit tests，并在临时 daemon 中跑 deterministic live smoke tests。
• coverage.yml ：运行 make coverage 并上传 coverage/testcover-summary.tsv 。
• melpazoid.yml ：运行 MELPA-style package checks。

melpazoid recipe 显式包含 lisp/magent*.el~、~prompts/ 和 skills/~。这些 production libraries 和 bundled runtime data 必须保留，因为 Magent 会在运行时解析它们。Recipe 应与 ~source-files.txt 和 prompts/manifest.txt 保持一致。

Package metadata 保持集中在 magent.el 和 magent-pkg.el 。不要在 secondary modules 中添加 Package-Requires headers；package-lint 会把 main file 之外的这些 headers 视为 ineffective。每个 Elisp 文件都应包含 SPDX license identifier。

• child-agent lifecycle polish 和 reliability，但不包含 sandbox parity。
• 新增 tool implementations。
• 性能优化。
• 测试覆盖率提升。
• 文档改进。

• 新的 built-in agents。
• Skill system 扩展。
• UI 改进。
• Error handling 优化。

• 代码清理。
• 重构。
• 风格改进。

1. 在 magent-tools.el 实现。
2. 加入 magent-enable-tools default。
3. 更新 agent permissions。
4. 添加测试。
5. 在 README.org 记录。

Agent lifecycle tools 是特殊情况。如果工具参与 spawn、message、wait、list、resume、inspect 或 close child agents，需要保持实现和 docs/AGENT_JOBS.org 对齐，并更新相关测试。

1. 遵守 dependency graph，参考 AGENTS.md 。
2. 使用 ;;; -*- lexical-binding: t; -*- 。
3. 显式 require dependencies。
4. 必要时加入 magent.el 。
5. 在 test/magent-test.el 写测试。

如果是新的 child-agent/job module，优先保持聚焦，例如使用 magent-agent-job.el ，不要过早把生命周期逻辑塞进 magent-tools.el 。

• Active request/tool-loop behavior 属于 magent-agent-loop.el 。
• Provider transport 继续使用 magent-sampling-gptel.el 和 gptel-request 。
• 为 normalized events、tool queueing、permission decisions、abort behavior 和 session recording 加 focused tests。
• 修改 continuation 或 final-response 行为时，要覆盖 post-tool empty completion 和 reasoning-only completion；reasoning 不能变成 assistant text。
• 当 callback 可能在 interruption 后到达时，更新 request generation 和 live-request checks。
• 不要重新引入已移除的 agent-loop modules；provider-specific transport handling 只放在 magent-sampling-gptel.el 。