diff --git a/docs/README.md b/docs/README.md index 379b13f..1c3526f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,31 +1,32 @@ -# 文档索引 +# llm-to-agent 文档 -本文档记录 `llm-to-agent` 当前已达成的产品与架构共识。它不是固定开发清单：实现前再细化当前功能点，发现新需求则补到对应功能文档中。 +文档分为三部分： -## 使用方式 +- [架构总览](architecture.md)：稳定的职责边界与依赖原则； +- [规划目录](directory-plan.md)：当前建议的源码与运行数据布局，允许随实际开发调整； +- [实现阶段](roadmap.md)：先完成基本能力，再建立自举，随后由 Agent 继续实现自己的开发顺序； +- `features/`：按整个项目的大功能分类，列出尽量完整且有实质性交付的小功能点。 -- 每个大功能点一个文件，大功能本身不设置状态或阶段。 -- 大功能文档内部拆分小功能点，每项分别记录期望实现阶段、实际开发状态、已确认点和待确认点。 -- 阶段只表示期望先后，不构成严格依赖顺序；实际开发状态按实施进展更新。 -- 每完成一个独立提交，在对应小功能点中补充提交、blog 和实现说明。 +## 功能目录 -## 导航 +- [Runtime 与内核](features/runtime.md) +- [本地数据与配置](features/data-config.md) +- [Space、Conversation 与消息](features/spaces.md) +- [模型、聊天与 Agent](features/model-agent.md) +- [Run 与 Agent 执行](features/run-execution.md) +- [Tools、Workspace 与产物](features/tools-execution.md) +- [CLI](features/cli.md) +- [Project 开发助手](features/project-assistant.md) +- [System Evolution](features/system-evolution.md) +- [扩展、Hooks 与 Profile](features/extensions.md) +- [计划、工作流与多 Agent](features/planning-multi-agent.md) +- [记忆、检索与知识](features/memory-knowledge.md) +- [浏览器](features/browser.md) +- [本机与桌面控制](features/desktop-control.md) +- [自动化与后台任务](features/automation.md) +- [可观测性与可靠性](features/observability-reliability.md) +- [权限、确认与敏感数据](features/permissions-security.md) +- [Web](features/web.md) +- [Desktop](features/desktop.md) -- [路线图与管理规则](roadmap.md) -- [架构总览](architecture/overview.md) -- [本地数据与目录](architecture/local-data.md) -- [Runtime](foundation/runtime.md) -- [CLI](foundation/cli.md) -- [Space 与 Conversation](foundation/spaces.md) -- [模型与聊天](agent/model-chat.md) -- [Run 与 Agent Behavior](agent/runs-behavior.md) -- [Tools 与 Workspace](agent/tools-workspace.md) -- [Project 开发助手](development/project-assistant.md) -- [System Evolution](development/system-evolution.md) -- [Hooks、扩展与 Profile](extension/hooks-extensions.md) -- [计划与多 Agent](intelligence/planning-multi-agent.md) -- [记忆与知识](intelligence/memory-knowledge.md) -- [电脑管家与自动化](automation/computer-butler.md) -- [可靠性与个人安全](operations/reliability-safety.md) -- [Web](clients/web.md) -- [Desktop](clients/desktop.md) +具体字段、技术库和交互细节在进入对应实现阶段时讨论，不用早期规划替代真实开发反馈。 diff --git a/docs/agent/model-chat.md b/docs/agent/model-chat.md deleted file mode 100644 index 986c3e6..0000000 --- a/docs/agent/model-chat.md +++ /dev/null @@ -1,31 +0,0 @@ -# 模型与聊天 - -首版聚焦可靠的 DeepSeek 聊天体验，模型扩展能力在真实需求出现后逐步提炼。 - -## DeepSeek Adapter - -- 期望实现阶段：P1 -- 实际开发状态：未开始 -- 已确认点：第一版只兼容 DeepSeek API；模型调用由 Runtime 管理。 -- 待确认点：默认模型、API 地址、请求参数、Key 的读取与配置方式。 - -## 流式聊天 - -- 期望实现阶段：P1 -- 实际开发状态：未开始 -- 已确认点：回答通过 Runtime 流式传递给客户端，并持久化至当前 Conversation。 -- 待确认点：断线处理、中途取消、重连以及部分回复的保存规则。 - -## 对话上下文 - -- 期望实现阶段：P1 -- 实际开发状态：未开始 -- 已确认点：聊天加载当前 Conversation 的历史；复杂记忆系统后置。 -- 待确认点：系统提示词、上下文窗口裁剪、历史过长时的摘要策略。 - -## 多模型支持 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：未来模型提供商属于 Adapter 层，不应写死在 Agent Behavior 中。 -- 待确认点：Provider 接口、模型路由、降级、成本与 Token 统计。 diff --git a/docs/agent/runs-behavior.md b/docs/agent/runs-behavior.md deleted file mode 100644 index cdaa11f..0000000 --- a/docs/agent/runs-behavior.md +++ /dev/null @@ -1,31 +0,0 @@ -# Run 与 Agent Behavior - -Run 为一次用户请求提供可观察的执行边界；Behavior 定义 Agent 如何完成这次执行。 - -## Run 生命周期 - -- 期望实现阶段：P1 -- 实际开发状态：未开始 -- 已确认点：一次用户消息默认产生一个 Run；纯聊天和 Tool 行动使用同一个 Run 概念。 -- 待确认点：首版状态、取消、失败、重试和后台运行语义。 - -## DefaultAgent Behavior - -- 期望实现阶段：P1 -- 实际开发状态：未开始 -- 已确认点：首版只有单 Agent；Behavior 负责准备上下文、调用模型、调用 Tool 和结束 Run。 -- 待确认点：Behavior 的 TypeScript 接口，以及系统提示词与上下文组装的位置。 - -## 执行日志 - -- 期望实现阶段：P1 -- 实际开发状态：未开始 -- 已确认点：记录输入、模型输出、Tool 调用、错误和时间；生成脚本文本记录在日志中，不额外保存脚本副本。 -- 待确认点：JSONL 记录粒度、大输出截断、日志与产物的边界。 - -## Run 控制 - -- 期望实现阶段：P2 -- 实际开发状态：未开始 -- 已确认点：客户端最终需要取消、查看和重新执行 Run。 -- 待确认点：取消信号传播、失败后续跑和重试时的上下文复用。 diff --git a/docs/agent/tools-workspace.md b/docs/agent/tools-workspace.md deleted file mode 100644 index 22f86d9..0000000 --- a/docs/agent/tools-workspace.md +++ /dev/null @@ -1,38 +0,0 @@ -# Tools 与 Workspace - -Tool 是 Agent 主动调用外部能力的统一边界；Workspace 是文件与 Shell 操作的默认作用域。 - -## Tool 契约与注册 - -- 期望实现阶段：P1 -- 实际开发状态：未开始 -- 已确认点：Tool 声明名称、描述、参数并返回结构化结果；实际执行由 Runtime 承载。 -- 待确认点：参数 Schema、错误结果、流式 Tool 输出与注册 API。 - -## Task Workspace - -- 期望实现阶段：P2 -- 实际开发状态：未开始 -- 已确认点：位于 `~/.agent/tasks//workspace/`；Shell 和文件 Tool 默认以其为作用域。 -- 待确认点：初始化内容、路径展示、临时文件和清理行为。 - -## 文件 Tool - -- 期望实现阶段：P2 -- 实际开发状态：未开始 -- 已确认点：首批支持读写文件、目录浏览和文本搜索。 -- 待确认点：补丁接口、编码处理、大文件限制与二进制文件策略。 - -## Shell Tool - -- 期望实现阶段：P2 -- 实际开发状态：未开始 -- 已确认点：记录命令、输出、退出码和错误；首期安全机制保持轻量。 -- 待确认点：超时、取消、后台进程、交互命令和输出上限。 - -## 单 Agent Tool Calling - -- 期望实现阶段：P2 -- 实际开发状态：未开始 -- 已确认点：Agent 自主选择 Tool、读取结果并继续调用模型，直至给出最终回复。 -- 待确认点：循环上限、失败反馈、并行调用和客户端事件协议。 diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..9d10cfe --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,125 @@ +# 架构总览 + +## 定位 + +`llm-to-agent` 是纯个人使用、本地优先的开发助手与电脑管家。它以一个常驻 Runtime 作为唯一运行宿主，并通过 CLI、Web、Desktop 三个客户端共享数据和执行状态。 + +系统采用四层结构： + +```text +Launcher / Supervisor + ↓ +Runtime Host + ↓ +Application Runtime + ↓ +Microkernel + Extensions +``` + +这四层表达职责和依赖方向，不要求第一版拆成四个独立进程。 + +## Launcher / Supervisor + +Supervisor 位于 Agent 运行版本之外，只负责启动、版本切换、健康检查和失败回退。它不理解 Space、Conversation、Tool 或 Agent 推理。 + +Supervisor 在 P3 的 System Evolution 发布闭环中实现，P1/P2 开发阶段可以先由普通启动脚本承担进程拉起。 + +## Runtime Host + +Runtime Host 是 Node.js 进程的组合入口，负责： + +- 创建并启动 Application Runtime 与 Microkernel； +- 装配当前启用的扩展； +- 开启本地客户端连接； +- 处理进程信号、单实例和退出； +- 将配置与基础设施交给内部模块。 + +Host 不包含 Project、Conversation、Agent 工作流等业务规则。 + +## Application Runtime + +Application Runtime 负责这个产品不可缺少的应用能力： + +- Project / Task Space； +- Conversation 与持久化 Run Record； +- 本地数据 Repository 和唯一写入； +- 客户端 Command、Query 与 Event Stream； +- 当前 Space/Conversation 上下文； +- Profile 选择和基础并发策略。 + +它不包含 DeepSeek 请求、Shell、Git、浏览器驱动、提示词或具体 Agent 协作策略。 + +## Microkernel + +Microkernel 负责一次 Agent 执行的通用机制： + +- 创建内存中的 Run Context； +- 调用 Agent Behavior； +- 注册并调用 Tool； +- 执行 Hook Pipeline； +- 发出流式输出和运行事件； +- 传播取消信号并隔离执行错误。 + +Microkernel 不认识 Project、Task 或具体存储，也不依赖任何具体扩展。 + +## Extensions + +扩展只放真正可替换、可按需增加的能力： + +- **Adapter**：DeepSeek、未来模型提供商、浏览器或检索驱动； +- **Tool**：文件、Shell、Git、浏览器、桌面控制； +- **Hook**：围绕 Tool/Run 生命周期观察、限制或响应； +- **Behavior**：DefaultAgent、CodingAgent、Planner、Reviewer。 + +Space、Conversation 和持久化 Run Record 是 Application Runtime 的产品领域，不作为可卸载插件。 + +## Profile + +Profile 是 Application Runtime 管理的声明式能力组合，不是独立运行层： + +```text +Profile +├── 默认 Behavior +├── 可用 Tools +├── 启用 Hooks +├── 模型设置 +└── 上下文/记忆策略 +``` + +Project 和 Task 是 Space 类型；System Evolution 是应用于 Project 的特殊 Profile。 + +## 依赖规则 + +```text +Supervisor → Runtime Host +Runtime Host → Application Runtime / Microkernel / Extensions +Application Runtime → Microkernel 公共接口 +Extensions → Microkernel 扩展接口 +Microkernel ✕ Application Runtime / 具体 Extensions +Clients → Runtime Interface +``` + +目录隔离只是表现，以上依赖方向才是边界是否真实成立的判断依据。 + +## 客户端接口 + +CLI、Web、Desktop 逻辑上只使用三类交互： + +- **Command**：创建 Space、发送消息、取消 Run 等状态变更； +- **Query**：读取 Space、Conversation、Run 和日志； +- **Event Stream**：接收模型增量、Tool 过程和 Run 状态。 + +具体采用 HTTP/SSE、Unix Socket 或其他本地协议在实现时确定，不提前冻结字段。 + +## Event 与 Hook + +- **Run Event** 是发生过的事实，用于日志和客户端实时展示。 +- **Hook** 是事件前后实际执行的扩展代码。 + +两者不能混为同一个事件总线：记录了一个事件，不代表必须触发可修改流程的 Hook。 + +## 演化原则 + +任何一层都允许由 Agent 修改，包括 Application Runtime 和 Microkernel。Agent 在 System Evolution Project 的隔离 worktree 中修改源码、运行测试并展示 Diff；Git 写操作由用户确认，Supervisor 负责切换构建版本和失败回退。 + +自进化依赖的是源码可修改、候选版本隔离、测试、发布和回退，不要求把所有产品能力插件化。 diff --git a/docs/architecture/local-data.md b/docs/architecture/local-data.md deleted file mode 100644 index 610a7b3..0000000 --- a/docs/architecture/local-data.md +++ /dev/null @@ -1,35 +0,0 @@ -# 本地数据与目录 - -## 原则 - -数据以本地普通文件保存，保持易读、易调试、易由 Agent 修改。早期不承诺兼容性，不预先建设 schema migration；重要数据依靠备份，格式变更需要时再写一次性转换脚本。 - -Runtime 是唯一写入者，CLI/Web/Desktop 均通过 Runtime 读取或修改数据。 - -## 目录 - -```text -~/.agent/ - tasks// - space.json - conversations/ - runs/ - workspace/ - -/.agent/ - project.json - conversations/ - runs/ -``` - -Conversation 与 Run 优先采用 JSONL；Space/Project 元信息采用小型 JSON 文件。生成并执行的脚本文本进入 Run 日志，不额外维护脚本库；真正写进 Workspace 的文件自然保留。 - -## Task 升级 - -Task Workspace 的组织尽量与 Project 工作区一致。升级为 Project 时，将该专属目录迁移至用户指定路径并写入 Project 元信息。 - -## 待细化 - -- ID 和文件命名规则。 -- Run 日志与产物的具体划分。 -- 备份、归档和数据清理策略。 diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md deleted file mode 100644 index b2a7f6c..0000000 --- a/docs/architecture/overview.md +++ /dev/null @@ -1,33 +0,0 @@ -# 架构总览 - -## 定位 - -这是纯个人使用的开发助手与电脑管家。它支持 Project 和 Task 两种并列 Space，并通过 CLI、Web、Desktop 三个客户端访问同一个本地 Runtime。 - -## 分层 - -```text -Launcher / Supervisor - ↓ -本地 Runtime（微内核） - ↓ -Adapter / Tool / Hook / Behavior Package - ↓ -Project / Task / System Evolution Profile - ↓ -CLI / Web / Desktop -``` - -微内核只负责运行规则：本地状态、Run 生命周期、Tool 调用边界、Hook 调度和扩展接缝。它不预先承载具体模型、浏览器、Git、记忆或 Agent 协作策略。 - -## 扩展边界 - -- **Adapter**：可替换的底层实现，例如模型供应商、检索或浏览器驱动。 -- **Tool**：Agent 主动调用的外部能力，例如文件、Shell、Git、浏览器。 -- **Hook**：围绕生命周期做观察、限制或后续动作。 -- **Behavior Package**：Agent 的思考、协作和完成方式。 -- **Profile**：为 Project、Task、System Evolution 组合默认行为与能力。 - -## 演化原则 - -内核可以被修改。Agent 对自身的改动必须发生在隔离 worktree 中，经过测试和 Git 确认后再由 Supervisor 切换版本；失败时能够回退。 diff --git a/docs/automation/computer-butler.md b/docs/automation/computer-butler.md deleted file mode 100644 index 317ffc9..0000000 --- a/docs/automation/computer-butler.md +++ /dev/null @@ -1,45 +0,0 @@ -# 电脑管家与自动化 - -电脑管家能力让 Task 能处理浏览器、本机应用和日常临时事务。 - -## 本机基础能力 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：候选能力包括剪贴板、通知、文件整理和进程信息，并通过 Tool 逐项加入。 -- 待确认点：优先能力、跨平台范围和系统 API 选择。 - -## 浏览器读取与交互 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：需要覆盖网页搜索、读取、结构化提取和交互操作。 -- 待确认点：浏览器驱动、登录态复用、下载、标签页管理和真实提交确认。 - -## 应用与窗口控制 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：逐步加入应用启动、窗口管理和文件定位等能力。 -- 待确认点：操作系统优先级、原生桥接方式和无障碍权限。 - -## 桌面自动化 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：候选能力包括截图、屏幕理解、键盘和鼠标操作。 -- 待确认点：视觉驱动方式、坐标可靠性、停止机制和操作确认。 - -## 定时与后台任务 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：未来支持提醒、定时执行与长期后台任务。 -- 待确认点：调度器归属、Runtime 重启恢复、错过任务和结果通知。 - -## 自动化模板 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：重复工作可沉淀为 Behavior 或工作流模板，但不提前固定格式。 -- 待确认点：模板创建、参数化、分享、修改和版本管理。 diff --git a/docs/clients/desktop.md b/docs/clients/desktop.md deleted file mode 100644 index 6e555c6..0000000 --- a/docs/clients/desktop.md +++ /dev/null @@ -1,31 +0,0 @@ -# Desktop - -Desktop 是本地常驻控制台与系统集成层，复用 Web 界面与同一个 Runtime。 - -## Desktop Host - -- 期望实现阶段：P6 -- 实际开发状态：未开始 -- 已确认点：负责拉起、连接和观察本地 Runtime；Desktop 框架在进入本阶段前单独讨论。 -- 待确认点：框架、打包、更新、Web 前端复用和跨平台目标。 - -## 常驻体验 - -- 期望实现阶段：P6 -- 实际开发状态：未开始 -- 已确认点：支持托盘、通知、全局快捷键和后台状态提示。 -- 待确认点：开机启动、任务完成通知、快捷入口和菜单设计。 - -## 原生确认与版本控制 - -- 期望实现阶段：P6 -- 实际开发状态：未开始 -- 已确认点：提供高影响操作确认、版本切换、Runtime 重启、回退与健康状态面板。 -- 待确认点：确认弹窗队列、Supervisor 连接和故障恢复体验。 - -## 原生能力桥接 - -- 期望实现阶段：P6 -- 实际开发状态：未开始 -- 已确认点：可逐步承载剪贴板、窗口、文件系统和其他原生能力桥接。 -- 待确认点：与 Runtime Tool 的边界、权限申请、平台差异和无界面运行方式。 diff --git a/docs/clients/web.md b/docs/clients/web.md deleted file mode 100644 index ef3c832..0000000 --- a/docs/clients/web.md +++ /dev/null @@ -1,38 +0,0 @@ -# Web - -Web 是 Runtime 的第二个客户端，不复制 Agent、存储或 Tool 逻辑。 - -## Web 连接层 - -- 期望实现阶段：P5 -- 实际开发状态：未开始 -- 已确认点：复用同一个本地 Runtime，并支持请求、流式事件和状态查询。 -- 待确认点：HTTP/SSE/WebSocket、远程访问方式和断线恢复。 - -## 会话工作台 - -- 期望实现阶段：P5 -- 实际开发状态：未开始 -- 已确认点：覆盖 Space、Conversation、流式聊天与历史浏览。 -- 待确认点：前端框架、状态管理、路由与移动端适配。 - -## 执行观察台 - -- 期望实现阶段：P5 -- 实际开发状态：未开始 -- 已确认点：查看 Run、Tool、Plan、Agent、日志和产物，并提供必要的取消/恢复操作。 -- 待确认点：实时视图、长日志渲染、后台任务和多 Run 并行展示。 - -## 项目与进化工作台 - -- 期望实现阶段：P5 -- 实际开发状态：未开始 -- 已确认点：后续展示项目规则、记忆、测试结果、Git Diff 和 System Evolution 过程。 -- 待确认点：文件编辑、Diff Review、发布确认和版本回退体验。 - -## Web 管理能力 - -- 期望实现阶段：P5 -- 实际开发状态：未开始 -- 已确认点：后续管理配置、扩展、记忆和高影响操作确认。 -- 待确认点：功能范围、本地/远程访问边界与是否需要轻量认证。 diff --git a/docs/development/project-assistant.md b/docs/development/project-assistant.md deleted file mode 100644 index 4082e90..0000000 --- a/docs/development/project-assistant.md +++ /dev/null @@ -1,38 +0,0 @@ -# Project 开发助手 - -Project 模式让 Agent 在绑定的源码目录中完成长期开发工作。 - -## Project 初始化与绑定 - -- 期望实现阶段：P2 -- 实际开发状态：未开始 -- 已确认点：Project 绑定本地源码目录，并在项目根目录使用 `.agent/` 保存会话、Run 和项目上下文。 -- 待确认点：初始化命令、已有 `.agent/` 的处理、路径移动与解绑。 - -## 代码工程 Toolset - -- 期望实现阶段：P2 -- 实际开发状态：未开始 -- 已确认点：包括代码搜索、修改/补丁、测试执行和测试结果收集；复用通用 Tool Runtime。 -- 待确认点：测试命令发现、语言适配、代码索引和大仓库性能。 - -## 单 Agent 开发工作流 - -- 期望实现阶段：P2 -- 实际开发状态：未开始 -- 已确认点：先跑通“理解源码 → 修改 → 测试 → 汇报”；第一版不强制 Planner/Worker/Reviewer。 -- 待确认点：项目上下文装配、修改前计划、完成判定与失败反馈。 - -## Git 与 Worktree - -- 期望实现阶段：P2 -- 实际开发状态：未开始 -- 已确认点：支持 status、diff、log 和 worktree；候选修改默认发生在隔离 worktree。 -- 待确认点：worktree 路径、分支命名、清理策略与普通 Project 的 Git 写操作确认。 - -## 项目知识沉淀 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：项目规则、架构摘要和决策记录以普通文件起步，不预先引入 RAG。 -- 待确认点：文件名称、自动更新时机、是否进入 Git 和人工编辑体验。 diff --git a/docs/development/system-evolution.md b/docs/development/system-evolution.md deleted file mode 100644 index 16bd32c..0000000 --- a/docs/development/system-evolution.md +++ /dev/null @@ -1,45 +0,0 @@ -# System Evolution - -System Evolution 让 Agent 像维护普通开发项目一样维护自身。进化目标由用户提出，不要求 Agent 主动发现问题。 - -## System Evolution Profile - -- 期望实现阶段：P3 -- 实际开发状态：未开始 -- 已确认点：它是绑定 Agent 自身源码仓库的特殊 Project Profile，不是独立系统。 -- 待确认点：初始化方式、默认项目规则、允许使用的 Tool 与上下文装配。 - -## 候选版本工作区 - -- 期望实现阶段：P3 -- 实际开发状态：未开始 -- 已确认点：Agent 在隔离 Git worktree 中分析、修改和测试自身，不直接篡改当前运行副本。 -- 待确认点：worktree 生命周期、并行候选版本和磁盘清理。 - -## 变更与测试报告 - -- 期望实现阶段：P3 -- 实际开发状态：未开始 -- 已确认点：发布前向用户展示 Diff、测试结果和变更说明。 -- 待确认点：最低测试门槛、健康检查、失败结果的保留与重新修改。 - -## Git 发布确认 - -- 期望实现阶段：P3 -- 实际开发状态：未开始 -- 已确认点：commit、merge、push 等 Git 写操作必须经用户确认。 -- 待确认点：确认粒度、CLI/TUI 交互、拒绝后的候选版本处理。 - -## Supervisor 与回退 - -- 期望实现阶段：P3 -- 实际开发状态：未开始 -- 已确认点：Supervisor 位于内核外，负责版本切换、启动、健康检查和失败回退。 -- 待确认点：部署布局、进程交接、版本指针和自动回退判定。 - -## 进化历史与评估 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：初期 Git 历史和 Run 日志即为进化记录；后续可关联需求、Diff、测试、发布和回退。 -- 待确认点：是否需要独立 Evolution Record、基准任务以及新旧版本比较方式。 diff --git a/docs/directory-plan.md b/docs/directory-plan.md new file mode 100644 index 0000000..1c5ac0d --- /dev/null +++ b/docs/directory-plan.md @@ -0,0 +1,116 @@ +# 规划目录 + +本文描述当前架构下建议采用的源码与运行数据目录。它用于指导项目起步，不是不可修改的目录规范。 + +后续实现或 System Evolution 过程中，如果真实依赖、代码规模或开发体验证明某个划分不合理，可以移动、合并或拆分目录；调整时应优先保持职责和依赖方向，而不是机械维持路径兼容。 + +## 源码仓库 + +```text +llm-to-agent/ +├── apps/ +│ ├── runtime/ # Runtime Host / composition root +│ ├── supervisor/ # 启动、版本切换、健康检查、回退 +│ ├── cli/ # REPL、非交互 CLI、TUI +│ ├── web/ # Web 客户端 +│ └── desktop/ # Desktop Host 与原生桥接 +│ +├── packages/ +│ ├── kernel/ # Microkernel +│ ├── application/ # Application Runtime +│ └── client/ # 客户端共享的 Runtime Client +│ +├── extensions/ # 第一方扩展，按完整能力纵向划分 +│ ├── deepseek/ +│ ├── workspace/ +│ ├── shell/ +│ ├── git/ +│ └── .../ +│ +├── docs/ +│ ├── architecture.md +│ ├── directory-plan.md +│ ├── roadmap.md +│ └── features/ +│ +├── tests/ +│ └── e2e/ # 跨包、自举和版本切换测试 +│ +├── tooling/ # 构建、发布、开发辅助 +│ +├── package.json +├── tsconfig.json +└── workspace.yaml +``` + +## 架构对应关系 + +| 架构职责 | 规划目录 | +| --- | --- | +| Launcher / Supervisor | `apps/supervisor/` | +| Runtime Host | `apps/runtime/` | +| Application Runtime | `packages/application/` | +| Microkernel | `packages/kernel/` | +| Extensions | `extensions/` | +| Runtime Client | `packages/client/` | +| CLI / Web / Desktop | `apps/cli/`、`apps/web/`、`apps/desktop/` | + +## 目录原则 + +### Apps 是进程和产品入口 + +`apps/runtime/` 负责创建组件、安装扩展并开启本地连接，不承载 Space、Conversation、Tool 或 Agent Behavior 的具体实现。 + +CLI、Web、Desktop 通过同一个 Runtime Client 工作，不各自复制 Agent、存储和执行逻辑。 + +### Packages 固定核心依赖边界 + +- `kernel/` 只包含 Run Context、Behavior 调度、Tool Gateway、Hook Pipeline、Run Event、流式输出、取消和错误边界。 +- `application/` 承载 Project/Task、Conversation、Message、Run Record、Repository、Profile 以及 Command/Query 等产品领域。 +- `client/` 承载三个客户端共用的 Command、Query、Event Stream 和连接逻辑。 + +不建立泛化的 `shared/` 或 `types/` 大杂烩。类型应尽量由拥有该概念的模块导出，只有真正跨客户端传输的协议进入 `client/`。 + +### Extensions 按完整能力纵向划分 + +扩展不按 Adapter、Tool、Hook、Behavior 等技术类型横向拆目录，而是按能力组织。例如 `browser/` 可以同时包含浏览器 Adapter、相关 Tools、操作 Hook 和 Browser Behavior。 + +第一版不要求每个扩展都是独立 package。只有在依赖、测试、复用、版本或独立发布需求出现后，才将它提升为单独 workspace package。 + +### 功能文档不映射源码目录 + +`docs/features/` 按产品大功能组织，源码按职责和依赖组织，两者不要求一一对应。 + +例如 System Evolution 会同时涉及 Application Runtime、Git 扩展、Runtime Host、Supervisor 和 CLI，不应为了与功能文档对齐而把所有代码放入单个目录。 + +### 测试就近放置 + +单元测试和模块测试与所属源码放在一起。顶层 `tests/e2e/` 只保存真正跨包、跨进程或跨版本的场景，例如 CLI 到 Runtime、Project 开发、自举发布和版本回退。 + +## 运行数据目录 + +运行数据不进入源码仓库： + +```text +~/.agent/ +├── tasks/ +├── registry.json +├── extensions/ # 用户本地安装的扩展 +├── releases/ # Installed Releases +├── runtime/ +└── config/ +``` + +Project 专属 Agent 数据位于项目根目录的 `.agent/`。候选 worktree 和 Installed Release 由 `~/.agent/` 下的运行数据管理，不作为源码仓库中的固定目录。 + +## 允许调整的判断标准 + +满足以下任一情况时，可以调整目录： + +- 一个目录长期承载了多个不相关职责； +- 一项完整能力被迫跨越过多技术分类目录； +- 模块需要独立测试、复用、加载、版本或发布； +- 现有依赖方向导致循环依赖或核心反向依赖具体功能； +- System Evolution 的真实开发过程证明当前结构降低了可理解性或修改效率。 + +目录调整后应同步更新本文，但不需要为保持旧规划而保留无价值的兼容层。 diff --git a/docs/extension/hooks-extensions.md b/docs/extension/hooks-extensions.md deleted file mode 100644 index 5eb6caf..0000000 --- a/docs/extension/hooks-extensions.md +++ /dev/null @@ -1,38 +0,0 @@ -# Hooks、扩展与 Profile - -扩展体系让新能力以 Tool、Hook、Behavior、Adapter 或 Profile 的形式生长，而不是全部进入微内核。 - -## 基础 Hook 接缝 - -- 期望实现阶段：P1 -- 实际开发状态：未开始 -- 已确认点：第一版只保留 `beforeTool`、`afterTool`、`afterRun` 三个轻量 Hook 点，并允许内置代码注册。 -- 待确认点：回调签名、错误传播、是否允许修改输入输出。 - -## Hook Runtime - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：Hook 用于观察、约束或响应生命周期，不承担存储一致性、Run 状态或 Tool 实际执行。 -- 待确认点：优先级、异常隔离、启停、同步/异步行为和更多稳定事件。 - -## 扩展加载 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：当独立扩展需求出现后，再支持 Tool、Hook、Behavior、Adapter 的本地发现与加载。 -- 待确认点：目录布局、manifest、版本依赖、热加载和调试方式。 - -## Profile 组合 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：Project、Task、System Evolution 的差异最终由默认 Tool、Hook、Behavior 和策略组合表达。 -- 待确认点：配置格式、继承覆盖、项目级自定义和运行时切换。 - -## 扩展开发体验 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：扩展应可单独测试、启停和定位运行问题。 -- 待确认点：模板生成、调试 CLI/TUI、扩展回滚和是否需要独立分发机制。 diff --git a/docs/features/automation.md b/docs/features/automation.md new file mode 100644 index 0000000..72f3bee --- /dev/null +++ b/docs/features/automation.md @@ -0,0 +1,49 @@ +# 自动化与后台任务 + +## 持久后台任务 + +**实现阶段：P7** + +- 将 Run 提交为客户端断开后仍能执行的持久任务。 +- 保存执行状态、下一步动作、关联 Space 和人工介入点。 +- Runtime 重启后识别未完成任务并按策略恢复或等待用户处理。 + +## 提醒与定时执行 + +**实现阶段：P7** + +- 创建一次性提醒和指定时间执行的 Agent 任务。 +- 正确处理时区、设备休眠、Runtime 未运行和错过执行时间。 +- 将执行结果通过 CLI、Web、Desktop 或系统通知反馈。 + +## 周期任务 + +**实现阶段：P7** + +- 支持每日、每周及可表达的周期规则。 +- 管理启停、下次执行、失败重试和避免重复运行。 +- 每次执行生成独立 Run，并保留周期任务的整体历史。 + +## 事件触发自动化 + +**实现阶段：P7** + +- 根据文件变化、下载完成、应用状态或其他本地事件触发 Run。 +- 对频繁事件去抖、合并并限制并发。 +- 显示触发来源，允许用户临时暂停或禁用自动化。 + +## 自动化模板与参数 + +**实现阶段：P7** + +- 将成功的脚本、Tool 组合或工作流保存为可复用自动化。 +- 定义输入参数、默认值、执行条件和所需能力。 +- 修改模板不会篡改既有执行记录，能够查看版本差异。 + +## 自动化执行历史与通知 + +**实现阶段：P7** + +- 汇总每个自动化的成功、失败、耗时、产物和人工介入记录。 +- 对连续失败或异常结果发送通知并暂停后续执行。 +- 从历史 Run 快速重试或进入对应 Conversation 排查。 diff --git a/docs/features/browser.md b/docs/features/browser.md new file mode 100644 index 0000000..19d3a2a --- /dev/null +++ b/docs/features/browser.md @@ -0,0 +1,49 @@ +# 浏览器 + +## 搜索、导航与页面读取 + +**实现阶段：P7** + +- 搜索互联网、打开 URL、读取页面文本和获取页面基本结构。 +- 管理重定向、加载失败、分页和动态页面等待。 +- 将页面内容转为适合模型使用且保留来源的结构化结果。 + +## 页面提取与站内探索 + +**实现阶段：P7** + +- 提取列表、表格、链接、表单和指定区域内容。 +- 在站内跟随链接完成多页资料收集，并避免无界爬取。 +- 保存必要截图、页面快照或下载内容作为 Run 产物。 + +## DOM 交互与表单操作 + +**实现阶段：P7** + +- 点击、输入、选择、滚动、等待和提交表单。 +- 通过可访问性树、DOM 和稳定定位信息减少脆弱坐标操作。 +- 提交、购买、发布等真实外部写操作进入确认流程。 + +## 标签页、会话与登录态 + +**实现阶段：P7** + +- 管理浏览器实例、窗口、标签页、历史和页面间上下文。 +- 按 Profile 或任务复用已有登录态，同时保持不同任务之间的边界。 +- 处理登录过期、验证码和必须由用户接管的页面。 + +## 上传、下载与文件流转 + +**实现阶段：P7** + +- 将 Workspace 文件上传到网页，并将下载内容保存为可追踪 Artifact。 +- 观察下载状态、文件名、重复文件和失败重试。 +- 将浏览器文件与 Task/Project Workspace 建立明确关联。 + +## 页面视觉理解与混合定位 + +**实现阶段：P7** + +- 使用截图和视觉模型理解仅靠 DOM 难以操作的界面。 +- 组合 DOM、可访问性树、图像和坐标完成定位。 +- 视觉操作记录截图和动作序列，便于用户检查和失败恢复。 diff --git a/docs/features/cli.md b/docs/features/cli.md new file mode 100644 index 0000000..261444c --- /dev/null +++ b/docs/features/cli.md @@ -0,0 +1,65 @@ +# CLI + +## Runtime 管理与首次配置 + +**实现阶段：P1** + +- 提供 Runtime 启动、连接、状态查询和停止命令。 +- Runtime 未启动时自动拉起，CLI 退出后 Runtime 保持运行。 +- 完成 DeepSeek Key、数据目录和首个 Task 的最小首次配置。 + +## 自然语言 REPL + +**实现阶段：P1** + +- 在当前 Conversation 中进行流式聊天。 +- 支持输入历史、多行输入、取消当前请求和清晰的当前上下文提示符。 +- 终端重开后恢复最近 Space、Conversation 和消息历史。 + +## Space 与 Conversation 控制 + +**实现阶段：P1** + +- 通过一组一致的斜杠命令创建、列出、切换、重命名和归档 Task/Conversation。 +- 为 Project 绑定和切换复用相同的导航体验。 +- 提供帮助、命令错误提示和最近使用列表。 + +## Run、Tool 与产物呈现 + +**实现阶段：P2** + +- 实时展示模型回复、Tool 调用、Shell 输出、测试结果、错误和最终状态。 +- 长输出默认摘要，并能查看完整 Run 日志和 Artifact。 +- 提供 Run 取消、重新执行以及 Project Diff 查看入口。 + +## System Evolution 终端流程 + +**实现阶段：P3** + +- 在 CLI 中查看候选版本、Diff、测试结果、发布说明和健康检查。 +- 完成 Git 写操作确认、版本切换和回退操作。 +- 确保拒绝发布或发布失败后仍能继续处理候选工作区。 + +## 非交互与管道模式 + +**实现阶段：P4** + +- 支持一次性命令、stdin 输入、stdout 结果、结构化 JSON 输出和可靠退出码。 +- 允许 Shell 脚本或其他程序创建 Run、等待结果或后台提交。 +- 交互模式和非交互模式使用同一 Runtime 接口。 + +## 全屏 TUI + +**实现阶段：P4** + +- 提供 Space/Conversation 导航、聊天、Run 时间线、日志、产物和 Diff 工作区。 +- 加入命令面板、搜索、补全、快捷键、主题和可调整布局。 +- 支持配置、扩展、System Evolution 和后台 Run 管理，不替代快速 REPL。 + +## 多 Agent 与记忆工作台 + +**实现阶段：P6** + +- 展示 Plan、Step、Child Run、Agent 分工、人工检查点和结果验证。 +- 管理 Conversation/Space/全局记忆，查看来源并进行编辑或遗忘。 +- 将 P5/P6 的复杂能力整合到一致的终端交互中。 diff --git a/docs/features/data-config.md b/docs/features/data-config.md new file mode 100644 index 0000000..04e084c --- /dev/null +++ b/docs/features/data-config.md @@ -0,0 +1,57 @@ +# 本地数据与配置 + +## 全局数据根目录与 Space 注册表 + +**实现阶段：P1** + +- 建立 `~/.agent/` 全局目录、Runtime 数据和 Space 注册表。 +- 注册表保存 Space 的 ID、类型、名称、真实路径和最近访问，用于定位 Task 与分散的 Project。 +- 处理首次启动、目录缺失、重复注册和路径不可访问等情况。 + +## Space、Conversation 与 Run 文件仓库 + +**实现阶段：P1** + +- 使用普通 JSON 保存当前元信息，使用 JSONL 保存消息与追加式 Run 记录。 +- 支持创建、读取、更新和列出 Space、Conversation、Message、Run。 +- 采用临时文件替换等简单方式保证单次写入完整，异常文件能够被识别并报告。 + +## 统一工作区目录 + +**实现阶段：P1** + +- Task 根目录本身就是 Workspace，内部使用 `.agent/` 保存 Agent 数据。 +- Project 使用相同目录形状，使 Task 可以整体移动并升级为 Project。 +- 明确工作文件、Agent 元数据和全局注册信息各自的所有权。 + +## Run 日志与产物仓库 + +**实现阶段：P2** + +- 保存模型调用、Tool 调用、Shell 输出、错误、测试结果和 Diff 等执行记录。 +- 将日志中的一次性内容与需要长期保留、预览或下载的 Artifact 分开管理。 +- 支持通过 Conversation、Run 和 Tool 调用定位相关记录与文件。 + +## 配置体系与覆盖规则 + +**实现阶段：P4** + +- 管理全局、Space、Profile 和客户端配置，并定义清晰的覆盖顺序。 +- 区分普通配置、凭据引用和运行时临时选项。 +- 支持查看配置最终值、来源、修改和恢复默认值。 + +## 缓存、索引与临时数据 + +**实现阶段：P6** + +- 为代码索引、知识检索、网页内容和模型缓存提供统一存放位置。 +- 缓存可重建且不与原始数据混淆，支持容量统计和按类型清理。 +- 保持 Project 数据、全局数据和临时数据之间的边界。 + +## 数据导入、导出与修复 + +**实现阶段：P8** + +- 支持全局或按 Space 导出、导入、备份和恢复。 +- 提供目录迁移、格式升级、完整性检查和损坏数据修复工具。 +- 备份过程可验证，恢复前保留现有数据的回退副本。 diff --git a/docs/features/desktop-control.md b/docs/features/desktop-control.md new file mode 100644 index 0000000..2fb9fe0 --- /dev/null +++ b/docs/features/desktop-control.md @@ -0,0 +1,51 @@ +# 本机与桌面控制 + +本功能描述 Agent 面向电脑的 Tool；它不同于 P10 的 Desktop 客户端。 + +## 剪贴板、通知与系统信息 + +**实现阶段：P7** + +- 读取和写入剪贴板文本或文件引用。 +- 发送本地通知并关联触发它的 Run。 +- 查询时间、网络、磁盘、进程和基础系统状态。 + +## 本地文件整理 + +**实现阶段：P7** + +- 对用户指定目录执行分类、移动、重命名、去重和下载目录整理。 +- 先生成变更预览，再执行可能影响大量文件的操作。 +- 删除优先进入系统回收站，并记录可恢复位置。 + +## 应用生命周期与状态 + +**实现阶段：P7** + +- 启动、聚焦、退出应用并查询运行状态。 +- 打开指定文件、URL 或项目位置到对应应用。 +- 处理应用未安装、无响应和需要用户登录等情况。 + +## 窗口与文件定位 + +**实现阶段：P7** + +- 查询、切换、移动、调整大小和排列窗口。 +- 将 Workspace、终端、编辑器和浏览器定位到相关资源。 +- 在多屏幕和多个同名窗口环境中保持明确目标。 + +## 屏幕理解与键鼠操作 + +**实现阶段：P7** + +- 截取屏幕或窗口，使用视觉能力识别界面状态。 +- 执行键盘、鼠标、拖放和快捷键操作。 +- 提供紧急停止、动作记录和操作前后截图。 + +## 系统权限与能力降级 + +**实现阶段：P7** + +- 检测辅助功能、录屏、通知和自动化权限。 +- 指引用户完成必要授权，并在权限缺失时切换到可用能力。 +- 向 Agent 暴露真实平台能力，避免反复调用不可用 Tool。 diff --git a/docs/features/desktop.md b/docs/features/desktop.md new file mode 100644 index 0000000..e5e71cb --- /dev/null +++ b/docs/features/desktop.md @@ -0,0 +1,57 @@ +# Desktop + +## Desktop Host 与共享界面 + +**实现阶段：P10** + +- 选择 Desktop 框架，复用 Web 的主要界面、状态和 Runtime Client。 +- 管理应用窗口、深色模式、链接打开和本地导航。 +- Desktop 不包含第三套 Agent、存储或 Tool 执行逻辑。 + +## Runtime 生命周期管理 + +**实现阶段：P10** + +- 安装、启动、停止、重启并观察本地 Runtime。 +- 处理 Runtime 未安装、启动失败、版本不匹配和客户端重连。 +- 提供健康状态、日志入口和故障恢复操作。 + +## 托盘、快捷键与通知 + +**实现阶段：P10** + +- 支持系统托盘、开机启动、后台常驻和快速状态查看。 +- 使用全局快捷键快速唤起输入、当前任务或运行面板。 +- 将 Run 完成、失败、确认和自动化结果发送为原生通知。 + +## 原生确认与任务总览 + +**实现阶段：P10** + +- 在应用不位于前台时显示原生确认窗口。 +- 汇总后台 Run、定时任务、自动化、资源使用和待处理人工介入。 +- 从通知或托盘直接跳转到对应 Space、Conversation 或 Run。 + +## 快速输入与语音交互 + +**实现阶段：P10** + +- 通过全局快捷入口快速输入文本、粘贴剪贴板内容或发起语音请求。 +- 将语音转写、附件和当前前台应用上下文交给同一个 Conversation/Run 流程。 +- 支持录音状态、取消、转写确认和输出朗读，不建立独立语音会话系统。 + +## 系统能力桥接 + +**实现阶段：P10** + +- 为剪贴板、窗口、文件选择器、浏览器和系统权限提供原生 Adapter。 +- Agent 使用的 Tool 仍归本机与桌面控制功能，Desktop 只提供平台桥接。 +- 处理权限申请、平台差异和应用关闭后的能力可用性。 + +## 版本、安装与更新 + +**实现阶段：P10** + +- 打包 Desktop、Runtime 和必要资源，提供个人设备安装流程。 +- 展示 Installed Release、更新、重启、版本切换和回退状态。 +- 更新失败时保留可启动的旧版本，并与 Supervisor 的版本管理保持一致。 diff --git a/docs/features/extensions.md b/docs/features/extensions.md new file mode 100644 index 0000000..ee5c4e7 --- /dev/null +++ b/docs/features/extensions.md @@ -0,0 +1,65 @@ +# 扩展、Hooks 与 Profile + +## 静态扩展装配 + +**实现阶段：P1** + +- Runtime Host 通过明确的 composition root 装配首批 Adapter 和 Behavior。 +- P2 在同一机制中加入 Tool 与基础 Hook，不使用动态扫描或 manifest。 +- 扩展只能通过 Microkernel 公共接口注册，不能反向依赖 Host 内部实现。 + +## 基础 Hook Pipeline + +**实现阶段：P2** + +- 围绕 Tool 调用和 Run 完成提供少量稳定 Hook 点。 +- Hook 与 Run Event 分离：Hook 执行附加逻辑，Event 记录已经发生的事实。 +- Hook 失败不会悄然破坏主流程，执行结果进入 Run 日志。 + +## Hook 管理与诊断 + +**实现阶段：P4** + +- 支持 Hook 顺序、启停、异常隔离、耗时和调用链查看。 +- 明确哪些 Hook 只观察、哪些可以拒绝或结构化修改调用。 +- 为日志、摘要、确认、通知和评估提供稳定接缝。 + +## 本地扩展加载 + +**实现阶段：P4** + +- 加载本地 Tool、Adapter、Hook 和 Behavior，并校验声明与依赖。 +- 支持安装、启用、禁用、重新加载和错误回退。 +- 内置模块与外部扩展使用相同的运行接缝，但 Application Runtime 领域不插件化。 + +## Profile 组合 + +**实现阶段：P4** + +- 声明每种 Space 默认使用的 Behavior、Tools、Hooks、模型和上下文策略。 +- 支持全局默认、Project/Task/System Evolution Profile 和 Space 级覆盖。 +- 运行前得到确定的能力集合，并能向用户解释最终配置来源。 + +## 扩展开发与版本管理 + +**实现阶段：P4** + +- 提供扩展模板、测试工具、调试输出和兼容性检查。 +- 将扩展变更纳入 System Evolution 的候选、测试和回退流程。 +- 当内部模块真实长大后，支持从目录提升为独立 package，而不要求一开始拆包。 + +## Behavior 与 Skill 能力包 + +**实现阶段：P5** + +- 将可复用的 Agent 角色、提示词、上下文策略和工作方法封装成能力包。 +- 支持 Behavior 组合、参数化和按 Profile 选择。 +- Skill 复用现有 Tool 和 Run 机制，不建立绕过 Microkernel 的第二套执行系统。 + +## 扩展分发 + +**实现阶段：P8** + +- 支持本地扩展打包、来源记录、版本锁定、更新和卸载。 +- 对不兼容或启动失败的扩展提供隔离和回退。 +- 分发机制服务个人设备与自举，不以建设公共插件市场为前提。 diff --git a/docs/features/memory-knowledge.md b/docs/features/memory-knowledge.md new file mode 100644 index 0000000..6c24504 --- /dev/null +++ b/docs/features/memory-knowledge.md @@ -0,0 +1,57 @@ +# 记忆、检索与知识 + +## Conversation 摘要与上下文记忆 + +**实现阶段：P6** + +- 从长会话中提炼目标、决策、约束、未完成事项和重要结果。 +- 摘要可查看并能追溯原始消息，更新时不覆盖用户显式纠正。 +- Context Builder 按当前需求选择摘要与必要原文。 + +## Task 与 Project 记忆 + +**实现阶段：P6** + +- 跨 Conversation 保存 Space 级事实、规则、架构、决策和经验。 +- Project 记忆与项目目录绑定，Task 记忆随 Task 升级迁移。 +- 新会话可以检索相关历史，而不是加载该 Space 的全部内容。 + +## 全局个人记忆 + +**实现阶段：P6** + +- 保存跨 Space 有效的个人偏好、习惯和长期事实。 +- 区分用户明确声明与 Agent 从历史中提炼的内容。 +- 三个客户端共享同一记忆服务和修改结果。 + +## 记忆管理与来源 + +**实现阶段：P6** + +- 支持查看、编辑、固定、合并、纠错、遗忘和恢复记忆。 +- 每条记忆保留来源、作用域、更新时间和相关 Conversation/Run。 +- 处理互相冲突、已过期和不再可信的信息。 + +## 全文、向量与混合检索 + +**实现阶段：P6** + +- 对消息、Run、项目文档和知识资料建立全文索引。 +- 在需要语义检索时增加向量索引，并通过混合排序提高准确性。 +- 返回可解释的来源片段，避免只给出不可核查的记忆结论。 + +## 文档导入与个人知识库 + +**实现阶段：P6** + +- 导入常见文本、代码、Markdown、PDF 和网页资料。 +- 管理解析、切分、索引、更新、删除和重复内容。 +- 回答时引用原始来源，并区分个人记忆与外部资料。 + +## 记忆提炼与维护 Hooks + +**实现阶段：P6** + +- 在 Conversation、Run 或 Project 事件后提出摘要与记忆更新。 +- 定期检测重复、冲突、过期和缺少来源的记忆。 +- 自动维护不得阻塞正常 Run，用户可以查看和撤销变更。 diff --git a/docs/features/model-agent.md b/docs/features/model-agent.md new file mode 100644 index 0000000..d6842c8 --- /dev/null +++ b/docs/features/model-agent.md @@ -0,0 +1,57 @@ +# 模型、聊天与 Agent + +## DeepSeek Adapter 与流式聊天 + +**实现阶段：P1** + +- 通过 Model Port 接入 DeepSeek API，支持流式文本生成和基础请求配置。 +- 将模型增量传递给客户端，并在完成后保存用户可见消息。 +- 处理网络失败、API 错误、中途取消和未完成回复。 + +## DefaultAgent 文本执行 + +**实现阶段：P1** + +- 实现单一 DefaultAgent Behavior，完成输入、上下文组装、模型调用和最终回答。 +- Behavior 运行在 Microkernel 中，通过端口使用模型，不直接写入 Repository。 +- 保持纯聊天 Run 与后续行动 Run 使用一致的执行入口。 + +## 系统提示词与上下文组装 + +**实现阶段：P1** + +- 组合系统提示词、当前 Space、Conversation 历史和用户输入。 +- 定义消息角色、顺序和客户端可见内容与模型内部消息的边界。 +- 为 Project 规则、记忆、附件和子 Agent 上下文预留明确装配位置。 + +## 单 Agent Tool Calling + +**实现阶段：P2** + +- 将可用 Tool 描述交给模型，解析 Tool Call 并通过 Tool Gateway 执行。 +- 将结构化 Tool 结果送回模型，循环直至生成最终回答。 +- 对未知 Tool、无效参数、执行失败和循环上限给出可恢复反馈。 + +## 上下文裁剪与压缩 + +**实现阶段：P4** + +- 在超过模型上下文限制前选择、裁剪或压缩历史内容。 +- 保留关键用户要求、Tool 结果和来源，避免摘要悄然改变任务意图。 +- 向用户展示发生过的上下文压缩，并允许查看原始历史。 + +## 多模型管理与路由 + +**实现阶段：P5** + +- 接入多个 Model Adapter，按 Space、Profile、Behavior 或具体 Run 选择模型。 +- 支持模型能力匹配、失败降级和角色级模型路由。 +- 统一记录模型标识、Token、延迟和调用结果。 + +## 多模态模型能力 + +**实现阶段：P7** + +- 支持图片、截图、文件等多模态输入和相应模型能力声明。 +- 将附件、屏幕内容和浏览器截图安全地组装进模型上下文。 +- 对不支持某种输入的模型进行能力降级或路由。 diff --git a/docs/features/observability-reliability.md b/docs/features/observability-reliability.md new file mode 100644 index 0000000..0b4be17 --- /dev/null +++ b/docs/features/observability-reliability.md @@ -0,0 +1,57 @@ +# 可观测性与可靠性 + +## Run 时间线与基础日志 + +**实现阶段：P1** + +- 记录 Run 状态、模型请求结果、错误和客户端输出时间线。 +- P2 加入 Tool、Shell、测试、Diff 和 Artifact 事件。 +- 日志保持可读、可关联且能够从 CLI 定位，不提前建设复杂遥测平台。 + +## Runtime 与功能诊断 + +**实现阶段：P4** + +- 生成包含 Runtime、配置、扩展、模型、数据目录和最近错误的诊断报告。 +- 查看 Hook 调用、Tool 耗时、连接状态和异常堆栈。 +- 支持脱敏后导出诊断信息用于排查或交给 Agent 自己分析。 + +## Run 暂停与恢复 + +**实现阶段：P5** + +- 在计划、子 Agent 或等待用户输入时持久化可恢复状态。 +- 区分可安全重放的步骤和已经产生外部副作用的步骤。 +- Runtime 重启后允许用户继续、跳过、回滚或终止未完成 Run。 + +## Runtime 崩溃恢复 + +**实现阶段：P8** + +- 检测异常退出、孤儿子进程、未完成写入和悬空 worktree。 +- 重启后恢复健康状态并列出需要处理的 Run。 +- 对自动恢复过程保留记录，避免隐藏数据或副作用不一致。 + +## 数据完整性与修复 + +**实现阶段：P8** + +- 检查注册表、JSON/JSONL、Artifact、索引和实际目录之间的一致性。 +- 修复可恢复问题，隔离损坏记录，并在操作前生成备份。 +- 定期验证备份可读取，而不是只确认备份文件存在。 + +## 资源、性能与成本监控 + +**实现阶段：P8** + +- 统计 Runtime CPU/内存、磁盘占用、队列长度、模型 Token、延迟和费用。 +- 定位过慢 Tool、异常循环、长期占用的进程和持续增长的数据。 +- 为清理、并发限制和模型路由提供真实依据。 + +## 资源回收 + +**实现阶段：P8** + +- 管理 Workspace 临时文件、worktree、日志、缓存、索引和 Artifact 的保留策略。 +- 在自动清理前保护用户固定内容和仍被 Run 引用的资源。 +- 提供空间预览、手动清理和可恢复删除。 diff --git a/docs/features/permissions-security.md b/docs/features/permissions-security.md new file mode 100644 index 0000000..8a21b0c --- /dev/null +++ b/docs/features/permissions-security.md @@ -0,0 +1,57 @@ +# 权限、确认与敏感数据 + +## API Key 与基础凭据配置 + +**实现阶段：P1** + +- 首版安全读取 DeepSeek API Key，避免写入源码和普通 Run 日志。 +- 明确环境变量、配置引用和错误提示。 +- 所有凭据访问集中经过统一接口，为后续 Keychain 做准备。 + +## System Evolution Git 确认 + +**实现阶段：P3** + +- 对 commit、merge、push 和活动版本切换展示具体对象与 Diff。 +- 用户明确确认后才能执行，拒绝不会导致候选数据丢失。 +- 确认结果关联到 Evolution Run 和发布记录。 + +## 自动化操作的就地确认 + +**实现阶段：P7** + +- 文件批量修改或删除、网页提交、消息发布、系统设置等高影响动作在对应功能中请求确认。 +- 确认内容描述即将发生的真实副作用，而不是只显示抽象 Tool 名称。 +- 支持本次允许、拒绝和转为人工接管。 + +## 统一 Tool 风险与确认协议 + +**实现阶段：P8** + +- 为 Tool 声明读取范围、写入副作用、外部提交和所需系统权限。 +- 按全局、Profile、Space 和具体 Tool 配置自动允许或询问。 +- 统一管理待确认、超时、拒绝、恢复和审计记录。 + +## Keychain 与凭据生命周期 + +**实现阶段：P8** + +- 将模型、网站和外部服务凭据接入系统安全存储。 +- 支持创建、更新、撤销、失效提示和按能力授权访问。 +- Agent 只获得调用凭据的能力，不在普通上下文中看到明文。 + +## 敏感内容与历史清理 + +**实现阶段：P8** + +- 对日志、模型输入输出和 Artifact 中的密钥、Cookie 与个人信息进行识别和脱敏。 +- 支持用户定位并清除已经写入历史的敏感内容。 +- 清理过程同步处理缓存、索引、备份策略和来源引用。 + +## 远程访问边界 + +**实现阶段：P9** + +- Web 远程访问默认关闭，本地访问与远程暴露使用不同配置。 +- 远程模式提供轻量认证、连接撤销、来源限制和敏感操作再确认。 +- 不引入多用户系统，但避免无认证地暴露本机 Agent 能力。 diff --git a/docs/features/planning-multi-agent.md b/docs/features/planning-multi-agent.md new file mode 100644 index 0000000..802c8b0 --- /dev/null +++ b/docs/features/planning-multi-agent.md @@ -0,0 +1,57 @@ +# 计划、工作流与多 Agent + +## Plan 创建、编辑与执行 + +**实现阶段：P5** + +- 将复杂目标拆成有顺序和依赖关系的 Step。 +- 在执行前查看、编辑、重新生成或直接批准计划。 +- 顺序执行 Step，并将每步的输入、状态、结果和产物关联到父 Run。 + +## Step 控制与动态重规划 + +**实现阶段：P5** + +- 支持暂停、继续、跳过、重试和修改尚未执行的步骤。 +- 步骤失败后根据实际结果修订后续计划，而不是机械重复原方案。 +- 允许 Agent 在关键点等待用户补充信息或确认方向。 + +## Child Run 与子 Agent 委派 + +**实现阶段：P5** + +- 主 Agent 创建 Child Run，传递清晰目标、上下文和可用能力范围。 +- 隔离不同子 Agent 的工作上下文并回收结构化结果。 +- 父 Run 可以观察、取消和处理子 Run 失败。 + +## Agent 角色、团队与 Reviewer + +**实现阶段：P5** + +- 支持 Planner、Worker、Reviewer 等 Behavior 角色，但不固定唯一协作模板。 +- 按任务动态选择角色、模型、Tool 和上下文。 +- Reviewer 依据测试、Diff 和完成条件给出通过、返工或人工处理结论。 + +## 并行与 DAG 调度 + +**实现阶段：P5** + +- 并行执行没有依赖且不会争用同一资源的步骤。 +- 管理 DAG 依赖、并发上限、取消传播、工作区冲突和结果合并。 +- 并行失败不会造成其他步骤结果丢失或状态不明。 + +## 可复用工作流 + +**实现阶段：P5** + +- 将稳定的计划和 Agent 协作方式保存为参数化工作流。 +- 支持从一次成功 Run 提炼模板、再次运行并查看版本变化。 +- 工作流调用统一的 Behavior、Tool 和 Run，不另建执行引擎。 + +## 任务验证与质量评估 + +**实现阶段：P5** + +- 为计划和步骤定义可检查的完成条件。 +- 综合自动测试、Reviewer、外部状态和用户反馈评估结果。 +- 记录部分完成、回退、返工和最终交付之间的关系。 diff --git a/docs/features/project-assistant.md b/docs/features/project-assistant.md new file mode 100644 index 0000000..d2f983c --- /dev/null +++ b/docs/features/project-assistant.md @@ -0,0 +1,57 @@ +# Project 开发助手 + +## 项目上下文与规则 + +**实现阶段：P2** + +- 读取项目说明、目录结构、已有开发规则和构建配置。 +- 将相关 Project 上下文装配给 Coding Behavior，而不是一次性塞入全部源码。 +- 支持用户维护项目专属指令，并在 Run 中显示实际采用的规则。 + +## 仓库理解与代码检索 + +**实现阶段：P2** + +- 浏览仓库结构、搜索符号与文本、定位入口和相关测试。 +- 形成面向当前需求的结构概览，避免为每次任务预先建立重型索引。 +- 在修改前识别影响范围、现有约定和可能的验证方式。 + +## 代码修改与 Diff + +**实现阶段：P2** + +- 使用文件与补丁 Tool 修改源码，处理多文件改动和冲突。 +- 持续展示工作区状态和 Diff，并关联每次修改的需求与 Run。 +- 保持用户已有未提交改动，不用破坏性 Git 操作覆盖现场。 + +## Build、Test、Lint 与验证 + +**实现阶段：P2** + +- 发现或配置项目验证命令，运行构建、测试、Lint 和类型检查。 +- 解析退出状态和关键失败，允许 Agent 修正后重新验证。 +- 汇总执行过的验证、未执行项和剩余风险。 + +## 单 Agent 开发闭环 + +**实现阶段：P2** + +- 跑通“理解需求 → 阅读源码 → 修改 → 验证 → 汇报”的完整流程。 +- 在普通非自身项目中验证该闭环后，才允许用于 System Evolution。 +- 最终回答包含改动摘要、验证结果、Diff 位置和需要用户决定的问题。 + +## Git 与 Worktree 工作流 + +**实现阶段：P2** + +- 支持 status、diff、log、branch 和隔离 worktree 的创建、使用、检查与清理。 +- 候选开发默认在 worktree 中进行，稳定工作区保持可用。 +- Git 写操作通过明确的工作流执行，不让模型随意拼接高影响命令。 + +## 远程仓库、PR 与 CI + +**实现阶段：P7** + +- 读取远程 Issue、PR、Review 和 CI 状态，将其转换为本地开发上下文。 +- 支持创建提交、推送分支、创建或更新 PR，并展示外部结果。 +- 所有对外写操作进入统一确认和审计流程。 diff --git a/docs/features/run-execution.md b/docs/features/run-execution.md new file mode 100644 index 0000000..a922dd5 --- /dev/null +++ b/docs/features/run-execution.md @@ -0,0 +1,49 @@ +# Run 与 Agent 执行 + +## Run Context、Record 与生命周期 + +**实现阶段：P1** + +- Microkernel 创建内存 Run Context，Application Runtime 保存同 ID 的 Run Record。 +- 覆盖创建、运行、完成、失败和取消等基础生命周期。 +- 纯聊天与 Tool 行动共享同一 Run 概念，并关联所属 Space、Conversation 和输入消息。 + +## Run Event 与实时输出 + +**实现阶段：P1** + +- 产生文本增量、状态变化、错误和完成结果等结构化 Run Event。 +- 将 Event 同时用于客户端实时展示和 Run 日志，不与 Hook 执行语义混淆。 +- 保证客户端断开不影响 Runtime 中 Run 的基本记录完整性。 + +## Tool 行动执行循环 + +**实现阶段：P2** + +- 记录模型请求 Tool、Tool 执行、结果返回模型和最终回答的完整时间线。 +- 支持一个 Run 内多次顺序 Tool 调用及其错误反馈。 +- 将 Run 结果、实际副作用和产物建立可追踪关联。 + +## Run 控制与人工介入 + +**实现阶段：P4** + +- 支持取消、重试、重新执行、暂停等待用户输入和继续运行。 +- 用户可以在长 Run 中回答 Agent 追问、修改约束或终止后续行动。 +- 重新执行时明确复用哪些输入、上下文和已经产生的副作用。 + +## 后台 Run 与运行队列 + +**实现阶段：P5** + +- 支持客户端退出后继续执行、排队、优先级和并发限制。 +- 恢复连接后可以重新订阅进度、查看结果或取消后台 Run。 +- 为 Child Run、多 Agent 和自动化任务提供统一调度入口。 + +## Run 结果验证 + +**实现阶段：P5** + +- 为 Run 定义可验证的完成条件，而不只依赖模型口头宣布完成。 +- 汇总测试、文件变化、Tool 结果和 Reviewer 结论形成最终结果。 +- 区分成功、部分完成、需要人工处理和不可继续的失败。 diff --git a/docs/features/runtime.md b/docs/features/runtime.md new file mode 100644 index 0000000..4e50426 --- /dev/null +++ b/docs/features/runtime.md @@ -0,0 +1,57 @@ +# Runtime 与系统生命周期 + +## 工程基座与依赖边界 + +**实现阶段：P1** + +- 建立 TypeScript + Node.js monorepo、统一构建、测试、类型检查和开发命令。 +- 落实 Supervisor、Runtime Host、Application Runtime、Microkernel、Extensions 和 Clients 的依赖方向。 +- 保证 Microkernel 不依赖产品领域或具体扩展，客户端不直接依赖 Runtime 内部实现。 + +## Runtime Host 与进程生命周期 + +**实现阶段：P1** + +- 提供常驻 Node.js Runtime、单实例检测、启动、停止、退出信号和基础健康检查。 +- 负责读取启动配置、组装 Application Runtime、Microkernel 与首批内置能力。 +- CLI 在 Runtime 未启动时能够拉起并连接，退出 CLI 不终止 Runtime。 + +## Application Runtime + +**实现阶段：P1** + +- 管理 Space、Conversation、持久化 Run Record、当前上下文和本地 Repository。 +- 作为所有本地数据的唯一写入者，协调客户端请求与 Agent 执行。 +- 提供基础 Profile 选择和首版串行 Run 策略。 + +## Microkernel + +**实现阶段：P1** + +- 创建内存 Run Context，调度 Behavior，传播取消信号并隔离错误。 +- 提供 Tool Gateway、最小 Hook Pipeline、运行事件和流式输出接缝。 +- 通过可测试的公共接口运行，不认识 Project、Task、DeepSeek 或具体存储。 + +## Runtime Interface + +**实现阶段：P1** + +- 提供 Command、Query、Event Stream 三类客户端交互。 +- 支持流式文本、Tool 进度、Run 状态和错误事件。 +- 首版完成本地传输、连接识别、断线处理和协议级错误返回。 + +## 运行诊断与环境信息 + +**实现阶段：P4** + +- 提供 Runtime 版本、进程、端口、数据目录、已加载能力和健康状态查询。 +- 支持诊断报告、连接恢复、配置来源追踪和调试模式。 +- 为 CLI/TUI、Web、Desktop 共享同一套诊断数据。 + +## 后台队列与并发运行 + +**实现阶段：P5** + +- 从首版串行执行发展为后台 Run、排队、按 Space 并发和资源占用控制。 +- 支持客户端断开后继续运行、重新订阅和跨子 Run 的取消传播。 +- 为多 Agent、自动化和长期任务提供统一运行基础。 diff --git a/docs/features/spaces.md b/docs/features/spaces.md new file mode 100644 index 0000000..ba83105 --- /dev/null +++ b/docs/features/spaces.md @@ -0,0 +1,49 @@ +# Space、Conversation 与消息 + +## Task 生命周期 + +**实现阶段：P1** + +- 创建、命名、列出、切换、重命名、归档和删除 Task。 +- 提供首次启动的默认 Task，并记录最近使用位置。 +- Task 的工作文件和 Agent 数据随整个 Task 目录移动。 + +## Conversation 生命周期 + +**实现阶段：P1** + +- 在每个 Space 内创建、命名、切换、重命名、归档和删除 Conversation。 +- 保存消息顺序、角色、可见内容和关联 Run。 +- 支持恢复最近 Conversation，并为自动标题保留实现入口。 + +## Project 绑定与发现 + +**实现阶段：P2** + +- 将本地目录注册为 Project，并初始化或复用根目录中的 `.agent/`。 +- 支持 Project 移动后的重新定位、解绑和重新发现。 +- 保证项目源码不复制到 Agent 数据目录，多个会话共享同一个 Project 上下文。 + +## Task 升级为 Project + +**实现阶段：P4** + +- 将整个 Task 目录移动至用户指定位置并改为 Project。 +- 更新 Space 类型、全局注册路径和相关上下文引用。 +- 处理目标目录冲突、Git 初始化与升级失败回退。 + +## Conversation 搜索、分支与引用 + +**实现阶段：P4** + +- 跨 Space 搜索 Conversation、消息和 Run 结果。 +- 支持编辑或重新执行历史输入，并通过会话分支保留原始对话。 +- 在新会话中引用其他 Conversation 或 Run，并保留来源导航。 + +## 会话附件 + +**实现阶段：P6** + +- 在消息中附加文件、图片、代码片段和其他本地资料。 +- 管理附件复制或引用策略、预览、上下文注入和删除。 +- 为 Web/Desktop 和多模态模型共享统一附件语义。 diff --git a/docs/features/system-evolution.md b/docs/features/system-evolution.md new file mode 100644 index 0000000..57596cf --- /dev/null +++ b/docs/features/system-evolution.md @@ -0,0 +1,49 @@ +# System Evolution + +## System Evolution Project + +**实现阶段：P3** + +- 将 Agent 自身源码仓库注册为特殊 Project，并应用 System Evolution Profile。 +- 用户在该 Project 的 Conversation 中提出自身需求和反馈，不要求 Agent 自动发现问题。 +- 复用 P2 已验证的单 Agent 开发能力，而不是建设第二套修改系统。 + +## Source、Candidate 与 Release 隔离 + +**实现阶段：P3** + +- 区分源码仓库、候选 worktree 和 Supervisor 实际启动的 Installed Release。 +- 当前运行版本不会被候选修改直接覆盖。 +- 候选失败、放弃或重新修改不会影响稳定 Runtime。 + +## 自身修改与验证流程 + +**实现阶段：P3** + +- 将用户需求转化为候选 worktree 中的代码修改。 +- 运行构建、测试、类型检查和最小启动验证。 +- 输出变更说明、完整 Diff、验证结果和已知风险。 + +## 发布提案与 Git 确认 + +**实现阶段：P3** + +- 将候选版本整理为可审核的发布提案。 +- commit、merge、push 等 Git 写操作必须由用户明确确认。 +- 拒绝发布时保留候选上下文，允许继续修改或安全清理。 + +## Supervisor 发布与回退 + +**实现阶段：P3** + +- 将通过确认的代码构建为不可变 Installed Release。 +- 原子切换活动版本、重启 Runtime、执行健康检查并完成客户端重连。 +- 新版本失败时自动切回旧版本，并支持用户主动回退演练。 + +## Evolution Record 与版本评估 + +**实现阶段：P4** + +- 关联需求、Conversation、Run、worktree、Diff、测试、Git 提交、Release 和回退结果。 +- 保存基准任务和回归验证，用于比较候选与稳定版本。 +- 从历史进化记录中查看某项能力为何加入、如何验证和何时发布。 diff --git a/docs/features/tools-execution.md b/docs/features/tools-execution.md new file mode 100644 index 0000000..2583179 --- /dev/null +++ b/docs/features/tools-execution.md @@ -0,0 +1,65 @@ +# Tools、Workspace 与产物 + +## Tool 契约与统一 Gateway + +**实现阶段：P2** + +- 定义 Tool 名称、说明、参数 Schema、结构化结果和错误协议。 +- 支持注册、列出、调用和取消 Tool，并将所有调用纳入 Run Context。 +- 在统一 Gateway 中触发基础 Hook、日志和输出事件。 + +## Workspace 作用域与路径解析 + +**实现阶段：P2** + +- 为 Task 和 Project 解析工作区根目录与当前工作目录。 +- 统一处理相对路径、绝对路径、符号链接和工作区外路径。 +- 将 Tool 产生的实际文件与 `.agent/` 元数据明确区分。 + +## 文件操作 Toolset + +**实现阶段：P2** + +- 支持目录浏览、文件读取、文本搜索、写入、补丁、移动、复制和创建目录。 +- 处理编码、大文件、二进制文件和修改冲突。 +- 返回适合模型继续工作的结构化摘要，同时保留完整结果入口。 + +## Shell 与进程 Toolset + +**实现阶段：P2** + +- 执行 Shell 命令，流式返回 stdout/stderr、退出码和耗时。 +- 支持超时、取消、工作目录、环境变量和基础后台进程处理。 +- 将模型临时生成的命令或脚本文本记录进 Run，不额外建立脚本库。 + +## Tool 进度与产物收集 + +**实现阶段：P2** + +- 统一表达 Tool 开始、进度、完成、失败和取消。 +- 自动识别测试报告、截图、下载文件和其他可预览产物并关联到 Run。 +- 支持产物查看、固定、导出和后续 Tool 引用。 + +## 交互式终端会话 + +**实现阶段：P4** + +- 使用 PTY 运行需要持续输入、终端控制序列或长时间驻留的命令。 +- 允许 Agent 与用户查看会话、发送输入、转入后台、重新连接和终止进程。 +- 将交互式会话与普通 Shell Tool、Run 日志和资源回收统一管理。 + +## Tool 能力范围与分组 + +**实现阶段：P4** + +- 按 Profile、Space 和 Behavior 选择向模型暴露的 Tool 集合。 +- 支持 Tool 别名、分组、描述优化和能力发现，避免一次向模型暴露过多接口。 +- 为权限策略和不同平台能力降级提供统一元数据。 + +## 外部 Tool 协议接入 + +**实现阶段：P4** + +- 通过 Adapter 接入 MCP 等外部 Tool 服务，将其映射到统一 Tool 契约。 +- 管理服务连接、能力同步、错误转换和生命周期。 +- 外部 Tool 与内置 Tool 使用一致的日志、确认和 Run 关联。 diff --git a/docs/features/web.md b/docs/features/web.md new file mode 100644 index 0000000..058049e --- /dev/null +++ b/docs/features/web.md @@ -0,0 +1,57 @@ +# Web + +## Web 客户端基础与 Runtime 连接 + +**实现阶段：P9** + +- 选择 Web 框架并建立路由、状态管理和 Runtime Client。 +- 使用 Runtime 已有的 Command、Query、Event Stream，不重复实现 Agent 逻辑。 +- 处理连接状态、断线重连、版本不匹配和实时事件恢复。 + +## Space、Conversation 与聊天 + +**实现阶段：P9** + +- 创建、切换和管理 Task、Project、Conversation 与消息附件。 +- 支持流式聊天、历史导航、搜索和会话分支。 +- 在桌面与移动尺寸下保持可用的响应式交互。 + +## Run 与 Agent 工作台 + +**实现阶段：P9** + +- 展示 Run 时间线、Tool、Plan、Step、Child Run、Agent 角色、日志和 Artifact。 +- 提供取消、暂停、继续、重试、人工回答和计划调整。 +- 长任务在页面刷新或断线后能够恢复观察。 + +## Project 开发与 Review + +**实现阶段：P9** + +- 展示项目文件、代码修改、Build/Test/Lint 结果和 Git Diff。 +- 完成候选修改 Review、评论、确认和返回 Agent 继续修改。 +- 查看远程 Issue、PR 和 CI 结果。 + +## System Evolution 控制台 + +**实现阶段：P9** + +- 查看自身候选版本、测试、Diff、Evolution Record 和 Release。 +- 执行 Git 确认、版本发布、健康检查、重启和回退。 +- 清晰区分稳定版本、当前运行版本和未发布候选版本。 + +## 记忆、扩展与自动化管理 + +**实现阶段：P9** + +- 查看和编辑记忆、知识来源、Profile、模型、Tool、Hook、Behavior 与扩展。 +- 管理提醒、周期任务、事件触发器和自动化执行历史。 +- 提供统一配置和确认中心。 + +## 本地与远程访问体验 + +**实现阶段：P9** + +- 默认服务本机使用，并提供明确的远程启用流程。 +- 支持会话过期、认证、设备连接管理和敏感操作保护。 +- 保持远程客户端不直接访问本地数据文件或 Tool 实现。 diff --git a/docs/foundation/cli.md b/docs/foundation/cli.md deleted file mode 100644 index 6471371..0000000 --- a/docs/foundation/cli.md +++ /dev/null @@ -1,45 +0,0 @@ -# CLI - -CLI 是第一条完整产品线，既要适合快速对话，也要能观察和管理复杂运行。 - -## 自然语言 REPL - -- 期望实现阶段：P1 -- 实际开发状态：未开始 -- 已确认点：普通输入发送给当前 Conversation；提示符展示当前 Task/Project 与 Conversation；回答支持流式输出。 -- 待确认点：启动时恢复最近上下文还是显示选择器；输入历史、多行输入与中断体验。 - -## 斜杠命令 - -- 期望实现阶段：P1 -- 实际开发状态：未开始 -- 已确认点：斜杠命令只处理确定性控制操作；候选包括 `/new`、`/switch`、`/task`、`/project`、`/runs`、`/log`、`/cancel`、`/exit`。 -- 待确认点：第一批命令范围、参数格式、命令补全和错误提示。 - -## Space 与会话导航 - -- 期望实现阶段：P1 -- 实际开发状态：未开始 -- 已确认点：CLI 能创建、查看、切换 Task/Project 和它们内部的多个 Conversation。 -- 待确认点：列表样式、编号/名称选择、最近使用记录与快速切换方式。 - -## Tool 与 Run 呈现 - -- 期望实现阶段：P2 -- 实际开发状态：未开始 -- 已确认点：显示 Tool 名称、关键参数、结果和失败，不展示模型内部推理；长输出保留完整日志入口。 -- 待确认点：流式事件样式、折叠规则、颜色、产物链接和后台 Run 展示。 - -## 全屏 TUI - -- 期望实现阶段：P1 -- 实际开发状态：未开始 -- 已确认点：TUI 属于 CLI 正式能力，用于浏览 Space、Conversation、Run、日志与产物；REPL 仍保留用于快速工作。 -- 待确认点：TUI 库、布局、快捷键、命令面板，以及与 REPL 的切换方式。 - -## CLI 诊断与配置 - -- 期望实现阶段：P2 -- 实际开发状态：未开始 -- 已确认点：CLI 应能查看 Runtime 状态、当前配置与日志位置。 -- 待确认点：配置修改入口、诊断报告和调试模式。 diff --git a/docs/foundation/runtime.md b/docs/foundation/runtime.md deleted file mode 100644 index 0a3023c..0000000 --- a/docs/foundation/runtime.md +++ /dev/null @@ -1,31 +0,0 @@ -# Runtime - -Runtime 是本地常驻的唯一运行宿主，负责状态写入、Agent 执行与 Tool 调用。CLI、Web、Desktop 都是它的客户端。 - -## 工程与包边界 - -- 期望实现阶段：P1 -- 实际开发状态：未开始 -- 已确认点：TypeScript + Node.js + monorepo；Runtime、客户端与共享边界需要清晰。 -- 待确认点：Node 版本、包管理器、monorepo 工具、首批包的职责与依赖方向。 - -## 常驻进程 - -- 期望实现阶段：P1 -- 实际开发状态：未开始 -- 已确认点：Runtime 从第一天起独立常驻；CLI 日常启动时自动连接，必要时自动拉起。 -- 待确认点：单实例检测、启动/停止、健康检查、日志位置和异常退出行为。 - -## 本地通信 - -- 期望实现阶段：P1 -- 实际开发状态：未开始 -- 已确认点：客户端不直接读写 Agent 数据；协议不绑定 CLI，并应能支持流式输出。 -- 待确认点：HTTP + SSE、Unix Socket 或其他本地 RPC 方案。 - -## Runtime 服务边界 - -- 期望实现阶段：P1 -- 实际开发状态：未开始 -- 已确认点：Runtime 负责 Space、Conversation、Run、本地数据、Agent Behavior 与 Tool 执行。 -- 待确认点：首版内部模块边界，以及哪些能力进入微内核、哪些保留为可替换实现。 diff --git a/docs/foundation/spaces.md b/docs/foundation/spaces.md deleted file mode 100644 index 8aed449..0000000 --- a/docs/foundation/spaces.md +++ /dev/null @@ -1,31 +0,0 @@ -# Space 与 Conversation - -Project 与 Task 是并列的一级空间，两者内部都可以包含多个 Conversation。 - -## Task Space - -- 期望实现阶段：P1 -- 实际开发状态：未开始 -- 已确认点：用于闲聊与临时事务；数据存放于用户目录；每个 Task 拥有专属 Workspace。 -- 待确认点：默认 `inbox`、自动命名、归档、删除与最近使用策略。 - -## Project Space - -- 期望实现阶段：P2 -- 实际开发状态：未开始 -- 已确认点：用于长期开发工作；绑定本地项目目录；Agent 数据存放在项目的 `.agent/` 中。 -- 待确认点：项目初始化、路径移动、解绑与多工作区支持。 - -## Conversation - -- 期望实现阶段：P1 -- 实际开发状态：未开始 -- 已确认点：每个 Space 可以拥有多个 Conversation；会话承载消息与相关 Run。 -- 待确认点：标题生成、重命名、归档、搜索和跨会话引用。 - -## Task 升级为 Project - -- 期望实现阶段：P2 -- 实际开发状态：未开始 -- 已确认点：Task Workspace 结构尽量与 Project 工作区一致；升级时迁移到用户指定位置并补充 Project 元数据。 -- 待确认点：目录冲突、历史记录路径更新、Git 初始化与升级交互。 diff --git a/docs/intelligence/memory-knowledge.md b/docs/intelligence/memory-knowledge.md deleted file mode 100644 index a546e7d..0000000 --- a/docs/intelligence/memory-knowledge.md +++ /dev/null @@ -1,38 +0,0 @@ -# 记忆与知识 - -记忆能力为 CLI、Web、Desktop 共享个人、项目和会话上下文，同时保持数据本地、可读和可编辑。 - -## Conversation 记忆 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：会话可以生成摘要，降低长历史的上下文成本。 -- 待确认点：生成时机、更新方式、人工编辑和与原始消息的关系。 - -## Space 记忆 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：Task/Project 各自保存长期上下文；Project 可沉淀规则、架构和决策。 -- 待确认点：文件布局、跨会话提炼、失效信息和 Task/Project 差异。 - -## 全局个人记忆 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：保存跨 Space 有效的个人偏好与长期事实，供三端共享。 -- 待确认点：写入确认、隐私边界、冲突处理和从 Space 提升的规则。 - -## 记忆管理 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：记忆应能查看、编辑、固定、遗忘并追溯来源。 -- 待确认点：客户端体验、自动清理、可信度与过期策略。 - -## 检索与知识导入 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：先使用普通文件和全文检索；向量/混合检索、文档导入按真实需求增加。 -- 待确认点：索引方式、切分、引用来源、支持格式与向量存储。 diff --git a/docs/intelligence/planning-multi-agent.md b/docs/intelligence/planning-multi-agent.md deleted file mode 100644 index 08a11f0..0000000 --- a/docs/intelligence/planning-multi-agent.md +++ /dev/null @@ -1,38 +0,0 @@ -# 计划与多 Agent - -这一能力在单 Agent 出现真实瓶颈后引入，用于拆解复杂目标并协调多个执行者。 - -## Plan 与 Step - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：复杂目标可拆为可执行步骤并自动依序执行；它们属于 Run 之上的行为能力。 -- 待确认点：数据结构、编辑方式、完成条件、CLI/TUI 展示和与 Conversation 的关系。 - -## 步骤执行与重规划 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：未来需要失败重试、跳过和重新规划，但不在 MVP 中预设完整状态机。 -- 待确认点：失败分类、重试上限、人工介入点和上下文继承。 - -## 子 Agent 委派 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：主 Agent 可以创建子 Run，分配目标并回收结果。 -- 待确认点：上下文隔离、Tool 范围、并发限制、取消传播与结果可信度。 - -## Agent 角色与协作模板 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：Planner、Worker、Reviewer 是候选角色，不构成强制工作流。 -- 待确认点：角色声明、Behavior 组合、Reviewer 门槛和用户自定义方式。 - -## 并行与模型路由 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：并行、DAG、不同角色使用不同模型都属于后续增强。 -- 待确认点：调度策略、成本/Token 统计、并发冲突与结果合并。 diff --git a/docs/operations/reliability-safety.md b/docs/operations/reliability-safety.md deleted file mode 100644 index f1c6038..0000000 --- a/docs/operations/reliability-safety.md +++ /dev/null @@ -1,38 +0,0 @@ -# 可靠性与个人安全 - -安全能力不阻塞早期个人探索，但在 Agent 开始影响真实文件、网站和系统后，需要逐步补足恢复与确认能力。 - -## Run 恢复 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：长期需要取消、暂停、恢复与 Runtime 崩溃后的未完成 Run 处理。 -- 待确认点：恢复粒度、可重放 Tool、幂等性和异常进程清理。 - -## 数据备份与迁移 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：本地数据最终需要备份、导入导出和目录迁移；早期格式变化可使用一次性脚本。 -- 待确认点：备份位置、周期、保留数量、恢复验证和格式兼容范围。 - -## 高影响操作确认 - -- 期望实现阶段：P3 -- 实际开发状态：未开始 -- 已确认点：System Evolution 的 Git 写操作必须确认；删除文件、真实网页提交、系统设置等后续按实际风险加入。 -- 待确认点：确认粒度、默认允许范围、超时和拒绝后的 Run 行为。 - -## 密钥与敏感数据 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：项目是单用户、本地优先，不建设多租户权限；长期可接入系统 Keychain 并处理敏感日志。 -- 待确认点：首版 API Key 保存方式、脱敏规则和敏感 Tool 输出保留策略。 - -## Workspace 与产物清理 - -- 期望实现阶段：P4 -- 实际开发状态：未开始 -- 已确认点：需要管理临时文件、候选 worktree、执行产物和长期磁盘占用。 -- 待确认点：自动清理阈值、回收站、归档和用户固定机制。 diff --git a/docs/roadmap.md b/docs/roadmap.md index bc24c10..e69670d 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,29 +1,75 @@ -# 路线图与管理规则 +# 实现阶段 -路线图只描述阶段目标。每个功能的具体拆分、提交顺序和实现方案以各自的功能文档为准。 +阶段只描述实际开发顺序，不等同于功能分类。大功能会跨越多个阶段，每个小功能点在对应功能文档中标记自己的实现阶段。 -| 阶段 | 目标 | 已知范围 | -| --- | --- | --- | -| P1 | 本地 Runtime 与终端产品基础 | Runtime、CLI（REPL 与全屏 TUI）、Space、会话、DeepSeek 聊天、Run、基础 Tool/Hook 接缝 | -| P2 | 终端行动能力与开发助手 | Workspace、文件/Shell、单 Agent Tool Calling、Project、代码与 Git Worktree 能力 | -| P3 | System Evolution 闭环 | 候选 worktree、自身修改与测试、确认发布、Supervisor 回退 | -| P4 | Runtime 成长与个人自动化 | 扩展、计划/多 Agent、记忆、浏览器/电脑控制、可靠性与按需安全能力 | -| P5 | Web 产品线 | Runtime 的 Web 客户端与管理界面 | -| P6 | Desktop 产品线 | 本地常驻控制台与系统集成 | +## P1：本地可交互基座 -## 功能记录格式 +建立 TypeScript + Node.js monorepo、常驻 Runtime、本地文件数据、Task、Conversation、基础 Run、DeepSeek 流式聊天和 CLI REPL。 -大功能本身不设置状态和阶段。大功能文档中的每个小功能点分别记录： +完成标准：Runtime 可独立启动，CLI 可连接并管理多个 Task/Conversation，退出重进后能够继续聊天。 -```text -期望实现阶段：P1 | P2 | ... -实际开发状态：未开始 | 设计中 | 开发中 | 已完成 | 暂停 -已确认点：当前已经达成共识的要求 -待确认点：实现前仍需讨论或通过实践决定的问题 -``` +## P2：可行动的开发助手 -新增需求先归类到已有大功能点；如果它确实是新的长期能力，再新建一个大功能文件。实现过程中允许新增、合并或拆分小功能点，不要求回头重排整份路线图。 +加入 Tool Gateway、文件与 Shell Tool、单 Agent Tool Calling、Project、源码修改、测试、Git/Worktree、Run 日志和终端执行观察。 -## 提交与 blog +完成标准：Agent 能在一个普通项目的隔离 worktree 中理解需求、修改源码、执行测试并展示可审核的 Diff。 -一次提交应交付一个可验证的纵向能力，而不是单独提交类型、枚举或预留接口。完成后在相关功能文档追加：提交链接、验证方式、实现取舍和对应 blog。 +## P3：最小自举闭环 + +建立 System Evolution Project、候选 worktree、构建测试、变更审核、Git 写操作确认、Installed Release、Supervisor 切换和失败回退。 + +完成标准：Agent 为自身增加一个完整的小能力，经用户确认发布后由新 Runtime 接管，并能够实际回退到旧版本。 + +P3 之后的功能默认优先通过该自举流程实现。 + +## P4：终端产品与扩展能力成熟 + +完善斜杠命令、非交互 CLI、全屏 TUI、Runtime 诊断、后台 Run、Hook Runtime、Profile、扩展加载与开发体验、多模型以及完整进化记录。 + +完成标准：终端可以承担日常工作和 System Evolution 的完整操作；新增能力通常能够落入清晰的 Adapter、Tool、Hook 或 Behavior 边界。 + +## P5：计划与多 Agent + +实现 Plan/Step、连续执行、失败重规划、Child Run、角色协作、并行/DAG 调度、结果验证和模型路由。 + +完成标准：复杂目标可以被拆解、连续执行、动态调整，并由多个 Agent 分工完成与验证。 + +## P6：分层记忆与个人知识 + +实现 Conversation、Task/Project、全局个人记忆，记忆管理、全文/向量检索、文档导入和项目知识沉淀。 + +完成标准：新会话能够准确找到相关历史和来源，用户可以查看、纠正或删除记忆。 + +## P7：电脑管家与个人自动化 + +实现浏览器、本机文件与应用、剪贴板、通知、屏幕理解和操作、定时/后台任务、多模态输入与可复用自动化流程。 + +完成标准：Agent 可以从终端完成开发之外的高频电脑事务，并沉淀重复工作。 + +## P8：可靠性、安全与数据治理 + +系统化建设崩溃恢复、数据备份和迁移、统一审批、风险策略、密钥与敏感数据、资源清理和版本维护。 + +完成标准：强能力不会因为进程崩溃、数据损坏、误操作或错误升级造成不可恢复的后果。 + +这不意味着早期阶段不处理错误和风险：每一阶段都必须具备支撑自身闭环的最小日志、取消、确认或回退；P8 负责将它们统一为完整体系。 + +## P9：Web 产品线 + +基于同一 Runtime 建设 Web 会话、运行观察、项目、记忆、扩展、审批和 System Evolution 管理，并支持受控远程访问。 + +完成标准：Web 能独立承担日常交互与执行观察，但不复制 Agent 逻辑和数据状态。 + +## P10：Desktop 产品线 + +复用 Web 界面并增加 Runtime 生命周期、托盘、快捷键、通知、原生确认、系统能力桥接、安装和更新体验。 + +完成标准：Desktop 提供 Web 无法自然提供的本地常驻和原生集成能力，而不是第三套 Agent 实现。 + +## 功能文档规则 + +- `docs/features/` 中每个文件对应一个大功能。 +- 大功能不设置阶段，因为其中的小功能可能分布在多个阶段。 +- 每个小功能必须有可独立验证的实质性交付；只需改动很少代码的细节应合并到相邻功能点。 +- 小功能只记录实现阶段和功能范围，不维护 todo/done、候选、已确认或待确认状态。 +- 进入某个阶段时，再围绕该阶段的小功能制定提交级实现计划。