YnuoAgent（依诺）：一个 npm 包，把你自己的 AI 研发平台跑起来
一个 MIT 开源、单机可跑、
npm install -g就能用的 AI 研发平台。不是插件，不是 SaaS，装完就在你本机http://localhost:2609。
两行命令，把一整套 AI 研发平台装进你自己的电脑。
bash
npm install -g @ynuo/ai@0.3.10
ynuo daemon # 然后打开 http://localhost:2609我第一次拿它跑完一个真实任务，第一反应不是「真快」，而是：「原来它刚才在干什么，我现在能看见。」
如果你也受够了「AI 写完、你不敢合」的循环------三分钟，装上试试。
一、先说一个很具体的困惑
这两年 AI 编码工具换了一茬又一茬，但我一直有个困惑：工具越来越强，我却越来越不知道"这个项目是怎么长出来的"。
- 代码是 AI 写的，但需求散在聊天记录里；
- 方案是 AI 想的，但评审只发生在它自己的脑子里；
- 测试是 AI 跑的，但"通过"这两个字没有凭据；
- 换个会话，昨天的分析结论、昨天定下的规矩，全部归零。
单点的编码助手解决的是"这一行怎么写"，解决不了"这个项目怎么被组织出来"。而后者，恰恰是研发管理真正在做的事。
所以有了 YnuoAgent（依诺） ：它把 AI Agent 放进真实的研发管理体系里------企业 → 项目 → 任务 → 文档 → 代码仓库，让每一次 AI 会话都绑在具体任务上，产物落在具体文档里，过程写进事件流里。
一句话：它不只是帮你写代码，它把写代码这件事的过程留下来了。
二、它到底是什么
三个事实，先把定位说清楚：
| 维度 | 说明 |
|---|---|
| 形态 | 一个 npm 包 @ynuo/ai，装完起一个本地服务 + 内置 Web IDE |
| 跨平台 | Windows x64 / Linux x64 / macOS Apple Silicon / macOS Intel，四平台 launcher 自动匹配 |
| 数据 | 全在本地（SQLite + 工作区目录），不上传云端，升级不丢数据 |
启动以后浏览器打开 http://localhost:2609，你会看到两个工作台：
- 创作（Creation） ：用自然语言驱动 Agent 写文档、做原型、按五段状态机产出一集漫剧的资产包（详见第六节）；
- 研发（R&D）：以项目为单位，任务 → 会话 → 代码仓库，AI 在流程里干活。
两个工作台共享同一个 Agent 运行时、同一套技能、同一份模型配置。区别只是"装配了什么上下文"。
三、一分钟跑起来
环境只有一个要求：Node.js >= 22。
bash
# 1. 全局安装（自动带上当前平台的守护启动器）
npm install -g @ynuo/ai
# 2. 启动
ynuo daemon # 后台守护，崩溃自动重启
# 或
ynuo # 前台模式，关终端即停
# 3. 打开浏览器
# http://localhost:2609当前最新发布是
0.3.10）。要装这一版请显式指定：npm install -g @ynuo/ai@0.3.10；不加版本号的npm install -g @ynuo/ai` 装的是稳定版线上 tag。
首次启动会进引导流程：建管理员账号 → 配模型 Provider → 建项目 → 开始会话。
其他常用命令：
bash
ynuo doctor # 系统诊断：Node 版本 / SQLite / 工作空间 / 数据库 / bcrypt
ynuo update # 查版本 → 确认 → 升级主包+平台包 → 自动重启守护
ynuo stop # 优雅停止守护进程
ynuo check # 只看有没有新版本端口默认 2609，改
~/.ynuo/config.toml即可。崩溃日志在~/.ynuo/logs/crash.log。
四、五个核心能力，讲人话版
1）事件溯源：把"AI 怎么想的"存下来
整个平台的底座不是"聊天记录"，是事件流。
会话里发生的每一件事------用户消息、模型调用、工具调用、工具结果、状态变更------都是一条带序号和时间戳的不可变事件，全量落进 SQLite。
这带来三个直接好处：
- 可回放：任意一次会话，可以按时间顺序重放，看到 AI 在第几步做了什么判断；
- 可快照：按固定间隔持久化 checkpoint，状态能恢复到某个事件点；
- 可隔离：需要"另一个视角"时，fork 一个空历史的隔离子会话------0.3.9 的 AI 方案预审就是这么实现的（评审线程和编码会话零共享上下文，避免自己批自己）。
顺带说，这也是为什么它能做"过程透明"：不是前端画得好看，是后端真的把过程存下来了。
2）技能体系：研发流程可以被写成文件
内置 10 个技能，覆盖研发全流程：
| 技能 | 干什么 |
|---|---|
lead |
研发工作流总管，会话开始自动加载，负责阶段与能力路由 |
analyze |
任务分析与需求澄清：扫现状、展开问题树、排序候选路径、对齐验收口径 |
design |
设计与规划：架构/模块/接口/表结构、原型图、实现步骤与风险 |
implement |
代码实现与 UI 生成：按设计产出代码并验证可运行 |
review |
代码审查与测试：分级问题清单 + 用例设计 + 真实执行收集证据 |
test |
测试验证：正常/边界/异常/状态变化四维用例，报告必须来自真实执行 |
debug |
根因调试：复现 → 证据 → 假设 → 最小修复 → 回归 |
refactor |
安全重构：识别坏味道、Wave 计划、小步改、持续验证 |
content-creator |
创作项目专用：文档写作、文案、资料整理 |
evant |
漫剧创作工作流：立项 → 剧本 → 角色资产 → 风格 → 分镜 → 交付 |
重点不是"有 10 个"，而是技能就是 Markdown 文件 ：往项目 .ynuo/skills/ 或全局 ~/.ynuo/skills/ 里丢一个带 frontmatter 的 SKILL.md，重启即生效。
markdown
---
name: our-api-convention
description: 公司 API 规范校验。写接口前必须检查路由命名、错误码、鉴权中间件。
---
# API 规范校验
1. 路由统一 `<模块>/<资源>` 小写下划线，禁止驼峰；
2. 业务错误码从 10000 起，禁止直接返回 500；
3. 所有写接口必须挂 auth 中间件，并在返回体带 traceId。团队的规范不用再写成 Wiki 文章等人去读------写成技能，让 AI 每次动手前先读一遍。
3）多模型：不绑死任何一家
统一 Provider 抽象，配置 model 即可切换：
- OpenAI 兼容协议（含各类兼容网关，国内大部分厂商都走这套）
- Anthropic
- 本地模型（Ollama 等）
支持 Provider 池、请求缓存与熔断降级：某个渠道挂了自动切下一个，长任务不会因为一次 429 直接崩。
模型标识按「渠道 + 模型 」区分------同一个 deepseek-* 你接了三家渠道，用量、选择、统计互不干扰。
4）工具与 MCP：能干活，也能扩展
内置工具集（开箱即用，无需配置）：
text
bash 命令执行（沙箱裁决）
filesystem 文件读写
git 版本操作
search 代码库检索
web / web-search 网页抓取与联网搜索
knowledge-search 知识库检索（RAG）
dev-rules 项目规约按需读取
repo-touch 仓库触点探测
todo-write 任务清单
subagent-spawn 子 Agent 派发
ask-user 阻塞式追问
offices-read 文档读取工具按 DAG 拓扑排序并行执行，单个工具 30s 超时兜底------不是串行一个个等。
需要更多能力？接 MCP（Model Context Protocol）。在项目配置里声明 MCP server，即可把外部工具（数据库、私有 API、公司内部系统）挂到 Agent 上。
5）沙箱与审批：AI 的手，得有人管
所有文件读写、命令执行都过统一沙箱裁决，三档权限：
| 档位 | 读 | 写 | 删 |
|---|---|---|---|
readonly |
✅ | ❌ | ❌ |
project（默认） |
✅ | ✅ 仅项目内 | ⚠️ 需审批 |
global |
✅ | ✅ | ✅ |
危险操作（项目内删除、越界写入）走审批流，全程留痕。这是"给 AI 权限"的正确姿势：不是信任它，而是把权限做成可调的档位。
五、两条使用路径，对应两类人
路径 A：一个人用 ------ 创作工作台
建一个「创作项目」，剩下交给会话：
- 写技术方案 / 产品文档 / 汇报材料；
- 从需求到原型页面；
- 漫剧创作：立项定调 → 剧本 → 角色资产 → 风格 → 分镜 → 交付（内置
evant工作流，状态机推进，媒体走四个创作工具；见下一节展开）
路径 B：一个团队用 ------ 研发工作台
这里是它和"单点编码助手"最不一样的地方。研发工作台的组织方式是：
text
企业 → 项目 → 任务 → 会话 / 文档 / 代码仓库- 每个任务有自己的类型、级别、状态；
- 每个会话绑定在具体任务上，产物进任务；
- 代码仓库登记在项目里，AI 直接读仓库、出分析、写规约；
- 0.3.9 起，任务还要走流程门禁 ：调研 → 实施方案 → 方案评审 → 编码 → 测试 → 交付，每道门做状态校验，评审门必须人工批准才能写代码，跳过要留痕（
dev_bypass=1）。
于是"AI 做了什么"这件事，有了可查询的载体：任务、文档、事件流、规约文件。
六、漫剧创作：从「一句话」到一集片子的资产包
上一节说创作工作台能做漫剧，这里单独展开------因为它是这套平台里最不像"聊天"的部分。
先说清楚它不是什么：它不是一个"文生视频"按钮。 它是一个被状态机约束的创作生产线。
为什么需要生产线？因为 AI 做长内容最常见的失败不是"生成不出来"，而是越做越飘：第 5 镜的角色换了张脸，第 8 镜的色调和开头不是同一部片子，第 12 镜的房子结构变了。这不是模型能力问题，是上下文和资产没有被管起来的问题。状态机 + 资产账本，就是把"一致性"从祈祷变成流程里的强制项。
1）三种开工方式，都从「00 项目简报」进
| 模式 | 你提供什么 | AI 做什么 |
|---|---|---|
| A 自写 | 一句创意、一段梗概 | 陪你定题材、集数、画幅（9:16 / 16:9）、目标平台，产出立项卡 |
| B 上传剧本 | 现成剧本 | 不代笔改剧情，直接分场、拆镜、配资产 |
| C 小说转 | 小说原文 | 抽取场景与人物，转成可分镜的剧本，且标注「原文明确 / 合理推断 / 创作建议」 |
模式 C 那条标注看着不起眼，但很关键：AI 的补充建议不会被写成剧本事实，你回头改稿知道自己改的是谁的判断。
2）五段状态机，每段都要你点头
text
00 项目简报 → 01 剧本 → 02 角色与资产 → 03 风格 → 04 分镜 → 交付- 进度真源是
.ynuo/evant/state.json，不是聊天记录。换会话、隔天回来，从上次那段接着做； - 每阶段结束必须你确认才推进，AI 不会自己一路跑到交付；
- 交付件一律落
docs/<阶段>/（如docs/剧本/剧本.md），治理区.ynuo/不进版本库------避免"交付件写在缓存区，一清理就没了"。
3）四个工具，是媒体生成的唯一出口
| 工具 | 干什么 |
|---|---|
creation_generate |
提交图像 / 视频 / 配音 / 音乐生成 |
creation_poll |
查进度、取真实 localPath |
creation_list_assets |
列资产 + 预算用量 |
creation_register_doc |
交付 .md 归档并登记 |
真正有意思的是幂等键 ：每次生成都带一个稳定镜号（S01、CHAR-主角）。同键重复提交会自动复用已有任务------网络抖了重试一次，不会重复计费，也不会生成两张脸不一样的图。
落盘规则也是硬的：docs/assets/<镜号>_<类型>_<序号>.<ext>，例如 S02_image_1.png、S02_video_1.mp4、S02_tts_1.mp3。按镜号字典序就是场景顺序，抽卡多版本按序号递增、不覆盖旧版。
4）花钱这件事，有三档刹车
| 策略 | 行为 |
|---|---|
confirm_each |
每次生成弹审批，你点「允许」才花钱（未知或缺失档位一律按这个最严的来） |
confirm_batch |
同一轮里的并行调用合成一批，一次审批统一提交 |
auto_budget |
设预算上限，用完直接拒绝------AI 只能如实告诉你用完了，不能绕过 |
资产账本 project_asset 记着每一笔，creation_list_assets 会返回预算余额。这一条的意义不只是省钱：它让 AI 的花费变成可核算的，而不是月底看账单猜哪来的。
5）一致性靠纪律，不靠模型自觉
工作流里写死了一条最高优先级规则：
视频必须以同镜号已就绪的关键帧图作首帧 （
imageUrl传该镜 image 资产的 id），禁止只给文字提示词就开视频。
理由很直白：只给提示词，角色形象和色调必然和关键帧脱钩。角色立绘统一走 CHAR-<名> 资产 + 角色圣经里的固定描述，换装、换脸、空间漂移都是红线，同理还有内容合规清单（不生成侵权形象、真实人物，真实地名公司须虚构化）。
6）接了哪些媒体平台
| 平台 | 能力 |
|---|---|
| 火山 · 即梦 | 图像 / 视频 / 音乐 |
| 火山 · 方舟 Ark | 图像 / 视频 |
| 火山 · 豆包 seed-tts | 配音（可开字级时间戳） |
| 阿里 · 百炼 | 视频；WebSocket 实时语音合成 |
| OpenAI 兼容网关（NewAPI / Navivo 等） | 图像 / 视频 / 配音 / 音乐 |
模型名一律取渠道里配的 params.model，换模型不改代码；渠道密钥在「系统设置 → 媒体模型」里配，接口返回一律掩码。
7）生成完还有两件事被自动做了
- 落盘和推进 ：
MediaPoller在服务端跨项目轮询生成中的资产，不需要你开着页面。关掉浏览器，任务照样跑完落盘； - 字幕：配音返回字级时间戳时按戳切 cue（中英支持），拿不到就整段均分降级，并在结果里标明走了哪条路径------字幕这事不糊弄。
8）创作页长什么样
右侧面板三个页签：素材库 （按 图像 / 视频 / 配音 / 音乐 分组，可预览、可重下）、阶段产物 （按阶段浏览 docs/）、最终产品 （按 EPxx 分集列成片 / 分镜 / 字幕）。生成中走 /progress 轮询 + 资产变更 SSE，审批走底部审批条（允许 / 拒绝）。
9）它现在还不是什么
- 不是「一键成片」 ：mp4 自动合成（ffmpeg 按镜拼接）还在 P2，当前交付的是资产包------分镜脚本、关键帧、视频片段、配音、字幕、交付清单，最后拼接你自己拿剪映或 ffmpeg 完成；
- 不做真人换脸 / 数字人克隆：合规红线明确不生成侵权形象与真实人物；
- 长剧集不是强项：单集几分钟的短剧、条漫剧、宣传片是甜区；几十集连续剧的跨集叙事一致性，仍需人来盯。
一句话收尾：它把"AI 帮我想分镜"升级成"AI 按生产线交付一集片子的资产，且每一步都留了凭据"。
七、给技术读者的几个实现细节
如果你关心它是怎么搭的，这几点可能有点意思：
1）六边形架构 + 事件溯源
领域逻辑与基础设施严格分离，@ynuo/core 是零依赖的纯类型内核，存储/遥测/沙箱/LLM 各自成包，依赖单向不可逆。
2）包结构
text
@ynuo/core 纯类型内核，零外部依赖
@ynuo/storage 事件存储 + SQLite（better-sqlite3 / knex）
@ynuo/telemetry OTel + pino + 审计
@ynuo/agent-sandbox 文件/进程沙箱 + Worker 池
@ynuo/agent-llm Provider 池 + 缓存 + 熔断
@ynuo/agent-harness 驾驭层：上下文 / 会话 / 工作流 / 工具 / 技能 / MCP
apps/server · apps/cli · apps/web3）分发方式：Claude Code 同款
@ynuo/ai 是主包，全部内部代码用 esbuild 内联成单文件 index.mjs（不含源码）；4 个平台 launcher 走 optionalDependencies，npm 按当前 os/cpu 只装匹配的那一个。5 个 tarball 加起来约 6.6MB。
4）守护进程是 Go 写的
launcher/ynuo(.exe) 以独立进程名运行主服务：崩溃自动重启（递增延迟）、PID 防重复、信号优雅关闭。所以 ynuo daemon 关了终端也不影响，ynuo update 升完自动重启加载新版。
5）单机、本地、SQLite
没有外部依赖，不需要 Docker、不需要数据库服务。数据都在工作区目录里（SQLite + 文件），升级只替换程序本身。
八、0.3.10 刚加的：研发透明化
最新版本把"过程可见"做深了一层，四条主线：
- 研发流程门禁：六段流程 + S/M/L 分级 + 评审门不可跳 + 跳过留痕；
- AI 方案预审 ：隔离子会话、只读核查、结论引到
file:line，人工结论优先； - 上下文白盒：token 水位环 + 15 个维度逐项可见（系统提示词/任务/代码仓库/知识库/记忆层规约/技能/工具/...）；
- 记忆层 devrules ：规约与经验落成文件（人工规则
docs/rules/+ 机器产物.ynuo/rules/），一仓一文件、按需读取、过期不注入。
（这块单独写了篇长文，这里不展开。）
九、诚实说边界：它不适合谁
写宣传最容易犯的错是把工具说成万能。说清楚不适用场景，反而省彼此时间：
- 只想在 IDE 里按 Tab 补全代码 ------ 你要的是编码插件，它是平台，杀鸡用牛刀；
- 团队完全没有研发流程意识 ------ 门禁、规约、留痕都需要有人认这些事，工具不会替你建立制度；
- 要求开箱即用、零配置 ------ 模型 Provider 得自己配 key，技能和规约要自己写，它是"可组装的平台"而不是"一键神器"；
- 需要多租户云服务 ------ 它定位是单机自托管（数据全在本地），不是 SaaS。
坦白讲，它还在早期：单机部署、生态刚起步，很多能力（比如跨仓规则自动提升）目前是刻意不做而不是忘了做。
十、它适合谁
- 独立开发者 / 小团队：想要一套自己的"AI 研发流水线"，又不愿意被 SaaS 绑定；
- 有规范诉求的技术负责人：希望 AI 写的东西能留痕、能评审、能追溯，而不是一堆无法验收的 commit；
- 对 Agent 工程感兴趣的人：事件溯源 + 沙箱 + 技能 + MCP 的组合，本身就是个不错的参考实现（MIT，代码全开）。
十一、开始用
bash
npm install -g @ynuo/ai@0.3.10
ynuo daemon
# open http://localhost:2609- Gitee 仓库：https://gitee.com/yanzkc/ynuo
- 作者：elcker（438586732@qq.com）
- License：MIT
- 当前版本：v0.3.10
如果你也在琢磨"怎么让 AI 写的东西可验证"，欢迎来仓库看看，或者直接留言聊聊你的做法。