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必填stringkebab-case,必须与父目录名完全一致。如 project-intake
description必填string100-200字,三要素:做什么+何时触发+不做什么。AI路由Skill的主要依据(配合triggers、sop_stage等辅助字段)。
allowed-tools可选string空格分隔的工具名。实验特性,客户端支持程度不同。
compatibility可选string环境依赖声明。值需加引号。如 "requires: asr-service>=1.0; network: yes"
version可选stringFDE扩展字段(非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.mdAgent Skills 可移植层YAML frontmatter + Markdown body(Prompt指令)。只放与平台无关的Skill指令。
fde.manifest.yamlFDE 业务注册层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: "" # 或省略此字段
Skillallowed-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 tokenSK-03/04/06/10
中等型(生成/检查/计算)≤1,200 tokenSK-05/07/22/27
复杂型(报告/合同/对账)≤2,000 tokenSK-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 tokenSchema限制≤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-08SK-07管"有没有",SK-08管"对不对"
SK-24 vs SK-25SK-24是尽调结论,SK-25引用不重复生成
SK-43 vs SK-44SK-43算账,SK-44开票,依赖SK-43

15.2 职责矩阵

业务动作主责不可越界
建档/录入项目SK-01其他不可自动建档
评估风险等级SK-14SK-24引用SK-14
生成合同初稿SK-27SK-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业务类型识别→自动加载对应SOPSK-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生成异常failedRetry 1次(温度降0.3)1次
MCP工具不可用failed切换手工模式否
用户拒绝确认cancelled保存草稿,不触发下游否
工具返回not_foundpartial"查了没有"≠"查询失败"否
权限拒绝failed"无权限"+所需权限否
红线:写操作不自动重试:涉及资金/合同/商品写操作失败不自动重试,必须人工确认后手动重试。使用幂等键,先查最终状态。
20Repair Loop

20.1 Repair Loop vs 重试(语义区分)

语义区分:Repair Loop 和 Retry 是两个独立机制,分别针对 Schema校验失败 和 LLM生成异常:
机制次数触发条件说明
Retry1次LLM生成异常/超时同样Prompt再来一次,温度降0.3。不改Prompt。
Repair Loop2轮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,00050个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性能基准
指标p50p95说明
响应(纯LLM)≤5s≤10sp95超10s需优化
响应(含API)≤8s≤15s超时降级
响应(含MCP)≤10s≤20s超时降级
Prompt token—≤2,000实际tokenizer实测
输出 token—≤3,000单次上限
上下文 token—≤15,000L1+L2+L3+历史
Repair Loop—≤2轮Schema失败修复
Retry—≤1次LLM异常重试
确认超时—24hB/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/partialSK-10/11/12
权限拒绝白名单外调用被拦截所有MCP类
重复提交幂等,不重复创建SK-01/27/37
部分成功多字段部分API失败 → partialSK-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.1PATCH:修bug/调措辞SK-01 1.0.1
1.1.0MINOR:调Prompt/触发词/补referencesSK-01 1.1.0
2.0.0MAJOR:改Schema/边界/交接格式SK-01 2.0.0
2.0.0-mcp.1MAJOR+预发布: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:3015min昨天/今天/阻塞
交接对齐13:3010min跨FDE格式/数据对齐
晚验收17:3020min演示+验收+记录

34.1 问题升级

级别时效处理
P0立即格式对不上/API不通/无法执行
P1当天输出质量不达标/卡片问题
P2次日Prompt优化/测试补充
35冲突检测矩阵

35.1 触发词冲突检测

触发词SK-07SK-08SK-14SK-22SK-29SK-34SK-42SK-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自动检测