我开源了一个让业务人员"对话改代码"的本地平台：Janus

我开源了一个让业务人员"对话改代码"的本地平台：Janus（Coding Agent Platform）

历时打磨的 side project 开源了：https://github.com/yonyong/Janus —— 一个本地部署的 Web 平台，业务人员凭一枚带令牌的分享链接，就能在沉浸式工作台里用对话召唤 Coding Agent 直接改项目代码，全程留痕、可回退、不需要 git。

技术栈：FastAPI + SQLite + React 18 + TypeScript + Ant Design 6 + SSE。如果这个思路对你有启发，欢迎去 GitHub 点个 Star ⭐，这是对独立开发者最大的鼓励。

一、为什么做这个东西

做过的朋友应该都遇到过这个场景：

业务同事跑过来说"帮我把报表里那个字段改一下"、"加个筛选条件"，改动其实很小，但流程很重——提需求、排期、拉分支、改代码、测试、合并、发布。改动只要十分钟，沟通来回要三天。

反过来，如果直接让业务人员碰代码仓库，那更是灾难：他们不会 git，不理解工程结构，一句"你直接帮我改了呗"背后是版本管理的无限风险。

核心矛盾是：业务人员有改需求的能力诉求，但缺少一个安全的、结构化的通道去触达代码。

市面上的 AI 编程工具（CLI 型的 agent）都假设使用者是开发者——要会开终端、会描述上下文、看得懂 diff。而需求方往往是完全不懂技术的人。

所以我的思路是：做一个中间层平台，把"对话改代码"包装成业务人员能用的产品形态，同时给开发者保留足够的管控能力。

这就是 Janus。Janus 是罗马神话里的双面神，一面看过去，一面看未来——这个平台的一面是业务人员的对话界面，另一面是真实的代码世界，中间由平台负责安全与秩序。

二、它长什么样、怎么用

整体流程设计成两种角色：

管理员（开发者）做的事，一次性配置：

  1. 把本地项目登记到平台（填一个磁盘绝对路径）；
  2. 签发一枚访问令牌，得到形如 http://host:8000/?token=xxx 的分享链接；
  3. 注册至少一个 Agent 引擎（内置 fake 联调引擎和 codebuddy CLI 适配器）。

业务人员做的事，日常使用：

  1. 打开分享链接（无需注册任何账号）；
  2. 新建需求，进入沉浸式工作台；
  3. 走四阶段工作流：需求澄清 → 用例配置 → 编码实现 → 归档验收；
  4. 全程只需要和右侧的 Coding Agent 对话。

工作台是三栏结构：左栏是随阶段切换的文件区（需求文档 / 用例 / 文件树与改动记录 / 归档汇总），右栏始终是 Agent 对话。Agent 每次运行，改动 diff 和测试结果实时流式回显（SSE），业务人员能直观看到"AI 这次到底改了什么"。

三、几个我认为最有含金量的设计

1. 快照式改动记录——不依赖 git 的可回退

这是整个平台我最满意的部分。业务人员改的需求，改坏了必须能一键还原，而且不能假设项目本身是 git 仓库。

方案：Agent 每次运行前后，平台各对工作区拍一张全量快照，逐文件 diff 后落库为"改动记录"。支持回退单个文件或整条记录，且回退动作本身也记一条 revert 记录——所以永远可以"反悔回退"。二进制和大文件只记指纹，界面明示不可回退，不给你"看起来能恢复其实恢复不了"的错觉。

# backend/snapshots.py：运行前后快照 → diff → 落库，全流程不碰 git

2. 令牌分享体系——无账号系统的鉴权

业务人员不该被要求注册账号。整个平台用令牌做鉴权：令牌支持备注、五种有效期、随时查看原文；后端按令牌白名单过滤可见项目，目录访问做 realpath 前缀校验防止越权。管理员口令和业务令牌走同一个登录弹框，但权限完全隔离。

3. 可插拔 Agent 引擎

平台不绑定任何具体 agent。定义了一个 CodingAgentProvider 协议 + 注册表，内置两个适配器：

  • fake：纯联调用，不走真模型；
  • codebuddy：子进程方式调用 CodeBuddy CLI。

接入自定义 CLI agent 的约定非常简单，实现同协议即可接入任意 CLI 型 agent：

  • stdin 收 JSON：{"message": "...", "project_path": "..."}
  • stdout 每行一个 AgentEvent（JSON-lines）：{"type":"message|edit|test|status|error", "pane":"...", "text":"...", "payload":{...}}

pane:"code" 的事件会触发平台计算 diff 并展示，pane:"test" 建议携带测试命令与结果。

4. 运行中止与幂等——工程上最容易踩坑的地方

Agent 是长时运行的子进程，"中止"不能是页面上的假停。Janus 的 abort 是真的：asyncio cancel → 适配器 finally 里连进程树一起杀（Windows 下 taskkill /F /T）。被中止的消息可以重发。

幂等上，同一 (session_id, message) 运行中最多执行一次；SSE 断线重连会自动回放已落库的事件，不会重复调用 agent、不会重复改盘。这类细节在 demo 里看不出来，一上生产全是坑。

5. 子进程环境变量清洗——一个隐蔽的坑

这里分享一个排查了很久的问题：在宿主进程里启动 codebuddy CLI 时，宿主注入的会话环境变量（SERVER__PORT、CODEBUDDY_* 等）会让 CLI 误以为自己运行在宿主网关内，然后静默挂死（EADDRINUSE）。

适配器启动子进程前必须清洗环境变量。表现是"超时"，根因是环境污染——如果你们的工具链也有子进程调用 CLI 的场景，建议先 env 对照排查这一项。

6. 其他

  • 文件在线预览：xlsx/csv（SheetJS）、PDF、图片、docx（docx-preview）、HTML（sandbox iframe）、Markdown、代码高亮，纯文本可就地编辑；
  • 日级 token 配额：Agent 用量按自然日限额，用满当日不可用、次日自动重置；
  • 审计日志：管理员可查完整调用明细；
  • 文档版本历史：需求文档每次修改记录版本，支持行级对比与回退。

四、技术选型：刻意克制

层 选型 理由
后端 Python 3.11+ / FastAPI 生态熟，SSE 支持好
存储 stdlib sqlite3（零 ORM） 单文件数据库，整个平台拷走即用，没有额外服务依赖
前端 React 18 / Vite / TS / Antd 6 快速搭出可靠的复杂表单界面
部署 后端单进程托管 web/dist 一个命令起全部

一个刻意的取舍：单进程单 worker 部署。运行去重和断线回放的状态放在进程内存里，换来的是零外部依赖——不需要 Redis，不需要消息队列。README 里明确写了：如需水平扩展，需把运行态外置。对一个本地部署的团队工具来说，"部署简单"比"天生可扩展"重要得多。

五、快速开始

git clone https://github.com/yonyong/Janus.git
cd Janus/coding-agent-platform

# 首次：装依赖
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
cd web && npm install && cd ..

# 生产模式：构建前端 + 启动后端
manage.bat build      # 访问 http://localhost:8000

# 配置管理员口令
echo CAP_ADMIN_TOKEN=your-admin-secret > .env

Linux / macOS：npm run build 后 python start.py 即可。

内置 fake 引擎不依赖任何真实模型，clone 下来 5 分钟就能把四阶段工作流完整跑一遍，感受一下交互形态。

六、架构图

平台提供了完整的架构图（中英双语 SVG）：

  • 业务架构：两类角色与平台能力边界
  • 技术架构：从浏览器到磁盘的完整链路
  • 需求流程：一次需求从澄清到归档的生命周期

（可在 GitHub 仓库 docs/images/ 目录查看，此处不赘贴。）

七、写在最后

这个项目的定位很明确：它不是又一个 AI 编程 CLI，而是面向非开发者的需求交付通道。它假设"改代码的是 agent，管代码的是平台，提需求的是业务"——三者各司其职。

目前它已经在我自己的日常工作中跑起来了，四阶段工作流、快照回退、令牌分享、配额审计都是实打实用过的功能，不是 PPT 特性。

如果你也苦于"业务需求太小不值得排期、但不改又不行"的内耗，或者对"如何安全地把 coding agent 开放给非技术人员"这个话题感兴趣，欢迎：

  • GitHub：https://github.com/yonyong/Janus （觉得有用请点个 Star ⭐）
  • 有想法或踩到坑，直接提 Issue，我都会回复
  • 适配器协议是开放的，欢迎 PR 接入 Cursor / Claude Code 等其他 CLI agent

标签建议（发布时勾选）：开源项目、Python、FastAPI、React、AI编程、Coding Agent

本文首发于博客园，转载请注明出处。

posted on 2026-09-21 21:31  yonyong  阅读(2)  评论(0)    收藏  举报