上周有个做企业文档中台的朋友问我，有没有办法让编码代理直接改客户发来的 Word 合同，而不是先转成 Markdown、改完再转回去。我当时给的建议是先别急着上，因为格式回写这一步坑最多。后来翻到 genspark-ai/genoffice 这个项目，发现它的思路正好绕开了这个坑——不转换，直接操作原生格式。它的中文翻译版这两天刚发布，仓库在 yangshun2005/genoffice-cn，我把 README 从头到尾读了一遍，顺手整理成这篇上手记录。
先说清楚这个中文版是什么。它不是 fork 出来改代码的分支，而是原项目文档的中文翻译版本，翻译日期标注为 2026-10-14，原项目 genspark-ai/genoffice 目前 9580 stars，主语言 TypeScript，Apache-2.0 许可证。中文版仓库额外加了一段「中文快速上手」的补充导读，这部分不是原文内容，是给中文用户省事的。需要提醒一句：翻译工作已经完成，但项目本身的 QA 还没有完全走完流程，所以遇到措辞别扭的地方直接提 Issue 或 PR 就行。
它到底解决什么问题
一句话概括：GenOffice 是 Microsoft Office 的免费开源替代品，支持 macOS、Windows 和 Linux，能打开并保存原生.docx、.xlsx、.pptx文件，也能编辑 PDF、Markdown 和 HTML，每个文档旁边挂一个 AI 智能体。
但真正让我觉得值得写一篇的，是它处理格式的方式。README 里的原话是「只重写你编辑的部分，文件中其余内容逐字节保留」。这句话的分量做过文档处理的人都懂。传统做法是把 docx 解析成中间结构，改完再序列化回去，这个过程里样式、批注、页眉页脚、嵌入对象经常莫名其妙丢一批。genoffice 选择只动被改的字节区间，剩下的原样保留，所以文件回到 Word、Excel、PowerPoint 里还能正常打开。这是个工程上的取舍，不是营销话术。
另外两个设计我觉得对落地影响很大：
一是可审查。AI 的编辑以修订和差异形式呈现，支持一键回滚。电子表格里用的是实时公式而不是粘贴进去的数值，幻灯片和页面在画布上生成，保持可编辑状态。这几点决定了它能不能进真实业务流程——如果 AI 改完你看不出改了哪儿，那在企业场景里基本没法用。
二是本地优先。文件打开、编辑、保存、转换全在本机完成，PDF 转 Word/Excel/PowerPoint、Markdown 转 Word、HTML 转 Word 都是本地跑的。只有 AI 调用会离开你的机器，发给你自己选的提供商。这个边界划得比较清楚。
装之前先确认这几件事
系统支持方面，macOS 覆盖 Apple Silicon 和 Intel，Windows 覆盖 x64 和 Arm，Linux 提供 deb、rpm、AppImage 三种包。硬件要求原文没写，我不瞎猜。
如果你只想用，去 Releases 页面按平台下载安装包就行，安装步骤原文没有细说，按常规桌面应用处理。项目当前版本号是 0.1.0。
如果你要从源码构建，门槛在package.json的 engines 字段里写死了：Node.js 需要>=22.12.0，npm 需要>=10。这两个版本号别凑合，尤其是 Node，22.12 以下的版本可能在依赖安装阶段就出问题。还有个容易忽略的点：postinstall会执行install-electron，也就是说npm install阶段会去拉 Electron，网络不好的话这一步会卡很久，建议提前把镜像源配好再动手。
README 里没有给出完整的构建和启动命令，只列了package.json的 scripts，所以从源码跑这条路我目前没法给出一套验证过的完整流程，这块得自己看 scripts 摸索。
AI 能力怎么接
这是绕不开的一步。两条路：
第一条，登录 Genspark，直接免密钥用。
第二条，自带密钥。支持的范围挺广，Claude、OpenAI、Gemini、DeepSeek、Kimi、GLM、Qwen、Doubao、MiniMax、Grok、Mistral、OpenRouter、Requesty、Opper、Cheaper Inference、Atlas Cloud 都在列表里，另外任何 OpenAI 兼容端点都能接，包括你自己搭的本地服务器。
我的建议是，如果你在公司内网做试点，优先走第二条路里的「OpenAI 兼容端点 + 本地服务器」这个组合。原因不是技术上的，是合规上的——文档内容属于敏感数据，AI 请求发到哪个域名，这件事在很多公司是要过安全评审的。本地端点至少让数据流向可控。
CLI 和 agent skill 才是重点
README 里有一句我反复看了几遍：应用自带genoffice命令行，以及面向 Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilot、OpenCode、Windsurf 的技能，让编码智能体不用打开窗口就能在你机器上创建、转换、读取和编辑真实的 Office 文件。
官方那句英文描述说得更直白：genofficeCLI 和 agent skill 的存在，就是为了让 Claude Code、Codex、Cursor 能在本地创建和编辑真正的 .docx/.xlsx/.pptx 文件。
这解决的是一个很具体的场景。以前让编码代理处理 Office 文件，常见做法是装个 Python 库写脚本，或者转成纯文本处理完再想办法拼回去。前者对代理来说调用链太长，后者格式必丢。现在如果 skill 能直接调起来，代理的操作路径就短了很多。
不过要如实说：CLI 和 skill 的具体用法，原文没有展开说明，我手上也没有可验证的调用示例，所以这块我不编。想用的话得去仓库里翻。
主屏幕那两个功能容易被忽略
README 里提到主屏幕有两个能力，我觉得比想象中实用。
一个是按内容查找文件。主屏幕通过本地 SQLite 索引，搜索.docx、.xlsx、.pptx、PDF、Markdown 和 HTML 的文件名、文件夹和全文，明确支持中日韩文字。对中文用户来说这个「支持中日韩」不是废话，全文检索里中文分词做不好是很常见的问题。另外可选地，排名靠前的结果会由 TypeSafe Jev（System One 判断模型）重新排序，让更能回答你问题的文件排前面。
另一个是向文件提问。收藏一组文档之后，主屏幕的 Ask AI 可以跨文档回答问题，每个论断都标注来源文件，方便你打开核实。带来源这一点很关键，没有来源的跨文档问答在企业里基本没法采信。
我的选型判断
如果你在评估要不要把这类工具引到团队里，我给几个顺序上的建议。
先评估格式保真度，再评估 AI 能力。理由很简单，AI 能力可以换供应商，格式丢了就是丢了。genoffice 的字节级保留思路是对的，但具体到你们业务里那些带复杂样式的模板，还是得拿真实文件测一遍。
先跑 CLI 和 skill，再考虑桌面端铺开。CLI 那条路的验证成本低，出了问题影响面小，而且能直接嵌进现有的自动化流程。桌面端涉及全员安装、密钥分发、权限管理，是另一个量级的事。
密钥策略提前定，别等用起来再补。是统一走公司网关，还是每人自备，这个决定会影响后面的审计和成本核算。
最后说边界。genoffice 的定位是替代品，不是兼容层，它不承诺覆盖 Office 的全部特性。你拿它处理常规文档没问题，但如果业务里重度依赖宏、复杂数据透视或者特定插件，先小范围验证再谈推广。这个判断不是针对 genoffice，是所有开源 Office 替代方案共同的边界。
中文版刚发布，翻译已经完成，但 QA 流程还没完全走完，仓库 stars 目前是 0，热度什么的谈不上。我的建议是把它当成一个值得放进候选清单的项目来看，先自己跑一遍 CLI，感受一下字节级保留到底靠不靠谱，再决定要不要往团队里推。先说一个我自己的观察。过去一年我帮几支团队看AI agent落地，卡点很少出现在"模型够不够聪明"上，反而集中在同一件事：会话不可续。你和agent聊了四十分钟，把需求拆完、把上下文喂饱，关掉窗口，第二天想接着干，得从头再讲一遍。agent没有记忆，没有排期，没有检查点，它只是一次对话。
KiroCrew这个项目想解决的正是这件事。原项目kirodotdev/KiroCrew目前4400 stars，主语言Python，Apache-2.0许可。它的官方一句话描述是：A persistent workspace for development work that self-improves and continues beyond one session——一个能自我改进、并跨越单个会话持续运行的开发工作区。
现在有了中文翻译版：https://github.com/yangshun2005/KiroCrew-cn 。翻译日期是2026-10-14，翻译已完成。需要说清楚的是，中文版今天刚发布，stars还是0，它不是另一个项目，就是把原项目文档翻译过来，让中文用户少一道语言门槛。
它到底"持久"在哪里
README里有一段话我觉得是理解这个项目的钥匙：多数AI agent会话在关闭聊天后就结束了，而KiroCrew的会话、记忆、调度和任务检查点能在Gateway重启后保留。计划任务和无人值守的多步任务可以持续运行。
拆开看是四个东西：会话、记忆、调度、任务检查点。它们的共同前提是"能扛住Gateway重启"。这一点在企业场景里比想象中重要——不是每个人都能接受一个跑长任务的agent，进程一挂，中间状态全丢。
交互入口它给了好几条：桌面应用、Web仪表盘、CLI，另外还能通过Slack、Discord这类消息渠道继续同一份工作。这个设计思路我比较认可，agent不该被绑死在一个聊天窗口里，你在工位上用仪表盘，出门用手机上的Slack接着推，指向的是同一份工作状态。
再往上一层是KiroCrew Apps，README的说法是把这种体验定制到特定工作场景，把专用界面和智能体、技能、计划、集成、后端服务组合起来。这块我还没实际跑过定制流程，暂时不下结论。
装之前必须先搞明白的前置条件
这是最容易踩的坑，我放在最前面说。
KiroCrew的默认agent运行在kiro-cli之上，而kiro-cli需要你单独安装并登录。首次启动时它会检查这个前置条件，缺失的话会链接到官方安装指南。也就是说，它不是那种装完就能用的单体工具，有一条外部依赖链。
README里没有给出kiro-cli的明确安装命令，只说明要参考正文。所以我的建议是：先把kiro-cli装好、跑通kiro-cli login，再去装KiroCrew本体，顺序反了会浪费一轮排查时间。
环境要求我列一下，都是README原文：
- 操作系统：macOS、Linux、Windows都支持，但Windows需要走原生源码安装，参考Windows指南
- Python：3.12+，pyproject.toml里声明的是
requires-python = ">=3.12"，支持CPython 3.12–3.13 - Node.js：源码构建需要22.12+，推荐24 LTS，还要npm
- 默认agent依赖：
kiro-cli，需要在Gateway主机上安装并运行kiro-cli login - 硬件架构：macOS覆盖x86_64和arm64，Linux覆盖x86_64和aarch64
- Docker方式：用GHCR上的公开多架构镜像
ghcr.io/kirodotdev/kirocrew:stable
另外提醒一句，国内网络环境可能需要换镜像源或者加速下载。README里没有给具体的镜像源配置，只说参考install guide，这一块得自己想办法。
一行命令跑起来
最短路径就三步。
第一步，装kiro-cli并登录。原文没给命令，按官方安装指南走。
第二步，一行命令装Stable版，不需要克隆仓库，也不需要构建前端：
curl-fsSLhttps://download.crew.kiro.dev/cli.sh|sh第三步，打开http://localhost:5476。
如果你需要固定版本，加--version。这里有个细节值得注意：最小可固定版本是0.1.2，因为0.1.0和0.1.1早于manifest签名机制，没有可解析的签名manifest。比如固定到0.6.0：
curl-fsSLhttps://download.crew.kiro.dev/cli.sh|sh-s----version0.6.0生产环境我倾向于固定版本，不跟着Stable漂。这个习惯和agent本身无关，是运维常识。
源码构建的路子
如果你要改代码或者做二次开发，README给的步骤是：
gitclone<仓库地址>cdKiroCrewmakebuildsource.venv/bin/activate kirocrew setup kirocrew doctor kirocrew gateway这里有两个坑。
一是前端要单独构建。前端用npm/Vite在website/目录下构建，产物需要staged到src/kiro_crew/static/dist之后再打包。不是make build一把梭就完事，前端产物没staged过去，跑起来会缺页面。
二是install.sh默认只装预编译wheel。遇到没有预编译wheel的依赖，它会直接拒绝构建，不会自动降级去源码编译。如果你确实需要允许源码编译，得设置KIROCREW_ALLOW_SOURCE_BUILDS=1，同时机器上要有C工具链和-dev头文件。这个设计我认为是对的，默认不编译能保证安装可复现，但第一次遇到报错的人容易懵。
kirocrew doctor这个命令值得单独说一句。它出现在构建流程里，作用类似环境自检。装完先跑doctor再起gateway，能省掉不少"起来了但不对劲"的时间。
发布渠道怎么选
Stable是默认渠道，Insider跟候选发布版本，Nightly跟main分支。README提到发布运行手册里有触发条件、版本形态、晋升行为、发布节奏和更新通道语义。
我的建议很直接：团队用Stable，个人折腾可以用Insider，Nightly只适合你想跟最新改动或者准备提PR的情况。理由不是稳定性玄学，而是Nightly跟main意味着你遇到问题时，别人很难复现你的版本。
中文版真正省掉的是什么
说回中文版本身。
它做的事情不复杂：把原项目README翻译成中文，保留README_en.md作为对照，翻译日期2026-10-14。顶部还加了一段"中文快速上手"，明确标注为非原文内容，是面向中文用户的补充导读，目的是让你不用读完整篇README就能先把项目跑起来。
这个补充导读的价值，恰恰在于它把"这是什么/解决什么问题"“最短路径”“环境要求”“常见坑"四件事前置了。原README信息很全，但对第一次接触的人，得先读一大段才能定位到"我该敲哪条命令”。
翻译本身也有取舍。README里写明了：如有翻译不准确之处，欢迎提Issue或PR。这是负责任的做法，翻译版最怕的就是把原文的技术细节"意译"没了。我对照着看了几处关键描述，比如Gateway重启后保留会话、记忆、调度和检查点这段，中文版是贴着原文走的，没有加戏。
需要克制地说一句：中文版刚发布，翻译已完成，但还没有经过大规模使用检验。术语选择是否顺手、后续原项目更新能不能跟上，这两点我暂时给不出结论，样本太少。
选型时我会怎么看这类项目
不针对KiroCrew，说一套我自己在用的判断顺序，供参考。
第一看持久化边界在哪。是进程内持久，还是能扛进程重启，还是能扛机器重启。这三个层级对应的运维成本差一个量级。KiroCrew README明确说的是能扛Gateway重启，这个层级对多数内部工具够用，但你要清楚它不等于分布式高可用。
第二看外部依赖链有多长。KiroCrew依赖kiro-cli，这就意味着你的部署清单里多了一个需要独立安装、独立登录、独立升级的组件。依赖链越长，权限和凭证管理越要提前设计，尤其是团队共用一台Gateway主机的时候。
第三看入口数量。桌面、Web、CLI、Slack、Discord，入口多对使用者是好事，对管理员是负担——每个入口都是一条访问路径。落地时我一般建议先只开一个入口，跑顺了再加。
第四看无人值守任务的可观测性。README提到计划任务和无人值守的多步任务可以持续运行，心跳机制持续监控系统直到有需要关注的事项。这类能力落地时，重点不是"能不能跑"，而是"跑歪了你怎么知道"。这块的具体实现我还没深入，先留个问号。
第五才是文档语言。中文文档能显著降低上手成本，但它排在后面，因为前四条决定项目能不能用，第五条只决定用得顺不顺。KiroCrew中文版解决的正是第五条，而它顺手把第一条到第四条的关键信息也前置了，这是我觉得它比单纯翻译更有用的地方。
落地顺序建议
如果你打算在团队里试，我给一个顺序。
先在单机上跑通一行安装加kiro-cli login，确认http://localhost:5476能打开。这一步只验证环境，不碰业务。
然后跑一个短的多步任务，故意把Gateway重启一次，看会话和检查点是不是真的还在。这是验证"持久化"这个核心卖点最直接的方式，比读十遍文档有用。
再往后接一个消息渠道，比如Slack，验证跨入口能不能续上同一份工作。
最后才考虑KiroCrew Apps那层定制，以及把计划任务交给它无人值守跑。顺序不要倒过来，前面没验证就上无人值守，出问题很难定位。
至于Docker方式，ghcr.io/kirodotdev/kirocrew:stable是公开多架构镜像，适合常开服务器场景。但镜像方式同样绕不开kiro-cli的前置依赖，别以为容器化就把依赖问题解决了。
收个尾
KiroCrew这个项目值得看的地方，是它把"agent会话"当成一个有生命周期的对象来设计，而不是一次性的问答。会话、记忆、调度、检查点，加上扛Gateway重启，这套组合指向的是能长期驻留的开发工作区。
中文版把这道语言门槛拿掉了，README翻译加中文快速上手导读，让你能更快走到"跑起来"那一步。它今天刚发布，stars还是0，翻译已完成但使用验证还早，这个预期要摆正。
我的建议是：把它当成一个值得花两小时试一下的项目，按上面的顺序走一遍，重点验证重启后状态还在不在。这一条过了，再谈别的。
