xhj的博客

02. 工具、权限与执行链需求文档1. 为什么工具系统是产品核心如果模型不能操作环境，它只是建议生成器。这个产品的目标是帮助用户推进真实工程任务，因此必须具备正式的工具系统。 2. 工具系统需求2.1 基础工具能力产品至少需要以下工具类别： 读文件 改文件 写文件 搜索文件 搜索内容 shell / 命令执行 todo / 任务管理 用户追问 启动子 agent 调用外部 MCP 工具 2.2 工具使用规范系统必须对模型明确规定工具使用优先级，避免： 用 shell 替代专用文件工具 误删或误改文件 低效重复操作 3. 权限系统需求3.1 用户控制边界用户必须能控制哪些工具自动允许，哪些要询问，哪些禁止。 3.2 权限决策来源权限决策至少可能来自： 当前模式 用户规则 项目规则 Hook 决策 特殊工具安全策略 3.3 被拒后的行为要求如果某次工具调用被拒绝，系统不能机械重试，而应： 理解拒绝信号 调整方案 必要时向用户澄清 4. 执行链路需求工具执行不能是“模型决定 -> 直接运行”。产品需要一条正式执行链： 找到工具 校验输入结构 ...

12. 工作区与隔离策略规格1. 目标不同 agent 不能默认拥有相同的文件系统权限。产品必须允许根据角色与场景控制工作区隔离。 2. 隔离模式Python 版建议至少定义： 2.1 shared workspace主线程默认工作区，共享项目目录。 2.2 read-only workspace用于探索、规划、验证等只读角色。 2.3 temp workspace用于临时脚本、临时测试产物。 2.4 worktree workspace用于隔离修改型子任务，避免污染主分支。 2.5 remote workspace用于远程执行环境（第一版可不做）。 3. 为什么隔离必须存在没有隔离会导致： 子任务互相污染 验证角色破坏项目 fork 实验影响主线程 风险动作边界模糊 4. 角色与隔离建议 Explore Agent -> read-only Plan Agent -> read-only Verification Agent -> read-only + temp writable General Agent -> shared 或 worktree...

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，...

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 是一种可复用的 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（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的目的是通过从外部知识库检索相关信息来辅...