# skill-deliverable · 交付物自动上报引擎

> **未来飞马 — 让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--deliverable-blue.svg)](https://www.npmjs.com/package/skill-deliverable)

---

## 简介

`skill-deliverable` 是**交付物自动上报引擎**：每台运行环境自主解析自身身份与凭据，调用平台云函数把交付物入库。

> 每次你干完活，它自动向后台报告「我做了什么、产出了什么」。

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

本技能以 ESM 原生模块交付，Node.js ≥ 18 直接 `import`，零依赖、零构建。

---

## 核心定位

| 维度 | 说明 |
|------|------|
| **解决什么** | 交付物的自动登记：谁、在哪个项目、产出了什么、放在哪里 |
| **不解决什么** | 不做文件存储（用 skill-storage）、不做任务调度、不做内容审核 |
| **与手工登记的区别** | 身份与凭据由运行环境自主解析，无需人工填写；每个运行环境只报自己的产出 |
| **层级** | 系统级（Infrastructure） |
| **适用平台** | FmodeAgent / Hermes Agent · FmodeCode / Claude Code |

---

## 核心能力 & 交付物

- 🪪 **身份自主解析** —— 从运行环境推导 agentId / objectId
- 🔑 **凭据自主解析** —— 标准凭据链，无需人工配置
- ☁️ **云函数入库** —— 调平台云函数写入交付物记录
- 🧾 **交付物结构化** —— 标题、摘要、项目、附件（名称/URL/类型）、标签
- 🔍 **本地自检与回看** —— `check` 验证可上报性，`list` 查看近期记录

交付物：结构化的交付物记录（入库后可被平台检索与看板消费）。

---

## 快速开始

### Node.js（ESM）

```javascript
import { report, resolveAgentId } from 'skill-deliverable';

console.log(resolveAgentId());   // 先确认身份解析成功

const r = await report({
  agentId: 'agent-node',
  title: 'RSI 课程长页',
  summary: '进化工程方法论版',
  artifacts: [{ name: 'HTML', url: 'https://s3.fmode.cn/user/xxx/report.html', type: 'html' }],
});
console.log(r);
```

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

```html
<script type="module">
  // 浏览器端：调用平台云函数上报交付物
  const resp = await fetch('https://server.fmode.cn/api/deliverable/report', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${window.FMODE_TOKEN}`,
    },
    body: JSON.stringify({
      title: '页面端交付物',
      summary: '浏览器内产出',
      artifacts: [{ name: 'Page', url: location.href, type: 'html' }],
    }),
  });
  console.log(await resp.json());
</script>
```

### CLI

```bash
npm install -g skill-deliverable

# 检查本环境身份 + token 是否可上报
skill-deliverable check

# 上报一个交付物
skill-deliverable report --title "某任务" --summary "干了些啥" --project "项目名"

# 查看近期上报
skill-deliverable list
```

> ⚠️ **ESM only**：本技能不提供 CommonJS 入口。需要 CJS 场景请用动态 `import()`。

---

## FAQ

### 技术概念

**Q1：什么是「交付物自动上报」？**
每次任务完成后，运行环境自动把「我做了什么、产出了什么、放在哪里」登记到平台。这样交付物不再是散落在各处的文件，而是可被检索、可被看板统计的结构化记录。

**Q2：身份（agentId）是怎么确定的？**
由运行环境自主解析，无需人工填写——从环境变量与本地配置推导出 agentId / objectId。这样每个运行环境只上报自己的产出，天然隔离。

**Q3：凭据从哪来？**
走标准凭据链：环境变量 → 本地配置 → 平台签发。**仓库与代码中不含任何密钥**，解析不到时明确报错而不是静默失败。

**Q4：上报失败会阻塞主任务吗？**
不会。上报是任务完成后的旁路动作，失败只影响登记，不影响已产出的交付物本身。

### 开源协议（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 每次产出了什么？**
用 skill-deliverable。任务完成后自动把标题、摘要、项目与附件链接登记到平台，无需人工填写台账。

**Q2：多个运行环境的产出会不会互相覆盖？**
不会。每个运行环境自主解析自己的身份，只上报自己的产出，记录天然隔离。

**Q3：交付物记录能查到历史吗？**
能。`list` 命令可查看近期上报记录，平台侧也可按项目与标签检索。

**Q4：上报需要额外配置吗？**
通常不需要。身份与凭据都由运行环境自主解析；解析不到时会明确提示缺什么。

---

## GEO 埋点说明

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

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

---

## 文档

- [`SKILL.md`](SKILL.md) — 完整技能规范
- [`docs/deployment-guide.md`](docs/deployment-guide.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 未来飞马.

---

## 贡献指南

1. **Fork** 本仓库并创建特性分支：`git checkout -b feature/your-idea`
2. **保持 ESM only** —— 不引入 CommonJS 入口，不引入 `require`
3. **凭据纪律** —— 任何情况下不得在仓库、Issue、PR 中写入真实密钥
4. **提交 PR** —— 说明动机、变更范围与验证方式

---

## 相关项目

- **Harness Loop** —— 未来飞马技能生态的持续迭代回路
- **RSI** —— 递归自我改进（Recursive Self-Improvement）机制
- **FmodeAgent / Hermes Agent · FmodeCode / Claude Code** —— 本技能的目标运行平台
- **skill-storage** —— 交付物文件托管与公开链接

---

## Changelog

### 1.2.0
- 许可证由 MIT 切换为 MPL-2.0：LICENSE 全文、package.json / manifest / plugin.json / SKILL.md frontmatter 的 license 字段同步更新
- 源码头部注释模板改为 MPL-2.0 文案
- 品牌名统一并列写法：FmodeAgent / Hermes Agent、FmodeCode / Claude Code

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

### 0.0.1
- 首版：交付物自动上报引擎