Kageos 是什么
Kageos 不是生成一个页面就结束的工具。它是业务能力的运行层和治理层。能力挂在 Service Tree 的目录上，有稳定路径、类型化函数、可用页面、运行状态和审计记录。
一个目录可以从 Hub 安装到私有 namespace，用自己的数据和流程改造，稳定后再打包发布。它可以服务一个人，也可以服务团队和企业部门，因为边界在目录上，不在某次对话里。
- 个人可以把重复工作沉淀成可复用工具，而不是每周重新写 prompt。
- 团队可以把记录、任务、表单、提醒和执行结果放回同一个工作面。
- 企业可以让 AI 在权限、日志、运行时隔离和交接规则里执行真实动作。
为什么是目录
AI 让做出一个“像软件的东西”变便宜了。生产环境问的是另一件事：这个东西有没有地址，有没有调用契约，有没有权限和日志，出了问题能不能追，换个人能不能接手。
一次 prompt 很难给出这些东西。目录可以。Kageos 里的目录，是能力从临时产物变成长期资产的位置。
- 地址：每个能力都有
full_code_path，例如/sales/crm/customer.table。 - 契约：Form、Table、Chart 和 callback 通过 SDK 暴露类型化 schema。
- 状态：代码、元数据、文件、日志和运行记录跟着工作区走。
- 治理：权限、操作日志、trace、来源路径和消息使用同一套坐标。
- 自动化：
app.function和agent.session任务由平台定时器触发。 - 分发：稳定目录可以打包、内置、安装，也可以发布回 Hub。
目录里到底有什么
Kageos 把目录当成打包好的工作流，不是链接文件夹。平台给目录路径，渲染页面，调用函数，启动容器，调度任务，并保存每次执行留下的记录。
- Service Tree：目录、函数、文档、消息、任务和日志的共同坐标。
- 人用页面：Form、Table、Chart、Docs 像正常软件一样打开使用。
- AI 调用面：工作台通过 schema 调用注册函数，不靠自然语言猜参数。
- 运行时：
app-server、app-runtime和kageos-sdk/agent-app构建并运行用户应用版本。 - 站内信：通知和执行结果进入
message-server，带来源路径和执行 ID。 - 调度器：
timer-scheduler保存下次执行时间、租约、执行记录、心跳和恢复状态。
工作怎么发生
目录有三种常见用法。人打开页面处理业务。AI 读取目录上下文并调用工具。定时任务在人不在线的时候执行，再把结果写回消息、日志和业务记录。
第三种很关键。无人值守不是藏起来的 cron。调度状态归调度器，执行器只负责执行。每次执行都有身份、来源、trace 和团队能回看的结果。
- 人工路径：打开目录，提交表单，查表，看文档，读图表，处理通知。
- AI 路径：启动工作台会话，读取上下文，改代码，构建，调用函数，检查结果，交接下一步。
- 函数定时路径：固定时间执行一个明确的 Form/Table/Chart action 和固定 payload。
- Agent 定时路径：启动无人值守工作台会话，用于监控、报告、巡检和跨目录处理。
现在已经有的能力
公开文档要和真实产品对齐。下面这些是主线已经接上的能力，不是未来包装词。
- Service Tree、工作区资源、访问控制、操作日志和带来源的 trace。
- Vue 前端渲染 Form、Table、Chart、Docs、Function，后端用 Go SDK schema 支撑。
- AI 工作台会话，支持历史消息、工具调用、改代码、修构建、运行时检查和阶段交接。
- 运行工具包括表单提交、表格查询和写入、图表查询、Python 执行、通知和定时任务管理。
timer-scheduler支持app.function函数任务和agent.sessionAgent 任务。message-server支持站内信、线程、未读、来源统计、工作区统计，以及 SDK 或 Agent 发通知。- 能力包 import/export，可在 namespace 之间移动目录，也能内置种子目录。
- Go、Vue 3、MySQL、NATS、MinIO、Podman 或 Docker 组成的可自托管运行时。
本地怎么跑起来
贡献者本地开发从 kagectl 开始。仓库里还保留 Compose 文件，但它们是底层实现和排障入口。新贡献者不应该为了跑起来先记一堆历史目录。
正常本地启动不需要手动 export 环境变量。kagectl bootstrap --dev 会生成本地 .kageos/ 环境文件，里面有 MySQL、NATS、MinIO、JWT、SMTP log 模式和 system 用户密码。这些文件不要提交。
- 前置条件：Go 1.25+，Node.js 20.19 或 22.12+，Podman Compose 或 Docker Compose。
- 拉代码后，在仓库根目录执行
go run ./cmd/kagectl bootstrap --dev。 - 另开终端启动前端：
cd web && npm install && npm run dev。 - 打开
http://localhost:5173，用户名system，密码用终端里Kageos dev initialization summary打印的Admin password。 - 如果密码被刷掉，重新执行
go run ./cmd/kagectl init --dev，或从.kageos/dev/env/kageos.env读取SYSTEM_USER_PASSWORD。 - 本地邮件验证码走 log 模式。注册新账号时，验证码在后端日志里，也会作为开发用
debug_code返回。
贡献代码时先守住边界
这个仓库里有两类代码：Kageos 平台本身，以及 namespace 里的工作区应用。边界要干净。平台服务可以用内部包，工作区应用应该用公开 SDK，不要直接依赖主仓内部实现。
core/app-server负责工作区 API、Service Tree、权限、操作日志、函数元数据和应用调用。core/agent-server负责工作台会话、工具、prompt、LLM 编排和 Agent 定时任务 worker。core/app-runtime负责写 namespace 文件、构建 Go 应用、管理版本和用户应用容器。core/timer-scheduler负责定时任务、执行记录、租约、心跳、恢复和 outbox 投递。core/message-server负责站内信、线程、未读状态和通知命令。web是 Vue 3 前端。deploy放本地、生产、AIO、镜像和安全部署材料。- PR 要聚焦。不要把行为修改、格式化、依赖升级和无关重构混在一起。
改完怎么验证
根据改动范围跑检查。完整说明在仓库里，但贡献者至少要知道这些入口。
- 后端：
bash scripts/test-core-go.sh。 - 前端：
cd web && npm run check:architecture && npm run lint && npm run type-check && npm run test:unit -- --run && npm run build。 - 仓库治理：
bash scripts/check-sensitive-files.sh、bash scripts/check-sdk-boundaries.sh、bash scripts/check-doc-links.sh和git diff --check。 - 本地启动排障：
go run ./cmd/kagectl doctor、status、verify、logs main、logs infra。
自托管和运维
Kageos 源码可见，也按自托管设计。当前生产路径是单机部署：Kageos 平台、MySQL、NATS、MinIO 和用户应用容器由平台运行时统一管理。
运维时先记住一件事：平台状态、应用源码、运行时元数据、日志和对象存储不是临时构建产物。做破坏性重置前要备份。密钥不要进仓库。本地和生产的 .kageos/ 都是私有运行状态。
- 本地开发用
go run ./cmd/kagectl bootstrap --dev。 - 生产部署看自托管指南和生产安装脚本，不要把本地 dev 命令照搬到服务器。
- 先用
kagectl doctor、status、verify和日志排查，再碰底层 Compose 命令。 - 停止本地基础设施用
go run ./cmd/kagectl down，默认保留本地数据。
当前边界
好的文档要讲清楚哪些是真的，哪些还在路上。Kageos 不应该把没上线的控制面说成已经可用。
- 主线已有：Service Tree、权限和操作日志、AI 工作台、Form/Table/Chart/Docs、站内信、函数任务、Agent 任务、应用运行时和能力包。
- 建设中：公开 Hub 市场、托管试用、发布闭环、企业私有 Hub 和 SaaS 运维能力。
- 预留但未上线：workflow 图、
workflow.run、通用审批、讨论、评分、外部通知 channel provider 和备份控制面。