muse-agent-example/.agent/docs/architecture/domains/07-Agent与Skill领域.md

Agent 与 Skill 领域 SoT

1. 唯一职责

Agent 与 Skill 领域拥有角色职责、可调用能力合同、确定性工具边界和能力复用方式。它回答“谁负责判断、调用什么能力、输入输出是什么、失败后如何收场、什么经验可以复用到下一部作品”。

本领域不拥有作品内容、实体事实、范式内容、质量终态或数据库事实；数据库权威和落库机制归 08-数据权威与可视化领域。但 Skill 是落库的执行者：它声明自己读写哪些表，并把经手的输入和产出落库可见。

2. 四类执行单元

单元	负责	不负责
主 ReAct Agent	观察库内状态、选择 Skill、组织步骤、融合结果、请求用户决策	代替所有专业角色创作，或绕过保护步骤
角色 Agent	在一次调用中完成一种需要模型判断的职责	运行 hash、权限、状态机或持久化
Skill	定义一个可复用能力的输入、输出、允许动作、失败和验收	同时承担多个无关意图
Tool	执行确定性解析、校验、计算、读写或报告	主观创作和质量裁决

角色至少包括 planner、writer、extractor、detector、judge。角色短身份提示由 .agent/agents/*.md 拥有；稳定角色合同由 角色合同 统一拥有，具体功能步骤由 Skill 拥有，不复制进角色文件。

派发器把身份提示、对应角色合同、功能合同和输出 Schema 按固定顺序装配。角色文件可以登记推荐 Skill 和工具能力供 Agent 路由，但不登记实际权限、模型、输入输出字段、hash、状态机或持久化规则。

角色是主 ReAct Agent 派发的子代理，按统一派发合同执行：

1. 派发方把角色身份提示与 角色合同 对应章节作系统提示词注入，不裁剪合同；身份和合同哈希进证据。
2. 输入是冻结的结构化 JSON，原样传入；输入哈希进证据。
3. 会话全新，不携带历史上下文；角色不得访问未声明的工具。
4. 输出是结构化 JSON，由派发方按 schema 校验后才可进入下游；校验失败按失败关闭。
5. 派发方负责证据落库（record-run-evidence）；角色本身不写回执、不推进状态。

派发的执行器是宿主适配器：交互式流程由宿主子代理机制承载（Claude Code 子代理、pi 会话等），自动化管线由受治理的模型调用适配器承载同一合同。合同不绑定任何 CLI 的原生角色装载（如 Claude Code --agent）；Claude CLI 不是角色运行底座。

3. Skill 合同

Skill 按实现性质分两类，合同要求不同。系统能力 Skill 执行动作并产生落库的系统事实，须声明下列全部九项；自带 scripts/ 不是判据——以模型判断为主的 Skill 可以不带 Tool，落库由它调用的 Skill 的 scripts/ 承担。参照 Skill 不执行动作、不产生系统事实，也不进 meta/chains 登记，只声明第 1、3 项并写明取用边界与不适用场景，第 2、4 至 9 项不适用。两类都是正式 skill，都可在创作生命周期内被角色取用，分类见 .agent/skills/_index.md。

每个系统能力 Skill 的 .agent/skills/{name}/SKILL.md 必须声明：

1. 唯一目的和消费者。
2. 输入、输出及 schema/version。
3. 必读文件和允许读取范围。
4. 允许的副作用与禁止写入对象。
5. 数据库读写合同：读哪些表、写哪些表、失败时如何关闭（失败即收手，不写半成品）。
6. 输入产出落库：哪些输入和产出必须进库可见，见索引 §3。
7. 稳定错误码和失败恢复。
8. raw、授权、预算和审计边界。
9. 开发验证与行为评测由 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 变更必须有登记在 harness/manifests/ 的相关实现测试、py_compile 和 git diff --check 证据；测试结果只证明机械合同，不升级为 Skill 行为或内容质量结论。

5. ReAct 工作方式

观察库内状态
  -> 选择单一 Skill
  -> Skill 读取受控上下文
  -> 角色 Agent 或 Tool 执行
  -> 校验结构化结果
  -> 更新待审候选(Shadow)与安全状态
  -> 判断继续、补证、修订或请求用户决策

ReAct Agent 不能把“扫全库、随意写表”当作通用工具。每次动作必须经过 Skill 合同，且只拿到完成当前步骤所需的表、文件和工具范围。

6. 能力复利：升格落点如何接收

经验升格的完整规则由质量与复利领域独家拥有，见 06-质量与复利领域 §6。本领域只管升格的落点——Skill、Tool 和 Agent 提示词——怎么接收：

• 作品内反复成功的做法先进入范式验证，不直接改全局 Agent。
• 升格一旦发生，原位置的重复执行说明必须删除，只保留证据和指向新 owner 的链接，不留下两份规则。
• 复用能力不得携带具体作品事实、人物名称或未经授权的正文。

注意两个“升格”不是一个意思：本节说的是经验或能力沉淀进 Skill、Tool、Agent 提示词；02-实体领域 里也习惯把“作品面实体从待审转为正式事实”叫升格，那是数据落库动作，与本节无关。

7. 模型与运行

模型运行时可替换；角色合同不绑定某个 CLI 的私有状态，也不绑定任何宿主的原生角色装载机制。角色执行走 §2 派发合同：全新会话、身份提示与中心合同注入、冻结输入、输出校验、证据落库。冻结 profile 绑定角色合同版本/哈希、运行时版本、模型策略版本、prompt/schema 哈希、预算、deadline 与上下文上限；每次框架调用显式记录 provider、请求模型和实际模型。模型不可用只终止当次调用，不损坏库里已有的正式内容，也不让 Skill 跳过检查。

运行底座分两层：宿主子代理机制承载交互式派发；muse_role -> muse_llm.chat_governed 承载自动化管线。工具隔离由会话授权实现：角色只用角色文件声明的工具，无工具角色不给任何工具。自动化角色调用不启动模型 CLI 子进程、不读取本机客户端配置。运行回执一经写入不可篡改；依赖只向下（上层调下层，不反向）。完整问答、完整原文这类 raw 进库可看全文；仓外保险库是可选备份，不是默认权威。

模型治理分两条明确策略：planner/writer/judge 使用固定 Opus 策略，绑定完整模型 ID，同模型可有限重试但不得降级或换供应商；extractor/detector 只有在 profile 明确登记时才可使用内容模型治理链。内容链按 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-数据权威与可视化领域。
• 范式来源：03-范式领域。
• 创作编排：05-创作流程领域。
• 质量升格：06-质量与复利领域。
• 实体入库（另一种“升格”）：02-实体领域。
• Agent 上级合同：专题-06。