AI coding agent with persistent memory and control plane
+The AI coding agent that remembers, plans, collaborates, and finishes
English | - 简体中文 + 简体中文 | + Enterprise
+Desktop 1.4.2 · DeepAgent Core V4.0
+ --- -DeepAgent Code is an AI coding agent built on persistent document memory. It keeps [opencode](https://github.com/sst/opencode)'s runtime foundations and adds a control plane so the agent behaves less like a one-shot chat and more like a teammate that remembers your project, sharpens vague asks, and goes deep on hard problems. +DeepAgent Code is an AI coding workspace for work that lasts longer than one prompt. It combines a production coding-agent runtime with durable sessions, connected project memory, live planning, code intelligence, multi-agent collaboration, and human oversight. + +You can ask for a small edit, guide a running task without interrupting it, hand over a migration with objective completion criteria, or bring several specialist agents into a decision. DeepAgent keeps the work coherent across turns, restarts, tools, people, and projects. + +## One Workspace, Three Ways to Work + +Choose the collaboration style that fits the task: + +| Mode | You provide | DeepAgent does | +|---|---|---| +| **Auto** | A request | Defines the objective, designs and plans as needed, then executes end to end | +| **Loop** | A goal | Writes an editable `goal+plan.md` and advances it through plan, execute, verify, and iterate ticks | +| **Design** | Your `goal+plan.md` | Executes your design faithfully without redefining its objective or completion criteria | + +Autonomy and permission are independent. Use **Read-only**, **Request approval**, or **Full access** without changing the collaboration mode. -The features below start from a real need — something a plain coding agent, opencode included, leaves on the table — and work down to the architecture we built to serve it. +## Stay in Control While It Works -## What You Can Do +DeepAgent is built for active collaboration, not fire-and-forget automation. -### Bring your history over — switch tools without starting from zero +- **Live steering:** send new guidance while a model turn or tool is running. The message is durably admitted and absorbed at the next safe provider-turn boundary without aborting in-flight work. +- **Goal steering:** guidance sent to an active goal is folded into the next tick, preserving the current tool and plan state. +- **Hot plan editing:** edit a running or paused goal. Stable step IDs, evidence, completed work, and the new plan version carry into the next tick. +- **Explicit queueing:** queue a future activity when the instruction should begin after the current activity instead of changing it. +- **Pause, resume, take over, or roll back:** every long-running workflow has a human control path and a durable audit trail. -**The need:** You've built up months of context in another agent — Codex or Claude Code — and switching tools normally means abandoning all of it: the conversations, the accumulated memory, the skills you tuned. That cost alone keeps people on tools they've outgrown. +## Memory You Can Inspect and Govern -**What DeepAgent does:** One-click import of your existing history. Point it at a Codex or Claude Code installation and it hot-imports your chat sessions, memory, and skills straight into DeepAgent — reading each tool's on-disk format, normalizing it, and replaying it into the document graph so imported conversations behave like native ones. Secrets are redacted on the way in, imported projects stay isolated so nothing collides with your active work, and re-running an import converges instead of duplicating. Available from the Settings "Import history" panel, a History view in the sidebar, or the `import-history` CLI command. Migration is a few minutes, not a fresh start. +DeepAgent does not hide memory in an opaque prompt. Project state lives in typed, versioned documents with provenance, confidence, scope, status, and links. -### Keep one conversation going indefinitely +- Session-private working context stays with the current conversation. +- Project-shared facts and decisions follow the repository. +- User-global preferences can travel across projects. +- Built-in skills and domain packs remain versioned system knowledge. +- Sealed evaluator material stays audit-only and never enters model context. -**The need:** Long tasks overflow the context window. Most agents respond by truncating history or summarizing everything at a threshold — so mid-task the agent forgets a decision you made an hour ago, or the window fills with stale tool output and quality falls off a cliff. +Learning follows a governed lifecycle: evidence creates a candidate, isolated review or a human decision changes its status, and regression/ablation gates publish a reproducible knowledge snapshot. Rejection reasons remain durable so discarded patterns are not silently relearned. -**What DeepAgent does:** Your conversation is treated as a continuously maintained work state, not a growing chat log. Before every turn, the agent rebuilds a working set — the task anchor, the most recent exchanges verbatim, active file references, and only the older facts that are relevant right now — while the full history is archived durably and stays queryable. The working set is held to a hard fraction of the model window, so there's always room for the model to actually think and respond. You just keep talking; the agent keeps focus. +The **Repo & Wiki** view makes this system readable. Browse knowledge and execution archives, search across the repository, follow docs-to-code links, inspect lineage, and promote useful run evidence into governed knowledge. -### Switch windows, fork freely, never lose memory +## Connected Context, Not a Larger Prompt -**The need:** You want to try two approaches, or hand the work to a fresh conversation, without starting from amnesia and without polluting the original thread. +DeepAgent connects four views of the project: -**What DeepAgent does:** Fork any conversation from a chosen message. The fork opens carrying the parent's memory up to that point, shows a full-width "derived from" marker at the top of its transcript, and nests folder-style under its origin in the session tree (subagents and forks alike, up to three levels deep). Knowledge flows up a scope hierarchy — what one session learns can be promoted to the whole project, and cross-project preferences live at the user-global layer — so switching windows is a clean handoff, not a reset. +1. **Code graph:** files, symbols, imports, calls, diagnostics, and references. +2. **Knowledge graph:** strategies, methodologies, facts, skills, and failure dossiers. +3. **Project memory:** decisions, constraints, environment facts, and learned conventions. +4. **Document graph:** plans, designs, worklogs, evaluations, run context, and evidence. -### Ask roughly, and let the agent sharpen it +The Session V2 runner assembles context from explicit sources under a durable Context Epoch. It selects linked evidence within budget, records why each reference was admitted or rejected, and preserves the current goal, constraints, decisions, open questions, next steps, and relevant files during compaction. -**The need:** A half-formed prompt gets a half-useful answer, and you don't always know how to phrase what you want. +Prompt caching remains effective across long runs: stable system instructions stay byte-stable, while plans, steering, budgets, round results, and other volatile state are appended in a dedicated tail block. -**What DeepAgent does:** Two scenario modes on the composer. **Direct** sends your prompt as-is — you own the wording. **Intelligence** refines a rough ask into a sharper prompt, surfaces a draft plan and decision suggestions, and waits for your confirmation before it automates anything. You decide how much the agent shapes the request. +## Built for Difficult Work -### Go deep on genuinely hard problems +### AI IDE -**The need:** Complex work — an architecture decision, a tricky migration, a subtle bug — needs more than a single confident pass. It needs research, a second opinion, and someone actively trying to poke holes. +Query code by symbol and intent instead of guessing file locations. DeepAgent combines LSP definitions, references, call chains, type information, diagnostics, rename previews, and cross-file evidence. Unsaved editor buffers participate in LSP updates, so analysis follows the code you are actually editing. -**What DeepAgent does:** At higher work strengths the primary agent decomposes the task, fans it out to focused subagents that research modules in parallel, synthesizes their findings, and then runs independent reviewers whose job is to *break* the plan rather than agree with it. Fan-out is bounded by a configurable concurrency ceiling, and live subagents surface in a session side panel and inline in the transcript so you can watch and jump into any of them. +### Domain packs -### Chat with your team and your agents in one place +Composable domain packs add language, framework, platform, hardware, business, and risk expertise without hardcoding it into the core. Packs activate from the problem profile, resolve conflicts with stricter-policy-wins semantics, and are snapshot-locked for reproducible runs. -**The need:** Coordinating with teammates and driving agents usually happens in two different tools. +### Specialist agents and Expert Panel -**What DeepAgent does:** A per-project group chat lives in the session side panel. @mention an agent as a chat member and it runs the full agent loop — query code, generate, fix — pulling project knowledge and recent messages for context, then replies inline with live progress streaming. +DeepAgent can partition independent work across bounded, isolated workers. Write-capable subagents receive dedicated worktrees, return compact summaries and artifact references, and leave their full transcripts available for inspection. -## How It Works +For high-risk decisions, convene an **Expert Panel**. Correctness, security, performance, architecture, and reproducibility lenses review the same frozen question, debate anonymously for up to three rounds, and feed a deterministic arbiter that preserves minority opinions and fails closed to human review. -Each capability above is served by a control-plane primitive underneath. These are the parts a plain runtime doesn't have. +### Team and agent messaging -**Four-graph unification** — Code, knowledge, project memory, and the document graph are unified into one typed, bidirectionally-linked store. When the agent pulls context, a change to a symbol surfaces the design decisions, past diagnoses, and knowledge actually linked to it — connected context, not four disconnected keyword searches. +Project IM brings people and agents into the same thread. Mention an agent to start a scoped run with project context, stream its progress, inspect its artifacts, and keep the answer attached to the conversation that requested it. -**Domain packs** — 140+ composable knowledge packages spanning languages, frameworks, platforms (cloud, Kubernetes, CI), hardware, and business/risk domains (security, privacy, compliance). Each pack bundles typed documents (strategies, methodologies, knowledge, skills, failure dossiers) with detectors that auto-activate the right packs for your task; conflicts resolve stricter-policy-wins, and the active set is version-locked so a run is reproducible. Core stays domain-neutral — expertise is data on disk, not hardcoded. +## DeepAgent Core V4.1 -**Tiered knowledge invocation** — A monotonic strength ladder (`general → high → xhigh → max → ultra`) gates how much control-plane machinery engages. `general` stays close to the plain runtime — fast and cheap. Higher rungs progressively unlock durable knowledge, project handoff summaries, heavier strategy/methodology tiers, and multi-agent orchestration. You pay for depth only when you dial it up. +V4.1 brings the complete DeepAgent control plane together: -**Self-learning** — After work lands, the agent proposes candidate knowledge, facts, and methodologies. Promotion is evidence-gated (a test passed, a diagnostic cleared, a validation confirmed) and user-controllable — durable knowledge is carried over deliberately, not silently guessed. Session-stable conclusions consolidate into project memory over time, so the next session starts smarter about *your* codebase. +- **Durable Session V2:** prompt admission is persisted before execution; exact retries do not duplicate user intent; same-session wakes coalesce safely. +- **One provider-turn contract:** native and AI SDK providers share the same budget, permission, artifact, audit, learning, and close lifecycle. +- **Single durable truth:** DocumentStore owns documents, plans, learning candidates, governance state, and version conflicts through atomic, recoverable writes. +- **Event-driven Agent OS:** durable events, priority routing, backpressure, worker claims, leases, handoffs, retries, dead-letter recovery, and distributed placement coordinate autonomous work. +- **Consumer-driven goals:** `goal.tick.requested` claims and executes one idempotent tick, records facts, and schedules the next tick only when the durable goal remains eligible. +- **Human oversight:** approval queues, trace correlation, takeover, rollback, Wiki archives, notifications, and organization/workspace isolation remain part of the execution path. +- **Secure integrations:** MCP credentials use environment references or native OS secret storage; catalog risk, runtime permissions, trusted sources, and tool capability checks fail closed. ## Installation +> **Note:** The `deepagent-code` npm package is not yet publicly published. +> Install via the desktop app or the install script below. + ```bash -npm install -g deepagent-code +# Install script (macOS / Linux) +curl -fsSL https://deepagent.ltd/install | bash ``` Then run: @@ -83,12 +121,73 @@ deepagent-code deepagent ``` +## Adding a Provider + +Before you can run a task, DeepAgent Code needs at least one model provider. It +supports 75+ providers through the [AI SDK](https://ai-sdk.dev/) and +[models.dev](https://models.dev), plus any OpenAI- or Anthropic-compatible +endpoint. Pick whichever path fits how you work. + +### Desktop app (recommended) + +Open **Settings → Providers**: + +- **Official providers** (OpenAI, Anthropic, DeepSeek, Google, xAI, ZhipuAI/GLM): + click **Connect**, paste your API key. +- **Any other provider or gateway**: click **Connect** on *Custom provider*, paste + the **Base URL** and **API key**. DeepAgent Code auto-detects the protocol + (OpenAI-compatible or Anthropic) and discovers the available models from the + endpoint's `/models` list — you don't have to fill anything else. + +Model specs (context window, reasoning) are auto-filled by matching each model +against the models.dev catalog. You can reopen a custom provider to override a +model's context/reasoning/temperature; those overrides are best-effort and not +guaranteed to keep the model working. + +### Terminal + +```bash +# Log in to a provider (official providers, or a plugin auth flow) +deepagent auth login + +# See what's connected +deepagent auth list +``` + +### Config file + +Providers also live in `~/.deepagent/code/config.jsonc`. A custom +OpenAI-compatible endpoint looks like this — set `discovery: true` to have models +refreshed from the endpoint at runtime, or list them explicitly under `models`: + +```jsonc +{ + "$schema": "https://deepagent-code.ai/config.json", + "provider": { + "myprovider": { + "name": "My Provider", + "npm": "@ai-sdk/openai-compatible", + "discovery": true, + "options": { + "baseURL": "https://api.myprovider.com/v1", + "apiKey": "sk-..." + } + } + } +} +``` + +Official-provider keys added via the app/CLI are stored separately in +`~/.deepagent/code/auth.json`, not in the config file. See the +[providers guide](https://deepagent-code.ai/docs/providers/) for the full +reference (base URL overrides, headers, per-model config, gateways). + ## Quick Example Start the agent and give it a task: ```bash -deepagent-code "add rate limiting to /api/users endpoint" +deepagent-code run "add rate limiting to /api/users endpoint" ``` The agent will: @@ -115,7 +214,7 @@ On your next session, when you ask to add rate limiting elsewhere, the agent alr ## Architecture -``` +```text ┌─────────────────────────────────────────────────────────────┐ │ Control Plane (DeepAgent additions) │ │ • Four-graph unified store (code + knowledge + memory + doc)│ @@ -123,6 +222,7 @@ On your next session, when you ask to add rate limiting elsewhere, the agent alr │ • Domain pack system (composable, auto-activating knowledge)│ │ • Context assembly & admission gates │ │ • Multi-agent orchestration & adversarial review │ +│ • Supervised goal loop & expert panel (event-driven) │ │ • Evidence-gated learning & work-strength ladder │ └─────────────────────────────────────────────────────────────┘ │ @@ -143,24 +243,57 @@ On your next session, when you ask to add rate limiting elsewhere, the agent alr └─────────────────────────────────────────────────────────────┘ ``` -DeepAgent's control plane operates at provider-turn boundaries: it selects context before each model call and writes evidence back into the document graph afterward. It does not replace opencode's runtime — it layers on top. +The full architecture and its invariants are documented in [Architecture & Design](design/README.md). + +## Build From Source + +DeepAgent Code uses Bun 1.3.14. + +```bash +git clone https://github.com/deepagent-ltd/deepagent-code.git +cd deepagent-code +bun install +``` + +Start the Desktop app: + +```bash +bun run dev:desktop +``` + +Start the terminal experience: + +```bash +bun run dev +``` + +Run a one-shot task: + +```bash +bun run --cwd packages/deepagent-code dev run "add rate limiting to /api/users" +``` + +Import existing Codex or Claude Code history: + +```bash +bun run --cwd packages/deepagent-code dev import-history --from codex --dry-run +``` ## Documentation -- [Architecture & Design](design/README.md) — Control plane, code intelligence, MCP security model -- [Security Policy](SECURITY.md) — Vulnerability reporting, known limitations -- [Privacy Policy](PRIVACY.md) — Data handling and storage -- [Contributing](CONTRIBUTING.md) — Development setup and guidelines -- [Changelog](CHANGELOG.md) — Release history +- [Providers & Models](https://deepagent-code.ai/docs/providers/) +- [Architecture & Design](design/README.md) +- [Security Policy](SECURITY.md) +- [Privacy Policy](PRIVACY.md) +- [Contributing](CONTRIBUTING.md) +- [Changelog](CHANGELOG.md) ## License & Attribution -DeepAgent Code is licensed under **AGPL-3.0-or-later**. If you modify and run it as a network service, you must make your source code available to users. +DeepAgent Code is licensed under **AGPL-3.0-or-later**. If you modify and run it as a network service, you must make the corresponding source available to its users. -This project is derived from [opencode](https://github.com/sst/opencode) (MIT License). See [NOTICE](NOTICE) for the upstream license and attribution. No endorsement by opencode or its contributors is implied. +DeepAgent Code is derived from [opencode](https://github.com/sst/opencode) under the MIT License. See [NOTICE](NOTICE) for upstream attribution. No endorsement by opencode or its contributors is implied. --- -- Built by DeepAgent -
+Built by DeepAgent
diff --git a/README.zh.md b/README.zh.md index 9d1618ab..15a1714d 100644 --- a/README.zh.md +++ b/README.zh.md @@ -6,68 +6,102 @@ -具备持久记忆与控制平面的 AI 编程智能体
+会记忆、会规划、会协作，也能把工作真正做完的 AI 编程智能体
English | - 简体中文 + 简体中文 | + Enterprise 版本
+桌面版 1.4.1 · DeepAgent Core V4.1
+ --- -DeepAgent Code 是一个构建在持久文档记忆之上的 AI 编程智能体。它保留了 [opencode](https://github.com/sst/opencode) 的运行时基座，并在其上叠加了一层控制平面——让智能体不再像一次性的对话工具，而更像一位记得住你项目、会替你打磨模糊需求、能对硬骨头深挖到底的队友。 +DeepAgent Code 是一套面向长期工作的 AI 编程工作区。它把生产级编程智能体运行时与持久会话、相互连通的项目记忆、实时计划、代码智能、多智能体协作和人类监督组合在一起。 + +你可以让它完成一次小改动，在任务运行中继续补充指令，把一场迁移交给带客观完成判据的目标回路，或者召集多位专家共同审阅一项决策。DeepAgent 会让工作在多轮对话、进程重启、工具调用、团队成员和不同项目之间保持连贯。 + +## 一个工作区，三种协作方式 + +按任务选择最合适的协作方式： + +| 模式 | 你提供 | DeepAgent 负责 | +|---|---|---| +| **自动（Auto）** | 一项需求 | 自行明确目标，按需设计和规划，再端到端执行 | +| **循环（Loop）** | 一个目标 | 生成可编辑的 `goal+plan.md`，按计划、执行、校验、迭代逐 tick 推进 | +| **设计（Design）** | 你编写的 `goal+plan.md` | 忠实执行你的设计，不重新定义目标或完成判据 | + +自主程度和权限相互独立。你可以在不改变协作模式的情况下选择**只读**、**请求批准**或**完全访问**。 -下面的每一项特性，都从一个真实的需求出发——一个普通编程智能体（包括 opencode）尚未满足的需求——再向下讲到我们为满足它而构建的底层架构。 +## 它在工作，你仍然掌控全局 -## 你可以做什么 +DeepAgent 为持续协作而设计，不是一个发出指令后只能等待的黑盒。 -### 把历史一起带过来——换工具不必从零开始 +- **实时 Steering：** 模型或工具仍在运行时继续发送指导。消息会先持久化，再在下一个安全的供应商轮次边界被吸收，不会中断在飞工作。 +- **Goal Steering：** 发给活跃目标的指导会进入下一个 tick，同时保留当前工具状态和计划状态。 +- **运行中计划热编辑：** 编辑正在运行或已暂停的目标。稳定的步骤 ID、证据、已完成工作和新计划版本会一起进入下一 tick。 +- **显式排队：** 当一条指令应该在当前 activity 结束后独立开始时，把它放入未来队列，而不是改变当前工作。 +- **暂停、恢复、接管或回滚：** 每个长跑流程都有清晰的人类控制路径和持久审计记录。 -**需求：** 你已经在另一个智能体里——Codex 或 Claude Code——积累了几个月的上下文，而换工具通常意味着把这一切统统丢下：那些对话、沉淀下来的记忆、你调好的技能。单是这份代价，就足以把人留在早该告别的工具上。 +## 看得见、管得住的记忆 -**DeepAgent 的做法：** 一键导入你已有的历史。把它指向一个 Codex 或 Claude Code 的安装目录，它就会把你的会话、记忆和技能热导入 DeepAgent——读取各工具的本地格式，归一化后重放进文档图，让导入的对话表现得和原生对话一样。导入过程中会对密钥做脱敏，导入的项目彼此隔离、不会和你正在进行的工作冲突，重复导入会收敛而不是产生重复。入口有三处：设置里的"导入历史"面板、侧栏的历史视图，以及 `import-history` 命令行。迁移只需几分钟，而不是推倒重来。 +DeepAgent 不会把记忆藏在不可见的提示词里。项目状态保存在带类型、版本、来源、置信度、作用域、状态和链接的文档中。 -### 一直对话下去，不必换新 +- 会话私有工作上下文只属于当前对话。 +- 项目共享事实与决策跟随代码仓库。 +- 用户全局偏好可以跨项目使用。 +- 内置技能与领域包保持系统级版本管理。 +- 封存的评测材料仅用于审计，永不进入模型上下文。 -**需求：** 长任务会撑爆上下文窗口。多数智能体的应对方式是截断历史，或在阈值处一刀切地整体摘要——于是任务进行到一半，智能体忘了你一小时前拍的板，或者窗口被陈旧的工具输出塞满，质量断崖式下跌。 +学习遵循可治理的生命周期：证据生成候选，隔离审阅或人工决策改变候选状态，回归与消融门发布可复现的知识快照。拒绝理由会持久保存，因此被淘汰的模式不会在后台被悄悄重新学习。 -**DeepAgent 的做法：** 你的对话被当作一份持续维护的工作状态，而不是不断变长的聊天记录。每一轮开始前，智能体都会重建一份工作面——任务锚点、最近若干轮的原文、活跃的文件引用，以及此刻真正相关的旧事实——同时完整历史被持久归档、随时可查。工作面被严格控制在模型窗口的一个固定比例以内，永远给模型留足思考和作答的余地。你只管一直说，智能体替你保持专注。 +**仓库与百科（Repo & Wiki）** 让这套系统对人可读。你可以浏览知识与执行档案、搜索整个仓库、沿文档到代码的链接探索上下文、检查来源链，并把有价值的运行证据升格为受治理知识。 -### 随手分叉、切换窗口，记忆不丢 +## 相互连接的上下文，而不是更长的提示词 -**需求：** 你想同时试两条思路，或把工作交给一个全新的对话，却不想从头失忆重来，也不想把原来的线程搅乱。 +DeepAgent 把项目的四个视图连接在一起： -**DeepAgent 的做法：** 从任意一条消息分叉当前对话。分叉出的新对话会继承父对话到该点为止的记忆，在时间线顶部显示一条贯穿窗口的"从对话派生"分割线，并像文件夹一样嵌套挂在来源对话之下（子 agent 与分叉同理，最多三层深）。知识沿作用域层级向上流动——单个会话学到的东西可提升到整个项目，跨项目的偏好则沉淀在用户全局层——所以换窗口是一次干净的交接，而非一次清零重来。 +1. **代码图：** 文件、符号、导入、调用、诊断与引用。 +2. **知识图：** 策略、方法论、事实、技能与故障档案。 +3. **项目记忆：** 决策、约束、环境事实与已学习的项目约定。 +4. **文档图：** 计划、设计、工作日志、评测、运行上下文与证据。 -### 想到哪问到哪，让智能体替你打磨 +Session V2 运行器在持久 Context Epoch 下从明确的 Context Source 装配上下文。它在预算内选择相互关联的证据，记录每条引用为什么被准入或拒绝，并在压缩时保留当前目标、约束、决策、开放问题、后续步骤与相关文件。 -**需求：** 半成品的提问只能换来半有用的回答，而你未必总知道该怎么把想要的东西说清楚。 +长跑任务也能持续命中提示词缓存：稳定 system 指令保持字节级稳定，计划、Steering、预算、轮次结果等易变状态只追加到独立的尾部区块。 -**DeepAgent 的做法：** 输入框上有两种情景模式。**直接**模式原样发送你的提示——措辞由你做主。**智能**模式会把粗糙的想法打磨成更精准的提示，给出草拟的方案和决策建议，并在自动执行任何操作前等你确认。智能体替你塑形到什么程度，由你决定。 +## 为困难工作而生 -### 对真正的难题深挖到底 +### AI IDE -**需求：** 复杂的工作——一个架构决策、一次棘手的迁移、一个隐蔽的 bug——需要的不止一次自信的单程作答。它需要调研、需要第二意见、需要有人主动来挑刺。 +按符号和意图查询代码，不再猜文件位置。DeepAgent 组合 LSP 定义、引用、调用链、类型信息、诊断、重命名预览与跨文件证据。未保存的编辑器 buffer 也会实时进入 LSP，因此分析看到的是你正在编辑的代码。 -**DeepAgent 的做法：** 在更高的工作强度下，主智能体会拆解任务，扇出给专注的子 agent 并行调研各个模块，综合它们的发现，再运行独立的审阅者——审阅者的职责是"击破"方案，而不是附和。扇出受可配置的并发上限约束；运行中的子 agent 会出现在会话侧栏面板和时间线内联卡片里，你可以旁观并随时跳进任意一个。 +### 领域包 -### 团队与智能体，在同一处协作 +可组合的领域包提供语言、框架、平台、硬件、业务与风险知识，而不把专业逻辑硬编码进内核。领域包根据问题画像自动激活，以“更严格策略优先”解决冲突，并锁定快照以保证运行可复现。 -**需求：** 和队友协调、驱动智能体，通常发生在两个不同的工具里。 +### 专业子智能体与 Expert Panel -**DeepAgent 的做法：** 每个项目的群聊就在会话侧栏里。把某个智能体 @ 进来当作聊天成员，它便会跑完整的智能体回路——查代码、生成、修复——拉取项目知识与最近消息作为上下文，然后带着实时进度在群里内联回复。 +DeepAgent 可以把独立工作拆分给数量有界、相互隔离的 Worker。具备写权限的子智能体获得独立 worktree，只向父会话返回紧凑摘要和工件引用，完整执行记录仍可随时查看。 -## 它是怎么做到的 +高风险决策可以召集 **Expert Panel**。正确性、安全、性能、架构与可复现性等专家视角审阅同一个冻结问题，进行最多三轮匿名辩论，再由确定性仲裁器生成裁定。少数派意见会被保留，无法安全达成一致时会失败关闭并交给人类。 -上面每一项能力，底层都由一个控制平面原语来支撑。这些正是普通运行时所没有的部分。 +### 团队与智能体消息 -**四图合一** — 代码图、知识图、项目记忆、文档图被统一进同一个带类型、双向链接的存储。当智能体拉取上下文时，对某个符号的改动会连带浮现出与它真正相连的设计决策、过往诊断和知识——是连通的上下文，而不是四次互不相干的关键词检索。 +项目 IM 把团队成员和智能体放进同一条讨论。@ 某个智能体即可启动有明确作用域的运行，使用项目上下文、流式展示进度、关联执行工件，并把答案留在发起任务的对话里。 -**领域包** — 140+ 个可组合的知识包，覆盖编程语言、框架、平台（云、Kubernetes、CI）、硬件，以及业务/风险领域（安全、隐私、合规）。每个包捆绑了带类型的文档（策略、方法论、知识、技能、故障档案）与探测器，能为你的任务自动激活相应的包；冲突按"更严策略优先"消解，激活的集合会被版本锁定，从而让一次运行可复现。内核保持领域中立——专业能力是磁盘上的数据，而非写死的代码。 +## DeepAgent Core V4.1 -**知识分级调用** — 一条单调递增的强度阶梯（`general → high → xhigh → max → ultra`）决定控制平面机器启动到什么程度。`general` 贴近原生运行时——又快又省。越往上，逐级解锁持久知识、项目交接摘要、更重的策略/方法论层，以及多智能体编排。只有当你上调档位时，才为深度付费。 +V4.1 把完整的 DeepAgent 控制平面汇聚在一起： -**自学习** — 工作落地后，智能体会提出候选的知识、事实与方法论。晋升是证据门控的（一项测试通过、一条诊断清零、一次校验确认）且由用户掌控——持久知识是被有意结转的，而非后台悄悄猜出来的。会话中稳定的结论会随时间巩固进项目记忆，于是下一次会话对*你的*代码库上手更聪明。 +- **持久 Session V2：** prompt 先持久准入、再调度执行；精确重试不会复制用户意图；同一 Session 的唤醒会安全合并。 +- **统一供应商轮次合同：** native 与 AI SDK provider 共享预算、权限、工件、审计、学习和关闭生命周期。 +- **单一持久真相：** DocumentStore 通过原子、可恢复写入统一管理文档、计划、学习候选、治理状态和版本冲突。 +- **事件驱动 Agent OS：** 持久事件、优先级路由、回压、Worker claim、租约、handoff、重试、死信恢复与分布式 placement 协调自主工作。 +- **消费者驱动 Goal：** `goal.tick.requested` 每次认领并执行一个幂等 tick，记录事实，并只在持久目标仍满足条件时调度下一 tick。 +- **人类监督：** 审批队列、全链路 trace、接管、回滚、Wiki 档案、通知，以及组织和 workspace 隔离始终位于执行路径上。 +- **安全集成：** MCP 凭据使用环境变量引用或原生操作系统 secret storage；目录风险、运行时权限、可信来源和工具 capability 逐层失败关闭。 ## 安装 @@ -83,6 +117,62 @@ deepagent-code deepagent ``` +## 添加供应商 + +在运行任务之前，DeepAgent Code 至少需要一个模型供应商。它通过 +[AI SDK](https://ai-sdk.dev/) 和 [models.dev](https://models.dev) 支持 75+ 家供应商， +以及任意 OpenAI 或 Anthropic 兼容的接口。按你习惯的方式选一种即可。 + +### 桌面应用（推荐） + +打开 **设置 → 供应商（Settings → Providers）**： + +- **官方供应商**（OpenAI、Anthropic、DeepSeek、Google、xAI、智谱/GLM）：点击 + **连接**，粘贴你的 API Key。 +- **其他供应商或网关**：在「自定义供应商」上点击 **连接**，填入 **Base URL** 和 + **API Key**。DeepAgent Code 会自动探测协议（OpenAI 兼容或 Anthropic），并从接口的 + `/models` 列表自动发现可用模型——其余字段无需填写。 + +模型规格（上下文窗口、推理能力）会通过与 models.dev 目录按模型 id 匹配来自动补全。 +你可以再次打开自定义供应商，覆盖某个模型的上下文/推理/温度；这些覆盖为尽力而为的默认值， +修改后不保证模型仍能正常使用。 + +### 终端 + +```bash +# 登录供应商（官方供应商，或插件鉴权流程） +deepagent auth login + +# 查看已连接的供应商 +deepagent auth list +``` + +### 配置文件 + +供应商也保存在 `~/.deepagent/code/config.jsonc` 中。一个自定义 OpenAI 兼容接口如下—— +设 `discovery: true` 让模型在运行时从接口刷新，或在 `models` 下显式列出： + +```jsonc +{ + "$schema": "https://deepagent-code.ai/config.json", + "provider": { + "myprovider": { + "name": "My Provider", + "npm": "@ai-sdk/openai-compatible", + "discovery": true, + "options": { + "baseURL": "https://api.myprovider.com/v1", + "apiKey": "sk-..." + } + } + } +} +``` + +通过应用/CLI 添加的官方供应商密钥单独存放在 `~/.deepagent/code/auth.json`，不在配置文件里。 +完整参考（Base URL 覆盖、请求头、逐模型配置、网关）见 +[供应商文档](https://deepagent-code.ai/docs/providers/)。 + ## 快速示例 启动智能体并交给它一个任务： @@ -115,7 +205,7 @@ deepagent-code "为 /api/users 端点添加限流" ## 架构 -``` +```text ┌─────────────────────────────────────────────────────────────┐ │ 控制平面（DeepAgent 新增） │ │ • 四图合一存储（代码 + 知识 + 记忆 + 文档） │ @@ -123,6 +213,7 @@ deepagent-code "为 /api/users 端点添加限流" │ • 领域包系统（可组合、自动激活的知识） │ │ • 上下文装配与准入门 │ │ • 多智能体编排与对抗式审阅 │ +│ • 受监督的目标回路与专家团（事件驱动） │ │ • 证据门控的学习 + 工作强度阶梯 │ └─────────────────────────────────────────────────────────────┘ │ @@ -143,24 +234,57 @@ deepagent-code "为 /api/users 端点添加限流" └─────────────────────────────────────────────────────────────┘ ``` -DeepAgent 的控制平面在供应商轮次的边界上运作：在每次模型调用前挑选上下文，调用后把证据写回文档图。它不替换 opencode 的运行时——只是叠加在其之上。 +完整架构与不变量见 [架构与设计](design/README.md)。 + +## 从源码运行 + +DeepAgent Code 使用 Bun 1.3.14。 + +```bash +git clone https://github.com/deepagent-ltd/deepagent-code.git +cd deepagent-code +bun install +``` + +启动桌面应用： + +```bash +bun run dev:desktop +``` + +启动终端界面： + +```bash +bun run dev +``` + +执行一次性任务： + +```bash +bun run --cwd packages/deepagent-code dev run "为 /api/users 添加限流" +``` + +导入已有 Codex 或 Claude Code 历史： + +```bash +bun run --cwd packages/deepagent-code dev import-history --from codex --dry-run +``` ## 文档 -- [架构与设计](design/README.md) — 控制平面、代码智能、MCP 安全模型 -- [安全策略](SECURITY.md) — 漏洞上报、已知限制 -- [隐私政策](PRIVACY.md) — 数据处理与存储 -- [贡献指南](CONTRIBUTING.md) — 开发环境与规范 -- [更新日志](CHANGELOG.md) — 发布历史 +- [供应商与模型](https://deepagent-code.ai/docs/providers/) +- [架构与设计](design/README.md) +- [安全策略](SECURITY.md) +- [隐私策略](PRIVACY.md) +- [贡献指南](CONTRIBUTING.md) +- [更新日志](CHANGELOG.md) ## 许可与署名 -DeepAgent Code 采用 **AGPL-3.0-or-later** 许可。如果你修改并将其作为网络服务运行，必须向用户提供你的源代码。 +DeepAgent Code 使用 **AGPL-3.0-or-later** 许可。如果你修改本项目并将其作为网络服务运行，必须向服务用户提供对应源代码。 -本项目衍生自 [opencode](https://github.com/sst/opencode)（MIT 许可）。完整的上游许可与署名见 [NOTICE](NOTICE)。本项目不暗示 opencode 或其贡献者的任何背书。 +DeepAgent Code 基于 [opencode](https://github.com/sst/opencode) 的 MIT 许可代码演进而来。上游署名见 [NOTICE](NOTICE)。本项目不暗示 opencode 或其贡献者的任何背书。 --- -- 由 DeepAgent 打造 -
+Built by DeepAgent
diff --git a/SECURITY.md b/SECURITY.md index dc4bf2ae..ee97178b 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -8,7 +8,7 @@ Do not include live secrets in reports. Use redacted examples or synthetic crede ## Supported versions -Before the first public stable tag, the supported line is the current `main` branch and the latest published pre-release. Security fixes may be released as patch versions. +The active development line is the `dev` branch. The supported release is the latest published version on the `core-v4.0-beta` branch and the desktop app release derived from it. Security fixes are applied to the active line and backported to the latest release where feasible. ## Source availability @@ -20,13 +20,13 @@ Preset MCP servers are opt-in. The preset catalog records intended risk tiers, b Read-only database presets are intended to use restricted server modes and SQL guardrails. Guardrails are defense in depth, not a substitute for least-privilege database users. -## Known limitation: preset MCP credentials in V3.4.1 +## MCP credential security (V4.0+) -When enabling preset MCP servers that require credentials, credential values may currently be persisted in local configuration. Until V3.5 M-CRED lands: +As of V4.0, MCP server credentials are stored in OS-backed secret storage where available (macOS Keychain; Linux and Windows fall back to a 0600 file). Credential values are not persisted in plain-text configuration. Only variable names or references travel through config files; values are resolved at runtime. + +If you are running a version older than V4.0: - Do not commit DeepAgent Code configuration files containing secrets. - Prefer environment-variable indirection where a server supports it. - Use least-privilege tokens and database users. - Rotate credentials if they were accidentally committed or shared. - -The planned V3.5 M-CRED work stores secrets in OS-backed secret storage where available (macOS Keychain, Windows Credential Manager, Linux Secret Service), passes only variable names or references through configuration, and resolves values at runtime. diff --git a/github/README.md b/github/README.md index 86f4d99f..9d75e57b 100644 --- a/github/README.md +++ b/github/README.md @@ -88,7 +88,7 @@ This will walk you through installing the GitHub app, creating the workflow, and persist-credentials: false - name: Run deepagent-code - uses: lessweb/deepagent-code/github@latest + uses: deepagent-ltd/deepagent-code/github@latest env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} @@ -101,7 +101,7 @@ This will walk you through installing the GitHub app, creating the workflow, and ## Support -This is an early release. If you encounter issues or have feedback, please create an issue at https://github.com/lessweb/deepagent-code/issues. +This is an early release. If you encounter issues or have feedback, please create an issue at https://github.com/deepagent-ltd/deepagent-code/issues. ## Development diff --git a/github/action.yml b/github/action.yml index 47f9d13d..249fd2a9 100644 --- a/github/action.yml +++ b/github/action.yml @@ -45,7 +45,7 @@ runs: id: version shell: bash run: | - VERSION=$(curl -sf https://api.github.com/repos/lessweb/deepagent-code/releases/latest | grep -o '"tag_name": *"[^"]*"' | cut -d'"' -f4) + VERSION=$(curl -sf https://api.github.com/repos/deepagent-ltd/deepagent-code/releases/latest | grep -o '"tag_name": *"[^"]*"' | cut -d'"' -f4) echo "version=${VERSION:-latest}" >> $GITHUB_OUTPUT - name: Cache deepagent-code diff --git a/package.json b/package.json index 6e0cdade..4d838030 100644 --- a/package.json +++ b/package.json @@ -19,7 +19,7 @@ "prepare": "husky", "random": "echo 'Random script'", "sso": "aws sso login --sso-session=deepagent-code --no-browser", - "test": "echo 'do not run tests from root' && exit 1" + "test": "bun run --cwd packages/app test && bun run --cwd packages/ui test" }, "workspaces": { "packages": [ diff --git a/packages/app/README.md b/packages/app/README.md index 9040c386..1bf37cbd 100644 --- a/packages/app/README.md +++ b/packages/app/README.md @@ -1,33 +1,32 @@ -## Usage +# @deepagent-code/app — Desktop Application -Dependencies for these templates are managed with [pnpm](https://pnpm.io) using `pnpm up -Lri`. +SolidJS front-end shell for the DeepAgent Code desktop app (Electron/Tauri). -This is the reason you see a `pnpm-lock.yaml`. That said, any package manager will work. This file can safely be removed once you clone a template. +## Stack -```bash -$ npm install # or pnpm install or yarn install -``` - -### Learn more on the [Solid Website](https://solidjs.com) and come chat with us on our [Discord](https://discord.com/invite/solidjs) - -## Available Scripts +- **UI:** SolidJS + Vite (Bun) +- **Backend:** `deepagent-code` package spawned as a local server or connected via the server-mode gateway +- **Build output:** `dist/` — consumed by the Electron/Tauri packager in CI -In the project directory, you can run: +## Development -### `npm run dev` or `npm start` +```bash +# from repo root +bun install +bun run dev # hot-reload dev server +``` -Runs the app in the development mode.