126 lines
13 KiB
Markdown
126 lines
13 KiB
Markdown
# Agent 与 Skill 领域 SoT
|
||
|
||
## 1. 唯一职责
|
||
|
||
Agent 与 Skill 领域拥有角色职责、可调用能力合同、确定性工具边界和能力复用方式。它回答“谁负责判断、调用什么能力、输入输出是什么、失败后如何收场、什么经验可以复用到下一部作品”。
|
||
|
||
本领域不拥有作品内容、实体事实、范式内容、质量终态或数据库事实；数据库权威和落库机制归 [08-数据权威与可视化领域](08-数据权威与可视化领域.md)。但 Skill 是落库的执行者：它声明自己读写哪些表，并把经手的输入和产出落库可见。组件职责边界与约束归属以 [边界合同](../边界合同.md) 为准，本节不重复定义。
|
||
|
||
## 2. 执行单元与派发合同
|
||
|
||
| 单元 | 负责 | 不负责 |
|
||
|---|---|---|
|
||
| 主代理 | 理解并润色人的创作意图、确认歧义、选择 Skill、转述智能体报告、向人请求授权（继续/补证/重写） | 代替智能体创作、替智能体制定创作约束、绕过保护步骤 |
|
||
| 创作智能体（五个角色） | 按角色合同经授权工具自主探索，生成候选或检查报告 | 运行 hash、权限、状态机、持久化、裁决自己的产出 |
|
||
| Skill | 定义一个可复用能力的输入、输出、允许动作、失败和验收 | 同时承担多个无关意图 |
|
||
| 工具 server | 给智能体提供只读取数能力，统一入口，按任务包授权圈定，调用即留痕 | 提供裸查询、写操作、内容裁决 |
|
||
| 脚本与静态校验 | 确定性编排：绑定校验、状态机、落库、CAS、终态；报告防造假校验 | 内容裁决、拼创作提示词 |
|
||
|
||
角色至少包括 planner、writer、extractor、detector、judge，五个角色在目标形态下都是创作智能体：经授权的只读工具自主探索、按提示词合同工作。角色短身份提示与探索方法由 `.agent/agents/*.md` 拥有；稳定角色合同由 [角色合同](../角色合同.md) 统一拥有，具体功能步骤由 Skill 拥有，不复制进角色文件。
|
||
|
||
派发器把身份提示、对应角色合同、功能合同和输出 Schema 按固定顺序装配。角色文件可以登记推荐 Skill 和工具能力供 Agent 路由，但不登记实际权限、模型、输入输出字段、hash、状态机或持久化规则。
|
||
|
||
角色按统一派发合同执行：
|
||
|
||
1. 派发方把角色身份提示与 [角色合同](../角色合同.md) 对应章节作系统提示词注入，不裁剪合同；身份和合同哈希进证据。
|
||
2. 输入是冻结的结构化 JSON，原样传入；输入哈希进证据。
|
||
3. 工具白名单由任务包声明，工具 server 机械执行；白名单之外的调用一律拒绝。探索授权模式（只读集 / 圈定授权 / 无工具）见 [边界合同](../边界合同.md)。
|
||
4. 会话复用：同一章的补证与修改默认继续原会话；完全重写时新建会话并显式传入交接材料（人的任务、已用资料与版本、当前候选、已发现问题），不依赖隐藏记忆。
|
||
5. 输出是结构化 JSON，由派发方按 schema 校验后才可进入下游；校验失败按失败关闭。
|
||
6. 派发方负责证据落库（record-run-evidence）：事件账本、raw、逐回合模型调用，以及工具读取形成的依赖清单；角色本身不写回执、不推进状态。
|
||
|
||
执行底座分三条链：Muse 派发层先解析 `RoleTaskRequest`、角色合同、模型策略和输出 Schema，再通过 `FrameworkExecutionRequest` 交给 `framework/adapters/`；框架派发链承载生产与评测的角色执行主链，是唯一的创作生成链；受治理直调链（`muse_role -> muse_llm.chat_governed`）只承载内容模型任务（清洗、拆书、抽取、审卡）与对照生成——2026-08-23 同源对照实验裁决其退出创作生成（同一份探索依赖上下文下，直调臂复读细纲原句被机械门拒绝，框架派发臂双门通过并经人采纳）；批处理执行链（execute-role-task）承载无工具的直接角色任务。三条链共用角色合同、证据账本与落库合同；合同不绑定任何 CLI 的原生角色装载机制。
|
||
|
||
当前生产适配器是 Pi；DSH headless 适配器只作为 opt-in 对照接缝，固定为 fresh、无工具、session flush 后回放，待只读工具闭集与真实业务旅程证据齐备后再评估是否扩大能力。
|
||
|
||
## 3. Skill 合同
|
||
|
||
Skill 按实现性质分两类，合同要求不同。**系统能力 Skill** 执行动作并产生落库的系统事实，须声明下列全部九项；自带 `scripts/` 不是判据——以模型判断为主的 Skill 可以不带 Tool，落库由它调用的 Skill 的 `scripts/` 承担。**参照 Skill** 不执行动作、不产生系统事实，也不进 `meta/chains` 登记，只声明第 1、3 项并写明取用边界与不适用场景，第 2、4 至 9 项不适用。两类都是正式 skill，都可在创作生命周期内被角色取用，分类见 `.agent/skills/_index.md`。
|
||
|
||
每个系统能力 Skill 的位置以 `muse/lifecycle/quality/harness/manifests/skills.json` 的 `skill_path` 为准；路径允许嵌套，且其 `SKILL.md` 必须声明：
|
||
|
||
1. 唯一目的和消费者。
|
||
2. 输入、输出及 schema/version。
|
||
3. 必读文件和允许读取范围。
|
||
4. 允许的副作用与禁止写入对象。
|
||
5. 数据库读写合同：读哪些表、写哪些表、失败时如何关闭（失败即收手，不写半成品）。
|
||
6. 输入产出落库：哪些输入和产出必须进库可见，见索引 §3。
|
||
7. 稳定错误码和失败恢复。
|
||
8. raw、授权、预算和审计边界。
|
||
9. 开发验证与行为评测由 `muse/lifecycle/quality/harness/manifests/` 登记；`SKILL.md` 不承载测试命令、测试文件路径或测试结论。Skill 运行时需要执行的业务 dry-run/评测操作仍属于运行合同。
|
||
|
||
数据库是权威：系统能力 Skill 对自己读写哪些表负责，声明失败时如何关闭，并确保经手的输入和产出都落库。没落库的输入产出，在系统视角里等于不存在。只读看板只查库渲染，不替 Skill 写任何数据。参照 Skill 不读写库，也不产生需要落库的输入产出。
|
||
|
||
### 3.1 命名与稳定标识
|
||
|
||
- 目录名必须与 frontmatter `name` 完全一致，两类 Skill 同样适用。
|
||
- 系统能力 Skill 名统一使用小写 `动作-对象`，直接说明调用者能执行什么；参照 Skill 名使用小写领域名，说明它讲哪一块方法，不伪装成可执行动作。
|
||
- 名称不使用 `db`、`llm`、`runtime`、`eval` 这类内部模块缩写，也不使用 `upgrade`、`planning` 这类无法判断具体动作的阶段词。
|
||
- scenario 与 Skill 名分离：`continuation`、`fine_outline` 等 scenario 由 `meta/chains` 显式映射到动作式 Skill 名，不能假设两者同名；参照 Skill 不进链登记，没有对应 scenario。
|
||
- 数据库 `source_type`、creator/updater、错误码和备份逻辑键是历史兼容标识；Skill 改名不自动改写这些值。
|
||
- 一个名称只对应一个目录和一份 `SKILL.md`；改名后不留旧目录、别名 Skill 或重复合同。
|
||
|
||
## 4. Tool 合同
|
||
|
||
- Tool 放在所属 Skill 的 `scripts/`，不散落一次性脚本；参照 Skill 的 `scripts/` 只放工作表与清单文本，不含 Tool。
|
||
- 被两个以上 Skill 或看板消费的确定性实现升级为共享运行时包（如 `muse_db`、`muse-deai`、`muse_llm`、`muse_role`、`muse_embed`）；所属 Skill 只保留 CLI 与落库编排。调用方 `import` 已安装的包，不得 `sys.path` 指向其它 Skill 的 `scripts/`。
|
||
- 默认从仓库任意工作目录调用，必须自行解析项目根和输入绝对路径，不能依赖调用者先 `cd` 到特定目录。
|
||
- 机械事实必须结构化输出稳定状态和错误码；人读日志是补充，不是唯一接口。
|
||
- Tool 不调用模型，除非所属 Skill 明确声明该步骤本质需要模型。
|
||
- Tool 变更必须有登记在 `muse/lifecycle/quality/harness/manifests/` 的相关实现测试、`py_compile` 和 `git diff --check` 证据；测试结果只证明机械合同，不升级为 Skill 行为或内容质量结论。
|
||
|
||
## 5. 目标工作链与授权管控
|
||
|
||
```text
|
||
人的创作意图
|
||
-> 主代理润色、确认歧义
|
||
-> 任务提示词 -> 智能体自主探索
|
||
-> 候选 / 报告 + 依赖清单
|
||
-> 静态校验与编排（状态机、落库）
|
||
-> 主代理向人说明并请求授权
|
||
-> 人闸决策 -> 正式正文 / 确认转正 / 丢弃
|
||
```
|
||
|
||
检查发现问题时，智能体返回结构化缺口报告（缺什么、为什么需要、预计成本），编排停在授权终态；主代理把报告转述给人，人决定继续、换方向或停止，之后复用原会话或新建会话继续。补证与重写没有业务次数硬上限，管控由人承担；技术保护（单次超时、单次预算、用户取消、事务保护）保留。
|
||
|
||
智能体的每次动作必须经过授权的只读工具；探索轨迹（读了什么、哪个版本）自动进事件账本，构成依赖清单，供人闸与链路透视审计。
|
||
|
||
## 6. 能力复利：升格落点如何接收
|
||
|
||
经验升格的完整规则由质量与复利领域独家拥有，见 [06-质量与复利领域 §6](06-质量与复利领域.md)。本领域只管升格的落点——Skill、Tool 和 Agent 提示词——怎么接收：
|
||
|
||
- 作品内反复成功的做法先进入范式验证，不直接改全局 Agent。
|
||
- 升格一旦发生，原位置的重复执行说明必须删除，只保留证据和指向新 owner 的链接，不留下两份规则。
|
||
- 复用能力不得携带具体作品事实、人物名称或未经授权的正文。
|
||
|
||
注意两个“升格”不是一个意思：本节说的是经验或能力沉淀进 Skill、Tool、Agent 提示词；[02-实体领域](02-实体领域.md) 里也习惯把“作品面实体从待审转为正式事实”叫升格，那是数据落库动作，与本节无关。
|
||
|
||
## 7. 模型与运行
|
||
|
||
模型运行时可替换；角色合同不绑定某个 CLI 的私有状态，也不绑定任何宿主的原生角色装载机制。角色执行走 §2 派发合同：全新会话、身份提示与中心合同注入、冻结输入、输出校验、证据落库。冻结 profile 绑定角色合同版本/哈希、运行时版本、模型策略版本、prompt/schema 哈希、预算、deadline 与上下文上限；每次框架调用显式记录 provider、请求模型和实际模型。模型不可用只终止当次调用，不损坏库里已有的正式内容，也不让 Skill 跳过检查。
|
||
|
||
运行底座三条链的分工见 §2。工具隔离由任务包白名单机械实现：智能体只用任务包声明的工具，白名单为空即无工具。自动化角色调用不读取本机客户端配置。运行回执一经写入不可篡改；依赖只向下（上层调下层，不反向）。完整问答、完整原文这类 raw 进库可看全文；仓外保险库是可选备份，不是默认权威。
|
||
|
||
模型治理分两条明确策略：`planner`/`writer`/`judge` 使用固定 Opus 策略，绑定完整模型 ID，同模型可有限重试但不得降级或换供应商；`extractor`/`detector` 只有在 profile 明确登记时才可使用内容模型治理链。模型策略的事实源是 [角色合同](../角色合同.md)，执行侧常量是该事实的镜像，两者不一致即为缺陷。内容链按 5 小时额度窗计量，达到约 $24 阈值后在策略内降级，命中敏感词时切换到策略内可用模型。两条策略都记录 requested 策略、actual 模型、成本和用量；策略外模型失败关闭，回执按索引 §3 落库。
|
||
|
||
## 8. 验收条件
|
||
|
||
1. 一个 Skill 只有一个明确业务目的。
|
||
2. Skill 目录名与 frontmatter `name` 一致；系统能力 Skill 名符合 `动作-对象` 且 scenario 通过链登记映射，参照 Skill 用领域名、不进链登记。
|
||
3. 每个系统能力 Skill 在 SKILL.md 声明数据库读写合同（读哪些表、写哪些表、失败如何关闭）。
|
||
4. 每个系统能力 Skill 的输入与产出都落库，只读看板能查到对应记录。
|
||
5. Tool 从不同当前目录调用得到一致结果。
|
||
6. 角色 Prompt 只声明职责边界（说清不做什么），不包含 adapter、hash、状态机等支架职责。
|
||
7. 稳定经验能沿“范式 -> Skill/Tool/Agent”升格且不产生重复规则。
|
||
8. 模型不可用只终止当次 AI 调用，库内已有正式内容不被损坏。
|
||
|
||
## 9. 关联 SoT
|
||
|
||
- 横切落库合同：见索引 §3。
|
||
- 数据权威、raw 进库与只读看板：[08-数据权威与可视化领域](08-数据权威与可视化领域.md)。
|
||
- 范式来源：[03-范式领域](03-范式领域.md)。
|
||
- 创作编排：[05-创作流程领域](05-创作流程领域.md)。
|
||
- 质量升格：[06-质量与复利领域](06-质量与复利领域.md)。
|
||
- 实体入库（另一种“升格”）：[02-实体领域](02-实体领域.md)。
|
||
- Agent 上级合同：[专题-06](../../../../design-docs/专题-06-元数据驱动的智能体架构.md)。
|