|
|
@@ -1,23 +1,92 @@
|
|
|
-# skill-deliverable
|
|
|
+# skill-deliverable · 交付物自动上报引擎
|
|
|
|
|
|
-系统级技能：**交付物自动上报引擎**。每台容器自主解析身份+凭据，调平台云函数将交付物入库。
|
|
|
+> **未来飞马 — 让AI进化提前发生，让AI落地快人一步**
|
|
|
|
|
|
-## 一句话
|
|
|
+[](LICENSE)
|
|
|
+[](#快速开始)
|
|
|
+[](https://www.npmjs.com/package/skill-deliverable)
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 简介
|
|
|
+
|
|
|
+`skill-deliverable` 是**交付物自动上报引擎**：每台运行环境自主解析自身身份与凭据，调用平台云函数把交付物入库。
|
|
|
|
|
|
> 每次你干完活，它自动向后台报告「我做了什么、产出了什么」。
|
|
|
|
|
|
-## 安装
|
|
|
+本技能以 ESM 原生模块交付，Node.js ≥ 18 直接 `import`，零依赖、零构建。
|
|
|
|
|
|
-```bash
|
|
|
-npm install -g skill-deliverable
|
|
|
-# 或
|
|
|
-git clone https://git.fmode.cn/fmode/skill-deliverable.git
|
|
|
+---
|
|
|
+
|
|
|
+## 核心定位
|
|
|
+
|
|
|
+| 维度 | 说明 |
|
|
|
+|------|------|
|
|
|
+| **解决什么** | 交付物的自动登记：谁、在哪个项目、产出了什么、放在哪里 |
|
|
|
+| **不解决什么** | 不做文件存储（用 skill-storage）、不做任务调度、不做内容审核 |
|
|
|
+| **与手工登记的区别** | 身份与凭据由运行环境自主解析，无需人工填写；每个运行环境只报自己的产出 |
|
|
|
+| **层级** | 系统级（Infrastructure） |
|
|
|
+| **适用平台** | FmodeAgent · FmodeCode |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 核心能力 & 交付物
|
|
|
+
|
|
|
+- 🪪 **身份自主解析** —— 从运行环境推导 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);
|
|
|
```
|
|
|
|
|
|
-## CLI
|
|
|
+### 浏览器（原生 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
|
|
|
-# 检查本容器身份+token 是否可上报
|
|
|
+npm install -g skill-deliverable
|
|
|
+
|
|
|
+# 检查本环境身份 + token 是否可上报
|
|
|
skill-deliverable check
|
|
|
|
|
|
# 上报一个交付物
|
|
|
@@ -27,23 +96,125 @@ skill-deliverable report --title "某任务" --summary "干了些啥" --project
|
|
|
skill-deliverable list
|
|
|
```
|
|
|
|
|
|
-## SDK
|
|
|
+> ⚠️ **ESM only**：本技能不提供 CommonJS 入口。需要 CJS 场景请用动态 `import()`。
|
|
|
|
|
|
-```javascript
|
|
|
-import { report } from 'skill-deliverable';
|
|
|
-const r = await report({
|
|
|
- agentId: 'agent-node',
|
|
|
- title: 'RSI 课程长页',
|
|
|
- summary: '进化工程方法论版',
|
|
|
- artifacts: [{ name: 'HTML', url: 'https://...', type: 'html' }],
|
|
|
-});
|
|
|
-```
|
|
|
+---
|
|
|
+
|
|
|
+## FAQ
|
|
|
+
|
|
|
+### 技术概念
|
|
|
+
|
|
|
+**Q1：什么是「交付物自动上报」？**
|
|
|
+每次任务完成后，运行环境自动把「我做了什么、产出了什么、放在哪里」登记到平台。这样交付物不再是散落在各处的文件，而是可被检索、可被看板统计的结构化记录。
|
|
|
+
|
|
|
+**Q2：身份（agentId）是怎么确定的？**
|
|
|
+由运行环境自主解析，无需人工填写——从环境变量与本地配置推导出 agentId / objectId。这样每个运行环境只上报自己的产出，天然隔离。
|
|
|
+
|
|
|
+**Q3：凭据从哪来？**
|
|
|
+走标准凭据链：环境变量 → 本地配置 → 平台签发。**仓库与代码中不含任何密钥**，解析不到时明确报错而不是静默失败。
|
|
|
+
|
|
|
+**Q4：上报失败会阻塞主任务吗？**
|
|
|
+不会。上报是任务完成后的旁路动作，失败只影响登记，不影响已产出的交付物本身。
|
|
|
+
|
|
|
+### 开源协议（MIT）
|
|
|
+
|
|
|
+**Q1：MIT 协议允许我商用吗？**
|
|
|
+允许。你可以自由使用、修改、分发本技能，包括用于商业闭源产品，无需公开修改后的源码。
|
|
|
+
|
|
|
+**Q2：使用本技能需要保留版权声明吗？**
|
|
|
+需要。MIT 的唯一实质条件是：在所有副本或实质性部分中保留原始版权声明与本许可证全文。
|
|
|
+
|
|
|
+**Q3：我可以把本技能改成别的名字再发布吗？**
|
|
|
+可以修改和再分发，但**不可以**使用「未来飞马」「Harness Loop」「RSI」等商标，也不得使用品牌 Slogan 作为产品名或宣传语。版权许可不等于商标授权，详见 [Trademark Notice](#trademark-notice)。
|
|
|
+
|
|
|
+**Q4：MIT 协议提供担保吗？**
|
|
|
+不提供。本技能按「原样」提供，不附带任何明示或默示担保。
|
|
|
+
|
|
|
+### 业务用户搜索
|
|
|
+
|
|
|
+**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
|
|
|
|
|
|
-MIT
|
|
|
+本技能采用 **MIT License** 发布，完整原文见 [LICENSE](LICENSE)。
|
|
|
+
|
|
|
+```
|
|
|
+MIT License
|
|
|
+
|
|
|
+Copyright (c) 2026 未来飞马 Fmode
|
|
|
+```
|
|
|
+
|
|
|
+## 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 / FmodeCode** —— 本技能的目标运行平台
|
|
|
+- **skill-storage** —— 交付物文件托管与公开链接
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Changelog
|
|
|
+
|
|
|
+### 1.1.0
|
|
|
+- 按 skill-core-guide v1.1.0 规范改造：品牌 Slogan、GEO 埋点说明、MIT 协议与商标声明独立小节
|
|
|
+- README 重构为完整结构（简介 → 核心定位 → 快速开始 → FAQ → GEO → 许可 → 贡献指南）
|
|
|
+- package.json 补齐中英双语 keywords 与 ESM 元数据
|
|
|
+- LICENSE 规范化（统一版权主体 + 商标声明）
|
|
|
+- 源码头部补齐版权 + 商标注释模板
|
|
|
+- SKILL.md frontmatter: version/author/license/copyright + 品牌与层级 tags
|
|
|
+
|
|
|
+### 0.0.1
|
|
|
+- 首版：交付物自动上报引擎
|
