失败处理与恢复规格
13. 失败处理与恢复规格1. 目标Agent 系统不能把失败当成异常边缘情况。失败是常态，系统必须有明确恢复策略。 2. 失败类型建议至少区分： tool_input_error permission_denied hook_blocked shell_runtime_error model_api_error prompt_too_long mcp_connect_error task_killed resume_load_error session_storage_error 3. 各类失败处理原则tool_input_error 直接回写错误给模型 不执行真实工具 permission_denied 不重复原样调用 引导模型调整方案 hook_blocked 将阻断原因结构化返回 允许模型或用户后续处理 prompt_too_long 触发 compact / reactive compact 必要时重建消息序列后重试 model_api_error 保留错误记录 可尝试有限恢复 4. resume 恢复需求系统必须支持： 读取 transcri...
命令系统、界面与操作者体验需求文档
05. 命令系统、界面与操作者体验需求文档1. 为什么命令系统是一级产品能力这类产品不是单轮对话工具，而是一个长期运行的操作者界面。因此，命令系统不是附属功能，而是操作面板。 2. 命令系统需求产品需要支持用户快速控制以下对象： memory permissions hooks mcp skills tasks review / plan / status 输出风格 model sandbox 插件管理 3. 命令系统的产品目标 降低复杂能力的学习成本 提供清晰的系统控制入口 把高级功能从自然语言里解耦出来 为插件和技能提供统一入口面 4. UI / TUI 的核心需求4.1 任务可见性用户需要看到： 当前在做什么 后台任务是否运行中 子 agent 在做什么 哪些动作在等待权限 4.2 状态反馈系统需要及时反馈： 进度 错误 被阻断原因 工具运行状态 4.3 结构化展示系统需要把复杂状态结构化展示出来，例如： memory 面板 permissions 面板 skills 列表 hooks 状态 mcp 状态 tasks 状态 5...
任务模型与后台执行规格
11. 任务模型与后台执行规格1. 目标任务系统负责把“一个 agent 在做什么”变成可追踪对象，而不是只存在于对话文本里。 2. 任务类型Python 版建议至少支持： main_session_task local_agent_task background_agent_task shell_task verification_task remote_task（可后置） 3. 核心任务字段123456789101112131415class TaskRecord: task_id: str type: str session_id: str parent_task_id: str | None agent_id: str | None description: str status: str created_at: float started_at: float | None finished_at: float | None output_path: str | None error: str |...
产品总览需求文档
00. 产品总览需求文档1. 产品定义这是一款面向软件工程任务的交互式 AI 执行系统。它不是单纯的聊天机器人，也不是只会调用几个工具的脚本外壳，而是一套把推理、工具、权限、任务拆解、记忆、扩展机制与用户交互统一起来的产品系统。 2. 产品目标产品需要满足以下目标： 帮助用户完成真实的软件工程任务，而不只是提供建议 在执行过程中保持安全、可控、可恢复 让复杂任务可以分解、委派、验证、追踪 让系统可以扩展新的技能、插件与外部工具能力 让长期使用形成可积累的记忆和工作习惯 3. 核心用户3.1 主要用户 独立开发者 工程师 技术产品经理 有代码任务但希望借助 AI 提升效率的操作者 3.2 用户的核心诉求 我不只想问问题，我想让系统帮我做事 我不只想生成代码，我想让它真正改动项目并验证结果 我不只想要一次回答，我想让它持续推进任务 我不只想在一个固定产品里工作，我希望它能接入我自己的工具和工作流 4. 产品要解决的核心问题4.1 普通聊天模型的问题普通聊天模型的核心局限是： 只做一次性回答 没有稳定执行能力 没有工具治理 没有任务状态 没有长期上下文管理 无法形成可扩展工作...
上下文管理与压缩规格
10. 上下文管理与压缩规格1. 目标上下文管理的目标不是“保留一切”，而是让模型在有限预算内持续拿到最关键的信息。 2. 必须保留的信息优先级最高的信息包括： 当前用户任务目标 系统硬规则与安全约束 用户明确偏好 最近关键工具结果 当前活跃子任务状态 记忆摘要 最近 compact 后的摘要 3. 可压缩的信息以下信息应优先被压缩或裁剪： 旧的长日志 重复解释 已完成步骤的冗余细节 大量相似 read/search 结果 旧的 progress 消息 4. 上下文预算机制Python 版建议同时维护： 粗略 token 估计 工具结果字符预算 每轮输出预算 全任务预算（可选） 5. 压缩触发条件建议在以下情况触发： 请求前 token 估计超过阈值 工具结果总量过大 模型返回 prompt too long resume 重建会话时 6. 压缩策略层级6.1 轻量裁剪先裁剪： 重复 progress 冗长工具输出尾部 无关附件 6.2 摘要压缩把旧消息浓缩成 summary message。 6.3 边界标记插入 compact boundary，...
Skills、Plugins与MCP需求文档
03. Skills、Plugins 与 MCP 需求文档1. 为什么产品不能只靠内置能力如果产品所有能力都硬编码在主程序里，会遇到几个问题： 难以扩展 难以适配不同团队 难以承载领域知识 难以形成生态 因此，这套产品必须支持可扩展能力面。 2. Skills 的需求本质Skill 不是普通帮助文档，而是一种可复用的工作流能力包。 2.1 Skill 需要承载什么 某类任务的使用规则 某类任务的上下文说明 某类任务的执行 SOP 该任务适用的工具边界 2.2 为什么 Skill 必须是 first-class primitive因为产品需要让模型在遇到特定任务时，优先加载相应能力，而不是每次都重新即兴发挥。 3. Skill 的产品需求 系统要能列出当前可用技能 模型要能在合适时调用技能 skill 内容要能注入会话 skill 要能带 frontmatter 元信息 skill 可以约束 allowed-tools skill 需要避免重复加载 4. Plugin 的需求本质Plugin 的角色不是给程序员加脚本，而是为模型注入新的行为表面。 Plugin 至少要支持 ...
Skill 技能
一、定义Skill 是一种可复用的 Prompt 增强包，通过渐进式加载机制为 Agent 注入领域知识和工作流程。 Anthropic 将 Skill 规范作为开放标准发布，目前已被多个 Agent 产品采纳，包括 Claude Code、OpenAI Codex、GitHub Copilot、VS Code、Cursor、Gemini CLI、Kiro 等。 按照我的理解，Skill 就是将一个固定的 Prompt 提示词进行打包，省去每次编写，供模型调用。 比如，我经常使用 AI 工具将工作内容进行汇总并生成报告，报告的要求包括字数、日期、错别字检查、格式等，这些规则都是固定的。如果没有 Skill，每次都要写大致相同的 Prompt 提示词。有了 Skill 之后，我可以先让 AI 工具生成这些规则的 Skill，以后每次只调用这个 Skill 执行，简化每次编写相同 Prompt 提示词的工作。 二、Skill 与 Prompt 的区别Prompt：临时指令，每次对话都要重写，易遗忘、占上下文。 Skill：长久指令包，可复用，不占对话空间。 三、Skill 目录文件夹...
RAG（检索、增强、生成）
RAG（检索、增强、生成） RAG（Retrieval-Augmented Generation，检索增强生成） 是一种结合了信息检索技术与语言生成模型的人工智能技术。该技术通过从外部知识库中检索相关信息，并将其作为提示（Prompt）输入给大型语言模型（LLMs），以增强模型处理知识密集型任务的能力，如问答、文本摘要、内容生成等。RAG模型由Facebook AI Research（FAIR）团队于2020年首次提出，并迅速成为大模型应用中的热门方案。 一、检索增强生成（RAG）什么是RAG？RAG（Retrieval-Augmented Generation，检索增强生成），RAG是一种 AI 框架，它将传统信息检索系统（例如数据库）的优势与生成式大语言模型 (LLM) 的功能结合在一起。 LLM通过将这些额外的知识与自己的语言技能相结合，可以撰写更准确、更具时效性且更贴合具体需求的文字。 如何理解RAG？通过上一个问题，我们知道了什么是RAG？了解到RAG是一种结合了信息检索、文本增强和文本生成的自然语言处理（NLP）的技术。 RAG的目的是通过从外部知识库检索相关信息来辅...
RAG是什么
什么是 RAG？AI 大模型有一些硬伤，比如： 知识有截止日期 会一本正经地胡说八道，也就是我们常说的幻觉 缺乏私有知识，了解不到内部的文档写了什么 比如问 DeepSeek：程序员鱼皮的最新项目是什么？ 结果它给我扯了个两年半以前的项目出来，技术栈也完全不对！ 解决这个问题就可以用 RAG。RAG 的核心思想是 先搜再答 ，让大模型在回答之前先去搜一遍相关资料，再基于搜到的知识来组织答案。 就跟考试的时候偷偷翻书一样，遇到不会的先翻一翻书，再根据书里的知识答题。 还是问 AI 同样的问题，我们主动给 AI 一些参考资料，他的回答就会准确一些： 这个思路听起来简单，但在实际工程上 RAG 已经演化出了很多种不同的实现方法，从最初的「切块 → 搜索 → 生成」，到让 AI Agent 自主决策检索策略的 Agentic RAG，复杂度和能力天差地别。 有朋友可能会问：现在的大模型不是已经支持百万 token 的上下文窗口了，还需要 RAG 吗？ 答案是：需要，而且用得比以前更多了！ 因为把所有文档塞进上下文窗口，既贵又不靠谱。上下文越长 token 费用越高，而且大模型普遍存在...
Python版本MVP范围
15. Python 版本 MVP 范围1. 目标避免 Python 版本一开始就无限扩张。MVP 只做能跑通核心闭环的最小系统。 2. MVP 必须包含2.1 主循环 多轮 query loop tool call -> tool result -> next turn 2.2 基础工具 read file write file edit file grep/search bash 2.3 基础权限系统 allow / ask / deny 被拒后不原样重试 2.4 基础 transcript / session 消息持久化 resume 会话 2.5 基础 memory 用户 / 项目记忆注入 简单记忆文件结构 2.6 基础 agent orchestration main agent 至少一个 verification agent 可选一个 explore / plan agent 2.7 基础 compact 超长消息时压缩历史 工具结果 budget 裁剪 3. MVP 可以后置的能力...