Magent 文档总览
欢迎阅读 Magent 文档。Magent 是一个 Emacs Lisp AI coding agent，具备 multi-agent 架构、permission-based tool access，并通过 gptel 集成 LLM。
文档索引
快速开始
- COMMANDS.zh.org ：slash commands、internal LLM workflows 及其管理命令。
- ONBOARDING.zh.org ：新贡献者导览，包括架构分层、代码阅读路线和复杂点。
- TROUBLESHOOTING.zh.org ：常见问题、CI 问题和 live Emacs 调试流程。
架构
- ARCHITECTURE.zh.org ：产品定位、系统边界、模块层次、请求流和扩展模型。
- AGENT_WORKFLOW.zh.org ：
thread -> turn -> item状态机、循环流程、snapshot + journal持久化、UI 投影和 Codex 差异。 - AGENT_JOBS.zh.org ：durable child-agent job 生命周期、工具面、持久化、UI 和边界。
- UI_BACKENDS.zh.org ：受支持的 agent-shell + ACP 流程，以及 frontend 开发边界。
- DOCTOR.zh.org ：Doctor probe API、信任边界、脱敏、session 和取消。
- PTC_MULTI_MODEL_PLAN.zh.org ：PTC、~run_code~ nested executor 和单个 agent loop 内多模型 phase 的详细实施计划。
- PROCESS_DISPLAY_PLAN.zh.org ：Codex 风格进度正文与工具调用前 assistant 文本续传的详细实施计划。
贡献
- CONTRIBUTING.zh.org ：贡献流程、代码风格、测试和 PR 要求。
- RELEASING.zh.org ：版本规则、公开兼容边界、changelog 规则和 release checklist。
- TROUBLESHOOTING.zh.org#github-actions-失败 ：CI、live smoke 和 melpazoid 常见失败。
仓库根目录文档
- ../README.org ：主 README，包含特性、安装和使用说明。
- ../CHANGELOG.org ：发布历史和当前 unreleased changes。
- ../AGENTS.md ：面向 agentic coding 工具的开发指南，包含构建命令、架构要点和仓库约定。
推荐阅读路径
新贡献者
- 先读 ONBOARDING.zh.org。
- 再读 CONTRIBUTING.zh.org 了解开发流程。
- 读 ../AGENTS.md 获取当前架构约束和 agent 开发规则。
- 改 child-agent 生命周期前必须读 AGENT_JOBS.zh.org。
用户
- ../README.org：安装和配置。
- COMMANDS.zh.org：内置 slash commands 和 Magent-owned LLM workflows。
- TROUBLESHOOTING.zh.org：常见问题。
- 运行
M-x magent-action-run-doctor做自诊断。 - 使用
M-x magent-start打开受支持的 agent-shell UI。
开发者
- CONTRIBUTING.zh.org：代码风格和 PR 流程。
- ../AGENTS.md：构建、测试、架构和开发指令。
- ARCHITECTURE.zh.org：当前系统边界。
- ONBOARDING.zh.org：代码导览和复杂点。
- AGENT_JOBS.zh.org：child-agent job 架构。
- UI_BACKENDS.zh.org：当前 frontend 支持边界。
- DOCTOR.zh.org：Doctor 数据边界和扩展契约。
- RELEASING.zh.org：版本和发布流程。
CI 与打包
- ../README.org：公开 workflow badge 和开发命令。
- CONTRIBUTING.zh.org#持续集成：本地和 CI 验证顺序。
- TROUBLESHOOTING.zh.org#github-actions-失败：GitHub Actions 失败特征。
- ../AGENTS.md#testing：面向 agent 的测试、coverage、live smoke 和 melpazoid 说明。
- RELEASING.zh.org：release gates 和 artifact checks。
文档维护标准
新增或修改文档时：
- 用户稳定入口优先更新根目录
README.org。 - 开发者文档放在
docs/。 docs/下使用 Org 作为源码；生成的 HTML 是_site/下的构建产物。- 除了明确标记为单语言的页面，新增文档时应同步英文/中文镜像页，并设置互为 reciprocal 的 ~magent_alt_url~。
- 新增公开页面时同步更新本索引和 ~magent-docs–navigation~。文档构建器会拒绝 duplicate URL、遗漏的导航项、语言分组错误以及不对称的显式翻译链接。
- 中断开发前更新稳定文档或活动任务笔记，让其他机器能从 git 恢复上下文。