feat(monitor): 抖音 Web 接口客户端 —— 绕开爬虫子进程，直接发 HTTP
移植自 mac-agent-os 的 mediacrawler_adapter：不起子进程、不开页面，用浏览器里那份
登录态直接调抖音 Web 接口。产物键名照抄 store/douyin，所以 ingest 那条链路一个字不用改。
**目前能用的（真环境实测，非推断）**：
profile/other : 200, 7075 字节 —— 博主主页指标（粉丝/获赞/作品数/昵称）
aweme/detail : 200, 45425 字节 —— 单条作品详情（含点赞/评论/收藏/分享）
**目前不能用的：作品列表 `aweme/post`。** 两个互相独立的原因：
1. 这个接口被抖音单独升级成了真校验：不带 x-tt-argus 回 403「Uifid Not Found」，
带上 dummy 值回 200 + **空 body**。也就是说「头在不在」骗得过，「真校验」过不了。
同一套头打 profile/other 和 aweme/detail 都是通的 —— 抖音是挑着接口加保护的，
挑中的恰好是「批量拉作品列表」这个最敏感的动作。
2. 改走页面截获也不行：CDP 浏览器打开博主主页会落到「验证码中间页」（当天大量探测的
代价，过几小时要重测）。
所以现在的边界是：**已知作品的指标刷新能做，自动发现新作品做不了**。
**排查中控住变量后得到的两条事实**（都写进注释了）：
· `Accept` / `Accept-Language` / `Referer` 才是主页接口能返回真数据的原因 —— 只有
UA+client hints+Cookie 时是 200 但仅 121 字节的空壳，补上这三个头变 7074 字节。
（我先前猜的 sec-ch-ua 不是关键。）
· 因此 UA 与 client hints 必须**成套地取自同一个浏览器**，所以 BrowserIdentity 一次
从 CDP 取齐 cookie + UA + hints，而不是各自写死。
「200 + 空 body 必须当场报错」也是刻意写死的：放过去它会在下游变成「这个博主没作品」，
把一次失败伪装成一条正常结果 —— 爬虫那条路正是这么栽的，还被翻译成「账号被封」。
测试 +11：cookie 解析、请求头成套性（含 uifid 缺失/回退）、产物键名与 store 对齐、
以及 _get 的三条失败路径（空 body / 403 带网关原话 / 正常返回）。
This commit is contained in:
@@ -0,0 +1,133 @@
|
||||
Read [](file:///Users/chengzige/agent-os/agent-sync/%E6%88%91%E7%9A%84%E8%AF%B4%E6%98%8E.md#1-1), lines 1 to 80
|
||||
|
||||
Read [](file:///Users/chengzige/agent-os/agent-sync/%E6%88%91%E7%9A%84%E8%AF%B4%E6%98%8E.md#81-81), lines 81 to 200
|
||||
|
||||
Read [](file:///Users/chengzige/agent-os/agent-sync/%E6%88%91%E7%9A%84%E8%AF%B4%E6%98%8E.md#201-201), lines 201 to 391
|
||||
|
||||
Read [](file:///Users/chengzige/agent-os/agent-sync/AgentOS-%E5%AE%8C%E6%95%B4%E8%AF%B4%E6%98%8E%E6%96%87%E6%A1%A3_%E5%89%AF%E6%9C%AC.md)
|
||||
|
||||
Read [](file:///Users/chengzige/agent-os/agent-sync/AgentOS-%E5%AE%8C%E6%95%B4%E8%AF%B4%E6%98%8E%E6%96%87%E6%A1%A3_%E5%89%AF%E6%9C%AC.md#31-31), lines 31 to 31
|
||||
|
||||
已完整读取你的《我的说明.md》和项目原历史说明文档，并结合你前述需求，现为你梳理出结构化的顶层大框架，并将你的关键想法单独标记，便于后续细化和追踪。
|
||||
|
||||
---
|
||||
|
||||
# AgentOS 顶层结构化大框架（多机协同·知识自进化）
|
||||
|
||||
## 1. agent-os（全局/多机共用内容）
|
||||
|
||||
### 1.1 初始化脚本（00_bootstrap）
|
||||
- 作用：一键环境搭建、依赖安装、权限配置、自动任务注册、主机身份识别与切换。
|
||||
- 你的重点：支持从零还原、主机身份切换、任务启停自动化。
|
||||
|
||||
### 1.2 核心配置（01_core）
|
||||
- 作用：系统身份、主机/维护机标识、全局参数、智能体基础设定。
|
||||
- 你的重点：支持多智能体、多主机角色，配置可多版本选择加载。
|
||||
|
||||
### 1.3 技能（02_skills）
|
||||
- 作用：系统必需技能、自定义技能、第三方技能，均有“技能身份证”（SKILL_CARD.yaml）。
|
||||
- 你的重点：
|
||||
- 技能身份证模板统一，主机归属、只读/主理标识。
|
||||
- 技能状态一键扫描（skill_scanner.py）。
|
||||
- 外部技能与自研技能分层管理。
|
||||
|
||||
### 1.4 知识库（03_knowledge）
|
||||
- 作用：全局知识库，支持多属性、多领域、版本化、向量化、自动分类。
|
||||
- 你的重点：
|
||||
- 分类体系：知识/个人笔记/记忆固化/项目过程/向量化/收件箱等。
|
||||
- 支持原始-已整理-归档多阶段。
|
||||
- 领域16大类，属性9大类，Frontmatter标准化。
|
||||
- 项目过程与知识归档分离，最终成果可转为事实/知识。
|
||||
- 向量库既有本地也有全局，支持多机同步与本地独立。
|
||||
|
||||
### 1.5 工具层（05_tools）
|
||||
- 作用：非技能化工具脚本（CLI/接口），如知识库/记忆/技能管理等。
|
||||
- 你的重点：工具与技能可互转，工具更注重效率和扩展性，技能偏自动化和系统集成。
|
||||
|
||||
### 1.6 系统管理（07_migration/90_archive）
|
||||
- 作用：打包、解包、迁移、备份、归档、历史记录。
|
||||
|
||||
---
|
||||
|
||||
## 2. agent-os-local（本机专属内容）
|
||||
|
||||
### 2.1 采集原始内容
|
||||
- 作用：本机原始数据采集（音频、视频、网页、截图、临时笔记等），作为知识库前端缓存。
|
||||
- 你的重点：每台机子独立采集，后续可分类同步到全局知识库。
|
||||
|
||||
### 2.2 本机记忆
|
||||
- 作用：本机专属记忆，部分可提炼为全局知识。
|
||||
- 你的重点：记忆属性字段丰富，向量化内容区分本地/全局，提炼机制需智能判断。
|
||||
|
||||
### 2.3 运行记录、对话记录、缓存
|
||||
- 作用：任务缓存、运行日志、对话历史，适配不同智能体。
|
||||
- 你的重点：智能体可切换，数据结构需适配不同上下文和对话格式。
|
||||
|
||||
### 2.4 本机情况数据说明记录
|
||||
- 作用：本机环境、硬件、软件、网络、环境变量等说明，支持动态更新。
|
||||
- 你的重点：数据结构需高效、节省token，支持自动/手动更新。
|
||||
|
||||
---
|
||||
|
||||
## 3. 关键机制与待展开问题（你的重点/待讨论）
|
||||
|
||||
- 向量库（vector_db）：本地与全局并存，需支持多机同步与本地独立，知识内容与索引分离/融合待定。
|
||||
- 主机/维护机标识：每台主机唯一ID，主维护机角色固定，权限与同步策略需细化。
|
||||
- 知识库分类：支持多级分类、标签，分类体系需灵活可扩展。
|
||||
- 工具与技能边界：工具注重效率和扩展，技能偏自动化和系统集成，二者可互转，需明确转换机制。
|
||||
- 本机数据说明：内容范围、更新机制、token效率需进一步细化。
|
||||
- 同步/备份机制：全局与本地的同步策略、备份粒度、冲突解决等需后续详细设计。
|
||||
|
||||
---
|
||||
|
||||
# 标记你的关键内容（便于后续追踪）
|
||||
|
||||
1. 技能身份证（SKILL_CARD.yaml）机制与模板
|
||||
2. 技能状态扫描工具（skill_scanner.py）
|
||||
3. 知识库多层级分类体系（16领域×9属性）
|
||||
4. 向量库本地/全局双轨设计
|
||||
5. 本机记忆与全局知识的提炼与同步机制
|
||||
6. 工具与技能的互转与边界
|
||||
7. 本机环境说明的高效结构与动态更新
|
||||
8. 多机主机/维护机角色与权限体系
|
||||
9. 项目过程与知识归档的分离与融合
|
||||
10. 自动化任务与定时调度体系
|
||||
|
||||
---
|
||||
|
||||
# 【2026-04-28 最新讨论补充】本地/全局记忆与知识库、向量库、同步机制设计
|
||||
|
||||
## 1. 目录与同步边界
|
||||
- `~/workbuddy-agent-os/agent-sync/`：所有内容都参与多机同步（知识库、协同收件箱、协同向量库等）。
|
||||
- `~/workbuddy-agent-os/agent-sync/agent-local/`：所有内容仅本机保存，绝不参与同步（本地记忆、个人笔记、本地素材等）。
|
||||
|
||||
## 2. 数据流转与提炼机制
|
||||
1. **本地记忆/个人笔记产生**
|
||||
- 存在于 `~/workbuddy-agent-os/agent-sync/agent-local/materials/`，如记忆系统自动提存、个人随手笔记等。
|
||||
2. **记忆/笔记提炼**
|
||||
- 用户可手动或自动将有价值的内容，从 `~/workbuddy-agent-os/agent-sync/agent-local/materials/` 提取到 `~/workbuddy-agent-os/agent-sync/03_knowledge/00_inbox/`（协同收件箱）。
|
||||
- 提取时可加属性（如“记忆”标签），以便后续分类。
|
||||
3. **知识库入库**
|
||||
- 协同收件箱只存 md 文件，知识管理系统定期/手动将内容加工、分类，正式入库到知识库（如 10_concepts、20_methods 等）。
|
||||
|
||||
## 3. 向量数据库设计
|
||||
- **本地向量库**：`~/workbuddy-agent-os/agent-sync/agent-local/` 下的所有内容（记忆、个人笔记等）向量化，仅本机检索。
|
||||
- **协同向量库**：`~/workbuddy-agent-os/agent-sync/` 下知识库内容向量化，参与多机同步和协同检索。
|
||||
- 检索时，默认先查本地向量库，再查协同向量库，结果合并展示，体验无割裂。
|
||||
|
||||
## 4. 分类与属性
|
||||
- 协同收件箱和知识库的 md 文件可通过 frontmatter 或标签标明来源（如“记忆提存”、“个人笔记”），方便后续分类和检索。
|
||||
- 知识库分类可灵活调整，不必强依赖文件名。
|
||||
|
||||
## 5. 机制总结
|
||||
- 本地内容完全隔离，隐私安全。
|
||||
- 有价值内容通过“提炼-收件箱-知识库”机制流转，保证协同知识的高质量和结构化。
|
||||
- 多机协同时，检索体验顺畅，既能查本地记忆，也能查全局知识。
|
||||
|
||||
---
|
||||
> 本节为 2026-04-28 讨论结论，后续如有新机制/细节调整请在此基础上补充。
|
||||
|
||||
---
|
||||
|
||||
如需展开某一部分（如知识库分类、向量库机制、同步策略等），可随时指定，我会基于你的原文和上述结构继续细化。
|
||||
如需将这些“你的关键内容”单独存档，或生成专门的追踪清单，也可直接说明。
|
||||
@@ -0,0 +1,314 @@
|
||||
# AgentOS vNext 重构规划与工作计划
|
||||
|
||||
> 版本：2026-04-29（第一稿，待审核）
|
||||
> 状态：**【待审核】** — 请确认目录结构与工作计划后再进入实施阶段
|
||||
|
||||
---
|
||||
|
||||
## 一、工作核心要点（实施前必读）
|
||||
|
||||
### 程序功能定位
|
||||
|
||||
| 模块 | 功能 | 说明 |
|
||||
|------|------|------|
|
||||
| `memory_manager` | 记忆提炼与固化 | 从对话日志/WorkBuddy记忆中提炼关键事实，生成L1/L2/L3分层记忆，并检测固化条件推送inbox/memory |
|
||||
| `kb_manager` | 知识入库 | 接受inbox各分区内容，分类、填写frontmatter、写入知识库对应目录 |
|
||||
| `inbox_refine` | 收件箱精炼 | 扫描inbox各分区，调用LLM分类，自动归档到知识库 |
|
||||
| `collect_to_inbox` | 内容采集推送 | 扫描本地素材/记忆，精炼后推送到协同inbox对应分区 |
|
||||
| `auto_collector` | 自动化采集 | 定时抓取外部信息（网页/RSS/社交媒体等），推送inbox/knowledge |
|
||||
| `sync_manager` | 同步管理 | 管理agent-os多机git同步，冲突检测与解决 |
|
||||
| `skill_scanner` | 技能状态扫描 | 扫描所有SKILL_CARD.yaml，报告哪些技能就绪/缺依赖 |
|
||||
| `vector_db` | 双轨向量库 | local向量库（私有内容）+ global向量库（协同知识），检索时合并 |
|
||||
|
||||
### 核心数据流
|
||||
|
||||
```
|
||||
本机采集（raw素材）
|
||||
↓ collect_to_inbox / 用户手动提炼
|
||||
agent-os-local/materials/refined_for_inbox/
|
||||
↓ 用户确认/AI判断固化条件
|
||||
agent-sync/03_knowledge/00_stream/inbox/
|
||||
├── knowledge/ ← 外部知识采集
|
||||
├── memory/ ← 记忆固化内容
|
||||
├── tools/ ← 工具提交
|
||||
├── personal/ ← 个人笔记
|
||||
└── media/ ← 轻量媒体
|
||||
↓ inbox_refine / kb_manager（AI自动分类）
|
||||
agent-sync/03_knowledge/[10~60_xxx]/
|
||||
↓ 每台机器自动重建
|
||||
agent-os-local/vector_db/global/ ← 协同知识向量化
|
||||
agent-os-local/vector_db/local/ ← 私有内容向量化
|
||||
↓ 检索时合并（先local后global）
|
||||
用户查询响应
|
||||
```
|
||||
|
||||
### 实施三原则
|
||||
|
||||
1. **不破坏现有功能** — 重命名/移动目录前做好兼容或路径别名处理
|
||||
2. **协同目录轻量化** — 大文件/向量库/本机专属内容绝不进入agent-os/
|
||||
3. **渐进实施** — 先目录结构，再配置文件，最后代码完善
|
||||
|
||||
---
|
||||
|
||||
## 二、新目录结构（【待审核】）
|
||||
|
||||
### 2.1 agent-os/ 变更说明
|
||||
|
||||
```
|
||||
agent-os/
|
||||
├── 00_bootstrap/ # 【保留】初始化脚本
|
||||
│ ├── init.sh # 主安装入口（后续增加HOST_ID读取逻辑）
|
||||
│ ├── apply-config.sh
|
||||
│ ├── export_skills.sh
|
||||
│ └── import_skills.sh
|
||||
│
|
||||
├── 01_core/ # 【扩展】核心配置
|
||||
│ ├── IDENTITY.md # 系统身份
|
||||
│ ├── SOUL.md # 智能体灵魂设定
|
||||
│ ├── USER.md # 用户画像
|
||||
│ ├── mcp.json # MCP配置
|
||||
│ ├── CHANGELOG.md
|
||||
│ └── HOST_ID.md # 【新增★】本机标识与角色
|
||||
│ # 格式：my-macbook_macOS14.4_16GB_master
|
||||
│
|
||||
├── 02_skills/ # 【扩展】技能库
|
||||
│ ├── _template/ # 技能模板（含SKILL_CARD.yaml模板）
|
||||
│ ├── memory_manager/ # 【扩展】记忆管理
|
||||
│ │ ├── SKILL.md
|
||||
│ │ ├── SKILL_CARD.yaml # 【新增★】技能身份证
|
||||
│ │ ├── daily_digest.py # 每日提炼
|
||||
│ │ ├── memory_extractor.py # 【新增★】记忆固化提取（推送inbox）
|
||||
│ │ ├── bootstrap_from_memory.py
|
||||
│ │ ├── agent_memory_init.py
|
||||
│ │ ├── export_memories.py
|
||||
│ │ ├── import_memories.py
|
||||
│ │ ├── memory_cleanup.py
|
||||
│ │ ├── semantic_search.py
|
||||
│ │ └── version.json
|
||||
│ ├── kb_manager/ # 【扩展】知识库管理
|
||||
│ │ ├── SKILL.md
|
||||
│ │ ├── SKILL_CARD.yaml # 【新增★】技能身份证
|
||||
│ │ ├── kb_ingest.py # 知识入库（更新inbox路径适配）
|
||||
│ │ ├── kb_search.py # 【新增★】知识检索（双轨向量）
|
||||
│ │ └── version.json
|
||||
│ ├── inbox_refine/ # 【扩展】收件箱精炼
|
||||
│ │ ├── SKILL.md
|
||||
│ │ ├── SKILL_CARD.yaml # 【新增★】技能身份证
|
||||
│ │ ├── inbox_refine.py # 精炼主程序（更新多分区支持）
|
||||
│ │ ├── llm_classifier.py
|
||||
│ │ └── version.json
|
||||
│ ├── collect_to_inbox/ # 【扩展】采集推送
|
||||
│ │ ├── SKILL.md
|
||||
│ │ ├── SKILL_CARD.yaml # 【新增★】技能身份证
|
||||
│ │ ├── collect_to_inbox.py # 采集推送（更新本地素材路径）
|
||||
│ │ └── version.json
|
||||
│ ├── auto_collector/ # 【扩展】自动采集
|
||||
│ │ ├── SKILL.md
|
||||
│ │ ├── SKILL_CARD.yaml # 【新增★】技能身份证
|
||||
│ │ └── version.json
|
||||
│ ├── sync_manager/ # 【扩展】同步管理
|
||||
│ │ ├── SKILL.md
|
||||
│ │ ├── SKILL_CARD.yaml # 【新增★】技能身份证
|
||||
│ │ └── version.json
|
||||
│ ├── web_crawler/ # 【保留】网页爬取
|
||||
│ │ └── SKILL.md
|
||||
│ └── content_processor/ # 【保留】内容处理
|
||||
│ └── SKILL.md
|
||||
│
|
||||
├── 03_knowledge/ # 【重构】知识库
|
||||
│ ├── 00_stream/ # 【新增★】数据流入区（替代原00_inbox）
|
||||
│ │ └── inbox/ # 协同收件箱（唯一进入通道）
|
||||
│ │ ├── knowledge/ # 外部知识（采集提炼后的MD知识卡）
|
||||
│ │ ├── memory/ # 记忆固化（本机重要记忆提炼后推入）
|
||||
│ │ ├── tools/ # 工具提交（TOOL_CARD.yaml+入口脚本）
|
||||
│ │ ├── personal/ # 个人内容（笔记/会议记录/随手记）
|
||||
│ │ └── media/ # 轻量媒体（<1MB关键附图）
|
||||
│ ├── 01_daily/ # 【保留】每日记录
|
||||
│ ├── 10_concepts/ # 【保留】概念（含各领域子目录）
|
||||
│ ├── 20_methods/ # 【保留】方法
|
||||
│ ├── 30_facts/ # 【保留】事实/数据
|
||||
│ ├── 40_references/ # 【保留】参考资料
|
||||
│ ├── 50_resources/ # 【保留】资源
|
||||
│ ├── 60_opinions/ # 【保留】观点
|
||||
│ ├── 90_archive/ # 【保留】归档
|
||||
│ └── 99_system/ # 【保留】系统文档
|
||||
│
|
||||
├── 04_memory/ # 【精简】记忆系统（仅保留协同部分）
|
||||
│ ├── daily_summaries/ # 【保留】每日摘要（可多机共享）
|
||||
│ ├── long_term/ # 【保留】长期记忆（经固化的全局记忆）
|
||||
│ ├── logs/ # 【保留】运行日志
|
||||
│ └── memory_backup/ # 【保留】记忆备份
|
||||
│ # ⚠️【审核点】vector_db 从此处移除，仅在本机local目录维护
|
||||
│
|
||||
├── 05_tools/ # 【扩展】工具层
|
||||
│ ├── 00_setup/ # 【保留】环境安装
|
||||
│ ├── 01_system/ # 【扩展】系统工具
|
||||
│ │ └── skill_scanner.py # 【新增★】技能状态扫描器
|
||||
│ ├── 02_browser/
|
||||
│ ├── 03_ocr/
|
||||
│ ├── 04_media/
|
||||
│ ├── 05_crawl/
|
||||
│ └── 06_mobile/
|
||||
│
|
||||
├── 06_runtime/ # 【保留】运行时
|
||||
│ └── tasks/
|
||||
│
|
||||
├── 07_migration/ # 【保留】迁移工具
|
||||
│ ├── backup.sh
|
||||
│ ├── pack.sh
|
||||
│ └── unpack.sh
|
||||
│
|
||||
└── 90_archive/ # 【保留】全局归档
|
||||
```
|
||||
|
||||
### 2.2 agent-os-local/ 变更说明
|
||||
|
||||
```
|
||||
agent-os-local/
|
||||
├── materials/ # 【保留+扩展】本机原始素材
|
||||
│ ├── audio/ # 音频
|
||||
│ ├── video/ # 视频
|
||||
│ ├── screenshots/ # 截图
|
||||
│ ├── web/ # 网页存档
|
||||
│ └── refined_for_inbox/ # 【保留】精炼待提交内容（暂存区）
|
||||
│
|
||||
├── memory/ # 【扩展】本机记忆
|
||||
│ ├── raw/ # 【保留】原始记忆日志（每日.md）
|
||||
│ └── long_term/ # 【新增★】本机长期记忆（固化前暂存）
|
||||
│
|
||||
├── knowledge/ # 【新增★】本机私有知识库（绝不同步）
|
||||
│ ├── projects/ # 项目过程记录
|
||||
│ └── personal/ # 个人私密笔记
|
||||
│
|
||||
├── vector_db/ # 【重构★】双轨向量库（绝不同步）
|
||||
│ ├── local/ # 本机私有内容向量化
|
||||
│ │ └── chroma/
|
||||
│ └── global/ # 协同知识库向量化（从agent-os重建）
|
||||
│ ├── keyword_index.json
|
||||
│ └── chroma/
|
||||
│
|
||||
├── runtime/ # 【保留】运行时缓存
|
||||
│ └── cache/
|
||||
│
|
||||
└── machine_info.json # 【新增★】本机环境描述
|
||||
# 含：主机名、OS、内存、角色、依赖清单
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、关键审核点（请逐一确认）
|
||||
|
||||
| # | 审核项 | 建议方案 | 需用户决策 |
|
||||
|---|--------|----------|------------|
|
||||
| ① | `03_knowledge/00_inbox/` → `03_knowledge/00_stream/inbox/` | 用新路径，旧路径做兼容软链接 | 是否保留旧00_inbox或完全迁移？ |
|
||||
| ② | `04_memory/vector_db` 移除出协同目录 | 迁移到 `agent-os-local/vector_db/global/` | 确认向量库不参与多机同步 |
|
||||
| ③ | `agent-os-local/knowledge/` 新增 | 存放本机私有知识和项目过程 | 确认路径合适 |
|
||||
| ④ | `machine_info.json` 格式 | 见下方模板，自动生成+手动补充 | 确认字段范围 |
|
||||
| ⑤ | SKILL_CARD.yaml 是否所有技能都要加 | 只给自研技能（5个核心）加 | 确认 |
|
||||
|
||||
---
|
||||
|
||||
## 四、实施任务清单（第二步工作计划）
|
||||
|
||||
### Phase 1：目录结构落地（即可执行）
|
||||
- [x] 创建规划文档（本文件）
|
||||
- [ ] 创建 `agent-sync/03_knowledge/00_stream/inbox/{knowledge,memory,tools,personal,media}/`
|
||||
- [ ] 创建 `agent-os-local/knowledge/{projects,personal}/`
|
||||
- [ ] 创建 `agent-os-local/memory/long_term/`
|
||||
- [ ] 创建 `agent-os-local/vector_db/{local,global}/chroma/`
|
||||
- [ ] 创建 `agent-os/01_core/HOST_ID.md`
|
||||
- [ ] 创建 `agent-os/05_tools/01_system/skill_scanner.py`（如不存在）
|
||||
|
||||
### Phase 2：配置文件（目录确认后）
|
||||
- [ ] 为5个核心技能创建 `SKILL_CARD.yaml`
|
||||
- [ ] 创建 `agent-os-local/machine_info.json`
|
||||
- [ ] 创建 `_template/SKILL_CARD.yaml` 模板
|
||||
|
||||
### Phase 3：核心代码完善（最终实施）
|
||||
- [ ] **memory_extractor.py** — 记忆固化提取，检测固化条件，推送inbox/memory/
|
||||
- [ ] **kb_ingest.py 更新** — 适配新inbox多分区路径
|
||||
- [ ] **inbox_refine.py 更新** — 支持5分区不同处理逻辑
|
||||
- [ ] **collect_to_inbox.py 更新** — 扫描agent-os-local/materials/refined_for_inbox/
|
||||
- [ ] **kb_search.py 新增** — 双轨向量库检索，先local后global合并结果
|
||||
- [ ] **vector_db_rebuild.py 新增** — 重建向量库（local/global两套）
|
||||
|
||||
---
|
||||
|
||||
## 五、machine_info.json 模板
|
||||
|
||||
```json
|
||||
{
|
||||
"machine": {
|
||||
"id": "my-macbook_macOS14.4_16GB_master",
|
||||
"display_name": "My MacBook Air M1",
|
||||
"role": "master",
|
||||
"os": "macOS",
|
||||
"os_version": "14.4",
|
||||
"memory_gb": 16,
|
||||
"cpu": "Apple M1",
|
||||
"hostname": "my-macbook.local"
|
||||
},
|
||||
"environment": {
|
||||
"python_path": "~/.workbuddy/binaries/python/envs/agent-os/bin/python3",
|
||||
"agent_os_path": "~/workbuddy-agent-os/agent-sync",
|
||||
"agent_os_local_path": "~/workbuddy-agent-os/agent-local",
|
||||
"shell": "zsh"
|
||||
},
|
||||
"software": {
|
||||
"git_version": "",
|
||||
"obsidian": true,
|
||||
"workbuddy": true
|
||||
},
|
||||
"network": {
|
||||
"vpn_available": false,
|
||||
"notes": ""
|
||||
},
|
||||
"special_config": {},
|
||||
"last_updated": "2026-04-29",
|
||||
"auto_update": false
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、SKILL_CARD.yaml 标准模板
|
||||
|
||||
```yaml
|
||||
# SKILL_CARD.yaml —— 技能身份证（标准模板）
|
||||
skill:
|
||||
name: "技能名称"
|
||||
id: "skill_id"
|
||||
version: "1.0.0"
|
||||
category: "core-system" # core-system / user-custom / external
|
||||
status: "active" # active / inactive / experimental
|
||||
created: "2026-04-29"
|
||||
updated: "2026-04-29"
|
||||
|
||||
description:
|
||||
short: "一句话描述"
|
||||
use_cases: []
|
||||
tags: []
|
||||
|
||||
ownership:
|
||||
master_editor: "my-macbook_macOS14.4_16GB_master"
|
||||
readonly_on_other_devices: true
|
||||
|
||||
environment:
|
||||
os: "macos"
|
||||
python_path: "~/.workbuddy/binaries/python/envs/agent-os/bin/python3"
|
||||
pip_dependencies: []
|
||||
|
||||
setup:
|
||||
install_script: ""
|
||||
post_check: ""
|
||||
|
||||
usage:
|
||||
entry_point: "main.py"
|
||||
scheduled: ""
|
||||
manual_trigger: ""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
> **【审核状态】** 请确认以上目录结构和计划后，回复"确认开始实施"或提出修改意见。
|
||||
> 确认后将进入第二步：实际创建目录、生成配置文件、完善核心代码。
|
||||
@@ -0,0 +1,139 @@
|
||||
# AgentOS 世界级知识库分类体系与全链路设计规范
|
||||
|
||||
> 版本：2026-04-29
|
||||
> 作者：AI+用户共创
|
||||
|
||||
---
|
||||
|
||||
## 一、收件箱（inbox）分区与跨界机制
|
||||
|
||||
收件箱是所有本地内容进入协同目录的唯一通道，分为五大分区：
|
||||
|
||||
```
|
||||
agent-sync/03_knowledge/00_stream/inbox/
|
||||
├── knowledge/ # 知识内容（外部采集提炼后的MD知识卡）
|
||||
├── memory/ # 记忆固化（本机记忆提炼的重要内容）
|
||||
├── tools/ # 工具提交（TOOL_CARD.yaml + 入口脚本）
|
||||
├── personal/ # 个人内容（笔记、语音转写、会议记录、随手记）
|
||||
└── media/ # 轻量媒体（关键图片、短音频片段）
|
||||
```
|
||||
|
||||
- 低权限主机只能通过inbox提交内容，高权限主机可直接写入协同目录。
|
||||
- 后期可扩展权限体系，当前以手动判断为主。
|
||||
|
||||
---
|
||||
|
||||
## 二、本机记忆固化机制
|
||||
|
||||
- 本机记忆（raw/）只有满足以下任一条件才可固化：
|
||||
1. 用户主动指定“固化”
|
||||
2. AI检测高频引用/反复出现
|
||||
3. 长期未被推翻且被引用多次
|
||||
- 固化后生成MD知识卡，推入inbox/memory/，由AI自动分类入库。
|
||||
- 不固化内容永远留在本机，不同步。
|
||||
|
||||
---
|
||||
|
||||
## 三、媒体同步边界
|
||||
|
||||
- 允许同步：
|
||||
- 关键知识附图（<500KB）
|
||||
- 重要截图（<1MB）
|
||||
- 精华语音片段（<2MB，已转写）
|
||||
- 项目产出设计稿（<2MB）
|
||||
- 不允许同步：
|
||||
- 完整视频/音频/高清图片/网页原始截图/单文件>5MB
|
||||
- 媒体与MD文件同目录，frontmatter标注attachments。
|
||||
|
||||
---
|
||||
|
||||
## 四、向量数据库架构
|
||||
|
||||
- 向量DB仅在本机重建，永不同步。
|
||||
- 协同知识库（MD文件）同步后，每台机器自动重建global向量库。
|
||||
- 本机私有内容单独建local向量库。
|
||||
- 检索时合并两层结果，优先本机，补充协同。
|
||||
|
||||
---
|
||||
|
||||
## 五、知识属性六大维度（frontmatter字段）
|
||||
|
||||
### 1. 知识本质属性（nature）
|
||||
- fact/concept/axiom/method/regulation/data/reference/opinion/quote/experience/insight/inspiration
|
||||
|
||||
### 2. 领域分类（domain）
|
||||
- 19大领域，含arts/health/culture等感官与人文类
|
||||
|
||||
### 3. 认知用途（cognitive_role）
|
||||
- foundational/actionable/reference/inspirational/contextual/evaluative
|
||||
|
||||
### 4. 个人主观属性
|
||||
- interest_level/practical_value/aesthetic_value/revisit_priority/mastery
|
||||
|
||||
### 5. 时效性（temporal）
|
||||
- evergreen/current/historical/trending/expires_at
|
||||
|
||||
### 6. 来源与可信度
|
||||
- source/source_type/confidence/machine_origin/author
|
||||
|
||||
---
|
||||
|
||||
## 六、frontmatter完整模板
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: KB-20260429-001
|
||||
title: "知识标题"
|
||||
version: 1
|
||||
status: draft
|
||||
nature: concept
|
||||
domain: [ai]
|
||||
subdomain: [RAG, NLP]
|
||||
cognitive_role: actionable
|
||||
interest_level: 4
|
||||
practical_value: 3
|
||||
aesthetic_value: 0
|
||||
revisit_priority: medium
|
||||
mastery: understanding
|
||||
temporal: evergreen
|
||||
expires_at: ""
|
||||
source: ""
|
||||
source_type: literature
|
||||
confidence: 0.8
|
||||
machine_origin: "macbook-air-m1"
|
||||
author: ""
|
||||
track: world
|
||||
summary: "一句话摘要"
|
||||
tags: [标签1, 标签2]
|
||||
keywords: [关键词1, 关键词2]
|
||||
aliases: [别名1]
|
||||
date_created: 2026-04-29
|
||||
date_modified: 2026-04-29
|
||||
previous_version: ""
|
||||
superseded_by: ""
|
||||
related: []
|
||||
project_ref: ""
|
||||
has_attachment: false
|
||||
attachments: []
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、字段分层与性价比建议
|
||||
|
||||
- 必填：id/title/nature/domain/confidence/date_created/status
|
||||
- 强烈建议：cognitive_role/summary/source/track
|
||||
- 按类型填：mastery/aesthetic_value/project_ref/expires_at
|
||||
- 其余可选，内容成熟后补充
|
||||
|
||||
---
|
||||
|
||||
## 八、整体链路总结
|
||||
|
||||
- 本机捕获(重)→本机加工(重)→本机精炼(轻MD)→inbox分区→AI分类入库→多轨道归档→归档/版本链→本机/协同向量库重建
|
||||
- 六大维度属性+分区收件箱+两层向量库，兼顾检索、创意、个性化、协同。
|
||||
|
||||
---
|
||||
|
||||
> 本规范为AgentOS知识管理系统vNext的顶层设计标准，后续如有补充请在本文件基础上增量修订。
|
||||
@@ -0,0 +1,193 @@
|
||||
# AgentOS vNext 讨论清单（2026-04-28）
|
||||
|
||||
## 一、待细化/待确认的核心议题
|
||||
|
||||
1. 向量库（vector_db）
|
||||
- 本地与全局的分工与同步机制
|
||||
- 向量库与知识内容的分离/融合方式
|
||||
- 多机向量同步的安全性与一致性
|
||||
2. 主机/维护机标识与权限体系
|
||||
- 主机唯一ID生成与管理
|
||||
- 主维护机的指定、切换与权限
|
||||
- 多机协同下的角色分工与冲突解决
|
||||
3. 知识库分类体系
|
||||
- 多级分类、标签体系的设计与落地
|
||||
- 领域/属性/标签的扩展与动态调整机制
|
||||
- 个人笔记、项目过程、记忆固化等特殊内容的归档策略
|
||||
4. 工具与技能的边界与互转
|
||||
- 工具与技能的定义、加载机制
|
||||
- CLI工具与自动化技能的互转标准
|
||||
- 何时应将工具升级为技能，反之亦然
|
||||
5. 本机数据说明与动态更新
|
||||
- 本机环境、硬件、软件、网络等数据的结构化存储
|
||||
- 自动/手动更新机制与token效率
|
||||
- 变更追踪与历史记录
|
||||
6. 同步/备份机制
|
||||
- agent-os 与 agent-os-local 的同步策略
|
||||
- 备份粒度、频率、冲突解决
|
||||
- 多机间的增量同步与恢复流程
|
||||
7. 项目过程与知识归档的分离与融合
|
||||
- 项目文档、过程记录与最终知识的转化机制
|
||||
- 归档标准与自动化流程
|
||||
8. 自动化任务与定时调度体系
|
||||
- 任务注册、启停、调度与监控
|
||||
- 多机环境下的任务分发与容错
|
||||
9. 其他（请补充）
|
||||
|
||||
---
|
||||
|
||||
## 二、任务细化清单（可持续补充）
|
||||
|
||||
- [ ] 设计向量库本地/全局结构与同步流程
|
||||
- [ ] 制定主机/维护机标识与权限管理方案
|
||||
- [ ] 优化知识库多级分类与标签体系
|
||||
- [ ] 明确工具与技能的互转标准与流程
|
||||
- [ ] 设计本机数据说明的结构与自动更新机制
|
||||
- [ ] 规划同步/备份的详细策略与实现步骤
|
||||
- [ ] 梳理项目过程与知识归档的转化流程
|
||||
- [ ] 设计自动化任务调度与监控体系
|
||||
- [ ] ...（后续补充）
|
||||
|
||||
---
|
||||
|
||||
## 三、讨论方向与预期（AI建议）
|
||||
|
||||
### 1. 全局视角
|
||||
- 以“多机协同+知识自进化”为核心，兼顾效率、可维护性与安全性
|
||||
- 强化自动化与智能化，减少人工干预
|
||||
- 结构化、标准化、可追溯，便于后续扩展
|
||||
|
||||
### 2. 细化建议
|
||||
- 每个议题可单独开子文件夹，沉淀方案、流程图、决策记录
|
||||
- 充分讨论后再进入开发，避免反复返工
|
||||
- 关键机制（如同步、权限、归档）优先原型验证
|
||||
|
||||
### 3. 预期目标
|
||||
- 明确每一项机制的“为什么/做什么/怎么做/如何验证”
|
||||
- 形成可落地的设计文档与任务分解
|
||||
- 逐步推进，阶段性评审与复盘
|
||||
|
||||
---
|
||||
|
||||
## 四、AI补充的全方位思考方向（供参考）
|
||||
|
||||
- 多机协同下的数据一致性与冲突解决最佳实践
|
||||
- 向量化知识检索的安全性与隐私保护
|
||||
- 个人与全局知识的边界与流转机制
|
||||
- 自动化任务的容错与自愈能力
|
||||
- 系统可观测性与监控体系建设
|
||||
- 版本管理与历史追溯的自动化
|
||||
- 用户体验与交互流程优化
|
||||
- 跨平台兼容性与迁移策略
|
||||
- ...（持续补充）
|
||||
|
||||
---
|
||||
|
||||
## 【2026-04-28 本机标识与角色机制简化方案】
|
||||
|
||||
- 每台机器只需配置一个唯一“主机名”或“身份名”，如：`my-macbook_macOS14.4_16GB_master`。
|
||||
- 名字建议包含：
|
||||
- 设备自定义名（如 my-macbook）
|
||||
- 系统版本（如 macOS14.4）
|
||||
- 内存（如 16GB）
|
||||
- 当前角色（如 master/maintainer）
|
||||
- 例如：`office-pc_Win11_32GB_maintainer`
|
||||
- 这样可一眼识别本机情况，角色切换只需手动改名，无需复杂权限体系。
|
||||
- 适合个人和小规模多机协同，简单高效，易于维护。
|
||||
|
||||
---
|
||||
|
||||
## 【2026-04-28 工具与技能边界、互转与迁移机制补充】
|
||||
|
||||
- 工具本身较重，依赖复杂环境，协同目录（如 agent-os/tools/）只同步“安装命令”“入口脚本”或“适配说明”，不直接同步所有依赖和环境。
|
||||
- 本地目录（agent-os-local/tools/）实际存放可执行脚本、依赖包、环境配置，确保工具能在本机落地运行。
|
||||
- 工具通过“标准化包装/描述文件”（如 TOOL_CARD.yaml），描述依赖、安装方式、适配平台、入口命令等，便于自动化部署和技能注册。
|
||||
- 支持“环境检测/自动适配”脚本，自动判断本地依赖是否齐全，缺失时友好提示或一键安装。
|
||||
- 技能本质是轻量化自动化脚本，调用本地已落地的工具，负责流程编排、输入输出标准化。
|
||||
- 工具与技能通过“标准化描述+适配层”灵活互转，协同目录轻量化，同步高效，落地灵活。
|
||||
- 工具卡和环境适配脚本为后续系统迁移、全量/部分备份、跨平台部署提供基础，迁移时只需同步描述和适配脚本，目标机自动完成环境适配和工具落地。
|
||||
|
||||
> 工具卡与环境适配机制将在“同步/备份机制”章节详细展开。
|
||||
|
||||
---
|
||||
|
||||
## 【2026-04-28 本机数据说明机制补充】
|
||||
|
||||
- 本机数据说明即“本机环境知识库”或“本机环境清单”，用于记录本机的硬件、系统、网络、环境变量、专用配置等关键信息。
|
||||
- 主要作用：
|
||||
- 让智能体/程序快速识别本机情况，避免每次都重新检测。
|
||||
- 便于记忆系统、自动化脚本、技能等直接读取和复用本机环境信息。
|
||||
- 记录本机专属设置（如内存大小、特殊端口、独有依赖等），不参与多机协同，仅本机使用。
|
||||
- 建议存储为结构化文件（如 environment.yaml、machine_info.json），并定期/按需自动更新，或手动补充特殊项。
|
||||
- 可作为记忆系统的一个专属分支，便于后续检索和自动化调用。
|
||||
|
||||
---
|
||||
|
||||
## 【2026-04-28 项目过程与知识归档的分离与融合机制补充】
|
||||
|
||||
- 项目过程、想法、实验性工具等内容，初期只保存在本机或本机项目知识库，支持高频变更和个性化探索。
|
||||
- 当项目或工具开发进入“转正”阶段（即具备通用价值、可协同复用）：
|
||||
1. 在本机完成最终打包或生成安装脚本。
|
||||
2. 通过“收件箱”机制，将打包文件、安装脚本、说明文档等统一提交到协同目录的专用收件箱（如 agent-sync/03_knowledge/00_inbox/projects/）。
|
||||
3. 普通节点仅有提交权限，主机/维护机负责审核、验收和归档。
|
||||
4. 主机/维护机审核通过后，将工具/项目内容正式迁移到协同目录的工具区（如 agent-os/05_tools/），并将相关知识、说明文档归档到知识库（如 agent-sync/03_knowledge/）。
|
||||
5. 归档时添加元数据（如来源、归档时间、版本、作者等），便于追溯和管理。
|
||||
- 只有经过“收件箱-审核-归档”流程的内容，才会同步到多机协同，成为所有节点认可的“公共工具/知识”。
|
||||
- 未归档内容仅在本机或主机流转，避免半成品、实验性内容干扰全局协同。
|
||||
- 支持“项目过程-知识归档-全局共享”全流程的元数据记录，便于后续追溯和复盘。
|
||||
|
||||
> 该机制确保项目内容从本地探索到全局协同的转化过程有据可查、权限清晰、流程严谨。
|
||||
你的思路非常清晰，补充总结如下：
|
||||
|
||||
---
|
||||
|
||||
## 【2026-04-28 自动化任务与定时调度体系补充】
|
||||
|
||||
- 自动化任务（如记忆压缩、知识提炼、信息抓取等）在多机协同的同步目录中统一管理，每台主机都能获取完整任务清单。
|
||||
- 每台主机根据自身“主机名/角色”有选择性地启用相关任务：
|
||||
- 普通主机只启用本地记忆压缩、体验类任务。
|
||||
- 知识库管理主机启用知识提炼、归档、同步等核心任务。
|
||||
- 特殊主机可启用自动抓取、外部采集等定制任务。
|
||||
- 任务启用逻辑简单高效：只需在任务配置中标明适用角色或主机名，系统自动判断是否执行。
|
||||
- 不做复杂的分发、容错、调度体系，单机/小规模协同下以“角色驱动”实现任务分工，灵活易维护。
|
||||
- 如后续有多用户/大规模协同需求，可再扩展任务分发、容错等机制。
|
||||
|
||||
---
|
||||
|
||||
你的方案已非常适合个人和小团队场景，简单高效，易于落地和维护。如需，我可以帮你设计任务配置模板或角色-任务映射示例。
|
||||
|
||||
---
|
||||
|
||||
# 【2026-04-28 最新讨论补充】本地/全局记忆与知识库、向量库、同步机制设计
|
||||
|
||||
## 1. 目录与同步边界
|
||||
- `~/workbuddy-agent-os/agent-sync/`：所有内容都参与多机同步（知识库、协同收件箱、协同向量库等）。
|
||||
- `~/workbuddy-agent-os/agent-sync/agent-local/`：所有内容仅本机保存，绝不参与同步（本地记忆、个人笔记、本地素材等）。
|
||||
|
||||
## 2. 数据流转与提炼机制
|
||||
1. **本地记忆/个人笔记产生**
|
||||
- 存在于 `~/workbuddy-agent-os/agent-sync/agent-local/materials/`，如记忆系统自动提存、个人随手笔记等。
|
||||
2. **记忆/笔记提炼**
|
||||
- 用户可手动或自动将有价值的内容，从 `~/workbuddy-agent-os/agent-sync/agent-local/materials/` 提取到 `~/workbuddy-agent-os/agent-sync/03_knowledge/00_inbox/`（协同收件箱）。
|
||||
- 提取时可加属性（如“记忆”标签），以便后续分类。
|
||||
3. **知识库入库**
|
||||
- 协同收件箱只存 md 文件，知识管理系统定期/手动将内容加工、分类，正式入库到知识库（如 10_concepts、20_methods 等）。
|
||||
|
||||
## 3. 向量数据库设计
|
||||
- **本地向量库**：`~/workbuddy-agent-os/agent-sync/agent-local/` 下的所有内容（记忆、个人笔记等）向量化，仅本机检索。
|
||||
- **协同向量库**：`~/workbuddy-agent-os/agent-sync/` 下知识库内容向量化，参与多机同步和协同检索。
|
||||
- 检索时，默认先查本地向量库，再查协同向量库，结果合并展示，体验无割裂。
|
||||
|
||||
## 4. 分类与属性
|
||||
- 协同收件箱和知识库的 md 文件可通过 frontmatter 或标签标明来源（如“记忆提存”、“个人笔记”），方便后续分类和检索。
|
||||
- 知识库分类可灵活调整，不必强依赖文件名。
|
||||
|
||||
## 5. 机制总结
|
||||
- 本地内容完全隔离，隐私安全。
|
||||
- 有价值内容通过“提炼-收件箱-知识库”机制流转，保证协同知识的高质量和结构化。
|
||||
- 多机协同时，检索体验顺畅，既能查本地记忆，也能查全局知识。
|
||||
|
||||
---
|
||||
> 本节为 2026-04-28 讨论结论，后续如有新机制/细节调整请在此基础上补充。
|
||||
|
||||
---
|
||||
@@ -0,0 +1,35 @@
|
||||
# 归档：AVE 早期编号分层目录（2026-10-01）
|
||||
|
||||
## 归档原因
|
||||
|
||||
这 7 个目录是视频工厂**早期的分层规划残留**，每个目录只有一个 **0 字节的 `__init__.py`**，
|
||||
**没有任何实现**。真正的实现都在同级的**无编号目录**里：
|
||||
|
||||
| 归档目录（空壳） | 实际实现位置 |
|
||||
|:--|:--|
|
||||
| `01_director_parser/` | `director_parser/`（323 行） |
|
||||
| `02_voice_synthesizer/` | `voice_synthesizer/`（391 行） |
|
||||
| `03_bgm_generator/` | `bgm_generator/`（654 行） |
|
||||
| `04_anchor_extractor/` | `anchor_extractor/`（155 行） |
|
||||
| `05_material_producer/` | `material_producer/`（902 行） |
|
||||
| `06_composer/` | `composer/`（2635 行） |
|
||||
| `07_service_layer/` | `service_layer/`（271 行） |
|
||||
|
||||
## 为什么要归档
|
||||
|
||||
1. **避免误导**：两套目录并存，看起来"有两份实现"，实际编号那份是空的
|
||||
2. **框架分层已换**：视频工厂框架（`PLANS/VIDEO_FACTORY_FRAMEWORK.md`）定义的新分层是
|
||||
`capabilities/`（能力层）· `directors/`（导演层）· `executor/`（编排层）· `assets/`（资产层），
|
||||
旧编号方案不再使用
|
||||
|
||||
## 影响与修复
|
||||
|
||||
- **`05_tools/07_matrix/scripts/agentos/plugins/ave.py`** 曾引用这些空壳路径
|
||||
（如 `01_director_parser/run.py`、`06_composer/run.py`、`07_service_layer/template_manager.py`），
|
||||
这些文件**本来就不存在**（引用早已失效）。该插件的路径已在同批次修正为指向真实目录。
|
||||
- 其余引用均为**源码注释里的历史标记**（如 `# AVE 06_composer — FFmpeg 合成模块`），无害。
|
||||
|
||||
## 恢复方式
|
||||
|
||||
如需找回：`git mv 90_archive/ave_legacy_numbered_dirs_20261001/<dir> 05_tools/09_ave/scripts/`
|
||||
（但按框架，不建议恢复）
|
||||
@@ -0,0 +1,30 @@
|
||||
# AgentOS 历史说明文档已归档
|
||||
|
||||
最后更新：2026-04-28
|
||||
|
||||
本文件原先承载的是一份大体量扩展说明，现已归档，不再作为 AgentOS v2.0 的正式基准。
|
||||
|
||||
## 当前正式入口
|
||||
|
||||
请优先查看：
|
||||
|
||||
1. `CORE-ARCHITECTURE.md`
|
||||
2. `V2.0-SUMMARY.md`
|
||||
3. `QUICKSTART.md`
|
||||
4. `REVIEW-V2.0.md`
|
||||
|
||||
## 历史归档位置
|
||||
|
||||
完整历史内容已移动到：
|
||||
|
||||
- `90_archive/docs/AgentOS-完整说明文档_副本.v2.1-history.md`
|
||||
|
||||
## 说明
|
||||
|
||||
归档原因不是内容无价值，而是其中混合了：
|
||||
|
||||
- 原形信息
|
||||
- 当前实现信息
|
||||
- 后续升级设想
|
||||
|
||||
为避免继续与 v2.0 基准冲突，现仅作为历史备忘保留。
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,721 @@
|
||||
# AgentOS 知识管理系统 —— 设计说明与操作指南
|
||||
|
||||
> **版本**：v1.0
|
||||
> **最后更新**：2026-04-28
|
||||
> **知识库路径**：`~/workbuddy-agent-os/agent-sync/03_knowledge/`（Obsidian Vault）
|
||||
> **面向读者**：需要了解本系统设计思路、分类逻辑、目录结构、工作流程的协作者
|
||||
|
||||
---
|
||||
|
||||
## 一、系统定位与设计理念
|
||||
|
||||
### 1.1 这是什么？
|
||||
|
||||
AgentOS 知识管理系统是一套**自动化知识采集→分类→归档→检索**的完整解决方案。它不是一个简单的文件分类目录，而是一个具有以下特征的**智能知识加工流水线**：
|
||||
|
||||
| 特征 | 说明 |
|
||||
|------|------|
|
||||
| **自动采集** | 多平台信息源（B站/YouTube/小红书/抖音/RSS/网页）24h 自动抓取 |
|
||||
| **智能分类** | 本地 LLM + 启发式规则自动判定知识的属性和领域 |
|
||||
| **标准化归档** | 每条知识都有统一的 Frontmatter 元数据、唯一 ID、版本链 |
|
||||
| **版本化管理** | 知识可进化（观点→事实、方法升级），旧版本自动保留 |
|
||||
| **语义检索** | BM25 + 向量混合检索，用自然语言找到知识 |
|
||||
| **双轨同步** | 坚果云实时同步 + Git 版本控制，跨设备安全可用 |
|
||||
|
||||
### 1.2 核心设计原则
|
||||
|
||||
1. **知识属性优先于内容类型**：不看"这是篇文章还是张图片"，而看"这是事实、方法、还是观点"
|
||||
2. **两级分类正交设计**：**nature（知识属性）** 决定"放在哪个层"，**domain（领域）** 决定"属于哪个学科"，两者互不干扰
|
||||
3. **英文目录 + 中文映射**：目录名用英文（跨平台兼容、无乱码风险），通过配置文件提供中文别名
|
||||
4. **收件箱缓冲机制**：新内容不直接归档，先进入收件箱缓冲，由定时任务统一提纯
|
||||
5. **自动化优先**：每日凌晨自动完成：收集→汇聚→提纯→归档→更新统计，人工干预最少化
|
||||
|
||||
---
|
||||
|
||||
## 二、目录结构总览
|
||||
|
||||
```
|
||||
03_knowledge/
|
||||
├── 00_inbox/ # 📥 收件箱（缓冲区，所有新内容先进这里）
|
||||
├── 01_daily/ # 📅 日记（每日记录、闪念笔记）
|
||||
├── 10_concepts/ # 💡 概念层（原子概念、公理、知识卡片）
|
||||
├── 20_methods/ # 🔧 方法层（教程、最佳实践、操作步骤）
|
||||
├── 30_facts/ # 📋 事实层（客观事实、法规、数据）
|
||||
├── 40_references/ # 📎 参考层（论文、文档、外部资料）
|
||||
├── 50_resources/ # 🛠 资源层（视频笔记、阅读笔记、灵感素材等原始收集物）
|
||||
├── 60_opinions/ # 💭 观点层（主观看法、引用、推测）
|
||||
├── 90_archive/ # 🗄 归档层（已过时或废弃的知识）
|
||||
├── 99_system/ # ⚙️ 系统层（模板、分类表、提示词——不是知识内容）
|
||||
│ ├── templates/ # 知识卡片模板（4种）
|
||||
│ ├── taxonomies/ # 分类配置（领域表 + 属性表 + 中文映射）
|
||||
│ ├── prompts/ # LLM 分类提示词
|
||||
│ └── timelines/ # 知识版本时间线图（自动生成）
|
||||
├── README.md # 知识库首页（统计 + 导览）
|
||||
└── CHANGELOG.md # 知识库变更日志
|
||||
```
|
||||
|
||||
### 2.1 为什么这样分目录？
|
||||
|
||||
目录按**知识属性（nature）** 分层，每个数字前缀代表一个"知识层级"：
|
||||
|
||||
| 目录 | 前缀 | 为什么设这个目录 | 里面放什么 |
|
||||
|------|------|------------------|------------|
|
||||
| `00_inbox` | 00 | **缓冲区**：新内容需要统一处理后才能精确分类，直接丢进来避免"不知道放哪"的决策负担 | 所有新采集/新收集的原始内容 |
|
||||
| `01_daily` | 01 | **时间维度**：有些知识是"某天的记录"，有强时间属性，不适合按属性分类 | 日记、闪念笔记、每日总结 |
|
||||
| `10_concepts` | 10 | **知识原子**：概念是知识的"基本粒子"，其他知识都建立在概念之上 | 概念定义、公理、术语解释 |
|
||||
| `20_methods` | 30 | **怎么做的**：方法是"行动指南"，与其他知识有本质区别——它是可执行的 | 教程、步骤、最佳实践、操作手册 |
|
||||
| `30_facts` | 30 | **是什么**：事实是"世界的客观描述"，可靠性最高 | 客观事实、法规制度、实验数据 |
|
||||
| `40_references` | 40 | **别人说的**：参考资料不是你的知识，而是"外部信息的索引" | 论文链接、文档引用、网页存档 |
|
||||
| `50_resources` | 50 | **原始素材**：这些是"未经加工的原材料"，如视频笔记、截图、翻译等 | 视频笔记、阅读笔记、灵感素材、语音转写、字幕存档 |
|
||||
| `60_opinions` | 60 | **我觉得**：观点不是事实，需要明确标注可信度，避免与事实混淆 | 个人见解、他人语录、未验证的推测 |
|
||||
| `90_archive` | 90 | **过期的**：知识会过时（技术更新、事实变更），归档而非删除，保留历史可追溯 | 已被新知识替代的旧版本 |
|
||||
| `99_system` | 99 | **系统本身**：模板和配置不属于知识内容，单独隔离 | 模板文件、分类配置、提示词 |
|
||||
|
||||
**关键洞察**：`50_resources/` 和 `99_system/` 虽然也在知识库目录下，但它们**不是知识内容本身**——resources 是原始素材（等待被提纯），system 是系统配置（不参与知识流转）。
|
||||
|
||||
---
|
||||
|
||||
## 三、知识属性分类（nature）
|
||||
|
||||
这是整个系统最核心的设计。每条知识都有一个 `nature` 字段，它决定了这条知识**存放在哪个目录**。
|
||||
|
||||
### 3.1 九种知识属性
|
||||
|
||||
| nature 值 | 中文名 | 一句话定义 | 目标目录 | 默认可信度 | 举例 |
|
||||
|-----------|--------|------------|----------|-----------|------|
|
||||
| `fact` | 事实 | 已验证的客观事实 | `30_facts/` | 1.0 | "Python 3.12 于 2023-10-2 发布" |
|
||||
| `method` | 方法 | 可操作的步骤/教程 | `20_methods/` | 1.0 | "使用 Playwright 抓取 SPA 页面的 5 个步骤" |
|
||||
| `concept` | 概念 | 原子概念、术语定义 | `10_concepts/` | 0.8 | "RAG：检索增强生成，是结合检索和生成的 AI 范式" |
|
||||
| `axiom` | 公理 | 公认的基础原理 | `10_concepts/` | 1.0 | "欧几里得第五公设：过直线外一点有且仅有一条平行线" |
|
||||
| `regulation` | 规章 | 法律/法规/制度 | `30_facts/` | 1.0 | "《个人信息保护法》2021年11月1日起施行" |
|
||||
| `reference` | 参考 | 论文/文档/外部资料 | `40_references/` | 0.7 | "《Attention is All You Need》论文存档" |
|
||||
| `data` | 数据 | 测试数据/基准结果 | `30_facts/` | 0.9 | "M1 Mac 运行 LLaMA-7B 推理速度：32 tokens/s" |
|
||||
| `opinion` | 观点 | 主观看法/推测 | `60_opinions/` | 0.5 | "我认为 Agent 框架会比单体 LLM 更有前景" |
|
||||
| `quote` | 引用 | 他人原话/语录 | `60_opinions/` | 0.6 | "Joel Spolsky: 'The best code is no code at all'" |
|
||||
|
||||
### 3.2 为什么分 9 种？
|
||||
|
||||
这是一个**粒度权衡**的结果：
|
||||
|
||||
- **太粗（比如只分"事实"和"非事实"）**：`concept`（定义）和 `method`（步骤）混在一起，检索时无法区分"我想查某个概念"还是"我想找某个方法"
|
||||
- **太细（比如分 20 种）**：分类成本太高，LLM 分类准确率下降，维护负担增加
|
||||
- **9 种是平衡点**：覆盖了日常知识的所有主要类型，每种之间有清晰的判定边界
|
||||
|
||||
### 3.3 分类决策树
|
||||
|
||||
当 LLM 或人工需要判定一条内容属于哪个 nature 时，使用以下决策树：
|
||||
|
||||
```
|
||||
这段内容是在描述"世界是什么样"还是在说"应该怎么做"？
|
||||
│
|
||||
├── "是什么" → 可能是 fact / opinion / quote / data / reference / axiom
|
||||
│ │
|
||||
│ ├── 有实验数据/论文支持？
|
||||
│ │ ├─ 是 → fact（confidence: 0.8+）
|
||||
│ │ └─ 否 ↓
|
||||
│ │
|
||||
│ ├── 是公认无需证明的原理？
|
||||
│ │ ├─ 是 → axiom（confidence: 0.95+）
|
||||
│ │ └─ 否 ↓
|
||||
│ │
|
||||
│ ├── 是作者的个人看法/推测？
|
||||
│ │ ├─ 是 → opinion（confidence: 0.4-0.6）
|
||||
│ │ └─ 否 ↓
|
||||
│ │
|
||||
│ ├── 是引用的他人原话？
|
||||
│ │ ├─ 是 → quote（confidence: 标注来源可信度）
|
||||
│ │ └─ 否 ↓
|
||||
│ │
|
||||
│ ├── 是外部资料的链接/存档？
|
||||
│ │ ├─ 是 → reference（confidence: 0.7）
|
||||
│ │ └─ 否 ↓
|
||||
│ │
|
||||
│ └── 是测试数据/基准结果？
|
||||
│ ├─ 是 → data（confidence: 0.9）
|
||||
│ └─ 否 → 默认 reference
|
||||
│
|
||||
└── "怎么做" → 可能是 method / regulation
|
||||
│
|
||||
├── 有法律/组织的强制力？
|
||||
│ ├─ 是 → regulation（confidence: 1.0）
|
||||
│ └─ 否 → method（confidence: 1.0）
|
||||
```
|
||||
|
||||
### 3.4 属性变更规则
|
||||
|
||||
知识不是静态的，它的属性可能随着时间变化：
|
||||
|
||||
| 变化场景 | 处理方式 | 示例 |
|
||||
|----------|----------|------|
|
||||
| 观点被验证为事实 | `opinion` → `fact`，confidence 提升，文件移动到 `30_facts/` | "我推测 GPT-5 会在2025发布" → OpenAI 实际发布了 |
|
||||
| 事实被推翻 | `fact` → `opinion`，confidence 降低，文件移动到 `60_opinions/` | "地球是平的" 被科学推翻 |
|
||||
| 方法升级 | 保留旧版本文件，新建 v2 文件，通过 `related` 双向链接 | "部署方案 v1" → "部署方案 v2（Docker化）" |
|
||||
| 知识过时 | 移动到 `90_archive/`，标记 `status: archived` | "Python 2.x 的字符串编码处理" |
|
||||
|
||||
> **注意**：所有属性变更都保留历史版本，不是直接覆盖。`previous_version` 和 `superseded_by` 字段构成版本链。
|
||||
|
||||
---
|
||||
|
||||
## 四、领域分类（domain）
|
||||
|
||||
领域分类解决的是"这条知识属于哪个学科/行业"的问题，与 nature 正交。
|
||||
|
||||
### 4.1 16 个一级领域
|
||||
|
||||
| 编号 | 英文目录名 | 中文名称 | 典型子领域 |
|
||||
|------|-----------|----------|-----------|
|
||||
| 01 | `cs` | 计算机科学 | 数据库、前端、后端、运维、安全 |
|
||||
| 02 | `ai` | 人工智能 | NLP、CV、强化学习、RAG、Agent |
|
||||
| 03 | `finance` | 金融 | 量化交易、价值投资、宏观经济 |
|
||||
| 04 | `law` | 法律 | 民法、商法、知识产权 |
|
||||
| 05 | `medicine` | 医学 | 中医、西医、营养学 |
|
||||
| 06 | `physics` | 物理 | 量子力学、相对论、热力学 |
|
||||
| 07 | `math` | 数学 | 线性代数、概率统计、微积分 |
|
||||
| 08 | `psychology` | 心理学 | 认知心理学、社会心理学 |
|
||||
| 09 | `philosophy` | 哲学 | 认识论、伦理学、美学 |
|
||||
| 10 | `history` | 历史 | 中国史、世界史、科技史 |
|
||||
| 11 | `engineering` | 工程 | 机械、电子、土木 |
|
||||
| 12 | `design` | 设计 | UI/UX、平面设计、建筑设计 |
|
||||
| 13 | `business` | 商业 | 创业、管理、营销、战略 |
|
||||
| 14 | `personal-management` | 个人管理 | GTD、番茄工作法、精力管理 |
|
||||
| 15 | `personal-insight` | 个人洞见 | 决策模型、价值观、反思 |
|
||||
| 16 | `other` | 其他 | 暂未归类 |
|
||||
|
||||
### 4.2 领域 vs 属性：正交关系
|
||||
|
||||
一条知识的**最终存储位置**由两者共同决定：
|
||||
|
||||
```
|
||||
物理路径 = 目标目录（由 nature 决定）+ 领域子目录（由 domain 决定）
|
||||
```
|
||||
|
||||
**示例**：
|
||||
|
||||
| 知识标题 | nature | domain | 物理路径 |
|
||||
|----------|--------|--------|----------|
|
||||
| Transformer 架构解析 | concept | ai | `10_concepts/ai/transformer-架构解析.md` |
|
||||
| macOS 终端快捷键 | method | cs | `20_methods/cs/macos-终端快捷键.md` |
|
||||
| 2026年Q1 GDP 增速 5.4% | fact | finance | `30_facts/finance/2026q1-gdp.md` |
|
||||
| 价值投资核心理念 | opinion | finance | `60_opinions/finance/价值投资核心理念.md` |
|
||||
| GTD 工作流详解 | method | personal-management | `20_methods/personal-management/gdt-工作流.md` |
|
||||
|
||||
### 4.3 领域扩展规则
|
||||
|
||||
- 当 `other/` 类别下的文件数**超过总文件数的 5%** 时，系统会提示新增领域
|
||||
- 新领域需同时定义：中文名称、英文目录名、说明、典型子领域
|
||||
- 新增后需更新两个文件：`domains.md`（分类表）和 `folder-aliases.json`（中文映射）
|
||||
|
||||
---
|
||||
|
||||
## 五、知识卡片模板
|
||||
|
||||
每条归档的知识都是一个标准化的 Markdown 文件，使用对应的卡片模板。模板保证了知识的**结构一致性**，便于检索和版本管理。
|
||||
|
||||
### 5.1 为什么用 4 种模板而非 1 种？
|
||||
|
||||
不同属性的知识需要记录的信息完全不同：
|
||||
|
||||
| 属性 | 需要记录的关键信息 | 模板 |
|
||||
|------|-------------------|------|
|
||||
| 概念 | 定义、原理、与相关概念的区别 | `concept-card.md` |
|
||||
| 方法 | 目标、前置条件、步骤、常见问题 | `method-card.md` |
|
||||
| 事实 | 数据来源、事实内容表格、结论 | `fact-card.md` |
|
||||
| 个人洞见 | 背景、核心观点、可复用原则、验证项 | `personal-insight-card.md` |
|
||||
|
||||
如果用一种"万能模板"，要么字段太多（大量留空），要么字段太少（丢失关键信息）。
|
||||
|
||||
### 5.2 模板一：概念卡片（concept-card.md）
|
||||
|
||||
**适用**：`nature: concept` 和 `nature: axiom`
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: KB-YYYYMMDD-NNN # 唯一标识符（自动生成）
|
||||
title: "__概念名称__"
|
||||
type: concept # 卡片类型
|
||||
status: draft # 状态：draft/review/published/archived
|
||||
nature: fact # 知识属性
|
||||
domain: [计算机科学] # 领域（1-3个）
|
||||
subdomain: [] # 子领域（可选）
|
||||
tags: [__标签1__, __标签2__] # 检索标签
|
||||
confidence: 0.8 # 可信度（0-1）
|
||||
source: "" # 来源 URL
|
||||
source_type: literature # 来源类型
|
||||
date_created: __DATE__ # 创建日期
|
||||
date_modified: __DATE__ # 最后修改日期
|
||||
version: 1 # 版本号
|
||||
aliases: [__别称__] # 别名（方便不同叫法都能找到）
|
||||
keywords: [__关键词__] # 关键词（用于 BM25 检索）
|
||||
summary: "__一句话摘要__" # 摘要（用于 L2 摘要层检索）
|
||||
related: [] # 关联知识（双向链接）
|
||||
previous_version: "" # 上一版本 KB-ID
|
||||
superseded_by: "" # 被哪个版本替代
|
||||
---
|
||||
```
|
||||
|
||||
**正文结构**：
|
||||
1. **一句话定义**：用最简洁的语言定义
|
||||
2. **核心原理**：3-5 个要点
|
||||
3. **与相关概念的区别**：对比表格（擅长/不擅长）
|
||||
4. **主流选择/实现**：业界常见方案
|
||||
5. **相关概念**：`[[双向链接]]`
|
||||
|
||||
**设计意图**：概念卡片的目标是"让读者 30 秒内理解一个概念"。一句话定义是核心，其余部分提供上下文。
|
||||
|
||||
### 5.3 模板二：方法卡片（method-card.md）
|
||||
|
||||
**适用**：`nature: method`
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: KB-YYYYMMDD-NNN
|
||||
title: "__方法/教程标题__"
|
||||
type: method
|
||||
status: published
|
||||
nature: method
|
||||
domain: [__领域__]
|
||||
confidence: 1.0
|
||||
source: "__来源__"
|
||||
date_created: __DATE__
|
||||
date_modified: __DATE__
|
||||
version: 1
|
||||
previous_version: ""
|
||||
superseded_by: ""
|
||||
---
|
||||
```
|
||||
|
||||
**正文结构**：
|
||||
1. **目标**：这个方法解决什么问题？
|
||||
2. **前置条件**：需要什么才能执行
|
||||
3. **步骤**：编号步骤 + 代码示例
|
||||
4. **注意事项**：踩过的坑
|
||||
5. **常见问题**：问题-原因-方案 三列表格
|
||||
6. **历史版本**：变更记录
|
||||
|
||||
**设计意图**：方法卡片的目标是"让读者照着做就能成功"。步骤是核心，常见问题是防错保障。
|
||||
|
||||
### 5.4 模板三：事实卡片（fact-card.md）
|
||||
|
||||
**适用**：`nature: fact`、`nature: regulation`、`nature: data`
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: KB-YYYYMMDD-NNN
|
||||
title: "__事实标题__"
|
||||
type: fact
|
||||
status: published
|
||||
nature: fact
|
||||
domain: [__领域__]
|
||||
confidence: 0.9
|
||||
source: "__来源URL或出处__"
|
||||
source_type: experiment|literature|official_doc|personal_exp
|
||||
date_created: __DATE__
|
||||
date_modified: __DATE__
|
||||
version: 1
|
||||
previous_version: ""
|
||||
superseded_by: ""
|
||||
---
|
||||
```
|
||||
|
||||
**正文结构**：
|
||||
1. **数据来源**：来源说明、测试环境、文献出处
|
||||
2. **事实内容**：维度-值-备注 三列表格
|
||||
3. **结论**：基于事实得出的结论
|
||||
4. **历史版本**：变更记录
|
||||
|
||||
**设计意图**：事实卡片的目标是"可追溯、可验证"。`source` 和 `source_type` 是关键——没有来源的事实不可信。
|
||||
|
||||
### 5.5 模板四：个人洞见卡片（personal-insight-card.md）
|
||||
|
||||
**适用**：`nature: opinion`（特别是个人洞见类）
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: KB-YYYYMMDD-NNN
|
||||
title: "__个人洞见标题__"
|
||||
type: concept
|
||||
status: draft # 洞见默认 draft，需验证后才 published
|
||||
nature: opinion
|
||||
domain: [个人洞见]
|
||||
tags: [__标签1__, __标签2__]
|
||||
confidence: 0.6 # 洞见默认 0.6（不高不低）
|
||||
source_type: personal_exp # 来源类型固定为个人经验
|
||||
date_created: __DATE__
|
||||
date_modified: __DATE__
|
||||
version: 1
|
||||
previous_version: ""
|
||||
superseded_by: ""
|
||||
---
|
||||
```
|
||||
|
||||
**正文结构**：
|
||||
1. **背景**：什么情境下产生的
|
||||
2. **核心观点**：一句话概括
|
||||
3. **详细思考**：推理过程
|
||||
4. **可复用的原则**：抽象出来的通用规则
|
||||
5. **相关经历**：案例支撑
|
||||
6. **后续验证**：待验证项 checklist
|
||||
|
||||
**设计意图**：个人洞见是"最有价值但最不可靠"的知识类型。默认 `status: draft` 和 `confidence: 0.6`，通过"后续验证"机制逐步提升可信度。当验证通过后可升级为 `fact`。
|
||||
|
||||
---
|
||||
|
||||
## 六、Frontmatter 字段详解
|
||||
|
||||
所有知识卡片共享一套 Frontmatter 字段体系。以下是每个字段的含义和用途：
|
||||
|
||||
### 6.1 必填字段
|
||||
|
||||
| 字段 | 类型 | 说明 | 示例 |
|
||||
|------|------|------|------|
|
||||
| `id` | string | 唯一标识符，自动生成 | `KB-20260428-001` |
|
||||
| `title` | string | 知识标题 | `"Transformer 架构详解"` |
|
||||
| `type` | enum | 卡片类型（与模板对应） | `concept` / `method` / `fact` |
|
||||
| `status` | enum | 生命周期状态 | `draft` / `review` / `published` / `archived` |
|
||||
| `nature` | enum | 知识属性（9种） | `fact` / `method` / `concept` / ... |
|
||||
| `domain` | list | 领域分类（1-3个） | `[人工智能, 计算机科学]` |
|
||||
| `confidence` | float | 可信度（0-1） | `0.85` |
|
||||
| `source` | string | 来源 URL 或出处 | `"https://arxiv.org/abs/1706.03762"` |
|
||||
| `date_created` | date | 创建日期 | `2026-04-28` |
|
||||
| `date_modified` | date | 最后修改日期 | `2026-04-28` |
|
||||
| `version` | int | 版本号 | `1` |
|
||||
|
||||
### 6.2 可选字段
|
||||
|
||||
| 字段 | 类型 | 说明 | 示例 |
|
||||
|------|------|------|------|
|
||||
| `subdomain` | list | 子领域 | `[自然语言处理, 大模型]` |
|
||||
| `tags` | list | 标签（用于检索） | `[transformer, attention, nlp]` |
|
||||
| `author` | string | 作者 | `"Ashish Vaswani"` |
|
||||
| `source_type` | enum | 来源类型 | `official_doc` / `literature` / `personal_exp` / `social_media` / `unknown` |
|
||||
| `related` | list | 关联知识的 KB-ID | `["KB-20260425-003"]` |
|
||||
| `previous_version` | string | 上一版本的 KB-ID | `KB-20260420-001` |
|
||||
| `superseded_by` | string | 被哪个新版本替代 | `KB-20260428-002` |
|
||||
| `aliases` | list | 别名/同义词 | `[Self-Attention, 自注意力机制]` |
|
||||
| `keywords` | list | 关键词（BM25 检索用） | `[attention, self-attention, transformer]` |
|
||||
| `summary` | string | 一句话摘要 | `"Transformer 是一种基于自注意力机制的序列建模架构"` |
|
||||
|
||||
### 6.3 可信度评分（confidence）
|
||||
|
||||
可信度不是"我信不信"，而是**来源的客观可靠程度**：
|
||||
|
||||
| source_type | confidence | 说明 |
|
||||
|-------------|-----------|------|
|
||||
| `official_doc` | 0.9 | 官方文档、法律文本 |
|
||||
| `literature` | 0.8 | 学术论文、经过同行评审 |
|
||||
| `experiment` | 0.7 | 自己实验验证过 |
|
||||
| `personal_exp` | 0.5 | 个人经验（可能有偏差） |
|
||||
| `social_media` | 0.3 | 社交媒体（可靠性低） |
|
||||
| `unknown` | 0.4 | 来源不明 |
|
||||
|
||||
**知识入库时的自动修正**：基础分 0.5，然后根据来源类型加减：
|
||||
- 官方文档/学术论文：+0.3
|
||||
- 知名技术博客/行业报告：+0.1
|
||||
- 个人博客/论坛帖子：-0.1
|
||||
- 未知来源/社交媒体：-0.3
|
||||
|
||||
---
|
||||
|
||||
## 七、知识生命周期
|
||||
|
||||
一条知识从"发现"到"归档"的完整生命周期：
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ 知识生命周期 │
|
||||
└──────────────────────────────────────────────────┘
|
||||
|
||||
① 发现/采集 ② 汇聚 ③ 提纯/分类
|
||||
┌───────────┐ ┌──────────┐ ┌───────────────┐
|
||||
│ 多平台采集 │───原始──→│ 收件箱 │──标准──→│ 分类 + 模板化 │
|
||||
│ B站/小红书 │ 内容 │ 00_inbox │ MD │ + ID 生成 │
|
||||
│ RSS/网页 │ │ │ │ + 去重检查 │
|
||||
└───────────┘ └──────────┘ └───────┬───────┘
|
||||
│
|
||||
┌─────────────────────────────────┤
|
||||
│ │
|
||||
▼ ▼
|
||||
④ 归档入库 ⑤ 持续进化
|
||||
┌──────────────┐ ┌──────────────────┐
|
||||
│ 按nature分配 │ │ 属性变更 │
|
||||
│ 到目标目录 │ │ opinion → fact │
|
||||
│ + domain子目录│ │ method v1 → v2 │
|
||||
│ + 更新统计 │ │ 过时 → archive │
|
||||
└──────────────┘ └──────────────────┘
|
||||
```
|
||||
|
||||
### 7.1 各阶段详情
|
||||
|
||||
#### 阶段①：自动采集
|
||||
|
||||
| 信息源 | 采集工具 | 保存位置 | 频率 |
|
||||
|--------|----------|----------|------|
|
||||
| B站/YouTube 订阅 | BiliNote | `50_resources/视频笔记/` | 每 30 分钟 |
|
||||
| 小红书博主 | TikOmni | `50_resources/灵感素材/` | 每 2 小时 |
|
||||
| 抖音账号 | TikOmni | `50_resources/灵感素材/` | 每 2 小时 |
|
||||
| RSS 订阅源 | feedparser | `40_references/` | 每 15 分钟 |
|
||||
| 指定网页 | Crawl4AI | `40_references/` | 每 1 小时 |
|
||||
|
||||
#### 阶段②：汇聚收件箱（collect_to_inbox 技能）
|
||||
|
||||
- **执行时间**：每日凌晨 2:30
|
||||
- **做什么**：扫描 `50_resources/`、`20_methods/`、`40_references/`、`01_daily/` 等目录中的文件，提取主要内容生成标准化 MD，放入 `00_inbox/`
|
||||
- **去重**：同名/同标题文件跳过，已标记 `collected: true` 的跳过
|
||||
|
||||
#### 阶段③：提纯分类（inbox_refine 技能）
|
||||
|
||||
- **执行时间**：每日凌晨 3:00
|
||||
- **做什么**：
|
||||
1. 读取 `00_inbox/` 所有文件
|
||||
2. 用本地 LLM（oMLX + Qwen 模型）或启发式规则判定 nature + domain
|
||||
3. 应用对应卡片模板
|
||||
4. 生成唯一 ID（格式 `KB-YYYYMMDD-NNN`）
|
||||
5. 去重检查（标题相似度 > 0.8 则合并）
|
||||
6. 写入目标目录
|
||||
7. 删除收件箱原文件
|
||||
8. 更新首页统计和变更日志
|
||||
|
||||
#### 阶段④：归档入库
|
||||
|
||||
归档后的知识文件名格式：`{标题}.md`，存储在 `{nature对应目录}/{domain}/` 下。
|
||||
|
||||
#### 阶段⑤：持续进化
|
||||
|
||||
| 变化类型 | 触发条件 | 处理 |
|
||||
|----------|----------|------|
|
||||
| 属性变更 | 观点被验证/事实被推翻 | 更新 nature，移动文件，更新内链 |
|
||||
| 版本升级 | 方法有更好的方案 | 保留旧版，新建 v2，双向链接 |
|
||||
| 过期归档 | 180 天未更新的技术知识 | 标记 `archived`，移入 `90_archive/` |
|
||||
| 知识修补 | 用户纠正 AI 输出 | 更新 confidence，记录修正日志 |
|
||||
|
||||
---
|
||||
|
||||
## 八、自动分类的实现机制
|
||||
|
||||
### 8.1 LLM 分类（主要方式）
|
||||
|
||||
使用本地 LLM（oMLX + Qwen2.5-VL-3B）调用以下提示词进行分类：
|
||||
|
||||
```
|
||||
你是一个知识分类助手。请对以下内容进行分析，返回 JSON 格式。
|
||||
|
||||
输入：{{content}}
|
||||
|
||||
输出：
|
||||
{
|
||||
"domain": ["领域1", "领域2"], // 从16个领域中选择1-3个
|
||||
"nature": "fact", // 从9种属性中选择
|
||||
"confidence": 0.85, // 可信度评分
|
||||
"tags": ["标签1", "标签2"], // 3-5个标签
|
||||
"summary": "一句话摘要" // 60字以内
|
||||
}
|
||||
```
|
||||
|
||||
**降级机制**：当 LLM 不可用时，自动切换到基于关键词的启发式规则分类。
|
||||
|
||||
### 8.2 置信度阈值
|
||||
|
||||
- LLM 分类信心度 ≥ 0.4 → 采用 LLM 结果
|
||||
- LLM 分类信心度 < 0.4 → 保留在 `00_inbox/`，标记 `#待分类`，等人工处理
|
||||
|
||||
### 8.3 去重策略
|
||||
|
||||
| 检测维度 | 阈值 | 处理 |
|
||||
|----------|------|------|
|
||||
| 标题完全一致 | 100% | 跳过，记录日志 |
|
||||
| 标题相似度 | > 0.8 | 合并（补充细节到已有文件） |
|
||||
| 内容完全一致 | 100% | 跳过 |
|
||||
| 同一事实新旧矛盾 | — | 新事实覆盖，旧值写入 `previous_version` |
|
||||
|
||||
---
|
||||
|
||||
## 九、知识检索机制
|
||||
|
||||
### 9.1 检索分层
|
||||
|
||||
```
|
||||
用户提问
|
||||
↓
|
||||
L1 关键词索引（BM25） ←── 快速粗筛
|
||||
├─ 无匹配 → 返回"无相关记忆"
|
||||
└─ 有匹配 ↓
|
||||
L2 结构化摘要（SQLite facts.db） ←── 精确匹配
|
||||
├─ 置信度 ≥ 0.7 → 返回摘要
|
||||
└─ 置信度 < 0.7 → 截止，返回"无高置信结果"
|
||||
↓
|
||||
【不自动加载原文】
|
||||
仅用户明确要求时 → L3 按行号加载原文片段
|
||||
```
|
||||
|
||||
### 9.2 混合检索
|
||||
|
||||
- **BM25（关键词匹配）**：适合精确术语检索，如"RAG"、"transformer"
|
||||
- **向量检索（ChromaDB + Qwen3-Embedding-0.6B）**：适合语义相似检索，如"怎么让 AI 记住之前说过的话"
|
||||
- **RRF（倒数秩融合）**：将两路结果合并排序
|
||||
|
||||
### 9.3 检索不加载全文
|
||||
|
||||
这是关键设计——检索时只返回摘要和行号片段，不加载整个文件。原因：
|
||||
1. **节省 token**：一个知识文件可能有几千字，但用户只需要其中的一个段落
|
||||
2. **保护隐私**：L3 原文层不暴露给外部 API
|
||||
3. **按需加载**：用户看到摘要后，觉得需要更多细节，再按行号加载指定片段
|
||||
|
||||
---
|
||||
|
||||
## 十、版本管理与时间线
|
||||
|
||||
### 10.1 三种变化类型
|
||||
|
||||
| 变化类型 | 举例 | 处理 |
|
||||
|----------|------|------|
|
||||
| **硬事实改变** | 服务器配置从 4C8G → 8C16G | 原地更新，旧值写入 `previous_version` |
|
||||
| **软升级** | 方法 V1 → V2（V1 仍有参考价值） | 保留 V1 文件，新建 V2，通过 `related` 双向链接 |
|
||||
| **观点→事实** | 推测经过验证变为可靠知识 | 更新 `nature`，提升 `confidence`，移动到对应目录 |
|
||||
|
||||
### 10.2 版本链
|
||||
|
||||
每条知识的 Frontmatter 中维护版本信息：
|
||||
|
||||
```yaml
|
||||
version: 2
|
||||
previous_version: KB-20260420-001 # 我是从哪个版本进化来的
|
||||
superseded_by: "" # 我是否被新版本替代（空=当前有效）
|
||||
```
|
||||
|
||||
当一条知识经过 **3 次以上重要更新**，系统自动在 `99_system/timelines/` 下生成 Mermaid 时间线图。
|
||||
|
||||
---
|
||||
|
||||
## 十一、中文映射机制
|
||||
|
||||
### 11.1 为什么用英文目录名？
|
||||
|
||||
- **跨平台兼容**：中文路径在 Windows/Git/NFS 等环境下容易出现编码问题
|
||||
- **脚本友好**：Shell 脚本、Python 路径拼接不会因为中文出 bug
|
||||
- **Git 友好**：避免提交时的文件名编码歧义
|
||||
|
||||
### 11.2 中文映射怎么工作？
|
||||
|
||||
`folder-aliases.json` 提供完整的目录中文映射：
|
||||
|
||||
```json
|
||||
{
|
||||
"knowledge": {
|
||||
"00_inbox": "收件箱",
|
||||
"10_concepts": "概念层",
|
||||
"20_methods": "方法层",
|
||||
"30_facts": "事实层",
|
||||
...
|
||||
},
|
||||
"concepts_domains": {
|
||||
"cs": "计算机科学",
|
||||
"ai": "人工智能",
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**使用场景**：
|
||||
- LLM 分类时，输出中文领域名（"人工智能"），系统查表得到英文目录名（`ai`），用于拼接物理路径
|
||||
- 知识库首页展示时，读取映射表显示中文名称
|
||||
- 日志和通知中显示中文名，方便阅读
|
||||
|
||||
---
|
||||
|
||||
## 十二、配置文件清单
|
||||
|
||||
知识管理系统的所有配置集中在 `99_system/` 目录下：
|
||||
|
||||
| 文件 | 路径 | 作用 |
|
||||
|------|------|------|
|
||||
| 领域分类表 | `99_system/taxonomies/domains.md` | 定义 16 个一级领域及其子领域 |
|
||||
| 属性分类表 | `99_system/taxonomies/nature-types.md` | 定义 9 种 nature 类型 + 分类决策树 |
|
||||
| 中文映射 | `99_system/taxonomies/folder-aliases.json` | 英文目录 ↔ 中文名映射（JSON） |
|
||||
| 概念卡片模板 | `99_system/templates/concept-card.md` | 概念/公理知识模板 |
|
||||
| 方法卡片模板 | `99_system/templates/method-card.md` | 方法/教程知识模板 |
|
||||
| 事实卡片模板 | `99_system/templates/fact-card.md` | 事实/法规/数据知识模板 |
|
||||
| 个人洞见模板 | `99_system/templates/personal-insight-card.md` | 个人见解/反思模板 |
|
||||
| 分类提示词 | `99_system/prompts/classify-knowledge.md` | LLM 自动分类的 Prompt 模板 |
|
||||
|
||||
---
|
||||
|
||||
## 十三、自动化任务时间表
|
||||
|
||||
知识管理涉及的定时任务：
|
||||
|
||||
| 时间 | 任务 | 技能 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 02:00 | 每日记忆提炼 | memory_manager | 提炼昨日对话为结构化记忆 |
|
||||
| 02:30 | 收件箱汇聚 | collect_to_inbox | 扫描各目录 → 提取 → 放入 00_inbox |
|
||||
| 03:00 | 收件箱提纯 | inbox_refine | 00_inbox → 分类 + 模板化 → 归档 |
|
||||
| 23:00 | 采集日报汇总 | auto_collector | 汇总当日采集数据 |
|
||||
|
||||
---
|
||||
|
||||
## 十四、操作速查
|
||||
|
||||
### 14.1 手动操作命令
|
||||
|
||||
| 操作 | 说/触发词 | 系统行为 |
|
||||
|------|-----------|----------|
|
||||
| 入库知识 | "入库"、"保存知识" | 内容 → `00_inbox/` |
|
||||
| 提纯收件箱 | "提纯"、"inbox refine" | `00_inbox/` → 分类归档 |
|
||||
| 汇聚收件箱 | "归集"、"collect inbox" | 各目录 → `00_inbox/` |
|
||||
| 知识检索 | "查知识库"、"知识检索" | L2 摘要检索 → 返回结果 |
|
||||
| 重分类 | "知识重分类" | 更新 nature → 移动文件 |
|
||||
| 备份知识库 | "知识备份" | 全量/增量备份 |
|
||||
|
||||
### 14.2 手动添加知识的步骤
|
||||
|
||||
1. 将内容保存到 `00_inbox/`（手动创建 .md 文件，或说"入库 xxx"）
|
||||
2. 系统会在下次提纯时（凌晨 3:00 或手动触发）自动分类
|
||||
3. 分类后可在对应目录找到标准化知识卡片
|
||||
|
||||
### 14.3 直接归档（跳过收件箱）
|
||||
|
||||
对于已经有明确分类的知识，可以直接使用 `kb_manager` 的入库功能指定 nature 和 domain，跳过收件箱直接写入目标目录。
|
||||
|
||||
---
|
||||
|
||||
## 十五、知识库首页统计
|
||||
|
||||
知识库首页 `README.md` 自动维护统计信息：
|
||||
|
||||
```
|
||||
| 英文目录 | 中文名称 | 文件数 | 最近更新 |
|
||||
|----------|----------|--------|----------|
|
||||
| 10_concepts | 概念层 | 1 | 2026-04-28 |
|
||||
| 20_methods | 方法层 | 0 | — |
|
||||
| 30_facts | 事实层 | 0 | — |
|
||||
| ... | ... | ... | ... |
|
||||
```
|
||||
|
||||
每次 inbox_refine 执行后自动刷新。
|
||||
|
||||
变更日志 `CHANGELOG.md` 记录每次归档操作：
|
||||
|
||||
```markdown
|
||||
## 2026-04-28
|
||||
|
||||
### 归档
|
||||
- [concept] 测试 LLM 分类器 → 10_concepts/ (KB-20260428-001)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十六、总结：知识管理系统的核心逻辑
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ 设计哲学 │
|
||||
│ │
|
||||
│ ① 知识是活的：可以进化、可以被修正、有过期时间 │
|
||||
│ ② 分类是正交的：属性（nature）× 领域（domain） │
|
||||
│ ③ 自动化优先：采集→汇聚→提纯→归档 全自动 │
|
||||
│ ④ 可追溯性：每条知识都有来源、版本链、变更记录 │
|
||||
│ ⑤ 可信度量化：不回避不确定性，用 confidence 评分表达 │
|
||||
│ ⑥ 检索不加载：按需获取片段，节省 token │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**一句话总结**：这是一个以 Obsidian Markdown 文件为基础、以 LLM 为分类引擎、以自动化任务为驱动、以版本化管理为保障的**全链路知识加工流水线**。
|
||||
@@ -0,0 +1,106 @@
|
||||
# AgentOS 项目变更日志
|
||||
|
||||
## [2.0.2] - 2026-04-28
|
||||
|
||||
### 文档收口
|
||||
|
||||
- 新增 `REVIEW-V2.0.md`，正式记录原形、当前实现与后续升级设想之间的差异
|
||||
- 新增 `V2.0-SUMMARY.md`，作为面向使用者的最新说明汇总
|
||||
- 重写 `CORE-ARCHITECTURE.md`，将当前仓库冻结为 AgentOS v2.0 基准定义
|
||||
- 重写 `README.md`，统一项目入口与当前基准说明
|
||||
- 更新 `QUICKSTART.md`，补充双根目录与软链接边界
|
||||
- 重写 `SKILLS-CATALOG.md`，收口为 v2.0 技能目录
|
||||
- 更新 `REQUIREMENTS.md`，移除过期运行状态并对齐 v2.0 口径
|
||||
- 将 `AgentOS-完整说明文档_副本.md` 正式归档到 `90_archive/docs/`，原路径保留跳转页
|
||||
|
||||
### 架构决策
|
||||
|
||||
- 明确 `agent-os/` 与 `agent-os-local/` 的双根目录边界
|
||||
- 明确 `04_memory/` 中共享内容与本机私有内容的分界
|
||||
- 明确 v2.0 采用“双入口汇聚到 Inbox”的知识流定义
|
||||
- 明确 `05_tools/` 是工具层，不默认等于技能层
|
||||
- 明确 `category` / `SKILL_CARD.yaml` / `collect_from_local.py` 等能力延后到后续版本
|
||||
|
||||
## [2.0.1] - 2026-04-25
|
||||
|
||||
### 修复
|
||||
|
||||
- **依赖管理统一**：删除旧的 `04_memory/vector_db/.venv`，统一使用 managed Python 专用 venv
|
||||
- 旧路径：`~/workbuddy-agent-os/agent-sync/04_memory/vector_db/.venv`（分散，与脚本运行环境不一致）
|
||||
- 新路径：`~/.workbuddy/binaries/python/envs/agent-os/`（统一，脚本和自动化共用）
|
||||
- **init.sh 修复**：指向新 venv，用 `requirements.txt` 安装依赖
|
||||
- **daily_digest.py 重写**：接入三个真实数据源（Claw 工作日志、WorkBuddy 系统画像、上轮摘要）
|
||||
- **自动化任务修复**：Python 路径更新为新 venv
|
||||
|
||||
### 新增
|
||||
|
||||
- **bootstrap_from_memory.py**：冷启动脚本，首次运行时将已有 MEMORY.md 灌入 L1/L2
|
||||
- **requirements.txt**：集中声明 Python 依赖（trafilatura + sqlite-utils）
|
||||
- **WorkBuddy 自动化**：每日凌晨 2:00 自动执行 `daily_digest.py`（ID: `agentos`）
|
||||
- **冷启动执行**：L2 写入 36 条初始事实，L1 索引同步建立
|
||||
|
||||
### 文档更新
|
||||
|
||||
- **REQUIREMENTS.md**：修正 venv 路径、更新实际设备状态、写清固定安装命令、新增自动化配置说明
|
||||
- **QUICKSTART.md**：新增步骤 4（冷启动记忆体）、修正坚果云路径为 `~/NutstoreCloudBridge/`
|
||||
- **README.md**：新增记忆数据流说明、固定路径速查表、补全目录说明
|
||||
|
||||
## [2.0.0] - 2026-04-25
|
||||
|
||||
### 新增
|
||||
|
||||
#### 核心框架
|
||||
- L0→L1→L2→L3 四级记忆模型
|
||||
- SOUL.md v2.0：完整的三层规则体系（硬约束/软约束/学习规则）
|
||||
- IDENTITY.md v2.0：Claw 身份档案，含设备信息自动填充
|
||||
- USER.md v2.0：ghai 用户档案
|
||||
- mcp.json：MCP 协议基础配置模板
|
||||
|
||||
#### 初始化脚本
|
||||
- init.sh：自动创建目录、安装依赖、填充设备信息
|
||||
- apply-config.sh：核心配置部署到 ~/.workbuddy/
|
||||
- import_skills.sh：技能导入
|
||||
- export_skills.sh：技能打包导出
|
||||
|
||||
#### 技能包
|
||||
- memory_manager：每日对话提炼、去重、冲突检测、版本管理
|
||||
- daily_digest.py：每日提炼脚本（凌晨 2:00 自动运行）
|
||||
- bootstrap_from_memory.py：冷启动（首次导入已有记忆）
|
||||
- memory_cleanup.py：冲突消解与过期清理
|
||||
- agent_memory_init.py：记忆体初始化
|
||||
- kb_manager：知识库入库、分类、检索、备份
|
||||
- kb_ingest.py：知识入库脚本（支持 URL/文件/文本）
|
||||
- _template：技能模板（SKILL.md + version.json + skill.py）
|
||||
- web_crawler：网页抓取（占位）
|
||||
- sync_manager：同步管理（占位，由坚果云替代）
|
||||
|
||||
#### 知识库
|
||||
- 按属性分层目录结构（概念/方法/事实/参考/资源/观点）
|
||||
- 16 个一级领域子目录
|
||||
- 知识卡片模板（概念卡/事实卡/方法卡/个人洞见卡）
|
||||
- 领域分类表（domains.md）
|
||||
- 知识属性分类表（nature-types.md + 分类决策树）
|
||||
- 中文映射配置（folder-aliases.json）
|
||||
- 知识分类提示词模板
|
||||
|
||||
#### 迁移脚本
|
||||
- pack.sh：全量打包
|
||||
- unpack.sh：解包还原
|
||||
- backup.sh：手动备份
|
||||
|
||||
#### 说明文件
|
||||
- README.md：项目概览
|
||||
- QUICKSTART.md：5 分钟快速上手
|
||||
- REQUIREMENTS.md：环境依赖清单
|
||||
- CHANGELOG.md：本文件
|
||||
|
||||
### 设计决策
|
||||
|
||||
| 决策 | 选择 | 原因 |
|
||||
|---|---|---|
|
||||
| 知识库物理目录分层 | 按属性（概念/方法/事实/...）为第一层 | 人找知识先想"类型"再想"领域"，机器检索空间更小 |
|
||||
| 记忆读取策略 | L2 置信度不足直接截断，不 fallback 到 L3 | 节省 token，避免无关信息干扰 |
|
||||
| 跨机同步 | 坚果云，不用 Git | 国内访问 Git 不稳定 |
|
||||
| 存储策略 | 单条存储线 + 平台自适应 | 避免数据分裂，init.sh 自动检测系统 |
|
||||
| 目录命名 | 英文文件夹名 + 中文映射 | 机器兼容性 + 人类可读性 |
|
||||
| Python 环境 | managed Python + 专用 venv | 不污染系统环境，版本可控 |
|
||||
@@ -0,0 +1,217 @@
|
||||
# CORE-ARCHITECTURE.md —— AgentOS v2.0 基准定义
|
||||
|
||||
最后更新：2026-04-28
|
||||
|
||||
本文档是 AgentOS v2.0 的正式基准。后续若其他大体量说明与本文冲突，以本文为准。
|
||||
|
||||
## 1. v2.0 的定位
|
||||
|
||||
AgentOS v2.0 是一套运行在 WorkBuddy 上的本地优先个人智能体外骨骼系统。
|
||||
|
||||
它不是最早的单机原形复刻，也不是未来多机协同终态，而是当前仓库中已经落地并可恢复的一版稳定基准。
|
||||
|
||||
v2.0 只做三件事：
|
||||
|
||||
- 冻结当前可运行结构
|
||||
- 明确同步与本地边界
|
||||
- 统一文档口径，避免把未来升级方案混入当前实现
|
||||
|
||||
## 2. 根目录模型
|
||||
|
||||
### 2.1 `~/workbuddy-agent-os/agent-sync/`
|
||||
|
||||
作用：同步与版本化的主仓库。
|
||||
|
||||
应放入：
|
||||
|
||||
- 核心配置
|
||||
- 技能层
|
||||
- 知识库
|
||||
- 共享记忆元数据
|
||||
- 工具脚本
|
||||
- 迁移脚本
|
||||
- 说明文档
|
||||
|
||||
### 2.2 `~/workbuddy-agent-os/agent-sync/agent-local/`
|
||||
|
||||
作用：本机私有数据区，不进入主仓库，不作为 v2.0 的主文档对象，但作为正式运行边界的一部分存在。
|
||||
|
||||
应放入：
|
||||
|
||||
- L3 原文
|
||||
- 向量库
|
||||
- 临时缓存
|
||||
- 原始素材
|
||||
- 已提炼待投递素材
|
||||
|
||||
## 3. 目录职责
|
||||
|
||||
| 目录 | v2.0 职责 | 是否共享 |
|
||||
|------|-----------|----------|
|
||||
| `00_bootstrap/` | 初始化、部署、导入导出 | 是 |
|
||||
| `01_core/` | SOUL、IDENTITY、USER、MCP 配置 | 是 |
|
||||
| `02_skills/` | WorkBuddy 技能层 | 是 |
|
||||
| `03_knowledge/` | Obsidian 知识库 | 是 |
|
||||
| `04_memory/` | 事实库、摘要、日志与本地挂载点 | 部分共享 |
|
||||
| `05_tools/` | 公共工具层 | 是 |
|
||||
| `06_runtime/` | 任务记录与缓存挂载点 | 部分共享 |
|
||||
| `07_migration/` | 打包、解包、备份 | 是 |
|
||||
|
||||
## 4. 本地挂载与共享边界
|
||||
|
||||
### 4.1 正式共享内容
|
||||
|
||||
以下内容属于 v2.0 的共享资产：
|
||||
|
||||
- `01_core/`
|
||||
- `02_skills/`
|
||||
- `03_knowledge/`
|
||||
- `04_memory/long_term/facts.db`
|
||||
- `04_memory/daily_summaries/`
|
||||
- `04_memory/logs/`
|
||||
- `05_tools/`
|
||||
- `06_runtime/tasks/`
|
||||
- `07_migration/`
|
||||
|
||||
### 4.2 正式本机私有内容
|
||||
|
||||
以下内容属于 v2.0 的本机私有资产：
|
||||
|
||||
- `04_memory/long_term/raw/`
|
||||
- `04_memory/vector_db/`
|
||||
- `06_runtime/cache/`
|
||||
- `~/workbuddy-agent-os/agent-sync/agent-local/materials/`
|
||||
|
||||
### 4.3 软链接映射
|
||||
|
||||
当前正式映射如下：
|
||||
|
||||
```text
|
||||
~/workbuddy-agent-os/agent-sync/04_memory/long_term/raw -> ~/workbuddy-agent-os/agent-sync/agent-local/memory/raw
|
||||
~/workbuddy-agent-os/agent-sync/04_memory/vector_db -> ~/workbuddy-agent-os/agent-sync/agent-local/memory/vector_db
|
||||
~/workbuddy-agent-os/agent-sync/06_runtime/cache -> ~/workbuddy-agent-os/agent-sync/agent-local/runtime/cache
|
||||
```
|
||||
|
||||
`init.sh` 负责重建这些映射。
|
||||
|
||||
## 5. v2.0 的正式数据流
|
||||
|
||||
### 5.1 知识流
|
||||
|
||||
v2.0 明确定义为“双入口汇聚到 Inbox”。
|
||||
|
||||
入口 A：直接入 Inbox
|
||||
|
||||
- 已经标准化的内容可以直接写入 `03_knowledge/00_inbox/`
|
||||
|
||||
入口 B：分类目录汇聚
|
||||
|
||||
- 内容先写入 `50_resources/`、`01_daily/`、`20_methods/`、`40_references/` 等目录
|
||||
- 再由 `collect_to_inbox` 汇聚进 `00_inbox/`
|
||||
|
||||
统一出口：
|
||||
|
||||
- `inbox_refine` 将 `00_inbox/` 内容提纯归档到知识库目标目录
|
||||
|
||||
因此，v2.0 不再把这两种入口视为冲突，而是视为同一流水线的两种合法前置路径。
|
||||
|
||||
### 5.2 记忆流
|
||||
|
||||
当前记忆流为：
|
||||
|
||||
```text
|
||||
WorkBuddy 工作日志 / 系统画像 / 上轮摘要
|
||||
-> daily_digest.py
|
||||
-> facts.db
|
||||
-> keyword_index.json / ChromaDB
|
||||
-> 原文写入本机私有 raw/
|
||||
```
|
||||
|
||||
### 5.3 工具流
|
||||
|
||||
`05_tools/` 是工具层，不等于技能层。
|
||||
|
||||
v2.0 允许在工具层中存在：
|
||||
|
||||
- 系统检查脚本
|
||||
- 抓取工具
|
||||
- 媒体处理脚本
|
||||
- 独立小项目
|
||||
|
||||
但这些工具默认不自动视为对话技能。
|
||||
|
||||
## 6. 技能分类
|
||||
|
||||
### 6.1 system 技能
|
||||
|
||||
system 技能是架构层约定，表示后台自动运行或以系统流程为主：
|
||||
|
||||
- `memory_manager`
|
||||
- `collect_to_inbox`
|
||||
- `inbox_refine`
|
||||
- `auto_collector`
|
||||
- `kb_manager`
|
||||
- `sync_manager`
|
||||
|
||||
### 6.2 user 技能
|
||||
|
||||
user 技能是对话直接触发的入口层：
|
||||
|
||||
- `content_processor`
|
||||
- `web_crawler`
|
||||
|
||||
### 6.3 约束说明
|
||||
|
||||
v2.0 仅把 system / user 作为文档级约定。
|
||||
|
||||
以下能力不在 v2.0 强制落地：
|
||||
|
||||
- `category` 元数据全量补齐
|
||||
- `SKILL_CARD.yaml`
|
||||
- `skill_scanner.py`
|
||||
|
||||
这些属于后续版本。
|
||||
|
||||
## 7. 初始化与恢复基准
|
||||
|
||||
v2.0 的正式恢复步骤如下：
|
||||
|
||||
```bash
|
||||
cd ~/workbuddy-agent-os/agent-sync/00_bootstrap
|
||||
bash init.sh
|
||||
bash apply-config.sh
|
||||
bash import_skills.sh
|
||||
|
||||
~/.workbuddy/binaries/python/envs/agent-os/bin/python3 \
|
||||
~/workbuddy-agent-os/agent-sync/02_skills/memory_manager/bootstrap_from_memory.py \
|
||||
--root ~/workbuddy-agent-os/agent-sync
|
||||
```
|
||||
|
||||
手动部分：
|
||||
|
||||
- 安装 WorkBuddy
|
||||
- 安装坚果云
|
||||
- 按需安装 Obsidian
|
||||
- 安装 oMLX 与模型
|
||||
|
||||
## 8. v2.0 延后项
|
||||
|
||||
以下内容明确不属于 v2.0：
|
||||
|
||||
- 本地素材统一投递脚本 `collect_from_local.py`
|
||||
- 技能身份证与统一扫描器
|
||||
- 工具 manifest 与自动化安装体系
|
||||
- 更细粒度的多机记忆隔离策略
|
||||
- 基于 `agent-os-local/materials/` 的全新单入口采集体系
|
||||
|
||||
这些内容如果要做，必须以 v2.1 或更高版本单独立项。
|
||||
|
||||
## 9. 验收标准
|
||||
|
||||
满足以下条件，即视为 v2.0 收口完成：
|
||||
|
||||
1. 核心文档不再互相冲突
|
||||
2. 目录边界和软链接边界明确
|
||||
3. 恢复步骤可以从文档直接执行
|
||||
4. 知识流与记忆流可以一句话解释清楚
|
||||
5. 延后项不再混入当前基准描述
|
||||
@@ -0,0 +1,174 @@
|
||||
# AgentOS v2.0 审查与收口文档
|
||||
|
||||
最后更新：2026-04-28
|
||||
|
||||
## 1. 审查范围
|
||||
|
||||
本次审查只做一件事：把 AgentOS 的原形、当前实现、未来升级想法彻底拆开，收口成一个可执行的 v2.0 基准。
|
||||
|
||||
审查对象包括：
|
||||
|
||||
- 根目录说明文档
|
||||
- `00_bootstrap/` 初始化与部署脚本
|
||||
- `01_core/` 核心配置
|
||||
- `02_skills/` 当前已落地技能
|
||||
- `03_knowledge/` 知识库结构与收件箱流水线
|
||||
- `04_memory/` 记忆体与本地私有目录边界
|
||||
- `05_tools/` 工具层
|
||||
- `07_migration/` 迁移脚本
|
||||
|
||||
## 2. 审查结论
|
||||
|
||||
### 结论 A：当前仓库不是原形复刻，而是原形之后的第一阶段增强版
|
||||
|
||||
原形是一个单机优先、骨架优先、目录清晰的 AgentOS。
|
||||
|
||||
当前仓库已经在原形之上新增：
|
||||
|
||||
- `agent-os-local/` 本机私有目录
|
||||
- 软链接隔离（raw、vector_db、cache）
|
||||
- `collect_to_inbox` / `inbox_refine` 收件箱双阶段流水线
|
||||
- `content_processor` / `auto_collector` 等扩展技能
|
||||
- WorkBuddy managed Python / Node 运行时约束
|
||||
- MCP 与本地 LLM 运行时集成
|
||||
|
||||
因此，当前仓库应被定义为“v2.0 基准版”，而不是“原形本身”。
|
||||
|
||||
### 结论 B：主要问题是文档基线失真，不是代码主干先坏了
|
||||
|
||||
目前最大问题不是脚本无法运行，而是多个文档分别在描述不同阶段：
|
||||
|
||||
- 有的描述原形
|
||||
- 有的描述当前实现
|
||||
- 有的描述未来升级设想
|
||||
|
||||
结果是同一件事出现多套口径，尤其集中在：
|
||||
|
||||
- 版本号
|
||||
- 技能数量
|
||||
- 知识流入口
|
||||
- 记忆同步边界
|
||||
- `05_tools/` 与 `02_skills/` 的职责划分
|
||||
|
||||
### 结论 C：v2.0 需要冻结一条“当前可运行”的基准，而不是继续把 v2.1 设想混进来
|
||||
|
||||
v2.0 的目标不是把所有未来升级一次做完，而是把当前仓库收口成：
|
||||
|
||||
- 文档统一
|
||||
- 边界明确
|
||||
- 路径一致
|
||||
- 恢复流程明确
|
||||
- 延后项清楚标注
|
||||
|
||||
## 3. 核心发现
|
||||
|
||||
### 高优先级
|
||||
|
||||
1. 知识流入口存在两种合法路径，但之前没有被正式定义
|
||||
|
||||
- 路径一：内容已标准化，直接写入 `03_knowledge/00_inbox/`
|
||||
- 路径二：内容先落在分类目录，再由 `collect_to_inbox` 汇聚进 `00_inbox/`
|
||||
|
||||
此前文档把它写成互相冲突。v2.0 统一定义为“双入口汇聚到 Inbox”，不再视为矛盾。
|
||||
|
||||
2. `04_memory/` 与 `agent-os-local/` 的边界缺少一句话定义
|
||||
|
||||
v2.0 统一定义：
|
||||
|
||||
- 共享并可同步：`facts.db`、`daily_summaries/`、`logs/`
|
||||
- 本机私有：`long_term/raw/`、`vector_db/`、`06_runtime/cache/`
|
||||
|
||||
3. `05_tools/` 在原形中是空骨架，在当前实现中已经变成工具层
|
||||
|
||||
v2.0 统一定义：
|
||||
|
||||
- `02_skills/` 是 WorkBuddy 技能层
|
||||
- `05_tools/` 是底层公共工具层
|
||||
- 工具层中允许存在独立小项目，但不自动视为对话技能
|
||||
|
||||
### 中优先级
|
||||
|
||||
4. system/user 技能分类已成为架构约定，但尚未有统一元数据强制落地
|
||||
|
||||
v2.0 结论：保留该分类作为文档级约定，不在本版本强推 `SKILL_CARD.yaml`、`skill_scanner.py`。
|
||||
|
||||
5. `agent-os-local/materials/` 已经存在，但尚未成为系统主数据入口
|
||||
|
||||
v2.0 结论：
|
||||
|
||||
- 它是本机原始素材存储区
|
||||
- 它服务于工具层与后续升级
|
||||
- 它不作为 v2.0 的唯一入库入口
|
||||
|
||||
### 低优先级
|
||||
|
||||
6. 大体量说明文档信息很多，但不适合作为唯一基准
|
||||
|
||||
v2.0 结论：
|
||||
|
||||
- 保留该文件作为扩展历史说明
|
||||
- 以 `README.md`、`CORE-ARCHITECTURE.md`、本文件为正式基准
|
||||
|
||||
## 4. v2.0 最终定稿
|
||||
|
||||
### 4.1 当前基准
|
||||
|
||||
AgentOS v2.0 是一套运行在 WorkBuddy 上的本地优先个人智能体外骨骼系统，当前以以下结构为正式基准：
|
||||
|
||||
- `agent-os/`：同步与版本化的主仓库
|
||||
- `agent-os-local/`：本机私有数据区
|
||||
- `01_core/`：核心配置
|
||||
- `02_skills/`：技能层
|
||||
- `03_knowledge/`：Obsidian 知识库
|
||||
- `04_memory/`：共享记忆元数据与结构化事实
|
||||
- `05_tools/`：公共工具层
|
||||
- `06_runtime/`：任务记录与缓存挂载点
|
||||
- `07_migration/`：迁移与打包
|
||||
|
||||
### 4.2 目标表述
|
||||
|
||||
v2.0 的正式目标表述如下：
|
||||
|
||||
> AgentOS v2.0 不是“未来多机协同终态”，而是“当前仓库的稳定可运行基准版”。
|
||||
> 它保留原形的骨架清晰性，同时承认已经落地的本地私有层、收件箱流水线和工具层增强。
|
||||
> v2.0 的任务是冻结边界、统一口径、保证可恢复、为 v2.1 升级留出明确接口。
|
||||
|
||||
### 4.3 明确不纳入 v2.0 的内容
|
||||
|
||||
以下内容属于后续版本，不纳入本次收口：
|
||||
|
||||
- `collect_from_local.py` 本地素材统一提炼入口
|
||||
- `skill_scanner.py` 和统一技能身份证体系
|
||||
- `SKILL_CARD.yaml` 全量改造
|
||||
- `setup_tools.sh` 与工具 manifest 规范
|
||||
- 更细粒度的记忆多机隔离策略
|
||||
|
||||
## 5. 修改计划
|
||||
|
||||
### 已完成
|
||||
|
||||
1. 统一 v2.0 基准文档入口
|
||||
2. 固化审查结论
|
||||
3. 统一当前基准与目标表述
|
||||
4. 将历史大文档降级为参考资料
|
||||
|
||||
### v2.0 收口后可继续执行
|
||||
|
||||
1. 先做 `collect_to_inbox` 与 `content_processor` 的入口契约统一
|
||||
2. 再做 `agent-os-local/materials/` 到 `00_inbox/` 的新流水线
|
||||
3. 最后补技能元数据和工具 manifest
|
||||
|
||||
## 6. 使用原则
|
||||
|
||||
从本文件起，后续若出现文档冲突，按以下优先级理解：
|
||||
|
||||
1. `CORE-ARCHITECTURE.md`
|
||||
2. `README.md`
|
||||
3. `REVIEW-V2.0.md`
|
||||
4. 其他大体量说明文件
|
||||
|
||||
这意味着：
|
||||
|
||||
- 大说明文档用于补充背景
|
||||
- 正式口径以基准文档为准
|
||||
- 升级想法必须单独标注版本，不得直接混入 v2.0 基准
|
||||
@@ -0,0 +1,133 @@
|
||||
# AgentOS v2.0 最新说明汇总
|
||||
|
||||
最后更新：2026-04-28
|
||||
|
||||
## 1. 当前版本是什么
|
||||
|
||||
AgentOS v2.0 是当前仓库的稳定可运行基准版。
|
||||
|
||||
它不是最初的单机原形，也不是未来多机协同终态，而是已经落地并能恢复的一版正式基线。
|
||||
|
||||
## 2. 当前正式文档入口
|
||||
|
||||
请按以下顺序阅读：
|
||||
|
||||
1. `CORE-ARCHITECTURE.md`：正式基准、目录边界、数据流定义
|
||||
2. `V2.0-SUMMARY.md`：本文件，最新说明汇总
|
||||
3. `QUICKSTART.md`：初始化与恢复操作
|
||||
4. `REQUIREMENTS.md`：环境要求与依赖说明
|
||||
5. `SKILLS-CATALOG.md`：v2.0 技能目录
|
||||
6. `REVIEW-V2.0.md`：审查结论与收口原因
|
||||
|
||||
历史大体量说明已归档到：
|
||||
|
||||
- `90_archive/docs/AgentOS-完整说明文档_副本.v2.1-history.md`
|
||||
|
||||
## 3. v2.0 一句话结构
|
||||
|
||||
```text
|
||||
agent-os/ = 共享主仓库
|
||||
agent-os-local/ = 本机私有目录
|
||||
```
|
||||
|
||||
主仓库负责：配置、技能、知识、共享记忆元数据、工具、迁移脚本。
|
||||
|
||||
本机私有目录负责：L3 原文、向量库、缓存、原始素材和待投递素材。
|
||||
|
||||
## 4. v2.0 正式边界
|
||||
|
||||
### 共享内容
|
||||
|
||||
- `01_core/`
|
||||
- `02_skills/`
|
||||
- `03_knowledge/`
|
||||
- `04_memory/long_term/facts.db`
|
||||
- `04_memory/daily_summaries/`
|
||||
- `04_memory/logs/`
|
||||
- `05_tools/`
|
||||
- `06_runtime/tasks/`
|
||||
- `07_migration/`
|
||||
|
||||
### 本机私有内容
|
||||
|
||||
- `04_memory/long_term/raw/`
|
||||
- `04_memory/vector_db/`
|
||||
- `06_runtime/cache/`
|
||||
- `~/workbuddy-agent-os/agent-sync/agent-local/materials/`
|
||||
|
||||
## 5. v2.0 正式数据流
|
||||
|
||||
### 知识流
|
||||
|
||||
v2.0 采用“双入口汇聚到 Inbox”：
|
||||
|
||||
- 入口 A：标准化内容直接写入 `03_knowledge/00_inbox/`
|
||||
- 入口 B：分类目录内容由 `collect_to_inbox` 汇聚到 `00_inbox/`
|
||||
- 统一出口：`inbox_refine` 提纯归档
|
||||
|
||||
### 记忆流
|
||||
|
||||
```text
|
||||
WorkBuddy 工作日志 / 系统画像 / 上轮摘要
|
||||
-> daily_digest.py
|
||||
-> facts.db
|
||||
-> keyword_index.json / ChromaDB
|
||||
-> 原文写入本机 raw/
|
||||
```
|
||||
|
||||
### 工具流
|
||||
|
||||
`05_tools/` 是工具层，不默认等于技能层。
|
||||
|
||||
## 6. v2.0 技能分组
|
||||
|
||||
### system 技能
|
||||
|
||||
- `memory_manager`
|
||||
- `collect_to_inbox`
|
||||
- `inbox_refine`
|
||||
- `auto_collector`
|
||||
- `kb_manager`
|
||||
- `sync_manager`
|
||||
|
||||
### user 技能
|
||||
|
||||
- `content_processor`
|
||||
- `web_crawler`
|
||||
|
||||
## 7. 恢复步骤
|
||||
|
||||
```bash
|
||||
cd ~/workbuddy-agent-os/agent-sync/00_bootstrap
|
||||
bash init.sh
|
||||
bash apply-config.sh
|
||||
bash import_skills.sh
|
||||
|
||||
~/.workbuddy/binaries/python/envs/agent-os/bin/python3 \
|
||||
~/workbuddy-agent-os/agent-sync/02_skills/memory_manager/bootstrap_from_memory.py \
|
||||
--root ~/workbuddy-agent-os/agent-sync
|
||||
```
|
||||
|
||||
手动安装项：
|
||||
|
||||
- WorkBuddy
|
||||
- 坚果云
|
||||
- Obsidian（按需）
|
||||
- oMLX 与模型
|
||||
|
||||
## 8. v2.0 不做什么
|
||||
|
||||
以下内容已经明确延后：
|
||||
|
||||
- `collect_from_local.py`
|
||||
- `skill_scanner.py`
|
||||
- `SKILL_CARD.yaml` 全量改造
|
||||
- 工具 manifest / 自动化安装体系
|
||||
- 更细粒度的多机记忆隔离策略
|
||||
- 基于 `agent-os-local/materials/` 的全新单入口采集体系
|
||||
|
||||
## 9. 现在应该怎么理解这个仓库
|
||||
|
||||
如果只看一句话：
|
||||
|
||||
> 这是一个已经从原形长成“可运行增强版”的 AgentOS 仓库，v2.0 的任务不是继续发散，而是先把当前这版冻结、讲清、可恢复。
|
||||
@@ -0,0 +1,390 @@
|
||||
agent-os多机协同
|
||||
本系统通过 WorkBuddy 作为 AI 交互中枢，整合本地大模型、计划做一个多机可协同，知识库可自增长，自学习、自优化。记忆可以不断提炼更新，向量化，持久化、长期化的、自我进化的 Mac 全栈智能体。
|
||||
多机采用共同底座及分机学习的模式，可进行快速迁移，快速生成复制快速恢复。
|
||||
## agent-os（全局/多机共用内容）这是共同底座的部分。
|
||||
1. **初始化脚本**
|
||||
- 从零安装、环境配置、workbuddy等自动化脚本
|
||||
- 建议统一放在 00_bootstrap，可细分 install、setup、update 等子目录
|
||||
安装的时候主要包括一次性把权限给到位，相应的基础设施，核心的环境内容，包括软件依赖，虚拟环境全部设置到位，假设是从空白组机开始还原先铺环境，然后再按依赖，最后按主程序。并设置自动任务、自动备份及自动优化等相应的所有的任务系统。所有的任务复制过来以后，根据祖籍身份，有些任务可以暂时暂停，如果身份切换以后再启用。
|
||||
2. **核心配置（01_core）**
|
||||
- 系统身份、主机标识、主维护机配置
|
||||
- 建议增加主机/维护机标识文件（如 `HOST_ID.md`、`MAINTAINER.md`）
|
||||
包括智能体所有的基础设定规则，还有一些通用全局的设置文件，全部装在这里，方便拷贝生成，或者可以进行嗯几个版本的生成，到时候可以选择性的加载，因为可能还涉及到多智能体等其他的各种设置，总之这些文件都可以配置在这里头
|
||||
3. **技能（02_skills）**
|
||||
- 系统必需技能
|
||||
- 自定义/个人维护技能
|
||||
- 每个技能需有身份证明（如 `SKILL.md`），并标注维护主机
|
||||
- 建议增加技能分类（如系统/自定义/第三方）
|
||||
基于前面讨论的技能身份证和版本控制分层，你只需要增加以下文件：
|
||||
|
||||
A. 每个技能目录下：SKILL_CARD.yaml（技能身份证）
|
||||
|
||||
只加在你自己写的技能里，比如 memory_manager/、kb_manager/、inbox_refine/、collect_to_inbox/、auto_collector/。
|
||||
|
||||
以 memory_manager/ 为例，在 02_skills/memory_manager/ 下新增一个文件：
|
||||
|
||||
```yaml
|
||||
# SKILL_CARD.yaml —— 技能身份证
|
||||
skill:
|
||||
name: "记忆管理器"
|
||||
id: "memory_manager"
|
||||
version: "1.1.0"
|
||||
category: "core-system"
|
||||
status: "active"
|
||||
created: "2026-04-25"
|
||||
updated: "2026-04-27"
|
||||
|
||||
description:
|
||||
short: "每日对话提炼、去重、冲突检测、版本管理"
|
||||
use_cases:
|
||||
- "每日凌晨 2:00 自动提炼前一天记忆"
|
||||
- "首次冷启动灌入已有 MEMORY.md"
|
||||
- "手动触发记忆更新"
|
||||
tags: ["记忆", "L1索引", "L2事实", "自动化"]
|
||||
|
||||
ownership:
|
||||
master_editor: "macbook-air-m1"
|
||||
readonly_on_other_devices: true
|
||||
|
||||
environment:
|
||||
os: "macos"
|
||||
python_path: "~/.workbuddy/binaries/python/envs/agent-os/bin/python3"
|
||||
local_dependencies:
|
||||
- "sqlite3（系统自带）"
|
||||
pip_dependencies:
|
||||
- "sqlite-utils>=3.35"
|
||||
- "chromadb>=1.0.0"
|
||||
|
||||
setup:
|
||||
install_script: "" # 由顶层 init.sh 统一安装
|
||||
post_check: "python3 -c 'import sqlite3; print(\"OK\")'"
|
||||
|
||||
usage:
|
||||
entry_point: "daily_digest.py"
|
||||
scheduled: "每日 02:00（WorkBuddy 自动化 agentos）"
|
||||
manual_trigger: "记忆更新"
|
||||
|
||||
changelog:
|
||||
- version: "1.1.0"
|
||||
date: "2026-04-27"
|
||||
changes: "接入 oMLX Embedding，支持向量化"
|
||||
- version: "1.0.0"
|
||||
date: "2026-04-25"
|
||||
changes: "初始版本"
|
||||
```
|
||||
|
||||
对其他技能（kb_manager、inbox_refine、collect_to_inbox、auto_collector）同样操作，字段按实际填写。
|
||||
|
||||
外部技能（如 web-clipper、voice-summary、social-collector）暂不加 SKILL_CARD，因为它们不是你开发的，升级不归你控制。如果你后续改造了它们，那时再加。
|
||||
|
||||
---
|
||||
|
||||
B. 05_tools/ 下：skill_scanner.py（技能身份证扫描器）
|
||||
|
||||
让你在任何一台机器上运行一次，就知道哪些技能就绪、哪些缺依赖：
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""扫描所有 SKILL_CARD.yaml，生成技能状态报告"""
|
||||
import os
|
||||
import yaml
|
||||
from pathlib import Path
|
||||
|
||||
SKILLS_DIR = Path.home() / "agent-os" / "02_skills"
|
||||
|
||||
def scan():
|
||||
print("=" * 60)
|
||||
print("AgentOS 技能状态报告")
|
||||
print("=" * 60)
|
||||
for skill_dir in sorted(SKILLS_DIR.iterdir()):
|
||||
if not skill_dir.is_dir():
|
||||
continue
|
||||
card_path = skill_dir / "SKILL_CARD.yaml"
|
||||
if not card_path.exists():
|
||||
print(f" ⚠️ {skill_dir.name} — 无 SKILL_CARD.yaml（外部技能或待补充）")
|
||||
continue
|
||||
with open(card_path) as f:
|
||||
card = yaml.safe_load(f)
|
||||
s = card["skill"]
|
||||
o = card.get("ownership", {})
|
||||
print(f" ✅ {s['name']} (v{s['version']}) 主理: {o.get('master_editor', '未知')}")
|
||||
print("=" * 60)
|
||||
|
||||
if __name__ == "__main__":
|
||||
scan()
|
||||
```
|
||||
|
||||
放在 05_tools/skill_scanner.py，用 AGENTOS_PYTHON 运行即可。
|
||||
|
||||
---
|
||||
|
||||
C. 根目录：SKILL_CARD_TEMPLATE.yaml（技能身份证模板）
|
||||
|
||||
当你在别的机器上新写一个技能时，复制这个模板来填，确保格式统一。放在 ~/workbuddy-agent-os/agent-sync/SKILL_CARD_TEMPLATE.yaml。
|
||||
|
||||
---
|
||||
|
||||
4. **知识库（03_knowledge）**
|
||||
- 分类建议：
|
||||
- 知识（外部资料、文档、教程等）
|
||||
- 个人笔记，个人我自己去想到的一些事，或者说我的感悟，或者说临时的一个随手的记的笔记，那这个东西呢其实就相当于随手记，我觉得这块就是呃它可以不用当成知识库，但是可能我需要有一个随手记随手查的事情，特别是比方说我开会的一个笔记，或者是我个人记录的一些语音，或者是个人记事，其实这是个个人成长，在我的第1版里头，其实是按照这个分类来的，所以呃知识库你会看到它比较乱，它有好多分类，其实是我的一个思想过程，中间呃有刚开始按照类别分的，后面按照事实分的，也有按领域分的，还有按概念分的，所以这块我们可以再讨论，嗯我只是把我所有的信息先放进来，你去了解一下
|
||||
- 记忆固化（长期记忆、总结、反思等）这个说的是整个我嗯好多机子的记忆体里头很多内容，它可能随着时间的偏移，它有些东西也变成了事实，也要记录下来。如果变成事实的东西，而且是通用的，不是说单机能用的，那其实也可以归集到总的知识库里头的记忆体里头，或者说是整个转到事实的记录，这块也要进行一个合理的判断
|
||||
- 项目立项/成形（项目文档、方案、进展等）我自己写的一些项目立项文件记录，包括我们自己编的程序的进展什么的，可能要单独画出来，因为它可能记录的我的一个过程，它可能是个过程记录，并不是结果，等到整个项目都成型了，稳固下来，可能他会写到正式记忆体。所以他要单独处理一下，我想的，
|
||||
- 向量化内容（如向量索引、embedding 数据）
|
||||
- 收件箱（待整理内容）
|
||||
- 建议每类下可细分为原始、已整理、归档等
|
||||
|
||||
── 8_收件箱/ # 临时收集，每月归档
|
||||
├── 1_日记/ # 每日记录，自动生成
|
||||
├── 20_项目/ # 活跃项目，Frontmatter包含type/status/areas
|
||||
├── 30_研究/ # 永久参考，深度调研内容
|
||||
├── 40_知识库/ # 原子概念，拆分独立知识点
|
||||
├── 50_资源/ # 精选内容，新闻稿、行业简报
|
||||
├── 90_计划/ # 执行计划，完成后归档
|
||||
└── 99_系统/ # 模板、提示词、归档目
|
||||
知识库结构详解
|
||||
6.1 目录结构与命名规则
|
||||
知识库路径：~/workbuddy-agent-os/agent-sync/03_knowledge/，同时作为 Obsidian Vault。
|
||||
编号
|
||||
目录
|
||||
中文名
|
||||
知识属性
|
||||
说明
|
||||
00
|
||||
00_inbox/
|
||||
📥 收件箱
|
||||
—
|
||||
待提纯内容暂存
|
||||
01
|
||||
01_daily/
|
||||
📅 日记
|
||||
—
|
||||
每日日记、闪念笔记
|
||||
10
|
||||
10_concepts/
|
||||
💡 概念层
|
||||
concept/axiom
|
||||
16 个子领域目录
|
||||
20
|
||||
20_methods/
|
||||
🔧 方法层
|
||||
method
|
||||
可操作的步骤/教程
|
||||
30
|
||||
30_facts/
|
||||
📋 事实层
|
||||
fact/regulation/data
|
||||
已验证的客观事实
|
||||
40
|
||||
40_references/
|
||||
📎 参考层
|
||||
reference
|
||||
论文/文档/外部资料
|
||||
50
|
||||
50_resources/
|
||||
🛠 资源层
|
||||
resource
|
||||
视频笔记/阅读笔记/灵感素材等
|
||||
60
|
||||
60_opinions/
|
||||
💭 观点层
|
||||
opinion/quote
|
||||
主观看法/他人原话
|
||||
90
|
||||
90_archive/
|
||||
🗄 归档层
|
||||
—
|
||||
已弃用的知识
|
||||
99
|
||||
99_system/
|
||||
⚙️ 系统层
|
||||
—
|
||||
模板/分类/配置
|
||||
|
||||
6.2 领域分类体系
|
||||
10_concepts/ 下按 16 个一级领域分子目录：
|
||||
编号
|
||||
英文目录
|
||||
中文
|
||||
典型子领域
|
||||
01
|
||||
cs
|
||||
计算机科学
|
||||
数据库、前端、后端、运维、安全
|
||||
02
|
||||
ai
|
||||
人工智能
|
||||
NLP、CV、强化学习、RAG、Agent
|
||||
03
|
||||
finance
|
||||
金融
|
||||
量化交易、价值投资、宏观经济
|
||||
04
|
||||
law
|
||||
法律
|
||||
民法、商法、知识产权
|
||||
05
|
||||
medicine
|
||||
医学
|
||||
中医、西医、营养学
|
||||
06
|
||||
physics
|
||||
物理
|
||||
量子力学、相对论、热力学
|
||||
07
|
||||
math
|
||||
数学
|
||||
线性代数、概率统计、微积分
|
||||
08
|
||||
psychology
|
||||
心理学
|
||||
认知心理学、社会心理学
|
||||
09
|
||||
philosophy
|
||||
哲学
|
||||
认识论、伦理学、美学
|
||||
10
|
||||
history
|
||||
历史
|
||||
中国史、世界史、科技史
|
||||
11
|
||||
engineering
|
||||
工程
|
||||
机械、电子、土木
|
||||
12
|
||||
design
|
||||
设计
|
||||
UI/UX、平面设计、建筑设计
|
||||
13
|
||||
business
|
||||
商业
|
||||
创业、管理、营销、战略
|
||||
14
|
||||
personal-management
|
||||
个人管理
|
||||
GTD、番茄工作法、精力管理
|
||||
15
|
||||
personal-insight
|
||||
个人洞见
|
||||
决策模型、价值观、反思
|
||||
16
|
||||
other
|
||||
其他
|
||||
待新增领域
|
||||
|
||||
当"其他"类别超过总知识 5% 时，memory_manager 会提示新增领域。
|
||||
6.3 知识卡片模板
|
||||
99_system/templates/ 下有 4 种标准化模板：
|
||||
模板文件
|
||||
适用类型
|
||||
核心字段
|
||||
concept-card.md
|
||||
概念/公理
|
||||
一句话定义、核心原理、与相关概念区别、主流选择
|
||||
method-card.md
|
||||
方法/教程
|
||||
适用场景、步骤、注意事项、示例
|
||||
fact-card.md
|
||||
事实/数据
|
||||
事实陈述、数据来源、可信度
|
||||
personal-insight-card.md
|
||||
个人洞见
|
||||
背景、思考过程、结论、行动项
|
||||
|
||||
所有知识卡片使用标准 Frontmatter：
|
||||
yaml
|
||||
复制
|
||||
---
|
||||
id: KB-YYYYMMDD-NNN
|
||||
title: "知识标题"
|
||||
type: concept|method|fact|reference|resource|opinion
|
||||
status: draft|review|published|archived
|
||||
nature: fact|opinion|method|regulation|reference|data|quote|axiom
|
||||
domain: [领域1, 领域2]
|
||||
tags: [标签列表]
|
||||
confidence: 0.0-1.0
|
||||
source: "原始来源 URL"
|
||||
source_type: official_doc|literature|experiment|personal_exp|social_media|unknown
|
||||
date_created: YYYY-MM-DD
|
||||
date_modified: YYYY-MM-DD
|
||||
version: 1
|
||||
previous_version: ""
|
||||
superseded_by: ""
|
||||
---
|
||||
|
||||
|
||||
6.4 分类体系配置文件
|
||||
文件
|
||||
路径
|
||||
说明
|
||||
domains.md
|
||||
99_system/taxonomies/domains.md
|
||||
16 个一级领域定义
|
||||
nature-types.md
|
||||
99_system/taxonomies/nature-types.md
|
||||
9 种 nature 类型 + 决策树
|
||||
folder-aliases.json
|
||||
99_system/taxonomies/folder-aliases.json
|
||||
英文目录 ↔ 中文映射
|
||||
classify-knowledge.md
|
||||
99_system/prompts/classify-knowledge.md
|
||||
知识分类 Prompt
|
||||
|
||||
|
||||
|
||||
5. **工具层（05_tools）**
|
||||
- 非技能化的工具脚本
|
||||
- 包括知识库管理、记忆管理、技能管理等
|
||||
- 建议按功能模块细分
|
||||
因为技能很更多的是自然语言或一些东西，它可能对于一些大量的个性化的工具，呃可能不一定使用得很好，所以我的工具做很多做cl i的终端化的处理，或者说直接写成一些接口的东西，这样子会被技能更好的去去调用，技能这面有一些东西，呃如果确实是可以写，那中间也可以转换，但这个转换过程可能要等着这个技能呃通用了，才可能放到技能里头，或者说它跟系统有关才放进去。我是这么想的，你可以给我点建议啊，我们在这个事上再讨论讨论
|
||||
6. **系统管理（07_migration/90_archive）**
|
||||
- 打包、解包、迁移、备份等脚本
|
||||
- 系统归档、历史记录
|
||||
|
||||
---
|
||||
|
||||
## agent-os-local（本机专属内容）
|
||||
|
||||
1. **采集原始内容**
|
||||
- 各类原始数据（音频、视频、网页、截图等），每个单机的原始讨论，可能还包括我说的一些话，一些笔记，这个其实和知识库那块来讲是联动的，它其实是先进行我从网上或者。说手机或者是新闻客户端收集到的内容全都看到了以后，先暂存到每台机子上，因为每台机子我在做项目的时候，同时会看到一些信息，这个信息就是临时性的，或者是一个闪念，但是过完以后可能再去收集整理，所以它就相当于是个前前端缓存，存。存完以后，有一些东西可能分门别类，这块跟知识库呢要对应起来，到时候连知识库的分门别类和这块一块讨论。这个才是这个项目可能比较核心的东西，最初我就是拿这个东西想写一个项目来着，但是后来发现其实是依托智能体，不过不光是做这个项目，还要做智能体的一些配置，运行状态等等，才会越写越大，最后涉及到多机联动
|
||||
- 建议按类型细分 materials/audio、video、web、screenshots 等
|
||||
|
||||
2. **本机记忆**
|
||||
- 个人/本机的记忆数据
|
||||
- 建议分为原始、整理、归档等
|
||||
本机的记忆，自己也涉及到和知识体的共享的，就是什么记忆提取出来变成长久的记忆，他记忆里头可能有一些东西是要加一些属性字段，也就是向量化处理的时候，可能在一些东西，比方说事实层，或者说具体的这种呃硬约束层，它可能。能能提取出来，分享给所有人用，呃有一些东西只有跟本机有关，比方说本机的CPU处理能力，或者本机的向量化处理能能力，这些东西只能在本机用，放在别的机器上不通用的，那其实是不要放，那这个中间如何去判断，如何去执行。所以我们这中间的这个知识管理和提炼，记忆提炼这两个程序，就要把这些东西都整理进去，所以这两个程序写起来就会很重要
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
3. **运行记录、对话记录、缓存**
|
||||
- 任务缓存、运行日志、对话历史
|
||||
- 建议分为 runtime/cache、memory/raw、memory/vector_db 等
|
||||
这块主要是和这个智能体的一个对接的地方，因为将来有可能智能体我换了的话，用其他智能体如何对接，其实都要在这块处理，因为换一个智能整体可能我用openclaw和现在workbuddy可能将来用的对接的方式或者是运行状态，可能对话记录或者说是呃每次的呃这种上下文也不一样。如何能从用这个适合智能体的一些工具把它调用出来，这个是很重要的事情，都在这块解决
|
||||
4. **本机情况数据说明记录**
|
||||
- 本机环境、硬件、软件、配置说明
|
||||
- 建议单独设 info/ 或 system/ 目录
|
||||
|
||||
---
|
||||
|
||||
## 需要你补充/确认的问题
|
||||
|
||||
1. **向量库（vector_db）**
|
||||
你希望它只作为索引，还是也存储知识内容？是否需要和知识库内容分离，还是做成知识库的一个子模块？向亮库，我就在想，其实我本地本机是应该有个向量库，然后在共享的呃服务器知识体上，其实也是有一个向量库，那个向亮库可以全全域和多多台主机同步，但我本机就是我本机，其实不需要同步，呃本机根据依据本机的这个能力，其实。在进行，所以我中间这个有一个向量库，可能要全局通用，这样子才能同步起来，呃我理解是这个样子，你可能想想是不是再帮我补充一下
|
||||
|
||||
2. **主机/维护机标识**
|
||||
是否需要每台主机有唯一标识？主维护机如何指定？是否需要自动同步主维护机的内容？
|
||||
主机肯定是要维护的，因为我相当于是多台主机跨系统的一个跨主机的一个操作，所以每台主机它是什么一个唯一标识，然后它充当。什么角色，对刚才我讲的知识库、记忆、技能，所有的这种管理，包括整个这个主程序的管理，他们都有什么权限角色，其实我觉得这个还是需要的，因为谁写的智能体可能最好是在他原来的这台主机上继续在维护。体的知识库的管理，最好是有一台主机，就固定充当这台管理主机，然后他晚上就可以进行呃提炼管理，记忆体各自是各自的管理，然后管理与有了一些记忆可以共享升级的情况下，然后再去提取到中组主机里头去呃管理
|
||||
3. **知识库分类**
|
||||
你希望知识库的分类粒度到什么程度？是否需要支持多级分类、标签等？
|
||||
知识库的分类，我前面讲了好多了，包括记忆体那块也讲了好多了，有很多对接的，所以我需要这块来讲，呃展开了，到时候我们再细聊，你可以发散性的给我提问题，帮助我去把这块这一部分去完善掉
|
||||
4. **工具与技能的边界**
|
||||
工具和技能的区别是否只在于是否被系统自动加载？有无交集或转换机制？
|
||||
工具在加载这一块，我需要既要注重效率，又要呃合理的去呃扩展，呃这块你给出很好的建议
|
||||
5. **本机数据说明**
|
||||
本机情况数据说明，具体希望包含哪些内容？如硬件、软件、网络、环境变量等？
|
||||
本机情况就是根据我系统将来要完成的所有的电脑相关的事项，给出来的所有的数据，其实这个数据最好固定的写在这儿，但是它有一些变化的时候，又能够动态更新，这个要有个很好的呃模式，我不想浪费太多的token，因为核心逻辑就是整个这个系统使用token的时候还是要尽量节省一点效率为先，我不不能太过于浪费
|
||||
6. **同步/备份机制**
|
||||
agent-os 与 agent-os-local 之间是否需要自动同步、定期备份？同步粒度和策略如何？ 我觉得你问这个问题就是你没搞清楚我现在在写什么，所以我现在才写了这么大一段东西给你
|
||||
@@ -0,0 +1,289 @@
|
||||
# 视频工厂模块梳理与 DCS 落地规划
|
||||
|
||||
> 创建: 2026-10-01 | 状态: 方案待确认
|
||||
> 输入文档: `~/Documents/导演创作系统（Director.docx`（DCS 项目开发说明书 v2.0）
|
||||
> 目标: 把 DCS 的「故事 → 分镜 → 成片」能力落到现有 Dashboard 视频工厂，先跑通一条片子
|
||||
|
||||
---
|
||||
|
||||
## 一、背景
|
||||
|
||||
用户提供 DCS 文档（5 层架构、统一分镜 Schema、8 类能力 API、去 AI 化合成链）。文档原设计用
|
||||
**Appsmith（控制台）+ n8n（编排）+ Docker** 三件套；但项目**已有 Dashboard 控制台 + command_bus/guardd 执行体系**，
|
||||
且 `09_ave` 后端**已有完整的视频生产流水线**。
|
||||
|
||||
**结论：融入现有 Dashboard（不引入 Appsmith/n8n）**，把 DCS 的分镜 Schema 与去 AI 化链补进来。
|
||||
|
||||
---
|
||||
|
||||
## 二、现状全景（2026-10-01 实测）
|
||||
|
||||
### 2.1 后端 `05_tools/09_ave/scripts/`（能力远比预期完整）
|
||||
|
||||
**六个分层目录**（已有）：
|
||||
|
||||
| 目录 | 职责 |
|
||||
|:--|:--|
|
||||
| `01_director_parser/` | 导演脚本解析（文案 → 结构化脚本） |
|
||||
| `02_voice_synthesizer/` | 语音合成（TTS） |
|
||||
| `03_bgm_generator/` | BGM 生成 |
|
||||
| `04_anchor_extractor/` | 锚点提取（一致性锚点） |
|
||||
| `05_material_producer/` | 素材生产 |
|
||||
| `06_composer/` | 合成器（**已有 2635 行**：`ffmpeg.py` 702 / `hybrid.py` 453 / `speed_ramp.py` 370 / `lipsync.py` 369 / `character_locker.py` 68 / `beat_sync.py`） |
|
||||
| `07_service_layer/` | 服务层（**空壳，只有 `__init__.py`**） |
|
||||
|
||||
**核心脚本**：
|
||||
|
||||
| 文件 | 规模 | 职责 |
|
||||
|:--|:--|:--|
|
||||
| `main.py` | 931 行 | 原子能力 CLI：`voice`（TTS aliyun/volcano）/ `material`（素材搜索）/ `parse`（文案→导演脚本）/ `compose`（视频合成）/ `anchors`（锚点提取）等 |
|
||||
| `character_sheet.py` | 841 行 | 定妆照/角色图（Kling 接入处） |
|
||||
| `character_portrait.py` | 790 行 | 角色画像 |
|
||||
| `video_factory.py` | 641 行 | **5 种生产模式**：`run_oral`（口播）/ `run_beat`（卡点）/ `run_digital_human`（数字人）/ `run_hybrid`（口播+卡点）/ **`run_story`（故事·漫剧，← DCS 目标）** |
|
||||
| `story_director/` | 1430 行 | `scene_planner` 444（剧本→场景+Prompt）/ `temporal_bridge` 322（场景过渡桥接）/ `batch_generator` 664（批量 Kling + 固定 seed） |
|
||||
| `director_parser/` | 323 行 | `parser.py` 192 + `schemas.py` 131 |
|
||||
| `composer/` | 2635 行 | FFmpeg 封装 / 混合合成 / 对口型 / 变速 / 节拍同步 / **角色锁定** |
|
||||
| `lib/` | — | `config.py` / `cost_tracker.py`（成本追踪）/ `dashboard.py`（生产埋点）/ `logger.py` |
|
||||
| `demo_full_pipeline.py` | 256 行 | 完整流程演示 |
|
||||
| `AVE_ARCHITECTURE_PLAN.md` | 480 行 | **既有架构规划**（见 2.3） |
|
||||
|
||||
**集成方式**：`09_ave` **没有独立 FastAPI 层**；Dashboard 通过 `app.py` 把 `09_ave/scripts` 加入 `sys.path`，
|
||||
并由 `plugins/ave.py`（243 行）解析能力清单供 `/api/capabilities` 使用。
|
||||
|
||||
### 2.2 前端视图（`10_dashboard/frontend/src/views/`）
|
||||
|
||||
**菜单已挂 8 项**（`nav-menu.js` → 视频工厂）：
|
||||
|
||||
| 视图 | 行数 | 实际状态 |
|
||||
|:--|:--|:--|
|
||||
| `workflow` | 485 | 节点画布（拖拽 + 模板系统，模板来自 `10_dashboard/workflows.py`） |
|
||||
| `capabilities` | 80 | 能力目录（调 `/api/capabilities`，数据源 `AVE_ARCHITECTURE_PLAN.md`） |
|
||||
| `person-swap` | 269 | 人物置换（已实现） |
|
||||
| `characters` | 138 | 角色列表 |
|
||||
| `char-gen` | 389 | 角色生成器 |
|
||||
| `productions` | 88 | 生产记录 |
|
||||
| `assets` | 57 | 素材库 |
|
||||
| `costs` | 61 | 费用分析 |
|
||||
|
||||
**未挂菜单的空壳**（各 9 行，仅"功能开发中"）：`ave-script`（脚本生成）/ `ave-materials` / `ave-render` / `ave-templates`
|
||||
|
||||
### 2.3 工作流模块现状（`10_dashboard/workflows.py`，599 行）
|
||||
|
||||
**已有 6 个模板**（`WORKFLOW_TEMPLATES`）：
|
||||
|
||||
| 模板 ID | 名称 | 节点数 | 节点链 |
|
||||
|:--|:--|:--|:--|
|
||||
| `basic_dub` | 基础口播 | 5 | 脚本 → TTS → 素材搜索 → BGM → 视频输出 |
|
||||
| `beat_sync` | 卡点视频 | 4 | BGM 导入 → 卡点风格 → 质量审核 → 视频输出 |
|
||||
| `character_narrative` | 角色叙事 | 8 | 剧本输入 → 脚本改编 → 角色引用 → 故事策略 → Kling 生成 → 旁白 TTS → 生成审核 → 最终输出 |
|
||||
| `digital_human` | 数字人口播 | 4 | 文案输入 → 人声合成 → 数字人角色 → 数字人视频 |
|
||||
| `hybrid_dub` | 口播+卡点混合 | 4 | 口播脚本 → 人声合成 → 混合风格 → 混合视频 |
|
||||
| **`short_drama`** | **短剧创作** | **12** | 故事输入 → 脚本编辑 → 角色设定 → 短剧策略 → **分镜规划** → **提示词生成** → 场景视频 → 角色配音 → 配乐 → 字幕 → 成片审核 → 短剧成片 |
|
||||
|
||||
**15 种节点类型**（`NODE_DEFINITIONS`）—— 已含 DCS 所需关键节点：
|
||||
`story_prototype`（剧本原型）/ `script_adaptor`（剧本改编）/ `storyboard`（**分镜规划**：景别/运镜/转场/对白/动作）/ `prompt_gen`（**分镜提示词**）/ `character`（角色引用+定妆照）/ `tts` / `material` / `bgm` / `style` / `strategy` / `model` / `audit_gate`（人工审核门）/ `subtitle` / `output`
|
||||
|
||||
**🔴 关键问题：执行器是空转的**
|
||||
|
||||
`workflows.py:519-530` 的 `WorkflowRunner.start_run()` → `_execute()`：
|
||||
|
||||
```python
|
||||
def _execute():
|
||||
ordered = self._kahn_sort(run["nodes"], run["edges"]) # 只做拓扑排序
|
||||
for n in ordered:
|
||||
run["node_states"][n["id"]] = "completed" # 直接标记完成
|
||||
run["status"] = "completed"
|
||||
```
|
||||
|
||||
**没有任何真实节点执行逻辑**（不调 TTS / Kling / 合成）→ 工作流"能画、能存、能排序，但点了不真跑"。
|
||||
真正能出片的是 `09_ave/scripts/video_factory.py`（`run_story` / `run_oral` / `run_beat` ...），走 CLI，**与 workflow 画布未打通**。
|
||||
|
||||
**接口现状**（`app.py:1083-1130`）：`GET /api/workflow/nodes|node/{type}|templates|runs|runs/{id}`、`POST /api/workflow/run`
|
||||
|
||||
### 2.4 三视角分工（结论）
|
||||
|
||||
```
|
||||
「🎬 导演创作」新建视图 ← 分镜视角（表格：逐条编辑/删/重试）★ M1 做这个
|
||||
「🔀 工作流」现有画布 ← 流程视角（6 模板 + 15 节点；执行器待补）
|
||||
「📋 生产记录 / 💰 费用」 ← 结果与成本视角
|
||||
────────────────────────────────────────────
|
||||
后端 09_ave 真实流水线 ← 真正出片的地方（run_story / run_oral / ...）
|
||||
```
|
||||
|
||||
**M1 正确做法**：新建导演创作视图（分镜表）+ 后端接**真实流水线**；
|
||||
工作流保留为流程视角（把画布节点接到真实能力的"执行器补齐"另排期，不在 M1）。
|
||||
|
||||
### 2.5 既有架构规划（`AVE_ARCHITECTURE_PLAN.md`，2026-05-18）
|
||||
|
||||
**已定义 6 条生产路径**：
|
||||
|
||||
```
|
||||
1. 口播线 文案→TTS→素材→BGM→字幕→合成
|
||||
2. 卡点线 BGM→节拍检测→素材→拍点切换→xfade
|
||||
3. 数字人线 照片/视频→OmniHuman对口型 / DreamActor动作模仿
|
||||
4. 口播+卡点线 人声锚点+BGM变速→帧锁定拼接 (hybrid)
|
||||
5. 故事/漫剧线 ★ 剧本→场景分解→Kling批量→角色拼接 ← DCS 要的这条
|
||||
6. 模仿视频线 ★ 参考视频→结构分析→动作迁移/角色替换→合成
|
||||
```
|
||||
|
||||
**已识别的问题**（原文）：
|
||||
1. 各策略独立实现，**底层能力重复**（口播和卡点的素材搜索各写一遍）
|
||||
2. **角色系统只在"故事"线使用**，口播/卡点/数字人都需要角色但未接入
|
||||
3. AudioLine 建成但未接入主流程
|
||||
|
||||
**既有解法**（原文）：分层架构 —— 底层能力层（原子操作）→ 策略编排层（生产路径）→ 接入层（CLI/Dashboard）。
|
||||
**与 DCS 的分层思路一致**，可直接承接。
|
||||
|
||||
---
|
||||
|
||||
## 三、视频工厂定位：能解决哪几类问题
|
||||
|
||||
**三层 × 六线矩阵**：
|
||||
|
||||
**A. 共用底座**（所有生产路径共享，应统一管理）
|
||||
|
||||
| 层 | 内容 | 现状 |
|
||||
|:--|:--|:--|
|
||||
| 资产管理 | 角色（2D 参考图 / 定妆照 / 3D 模型）、场地、产品、道具、BGM、音效、特效预设 | 部分（`characters`/`char-gen`/`assets`/`character_registry`） |
|
||||
| 能力层 | 语音合成 / 素材搜索 / 图像生成（Kling）/ 图生视频（Kling）/ 人物置换（百炼）/ BGM 生成 | 大部分已有（`main.py` 原子命令 + `character_sheet` + `person_swap`） |
|
||||
| 合成层 | FFmpeg 拼接 / 变速 / 对口型 / 节拍同步 / 角色锁定 / **去 AI 化**（缺） | 除"去 AI 化"外已有 |
|
||||
|
||||
**B. 生产路径**（6 条线，每条是"策略编排"）
|
||||
|
||||
**C. 编排与任务**（分镜级任务分发、进度、重试、成本）
|
||||
|
||||
---
|
||||
|
||||
## 四、模块重构方案（菜单分层）
|
||||
|
||||
现有 8 项菜单**混了三种性质**（资产 / 生产路径 / 分析），建议按层重组为 **4 组**（二级分类）：
|
||||
|
||||
```
|
||||
🎬 视频工厂
|
||||
├─ 📦 资产管理 ← 共用底座
|
||||
│ ├─ 🧑 角色库 （characters + char-gen 合并：生成/列表/定妆照）
|
||||
│ ├─ 🎬 场景与道具 （待建：locations/products/props）
|
||||
│ ├─ 🖼️ 素材库 （assets，扩展 ave-materials）
|
||||
│ └─ 🔄 人物置换 （person-swap）
|
||||
│
|
||||
├─ 🎞️ 生产路径 ← 6 条线，一条一个入口
|
||||
│ ├─ 🎬 导演创作 ★ （新建，DCS 主线：故事→分镜→成片）
|
||||
│ ├─ 🎙️ 口播视频 （run_oral）
|
||||
│ ├─ 🥁 卡点视频 （run_beat）
|
||||
│ ├─ 👤 数字人 （run_digital_human）
|
||||
│ └─ 🎭 模仿换人 （run_hybrid / 第六线）
|
||||
│
|
||||
├─ ⚙️ 编排与任务 ← 执行层
|
||||
│ ├─ 🔀 工作流 （workflow 画布，保留）
|
||||
│ ├─ 📋 生产记录 （productions）
|
||||
│ └─ 💰 费用分析 （costs）
|
||||
│
|
||||
└─ 🔧 配置
|
||||
├─ ⚡ 能力目录 （capabilities）
|
||||
└─ 🎨 模板 （ave-templates → 参数模板，DCS 第八节）
|
||||
```
|
||||
|
||||
**关键判断：新做的"导演创作"应该新建视图，不塞进工作流**
|
||||
- `workflow` 是**节点画布**（拖拽式编排），适合"流程可视化"
|
||||
- DCS 的**分镜编辑**是"逐条表格 + 逐条修改 + 逐条重试"，表格化交互更适合
|
||||
- 二者互补：分镜编辑产出 Schema → 可"发送到工作流"做可视化编排（后期联动）
|
||||
|
||||
---
|
||||
|
||||
## 五、DCS 落地映射（复用 vs 新写）
|
||||
|
||||
| DCS 要求 | 项目现状 | 落地动作 |
|
||||
|:--|:--|:--|
|
||||
| 统一分镜 Schema（12 pydantic 模型） | 无（`director_parser/schemas.py` 131 行，非此 Schema） | **新写** `09_ave/scripts/schemas.py` |
|
||||
| 层1 导演系统（故事→Schema） | `story_director/scene_planner`（剧本→场景+Prompt） | **适配**：输出对齐统一 Schema |
|
||||
| 层0 控制台分镜编辑页 | `ave-script` 空壳 | **新建** `views/ave-director.js`（分镜编辑器） |
|
||||
| 层2 编排（n8n） | `command_bus` + `guardd` + `workflow` 画布 | **复用** command_bus 派任务（M2 阶段接） |
|
||||
| 层3 TTS | `main.py voice`（aliyun/volcano） | 复用；DCS 提的 Fish Audio 可选接 |
|
||||
| 层3 图生视频 | `story_director/batch_generator`（Kling） | 复用（**Kling 余额不足，需充值**） |
|
||||
| 层3 素材/背景 | `main.py material` | 复用；DCS 提的通义万相可选接 |
|
||||
| 层4 合成 | `composer/ffmpeg.py` + `speed_ramp` + `lipsync` | 复用 |
|
||||
| 层4 **去 AI 化链** | **无**（grep `gblur`/`deai` 无命中） | **新写** `composer/de_ai.py`（DCS 第八节 FFmpeg 模板） |
|
||||
| 资产库规范（characters/locations/products/…） | `character_registry/` 已有角色部分 | **扩展**目录结构对齐 DCS 第五节 |
|
||||
| 任务状态/重试（`/api/task/*`） | `lib/dashboard.py` 有生产埋点；Dashboard 有任务面板 | 复用 + 补分镜级重试 |
|
||||
| 特效库（子弹时间/环绕运镜） | 无 | 后期（M4，接 Kling camera_control） |
|
||||
| 3D 角色（混元3D） | 无 | 后期（M4） |
|
||||
|
||||
**环境确认**：
|
||||
- ✅ **FFmpeg 6.0 已装**（`~/.local/bin/ffmpeg` + `ffprobe`，非 brew 安装）
|
||||
- ⚠️ **可灵余额不足**（`code:1102`）→ M2 实测前需充值，或先用火山方舟（已配 key）
|
||||
- ✅ Dashboard `:9988` 运行中；Tailscale 访问已通
|
||||
|
||||
---
|
||||
|
||||
## 六、M1 实施计划（本期：故事 → 分镜 → 成片）
|
||||
|
||||
**目标**：输入一段故事 → 生成可编辑分镜表 → 提交生成 → 输出一条 20 秒成片。**先看效果，再决定后续**。
|
||||
|
||||
**M1 范围（4 步）**：
|
||||
|
||||
1. **统一分镜 Schema**（`09_ave/scripts/schemas.py`）
|
||||
- 按 DCS 第四节实现 12 个模型（`Storyboard`/`Shot`/`GlobalAnchors`/`ShotContract`/`VFXConfig`/`AudioConfig`/`Subtitle`/`Transition`/`Speed`/`ColorConfig`/`PostProcess`/`OutputConfig`）
|
||||
- 提供 `to_dict()` / `from_dict()` 便于 JSON 传输
|
||||
|
||||
2. **故事 → 分镜**（后端）
|
||||
- `routes/` 新增 `ave.py`（或其插件扩展）：`POST /api/ave/storyboard/generate`（body: story/content_type/global_anchors）
|
||||
- 内部调 `story_director.scene_planner.plan_scenes` → 转成统一 Schema
|
||||
- `POST /api/ave/storyboard/revise`（单镜头重生成，为后期重试预留）
|
||||
|
||||
3. **分镜编辑 UI**（`views/ave-director.js`，菜单「🎬 导演创作」）
|
||||
- 故事输入（textarea）+ 内容类型 + 全局锚点（角色/场地选择）
|
||||
- 分镜表：逐条显示 `镜号/时长/类型/画面描述/台词/情绪`，可编辑、可删除、可加特效占位
|
||||
- 「生成分镜」→ 表格；「提交生成」→ 派任务
|
||||
|
||||
4. **生成 + 合成**（后端流水线）
|
||||
- 每镜头按 `type` 调能力（M1 先支持：`action`（Kling 图生视频）/ `background`（素材）/ `talking_head`（预留））
|
||||
- 去 AI 化链 `composer/de_ai.py`（DCS 第八节 FFmpeg 参数）
|
||||
- 拼接输出到 `output/<project_id>.mp4`；分镜状态回写（排队/生成中/完成/失败）
|
||||
|
||||
**验收标准**：一条 20 秒片子（3~6 个镜头），画面连贯、角色一致（`consistency_seed`）、有去 AI 化处理、能在「成片预览」播放。
|
||||
|
||||
---
|
||||
|
||||
## 七、后续里程碑（M1 之后，视效果再定）
|
||||
|
||||
| 里程碑 | 内容 |
|
||||
|:--|:--|
|
||||
| M2 | 资产库规范化（locations/products/props/vfx_presets 目录 + 上传 UI）+ `global_anchors` 全量注入 |
|
||||
| M3 | 能力层扩展（TTS 多提供商 / 口播 D-ID / 背景通义万相）+ 编排接入 command_bus（并行/重试/停止） |
|
||||
| M4 | 特效库（Kling camera_control 六参数 + 子弹时间）+ 3D 角色（混元3D） |
|
||||
| M5 | 批量生产（多故事并行）+ 成本追踪接入（`lib/cost_tracker` 已有） |
|
||||
| M6 | 按 2.2 节方案重组视频工厂菜单（资产/生产路径/编排/配置 4 组） |
|
||||
|
||||
---
|
||||
|
||||
## 八、待确认
|
||||
|
||||
1. **M1 生成引擎**：可灵余额不足 —— 先充值，还是先用火山方舟（即梦）跑通？
|
||||
2. **故事输入源**：手写故事 / 粘贴文案 / 也给「AI 从主题生成故事」？
|
||||
3. **菜单重组时机**：M1 先加一个「🎬 导演创作」入口（不动现有），还是先按第四节的 4 组方案整体重组？
|
||||
4. **成片时长**：M1 目标时限（20 秒 / 30 秒 / 不限，按分镜数定）？
|
||||
5. **去 AI 化是否默认开**？DCS 默认参数（模糊 0.4 / 颗粒 12 / 饱和 -0.12 / 色温 5300K）
|
||||
|
||||
---
|
||||
|
||||
## 九、关键文件索引
|
||||
|
||||
**后端（`05_tools/09_ave/scripts/`）**
|
||||
- `video_factory.py` — 5 种生产模式（`run_story` 在 518-631 行）
|
||||
- `story_director/scene_planner.py` / `temporal_bridge.py` / `batch_generator.py`
|
||||
- `composer/ffmpeg.py` / `hybrid.py` / `lipsync.py` / `speed_ramp.py` / `character_locker.py`
|
||||
- `main.py`（原子能力 CLI）/ `character_sheet.py`（Kling）/ `lib/`（config/cost_tracker/dashboard/logger）
|
||||
- `AVE_ARCHITECTURE_PLAN.md`（**既有架构规划，6 条生产路径**）
|
||||
- 待新建：`schemas.py` / `composer/de_ai.py`
|
||||
|
||||
**前端（`10_tools/10_dashboard/frontend/src/`）**
|
||||
- `nav-menu.js`（菜单单点定义）→ 视频工厂分组
|
||||
- `views/workflow.js`（画布+模板）/ `capabilities.js` / `person-swap.js` / `characters.js` / `char-gen.js`
|
||||
- 待新建：`views/ave-director.js`（分镜编辑 + 生成）
|
||||
|
||||
**集成**
|
||||
- `10_dashboard/app.py`（把 `09_ave/scripts` 加 sys.path）
|
||||
- `10_dashboard/plugins/ave.py`（能力目录数据源）/ `10_dashboard/workflows.py`（工作流模板）
|
||||
|
||||
**外部参考**
|
||||
- `~/Documents/导演创作系统（Director.docx`（DCS 说明书，已转文本 `/tmp/director_doc.txt`）
|
||||
@@ -0,0 +1,23 @@
|
||||
# 归档：视频工厂旧设计文档（2026-10-01）
|
||||
|
||||
这批文档是**视频工厂重构前**的设计稿，内容已被 **`PLANS/VIDEO_FACTORY_MASTER.md`（v2.0 唯一权威版）** 取代。
|
||||
|
||||
| 文档 | 归档原因 |
|
||||
|:--|:--|
|
||||
| `VIDEO_FACTORY_FRAMEWORK.md` | **菜单分类有误**：把"流程"和"能力"混着平铺；「导演创作」被当成独立板块（实际是一条流程）、「人物置换」被错放进资产（实际也是一条流程）→ 正确结构见 MASTER 第二节 |
|
||||
| `VIDEO_FACTORY_ARCHITECTURE.md` | 技术细节已并入 MASTER（第六节后端架构、第七节代码映射） |
|
||||
| `DCS_VIDEO_FACTORY_PLAN.md` | 现状调研 + M1 计划；**M1 已完成**（统一分镜 Schema → 导演适配器 → 端到端出片），计划部分作废 |
|
||||
|
||||
## 仍可参考的部分
|
||||
|
||||
- M1 的实施记录与实测数据（统一分镜 Schema 14 模型 / 导演适配器 / 可灵引擎 / 去AI化 / 流水线 / 并发与体积优化）
|
||||
- 现有代码盘点表（哪些是空壳、哪些真能跑）
|
||||
|
||||
## 已失效的部分
|
||||
|
||||
- **菜单/信息架构**（错把流程与能力平级摆放）
|
||||
- 阶段划分（S1~S5 → 已重排为 MASTER 的 P1~P7）
|
||||
|
||||
## 当前权威文档
|
||||
|
||||
**`PLANS/VIDEO_FACTORY_MASTER.md`** —— 三层模型（流程 / 能力 / 资产）+ 前端信息架构 + 流程清单与现状 + 执行审查机制 + 后端架构 + 改造计划 + 待确认项。
|
||||
+340
@@ -0,0 +1,340 @@
|
||||
# 视频工厂结构化设计 v1.0
|
||||
|
||||
> 创建: 2026-10-01 | 状态: 设计待确认
|
||||
> 定位: 视频工厂的**整体架构设计**（能力层/节点层/流程层/执行器 + 4 个可替换点）
|
||||
> 配套: `DCS_VIDEO_FACTORY_PLAN.md`（现状调研 + M1 落地计划）
|
||||
> 输入: DCS 说明书 v2.0 + 用户口述需求 + 4 个导演系统调研
|
||||
|
||||
---
|
||||
|
||||
## 一、设计目标（用户原话转译）
|
||||
|
||||
> "我用不同的导演系统，最后都出现统一的这种调度；把大家的优点结合起来，怎么嵌入进去"
|
||||
|
||||
**五件事要串起来**：
|
||||
|
||||
1. **能力节点**（原子能力）—— 一个个小工作能力（TTS / 图生视频 / 换脸 / 对口型…）
|
||||
2. **流程拼接**（模板）—— 能力节点串成流水线（口播 / 短剧 / 广告…）
|
||||
3. **节点设置 + 流程设置** —— 每个节点打开有**默认值**，可改成别的（含数据库、大模型）
|
||||
4. **基础资源库**（资产）—— 角色 / 场景 / 道具 / 产品 / BGM / 音效 / 特效预设，**所有流程共用**
|
||||
5. **导演选择 + 路径/脚本/分镜设置** —— 导演系统可切换（5.2 为主），统一输出分镜
|
||||
|
||||
**三个核心机制**：
|
||||
- **可插拔**：导演系统、能力供应商、大模型、资产 —— 都能换，换了不改流程
|
||||
- **统一调度**：无论哪个导演系统、哪个供应商，下游执行完全一样
|
||||
- **分层配置**：全局默认 → 流程级 → 节点级（逐级覆盖）
|
||||
|
||||
---
|
||||
|
||||
## 二、总体架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ ① 导演层（可替换）★ 替换点 1 │
|
||||
│ OpenDirector │ AI Storyboard Director v5.2（默认） │ clip-storyboard │
|
||||
│ Seedance Director 4.0 │ …（任何导演系统） │
|
||||
│ ↓ 都输出「统一分镜 Schema」 │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ ② 编排层：流程（Template）= 节点 + 连线 │
|
||||
│ 短剧线 / 口播线 / 卡点线 / 数字人线 / 广告线 / 模仿线 │
|
||||
│ ↓ 每个节点引用能力 │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ ③ 能力层（Capability Registry）★ 替换点 2（供应商）★ 替换点 3（模型） │
|
||||
│ 音频：TTS / 变声 / BGM / 节拍分析 / 混音 │
|
||||
│ 视觉：文生图 / 图生视频 / 文生视频 / 换脸 / 对口型 / 运镜 / 特效 │
|
||||
│ 视频：拼接 / 变速 / 转场 / 字幕 / 去AI化 │
|
||||
│ 分析：剧本解析 / 分镜规划 / 提示词生成 / 内容审核 │
|
||||
│ 外部：ComfyUI 工作流（=能力孵化器） │
|
||||
│ ↓ 每个能力多供应商可选 │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ ④ 执行层（统一调度）★ 要补 │
|
||||
│ 任务派发 → 状态机 → 轮询 → 重试 → 停止 → 产物收集 → 成本记账 │
|
||||
│ 复用：command_bus / guardd / 任务面板 / lib.cost_tracker │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ ⑤ 资产层（共享底座）★ 替换点 4（内容） │
|
||||
│ 角色 / 场景 / 道具 / 产品 / BGM / 音效 / 特效预设 / 风格 │
|
||||
│ 被所有流程按 id 引用 │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**统一调度的实现关键**：所有导演系统输出**同一份分镜 Schema** → 编排层/能力层/执行层完全不感知导演是谁。
|
||||
|
||||
---
|
||||
|
||||
## 三、① 导演层（可替换）
|
||||
|
||||
### 3.1 四个候选系统定位
|
||||
|
||||
| 系统 | 形态 | 强项 | 弱点 | 在我们的定位 |
|
||||
|:--|:--|:--|:--|:--|
|
||||
| **AI Storyboard Director v5.2** | Agent Skill（提示词/方法论） | **分镜质量最高**；先锁视觉概念再拆镜头；两遍交付（设计稿+生产稿） | 不自动出片（要接生成 API） | **默认导演**（分镜/摄影精细打磨） |
|
||||
| clip-storyboard-director | Agent Skill（本地优先） | **跨场景一致性最强**（4D 持久化缓冲区，"病房→走廊→室外"角色不变） | 配置复杂（维护 persistence_buffer） | **一致性模式**（多场景长片、角色要严格不变时切换） |
|
||||
| Seedance Director 4.0 | 提示词工程（16 技能） | **模板化最好**（9 层工程文件 + 广告/短剧/生活方式配方） | 需 Claude Code/Cursor 环境 | **批量复用模式**（配方化生产） |
|
||||
| OpenDirector | Docker 全自动流水线（9 Agent） | **全自动程度最高**（研究→剧本→分镜→配音→成片），34 风格模板 | 叙事精细控制弱（适合粗剪） | **快速验证模式**（"一句话→成片"粗剪） |
|
||||
|
||||
### 3.2 接入规范（适配器模式）
|
||||
|
||||
```python
|
||||
# 09_ave/scripts/directors/base.py
|
||||
class BaseDirector:
|
||||
id: str # "storyboard_v52" / "clip_storyboard" / "seedance_4" / "open_director"
|
||||
name: str
|
||||
capabilities: list # ["storyboard", "visual_concept", "consistency", "auto_pipeline"]
|
||||
def generate(self, story: str, anchors: GlobalAnchors, options: dict) -> Storyboard:
|
||||
"""任何导演系统 → 统一分镜 Schema（Storyboard）"""
|
||||
```
|
||||
|
||||
- **Skill 型**（v5.2 / clip / Seedance）：把技能文档作为**提示词注入**，调 LLM 产出分镜 → 适配器转 Schema
|
||||
- **Service 型**（OpenDirector）：调它的 HTTP 服务拿结果 → 适配器转 Schema
|
||||
- **切换方式**：控制台下拉选导演 + 每个导演独立的选项面板（如 clip 的 persistence 开关、Seedance 的配方选择）
|
||||
|
||||
### 3.3 视觉概念锁定（v5.2 的"两遍交付"）
|
||||
|
||||
```
|
||||
第一遍：设计稿 —— 锁定视觉概念（风格/色调/材质/构图语言），供导演确认
|
||||
第二遍：生产稿 —— 按确认的概念拆镜头，输出可执行分镜
|
||||
```
|
||||
→ 我们的 UI：分镜页分**两个 Tab**（设计稿 / 生产稿），设计稿确认后才生成生产稿。
|
||||
|
||||
---
|
||||
|
||||
## 四、③ 能力层（Capability Registry）★ 用户最想要的"基础能力整理"
|
||||
|
||||
### 4.1 能力定义结构
|
||||
|
||||
```yaml
|
||||
# 09_ave/config/capabilities.yaml
|
||||
capabilities:
|
||||
- id: tts_generate
|
||||
name: 语音合成
|
||||
category: audio # audio | visual | video | analysis | external
|
||||
description: 文本 → 语音音频
|
||||
input: { text: string, emotion: string?, speed: float? }
|
||||
output: { audio_path: string, duration: float }
|
||||
params_schema: # 参数定义（用于生成 UI 表单）
|
||||
emotion: { type: enum, options: [normal, happy, sad, angry], default: normal }
|
||||
speed: { type: number, min: 0.5, max: 2.0, default: 1.0 }
|
||||
providers: # ★ 多供应商
|
||||
- { id: volcano, name: 火山语音, api_key_ref: volcano.voice_app_key, default: true }
|
||||
- { id: aliyun, name: 阿里语音, api_key_ref: aliyun.api_key }
|
||||
- { id: fish_audio,name: Fish Audio, api_key_ref: fish_audio.api_key }
|
||||
defaults: { provider: volcano, emotion: normal, speed: 1.0 }
|
||||
```
|
||||
|
||||
### 4.2 四类能力来源
|
||||
|
||||
| 来源 | 说明 | 现有资产 |
|
||||
|:--|:--|:--|
|
||||
| **原子能力** | 后端已实现的固定能力 | `09_ave/scripts/01~06` + `main.py` CLI（voice/material/parse/compose/anchors…） |
|
||||
| **外部 API** | 第三方服务（多供应商） | 可灵 / 火山方舟(即梦) / 百炼(人物置换) / 阿里 TTS / Pexels |
|
||||
| **ComfyUI 工作流** | **能力孵化器**：一个工作流 = 一个新能力 | RunningHub（待接入）→ 可长出面部件表情控制、风格渲染等 |
|
||||
| **技能包** | 提示词型能力（导演/编剧/审核） | `ai-film-skills` 21 模块（待下载） |
|
||||
|
||||
### 4.3 能力盘点（从现有资产映射）
|
||||
|
||||
| 类别 | 已有能力 | 来源 |
|
||||
|:--|:--|:--|
|
||||
| 音频 | TTS 合成（火山/阿里）、BGM 生成、节拍分析、混音 | `02_voice_synthesizer` / `03_bgm_generator` / `main.py voice` |
|
||||
| 视觉 | 文生图（Kling）、图生视频（Kling）、人物置换（百炼）、定妆照 | `character_sheet.py` / `person_swap/` |
|
||||
| 视频 | 拼接、变速、转场、对口型、节拍同步、角色锁定 | `composer/`（ffmpeg/hybrid/speed_ramp/lipsync/character_locker/beat_sync） |
|
||||
| 分析 | 文案解析、分镜规划、锚点提取、素材搜索 | `01_director_parser` / `story_director` / `04_anchor_extractor` / `main.py material` |
|
||||
| **缺** | **去 AI 化**、字幕生成增强、ComfyUI、面部微表情 | 待建 / 待接 |
|
||||
|
||||
### 4.4 与大模型的关系
|
||||
|
||||
**能力 ≠ 模型**，但很多能力**背后是模型**：
|
||||
- TTS 能力 → 背后可选火山/阿里模型
|
||||
- 分镜能力 → 背后可选 DeepSeek / 其他 LLM
|
||||
- 图生视频 → 可灵 / 即梦 / 其他
|
||||
|
||||
→ 所以能力定义里既列 **providers**（服务商），也在 providers 里带 **model** 字段 → 与现有「🔑 API 配置」页打通（4.6.0 已做密钥管理）。
|
||||
|
||||
---
|
||||
|
||||
## 五、② 编排层：节点与流程
|
||||
|
||||
### 5.1 节点模型
|
||||
|
||||
```yaml
|
||||
node:
|
||||
id: n3
|
||||
type: capability # capability（能力节点）| control（控制节点）
|
||||
capability_id: tts_generate # 引用能力
|
||||
provider: volcano # 覆盖默认供应商
|
||||
model: null # 覆盖默认模型（null=用能力默认）
|
||||
params: # 覆盖能力默认参数（只写要改的）
|
||||
emotion: warm
|
||||
inputs: { text: "{{n1.script}}" } # 上游节点输出引用
|
||||
outputs: { audio_path: "var.audio" }
|
||||
ui: { x: 300, y: 160, collapsed: false }
|
||||
```
|
||||
|
||||
**两种节点**：
|
||||
- **能力节点**：引用一个能力（占 15 种节点类型的大部分）
|
||||
- **控制节点**：`audit_gate`（人工审核门）、分支、循环（现有 `audit_gate` 已有）
|
||||
|
||||
### 5.2 流程模板（Template）
|
||||
|
||||
现有 6 个 + 建议补充：
|
||||
|
||||
| 模板 | 线 | 现状 |
|
||||
|:--|:--|:--|
|
||||
| `basic_dub` 基础口播 | 口播线 | ✅ 已有（5 节点） |
|
||||
| `beat_sync` 卡点视频 | 卡点线 | ✅ 已有（4 节点） |
|
||||
| `character_narrative` 角色叙事 | 故事线 | ✅ 已有（8 节点） |
|
||||
| `digital_human` 数字人口播 | 数字人线 | ✅ 已有（4 节点） |
|
||||
| `hybrid_dub` 口播+卡点 | 混合线 | ✅ 已有（4 节点） |
|
||||
| `short_drama` 短剧创作 | 故事线 | ✅ 已有（12 节点） |
|
||||
| **`director_cut` 导演精剪**（建议新增） | DCS 主线 | 🆕 分镜编辑 + 逐镜头重试 + 去AI化 |
|
||||
|
||||
### 5.3 配置继承链（用户说的"默认值 + 可改"）
|
||||
|
||||
```
|
||||
全局默认（capability.defaults）
|
||||
↓ 被覆盖
|
||||
流程级（template.node_defaults） ← 这个流程普遍要改的
|
||||
↓ 被覆盖
|
||||
节点级（node.params） ← 这一次执行的
|
||||
↓ 被覆盖
|
||||
运行时输入（用户当场填） ← 内容/临时调整
|
||||
```
|
||||
|
||||
**UI 呈现**：节点配置面板里每个字段显示"**当前值 + 来源标记**"（默认/流程/节点/临时），改了就在当前层生效，并提供"恢复默认"。
|
||||
|
||||
---
|
||||
|
||||
## 六、④ 执行层（统一调度）★ 要补
|
||||
|
||||
### 6.1 现状问题
|
||||
|
||||
`workflows.py:519-530` 的 `WorkflowRunner._execute()` **只做拓扑排序然后标记 completed**，不真跑。
|
||||
真正能出片的是 `video_factory.py`（CLI），**两者未打通**。
|
||||
|
||||
### 6.2 补齐方案
|
||||
|
||||
```python
|
||||
# 执行器职责
|
||||
1. 拓扑排序（已有）
|
||||
2. 逐节点执行：按 node.capability_id 查能力注册表 → 取 provider → 调实现
|
||||
3. 状态机：pending → running → succeeded / failed / skipped
|
||||
4. 产物收集：每节点输出存入 run context（供下游 {n1.xxx} 引用）
|
||||
5. 失败重试：节点级重试次数 + 指数退避（复用 lib/retry 思路）
|
||||
6. 停止：支持中断运行中的流程
|
||||
7. 成本记账：调 lib.cost_tracker 记录每次调用花费
|
||||
8. 进度上报：写 run 状态 → 前端轮询展示（复用现有 /api/workflow/runs/{id}）
|
||||
```
|
||||
|
||||
**执行通道选项**：
|
||||
- **本地线程**（现有 `WorkflowRunner` 骨架 + threading）—— 适合轻量任务（解析/规划/合成）
|
||||
- **command_bus 派发**（现有养号体系）—— 适合长任务（Kling 生成、ComfyUI 渲染），有任务面板/重试/停止
|
||||
- **建议**：能力定义里带 `execution: local | remote` 字段，执行器按此选择通道
|
||||
|
||||
---
|
||||
|
||||
## 七、⑤ 资产层（共享底座）
|
||||
|
||||
### 7.1 目录结构（对齐 DCS 第五节 + 复用现有）
|
||||
|
||||
```
|
||||
agent-local/tools/ave/assets/ ← 运行时资产（不进 git）
|
||||
├── characters/ 角色 2D 参考图 + 定妆照 + voice_sample ✅ character_registry 已有
|
||||
├── characters_3d/ 3D 模型（混元3D，后期）
|
||||
├── locations/ 场景（AI 生成）
|
||||
├── real_locations/ 真实场地参考（多角度图 + 视频）
|
||||
├── products/ 产品资产（多角度 + must_keep 清单）
|
||||
├── props/ 道具
|
||||
├── bgm/ sfx/ BGM / 音效
|
||||
└── vfx_presets/ 特效预设（bullet_time.yaml 等）
|
||||
```
|
||||
|
||||
### 7.2 引用方式
|
||||
|
||||
分镜 Schema 里按 **id** 引用（`character_id` / `location_id` / `product_id` / `props[]` / `bgm_id` / `vfx.vfx_id`），执行器按 id 去资产库取文件路径注入 API 请求。
|
||||
|
||||
---
|
||||
|
||||
## 八、④/⑤ 之外的横切：大模型与供应商管理
|
||||
|
||||
| 项 | 现状 | 落地 |
|
||||
|:--|:--|:--|
|
||||
| 密钥管理 | ✅ 「🔑 API 配置」页（脱敏 + 测试 + 版本回滚） | 能力注册表的 `api_key_ref` 指向它 |
|
||||
| 供应商切换 | 🟡 分散在代码 | 能力定义里 providers 列表 + UI 下拉 |
|
||||
| 模型切换 | 🟡 仅 AI 文本（DeepSeek） | 扩展到 TTS/图像/视频模型 |
|
||||
| 效果对比 | ❌ | **建议**：每次执行记录所用 provider/model 组合 → 后续可按"效果好的组合"复用 |
|
||||
|
||||
---
|
||||
|
||||
## 九、UI 结构（菜单重组）
|
||||
|
||||
```
|
||||
🎬 视频工厂
|
||||
├─ 📦 资产管理 ← 共享底座
|
||||
│ 🧑 角色库（生成/列表/定妆照/音色）· 🎬 场景库 · 🧊 产品道具 · 🖼️ 素材库 · 🔄 人物置换
|
||||
│
|
||||
├─ 🎞️ 创作（生产路径） ← 一条线一个入口
|
||||
│ 🎬 导演创作★（故事→分镜→成片，默认）· 🎙️ 口播 · 🥁 卡点 · 👤 数字人 · 🎭 模仿换人
|
||||
│
|
||||
├─ ⚙️ 编排 ← 能力与流程
|
||||
│ 🔀 工作流（画布 + 真执行）· 🧩 能力库（注册表 + 供应商/参数默认值）· 🎨 流程模板 · 📋 生产记录 · 💰 费用
|
||||
│
|
||||
└─ 🔧 配置
|
||||
⚡ 能力目录（只读总览）· 🤖 模型与供应商 · 🎯 导演系统 · 🔑 API 配置
|
||||
```
|
||||
|
||||
**每个节点打开后的配置面板**（用户核心诉求）：
|
||||
|
||||
```
|
||||
┌─ 节点：语音合成 ────────────────────┐
|
||||
│ 供应商 [火山语音 ▾]（默认） │ ← 可换：火山/阿里/Fish
|
||||
│ 模型 [CosyVoice ▾]（默认） │ ← 可换
|
||||
│ 情绪 [normal ▾]（流程覆盖） │ ← 显示来源
|
||||
│ 语速 [1.0]（默认） │
|
||||
│ ────────────────────────────── │
|
||||
│ 输入 text ← {{n1.script}} │
|
||||
│ 输出 audio_path → var.audio │
|
||||
│ [测试此节点] [恢复默认] [保存] │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十、实施路线
|
||||
|
||||
| 阶段 | 内容 | 交付 |
|
||||
|:--|:--|:--|
|
||||
| **S1｜能力注册表** | `capabilities.yaml` + 后端加载器 + 「🧩 能力库」页（列表 + 供应商/参数默认值编辑） | 看得见"我有哪些能力" |
|
||||
| **S2｜M1 导演创作** | 统一分镜 Schema + 导演适配器（先接 v5.2）+ 分镜编辑页 + 调真实流水线出片 | **一条 20 秒成片** |
|
||||
| **S3｜执行器补齐** | `WorkflowRunner` 真执行（能力注册表驱动）+ 节点配置面板（默认/覆盖）+ 状态/重试/停止 | 工作流"通电" |
|
||||
| **S4｜资产库扩展** | locations / products / props / vfx_presets + 上传 UI + `global_anchors` 全量注入 | 一致性保障 |
|
||||
| **S5｜能力扩展** | ComfyUI(RunningHub) 接入 + 更替导演系统（clip/Seedance 可切）+ 效果对比记录 | 能力孵化 |
|
||||
|
||||
---
|
||||
|
||||
## 十一、现有资产映射（复用 / 改造 / 新建）
|
||||
|
||||
| 现有资产 | 处置 |
|
||||
|:--|:--|
|
||||
| `09_ave/scripts/01~06`、`main.py` CLI | **复用**为能力层实现（包一层能力接口） |
|
||||
| `composer/`（ffmpeg/hybrid/lipsync/speed_ramp/beat_sync/character_locker） | **复用**为视频类能力 |
|
||||
| `video_factory.py`（run_oral/beat/story/…） | **改造**：拆成能力 + 保留为"快速命令"入口 |
|
||||
| `story_director/`（scene_planner/temporal_bridge/batch_generator） | **改造**为"导演适配器"之一（与 v5.2 并列可选） |
|
||||
| `workflows.py`（6 模板 + 15 节点定义） | **复用**：节点定义 → 对齐能力注册表；**补执行器** |
|
||||
| `app.py` + `plugins/ave.py` + `/api/capabilities` | **复用**：能力目录数据源从"解析 Markdown"改为读能力注册表 |
|
||||
| `person_swap/` / `character_sheet.py` | **复用**为能力（换脸 / 文生图） |
|
||||
| `lib/cost_tracker.py` | **复用**为执行层记账 |
|
||||
| `character_registry/` | **扩展**为完整资产库 |
|
||||
| **能力注册表**（`config/capabilities.yaml` + 加载器） | 🆕 **新建（S1）** |
|
||||
| **导演适配器**（`directors/base.py` + 各实现） | 🆕 **新建（S2）** |
|
||||
| **去 AI 化**（`composer/de_ai.py`） | 🆕 **新建（S2）** |
|
||||
| **分镜编辑 UI**（`views/ave-director.js`） | 🆕 **新建（S2）** |
|
||||
| `ai-film-skills` 21 模块 | 🆕 **下载并入**（建议 `05_tools/09_ave/skills/`） |
|
||||
|
||||
---
|
||||
|
||||
## 十二、待确认
|
||||
|
||||
1. **S1 先做还是 S2 先做？**（我建议 S1 能力注册表 —— 它是后面所有事的底座，半天出初版）
|
||||
2. **`ai-film-skills` 是否下载入库**？（Apache-2.0，含 v5.2 分镜技能 + 人物/场景/道具资产规范）
|
||||
3. **去 AI 化默认开吗**？（DCS 参数：模糊 0.4 / 颗粒 12 / 饱和 -0.12 / 色温 5300K）
|
||||
4. **执行通道偏好**：轻任务本地线程 + 长任务走 command_bus/guardd —— 认可？
|
||||
5. **菜单重组时机**：S1/S2 期间只加必要入口，S3 时按第九节整体重组 —— 还是尽早重组？
|
||||
@@ -0,0 +1,530 @@
|
||||
# 视频工厂框架说明书 v1.0
|
||||
|
||||
> 创建: 2026-10-01 | 状态: **框架对齐中（待你确认后冻结）**
|
||||
> 定位: 视频工厂的**纲领文档** —— 模块边界、五张地图、解耦规范、代码组织、实施路径、扩展速查
|
||||
> 配套: `DCS_VIDEO_FACTORY_PLAN.md`（现状调研 + M1 落地细节）
|
||||
> 输入: DCS 说明书 v2.0 + 用户口述需求 + 4 个导演系统调研
|
||||
|
||||
---
|
||||
|
||||
## 〇、一句话定位
|
||||
|
||||
> **视频工厂是一个「调用层 + 编排层」—— 大模型能力全部解耦在远端，我们只负责：选（哪家能力）、调（带什么参数）、串（流程怎么走）、管（资产/产物/成本）。**
|
||||
|
||||
**明确边界**（避免越做越乱）：
|
||||
|
||||
| 是 ✅ | 不是 ❌ |
|
||||
|:--|:--|
|
||||
| 能力调用层（封装远端 API，多供应商可选） | 模型训练 / 推理（全部远端） |
|
||||
| 流程编排层（能力串成流水线） | 渲染农场（FFmpeg 本地轻量处理） |
|
||||
| 资产管理层（角色/场景/产品/道具/音效） | 素材库平台（只做引用与索引） |
|
||||
| 产物与成本管理层 | 剪辑软件（不做精细时间线编辑） |
|
||||
|
||||
**与养号模块的关系**：**并列**。共用 Dashboard、账号体系、任务面板、API 配置页；互不侵入。
|
||||
|
||||
---
|
||||
|
||||
## 一、五张地图
|
||||
|
||||
### 地图 1｜架构图（5 层 + 4 替换点）
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────────────────┐
|
||||
│ L5 接入层（Dashboard 前端） │
|
||||
│ 🎬导演创作 · 🔀工作流 · 🧩能力库 · 📦资产库 · 🎯导演系统 · 🤖模型供应商 │
|
||||
└────────────────────────────────┬─────────────────────────────────────────┘
|
||||
↓ HTTP (FastAPI :9988)
|
||||
┌──────────────────────────────────────────────────────────────────────────┐
|
||||
│ L4 编排层（后端） │
|
||||
│ · 流程执行器（拓扑排序 → 逐节点执行 → 状态机 → 重试/停止） │
|
||||
│ · 节点配置解析（默认 ← 流程 ← 节点 ← 运行时 四级继承） │
|
||||
│ · 分镜编辑器后端（统一 Schema 读写） │
|
||||
└────────────────────────────────┬─────────────────────────────────────────┘
|
||||
↓ 按 capability_id 查注册表
|
||||
┌──────────────────────────────────────────────────────────────────────────┐
|
||||
│ L3 能力层（Capability Registry）★替换点②供应商 ★替换点③模型 │
|
||||
│ 音频: TTS/BGM/节拍/混音 视觉: 文生图/图生视频/换脸/对口型/运镜 │
|
||||
│ 视频: 拼接/变速/转场/字幕/去AI化 分析: 解析/分镜/提示词/审核 │
|
||||
│ 外部: ComfyUI 工作流（孵化器） │
|
||||
│ 每个能力: input/output/params_schema/providers[]/defaults/execution │
|
||||
└────────────────────────────────┬─────────────────────────────────────────┘
|
||||
↓ 本地线程 或 command_bus 派发
|
||||
┌──────────────────────────────────────────────────────────────────────────┐
|
||||
│ L2 执行层（统一调度） │
|
||||
│ 本地任务（解析/规划/合成）· 远程任务（生成类，走 guardd） │
|
||||
│ 状态机 / 轮询 / 重试 / 停止 / 产物收集 / 成本记账 │
|
||||
└────────────────────────────────┬─────────────────────────────────────────┘
|
||||
↓ 按 id 取资产
|
||||
┌──────────────────────────────────────────────────────────────────────────┐
|
||||
│ L1 资产层（共享底座）★替换点④内容 │
|
||||
│ 角色(含3D) · 场景 · 产品 · 道具 · BGM · 音效 · 特效预设 · 风格 │
|
||||
└──────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
★替换点①导演：AI Storyboard Director v5.2(默认) | clip-storyboard | Seedance 4.0 | OpenDirector
|
||||
全部输出同一份「统一分镜 Schema」
|
||||
```
|
||||
|
||||
### 地图 2｜能力地图（现有 + 规划）
|
||||
|
||||
| 类别 | 能力 | 供应商（可选） | 现状 |
|
||||
|:--|:--|:--|:--|
|
||||
| **音频** | TTS 语音合成 | 火山语音 ✅ / 阿里语音 ✅ / Fish Audio(待) / ElevenLabs(待) | 已有 |
|
||||
| | BGM 生成 | ACE-Step / MusicGen / Suno | 已有（`03_bgm_generator`） |
|
||||
| | 节拍分析 | 本地 librosa 类 | 已有（`beat_sync`） |
|
||||
| | 混音 / 变速 | 本地 FFmpeg | 已有（`composer`） |
|
||||
| **视觉** | 文生图（定妆照/概念图） | 可灵 v1 ✅ / 火山即梦 ✅ | 已有（`character_sheet`） |
|
||||
| | 图生视频 | 可灵 ✅(余额不足) / 火山即梦 ✅ | 已有（`batch_generator`） |
|
||||
| | 文生视频 | 可灵 / 通义万相(待) / Sora(待) | 部分 |
|
||||
| | 人物置换（换脸） | 阿里百炼 wan2.2-animate-mix ✅(欠费) | 已有（`person_swap`） |
|
||||
| | 对口型（数字人） | 火山 OmniHuman / D-ID(待) / HeyGen(待) | 已有 |
|
||||
| | 运镜控制 | 可灵 camera_control（6 参数） | 待接 |
|
||||
| | 特效（子弹时间等） | 万兴天幕(待) / 海螺AI(待) / ComfyUI | 待接 |
|
||||
| | **面部微表情** | ComfyUI 工作流 | 待接 |
|
||||
| **视频** | 拼接 / 转场 | 本地 FFmpeg | 已有（`composer/ffmpeg`） |
|
||||
| | 变速 / 速度斜坡 | 本地 | 已有（`speed_ramp`） |
|
||||
| | 字幕 | 本地（SRT/ASS） | 部分 |
|
||||
| | **去 AI 化** | 本地 FFmpeg 链 | 🆕 待建 |
|
||||
| | 3D 角色 | 混元3D(待) | 待接 |
|
||||
| **分析** | 文案解析 | LLM（DeepSeek ✅） | 已有（`01_director_parser`） |
|
||||
| | 分镜规划 | **导演系统**（见替换点①） | 已有（`scene_planner`）+ 待接 v5.2 |
|
||||
| | 提示词生成 | LLM / 导演技能 | 已有 |
|
||||
| | 内容审核 | LLM / 人工门 | 部分（`audit_gate`） |
|
||||
| **外部** | ComfyUI 工作流 | RunningHub(待) / ComfyDeploy(待) / 自建 | 🆕 待接 |
|
||||
|
||||
### 地图 3｜菜单地图
|
||||
|
||||
**当前已落地（4.8.1 重组后）**：
|
||||
|
||||
```
|
||||
📦 🎬 视频·资产 ← 共享底座
|
||||
🧑 角色库（characters）· 🎭 角色生成器（char-gen）· 🖼️ 素材库（assets）· 🔄 人物置换（person-swap）
|
||||
|
||||
⚙️ 🎬 视频·编排 ← 能力与流程
|
||||
🔀 工作流（workflow）· 🧩 能力库（ave-capabilities，可编辑注册表）
|
||||
📋 生产记录（productions）· 💰 费用分析（costs）
|
||||
|
||||
🔧 🎬 视频·配置
|
||||
⚡ 能力总览（capabilities，只读；与「能力库」互补）
|
||||
|
||||
🎬 视频·创作 ← 待 S2 建立页面后加入
|
||||
🎬 导演创作★（ave-director）· 🎙️ 口播 · 🥁 卡点 · 👤 数字人 · 🎭 模仿换人
|
||||
```
|
||||
|
||||
**目标形态（框架规划，S2~S4 逐步补齐）**：
|
||||
|
||||
```
|
||||
🎬 视频工厂
|
||||
├─ 📦 资产管理 🧑 角色库 · 🎬 场景库 · 🧊 产品道具 · 🖼️ 素材库 · 🔄 人物置换
|
||||
├─ 🎞️ 创作 🎬 导演创作★ · 🎙️ 口播 · 🥁 卡点 · 👤 数字人 · 🎭 模仿换人
|
||||
├─ ⚙️ 编排 🔀 工作流 · 🧩 能力库 · 🎨 流程模板 · 📋 生产记录 · 💰 费用
|
||||
└─ 🔧 配置 ⚡ 能力总览 · 🤖 模型与供应商 · 🎯 导演系统 · 🔑 API 配置
|
||||
```
|
||||
|
||||
### 地图 4｜端到端流程图（导演创作主线）
|
||||
|
||||
```
|
||||
【1. 起意】
|
||||
选导演系统(M) ── 5.2默认 / clip一致性 / Seedance配方 / OpenDirector全自动
|
||||
写故事 ─────── 手写 or 粘贴 or(AI 从主题生成)
|
||||
选资产 ─────── 角色(必) / 场景 / 产品 / 风格
|
||||
设全局锚点 ──── consistency_seed / shooting_style / 光照/镜头语言
|
||||
↓
|
||||
【2. 分镜（导演干活）】
|
||||
① 设计稿：锁视觉概念（风格/色调/材质/构图）→ 人工确认 ★v5.2 两遍交付
|
||||
② 生产稿：按概念拆镜头 → 统一分镜 Schema（每镜头：景别/机位/运镜/时长/画面/台词/情绪）
|
||||
↓
|
||||
【3. 分镜编辑（人工把关）】
|
||||
逐条看 → 改画面描述/台词/时长 → 删镜头/加镜头 → 加特效(占位) → 单镜头重生成
|
||||
↓
|
||||
【4. 逐镜头执行（能力层）】
|
||||
每镜头按 type 选能力：
|
||||
action → 图生视频（可灵/即梦）
|
||||
talking_head → 口播（火山/D-ID）
|
||||
background → 素材/背景生成（通义万相/素材库）
|
||||
vfx → 特效（可灵运镜/万兴/ComfyUI）
|
||||
3d_character → 3D 角色（混元3D）
|
||||
每镜头可调：供应商 / 模型 / 参数（覆盖默认）
|
||||
↓
|
||||
【5. 合成（本地）】
|
||||
配音(TTS) → 去AI化(模糊/颗粒/调色) → 拼接 → BGM → 字幕 → 成片 mp4
|
||||
↓
|
||||
【6. 验收与迭代】
|
||||
预览成片 → 不满意 → 回到【3】改对应镜头 → 单条重试（不必整片重跑）
|
||||
满意 → 生产记录归档 + 成本入账
|
||||
```
|
||||
|
||||
### 地图 5｜数据流（统一 Schema 是中枢）
|
||||
|
||||
```
|
||||
导演系统 ──出──→ ┌──────────────────┐ ──读──→ 分镜编辑器 UI
|
||||
│ 统一分镜 Schema │
|
||||
资产库 ──id引用─→ │ Storyboard │ ──读──→ 执行器（逐镜头派任务）
|
||||
│ ├ GlobalAnchors│
|
||||
│ └ Shot[] │ ──写──→ 执行状态（每镜头）
|
||||
└──────────────────┘ ──写──→ 产物路径 + 成本记录
|
||||
```
|
||||
|
||||
**Schema 的三大作用**：① 导演系统的"普通话"（谁都能读）② 前端编辑对象 ③ 执行器的输入契约。
|
||||
|
||||
---
|
||||
|
||||
## 二、解耦机制（4 个扩展点 + 契约）
|
||||
|
||||
### 扩展点①：导演系统（新增一个导演 = 实现一个类）
|
||||
|
||||
```python
|
||||
# 09_ave/scripts/directors/base.py
|
||||
class BaseDirector:
|
||||
id: str # "storyboard_v52"
|
||||
name: str # "AI Storyboard Director v5.2"
|
||||
kind: str # "skill" | "service"
|
||||
features: list # ["visual_concept", "two_pass", "consistency"]
|
||||
options_schema: dict # 该导演的专属选项（自动生成 UI 表单）
|
||||
|
||||
def generate(self, story, anchors, options) -> Storyboard:
|
||||
"""输出统一分镜 Schema —— 这是唯一的契约"""
|
||||
|
||||
# 注册（directors/__init__.py）
|
||||
DIRECTORS = {d.id: d for d in [StoryboardV52(), ClipStoryboard(), Seedance4(), OpenDirector()]}
|
||||
```
|
||||
|
||||
**接入一个新导演系统，只需 3 步**：
|
||||
1. 在 `directors/` 加一个文件，实现 `BaseDirector`
|
||||
2. 在 `directors/__init__.py` 注册
|
||||
3. （如需要）加它的选项面板 schema
|
||||
|
||||
→ 前端下拉自动出现，下游全不用改。
|
||||
|
||||
### 扩展点②：能力供应商（一个能力接多家）
|
||||
|
||||
```yaml
|
||||
# 09_ave/config/capabilities.yaml
|
||||
- id: image_to_video
|
||||
name: 图生视频
|
||||
category: visual
|
||||
input: { image: file, prompt: string, duration: number }
|
||||
output: { video_path: string }
|
||||
params_schema:
|
||||
duration: { type: number, min: 3, max: 10, default: 5 }
|
||||
providers:
|
||||
- { id: kling, name: 可灵, api_key_ref: kling.api_key, model: kling-v1, default: true }
|
||||
- { id: jimeng, name: 即梦, api_key_ref: volcano.ark_api_key, model: seedance }
|
||||
defaults: { provider: kling }
|
||||
execution: remote # local | remote（决定走本地线程还是 guardd）
|
||||
impl: providers.visual.kling_i2v # 实现类路径
|
||||
```
|
||||
|
||||
### 扩展点③：模型（能力背后的 LLM/模型）
|
||||
|
||||
- providers 里带 `model` 字段 → UI 可切
|
||||
- LLM 类能力（解析/分镜/提示词）也走同一机制：providers = DeepSeek / 其他
|
||||
- 与「🔑 API 配置」页打通（`api_key_ref` 指向已有密钥管理）
|
||||
|
||||
### 扩展点④：资产（内容可换）
|
||||
|
||||
- 所有流程按 **id** 引用资产（`character_id` / `location_id` / `product_id` / `bgm_id` / `vfx.vfx_id`）
|
||||
- 新增一类资产 = 加目录 + 加 meta.json 规范 + （可选）加管理 UI
|
||||
|
||||
### 配置继承链（四级覆盖）
|
||||
|
||||
```
|
||||
① 能力默认值（capabilities.yaml → defaults）
|
||||
↓ 被覆盖
|
||||
② 流程级（template.node_defaults）
|
||||
↓ 被覆盖
|
||||
③ 节点级（node.params）
|
||||
↓ 被覆盖
|
||||
④ 运行时（用户当场填）
|
||||
```
|
||||
UI 每个字段标注**来源**（默认/流程/节点/临时），并支持"恢复默认"。
|
||||
|
||||
---
|
||||
|
||||
## 三、代码组织规范
|
||||
|
||||
### 后端目录（`05_tools/09_ave/`）
|
||||
|
||||
```
|
||||
scripts/
|
||||
├── capabilities/ 🆕 能力层实现（每个能力一个文件，实现统一接口）
|
||||
│ ├── base.py 能力基类（input/output/params/providers）+ 注册表加载器
|
||||
│ ├── audio/ tts.py / bgm.py / beat.py / mix.py
|
||||
│ ├── visual/ t2i.py / i2v.py / swap_face.py / lipsync.py
|
||||
│ ├── video/ concat.py / speed.py / subtitle.py / de_ai.py ← de_ai 新建
|
||||
│ ├── analysis/ script_parse.py / storyboard.py / prompt_gen.py / review.py
|
||||
│ └── external/ comfyui.py（RunningHub）
|
||||
├── directors/ 🆕 导演层（替换点①）
|
||||
│ ├── base.py
|
||||
│ ├── storyboard_v52.py （默认，接 ai-film-skills 的 v5.2 技能）
|
||||
│ ├── clip_storyboard.py / seedance_4.py / open_director.py
|
||||
│ └── legacy_scene_planner.py （现有 story_director 包装为适配器）
|
||||
├── schemas.py 🆕 统一分镜 Schema（12 模型）
|
||||
├── executor/ 🆕 编排执行器
|
||||
│ ├── engine.py 拓扑排序 + 逐节点执行 + 状态机
|
||||
│ ├── config_resolver.py 四级配置继承解析
|
||||
│ └── task_runner.py local/remote 双通道（remote 走 command_bus）
|
||||
├── assets/ 🆕 资产管理（loader/validator/registry）
|
||||
├── composer/ ✅ 已有（ffmpeg/hybrid/lipsync/speed_ramp/beat_sync/character_locker）
|
||||
├── story_director/ ✅ 已有（作为 legacy 导演，保留）
|
||||
├── lib/ ✅ 已有（config/cost_tracker/dashboard/logger）
|
||||
├── skills/ 🆕 ai-film-skills 21 模块（导演/资产/摄影方法论）
|
||||
├── config/
|
||||
│ ├── capabilities.yaml 🆕 能力注册表（唯一的"能力真相源"）
|
||||
│ ├── directors.yaml 🆕 导演注册配置
|
||||
│ └── providers.yaml 🆕 供应商/模型配置（密钥引用 API 配置页）
|
||||
└── main.py ✅ 已有（CLI 原子命令，保留为调试入口）
|
||||
```
|
||||
|
||||
### 前端目录（`05_tools/10_dashboard/frontend/src/`）
|
||||
|
||||
```
|
||||
views/
|
||||
├── ave-director.js 🆕 导演创作（分镜编辑，M1 主入口）
|
||||
├── ave-capabilities.js 🆕 能力库（注册表管理 + 供应商/参数默认值）
|
||||
├── ave-assets-*.js 🆕 场景库 / 产品道具
|
||||
├── workflow.js ✅ 已有（画布，补执行器）
|
||||
├── capabilities.js ✅ 已有（只读总览）
|
||||
├── char-gen.js / characters.js / person-swap.js / productions.js / assets.js / costs.js ✅ 已有
|
||||
├── ave-script.js / ave-materials.js / ave-render.js / ave-templates.js ⚪ 空壳（择机激活或删除）
|
||||
nav-menu.js ✅ 菜单单点定义（按地图 3 重组时只改这里）
|
||||
```
|
||||
|
||||
### 接口约定
|
||||
|
||||
| 层 | 约定 |
|
||||
|:--|:--|
|
||||
| 能力接口 | `generate(inputs, params, provider) -> {status, output, cost, error}`（对齐 DCS 统一返回） |
|
||||
| 导演接口 | `generate(story, anchors, options) -> Storyboard` |
|
||||
| 执行器 | `run(template_id, node_overrides) -> run_id`；`get_run(run_id) -> {status, node_states, artifacts}` |
|
||||
| API 路由 | 前端统一 `/api/ave/*`（新建 `routes/ave.py` 或扩插件），不散落 |
|
||||
|
||||
---
|
||||
|
||||
## 四、实施路径（5 阶段，每阶段可独立验收）
|
||||
|
||||
| 阶段 | 改什么 | 加什么 | 验收 |
|
||||
|:--|:--|:--|:--|
|
||||
| **S1 能力注册表** | `plugins/ave.py`（数据源改读注册表）；`/api/capabilities` | `config/capabilities.yaml` + `capabilities/base.py` 加载器 + `views/ave-capabilities.js` | 「🧩 能力库」页能看到全部能力 + 改供应商/参数默认值并保存 |
|
||||
| **S2 导演创作（M1）** | 现有流水线包能力接口 | `schemas.py` + `directors/`（v5.2 适配器）+ `routes/ave.py` + `views/ave-director.js` + `composer/de_ai.py` | **一条 20 秒成片**：故事→分镜表(可编辑)→生成→去AI化→拼接→预览 |
|
||||
| **S3 执行器补齐** | `workflows.py` 的 `WorkflowRunner`（真执行） | `executor/engine.py` + `config_resolver.py` + 节点配置面板（前端） | 工作流"通电"：6 模板能真跑；节点可改供应商/模型；失败可重试 |
|
||||
| **S4 资产库扩展** | `character_registry` 扩展 | 场景/产品/道具/特效预设目录 + 上传 UI + `global_anchors` 全量注入 | 多镜头角色/场景一致；资产按 id 引用生效 |
|
||||
| **S5 能力扩展** | — | `capabilities/external/comfyui.py`（RunningHub）+ 其他导演系统实装 + 效果对比记录 | 新能力可"加文件即接入"；导演可切换对比 |
|
||||
|
||||
**S1 优先的理由**：它是"能力真相源"，S2/S3 都依赖它；且半天可出初版，让你先看清家底。
|
||||
|
||||
---
|
||||
|
||||
## 五、扩展点速查（"以后怎么加东西"）
|
||||
|
||||
| 我要做的事 | 改哪里 | 步骤 |
|
||||
|:--|:--|:--|
|
||||
| **加一个新能力**（如"面部微表情"） | `config/capabilities.yaml` + `capabilities/<类目>/xxx.py` | ① 写实现类（实现能力接口）② yaml 加一条（input/output/params/providers）③ 重启，UI 自动出现 |
|
||||
| **给已有能力加供应商** | `config/capabilities.yaml` | providers 加一条（id/name/api_key_ref/model）；密钥在「🔑 API 配置」页填 |
|
||||
| **换默认模型** | `config/capabilities.yaml` 或「🧩 能力库」页 | 改 `defaults.model` / UI 里改 |
|
||||
| **接一个新导演系统** | `directors/xxx.py` + `__init__.py` 注册 | ① 实现 `BaseDirector.generate() → Storyboard` ② 注册 ③ （可选）加选项 schema |
|
||||
| **加一个新流程模板** | `workflows.py` 的 `WORKFLOW_TEMPLATES` | 加一条（nodes + edges），复用现有 15 种节点类型 |
|
||||
| **接入一个新开源项目** | 见下方"接入清单" | — |
|
||||
| **加一类新资产** | `assets/` 目录 + meta 规范 + （可选）UI | 目录 + meta.json + loader 注册 |
|
||||
| **改菜单** | `frontend/src/nav-menu.js` | **单点定义**，只改这一个文件（4.6.4 已单点化） |
|
||||
|
||||
### 接入一个新开源项目的清单（通用）
|
||||
|
||||
```
|
||||
□ 1. 判定类型：导演型 / 能力型 / 全流程型（OpenDirector）/ 资产规范型
|
||||
□ 2. 判定形态：Skill（提示词包）→ 放 skills/ ｜ Service（HTTP）→ 写 provider ｜ 代码库 → 抽能力
|
||||
□ 3. 查许可：Apache/MIT 可直接并入；GPL 谨慎；商业需授权
|
||||
□ 4. 找契约点：它输出什么？→ 对应我们的哪个扩展点（导演/能力/资产）
|
||||
□ 5. 写适配器：把它的输出转成统一 Schema 或能力返回值
|
||||
□ 6. 注册 + 配置（yaml 一条）+ UI 下拉出现
|
||||
□ 7. 记录来源与版本（便于后续升级）
|
||||
```
|
||||
|
||||
**示例**：接入 v5.2（Skill 型导演）→ 放 `skills/ai-film-skills/`，写 `directors/storyboard_v52.py` 把技能文档作为提示词注入，输出转 `Storyboard`，注册 → UI 下拉出现。
|
||||
|
||||
---
|
||||
|
||||
## 六、当前状态与差距
|
||||
|
||||
| 层 | 现状 | 差距 |
|
||||
|:--|:--|:--|
|
||||
| L5 接入层 | 8 视图（4 空壳）；菜单 8 项混三种性质 | 缺导演创作/能力库页；菜单待按地图 3 重组 |
|
||||
| L4 编排层 | 6 模板 + 15 节点定义齐 | ❌ **执行器空转**（只拓扑排序不真跑）；❌ 无节点配置面板；❌ 无分镜编辑 |
|
||||
| L3 能力层 | 原子能力齐（01-06 + CLI + composer 2635 行） | ❌ 无统一注册表（供应商/参数 schema）；❌ 缺去AI化 |
|
||||
| L2 执行层 | guardd/command_bus 体系成熟（养号在用） | 🟡 未与视频工厂任务打通 |
|
||||
| L1 资产层 | 仅有角色（character_registry + 定妆照） | ❌ 场景/产品/道具/特效预设 全缺 |
|
||||
| 统一 Schema | ❌ 无 | 🆕 待建（S2） |
|
||||
| 导演可切换 | 仅 `story_director/scene_planner` 一套 | 🆕 适配器框架 + v5.2 待接（S2） |
|
||||
|
||||
---
|
||||
|
||||
## 七、框架确认清单（请你逐条确认/修改）
|
||||
|
||||
| # | 框架要点 | 确认 |
|
||||
|:--|:--|:--|
|
||||
| 1 | 定位：**调用层 + 编排层**（模型全远端，不做训练/推理） | ☐ |
|
||||
| 2 | 5 层架构 + **4 个替换点**（导演/供应商/模型/资产） | ☐ |
|
||||
| 3 | 统一分镜 Schema 作中枢（所有导演系统输出它） | ☐ |
|
||||
| 4 | 四级配置继承（能力默认→流程→节点→运行时） | ☐ |
|
||||
| 5 | 菜单 4 组：资产管理 / 创作 / 编排 / 配置 | ☐ |
|
||||
| 6 | 能力注册表（`capabilities.yaml`）为"能力真相源" | ☐ |
|
||||
| 7 | 执行双通道：轻任务本地线程 / 长任务 guardd | ☐ |
|
||||
| 8 | 代码组织：`capabilities/` `directors/` `executor/` `assets/` 四个新目录 | ☐ |
|
||||
| 9 | 实施顺序 S1→S5（S1 能力注册表优先） | ☐ |
|
||||
| 10 | 扩展点速查（加能力/供应商/导演/模板/开源项目）为标准流程 | ☐ |
|
||||
|
||||
**确认后冻结框架**，后续所有开发按此对齐；如需变更，改本文档 + 记 CHANGELOG。
|
||||
|
||||
---
|
||||
|
||||
## 附录 A｜现有代码在框架中的位置（2026-10-01 实测盘点）
|
||||
|
||||
> 目的：看清"家底"在框架里的位置。✅ 已就位 ｜ 🟡 需改造 ｜ 🆕 待建
|
||||
|
||||
### A.1 后端资产（`05_tools/09_ave/`，约 19,000 行）
|
||||
|
||||
**L1 资产层（替换点④）**
|
||||
|
||||
| 现有资产 | 行数 | 框架位置 |
|
||||
|:--|:--|:--|
|
||||
| `character_registry/` | 318 | ✅ 角色注册表（资产库·角色） |
|
||||
| `character_generator/` | 2296 | ✅ 角色生成能力 |
|
||||
| `character_sheet.py` | 841 | ✅ 定妆照/角色图（文生图能力） |
|
||||
| `character_portrait.py` | 790 | ✅ 角色画像 |
|
||||
| `character_adapter/` | 397 | ✅ 角色适配（跨模块统一） |
|
||||
| `asset_manager/`（cache/index/tags） | 1167 | 🟡 资产索引 → 扩展为完整资产库 |
|
||||
| `lib/ghvideo_upload.py` | — | ✅ 产物上传 |
|
||||
| 🆕 场景库 / 产品库 / 道具库 / 特效预设 | — | 🆕 待建（S4） |
|
||||
|
||||
**L3 能力层（替换点②③）**
|
||||
|
||||
| 现有资产 | 行数 | 能力归类 | 状态 |
|
||||
|:--|:--|:--|:--|
|
||||
| `audio_line/`（layer2_analysis / layer3_creation） | 3530 | 音频分析 + 创作 | ✅ 已有（**最大音频资产**，待接入主流程） |
|
||||
| `bgm_generator/`（suno 等 4 文件） | 654 | BGM 生成 | ✅ 已有 |
|
||||
| `music_selector/` | 371 | BGM 选择 | ✅ 已有 |
|
||||
| `main.py voice`（调 aliyun/volcano） | — | TTS 合成 | ✅ 已有（无独立模块，在 CLI 内） |
|
||||
| `character_sheet.py` | 841 | 文生图（Kling v1） | ✅ 已有 |
|
||||
| `story_director/batch_generator.py` | 664 | 图生视频（Kling 批量） | ✅ 已有 |
|
||||
| `person_swap/` | — | 人物置换（百炼 wan2.2-animate-mix） | ✅ 已有 |
|
||||
| `composer/ffmpeg.py` | 702 | 拼接 / 转场 / 合成 | ✅ 已有 |
|
||||
| `composer/speed_ramp.py` | 370 | 变速 / 速度斜坡 | ✅ 已有 |
|
||||
| `composer/lipsync.py` | 369 | 对口型 | ✅ 已有 |
|
||||
| `composer/beat_sync.py` | — | 节拍同步 | ✅ 已有 |
|
||||
| `composer/hybrid.py` | 453 | 混合合成（口播+卡点） | ✅ 已有 |
|
||||
| `composer/character_locker.py` | 68 | **角色锁定（一致性！）** | ✅ 已有（对应 DCS 的 consistency_seed） |
|
||||
| `material_producer/`（pexels / wan2_2 / fallback） | 902 | 素材生产 | ✅ 已有 |
|
||||
| `director_parser/`（parser + schemas） | 323 | 文案解析 | ✅ 已有 |
|
||||
| `story_director/scene_planner.py` | 444 | **分镜规划** | ✅ 已有（→ 可包装为 legacy 导演适配器） |
|
||||
| `story_director/temporal_bridge.py` | 322 | 场景过渡桥接 | ✅ 已有 |
|
||||
| `anchor_extractor/` | 155 | 锚点提取 | ✅ 已有 |
|
||||
| 🆕 去 AI 化 | — | 视频后处理 | 🆕 待建（S2） |
|
||||
| 🆕 ComfyUI / 运镜 / 特效 / 面部微表情 / 3D | — | 视觉扩展 | 🆕 待接（S5） |
|
||||
|
||||
**L4 编排层**
|
||||
|
||||
| 现有资产 | 规模 | 框架位置 | 状态 |
|
||||
|:--|:--|:--|:--|
|
||||
| `video_factory.py` | 641 | 5 种生产模式（run_oral/beat/digital_human/hybrid/**run_story**） | 🟡 拆成能力 + 保留为快速入口 |
|
||||
| `workflows.py`（Dashboard） | 599 | 流程模板（6 个）+ 节点定义（15 种） | ✅ 定义齐，🟡 **执行器空转需补** |
|
||||
| `demo_full_pipeline.py` | 256 | 端到端演示 | ✅ 参考用 |
|
||||
| `story_director/` | 1443 | 导演（legacy） | 🟡 包装为导演适配器 |
|
||||
| 🆕 统一分镜 Schema | — | 中枢契约 | 🆕 待建（S2） |
|
||||
| 🆕 导演适配器框架 | — | 替换点① | 🆕 待建（S2） |
|
||||
| 🆕 执行器（真跑） | — | L2 执行层 | 🆕 待建（S3） |
|
||||
|
||||
**L5 接入层 / 支撑**
|
||||
|
||||
| 现有资产 | 规模 | 框架位置 |
|
||||
|:--|:--|:--|
|
||||
| `main.py` | 931 | ✅ CLI 原子命令（调试入口，保留） |
|
||||
| Dashboard `plugins/ave.py` | 243 | ✅ 能力目录插件（🟡 数据源改读注册表） |
|
||||
| Dashboard `app.py` | — | ✅ sys.path 集成 + `/api/capabilities` |
|
||||
| Dashboard `workflows.py` | 599 | ✅ 模板/节点接口（`/api/workflow/*`） |
|
||||
| `lib/config.py` / `cost_tracker.py` / `dashboard.py` / `logger.py` | 921 | ✅ 配置 / 成本记账 / 生产埋点 / 日志 |
|
||||
| `09_ave/config.yaml` | — | ✅ 配置（kling/aliyun/volcano/llm/pexels…） |
|
||||
| `AVE_ARCHITECTURE_PLAN.md` | 480 | ✅ 既有架构规划（6 条生产路径 + 原子能力表） |
|
||||
|
||||
### A.2 前端资产（`10_dashboard/frontend/src/`）
|
||||
|
||||
| 现有视图 | 行数 | 框架位置 | 状态 |
|
||||
|:--|:--|:--|:--|
|
||||
| `workflow.js` | 485 | ⚙️编排 → 工作流 | ✅ 画布；🟡 待接真执行 + 节点配置面板 |
|
||||
| `capabilities.js` | 80 | 🔧配置 → 能力目录 | ✅ 只读总览 |
|
||||
| `person-swap.js` | 269 | 📦资产 → 人物置换 | ✅ |
|
||||
| `characters.js` | 138 | 📦资产 → 角色库 | ✅ |
|
||||
| `char-gen.js` | 389 | 📦资产 → 角色生成器 | ✅ |
|
||||
| `productions.js` | 88 | ⚙️编排 → 生产记录 | ✅ |
|
||||
| `assets.js` | 57 | 📦资产 → 素材库 | 🟡 待扩展 |
|
||||
| `costs.js` | 61 | ⚙️编排 → 费用分析 | ✅ |
|
||||
| `ave-script.js` 等 4 个 | 各 9 | — | ⚪ **空壳**（择机激活为导演创作页或删除） |
|
||||
| 🆕 `ave-director.js` | — | 🎞️创作 → 导演创作 | 🆕 待建（S2） |
|
||||
| 🆕 `ave-capabilities.js`（管理） | — | ⚙️编排 → 能力库 | 🆕 待建（S1） |
|
||||
|
||||
### A.3 盘点发现的问题
|
||||
|
||||
1. **编号目录 `01-07` 全是空壳**（每个 `__init__.py` 0 字节）—— 早期分层规划残留，**实现都在无编号目录**里（`director_parser/` `composer/` `bgm_generator/` …）
|
||||
→ **建议**：归档到 `90_archive/`，避免后续误导（框架里的 `capabilities/` `directors/` 等新目录才是正式分层）
|
||||
2. **命名不统一**：`character_sheet.py` / `character_portrait.py` 在根级，`character_registry/` `character_generator/` 在目录
|
||||
→ 按框架收进 `capabilities/` `assets/` 时统一
|
||||
3. **资产比预想多**：`audio_line`(3530) + `character_*` 系(4642) + `asset_manager`(1167) 都是成熟资产，**不用重写，只需包装**
|
||||
4. **缺口集中**：去 AI 化、统一 Schema、导演可切换、执行器、场景/产品资产 —— 正好是 S1~S4 的内容
|
||||
|
||||
### A.4 结论：现有资产覆盖率
|
||||
|
||||
| 层 | 覆盖度 | 说明 |
|
||||
|:--|:--|:--|
|
||||
| L1 资产层 | **角色 100%** / 场景产品 0% | 角色系资产最完整 |
|
||||
| L3 能力层 | **约 80%** | 音频/视频/基础视觉齐；缺去AI化、ComfyUI、特效、3D |
|
||||
| L4 编排层 | **定义 100% / 执行 0%** | 模板与节点齐，执行器空转 |
|
||||
| L5 接入层 | **60%** | CLI + 插件齐；前端缺导演创作/能力库页 |
|
||||
| 统一契约 | **0%** | 分镜 Schema 与导演适配器待建 |
|
||||
|
||||
**一句话**：零件大多已有（约 19,000 行可复用），缺的是**统一契约（Schema）+ 通电（执行器）+ 几个关键缺口（去AI化/资产扩展）** —— 这正是 S1~S5 要补的，不需要推倒重来。
|
||||
|
||||
---
|
||||
|
||||
## 附录 B｜方法论整合（从成熟系统抓取，2026-10-01）
|
||||
|
||||
> 原则：**"市面上已有人把整套系统做出来了，我们抓下来做成自己的风格"** —— 不重造轮子，抓方法论、按我们的架构增量接入。
|
||||
|
||||
### B.1 抓取清单（ai-film-skills，Apache-2.0）
|
||||
|
||||
**位置**：`05_tools/09_ave/skills/ai-film-skills/`
|
||||
|
||||
| 类别 | 内容 | 说明 |
|
||||
|:--|:--|:--|
|
||||
| 技能包 | **21 个**（18 常规 + 3 实验） | 每包含 `SKILL.md` 运行正文 |
|
||||
| 方法论 | **150 个 `references/`**（1.4MB） | 执行细节（编译器/引擎/协议/验收/诊断） |
|
||||
|
||||
**核心包**：
|
||||
- `ai-storyboard-director`（v5.2 分镜，5.7.1）— **已接入为默认导演**
|
||||
- `produce-ai-video`（实际生产与验收）— **六模块提示词编译器 + 三级交付状态已接入**
|
||||
- `ai-short-drama-production`（短剧控制：五列分镜 + 六模块母提示词）
|
||||
- `character-asset` / `scene-asset` / `prop-asset`（人物/场景/道具资产规范）— **待接资产库**
|
||||
- `director-agent`（编剧与导演）
|
||||
- 7 个题材风格包（武侠/战争/赛博朋克/恐怖/黑色/爱情/奇幻/史诗）
|
||||
|
||||
### B.2 已整合（已落地在代码里，可验证）
|
||||
|
||||
| 方法论 | 落地位置 | 效果 |
|
||||
|:--|:--|:--|
|
||||
| **六模块母提示词**<br>（生成任务/主体/场景/情绪/风格/分段脚本） | `composer/pipeline.py::build_shot_prompt` | 提示词 470~530 字、结构完整、**含负向约束**（不要 AI 塑料质感/字幕水印/快速变焦） |
|
||||
| **三级交付状态**<br>（合格成片/候选成片/未完成） | `schemas.py::Storyboard.delivery_status` + `pipeline.delivery_status()` + 前端徽章 + `POST .../review` 确认接口 | **诚实标注**：未经完整播放审查一律标「候选成片」 |
|
||||
| **v5.2 分镜方法论** | `directors/storyboard_v52.py`（技能文档作系统提示词） | 分镜质量显著优于 legacy（场面调度/连续性/按内容选景别） |
|
||||
|
||||
### B.3 待整合（接入点已明确，按需做）
|
||||
|
||||
| 方法论 | 接入点 | 预期收益 |
|
||||
|:--|:--|:--|
|
||||
| **设计记忆协议**（`design-memory-protocol.md`） | `Shot` 加 `enter_state`/`exit_state`；`Storyboard` 加 `locked_facts`（用户锁定）/`source_hash`（源剧本校验） | 跨镜头状态传递 + **用户改过的镜头不被重生成覆盖** |
|
||||
| **十二项完成门** | 导演 prompt 强化 + 可选校验器（时间轴闭合/轴线一致/台词时长/道具追溯） | 分镜质量自检，减少"术语轮换"式假分镜 |
|
||||
| **资产规范**（人物/场景/道具） | 资产库 UI + `GlobalAnchors`（多角度参考图 + 必保特征） | 角色一致性（换场景不变脸） |
|
||||
| **五列人读分镜** | 分镜表 UI 列：时间 / 景别机位 / 摄影机 / 画面与动作 / 台词声音 | 更专业的编辑视图（当前是单列卡片） |
|
||||
| **验收细则**（`qualified-video-acceptance.md`） | 交付前的检查清单（连续性/瑕疵/声音） | 合格成片判定有据可依 |
|
||||
|
||||
### B.4 整合原则
|
||||
|
||||
1. **不推翻现有设计**：统一分镜 Schema 是中枢，方法论以"字段 / 提示词 / 校验器"形式**增量**接入
|
||||
2. **能跑通优先**：先保证端到端可用（✅ 已完成），再补精细化
|
||||
3. **可切换**：所有接入点设计为可选（v5.2 与 legacy 并存、六模块与简洁模式并存）
|
||||
4. **不动别人的代码**：技能包原样存放 `skills/`，通过适配器/编译器接入，便于后续升级技能版本
|
||||
Reference in New Issue
Block a user