人工智能AI Agent自主智能体代码智能体桌面应用前端开发工具【免费下载链接】AperantAutonomous multi-session AI coding项目地址https://gitcode.com/gh_mirrors/au/Aperant点击查看免费下载本文是开源项目 Aperant即 Auto Claude仓库内的完整开发文档为 CLAUDE.md的技术开发指南。它面向想要理解或参与该仓库的开发者系统讲解这款“自主多会话 AI 编程框架”的产品工作流、硬性开发规则、Orchestrator-First 协作模式、TypeScript AI 代理层基于 Vercel AI SDK v6的架构与关键实现、前端工程规范以及跨平台与 E2E 测试方法。读完本文你将掌握在 Aperant 仓库中规划任务、定位代码、遵循约束开发与验证功能的完整实战路径。产品定位与核心工作流Aperant 是一个自主多代理编码框架用户描述目标后AI 代理自主完成规划、实现与 QA 校验。它是一款 TypeScript 优先的 Electron 桌面应用内置自包含的 AI 代理层Vercel AI SDK v6并附带一个轻量级 Python 伴生进程提供可选的 Graphiti 记忆系统。所有构建工作都发生在隔离的 git worktree 中保证main分支始终安全见 CLAUDE.md 顶部说明。核心工作流如下用户创建任务 → Spec 创建管线评估复杂度并撰写规格 → Planner 代理拆分子任务 → Coder 代理实现可并行派生子代理→ QA 审查代理校验 → QA 修复代理解决问题 → 用户审查并合并。主要功能清单功能说明自主任务Autonomous Tasksplanner → coder → QA 的多代理管线端到端构建功能看板Kanban Board从规划到完成的可视化任务管理代理终端Agent Terminals最多 12 个并行的 AI 驱动终端注入任务上下文Insights用于探索和理解代码库的 AI 聊天界面Roadmap带战略路线图生成的 AI 辅助功能规划Ideation发现改进点、性能问题与安全漏洞GitHub/GitLab 集成导入 Issue、AI 驱动的调查、PR/MR 审查与创建Changelog从已完成任务生成发布说明记忆系统Memory System基于 Graphiti 的知识图谱跨会话保留洞察隔离工作区Isolated Workspaces每次构建使用 git worktree 隔离支持 AI 驱动的语义合并灵活认证Flexible AuthenticationClaude Code 订阅OAuth或任意 Anthropic 兼容端点的 API Profile如 Anthropic API、z.ai 的 GLM 模型多账号切换Multi-Account Swapping注册多个 Claude 账号遇到限流时自动切换到可用账号跨平台Cross-Platform支持 Windows、macOS、Linux 原生桌面应用含自动更新硬性开发规则不可逾越的约束CLAUDE.md 明确列出若干“Critical Rules”这些规则约束着所有代码贡献并且每条都能在源码中找到对应实现。Vercel AI SDK onlyAI 交互唯一技术栈——所有 AI 交互必须使用 Vercel AI SDK v6ai包通过apps/desktop/src/main/ai/下的 TypeScript 代理层完成。严禁直接使用anthropic-ai/sdk或anthropic.Anthropic()。创建模型必须走 createProvider()文本生成必须走streamText()/generateText()。Provider 专属适配器如ai-sdk/anthropic、ai-sdk/openai通过 Provider 注册表统一管理。从源码看factory.ts 通过createProviderInstance()按 provider 分发到对应构造函数支持 Anthropic、OpenAI、Google、Bedrock、Azure、Mistral、Groq、xAI、OpenRouter、z.ai 与 Ollama。这里有几个值得注意的实现细节Anthropic OAuth token 以sk-ant-oa/sk-ant-ort前缀识别此时改用authToken 必需的anthropic-beta头见 factory.tsOpenAI 的 Codex OAuth 账号会把所有 URL 重写到 Codex Responses 端点因此这类账号的所有模型都必须走.responses()否则会因 Chat Completions 格式与 Responses 端点不匹配而返回 400见 factory.tsOllama 需要自动补/v1路径见 factory.ts。i18n 必须——所有前端用户可见文本都使用react-i18next翻译键。JSX/TSX 中硬编码字符串会破坏非英语用户的本土化新增键必须同时加入en/*.json与fr/*.json目录见 apps/desktop/src/shared/i18n/locales。平台抽象——禁止直接使用process.platform一律从 apps/desktop/src/main/platform/ 导入。CI 会测试全部三个平台。该模块提供了isWindows()/isMacOS()/isLinux()、getPathDelimiter()Windows 为;Unix 为:、findExecutable(name)、requiresShell(command)等函数见 platform/index.ts以及跨平台的优雅杀进程逻辑killProcessGracefully()Unix 用 SIGTERM→SIGKILLWindows 用kill()→taskkill /f /t。其他规则不提供时间估算——只按优先级排序不做耗时预测PR 目标分支——PR 一律指向develop分支而非mainmain只用于发布生产代码禁用 console.log——打包后的 Electron 应用中console.log不可见生产环境用 Sentry 追踪错误console.log仅供开发调试。Orchestrator-First 工作模式CLAUDE.md 强调开发者应把自己定位为“orchestrator编排者”核心职责是理解需求、拆分为工作流、把执行委托给代理团队从而把上下文窗口集中在协调与决策上而不是被实现细节塞满。标准的 orchestrator 模式包含四步先调查Investigate first——在形成任何假设前先读实际代码。简单查询用定向搜索Glob、Grep、Read更广泛的探索则派生 Explore 代理。规划方案Plan the approach——识别需要改什么、涉及哪些文件、能否并行。多步骤任务用任务清单跟踪工作流。委托执行Delegate execution——派生代理团队做实现。每个代理拿到清晰自包含的任务包含相关文件路径、具体改动与验收标准独立工作流并行运行。验证与集成Verify and integrate——审查代理输出、运行测试、确保改动协同工作必要时修复集成问题或派生跟进代理。何时委托 vs 直接做委托多文件改动、跨代码库研究、独立并行工作流、会消耗大量上下文的任务直接做单文件编辑、简单 bug 修复、快速查询、已掌握上下文的任务。给代理好任务的关键每个代理都从全新上下文开始任务书要包含具体目标、相关文件路径、要遵循的代码模式以及“完成”的定义。显式完整的指令远好于模糊引用“当前任务”。最小改动原则——优先最简单的方案例如仅改 prompt、单个 guard clause再考虑多组件方案。用户要求 X 就实现 X不要捆绑额外的修复。默认行动——当用户意图暗含改动时直接实现而不是只提建议不确定就阅读相关代码补全信息而不是反复提问只有在用户真实意图仍存在歧义时才发问。上下文管理与长任务策略代理的上下文窗口接近上限时会被自动压缩compaction因此可以无限期持续工作。不要因担心上下文而提前停止任务——持续记录进度继续前进。针对长任务的实践用 git commit、任务清单和结构化笔记跟踪状态上下文压缩后通过git log和进度文件重新定位聚焦增量进展——完成一个组件再推进下一个边做边提交可工作的状态。并行工具调用——读取多个文件、运行独立搜索或执行无关命令时所有调用应并行而非串行这能显著加速调查与实现。已知坑Known GotchasElectron 路径解析——修复 Electron 应用 bug 时必须检查开发与生产构建之间的路径解析差异app.isPackaged、process.resourcesPath。开发环境正常工作的路径在 Electron 打包为生产版本后常常失效两种上下文都要验证。重置 PR Review 状态——要完全清空所有 PR 审查数据让审查从零开始需要删除/重置.auto-claude/github/下三处内容rm .auto-claude/github/pr/logs_*.json—— 审查日志文件rm .auto-claude/github/pr/review_*.json—— 审查结果文件将pr/index.json重置为{reviews: [], last_updated: null}将bot_detection_state.json重置为{reviewed_commits: {}}—— 这是守门者gatekeeper不清除它bot 检测器会跳过已见过的 commit。项目结构仓库采用单应用结构核心代码如下autonomous-coding/ ├── apps/ │ └── desktop/ # Electron 桌面应用唯一应用 │ ├── prompts/ # 代理系统提示词.md │ └── src/ │ ├── main/ # Electron 主进程 │ │ ├── ai/ # TypeScript AI 代理层Vercel AI SDK v6 │ │ │ ├── providers/ # 多 Provider 注册表 工厂9 个 Provider │ │ │ ├── tools/ # 内置工具Read, Write, Edit, Bash, Glob, Grep 等 │ │ │ ├── security/ # Bash 校验器、命令解析器、路径包含检查 │ │ │ ├── config/ # 代理配置25 类型、阶段配置、模型解析 │ │ │ ├── session/ # streamText() 代理循环、错误分类、进度 │ │ │ ├── agent/ # Worker 线程执行器 桥接 │ │ │ ├── orchestration/ # 构建管线planner → coder → QA │ │ │ ├── runners/ # 工具运行器insights, roadmap, PR review 等 │ │ │ ├── mcp/ # MCP 客户端集成 │ │ │ ├── client/ # Client 工厂便捷构造器 │ │ │ └── auth/ # Token 解析复用 claude-profile/ │ │ ├── agent/ # 代理队列、进程、状态、事件 │ │ ├── claude-profile/ # 多 Profile 凭证、token 刷新、用量 │ │ ├── terminal/ # PTY 守护进程、生命周期、Claude 集成 │ │ ├── platform/ # 跨平台抽象 │ │ ├── ipc-handlers/# 40 个按领域划分的 handler 模块 │ │ ├── services/ # 会话恢复、Profile 服务 │ │ └── changelog/ # Changelog 生成与格式化 │ ├── preload/ # Electron preload 脚本electronAPI 桥接 │ ├── renderer/ # React UI │ │ ├── components/ # UI 组件onboarding, settings, task, terminal, github 等 │ │ ├── stores/ # 24 个 Zustand 状态 store │ │ ├── contexts/ # React 上下文ViewStateContext │ │ ├── hooks/ # 自定义 hooksuseIpc, useTerminal 等 │ │ ├── styles/ # CSS / Tailwind 样式 │ │ └── App.tsx # 根组件 │ ├── shared/ # 共享类型、i18n、常量、工具 │ │ ├── i18n/locales/# en/*.json, fr/*.json │ │ ├── constants/ # themes.ts 等 │ │ ├── types/ # 19 个类型定义文件 │ │ └── utils/ # ANSI 净化、shell 转义、Provider 检测 │ └── types/ # TypeScript 类型定义 ├── guides/ # 文档 └── scripts/ # 构建与工具脚本注意CLAUDE.md 中指向的shared_docs/ARCHITECTURE.md与apps/desktop/CONTRIBUTING.md在仓库当前快照中不存在于预期位置如需深度架构参考可结合实际存在的 apps/desktop/README.md 与 apps/desktop/CONTRIBUTING.md 阅读。命令速查环境搭建npm run install:all # 从根目录安装全部依赖 # 或者单独安装 cd apps/desktop npm install测试栈命令工具前端单元测试cd apps/desktop npm testVitest前端 E2Ecd apps/desktop npm run test:e2ePlaywright发布node scripts/bump-version.js patch|minor|major # 升级版本号 git push gh pr create --base main # 合并到 main 的 PR 触发发布完整发布流程参见 RELEASE.md。补充说明apps/desktop/package.json 中还提供了npm run develectron-vite 开发模式、npm run build、npm run typechecktsc 严格模式、npm run lintBiome、npm run test:integration与npm run test:coverage等脚本。AI 代理层深入apps/desktop/src/main/ai/所有 AI 代理逻辑都使用 TypeScript Vercel AI SDK v6 实现取代了此前 Python 的claude-agent-sdk集成。架构总览Provider 层providers/——通过createProviderRegistry()支持多 ProviderAnthropic、OpenAI、Google、Bedrock、Azure、Mistral、Groq、xAI、Ollama。Provider 专属 transform 负责 thinking token 归一化与 prompt 缓存。会话运行时session/——runAgentSession()使用streamText()配合stopWhen: stepCountIs(N)实现 agentic 工具调用循环包含错误分类429/401/400与进度跟踪。Worker 线程agent/——代理会话运行在worker_threads中避免阻塞 Electron 主进程WorkerBridge将postMessage()事件转发到既有AgentManagerEvents接口。构建编排orchestration/——完整的 planner → coder → QA 管线并行子代理执行基于Promise.allSettled()。工具tools/——8 个内置工具Read、Write、Edit、Bash、Glob、Grep、WebFetch、WebSearch通过 AI SDKtool()以 Zod schema 定义。安全security/——Bash 校验器、命令解析器、路径包含检查由 Python 移植而来allowlist 行为完全一致。配置config/——AGENT_CONFIGS注册表25 种代理类型、阶段感知的模型解析、thinking 预算。关键模式代码// 使用 streamText() 的代理会话 import { streamText, stepCountIs } from ai; const result streamText({ model: provider, system: systemPrompt, messages: conversationHistory, tools: toolRegistry.getToolsForAgent(agentType), stopWhen: stepCountIs(1000), onStepFinish: ({ toolCalls, text, usage }) { progressTracker.update(toolCalls, text); }, }); // 使用 Zod schema 定义工具 import { tool } from ai; import { z } from zod; const readTool tool({ description: Read a file from the filesystem, inputSchema: z.object({ file_path: z.string(), offset: z.number().optional(), limit: z.number().optional(), }), execute: async ({ file_path, offset, limit }) { /* ... */ }, });会话运行时源码级细节runner.ts 是执行代理会话的核心入口实现了多层防护默认最大步数DEFAULT_MAX_STEPS 500防止代理空转runner.ts上下文窗口守卫prompt token 达到窗口的 85% 时注入压缩警告达到 90% 时硬中止并触发 continuation 断点续跑CONTEXT_WINDOW_THRESHOLD 0.85、CONTEXT_WINDOW_ABORT_THRESHOLD 0.90流不活动超时60 秒内无数据即中止流防止某些 Provider如 OpenAI Codex接受请求后永不返回数据导致 worker 挂死STREAM_INACTIVITY_TIMEOUT_MS 60_000收敛助推Convergence Nudge当 QA 类代理用到 75% 步数预算时注入“立即产出结论”的提示把空转的代理拉回正轨认证重试429 限流或 401 认证失败时可通过onAccountSwitch走全局优先级队列切换到备用账号实现跨 Provider 回退结构化解构注意点AI SDK 的Output.object()不能与 tools 同时出现在同一次streamText()中已知限制此时会先跑工具循环、再尝试从响应文本中解析 JSON 并做 schema 校验。代理 Prompt 目录apps/desktop/prompts/Prompt用途planner.md带子任务的实现计划coder.md / coder_recovery.md子任务实现 / 恢复qa_reviewer.md / qa_fixer.md验收校验 / 问题修复spec_gatherer.md、spec_researcher.md、spec_writer.md、spec_critic.mdSpec 创建管线complexity_assessor.md基于 AI 的复杂度评估此外apps/desktop/prompts/github/下还有一整套 PR 审查相关 prompt如pr_orchestrator.md、pr_reviewer.md、pr_security_agent.md等与apps/desktop/prompts/mcp_tools/下的 MCP 工具说明。Agent 配置注册表agent-configs.ts 是“代理类型 → 工具 → MCP 服务器”映射的唯一事实来源实现了阶段感知的工具控制与上下文窗口优化。例如Spec 管线代理spec_gatherer、spec_researcher、spec_writer、spec_critic等只使用SPEC_TOOLSRead、Glob、Grep、Write、WebFetch、WebSearch没有 Edit 和 Bash且都挂载context7MCPbuild_orchestrator拥有全部内置工具 SpawnSubagentMCP 服务器为context7、memory、auto-claude可选linear默认 thinking 级别为highcoder拥有全部内置工具默认 thinking 级别low编码追求速度qa_reviewer/qa_fixer额外挂载browserMCPelectron 或 puppeteer取决于项目能力QA 默认 thinking 级别high。工具解析由 registry.ts 的ToolRegistry.getToolsForAgent()完成按 agent 类型过滤已注册工具并绑定ToolContext。MCP 服务器解析getRequiredMcpServers还支持按环境开关动态选择例如browser在 Electron 项目中解析为electron、在 Web 前端项目中解析为puppeteer。Spec 目录结构每个 spec 位于.auto-claude/specs/XXX-name/包含spec.md、requirements.json、context.json、implementation_plan.json、qa_report.md、QA_FIX_REQUEST.md。记忆系统Graphiti基于图谱的语义记忆通过 Python MCP 伴生进程访问位于apps/desktop/之外AI 层通过ai-sdk/mcp的createMCPClient连接配置通过 Electron 应用的 onboarding/settings UI 完成。记忆工具包括search_nodes、search_facts、add_episode、get_episodes、get_entity_edge定义见 agent-configs.ts。在 runner.ts 的prepareStep回调中实现了 step 间记忆注入前 5 步为预热期之后每次 step 都会请求requestStepInjection注入相关记忆并配合buildMemoryAwareStopCondition根据校准因子动态调整步数上限。前端开发技术栈React 19、TypeScriptstrict、Electron 39、Vercel AI SDK v6、Zustand 5、Tailwind CSS v4、Radix UI、xterm.js 6、Vite 7、Vitest 4、Biome 2、MotionFramer Motion。路径别名tsconfig.json别名映射/*src/renderer/*shared/*src/shared/*preload/*src/preload/*features/*src/renderer/features/*components/*src/renderer/shared/components/*hooks/*src/renderer/shared/hooks/*lib/*src/renderer/shared/lib/*状态管理Zustand所有状态位于src/renderer/stores/关键 storeproject-store.ts—— 当前项目、项目列表task-store.ts—— 任务/spec 管理terminal-store.ts—— 终端会话与状态settings-store.ts—— 用户偏好github/issues-store.ts、github/pr-review-store.ts—— GitHub 集成insights-store.ts、roadmap-store.ts、kanban-settings-store.ts。主进程同样有 storesrc/main/project-store.ts、src/main/terminal-session-store.ts。样式Tailwind CSS v4使用tailwindcss/postcss插件7 套颜色主题Default、Dusk、Lime、Ocean、Retro、Neo 等定义于src/shared/constants/themes.ts每个主题通过 CSS 自定义属性提供明暗两套变体工具函数clsxtailwind-mergecn()辅助函数组件变体class-variance-authorityCVA。IPC 通信主进程 ↔ 渲染进程通过 Electron IPC 通信Handlersapps/desktop/src/main/ipc-handlers/ —— 按领域划分github、gitlab、ideation、context、task、terminal 等 40 模块Preloadapps/desktop/src/preload/ —— 向渲染进程暴露安全 API模式渲染进程通过window.electronAPI.*调用主进程在 IPC handler 模块中处理。代理管理src/main/agent/前端端到端管理代理生命周期agent-queue.ts—— 队列路由、优先级、spec 编号锁定agent-process.ts—— 通过WorkerBridge派生 worker 线程执行代理agent-state.ts—— 跟踪运行中的代理状态agent-events.ts—— 代理生命周期事件与状态转换来自 worker 线程的结构化事件。Claude Profile 系统src/main/claude-profile/多 Profile 凭证管理用于 Claude 账号切换credential-utils.ts—— OS 凭证存储Keychain / Windows Credential Managertoken-refresh.ts—— OAuth token 生命周期与自动刷新usage-monitor.ts—— 每个 Profile 的 API 用量跟踪与限流profile-scorer.ts—— 按用量与可用性给 Profile 打分。终端系统src/main/terminal/完整的 PTY 终端集成pty-daemon.ts/pty-manager.ts—— 后台 PTY 进程管理。守护进程作为独立分离进程运行拥有全部 PTY 实例可跨主进程重启保持会话连续性通信走 Unix socketLinux/macOS或命名管道Windows见 pty-daemon.tsterminal-lifecycle.ts—— 会话创建、清理、事件处理claude-integration-handler.ts—— 终端内的 Claude SDK 集成渲染层xterm.js 6WebGL、fit、web-links、serialize 插件store 为terminal-store.ts。代码质量前端LintBiomenpm run lint/npm run lint:fix类型检查npm run typecheckstrict 模式提交前检查Husky lint-staged 对暂存的.ts/.tsx/.js/.jsx/.json运行 Biome测试Vitest React Testing Library jsdom。i18n 指南所有前端 UI 文本使用react-i18next。翻译文件apps/desktop/src/shared/i18n/locales/{en,fr}/*.json。命名空间common、navigation、settings、dialogs、tasks、errors、onboarding、welcomeimport { useTranslation } from react-i18next; const { t } useTranslation([navigation, common]); span{t(navigation:items.githubPRs)}/span // 正确 spanGitHub PRs/span // 错误 // 带插值 span{t(errors:task.parseError, { error })}/span新增 UI 文本时必须向所有语言文件添加键并使用namespace:section.key格式。跨平台支持支持 Windows、macOS、LinuxCI 测试全部三个平台。平台模块apps/desktop/src/main/platform/函数用途isWindows()/isMacOS()/isLinux()操作系统检测getPathDelimiter();Win或:UnixfindExecutable(name)跨平台可执行文件查找requiresShell(command).cmd/.batshell 检测Win开发时优先使用findExecutable()和joinPaths()而非硬编码路径。补充说明isSecurePath()还会拒绝含 shell 元字符、目录穿越、换行/空字节的路径防止命令注入见 platform/index.ts。E2E 测试Electron MCPQA 代理可以通过 Chrome DevTools Protocol 与运行中的 Electron 应用交互启动应用npm run dev:debug调试模式供 AI 通过 Electron MCP 自我验证在设置中启用 Electron MCPQA 通过 TypeScript 代理管线自动运行。工具包括take_screenshot、click_by_text、fill_input、get_page_structure、send_keyboard_shortcut、eval。相关脚本见 apps/desktop/package.json 中的dev:debug与dev:mcp后者以--remote-debugging-port9222启动供 AI 调试。运行应用# 桌面应用 npm start # 生产构建 运行 npm run dev # 带 HMR 的开发模式 npm run dev:debug # 带详细输出的调试模式 npm run dev:mcp # 供 AI 调试的 Electron MCP 服务器 # 项目数据.auto-claude/specs/gitignored项目数据spec、PR 审查状态、任务日志默认存放在各项目根目录的.auto-claude/下该目录被 gitignore不会污染仓库。至此从硬性规则、协作模式到 AI 代理层源码、前端规范与运行方式Aperant 仓库的核心开发知识已全部覆盖你可以据此直接开始在该仓库中进行规划、实现与验证。赞分享人工智能AI Agent自主智能体代码智能体桌面应用前端开发工具【免费下载链接】AperantAutonomous multi-session AI coding项目地址https://gitcode.com/gh_mirrors/au/Aperant点击查看免费下载相关推荐reth AI 代理开发手册从 Crate 架构地图到代码提交规范reth AI 代理开发手册从 Crate 架构地图到代码提交规范 本文基于 reth 仓库根目录的 CLAUDE.md https://link.gitco区块链Web3后端Litestream AI Agent 开发指南AGENTS.md 核心规则、分层架构与贡献实践Litestream AI Agent 开发指南AGENTS.md 核心规则、分层架构与贡献实践 Litestream 是一款面向 SQLite 的流式灾难恢数据库数据同步灾备高可用Matter SDK 的 AI Agent 开发规范指南从代码风格到构建测试的完整实践手册Matter SDK 的 AI Agent 开发规范指南从代码风格到构建测试的完整实践手册 Matter前身 Project CHIPSDK 是一个由 C物联网智能家居嵌入式通信创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考