# AI Agent # Claude-Skills-完全构建指南 ## 目录 - [简介](#%E7%AE%80%E4%BB%8B) - [第一章：基础知识](#%E7%AC%AC%E4%B8%80%E7%AB%A0%E5%9F%BA%E7%A1%80%E7%9F%A5%E8%AF%86) - [第二章：规划与设计](#%E7%AC%AC%E4%BA%8C%E7%AB%A0%E8%A7%84%E5%88%92%E4%B8%8E%E8%AE%BE%E8%AE%A1) - [第三章：测试与迭代](#%E7%AC%AC%E4%B8%89%E7%AB%A0%E6%B5%8B%E8%AF%95%E4%B8%8E%E8%BF%AD%E4%BB%A3) - [第四章：分发与共享](#%E7%AC%AC%E5%9B%9B%E7%AB%A0%E5%88%86%E5%8F%91%E4%B8%8E%E5%85%B1%E4%BA%AB) - [第五章：模式与故障排除](#%E7%AC%AC%E4%BA%94%E7%AB%A0%E6%A8%A1%E5%BC%8F%E4%B8%8E%E6%95%85%E9%9A%9C%E6%8E%92%E9%99%A4) - [第六章：资源与参考](#%E7%AC%AC%E5%85%AD%E7%AB%A0%E8%B5%84%E6%BA%90%E4%B8%8E%E5%8F%82%E8%80%83) - [参考 A：快速检查清单](#%E5%8F%82%E8%80%83-a%E5%BF%AB%E9%80%9F%E6%A3%80%E6%9F%A5%E6%B8%85%E5%8D%95) - [参考 B：YAML Frontmatter](#%E5%8F%82%E8%80%83-byaml-frontmatter) - [参考 C：完整的 Skill 示例](#%E5%8F%82%E8%80%83-c%E5%AE%8C%E6%95%B4%E7%9A%84-skill-%E7%A4%BA%E4%BE%8B) --- ## 简介 Skill 是一组指令——打包成一个简单的文件夹——用于教导 Claude 如何处理特定任务或工作流程。Skills 是根据你的特定需求定制 Claude 最强大的方式之一。你无需在每次对话中重复解释自己的偏好、流程和领域知识，Skills 让你只需教导 Claude 一次，便能每次受益。 Skills 在你拥有可重复工作流程时效果最佳：从规范中生成前端设计、使用一致方法论进行研究、按照团队风格指南创建文档，或编排多步骤流程。它们与 Claude 的内置能力（如代码执行和文档创建）协同良好。对于构建 MCP 集成的用户，Skills 提供了另一个强大层级——帮助将原始工具访问转化为可靠、优化的工作流程。 本指南涵盖构建高效 Skills 所需了解的一切内容——从规划与结构到测试与分发。无论你是为自己、团队还是社区构建 Skill，你都将在全文中找到实用模式和真实案例。 **你将学到：** - Skills 结构的技术要求和最佳实践 - 独立 Skill 和 MCP 增强工作流的模式 - 我们在不同使用场景中观察到的有效模式 - 如何测试、迭代和分发你的 Skills **适合人群：** - 希望 Claude 持续遵循特定工作流程的开发者 - 希望 Claude 遵循特定工作流程的高级用户 - 希望在组织中标准化 Claude 工作方式的团队 --- **本指南的两条路径** 构建独立 Skills？重点关注「基础知识」、「规划与设计」和第 1-2 类。增强 MCP 集成？「Skills + MCP」章节和第 3 类适合你。两条路径共享相同的技术要求，你可根据使用场景选择相关内容。 **你将从本指南中获得什么：** 读完本指南后，你将能够在单次会话中构建一个可运行的 Skill。预计使用 skill-creator 构建并测试你的第一个 Skill 约需 15-30 分钟。 让我们开始吧。 --- ## 第一章：基础知识 ### 什么是 Skill？ Skill 是一个包含以下内容的文件夹： - **SKILL.md**（必须）：带有 YAML frontmatter 的 Markdown 格式指令 - **scripts/**（可选）：可执行代码（Python、Bash 等） - **references/**（可选）：按需加载的文档 - **assets/**（可选）：输出中使用的模板、字体、图标 ### 核心设计原则 #### 递进式披露（Progressive Disclosure） Skills 使用三级系统： - **第一级（YAML frontmatter）**：始终加载到 Claude 的系统提示中。提供恰到好处的信息，让 Claude 知道何时应使用每个 Skill，而无需将全部内容加载到上下文中。 - **第二级（SKILL.md 正文）**：当 Claude 认为该 Skill 与当前任务相关时加载。包含完整的指令和指导。 - **第三级（链接文件）**：打包在 Skill 目录中的附加文件，Claude 可以按需选择浏览和发现。 这种递进式披露在保持专业能力的同时最大限度地减少了 token 消耗。 #### 可组合性（Composability） Claude 可以同时加载多个 Skills。你的 Skill 应能与其他 Skills 协同工作，而不是假设自己是唯一可用的能力。 #### 可移植性（Portability） Skills 在 Claude.ai、Claude Code 和 API 上的工作方式完全相同。创建一次，即可在所有平台使用，无需修改——前提是运行环境支持 Skill 所需的任何依赖项。 --- ### 面向 MCP 构建者：Skills + 连接器 > 💡 在没有 MCP 的情况下构建独立 Skills？跳到「规划与设计」——你随时可以回来查看这部分。 如果你已经有一个可运行的 MCP 服务器，那你已经完成了最难的部分。Skills 是顶层的知识层——捕获你已知的工作流程和最佳实践，让 Claude 能够持续地应用它们。 #### 厨房类比 MCP 提供专业厨房：工具、食材和设备的访问权限。 Skills 提供菜谱：一步步地说明如何创造有价值的成果。 两者结合，让用户无需自己摸索每一个步骤就能完成复杂任务。 #### 两者如何协作
MCP（连接性）Skills（知识）
将 Claude 连接到你的服务（Notion、Asana、Linear 等）教导 Claude 如何有效使用你的服务
提供实时数据访问和工具调用捕获工作流程和最佳实践
Claude **能做**什么Claude **应该怎么做**
#### 这对你的 MCP 用户意味着什么 **没有 Skills：** - 用户连接了你的 MCP，但不知道下一步该做什么 - 支持工单询问"我如何用你的集成做 X" - 每次对话从零开始 - 因为用户每次提示方式不同，结果不一致 - 用户将问题归咎于你的连接器，而真正的问题是工作流程指导缺失 **有了 Skills：** - 预构建的工作流程在需要时自动激活 - 一致、可靠的工具使用 - 每次交互中都嵌入了最佳实践 - 降低了你的集成的学习曲线 --- ## 第二章：规划与设计 ### 从使用场景出发 在编写任何代码之前，先确定你的 Skill 应该实现的 2-3 个具体使用场景。 **良好的使用场景定义示例：** ``` 使用场景：项目冲刺规划 触发条件：用户说"帮我规划这个冲刺"或"创建冲刺任务" 步骤： 1. 从 Linear（通过 MCP）获取当前项目状态 2. 分析团队速度和容量 3. 建议任务优先级 4. 在 Linear 中创建带有适当标签和估算的任务 结果：已规划完成的冲刺，并创建了任务 ``` **问自己：** - 用户想完成什么？ - 这需要哪些多步骤工作流程？ - 需要哪些工具（内置或 MCP）？ - 应该嵌入哪些领域知识或最佳实践？ --- ### 常见 Skill 使用场景类别 在 Anthropic，我们观察到三类常见使用场景： #### 第 1 类：文档与资产创建 **用途：** 创建一致、高质量的输出，包括文档、演示文稿、应用、设计、代码等。 **真实案例：** frontend-design skill（另见用于 docx、pptx、xlsx 和 ppt 的 Skills） > "创建具有高设计质量的独特、生产级前端界面。在构建 Web 组件、页面、artifact、海报或应用时使用。" **核心技巧：** - 内嵌样式指南和品牌标准 - 一致输出的模板结构 - 定稿前的质量检查清单 - 无需外部工具——使用 Claude 的内置能力 #### 第 2 类：工作流程自动化 **用途：** 受益于一致方法论的多步骤流程，包括跨多个 MCP 服务器的协调。 **真实案例：** skill-creator skill > "创建新 Skills 的交互式指南。引导用户完成使用场景定义、frontmatter 生成、指令编写和验证。" **核心技巧：** - 带有验证节点的分步工作流程 - 常见结构的模板 - 内置审查和改进建议 - 迭代精炼循环 #### 第 3 类：MCP 增强 **用途：** 工作流程指导，以增强 MCP 服务器提供的工具访问能力。 **真实案例：** sentry-code-review skill（来自 Sentry） > "通过 Sentry 的 MCP 服务器，使用 Sentry 错误监控数据自动分析并修复 GitHub Pull Request 中检测到的 bug。" **核心技巧：** - 按顺序协调多个 MCP 调用 - 嵌入领域专业知识 - 提供用户否则需要自行指定的上下文 - 处理常见 MCP 问题的错误处理 --- ### 定义成功标准 你如何知道你的 Skill 在正常工作？ 这些是有抱负的目标——粗略的基准，而非精确的阈值。力求严谨，但要接受其中会有一定程度的主观判断。我们正在积极开发更完善的测量指导和工具。 **量化指标：** - **Skill 在 90% 的相关查询上触发** - 测量方法：运行 10-20 个应该触发你的 Skill 的测试查询。追踪它自动加载的次数 vs. 需要显式调用的次数。 - **在 X 次工具调用内完成工作流程** - 测量方法：在启用和不启用 Skill 的情况下比较相同任务。统计工具调用次数和消耗的 token 总量。 - **每个工作流程 0 次 API 调用失败** - 测量方法：在测试运行期间监控 MCP 服务器日志。追踪重试率和错误代码。 **定性指标：** - **用户不需要提示 Claude 下一步该做什么** - 评估方法：在测试期间，记录你需要重定向或澄清的频率。向测试用户征求反馈。 - **工作流程无需用户纠正即可完成** - 评估方法：将相同请求运行 3-5 次。比较输出的结构一致性和质量。 - **跨会话结果一致** - 评估方法：新用户能否在最少指导下第一次就完成任务？ --- ### 技术要求 #### 文件结构 ``` your-skill-name/ ├── SKILL.md # 必须——主 Skill 文件 ├── scripts/ # 可选——可执行代码 │ ├── process_data.py # 示例 │ └── validate.sh # 示例 ├── references/ # 可选——文档 │ ├── api-guide.md # 示例 │ └── examples/ # 示例 └── assets/ # 可选——模板等 └── report-template.md # 示例 ``` #### 关键规则 **SKILL.md 命名：** - 必须完全命名为 `SKILL.md`（区分大小写） - 不接受任何变体（SKILL.MD、skill.md 等） **Skill 文件夹命名：** - 使用 kebab-case：`notion-project-setup` ✅ - 不使用空格：`Notion Project Setup` ❌ - 不使用下划线：`notion_project_setup` ❌ - 不使用大写：`NotionProjectSetup` ❌ **不包含 README.md：** - 不要在你的 Skill 文件夹内包含 README.md - 所有文档放在 SKILL.md 或 references/ 中 - 注意：通过 GitHub 分发时，你仍然需要在仓库级别为人类用户提供 README——参见「分发与共享」章节。 --- ### YAML Frontmatter：最重要的部分 YAML frontmatter 是 Claude 决定是否加载你的 Skill 的方式。务必把这部分做好。 **最小必要格式：** ```yaml --- name: your-skill-name description: What it does. Use when user asks to [specific phrases]. --- ``` 这就是你开始所需的全部内容。 **字段要求：** `name`（必须）： - 仅使用 kebab-case - 无空格或大写字母 - 应与文件夹名称匹配 `description`（必须）： - 必须同时包含： - 该 Skill 的功能 - 何时使用它（触发条件） - 少于 1024 个字符 - 无 XML 标签（`<` 或 `>`） - 包含用户可能说的具体任务 - 如相关，提及文件类型 `license`（可选）： - 将 Skill 开源时使用 - 常用：MIT、Apache-2.0 `compatibility`（可选）： - 1-500 个字符 - 说明环境要求：例如目标产品、所需系统包、网络访问需求等 `metadata`（可选）： - 任意自定义键值对 - 建议：author、version、mcp-server - 示例： ```yaml metadata: author: ProjectHub version: 1.0.0 mcp-server: projecthub ``` #### 安全限制 **Frontmatter 中禁止：** - XML 尖括号（`< >`） - 名称中含有 "claude" 或 "anthropic" 的 Skills（保留字） **原因：** Frontmatter 出现在 Claude 的系统提示中。恶意内容可能注入指令。 --- ### 编写高效的 Skills #### Description 字段 根据 Anthropic 工程博客的说法："这些元数据……提供恰到好处的信息，让 Claude 知道何时应使用每个 Skill，而无需将全部内容加载到上下文中。"这是递进式披露的第一级。 **结构：** ``` [它做什么] + [何时使用] + [核心能力] ``` **良好 description 的示例：** ```yaml # 好——具体且可执行 description: Analyzes Figma design files and generates developer handoff documentation. Use when user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code handoff". # 好——包含触发短语 description: Manages Linear project workflows including sprint planning, task creation, and status tracking. Use when user mentions "sprint", "Linear tasks", "project planning", or asks to "create tickets". # 好——清晰的价值主张 description: End-to-end customer onboarding workflow for PayFlow. Handles account creation, payment setup, and subscription management. Use when user says "onboard new customer", "set up subscription", or "create PayFlow account". ``` **糟糕 description 的示例：** ```yaml # 太模糊 description: Helps with projects. # 缺少触发条件 description: Creates sophisticated multi-page documentation systems. # 过于技术性，没有用户触发词 description: Implements the Project entity model with hierarchical relationships. ``` --- #### 编写主体指令 在 frontmatter 之后，用 Markdown 编写实际指令。 **推荐结构：** 根据你的 Skill 调整此模板。用你的具体内容替换括号中的部分。 ```markdown --- name: your-skill description: [...] --- # Your Skill Name ## Instructions ### Step 1: [First Major Step] Clear explanation of what happens. ```bash python scripts/fetch_data.py --project-id PROJECT_ID Expected output: [describe what success looks like] ``` (Add more steps as needed) Examples Example 1: [common scenario] User says: "Set up a new marketing campaign" Actions: 1. Fetch existing campaigns via MCP 2. Create new campaign with provided parameters Result: Campaign created with confirmation link (Add more examples as needed) Troubleshooting Error: [Common error message] Cause: [Why it happens] Solution: [How to fix] (Add more error cases as needed) ``` --- #### 指令最佳实践 **具体且可执行** ✅ 好： ``` Run `python scripts/validate.py --input {filename}` to check data format. If validation fails, common issues include: - Missing required fields (add them to the CSV) - Invalid date formats (use YYYY-MM-DD) ``` ❌ 差： ``` Validate the data before proceeding. ``` **包含错误处理** ```markdown ## Common Issues ### MCP Connection Failed If you see "Connection refused": 1. Verify MCP server is running: Check Settings > Extensions 2. Confirm API key is valid 3. Try reconnecting: Settings > Extensions > [Your Service] > Reconnect ``` **清晰引用捆绑的资源** ``` Before writing queries, consult `references/api-patterns.md` for: - Rate limiting guidance - Pagination patterns - Error codes and handling ``` **使用递进式披露** 保持 SKILL.md 专注于核心指令。将详细文档移至 `references/` 并添加链接。（参见「核心设计原则」了解三级系统的工作方式。） --- ## 第三章：测试与迭代 Skills 可以根据你的需求进行不同严格程度的测试： - **在 Claude.ai 中手动测试** - 直接运行查询并观察行为。迭代快速，无需配置。 - **在 Claude Code 中脚本化测试** - 自动化测试用例，实现跨版本的可重复验证。 - **通过 Skills API 程序化测试** - 构建评估套件，系统地针对定义的测试集运行。 根据你的质量要求和 Skill 的可见度选择合适的方法。供小团队内部使用的 Skill 与部署给数千名企业用户的 Skill，其测试需求截然不同。 > **专业建议：在扩展之前先在单一任务上迭代** > > 我们发现，最有效的 Skill 创建者会在单个具有挑战性的任务上持续迭代直到 Claude 成功，然后将成功的方法提炼成 Skill。这利用了 Claude 的上下文学习能力，比广泛测试提供更快的信号反馈。一旦有了可用的基础，再扩展到多个测试用例以提升覆盖率。 ### 推荐的测试方法 基于早期经验，有效的 Skills 测试通常涵盖三个方面： #### 1. 触发测试 **目标：** 确保你的 Skill 在正确时机加载。 **测试用例：** - ✅ 在明显任务上触发 - ✅ 在换句话的请求上触发 - ❌ 不在无关话题上触发 **示例测试套件：** ``` 应该触发： - "Help me set up a new ProjectHub workspace" - "I need to create a project in ProjectHub" - "Initialize a ProjectHub project for Q4 planning" 不应触发： - "What's the weather in San Francisco?" - "Help me write Python code" - "Create a spreadsheet" (unless ProjectHub skill handles sheets) ``` #### 2. 功能测试 **目标：** 验证 Skill 能产生正确的输出。 **测试用例：** - 生成有效的输出 - API 调用成功 - 错误处理正常工作 - 边缘情况有所覆盖 **示例：** ``` Test: Create project with 5 tasks Given: Project name "Q4 Planning", 5 task descriptions When: Skill executes workflow Then: - Project created in ProjectHub - 5 tasks created with correct properties - All tasks linked to project - No API errors ``` #### 3. 性能对比 **目标：** 证明 Skill 相比基线有所改善。 使用「定义成功标准」中的指标。以下是一个对比示例： **基线对比：** ``` Without skill: - User provides instructions each time - 15 back-and-forth messages - 3 failed API calls requiring retry - 12,000 tokens consumed With skill: - Automatic workflow execution - 2 clarifying questions only - 0 failed API calls - 6,000 tokens consumed ``` --- ### 使用 skill-creator Skill Anthropic 维护的 [`skill-creator`](https://github.com/anthropics/skills/tree/main/skills/skill-creator) Skill 可以帮助你构建和迭代 Skills。如果你有一个 MCP 服务器并了解你的 2-3 个主要工作流程，你可以在单次会话中构建并测试一个功能性 Skill——通常只需 15-30 分钟。 **创建 Skills：** - 从自然语言描述生成 Skills - 生成带有 frontmatter 的规范格式 SKILL.md - 建议触发短语和结构 **审查 Skills：** - 标记常见问题（模糊描述、缺少触发词、结构问题） - 识别潜在的过度/不足触发风险 - 根据 Skill 的目标用途建议测试用例 **迭代改进：** - 使用 Skill 过程中遇到边缘情况或失败时，将这些示例带回 skill-creator - 示例："Use the issues & solution identified in this chat to improve how the skill handles \[specific edge case\]" **使用方法：** ``` "Use the skill-creator skill to help me build a skill for [your use case]" ``` 注意：skill-creator 帮助你设计和完善 Skills，但不执行自动化测试套件或生成定量评估结果。 --- ### 基于反馈的迭代 Skills 是动态文档。计划根据以下信号进行迭代： **触发不足的信号：** - Skill 在应该加载时没有加载 - 用户手动启用它 - 关于何时使用它的支持问题 > 解决方案：在 description 中添加更多细节和针对性内容——对于技术术语，可能需要包含关键词 **过度触发的信号：** - Skill 在无关查询时加载 - 用户禁用它 - 对用途感到困惑 > 解决方案：添加负面触发词，更加具体 **执行问题：** - 结果不一致 - API 调用失败 - 需要用户纠正 > 解决方案：改进指令，添加错误处理 --- ## 第四章：分发与共享 Skills 让你的 MCP 集成更加完整。当用户比较各种连接器时，拥有 Skills 的连接器提供了更快的价值路径，让你在仅有 MCP 的替代方案中脱颖而出。 ### 当前分发模型（2026 年 1 月） **个人用户获取 Skills 的方式：** 1. 下载 Skill 文件夹 2. 压缩文件夹（如需要） 3. 通过 Claude.ai 的 Settings > Capabilities > Skills 上传 4. 或放置在 Claude Code skills 目录中 **组织级 Skills：** - 管理员可以在整个工作区部署 Skills（2025 年 12 月 18 日上线） - 自动更新 - 集中管理 ### 开放标准 我们将 Agent Skills 作为开放标准发布。与 MCP 一样，我们相信 Skills 应该可以跨工具和平台移植——无论使用 Claude 还是其他 AI 平台，同一个 Skill 都应该能够工作。也就是说，有些 Skills 被设计为充分利用特定平台的能力；作者可以在 Skill 的 `compatibility` 字段中注明这一点。我们一直在与生态系统的各方成员合作推进这一标准，并对早期采用者的积极反响感到振奋。 ### 通过 API 使用 Skills 对于程序化使用场景——如构建利用 Skills 的应用程序、智能体或自动化工作流——API 提供对 Skill 管理和执行的直接控制。 **核心能力：** - `/v1/skills` 端点，用于列举和管理 Skills - 通过 `container.skills` 参数将 Skills 添加到 Messages API 请求 - 通过 Claude Console 进行版本控制和管理 - 与 Claude Agent SDK 协同工作，用于构建自定义智能体 **何时使用 API vs. Claude.ai：**
使用场景最佳平台
终端用户直接与 Skills 交互Claude.ai / Claude Code
开发期间的手动测试和迭代Claude.ai / Claude Code
个人、临时工作流Claude.ai / Claude Code
以编程方式使用 Skills 的应用程序API
大规模生产部署API
自动化流水线和智能体系统API
注意：API 中的 Skills 需要代码执行工具（Code Execution Tool）beta 版，该工具提供了 Skills 运行所需的安全环境。 更多实现细节，请参阅： - Skills API 快速入门 - 创建自定义 Skills - Agent SDK 中的 Skills --- ### 当前推荐方法 从在 GitHub 上用公开仓库托管你的 Skill 开始，包含清晰的 README（面向人类访问者——这与你的 Skill 文件夹分开，Skill 文件夹不应包含 README.md）以及带截图的示例用法。然后在你的 MCP 文档中添加一个章节，链接到该 Skill，解释同时使用两者为何有价值，并提供快速入门指南。 **1. 在 GitHub 上托管** - 开源 Skills 使用公开仓库 - 清晰的 README，包含安装说明 - 示例用法和截图 **2. 在你的 MCP 仓库中建立文档** - 从 MCP 文档链接到 Skills - 解释同时使用两者的价值 - 提供快速入门指南 **3. 创建安装指南** ```markdown ## Installing the [Your Service] skill 1. Download the skill: - Clone repo: `git clone https://github.com/yourcompany/ skills` - Or download ZIP from Releases 2. Install in Claude: - Open Claude.ai > Settings > skills - Click "Upload skill" - Select the skill folder (zipped) 3. Enable the skill: - Toggle on the [Your Service] skill - Ensure your MCP server is connected 4. Test: - Ask Claude: "Set up a new project in [Your Service]" ``` ### 定位你的 Skill 你描述 Skill 的方式决定了用户是否理解其价值并真正尝试使用它。在 README、文档或推广材料中介绍你的 Skill 时，请遵循以下原则： **聚焦结果，而非功能：** ✅ 好： ``` "The ProjectHub skill enables teams to set up complete project workspaces in seconds — including pages, databases, and templates — instead of spending 30 minutes on manual setup." ``` ❌ 差： ``` "The ProjectHub skill is a folder containing YAML frontmatter and Markdown instructions that calls our MCP server tools." ``` **突出 MCP + Skills 的组合：** ``` "Our MCP server gives Claude access to your Linear projects. Our skills teach Claude your team's sprint planning workflow. Together, they enable AI-powered project management." ``` --- ## 第五章：模式与故障排除 这些模式来自早期采用者和内部团队创建的 Skills。它们代表了我们观察到的常见有效方法，而非规定性模板。 ### 选择方法：问题优先 vs. 工具优先 把它想象成家得宝（Home Depot）。你可能带着一个问题走进去——"我需要修厨房橱柜"——然后员工引导你找到合适的工具。或者你可能挑好了一把新电钻，然后询问如何用它完成你的特定工作。 Skills 的工作方式相同： - **问题优先**："我需要设置一个项目工作区" → 你的 Skill 按正确顺序编排合适的 MCP 调用。用户描述结果；Skill 处理工具。 - **工具优先**："我已连接了 Notion MCP" → 你的 Skill 教导 Claude 最优工作流程和最佳实践。用户拥有访问权限；Skill 提供专业知识。 大多数 Skills 偏向某一方向。了解哪种框架适合你的使用场景，有助于你选择下方合适的模式。 --- ### 模式 1：顺序工作流程编排 **适用场景：** 用户需要按特定顺序执行的多步骤流程。 **示例结构：** ```markdown ## Workflow: Onboard New Customer ### Step 1: Create Account Call MCP tool: `create_customer` Parameters: name, email, company ### Step 2: Setup Payment Call MCP tool: `setup_payment_method` Wait for: payment method verification ### Step 3: Create Subscription Call MCP tool: `create_subscription` Parameters: plan_id, customer_id (from Step 1) ### Step 4: Send Welcome Email Call MCP tool: `send_email` Template: welcome_email_template ``` **核心技巧：** - 明确的步骤顺序 - 步骤间的依赖关系 - 每个阶段的验证 - 失败时的回滚指令 --- ### 模式 2：多 MCP 协调 **适用场景：** 工作流程跨越多个服务。 **示例：** 设计到开发的交接 ```markdown ### Phase 1: Design Export (Figma MCP) 1. Export design assets from Figma 2. Generate design specifications 3. Create asset manifest ### Phase 2: Asset Storage (Drive MCP) 1. Create project folder in Drive 2. Upload all assets 3. Generate shareable links ### Phase 3: Task Creation (Linear MCP) 1. Create development tasks 2. Attach asset links to tasks 3. Assign to engineering team ### Phase 4: Notification (Slack MCP) 1. Post handoff summary to #engineering 2. Include asset links and task references ``` **核心技巧：** - 清晰的阶段划分 - MCP 之间的数据传递 - 进入下一阶段前的验证 - 集中的错误处理 --- ### 模式 3：迭代精炼 **适用场景：** 输出质量随迭代提升。 **示例：** 报告生成 ```markdown ## Iterative Report Creation ### Initial Draft 1. Fetch data via MCP 2. Generate first draft report 3. Save to temporary file ### Quality Check 1. Run validation script: `scripts/check_report.py` 2. Identify issues: - Missing sections - Inconsistent formatting - Data validation errors ### Refinement Loop 1. Address each identified issue 2. Regenerate affected sections 3. Re-validate 4. Repeat until quality threshold met ### Finalization 1. Apply final formatting 2. Generate summary 3. Save final version ``` **核心技巧：** - 明确的质量标准 - 迭代改进 - 验证脚本 - 知道何时停止迭代 --- ### 模式 4：上下文感知工具选择 **适用场景：** 相同的结果，根据上下文使用不同的工具。 **示例：** 文件存储 ```markdown ## Smart File Storage ### Decision Tree 1. Check file type and size 2. Determine best storage location: - Large files (>10MB): Use cloud storage MCP - Collaborative docs: Use Notion/Docs MCP - Code files: Use GitHub MCP - Temporary files: Use local storage ### Execute Storage Based on decision: - Call appropriate MCP tool - Apply service-specific metadata - Generate access link ### Provide Context to User Explain why that storage was chosen ``` **核心技巧：** - 清晰的决策标准 - 备选方案 - 关于选择的透明度 --- ### 模式 5：领域特定智能 **适用场景：** 你的 Skill 在工具访问之外增加了专业知识。 **示例：** 金融合规 ```markdown ## Payment Processing with Compliance ### Before Processing (Compliance Check) 1. Fetch transaction details via MCP 2. Apply compliance rules: - Check sanctions lists - Verify jurisdiction allowances - Assess risk level 3. Document compliance decision ### Processing IF compliance passed: - Call payment processing MCP tool - Apply appropriate fraud checks - Process transaction ELSE: - Flag for review - Create compliance case ### Audit Trail - Log all compliance checks - Record processing decisions - Generate audit report ``` **核心技巧：** - 逻辑中嵌入领域专业知识 - 行动前先合规 - 全面的文档记录 - 清晰的治理 --- ### 故障排除 #### Skill 无法上传 **错误："Could not find SKILL.md in uploaded folder"** 原因：文件没有完全命名为 SKILL.md 解决方案： - 重命名为 SKILL.md（区分大小写） - 用 `ls -la` 验证，应显示 SKILL.md --- **错误："Invalid frontmatter"** 原因：YAML 格式问题 常见错误： ```yaml # 错误——缺少分隔符 name: my-skill description: Does things # 错误——未闭合的引号 name: my-skill description: "Does things # 正确 --- name: my-skill description: Does things --- ``` --- **错误："Invalid skill name"** 原因：名称含有空格或大写字母 ```yaml # 错误 name: My Cool Skill # 正确 name: my-cool-skill ``` --- #### Skill 不触发 **症状：** Skill 从不自动加载 **修复：** 修改你的 description 字段。参见「Description 字段」章节中的好/坏示例。 **快速检查清单：** - 是否太通用？（"Helps with projects" 无效） - 是否包含用户实际会说的触发短语？ - 如果适用，是否提及了相关文件类型？ **调试方法：** 询问 Claude："When would you use the \[skill name\] skill?" Claude 会引用 description 内容。根据缺失的内容进行调整。 --- #### Skill 触发过于频繁 **症状：** Skill 在无关查询时加载 **解决方案：** **1. 添加负面触发词** ```yaml description: Advanced data analysis for CSV files. Use for statistical modeling, regression, clustering. Do NOT use for simple data exploration (use data-viz skill instead). ``` **2. 更加具体** ```yaml # 太宽泛 description: Processes documents # 更具体 description: Processes PDF legal documents for contract review ``` **3. 明确范围** ```yaml description: PayFlow payment processing for e-commerce. Use specifically for online payment workflows, not for general financial queries. ``` --- #### MCP 连接问题 **症状：** Skill 加载但 MCP 调用失败 **检查清单：** 1. 验证 MCP 服务器是否已连接 - Claude.ai：Settings > Extensions > \[你的服务\] - 应显示"Connected"状态 2. 检查身份验证 - API 密钥有效且未过期 - 已授予正确的权限/范围 - OAuth token 已刷新 3. 独立测试 MCP - 让 Claude 直接调用 MCP（不使用 Skill） - "Use \[Service\] MCP to fetch my projects" - 如果这也失败，问题在 MCP 而非 Skill 4. 验证工具名称 - Skill 引用了正确的 MCP 工具名称 - 检查 MCP 服务器文档 - 工具名称区分大小写 --- #### 指令未被遵循 **症状：** Skill 加载但 Claude 不遵循指令 **常见原因：** 1. 指令太冗长 - 保持指令简洁 - 使用项目符号和编号列表 - 将详细参考内容移至单独文件 2. 指令被埋没 - 将关键指令放在最前面 - 使用 `## Important` 或 `## Critical` 标题 - 如有必要，重复关键要点 3. 语言模糊 ```markdown # 差 Make sure to validate things properly # 好 CRITICAL: Before calling create_project, verify: - Project name is non-empty - At least one team member assigned - Start date is not in the past ``` **高级技巧：** 对于关键验证，考虑打包一个以编程方式执行检查的脚本，而不是依赖语言指令。代码是确定性的；语言解读则不然。参见 Office skills 了解此模式的示例。 4. 模型"偷懒" 添加明确的鼓励： ```markdown ## Performance Notes - Take your time to do this thoroughly - Quality is more important than speed - Do not skip validation steps ``` 注意：将此内容添加到用户提示中比放在 SKILL.md 中更有效。 --- #### 大上下文问题 **症状：** Skill 看起来变慢或响应质量下降 **原因：** - Skill 内容太大 - 同时启用的 Skills 太多 - 所有内容被加载而非递进式披露 **解决方案：** 1. 优化 SKILL.md 大小 - 将详细文档移至 references/ - 链接引用而非内联 - 将 SKILL.md 控制在 5,000 字以内 2. 减少启用的 Skills 数量 - 评估是否同时启用了超过 20-50 个 Skills - 建议选择性启用 - 考虑将相关能力打包成 Skill "套件" --- ## 第六章：资源与参考 如果你在构建第一个 Skill，从最佳实践指南开始，然后根据需要参考 API 文档。 ### 官方文档 **Anthropic 资源：** - 最佳实践指南 - Skills 文档 - API 参考 - MCP 文档 **博客文章：** - Introducing Agent Skills - Engineering Blog: Equipping Agents for the Real World - Skills Explained - How to Create Skills for Claude - Building Skills for Claude Code - Improving Frontend Design through Skills ### 示例 Skills **公开 Skills 仓库：** - GitHub：anthropics/skills - 包含 Anthropic 创建的可供定制的 Skills ### 工具与实用程序 **skill-creator skill：** - 内置于 Claude.ai 并可用于 Claude Code - 可以从描述生成 Skills - 提供审查和建议 - 使用方法："Help me build a skill using skill-creator" **验证：** - skill-creator 可以评估你的 Skills - 询问："Review this skill and suggest improvements" ### 获取支持 **技术问题：** - 一般问题：Claude Developers Discord 社区论坛 **Bug 报告：** - GitHub Issues：anthropics/skills/issues - 请包含：Skill 名称、错误信息、复现步骤 --- ## 参考 A：快速检查清单 使用此检查清单在上传前后验证你的 Skill。如果你想更快上手，可以使用 skill-creator skill 生成初稿，然后通过此清单确保没有遗漏任何内容。 ### 开始之前 - [ ] 已确定 2-3 个具体使用场景 - [ ] 已确定所需工具（内置或 MCP） - [ ] 已阅读本指南和示例 Skills - [ ] 已规划文件夹结构 ### 开发过程中 - [ ] 文件夹以 kebab-case 命名 - [ ] SKILL.md 文件存在（拼写准确） - [ ] YAML frontmatter 有 `---` 分隔符 - [ ] `name` 字段：kebab-case，无空格，无大写字母 - [ ] `description` 包含功能描述（WHAT）和使用时机（WHEN） - [ ] 无 XML 标签（`< >`） - [ ] 指令清晰且可执行 - [ ] 包含错误处理 - [ ] 提供了示例 - [ ] 引用已清晰链接 ### 上传之前 - [ ] 已测试在明显任务上的触发 - [ ] 已测试在换句话请求上的触发 - [ ] 已验证不会在无关话题上触发 - [ ] 功能测试通过 - [ ] 工具集成正常工作（如适用） - [ ] 已压缩为 .zip 文件 ### 上传之后 - [ ] 在真实对话中测试 - [ ] 监控触发不足/过度触发情况 - [ ] 收集用户反馈 - [ ] 迭代 description 和指令 - [ ] 在 metadata 中更新版本号 --- ## 参考 B：YAML Frontmatter ### 必填字段 ```yaml --- name: skill-name-in-kebab-case description: What it does and when to use it. Include specific trigger phrases. --- ``` ### 所有可选字段 ```yaml name: skill-name description: [required description] license: MIT # 可选：开源许可证 allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch" # 可选：限制工具访问 metadata: # 可选：自定义字段 author: Company Name version: 1.0.0 mcp-server: server-name category: productivity tags: [project-management, automation] documentation: https://example.com/docs support: support@example.com ``` ### 安全说明 **允许：** - 任何标准 YAML 类型（字符串、数字、布尔值、列表、对象） - 自定义 metadata 字段 - 较长的 description（最多 1024 个字符） **禁止：** - XML 尖括号（`< >`）——安全限制 - YAML 中的代码执行（使用安全 YAML 解析） - 以 "claude" 或 "anthropic" 为前缀命名的 Skills（保留字） --- ## 参考 C：完整的 Skill 示例 完整的、生产就绪的 Skills 演示了本指南中的各种模式，请参阅： - **Document Skills** - PDF、DOCX、PPTX、XLSX 创建 - **Example Skills** - 各种工作流程模式 - **Partner Skills Directory** - 查看来自各合作伙伴的 Skills，包括 Asana、Atlassian、Canva、Figma、Sentry、Zapier 等 这些仓库持续更新，并包含本指南之外的更多示例。克隆它们，根据你的使用场景进行修改，并将其作为模板使用。 # Claude Code Skills 实战经验 Skills 已经成为 Claude Code 中使用最广泛的扩展点（extension points）之一。它们灵活、容易制作，分发起来也很简单。 但也正因为太灵活，你很难知道怎样用才最好。什么类型的 Skills 值得做？写出好 Skill 的秘诀是什么？什么时候该把它们分享给别人？ 我们在 Anthropic 内部大量使用 Claude Code 的 Skills（技能扩展），目前活跃使用的已经有几百个。以下就是我们在用 Skills 加速开发过程中总结出的经验。 ## 什么是 Skills？ 如果你还不了解 Skills，建议先看看[我们的文档](https://code.claude.com/docs/en/skills)或最新的 [Skilljar 上关于 Agent Skills 的课程](https://anthropic.skilljar.com/introduction-to-agent-skills)，本文假设你已经对 Skills 有了基本的了解。 我们经常听到一个误解，认为 Skills"只不过是 markdown 文件"。但 Skills 最有意思的地方恰恰在于它们不只是文本文件——它们是文件夹，可以包含脚本、资源文件、数据等等，智能体可以发现、探索和使用这些内容。 在 Claude Code 中，Skills 还拥有[丰富的配置选项](https://code.claude.com/docs/en/skills#frontmatter-reference)，包括注册动态钩子（hooks）。 我们发现，Claude Code 中最有意思的那些 Skills，往往就是创造性地利用了这些配置选项和文件夹结构。 在梳理了我们所有的 Skills 之后，我们注意到它们大致可以归为几个反复出现的类别。最好的 Skills 清晰地落在某一个类别里；让人困惑的 Skills 往往横跨了好几个。这不是一份终极清单，但如果你想检查团队里是否还缺了什么类型的 Skills，这是一个很好的思路。 ## 九种 Skill 类型 ![](https://pbs.twimg.com/media/HDo5BLyXEAA8McR?format=jpg&name=large) ### 1. 库与 API 参考 帮助你正确使用某个库、命令行工具或 SDK 的 Skills。它们既可以针对内部库，也可以针对 Claude Code 偶尔会犯错的常用库。这类 Skills 通常会包含一个参考代码片段的文件夹，以及一份 Claude 在写代码时需要避免的踩坑点（gotchas）列表。 示例： - `billing-lib` — 你的内部计费库：边界情况、容易踩的坑（footguns）等 - `internal-platform-cli` — 内部 CLI 工具的每个子命令及其使用场景示例 - `frontend-design` — 让 Claude 更好地理解你的设计系统 ### 2. 产品验证 描述如何测试或验证代码是否正常工作的 Skills。通常会搭配 Playwright、tmux 等外部工具来完成验证。 验证类 Skills 对于确保 Claude 输出的正确性非常有用。值得安排一个工程师花上一周时间专门打磨你的验证 Skills。 可以考虑一些技巧，比如让 Claude 录制输出过程的视频，这样你就能看到它到底测试了什么；或者在每一步强制执行程序化的状态断言。这些通常通过在 Skill 中包含各种脚本来实现。 示例： - `signup-flow-driver` — 在无头浏览器中跑完注册→邮件验证→引导流程，每一步都可以插入状态断言的钩子 - `checkout-verifier` — 用 Stripe 测试卡驱动结账 UI，验证发票最终是否到了正确的状态 - `tmux-cli-driver` — 针对需要 TTY 的交互式命令行测试 ### 3. 数据获取与分析 连接你的数据和监控体系的 Skills。这类 Skills 可能会包含带有凭证的数据获取库、特定的仪表盘 ID 等，以及常用工作流和数据获取方式的说明。 示例： - `funnel-query` — "要看注册→激活→付费的转化，需要关联哪些事件？"，再加上真正存放规范 user\_id 的那张表 - `cohort-compare` — 对比两个用户群的留存或转化率，标记统计显著的差异，链接到分群定义 - `grafana` — 数据源 UID、集群名称、问题→仪表盘对照表 ### 4. 业务流程与团队自动化 把重复性工作流自动化为一条命令的 Skills。这类 Skills 通常指令比较简单，但可能会依赖其他 Skills 或 MCP（Model Context Protocol，模型上下文协议）。对于这类 Skills，把之前的执行结果保存在日志文件中，有助于模型保持一致性并反思之前的执行情况。 示例： - `standup-post` — 汇总你的任务追踪器、GitHub 活动和之前的 Slack 消息→生成格式化的站会汇报，只报变化部分（delta-only） - `create--ticket` — 强制执行 schema（合法的枚举值、必填字段）加上创建后的工作流（通知审查者、在 Slack 中发链接） - `weekly-recap` — 已合并的 PR + 已关闭的工单 + 部署记录→格式化的周报 ### 5. 代码脚手架与模板 为代码库中的特定功能生成框架样板代码（boilerplate）的 Skills。你可以把这些 Skills 和脚本组合使用。当你的脚手架（scaffolding）有自然语言需求、无法纯靠代码覆盖时，这类 Skills 特别有用。 示例： - `new--workflow` — 用你的注解搭建新的服务/工作流/处理器 - `new-migration` — 你的数据库迁移文件模板加上常见踩坑点 - `create-app` — 新建内部应用，预配好你的认证、日志和部署配置 ### 6. 代码质量与审查 在团队内部执行代码质量标准并辅助代码审查的 Skills。可以包含确定性的脚本或工具来保证最大的可靠性。你可能希望把这些 Skills 作为钩子的一部分自动运行，或者放在 GitHub Action 中执行。 示例： - `adversarial-review` — 生成一个全新视角的子智能体来挑刺，实施修复，反复迭代直到发现的问题退化为吹毛求疵。子智能体（subagent）是指 Claude Code 在执行任务时启动的另一个独立 Claude 实例。这里的做法是让一个"没见过这段代码"的新实例来做代码审查，避免原实例的思维惯性。 - `code-style` — 强制执行代码风格，特别是那些 Claude 默认做不好的风格 - `testing-practices` — 关于如何写测试以及测试什么的指导 ### 7. CI/CD 与部署 帮你拉取、推送和部署代码的 Skills。这类 Skills 可能会引用其他 Skills 来收集数据。 示例： - `babysit-pr` — 监控一个 PR→重试不稳定的 CI→解决合并冲突→启用自动合并 - `deploy-` — 构建→冒烟测试→渐进式流量切换并对比错误率→指标恶化时自动回滚 - `cherry-pick-prod` — 隔离的工作树（worktree）→cherry-pick→解决冲突→用模板创建 PR ### 8. 运维手册 接收一个现象（比如一条 Slack 消息、一条告警或者一个错误特征），引导你走完多工具排查流程，最后生成结构化报告的 Skills。 示例： - `-debugging` — 把现象对应到工具→查询模式，覆盖你流量最大的服务 - `oncall-runner` — 拉取告警→检查常见嫌疑→格式化输出排查结论 - `log-correlator` — 给定一个请求 ID，从所有可能经过的系统中拉取匹配的日志 ### 9. 基础设施运维 执行日常维护和运维操作的 Skills——其中一些涉及破坏性操作，需要安全护栏。这些 Skills 让工程师在执行关键操作时更容易遵循最佳实践。 示例： - `-orphans` — 找到孤立的 Pod/Volume→发到 Slack→等待观察→用户确认→级联清理 - `dependency-management` — 你所在组织的依赖审批工作流 - `cost-investigation` — "我们的存储/出口带宽费用为什么突然涨了"，附带具体的存储桶和查询模式 ## 编写技巧 ![](https://pbs.twimg.com/media/HDo5Dl9XsAAWY7o?format=jpg&name=large) 确定了要做什么 Skill 之后，怎么写呢？以下是我们总结的一些最佳实践和技巧。 我们最近还发布了 [Skill Creator](https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills)，让在 Claude Code 中创建 Skills 变得更加简单。 ### 不要说显而易见的事 Claude Code 对你的代码库已经非常了解，Claude 本身对编程也很在行，包括很多默认的观点。如果你发布的 Skill 主要是提供知识，那就把重点放在能打破 Claude 常规思维模式的信息上。 [`frontend design` 这个 Skill](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md) 就是一个很好的例子——它是 Anthropic 的一位工程师通过与用户反复迭代、改进 Claude 的设计品味而构建的，专门避免那些典型的套路，比如 Inter 字体和紫色渐变。 ### 建一个踩坑点章节 ![](https://pbs.twimg.com/media/HDo5GDjbEAMAlZj?format=jpg&name=large) 任何 Skill 中信息量最大的部分就是踩坑点章节。这些章节应该根据 Claude 在使用你的 Skill 时遇到的常见失败点逐步积累起来。理想情况下，你会持续更新 Skill 来记录这些踩坑点。 ### 利用文件系统与渐进式披露 ![](https://pbs.twimg.com/media/HDo5JN1WQAAPmnG?format=jpg&name=large) 就像前面说的，Skill 是一个文件夹，不只是一个 markdown 文件。你应该把整个文件系统当作上下文工程（Context Engineering）和渐进式披露（progressive disclosure）的工具。告诉 Claude 你的 Skill 里有哪些文件，它会在合适的时候去读取它们。 上下文工程（Context Engineering）是 2025 年由 Andrej Karpathy 等人提出并广泛传播的概念，指的是精心设计和管理输入给大语言模型的上下文信息，以最大化模型的输出质量。渐进式披露（progressive disclosure）借用了 UI 设计中的概念，意思是不一次性把所有信息塞给模型，而是让它在需要时再去读取，从而节省上下文窗口空间。 最简单的渐进式披露形式是指向其他 markdown 文件让 Claude 使用。例如，你可以把详细的函数签名和用法示例拆分到 `references/api.md` 里。 另一个例子：如果你的最终输出是一个 markdown 文件，你可以在 `assets/` 中放一个模板文件供复制使用。 你可以有参考资料、脚本、示例等文件夹，帮助 Claude 更高效地工作。 ### 不要把 Claude 限制得太死 Claude 通常会努力遵循你的指令，而由于 Skills 的复用性很强，你需要注意不要把指令写得太具体。给 Claude 它需要的信息，但留给它适应具体情况的灵活性。 ![](https://pbs.twimg.com/media/HDo5Lo1W8AArlpo?format=jpg&name=large) ### 考虑好初始设置 ![](https://pbs.twimg.com/media/HDo5OrObEAAENZA?format=jpg&name=large) 有些 Skills 可能需要用户提供上下文来完成初始设置。例如，如果你做了一个把站会内容发到 Slack 的 Skill，你可能希望 Claude 先问用户要发到哪个 Slack 频道。 一个好的做法是把这些设置信息存在 Skill 目录下的 `config.json` 文件里。如果配置还没设置好，智能体就会向用户询问相关信息。 如果你希望智能体向用户展示结构化的多选题，可以让 Claude 使用 `AskUserQuestion` 工具。 ### description 字段是给模型看的 当 Claude Code 启动一个会话时，它会构建一份所有可用 Skills 及其描述的清单。Claude 通过扫描这份清单来判断"这个请求有没有对应的 Skill？"所以 `description` 字段不是摘要——它描述的是**何时该触发这个 Skill**。 这条建议经常被忽略。很多人写 description 时会写"这个 Skill 做什么"，但 Claude 需要的是"什么情况下该用这个 Skill"。好的 description 读起来更像 if-then 条件，而不是功能说明。 ![](https://pbs.twimg.com/media/HDo5Rspa0AApYXU?format=jpg&name=large) ### 记忆与数据存储 ![](https://pbs.twimg.com/media/HDo5UrhbEAAqlvQ?format=jpg&name=large) 有些 Skills 可以通过在内部存储数据来实现某种形式的记忆。你可以用最简单的方式——一个只追加写入的文本日志文件或 JSON 文件，也可以用更复杂的方式——比如 SQLite 数据库。 例如，一个 `standup-post` Skill 可以保留一份 `standups.log`，记录它写过的每一条站会汇报。这样下次运行时，Claude 会读取自己的历史记录，就能知道从昨天到现在发生了什么变化。 存在 Skill 目录下的数据可能会在升级 Skill 时被删除，因此持久数据应保存在 Skill 目录之外、由用户明确选择的稳定位置，并在配置中记录该路径。 ### 存储脚本与生成代码 你能给 Claude 的最强大的工具之一就是代码。给 Claude 提供脚本和库，让它把精力花在组合编排上——决定下一步做什么，而不是重新构造样板代码。 例如，在你的数据科学 Skill 中，你可以放一组从事件源获取数据的函数库。为了让 Claude 做更复杂的分析，你可以提供一组辅助函数，像这样： ![](https://pbs.twimg.com/media/HDo5XLwXcAA-ocz?format=jpg&name=large) Claude 就可以即时生成脚本来组合这些功能，完成更高级的分析——比如回答"周二发生了什么？"这样的问题。 ![](https://pbs.twimg.com/media/HDo5ZkUW0AAMmfP?format=jpg&name=large) ### 按需钩子 Skills 可以包含只在该 Skill 被调用时才激活的钩子（On Demand Hooks），并且在整个会话期间保持生效。这适合那些比较主观、你不想一直运行但有时候极其有用的钩子。 例如： - `/careful` — 通过 `PreToolUse` 匹配器拦截 Bash 中的 `rm -rf`、`DROP TABLE`、force-push、`kubectl delete`。你只在知道自己在操作生产环境时才需要这个——要是一直开着会让你抓狂。PreToolUse 是 Claude Code 的钩子（hook）机制之一，会在 Claude 每次调用工具之前触发。你可以在这个钩子里检查 Claude 即将执行的命令，如果命中危险操作就阻止执行。这里 `/careful` 是一个按需激活的 Skill，只有用户主动调用时才会注册这个钩子。 - `/freeze` — 阻止对特定目录之外的任何 Edit/Write 操作。在调试时特别有用："我想加日志但老是不小心'修'了不相关的代码" --- ## 团队分发 Skills 最大的好处之一就是你可以把它们分享给团队的其他人。 最直接的分享方式是把 Skills 提交到代码仓库的 `.agents/skills/` 中，让项目成员和兼容客户端共同使用；跨项目复用时，也可以通过独立 Git 仓库或压缩包分发到用户级 Skills 目录。无论采用哪种方式，都应在正式分发前检查重复内容、来源、权限和实际评测结果。 ### 组合 Skills 你可能希望 Skills 之间互相依赖。例如，你可能有一个文件上传 Skill 用来上传文件，以及一个 CSV 生成 Skill 用来生成 CSV 并上传。Agent Skills 规范目前没有定义 Skill 间的依赖管理；可以在说明中引用其他 Skill，但需要明确前置条件，并为缺少依赖的情况提供替代路径。 ### 衡量 Skills 的效果 为了了解一个 Skill 的表现，我们使用了一个 `PreToolUse` 钩子来在公司内部记录 Skill 的使用情况（[示例代码在这里](https://gist.github.com/ThariqS/24defad423d701746e23dc19aace4de5)）。这样我们就能发现哪些 Skills 很受欢迎，或者哪些触发频率低于预期。 ## 结语 Skills 是 AI 智能体（AI Agent）极其强大且灵活的工具，但这一切还处于早期阶段，我们都在摸索怎样用好它们。 与其把这篇文章当作权威指南，不如把它看作我们实践中验证过有效的一堆实用技巧合集。理解 Skills 最好的方式就是动手开始做、不断试验、看看什么对你管用。我们大多数 Skills 一开始就是几行文字加一个踩坑点，后来因为大家不断补充 Claude 遇到的新边界情况，才慢慢变好的。 希望这篇文章对你有帮助，如果有任何问题欢迎告诉我。 # Agent Skill 五种设计模式 说到 `SKILL.md`，开发者往往执着于格式问题——把 YAML 写对、组织好目录结构、遵循规范。但随着超过 30 种 Agent 工具（如 Claude Code、Gemini CLI、Cursor）都在向同一套目录结构靠拢，格式问题已基本成为历史。 现在真正的挑战是**内容设计**。规范告诉你如何打包一个 Skill，却对如何组织其中的逻辑毫无指导。举个例子：一个封装 FastAPI 规范的 Skill，和一个四步文档生成流水线，从外部看 `SKILL.md` 文件几乎一模一样，但它们的运作方式截然不同。 通过研究整个生态系统中 Skill 的构建方式——从 Anthropic 的代码库到 Vercel 和 Google 的内部指南——我们总结出了五种反复出现的设计模式，帮助开发者构建更可靠的 Agent。 本文将结合可运行的 ADK 代码，逐一介绍每种模式： - **工具封装（Tool Wrapper）**：让你的 Agent 瞬间成为任意库的专家 - **生成器（Generator）**：从可复用模板生成结构化文档 - **审查器（Reviewer）**：按严重程度对照清单评审代码 - **反转（Inversion）**：Agent 先采访你，再开始行动 - **流水线（Pipeline）**：强制执行带检查点的严格多步骤工作流 ![alt text](../assets/media/5pattern01.png) ## 模式一：工具封装（Tool Wrapper） 工具封装让你的 Agent 能够按需获取特定库的上下文。与其把 API 规范硬编码进系统提示，不如将它们打包成一个 Skill。Agent 只在真正需要使用该技术时才加载这些上下文。 ![alt text](../assets/media/5pattern02.png) 这是最简单的实现模式。`SKILL.md` 文件监听用户提示中的特定库关键词，从 `references/` 目录动态加载内部文档，并将这些规则作为绝对准则应用。这正是你向团队开发者工作流中分发内部编码规范或特定框架最佳实践的机制。 下面是一个工具封装示例，教 Agent 如何编写 FastAPI 代码。注意指令明确告诉 Agent 只在开始审查或编写代码时才加载 `conventions.md`： ```text # skills/api-expert/SKILL.md --- name: api-expert description: FastAPI 开发最佳实践与规范。在构建、审查或调试 FastAPI 应用、REST API 或 Pydantic 模型时使用。 metadata: pattern: tool-wrapper domain: fastapi --- 你是 FastAPI 开发专家。将以下规范应用于用户的代码或问题。 ## 核心规范 加载 'references/conventions.md' 获取完整的 FastAPI 最佳实践列表。 ## 审查代码时 1. 加载规范参考文件 2. 对照每条规范检查用户代码 3. 对于每处违规，引用具体规则并给出修复建议 ## 编写代码时 1. 加载规范参考文件 2. 严格遵循每条规范 3. 为所有函数签名添加类型注解 4. 使用 Annotated 风格进行依赖注入 ``` ## 模式二：生成器（Generator） 工具封装负责应用知识，而生成器负责强制输出一致性。如果你苦恼于 Agent 每次生成的文档结构都不一样，生成器通过编排"填空"流程来解决这个问题。 ![](../assets/media/5pattern03.png) 它利用两个可选目录：`assets/` 存放输出模板，`references/` 存放风格指南。指令充当项目经理的角色，告诉 Agent 加载模板、读取风格指南、向用户询问缺失的变量，然后填充文档。这对于生成可预期的 API 文档、标准化提交信息或搭建项目架构非常实用。 在这个技术报告生成器示例中，Skill 文件本身不包含实际的布局或语法规则，它只是协调这些资源的检索，并强制 Agent 逐步执行： ```text # skills/report-generator/SKILL.md --- name: report-generator description: 生成 Markdown 格式的结构化技术报告。当用户要求撰写、创建或起草报告、摘要或分析文档时使用。 metadata: pattern: generator output-format: markdown --- 你是一个技术报告生成器。严格按照以下步骤执行： 第一步：加载 'references/style-guide.md' 获取语气和格式规则。 第二步：加载 'assets/report-template.md' 获取所需的输出结构。 第三步：向用户询问填充模板所需的缺失信息： - 主题或议题 - 关键发现或数据点 - 目标受众（技术人员、管理层、普通读者） 第四步：按照风格指南规则填充模板。模板中的每个章节都必须出现在输出中。 第五步：以单个 Markdown 文档的形式返回完成的报告。 ``` ## 模式三：审查器（Reviewer） 审查器模式将"检查什么"与"如何检查"分离开来。与其在系统提示中罗列每一种代码坏味道，不如将模块化的评审标准存储在 `references/review-checklist.md` 文件中。 ![](../assets/media/5pattern04.png) 当用户提交代码时，Agent 加载这份清单并系统地对提交内容评分，按严重程度分组整理发现的问题。如果你把 Python 风格清单换成 OWASP 安全清单，使用完全相同的 Skill 基础设施，就能得到一个完全不同的专项审计工具。这是自动化 PR 审查或在人工审查前捕获漏洞的高效方式。 下面的代码审查器 Skill 展示了这种分离。指令保持静态，但 Agent 从外部清单动态加载具体的审查标准，并强制输出结构化的、按严重程度分级的结果： ```text # skills/code-reviewer/SKILL.md --- name: code-reviewer description: 审查 Python 代码的质量、风格和常见 Bug。当用户提交代码请求审查、寻求代码反馈或需要代码审计时使用。 metadata: pattern: reviewer severity-levels: error,warning,info --- 你是一名 Python 代码审查员。严格遵循以下审查流程： 第一步：加载 'references/review-checklist.md' 获取完整的审查标准。 第二步：仔细阅读用户的代码。在批评之前先理解其目的。 第三步：将清单中的每条规则应用于代码。对于发现的每处违规： - 记录行号（或大致位置） - 分类严重程度：error（必须修复）、warning（应该修复）、info（建议考虑） - 解释为什么这是问题，而不仅仅是说明是什么问题 - 给出包含修正代码的具体修复建议 第四步：生成包含以下章节的结构化审查报告： - **摘要**：代码的功能描述，整体质量评估 - **发现**：按严重程度分组（先列 error，再列 warning，最后列 info） - **评分**：1-10 分，附简短说明 - **三大建议**：最具影响力的改进措施 ``` ## 模式四：反转（Inversion） Agent 天生倾向于立即猜测并生成内容。反转模式颠覆了这一动态。不再是用户驱动提示、Agent 执行，而是让 Agent 扮演采访者的角色。 ![](../assets/media/5Pattern05.png) 反转依赖明确的、不可绕过的门控指令（如"在所有阶段完成之前不得开始构建"），强制 Agent 先收集上下文。它按顺序提出结构化问题，等待你的回答后再进入下一阶段。在获得完整的需求和部署约束全貌之前，Agent 拒绝综合最终输出。 来看这个项目规划器 Skill。关键要素是严格的阶段划分，以及明确阻止 Agent 在收集完所有用户回答之前综合最终计划的门控提示： ```text # skills/project-planner/SKILL.md --- name: project-planner description: 通过结构化提问收集需求，然后生成计划，从而规划新软件项目。当用户说"我想构建"、"帮我规划"、"设计一个系统"或"启动新项目"时使用。 metadata: pattern: inversion interaction: multi-turn --- 你正在进行一次结构化需求访谈。在所有阶段完成之前，不得开始构建或设计。 ## 第一阶段——问题发现（每次只问一个问题，等待每个回答） 按顺序提问，不得跳过任何问题。 - Q1："这个项目为用户解决什么问题？" - Q2："主要用户是谁？他们的技术水平如何？" - Q3："预期规模是多少？（每日用户数、数据量、请求频率）" ## 第二阶段——技术约束（仅在第一阶段完全回答后进行） - Q4："你将使用什么部署环境？" - Q5："你有技术栈要求或偏好吗？" - Q6："有哪些不可妥协的要求？（延迟、可用性、合规性、预算）" ## 第三阶段——综合（仅在所有问题都回答后进行） 1. 加载 'assets/plan-template.md' 获取输出格式 2. 使用收集到的需求填充模板的每个章节 3. 向用户呈现完成的计划 4. 询问："这份计划是否准确反映了你的需求？你想修改什么？" 5. 根据反馈迭代，直到用户确认 ``` ## 模式五：流水线（Pipeline） 对于复杂任务，你无法承受步骤被跳过或指令被忽视的代价。流水线模式强制执行带有硬性检查点的严格顺序工作流。 ![](../assets/media/5Pattern06.png) 指令本身就是工作流定义。通过实现明确的菱形门控条件（例如要求用户在从文档字符串生成阶段进入最终组装阶段之前给予确认），流水线确保 Agent 不能绕过复杂任务直接呈现未经验证的最终结果。 这种模式充分利用所有可选目录，只在特定步骤需要时才引入不同的参考文件和模板，保持上下文窗口的整洁。 在这个文档生成流水线示例中，注意明确的门控条件——Agent 被明确禁止在用户确认上一步生成的文档字符串之前进入组装阶段： ```text # skills/doc-pipeline/SKILL.md --- name: doc-pipeline description: 通过多步骤流水线从 Python 源代码生成 API 文档。当用户要求为模块编写文档、生成 API 文档或从代码创建文档时使用。 metadata: pattern: pipeline steps: "4" --- 你正在运行一个文档生成流水线。按顺序执行每个步骤。不得跳过步骤，步骤失败时不得继续。 ## 第一步——解析与清点 分析用户的 Python 代码，提取所有公开的类、函数和常量。以清单形式呈现清点结果。询问："这是你想要文档化的完整公开 API 吗？" ## 第二步——生成文档字符串 对于每个缺少文档字符串的函数： - 加载 'references/docstring-style.md' 获取所需格式 - 严格按照风格指南生成文档字符串 - 逐一呈现生成的文档字符串供用户确认 在用户确认之前，不得进入第三步。 ## 第三步——组装文档 加载 'assets/api-doc-template.md' 获取输出结构。将所有类、函数和文档字符串编译成单一的 API 参考文档。 ## 第四步——质量检查 对照 'references/quality-checklist.md' 进行审查： - 每个公开符号都已文档化 - 每个参数都有类型和描述 - 每个函数至少有一个使用示例 报告结果。在呈现最终文档之前修复所有问题。 ``` ## 如何选择合适的模式 每种模式回答的是不同的问题。用这棵决策树找到适合你场景的模式： ![](../assets/media/5Pattern07.png)
你的问题推荐模式
如何让 Agent 掌握特定库或框架的知识？工具封装
如何确保每次输出的文档结构一致？生成器
如何自动化代码审查或安全审计？审查器
如何防止 Agent 在需求不明确时乱猜？反转
如何确保复杂任务的每个步骤都被执行？流水线
## 模式可以组合使用 这五种模式并不互斥，它们可以组合。 流水线 Skill 可以在末尾加入一个审查器步骤来自我检验。生成器可以在开头借助反转模式收集必要的变量，再填充模板。得益于 ADK 的 `SkillToolset` 和递进式披露机制，你的 Agent 在运行时只会为真正需要的模式消耗上下文 token。 不要再试图把复杂而脆弱的指令塞进单个系统提示。拆解你的工作流，应用正确的结构模式，构建更可靠的 Agent。 ## 立即开始 Agent Skills 规范是开源的，并在 ADK 中原生支持。你已经知道如何打包格式，现在你也知道如何设计内容了。用 [Google Agent Development Kit](https://google.github.io/adk-docs/) 构建更智能的 Agent 吧。 # Claude Skill：Skill Creator ``` --- name: skill-creator description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. --- ``` # Skill Creator A skill for creating new skills and iteratively improving them. At a high level, the process of creating a skill goes like this: - Decide what you want the skill to do and roughly how it should do it - Write a draft of the skill - Create a few test prompts and run claude-with-access-to-the-skill on them - Help the user evaluate the results both qualitatively and quantitatively - While the runs happen in the background, draft some quantitative evals if there aren't any (if there are some, you can either use as is or modify if you feel something needs to change about them). Then explain them to the user (or if they already existed, explain the ones that already exist) - Use the `eval-viewer/generate_review.py` script to show the user the results for them to look at, and also let them look at the quantitative metrics - Rewrite the skill based on feedback from the user's evaluation of the results (and also if there are any glaring flaws that become apparent from the quantitative benchmarks) - Repeat until you're satisfied - Expand the test set and try again at larger scale Your job when using this skill is to figure out where the user is in this process and then jump in and help them progress through these stages. So for instance, maybe they're like "I want to make a skill for X". You can help narrow down what they mean, write a draft, write the test cases, figure out how they want to evaluate, run all the prompts, and repeat. On the other hand, maybe they already have a draft of the skill. In this case you can go straight to the eval/iterate part of the loop. Of course, you should always be flexible and if the user is like "I don't need to run a bunch of evaluations, just vibe with me", you can do that instead. Then after the skill is done (but again, the order is flexible), you can also run the skill description improver, which we have a whole separate script for, to optimize the triggering of the skill. Cool? Cool. ## Communicating with the user The skill creator is liable to be used by people across a wide range of familiarity with coding jargon. If you haven't heard (and how could you, it's only very recently that it started), there's a trend now where the power of Claude is inspiring plumbers to open up their terminals, parents and grandparents to google "how to install npm". On the other hand, the bulk of users are probably fairly computer-literate. So please pay attention to context cues to understand how to phrase your communication! In the default case, just to give you some idea: - "evaluation" and "benchmark" are borderline, but OK - for "JSON" and "assertion" you want to see serious cues from the user that they know what those things are before using them without explaining them It's OK to briefly explain terms if you're in doubt, and feel free to clarify terms with a short definition if you're unsure if the user will get it. --- ## Creating a skill ### Capture Intent Start by understanding the user's intent. The current conversation might already contain a workflow the user wants to capture (e.g., they say "turn this into a skill"). If so, extract answers from the conversation history first — the tools used, the sequence of steps, corrections the user made, input/output formats observed. The user may need to fill the gaps, and should confirm before proceeding to the next step. 1. What should this skill enable Claude to do? 2. When should this skill trigger? (what user phrases/contexts) 3. What's the expected output format? 4. Should we set up test cases to verify the skill works? Skills with objectively verifiable outputs (file transforms, data extraction, code generation, fixed workflow steps) benefit from test cases. Skills with subjective outputs (writing style, art) often don't need them. Suggest the appropriate default based on the skill type, but let the user decide. ### Interview and Research Proactively ask questions about edge cases, input/output formats, example files, success criteria, and dependencies. Wait to write test prompts until you've got this part ironed out. Check available MCPs - if useful for research (searching docs, finding similar skills, looking up best practices), research in parallel via subagents if available, otherwise inline. Come prepared with context to reduce burden on the user. ### Write the SKILL.md Based on the user interview, fill in these components: - **name**: Skill identifier - **description**: When to trigger, what it does. This is the primary triggering mechanism - include both what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body. Note: currently Claude has a tendency to "undertrigger" skills -- to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit "pushy". So for instance, instead of "How to build a simple fast dashboard to display internal Anthropic data.", you might write "How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'" - **compatibility**: Required tools, dependencies (optional, rarely needed) - **the rest of the skill :)** ### Skill Writing Guide #### Anatomy of a Skill ``` skill-name/ ├── SKILL.md (required) │ ├── YAML frontmatter (name, description required) │ └── Markdown instructions └── Bundled Resources (optional) ├── scripts/ - Executable code for deterministic/repetitive tasks ├── references/ - Docs loaded into context as needed └── assets/ - Files used in output (templates, icons, fonts) ``` #### Progressive Disclosure Skills use a three-level loading system: 1. **Metadata** (name + description) - Always in context (~100 words) 2. **SKILL.md body** - In context whenever skill triggers (<500 lines ideal) 3. **Bundled resources** - As needed (unlimited, scripts can execute without loading) These word counts are approximate and you can feel free to go longer if needed. **Key patterns:** - Keep SKILL.md under 500 lines; if you're approaching this limit, add an additional layer of hierarchy along with clear pointers about where the model using the skill should go next to follow up. - Reference files clearly from SKILL.md with guidance on when to read them - For large reference files (>300 lines), include a table of contents **Domain organization**: When a skill supports multiple domains/frameworks, organize by variant: ``` cloud-deploy/ ├── SKILL.md (workflow + selection) └── references/ ├── aws.md ├── gcp.md └── azure.md ``` Claude reads only the relevant reference file. #### Principle of Lack of Surprise This goes without saying, but skills must not contain malware, exploit code, or any content that could compromise system security. A skill's contents should not surprise the user in their intent if described. Don't go along with requests to create misleading skills or skills designed to facilitate unauthorized access, data exfiltration, or other malicious activities. Things like a "roleplay as an XYZ" are OK though. #### Writing Patterns Prefer using the imperative form in instructions. **Defining output formats** - You can do it like this: ```markdown ## Report structure ALWAYS use this exact template: # [Title] ## Executive summary ## Key findings ## Recommendations ``` **Examples pattern** - It's useful to include examples. You can format them like this (but if "Input" and "Output" are in the examples you might want to deviate a little): ```markdown ## Commit message format **Example 1:** Input: Added user authentication with JWT tokens Output: feat(auth): implement JWT-based authentication ``` ### Writing Style Try to explain to the model why things are important in lieu of heavy-handed musty MUSTs. Use theory of mind and try to make the skill general and not super-narrow to specific examples. Start by writing a draft and then look at it with fresh eyes and improve it. ### Test Cases After writing the skill draft, come up with 2-3 realistic test prompts — the kind of thing a real user would actually say. Share them with the user: \[you don't have to use this exact language\] "Here are a few test cases I'd like to try. Do these look right, or do you want to add more?" Then run them. Save test cases to `evals/evals.json`. Don't write assertions yet — just the prompts. You'll draft assertions in the next step while the runs are in progress. ```json { "skill_name": "example-skill", "evals": [ { "id": 1, "prompt": "User's task prompt", "expected_output": "Description of expected result", "files": [] } ] } ``` See `references/schemas.md` for the full schema (including the `assertions` field, which you'll add later). ## Running and evaluating test cases This section is one continuous sequence — don't stop partway through. Do NOT use `/skill-test` or any other testing skill. Put results in `-workspace/` as a sibling to the skill directory. Within the workspace, organize results by iteration (`iteration-1/`, `iteration-2/`, etc.) and within that, each test case gets a directory (`eval-0/`, `eval-1/`, etc.). Don't create all of this upfront — just create directories as you go. ### Step 1: Spawn all runs (with-skill AND baseline) in the same turn For each test case, spawn two subagents in the same turn — one with the skill, one without. This is important: don't spawn the with-skill runs first and then come back for baselines later. Launch everything at once so it all finishes around the same time. **With-skill run:** ``` Execute this task: - Skill path: - Task: - Input files: - Save outputs to: /iteration-/eval-/with_skill/outputs/ - Outputs to save: ``` **Baseline run** (same prompt, but the baseline depends on context): - **Creating a new skill**: no skill at all. Same prompt, no skill path, save to `without_skill/outputs/`. - **Improving an existing skill**: the old version. Before editing, snapshot the skill (`cp -r /skill-snapshot/`), then point the baseline subagent at the snapshot. Save to `old_skill/outputs/`. Write an `eval_metadata.json` for each test case (assertions can be empty for now). Give each eval a descriptive name based on what it's testing — not just "eval-0". Use this name for the directory too. If this iteration uses new or modified eval prompts, create these files for each new eval directory — don't assume they carry over from previous iterations. ```json { "eval_id": 0, "eval_name": "descriptive-name-here", "prompt": "The user's task prompt", "assertions": [] } ``` ### Step 2: While runs are in progress, draft assertions Don't just wait for the runs to finish — you can use this time productively. Draft quantitative assertions for each test case and explain them to the user. If assertions already exist in `evals/evals.json`, review them and explain what they check. Good assertions are objectively verifiable and have descriptive names — they should read clearly in the benchmark viewer so someone glancing at the results immediately understands what each one checks. Subjective skills (writing style, design quality) are better evaluated qualitatively — don't force assertions onto things that need human judgment. Update the `eval_metadata.json` files and `evals/evals.json` with the assertions once drafted. Also explain to the user what they'll see in the viewer — both the qualitative outputs and the quantitative benchmark. ### Step 3: As runs complete, capture timing data When each subagent task completes, you receive a notification containing `total_tokens` and `duration_ms`. Save this data immediately to `timing.json` in the run directory: ```json { "total_tokens": 84852, "duration_ms": 23332, "total_duration_seconds": 23.3 } ``` This is the only opportunity to capture this data — it comes through the task notification and isn't persisted elsewhere. Process each notification as it arrives rather than trying to batch them. ### Step 4: Grade, aggregate, and launch the viewer Once all runs are done: 1. **Grade each run** — spawn a grader subagent (or grade inline) that reads `agents/grader.md` and evaluates each assertion against the outputs. Save results to `grading.json` in each run directory. The grading.json expectations array must use the fields `text`, `passed`, and `evidence` (not `name`/`met`/`details` or other variants) — the viewer depends on these exact field names. For assertions that can be checked programmatically, write and run a script rather than eyeballing it — scripts are faster, more reliable, and can be reused across iterations. 2. **Aggregate into benchmark** — run the aggregation script from the skill-creator directory: ```bash python -m scripts.aggregate_benchmark /iteration-N --skill-name ``` This produces `benchmark.json` and `benchmark.md` with pass\_rate, time, and tokens for each configuration, with mean ± stddev and the delta. If generating benchmark.json manually, see `references/schemas.md` for the exact schema the viewer expects. Put each with\_skill version before its baseline counterpart. 3. **Do an analyst pass** — read the benchmark data and surface patterns the aggregate stats might hide. See `agents/analyzer.md` (the "Analyzing Benchmark Results" section) for what to look for — things like assertions that always pass regardless of skill (non-discriminating), high-variance evals (possibly flaky), and time/token tradeoffs. 4. **Launch the viewer** with both qualitative outputs and quantitative data: ```bash nohup python /eval-viewer/generate_review.py \ /iteration-N \ --skill-name "my-skill" \ --benchmark /iteration-N/benchmark.json \ > /dev/null 2>&1 & VIEWER_PID=$! ``` For iteration 2+, also pass `--previous-workspace /iteration-`. **Cowork / headless environments:** If `webbrowser.open()` is not available or the environment has no display, use `--static ` to write a standalone HTML file instead of starting a server. Feedback will be downloaded as a `feedback.json` file when the user clicks "Submit All Reviews". After download, copy `feedback.json` into the workspace directory for the next iteration to pick up. Note: please use generate\_review.py to create the viewer; there's no need to write custom HTML. 5. **Tell the user** something like: "I've opened the results in your browser. There are two tabs — 'Outputs' lets you click through each test case and leave feedback, 'Benchmark' shows the quantitative comparison. When you're done, come back here and let me know." ### What the user sees in the viewer The "Outputs" tab shows one test case at a time: - **Prompt**: the task that was given - **Output**: the files the skill produced, rendered inline where possible - **Previous Output** (iteration 2+): collapsed section showing last iteration's output - **Formal Grades** (if grading was run): collapsed section showing assertion pass/fail - **Feedback**: a textbox that auto-saves as they type - **Previous Feedback** (iteration 2+): their comments from last time, shown below the textbox The "Benchmark" tab shows the stats summary: pass rates, timing, and token usage for each configuration, with per-eval breakdowns and analyst observations. Navigation is via prev/next buttons or arrow keys. When done, they click "Submit All Reviews" which saves all feedback to `feedback.json`. ### Step 5: Read the feedback When the user tells you they're done, read `feedback.json`: ```json { "reviews": [ {"run_id": "eval-0-with_skill", "feedback": "the chart is missing axis labels", "timestamp": "..."}, {"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."}, {"run_id": "eval-2-with_skill", "feedback": "perfect, love this", "timestamp": "..."} ], "status": "complete" } ``` Empty feedback means the user thought it was fine. Focus your improvements on the test cases where the user had specific complaints. Kill the viewer server when you're done with it: ```bash kill $VIEWER_PID 2>/dev/null ``` --- ## Improving the skill This is the heart of the loop. You've run the test cases, the user has reviewed the results, and now you need to make the skill better based on their feedback. ### How to think about improvements 1. **Generalize from the feedback.** The big picture thing that's happening here is that we're trying to create skills that can be used a million times (maybe literally, maybe even more who knows) across many different prompts. Here you and the user are iterating on only a few examples over and over again because it helps move faster. The user knows these examples in and out and it's quick for them to assess new outputs. But if the skill you and the user are codeveloping works only for those examples, it's useless. Rather than put in fiddly overfitty changes, or oppressively constrictive MUSTs, if there's some stubborn issue, you might try branching out and using different metaphors, or recommending different patterns of working. It's relatively cheap to try and maybe you'll land on something great. 2. **Keep the prompt lean.** Remove things that aren't pulling their weight. Make sure to read the transcripts, not just the final outputs — if it looks like the skill is making the model waste a bunch of time doing things that are unproductive, you can try getting rid of the parts of the skill that are making it do that and seeing what happens. 3. **Explain the why.** Try hard to explain the **why** behind everything you're asking the model to do. Today's LLMs are *smart*. They have good theory of mind and when given a good harness can go beyond rote instructions and really make things happen. Even if the feedback from the user is terse or frustrated, try to actually understand the task and why the user is writing what they wrote, and what they actually wrote, and then transmit this understanding into the instructions. If you find yourself writing ALWAYS or NEVER in all caps, or using super rigid structures, that's a yellow flag — if possible, reframe and explain the reasoning so that the model understands why the thing you're asking for is important. That's a more humane, powerful, and effective approach. 4. **Look for repeated work across test cases.** Read the transcripts from the test runs and notice if the subagents all independently wrote similar helper scripts or took the same multi-step approach to something. If all 3 test cases resulted in the subagent writing a `create_docx.py` or a `build_chart.py`, that's a strong signal the skill should bundle that script. Write it once, put it in `scripts/`, and tell the skill to use it. This saves every future invocation from reinventing the wheel. This task is pretty important (we are trying to create billions a year in economic value here!) and your thinking time is not the blocker; take your time and really mull things over. I'd suggest writing a draft revision and then looking at it anew and making improvements. Really do your best to get into the head of the user and understand what they want and need. ### The iteration loop After improving the skill: 1. Apply your improvements to the skill 2. Rerun all test cases into a new `iteration-/` directory, including baseline runs. If you're creating a new skill, the baseline is always `without_skill` (no skill) — that stays the same across iterations. If you're improving an existing skill, use your judgment on what makes sense as the baseline: the original version the user came in with, or the previous iteration. 3. Launch the reviewer with `--previous-workspace` pointing at the previous iteration 4. Wait for the user to review and tell you they're done 5. Read the new feedback, improve again, repeat Keep going until: - The user says they're happy - The feedback is all empty (everything looks good) - You're not making meaningful progress --- ## Advanced: Blind comparison For situations where you want a more rigorous comparison between two versions of a skill (e.g., the user asks "is the new version actually better?"), there's a blind comparison system. Read `agents/comparator.md` and `agents/analyzer.md` for the details. The basic idea is: give two outputs to an independent agent without telling it which is which, and let it judge quality. Then analyze why the winner won. This is optional, requires subagents, and most users won't need it. The human review loop is usually sufficient. --- ## Description Optimization The description field in SKILL.md frontmatter is the primary mechanism that determines whether Claude invokes a skill. After creating or improving a skill, offer to optimize the description for better triggering accuracy. ### Step 1: Generate trigger eval queries Create 20 eval queries — a mix of should-trigger and should-not-trigger. Save as JSON: ```json [ {"query": "the user prompt", "should_trigger": true}, {"query": "another prompt", "should_trigger": false} ] ``` The queries must be realistic and something a Claude Code or Claude.ai user would actually type. Not abstract requests, but requests that are concrete and specific and have a good amount of detail. For instance, file paths, personal context about the user's job or situation, column names and values, company names, URLs. A little bit of backstory. Some might be in lowercase or contain abbreviations or typos or casual speech. Use a mix of different lengths, and focus on edge cases rather than making them clear-cut (the user will get a chance to sign off on them). Bad: `"Format this data"`, `"Extract text from PDF"`, `"Create a chart"` Good: `"ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think"` For the **should-trigger** queries (8-10), think about coverage. You want different phrasings of the same intent — some formal, some casual. Include cases where the user doesn't explicitly name the skill or file type but clearly needs it. Throw in some uncommon use cases and cases where this skill competes with another but should win. For the **should-not-trigger** queries (8-10), the most valuable ones are the near-misses — queries that share keywords or concepts with the skill but actually need something different. Think adjacent domains, ambiguous phrasing where a naive keyword match would trigger but shouldn't, and cases where the query touches on something the skill does but in a context where another tool is more appropriate. The key thing to avoid: don't make should-not-trigger queries obviously irrelevant. "Write a fibonacci function" as a negative test for a PDF skill is too easy — it doesn't test anything. The negative cases should be genuinely tricky. ### Step 2: Review with user Present the eval set to the user for review using the HTML template: 1. Read the template from `assets/eval_review.html` 2. Replace the placeholders: - `__EVAL_DATA_PLACEHOLDER__` → the JSON array of eval items (no quotes around it — it's a JS variable assignment) - `__SKILL_NAME_PLACEHOLDER__` → the skill's name - `__SKILL_DESCRIPTION_PLACEHOLDER__` → the skill's current description 3. Write to a temp file (e.g., `/tmp/eval_review_.html`) and open it: `open /tmp/eval_review_.html` 4. The user can edit queries, toggle should-trigger, add/remove entries, then click "Export Eval Set" 5. The file downloads to `~/Downloads/eval_set.json` — check the Downloads folder for the most recent version in case there are multiple (e.g., `eval_set (1).json`) This step matters — bad eval queries lead to bad descriptions. ### Step 3: Run the optimization loop Tell the user: "This will take some time — I'll run the optimization loop in the background and check on it periodically." Save the eval set to the workspace, then run in the background: ```bash python -m scripts.run_loop \ --eval-set \ --skill-path \ --model \ --max-iterations 5 \ --verbose ``` Use the model ID from your system prompt (the one powering the current session) so the triggering test matches what the user actually experiences. While it runs, periodically tail the output to give the user updates on which iteration it's on and what the scores look like. This handles the full optimization loop automatically. It splits the eval set into 60% train and 40% held-out test, evaluates the current description (running each query 3 times to get a reliable trigger rate), then calls Claude to propose improvements based on what failed. It re-evaluates each new description on both train and test, iterating up to 5 times. When it's done, it opens an HTML report in the browser showing the results per iteration and returns JSON with `best_description` — selected by test score rather than train score to avoid overfitting. ### How skill triggering works Understanding the triggering mechanism helps design better eval queries. Skills appear in Claude's `available_skills` list with their name + description, and Claude decides whether to consult a skill based on that description. The important thing to know is that Claude only consults skills for tasks it can't easily handle on its own — simple, one-step queries like "read this PDF" may not trigger a skill even if the description matches perfectly, because Claude can handle them directly with basic tools. Complex, multi-step, or specialized queries reliably trigger skills when the description matches. This means your eval queries should be substantive enough that Claude would actually benefit from consulting a skill. Simple queries like "read file X" are poor test cases — they won't trigger skills regardless of description quality. ### Step 4: Apply the result Take `best_description` from the JSON output and update the skill's SKILL.md frontmatter. Show the user before/after and report the scores. --- ### Package and Present (only if `present_files` tool is available) Check whether you have access to the `present_files` tool. If you don't, skip this step. If you do, package the skill and present the .skill file to the user: ```bash python -m scripts.package_skill ``` After packaging, direct the user to the resulting `.skill` file path so they can install it. --- ## Claude.ai-specific instructions In Claude.ai, the core workflow is the same (draft → test → review → improve → repeat), but because Claude.ai doesn't have subagents, some mechanics change. Here's what to adapt: **Running test cases**: No subagents means no parallel execution. For each test case, read the skill's SKILL.md, then follow its instructions to accomplish the test prompt yourself. Do them one at a time. This is less rigorous than independent subagents (you wrote the skill and you're also running it, so you have full context), but it's a useful sanity check — and the human review step compensates. Skip the baseline runs — just use the skill to complete the task as requested. **Reviewing results**: If you can't open a browser (e.g., Claude.ai's VM has no display, or you're on a remote server), skip the browser reviewer entirely. Instead, present results directly in the conversation. For each test case, show the prompt and the output. If the output is a file the user needs to see (like a .docx or .xlsx), save it to the filesystem and tell them where it is so they can download and inspect it. Ask for feedback inline: "How does this look? Anything you'd change?" **Benchmarking**: Skip the quantitative benchmarking — it relies on baseline comparisons which aren't meaningful without subagents. Focus on qualitative feedback from the user. **The iteration loop**: Same as before — improve the skill, rerun the test cases, ask for feedback — just without the browser reviewer in the middle. You can still organize results into iteration directories on the filesystem if you have one. **Description optimization**: This section requires the `claude` CLI tool (specifically `claude -p`) which is only available in Claude Code. Skip it if you're on Claude.ai. **Blind comparison**: Requires subagents. Skip it. **Packaging**: The `package_skill.py` script works anywhere with Python and a filesystem. On Claude.ai, you can run it and the user can download the resulting `.skill` file. **Updating an existing skill**: The user might be asking you to update an existing skill, not create a new one. In this case: - **Preserve the original name.** Note the skill's directory name and `name` frontmatter field -- use them unchanged. E.g., if the installed skill is `research-helper`, output `research-helper.skill` (not `research-helper-v2`). - **Copy to a writeable location before editing.** The installed skill path may be read-only. Copy to `/tmp/skill-name/`, edit there, and package from the copy. - **If packaging manually, stage in `/tmp/` first**, then copy to the output directory -- direct writes may fail due to permissions. --- ## Cowork-Specific Instructions If you're in Cowork, the main things to know are: - You have subagents, so the main workflow (spawn test cases in parallel, run baselines, grade, etc.) all works. (However, if you run into severe problems with timeouts, it's OK to run the test prompts in series rather than parallel.) - You don't have a browser or display, so when generating the eval viewer, use `--static ` to write a standalone HTML file instead of starting a server. Then proffer a link that the user can click to open the HTML in their browser. - For whatever reason, the Cowork setup seems to disincline Claude from generating the eval viewer after running the tests, so just to reiterate: whether you're in Cowork or in Claude Code, after running tests, you should always generate the eval viewer for the human to look at examples before revising the skill yourself and trying to make corrections, using `generate_review.py` (not writing your own boutique html code). Sorry in advance but I'm gonna go all caps here: GENERATE THE EVAL VIEWER *BEFORE* evaluating inputs yourself. You want to get them in front of the human ASAP! - Feedback works differently: since there's no running server, the viewer's "Submit All Reviews" button will download `feedback.json` as a file. You can then read it from there (you may have to request access first). - Packaging works — `package_skill.py` just needs Python and a filesystem. - Description optimization (`run_loop.py` / `run_eval.py`) should work in Cowork just fine since it uses `claude -p` via subprocess, not a browser, but please save it until you've fully finished making the skill and the user agrees it's in good shape. - **Updating an existing skill**: The user might be asking you to update an existing skill, not create a new one. Follow the update guidance in the claude.ai section above. --- ## Reference files The agents/ directory contains instructions for specialized subagents. Read them when you need to spawn the relevant subagent. - `agents/grader.md` — How to evaluate assertions against outputs - `agents/comparator.md` — How to do blind A/B comparison between two outputs - `agents/analyzer.md` — How to analyze why one version beat another The references/ directory has additional documentation: - `references/schemas.md` — JSON structures for evals.json, grading.json, etc. --- Repeating one more time the core loop here for emphasis: - Figure out what the skill is about - Draft or edit the skill - Run claude-with-access-to-the-skill on test prompts - With the user, evaluate the outputs: - Create benchmark.json and run `eval-viewer/generate_review.py` to help the user review them - Run quantitative evals - Repeat until you and the user are satisfied - Package the final skill and return it to the user. Please add steps to your TodoList, if you have such a thing, to make sure you don't forget. If you're in Cowork, please specifically put "Create evals JSON and run `eval-viewer/generate_review.py` so human can review test cases" in your TodoList to make sure it happens. Good luck! # Deepseek Harness # DeepSeek Harness 架构 [English](architecture.md) | 中文 改动 `packages/` 下的任何内容之前，请先阅读本文。本文假定你已了解 Cordis；如果尚未了解，请先阅读[入门](cordis-primer.zh.md)或[教程](cordis-tutorial/index.zh.md)。 建议使用 agent（智能体）探索代码库并理解其架构。 ## Cordis [Cordis](cordis-primer.zh.md) 是 dsh 底层的框架：插件向共享上下文贡献服务、类型化事件和可逆的副作用。产品的每一部分都是插件，包括模型适配器、工具注册表、会话日志，以及 agent loop（智能体循环）本身，因此每个都可以从配置替换。 不存在需要打补丁的特权内核：扩展 dsh 的方式是把插件挂载到其他插件旁边，而各项注册都是副作用，会在其插件卸载时撤销。 ## Profile 与组合包 运行中的 `dsh` 是一棵插件树，由启动时按序叠加的各层组合而成。 **profile** 是存放在 Harness home 中的具名组装。它列出自己叠放的组合包，存放自己安装的树外插件，并保存用户自己的 `cordis.patch.yml`。`web`、`headless`、`sdk`、`sdk-minimal` 和 `acp` 作为模板随发行版交付。 **组合包**是 Cordis 配置项及其挂载代码的分发格式，因此它插入的内容始终可被其上各层 patch。 两者都在各自的 `package.json` 中通过 `dsh` 字段声明自己：`dsh.profile` 列出一个 profile 的组合包，`dsh.bundle` 指向一个组合包的 patch 文件。 [`dsh-base`](../packages/bundle/base/README.zh.md) 是 `web`、`headless`、`sdk` 与 `acp` profile 的共享第一层：模型适配器、工具、持久化、沙箱与审批策略、设置、凭据、遥测。[`dsh-web-app`](../packages/bundle/web-app/README.zh.md) 增加浏览器应用，[`dsh-headless`](../packages/bundle/headless/README.zh.md) 增加不带服务器的一次性运行器，[`dsh-sdk-app`](../packages/bundle/sdk-app/README.zh.md) 增加 SDK JSON-RPC 服务器，[`dsh-acp-app`](../packages/bundle/acp-app/README.zh.md) 增加仅用于自动化的 ACP 服务器。[`dsh-sdk-minimal`](../packages/bundle/sdk-minimal/README.zh.md) 是刻意保留的例外：一个组合包拥有完整的显式 SDK 配置树，不应用 `dsh-base`。 各层按此顺序应用在空条目列表之上：先按 profile 列出的顺序应用每个组合包，然后是 profile 的 `cordis.patch.yml`，然后是 home 级的那份，最后是任意 `--patch` overlay。一条 patch 按 id 定位某个条目并替换其整个 config，或插入新条目。 自定义 profile 默认实时重载 patch。随附的 `web` profile 使用实时重载；`headless`、`sdk`、`sdk-minimal` 和 `acp` 则只在启动时应用一次所有配置层，因为一次性应用或 stdio 应用拥有工作之后，替换其依赖会破坏该生命周期。 要查看你的机器启动的配置树： ```sh dsh --profile web --dump-config ``` 它打印出的任何条目，都可以由你自己的 patch 替换。 组装机制见 [app-boot](../packages/boot/app-boot/README.zh.md#profiles)；配置字段见生成的[配置目录](config-catalog.zh.md)。 ## 应用启动 所有受支持的 Node 应用都从 `dsh` CLI 与具名 profile 启动。随附应用是 `dsh web`（刻意为 `--profile web` 保留的别名）、`dsh --profile headless`、`dsh --profile sdk`、`dsh --profile sdk-minimal` 与 `dsh --profile acp`。TypeScript SDK 会解析其同版本 `dsh` 依赖并选择 `sdk`；自定义插件组合继续由 profile 与有序 patch 文件表达，而不是另一个可执行文件或内联应用树。`sdk-minimal` 是位于同一 launcher 后的仓库自有独立组合包，而不是由调用方提供的 Cordis 配置树。 Vendored CLI、仅用于构建和测试的可执行文件、进程内直接挂载插件以及私有浏览器 WebWorker 预览都不属于 Harness 应用启动器。[`verify-application-entrypoints`](../scripts/verify-application-entrypoints.ts)将每个包 bin、可执行源码与根 demo 归入显式类别，并拒绝任何绕过 `dsh` 的 Node 应用路径。 Python SDK 遵循相同的应用架构。其运行时 wheel 把普通 `dsh` CLI 打包为 `deepseek-harness-sdk-runtime--`，客户端默认以显式 Harness home 启动 `dsh --profile sdk`。极简示例选择随附的 `sdk-minimal` profile。Python 暴露 profile 选择与有序 patch 文件，而不是完整 Cordis 树；持久外部插件通过 `dsh plugin` 安装。已删除的私有直读配置载体没有兼容 bin 或回退 parser。 ## 核心包 以下是向 Cordis 树贡献内容的部分核心包。 | 包 | 职责 | `ctx` 键 | |---|---|---| | [`core/session`](subsystems/session.zh.md) | 仅追加的 `SessionEvent` 日志和内存存储 | `ctx.sessions` | | [`core/system-prompt`](subsystems/system-prompt.zh.md) | 提示词片段与工具 schema 的组装 | `ctx.systemPrompt` | | [`core/tools`](subsystems/tools.zh.md) | 作用域化的工具注册表和带把关的执行流水线 | `ctx.tools` | | [`core/agent`](subsystems/core.zh.md) | `Agent` 接口、活跃 agent 注册表和 `agent/*` 事件 | `ctx.agents` | | [`core/agent-loop`](subsystems/core.zh.md) | 实现该接口的默认驱动器 | `ctx.agentLoop` | | [`core/scope`](subsystems/scope.zh.md) | 按 agent 划分作用域的注册原语 | 库，无 ctx 键 | | [`llm/llm`](subsystems/llm-streaming.zh.md) | 消息与流式词汇表，以及适配器 seam | `ctx.llm` | | [`webhook/webhook`](subsystems/webhook.zh.md) | 已认证 delivery 的分派和 Workspace Session 创建 | `ctx.webhookRuntime` | ## 事件 事件就是扩展点，而选对事件域是大多数改动的第一个决定。 - **会话事件**是追加到日志并通过 `session/event` 广播的持久事实。当某个事实必须在重新加载后仍然存在时，使用它。 - **Agent 事件**（`agent/*`）携带活跃 `Agent`：inbox、步骤、状态、请求、验证、续跑。要观察或拦截进行中的工作时，使用它。 - **能力事件**无需导入循环即可向某个 seam（`fs/*`、`tools/*`、`telemetry/*`）附加策略和适配器。 [事件映射](event-producer-consumer.zh.md)列出每个事件的生产方与消费方。 ## 轮次流程 一个**步骤**是一次模型请求加上它调用的工具。一个**轮次**包含零个或多个步骤：它在领取首条输入之前打开，并在不再欠下任何工作时关闭。 ```text turn/start claim next-step input plus one queued message assemble prompt sections + tool schemas -> agent/pre-step reject | enter(messages, startsRequestSeries?) reject, or a first enter rewritten empty -> close the turn with no step step/start append entered messages as user/message derive model history from the log agent/request -> llm/stream -> assistant/chunk* -> assistant/message tool/call* -> tools/pre-execute -> tools/execute -> tools/post-execute -> tool/result* step/end tools owe another request, or next-step input arrived -> claim -> next step -> agent/turn-stopping turn/end ``` `turn/*`、`step/*`、`user/message`、`assistant/*` 和 `tool/*` 是持久会话事件；其余是分属三个事件域的实时扩展点。`agent/pre-step`、`agent/request`、`llm/stream` 和三个 `tools/*` 事件是 waterfall（瀑布式事件），其监听器必须调用 `next()` 才能委托下去；`agent/turn-stopping` 是 serial 事件，没有 `next()`。 输入通过同一个 inbox 到达驱动器。有些消息会立即唤醒它；注入的上下文会留在 inbox 中，直到另一条消息将其唤醒。 `agent/pre-step` 决定模型看到什么。监听器可以改写已领取的消息，也可以直接拒绝它们；首次领取被拒绝或被改写为空时，仍会关闭一个不含步骤的持久轮次，因此日志会记录这次尝试。enter 决策还可以设置 `startsRequestSeries` 来开启独立的模型消息序列：loop 会随之记录一个新的 `request/header`（原因为 `series`，或在封装同时变化时为携带 `startsSeries: true` 的 `change`）。重建下游 enter 决策的监听器必须展开它（`{ ...decision, messages }`），该声明才能存活。每个步骤读取插件注册的提示词片段和工具 schema。 详情见[时序图](agent-lifecycle.zh.md)、[工具流水线](tool-execution-pipeline.zh.md)和[取消与错误恢复](subsystems/core.zh.md#the-agent-handle)。 ## 会话日志 会话日志是模型所见上下文的来源。`deriveMessages()` 从中投影出模型历史，原始 `assistant/chunk` 事件则保证回放和 UI 保真。fork、恢复、transcript（文本记录）、遥测和持久化都派生自该事件流。 **模型可见即已记录。** 抵达模型请求的一切都必须能从日志重建，并由一项运行时不变量断言这一点。因此，新增一项模型可见输入就需要新增一个会话事件：扩展 `SessionEventMap` 并从日志渲染。 **投影 seam。** `dsh-session-projection` 提供 `ctx.sessionProjections`：已注册单元增量折叠已提交事件，host 消费方通过 `stateOf()` 读取单个类型化状态，载体通过 `snapshot()` 批量取得裁剪后的客户端视图。host 读取方要么在激活时要求该服务，要么在注册表或必需 key 缺席时明确失败。贡献方可以保留 `ctx.inject(['sessionProjections'], ...)` 注册，但不能为缺失的 host 值静默提供默认值。agent loop 为读取方注册共享的 `turnBoundary` 状态（[决策](../.agents/notes/implemented/architecture/2026-08-19-session-projection-mandatory-seam.zh.md)）。 ## 能力 seam 一个 **seam** 是一项可替换能力，包含三种角色：声明接口的 **Service Definition**、实现它的 **Service Provider**，以及使用它的 **Consumer**（通常是面向模型的工具）。一个包可以合并承担多个角色，但单一角色本身不是 seam；添加一项能力意味着把三者一并设计（[能力图](capability-seams.zh.md)）。 seam 正是替换一个提供方就能改变整个产品的原因。文件系统与进程提供方共享同一个执行世界，因此把它们指向远程沙箱，也就把 Bash、PTY 和 LSP 一并搬了过去，无需提供方专用 fork。[subagent 提供方](subsystems/subagent.zh.md)在同一个接口之后同样千差万别，从新建一个子 agent，到把一个轮次委派给另一个产品。 [实验性 Agent Teams](subsystems/agent-team.zh.md) 是 `ctx.agentTeams` 上的私有显式启用协作 seam，在可继续 subagent 之上提供持久 roster、任务板和 mailbox。 ## 新行为的归属位置 新行为附加到已有文档记录的扩展点。改动循环本身时，本映射随之更新。 | 目标 | 机制 | |---|---| | 添加模型提供方 | 在 `ctx.llm` 上注册其适配器 | | 添加面向模型的能力 | 在 `ctx.tools` 上注册；其 schema 加入提示词组装 | | 让某个会话拥有不同的能力集合 | 组装一个 agent preset；其中的服务行需要 `isolate` realm | | 添加 shell 执行 | 注册 `ctx.shell` 后端；本地后端通过 `ctx.subprocess` spawn 进程 | | 添加持久化终端执行 | 注册 `ctx.terminals` 后端和 `dsh-tool-terminal` | | 添加用户命令 | 在 `ctx.commands` 上注册；它无需模型轮次即可分派 | | 添加后台工作 | 在 `ctx.jobs` 上注册；`job_*` 工具负责收集或停止 | | 从外部 webhook 启动 Session | 在 `ctx.webhookRuntime` 上注册可信规则，并挂载提供方适配器 | | 添加文件系统访问或策略 | 注册 `ctx.fs` 提供方，或监听 `fs/*` 事件 | | 限制所启动的进程 | 使用 `ctx.sandbox` 后端；消费方在启动进程前包装 argv | | 拦截请求、工具或轮次 | 使用相应的 `agent/*` 或 `tools/*` 事件；`agent/turn-stopping` 会停止轮次 | | 添加模型可见上下文 | 调用 `agent.inject()`；它会落到下一次获准的请求中 | | 添加 UI 或编辑器集成 | 驱动 `ctx.agents` 并从 `session/event` 渲染 | | 添加 Web Client Chat 节点 | 注册 `ConversationNodeDefinition` + keyed renderer | | 添加持久会话状态 | 扩展 `SessionEventMap`；从日志渲染和回放 | | 生成会话标题 | 注册唯一的 `ctx.sessionTitle` 提供方 | | 管理同会话目标 | 使用 `ctx.goals`；通过 `agent/*` 续跑 | | fork 活跃会话 | `ctx.sessions.fork(source, boundary?, childSessionId?)` | | 将注册项限定到单个 agent | 使用该 agent 的 `agent.ctx` | [扩展实操手册](cookbook/extension-cookbook.zh.md)将功能映射到能力，并索引[包](cookbook/adding-a-package.zh.md)、[工具](cookbook/adding-a-tool.zh.md)、[LLM（大语言模型）适配器](cookbook/adding-an-llm-adapter.zh.md)和[设置卡片](cookbook/adding-a-settings-card.zh.md)的分步指南。[Conversation 子系统](subsystems/conversation.zh.md)负责 Chat node 组装。 # 插件配置目录 [English](config-catalog.md) | 中文 每个 `config:` 块均可由 `cordis.yml` 条目设置：针对每个可加载的 harness 包，原样列出其 `apply` 函数或服务构造函数接收的配置声明（包括 JSDoc），并附上所有引用类型——包内类型直接粘贴，其他类型则提供链接。粘贴的内容是插件声明的完整配置类型——运行时 schema 有意排除的字段是仅供运行时使用的 seam（其自身的 JSDoc 会如此说明），不能通过 `cordis.yml` 设置。这是以**部署**为轴的参考文档——插件作者所依据的连接方式请参阅各[子系统页面](subsystems/core.zh.md)中的生成 `cordis-surface` 区域，面向模型的工具 schema 请参阅[工具目录](tool-catalog.zh.md)，而 [subsystems/](subsystems/core.zh.md) 则记录了这些声明所引用的类型。 英文源文件由源代码（`scripts/gen-config-catalog.ts`）生成，并通过 `pnpm run verify-config-catalog`（`doc-sync` 的一部分）验证新鲜度；本中文文件作为经评审对侧通过双语配对维护。声明块使用 `ts config-catalog` 围栏（doc-typecheck 会跳过它，因为单独引用导入项的声明无法独立编译）。英文生成器还会将运行时 schemastery schema 与粘贴的声明进行交叉核对——每个经 schema 验证的键（包括嵌套键）都必须能在声明的配置类型中找到——因此，粘贴内容无法隐藏加载器接受的字段。 `Requires:` 行列出插件通过 `inject` 注入的服务键：其 `cordis.yml` 树还必须加载这些服务的提供者。范围限定为 harness 层级（`packages/`）；配置树还可能加载的 vendored cordis 插件（`hmr`、控制台日志记录器等）固定为上游源代码（参见 [vendoring policy](../vendor/README.md)），未收录于此目录。 ## `@deepseek-ai/dsh-acp` 需要：`agents` · `llm` · `sessionPersistence` · `sessions` ```ts config-catalog /** Plugin config: the provider/model selection used for each ACP-created agent. */ export interface AcpConfig { /** Provider route for created agents. */ provider?: string /** Model name for created agents. */ model?: string /** Maximum summaries returned by one session/list page. */ sessionListPageSize?: number /** Runtime-only transport override; production uses stdio. */ stream?: Stream } ``` 依赖：`Stream`（`@agentclientprotocol/sdk`） 来源：[`packages/acp/acp/src/index.ts:75`](../packages/acp/acp/src/index.ts) ## `@deepseek-ai/dsh-agent-default-model` ```ts config-catalog /** Composition entry for the default model selection. */ export interface Config { /** Registered provider route. */ provider: string /** Provider-owned model id. */ model: string } ``` 来源：[`packages/core/agent-default-model/src/index.ts:41`](../packages/core/agent-default-model/src/index.ts) ## `@deepseek-ai/dsh-agent-instructions` 需要：`sessionProjections` ```ts config-catalog /** User-facing workspace instruction loader configuration. */ export interface Config { /** Harness home containing the fixed user-global `AGENTS.md`; defaults to `$DSH_HOME` or `~/.dsh`. */ dshHome?: string /** Directory entries that identify the project root while walking upward from the session cwd. */ projectRootMarkers?: string[] /** UTF-8 byte cap for one rendered baseline or dynamic batch; non-positive or non-finite disables loading. */ maxBytes: number /** Maximum UTF-8 bytes read from one instruction file; larger files are ignored. */ maxSourceBytes?: number /** * Ordered same-directory project candidates; every existing file loads, with * per-directory trimmed-content duplicates collapsed to the earliest candidate. */ instructionFileCandidates?: string[] /** * Ordered same-directory local-overlay candidates loaded after the base files * under the same per-directory trimmed-content dedup; empty disables the overlay. */ localInstructionFileCandidates?: string[] } ``` 来源：[`packages/context/agent-instructions/src/config.ts:18`](../packages/context/agent-instructions/src/config.ts) ## `@deepseek-ai/dsh-agent-loop` 需要：`agents` · `sessions` · `llm` · `tools` · `systemPrompt` · `sessionProjections` ```ts config-catalog /** Agent-loop plugin configuration. */ export interface Config { /** * Maximum parallel-safe calls in flight per agent step. `1` is serial; * omission defaults to {@link DEFAULT_MAX_PARALLEL_TOOL_CALLS}. */ maxParallelToolCalls?: number /** Agents created or resumed at plugin startup. */ agents: (AgentOptions & { /** Stable config label used in logs and as the fresh combined-id prefix. */ id: string /** Optional stable identity; remounts resume its materialized history, while first use creates it fresh. */ sessionId?: SessionId /** Optional workspace for a fresh session. */ cwd?: string /** Persisted session to resume instead of creating a fresh session. */ resumeSessionId?: SessionId })[] } ``` 依赖：[`AgentOptions`](subsystems/core.zh.md) · [`SessionId`](subsystems/core.zh.md) 来源：[`packages/core/agent-loop/src/index.ts:311`](../packages/core/agent-loop/src/index.ts) ## `@deepseek-ai/dsh-agent-presets` 需要：`loader` · `sessionProjections` ```ts config-catalog /** Plugin config: which preset is the default, and where presets live. */ export interface Config { /** Preset id mounted when a caller names none. Missing at mount time fails loud. */ default: string /** Scanned roots in precedence order; an earlier root wins a duplicate id. */ roots: PresetRoot[] /** * Prepend this package's bundled shipped presets as a `system` root, before * every configured root, so the shipped set always mounts and wins a * duplicate id. The default survives a whole-`config` patch replacement; * only an explicit `false` — a deployment supplying purely its own presets, * or an embedder using the roster as bare machinery — drops the set. */ includeShippedRoot: boolean /** * Append the harness home's `USER_PRESET_DIR` as a `user` root, after every * configured root. False mounts a roster without the derived writable root. */ includeUserRoot: boolean } /** One directory scanned for preset subdirectories. */ export interface PresetRoot { /** Directory holding one subdirectory per preset; a leading `~` expands. */ path: string /** Trust recorded on every preset discovered under this root. */ trust: PresetTrust } /** * Where a preset's composition came from. A `system` preset ships with the * deployment; a `user` preset was authored locally, by a person or by an * agent, and therefore carries the same trust as shell access. */ export type PresetTrust = 'system' | 'user' ``` 来源：[`packages/preset/agent-presets/src/preset.ts:52`](../packages/preset/agent-presets/src/preset.ts) ## `@deepseek-ai/dsh-agent-tool-presentation` 需要：`tools` ```ts config-catalog /** Plugin config. */ export interface Config { /** * The form this agent's model sees. `native` sends every visible schema, * `ptc` sends only `run_code` plus a generated SDK, `both` sends both. * Required rather than defaulted: the deployment default is what a preset * without this row already gets, so an omitted value would mean the row was * composed for nothing. */ mode: ToolPresentationMode } ``` 依赖：[`ToolPresentationMode`](subsystems/tools.zh.md) 来源：[`packages/core/agent-tool-presentation/src/index.ts:38`](../packages/core/agent-tool-presentation/src/index.ts) ## `@deepseek-ai/dsh-api-gateway` 需要：`typert` ```ts config-catalog /** Gateway transport configuration. */ export interface Config { /** WebSocket Ping interval from 1 through 2,147,483,647 milliseconds. @default 2000 */ readonly websocketHeartbeatIntervalMs?: number } ``` 来源：[`packages/api/gateway/src/index.ts:119`](../packages/api/gateway/src/index.ts) ## `@deepseek-ai/dsh-api-session-controller` 需要：`agentDefaultModel` · `agents` · `attachments` · `llm` · `sessions` · `sessionProjections` · `sessionQuery` · `typert` · `workspaceRegistry` ```ts config-catalog /** Session Controller deployment policy. */ export interface Config { /** Maximum cold Session artifact size eligible for one full projection observation. */ readonly coldBlankProbeMaxBytes?: number /** Override platform desktop-opener detection. */ readonly nativeOpen?: boolean } ``` 来源：[`packages/api/session-controller/src/index.ts:68`](../packages/api/session-controller/src/index.ts) ## `@deepseek-ai/dsh-api-settings-controller` ```ts config-catalog /** Native document-opening policy. */ export interface Config { /** Override platform desktop-opener detection. */ readonly nativeOpen?: boolean } ``` 来源：[`packages/api/settings-controller/src/index.ts:36`](../packages/api/settings-controller/src/index.ts) ## `@deepseek-ai/dsh-attachment-local` ```ts config-catalog /** Local attachment backend configuration. */ export interface Config { /** Explicit harness home; omitted follows `DSH_HOME`, then `~/.dsh`. */ dshHome?: string /** Maximum encoded bytes accepted for one submitted image. Default: 20 MiB. */ maxImageBytes?: number /** Maximum image count accepted in one submitted message. Default: 20. */ maxImagesPerMessage?: number /** Maximum aggregate encoded image bytes accepted in one submitted message. Default: 200 MiB. */ maxMessageImageBytes?: number /** Maximum intrinsic width multiplied by height accepted for one submitted image. Default: 64,000,000. */ maxImagePixels?: number /** Maximum intrinsic width and maximum intrinsic height accepted for one submitted image. Default: 8192px. */ maxImageDimension?: number /** Total-pixel budget of the stored provider-independent normalized image. */ normalizedImageMaxPixels?: number /** Long-edge pixel cap of the stored provider-independent normalized image, applied after the total-pixel budget. */ normalizedImageMaxDimension?: number /** * Encoded-byte target of the stored provider-independent normalized image; * the smallest quality-ladder output is kept when no quality fits. */ normalizedImageMaxBytes?: number /** Maximum simultaneous normalization or request-image transformations in this service instance. */ imageCompressionConcurrency?: number } ``` 来源：[`packages/attachment/attachment-local/src/index.ts:55`](../packages/attachment/attachment-local/src/index.ts) ## `@deepseek-ai/dsh-bash-local` 需要：`subprocess` ```ts config-catalog /** Plugin config (all optional — `static Config` supplies the defaults). */ export interface Config { /** Default working directory for commands (default: process.cwd()). */ cwd?: string /** Default foreground timeout in milliseconds. */ timeoutMs?: number /** Upper bound for per-call timeout overrides. */ maxTimeoutMs?: number /** Per-stream in-memory output cap; overflow spills to a temp file. */ maxOutputBytes?: number /** Per-stream spill-file cap; larger streams retain only their in-memory tail. */ maxSpillBytes?: number /** Grace period for kill escalation and inherited pipes; at most `MAX_TIMER_DELAY_MS`. */ graceMs?: number } ``` 来源：[`packages/shell/bash-local/src/index.ts:41`](../packages/shell/bash-local/src/index.ts) ## `@deepseek-ai/dsh-bash-sandbox` 需要：`subprocess` · `sandbox` · `sandboxPolicy` ```ts config-catalog /** * Plugin config: the local executor's knobs, verbatim. The sandbox policy — * the default mode and fallback `workspace-write` root — is NOT here: it lives * on `ctx.sandboxPolicy` (`@deepseek-ai/dsh-sandbox-policy`), which resolves * each calling session's mode and cwd for every enforcing capability. The runner * choice is likewise the `ctx.sandbox` provider's config, not this executor's. */ export type Config = LocalConfig ``` 依赖：[`LocalConfig`](#deepseek-aidsh-bash-local) 来源：[`packages/shell/bash-sandbox/src/index.ts:35`](../packages/shell/bash-sandbox/src/index.ts) ## `@deepseek-ai/dsh-client-connection` 需要：`webServer` · `credentials` ```ts config-catalog /** Plugin config: the deployment's non-loopback serving authorities. */ export interface ConnectionConfig { /** * Authorities this deployment serves beyond loopback: exact `host:port`, or * port-less `host` matching any port. The /api trust fence refuses any * request whose Host is neither loopback nor listed here, so a * non-loopback (`0.0.0.0`) deployment must declare the names it is reached * by; the Web runtime derives LAN IP literals from an active all-interface * bind. An entry that is not a bare, canonical authority fails plugin load. */ trustedHosts?: string[] /** Absolute browser-session lifetime in days. Default: 30. */ cookieMaxAgeDays?: number /** Maximum buffered JSON body for every `/api` request. Default: 300 MiB. */ maxRequestBodyBytes?: number } ``` 来源：[`packages/client/connection/src/index.ts:55`](../packages/client/connection/src/index.ts) ## `@deepseek-ai/dsh-client-hmr` 需要：`clientModules` · `webServer` ```ts config-catalog /** Plugin config, validated by the same-named schemastery schema. */ export interface Config { /** Bundle stat-poll interval in milliseconds (default 500, the build-side watcher's polling default). */ pollIntervalMs?: number } ``` 来源：[`packages/client/hmr/src/index.ts:31`](../packages/client/hmr/src/index.ts) ## `@deepseek-ai/dsh-code-runtime-worker-thread` ```ts config-catalog /** Plugin config: every execution cap, changeable from `cordis.yml` (no hardcoded tunables). */ export interface Config { /** * Busy-time budget in milliseconds: the run fails with kind `'timeout'` * once the worker's MEASURED event-loop active time * (`worker.performance.eventLoopUtilization()`) exceeds this. Metering * measured busy time — not wall time, not host-side pending-call * bookkeeping — is what makes the budget both fair (a program awaiting a * slow tool accrues nothing) and ungameable (a hot loop accrues whether * or not a decoy dispatch is in flight). */ computeMs?: number /** * Wall-clock ceiling in milliseconds; never pauses for anything. The * backstop for what busy-time cannot see (a program awaiting a promise * nobody will resolve). At most `2_147_483_647` (Node's maximum * `setTimeout` delay, about 24.9 days): a longer value is rejected at load * because `setTimeout` would clamp it to 1 ms. */ maxWallMs?: number /** * Hard cap for serialized log-array, completion-value, and failure-message payloads; * fixed result-envelope syntax is excluded. */ maxOutputBytes?: number /** The worker's max old-generation heap in MiB (`resourceLimits`); overflow kills the worker, surfacing as kind `'worker-exit'`. */ maxOldGenerationSizeMb?: number } ``` 来源：[`packages/code-runtime/code-runtime-worker-thread/src/index.ts:25`](../packages/code-runtime/code-runtime-worker-thread/src/index.ts) ## `@deepseek-ai/dsh-compaction-basic` 需要：`llm` · `tokenMeter` · `sessions` ```ts config-catalog /** Basic compaction configuration with an optional exact-target policy table. */ export interface BasicCompactionConfig extends CompactionPolicyConfig { /** Exact provider/model overrides; duplicate targets fail plugin load. */ modelPolicies?: ModelCompactPolicyConfig[] /** Enable automatic step-boundary pressure and overflow-recovery listeners. Defaults to `true`. */ auto?: boolean } /** Policy fields shared by the default policy and exact model overrides. */ export interface CompactionPolicyConfig { /** Compact at this fraction of the model's context window. Defaults to `0.8`. */ thresholdRatio?: number /** Recent context retained as a fraction of the model's window. Defaults to `0.16`. */ retainRatio?: number /** Absolute recent-context budget; mutually exclusive with `retainRatio`. */ retainTokens?: number /** Summary provider; set together with `summarizationModel`, or inherit the conversation target. */ summarizationProvider?: string /** Summary model; set together with `summarizationProvider`, or inherit the conversation target. */ summarizationModel?: string /** Provider generation cap for summarization. Defaults to `8192`. */ maxTokens?: number /** Extra attempts after the first compaction when pressure remains above threshold. Defaults to `1`. */ compactionRetries?: number /** Maximum retries after canonical context overflow; `0` disables recovery. Defaults to `1`. */ maxOverflowRetries?: number } /** Exact provider/model override merged over the default compaction policy. */ export interface ModelCompactPolicyConfig extends CompactionPolicyConfig { /** Registered provider route to match. */ provider: string /** Exact routed model id to match within `provider`. */ model: string } ``` 来源：[`packages/compaction/compaction-basic/src/types.ts:38`](../packages/compaction/compaction-basic/src/types.ts) ## `@deepseek-ai/dsh-compaction-tool-result-pruner` 需要：`tokenMeter` ```ts config-catalog /** Character-budget policy for deterministic tool-result pruning. */ export interface ToolResultPruneConfig { /** Prune when total text exceeds this many Unicode code points. Defaults to `8192`. */ thresholdChars?: number /** Maximum leading Unicode code points retained. Defaults to `4096`. */ headChars?: number /** Maximum trailing Unicode code points retained. Defaults to `1024`. */ tailChars?: number } ``` 来源：[`packages/compaction/compaction-tool-result-pruner/src/types.ts:5`](../packages/compaction/compaction-tool-result-pruner/src/types.ts) ## `@deepseek-ai/dsh-cordis-host-runner` 需要：`tools` ```ts config-catalog /** Runner configuration. */ export interface Config { /** Maximum synchronous VM evaluation time in milliseconds. */ vmTimeoutMs?: number } ``` 来源：[`packages/extensions/cordis-host-runner/src/index.ts:88`](../packages/extensions/cordis-host-runner/src/index.ts) ## `@deepseek-ai/dsh-credentials-local` ```ts config-catalog /** Plugin config: file location and hot-reload behavior. */ export interface Config { /** Credentials document path; defaults to `.credentials.yaml` under the harness home. */ path?: string /** Harness home used when `path` is omitted; defaults to `$DSH_HOME` or `~/.dsh`. */ dshHome?: string /** Watch the document and hot-publish external edits; defaults to true. */ watch?: boolean /** Watcher write-settle window in milliseconds; defaults to 100. */ debounceMs?: number } ``` 来源：[`packages/credentials/credentials-local/src/index.ts:64`](../packages/credentials/credentials-local/src/index.ts) ## `@deepseek-ai/dsh-e2b` ```ts config-catalog /** Configuration for the shared E2B sandbox owner. */ export interface Config { /** API key; omission reads `E2B_API_KEY`. It is never forwarded into the sandbox. */ apiKey?: string /** Shared remote working directory, created before adapters receive the sandbox. */ cwd?: string /** E2B sandbox lifetime in milliseconds; expiry always deletes the sandbox. */ timeoutMs?: number } ``` 来源：[`packages/e2b/e2b/src/index.ts:43`](../packages/e2b/e2b/src/index.ts) ## `@deepseek-ai/dsh-experimental-agent-team` 需要：`agents` · `sessions` · `sessionPersistence` · `sessionProjections` · `subagents` ```ts config-catalog /** Team-service deployment limits. */ export interface Config { /** Maximum immutable teammate names retained by one Team. */ readonly maxMembers?: number /** Maximum non-deleted tasks retained by one Team. */ readonly maxTasks?: number /** Maximum queued-minus-delivered messages for one target member. */ readonly maxPendingMessagesPerMember?: number /** Maximum UTF-8 bytes in one complete sender-framed delivery. */ readonly maxMessageBytes?: number /** Maximum milliseconds allowed for Team-owned runtime disposal. */ readonly disposalTimeoutMs?: number } ``` 来源：[`packages/experimental/agent-team/src/types.ts:125`](../packages/experimental/agent-team/src/types.ts) ## `@deepseek-ai/dsh-experimental-code-runtime-python` ```ts config-catalog /** Plugin config: every cap, changeable from `cordis.yml` (no hardcoded tunables). */ export interface Config { /** * RLIMIT_CPU in whole seconds (a positive integer — `setrlimit` in the child * rejects a float). The child sets the soft limit to `cpuSeconds` and the * hard limit to `cpuSeconds + 1`: the kernel delivers SIGXCPU at the soft * limit, which the host classifies as a `timeout`; the +1s hard limit is a * SIGKILL backstop for a program that traps SIGXCPU. Granularity is seconds — * a coarser counterpart to the worker backend's millisecond `computeMs`. */ cpuSeconds?: number /** Wall-clock ceiling in milliseconds; backstops CPU time for programs awaiting a promise nobody resolves. */ maxWallMs?: number /** * RLIMIT_AS in mebibytes; caps address space so a runaway allocation fails * cleanly. Not applied on Darwin, where the dyld shared cache mapped into * every process at exec exceeds any practical cap and the kernel rejects * the call; `cpuSeconds` and `maxWallMs` still bound the run there. Bounds * `maxLogBytes`/`maxValueBytes` at load on EVERY platform (this static check * runs on Darwin too, where only the runtime `setrlimit` is skipped): each * budget times a worst-case Unicode expansion must fit this byte count minus a * fixed interpreter baseline, so a near-budget output cannot breach the address * space during the child's build-and-encode. */ addressSpaceMb?: number /** * Shared byte budget for captured log text (host-side ledger). Bounded at load * against `addressSpaceMb`: the child builds and encodes a near-budget entry * under RLIMIT_AS with several copies live at once, so this cap times the * worst-case Unicode expansion must fit the address space left after the * interpreter baseline (see `addressSpaceMb`) — a load-time rejection, not a * runtime clamp. Also bounded at load by the host's configured heap like * `maxValueBytes` (see its JSDoc): the effective frame cap minus the frame * envelope. */ maxLogBytes?: number /** * Byte cap for the completion value. Bounded at load against `addressSpaceMb` * the same way `maxLogBytes` is: the child builds and encodes a near-budget * value under RLIMIT_AS with several copies live at once, so this cap times the * worst-case Unicode expansion must fit the address space left after the * interpreter baseline. Both budgets are ALSO bounded at load by the host's * configured heap: the effective frame cap (the protocol cap, or a lower * heap-derived ceiling when the host heap cannot safely parse a near-cap * frame — see `hostFrameParseCeiling`) minus the frame envelope, so a budget * whose honest frame could OOM the host's own JSON.parse is rejected up * front. */ maxValueBytes?: number /** SIGTERM→SIGKILL grace period on kill, matching bash-local's default. */ graceMs?: number /** * Absolute path, relative path, or basename of a CPython 3.10+ interpreter. * Resolved and validated once at plugin load under a five-second force-kill * deadline; a basename searches `PATH`. */ pythonBin?: string } ``` 来源：[`packages/experimental/code-runtime-python/src/index.ts:42`](../packages/experimental/code-runtime-python/src/index.ts) ## `@deepseek-ai/dsh-experimental-inspector` 需要：`webServer` ```ts config-catalog /** Host plugin configuration. Fetch capture is enabled by default. */ export interface Config extends Omit { /** Browser origins allowed to open the Client ingest WebSocket. */ clientOrigins?: string[] } /** User-facing Host options; every memory and lifecycle bound is configurable. */ export interface InspectorOptions { /** Loopback address used by the Worker HTTP and WebSocket endpoint. */ readonly host?: '127.0.0.1' /** First port to bind; occupied ports advance until one is available. */ readonly port?: number /** Additional exact browser origins admitted to the Client ingest socket. */ readonly clientOrigins?: readonly string[] /** Whether to observe calls made through the current global fetch function. */ readonly captureFetch?: boolean /** Maximum request-body prefix retained for one fetch. */ readonly maxRequestBodyBytes?: number /** Maximum response-body prefix retained for one fetch. */ readonly maxResponseBodyBytes?: number /** Maximum raw bytes encoded into one body observation. */ readonly maxBodyChunkBytes?: number /** Maximum total request and response body bytes retained by the Worker. */ readonly maxJournalBytes?: number /** Maximum active and completed fetch requests retained by the Worker. */ readonly maxRetainedRequests?: number /** Maximum encoded bytes accepted in one source transport frame. */ readonly maxSourceFrameBytes?: number /** Maximum observation records accepted in one source batch. */ readonly maxSourceRecordsPerFrame?: number /** Maximum records waiting in one producer queue. */ readonly maxQueuedRecords?: number /** Maximum encoded bytes waiting in one producer queue. */ readonly maxQueuedBytes?: number /** Maximum time allowed for the Worker to become ready. */ readonly startupTimeoutMs?: number /** Grace period before a stopping Worker is terminated. */ readonly stopTimeoutMs?: number /** Initial upper bound for randomized Client reconnect delay. */ readonly clientReconnectBaseMs?: number /** Maximum upper bound for randomized Client reconnect delay. */ readonly clientReconnectMaxMs?: number /** Deadline for one Worker-to-Client Runtime or Sources request. */ readonly clientRuntimeTimeoutMs?: number /** Deadline for one non-CDP semantic query. */ readonly queryTimeoutMs?: number /** Maximum live object handles retained per Client Runtime session. */ readonly maxClientRuntimeObjects?: number /** Maximum descriptors returned by one Client property request. */ readonly maxClientRuntimeProperties?: number /** Maximum encoded bytes read for one Client script or source map. */ readonly maxClientSourceBytes?: number /** Maximum Context and Fiber nodes retained in one realm snapshot. */ readonly maxCordisNodes?: number /** Disconnected Cordis snapshots retained after their live realm closes. */ readonly maxDisconnectedCordisTrees?: number } ``` 来源：[`packages/experimental/inspector/src/index.ts:66`](../packages/experimental/inspector/src/index.ts) ## `@deepseek-ai/dsh-experimental-tool-agent-team` 需要：`agents` · `agentTeams` · `tools` · `systemPrompt` ```ts config-catalog /** Tool routing configuration. */ export interface Config { /** Continuable-subagent provider used for fresh teammates. */ readonly freshProvider?: string /** Continuable-subagent provider used for completed-prefix fork teammates. */ readonly forkProvider?: string } ``` 来源：[`packages/experimental/tool-agent-team/src/index.ts:17`](../packages/experimental/tool-agent-team/src/index.ts) ## `@deepseek-ai/dsh-file-reference-local` 需要：`agents` · `sessionProjections` ```ts config-catalog /** Local file-reference discovery configuration. */ export interface Config { /** Maximum ranked candidates returned for one query. */ maxResults?: number /** Maximum indexed files and directories per agent workspace. */ maxEntries?: number /** Directory basenames never traversed or offered. */ excludedDirectories?: string[] } ``` 来源：[`packages/context/file-reference-local/src/index.ts:34`](../packages/context/file-reference-local/src/index.ts) ## `@deepseek-ai/dsh-fs-local` ```ts config-catalog /** Configuration for the local filesystem backend. */ export interface Config { /** Base directory for relative paths. Defaults to `process.cwd()`. */ cwd?: string /** * Exclusive UTF-8 byte limit on each overwrite-diff side, capped by the * runtime's safe allocation/decode maximum. Defaults to 10 MiB. */ diffBasisMaxBytes?: number } ``` 来源：[`packages/fs/fs-local/src/index.ts:41`](../packages/fs/fs-local/src/index.ts) ## `@deepseek-ai/dsh-fs-sandbox` 需要：`sandboxPolicy` ```ts config-catalog /** * Plugin config: the local backend's knobs verbatim (`cwd` resolution default * and `diffBasisMaxBytes` overwrite-presentation bound). The sandbox default * (mode + `workspace-write` fallback root) is NOT here — `ctx.sandboxPolicy` * resolves each calling session for every enforcing capability. */ export type Config = LocalConfig ``` 依赖：[`LocalConfig`](#deepseek-aidsh-fs-local) 来源：[`packages/fs/fs-sandbox/src/index.ts:45`](../packages/fs/fs-sandbox/src/index.ts) ## `@deepseek-ai/dsh-goal` 需要：`agents` · `sessionProjections` ```ts config-catalog /** Deployment defaults for goal creation. */ export interface Config { /** Total rounds used when a create request omits its own cap. */ defaultMaxGoalRounds?: number } ``` 来源：[`packages/goal/goal/src/index.ts:172`](../packages/goal/goal/src/index.ts) ## `@deepseek-ai/dsh-headless` 需要：`agentDefaultModel` · `agents` · `sessions` ```ts config-catalog /** Plugin config: the task resolved from this app's injected provider service. */ export interface Config { /** The prompt text for the single run. */ task: string } ``` 来源：[`packages/bundle/headless/src/index.ts:33`](../packages/bundle/headless/src/index.ts) ## `@deepseek-ai/dsh-hooks-claude-code` 需要：`shell` · `sessionProjections` ```ts config-catalog /** Plugin config: where the CC hook config lives + substitution roots. */ export interface Config { /** * Path to a `hooks.json` or a settings file whose `hooks` key holds the config. * Process-level: read once at load, a relative path resolves against the process * launch cwd, so one config applies to the whole process. * TODO(per-session-hook-config): per-session discovery of a project-local * `hooks.json` from each `session/new.cwd`. */ configPath: string /** * Replaces `${CLAUDE_PLUGIN_ROOT}` in command strings (the plugin's root dir). */ pluginRoot?: string /** * Replaces `${CLAUDE_PROJECT_DIR}` in command strings AND is exported as the * `CLAUDE_PROJECT_DIR` env var for hook processes. When omitted, the env var * defaults per-run to the agent's session workspace (`session.header.cwd`, the * same dir the hook runs in) — Claude Code always exports this var, and common * unmodified hooks reference `$CLAUDE_PROJECT_DIR` for project-relative paths. */ projectDir?: string /** Default per-hook timeout in ms when a hook sets none (CC default: 600000). */ defaultTimeoutMs?: number /** Character cap for the `hook/result` event's persisted stderr summary. */ stderrSummaryMaxChars?: number } ``` 来源：[`packages/hooks/hooks-claude-code/src/index.ts:46`](../packages/hooks/hooks-claude-code/src/index.ts) ## `@deepseek-ai/dsh-hooks-codex` 需要：`shell` · `sessionProjections` ```ts config-catalog /** Plugin config: where the Codex hooks.json lives + the model name for payloads. */ export interface Config { /** * Path to a Codex `hooks.json`. Process-level: read once at load, a relative * path resolves against the process launch cwd. * TODO(per-session-hook-config): per-session project-local discovery from each * `session/new.cwd`. */ configPath: string /** The model name stamped on every payload (Codex includes `model` on each event). */ model?: string /** Default per-hook timeout in ms when a hook sets none (Codex default: 600000). */ defaultTimeoutMs?: number /** Character cap for the `hook/result` event's persisted stderr summary. */ stderrSummaryMaxChars?: number } ``` 来源：[`packages/hooks/hooks-codex/src/index.ts:45`](../packages/hooks/hooks-codex/src/index.ts) ## `@deepseek-ai/dsh-host-directory-picker-browse` ```ts config-catalog /** Validated plugin configuration. */ export interface Config { /** Complete-result bound of one listing level; see {@link BrowseDirectoryPicker.Config}. */ maxEntries: number } ``` 来源：[`packages/host/directory-picker-browse/src/index.ts:181`](../packages/host/directory-picker-browse/src/index.ts) ## `@deepseek-ai/dsh-host-frontend-static` 需要：`webServer` · `connection` ```ts config-catalog /** Plugin config: the dist anchor. */ export interface Config { /** Absolute path of index.html inside the dist root. */ distIndex: string } ``` 来源：[`packages/host/frontend-static/src/index.ts:30`](../packages/host/frontend-static/src/index.ts) ## `@deepseek-ai/dsh-host-webserver` ```ts config-catalog /** Web server listen and response-compression config. */ export interface Config { /** Listen host; the two supported values are loopback and all-interfaces. */ host: '127.0.0.1' | '0.0.0.0' /** Listen port; zero requests an OS-assigned port. */ port: number /** Response compression for socket-backed HTTP requests. @default 'none' */ compression?: 'none' | 'gzip' /** Gzip DEFLATE level from 0 through 9. @default 1 */ compressionLevel?: number /** Minimum known response length eligible for gzip; unknown-length streams are eligible. @default 1024 */ compressionThresholdBytes?: number } ``` 来源：[`packages/host/webserver/src/index.ts:59`](../packages/host/webserver/src/index.ts) ## `@deepseek-ai/dsh-invariants` ```ts config-catalog /** Runtime invariant selection configured on the service plugin. */ export interface Config { /** Global switch; defaults to `true`. */ readonly enabled?: boolean /** Case-sensitive JavaScript regex sources that admit package names; empty admits all. */ readonly package_allowlist?: string[] /** Case-sensitive JavaScript regex sources that exclude package names after allowlist matching. */ readonly package_blocklist?: string[] } ``` 来源：[`packages/runtime-diagnostics/invariants/src/index.ts:15`](../packages/runtime-diagnostics/invariants/src/index.ts) ## `@deepseek-ai/dsh-jobs-local` ```ts config-catalog /** Configuration for the process-local job registry. */ export interface Config { /** * Maximum `running` plus `stopping` jobs per exact owner or in the shared unowned bucket; * omission defaults to 10. */ maxConcurrentJobsPerOwner?: number } ``` 来源：[`packages/jobs/jobs-local/src/index.ts:31`](../packages/jobs/jobs-local/src/index.ts) ## `@deepseek-ai/dsh-llm-deepseek` 需要：`llm` ```ts config-catalog /** * Plugin config, validated by the same-named schemastery schema and doubling * as the `llm-deepseek` settings-section shape. Every field is optional in * yml: a missing API key resolves through {@link Config.apiKeyEnv} at each * request (a request without any key fails with `MISSING_CREDENTIAL`, not at * plugin load), omitted thinking mode uses the provider default, and omitted * reasoning effort resolves to `high`. */ export interface Config { /** Credential reference (environment-variable name) resolved per request; defaults to `DEEPSEEK_API_KEY`. */ apiKeyEnv?: string /** Endpoint base; falls back to $DEEPSEEK_BASE_URL from a trusted environment layer, then the public API. */ baseURL?: string /** Deployment thinking policy; `disabled` limits every conversation request to `off`. */ thinking?: 'enabled' | 'disabled' /** Default thinking effort (default `high`); `off` disables thinking per request. */ reasoningEffort?: 'off' | 'low' | 'high' | 'max' /** Default per-request output cap (default 256,000); a model's own cap and explicit request values win. */ maxTokens?: number /** Positive context capacity used when the selected model has no exact value (default 1,000,000). */ defaultContextWindow?: number /** Advisory models shown by discovery consumers; defaults to V4 Flash, V4 Pro, and V4 Flash Vision Exp. */ models?: DeepSeekCatalogModel[] /** Maximum provider idle time while one stream read is outstanding (default five minutes). */ streamIdleTimeoutMs?: number /** Maximum accumulated file-referenced image bytes per chat request (default 128 MiB). */ maxRequestFilesBytes?: number /** Maximum accumulated base64 image payload after Files API fallback (default 20 MiB). */ maxInlineRequestImageBytes?: number /** Maximum number of represented images per chat request (default 600). */ maxImagesPerRequest?: number /** Raw-byte removal step after the request exceeds its file bound (default 64 MiB). */ imageOffloadByteQuantum?: number /** Base64-byte removal step after inline fallback exceeds its bound (default 10 MiB). */ inlineImageOffloadByteQuantum?: number /** Image-count removal step after the request exceeds its count bound (default 20). */ imageOffloadCountQuantum?: number /** Maximum duration of one request-image Files API resolution (default one minute). */ filesApiTimeoutMs?: number /** Explicit lifetime assigned to each uploaded image (default seven days). */ fileExpiresAfterSeconds?: number /** Remaining lifetime below which an indexed file is replaced (default one hour). */ fileRefreshMarginSeconds?: number /** Oldest harness-owned files deleted before one quota-recovery upload retry (default 100). */ fileQuotaCleanupBatch?: number /** Provider-owned model-request retry policy; omission uses normal mode with five retries. */ retryPolicy?: RetryPolicyConfig } /** One optional model entry advertised by the direct-fetch adapter. */ export interface DeepSeekCatalogModel { /** Wire model id accepted by the configured endpoint. */ id: string /** Selector label; defaults to {@link id}. */ name?: string /** Optional selector detail for deployments with similar model variants. */ description?: string /** Known combined request/response context capacity; omitted when deployment metadata is unavailable. */ contextWindow?: number /** Per-request output cap for this model; omission falls back to the profile's {@link DeepSeekConnectionOptions.maxTokens}. */ maxTokens?: number /** Accepted request modalities; omission is text-only. */ inputModalities?: ModelModality[] /** Total-pixel budget for one deterministic request preview, or the 512-by-512 `low` preset. */ imagePixelBudget?: number | 'low' /** Encoded-byte target for one deterministic request preview; the smallest quality-ladder output is used when no quality fits. */ imageMaxBytes?: number } ``` 依赖：[`ModelModality`](../packages/llm/llm/src/index.ts) · [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts) 来源：[`packages/llm/llm-deepseek/src/index.ts:125`](../packages/llm/llm-deepseek/src/index.ts) ## `@deepseek-ai/dsh-llm-pi-ai` 需要：`llm` ```ts config-catalog /** Plugin configuration: the provider routes this instance owns. */ export interface Config { /** * pi-ai provider routes, keyed by provider. An empty (or omitted) dict is * the dormant settings-driven posture: the adapter mounts with no routes * and registers them the moment a settings section supplies profiles. */ providers?: Record } /** Configuration for one pi-ai provider route; the `providers` dict key IS the route. */ export interface PiAiProviderProfile { /** Credential reference (environment-variable name) resolved per request through `ctx.credentials`. */ apiKeyEnv?: string /** Name shown by configuration surfaces; defaults to the route key. */ displayName?: string /** * Wire protocol every model on this route speaks. Omission keeps each * installed catalog model's own protocol, which is why a catalog route needs * no protocol at all; a route the catalog does not ship must name one. */ api?: string /** Endpoint for this route's models; defaults to the installed catalog's endpoint. */ baseURL?: string /** * This route's model catalog. Omission serves the installed catalog for the * route unchanged; an explicit list replaces it, each entry defaulting its * unset fields from the installed model of the same id. */ models?: PiAiModelProfile[] /** * Installed-catalog customizations by model id: each entry reshapes that * one model with the same fields a {@link models} entry takes, while the * rest of the catalog keeps serving untouched. Only meaningful on a catalog * route with no `models` list — `models` already replaces the catalog, so * an override beside it, on a route the catalog does not ship, or naming a * model the catalog does not describe is refused rather than skipped. */ modelOverrides?: Record /** * pi-ai wire-compatibility switches defaulting every model on this route * whose protocol declares them; each model's own `compat` overrides per * field. What neither sets keeps the installed catalog entry's value, then * pi-ai's own detection. A switch no model on the route could read is * refused rather than left looking applied. */ compat?: PiAiCompatProfile /** * Context capacity for a model this route lists that neither the entry nor * the installed catalog sizes (default 262,144). A guess by construction, so * a deployment whose gateway serves smaller models corrects it here. */ defaultContextWindow?: number /** * Output capability for a model this route lists that neither the entry nor * the installed catalog sizes (default 32,768). This sizes the model; it * never becomes a per-request cap on its own. */ defaultMaxTokens?: number /** * Request modalities for a model this route lists that neither its entry's * {@link PiAiModelProfile.input} nor the installed catalog declares (default * `[text]`). A fallback like the capacities above, not an override: a * catalog model keeps the modalities the catalog records for it, and this * value never narrows one. A gateway serving vision models the catalog does * not describe declares `[text, image]` once here instead of on every entry. * Unlike an entry's list, this one may not be empty — nothing sits below it * to answer instead. */ defaultInput?: PiAiModality[] /** Provider request headers, validated against Fetch when the profile resolves; Harness attribution wins reserved names. */ headers?: Record /** Provider-neutral pi-ai reasoning level. */ reasoning?: ModelThinkingLevel /** Token budgets used by reasoning providers that support them. */ thinkingBudgets?: ThinkingBudgets /** Prompt-cache retention preference. */ cacheRetention?: CacheRetention /** Streaming transport preference. */ transport?: Transport /** HTTP/provider SDK timeout in milliseconds. */ timeoutMs?: number /** WebSocket connection timeout in milliseconds. */ websocketConnectTimeoutMs?: number /** Maximum provider idle time while one stream read is outstanding. */ streamIdleTimeoutMs?: number /** * Maximum base64-encoded image payload per request. When a request's * accumulated images exceed it, the oldest images are replaced by text * placeholders until the request fits, so a long session keeps completing * requests instead of being rejected by a request-size cap. */ maxRequestImageBytes?: number /** Total-pixel budget for each deterministic inline request version. */ requestImagePixelBudget?: number /** * Raw encoded-byte target for each deterministic inline request version; * the smallest quality-ladder output is used when no quality fits. */ requestImageMaxBytes?: number /** Provider-owned model-request retry policy; omission uses normal mode with five retries. */ retryPolicy?: RetryPolicyConfig } /** One configured model entry: an id plus the catalog fields it overrides. */ export interface PiAiModelProfile { /** Model id sent to the provider and accepted by {@link GenerateOptions.model}. */ id: string /** Display name for selectors; defaults to the catalog name, then the id. */ name?: string /** Maximum combined request and response context in tokens. */ contextWindow?: number /** * Maximum output tokens. Configuring one also makes it this model's * per-request default; a value inherited from the installed catalog, or the * route's fallback, is the model's capability and never becomes a request * default on its own. */ maxTokens?: number /** * Request modalities this model accepts. Absent — or empty, which describes * a model that accepts nothing and so states no answer either — keeps the * installed catalog entry's modalities, then the route's `defaultInput`. * Declaring images is what makes a hand-declared vision model usable, and * declaring text alone corrects a catalog model whose gateway does not serve * what the catalog records. This is a claim about the endpoint, not a check * of it: nothing interrogates a gateway for what it accepts, so a model * claiming images its endpoint refuses is refused by the provider instead, * mid-turn. */ input?: PiAiModality[] /** * Selectable reasoning efforts. Absent inherits the installed catalog * entry's capability (a hand-declared model has none and does not reason); * `false` declares a non-reasoning model, which is how a profile strips * reasoning from a catalog model its gateway cannot serve; a non-empty dict * declares the offered levels and their wire spellings. */ reasoningEfforts?: false | PiAiReasoningEfforts /** pi-ai wire-compatibility switches for this model, winning over the route's per field; one its protocol does not declare is refused. */ compat?: PiAiCompatProfile } /** * Customization of one installed catalog model, keyed by its id in the * route's `modelOverrides` dict — the same fields a `models` entry may set, * with the id living in the key. Unlike a `models` list, overrides leave the * rest of the catalog serving untouched, which is what makes "correct one * model, keep the other thirty-seven" a three-line edit. */ export type PiAiModelOverride = Omit /** * pi-ai wire-compatibility switches, set on the route (its models' default) or * per model (winning over the route, field by field). * * pi-ai decides each of these from the provider id and baseURL when no layer * sets it, and a private gateway's URL says nothing: for an endpoint it does * not recognize the detection answers as though it were OpenAI itself, which * is wrong for most OpenAI-compatible gateways. So every field here is one a * deployment must be able to state because nothing can infer it, while the * fields pi-ai's catalog sets for a named vendor stay withheld. * * A field belongs to the protocols whose upstream compat type declares it: a * model-level switch its protocol does not take fails resolution, and a * route-level one skips past models it cannot fit. "The three Responses * protocols" below means `openai-responses`, `azure-openai-responses`, and * `openai-codex-responses`, which pi-ai gives one shared compat type, so a * switch settable on one is settable on all three. */ export interface PiAiCompatProfile { /** Whether the endpoint accepts `store`; `openai-completions`. */ supportsStore?: boolean /** * Whether the endpoint accepts the `developer` role for the system prompt, * which pi-ai sends only to a reasoning model; `false` keeps `system`. * `openai-completions` and the three Responses protocols. */ supportsDeveloperRole?: boolean /** Whether the endpoint accepts `reasoning_effort`; `openai-completions`. */ supportsReasoningEffort?: boolean /** Whether the endpoint accepts `stream_options: {include_usage: true}`; `openai-completions`. */ supportsUsageInStreaming?: boolean /** * Whether streams include `finish_reason`; `false` lets pi-ai infer the * terminal reason when the stream ends; `openai-completions`. */ supportsFinishReason?: boolean /** Which output-cap field the endpoint reads; `openai-completions`. */ maxTokensField?: NonNullable /** Whether tool results must carry `name`; `openai-completions`. */ requiresToolResultName?: boolean /** Whether a user message after tool results needs an assistant message between; `openai-completions`. */ requiresAssistantAfterToolResult?: boolean /** Whether thinking blocks must travel as text in `` delimiters; `openai-completions`. */ requiresThinkingAsText?: boolean /** Whether replayed assistant messages need an empty `reasoning_content` while reasoning is on; `openai-completions`. */ requiresReasoningContentOnAssistantMessages?: boolean /** Reasoning parameter format the endpoint expects; `openai-completions`. */ thinkingFormat?: PiAiThinkingFormat /** * Kwargs sent as `chat_template_kwargs`, which pi-ai reads only under the * two `chat-template` thinking formats; `openai-completions`. Nothing checks * that pairing: the format in force may come from the installed catalog * entry or from pi-ai's own baseURL detection, neither of which resolution * can read, so kwargs set beside another format are sent nowhere. */ chatTemplateKwargs?: NonNullable /** Arguments sent as `chat_template_args` under the `baseten` thinking format; `openai-completions`. */ chatTemplateArgs?: NonNullable /** Whether the endpoint accepts `thinking_token_budget` to cap vLLM reasoning; `openai-completions`. */ supportsThinkingTokenBudget?: boolean /** * Whether the endpoint accepts `strict` in tool definitions; * `openai-completions`, the three Responses protocols, `bedrock-converse-stream`. */ supportsStrictMode?: boolean /** Prompt-cache marker convention; `openai-completions`. */ cacheControlFormat?: NonNullable /** * Whether the endpoint accepts long prompt-cache retention; * `openai-completions`, the three Responses protocols, `anthropic-messages`. */ supportsLongCacheRetention?: boolean /** Whether the endpoint accepts per-tool `eager_input_streaming`; `anthropic-messages`. */ supportsEagerToolInputStreaming?: boolean /** Whether the endpoint accepts `cache_control` on tool definitions; `anthropic-messages`. */ supportsCacheControlOnTools?: boolean /** Whether the endpoint accepts the `temperature` request field; `anthropic-messages`. */ supportsTemperature?: boolean /** Whether to force adaptive thinking regardless of model id; `anthropic-messages`. */ forceAdaptiveThinking?: boolean /** Whether to replay an empty thinking signature instead of converting thinking to text; `anthropic-messages`. */ allowEmptySignature?: boolean /** Whether the endpoint accepts Anthropic strict tool schemas; `anthropic-messages`. */ supportsStrictTools?: boolean } /** One request modality a pi-ai model may accept. */ export type PiAiModality = Model['input'][number] /** * Selectable reasoning efforts for one model: each key is a level the model * offers (and selectors show), and its value is the wire spelling dispatch * sends for it. `off` alone may leave its value empty — "supported, send * nothing" — because for most providers not thinking is the parameter's * absence; every other declared level must name a wire value. A level absent * from the dict is not offered. */ export type PiAiReasoningEfforts = Partial> /** One reasoning-dispatch wire format a profile may name. */ export type PiAiThinkingFormat = NonNullable ``` 依赖：`Api`（`@earendil-works/pi-ai`）· `CacheRetention`（`@earendil-works/pi-ai`）· `Model`（`@earendil-works/pi-ai`）· `ModelThinkingLevel`（`@earendil-works/pi-ai`）· `OpenAICompletionsCompat`（`@earendil-works/pi-ai`）· [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts) · `ThinkingBudgets`（`@earendil-works/pi-ai`）· `Transport`（`@earendil-works/pi-ai`) 来源：[`packages/llm/llm-pi-ai/src/config.ts:213`](../packages/llm/llm-pi-ai/src/config.ts) ## `@deepseek-ai/dsh-llm-replay` 需要：`llm` ```ts config-catalog /** Plugin config: the {@link ReplayConfig} inputs, each defaulting to its `DSH_SNAPSHOT_*` env var in `apply`. */ export interface Config { /** Override the fixture path; defaults to `$DSH_SNAPSHOT_FILE`. */ file?: string /** Override the sidecar path; defaults to `$DSH_SNAPSHOT_OVERRIDE`. */ overrideFile?: string /** * Override the child-log paths; defaults to `$DSH_SNAPSHOT_CHILD_FILES` (a * path-separator-delimited list). Each is a recorded subagent session log for * a nested-agent scenario; absent/empty for a single-session scenario. */ childFiles?: string[] /** Optional replay-only provider catalog; absent or empty selects catch-all waterfall replay. */ providers?: ReplayProviderConfig[] /** Optional per-chunk pacing delay in ms (see {@link ReplayConfig.paceMs}); absent keeps burst yield. */ paceMs?: number } /** One provider route exposed by the replay adapter. */ export interface ReplayProviderConfig { /** Provider route used for replay requests. */ id: string /** Selector label; defaults to {@link id}. */ name?: string /** Advisory models exposed to replay scenarios that exercise discovery. */ models?: ReplayModelConfig[] /** Optional provider-owned retry policy used by assembled recovery snapshots. */ retryPolicy?: RetryPolicyConfig } /** One model exposed by a replay-only provider catalog. */ export interface ReplayModelConfig { /** Model id used for replay requests. */ id: string /** Selector label; defaults to {@link id}. */ name?: string /** Optional selector description. */ description?: string /** Optional positive integer context capacity published by the replay adapter. */ contextWindow?: number /** Optional declared input modalities, so a scenario can exercise capability gates (e.g. image-capable `read_image`). */ inputModalities?: readonly ModelModality[] /** * Optional per-request output cap the replay route materializes when callers * omit one, so replay reconstructs the request header a live catalog produced. */ defaultMaxTokens?: number /** * Optional flat visual-token price the replay route declares for every * retained request image, so keyless scenarios exercise route-priced * request pressure; each occurrence is priced at this value plus its * request-preview handle text. Requires {@link inputModalities} to include * `image` — a text-only route never sends visual tokens. Absent declares * no image pricing. */ imageRequestTokens?: number /** Optional reasoning-effort ids the replay route accepts, in display order. */ reasoningEfforts?: string[] /** * Optional effort materialized when callers omit one; must appear in * {@link reasoningEfforts} or call resolution rejects the route. */ defaultReasoningEffort?: string } ``` 依赖：[`ModelModality`](../packages/llm/llm/src/index.ts) · [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts) 来源：[`packages/test-support/llm-replay/src/index.ts:924`](../packages/test-support/llm-replay/src/index.ts) ## `@deepseek-ai/dsh-llm-retry` 需要：`agents` · `sessionProjections` ```ts config-catalog /** This policy executor has no config; providers own `retryPolicy`. */ export type Config = Readonly> ``` 来源：[`packages/llm/llm-retry/src/index.ts:25`](../packages/llm/llm-retry/src/index.ts) ## `@deepseek-ai/dsh-lsp-stdio` 需要：`fs` · `lsp` · `subprocess` ```ts config-catalog /** Plugin configuration: provider id → local language-server configuration. */ export interface Config { /** Non-empty table of stable provider ids to independent local server configurations. */ servers: Record } /** One configured local language server and its host bounds. */ export interface LspLocalServerConfig { /** Executable to spawn (absolute, or resolved on PATH at load). */ command: string /** Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). */ extensionToLanguage: Record /** Arguments passed to the executable (no shell). Default `[]`. */ args?: string[] /** Extra env vars merged on top of the scrubbed ambient env. Default `{}`. */ env?: Record /** Static `initialize` options forwarded to the server. Default `null`. */ initializationOptions?: unknown /** Static answer to every `workspace/configuration` item. Default `null`. */ configuration?: unknown /** Largest single framed message accepted from the server (bytes). Default 16000000. */ maxMessageBytes?: number /** Largest stderr tail retained for diagnostics (bytes). Default 1000000. */ maxStderrBytes?: number /** Largest source file this host will open (bytes). Default 4000000. */ maxDocumentBytes?: number /** Graceful `shutdown`/`exit` budget before escalation (ms). Default 5000. */ shutdownTimeoutMs?: number /** Request-cancel and SIGTERM→SIGKILL grace (ms). Default 2000. */ killGraceMs?: number } ``` 来源：[`packages/lsp/lsp-stdio/src/index.ts:82`](../packages/lsp/lsp-stdio/src/index.ts) ## `@deepseek-ai/dsh-mcp-client` 需要：`tools` ```ts config-catalog /** Configuration for one stdio or Streamable HTTP MCP server. */ export type Config = StdioConfig | StreamableHttpConfig /** Config for connecting to an MCP server via a spawned child process over stdio. */ export interface StdioConfig { /** Selects child-process stdio transport. */ transport: 'stdio' /** * Stable local namespace for this server's model-facing tool names * (`mcp____`). Must match `[A-Za-z0-9_-]{1,32}` and be * unique across live mcp-client instances. */ serverName: string /** Executable used to start the server. */ command: string /** Arguments passed directly, without shell interpolation. */ args: string[] /** Extra env vars merged on top of scrubbed ambient env. */ env: Record /** Working directory for the child process. */ cwd: string /** Per-tool-call timeout in milliseconds. */ toolCallTimeoutMs: number /** Fail plugin activation when the initial connection or tool synchronization fails. */ failOnStartupError: boolean /** Automatic reconnect policy after a lost connection; omission uses the defaults. */ reconnect?: ReconnectConfig } /** Config for connecting to an MCP server over Streamable HTTP (SSE). */ export interface StreamableHttpConfig { /** Selects Streamable HTTP transport. */ transport: 'streamable-http' /** * Stable local namespace for this server's model-facing tool names * (`mcp____`). Must match `[A-Za-z0-9_-]{1,32}` and be * unique across live mcp-client instances. */ serverName: string /** MCP endpoint URL. */ url: string /** Additional headers attached to MCP requests. */ headers: Record /** Per-tool-call timeout in milliseconds. */ toolCallTimeoutMs: number /** Fail plugin activation when the initial connection or tool synchronization fails. */ failOnStartupError: boolean /** Automatic reconnect policy after a lost connection; omission uses the defaults. */ reconnect?: ReconnectConfig } /** Automatic reconnect policy for one MCP server connection. */ export interface ReconnectConfig { /** Reconnect automatically after a lost connection (default true). */ enabled?: boolean /** First reconnect delay in milliseconds; doubles per consecutive failed attempt (default 500). */ initialDelayMs?: number /** Backoff ceiling in milliseconds; also the uptime after which the attempt budget resets (default 30000). */ maxDelayMs?: number /** Consecutive failed attempts per outage before giving up for good (default 10). */ maxAttempts?: number } ``` 来源：[`packages/mcp/mcp-client/src/index.ts:98`](../packages/mcp/mcp-client/src/index.ts) ## `@deepseek-ai/dsh-message-feedback` 需要：`storageDomain` · `sessionPersistence` · `sessions` ```ts config-catalog /** Required deployment policy for optional notes. */ export interface Config { /** Maximum UTF-8 byte length accepted for one note. */ readonly maxNoteBytes: number } ``` 来源：[`packages/feedback/message-feedback/src/index.ts:50`](../packages/feedback/message-feedback/src/index.ts) ## `@deepseek-ai/dsh-permission-presets` 需要：`shell` · `approval` · `sessions` · `sessionProjections` ```ts config-catalog /** The {@link PermissionPresetService} config: preset table and composition default. */ export interface Config { /** * The preset table: name → knob bundle. Defaults to `workspace-write` * (workspace-write + ask) and `danger-full-access` (danger-full-access + * never). The name `custom` is reserved for the derived not-a-preset state. */ presets?: Record /** * Default for new sessions. When omitted, the preset matching the composed * sandbox and approval defaults is used. */ defaultPreset?: string } /** One preset's sandbox/approval bundle and optional client presentation. */ export interface PresetSpec { /** The `sandbox/mode` value the preset writes through. */ sandbox: SandboxMode /** The `approval/policy` value the preset writes through. */ approval: ApprovalPolicy /** The display label a client shows for this preset; the raw table key when omitted. */ name?: string /** One user-facing sentence on what the preset means; omitted when not configured. */ description?: string } ``` 依赖：[`ApprovalPolicy`](subsystems/approval.zh.md) · [`SandboxMode`](subsystems/sandbox.zh.md) 来源：[`packages/interaction/permission-presets/src/index.ts:143`](../packages/interaction/permission-presets/src/index.ts) ## `@deepseek-ai/dsh-persona` 需要：`systemPrompt` ```ts config-catalog /** Plugin config: the persona text this composition contributes. */ export interface Config { /** * Persona prose rendered as the `deployment:persona` section. A template: * complete `{{…}}` groups interpolate strictly against registered prompt * variables. Empty text drops the section at render, matching the registry. */ text: string /** Make this persona the complete system prompt, suppressing every other section. */ complete?: boolean /** Suppress dynamic runtime-context snapshots for this persona's agent scope. */ includeRuntimeContext?: boolean } ``` 来源：[`packages/preset/persona/src/index.ts:30`](../packages/preset/persona/src/index.ts) ## `@deepseek-ai/dsh-plan-mode` 需要：`tools` · `systemPrompt` · `sessionProjections` ```ts config-catalog /** Deployment-owned plan guidance. */ export interface PlanModeConfig { /** Guidance rendered as the `plan:policy` prompt section while plan mode is active. */ section: string } ``` 来源：[`packages/plan/plan-mode/src/index.ts:63`](../packages/plan/plan-mode/src/index.ts) ## `@deepseek-ai/dsh-plugin-package-inventory-deepseek` 需要：`agents` · `deepseekLlmApiExtensions` · `loader` ```ts config-catalog /** Plugin-package request contribution configuration. */ export interface Config { /** Contribute `dsh_plugin_packages` to official DeepSeek requests. Defaults to `true`. */ enabled?: boolean } ``` 来源：[`packages/llm/plugin-package-inventory-deepseek/src/index.ts:31`](../packages/llm/plugin-package-inventory-deepseek/src/index.ts) ## `@deepseek-ai/dsh-pwsh-local` 需要：`subprocess` ```ts config-catalog /** Plugin config (all optional — `static Config` supplies the defaults). */ export interface Config { /** Default working directory for commands (default: process.cwd()). */ cwd?: string /** Default foreground timeout in milliseconds. */ timeoutMs?: number /** Upper bound for per-call timeout overrides. */ maxTimeoutMs?: number /** Per-stream in-memory output cap; overflow spills to a temp file. */ maxOutputBytes?: number /** Per-stream spill-file cap; larger streams retain only their in-memory tail. */ maxSpillBytes?: number /** Grace period for kill escalation and inherited pipes; at most `MAX_TIMER_DELAY_MS`. */ graceMs?: number /** * Explicit pwsh executable. When omitted, well-known Windows install * locations and PATH entries are probed in order (PowerShell 7 install, * PATH entries such as the Microsoft Store install, then Windows * PowerShell 5.1), falling back to a bare `pwsh` resolved through PATH. */ pwshPath?: string } ``` 来源：[`packages/shell/pwsh-local/src/index.ts:58`](../packages/shell/pwsh-local/src/index.ts) ## `@deepseek-ai/dsh-pwsh-sandbox` 需要：`subprocess` · `sandbox` · `sandboxPolicy` ```ts config-catalog /** * Plugin config: the local executor's knobs, verbatim. The sandbox policy — * the default mode and fallback `workspace-write` root — is NOT here: it lives * on `ctx.sandboxPolicy` (`@deepseek-ai/dsh-sandbox-policy`), which resolves * each calling session's mode and cwd for every enforcing capability. The * runner choice is likewise the `ctx.sandbox` provider's config, not this * executor's. */ export type Config = LocalConfig ``` 依赖：[`LocalConfig`](#deepseek-aidsh-pwsh-local) 来源：[`packages/shell/pwsh-sandbox/src/index.ts:40`](../packages/shell/pwsh-sandbox/src/index.ts) ## `@deepseek-ai/dsh-repeat-tool-reminder` ```ts config-catalog /** * Plugin config, validated by the same-named schemastery schema plus the * load-time checks in `apply` (misconfiguration fails loud: an empty * `thresholds` list, a non-integer, a value below 2, or a duplicate throws at * plugin load, never a silent fall-back). `include`/`exclude` entries are * `*`-wildcard predicates over tool names at call time, not references to * registry entries — a pattern matching no currently registered tool is valid * (`exclude: [mcp_*]` must stay legal in a deployment that loads no MCP tools). */ export interface Config { /** Consecutive-repeat counts that trigger a reminder (default `[3, 5, 8]`). */ thresholds?: number[] /** Tool-name patterns to track; empty means every tool is tracked. */ include?: string[] /** Tool-name patterns transparent to the chain (neither count nor reset). */ exclude?: string[] /** * Maximum characters of canonical arguments quoted in the DETAILED reminder * (default 500). Large payloads (a `write` body, a long command) would * otherwise ride into the next request unbounded — precisely in a loop * scenario; the cap bounds the reminder, never the detection (the chain key * always compares the FULL canonical string). */ argumentsPreviewChars?: number } ``` 来源：[`packages/guard/repeat-tool-reminder/src/index.ts:28`](../packages/guard/repeat-tool-reminder/src/index.ts) ## `@deepseek-ai/dsh-sandbox-local` ```ts config-catalog /** Plugin config. All optional — `static Config` supplies the defaults. */ export interface Config { /** * Override the runner argv; bwrap-compatible profile arguments are appended. A * non-empty override asserts full enforcement and skips built-in selection and * probing. A runner that starts but refuses its profile must be identifiable by * {@link runnerFailureSignatures}. Consumers classify a spawn rejection only after * confirming the workdir is usable. `ENOENT` or `EACCES` identifies the runner when * `error.path` equals argv[0] and `error.syscall` is `spawn` or `spawn `, or * when `error.path` is absent and `error.syscall` is exactly `spawn `. */ runnerCommand?: string[] /** * Case-insensitive stderr substrings emitted when a configured * {@link runnerCommand} refuses its profile before executing the wrapped * command. Required and non-empty with `runnerCommand`; rejected without * it. Each entry is a non-empty, single-line, case-insensitive substring * covering the executable runner's own failure dialect. */ runnerFailureSignatures?: string[] /** Positive timeout for each functional probe; zero would mean unbounded to Node. */ probeTimeoutMs?: number } ``` 来源：[`packages/sandbox/sandbox-local/src/index.ts:44`](../packages/sandbox/sandbox-local/src/index.ts) ## `@deepseek-ai/dsh-sandbox-policy` 需要：`sessionProjections` ```ts config-catalog /** * Plugin config: the deployment's sandbox default. All optional — `Config` * supplies the defaults (`mode: 'read-only'` is the fail-safe default; a * deployment that wants a workspace-writable agent opts in explicitly). The * runner choice is NOT here (it is the `ctx.sandbox` provider's config), nor * is any per-family knob: this is the one shared policy home. */ export interface Config { /** File-sandbox mode a session starts from (default: `read-only`). */ mode?: SandboxMode /** * Fallback root for agentless calls and sessions without a cwd (default: * `process.cwd()`). Normal agent calls use their session cwd instead. */ workspaceRoot?: string } ``` 依赖：[`SandboxMode`](subsystems/sandbox.zh.md) 来源：[`packages/sandbox/sandbox-policy/src/index.ts:70`](../packages/sandbox/sandbox-policy/src/index.ts) ## `@deepseek-ai/dsh-sdk-app` 需要：`cmdlineArgs` ```ts config-catalog /** SDK stdio startup configuration. */ export interface Config { /** Profile name rendered in help and diagnostics (default `sdk`). */ profile?: string } ``` 来源：[`packages/bundle/sdk-app/src/index.ts:23`](../packages/bundle/sdk-app/src/index.ts) ## `@deepseek-ai/dsh-sdk-jsonrpc-server` 需要：`agents` ```ts config-catalog /** JSON-RPC deployment config plus runtime-only test hooks. */ export interface JsonRpcConfig { /** Report max-token turn/subagent termination as a successful SDK result. */ maxTokensAsSuccess?: boolean /** Transport input override; production uses `process.stdin`. */ input?: Readable /** Transport output override; production uses `process.stdout`. */ output?: Writable /** Process-exit override; production uses `process.exit`. */ exit?: (code: number) => void } ``` 依赖：`Readable`（`node:stream`）· `Writable`（`node:stream`） 来源：[`packages/sdk/server/src/index.ts:25`](../packages/sdk/server/src/index.ts) ## `@deepseek-ai/dsh-session-log-deepseek` 需要：`deepseekLlmApiExtensions` · `sessions` ```ts config-catalog /** Session-log request contribution configuration. */ export interface Config { /** Contribute `dsh_session_log` to official DeepSeek requests. Defaults to `false`. */ enabled?: boolean } ``` 来源：[`packages/session/session-log-deepseek/src/index.ts:36`](../packages/session/session-log-deepseek/src/index.ts) ## `@deepseek-ai/dsh-session-log-export` 需要：`commands` · `connection` ```ts config-catalog /** Session-log archive policy. */ export interface Config { /** DEFLATE level for each ZIP entry. @default 6 */ readonly compressionLevel?: SessionLogCompressionLevel } /** Valid fflate DEFLATE levels accepted by session-log export. */ export type SessionLogCompressionLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 ``` 来源：[`packages/session-query/session-log-export/src/index.ts:42`](../packages/session-query/session-log-export/src/index.ts) ## `@deepseek-ai/dsh-session-persistence-jsonl` 需要：`sessions` · `sessionProjections` ```ts config-catalog /** Plugin config: where the JSONL backend keeps its session logs, and the packed-row write switch. */ export interface Config { /** * Root directory for all session files. Required (no default): a default of * `process.cwd()` would scatter session files as the process's cwd changes * (bash calls, subprocesses). Sessions group under human-readable project * directories, then per-session directories. An existing root must be a * readable directory; an absent root is created on first materialization. */ root: string /** * Write runs of consecutive `assistant/chunk` delta events as packed * `text-chunks`/`reasoning-chunks`/`tool-call-chunks` rows (lossless, * ~60% smaller logs measured on a real session). Defaults to true; false * keeps one `SessionEvent` per line for diagnostics. Reading packed rows is * unconditional: a log's layout never depends on this switch. */ packChunks?: boolean /** Physical encoding; defaults to checksummed Zstandard frames. */ compression?: JsonlCompression /** Maximum cold Session preparations retained for history-to-resume reuse. */ preparedSessionCacheSize?: number /** Fixed live-event coalescing window; not a backend completion deadline. */ writeBatchMaxDelayMs?: number } /** Physical encoding selected for JSONL session artifacts. */ export type JsonlCompression = 'zstd' | 'none' ``` 来源：[`packages/session/session-persistence-jsonl/src/index.ts:70`](../packages/session/session-persistence-jsonl/src/index.ts) ## `@deepseek-ai/dsh-session-projection-cache` 需要：`storageDomain` · `sessionProjections` · `sessions` ```ts config-catalog /** * Plugin config. Both throttle triggers are deployment choices with no * universally correct value, so the composition states them explicitly * (cordis.yml); the three mandatory write points (session creation, * `turn/end`, and session disposal) are policy, not tunables, and always * fire. */ export interface Config { /** Committed events per session that force a durable checkpoint write between mandatory points. */ writeEveryEvents: number /** Longest time (milliseconds) a dirty checkpoint may stay unwritten between mandatory points. */ writeIntervalMs: number } ``` 来源：[`packages/session/session-projection-cache/src/index.ts:55`](../packages/session/session-projection-cache/src/index.ts) ## `@deepseek-ai/dsh-session-query-sqlite` 需要：`sessions` ```ts config-catalog /** Combined session-query configuration backed by SQLite full-text search. */ export interface Config extends SessionQueryConfig { /** * Dedicated derived-index path; `:memory:` is supported for ephemeral * indexes. Missing directories and database files are created owner-only on * POSIX filesystems; existing modes are preserved. */ path: string /** * Open the SQLite module and handle at service activation or the first * search, or `never` to disable full-text search: the inherited exact * reads, filters, and traces stay available, while `searchSessions` and * `searchEvents` fail with `SESSION_QUERY_SEARCH_DISABLED` and SQLite is * never imported or opened. Defaults to `startup`. */ openAt?: OpenAt /** SQLite journal mode. Defaults to `wal`. */ journalMode?: JournalMode /** Page size when a request omits `limit`. At most `Number.MAX_SAFE_INTEGER - 1`; defaults to 20. */ defaultLimit?: number /** Largest accepted page size. At most `Number.MAX_SAFE_INTEGER - 1`; defaults to 100. */ maxLimit?: number /** Maximum snippet length in Unicode code points. Defaults to 240. */ snippetChars?: number /** Maximum concurrent persisted-log inspections in one inherited batch read. Defaults to 4. */ persistedInspectConcurrency?: number } /** SQLite module/handle opening phase; `never` disables full-text search entirely. */ export type OpenAt = 'startup' | 'first-search' | 'never' /** Supported SQLite journal modes. */ export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist' ``` 依赖：[`SessionQueryConfig`](../packages/session-query/session-query/src/index.ts) 来源：[`packages/session-query/session-query-sqlite/src/index.ts:96`](../packages/session-query/session-query-sqlite/src/index.ts) ## `@deepseek-ai/dsh-session-reference` 需要：`sessionQuery` ```ts config-catalog /** Session-reference service configuration. */ export interface Config { /** Maximum distinct source sessions referenced by one message, from one to three. */ maxReferences?: number /** Default host candidate-list limit. */ candidateLimit?: number /** Maximum rendered UTF-8 bytes for one source snapshot. */ maxReferenceBytes?: number } ``` 来源：[`packages/context/session-reference/src/config.ts:11`](../packages/context/session-reference/src/config.ts) ## `@deepseek-ai/dsh-session-telemetry-otel` 需要：`sessions` ```ts config-catalog /** * Plugin configuration: one sharing policy, two verbatim SDK option objects, * and one DSH-owned shutdown bound. Uploading modes validate their endpoint * and shutdown deadline at plugin load; `DISABLED` reads neither. */ export interface Config { /** Sharing policy; defaults to local-only `DISABLED` behavior. */ mode?: SessionTelemetryMode /** * Passed verbatim to the SDK's OTLP/HTTP log exporter — the complete * `OTLPExporterNodeConfigBase` shape (`headers`, `timeoutMillis`, * `compression`, `keepAlive`, …), owned and documented by the SDK. `url` * is the one field this package requires and validates itself. */ exporter?: OTLPExporterNodeConfigBase & { /** Full logs endpoint (e.g. `https://collector.example.com/v1/logs`). Required outside `DISABLED`; validated at load. */ url?: string } /** * Passed verbatim to `BatchLogRecordProcessor` (minus the exporter slot, * which this plugin fills); the SDK owns and documents these knobs. */ processor?: Omit /** Maximum time spent awaiting the SDK provider's complete shutdown path. */ shutdownTimeoutMillis?: number } /** Session-sharing policy selected by {@link Config.mode}. */ export enum SessionTelemetryMode { FULL = 'FULL', FEEDBACK_ONLY = 'FEEDBACK_ONLY', DISABLED = 'DISABLED', } ``` 依赖：`BatchLogRecordProcessorOptions`（`@opentelemetry/sdk-logs`）· `OTLPExporterNodeConfigBase`（`@opentelemetry/otlp-exporter-base`） 来源：[`packages/session/session-telemetry-otel/src/index.ts:91`](../packages/session/session-telemetry-otel/src/index.ts) ## `@deepseek-ai/dsh-session-title` 需要：`sessions` ```ts config-catalog /** Required deterministic fallback and accepted-title limits. */ export interface Config { /** Maximum whitespace-delimited words in the built-in fallback. */ readonly fallbackMaxWords: number /** Maximum UTF-8 bytes in the built-in fallback. */ readonly fallbackMaxBytes: number /** Maximum UTF-8 bytes in any accepted title. */ readonly maxTitleBytes: number } ``` 来源：[`packages/session/session-title/src/index.ts:56`](../packages/session/session-title/src/index.ts) ## `@deepseek-ai/dsh-session-title-all-prompts-llm` 需要：`sessionTitle` · `llm` · `sessions` ```ts config-catalog /** Required LLM policy; this plugin adds no defaults. */ export type Config = SessionTitleLlmConfig ``` 依赖：[`SessionTitleLlmConfig`](../packages/session/session-title-llm/src/index.ts) 来源：[`packages/session/session-title-all-prompts-llm/src/index.ts:15`](../packages/session/session-title-all-prompts-llm/src/index.ts) ## `@deepseek-ai/dsh-session-title-first-prompt-llm` 需要：`sessionTitle` · `llm` · `sessions` ```ts config-catalog /** Required LLM policy; this plugin adds no defaults. */ export type Config = SessionTitleLlmConfig ``` 依赖：[`SessionTitleLlmConfig`](../packages/session/session-title-llm/src/index.ts) 来源：[`packages/session/session-title-first-prompt-llm/src/index.ts:15`](../packages/session/session-title-first-prompt-llm/src/index.ts) ## `@deepseek-ai/dsh-settings-file` ```ts config-catalog /** Plugin config: file location and hot-reload behavior. */ export interface Config { /** Settings document path; defaults to `settings.yaml` under the harness home. */ path?: string /** Harness home used when `path` is omitted; defaults to `$DSH_HOME` or `~/.dsh`. */ dshHome?: string /** Watch the document and hot-publish external edits; defaults to true. */ watch?: boolean /** Watcher write-settle window in milliseconds; defaults to 100. */ debounceMs?: number } ``` 来源：[`packages/settings/settings-file/src/index.ts:22`](../packages/settings/settings-file/src/index.ts) ## `@deepseek-ai/dsh-shell-env` ```ts config-catalog /** Plugin config (all optional — the built-in facts resolve without defaults). */ export interface Config { /** DeepSeek Harness home directory exposed as `DSH_HOME`; defaults to `$DSH_HOME` or `~/.dsh`. */ dshHome?: string } ``` 来源：[`packages/shell/shell-env/src/index.ts:29`](../packages/shell/shell-env/src/index.ts) ## `@deepseek-ai/dsh-skill` ```ts config-catalog /** Skill registry configuration. */ export interface Config { /** Maximum number of completed cwd/provider catalogs kept in memory. */ readonly collectCacheMaxEntries?: number } ``` 来源：[`packages/skill/skill/src/index.ts:280`](../packages/skill/skill/src/index.ts) ## `@deepseek-ai/dsh-skill-filesystem` 需要：`skills` ```ts config-catalog /** Local filesystem skill provider configuration. */ export interface Config { /** Unique provider name. Defaults to `filesystem`. */ providerName?: string /** Whether project and user roots are included around custom roots. */ includeDefaultRoots?: boolean /** DeepSeek Harness config root. Defaults to `$DSH_HOME` or `~/.dsh`. */ dshHome?: string /** Shared agent config root. Defaults to `$DSH_AGENTS_HOME` or `~/.agents`. */ agentsHome?: string /** Additional skill roots scanned after project roots and before user roots. */ customSkillDirs?: string[] /** Whether host-local skill roots are watched for catalog changes. */ watch?: boolean /** Whether Chokidar uses polling instead of native filesystem events. */ watchUsePolling?: boolean /** Milliseconds a changed skill entry must remain stable before it is observed. */ watchStabilityThresholdMs?: number /** Milliseconds between Chokidar stability or polling probes. */ watchPollIntervalMs?: number /** Maximum distinct project roots whose skill directories remain watched. */ watchMaxProjects?: number /** Whether watched symbolic links follow their target files. */ watchFollowSymlinks?: boolean /** Bundled skill root; defaults to `$DSH_BUNDLED_SKILL_DIR` when default roots are included, otherwise mounts none. */ bundledSkillDir?: string } ``` 来源：[`packages/skill/skill-filesystem/src/index.ts:49`](../packages/skill/skill-filesystem/src/index.ts) ## `@deepseek-ai/dsh-spill-local` ```ts config-catalog /** Plugin config (all optional — `static Config` supplies the defaults). */ export interface Config { /** * Root directory for spill files. Omitted uses a lazily-created private * (0700) per-process directory under the OS temp dir — the safe default for * a local deployment. Set it to keep spill files under a known location. */ root?: string /** * Age in days after which a spill file is eligible for the one-shot startup * cleanup sweep. Defaults to `30`; `0` disables cleanup entirely. Files whose * `mtime` is strictly older than the cutoff are deleted and emptied * directories are pruned; fresh files, symlinks, and unrelated entries are * left untouched. On POSIX, cleanup skips roots and session directories that * another local user could modify or replace. Retention is deliberate — a * resumed or forked session may still reference an older locator until it * ages out. */ cleanupPeriodDays?: number } ``` 来源：[`packages/spill/spill-local/src/index.ts:31`](../packages/spill/spill-local/src/index.ts) ## `@deepseek-ai/dsh-spill-policy` 需要：`tools` · `sessionProjections` ```ts config-catalog /** Plugin config. */ export interface Config { /** * The model-facing context cap for a plain-text tool result, in UTF-8 bytes. * Omitted disables the policy entirely (no-op). When set, a result larger than * this is spilled and replaced with a preview derived from this same budget. */ maxInlineBytes?: number } ``` 来源：[`packages/spill/spill-policy/src/index.ts:60`](../packages/spill/spill-policy/src/index.ts) ## `@deepseek-ai/dsh-storage-domain` 需要：`storage` ```ts config-catalog /** * Plugin config. Which backend serves which domain is decided here, not * globally on the hub: `backend` is the default route and `routes` overrides * it per domain name. A route naming an unregistered backend fails loud at * `open` with `backend-not-found`. */ export interface Config { /** Default backend name for every domain without an explicit route. Required: there is no universally correct medium. */ backend: string /** Per-domain overrides: domain name → backend name. */ routes?: Record } ``` 来源：[`packages/storage/storage-domain/src/index.ts:52`](../packages/storage/storage-domain/src/index.ts) ## `@deepseek-ai/dsh-storage-json` 需要：`storage` ```ts config-catalog /** * Plugin configuration. * `root` has NO default on purpose: a `process.cwd()` fallback would scatter * unit files wherever the process happens to start; assemblies state the * location explicitly. */ export interface Config { /** Directory holding one `.json` file (or `/` tree) per unit. */ root: string } ``` 来源：[`packages/storage/storage-json/src/index.ts:28`](../packages/storage/storage-json/src/index.ts) ## `@deepseek-ai/dsh-storage-sqlite` 需要：`storage` ```ts config-catalog /** Plugin configuration. */ export interface Config { /** * Filesystem path to the SQLite database file. The special value `:memory:` * opens an in-process database (tests). On filesystems with POSIX modes, * missing directories and databases are created owner-only; existing path * modes are preserved. Filesystem setup errors other than an existing * database fail the open. The backend does not protect confidentiality or * integrity when another principal can replace the database entry in its * parent directory. */ path: string /** * SQLite `journal_mode` pragma. `wal` (the default) suits local disks; pick * a rollback-journal mode (`delete`/`truncate`/`persist`) on filesystems * where WAL's shared-memory files do not work (network mounts). See * {@link JournalMode}. */ journalMode?: JournalMode } /** * Journal modes the backend will run under. `wal` is the default; the * rollback-journal modes (`delete`/`truncate`/`persist`) exist for * filesystems where WAL's shared-memory files do not work (network mounts). * `memory`/`off` are excluded: dropping journal durability silently * contradicts the durability clause of the KV backend contract. */ export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist' ``` 来源：[`packages/storage/storage-sqlite/src/index.ts:24`](../packages/storage/storage-sqlite/src/index.ts) ## `@deepseek-ai/dsh-subagent-acp` 需要：`subagents` · `subprocess` ```ts config-catalog /** Config: how to spawn and drive the child ACP agent process. */ export interface Config { /** Provider name on `ctx.subagents` (default `acp`). */ providerName: string /** The executable to spawn for each run (the child ACP agent). */ command: string /** Arguments passed to {@link command}. */ args: string[] /** * Working directory override for the child process and its ACP session. * Must be non-empty; a relative path resolves against the harness launch * directory at load, and the result must be an existing directory. When * omitted, each child inherits its delegating parent session's cwd — and * starting one from a parent session that has no cwd fails. */ cwd?: string /** * How to auto-answer the child's `session/request_permission` prompts: * `reject` (default — decline every prompt) or `allow` (approve via the first * `allow_once` or `allow_always` option). No prompt is surfaced to a human. */ permission: PermissionPolicy /** * Extra environment variables for the child process — e.g. the child * harness's own `DEEPSEEK_API_KEY`. Forwarded on top of a credential-scrubbed * copy of the parent env, so an explicit key here reaches the child while * ambient secrets do not leak implicitly. */ env: Record /** * Grace period (ms) for the child's EOF-driven quiesce on dispose — its * window to flush persistence and tear down its own nested subprocesses * before the parent escalates to a signal. Must not exceed * `MAX_TIMER_DELAY_MS`. */ disposeEofGraceMs?: number /** Failure-observation and termination-escalation grace (ms); must not exceed `MAX_TIMER_DELAY_MS`. */ disposeGraceMs?: number } /** Fixed response to child permission requests: reject by default, or select the first allow option. */ export type PermissionPolicy = 'allow' | 'reject' ``` 来源：[`packages/subagent/subagent-acp/src/index.ts:27`](../packages/subagent/subagent-acp/src/index.ts) ## `@deepseek-ai/dsh-subagent-claude-code` 需要：`subagents` · `subprocess` ```ts config-catalog /** Deployment-owned model, permission, environment, and process-release settings. */ export interface Config { /** Provider name on `ctx.subagents` (default `claude-code`). */ providerName?: string /** Native Claude model fixed for this instance; omitted to inherit Claude settings. */ model?: string /** * Explicit environment entries layered over the subprocess seam's * credential-scrubbed parent environment. */ env?: Record /** * Native non-interactive mode fixed for this Provider instance. Defaults to * `dontAsk`; `acceptEdits` accepts edits, `auto` uses the native classifier, * `plan` returns a plan without approving execution, and * `bypassPermissions` explicitly skips permission checks. */ permissionMode?: ClaudeCodePermissionMode /** Grace in milliseconds for Claude Code process-tree termination. */ disposeGraceMs?: number } /** Profile-selectable non-interactive Claude Code permission mode. */ export type ClaudeCodePermissionMode = typeof CLAUDE_CODE_PERMISSION_MODES[number] ``` 来源：[`packages/subagent/subagent-claude-code/src/index.ts:38`](../packages/subagent/subagent-claude-code/src/index.ts) ## `@deepseek-ai/dsh-subagent-codex` 需要：`subagents` · `subprocess` ```ts config-catalog /** Deployment-owned model, permission, environment, and process-release settings. */ export interface Config { /** Provider name on `ctx.subagents` (default `codex`). */ providerName?: string /** Native Codex model fixed for this instance; omitted to inherit Codex settings. */ model?: string /** * Explicit environment entries layered over the subprocess seam's * credential-scrubbed parent environment. */ env?: Record /** Native non-interactive permission mode fixed for this Provider instance. */ permissionMode?: CodexPermissionMode /** Grace in milliseconds for app-server process-tree termination. */ disposeGraceMs?: number } /** Profile-selectable non-interactive Codex permission mode. */ export type CodexPermissionMode = | 'never' | 'approve-for-me' | 'dangerously-bypass-approvals-and-sandbox' ``` 来源：[`packages/subagent/subagent-codex/src/index.ts:36`](../packages/subagent/subagent-codex/src/index.ts) ## `@deepseek-ai/dsh-subagent-dsh-sdk` 需要：`subagents` ```ts config-catalog /** Config: how to spawn and drive the child SDK runtime process. */ export interface Config { /** Provider name on `ctx.subagents` (default `dsh-sdk`). */ providerName: string /** Explicit dsh CLI module, resolved and checked at plugin load; omission uses the SDK dependency. */ dshBin?: string /** Named child profile (default `sdk`). */ profile: string /** Ordered per-launch profile patch files, resolved and checked at plugin load. */ patches: string[] /** Absolute isolated Harness home for every nested child process. */ dshHome: string /** * Working directory override for the child process and its SDK session * workspace. Must be non-empty; a relative path resolves against the * harness launch directory at load, and the result must be an existing * directory. When omitted, each child inherits its delegating parent * session's cwd — and starting one from a parent session that has no cwd * fails. */ cwd?: string /** Provider route the child runtime initializes with (default `deepseek-official`). */ provider: string /** Model the child runtime initializes with (default `deepseek-v4-flash`). */ model: string /** Optional per-request output-token cap for the child runtime. */ maxTokens?: number /** * Extra environment variables for the child process — e.g. the child * runtime's own `DEEPSEEK_API_KEY`. Forwarded on top of a credential-scrubbed copy of the parent * env, so an explicit key here reaches the child while ambient secrets do * not leak implicitly. */ env: Record /** Bound (ms) on the protocol `shutdown` exchange during dispose. */ shutdownTimeoutMs?: number /** * Grace period (ms) for the child's EOF-driven quiesce on dispose — its * window to flush persistence and tear down its own nested subprocesses * before the parent escalates to a signal. */ disposeEofGraceMs?: number /** Termination confirmation window (ms), including forced exit on every platform. */ disposeGraceMs?: number } ``` 来源：[`packages/subagent/subagent-dsh-sdk/src/index.ts:34`](../packages/subagent/subagent-dsh-sdk/src/index.ts) ## `@deepseek-ai/dsh-subagent-fork-in-process` 需要：`subagents` ```ts config-catalog /** Config: the registry name to register the provider under. */ export interface Config { /** Provider name on `ctx.subagents` (default `fork`). */ providerName: string } ``` 来源：[`packages/subagent/subagent-fork-in-process/src/index.ts:31`](../packages/subagent/subagent-fork-in-process/src/index.ts) ## `@deepseek-ai/dsh-subagent-spawn-in-process` 需要：`subagents` ```ts config-catalog /** Config: the registry name to register the provider under. */ export interface Config { /** Provider name on `ctx.subagents` (default `spawn`). */ providerName: string } ``` 来源：[`packages/subagent/subagent-spawn-in-process/src/index.ts:25`](../packages/subagent/subagent-spawn-in-process/src/index.ts) ## `@deepseek-ai/dsh-subprocess-e2b` 需要：`e2b` ```ts config-catalog /** Configuration for the E2B subprocess adapter. */ export interface Config { /** Remote status/liveness poll cadence in milliseconds; each tick is one control-plane request. */ pollMs?: number } ``` 来源：[`packages/e2b/subprocess-e2b/src/index.ts:25`](../packages/e2b/subprocess-e2b/src/index.ts) ## `@deepseek-ai/dsh-system-prompt` ```ts config-catalog /** Plugin config: the deployment-authored fragment of the system prompt (see {@link Config.persona} for its contract). */ export interface Config { /** Include the fixed DeepSeek Harness identity before the deployment persona (default true). */ includeHarnessIdentity?: boolean /** Include dynamic runtime-context snapshots in model history (default true). */ includeRuntimeContext?: boolean /** * Deployment-wide order-0 persona template. A scoped section named * `deployment:persona` shadows it; `{{variable}}` references are strict. */ persona?: string /** * Model-facing tool names in order, with {@link TOOL_ORDER_REST} exactly once. * Invalid fields fail at load and unknown names fail at assembly; known names * hidden in one scope may be absent there. Omitted means lexicographic order. */ toolOrder?: string[] } ``` 来源：[`packages/core/system-prompt/src/index.ts:237`](../packages/core/system-prompt/src/index.ts) ## `@deepseek-ai/dsh-terminal-bash` 需要：`terminals` · `sandboxPolicy` · `sessionProjections` · `subprocess` ```ts config-catalog /** Public plugin configuration. */ export interface Config { /** Backend registry type (default: `shell`). */ backendType?: string /** Interactive shell dialect (default: `bash`); selects the argv/env/startup defaults. */ shellDialect?: ShellDialect /** Interactive shell executable (default per dialect: `/bin/bash`, or the resolved pwsh). */ shellPath?: string /** Shell arguments (default per dialect: bash `--noprofile --norc -i`, pwsh `-NoLogo -NoProfile`). */ shellArgs?: string[] /** Terminal rows. */ rows?: number /** Terminal columns. */ cols?: number /** Maximum retained logical lines. */ scrollbackLines?: number /** Maximum retained UTF-8 bytes. */ scrollbackMaxBytes?: number /** Maximum bytes returned by one read or settled viewport. */ maxReadBytes?: number /** Readiness polling interval. */ pollIntervalMs?: number /** Delay before Linux exact syscall probes. */ exactProbeAfterMs?: number /** Silence duration that yields `inferred_idle`. */ idleSilenceMs?: number /** * Extra wait beyond `idleSilenceMs`, once a prompt marker was seen, for the shell to * regain the foreground before `inferred_idle` settles; at least one `pollIntervalMs`. */ handoffGraceMs?: number /** Absolute bound for one send and the complete pwsh startup sequence. */ timeoutMs?: number /** Grace before teardown escalates to `SIGKILL`. */ disposeGraceMs?: number } /** One supported interactive shell dialect. */ export type ShellDialect = 'bash' | 'pwsh' ``` 来源：[`packages/terminal/terminal-bash/src/config.ts:10`](../packages/terminal/terminal-bash/src/config.ts) ## `@deepseek-ai/dsh-time-context` 需要：`agents` · `sessionProjections` ```ts config-catalog /** Request-preparation clock formatting and append scheduling. Invalid values fail plugin load. */ export interface Config { /** Fallback display zone when the open turn has no unique browser zone. Omit to use the process zone. */ timeZone?: string /** Minimum milliseconds between durable injections in one session. Omit or set to 0 to inject at every eligible step. */ refreshIntervalMs?: number } ``` 来源：[`packages/context/time-context/src/index.ts:48`](../packages/context/time-context/src/index.ts) ## `@deepseek-ai/dsh-tmux-context` 需要：`agents` · `sessionProjections` ```ts config-catalog /** Per-turn tmux-location scheduling. Invalid values fail plugin load. */ export interface Config { /** Minimum milliseconds between durable injections in one session. Omit or set to 0 to inject on every eligible change. */ refreshIntervalMs?: number } ``` 来源：[`packages/context/tmux-context/src/index.ts:36`](../packages/context/tmux-context/src/index.ts) ## `@deepseek-ai/dsh-token-meter` 需要：`sessionProjections` ```ts config-catalog /** Token-meter plugin configuration; the fixed estimator has no settings. */ export type TokenMeterConfig = Record ``` 来源：[`packages/llm/token-meter/src/types.ts:13`](../packages/llm/token-meter/src/types.ts) ## `@deepseek-ai/dsh-tool-bash` 需要：`tools` · `shell` · `systemPrompt` · `shellEnv` ```ts config-catalog /** Configuration for the bash tool. */ export interface Config { /** Expose `run_in_background` (default true); disabled calls are also rejected. */ enableRunInBackground?: boolean } ``` 来源：[`packages/shell/tool-bash/src/index.ts:33`](../packages/shell/tool-bash/src/index.ts) ## `@deepseek-ai/dsh-tool-bash-persistent` 需要：`tools` · `terminals` ```ts config-catalog /** Configuration for the persistent Bash tool. */ export interface Config { /** PTY backend used for each owner-isolated persistent shell (default `shell`). */ backendType?: string /** Wall-clock limit for one command (default 300000). */ timeoutMs?: number /** Maximum returned command-output characters before clipping (default 16000). */ maxOutputChars?: number /** Model-facing tool description; deployments may describe their environment. */ description?: string } ``` 来源：[`packages/shell/tool-bash-persistent/src/index.ts:432`](../packages/shell/tool-bash-persistent/src/index.ts) ## `@deepseek-ai/dsh-tool-fs` 需要：`tools` · `fs` · `systemPrompt` ```ts config-catalog /** Plugin config (all optional — `Config` supplies the defaults). */ export interface Config { /** Default and maximum number of lines returned by one `read` call. */ readLimit?: number /** Maximum characters returned for a single line before truncation. */ readMaxLineLength?: number /** Maximum bytes returned for the selected lines of one `read` call. */ readMaxBytes?: number /** Files at or above this size stream instead of loading whole into memory. */ readStreamMinSize?: number } ``` 来源：[`packages/fs/tool-fs/src/index.ts:25`](../packages/fs/tool-fs/src/index.ts) ## `@deepseek-ai/dsh-tool-fs-search` 需要：`tools` · `systemPrompt` · `subprocess` ```ts config-catalog /** Plugin config; over-cap glob sampling is an explicit deployment choice and the remaining fields have defaults. */ export interface Config { /** Whether an over-cap `glob` page is sampled across top-level entries instead of taking the modification-time head. */ sampleOverCapGlobResults: boolean /** Max paths one `glob` call retains inline; later paths go to the formatted spill file. */ globMaxResults?: number /** Max flat matches one `grep` call retains inline; later matches go to the formatted spill file. */ grepMaxMatches?: number /** Max bytes retained for one matched-line preview (the cut preserves UTF-8 boundaries). */ grepMaxLineBytes?: number /** Max bytes of one search's serialized `presentationMeta`; trailing groups/paths drop past it so the persisted card stays bounded. */ searchMetaMaxBytes?: number /** Max complete raw `rg` stdout bytes a search will parse; larger raw output fails with `SEARCH_RAW_OUTPUT_OVERFLOW`. */ rawOutputMaxBytes?: number /** Terminate-escalation grace (ms), handed to the subprocess seam and bounded by `MAX_TIMER_DELAY_MS`. */ graceMs?: number /** Max bytes retained for one search's stderr tail; the excerpt is embedded in `SEARCH_*` error messages, never shown on success. */ stderrMaxBytes?: number /** * Cooperative tool-call timeout budget (ms) on both tools, enforced by * `@deepseek-ai/dsh-tool-call-timeout-policy` through `exec.signal`. */ timeoutMs?: number } ``` 来源：[`packages/fs/tool-fs-search/src/index.ts:73`](../packages/fs/tool-fs-search/src/index.ts) ## `@deepseek-ai/dsh-tool-goal` 需要：`agents` · `goals` · `tools` · `systemPrompt` · `sessionProjections` ```ts config-catalog /** Model policy and hard lower bounds for goal-state updates. */ export interface Config { /** Minimum admitted goal rounds before the model may self-report `blocked`. */ blockedAfterConsecutiveRounds?: number } ``` 来源：[`packages/goal/tool-goal/src/index.ts:25`](../packages/goal/tool-goal/src/index.ts) ## `@deepseek-ai/dsh-tool-jobs` 需要：`tools` · `jobs` · `systemPrompt` ```ts config-catalog /** Configures bounded `job_output` waits and completion-notice delivery. */ export interface Config { /** Wait duration applied when `job_output` sets `wait` without `timeout_ms` (default 30s). */ waitTimeoutMs?: number /** Hard cap on any single wait; a larger model-supplied `timeout_ms` is clamped down to it (default 10min). */ maxWaitTimeoutMs?: number /** Whether a completion opens a turn on an idle owner (default `wakeup`). */ completionDelivery?: CompletionDelivery /** * Turns one owner may have opened by completion wakes before the next * notice degrades to injection, reset by any user-authored input (default 3). * Bounds the self-exciting chain where a woken turn starts the job whose * completion wakes it again. */ maxConsecutiveWakes?: number } /** * How an unreported completion reaches an owner that is already idle: `wakeup` * opens a turn for it, `quiet` leaves it pending until something else wakes the * owner. A busy owner is injected either way. */ export type CompletionDelivery = 'quiet' | 'wakeup' ``` 来源：[`packages/jobs/tool-jobs/src/index.ts:31`](../packages/jobs/tool-jobs/src/index.ts) ## `@deepseek-ai/dsh-tool-lsp` 需要：`tools` · `lsp` · `systemPrompt` ```ts config-catalog /** Plugin configuration: result caps and the timeout budget. */ export interface Config { /** Largest number of rendered locations before an omission marker (default 100). */ maxLocations?: number /** Largest complete rendered result in characters, including truncation metadata (default 16000). */ maxResultChars?: number /** Tool-call timeout budget in ms (default 60000). */ timeoutMs?: number } ``` 来源：[`packages/lsp/tool-lsp/src/index.ts:57`](../packages/lsp/tool-lsp/src/index.ts) ## `@deepseek-ai/dsh-tool-pwsh` 需要：`tools` · `shell` · `systemPrompt` · `shellEnv` ```ts config-catalog /** Configuration for the pwsh tool. */ export interface Config { /** Expose `run_in_background` (default true); disabled calls are also rejected. */ enableRunInBackground?: boolean } ``` 来源：[`packages/shell/tool-pwsh/src/index.ts:51`](../packages/shell/tool-pwsh/src/index.ts) ## `@deepseek-ai/dsh-tool-pwsh-persistent` 需要：`tools` · `terminals` ```ts config-catalog /** Configuration for the persistent pwsh tool. */ export interface Config { /** PTY backend used for each owner-isolated persistent shell (default `shell`). */ backendType?: string /** Wall-clock limit for one command (default 300000). */ timeoutMs?: number /** Maximum returned command-output characters before clipping (default 16000). */ maxOutputChars?: number /** Model-facing tool description; deployments may describe their environment. */ description?: string } ``` 来源：[`packages/shell/tool-pwsh-persistent/src/index.ts:472`](../packages/shell/tool-pwsh-persistent/src/index.ts) ## `@deepseek-ai/dsh-tool-ralph` 需要：`tools` · `workflowEngine` · `subagents` · `systemPrompt` ```ts config-catalog /** Deployment policy for the fixed Ralph workflow. */ export interface Config { /** Fresh structured-output provider used for every round (default `spawn`). */ subagentProvider?: string /** Default and deployment ceiling for one call's round count (default 256). */ maxRounds?: number /** Maximum serialized characters in one structured handoff (default 16384). */ maxHandoffChars?: number /** Maximum characters in a successful parent-facing terminal text (default 16384). */ maxResultChars?: number } ``` 来源：[`packages/workflow/tool-ralph/src/index.ts:21`](../packages/workflow/tool-ralph/src/index.ts) ## `@deepseek-ai/dsh-tool-session-query` 需要：`tools` · `systemPrompt` · `sessionQuery` · `sessionProjections` ```ts config-catalog /** Deployment-owned search count and timeout bounds. */ export interface Config { /** Maximum authorized hits returned by one search call. Defaults to 100. */ maxSearchResults?: number /** Cooperative full-text search deadline in milliseconds. Defaults to 30000. */ searchTimeoutMs?: number } ``` 来源：[`packages/session-query/tool-session-query/src/index.ts:28`](../packages/session-query/tool-session-query/src/index.ts) ## `@deepseek-ai/dsh-tool-skill` 需要：`agents` · `tools` · `skills` ```ts config-catalog /** Model-facing skill catalog configuration. */ export interface Config { /** Maximum normalized description length rendered in the session catalog; minimum 3. */ catalogDescriptionMaxLength?: number } ``` 来源：[`packages/skill/tool-skill/src/index.ts:61`](../packages/skill/tool-skill/src/index.ts) ## `@deepseek-ai/dsh-tool-str-replace-editor` 需要：`tools` · `fs` ```ts config-catalog /** Configuration for the string-replacement editor tool. */ export interface Config { /** Maximum returned view characters before clipping (default 16000). */ maxOutputChars?: number /** Model-facing tool description. */ description?: string } ``` 来源：[`packages/fs/tool-str-replace-editor/src/index.ts:505`](../packages/fs/tool-str-replace-editor/src/index.ts) ## `@deepseek-ai/dsh-tool-subagent` 需要：`tools` · `subagents` · `systemPrompt` · `sessionProjections` ```ts config-catalog /** Config: which registered provider this tool delegates to, plus child defaults. */ export interface Config { /** The `ctx.subagents` provider name to start runs on (e.g. `spawn`, `acp`). */ provider: string /** * Model-facing tool name (default `subagent`). Each loaded instance must use * a distinct name. */ toolName?: string /** * Sample the Host `subagent-model-selection` user setting for each new * top-level session and inherit that decision in its child sessions. */ modelSelectionSettings?: boolean /** * Expose `run_in_background` (default true). Disabled instances omit the * parameter and reject forced background calls. */ enableRunInBackground?: boolean /** * Background execution policy (default `one-shot`). `one-shot` defaults calls * to foreground; `continuable` defaults them to background, requires a provider * with the `prepareContinuable` capability, and returns the durable child id. * Follow-up adapters remain independently optional. */ backgroundMode?: 'one-shot' | 'continuable' /** * Agent options applied to every child; omitted fields use child-loop defaults. */ agentOptions?: AgentOptions /** * Per-child persona that shadows `deployment:persona`. Requires the * provider's `persona` capability; omission preserves the deployment persona. */ persona?: string /** * Tool filter applied to every child. Filtered tools disappear from its * prompt and reject execution. Requires the provider's `toolFilter` * capability; unknown names fail startup. */ toolFilter?: { /** Global tool names the child keeps; everything else is removed. */ allow?: string[] /** Global tool names removed from the child. */ deny?: string[] } /** * Maximum child depth: a non-negative safe integer (default `3`; `0` forbids * delegation entirely), or `'provider-managed'` to send no cap. A numeric cap * requires the provider's `depthLimit` capability (mount fails loud * otherwise). The provider checks the calling agent's current depth at every * start; the tool remains model-visible so runtime policy owns rejection. * `'provider-managed'` is for an out-of-process provider whose recursion * budget belongs to the child runtime or its own deployment. */ maxDepth?: number | 'provider-managed' } ``` 依赖：[`AgentOptions`](subsystems/core.zh.md) 来源：[`packages/subagent/tool-subagent/src/index.ts:48`](../packages/subagent/tool-subagent/src/index.ts) ## `@deepseek-ai/dsh-tool-terminal` 需要：`terminals` · `tools` · `systemPrompt` ```ts config-catalog /** Model-facing terminal tool configuration. */ export interface Config { /** Expose `run_in_background` and accept background sends (default true). */ enableRunInBackground?: boolean /** Maximum UTF-8 bytes in one complete terminal or task-output result. */ maxResultBytes?: number } ``` 来源：[`packages/terminal/tool-terminal/src/index.ts:35`](../packages/terminal/tool-terminal/src/index.ts) ## `@deepseek-ai/dsh-tool-todo` 需要：`tools` ```ts config-catalog /** Model-facing todo tool configuration. */ export interface Config { /** * Required deployment choice for whether several todos may be `in_progress` at once. True suits * agents that run work concurrently — subagents, background commands, workflow fan-out — and the * description then instructs the model to mark every actively worked task. False restores the * single-active discipline: the description asks for exactly one, and a call marking more is * rejected. */ allowParallelInProgress: boolean } ``` 来源：[`packages/todo/tool-todo/src/index.ts:29`](../packages/todo/tool-todo/src/index.ts) ## `@deepseek-ai/dsh-tool-web` 需要：`tools` · `web` · `systemPrompt` ```ts config-catalog /** Plugin config: which web tools to register, search bounds, per-tool budgets, and the fetch output cap. */ export interface Config { /** Register `web_search`. Defaults to true. */ search?: boolean /** Register `web_fetch`. Defaults to true. */ fetch?: boolean /** Upper bound on sources returned by one `web_search` call. */ searchMaxResults?: number /** Upper bound on queries accepted by one `web_search` call. */ searchMaxQueries?: number /** Cooperative timeout budget (ms) for `web_fetch`. Defaults to 30000. */ fetchTimeoutMs?: number /** Cooperative timeout budget (ms) for `web_search`. Defaults to 30000. */ searchTimeoutMs?: number /** Cap on source characters converted and complete `web_fetch` output characters. Defaults to 200000. */ fetchMaxOutputChars?: number } ``` 来源：[`packages/web/tool-web/src/index.ts:37`](../packages/web/tool-web/src/index.ts) ## `@deepseek-ai/dsh-tool-workflow` 需要：`tools` · `workflowEngine` · `systemPrompt` ```ts config-catalog /** Config: the model-facing tool name plus result rendering caps. */ export interface Config { /** The model-facing tool name to register (default `workflow`). */ toolName?: string /** Rendered-result ceiling, in characters: a longer JSON value is truncated with a notice (default 50000). */ maxResultChars?: number } ``` 来源：[`packages/workflow/tool-workflow/src/index.ts:32`](../packages/workflow/tool-workflow/src/index.ts) ## `@deepseek-ai/dsh-tools` 需要：`systemPrompt` ```ts config-catalog /** Plugin config: how the registered tools are presented to the model. */ export interface Config { /** * Model presentation. `native` (default) sends every visible schema; `ptc` * sends only `run_code` plus a generated SDK prompt and collapses the * executor to the same surface (a model-direct call may only name * `run_code`; `run_code` SDK sub-dispatches keep every visible tool); `both` * sends both forms. PTC mode requires a `ctx.codeRuntime` whose `language` * has a registered SDK renderer (TypeScript or Python) and fail prompt * assembly when it is absent or has no renderer. Under `ptc`, native names * in `toolOrder` are invalid. */ mode?: ToolPresentationMode /** * Concurrency cap for a `run_code` program's overlapping sub-calls * (default 10, the loop scheduler's own default). Sub-calls follow the * native scheduling contract — only calls whose tools classify * concurrency-safe overlap; exclusive calls form barriers — so `1` * restores strictly serial dispatch. Must be a positive integer. */ maxParallelSubCalls?: number } /** How the registry presents its tools to the model (see {@link Config.mode}). */ export type ToolPresentationMode = 'native' | 'ptc' | 'both' ``` 来源：[`packages/core/tools/src/index.ts:647`](../packages/core/tools/src/index.ts) ## `@deepseek-ai/dsh-typert-loader` 需要：`typert` · `loader` ```ts config-catalog /** Additional package artifacts whose owning plugins are nested behind another Loader entry. */ export interface Config { /** Exact npm package names that must resolve and export `./typert`. */ packages?: string[] } ``` 来源：[`packages/typert/loader/src/index.ts:47`](../packages/typert/loader/src/index.ts) ## `@deepseek-ai/dsh-user-approval` ```ts config-catalog /** Plugin config. All optional — `static Config` supplies the defaults. */ export interface Config { /** * The deployment's default {@link ApprovalPolicy} for sessions without an * `approval/policy` override — `'ask'` delegates to the composed answerers * (fail-closed with none); `'never'` auto-rejects every ask without * prompting (the deterministic CI/unattended stance). */ readonly policy?: ApprovalPolicy } /** * A session's approval policy — what happens to an {@link ApprovalService} * ask BEFORE any interactive answerer sees it: * * - `'ask'` (the default) — delegate to the composed answerers; with none * composed the chain falls through to the fail-closed `'unavailable'`. * - `'never'` — never prompt anyone: every ask resolves `'rejected'` * deterministically. The strict headless stance (CI, unattended runs) and * the policy whose outcome is knowable without asking. */ export type ApprovalPolicy = 'ask' | 'never' ``` 来源：[`packages/interaction/user-approval/src/index.ts:126`](../packages/interaction/user-approval/src/index.ts) ## `@deepseek-ai/dsh-web` ```ts config-catalog /** * Config for the web seam. `searchProvider` / `fetchProvider` pin which provider * wins for each capability; both are optional (a single registered usable * provider auto-selects). Operational overrides such as environment variables * must feed these same fields rather than introduce a hidden priority chain. */ export interface WebRuntimeConfig { /** Explicit search provider id. Omitted = auto-select when exactly one usable. */ readonly searchProvider?: string /** Explicit fetch provider id. Omitted = auto-select when exactly one usable. */ readonly fetchProvider?: string } ``` 来源：[`packages/web/web/src/index.ts:55`](../packages/web/web/src/index.ts) ## `@deepseek-ai/dsh-web-app` 需要：`webServer` ```ts config-catalog /** Plugin config: composed deployment settings plus per-invocation command-line values. */ export interface Config { /** Permit default-browser handoff after the Loader tree settles; an SSH launch suppresses it. */ openBrowser: boolean /** Print the URL line on activation; a non-interactive layer can turn it off. */ printUrl: boolean /** * Register the model-visible surface context (the `app:web-surface` prompt * section and the `DSH_WEB_URL` bash variable). A one-shot non-interactive * layer can turn it off when its user is not in the GUI, so the * orientation text would be false. */ surfaceContext: boolean /** Explicit `--trusted-host` authorities from this invocation. */ trustedHosts: string[] } ``` 来源：[`packages/bundle/web-app/src/index.ts:44`](../packages/bundle/web-app/src/index.ts) ## `@deepseek-ai/dsh-web-fetch-http` 需要：`web` ```ts config-catalog /** Plugin config: the provider's transport and size limits plus its `User-Agent` (all defaulted). */ export interface Config { /** Maximum response body size in bytes. */ maxResponseBytes?: number /** Maximum decoded body length in characters. */ maxBodyChars?: number /** Default fetch timeout in milliseconds, within Node's timer range. */ timeoutMs?: number /** Maximum number of same-origin redirect hops to follow. */ maxRedirects?: number /** `User-Agent` header sent on every request. */ userAgent?: string } ``` 来源：[`packages/web/web-fetch-http/src/index.ts:32`](../packages/web/web-fetch-http/src/index.ts) ## `@deepseek-ai/dsh-web-search-deepseek` 需要：`web` ```ts config-catalog /** Plugin config (all optional — `apply` fills env-var and constant defaults). */ export interface Config { /** Literal DeepSeek API key; prefer {@link apiKeyEnv} so no secret enters configuration files. */ apiKey?: string /** Credential reference resolved for each search; defaults to `DEEPSEEK_API_KEY`. */ apiKeyEnv?: string /** Anthropic-compatible endpoint base; `/messages` is appended. */ baseURL?: string /** Anthropic-format model name. Defaults to `deepseek-v4-flash`. */ model?: string /** `anthropic-version` header value. Defaults to `2023-06-01`. */ apiVersion?: string /** Upper bound on generated tokens for the Messages request. Defaults to 4096. */ maxTokens?: number /** Maximum `web_search` server-tool uses per request. Defaults to 5. */ maxUses?: number } ``` 来源：[`packages/web/web-search-deepseek/src/index.ts:46`](../packages/web/web-search-deepseek/src/index.ts) ## `@deepseek-ai/dsh-web-search-exa` 需要：`web` ```ts config-catalog /** Plugin config (all optional — `apply` fills env-var and constant defaults). */ export interface Config { /** Exa API key. Falls back to `$EXA_API_KEY`. Empty → provider unavailable. */ apiKey?: string /** Endpoint base; `/search` is appended. Defaults to the public API. */ baseURL?: string /** Retrieval mode sent as Exa's `type`. Defaults to `auto`. */ searchType?: 'auto' | 'keyword' | 'neural' /** Default result count when a request carries no `maxResults`. Omitted = none. */ numResults?: number /** Highlight sentences requested per result. Defaults to 1. */ highlightsPerResult?: number } ``` 来源：[`packages/web/web-search-exa/src/index.ts:35`](../packages/web/web-search-exa/src/index.ts) ## `@deepseek-ai/dsh-web-search-perplexity` 需要：`web` ```ts config-catalog /** Plugin config (all optional — `apply` fills env-var and constant defaults). */ export interface Config { /** Perplexity API key. Falls back to `$PERPLEXITY_API_KEY`. Empty → unavailable. */ apiKey?: string /** Endpoint base; `/chat/completions` is appended. Defaults to the public API. */ baseURL?: string /** Search model name. Defaults to `sonar`. */ model?: string /** Upper bound on generated answer tokens. Defaults to 1024. */ maxTokens?: number /** Recency window sent as `search_recency_filter`. Omitted = no filter. */ searchRecency?: 'day' | 'week' | 'month' | 'year' } ``` 来源：[`packages/web/web-search-perplexity/src/index.ts:30`](../packages/web/web-search-perplexity/src/index.ts) ## `@deepseek-ai/dsh-webhook-github` 需要：`webServer` · `webhookRuntime` · `credentials` ```ts config-catalog /** Required GitHub ingress configuration. */ export interface Config { /** Adapter instance name carried to rules. */ readonly source: string /** Exact absolute route path. */ readonly path: string /** Credential reference containing the shared webhook secret. */ readonly secretEnv: string /** Positive raw body ceiling in bytes. */ readonly maxBodyBytes: number } ``` 来源：[`packages/webhook/webhook-github/src/index.ts:17`](../packages/webhook/webhook-github/src/index.ts) ## `@deepseek-ai/dsh-workflow-worker-thread` 需要：`subagents` ```ts config-catalog /** Plugin config (all optional — `static Config` supplies the defaults). */ export interface Config { /** The `ctx.subagents` provider children run on (default `spawn`). */ provider?: string /** Concurrent `agent()` ceiling; `0` (the default) auto-resolves to `min(16, max(1, cores - 2))`. */ maxConcurrentAgents?: number /** Total `agent()` calls one run may start — the runaway-loop backstop (default 1000). */ maxTotalAgents?: number /** Items accepted by a single `parallel()`/`pipeline()` call (default 4096). */ maxItemsPerCall?: number /** vm timeout for the script's initial synchronous slice, inside the worker (default 5000 ms). */ syncTimeoutMs?: number /** * How long after a cancellation an unsettled script may keep running before * the run force-settles `cancelled` and its worker is TERMINATED (default * 5000 ms); also bounds `dispose()`. */ disposeGraceMs?: number } ``` 来源：[`packages/workflow/workflow-worker-thread/src/index.ts:32`](../packages/workflow/workflow-worker-thread/src/index.ts) ## 无配置的可加载插件 这些插件通过 `cordis.yml` 中不含 `config:` 块的条目加载；它们未声明任何配置接口。 - `@deepseek-ai/dsh-acp-app` — 需要 `cmdlineArgs`（[`packages/bundle/acp-app/src/index.ts`](../packages/bundle/acp-app/src/index.ts)） - `@deepseek-ai/dsh-agent`（[`packages/core/agent/src/index.ts`](../packages/core/agent/src/index.ts)） - `@deepseek-ai/dsh-api-remotes` — 需要 `typertGateway`（[`packages/api/remotes/src/index.ts`](../packages/api/remotes/src/index.ts)） - `@deepseek-ai/dsh-api-workspace-controller` — 需要 `typert` · `workspaceRegistry`（[`packages/api/workspace-controller/src/index.ts`](../packages/api/workspace-controller/src/index.ts)） - `@deepseek-ai/dsh-authorization` — 需要 `credentials`（[`packages/credentials/authorization/src/index.ts`](../packages/credentials/authorization/src/index.ts)） - `@deepseek-ai/dsh-client-locale`（[`packages/client/locale/src/index.ts`](../packages/client/locale/src/index.ts)） - `@deepseek-ai/dsh-client-modules` — 需要 `webServer` · `loader`（[`packages/client/modules/src/index.ts`](../packages/client/modules/src/index.ts)） - `@deepseek-ai/dsh-client-ui-agent-preset`（[`packages/client/ui-agent-preset/src/index.ts`](../packages/client/ui-agent-preset/src/index.ts)） - `@deepseek-ai/dsh-client-ui-approval`（[`packages/client/ui-approval/src/index.ts`](../packages/client/ui-approval/src/index.ts)） - `@deepseek-ai/dsh-client-ui-attachment`（[`packages/client/ui-attachment/src/index.ts`](../packages/client/ui-attachment/src/index.ts)） - `@deepseek-ai/dsh-client-ui-brand-official`（[`packages/client/ui-brand-official/src/index.ts`](../packages/client/ui-brand-official/src/index.ts)） - `@deepseek-ai/dsh-client-ui-chat`（[`packages/client/ui-chat/src/index.ts`](../packages/client/ui-chat/src/index.ts)） - `@deepseek-ai/dsh-client-ui-commands`（[`packages/client/ui-commands/src/index.ts`](../packages/client/ui-commands/src/index.ts)） - `@deepseek-ai/dsh-client-ui-conversation`（[`packages/client/ui-conversation/src/index.ts`](../packages/client/ui-conversation/src/index.ts)） - `@deepseek-ai/dsh-client-ui-cordis`（[`packages/extensions/ui-cordis/src/index.ts`](../packages/extensions/ui-cordis/src/index.ts)） - `@deepseek-ai/dsh-client-ui-deliverables` — 需要 `systemPrompt`（[`packages/client/ui-deliverables/src/index.ts`](../packages/client/ui-deliverables/src/index.ts)） - `@deepseek-ai/dsh-client-ui-directory-picker-browse`（[`packages/client/ui-directory-picker-browse/src/index.ts`](../packages/client/ui-directory-picker-browse/src/index.ts)） - `@deepseek-ai/dsh-client-ui-directory-picker-native`（[`packages/client/ui-directory-picker-native/src/index.ts`](../packages/client/ui-directory-picker-native/src/index.ts)） - `@deepseek-ai/dsh-client-ui-goal`（[`packages/client/ui-goal/src/index.ts`](../packages/client/ui-goal/src/index.ts)） - `@deepseek-ai/dsh-client-ui-input-trigger`（[`packages/client/ui-input-trigger/src/index.ts`](../packages/client/ui-input-trigger/src/index.ts)） - `@deepseek-ai/dsh-client-ui-jobs`（[`packages/client/ui-jobs/src/index.ts`](../packages/client/ui-jobs/src/index.ts)） - `@deepseek-ai/dsh-client-ui-layout`（[`packages/client/ui-layout/src/index.ts`](../packages/client/ui-layout/src/index.ts)） - `@deepseek-ai/dsh-client-ui-message-feedback`（[`packages/client/ui-message-feedback/src/index.ts`](../packages/client/ui-message-feedback/src/index.ts)） - `@deepseek-ai/dsh-client-ui-model-selection`（[`packages/client/ui-model-selection/src/index.ts`](../packages/client/ui-model-selection/src/index.ts)） - `@deepseek-ai/dsh-client-ui-permission-presets`（[`packages/client/ui-permission-presets/src/index.ts`](../packages/client/ui-permission-presets/src/index.ts)） - `@deepseek-ai/dsh-client-ui-plan`（[`packages/client/ui-plan/src/index.ts`](../packages/client/ui-plan/src/index.ts)） - `@deepseek-ai/dsh-client-ui-reference`（[`packages/client/ui-reference/src/index.ts`](../packages/client/ui-reference/src/index.ts)） - `@deepseek-ai/dsh-client-ui-renderer`（[`packages/client/ui-renderer/src/index.ts`](../packages/client/ui-renderer/src/index.ts)） - `@deepseek-ai/dsh-client-ui-schedule`（[`packages/client/ui-schedule/src/index.ts`](../packages/client/ui-schedule/src/index.ts)） - `@deepseek-ai/dsh-client-ui-session`（[`packages/client/ui-session/src/index.ts`](../packages/client/ui-session/src/index.ts)） - `@deepseek-ai/dsh-client-ui-settings`（[`packages/client/ui-settings/src/index.ts`](../packages/client/ui-settings/src/index.ts)） - `@deepseek-ai/dsh-client-ui-settings-general`（[`packages/client/ui-settings-general/src/index.ts`](../packages/client/ui-settings-general/src/index.ts)） - `@deepseek-ai/dsh-client-ui-settings-models`（[`packages/client/ui-settings-models/src/index.ts`](../packages/client/ui-settings-models/src/index.ts)） - `@deepseek-ai/dsh-client-ui-settings-plugin-inventory`（[`packages/client/ui-settings-plugin-inventory/src/index.ts`](../packages/client/ui-settings-plugin-inventory/src/index.ts)） - `@deepseek-ai/dsh-client-ui-settings-plugins`（[`packages/client/ui-settings-plugins/src/index.ts`](../packages/client/ui-settings-plugins/src/index.ts)） - `@deepseek-ai/dsh-client-ui-sidebar`（[`packages/client/ui-sidebar/src/index.ts`](../packages/client/ui-sidebar/src/index.ts)） - `@deepseek-ai/dsh-client-ui-skill`（[`packages/client/ui-skill/src/index.ts`](../packages/client/ui-skill/src/index.ts)） - `@deepseek-ai/dsh-client-ui-subagent`（[`packages/client/ui-subagent/src/index.ts`](../packages/client/ui-subagent/src/index.ts)） - `@deepseek-ai/dsh-client-ui-theme`（[`packages/client/ui-theme/src/index.ts`](../packages/client/ui-theme/src/index.ts)） - `@deepseek-ai/dsh-client-ui-tool`（[`packages/client/ui-tool/src/index.ts`](../packages/client/ui-tool/src/index.ts)） - `@deepseek-ai/dsh-client-ui-trajectory`（[`packages/client/ui-trajectory/src/index.ts`](../packages/client/ui-trajectory/src/index.ts)） - `@deepseek-ai/dsh-client-ui-user-questions`（[`packages/client/ui-user-questions/src/index.ts`](../packages/client/ui-user-questions/src/index.ts)） - `@deepseek-ai/dsh-client-ui-workflow-run`（[`packages/client/ui-workflow-run/src/index.ts`](../packages/client/ui-workflow-run/src/index.ts)） - `@deepseek-ai/dsh-client-ui-workspace`（[`packages/client/ui-workspace/src/index.ts`](../packages/client/ui-workspace/src/index.ts)） - `@deepseek-ai/dsh-command-compact` — 需要 `commands` · `compact`（[`packages/compaction/command-compact/src/index.ts`](../packages/compaction/command-compact/src/index.ts)） - `@deepseek-ai/dsh-command-feedback` — 需要 `commands`（[`packages/feedback/command-feedback/src/index.ts`](../packages/feedback/command-feedback/src/index.ts)） - `@deepseek-ai/dsh-command-goal` — 需要 `commands` · `goals`（[`packages/goal/command-goal/src/index.ts`](../packages/goal/command-goal/src/index.ts)） - `@deepseek-ai/dsh-commands`（[`packages/interaction/commands/src/index.ts`](../packages/interaction/commands/src/index.ts)） - `@deepseek-ai/dsh-cordis-client-runner`（[`packages/extensions/cordis-client-runner/src/index.ts`](../packages/extensions/cordis-client-runner/src/index.ts)） - `@deepseek-ai/dsh-deepseek-llm-api-extensions`（[`packages/llm/deepseek-llm-api-extensions/src/index.ts`](../packages/llm/deepseek-llm-api-extensions/src/index.ts)） - `@deepseek-ai/dsh-experimental-client-ui-agent-team`（[`packages/experimental/client-ui-agent-team/src/index.ts`](../packages/experimental/client-ui-agent-team/src/index.ts)） - `@deepseek-ai/dsh-fs-e2b` — 需要 `e2b`（[`packages/e2b/fs-e2b/src/index.ts`](../packages/e2b/fs-e2b/src/index.ts)） - `@deepseek-ai/dsh-fs-observation-policy`（[`packages/fs/fs-observation-policy/src/index.ts`](../packages/fs/fs-observation-policy/src/index.ts)） - `@deepseek-ai/dsh-goal-round-driver` — 需要 `agents` · `goals` · `sessions`（[`packages/goal/goal-round-driver/src/index.ts`](../packages/goal/goal-round-driver/src/index.ts)） - `@deepseek-ai/dsh-host-directory-picker-auto` — 需要 `webServer` · `loader`（[`packages/host/directory-picker-auto/src/index.ts`](../packages/host/directory-picker-auto/src/index.ts)） - `@deepseek-ai/dsh-host-directory-picker-native`（[`packages/host/directory-picker-native/src/index.ts`](../packages/host/directory-picker-native/src/index.ts)） - `@deepseek-ai/dsh-host-plugin-inventory` — 需要 `loader`（[`packages/host/plugin-inventory/src/index.ts`](../packages/host/plugin-inventory/src/index.ts)） - `@deepseek-ai/dsh-llm`（[`packages/llm/llm/src/index.ts`](../packages/llm/llm/src/index.ts)） - `@deepseek-ai/dsh-lsp`（[`packages/lsp/lsp/src/index.ts`](../packages/lsp/lsp/src/index.ts)） - `@deepseek-ai/dsh-schedule` — 需要 `agents` · `sessions` · `tools` · `sessionPersistence`（[`packages/schedule/schedule/src/index.ts`](../packages/schedule/schedule/src/index.ts)） - `@deepseek-ai/dsh-session`（[`packages/core/session/src/index.ts`](../packages/core/session/src/index.ts)） - `@deepseek-ai/dsh-session-checkpoint-policy` — 需要 `llm` · `sessionPersistence` · `sessions` · `tools`（[`packages/session/session-checkpoint-policy/src/index.ts`](../packages/session/session-checkpoint-policy/src/index.ts)） - `@deepseek-ai/dsh-session-projection`（[`packages/session/session-projection/src/index.ts`](../packages/session/session-projection/src/index.ts)） - `@deepseek-ai/dsh-session-stats` — 需要 `sessionProjections`（[`packages/session/session-stats/src/index.ts`](../packages/session/session-stats/src/index.ts)） - `@deepseek-ai/dsh-session-turn-outline` — 需要 `sessionProjections`（[`packages/session/session-turn-outline/src/index.ts`](../packages/session/session-turn-outline/src/index.ts)） - `@deepseek-ai/dsh-skill-badge` — 需要 `skills`（[`packages/skill/skill-badge/src/index.ts`](../packages/skill/skill-badge/src/index.ts)） - `@deepseek-ai/dsh-storage`（[`packages/storage/storage/src/index.ts`](../packages/storage/storage/src/index.ts)） - `@deepseek-ai/dsh-subagent`（[`packages/subagent/subagent/src/index.ts`](../packages/subagent/subagent/src/index.ts)） - `@deepseek-ai/dsh-subprocess-local`（[`packages/subprocess/subprocess-local/src/index.ts`](../packages/subprocess/subprocess-local/src/index.ts)） - `@deepseek-ai/dsh-terminal`（[`packages/terminal/terminal/src/index.ts`](../packages/terminal/terminal/src/index.ts)） - `@deepseek-ai/dsh-tool-ask-user` — 需要 `tools` · `userInteraction`（[`packages/interaction/tool-ask-user/src/index.ts`](../packages/interaction/tool-ask-user/src/index.ts)） - `@deepseek-ai/dsh-tool-call-timeout-policy` — 需要 `tools`（[`packages/guard/timeout-policy/src/index.ts`](../packages/guard/timeout-policy/src/index.ts)） - `@deepseek-ai/dsh-tool-cordis` — 需要 `tools` · `systemPrompt` · `dynamicCordisRunner` · `cordisInspect`（[`packages/extensions/tool-cordis/src/index.ts`](../packages/extensions/tool-cordis/src/index.ts)） - `@deepseek-ai/dsh-tool-subagent-control` — 需要 `tools` · `subagents`（[`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts)） - `@deepseek-ai/dsh-user-questions`（[`packages/interaction/user-questions/src/index.ts`](../packages/interaction/user-questions/src/index.ts)） - `@deepseek-ai/dsh-webhook` — 需要 `agents` · `agentDefaultModel` · `agentPresets` · `permissionPresets` · `sessionTitle` · `workspaceRegistry`（[`packages/webhook/webhook/src/index.ts`](../packages/webhook/webhook/src/index.ts)） - `@deepseek-ai/dsh-workspace` — 需要 `storageDomain` · `sessionPersistence`（[`packages/workspace/workspace/src/index.ts`](../packages/workspace/workspace/src/index.ts)） ## Seam 包（不可直接加载） 抽象服务类——部署时应改为加载具体的实现包（参见[能力 seam](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md)）。 - `@deepseek-ai/dsh-attachment` — 抽象 `AttachmentStore`（[`packages/attachment/attachment/src/index.ts`](../packages/attachment/attachment/src/index.ts)） - `@deepseek-ai/dsh-code-runtime` — 抽象 `CodeRuntime`（[`packages/code-runtime/code-runtime/src/index.ts`](../packages/code-runtime/code-runtime/src/index.ts)） - `@deepseek-ai/dsh-compaction` — 抽象 `CompactionEngine`（[`packages/compaction/compaction/src/index.ts`](../packages/compaction/compaction/src/index.ts)） - `@deepseek-ai/dsh-credentials` — 抽象 `Credentials`（[`packages/credentials/credentials/src/index.ts`](../packages/credentials/credentials/src/index.ts)） - `@deepseek-ai/dsh-file-reference` — 抽象 `FileReferenceService`（[`packages/context/file-reference/src/index.ts`](../packages/context/file-reference/src/index.ts)） - `@deepseek-ai/dsh-fs` — 抽象 `FileSystem`（[`packages/fs/fs/src/index.ts`](../packages/fs/fs/src/index.ts)） - `@deepseek-ai/dsh-host-directory-picker` — 抽象 `DirectoryPicker`（[`packages/host/directory-picker/src/index.ts`](../packages/host/directory-picker/src/index.ts)） - `@deepseek-ai/dsh-jobs` — 抽象 `JobRegistry`（[`packages/jobs/jobs/src/index.ts`](../packages/jobs/jobs/src/index.ts)） - `@deepseek-ai/dsh-sandbox` — 抽象 `SandboxProvider`（[`packages/sandbox/sandbox/src/index.ts`](../packages/sandbox/sandbox/src/index.ts)） - `@deepseek-ai/dsh-session-persistence` — 抽象 `SessionPersistence`（[`packages/session/session-persistence/src/index.ts`](../packages/session/session-persistence/src/index.ts)） - `@deepseek-ai/dsh-session-query` — 抽象 `SessionQueryEngine`（[`packages/session-query/session-query/src/index.ts`](../packages/session-query/session-query/src/index.ts)） - `@deepseek-ai/dsh-settings` — 抽象 `Settings`（[`packages/settings/settings/src/index.ts`](../packages/settings/settings/src/index.ts)） - `@deepseek-ai/dsh-shell` — 抽象 `ShellExecutor`（[`packages/shell/shell/src/index.ts`](../packages/shell/shell/src/index.ts)） - `@deepseek-ai/dsh-spill` — 抽象 `SpillStore`（[`packages/spill/spill/src/index.ts`](../packages/spill/spill/src/index.ts)） - `@deepseek-ai/dsh-subprocess` — 抽象 `SubprocessRuntime`（[`packages/subprocess/subprocess/src/index.ts`](../packages/subprocess/subprocess/src/index.ts)） - `@deepseek-ai/dsh-workflow` — 抽象 `WorkflowEngine`（[`packages/workflow/workflow/src/index.ts`](../packages/workflow/workflow/src/index.ts)） ## 库包（无插件入口） 由其他包作为库导入；`cordis.yml` 无法加载它们。 - `@deepseek-ai/dsh-agent-loop-testkit`（[`packages/test-support/agent-loop-testkit/src/index.ts`](../packages/test-support/agent-loop-testkit/src/index.ts)） - `@deepseek-ai/dsh-anonymous-user-id`（[`packages/identity/anonymous-user-id/src/index.ts`](../packages/identity/anonymous-user-id/src/index.ts)） - `@deepseek-ai/dsh-app-boot`（[`packages/boot/app-boot/src/index.ts`](../packages/boot/app-boot/src/index.ts)） - `@deepseek-ai/dsh-atomic-write`（[`packages/util/atomic-write/src/index.ts`](../packages/util/atomic-write/src/index.ts)） - `@deepseek-ai/dsh-base`（[`packages/bundle/base/src/index.ts`](../packages/bundle/base/src/index.ts)） - `@deepseek-ai/dsh-brand`（[`packages/util/brand/src/index.ts`](../packages/util/brand/src/index.ts)） - `@deepseek-ai/dsh-client-store`（[`packages/client/store/src/index.ts`](../packages/client/store/src/index.ts)） - `@deepseek-ai/dsh-client-test-runtime`（[`packages/test-support/client-runtime/src/index.ts`](../packages/test-support/client-runtime/src/index.ts)） - `@deepseek-ai/dsh-client-ui-primitives`（[`packages/client/ui-primitives/src/index.ts`](../packages/client/ui-primitives/src/index.ts)） - `@deepseek-ai/dsh-client-ui-slots`（[`packages/client/ui-slots/src/index.ts`](../packages/client/ui-slots/src/index.ts)） - `@deepseek-ai/dsh-client-web`（[`packages/client/web/src/index.ts`](../packages/client/web/src/index.ts)） - `@deepseek-ai/dsh-cmdline`（[`packages/boot/cmdline/src/index.ts`](../packages/boot/cmdline/src/index.ts)） - `@deepseek-ai/dsh-deque`（[`packages/util/deque/src/index.ts`](../packages/util/deque/src/index.ts)） - `@deepseek-ai/dsh-experimental-agent-team-profile`（[`packages/experimental/agent-team-profile/src/index.ts`](../packages/experimental/agent-team-profile/src/index.ts)） - `@deepseek-ai/dsh-experimental-agent-team-web-profile`（[`packages/experimental/agent-team-web-profile/src/index.ts`](../packages/experimental/agent-team-web-profile/src/index.ts)） - `@deepseek-ai/dsh-experimental-webworker-packer`（[`packages/experimental/webworker-packer/src/index.ts`](../packages/experimental/webworker-packer/src/index.ts)） - `@deepseek-ai/dsh-experimental-webworker-runtime`（[`packages/experimental/webworker-runtime/src/index.ts`](../packages/experimental/webworker-runtime/src/index.ts)） - `@deepseek-ai/dsh-home-paths`（[`packages/util/home-paths/src/index.ts`](../packages/util/home-paths/src/index.ts)） - `@deepseek-ai/dsh-hook-protocol`（[`packages/hooks/hook-protocol/src/index.ts`](../packages/hooks/hook-protocol/src/index.ts)） - `@deepseek-ai/dsh-launch-environment`（[`packages/util/launch-environment/src/index.ts`](../packages/util/launch-environment/src/index.ts)） - `@deepseek-ai/dsh-llm-mock-server`（[`packages/test-support/llm-mock-server/src/index.ts`](../packages/test-support/llm-mock-server/src/index.ts)） - `@deepseek-ai/dsh-loader-smoke`（[`packages/test-support/loader-smoke/src/index.ts`](../packages/test-support/loader-smoke/src/index.ts)） - `@deepseek-ai/dsh-native-command`（[`packages/util/native-command/src/index.ts`](../packages/util/native-command/src/index.ts)） - `@deepseek-ai/dsh-output-retention`（[`packages/util/output-retention/src/index.ts`](../packages/util/output-retention/src/index.ts)） - `@deepseek-ai/dsh-sandbox-windows-acl`（[`packages/sandbox/sandbox-windows-acl/src/index.ts`](../packages/sandbox/sandbox-windows-acl/src/index.ts)） - `@deepseek-ai/dsh-scope`（[`packages/core/scope/src/index.ts`](../packages/core/scope/src/index.ts)） - `@deepseek-ai/dsh-sdk-client`（[`packages/sdk/client/src/index.ts`](../packages/sdk/client/src/index.ts)） - `@deepseek-ai/dsh-sdk-minimal`（[`packages/bundle/sdk-minimal/src/index.ts`](../packages/bundle/sdk-minimal/src/index.ts)） - `@deepseek-ai/dsh-sdk-protocol`（[`packages/sdk/protocol/src/index.ts`](../packages/sdk/protocol/src/index.ts)） - `@deepseek-ai/dsh-session-snapshot`（[`packages/test-support/session-snapshot/src/index.ts`](../packages/test-support/session-snapshot/src/index.ts)） - `@deepseek-ai/dsh-session-telemetry`（[`packages/session/session-telemetry/src/index.ts`](../packages/session/session-telemetry/src/index.ts)） - `@deepseek-ai/dsh-session-title-llm`（[`packages/session/session-title-llm/src/index.ts`](../packages/session/session-title-llm/src/index.ts)） - `@deepseek-ai/dsh-subagent-in-process-driver`（[`packages/subagent/subagent-in-process-driver/src/index.ts`](../packages/subagent/subagent-in-process-driver/src/index.ts)） - `@deepseek-ai/dsh-timeout`（[`packages/util/timeout/src/index.ts`](../packages/util/timeout/src/index.ts)） - `@deepseek-ai/dsh-typert-generator`（[`packages/typert/generator/src/index.ts`](../packages/typert/generator/src/index.ts)） - `@deepseek-ai/dsh-typert-protocol`（[`packages/typert/protocol/src/index.ts`](../packages/typert/protocol/src/index.ts)） - `@deepseek-ai/dsh-typert-registry`（[`packages/typert/registry/src/index.ts`](../packages/typert/registry/src/index.ts)） - `@deepseek-ai/dsh-util-crypto`（[`packages/util/crypto/src/index.ts`](../packages/util/crypto/src/index.ts)） - `@deepseek-ai/dsh-util-time`（[`packages/util/time/src/index.ts`](../packages/util/time/src/index.ts)） - `@deepseek-ai/dsh-util-values`（[`packages/util/values/src/index.ts`](../packages/util/values/src/index.ts)） - `@deepseek-ai/dsh-util-workspace-path`（[`packages/util/workspace-path/src/index.ts`](../packages/util/workspace-path/src/index.ts)） - `@deepseek-ai/dsh-win32-process`（[`packages/subprocess/win32-process/src/index.ts`](../packages/subprocess/win32-process/src/index.ts)） # 开发指南 [English](development.md) | 中文 搭建教程引导新贡献者从准备前置条件开始，直到检出目录通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 组织方式。设计依据与实现细节属于链接的 Agent Note 和脚本。 ## 搭建教程 ### 前置条件 - Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md)。 - 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。 - Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。 - 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。 ### 首次搭建 在仓库根目录安装依赖： ```sh pnpm install ``` 安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.zh.md) 负责钩子路径的安全约定；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md) 负责合并驱动。 如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装： ```sh node scripts/install-lefthook.mjs ``` 如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。 新克隆后请先运行一次类型检查： ```sh pnpm run typecheck ``` `pnpm run typecheck` 成功退出即表示搭建完成。 ## 贡献者参考 ### TypeScript 项目布局 仓库使用相互隔离的 Host 与 Client aggregate。普通包只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`；`host/webserver`、`compaction/compaction` 与 `typert/registry` 三个包被两个 aggregate 同时引用，作为共享 leaf，让两侧对同一份源码做类型检查。 | 文件 | 角色 | 是否构成 program？ | |---|---|---| | `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `scripts/` 时的解析配置。 | 否 | | `tsconfig.host.json` | Host aggregate：Host 包、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 | | `tsconfig.client.json` | Client aggregate：`packages/client/*` 包及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 | | `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 | | `tsconfig.base.client.json` | 浏览器编译设置（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` 包 extends。 | 否 | Host 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律： - `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。 - 构造全仓 `ts.Program` 的脚本显式以 `tsconfig.host.json` 或 `tsconfig.client.json` 为种子——根 solution 永不作为种子，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。 - 新包只登记进一个 aggregate；只有上述拆分包同时携带两个 leaf 配置，共享 leaf 因两侧需要对同一份源码做类型检查而登记进两个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client 插件的两份运行时产物都在 Client 构建阶段生成。 拆分 Host/Client tsconfig 的包有六个：`api/remotes`、`api/gateway`、`api/session-controller`、`api/workspace-controller`、`client/connection` 与 `session-query/session-log-export`。`api/remotes` 的 Host 入口进入 Host Typert 图，而 Client 入口导入生成的 `/remote` 声明；`session-log-export` 则让 Node archive 生产代码不进入浏览器 controller。每个拆分包根 `tsconfig.json` 因此只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf；该门禁按「两个 leaf 配置同时存在」自动发现拆分包，所以新拆分的包会自动纳入管辖。[`api-remotes` README](../packages/api/remotes/README.zh.md) 与 [`session-log-export` README](../packages/session-query/session-log-export/README.zh.md)分别说明其拆分。 根构建按生成依赖排序： ```sh tsc -b tsconfig.host.json tsdown --env.DSH_BUILD_FACE host tsc -b tsconfig.client.json tsdown --env.DSH_BUILD_FACE client pnpm run build:web ``` 两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client 包，也不维护 Host/Client 包过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client 插件在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。 Typert 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 Typert。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成约定构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md)。 `pnpm run build` 会内联根包版本、七位源码 commit，并在 Git 报告本地变化时内联 dirty 标记；调用方提供的其他 `DSH_CLIENT_*` 值也会被继承。`pnpm run build:official` 是与 CI 和 release 产物构建等价的跨平台本地命令，并省略本地 dirty 标记。每次完整构建成功后都会写入一份被 gitignore 的记录，把精确公开值与 Vite 输出及动态 client bundle 绑定；release 打包和 built Web 测试会拒绝缺少记录或被后续局部构建改动的产物。`pnpm run dev:web` 仍需要先执行完整构建来准备产物树，但会在启动时读取一次当前版本和 Git 状态，并在本次会话的所有 watcher stage 之间共享该环境；它不会校验完整构建记录，因为 watcher stage 会重写记录覆盖的产物。 静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本假定调用它的公共命令或调度器门禁已经依赖 Typert 约定生成阶段或完整构建。两个 aggregate 的设置见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md)，门禁准备约定见 [Typert Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md)。 业务服务在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.zh.md)。 如果相关的本地检查需要使用构建后的包产物，请先构建一次： ```sh pnpm run build ``` `pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验包入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。 ### 环境变量 真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证： ```sh DEEPSEEK_API_KEY=sk-... DEEPSEEK_BASE_URL=https://... # optional ``` `DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。 ### Git 集成 当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。[双语文档约定](i18n/README.zh.md#the-pairing-contract)列出该驱动接受的确切文件和状态。 安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md#failure-contract)负责记录。 lefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点： - `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件，并通过一次有界重试应用 Oxlint 修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫； - `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查； - `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 Typert 约定生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。 vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。 除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。 贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。 ### CI 门禁 keyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。 ### 日常命令 根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；包公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。 ### Profile 运行 从源码 checkout 运行这些演示前，请单独执行仓库构建： ```sh pnpm run build ``` 单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`： ```sh pnpm dsh --profile headless "summarize this workspace" ``` PTC mode 演示启用代码式工具展示，并运行同一个 headless profile： ```sh pnpm run demo:ptc -- "summarize this workspace" ``` ### TODO 标记 请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序： - `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`； - `TODO`：应当尽快修复的问题，等资源到位即可处理； - `XXX`：也许某天会修复的问题，优先级最低，不作承诺。 请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。 ### 逐字记录类型定义（`ts type-equiv`） [子系统](subsystems/README.zh.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切类型定义和源码约定。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号： ```json { "doc": "docs/subsystems/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" } ``` `pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `"projection": "public-api"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码约定和确切类型定义。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例的计算之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。 # API Gateway [English](api-gateway.md) | 中文 本文是 Typert API Gateway 的当前状态参考。它描述业务服务如何声明一元 Remote 方法、构建如何生成 Host 与 Client 约定，以及调用如何复用 Connection 的 RPC 与 `/api` 路由。会话事件、增量数据和其他流协议不属于本文范围；它们可以使用同一个 Connection，但不使用 Remote 方法描述符。 ## 编程模型 业务服务通过 `@Remote` 或 `@RemoteScope` 选择对 Client 开放的方法。未标记的方法不会进入生成的 Client 类型或运行时贡献，也不能通过 `ctx.remote` 调用。 `@Remote` 表示调用根 Host Context 中注册的 Cordis 服务。复杂的 Host 对象不能直接跨 wire 传输；业务包必须通过 `TypertLookupMap` 声明它与 wire identity 的关联，并在运行时向 `ctx.typert.lookups` 注册默认解析提供方。例如 `Agent` 参数在 Host 签名中名为 `agent`，生成的 wire 字段为 `agentId`，Gateway 在调用业务方法前将 id 解析为 Host 对象。Host 组合可以用 `ctx.typert.lookups.configure()` 覆盖某个 lookup key 的解析策略，而不改变业务包拥有的参数名、wire 字段或规范类型 symbol。 `@RemoteScope(key)` 表示先通过 `ctx.typert.contexts` 把 identity 解析为一个作用域 Context，再从该 Context 取得服务并调用方法。它适用于方法本身依赖作用域组合、而不需要显式接收 `Agent` 等对象的情形。 服务通常继承 `TypertRemoteService`，让 Cordis 服务 key 与默认 Remote namespace 在构造器中显式绑定。已有其他基类的服务可以改为声明 `readonly typertRemote = bindTypertRemote(this, serviceKey)`；两种方式都会留下可检查的公开 binding，不依赖编译器向构造函数注入 symbol。 ```ts import type { Agent } from '@deepseek-ai/dsh-agent' import { TypertRemoteService, Remote, RemoteScope } from '@deepseek-ai/dsh-typert-protocol' import type { Context } from '@deepseek-ai/cordis' export interface CreateGoalRequest { objective: string } export interface CreateGoalResult { accepted: boolean } export class GoalService extends TypertRemoteService { constructor(ctx: Context) { super(ctx, 'goals') } @Remote('create') createForClient( agent: Agent, request: CreateGoalRequest, signal: AbortSignal, ): CreateGoalResult { signal.throwIfAborted() return this.create(agent, request) } @RemoteScope('agent', 'current') currentForClient(): CreateGoalResult { return { accepted: true } } private create(_agent: Agent, request: CreateGoalRequest): CreateGoalResult { return { accepted: request.objective.length > 0 } } } ``` Remote 方法可以同步返回或返回 Promise。若需要协作式取消，Host 签名的最后一个参数必须是全局类型的 `signal: AbortSignal`；它记录在描述符中而不是进入 `args`，Client 生成的方法则接受最后一个可选的 `AbortSignal`。 Client 使用普通对象上的具体函数，不使用 JavaScript Proxy。直接调用与作用域调用分别出现在 `ctx.remote.` 和 `agentCtx.remote.`。每个 namespace 都是注册为 `remote.` 的可追踪 Cordis 子服务；Client assembly 通过 `ctx.remote.$mount()` 挂载贡献，最后一个方法撤回后该 namespace 随即卸载。依赖声明归实际调用方所有：只有读取 `ctx.remote.` 或 `agentCtx.remote.` 的业务包才在自己的 `inject` 中同时声明 `remote` 与 `remote.`；只负责挂载 contribution 的 assembly，以及不调用该 namespace 的上层运行时，不代业务包声明 namespace 依赖。当一个 `@Remote` 方法恰好有一个 lookup 参数、且同名 `TypertContextMap` 使用相同 wire identity 时，生成的作用域签名会省略该 identity 参数。`@RemoteScope` 只生成作用域调用接口。 ```ts ignore-check import type { SessionId } from '@deepseek-ai/dsh-session/types' import type { AgentContext } from '@deepseek-ai/dsh-api-session-controller/client' import type { Context } from '@deepseek-ai/cordis' import type {} from '@deepseek-ai/dsh-api-remotes/client' export const inject = ['remote', 'remote.goals'] declare const ctx: Context declare const agentCtx: AgentContext declare const agentId: SessionId await ctx.remote.goals.create(agentId, { objective: 'ship it' }) await agentCtx.remote.goals.create({ objective: 'ship it' }) ``` Client 应用只装配 `@deepseek-ai/dsh-api-remotes`。该包以运行时值导入被选业务包的 `/remote` 子路径，通过 `ctx.remote.$mount()` 挂载贡献，同时重新导出相同文件中的声明合并。增加一个 Host Remote 包是 Client 组合所有者的显式选择；业务组件不需要分别加载 Typert Gateway 或业务包的 Remote JS。 `api-remotes` 装配与 `ctx.remote` 约定不依赖 React；任何 Client 装配能看到的 Host 方法都只限于生成时选择的 Remote 方法。 ## 组件职责 | 位置 | 包或入口 | 职责 | |---|---|---| | 共享 | `@deepseek-ai/dsh-typert-protocol` | 声明 decorator、Gateway binding、可合并协议映射、调用描述符及提供方类型；不启动 TypeScript 分析，也不注册 Cordis 服务 | | 构建 | `@deepseek-ai/dsh-typert-generator` | 从 Host `ts.Program` 严格分析 Remote 签名、类型图、lookup、Context 与源码位置，并生成 Host 和 Host-for-Client 产物 | | Host | `@deepseek-ai/dsh-typert-registry` 与 Loader | 把生成的 Host 描述符、schema 及业务包注册项放入 `ctx.typert`，并持有 lookup 与 Context 提供方 | | Host | `@deepseek-ai/dsh-api-session-controller` | 负责应用的 Agent/Session 身份策略，并配置对应的 Typert lookup | | Host | `@deepseek-ai/dsh-api-gateway` | 提供 `ctx.typertGateway`，认领 Remote endpoint，解析对象或 Context，调用实时 Cordis 服务，并校验请求值和返回值 | | Client | `@deepseek-ai/dsh-api-gateway/client` | 提供 `ctx.remote` 与 `remote.` 子服务，把生成的描述符挂成具体方法，并通过 Connection 发起、校验和取消调用 | | Client | `@deepseek-ai/dsh-api-remotes/client` | 显式选择并挂载本应用允许使用的 `/remote` 贡献，向业务代码带入对应的声明合并 | | 双侧 | `@deepseek-ai/dsh-client-connection` | 提供 RPC carrier、请求关联、信任边界、取消、响应 envelope 与 `/api` HTTP bridge | API Gateway 包同时拥有 Host dispatcher 与 Client Remote endpoint 两个对等入口，但两侧构建不会进入同一个 `ts.Program`。Host 入口不导入 Client 的 Cordis `Context` 合并，Client 入口也不导入 Host Gateway 服务。 ## 严格生成流水线 根构建依次执行 `build:lib:host`、`build:lib:client` 与 `build:web`。Host lib 阶段先运行 `tsc -b tsconfig.host.json`，再运行 `tsdown --env.DSH_BUILD_FACE host`；Typert generator 由正常 Host Project Reference 图编译，并在这次 tsdown 中以 Host aggregate 为唯一 `ts.Program` 种子运行。Client lib 阶段随后运行 `tsc -b tsconfig.client.json` 与 `tsdown --env.DSH_BUILD_FACE client`，使用刚生成的 Remote Client 声明和运行时贡献，但不再次启动 Typert。 两次 tsdown 都接收完整 workspace，且都只打包 `lib/types` 中由对应 tsc 阶段发射的 JavaScript。根配置不扫描 Client 产物、不按包名分类，也不向 tsdown 传维护式 filter；各包的本地配置根据 `DSH_BUILD_FACE` 返回当前阶段的入口。普通 Client 插件在 Client 阶段一起生成 Node loader 入口与 browser bundle。 `api/remotes`、`api/gateway`、`api/session-controller` 与 `api/workspace-controller`（外加 `client/connection`）都拆分 TypeScript face。`api/remotes` 的 Client project 依赖业务包在 Host tsdown 中生成的 `/remote` 声明；根 aggregate 与直接消费方必须分别引用各拆分包自己的 `tsconfig.host.json` 或 `tsconfig.client.json`。`api-remotes` 的 `clientBundle(..., { hostPhase: true })` 让 Host 入口在 Host tsdown 中生成，让 Client tsdown 只生成 browser 入口。Agent/Session lookup 策略位于 `@deepseek-ai/dsh-api-session-controller`，而非 `api-remotes`。 每个贡献业务包把生成文件写入自己的 `lib/`，而不是源码目录： | 文件 | 消费方 | 内容 | |---|---|---| | `typert.host.js` | Host Loader | Host face 的运行时反射、严格调用描述符和 schema 注册值 | | `typert.host.d.ts` | Host 类型系统 | Host face 的生成声明 | | `typert.remote-client.js` | `api-remotes` | 可挂载的 `TypertRemoteContribution`，包含严格描述符与运行时 codec | | `typert.remote-client.d.ts` | Client 类型系统 | `TypertRemoteNamespaceMap` 与 `TypertRemoteScopeMap` 的声明合并及 Client-safe 类型引用 | | `typert.remote-client.d.ts.map` | 编辑器 | 将生成的方法属性映射回 Host 包中的 Remote 方法声明 | 业务包通过 `./typert` 暴露 Host Loader 入口，通过 `./remote` 暴露 Host-for-Client 入口。生成器同时校验这些包 export 及发布文件清单；只有具备相应入口的显式贡献包才会生成产物。 Remote Client 声明中的参数名来自 wire 字段，参数和返回类型则引用原业务包导出的 Client-safe 类型。声明 map 把 `ctx.remote.goals.create` 最终解析到的生成属性映射到带 `@Remote` 的 Host 源方法，因此支持 declaration-map 的编辑器可以从 Client 调用跳到真实实现，而不是停在生成的 `.d.ts`。 严格分析要求 Remote 是公开、非静态、有具体实现的实例方法。方法不能是泛型；参数必须是具名且必填的简单标识符，不能使用解构、默认值、rest 或可选参数。可 JSON 表示的普通类型由 Typert 生成严格 schema；工作区 class 等复杂对象必须具有唯一的 `TypertLookupMap` 声明。lookup 与 Context 包同时负责静态声明合并和运行时提供方注册；缺少任一侧都会导致构建失败，或者首次调用需要该提供方时失败。 ## 运行时调用 Remote 调用使用 Connection 的 `/api` 路由。Client Remote 调用 `connection.rpc.call('/api', '/', { args }, signal)`；HTTP carrier 对应 `POST /api//`，payload 只包含一个具名 `args` 对象。 Connection 在 HTTP bridge 之前执行 `/api` 的统一信任检查，再在共享 FetchHandler 内分发。Typert Gateway 只认领存在严格描述符或活跃 SRC marker 的两段式 endpoint；功能自有的精确 Fetch 路由处理非 JSON 响应，其他请求返回 404。Connection 拥有传输、RPC id、响应 envelope 和请求取消，Gateway 只拥有 Remote 数据协议和业务分发。替换 Connection carrier 不要求改变 Remote 描述符或 Client 编程接口。 Gateway 每次调用都从当前注册表解析描述符和实时服务，不缓存业务对象。它要求 `args` 的字段集合与描述符完全一致，先用 codec 校验 wire 值，再通过注册的 lookup 或 Context 提供方解析对象或接收者，最后调用 binding 指向的服务方法并校验返回值。缺少提供方、identity 未命中、binding 不一致、参数缺失或多余、schema 失败和方法不存在都会在进入业务代码前或离开业务代码后失败。 lookup 提供方的 `register()` 同时提供稳定声明和默认 resolver；`configure()` 提供由 Host 组合拥有、可异步执行且受 effect 生命周期约束的 resolver。配置可以先于提供方挂载；没有提供方时调用仍以 `gateway/lookup-unavailable` 失败，配置卸载后则恢复提供方默认策略。Session Controller 负责 `agent` 与 `session` 的标准 resolver 语义：复用 live Agent，自动恢复普通冷会话，对并发恢复去重，并拒绝由 subagent routing 拥有的 identity；`session` lookup 返回该 Agent 的 Session。恢复失败与 ownership fence 抛出携带自有码的 `RemoteError`（`session/not-found` 或 `session/agent-busy`），Gateway 原样编码上 wire；只有未归类的 throw 才折成 `gateway/internal`。 Client 卸载一个贡献时会一起移除描述符和具体方法，中止其进行中的调用，并使外部仍持有的陈旧方法句柄拒绝继续调用。Host 上已经注册过的严格 endpoint 被撤回后也不会降级到 SRC 推断，以免热卸载悄然降低校验强度。 ## SRC 开发回退 Host 通过 `node --import tsx/esm` 从源码启动时不会执行 Typert 编译插件。标准 decorator 初始化器仍会把方法名和调用模式记录到 Service 原型上的带版本描述符中，`TypertRemoteService` 或 `bindTypertRemote()` 则提供显式服务 binding；Gateway 因而可以在不启动 `ts.Program` 的情况下构造一个较弱的临时描述符。描述符使用稳定的字符串属性名，因此 `remoteMethods()` 能读取协议包另一个已安装副本写入的标记。 SRC 回退从运行中函数解析简单参数名。参数名与某个已注册 lookup 的 `parameter` 相同，例如 `agent` 或 `session`，就使用其 `agentId` 或 `sessionId` wire 字段并在 Host 解析对象；其他参数只检查值是否为无循环、无特殊 prototype 的 JSON-safe 数据。`@RemoteScope` 直接使用已注册 Host Context 提供方的 wire 字段。SRC 不读取 TypeScript 类型，不生成 Zod schema，不推断可选参数，也不支持解构、默认值、rest 或重复参数名。 SRC 只解决 Host 源码进程的分发问题。Client 不会从运行中的 Host 发现 decorator，Client Remote 也拒绝挂载缺少严格 codec 的 SRC 描述符；其类型、codec 和 Remote 注册值始终来自最近一次生成的 `lib/typert.remote-client.*`。 ## 开发模式 Web 开发先使用 `pnpm run build` 准备当前 Host、Client 与 Web 产物，然后在两个终端中分别运行源码 Host 和 Client plugin watcher： ```sh pnpm dsh web pnpm run dev:web ``` `dsh` 通过 tsx 启动 Host 源码，所以 Host 可以使用 SRC 回退；`dev:web` 只监听带 `dsh.client` 声明的 Client 插件并重写其 `lib/client.js`，它不会分析 Host decorator，也不会生成 Remote Client DTS。 只修改 Remote 方法实现体而不改变约定时，无需重新生成 Typert 文件。新增或删除 decorator、修改导出名、namespace、参数、返回值、lookup、Context 或取消签名时，重新执行有序 lib 构建，让 Host 先生成严格约定，再让 Client 编译并打包新的贡献： ```sh pnpm run build:lib ``` 运行中的 Client watcher 会在重新打包时消费这些生成文件。若已单独运行 `pnpm run build:lib:host` 刷新 Host 约定，也可再运行 `pnpm run build:lib:client` 完成 Client 侧；干净工作树不能跳过 Host 阶段。仅重新编译前端源码不能从 Host decorator 推导新类型。`pnpm run typecheck` 会执行 Host lib 阶段后再运行 Client tsc，CI 与发布构建也使用同一顺序。 ## 边界 Remote 只处理有单个请求与单个结果的一元方法调用。会话事件流、分页、增量 reduce、projection 和实体子流需要独立的数据协议与注册模型；即使它们复用 Connection，也不应伪装成 Remote 方法或放入调用描述符。 API 各层按 `remotes → gateway → connection → webserver` 组织。BFF 与 Typert RPC 层位于 `packages/api`；Connection 与 WebServer 位于 `packages/client/connection` 和 `packages/host/webserver`。需要流式或浏览器原生响应的功能注册精确的 Connection Fetch 路由，而不定义 Remote 方法。 lookup 策略按 key 配置，因此所有 `agent` 或 `session` 参数共享冷恢复行为。只接受 live 对象需要显式的逐参数或逐 endpoint 策略，而这种策略并不存在；不能通过业务方法内部猜测对象是否来自恢复。 # DeepSeek 官方 LLM API 协议扩展 [English](deepseek-llm-api-wire-extensions.md) | 中文 本参考文档定义 [`@deepseek-ai/dsh-llm-deepseek`](../packages/llm/llm-deepseek/README.zh.md) 在 `deepseek-official` 聊天补全请求中发送的全部 DeepSeek Harness 特有 HTTP 标头和附加 JSON 字段。本文不重复定义 DeepSeek 上游 API 持有的字段。提供方无关的 LLM（大语言模型）接口与 `llm-pi-ai` 均不实现这些扩展。 适配器将这些扩展发送至已解析的 `baseURL`，包括已配置的网关。扩展位于 `messages`、系统提示词和工具 schema 之外，因此不会增加模型输入 token，也不会改变模型可见前缀。 ## 协议命名空间与版本 | 位置 | 命名方式 | 示例 | |---|---|---| | HTTP 字段名 | 小写 kebab-case；HTTP 匹配仍不区分大小写 | `user-agent`, `x-deepseek-harness-session-id` | | DeepSeek 请求正文扩展字段 | 使用保留 `dsh_` 前缀的 snake case | `dsh_plugin_packages`, `dsh_session_log` | | DSH 持有的嵌套 JSON 成员 | Camel case | `afterSeq`, `throughSeq`, `sessionId` | | 带标签的值 | 使用 kebab-case 字符串；持久事件采用 `domain/action` | `session-log-deepseek/delivery-accepted` | 每个正文扩展独立持有自身的 `version`。版本仅适用于包含该字段的对象；不同字段的版本之间不存在兼容或排序关系。JSON 成员顺序不属于协议。 [`DeepSeekLlmApiExtensionRegistry`](../packages/llm/deepseek-llm-api-extensions/README.zh.md) 为每个顶层扩展名保留一个提供方。空名称、两端带空白的名称、重复注册以及与 DeepSeek 基础请求冲突的名称都会在 HTTP 分派前失败。 ## 请求标头 | 标头 | 出现条件 | 值 | |---|---|---| | `user-agent` | 每个提供方 HTTP 请求，包括 Files API 操作 | 采用 `product/version (+url)` 形式的应用身份；默认产品为 `deepseek-harness` | | `x-deepseek-harness-user-id` | 每个已授权的聊天补全请求 | 已解析 Harness home 的稳定匿名 UUID | | `x-deepseek-harness-session-id` | 携带会话 id 的聊天补全请求 | 确切的请求 `sessionId` 字符串 | | `x-deepseek-harness-compact` | 用途为 `compaction` 的聊天补全请求 | 字面字符串 `1` | 凭据失败发生在解析匿名用户 id 之前，因此未授权请求既不会发送这些标头，也不会创建身份文件。没有会话的直接请求会省略 `x-deepseek-harness-session-id`。会话标题请求没有额外的用途标头；请求携带 `sessionId` 时，仍然适用普通的会话 id 规则。 ## 正文扩展事务 适配器先序列化包括确切 `messages` 在内的完整基础正文，再让已注册提供方准备字段。提供方会收到该不可变正文、请求取消信号，以及可选的 `sessionId` 和辅助调用 `purpose`。提供方返回 `undefined` 时，本次请求会省略其字段。 系统将已准备的 JSON 值与提供方持有的状态分离，再将其作为基础字段的顶层同级成员合并，并序列化到同一个 HTTP 正文中。准备失败或冲突会阻止请求。组合未挂载注册表时，适配器发送未经扩展的基础正文。 已配置端点返回 HTTP 2xx 后，适配器会在读取 SSE 正文之前运行已准备的 `accept()` 事务。传输失败和非 2xx 响应不会接受任何贡献。即使端点返回 2xx，接受失败仍会使模型请求失败。接受仅记录端点级 HTTP 成功，不表示 SSE 流已完整结束，也不表示端点已持久化扩展。 ## `dsh_plugin_packages` [`@deepseek-ai/dsh-plugin-package-inventory-deepseek`](../packages/llm/plugin-package-inventory-deepseek/README.zh.md) 贡献完整存活的 Loader-backed 插件包清单。该字段默认启用。 ```json { "dsh_plugin_packages": { "version": 1, "packages": [ { "name": "@deepseek-ai/dsh-example", "version": "0.1.1-rc.2" } ] } } ``` | 成员 | 类型 | 含义 | |---|---|---| | `version` | `1` | `dsh_plugin_packages` 的 schema 版本 | | `packages` | 数组 | 本次请求的完整存活集合 | | `packages[].name` | 字符串 | 来自所属 manifest（元数据清单）的确切非空 npm 包名 | | `packages[].version` | 字符串 | 来自同一 manifest 的确切非空包版本 | 每个请求都会重新读取宿主树中的存活非分组 Loader 配置项；请求会话存在 standing agent-preset 树时，也会读取该树。相对与绝对模块使用距离自身最近的所属 manifest；裸包配置项使用激活自身的 Loader 解析基准。具名 manifest 未提供非空版本时，请求准备会失败。 发送方会对确切 `(name, version)` 组合去重，并使用与 locale 无关的文本比较，先按 `name`、再按 `version` 排序。同一包的多个同时存活版本会保留为独立配置项。接收方不得按包名折叠该数组，也不得根据数组顺序推断包的激活关系。 该清单不包含已禁用、pending、failed、unloading、disposed 和结构性 Loader 配置项。普通依赖、没有具名所属包的松散模块、以编程方式挂载的子 fiber，以及内存动态插件也不在其中，因为它们没有权威的 Loader 包来源信息。 清单已启用但没有符合条件的配置项时，系统发送 `packages: []`；禁用贡献插件时，系统省略整个 `dsh_plugin_packages` 字段。包身份属于提供方元数据，绝不进入模型输入。 ## `dsh_session_log` [`@deepseek-ai/dsh-session-log-deepseek`](../packages/session/session-log-deepseek/README.zh.md) 贡献权威会话日志的一段连续后缀。该字段默认禁用。启用后，它适用于携带存活会话且至少存在一个事件的请求；直接请求、陈旧会话 id 或空日志会省略该字段。 ```json { "dsh_session_log": { "version": 1, "session": { "version": 0, "id": "session-id", "createdAt": 1780000000000 }, "afterSeq": -1, "throughSeq": 0, "events": [ { "type": "turn/start", "seq": 0, "time": 1780000000001, "data": { "turn": 1 } } ] } } ``` | 成员 | 类型 | 含义 | |---|---|---| | `version` | `1` | `dsh_session_log` 的 schema 版本 | | `session` | 对象 | 不可变的权威 `SessionHeader` | | `afterSeq` | 整数 | 本次请求前记录为已接受的最大序号，或 `-1` | | `throughSeq` | 非负整数 | 本次请求所表示的最大序号 | | `events` | 数组 | 从 `afterSeq + 1` 到 `throughSeq` 的连续事件 | 首次上传使用 `afterSeq: -1`，并携带当前的完整日志。此后每次上传都从同一会话 id 的最大已接受水位（watermark）之后开始。发送方为每次请求仅快照一次事件数组；快照后的追加内容属于后续请求。 ### 会话头 `session` 成员是确切的 `Session.header`，不是完整的运行时会话。外层 `dsh_session_log.version` 选择本扩展 schema，`session.version` 则选择权威磁盘会话格式；两个版本值相互独立演进。 | 成员 | 出现条件 | 含义 | |---|---|---| | `version` | 必需 | 权威会话格式版本；当前为 `0` | | `id` | 必需 | 确切的会话 id | | `createdAt` | 必需 | 非负安全整数 Unix epoch 毫秒数 | | `cwd` | 可选 | 创建会话时记录的绝对工作目录 | | `parentSession` | 可选 | fork 的父会话 id | | `seedLength` | 可选 | 通过 seed 继承的前导事件数量 | | `origin` | 可选 | subagent 子项使用的字面值 `subagent` | | `delegationDepth` | 可选 | 持久化的非负 subagent 委派深度 | | `agentPreset` | 可选 | 用于组合该会话的 agent preset id | ### 权威事件信封 每个 `events` 元素都是完整的权威 `SessionEvent`，不依赖任何其他请求字段。事件始终携带 `type`、`seq`、`time` 与 `data`；它可以携带 `ignorable: true`，展示事件还可携带 `sourceEventSeqs` 与 `surfaceOp`。发送方会复制每个已有成员，不执行投影、脱敏或重建。 ### 接受水位与至少一次交付 端点返回 HTTP 2xx 后，该贡献会向同一会话追加以下权威事件： ```json { "type": "session-log-deepseek/delivery-accepted", "seq": 8, "time": 1780000000002, "data": { "sessionId": "session-id", "throughSeq": 7 } } ``` `delivery-accepted` 表示已配置端点为包含该字段的 LLM 请求返回 HTTP 2xx。它不表示 SSE 已完整结束，也不表示远端已经持久化。该事件的 `throughSeq` 必须标识一项更早的事件，`sessionId` 则标识已发送后缀所属的会话。 发送方会折叠最大的匹配 `throughSeq`，因此并发已接受请求无法使游标倒退。恢复后的进程会从持久日志重建游标。fork 会忽略命名其父会话的继承水位，因此先发送自身完整的继承前缀，再以子会话 id 推进。水位事件自身属于下一段未发送后缀。 传输失败和非 2xx 响应不会追加水位。端点接受后、本地持久化前发生崩溃时，系统可能重新发送已接受范围；不确定性只会产生重复，绝不会产生序号缺口。系统没有独立上传存储、大小上限或截断路径。 ## 暴露内容与接收方要求 请求标头会暴露 Harness 应用版本、一个匿名 Harness-home 身份和可选的会话身份。`dsh_plugin_packages` 会暴露存活 npm 包的名称与版本。启用后，`dsh_session_log` 可能暴露会话工作目录、系统提示词快照、用户与 assistant 内容、原始 assistant 分片、工具参数与结果、压缩摘要、反馈和插件持有的事件。适配器 API key 不是会话事件，因此不会进入该字段。通过 `baseURL` 选择的网关会收到与官方端点相同的值。 接收方按名称定位扩展字段，按各字段自己的 `version` 分派，保留不同的包版本，并忽略 JSON 成员顺序。会话日志接收方必须先校验连续序号范围，再解释事件类型。遇到不带 `ignorable: true` 的未知权威事件时，接收方无法进行无损重建。即使缺少注册表或某项贡献，基础请求仍然可用；字段缺失表示该项贡献不适用于本次请求。 # 会话持久化事件目录 [English](persistence-catalog.md) | 中文 会话持久事件日志中可能出现的所有事件类型：完整持久化的 `SessionEvent` 信封，以及可通过合并扩展的 `SessionEventMap` 中的每个成员，包括 `@deepseek-ai/dsh-session` 所属的词汇和本仓库中每个插件对 `@deepseek-ai/dsh-session/types` 的声明合并，并附有源 JSDoc、完整 payload 声明、surface 标记和声明位置。本文档是 [session.md](subsystems/session.zh.md)（surface 排序与 `deriveMessages()` 投影）、[persistence.md](subsystems/persistence.zh.md)（如何让日志持久化）和 [session.md](subsystems/session.zh.md#cordis-surface) 中生成区域（实时总线接线；日志事件**不是** cordis 事件，它通过唯一的 `session/event` emit 到达监听器）的补充。 英文源文件根据源码生成（`scripts/gen-persistence-catalog.ts`），并由 `pnpm run verify-persistence-catalog`（`doc-sync`（文档同步门禁）的一部分）验证新鲜度；本中文文件作为经评审对侧通过双语配对维护。声明块保留源码声明和嵌套属性的 JSDoc，只移除其所在接口／模块带来的缩进，并使用 `ts persistence-catalog` 围栏（doc-typecheck 会跳过这些围栏，因为声明引用了其所属模块中的类型）。payload 中的类型名称会链接到记录该类型的页面。参见 [persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md)。 以下信封声明组合了每个事件的 `type`、单调递增的 `seq`、以 epoch 毫秒表示的 `time`、`data`、可选的未知类型跳过标记 `ignorable`，以及条件字段 `surfaceOp`／`sourceEventSeqs`。**surface** 表示 `SurfaceEventType` 成员：它会生成一条 LLM（大语言模型）消息，并声明该事件如何加入 surface 列表。**log-only** 表示其他所有事件：这类记录可持久化、可回放，但不参与派生历史。每个 payload 均可进行 JSON 序列化（在 `Session.append` 处强制执行），整个格式固定为 `SESSION_FORMAT_VERSION = 0`：这是预发布格式，不暗示任何兼容性（参见[版本立场](subsystems/persistence.zh.md)）。范围仅限本仓库中的包；下游插件可以继续合并其他事件类型，而这些类型按设计不属于本目录。 ## 事件信封 ```ts persistence-catalog /** The appendable event-type keys of {@link SessionEventMap}, plugin-merged extensions included. */ export type SessionEventType = keyof SessionEventMap /** * The subset of {@link SessionEventType} values whose events produce LLM * messages and are eligible to appear on the ordered surface. Only these * event types may carry {@link SurfaceOp} and {@link SessionEvent.sourceEventSeqs}. */ export type SurfaceEventType = | 'user/message' | 'assistant/message' | 'tool/result' /** * How a session event entered the ordered surface. Only valid on * {@link SurfaceEventType} events. * * - `'append'`: added to the tail — normal path for user/assistant/tool * messages. * - `{ op: 'replace', start, end }`: replaces surface nodes from `start` * (inclusive) through `end` (inclusive) with this node. Both must exist as * surface nodes in the current surface. `start === end` replaces a single * node. The node's {@link SessionEvent.sourceEventSeqs} must include every * shadowed surface node. Used by compaction; any surface-replacing producer * may use it. */ export type SurfaceOp = | 'append' | { op: 'replace'; start: SessionSeq; end: SessionSeq } /** * One immutable entry in the session log. * * A proper discriminated union over `type` (not independent `type`/`data` * unions), so `switch (event.type)` narrows `event.data` without casts. * * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional: * they only exist on {@link SurfaceEventType} variants (`user/message`, * `assistant/message`, `tool/result`). * Non-surface events (boundary markers, chunks, usage, errors) never carry * surface metadata — the compiler enforces this at `Session.append()` * call sites. */ export type SessionEvent = { [K in SessionEventType]: { type: K /** Monotonic sequence number within the session. */ seq: SessionSeq /** Unix epoch milliseconds. */ time: number data: SessionEventMap[K] /** * Marks an event a reader may safely skip when it does not recognize * `type`. Absent means required: a reader meeting an unrecognized type * without this marker MUST refuse to reconstruct the session instead of * silently dropping the event, because an unrecognized required event may * change how the rest of the log is interpreted. A writer sets `true` only * on purely informational records whose loss cannot affect reconstruction; * defaulting to required means a forgotten marker over-refuses (an * inconvenience) rather than silently resuming a gutted session. */ ignorable?: true } & (K extends SurfaceEventType ? { /** * Seq numbers of earlier events that this event cites as sources * (e.g. the `assistant/chunk` seqs that built an `assistant/message`, * or the surface nodes shadowed by a compaction replace node). An * `assistant/message` may carry a present empty array for a known empty * provider stream; when the field is absent, the event does not record which * earlier events produced the message. */ sourceEventSeqs?: SessionSeq[] /** How this event entered the surface; absent for non-surface events. */ surfaceOp?: SurfaceOp } : object) }[T] ``` 来源：[`packages/core/session/src/types.ts:366`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:373`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:402`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:434`](../packages/core/session/src/types.ts) ## 事件 ### `agent/*` #### `agent/inbox/spliced` — log-only ```ts persistence-catalog /** * One normalized mutation of an agent's durable pending-message lists. * Live dispatch precedes projection mutation, so synchronous observers may * read the pre-splice inbox to recover the removed messages. */ 'agent/inbox/spliced': { target: InboxTarget start: number removedCount?: number inserted: UserMessage[] outcome?: 'canceled' } ``` 来源：[`packages/core/agent/src/types.ts:58`](../packages/core/agent/src/types.ts) ### `agent-preset/*` #### `agent-preset/selected` — log-only ```ts persistence-catalog /** * The session's agent preset was chosen after creation, while the session * was still blank. Log-only: it records the composition later turns ran * under, so a resumed or forked session rebuilds the same one instead of * the header's creation-time value. */ 'agent-preset/selected': { agentPreset: string } ``` 来源：[`packages/preset/agent-presets/src/session.ts:28`](../packages/preset/agent-presets/src/session.ts) ### `approval/*` #### `approval/asked` — log-only ```ts persistence-catalog /** * An approval question was put to the answerer chain — log-only audit * (like `hook/*`; NOT a surface event, carries no `surfaceOp`). `id` pairs * it with the `approval/decided` that always follows; `toolName` is the * tool the question is about, `callId` the exact tool call when the asker * had one, `reason` the asker's human-readable explanation (e.g. a hook's * permission-decision reason). */ 'approval/asked': { id: ApprovalRequestId toolName: string callId?: ToolCallId reason?: string } ``` 类型：[ToolCallId](subsystems/core.zh.md) 来源：[`packages/interaction/user-approval/src/types.ts:44`](../packages/interaction/user-approval/src/types.ts) #### `approval/decided` — log-only ```ts persistence-catalog /** * The outcome of a prior `approval/asked` (same `id`) — log-only audit. * Exactly one per ask, appended when the outcome is known: a decision, a * cancellation, or the fail-closed `'unavailable'`. */ 'approval/decided': { id: ApprovalRequestId outcome: ApprovalOutcome } ``` 来源：[`packages/interaction/user-approval/src/types.ts:55`](../packages/interaction/user-approval/src/types.ts) #### `approval/policy` — log-only ```ts persistence-catalog /** * The session's approval policy was switched — log-only, durable, * replayable, never in the model transcript (the model learns the policy * from the runtime-context snapshot and live switch notices). The LAST * such event is the session's override. * `source: 'delegation'` marks an override seeded into a child; an absent * source is a runtime switch. */ 'approval/policy': { policy: ApprovalPolicy /** Marks an override seeded into a child at delegation. */ source?: 'delegation' } ``` 来源：[`packages/interaction/user-approval/src/index.ts:32`](../packages/interaction/user-approval/src/index.ts) ### `assistant/*` #### `assistant/chunk` — log-only ```ts persistence-catalog /** Raw stream chunk — token-level replay fidelity. */ 'assistant/chunk': { turn: number; step: number; chunk: StreamChunk } ``` 类型：[StreamChunk](subsystems/llm-streaming.zh.md) 来源：[`packages/core/session/src/types.ts:289`](../packages/core/session/src/types.ts) #### `assistant/message` — surface ```ts persistence-catalog /** * Assembled assistant message for one step (derived history uses this). * Carries the step's `usage` when the adapter reported token accounting, so * the model output and its accounting travel together (there is no separate * usage record). `usage` is absent when the adapter reported none. A turn * cancelled mid-stream finalizes its delivered text/reasoning prefix as this * event with `interrupted: true`; undispatched tool calls are absent. The * marker distinguishes that prefix without re-deriving interruption from turn * boundaries. An aborted turn with no such event streamed no visible content. */ 'assistant/message': { turn: number; step: number; message: AssistantMessage; usage?: TokenUsage; interrupted?: true } ``` 类型：[TokenUsage](subsystems/llm-streaming.zh.md) 来源：[`packages/core/session/src/types.ts:300`](../packages/core/session/src/types.ts) ### `command/*` #### `command/done` — log-only ```ts persistence-catalog /** * The paired command settled. `kind`/`text` carry the handler's verbatim * outcome (a thrown/aborted handler settles as `kind: 'error'` with the * rendered failure). A successful command may identify the earlier * authoritative domain event for a richer client-computed presentation. */ 'command/done': { commandId: CommandId kind: 'success' | 'error' text?: string sourceEventSeq?: import('@deepseek-ai/dsh-session/types').SessionSeq } ``` 来源：[`packages/interaction/commands/src/types.ts:104`](../packages/interaction/commands/src/types.ts) #### `command/run` — log-only ```ts persistence-catalog /** * A resolved slash command entered its handler. Log-only (never model * surface); paired with `command/done` by `commandId`, mirroring the * `tool/call`↔`tool/result` pairing. The payload is structured — `name` * and `args` are `parseCommand`'s own split (name and verbatim rawInput, * separator whitespace included), so a consumer (a projection unit * folding its own command records, a rich command card) never re-parses * a line. `args` is absent when the definition sets `recordInput: false` * because an authoritative domain event owns the input payload. */ 'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource } ``` 来源：[`packages/interaction/commands/src/types.ts:97`](../packages/interaction/commands/src/types.ts) ### `compaction/*` #### `compaction/end` — log-only ```ts persistence-catalog /** * Marks the end of a compaction — log-only, releases the lock. Its owner * matches `compaction/start`; `error` records an unsuccessful attempt. */ 'compaction/end': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; error?: string } ``` 来源：[`packages/compaction/compaction/src/types.ts:72`](../packages/compaction/compaction/src/types.ts) #### `compaction/prune` — log-only ```ts persistence-catalog /** * Shadow price of one model-free prune replacement — log-only, no * surfaceOp. The shared shadow-price protocol: a surface `replace` event * is priced by the metering event immediately before it (`compaction/summary` * for a summarizing compaction, this event for a prune), which states the * heuristic token price of the exact replaced range so a pure consumer * can subtract it without retaining per-node prices. The replacement MUST * be appended synchronously right after this event. */ 'compaction/prune': { /** The replaced range's first and last surface-node seqs (a surface-position span, like {@link CompactionResult.shadowedRange}). */ shadowedRange: { start: SessionSeq; end: SessionSeq } /** The seqs of all shadowed surface nodes, in surface order. */ shadowedSeqs: SessionSeq[] /** Heuristic price of the shadowed content under the token-meter's fixed estimator. */ shadowedTokenCount: number } ``` 来源：[`packages/compaction/compaction/src/types.ts:82`](../packages/compaction/compaction/src/types.ts) #### `compaction/start` — log-only ```ts persistence-catalog /** * Marks the start of a compaction — log-only, holds the lock until * `compaction/end`. A numbered owner is strictly enclosed by that open turn; * `null` identifies a standalone manual transaction between turns. */ 'compaction/start': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null } ``` 来源：[`packages/compaction/compaction/src/types.ts:24`](../packages/compaction/compaction/src/types.ts) #### `compaction/summary` — log-only ```ts persistence-catalog /** * Completed summary, its inputs, and its model call facts — log-only, no surfaceOp. * The summary content is in `data.summary`; the actual surface replacement * is performed by the immediately following `user/message` event that * shadows the compacted range. That adjacency is contractual — the * shadowed pricing fields are the replacement's shadow price, so a * consumer may pair a replacement with the metering event directly * before it (`compaction/prune` documents the shared protocol). */ 'compaction/summary': { compactionId: CompactionId sourceCommandId?: CommandId summary: ContentBlock[] shadowedRange: { start: SessionSeq; end: SessionSeq } shadowedSeqs: SessionSeq[] shadowedTokenCount: number /** The provider route that wrote the summary. */ provider: string /** * The model that wrote the summary — the summarize call's envelope, * reported by the backend that made the call, logged so the one-shot * request is reconstructable from log + code and "which model wrote * this summary" has a durable answer (the reconstructability Agent Note). */ model: string /** The generation cap the summarize call sent, when one applied. */ maxTokens?: number /** Provider-reported token usage for the summarization request, when emitted. */ usage?: TokenUsage } & ( | { /** Complete provider output before the backend's safe summary projection. */ rawOutput: ContentBlock[] /** Identifies exactly one call through this context's `ctx.llm.stream()`. */ llmStreamCall: true } | { /** Optional complete output from an unmarked template, remote, or other summarizer. */ rawOutput?: ContentBlock[] /** An unmarked summary does not identify a call through this context's LLM seam. */ llmStreamCall?: never } ) ``` 类型：[ContentBlock](subsystems/core.zh.md) · [TokenUsage](subsystems/llm-streaming.zh.md) 来源：[`packages/compaction/compaction/src/types.ts:34`](../packages/compaction/compaction/src/types.ts) ### `feedback/*` #### `feedback/record` — log-only ```ts persistence-catalog /** * One recorded human remark about this session. Log-only and independent * of its trigger; it never enters model context or derived history. */ 'feedback/record': { text: string } ``` 来源：[`packages/feedback/command-feedback/src/index.ts:62`](../packages/feedback/command-feedback/src/index.ts) ### `goal/*` #### `goal/change` — log-only ```ts persistence-catalog /** * Complete post-mutation goal state or clear tombstone. */ 'goal/change': GoalChangeMeta ``` 来源：[`packages/goal/goal/src/domain.ts:66`](../packages/goal/goal/src/domain.ts) ### `hook/*` #### `hook/invoked` — log-only ```ts persistence-catalog /** * A hook command was invoked at a hook point — a log-only record (like * `compaction/*`; NOT a {@link SurfaceEventType}, carries no `surfaceOp`). * `dialect` is the bridge that ran it (`claude`/`codex`), `point` * the hook point (`PreToolUse`, `Stop`, …), `matcher` the matcher-group * pattern that selected it (absent for match-all), `handlerId` a stable id * for the command (so an invoked/result pair correlates). `turn` is the open * turn the invocation lives inside. */ 'hook/invoked': { turn: number point: string dialect: HookDialect matcher?: string handlerId: string } ``` 来源：[`packages/hooks/hook-protocol/src/types.ts:19`](../packages/hooks/hook-protocol/src/types.ts) #### `hook/result` — log-only ```ts persistence-catalog /** * Log-only outcome paired to `hook/invoked` by `handlerId`. Decision is the * parsed permission result, `stop` for `continue:false`, or `pass`; exit code * may be absent, stderr is bounded, and duration is wall-clock runtime. */ 'hook/result': { turn: number point: string handlerId: string decision: string exitCode?: number stderrSummary?: string durationMs: number } ``` 来源：[`packages/hooks/hook-protocol/src/types.ts:31`](../packages/hooks/hook-protocol/src/types.ts) ### `llm/*` #### `llm/retry` — log-only ```ts persistence-catalog /** Durable, non-surface record of one provider-routed retry scheduled after a failed request attempt. */ 'llm/retry': LlmRetryEventData ``` 来源：[`packages/llm/llm-retry/src/types.ts:9`](../packages/llm/llm-retry/src/types.ts) #### `llm/retry-started` — log-only ```ts persistence-catalog /** Durable transition written after a retry wait succeeds and before the next request attempt starts. */ 'llm/retry-started': LlmRetryStartedEventData ``` 来源：[`packages/llm/llm-retry/src/types.ts:11`](../packages/llm/llm-retry/src/types.ts) ### `model/*` #### `model/selection` — log-only ```ts persistence-catalog /** * Complete validated model selection requested for subsequent prompt * assembly. Log-only: it never enters derived model history. */ 'model/selection': ModelSelection ``` 来源：[`packages/api/session-controller/src/types.ts:41`](../packages/api/session-controller/src/types.ts) ### `permission/*` #### `permission/preset` — log-only ```ts persistence-catalog /** * Records the selected preset as durable, log-only user intent. The knob * events follow in the same turn and control execution; this event stays * out of the model transcript and lets the permission projection unit * preserve a selection when bundles match. */ 'permission/preset': { preset: string } ``` 来源：[`packages/interaction/permission-presets/src/index.ts:53`](../packages/interaction/permission-presets/src/index.ts) ### `plan/*` #### `plan/mode` — log-only ```ts persistence-catalog /** * Whether plan mode is in force from this point on: log-only, non-surface, * whole-value replace. The last `plan/mode` wins; a log with none folds to * inactive through the projection unit's fold. */ 'plan/mode': { active: boolean } ``` 来源：[`packages/plan/plan-mode/src/index.ts:46`](../packages/plan/plan-mode/src/index.ts) ### `request/*` #### `request/context` — log-only ```ts persistence-catalog /** * Route metadata for the next request, logged only when the route or capacity * changes. It does not participate in request reconstruction or header equality. */ 'request/context': RequestContext ``` 来源：[`packages/core/session/src/types.ts:339`](../packages/core/session/src/types.ts) #### `request/header` — log-only ```ts persistence-catalog /** * Full header for the next request, appended inside its step before dispatch. * It is log-only; the latest snapshot reconstructs the request header. */ 'request/header': { header: EpochHeader reason: RequestHeaderReason /** A changed header also begins a distinct model-message series. */ startsSeries?: true } ``` 来源：[`packages/core/session/src/types.ts:329`](../packages/core/session/src/types.ts) ### `sandbox/*` #### `sandbox/mode` — log-only ```ts persistence-catalog /** * The session's sandbox mode was switched — log-only (like `approval/*`; * NOT a surface event, carries no `surfaceOp`): durable and replayable, * never in the model transcript. The LAST such event is the session's * override (folded by the sandboxMode projection unit). `source: 'delegation'` marks * an override seeded into a child; an absent source is a runtime switch. */ 'sandbox/mode': { mode: SandboxMode /** Marks an override seeded into a child at delegation. */ source?: 'delegation' } ``` 来源：[`packages/sandbox/sandbox-policy/src/session-mode.ts:33`](../packages/sandbox/sandbox-policy/src/session-mode.ts) ### `schedule/*` #### `schedule/change` — log-only ```ts persistence-catalog /** * Versioned Schedule mutation. The owning package validates the complete * session-local transition stream before accepting a candidate event. */ 'schedule/change': ScheduleChange ``` 类型：[ScheduleChange](subsystems/schedule.zh.md) 来源：[`packages/schedule/schedule/src/types.ts:219`](../packages/schedule/schedule/src/types.ts) ### `session/*` #### `session/end-seed` — log-only ```ts persistence-catalog /** * Marks the end of a constructor seed. Events before it have smaller seq * values and came from the seed (resume, fork, or replay); this lifecycle * produced none of them. This log-only event is the durable projection of * {@link Session.firstLiveSeq}. Its payload is empty — position and `time` * carry the meaning. * * Locate the LAST one in stored history. A seed already ending in one is not * re-marked, so reopening an untouched session does not grow its log per * pickup and the event need not be at the current `firstLiveSeq`. * * `Session`'s constructor is the only legitimate writer. The invariant * companion deliberately constrains nothing here, so a plugin appending one * would silently classify every live bracket before it as seed history. * * An owner of a standalone open/close bracket (`compaction/start` … * `compaction/end`) reads it because seed history and live work are otherwise * byte-identical: an unmatched opening marker before this event belongs to * an ended lifecycle, whatever ended it. NOT a liveness signal about other * writers — a concurrently live session holds its own boundary elsewhere, * so tolerating concurrent writers needs a signal beyond the log. */ 'session/end-seed': Record ``` 来源：[`packages/core/session/src/types.ts:362`](../packages/core/session/src/types.ts) #### `session/title` — log-only ```ts persistence-catalog /** * Latest-wins session title snapshot. Log-only: it never enters the model * surface or derived history. */ 'session/title': SessionTitleEventData ``` 类型：[SessionTitleEventData](subsystems/session-title.zh.md) 来源：[`packages/session/session-title/src/index.ts:77`](../packages/session/session-title/src/index.ts) #### `session/title-llm-request` — log-only ```ts persistence-catalog /** Log-only pre-dispatch record of one session-title model request. */ 'session/title-llm-request': SessionTitleLlmRequestEventData ``` 类型：[SessionTitleLlmRequestEventData](subsystems/session-title.zh.md) 来源：[`packages/session/session-title-llm/src/index.ts:45`](../packages/session/session-title-llm/src/index.ts) ### `session-log-deepseek/*` #### `session-log-deepseek/delivery-accepted` — log-only ```ts persistence-catalog /** Records that the configured endpoint accepted one delivery through `throughSeq`. */ 'session-log-deepseek/delivery-accepted': { /** Session identity the accepted delivery carried; inherited fork markers retain the parent's id. */ sessionId: import('@deepseek-ai/dsh-session/types').SessionId /** Last canonical event included in the accepted request. */ throughSeq: import('@deepseek-ai/dsh-session/types').SessionSeq } ``` 来源：[`packages/session/session-log-deepseek/src/types.ts:57`](../packages/session/session-log-deepseek/src/types.ts) ### `step/*` #### `step/end` — log-only ```ts persistence-catalog /** Closes step `step` of turn `turn`. */ 'step/end': { turn: number; step: number } ``` 来源：[`packages/core/session/src/types.ts:279`](../packages/core/session/src/types.ts) #### `step/start` — log-only ```ts persistence-catalog /** Opens step `step` of turn `turn` — one model call plus the tool executions it requested. */ 'step/start': { turn: number; step: number } ``` 来源：[`packages/core/session/src/types.ts:277`](../packages/core/session/src/types.ts) ### `subagent/*` #### `subagent/descriptor` — log-only ```ts persistence-catalog /** * Durable identity and lifecycle mode of a session-backed subagent child, * appended once by the establishing provider inside the child's initial * turn, before its first request. Continuable records also carry their * resumable composition. Log-only: it carries no `surfaceOp`, never enters * model history, and survives compaction. */ 'subagent/descriptor': SubagentDescriptorData ``` 来源：[`packages/subagent/subagent/src/descriptor.ts:38`](../packages/subagent/subagent/src/descriptor.ts) #### `subagent/model-selection-policy` — 仅日志 ```ts persistence-catalog /** * Records that this session's delegation tool exposes child provider, * model, and reasoning-effort selection. Appended before the first model * request; absence means the fixed-route definition. Log-only: it carries * no `surfaceOp` and never enters model history. */ 'subagent/model-selection-policy': { /** Exact routes this Session may select explicitly for a child. */ allowedModels: AllowedModelRoute[] } ``` 来源：[`packages/subagent/tool-subagent/src/model-selection-state.ts:17`](../packages/subagent/tool-subagent/src/model-selection-state.ts) ### `team/*` #### `team/member` — log-only ```ts persistence-catalog /** Whole teammate lifecycle value, stored only in the Team Lead Session. */ 'team/member': { version: 1; teamId: TeamId; member: TeamMemberSnapshot } ``` 类型：[TeamId](subsystems/agent-team.zh.md) · [TeamMemberSnapshot](subsystems/agent-team.zh.md) 来源：[`packages/experimental/agent-team/src/types.ts:206`](../packages/experimental/agent-team/src/types.ts) #### `team/message/delivered` — log-only ```ts persistence-catalog /** Durable acknowledgement that the target Session recorded the message. */ 'team/message/delivered': { version: 1 teamId: TeamId messageId: TeamMessageId targetId: SessionId } ``` 类型：[TeamId](subsystems/agent-team.zh.md) · [TeamMessageId](subsystems/agent-team.zh.md) 来源：[`packages/experimental/agent-team/src/types.ts:212`](../packages/experimental/agent-team/src/types.ts) #### `team/message/queued` — log-only ```ts persistence-catalog /** Durable mailbox enqueue, stored before delivery is attempted. */ 'team/message/queued': { version: 1; teamId: TeamId; message: TeamMessageSnapshot } ``` 类型：[TeamId](subsystems/agent-team.zh.md) · [TeamMessageSnapshot](subsystems/agent-team.zh.md) 来源：[`packages/experimental/agent-team/src/types.ts:210`](../packages/experimental/agent-team/src/types.ts) #### `team/task` — log-only ```ts persistence-catalog /** Whole shared-task value, stored only in the Team Lead Session. */ 'team/task': { version: 1; teamId: TeamId; task: TeamTaskSnapshot } ``` 类型：[TeamId](subsystems/agent-team.zh.md) · [TeamTaskSnapshot](subsystems/agent-team.zh.md) 来源：[`packages/experimental/agent-team/src/types.ts:208`](../packages/experimental/agent-team/src/types.ts) ### `todo/*` #### `todo/write` — log-only ```ts persistence-catalog /** Whole-list snapshot; latest write wins on replay. Log-only UI state; never derived history. */ 'todo/write': { todos: TodoItem[] } ``` 类型：[TodoItem](subsystems/todo.zh.md) 来源：[`packages/todo/tool-todo/src/types.ts:31`](../packages/todo/tool-todo/src/types.ts) ### `tool/*` #### `tool/call` — log-only ```ts persistence-catalog /** * The model requested one tool invocation: `name` with the raw `arguments` * JSON string exactly as the model produced it (unparsed). `callId` pairs the * call with its `tool/result`. */ 'tool/call': { turn: number; step: number; callId: ToolCallId; name: string; arguments: string } ``` 类型：[ToolCallId](subsystems/core.zh.md) 来源：[`packages/core/session/src/types.ts:306`](../packages/core/session/src/types.ts) #### `tool/code-dispatch` — log-only ```ts persistence-catalog /** * One bridged sub-dispatch SETTLING: the pairing ids (matching the * `tool/code-dispatch-start` with the same `subCallId`), the tool `name` * with the same JSON-normalized `arguments`, and the sub-call's complete * model-facing outcome in `tool/result`'s own vocabulary * (`content` + `isError`), so UIs render a sub-call through the exact * code path that renders a native call. Every started sub-call settles * with exactly one of these (abort included: the aborted pipeline result * is an `isError` outcome). * Log-only: `deriveMessages()` ignores it, so sub-calls never re-enter * model context; persistence and UIs get every call. Appended inside the * parent `run_code`'s execution (the bridge drains in-flight dispatches * before returning), so its execution-enclosure relation holds by * construction. */ 'tool/code-dispatch': PtcDispatchEventData ``` 来源：[`packages/core/tools/src/types.ts:56`](../packages/core/tools/src/types.ts) #### `tool/code-dispatch-start` — log-only ```ts persistence-catalog /** * One sub-dispatch STARTING inside a `run_code` program: the parent * `run_code` call id, the deterministic sub-call id (`:code:`, * numbered in submission order), and the tool `name` with its * JSON-normalized `arguments` — the exact value dispatched, normalized * BEFORE dispatch, so this append can never fail on payload shape. * Appended when the scheduler actually starts the call (not at * submission), so a start means the tool body pipeline was entered; a * call abandoned in the queue logs nothing. Log-only: `deriveMessages()` * ignores it; UIs use it for live per-sub-call running state and pair it * with `tool/code-dispatch` by `subCallId` (timing = the two events' * `time` fields). */ 'tool/code-dispatch-start': PtcDispatchStartEventData ``` 来源：[`packages/core/tools/src/types.ts:40`](../packages/core/tools/src/types.ts) #### `tool/result` — surface ```ts persistence-catalog /** * A completed tool call's model-facing result, optional internal failure * identity, and optional tool-private `meta` presentation payload. `meta` is * opaque to the core (the producing tool owns its shape and reads it back in * `presentResult`) but MUST be JSON-serializable: `Session.append` * runtime-validates all event data with `isJsonValue`, so a non-serializable * `meta` is rejected at the source, and the durable log reproduces the * identical card on replay. Absent * unless the tool attaches one (e.g. `dsh-tool-fs` carries its result-time * contextual diff here). */ 'tool/result': { turn: number step: number message: ToolResultMessage error?: { name: string; code: string } meta?: JsonValue } ``` 来源：[`packages/core/session/src/types.ts:318`](../packages/core/session/src/types.ts) ### `tool-workflow/*` #### `tool-workflow/agent-end` — log-only ```ts persistence-catalog /** * Records one member settlement. * @param data - run identity, paired member sequence, and outcome. */ 'tool-workflow/agent-end': ToolWorkflowAgentEndData ``` 来源：[`packages/workflow/tool-workflow/src/types.ts:57`](../packages/workflow/tool-workflow/src/types.ts) #### `tool-workflow/agent-start` — log-only ```ts persistence-catalog /** * Records one published workflow member. * @param data - run identity, member sequence, display identity, and child Session. */ 'tool-workflow/agent-start': ToolWorkflowAgentStartData ``` 来源：[`packages/workflow/tool-workflow/src/types.ts:52`](../packages/workflow/tool-workflow/src/types.ts) #### `tool-workflow/run-end` — log-only ```ts persistence-catalog /** * Closes one workflow record after cleanup. * @param data - stable run identity and terminal reason. */ 'tool-workflow/run-end': ToolWorkflowRunEndData ``` 来源：[`packages/workflow/tool-workflow/src/types.ts:62`](../packages/workflow/tool-workflow/src/types.ts) #### `tool-workflow/run-start` — log-only ```ts persistence-catalog /** * Opens one top-level workflow record. * @param data - stable run identity and display name. */ 'tool-workflow/run-start': ToolWorkflowRunStartData ``` 来源：[`packages/workflow/tool-workflow/src/types.ts:47`](../packages/workflow/tool-workflow/src/types.ts) ### `turn/*` #### `turn/end` — log-only ```ts persistence-catalog /** * Closes turn `turn` with the {@link TurnEndReason} that ended it. A turn * with no entered step has no `step/start` or `step/end`. The loop does not await a * flush at turn boundaries: `dsh-session-checkpoint-policy` owns the * per-request durability checkpoint, and consumers that read storage after * `whenIdle()` flush themselves. Success commits the turn; rejection is * reported live and does not prevent later work. */ 'turn/end': { turn: number; reason: TurnEndReason } ``` 类型：[TurnEndReason](subsystems/session.zh.md) 来源：[`packages/core/session/src/types.ts:275`](../packages/core/session/src/types.ts) #### `turn/start` — log-only ```ts persistence-catalog /** * Opens turn `turn` before the loop claims queued input or runs pre-step. * Rejection, empty input, cancellation, or failure may close it with no * step; otherwise the following identified `user/message` event or batch * records the messages entering the step. */ 'turn/start': { turn: number } ``` 来源：[`packages/core/session/src/types.ts:266`](../packages/core/session/src/types.ts) ### `user/*` #### `user/message` — surface ```ts persistence-catalog /** * A user-role message on the model-visible surface: a direct human prompt * (the queued message claimed for this turn), a synthetic `agent.inject()` * context (file-change notices, subdir AGENTS.md, skill content, cron * notifications, …), or an entered goal continuation round. All three * project their `content` verbatim; `source` tells them apart. */ 'user/message': UserMessage ``` 来源：[`packages/core/session/src/types.ts:287`](../packages/core/session/src/types.ts) ### `web/*` #### `web/deepseek-search-llm-request` — log-only ```ts persistence-catalog /** Secret-free auxiliary DeepSeek search request recorded before dispatch. */ 'web/deepseek-search-llm-request': DeepSeekSearchLlmRequest ``` 来源：[`packages/web/web-search-deepseek/src/provider.ts:83`](../packages/web/web-search-deepseek/src/provider.ts) # Vendored 包改名 [English](rescope.md) | 中文 Cordis 框架及其基础库以源码形式 vendored 在 [`vendor/`](../vendor/README.md) 下，并以 `@deepseek-ai` scope 发布：每个 harness 包都把框架声明为 peer dependency，发布 harness 就会连带发布这一层，用上游名发布等于在 registry 上占用别人的名字。本页是名字映射表；决策与影响见 [改名 Agent Note](../.agents/notes/implemented/process/2026-08-10-vendor-package-rescope.zh.md)，上游 commit 见 [`vendor/README.md`](../vendor/README.md)。 ## 名字映射 | 目录 | 上游名 | 发布名 | 上游版本 | 角色 | |---|---|---|---|---| | `vendor/cordis/` | `cordis` | `@deepseek-ai/cordis` | 4.0.0-rc.7 | 框架核心：`Context`、`Service`、`Fiber`、事件 | | `vendor/cosmokit/` | `cosmokit` | `@deepseek-ai/cosmokit` | 1.8.1 | 框架与 Schemastery 共用的基础工具 | | `vendor/schemastery/` | `schemastery` | `@deepseek-ai/schemastery` | 3.18.0 | 配置 schema（`Schema`），每个插件的 `Config` 都基于它 | | `vendor/loader/` | `@cordisjs/plugin-loader` | `@deepseek-ai/cordis-plugin-loader` | 1.0.0-rc.5 | `cordis.yml` 装载、插件解析、repository 缓存 | | `vendor/include/` | `@cordisjs/plugin-include` | `@deepseek-ai/cordis-plugin-include` | 1.0.4 | 配置包含与 patch 叠加 | | `vendor/group/` | `@cordisjs/plugin-group` | `@deepseek-ai/cordis-plugin-group` | 1.0.0 | 嵌套插件分组 | | `vendor/timer/` | `@cordisjs/plugin-timer` | `@deepseek-ai/cordis-plugin-timer` | 1.1.2 | `ctx` 上随 disposal 回收的定时器 | | `vendor/hmr/` | `@cordisjs/plugin-hmr` | `@deepseek-ai/cordis-plugin-hmr` | 1.0.15 | 插件与配置的热替换 | | `vendor/logger-console/` | `@cordisjs/plugin-logger-console` | `@deepseek-ai/cordis-plugin-logger-console` | 1.0.0 | 控制台日志导出 | 子路径导出保持原路径：`@cordisjs/plugin-loader/repository` 变成 `@deepseek-ai/cordis-plugin-loader/repository`。 ## 改名不碰什么 - **目录名与上游源码版本。** `vendor/hmr/` 仍是 `vendor/hmr/`，清单表记录的是所钉住源码快照的上游版本，因此清单读作一份上游快照；而每个 vendored 包 `package.json` 自身的 `version` 字段是 harness 发布的清单版本，`pnpm run release:vendor` 会提升它，重新 sync 时会恢复成上游版本。 - **依赖 range。** 依赖条目只换键、不换范围：`"cordis": "^4.0.0-rc.7"` 变成 `"@deepseek-ai/cordis": "^4.0.0-rc.7"`；`linkWorkspacePackages` 靠这些保留下来的范围把它们解析到固定的 workspace。 - **Loader 的 `cordis:` 内建前缀。** `cordis:include`、`cordis:group` 是协议前缀，不是包名。 - **`cordis.yml` 配置文件家族**，包括 `*.cordis.yml`、`*.cordis.snapshot.yml`、`cordis.patch.yml`。 - **名字里带这个词的 harness 包**，例如 `@deepseek-ai/dsh-tool-cordis`。 - **上游运行时标识符**，例如 Schemastery 的 `Symbol.for('schemastery')` 及其 `vendor:` 元数据字段。 - **`docs/` 之外的散文。** `vendor/*/README.md`、各包 README 与 Agent Note 保留写作当时的名字；那里的裸 `cordis` 也可能是 Python SDK 的选项名或某个 agent-preset 的 id。`docs/` 之内，散文与所有 Markdown 围栏都跟着改。 ## 你的代码要改什么 | 位置 | 改前 | 改后 | |---|---|---| | 模块 import | `import { Context } from 'cordis'` | `import { Context } from '@deepseek-ai/cordis'` | | 类型事件声明合并 | `declare module 'cordis'` | `declare module '@deepseek-ai/cordis'` | | `package.json` 依赖键 | `"@cordisjs/plugin-hmr": "^1.0.15"` | `"@deepseek-ai/cordis-plugin-hmr": "^1.0.15"` | | `cordis.yml` 插件条目 | `name: '@cordisjs/plugin-include'` | `name: '@deepseek-ai/cordis-plugin-include'` | ## 施加、核验与回退 上面这份映射由 [`scripts/rescope-vendor.ts`](../scripts/rescope-vendor.ts) 承载并执行改名，任何引用都不靠手改： ```sh pnpm run rescope-vendor # report what would change pnpm run rescope-vendor --apply # rewrite every reference pnpm run rescope-vendor:check # assert the post-state; runs in the hygiene gate pnpm run rescope-vendor --apply --reverse # return to the upstream names ``` 上游 sync 之后重跑它（[流程](../vendor/README.md)），并接上它打印的重生成：`pnpm install` 重生成 lockfile、`pnpm run gen-third-party-notices`、以及对它触及的双语对跑 `pnpm run verify-translation-pairing --write`。 # 防御性模式 [English](defensive-patterns.md) | 中文 来之不易的缺陷类别规则：下面每条模式都是本项目实际发布或差点发布的一类缺陷，以防止其复发的规则形式陈述。在编写生命周期、并发、子进程或清理代码之前请先阅读本文。测试层面的对应规则（真实入口路径、验证实际结果、资源归属）见 [testing.md](testing.zh.md)。 ## 正交结果独立上报 一个结果可以同时具有多种性质：进程可能已经超时，却仍以退出码 0 结束，因为它捕获了终止信号。每个独立事实（`timedOut`、`signal`、`exitCode`）都应单独上报；切勿把一个标志的上报嵌套在另一个标志的分支中，否则调用方可能把提前终止的运行误判为正常成功。 ## 公共约定两侧都要遵守 当一个实现收到同一结果的多种表示时，应在通过公共 API 返回前将其规范化。`LlmAdapter.stream()` 的实现可以抛出异常或发出 `finish {kind:'error'|'aborted'}`，但 `LlmRuntime.stream()` 只会通过终止型 finish 分片暴露模型请求失败；middleware 缺陷与消费方缺陷仍会以异常形式抛出。这使消费方不必猜测捕获的异常究竟来自提供方、包装层、分片日志记录还是自身组装逻辑。请在类型定义处记录规范化后的约定；通过真实消费方覆盖每种来源形式。 ## 异步状态不是同步状态 `agent.followup()` 没有逐消息的完成状态或结果；后台任务的完成与轮次边界存在竞争；`reader.close()` 在 EOF 和 dispose（资源释放）两种情况下都会触发。切勿把 `agent/status` 或 `whenIdle()` 当作某次 `followup()` 的结果：多条已排队的后续消息、steering（中途引导）和注入工作可能共用同一个 `running` 区间，而取消或资源释放可能丢弃尚未启动的项。真正拥有一次运行的自动化调用方必须显式定义其区间——例如从消息的持久 inbox 回执到整个 agent（智能体）下一次进入 `idle`——并将选取的任何输出描述为整个区间的输出，而不是把因果关系归于该消息。这条守则是双向的：如果等待的转换永远不会发生，等待就会挂起，因此应显式处理「无需等待」的分支。 ## dispose 必须达到完全停稳，而不仅仅是请求停止 如果清理流程只发出终止或中止信号便返回，而不等待工作真正停止，就会留下孤儿进程。清理逻辑应采用异步流程，并等待子进程退出（发出终止信号后等待 `done`）；还应在终止进程前关闭监听器注册表和通知注册表，使迟到的完成事件保持静默。 ## 在分发器中隔离回调异常 用户提供的监听器如果抛出异常，不得导致它所在的 promise 被 reject，也不得饿死排在它后面的监听器。请用 try/catch 包裹分发循环并记录日志；一个行为不当的订阅者绝不能破坏核心生命周期。 ## 绝不将环境变量或可预测路径暴露给不可信输出 启动的命令应使用经过清理的环境变量，移除名称匹配 `*KEY*`、`*SECRET*`、`*TOKEN*` 或 `*PASSWORD*` 的项，防止 harness 凭证通过命令输出、`env` 或 spill 文件泄漏。临时文件和 spill 文件应放在权限为 0700 的私有目录中，使用随机文件名，并以独占且仅所有者可访问的方式打开（`'wx'`、`0o600`）；可预测且全局可读的路径会引发符号链接竞态和信息泄露。 ## 用 unlink 删除链接形态的路径 可能是符号链接或 Windows junction 的路径，应先用 `lstatSync().isSymbolicLink()` 判断，再用 `unlinkSync` 删除：unlink 只删除链接本身并拒绝真实目录，因此绝不会跟随链接进入其目标。Windows 上对 junction 调用 `rmSync(link)` 会抛 `ERR_FS_EISDIR`；递归删除可能穿过 junction 进入其目标。真实目录才使用带 `recursive` 的 `rmSync`。 # 测试策略 [English](testing.md) | 中文 本文说明本仓库的分层测试方式，以及保持绿色测试套件有意义的规则。命令见根目录 [AGENTS.md](../AGENTS.md)；相关 Agent Note 承载设计动机。 ## 层级 - **单元测试**（`pnpm run test`）：vitest 运行包和示例各自的 `tests/**` 目录下的测试，以及匹配 `scripts/**/*.spec.ts` 的仓库脚本测试；测试文件与其所覆盖的代码区域放在一起。每个注册表都有一个 HMR（热模块替换）安全测试（对向该注册表贡献内容的 fiber 执行 dispose（资源释放），并断言清理完成）。优先覆盖边界情况、错误路径、事件顺序、并发竞态，以及针对约定回归的永久测试（见 `packages/core/agent-loop/tests/contract-regressions.spec.ts`）。 - **覆盖率门禁**（`pnpm run test:coverage`）：门禁级运行，对 `packages/*/*/src` 按文件 100% 覆盖。未覆盖的行往往是门禁正确标记出的死代码（应删除），而非需要补写的测试。行覆盖率是必要条件，但永远不是充分条件：它证明行被执行过，不证明功能按交付预期工作。`packages/shell/pwsh-local/src` 的按文件 100% 覆盖需要真实的 `pwsh`：缺少它时其执行器套件会自动跳过，`vitest.config.ts` 会豁免该文件以使无 pwsh 的主机保持绿色，而 CI runner 自带 pwsh，仍按完整标准执行门禁。 - **真实 API e2e**（`pnpm run test:e2e`）：带密钥测试调用真实提供方 API，包括 DeepSeek 模型以及各提供方特有的冒烟测试；这些测试各自由自己的密钥控制（`EXA_API_KEY`、`PERPLEXITY_API_KEY` 等），缺少密钥时套件会自动跳过，使 keyless CI 保持绿色（[真实 API e2e Agent Note](../.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.zh.md)）。 - **所属位置的预期输出**（`pnpm run test:expected`）：无录制会话往返的无密钥组装 CLI/进程预期。驱动使用 `*.expected.e2e.ts`，并与 `tests/expected/` 同属一处；CI 针对构建产物运行。包/脚本预期使用 `test`，浏览器预期使用 `test:web`。 - **快照**（`pnpm run test:snapshot`）：顶层场景的录制 `session.jsonl` 同时提供用户输入和模型回放，并作为持久化结果的预期值。进程级场景都通过 `dsh` 启动：headless 负责一次性行为，SDK 负责持久控制，ACP 负责自动化协议行为，Web 在同一会话旁保留浏览器与 ARIA 证据。`snapshot.yml` 声明 profile、组合与请求头类别、录制策略、例外回放或输入元数据以及工作区事实。带类型的 token 保留父子身份关系；只有请求头 pin 拥有提示词/schema sidecar。变更工作区的场景会独立比较完整的 `workspace.expected/` 目录，record 与 refresh 绝不改写该目录。当模型 transcript（文本记录）变化时使用 `test:snapshot:record`，回放输入仍有效时使用 `test:snapshot:refresh`；请审查所有结果差异。 - **Web 浏览器快照**（`pnpm run test:web`；必需的 Linux PR（Pull Request）门禁）：Chromium 比较 `snapshots/web/` 下由会话驱动的输出，以及 `apps/web/tests/expected/` 下仅含 UI 的输出。CI 强制只读的 `DSH_SNAPSHOT=replay`，绝不写入预期输出；record/refresh 留在本地，每处 diff 都须评审（[web e2e 车道](../.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md)、[CI 门禁决策](../.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.zh.md)）。`test:web` 会[先构建](../.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md)以交付插件 CSS。 会话 fixture 保留 header 与 payload，但省略正文序号／时间 envelope。回放会合成这些字段；运行时持久化不变。fixture 使用规范打包行；[迁移器](../scripts/migrate-packed-session-fixtures.ts)会改写旧布局。 ## spec 如何被执行 fork 出的 worker 会同时运行多个 spec 文件，coverage gate 会拆成并发的 partition，与同一个 job 中的其它 gate 并排运行，而自托管 runner 共用同一台宿主机和同一个卷。被隔离的只有进程：端口、可预测路径、外部命名空间和继承而来的子进程都不隔离。为每个占用的资源负责到它的 teardown，并把「只有单独运行时才通过」的 spec 读作该 spec 的缺陷，而不是 runner 不稳定。[dsh-ci-test-reliability](../.agents/skills/dsh-ci-test-reliability/SKILL.md) 负责资源分配、状态恢复、同步、超时预算、平台差异与 teardown 规则；它的 [flake 诊断流程](../.agents/skills/dsh-ci-test-reliability/references/ci-flake-diagnosis.md)用于归类已经存在的概率性失败。 ## 带密钥策略：推理（inference）在这里很便宜 我们是 DeepSeek，不要吝惜真实 API 测试。无密钥测试只能证明底层通路；只有带密钥运行才能证明 agent（智能体）能对接真实模型正常工作。覆盖文件写入提示词、包含多个轮次的对话、工具使用和流中取消。价值最高的是**冒烟测试**：启动已交付的 `dsh` profile、发送一条提示词，并检查外部世界；它们能捕获「单元测试全绿、产品却坏了」这一类 mock 无法发现的问题（[事故复盘 0001](postmortem/0001-acp-default-export-drops-inject.zh.md)）。自动跳过让无密钥 CI 和无密钥贡献者不受阻塞；它不是成本信号。Profile 级集成测试位于 `apps/cli/tests/profiles/`；包专属组合留在对应包的测试目录中。 ## 优先使用真实实现而非 mock 只 mock 开销高或不确定的边界（LLM（大语言模型）适配器、网络、时钟）；下游一切保持真实。手写替身只能证明桥接层在搬运字节，不能证明交付的工具行为符合断言。桥接工具调用测试把真实的工具注册表与执行管线保留在脚本化 mock 模型下游：`makeBridgeHarness()`（packages/acp/acp/tests/harness.ts）挂载 agent loop、会话存储、工具注册表与 JSONL 持久化，唯一 mock 是脚本化 `MockAdapter`。 恢复测试按步骤区分分片前与分片后的失败，并证明失败分片不会派生出消息或工具副作用。覆盖耗尽、取消、策略组合、持久化、状态、协议计数、会关闭传输的空闲超时，以及交付的 Loader 组合。 ## 验证外部世界，而非自我报告 e2e 断言应重新运行命令或从外部重新读取文件；对 agent 自身输出做关键词探测会让作弊的 agent 通过。断言未修改的文件逐字节一致。e2e 测试自行管理资源：在测试中创建 harness，在 `afterEach` 中 dispose（即使失败/重试/超时也要释放）；共享 fixture 放在普通的 `tests/harness.ts` 中，绝不放在另一个 `*.e2e.ts` 中（导入一个 spec 会重新注册其 `describe`，导致真实 API 调用重复执行）。 ## 测试真实入口路径 - 产品可见的插件必须有一个非单元的真实组合测试。手动构建的 `ctx.plugin(...)` 套件不够：通过 Loader 和 app/process 启动仅用于测试的 `cordis.yml`，只 mock 外部服务或非确定性输入，断言模型可见的请求/日志、持久状态或用户可见输出。不要把 opt-in 选项混入交付默认值。 - 一个守卫只有在回归能让它失败时才有效。对于没有 `inject` 的插件（bundle/组合插件），Loader 冒烟测试在默认导出替换必需的具名导出时仍然绿着——需要添加显式的 `expect('default' in mod).toBe(false)` 加 `unwrapExports` 往返断言，并证明它有效：引入回归、观察变红、回退。 - 「真实入口路径」指已发布的产物：包的 `bin` 所运行的是构建后的 `lib/bin.js`，并由普通 `node` 执行，从而暴露 tsx 会掩盖的失败（结算竞态、模块解析、被吞掉的加载失败）。同样的规则适用于非 index 运行时入口（worker-thread 的同级文件 `lib/worker.cjs`），也适用于多个 bundle 共享的单例模块（`packages/sdk/server/tests/built-scope-carrier.e2e.ts`）。保持构建产物冒烟测试绿色（`packages/examples/*/tests/built-bin.e2e.ts`、`packages/code-runtime/code-runtime-worker-thread/tests/built-lib.e2e.ts`），并断言真正缺失的配置以非零状态退出。 ## 测试解析：仅限源码 - 每个 vitest 配置都将 vite-tsconfig-paths 指向 `tsconfig.base.json`；工作区包的裸导入解析到 `src`（[布局](development.zh.md#typescript-project-layout)），绝不会经由包的 `exports` 解析到构建后的 `lib/`，因为其中的陈旧产物会加载第二份模块单例。构建产物只在显式指定时使用：以 `lib` 模式运行的子进程，以及下文的构建产物冒烟测试。 ## 测试子进程启动模式 - CI 与已有构建产物的测试通道通过共享双模式启动器，从构建后的 `lib/` 运行每个 profile 或 Cordis 配置子进程。不要为这些子进程手写 `--import tsx`。 - 不加载 Cordis 的协议与操作系统 fixture 直接通过 Node 运行使用可擦除语法的 `.ts` 文件，不经过 tsx 或根路径映射。 - 只有测试对象本身是源码路径解析时，才可以选择 `src`；在测试中写明这一约定。 ## 何时需要快照测试 每项非平凡的模型可见、协议可见或人类可见变更，都在同一 PR 中添加或更新无密钥录制会话场景；包级、e2e、仅 mock 和 PR 理由证据不能取代组装后的 transcript。Headless、SDK、ACP 和 Web 录制分别位于 `snapshots/session/`、`snapshots/sdk/`、`snapshots/acp/` 和 `snapshots/web/`；Web 渲染可以显式借用另一个场景的规范会话。不由录制会话驱动的预期输出保留在所属应用、包或脚本的 `tests/expected/` 下，并且不使用 `*.snapshot.ts` 后缀。[`dsh-session-snapshot`](../packages/test-support/session-snapshot/README.zh.md) 拥有共享存储规则和 profile 适配器。Agent loop、会话生命周期和 `SessionEventMap` 变更应更新两个 SDK 投影：`snapshots/sdk/` 拥有 TypeScript，必需的 Python 运行时 CI 拥有 `scripts/snapshots/python-sdk-single-exe/`。新增 capability seam、生命周期或 transcript 变体应在计划阶段列出每个必需层级。 # Web UI 样式参考 [English](web-styling.md) | 中文 本文规定浏览器客户端包的样式职责归属与组件规则。当前 token 值位于 [`packages/client/ui-theme/src/styles/`](../packages/client/ui-theme/src/styles/)；本文不重复这份由源码生成的清单。 ## 职责归属 [`ui-theme`](../packages/client/ui-theme/README.zh.md) 负责 `--dsw-*` 静态色阶、语义别名、排版、动效、渐变、阴影、滚动条样式以及明暗主题偏好。[`ui-layout`](../packages/client/ui-layout/README.zh.md) 将解析后的主题快照应用到文档。功能包使用语义别名，不得另行定义全局主题。 全局样式表归 `ui-theme/src/styles/` 所有。组件样式以 CSS Modules 形式放在组件旁。当某个值属于该组件的布局或呈现约定时，组件可以定义局部自定义属性；共享颜色、排版、层级和动效属于主题包。 ## 组件规则 - 使用 CSS Modules 和 `clsx`；不得添加组件库或 Tailwind。 - 功能组件使用 `--dsw-alias-*` 语义 token。不得复制静态色板值或在其中写入颜色字面量。 - 功能组件 CSS 不得包含主题选择器。明暗主题覆盖属于主题所有方。 - 字体大小必须与行高配对；已有角色匹配时使用主题排版变量。 - 当组件约定要求保留列结构时，源码文本、终端输出和 diff 行不得换行；使用共享滚动条样式，不得定义组件专用滚动条选择器。 - 呈现规则写在 CSS 中。React 内联样式可以传递组件局部自定义属性值，但不得编码主题分支。 - 添加过渡动画或仅悬停可见的控件时，保留清晰可见的键盘焦点和减少动态效果行为。 - 支持的引擎上，圆角继承 ui-theme `corner-shape.css` 的全局超级椭圆平滑。每个正圆 `border-radius`（`50%`、`100%` 或胶囊半径）必须配对 `corner-shape: round`，使圆形与胶囊保持圆弧；ui-theme 的 corner-shape spec 强制这一配对。 - 高层级表面（菜单、浮层、对话框、面板、悬浮按钮、输入框）设 `border: 0` 并使用 `box-shadow: var(--dsw-elevation-panel)`、`var(--dsw-elevation-prominent)` 或输入框专用的 `var(--dsw-elevation-soft)`（更大模糊、更低透明度）：0.5px 发丝描边是第一层投影，`--dsw-elevation-stroke-color` 可按表面或状态重绑或抑制描边。不得将 `--dsw-alias-border-*` border 与 lv/elevation 投影配对——ui-theme 的 elevation spec 会拒绝；状态色 border（warn 面板）保持真 border。 - 使用中性 `--dsw-alias-border-*` token 的平面边框与分割线一律 `0.5px`——按钮、输入框、卡片、行分割线，以及以填充盒绘制的分隔线（菜单分隔、对话标题栏接缝、markdown `hr`、竖向轨道线）共用发丝线粗细，Chromium 将其绘制为一个设备像素。dashed 记号与状态色 border 保持 1px；spinner 圆环经 spec 的显式豁免保留原宽度。更宽的中性 solid border 会被 ui-theme elevation spec 拒绝。 ## 变更系统 在所属 `ui-theme` 样式表中添加或修改共享 token，然后在功能包中使用其语义别名。公共样式约定发生变化时，更新所属包的参考文档。视觉行为遵循[测试策略](testing.zh.md)；[样式系统 Agent Note](../.agents/notes/implemented/process/2026-07-19-web-styling-system.zh.md) 记录框架依据。 # 术语表 [English](glossary.md) | 中文 DeepSeek Harness 的领域词汇为每个概念规定一个规范术语。各术语通过标准 Markdown 锚点链接到相应条目；实现细节留在各包的 README 与 Agent Note 中。 ## capability-seam - **seam**：一种包含三种角色的*可替换能力*：**Service Definition**（拥有自身 `ctx.` 和词汇类型的 Cordis `Service`——可以是 `ShellExecutor` 这样的抽象类，也可以是 `WebRuntime` 这样的具体注册表，绝不是 TypeScript `interface`）、一个或多个 **Service Provider**，以及一个或多个注入该服务的 **Consumer**。`packages/shell` 是规范范例：`dsh-shell`（Service Definition）、`dsh-bash-local` / `dsh-bash-sandbox`（提供方），以及 `dsh-tool-bash`（Consumer）。角色需要独立演进时通常位于不同包，但属于同一关注点时，一个包也可以承担多个角色（`dsh-user-approval` 在同一个包中承担 approval seam 的 Service Definition 与其具体实现）。seam 是完整能力，绝不是其中一个角色；该术语仅保留此义，能力成员应按其角色、类、服务、约定或扩展点命名。 ## agent-scope - **scope**：按 agent（智能体）划分的注册单位。一项贡献（工具、提示词段、变量、限制、监听器）要么是*全局的*（对所有 agent 可见），要么是*带作用域的*（归属于恰好一个 [scope key](#scope-key)）。只有两层，采用扁平结构：带作用域的注册不会向下继承给 subagent；子树行为通过 [lineage](#lineage) 数据表达，从不通过 scope 结构。 - **scope key**：scope 的不透明标识，按对象同一性比较。harness 约定：一个活跃的 agent 就是其自身 scope 的 key。 - **agent 上下文（`agent.ctx`）**：agent 的带作用域上下文；通过它进行的注册既具有 scope 可见性，其生命周期也绑定到该 scope（同一事实决定两者），其上的监听器参与该 agent 的 scope 过滤分发。注册表主体事件可以根据各自的事件约定有意保持不过滤。 - **scope carrier**：scope 过滤分发所携带的 `thisArg`（由 `scopeTarget` 构建）；其过滤器放行无标签监听器加上主体自身的监听器。*无主体*的 carrier（没有 key）只放行无标签监听器。 - **scoped dispatch**：规则是：关于某个 agent 的活动的事件以该 agent 的 carrier 进行分发。关于注册表本身的事件（如「一个工具被添加了」）属于*注册表主体*事件，保持不过滤。 - **shadowing**：最具体者胜出的名称解析：一个带作用域的工具／片段／变量仅在该 scope 内替换同名的全局对应项。这是按 agent 定制 persona 和按 agent 定制工具变体的机制。 - **restriction / scope-local 注册**：restriction（`tools.restrict`）为单个 scope 过滤全局工具集合（多个 restriction 取交集组合）；scope-local 注册在过滤之后合并。被过滤掉的全局工具既不出现在提示词中，也拒绝执行，与不存在的工具无法区分。 - **setup window**：创建者组装 agent 作用域环境的创建时隙（`CreateAgentOptions.setup`）：此时 scope 和 agent 对象已存在，但 agent 或会话尚未发布，`agent/session-start` 尚未触发，首次提示词尚未组装。setup 只做注册，从不驱动 agent。 - **lineage**：以数据形式携带的父子关系事实（`parentSession`、持久的 `delegationDepth`、运行时 `subagentDepth`）；从不影响可见性。 ## 目标 - **目标**：附着在现有会话上的单个持久完成目标，带有按修订号演进的 `active` / `paused` / `blocked` / `complete` 阶段和 Goal Round 上限；`blocked` 保留策略代码与说明。目标是一种状态，不是调度器，也不是一段独立对话；会话日志仍是其真源。 - **Goal Round**：为当前目标接纳的一次续行周期。同会话驱动器将 Goal Round 具体化为一个由目标触发的[轮次](#turn)，其中可包含零个或多个步骤；同一会话中无关的人类轮次不消耗 Goal Round 上限。 - **目标激活**：续行消费方接纳下一个 Goal Round 的进程本地权限。激活态为 `armed` 或 `disarmed`；它有意不参与持久回放，因此在恢复或 fork 后，只有随后通过 `/goal` 或模型工具执行一次经人类授权的恢复变更，自动工作才能开始。 ## 人类命令 - **人类命令**：以斜杠开头的指令，由面向人类的适配器通过 `ctx.commands` 解释并执行，不会成为模型消息。它既不同于面向模型的工具，也不同于通过 `ctx.shell` 执行 shell 命令。 - **命令平面**：由 UI 适配器和命令插件负责的发现、解析、分发、取消与结果渲染机制。除非处理器另行改变持久领域，否则命令输出属于 UI 状态。 - **目标命令**：`/goal` 是由 `dsh-command-goal` 提供的人类命令；它直接观察或更改当前目标，而目标领域拥有每条持久且模型可见的记录。 ## 循环层级 - **轮次**：会话中一次对已接纳输入的排空过程，在模型及其工具停止工作或终止策略介入后结束。 - **步骤**：一次模型请求，以及由模型响应引发的工具执行；一个轮次包含零个或多个步骤。 - **Round**：承载一个轮次的外层策略迭代，例如一个 [Goal Round](#goal-round) 或一次使用全新 agent 的 Ralph 尝试。Round 计数器归该策略所有，并不统计会话中的每个轮次。 ## Ralph - **Ralph 循环**：一次面向不可变目标的前台全新 agent 工作流运行。它是由工作流和 subagent 原语组合而成的面向模型的工具策略，不是同会话目标、agent loop（智能体循环）模式、调度器或通用工作流脚本功能。 - **Ralph Round**：[Ralph 循环](#ralph-loop)中的一个全新子会话。子会话不接收父会话或此前子会话的对话种子；共享工作区和一份有界的 [Ralph 交接](#ralph-handoff)承载跨 Round 的状态。 - **Ralph 交接**：从一个仍需继续的 Ralph Round 传给下一个 Ralph Round 的规范化、有界结构化报告，包含状态、摘要、证据、后续步骤和阻塞说明。它补充共享工作区，而不取代工作区的权威地位。 # 文档图索引 [English](graph-atlas.md) | 中文 这些图展示生成目录未包含的关系。可以用它们查找包之间的关系、能力 seam、事件流、面向模型的工具、应用组合和运行时生命周期路径。精确签名和类型定义仍以[子系统页面](subsystems/core.zh.md)（类型和生成的 `cordis-surface` 区域）及[工具目录](tool-catalog.zh.md)为准。 本索引背后的流程决策记录在[文档图 Agent Note](../.agents/notes/archived/process/2026-07-03-documentation-graph-atlas.md)中。 | 图 | 模式 | | --- | --- | | [模块依赖图](module-graph.zh.md) | `generated` | | [工具 schema 目录与包映射](tool-catalog.zh.md) | `generated` | | [能力 seam 与核心服务](capability-seams.zh.md) | `hybrid generated` | | [dsh 共享基础组合](../apps/cli/composition.md) | `hybrid generated` | | [事件生产方／消费方矩阵](event-producer-consumer.zh.md) | `hybrid generated` | | [agent（智能体）轮次与步骤生命周期](agent-lifecycle.zh.md) | `curated` | | [工具执行流水线](tool-execution-pipeline.zh.md) | `curated` | 运行 `pnpm run gen-doc-graphs` 可重新生成英文源文件；运行 `pnpm run verify-doc-graphs` 可验证英文源的新鲜度，中文对侧则通过双语配对维护。 英文源文件的维护模式为混合。每个链接页面都会声明其英文源模式为生成、混合或人工编写；本中文文件是通过双语配对维护的经评审对侧。 # 共享实例依赖关系图 [English](module-graph.md) | 中文 `@deepseek-ai/dsh-*` harness 包之间的 peer 依赖关系。peer 表示消费端需要提供共享实例，不包括普通运行时 dependency 或仅开发期关系。该图按 `packages//` 层级分组；边 `a --> b` 表示包 `a` peer 依赖包 `b`。名称中的 `@deepseek-ai/dsh-` 前缀已移除。 ```mermaid flowchart TD subgraph group_util["packages/util"] pkg_atomic_write["atomic-write"] pkg_brand["brand"] pkg_deque["deque"] pkg_home_paths["home-paths"] pkg_launch_environment["launch-environment"] pkg_native_command["native-command"] pkg_output_retention["output-retention"] pkg_timeout["timeout"] pkg_util_crypto["util-crypto"] pkg_util_time["util-time"] pkg_util_values["util-values"] pkg_util_workspace_path["util-workspace-path"] end subgraph group_llm["packages/llm"] pkg_deepseek_llm_api_extensions["deepseek-llm-api-extensions"] pkg_llm["llm"] pkg_llm_deepseek["llm-deepseek"] pkg_llm_pi_ai["llm-pi-ai"] pkg_llm_retry["llm-retry"] pkg_plugin_package_inventory_deepseek["plugin-package-inventory-deepseek"] pkg_token_meter["token-meter"] end subgraph group_core["packages/core"] pkg_agent["agent"] pkg_agent_default_model["agent-default-model"] pkg_agent_loop["agent-loop"] pkg_agent_tool_presentation["agent-tool-presentation"] pkg_scope["scope"] pkg_session["session"] pkg_system_prompt["system-prompt"] pkg_tools["tools"] end subgraph group_goal["packages/goal"] pkg_command_goal["command-goal"] pkg_goal["goal"] pkg_goal_round_driver["goal-round-driver"] pkg_tool_goal["tool-goal"] end subgraph group_fs["packages/fs"] pkg_fs["fs"] pkg_fs_local["fs-local"] pkg_fs_observation_policy["fs-observation-policy"] pkg_fs_sandbox["fs-sandbox"] pkg_tool_fs["tool-fs"] pkg_tool_fs_search["tool-fs-search"] pkg_tool_str_replace_editor["tool-str-replace-editor"] end subgraph group_skill["packages/skill"] pkg_skill["skill"] pkg_skill_badge["skill-badge"] pkg_skill_filesystem["skill-filesystem"] pkg_tool_skill["tool-skill"] end subgraph group_subagent["packages/subagent"] pkg_subagent["subagent"] pkg_subagent_acp["subagent-acp"] pkg_subagent_claude_code["subagent-claude-code"] pkg_subagent_codex["subagent-codex"] pkg_subagent_dsh_sdk["subagent-dsh-sdk"] pkg_subagent_fork_in_process["subagent-fork-in-process"] pkg_subagent_in_process_driver["subagent-in-process-driver"] pkg_subagent_spawn_in_process["subagent-spawn-in-process"] pkg_tool_subagent["tool-subagent"] pkg_tool_subagent_control["tool-subagent-control"] end subgraph group_web["packages/web"] pkg_tool_web["tool-web"] pkg_web["web"] pkg_web_fetch_http["web-fetch-http"] pkg_web_search_deepseek["web-search-deepseek"] pkg_web_search_exa["web-search-exa"] pkg_web_search_perplexity["web-search-perplexity"] end subgraph group_spill["packages/spill"] pkg_spill["spill"] pkg_spill_local["spill-local"] pkg_spill_policy["spill-policy"] end subgraph group_todo["packages/todo"] pkg_tool_todo["tool-todo"] end subgraph group_plan["packages/plan"] pkg_plan_mode["plan-mode"] end subgraph group_hooks["packages/hooks"] pkg_hook_protocol["hook-protocol"] pkg_hooks_claude_code["hooks-claude-code"] pkg_hooks_codex["hooks-codex"] end subgraph group_session_query["packages/session-query"] pkg_session_log_export["session-log-export"] pkg_session_query["session-query"] pkg_session_query_sqlite["session-query-sqlite"] pkg_tool_session_query["tool-session-query"] end subgraph group_acp["packages/acp"] pkg_acp["acp"] end subgraph group_api["packages/api"] pkg_api_gateway["api-gateway"] pkg_api_remotes["api-remotes"] pkg_api_session_controller["api-session-controller"] pkg_api_settings_controller["api-settings-controller"] pkg_api_workspace_controller["api-workspace-controller"] end subgraph group_attachment["packages/attachment"] pkg_attachment["attachment"] pkg_attachment_local["attachment-local"] end subgraph group_boot["packages/boot"] pkg_app_boot["app-boot"] pkg_cmdline["cmdline"] end subgraph group_bundle["packages/bundle"] pkg_acp_app["acp-app"] pkg_base["base"] pkg_headless["headless"] pkg_sdk_app["sdk-app"] pkg_sdk_minimal["sdk-minimal"] pkg_web_app["web-app"] end subgraph group_client["packages/client"] pkg_client_connection["client-connection"] pkg_client_hmr["client-hmr"] pkg_client_locale["client-locale"] pkg_client_modules["client-modules"] pkg_client_store["client-store"] pkg_client_ui_agent_preset["client-ui-agent-preset"] pkg_client_ui_approval["client-ui-approval"] pkg_client_ui_attachment["client-ui-attachment"] pkg_client_ui_brand_official["client-ui-brand-official"] pkg_client_ui_chat["client-ui-chat"] pkg_client_ui_commands["client-ui-commands"] pkg_client_ui_conversation["client-ui-conversation"] pkg_client_ui_deliverables["client-ui-deliverables"] pkg_client_ui_directory_picker_browse["client-ui-directory-picker-browse"] pkg_client_ui_directory_picker_native["client-ui-directory-picker-native"] pkg_client_ui_goal["client-ui-goal"] pkg_client_ui_input_trigger["client-ui-input-trigger"] pkg_client_ui_jobs["client-ui-jobs"] pkg_client_ui_layout["client-ui-layout"] pkg_client_ui_message_feedback["client-ui-message-feedback"] pkg_client_ui_model_selection["client-ui-model-selection"] pkg_client_ui_permission_presets["client-ui-permission-presets"] pkg_client_ui_plan["client-ui-plan"] pkg_client_ui_primitives["client-ui-primitives"] pkg_client_ui_reference["client-ui-reference"] pkg_client_ui_renderer["client-ui-renderer"] pkg_client_ui_schedule["client-ui-schedule"] pkg_client_ui_session["client-ui-session"] pkg_client_ui_settings["client-ui-settings"] pkg_client_ui_settings_general["client-ui-settings-general"] pkg_client_ui_settings_models["client-ui-settings-models"] pkg_client_ui_settings_plugin_inventory["client-ui-settings-plugin-inventory"] pkg_client_ui_settings_plugins["client-ui-settings-plugins"] pkg_client_ui_sidebar["client-ui-sidebar"] pkg_client_ui_skill["client-ui-skill"] pkg_client_ui_slots["client-ui-slots"] pkg_client_ui_subagent["client-ui-subagent"] pkg_client_ui_theme["client-ui-theme"] pkg_client_ui_tool["client-ui-tool"] pkg_client_ui_trajectory["client-ui-trajectory"] pkg_client_ui_user_questions["client-ui-user-questions"] pkg_client_ui_workflow_run["client-ui-workflow-run"] pkg_client_ui_workspace["client-ui-workspace"] pkg_client_web["client-web"] end subgraph group_code_runtime["packages/code-runtime"] pkg_code_runtime["code-runtime"] pkg_code_runtime_worker_thread["code-runtime-worker-thread"] end subgraph group_compaction["packages/compaction"] pkg_command_compact["command-compact"] pkg_compaction["compaction"] pkg_compaction_basic["compaction-basic"] pkg_compaction_tool_result_pruner["compaction-tool-result-pruner"] end subgraph group_context["packages/context"] pkg_agent_instructions["agent-instructions"] pkg_file_reference["file-reference"] pkg_file_reference_local["file-reference-local"] pkg_session_reference["session-reference"] pkg_time_context["time-context"] pkg_tmux_context["tmux-context"] end subgraph group_credentials["packages/credentials"] pkg_authorization["authorization"] pkg_credentials["credentials"] pkg_credentials_local["credentials-local"] end subgraph group_e2b["packages/e2b"] pkg_e2b["e2b"] pkg_fs_e2b["fs-e2b"] pkg_subprocess_e2b["subprocess-e2b"] end subgraph group_experimental["packages/experimental"] pkg_experimental_agent_team["experimental-agent-team"] pkg_experimental_agent_team_profile["experimental-agent-team-profile"] pkg_experimental_agent_team_web_profile["experimental-agent-team-web-profile"] pkg_experimental_client_ui_agent_team["experimental-client-ui-agent-team"] pkg_experimental_code_runtime_python["experimental-code-runtime-python"] pkg_experimental_inspector["experimental-inspector"] pkg_experimental_tool_agent_team["experimental-tool-agent-team"] pkg_experimental_webworker_packer["experimental-webworker-packer"] pkg_experimental_webworker_runtime["experimental-webworker-runtime"] end subgraph group_extensions["packages/extensions"] pkg_client_ui_cordis["client-ui-cordis"] pkg_cordis_client_runner["cordis-client-runner"] pkg_cordis_host_runner["cordis-host-runner"] pkg_tool_cordis["tool-cordis"] end subgraph group_feedback["packages/feedback"] pkg_command_feedback["command-feedback"] pkg_message_feedback["message-feedback"] end subgraph group_guard["packages/guard"] pkg_repeat_tool_reminder["repeat-tool-reminder"] pkg_tool_call_timeout_policy["tool-call-timeout-policy"] end subgraph group_host["packages/host"] pkg_host_directory_picker["host-directory-picker"] pkg_host_directory_picker_auto["host-directory-picker-auto"] pkg_host_directory_picker_browse["host-directory-picker-browse"] pkg_host_directory_picker_native["host-directory-picker-native"] pkg_host_frontend_static["host-frontend-static"] pkg_host_plugin_inventory["host-plugin-inventory"] pkg_host_webserver["host-webserver"] end subgraph group_identity["packages/identity"] pkg_anonymous_user_id["anonymous-user-id"] end subgraph group_interaction["packages/interaction"] pkg_commands["commands"] pkg_permission_presets["permission-presets"] pkg_tool_ask_user["tool-ask-user"] pkg_user_approval["user-approval"] pkg_user_questions["user-questions"] end subgraph group_jobs["packages/jobs"] pkg_jobs["jobs"] pkg_jobs_local["jobs-local"] pkg_tool_jobs["tool-jobs"] end subgraph group_lsp["packages/lsp"] pkg_lsp["lsp"] pkg_lsp_stdio["lsp-stdio"] pkg_tool_lsp["tool-lsp"] end subgraph group_mcp["packages/mcp"] pkg_mcp_client["mcp-client"] end subgraph group_preset["packages/preset"] pkg_agent_presets["agent-presets"] pkg_persona["persona"] end subgraph group_runtime_diagnostics["packages/runtime-diagnostics"] pkg_invariants["invariants"] end subgraph group_sandbox["packages/sandbox"] pkg_sandbox["sandbox"] pkg_sandbox_local["sandbox-local"] pkg_sandbox_policy["sandbox-policy"] pkg_sandbox_windows_acl["sandbox-windows-acl"] end subgraph group_schedule["packages/schedule"] pkg_schedule["schedule"] end subgraph group_sdk["packages/sdk"] pkg_sdk_client["sdk-client"] pkg_sdk_jsonrpc_server["sdk-jsonrpc-server"] pkg_sdk_protocol["sdk-protocol"] end subgraph group_session["packages/session"] pkg_session_checkpoint_policy["session-checkpoint-policy"] pkg_session_log_deepseek["session-log-deepseek"] pkg_session_persistence["session-persistence"] pkg_session_persistence_jsonl["session-persistence-jsonl"] pkg_session_projection["session-projection"] pkg_session_projection_cache["session-projection-cache"] pkg_session_stats["session-stats"] pkg_session_telemetry["session-telemetry"] pkg_session_telemetry_otel["session-telemetry-otel"] pkg_session_title["session-title"] pkg_session_title_all_prompts_llm["session-title-all-prompts-llm"] pkg_session_title_first_prompt_llm["session-title-first-prompt-llm"] pkg_session_title_llm["session-title-llm"] pkg_session_turn_outline["session-turn-outline"] end subgraph group_settings["packages/settings"] pkg_settings["settings"] pkg_settings_file["settings-file"] end subgraph group_shell["packages/shell"] pkg_bash_local["bash-local"] pkg_bash_sandbox["bash-sandbox"] pkg_pwsh_local["pwsh-local"] pkg_pwsh_sandbox["pwsh-sandbox"] pkg_shell["shell"] pkg_shell_env["shell-env"] pkg_tool_bash["tool-bash"] pkg_tool_bash_persistent["tool-bash-persistent"] pkg_tool_pwsh["tool-pwsh"] pkg_tool_pwsh_persistent["tool-pwsh-persistent"] end subgraph group_storage["packages/storage"] pkg_storage["storage"] pkg_storage_domain["storage-domain"] pkg_storage_json["storage-json"] pkg_storage_sqlite["storage-sqlite"] end subgraph group_subprocess["packages/subprocess"] pkg_subprocess["subprocess"] pkg_subprocess_local["subprocess-local"] pkg_win32_process["win32-process"] end subgraph group_terminal["packages/terminal"] pkg_terminal["terminal"] pkg_terminal_bash["terminal-bash"] pkg_tool_terminal["tool-terminal"] end subgraph group_test_support["packages/test-support"] pkg_agent_loop_testkit["agent-loop-testkit"] pkg_client_test_runtime["client-test-runtime"] pkg_llm_mock_server["llm-mock-server"] pkg_llm_replay["llm-replay"] pkg_loader_smoke["loader-smoke"] pkg_session_snapshot["session-snapshot"] end subgraph group_typert["packages/typert"] pkg_typert_generator["typert-generator"] pkg_typert_loader["typert-loader"] pkg_typert_protocol["typert-protocol"] pkg_typert_registry["typert-registry"] end subgraph group_webhook["packages/webhook"] pkg_webhook["webhook"] pkg_webhook_github["webhook-github"] end subgraph group_workflow["packages/workflow"] pkg_tool_ralph["tool-ralph"] pkg_tool_workflow["tool-workflow"] pkg_workflow["workflow"] pkg_workflow_worker_thread["workflow-worker-thread"] end subgraph group_workspace["packages/workspace"] pkg_workspace["workspace"] end pkg_scope --> pkg_invariants pkg_web --> pkg_llm pkg_attachment --> pkg_brand pkg_credentials --> pkg_invariants pkg_subprocess_e2b --> pkg_e2b pkg_subprocess_e2b --> pkg_subprocess pkg_subprocess_e2b --> pkg_timeout pkg_experimental_code_runtime_python --> pkg_code_runtime pkg_experimental_code_runtime_python --> pkg_timeout pkg_experimental_code_runtime_python --> pkg_util_values pkg_experimental_inspector --> pkg_client_modules pkg_experimental_inspector --> pkg_host_webserver pkg_experimental_webworker_runtime --> pkg_client_connection pkg_experimental_webworker_runtime --> pkg_client_modules pkg_experimental_webworker_runtime --> pkg_host_webserver pkg_host_directory_picker_auto --> pkg_client_ui_directory_picker_browse pkg_host_directory_picker_auto --> pkg_client_ui_directory_picker_native pkg_host_directory_picker_auto --> pkg_host_directory_picker_browse pkg_host_directory_picker_auto --> pkg_host_directory_picker_native pkg_host_directory_picker_auto --> pkg_host_webserver pkg_host_frontend_static --> pkg_client_connection pkg_host_frontend_static --> pkg_host_webserver pkg_anonymous_user_id --> pkg_brand pkg_anonymous_user_id --> pkg_home_paths pkg_lsp --> pkg_brand pkg_lsp --> pkg_llm pkg_storage_domain --> pkg_invariants pkg_storage_domain --> pkg_storage pkg_storage_json --> pkg_storage pkg_storage_sqlite --> pkg_storage pkg_subprocess_local --> pkg_subprocess pkg_subprocess_local --> pkg_timeout pkg_typert_loader --> pkg_typert_registry pkg_session --> pkg_scope pkg_system_prompt --> pkg_invariants pkg_system_prompt --> pkg_llm pkg_system_prompt --> pkg_scope pkg_skill --> pkg_llm pkg_skill --> pkg_scope pkg_web_fetch_http --> pkg_timeout pkg_web_fetch_http --> pkg_web pkg_web_search_exa --> pkg_launch_environment pkg_web_search_exa --> pkg_web pkg_web_search_perplexity --> pkg_launch_environment pkg_web_search_perplexity --> pkg_web pkg_api_remotes --> pkg_scope pkg_attachment_local --> pkg_attachment pkg_attachment_local --> pkg_home_paths pkg_authorization --> pkg_credentials pkg_authorization --> pkg_invariants pkg_authorization --> pkg_llm pkg_credentials_local --> pkg_atomic_write pkg_credentials_local --> pkg_credentials pkg_credentials_local --> pkg_home_paths pkg_credentials_local --> pkg_launch_environment pkg_skill_badge --> pkg_skill pkg_spill --> pkg_brand pkg_spill --> pkg_llm pkg_spill --> pkg_session pkg_app_boot --> pkg_home_paths pkg_app_boot --> pkg_launch_environment pkg_app_boot --> pkg_system_prompt pkg_code_runtime_worker_thread --> pkg_code_runtime pkg_code_runtime_worker_thread --> pkg_session pkg_code_runtime_worker_thread --> pkg_timeout pkg_persona --> pkg_system_prompt pkg_sandbox --> pkg_llm pkg_sandbox --> pkg_session pkg_session_log_deepseek --> pkg_deepseek_llm_api_extensions pkg_session_log_deepseek --> pkg_invariants pkg_session_log_deepseek --> pkg_session pkg_session_persistence --> pkg_brand pkg_session_persistence --> pkg_session pkg_session_persistence --> pkg_timeout pkg_session_projection --> pkg_session pkg_settings --> pkg_brand pkg_settings --> pkg_invariants pkg_settings --> pkg_session pkg_session_snapshot --> pkg_session pkg_agent --> pkg_invariants pkg_agent --> pkg_llm pkg_agent --> pkg_scope pkg_agent --> pkg_session pkg_agent --> pkg_session_projection pkg_agent --> pkg_system_prompt pkg_agent --> pkg_typert_protocol pkg_fs --> pkg_brand pkg_fs --> pkg_invariants pkg_fs --> pkg_llm pkg_fs --> pkg_sandbox pkg_spill_local --> pkg_spill pkg_message_feedback --> pkg_brand pkg_message_feedback --> pkg_llm pkg_message_feedback --> pkg_session pkg_message_feedback --> pkg_session_persistence pkg_message_feedback --> pkg_storage_domain pkg_message_feedback --> pkg_typert_protocol pkg_sandbox_local --> pkg_llm pkg_sandbox_local --> pkg_sandbox pkg_sandbox_local --> pkg_session pkg_session_persistence_jsonl --> pkg_session pkg_session_persistence_jsonl --> pkg_session_persistence pkg_session_projection_cache --> pkg_session pkg_session_projection_cache --> pkg_session_projection pkg_session_projection_cache --> pkg_storage_domain pkg_session_stats --> pkg_llm pkg_session_stats --> pkg_session pkg_session_stats --> pkg_session_projection pkg_session_turn_outline --> pkg_llm pkg_session_turn_outline --> pkg_session pkg_session_turn_outline --> pkg_session_projection pkg_settings_file --> pkg_atomic_write pkg_settings_file --> pkg_home_paths pkg_settings_file --> pkg_settings pkg_shell --> pkg_sandbox pkg_shell --> pkg_settings pkg_shell --> pkg_subprocess pkg_workspace --> pkg_invariants pkg_workspace --> pkg_session pkg_workspace --> pkg_session_persistence pkg_workspace --> pkg_storage pkg_workspace --> pkg_storage_domain pkg_workspace --> pkg_typert_protocol pkg_llm_deepseek --> pkg_anonymous_user_id pkg_llm_deepseek --> pkg_atomic_write pkg_llm_deepseek --> pkg_attachment pkg_llm_deepseek --> pkg_credentials pkg_llm_deepseek --> pkg_deepseek_llm_api_extensions pkg_llm_deepseek --> pkg_fs pkg_llm_deepseek --> pkg_home_paths pkg_llm_deepseek --> pkg_launch_environment pkg_llm_deepseek --> pkg_llm pkg_llm_deepseek --> pkg_settings pkg_llm_deepseek --> pkg_timeout pkg_llm_pi_ai --> pkg_attachment pkg_llm_pi_ai --> pkg_authorization pkg_llm_pi_ai --> pkg_credentials pkg_llm_pi_ai --> pkg_fs pkg_llm_pi_ai --> pkg_launch_environment pkg_llm_pi_ai --> pkg_llm pkg_llm_pi_ai --> pkg_settings pkg_llm_pi_ai --> pkg_timeout pkg_llm_retry --> pkg_agent pkg_llm_retry --> pkg_brand pkg_llm_retry --> pkg_invariants pkg_llm_retry --> pkg_llm pkg_llm_retry --> pkg_session pkg_llm_retry --> pkg_session_projection pkg_llm_retry --> pkg_timeout pkg_agent_default_model --> pkg_agent pkg_agent_default_model --> pkg_llm pkg_agent_default_model --> pkg_settings pkg_goal --> pkg_agent pkg_goal --> pkg_brand pkg_goal --> pkg_invariants pkg_goal --> pkg_llm pkg_goal --> pkg_scope pkg_goal --> pkg_session pkg_goal --> pkg_session_projection pkg_goal --> pkg_typert_protocol pkg_fs_local --> pkg_fs pkg_fs_observation_policy --> pkg_fs pkg_skill_filesystem --> pkg_fs pkg_skill_filesystem --> pkg_home_paths pkg_skill_filesystem --> pkg_skill pkg_web_search_deepseek --> pkg_agent pkg_web_search_deepseek --> pkg_credentials pkg_web_search_deepseek --> pkg_launch_environment pkg_web_search_deepseek --> pkg_session pkg_web_search_deepseek --> pkg_settings pkg_web_search_deepseek --> pkg_web pkg_hook_protocol --> pkg_invariants pkg_hook_protocol --> pkg_session pkg_hook_protocol --> pkg_shell pkg_api_workspace_controller --> pkg_api_gateway pkg_api_workspace_controller --> pkg_client_connection pkg_api_workspace_controller --> pkg_host_directory_picker pkg_api_workspace_controller --> pkg_session pkg_api_workspace_controller --> pkg_storage_domain pkg_api_workspace_controller --> pkg_typert_protocol pkg_api_workspace_controller --> pkg_workspace pkg_file_reference --> pkg_agent pkg_time_context --> pkg_agent pkg_time_context --> pkg_invariants pkg_time_context --> pkg_llm pkg_time_context --> pkg_session pkg_time_context --> pkg_session_projection pkg_tmux_context --> pkg_agent pkg_tmux_context --> pkg_session pkg_tmux_context --> pkg_session_projection pkg_tmux_context --> pkg_shell pkg_fs_e2b --> pkg_e2b pkg_fs_e2b --> pkg_fs pkg_commands --> pkg_agent pkg_commands --> pkg_attachment pkg_commands --> pkg_brand pkg_commands --> pkg_invariants pkg_commands --> pkg_llm pkg_commands --> pkg_scope pkg_commands --> pkg_session pkg_commands --> pkg_typert_protocol pkg_user_approval --> pkg_agent pkg_user_approval --> pkg_brand pkg_user_approval --> pkg_invariants pkg_user_approval --> pkg_llm pkg_user_approval --> pkg_scope pkg_user_approval --> pkg_session pkg_user_approval --> pkg_system_prompt pkg_user_questions --> pkg_agent pkg_user_questions --> pkg_llm pkg_user_questions --> pkg_scope pkg_jobs --> pkg_agent pkg_jobs --> pkg_brand pkg_jobs --> pkg_invariants pkg_jobs --> pkg_session pkg_lsp_stdio --> pkg_brand pkg_lsp_stdio --> pkg_fs pkg_lsp_stdio --> pkg_llm pkg_lsp_stdio --> pkg_lsp pkg_lsp_stdio --> pkg_subprocess pkg_lsp_stdio --> pkg_timeout pkg_sandbox_policy --> pkg_agent pkg_sandbox_policy --> pkg_invariants pkg_sandbox_policy --> pkg_sandbox pkg_sandbox_policy --> pkg_session pkg_sandbox_policy --> pkg_session_projection pkg_sandbox_policy --> pkg_system_prompt pkg_session_telemetry --> pkg_agent pkg_session_telemetry --> pkg_session pkg_session_title --> pkg_agent pkg_session_title --> pkg_brand pkg_session_title --> pkg_invariants pkg_session_title --> pkg_llm pkg_session_title --> pkg_session pkg_session_title --> pkg_session_projection pkg_bash_local --> pkg_settings pkg_bash_local --> pkg_shell pkg_bash_local --> pkg_subprocess pkg_bash_local --> pkg_timeout pkg_pwsh_local --> pkg_settings pkg_pwsh_local --> pkg_shell pkg_pwsh_local --> pkg_subprocess pkg_pwsh_local --> pkg_timeout pkg_terminal --> pkg_agent pkg_terminal --> pkg_brand pkg_loader_smoke --> pkg_agent pkg_loader_smoke --> pkg_llm pkg_loader_smoke --> pkg_session pkg_workflow --> pkg_agent pkg_workflow --> pkg_brand pkg_workflow --> pkg_invariants pkg_workflow --> pkg_llm pkg_workflow --> pkg_session pkg_tools --> pkg_agent pkg_tools --> pkg_code_runtime pkg_tools --> pkg_invariants pkg_tools --> pkg_llm pkg_tools --> pkg_scope pkg_tools --> pkg_session pkg_tools --> pkg_system_prompt pkg_tools --> pkg_user_approval pkg_command_goal --> pkg_commands pkg_command_goal --> pkg_goal pkg_command_goal --> pkg_llm pkg_goal_round_driver --> pkg_agent pkg_goal_round_driver --> pkg_goal pkg_goal_round_driver --> pkg_invariants pkg_goal_round_driver --> pkg_llm pkg_goal_round_driver --> pkg_session pkg_fs_sandbox --> pkg_fs pkg_fs_sandbox --> pkg_fs_local pkg_fs_sandbox --> pkg_sandbox pkg_fs_sandbox --> pkg_sandbox_policy pkg_headless --> pkg_agent pkg_headless --> pkg_agent_default_model pkg_headless --> pkg_llm pkg_headless --> pkg_session pkg_compaction --> pkg_brand pkg_compaction --> pkg_commands pkg_compaction --> pkg_invariants pkg_compaction --> pkg_llm pkg_compaction --> pkg_session pkg_command_feedback --> pkg_anonymous_user_id pkg_command_feedback --> pkg_commands pkg_command_feedback --> pkg_session pkg_command_feedback --> pkg_session_telemetry pkg_permission_presets --> pkg_commands pkg_permission_presets --> pkg_invariants pkg_permission_presets --> pkg_sandbox pkg_permission_presets --> pkg_sandbox_policy pkg_permission_presets --> pkg_session pkg_permission_presets --> pkg_session_projection pkg_permission_presets --> pkg_settings pkg_permission_presets --> pkg_shell pkg_permission_presets --> pkg_user_approval pkg_jobs_local --> pkg_agent pkg_jobs_local --> pkg_jobs pkg_jobs_local --> pkg_scope pkg_jobs_local --> pkg_timeout pkg_session_title_llm --> pkg_llm pkg_session_title_llm --> pkg_session pkg_session_title_llm --> pkg_session_title pkg_session_title_llm --> pkg_timeout pkg_bash_sandbox --> pkg_bash_local pkg_bash_sandbox --> pkg_sandbox pkg_bash_sandbox --> pkg_sandbox_policy pkg_bash_sandbox --> pkg_shell pkg_pwsh_sandbox --> pkg_pwsh_local pkg_pwsh_sandbox --> pkg_sandbox pkg_pwsh_sandbox --> pkg_sandbox_policy pkg_pwsh_sandbox --> pkg_shell pkg_terminal_bash --> pkg_agent pkg_terminal_bash --> pkg_sandbox pkg_terminal_bash --> pkg_sandbox_policy pkg_terminal_bash --> pkg_session pkg_terminal_bash --> pkg_session_projection pkg_terminal_bash --> pkg_subprocess pkg_terminal_bash --> pkg_terminal pkg_token_meter --> pkg_compaction pkg_token_meter --> pkg_llm pkg_token_meter --> pkg_llm_retry pkg_token_meter --> pkg_session pkg_token_meter --> pkg_session_projection pkg_agent_loop --> pkg_agent pkg_agent_loop --> pkg_invariants pkg_agent_loop --> pkg_llm pkg_agent_loop --> pkg_scope pkg_agent_loop --> pkg_session pkg_agent_loop --> pkg_session_persistence pkg_agent_loop --> pkg_session_projection pkg_agent_loop --> pkg_settings pkg_agent_loop --> pkg_system_prompt pkg_agent_loop --> pkg_tools pkg_agent_tool_presentation --> pkg_tools pkg_tool_goal --> pkg_agent pkg_tool_goal --> pkg_goal pkg_tool_goal --> pkg_llm pkg_tool_goal --> pkg_session pkg_tool_goal --> pkg_session_projection pkg_tool_goal --> pkg_system_prompt pkg_tool_goal --> pkg_tools pkg_tool_fs --> pkg_attachment pkg_tool_fs --> pkg_fs pkg_tool_fs --> pkg_llm pkg_tool_fs --> pkg_sandbox pkg_tool_fs --> pkg_sandbox_policy pkg_tool_fs --> pkg_session pkg_tool_fs --> pkg_system_prompt pkg_tool_fs --> pkg_tools pkg_tool_fs --> pkg_user_approval pkg_tool_fs_search --> pkg_llm pkg_tool_fs_search --> pkg_output_retention pkg_tool_fs_search --> pkg_session pkg_tool_fs_search --> pkg_spill pkg_tool_fs_search --> pkg_subprocess pkg_tool_fs_search --> pkg_system_prompt pkg_tool_fs_search --> pkg_timeout pkg_tool_fs_search --> pkg_tools pkg_tool_str_replace_editor --> pkg_fs pkg_tool_str_replace_editor --> pkg_sandbox pkg_tool_str_replace_editor --> pkg_sandbox_policy pkg_tool_str_replace_editor --> pkg_tools pkg_tool_skill --> pkg_agent pkg_tool_skill --> pkg_llm pkg_tool_skill --> pkg_skill pkg_tool_skill --> pkg_tools pkg_tool_web --> pkg_llm pkg_tool_web --> pkg_system_prompt pkg_tool_web --> pkg_tools pkg_tool_web --> pkg_web pkg_spill_policy --> pkg_llm pkg_spill_policy --> pkg_output_retention pkg_spill_policy --> pkg_session pkg_spill_policy --> pkg_spill pkg_spill_policy --> pkg_tools pkg_tool_todo --> pkg_agent pkg_tool_todo --> pkg_invariants pkg_tool_todo --> pkg_session pkg_tool_todo --> pkg_session_projection pkg_tool_todo --> pkg_tools pkg_plan_mode --> pkg_agent pkg_plan_mode --> pkg_commands pkg_plan_mode --> pkg_invariants pkg_plan_mode --> pkg_llm pkg_plan_mode --> pkg_session pkg_plan_mode --> pkg_session_projection pkg_plan_mode --> pkg_system_prompt pkg_plan_mode --> pkg_tools pkg_plan_mode --> pkg_user_questions pkg_hooks_codex --> pkg_agent pkg_hooks_codex --> pkg_hook_protocol pkg_hooks_codex --> pkg_llm pkg_hooks_codex --> pkg_session pkg_hooks_codex --> pkg_session_persistence pkg_hooks_codex --> pkg_session_projection pkg_hooks_codex --> pkg_tools pkg_command_compact --> pkg_commands pkg_command_compact --> pkg_compaction pkg_agent_instructions --> pkg_agent pkg_agent_instructions --> pkg_fs pkg_agent_instructions --> pkg_home_paths pkg_agent_instructions --> pkg_llm pkg_agent_instructions --> pkg_session pkg_agent_instructions --> pkg_session_projection pkg_agent_instructions --> pkg_tools pkg_file_reference_local --> pkg_agent pkg_file_reference_local --> pkg_file_reference pkg_file_reference_local --> pkg_system_prompt pkg_file_reference_local --> pkg_tools pkg_cordis_host_runner --> pkg_agent pkg_cordis_host_runner --> pkg_brand pkg_cordis_host_runner --> pkg_llm pkg_cordis_host_runner --> pkg_scope pkg_cordis_host_runner --> pkg_session pkg_cordis_host_runner --> pkg_tools pkg_cordis_host_runner --> pkg_typert_protocol pkg_repeat_tool_reminder --> pkg_agent pkg_repeat_tool_reminder --> pkg_tools pkg_tool_call_timeout_policy --> pkg_llm pkg_tool_call_timeout_policy --> pkg_timeout pkg_tool_call_timeout_policy --> pkg_tools pkg_tool_ask_user --> pkg_agent pkg_tool_ask_user --> pkg_tools pkg_tool_ask_user --> pkg_user_questions pkg_tool_jobs --> pkg_agent pkg_tool_jobs --> pkg_jobs pkg_tool_jobs --> pkg_llm pkg_tool_jobs --> pkg_output_retention pkg_tool_jobs --> pkg_system_prompt pkg_tool_jobs --> pkg_tools pkg_tool_lsp --> pkg_llm pkg_tool_lsp --> pkg_lsp pkg_tool_lsp --> pkg_system_prompt pkg_tool_lsp --> pkg_timeout pkg_tool_lsp --> pkg_tools pkg_mcp_client --> pkg_attachment pkg_mcp_client --> pkg_llm pkg_mcp_client --> pkg_scope pkg_mcp_client --> pkg_subprocess pkg_mcp_client --> pkg_timeout pkg_mcp_client --> pkg_tools pkg_agent_presets --> pkg_agent pkg_agent_presets --> pkg_atomic_write pkg_agent_presets --> pkg_home_paths pkg_agent_presets --> pkg_invariants pkg_agent_presets --> pkg_scope pkg_agent_presets --> pkg_session pkg_agent_presets --> pkg_session_projection pkg_agent_presets --> pkg_settings pkg_agent_presets --> pkg_system_prompt pkg_agent_presets --> pkg_tools pkg_agent_presets --> pkg_typert_protocol pkg_schedule --> pkg_agent pkg_schedule --> pkg_brand pkg_schedule --> pkg_invariants pkg_schedule --> pkg_llm pkg_schedule --> pkg_session pkg_schedule --> pkg_session_persistence pkg_schedule --> pkg_session_projection pkg_schedule --> pkg_tools pkg_session_checkpoint_policy --> pkg_agent pkg_session_checkpoint_policy --> pkg_llm pkg_session_checkpoint_policy --> pkg_session pkg_session_checkpoint_policy --> pkg_session_persistence pkg_session_checkpoint_policy --> pkg_tools pkg_session_telemetry_otel --> pkg_anonymous_user_id pkg_session_telemetry_otel --> pkg_command_feedback pkg_session_telemetry_otel --> pkg_llm pkg_session_telemetry_otel --> pkg_session pkg_session_telemetry_otel --> pkg_session_telemetry pkg_session_title_all_prompts_llm --> pkg_llm pkg_session_title_all_prompts_llm --> pkg_session pkg_session_title_all_prompts_llm --> pkg_session_title pkg_session_title_all_prompts_llm --> pkg_session_title_llm pkg_session_title_first_prompt_llm --> pkg_llm pkg_session_title_first_prompt_llm --> pkg_session pkg_session_title_first_prompt_llm --> pkg_session_title pkg_session_title_first_prompt_llm --> pkg_session_title_llm pkg_shell_env --> pkg_home_paths pkg_shell_env --> pkg_session_persistence pkg_shell_env --> pkg_shell pkg_shell_env --> pkg_tools pkg_tool_bash_persistent --> pkg_agent pkg_tool_bash_persistent --> pkg_terminal pkg_tool_bash_persistent --> pkg_timeout pkg_tool_bash_persistent --> pkg_tools pkg_tool_pwsh_persistent --> pkg_agent pkg_tool_pwsh_persistent --> pkg_terminal pkg_tool_pwsh_persistent --> pkg_timeout pkg_tool_pwsh_persistent --> pkg_tools pkg_tool_terminal --> pkg_agent pkg_tool_terminal --> pkg_jobs pkg_tool_terminal --> pkg_llm pkg_tool_terminal --> pkg_output_retention pkg_tool_terminal --> pkg_system_prompt pkg_tool_terminal --> pkg_terminal pkg_tool_terminal --> pkg_tools pkg_agent_loop_testkit --> pkg_agent pkg_agent_loop_testkit --> pkg_llm pkg_agent_loop_testkit --> pkg_session pkg_agent_loop_testkit --> pkg_system_prompt pkg_agent_loop_testkit --> pkg_tools pkg_llm_replay --> pkg_compaction pkg_llm_replay --> pkg_deepseek_llm_api_extensions pkg_llm_replay --> pkg_llm pkg_llm_replay --> pkg_session pkg_tool_workflow --> pkg_agent pkg_tool_workflow --> pkg_invariants pkg_tool_workflow --> pkg_llm pkg_tool_workflow --> pkg_session pkg_tool_workflow --> pkg_system_prompt pkg_tool_workflow --> pkg_tools pkg_tool_workflow --> pkg_workflow pkg_plugin_package_inventory_deepseek --> pkg_agent pkg_plugin_package_inventory_deepseek --> pkg_agent_presets pkg_plugin_package_inventory_deepseek --> pkg_deepseek_llm_api_extensions pkg_plugin_package_inventory_deepseek --> pkg_session pkg_session_query --> pkg_brand pkg_session_query --> pkg_llm pkg_session_query --> pkg_session pkg_session_query --> pkg_session_persistence pkg_session_query --> pkg_session_projection pkg_session_query --> pkg_session_projection_cache pkg_session_query --> pkg_session_title pkg_session_query --> pkg_tool_todo pkg_acp --> pkg_agent pkg_acp --> pkg_attachment pkg_acp --> pkg_llm pkg_acp --> pkg_mcp_client pkg_acp --> pkg_session pkg_acp --> pkg_session_persistence pkg_acp --> pkg_token_meter pkg_acp --> pkg_user_approval pkg_api_settings_controller --> pkg_agent_presets pkg_api_settings_controller --> pkg_credentials pkg_api_settings_controller --> pkg_native_command pkg_api_settings_controller --> pkg_session pkg_api_settings_controller --> pkg_settings pkg_api_settings_controller --> pkg_typert_protocol pkg_web_app --> pkg_shell_env pkg_web_app --> pkg_system_prompt pkg_compaction_tool_result_pruner --> pkg_compaction pkg_compaction_tool_result_pruner --> pkg_llm pkg_compaction_tool_result_pruner --> pkg_session pkg_compaction_tool_result_pruner --> pkg_token_meter pkg_tool_cordis --> pkg_agent pkg_tool_cordis --> pkg_cordis_host_runner pkg_tool_cordis --> pkg_llm pkg_tool_cordis --> pkg_scope pkg_tool_cordis --> pkg_session pkg_tool_cordis --> pkg_system_prompt pkg_tool_cordis --> pkg_tools pkg_host_plugin_inventory --> pkg_agent_presets pkg_host_plugin_inventory --> pkg_brand pkg_host_plugin_inventory --> pkg_typert_protocol pkg_tool_bash --> pkg_agent pkg_tool_bash --> pkg_jobs pkg_tool_bash --> pkg_llm pkg_tool_bash --> pkg_sandbox pkg_tool_bash --> pkg_sandbox_policy pkg_tool_bash --> pkg_shell pkg_tool_bash --> pkg_shell_env pkg_tool_bash --> pkg_system_prompt pkg_tool_bash --> pkg_tools pkg_tool_bash --> pkg_user_approval pkg_tool_pwsh --> pkg_agent pkg_tool_pwsh --> pkg_jobs pkg_tool_pwsh --> pkg_llm pkg_tool_pwsh --> pkg_sandbox pkg_tool_pwsh --> pkg_sandbox_policy pkg_tool_pwsh --> pkg_shell pkg_tool_pwsh --> pkg_shell_env pkg_tool_pwsh --> pkg_system_prompt pkg_tool_pwsh --> pkg_tools pkg_tool_pwsh --> pkg_user_approval pkg_webhook --> pkg_agent pkg_webhook --> pkg_agent_default_model pkg_webhook --> pkg_agent_presets pkg_webhook --> pkg_invariants pkg_webhook --> pkg_llm pkg_webhook --> pkg_permission_presets pkg_webhook --> pkg_session pkg_webhook --> pkg_session_title pkg_webhook --> pkg_workspace pkg_subagent --> pkg_agent pkg_subagent --> pkg_agent_presets pkg_subagent --> pkg_attachment pkg_subagent --> pkg_invariants pkg_subagent --> pkg_jobs pkg_subagent --> pkg_llm pkg_subagent --> pkg_sandbox pkg_subagent --> pkg_sandbox_policy pkg_subagent --> pkg_scope pkg_subagent --> pkg_session pkg_subagent --> pkg_session_persistence pkg_subagent --> pkg_session_projection pkg_subagent --> pkg_session_projection_cache pkg_subagent --> pkg_session_query pkg_subagent --> pkg_system_prompt pkg_subagent --> pkg_tools pkg_subagent --> pkg_typert_protocol pkg_subagent --> pkg_user_approval pkg_subagent --> pkg_util_time pkg_session_query_sqlite --> pkg_session pkg_session_query_sqlite --> pkg_session_persistence pkg_session_query_sqlite --> pkg_session_query pkg_tool_session_query --> pkg_agent pkg_tool_session_query --> pkg_llm pkg_tool_session_query --> pkg_session pkg_tool_session_query --> pkg_session_projection pkg_tool_session_query --> pkg_session_query pkg_tool_session_query --> pkg_system_prompt pkg_tool_session_query --> pkg_timeout pkg_tool_session_query --> pkg_tools pkg_compaction_basic --> pkg_agent pkg_compaction_basic --> pkg_commands pkg_compaction_basic --> pkg_compaction pkg_compaction_basic --> pkg_compaction_tool_result_pruner pkg_compaction_basic --> pkg_llm pkg_compaction_basic --> pkg_session pkg_compaction_basic --> pkg_token_meter pkg_session_reference --> pkg_agent pkg_session_reference --> pkg_compaction pkg_session_reference --> pkg_llm pkg_session_reference --> pkg_output_retention pkg_session_reference --> pkg_session pkg_session_reference --> pkg_session_projection pkg_session_reference --> pkg_session_projection_cache pkg_session_reference --> pkg_session_query pkg_session_reference --> pkg_session_title pkg_session_reference --> pkg_typert_protocol pkg_webhook_github --> pkg_credentials pkg_webhook_github --> pkg_host_webserver pkg_webhook_github --> pkg_session pkg_webhook_github --> pkg_webhook pkg_subagent_acp --> pkg_agent pkg_subagent_acp --> pkg_llm pkg_subagent_acp --> pkg_session pkg_subagent_acp --> pkg_subagent pkg_subagent_acp --> pkg_subprocess pkg_subagent_acp --> pkg_timeout pkg_subagent_claude_code --> pkg_llm pkg_subagent_claude_code --> pkg_session pkg_subagent_claude_code --> pkg_subagent pkg_subagent_claude_code --> pkg_subprocess pkg_subagent_claude_code --> pkg_timeout pkg_subagent_codex --> pkg_llm pkg_subagent_codex --> pkg_session pkg_subagent_codex --> pkg_subagent pkg_subagent_codex --> pkg_subprocess pkg_subagent_codex --> pkg_timeout pkg_subagent_in_process_driver --> pkg_agent pkg_subagent_in_process_driver --> pkg_llm pkg_subagent_in_process_driver --> pkg_session pkg_subagent_in_process_driver --> pkg_subagent pkg_subagent_in_process_driver --> pkg_system_prompt pkg_subagent_in_process_driver --> pkg_tools pkg_tool_subagent --> pkg_agent pkg_tool_subagent --> pkg_invariants pkg_tool_subagent --> pkg_jobs pkg_tool_subagent --> pkg_llm pkg_tool_subagent --> pkg_scope pkg_tool_subagent --> pkg_session pkg_tool_subagent --> pkg_session_projection pkg_tool_subagent --> pkg_settings pkg_tool_subagent --> pkg_subagent pkg_tool_subagent --> pkg_system_prompt pkg_tool_subagent --> pkg_tools pkg_tool_subagent_control --> pkg_llm pkg_tool_subagent_control --> pkg_session pkg_tool_subagent_control --> pkg_subagent pkg_tool_subagent_control --> pkg_tools pkg_hooks_claude_code --> pkg_agent pkg_hooks_claude_code --> pkg_hook_protocol pkg_hooks_claude_code --> pkg_llm pkg_hooks_claude_code --> pkg_session pkg_hooks_claude_code --> pkg_session_persistence pkg_hooks_claude_code --> pkg_session_projection pkg_hooks_claude_code --> pkg_subagent pkg_hooks_claude_code --> pkg_tools pkg_api_session_controller --> pkg_agent pkg_api_session_controller --> pkg_agent_default_model pkg_api_session_controller --> pkg_agent_presets pkg_api_session_controller --> pkg_api_gateway pkg_api_session_controller --> pkg_attachment pkg_api_session_controller --> pkg_client_connection pkg_api_session_controller --> pkg_file_reference pkg_api_session_controller --> pkg_jobs pkg_api_session_controller --> pkg_llm pkg_api_session_controller --> pkg_native_command pkg_api_session_controller --> pkg_scope pkg_api_session_controller --> pkg_session pkg_api_session_controller --> pkg_session_persistence pkg_api_session_controller --> pkg_session_projection pkg_api_session_controller --> pkg_session_projection_cache pkg_api_session_controller --> pkg_session_query pkg_api_session_controller --> pkg_session_title pkg_api_session_controller --> pkg_skill pkg_api_session_controller --> pkg_subagent pkg_api_session_controller --> pkg_typert_protocol pkg_api_session_controller --> pkg_typert_registry pkg_api_session_controller --> pkg_util_time pkg_api_session_controller --> pkg_util_workspace_path pkg_api_session_controller --> pkg_workspace pkg_experimental_agent_team --> pkg_agent pkg_experimental_agent_team --> pkg_invariants pkg_experimental_agent_team --> pkg_llm pkg_experimental_agent_team --> pkg_session pkg_experimental_agent_team --> pkg_session_persistence pkg_experimental_agent_team --> pkg_session_projection pkg_experimental_agent_team --> pkg_subagent pkg_experimental_agent_team --> pkg_typert_protocol pkg_sdk_protocol --> pkg_llm pkg_sdk_protocol --> pkg_session pkg_sdk_protocol --> pkg_subagent pkg_tool_ralph --> pkg_agent pkg_tool_ralph --> pkg_llm pkg_tool_ralph --> pkg_subagent pkg_tool_ralph --> pkg_system_prompt pkg_tool_ralph --> pkg_tools pkg_tool_ralph --> pkg_workflow pkg_workflow_worker_thread --> pkg_agent pkg_workflow_worker_thread --> pkg_llm pkg_workflow_worker_thread --> pkg_session pkg_workflow_worker_thread --> pkg_subagent pkg_workflow_worker_thread --> pkg_tools pkg_workflow_worker_thread --> pkg_workflow pkg_subagent_fork_in_process --> pkg_agent pkg_subagent_fork_in_process --> pkg_session pkg_subagent_fork_in_process --> pkg_subagent pkg_subagent_fork_in_process --> pkg_subagent_in_process_driver pkg_subagent_spawn_in_process --> pkg_subagent pkg_subagent_spawn_in_process --> pkg_subagent_in_process_driver pkg_experimental_client_ui_agent_team --> pkg_api_remotes pkg_experimental_client_ui_agent_team --> pkg_api_session_controller pkg_experimental_client_ui_agent_team --> pkg_client_locale pkg_experimental_client_ui_agent_team --> pkg_client_ui_conversation pkg_experimental_client_ui_agent_team --> pkg_client_ui_primitives pkg_experimental_client_ui_agent_team --> pkg_client_ui_renderer pkg_experimental_client_ui_agent_team --> pkg_client_ui_session pkg_experimental_client_ui_agent_team --> pkg_client_ui_slots pkg_experimental_client_ui_agent_team --> pkg_experimental_agent_team pkg_experimental_client_ui_agent_team --> pkg_session pkg_experimental_client_ui_agent_team --> pkg_typert_protocol pkg_experimental_tool_agent_team --> pkg_agent pkg_experimental_tool_agent_team --> pkg_experimental_agent_team pkg_experimental_tool_agent_team --> pkg_session pkg_experimental_tool_agent_team --> pkg_system_prompt pkg_experimental_tool_agent_team --> pkg_tools pkg_sdk_client --> pkg_llm pkg_sdk_client --> pkg_sdk_protocol pkg_sdk_client --> pkg_session pkg_sdk_jsonrpc_server --> pkg_agent pkg_sdk_jsonrpc_server --> pkg_attachment pkg_sdk_jsonrpc_server --> pkg_llm pkg_sdk_jsonrpc_server --> pkg_llm_deepseek pkg_sdk_jsonrpc_server --> pkg_scope pkg_sdk_jsonrpc_server --> pkg_sdk_protocol pkg_sdk_jsonrpc_server --> pkg_session pkg_sdk_jsonrpc_server --> pkg_subagent pkg_client_test_runtime --> pkg_api_session_controller pkg_client_test_runtime --> pkg_api_workspace_controller pkg_client_test_runtime --> pkg_attachment pkg_client_test_runtime --> pkg_client_connection pkg_client_test_runtime --> pkg_client_store pkg_client_test_runtime --> pkg_client_ui_chat pkg_client_test_runtime --> pkg_client_ui_conversation pkg_client_test_runtime --> pkg_client_ui_renderer pkg_client_test_runtime --> pkg_client_ui_session pkg_client_test_runtime --> pkg_client_ui_settings pkg_client_test_runtime --> pkg_client_ui_slots pkg_client_test_runtime --> pkg_session pkg_client_test_runtime --> pkg_subagent pkg_client_test_runtime --> pkg_typert_protocol pkg_subagent_dsh_sdk --> pkg_agent pkg_subagent_dsh_sdk --> pkg_llm pkg_subagent_dsh_sdk --> pkg_sdk_client pkg_subagent_dsh_sdk --> pkg_session pkg_subagent_dsh_sdk --> pkg_subagent pkg_subagent_dsh_sdk --> pkg_subprocess ``` | 包 | 分组 | Peer 依赖 | | --- | --- | --- | | [`atomic-write`](../packages/util/atomic-write) | `util` | — | | [`brand`](../packages/util/brand) | `util` | — | | [`deque`](../packages/util/deque) | `util` | — | | [`home-paths`](../packages/util/home-paths) | `util` | — | | [`launch-environment`](../packages/util/launch-environment) | `util` | — | | [`native-command`](../packages/util/native-command) | `util` | — | | [`output-retention`](../packages/util/output-retention) | `util` | — | | [`timeout`](../packages/util/timeout) | `util` | — | | [`util-crypto`](../packages/util/crypto) | `util` | — | | [`util-time`](../packages/util/time) | `util` | — | | [`util-values`](../packages/util/values) | `util` | — | | [`util-workspace-path`](../packages/util/workspace-path) | `util` | — | | [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions) | `llm` | — | | [`llm`](../packages/llm/llm) | `llm` | — | | [`session-log-export`](../packages/session-query/session-log-export) | `session-query` | — | | [`api-gateway`](../packages/api/gateway) | `api` | — | | [`cmdline`](../packages/boot/cmdline) | `boot` | — | | [`acp-app`](../packages/bundle/acp-app) | `bundle` | — | | [`base`](../packages/bundle/base) | `bundle` | — | | [`sdk-app`](../packages/bundle/sdk-app) | `bundle` | — | | [`sdk-minimal`](../packages/bundle/sdk-minimal) | `bundle` | — | | [`client-connection`](../packages/client/connection) | `client` | — | | [`client-hmr`](../packages/client/hmr) | `client` | — | | [`client-locale`](../packages/client/locale) | `client` | — | | [`client-modules`](../packages/client/modules) | `client` | — | | [`client-store`](../packages/client/store) | `client` | — | | [`client-ui-agent-preset`](../packages/client/ui-agent-preset) | `client` | — | | [`client-ui-approval`](../packages/client/ui-approval) | `client` | — | | [`client-ui-attachment`](../packages/client/ui-attachment) | `client` | — | | [`client-ui-brand-official`](../packages/client/ui-brand-official) | `client` | — | | [`client-ui-chat`](../packages/client/ui-chat) | `client` | — | | [`client-ui-commands`](../packages/client/ui-commands) | `client` | — | | [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | — | | [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | — | | [`client-ui-directory-picker-browse`](../packages/client/ui-directory-picker-browse) | `client` | — | | [`client-ui-directory-picker-native`](../packages/client/ui-directory-picker-native) | `client` | — | | [`client-ui-goal`](../packages/client/ui-goal) | `client` | — | | [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | — | | [`client-ui-jobs`](../packages/client/ui-jobs) | `client` | — | | [`client-ui-layout`](../packages/client/ui-layout) | `client` | — | | [`client-ui-message-feedback`](../packages/client/ui-message-feedback) | `client` | — | | [`client-ui-model-selection`](../packages/client/ui-model-selection) | `client` | — | | [`client-ui-permission-presets`](../packages/client/ui-permission-presets) | `client` | — | | [`client-ui-plan`](../packages/client/ui-plan) | `client` | — | | [`client-ui-primitives`](../packages/client/ui-primitives) | `client` | — | | [`client-ui-reference`](../packages/client/ui-reference) | `client` | — | | [`client-ui-renderer`](../packages/client/ui-renderer) | `client` | — | | [`client-ui-schedule`](../packages/client/ui-schedule) | `client` | — | | [`client-ui-session`](../packages/client/ui-session) | `client` | — | | [`client-ui-settings`](../packages/client/ui-settings) | `client` | — | | [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | — | | [`client-ui-settings-models`](../packages/client/ui-settings-models) | `client` | — | | [`client-ui-settings-plugin-inventory`](../packages/client/ui-settings-plugin-inventory) | `client` | — | | [`client-ui-settings-plugins`](../packages/client/ui-settings-plugins) | `client` | — | | [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | — | | [`client-ui-skill`](../packages/client/ui-skill) | `client` | — | | [`client-ui-slots`](../packages/client/ui-slots) | `client` | — | | [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | — | | [`client-ui-theme`](../packages/client/ui-theme) | `client` | — | | [`client-ui-tool`](../packages/client/ui-tool) | `client` | — | | [`client-ui-trajectory`](../packages/client/ui-trajectory) | `client` | — | | [`client-ui-user-questions`](../packages/client/ui-user-questions) | `client` | — | | [`client-ui-workflow-run`](../packages/client/ui-workflow-run) | `client` | — | | [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | — | | [`client-web`](../packages/client/web) | `client` | — | | [`code-runtime`](../packages/code-runtime/code-runtime) | `code-runtime` | — | | [`e2b`](../packages/e2b/e2b) | `e2b` | — | | [`experimental-agent-team-profile`](../packages/experimental/agent-team-profile) | `experimental` | — | | [`experimental-agent-team-web-profile`](../packages/experimental/agent-team-web-profile) | `experimental` | — | | [`experimental-webworker-packer`](../packages/experimental/webworker-packer) | `experimental` | — | | [`client-ui-cordis`](../packages/extensions/ui-cordis) | `extensions` | — | | [`cordis-client-runner`](../packages/extensions/cordis-client-runner) | `extensions` | — | | [`host-directory-picker`](../packages/host/directory-picker) | `host` | — | | [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | `host` | — | | [`host-directory-picker-native`](../packages/host/directory-picker-native) | `host` | — | | [`host-webserver`](../packages/host/webserver) | `host` | — | | [`invariants`](../packages/runtime-diagnostics/invariants) | `runtime-diagnostics` | — | | [`sandbox-windows-acl`](../packages/sandbox/sandbox-windows-acl) | `sandbox` | — | | [`storage`](../packages/storage/storage) | `storage` | — | | [`subprocess`](../packages/subprocess/subprocess) | `subprocess` | — | | [`win32-process`](../packages/subprocess/win32-process) | `subprocess` | — | | [`llm-mock-server`](../packages/test-support/llm-mock-server) | `test-support` | — | | [`typert-generator`](../packages/typert/generator) | `typert` | — | | [`typert-protocol`](../packages/typert/protocol) | `typert` | — | | [`typert-registry`](../packages/typert/registry) | `typert` | — | | [`scope`](../packages/core/scope) | `core` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`web`](../packages/web/web) | `web` | [`llm`](../packages/llm/llm) | | [`attachment`](../packages/attachment/attachment) | `attachment` | [`brand`](../packages/util/brand) | | [`credentials`](../packages/credentials/credentials) | `credentials` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | | [`experimental-code-runtime-python`](../packages/experimental/code-runtime-python) | `experimental` | [`code-runtime`](../packages/code-runtime/code-runtime), [`timeout`](../packages/util/timeout), [`util-values`](../packages/util/values) | | [`experimental-inspector`](../packages/experimental/inspector) | `experimental` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver) | | [`experimental-webworker-runtime`](../packages/experimental/webworker-runtime) | `experimental` | [`client-connection`](../packages/client/connection), [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver) | | [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`client-ui-directory-picker-browse`](../packages/client/ui-directory-picker-browse), [`client-ui-directory-picker-native`](../packages/client/ui-directory-picker-native), [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver) | | [`host-frontend-static`](../packages/host/frontend-static) | `host` | [`client-connection`](../packages/client/connection), [`host-webserver`](../packages/host/webserver) | | [`anonymous-user-id`](../packages/identity/anonymous-user-id) | `identity` | [`brand`](../packages/util/brand), [`home-paths`](../packages/util/home-paths) | | [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm) | | [`storage-domain`](../packages/storage/storage-domain) | `storage` | [`invariants`](../packages/runtime-diagnostics/invariants), [`storage`](../packages/storage/storage) | | [`storage-json`](../packages/storage/storage-json) | `storage` | [`storage`](../packages/storage/storage) | | [`storage-sqlite`](../packages/storage/storage-sqlite) | `storage` | [`storage`](../packages/storage/storage) | | [`subprocess-local`](../packages/subprocess/subprocess-local) | `subprocess` | [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | | [`typert-loader`](../packages/typert/loader) | `typert` | [`typert-registry`](../packages/typert/registry) | | [`session`](../packages/core/session) | `core` | [`scope`](../packages/core/scope) | | [`system-prompt`](../packages/core/system-prompt) | `core` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) | | [`skill`](../packages/skill/skill) | `skill` | [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) | | [`web-fetch-http`](../packages/web/web-fetch-http) | `web` | [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) | | [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`launch-environment`](../packages/util/launch-environment), [`web`](../packages/web/web) | | [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`launch-environment`](../packages/util/launch-environment), [`web`](../packages/web/web) | | [`api-remotes`](../packages/api/remotes) | `api` | [`scope`](../packages/core/scope) | | [`attachment-local`](../packages/attachment/attachment-local) | `attachment` | [`attachment`](../packages/attachment/attachment), [`home-paths`](../packages/util/home-paths) | | [`authorization`](../packages/credentials/authorization) | `credentials` | [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) | | [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`home-paths`](../packages/util/home-paths), [`launch-environment`](../packages/util/launch-environment) | | [`skill-badge`](../packages/skill/skill-badge) | `skill` | [`skill`](../packages/skill/skill) | | [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`app-boot`](../packages/boot/app-boot) | `boot` | [`home-paths`](../packages/util/home-paths), [`launch-environment`](../packages/util/launch-environment), [`system-prompt`](../packages/core/system-prompt) | | [`code-runtime-worker-thread`](../packages/code-runtime/code-runtime-worker-thread) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) | | [`persona`](../packages/preset/persona) | `preset` | [`system-prompt`](../packages/core/system-prompt) | | [`sandbox`](../packages/sandbox/sandbox) | `sandbox` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`session-log-deepseek`](../packages/session/session-log-deepseek) | `session` | [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | | [`session-persistence`](../packages/session/session-persistence) | `session` | [`brand`](../packages/util/brand), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) | | [`session-projection`](../packages/session/session-projection) | `session` | [`session`](../packages/core/session) | | [`settings`](../packages/settings/settings) | `settings` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | | [`session-snapshot`](../packages/test-support/session-snapshot) | `test-support` | [`session`](../packages/core/session) | | [`agent`](../packages/core/agent) | `core` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`typert-protocol`](../packages/typert/protocol) | | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) | | [`spill-local`](../packages/spill/spill-local) | `spill` | [`spill`](../packages/spill/spill) | | [`message-feedback`](../packages/feedback/message-feedback) | `feedback` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol) | | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) | | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl) | `session` | [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) | | [`session-projection-cache`](../packages/session/session-projection-cache) | `session` | [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`storage-domain`](../packages/storage/storage-domain) | | [`session-stats`](../packages/session/session-stats) | `session` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) | | [`session-turn-outline`](../packages/session/session-turn-outline) | `session` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) | | [`settings-file`](../packages/settings/settings-file) | `settings` | [`atomic-write`](../packages/util/atomic-write), [`home-paths`](../packages/util/home-paths), [`settings`](../packages/settings/settings) | | [`shell`](../packages/shell/shell) | `shell` | [`sandbox`](../packages/sandbox/sandbox), [`settings`](../packages/settings/settings), [`subprocess`](../packages/subprocess/subprocess) | | [`workspace`](../packages/workspace/workspace) | `workspace` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`storage`](../packages/storage/storage), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol) | | [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`atomic-write`](../packages/util/atomic-write), [`attachment`](../packages/attachment/attachment), [`credentials`](../packages/credentials/credentials), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`fs`](../packages/fs/fs), [`home-paths`](../packages/util/home-paths), [`launch-environment`](../packages/util/launch-environment), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) | | [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`attachment`](../packages/attachment/attachment), [`authorization`](../packages/credentials/authorization), [`credentials`](../packages/credentials/credentials), [`fs`](../packages/fs/fs), [`launch-environment`](../packages/util/launch-environment), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) | | [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`timeout`](../packages/util/timeout) | | [`agent-default-model`](../packages/core/agent-default-model) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings) | | [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`typert-protocol`](../packages/typert/protocol) | | [`fs-local`](../packages/fs/fs-local) | `fs` | [`fs`](../packages/fs/fs) | | [`fs-observation-policy`](../packages/fs/fs-observation-policy) | `fs` | [`fs`](../packages/fs/fs) | | [`skill-filesystem`](../packages/skill/skill-filesystem) | `skill` | [`fs`](../packages/fs/fs), [`home-paths`](../packages/util/home-paths), [`skill`](../packages/skill/skill) | | [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`launch-environment`](../packages/util/launch-environment), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`web`](../packages/web/web) | | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`shell`](../packages/shell/shell) | | [`api-workspace-controller`](../packages/api/workspace-controller) | `api` | [`api-gateway`](../packages/api/gateway), [`client-connection`](../packages/client/connection), [`host-directory-picker`](../packages/host/directory-picker), [`session`](../packages/core/session), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol), [`workspace`](../packages/workspace/workspace) | | [`file-reference`](../packages/context/file-reference) | `context` | [`agent`](../packages/core/agent) | | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) | | [`tmux-context`](../packages/context/tmux-context) | `context` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`shell`](../packages/shell/shell) | | [`fs-e2b`](../packages/e2b/fs-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`fs`](../packages/fs/fs) | | [`commands`](../packages/interaction/commands) | `interaction` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | | [`user-approval`](../packages/interaction/user-approval) | `interaction` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) | | [`user-questions`](../packages/interaction/user-questions) | `interaction` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) | | [`jobs`](../packages/jobs/jobs) | `jobs` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | | [`lsp-stdio`](../packages/lsp/lsp-stdio) | `lsp` | [`brand`](../packages/util/brand), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt) | | [`session-telemetry`](../packages/session/session-telemetry) | `session` | [`agent`](../packages/core/agent), [`session`](../packages/core/session) | | [`session-title`](../packages/session/session-title) | `session` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) | | [`bash-local`](../packages/shell/bash-local) | `shell` | [`settings`](../packages/settings/settings), [`shell`](../packages/shell/shell), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | | [`pwsh-local`](../packages/shell/pwsh-local) | `shell` | [`settings`](../packages/settings/settings), [`shell`](../packages/shell/shell), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | | [`terminal`](../packages/terminal/terminal) | `terminal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand) | | [`loader-smoke`](../packages/test-support/loader-smoke) | `test-support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`workflow`](../packages/workflow/workflow) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/interaction/user-approval) | | [`command-goal`](../packages/goal/command-goal) | `goal` | [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`llm`](../packages/llm/llm) | | [`goal-round-driver`](../packages/goal/goal-round-driver) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) | | [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`compaction`](../packages/compaction/compaction) | `compaction` | [`brand`](../packages/util/brand), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`commands`](../packages/interaction/commands), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) | | [`permission-presets`](../packages/interaction/permission-presets) | `interaction` | [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`shell`](../packages/shell/shell), [`user-approval`](../packages/interaction/user-approval) | | [`jobs-local`](../packages/jobs/jobs-local) | `jobs` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`scope`](../packages/core/scope), [`timeout`](../packages/util/timeout) | | [`session-title-llm`](../packages/session/session-title-llm) | `session` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`timeout`](../packages/util/timeout) | | [`bash-sandbox`](../packages/shell/bash-sandbox) | `shell` | [`bash-local`](../packages/shell/bash-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell) | | [`pwsh-sandbox`](../packages/shell/pwsh-sandbox) | `shell` | [`pwsh-local`](../packages/shell/pwsh-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell) | | [`terminal-bash`](../packages/terminal/terminal-bash) | `terminal` | [`agent`](../packages/core/agent), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subprocess`](../packages/subprocess/subprocess), [`terminal`](../packages/terminal/terminal) | | [`token-meter`](../packages/llm/token-meter) | `llm` | [`compaction`](../packages/compaction/compaction), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) | | [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`agent-tool-presentation`](../packages/core/agent-tool-presentation) | `core` | [`tools`](../packages/core/tools) | | [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`attachment`](../packages/attachment/attachment), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | | [`tool-fs-search`](../packages/fs/tool-fs-search) | `fs` | [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) | | [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) | `fs` | [`fs`](../packages/fs/fs), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`tools`](../packages/core/tools) | | [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) | | [`tool-web`](../packages/web/tool-web) | `web` | [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) | | [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) | | [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) | | [`plan-mode`](../packages/plan/plan-mode) | `plan` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-questions`](../packages/interaction/user-questions) | | [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) | | [`command-compact`](../packages/compaction/command-compact) | `compaction` | [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction) | | [`agent-instructions`](../packages/context/agent-instructions) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`home-paths`](../packages/util/home-paths), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) | | [`file-reference-local`](../packages/context/file-reference-local) | `context` | [`agent`](../packages/core/agent), [`file-reference`](../packages/context/file-reference), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) | `extensions` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol) | | [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder) | `guard` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools) | | [`tool-call-timeout-policy`](../packages/guard/timeout-policy) | `guard` | [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) | | [`tool-ask-user`](../packages/interaction/tool-ask-user) | `interaction` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools), [`user-questions`](../packages/interaction/user-questions) | | [`tool-jobs`](../packages/jobs/tool-jobs) | `jobs` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`tool-lsp`](../packages/lsp/tool-lsp) | `lsp` | [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) | | [`mcp-client`](../packages/mcp/mcp-client) | `mcp` | [`attachment`](../packages/attachment/attachment), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) | | [`agent-presets`](../packages/preset/agent-presets) | `preset` | [`agent`](../packages/core/agent), [`atomic-write`](../packages/util/atomic-write), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol) | | [`schedule`](../packages/schedule/schedule) | `schedule` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) | | [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy) | `session` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) | | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | `session` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`command-feedback`](../packages/feedback/command-feedback), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) | | [`session-title-all-prompts-llm`](../packages/session/session-title-all-prompts-llm) | `session` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) | | [`session-title-first-prompt-llm`](../packages/session/session-title-first-prompt-llm) | `session` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) | | [`shell-env`](../packages/shell/shell-env) | `shell` | [`home-paths`](../packages/util/home-paths), [`session-persistence`](../packages/session/session-persistence), [`shell`](../packages/shell/shell), [`tools`](../packages/core/tools) | | [`tool-bash-persistent`](../packages/shell/tool-bash-persistent) | `shell` | [`agent`](../packages/core/agent), [`terminal`](../packages/terminal/terminal), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) | | [`tool-pwsh-persistent`](../packages/shell/tool-pwsh-persistent) | `shell` | [`agent`](../packages/core/agent), [`terminal`](../packages/terminal/terminal), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) | | [`tool-terminal`](../packages/terminal/tool-terminal) | `terminal` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`system-prompt`](../packages/core/system-prompt), [`terminal`](../packages/terminal/terminal), [`tools`](../packages/core/tools) | | [`agent-loop-testkit`](../packages/test-support/agent-loop-testkit) | `test-support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`llm-replay`](../packages/test-support/llm-replay) | `test-support` | [`compaction`](../packages/compaction/compaction), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | | [`plugin-package-inventory-deepseek`](../packages/llm/plugin-package-inventory-deepseek) | `llm` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`session`](../packages/core/session) | | [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-title`](../packages/session/session-title), [`tool-todo`](../packages/todo/tool-todo) | | [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`llm`](../packages/llm/llm), [`mcp-client`](../packages/mcp/mcp-client), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`token-meter`](../packages/llm/token-meter), [`user-approval`](../packages/interaction/user-approval) | | [`api-settings-controller`](../packages/api/settings-controller) | `api` | [`agent-presets`](../packages/preset/agent-presets), [`credentials`](../packages/credentials/credentials), [`native-command`](../packages/util/native-command), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`typert-protocol`](../packages/typert/protocol) | | [`web-app`](../packages/bundle/web-app) | `bundle` | [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt) | | [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner) | `compaction` | [`compaction`](../packages/compaction/compaction), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) | | [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`host-plugin-inventory`](../packages/host/plugin-inventory) | `host` | [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`typert-protocol`](../packages/typert/protocol) | | [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | | [`tool-pwsh`](../packages/shell/tool-pwsh) | `shell` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | | [`webhook`](../packages/webhook/webhook) | `webhook` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`workspace`](../packages/workspace/workspace) | | [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`attachment`](../packages/attachment/attachment), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-approval`](../packages/interaction/user-approval), [`util-time`](../packages/util/time) | | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) | | [`tool-session-query`](../packages/session-query/tool-session-query) | `session-query` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) | | [`compaction-basic`](../packages/compaction/compaction-basic) | `compaction` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) | | [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compaction`](../packages/compaction/compaction), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`typert-protocol`](../packages/typert/protocol) | | [`webhook-github`](../packages/webhook/webhook-github) | `webhook` | [`credentials`](../packages/credentials/credentials), [`host-webserver`](../packages/host/webserver), [`session`](../packages/core/session), [`webhook`](../packages/webhook/webhook) | | [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | | [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | `subagent` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | | [`subagent-codex`](../packages/subagent/subagent-codex) | `subagent` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | | [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | | [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | | [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`file-reference`](../packages/context/file-reference), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) | | [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) | | [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) | | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | | [`workflow-worker-thread`](../packages/workflow/workflow-worker-thread) | `workflow` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | | [`subagent-fork-in-process`](../packages/subagent/subagent-fork-in-process) | `subagent` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver) | | [`subagent-spawn-in-process`](../packages/subagent/subagent-spawn-in-process) | `subagent` | [`subagent`](../packages/subagent/subagent), [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver) | | [`experimental-client-ui-agent-team`](../packages/experimental/client-ui-agent-team) | `experimental` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-slots`](../packages/client/ui-slots), [`experimental-agent-team`](../packages/experimental/agent-team), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | | [`experimental-tool-agent-team`](../packages/experimental/tool-agent-team) | `experimental` | [`agent`](../packages/core/agent), [`experimental-agent-team`](../packages/experimental/agent-team), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`sdk-client`](../packages/sdk/client) | `sdk` | [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session) | | [`sdk-jsonrpc-server`](../packages/sdk/server) | `sdk` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) | | [`client-test-runtime`](../packages/test-support/client-runtime) | `test-support` | [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-store`](../packages/client/store), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) | | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) | # 工具 Schema 目录 [English](tool-catalog.md) | 中文 已发布插件向 `ctx.tools` 提供的所有面向模型的工具：模型通过系统提示词组装获得的 `name`、`description` 和 JSON Schema `parameters`。本目录是[子系统页面](subsystems/core.zh.md)（类型及每页生成的 `cordis-surface` 接线区域）的补充；本页列出的是向 agent（智能体）提供的*工具*。 英文源文件由系统**生成**，并通过 `pnpm run verify-tool-catalog`（`doc-sync`（文档同步门禁）的一部分）验证新鲜度；本中文文件作为经评审对侧通过双语配对维护。与 Cordis 目录（纯源码 AST 处理）不同，英文生成器会在真实上下文中**启动**每个工具插件并读取 `ctx.tools.schemas()`，因为工具 schema 无法通过静态分析完全确定，例如运行时展开的枚举、拼接的描述、由配置决定的名称以及使用原始 JSON Schema 的 MCP 工具。完整性守卫会 glob 匹配 `packages/*/tool-*`；如果生成器的启动 manifest（元数据清单）遗漏任何包，检查就会失败，因此新工具不会在无人察觉的情况下缺少文档。参见[工具 schema 目录 Agent Note](../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.zh.md)。 范围：`packages/*/tool-*` 下已发布的产品工具，每个工具均使用其**默认**配置启动；但如果某个 Config 字段是**必填项**且没有默认值，生成器就必须作出选择，对应包的说明会记录本页展示的是哪个分支。注册的工具**名称**可以是加载时配置，例如 `tool-subagent` 的 `toolName`，因此部署可能以不同名称或额外名称提供某个包；如果存在随产品发布的别名，对应包的说明会予以记录。`examples/` 中的演示工具（例如 `echo`）不在范围内，这与 Cordis 目录仅涵盖包的范围一致。 ## 工具包映射 下表将模型可见的工具名称与其背后的插件包和服务 seam 对应起来。各包章节随后给出确切的 JSON Schema。 | 工具包 | 模型可见名称 | 依赖 | 写入／影响 | 随产品发布的别名 | 部署说明 | | --- | --- | --- | --- | --- | --- | | `@deepseek-ai/dsh-tool-ask-user` | `ask_user_question` | `ctx.tools`、`ctx.userQuestions` | `tool/call`、`tool/result after a UI/provider answers the question` | - | ask_user_question 会暂停工具调用，直到当前 UI 提供方返回人类答案。 | | `@deepseek-ai/dsh-tools` | `run_code` | `ctx.tools`、`ctx.codeRuntime (execution time)`、`ctx.systemPrompt` | `tool/call`、`one tool/code-dispatch-start + tool/code-dispatch pair per bridged sub-call`、`tool/result` | - | 在 `mode: ptc`／`mode: both` 下，它由工具注册表所有，作为可过滤能力层之外的保留传输机制（参见 PTC mode Agent Note）。在 `ptc` 下，它是注册表对协议格式（wire format）的唯一贡献；其他可见能力在使用已加载运行时语言生成的 SDK 章节中声明。程序通过 binding 调用这些能力，调用按照原生并发约定调度：启动顺序和策略遵循提交顺序，并发安全的函数体最多重叠执行 `maxParallelSubCalls` 个。调用会重新进入完整且受守卫保护的工具流水线，并将每个嵌套执行关联到此外层结果。 | | `@deepseek-ai/dsh-plan-mode` | `exit_plan_mode` | `ctx.tools`、`ctx.systemPrompt`、`ctx.userQuestions (execution time, opportunistic)` | `tool/call`、`plan/mode inactive on an approved review`、`tool/result` | - | 规划未激活时，exit_plan_mode 仍保留在面向模型的 schema 中，这样状态转换不会在规划策略变更之外额外造成工具目录变动。其执行路径会拒绝规划模式之外的调用；在规划模式下，它通过用户交互 seam 提交计划（批准／根据反馈继续规划），批准后会在步骤边界记录规划模式已停用。 | | `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`、`ctx.shell`、`ctx.systemPrompt`、`ctx.shellEnv`、`ctx.jobs at call time for run_in_background` | `tool/call`、`tool/result` | - | bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_background` 的运行会注册到通用 `ctx.jobs` 运行时，并通过 `job_*` 工具（来自 `@deepseek-ai/dsh-tool-jobs`）收集／停止；禁用 `enableRunInBackground` 配置（默认为 true）后，该参数会被完全移除。 | | `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`、`ctx.shell`、`ctx.systemPrompt`、`ctx.shellEnv`、`ctx.jobs at call time for run_in_background` | `tool/call`、`tool/result` | - | pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.shell` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.jobs` 运行时，并通过 `job_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-shell-env`。每次调用都在新进程中运行，不使用持久 PTY 会话。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。 | | `@deepseek-ai/dsh-tool-cordis` | `cordis_define`、`cordis_inspect_list`、`cordis_inspect_query`、`cordis_inspect_self`、`cordis_run`、`cordis_stop`、`cordis_undefine` | `ctx.tools`、`ctx.dynamicCordisRunner` | `tool/call`、`tool/result`、`process-local dynamic package lifecycle` | - | 不在任何随产品发布的树中，需要显式选择启用；动态 Package 代码可以访问真实运行时，见 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md。该工具集注入 `@deepseek-ai/dsh-cordis-host-runner` 提供的 `ctx.dynamicCordisRunner`，后者拥有定义注册表和 vm 沙箱；组合缺少它时这些工具不会激活。运行中的 Package 在停止、undefine 或 DSH 重启前可以注册**额外的**模型可见工具；发生这类工具集变化时，系统会记录完整且有变动的请求头。 | | `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`、`ctx.terminals`、`an owning Agent at execution time` | `tool/call`、`PTY shell state`、`tool/result` | - | 一个按所有者隔离的持久 bash 工具；部署组合提供 PTY 后端，并可覆盖面向模型的环境描述。 | | `@deepseek-ai/dsh-tool-pwsh-persistent` | `pwsh` | `ctx.tools`、`ctx.terminals`、`an owning Agent at execution time` | `tool/call`、`PTY shell state`、`tool/result` | - | 一个按所有者隔离的持久 pwsh 工具，持久 bash 工具的 Windows 对应物；部署组合提供 pwsh 方言的 PTY 后端，并可覆盖面向模型的环境描述。 | | `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`、`ctx.fs` | `tool/call`、`fs/observed after view presence/absence, edit absence, or successful mutation`、`tool/result` | - | 基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。 | | `@deepseek-ai/dsh-tool-fs` | `edit`、`read`、`read_image`、`write` | `ctx.tools`、`ctx.fs`、`ctx.systemPrompt`、`ctx.attachments (image-tool registration)`、`ctx.llm + an image-capable route (image-tool execution)` | `tool/call`、`fs/write-intent or fs/edit-intent for mutations`、`fs/observed after read presence/absence or successful file operation`、`durable attachment (read_image)`、`tool/result` | - | 先读后写／编辑策略由 `@deepseek-ai/dsh-fs-observation-policy` 添加；它是一个 `fs/*` 事件门禁插件，不会改变 schema。加载这些工具的部署按预期也应加载该插件。没有 `ctx.attachments` 时图片工具不会注册；其 schema 与路由无关，执行时除非确切路由的模型声明图片输入，否则拒绝。 | | `@deepseek-ai/dsh-tool-fs-search` | `glob`、`grep` | `ctx.tools`、`ctx.subprocess`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | glob 和 grep 是无条件可用的发现工具，通过 ctx.subprocess spawn 随包提供的 ripgrep 二进制文件（`@vscode/ripgrep`），并作为普通前台调用运行，绝不作为后台任务；无需在宿主机安装 `rg`，也不经过 shell 层。本目录使用 `sampleOverCapGlobResults: true`；部署必须显式选择该行为。结果超过上限时，会通过可选的 ctx.spillStore 后端保存完整的格式化列表；在共置部署中，如果后端公开本地路径，返回的定位信息可供后续读取／搜索。 | | `@deepseek-ai/dsh-tool-terminal` | `terminal_close`、`terminal_list`、`terminal_open`、`terminal_read`、`terminal_send`、`terminal_signal` | `ctx.tools`、`ctx.terminals`、`ctx.systemPrompt`、`ctx.jobs at call time for run_in_background` | `tool/call`、`tool/result` | - | 这 6 个终端工具需要选择启用，用于补充一次性 bash／文件系统工具。`terminal_send(run_in_background: true)` 会注册到 `ctx.jobs`；schema 不包含 TUI、具名按键序列、BEL、调整尺寸、自动启动和跨 agent 共享。 | | `@deepseek-ai/dsh-tool-goal` | `create_goal`、`get_goal`、`update_goal` | `ctx.tools`、`ctx.agents`、`ctx.goals`、`ctx.systemPrompt`、`a calling Agent in an authorized open turn` | `tool/call`、`goal/change for mutations`、`tool/result` | - | create、edit、pause 和 resume 要求直接来自人类的根权限；complete 和 blocked 也接受确切的当前 Goal Round。blocked 的默认下限是 3 个获准的 Round。 | | `@deepseek-ai/dsh-schedule` | `schedule_create`、`schedule_delete`、`schedule_list` | `ctx.tools`、`ctx.sessions`、Session 持久化、未来创建的 live 根 Agent | `tool/call`、`schedule/change create or delete`、`tool/result` | - | 仅在选择启用的 Schedule 插件加载后创建的 live 根 Agent scope 内注册。版本 1 接受 after_seconds、显式绝对 at 和有界固定速率 every_seconds，并披露 session-local 交付；管理读取与变更必须通过共享的 Session 持久化 barrier。 | | `@deepseek-ai/dsh-tool-lsp` | `lsp` | `ctx.tools`、`ctx.lsp`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，因此其模型可见 schema 在更换提供方时保持稳定。运行时要求已注册提供方，例如 `@deepseek-ai/dsh-lsp-stdio`；如果没有提供方，查询会返回结构化 `LSP_UNAVAILABLE` 错误，而不会改变 schema。 | | `@deepseek-ai/dsh-tool-ralph` | `ralph` | `ctx.tools`、`ctx.workflowEngine`、`ctx.subagents`、`ctx.systemPrompt`、`a calling Agent (exec.agent parents every fresh round)` | `tool/call`、`tool/result`、`workflow and child session events during execution` | - | 固定的前台工作流会在每个 Round 启动一个全新的结构化子级；模型只能选择不可变目标和可选的 Round 上限。 | | `@deepseek-ai/dsh-tool-skill` | `skill` | `ctx.tools`、`ctx.agents`、`ctx.skills` | `tool/call`、`tool/result`、`user/message replacement catalogs via agent.inject()` | - | - | | `@deepseek-ai/dsh-tool-session-query` | `session_event_read`、`session_event_search`、`session_event_trace`、`session_search`、`session_trace` | `ctx.tools`、`ctx.systemPrompt`、`ctx.sessionQuery`、`a calling Agent for workspace authority` | `tool/call`、`tool/result` | - | 这 5 个只读工具会隐藏提供方游标，并根据不可变的调用 agent 会话为每个结果授权。该包需要选择启用；需要强制截止时间或限制行内输出的组合还会挂载通用超时或 spill 策略。 | | `@deepseek-ai/dsh-tool-subagent` | `list_subagent_models`、`subagent` | `ctx.tools`、`ctx.subagents`、`ctx.systemPrompt`、`用于模型发现和所选路由校验的 ctx.llm` | `tool/call`、`tool/result`、`child session events through the chosen provider` | `subagent`、`subagent_fork` | 注册的委派工具名称取决于加载时 `toolName` 配置（默认为 `subagent`）；上述默认 schema 关闭模型选择，而发现 schema 则展示为已启用 Session 中可用的固定配套工具。Web preset 会在每个新顶层 Session 创建时读取插件页偏好，并为其子 Session 保留该决定；`subagent_fork` 始终使用固定路由。每个实例通过 `modelSelectionSettings`、`backgroundMode` 与 `enableRunInBackground` 独立控制是否读取模型选择设置及其后台行为。 | | `@deepseek-ai/dsh-tool-subagent-control` | `interrupt_agent`、`list_agents`、`send_message` | `ctx.tools`、`ctx.subagents`、`ctx.agents and ctx.sessionProjections (list_agents only)` | `tool/call`、`tool/result`、`child session events through ctx.subagents` | - | 这些是控制可继续后台 subagent 的全局命名工具：绑定提供方的 `tool-subagent` 实例注册不同的委派工具；本包注册一次 `send_message` 和 `interrupt_agent`，另由 `list_agents` 通过单独加载的 `/list-agents` 插件提供，其目录行使用 sessionProjections 和实时 Agent 注册表。 | | `@deepseek-ai/dsh-tool-jobs` | `job_kill`、`job_list`、`job_output` | `ctx.tools`、`ctx.jobs`、`ctx.systemPrompt` | `tool/call`、`tool/result`、`user/message via agent.inject() for background completion notices` | - | 与任务种类无关的后台任务控制器：后台 bash 命令、PTY 发送和 subagent 都通过相同的 3 个工具读取、列出和终止。加载该插件会挂接控制器，从而启用生产方的 `ctx.jobs.start()`。 | | `@deepseek-ai/dsh-experimental-tool-agent-team` | `followup_task`、`interrupt_agent`、`list_agents`、`send_message`、`spawn_teammate`、`team_task_create`、`team_task_get`、`team_task_list`、`team_task_update`、`wait_agent` | `ctx.tools`、`ctx.systemPrompt`、`ctx.agentTeams`、`an exact live Team member Agent` | `tool/call`、`team/member`、`team/message/queued`、`team/message/delivered`、`team/task`、`tool/result` | - | 这 10 个工具限定于隐式 Team Lead 与持久 teammate 作用域。随产品发布的 dsh-base bundle 默认禁用该包；文档中的 Agent Teams profile patch 会启用它，并禁用旧 continuable child 的同名控制工具。 | | `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`、`owning Agent session` | `tool/call`、`todo/write`、`tool/result` | - | todo_write 是会话所有的状态；UI 将最新的 todo/write 事件渲染为检查清单。`allowParallelInProgress` 是没有默认值的必填项，因此本目录明确选择 `true`，对应描述允许同时存在多个 `in_progress` 项。选择 `false` 的部署会获得同一工具，但描述会要求只能有 1 个活动任务。 | | `@deepseek-ai/dsh-tool-workflow` | `workflow` | `ctx.tools`、`ctx.workflowEngine`、`ctx.systemPrompt`、`a calling Agent (exec.agent parents the script children)` | `tool/call`、`tool/result` | - | - | | `@deepseek-ai/dsh-tool-web` | `web_fetch`、`web_search` | `ctx.tools`、`ctx.web`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | web_search 和 web_fetch 将提供方选择置于 ctx.web 之后，使模型可见 schema 在更换后端时保持稳定。 | ## `@deepseek-ai/dsh-tool-ask-user` ### `ask_user_question` 继续操作前，如果需要确认、选择或缺失的信息，请向用户提出简明问题。发送一个或多个问题，每个问题都带一个稳定 id，该 id 会在答案中原样返回。 ```json { "type": "object", "properties": { "questions": { "type": "array", "description": "Questions to ask the user before continuing.", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Stable id for this question; echoed in the answer." }, "question": { "type": "string", "description": "The specific question to ask the user." }, "header": { "type": "string", "description": "Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"." }, "options": { "type": "array", "description": "Optional choices to show the user. If you recommend one, put it first and append \"(Recommended)\" to that label.", "items": { "type": "object", "additionalProperties": true, "properties": { "label": { "type": "string", "description": "Short user-facing option label." }, "description": { "type": "string", "description": "One sentence explaining the tradeoff or impact." } }, "required": [ "label" ] } }, "multi_select": { "type": "boolean", "description": "Whether the user may select more than one option. Defaults to false." } }, "required": [ "id", "question" ] } } }, "required": [ "questions" ] } ``` 来源：[`packages/interaction/tool-ask-user/src/index.ts`](../packages/interaction/tool-ask-user/src/index.ts) ask_user_question 会暂停工具调用，直到当前 UI 提供方返回人类答案。 ## `@deepseek-ai/dsh-tools` ### `run_code` 针对可用工具执行 TypeScript 程序。接受两个必填参数：`code`，即异步函数的**函数体**（仅使用可擦除语法；支持顶层 `await` 和 `return`）；以及 `description`，简要说明该程序做什么。请根据系统提示词中的声明，以 `await tools.name(args)` 形式调用工具。只有打印或返回的内容属于程序输出，请谨慎筛选。含图片的子工具结果会在运行结束后附加。 ```json { "type": "object", "properties": { "code": { "type": "string", "description": "The program: the body of an async TypeScript function." }, "description": { "type": "string", "description": "Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"." } }, "required": [ "code", "description" ] } ``` 来源：[`packages/core/tools/src/ptc.ts`](../packages/core/tools/src/ptc.ts) 在 `mode: ptc`／`mode: both` 下，它由工具注册表所有，作为可过滤能力层之外的保留传输机制（参见 PTC mode Agent Note）。在 `ptc` 下，它是注册表对协议格式的唯一贡献；其他可见能力在使用已加载运行时语言生成的 SDK 章节中声明。程序通过 binding 调用这些能力，调用按照原生并发约定调度：启动顺序和策略遵循提交顺序，并发安全的函数体最多重叠执行 `maxParallelSubCalls` 个。调用会重新进入完整且受守卫保护的工具流水线，并将每个嵌套执行关联到此外层结果。 ## `@deepseek-ai/dsh-plan-mode` ### `exit_plan_mode` 仅在规划模式下使用。提交计划供用户评审，并在获批后退出规划模式。发送**完整的** Markdown 计划，以一个为计划命名的 # 标题开头。用户可以批准（从你的下一步骤起执行计划），也可以要求继续规划；其反馈会通过工具结果返回，请修改后再次提交。 ```json { "type": "object", "properties": { "plan": { "type": "string", "description": "The complete plan, as markdown, starting with a # heading that names it." } }, "required": [ "plan" ] } ``` 来源：[`packages/plan/plan-mode/src/index.ts`](../packages/plan/plan-mode/src/index.ts) 规划未激活时，exit_plan_mode 仍保留在面向模型的 schema 中，这样状态转换不会在规划策略变更之外额外造成工具目录变动。其执行路径会拒绝规划模式之外的调用；在规划模式下，它通过用户交互 seam 提交计划（批准／根据反馈继续规划），批准后会在步骤边界记录规划模式已停用。 ## `@deepseek-ai/dsh-tool-bash` ### `bash` 执行 bash 命令（`bash -c`）并返回 stdout/stderr。每次调用都在新 shell 中运行：调用之间不保留任何状态（cwd、变量、函数），请传入 `workdir`，不要使用 `cd`。非零退出会报告为 `[exit code: N]`。当前 harness 环境信息通过托管的 `$DSH_*` 变量公开，需要时请检查这些变量。命令可能在文件沙箱中运行；被阻止的文件操作报告为 `[sandbox: file access denied under mode]`，这是策略拒绝，而不是命令缺陷，请勿换一种方式重试。较长的输出会截断，只保留尾部；如可用，完整输出会保存到文件并报告其路径。对于长时间运行的命令，请设置 `run_in_background: true`：调用会立即返回 job id；使用 `job_output` 读取输出，使用 `job_kill` 停止任务。 ```json { "type": "object", "properties": { "command": { "type": "string", "description": "The bash command to execute." }, "description": { "type": "string", "description": "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"." }, "timeoutMs": { "type": "number", "description": "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry." }, "workdir": { "type": "string", "description": "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it." }, "run_in_background": { "type": "boolean", "description": "Run in the background and return a job id immediately (collect with job_output, stop with job_kill). No timeout applies." } }, "required": [ "command", "description" ] } ``` 来源：[`packages/shell/tool-bash/src/index.ts`](../packages/shell/tool-bash/src/index.ts) bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_background` 的运行会注册到通用 `ctx.jobs` 运行时，并通过 `job_*` 工具（来自 `@deepseek-ai/dsh-tool-jobs`）收集／停止；禁用 `enableRunInBackground` 配置（默认为 true）后，该参数会被完全移除。 ## `@deepseek-ai/dsh-tool-pwsh` ### `pwsh` 执行 PowerShell 命令（`pwsh -Command`）并返回 stdout/stderr。每次调用都在新的 pwsh 进程中运行：调用之间不保留任何状态（cwd、变量、函数），请传入 `workdir`，不要使用 `cd`。路径采用 Windows 原生形式（`C:\...`）；使用 `$env:NAME` 读取环境变量。非零退出会报告为 `[exit code: N]`。当前 harness 环境信息通过托管的 `$env:DSH_*` 变量公开，需要时请检查这些变量。命令可能在文件沙箱中运行；被阻止的文件操作报告为 `[sandbox: file access denied under mode]`，这是策略拒绝，而不是命令缺陷，请勿换一种方式重试。较长的输出会截断，只保留尾部；如可用，完整输出会保存到文件并报告其路径。在 Windows 上，被强制终止的命令会以 `[exit code: 1]` 结算且不带信号标记，请将其视为中断，而不是命令失败。对于长时间运行的命令，请设置 `run_in_background: true`：调用会立即返回 job id；使用 `job_output` 读取输出，使用 `job_kill` 停止任务。 ```json { "type": "object", "properties": { "command": { "type": "string", "description": "The PowerShell command to execute." }, "description": { "type": "string", "description": "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"Get-Process\" → \"List running processes\"." }, "timeoutMs": { "type": "number", "description": "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry." }, "workdir": { "type": "string", "description": "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it." }, "run_in_background": { "type": "boolean", "description": "Run in the background and return a job id immediately (collect with job_output, stop with job_kill). No timeout applies." } }, "required": [ "command", "description" ] } ``` 来源：[`packages/shell/tool-pwsh/src/index.ts`](../packages/shell/tool-pwsh/src/index.ts) pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.shell` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.jobs` 运行时，并通过 `job_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-shell-env`。每次调用都在新进程中运行，不使用持久 PTY 会话。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。 ## `@deepseek-ai/dsh-tool-cordis` ### `cordis_define` 定义一个不可变的 Cordis Package。新建 Plugin 时使用 kind:"new"，只提供 3 至 6 位小写英文字母组成的语义前缀；Host 返回最终 pluginId 和 packageId。修改现有 Plugin 时使用 kind:"existing" 并传入精确 pluginId，以追加 Package 而不覆盖旧版本。code.host 与 code.client 至少提供一个；每个值都是返回 Cordis Plugin 的 plain JavaScript 函数体，不经过 TypeScript、JSX 或 import 转换。依赖 Service、Event、Builtin、Slot 或 token 前先查询 Inspect。Define 只校验参数和语法并记录源码，不申请审批、不执行 apply，也不改变 currentPackageId。成功后用返回的 ID 调用 cordis_run。 ```json { "type": "object", "properties": { "plugin": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "const": "new" }, "idPrefix": { "type": "string", "description": "Suggested semantic prefix of 3–6 lowercase English letters; the Host adds a unique numeric suffix." } }, "required": [ "kind", "idPrefix" ] }, { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "const": "existing" }, "pluginId": { "type": "string", "description": "Exact ID of an existing Plugin; the new Package is appended to that instance." } }, "required": [ "kind", "pluginId" ] } ] }, "name": { "type": "string", "description": "Short, readable Package name." }, "purpose": { "type": "string", "description": "One-sentence, user-facing description of the Package purpose." }, "code": { "type": "object", "additionalProperties": false, "properties": { "host": { "type": "string", "description": "Plain JavaScript function body that returns the Host-half Cordis Plugin." }, "client": { "type": "string", "description": "Plain JavaScript function body that returns the browser Client-half Cordis Plugin." } } } }, "required": [ "plugin", "name", "purpose", "code" ] } ``` 来源：[`packages/extensions/tool-cordis/src/index.ts`](../packages/extensions/tool-cordis/src/index.ts) ### `cordis_inspect_list` 列出 Host 当前已知的全部 Cordis Inspect Provider，包括本地 Host Provider 和 Client 最近同步的 manifest。每项包含所属平台、用途、只读方法及输入／输出 schema。创建或修改 Package 前先调用本 Tool，再从结果中选择 cordis_inspect_query 的 provider 和 method。不要猜测名称，也不要把 Inspect method 当作 Plugin 代码可调用的业务 Service。 ```json { "type": "object", "properties": {} } ``` 来源：[`packages/extensions/tool-cordis/src/index.ts`](../packages/extensions/tool-cordis/src/index.ts) ### `cordis_inspect_query` 执行 Inspect Provider 显式声明的只读查询。platform、provider 和 method 必须来自 cordis_inspect_list，input 必须符合该方法的 schema。在 cordis_define 前用本 Tool 读取精确 Service 方法、Event mode、Builtin 签名、Tool schema、主题 token，或实时 Slot 树及 props。Host 查询在本地执行；Client 查询等待首个有效页面响应，在页面回答或 Tool 被取消前保持 pending。本 Tool 不能调用业务 Service 方法或修改运行时。查询 Service.listService 和 Event.listEvents 时，先不传 input 浏览紧凑签名目录，再查询精确 service 或 event 获取结构化约定和引用类型。查询 Slots.listSubTree 时，先不传 root 浏览紧凑树，再查询精确 root 获取完整注册约定和 props。 ```json { "type": "object", "properties": { "platform": { "type": "string", "description": "Runtime platform that owns the Provider.", "enum": [ "host", "client" ] }, "provider": { "type": "string", "description": "Exact Provider ID returned by cordis_inspect_list." }, "method": { "type": "string", "description": "Exact method name declared by the Provider manifest." }, "input": { "description": "Optional query input; it must satisfy the method input schema." } }, "required": [ "platform", "provider", "method" ] } ``` 来源：[`packages/extensions/tool-cordis/src/index.ts`](../packages/extensions/tool-cordis/src/index.ts) ### `cordis_inspect_self` 按逐层增加的详细程度检查当前 Session 拥有的动态 Cordis 对象。不传 ID 时只列 Plugin 摘要；只传 pluginId 时返回版本指针、最新 Run 和全部 Package 摘要；只有同时传 pluginId 与 packageId 才返回该不可变 Package 的 Host/Client 源码和运行诊断。packageId 不能单独传入。处理 @pluginId、修复异步失败或定义更新版本前，先查询精确 Package。本 Tool 只读，不执行代码，也不改变版本指针。 ```json { "type": "object", "properties": { "pluginId": { "type": "string", "description": "Stable Plugin ID returned by cordis_define or injected by @pluginId; omit it to list every current Plugin." }, "packageId": { "type": "string", "description": "Exact immutable Package ID owned by pluginId; when specified, source and diagnostics are returned." } } } ``` 来源：[`packages/extensions/tool-cordis/src/index.ts`](../packages/extensions/tool-cordis/src/index.ts) ### `cordis_run` 激活动态 Plugin 的一个精确 Package。首次激活、重启 currentPackageId 或回退使用 mode:"run"；已有 current 时，即使 Plugin 当前已停止，切换到其他 Package 也使用 mode:"update"。未授权的 Client Package 创建审批请求并返回 awaiting-approval；已授权的 Package 返回 starting，并在浏览器中异步继续。两种结果都不会在 Tool 内等待最终结局。currentPackageId 只在完整成功后改变；失败时保留旧 current 和目标 next。异步成功、拒绝或技术失败通过状态与 steering 报告。技术失败后，用 cordis_inspect_self 读取诊断，修正同一 Plugin 并自主重试。用户拒绝后不要再次申请审批。 ```json { "type": "object", "properties": { "pluginId": { "type": "string", "description": "Stable Plugin ID returned by cordis_define." }, "packageId": { "type": "string", "description": "Exact immutable Package ID to activate under that Plugin." }, "mode": { "type": "string", "description": "Use run for the first activation, restarting current, or rollback; use update to switch from current to a different Package.", "enum": [ "run", "update" ] } }, "required": [ "pluginId", "packageId", "mode" ] } ``` 来源：[`packages/extensions/tool-cordis/src/index.ts`](../packages/extensions/tool-cordis/src/index.ts) ### `cordis_stop` 停止动态 Plugin 的当前 Run，并取消尚未完成的审批或激活请求。保留 Plugin、全部不可变 Package、授权、currentPackageId 和 nextPackageId，以便之后直接运行或更新。停止已处于停止状态的 Plugin 会幂等成功。临时禁用副作用使用本 Tool；永久移除使用 cordis_undefine。 ```json { "type": "object", "properties": { "pluginId": { "type": "string", "description": "Stable dynamic Plugin ID to stop." } }, "required": [ "pluginId" ] } ``` 来源：[`packages/extensions/tool-cordis/src/index.ts`](../packages/extensions/tool-cordis/src/index.ts) ### `cordis_undefine` 永久移除当前 Session 拥有的动态 Plugin。如果它正在运行或等待审批，先停止并取消请求，再删除全部 Package、授权和版本指针。返回后，其 pluginId、packageIds、@ 引用和 Package 业务视图均失效；历史卡片只保留“Plugin 已移除”记录。需要保留版本以便重启或回退时不要调用本 Tool，应改用 cordis_stop。 ```json { "type": "object", "properties": { "pluginId": { "type": "string", "description": "Stable dynamic Plugin ID to remove permanently." } }, "required": [ "pluginId" ] } ``` 来源：[`packages/extensions/tool-cordis/src/index.ts`](../packages/extensions/tool-cordis/src/index.ts) 不在任何随产品发布的树中，需要显式选择启用；动态 Package 代码可以访问真实运行时，见 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md。该工具集注入 `@deepseek-ai/dsh-cordis-host-runner` 提供的 `ctx.dynamicCordisRunner`，后者拥有定义注册表和 vm 沙箱；组合缺少它时这些工具不会激活。运行中的 Package 在停止、undefine 或 DSH 重启前可以注册**额外的**模型可见工具；发生这类工具集变化时，系统会记录完整且有变动的请求头。 ## `@deepseek-ai/dsh-tool-bash-persistent` ### `bash` 在持久 bash shell 中运行命令。包括当前目录和已导出环境变量在内的状态会在此 agent 的多次调用之间保留。 ```json { "type": "object", "properties": { "command": { "type": "string", "description": "The bash command to run. Relative path is preferred in the command." } }, "required": [ "command" ] } ``` 来源：[`packages/shell/tool-bash-persistent/src/index.ts`](../packages/shell/tool-bash-persistent/src/index.ts) 一个按所有者隔离的持久 bash 工具；部署组合提供 PTY 后端，并可覆盖面向模型的环境描述。 ## `@deepseek-ai/dsh-tool-pwsh-persistent` ### `pwsh` 在持久 PowerShell shell 中运行命令。包括当前目录和已导出环境变量在内的状态会在此 agent 的多次调用之间保留。 ```json { "type": "object", "properties": { "command": { "type": "string", "description": "The PowerShell command to run. Relative path is preferred in the command." } }, "required": [ "command" ] } ``` 来源：[`packages/shell/tool-pwsh-persistent/src/index.ts`](../packages/shell/tool-pwsh-persistent/src/index.ts) 一个按所有者隔离的持久 pwsh 工具，持久 bash 工具的 Windows 对应物；部署组合提供 pwsh 方言的 PTY 后端，并可覆盖面向模型的环境描述。 ## `@deepseek-ai/dsh-tool-str-replace-editor` ### `str_replace_editor` 用于查看、创建和编辑文件的自定义编辑工具： * 状态会在命令调用以及与用户的讨论之间持久保留 * 如果 `path` 是文件，`view` 会显示应用 `cat -n` 后的结果。如果 `path` 是目录，`view` 会列出最多向下 2 层的非隐藏文件和目录 * 如果指定的 `create` 命令目标 `path` 已作为文件存在，则不能使用该命令 * 如果 `command` 产生较长输出，输出会被截断并标记为 `` * 当前命令不使用某个参数时，值为 `null` 的占位参数视为未提供。必填参数仍须提供值；删除匹配内容时应省略 `str_replace.new_str`，而不是将其设为 `null` 使用 `str_replace` 命令时请注意： * `old_str` 参数应与原文件中一行或多行连续内容**完全**匹配。请留意空白字符！ * 如果 `old_str` 参数在文件中不唯一，则不会执行替换。请确保在 `old_str` 中包含足够的上下文，使其唯一 * `new_str` 参数应包含用于替换 `old_str` 的已编辑行 ```json { "type": "object", "properties": { "command": { "type": "string", "description": "The commands to run. Allowed options are: `view`, `create`, `str_replace`, `insert`.", "enum": [ "view", "create", "str_replace", "insert" ] }, "path": { "type": "string", "description": "Absolute path to file or directory, e.g. `/repo/file.py` or `/repo`." }, "file_text": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Required string parameter of `create` command, with the content of the file to be created. A null placeholder is treated as omitted by commands that do not use this parameter." }, "insert_line": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Required integer parameter of `insert` command. The `new_str` will be inserted AFTER the line `insert_line` of `path`. A null placeholder is treated as omitted by commands that do not use this parameter." }, "new_str": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional string parameter of `str_replace` command containing the new string (if omitted, no string will be added). Required string parameter of `insert` command containing the string to insert. A null placeholder is accepted only by commands that do not use this parameter." }, "old_str": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Required string parameter of `str_replace` command containing the string in `path` to replace. A null placeholder is treated as omitted by commands that do not use this parameter." }, "view_range": { "oneOf": [ { "type": "array", "items": { "type": "integer" } }, { "type": "null" } ], "description": "Optional parameter of `view` command when `path` points to a file. If omitted or null, the full file is shown. If provided, the file will be shown in the indicated line number range, e.g. [11, 12] will show lines 11 and 12. Indexing at 1 to start. Setting `[start_line, -1]` shows all lines from `start_line` to the end of the file." } }, "required": [ "command", "path" ] } ``` 来源：[`packages/fs/tool-str-replace-editor/src/index.ts`](../packages/fs/tool-str-replace-editor/src/index.ts) 基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。 ## `@deepseek-ai/dsh-tool-fs` ### `edit` 通过替换字面量文本来编辑现有 UTF-8 文本文件。 ```json { "type": "object", "properties": { "file_path": { "type": "string", "description": "Path to edit, resolved by the filesystem backend." }, "old_string": { "type": "string", "description": "Literal text to replace. Must match exactly." }, "new_string": { "type": "string", "description": "Literal replacement text. Use an empty string to delete the match." }, "replace_all": { "type": "boolean", "description": "Replace all matches. Defaults to false; when false, old_string must appear exactly once." } }, "required": [ "file_path", "old_string", "new_string" ] } ``` 来源：[`packages/fs/tool-fs/src/index.ts`](../packages/fs/tool-fs/src/index.ts) ### `read` 读取 UTF-8 文本文件，并返回带行号的内容。 ```json { "type": "object", "properties": { "file_path": { "type": "string", "description": "Path to read, resolved by the filesystem backend." }, "offset": { "type": "number", "description": "1-based first line to return. Defaults to 1." }, "limit": { "type": "number", "description": "Maximum number of lines to return. Defaults to 2000." } }, "required": [ "file_path" ] } ``` 来源：[`packages/fs/tool-fs/src/index.ts`](../packages/fs/tool-fs/src/index.ts) ### `read_image` 读取 PNG/JPEG/WebP/GIF 文件并返回图像本身。无扩展名的路径同样被接受；格式按文件内容检测，因此规范化附件路径可以直接传入，无需复制或重命名。Harness 会在下一次模型请求前校验并缩小受支持的大图，因此仅为查看图片时应直接使用此工具，无需安装图片库或创建缩略图。可以用小批次并发读取彼此独立的文件。要求当前模型接受图像输入。 ```json { "type": "object", "properties": { "file_path": { "type": "string", "description": "Path to the image file, resolved by the filesystem backend." } }, "required": [ "file_path" ] } ``` 来源：[`packages/fs/tool-fs/src/index.ts`](../packages/fs/tool-fs/src/index.ts) ### `write` 创建或完全替换 UTF-8 文本文件。 ```json { "type": "object", "properties": { "file_path": { "type": "string", "description": "Path to write, resolved by the filesystem backend." }, "content": { "type": "string", "description": "Full UTF-8 text content to write." } }, "required": [ "file_path", "content" ] } ``` 来源：[`packages/fs/tool-fs/src/index.ts`](../packages/fs/tool-fs/src/index.ts) 先读后写／编辑策略由 `@deepseek-ai/dsh-fs-observation-policy` 添加；它是一个 `fs/*` 事件门禁插件，不会改变 schema。加载这些工具的部署按预期也应加载该插件。没有 `ctx.attachments` 时图片工具不会注册；其 schema 与路由无关，执行时除非确切路由的模型声明图片输入，否则拒绝。 ## `@deepseek-ai/dsh-tool-fs-search` ### `glob` 查找路径匹配 glob 模式的文件。只返回匹配的文件路径，绝不返回目录；包括隐藏文件和被忽略的文件，但排除 VCS 元数据目录。最多按修改时间顺序返回 100 条路径；如果结果更多，则改为返回从顶层条目中抽样的 100 条路径，说明已抽样，并报告完整排序列表的保存位置。该工具不枚举目录条目。 ```json { "type": "object", "properties": { "pattern": { "type": "string", "description": "Glob pattern to match file paths against (e.g. \"**/*.ts\", \"src/**/*.test.js\"). A pattern with no \"/\" matches the basename at any depth, so \"*\" and \"*.ts\" both search the whole tree; include a separator to anchor the depth." }, "path": { "type": "string", "description": "Directory to search in. Defaults to the session workspace; a relative path resolves against it." } }, "required": [ "pattern" ] } ``` 来源：[`packages/fs/tool-fs-search/src/index.ts`](../packages/fs/tool-fs-search/src/index.ts) ### `grep` 使用 ripgrep 正则表达式搜索文件内容。返回带行号的匹配行，并按文件分组。前 250 条匹配会直接返回；结果达到上限时会报告完整匹配列表的保存位置。如需周边上下文，请对匹配的文件使用 read。 ```json { "type": "object", "properties": { "pattern": { "type": "string", "description": "Regular expression to search for (ripgrep syntax)." }, "path": { "type": "string", "description": "File or directory to search. Defaults to the session workspace; a relative path resolves against it." }, "include": { "type": "string", "description": "One glob filter for which files to search (e.g. \"*.ts\", \"*.{js,jsx}\"). Not a list; negation is not supported." } }, "required": [ "pattern" ] } ``` 来源：[`packages/fs/tool-fs-search/src/index.ts`](../packages/fs/tool-fs-search/src/index.ts) glob 和 grep 是无条件可用的发现工具，通过 ctx.subprocess spawn 随包提供的 ripgrep 二进制文件（`@vscode/ripgrep`），并作为普通前台调用运行，绝不作为后台任务；无需在宿主机安装 `rg`，也不经过 shell 层。本目录使用 `sampleOverCapGlobResults: true`；部署必须显式选择该行为。结果超过上限时，会通过可选的 ctx.spillStore 后端保存完整的格式化列表；在共置部署中，如果后端公开本地路径，返回的定位信息可供后续读取／搜索。 ## `@deepseek-ai/dsh-tool-terminal` ### `terminal_close` 关闭一个持久终端，并等待其捕获且所有的进程树完全退出。 ```json { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Terminal session id." } }, "required": [ "sessionId" ] } ``` 来源：[`packages/terminal/tool-terminal/src/index.ts`](../packages/terminal/tool-terminal/src/index.ts) ### `terminal_list` 列出当前 agent 所有的持久终端会话。 ```json { "type": "object", "properties": {} } ``` 来源：[`packages/terminal/tool-terminal/src/index.ts`](../packages/terminal/tool-terminal/src/index.ts) ### `terminal_open` 通过已注册的后端类型创建按所有者隔离的持久终端会话。需要在多次工具调用之间保留 shell 或 REPL 状态时，请使用此工具。 ```json { "type": "object", "properties": { "type": { "type": "string", "description": "Registered terminal backend type, usually \"shell\"." }, "name": { "type": "string", "description": "Optional owner-local display name such as \"main\" or \"gdb\"." }, "cwd": { "type": "string", "description": "Initial working directory. Defaults to the deployment workspace root." } }, "required": [ "type" ] } ``` 来源：[`packages/terminal/tool-terminal/src/index.ts`](../packages/terminal/tool-terminal/src/index.ts) ### `terminal_read` 从持久终端读取一页有界的保留输出，不发送输入。 ```json { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Terminal session id." }, "offset": { "type": "number", "description": "Newest-relative line offset (default 0)." }, "count": { "type": "number", "description": "Requested line count (default 500; backend caps apply)." } }, "required": [ "sessionId" ] } ``` 来源：[`packages/terminal/tool-terminal/src/index.ts`](../packages/terminal/tool-terminal/src/index.ts) ### `terminal_send` 向持久终端发送文本。默认会提交 Enter，并等待提示符、stdin 等待、输出静默、超时或会话退出。后台模式会返回供 job_output／job_kill 使用的 job id。 ```json { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Terminal session id returned by terminal_open or terminal_list." }, "text": { "type": "string", "description": "UTF-8 text to write to the terminal." }, "submit": { "type": "boolean", "description": "Submit Enter after text (default true). Set false for control characters or incomplete REPL input." }, "run_in_background": { "type": "boolean", "description": "Return a job id immediately; collect with job_output or stop with job_kill." } }, "required": [ "sessionId", "text" ] } ``` 来源：[`packages/terminal/tool-terminal/src/index.ts`](../packages/terminal/tool-terminal/src/index.ts) ### `terminal_signal` 向持久终端当前的前台进程组发送允许的信号。 ```json { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Terminal session id." }, "signal": { "type": "string", "description": "Signal to deliver. Shell-targeted SIGKILL is rejected; use terminal_close.", "enum": [ "SIGINT", "SIGTERM", "SIGKILL", "SIGTSTP", "SIGHUP" ] } }, "required": [ "sessionId", "signal" ] } ``` 来源：[`packages/terminal/tool-terminal/src/index.ts`](../packages/terminal/tool-terminal/src/index.ts) 这 6 个终端工具需要选择启用，用于补充一次性 bash／文件系统工具。`terminal_send(run_in_background: true)` 会注册到 `ctx.jobs`；schema 不包含 TUI、具名按键序列、BEL、调整尺寸、自动启动和跨 agent 共享。 ## `@deepseek-ai/dsh-tool-goal` ### `create_goal` 当当前直接人类请求是需要跨自主 Goal Round 持续推进的长期目标时，创建一个持久化的同会话完成目标。即使用户没有明确说「创建目标」，你也可以推断其意图。不要用于简单的单轮工作。执行时会拒绝非人类权限和 subagent 权限。 ```json { "type": "object", "properties": { "objective": { "type": "string", "description": "The concrete completion objective inferred from the direct human request." }, "max_goal_rounds": { "type": "number", "description": "Optional positive safe-integer limit on automatic continuation rounds." } }, "required": [ "objective" ] } ``` 来源：[`packages/goal/tool-goal/src/index.ts`](../packages/goal/tool-goal/src/index.ts) ### `get_goal` 读取当前的同会话目标，包括确切的 id／revision、目标、阶段、已完成的延续 Round 数、Round 上限、存在时的阻塞原因，以及是否已准备下一次延续。更新目标前请先调用此工具。 ```json { "type": "object", "properties": {} } ``` 来源：[`packages/goal/tool-goal/src/index.ts`](../packages/goal/tool-goal/src/index.ts) ### `update_goal` 更新确切的当前目标 revision。edit、pause 和 resume 要求直接的顶层人类请求。在自动延续当前目标期间，也允许 complete 和 blocked。在达到配置的最小 Round 数之前会拒绝 blocked；模型仍须判断相同条件是否在这些 Round 中持续存在，并在 blocked_reason 中予以说明。 ```json { "type": "object", "properties": { "goal_id": { "type": "string", "description": "Exact id returned by get_goal." }, "revision": { "type": "number", "description": "Exact positive revision returned by get_goal." }, "action": { "type": "string", "description": "edit | pause | resume | complete | blocked", "enum": [ "edit", "pause", "resume", "complete", "blocked" ] }, "objective": { "type": "string", "description": "Replacement objective; valid only with action edit." }, "max_goal_rounds": { "type": "number", "description": "Replacement cap; valid only with action edit." }, "blocked_reason": { "type": "string", "description": "Concrete blocking condition; required only with action blocked." } }, "required": [ "goal_id", "revision", "action" ] } ``` 来源：[`packages/goal/tool-goal/src/index.ts`](../packages/goal/tool-goal/src/index.ts) create、edit、pause 和 resume 要求直接来自人类的根权限；complete 和 blocked 也接受确切的当前 Goal Round。blocked 的默认下限是 3 个获准的 Round。 ## `@deepseek-ai/dsh-schedule` ### `schedule_create` 在当前会话中创建一条提醒。请提供非空 prompt 和恰好一个 selector：正的安全整数 after_seconds 延时；作为严格带偏移日期时间或本地日期／时间对象的 at；或不小于 300 的安全整数 every_seconds。固定速率提醒始终与创建时刻对齐，会跳过错过的发生时点，并把每条逾期规则的最新一个发生时点合并到一个批次中。交付模式是 session-local：只有此会话处于 live 状态时，提醒才会准时运行；否则提醒会进入 overdue 状态，直至会话恢复。 ```json { "type": "object", "properties": { "prompt": { "type": "string", "description": "Reminder content to present when the target becomes due." }, "after_seconds": { "type": "number", "description": "Positive safe-integer delay in seconds." }, "every_seconds": { "type": "number", "description": "Fixed-rate safe-integer interval in seconds, at least 300." }, "at": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": false, "properties": { "date": { "type": "string" }, "time": { "type": "string" }, "time_zone": { "type": "string" } }, "required": [ "date", "time", "time_zone" ] } ], "description": "Absolute target as strict offset RFC 3339 or local date/time with an explicit IANA zone." } }, "required": [ "prompt" ] } ``` 来源：[`packages/schedule/schedule/src/tools.ts`](../packages/schedule/schedule/src/tools.ts) ### `schedule_delete` 使用 schedule_create 或 schedule_list 返回的确切 id，删除当前会话中的一条活动提醒。未知或已经结束的 id 会返回 deleted false。 ```json { "type": "object", "properties": { "id": { "type": "string", "description": "Exact session-local schedule id." } }, "required": [ "id" ] } ``` 来源：[`packages/schedule/schedule/src/tools.ts`](../packages/schedule/schedule/src/tools.ts) ### `schedule_list` 按创建顺序列出当前会话中的所有活动提醒，包括确切 id、UTC 目标、scheduled 或 overdue 状态，以及 session-local 交付模式。 ```json { "type": "object", "properties": {} } ``` 来源：[`packages/schedule/schedule/src/tools.ts`](../packages/schedule/schedule/src/tools.ts) 仅在选择启用的 Schedule 插件加载后创建的 live 根 Agent scope 内注册。版本 1 接受 after_seconds、显式绝对 at 和有界固定速率 every_seconds，并披露 session-local 交付；管理读取与变更必须通过共享的 Session 持久化 barrier。 ## `@deepseek-ai/dsh-tool-lsp` ### `lsp` 查询语言服务器，以精确导航代码。operation 可取 goToDefinition、findReferences、goToImplementation 或 hover。line 和 character 是从 1 开始的 UTF-16 光标坐标。findReferences 包含声明。 ```json { "type": "object", "properties": { "operation": { "type": "string", "description": "goToDefinition, findReferences, goToImplementation, or hover.", "enum": [ "goToDefinition", "findReferences", "goToImplementation", "hover" ] }, "file_path": { "type": "string", "description": "The source file to query, relative to the workspace or absolute." }, "line": { "type": "number", "description": "One-based line of the cursor." }, "character": { "type": "number", "description": "One-based UTF-16 column of the cursor." } }, "required": [ "operation", "file_path", "line", "character" ] } ``` 来源：[`packages/lsp/tool-lsp/src/index.ts`](../packages/lsp/tool-lsp/src/index.ts) lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，因此其模型可见 schema 在更换提供方时保持稳定。运行时要求已注册提供方，例如 `@deepseek-ai/dsh-lsp-stdio`；如果没有提供方，查询会返回结构化 `LSP_UNAVAILABLE` 错误，而不会改变 schema。 ## `@deepseek-ai/dsh-tool-ralph` ### `ralph` 围绕一个不可变目标运行使用全新 agent 的前台 Ralph 循环。仅当直接人类明确要求 Ralph 或使用全新 agent 迭代时使用。每个 Round 都会启动一个全新子级，该子级看不到父级对话或先前子会话；共享工作区充当长期记忆，Round 之间只传递有界的结构化报告。当工作进程报告完成、报告具体阻塞项或达到 Round 上限时，调用返回。普通的长期同会话工作应使用 goal 工具。 ```json { "type": "object", "properties": { "objective": { "type": "string", "description": "The immutable completion objective for every fresh Ralph round." }, "maxRounds": { "type": "number", "description": "Optional positive safe-integer round cap, bounded by the deployment ceiling." } }, "required": [ "objective" ] } ``` 来源：[`packages/workflow/tool-ralph/src/index.ts`](../packages/workflow/tool-ralph/src/index.ts) 固定的前台工作流会在每个 Round 启动一个全新的结构化子级；模型只能选择不可变目标和可选的 Round 上限。 ## `@deepseek-ai/dsh-tool-skill` ### `skill` 加载可用 skill（技能）的完整说明。在执行点名某项 skill 或与其明确匹配的任务前，请使用会话 skill 目录中的确切名称调用此工具。 ```json { "type": "object", "properties": { "name": { "type": "string", "description": "The exact skill name from the available skills list." } }, "required": [ "name" ] } ``` 来源：[`packages/skill/tool-skill/src/index.ts`](../packages/skill/tool-skill/src/index.ts) ## `@deepseek-ai/dsh-tool-session-query` ### `session_event_read` 从一个已获授权的会话中读取一个完整且未删节的事件，以及可选的相邻原始事件概述。 ```json { "type": "object", "properties": { "session_id": { "type": "string", "description": "Target session id. Omit for the current session." }, "seq": { "type": "integer", "description": "Target event sequence number." }, "before": { "type": "integer", "description": "Number of preceding raw events to summarize. Omit for none." }, "after": { "type": "integer", "description": "Number of following raw events to summarize. Omit for none." } }, "required": [ "seq" ] } ``` 来源：[`packages/session-query/tool-session-query/src/index.ts`](../packages/session-query/tool-session-query/src/index.ts) ### `session_event_search` 在一个已获授权的会话中搜索先前事件；如果搜索当前会话，则排除执行此次调用的步骤。 ```json { "type": "object", "properties": { "session_id": { "type": "string", "description": "Target session id. Omit for the current session." }, "query": { "type": "string", "description": "Literal full-text query over the target session." }, "seq_from": { "type": "integer", "description": "Inclusive event sequence lower bound." }, "seq_to": { "type": "integer", "description": "Inclusive event sequence upper bound." }, "time_from": { "type": "string", "description": "Inclusive timezone-qualified ISO 8601 event-time lower bound." }, "time_to": { "type": "string", "description": "Inclusive timezone-qualified ISO 8601 event-time upper bound." }, "event_types": { "type": "array", "description": "Event types to include.", "items": { "type": "string" } }, "surfaces": { "type": "array", "description": "Event surfaces to include.", "items": { "type": "string", "enum": [ "current", "shadowed", "log-only" ] } } }, "required": [ "query" ] } ``` 来源：[`packages/session-query/tool-session-query/src/index.ts`](../packages/session-query/tool-session-query/src/index.ts) ### `session_event_trace` 读取已获授权会话中某个事件的所有直接替换关系，以及该事件与其引用的来源事件之间的关系。 ```json { "type": "object", "properties": { "session_id": { "type": "string", "description": "Target session id. Omit for the current session." }, "seq": { "type": "integer", "description": "Target event sequence number." } }, "required": [ "seq" ] } ``` 来源：[`packages/session-query/tool-session-query/src/index.ts`](../packages/session-query/tool-session-query/src/index.ts) ### `session_search` 搜索调用方工作区中的先前会话，并从每个会话返回匹配度最高的事件。 ```json { "type": "object", "properties": { "query": { "type": "string", "description": "Literal full-text query over prior session history." }, "session_ids": { "type": "array", "description": "Optional session ids to include.", "items": { "type": "string" } }, "created_at_from": { "type": "string", "description": "Inclusive timezone-qualified ISO 8601 creation-time lower bound." }, "created_at_to": { "type": "string", "description": "Inclusive timezone-qualified ISO 8601 creation-time upper bound." }, "parent_session_ids": { "type": "array", "description": "Optional direct parent session ids.", "items": { "type": "string" } }, "include_root_sessions": { "type": "boolean", "description": "Include sessions with no parent in the parent filter." }, "availability": { "type": "array", "description": "Require at least one selected source availability.", "items": { "type": "string", "enum": [ "live", "persisted" ] } }, "event_seq_from": { "type": "integer", "description": "Inclusive event sequence lower bound." }, "event_seq_to": { "type": "integer", "description": "Inclusive event sequence upper bound." }, "event_time_from": { "type": "string", "description": "Inclusive timezone-qualified ISO 8601 event-time lower bound." }, "event_time_to": { "type": "string", "description": "Inclusive timezone-qualified ISO 8601 event-time upper bound." }, "event_types": { "type": "array", "description": "Event types to include.", "items": { "type": "string" } }, "event_surfaces": { "type": "array", "description": "Event surfaces to include.", "items": { "type": "string", "enum": [ "current", "shadowed", "log-only" ] } } }, "required": [ "query" ] } ``` 来源：[`packages/session-query/tool-session-query/src/index.ts`](../packages/session-query/tool-session-query/src/index.ts) ### `session_trace` 读取围绕一个会话的已授权会话谱系，包括完整可见的祖先和后代关系。 ```json { "type": "object", "properties": { "session_id": { "type": "string", "description": "Target session id. Omit for the current session." } } } ``` 来源：[`packages/session-query/tool-session-query/src/index.ts`](../packages/session-query/tool-session-query/src/index.ts) 这 5 个只读工具会隐藏提供方游标，并根据不可变的调用 agent 会话为每个结果授权。该包需要选择启用；需要强制截止时间或限制行内输出的组合还会挂载通用超时或 spill 策略。 ## `@deepseek-ai/dsh-tool-subagent` ### `list_subagent_models` 发现 subagent 可用的 LLM 路由，不更改当前 Agent。无参数调用会列出已注册提供方；提供 `provider` 时会列出其公布的模型；同时提供 `provider` 和 `model` 时会检查该精确模型及其推理强度。目录条目只提供建议：adapter 可能接受未列出的模型 id。把返回的 id 用于委派工具的 `provider`、`model` 与 `reasoning_effort` 字段。 ```json { "type": "object", "properties": { "provider": { "type": "string", "description": "Registered LLM provider id. Omit to list providers." }, "model": { "type": "string", "description": "Exact model id to inspect. Requires provider; omit to list that provider's advertised models." } } } ``` 来源：[`packages/subagent/tool-subagent/src/list-models.ts`](../packages/subagent/tool-subagent/src/list-models.ts) ### `subagent` 将一项自包含任务委派给 subagent（在自身上下文中工作的独立 agent），用它卸载聚焦且独立的工作，例如研究、限定范围的实现或分析，以免消耗当前对话的上下文。subagent 会返回结果，但不会返回中间步骤。请提供完整、独立的提示词，因为它看不到当前对话。此调用默认等待结果。设置 `run_in_background: true` 可返回 job id；使用 `job_output` 收集结果，使用 `job_kill` 停止任务。 ```json { "type": "object", "properties": { "description": { "type": "string", "description": "A short (3-5 word) description of the delegated task, for display." }, "prompt": { "type": "string", "description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs." }, "run_in_background": { "type": "boolean", "description": "Whether to run as a background job and return its id. Defaults to false; collect with job_output or stop with job_kill." } }, "required": [ "description", "prompt" ] } ``` 来源：[`packages/subagent/tool-subagent/src/index.ts`](../packages/subagent/tool-subagent/src/index.ts) 注册的委派工具名称取决于加载时 `toolName` 配置（默认为 `subagent`）；上述默认 schema 关闭模型选择，而发现 schema 则展示为已启用 Session 中可用的固定配套工具。Web preset 会在每个新顶层 Session 创建时读取插件页偏好，并为其子 Session 保留该决定；`subagent_fork` 始终使用固定路由。每个实例通过 `modelSelectionSettings`、`backgroundMode` 与 `enableRunInBackground` 独立控制是否读取模型选择设置及其后台行为。 ## `@deepseek-ai/dsh-tool-subagent-control` ### `interrupt_agent` 根据 agent id 请求取消后台 agent 的当前轮次。目标可以是你的直接子级，也可以是在你下方创建的更深层 agent。只有当前轮次会停止：已经排队发给该 agent 的消息会一直搁置到后续的 send_message；它启动的 agent 会继续运行；该 agent 本身仍可接受后续操作。停止请求被接受后，此调用立即返回，因此目标可能还会短暂运行；中断一个已经完成的 agent 是可接受的空操作。 ```json { "type": "object", "properties": { "agent_id": { "type": "string", "description": "The agent id of the running agent to interrupt." } }, "required": [ "agent_id" ] } ``` 来源：[`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts) ### `list_agents` 按持久 id 和标签列出你的可继续后台 subagent。用它回忆你启动过哪些 subagent，而不是轮询完成情况——subagent 完成时你会被告知。状态来自实时注册表：running 表示 agent 此刻正在工作；idle 表示已加载但处于轮次之间，可能正在等待它启动的 agent；ready 表示它只存在于存储中——可恢复而非终态，也不表示有结果等待收集；`send_message` 会在运行中 child 的最近 step 边界 steer 消息，或为 idle、ready child 启动轮次，且无论处于哪种状态，直接子级都仍可作为 `send_message` 的目标。该快照并非投递承诺；`send_message` 会执行权威检查，仍可能失败。无法读取的子级会作为诊断信息报告，而不会被静默丢弃。`descendants` 作用域会按稳定的前序顺序遍历你下方的整棵树，并为每个条目标注其持久的直接父会话 id 和深度。只有深度为 1 的条目可以使用 `send_message`；更深的条目只能作为 `interrupt_agent` 的候选目标。 ```json { "type": "object", "properties": { "scope": { "type": "string", "description": "children (default) lists direct children only; descendants walks the complete tree below you.", "enum": [ "children", "descendants" ] } } } ``` 来源：[`packages/subagent/tool-subagent-control/src/list-agents.ts`](../packages/subagent/tool-subagent-control/src/list-agents.ts) ### `send_message` 根据 agent id 向直接可继续 child 发送消息。如果你是驻留的可继续 child，也可以把自己的直接 parent 作为目标。如果目标仍在工作，消息会 steer 其最近的 step；如果目标处于 idle，消息会启动一个轮次。此调用不会返回该 agent 的答案，只会确认消息已投递。调用失败表示消息**未**投递。 ```json { "type": "object", "properties": { "agent_id": { "type": "string", "description": "The agent id of your direct continuable child, or your direct parent when you are a resident continuable child." }, "message": { "type": "string", "description": "The message to deliver to the agent." } }, "required": [ "agent_id", "message" ] } ``` 来源：[`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts) 这些是控制可继续后台 subagent 的全局命名工具：绑定提供方的 `tool-subagent` 实例注册不同的委派工具；本包注册一次 `send_message` 和 `interrupt_agent`，另由 `list_agents` 通过单独加载的 `/list-agents` 插件提供，其目录行使用 sessionProjections 和实时 Agent 注册表。 ## `@deepseek-ai/dsh-tool-jobs` ### `job_kill` 根据 job id 请求取消正在运行的后台任务。此调用立即返回；任务的工作真正停止后，会以 killed 状态结算。 ```json { "type": "object", "properties": { "job_id": { "type": "string", "description": "Job id returned by the tool that started the background work." }, "reason": { "type": "string", "description": "Optional short reason, recorded in the log and forwarded to the job." } }, "required": [ "job_id" ] } ``` 来源：[`packages/jobs/tool-jobs/src/index.ts`](../packages/jobs/tool-jobs/src/index.ts) ### `job_list` 列出你的后台任务（包括正在运行和已完成的任务）及其 id、种类和状态。 ```json { "type": "object", "properties": {} } ``` 来源：[`packages/jobs/tool-jobs/src/index.ts`](../packages/jobs/tool-jobs/src/index.ts) ### `job_output` 读取后台任务。流式任务只返回自上次读取以来的输出；最终输出任务会在结算后返回结果。每个响应都以 `[status: ...]` 结尾。读取默认不阻塞；设置 `wait: true` 后，最长等待到配置的上限。 ```json { "type": "object", "properties": { "job_id": { "type": "string", "description": "Job id returned by the tool that started the background work." }, "wait": { "type": "boolean", "description": "Block until the job reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the job alive." }, "timeout_ms": { "type": "number", "description": "Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum." } }, "required": [ "job_id" ] } ``` 来源：[`packages/jobs/tool-jobs/src/index.ts`](../packages/jobs/tool-jobs/src/index.ts) 与任务种类无关的后台任务控制器：后台 bash 命令、PTY 发送和 subagent 都通过相同的 3 个工具读取、列出和终止。加载该插件会挂接控制器，从而启用生产方的 `ctx.jobs.start()`。 ## `@deepseek-ai/dsh-experimental-tool-agent-team` ### `followup_task` 向另一名 Team member 发送持久 follow-up task，并在需要时启动一个 turn。 ```json { "type": "object", "properties": { "target": { "type": "string", "description": "Team member name, or lead." }, "message": { "type": "string", "description": "Self-contained message for the target." } }, "required": [ "target", "message" ] } ``` 来源：[`packages/experimental/tool-agent-team/src/index.ts`](../packages/experimental/tool-agent-team/src/index.ts) ### `interrupt_agent` 中断一名 teammate 的当前 turn，同时保留其待处理 inbox。仅 Team Lead 可用。 ```json { "type": "object", "properties": { "target": { "type": "string", "description": "Teammate name." } }, "required": [ "target" ] } ``` 来源：[`packages/experimental/tool-agent-team/src/index.ts`](../packages/experimental/tool-agent-team/src/index.ts) ### `list_agents` 列出 Lead 与所有持久 teammate，以及各自当前的运行时状态。 ```json { "type": "object", "properties": {} } ``` 来源：[`packages/experimental/tool-agent-team/src/index.ts`](../packages/experimental/tool-agent-team/src/index.ts) ### `send_message` 向另一名 Team member 发送持久信息，但不启动 idle member。 ```json { "type": "object", "properties": { "target": { "type": "string", "description": "Team member name, or lead." }, "message": { "type": "string", "description": "Self-contained message for the target." } }, "required": [ "target", "message" ] } ``` 来源：[`packages/experimental/tool-agent-team/src/index.ts`](../packages/experimental/tool-agent-team/src/index.ts) ### `spawn_teammate` 创建一名具名、持久的 teammate。只有 Team Lead 可以调用此工具。 ```json { "type": "object", "properties": { "name": { "type": "string", "description": "Unique lower-kebab-case teammate name." }, "description": { "type": "string", "description": "Short description of the delegated responsibility." }, "prompt": { "type": "string", "description": "Complete initial task for the teammate." }, "context": { "type": "string", "description": "fresh starts without Lead history; fork inherits completed Lead turns. Defaults to fresh.", "enum": [ "fresh", "fork" ] } }, "required": [ "name", "description", "prompt" ] } ``` 来源：[`packages/experimental/tool-agent-team/src/index.ts`](../packages/experimental/tool-agent-team/src/index.ts) ### `team_task_create` 在共享 Team 任务板上创建一个无 owner 的 pending task。 ```json { "type": "object", "properties": { "subject": { "type": "string", "description": "Concise task title." }, "description": { "type": "string", "description": "Complete task details and acceptance criteria." }, "blocked_by": { "type": "array", "description": "Task ids that must complete first.", "items": { "type": "string" } }, "write_scopes": { "type": "array", "description": "Advisory workspace-relative file or directory prefixes this task expects to modify.", "items": { "type": "string" } } }, "required": [ "subject", "description" ] } ``` 来源：[`packages/experimental/tool-agent-team/src/index.ts`](../packages/experimental/tool-agent-team/src/index.ts) ### `team_task_get` 在修改或执行共享任务前，读取其完整的最新值。 ```json { "type": "object", "properties": { "task_id": { "type": "string", "description": "Shared task id." } }, "required": [ "task_id" ] } ``` 来源：[`packages/experimental/tool-agent-team/src/index.ts`](../packages/experimental/tool-agent-team/src/index.ts) ### `team_task_list` 列出共享任务，包括 readiness、owner、revision、blocker 与 write-scope warning。 ```json { "type": "object", "properties": { "status": { "type": "string", "description": "Optional exact status filter.", "enum": [ "pending", "in_progress", "completed" ] }, "owner": { "type": "string", "description": "Optional member-name filter; use unowned for tasks without an owner." }, "ready": { "type": "boolean", "description": "Optional readiness filter." }, "cursor": { "type": "integer", "description": "Zero-based result offset. Defaults to 0." }, "limit": { "type": "integer", "description": "Number of rows, 1 through 100. Defaults to 50." } } } ``` 来源：[`packages/experimental/tool-agent-team/src/index.ts`](../packages/experimental/tool-agent-team/src/index.ts) ### `team_task_update` 使用 team_task_get 或 team_task_list 返回的最新 revision，对共享任务操作执行 compare-and-set。 ```json { "type": "object", "properties": { "task_id": { "type": "string", "description": "Shared task id." }, "expected_revision": { "type": "integer", "description": "Current task revision used as the CAS precondition." }, "action": { "type": "string", "description": "Task transition to apply.", "enum": [ "claim", "release", "edit", "set_dependencies", "complete", "reopen", "reassign", "delete" ] }, "subject": { "type": "string", "description": "Replacement title for edit." }, "description": { "type": "string", "description": "Replacement details for edit." }, "blocked_by": { "type": "array", "description": "Complete blocker list for set_dependencies.", "items": { "type": "string" } }, "write_scopes": { "type": "array", "description": "Replacement advisory write scopes for edit.", "items": { "type": "string" } }, "owner": { "type": "string", "description": "Member name for Lead-only reassign; omit to unassign." } }, "required": [ "task_id", "expected_revision", "action" ] } ``` 来源：[`packages/experimental/tool-agent-team/src/index.ts`](../packages/experimental/tool-agent-team/src/index.ts) ### `wait_agent` 等待本次调用开始后下一次 teammate 状态、mailbox 或共享任务变更。它绝不会唤醒 inactive member；若没有其他 member 正在 running 或 provisioning，则立即返回 noProgress。唤醒或超时后应重新列出状态，而不是轮询。 ```json { "type": "object", "properties": { "timeout_ms": { "type": "integer", "description": "Wait duration in milliseconds, from 10000 through 3600000. Defaults to 30000." } } } ``` 来源：[`packages/experimental/tool-agent-team/src/index.ts`](../packages/experimental/tool-agent-team/src/index.ts) 这 10 个工具限定于隐式 Team Lead 与持久 teammate 作用域。随产品发布的 dsh-base bundle 默认禁用该包；文档中的 Agent Teams profile patch 会启用它，并禁用旧 continuable child 的同名控制工具。 ## `@deepseek-ai/dsh-tool-todo` ### `todo_write` 记录并更新当前工作的结构化任务列表。每次调用都要发送**完整列表**，它会**替换**之前的列表，不支持局部更新或逐项编辑。请用它规划多步骤工作并展示进度：开始前为每个具体步骤添加一项 todo。将当前正在处理的每项 todo 标记为 `in_progress`；确实并行运行时（例如并发 subagent 或后台命令）可同时标记多项，顺序工作则标记 1 项。只要工作尚未完成，就应至少有一项任务为 `in_progress`。某项 todo 完成后立即标记为 `completed`，不要批量标记完成；只有全部工作完成后，才可以没有 `in_progress` 项。简单的单步骤任务无需使用列表。状态：`pending`（未开始）、`in_progress`（正在处理）、`completed`（已完成）。 ```json { "type": "object", "properties": { "todos": { "type": "array", "description": "The COMPLETE task list, replacing any previous list.", "items": { "type": "object", "additionalProperties": false, "properties": { "content": { "type": "string", "description": "What the task is — a short imperative line." }, "status": { "type": "string", "description": "pending (not started) | in_progress (now) | completed (done).", "enum": [ "pending", "in_progress", "completed" ] } }, "required": [ "content", "status" ] } } }, "required": [ "todos" ] } ``` 来源：[`packages/todo/tool-todo/src/index.ts`](../packages/todo/tool-todo/src/index.ts) todo_write 是会话所有的状态；UI 将最新的 todo/write 事件渲染为检查清单。`allowParallelInProgress` 是没有默认值的必填项，因此本目录明确选择 `true`，对应描述允许同时存在多个 `in_progress` 项。选择 `false` 的部署会获得同一工具，但描述会要求只能有 1 个活动任务。 ## `@deepseek-ai/dsh-tool-workflow` ### `workflow` 运行用于大规模编排 subagent 的 JavaScript 工作流脚本。当工作会分散到许多相互独立的部分时，请使用此工具，例如审查大量文件、执行迁移、开展多角度研究或对发现进行对抗式验证；此时应将编排写成脚本，而不是逐轮委派。 工作流的身份通过 `meta` 参数以 JSON 形式传入：必填的 `name`（简短 kebab-case）和 `description` 字符串，以及可选的 `whenToUse` 字符串和 `phases` 数组（`{title, detail?, provider?, model?}`）。`script` 参数只能是纯 JavaScript **函数体**，不能是 TypeScript，也不能包含 `export const meta` 语句；meta 是参数而非代码。脚本支持顶层 await；请以 `return ` 结尾，该值必须可以 JSON 序列化，并作为此工具的结果。 脚本函数体提供以下钩子： - `agent(prompt, opts?): Promise`：运行一个 subagent 直至完成。不提供 `opts.schema` 时，解析为子级最终文本；提供 `opts.schema` 时，它必须是以对象为根、且**只能**使用 type/properties/required/additionalProperties/items/enum/const/oneOf 的 JSON Schema，不支持 pattern/format/数值边界，此时解析为通过校验的对象。子级失败时解析为 `null`，可使用 `.filter(Boolean)` 过滤。其他选项包括 `label`（显示名称）、`phase`（进度组），以及相互独立的 `provider`／`model` LLM（大语言模型）目标覆盖项，两者可单独提供。其他任何选项（`effort`／`isolation`／`agentType`）都会明确报错。 - `pipeline(items, ...stages): Promise`：让每个条目分别经过各阶段，阶段之间**没有**屏障；多阶段工作优先使用它。每个阶段接收 `(prev, item, index)`。普通的阶段异常会将该**条目**变为 `null`，并跳过它的剩余阶段。 - `parallel(thunks): Promise`：并发运行零参数函数并等待**全部**完成。它会形成屏障，仅当某个阶段确实需要汇总全部先前结果时使用。抛出异常的 thunk 解析为 `null`。 - `phase(title)`：开始一个进度阶段；`log(message)`：说明进度；`args`：工具调用的 `args` 输入，原样提供。 如果误用钩子（参数错误、未知选项、不受支持的 schema、触发上限），抛出的错误**总会**终止脚本，绝不会退化为单个条目的 `null`。 约束：并发上限和 agent 总数上限均会生效；不提供文件系统、网络、定时器或 Node.js API。具体工作由 agent 完成，脚本只负责编排。该运行在前台执行：整个脚本完成后，调用才会返回。 ```json { "type": "object", "properties": { "script": { "type": "string", "description": "The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `)." }, "meta": { "type": "object", "description": "The workflow identity block (plain JSON — never code).", "additionalProperties": true, "properties": { "name": { "type": "string", "description": "Short kebab-case workflow name." }, "description": { "type": "string", "description": "One-line description of what the workflow does." }, "whenToUse": { "type": "string", "description": "Optional guidance on when this workflow applies." }, "phases": { "type": "array", "description": "Optional phase declarations matched by phase() calls.", "items": { "type": "object", "additionalProperties": true, "properties": { "title": { "type": "string", "description": "The phase title phase() calls match by exact string." }, "detail": { "type": "string", "description": "Optional one-line description of the phase." }, "provider": { "type": "string", "description": "Optional provider override this phase is expected to use." }, "model": { "type": "string", "description": "Optional model override this phase is expected to use." } }, "required": [ "title" ] } } }, "required": [ "name", "description" ] }, "args": { "type": "object", "description": "Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).", "additionalProperties": true } }, "required": [ "script", "meta" ] } ``` 来源：[`packages/workflow/tool-workflow/src/index.ts`](../packages/workflow/tool-workflow/src/index.ts) ## `@deepseek-ai/dsh-tool-web` ### `web_fetch` 获取指定 HTTP(S) URL 的内容，并将其解码为文本后返回。 ```json { "type": "object", "properties": { "url": { "type": "string", "description": "The HTTP(S) URL to fetch." } }, "required": [ "url" ] } ``` 来源：[`packages/web/tool-web/src/index.ts`](../packages/web/tool-web/src/index.ts) ### `web_search` 在 Web 上搜索最新信息。在必填的 `queries` 数组中提供 1–4 个查询。返回可选的摘要答案和来源 URL 列表。 ```json { "type": "object", "properties": { "queries": { "type": "array", "description": "Required search queries; accepts 1–4 items and merges their results.", "items": { "type": "string" } } }, "required": [ "queries" ] } ``` 来源：[`packages/web/tool-web/src/index.ts`](../packages/web/tool-web/src/index.ts) web_search 和 web_fetch 将提供方选择置于 ctx.web 之后，使模型可见 schema 在更换后端时保持稳定。 # 能力 Seams 与核心服务 [English](capability-seams.md) | 中文 服务可以是核心主干服务、可替换的能力 seam，也可以是组合包／组合点。下图展示了拥有服务声明的包、已知实现包，以及直接消费该服务的包。 ```mermaid flowchart LR pkg_attachment["attachment"] svc_attachments["ctx.attachments
Durable binary attachment storage"] pkg_attachment_local["attachment-local"] pkg_api_session_controller["api-session-controller"] pkg_tool_fs["tool-fs"] pkg_llm_pi_ai["llm-pi-ai"] pkg_llm_deepseek["llm-deepseek"] pkg_llm["llm"] svc_llm["ctx.llm
LLM adapter registry"] pkg_llm_replay["llm-replay"] pkg_agent_loop["agent-loop"] pkg_compaction_basic["compaction-basic"] pkg_deepseek_llm_api_extensions["deepseek-llm-api-extensions"] svc_deepseekLlmApiExtensions["ctx.deepseekLlmApiExtensions
Official DeepSeek request extensions"] pkg_session_log_deepseek["session-log-deepseek"] pkg_plugin_package_inventory_deepseek["plugin-package-inventory-deepseek"] pkg_token_meter["token-meter"] svc_tokenMeter["ctx.tokenMeter
Replay token measurement"] pkg_compaction_tool_result_pruner["compaction-tool-result-pruner"] svc_toolResultPruner["ctx.toolResultPruner
Model-free tool-result pruning"] pkg_session["session"] svc_sessions["ctx.sessions
In-memory session store"] pkg_agent["agent"] pkg_session_persistence["session-persistence"] pkg_session_query["session-query"] pkg_session_query_sqlite["session-query-sqlite"] pkg_subagent_in_process_driver["subagent-in-process-driver"] pkg_invariants["invariants"] pkg_message_feedback["message-feedback"] svc_sessionController["ctx.sessionController
Host Session Remote controller"] svc_sessionFileReferences["ctx.sessionFileReferences
Session-addressed file-reference Remote adapter"] svc_sessionSkillCatalog["ctx.sessionSkillCatalog
Session-addressed skill Remote adapter"] pkg_api_settings_controller["api-settings-controller"] svc_credentialsController["ctx.credentialsController
Host credential-surface Remote controller"] svc_settingsController["ctx.settingsController
Host settings-surface Remote controller"] pkg_api_workspace_controller["api-workspace-controller"] svc_workspaceController["ctx.workspaceController
Host Workspace Remote controller"] svc_directoryPickerController["ctx.directoryPickerController
Host directory-picking Remote controller"] svc_invariants["ctx.invariants
Package-owned invariant registry"] pkg_scope["scope"] pkg_typert_registry["typert-registry"] svc_typert["ctx.typert
Runtime type registry"] pkg_typert_loader["typert-loader"] pkg_api_gateway["api-gateway"] svc_typertGateway["ctx.typertGateway
Typert Host invocation gateway"] svc_sessionPersistence["ctx.sessionPersistence
Durable session persistence seam"] pkg_session_persistence_jsonl["session-persistence-jsonl"] pkg_tool_bash["tool-bash"] pkg_hooks_claude_code["hooks-claude-code"] pkg_hooks_codex["hooks-codex"] pkg_settings["settings"] svc_settings["ctx.settings
User-settings seam"] pkg_settings_file["settings-file"] pkg_tool_subagent["tool-subagent"] svc_subagentModelSelection["ctx.subagentModelSelection
Subagent model-selection preference"] pkg_credentials["credentials"] svc_credentials["ctx.credentials
Credential seam"] pkg_credentials_local["credentials-local"] pkg_authorization["authorization"] svc_authorization["ctx.authorization
Authorization flow registry"] pkg_session_telemetry["session-telemetry"] svc_sessionTelemetry["ctx.sessionTelemetry
Session telemetry seam"] pkg_session_telemetry_otel["session-telemetry-otel"] pkg_storage["storage"] svc_storage["ctx.storage
Non-session storage hub"] pkg_storage_json["storage-json"] pkg_storage_sqlite["storage-sqlite"] pkg_storage_domain["storage-domain"] svc_storageDomain["ctx.storageDomain
Domain data facility"] pkg_workspace["workspace"] svc_messageFeedback["ctx.messageFeedback
Lifecycle-bound message feedback"] svc_workspaceRegistry["ctx.workspaceRegistry
Workspace entity registry"] svc_sessionQuery["ctx.sessionQuery
Session reads, traces, filters, and search"] pkg_session_reference["session-reference"] pkg_tool_session_query["tool-session-query"] pkg_file_reference["file-reference"] svc_fileReferences["ctx.fileReferences
File reference discovery"] pkg_file_reference_local["file-reference-local"] svc_sessionReferenceResolver["ctx.sessionReferenceResolver
Cross-session snapshot preparation"] pkg_session_title["session-title"] svc_sessionTitle["ctx.sessionTitle
Log-backed session titles"] pkg_session_title_first_prompt_llm["session-title-first-prompt-llm"] pkg_session_title_all_prompts_llm["session-title-all-prompts-llm"] pkg_system_prompt["system-prompt"] svc_systemPrompt["ctx.systemPrompt
System prompt assembly registry"] pkg_tools["tools"] pkg_tool_terminal["tool-terminal"] pkg_tool_web["tool-web"] svc_tools["ctx.tools
Tool registry and guarded execution pipeline"] pkg_tool_ask_user["tool-ask-user"] pkg_tool_cordis["tool-cordis"] pkg_tool_skill["tool-skill"] pkg_tool_todo["tool-todo"] pkg_user_questions["user-questions"] svc_userQuestions["ctx.userQuestions
Human question/answer seam"] pkg_plan_mode["plan-mode"] svc_planMode["ctx.planMode
Plan collaboration state"] pkg_agent_presets["agent-presets"] svc_agentPresets["ctx.agentPresets
Per-session agent composition"] pkg_commands["commands"] svc_commands["ctx.commands
Human command registry"] pkg_session_projection["session-projection"] svc_sessionProjections["ctx.sessionProjections
Session projection units"] pkg_session_projection_cache["session-projection-cache"] svc_sessionProjectionCache["ctx.sessionProjectionCache
Persisted projection cache"] pkg_subagent["subagent"] pkg_skill["skill"] svc_skills["ctx.skills
Skill provider registry"] pkg_skill_badge["skill-badge"] pkg_skill_filesystem["skill-filesystem"] svc_agents["ctx.agents
Agent service"] pkg_acp["acp"] pkg_agent_default_model["agent-default-model"] svc_agentDefaultModel["ctx.agentDefaultModel
Default Agent model selection"] pkg_headless["headless"] svc_agentLoop["ctx.agentLoop
Concrete loop driver"] pkg_base["base"] pkg_sdk_minimal["sdk-minimal"] pkg_goal["goal"] svc_goals["ctx.goals
Same-session goal domain"] pkg_e2b["e2b"] svc_e2b["ctx.e2b
E2B sandbox lifecycle owner"] pkg_fs_e2b["fs-e2b"] pkg_subprocess_e2b["subprocess-e2b"] pkg_subprocess["subprocess"] svc_subprocess["ctx.subprocess
Subprocess seam"] pkg_subprocess_local["subprocess-local"] pkg_bash_local["bash-local"] pkg_bash_sandbox["bash-sandbox"] pkg_terminal_bash["terminal-bash"] pkg_lsp_stdio["lsp-stdio"] pkg_subagent_acp["subagent-acp"] pkg_subagent_codex["subagent-codex"] pkg_subagent_claude_code["subagent-claude-code"] pkg_shell["shell"] svc_shell["ctx.shell
Bash executor seam"] pkg_pwsh_local["pwsh-local"] pkg_tool_pwsh["tool-pwsh"] pkg_shell_env["shell-env"] svc_shellEnv["ctx.shellEnv
Managed bash environment registry"] pkg_terminal["terminal"] svc_terminals["ctx.terminals
Persistent PTY session registry"] pkg_sandbox["sandbox"] svc_sandbox["ctx.sandbox
Process-sandbox seam"] pkg_sandbox_local["sandbox-local"] pkg_sandbox_policy["sandbox-policy"] svc_sandboxPolicy["ctx.sandboxPolicy
Sandbox policy home"] pkg_fs_sandbox["fs-sandbox"] pkg_user_approval["user-approval"] svc_approval["ctx.approval
Approval seam"] pkg_permission_presets["permission-presets"] svc_permissionPresets["ctx.permissionPresets
Permission presets"] pkg_code_runtime["code-runtime"] svc_codeRuntime["ctx.codeRuntime
Code-execution seam"] pkg_code_runtime_worker_thread["code-runtime-worker-thread"] pkg_experimental_code_runtime_python["experimental-code-runtime-python"] pkg_fs["fs"] svc_fs["ctx.fs
Filesystem provider seam"] pkg_fs_local["fs-local"] pkg_fs_observation_policy["fs-observation-policy"] pkg_compaction["compaction"] svc_compaction["ctx.compaction
Compaction seam"] svc_subagents["ctx.subagents
Subagent provider and continuation service"] pkg_subagent_spawn_in_process["subagent-spawn-in-process"] pkg_subagent_fork_in_process["subagent-fork-in-process"] pkg_subagent_dsh_sdk["subagent-dsh-sdk"] pkg_tool_subagent_control["tool-subagent-control"] pkg_tool_ralph["tool-ralph"] pkg_experimental_agent_team["experimental-agent-team"] svc_agentTeams["ctx.agentTeams
Agent Teams coordination domain"] pkg_experimental_tool_agent_team["experimental-tool-agent-team"] pkg_experimental_client_ui_agent_team["experimental-client-ui-agent-team"] pkg_inspector["inspector"] svc_inspector["ctx.inspector
Cross-realm runtime inspection"] pkg_jobs["jobs"] svc_jobs["ctx.jobs
Background job registry"] pkg_jobs_local["jobs-local"] pkg_tool_jobs["tool-jobs"] pkg_web["web"] svc_web["ctx.web
Web access provider registry"] pkg_web_search_exa["web-search-exa"] pkg_web_search_perplexity["web-search-perplexity"] pkg_web_search_deepseek["web-search-deepseek"] pkg_web_fetch_http["web-fetch-http"] pkg_spill["spill"] svc_spillStore["ctx.spillStore
Spill storage seam"] pkg_spill_local["spill-local"] pkg_spill_policy["spill-policy"] pkg_host_directory_picker["host-directory-picker"] svc_directoryPicker["ctx.directoryPicker
Workspace-directory picking seam"] pkg_host_directory_picker_native["host-directory-picker-native"] pkg_host_directory_picker_browse["host-directory-picker-browse"] pkg_host_webserver["host-webserver"] svc_webServer["ctx.webServer
HTTP route registration"] pkg_client_connection["client-connection"] pkg_client_modules["client-modules"] pkg_client_hmr["client-hmr"] svc_clientModules["ctx.clientModules
Client plugin graph host"] pkg_workflow["workflow"] svc_workflowEngine["ctx.workflowEngine
Workflow script engine"] pkg_workflow_worker_thread["workflow-worker-thread"] pkg_tool_workflow["tool-workflow"] pkg_webhook["webhook"] svc_webhookRuntime["ctx.webhookRuntime
Webhook rule runtime"] pkg_webhook_github["webhook-github"] pkg_lsp["lsp"] svc_lsp["ctx.lsp
Language-server navigation seam"] pkg_tool_lsp["tool-lsp"] pkg_cordis_host_runner["cordis-host-runner"] svc_dynamicCordisRunner["ctx.dynamicCordisRunner
Dynamic Cordis package host runner"] svc_cordisInspect["ctx.cordisInspect
Dynamic Cordis inspect registry"] pkg_agent --> svc_agents pkg_agent_default_model --> svc_agentDefaultModel pkg_agent_loop --> svc_agentLoop pkg_agent_presets --> svc_agentPresets pkg_api_gateway --> svc_typertGateway pkg_api_session_controller --> svc_sessionController pkg_api_session_controller --> svc_sessionFileReferences pkg_api_session_controller --> svc_sessionSkillCatalog pkg_api_settings_controller --> svc_credentialsController pkg_api_settings_controller --> svc_settingsController pkg_api_workspace_controller --> svc_directoryPickerController pkg_api_workspace_controller --> svc_workspaceController pkg_attachment --> svc_attachments pkg_attachment_local --> svc_attachments pkg_authorization --> svc_authorization pkg_bash_local --> svc_shell pkg_bash_sandbox --> svc_shell pkg_client_modules --> svc_clientModules pkg_code_runtime --> svc_codeRuntime pkg_code_runtime_worker_thread --> svc_codeRuntime pkg_commands --> svc_commands pkg_compaction --> svc_compaction pkg_compaction_basic --> svc_compaction pkg_compaction_tool_result_pruner --> svc_toolResultPruner pkg_cordis_host_runner --> svc_cordisInspect pkg_cordis_host_runner --> svc_dynamicCordisRunner pkg_credentials --> svc_credentials pkg_credentials_local --> svc_credentials pkg_deepseek_llm_api_extensions --> svc_deepseekLlmApiExtensions pkg_e2b --> svc_e2b pkg_experimental_agent_team --> svc_agentTeams pkg_experimental_code_runtime_python --> svc_codeRuntime pkg_file_reference --> svc_fileReferences pkg_file_reference_local --> svc_fileReferences pkg_fs --> svc_fs pkg_fs_e2b --> svc_fs pkg_fs_local --> svc_fs pkg_fs_sandbox --> svc_fs pkg_goal --> svc_goals pkg_host_directory_picker --> svc_directoryPicker pkg_host_directory_picker_browse --> svc_directoryPicker pkg_host_directory_picker_native --> svc_directoryPicker pkg_host_webserver --> svc_webServer pkg_inspector --> svc_inspector pkg_invariants --> svc_invariants pkg_jobs --> svc_jobs pkg_jobs_local --> svc_jobs pkg_llm --> svc_llm pkg_llm_deepseek --> svc_llm pkg_llm_pi_ai --> svc_llm pkg_llm_replay --> svc_llm pkg_lsp --> svc_lsp pkg_lsp_stdio --> svc_lsp pkg_message_feedback --> svc_messageFeedback pkg_permission_presets --> svc_permissionPresets pkg_plan_mode --> svc_planMode pkg_plugin_package_inventory_deepseek --> svc_deepseekLlmApiExtensions pkg_pwsh_local --> svc_shell pkg_sandbox --> svc_sandbox pkg_sandbox_local --> svc_sandbox pkg_sandbox_policy --> svc_sandboxPolicy pkg_session --> svc_sessions pkg_session_log_deepseek --> svc_deepseekLlmApiExtensions pkg_session_persistence --> svc_sessionPersistence pkg_session_persistence_jsonl --> svc_sessionPersistence pkg_session_projection --> svc_sessionProjections pkg_session_projection_cache --> svc_sessionProjectionCache pkg_session_query --> svc_sessionQuery pkg_session_query_sqlite --> svc_sessionQuery pkg_session_reference --> svc_sessionReferenceResolver pkg_session_telemetry --> svc_sessionTelemetry pkg_session_telemetry_otel --> svc_sessionTelemetry pkg_session_title --> svc_sessionTitle pkg_session_title_all_prompts_llm --> svc_sessionTitle pkg_session_title_first_prompt_llm --> svc_sessionTitle pkg_settings --> svc_settings pkg_settings_file --> svc_settings pkg_shell --> svc_shell pkg_shell_env --> svc_shellEnv pkg_skill --> svc_skills pkg_skill_badge --> svc_skills pkg_skill_filesystem --> svc_skills pkg_spill --> svc_spillStore pkg_spill_local --> svc_spillStore pkg_storage --> svc_storage pkg_storage_domain --> svc_storageDomain pkg_storage_json --> svc_storage pkg_storage_sqlite --> svc_storage pkg_subagent --> svc_subagents pkg_subagent_acp --> svc_subagents pkg_subagent_claude_code --> svc_subagents pkg_subagent_codex --> svc_subagents pkg_subagent_dsh_sdk --> svc_subagents pkg_subagent_fork_in_process --> svc_subagents pkg_subagent_spawn_in_process --> svc_subagents pkg_subprocess --> svc_subprocess pkg_subprocess_e2b --> svc_subprocess pkg_subprocess_local --> svc_subprocess pkg_system_prompt --> svc_systemPrompt pkg_terminal --> svc_terminals pkg_terminal_bash --> svc_terminals pkg_token_meter --> svc_tokenMeter pkg_tool_subagent --> svc_subagentModelSelection pkg_tools --> svc_tools pkg_typert_registry --> svc_typert pkg_user_approval --> svc_approval pkg_user_questions --> svc_userQuestions pkg_web --> svc_web pkg_web_fetch_http --> svc_web pkg_web_search_deepseek --> svc_web pkg_web_search_exa --> svc_web pkg_web_search_perplexity --> svc_web pkg_webhook --> svc_webhookRuntime pkg_workflow --> svc_workflowEngine pkg_workflow_worker_thread --> svc_workflowEngine pkg_workspace --> svc_workspaceRegistry svc_agentDefaultModel --> pkg_api_session_controller svc_agentDefaultModel --> pkg_headless svc_agentLoop --> pkg_base svc_agentLoop --> pkg_sdk_minimal svc_agentTeams --> pkg_experimental_client_ui_agent_team svc_agentTeams --> pkg_experimental_tool_agent_team svc_agents --> pkg_acp svc_agents --> pkg_agent_loop svc_agents --> pkg_subagent_in_process_driver svc_approval --> pkg_acp svc_approval --> pkg_tool_bash svc_approval --> pkg_tools svc_attachments --> pkg_api_session_controller svc_attachments --> pkg_llm_deepseek svc_attachments --> pkg_llm_pi_ai svc_attachments --> pkg_tool_fs svc_authorization --> pkg_llm_pi_ai svc_clientModules --> pkg_client_hmr svc_codeRuntime --> pkg_tools svc_compaction --> pkg_compaction_basic svc_cordisInspect --> pkg_tool_cordis svc_credentials --> pkg_api_settings_controller svc_credentials --> pkg_llm_deepseek svc_credentials --> pkg_llm_pi_ai svc_deepseekLlmApiExtensions --> pkg_llm_deepseek svc_directoryPicker --> pkg_api_workspace_controller svc_dynamicCordisRunner --> pkg_tool_cordis svc_e2b --> pkg_fs_e2b svc_e2b --> pkg_subprocess_e2b svc_fileReferences --> pkg_api_session_controller svc_fs --> pkg_tool_fs svc_invariants --> pkg_agent svc_invariants --> pkg_agent_loop svc_invariants --> pkg_scope svc_invariants --> pkg_session svc_jobs --> pkg_tool_bash svc_jobs --> pkg_tool_jobs svc_jobs --> pkg_tool_subagent svc_jobs --> pkg_tool_terminal svc_llm --> pkg_agent_loop svc_llm --> pkg_compaction_basic svc_lsp --> pkg_tool_lsp svc_sandbox --> pkg_bash_sandbox svc_sandbox --> pkg_terminal_bash svc_sandboxPolicy --> pkg_bash_sandbox svc_sandboxPolicy --> pkg_fs_sandbox svc_sandboxPolicy --> pkg_terminal_bash svc_sessionPersistence --> pkg_agent_loop svc_sessionPersistence --> pkg_hooks_claude_code svc_sessionPersistence --> pkg_hooks_codex svc_sessionPersistence --> pkg_message_feedback svc_sessionPersistence --> pkg_session_query svc_sessionPersistence --> pkg_session_query_sqlite svc_sessionPersistence --> pkg_tool_bash svc_sessionProjectionCache --> pkg_api_session_controller svc_sessionProjectionCache --> pkg_session_query svc_sessionProjectionCache --> pkg_session_reference svc_sessionProjectionCache --> pkg_subagent svc_sessionProjections --> pkg_api_session_controller svc_sessionProjections --> pkg_session_title svc_sessionProjections --> pkg_tool_todo svc_sessionQuery --> pkg_session_reference svc_sessionQuery --> pkg_tool_session_query svc_sessions --> pkg_agent svc_sessions --> pkg_agent_loop svc_sessions --> pkg_invariants svc_sessions --> pkg_message_feedback svc_sessions --> pkg_session_persistence svc_sessions --> pkg_session_query svc_sessions --> pkg_session_query_sqlite svc_sessions --> pkg_subagent_in_process_driver svc_settings --> pkg_api_settings_controller svc_settings --> pkg_llm_deepseek svc_settings --> pkg_llm_pi_ai svc_shell --> pkg_hooks_claude_code svc_shell --> pkg_hooks_codex svc_shell --> pkg_tool_bash svc_shell --> pkg_tool_pwsh svc_shellEnv --> pkg_tool_bash svc_shellEnv --> pkg_tool_pwsh svc_skills --> pkg_tool_skill svc_spillStore --> pkg_spill_policy svc_storage --> pkg_storage_domain svc_storageDomain --> pkg_message_feedback svc_storageDomain --> pkg_workspace svc_subagentModelSelection --> pkg_tool_subagent svc_subagents --> pkg_tool_ralph svc_subagents --> pkg_tool_subagent svc_subagents --> pkg_tool_subagent_control svc_subprocess --> pkg_bash_local svc_subprocess --> pkg_bash_sandbox svc_subprocess --> pkg_lsp_stdio svc_subprocess --> pkg_subagent_acp svc_subprocess --> pkg_subagent_claude_code svc_subprocess --> pkg_subagent_codex svc_subprocess --> pkg_terminal_bash svc_systemPrompt --> pkg_agent_loop svc_systemPrompt --> pkg_tool_fs svc_systemPrompt --> pkg_tool_terminal svc_systemPrompt --> pkg_tool_web svc_systemPrompt --> pkg_tools svc_terminals --> pkg_tool_terminal svc_tokenMeter --> pkg_compaction_basic svc_toolResultPruner --> pkg_compaction_basic svc_tools --> pkg_agent_loop svc_tools --> pkg_tool_ask_user svc_tools --> pkg_tool_bash svc_tools --> pkg_tool_cordis svc_tools --> pkg_tool_fs svc_tools --> pkg_tool_skill svc_tools --> pkg_tool_subagent svc_tools --> pkg_tool_terminal svc_tools --> pkg_tool_todo svc_tools --> pkg_tool_web svc_typert --> pkg_api_gateway svc_typert --> pkg_typert_loader svc_userQuestions --> pkg_tool_ask_user svc_web --> pkg_tool_web svc_webServer --> pkg_client_connection svc_webServer --> pkg_client_hmr svc_webServer --> pkg_client_modules svc_webhookRuntime --> pkg_webhook_github svc_workflowEngine --> pkg_tool_ralph svc_workflowEngine --> pkg_tool_workflow svc_workspaceRegistry --> pkg_api_session_controller svc_workspaceRegistry --> pkg_api_workspace_controller svc_fs -. event gate .-> pkg_fs_observation_policy ``` | ctx 键 | 角色 | 所属包 | 实现 | 直接消费方 | 配套插件 | 说明 | | --- | --- | --- | --- | --- | --- | --- | | `ctx.attachments` | `seam` | [`attachment`](../packages/attachment/attachment) | [`attachment-local`](../packages/attachment/attachment-local) | [`api-session-controller`](../packages/api/session-controller), [`tool-fs`](../packages/fs/tool-fs), [`llm-pi-ai`](../packages/llm/llm-pi-ai), [`llm-deepseek`](../packages/llm/llm-deepseek) | - | 宿主会在会话事件之前提交已接受的图片；提供方适配器将已授权的持久引用解析为提供方原生内容。 | | `ctx.llm` | `seam` | [`llm`](../packages/llm/llm) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), [`llm-replay`](../packages/test-support/llm-replay) | [`agent-loop`](../packages/core/agent-loop), [`compaction-basic`](../packages/compaction/compaction-basic) | - | 适配器注册提供方实现；agent loop（智能体循环）与压缩功能调用提供方无关的流服务。 | | `ctx.deepseekLlmApiExtensions` | `seam` | [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions) | [`session-log-deepseek`](../packages/session/session-log-deepseek), [`plugin-package-inventory-deepseek`](../packages/llm/plugin-package-inventory-deepseek) | [`llm-deepseek`](../packages/llm/llm-deepseek) | - | 插件准备彼此独立的顶层字段；官方适配器会合并这些字段，并在 HTTP 接受后提交其交付状态。 | | `ctx.tokenMeter` | `core` | [`token-meter`](../packages/llm/token-meter) | - | [`compaction-basic`](../packages/compaction/compaction-basic) | - | 拥有按会话隔离的回放折叠区；压力消费方共享不可变且带修订版本的测量结果。 | | `ctx.toolResultPruner` | `core` | [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner) | - | [`compaction-basic`](../packages/compaction/compaction-basic) | - | 在摘要压缩前，通过可回放的单节点表层替换来改写过大的当前工具结果。 | | `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver), [`invariants`](../packages/runtime-diagnostics/invariants), [`message-feedback`](../packages/feedback/message-feedback) | - | 拥有仅追加的 Session 实例，并发出持久的会话事件流。 | | `ctx.sessionController` | `core` | [`api-session-controller`](../packages/api/session-controller) | - | - | - | 负责 Session 命令、冷读取、持久事件跟随、实时控制状态、模型目录、workspace 打开与 Agent 激活策略。 | | `ctx.sessionFileReferences` | `core` | [`api-session-controller`](../packages/api/session-controller) | - | - | - | 通过 Session Controller 的既有 Agent lookup 策略委托文件引用发现。 | | `ctx.sessionSkillCatalog` | `core` | [`api-session-controller`](../packages/api/session-controller) | - | - | - | 在不激活冷 Agent 的前提下列出 Session 组合中允许用户调用的 skill。 | | `ctx.credentialsController` | `core` | [`api-settings-controller`](../packages/api/settings-controller) | - | - | - | 把凭据引用 seam 投影到生成的 Remote namespace：批量扇出、视图投影与拒绝映射都在这里，而不在 seam Definition 上。 | | `ctx.settingsController` | `core` | [`api-settings-controller`](../packages/api/settings-controller) | - | - | - | 把用户设置 seam 投影到生成的 Remote namespace：读取一律脱敏，所有拒绝在这里分类，而不在 seam Definition 上。 | | `ctx.workspaceController` | `core` | [`api-workspace-controller`](../packages/api/workspace-controller) | - | - | - | 通过生成的 Remote namespace 负责 Workspace 命令和可在重连后收敛的 Workspace 状态投递。 | | `ctx.directoryPickerController` | `core` | [`api-workspace-controller`](../packages/api/workspace-controller) | - | - | - | 把选目录 seam 送上线：能力门禁、取消传播，以及浏览器目录流程用于分支判断的 seam 错误码。 | | `ctx.invariants` | `core` | [`invariants`](../packages/runtime-diagnostics/invariants) | - | [`session`](../packages/core/session), [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`agent-loop`](../packages/core/agent-loop) | - | 配套子路径注册所属包本地的检查；该服务负责选择、唯一性、子 fiber，以及标明所属包的失败。 | | `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader), [`api-gateway`](../packages/api/gateway) | - | 插件直接或通过 dsh-typert-loader 注册实时 zod 贡献；API 网关消费调用描述符和提供方，其他运行时消费方则在各自边界查询 schema 与反射元数据。 | | `ctx.typertGateway` | `core` | [`api-gateway`](../packages/api/gateway) | - | - | - | 将生成的 Remote 描述符与实时 Cordis 服务关联，解析已注册的身份，并通过共享的 Connection RPC 载体提供一元调用。 | | `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session/session-persistence) | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl) | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/shell/tool-bash), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`message-feedback`](../packages/feedback/message-feedback) | - | JSONL backend 把 SessionEvent 词汇持久化为每个 Session 一份产物。 | | `ctx.settings` | `seam` | [`settings`](../packages/settings/settings) | [`settings-file`](../packages/settings/settings-file) | [`api-settings-controller`](../packages/api/settings-controller), [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai) | - | 插件注册命名空间 schema 并解析分层值；提供方存储原始文档。LLM（大语言模型）适配器在用户分区下将其入口配置注册为组合基础；settings controller 提供经过脱敏的分层描述符，并写入用户层。 | | `ctx.subagentModelSelection` | `core` | [`tool-subagent`](../packages/subagent/tool-subagent) | - | [`tool-subagent`](../packages/subagent/tool-subagent) | - | 拥有默认关闭的设置命名空间；Agent 作用域的委派工具会在组合新顶层 Session 时读取它。 | | `ctx.credentials` | `seam` | [`credentials`](../packages/credentials/credentials) | [`credentials-local`](../packages/credentials/credentials-local) | [`api-settings-controller`](../packages/api/settings-controller), [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai) | - | 配置携带对机密信息的引用；提供方拥有实际值。消费方按操作解析，因此轮换后的凭据会在紧接着的下一次请求中生效；settings controller 提供不含实际值的视图和只写存储。 | | `ctx.authorization` | `seam` | [`authorization`](../packages/credentials/authorization) | - | [`llm-pi-ai`](../packages/llm/llm-pi-ai) | - | flow 由知道如何取得某份凭据的插件注册，并以其写入的记录为键；seam 拥有这段对话与"每个键同时只跑一次尝试"的生命周期，而非协议本身。 | | `ctx.sessionTelemetry` | `seam` | [`session-telemetry`](../packages/session/session-telemetry) | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | - | - | 该 seam 捕获会话记录、进行脱敏并交给一个后端；没有其他组件消费该服务，其输出会离开当前进程。 | | `ctx.storage` | `seam` | [`storage`](../packages/storage/storage) | [`storage-json`](../packages/storage/storage-json), [`storage-sqlite`](../packages/storage/storage-sqlite) | [`storage-domain`](../packages/storage/storage-domain) | - | 各后端以不同名称并列注册；数据形态（领域优先）挂载到枢纽上，并将类型化操作转换为不透明的 KV 单元原语。 | | `ctx.storageDomain` | `core` | [`storage-domain`](../packages/storage/storage-domain) | - | [`workspace`](../packages/workspace/workspace), [`message-feedback`](../packages/feedback/message-feedback) | - | 等待所有已配置后端就绪，然后将领域形态发布为一个受生命周期约束的服务，用于类型化持久状态。 | | `ctx.messageFeedback` | `core` | [`message-feedback`](../packages/feedback/message-feedback) | - | - | - | 拥有本地逐 assistant 消息反馈、生命周期与目标校验、逐条目 compare-and-set 及 Host 一元 Remote 契约，且不进入 Session 历史或遥测。 | | `ctx.workspaceRegistry` | `core` | [`workspace`](../packages/workspace/workspace) | - | [`api-workspace-controller`](../packages/api/workspace-controller), [`api-session-controller`](../packages/api/session-controller) | - | 通过领域设施拥有带 WorkspaceId 品牌类型的记录；稳定的 sessionIds 账户驱动 Host RPC 与 GUI 投影。 | | `ctx.sessionQuery` | `seam` | [`session-query`](../packages/session-query/session-query) | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | [`session-reference`](../packages/context/session-reference), [`tool-session-query`](../packages/session-query/tool-session-query) | - | 该接口提供精确读取、过滤和追踪；具体后端还提供全文协调、排序、摘要片段和游标世代，而模型消费方负责工作区权限与不含游标的渲染。 | | `ctx.fileReferences` | `seam` | [`file-reference`](../packages/context/file-reference) | [`file-reference-local`](../packages/context/file-reference-local) | [`api-session-controller`](../packages/api/session-controller) | - | 该接口返回 Agent cwd 内仅含路径的补全候选；提供方负责命名空间访问与排序，但不读取文件内容。 | | `ctx.sessionReferenceResolver` | `core` | [`session-reference`](../packages/context/session-reference) | - | - | - | 将当前表层中有界的对话快照投影为持久但不可信的消息上下文；Host 适配器负责提及语法。 | | `ctx.sessionTitle` | `seam` | [`session-title`](../packages/session/session-title) | [`session-title-first-prompt-llm`](../packages/session/session-title-first-prompt-llm), [`session-title-all-prompts-llm`](../packages/session/session-title-all-prompts-llm) | - | - | 负责确定性回退、最新标题折叠区，以及唯一的可选异步提供方注册。 | | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-terminal`](../packages/terminal/tool-terminal), [`tool-web`](../packages/web/tool-web) | - | 为每个步骤收集提示词各部分和面向模型的工具 schema。 | | `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/interaction/tool-ask-user), [`tool-bash`](../packages/shell/tool-bash), [`tool-cordis`](../packages/extensions/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-terminal`](../packages/terminal/tool-terminal), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web) | - | 注册能力，负责 PTC mode 传输，并让调用依次经过策略前处理、单调守卫、环绕分派、策略后处理和最终结果观测。 | | `ctx.userQuestions` | `seam` | [`user-questions`](../packages/interaction/user-questions) | - | [`tool-ask-user`](../packages/interaction/tool-ask-user) | - | UI 前端提供当前生效的人工回答提供方；tool-ask-user 在提供方无关的 ask() promise 上暂停工具调用。 | | `ctx.planMode` | `core` | [`plan-mode`](../packages/plan/plan-mode) | - | - | - | 折叠已记录的计划／模式状态，在轮次边界刷新用户选择，渲染由部署方拥有的指导信息，注册 /plan，并在状态转换期间保持计划退出 schema 稳定。 | | `ctx.agentPresets` | `core` | [`agent-presets`](../packages/preset/agent-presets) | - | - | - | 在受信任根目录与用户创作根目录上发现 preset 目录，并在创建期把一份 preset cordis.yml 挂载到 agent 作用域之下，拒绝始终未激活或向根服务 realm 发布服务的行。 | | `ctx.commands` | `core` | [`commands`](../packages/interaction/commands) | - | - | - | 插件注册直接面向人的命令，而不会把调用发送给模型。 | | `ctx.sessionProjections` | `core` | [`session-projection`](../packages/session/session-projection) | - | [`api-session-controller`](../packages/api/session-controller), [`tool-todo`](../packages/todo/tool-todo), [`session-title`](../packages/session/session-title) | - | 各领域注册由状态驱动的折叠单元；主动驱动过程维护每个会话的水位状态，Session controller 提供 baseline 并推送发生变化的值。 | | `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session/session-projection-cache) | - | [`api-session-controller`](../packages/api/session-controller), [`session-query`](../packages/session-query/session-query), [`session-reference`](../packages/context/session-reference), [`subagent`](../packages/subagent/subagent) | - | 按会话持久保存投影单元状态的检查点（节流检查点，以及轮次／结束／分离时的必选检查点），并提供冷读取阶梯：缓存行加持久化尾部回放，因此列表读取永远不需要加载完整日志。 | | `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-badge`](../packages/skill/skill-badge), [`skill-filesystem`](../packages/skill/skill-filesystem) | [`tool-skill`](../packages/skill/tool-skill) | - | 合并提供方的 skill（技能）目录；tool-skill 渲染会话前缀目录，并加载完整的 skill 正文。 | | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver) | - | 拥有实时 Agent 句柄、创建／恢复工厂 seam，以及进程本地的发起方传播。 | | `ctx.agentDefaultModel` | `core` | [`agent-default-model`](../packages/core/agent-default-model) | - | [`api-session-controller`](../packages/api/session-controller), [`headless`](../packages/bundle/headless) | - | 通过 settings 分层默认 `ModelSelection`，让直接入口与 Host 支撑的 Agent 入口共享同一个状态所有者。 | | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`base`](../packages/bundle/base), [`sdk-minimal`](../packages/bundle/sdk-minimal) | - | 唯一的具体循环插件；扩展包依赖 dsh-agent 的事件和服务，而不依赖此包。 | | `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | 从会话日志折叠带修订版本的目标状态，并将实时延续激活保留在进程本地。 | | `ctx.e2b` | `core` | [`e2b`](../packages/e2b/e2b) | - | [`fs-e2b`](../packages/e2b/fs-e2b), [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | - | 拥有一个共享的 E2B SDK 句柄、远程工作目录和最终沙箱处置，使两个基础 E2B 提供方处于同一个 Linux 运行时中。 | | `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local), [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | [`bash-local`](../packages/shell/bash-local), [`bash-sandbox`](../packages/shell/bash-sandbox), [`terminal-bash`](../packages/terminal/terminal-bash), [`lsp-stdio`](../packages/lsp/lsp-stdio), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | - | Bash 执行器、PTY shell 后端、LSP Host，以及进程外 ACP、Codex 和 Claude Code subagent 后端都通过 ctx.subprocess 执行 spawn；该服务负责进程坐标、进程树／会话生命周期、stdio 处置、终端机制和 kill 升级。 | | `ctx.shell` | `seam` | [`shell`](../packages/shell/shell) | [`bash-local`](../packages/shell/bash-local), [`bash-sandbox`](../packages/shell/bash-sandbox), [`pwsh-local`](../packages/shell/pwsh-local) | [`tool-bash`](../packages/shell/tool-bash), [`tool-pwsh`](../packages/shell/tool-pwsh), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | - | 面向模型的 shell 工具和钩子桥接消费此 seam；沙箱、远程或 PowerShell 执行器可以替换 bash-local，而无需改动这些消费方。 | | `ctx.shellEnv` | `core` | [`shell-env`](../packages/shell/shell-env) | - | [`tool-bash`](../packages/shell/tool-bash), [`tool-pwsh`](../packages/shell/tool-pwsh) | - | 插件声明限定于 effect 作用域的 DSH_* 事实；每个 shell 工具在每次执行时收集一份可信快照，其执行器据此重建命名空间。 | | `ctx.terminals` | `seam` | [`terminal`](../packages/terminal/terminal) | [`terminal-bash`](../packages/terminal/terminal-bash) | [`tool-terminal`](../packages/terminal/tool-terminal) | - | 注册表负责精确到 Agent 的会话身份和清理；后端负责终端机制，tool-terminal 则提供限定于所有者作用域的模型接口。 | | `ctx.sandbox` | `seam` | [`sandbox`](../packages/sandbox/sandbox) | [`sandbox-local`](../packages/sandbox/sandbox-local) | [`bash-sandbox`](../packages/shell/bash-sandbox), [`terminal-bash`](../packages/terminal/terminal-bash) | - | 消费方交出即将执行 spawn 的确切 argv；与宿主共享文件系统和内核的后端按每次调用的策略包装该 argv，并报告强制执行情况。 | | `ctx.sandboxPolicy` | `core` | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | - | [`bash-sandbox`](../packages/shell/bash-sandbox), [`fs-sandbox`](../packages/fs/fs-sandbox), [`terminal-bash`](../packages/terminal/terminal-bash) | - | 统一保存部署默认模式和工作区根目录；只有沙箱执行器和提供方读取该服务（工具层使用它同时导出的纯 `sandbox/mode` 折叠区）。两类强制执行组件都读取该服务，因此 bash 与 fs 不会限制到不同的根目录。 | | `ctx.approval` | `seam` | [`user-approval`](../packages/interaction/user-approval) | - | [`tools`](../packages/core/tools), [`tool-bash`](../packages/shell/tool-bash), [`acp`](../packages/acp/acp) | - | 一次性权限决策通过 `approval/request` waterfall（瀑布式事件）分派；回答方是监听器（即 ACP 为自身 agent 提供的桥接），没有回答方时以 `unavailable` 关闭失败。 | | `ctx.permissionPresets` | `core` | [`permission-presets`](../packages/interaction/permission-presets) | - | - | - | 面向用户的预设表（`workspace-write`／`danger-full-access`），将沙箱模式与审批策略选项组合在一起；一次切换会写入一个 `permission/preset` 事件，并贯通到两个选项事件。 | | `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker-thread`](../packages/code-runtime/code-runtime-worker-thread), [`experimental-code-runtime-python`](../packages/experimental/code-runtime-python) | [`tools`](../packages/core/tools) | - | 使用 Host 提供的异步绑定运行一段由模型编写的程序；各后端采用不同的基础环境和语言（工具注册表在 PTC mode 下消费该服务）。 | | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox), [`fs-e2b`](../packages/e2b/fs-e2b) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) | tool-fs 通过 ctx.fs 执行读取／写入／编辑；fs-sandbox 按共享沙箱模式限制变更；fs-observation-policy 通过 fs/* 事件门禁贡献基于观测状态的检查。 | | `ctx.compaction` | `seam` | [`compaction`](../packages/compaction/compaction) | [`compaction-basic`](../packages/compaction/compaction-basic) | [`compaction-basic`](../packages/compaction/compaction-basic) | - | 基础后端消费步骤后的压力事件和请求错误恢复事件；不存在面向模型的压缩工具。 | | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn-in-process`](../packages/subagent/subagent-spawn-in-process), [`subagent-fork-in-process`](../packages/subagent/subagent-fork-in-process), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/workflow/tool-ralph) | - | 提供方实现传输；该服务还负责可选的、基于 Activation 的延续编排，tool-subagent 选择一次性或可延续委派，tool-subagent-control 传递后续消息，而 tool-ralph 要求一条全新的结构化输出路由。 | | `ctx.agentTeams` | `core` | [`experimental-agent-team`](../packages/experimental/agent-team) | - | [`experimental-tool-agent-team`](../packages/experimental/tool-agent-team), [`experimental-client-ui-agent-team`](../packages/experimental/client-ui-agent-team) | - | 负责隐式 Root roster、持久 peer mailbox、共享任务 DAG、continuable child 生命周期与生成式 Team Remote method；tool-agent-team 提供模型控制工具，client-ui-agent-team 挂载浏览器 contribution。 | | `ctx.inspector` | `core` | `inspector` | - | - | - | 负责 Worker 托管的 CDP target，以及独立于传输的 Host 和 Client observation 与 Cordis tree query API。 | | `ctx.jobs` | `seam` | [`jobs`](../packages/jobs/jobs) | [`jobs-local`](../packages/jobs/jobs-local) | [`tool-bash`](../packages/shell/tool-bash), [`tool-terminal`](../packages/terminal/tool-terminal), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-jobs`](../packages/jobs/tool-jobs) | - | 生产方（后台 bash、PTY 发送和 subagent 委派）登记正在运行的工作；tool-jobs 是面向模型的控制器，用于读取、列出和终止这些工作；jobs-local 是进程本地注册表。 | | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-http`](../packages/web/web-fetch-http) | [`tool-web`](../packages/web/tool-web) | - | 搜索和抓取提供方注册到同一个 ctx.web seam；tool-web 负责稳定的面向模型名称。 | | `ctx.spillStore` | `seam` | [`spill`](../packages/spill/spill) | [`spill-local`](../packages/spill/spill-local) | [`spill-policy`](../packages/spill/spill-policy) | - | 后端保存过大的工具文本，并返回面向模型的定位信息和取回提示；spill-policy 是 tools/post-execute 消费方，负责决定何时 spill。 | | `ctx.directoryPicker` | `seam` | [`host-directory-picker`](../packages/host/directory-picker) | [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | [`api-workspace-controller`](../packages/api/workspace-controller) | - | 带判别标记的交互能力：原生后端在 Host 显示设备上打开一个操作系统选择器，浏览后端为应用内浏览器提供列表与创建原语；双端后端通过其浏览器侧填充 ui-workspace 目录流程的 slot（不通过协议发布）。 | | `ctx.webServer` | `core` | [`host-webserver`](../packages/host/webserver) | - | [`client-connection`](../packages/client/connection), [`client-modules`](../packages/client/modules), [`client-hmr`](../packages/client/hmr) | - | 普通的 node:http 载体：具名路由注册表、索引转换 tap，以及静态 dist 回退；Web 传输插件注册自己的路由。 | | `ctx.clientModules` | `core` | [`client-modules`](../packages/client/modules) | - | [`client-hmr`](../packages/client/hmr) | - | 通过增量 `dsh.client` 扫描组合 __DSH_BOOT__ 入口图，提供插件组合包，并通知重建／图变更订阅方。 | | `ctx.workflowEngine` | `seam` | [`workflow`](../packages/workflow/workflow) | [`workflow-worker-thread`](../packages/workflow/workflow-worker-thread) | [`tool-workflow`](../packages/workflow/tool-workflow), [`tool-ralph`](../packages/workflow/tool-ralph) | - | 每个上下文使用一个引擎，与 bash 相同，且没有具名提供方注册表；通用工作流与固定 Ralph 消费方启动运行，其中的 agent() 调用通过 ctx.subagents 扇出。 | | `ctx.webhookRuntime` | `core` | [`webhook`](../packages/webhook/webhook) | - | [`webhook-github`](../packages/webhook/webhook-github) | - | 提供方适配器分派已认证交付；可信插件注册独立的进程本地规则，runtime 把非 null 结果转换为普通的 Workspace-backed Session，不保留交付或完成状态。 | | `ctx.lsp` | `seam` | [`lsp`](../packages/lsp/lsp) | [`lsp-stdio`](../packages/lsp/lsp-stdio) | [`tool-lsp`](../packages/lsp/tool-lsp) | - | 提供方注册与选择，加上恰好四种操作的标准化查询执行；该 seam 不提供协议逃生口，后端必须转换为标准化请求和结果。 | | `ctx.dynamicCordisRunner` | `core` | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) | - | [`tool-cordis`](../packages/extensions/tool-cordis) | - | 拥有内存定义注册表、Host 半的 vm 沙箱和 request-run 往返流程；浏览器页面通过其 Remote 命名空间在线访问同一服务。 | | `ctx.cordisInspect` | `core` | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) | - | [`tool-cordis`](../packages/extensions/tool-cordis) | - | 注册 Host inspect 提供方、镜像 Client 提供方 manifest，并通过动态 Cordis 传输路由 Client 查询。 | 维护模式：混合模式。服务从 Cordis 声明中发现；接口、实现和消费方角色在 `scripts/gen-doc-graphs.ts` 中分类，并设有完整性守卫。 # 事件生产方与消费方矩阵 [English](event-producer-consumer.md) | 中文 本矩阵展示哪些包会派发各个 harness 自有事件，以及哪些包会监听这些事件。事件之间存在多对多关系，因此密集的关系数据以表格而非一张大型关系图呈现。接收方和事件名称类型还涵盖有意绕过 `ctx.emit` 的内含派发位置，例如 subagent 生命周期封装。 | 事件 | 模式 | 声明位置 | 派发方 | 监听方 | | --- | --- | --- | --- | --- | | `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:239`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - | | `agent-preset/selected` | `emit` | [`packages/preset/agent-presets/src/types.ts:80`](../packages/preset/agent-presets/src/types.ts) | [`agent-presets`](../packages/preset/agent-presets) (`emit`) | `remotes` | | `agent/created` | `emit` | [`packages/core/agent/src/runtime-types.ts:166`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-presets`](../packages/preset/agent-presets), [`file-reference-local`](../packages/context/file-reference-local), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `tool-agent-team`, [`tool-subagent`](../packages/subagent/tool-subagent) | | `agent/disposed` | `emit` | [`packages/core/agent/src/runtime-types.ts:175`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`file-reference-local`](../packages/context/file-reference-local), [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent), `tool-agent-team`, [`tool-subagent`](../packages/subagent/tool-subagent) | | `agent/error` | `emit` | [`packages/core/agent/src/runtime-types.ts:297`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-round-driver`](../packages/goal/goal-round-driver), `session-controller`, [`session-telemetry`](../packages/session/session-telemetry) | | `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/runtime-types.ts:204`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent), [`tool-jobs`](../packages/jobs/tool-jobs) | | `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/runtime-types.ts:212`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent) | | `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/runtime-types.ts:193`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-round-driver`](../packages/goal/goal-round-driver) | | `agent/pre-step` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:238`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent-instructions`](../packages/context/agent-instructions), [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-reference`](../packages/context/session-reference), [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-cordis`](../packages/extensions/tool-cordis), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent) | | `agent/request` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:251`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent), [`webhook`](../packages/webhook/webhook) | | `agent/request-error` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:267`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compaction-basic`](../packages/compaction/compaction-basic), [`llm-retry`](../packages/llm/llm-retry) | | `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:224`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `agent-team`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:185`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` | | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:285`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | | `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:542`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | | `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:522`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | | `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:549`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | | `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:528`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | | `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:535`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` | | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) | | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:81`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` | | `cordis/dynamic-package` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:380`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` | | `cordis/dynamic-retract` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:386`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` | | `cordis/inspect-query` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:392`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` | | `cordis/inspect-query-resolved` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:398`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` | | `cordis/request-run` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:368`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` | | `cordis/request-run-resolved` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:374`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` | | `credentials/record-updated` | `emit` | [`packages/credentials/credentials/src/types.ts:96`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) | | `credentials/reference-updated` | `emit` | [`packages/credentials/credentials/src/types.ts:84`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | [`credentials`](../packages/credentials/credentials), `remotes` | | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace), `workspace-controller` | | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) | | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:76`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem) | | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:58`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) | | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-round-driver`](../packages/goal/goal-round-driver) | | `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/types.ts:23`](../packages/llm/llm/src/types.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`llm`](../packages/llm/llm), `remotes` | | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:67`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/test-support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) | | `session-telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:43`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - | | `session/created` | `emit` | [`packages/core/session/src/index.ts:52`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`compaction`](../packages/compaction/compaction), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`schedule`](../packages/schedule/schedule), `server`, [`session`](../packages/core/session), `session-controller`, [`session-log-deepseek`](../packages/session/session-log-deepseek), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | | `session/disposed` | `emit` | [`packages/core/session/src/index.ts:62`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `agent-team`, `session-controller`, [`session-persistence`](../packages/session/session-persistence), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title) | | `session/event` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`agent-presets`](../packages/preset/agent-presets), `agent-team`, [`compaction`](../packages/compaction/compaction), [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), [`hook-protocol`](../packages/hooks/hook-protocol), [`loader-smoke`](../packages/test-support/loader-smoke), `server`, [`session`](../packages/core/session), `session-controller`, [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:83`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry) | | `settings/document-updated` | `emit` | [`packages/settings/settings/src/types.ts:105`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `remotes` | | `settings/updated` | `emit` | [`packages/settings/settings/src/types.ts:92`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) | | `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:298`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - | | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:173`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), `server`, [`subagent`](../packages/subagent/subagent) | | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:147`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) | | `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:153`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) | | `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:164`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`subagent`](../packages/subagent/subagent) | | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:31`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`system-prompt`](../packages/core/system-prompt) | | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:37`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - | | `tools/change` | `emit` | [`packages/core/tools/src/index.ts:199`](../packages/core/tools/src/index.ts) | [`agent-presets`](../packages/preset/agent-presets) (`emit`), [`tools`](../packages/core/tools) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) | | `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:155`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), `timeout-policy` | | `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:167`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) | | `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:144`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-jobs`](../packages/jobs/tool-jobs) | | `tools/ptc-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:181`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) | | `tools/result` | `emit` | [`packages/core/tools/src/index.ts:189`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`agent-instructions`](../packages/context/agent-instructions), [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver) | | `user-questions/request` | `waterfall` | [`packages/interaction/user-questions/src/types.ts:85`](../packages/interaction/user-questions/src/types.ts) | [`user-questions`](../packages/interaction/user-questions) (`waterfall`) | `remotes` | | `webserver/index-inject` | `emit` | [`packages/host/webserver/src/index.ts:34`](../packages/host/webserver/src/index.ts) | `webserver` (`emit`) | `inspector`, `modules` | | `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:79`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow), [`workflow`](../packages/workflow/workflow) | | `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:68`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow), [`workflow`](../packages/workflow/workflow) | | `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:89`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) | | `workflow/log` | `emit` | [`packages/workflow/workflow/src/index.ts:58`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | | `workflow/phase` | `emit` | [`packages/workflow/workflow/src/index.ts:51`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | | `workflow/start` | `emit` | [`packages/workflow/workflow/src/index.ts:43`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) | ## 包源码中出现的非 harness 或未声明事件字符串 | 事件字符串 | 派发方 | 监听方 | | --- | --- | --- | | `internal/dispatch` | - | `agent-team`, [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`schedule`](../packages/schedule/schedule), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-log-deepseek`](../packages/session/session-log-deepseek), [`session-title`](../packages/session/session-title), [`subagent`](../packages/subagent/subagent), [`terminal-bash`](../packages/terminal/terminal-bash), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`webhook`](../packages/webhook/webhook), [`workflow`](../packages/workflow/workflow) | | `internal/plugin` | - | `inspector`, `loader`, [`lsp-stdio`](../packages/lsp/lsp-stdio), `modules` | | `internal/service` | - | [`agent-presets`](../packages/preset/agent-presets), `gateway` | | `internal/status` | - | [`agent`](../packages/core/agent), `inspector` | 维护模式：生成内容。Cordis 事件声明及生产方／监听方的关系边由仓库的 TypeScript Program 解析。 # Agent 轮次与步骤生命周期 [English](agent-lifecycle.md) | 中文 此时序图是 [architecture.md](architecture.zh.md#turn-flow) 的配套图示。持久的回放事实保存在 `session/event` 中，实时控制与状态则保存在 `agent/*` 中。 ```mermaid sequenceDiagram participant User participant Agent participant Driver participant Hooks as hook listeners participant Prompt as ctx.systemPrompt participant LLM as ctx.llm participant Tools as ctx.tools participant Session participant SDK as UI or SDK listener User->>Agent: followup(content) Agent-->>SDK: agent/inbox/spliced Agent-->>SDK: agent/inbox/inserted { message } Agent->>Driver: queued work wakes driver Driver-->>SDK: agent/status running Driver->>Session: turn/start Note over Agent,Driver: claim pending next-step input plus one queued prompt Driver-->>SDK: agent/inbox/spliced pure deletion Driver-->>SDK: agent/inbox/claimed { message, turn } per message Driver->>Hooks: agent/pre-step waterfall Hooks-->>Driver: authoritative reject or enter(messages) alt proposed step rejected or pre-step failed Driver-->>Driver: claimed batch stays removed, the open turn spends no step else enter proposed step Driver->>Session: step/start Driver->>Session: user/message per entered message Driver->>Prompt: system-prompt/assemble waterfall Driver->>LLM: agent/request waterfall, then llm/stream waterfall LLM-->>Driver: StreamChunk* Driver->>Session: assistant/chunk* Session-->>SDK: session/event assistant/chunk* alt final adapter or terminal in-band request failure Driver->>Session: step/end Driver->>Hooks: agent/request-error waterfall Hooks-->>Driver: return retry action or preserve the original error else model request succeeded Driver->>Session: assistant/message Driver->>Tools: classify pending call by executionMode loop barriers and bounded rolling pool, reclassify before start opt call starts Driver->>Session: tool/call Driver->>Tools: ordered pre, concurrent execute Tools-->>Session: tool-owned events when applicable end opt next model-order result ready Driver->>Tools: ordered post Driver->>Session: tool/result end end Driver->>Session: step/end opt natural stop and next-step inbox empty Driver->>Hooks: agent/turn-stopping serial terminal checkpoint end opt next-step input is pending Driver-->>Driver: claim pending next-step input Driver-->>SDK: agent/inbox/claimed { message, turn } per message Driver->>Hooks: agent/pre-step waterfall Hooks-->>Driver: authoritative reject or enter(messages) end end end Driver->>Session: turn/end Driver-->>SDK: agent/status idle ``` `assistant/message` 事件会记录每次成功的提供方调用，包括返回空内容或以 `max-tokens` 结束的调用。空内容不会进入派生历史，但该持久事件仍会保留用量，并通过 `sourceEventSeqs` 精确列出对应的 `assistant/chunk` 事件，包括显式空列表。 `dsh-compaction-basic` 在派生请求之前通过 `agent/pre-step` 处理压力，而 `agent/request-error` 仅用于规范的上下文溢出。任一触发条件满足后，系统都会先执行可选的工具结果剪枝，再选择摘要。恢复发生在失败步骤结束之后、失败轮次结束之前；只有当剪枝或摘要生成推进了 surface replacement generation 时，系统才会开启一个全新的重试轮次，否则仍以原始请求错误为准。 以返回的 `agent/pre-step` 决策为准；通过包装 `next()` 的监听器会保留下游消息与 `startsRequestSeries`，除非有意替换。steering（中途引导）和注入的上下文在后续的认领操作取得其下一步骤批次后，会经过同一 waterfall（瀑布式事件）。 需要可回放 transcript（文本记录）数据的 SDK 用户应当消费 `session/event`；`agent/*` 是用于队列与状态、提示词拦截、请求构造、steering、继续执行和错误处理的实时协调接口。 维护模式：英文源文件包含人工维护的 Mermaid 时序图，并由生成器写出；本中文文件作为经评审对侧通过双语配对维护。确切的事件签名位于生成的 Cordis 目录中。 # 工具执行流水线 [English](tool-execution-pipeline.md) | 中文 此图展示策略、钩子、沙箱、文件系统守卫、结果重写、最终结果观察和 UI 渲染在不改变循环的情况下何时运行。`tools/pre-execute` waterfall（瀑布式事件）首先运行，随后是单调守卫，然后运行 `tools/execute` 和 `tools/post-execute` waterfall；这三个 waterfall 可以改写一次调用。由定义自身控制的 `finalizeContent` 和 `tools/result` 在此之后运行。 ```mermaid flowchart TD model["Assistant message contains tool-call block"] toolCall["Session event: tool/call
logged before execution"] presentCall["UI pending card
presentCall(args)"] pre["tools/pre-execute waterfall
hooks, permission, sandbox"] guards["Registered monotonic guards
deny or abstain; identity protected"] denied["denied or approval refused
tool body skipped"] approval["ctx.approval one-shot prompt
absent or unanswerable: deny"] around["tools/execute waterfall
timeout, retry, metrics (around dispatch)"] toolBody["Registered tool execute() body"] fsGate["fs/write-intent or fs/edit-intent
tool-fs mutations only"] owned["Tool-owned session events
todo/write, fs/observed, hook/invoked, hook/result, tool/code-dispatch"] post["tools/post-execute waterfall
accept, block, replace, add context"] normalized["Registry outer normalization
pipeline/result snapshot throws become isError"] finalize["ToolDefinition.finalizeContent
last content-only invariant"] final["tools/result synchronous notification
frozen authoritative outcome"] context["Active-batch additionalContexts FIFO
injected user/message after recorded tool results"] toolResult["Session event: tool/result
single model-facing outcome"] allResults["Tool batch settled
recorded tool/result events complete"] presentResult["UI completed card
presentResult(args, result)"] model --> toolCall toolCall --> presentCall toolCall --> pre pre -->|allow| guards guards -->|allow| around guards -->|deny| denied guards -.->|throw| normalized around --> toolBody pre -->|deny| denied pre -->|ask| approval approval -->|allowed-once| guards approval -->|rejected, cancelled, unavailable| denied approval -.->|throw| normalized denied --> post pre -.->|throw| normalized toolBody --> fsGate fsGate --> toolBody toolBody --> owned toolBody --> around around --> post around -.->|wrapper throws| normalized post -.->|throw| normalized post --> finalize normalized --> finalize finalize --> final final --> toolResult toolResult --> presentResult toolResult --> allResults allResults --> context ``` 文件系统的先读后编辑检查位于 `tool-fs` 之下，通过 `fs/*` 事件实现。通用的前置／后置 waterfall 承载钩子与审批策略；`ctx.approval` 在单调守卫之前处理询问，而不得重新排序的所有者策略仍作为已注册的守卫。超时等环绕分发关注点对 `tools/execute` 进行包装。注册表会对候选结果进行无损快照；如果快照失败，则会先将失败规范化，之后再由可见定义中已随快照固定的 `finalizeContent` 回调强制执行其同步且仅限内容的不变式。随后，`tools/result` 会观察不可变、可由 JSON 无损表示的结果。这样一来，钩子便可跨越不同工具系列，而无需让工具与某个策略服务耦合。PTC mode 会将保留的 `run_code` 传输及其序列化子调用都送入流水线；子调用携带父级 token、记录 `tool/code-dispatch`、将拒绝呈现为具有约束力的驳回，并省略 `additionalContexts`，以保持调用与结果相邻。 维护模式：英文源文件包含人工维护的 Mermaid 流程图，并由生成器写出；本中文文件作为经评审对侧通过双语配对维护。确切的工具 schema 与事件签名位于生成的目录中。 # Dsh Cordis教程 # Cordis 入门 [English](cordis-primer.md) | 中文 Cordis 是 DeepSeek Harness 底层以 vendor 方式引入的插件框架。本文介绍 harness 插件作者在阅读[子系统页面](subsystems/core.zh.md)上生成的服务/事件参考之前需要了解的 Cordis 核心概念；[Cordis 教程](cordis-tutorial/index.zh.md)则通过实践逐一讲解这些概念。vendor 源码与同步流程见 [vendor/README.md](../vendor/README.md)。 ## 五个核心概念 - **插件是实现 Service 的对象。** 它可以是一个带有可选 `inject` 和 `apply(ctx)` 字段的函数，也可以是一个 `Service` 子类，其生命周期由 Cordis 挂载到当前上下文中。 - **上下文是服务的容器。** 一个服务占据一个稳定的 `ctx.`（如 `ctx.tools`、`ctx.llm`、`ctx.sessions`）；其他插件通过 key 查找服务，而非导入具体实现。 - **通过 `inject` 声明服务依赖。** 插件声明所需的服务后，会等待这些服务就绪才启动；加载顺序通过服务依赖表达，而非手动编排启动序列。 - **类型化事件用于通信。** 服务通过 TypeScript 声明合并注册事件名，然后以 `emit`、`waterfall`（瀑布式事件）、`parallel`、`serial` 或 `bail` 方式分发，分别对应监听者观察、包装、并行扇出、按序执行或停在首个 bail 值。 - **注册是可逆的副作用。** 提示词片段、工具 schema、适配器、提供方和监听器通过 `ctx.effect()` 或 `ctx.on()` 安装，reload 和 teardown 时会按预期撤销。 ## 分发模式 每个事件具有以下分发模式之一，且只能通过对应方法分发。 | 模式 | 是否 await？ | 分发顺序 | 是否有返回值？ | |---|---|---|---| | `emit` | 否 | 监听器按注册顺序观察 | 否 | | `waterfall` | 否 | 监听器按注册顺序观察 | 是 | | `parallel` | 是 | 所有监听器并行观察事件 | 否 | | `serial` | 是 | 监听器按注册顺序观察 | 是 | | `bail` | 否 | 监听器按注册顺序观察，直到某个监听器返回 bail 值 | 是 | 分发模式是事件公开约定的一部分。新的 harness 事件通过 `@mode` 标签记录模式，以便生成的目录可以将声明与分发调用点做交叉校验。 ## Cordis Waterfall 语义 `ctx.waterfall` 是环绕中间件。监听器接收 `(...args, next)`。调用 `next()` 会执行下游监听器；下游返回值通过 `next()` 返回当前包装层，可由该层包装后继续向外返回。不调用 `next()` 直接返回则短路。 协作式监听器通常修改一个共享的请求或决策对象，然后委托。监听器也可以选择完全替换结果，下游监听器将只看到替换后的结果。仅当监听器必须在普通注册之前运行时才使用 `prepend: true`。 对于单决策事件，短路是设计意图。策略监听器在拥有决策权时可以不调用 `next()` 直接返回，而仅做标注或观察的监听器则必须委托。 ## Loader 配置 `@deepseek-ai/cordis-plugin-include` 将 `!!js` 解析为表达式节点。Loader 在声明的注入激活后，基于该插件上下文（`ctx.serviceName`）插值条目的 `config`，并在每次挂载决策时基于 loader 上下文插值其 `disabled` 字段；Include 会保留嵌套行表达式，直到目标行激活。其余条目元数据保持字面值。由环境选择插件时，请使用 overlay。 ## 实践规则 将行为封装为插件：工具流水线事件属于 `ctx.tools`，模型流式输出属于 `ctx.llm`，实时 agent（智能体）协调属于 `ctx.agents`。拦截和策略优先使用事件；直接能力调用优先使用服务方法。 每个注册都应有对应的 disposer（资源释放函数）：要么从 `ctx.effect()` 返回一个，要么使用 Cordis 提供的辅助方法自动处理。如果 teardown 顺序有要求，请将相关工作放在同一个 effect 中，以确保资源按预期顺序释放。 # Cordis 教程 [English](index.md) | 中文 Cordis 是 DeepSeek Harness 底层的插件框架：它是一个小型运行时，其中的每项能力，包括工具、LLM（大语言模型）适配器、文件访问乃至 agent loop（智能体循环）本身，都是挂载到共享上下文中的插件。本教程通过动手实践讲解 Cordis：每一章都是一个可以运行的示例，你将在本仓库内的临时目录中逐步构建它，最后把一个插件接入真实的 harness 服务。 本教程面向 agent 开发者。你不需要深入掌握 TypeScript；下文的 [TypeScript 说明](#typescript-notes)会解释可能陌生的语法，并且每一章都会给出确切命令和预期输出。 如果你想阅读精简的概念参考，而不是逐步实践，请参阅 [Cordis 入门](../cordis-primer.zh.md)。详尽的 API 参考见[子系统页面](../subsystems/core.zh.md)上生成的 `cordis-surface` 区块，以及 [Cordis 核心 API](../cordis-api/context.zh.md) 页面。 如果你要为 harness 本身编写插件——由 `cordis.yml` 加载、在 Web UI 中驱动，而不是下面这个启动器——请从[第一个 Harness 插件](../user/develop/basic/index.zh.md)开始。 ## 准备工作 你需要克隆本仓库并安装依赖；[开发指南](../development.zh.md#setup-tutorial)列出了前置条件。本教程不需要 API 密钥；所有示例均可在无密钥环境中运行。 ```sh git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness pnpm install ``` 创建各章使用的临时目录。`tmp/` 已被 git 忽略，因此你在其中写入的任何内容都不会进入版本控制： ```sh mkdir -p tmp/cordis-tutorial cd tmp/cordis-tutorial ``` 每一章都从该目录运行同一条命令： ```sh node --import tsx ../../vendor/cordis/bin.js ``` 这个单文件启动器（见 [vendor/cordis/bin.js](../../vendor/cordis/bin.js)）会创建根 `Context`、挂载 Loader 插件，并让它从当前目录加载 `./cordis.yml`。其余所有内容，包括有哪些插件以及如何配置它们，都来自你稍后将编写的 YAML 文件。`--import tsx` 标志让 Node 无需构建步骤即可运行配置所指向的 TypeScript 文件。 ## 章节 1. [你的第一个插件](01-first-plugin.zh.md)：插件是函数，由 loader 挂载。 2. [生命周期与 effect](02-lifecycle-and-effects.zh.md)：由 Cordis 管理的注册会在所属插件卸载时撤销。 3. [服务](03-services.zh.md)：在 `ctx` 上公开一项能力，并通过 `inject` 依赖它。 4. [事件](04-events.zh.md)：类型化事件、广播分发和 waterfall（瀑布式事件）的短路行为。 5. [配置](05-config.zh.md)：读取 `cordis.yml` 中经过校验的配置，并在输入错误时明确报错。 6. [组合与 HMR（热模块替换）](06-composition-and-hmr.zh.md)：把配置文件作为插件树，使用热重载，并诊断始终无法加载的插件。 7. [进入 harness](07-into-the-harness.zh.md)：基于真实的 harness 服务注册一个可由模型调用的工具。 ## TypeScript 说明 这些示例使用了普通现代 JavaScript 之外的三项 TypeScript 功能： - **类型注解**描述值，但不会改变运行时行为：`ctx: Context` 表示 `ctx` 具备 Cordis 上下文 API，`who: string` 接受文本，而 `string[]` 表示字符串数组。 - **`import type { Context } from '@deepseek-ai/cordis'`** 只导入类型信息。它在运行时会消失，因此仅为类型注解使用 `Context` 的插件文件不会增加运行时依赖。 - **声明合并**（`declare module '@deepseek-ai/cordis' { ... }`）会为 Cordis 已经声明的接口添加你的条目，例如新 `ctx.greeter` 属性的类型或事件名称。它不会生成任何运行时接线；插件必须另行提供服务或发出事件。第 3 章会完整展示该模式。 第 5 章还会使用 `interface` 描述配置对象的字段，并使用 `Schema` 这类泛型表示 schema 校验哪些对象字段。你可以直接照写这些声明；周围的正文会解释每项声明连接了什么。 [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness) # 1. 编写第一个插件 [English](01-first-plugin.md) | 中文 在本教程使用的 loader 配置中，Cordis 插件模块通过命名导出提供 `apply` 函数。Cordis 加载模块时，会用一个 **上下文** 调用 `apply`；该上下文就是 `ctx` 对象，插件通过它注册自己贡献的所有内容。 ## 编写插件 在 `tmp/cordis-tutorial` 目录中（参见[环境设置](index.zh.md#setup)）创建 `hello.ts`： ```ts import type { Context } from '@deepseek-ai/cordis' export const name = 'hello' export function apply(ctx: Context) { console.log('hello from my first plugin') } ``` `name` 导出项是可选的显示元数据；它用于在诊断信息中标识插件。 ## 组合应用 本教程的启动器通过配置组装应用。创建 `cordis.yml`： ```yaml - name: './hello.ts' ``` 该文件是一组 Cordis 配置项的列表。`name` 是模块指定符，可以是相对路径或 NPM 包名；loader 会挂载每个配置项。各项会并发启动，因此它们在列表中的位置不保证插件的加载先后；顺序由服务依赖（`inject`，参见[第 3 章](03-services.zh.md)）决定，而非文件中的位置。 ## 运行 ```sh node --import tsx ../../vendor/cordis/bin.js ``` 预期输出： ``` hello from my first plugin ``` 当没有任何内容继续运行时，进程会自行退出。具体过程如下： 1. 启动器创建根 `Context`，并挂载 **Loader** 插件。 2. Loader 读取 `cordis.yml`，解析 `./hello.ts`，然后将其作为子插件挂载。 3. Cordis 调用你的 `apply(ctx)`。 你的文件中没有框架启动代码：插件描述自己的贡献，`cordis.yml` 则组合应用。例如，[`dsh` base](../../packages/bundle/base/cordis.patch.yml) 就是一份更长的插件组合，由部署 overlay 对它进行修补。 ## 其他两种插件形态 函数是最常见的形式，但 Cordis 接受三种形式： ```ts import { Service, type Context } from '@deepseek-ai/cordis' // 1. Function plugin (what you just wrote). export function apply(ctx: Context) {} // 2. Object plugin: an object with an `apply` method. export const objectPlugin = { name: 'object-plugin', apply(ctx: Context) {}, } // 3. Class plugin: a Service subclass (covered in chapter 3). export class MyService extends Service { constructor(ctx: Context) { super(ctx, 'myTutorialService') } } ``` 在你需要公开服务之前，请一直使用函数形态；[第 3 章](03-services.zh.md)介绍了何时应当使用类形态。 ## 尝试制造错误 让 `apply` 抛出异常： ```ts ignore-check export function apply(ctx: Context) { throw new Error('apply exploded') } ``` 再次运行：进程会因该错误而终止。插件加载失败会明确报错，不会仅跳过该配置项。 还需要尽早了解一个例外：如果某个配置项的模块无法被 **解析**，例如路径或包名拼写错误，Cordis 会通过 logger 服务报告错误，而不会使进程崩溃。在启动阶段，这条报告可能在 console 导出器开始观察之前丢失。如果新增配置项似乎没有任何效果，请先检查拼写。 下一章：[生命周期与 effect](02-lifecycle-and-effects.zh.md)：插件卸载时会发生什么。 [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness) # 2. 生命周期与 effect [English](02-lifecycle-and-effects.md) | 中文 Cordis 插件可能因修改配置、热重载、显式资源释放或所需服务消失而卸载。通过 Cordis API 建立的注册属于 effect，会在所属插件卸载时撤销；在这些 API 之外管理的资源必须包装在 `ctx.effect()` 中。 ## Effect 对于 Cordis 尚未管理的资源，例如定时器、连接或 watcher，应将其包装在 `ctx.effect()` 中并返回 disposer（资源释放函数）： 创建 `lifecycle.ts`，将它放在 `tmp/cordis-tutorial` 中： ```ts import type { Context } from '@deepseek-ai/cordis' export const name = 'lifecycle-demo' function heartbeat(ctx: Context) { console.log('heartbeat plugin loading') ctx.effect(() => { const timer = setInterval(() => console.log('tick'), 200) return () => { clearInterval(timer) console.log('heartbeat cleaned up') } }) } export function apply(ctx: Context) { // Mount a child plugin and keep its fiber to dispose it later. const fiber = ctx.plugin(heartbeat) // The demo timer is itself an effect: if THIS plugin is unloaded first, // the pending callback is cancelled instead of firing on a dead app. ctx.effect(() => { const timer = setTimeout(async () => { await fiber.dispose() console.log('disposed') process.exit(0) }, 700) return () => clearTimeout(timer) }) } ``` 让 `cordis.yml` 指向该文件： ```yaml - name: './lifecycle.ts' ``` 运行（`node --import tsx ../../vendor/cordis/bin.js`）后会得到： ``` heartbeat plugin loading tick tick tick heartbeat cleaned up disposed ``` 请留意三点： - `ctx.plugin(heartbeat)` 会把一个**来自代码**的函数挂载为插件，这与 YAML loader 为每个配置项执行的操作相同。函数插件不需要 `apply` 方法：Cordis 会直接调用该函数，其名称只用于诊断。只有对象形态才要求 `apply` 方法，例如 `ctx.plugin({ apply(ctx) { /* ... */ } })`。调用会返回一个 **fiber**，即一个已加载插件实例的运行时句柄。 - effect 主体在加载期间运行；它返回的 disposer 在卸载期间运行。对于生命周期与插件一致的资源，你绝不需要自行调用 disposer。 - `fiber.dispose()` 会等该插件的所有清理工作（包括异步 disposer）完成后才结束，并递归卸载它挂载的所有子插件。 ## Fiber 状态机 每个已加载插件实例都拥有一个 fiber，并在以下状态之间转换： ``` PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED ↘ FAILED ``` - **PENDING**：已经声明，但所需服务（第 3 章）尚不可用。 - **LOADING / ACTIVE**：`apply` 正在运行／已经完成。 - **FAILED**：`apply` 或配置校验抛出异常。 - **UNLOADING / DISPOSED**：disposer 正在运行／一切均已拆除。 你会在[第 6 章](06-composition-and-hmr.zh.md)再次遇到 PENDING，它通常就是「为什么我的插件没有输出」的答案。 ## 已经属于 effect 的操作 你很少需要亲自编写 `ctx.effect()`，因为内置注册 API 本身已经是 effect： - `ctx.on(event, listener)`：监听器会在卸载时移除（[第 4 章](04-events.zh.md)）。 - `ctx.plugin(child)`：子插件会随父插件一同 dispose（资源释放）。 - 服务注册属于 effect。`ctx.tools.register(...)` 等 harness 注册表也会把返回的 disposer 附着到调用插件上，因此会自动撤销（[第 7 章](07-into-the-harness.zh.md)）。 对于 Cordis 不管理的资源，应在 `ctx.effect()` 内获取它，并返回用于释放资源的 disposer。此后 Cordis 会在卸载期间调用该释放逻辑，热重载时也不例外。 有一项顺序注意事项：disposer 会按注册顺序的逆序启动，但多个**异步** disposer 会并发运行。如果拆除步骤必须按顺序执行，请把它们放在同一个 disposer 中，并在其中依次等待每步完成。 下一章：[服务](03-services.zh.md)：插件如何共享功能。 [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness) # 3. 服务 [English](03-services.md) | 中文 **服务**是一个插件提供、其他插件通过 `ctx` 消费的具名能力。在 harness 中，`ctx.tools`、`ctx.llm` 和 `ctx.agents` 都是服务。消费方只指定 `'tools'` 之类的能力，而不导入其提供方，因此配置可以选择提供方，无需修改消费方。 ## 提供服务 创建 `greeter.ts`，将它放在 `tmp/cordis-tutorial` 中： ```ts import { Service, type Context } from '@deepseek-ai/cordis' declare module '@deepseek-ai/cordis' { interface Context { greeter: GreeterService } } export class GreeterService extends Service { constructor(ctx: Context) { super(ctx, 'greeter') } greet(who: string) { return `Hello, ${who}!` } } export const name = 'greeter' export function apply(ctx: Context) { ctx.plugin(GreeterService) } ``` 两部分协同工作： - **运行时**：`super(ctx, 'greeter')` 以名称 `greeter` 注册该实例。此后，任何插件都可以通过 `ctx.greeter` 访问它。注册属于 effect，卸载提供方时会移除该服务。 - **编译时**：`declare module '@deepseek-ai/cordis'` 块使用 TypeScript 声明合并，把 `greeter` 加入 `Context` 接口，使 `ctx.greeter` 在各处都能通过类型检查。它不会生成代码；没有该声明时，服务在运行时仍能工作，但消费方会失去类型安全。 `Service` 子类本身就是插件（第 1 章介绍的类形态），因此 `ctx.plugin(GreeterService)` 会像挂载其他插件一样挂载它。 ## 使用 `inject` 消费服务 创建 `consumer.ts`： ```ts import type { Context } from '@deepseek-ai/cordis' export const name = 'consumer' export const inject = ['greeter'] export function apply(ctx: Context) { console.log(ctx.greeter.greet('world')) } ``` `inject` 列出该插件需要的服务。Cordis 会让插件保持 PENDING，直到列出的每项服务都存在，因此在 `apply` 内可以保证 `ctx.greeter` 已经就绪。`cordis.yml` 中的加载顺序无关紧要：决定插件何时启动的是依赖关系，而不是文件顺序。 组合并运行： ```yaml - name: './greeter.ts' - name: './consumer.ts' ``` ``` Hello, world! ``` 交换 `cordis.yml` 中两行的顺序后重新运行，输出仍然相同。尝试彻底移除 `./greeter.ts`：消费方会保持 PENDING，不输出任何内容，既不崩溃，也不会只运行一部分。处于 PENDING 的 fiber 也不会让 Node 的事件循环保持活跃，因此如果组合中没有其他运行项，进程会静默地以状态码 0 退出。[第 6 章](06-composition-and-hmr.zh.md)介绍如何诊断这种状态。 ## 加载后仍会跟踪依赖关系 `inject` 并非一次性的启动检查。如果应用运行期间所需服务消失，例如提供方被卸载或热替换，每个依赖插件也会随之卸载，并在服务恢复后再次加载。结合 effect（[第 2 章](02-lifecycle-and-effects.zh.md)），这能防止运行中的消费方保留对不可用服务的引用：依赖消失时，它自己的注册也会撤销。 这也是配置中可以替换服务的原因：卸载 Cordis 配置项 `dsh-bash-local`，挂载另一个 `shell` 提供方，所有注入 `'shell'` 的插件都会重新启动并使用新实现。 ## 可选依赖 `inject` 用于硬性依赖。如果某项功能缺失时插件仍可运行，请跳过 `inject`，并在使用处探测： ```ts ignore-check export function apply(ctx: Context) { // undefined when no provider is loaded; the plugin still runs. const greeter = ctx.get('greeter') console.log(greeter?.greet('maybe') ?? 'no greeter available') } ``` ## 命名 每个应用中的服务名称共用一个扁平命名空间。请为自有服务添加有辨识度的前缀或命名空间（harness 已占用 `tools` 和 `llm` 等普通名称）；[子系统页面](../subsystems/core.zh.md)上生成的 `cordis-surface` 区块列出 harness 注册的每个名称。 下一章：[事件](04-events.zh.md)：无需共享服务即可通信。 [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness) # 4. 事件 [English](04-events.md) | 中文 服务支持直接调用；**事件**让插件无需知道有哪些插件正在监听，就能发出通知。harness 使用事件处理工具结果、模型请求和审批决定等交互。 ## 声明、发出与监听 创建 `stats.ts`，将它放在 `tmp/cordis-tutorial` 中。它是一项负责计数并在每次变化时发出通知的服务： ```ts import { Service, type Context } from '@deepseek-ai/cordis' declare module '@deepseek-ai/cordis' { interface Context { stats: StatsService } interface Events { 'stats/report'(name: string, count: number): void } } export class StatsService extends Service { private counts = new Map() constructor(ctx: Context) { super(ctx, 'stats') } bump(name: string) { const next = (this.counts.get(name) ?? 0) + 1 this.counts.set(name, next) this.ctx.emit('stats/report', name, next) } } export const name = 'stats' export function apply(ctx: Context) { ctx.plugin(StatsService) } ``` `interface Events` 合并与第 3 章的 `interface Context` 合并在事件系统中相互对应：它声明事件名称及其监听器签名，因此 `ctx.emit` 和 `ctx.on` 都具有完整类型。`namespace/action` 命名约定让扁平的事件命名空间保持易读。 创建 `reporter.ts`： ```ts ignore-check import type { Context } from '@deepseek-ai/cordis' import type {} from './stats.ts' export const name = 'reporter' export const inject = ['stats'] export function apply(ctx: Context) { ctx.on('stats/report', (name, count) => { console.log(`[stats] ${name} -> ${count}`) }) ctx.stats.bump('tool_call') ctx.stats.bump('tool_call') ctx.stats.bump('prompt') } ``` `import type {} from './stats.ts'` 行不会在运行时导入任何内容；它的作用是让 TypeScript 看到声明合并。组合并运行： ```yaml - name: './stats.ts' - name: './reporter.ts' ``` ``` [stats] tool_call -> 1 [stats] tool_call -> 2 [stats] prompt -> 1 ``` 因为 `ctx.on()` 属于 effect，监听器会随插件一同消失，绝不需要手动维护 `removeListener`。 ## 分发模式 `emit` 是 5 种分发模式之一。事件采用哪种模式是其约定的一部分，决定了监听器能否返回值、能否并发运行，以及能否彼此短路： | 模式 | 调用 | 语义 | |---|---|---| | emit | `ctx.emit(name, ...args)` | 同步广播；不会等待或收集返回的 promise 与值。 | | parallel | `await ctx.parallel(name, ...args)` | 所有监听器并发运行，并一同等待。 | | serial | `await ctx.serial(name, ...args)` | 监听器按顺序运行并等待；第一个非 `null`/`false`/`undefined` 返回值胜出，并停止后续监听器。 | | bail | `ctx.bail(name, ...args)` | serial 的同步版本。 | | waterfall（瀑布式事件） | `ctx.waterfall(name, ...args, next)` | 环绕中间件，见下文。 | 每个 harness 事件都会在其所属[子系统页面](../subsystems/core.zh.md)自动生成的参考文档中记录其模式。 ## waterfall：转换或短路 waterfall 是实现拦截的模式。每个监听器都会收到参数和一个 `next()` continuation；它可以转换 `next()` 的返回值，也可以不调用 `next()` 就直接返回，从而短路链条的其余部分。Cordis 文档把后一种行为称为否决。创建 `waterfall-demo.ts`： ```ts import type { Context } from '@deepseek-ai/cordis' declare module '@deepseek-ai/cordis' { interface Events { 'demo/transform'(input: string, next: () => Promise): Promise } } export const name = 'waterfall-demo' export function apply(ctx: Context) { // Listener 1: wrap the downstream result. ctx.on('demo/transform', async (input, next) => { const downstream = await next() return downstream.toUpperCase() }) // Listener 2: short-circuit when it owns the decision. ctx.on('demo/transform', async (input, next) => { if (input.includes('blocked')) return '** blocked **' return next() }) void (async () => { console.log(await ctx.waterfall('demo/transform', 'hello', async () => 'hello')) console.log(await ctx.waterfall('demo/transform', 'blocked words', async () => 'blocked words')) })() } ``` 让 `cordis.yml` 只指向该文件并运行： ``` HELLO ** BLOCKED ** ``` 按顺序看第二行如何产生：监听器 1 先运行并调用 `next()`，从而调用监听器 2；监听器 2 看到 `blocked` 后直接返回而不调用 `next()`，因此最内层默认逻辑（传给 `ctx.waterfall` 的函数）从未运行；返回途中，监听器 1 再把替换消息转换为大写。 由此得到一项纪律：**只负责观察或标注的 waterfall 监听器必须调用 `next()`**；不调用就直接返回代表有意短路。如果日志监听器忘记调用 `next()`，会悄无声息地吞掉所有下游的默认行为。这是本仓库的常设规则（[waterfall 语义](../cordis-primer.zh.md#cordis-waterfall-semantics)）。 harness 使用 waterfall 处理协作插件可以包装或回答的决策：[`agent/request`](../subsystems/core.zh.md#agentrequest--waterfall) 允许插件替换模型调用配置，[`approval/request`](../subsystems/approval.zh.md#approvalrequest--waterfall) 允许策略代替用户作答。 下一章：[配置](05-config.zh.md)：来自 `cordis.yml` 的插件选项。 [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness) # 5. 配置 [English](05-config.md) | 中文 `cordis.yml` 中的每个 Cordis 配置项都可以携带 `config` 块，插件则声明一个 schema，在运行 `apply` 前验证该块。错误配置会导致加载失败，并给出准确的错误：插件绝不会在配置不完整时启动。 ## 可配置插件 创建 `config-demo.ts`，并将其放在 `tmp/cordis-tutorial` 中： ```ts import type { Context } from '@deepseek-ai/cordis' import Schema from '@deepseek-ai/schemastery' export const name = 'config-demo' export interface Config { greeting: string targets: string[] } export const Config: Schema = Schema.object({ greeting: Schema.string().default('Hello'), targets: Schema.array(String).default(['world']), }) export function apply(ctx: Context, config: Config) { for (const target of config.targets) { console.log(`${config.greeting}, ${target}!`) } } ``` 导出的 `Config` 既是 TypeScript 接口，也是同名的运行时 schema：消费方获得类型，Cordis 获得验证器。本仓库使用 [Schemastery](https://github.com/shigma/schemastery) 定义 schema；Cordis 本身接受任意 [Standard Schema](https://standardschema.dev/) 验证器，因此将普通对象导出为 `Config` 无法工作。 对其进行配置： ```yaml - name: './config-demo.ts' config: targets: ['alpha', 'beta'] ``` 运行： ``` Hello, alpha! Hello, beta! ``` 未提供 `greeting`，因此 schema 默认值会将其补齐：`apply` 始终会收到完整且经过验证的配置。 ## 明确报错 现在向它传入无效内容： ```yaml - name: './config-demo.ts' config: targets: 'not-an-array' ``` ``` ValidationError: invalid config: - $.targets expected array but got not-an-array (at targets) ``` 插件的 fiber 进入 FAILED 状态，本教程的启动器打印错误后以状态码 1 退出。如果某个插件的配置通过了 schema 验证，但其中指定的资源或提供方不可用，该插件也应当在能解析该引用时立即拒绝。 ## 计算得到的配置值 本仓库使用的 loader 支持 `!!js` 标签，用于必须在加载时计算的配置值： ```yaml - name: './config-demo.ts' config: greeting: !!js process.env.DEMO_GREETING ?? 'Hello' ``` `!!js` 仅在 `config` 与条目 `disabled` 字段内有效。`disabled: !!js ...` 在每次挂载决策时基于 loader 上下文求值（本仓库的扩展），可以按平台或环境门控一行；其余元数据（`name`、`id`、`inject` 等）保持静态，其中的表达式是普通真值数据。详见 [loader 配置](../cordis-primer.zh.md#loader-configuration)。 下一章：[组合与 HMR（热模块替换）](06-composition-and-hmr.zh.md)：将 `cordis.yml` 视为应用。 [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness) # 6. 组合与 HMR（热模块替换） [English](06-composition-and-hmr.md) | 中文 到目前为止构建的每项能力都是插件，`cordis.yml` 则选择应用的插件树。本章会改变这种组合、热重载一个插件，并诊断始终无法加载的插件。 ## Cordis 配置项不只有名称 Cordis 配置项除了 `name` 和 `config`，还接受其他元数据： ```yaml - id: greeter # stable identity for this entry name: './greeter.ts' - id: consumer name: './consumer.ts' disabled: true # keep the entry, skip mounting it ``` `id` 为 Cordis 配置项提供稳定标识，使 loader 能区分修改现有 Cordis 配置项与先删除再添加。`disabled: true` 会卸载插件而不删除其 Cordis 配置项；改回原值后，插件以及所有因依赖其服务而处于 PENDING 的插件都会再次加载。 组可以嵌套一份 Cordis 配置项子列表，并将其作为一个单元加载和卸载；`isolate` 则为一个组提供某项服务名称的独立实例，因此两个组可以各自看到配置不同的 `shell` 提供方，互不影响。[Cordis 入门](../cordis-primer.zh.md)和[服务隔离示例](../user/develop/framework/service.zh.md#service-isolation)介绍了详细内容。 ## 热模块替换 卸载会释放 effect（[第 2 章](02-lifecycle-and-effects.zh.md)），加载则遵循依赖关系（[第 3 章](03-services.zh.md)），因此 HMR 可以先卸载、再加载，以替换正在运行的插件。`@deepseek-ai/cordis-plugin-hmr` 插件会监视文件，并在保存时执行这一过程。 在 `tmp/cordis-tutorial` 中编写 `cordis.yml`： ```yaml - id: logger name: '@deepseek-ai/cordis-plugin-logger-console' - id: timer name: '@deepseek-ai/cordis-plugin-timer' - id: hmr name: '@deepseek-ai/cordis-plugin-hmr' config: root: ['.'] - id: hello name: './hello.ts' ``` 列表中增加了两个辅助插件：HMR 通过 Cordis logger 服务记录日志，因此没有控制台导出器时看不到其消息；它还会 `inject` `timer` 服务来实现去抖，如果没有 `@deepseek-ai/cordis-plugin-timer`，它就会永远停在 PENDING，而且不发出任何提示。下一节就讨论这种静默状态。 HMR 通过 Loader 的原生辅助工具读取 Node 的 loader 内部结构。请在 tsx 下运行 Cordis： ```sh node --import tsx ../../vendor/cordis/bin.js ``` 现在编辑 `hello.ts`，修改日志消息并保存： ``` hello from my first plugin 2026-07-22 15:44:36 [I] hmr watching [ '.' ] 2026-07-22 15:44:39 [I] hmr reload plugin at hello.ts hello from my EDITED plugin ``` 旧实例先卸载（其所有 effect 都会回卷），新代码随后加载，`apply` 再次运行。按 Ctrl-C 停止进程。编辑 `cordis.yml` 本身也会触发更新：loader 按 `id` 比较 Cordis 配置项，只挂载、卸载或重新配置发生变化的部分。这就是上述 Cordis 配置项显式携带 `id` 的原因：不带该字段的 Cordis 配置项在每次读取时都会获得一个新生成的 id，所以只要配置文件发生任何编辑，即使自身文本未变，它也会被视为先删除再添加并重新挂载。 ## 诊断始终无法加载的插件 依赖驱动加载也有另一面：如果插件的 `inject` 指定了无人提供的服务，它就会一直等待，不输出任何内容。这不是错误，因为 PENDING 是合法状态，提供方可能稍后才挂载。 你可以直接查看这些状态。每个上下文都能枚举插件注册表；创建 `diagnose.ts`： ```ts import { FiberState, type Context } from '@deepseek-ai/cordis' export const name = 'diagnose' export function apply(ctx: Context) { setTimeout(() => { for (const runtime of ctx.registry.values()) { for (const fiber of runtime.fibers) { if (fiber.state === FiberState.PENDING) { console.log(`${fiber.name} is PENDING — a required service is missing`) } } } }, 500) } ``` 再创建一个依赖无法满足的插件 `needs-timer.ts`： ```ts import type { Context } from '@deepseek-ai/cordis' export const name = 'needs-timer' export const inject = ['timer'] export function apply(ctx: Context) { console.log('needs-timer loaded') } ``` ```yaml - name: './needs-timer.ts' - name: './diagnose.ts' ``` 运行它（直接执行 `node --import tsx ../../vendor/cordis/bin.js`，按 Ctrl-C 停止）： ``` needs-timer is PENDING — a required service is missing ``` `inject: ['timer']` 没有提供方。向列表添加 `- name: '@deepseek-ai/cordis-plugin-timer'` 后，插件就会加载。如果插件既不执行任何操作，也不报告任何内容，请检查其 fiber 状态。不加 PENDING 过滤条件进行迭代时，还会看到 loader 自身的插件（Loader、Include）处于 ACTIVE，因为配置文件本身也是通过插件挂载的。 下一章：[进入 harness](07-into-the-harness.zh.md)：把相同模式用于真实的 harness 服务。 [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness) # 7. 进入 harness [English](07-into-the-harness.md) | 中文 本章会向 harness 的 `tools` 服务注册一个可由模型调用的工具，通过 harness 工具流水线执行它，并观察结果事件。整个示例无需密钥，也不会调用模型。 ## 工具插件 创建 `greet-tool.ts`，将它放在 `tmp/cordis-tutorial` 中： ```ts import type { Context } from '@deepseek-ai/cordis' import { brandString } from '@deepseek-ai/dsh-brand' import { defineTool } from '@deepseek-ai/dsh-tools' import type { ToolCallId } from '@deepseek-ai/dsh-llm' export const name = 'greet-tool' export const inject = ['tools'] export function apply(ctx: Context) { ctx.tools.register(defineTool({ name: 'greet', description: 'Greet the named person.', parameters: { name: { type: 'string', required: true, description: 'Who to greet' }, }, output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }], }, async execute(args) { return `Hello, ${args.name}!` }, })) // Drive one call through the real execution pipeline, standing in for // the model. ToolCallId brands the correlation id a provider would issue. void (async () => { const result = await ctx.tools.execute({ callId: brandString('demo-1'), name: 'greet', arguments: { name: 'Cordis' }, signal: new AbortController().signal, }) console.log('tool replied:', JSON.stringify(result.content)) })() } ``` 这里的每个模式都来自前几章：`inject: ['tools']`（[第 3 章](03-services.zh.md)）会让插件等待工具注册表就绪；`ctx.tools.register(...)` 会把注册 disposer 附着到插件（[第 2 章](02-lifecycle-and-effects.zh.md)），因此卸载时会注销工具。`defineTool` 将 `parameters` 规约转换为向模型展示的 JSON Schema，推导 `args` 的类型，并在 `execute` 运行前校验模型提供的参数。工具返回由 `output.schema` 声明的规范值；`output.render` 则作为 Native renderer（原生渲染器），另行生成可持久化的结果内容。 ## 观察插件 创建 `tool-logger.ts`。这是一个独立插件，通过 harness 的 `tools/result` 事件观察应用中的每次工具调用： ```ts import type { Context } from '@deepseek-ai/cordis' import type {} from '@deepseek-ai/dsh-tools' export const name = 'tool-logger' export const inject = ['tools'] export function apply(ctx: Context) { ctx.on('tools/result', (exec, result) => { const text = result.content .map(block => (block.type === 'text' ? block.text : '')) .join('') console.log(`[tool-logger] ${exec.name} -> ${text}`) }) } ``` `import type {} from '@deepseek-ai/dsh-tools'` 行会引入该包的声明合并，使 `'tools/result'` 及其 payload 具有类型。这与第 4 章导入 `stats.ts` 的做法相同，只是扩展到了包级别。 ## 组合并运行 ```yaml - name: '@deepseek-ai/dsh-system-prompt' - name: '@deepseek-ai/dsh-tools' - name: './tool-logger.ts' - name: './greet-tool.ts' ``` `@deepseek-ai/dsh-tools` 会注入 `systemPrompt` 服务，因为工具需要向系统提示词贡献 schema，所以组合中也要列出该服务的提供方。缺少提供方时，工具插件会像[第 6 章](06-composition-and-hmr.zh.md)所述那样保持 PENDING。 ```sh node --import tsx ../../vendor/cordis/bin.js ``` ``` [tool-logger] greet -> Hello, Cordis! tool replied: [{"type":"text","text":"Hello, Cordis!"}] ``` logger 会先触发：`tools/result` 在结果物化过程中发出，发生在 `execute` 向调用方返回的 promise 兑现之前。两个插件都不知道另一个插件存在，它们由注册表服务和事件连接。 ## 从这里走向完整 agent（智能体） 真实 agent 就是这套组合再加上更多插件：LLM（大语言模型）适配器、agent loop（智能体循环）、持久化和应用入口。对照 [base profile 层](../../packages/bundle/base/cordis.patch.yml)与 [headless 层](../../packages/bundle/headless/cordis.patch.yml)，你现在已经可以读懂其中各项。通过一个小型 `--patch` overlay 加入 `greet-tool.ts` 即可。 后续可以阅读： - [构建工具](../user/develop/basic/tool.zh.md)：深入了解 `defineTool`，包括呈现和更丰富的 schema。 - [三层能力设计](../user/develop/practice/index.zh.md)：harness 如何组织可替换能力。 - [子系统页面](../subsystems/core.zh.md)上生成的 `cordis-surface` 区块：可以注入和监听的所有内容，各在其所属页面上。 - [架构](../architecture.zh.md)：这些插件所处的系统地图。 [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness) # DeepSeek Harness 包工作区 # 新页面 # 包工作区 ``` --- description: "DeepSeek Harness 包工作区：packages/ 下的 npm 包如何分组、每个组负责什么，以及约束它们的约定。" kind: "package-group" --- ``` # 包 [English](README.md) | 中文 ## 概述 harness 由 `packages/` 下的 npm 包组装而成，按能力系列分组：会话与 agent 循环、面向模型的工具、shell 与文件系统执行、Web 访问、subagent 等等。把本页当作顶层地图使用：先找到拥有某能力的组，再打开其 README 查看包列表。每个包都以 `@deepseek-ai/dsh-*` 为作用域、只属于一个组；每个组的 README 都是该能力系列的权威包映射。 ## 目录 - [包分组](#package-groups) - [发布预期](#release-expectations) - [依赖](#dependencies) - [包 README 约定](#package-readme-contracts) - [开发备注](#dev-note) ----- ## 包分组 每个包只属于一个组；新包加入现有组，新组则更新其自身 README 与本表。 | 组 | 职责 | |---|---| | [`core/`](core/README.zh.md) | 产品 API 主干：会话、提示词、工具、agent 服务与具体循环 | | [`api/`](api/README.zh.md) | Remote BFF 装配与 Typert RPC 网关 | | [`typert/`](typert/README.zh.md) | 类型图生成、产物加载与运行时注册表 | | [`goal/`](goal/README.zh.md) | 同会话 goal 的持久化与生命周期 | | [`schedule/`](schedule/README.zh.md) | 仅限会话内的定时后续操作 | | [`feedback/`](feedback/README.zh.md) | 人类反馈的采集与命令 | | [`identity/`](identity/README.zh.md) | 共享匿名身份 | | [`llm/`](llm/README.zh.md) | LLM 能力系列：抽象服务 + 提供方适配器 | | [`e2b/`](e2b/README.zh.md) | E2B 远程运行时提供方 | | [`subprocess/`](subprocess/README.zh.md) | 子进程能力系列：Service Definition + 本地进程树提供方 | | [`shell/`](shell/README.zh.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | | [`terminal/`](terminal/README.zh.md) | 持久 PTY 能力系列：限定所有者范围的会话、本地实现、面向模型的工具 | | [`code-runtime/`](code-runtime/README.zh.md) | 代码执行能力系列：Service Definition + worker 线程提供方 + PTC mode Consumer | | [`sandbox/`](sandbox/README.zh.md) | 进程限制 seam；bwrap/Landlock/Seatbelt 后端 | | [`fs/`](fs/README.zh.md) | 文件系统能力系列：seam、本地实现、面向模型的文件工具、发现工具 | | [`lsp/`](lsp/README.zh.md) | LSP 能力系列：seam、通用 stdio 提供方和 `lsp` 工具 | | [`skill/`](skill/README.zh.md) | skill 能力系列：提供方注册表、本地提供方、面向模型的目录/loader | | [`compaction/`](compaction/README.zh.md) | 压缩能力系列：Service Definition + 基础提供方 + 命令 Consumer | | [`context/`](context/README.zh.md) | 模型可见请求上下文：workspace 指令、时间上下文、引用 | | [`subagent/`](subagent/README.zh.md) | subagent 能力系列：提供方注册表约定和面向模型的委托工具 | | [`jobs/`](jobs/README.zh.md) | 通用后台任务运行时和面向模型的作业控制工具 | | [`experimental/`](experimental/README.zh.md) | 私有原型与内部专用插件 | | [`workflow/`](workflow/README.zh.md) | 工作流 seam、worker 线程引擎、面向模型的 `workflow`/`ralph` 工具 | | [`webhook/`](webhook/README.zh.md) | 已验证外部事件、受信规则与即发即弃 Workspace Session | | [`web/`](web/README.zh.md) | Web 能力系列：seam、搜索/获取提供方、面向模型的 Web 工具 | | [`attachment/`](attachment/README.zh.md) | 持久附件标识、校验、本地内容寻址存储 | | [`spill/`](spill/README.zh.md) | spill 能力系列：存储 seam、本地实现、工具结果 spill 策略 | | [`todo/`](todo/README.zh.md) | 面向模型的 `todo_write` 工具 | | [`plan/`](plan/README.zh.md) | Plan 协作状态，提供直接进入命令与经评审的退出 | | [`preset/`](preset/README.zh.md) | 由 preset `cordis.yml` 按会话组装 agent | | [`guard/`](guard/README.zh.md) | 循环卫生守卫：建议性重复调用提醒 + `tools/execute` 截止时间强制执行器 | | [`bundle/`](bundle/README.zh.md) | 可安装的 `dsh --profile` 补丁层 | | [`extensions/`](extensions/README.zh.md) | agent 运行时自修改：实时插件/服务检查与模型所写挂载/卸载 | | [`hooks/`](hooks/README.zh.md) | 钩子桥接 + 共享的 Claude Code / Codex 线协议库 | | [`session/`](session/README.zh.md) | 持久会话数据平面：持久化 seam + 后端、投影 seam、基于日志的标题、会话上报 | | [`session-query/`](session-query/README.zh.md) | 会话检索系列：逻辑语料库、有界读取、血缘、语义过滤、SQLite 全文搜索 | | [`settings/`](settings/README.zh.md) | 用户设置 seam + 基于文件的提供方 | | [`credentials/`](credentials/README.zh.md) | 凭据引用/记录 seam + 环境变量优先于 `.env` 的提供方 + 询问人类的授权 flow | | [`storage/`](storage/README.zh.md) | 非会话存储中枢 + 后端 + 领域形式 | | [`workspace/`](workspace/README.zh.md) | Workspace 实体 | | [`sdk/`](sdk/README.zh.md) | 进程外 SDK：JSON-RPC 协议与 TypeScript 客户端／服务器 | | [`acp/`](acp/README.zh.md) | 仅面向自动化的 Agent Client Protocol 服务器 | | [`interaction/`](interaction/README.zh.md) | 人机协作平面：批准/交互 seam、权限预设、命令、询问用户的工具 | | [`boot/`](boot/README.zh.md) | 共享的 app bin 启动粘合层 | | [`host/`](host/README.zh.md) | web GUI 宿主半侧：API 网关 + HTTP 路由服务器 | | [`client/`](client/README.zh.md) | web GUI 浏览器半侧：shell、协议层、对象服务、slot、`ui-*` 插件 | | [`test-support/`](test-support/README.zh.md) | 支持基础设施（testkit、不变式、回放、Loader 冒烟测试） | | [`runtime-diagnostics/`](runtime-diagnostics/README.zh.md) | 运行时诊断：按包归属的运行时不变式检查与报告 | | [`util/`](util/README.zh.md) | 组间共享的低层零依赖工具（`Branded`、home/路径辅助函数、超时、留存） | ----- ## 发布预期 大多数组是产品——稳定 API。例外：`e2b/` 是 POC，`experimental/` 不发布，`test-support/`、`runtime-diagnostics/` 与 `util/` 是兼容性预期较低的支持组。 ----- ## 依赖 依赖图由工具生成：[docs/module-graph.md](../docs/module-graph.zh.md)（`pnpm run gen-module-graph`，CI 中有新鲜度门禁）。 **扩展插件依赖 Service Definition，绝不依赖具体提供方。** `dsh-agent-loop` 可替换；UI、钩子和工具插件使用 `dsh-agent`。组合包可以依赖主干插件。能力在需要独立演进时分离 Service Definition / Service Provider / Consumer 角色；详见[能力 seam](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md)。 ----- ## 包 README 约定 每个包 README 都覆盖用途、配置、扩展点与[模型体验](../docs/cookbook/adding-a-package.zh.md#4-write-the-package-readme)，列入模型无关[省略允许清单](../scripts/verify-package-readme-model-experience.ts)的包除外。它还要包含 `## Known Limitations and Deferred Work`，或列入其[允许清单](../scripts/verify-package-readme-limitations.ts)。包约定——导出、服务访问、不变式、测试——见 [packages/AGENTS.md](AGENTS.md)。 ----- ## 开发备注
维护者的工作上下文——点击展开 无。
# core/ 产品 API 主干：会话、提示词、工具、agent 服务与具体循环 ``` --- description: "core 分组地图：构成产品 API 主干的会话日志、系统提示词组装、工具注册表、agent 词汇与默认循环。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 core 分组提供 DeepSeek Harness 的产品 API 主干：仅追加的会话日志、系统提示词组装、工具注册表、`Agent` 句柄，以及驱动它们的具体循环。每个组合都会启动这些包，插件与消费方构建所依赖的正是它们稳定的约定。一个轮次会流经其中全部环节——循环领取提示词，在会话日志上打开轮次，通过 system-prompt 组装请求，流式接收模型响应，通过注册表分发工具调用，并把每个模型可见的事实追加回日志。构建或扩展 agent 时请选择本分组；默认产品组合是 [`dsh-base`](../bundle/base/README.zh.md)。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | ctx key | |---|---|---| | [`scope/`](scope/README.zh.md) | 隔离单个 agent 贡献的作用域注册与事件路由 | 库，不使用 ctx key | | [`session/`](session/README.zh.md) | 每个 agent 的历史都由其派生的仅追加会话事件日志 | `ctx.sessions` | | [`system-prompt/`](system-prompt/README.zh.md) | 由有序段、工具 schema 与变量进行的系统提示词组装 | `ctx.systemPrompt` | | [`tools/`](tools/README.zh.md) | 循环分发所经过的工具注册表与受守卫的执行流水线 | `ctx.tools` | | [`agent-tool-presentation/`](agent-tool-presentation/README.zh.md) | 为 preset 提供按 agent 的工具呈现方式选择器 | 无 ctx key | | [`agent/`](agent/README.zh.md) | 插件面向编程的 `Agent` 句柄，以及其实时注册表与事件 | `ctx.agents` | | [`agent-default-model/`](agent-default-model/README.zh.md) | 入口对全新 agent 应用的部署默认模型选择 | `ctx.agentDefaultModel` | | [`agent-loop/`](agent-loop/README.zh.md) | 默认 agent 驱动器：创建 agent 并运行轮次与步骤生命周期 | `ctx.agentLoop` | `scope` 提供共享作用域原语；`agent` 拥有公开的 `Agent` 约定，而 `agent-loop` 是其默认实现，因此扩展插件依赖 `agent`，驱动器保持可替换。`agent-default-model` 拥有会话自身没有选择时由入口应用的部署选择。可运行组合位于 [`packages/bundle`](../bundle/README.zh.md)；本分组只拥有可替换的主干组件。 ----- ## 相关文档 - [Core 子系统](../../docs/subsystems/core.zh.md)——逐包循环图与 `Agent` 句柄约定。 - [会话子系统](../../docs/subsystems/session.zh.md)——会话事件词汇与派生历史。 - [系统提示词子系统](../../docs/subsystems/system-prompt.zh.md)——提示词段、动态上下文与工具 schema 类型。 - [工具子系统](../../docs/subsystems/tools.zh.md)——工具执行流水线与呈现词汇。 - [作用域注册子系统](../../docs/subsystems/scope.zh.md)——这些注册表所依赖的作用域层原语。 - [架构](../../docs/architecture.zh.md)——轮次流与新行为归属。 - [基础组合包](../bundle/base/README.zh.md)——默认产品组合。 - [SDK 最小组合包](../bundle/sdk-minimal/README.zh.md)——完整、独立且功能集更小的组合。 ----- ## 开发备注
维护者的工作上下文——点击展开 无。
# api/ Remote BFF 装配与 Typert RPC 网关 ``` --- description: "应用 Remote 层的包映射：类型化的 Client 到 Host 能力调用、结果与转发事件，供用户与维护者浏览该组。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 `api/` 组提供应用的 Remote 层：Client 环境可以调用运行在 Host 上的业务能力——管理目标、运行命令、查看插件清单、发现文件与会话引用——调用方式是类型化方法，并接收结果或转发的 Host 事件。`remotes` 决定暴露哪些能力、以及每次调用如何到达正确会话的 agent；`gateway` 在 Client 与 Host 之间承载调用及其结果。技术栈运行在应用共享的 Connection 之上；流式会话数据刻意不在其中。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 下面这些包共同提供 Remote 层；穷尽式约定以各包 README 为准。 | 包 | 职责 | ctx key | |---|---|---| | [`remotes/`](remotes/README.zh.md) | 决定 Client 可以消费哪些 Host 能力与事件。 | — | | [`gateway/`](gateway/README.zh.md) | 承载带类型的单次调用、多路复用 stream 与转发的 Host 事件。 | `ctx.typertGateway` / `ctx.remote` | | [`session-controller/`](session-controller/README.zh.md) | 拥有 Session 命令、历史 stream、实时控制状态与 Agent/Session 身份策略。 | `ctx.sessionController` / `ctx.remote.session` | | [`settings-controller/`](settings-controller/README.zh.md) | 拥有 settings 域各 seam 之上的配置界面读写。 | `ctx.settingsController`、`ctx.credentialsController` / `ctx.remote.settings`、`ctx.remote.credentials` | | [`workspace-controller/`](workspace-controller/README.zh.md) | 拥有 Workspace 变更与完整 Client Workspace 投影。 | `ctx.workspaceController` / `ctx.remote.workspace` | Remote 调用沿 Client → Host 方向运行在应用共享的 Connection 之上。API Gateway 拥有 Remote 传输，各 controller 包分别拥有 Session、配置界面与 Workspace 行为。流式下载等不适合 Remote 调用的响应由功能包注册精确的 Connection Fetch 路由。 ----- ## 相关文档 先读 API Gateway 参考以端到端了解 Remote 模型，再读 Typert 子系统页了解共享定义，并通过 Connection 了解物理载体。 - [API Gateway 参考](../../docs/api-gateway.zh.md)——Typert API Gateway 的现状参考：编程模型、生成流水线与运行时调用。 - [Typert 子系统参考](../../docs/subsystems/typert.zh.md)——protocol、Gateway 与消费方装配共享的公共约定。 - [Connection](../client/connection/README.zh.md)——每次 Remote 调用背后的 RPC 载体、`/api` 信任围栏与响应封装。 ## 开发备注
维护者的工作上下文——点击展开 无。
# typert/ 类型图生成、产物加载与运行时注册表 ``` --- description: "typert 组地图：构建时类型图生成器、运行时注册表、Loader 集成与共享 Remote 协议，它们共同支撑类型化的 Host 到 Client 调用。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 借助 typert 组，Client 环境能以类型化方法调用 Host 能力，并在无需手写协议代码的情况下共享生成的 schema 与反射信息。构建时生成器把源代码类型声明转换为与编译器无关的模型与运行时产物，运行时注册表保存这些产物，Loader 集成则在 Loader 组合中自动注册它们。共享的协议包提供 Remote 调用声明——装饰器、wire 描述符、编解码器与提供方约定——供业务包、生成产物、Host Gateway 与 Client API 共同消费。本页是四个包的索引；每个包的 README 负责各自的配置、用法与限制。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | ctx 键 | |---|---|---| | [`generator/`](generator/README.zh.md) | 在构建时分析源代码类型，并生成运行时加载所需的反射、schema 与 Remote 描述符 | — | | [`loader/`](loader/README.zh.md) | 把 Loader 组合中的生成 Typert 产物自动注册到运行时注册表 | 消费 `ctx.loader` 与 `ctx.typert` | | [`protocol/`](protocol/README.zh.md) | 声明 Host 与 Client 共享的 Remote 装饰器、wire 描述符、编解码器与提供方约定 | — | | [`registry/`](registry/README.zh.md) | 在运行时保存生成的包反射与实时 Zod schema，并提供 lookup 与 Context 提供方注册表 | `ctx.typert` | ----- ## 相关文档 - [Typert 子系统参考](../../docs/subsystems/typert.zh.md)——从协议与注册表类型记录的字面公共约定。 - [API Gateway 参考](../../docs/api-gateway.zh.md)——生成的 Remote 描述符如何成为实际的 Host 到 Client 调用。 - [Remote 调用 Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md)——Remote 调用背后的架构与传输决策。 - [包工作区地图](../README.zh.md)——工作区中的每个组及其职责。 ----- ## 开发备注
维护者的工作上下文——点击展开 无。
# goal/ 同会话 goal 的持久化与生命周期 ``` --- description: "goal 组地图：每会话一个持久的完成目标，以及模型工具、用户命令与自动续行，供浏览本组的用户与维护者阅读。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 goal 组为 agent 会话提供一个持久的完成目标，在重启、resume（恢复）与 fork 后依然存在：goal 服务持久保存状态与生命周期，模型工具让 agent 创建和更新 goal，`/goal` 命令让用户无需模型轮次即可直接控制 goal，续行驱动器则把 active 的 goal 变成连续多轮的自动工作。goal 状态保存在会话日志中，组内没有任何独立存储。同一时刻只有一个当前 goal；goal 是状态而非调度器——自动续行是需要你刻意挂载的可选消费方。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | ctx 键 | |---|---|---| | [`goal`](goal/README.zh.md) | 每会话一个持久 goal：create、edit、pause、resume、complete、block 和 clear | `ctx.goals` | | [`tool-goal`](tool-goal/README.zh.md) | 模型工具 `get_goal`、`create_goal`、`update_goal` | 注册到 `ctx.tools` | | [`command-goal`](command-goal/README.zh.md) | UI 命令平面中的用户 `/goal` 命令 | 注册到 `ctx.commands` | | [`goal-round-driver`](goal-round-driver/README.zh.md) | 自动续行：把 active 的 goal 变成连续多轮 | 无服务键 | ----- ## 相关文档 - [goal 子系统](../../docs/subsystems/goal.zh.md)——goal 类型、持久的 `goal/change` 事件与生成的服务 API。 - [生成的工具目录](../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-goal)——模型接收的三个 goal 工具 schema。 - [生成的配置目录](../../docs/config-catalog.zh.md#deepseek-aidsh-goal)——goal 服务的每个受支持配置字段。 - [goal 领域 Agent Note](../../.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.zh.md)——领域设计及其决策。 - [同会话驱动器 Agent Note](../../.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md)——续行竞态与生命周期理由。 ----- ## 开发备注
维护者的工作上下文——点击展开 无。
# schedule/ — 仅限会话内的提醒 ``` --- description: "schedule 组地图：基于会话日志的会话本地持久提醒，供浏览本组的用户与维护者阅读。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 schedule 组为运行中的会话提供会话本地提醒：让 agent 在稍后、绝对时间或固定间隔提醒你，每条提醒到期时都会作为同一会话中的普通消息到达。它的宿主包拥有三个管理工具，并可通过可选的 Session projection registry 发布完整活动记录集合。独立的 [`ui-schedule`](../client/ui-schedule/README.zh.md) 浏览器插件把该 projection 渲染为只读的当前状态目录，[`ui-workspace`](../client/ui-workspace/README.zh.md) 则为尽力而为的列表值明确非空的普通行与搜索结果显示闹钟。该标识只报告缓存所知的活动状态，不保证 live runtime 存在。提醒在重启后依然存在，但只留在会话内部：没有电子邮件、短信或推送通知。本页是组地图；各包 README 拥有自己的约定。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | ctx key | |---|---|---| | [`schedule/`](schedule/README.zh.md) | 会话本地提醒：安排、列出并取消活动记录；发布供 header 目录与列表行标识读取的可选只读 projection；把到期提醒作为会话消息交付 | —（工具只注册在精确的 agent scope 中） | ----- ## 相关文档 - [仅限会话内的 Schedule 子系统](../../docs/subsystems/schedule.zh.md)——持久记录、转换、视图与交付约定。 - [生成的工具目录](../../docs/tool-catalog.zh.md#deepseek-aidsh-schedule)——模型接收的 `schedule_create`／`schedule_list`／`schedule_delete` schema。 - [Schedule 用户指南](../../docs/user/guide/schedule.zh.md)——挂载本包的官方配置路径。 - [Web Schedule 目录](../client/ui-schedule/README.zh.md)——活动记录的可选只读浏览器呈现。 ----- ## 开发备注
维护者的工作上下文——点击展开 无。
# feedback/：记录的人类反馈 ``` --- description: "feedback 包组：关于会话与 assistant 消息的用户反馈，供用户与维护者选择、组合或排查反馈采集。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 feedback 组收集用户对 harness 工作成果的意见：用户可以提交一条关于整个会话的自由文本评价，也可以对单条 assistant 消息评分或加备注。两类反馈都不会到达模型——它们是关于输出的信号，绝不是输入。用户通过 `/feedback` 命令记录会话评价；产品界面通过 `messageFeedback` 服务读取和修改逐消息评分。两个包相互独立：会话评价与逐消息评分互不影响。本页是组的映射；包 README 与[反馈子系统页](../../docs/subsystems/feedback.zh.md)负责各自的包级约定。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ## 包 | 包 | 职责 | |---|---| | [`command-feedback`](command-feedback/README.zh.md) | 一条命令即可记录自由文本会话评价的 `/feedback` 命令，无需模型轮次 | | [`message-feedback`](message-feedback/README.zh.md) | 逐消息评分与备注，通过 `messageFeedback` 服务提供给产品界面 | 会话评价是单向信号：在对话的任何时刻记录它都是安全的，且绝不会改变模型看到的内容。在 feedback-gated 共享策略下，记录会话评价正是释放会话共享的动作。 逐消息评分与备注与会话一起保存，重启后依然存在，并且绝不会出现在模型历史或遥测中。 ## 相关文档 - [反馈子系统](../../docs/subsystems/feedback.zh.md)——message-feedback 的类型、服务契约与 Web 消费方。 - [会话遥测子系统](../../docs/subsystems/session-telemetry.zh.md)——`/feedback` 确认文本披露的共享策略。 - [匿名用户身份](../identity/README.zh.md)——嵌入反馈确认文本的按 harness home 共享 id。 ## 开发备注 无。 # identity/ — 共享身份 ``` --- description: "identity 包组：由遥测、反馈与 DeepSeek 提供方请求共享的匿名按 harness home 关联 id。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 identity 组为每个 harness home 提供一个匿名 id，该安装的遥测、反馈与 DeepSeek 请求会把它附加到各自的记录上，因此离开同一个 home 的所有内容都能被识别为来自同一套安装，而无需识别用户身份。无需配置任何东西：id 会在这些功能之一首次运行时自动出现，并在文件被删除前保持稳定。本组只有一个包；本页是组的映射，包 README 负责细节。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ## 包 | 包 | 职责 | |---|---| | [`anonymous-user-id`](anonymous-user-id/README.zh.md) | 让每个 harness home 拥有一个匿名 id，遥测、反馈与 DeepSeek 请求把它附加到记录上，使来自同一安装的记录无需识别用户即可被辨认 | ## 相关文档 - [会话遥测子系统](../../docs/subsystems/session-telemetry.zh.md)——在导出中携带该 id 的遥测功能。 - [dsh-llm-deepseek](../llm/llm-deepseek/README.zh.md)——在请求中携带该 id 的 DeepSeek 提供方。 - [dsh-command-feedback](../feedback/command-feedback/README.zh.md)——在确认文本中点名该匿名安装的反馈命令。 ## 开发备注 无。 # llm/ — LLM 能力家族 ``` --- description: "LLM 能力包组：一个提供方无关的模型调用服务、DeepSeek 与 pi-ai 提供方适配器、请求重试执行器，以及具备回放感知的 token 计量。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 llm 组提供 harness 的模型调用能力：一个提供方无关的服务，任何组合都可以通过它向模型提供方发起流式请求，外加适配器、提供方专用请求元数据、重试执行与计量。核心 `llm` 包定义所有插件与会话日志使用的消息、内容块与流式分片词汇；提供方适配器把某个提供方的协议格式翻译为该词汇；DeepSeek 请求扩展插件在模型输入之外贡献具有生命周期归属的元数据；`llm-retry` 在持久 agent 步骤边界上重跑失败的请求；`token-meter` 从持久日志测量请求与上下文压力。本页是组的映射；每个包 README 负责各自的包级约定。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | ctx key | |---|---|---| | [`llm/`](llm/README.zh.md) | 通过已注册的提供方适配器流式发起一次模型调用，并共享 harness 的消息、块与分片词汇 | `ctx.llm` | | [`llm-deepseek/`](llm-deepseek/README.zh.md) | 以 DeepSeek chat-completions 直连、thinking 与图片输入服务 `deepseek-official` 路由 | 注册到 `ctx.llm` | | [`llm-pi-ai/`](llm-pi-ai/README.zh.md) | 通过 pi-ai 目录与协议格式服务配置的提供方路由，包括手工声明的网关 | 注册到 `ctx.llm` | | [`deepseek-llm-api-extensions/`](deepseek-llm-api-extensions/README.zh.md) | 在官方 DeepSeek 请求上注册具有生命周期归属的顶层字段 | `ctx.deepseekLlmApiExtensions` | | [`plugin-package-inventory-deepseek/`](plugin-package-inventory-deepseek/README.zh.md) | 为官方 DeepSeek 请求贡献活跃 Loader 包清单 | 贡献 `dsh_plugin_packages` | | [`llm-retry/`](llm-retry/README.zh.md) | 在持久 agent 步骤边界上按各提供方策略重试失败的模型请求 | 监听 `agent/request-error` | | [`token-meter/`](token-meter/README.zh.md) | 用固定启发式规则从持久会话日志测量请求与上下文压力 | `ctx.tokenMeter` | ----- ## 相关文档 - [LLM 流式子系统](../../docs/subsystems/llm-streaming.zh.md)——消息与块类型、组装后的模型请求、`StreamChunk` 协议与适配器约定。 - [Token 计量子系统](../../docs/subsystems/token-meter.zh.md)——`ctx.tokenMeter` 背后的测量语义。 - [孪生 LLM 适配器](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.zh.md)——为什么 DeepSeek 路由交付两个结构不同的适配器。 - [按路由的模型上下文](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.zh.md)——loop 如何路由模型请求并压缩上下文。 - [回放 token 计量服务](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.zh.md)——具备回放感知的计量背后的设计。 ## 开发备注 无。 # e2b/ E2B 远程运行时提供方 ``` --- description: "E2B 远程运行时组映射：把文件与命令工作放进一个远程 Linux 沙箱，供 E2B 家族的用户与维护者浏览。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 e2b 组把 agent（智能体）的文件与命令工作移入远程 Linux 沙箱：文件读写、shell 命令与终端都在同一个远程世界中运行，而不是在你的机器上。三个包协同工作——一个提供共享沙箱，一个让文件操作在其中运行，一个让命令与终端在其中运行。启用本家族后，现有的 shell、终端与语言服务器功能无需任何改动即可继续工作，因此不需要 E2B 专用工具。harness 进程、模型调用与会话状态永远不会移动——只有执行世界是远程的，而且沙箱是短暂的。这是一个实验性 POC，任何已发布的组合都不会默认启用它。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包（package） | 职责 | ctx 键 | |---|---|---| | [`e2b`](e2b/README.zh.md) | 文件与命令工作运行所在的共享远程 Linux 沙箱 | `ctx.e2b` | | [`fs-e2b`](fs-e2b/README.zh.md) | 远程沙箱内的文件读取、写入、编辑与列表 | `ctx.fs` | | [`subprocess-e2b`](subprocess-e2b/README.zh.md) | 远程沙箱内的 shell 命令与交互式终端 | `ctx.subprocess` | ----- ## 相关文档 - [可移植执行世界决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md)——执行世界为何可以在不移动 harness 的情况下迁移，以及哪些内容留在本地。 - [子进程子系统](../../docs/subsystems/subprocess.zh.md)——子进程 seam 约定与生成的 Cordis 表面，包括 `ctx.e2b`。 - [文件系统子系统](../../docs/subsystems/filesystem.zh.md)——文件系统 seam 约定与生成的 Cordis 表面。 ----- ## 开发备注
维护者的工作上下文——点击展开 无。
# subprocess/：子进程能力家族 ``` --- description: "subprocess 组地图：共享的子进程服务及其本地宿主提供方，供浏览本组的用户与维护者阅读。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 harness 运行的每个子进程与终端会话——bash 命令、语言服务器、持久 shell 与进程外 subagent 后端——都经由一个共享服务（`ctx.subprocess`）启动、观察与终止，并由一个本地提供方在宿主机器上执行。它不是独立的产品功能：消费方能力 seam 决定每个进程的含义，命令语义、时限与面向模型的呈现仍归它们所有。本组提供可执行文件查找、带 spill 恢复的有界输出捕获、整棵进程树的终止，以及每个子进程起步时所用的清理后环境。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | ctx 键 | |---|---|---| | [`subprocess`](subprocess/README.zh.md) | 定义子进程服务：可执行文件查找、受管进程 spawn 与真实终端会话 | `ctx.subprocess` | | [`subprocess-local`](subprocess-local/README.zh.md) | 在宿主机器上运行这些进程与终端 spawn | 注册到 `ctx.subprocess` | | [`win32-process`](win32-process/README.zh.md) | 归属受限进程创建、stdio、Job 分配、等待与句柄清理所用的共享 Win32 绑定 | 库，不使用 ctx key | 即使消费方重载，进程生命周期仍由服务负责管理；消费方负责定义进程的含义（一条 bash 命令、一个语言服务器），以及决定塑造该进程的每一项默认值。 ----- ## 相关文档 - [子进程子系统](../../docs/subsystems/subprocess.zh.md)——spawn spec、输出读取器、结果与受管的 `DSH_*` 环境。 - [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md)——bash 执行器的进程部分为何成为独立的 seam。 ----- ## 开发备注
维护者的工作上下文——点击展开 无。
# shell/ — bash 能力家族 ``` --- description: "面向部署方与维护者的 bash 能力家族说明，用于选择并组合 shell 执行器、沙箱化与面向模型的 bash 与 pwsh 工具。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 shell 组为 agent 提供命令执行能力：运行前台命令并读取其有界输出，或启动后台进程并轮询它——在 POSIX 上用 Bash，在 Windows 上用 PowerShell。每个组合恰好挂载一个执行器实现；沙箱执行器会通过沙箱能力限制每条命令，面向模型的 `bash` 与 `pwsh` 工具则位于所挂载执行器之上。POSIX 选择 Bash 执行器，Windows 选择 PowerShell 执行器；命令需要文件级隔离时选择沙箱变体。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | ctx key | |---|---|---| | [`shell`](shell/README.zh.md) | 定义执行器约定：前台运行、后台句柄与请求解析 | `ctx.shell` | | [`bash-local`](bash-local/README.zh.md) | 在 POSIX 上以全新 `bash -c` 进程运行 Bash 命令 | 注册 `ctx.shell` | | [`bash-sandbox`](bash-sandbox/README.zh.md) | 通过沙箱能力限制 Bash 命令运行，并把拒绝报告为事实 | 注册 `ctx.shell` | | [`pwsh-local`](pwsh-local/README.zh.md) | 在 Windows 上以全新 `pwsh -Command` 进程运行 PowerShell 命令 | 注册 `ctx.shell` | | [`pwsh-sandbox`](pwsh-sandbox/README.zh.md) | 通过沙箱能力限制 PowerShell 命令运行 | 注册 `ctx.shell` | | [`shell-env`](shell-env/README.zh.md) | 提供每条 shell 命令都会收到的受管 `DSH_*` 环境 | `ctx.shellEnv` | | [`tool-bash`](tool-bash/README.zh.md) | 以 `bash` 工具向模型公开 Bash 执行与后台任务 | 注册到 `ctx.tools` | | [`tool-bash-persistent`](tool-bash-persistent/README.zh.md) | 在单个限定所有者范围的持久 Bash 会话中运行模型的 shell 调用 | 注册到 `ctx.tools` | | [`tool-pwsh`](tool-pwsh/README.zh.md) | 以 `pwsh` 工具向模型公开 PowerShell 执行 | 注册到 `ctx.tools` | | [`tool-pwsh-persistent`](tool-pwsh-persistent/README.zh.md) | 在单个限定所有者范围的持久 PowerShell 会话中运行模型的 shell 调用 | 注册到 `ctx.tools` | profile 层恰好选择一个执行器实现（win32 层会把 POSIX 行换成 pwsh 行；同时挂载两个会因服务重复注册而在加载期失败）以及所需的面向模型工具。沙箱化组合还会选择一个 `ctx.sandbox` 提供方与 `ctx.sandboxPolicy`；[base bundle](../bundle/base/cordis.patch.yml)拥有随附接线。 ----- ## 相关文档 - [Bash 执行器子系统](../../docs/subsystems/shell.zh.md) —— 共享的请求/spec 词汇、结果、后台进程与完整的服务约定。 - [沙箱子系统](../../docs/subsystems/sandbox.zh.md) —— 沙箱执行器所消费的隔离能力。 ## 开发备注 None. # terminal/：持久 PTY 能力家族 ``` --- description: "持久终端能力家族的包映射：限定所有者范围的 ctx.terminals 服务、启动交互式 bash 或 pwsh 的 shell 后端，以及 6 个面向模型的工具。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 `terminal/` 组为 agent 提供持久且限定所有者范围的终端会话：shell 与 REPL 状态——cwd、导出的变量、激活的环境、正在运行的交互式子进程——都能跨工具调用存活。三个包共同覆盖整个家族：`terminal/` 提供限定所有者范围的 `ctx.terminals` 会话服务（会话获得不透明 id，每个操作都限制在所属 agent 内）；`terminal-bash/` 在共享沙箱策略下启动交互式 bash 或 pwsh shell；`tool-terminal/` 提供 6 个结果有界的面向模型工具。终端是单次 bash 与文件系统工具的补充：仅在需要交互式 stdin 或跨调用状态时使用。会话只存在于进程本地，harness 重启后不会恢复。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 该家族包含一个会话服务、一个 shell 后端与一组面向模型的工具。完整约定由各子级 README 负责；共享词汇与生成的服务接口面由子系统参考负责。 | 包 | 角色 | ctx 键 | |---|---|---| | [`terminal/`](terminal/README.zh.md) | 会话服务：限定所有者范围的会话、不透明 id、精确到所有者的限制与等待完成的清理 | `ctx.terminals` | | [`terminal-bash/`](terminal-bash/README.zh.md) | shell 后端：在共享沙箱策略下启动交互式 bash 或 pwsh，带就绪检测与有界输出 | 注册后端到 `ctx.terminals` | | [`tool-terminal/`](tool-terminal/README.zh.md) | 6 个面向模型的工具，带所有者隔离与可选后台发送 | 注册到 `ctx.tools` | ----- ## 相关文档 先从子系统参考了解共享类型与服务接口面，再从 Agent Note 了解设计理由与暂缓边界。 - [终端子系统参考](../../docs/subsystems/terminal.zh.md)——id、后端与会话约定、发送就绪、有界读取，以及生成的 `ctx.terminals` API。 - [持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md)——设计决策、备选方案与延期工作。 - [能力 seam](../../docs/capability-seams.zh.md)——本家族遵循的 Service Definition / Service Provider / Consumer 拆分。 ## 开发备注
维护者的工作上下文——点击展开 无。
# code-runtime/——代码执行能力族 ``` --- description: "代码执行能力族的包映射：程序执行能为你做什么，以及每个部分由哪个包负责。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 `code-runtime/` 组提供程序执行能力：模型编写一个程序，把宿主提供的函数当作普通异步调用，运行时在隔离环境中执行它，只返回程序打印和返回的内容。一个包定义共享能力（`ctx.codeRuntime`），第二个包在全新的 Node Worker 线程中执行 TypeScript 程序，第三个包持有 Node host 与 CPython 子进程之间的 fd-3 协议格式（wire protocol），为 Python 后端服务。每次运行彼此独立——程序之间不保留任何状态——失败也会作为结果的一部分返回，调用方因此能知道程序为何失败，并把它反馈给模型。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 这三个包共同提供程序执行能力；每个 README 描述其各自部分做什么。 | 包 | 角色 | ctx 键 | |---|---|---| | [`code-runtime/`](code-runtime/README.zh.md) | 定义代码运行时做什么：针对宿主提供的绑定运行一个程序，并报告其打印和返回的内容 | `ctx.codeRuntime` | | [`code-runtime-worker-thread/`](code-runtime-worker-thread/README.zh.md) | 在全新的 Node Worker 线程中执行 TypeScript 程序 | 注册 `ctx.codeRuntime` | | [`experimental/code-runtime-python/`](../experimental/code-runtime-python/README.zh.md) | 实验性 Python 后端：持有 Node host 与 CPython 子进程之间的 fd-3 协议格式与 CPython 运行时实现 | — | ----- ## 相关文档 先从子系统参考了解服务约定，再看消费此能力的 PTC mode 设计，以及它所遵循的能力 seam 模型。 - [代码运行时子系统参考](../../docs/subsystems/code-runtime.zh.md)——请求／结果词汇、绑定与 `ctx.codeRuntime` 的 cordis 接口面。 - [PTC mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-ptc.zh.md)——工具注册表如何把 `run_code` 呈现给模型。 - [能力 seam](../../docs/capability-seams.zh.md)——本家族遵循的 Service Definition / Service Provider / Consumer 拆分。 ## 开发备注
维护者的工作上下文——点击展开 无。
# sandbox/ 进程限制 seam；bwrap/Landlock/Seatbelt 后端 ``` --- description: "进程沙箱包组：隔离 seam、各平台后端、共享策略解析器与 Windows 写入限制档。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 `sandbox/` 组将子进程执行限制在文件效果策略之下：命令以 `read-only` 运行、只能写入会话工作区（`workspace-write`）或不受限制地运行（`danger-full-access`）。四个包交付该能力：隔离服务（`sandbox/`）、面向 Linux、macOS 与 Windows 的各平台后端（`sandbox-local/`）、共享策略解析器（`sandbox-policy/`）与 Windows 写入限制后端（`sandbox-windows-acl/`）。被策略拒绝的受限调用可以通过用户批准的一次性升权重试。隔离仅限同世界：它与宿主共享内核与文件系统，容器、microVM 与远程执行器会替换整个能力，而不是在此注册。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 四个包承担隔离角色；子系统参考文档拥有穷尽式约定与逐调用策略语义。 | 包 | 职责 | ctx key | |---|---|---| | [`sandbox/`](sandbox/README.zh.md) | 隔离服务约定：模式、强制执行、逐调用策略与升权词汇 | `ctx.sandbox` | | [`sandbox-local/`](sandbox-local/README.zh.md) | 各平台隔离后端：Linux bwrap 与 Landlock、macOS Seatbelt、Windows 受限令牌 | 注册到 `ctx.sandbox` | | [`sandbox-policy/`](sandbox-policy/README.zh.md) | 共享策略归属：每个执行家族的部署默认值与逐会话模式覆盖 | `ctx.sandboxPolicy` | | [`sandbox-windows-acl/`](sandbox-windows-acl/README.zh.md) | Windows 写入限制：受限子进程只能写入工作区与私有临时目录 | —（由 `sandbox-local` 挂载为 win32 后端） | ----- ## 相关文档 先从子系统参考文档了解共享词汇，再看隔离决策及其跨家族扩展。 - [进程沙箱子系统](../../docs/subsystems/sandbox.zh.md)——模式、逐调用策略、包装 argv 方言与故障关闭错误。 - [子进程沙箱决策](../../.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md)——能力边界、升权编排与延期阶段。 - [跨家族文件沙箱决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md)——统一的共享策略归属与沙箱化文件系统提供方。 - [Windows ACL 受限令牌沙箱决策](../../.agents/notes/implemented/feature/2026-08-08-windows-acl-restricted-token-sandbox.zh.md)——为何选择原始 ACL 受限令牌而非 mxc 与 AppContainer。 ## 开发备注
维护者的工作上下文——点击展开 无。
# fs/ 文件系统能力系列：seam、本地实现、面向模型的文件工具、发现工具 ``` --- description: "文件系统包组：`ctx.fs` 提供方约定、本地与沙箱强制后端、编辑前读取策略插件，以及面向模型的文件与搜索工具。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 `fs/` 组为 agent（智能体）提供持久、受策略约束的文件访问：`fs/` 定义 `ctx.fs` 服务约定，`fs-local/` 与 `fs-sandbox/` 提供宿主文件系统与沙箱强制后端，`fs-observation-policy/` 提供编辑前读取策略，`tool-fs/`（`read`、`read_image`、`write`、`edit`）与 `tool-fs-search/`（`glob`、`grep`）提供面向模型的工具。部署挂载一个后端，加载策略以获得新鲜度防护的变更，并注册模型应看到的工具包；后端可以更换，无需改动工具或策略。文件 I/O 有意不设超时：deadline 只会杀掉操作系统仍会完成的工作，因此取消只是系统调用边界的尽力而为信号。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 七个包加上远程同级 `fs-e2b` 承担文件系统角色；子系统参考文档拥有穷尽式约定与错误分类体系。 | 包 | 职责 | ctx 键 | |---|---|---| | [`fs/`](fs/README.zh.md) | `ctx.fs` 服务约定：执行世界路径、有界文本 I/O，以及带可选版本防护的原子变更 | `ctx.fs` | | [`fs-local/`](fs-local/README.zh.md) | 宿主文件系统后端：读取、写入并编辑本机上的真实文件 | 注册到 `ctx.fs` | | [`fs-sandbox/`](fs-sandbox/README.zh.md) | 沙箱强制后端：按每次调用的沙箱模式约束写入与编辑，读取直接通过 | 注册到 `ctx.fs` | | [`e2b/fs-e2b`](../e2b/fs-e2b/README.zh.md) | 以 E2B 为后端：文件状态位于与 E2B 子进程提供方共享的远程执行世界 | 注册到 `ctx.fs` | | [`fs-observation-policy/`](fs-observation-policy/README.zh.md) | 编辑前读取策略：记录观测到的存在或缺失，并通过 `fs/*` 事件防护写入/编辑 | `fs/*` 监听器 | | [`tool-fs/`](tool-fs/README.zh.md) | 面向模型的 `read`、`read_image`、`write` 与 `edit` 工具及其执行器 | 注册到 `ctx.tools` | | [`tool-fs-search/`](tool-fs-search/README.zh.md) | 由打包 ripgrep 二进制支持的面向模型 `glob` 与 `grep` 发现工具 | 注册到 `ctx.tools` | | [`tool-str-replace-editor/`](tool-str-replace-editor/README.zh.md) | 独立的 `str_replace_editor` 工具：基于 `ctx.fs` 的 `view`、`create`、`str_replace` 与 `insert` | 注册到 `ctx.tools` | 策略是插件，不是工具注入的服务：移除它只会让工具回到裸提供方的无条件变更行为，而不会破坏工具。`fs-sandbox` 的模式围栏与编辑前读取门禁可以组合。`tool-fs-search` 有意不扩展提供方约定——搜索是由进程支持的 ripgrep 工作流，因此文件系统后端无需承担通用搜索 API。 ----- ## 相关文档 先从子系统参考文档了解共享词汇与错误分类体系，再看塑造该家族的设计决策。 - [文件系统子系统](../../docs/subsystems/filesystem.zh.md)——目标、结果、防护、策略事件与错误分类体系。 - [跨能力族 fs 沙箱决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md)——文件系统 seam 上共享的沙箱模式围栏。 - [可移植执行世界消费方决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md)——E2B 后端为何共享远程执行世界。 ## 开发备注
维护者的工作上下文——点击展开 无。
# lsp/：语言服务器代码导航 ``` --- description: "lsp 组地图：通过 LSP seam、其 stdio 提供方与面向模型的 lsp 工具实现的语言服务器代码导航，供浏览本组的用户与维护者阅读。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 lsp 组为 agent 提供精确的、由语言服务器支撑的代码导航：转到符号的定义、查找其引用、跳转到其实现，或阅读悬停文档，而模型无需知道是哪个服务器在应答。该能力拆分为三个产品包：`dsh-lsp` seam（`ctx.lsp`）按文件扩展名选择提供方并规范化结果，`dsh-lsp-stdio` 提供方驱动配置好的本地语言服务器命令，面向模型的 `dsh-tool-lsp` 工具拥有 `lsp` 的 schema、提示词与呈现。只有提供方与工具在加载后才实际做事；部署需要显式配置服务器命令与扩展名映射，本组自身不随附任何语言服务器。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | ctx key | |---|---|---| | [`lsp/`](lsp/README.zh.md) | 定义代码导航服务：按文件扩展名选择提供方、四种规范化的只读操作与结构化错误 | `ctx.lsp` | | [`lsp-stdio/`](lsp-stdio/README.zh.md) | 通过 `ctx.fs` 与 `ctx.subprocess` 驱动配置好的 stdio 语言服务器命令，注册为提供方 | 注册到 `ctx.lsp` | | [`tool-lsp/`](tool-lsp/README.zh.md) | 通过 `lsp` 工具向模型暴露精确的代码导航 | 注册到 `ctx.tools` | 提供方注册的是能力而非工具：`tool-lsp` 是面向模型的名称、schema、提示词指引与呈现的唯一 owner，因此更换提供方绝不会改变模型请求导航的方式。 ----- ## 相关文档 - [LSP 导航子系统](../../docs/subsystems/lsp.zh.md)——操作、坐标、请求与结果，以及 `LspError` code。 - [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md)——设计原理、备选方案与刻意推迟的 API。 - [生成的工具目录](../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-lsp)——模型接收的 `lsp` schema。 ----- ## 开发备注
维护者的工作上下文——点击展开 无。
# skill/ — skill（技能）能力家族 ``` --- description: "skill 组地图：由提供方发现、并经会话目录与 skill 工具加载的可复用 agent 指令，供浏览本组的用户与维护者阅读。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 skill 组让 agent（智能体）和用户按需使用可复用的任务专项指令。提供方贡献 skill——来自本地项目或用户目录、随包分发或远程服务——注册表合并它们的目录，并为每个名称解析出胜出的 skill。一个消费方把可用 skill 发布为持久的会话目录，并提供面向模型的 `skill` 加载工具，因此模型看到排序后的 skill 名称与简短描述，并能加载任一列出 skill 的完整指令；用户也可以用 `/name` 直接调用 skill。提供方类型不会改变模型看到的内容，因为所有面向模型的渲染都集中在一个消费方包中。按需挂载各包：注册表加至少一个提供方，再加消费方以获得模型访问。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | ctx 键 | |---|---|---| | [`skill/`](skill/README.zh.md) | 合并任意提供方的 skill 目录、并按名称解析出胜出 skill 的注册表 | `ctx.skills` | | [`skill-filesystem/`](skill-filesystem/README.zh.md) | 从项目、自定义与用户目录发现 skill，并监视其变更 | 注册到 `ctx.skills` | | [`skill-badge/`](skill-badge/README.zh.md) | 随包附带官方「powered by dsh」徽章 skill，默认禁用 | 注册到 `ctx.skills` | | [`tool-skill/`](tool-skill/README.zh.md) | 发布会话 skill 目录与面向模型的 `skill` 加载工具 | 注册到 `ctx.tools` | ----- ## 相关文档 先从子系统参考了解共享词汇，再阅读 Agent Note 了解设计依据。 - [skill 子系统参考](../../docs/subsystems/skills.zh.md)——注册表、提供方约定、本地发现优先级，以及目录与工具。 - [skill 系统 Agent Note](../../.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md)——家族如何拆分与分层注册表设计。 - [skill 目录热刷新 Agent Note](../../.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.zh.md)——持久初始目录与替换生命周期。 - [skill 调用策略 Agent Note](../../.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md)——模型与用户调用控制。 ----- ## 开发备注
维护者的工作上下文——点击展开 无。
# compaction/ — 压缩能力家族 ``` --- description: "会话压缩功能家族的包映射：自动压缩、按需 /compact 命令与工具输出修剪。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 `compaction/` 组让长时 agent 会话在接近模型上下文上限时仍能正常工作：token 压力上升时自动把较早历史压缩为摘要，随时可用 `/compact` 按需压缩，超大工具输出也可以先被修剪，从而减少需要压缩的内容。随附 `dsh` 基础配置默认启用该功能——显式挂载各包即可调整压缩发生的时机与方式。决定何时压缩的 token 测量属于独立的 LLM（大语言模型）家族服务。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 以下每个包提供该功能的一个环节；打开对应包页面了解如何使用。 | 包 | 职责 | ctx key | |---|---|---| | [`compaction/`](compaction/README.zh.md) | 共享的压缩约定：所有后端与触发器使用的操作与摘要格式 | `ctx.compaction` | | [`compaction-basic/`](compaction-basic/README.zh.md) | 随 token 压力上升自动把较早历史压缩为摘要 | 注册 `ctx.compaction` | | [`compaction-tool-result-pruner/`](compaction-tool-result-pruner/README.zh.md) | 修剪超大工具输出，减少需要压缩的历史 | `ctx.toolResultPruner` | | [`command-compact/`](command-compact/README.zh.md) | 按需压缩历史的 `/compact` 命令 | 注册到 `ctx.commands` | ----- ## 相关文档 先从子系统参考了解共享词汇，再阅读两份 Agent Note 了解设计依据。 - [压缩子系统参考](../../docs/subsystems/compaction.zh.md)——压缩词汇、结果与服务行为。 - [压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md)——家族如何拆分，以及为何依赖会话与 LLM 词汇。 - [排队手动压缩 Agent Note](../../.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md)——按需 `/compact` 如何与运行中的轮次串行化。 - [能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md)——本家族遵循的 Service Definition / Service Provider / Consumer 拆分。 ## 开发备注
维护者的工作上下文——点击展开 无。
# context/ — 请求上下文插件 ``` --- description: "context 组地图：不定义工具、为每次请求添加持久且模型可见上下文的插件，供浏览本组的用户与维护者阅读。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 context 组提供不定义任何工具、为每次请求添加模型可见上下文的插件：工作区指令文件成为指引，`@file` mention 提供路径补全，其他会话可以作为有界快照被引用，模型还能看到当前时间与 agent 的 tmux 位置。除 `agent-instructions`（`dsh-base` 默认包含它，profile patch 可以禁用）外，其余全部需主动启用。上下文是持久的：注入的指令与引用以 user 角色消息进入会话历史，因此与其他对话内容一样持久、可回放、可压缩。本页是组的映射；包级约定由各包 README 负责。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | ctx key | |---|---|---| | [`agent-instructions/`](agent-instructions/README.zh.md) | 将 `AGENTS.md`／`CLAUDE.md` 工作区指令加载到上下文，并在文件编辑后刷新 | — | | [`session-reference/`](session-reference/README.zh.md) | 引用其他会话：提及一个会话，其有界只读快照即成为上下文 | `ctx.sessionReferenceResolver` | | [`file-reference/`](file-reference/README.zh.md) | `@file` mention 发现与供宿主驱动 UI 使用的共享 mention 语法 | `ctx.fileReferences` | | [`file-reference-local/`](file-reference-local/README.zh.md) | `@file` mention 的本地工作区补全提供方 | — | | [`time-context/`](time-context/README.zh.md) | 每个步骤的当前时间、浏览器时区与经过时长 | — | | [`tmux-context/`](tmux-context/README.zh.md) | agent 所在的 tmux session、window 与 pane 位置 | — | ----- ## 相关文档 - [会话引用子系统](../../docs/subsystems/session-reference.zh.md)——规范 mention URI、快照语义与稳定的错误分类。 - [工作区上下文决策记录](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md)——指令上下文为何按 agent／会话隔离并持久记录。 - [生成的配置目录](../../docs/config-catalog.zh.md)——本组各包接受的全部配置字段。 ----- ## 开发备注
维护者的工作上下文——点击展开 无。
# subagent/ subagent 能力系列：提供方注册表约定和面向模型的委托工具 ``` --- description: "subagent 包组：委派 seam、其进程内与进程外后端，以及面向模型的委派工具。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 subagent 组是委派能力家族：它让 agent（智能体）把任务交给子 agent，等待或继续子 agent 的工作，并让每个子 agent 随时可被发现。一个约定（`ctx.subagents`）服务任意数量的具名提供方，因此单个组合可以混合进程内子 agent（全新启动，或从父级已完成历史派生）与进程外子 agent——ACP agent、真实 Codex 或 Claude Code 安装，或经 SDK 运行的完整 Harness 运行时。面向模型的工具向 agent 公开委派、相邻 Agent 消息与列举，父级总能看到存在哪些子级、它们在线还是仅存于存储。本页是组的映射；各包 README 负责各自的包约定。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | ctx 键 | |---|---|---| | [`subagent/`](subagent/README.zh.md) | 定义委派服务：提供方注册表、一次性运行、可继续子级与发现 | `ctx.subagents` | | [`subagent-in-process-driver/`](subagent-in-process-driver/README.zh.md) | 提供共享的进程内运行驱动器 | 无 | | [`subagent-spawn-in-process/`](subagent-spawn-in-process/README.zh.md) | 运行全新的进程内子 agent | 注册到 `ctx.subagents` | | [`subagent-fork-in-process/`](subagent-fork-in-process/README.zh.md) | 运行从父级已完成历史派生的进程内子 agent | 注册到 `ctx.subagents` | | [`subagent-acp/`](subagent-acp/README.zh.md) | 经 Agent Client Protocol 运行进程外子 agent | 注册到 `ctx.subagents` | | [`subagent-codex/`](subagent-codex/README.zh.md) | 经官方 app-server 协议运行真实 Codex 子 agent | 注册到 `ctx.subagents` | | [`subagent-claude-code/`](subagent-claude-code/README.zh.md) | 经官方 Agent SDK 运行真实 Claude Code 子 agent | 注册到 `ctx.subagents` | | [`subagent-dsh-sdk/`](subagent-dsh-sdk/README.zh.md) | 经 TypeScript SDK 运行进程外 Harness 子 agent | 注册到 `ctx.subagents` | | [`tool-subagent/`](tool-subagent/README.zh.md) | 向模型公开委派 | 注册到 `ctx.tools` | | [`tool-subagent-control/`](tool-subagent-control/README.zh.md) | 向模型公开相邻 Agent 消息、中断与列举 | 注册到 `ctx.tools` | ----- ## 相关文档 - [Subagent 子系统](../../docs/subsystems/subagent.zh.md)——服务约定、提供方约定与终态结果语义。 - [Subagent 能力 seam](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md)——委派能力家族的设计记录。 - [可续跑后台 subagent](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md)——接受后续轮次的持久子级。 - [合并后的 subagent 控制服务](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md)——后续消息、中断与列举面。 ## 开发备注 无。 # jobs/：后台任务能力家族 ``` --- description: "jobs 组地图：后台任务控制——注册表约定、进程本地存储与面向模型的任务工具，供浏览本组的用户与维护者阅读。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 jobs 组是后台工作能力家族：运行长时间工作的工具把工作注册为任务，拥有它的 agent 可以在不阻塞自身轮次的情况下读取、等待、列出或取消任务。任务属于启动它的 agent 会话，因此一个 agent 永远不会看到另一个 agent 的工作；任务完成时以会话内通知送达给拥有它的 agent，无需轮询。本组拆分为注册表约定（`jobs`）、其进程本地存储（`jobs-local`）以及带完成通知的模型侧控制工具（`tool-jobs`）。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | ctx 键 | |---|---|---| | [`jobs`](jobs/README.zh.md) | 定义后台任务约定：id、归属、生命周期与完成监听器 | `ctx.jobs` | | [`jobs-local`](jobs-local/README.zh.md) | 在本进程中运行并存储任务，按所有者隔离 | 注册到 `ctx.jobs` | | [`tool-jobs`](tool-jobs/README.zh.md) | 让模型读取、列出和终止任务，并投递完成通知 | 注册到 `ctx.tools` | ----- ## 相关文档 - [后台任务运行时子系统](../../docs/subsystems/jobs.zh.md)——任务类型、快照字段与 `ctx.jobs` API。 - [通用长时间运行工具运行时 Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md)——后台任务运行时背后的设计。 - [任务注册表 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-job-registry-seam.zh.md)——按所有者隔离的注册表约定及其理由。 ----- ## 开发备注
维护者的工作上下文——点击展开 无。
# experimental/ 私有原型与内部专用插件 ``` --- description: "实验组地图：不进入正式发布的私有原型与内部专用插件，供浏览本组的用户与维护者阅读。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 实验组包含不属于任何正式发布的原型能力：它们运行在真实 harness 上，但约定可能变更，也不提供支持承诺。本组包含 Agent Teams、跨 realm Inspector、代码执行 seam 的 CPython 子进程后端，以及预览部署使用的浏览器 worker 运行时与镜像打包器。用这些包来尝试未发布的能力；它们没有稳定性承诺，已发布产品不得依赖它们。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | ctx 键 | |---|---|---| | [`agent-team-profile`](agent-team-profile/README.zh.md) | Agent Teams 的显式源码 checkout profile 层 | — | | [`agent-team`](agent-team/README.zh.md) | 具名 teammate，成员之间持久消息与共享任务板 | `ctx.agentTeams` | | [`agent-team-web-profile`](agent-team-web-profile/README.zh.md) | Agent Teams 的显式源码 checkout Web 层 | — | | [`client-ui-agent-team`](client-ui-agent-team/README.zh.md) | Web Team roster、任务板与 teammate 导航 | — | | [`code-runtime-python`](code-runtime-python/README.zh.md) | 代码执行 seam 的 CPython 子进程后端 | `ctx.codeRuntime` | | [`inspector`](inspector/README.zh.md) | 用于 Host 调试、Client Runtime 检查、网络采集与 Cordis 树的跨 realm CDP hub | `ctx.inspector` | | [`tool-agent-team`](tool-agent-team/README.zh.md) | 让模型创建、发消息与协调 teammate 的十个工具 | 按作用域注册工具到 `ctx.tools` | | [`webworker-packer`](webworker-packer/README.zh.md) | 构建浏览器 worker 预览所消费的 gzip 压缩 VFS 镜像 | 库与 CLI，不使用 ctx key | | [`webworker-runtime`](webworker-runtime/README.zh.md) | 在专用浏览器 worker 中运行 harness 插件树 | 库与 worker 入口，不使用 ctx key | ----- ## 相关文档 - [实验包决策](../../.agents/notes/implemented/architecture/2026-08-18-experimental-agent-teams-packages.zh.md)——位置、发布排除与依赖隔离。 - [Agent Teams 子系统](../../docs/subsystems/agent-team.zh.md)——持久 Team 类型与 `ctx.agentTeams` 服务 API。 - [实验子树规则](AGENTS.md)——实验状态放宽了什么、不放宽什么。 ----- ## 开发备注
维护者的工作上下文——点击展开 无。
# workflow/ 工作流 seam、worker 线程引擎、面向模型的 workflow/ralph 工具 ``` --- description: "workflow 组地图：由模型编写的、可扇出 subagent 的编排脚本，供浏览本组的用户与维护者阅读。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 workflow 组让 agent 可以运行一段由模型编写的编排脚本，把工作扇出到多个 subagent 并返回最终值。`workflow` 包提供运行服务，worker-thread 包在隔离线程中执行脚本，两个面向模型的工具公开编排能力：通用的 `workflow` 工具用于脚本化扇出，固定的 `ralph` 工具用于全新 agent 迭代循环。脚本用钩子协调 agent，实际工作由 agent 完成。引擎把脚本的同步工作移出宿主事件循环，但这只是隔离，不是安全边界。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | ctx 键 | |---|---|---| | [`workflow`](workflow/README.zh.md) | 运行由模型编写的、扇出 subagent 的编排脚本 | `ctx.workflowEngine` | | [`workflow-worker-thread`](workflow-worker-thread/README.zh.md) | 在独立 worker thread 中执行每个工作流脚本，移出宿主事件循环 | 注册到 `ctx.workflowEngine` | | [`tool-workflow`](tool-workflow/README.zh.md) | 把 `workflow` 工具交给模型，用于脚本化多 agent 编排 | 注册到 `ctx.tools` | | [`tool-ralph`](tool-ralph/README.zh.md) | 把 `ralph` 工具交给模型，用于全新 agent 迭代循环 | 注册到 `ctx.tools` | ----- ## 相关文档 - [工作流子系统](../../docs/subsystems/workflow.zh.md)——seam 的类型、启动请求与 `workflow/*` 事件。 - [生成的工具目录](../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-workflow)——模型接收的 `workflow` 工具 schema。 - [生成的工具目录](../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-ralph)——模型接收的 `ralph` 工具 schema。 - [生成的配置目录](../../docs/config-catalog.zh.md#deepseek-aidsh-workflow-worker-thread)——每个受支持的引擎配置字段。 - [动态工作流 Agent Note](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md)——seam 设计及其决策。 - [Ralph 工具 Agent Note](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md)——固定全新 agent 循环的设计与暂缓事项。 ----- ## 开发备注
维护者的工作上下文——点击展开 无。
# webhook/ — 从已验证外部事件到 DSH Session ``` --- description: "经验证的外部事件、程序化规则与即发即弃 DSH Session 创建的包映射。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 Webhook 系列接收通过身份验证的提供方事件，并运行受信任的程序化规则。规则可以在 Web Workspace 中创建普通根 Session。分发仅存在于进程内并采用 fire-and-forget，不拥有交付数据库、队列、重试、去重或 Agent 完成状态。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 角色 | ctx key | |---|---|---| | [`webhook/`](webhook/README.zh.md) | 规则注册表、回调生命周期与基于 Workspace 的 Session 创建 | `ctx.webhookRuntime` | | [`webhook-github/`](webhook-github/README.zh.md) | 签名 GitHub HTTP 适配器 | 消费 `ctx.webhookRuntime` 与 `ctx.webServer` | ## 相关文档 提供方适配器负责验证身份并规范化交付。规则拥有任意条件和外部调用，随后返回 `null` 或一个 Session 请求。[Webhook 子系统参考](../../docs/subsystems/webhook.zh.md)拥有共享类型与时序保证。 ## 开发备注 无。 # web/：web 访问能力家族 ``` --- description: "web 访问能力家族的包映射：搜索/抓取服务、其提供方后端，以及消费它们的面向模型工具。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 `web/` 组为 harness 提供 web 访问能力——搜索 web 与抓取 URL——通过一个与提供方无关的服务（`ctx.web`）以及使用它的后端和工具。部署可以挂载一个或多个后端——搜索用 Exa、Perplexity 或 DeepSeek，抓取用匿名 HTTP(S)——服务按操作挑选可用的提供方，因此后端来来去去，面向模型的工具保持稳定。六个包构成该家族：负责提供方选择与错误的 `web/` 服务、三个搜索后端、一个抓取后端，以及向模型公开 `web_search` 与 `web_fetch` 的 `tool-web/`。该组只拥有 web 访问本身：没有浏览或提取，没有逐 URL 策略，各后端保留自己的资源上限。搜索与抓取有意共用一项服务，使选择、取消、错误与配置只有一个归属方。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 六个包分别承担 web 角色；子系统参考文档拥有穷尽式词汇与约定。 | 包 | 职责 | ctx 键 | |---|---|---| | [`web/`](web/README.zh.md) | 搜索/抓取服务：通过可互换的后端搜索与抓取 URL，统一选择与错误策略 | `ctx.web` | | [`web-search-exa/`](web-search-exa/README.zh.md) | 通过 Exa 搜索 web | 注册到 `ctx.web` | | [`web-search-perplexity/`](web-search-perplexity/README.zh.md) | 通过 Perplexity 搜索 web | 注册到 `ctx.web` | | [`web-search-deepseek/`](web-search-deepseek/README.zh.md) | 通过 DeepSeek 原生搜索搜索 web | 注册到 `ctx.web` | | [`web-fetch-http/`](web-fetch-http/README.zh.md) | 匿名抓取公共 HTTP(S) 页面 | 注册到 `ctx.web` | | [`tool-web/`](tool-web/README.zh.md) | 向模型公开 `web_search` 与 `web_fetch` | 注册到 `ctx.tools` | ----- ## 相关文档 先从子系统参考文档了解共享词汇，再看单一提供方选择服务背后的设计决策。 - [web 子系统](../../docs/subsystems/web.zh.md)——搜索/抓取请求与结果、提供方可用性、`WebError` 与公开地址强制规则。 - [web 能力 seam 决策](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md)——搜索与抓取为何共用一项提供方选择服务。 ## 开发备注
维护者的工作上下文——点击展开 无。
# attachment/：持久附件能力族 ``` --- description: "持久图片附件能力族的包映射：你可以用图片附件做什么，以及你的图片存放在哪里。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 `attachment/` 组提供持久图片附件：把图片附加到提示词和命令，harness 会把它保存到你的机器上，重新显示在对话历史中，并在后续轮次发送给模型。随附的 `dsh` 组合无需任何设置即可支持这一点。该能力与它的存储拆分为两个包，见下文。已存储的图片在重启后依然存在且永远不会被自动删除，并且只支持光栅图片格式。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 这两个包提供持久图片附件；每个 README 描述其各自部分可以做什么。 | 包 | 角色 | ctx 键 | |---|---|---| | [`attachment/`](attachment/README.zh.md) | 可用于提示词与命令、会持久保存并回到历史中的图片附件 | `ctx.attachments` | | [`attachment-local/`](attachment-local/README.zh.md) | 把附加图片存储在本机 `DSH_HOME` 下 | 注册到 `ctx.attachments` | ----- ## 相关文档 先从子系统参考了解服务约定，再看能力 seam 表与本地后端的配置面。 - [附件子系统参考](../../docs/subsystems/attachment.zh.md)——服务约定、载荷类型与 `ctx.attachments` 的 cordis 接口面。 - [能力 seam](../../docs/capability-seams.zh.md)——本家族遵循的 Service Definition / Service Provider / Consumer 拆分。 - [生成配置目录](../../docs/config-catalog.zh.md#deepseek-aidsh-attachment-local)——本地后端的每个受支持字段。 ## 开发备注
维护者的工作上下文——点击展开 无。
# spill/：工具输出 spill 能力家族 ``` --- description: "工具输出 spill 能力家族的包映射：存储服务、本地后端与结果策略各自提供什么。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 `spill/` 组在不丢失超大工具输出的前提下把它们挡在模型上下文之外：当某个工具结果超过部署配置的字节上限时，完整文本会保存到 spill 产物中，模型只看到有界预览和一个稍后可以读取或搜索的定位信息。该家族拆分为三个包——`spill/` 中的存储服务、`spill-local/` 中的本地文件系统后端，以及 `spill-policy/` 中决定最终工具结果何时过大并触发 spill 的结果策略。spill 是可选且尽力而为的：只有配置了 `maxInlineBytes` 时策略才会生效，存储失败时原始结果仍然可见。本组只负责存储与结果替换；预览机制归 `dsh-output-retention` 所有，提供方资源上限保持独立。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 三个包分别承担 spill 角色；子系统参考文档拥有穷尽式词汇与约定。 | 包 | 职责 | ctx 键 | |---|---|---| | [`spill/`](spill/README.zh.md) | 存储服务：保存过大的工具文本并返回定位信息与取回指引 | `ctx.spillStore` | | [`spill-local/`](spill-local/README.zh.md) | 将 spill 文本保存到本机的私有会话级文件 | 注册到 `ctx.spillStore` | | [`spill-policy/`](spill-policy/README.zh.md) | 用预览和定位信息替换过大的纯文本工具结果 | 监听 `ctx.tools` | ----- ## 相关文档 先从子系统参考文档了解共享词汇，再看设计决策及其持久日志扩展。 - [spill 子系统](../../docs/subsystems/spill.zh.md)——`SaveTextSpill`/`SpillRef` 词汇、归属与后端关系。 - [工具输出 spill 决策](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md)——存储、保留与工具自有输出处理之间的能力边界。 - [代码 dispatch-log spill 决策](../../.agents/notes/implemented/feature/2026-07-26-ptc-dispatch-log-spill.zh.md)——为何 `run_code` 子调用结果的持久副本同样设界。 ## 开发备注
维护者的工作上下文——点击展开 无。
# todo/ 面向模型的 todo_write 工具 ``` --- description: "todo 组地图：基于会话日志的模型侧 todo_write 工具，供浏览本组的用户与维护者阅读。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 todo 组为 agent 提供可用于规划的会话级任务列表：添加任务、标记进行中、逐项完成，同一份列表跨轮次、跨重新打开的会话持续存在。它只包含一个产品包，提供 `todo_write` 工具；列表属于创建它的 agent 会话，每次更新都会整体替换。交互式宿主会从列表展示当前计划，组本身不附带任何 UI。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | ctx 键 | |---|---|---| | [`tool-todo`](tool-todo/README.zh.md) | 让 agent 维护会话任务列表：规划任务、更新状态、跟踪进度 | 注册到 `ctx.tools` | ----- ## 相关文档 - [Todo 子系统](../../docs/subsystems/todo.zh.md)——`todo/write` 事件载荷、归属规则与 `TodoItem`。 - [生成的工具目录](../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-todo)——模型接收的 `todo_write` schema。 - [生成的配置目录](../../docs/config-catalog.zh.md#deepseek-aidsh-tool-todo)——每个受支持配置字段。 - [todo_write 工具 Agent Note](../../.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md)——原始设计及其备选方案。 ----- ## 开发备注
维护者的工作上下文——点击展开 无。
# plan/：plan 协作状态 ``` --- description: "plan 组的包映射：引导 agent 先探索和设计再执行的计划模式功能，供用户和维护者浏览该组。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 `plan/` 组提供计划模式：激活期间，agent（智能体）先探索和设计再执行，遵循你的部署所写的引导行事，并在执行前把完成的计划呈交你批准。你可以用 `/plan` 命令进入和离开计划模式，批准计划，或让 agent 回去继续规划。计划模式是引导而非限制：每个工具仍然可用，沙箱模式与审批提示等限制需另行配置。该组只包含一个包 `plan-mode`。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 一个包提供完整的计划模式功能；子系统参考拥有穷尽式约定。 | 包 | 职责 | ctx 键 | |---|---|---| | [`plan-mode/`](plan-mode/README.zh.md) | 提供计划模式：`/plan` 进入和离开，规划期间由部署引导指引 agent，`exit_plan_mode` 把完成的计划呈交你评审 | `ctx.planMode` | ----- ## 相关文档 先从子系统参考了解共享词汇，再阅读设计说明了解决策。 - [计划模式子系统参考](../../docs/subsystems/plan.zh.md)——计划模式如何工作、其配置与退出工具的行为。 - [plan 专用协作状态](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md)——计划模式背后的设计决策。 ## 开发备注
维护者的工作上下文——点击展开 无。
# preset/ 由 preset cordis.yml 按会话组装 agent ``` --- description: "preset 组地图：按会话从 preset 文件组装 agent，供浏览本组的用户与维护者阅读。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 preset 组提供按会话的 agent（智能体）组装：agent preset 是一个目录，内含一份 `agent.cordis.yml`；从 preset 组装的会话会运行该 preset 的工具、提示词段落与 skill（技能），而其他会话各自保持自己的。`agent-presets` 拥有名单——对已配置根目录与 harness home 的发现、受防护的按 agent 挂载，以及只复制的创作方式——`persona` 则提供可组装的行，让 preset 不止能改变 agent 的工具、也能改变它的身份。两者合起来让一个进程可以同时运行多个组装方式不同的 agent。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | ctx 键 | |---|---|---| | [`agent-presets`](agent-presets/README.zh.md) | preset 名单、对受信任根目录与用户根目录的发现、按 agent 组装、只复制的创作 | `ctx.agentPresets` | | [`persona`](persona/README.zh.md) | preset 挂载的可组装人设行，用于遮蔽或替换部署级人设 | — | ----- ## 相关文档 - [`AgentPresets` 参考](../../docs/subsystems/core.zh.md#ctxagentpresets--agentpresets)——发现、挂载、继承与重组。 - [Scope 子系统](../../docs/subsystems/scope.zh.md)——scope key 与挂载用以加入 agent 的父链。 - [系统提示词子系统](../../docs/subsystems/system-prompt.zh.md)——preset 提示词段落如何注册与组装。 - [按会话组装 agent preset 的 Agent Note](../../.agents/notes/implemented/architecture/2026-08-03-per-session-agent-presets.zh.md)——设计理由与备选方案。 - [按 preset 常驻挂载的 Agent Note](../../.agents/notes/implemented/architecture/2026-08-08-per-preset-standing-mounts.zh.md)——挂载为何是常驻且共享的。 部署交付的 preset 位于 [`agent-presets/presets/`](agent-presets/presets)——一个 preset 一个目录，那份目录列表就是名单；在这里再列一遍只会多出一份需要同步的名单。 ----- ## 开发备注
维护者的工作上下文——点击展开 无。
# guard/：循环卫生 guard 家族 ``` --- description: "循环卫生 guard 家族的包映射：建议性重复工具提醒与单次工具调用超时策略，供选择或组合 guard 的用户与维护者阅读。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 `guard/` 组通过监视两种常见失败模式来保持 agent loop（智能体循环）高效。`repeat-tool-reminder` 会在模型重复完全相同的工具调用时提醒它改变方法或结束任务，让卡住的循环不再浪费时间和 token。`timeout-policy` 为声明了限时的工具调用设置时间上限，让挂起的调用向模型返回清晰的超时错误，而不是拖住整个会话。两者都随 `dsh` base 组合默认启用；组合可以调优或移除它们。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 两个小插件分别覆盖两种模式；下文每个 README 都说明何时保留、调优或移除它。 | 包 | 提供什么 | |---|---| | [`repeat-tool-reminder/`](repeat-tool-reminder/README.zh.md) | 在模型重复相同工具调用时提醒它，使其改变方法或结束任务 | | [`timeout-policy/`](timeout-policy/README.zh.md) | 为声明了限时的工具调用设置超时，让模型得到清晰错误而不是无限等待 | ----- ## 相关文档 先从工具子系统参考了解工具调用流水线，再看重复提醒的配置与策略背后的超时库决策。 - [工具子系统参考](../../docs/subsystems/tools.zh.md)——两个 guard 都依赖的工具调用流水线与决策。 - [生成配置目录](../../docs/config-catalog.zh.md#deepseek-aidsh-repeat-tool-reminder)——重复调用提醒的每个受支持字段。 - [超时截止时间库 Agent Note](../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md)——`timeout-policy` 所执行的时序／终止拆分。 ## 开发备注
维护者的工作上下文——点击展开 无。
# bundle/：profile 插件组合包 ``` --- description: "共享核心、浏览器 GUI、一次性任务、ACP 与 SDK 应用表层的现成 dsh profile bundle。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 本组列出 `dsh --profile` 使用的可安装 patch 层。每个包都声明 `dsh.bundle.patch`；启动器会叠放这些 patch 文档来组装具名 profile。`web`、`headless`、`acp` 与 `sdk` profile 以 `dsh-base` 为基础，`sdk-minimal` 则由一个 bundle 提供完整配置树。领域包也可以在本目录之外声明附加层。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ## 包 | 包 | 职责 | ctx key | |---|---|---| | [`base`](base/README.zh.md) | 基于 base 的 profile 共享核心 | —（仅 patch） | | [`acp-app`](acp-app/README.zh.md) | 基于 base 的纯自动化 ACP stdio 应用 | 挂载 ACP bridge | | [`web-app`](web-app/README.zh.md) | 基于 base 的浏览器应用层 | 挂载 Web 配置项 | | [`headless`](headless/README.zh.md) | 基于 base 的一次性命令行任务应用 | `headless-runner` | | [`sdk-app`](sdk-app/README.zh.md) | 基于 base 的 SDK JSON-RPC stdio 应用 | 挂载 SDK server | | [`sdk-minimal`](sdk-minimal/README.zh.md) | 不使用 base 或 Web 的独立极简 SDK 应用 | —（完整 patch 树） | 内置组合包从 dsh 安装目录解析；树外（out-of-tree）组合包通过 `dsh plugin --profile add ` 安装进 profile。 ## 相关文档 - [dsh 应用](../../apps/cli/README.zh.md)——启动 profile 的 `dsh` 命令。 - [app-boot](../boot/app-boot/README.zh.md)——profile 如何解析、分层与定制。 - [Profile 组合包设计笔记](../../.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md)——profile 与组合包的组合设计。 - [生成组合图](../../apps/cli/composition.md)——每个已发布 profile 使用的确切组合。 ## 开发备注 无。 # extensions/ agent 运行时自修改：实时插件/服务检查与模型所写挂载/卸载 ``` --- description: "extensions 组地图：用于定义、运行与移除动态 Cordis 包的模型侧工具和双半 runner，供浏览本组的用户与维护者阅读。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 extensions 组让运行中的 agent 修改它自己所在的运行时：模型可以检查当前 DSH 进程里加载的插件与服务，定义动态 Cordis 包（可含 host 半、浏览器半或两者），运行、停止并彻底移除它，浏览器面板则操作全部定义。包按插件演进：一个插件持有若干不可变的包版本，可以在它们之间运行或更新。定义只存在于进程内存中，因此 DSH 重启即清空，本组不会写仓库文件，也不改任何配置。四个包构成整个子系统：模型侧工具加 host 半 runner，浏览器半 runner 加浏览器 UI。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | ctx 键 | |---|---|---| | [`tool-cordis`](tool-cordis/README.zh.md) | 七个模型侧工具：检查实时运行时，定义、运行、停止并移除动态包 | 注册到 `ctx.tools` | | [`cordis-host-runner`](cordis-host-runner/README.zh.md) | host 半：定义注册表、沙箱化的 host 半生命周期，以及浏览器查询应答的 inspect 注册表 | 提供 `ctx.dynamicCordisRunner` 与 `ctx.cordisInspect` | | [`cordis-client-runner`](cordis-client-runner/README.zh.md) | 浏览器半：把浏览器半源码求值成活插件，并应答运行请求 | client 面；提供浏览器侧 `ctx.dynamicCordisRunner` | | [`ui-cordis`](ui-cordis/README.zh.md) | 浏览器面：全局面板、生命周期工具卡片与 `@pluginId` 输入源 | client 面；注册 slot | ----- ## 相关文档 - [extensions 子系统](../../docs/subsystems/extensions.zh.md)——生成的 `ctx.cordisInspect` 与 `ctx.dynamicCordisRunner` 服务 API。 - [生成的工具目录](../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-cordis)——七个模型侧工具 schema。 - [生成的配置目录](../../docs/config-catalog.zh.md#deepseek-aidsh-cordis-host-runner)——runner 的受支持配置字段。 - [自引用 Cordis 工具集 Agent Note](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md)——沙箱语义、生命周期与组合的设计居所。 - [客户端外壳与动态包 Agent Note](../../.agents/notes/implemented/architecture/2026-08-15-client-shells-and-dynamic-packages.zh.md)——浏览器半的包归属与构建面。 ----- ## 开发备注
维护者的工作上下文——点击展开 两个浏览器半包住在本组而不是 `packages/client/` 下，因为它们是本子系统双半包的其中一半；client 面经由 client program 编译它们，host program 只引用 host runner。
# hooks/ 钩子桥接 + 共享的 Claude Code / Codex 线协议库 ``` --- description: "hooks 组地图：在 agent 运行期间使用现有的 Claude Code 与 Codex shell 钩子配置，供浏览本组的用户与维护者阅读。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 hooks 组让 agent（智能体）运行可以使用你为 Claude Code 或 Codex 写好的 shell 钩子：挂载对应的桥接、把它指向你现有的 `hooks.json`，这些钩子就会在 agent 运行中的对应时刻触发——会话开始时、提示词提交时、工具运行前后，或运行即将停止时。钩子可以带一条模型可见的消息阻塞提示词或工具调用、向对话附加额外上下文，或强制运行继续。当你希望现有钩子配置无需改写成原生插件就能继续工作时，选择本组；每个桥接覆盖其参考工具文档中的 command hook 子集。`hook-protocol` 是两个桥接共享的钩子引擎，因此两种方言在协议一致之处行为相同。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | 形态 | |---|---|---| | [`hook-protocol`](hook-protocol/README.zh.md) | 两个桥接共享的钩子引擎；无需直接配置 | 库 | | [`hooks-claude-code`](hooks-claude-code/README.zh.md) | 在 agent 运行期间运行你现有的 Claude Code `hooks.json` 钩子 | 插件 | | [`hooks-codex`](hooks-codex/README.zh.md) | 在 agent 运行期间运行你现有的 Codex `hooks.json` 钩子 | 插件 | ----- ## 相关文档 - [拦截扩展点 Agent Note](../../.agents/notes/implemented/feature/2026-06-30-interception-extension-points.zh.md)——桥接所面向的类型化 Decision 接口面。 - [钩子桥接 Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.zh.md)——桥接设计及其决策映射。 - [钩子协议库 Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md)——共享库负责的内容及其原因。 ----- ## 开发备注
维护者的工作上下文——点击展开 无。
# session/ — 持久会话数据平面 ``` --- description: "持久会话数据平面的包映射：持久化 seam 及其后端、检查点策略、投影、基于日志的标题与外发会话遥测。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 session 组让 agent（智能体）的对话在实时 loop 之外持久可复用：持久化 seam 存储事件日志并在恢复时还原，检查点策略让请求、工具副作用与已完成步骤在下一步动作前持久化，投影向客户端载体提供日志派生的完整值，标题根据会话内容为其命名，遥测则向外上报会话活动。先挂载随产品交付的 JSONL 持久化 provider，再按部署需要挂载检查点策略以及投影、标题或遥测包。本页是组的映射；每个包 README 负责各自的约定，`session-query/` 是同级独立组，其读取／工具接口独立消费持久化。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 本组分为四个家族：持久存储（持久化 seam、后端、检查点策略）、投影、标题与遥测。每个包 README 负责各自的约定与配置。 ### 持久化 | 包 | 职责 | ctx key | |---|---|---| | [`session-persistence/`](session-persistence/README.zh.md) | 定义持久会话存储服务，以及每个后端组合的共享写入协调机制 | `ctx.sessionPersistence` | | [`session-persistence-jsonl/`](session-persistence-jsonl/README.zh.md) | 随产品交付的后端：每会话一份仅追加 JSONL 日志，可选 Zstandard 压缩 | 注册到 `ctx.sessionPersistence` | | [`session-checkpoint-policy/`](session-checkpoint-policy/README.zh.md) | 让模型请求、顶层工具副作用与已完成步骤在下一步动作前持久化 | 包装 `ctx.llm` 与 `ctx.tools` | | [`session-log-deepseek/`](session-log-deepseek/README.zh.md) | 把增量规范日志作为可选的官方 DeepSeek 请求元数据上传 | 贡献 `dsh_session_log` | ### 投影 | 包 | 职责 | ctx key | |---|---|---| | [`session-projection/`](session-projection/README.zh.md) | 定义并驱动把已提交事件折叠为完整当前值的投影单元 | `ctx.sessionProjections` | | [`session-projection-cache/`](session-projection-cache/README.zh.md) | 持久化投影检查点，使冷读跳过全量日志加载 | `ctx.sessionProjectionCache` | | [`session-stats/`](session-stats/README.zh.md) | 通过 `sessionStats` 单元提供全日志会话计数与墙钟时间 | 注册到 `ctx.sessionProjections` | | [`session-turn-outline/`](session-turn-outline/README.zh.md) | 通过 `turnOutline` 单元提供全日志轮次大纲（轮次号、`turn/start` seq、提示词预览） | 注册到 `ctx.sessionProjections` | ### 标题 | 包 | 职责 | ctx key | |---|---|---| | [`session-title/`](session-title/README.zh.md) | 基于日志的会话标题，带确定性回退与一个可选提供方 | `ctx.sessionTitle` | | [`session-title-llm/`](session-title-llm/README.zh.md) | 供提供方包共享的模型标题生成策略 | 库，不使用 ctx key | | [`session-title-first-prompt-llm/`](session-title-first-prompt-llm/README.zh.md) | 根据第一条合格的人类消息为会话生成标题 | 注册到 `ctx.sessionTitle` | | [`session-title-all-prompts-llm/`](session-title-all-prompts-llm/README.zh.md) | 根据所有合格的人类消息为会话生成标题 | 注册到 `ctx.sessionTitle` | ### 遥测 | 包 | 职责 | ctx key | |---|---|---| | [`session-telemetry/`](session-telemetry/README.zh.md) | 捕获会话活动并把记录交给配置的上报后端 | `ctx.sessionTelemetry` | | [`session-telemetry-otel/`](session-telemetry-otel/README.zh.md) | 通过 OpenTelemetry 日志以 `FULL`、`FEEDBACK_ONLY` 或 `DISABLED` 模式投递遥测 | 注册到 `ctx.sessionTelemetry` | 同一时间只允许一个标题提供方注册；未注册时，标题服务保留其确定性回退。下面的子系统页面是各家族后端无关的参考资料。 ----- ## 相关文档 - [会话持久化子系统](../../docs/subsystems/persistence.zh.md)——后端无关的服务语义、flush 检查点与崩溃恢复。 - [会话投影子系统](../../docs/subsystems/session-projection.zh.md)——投影单元约定与驱动语义。 - [会话标题子系统](../../docs/subsystems/session-title.zh.md)——标题资格、回退与提供方流程。 - [会话遥测子系统](../../docs/subsystems/session-telemetry.zh.md)——捕获、脱敏与投递模式。 - [会话子系统](../../docs/subsystems/session.zh.md)——本组每个包持久化或派生的实时事件日志。 ## 开发备注 无。 # session-query/：会话检索能力家族 ``` --- description: "会话检索能力家族的包映射：搜索、追踪与读取实时和持久会话历史，以及 Web 端会话日志导出。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 `session-query/` 组提供对实时与持久会话历史的检索，且独立于压缩（compaction）：程序化调用方通过一个统一服务查询精确日志、过滤后的列表、关系追踪与全文搜索；SQLite 后端支撑搜索；模型获得五个经工作区授权的工具；Web 界面获得下载会话 ZIP 的 `/export` 命令。搜索结果与模型看到的对话历史一致。本页是组的映射；各包 README 负责各自的包级约定。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 每个包 README 描述你可用该包部分完成的事情。 | 包 | 职责 | ctx 键 | |---|---|---| | [`session-query/`](session-query/README.zh.md) | 统一的会话历史查询服务：精确读取、关系追踪与过滤 | `ctx.sessionQuery` | | [`session-query-sqlite/`](session-query-sqlite/README.zh.md) | 基于 SQLite FTS5 索引的会话历史全文搜索 | 注册到 `ctx.sessionQuery` | | [`session-log-export/`](session-log-export/README.zh.md) | Web `/export` 命令与浏览器下载会话 ZIP | `ctx.sessionLogDownload`（浏览器） | | [`tool-session-query/`](tool-session-query/README.zh.md) | 面向模型的搜索、追踪与读取会话历史工具 | 注册到 `ctx.tools` | ----- ## 相关文档 先从子系统参考了解共享的查询词汇，再看追踪、搜索与面向模型工具背后的设计记录。 - [会话查询子系统参考](../../docs/subsystems/session-query.zh.md)——逻辑记录、过滤器、搜索页、血缘、有界读取与事件关系。 - [会话查询关系追踪](../../.agents/notes/implemented/feature/2026-07-13-session-query-tracing.zh.md)——追踪语义与校验边界。 - [SQLite FTS5 会话搜索](../../.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md)——搜索语义、对账与 tokenizer 决策。 - [面向模型的会话查询工具](../../.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md)——工作区授权与无游标结果设计。 ## 开发备注 无。 # settings/：用户可编辑配置 ``` --- description: "用户设置能力族的包映射：解析各 namespace 配置的 ctx.settings 服务，以及存储它的 YAML/JSON 文件提供方。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 `settings/` 组让插件配置变为用户可编辑：插件用一个 schema 注册具名 namespace，用户在一份文档里覆盖值，无需改动 `cordis.yml`。用户覆盖优先于部署自身的配置与 schema 默认值，变更实时生效。两个包覆盖该能力：`settings/` 提供设置服务，`settings-file/` 把所有 namespace 存进一个用户可编辑的 YAML 或 JSON 文档。设置是可选的：没有挂载提供方时，配置保持组合原样。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 两个包覆盖该能力；完整约定由各子级 README 负责，穷尽式服务接口面由子系统参考负责。 | 包 | 角色 | ctx 键 | |---|---|---| | [`settings/`](settings/README.zh.md) | 设置服务：注册 namespace 并读取或修改其值 | `ctx.settings` | | [`settings-file/`](settings-file/README.zh.md) | 把设置存进一个本地 YAML/JSON 文件并热发布外部编辑 | 注册 `ctx.settings` | ----- ## 相关文档 先从子系统参考了解共享词汇，再看本家族遵循的能力 seam 拆分。 - [设置子系统参考](../../docs/subsystems/settings.zh.md)——namespace、分层解析、descriptor、变更提交与生成的 cordis 接口面。 - [能力 seam](../../docs/capability-seams.zh.md)——本家族遵循的 Service Definition / Service Provider / Consumer 拆分。 ## 开发备注
维护者的工作上下文——点击展开 无。
# credentials/：凭据与授权 ``` --- description: "凭据能力族的包映射：凭据引用 seam、环境与文件提供方、授权 flow 注册表，以及引用如何让机密值留在配置之外。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 `credentials/` 组管理你的配置按名引用的机密值：API 密钥只存一次，在 settings 或 `cordis.yml` 中按名引用，轮换时无需编辑任何配置文件。它提供产品中负责存储与查询机密的运行时部分（`credentials/`）、默认的本机凭据文件（`credentials-local/`），以及授权 flow 注册表（`authorization/`）——用于获取无法配置、只能开口去要的凭据。轮换后的密钥会作用于紧随其后的下一次模型请求，而按次运行的环境覆盖（`DEEPSEEK_API_KEY=… dsh`）始终优先于存储值。机密值绝不进入你同步或渲染的配置文件——进去的只有它们的名字，而且本地文件只有同一 OS 用户可读，其他用户读不到。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 三个包共同提供凭据功能：一个在运行时存储、查询与移除机密，而配置只写名字；第二个是默认的本机存储；第三个让插件获取必须开口去要的凭据。它们的 README 覆盖日常使用；子系统参考拥有穷尽式约定。 | 包 | 角色 | ctx 键 | |---|---|---| | [`credentials/`](credentials/README.zh.md) | 在运行时存储、查询与移除机密，而配置只写名字 | `ctx.credentials` | | [`credentials-local/`](credentials-local/README.zh.md) | 默认本机存储：一个私有 YAML 文件，环境覆盖优先 | 注册 `ctx.credentials` | | [`authorization/`](authorization/README.zh.md) | 由插件拥有、通过询问人来取得凭据的 flow | `ctx.authorization` | ----- ## 相关文档 先从子系统参考了解共享词汇，再看能力 seam 表与本地存储的配置面。 - [凭据子系统参考](../../docs/subsystems/credentials.zh.md)——`CredentialRef` 与 `CredentialKey`、按操作解析、对 UI 安全的 `CredentialInfo`、授权 flow 与生成的 cordis 接口面。 - [能力 seam](../../docs/capability-seams.zh.md)——本家族遵循的 Service Definition / Service Provider / Consumer 拆分。 - [生成配置目录](../../docs/config-catalog.zh.md#deepseek-aidsh-credentials-local)——本地存储的每个受支持字段。 ## 开发备注
维护者的工作上下文——点击展开 无。
# storage/ 非会话存储中枢 + 后端 + 领域形式 ``` --- description: "存储组地图：通过具名后端与类型化领域数据形式持久化非会话数据，供浏览本组的用户与维护者阅读。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 存储组为组合提供会话事件日志以外一切数据的持久存储：工作区记录、会话伴随数据，以及其他宿主侧应用数据。借助它，宿主包可以经 schema 校验过的领域数据形式持久化类型化记录，在人类可读的 JSON 后端与支持定点更新的 SQLite 后端之间选择，并在每次持久写入后收到变更事件。本家族是可选项，且只面向宿主侧：它不注册工具、不注入提示词，也不写入会话事件，因此模型与 agent loop（智能体循环）永远不会看到它。当产品需要跨重启保留应用状态时使用它；没有任何此类数据的组合可以省略整个组。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | ctx 键 | |---|---|---| | [`storage`](storage/README.zh.md) | 把已注册后端与已挂载的数据形式设施连接起来 | `ctx.storage` | | [`storage-json`](storage-json/README.zh.md) | 把每个单元存为一个人类可读的 JSON 文件 | 注册后端 `json` | | [`storage-sqlite`](storage-sqlite/README.zh.md) | 把单元作为 JSON 文档存进一个 SQLite 数据库 | 注册后端 `sqlite` | | [`storage-domain`](storage-domain/README.zh.md) | 在已路由后端之上提供经过 schema 校验、发出变更事件的 KV 领域 | `ctx.storageDomain` | ----- ## 相关文档 - [存储子系统](../../docs/subsystems/storage.zh.md)——权威约定：后端约定、领域声明、变更事件与生成的 API。 - [领域 KV 存储 Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md)——本家族的设计、workspace 消费方与被推迟的会话后端迁移。 - [Workspace 子系统](../../docs/subsystems/workspace.zh.md)——领域数据形式的第一个消费方。 ----- ## 开发备注
维护者的工作上下文——点击展开 设计 Agent Note 仍标记为 proposed，而本家族已经发布；其范围外事项表就是迁移阶段（`log` 分面、会话后端复用、跨进程变更推送）的延期工作清单。决策落地后，请把结论提升为 implemented 笔记。
# workspace/ Workspace 实体 ``` --- description: "workspace 组地图：持久工作区实体家族、用户目录的持久记录与基于会话头的成员资格记账，供浏览本组的用户与维护者阅读。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 workspace 组提供宿主 UI 背后的持久项目列表：一个产品包 `workspace`，把用户目录命名为项目、保持稳定顺序，并把每个项目的会话归入其下。借助它，UI 可以显示带会话的项目侧边栏、把会话从分组中隐藏而不删除它，以及移除项目——移除绝不会删除文件夹或会话历史，它们只会变成 Ungrouped。本组只面向宿主侧：没有工具、提示词或会话事件，因此模型与 agent loop 永远不会看到它。当产品展示持久 workspace 或项目界面时使用它；它需要会话存储与持久化后端一并挂载。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | ctx 键 | |---|---|---| | [`workspace`](workspace/README.zh.md) | 提供命名且有序的项目，并在每个目录下聚合其会话 | `ctx.workspaceRegistry` | ----- ## 相关文档 - [Workspace 子系统](../../docs/subsystems/workspace.zh.md)——项目及其会话的权威功能约定。 - [领域 KV 存储 Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md)——项目记录背后的存储设计。 - [Workspace UI 产品流 Agent Note](../../.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md)——首次启动如何从会话历史构建项目，以及 GUI 如何排序。 - [删除 Workspace 注册记录决策](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md)——为什么移除项目绝不会删除其文件夹或会话。 ----- ## 开发备注
维护者的工作上下文——点击展开 无。
# sdk/：从另一进程驱动 Harness 运行时 ``` --- description: "SDK 能力家族的包映射：JSON-RPC 协议格式，以及供进程外 SDK 使用的 TypeScript 客户端与服务器。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 本组让另一进程驱动完整的 DeepSeek Harness 运行时：JSON-RPC 协议格式定义消息，服务插件通过 stdio 为外部客户端提供服务，TypeScript 与 Python 客户端则用具名 profile 和有序 patch 启动 `dsh`。本组没有任何包定义独立应用或创建开发者项目。SDK 客户端可以打开会话、发送提示词，并实时观察会话事件、agent 状态转换与 subagent 完成事件。TypeScript 客户端是 [Python SDK](../../python/README.zh.md) 的设计孪生，二者说同一种协议。本页是组的映射；各包 README 负责各自的包级约定。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 每个包 README 描述你可用该包部分完成的事情。 | 包 | 职责 | |---|---| | [`protocol/`](protocol/README.zh.md) | 协议格式：按换行分帧的 JSON-RPC 传输，以及具名的请求、结果与通知类型 | | [`client/`](client/README.zh.md) | TypeScript 客户端：启动运行时子进程，通过高层与协议层 API 驱动 agent 轮次 | | [`server/`](server/README.zh.md) | `jsonrpc` 插件：通过 stdio 为进程外 SDK 客户端提供服务 | ----- ## 相关文档 先从 Python SDK（客户端约定的姊妹实现）开始，再看可运行应用与组边界背后的决策记录。 - [Python SDK](../../python/README.zh.md) — 说同一种协议的 Python 对侧实现，并随附捆绑运行时。 - [SDK 应用组合包](../bundle/sdk-app/README.zh.md) — 启动 JSON-RPC 服务器的 `dsh --profile sdk` 应用。 - [Python profile 运行时决策](../../.agents/notes/implemented/architecture/2026-08-23-python-sdk-dsh-profile-runtime.zh.md) — 打包后的 Python 客户端为何启动相同的具名 profile。 - [TypeScript SDK 与 SDK subagent 后端决策](../../.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md) — 客户端约定及其上的 subagent 后端。 - [SDK 项目工具链移除](../../.agents/notes/implemented/simplification/2026-08-11-remove-sdk-project-toolchain.zh.md) — 本组为何从不创建、配置或构建开发者项目。 - [SDK subagent 提供方](../subagent/subagent-dsh-sdk/README.zh.md) — harness 内部消费 TypeScript 客户端的例子。 ## 开发备注 无。 # acp/ — Agent Client Protocol 自动化 ``` --- description: "ACP（Agent Client Protocol）包组：通过 JSON-RPC stdio 将全新 harness agent 暴露给程序化客户端的仅自动化服务器。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 acp 组提供一个包：一台服务器，让程序与自动化可以通过标准 Agent Client Protocol 运行持久 DeepSeek Harness agent。客户端可以创建、列出、恢复与关闭会话，挂载标准 MCP 服务器，选择模型选项，发送文本与图片提示词，接收语义更新，响应权限提示并取消工作——无需人类参与。从另一个 harness 启动这种服务器的配套客户端位于 `subagent/subagent-acp`。本页是组的映射；包 README 负责各自的包级约定。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | |---|---| | [`acp/`](acp/README.zh.md) | 让程序通过 ACP 管理持久 agent、挂载 MCP 服务器、选择模型选项、发送或取消工作并接收语义更新 | ----- ## 相关文档 - [dsh-subagent-acp](../subagent/subagent-acp/README.zh.md)——spawn 并驱动本服务器的进程外 ACP 客户端。 - [ACP 作为仅面向自动化的协议](../../.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md)——自动化约定及其协议边界的决策记录。 - [在单个连接上多路复用并发 ACP 会话](../../.agents/notes/implemented/feature/2026-06-14-acp-multi-session.zh.md)——按会话隔离、归属与清理决策。 ## 开发备注 无。 # interaction/：人机协作平面 ``` --- description: "人机协作能力族的包映射：斜杠命令、一次性审批、权限预设，以及让运行中的 agent 暂停等待人类决定的问答 seam。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 `interaction/` 组是人机协作的场所。它提供用户输入所用的斜杠命令平面、敏感操作背后的一次性审批决定、把沙箱模式与审批策略捆绑为具名预设的权限预设，以及 agent 需要人类决定时暂停等待的问答服务。五个包都是产品包——由用户直接操作的真实接口——产品 `dsh` CLI 直接组合它们。交互式应用直接驱动命令、审批与提问接口，自动化则改用 ACP 传输。子系统参考拥有穷尽式约定；本映射指向每个包及其相邻包。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 每个包的 README 与对应子系统参考拥有穷尽式约定。 | 包 | 角色 | ctx 键 | |---|---|---| | [`commands/`](commands/README.zh.md) | 让用户输入斜杠命令，直接针对 agent 执行，无需模型往返 | `ctx.commands` | | [`user-approval/`](user-approval/README.zh.md) | 向已组合的应答者征求一次性允许／拒绝决定，缺失时以拒绝方式关闭 | `ctx.approval` | | [`permission-presets/`](permission-presets/README.zh.md) | 把沙箱模式与审批策略捆绑为一个面向用户的权限选择器 | `ctx.permissionPresets` | | [`user-questions/`](user-questions/README.zh.md) | 定义经过校验的问题 schema 与作用域 answerer waterfall，agent 可暂停等待 | `ctx.userQuestions` | | [`tool-ask-user/`](tool-ask-user/README.zh.md) | 暴露 `ask_user_question` 工具，让模型可以向用户提问 | 注册到 `ctx.tools` | ----- ## 相关文档 先从子系统参考了解共享词汇，再看相邻的自动化与组合面。 - [命令子系统](../../docs/subsystems/commands.zh.md)——命令注册表语义与 `ctx.commands` 的 cordis 接口面。 - [审批子系统](../../docs/subsystems/approval.zh.md)——请求／结果词汇、应答者瀑布与按会话策略。 - [权限预设子系统](../../docs/subsystems/permission-presets.zh.md)——预设表与旋钮写穿。 - [用户交互子系统](../../docs/subsystems/user-questions.zh.md)——问题词汇、answerer waterfall 与呈现意图。 - [ACP 组](../acp/README.zh.md)——仅自动化的传输，为其自有 agent 回答审批请求。 ## 开发备注
维护者的工作上下文——点击展开 无。
# boot/：共享的 app bin 启动粘合层 ``` --- description: "boot 包组：dsh app bin 如何启动——环境加载、profile 与 patch 层、清晰的启动失败信息，以及由应用持有的命令行。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 boot 组提供每个 dsh app bin 启动所需的全部能力：`app-boot` 把 `cordis.yml` 连同你的环境与 patch 层变成运行中的应用，并给出清晰的失败信息；`cmdline` 让应用持有自己的命令行 flag 与 `--help`。借助这些包，你可以运行 `dsh`，也可以编写以同样方式启动的新应用或测试 fixture。两者都是 `apps/cli` 与测试专用 Loader fixture 导入的库，绝不是组合加载的插件。本页是组的映射；各包 README 负责各自的包级约定。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ## 包 | 包 | 职责 | ctx 键 | |---|---|---| | [`app-boot`](app-boot/README.zh.md) | 从 `cordis.yml` 启动 dsh 应用：加载 `.env`、应用 profile 与 patch 层，并清晰报告启动失败 | （供各 bin 使用的库） | | [`cmdline`](cmdline/README.zh.md) | 让应用持有自己的 flag、`--help` 与退出码；启动器自身 flag 之后的一切原样传入 | `cmdlineArgs`、`appExit` | ## 相关文档 - [dsh 应用](../../apps/cli/README.zh.md)——在其启动序列中使用这些 helper 的 `dsh` bin。 - [Profile 组合包](../bundle/README.zh.md)——可由 `dsh --profile` 组合挂载的可安装 patch 层。 - [dsh-home-paths](../util/home-paths/README.zh.md)——两个包都依赖的 harness home 解析器。 - [应用持有命令行决策](../../.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.zh.md)——为什么 flag 家族由应用持有而非启动器。 ## 开发备注 无。 # host/ — Web GUI 宿主侧 ``` --- description: "Web GUI Host 侧的包映射：HTTP 与 SPA 服务器、工作区目录选择实现和插件清单投影。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 `host/` 组提供 Web GUI 的普通 HTTP 服务器、服务已构建 Web 壳的 SPA dist 服务器、带原生／浏览／自适应组合包的工作区目录选择 seam，以及只读的插件清单投影。这七个包都是产品包；浏览器传输位于 [`client/`](../client/README.zh.md)，组合应用是 [`apps/cli`](../../apps/cli/README.zh.md)，它启动 [`dsh-base` 组合包](../bundle/base/cordis.patch.yml) 来提供 `apps/web/` 下的 Web 应用。选择器后端可在共享 seam 后互相替换。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 七个包分别承担 Host 角色；各包的 README 拥有自己的约定与配置。 | 包 | 职责 | ctx 键 | |---|---|---| | [`webserver/`](webserver/README.zh.md) | 浏览器 HTTP 服务器：具名路由、upgrade、index 转换与回退席位 | `ctx.webServer` | | [`frontend-static/`](frontend-static/README.zh.md) | 占据 webserver 回退席位的 SPA dist 服务器 | 消费 `ctx.webServer` | | [`directory-picker/`](directory-picker/README.zh.md) | 工作区目录选择 seam：能力约定与错误词汇 | `ctx.directoryPicker` | | [`directory-picker-native/`](directory-picker-native/README.zh.md) | 面向宿主屏幕前操作者的原生 OS 选择器后端 | 注册 `ctx.directoryPicker` | | [`directory-picker-browse/`](directory-picker-browse/README.zh.md) | 应用内目录浏览器后端，也服务于远程客户端 | 注册 `ctx.directoryPicker` | | [`directory-picker-auto/`](directory-picker-auto/README.zh.md) | 在启动时挂载匹配后端的宿主自适应选择器 | 挂载一个后端 | | [`plugin-inventory/`](plugin-inventory/README.zh.md) | 当前 Loader 条目的只读投影 | Remote `pluginInventory/list` | ----- ## 相关文档 先从传输与工作区记录的子系统参考读起，再看 Web Client 背后的分层决策。 - [HTTP 服务器子系统](../../docs/subsystems/web-server.zh.md)——webserver 的路由、匹配顺序与配置。 - [工作区子系统](../../docs/subsystems/workspace.zh.md)——目录选择器所喂给的工作区记录。 - [Web 配置树启动与传输分层](../../.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md)——Web 传输各层的所有权。 ## 开发备注
维护者的工作上下文——点击展开 无。
# client/ — Web GUI 浏览器侧 ``` --- description: "web GUI 浏览器侧的包映射：外壳启动、浏览器与宿主通信、共享客户端服务、本地化、开发重载与 UI 功能插件。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 `client/` 组运行 dsh web GUI 的浏览器侧：它启动 web 外壳、加载浏览器侧插件模块、维持浏览器与宿主之间的 RPC 与事件投递，并提供渲染应用所需的共享客户端服务与 UI 功能插件。UI 功能通过 slot 系统组合——每个插件填充已声明的扩展 slot，携带类型化 props 与 store，由外壳渲染组装后的整棵树。本组所有包均为产品包，名为 `@deepseek-ai/dsh-client-`；服务于页面的宿主半侧位于 [`host/`](../host/README.zh.md)。编写规则见 [AGENTS.md](AGENTS.md)，模块图、slot 模型与对象层的说明见下方相关文档。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 内核包负责启动与服务于页面，UI 功能包负责呈现页面。各包的 README 拥有自己的约定与配置。 | 包 | 职责 | ctx 键 | |---|---|---| | [`web/`](web/README.zh.md) | 启动浏览器外壳 | — | | [`modules/`](modules/README.zh.md) | 加载浏览器侧客户端模块 | `ctx.clientModules` / `ctx.modules` | | [`connection/`](connection/README.zh.md) | 维护浏览器与宿主之间的 RPC 通信与事件投递 | `ctx.connection` | | [`store/`](store/README.zh.md) | 提供不依赖 React 的 observable 与 snapshot-store 原语 | — | | [`hmr/`](hmr/README.zh.md) | 在开发期间刷新客户端插件 | — | | [`locale/`](locale/README.zh.md) | 提供本地化偏好与消息词典 | `ctx.locale` | | [`test-runtime/`](../test-support/client-runtime/README.zh.md) | 为客户端功能包提供共享的仓库测试支持 | — | | [`ui-renderer/`](ui-renderer/README.zh.md) | 将 slot 数据绑定到 React，并挂载组装完成的应用 | `ctx.uiRenderer` | | [`ui-slots/`](ui-slots/README.zh.md) | 定义 UI 功能注册与组合扩展 slot 的方式 | — | | [`ui-session/`](ui-session/README.zh.md) | 把 Session Controller 状态适配为标准 Slot source 与 hook | — | | [`ui-theme/`](ui-theme/README.zh.md) | 应用所选颜色主题 | — | | [`ui-primitives/`](ui-primitives/README.zh.md) | 提供共享 React 控件、图标与内容渲染器 | — | | [`ui-attachment/`](ui-attachment/README.zh.md) | 注册输入框与消息图片的附件呈现 | — | | [`ui-layout/`](ui-layout/README.zh.md) | 排列应用的主要区域 | — | | [`ui-sidebar/`](ui-sidebar/README.zh.md) | 展示工作区与会话导航 | — | | [`ui-brand-official/`](ui-brand-official/README.zh.md) | 用官方名称与标记填充通用浏览器品牌 slot | — | | [`ui-workspace/`](ui-workspace/README.zh.md) | 提供工作区选择与创建界面 | — | | [`ui-conversation/`](ui-conversation/README.zh.md) | 展示当前对话及其输入界面 | — | | [`ui-chat/`](ui-chat/README.zh.md) | 投影并渲染 Chat 对话 target | — | | [`ui-approval/`](ui-approval/README.zh.md) | 展示批准请求并返回用户决策 | — | | [`ui-tool/`](ui-tool/README.zh.md) | 编排工具调用树与按工具键控的视图 | — | | [`ui-workflow-run/`](ui-workflow-run/README.zh.md) | 把持久工作流运行回放为嵌套对话折叠项 | — | | [`ui-goal/`](ui-goal/README.zh.md) | 展示与管理当前目标 | — | | [`ui-trajectory/`](ui-trajectory/README.zh.md) | 提供 agent（智能体）活动的其他视图 | — | | [`ui-commands/`](ui-commands/README.zh.md) | 提供会话感知的命令发现与分发 | — | | [`ui-input-trigger/`](ui-input-trigger/README.zh.md) | 协调内联命令与引用建议 | — | | [`ui-skill/`](ui-skill/README.zh.md) | 向内联建议添加 skill（技能）引用 | — | | [`ui-reference/`](ui-reference/README.zh.md) | 统一的 Web `@file` / `@session` 引用 source | — | | [`ui-subagent/`](ui-subagent/README.zh.md) | 提供 subagent（子智能体）导航、子级 transcript（文本记录）状态与内联引用 | — | | [`ui-schedule/`](ui-schedule/README.zh.md) | 在只读标题栏目录中列出当前 Session 的活动提醒 | — | | [`ui-jobs/`](ui-jobs/README.zh.md) | 在会话标题栏列出当前会话的后台任务 | — | | [`ui-model-selection/`](ui-model-selection/README.zh.md) | 在对话界面中提供模型选择 | — | | [`ui-permission-presets/`](ui-permission-presets/README.zh.md) | 配置默认权限并切换当前会话的访问模式 | — | | [`ui-plan/`](ui-plan/README.zh.md) | 展示生效中的 plan mode 状态及其退出控件 | — | | [`ui-settings-plugins/`](ui-settings-plugins/README.zh.md) | 拥有“插件”设置分区、其标签页扩展点与可配置的宿主平面插件卡片 | — | | [`ui-user-questions/`](ui-user-questions/README.zh.md) | 展示 agent 请求的交互式问题 | — | | [`ui-agent-preset/`](ui-agent-preset/README.zh.md) | 选择会话的 agent 预设并编写预设组合 | — | | [`ui-settings/`](ui-settings/README.zh.md) | 承载设置界面及其扩展区域 | — | | [`ui-settings-general/`](ui-settings-general/README.zh.md) | 提供常规设置分区 | — | | [`ui-settings-models/`](ui-settings-models/README.zh.md) | 提供模型提供方配置与 DeepSeek 引导 | — | | [`ui-settings-plugin-inventory/`](ui-settings-plugin-inventory/README.zh.md) | 向“插件”设置贡献只读的 Host Loader 清单标签页 | — | | [`ui-deliverables/`](ui-deliverables/README.zh.md) | 生成已产出文件的轮次尾部与可点击的最终响应文件引用 | — | | [`ui-message-feedback/`](ui-message-feedback/README.zh.md) | 向助手消息操作条贡献逐消息反馈控件 | — | | [`ui-directory-picker-browse/`](ui-directory-picker-browse/README.zh.md) | 面向工作区目录流程的应用内目录浏览界面 | — | | [`ui-directory-picker-native/`](ui-directory-picker-native/README.zh.md) | 驱动宿主 OS 选择器的原生目录选择界面 | — | ----- ## 相关文档 先从子系统参考与两份拥有跨包组合决策的 Agent Note 读起，再看服务于本页的宿主半侧。 - [客户端模块子系统](../../docs/subsystems/client-modules.zh.md)——web 插件表：`dsh.client` 声明、启动图协议与 bundle 路由。 - [slot 系统标准](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md)——权威 slot 模型：注册、props 份额与 store。 - [web 客户端架构 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md)——加载链、对象层与客户端服务。 - [宿主组地图](../host/README.zh.md)——服务于本浏览器半侧的宿主半侧。 ## 开发备注
维护者的工作上下文——点击展开 无。
# test-support/ 支持基础设施（testkit、不变式、回放、Loader 冒烟测试） ``` --- description: "test-support 组地图：面向编写与运行仓库测试的开发者，提供无密钥测试工具、LLM mock 与回放服务器以及 Loader 冒烟测试辅助。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 test-support 组为仓库测试提供确定性、无密钥地运行真实产品的方式。它包含 Loader 应用 harness、session-log 快照适配器、回放 LLM（大语言模型）插件和可编脚本的 OpenAI 兼容故障服务器。每个包都是支持层基础设施；当某个包获得产品约定与产品消费方时，它就会移出本组。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | |---|---| | [`session-snapshot`](session-snapshot/README.zh.md) | 为 profile 驱动的测试提供 session-log 快照支持与协议适配器 | | [`agent-loop-testkit`](agent-loop-testkit/README.zh.md) | 为运行具体 AgentLoop 的测试提供共享先决服务 | | [`client-runtime`](client-runtime/README.zh.md) | 为浏览器功能测试提供 jsdom slot 测试台 | | [`loader-smoke`](loader-smoke/README.zh.md) | 启动由 Loader 组合的应用并驱动 fixture 轮次以执行冒烟测试 | | [`llm-mock-server`](llm-mock-server/README.zh.md) | 为恢复测试提供可编脚本的 OpenAI 兼容故障服务器 | | [`llm-replay`](llm-replay/README.zh.md) | 为无密钥测试与演示回放已记录的模型流 | ----- ## 相关文档 - [测试策略](../../docs/testing.zh.md)——这些 harness 所服务的无密钥快照层及其适用时机。 - [运行时不变式子系统](../../docs/subsystems/invariants.zh.md)——每个 test-support 包以 `./invariant` 形式随附的包自有运行时检查。 - [包组](../README.zh.md)——支持组与产品组的关系。 ----- ## 开发备注
维护者的工作上下文——点击展开 无。
# runtime-diagnostics/ 运行时诊断：按包归属的运行时不变式检查与报告 ``` --- description: "runtime-diagnostics 组地图：面向用户与维护者浏览本组的包自有运行时检查能力。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 runtime-diagnostics 组为 DeepSeek Harness 组合提供运行时自检：一个包 `invariants` 在组合运行期间运行包自有检查，验证每个包的持久事件与数据关系。违规会以归因到拥有该关系的包的错误呈现；全局开关与包名过滤器控制运行哪些检查。当组合需要在正常运行中验证自身运行时约定时，请使用本组的包。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 | 包 | 职责 | ctx 键 | |---|---|---| | [`invariants`](invariants/README.zh.md) | 运行包自有运行时检查，并按所属包报告每次失败 | 注册到 `ctx.invariants` | ----- ## 相关文档 - [运行时不变式子系统](../../docs/subsystems/invariants.zh.md)——生成的服务参考：选择、installer 与配套入口约定。 - [包自有不变式服务 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md)——检查为何放在归属者旁边，以及注册表为何拥有选择与生命周期。 - [不变式运行时约定 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md)——运行时不变量可以断言什么，以及强制配套入口接线的机械门禁。 - [包约定](../AGENTS.md)——每个包都必须遵循的 `./invariant` 配套入口规则。 ----- ## 开发备注
维护者的工作上下文——点击展开 无。
# util/：共享工具 ``` --- description: "共享工具家族的包映射：原子文件写入、品牌化 id、双端队列、JSON 值、harness 主目录路径、启动环境、原生命令、输出保留、时区与超时。" kind: "package-group" --- ``` [English](README.md) | 中文 ## 概述 `util/` 组为能力包提供共享的机制原语，避免重复实现。它涵盖原子写入、品牌化 id、双端队列、无损 JSON 值、UUID、Harness home 路径、启动环境、原生命令、输出保留、时区规范化和超时处理。这里的每个根入口都是库：它不注册产品服务或事件，业务语义仍由消费它的能力负责。 ## 目录 - [包](#packages) - [相关文档](#related-documentation) - [开发备注](#dev-note) ----- ## 包 每个包提供一个原语；打开对应包页面了解如何使用。 | 包 | 职责 | |---|---| | [`brand/`](brand/README.zh.md) | 提供名义字符串类型及其无状态构造函数 | | [`crypto/`](crypto/README.zh.md) | 基于跨运行时 `crypto.getRandomValues` 原语生成 RFC 9562 v4 UUID | | [`deque/`](deque/README.zh.md) | 提供摊销常数时间的队列操作和有界空闲存储 | | [`values/`](values/README.zh.md) | 校验、创建快照、比较和冻结无损 JSON 兼容值 | | [`home-paths/`](home-paths/README.zh.md) | 解析统一的 Harness 主目录并拼接共享的用户数据路径 | | [`launch-environment/`](launch-environment/README.zh.md) | 冻结的启动环境，记住每个值来自哪一层 | | [`atomic-write/`](atomic-write/README.zh.md) | 原子文件替换与跨进程写锁 | | [`native-command/`](native-command/README.zh.md) | 直接运行宿主原生命令，绝不拼 shell 字符串 | | [`workspace-path/`](workspace-path/README.zh.md) | 提供浏览器安全的 Workspace 路径与显示辅助函数 | | [`output-retention/`](output-retention/README.zh.md) | 限制面向模型的输出并报告精确的省略元数据 | | [`time/`](time/README.zh.md) | 校验并规范化调用方所报的 IANA 时区 | | [`timeout/`](timeout/README.zh.md) | 截止时间运算、信号融合与超时/取消分类 | ----- ## 相关文档 - [根包映射](../README.zh.md)——`util/` 在所有包组中的位置。 - [生成配置目录](../../docs/config-catalog.zh.md)——本组所属的库包索引。 - [添加包实操手册](../../docs/cookbook/adding-a-package.zh.md)——新的共享原语如何落入本组。 ## 开发备注
维护者的工作上下文——点击展开 无。