Aperant（Auto Claude）开发指南：从架构规则到 AI 代理层的 TypeScript 实践手册

• 人工智能
• AI Agent
• 自主智能体
• 代码智能体
• 桌面应用
• 前端
• 开发工具

本文是开源项目 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 修复代理解决问题 → 用户审查并合并。

主要功能清单：

硬性开发规则：不可逾越的约束

CLAUDE.md 明确列出若干“Critical Rules”，这些规则约束着所有代码贡献，并且每条都能在源码中找到对应实现。

Vercel AI SDK only（AI 交互唯一技术栈）——所有 AI 交互必须使用 Vercel AI SDK v6（ai包），通过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.ts）；
• OpenAI 的 Codex OAuth 账号会把所有 URL 重写到 Codex Responses 端点，因此这类账号的所有模型都必须走.responses()，否则会因 Chat Completions 格式与 Responses 端点不匹配而返回 400（见 factory.ts）；
• Ollama 需要自动补/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→SIGKILL，Windows 用kill()→taskkill /f /t）。

其他规则：

• 不提供时间估算——只按优先级排序，不做耗时预测；
• PR 目标分支——PR 一律指向develop分支而非main，main只用于发布；
• 生产代码禁用 console.log——打包后的 Electron 应用中console.log不可见，生产环境用 Sentry 追踪错误，console.log仅供开发调试。

Orchestrator-First 工作模式

CLAUDE.md 强调开发者应把自己定位为“orchestrator（编排者）”：核心职责是理解需求、拆分为工作流、把执行委托给代理团队，从而把上下文窗口集中在协调与决策上，而不是被实现细节塞满。

标准的 orchestrator 模式包含四步：

1. 先调查（Investigate first）——在形成任何假设前先读实际代码。简单查询用定向搜索（Glob、Grep、Read）；更广泛的探索则派生 Explore 代理。
2. 规划方案（Plan the approach）——识别需要改什么、涉及哪些文件、能否并行。多步骤任务用任务清单跟踪工作流。
3. 委托执行（Delegate execution）——派生代理团队做实现。每个代理拿到清晰自包含的任务，包含相关文件路径、具体改动与验收标准；独立工作流并行运行。
4. 验证与集成（Verify and integrate）——审查代理输出、运行测试、确保改动协同工作；必要时修复集成问题或派生跟进代理。

何时委托 vs 直接做：

• 委托：多文件改动、跨代码库研究、独立并行工作流、会消耗大量上下文的任务；
• 直接做：单文件编辑、简单 bug 修复、快速查询、已掌握上下文的任务。

给代理好任务的关键：每个代理都从全新上下文开始，任务书要包含具体目标、相关文件路径、要遵循的代码模式以及“完成”的定义。显式完整的指令远好于模糊引用“当前任务”。

最小改动原则——优先最简单的方案（例如仅改 prompt、单个 guard clause），再考虑多组件方案。用户要求 X 就实现 X，不要捆绑额外的修复。

默认行动——当用户意图暗含改动时，直接实现而不是只提建议；不确定就阅读相关代码补全信息，而不是反复提问；只有在用户真实意图仍存在歧义时才发问。

上下文管理与长任务策略

代理的上下文窗口接近上限时会被自动压缩（compaction），因此可以无限期持续工作。不要因担心上下文而提前停止任务——持续记录进度继续前进。

针对长任务的实践：

• 用 git commit、任务清单和结构化笔记跟踪状态；
• 上下文压缩后，通过git log和进度文件重新定位；
• 聚焦增量进展——完成一个组件再推进下一个，边做边提交可工作的状态。

并行工具调用——读取多个文件、运行独立搜索或执行无关命令时，所有调用应并行而非串行，这能显著加速调查与实现。

已知坑（Known Gotchas）

Electron 路径解析——修复 Electron 应用 bug 时，必须检查开发与生产构建之间的路径解析差异（app.isPackaged、process.resourcesPath）。开发环境正常工作的路径在 Electron 打包为生产版本后常常失效，两种上下文都要验证。

重置 PR Review 状态——要完全清空所有 PR 审查数据让审查从零开始，需要删除/重置.auto-claude/github/下三处内容：

1. rm .auto-claude/github/pr/logs_*.json—— 审查日志文件；
2. rm .auto-claude/github/pr/review_*.json—— 审查结果文件；
3. 将pr/index.json重置为{"reviews": [], "last_updated": null}；
4. 将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/ # 自定义 hooks（useIpc, 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

测试：

发布：

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 dev（electron-vite 开发模式）、npm run build、npm run typecheck（tsc 严格模式）、npm run lint（Biome）、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()支持多 Provider：Anthropic、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/）

此外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_TOOLS（Read、Glob、Grep、Write、WebFetch、WebSearch），没有 Edit 和 Bash，且都挂载context7MCP；
• build_orchestrator拥有全部内置工具 +SpawnSubagent，MCP 服务器为context7、memory、auto-claude，可选linear，默认 thinking 级别为high；
• coder拥有全部内置工具，默认 thinking 级别low（编码追求速度）；
• qa_reviewer/qa_fixer额外挂载browserMCP（electron 或 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、TypeScript（strict）、Electron 39、Vercel AI SDK v6、Zustand 5、Tailwind CSS v4、Radix UI、xterm.js 6、Vite 7、Vitest 4、Biome 2、Motion（Framer Motion）。

路径别名（tsconfig.json）

状态管理（Zustand）

所有状态位于src/renderer/stores/，关键 store：

• project-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。

主进程同样有 store：src/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 自定义属性提供明暗两套变体；
• 工具函数：clsx+tailwind-merge（cn()辅助函数）；
• 组件变体：class-variance-authority（CVA）。

IPC 通信

主进程 ↔ 渲染进程通过 Electron IPC 通信：

• Handlers：apps/desktop/src/main/ipc-handlers/ —— 按领域划分（github、gitlab、ideation、context、task、terminal 等 40+ 模块）；
• Preload：apps/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 Manager）；
• token-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 socket（Linux/macOS）或命名管道（Windows），见 pty-daemon.ts；
• terminal-lifecycle.ts—— 会话创建、清理、事件处理；
• claude-integration-handler.ts—— 终端内的 Claude SDK 集成；
• 渲染层：xterm.js 6（WebGL、fit、web-links、serialize 插件），store 为terminal-store.ts。

代码质量

前端

• Lint：Biome（npm run lint/npm run lint:fix）；
• 类型检查：npm run typecheck（strict 模式）；
• 提交前检查：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、welcome

import { useTranslation } from 'react-i18next'; const { t } = useTranslation(['navigation', 'common']); <span>{t('navigation:items.githubPRs')}</span> // 正确 <span>GitHub PRs</span> // 错误 // 带插值： <span>{t('errors:task.parseError', { error })}</span>

新增 UI 文本时必须：向所有语言文件添加键，并使用namespace:section.key格式。

跨平台支持

支持 Windows、macOS、Linux，CI 测试全部三个平台。

平台模块：apps/desktop/src/main/platform/

开发时优先使用findExecutable()和joinPaths()而非硬编码路径。补充说明：isSecurePath()还会拒绝含 shell 元字符、目录穿越、换行/空字节的路径，防止命令注入（见 platform/index.ts）。

E2E 测试（Electron MCP）

QA 代理可以通过 Chrome DevTools Protocol 与运行中的 Electron 应用交互：

1. 启动应用：npm run dev:debug（调试模式，供 AI 通过 Electron MCP 自我验证）；
2. 在设置中启用 Electron MCP；
3. QA 通过 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-port=9222启动，供 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
• 自主智能体
• 代码智能体
• 桌面应用
• 前端
• 开发工具