在 GitHub 上编辑 docs/zh/modules.md ↗
代码地图
分析基线:main@95231e8。src/ 约 22,000 行 TypeScript(不含 public-board/dashboard 与 static/ 前端资源)。下面按目录给职责,并列出最值得先读的文件。
src/ 控制面
| 目录 |
职责 |
先读 |
core/ |
通用安全原语:随机 ID、SHA-256、密码哈希、HMAC 验签、SecretBox |
security.ts |
storage/ |
SQLite 打开、PRAGMA、增量迁移、事务、审计 |
database.ts |
main.ts / server.ts |
装配和唯一 HTTP 入口;路径分派、认证、CSP、静态资源 |
main.ts, server.ts |
app/ |
账号/登录、安装同步、模型与项目列表、Webhook 归一化、管理 API |
installations.ts, webhook.ts, models.ts |
agent/ |
任务引擎、模型循环、工具网关、Git 镜像缓存、只读令牌、工作区、失败分类 |
engine.ts, loop.ts, gateway.ts, read-token.ts |
tasks/ |
任务、task run、候选、契约、记录、验收与发布前置 |
records.ts, contract.ts, candidate.ts |
roles/ |
角色定义、RoleRun 协议、租约/令牌/事件/检查点、TaskToolGateway、调度 |
protocol.ts, role-run.ts, run.ts, gateway.ts |
harness/ |
执行器适配:Native、Process、ACP、Codex app-server、Claude Code |
session.ts, acp.ts, app-server.ts, claude-code.ts |
dispatch/ |
项目 Manager 的事件分派(create/continue/ignore) |
manager.ts, worker.ts, store.ts |
review/ |
检视触发、队列、位置校验、摘要单评论 |
queue.ts |
github/ |
GitHub 客户端、发布 outbox、限流、Release 标签、文本清理 |
client.ts, publisher.ts, rate-limits.ts |
automation/ |
纯函数模块:标签规范、门禁、合并队列;仓库 YAML 配置 |
engine.ts, registry.ts, config.ts, modules/* |
projects/ |
环境网关(manager 调用)、门禁接入向导、集成检查 |
service.ts, gate-onboarding.ts, gate-plan.ts |
identity/ |
GitHub 登录、派生授权、外部身份绑定、权限核验 |
authorization.ts, github-login.ts, github-permissions.ts |
installations/ |
安装档案、投影与同步 |
archive.ts, projection.ts |
external/ |
外部执行端:签名、转发、身份、目标、事件 |
broker.ts, forward.ts, identity.ts |
releases/ |
发版:标签、Release 工作流跟踪、发行说明、状态 |
service.ts, worker.ts |
actions/ |
Actions 失败扫描、分类、一次重跑与提报 |
service.ts, classifier.ts, safety.ts |
board/ |
工作看板 API 与存储 |
api.ts, storage.ts |
channels/ |
飞书等消息渠道、绑定、连接、发送队列 |
service.ts, feishu.ts, binding.ts |
schedules/ |
定时计划与服务 |
service.ts, worker.ts |
memory/ |
项目记忆、作用域、检索 |
store.ts 等 |
metrics/ |
任务耗时、token、费用 |
*.ts |
public-board/ |
公共看板(单仓库) |
service.ts |
onboarding/ |
七步接入向导、公网 URL、Tunnel 检查 |
service.ts, public-url.ts |
work/ |
工作类型、设置、迁移与事件 |
settings.ts, migration.ts |
management/ |
管理对话/管理服务 |
service.ts |
rules/ |
内置规则文本与版本 |
*.ts |
manager/ 执行网关(约 1,500 行 JavaScript)
| 文件 |
职责 |
main.mjs |
读取 manager 令牌、计算 deployment id、启动 HTTP |
server.mjs |
/ready 探针、Bearer 鉴权、项目/文件/笔记/统计/运行环境 API |
docker.mjs |
对 Docker Engine 的薄封装、受控错误 |
projects.mjs |
每仓库容器的建/停/重置/执行、代次、卷、派生镜像、恢复 |
run-environments.mjs |
每次 RoleRun 的独立容器与网络 |
manager 是唯一持有 /var/run/docker.sock 的组件;这是整个系统最大的权限面,见安全模型。
runner/ 项目电脑内入口(约 1,100 行)
| 文件 |
职责 |
runner.mjs |
无网络监听的固定入口;校验请求、执行、写 journal |
workspace.mjs |
工作区相对路径、读写、命令、Git 候选 |
store.mjs |
journal 与输出文件 |
pi-entry.mjs |
Pi SDK 入口 |
repository-context.mjs / repository-tool.mjs |
受控仓库读取 |
token-exchange.mjs |
向控制面兑换只读令牌 |
其他
| 路径 |
内容 |
static/ |
控制台前端资源(原生 JS/CSS,无框架) |
public-board/dashboard/ |
公共看板的 dashboard workspace |
config/repositories/ |
仓库级 YAML:标签、门禁、合并队列、CI lane |
webhook/ |
tunnel 与控制面之间的固定网关进程 |
images/project/ |
项目电脑镜像的构建上下文 |
scripts/ |
测试集运行器、API 文档生成、协议锁定、检查脚本 |
test/ |
node:test 测试、夹具、假 GitHub/假模型 |
e2e/ |
Playwright 浏览器验收 |
读代码的建议顺序
src/main.ts → src/server.ts:先看资源装配和唯一入口。
src/storage/database.ts:看表与迁移,理解“先落库”。
src/app/webhook.ts → src/dispatch/*:事件如何变成任务。
src/agent/engine.ts → src/tasks/* → src/github/publisher.ts:任务如何变成 PR。
src/roles/*:需要理解 RoleRun、租约与隔离时再读。
src/identity/* 与 src/core/security.ts:评估信任边界时读。