diff --git a/docs/02-user-guide/06-agents/03-create-agent.md b/docs/02-user-guide/06-agents/03-create-agent.md index 1b1d651..1fb79c5 100644 --- a/docs/02-user-guide/06-agents/03-create-agent.md +++ b/docs/02-user-guide/06-agents/03-create-agent.md @@ -6,6 +6,10 @@ keywords: [创建智能体, 自定义 Agent, 对话创建, 模板] # 创建自定义智能体 +:::info 长期指令的版本支持 +`instructions.md` 已在开发分支的 10.0.179 实现。截至 2026-10-09，最新公开发行版仍为 v10.0.177；正式发行版需要升级到包含这项能力的版本后才能使用。 +::: + 当市场上没有满足你需求的智能体时，你可以创建一个完全自定义的智能体。DesireCore 提供两种创建方式。 ## 通过对话创建（推荐） @@ -24,6 +28,7 @@ keywords: [创建智能体, 自定义 Agent, 对话创建, 模板] - **角色定位**：专业领域和行为风格 - **技能需求**：需要哪些能力 - **行为准则**：有什么该做或不该做的 + - **长期指令**（可选）：这个智能体长期负责什么、默认怎样工作、应交付什么 4. 确认后，核心智能体自动创建完整的智能体配置 5. 新智能体出现在你的智能体列表中，可以立即使用 @@ -47,8 +52,7 @@ keywords: [创建智能体, 自定义 Agent, 对话创建, 模板] 3. 配置人格设定（`persona.md`）： - 角色定位和语气风格 - - 回答策略和确认策略 - - 禁区和边界 + - 表达习惯和回答组织方式 4. 配置行为准则（`principles.md`）： - 核心原则 @@ -59,6 +63,14 @@ keywords: [创建智能体, 自定义 Agent, 对话创建, 模板] - 从技能市场安装 - 或手动编写 SKILL.md +### 补充长期指令（可选） + +长期职责可以在创建时通过对话提出，也可以创建后再补充，例如： + +> “为这个财务助手保存长期指令：每次分析先核实数据期间和口径，交付结论、关键指标、计算依据和待确认问题。详细分析步骤放在技能里。” + +内容保存在 `instructions.md`。创建后可通过[文件资源管理器](./06-agent-files.md)或[提示词中心](./12-prompt-center.md)编辑；不需要把长期职责塞进人格或行为准则，也不要求填写 L0/L1/L2。用户、团队和项目专属约定仍保留在对应作用范围。完整格式见[文件格式说明](../../05-more/06-file-formats.md)。 + ### AgentFS 目录结构 创建完成后，智能体的文件存放在 `~/.desirecore/agents//`： @@ -68,6 +80,7 @@ keywords: [创建智能体, 自定义 Agent, 对话创建, 模板] ├── agent.json # 入口配置（名称、描述、版本等） ├── persona.md # 人格设定 ├── principles.md # 行为准则 +├── instructions.md # 可选长期职责、工作策略与交付标准 ├── memory/ # 记忆目录 ├── skills/ # 技能目录 ├── tools/ # 工具注册 diff --git a/docs/02-user-guide/06-agents/04-edit-persona.md b/docs/02-user-guide/06-agents/04-edit-persona.md index 1ce0dfe..7e2aea0 100644 --- a/docs/02-user-guide/06-agents/04-edit-persona.md +++ b/docs/02-user-guide/06-agents/04-edit-persona.md @@ -6,6 +6,10 @@ keywords: [人格设定, Persona, 角色定位, 性格特征, 智能体配置] # 编辑人格设定 +:::info 长期指令的版本支持 +`instructions.md` 已在开发分支的 10.0.179 实现。截至 2026-10-09，最新公开发行版仍为 v10.0.177；正式发行版需要升级到包含这项能力的版本后才能使用。 +::: + 人格设定（Persona）定义了智能体"是谁"——它的语气、风格、专业领域和行为方式。这不是一段人设文案，而是一份**可执行的行为规范**。 ## 什么是人格设定 @@ -16,14 +20,13 @@ keywords: [人格设定, Persona, 角色定位, 性格特征, 智能体配置] |---|---|---| | **回答策略** | 怎么回答问题 | "先给结论，再给理由；少客套" | | **语气风格** | 用什么口吻说话 | "专业但不刻板，简洁但不敷衍" | -| **确认策略** | 什么时候要问用户 | "发消息、删除、付费操作前必须确认" | | **禁区** | 什么不该做 | "不要使用模板腔，不要回避给结论" | | **不确定处理** | 拿不准时怎么办 | "说明不确定点并给验证路径" | -`persona.md` 是 **Agent 层提示词**的一部分。运行时还会叠加当前用户的全局提示词和智能体所属团队的团队提示词；你可以在 **资源管理器 → 提示词中心**中集中编辑并预览最终组合。详见[提示词中心与三层提示词](./12-prompt-center.md)。 +`persona.md` 是 **Agent 层提示词**的一部分。运行时还会叠加当前用户的全局提示词和智能体所属团队的团队提示词；你可以在 **资源管理器 → 提示词中心**中集中编辑并预览最终组合。详见[提示词中心与内容归属](./12-prompt-center.md)。 -:::info 人格 vs 行为准则 -**人格设定**定义的是"怎么做"——语气、风格、回答方式。**行为准则**（Principles）定义的是"做什么和不做什么"——规则、边界、优先级。两者互补但不重叠。 +:::info 人格、行为准则与长期指令 +**人格**定义角色和表达风格；**行为准则**定义边界、禁区和优先级；可选 **`instructions.md`** 保存 Agent 专属的稳定职责、默认工作策略和交付标准。用户偏好、团队与项目约定保留在对应作用范围，详细方法放入技能。见[文件格式说明](../../05-more/06-file-formats.md)。 ::: ## 编辑名称、头像、描述 @@ -103,5 +106,5 @@ keywords: [人格设定, Persona, 角色定位, 性格特征, 智能体配置] ## 下一步 - [编辑行为准则](./05-edit-principles.md) — 为智能体设定行为边界 -- [提示词中心与三层提示词](./12-prompt-center.md) — 管理全局、团队和 Agent 提示词 +- [提示词中心与内容归属](./12-prompt-center.md) — 管理全局、团队和 Agent 提示词 - [创建自定义智能体](./03-create-agent.md) — 回顾创建流程 diff --git a/docs/02-user-guide/06-agents/05-edit-principles.md b/docs/02-user-guide/06-agents/05-edit-principles.md index 0765756..f56c2b4 100644 --- a/docs/02-user-guide/06-agents/05-edit-principles.md +++ b/docs/02-user-guide/06-agents/05-edit-principles.md @@ -6,6 +6,10 @@ keywords: [行为准则, Principles, L0, L1, L2, 安全规则, 优先级] # 编辑行为准则 +:::info 长期指令的版本支持 +`instructions.md` 已在开发分支的 10.0.179 实现。截至 2026-10-09，最新公开发行版仍为 v10.0.177；正式发行版需要升级到包含这项能力的版本后才能使用。 +::: + 行为准则（Principles）是智能体的"行为手册"——它规定了智能体必须遵守的规则、禁止触碰的红线，以及决策时的优先级排序。 ## 什么是行为准则 @@ -44,9 +48,9 @@ L1 保存执行任务时需要直接看到的关键要点，默认注入系统 L2 保存较长的解释、例外、示例和操作细节，默认不注入，由智能体在需要时读取： -- 输出格式偏好（Markdown / 纯文本） -- 回答详细程度（简洁 / 详尽） -- 特定领域的工作习惯 +- 某条边界的解释与判定示例 +- 例外情况及其确认条件 +- 发生规则冲突时的优先级说明 | 层级 | 默认加载 | 建议内容 | 可编辑 | |---|---|---|---| @@ -83,7 +87,9 @@ L2 保存较长的解释、例外、示例和操作细节，默认不注入， ## 与其他提示词层的关系 -运行时按 **全局 → 所属团队 → Agent 人格 → Agent 行为准则** 组合可编辑提示词，再加入团队身份、工具、记忆等系统上下文。L0/L1/L2 决定每个文件加载多少内容；全局/团队/Agent 决定规则的适用范围。请避免在不同层重复写相互矛盾的规则，并用提示词预览检查最终组合。 +在支持长期指令的版本中，运行时按 **全局 → 所属团队 → Agent 人格 → Agent 行为准则 → Agent 长期指令** 组合可编辑片段，再加入团队身份、工具、记忆等上下文。L0/L1/L2 只控制分层文件的加载粒度；`instructions.md` 使用普通 Markdown，获准时全文加载。 + +边界和优先级留在原则中，稳定职责与交付要求写入长期指令，角色与表达方式留在人格中。用户、团队和项目要求保留在对应作用范围；详细 SOP 放入技能。完整约定见[文件格式说明](../../05-more/06-file-formats.md)。请用提示词预览检查重复和冲突。 :::tip 准则写作建议 - **具体胜于模糊**："涉及金额超过 1000 元的操作前必须确认"比"大额操作要确认"更好 @@ -95,4 +101,4 @@ L2 保存较长的解释、例外、示例和操作细节，默认不注入， - [文件资源管理器](./06-agent-files.md) — 浏览智能体的文件结构 - [编辑人格设定](./04-edit-persona.md) — 调整智能体的语气和风格 -- [提示词中心与三层提示词](./12-prompt-center.md) — 理解全局、团队和 Agent 的组合顺序 +- [提示词中心与内容归属](./12-prompt-center.md) — 理解全局、团队和 Agent 的组合顺序 diff --git a/docs/02-user-guide/06-agents/06-agent-files.md b/docs/02-user-guide/06-agents/06-agent-files.md index c4f4755..671eca8 100644 --- a/docs/02-user-guide/06-agents/06-agent-files.md +++ b/docs/02-user-guide/06-agents/06-agent-files.md @@ -6,6 +6,10 @@ keywords: [AgentFS, 文件系统, 资源管理器, 智能体文件, 文件结构 # 文件资源管理器 +:::info 长期指令的版本支持 +`instructions.md` 已在开发分支的 10.0.179 实现。截至 2026-10-09，最新公开发行版仍为 v10.0.177；正式发行版需要升级到包含这项能力的版本后才能使用。 +::: + 每个智能体的所有配置、记忆和技能都以文件的形式存储在 AgentFS（智能体文件系统）中。资源管理器让你可以直观地浏览和管理这些文件。 ## AgentFS 文件结构概览 @@ -17,6 +21,7 @@ keywords: [AgentFS, 文件系统, 资源管理器, 智能体文件, 文件结构 ├── agent.json # 入口配置 ├── persona.md # 人格设定 ├── principles.md # 行为准则 +├── instructions.md # 可选长期职责、工作策略与交付标准 ├── memory/ # 记忆文件 │ └── *.md # 每条记忆一个文件 ├── skills/ # 技能目录 @@ -60,6 +65,12 @@ DesireCore 的设计理念是"一切皆文件"。文件比数据库更透明— 直接编辑 `agent.json` 等核心配置文件可能影响智能体的正常运行。如果你不确定某个字段的含义，建议通过界面或对话来修改。 ::: +### 编辑长期指令 + +已有 `instructions.md` 可以像其他 Markdown 一样在文件树中打开并编辑，也可以在[提示词中心](./12-prompt-center.md)选择智能体的“长期指令 instructions”。尚未创建文件时，可以通过对话要求保存长期职责，再编辑正文。 + +这份文件不分 L0/L1/L2。保存后的内容在下一次输入、显式继续或恢复被接纳时读取，当前执行轮次保留原快照。详细 SOP 放入技能，个人偏好保留在用户作用范围。完整的全文加载、预算和更新约定见[文件格式说明](../../05-more/06-file-formats.md)。 + ## 上传和管理资源文件 你可以将参考文档、模板、数据文件等上传到智能体的 `resources/` 目录，供智能体在工作时引用。 @@ -84,6 +95,7 @@ DesireCore 的设计理念是"一切皆文件"。文件比数据库更透明— | `agent.json` | JSON | 入口配置：名称、版本、描述、默认模型、环境注入、心跳开关、权限和仓库配置 | | `persona.md` | Markdown | 人格设定：语气、风格、回答策略 | | `principles.md` | Markdown | 行为准则：规则、禁区、优先级 | +| `instructions.md` | 普通 Markdown | 可选的 Agent 专属长期职责、默认工作策略和交付标准，获准时全文加载 | | `memory/_policy.json` | JSON | 记忆压缩与保留策略 | | `memory/*.md` | Markdown | 记忆条目：学到的知识和偏好 | | `skills/*/SKILL.md` | Markdown | 技能文档：技能说明和执行指令 | diff --git a/docs/02-user-guide/06-agents/09-clone-and-sync.md b/docs/02-user-guide/06-agents/09-clone-and-sync.md index 5b975d0..7a50985 100644 --- a/docs/02-user-guide/06-agents/09-clone-and-sync.md +++ b/docs/02-user-guide/06-agents/09-clone-and-sync.md @@ -6,6 +6,10 @@ keywords: [Clone, 克隆智能体, 同步, 冲突解决, Agent Git] # Clone 与同步 +:::info 长期指令的版本支持 +`instructions.md` 已在开发分支的 10.0.179 实现。截至 2026-10-09，最新公开发行版仍为 v10.0.177；正式发行版需要升级到包含这项能力的版本后才能使用。 +::: + Clone 用于基于现有智能体创建一个新副本。它适合做实验、为不同项目准备变体，或把市场智能体调整成自己的版本。 ## 何时需要克隆 @@ -34,6 +38,12 @@ Clone 用于基于现有智能体创建一个新副本。它适合做实验、 核心 DesireCore 智能体（系统调度器）不允许被克隆，以避免破坏主控入口。如果菜单中克隆选项为灰色，说明该智能体受保护。 ::: +### 长期指令跟随智能体本体 + +可选 `instructions.md` 与人格、原则等定义文件一起随智能体克隆、导入导出和版本更新，不属于“私有数据选项”。它应只保存 Agent 自身的长期职责与交付要求；用户、团队或项目专属内容保留在对应作用范围，避免通过共享智能体把这些内容带给其他人。 + +更新前可以查看长期指令的 diff，决定如何合并本地与上游要求。使用这类内容包前，应满足包声明的最低客户端版本。格式与归属见[文件格式说明](../../05-more/06-file-formats.md)。 + ## 私有数据选项 克隆时可以选择是否复制当前用户与该智能体之间的私有数据： @@ -57,7 +67,7 @@ Clone 用于基于现有智能体创建一个新副本。它适合做实验、 4. 点击 **合并更新**，系统执行 Git 合并 :::info 更新策略 -- **纯配置更新**（人格、原则、技能）：查看差异，确认是否需要保留本地调整 +- **定义更新**（人格、原则、长期指令、技能）：查看差异，确认是否需要保留本地调整 - **新增技能/工具**：合并后检查新增内容及依赖要求 - **删除或重命名**：需要手动确认，系统不会静默删除你本地已有的文件 ::: diff --git a/docs/02-user-guide/06-agents/12-prompt-center.md b/docs/02-user-guide/06-agents/12-prompt-center.md index cbce29b..0bb21d2 100644 --- a/docs/02-user-guide/06-agents/12-prompt-center.md +++ b/docs/02-user-guide/06-agents/12-prompt-center.md @@ -1,26 +1,30 @@ --- -title: 提示词中心与三层提示词 -description: 集中管理全局、团队和 Agent 提示词，理解 L0/L1/L2 加载方式并预览最终系统提示词。 -keywords: [提示词中心, 系统提示词, 全局提示词, 团队提示词, Persona, Principles, L0, L1, L2] +title: 提示词中心与内容归属 +description: 管理全局、团队和 Agent 提示词，区分分层提示词与全文长期指令，并预览组合结果。 +keywords: [提示词中心, 系统提示词, 全局提示词, 团队提示词, Persona, Principles, instructions.md, L0, L1, L2] --- -# 提示词中心与三层提示词 +# 提示词中心与内容归属 -提示词中心把分散在用户、团队和智能体目录中的系统提示词放到同一个界面中管理。打开 **资源管理器 → 提示词中心**，左侧选择作用范围，右侧编辑内容或预览组合结果。 +:::info 长期指令的版本支持 +`instructions.md` 已在开发分支的 10.0.179 实现。截至 2026-10-09，最新公开发行版仍为 v10.0.177；正式发行版需要升级到包含这项能力的版本后才能使用。 +::: + +提示词中心把分散在用户、团队和智能体目录中的提示词来源放到同一个界面中管理。打开 **资源管理器 → 提示词中心**，左侧选择作用范围，右侧编辑内容或预览组合结果。 ## 三个作用范围 -| 层 | 影响范围 | 内容 | +| 作用范围 | 影响范围 | 内容 | |---|---|---| -| **全局** | 当前用户的所有智能体 | 通用偏好、工作方式和跨智能体规则 | +| **全局** | 当前用户的所有智能体 | 用户通用偏好、工作方式和跨智能体规则 | | **团队** | 该团队的全部成员和组长；属于多个团队时可出现多段 | 团队协作约定、共享术语和交付标准 | -| **Agent** | 单个智能体 | `persona.md` 人格和 `principles.md` 行为准则 | +| **Agent** | 单个智能体 | `persona.md` 角色与表达、`principles.md` 边界与优先级、可选 `instructions.md` 长期职责与交付要求 | -运行时按 **全局 → 团队 → Agent 人格 → Agent 行为准则** 组合这些可编辑片段，然后加入团队身份、工具、Skill、记忆和会话等运行时上下文。团队提示词不能伪造或改写真实团队身份；成员、组长和同伴关系来自团队配置。 +在支持长期指令的版本中，运行时按 **全局 → 团队 → Agent 人格 → Agent 行为准则 → Agent 长期指令** 组合可编辑片段，再加入团队身份、工具、Skill、记忆和会话等运行时上下文。团队提示词不能伪造或改写真实团队身份；成员、组长和同伴关系来自团队配置。项目规则应保留在项目工作目录的 `AGENTS.md` 等文件中。 -## L0 / L1 / L2 +## 分层文件的 L0 / L1 / L2 -全局和团队编辑器支持表单与 Markdown 源码两种模式。分层文件必须使用严格的二级标题： +全局和团队编辑器支持表单与 Markdown 源码两种模式；人格和原则也支持分层 Markdown。分层时必须使用严格的二级标题： ```md ## L0 @@ -30,87 +34,66 @@ keywords: [提示词中心, 系统提示词, 全局提示词, 团队提示词, P - 每次任务都需要看到的关键要点 ## L2 -较长的背景、示例、例外和操作细节 +较长的背景、示例和例外 ``` | 层级 | 运行时行为 | |---|---| -| **L0** | 始终注入系统提示词 | +| **L0** | 注入系统提示词 | | **L1** | 默认注入系统提示词 | | **L2** | 默认不注入，保留为按需读取的详情 | -L0/L1/L2 表示加载粒度，不是权限或安全等级。保存全局、团队或 Agent 文件不会自动扩大工具权限、文件范围或审批权限。 +L0/L1/L2 表示加载粒度，不是权限或安全等级。分层文件没有可识别的层级标题时，会整份作为一个提示词片段加载；全局和团队编辑器可能提示格式问题。 + +## 长期指令使用普通 Markdown + +`instructions.md` 不使用上述加载层级，不要求或解析 frontmatter。它保存这个 Agent 稳定的职责、默认工作策略和交付标准。正文中写了 `## L2` 也不会按需隐藏这一段：获准加载时，整份正文进入独立提示词片段，不摘要、不截断。全文超出上下文预算时会明确失败；把详细方法、长 SOP 和参考资料放入技能，而不是为长期指令编写摘要层。 -如果源码没有识别到分层标题，DesireCore 会把整份文件作为一个提示词片段注入，并在校验或保存时给出格式提示。 +保存后的内容在新的输入、显式继续或恢复被接纳时刷新；同一执行轮次保持快照。普通心跳全文加载，`lightContext=true` 的轻量心跳跳过它。完整格式和工具更新约定见[文件格式说明](../../05-more/06-file-formats.md)。 ## 编辑和预览 1. 选择“全局提示词”、某个团队，或展开某个智能体 -2. 在表单模式填写 L0/L1/L2，或在源码模式编辑完整 Markdown +2. 分层文件按其编辑器填写 L0/L1/L2 或 Markdown；Agent 的“长期指令 instructions”直接编辑完整 Markdown 3. 保存内容 4. 对 Agent 选择“提示词预览”，按全局、团队、Agent 和系统分组检查组合结果 -预览会显示片段来源和字符数，适合发现重复、冲突和过长内容。预览反映查询时可加载的静态上下文；实际请求还可能动态加入 inbox、handoff、语音、工具或最新团队状态，因此排查线上请求时应以接口审计记录的系统提示词摘要为最终依据。 +预览会显示片段来源和字符数，适合发现重复、冲突和过长内容。预览反映查询时可加载的静态上下文；实际请求还可能动态加入 inbox、handoff、语音、工具或最新团队状态，因此排查实际请求时应以接口审计记录为最终依据。长期指令只是动态系统提示词的一个来源，不保存或替换完整 `systemPrompt`。 ## 写作建议 -- 全局层只写所有智能体都适用的规则 -- 团队层写协作和交付约定，不重复成员身份 -- Agent 层保留角色特有的人格和边界 -- 把短小、常用内容放在 L0/L1，把长解释和示例放在 L2 -- 不要依靠提示词替代工具权限、审批策略或代码级安全限制 +- 全局只写用户对所有智能体的通用要求，团队写协作约定；个人和项目内容不要复制到可共享的 Agent 本体 +- 人格写角色和表达方式，原则写边界和优先级，长期指令写稳定职责、默认策略和交付标准 +- 分层文件把每次需要的内容放在 L0/L1；长期指令全文加载，详细方法转到技能和参考资料 +- 不要依靠提示词替代工具权限和审批策略 ## 实战示例 -以下是一个三层提示词的配合示例，展示如何避免重复和冲突： - -**全局提示词**（适用于所有智能体）： - -```md -## L0 -用户偏好中文回复，技术术语保留英文原文。 - -## L1 -- 输出格式优先使用 Markdown 表格和列表 -- 代码块标注语言类型 -``` - -**团队提示词**（仅团队成员可见）： - -```md -## L0 -文档团队：统一使用 Docusaurus 格式，图片放 static/img/ 对应章节目录。 - -## L1 -- 提交前运行 npm run build 确认无断链 -- 配图使用 SVG 格式，支持暗色模式 -``` - -**Agent 人格**（单个智能体独有）： - -```md -## L0 -技术文档工程师，专注于 API 参考和用户指南。 - -## L1 -- 写作风格：简洁、准确、面向开发者 -- 每个操作步骤配一个可复制的代码示例 -``` +例如，文档工程师可以按归属保存以下内容，避免把每项要求都塞进人格： -运行时，这三层按顺序拼接，智能体同时知道用户偏好（全局）、团队规范（团队）和自身角色（Agent）。 +| 归属 | 示例 | +|------|------| +| 用户全局提示词 | 用户偏好中文回复，技术术语保留英文原文 | +| 团队提示词 | 文档团队采用统一术语和文档格式 | +| `persona.md` | 技术文档工程师，表达简洁、准确，面向开发者 | +| `principles.md` | 不把未验证的能力写成已实现；不编造来源 | +| `instructions.md` | 交付可操作的说明、必要示例与验证结果；标明已验证和待确认的边界 | +| 技能与参考资料 | 构建、断链检查、图片目录和发布流程的详细步骤 | ## 常见问题 | 问题 | 原因与解决 | |------|-----------| -| 保存后智能体行为没变化 | L2 内容默认不注入运行时；确认关键规则在 L0/L1 中 | -| 预览中看到重复内容 | 全局和 Agent 层写了相似规则；精简其中一层 | -| 团队提示词不生效 | 确认智能体已加入该团队；多团队时检查是否选对了团队 | -| 源码模式提示"格式错误" | 检查二级标题是否严格为 `## L0`、`## L1`、`## L2`（注意空格） | -| 字符数过长导致截断 | 把详细内容移到 L2，L0/L1 只保留摘要 | +| 分层文件保存后关键内容没生效 | L2 默认不注入；确认每次需要的规则在 L0/L1 中 | +| 长期指令保存后当前任务仍使用旧内容 | 当前执行轮次保留快照，在新的输入、显式继续或恢复接纳时读取新内容 | +| 预览中看到重复内容 | 同一要求写到了多个作用范围；保留在真正归属的位置 | +| 团队提示词不生效 | 确认智能体已加入该团队；多团队时检查对应来源 | +| 分层源码提示格式问题 | 检查标题是否严格为 `## L0`、`## L1`、`## L2`；长期指令无需这些标题 | +| 找不到长期指令入口 | 检查客户端是否已包含 10.0.179 开发分支中的长期指令能力 | +| 长期指令超出预算 | 精简正文，把详细步骤移到技能；它不会通过截断或 L2 隐藏来继续执行 | :::caution 提示词 ≠ 权限 -修改提示词不会改变智能体的工具权限、文件访问范围或审批策略。如需调整安全边界，请在 **资源管理器 → 智能体设置 → 权限** 中操作。 +修改提示词不会改变智能体的工具权限、文件访问范围或审批策略。如需调整权限，请使用相应权限设置。 ::: ## 下一步 diff --git a/docs/04-concepts/03-agentfs.md b/docs/04-concepts/03-agentfs.md index d82ac82..be4eb3a 100644 --- a/docs/04-concepts/03-agentfs.md +++ b/docs/04-concepts/03-agentfs.md @@ -6,6 +6,10 @@ keywords: [AgentFS, 文件系统, 数据存储, Git, 智能体仓库] # AgentFS 文件系统 +:::info 长期指令的版本支持 +`instructions.md` 已在开发分支的 10.0.179 实现。截至 2026-10-09，最新公开发行版仍为 v10.0.177；正式发行版需要升级到包含这项能力的版本后才能使用。 +::: + ## AgentFS 就像每个智能体的"家" 如果把 DesireCore 比作一个社区，那么 AgentFS 就是每个智能体在这个社区中的"家"。这个家里有它的个人档案、工作手册、技能证书、记忆日志，还有每次工作的回执存档。 @@ -37,6 +41,7 @@ AgentFS 的设计灵感来源于 Linux 操作系统的文件结构： │ ├── agent.json # 身份证：基本信息和配置 │ ├── persona.md # 性格档案：沟通风格、决策偏好 │ ├── principles.md # 行为准则：规则、禁区、底线 +│ ├── instructions.md # 可选长期指令：职责、策略、交付标准 │ ├── memory/ # 记忆库：它记住的事实和经验 │ ├── skills/ # 技能包：它学会的各种技能 │ ├── workflows/ # 工作流：复杂任务的执行计划 @@ -72,6 +77,7 @@ AgentFS 的设计灵感来源于 Linux 操作系统的文件结构： | `agent.json` | 智能体的基本信息、版本号 | 身份证 | | `persona.md` | 性格、语气、决策偏好 | 性格特征 | | `principles.md` | 行为准则、红线、底线 | 职业操守 | +| `instructions.md` | 可选的长期职责、工作策略和交付标准 | 工作约定 | | `memory/` | 积累的知识和经验 | 长期记忆 | | `skills/` | 学会的各种技能 | 技能证书 | | `tools/` | 能使用的外部工具 | 工具箱 | @@ -99,7 +105,7 @@ AgentFS 的设计灵感来源于 Linux 操作系统的文件结构： ### 1. 智能体可以"自己改自己" -因为一切都是文件，智能体可以直接读写自己的文件来学习和进化。比如，当你教它一条新规则时，它会把规则写入 `principles.md`。这比通过 API 操作数据库要简单得多。 +因为一切都是文件，智能体可以直接读写自己的文件来学习和进化。比如，行为边界归入 `principles.md`，Agent 专属的长期职责归入 `instructions.md`，详细方法归入技能；个人偏好保留在用户作用范围。这比通过 API 操作数据库要简单得多。 ### 2. 人类可以轻松审阅 @@ -115,7 +121,7 @@ AgentFS 的设计灵感来源于 Linux 操作系统的文件结构： ## 分层加载 -为了节省 AI 模型的 token 消耗，AgentFS 采用三级加载策略： +人格、原则及全局、团队分层提示词可以用 L0/L1/L2 控制加载粒度，技能等内容也支持按需发现。不是所有 AgentFS 文件都按三级加载： | 层级 | 内容 | 消耗 | 用途 | |------|------|------|------| @@ -123,7 +129,7 @@ AgentFS 的设计灵感来源于 Linux 操作系统的文件结构： | **L1** | 核心信息 + 适用场景 | 较少 | 规划和决策 | | **L2** | 完整内容 | 按需 | 实际执行 | -这意味着智能体不需要每次都读取所有文件，而是按需加载，既节省成本又提高效率。 +`instructions.md` 使用普通 Markdown，不解析 L0/L1/L2，获准加载时全文进入上下文，不摘要或截断；详细步骤应放入技能。完整归属与更新约定见[长期指令格式](../05-more/06-file-formats.md)。 ## 下一步 diff --git a/docs/04-concepts/06-self-evolution.md b/docs/04-concepts/06-self-evolution.md index d10c878..049d82d 100644 --- a/docs/04-concepts/06-self-evolution.md +++ b/docs/04-concepts/06-self-evolution.md @@ -6,6 +6,10 @@ keywords: [自我进化, Self-Evolution, 学习, 记忆, 经验积累] # 自我进化 +:::info 长期指令的版本支持 +`instructions.md` 已在开发分支的 10.0.179 实现。截至 2026-10-09，最新公开发行版仍为 v10.0.177；正式发行版需要升级到包含这项能力的版本后才能使用。 +::: + ## 智能体不是静态的 大多数 AI 产品是"静态"的 -- 你用了 100 次和用了 1 次，它的能力完全一样。每次对话都像第一次见面。 @@ -26,7 +30,7 @@ DesireCore 的智能体是**动态进化**的。它会在与你的每次互动 - "以后帮我写周报，按照这个格式：先写本周完成，再写下周计划，最后写遇到的问题" - "审查合同时，如果发现知识产权归属不清，必须标红警告" -**产出物**：同伴生成一个规则/技能的修改提案（diff），你确认后生效。 +**产出物**：同伴生成一个规则/技能的修改提案（diff），你确认后生效。内容按归属保存：角色与表达在人格，边界与优先级在原则，Agent 专属的长期职责与交付要求在可选 `instructions.md`，详细方法在技能。个人偏好仍保留在用户作用范围。见[文件格式说明](../05-more/06-file-formats.md)。 ### 第二层：经验积累（互动中学的） @@ -65,13 +69,11 @@ DesireCore 的智能体是**动态进化**的。它会在与你的每次互动 自由进化听起来很美好，但如果不加限制，可能导致同伴"人格漂移"或"记忆污染"。因此，DesireCore 设置了严格的进化治理机制。 -### 不可触碰的底线 +### 内容修改与权限边界 -以下内容**不可**被自动进化覆盖： +`persona.md`、`principles.md` 和 `instructions.md` 都是可编辑的内容文件。修改角色、边界或长期职责时，应审阅具体 diff，并遵循现有工具权限与审批策略；不能把文件中的某个标题当作不可修改的系统权限等级。 -- **核心人格**（`persona.md` 的核心部分）：同伴的基本性格不会因为进化而改变 -- **安全红线**（`principles.md` 中的"绝不做"）：绝对禁止的行为不会被放松 -- **权限配置**：权限等级不会被自动提升 +内容变化不会自动提升权限，也不会绕过审批。修改长期指令后，新内容在新的输入、显式继续或恢复被接纳时读取；同一执行轮次保留原快照。 ### 变更可审阅 diff --git a/docs/05-more/03-glossary.md b/docs/05-more/03-glossary.md index 26e2d8d..d9dab2b 100644 --- a/docs/05-more/03-glossary.md +++ b/docs/05-more/03-glossary.md @@ -95,6 +95,11 @@ DesireCore 的核心交互范式。不是"我问你答"，而是"我教你做" ### Human Gate（人闸门） 三种步骤类型之一。需要用户亲自确认的步骤。执行到此步骤时自动暂停，等待用户明确指示后才继续。 +## I + +### Instructions（长期指令） +智能体根目录下的可选 `instructions.md`，保存 Agent 专属的长期职责、默认工作策略和交付标准。使用普通 Markdown，获准加载时全文进入上下文，不解析 L0/L1/L2、不摘要或截断，也不授予权限。开发版本 10.0.179 已实现；截至 2026-10-09，公开发行版 v10.0.177 尚未包含该能力。详见[文件格式说明](./06-file-formats.md)。 + ## M ### MCP（Model Context Protocol） @@ -103,7 +108,7 @@ DesireCore 的核心交互范式。不是"我问你答"，而是"我教你做" ## P ### Persona（人格档案） -智能体的性格定义文件（`persona.md`）。包含沟通风格、决策偏好、输出规范等，是智能体"像谁"的核心定义。不是"人设文案"，而是可执行的行为规范。 +智能体的角色与表达定义文件（`persona.md`），包含沟通风格、语气和回答组织方式。稳定职责与交付标准归入 `instructions.md`，边界与优先级归入 `principles.md`。 ### Plan（立） 六原语之一。智能体在当前工作目录维护可版本化计划，记录目标、约束、步骤、风险和验证方式。Plan 通过自然对话修订，不是模式或执行授权。 diff --git a/docs/05-more/06-file-formats.md b/docs/05-more/06-file-formats.md index 6d8d1d6..6f70448 100644 --- a/docs/05-more/06-file-formats.md +++ b/docs/05-more/06-file-formats.md @@ -1,11 +1,15 @@ --- title: 文件格式说明 description: AgentFS 中各文件的格式规范和结构说明 -keywords: [文件格式, AgentFS, agent.json, SKILL.md, 记忆, 准则] +keywords: [文件格式, AgentFS, agent.json, instructions.md, SKILL.md, 记忆, 准则] --- # 文件格式说明 +:::info 长期指令的版本支持 +`instructions.md` 已在开发分支的 10.0.179 实现。截至 2026-10-09，最新公开发行版仍为 v10.0.177；正式发行版需要升级到包含这项能力的版本后才能使用。 +::: + AgentFS 把智能体的身份、行为、记忆、技能和运行策略保存为普通文件。你可以通过界面编辑，也可以在了解字段含义后直接修改文件。 ## 读取与导出格式矩阵 @@ -132,15 +136,11 @@ PDF 读取会根据文件大小和内容选择策略：文字页优先文本提 - 模板腔或过度共情 - 没有结论的泛泛分析 -## 安全与确认 -- 读文件、整理、生成草稿、做分析：可以直接做，并写回执。 -- 发消息/邮件、删除/付费、线上变更、对外发布：必须先过人闸门确认。 - ## 不确定时 - 说明不确定点，并给验证路径；必要时升级给人。 ``` -`persona.md` 是可执行沟通规范，不是“人设文案”。建议写得短、硬、可测试，让智能体能稳定遵守。 +`persona.md` 保存角色、表达风格和沟通方式。安全边界与确认规则放在 `principles.md`，稳定职责与交付要求放在 `instructions.md`，避免同一条要求在多个文件重复维护。 ## principles.md -- 行为准则 @@ -163,6 +163,39 @@ PDF 读取会根据文件大小和内容选择策略：文字页优先文本提 `绝不做` 和安全红线通常应保持简洁明确。这类约束会影响智能体的长期行为，不应该写成模糊建议。 +## instructions.md -- Agent 专属长期指令 + +`instructions.md` 是智能体根目录下的可选文件，保存长期职责、默认工作策略和交付标准。例如，同一个法律顾问在每次审阅中都要交付哪些内容： + +```markdown +# 合同审阅职责 + +审阅合同前，先明确交易目的、合同版本和重点条款。 + +交付包含风险摘要、逐条意见、建议修改和待用户决定的问题。 +每项意见附原文位置；缺少依据时说明不确定点，不编造条款或事实。 +``` + +### 内容放在哪里 + +| 内容 | 归属 | +|------|------| +| 角色定位、语气和表达风格 | `persona.md` | +| 行为边界、禁区和优先级 | `principles.md` | +| 这个 Agent 的长期职责、默认工作策略和交付标准 | `instructions.md` | +| 详细操作步骤、较长 SOP、模板和参考资料 | `skills/*/SKILL.md` 及其 `references/` | +| 用户偏好、团队约定和项目规则 | 相应作用范围的 `prompt.md`、`rules.md` 或 `AGENTS.md`；不要复制到可共享的 Agent 本体 | + +### 文件与更新约定 + +- 使用普通 UTF-8 Markdown，不要求 frontmatter，也不解析 frontmatter 或 L0/L1/L2。即使写了 `## L2`，其中内容仍属于要完整读取的正文。 +- 当该来源被当前运行上下文允许加载时，非空正文全文进入独立提示词片段，不自动摘要或截断。全文装不进上下文预算时，会明确失败；应精简长期指令，把详细方法移到技能。 +- 保存后的内容在新的输入、显式继续或恢复被接纳时重新读取；同一执行轮次的工具循环、重试和备用模型沿用已接纳的快照，避免半途替换要求。 +- 普通心跳也读取长期指令全文；使用 `lightContext=true` 的轻量心跳跳过它。 +- `ManageAgent` 的 `instructions` 参数是字符串：省略表示保留已有文件，传入字符串表示整份替换，空字符串表示清空。创建时省略不会要求生成该文件；正文不能含 NUL 字符。 + +这份文件是动态系统提示词的一个来源，不保存或替换完整 `systemPrompt`。编辑它不会授予工具权限、改变文件访问范围或绕过审批。编辑入口见[文件资源管理器](../02-user-guide/06-agents/06-agent-files.md)和[提示词中心](../02-user-guide/06-agents/12-prompt-center.md)。 + ## SKILL.md -- 技能定义 每个技能包至少包含一个 `SKILL.md`。frontmatter 可使用根级字段，也可使用 `metadata` 包裹字段。 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/03-create-agent.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/03-create-agent.md index 751de66..ecf630d 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/03-create-agent.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/03-create-agent.md @@ -6,6 +6,10 @@ keywords: [Create Agent, Custom Agent, Conversation Creation, Template] # Create Custom Agent +:::info Standing instructions version support +`instructions.md` is implemented in development version 10.0.179. As of 2026-10-09, the latest public release is still v10.0.177. Release users need a version that includes this capability before using it. +::: + When there is no Agent in the marketplace that meets your needs, you can create a fully custom Agent. DesireCore provides two creation methods. ## Create Through Conversation (Recommended) @@ -24,6 +28,7 @@ The simplest way is to directly tell the DesireCore Core Agent what kind of assi - **Role Positioning**: Professional domain and behavioral style - **Skill Requirements**: What capabilities are needed - **Behavioral Guidelines**: What should or shouldn't be done + - **Standing Instructions** (optional): Stable responsibilities, default work strategies, and expected deliverables 4. After confirmation, the Core Agent automatically creates the complete Agent configuration 5. The new Agent appears in your Agent list and can be used immediately @@ -47,8 +52,7 @@ If you are familiar with the AgentFS file system structure, you can directly cre 3. Configure Persona (`persona.md`): - Role positioning and tone style - - Response strategy and confirmation strategy - - Forbidden zones and boundaries + - Expression preferences and answer structure 4. Configure Principles (`principles.md`): - Core principles @@ -59,6 +63,14 @@ If you are familiar with the AgentFS file system structure, you can directly cre - Install from skill marketplace - Or manually write SKILL.md +### Add Standing Instructions (Optional) + +You can describe stable responsibilities during conversational creation or add them afterward. For example: + +> “Save standing instructions for this financial assistant: check the data period and definitions before each analysis, and deliver conclusions, key metrics, calculation evidence, and open questions. Keep detailed analysis procedures in a skill.” + +The content is stored in `instructions.md`. Edit it after creation through [File Explorer](./06-agent-files.md) or [Prompt Center](./12-prompt-center.md). It does not require L0/L1/L2 headings. Keep role and style in persona, boundaries in principles, and user, team, or project conventions in their own scopes. See [File Format Reference](../../05-more/06-file-formats.md) for the full contract. + ### AgentFS Directory Structure After creation, the Agent's files are stored in `~/.desirecore/agents//`: @@ -68,6 +80,7 @@ After creation, the Agent's files are stored in `~/.desirecore/agents/ ├── agent.json # Entry configuration (name, description, version, etc.) ├── persona.md # Persona ├── principles.md # Principles +├── instructions.md # Optional stable responsibilities, work strategies, and delivery standards ├── memory/ # Memory directory ├── skills/ # Skills directory ├── tools/ # Tool registration diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/04-edit-persona.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/04-edit-persona.md index 027fab8..945a60e 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/04-edit-persona.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/04-edit-persona.md @@ -6,6 +6,10 @@ keywords: [Persona, Role Positioning, Personality Traits, Agent Configuration] # Edit Persona +:::info Standing instructions version support +`instructions.md` is implemented in development version 10.0.179. As of 2026-10-09, the latest public release is still v10.0.177. Release users need a version that includes this capability before using it. +::: + Persona defines "who" the Agent is—its tone, style, professional domain, and behavior. This is not a character description, but an **executable behavioral specification**. ## What is Persona @@ -16,14 +20,13 @@ Persona is saved in the `persona.md` file in the Agent directory. It tells the A |---|---|---| | **Response Strategy** | How to answer questions | "Give conclusion first, then reasons; less formalities" | | **Tone Style** | What tone to use | "Professional but not rigid, concise but not perfunctory" | -| **Confirmation Strategy** | When to ask the user | "Must confirm before sending messages, deleting, or paid operations" | | **Forbidden Zones** | What not to do | "Don't use template clichés, don't avoid giving conclusions" | | **Uncertainty Handling** | What to do when unsure | "Explain uncertainty and provide verification path" | -`persona.md` is part of the **Agent prompt layer**. At runtime, DesireCore also combines the current user's global prompt and prompts from every team the Agent belongs to. Open **Explorer -> Prompt Center** to edit these sources together and preview the result. See [Prompt Center and Prompt Layers](./12-prompt-center.md). +`persona.md` is part of the **Agent prompt layer**. At runtime, DesireCore also combines the current user's global prompt and prompts from every team the Agent belongs to. Open **Explorer -> Prompt Center** to edit these sources together and preview the result. See [Prompt Center and Content Ownership](./12-prompt-center.md). -:::info Persona vs. Principles -**Persona** defines "how to do it"—tone, style, response methods. **Principles** define "what to do and not do"—rules, boundaries, priorities. They complement each other without overlapping. +:::info Persona, Principles, and Standing Instructions +**Persona** defines role and expression style. **Principles** defines boundaries, prohibited actions, and priorities. Optional **`instructions.md`** stores agent-specific stable responsibilities, default work strategies, and delivery standards. Keep user preferences, team conventions, and project rules in their own scopes, and detailed methods in skills. See [File Format Reference](../../05-more/06-file-formats.md). ::: ## Editing Name, Avatar, Description @@ -103,5 +106,5 @@ The Agent will record your preferences and apply them in subsequent conversation ## Next Steps - [Edit Principles](./05-edit-principles.md) — Set behavioral boundaries for the Agent -- [Prompt Center and Prompt Layers](./12-prompt-center.md) — Manage global, team, and Agent prompts +- [Prompt Center and Content Ownership](./12-prompt-center.md) — Manage global, team, and Agent prompts - [Create Custom Agent](./03-create-agent.md) — Review the creation process diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/05-edit-principles.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/05-edit-principles.md index 5906e98..982931b 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/05-edit-principles.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/05-edit-principles.md @@ -6,6 +6,10 @@ keywords: [Principles, L0, L1, L2, Safety Rules, Priority] # Edit Principles +:::info Standing instructions version support +`instructions.md` is implemented in development version 10.0.179. As of 2026-10-09, the latest public release is still v10.0.177. Release users need a version that includes this capability before using it. +::: + Principles are the Agent's "behavior manual"—they specify the rules the Agent must follow, the red lines it must not cross, and the priority order when making decisions. ## What are Principles @@ -44,9 +48,9 @@ L1 contains the key points the Agent should see while doing normal work. It is i L2 contains longer explanations, exceptions, examples, and operating detail. It is not injected by default and can be read on demand: -- Output format preferences (Markdown / plain text) -- Answer detail level (concise / detailed) -- Specific domain work habits +- Explanations and decision examples for a boundary +- Exceptions and their confirmation requirements +- Priorities when rules conflict | Level | Default Loading | Recommended Content | Editable | |---|---|---|---| @@ -83,7 +87,9 @@ Advanced users can edit the Agent's `principles.md` under the DesireCore data di ## Relationship to Other Prompt Layers -At runtime, DesireCore combines editable prompts in this order: **global -> team -> Agent persona -> Agent principles**, then adds team identity, tools, memory, and other system context. L0/L1/L2 controls how much of each file is loaded; global/team/Agent controls its scope. Avoid contradictory rules across layers, and use Prompt Preview to inspect the final combination. +In a version supporting standing instructions, editable sections are combined in this order: **global → team → agent persona → agent principles → agent standing instructions**, then runtime context such as team identity, tools, and memory is added. L0/L1/L2 controls layered files only. `instructions.md` is ordinary Markdown and loads in full when allowed. + +Keep boundaries and priorities in principles, stable responsibilities and delivery requirements in standing instructions, and role and expression in persona. User, team, and project requirements remain in their own scopes; detailed SOPs belong in skills. See [File Format Reference](../../05-more/06-file-formats.md), and use Prompt Preview to check duplication and conflicts. :::tip Principle Writing Suggestions - **Specific beats vague**: "Must confirm before operations involving amounts over 1000 yuan" is better than "Confirm for large amounts" @@ -95,4 +101,4 @@ At runtime, DesireCore combines editable prompts in this order: **global -> team - [File Explorer](./06-agent-files.md) — Browse the Agent's file structure - [Edit Persona](./04-edit-persona.md) — Adjust the Agent's tone and style -- [Prompt Center and Prompt Layers](./12-prompt-center.md) — Understand global, team, and Agent prompt composition +- [Prompt Center and Content Ownership](./12-prompt-center.md) — Understand global, team, and Agent prompt composition diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/06-agent-files.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/06-agent-files.md index 3e09d23..87334ce 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/06-agent-files.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/06-agent-files.md @@ -6,6 +6,10 @@ keywords: [AgentFS, File System, File Explorer, Agent Files, File Structure] # File Explorer +:::info Standing instructions version support +`instructions.md` is implemented in development version 10.0.179. As of 2026-10-09, the latest public release is still v10.0.177. Release users need a version that includes this capability before using it. +::: + Each Agent's configuration, memory, and skills are stored as files in AgentFS (Agent File System). The file explorer lets you intuitively browse and manage these files. ## AgentFS File Structure Overview @@ -17,6 +21,7 @@ Each Agent's files are stored in the `~/.desirecore/agents//` director +-- agent.json # Entry configuration +-- persona.md # Persona +-- principles.md # Principles ++-- instructions.md # Optional stable responsibilities, strategies, and delivery standards +-- memory/ # Memory files | +-- *.md # One file per memory +-- skills/ # Skills directory @@ -59,6 +64,12 @@ For Markdown and configuration files, you can edit directly in the preview inter Directly editing core configuration files like `agent.json` may affect the Agent's normal operation. If you're unsure about the meaning of a field, it's recommended to modify through the interface or conversation. ::: +### Edit Standing Instructions + +Open an existing `instructions.md` in the file tree and edit it like other Markdown files, or select the agent's **Standing Instructions** in [Prompt Center](./12-prompt-center.md). If the file does not exist yet, ask the agent through conversation to save its stable responsibilities, then edit the body. + +This file has no L0/L1/L2 loading tiers. Saved changes are read when the next input, explicit continuation, or restoration is accepted; the current execution turn keeps its original snapshot. Put detailed SOPs in skills and personal preferences in the user scope. See [File Format Reference](../../05-more/06-file-formats.md) for full-body loading, budget, and update behavior. + ## Uploading and Managing Resource Files You can upload reference documents, templates, data files, etc. to the Agent's `resources/` directory for the Agent to reference during work. @@ -83,6 +94,7 @@ You can upload reference documents, templates, data files, etc. to the Agent's ` | `agent.json` | JSON | Entry configuration: name, version, description, default model, environment injection, heartbeat switch, permissions, and repository settings | | `persona.md` | Markdown | Persona: tone, style, response strategy | | `principles.md` | Markdown | Principles: rules, forbidden zones, priorities | +| `instructions.md` | Ordinary Markdown | Optional agent-specific stable responsibilities, default work strategies, and delivery standards; loaded in full when allowed | | `memory/_policy.json` | JSON | Memory compression and retention policy | | `memory/*.md` | Markdown | Memory entries: learned knowledge and preferences | | `skills/*/SKILL.md` | Markdown | Skill documentation: skill description and execution instructions | diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/09-clone-and-sync.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/09-clone-and-sync.md index c34b6bb..77da17e 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/09-clone-and-sync.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/09-clone-and-sync.md @@ -6,6 +6,10 @@ keywords: [Clone, agent clone, sync, conflicts, Agent Git] # Clone and Sync +:::info Standing instructions version support +`instructions.md` is implemented in development version 10.0.179. As of 2026-10-09, the latest public release is still v10.0.177. Release users need a version that includes this capability before using it. +::: + Clone creates a new copy based on an existing agent. It is useful for experiments, preparing variants for different projects, or customizing a marketplace agent into your own version. ## When to Clone @@ -34,6 +38,12 @@ Clone creates a new copy based on an existing agent. It is useful for experiment The core DesireCore agent (the system scheduler) cannot be cloned, to avoid breaking the main control entry. If the clone option is greyed out in the menu, the agent is protected. ::: +### Standing Instructions Travel with the Agent Body + +Optional `instructions.md` is cloned, imported, exported, and versioned with definition files such as persona and principles. It is not a private-data option. Keep only the agent's own stable responsibilities and delivery requirements in it. User, team, and project content should stay in the relevant scope to avoid sharing it with the agent body. + +Review the standing-instructions diff before updating, and decide how to merge local and upstream requirements. Meet the content package's minimum client version before using it. See [File Format Reference](../../05-more/06-file-formats.md) for format and ownership. + ## Private Data Options When cloning, you can choose whether to copy private data between the current user and that agent: @@ -57,7 +67,7 @@ If a cloned agent still retains its remote source (i.e., you chose "Keep Remote" 4. Click **Merge Updates** — the system performs a Git merge :::info Update Strategy -- **Pure config updates** (persona, principles, skills): review the differences and decide which local adjustments to retain +- **Definition updates** (persona, principles, standing instructions, skills): review the differences and decide which local adjustments to retain - **New skills/tools**: check the added content and dependency requirements after merging - **Deletions or renames**: require manual confirmation; the system will not silently delete files you already have locally ::: diff --git a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/12-prompt-center.md b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/12-prompt-center.md index ff71e3a..a2bd463 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/12-prompt-center.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/02-user-guide/06-agents/12-prompt-center.md @@ -1,26 +1,30 @@ --- -title: Prompt Center and Prompt Layers -description: Manage global, team, and Agent prompts, understand L0/L1/L2 loading, and preview the combined system prompt. -keywords: [Prompt Center, system prompt, global prompt, team prompt, Persona, Principles, L0, L1, L2] +title: Prompt Center and Content Ownership +description: Manage global, team, and agent prompts, distinguish layered prompts from full-body standing instructions, and preview their composition. +keywords: [Prompt Center, system prompt, global prompt, team prompt, Persona, Principles, instructions.md, L0, L1, L2] --- -# Prompt Center and Prompt Layers +# Prompt Center and Content Ownership -Prompt Center brings prompts stored across the user, team, and Agent directories into one management surface. Open **Explorer -> Prompt Center**, select a scope on the left, and edit or preview it on the right. +:::info Standing instructions version support +`instructions.md` is implemented in development version 10.0.179. As of 2026-10-09, the latest public release is still v10.0.177. Release users need a version that includes this capability before using it. +::: + +Prompt Center brings prompt sources stored across user, team, and agent directories into one management surface. Open **Explorer → Prompt Center**, select a scope on the left, and edit or preview it on the right. ## Three Scopes -| Layer | Scope | Content | +| Scope | Applies To | Content | |---|---|---| -| **Global** | All Agents owned by the current user | General preferences, working style, and cross-Agent rules | -| **Team** | Every member and supervisor of the team; multiple memberships can produce multiple sections | Collaboration rules, shared terminology, and delivery standards | -| **Agent** | One Agent | `persona.md` and `principles.md` | +| **Global** | All agents owned by the current user | User preferences, working style, and cross-agent rules | +| **Team** | Every member and supervisor; multiple memberships can produce multiple sections | Collaboration rules, shared terminology, and delivery standards | +| **Agent** | One agent | `persona.md` for role and expression, `principles.md` for boundaries and priorities, and optional `instructions.md` for stable responsibilities and delivery requirements | -At runtime, DesireCore combines editable sections in this order: **global -> team -> Agent persona -> Agent principles**, then adds team identity, tools, skills, memory, conversation, and other runtime context. A team prompt cannot forge or replace real team identity; membership, supervisor, and peer relationships come from team configuration. +In a version supporting standing instructions, editable sections are combined in this order: **global → team → agent persona → agent principles → agent standing instructions**. Runtime context such as team identity, tools, skills, memory, and conversation is then added. A team prompt cannot forge or replace real team identity; membership and relationships come from team configuration. Keep project rules in files such as `AGENTS.md` in the project working directory. -## L0 / L1 / L2 +## L0 / L1 / L2 in Layered Files -The global and team editors support both form and Markdown source modes. A layered file must use exact second-level headings: +Global and team editors support form and Markdown source modes. Persona and principles also support layered Markdown. Layered content must use exact second-level headings: ```md ## L0 @@ -30,35 +34,67 @@ One-sentence core summary - Key points needed in every normal run ## L2 -Longer background, examples, exceptions, and operating detail +Longer background, examples, and exceptions ``` | Level | Runtime Behavior | |---|---| -| **L0** | Always injected into the system prompt | +| **L0** | Injected into the system prompt | | **L1** | Injected by default | -| **L2** | Not injected by default; retained for on-demand reading | +| **L2** | Not injected by default; available for on-demand reading | + +L0/L1/L2 describes loading granularity, not permission or safety levels. A layered file without recognized headings is loaded as one complete prompt section. Global and team editors may report a format warning. + +## Standing Instructions Use Ordinary Markdown -L0/L1/L2 describes loading granularity, not permission or safety levels. Saving a global, team, or Agent file does not expand tool permissions, file scope, or approval authority. +`instructions.md` does not use these loading tiers and does not require or parse frontmatter. It stores this agent's stable responsibilities, default work strategies, and delivery standards. Even content under `## L2` is part of the body: when the source is allowed, the entire body is loaded as a separate section without summarization or truncation. If it exceeds the context budget, the operation fails explicitly. Put detailed methods, long SOPs, and reference material in skills instead of creating summary tiers for standing instructions. -If no layer headings are recognized in source mode, DesireCore injects the whole file as one prompt section and reports a format warning during validation or save. +Saved changes are reread when new input, explicit continuation, or restoration is accepted. The same execution turn keeps its snapshot. Normal heartbeats load the full body; lightweight heartbeats with `lightContext=true` skip it. See [File Format Reference](../../05-more/06-file-formats.md) for the full format and tool update contract. ## Edit and Preview -1. Select **Global Prompt**, a team, or expand an Agent. -2. Fill L0/L1/L2 in form mode, or edit the full Markdown in source mode. +1. Select **Global Prompt**, a team, or expand an agent. +2. Use the relevant editor for L0/L1/L2 or Markdown in layered files. For the agent's **Standing Instructions**, edit the complete Markdown body. 3. Save the content. -4. For an Agent, select **Prompt Preview** and inspect the global, team, Agent, and system groups. +4. Select the agent's **Prompt Preview** to inspect global, team, agent, and system groups. -Preview shows section sources and character counts, making duplicated, conflicting, or oversized content easier to spot. It represents the static context available at query time. A live request may also add inbox, handoff, voice, tools, or newer team state, so use the system-prompt summary in Interface Audit as the final reference for live diagnosis. +Preview shows sources and character counts so you can spot duplication, conflicts, and oversized content. It represents static context available at query time. A live request may add inbox, handoff, voice, tools, or newer team state, so use Interface Audit records when diagnosing the actual request. Standing instructions are one source for the dynamic system prompt; they do not store or replace the complete `systemPrompt`. ## Writing Guidance -- Put only rules that apply to every Agent in the global layer. -- Put collaboration and delivery conventions in the team layer; do not duplicate membership identity. -- Keep role-specific personality and boundaries in the Agent layer. -- Put short, frequently needed content in L0/L1 and long explanations or examples in L2. -- Do not use prompt text as a substitute for permissions, approval policies, or code-level safety controls. +- Put the user's general requirements in the global scope and collaboration conventions in the team scope. Keep personal and project content out of the shareable agent body. +- Put role and expression in persona, boundaries and priorities in principles, and stable responsibilities, default strategies, and delivery standards in standing instructions. +- In layered files, keep content needed on every run in L0/L1. Standing instructions load in full; detailed methods belong in skills and reference material. +- Do not use prompt text as a substitute for permissions or approval policies. + +## Example + +A documentation engineer can keep each requirement in its own scope instead of putting everything in persona: + +| Location | Example | +|----------|---------| +| User global prompt | The user prefers Chinese replies with technical terms in their original English form. | +| Team prompt | The documentation team uses shared terminology and document formats. | +| `persona.md` | A technical documentation engineer who writes concisely and accurately for developers. | +| `principles.md` | Do not describe unverified capabilities as implemented or invent sources. | +| `instructions.md` | Deliver actionable explanations, necessary examples, and validation results. Identify verified and unresolved boundaries. | +| Skills and reference material | Detailed build, link-checking, image-location, and publishing procedures. | + +## Common Questions + +| Question | Cause and Resolution | +|----------|----------------------| +| Key content in a layered file does not take effect | L2 is not injected by default; put always-needed rules in L0/L1. | +| The current task still uses old standing instructions after saving | The current execution turn keeps its snapshot. New content is read when new input, explicit continuation, or restoration is accepted. | +| Preview shows duplicate content | The same requirement is stored in multiple scopes. Keep it in the scope that owns it. | +| A team prompt does not take effect | Confirm membership and check the corresponding source when the agent belongs to multiple teams. | +| Layered source reports a format issue | Check for exact `## L0`, `## L1`, and `## L2` headings; standing instructions need none. | +| Standing Instructions is unavailable | Check whether the client includes the capability implemented in development version 10.0.179. | +| Standing instructions exceed the budget | Shorten the body and move detailed steps into skills. Execution does not proceed by truncating it or hiding an L2 section. | + +:::caution Prompts Are Not Permissions +Editing prompts does not change tool permissions, file access, or approval policy. Use the relevant permission settings to change permissions. +::: ## Next Steps diff --git a/i18n/en/docusaurus-plugin-content-docs/current/04-concepts/03-agentfs.md b/i18n/en/docusaurus-plugin-content-docs/current/04-concepts/03-agentfs.md index af04667..4a8681b 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/04-concepts/03-agentfs.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/04-concepts/03-agentfs.md @@ -6,6 +6,10 @@ keywords: [AgentFS, filesystem, data storage, Git, agent repository] # AgentFS Filesystem +:::info Standing instructions version support +`instructions.md` is implemented in development version 10.0.179. As of 2026-10-09, the latest public release is still v10.0.177. Release users need a version that includes this capability before using it. +::: + ## AgentFS is Like Each Agent's "Home" If DesireCore is like a community, then AgentFS is each agent's "home" in that community. This home contains its personal profile, work manual, skill certificates, memory logs, and archived receipts from every job. @@ -37,6 +41,7 @@ AgentFS's design is inspired by the Linux operating system's file structure: │ ├── agent.json # ID card: basic info and configuration │ ├── persona.md # Personality profile: communication style, decision preferences │ ├── principles.md # Behavioral guidelines: rules, forbidden zones, baselines +│ ├── instructions.md # Optional standing responsibilities, strategies, and delivery standards │ ├── memory/ # Memory bank: facts and experiences it remembers │ ├── skills/ # Skill packages: various skills it has learned │ ├── workflows/ # Workflows: execution plans for complex tasks @@ -72,6 +77,7 @@ This is where the agent's "soul" resides. Each agent is a Git repository contain | `agent.json` | Agent's basic info, version number | ID card | | `persona.md` | Personality, tone, decision preferences | Character traits | | `principles.md` | Behavioral guidelines, red lines, baselines | Professional ethics | +| `instructions.md` | Optional stable responsibilities, work strategies, and delivery standards | Working agreement | | `memory/` | Accumulated knowledge and experience | Long-term memory | | `skills/` | Various learned skills | Skill certificates | | `tools/` | External tools it can use | Toolbox | @@ -99,7 +105,7 @@ Detailed process of each task execution, including receipts, session records, et ### 1. Agents Can "Modify Themselves" -Because everything is files, agents can directly read and write their own files to learn and evolve. For example, when you teach it a new rule, it writes the rule to `principles.md`. This is much simpler than operating a database through APIs. +Because everything is files, agents can directly read and write their own files to learn and evolve. For example, behavioral boundaries belong in `principles.md`, agent-specific stable responsibilities in `instructions.md`, and detailed methods in skills. Personal preferences stay in the user scope. This is much simpler than operating a database through APIs. ### 2. Humans Can Easily Review @@ -115,7 +121,7 @@ Made a mistake? `git revert` and it's back. Not satisfied with recent "evolution ## Tiered Loading -To save AI model token consumption, AgentFS adopts a three-tier loading strategy: +Persona, principles, and layered global or team prompts can use L0/L1/L2 to control loading granularity. Skills also support on-demand discovery. Not every AgentFS file uses these tiers: | Tier | Content | Consumption | Purpose | |------|---------|-------------|---------| @@ -123,7 +129,7 @@ To save AI model token consumption, AgentFS adopts a three-tier loading strategy | **L1** | Core info + applicable scenarios | Low | Planning and decision-making | | **L2** | Complete content | On-demand | Actual execution | -This means the agent doesn't need to read all files every time, but loads on demand — saving both cost and improving efficiency. +`instructions.md` uses ordinary Markdown without L0/L1/L2 parsing. When allowed, it loads in full without summarization or truncation; detailed procedures belong in skills. See the [standing instructions format](../05-more/06-file-formats.md) for content ownership and update behavior. ## Next Steps diff --git a/i18n/en/docusaurus-plugin-content-docs/current/04-concepts/06-self-evolution.md b/i18n/en/docusaurus-plugin-content-docs/current/04-concepts/06-self-evolution.md index e61e52e..42799d0 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/04-concepts/06-self-evolution.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/04-concepts/06-self-evolution.md @@ -6,6 +6,10 @@ keywords: [self-evolution, Self-Evolution, learning, memory, experience accumula # Self-Evolution +:::info Standing instructions version support +`instructions.md` is implemented in development version 10.0.179. As of 2026-10-09, the latest public release is still v10.0.177. Release users need a version that includes this capability before using it. +::: + ## Agents Are Not Static Most AI products are "static" — using them 100 times is the same as using them once. Every conversation is like meeting for the first time. @@ -26,7 +30,7 @@ This is the most direct evolution method — you explicitly tell the companion h - "When writing weekly reports for me in the future, follow this format: first what was completed this week, then next week's plan, finally problems encountered" - "When reviewing contracts, if you find unclear intellectual property ownership, you must mark it in red as a warning" -**Output**: The companion generates a rule/skill modification proposal (diff), which takes effect after your confirmation. +**Output**: The companion generates a rule/skill modification proposal (diff), which takes effect after your confirmation. Save content by ownership: role and expression in persona, boundaries and priorities in principles, agent-specific stable responsibilities and delivery requirements in optional `instructions.md`, and detailed methods in skills. Personal preferences remain in the user scope. See [File Format Reference](../05-more/06-file-formats.md). ### Layer 2: Experience Accumulation (Learned from Interaction) @@ -65,13 +69,11 @@ By installing new skill packages or connecting new tools, the companion's capabi Free evolution sounds great, but without constraints, it could lead to companion "personality drift" or "memory pollution." Therefore, DesireCore sets strict evolution governance mechanisms. -### Untouchable Baselines +### Content Changes and Permission Boundaries -The following **cannot** be automatically overridden by evolution: +`persona.md`, `principles.md`, and `instructions.md` are editable content files. Review the specific diff when changing role, boundaries, or stable responsibilities, and follow existing tool permissions and approval policy. A heading in these files is not an immutable system permission level. -- **Core Personality** (core part of `persona.md`): The companion's basic character won't change due to evolution -- **Safety Red Lines** ("never do" in `principles.md`): Absolutely prohibited behaviors won't be relaxed -- **Permission Configuration**: Permission levels won't be automatically elevated +Content changes do not automatically elevate permissions or bypass approval. Saved standing instructions are read when new input, explicit continuation, or restoration is accepted; the same execution turn retains its original snapshot. ### Changes Reviewable diff --git a/i18n/en/docusaurus-plugin-content-docs/current/05-more/03-glossary.md b/i18n/en/docusaurus-plugin-content-docs/current/05-more/03-glossary.md index 1c014fe..35b436a 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/05-more/03-glossary.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/05-more/03-glossary.md @@ -95,6 +95,11 @@ The agent's active monitoring mechanism. Agents can periodically check specific ### Human Gate One of three step types. Steps requiring user personal confirmation. Execution automatically pauses at this step, waiting for explicit user instruction before continuing. +## I + +### Instructions (Standing Instructions) +Optional `instructions.md` at the agent root stores agent-specific stable responsibilities, default work strategies, and delivery standards. It uses ordinary Markdown and loads in full when allowed, without L0/L1/L2 parsing, summarization, or truncation. It grants no permissions. Implemented in development version 10.0.179; as of 2026-10-09, public release v10.0.177 does not yet include it. See [File Format Reference](./06-file-formats.md). + ## M ### MCP (Model Context Protocol) @@ -103,7 +108,7 @@ Model Context Protocol. An open standard proposed by Anthropic that allows AI mo ## P ### Persona -The agent's personality definition file (`persona.md`). Contains communication style, decision preferences, output specifications, etc.—the core definition of "who the agent is like." Not a "character setting copy," but executable behavioral specifications. +The agent's role and expression file (`persona.md`), including communication style, tone, and answer structure. Stable responsibilities and delivery standards belong in `instructions.md`; boundaries and priorities belong in `principles.md`. ### Plan One of the Six Primitives. The agent keeps a versioned Plan in the current working directory, recording goals, constraints, steps, risks, and verification. Plans are revised through natural conversation; they are not a mode or execution permission. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/05-more/06-file-formats.md b/i18n/en/docusaurus-plugin-content-docs/current/05-more/06-file-formats.md index da85b56..be02439 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/05-more/06-file-formats.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/05-more/06-file-formats.md @@ -1,11 +1,15 @@ --- title: File Format Reference description: Format and structure reference for core AgentFS files -keywords: [file format, AgentFS, agent.json, SKILL.md, memory, principles] +keywords: [file format, AgentFS, agent.json, instructions.md, SKILL.md, memory, principles] --- # File Format Reference +:::info Standing instructions version support +`instructions.md` is implemented in development version 10.0.179. As of 2026-10-09, the latest public release is still v10.0.177. Release users need a version that includes this capability before using it. +::: + AgentFS stores agent identity, behavior, memory, skills, and runtime policy as ordinary files. You can edit them through the UI or directly when you understand the fields. ## agent.json -- Agent Entry Configuration @@ -115,15 +119,11 @@ Every agent has an `agent.json` at its root. It defines identity, default model, - Template-like empathy or generic encouragement - Analysis with no decision or next action -## Safety and Confirmation -- Reading files, organizing material, drafting, and analysis can proceed directly and should produce a receipt. -- Sending messages or mail, deleting files, paying, production changes, and public publishing must pass a human gate first. - ## When Uncertain - State what is uncertain and give a verification path. Escalate to the user when the uncertainty affects risk. ``` -`persona.md` should be an executable communication contract, not marketing copy. Keep it short, concrete, and easy to test so the agent can follow it consistently. +`persona.md` stores role, expression style, and communication preferences. Put safety boundaries and confirmation rules in `principles.md`, and stable responsibilities and delivery requirements in `instructions.md`, so each requirement has one home. ## principles.md -- Behavioral Rules @@ -146,6 +146,40 @@ Every agent has an `agent.json` at its root. It defines identity, default model, `Never Do` rules and safety boundaries should stay concise and unambiguous. These constraints affect long-running agent behavior, so avoid writing them as vague preferences. +## instructions.md -- Agent Standing Instructions + +`instructions.md` is an optional file at the agent root. It stores stable responsibilities, default work strategies, and delivery standards. For example, it can define what a legal advisor should deliver in every contract review: + +```markdown +# Contract Review Responsibilities + +Before reviewing, establish the transaction goal, contract version, and priority clauses. + +Deliver a risk summary, itemized comments, suggested revisions, and questions for the user. +Include the source location for each comment. State uncertainty when evidence is missing; +do not invent clauses or facts. +``` + +### Where Content Belongs + +| Content | Location | +|---------|----------| +| Role, tone, and expression style | `persona.md` | +| Behavioral boundaries, prohibited actions, and priorities | `principles.md` | +| This agent's stable responsibilities, default work strategies, and delivery standards | `instructions.md` | +| Detailed procedures, long SOPs, templates, and reference material | `skills/*/SKILL.md` and its `references/` | +| User preferences, team conventions, and project rules | `prompt.md`, `rules.md`, or `AGENTS.md` in the relevant scope; do not copy them into the shareable agent body | + +### File and Update Contract + +- Use ordinary UTF-8 Markdown. Frontmatter is not required or parsed, and L0/L1/L2 headings have no loading semantics. Content under `## L2` is still part of the full body. +- When the current runtime context allows this source, its nonempty body is loaded in full as a separate prompt section. It is never automatically summarized or truncated. If it cannot fit the context budget, the operation fails explicitly; shorten the instructions and move detailed methods into skills. +- Saved content is reread when new input, explicit continuation, or restoration is accepted. Tool loops, retries, and fallback models within the same execution turn retain the accepted snapshot. +- Normal heartbeats also load the full instructions. Lightweight heartbeats with `lightContext=true` skip them. +- The `ManageAgent` `instructions` parameter is a string: omission preserves the file, a string replaces the whole body, and an empty string clears it. Omitting it during creation does not require the file to be generated. The body must not contain NUL characters. + +This file is one source for the dynamically assembled system prompt; it does not store or replace the complete `systemPrompt`. Editing it grants no tools, file access, or approval authority. See [File Explorer](../02-user-guide/06-agents/06-agent-files.md) and [Prompt Center](../02-user-guide/06-agents/12-prompt-center.md) for editing. + ## SKILL.md -- Skill Definition Each skill pack must include `SKILL.md`. Frontmatter can use top-level fields or a `metadata` wrapper.