FDE Skill 开发规范手册
V1.0 · 2026-09-15 · 4人并行 · 50 Skill · YAML Frontmatter · JSON Schema Draft 2020-12 · 路由评测20条 · 安全约束7条 · SOP 31步全覆盖
一、Agent Skills 兼容格式
1Frontmatter 规范
1.1 SKILL.md Frontmatter格式
对标 Agent Skills 规范,SKILL.md 使用 YAML frontmatter。官方只要求 name 和 description:
---
name: project-intake
description: 录入商机信息并创建项目档案,输出项目编号、关联客户、商机阶段等结构化数据。当用户需要新建项目、录入商机时使用。不查询工商信息(→SK-10)、不做风险评分(→SK-14)、不生成尽调报告(→SK-24)。
allowed-tools: ""
compatibility: "requires: none"
version: 1.0.0 # FDE扩展字段,非Agent Skills标准顶层字段
---
## 角色定义
你是项目自动建档助手,负责录入商机信息并创建项目档案。
1.2 字段说明
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
name | 必填 | string | kebab-case,必须与父目录名完全一致。如 project-intake |
description | 必填 | string | 100-200字,三要素:做什么+何时触发+不做什么。AI路由Skill的主要依据(配合triggers、sop_stage等辅助字段)。 |
allowed-tools | 可选 | string | 空格分隔的工具名。实验特性,客户端支持程度不同。 |
compatibility | 可选 | string | 环境依赖声明。值需加引号。如 "requires: asr-service>=1.0; network: yes" |
version | 可选 | string | FDE扩展字段(非Agent Skills标准顶层字段)。语义化版本号 MAJOR.MINOR.PATCH。如 1.0.0 |
1.3 description 三要素
| 要素 | 说明 | 示例(SK-10) |
|---|---|---|
| 做什么 | 核心功能和输入→输出 | "查询企业的工商注册信息,输入公司名/统一社会信用代码,输出注册资本、法定代表人、经营状态等" |
| 何时触发 | 什么场景下调用 | "当用户需要查工商信息、核验企业资质、尽调阶段查询合作方工商状态时使用" |
| 不做什么 | 明确边界 | "不查询司法记录(→SK-11)、不搜舆情(→SK-12)、不做风险评分(→SK-14)" |
1.4 字段命名规范
| 规则 | 说明 |
|---|---|
| JSON字段 | snake_case(小写+下划线),不用驼峰 |
| YAML字段 | kebab-case(连字符),如 allowed-tools |
| 时间格式 | ISO 8601(2026-09-05T10:30:00+08:00),不用时间戳 |
| 金额格式 | int分,不用float元。10000=100元 |
| 枚举值 | 英文小写+下划线,如 "risk_level": "high" |
| 空值 | null,不用空字符串"" |
| 空数组 | [],不用null([]表示"无依赖",null表示"未设置") |
| 三态区分 | not_found / unavailable / not_provided,不统一用null |
红线:金额用int分不用元——最高频bug来源。所有Skill输入输出统一。
2目录结构(四层分离)
2.1 四层分离
四层分离:Agent Skills 可移植格式、FDE业务注册、运行时编排、运行环境协议分属不同层,拆为四层:
| 文件 | 归属层 | 内容 |
|---|---|---|
SKILL.md | Agent Skills 可移植层 | YAML frontmatter + Markdown body(Prompt指令)。只放与平台无关的Skill指令。 |
fde.manifest.yaml | FDE 业务注册层 | SK编号、FDE归属、SOP阶段、依赖图、执行边界。 |
references/ | 业务规则层 | 详细规则/模板/矩阵。AI按需加载。 |
evals/ | 评测层 | 路由评测 + 产出评测用例。 |
scripts/ | 计算层 | 程序化计算脚本(评分/公式/对账匹配)。 |
CHANGELOG.md | 版本层 | 版本变更记录。 |
运行协议分离:"所有Skill必须只输出JSON""三按钮确认卡片""24小时超时"等属于 Skill运行时协议,不在 SKILL.md 中定义。规范只定义运行时需提供的能力(权限拦截、卡片渲染、上下文管理、手工模式),不绑定具体产品。
2.2 标准目录结构
skills/
├── project-intake/ # 目录名 = name = "project-intake"
│ ├── SKILL.md # 必填:YAML frontmatter + 5段式Prompt
│ ├── fde.manifest.yaml # 必填:业务元数据
│ ├── references/ # 选填:详细规则/模板/矩阵
│ │ ├── report_template.md
│ │ └── scoring_rules.md
│ ├── scripts/ # 选填:程序化计算脚本
│ │ └── calc_score.py
│ ├── evals/ # 必填:评测用例
│ │ ├── should_trigger.jsonl # 路由正例(8-10条)
│ │ ├── should_not_trigger.jsonl # 路由反例(8-10条)
│ │ └── output_assertions.jsonl # 产出断言用例
│ └── CHANGELOG.md # 必填:版本记录
├── business-type-detect/ # SK-02
└── _shared/
├── schemas/ # JSON Schema 文件 (Draft 2020-12)
│ ├── envelope.schema.json
│ ├── handoff/
│ └── skill_output/
├── enums.json
└── prompt_fragments/
命名规范:目录名 = name = kebab-case标识符(如
project-intake),SK-01编号放 fde.manifest.yaml。3fde.manifest.yaml
# fde.manifest.yaml
skill_id: SK-01
skill_name_cn: 项目自动建档
owner_fde: FDE-1
sop_stage: S1-B00
boundary: A # A/B/C 执行边界
dependencies:
external_api: [] # 空数组用[],不用null
mcp_tools: []
upstream_skills: []
downstream_skills: [SK-02] # 直接下游,同MD1表D"下游"列(链式消费以主表为准)
parallelizable_with: []
triggers:
- phrase: "建档"
type: primary
sop_stage: S1
空值规范:空依赖一律用
[],不用 null。4allowed-tools 规范
4.1 格式规范
| 属性 | 规范 | 说明 |
|---|---|---|
| 字段名 | allowed-tools(连字符) | YAML frontmatter 标准字段名 |
| 值类型 | 空格分隔字符串 | 如 "erp.route-search ec.product-create" |
| 权限语义 | 声明性字段 | 实际拦截由 Skill运行时执行 |
4.2 正确用法
# SKILL.md frontmatter
allowed-tools: erp.route-search ec.product-create
# 纯LLM Skill(不需要外部工具)
allowed-tools: "" # 或省略此字段
| Skill | allowed-tools | 说明 |
|---|---|---|
| SK-39 核销数据导入 | ext.gate-query | 只能调闸机核销查询 |
| SK-27 合同初稿生成 | (空) | 纯LLM生成 |
| SK-37 商品配置预填 | ec.product-create ec.product-search | 只能调电商域2个工具 |
警告:allowed-tools 是声明性字段。实际权限拦截必须由 Skill运行时实现——读取声明,拦截白名单外的工具调用。SKILL.md 本身不执行权限拦截。
二、输入输出规范
5输出公共信封
所有 Skill 输出必须为合法 JSON,遵循公共信封结构。
{
"skill_id": "SK-24",
"skill_name": "尽调报告生成",
"exec_status": "success",
"exec_boundary": "C",
"need_confirm": true,
"confirm_message": "尽调报告已生成,请确认",
"data": {
"structured": { "risk_level": "medium", "risk_score": 72 },
"document": { "format": "markdown", "content": "# 尽调报告\n..." }
},
"progress": {
"current_step": "B08 · 尽调报告生成",
"current_stage": "S1 商机与尽调",
"overall_progress": "8/31",
"next_step": "B09 · 谈判问题清单 (SK-18)",
"blocked": false
},
"downstream_hint": {
"for_skills": ["SK-25"],
"key_fields": ["report_id", "risk_level"]
},
"errors": null,
"timestamp": "2026-09-05T10:30:00+08:00"
}
JSON合法性:实际 Skill 输出必须为合法 JSON(无注释、无尾逗号、无省略)。
6JSON Schema 规范
6.1 为什么需要正式 Schema
正式 JSON Schema 文件可校验类型、枚举、必填,validate.js 仅检查字段名不足以覆盖。
6.2 Schema 文件组织
_shared/schemas/
├── envelope.schema.json # 公共信封 (Draft 2020-12)
├── handoff/ # 6个交接格式
│ ├── due_diligence_pack.schema.json
│ ├── dd_report.schema.json
│ └── ...
└── skill_output/ # 各Skill输出Schema
├── sk-01-output.schema.json
└── ...
6.3 公共信封 Schema(Draft 2020-12 节选)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://yunlingxi.com/schemas/envelope.schema.json",
"title": "Skill输出公共信封",
"type": "object",
"required": ["skill_id", "skill_name", "exec_status", "data", "timestamp"],
"properties": {
"skill_id": { "type": "string", "pattern": "^SK-\\d{2}$" },
"exec_status": { "type": "string", "enum": ["success", "partial", "failed", "cancelled"] },
"exec_boundary": { "type": "string", "enum": ["A", "B", "C"] },
"data": { "type": ["object", "null"] },
"errors": {
"type": ["array", "null"],
"items": {
"type": "object",
"required": ["code", "message"],
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"retryable": { "type": "boolean" }
}
}
},
"timestamp": { "type": "string", "format": "date-time" }
}
}
Schema变更=MAJOR版本:Schema文件变更时信封
schema_version 升MAJOR,通知所有下游FDE。7文档类 Skill 输出双结构
生成文档的 Skill 输出分 structured(给下游Skill消费)+ document(给用户查看):
"data": {
"structured": { "risk_level": "medium", "risk_score": 72 },
"document": { "format": "markdown", "content": "# 尽调报告\n..." }
}
三、Prompt 工程
8Prompt 5段式结构
## 角色定义
你是{角色名称},负责{职责描述}。当前执行SK-{编号} {中文名}。
## 职责边界
你做什么:{列举}
你不做什么:{列举相邻Skill,用"→ SK-xx"标注路由}
## 输入规范
- {参数1}({类型},{必填/选填}):{说明}
## 输出规范
必须输出JSON,结构如下:
{输出JSON Schema引用}
## 执行边界
- 级别:{A/B/C}
- 执行后行为:{描述}
- 禁止事项:{≥1条}
- 输出前自检:格式/事实/范围/边界/语言 5项
"不做什么"必须列出所有易混淆的相邻Skill,用"→ SK-xx"标注正确路由。
9长度控制
9.1 Prompt 长度限制
| Skill类型 | 上限 | 示例 |
|---|---|---|
| 简单型(查询/检索/归类) | ≤500 token | SK-03/04/06/10 |
| 中等型(生成/检查/计算) | ≤1,200 token | SK-05/07/22/27 |
| 复杂型(报告/合同/对账) | ≤2,000 token | SK-24/25/43 |
红线:超过2,000 token必须拆分。拆为串联小Skill,或使用 references/ 引用文件。
9.2 Token 估算方式
红线:禁止粗估:"1 token≈1.5字"不适合中文。不同模型中文 token 率差异很大。
| 方式 | 说明 |
|---|---|
| 禁止 | 用"1 token≈1.5字"或"1 token≈1字"粗估 |
| 正确 | 使用目标模型实际 tokenizer 测量(tiktoken等) |
| 验证脚本 | validate.js 调用 tokenizer 库实际计数 |
9.3 输出长度控制
| 输出类型 | 上限 | 控制方式 |
|---|---|---|
| 结构化数据(JSON) | ≤2,000 token | Schema限制≤20字段 |
| 摘要/列表 | ≤500 token | 限制条数(摘要≤6,风险≤5) |
| 文档(报告/合同) | ≤3,000 token | 分section,每section≤800 |
| 确认卡片 | ≤300 token | 摘要≤6条,每条≤30字 |
106类约束
| 约束 | 说明 | 示例 |
|---|---|---|
| 格式 | 输出必须是什么格式 | "必须输出JSON,不输出其他内容" |
| 事实 | 禁止编造数据 | "只使用输入或API数据,不可编造" |
| 行为 | 禁止越权 | "不评估风险等级(→SK-14)" |
| 质量 | 可检验标准 | "摘要≤6条""关键风险≤5条" |
| 语言 | 语言和风格 | "中文,正式商务语气" |
| 默认值 | 可选参数提供默认值 | "默认使用中等风险情景(profit_margin=0.15)" |
11Few-shot 与 references 引用
11.1 Few-shot 示例
| Skill类型 | 示例数 | 说明 |
|---|---|---|
| 格式严格型 | 1个 | 输出格式固定,1个够 |
| 判断有弹性型 | 2-3个 | 需正反例 |
| 生成文档型 | 1个模板 | 给模板不给完整示例 |
11.2 references/ 引用文件模式(Progressive Disclosure)
## SKILL.md(核心流程,≤1,000 token)
你是尽调报告生成助手。按照以下步骤生成报告:
1. 读取尽调数据包(上游交接1)
2. 按 references/report_template.md 的模板结构生成
3. 评分规则见 references/scoring_rules.md
4. 风险等级判定见 references/risk_matrix.md
## references/report_template.md(按需加载)
# 尽调报告模板
## 一、企业基本信息
## 二、工商与司法查询结果
## 三、财务勾稽分析
## 四、风险评级与纳入建议
引用原则:SKILL.md只放"做什么+怎么做",详细规则全部放references/。
四、业务架构
12执行边界
12.1 三级边界
| 级别 | 含义 | 行为 | need_confirm |
|---|---|---|---|
| A级 | 可自动执行 | 直接返回结果 | false |
| B级 | AI辅助人确认 | 弹出确认卡片 | true |
| C级 | 人工主责 | 提供模板/预填 | true |
12.2 四类自动化红线
| 红线 | 说明 | 涉及Skill |
|---|---|---|
| 经营决策 | 不可自动决定通过合作/纳入 | SK-14,24 |
| 法务财务 | 不可认定财务真实性/法务意见 | SK-15,22 |
| 资金动作 | 不可自动付款/变更账户 | SK-35,36,44,45 |
| 数据治理 | 不可无边界爬取/脱敏后外传 | SK-09,50 |
红线:资金类证据链(加硬):SK-35/36/44/45等资金类C级Skill,仅"用户告诉我已完成"不够。必须遵循四步闭环:AI生成材料 → 人工在目标系统执行 → 人工上传执行证据(回单/凭证号/截图) → 系统记录证据URL+时间+操作人。确认卡片增加
evidence_required: true 字段,未上传证据不允许确认。13人工确认卡片
13.1 统一格式(B/C级弹出)
{
"card_type": "confirm",
"skill_id": "SK-24",
"title": "尽调报告已生成,请确认",
"summary": [
{"label": "风险评级", "value": "中风险", "highlight": true},
{"label": "纳入建议", "value": "建议纳入,需追加担保"}
],
"actions": [
{"id": "confirm", "label": "确认采纳", "primary": true},
{"id": "modify", "label": "我要修改", "primary": false},
{"id": "reject", "label": "不采纳", "primary": false}
],
"evidence_required": true,
"next_hint": {
"message": "确认后可进入谈判阶段,需要出谈判问题清单吗?",
"suggested_skill": "SK-18",
"auto_trigger": false
},
"timeout": 86400,
"on_timeout": "cancel"
}
13.2 卡片设计规则
| 规则 | 说明 |
|---|---|
| 摘要≤6条 | 人能一眼扫完 |
| 高风险标红 | highlight=true红色高亮 |
| 三按钮 | 确认/修改/不采纳 |
| 超时取消 | B/C级超时=cancel |
| 修改入口 | 点击后进入编辑模式 |
| 拒绝有因 | 必填拒绝原因 |
| 操作绑定 | 绑定具体操作+目标+参数 |
14触发词防冲突
14.1 触发词三段式
所有触发词按 [动作]+[业务对象]+[限定词] 注册,禁止单动词:
// 正确
SK-07: "检查资料完整性" // 动作=检查 对象=资料 限定=完整性
SK-24: "出尽调报告" // 动作=出 对象=尽调报告
// 禁止
SK-07: "检查" // 单动词,8个Skill冲突
14.2 注册规则
| 规则 | 说明 |
|---|---|
| 每Skill ≤5条 | 3-5条最佳 |
| 主触发词唯一 | 50个Skill两两不同 |
| 带SOP阶段标签 | AI按阶段过滤 |
14.3 高频冲突词消解表
| 冲突词 | 涉及Skill | 消解方案 |
|---|---|---|
| "检查" | SK-07/08/14/22/29/34/42/44 | 加对象:资料/主体/偏离/材料 |
| "生成/出" | SK-05/24/25/27/43/48 | 加产出物:清单/报告/合同 |
| "查询/查" | SK-03/10/11/12/39 | 加对象:案例/工商/司法 |
15职责边界防重叠
15.1 易混淆Skill对区分
| 重叠组 | 区分原则 |
|---|---|
| SK-07 vs SK-08 | SK-07管"有没有",SK-08管"对不对" |
| SK-24 vs SK-25 | SK-24是尽调结论,SK-25引用不重复生成 |
| SK-43 vs SK-44 | SK-43算账,SK-44开票,依赖SK-43 |
15.2 职责矩阵
| 业务动作 | 主责 | 不可越界 |
|---|---|---|
| 建档/录入项目 | SK-01 | 其他不可自动建档 |
| 评估风险等级 | SK-14 | SK-24引用SK-14 |
| 生成合同初稿 | SK-27 | SK-28只做版本对比 |
16SOP 全链路覆盖
步数说明:按HTML 3.5b,B00-B30共31步全覆盖。其中MCP依赖步7步(B18、B23-B28,另有S5隐式SK-46);B20为人工签章步骤(无AI Skill);未拆B#的隐式Skill(SK-09/47跨步、SK-15/16/17归S1、SK-45/46归S5)在fde.manifest的sop_stage标注,路由时需显式识别。
| 步 | SOP动作 | 主Skill | 状态 | 说明 |
|---|---|---|---|---|
| B00 | 商机线索录入/项目自动建档 | SK-01 | ✓ | — |
| B01 | 业务类型识别→自动加载对应SOP | SK-02 | ✓ | — |
| B02 | 历史案例检索+模板检索 | SK-03/04 | ✓ | — |
| B03 | 尽调清单生成+资料索取 | SK-05 | ✓ | — |
| B04 | 文件归类命名+资料完整性检查 | SK-06/07 | ✓ | — |
| B05 | 主体一致性检查 | SK-08 | ✓ | — |
| B06 | 公开工商查询+司法执行+舆情检索 | SK-10/11/12 | ✓ | 需外部API |
| B07 | 风险主体消歧+尽调评分辅助 | SK-13/14 | ✓ | — |
| B08 | 尽调报告生成→风险卡→纳入建议初稿 | SK-24 | ✓ | — |
| B09 | 谈判问题清单生成 | SK-18 | ✓ | — |
| B10 | 录音转写与说话人识别+商务条款抽取 | SK-19/20 | ✓ | SK-19需ASR |
| B11 | 共识与争议识别+标准条款偏离检查 | SK-21/22 | ✓ | — |
| B12 | 商业方案四流检查→谈判卡定稿 | SK-23 | ✓ | — |
| B13 | 上会材料生成(请示/议案/尽调摘要) | SK-25 | ✓ | — |
| B14 | 跨材料一致性检查 | SK-29 | ✓ | — |
| B15 | 审批路径计算+审批角色摘要 | SK-30/31 | ✓ | SK-30需组织架构API |
| B16 | 会议纪要+任务提取+评论汇总→决议 | SK-33/32 | ✓ | — |
| B17 | 合同初稿生成 | SK-27 | ✓ | — |
| B18 | 律师对接资料组包 | SK-26 | ✗MCP | 需文档系统 |
| B19 | 合同版本对比→签署前完整性检查 | SK-28/34 | ✓ | — |
| B20 | 合同签署(人工签章确认) | — | △人工 | 无AI Skill对应 |
| B21 | 付款申请组包→预付款流程发起 | SK-35 | ✓ | — |
| B22 | 收款账户变更核验 | SK-36 | ✓ | 银行API |
| B23 | 商品配置预填→创建商品→挂商城 | SK-37 | ✗MCP | 需ec.product-create |
| B24 | 履约阈值监控 | SK-38 | ✗MCP | 需订单实时数据 |
| B25 | 核销与订单数据导入 | SK-39 | ✗MCP | 需ext.gate-query |
| B26 | 逐笔对账匹配+合同公式复算+差异分类 | SK-40/41/42 | ✗MCP | — |
| B27 | 对账单生成 | SK-43 | ✗MCP | — |
| B28 | 开票清单检查 | SK-44 | ✗MCP | 需fin.invoice-issue |
| B29 | 续约复盘生成 | SK-48 | ✓ | 完整验证需全链路 |
| B30 | 项目归档索引+SOP规则候选提炼 | SK-49/50 | ✓ | SK-50需全链路验证 |
覆盖结论:31步全覆盖(B00-B30),其中B20为人工签章步骤(无AI Skill对应)。MCP断档7步(B18、B23-B28,另有S5隐式SK-46)有手工模式兜底;外部API 6个(SK-10/11/12/19/30/36)需API对接后自动化。
17断档兜底机制
| 断档类型 | 场景 | 兜底 |
|---|---|---|
| MCP未就绪 | B18+B23-B28共7步(另有S5隐式SK-46) | 手工模式 |
| API不可用 | SK-10/11/12/19/30/36 | 返回空+标注"待补充" |
| 上游缺失 | 下游上游未执行 | null填充+高亮"数据缺失" |
17.1 MCP手工模式
1. 不执行实际业务操作
2. 生成操作指引:目标系统+步骤+预填数据
3. 告知用户:"当前为手工模式,请在ERP中操作后告诉我"
4. 用户确认后,Skill继续下游
关键:断档不等于停摆。
18进度提示与接力棒
"progress": {
"current_step": "B08 · 尽调报告生成",
"current_stage": "S1 商机与尽调",
"overall_progress": "8/31",
"next_step": "B09 · 谈判问题清单 (SK-18)",
"blocked": false
}
progress分母:31(B00-B30)。
接力棒(next_hint):Skill执行完成后主动提示下一步,但不自动触发(auto_trigger=false)。
五、错误处理与降级
19错误分类与处理
| 错误类型 | status | 处理策略 | 重试 |
|---|---|---|---|
| 输入缺失/格式错误 | failed | 返回错误+正确格式示例 | 否 |
| 外部API超时 | partial | 返回部分+标注缺失 | 1次 |
| LLM生成异常 | failed | Retry 1次(温度降0.3) | 1次 |
| MCP工具不可用 | failed | 切换手工模式 | 否 |
| 用户拒绝确认 | cancelled | 保存草稿,不触发下游 | 否 |
| 工具返回not_found | partial | "查了没有"≠"查询失败" | 否 |
| 权限拒绝 | failed | "无权限"+所需权限 | 否 |
红线:写操作不自动重试:涉及资金/合同/商品写操作失败不自动重试,必须人工确认后手动重试。使用幂等键,先查最终状态。
20Repair Loop
20.1 Repair Loop vs 重试(语义区分)
语义区分:Repair Loop 和 Retry 是两个独立机制,分别针对 Schema校验失败 和 LLM生成异常:
| 机制 | 次数 | 触发条件 | 说明 |
|---|---|---|---|
| Retry | 1次 | LLM生成异常/超时 | 同样Prompt再来一次,温度降0.3。不改Prompt。 |
| Repair Loop | 2轮 | Schema校验失败 | 把错误信息+原始输出喂回LLM让它自修正。 |
关系:LLM输出 → Schema校验 → 失败进Repair Loop(最多2轮)→ 仍失败标记failed。LLM本身异常则Retry 1次后重新进入Schema校验。
20.2 Repair Loop流程
1. LLM输出 → Schema校验
2. 校验失败 → 把错误信息+原始输出喂回LLM:
"你上次的输出存在以下问题:{错误详情}。请修正后重新输出。"
3. LLM修正输出 → 再次Schema校验
4. 通过 → 返回结果
5. 仍然失败 → 标记failed+返回原始输出供人工查看
// 最多2轮repair,温度:第1轮原温度,第2轮降0.3
// 不repair:语义错误、写操作失败
关键:Repair Loop vs 简单重试:重试是"再来一次"(大概率犯同样错);Repair Loop是"告诉你错在哪了,改过来"。
21错误信封
{
"skill_id": "SK-11",
"exec_status": "failed",
"errors": [{
"code": "API_TIMEOUT",
"message": "裁判文书网API请求超时",
"detail": "请求耗时15s,超过5s阈值",
"suggestion": "可稍后重试,或手动查询后录入",
"retryable": true
}],
"data": null
}
六、AI 适配与防偏
22三级上下文加载
| 级别 | 目标token | 加载内容 | 加载时机 |
|---|---|---|---|
| L1 索引层 常驻 | ~3,000 | 50个Skill精简索引(name+描述+主触发词+阶段) | 对话开始 |
| L2 活跃层 按阶段 | ~8,000 | 当前SOP阶段全部Skill完整description | 阶段切换 |
| L3 执行层 按需 | ~2,000 | 被调用Skill完整SKILL.md+输入数据 | 确定调用 |
Token估算:3K是目标值不是保证值。用目标模型实际tokenizer测量L1/L2/L3实际token数。
22.1 上下文压缩策略
| 策略 | 说明 |
|---|---|
| 已执行Skill摘要化 | 确认后保留摘要(id+status+结论),丢弃完整输出 |
| 对话历史窗口 | 保留最近5轮,更早压缩为摘要 |
| 交接数据外部存储 | 不通过上下文传递,写入外部存储 |
23产出防偏机制
| 偏离类型 | 表现 | 防护 |
|---|---|---|
| 幻觉编造 | API返回空,AI编数据 | ①Prompt"不可编造" ②API数据标注来源 ③空数据填null |
| 格式漂移 | 输出自由文本 | ①"必须输出JSON" ②Schema校验,不过进Repair Loop |
| 越权执行 | 做了别的Skill的事 | ①Prompt写"不做什么" ②Schema不含其他Skill字段 |
| 数值错误 | 分当成了元 | ①"金额单位:分"写入Prompt ②输出含amount_unit:cent |
23.1 输出前自检
1. 格式:合法JSON,必填字段齐全
2. 事实:数据来自输入或API,无编造
3. 范围:金额在1分~100亿元内
4. 边界:未输出不属于本Skill的字段
5. 语言:中文,正式商务语气
23.2 关键Skill双重校验(AI不做数学题)
| Skill | 校验方式 |
|---|---|
| SK-17 额度测算 | 程序化复算 |
| SK-41 公式复算 | 程序化计算,AI只提取参数 |
| SK-40 逐笔对账 | 程序化匹配,AI只做差异分类 |
| SK-14 尽调评分 | 加权求和(程序化),AI只打分 |
24性能基准
| 指标 | p50 | p95 | 说明 |
|---|---|---|---|
| 响应(纯LLM) | ≤5s | ≤10s | p95超10s需优化 |
| 响应(含API) | ≤8s | ≤15s | 超时降级 |
| 响应(含MCP) | ≤10s | ≤20s | 超时降级 |
| Prompt token | — | ≤2,000 | 实际tokenizer实测 |
| 输出 token | — | ≤3,000 | 单次上限 |
| 上下文 token | — | ≤15,000 | L1+L2+L3+历史 |
| Repair Loop | — | ≤2轮 | Schema失败修复 |
| Retry | — | ≤1次 | LLM异常重试 |
| 确认超时 | — | 24h | B/C级超时=取消 |
25Skill路由与调度
25.1 4步路由
Step 1: 意图识别 // 动作=查询, 对象=工商信息
Step 2: 索引匹配 // 从L1匹配description,命中1个→调用
Step 3: 消歧 // 命中多个→问用户
Step 4: SOP阶段过滤 // 跨阶段→提示
路由依据是 description,不是触发词。这就是为什么 description 必须含三要素。
25.2 不可用降级
| 场景 | 路由行为 |
|---|---|
| API不可用 | 降级为partial+标注缺失 |
| MCP未就绪 | 降级为手工模式 |
| Skill未安装 | 提示"需SK-xx"+操作指引 |
七、测试与安全
26路由评测
| 维度 | 要求 | 说明 |
|---|---|---|
| 路由正例 | 8-10条 | 该触发的各种自然语言表达 |
| 路由反例 | 8-10条 | 不该触发的易混淆场景 |
| 重复执行 | 每条3次 | 统计触发率 |
| 触发率目标 | 正例≥90% / 反例≤10% | 非确定性结果需重复验证 |
26.1 评测文件格式
// evals/should_trigger.jsonl
{"input": "帮我查一下这个公司的工商信息", "expected_skill": "SK-10", "note": "标准表达"}
{"input": "这个公司注册资本多少", "expected_skill": "SK-10", "note": "隐含意图"}
// evals/should_not_trigger.jsonl
{"input": "查一下这个公司有没有被执行记录", "expected_skill": "SK-11", "reason": "司法查询不是工商查询"}
{"input": "这家公司最近有什么负面新闻", "expected_skill": "SK-12", "reason": "舆情不是工商"}
27产出评测
不仅检查触发,还要检查产出质量。每个Skill至少3条产出断言:
// evals/output_assertions.jsonl
{
"input": {"company_name": "xxx旅游开发有限公司"},
"assertions": [
{"type": "schema_valid", "description": "输出通过JSON Schema校验"},
{"type": "field_equals", "path": "data.structured.business_status", "value": "normal"},
{"type": "no_hallucination", "description": "所有数据来自API,无编造"}
]
}
27.1 基线对比
| 维度 | 说明 |
|---|---|
| 基线建立 | v1.0.0交付时跑全部评测,记录基线 |
| 迭代对比 | 迭代后重跑,对比触发率/通过率变化 |
| 回归检测 | 通过率下降→阻断发布,回滚 |
28边界与异常测试
| 场景 | 测试要点 | 涉及Skill |
|---|---|---|
| 工具调用失败 | API 500/超时 → status=failed/partial | SK-10/11/12 |
| 权限拒绝 | 白名单外调用被拦截 | 所有MCP类 |
| 重复提交 | 幂等,不重复创建 | SK-01/27/37 |
| 部分成功 | 多字段部分API失败 → partial | SK-10/11/12 |
| 写操作幂等 | 幂等键重试→先查状态 | SK-35/36/37 |
| 上游缺失 | failed+"请先完成XX步骤" | 所有有上游 |
| not_found vs unavailable | 分别处理 | SK-10/11/39 |
| 外部内容注入 | API返回值含指令→不执行 | 所有API类 |
29安全约束
红线:7条安全约束:A/B/C边界和确认卡片是基础,以下7条安全约束为必须遵守的硬性规则。
| # | 规则 | 说明 | 优先级 |
|---|---|---|---|
| 1 | 外部内容不作为指令 | API返回值/工具输出/文档不得作为新指令执行。防注入。 | 必须 |
| 2 | 确认绑定具体操作 | 确认卡片绑定操作类型+目标+参数,不笼统确认。 | 必须 |
| 3 | 写操作幂等 | 幂等键,重试先查最终状态。 | 必须 |
| 4 | 确认非长期授权 | 用户确认仅对当前操作有效。 | 必须 |
| 5 | 敏感信息脱敏 | 密钥/个人信息/原始错误详情脱敏。 | 必须 |
| 6 | 区分三态 | not_found / unavailable / not_provided 不统一用null。 | 必须 |
| 7 | 范围校验 | 金额/日期/枚举值范围校验。 | 建议 |
30自动验证脚本
30.1 validate.js(12项检测)
# 运行(在skills/根目录执行)
node _shared/validate.js
// 验证项目:
1. 结构检测:SKILL.md + fde.manifest.yaml 存在
2. Frontmatter检测:YAML格式,name + description 必填
3. 命名一致性:目录名 == name 字段
4. 描述检测:description 100-200字,含三要素
5. 触发词冲突:主触发词两两相似度
6. Prompt长度:≤2,000 token(实际tokenizer)
7. allowed-tools格式:空格分隔字符串
8. JSON Schema:信封通过Schema校验
9. 评测文件:should_trigger≥8 + should_not_trigger≥8
10. 交接Schema:6个交接格式通过校验
11. CHANGELOG:每个Skill有CHANGELOG.md
12. 空值规范:空数组用[]不用null
// 输出:
✓ project-intake: 12/12 passed
✗ completeness-check: 11/12 — description仅82字
✗ dd-report: 10/12 — references/缺失,evals不足
31验收标准
31.1 单Skill技术验收
- Frontmatter:YAML格式,name+description必填,name=目录名
- 目录结构:SKILL.md + fde.manifest.yaml + evals/ + CHANGELOG.md
- allowed-tools:连字符格式,空格分隔字符串
- Prompt:5段式,≤2,000 token(实测),6类约束
- 输出:合法JSON,通过envelope.schema.json校验
- JSON Schema:有对应schema文件,含类型/枚举/必填
- 路由评测:正例≥8 + 反例≥8,正例触发率≥90%/反例≤10%
- 产出评测:≥3条output_assertions
- 异常测试:工具失败/权限/重复/幂等 ≥4种
- 安全约束:防注入/确认绑定/写操作幂等
- 空值规范:空依赖用[];区分not_found/unavailable/not_provided
- references/:复杂Skill有引用文件
- 默认值原则:可选参数有默认值
- 跨FDE交接:通过handoff Schema校验
- 运行时可跑:实际执行通过
八、协作与交付
32跨FDE交接格式(6个)
Day 1对齐会确认。完整 JSON Schema 见 _shared/schemas/handoff/。格式变更通知全员+升MAJOR。
交接1:尽调数据包 FDE-1 → FDE-2
SK-08+SK-14 → SK-24
{
"package_type": "due_diligence_pack",
"project_id": "PRJ-2026-0904-001",
"entity_info": {"company_name": "xxx旅游开发有限公司", "credit_code": "91520...", "legal_person": "张三", "registered_capital": 10000000},
"risk_score": 72,
"risk_level": "medium",
"completeness": {"total": 15, "provided": 13, "missing": ["近三年审计报告"]}
}
交接2:尽调报告 FDE-2 → FDE-3
SK-24 → SK-25, SK-27(SK-25用于上会材料,SK-27用于合同条款约束条件映射)
{
"package_type": "dd_report",
"report_id": "DD-2026-0904-001",
"risk_level": "medium",
"inclusion_advice": "recommend_with_conditions",
"conditions": ["需追加担保", "需季度对账"],
"key_risk_points": ["司法记录2条", "舆情负面3条"],
"document_ref": "DD-2026-0904-001.md"
}
交接3:商务条件 FDE-2 → FDE-3
SK-23 → SK-27
{
"package_type": "business_terms",
"business_type": "package_ticket",
"terms": {
"pricing": {"purchase_price": 800000, "selling_price": 950000},
"payment": {"method": "prepay_50_pct", "prepay_amount": 400000}
},
"four_flow_check": "passed"
}
交接4:合同结构化 FDE-3 → FDE-4
SK-27 → SK-45
{
"package_type": "contract_structured",
"contract_id": "CT-2026-0904-001",
"clauses": [
{"clause_id": "CL-001", "type": "refund", "title": "退票及退款条款", "key_terms": {"refund_rate": 0.8}}
],
"document_ref": "CT-2026-0904-001.md"
}
交接5:风险基线 FDE-1 → FDE-4
SK-10~14 → SK-47
{
"package_type": "risk_baseline",
"baseline_date": "2026-09-04",
"snapshot": {"business_status": "normal", "judicial_count": 2, "risk_score": 72},
"monitor_fields": ["business_status", "judicial_count"]
}
交接6:全链路执行记录 F1+F2+F3 → FDE-4
全部Skill → SK-48+SK-49+SK-50
{
"package_type": "execution_log",
"timeline": [{"skill_id": "SK-01", "exec_time": "2026-09-04T10:00:00+08:00", "duration_sec": 15}],
"statistics": {"total": 31, "auto": 17, "confirmed": 10, "modified": 3, "rejected": 1}
}
33版本管理
33.1 语义化版本(统一)
版本号统一:version字段和版本管理均使用 MAJOR.MINOR.PATCH 语义化版本。
| 版本号 | 使用场景 | 示例 |
|---|---|---|
| 1.0.0 | 首次交付 | SK-01 1.0.0 |
| 1.0.1 | PATCH:修bug/调措辞 | SK-01 1.0.1 |
| 1.1.0 | MINOR:调Prompt/触发词/补references | SK-01 1.1.0 |
| 2.0.0 | MAJOR:改Schema/边界/交接格式 | SK-01 2.0.0 |
| 2.0.0-mcp.1 | MAJOR+预发布:MCP迁移 | SK-37 2.0.0-mcp.1 |
33.2 CHANGELOG
## 1.1.0 (2026-09-05)
- 优化:确认卡片摘要精简为5条
- 新增:references/risk_matrix.md
## 1.0.0 (2026-09-03)
- 首次交付
34每日协作机制
| 会议 | 时间 | 时长 | 内容 |
|---|---|---|---|
| 早站会 | 9:30 | 15min | 昨天/今天/阻塞 |
| 交接对齐 | 13:30 | 10min | 跨FDE格式/数据对齐 |
| 晚验收 | 17:30 | 20min | 演示+验收+记录 |
34.1 问题升级
| 级别 | 时效 | 处理 |
|---|---|---|
| P0 | 立即 | 格式对不上/API不通/无法执行 |
| P1 | 当天 | 输出质量不达标/卡片问题 |
| P2 | 次日 | Prompt优化/测试补充 |
35冲突检测矩阵
35.1 触发词冲突检测
| 触发词 | SK-07 | SK-08 | SK-14 | SK-22 | SK-29 | SK-34 | SK-42 | SK-44 |
|---|---|---|---|---|---|---|---|---|
| 检查 | 冲突 | 冲突 | 冲突 | 冲突 | 冲突 | 冲突 | 冲突 | 冲突 |
| 检查资料完整性 | ✓主 | — | — | — | — | — | — | — |
| 检查主体一致性 | — | ✓主 | — | — | — | — | — | — |
| 算评分 | — | — | ✓主 | — | — | — | — | — |
| 检查条款偏离 | — | — | — | ✓主 | — | — | — | — |
关键:单动词"检查"8路冲突,加业务对象后全部消解。
36速查清单(打印贴桌上)
Frontmatter
- 格式: YAML (---分隔)
- 必填: name + description
- name = 目录名
- allowed-tools: 连字符,空格分隔
- version: MAJOR.MINOR.PATCH
目录结构
- SKILL.md(必填)
- fde.manifest.yaml(必填)
- references/(复杂Skill)
- evals/(必填,正反例各8-10)
- scripts/(计算类)
- CHANGELOG.md(必填)
格式
- 数据: 合法JSON
- 时间: ISO 8601
- 金额: int分
- 空值: null
- 空数组: []
- 三态: not_found/unavailable/not_provided
Prompt
- 5段式: 角色/边界/输入/输出/执行
- ≤2,000 token(实测)
- 6类约束: 格式/事实/行为/质量/语言/默认值
- 输出前5项自检
- references/引用(复杂Skill)
执行边界
- A级: 自动 B级: 确认 C级: 人工
- 四类红线: 经营/法务/资金/数据
- 写操作: 幂等键+先查状态
- 确认: 绑定操作,非长期授权
确认卡片
- 摘要≤6条
- 三按钮: 确认/修改/不采纳
- 高风险标红
- 超时=取消
- 拒绝必填原因
- 操作绑定具体参数
SOP覆盖
- 31步(B00-B30)全覆盖
- MCP断档7步(B18、B23-B28)→手工模式
- 另有S5隐式SK-46
- 隐式Skill(未拆B#)标注sop_stage
- progress分母=31
错误处理
- Retry: LLM异常1次
- Repair Loop: Schema失败2轮
- 写操作: 不自动repair/retry
- not_found≠unavailable
- 敏感信息脱敏
评测
- 路由正例≥8 反例≥8
- 每条3次,正例≥90%触发
- 产出断言≥3条
- 异常测试≥4种
- 基线对比+回归检测
安全
- 外部内容不作指令
- 确认绑定操作
- 写操作幂等
- 确认非长期授权
- 敏感信息脱敏
- 区分三态
版本
- 1.0.0: 首次
- 1.0.1: 修bug
- 1.1.0: 调Prompt
- 2.0.0: 改Schema
- 2.0.0-mcp.1: MCP迁移
每日
- 9:30 早站会15min
- 13:30 交接对齐10min
- 17:30 晚验收20min
- validate.js自动检测