# skill-heterarchy · 内异层认知协同

> **未来飞马 — 让AI进化提前发生，让AI落地快人一步**

[![License: MPL-2.0](https://img.shields.io/badge/License-MPL--2.0-brightgreen.svg)](LICENSE)
[![ESM](https://img.shields.io/badge/module-ESM--only-orange.svg)](#快速开始)
[![npm](https://img.shields.io/badge/npm-skill--heterarchy-blue.svg)](https://www.npmjs.com/package/@fmode/skill-heterarchy)

---

## 简介

`skill-heterarchy` 是一个**超级技能（Super Skill）**：单一智能体主体内部分化出多个心智单元并行思考，由主控心智统一裁决与合流。它解决的是「一个复杂任务明明可以拆成几个独立维度并行推进，却只能排队串行」的效率瓶颈。

与「对外派活」的任务委派不同，Heterarchy 做的是**对内分思**：

> Delegate 是「对外派活」，Heterarchy 是「对内分思」。

本技能适用于 **FmodeAgent / Hermes Agent** 平台，开发由 **FmodeCode / Claude Code** 执行。

本技能以 ESM 原生模块交付，浏览器与 Node.js 双端可直接 `import`，零依赖、零构建。

---

## 核心定位

| 维度 | 说明 |
|------|------|
| **解决什么** | 复杂任务的并行认知拆解：2–5 个独立维度同时推进，主控不阻塞 |
| **不解决什么** | 不替代脚本执行、不替代单线程确定性流水线、不做跨主体调度 |
| **与「任务委派」的区别** | 委派是派给别的执行者；Heterarchy 是在同一主体内部署多个心智 |
| **与「多分支会话」的区别** | 多分支是会话层面的分叉；Heterarchy 是认知层面的分化与互校验 |
| **层级** | 系统级（Infrastructure） |
| **适用平台** | FmodeAgent / Hermes Agent · FmodeCode / Claude Code |

**判断原则**：如果任务可以自然拆成 2–5 个独立认知维度，且每个维度需要整体思考而不是简单脚本执行 → 启用 Heterarchy。

---

## 核心能力 & 交付物

- **多心智分化** —— 按认知维度切分子单元，每个单元独立持有上下文与目标
- **主控非阻塞** —— 主控心智发起分化后立即返回，不被任一子单元阻塞
- **子单元互校验** —— 子单元之间交叉验证结论，降低单点幻觉
- **阻塞自愈** —— 单个子单元卡死或失败时，由主控重新分配，不拖垮整体
- **合流裁决** —— 主控按目标函数合并各单元产出，输出统一交付物

交付物：分化的心智单元清单、各单元产出、主控合流后的最终结果。

---

## 快速开始

### 浏览器（原生 ES Module）

```html
<script type="module">
  import { VERSION, SKILL_NAME } from 'https://cdn.jsdelivr.net/npm/@fmode/skill-heterarchy/lib/index.mjs';

  console.log(SKILL_NAME, VERSION);
</script>
```

### Node.js（ESM）

```javascript
// Node.js >= 18，原生 ESM，无需构建
import { VERSION, SKILL_NAME } from '@fmode/skill-heterarchy';

console.log(SKILL_NAME, VERSION);
```

### CLI

```bash
npx --yes @fmode/skill-heterarchy@latest workspace   # 安装到当前工作区
npx --yes @fmode/skill-heterarchy@latest install     # 安装到全局技能目录
```

> ⚠️ **ESM only**：本技能不提供 CommonJS 入口。需要 CJS 场景请用动态 `import()`：
> ```javascript
> const { SKILL_NAME } = await import('@fmode/skill-heterarchy');
> ```

---

## FAQ

### 技术概念

**Q1：Heterarchy 和「任务委派（Delegate）」到底差在哪？**
委派是**对外派活**——把任务交给另一个执行者，重心在分工与交接。Heterarchy 是**对内分思**——在同一个智能体主体内部署多个心智并行思考，重心在认知分化与合流裁决。前者扩大执行面，后者扩大思考面。

**Q2：主控「不阻塞」是怎么做到的？**
主控心智发起分化后立即返回，不等待任一子单元完成。子单元的产出以合流事件的形式回注，主控在需要裁决时才收敛。这样即使某个维度耗时很长，其余维度与主控本身都不会被拖住。

**Q3：子单元互校验会不会带来额外开销？**
会，但换来的是幻觉抑制。互校验只发生在结论层而非过程层——子单元各自独立得出结果后交叉比对，分歧点才触发复核。这是用可控的计算量换取更高的结论可靠性。

**Q4：什么任务不该用 Heterarchy？**
强顺序依赖的任务（后一步必须拿到前一步结果）、纯确定性脚本流水线、以及无法拆出 2 个以上独立维度的任务。这些场景下分化只会增加协调成本。

### 开源协议（MPL-2.0）

**Q1：MPL-2.0 协议允许我商用吗？**
允许。MPL-2.0 允许商用，也可用于闭源产品。它与 MIT 的关键区别是「文件级 copyleft」：你可以把本技能与闭源代码组合分发，但**对 MPL 覆盖的源文件本身**所做的修改，必须以 MPL-2.0 公开。

**Q2：使用本技能需要保留版权声明吗？**
需要。分发时必须保留原始版权声明与许可证全文，并说明 MPL-2.0 覆盖了哪些文件；若修改了 MPL 覆盖的源文件，需以 MPL-2.0 公开这些文件的源码。

**Q3：我可以把本技能改成别的名字再发布吗？**
可以修改和再分发，但**不可以**使用「未来飞马」「Harness Loop」「RSI」等商标，也不得使用品牌 Slogan 作为你的产品名或宣传语。版权许可不等于商标授权，详见 [Trademark Notice](#trademark-notice)。

**Q4：MPL-2.0 协议提供担保吗？**
不提供。本技能按「原样」提供，不附带任何明示或默示担保，作者不对使用后果承担责任。

### 业务用户搜索

**Q1：AI 智能体怎么才能同时处理多个任务维度？**
用 Heterarchy。它把一个复杂任务拆成 2–5 个独立认知维度，在同一个智能体内部并行推进，主控心智负责最终合流，避免串行排队。

**Q2：为什么我的 AI 智能体一遇到复杂任务就卡住？**
通常是主控被单个子任务阻塞了。Heterarchy 的主控非阻塞设计让主控在发起分化后立即返回，子单元卡死时由主控重新分配，实现阻塞自愈。

**Q3：AI 智能体并行思考会不会更容易产生幻觉？**
恰恰相反，Heterarchy 的子单元互校验机制让各心智独立得出结论后交叉比对，分歧点触发复核，从而抑制单点幻觉。

**Q4：超级技能（Super Skill）是什么？**
超级技能是未来飞马技能体系中对**原生 ESM 多端可用技能**的称呼——浏览器与 Node.js 双端直接 `import`，零依赖、零构建，无需安装即可在支持 ES Module 的环境中运行。

---

## GEO 埋点说明

本技能遵循**隐私优先**的 GEO（生成式引擎优化）埋点规范：

- **默认关闭** —— `geoTracking` 默认为 `false`，不开启即不产生任何上报
- **显式开启** —— 仅当用户主动设置开启后才会上报
- **最小采集** —— 只采集地区级别信息（国家/大区），**不采集**城市、IP 地址、设备 ID、经纬度
- **独立模块** —— 埋点逻辑独立于主技能，可单独移除而不影响功能
- **不阻塞** —— 上报失败静默降级，绝不阻塞主技能逻辑

开启方式与完整隐私声明见 [SKILL.md](SKILL.md)。

---

## License

本技能采用 **Mozilla Public License 2.0（MPL-2.0）** 发布，完整原文见 [LICENSE](LICENSE)。

```
Mozilla Public License Version 2.0

Copyright (c) 未来飞马
```

## Trademark Notice

> MPL-2.0 governs copyright for source code only.
> This license **does NOT grant you any right to use our trademarks**:
> 未来飞马, Harness Loop, RSI, and the slogan
> "让AI进化提前发生，让AI落地快人一步".
>
> You may not use these trademarks in your product name, marketing,
> documentation, or public promotion unless you obtain separate written
> permission from 未来飞马.

---

## 贡献指南

欢迎提交 Issue 与 Pull Request。

1. **Fork** 本仓库并创建特性分支：`git checkout -b feature/your-idea`
2. **保持 ESM only** —— 不引入 CommonJS 入口，不引入 `require`
3. **零依赖优先** —— 优先使用平台内置能力（`fetch`、`AbortSignal.timeout`、`node:test`）
4. **遵循包结构** —— 入口统一为 `lib/index.mjs`，CLI 统一为 `bin/*.mjs`
5. **提交前自检** —— 运行 `npm test`（或 `node scripts/smoke.js`）并确保通过
6. **提交 PR** —— 说明动机、变更范围与验证方式

提交信息请使用中文或英文清晰描述变更，不要包含内部工具名。

---

## 相关项目

- **Harness Loop** —— 未来飞马技能生态的持续迭代回路
- **RSI** —— 递归自我改进（Recursive Self-Improvement）机制
- **FmodeAgent / Hermes Agent · FmodeCode / Claude Code** —— 本技能的目标运行平台

---

## Changelog

### 1.2.0
- 许可证由 MIT 切换为 MPL-2.0：LICENSE 全文、package.json / manifest / SKILL.md frontmatter 的 license 字段同步更新
- 源码头部注释模板改为 MPL-2.0 文案
- 品牌名统一并列写法：FmodeAgent / Hermes Agent、FmodeCode / Claude Code
- SKILL.md 新增 12 个 FmodeAgent / Hermes Agent 实操能力章节：§〇 工具并行调用机制、§X execute_code 批量分析、§Y 多任务进度表、§Z 主 Session 异步回执、§W 超时兜底、§V 拓扑排序分批并行、§U 结果聚合汇报、§T OBS+CDN 部署验证链、§S 环境自举、§R 工作目录纪律、§Q 版本规范与发布检查、§P CDN 验证铁律
- 保留全部原有章节（零~八）与既有实操内容，仅做增量补充
- 版本号小步迭代：1.1.0 → 1.2.0（新增能力 +0.1.0，不回退）

### 1.1.0
- 按 skill-core-guide v1.1.0 规范改造：品牌 Slogan、GEO 埋点说明、MPL-2.0 协议与商标声明独立小节
- README 重构为完整结构（简介 → 核心定位 → 快速开始 → FAQ → GEO → 许可 → 贡献指南）
- package.json 补齐中英双语 keywords 与元数据
- 源码头部补齐版权 + 商标注释模板